diff options
Diffstat (limited to 'Documentation')
729 files changed, 19250 insertions, 12213 deletions
diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio index 40d41ea1a3f5..e0d4e5e2dd90 100644 --- a/Documentation/ABI/obsolete/sysfs-gpio +++ b/Documentation/ABI/obsolete/sysfs-gpio @@ -11,7 +11,7 @@ Description: Kernel code may export it for complete or partial access. GPIOs are identified as they are inside the kernel, using integers in - the range 0..INT_MAX. See Documentation/gpio for more information. + the range 0..INT_MAX. See Documentation/admin-guide/gpio for more information. /sys/class/gpio /export ... asks the kernel to export a GPIO to userspace diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill index 3ce6231f20b2..9c08c7f98ffb 100644 --- a/Documentation/ABI/removed/sysfs-class-rfkill +++ b/Documentation/ABI/removed/sysfs-class-rfkill @@ -1,6 +1,6 @@ rfkill - radio frequency (RF) connector kill switch support -For details to this subsystem look at Documentation/rfkill.txt. +For details to this subsystem look at Documentation/driver-api/rfkill.rst. What: /sys/class/rfkill/rfkill[0-9]+/claim Date: 09-Jul-2007 diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband index 17211ceb9bf4..aed21b8916a2 100644 --- a/Documentation/ABI/stable/sysfs-class-infiniband +++ b/Documentation/ABI/stable/sysfs-class-infiniband @@ -423,23 +423,6 @@ Description: (e.g. driver restart on the VM which owns the VF). -sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes) ---------------------------------------------------------------- - -What: /sys/class/infiniband/nesX/hw_rev -What: /sys/class/infiniband/nesX/hca_type -What: /sys/class/infiniband/nesX/board_id -Date: Feb, 2008 -KernelVersion: v2.6.25 -Contact: linux-rdma@vger.kernel.org -Description: - hw_rev: (RO) Hardware revision number - - hca_type: (RO) Host Channel Adapter type (NEX020) - - board_id: (RO) Manufacturing board id - - sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4) ----------------------------------------------------- diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill index 80151a409d67..5b154f922643 100644 --- a/Documentation/ABI/stable/sysfs-class-rfkill +++ b/Documentation/ABI/stable/sysfs-class-rfkill @@ -1,6 +1,6 @@ rfkill - radio frequency (RF) connector kill switch support -For details to this subsystem look at Documentation/rfkill.txt. +For details to this subsystem look at Documentation/driver-api/rfkill.rst. For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in Documentation/ABI/removed/sysfs-class-rfkill. diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node index f7ce68fbd4b9..df8413cf1468 100644 --- a/Documentation/ABI/stable/sysfs-devices-node +++ b/Documentation/ABI/stable/sysfs-devices-node @@ -61,7 +61,7 @@ Date: October 2002 Contact: Linux Memory Management list <linux-mm@kvack.org> Description: The node's hit/miss statistics, in units of pages. - See Documentation/numastat.txt + See Documentation/admin-guide/numastat.rst What: /sys/devices/system/node/nodeX/distance Date: October 2002 diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io index 3544968f43cc..8ca498447aeb 100644 --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io @@ -120,3 +120,23 @@ Description: These files show the system reset cause, as following: ComEx the last reset cause. The files are read only. + +Date: June 2019 +KernelVersion: 5.3 +Contact: Vadim Pasternak <vadimpmellanox.com> +Description: These files show the system reset cause, as following: + COMEX thermal shutdown; wathchdog power off or reset was derived + by one of the next components: COMEX, switch board or by Small Form + Factor mezzanine, reset requested from ASIC, reset cuased by BIOS + reload. Value 1 in file means this is reset cause, 0 - otherwise. + Only one of the above causes could be 1 at the same time, representing + only last reset cause. + + The files are read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_thermal +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_comex_wd +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_from_asic +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_reload_bios +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_sff_wd +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/reset_swb_wd diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats index abac31d216de..2c44b4f1b060 100644 --- a/Documentation/ABI/testing/procfs-diskstats +++ b/Documentation/ABI/testing/procfs-diskstats @@ -29,4 +29,4 @@ Description: 17 - sectors discarded 18 - time spent discarding - For more details refer to Documentation/iostats.txt + For more details refer to Documentation/admin-guide/iostats.rst diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index dfad7427817c..f8c7c7126bb1 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -15,7 +15,7 @@ Description: 9 - I/Os currently in progress 10 - time spent doing I/Os (ms) 11 - weighted time spent doing I/Os (ms) - For more details refer Documentation/iostats.txt + For more details refer Documentation/admin-guide/iostats.rst What: /sys/block/<disk>/<part>/stat diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device index 82ef6eab042d..17f2bc7dd261 100644 --- a/Documentation/ABI/testing/sysfs-block-device +++ b/Documentation/ABI/testing/sysfs-block-device @@ -45,7 +45,7 @@ Description: - Values below -2 are rejected with -EINVAL For more information, see - Documentation/laptops/disk-shock-protection.txt + Documentation/admin-guide/laptops/disk-shock-protection.rst What: /sys/block/*/device/ncq_prio_enable diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index b77e30b9014e..27edc06e2495 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -376,10 +376,42 @@ Description: supply. Normally this is configured based on the type of connection made (e.g. A configured SDP should output a maximum of 500mA so the input current limit is set to the same value). + Use preferably input_power_limit, and for problems that can be + solved using power limit use input_current_limit. Access: Read, Write Valid values: Represented in microamps +What: /sys/class/power_supply/<supply_name>/input_voltage_limit +Date: May 2019 +Contact: linux-pm@vger.kernel.org +Description: + This entry configures the incoming VBUS voltage limit currently + set in the supply. Normally this is configured based on + system-level knowledge or user input (e.g. This is part of the + Pixel C's thermal management strategy to effectively limit the + input power to 5V when the screen is on to meet Google's skin + temperature targets). Note that this feature should not be + used for safety critical things. + Use preferably input_power_limit, and for problems that can be + solved using power limit use input_voltage_limit. + + Access: Read, Write + Valid values: Represented in microvolts + +What: /sys/class/power_supply/<supply_name>/input_power_limit +Date: May 2019 +Contact: linux-pm@vger.kernel.org +Description: + This entry configures the incoming power limit currently set + in the supply. Normally this is configured based on + system-level knowledge or user input. Use preferably this + feature to limit the incoming power and use current/voltage + limit only for problems that can be solved using power limit. + + Access: Read, Write + Valid values: Represented in microwatts + What: /sys/class/power_supply/<supply_name>/online, Date: May 2007 Contact: linux-pm@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco new file mode 100644 index 000000000000..da1d6ffe5e3c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-power-wilco @@ -0,0 +1,30 @@ +What: /sys/class/power_supply/wilco-charger/charge_type +Date: April 2019 +KernelVersion: 5.2 +Description: + What charging algorithm to use: + + Standard: Fully charges battery at a standard rate. + Adaptive: Battery settings adaptively optimized based on + typical battery usage pattern. + Fast: Battery charges over a shorter period. + Trickle: Extends battery lifespan, intended for users who + primarily use their Chromebook while connected to AC. + Custom: A low and high threshold percentage is specified. + Charging begins when level drops below + charge_control_start_threshold, and ceases when + level is above charge_control_end_threshold. + +What: /sys/class/power_supply/wilco-charger/charge_control_start_threshold +Date: April 2019 +KernelVersion: 5.2 +Description: + Used when charge_type="Custom", as described above. Measured in + percentages. The valid range is [50, 95]. + +What: /sys/class/power_supply/wilco-charger/charge_control_end_threshold +Date: April 2019 +KernelVersion: 5.2 +Description: + Used when charge_type="Custom", as described above. Measured in + percentages. The valid range is [55, 100]. diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap index f333a0ccc29b..ca491ec4e693 100644 --- a/Documentation/ABI/testing/sysfs-class-powercap +++ b/Documentation/ABI/testing/sysfs-class-powercap @@ -5,7 +5,7 @@ Contact: linux-pm@vger.kernel.org Description: The powercap/ class sub directory belongs to the power cap subsystem. Refer to - Documentation/power/powercap/powercap.txt for details. + Documentation/power/powercap/powercap.rst for details. What: /sys/class/powercap/<control type> Date: September 2013 diff --git a/Documentation/ABI/testing/sysfs-class-switchtec b/Documentation/ABI/testing/sysfs-class-switchtec index 48cb4c15e430..76c7a661a595 100644 --- a/Documentation/ABI/testing/sysfs-class-switchtec +++ b/Documentation/ABI/testing/sysfs-class-switchtec @@ -1,6 +1,6 @@ switchtec - Microsemi Switchtec PCI Switch Management Endpoint -For details on this subsystem look at Documentation/switchtec.txt. +For details on this subsystem look at Documentation/driver-api/switchtec.rst. What: /sys/class/switchtec Date: 05-Jan-2017 diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index d404603c6b52..5f7d7b14fa44 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -34,7 +34,7 @@ Description: CPU topology files that describe kernel limits related to present: cpus that have been identified as being present in the system. - See Documentation/cputopology.txt for more information. + See Documentation/admin-guide/cputopology.rst for more information. What: /sys/devices/system/cpu/probe @@ -103,7 +103,7 @@ Description: CPU topology files that describe a logical CPU's relationship thread_siblings_list: human-readable list of cpu#'s hardware threads within the same core as cpu# - See Documentation/cputopology.txt for more information. + See Documentation/admin-guide/cputopology.rst for more information. What: /sys/devices/system/cpu/cpuidle/current_driver diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop index cd9d667c3da2..8b0e8205a6a2 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-laptop +++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop @@ -31,7 +31,7 @@ Description: To control the LED display, use the following : echo 0x0T000DDD > /sys/devices/platform/asus_laptop/ where T control the 3 letters display, and DDD the 3 digits display. - The DDD table can be found in Documentation/laptops/asus-laptop.txt + The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst What: /sys/devices/platform/asus_laptop/bluetooth Date: January 2007 diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi index 019e1e29370e..9e99f2909612 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-wmi +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi @@ -36,3 +36,13 @@ KernelVersion: 3.5 Contact: "AceLan Kao" <acelan.kao@canonical.com> Description: Resume on lid open. 1 means on, 0 means off. + +What: /sys/devices/platform/<platform>/fan_boost_mode +Date: Sep 2019 +KernelVersion: 5.3 +Contact: "Yurii Pavlovskyi" <yurii.pavlovskyi@gmail.com> +Description: + Fan boost mode: + * 0 - normal, + * 1 - overboost, + * 2 - silent diff --git a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl index 3c3514815cd5..c394b808be19 100644 --- a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl +++ b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl @@ -1,7 +1,7 @@ What: /sys/devices/platform/<i2c-demux-name>/available_masters Date: January 2016 KernelVersion: 4.6 -Contact: Wolfram Sang <wsa@the-dreams.de> +Contact: Wolfram Sang <wsa+renesas@sang-engineering.com> Description: Reading the file will give you a list of masters which can be selected for a demultiplexed bus. The format is @@ -12,7 +12,7 @@ Description: What: /sys/devices/platform/<i2c-demux-name>/current_master Date: January 2016 KernelVersion: 4.6 -Contact: Wolfram Sang <wsa@the-dreams.de> +Contact: Wolfram Sang <wsa+renesas@sang-engineering.com> Description: This file selects/shows the active I2C master for a demultiplexed bus. It uses the <index> value from the file 'available_masters'. diff --git a/Documentation/logo.txt b/Documentation/COPYING-logo index 296f0f7f67eb..296f0f7f67eb 100644 --- a/Documentation/logo.txt +++ b/Documentation/COPYING-logo diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index cb712a02f59f..358d495456d1 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -212,7 +212,7 @@ The standard 64-bit addressing device would do something like this:: If the device only supports 32-bit addressing for descriptors in the coherent allocations, but supports full 64-bits for streaming mappings -it would look like this: +it would look like this:: if (dma_set_mask(dev, DMA_BIT_MASK(64))) { dev_warn(dev, "mydev: No suitable DMA available\n"); diff --git a/Documentation/PCI/acpi-info.txt b/Documentation/PCI/acpi-info.rst index 3ffa3b03970e..060217081c79 100644 --- a/Documentation/PCI/acpi-info.txt +++ b/Documentation/PCI/acpi-info.rst @@ -1,4 +1,8 @@ - ACPI considerations for PCI host bridges +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +ACPI considerations for PCI host bridges +======================================== The general rule is that the ACPI namespace should describe everything the OS might use unless there's another way for the OS to find it [1, 2]. @@ -131,12 +135,13 @@ address always corresponds to bus 0, even if the bus range below the bridge [4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4: QWord/DWord/Word Address Space Descriptor (.1, .2, .3) - General Flags: Bit [0] Ignored + General Flags: Bit [0] Ignored Extended Address Space Descriptor (.4) - General Flags: Bit [0] Consumer/Producer: - 1–This device consumes this resource - 0–This device produces and consumes this resource + General Flags: Bit [0] Consumer/Producer: + + * 1 – This device consumes this resource + * 0 – This device produces and consumes this resource [5] ACPI 6.2, sec 19.6.43: ResourceUsage specifies whether the Memory range is consumed by diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst new file mode 100644 index 000000000000..d114ea74b444 --- /dev/null +++ b/Documentation/PCI/endpoint/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +PCI Endpoint Framework +====================== + +.. toctree:: + :maxdepth: 2 + + pci-endpoint + pci-endpoint-cfs + pci-test-function + pci-test-howto diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst index d740f29960a4..b6d39cdec56e 100644 --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst @@ -1,41 +1,51 @@ - CONFIGURING PCI ENDPOINT USING CONFIGFS - Kishon Vijay Abraham I <kishon@ti.com> +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Configuring PCI Endpoint Using CONFIGFS +======================================= + +:Author: Kishon Vijay Abraham I <kishon@ti.com> The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the PCI endpoint function and to bind the endpoint function with the endpoint controller. (For introducing other mechanisms to configure the PCI Endpoint Function refer to [1]). -*) Mounting configfs +Mounting configfs +================= The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs -directory. configfs can be mounted using the following command. +directory. configfs can be mounted using the following command:: mount -t configfs none /sys/kernel/config -*) Directory Structure +Directory Structure +=================== The pci_ep configfs has two directories at its root: controllers and functions. Every EPC device present in the system will have an entry in the *controllers* directory and and every EPF driver present in the system will have an entry in the *functions* directory. +:: -/sys/kernel/config/pci_ep/ - .. controllers/ - .. functions/ + /sys/kernel/config/pci_ep/ + .. controllers/ + .. functions/ -*) Creating EPF Device +Creating EPF Device +=================== Every registered EPF driver will be listed in controllers directory. The entries corresponding to EPF driver will be created by the EPF core. +:: -/sys/kernel/config/pci_ep/functions/ - .. <EPF Driver1>/ - ... <EPF Device 11>/ - ... <EPF Device 21>/ - .. <EPF Driver2>/ - ... <EPF Device 12>/ - ... <EPF Device 22>/ + /sys/kernel/config/pci_ep/functions/ + .. <EPF Driver1>/ + ... <EPF Device 11>/ + ... <EPF Device 21>/ + .. <EPF Driver2>/ + ... <EPF Device 12>/ + ... <EPF Device 22>/ In order to create a <EPF device> of the type probed by <EPF Driver>, the user has to create a directory inside <EPF DriverN>. @@ -44,34 +54,37 @@ Every <EPF device> directory consists of the following entries that can be used to configure the standard configuration header of the endpoint function. (These entries are created by the framework when any new <EPF Device> is created) - - .. <EPF Driver1>/ - ... <EPF Device 11>/ - ... vendorid - ... deviceid - ... revid - ... progif_code - ... subclass_code - ... baseclass_code - ... cache_line_size - ... subsys_vendor_id - ... subsys_id - ... interrupt_pin - -*) EPC Device +:: + + .. <EPF Driver1>/ + ... <EPF Device 11>/ + ... vendorid + ... deviceid + ... revid + ... progif_code + ... subclass_code + ... baseclass_code + ... cache_line_size + ... subsys_vendor_id + ... subsys_id + ... interrupt_pin + +EPC Device +========== Every registered EPC device will be listed in controllers directory. The entries corresponding to EPC device will be created by the EPC core. - -/sys/kernel/config/pci_ep/controllers/ - .. <EPC Device1>/ - ... <Symlink EPF Device11>/ - ... <Symlink EPF Device12>/ - ... start - .. <EPC Device2>/ - ... <Symlink EPF Device21>/ - ... <Symlink EPF Device22>/ - ... start +:: + + /sys/kernel/config/pci_ep/controllers/ + .. <EPC Device1>/ + ... <Symlink EPF Device11>/ + ... <Symlink EPF Device12>/ + ... start + .. <EPC Device2>/ + ... <Symlink EPF Device21>/ + ... <Symlink EPF Device22>/ + ... start The <EPC Device> directory will have a list of symbolic links to <EPF Device>. These symbolic links should be created by the user to @@ -81,7 +94,7 @@ The <EPC Device> directory will also have a *start* field. Once "1" is written to this field, the endpoint device will be ready to establish the link with the host. This is usually done after all the EPF devices are created and linked with the EPC device. - +:: | controllers/ | <Directory: EPC name>/ @@ -102,4 +115,4 @@ all the EPF devices are created and linked with the EPC device. | interrupt_pin | function -[1] -> Documentation/PCI/endpoint/pci-endpoint.txt +[1] :doc:`pci-endpoint` diff --git a/Documentation/PCI/endpoint/pci-endpoint.txt b/Documentation/PCI/endpoint/pci-endpoint.rst index e86a96b66a6a..0e2311b5617b 100644 --- a/Documentation/PCI/endpoint/pci-endpoint.txt +++ b/Documentation/PCI/endpoint/pci-endpoint.rst @@ -1,11 +1,13 @@ - PCI ENDPOINT FRAMEWORK - Kishon Vijay Abraham I <kishon@ti.com> +.. SPDX-License-Identifier: GPL-2.0 + +:Author: Kishon Vijay Abraham I <kishon@ti.com> This document is a guide to use the PCI Endpoint Framework in order to create endpoint controller driver, endpoint function driver, and using configfs interface to bind the function driver to the controller driver. -1. Introduction +Introduction +============ Linux has a comprehensive PCI subsystem to support PCI controllers that operates in Root Complex mode. The subsystem has capability to scan PCI bus, @@ -19,26 +21,30 @@ add endpoint mode support in Linux. This will help to run Linux in an EP system which can have a wide variety of use cases from testing or validation, co-processor accelerator, etc. -2. PCI Endpoint Core +PCI Endpoint Core +================= The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller library, the Endpoint Function library, and the configfs layer to bind the endpoint function with the endpoint controller. -2.1 PCI Endpoint Controller(EPC) Library +PCI Endpoint Controller(EPC) Library +------------------------------------ The EPC library provides APIs to be used by the controller that can operate in endpoint mode. It also provides APIs to be used by function driver/library in order to implement a particular endpoint function. -2.1.1 APIs for the PCI controller Driver +APIs for the PCI controller Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section lists the APIs that the PCI Endpoint core provides to be used by the PCI controller driver. -*) devm_pci_epc_create()/pci_epc_create() +* devm_pci_epc_create()/pci_epc_create() The PCI controller driver should implement the following ops: + * write_header: ops to populate configuration space header * set_bar: ops to configure the BAR * clear_bar: ops to reset the BAR @@ -51,110 +57,116 @@ by the PCI controller driver. The PCI controller driver can then create a new EPC device by invoking devm_pci_epc_create()/pci_epc_create(). -*) devm_pci_epc_destroy()/pci_epc_destroy() +* devm_pci_epc_destroy()/pci_epc_destroy() The PCI controller driver can destroy the EPC device created by either devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or pci_epc_destroy(). -*) pci_epc_linkup() +* pci_epc_linkup() In order to notify all the function devices that the EPC device to which they are linked has established a link with the host, the PCI controller driver should invoke pci_epc_linkup(). -*) pci_epc_mem_init() +* pci_epc_mem_init() Initialize the pci_epc_mem structure used for allocating EPC addr space. -*) pci_epc_mem_exit() +* pci_epc_mem_exit() Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init(). -2.1.2 APIs for the PCI Endpoint Function Driver + +APIs for the PCI Endpoint Function Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section lists the APIs that the PCI Endpoint core provides to be used by the PCI endpoint function driver. -*) pci_epc_write_header() +* pci_epc_write_header() The PCI endpoint function driver should use pci_epc_write_header() to write the standard configuration header to the endpoint controller. -*) pci_epc_set_bar() +* pci_epc_set_bar() The PCI endpoint function driver should use pci_epc_set_bar() to configure the Base Address Register in order for the host to assign PCI addr space. Register space of the function driver is usually configured using this API. -*) pci_epc_clear_bar() +* pci_epc_clear_bar() The PCI endpoint function driver should use pci_epc_clear_bar() to reset the BAR. -*) pci_epc_raise_irq() +* pci_epc_raise_irq() The PCI endpoint function driver should use pci_epc_raise_irq() to raise Legacy Interrupt, MSI or MSI-X Interrupt. -*) pci_epc_mem_alloc_addr() +* pci_epc_mem_alloc_addr() The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to allocate memory address from EPC addr space which is required to access RC's buffer -*) pci_epc_mem_free_addr() +* pci_epc_mem_free_addr() The PCI endpoint function driver should use pci_epc_mem_free_addr() to free the memory space allocated using pci_epc_mem_alloc_addr(). -2.1.3 Other APIs +Other APIs +~~~~~~~~~~ There are other APIs provided by the EPC library. These are used for binding the EPF device with EPC device. pci-ep-cfs.c can be used as reference for using these APIs. -*) pci_epc_get() +* pci_epc_get() Get a reference to the PCI endpoint controller based on the device name of the controller. -*) pci_epc_put() +* pci_epc_put() Release the reference to the PCI endpoint controller obtained using pci_epc_get() -*) pci_epc_add_epf() +* pci_epc_add_epf() Add a PCI endpoint function to a PCI endpoint controller. A PCIe device can have up to 8 functions according to the specification. -*) pci_epc_remove_epf() +* pci_epc_remove_epf() Remove the PCI endpoint function from PCI endpoint controller. -*) pci_epc_start() +* pci_epc_start() The PCI endpoint function driver should invoke pci_epc_start() once it has configured the endpoint function and wants to start the PCI link. -*) pci_epc_stop() +* pci_epc_stop() The PCI endpoint function driver should invoke pci_epc_stop() to stop the PCI LINK. -2.2 PCI Endpoint Function(EPF) Library + +PCI Endpoint Function(EPF) Library +---------------------------------- The EPF library provides APIs to be used by the function driver and the EPC library to provide endpoint mode functionality. -2.2.1 APIs for the PCI Endpoint Function Driver +APIs for the PCI Endpoint Function Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section lists the APIs that the PCI Endpoint core provides to be used by the PCI endpoint function driver. -*) pci_epf_register_driver() +* pci_epf_register_driver() The PCI Endpoint Function driver should implement the following ops: * bind: ops to perform when a EPC device has been bound to EPF device @@ -166,50 +178,54 @@ by the PCI endpoint function driver. The PCI Function driver can then register the PCI EPF driver by using pci_epf_register_driver(). -*) pci_epf_unregister_driver() +* pci_epf_unregister_driver() The PCI Function driver can unregister the PCI EPF driver by using pci_epf_unregister_driver(). -*) pci_epf_alloc_space() +* pci_epf_alloc_space() The PCI Function driver can allocate space for a particular BAR using pci_epf_alloc_space(). -*) pci_epf_free_space() +* pci_epf_free_space() The PCI Function driver can free the allocated space (using pci_epf_alloc_space) by invoking pci_epf_free_space(). -2.2.2 APIs for the PCI Endpoint Controller Library +APIs for the PCI Endpoint Controller Library +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + This section lists the APIs that the PCI Endpoint core provides to be used by the PCI endpoint controller library. -*) pci_epf_linkup() +* pci_epf_linkup() The PCI endpoint controller library invokes pci_epf_linkup() when the EPC device has established the connection to the host. -2.2.2 Other APIs +Other APIs +~~~~~~~~~~ + There are other APIs provided by the EPF library. These are used to notify the function driver when the EPF device is bound to the EPC device. pci-ep-cfs.c can be used as reference for using these APIs. -*) pci_epf_create() +* pci_epf_create() Create a new PCI EPF device by passing the name of the PCI EPF device. This name will be used to bind the the EPF device to a EPF driver. -*) pci_epf_destroy() +* pci_epf_destroy() Destroy the created PCI EPF device. -*) pci_epf_bind() +* pci_epf_bind() pci_epf_bind() should be invoked when the EPF device has been bound to a EPC device. -*) pci_epf_unbind() +* pci_epf_unbind() pci_epf_unbind() should be invoked when the binding between EPC device and EPF device is lost. diff --git a/Documentation/PCI/endpoint/pci-test-function.txt b/Documentation/PCI/endpoint/pci-test-function.rst index 5916f1f592bb..3c8521d7aa31 100644 --- a/Documentation/PCI/endpoint/pci-test-function.txt +++ b/Documentation/PCI/endpoint/pci-test-function.rst @@ -1,5 +1,10 @@ - PCI TEST - Kishon Vijay Abraham I <kishon@ti.com> +.. SPDX-License-Identifier: GPL-2.0 + +================= +PCI Test Function +================= + +:Author: Kishon Vijay Abraham I <kishon@ti.com> Traditionally PCI RC has always been validated by using standard PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards. @@ -23,65 +28,76 @@ The PCI endpoint test device has the following registers: 8) PCI_ENDPOINT_TEST_IRQ_TYPE 9) PCI_ENDPOINT_TEST_IRQ_NUMBER -*) PCI_ENDPOINT_TEST_MAGIC +* PCI_ENDPOINT_TEST_MAGIC This register will be used to test BAR0. A known pattern will be written and read back from MAGIC register to verify BAR0. -*) PCI_ENDPOINT_TEST_COMMAND: +* PCI_ENDPOINT_TEST_COMMAND This register will be used by the host driver to indicate the function that the endpoint device must perform. -Bitfield Description: - Bit 0 : raise legacy IRQ - Bit 1 : raise MSI IRQ - Bit 2 : raise MSI-X IRQ - Bit 3 : read command (read data from RC buffer) - Bit 4 : write command (write data to RC buffer) - Bit 5 : copy command (copy data from one RC buffer to another - RC buffer) +======== ================================================================ +Bitfield Description +======== ================================================================ +Bit 0 raise legacy IRQ +Bit 1 raise MSI IRQ +Bit 2 raise MSI-X IRQ +Bit 3 read command (read data from RC buffer) +Bit 4 write command (write data to RC buffer) +Bit 5 copy command (copy data from one RC buffer to another RC buffer) +======== ================================================================ -*) PCI_ENDPOINT_TEST_STATUS +* PCI_ENDPOINT_TEST_STATUS This register reflects the status of the PCI endpoint device. -Bitfield Description: - Bit 0 : read success - Bit 1 : read fail - Bit 2 : write success - Bit 3 : write fail - Bit 4 : copy success - Bit 5 : copy fail - Bit 6 : IRQ raised - Bit 7 : source address is invalid - Bit 8 : destination address is invalid - -*) PCI_ENDPOINT_TEST_SRC_ADDR +======== ============================== +Bitfield Description +======== ============================== +Bit 0 read success +Bit 1 read fail +Bit 2 write success +Bit 3 write fail +Bit 4 copy success +Bit 5 copy fail +Bit 6 IRQ raised +Bit 7 source address is invalid +Bit 8 destination address is invalid +======== ============================== + +* PCI_ENDPOINT_TEST_SRC_ADDR This register contains the source address (RC buffer address) for the COPY/READ command. -*) PCI_ENDPOINT_TEST_DST_ADDR +* PCI_ENDPOINT_TEST_DST_ADDR This register contains the destination address (RC buffer address) for the COPY/WRITE command. -*) PCI_ENDPOINT_TEST_IRQ_TYPE +* PCI_ENDPOINT_TEST_IRQ_TYPE This register contains the interrupt type (Legacy/MSI) triggered for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands. Possible types: - - Legacy : 0 - - MSI : 1 - - MSI-X : 2 -*) PCI_ENDPOINT_TEST_IRQ_NUMBER +====== == +Legacy 0 +MSI 1 +MSI-X 2 +====== == + +* PCI_ENDPOINT_TEST_IRQ_NUMBER This register contains the triggered ID interrupt. Admissible values: - - Legacy : 0 - - MSI : [1 .. 32] - - MSI-X : [1 .. 2048] + +====== =========== +Legacy 0 +MSI [1 .. 32] +MSI-X [1 .. 2048] +====== =========== diff --git a/Documentation/PCI/endpoint/pci-test-howto.txt b/Documentation/PCI/endpoint/pci-test-howto.rst index 040479f437a5..909f770a07d6 100644 --- a/Documentation/PCI/endpoint/pci-test-howto.txt +++ b/Documentation/PCI/endpoint/pci-test-howto.rst @@ -1,38 +1,51 @@ - PCI TEST USERGUIDE - Kishon Vijay Abraham I <kishon@ti.com> +.. SPDX-License-Identifier: GPL-2.0 + +=================== +PCI Test User Guide +=================== + +:Author: Kishon Vijay Abraham I <kishon@ti.com> This document is a guide to help users use pci-epf-test function driver and pci_endpoint_test host driver for testing PCI. The list of steps to be followed in the host side and EP side is given below. -1. Endpoint Device +Endpoint Device +=============== -1.1 Endpoint Controller Devices +Endpoint Controller Devices +--------------------------- -To find the list of endpoint controller devices in the system: +To find the list of endpoint controller devices in the system:: # ls /sys/class/pci_epc/ 51000000.pcie_ep -If PCI_ENDPOINT_CONFIGFS is enabled +If PCI_ENDPOINT_CONFIGFS is enabled:: + # ls /sys/kernel/config/pci_ep/controllers 51000000.pcie_ep -1.2 Endpoint Function Drivers -To find the list of endpoint function drivers in the system: +Endpoint Function Drivers +------------------------- + +To find the list of endpoint function drivers in the system:: # ls /sys/bus/pci-epf/drivers pci_epf_test -If PCI_ENDPOINT_CONFIGFS is enabled +If PCI_ENDPOINT_CONFIGFS is enabled:: + # ls /sys/kernel/config/pci_ep/functions pci_epf_test -1.3 Creating pci-epf-test Device + +Creating pci-epf-test Device +---------------------------- PCI endpoint function device can be created using the configfs. To create -pci-epf-test device, the following commands can be used +pci-epf-test device, the following commands can be used:: # mount -t configfs none /sys/kernel/config # cd /sys/kernel/config/pci_ep/ @@ -42,7 +55,7 @@ The "mkdir func1" above creates the pci-epf-test function device that will be probed by pci_epf_test driver. The PCI endpoint framework populates the directory with the following -configurable fields. +configurable fields:: # ls functions/pci_epf_test/func1 baseclass_code interrupt_pin progif_code subsys_id @@ -51,67 +64,83 @@ configurable fields. The PCI endpoint function driver populates these entries with default values when the device is bound to the driver. The pci-epf-test driver populates -vendorid with 0xffff and interrupt_pin with 0x0001 +vendorid with 0xffff and interrupt_pin with 0x0001:: # cat functions/pci_epf_test/func1/vendorid 0xffff # cat functions/pci_epf_test/func1/interrupt_pin 0x0001 -1.4 Configuring pci-epf-test Device + +Configuring pci-epf-test Device +------------------------------- The user can configure the pci-epf-test device using configfs entry. In order to change the vendorid and the number of MSI interrupts used by the function -device, the following commands can be used. +device, the following commands can be used:: # echo 0x104c > functions/pci_epf_test/func1/vendorid # echo 0xb500 > functions/pci_epf_test/func1/deviceid # echo 16 > functions/pci_epf_test/func1/msi_interrupts # echo 8 > functions/pci_epf_test/func1/msix_interrupts -1.5 Binding pci-epf-test Device to EP Controller + +Binding pci-epf-test Device to EP Controller +-------------------------------------------- In order for the endpoint function device to be useful, it has to be bound to a PCI endpoint controller driver. Use the configfs to bind the function -device to one of the controller driver present in the system. +device to one of the controller driver present in the system:: # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/ Once the above step is completed, the PCI endpoint is ready to establish a link with the host. -1.6 Start the Link + +Start the Link +-------------- In order for the endpoint device to establish a link with the host, the _start_ -field should be populated with '1'. +field should be populated with '1':: # echo 1 > controllers/51000000.pcie_ep/start -2. RootComplex Device -2.1 lspci Output +RootComplex Device +================== + +lspci Output +------------ -Note that the devices listed here correspond to the value populated in 1.4 above +Note that the devices listed here correspond to the value populated in 1.4 +above:: 00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01) 01:00.0 Unassigned class [ff00]: Texas Instruments Device b500 -2.2 Using Endpoint Test function Device + +Using Endpoint Test function Device +----------------------------------- pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint -tests. To compile this tool the following commands should be used: +tests. To compile this tool the following commands should be used:: # cd <kernel-dir> # make -C tools/pci -or if you desire to compile and install in your system: +or if you desire to compile and install in your system:: # cd <kernel-dir> # make -C tools/pci install The tool and script will be located in <rootfs>/usr/bin/ -2.2.1 pcitest.sh Output + +pcitest.sh Output +~~~~~~~~~~~~~~~~~ +:: + # pcitest.sh BAR tests diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst new file mode 100644 index 000000000000..f4c6121868c3 --- /dev/null +++ b/Documentation/PCI/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Linux PCI Bus Subsystem +======================= + +.. toctree:: + :maxdepth: 2 + :numbered: + + pci + picebus-howto + pci-iov-howto + msi-howto + acpi-info + pci-error-recovery + pcieaer-howto + endpoint/index diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/msi-howto.rst index 618e13d5e276..994cbb660ade 100644 --- a/Documentation/PCI/MSI-HOWTO.txt +++ b/Documentation/PCI/msi-howto.rst @@ -1,13 +1,16 @@ - The MSI Driver Guide HOWTO - Tom L Nguyen tom.l.nguyen@intel.com - 10/03/2003 - Revised Feb 12, 2004 by Martine Silbermann - email: Martine.Silbermann@hp.com - Revised Jun 25, 2004 by Tom L Nguyen - Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com> - Copyright 2003, 2008 Intel Corporation +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> -1. About this guide +========================== +The MSI Driver Guide HOWTO +========================== + +:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox + +:Copyright: 2003, 2008 Intel Corporation + +About this guide +================ This guide describes the basics of Message Signaled Interrupts (MSIs), the advantages of using MSI over traditional interrupt mechanisms, how @@ -15,7 +18,8 @@ to change your driver to use MSI or MSI-X and some basic diagnostics to try if a device doesn't support MSIs. -2. What are MSIs? +What are MSIs? +============== A Message Signaled Interrupt is a write from the device to a special address which causes an interrupt to be received by the CPU. @@ -29,7 +33,8 @@ Devices may support both MSI and MSI-X, but only one can be enabled at a time. -3. Why use MSIs? +Why use MSIs? +============= There are three reasons why using MSIs can give an advantage over traditional pin-based interrupts. @@ -61,14 +66,16 @@ Other possible designs include giving one interrupt to each packet queue in a network card or each port in a storage controller. -4. How to use MSIs +How to use MSIs +=============== PCI devices are initialised to use pin-based interrupts. The device driver has to set up the device to use MSI or MSI-X. Not all machines support MSIs correctly, and for those machines, the APIs described below will simply fail and the device will continue to use pin-based interrupts. -4.1 Include kernel support for MSIs +Include kernel support for MSIs +------------------------------- To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI option enabled. This option is only available on some architectures, @@ -76,14 +83,15 @@ and it may depend on some other options also being set. For example, on x86, you must also enable X86_UP_APIC or SMP in order to see the CONFIG_PCI_MSI option. -4.2 Using MSI +Using MSI +--------- Most of the hard work is done for the driver in the PCI layer. The driver simply has to request that the PCI layer set up the MSI capability for this device. To automatically use MSI or MSI-X interrupt vectors, use the following -function: +function:: int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, unsigned int max_vecs, unsigned int flags); @@ -101,12 +109,12 @@ any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set, pci_alloc_irq_vectors() will spread the interrupts around the available CPUs. To get the Linux IRQ numbers passed to request_irq() and free_irq() and the -vectors, use the following function: +vectors, use the following function:: int pci_irq_vector(struct pci_dev *dev, unsigned int nr); Any allocated resources should be freed before removing the device using -the following function: +the following function:: void pci_free_irq_vectors(struct pci_dev *dev); @@ -126,7 +134,7 @@ The typical usage of MSI or MSI-X interrupts is to allocate as many vectors as possible, likely up to the limit supported by the device. If nvec is larger than the number supported by the device it will automatically be capped to the supported limit, so there is no need to query the number of -vectors supported beforehand: +vectors supported beforehand:: nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) if (nvec < 0) @@ -135,7 +143,7 @@ vectors supported beforehand: If a driver is unable or unwilling to deal with a variable number of MSI interrupts it can request a particular number of interrupts by passing that number to pci_alloc_irq_vectors() function as both 'min_vecs' and -'max_vecs' parameters: +'max_vecs' parameters:: ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); if (ret < 0) @@ -143,23 +151,24 @@ number to pci_alloc_irq_vectors() function as both 'min_vecs' and The most notorious example of the request type described above is enabling the single MSI mode for a device. It could be done by passing two 1s as -'min_vecs' and 'max_vecs': +'min_vecs' and 'max_vecs':: ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); if (ret < 0) goto out_err; Some devices might not support using legacy line interrupts, in which case -the driver can specify that only MSI or MSI-X is acceptable: +the driver can specify that only MSI or MSI-X is acceptable:: nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); if (nvec < 0) goto out_err; -4.3 Legacy APIs +Legacy APIs +----------- The following old APIs to enable and disable MSI or MSI-X interrupts should -not be used in new code: +not be used in new code:: pci_enable_msi() /* deprecated */ pci_disable_msi() /* deprecated */ @@ -174,9 +183,11 @@ number of vectors. If you have a legitimate special use case for the count of vectors we might have to revisit that decision and add a pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently. -4.4 Considerations when using MSIs +Considerations when using MSIs +------------------------------ -4.4.1 Spinlocks +Spinlocks +~~~~~~~~~ Most device drivers have a per-device spinlock which is taken in the interrupt handler. With pin-based interrupts or a single MSI, it is not @@ -188,7 +199,8 @@ acquire the spinlock. Such deadlocks can be avoided by using spin_lock_irqsave() or spin_lock_irq() which disable local interrupts and acquire the lock (see Documentation/kernel-hacking/locking.rst). -4.5 How to tell whether MSI/MSI-X is enabled on a device +How to tell whether MSI/MSI-X is enabled on a device +---------------------------------------------------- Using 'lspci -v' (as root) may show some devices with "MSI", "Message Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities @@ -196,7 +208,8 @@ has an 'Enable' flag which is followed with either "+" (enabled) or "-" (disabled). -5. MSI quirks +MSI quirks +========== Several PCI chipsets or devices are known not to support MSIs. The PCI stack provides three ways to disable MSIs: @@ -205,7 +218,8 @@ The PCI stack provides three ways to disable MSIs: 2. on all devices behind a specific bridge 3. on a single device -5.1. Disabling MSIs globally +Disabling MSIs globally +----------------------- Some host chipsets simply don't support MSIs properly. If we're lucky, the manufacturer knows this and has indicated it in the ACPI @@ -219,7 +233,8 @@ on the kernel command line to disable MSIs on all devices. It would be in your best interests to report the problem to linux-pci@vger.kernel.org including a full 'lspci -v' so we can add the quirks to the kernel. -5.2. Disabling MSIs below a bridge +Disabling MSIs below a bridge +----------------------------- Some PCI bridges are not able to route MSIs between busses properly. In this case, MSIs must be disabled on all devices behind the bridge. @@ -230,7 +245,7 @@ as the nVidia nForce and Serverworks HT2000). As with host chipsets, Linux mostly knows about them and automatically enables MSIs if it can. If you have a bridge unknown to Linux, you can enable MSIs in configuration space using whatever method you know works, then -enable MSIs on that bridge by doing: +enable MSIs on that bridge by doing:: echo 1 > /sys/bus/pci/devices/$bridge/msi_bus @@ -244,7 +259,8 @@ below this bridge. Again, please notify linux-pci@vger.kernel.org of any bridges that need special handling. -5.3. Disabling MSIs on a single device +Disabling MSIs on a single device +--------------------------------- Some devices are known to have faulty MSI implementations. Usually this is handled in the individual device driver, but occasionally it's necessary @@ -252,7 +268,8 @@ to handle this with a quirk. Some drivers have an option to disable use of MSI. While this is a convenient workaround for the driver author, it is not good practice, and should not be emulated. -5.4. Finding why MSIs are disabled on a device +Finding why MSIs are disabled on a device +----------------------------------------- From the above three sections, you can see that there are many reasons why MSIs may not be enabled for a given device. Your first step should @@ -260,8 +277,8 @@ be to examine your dmesg carefully to determine whether MSIs are enabled for your machine. You should also check your .config to be sure you have enabled CONFIG_PCI_MSI. -Then, 'lspci -t' gives the list of bridges above a device. Reading -/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1) +Then, 'lspci -t' gives the list of bridges above a device. Reading +`/sys/bus/pci/devices/*/msi_bus` will tell you whether MSIs are enabled (1) or disabled (0). If 0 is found in any of the msi_bus files belonging to bridges between the PCI root and the device, MSIs are disabled. diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.rst index 0b6bb3ef449e..83db42092935 100644 --- a/Documentation/PCI/pci-error-recovery.txt +++ b/Documentation/PCI/pci-error-recovery.rst @@ -1,12 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 - PCI Error Recovery - ------------------ - February 2, 2006 +================== +PCI Error Recovery +================== - Current document maintainer: - Linas Vepstas <linasvepstas@gmail.com> - updated by Richard Lary <rlary@us.ibm.com> - and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009 + +:Authors: - Linas Vepstas <linasvepstas@gmail.com> + - Richard Lary <rlary@us.ibm.com> + - Mike Mason <mmlnx@us.ibm.com> Many PCI bus controllers are able to detect a variety of hardware @@ -63,7 +64,8 @@ mechanisms for dealing with SCSI bus errors and SCSI bus resets. Detailed Design ---------------- +=============== + Design and implementation details below, based on a chain of public email discussions with Ben Herrenschmidt, circa 5 April 2005. @@ -73,30 +75,33 @@ pci_driver. A driver that fails to provide the structure is "non-aware", and the actual recovery steps taken are platform dependent. The arch/powerpc implementation will simulate a PCI hotplug remove/add. -This structure has the form: -struct pci_error_handlers -{ - int (*error_detected)(struct pci_dev *dev, enum pci_channel_state); - int (*mmio_enabled)(struct pci_dev *dev); - int (*slot_reset)(struct pci_dev *dev); - void (*resume)(struct pci_dev *dev); -}; - -The possible channel states are: -enum pci_channel_state { - pci_channel_io_normal, /* I/O channel is in normal state */ - pci_channel_io_frozen, /* I/O to channel is blocked */ - pci_channel_io_perm_failure, /* PCI card is dead */ -}; - -Possible return values are: -enum pci_ers_result { - PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */ - PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */ - PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */ - PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */ - PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */ -}; +This structure has the form:: + + struct pci_error_handlers + { + int (*error_detected)(struct pci_dev *dev, enum pci_channel_state); + int (*mmio_enabled)(struct pci_dev *dev); + int (*slot_reset)(struct pci_dev *dev); + void (*resume)(struct pci_dev *dev); + }; + +The possible channel states are:: + + enum pci_channel_state { + pci_channel_io_normal, /* I/O channel is in normal state */ + pci_channel_io_frozen, /* I/O to channel is blocked */ + pci_channel_io_perm_failure, /* PCI card is dead */ + }; + +Possible return values are:: + + enum pci_ers_result { + PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */ + PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */ + PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */ + PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */ + PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */ + }; A driver does not have to implement all of these callbacks; however, if it implements any, it must implement error_detected(). If a callback @@ -134,16 +139,17 @@ shouldn't do any new IOs. Called in task context. This is sort of a All drivers participating in this system must implement this call. The driver must return one of the following result codes: - - PCI_ERS_RESULT_CAN_RECOVER: - Driver returns this if it thinks it might be able to recover - the HW by just banging IOs or if it wants to be given - a chance to extract some diagnostic information (see - mmio_enable, below). - - PCI_ERS_RESULT_NEED_RESET: - Driver returns this if it can't recover without a - slot reset. - - PCI_ERS_RESULT_DISCONNECT: - Driver returns this if it doesn't want to recover at all. + + - PCI_ERS_RESULT_CAN_RECOVER + Driver returns this if it thinks it might be able to recover + the HW by just banging IOs or if it wants to be given + a chance to extract some diagnostic information (see + mmio_enable, below). + - PCI_ERS_RESULT_NEED_RESET + Driver returns this if it can't recover without a + slot reset. + - PCI_ERS_RESULT_DISCONNECT + Driver returns this if it doesn't want to recover at all. The next step taken will depend on the result codes returned by the drivers. @@ -159,25 +165,27 @@ then recovery proceeds to STEP 4 (Slot Reset). If the platform is unable to recover the slot, the next step is STEP 6 (Permanent Failure). ->>> The current powerpc implementation assumes that a device driver will ->>> *not* schedule or semaphore in this routine; the current powerpc ->>> implementation uses one kernel thread to notify all devices; ->>> thus, if one device sleeps/schedules, all devices are affected. ->>> Doing better requires complex multi-threaded logic in the error ->>> recovery implementation (e.g. waiting for all notification threads ->>> to "join" before proceeding with recovery.) This seems excessively ->>> complex and not worth implementing. - ->>> The current powerpc implementation doesn't much care if the device ->>> attempts I/O at this point, or not. I/O's will fail, returning ->>> a value of 0xff on read, and writes will be dropped. If more than ->>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH ->>> assumes that the device driver has gone into an infinite loop ->>> and prints an error to syslog. A reboot is then required to ->>> get the device working again. +.. note:: + + The current powerpc implementation assumes that a device driver will + *not* schedule or semaphore in this routine; the current powerpc + implementation uses one kernel thread to notify all devices; + thus, if one device sleeps/schedules, all devices are affected. + Doing better requires complex multi-threaded logic in the error + recovery implementation (e.g. waiting for all notification threads + to "join" before proceeding with recovery.) This seems excessively + complex and not worth implementing. + + The current powerpc implementation doesn't much care if the device + attempts I/O at this point, or not. I/O's will fail, returning + a value of 0xff on read, and writes will be dropped. If more than + EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH + assumes that the device driver has gone into an infinite loop + and prints an error to syslog. A reboot is then required to + get the device working again. STEP 2: MMIO Enabled -------------------- +-------------------- The platform re-enables MMIO to the device (but typically not the DMA), and then calls the mmio_enabled() callback on all affected device drivers. @@ -192,34 +200,36 @@ link reset was performed by the HW. If the platform can't just re-enable IOs without a slot reset or a link reset, it will not call this callback, and instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) ->>> The following is proposed; no platform implements this yet: ->>> Proposal: All I/O's should be done _synchronously_ from within ->>> this callback, errors triggered by them will be returned via ->>> the normal pci_check_whatever() API, no new error_detected() ->>> callback will be issued due to an error happening here. However, ->>> such an error might cause IOs to be re-blocked for the whole ->>> segment, and thus invalidate the recovery that other devices ->>> on the same segment might have done, forcing the whole segment ->>> into one of the next states, that is, link reset or slot reset. +.. note:: + + The following is proposed; no platform implements this yet: + Proposal: All I/O's should be done _synchronously_ from within + this callback, errors triggered by them will be returned via + the normal pci_check_whatever() API, no new error_detected() + callback will be issued due to an error happening here. However, + such an error might cause IOs to be re-blocked for the whole + segment, and thus invalidate the recovery that other devices + on the same segment might have done, forcing the whole segment + into one of the next states, that is, link reset or slot reset. The driver should return one of the following result codes: - - PCI_ERS_RESULT_RECOVERED - Driver returns this if it thinks the device is fully - functional and thinks it is ready to start - normal driver operations again. There is no - guarantee that the driver will actually be - allowed to proceed, as another driver on the - same segment might have failed and thus triggered a - slot reset on platforms that support it. - - - PCI_ERS_RESULT_NEED_RESET - Driver returns this if it thinks the device is not - recoverable in its current state and it needs a slot - reset to proceed. - - - PCI_ERS_RESULT_DISCONNECT - Same as above. Total failure, no recovery even after - reset driver dead. (To be defined more precisely) + - PCI_ERS_RESULT_RECOVERED + Driver returns this if it thinks the device is fully + functional and thinks it is ready to start + normal driver operations again. There is no + guarantee that the driver will actually be + allowed to proceed, as another driver on the + same segment might have failed and thus triggered a + slot reset on platforms that support it. + + - PCI_ERS_RESULT_NEED_RESET + Driver returns this if it thinks the device is not + recoverable in its current state and it needs a slot + reset to proceed. + + - PCI_ERS_RESULT_DISCONNECT + Same as above. Total failure, no recovery even after + reset driver dead. (To be defined more precisely) The next step taken depends on the results returned by the drivers. If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform @@ -293,31 +303,33 @@ device will be considered "dead" in this case. Drivers for multi-function cards will need to coordinate among themselves as to which driver instance will perform any "one-shot" or global device initialization. For example, the Symbios sym53cxx2 -driver performs device init only from PCI function 0: +driver performs device init only from PCI function 0:: -+ if (PCI_FUNC(pdev->devfn) == 0) -+ sym_reset_scsi_bus(np, 0); + + if (PCI_FUNC(pdev->devfn) == 0) + + sym_reset_scsi_bus(np, 0); - Result codes: - - PCI_ERS_RESULT_DISCONNECT - Same as above. +Result codes: + - PCI_ERS_RESULT_DISCONNECT + Same as above. Drivers for PCI Express cards that require a fundamental reset must set the needs_freset bit in the pci_dev structure in their probe function. For example, the QLogic qla2xxx driver sets the needs_freset bit for certain -PCI card types: +PCI card types:: -+ /* Set EEH reset type to fundamental if required by hba */ -+ if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha)) -+ pdev->needs_freset = 1; -+ + + /* Set EEH reset type to fundamental if required by hba */ + + if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha)) + + pdev->needs_freset = 1; + + Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent Failure). ->>> The current powerpc implementation does not try a power-cycle ->>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT. ->>> However, it probably should. +.. note:: + + The current powerpc implementation does not try a power-cycle + reset if the driver returned PCI_ERS_RESULT_DISCONNECT. + However, it probably should. STEP 5: Resume Operations @@ -370,44 +382,43 @@ The current policy is to turn this into a platform policy. That is, the recovery API only requires that: - There is no guarantee that interrupt delivery can proceed from any -device on the segment starting from the error detection and until the -slot_reset callback is called, at which point interrupts are expected -to be fully operational. + device on the segment starting from the error detection and until the + slot_reset callback is called, at which point interrupts are expected + to be fully operational. - There is no guarantee that interrupt delivery is stopped, that is, -a driver that gets an interrupt after detecting an error, or that detects -an error within the interrupt handler such that it prevents proper -ack'ing of the interrupt (and thus removal of the source) should just -return IRQ_NOTHANDLED. It's up to the platform to deal with that -condition, typically by masking the IRQ source during the duration of -the error handling. It is expected that the platform "knows" which -interrupts are routed to error-management capable slots and can deal -with temporarily disabling that IRQ number during error processing (this -isn't terribly complex). That means some IRQ latency for other devices -sharing the interrupt, but there is simply no other way. High end -platforms aren't supposed to share interrupts between many devices -anyway :) - ->>> Implementation details for the powerpc platform are discussed in ->>> the file Documentation/powerpc/eeh-pci-error-recovery.txt - ->>> As of this writing, there is a growing list of device drivers with ->>> patches implementing error recovery. Not all of these patches are in ->>> mainline yet. These may be used as "examples": ->>> ->>> drivers/scsi/ipr ->>> drivers/scsi/sym53c8xx_2 ->>> drivers/scsi/qla2xxx ->>> drivers/scsi/lpfc ->>> drivers/next/bnx2.c ->>> drivers/next/e100.c ->>> drivers/net/e1000 ->>> drivers/net/e1000e ->>> drivers/net/ixgb ->>> drivers/net/ixgbe ->>> drivers/net/cxgb3 ->>> drivers/net/s2io.c ->>> drivers/net/qlge - -The End -------- + a driver that gets an interrupt after detecting an error, or that detects + an error within the interrupt handler such that it prevents proper + ack'ing of the interrupt (and thus removal of the source) should just + return IRQ_NOTHANDLED. It's up to the platform to deal with that + condition, typically by masking the IRQ source during the duration of + the error handling. It is expected that the platform "knows" which + interrupts are routed to error-management capable slots and can deal + with temporarily disabling that IRQ number during error processing (this + isn't terribly complex). That means some IRQ latency for other devices + sharing the interrupt, but there is simply no other way. High end + platforms aren't supposed to share interrupts between many devices + anyway :) + +.. note:: + + Implementation details for the powerpc platform are discussed in + the file Documentation/powerpc/eeh-pci-error-recovery.txt + + As of this writing, there is a growing list of device drivers with + patches implementing error recovery. Not all of these patches are in + mainline yet. These may be used as "examples": + + - drivers/scsi/ipr + - drivers/scsi/sym53c8xx_2 + - drivers/scsi/qla2xxx + - drivers/scsi/lpfc + - drivers/next/bnx2.c + - drivers/next/e100.c + - drivers/net/e1000 + - drivers/net/e1000e + - drivers/net/ixgb + - drivers/net/ixgbe + - drivers/net/cxgb3 + - drivers/net/s2io.c + - drivers/net/qlge diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.rst index d2a84151e99c..b9fd003206f1 100644 --- a/Documentation/PCI/pci-iov-howto.txt +++ b/Documentation/PCI/pci-iov-howto.rst @@ -1,14 +1,19 @@ - PCI Express I/O Virtualization Howto - Copyright (C) 2009 Intel Corporation - Yu Zhao <yu.zhao@intel.com> +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> - Update: November 2012 - -- sysfs-based SRIOV enable-/disable-ment - Donald Dutile <ddutile@redhat.com> +==================================== +PCI Express I/O Virtualization Howto +==================================== -1. Overview +:Copyright: |copy| 2009 Intel Corporation +:Authors: - Yu Zhao <yu.zhao@intel.com> + - Donald Dutile <ddutile@redhat.com> -1.1 What is SR-IOV +Overview +======== + +What is SR-IOV +-------------- Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended capability which makes one physical device appear as multiple virtual @@ -23,9 +28,11 @@ Memory Space, which is used to map its register set. VF device driver operates on the register set so it can be functional and appear as a real existing PCI device. -2. User Guide +User Guide +========== -2.1 How can I enable SR-IOV capability +How can I enable SR-IOV capability +---------------------------------- Multiple methods are available for SR-IOV enablement. In the first method, the device driver (PF driver) will control the @@ -43,105 +50,123 @@ checks, e.g., check numvfs == 0 if enabling VFs, ensure numvfs <= totalvfs. The second method is the recommended method for new/future VF devices. -2.2 How can I use the Virtual Functions +How can I use the Virtual Functions +----------------------------------- The VF is treated as hot-plugged PCI devices in the kernel, so they should be able to work in the same way as real PCI devices. The VF requires device driver that is same as a normal PCI device's. -3. Developer Guide +Developer Guide +=============== -3.1 SR-IOV API +SR-IOV API +---------- To enable SR-IOV capability: -(a) For the first method, in the driver: + +(a) For the first method, in the driver:: + int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn); - 'nr_virtfn' is number of VFs to be enabled. -(b) For the second method, from sysfs: + +'nr_virtfn' is number of VFs to be enabled. + +(b) For the second method, from sysfs:: + echo 'nr_virtfn' > \ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs To disable SR-IOV capability: -(a) For the first method, in the driver: + +(a) For the first method, in the driver:: + void pci_disable_sriov(struct pci_dev *dev); -(b) For the second method, from sysfs: + +(b) For the second method, from sysfs:: + echo 0 > \ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs To enable auto probing VFs by a compatible driver on the host, run command below before enabling SR-IOV capabilities. This is the default behavior. +:: + echo 1 > \ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe To disable auto probing VFs by a compatible driver on the host, run command below before enabling SR-IOV capabilities. Updating this entry will not affect VFs which are already probed. +:: + echo 0 > \ /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_drivers_autoprobe -3.2 Usage example +Usage example +------------- Following piece of code illustrates the usage of the SR-IOV API. +:: -static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) -{ - pci_enable_sriov(dev, NR_VIRTFN); + static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) + { + pci_enable_sriov(dev, NR_VIRTFN); - ... - - return 0; -} + ... -static void dev_remove(struct pci_dev *dev) -{ - pci_disable_sriov(dev); + return 0; + } - ... -} + static void dev_remove(struct pci_dev *dev) + { + pci_disable_sriov(dev); -static int dev_suspend(struct pci_dev *dev, pm_message_t state) -{ - ... + ... + } - return 0; -} + static int dev_suspend(struct pci_dev *dev, pm_message_t state) + { + ... -static int dev_resume(struct pci_dev *dev) -{ - ... + return 0; + } - return 0; -} + static int dev_resume(struct pci_dev *dev) + { + ... -static void dev_shutdown(struct pci_dev *dev) -{ - ... -} + return 0; + } -static int dev_sriov_configure(struct pci_dev *dev, int numvfs) -{ - if (numvfs > 0) { - ... - pci_enable_sriov(dev, numvfs); + static void dev_shutdown(struct pci_dev *dev) + { ... - return numvfs; } - if (numvfs == 0) { - .... - pci_disable_sriov(dev); - ... - return 0; + + static int dev_sriov_configure(struct pci_dev *dev, int numvfs) + { + if (numvfs > 0) { + ... + pci_enable_sriov(dev, numvfs); + ... + return numvfs; + } + if (numvfs == 0) { + .... + pci_disable_sriov(dev); + ... + return 0; + } } -} - -static struct pci_driver dev_driver = { - .name = "SR-IOV Physical Function driver", - .id_table = dev_id_table, - .probe = dev_probe, - .remove = dev_remove, - .suspend = dev_suspend, - .resume = dev_resume, - .shutdown = dev_shutdown, - .sriov_configure = dev_sriov_configure, -}; + + static struct pci_driver dev_driver = { + .name = "SR-IOV Physical Function driver", + .id_table = dev_id_table, + .probe = dev_probe, + .remove = dev_remove, + .suspend = dev_suspend, + .resume = dev_resume, + .shutdown = dev_shutdown, + .sriov_configure = dev_sriov_configure, + }; diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.rst index badb26ac33dc..6864f9a70f5f 100644 --- a/Documentation/PCI/pci.txt +++ b/Documentation/PCI/pci.rst @@ -1,10 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 - How To Write Linux PCI Drivers +============================== +How To Write Linux PCI Drivers +============================== - by Martin Mares <mj@ucw.cz> on 07-Feb-2000 - updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006 +:Authors: - Martin Mares <mj@ucw.cz> + - Grant Grundler <grundler@parisc-linux.org> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The world of PCI is vast and full of (mostly unpleasant) surprises. Since each CPU architecture implements different chip-sets and PCI devices have different requirements (erm, "features"), the result is the PCI support @@ -15,8 +17,7 @@ PCI device drivers. A more complete resource is the third edition of "Linux Device Drivers" by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. LDD3 is available for free (under Creative Commons License) from: - - http://lwn.net/Kernel/LDD3/ +http://lwn.net/Kernel/LDD3/. However, keep in mind that all documents are subject to "bit rot". Refer to the source code if things are not working as described here. @@ -25,9 +26,8 @@ Please send questions/comments/patches about Linux PCI API to the "Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. - -0. Structure of PCI drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Structure of PCI drivers +======================== PCI drivers "discover" PCI devices in a system via pci_register_driver(). Actually, it's the other way around. When the PCI generic code discovers a new device, the driver with a matching "description" will be notified. @@ -42,24 +42,25 @@ pointers and thus dictates the high level structure of a driver. Once the driver knows about a PCI device and takes ownership, the driver generally needs to perform the following initialization: - Enable the device - Request MMIO/IOP resources - Set the DMA mask size (for both coherent and streaming DMA) - Allocate and initialize shared control data (pci_allocate_coherent()) - Access device configuration space (if needed) - Register IRQ handler (request_irq()) - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) - Enable DMA/processing engines + - Enable the device + - Request MMIO/IOP resources + - Set the DMA mask size (for both coherent and streaming DMA) + - Allocate and initialize shared control data (pci_allocate_coherent()) + - Access device configuration space (if needed) + - Register IRQ handler (request_irq()) + - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + - Enable DMA/processing engines When done using the device, and perhaps the module needs to be unloaded, the driver needs to take the follow steps: - Disable the device from generating IRQs - Release the IRQ (free_irq()) - Stop all DMA activity - Release DMA buffers (both streaming and coherent) - Unregister from other subsystems (e.g. scsi or netdev) - Release MMIO/IOP resources - Disable the device + + - Disable the device from generating IRQs + - Release the IRQ (free_irq()) + - Stop all DMA activity + - Release DMA buffers (both streaming and coherent) + - Unregister from other subsystems (e.g. scsi or netdev) + - Release MMIO/IOP resources + - Disable the device Most of these topics are covered in the following sections. For the rest look at LDD3 or <linux/pci.h> . @@ -70,99 +71,38 @@ completely empty or just returning an appropriate error codes to avoid lots of ifdefs in the drivers. +pci_register_driver() call +========================== -1. pci_register_driver() call -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -PCI device drivers call pci_register_driver() during their +PCI device drivers call ``pci_register_driver()`` during their initialization with a pointer to a structure describing the driver -(struct pci_driver): - - field name Description - ---------- ------------------------------------------------------ - id_table Pointer to table of device ID's the driver is - interested in. Most drivers should export this - table using MODULE_DEVICE_TABLE(pci,...). - - probe This probing function gets called (during execution - of pci_register_driver() for already existing - devices or later if a new device gets inserted) for - all PCI devices which match the ID table and are not - "owned" by the other drivers yet. This function gets - passed a "struct pci_dev *" for each device whose - entry in the ID table matches the device. The probe - function returns zero when the driver chooses to - take "ownership" of the device or an error code - (negative number) otherwise. - The probe function always gets called from process - context, so it can sleep. - - remove The remove() function gets called whenever a device - being handled by this driver is removed (either during - deregistration of the driver or when it's manually - pulled out of a hot-pluggable slot). - The remove function always gets called from process - context, so it can sleep. - - suspend Put device into low power state. - suspend_late Put device into low power state. - - resume_early Wake device from low power state. - resume Wake device from low power state. - - (Please see Documentation/power/pci.txt for descriptions - of PCI Power Management and the related functions.) - - shutdown Hook into reboot_notifier_list (kernel/sys.c). - Intended to stop any idling DMA operations. - Useful for enabling wake-on-lan (NIC) or changing - the power state of a device before reboot. - e.g. drivers/net/e100.c. - - err_handler See Documentation/PCI/pci-error-recovery.txt - - -The ID table is an array of struct pci_device_id entries ending with an -all-zero entry. Definitions with static const are generally preferred. - -Each entry consists of: - - vendor,device Vendor and device ID to match (or PCI_ANY_ID) +(``struct pci_driver``): - subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID) - subdevice, +.. kernel-doc:: include/linux/pci.h + :functions: pci_driver - class Device class, subclass, and "interface" to match. - See Appendix D of the PCI Local Bus Spec or - include/linux/pci_ids.h for a full list of classes. - Most drivers do not need to specify class/class_mask - as vendor/device is normally sufficient. - - class_mask limit which sub-fields of the class field are compared. - See drivers/scsi/sym53c8xx_2/ for example of usage. - - driver_data Data private to the driver. - Most drivers don't need to use driver_data field. - Best practice is to use driver_data as an index - into a static list of equivalent device types, - instead of using it as a pointer. +The ID table is an array of ``struct pci_device_id`` entries ending with an +all-zero entry. Definitions with static const are generally preferred. +.. kernel-doc:: include/linux/mod_devicetable.h + :functions: pci_device_id -Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up +Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up a pci_device_id table. New PCI IDs may be added to a device driver pci_ids table at runtime -as shown below: +as shown below:: -echo "vendor device subvendor subdevice class class_mask driver_data" > \ -/sys/bus/pci/drivers/{driver}/new_id + echo "vendor device subvendor subdevice class class_mask driver_data" > \ + /sys/bus/pci/drivers/{driver}/new_id All fields are passed in as hexadecimal values (no leading 0x). The vendor and device fields are mandatory, the others are optional. Users need pass only as many optional fields as necessary: - o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) - o class and classmask fields default to 0 - o driver_data defaults to 0UL. + + - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) + - class and classmask fields default to 0 + - driver_data defaults to 0UL. Note that driver_data must match the value used by any of the pci_device_id entries defined in the driver. This makes the driver_data field mandatory @@ -175,29 +115,31 @@ When the driver exits, it just calls pci_unregister_driver() and the PCI layer automatically calls the remove hook for all devices handled by the driver. -1.1 "Attributes" for driver functions/data +"Attributes" for driver functions/data +-------------------------------------- Please mark the initialization and cleanup functions where appropriate (the corresponding macros are defined in <linux/init.h>): + ====== ================================================= __init Initialization code. Thrown away after the driver initializes. __exit Exit code. Ignored for non-modular drivers. + ====== ================================================= Tips on when/where to use the above attributes: - o The module_init()/module_exit() functions (and all + - The module_init()/module_exit() functions (and all initialization functions called _only_ from these) should be marked __init/__exit. - o Do not mark the struct pci_driver. + - Do not mark the struct pci_driver. - o Do NOT mark a function if you are not sure which mark to use. + - Do NOT mark a function if you are not sure which mark to use. Better to not mark the function than mark the function wrong. - -2. How to find PCI devices manually -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How to find PCI devices manually +================================ PCI drivers should have a really good reason for not using the pci_register_driver() interface to search for PCI devices. @@ -207,17 +149,17 @@ E.g. combined serial/parallel port/floppy controller. A manual search may be performed using the following constructs: -Searching by vendor and device ID: +Searching by vendor and device ID:: struct pci_dev *dev = NULL; while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev)) configure_device(dev); -Searching by class ID (iterate in a similar way): +Searching by class ID (iterate in a similar way):: pci_get_class(CLASS_ID, dev) -Searching by both vendor/device and subsystem vendor/device ID: +Searching by both vendor/device and subsystem vendor/device ID:: pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). @@ -230,21 +172,20 @@ the pci_dev that they return. You must eventually (possibly at module unload) decrement the reference count on these devices by calling pci_dev_put(). - -3. Device Initialization Steps -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Device Initialization Steps +=========================== As noted in the introduction, most PCI drivers need the following steps for device initialization: - Enable the device - Request MMIO/IOP resources - Set the DMA mask size (for both coherent and streaming DMA) - Allocate and initialize shared control data (pci_allocate_coherent()) - Access device configuration space (if needed) - Register IRQ handler (request_irq()) - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) - Enable DMA/processing engines. + - Enable the device + - Request MMIO/IOP resources + - Set the DMA mask size (for both coherent and streaming DMA) + - Allocate and initialize shared control data (pci_allocate_coherent()) + - Access device configuration space (if needed) + - Register IRQ handler (request_irq()) + - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + - Enable DMA/processing engines. The driver can access PCI config space registers at any time. (Well, almost. When running BIST, config space can go away...but @@ -252,26 +193,29 @@ that will just result in a PCI Bus Master Abort and config reads will return garbage). -3.1 Enable the PCI device -~~~~~~~~~~~~~~~~~~~~~~~~~ +Enable the PCI device +--------------------- Before touching any device registers, the driver needs to enable the PCI device by calling pci_enable_device(). This will: - o wake up the device if it was in suspended state, - o allocate I/O and memory regions of the device (if BIOS did not), - o allocate an IRQ (if BIOS did not). -NOTE: pci_enable_device() can fail! Check the return value. + - wake up the device if it was in suspended state, + - allocate I/O and memory regions of the device (if BIOS did not), + - allocate an IRQ (if BIOS did not). -[ OS BUG: we don't check resource allocations before enabling those - resources. The sequence would make more sense if we called - pci_request_resources() before calling pci_enable_device(). - Currently, the device drivers can't detect the bug when when two - devices have been allocated the same range. This is not a common - problem and unlikely to get fixed soon. +.. note:: + pci_enable_device() can fail! Check the return value. + +.. warning:: + OS BUG: we don't check resource allocations before enabling those + resources. The sequence would make more sense if we called + pci_request_resources() before calling pci_enable_device(). + Currently, the device drivers can't detect the bug when when two + devices have been allocated the same range. This is not a common + problem and unlikely to get fixed soon. + + This has been discussed before but not changed as of 2.6.19: + http://lkml.org/lkml/2006/3/2/194 - This has been discussed before but not changed as of 2.6.19: - http://lkml.org/lkml/2006/3/2/194 -] pci_set_master() will enable DMA by setting the bus master bit in the PCI_COMMAND register. It also fixes the latency timer value if @@ -288,8 +232,8 @@ pci_try_set_mwi() to have the system do its best effort at enabling Mem-Wr-Inval. -3.2 Request MMIO/IOP resources -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Request MMIO/IOP resources +-------------------------- Memory (MMIO), and I/O port addresses should NOT be read directly from the PCI device config space. Use the values in the pci_dev structure as the PCI "bus address" might have been remapped to a "host physical" @@ -304,9 +248,10 @@ Conversely, drivers should call pci_release_region() AFTER calling pci_disable_device(). The idea is to prevent two devices colliding on the same address range. -[ See OS BUG comment above. Currently (2.6.19), The driver can only - determine MMIO and IO Port resource availability _after_ calling - pci_enable_device(). ] +.. tip:: + See OS BUG comment above. Currently (2.6.19), The driver can only + determine MMIO and IO Port resource availability _after_ calling + pci_enable_device(). Generic flavors of pci_request_region() are request_mem_region() (for MMIO ranges) and request_region() (for IO Port ranges). @@ -316,12 +261,13 @@ BARs. Also see pci_request_selected_regions() below. -3.3 Set the DMA mask size -~~~~~~~~~~~~~~~~~~~~~~~~~ -[ If anything below doesn't make sense, please refer to - Documentation/DMA-API.txt. This section is just a reminder that - drivers need to indicate DMA capabilities of the device and is not - an authoritative source for DMA interfaces. ] +Set the DMA mask size +--------------------- +.. note:: + If anything below doesn't make sense, please refer to + Documentation/DMA-API.txt. This section is just a reminder that + drivers need to indicate DMA capabilities of the device and is not + an authoritative source for DMA interfaces. While all drivers should explicitly indicate the DMA capability (e.g. 32 or 64 bit) of the PCI bus master, devices with more than @@ -342,23 +288,23 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are ("consistent") data. -3.4 Setup shared control data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Setup shared control data +------------------------- Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) memory. See Documentation/DMA-API.txt for a full description of the DMA APIs. This section is just a reminder that it needs to be done before enabling DMA on the device. -3.5 Initialize device registers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Initialize device registers +--------------------------- Some drivers will need specific "capability" fields programmed or other "vendor specific" register initialized or reset. E.g. clearing pending interrupts. -3.6 Register IRQ handler -~~~~~~~~~~~~~~~~~~~~~~~~ +Register IRQ handler +-------------------- While calling request_irq() is the last step described here, this is often just another intermediate step to initialize a device. This step can often be deferred until the device is opened for use. @@ -396,6 +342,7 @@ and msix_enabled flags in the pci_dev structure after calling pci_alloc_irq_vectors. There are (at least) two really good reasons for using MSI: + 1) MSI is an exclusive interrupt vector by definition. This means the interrupt handler doesn't have to verify its device caused the interrupt. @@ -410,24 +357,23 @@ See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples of MSI/MSI-X usage. - -4. PCI device shutdown -~~~~~~~~~~~~~~~~~~~~~~~ +PCI device shutdown +=================== When a PCI device driver is being unloaded, most of the following steps need to be performed: - Disable the device from generating IRQs - Release the IRQ (free_irq()) - Stop all DMA activity - Release DMA buffers (both streaming and consistent) - Unregister from other subsystems (e.g. scsi or netdev) - Disable device from responding to MMIO/IO Port addresses - Release MMIO/IO Port resource(s) + - Disable the device from generating IRQs + - Release the IRQ (free_irq()) + - Stop all DMA activity + - Release DMA buffers (both streaming and consistent) + - Unregister from other subsystems (e.g. scsi or netdev) + - Disable device from responding to MMIO/IO Port addresses + - Release MMIO/IO Port resource(s) -4.1 Stop IRQs on the device -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Stop IRQs on the device +----------------------- How to do this is chip/device specific. If it's not done, it opens the possibility of a "screaming interrupt" if (and only if) the IRQ is shared with another device. @@ -446,16 +392,16 @@ MSI and MSI-X are defined to be exclusive interrupts and thus are not susceptible to the "screaming interrupt" problem. -4.2 Release the IRQ -~~~~~~~~~~~~~~~~~~~ +Release the IRQ +--------------- Once the device is quiesced (no more IRQs), one can call free_irq(). This function will return control once any pending IRQs are handled, "unhook" the drivers IRQ handler from that IRQ, and finally release the IRQ if no one else is using it. -4.3 Stop all DMA activity -~~~~~~~~~~~~~~~~~~~~~~~~~ +Stop all DMA activity +--------------------- It's extremely important to stop all DMA operations BEFORE attempting to deallocate DMA control data. Failure to do so can result in memory corruption, hangs, and on some chip-sets a hard crash. @@ -467,8 +413,8 @@ While this step sounds obvious and trivial, several "mature" drivers didn't get this step right in the past. -4.4 Release DMA buffers -~~~~~~~~~~~~~~~~~~~~~~~ +Release DMA buffers +------------------- Once DMA is stopped, clean up streaming DMA first. I.e. unmap data buffers and return buffers to "upstream" owners if there is one. @@ -478,8 +424,8 @@ Then clean up "consistent" buffers which contain the control data. See Documentation/DMA-API.txt for details on unmapping interfaces. -4.5 Unregister from other subsystems -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Unregister from other subsystems +-------------------------------- Most low level PCI device drivers support some other subsystem like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your driver isn't losing resources from that other subsystem. @@ -487,31 +433,30 @@ If this happens, typically the symptom is an Oops (panic) when the subsystem attempts to call into a driver that has been unloaded. -4.6 Disable Device from responding to MMIO/IO Port addresses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Disable Device from responding to MMIO/IO Port addresses +-------------------------------------------------------- io_unmap() MMIO or IO Port resources and then call pci_disable_device(). This is the symmetric opposite of pci_enable_device(). Do not access device registers after calling pci_disable_device(). -4.7 Release MMIO/IO Port Resource(s) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Release MMIO/IO Port Resource(s) +-------------------------------- Call pci_release_region() to mark the MMIO or IO Port range as available. Failure to do so usually results in the inability to reload the driver. +How to access PCI config space +============================== -5. How to access PCI config space -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can use pci_(read|write)_config_(byte|word|dword) to access the config -space of a device represented by struct pci_dev *. All these functions return 0 -when successful or an error code (PCIBIOS_...) which can be translated to a text -string by pcibios_strerror. Most drivers expect that accesses to valid PCI +You can use `pci_(read|write)_config_(byte|word|dword)` to access the config +space of a device represented by `struct pci_dev *`. All these functions return +0 when successful or an error code (`PCIBIOS_...`) which can be translated to a +text string by pcibios_strerror. Most drivers expect that accesses to valid PCI devices don't fail. If you don't have a struct pci_dev available, you can call -pci_bus_(read|write)_config_(byte|word|dword) to access a given device +`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device and function on that bus. If you access fields in the standard portion of the config header, please @@ -522,10 +467,10 @@ pci_find_capability() for the particular capability and it will find the corresponding register block for you. +Other interesting functions +=========================== -6. Other interesting functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - +============================= ================================================ pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain, bus and slot and number. If the device is found, its reference count is increased. @@ -539,11 +484,11 @@ pci_set_drvdata() Set private driver data pointer for a pci_dev pci_get_drvdata() Return private driver data pointer for a pci_dev pci_set_mwi() Enable Memory-Write-Invalidate transactions. pci_clear_mwi() Disable Memory-Write-Invalidate transactions. +============================= ================================================ - -7. Miscellaneous hints -~~~~~~~~~~~~~~~~~~~~~~ +Miscellaneous hints +=================== When displaying PCI device names to the user (for example when a driver wants to tell the user what card has it found), please use pci_name(pci_dev). @@ -559,9 +504,8 @@ on the bus need to be capable of doing it, so this is something which needs to be handled by platform and generic code, not individual drivers. - -8. Vendor and device identifications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Vendor and device identifications +================================= Do not add new device or vendor IDs to include/linux/pci_ids.h unless they are shared across multiple drivers. You can add private definitions in @@ -575,28 +519,27 @@ There are mirrors of the pci.ids file at http://pciids.sourceforge.net/ and https://github.com/pciutils/pciids. - -9. Obsolete functions -~~~~~~~~~~~~~~~~~~~~~ +Obsolete functions +================== There are several functions which you might come across when trying to port an old driver to the new PCI interface. They are no longer present in the kernel as they aren't compatible with hotplug or PCI domains or having sane locking. +================= =========================================== pci_find_device() Superseded by pci_get_device() pci_find_subsys() Superseded by pci_get_subsys() pci_find_slot() Superseded by pci_get_domain_bus_and_slot() pci_get_slot() Superseded by pci_get_domain_bus_and_slot() - +================= =========================================== The alternative is the traditional PCI device driver that walks PCI device lists. This is still possible but discouraged. - -10. MMIO Space and "Write Posting" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +MMIO Space and "Write Posting" +============================== Converting a driver from using I/O Port space to using MMIO space often requires some additional changes. Specifically, "write posting" @@ -609,14 +552,14 @@ the CPU before the transaction has reached its destination. Thus, timing sensitive code should add readl() where the CPU is expected to wait before doing other work. The classic "bit banging" -sequence works fine for I/O Port space: +sequence works fine for I/O Port space:: for (i = 8; --i; val >>= 1) { outb(val & 1, ioport_reg); /* write bit */ udelay(10); } -The same sequence for MMIO space should be: +The same sequence for MMIO space should be:: for (i = 8; --i; val >>= 1) { writeb(val & 1, mmio_reg); /* write bit */ @@ -633,4 +576,3 @@ handle the PCI master abort on all platforms if the PCI device is expected to not respond to a readl(). Most x86 platforms will allow MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage (e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). - diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.rst index 48ce7903e3c6..18bdefaafd1a 100644 --- a/Documentation/PCI/pcieaer-howto.txt +++ b/Documentation/PCI/pcieaer-howto.rst @@ -1,21 +1,29 @@ - The PCI Express Advanced Error Reporting Driver Guide HOWTO - T. Long Nguyen <tom.l.nguyen@intel.com> - Yanmin Zhang <yanmin.zhang@intel.com> - 07/29/2006 +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> +=========================================================== +The PCI Express Advanced Error Reporting Driver Guide HOWTO +=========================================================== -1. Overview +:Authors: - T. Long Nguyen <tom.l.nguyen@intel.com> + - Yanmin Zhang <yanmin.zhang@intel.com> -1.1 About this guide +:Copyright: |copy| 2006 Intel Corporation + +Overview +=========== + +About this guide +---------------- This guide describes the basics of the PCI Express Advanced Error Reporting (AER) driver and provides information on how to use it, as well as how to enable the drivers of endpoint devices to conform with PCI Express AER driver. -1.2 Copyright (C) Intel Corporation 2006. -1.3 What is the PCI Express AER Driver? +What is the PCI Express AER Driver? +----------------------------------- PCI Express error signaling can occur on the PCI Express link itself or on behalf of transactions initiated on the link. PCI Express @@ -30,17 +38,19 @@ The PCI Express AER driver provides the infrastructure to support PCI Express Advanced Error Reporting capability. The PCI Express AER driver provides three basic functions: -- Gathers the comprehensive error information if errors occurred. -- Reports error to the users. -- Performs error recovery actions. + - Gathers the comprehensive error information if errors occurred. + - Reports error to the users. + - Performs error recovery actions. AER driver only attaches root ports which support PCI-Express AER capability. -2. User Guide +User Guide +========== -2.1 Include the PCI Express AER Root Driver into the Linux Kernel +Include the PCI Express AER Root Driver into the Linux Kernel +------------------------------------------------------------- The PCI Express AER Root driver is a Root Port service driver attached to the PCI Express Port Bus driver. If a user wants to use it, the driver @@ -48,7 +58,8 @@ has to be compiled. Option CONFIG_PCIEAER supports this capability. It depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and CONFIG_PCIEAER = y. -2.2 Load PCI Express AER Root Driver +Load PCI Express AER Root Driver +-------------------------------- Some systems have AER support in firmware. Enabling Linux AER support at the same time the firmware handles AER may result in unpredictable @@ -56,30 +67,34 @@ behavior. Therefore, Linux does not handle AER events unless the firmware grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0 Specification for details regarding _OSC usage. -2.3 AER error output +AER error output +---------------- When a PCIe AER error is captured, an error message will be output to console. If it's a correctable error, it is output as a warning. Otherwise, it is printed as an error. So users could choose different log level to filter out correctable error messages. -Below shows an example: -0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID) -0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000 -0000:50:00.0: [20] Unsupported Request (First) -0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100 +Below shows an example:: + + 0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID) + 0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000 + 0000:50:00.0: [20] Unsupported Request (First) + 0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100 In the example, 'Requester ID' means the ID of the device who sends the error message to root port. Pls. refer to pci express specs for other fields. -2.4 AER Statistics / Counters +AER Statistics / Counters +------------------------- When PCIe AER errors are captured, the counters / statistics are also exposed in the form of sysfs attributes which are documented at Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats -3. Developer Guide +Developer Guide +=============== To enable AER aware support requires a software driver to configure the AER capability structure within its device and to provide callbacks. @@ -120,7 +135,8 @@ hierarchy and links. These errors do not include any device specific errors because device specific errors will still get sent directly to the device driver. -3.1 Configure the AER capability structure +Configure the AER capability structure +-------------------------------------- AER aware drivers of PCI Express component need change the device control registers to enable AER. They also could change AER registers, @@ -128,9 +144,11 @@ including mask and severity registers. Helper function pci_enable_pcie_error_reporting could be used to enable AER. See section 3.3. -3.2. Provide callbacks +Provide callbacks +----------------- -3.2.1 callback reset_link to reset pci express link +callback reset_link to reset pci express link +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This callback is used to reset the pci express physical link when a fatal error happens. The root port aer service driver provides a @@ -140,13 +158,15 @@ upstream ports should provide their own reset_link functions. In struct pcie_port_service_driver, a new pointer, reset_link, is added. +:: -pci_ers_result_t (*reset_link) (struct pci_dev *dev); + pci_ers_result_t (*reset_link) (struct pci_dev *dev); Section 3.2.2.2 provides more detailed info on when to call reset_link. -3.2.2 PCI error-recovery callbacks +PCI error-recovery callbacks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The PCI Express AER Root driver uses error callbacks to coordinate with downstream device drivers associated with a hierarchy in question @@ -161,7 +181,8 @@ definitions of the callbacks. Below sections specify when to call the error callback functions. -3.2.2.1 Correctable errors +Correctable errors +~~~~~~~~~~~~~~~~~~ Correctable errors pose no impacts on the functionality of the interface. The PCI Express protocol can recover without any @@ -169,13 +190,16 @@ software intervention or any loss of data. These errors do not require any recovery actions. The AER driver clears the device's correctable error status register accordingly and logs these errors. -3.2.2.2 Non-correctable (non-fatal and fatal) errors +Non-correctable (non-fatal and fatal) errors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If an error message indicates a non-fatal error, performing link reset at upstream is not required. The AER driver calls error_detected(dev, pci_channel_io_normal) to all drivers associated within a hierarchy in -question. for example, -EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort. +question. for example:: + + EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort + If Upstream port A captures an AER error, the hierarchy consists of Downstream port B and EndPoint. @@ -199,53 +223,72 @@ function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes to mmio_enabled. -3.3 helper functions +helper functions +---------------- +:: + + int pci_enable_pcie_error_reporting(struct pci_dev *dev); -3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev); pci_enable_pcie_error_reporting enables the device to send error messages to root port when an error is detected. Note that devices don't enable the error reporting by default, so device drivers need call this function to enable it. -3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev); +:: + + int pci_disable_pcie_error_reporting(struct pci_dev *dev); + pci_disable_pcie_error_reporting disables the device to send error messages to root port when an error is detected. -3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev); +:: + + int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev);` + pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable error status register. -3.4 Frequent Asked Questions +Frequent Asked Questions +------------------------ -Q: What happens if a PCI Express device driver does not provide an -error recovery handler (pci_driver->err_handler is equal to NULL)? +Q: + What happens if a PCI Express device driver does not provide an + error recovery handler (pci_driver->err_handler is equal to NULL)? -A: The devices attached with the driver won't be recovered. If the -error is fatal, kernel will print out warning messages. Please refer -to section 3 for more information. +A: + The devices attached with the driver won't be recovered. If the + error is fatal, kernel will print out warning messages. Please refer + to section 3 for more information. -Q: What happens if an upstream port service driver does not provide -callback reset_link? +Q: + What happens if an upstream port service driver does not provide + callback reset_link? -A: Fatal error recovery will fail if the errors are reported by the -upstream ports who are attached by the service driver. +A: + Fatal error recovery will fail if the errors are reported by the + upstream ports who are attached by the service driver. -Q: How does this infrastructure deal with driver that is not PCI -Express aware? +Q: + How does this infrastructure deal with driver that is not PCI + Express aware? -A: This infrastructure calls the error callback functions of the -driver when an error happens. But if the driver is not aware of -PCI Express, the device might not report its own errors to root -port. +A: + This infrastructure calls the error callback functions of the + driver when an error happens. But if the driver is not aware of + PCI Express, the device might not report its own errors to root + port. -Q: What modifications will that driver need to make it compatible -with the PCI Express AER Root driver? +Q: + What modifications will that driver need to make it compatible + with the PCI Express AER Root driver? -A: It could call the helper functions to enable AER in devices and -cleanup uncorrectable status register. Pls. refer to section 3.3. +A: + It could call the helper functions to enable AER in devices and + cleanup uncorrectable status register. Pls. refer to section 3.3. -4. Software error injection +Software error injection +======================== Debugging PCIe AER error recovery code is quite difficult because it is hard to trigger real hardware errors. Software based error @@ -261,6 +304,7 @@ After reboot with new kernel or insert the module, a device file named Then, you need a user space tool named aer-inject, which can be gotten from: + https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/ More information about aer-inject can be found in the document comes diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/picebus-howto.rst index 15f0bb3b5045..f882ff62c51f 100644 --- a/Documentation/PCI/PCIEBUS-HOWTO.txt +++ b/Documentation/PCI/picebus-howto.rst @@ -1,16 +1,23 @@ - The PCI Express Port Bus Driver Guide HOWTO - Tom L Nguyen tom.l.nguyen@intel.com - 11/03/2004 +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> -1. About this guide +=========================================== +The PCI Express Port Bus Driver Guide HOWTO +=========================================== + +:Author: Tom L Nguyen tom.l.nguyen@intel.com 11/03/2004 +:Copyright: |copy| 2004 Intel Corporation + +About this guide +================ This guide describes the basics of the PCI Express Port Bus driver and provides information on how to enable the service drivers to register/unregister with the PCI Express Port Bus Driver. -2. Copyright 2004 Intel Corporation -3. What is the PCI Express Port Bus Driver +What is the PCI Express Port Bus Driver +======================================= A PCI Express Port is a logical PCI-PCI Bridge structure. There are two types of PCI Express Port: the Root Port and the Switch @@ -30,7 +37,8 @@ support (AER), and virtual channel support (VC). These services may be handled by a single complex driver or be individually distributed and handled by corresponding service drivers. -4. Why use the PCI Express Port Bus Driver? +Why use the PCI Express Port Bus Driver? +======================================== In existing Linux kernels, the Linux Device Driver Model allows a physical device to be handled by only a single driver. The PCI @@ -51,28 +59,31 @@ PCI Express Ports and distributes all provided service requests to the corresponding service drivers as required. Some key advantages of using the PCI Express Port Bus driver are listed below: - - Allow multiple service drivers to run simultaneously on - a PCI-PCI Bridge Port device. + - Allow multiple service drivers to run simultaneously on + a PCI-PCI Bridge Port device. - - Allow service drivers implemented in an independent - staged approach. + - Allow service drivers implemented in an independent + staged approach. - - Allow one service driver to run on multiple PCI-PCI Bridge - Port devices. + - Allow one service driver to run on multiple PCI-PCI Bridge + Port devices. - - Manage and distribute resources of a PCI-PCI Bridge Port - device to requested service drivers. + - Manage and distribute resources of a PCI-PCI Bridge Port + device to requested service drivers. -5. Configuring the PCI Express Port Bus Driver vs. Service Drivers +Configuring the PCI Express Port Bus Driver vs. Service Drivers +=============================================================== -5.1 Including the PCI Express Port Bus Driver Support into the Kernel +Including the PCI Express Port Bus Driver Support into the Kernel +----------------------------------------------------------------- Including the PCI Express Port Bus driver depends on whether the PCI Express support is included in the kernel config. The kernel will automatically include the PCI Express Port Bus driver as a kernel driver when the PCI Express support is enabled in the kernel. -5.2 Enabling Service Driver Support +Enabling Service Driver Support +------------------------------- PCI device drivers are implemented based on Linux Device Driver Model. All service drivers are PCI device drivers. As discussed above, it is @@ -89,9 +100,11 @@ header file /include/linux/pcieport_if.h, before calling these APIs. Failure to do so will result an identity mismatch, which prevents the PCI Express Port Bus driver from loading a service driver. -5.2.1 pcie_port_service_register +pcie_port_service_register +~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: -int pcie_port_service_register(struct pcie_port_service_driver *new) + int pcie_port_service_register(struct pcie_port_service_driver *new) This API replaces the Linux Driver Model's pci_register_driver API. A service driver should always calls pcie_port_service_register at @@ -99,69 +112,76 @@ module init. Note that after service driver being loaded, calls such as pci_enable_device(dev) and pci_set_master(dev) are no longer necessary since these calls are executed by the PCI Port Bus driver. -5.2.2 pcie_port_service_unregister +pcie_port_service_unregister +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: -void pcie_port_service_unregister(struct pcie_port_service_driver *new) + void pcie_port_service_unregister(struct pcie_port_service_driver *new) pcie_port_service_unregister replaces the Linux Driver Model's pci_unregister_driver. It's always called by service driver when a module exits. -5.2.3 Sample Code +Sample Code +~~~~~~~~~~~ Below is sample service driver code to initialize the port service driver data structure. +:: -static struct pcie_port_service_id service_id[] = { { - .vendor = PCI_ANY_ID, - .device = PCI_ANY_ID, - .port_type = PCIE_RC_PORT, - .service_type = PCIE_PORT_SERVICE_AER, - }, { /* end: all zeroes */ } -}; + static struct pcie_port_service_id service_id[] = { { + .vendor = PCI_ANY_ID, + .device = PCI_ANY_ID, + .port_type = PCIE_RC_PORT, + .service_type = PCIE_PORT_SERVICE_AER, + }, { /* end: all zeroes */ } + }; -static struct pcie_port_service_driver root_aerdrv = { - .name = (char *)device_name, - .id_table = &service_id[0], + static struct pcie_port_service_driver root_aerdrv = { + .name = (char *)device_name, + .id_table = &service_id[0], - .probe = aerdrv_load, - .remove = aerdrv_unload, + .probe = aerdrv_load, + .remove = aerdrv_unload, - .suspend = aerdrv_suspend, - .resume = aerdrv_resume, -}; + .suspend = aerdrv_suspend, + .resume = aerdrv_resume, + }; Below is a sample code for registering/unregistering a service driver. +:: -static int __init aerdrv_service_init(void) -{ - int retval = 0; + static int __init aerdrv_service_init(void) + { + int retval = 0; - retval = pcie_port_service_register(&root_aerdrv); - if (!retval) { - /* - * FIX ME - */ - } - return retval; -} + retval = pcie_port_service_register(&root_aerdrv); + if (!retval) { + /* + * FIX ME + */ + } + return retval; + } -static void __exit aerdrv_service_exit(void) -{ - pcie_port_service_unregister(&root_aerdrv); -} + static void __exit aerdrv_service_exit(void) + { + pcie_port_service_unregister(&root_aerdrv); + } -module_init(aerdrv_service_init); -module_exit(aerdrv_service_exit); + module_init(aerdrv_service_init); + module_exit(aerdrv_service_exit); -6. Possible Resource Conflicts +Possible Resource Conflicts +=========================== Since all service drivers of a PCI-PCI Bridge Port device are allowed to run simultaneously, below lists a few of possible resource conflicts with proposed solutions. -6.1 MSI and MSI-X Vector Resource +MSI and MSI-X Vector Resource +----------------------------- Once MSI or MSI-X interrupts are enabled on a device, it stays in this mode until they are disabled again. Since service drivers of the same @@ -179,7 +199,8 @@ driver. Service drivers should use (struct pcie_device*)dev->irq to call request_irq/free_irq. In addition, the interrupt mode is stored in the field interrupt_mode of struct pcie_device. -6.3 PCI Memory/IO Mapped Regions +PCI Memory/IO Mapped Regions +---------------------------- Service drivers for PCI Express Power Management (PME), Advanced Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access @@ -188,7 +209,8 @@ registers accessed are independent of each other. This patch assumes that all service drivers will be well behaved and not overwrite other service driver's configuration settings. -6.4 PCI Config Registers +PCI Config Registers +-------------------- Each service driver runs its PCI config operations on its own capability structure except the PCI Express capability structure, in diff --git a/Documentation/accounting/cgroupstats.txt b/Documentation/accounting/cgroupstats.rst index d16a9849e60e..b9afc48f4ea2 100644 --- a/Documentation/accounting/cgroupstats.txt +++ b/Documentation/accounting/cgroupstats.rst @@ -1,3 +1,7 @@ +================== +Control Groupstats +================== + Control Groupstats is inspired by the discussion at http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263. @@ -19,9 +23,9 @@ about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this information will not be available. To extract cgroup statistics a utility very similar to getdelays.c -has been developed, the sample output of the utility is shown below +has been developed, the sample output of the utility is shown below:: -~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a" -sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0 -~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup" -sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2 + ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a" + sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0 + ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup" + sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2 diff --git a/Documentation/accounting/delay-accounting.txt b/Documentation/accounting/delay-accounting.rst index 042ea59b5853..7cc7f5852da0 100644 --- a/Documentation/accounting/delay-accounting.txt +++ b/Documentation/accounting/delay-accounting.rst @@ -1,5 +1,6 @@ +================ Delay accounting ----------------- +================ Tasks encounter delays in execution when they wait for some kernel resource to become available e.g. a @@ -39,7 +40,9 @@ in detail in a separate document in this directory. Taskstats returns a generic data structure to userspace corresponding to per-pid and per-tgid statistics. The delay accounting functionality populates specific fields of this structure. See + include/linux/taskstats.h + for a description of the fields pertaining to delay accounting. It will generally be in the form of counters returning the cumulative delay seen for cpu, sync block I/O, swapin, memory reclaim etc. @@ -61,13 +64,16 @@ also serves as an example of using the taskstats interface. Usage ----- -Compile the kernel with +Compile the kernel with:: + CONFIG_TASK_DELAY_ACCT=y CONFIG_TASKSTATS=y Delay accounting is enabled by default at boot up. -To disable, add +To disable, add:: + nodelayacct + to the kernel boot options. The rest of the instructions below assume this has not been done. @@ -78,40 +84,43 @@ The utility also allows a given command to be executed and the corresponding delays to be seen. -General format of the getdelays command +General format of the getdelays command:: -getdelays [-t tgid] [-p pid] [-c cmd...] + getdelays [-t tgid] [-p pid] [-c cmd...] -Get delays, since system boot, for pid 10 -# ./getdelays -p 10 -(output similar to next case) +Get delays, since system boot, for pid 10:: -Get sum of delays, since system boot, for all pids with tgid 5 -# ./getdelays -t 5 + # ./getdelays -p 10 + (output similar to next case) +Get sum of delays, since system boot, for all pids with tgid 5:: -CPU count real total virtual total delay total - 7876 92005750 100000000 24001500 -IO count delay total - 0 0 -SWAP count delay total - 0 0 -RECLAIM count delay total - 0 0 + # ./getdelays -t 5 + + + CPU count real total virtual total delay total + 7876 92005750 100000000 24001500 + IO count delay total + 0 0 + SWAP count delay total + 0 0 + RECLAIM count delay total + 0 0 + +Get delays seen in executing a given simple command:: -Get delays seen in executing a given simple command -# ./getdelays -c ls / + # ./getdelays -c ls / -bin data1 data3 data5 dev home media opt root srv sys usr -boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var + bin data1 data3 data5 dev home media opt root srv sys usr + boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var -CPU count real total virtual total delay total + CPU count real total virtual total delay total 6 4000250 4000000 0 -IO count delay total + IO count delay total 0 0 -SWAP count delay total + SWAP count delay total 0 0 -RECLAIM count delay total + RECLAIM count delay total 0 0 diff --git a/Documentation/accounting/index.rst b/Documentation/accounting/index.rst new file mode 100644 index 000000000000..9369d8bf32be --- /dev/null +++ b/Documentation/accounting/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +Accounting +========== + +.. toctree:: + :maxdepth: 1 + + cgroupstats + delay-accounting + psi + taskstats + taskstats-struct diff --git a/Documentation/accounting/psi.txt b/Documentation/accounting/psi.rst index 5cbe5659e3b7..621111ce5740 100644 --- a/Documentation/accounting/psi.txt +++ b/Documentation/accounting/psi.rst @@ -35,14 +35,14 @@ Pressure interface Pressure information for each resource is exported through the respective file in /proc/pressure/ -- cpu, memory, and io. -The format for CPU is as such: +The format for CPU is as such:: -some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 -and for memory and IO: +and for memory and IO:: -some avg10=0.00 avg60=0.00 avg300=0.00 total=0 -full avg10=0.00 avg60=0.00 avg300=0.00 total=0 + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + full avg10=0.00 avg60=0.00 avg300=0.00 total=0 The "some" line indicates the share of time in which at least some tasks are stalled on a given resource. @@ -77,9 +77,9 @@ To register a trigger user has to open psi interface file under /proc/pressure/ representing the resource to be monitored and write the desired threshold and time window. The open file descriptor should be used to wait for trigger events using select(), poll() or epoll(). -The following format is used: +The following format is used:: -<some|full> <stall amount in us> <time window in us> + <some|full> <stall amount in us> <time window in us> For example writing "some 150000 1000000" into /proc/pressure/memory would add 150ms threshold for partial memory stall measured within @@ -115,18 +115,20 @@ trigger is closed. Userspace monitor usage example =============================== -#include <errno.h> -#include <fcntl.h> -#include <stdio.h> -#include <poll.h> -#include <string.h> -#include <unistd.h> - -/* - * Monitor memory partial stall with 1s tracking window size - * and 150ms threshold. - */ -int main() { +:: + + #include <errno.h> + #include <fcntl.h> + #include <stdio.h> + #include <poll.h> + #include <string.h> + #include <unistd.h> + + /* + * Monitor memory partial stall with 1s tracking window size + * and 150ms threshold. + */ + int main() { const char trig[] = "some 150000 1000000"; struct pollfd fds; int n; @@ -165,7 +167,7 @@ int main() { } return 0; -} + } Cgroup2 interface ================= diff --git a/Documentation/accounting/taskstats-struct.txt b/Documentation/accounting/taskstats-struct.rst index e7512c061c15..ca90fd489c9a 100644 --- a/Documentation/accounting/taskstats-struct.txt +++ b/Documentation/accounting/taskstats-struct.rst @@ -1,5 +1,6 @@ +==================== The struct taskstats --------------------- +==================== This document contains an explanation of the struct taskstats fields. @@ -10,16 +11,24 @@ There are three different groups of fields in the struct taskstats: the common fields and basic accounting fields are collected for delivery at do_exit() of a task. 2) Delay accounting fields - These fields are placed between - /* Delay accounting fields start */ - and - /* Delay accounting fields end */ + These fields are placed between:: + + /* Delay accounting fields start */ + + and:: + + /* Delay accounting fields end */ + Their values are collected if CONFIG_TASK_DELAY_ACCT is set. 3) Extended accounting fields - These fields are placed between - /* Extended accounting fields start */ - and - /* Extended accounting fields end */ + These fields are placed between:: + + /* Extended accounting fields start */ + + and:: + + /* Extended accounting fields end */ + Their values are collected if CONFIG_TASK_XACCT is set. 4) Per-task and per-thread context switch count statistics @@ -31,31 +40,33 @@ There are three different groups of fields in the struct taskstats: Future extension should add fields to the end of the taskstats struct, and should not change the relative position of each field within the struct. +:: -struct taskstats { + struct taskstats { + +1) Common and basic accounting fields:: -1) Common and basic accounting fields: /* The version number of this struct. This field is always set to * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>. * Each time the struct is changed, the value should be incremented. */ __u16 version; - /* The exit code of a task. */ + /* The exit code of a task. */ __u32 ac_exitcode; /* Exit status */ - /* The accounting flags of a task as defined in <linux/acct.h> + /* The accounting flags of a task as defined in <linux/acct.h> * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG. */ __u8 ac_flag; /* Record flags */ - /* The value of task_nice() of a task. */ + /* The value of task_nice() of a task. */ __u8 ac_nice; /* task_nice */ - /* The name of the command that started this task. */ + /* The name of the command that started this task. */ char ac_comm[TS_COMM_LEN]; /* Command name */ - /* The scheduling discipline as set in task->policy field. */ + /* The scheduling discipline as set in task->policy field. */ __u8 ac_sched; /* Scheduling discipline */ __u8 ac_pad[3]; @@ -64,26 +75,27 @@ struct taskstats { __u32 ac_pid; /* Process ID */ __u32 ac_ppid; /* Parent process ID */ - /* The time when a task begins, in [secs] since 1970. */ + /* The time when a task begins, in [secs] since 1970. */ __u32 ac_btime; /* Begin time [sec since 1970] */ - /* The elapsed time of a task, in [usec]. */ + /* The elapsed time of a task, in [usec]. */ __u64 ac_etime; /* Elapsed time [usec] */ - /* The user CPU time of a task, in [usec]. */ + /* The user CPU time of a task, in [usec]. */ __u64 ac_utime; /* User CPU time [usec] */ - /* The system CPU time of a task, in [usec]. */ + /* The system CPU time of a task, in [usec]. */ __u64 ac_stime; /* System CPU time [usec] */ - /* The minor page fault count of a task, as set in task->min_flt. */ + /* The minor page fault count of a task, as set in task->min_flt. */ __u64 ac_minflt; /* Minor Page Fault Count */ /* The major page fault count of a task, as set in task->maj_flt. */ __u64 ac_majflt; /* Major Page Fault Count */ -2) Delay accounting fields: +2) Delay accounting fields:: + /* Delay accounting fields start * * All values, until the comment "Delay accounting fields end" are @@ -134,7 +146,8 @@ struct taskstats { /* version 1 ends here */ -3) Extended accounting fields +3) Extended accounting fields:: + /* Extended accounting fields start */ /* Accumulated RSS usage in duration of a task, in MBytes-usecs. @@ -145,15 +158,15 @@ struct taskstats { */ __u64 coremem; /* accumulated RSS usage in MB-usec */ - /* Accumulated virtual memory usage in duration of a task. + /* Accumulated virtual memory usage in duration of a task. * Same as acct_rss_mem1 above except that we keep track of VM usage. */ __u64 virtmem; /* accumulated VM usage in MB-usec */ - /* High watermark of RSS usage in duration of a task, in KBytes. */ + /* High watermark of RSS usage in duration of a task, in KBytes. */ __u64 hiwater_rss; /* High-watermark of RSS usage */ - /* High watermark of VM usage in duration of a task, in KBytes. */ + /* High watermark of VM usage in duration of a task, in KBytes. */ __u64 hiwater_vm; /* High-water virtual memory usage */ /* The following four fields are I/O statistics of a task. */ @@ -164,17 +177,23 @@ struct taskstats { /* Extended accounting fields end */ -4) Per-task and per-thread statistics +4) Per-task and per-thread statistics:: + __u64 nvcsw; /* Context voluntary switch counter */ __u64 nivcsw; /* Context involuntary switch counter */ -5) Time accounting for SMT machines +5) Time accounting for SMT machines:: + __u64 ac_utimescaled; /* utime scaled on frequency etc */ __u64 ac_stimescaled; /* stime scaled on frequency etc */ __u64 cpu_scaled_run_real_total; /* scaled cpu_run_real_total */ -6) Extended delay accounting fields for memory reclaim +6) Extended delay accounting fields for memory reclaim:: + /* Delay waiting for memory reclaim */ __u64 freepages_count; __u64 freepages_delay_total; -} + +:: + + } diff --git a/Documentation/accounting/taskstats.txt b/Documentation/accounting/taskstats.rst index ff06b738bb88..2a28b7f55c10 100644 --- a/Documentation/accounting/taskstats.txt +++ b/Documentation/accounting/taskstats.rst @@ -1,5 +1,6 @@ +============================= Per-task statistics interface ------------------------------ +============================= Taskstats is a netlink-based interface for sending per-task and @@ -65,7 +66,7 @@ taskstats.h file. The data exchanged between user and kernel space is a netlink message belonging to the NETLINK_GENERIC family and using the netlink attributes interface. -The messages are in the format +The messages are in the format:: +----------+- - -+-------------+-------------------+ | nlmsghdr | Pad | genlmsghdr | taskstats payload | @@ -167,15 +168,13 @@ extended and the number of cpus grows large. To avoid losing statistics, userspace should do one or more of the following: - increase the receive buffer sizes for the netlink sockets opened by -listeners to receive exit data. + listeners to receive exit data. - create more listeners and reduce the number of cpus being listened to by -each listener. In the extreme case, there could be one listener for each cpu. -Users may also consider setting the cpu affinity of the listener to the subset -of cpus to which it listens, especially if they are listening to just one cpu. + each listener. In the extreme case, there could be one listener for each cpu. + Users may also consider setting the cpu affinity of the listener to the subset + of cpus to which it listens, especially if they are listening to just one cpu. Despite these measures, if the userspace receives ENOBUFS error messages indicated overflow of receive buffers, it should take measures to handle the loss of data. - ----- diff --git a/Documentation/aoe/aoe.rst b/Documentation/admin-guide/aoe/aoe.rst index 58747ecec71d..a05e751363a0 100644 --- a/Documentation/aoe/aoe.rst +++ b/Documentation/admin-guide/aoe/aoe.rst @@ -20,7 +20,7 @@ driver. The aoetools are on sourceforge. http://aoetools.sourceforge.net/ -The scripts in this Documentation/aoe directory are intended to +The scripts in this Documentation/admin-guide/aoe directory are intended to document the use of the driver and are not necessary if you install the aoetools. @@ -86,7 +86,7 @@ Using sysfs a convenient way. Users with aoetools should use the aoe-stat command:: - root@makki root# sh Documentation/aoe/status.sh + root@makki root# sh Documentation/admin-guide/aoe/status.sh e10.0 eth3 up e10.1 eth3 up e10.2 eth3 up diff --git a/Documentation/aoe/autoload.sh b/Documentation/admin-guide/aoe/autoload.sh index 815dff4691c9..815dff4691c9 100644 --- a/Documentation/aoe/autoload.sh +++ b/Documentation/admin-guide/aoe/autoload.sh diff --git a/Documentation/aoe/examples.rst b/Documentation/admin-guide/aoe/examples.rst index 91f3198e52c1..91f3198e52c1 100644 --- a/Documentation/aoe/examples.rst +++ b/Documentation/admin-guide/aoe/examples.rst diff --git a/Documentation/aoe/index.rst b/Documentation/admin-guide/aoe/index.rst index 4394b9b7913c..d71c5df15922 100644 --- a/Documentation/aoe/index.rst +++ b/Documentation/admin-guide/aoe/index.rst @@ -1,5 +1,3 @@ -:orphan: - ======================= ATA over Ethernet (AoE) ======================= diff --git a/Documentation/aoe/status.sh b/Documentation/admin-guide/aoe/status.sh index eeec7baae57a..eeec7baae57a 100644 --- a/Documentation/aoe/status.sh +++ b/Documentation/admin-guide/aoe/status.sh diff --git a/Documentation/aoe/todo.rst b/Documentation/admin-guide/aoe/todo.rst index dea8db5a33e1..dea8db5a33e1 100644 --- a/Documentation/aoe/todo.rst +++ b/Documentation/admin-guide/aoe/todo.rst diff --git a/Documentation/aoe/udev-install.sh b/Documentation/admin-guide/aoe/udev-install.sh index 15e86f58c036..15e86f58c036 100644 --- a/Documentation/aoe/udev-install.sh +++ b/Documentation/admin-guide/aoe/udev-install.sh diff --git a/Documentation/aoe/udev.txt b/Documentation/admin-guide/aoe/udev.txt index 54feda5a0772..5fb756466bc7 100644 --- a/Documentation/aoe/udev.txt +++ b/Documentation/admin-guide/aoe/udev.txt @@ -11,7 +11,7 @@ # udev_rules="/etc/udev/rules.d/" # bash# ls /etc/udev/rules.d/ # 10-wacom.rules 50-udev.rules -# bash# cp /path/to/linux/Documentation/aoe/udev.txt \ +# bash# cp /path/to/linux/Documentation/admin-guide/aoe/udev.txt \ # /etc/udev/rules.d/60-aoe.rules # diff --git a/Documentation/blockdev/drbd/DRBD-8.3-data-packets.svg b/Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg index f87cfa0dc2fb..f87cfa0dc2fb 100644 --- a/Documentation/blockdev/drbd/DRBD-8.3-data-packets.svg +++ b/Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg diff --git a/Documentation/blockdev/drbd/DRBD-data-packets.svg b/Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg index 48a1e2165fec..48a1e2165fec 100644 --- a/Documentation/blockdev/drbd/DRBD-data-packets.svg +++ b/Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg diff --git a/Documentation/blockdev/drbd/conn-states-8.dot b/Documentation/admin-guide/blockdev/drbd/conn-states-8.dot index 025e8cf5e64a..025e8cf5e64a 100644 --- a/Documentation/blockdev/drbd/conn-states-8.dot +++ b/Documentation/admin-guide/blockdev/drbd/conn-states-8.dot diff --git a/Documentation/blockdev/drbd/data-structure-v9.txt b/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst index 1e52a0e32624..66036b901644 100644 --- a/Documentation/blockdev/drbd/data-structure-v9.txt +++ b/Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst @@ -1,3 +1,7 @@ +================================ +kernel data structure for DRBD-9 +================================ + This describes the in kernel data structure for DRBD-9. Starting with Linux v3.14 we are reorganizing DRBD to use this data structure. @@ -10,7 +14,7 @@ device is represented by a block device locally. The DRBD objects are interconnected to form a matrix as depicted below; a drbd_peer_device object sits at each intersection between a drbd_device and a -drbd_connection: +drbd_connection:: /--------------+---------------+.....+---------------\ | resource | device | | device | diff --git a/Documentation/blockdev/drbd/disk-states-8.dot b/Documentation/admin-guide/blockdev/drbd/disk-states-8.dot index d06cfb46fb98..d06cfb46fb98 100644 --- a/Documentation/blockdev/drbd/disk-states-8.dot +++ b/Documentation/admin-guide/blockdev/drbd/disk-states-8.dot diff --git a/Documentation/blockdev/drbd/drbd-connection-state-overview.dot b/Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot index 6d9cf0a7b11d..6d9cf0a7b11d 100644 --- a/Documentation/blockdev/drbd/drbd-connection-state-overview.dot +++ b/Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot diff --git a/Documentation/admin-guide/blockdev/drbd/figures.rst b/Documentation/admin-guide/blockdev/drbd/figures.rst new file mode 100644 index 000000000000..bd9a4901fe46 --- /dev/null +++ b/Documentation/admin-guide/blockdev/drbd/figures.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. The here included files are intended to help understand the implementation + +Data flows that Relate some functions, and write packets +======================================================== + +.. kernel-figure:: DRBD-8.3-data-packets.svg + :alt: DRBD-8.3-data-packets.svg + :align: center + +.. kernel-figure:: DRBD-data-packets.svg + :alt: DRBD-data-packets.svg + :align: center + + +Sub graphs of DRBD's state transitions +====================================== + +.. kernel-figure:: conn-states-8.dot + :alt: conn-states-8.dot + :align: center + +.. kernel-figure:: disk-states-8.dot + :alt: disk-states-8.dot + :align: center + +.. kernel-figure:: node-states-8.dot + :alt: node-states-8.dot + :align: center diff --git a/Documentation/blockdev/drbd/README.txt b/Documentation/admin-guide/blockdev/drbd/index.rst index 627b0a1bf35e..68ecd5c113e9 100644 --- a/Documentation/blockdev/drbd/README.txt +++ b/Documentation/admin-guide/blockdev/drbd/index.rst @@ -1,4 +1,9 @@ +========================================== +Distributed Replicated Block Device - DRBD +========================================== + Description +=========== DRBD is a shared-nothing, synchronously replicated block device. It is designed to serve as a building block for high availability @@ -7,10 +12,8 @@ Description Please visit http://www.drbd.org to find out more. -The here included files are intended to help understand the implementation - -DRBD-8.3-data-packets.svg, DRBD-data-packets.svg - relates some functions, and write packets. +.. toctree:: + :maxdepth: 1 -conn-states-8.dot, disk-states-8.dot, node-states-8.dot - The sub graphs of DRBD's state transitions + data-structure-v9 + figures diff --git a/Documentation/blockdev/drbd/node-states-8.dot b/Documentation/admin-guide/blockdev/drbd/node-states-8.dot index 4a2b00c23547..bfa54e1f8016 100644 --- a/Documentation/blockdev/drbd/node-states-8.dot +++ b/Documentation/admin-guide/blockdev/drbd/node-states-8.dot @@ -11,4 +11,3 @@ digraph peer_states { Unknown -> Primary [ label = "connected" ] Unknown -> Secondary [ label = "connected" ] } - diff --git a/Documentation/blockdev/floppy.txt b/Documentation/admin-guide/blockdev/floppy.rst index e2240f5ab64d..4a8f31cf4139 100644 --- a/Documentation/blockdev/floppy.txt +++ b/Documentation/admin-guide/blockdev/floppy.rst @@ -1,35 +1,37 @@ -This file describes the floppy driver. +============= +Floppy Driver +============= FAQ list: ========= - A FAQ list may be found in the fdutils package (see below), and also +A FAQ list may be found in the fdutils package (see below), and also at <http://fdutils.linux.lu/faq.html>. LILO configuration options (Thinkpad users, read this) ====================================================== - The floppy driver is configured using the 'floppy=' option in +The floppy driver is configured using the 'floppy=' option in lilo. This option can be typed at the boot prompt, or entered in the lilo configuration file. - Example: If your kernel is called linux-2.6.9, type the following line -at the lilo boot prompt (if you have a thinkpad): +Example: If your kernel is called linux-2.6.9, type the following line +at the lilo boot prompt (if you have a thinkpad):: linux-2.6.9 floppy=thinkpad You may also enter the following line in /etc/lilo.conf, in the description -of linux-2.6.9: +of linux-2.6.9:: append = "floppy=thinkpad" - Several floppy related options may be given, example: +Several floppy related options may be given, example:: linux-2.6.9 floppy=daring floppy=two_fdc append = "floppy=daring floppy=two_fdc" - If you give options both in the lilo config file and on the boot +If you give options both in the lilo config file and on the boot prompt, the option strings of both places are concatenated, the boot prompt options coming last. That's why there are also options to restore the default behavior. @@ -38,21 +40,23 @@ restore the default behavior. Module configuration options ============================ - If you use the floppy driver as a module, use the following syntax: -modprobe floppy floppy="<options>" +If you use the floppy driver as a module, use the following syntax:: -Example: - modprobe floppy floppy="omnibook messages" + modprobe floppy floppy="<options>" - If you need certain options enabled every time you load the floppy driver, -you can put: +Example:: - options floppy floppy="omnibook messages" + modprobe floppy floppy="omnibook messages" + +If you need certain options enabled every time you load the floppy driver, +you can put:: + + options floppy floppy="omnibook messages" in a configuration file in /etc/modprobe.d/. - The floppy driver related options are: +The floppy driver related options are: floppy=asus_pci Sets the bit mask to allow only units 0 and 1. (default) @@ -70,8 +74,7 @@ in a configuration file in /etc/modprobe.d/. Tells the floppy driver that you have only one floppy controller. (default) - floppy=two_fdc - floppy=<address>,two_fdc + floppy=two_fdc / floppy=<address>,two_fdc Tells the floppy driver that you have two floppy controllers. The second floppy controller is assumed to be at <address>. This option is not needed if the second controller is at address @@ -84,8 +87,7 @@ in a configuration file in /etc/modprobe.d/. floppy=0,thinkpad Tells the floppy driver that you don't have a Thinkpad. - floppy=omnibook - floppy=nodma + floppy=omnibook / floppy=nodma Tells the floppy driver not to use Dma for data transfers. This is needed on HP Omnibooks, which don't have a workable DMA channel for the floppy driver. This option is also useful @@ -144,14 +146,16 @@ in a configuration file in /etc/modprobe.d/. described in the physical CMOS), or if your BIOS uses non-standard CMOS types. The CMOS types are: - 0 - Use the value of the physical CMOS - 1 - 5 1/4 DD - 2 - 5 1/4 HD - 3 - 3 1/2 DD - 4 - 3 1/2 HD - 5 - 3 1/2 ED - 6 - 3 1/2 ED - 16 - unknown or not installed + == ================================== + 0 Use the value of the physical CMOS + 1 5 1/4 DD + 2 5 1/4 HD + 3 3 1/2 DD + 4 3 1/2 HD + 5 3 1/2 ED + 6 3 1/2 ED + 16 unknown or not installed + == ================================== (Note: there are two valid types for ED drives. This is because 5 was initially chosen to represent floppy *tapes*, and 6 for ED drives. @@ -162,8 +166,7 @@ in a configuration file in /etc/modprobe.d/. Print a warning message when an unexpected interrupt is received. (default) - floppy=no_unexpected_interrupts - floppy=L40SX + floppy=no_unexpected_interrupts / floppy=L40SX Don't print a message when an unexpected interrupt is received. This is needed on IBM L40SX laptops in certain video modes. (There seems to be an interaction between video and floppy. The unexpected @@ -199,47 +202,54 @@ in a configuration file in /etc/modprobe.d/. Sets the floppy DMA channel to <nr> instead of 2. floppy=slow - Use PS/2 stepping rate: - " PS/2 floppies have much slower step rates than regular floppies. + Use PS/2 stepping rate:: + + PS/2 floppies have much slower step rates than regular floppies. It's been recommended that take about 1/4 of the default speed - in some more extreme cases." + in some more extreme cases. Supporting utilities and additional documentation: ================================================== - Additional parameters of the floppy driver can be configured at +Additional parameters of the floppy driver can be configured at runtime. Utilities which do this can be found in the fdutils package. This package also contains a new version of mtools which allows to access high capacity disks (up to 1992K on a high density 3 1/2 disk!). It also contains additional documentation about the floppy driver. The latest version can be found at fdutils homepage: + http://fdutils.linux.lu The fdutils releases can be found at: + http://fdutils.linux.lu/download.html + http://www.tux.org/pub/knaff/fdutils/ + ftp://metalab.unc.edu/pub/Linux/utils/disk-management/ Reporting problems about the floppy driver ========================================== - If you have a question or a bug report about the floppy driver, mail +If you have a question or a bug report about the floppy driver, mail me at Alain.Knaff@poboxes.com . If you post to Usenet, preferably use comp.os.linux.hardware. As the volume in these groups is rather high, be sure to include the word "floppy" (or "FLOPPY") in the subject line. If the reported problem happens when mounting floppy disks, be sure to mention also the type of the filesystem in the subject line. - Be sure to read the FAQ before mailing/posting any bug reports! +Be sure to read the FAQ before mailing/posting any bug reports! - Alain +Alain Changelog ========= -10-30-2004 : Cleanup, updating, add reference to module configuration. +10-30-2004 : + Cleanup, updating, add reference to module configuration. James Nelson <james4765@gmail.com> -6-3-2000 : Original Document +6-3-2000 : + Original Document diff --git a/Documentation/admin-guide/blockdev/index.rst b/Documentation/admin-guide/blockdev/index.rst new file mode 100644 index 000000000000..b903cf152091 --- /dev/null +++ b/Documentation/admin-guide/blockdev/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +The Linux RapidIO Subsystem +=========================== + +.. toctree:: + :maxdepth: 1 + + floppy + nbd + paride + ramdisk + zram + + drbd/index diff --git a/Documentation/blockdev/nbd.txt b/Documentation/admin-guide/blockdev/nbd.rst index db242ea2bce8..d78dfe559dcf 100644 --- a/Documentation/blockdev/nbd.txt +++ b/Documentation/admin-guide/blockdev/nbd.rst @@ -1,3 +1,4 @@ +================================== Network Block Device (TCP version) ================================== @@ -28,4 +29,3 @@ max_part nbds_max Number of block devices that should be initialized (default: 16). - diff --git a/Documentation/blockdev/paride.txt b/Documentation/admin-guide/blockdev/paride.rst index ee6717e3771d..87b4278bf314 100644 --- a/Documentation/blockdev/paride.txt +++ b/Documentation/admin-guide/blockdev/paride.rst @@ -1,15 +1,17 @@ - - Linux and parallel port IDE devices +=================================== +Linux and parallel port IDE devices +=================================== PARIDE v1.03 (c) 1997-8 Grant Guenther <grant@torque.net> 1. Introduction +=============== Owing to the simplicity and near universality of the parallel port interface to personal computers, many external devices such as portable hard-disk, CD-ROM, LS-120 and tape drives use the parallel port to connect to their host computer. While some devices (notably scanners) use ad-hoc methods -to pass commands and data through the parallel port interface, most +to pass commands and data through the parallel port interface, most external devices are actually identical to an internal model, but with a parallel-port adapter chip added in. Some of the original parallel port adapters were little more than mechanisms for multiplexing a SCSI bus. @@ -28,47 +30,50 @@ were to open up a parallel port CD-ROM drive, for instance, one would find a standard ATAPI CD-ROM drive, a power supply, and a single adapter that interconnected a standard PC parallel port cable and a standard IDE cable. It is usually possible to exchange the CD-ROM device with -any other device using the IDE interface. +any other device using the IDE interface. The document describes the support in Linux for parallel port IDE devices. It does not cover parallel port SCSI devices, "ditto" tape -drives or scanners. Many different devices are supported by the +drives or scanners. Many different devices are supported by the parallel port IDE subsystem, including: - MicroSolutions backpack CD-ROM - MicroSolutions backpack PD/CD - MicroSolutions backpack hard-drives - MicroSolutions backpack 8000t tape drive - SyQuest EZ-135, EZ-230 & SparQ drives - Avatar Shark - Imation Superdisk LS-120 - Maxell Superdisk LS-120 - FreeCom Power CD - Hewlett-Packard 5GB and 8GB tape drives - Hewlett-Packard 7100 and 7200 CD-RW drives + - MicroSolutions backpack CD-ROM + - MicroSolutions backpack PD/CD + - MicroSolutions backpack hard-drives + - MicroSolutions backpack 8000t tape drive + - SyQuest EZ-135, EZ-230 & SparQ drives + - Avatar Shark + - Imation Superdisk LS-120 + - Maxell Superdisk LS-120 + - FreeCom Power CD + - Hewlett-Packard 5GB and 8GB tape drives + - Hewlett-Packard 7100 and 7200 CD-RW drives as well as most of the clone and no-name products on the market. To support such a wide range of devices, PARIDE, the parallel port IDE subsystem, is actually structured in three parts. There is a base paride module which provides a registry and some common methods for -accessing the parallel ports. The second component is a set of -high-level drivers for each of the different types of supported devices: +accessing the parallel ports. The second component is a set of +high-level drivers for each of the different types of supported devices: + === ============= pd IDE disk pcd ATAPI CD-ROM pf ATAPI disk pt ATAPI tape pg ATAPI generic + === ============= (Currently, the pg driver is only used with CD-R drives). The high-level drivers function according to the relevant standards. The third component of PARIDE is a set of low-level protocol drivers for each of the parallel port IDE adapter chips. Thanks to the interest -and encouragement of Linux users from many parts of the world, +and encouragement of Linux users from many parts of the world, support is available for almost all known adapter protocols: + ==== ====================================== ==== aten ATEN EH-100 (HK) bpck Microsolutions backpack (US) comm DataStor (old-type) "commuter" adapter (TW) @@ -83,9 +88,11 @@ support is available for almost all known adapter protocols: ktti KT Technology PHd adapter (SG) on20 OnSpec 90c20 (US) on26 OnSpec 90c26 (US) + ==== ====================================== ==== 2. Using the PARIDE subsystem +============================= While configuring the Linux kernel, you may choose either to build the PARIDE drivers into your kernel, or to build them as modules. @@ -94,10 +101,10 @@ In either case, you will need to select "Parallel port IDE device support" as well as at least one of the high-level drivers and at least one of the parallel port communication protocols. If you do not know what kind of parallel port adapter is used in your drive, you could -begin by checking the file names and any text files on your DOS +begin by checking the file names and any text files on your DOS installation floppy. Alternatively, you can look at the markings on the adapter chip itself. That's usually sufficient to identify the -correct device. +correct device. You can actually select all the protocol modules, and allow the PARIDE subsystem to try them all for you. @@ -105,8 +112,9 @@ subsystem to try them all for you. For the "brand-name" products listed above, here are the protocol and high-level drivers that you would use: + ================ ============ ====== ======== Manufacturer Model Driver Protocol - + ================ ============ ====== ======== MicroSolutions CD-ROM pcd bpck MicroSolutions PD drive pf bpck MicroSolutions hard-drive pd bpck @@ -119,8 +127,10 @@ and high-level drivers that you would use: Hewlett-Packard 5GB Tape pt epat Hewlett-Packard 7200e (CD) pcd epat Hewlett-Packard 7200e (CD-R) pg epat + ================ ============ ====== ======== 2.1 Configuring built-in drivers +--------------------------------- We recommend that you get to know how the drivers work and how to configure them as loadable modules, before attempting to compile a @@ -143,7 +153,7 @@ protocol identification number and, for some devices, the drive's chain ID. While your system is booting, a number of messages are displayed on the console. Like all such messages, they can be reviewed with the 'dmesg' command. Among those messages will be -some lines like: +some lines like:: paride: bpck registered as protocol 0 paride: epat registered as protocol 1 @@ -158,10 +168,10 @@ the last two digits of the drive's serial number (but read MicroSolutions' documentation about this). As an example, let's assume that you have a MicroSolutions PD/CD drive -with unit ID number 36 connected to the parallel port at 0x378, a SyQuest -EZ-135 connected to the chained port on the PD/CD drive and also an -Imation Superdisk connected to port 0x278. You could give the following -options on your boot command: +with unit ID number 36 connected to the parallel port at 0x378, a SyQuest +EZ-135 connected to the chained port on the PD/CD drive and also an +Imation Superdisk connected to port 0x278. You could give the following +options on your boot command:: pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36 @@ -169,24 +179,27 @@ In the last option, pf.drive1 configures device /dev/pf1, the 0x378 is the parallel port base address, the 0 is the protocol registration number and 36 is the chain ID. -Please note: while PARIDE will work both with and without the +Please note: while PARIDE will work both with and without the PARPORT parallel port sharing system that is included by the "Parallel port support" option, PARPORT must be included and enabled if you want to use chains of devices on the same parallel port. 2.2 Loading and configuring PARIDE as modules +---------------------------------------------- It is much faster and simpler to get to understand the PARIDE drivers -if you use them as loadable kernel modules. +if you use them as loadable kernel modules. -Note 1: using these drivers with the "kerneld" automatic module loading -system is not recommended for beginners, and is not documented here. +Note 1: + using these drivers with the "kerneld" automatic module loading + system is not recommended for beginners, and is not documented here. -Note 2: if you build PARPORT support as a loadable module, PARIDE must -also be built as loadable modules, and PARPORT must be loaded before the -PARIDE modules. +Note 2: + if you build PARPORT support as a loadable module, PARIDE must + also be built as loadable modules, and PARPORT must be loaded before + the PARIDE modules. -To use PARIDE, you must begin by +To use PARIDE, you must begin by:: insmod paride @@ -195,8 +208,8 @@ among other tasks. Then, load as many of the protocol modules as you think you might need. As you load each module, it will register the protocols that it supports, -and print a log message to your kernel log file and your console. For -example: +and print a log message to your kernel log file and your console. For +example:: # insmod epat paride: epat registered as protocol 0 @@ -205,22 +218,22 @@ example: paride: k971 registered as protocol 2 Finally, you can load high-level drivers for each kind of device that -you have connected. By default, each driver will autoprobe for a single +you have connected. By default, each driver will autoprobe for a single device, but you can support up to four similar devices by giving their individual co-ordinates when you load the driver. For example, if you had two no-name CD-ROM drives both using the KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc -you could give the following command: +you could give the following command:: # insmod pcd drive0=0x378,1 drive1=0x3bc,1 For most adapters, giving a port address and protocol number is sufficient, -but check the source files in linux/drivers/block/paride for more +but check the source files in linux/drivers/block/paride for more information. (Hopefully someone will write some man pages one day !). As another example, here's what happens when PARPORT is installed, and -a SyQuest EZ-135 is attached to port 0x378: +a SyQuest EZ-135 is attached to port 0x378:: # insmod paride paride: version 1.0 installed @@ -237,46 +250,47 @@ Note that the last line is the output from the generic partition table scanner - in this case it reports that it has found a disk with one partition. 2.3 Using a PARIDE device +-------------------------- Once the drivers have been loaded, you can access PARIDE devices in the same way as their traditional counterparts. You will probably need to create the device "special files". Here is a simple script that you can -cut to a file and execute: - -#!/bin/bash -# -# mkd -- a script to create the device special files for the PARIDE subsystem -# -function mkdev { - mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1 -} -# -function pd { - D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) ) - mkdev pd$D b 45 $[ $1 * 16 ] - for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 - do mkdev pd$D$P b 45 $[ $1 * 16 + $P ] - done -} -# -cd /dev -# -for u in 0 1 2 3 ; do pd $u ; done -for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done -for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done -for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done -for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done -for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done -# -# end of mkd +cut to a file and execute:: + + #!/bin/bash + # + # mkd -- a script to create the device special files for the PARIDE subsystem + # + function mkdev { + mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1 + } + # + function pd { + D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) ) + mkdev pd$D b 45 $[ $1 * 16 ] + for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 + do mkdev pd$D$P b 45 $[ $1 * 16 + $P ] + done + } + # + cd /dev + # + for u in 0 1 2 3 ; do pd $u ; done + for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done + for u in 0 1 2 3 ; do mkdev pf$u b 47 $u ; done + for u in 0 1 2 3 ; do mkdev pt$u c 96 $u ; done + for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done + for u in 0 1 2 3 ; do mkdev pg$u c 97 $u ; done + # + # end of mkd With the device files and drivers in place, you can access PARIDE devices -like any other Linux device. For example, to mount a CD-ROM in pcd0, use: +like any other Linux device. For example, to mount a CD-ROM in pcd0, use:: mount /dev/pcd0 /cdrom If you have a fresh Avatar Shark cartridge, and the drive is pda, you -might do something like: +might do something like:: fdisk /dev/pda -- make a new partition table with partition 1 of type 83 @@ -289,41 +303,46 @@ might do something like: Devices like the Imation superdisk work in the same way, except that they do not have a partition table. For example to make a 120MB -floppy that you could share with a DOS system: +floppy that you could share with a DOS system:: mkdosfs /dev/pf0 mount /dev/pf0 /mnt 2.4 The pf driver +------------------ The pf driver is intended for use with parallel port ATAPI disk devices. The most common devices in this category are PD drives and LS-120 drives. Traditionally, media for these devices are not partitioned. Consequently, the pf driver does not support partitioned -media. This may be changed in a future version of the driver. +media. This may be changed in a future version of the driver. 2.5 Using the pt driver +------------------------ The pt driver for parallel port ATAPI tape drives is a minimal driver. -It does not yet support many of the standard tape ioctl operations. +It does not yet support many of the standard tape ioctl operations. For best performance, a block size of 32KB should be used. You will probably want to set the parallel port delay to 0, if you can. 2.6 Using the pg driver +------------------------ The pg driver can be used in conjunction with the cdrecord program to create CD-ROMs. Please get cdrecord version 1.6.1 or later -from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media -your parallel port should ideally be set to EPP mode, and the "port delay" -should be set to 0. With those settings it is possible to record at 2x +from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ . To record CD-R media +your parallel port should ideally be set to EPP mode, and the "port delay" +should be set to 0. With those settings it is possible to record at 2x speed without any buffer underruns. If you cannot get the driver to work in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only. 3. Troubleshooting +================== 3.1 Use EPP mode if you can +---------------------------- The most common problems that people report with the PARIDE drivers concern the parallel port CMOS settings. At this time, none of the @@ -332,6 +351,7 @@ If you are able to do so, please set your parallel port into EPP mode using your CMOS setup procedure. 3.2 Check the port delay +------------------------- Some parallel ports cannot reliably transfer data at full speed. To offset the errors, the PARIDE protocol modules introduce a "port @@ -347,23 +367,25 @@ read the comments at the beginning of the driver source files in linux/drivers/block/paride. 3.3 Some drives need a printer reset +------------------------------------- There appear to be a number of "noname" external drives on the market that do not always power up correctly. We have noticed this with some drives based on OnSpec and older Freecom adapters. In these rare cases, the adapter can often be reinitialised by issuing a "printer reset" on -the parallel port. As the reset operation is potentially disruptive in -multiple device environments, the PARIDE drivers will not do it -automatically. You can however, force a printer reset by doing: +the parallel port. As the reset operation is potentially disruptive in +multiple device environments, the PARIDE drivers will not do it +automatically. You can however, force a printer reset by doing:: insmod lp reset=1 rmmod lp If you have one of these marginal cases, you should probably build your paride drivers as modules, and arrange to do the printer reset -before loading the PARIDE drivers. +before loading the PARIDE drivers. 3.4 Use the verbose option and dmesg if you need help +------------------------------------------------------ While a lot of testing has gone into these drivers to make them work as smoothly as possible, problems will arise. If you do have problems, @@ -373,7 +395,7 @@ clues, then please make sure that only one drive is hooked to your system, and that either (a) PARPORT is enabled or (b) no other device driver is using your parallel port (check in /proc/ioports). Then, load the appropriate drivers (you can load several protocol modules if you want) -as in: +as in:: # insmod paride # insmod epat @@ -394,12 +416,14 @@ by e-mail to grant@torque.net, or join the linux-parport mailing list and post your report there. 3.5 For more information or help +--------------------------------- You can join the linux-parport mailing list by sending a mail message -to +to: + linux-parport-request@torque.net -with the single word +with the single word:: subscribe @@ -412,6 +436,4 @@ have in your mail headers, when sending mail to the list server. You might also find some useful information on the linux-parport web pages (although they are not always up to date) at - http://web.archive.org/web/*/http://www.torque.net/parport/ - - + http://web.archive.org/web/%2E/http://www.torque.net/parport/ diff --git a/Documentation/blockdev/ramdisk.txt b/Documentation/admin-guide/blockdev/ramdisk.rst index 501e12e0323e..b7c2268f8dec 100644 --- a/Documentation/blockdev/ramdisk.txt +++ b/Documentation/admin-guide/blockdev/ramdisk.rst @@ -1,7 +1,8 @@ +========================================== Using the RAM disk block device with Linux ------------------------------------------- +========================================== -Contents: +.. Contents: 1) Overview 2) Kernel Command Line Parameters @@ -42,7 +43,7 @@ rescue floppy disk. 2a) Kernel Command Line Parameters ramdisk_size=N - ============== + Size of the ramdisk. This parameter tells the RAM disk driver to set up RAM disks of N k size. The default is 4096 (4 MB). @@ -50,16 +51,13 @@ default is 4096 (4 MB). 2b) Module parameters rd_nr - ===== - /dev/ramX devices created. + /dev/ramX devices created. max_part - ======== - Maximum partition number. + Maximum partition number. rd_size - ======= - See ramdisk_size. + See ramdisk_size. 3) Using "rdev -r" ------------------ @@ -71,11 +69,11 @@ to 2 MB (2^11) of where to find the RAM disk (this used to be the size). Bit prompt/wait sequence is to be given before trying to read the RAM disk. Since the RAM disk dynamically grows as data is being written into it, a size field is not required. Bits 11 to 13 are not currently used and may as well be zero. -These numbers are no magical secrets, as seen below: +These numbers are no magical secrets, as seen below:: -./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF -./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000 -./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000 + ./arch/x86/kernel/setup.c:#define RAMDISK_IMAGE_START_MASK 0x07FF + ./arch/x86/kernel/setup.c:#define RAMDISK_PROMPT_FLAG 0x8000 + ./arch/x86/kernel/setup.c:#define RAMDISK_LOAD_FLAG 0x4000 Consider a typical two floppy disk setup, where you will have the kernel on disk one, and have already put a RAM disk image onto disk #2. @@ -92,20 +90,23 @@ sequence so that you have a chance to switch floppy disks. The command line equivalent is: "prompt_ramdisk=1" Putting that together gives 2^15 + 2^14 + 0 = 49152 for an rdev word. -So to create disk one of the set, you would do: +So to create disk one of the set, you would do:: /usr/src/linux# cat arch/x86/boot/zImage > /dev/fd0 /usr/src/linux# rdev /dev/fd0 /dev/fd0 /usr/src/linux# rdev -r /dev/fd0 49152 -If you make a boot disk that has LILO, then for the above, you would use: +If you make a boot disk that has LILO, then for the above, you would use:: + append = "ramdisk_start=0 load_ramdisk=1 prompt_ramdisk=1" -Since the default start = 0 and the default prompt = 1, you could use: + +Since the default start = 0 and the default prompt = 1, you could use:: + append = "load_ramdisk=1" 4) An Example of Creating a Compressed RAM Disk ----------------------------------------------- +----------------------------------------------- To create a RAM disk image, you will need a spare block device to construct it on. This can be the RAM disk device itself, or an @@ -120,11 +121,11 @@ a) Decide on the RAM disk size that you want. Say 2 MB for this example. Create it by writing to the RAM disk device. (This step is not currently required, but may be in the future.) It is wise to zero out the area (esp. for disks) so that maximal compression is achieved for - the unused blocks of the image that you are about to create. + the unused blocks of the image that you are about to create:: dd if=/dev/zero of=/dev/ram0 bs=1k count=2048 -b) Make a filesystem on it. Say ext2fs for this example. +b) Make a filesystem on it. Say ext2fs for this example:: mke2fs -vm0 /dev/ram0 2048 @@ -133,11 +134,11 @@ c) Mount it, copy the files you want to it (eg: /etc/* /dev/* ...) d) Compress the contents of the RAM disk. The level of compression will be approximately 50% of the space used by the files. Unused - space on the RAM disk will compress to almost nothing. + space on the RAM disk will compress to almost nothing:: dd if=/dev/ram0 bs=1k count=2048 | gzip -v9 > /tmp/ram_image.gz -e) Put the kernel onto the floppy +e) Put the kernel onto the floppy:: dd if=zImage of=/dev/fd0 bs=1k @@ -146,13 +147,13 @@ f) Put the RAM disk image onto the floppy, after the kernel. Use an offset (possibly larger) kernel onto the same floppy later without overlapping the RAM disk image. An offset of 400 kB for kernels about 350 kB in size would be reasonable. Make sure offset+size of ram_image.gz is - not larger than the total space on your floppy (usually 1440 kB). + not larger than the total space on your floppy (usually 1440 kB):: dd if=/tmp/ram_image.gz of=/dev/fd0 bs=1k seek=400 g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc. For prompt_ramdisk=1, load_ramdisk=1, ramdisk_start=400, one would - have 2^15 + 2^14 + 400 = 49552. + have 2^15 + 2^14 + 400 = 49552:: rdev /dev/fd0 /dev/fd0 rdev -r /dev/fd0 49552 @@ -160,15 +161,17 @@ g) Use "rdev" to set the boot device, RAM disk offset, prompt flag, etc. That is it. You now have your boot/root compressed RAM disk floppy. Some users may wish to combine steps (d) and (f) by using a pipe. --------------------------------------------------------------------------- + Paul Gortmaker 12/95 Changelog: ---------- -10-22-04 : Updated to reflect changes in command line options, remove +10-22-04 : + Updated to reflect changes in command line options, remove obsolete references, general cleanup. James Nelson (james4765@gmail.com) -12-95 : Original Document +12-95 : + Original Document diff --git a/Documentation/blockdev/zram.txt b/Documentation/admin-guide/blockdev/zram.rst index 4df0ce271085..6eccf13219ff 100644 --- a/Documentation/blockdev/zram.txt +++ b/Documentation/admin-guide/blockdev/zram.rst @@ -1,7 +1,9 @@ +======================================== zram: Compressed RAM based block devices ----------------------------------------- +======================================== -* Introduction +Introduction +============ The zram module creates RAM based block devices named /dev/zram<id> (<id> = 0, 1, ...). Pages written to these disks are compressed and stored @@ -12,9 +14,11 @@ use as swap disks, various caches under /var and maybe many more :) Statistics for individual zram devices are exported through sysfs nodes at /sys/block/zram<id>/ -* Usage +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). @@ -22,7 +26,7 @@ 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 +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 @@ -30,19 +34,23 @@ 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. + +======== ============================================================= +-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: +and, in general case, something like:: echo 3 > /sys/block/zram0/max_comp_streams if [ $? -ne 0 ]; @@ -51,7 +59,11 @@ and, in general case, something like: should suffice. -1) Load Module: +1) Load Module +============== + +:: + modprobe zram num_devices=4 This creates 4 devices: /dev/zram{0,1,2,3} @@ -59,6 +71,8 @@ num_devices parameter is optional and tells zram how many devices should be pre-created. Default: 1. 2) Set max number of compression streams +======================================== + Regardless the value passed to this attribute, ZRAM will always allocate multiple compression streams - one per online CPUs - thus allowing several concurrent compression operations. The number of @@ -66,16 +80,20 @@ allocated compression streams goes down when some of the CPUs become offline. There is no single-compression-stream mode anymore, unless you are running a UP system or has only 1 CPU online. -To find out how many streams are currently available: +To find out how many streams are currently available:: + cat /sys/block/zram0/max_comp_streams 3) Select compression algorithm +=============================== + Using comp_algorithm device attribute one can see available and currently selected (shown in square brackets) compression algorithms, change selected compression algorithm (once the device is initialised there is no way to change compression algorithm). -Examples: +Examples:: + #show supported compression algorithms cat /sys/block/zram0/comp_algorithm lzo [lz4] @@ -83,20 +101,23 @@ Examples: #select lzo compression algorithm echo lzo > /sys/block/zram0/comp_algorithm -For the time being, the `comp_algorithm' content does not necessarily +For the time being, the `comp_algorithm` content does not necessarily show every compression algorithm supported by the kernel. We keep this list primarily to simplify device configuration and one can configure a new device with a compression algorithm that is not listed in -`comp_algorithm'. The thing is that, internally, ZRAM uses Crypto API +`comp_algorithm`. The thing is that, internally, ZRAM uses Crypto API and, if some of the algorithms were built as modules, it's impossible to list all of them using, for instance, /proc/crypto or any other method. This, however, has an advantage of permitting the usage of custom crypto compression modules (implementing S/W or H/W compression). 4) Set Disksize +=============== + Set disk size by writing the value to sysfs node 'disksize'. The value can be either in bytes or you can use mem suffixes. -Examples: +Examples:: + # Initialize /dev/zram0 with 50MB disksize echo $((50*1024*1024)) > /sys/block/zram0/disksize @@ -111,10 +132,13 @@ since we expect a 2:1 compression ratio. Note that zram uses about 0.1% of the size of the disk when not in use so a huge zram is wasteful. 5) Set memory limit: Optional +============================= + Set memory limit by writing the value to sysfs node 'mem_limit'. The value can be either in bytes or you can use mem suffixes. In addition, you could change the value in runtime. -Examples: +Examples:: + # limit /dev/zram0 with 50MB memory echo $((50*1024*1024)) > /sys/block/zram0/mem_limit @@ -126,7 +150,11 @@ Examples: # To disable memory limit echo 0 > /sys/block/zram0/mem_limit -6) Activate: +6) Activate +=========== + +:: + mkswap /dev/zram0 swapon /dev/zram0 @@ -134,6 +162,7 @@ Examples: mount /dev/zram1 /tmp 7) Add/remove zram devices +========================== zram provides a control interface, which enables dynamic (on-demand) device addition and removal. @@ -142,44 +171,51 @@ In order to add a new /dev/zramX device, perform read operation on hot_add attribute. This will return either new device's device id (meaning that you can use /dev/zram<id>) or error code. -Example: +Example:: + cat /sys/class/zram-control/hot_add 1 To remove the existing /dev/zramX device (where X is a device id) -execute +execute:: + echo X > /sys/class/zram-control/hot_remove -8) Stats: +8) Stats +======== + Per-device statistics are exported as various nodes under /sys/block/zram<id>/ A brief description of exported device attributes. For more details please read Documentation/ABI/testing/sysfs-block-zram. +====================== ====== =============================================== Name access description ----- ------ ----------- +====================== ====== =============================================== disksize RW show and set the device's disk size initstate RO shows the initialization state of the device reset WO trigger device reset -mem_used_max WO reset the `mem_used_max' counter (see later) -mem_limit WO specifies the maximum amount of memory ZRAM can use - to store the compressed data -writeback_limit WO specifies the maximum amount of write IO zram can - write out to backing device as 4KB unit +mem_used_max WO reset the `mem_used_max` counter (see later) +mem_limit WO specifies the maximum amount of memory ZRAM can + use to store the compressed data +writeback_limit WO specifies the maximum amount of write IO zram + can write out to backing device as 4KB unit writeback_limit_enable RW show and set writeback_limit feature -max_comp_streams RW the number of possible concurrent compress operations +max_comp_streams RW the number of possible concurrent compress + operations comp_algorithm RW show and change the compression algorithm compact WO trigger memory compaction debug_stat RO this file is used for zram debugging purposes backing_dev RW set up backend storage for zram to write out idle WO mark allocated slot as idle +====================== ====== =============================================== User space is advised to use the following files to read the device statistics. File /sys/block/zram<id>/stat -Represents block layer statistics. Read Documentation/block/stat.txt for +Represents block layer statistics. Read Documentation/block/stat.rst for details. File /sys/block/zram<id>/io_stat @@ -188,23 +224,31 @@ The stat file represents device's I/O statistics not accounted by block layer and, thus, not available in zram<id>/stat file. It consists of a single line of text and contains the following stats separated by whitespace: - failed_reads the number of failed reads - failed_writes the number of failed writes - invalid_io the number of non-page-size-aligned I/O requests + + ============= ============================================================= + failed_reads The number of failed reads + failed_writes The number of failed writes + invalid_io The number of non-page-size-aligned I/O requests notify_free Depending on device usage scenario it may account + a) the number of pages freed because of swap slot free - notifications or b) the number of pages freed because of - REQ_OP_DISCARD requests sent by bio. The former ones are - sent to a swap block device when a swap slot is freed, - which implies that this disk is being used as a swap disk. + notifications + b) the number of pages freed because of + REQ_OP_DISCARD requests sent by bio. The former ones are + sent to a swap block device when a swap slot is freed, + which implies that this disk is being used as a swap disk. + The latter ones are sent by filesystem mounted with discard option, whenever some data blocks are getting discarded. + ============= ============================================================= File /sys/block/zram<id>/mm_stat The stat file represents device's mm statistics. It consists of a single line of text and contains the following stats separated by whitespace: + + ================ ============================================================= orig_data_size uncompressed size of data stored in this disk. This excludes same-element-filled pages (same_pages) since no memory is allocated for them. @@ -223,58 +267,71 @@ line of text and contains the following stats separated by whitespace: No memory is allocated for such pages. pages_compacted the number of pages freed during compaction huge_pages the number of incompressible pages + ================ ============================================================= File /sys/block/zram<id>/bd_stat The stat file represents device's backing device statistics. It consists of a single line of text and contains the following stats separated by whitespace: + + ============== ============================================================= bd_count size of data written in backing device. Unit: 4K bytes bd_reads the number of reads from backing device Unit: 4K bytes bd_writes the number of writes to backing device Unit: 4K bytes + ============== ============================================================= + +9) Deactivate +============= + +:: -9) Deactivate: swapoff /dev/zram0 umount /dev/zram1 -10) Reset: - Write any positive value to 'reset' sysfs node - echo 1 > /sys/block/zram0/reset - echo 1 > /sys/block/zram1/reset +10) Reset +========= + + Write any positive value to 'reset' sysfs node:: + + echo 1 > /sys/block/zram0/reset + echo 1 > /sys/block/zram1/reset This frees all the memory allocated for the given device and resets the disksize to zero. You must set the disksize again before reusing the device. -* Optional Feature +Optional Feature +================ -= writeback +writeback +--------- With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page to backing storage rather than keeping it in memory. -To use the feature, admin should set up backing device via +To use the feature, admin should set up backing device via:: - "echo /dev/sda5 > /sys/block/zramX/backing_dev" + echo /dev/sda5 > /sys/block/zramX/backing_dev before disksize setting. It supports only partition at this moment. -If admin want to use incompressible page writeback, they could do via +If admin want to use incompressible page writeback, they could do via:: - "echo huge > /sys/block/zramX/write" + echo huge > /sys/block/zramX/write To use idle page writeback, first, user need to declare zram pages -as idle. +as idle:: - "echo all > /sys/block/zramX/idle" + echo all > /sys/block/zramX/idle From now on, any pages on zram are idle pages. The idle mark will be removed until someone request access of the block. IOW, unless there is access request, those pages are still idle pages. -Admin can request writeback of those idle pages at right timing via +Admin can request writeback of those idle pages at right timing via:: - "echo idle > /sys/block/zramX/writeback" + echo idle > /sys/block/zramX/writeback With the command, zram writeback idle pages from memory to the storage. @@ -285,7 +342,7 @@ to guarantee storage health for entire product life. To overcome the concern, zram supports "writeback_limit" feature. The "writeback_limit_enable"'s default value is 0 so that it doesn't limit any writeback. IOW, if admin want to apply writeback budget, he should -enable writeback_limit_enable via +enable writeback_limit_enable via:: $ echo 1 > /sys/block/zramX/writeback_limit_enable @@ -296,7 +353,7 @@ until admin set the budget via /sys/block/zramX/writeback_limit. assigned via /sys/block/zramX/writeback_limit is meaninless.) If admin want to limit writeback as per-day 400M, he could do it -like below. +like below:: $ MB_SHIFT=20 $ 4K_SHIFT=12 @@ -305,16 +362,16 @@ like below. $ echo 1 > /sys/block/zram0/writeback_limit_enable If admin want to allow further write again once the bugdet is exausted, -he could do it like below +he could do it like below:: $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \ /sys/block/zram0/writeback_limit -If admin want to see remaining writeback budget since he set, +If admin want to see remaining writeback budget since he set:: $ cat /sys/block/zramX/writeback_limit -If admin want to disable writeback limit, he could do +If admin want to disable writeback limit, he could do:: $ echo 0 > /sys/block/zramX/writeback_limit_enable @@ -326,25 +383,35 @@ budget in next setting is user's job. If admin want to measure writeback count in a certain period, he could know it via /sys/block/zram0/bd_stat's 3rd column. -= memory tracking +memory tracking +=============== With CONFIG_ZRAM_MEMORY_TRACKING, user can know information of the zram block. It could be useful to catch cold or incompressible pages of the process with*pagemap. + If you enable the feature, you could see block state via -/sys/kernel/debug/zram/zram0/block_state". The output is as follows, +/sys/kernel/debug/zram/zram0/block_state". The output is as follows:: 300 75.033841 .wh. 301 63.806904 s... 302 63.806919 ..hi -First column is zram's block index. -Second column is access time since the system was booted -Third column is state of the block. -(s: same page -w: written page to backing store -h: huge page -i: idle page) +First column + zram's block index. +Second column + access time since the system was booted +Third column + state of the block: + + s: + same page + w: + written page to backing store + h: + huge page + i: + idle page First line of above example says 300th block is accessed at 75.033841sec and the block's state is huge so it is written back to the backing diff --git a/Documentation/btmrvl.txt b/Documentation/admin-guide/btmrvl.rst index ec57740ead0c..ec57740ead0c 100644 --- a/Documentation/btmrvl.txt +++ b/Documentation/admin-guide/btmrvl.rst diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst index b761aa2a51d2..44b8a4edd348 100644 --- a/Documentation/admin-guide/bug-hunting.rst +++ b/Documentation/admin-guide/bug-hunting.rst @@ -90,9 +90,9 @@ the disk is not available then you have three options: run a null modem to a second machine and capture the output there using your favourite communication program. Minicom works well. -(3) Use Kdump (see Documentation/kdump/kdump.rst), +(3) Use Kdump (see Documentation/admin-guide/kdump/kdump.rst), extract the kernel ring buffer from old memory with using dmesg - gdbmacro in Documentation/kdump/gdbmacros.txt. + gdbmacro in Documentation/admin-guide/kdump/gdbmacros.txt. Finding the bug's location -------------------------- diff --git a/Documentation/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst index 1d7d962933be..1d7d962933be 100644 --- a/Documentation/cgroup-v1/blkio-controller.rst +++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst diff --git a/Documentation/cgroup-v1/cgroups.rst b/Documentation/admin-guide/cgroup-v1/cgroups.rst index 46bbe7e022d4..b0688011ed06 100644 --- a/Documentation/cgroup-v1/cgroups.rst +++ b/Documentation/admin-guide/cgroup-v1/cgroups.rst @@ -3,7 +3,7 @@ Control Groups ============== Written by Paul Menage <menage@google.com> based on -Documentation/cgroup-v1/cpusets.rst +Documentation/admin-guide/cgroup-v1/cpusets.rst Original copyright statements from cpusets.txt: @@ -76,7 +76,7 @@ On their own, the only use for cgroups is for simple job tracking. The intention is that other subsystems hook into the generic cgroup support to provide new attributes for cgroups, such as accounting/limiting the resources which processes in a cgroup can -access. For example, cpusets (see Documentation/cgroup-v1/cpusets.rst) allow +access. For example, cpusets (see Documentation/admin-guide/cgroup-v1/cpusets.rst) allow you to associate a set of CPUs and a set of memory nodes with the tasks in each cgroup. diff --git a/Documentation/cgroup-v1/cpuacct.rst b/Documentation/admin-guide/cgroup-v1/cpuacct.rst index d30ed81d2ad7..d30ed81d2ad7 100644 --- a/Documentation/cgroup-v1/cpuacct.rst +++ b/Documentation/admin-guide/cgroup-v1/cpuacct.rst diff --git a/Documentation/cgroup-v1/cpusets.rst b/Documentation/admin-guide/cgroup-v1/cpusets.rst index b6a42cdea72b..86a6ae995d54 100644 --- a/Documentation/cgroup-v1/cpusets.rst +++ b/Documentation/admin-guide/cgroup-v1/cpusets.rst @@ -49,7 +49,7 @@ hooks, beyond what is already present, required to manage dynamic job placement on large systems. Cpusets use the generic cgroup subsystem described in -Documentation/cgroup-v1/cgroups.rst. +Documentation/admin-guide/cgroup-v1/cgroups.rst. Requests by a task, using the sched_setaffinity(2) system call to include CPUs in its CPU affinity mask, and using the mbind(2) and diff --git a/Documentation/cgroup-v1/devices.rst b/Documentation/admin-guide/cgroup-v1/devices.rst index e1886783961e..e1886783961e 100644 --- a/Documentation/cgroup-v1/devices.rst +++ b/Documentation/admin-guide/cgroup-v1/devices.rst diff --git a/Documentation/cgroup-v1/freezer-subsystem.rst b/Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst index 582d3427de3f..582d3427de3f 100644 --- a/Documentation/cgroup-v1/freezer-subsystem.rst +++ b/Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst diff --git a/Documentation/cgroup-v1/hugetlb.rst b/Documentation/admin-guide/cgroup-v1/hugetlb.rst index a3902aa253a9..a3902aa253a9 100644 --- a/Documentation/cgroup-v1/hugetlb.rst +++ b/Documentation/admin-guide/cgroup-v1/hugetlb.rst diff --git a/Documentation/cgroup-v1/index.rst b/Documentation/admin-guide/cgroup-v1/index.rst index fe76d42edc11..10bf48bae0b0 100644 --- a/Documentation/cgroup-v1/index.rst +++ b/Documentation/admin-guide/cgroup-v1/index.rst @@ -1,5 +1,3 @@ -:orphan: - ======================== Control Groups version 1 ======================== diff --git a/Documentation/cgroup-v1/memcg_test.rst b/Documentation/admin-guide/cgroup-v1/memcg_test.rst index 91bd18c6a514..3f7115e07b5d 100644 --- a/Documentation/cgroup-v1/memcg_test.rst +++ b/Documentation/admin-guide/cgroup-v1/memcg_test.rst @@ -10,7 +10,7 @@ Because VM is getting complex (one of reasons is memcg...), memcg's behavior is complex. This is a document for memcg's internal behavior. Please note that implementation details can be changed. -(*) Topics on API should be in Documentation/cgroup-v1/memory.rst) +(*) Topics on API should be in Documentation/admin-guide/cgroup-v1/memory.rst) 0. How to record usage ? ======================== @@ -327,7 +327,7 @@ Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y. You can see charges have been moved by reading ``*.usage_in_bytes`` or memory.stat of both A and B. - See 8.2 of Documentation/cgroup-v1/memory.rst to see what value should + See 8.2 of Documentation/admin-guide/cgroup-v1/memory.rst to see what value should be written to move_charge_at_immigrate. 9.10 Memory thresholds diff --git a/Documentation/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index 41bdc038dad9..41bdc038dad9 100644 --- a/Documentation/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst diff --git a/Documentation/cgroup-v1/net_cls.rst b/Documentation/admin-guide/cgroup-v1/net_cls.rst index a2cf272af7a0..a2cf272af7a0 100644 --- a/Documentation/cgroup-v1/net_cls.rst +++ b/Documentation/admin-guide/cgroup-v1/net_cls.rst diff --git a/Documentation/cgroup-v1/net_prio.rst b/Documentation/admin-guide/cgroup-v1/net_prio.rst index b40905871c64..b40905871c64 100644 --- a/Documentation/cgroup-v1/net_prio.rst +++ b/Documentation/admin-guide/cgroup-v1/net_prio.rst diff --git a/Documentation/cgroup-v1/pids.rst b/Documentation/admin-guide/cgroup-v1/pids.rst index 6acebd9e72c8..6acebd9e72c8 100644 --- a/Documentation/cgroup-v1/pids.rst +++ b/Documentation/admin-guide/cgroup-v1/pids.rst diff --git a/Documentation/cgroup-v1/rdma.rst b/Documentation/admin-guide/cgroup-v1/rdma.rst index 2fcb0a9bf790..2fcb0a9bf790 100644 --- a/Documentation/cgroup-v1/rdma.rst +++ b/Documentation/admin-guide/cgroup-v1/rdma.rst diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index a9548de56ac9..3b29005aa981 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -9,7 +9,7 @@ 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/. +v1 is available under Documentation/admin-guide/cgroup-v1/. .. CONTENTS @@ -1014,7 +1014,7 @@ All time durations are in microseconds. A read-only nested-key file which exists on non-root cgroups. Shows pressure stall information for CPU. See - Documentation/accounting/psi.txt for details. + Documentation/accounting/psi.rst for details. Memory @@ -1355,7 +1355,7 @@ PAGE_SIZE multiple when read back. A read-only nested-key file which exists on non-root cgroups. Shows pressure stall information for memory. See - Documentation/accounting/psi.txt for details. + Documentation/accounting/psi.rst for details. Usage Guidelines @@ -1498,7 +1498,7 @@ IO Interface Files A read-only nested-key file which exists on non-root cgroups. Shows pressure stall information for IO. See - Documentation/accounting/psi.txt for details. + Documentation/accounting/psi.rst for details. Writeback @@ -2124,7 +2124,7 @@ following two functions. a queue (device) has been associated with the bio and before submission. - wbc_account_io(@wbc, @page, @bytes) + wbc_account_cgroup_owner(@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 diff --git a/Documentation/clearing-warn-once.txt b/Documentation/admin-guide/clearing-warn-once.rst index 211fd926cf00..211fd926cf00 100644 --- a/Documentation/clearing-warn-once.txt +++ b/Documentation/admin-guide/clearing-warn-once.rst diff --git a/Documentation/cpu-load.txt b/Documentation/admin-guide/cpu-load.rst index 2d01ce43d2a2..2d01ce43d2a2 100644 --- a/Documentation/cpu-load.txt +++ b/Documentation/admin-guide/cpu-load.rst diff --git a/Documentation/cputopology.txt b/Documentation/admin-guide/cputopology.rst index b90dafcc8237..b90dafcc8237 100644 --- a/Documentation/cputopology.txt +++ b/Documentation/admin-guide/cputopology.rst diff --git a/Documentation/device-mapper/cache-policies.rst b/Documentation/admin-guide/device-mapper/cache-policies.rst index b17fe352fc41..b17fe352fc41 100644 --- a/Documentation/device-mapper/cache-policies.rst +++ b/Documentation/admin-guide/device-mapper/cache-policies.rst diff --git a/Documentation/device-mapper/cache.rst b/Documentation/admin-guide/device-mapper/cache.rst index f15e5254d05b..f15e5254d05b 100644 --- a/Documentation/device-mapper/cache.rst +++ b/Documentation/admin-guide/device-mapper/cache.rst diff --git a/Documentation/device-mapper/delay.rst b/Documentation/admin-guide/device-mapper/delay.rst index 917ba8c33359..917ba8c33359 100644 --- a/Documentation/device-mapper/delay.rst +++ b/Documentation/admin-guide/device-mapper/delay.rst diff --git a/Documentation/device-mapper/dm-crypt.rst b/Documentation/admin-guide/device-mapper/dm-crypt.rst index 8f4a3f889d43..8f4a3f889d43 100644 --- a/Documentation/device-mapper/dm-crypt.rst +++ b/Documentation/admin-guide/device-mapper/dm-crypt.rst diff --git a/Documentation/device-mapper/dm-dust.txt b/Documentation/admin-guide/device-mapper/dm-dust.txt index 954d402a1f6a..954d402a1f6a 100644 --- a/Documentation/device-mapper/dm-dust.txt +++ b/Documentation/admin-guide/device-mapper/dm-dust.txt diff --git a/Documentation/device-mapper/dm-flakey.rst b/Documentation/admin-guide/device-mapper/dm-flakey.rst index 86138735879d..86138735879d 100644 --- a/Documentation/device-mapper/dm-flakey.rst +++ b/Documentation/admin-guide/device-mapper/dm-flakey.rst diff --git a/Documentation/device-mapper/dm-init.rst b/Documentation/admin-guide/device-mapper/dm-init.rst index e5242ff17e9b..e5242ff17e9b 100644 --- a/Documentation/device-mapper/dm-init.rst +++ b/Documentation/admin-guide/device-mapper/dm-init.rst diff --git a/Documentation/device-mapper/dm-integrity.rst b/Documentation/admin-guide/device-mapper/dm-integrity.rst index a30aa91b5fbe..a30aa91b5fbe 100644 --- a/Documentation/device-mapper/dm-integrity.rst +++ b/Documentation/admin-guide/device-mapper/dm-integrity.rst diff --git a/Documentation/device-mapper/dm-io.rst b/Documentation/admin-guide/device-mapper/dm-io.rst index d2492917a1f5..d2492917a1f5 100644 --- a/Documentation/device-mapper/dm-io.rst +++ b/Documentation/admin-guide/device-mapper/dm-io.rst diff --git a/Documentation/device-mapper/dm-log.rst b/Documentation/admin-guide/device-mapper/dm-log.rst index ba4fce39bc27..ba4fce39bc27 100644 --- a/Documentation/device-mapper/dm-log.rst +++ b/Documentation/admin-guide/device-mapper/dm-log.rst diff --git a/Documentation/device-mapper/dm-queue-length.rst b/Documentation/admin-guide/device-mapper/dm-queue-length.rst index d8e381c1cb02..d8e381c1cb02 100644 --- a/Documentation/device-mapper/dm-queue-length.rst +++ b/Documentation/admin-guide/device-mapper/dm-queue-length.rst diff --git a/Documentation/device-mapper/dm-raid.rst b/Documentation/admin-guide/device-mapper/dm-raid.rst index 2fe255b130fb..2fe255b130fb 100644 --- a/Documentation/device-mapper/dm-raid.rst +++ b/Documentation/admin-guide/device-mapper/dm-raid.rst diff --git a/Documentation/device-mapper/dm-service-time.rst b/Documentation/admin-guide/device-mapper/dm-service-time.rst index facf277fc13c..facf277fc13c 100644 --- a/Documentation/device-mapper/dm-service-time.rst +++ b/Documentation/admin-guide/device-mapper/dm-service-time.rst diff --git a/Documentation/device-mapper/dm-uevent.rst b/Documentation/admin-guide/device-mapper/dm-uevent.rst index 4a8ee8d069c9..4a8ee8d069c9 100644 --- a/Documentation/device-mapper/dm-uevent.rst +++ b/Documentation/admin-guide/device-mapper/dm-uevent.rst diff --git a/Documentation/device-mapper/dm-zoned.rst b/Documentation/admin-guide/device-mapper/dm-zoned.rst index 07f56ebc1730..07f56ebc1730 100644 --- a/Documentation/device-mapper/dm-zoned.rst +++ b/Documentation/admin-guide/device-mapper/dm-zoned.rst diff --git a/Documentation/device-mapper/era.rst b/Documentation/admin-guide/device-mapper/era.rst index 90dd5c670b9f..90dd5c670b9f 100644 --- a/Documentation/device-mapper/era.rst +++ b/Documentation/admin-guide/device-mapper/era.rst diff --git a/Documentation/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index 105e253bc231..c77c58b8f67b 100644 --- a/Documentation/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -1,5 +1,3 @@ -:orphan: - ============= Device Mapper ============= diff --git a/Documentation/device-mapper/kcopyd.rst b/Documentation/admin-guide/device-mapper/kcopyd.rst index 7651d395127f..7651d395127f 100644 --- a/Documentation/device-mapper/kcopyd.rst +++ b/Documentation/admin-guide/device-mapper/kcopyd.rst diff --git a/Documentation/device-mapper/linear.rst b/Documentation/admin-guide/device-mapper/linear.rst index 9d17fc6e64a9..9d17fc6e64a9 100644 --- a/Documentation/device-mapper/linear.rst +++ b/Documentation/admin-guide/device-mapper/linear.rst diff --git a/Documentation/device-mapper/log-writes.rst b/Documentation/admin-guide/device-mapper/log-writes.rst index 23141f2ffb7c..23141f2ffb7c 100644 --- a/Documentation/device-mapper/log-writes.rst +++ b/Documentation/admin-guide/device-mapper/log-writes.rst diff --git a/Documentation/device-mapper/persistent-data.rst b/Documentation/admin-guide/device-mapper/persistent-data.rst index 2065c3c5a091..2065c3c5a091 100644 --- a/Documentation/device-mapper/persistent-data.rst +++ b/Documentation/admin-guide/device-mapper/persistent-data.rst diff --git a/Documentation/device-mapper/snapshot.rst b/Documentation/admin-guide/device-mapper/snapshot.rst index 4c53304e72f1..ccdd8b587a74 100644 --- a/Documentation/device-mapper/snapshot.rst +++ b/Documentation/admin-guide/device-mapper/snapshot.rst @@ -32,6 +32,7 @@ its visible content unchanged, at least until the <COW device> fills up. - snapshot <origin> <COW device> <persistent?> <chunksize> + [<# feature args> [<arg>]*] A snapshot of the <origin> block device is created. Changed chunks of <chunksize> sectors will be stored on the <COW device>. Writes will @@ -54,8 +55,23 @@ When loading or unloading the snapshot target, the corresponding snapshot-origin or snapshot-merge target must be suspended. A failure to suspend the origin target could result in data corruption. +Optional features: -* snapshot-merge <origin> <COW device> <persistent> <chunksize> + discard_zeroes_cow - a discard issued to the snapshot device that + maps to entire chunks to will zero the corresponding exception(s) in + the snapshot's exception store. + + discard_passdown_origin - a discard to the snapshot device is passed + down to the snapshot-origin's underlying device. This doesn't cause + copy-out to the snapshot exception store because the snapshot-origin + target is bypassed. + + The discard_passdown_origin feature depends on the discard_zeroes_cow + feature being enabled. + + +- snapshot-merge <origin> <COW device> <persistent> <chunksize> + [<# feature args> [<arg>]*] takes the same table arguments as the snapshot target except it only works with persistent snapshots. This target assumes the role of the diff --git a/Documentation/device-mapper/statistics.rst b/Documentation/admin-guide/device-mapper/statistics.rst index 3d80a9f850cc..41ded0bc5933 100644 --- a/Documentation/device-mapper/statistics.rst +++ b/Documentation/admin-guide/device-mapper/statistics.rst @@ -13,7 +13,7 @@ the range specified. The I/O statistics counters for each step-sized area of a region are in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see: -Documentation/iostats.txt). But two extra counters (12 and 13) are +Documentation/admin-guide/iostats.rst). But two extra counters (12 and 13) are provided: total time spent reading and writing. When the histogram argument is used, the 14th parameter is reported that represents the histogram of latencies. All these counters may be accessed by sending @@ -151,7 +151,7 @@ Messages The first 11 counters have the same meaning as `/sys/block/*/stat or /proc/diskstats`. - Please refer to Documentation/iostats.txt for details. + Please refer to Documentation/admin-guide/iostats.rst for details. 1. the number of reads completed 2. the number of reads merged diff --git a/Documentation/device-mapper/striped.rst b/Documentation/admin-guide/device-mapper/striped.rst index e9a8da192ae1..e9a8da192ae1 100644 --- a/Documentation/device-mapper/striped.rst +++ b/Documentation/admin-guide/device-mapper/striped.rst diff --git a/Documentation/device-mapper/switch.rst b/Documentation/admin-guide/device-mapper/switch.rst index 7dde06be1a4f..7dde06be1a4f 100644 --- a/Documentation/device-mapper/switch.rst +++ b/Documentation/admin-guide/device-mapper/switch.rst diff --git a/Documentation/device-mapper/thin-provisioning.rst b/Documentation/admin-guide/device-mapper/thin-provisioning.rst index bafebf79da4b..bafebf79da4b 100644 --- a/Documentation/device-mapper/thin-provisioning.rst +++ b/Documentation/admin-guide/device-mapper/thin-provisioning.rst diff --git a/Documentation/device-mapper/unstriped.rst b/Documentation/admin-guide/device-mapper/unstriped.rst index 0a8d3eb3f072..0a8d3eb3f072 100644 --- a/Documentation/device-mapper/unstriped.rst +++ b/Documentation/admin-guide/device-mapper/unstriped.rst diff --git a/Documentation/device-mapper/verity.rst b/Documentation/admin-guide/device-mapper/verity.rst index a4d1c1476d72..a4d1c1476d72 100644 --- a/Documentation/device-mapper/verity.rst +++ b/Documentation/admin-guide/device-mapper/verity.rst diff --git a/Documentation/device-mapper/writecache.rst b/Documentation/admin-guide/device-mapper/writecache.rst index d3d7690f5e8d..d3d7690f5e8d 100644 --- a/Documentation/device-mapper/writecache.rst +++ b/Documentation/admin-guide/device-mapper/writecache.rst diff --git a/Documentation/device-mapper/zero.rst b/Documentation/admin-guide/device-mapper/zero.rst index 11fb5cf4597c..11fb5cf4597c 100644 --- a/Documentation/device-mapper/zero.rst +++ b/Documentation/admin-guide/device-mapper/zero.rst diff --git a/Documentation/efi-stub.txt b/Documentation/admin-guide/efi-stub.rst index 833edb0d0bc4..833edb0d0bc4 100644 --- a/Documentation/efi-stub.txt +++ b/Documentation/admin-guide/efi-stub.rst diff --git a/Documentation/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index 09a4a553f434..a244ba4e87d5 100644 --- a/Documentation/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ==== gpio diff --git a/Documentation/gpio/sysfs.rst b/Documentation/admin-guide/gpio/sysfs.rst index ec09ffd983e7..ec09ffd983e7 100644 --- a/Documentation/gpio/sysfs.rst +++ b/Documentation/admin-guide/gpio/sysfs.rst diff --git a/Documentation/highuid.txt b/Documentation/admin-guide/highuid.rst index 6ee70465c0ea..6ee70465c0ea 100644 --- a/Documentation/highuid.txt +++ b/Documentation/admin-guide/highuid.rst diff --git a/Documentation/admin-guide/hw-vuln/l1tf.rst b/Documentation/admin-guide/hw-vuln/l1tf.rst index 656aee262e23..f83212fae4d5 100644 --- a/Documentation/admin-guide/hw-vuln/l1tf.rst +++ b/Documentation/admin-guide/hw-vuln/l1tf.rst @@ -241,7 +241,7 @@ Guest mitigation mechanisms For further information about confining guests to a single or to a group of cores consult the cpusets documentation: - https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.rst + https://www.kernel.org/doc/Documentation/admin-guide/cgroup-v1/cpusets.rst .. _interrupt_isolation: diff --git a/Documentation/hw_random.txt b/Documentation/admin-guide/hw_random.rst index 121de96e395e..121de96e395e 100644 --- a/Documentation/hw_random.txt +++ b/Documentation/admin-guide/hw_random.rst diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 24fbe0568eff..33feab2f4084 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -16,6 +16,7 @@ etc. README kernel-parameters devices + sysctl/index This section describes CPU vulnerabilities and their mitigations. @@ -38,6 +39,8 @@ problems and bugs in particular. ramoops dynamic-debug-howto init + kdump/index + perf/index This is the beginning of a section with information of interest to application developers. Documents covering various aspects of the kernel @@ -56,11 +59,13 @@ configure specific aspects of kernel behavior to your liking. initrd cgroup-v2 + cgroup-v1/index serial-console braille-console parport md module-signing + rapidio sysrq unicode vga-softcursor @@ -69,14 +74,38 @@ configure specific aspects of kernel behavior to your liking. java ras bcache + blockdev/index ext4 binderfs + xfs pm/index thunderbolt LSM/index mm/index + namespaces/index perf-security acpi/index + aoe/index + btmrvl + clearing-warn-once + cpu-load + cputopology + device-mapper/index + efi-stub + gpio/index + highuid + hw_random + iostats + kernel-per-CPU-kthreads + laptops/index + lcd-panel-cgram + ldm + lockup-watchdogs + numastat + pnp + rtc + svga + video-output .. only:: subproject and html diff --git a/Documentation/iostats.txt b/Documentation/admin-guide/iostats.rst index 5d63b18bd6d1..5d63b18bd6d1 100644 --- a/Documentation/iostats.txt +++ b/Documentation/admin-guide/iostats.rst diff --git a/Documentation/kdump/gdbmacros.txt b/Documentation/admin-guide/kdump/gdbmacros.txt index 220d0a80ca2c..220d0a80ca2c 100644 --- a/Documentation/kdump/gdbmacros.txt +++ b/Documentation/admin-guide/kdump/gdbmacros.txt diff --git a/Documentation/kdump/index.rst b/Documentation/admin-guide/kdump/index.rst index 2b17fcf6867a..8e2ebd0383cd 100644 --- a/Documentation/kdump/index.rst +++ b/Documentation/admin-guide/kdump/index.rst @@ -1,4 +1,3 @@ -:orphan: ================================================================ Documentation for Kdump - The kexec-based Crash Dumping Solution diff --git a/Documentation/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst index ac7e131d2935..ac7e131d2935 100644 --- a/Documentation/kdump/kdump.rst +++ b/Documentation/admin-guide/kdump/kdump.rst diff --git a/Documentation/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index 007a6b86e0ee..007a6b86e0ee 100644 --- a/Documentation/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 5d29ba5ad88c..d05d531b4ec9 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -118,7 +118,7 @@ parameter is applicable:: LOOP Loopback device support is enabled. M68k M68k architecture is enabled. These options have more detailed description inside of - Documentation/m68k/kernel-options.txt. + Documentation/m68k/kernel-options.rst. MDA MDA console support is enabled. MIPS MIPS architecture is enabled. MOUSE Appropriate mouse support is enabled. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 8a8880cec34b..7ccd158b3894 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -13,7 +13,7 @@ For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force" are available - See also Documentation/power/runtime_pm.txt, pci=noacpi + See also Documentation/power/runtime_pm.rst, pci=noacpi acpi_apic_instance= [ACPI, IOAPIC] Format: <int> @@ -223,7 +223,7 @@ acpi_sleep= [HW,ACPI] Sleep options Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, old_ordering, nonvs, sci_force_enable, nobl } - See Documentation/power/video.txt for information on + See Documentation/power/video.rst for information on s3_bios and s3_mode. s3_beep is for debugging; it makes the PC's speaker beep as soon as the kernel's real-mode entry point is called. @@ -430,7 +430,7 @@ blkdevparts= Manual partition parsing of block device(s) for embedded devices based on command line input. - See Documentation/block/cmdline-partition.txt + See Documentation/block/cmdline-partition.rst boot_delay= Milliseconds to delay each printk during boot. Values larger than 10 seconds (10000) are changed to @@ -708,14 +708,14 @@ [KNL, x86_64] select a region under 4G first, and fall back to reserve region above 4G when '@offset' hasn't been specified. - See Documentation/kdump/kdump.rst for further details. + See Documentation/admin-guide/kdump/kdump.rst for further details. crashkernel=range1:size1[,range2:size2,...][@offset] [KNL] Same as above, but depends on the memory in the running system. The syntax of range is start-[end] where start and end are both a memory unit (amount[KMG]). See also - Documentation/kdump/kdump.rst for an example. + Documentation/admin-guide/kdump/kdump.rst for an example. crashkernel=size[KMG],high [KNL, x86_64] range could be above 4G. Allow kernel @@ -930,7 +930,7 @@ edid/1680x1050.bin, or edid/1920x1080.bin is given and no file with the same name exists. Details and instructions how to build your own EDID data are - available in Documentation/EDID/howto.rst. An EDID + available in Documentation/driver-api/edid.rst. An EDID data set will only be used for a particular connector, if its name and a colon are prepended to the EDID name. Each connector may use a unique EDID data @@ -1199,15 +1199,15 @@ elevator= [IOSCHED] Format: { "mq-deadline" | "kyber" | "bfq" } - See Documentation/block/deadline-iosched.txt, - Documentation/block/kyber-iosched.txt and - Documentation/block/bfq-iosched.txt for details. + See Documentation/block/deadline-iosched.rst, + Documentation/block/kyber-iosched.rst and + Documentation/block/bfq-iosched.rst for details. elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] Specifies physical address of start of kernel core image elf header and optionally the size. Generally kexec loader will pass this option to capture kernel. - See Documentation/kdump/kdump.rst for details. + See Documentation/admin-guide/kdump/kdump.rst for details. enable_mtrr_cleanup [X86] The kernel tries to adjust MTRR layout from continuous @@ -1249,7 +1249,7 @@ See also Documentation/fault-injection/. floppy= [HW] - See Documentation/blockdev/floppy.txt. + See Documentation/admin-guide/blockdev/floppy.rst. force_pal_cache_flush [IA-64] Avoid check_sal_cache_flush which may hang on @@ -2011,6 +2011,19 @@ Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, the default is off. + kprobe_event=[probe-list] + [FTRACE] Add kprobe events and enable at boot time. + The probe-list is a semicolon delimited list of probe + definitions. Each definition is same as kprobe_events + interface, but the parameters are comma delimited. + For example, to add a kprobe event on vfs_read with + arg1 and arg2, add to the command line; + + kprobe_event=p,vfs_read,$arg1,$arg2 + + See also Documentation/trace/kprobetrace.rst "Kernel + Boot Parameter" section. + kpti= [ARM64] Control page table isolation of user and kernel address spaces. Default: enabled on cores which need mitigation. @@ -2234,7 +2247,7 @@ memblock=debug [KNL] Enable memblock debug messages. load_ramdisk= [RAM] List of ramdisks to load from floppy - See Documentation/blockdev/ramdisk.txt. + See Documentation/admin-guide/blockdev/ramdisk.rst. lockd.nlm_grace_period=P [NFS] Assign grace period. Format: <integer> @@ -2877,6 +2890,17 @@ /sys/module/printk/parameters/console_suspend) to turn on/off it dynamically. + novmcoredd [KNL,KDUMP] + Disable device dump. Device dump allows drivers to + append dump data to vmcore so you can collect driver + specified debug info. Drivers can append the data + without any limit and this data is stored in memory, + so this may cause significant memory stress. Disabling + device dump can help save memory but the driver debug + data will be no longer available. This parameter + is only available when CONFIG_PROC_VMCORE_DEVICE_DUMP + is set. + noaliencache [MM, NUMA, SLAB] Disables the allocation of alien caches in the slab allocator. Saves per-node memory, but will impact performance. @@ -2932,7 +2956,7 @@ register save and restore. The kernel will only save legacy floating-point registers on task switch. - nohugeiomap [KNL,x86] Disable kernel huge I/O mappings. + nohugeiomap [KNL,x86,PPC] Disable kernel huge I/O mappings. nosmt [KNL,S390] Disable symmetric multithreading (SMT). Equivalent to smt=1. @@ -3144,7 +3168,7 @@ numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. 'node', 'default' can be specified This can be set from sysctl after boot. - See Documentation/sysctl/vm.txt for details. + See Documentation/admin-guide/sysctl/vm.rst for details. ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. See Documentation/debugging-via-ohci1394.txt for more @@ -3268,7 +3292,7 @@ pcd. [PARIDE] See header of drivers/block/paride/pcd.c. - See also Documentation/blockdev/paride.txt. + See also Documentation/admin-guide/blockdev/paride.rst. pci=option[,option...] [PCI] various PCI subsystem options. @@ -3512,7 +3536,7 @@ needed on a platform with proper driver support. pd. [PARIDE] - See Documentation/blockdev/paride.txt. + See Documentation/admin-guide/blockdev/paride.rst. pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at boot time. @@ -3527,10 +3551,10 @@ and performance comparison. pf. [PARIDE] - See Documentation/blockdev/paride.txt. + See Documentation/admin-guide/blockdev/paride.rst. pg. [PARIDE] - See Documentation/blockdev/paride.txt. + See Documentation/admin-guide/blockdev/paride.rst. pirq= [SMP,APIC] Manual mp-table setup See Documentation/x86/i386/IO-APIC.rst. @@ -3642,7 +3666,7 @@ prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk before loading. - See Documentation/blockdev/ramdisk.txt. + See Documentation/admin-guide/blockdev/ramdisk.rst. psi= [KNL] Enable or disable pressure stall information tracking. @@ -3664,7 +3688,7 @@ pstore.backend= Specify the name of the pstore backend to use pt. [PARIDE] - See Documentation/blockdev/paride.txt. + See Documentation/admin-guide/blockdev/paride.rst. pti= [X86_64] Control Page Table Isolation of user and kernel address spaces. Disabling this feature @@ -3693,7 +3717,7 @@ See Documentation/admin-guide/md.rst. ramdisk_size= [RAM] Sizes of RAM disks in kilobytes - See Documentation/blockdev/ramdisk.txt. + See Documentation/admin-guide/blockdev/ramdisk.rst. random.trust_cpu={on,off} [KNL] Enable or disable trusting the use of the @@ -4089,7 +4113,7 @@ relax_domain_level= [KNL, SMP] Set scheduler's default relax_domain_level. - See Documentation/cgroup-v1/cpusets.rst. + See Documentation/admin-guide/cgroup-v1/cpusets.rst. reserve= [KNL,BUGS] Force kernel to ignore I/O ports or memory Format: <base1>,<size1>[,<base2>,<size2>,...] @@ -4119,7 +4143,7 @@ Specify the offset from the beginning of the partition given by "resume=" at which the swap header is located, in <PAGE_SIZE> units (needed only for swap files). - See Documentation/power/swsusp-and-swap-files.txt + See Documentation/power/swsusp-and-swap-files.rst resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to read the resume files @@ -4347,7 +4371,7 @@ Format: <integer> sonypi.*= [HW] Sony Programmable I/O Control Device driver - See Documentation/laptops/sonypi.txt + See Documentation/admin-guide/laptops/sonypi.rst spectre_v2= [X86] Control mitigation of Spectre variant 2 (indirect branch speculation) vulnerability. @@ -4599,7 +4623,7 @@ swapaccount=[0|1] [KNL] Enable accounting of swap in memory resource controller if no parameter or 1 is given or disable - it if 0 is given (See Documentation/cgroup-v1/memory.rst) + it if 0 is given (See Documentation/admin-guide/cgroup-v1/memory.rst) swiotlb= [ARM,IA-64,PPC,MIPS,X86] Format: { <int> | force | noforce } @@ -4674,27 +4698,6 @@ Force threading of all interrupt handlers except those marked explicitly IRQF_NO_THREAD. - tmem [KNL,XEN] - Enable the Transcendent memory driver if built-in. - - tmem.cleancache=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the cleancache - API to send anonymous pages to the hypervisor. - - tmem.frontswap=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the frontswap - API to send swap pages to the hypervisor. If disabled - the selfballooning and selfshrinking are force disabled. - - tmem.selfballooning=0|1 [KNL, XEN] - Default is on (1). Disable the driving of swap pages - to the hypervisor. - - tmem.selfshrinking=0|1 [KNL, XEN] - Default is on (1). Partial swapoff that immediately - transfers pages from Xen hypervisor back to the - kernel based on different criteria. - topology= [S390] Format: {off | on} Specify if the kernel should make use of the cpu @@ -5066,7 +5069,7 @@ vga= [BOOT,X86-32] Select a particular video mode See Documentation/x86/boot.rst and - Documentation/svga.txt. + Documentation/admin-guide/svga.rst. Use vga=ask for menu. This is actually a boot loader parameter; the value is passed to the kernel using a special protocol. @@ -5264,6 +5267,8 @@ xen_nopv [X86] Disables the PV optimizations forcing the HVM guest to run as generic HVM guest with no PV drivers. + This option is obsoleted by the "nopv" option, which + has equivalent effect for XEN platform. xen_scrub_pages= [XEN] Boolean option to control scrubbing pages before giving them back @@ -5278,10 +5283,24 @@ improve timer resolution at the expense of processing more timer interrupts. + nopv= [X86,XEN,KVM,HYPER_V,VMWARE] + Disables the PV optimizations forcing the guest to run + as generic guest with no PV drivers. Currently support + XEN HVM, KVM, HYPER_V and VMWARE guest. + xirc2ps_cs= [NET,PCMCIA] Format: <irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]] + xive= [PPC] + By default on POWER9 and above, the kernel will + natively use the XIVE interrupt controller. This option + allows the fallback firmware mode to be used: + + off Fallback to firmware control of XIVE interrupt + controller on both pseries and powernv + platforms. Only useful on POWER9 and above. + xhci-hcd.quirks [USB,KNL] A hex value specifying bitmask with supplemental xhci host controller quirks. Meaning of each bit can be diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 5623b9916411..4f18456dd3b1 100644 --- a/Documentation/kernel-per-CPU-kthreads.txt +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -12,7 +12,7 @@ References - Documentation/IRQ-affinity.txt: Binding interrupts to sets of CPUs. -- Documentation/cgroup-v1: Using cgroups to bind tasks to sets of CPUs. +- Documentation/admin-guide/cgroup-v1: Using cgroups to bind tasks to sets of CPUs. - man taskset: Using the taskset command to bind tasks to sets of CPUs. diff --git a/Documentation/laptops/asus-laptop.txt b/Documentation/admin-guide/laptops/asus-laptop.rst index 5f2858712aa0..95176321a25a 100644 --- a/Documentation/laptops/asus-laptop.txt +++ b/Documentation/admin-guide/laptops/asus-laptop.rst @@ -1,6 +1,9 @@ +================== Asus Laptop Extras +================== Version 0.1 + August 6, 2009 Corentin Chary <corentincj@iksaif.net> @@ -10,11 +13,12 @@ http://acpi4asus.sf.net/ It may also support some MEDION, JVC or VICTOR laptops (such as MEDION 9675 or VICTOR XP7210 for example). It makes all the extra buttons generate input events (like keyboards). + On some models adds support for changing the display brightness and output, switching the LCD backlight on and off, and most importantly, allows you to blink those fancy LEDs intended for reporting mail and wireless status. -This driver supercedes the old asus_acpi driver. +This driver supersedes the old asus_acpi driver. Requirements ------------ @@ -49,7 +53,7 @@ Usage see some lines like this : Asus Laptop Extras version 0.42 - L2D model detected. + - L2D model detected. If it is not the output you have on your laptop, send it (and the laptop's DSDT) to me. @@ -68,9 +72,12 @@ Usage LEDs ---- - You can modify LEDs be echoing values to /sys/class/leds/asus::*/brightness : + You can modify LEDs be echoing values to `/sys/class/leds/asus/*/brightness`:: + echo 1 > /sys/class/leds/asus::mail/brightness + will switch the mail LED on. + You can also know if they are on/off by reading their content and use kernel triggers like disk-activity or heartbeat. @@ -81,7 +88,7 @@ Backlight /sys/class/backlight/asus-laptop/. Brightness Values are between 0 and 15. Wireless devices ---------------- +---------------- You can turn the internal Bluetooth adapter on/off with the bluetooth entry (only on models with Bluetooth). This usually controls the associated LED. @@ -93,18 +100,20 @@ Display switching Note: the display switching code is currently considered EXPERIMENTAL. Switching works for the following models: - L3800C - A2500H - L5800C - M5200N - W1000N (albeit with some glitches) - M6700R - A6JC - F3J + + - L3800C + - A2500H + - L5800C + - M5200N + - W1000N (albeit with some glitches) + - M6700R + - A6JC + - F3J Switching doesn't work for the following: - M3700N - L2X00D (locks the laptop under certain conditions) + + - M3700N + - L2X00D (locks the laptop under certain conditions) To switch the displays, echo values from 0 to 15 to /sys/devices/platform/asus-laptop/display. The significance of those values @@ -113,48 +122,51 @@ Display switching +-------+-----+-----+-----+-----+-----+ | Bin | Val | DVI | TV | CRT | LCD | +-------+-----+-----+-----+-----+-----+ - + 0000 + 0 + + + + + + | 0000 | 0 | | | | | +-------+-----+-----+-----+-----+-----+ - + 0001 + 1 + + + + X + + | 0001 | 1 | | | | X | +-------+-----+-----+-----+-----+-----+ - + 0010 + 2 + + + X + + + | 0010 | 2 | | | X | | +-------+-----+-----+-----+-----+-----+ - + 0011 + 3 + + + X + X + + | 0011 | 3 | | | X | X | +-------+-----+-----+-----+-----+-----+ - + 0100 + 4 + + X + + + + | 0100 | 4 | | X | | | +-------+-----+-----+-----+-----+-----+ - + 0101 + 5 + + X + + X + + | 0101 | 5 | | X | | X | +-------+-----+-----+-----+-----+-----+ - + 0110 + 6 + + X + X + + + | 0110 | 6 | | X | X | | +-------+-----+-----+-----+-----+-----+ - + 0111 + 7 + + X + X + X + + | 0111 | 7 | | X | X | X | +-------+-----+-----+-----+-----+-----+ - + 1000 + 8 + X + + + + + | 1000 | 8 | X | | | | +-------+-----+-----+-----+-----+-----+ - + 1001 + 9 + X + + + X + + | 1001 | 9 | X | | | X | +-------+-----+-----+-----+-----+-----+ - + 1010 + 10 + X + + X + + + | 1010 | 10 | X | | X | | +-------+-----+-----+-----+-----+-----+ - + 1011 + 11 + X + + X + X + + | 1011 | 11 | X | | X | X | +-------+-----+-----+-----+-----+-----+ - + 1100 + 12 + X + X + + + + | 1100 | 12 | X | X | | | +-------+-----+-----+-----+-----+-----+ - + 1101 + 13 + X + X + + X + + | 1101 | 13 | X | X | | X | +-------+-----+-----+-----+-----+-----+ - + 1110 + 14 + X + X + X + + + | 1110 | 14 | X | X | X | | +-------+-----+-----+-----+-----+-----+ - + 1111 + 15 + X + X + X + X + + | 1111 | 15 | X | X | X | X | +-------+-----+-----+-----+-----+-----+ In most cases, the appropriate displays must be plugged in for the above combinations to work. TV-Out may need to be initialized at boot time. Debugging: + 1) Check whether the Fn+F8 key: + a) does not lock the laptop (try a boot with noapic / nolapic if it does) b) generates events (0x6n, where n is the value corresponding to the configuration above) c) actually works + Record the disp value at every configuration. 2) Echo values from 0 to 15 to /sys/devices/platform/asus-laptop/display. Record its value, note any change. If nothing changes, try a broader range, @@ -164,7 +176,7 @@ Display switching Note: on some machines (e.g. L3C), after the module has been loaded, only 0x6n events are generated and no actual switching occurs. In such a case, a line - like: + like:: echo $((10#$arg-60)) > /sys/devices/platform/asus-laptop/display @@ -180,15 +192,16 @@ LED display several items of information. LED display works for the following models: - W1000N - W1J - To control the LED display, use the following : + - W1000N + - W1J + + To control the LED display, use the following:: echo 0x0T000DDD > /sys/devices/platform/asus-laptop/ where T control the 3 letters display, and DDD the 3 digits display, - according to the tables below. + according to the tables below:: DDD (digits) 000 to 999 = display digits @@ -208,8 +221,8 @@ LED display For example "echo 0x01000001 >/sys/devices/platform/asus-laptop/ledd" would display "DVD001". -Driver options: ---------------- +Driver options +-------------- Options can be passed to the asus-laptop driver using the standard module argument syntax (<param>=<value> when passing the option to the @@ -219,6 +232,7 @@ Driver options: wapf: WAPF defines the behavior of the Fn+Fx wlan key The significance of values is yet to be found, but most of the time: + - 0x0 should do nothing - 0x1 should allow to control the device with Fn+Fx key. - 0x4 should send an ACPI event (0x88) while pressing the Fn+Fx key @@ -237,7 +251,7 @@ Unsupported models - ASUS L7300G - ASUS L8400 -Patches, Errors, Questions: +Patches, Errors, Questions -------------------------- I appreciate any success or failure @@ -253,5 +267,5 @@ Patches, Errors, Questions: Any other comments or patches are also more than welcome. acpi4asus-user@lists.sourceforge.net - http://sourceforge.net/projects/acpi4asus + http://sourceforge.net/projects/acpi4asus diff --git a/Documentation/laptops/disk-shock-protection.txt b/Documentation/admin-guide/laptops/disk-shock-protection.rst index 0e6ba2663834..e97c5f78d8c3 100644 --- a/Documentation/laptops/disk-shock-protection.txt +++ b/Documentation/admin-guide/laptops/disk-shock-protection.rst @@ -1,17 +1,18 @@ +========================== Hard disk shock protection ========================== Author: Elias Oltmanns <eo@nebensachen.de> + Last modified: 2008-10-03 -0. Contents ------------ +.. 0. Contents -1. Intro -2. The interface -3. References -4. CREDITS + 1. Intro + 2. The interface + 3. References + 4. CREDITS 1. Intro @@ -36,8 +37,8 @@ that). ---------------- For each ATA device, the kernel exports the file -block/*/device/unload_heads in sysfs (here assumed to be mounted under -/sys). Access to /sys/block/*/device/unload_heads is denied with +`block/*/device/unload_heads` in sysfs (here assumed to be mounted under +/sys). Access to `/sys/block/*/device/unload_heads` is denied with -EOPNOTSUPP if the device does not support the unload feature. Otherwise, writing an integer value to this file will take the heads of the respective drive off the platter and block all I/O operations @@ -54,18 +55,18 @@ cancel a previously set timeout and resume normal operation immediately by specifying a timeout of 0. Values below -2 are rejected with -EINVAL (see below for the special meaning of -1 and -2). If the timeout specified for a recent head park request has not yet expired, -reading from /sys/block/*/device/unload_heads will report the number +reading from `/sys/block/*/device/unload_heads` will report the number of milliseconds remaining until normal operation will be resumed; otherwise, reading the unload_heads attribute will return 0. For example, do the following in order to park the heads of drive -/dev/sda and stop all I/O operations for five seconds: +/dev/sda and stop all I/O operations for five seconds:: -# echo 5000 > /sys/block/sda/device/unload_heads + # echo 5000 > /sys/block/sda/device/unload_heads -A simple +A simple:: -# cat /sys/block/sda/device/unload_heads + # cat /sys/block/sda/device/unload_heads will show you how many milliseconds are left before normal operation will be resumed. @@ -112,9 +113,9 @@ unload_heads attribute. If you know that your device really does support the unload feature (for instance, because the vendor of your laptop or the hard drive itself told you so), then you can tell the kernel to enable the usage of this feature for that drive by writing -the special value -1 to the unload_heads attribute: +the special value -1 to the unload_heads attribute:: -# echo -1 > /sys/block/sda/device/unload_heads + # echo -1 > /sys/block/sda/device/unload_heads will enable the feature for /dev/sda, and giving -2 instead of -1 will disable it again. @@ -135,6 +136,7 @@ for use. Please feel free to add projects that have been the victims of my ignorance. - http://www.thinkwiki.org/wiki/HDAPS + See this page for information about Linux support of the hard disk active protection system as implemented in IBM/Lenovo Thinkpads. diff --git a/Documentation/admin-guide/laptops/index.rst b/Documentation/admin-guide/laptops/index.rst new file mode 100644 index 000000000000..cd9a1c2695fd --- /dev/null +++ b/Documentation/admin-guide/laptops/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +Laptop Drivers +============== + +.. toctree:: + :maxdepth: 1 + + asus-laptop + disk-shock-protection + laptop-mode + lg-laptop + sony-laptop + sonypi + thinkpad-acpi + toshiba_haps diff --git a/Documentation/laptops/laptop-mode.txt b/Documentation/admin-guide/laptops/laptop-mode.rst index 1c707fc9b141..c984c4262f2e 100644 --- a/Documentation/laptops/laptop-mode.txt +++ b/Documentation/admin-guide/laptops/laptop-mode.rst @@ -1,8 +1,11 @@ +=============================================== How to conserve battery power using laptop-mode ------------------------------------------------ +=============================================== Document Author: Bart Samwel (bart@samwel.tk) + Date created: January 2, 2004 + Last modified: December 06, 2004 Introduction @@ -12,17 +15,16 @@ Laptop mode is used to minimize the time that the hard disk needs to be spun up, to conserve battery power on laptops. It has been reported to cause significant power savings. -Contents --------- +.. Contents -* Introduction -* Installation -* Caveats -* The Details -* Tips & Tricks -* Control script -* ACPI integration -* Monitoring tool + * Introduction + * Installation + * Caveats + * The Details + * Tips & Tricks + * Control script + * ACPI integration + * Monitoring tool Installation @@ -33,7 +35,7 @@ or anything. Simply install all the files included in this document, and laptop mode will automatically be started when you're on battery. For your convenience, a tarball containing an installer can be downloaded at: -http://www.samwel.tk/laptop_mode/laptop_mode/ + http://www.samwel.tk/laptop_mode/laptop_mode/ To configure laptop mode, you need to edit the configuration file, which is located in /etc/default/laptop-mode on Debian-based systems, or in @@ -209,7 +211,7 @@ Tips & Tricks this on powerbooks too. I hope that this is a piece of information that might be useful to the Laptop Mode patch or its users." -* In syslog.conf, you can prefix entries with a dash ``-'' to omit syncing the +* In syslog.conf, you can prefix entries with a dash `-` to omit syncing the file after every logging. When you're using laptop-mode and your disk doesn't spin down, this is a likely culprit. @@ -233,83 +235,82 @@ configuration file It should be installed as /etc/default/laptop-mode on Debian, and as /etc/sysconfig/laptop-mode on Red Hat, SUSE, Mandrake, and other work-alikes. ---------------------CONFIG FILE BEGIN------------------------------------------- -# Maximum time, in seconds, of hard drive spindown time that you are -# comfortable with. Worst case, it's possible that you could lose this -# amount of work if your battery fails you while in laptop mode. -#MAX_AGE=600 - -# Automatically disable laptop mode when the number of minutes of battery -# that you have left goes below this threshold. -MINIMUM_BATTERY_MINUTES=10 - -# Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG -# by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk -# will read a complete MP3 at once, and will then spin down while the MP3/OGG is -# playing. -#READAHEAD=4096 - -# Shall we remount journaled fs. with appropriate commit interval? (1=yes) -#DO_REMOUNTS=1 - -# And shall we add the "noatime" option to that as well? (1=yes) -#DO_REMOUNT_NOATIME=1 - -# Dirty synchronous ratio. At this percentage of dirty pages the process -# which -# calls write() does its own writeback -#DIRTY_RATIO=40 - -# -# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been -# exceeded, the kernel will wake flusher threads which will then reduce the -# amount of dirty memory to dirty_background_ratio. Set this nice and low, -# so once some writeout has commenced, we do a lot of it. -# -#DIRTY_BACKGROUND_RATIO=5 - -# kernel default dirty buffer age -#DEF_AGE=30 -#DEF_UPDATE=5 -#DEF_DIRTY_BACKGROUND_RATIO=10 -#DEF_DIRTY_RATIO=40 -#DEF_XFS_AGE_BUFFER=15 -#DEF_XFS_SYNC_INTERVAL=30 -#DEF_XFS_BUFD_INTERVAL=1 - -# This must be adjusted manually to the value of HZ in the running kernel -# on 2.4, until the XFS people change their 2.4 external interfaces to work in -# centisecs. This can be automated, but it's a work in progress that still -# needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for -# external interfaces, and that is currently always set to 100. So you don't -# need to change this on 2.6. -#XFS_HZ=100 - -# Should the maximum CPU frequency be adjusted down while on battery? -# Requires CPUFreq to be setup. -# See Documentation/admin-guide/pm/cpufreq.rst for more info -#DO_CPU=0 - -# When on battery what is the maximum CPU speed that the system should -# use? Legal values are "slowest" for the slowest speed that your -# CPU is able to operate at, or a value listed in: -# /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies -# Only applicable if DO_CPU=1. -#CPU_MAXFREQ=slowest - -# Idle timeout for your hard drive (man hdparm for valid values, -S option) -# Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4). -#AC_HD=244 -#BATT_HD=4 - -# The drives for which to adjust the idle timeout. Separate them by a space, -# e.g. HD="/dev/hda /dev/hdb". -#HD="/dev/hda" - -# Set the spindown timeout on a hard drive? -#DO_HD=1 - ---------------------CONFIG FILE END--------------------------------------------- +Config file:: + + # Maximum time, in seconds, of hard drive spindown time that you are + # comfortable with. Worst case, it's possible that you could lose this + # amount of work if your battery fails you while in laptop mode. + #MAX_AGE=600 + + # Automatically disable laptop mode when the number of minutes of battery + # that you have left goes below this threshold. + MINIMUM_BATTERY_MINUTES=10 + + # Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG + # by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk + # will read a complete MP3 at once, and will then spin down while the MP3/OGG is + # playing. + #READAHEAD=4096 + + # Shall we remount journaled fs. with appropriate commit interval? (1=yes) + #DO_REMOUNTS=1 + + # And shall we add the "noatime" option to that as well? (1=yes) + #DO_REMOUNT_NOATIME=1 + + # Dirty synchronous ratio. At this percentage of dirty pages the process + # which + # calls write() does its own writeback + #DIRTY_RATIO=40 + + # + # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been + # exceeded, the kernel will wake flusher threads which will then reduce the + # amount of dirty memory to dirty_background_ratio. Set this nice and low, + # so once some writeout has commenced, we do a lot of it. + # + #DIRTY_BACKGROUND_RATIO=5 + + # kernel default dirty buffer age + #DEF_AGE=30 + #DEF_UPDATE=5 + #DEF_DIRTY_BACKGROUND_RATIO=10 + #DEF_DIRTY_RATIO=40 + #DEF_XFS_AGE_BUFFER=15 + #DEF_XFS_SYNC_INTERVAL=30 + #DEF_XFS_BUFD_INTERVAL=1 + + # This must be adjusted manually to the value of HZ in the running kernel + # on 2.4, until the XFS people change their 2.4 external interfaces to work in + # centisecs. This can be automated, but it's a work in progress that still + # needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for + # external interfaces, and that is currently always set to 100. So you don't + # need to change this on 2.6. + #XFS_HZ=100 + + # Should the maximum CPU frequency be adjusted down while on battery? + # Requires CPUFreq to be setup. + # See Documentation/admin-guide/pm/cpufreq.rst for more info + #DO_CPU=0 + + # When on battery what is the maximum CPU speed that the system should + # use? Legal values are "slowest" for the slowest speed that your + # CPU is able to operate at, or a value listed in: + # /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies + # Only applicable if DO_CPU=1. + #CPU_MAXFREQ=slowest + + # Idle timeout for your hard drive (man hdparm for valid values, -S option) + # Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4). + #AC_HD=244 + #BATT_HD=4 + + # The drives for which to adjust the idle timeout. Separate them by a space, + # e.g. HD="/dev/hda /dev/hdb". + #HD="/dev/hda" + + # Set the spindown timeout on a hard drive? + #DO_HD=1 Control script @@ -318,125 +319,126 @@ Control script Please note that this control script works for the Linux 2.4 and 2.6 series (thanks to Kiko Piris). ---------------------CONTROL SCRIPT BEGIN---------------------------------------- -#!/bin/bash - -# start or stop laptop_mode, best run by a power management daemon when -# ac gets connected/disconnected from a laptop -# -# install as /sbin/laptop_mode -# -# Contributors to this script: Kiko Piris -# Bart Samwel -# Micha Feigin -# Andrew Morton -# Herve Eychenne -# Dax Kelson -# -# Original Linux 2.4 version by: Jens Axboe - -############################################################################# - -# Source config -if [ -f /etc/default/laptop-mode ] ; then +Control script:: + + #!/bin/bash + + # start or stop laptop_mode, best run by a power management daemon when + # ac gets connected/disconnected from a laptop + # + # install as /sbin/laptop_mode + # + # Contributors to this script: Kiko Piris + # Bart Samwel + # Micha Feigin + # Andrew Morton + # Herve Eychenne + # Dax Kelson + # + # Original Linux 2.4 version by: Jens Axboe + + ############################################################################# + + # Source config + if [ -f /etc/default/laptop-mode ] ; then # Debian . /etc/default/laptop-mode -elif [ -f /etc/sysconfig/laptop-mode ] ; then + elif [ -f /etc/sysconfig/laptop-mode ] ; then # Others - . /etc/sysconfig/laptop-mode -fi - -# Don't raise an error if the config file is incomplete -# set defaults instead: - -# Maximum time, in seconds, of hard drive spindown time that you are -# comfortable with. Worst case, it's possible that you could lose this -# amount of work if your battery fails you while in laptop mode. -MAX_AGE=${MAX_AGE:-'600'} - -# Read-ahead, in kilobytes -READAHEAD=${READAHEAD:-'4096'} - -# Shall we remount journaled fs. with appropriate commit interval? (1=yes) -DO_REMOUNTS=${DO_REMOUNTS:-'1'} - -# And shall we add the "noatime" option to that as well? (1=yes) -DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'} - -# Shall we adjust the idle timeout on a hard drive? -DO_HD=${DO_HD:-'1'} - -# Adjust idle timeout on which hard drive? -HD="${HD:-'/dev/hda'}" - -# spindown time for HD (hdparm -S values) -AC_HD=${AC_HD:-'244'} -BATT_HD=${BATT_HD:-'4'} - -# Dirty synchronous ratio. At this percentage of dirty pages the process which -# calls write() does its own writeback -DIRTY_RATIO=${DIRTY_RATIO:-'40'} - -# cpu frequency scaling -# See Documentation/admin-guide/pm/cpufreq.rst for more info -DO_CPU=${CPU_MANAGE:-'0'} -CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'} - -# -# Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been -# exceeded, the kernel will wake flusher threads which will then reduce the -# amount of dirty memory to dirty_background_ratio. Set this nice and low, -# so once some writeout has commenced, we do a lot of it. -# -DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'} - -# kernel default dirty buffer age -DEF_AGE=${DEF_AGE:-'30'} -DEF_UPDATE=${DEF_UPDATE:-'5'} -DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'} -DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'} -DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'} -DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'} -DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'} - -# This must be adjusted manually to the value of HZ in the running kernel -# on 2.4, until the XFS people change their 2.4 external interfaces to work in -# centisecs. This can be automated, but it's a work in progress that still needs -# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external -# interfaces, and that is currently always set to 100. So you don't need to -# change this on 2.6. -XFS_HZ=${XFS_HZ:-'100'} - -############################################################################# - -KLEVEL="$(uname -r | - { + . /etc/sysconfig/laptop-mode + fi + + # Don't raise an error if the config file is incomplete + # set defaults instead: + + # Maximum time, in seconds, of hard drive spindown time that you are + # comfortable with. Worst case, it's possible that you could lose this + # amount of work if your battery fails you while in laptop mode. + MAX_AGE=${MAX_AGE:-'600'} + + # Read-ahead, in kilobytes + READAHEAD=${READAHEAD:-'4096'} + + # Shall we remount journaled fs. with appropriate commit interval? (1=yes) + DO_REMOUNTS=${DO_REMOUNTS:-'1'} + + # And shall we add the "noatime" option to that as well? (1=yes) + DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'} + + # Shall we adjust the idle timeout on a hard drive? + DO_HD=${DO_HD:-'1'} + + # Adjust idle timeout on which hard drive? + HD="${HD:-'/dev/hda'}" + + # spindown time for HD (hdparm -S values) + AC_HD=${AC_HD:-'244'} + BATT_HD=${BATT_HD:-'4'} + + # Dirty synchronous ratio. At this percentage of dirty pages the process which + # calls write() does its own writeback + DIRTY_RATIO=${DIRTY_RATIO:-'40'} + + # cpu frequency scaling + # See Documentation/admin-guide/pm/cpufreq.rst for more info + DO_CPU=${CPU_MANAGE:-'0'} + CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'} + + # + # Allowed dirty background ratio, in percent. Once DIRTY_RATIO has been + # exceeded, the kernel will wake flusher threads which will then reduce the + # amount of dirty memory to dirty_background_ratio. Set this nice and low, + # so once some writeout has commenced, we do a lot of it. + # + DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'} + + # kernel default dirty buffer age + DEF_AGE=${DEF_AGE:-'30'} + DEF_UPDATE=${DEF_UPDATE:-'5'} + DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'} + DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'} + DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'} + DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'} + DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'} + + # This must be adjusted manually to the value of HZ in the running kernel + # on 2.4, until the XFS people change their 2.4 external interfaces to work in + # centisecs. This can be automated, but it's a work in progress that still needs + # some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external + # interfaces, and that is currently always set to 100. So you don't need to + # change this on 2.6. + XFS_HZ=${XFS_HZ:-'100'} + + ############################################################################# + + KLEVEL="$(uname -r | + { IFS='.' read a b c echo $a.$b } -)" -case "$KLEVEL" in + )" + case "$KLEVEL" in "2.4"|"2.6") ;; *) echo "Unhandled kernel version: $KLEVEL ('uname -r' = '$(uname -r)')" >&2 exit 1 ;; -esac + esac -if [ ! -e /proc/sys/vm/laptop_mode ] ; then + if [ ! -e /proc/sys/vm/laptop_mode ] ; then echo "Kernel is not patched with laptop_mode patch." >&2 exit 1 -fi + fi -if [ ! -w /proc/sys/vm/laptop_mode ] ; then + if [ ! -w /proc/sys/vm/laptop_mode ] ; then echo "You do not have enough privileges to enable laptop_mode." >&2 exit 1 -fi + fi -# Remove an option (the first parameter) of the form option=<number> from -# a mount options string (the rest of the parameters). -parse_mount_opts () { + # Remove an option (the first parameter) of the form option=<number> from + # a mount options string (the rest of the parameters). + parse_mount_opts () { OPT="$1" shift echo ",$*," | sed \ @@ -444,11 +446,11 @@ parse_mount_opts () { -e 's/,,*/,/g' \ -e 's/^,//' \ -e 's/,$//' -} + } -# Remove an option (the first parameter) without any arguments from -# a mount option string (the rest of the parameters). -parse_nonumber_mount_opts () { + # Remove an option (the first parameter) without any arguments from + # a mount option string (the rest of the parameters). + parse_nonumber_mount_opts () { OPT="$1" shift echo ",$*," | sed \ @@ -456,20 +458,20 @@ parse_nonumber_mount_opts () { -e 's/,,*/,/g' \ -e 's/^,//' \ -e 's/,$//' -} - -# Find out the state of a yes/no option (e.g. "atime"/"noatime") in -# fstab for a given filesystem, and use this state to replace the -# value of the option in another mount options string. The device -# is the first argument, the option name the second, and the default -# value the third. The remainder is the mount options string. -# -# Example: -# parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime -# -# If fstab contains, say, "rw" for this filesystem, then the result -# will be "defaults,atime". -parse_yesno_opts_wfstab () { + } + + # Find out the state of a yes/no option (e.g. "atime"/"noatime") in + # fstab for a given filesystem, and use this state to replace the + # value of the option in another mount options string. The device + # is the first argument, the option name the second, and the default + # value the third. The remainder is the mount options string. + # + # Example: + # parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime + # + # If fstab contains, say, "rw" for this filesystem, then the result + # will be "defaults,atime". + parse_yesno_opts_wfstab () { L_DEV="$1" OPT="$2" DEF_OPT="$3" @@ -491,21 +493,21 @@ parse_yesno_opts_wfstab () { # option not specified in fstab -- choose the default. echo "$PARSEDOPTS1,$DEF_OPT" fi -} - -# Find out the state of a numbered option (e.g. "commit=NNN") in -# fstab for a given filesystem, and use this state to replace the -# value of the option in another mount options string. The device -# is the first argument, and the option name the second. The -# remainder is the mount options string in which the replacement -# must be done. -# -# Example: -# parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7 -# -# If fstab contains, say, "commit=3,rw" for this filesystem, then the -# result will be "rw,commit=3". -parse_mount_opts_wfstab () { + } + + # Find out the state of a numbered option (e.g. "commit=NNN") in + # fstab for a given filesystem, and use this state to replace the + # value of the option in another mount options string. The device + # is the first argument, and the option name the second. The + # remainder is the mount options string in which the replacement + # must be done. + # + # Example: + # parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7 + # + # If fstab contains, say, "commit=3,rw" for this filesystem, then the + # result will be "rw,commit=3". + parse_mount_opts_wfstab () { L_DEV="$1" OPT="$2" shift 2 @@ -523,9 +525,9 @@ parse_mount_opts_wfstab () { # option not specified in fstab: set it to 0 echo "$PARSEDOPTS1,$OPT=0" fi -} + } -deduce_fstype () { + deduce_fstype () { MP="$1" # My root filesystem unfortunately has # type "unknown" in /etc/mtab. If we encounter @@ -538,13 +540,13 @@ deduce_fstype () { exit 0 fi done -} + } -if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then + if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then NOATIME_OPT=",noatime" -fi + fi -case "$1" in + case "$1" in start) AGE=$((100*$MAX_AGE)) XFS_AGE=$(($XFS_HZ*$MAX_AGE)) @@ -687,10 +689,9 @@ case "$1" in exit 1 ;; -esac + esac -exit 0 ---------------------CONTROL SCRIPT END------------------------------------------ + exit 0 ACPI integration @@ -701,78 +702,76 @@ kick off the laptop_mode script and run hdparm. The part that automatically disables laptop mode when the battery is low was written by Jan Topinski. ------------------/etc/acpi/events/ac_adapter BEGIN------------------------------ -event=ac_adapter -action=/etc/acpi/actions/ac.sh %e -----------------/etc/acpi/events/ac_adapter END--------------------------------- +/etc/acpi/events/ac_adapter:: + + event=ac_adapter + action=/etc/acpi/actions/ac.sh %e + +/etc/acpi/events/battery:: + event=battery.* + action=/etc/acpi/actions/battery.sh %e ------------------/etc/acpi/events/battery BEGIN--------------------------------- -event=battery.* -action=/etc/acpi/actions/battery.sh %e -----------------/etc/acpi/events/battery END------------------------------------ +/etc/acpi/actions/ac.sh:: + #!/bin/bash -----------------/etc/acpi/actions/ac.sh BEGIN----------------------------------- -#!/bin/bash + # ac on/offline event handler -# ac on/offline event handler + status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state` -status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state` + case $status in + "on-line") + /sbin/laptop_mode stop + exit 0 + ;; + "off-line") + /sbin/laptop_mode start + exit 0 + ;; + esac -case $status in - "on-line") - /sbin/laptop_mode stop - exit 0 - ;; - "off-line") - /sbin/laptop_mode start - exit 0 - ;; -esac ----------------------------/etc/acpi/actions/ac.sh END-------------------------- +/etc/acpi/actions/battery.sh:: ----------------------------/etc/acpi/actions/battery.sh BEGIN------------------- -#! /bin/bash + #! /bin/bash -# Automatically disable laptop mode when the battery almost runs out. + # Automatically disable laptop mode when the battery almost runs out. -BATT_INFO=/proc/acpi/battery/$2/state + BATT_INFO=/proc/acpi/battery/$2/state -if [[ -f /proc/sys/vm/laptop_mode ]] -then - LM=`cat /proc/sys/vm/laptop_mode` - if [[ $LM -gt 0 ]] - then - if [[ -f $BATT_INFO ]] + if [[ -f /proc/sys/vm/laptop_mode ]] + then + LM=`cat /proc/sys/vm/laptop_mode` + if [[ $LM -gt 0 ]] then - # Source the config file only now that we know we need - if [ -f /etc/default/laptop-mode ] ; then - # Debian - . /etc/default/laptop-mode - elif [ -f /etc/sysconfig/laptop-mode ] ; then - # Others - . /etc/sysconfig/laptop-mode - fi - MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'} - - ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`" - if [[ ACTION -eq "discharging" ]] - then - PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" ` - REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" ` - fi - if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES)) - then - /sbin/laptop_mode stop - fi - else - logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path." + if [[ -f $BATT_INFO ]] + then + # Source the config file only now that we know we need + if [ -f /etc/default/laptop-mode ] ; then + # Debian + . /etc/default/laptop-mode + elif [ -f /etc/sysconfig/laptop-mode ] ; then + # Others + . /etc/sysconfig/laptop-mode + fi + MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'} + + ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`" + if [[ ACTION -eq "discharging" ]] + then + PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed "s/.* \([0-9][0-9]* \).*/\1/" ` + REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed "s/.* \([0-9][0-9]* \).*/\1/" ` + fi + if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES)) + then + /sbin/laptop_mode stop + fi + else + logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path." + fi fi - fi -fi ----------------------------/etc/acpi/actions/battery.sh END-------------------- + fi Monitoring tool diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/admin-guide/laptops/lg-laptop.rst index f2c2ffe31101..ce9b14671cb9 100644 --- a/Documentation/laptops/lg-laptop.rst +++ b/Documentation/admin-guide/laptops/lg-laptop.rst @@ -1,6 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0+ -:orphan: LG Gram laptop extra features ============================= diff --git a/Documentation/laptops/sony-laptop.txt b/Documentation/admin-guide/laptops/sony-laptop.rst index 978b1e615155..9edcc7f6612f 100644 --- a/Documentation/laptops/sony-laptop.txt +++ b/Documentation/admin-guide/laptops/sony-laptop.rst @@ -1,7 +1,9 @@ +========================================= Sony Notebook Control Driver (SNC) Readme ------------------------------------------ - Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net> - Copyright (C) 2007 Mattia Dongili <malattia@linux.it> +========================================= + + - Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net> + - Copyright (C) 2007 Mattia Dongili <malattia@linux.it> This mini-driver drives the SNC and SPIC device present in the ACPI BIOS of the Sony Vaio laptops. This driver mixes both devices functions under the same @@ -10,6 +12,7 @@ obsoleted by sony-laptop now. Fn keys (hotkeys): ------------------ + Some models report hotkeys through the SNC or SPIC devices, such events are reported both through the ACPI subsystem as acpi events and through the INPUT subsystem. See the logs of /proc/bus/input/devices to find out what those @@ -28,11 +31,14 @@ If your laptop model supports it, you will find sysfs files in the /sys/class/backlight/sony/ directory. You will be able to query and set the current screen brightness: + + ====================== ========================================= brightness get/set screen brightness (an integer between 0 and 7) actual_brightness reading from this file will query the HW to get real brightness value max_brightness the maximum brightness value + ====================== ========================================= Platform specific: @@ -45,6 +51,8 @@ You then read/write integer values from/to those files by using standard UNIX tools. The files are: + + ====================== ========================================== brightness_default screen brightness which will be set when the laptop will be rebooted cdpower power on/off the internal CD drive @@ -53,21 +61,39 @@ The files are: (only in debug mode) bluetoothpower power on/off the internal bluetooth device fanspeed get/set the fan speed + ====================== ========================================== Note that some files may be missing if they are not supported by your particular laptop model. -Example usage: +Example usage:: + # echo "1" > /sys/devices/platform/sony-laptop/brightness_default -sets the lowest screen brightness for the next and later reboots, + +sets the lowest screen brightness for the next and later reboots + +:: + # echo "8" > /sys/devices/platform/sony-laptop/brightness_default -sets the highest screen brightness for the next and later reboots, + +sets the highest screen brightness for the next and later reboots + +:: + # cat /sys/devices/platform/sony-laptop/brightness_default -retrieves the value. + +retrieves the value + +:: # echo "0" > /sys/devices/platform/sony-laptop/audiopower -powers off the sound card, + +powers off the sound card + +:: + # echo "1" > /sys/devices/platform/sony-laptop/audiopower + powers on the sound card. @@ -76,7 +102,8 @@ RFkill control: More recent Vaio models expose a consistent set of ACPI methods to control radio frequency emitting devices. If you are a lucky owner of such a laptop you will find the necessary rfkill devices under -/sys/class/rfkill. Check those starting with sony-* in +/sys/class/rfkill. Check those starting with sony-* in:: + # grep . /sys/class/rfkill/*/{state,name} @@ -88,26 +115,29 @@ you are not afraid of any side effects doing strange things with your ACPI BIOS could have on your laptop), load the driver and pass the option 'debug=1'. -REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS. +REPEAT: + **DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.** In your kernel logs you will find the list of all ACPI methods the SNC device has on your laptop. * For new models you will see a long list of meaningless method names, -reading the DSDT table source should reveal that: + reading the DSDT table source should reveal that: + (1) the SNC device uses an internal capability lookup table (2) SN00 is used to find values in the lookup table (3) SN06 and SN07 are used to call into the real methods based on offsets you can obtain iterating the table using SN00 (4) SN02 used to enable events. + Some values in the capability lookup table are more or less known, see the code for all sony_call_snc_handle calls, others are more obscure. * For old models you can see the GCDP/GCDP methods used to pwer on/off -the CD drive, but there are others and they are usually different from -model to model. + the CD drive, but there are others and they are usually different from + model to model. -I HAVE NO IDEA WHAT THOSE METHODS DO. +**I HAVE NO IDEA WHAT THOSE METHODS DO.** The sony-laptop driver creates, for some of those methods (the most current ones found on several Vaio models), an entry under diff --git a/Documentation/laptops/sonypi.txt b/Documentation/admin-guide/laptops/sonypi.rst index 606bdb9ce036..c6eaaf48f7c1 100644 --- a/Documentation/laptops/sonypi.txt +++ b/Documentation/admin-guide/laptops/sonypi.rst @@ -1,11 +1,13 @@ +================================================== Sony Programmable I/O Control Device Driver Readme --------------------------------------------------- - Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net> - Copyright (C) 2001-2002 Alcôve <www.alcove.com> - Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au> - Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp> - Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp> - Copyright (C) 2000 Andrew Tridgell <tridge@samba.org> +================================================== + + - Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net> + - Copyright (C) 2001-2002 Alcôve <www.alcove.com> + - Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au> + - Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp> + - Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp> + - Copyright (C) 2000 Andrew Tridgell <tridge@samba.org> This driver enables access to the Sony Programmable I/O Control Device which can be found in many Sony Vaio laptops. Some newer Sony laptops (seems to be @@ -14,6 +16,7 @@ sonypi device and are not supported at all by this driver. It will give access (through a user space utility) to some events those laptops generate, like: + - jogdial events (the small wheel on the side of Vaios) - capture button events (only on Vaio Picturebook series) - Fn keys @@ -49,7 +52,8 @@ module argument syntax (<param>=<value> when passing the option to the module or sonypi.<param>=<value> on the kernel boot line when sonypi is statically linked into the kernel). Those options are: - minor: minor number of the misc device /dev/sonypi, + =============== ======================================================= + minor: minor number of the misc device /dev/sonypi, default is -1 (automatic allocation, see /proc/misc or kernel logs) @@ -85,17 +89,18 @@ statically linked into the kernel). Those options are: set to 0xffffffff, meaning that all possible events will be tried. You can use the following bits to construct your own event mask (from - drivers/char/sonypi.h): - SONYPI_JOGGER_MASK 0x0001 - SONYPI_CAPTURE_MASK 0x0002 - SONYPI_FNKEY_MASK 0x0004 - SONYPI_BLUETOOTH_MASK 0x0008 - SONYPI_PKEY_MASK 0x0010 - SONYPI_BACK_MASK 0x0020 - SONYPI_HELP_MASK 0x0040 - SONYPI_LID_MASK 0x0080 - SONYPI_ZOOM_MASK 0x0100 - SONYPI_THUMBPHRASE_MASK 0x0200 + drivers/char/sonypi.h):: + + SONYPI_JOGGER_MASK 0x0001 + SONYPI_CAPTURE_MASK 0x0002 + SONYPI_FNKEY_MASK 0x0004 + SONYPI_BLUETOOTH_MASK 0x0008 + SONYPI_PKEY_MASK 0x0010 + SONYPI_BACK_MASK 0x0020 + SONYPI_HELP_MASK 0x0040 + SONYPI_LID_MASK 0x0080 + SONYPI_ZOOM_MASK 0x0100 + SONYPI_THUMBPHRASE_MASK 0x0200 SONYPI_MEYE_MASK 0x0400 SONYPI_MEMORYSTICK_MASK 0x0800 SONYPI_BATTERY_MASK 0x1000 @@ -105,17 +110,18 @@ statically linked into the kernel). Those options are: created, one which interprets the jogdial events as mouse events, the other one which acts like a keyboard reporting the pressing of the special keys. + =============== ======================================================= Module use: ----------- In order to automatically load the sonypi module on use, you can put those -lines a configuration file in /etc/modprobe.d/: +lines a configuration file in /etc/modprobe.d/:: alias char-major-10-250 sonypi options sonypi minor=250 -This supposes the use of minor 250 for the sonypi device: +This supposes the use of minor 250 for the sonypi device:: # mknod /dev/sonypi c 10 250 @@ -148,5 +154,5 @@ Bugs: http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2 - since all development was done by reverse engineering, there is - _absolutely no guarantee_ that this driver will not crash your + *absolutely no guarantee* that this driver will not crash your laptop. Permanently. diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 75ef063622d2..adea0bf2acc5 100644 --- a/Documentation/laptops/thinkpad-acpi.txt +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -1,12 +1,15 @@ - ThinkPad ACPI Extras Driver +=========================== +ThinkPad ACPI Extras Driver +=========================== - Version 0.25 - October 16th, 2013 +Version 0.25 - Borislav Deianov <borislav@users.sf.net> - Henrique de Moraes Holschuh <hmh@hmh.eng.br> - http://ibm-acpi.sf.net/ +October 16th, 2013 +- Borislav Deianov <borislav@users.sf.net> +- Henrique de Moraes Holschuh <hmh@hmh.eng.br> + +http://ibm-acpi.sf.net/ This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It supports various features of these laptops which are accessible @@ -91,7 +94,8 @@ yet ready or stabilized, it is expected that this interface will change, and any and all userspace programs must deal with it. -Notes about the sysfs interface: +Notes about the sysfs interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Unlike what was done with the procfs interface, correctness when talking to the sysfs interfaces will be enforced, as will correctness in the @@ -129,6 +133,7 @@ Driver version -------------- procfs: /proc/acpi/ibm/driver + sysfs driver attribute: version The driver name and version. No commands can be written to this file. @@ -141,9 +146,13 @@ sysfs driver attribute: interface_version Version of the thinkpad-acpi sysfs interface, as an unsigned long (output in hex format: 0xAAAABBCC), where: - AAAA - major revision - BB - minor revision - CC - bugfix revision + + AAAA + - major revision + BB + - minor revision + CC + - bugfix revision The sysfs interface version changelog for the driver can be found at the end of this document. Changes to the sysfs interface done by the kernel @@ -170,6 +179,7 @@ Hot keys -------- procfs: /proc/acpi/ibm/hotkey + sysfs device attribute: hotkey_* In a ThinkPad, the ACPI HKEY handler is responsible for communicating @@ -181,7 +191,7 @@ firmware will behave in many situations. The driver enables the HKEY ("hot key") event reporting automatically when loaded, and disables it when it is removed. -The driver will report HKEY events in the following format: +The driver will report HKEY events in the following format:: ibm/hotkey HKEY 00000080 0000xxxx @@ -217,9 +227,10 @@ ThinkPads, it is still possible to support some extra hotkeys by polling the "CMOS NVRAM" at least 10 times per second. The driver attempts to enables this functionality automatically when required. -procfs notes: +procfs notes +^^^^^^^^^^^^ -The following commands can be written to the /proc/acpi/ibm/hotkey file: +The following commands can be written to the /proc/acpi/ibm/hotkey file:: echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys @@ -227,7 +238,7 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file: echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask The following commands have been deprecated and will cause the kernel -to log a warning: +to log a warning:: echo enable > /proc/acpi/ibm/hotkey -- does nothing echo disable > /proc/acpi/ibm/hotkey -- returns an error @@ -237,7 +248,8 @@ maintain maximum bug-to-bug compatibility, it does not report any masks, nor does it allow one to manipulate the hot key mask when the firmware does not support masks at all, even if NVRAM polling is in use. -sysfs notes: +sysfs notes +^^^^^^^^^^^ hotkey_bios_enabled: DEPRECATED, WILL BE REMOVED SOON. @@ -349,7 +361,8 @@ sysfs notes: This attribute has poll()/select() support. -input layer notes: +input layer notes +^^^^^^^^^^^^^^^^^ A Hot key is mapped to a single input layer EV_KEY event, possibly followed by an EV_MSC MSC_SCAN event that shall contain that key's scan @@ -362,11 +375,13 @@ remapping KEY_UNKNOWN keys. The events are available in an input device, with the following id: - Bus: BUS_HOST - vendor: 0x1014 (PCI_VENDOR_ID_IBM) or + ============== ============================== + Bus BUS_HOST + vendor 0x1014 (PCI_VENDOR_ID_IBM) or 0x17aa (PCI_VENDOR_ID_LENOVO) - product: 0x5054 ("TP") - version: 0x4101 + product 0x5054 ("TP") + version 0x4101 + ============== ============================== The version will have its LSB incremented if the keymap changes in a backwards-compatible way. The MSB shall always be 0x41 for this input @@ -380,9 +395,10 @@ backwards-compatible change for this input device. Thinkpad-acpi Hot Key event map (version 0x4101): +======= ======= ============== ============================================== ACPI Scan event code Key Notes - +======= ======= ============== ============================================== 0x1001 0x00 FN+F1 - 0x1002 0x01 FN+F2 IBM: battery (rare) @@ -426,7 +442,9 @@ event code Key Notes or toggle screen expand 0x1009 0x08 FN+F9 - - .. .. .. + +... ... ... ... + 0x100B 0x0A FN+F11 - 0x100C 0x0B FN+F12 Sleep to disk. You are always @@ -480,8 +498,11 @@ event code Key Notes 0x1018 0x17 THINKPAD ThinkPad/Access IBM/Lenovo key 0x1019 0x18 unknown -.. .. .. + +... ... ... + 0x1020 0x1F unknown +======= ======= ============== ============================================== The ThinkPad firmware does not allow one to differentiate when most hot keys are pressed or released (either that, or we don't know how to, yet). @@ -499,14 +520,17 @@ generate input device EV_KEY events. In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW events for switches: +============== ============================================== SW_RFKILL_ALL T60 and later hardware rfkill rocker switch SW_TABLET_MODE Tablet ThinkPads HKEY events 0x5009 and 0x500A +============== ============================================== -Non hotkey ACPI HKEY event map: -------------------------------- +Non hotkey ACPI HKEY event map +------------------------------ Events that are never propagated by the driver: +====== ================================================== 0x2304 System is waking up from suspend to undock 0x2305 System is waking up from suspend to eject bay 0x2404 System is waking up from hibernation to undock @@ -519,10 +543,12 @@ Events that are never propagated by the driver: 0x6000 KEYBOARD: Numlock key pressed 0x6005 KEYBOARD: Fn key pressed (TO BE VERIFIED) 0x7000 Radio Switch may have changed state +====== ================================================== Events that are propagated by the driver to userspace: +====== ===================================================== 0x2313 ALARM: System is waking up from suspend because the battery is nearly empty 0x2413 ALARM: System is waking up from hibernation because @@ -544,6 +570,7 @@ Events that are propagated by the driver to userspace: 0x6040 Nvidia Optimus/AC adapter related (TO BE VERIFIED) 0x60C0 X1 Yoga 2016, Tablet mode status changed 0x60F0 Thermal Transformation changed (GMTS, Windows) +====== ===================================================== Battery nearly empty alarms are a last resort attempt to get the operating system to hibernate or shutdown cleanly (0x2313), or shutdown @@ -562,7 +589,8 @@ cycle, or a system shutdown. Obviously, something is very wrong if this happens. -Brightness hotkey notes: +Brightness hotkey notes +^^^^^^^^^^^^^^^^^^^^^^^ Don't mess with the brightness hotkeys in a Thinkpad. If you want notifications for OSD, use the sysfs backlight class event support. @@ -579,7 +607,9 @@ Bluetooth --------- procfs: /proc/acpi/ibm/bluetooth + sysfs device attribute: bluetooth_enable (deprecated) + sysfs rfkill class: switch "tpacpi_bluetooth_sw" This feature shows the presence and current state of a ThinkPad @@ -588,36 +618,39 @@ Bluetooth device in the internal ThinkPad CDC slot. If the ThinkPad supports it, the Bluetooth state is stored in NVRAM, so it is kept across reboots and power-off. -Procfs notes: +Procfs notes +^^^^^^^^^^^^ -If Bluetooth is installed, the following commands can be used: +If Bluetooth is installed, the following commands can be used:: echo enable > /proc/acpi/ibm/bluetooth echo disable > /proc/acpi/ibm/bluetooth -Sysfs notes: +Sysfs notes +^^^^^^^^^^^ If the Bluetooth CDC card is installed, it can be enabled / disabled through the "bluetooth_enable" thinkpad-acpi device attribute, and its current status can also be queried. enable: - 0: disables Bluetooth / Bluetooth is disabled - 1: enables Bluetooth / Bluetooth is enabled. + + - 0: disables Bluetooth / Bluetooth is disabled + - 1: enables Bluetooth / Bluetooth is enabled. Note: this interface has been superseded by the generic rfkill class. It has been deprecated, and it will be removed in year 2010. rfkill controller switch "tpacpi_bluetooth_sw": refer to - Documentation/rfkill.txt for details. + Documentation/driver-api/rfkill.rst for details. Video output control -- /proc/acpi/ibm/video -------------------------------------------- This feature allows control over the devices used for video output - -LCD, CRT or DVI (if available). The following commands are available: +LCD, CRT or DVI (if available). The following commands are available:: echo lcd_enable > /proc/acpi/ibm/video echo lcd_disable > /proc/acpi/ibm/video @@ -630,9 +663,10 @@ LCD, CRT or DVI (if available). The following commands are available: echo expand_toggle > /proc/acpi/ibm/video echo video_switch > /proc/acpi/ibm/video -NOTE: Access to this feature is restricted to processes owning the -CAP_SYS_ADMIN capability for safety reasons, as it can interact badly -enough with some versions of X.org to crash it. +NOTE: + Access to this feature is restricted to processes owning the + CAP_SYS_ADMIN capability for safety reasons, as it can interact badly + enough with some versions of X.org to crash it. Each video output device can be enabled or disabled individually. Reading /proc/acpi/ibm/video shows the status of each device. @@ -665,18 +699,21 @@ ThinkLight control ------------------ procfs: /proc/acpi/ibm/light + sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED -procfs notes: +procfs notes +^^^^^^^^^^^^ The ThinkLight status can be read and set through the procfs interface. A few models which do not make the status available will show the ThinkLight -status as "unknown". The available commands are: +status as "unknown". The available commands are:: echo on > /proc/acpi/ibm/light echo off > /proc/acpi/ibm/light -sysfs notes: +sysfs notes +^^^^^^^^^^^ The ThinkLight sysfs interface is documented by the LED class documentation, in Documentation/leds/leds-class.rst. The ThinkLight LED name @@ -691,6 +728,7 @@ CMOS/UCMS control ----------------- procfs: /proc/acpi/ibm/cmos + sysfs device attribute: cmos_command This feature is mostly used internally by the ACPI firmware to keep the legacy @@ -707,16 +745,16 @@ The range of valid cmos command numbers is 0 to 21, but not all have an effect and the behavior varies from model to model. Here is the behavior on the X40 (tpb is the ThinkPad Buttons utility): - 0 - Related to "Volume down" key press - 1 - Related to "Volume up" key press - 2 - Related to "Mute on" key press - 3 - Related to "Access IBM" key press - 4 - Related to "LCD brightness up" key press - 5 - Related to "LCD brightness down" key press - 11 - Related to "toggle screen expansion" key press/function - 12 - Related to "ThinkLight on" - 13 - Related to "ThinkLight off" - 14 - Related to "ThinkLight" key press (toggle ThinkLight) + - 0 - Related to "Volume down" key press + - 1 - Related to "Volume up" key press + - 2 - Related to "Mute on" key press + - 3 - Related to "Access IBM" key press + - 4 - Related to "LCD brightness up" key press + - 5 - Related to "LCD brightness down" key press + - 11 - Related to "toggle screen expansion" key press/function + - 12 - Related to "ThinkLight on" + - 13 - Related to "ThinkLight off" + - 14 - Related to "ThinkLight" key press (toggle ThinkLight) The cmos command interface is prone to firmware split-brain problems, as in newer ThinkPads it is just a compatibility layer. Do not use it, it is @@ -748,9 +786,10 @@ are aware of the consequences are welcome to enabling it. Audio mute and microphone mute LEDs are supported, but currently not visible to userspace. They are used by the snd-hda-intel audio driver. -procfs notes: +procfs notes +^^^^^^^^^^^^ -The available commands are: +The available commands are:: echo '<LED number> on' >/proc/acpi/ibm/led echo '<LED number> off' >/proc/acpi/ibm/led @@ -760,23 +799,24 @@ The <LED number> range is 0 to 15. The set of LEDs that can be controlled varies from model to model. Here is the common ThinkPad mapping: - 0 - power - 1 - battery (orange) - 2 - battery (green) - 3 - UltraBase/dock - 4 - UltraBay - 5 - UltraBase battery slot - 6 - (unknown) - 7 - standby - 8 - dock status 1 - 9 - dock status 2 - 10, 11 - (unknown) - 12 - thinkvantage - 13, 14, 15 - (unknown) + - 0 - power + - 1 - battery (orange) + - 2 - battery (green) + - 3 - UltraBase/dock + - 4 - UltraBay + - 5 - UltraBase battery slot + - 6 - (unknown) + - 7 - standby + - 8 - dock status 1 + - 9 - dock status 2 + - 10, 11 - (unknown) + - 12 - thinkvantage + - 13, 14, 15 - (unknown) All of the above can be turned on and off and can be made to blink. -sysfs notes: +sysfs notes +^^^^^^^^^^^ The ThinkPad LED sysfs interface is described in detail by the LED class documentation, in Documentation/leds/leds-class.rst. @@ -815,7 +855,7 @@ The BEEP method is used internally by the ACPI firmware to provide audible alerts in various situations. This feature allows the same sounds to be triggered manually. -The commands are non-negative integer numbers: +The commands are non-negative integer numbers:: echo <number> >/proc/acpi/ibm/beep @@ -823,25 +863,26 @@ The valid <number> range is 0 to 17. Not all numbers trigger sounds and the sounds vary from model to model. Here is the behavior on the X40: - 0 - stop a sound in progress (but use 17 to stop 16) - 2 - two beeps, pause, third beep ("low battery") - 3 - single beep - 4 - high, followed by low-pitched beep ("unable") - 5 - single beep - 6 - very high, followed by high-pitched beep ("AC/DC") - 7 - high-pitched beep - 9 - three short beeps - 10 - very long beep - 12 - low-pitched beep - 15 - three high-pitched beeps repeating constantly, stop with 0 - 16 - one medium-pitched beep repeating constantly, stop with 17 - 17 - stop 16 + - 0 - stop a sound in progress (but use 17 to stop 16) + - 2 - two beeps, pause, third beep ("low battery") + - 3 - single beep + - 4 - high, followed by low-pitched beep ("unable") + - 5 - single beep + - 6 - very high, followed by high-pitched beep ("AC/DC") + - 7 - high-pitched beep + - 9 - three short beeps + - 10 - very long beep + - 12 - low-pitched beep + - 15 - three high-pitched beeps repeating constantly, stop with 0 + - 16 - one medium-pitched beep repeating constantly, stop with 17 + - 17 - stop 16 Temperature sensors ------------------- procfs: /proc/acpi/ibm/thermal + sysfs device attributes: (hwmon "thinkpad") temp*_input Most ThinkPads include six or more separate temperature sensors but only @@ -850,10 +891,14 @@ feature shows readings from up to eight different sensors on older ThinkPads, and up to sixteen different sensors on newer ThinkPads. For example, on the X40, a typical output may be: -temperatures: 42 42 45 41 36 -128 33 -128 + +temperatures: + 42 42 45 41 36 -128 33 -128 On the T43/p, a typical output may be: -temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128 + +temperatures: + 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128 The mapping of thermal sensors to physical locations varies depending on system-board model (and thus, on ThinkPad model). @@ -863,46 +908,53 @@ tries to track down these locations for various models. Most (newer?) models seem to follow this pattern: -1: CPU -2: (depends on model) -3: (depends on model) -4: GPU -5: Main battery: main sensor -6: Bay battery: main sensor -7: Main battery: secondary sensor -8: Bay battery: secondary sensor -9-15: (depends on model) +- 1: CPU +- 2: (depends on model) +- 3: (depends on model) +- 4: GPU +- 5: Main battery: main sensor +- 6: Bay battery: main sensor +- 7: Main battery: secondary sensor +- 8: Bay battery: secondary sensor +- 9-15: (depends on model) For the R51 (source: Thomas Gruber): -2: Mini-PCI -3: Internal HDD + +- 2: Mini-PCI +- 3: Internal HDD For the T43, T43/p (source: Shmidoax/Thinkwiki.org) http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p -2: System board, left side (near PCMCIA slot), reported as HDAPS temp -3: PCMCIA slot -9: MCH (northbridge) to DRAM Bus -10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI - card, under touchpad -11: Power regulator, underside of system board, below F2 key + +- 2: System board, left side (near PCMCIA slot), reported as HDAPS temp +- 3: PCMCIA slot +- 9: MCH (northbridge) to DRAM Bus +- 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI + card, under touchpad +- 11: Power regulator, underside of system board, below F2 key The A31 has a very atypical layout for the thermal sensors (source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) -1: CPU -2: Main Battery: main sensor -3: Power Converter -4: Bay Battery: main sensor -5: MCH (northbridge) -6: PCMCIA/ambient -7: Main Battery: secondary sensor -8: Bay Battery: secondary sensor +- 1: CPU +- 2: Main Battery: main sensor +- 3: Power Converter +- 4: Bay Battery: main sensor +- 5: MCH (northbridge) +- 6: PCMCIA/ambient +- 7: Main Battery: secondary sensor +- 8: Bay Battery: secondary sensor + + +Procfs notes +^^^^^^^^^^^^ -Procfs notes: Readings from sensors that are not available return -128. No commands can be written to this file. -Sysfs notes: +Sysfs notes +^^^^^^^^^^^ + Sensors that are not available return the ENXIO error. This status may change at runtime, as there are hotplug thermal sensors, like those inside the batteries and docks. @@ -921,6 +973,7 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec Use it to determine the register holding the fan speed on some models. To do that, do the following: + - make sure the battery is fully charged - make sure the fan is running - use above mentioned tool to read out the EC @@ -941,6 +994,7 @@ LCD brightness control ---------------------- procfs: /proc/acpi/ibm/brightness + sysfs backlight device "thinkpad_screen" This feature allows software control of the LCD brightness on ThinkPad @@ -985,15 +1039,17 @@ brightness_enable=0 forces it to be disabled. brightness_enable=1 forces it to be enabled when available, even if the standard ACPI interface is also available. -Procfs notes: +Procfs notes +^^^^^^^^^^^^ - The available commands are: +The available commands are:: echo up >/proc/acpi/ibm/brightness echo down >/proc/acpi/ibm/brightness echo 'level <level>' >/proc/acpi/ibm/brightness -Sysfs notes: +Sysfs notes +^^^^^^^^^^^ The interface is implemented through the backlight sysfs class, which is poorly documented at this time. @@ -1038,6 +1094,7 @@ Volume control (Console Audio control) -------------------------------------- procfs: /proc/acpi/ibm/volume + ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC" NOTE: by default, the volume control interface operates in read-only @@ -1053,7 +1110,8 @@ Software volume control should be done only in the main AC97/HDA mixer. -About the ThinkPad Console Audio control: +About the ThinkPad Console Audio control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ThinkPads have a built-in amplifier and muting circuit that drives the console headphone and speakers. This circuit is after the main AC97 @@ -1092,13 +1150,14 @@ normal key presses to the operating system (thinkpad-acpi is not involved). -The ThinkPad-ACPI volume control: +The ThinkPad-ACPI volume control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The preferred way to interact with the Console Audio control is the ALSA interface. The legacy procfs interface allows one to read the current state, -and if volume control is enabled, accepts the following commands: +and if volume control is enabled, accepts the following commands:: echo up >/proc/acpi/ibm/volume echo down >/proc/acpi/ibm/volume @@ -1137,13 +1196,15 @@ Fan control and monitoring: fan speed, fan enable/disable --------------------------------------------------------- procfs: /proc/acpi/ibm/fan -sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, - pwm1_enable, fan2_input + +sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, pwm1_enable, fan2_input + sysfs hwmon driver attributes: fan_watchdog -NOTE NOTE NOTE: fan control operations are disabled by default for -safety reasons. To enable them, the module parameter "fan_control=1" -must be given to thinkpad-acpi. +NOTE NOTE NOTE: + fan control operations are disabled by default for + safety reasons. To enable them, the module parameter "fan_control=1" + must be given to thinkpad-acpi. This feature attempts to show the current fan speed, control mode and other fan data that might be available. The speed is read directly @@ -1154,7 +1215,8 @@ value on other models. Some Lenovo ThinkPads support a secondary fan. This fan cannot be controlled separately, it shares the main fan control. -Fan levels: +Fan levels +^^^^^^^^^^ Most ThinkPad fans work in "levels" at the firmware interface. Level 0 stops the fan. The higher the level, the higher the fan speed, although @@ -1209,9 +1271,10 @@ therefore, not suitable to protect against fan mode changes made through means other than the "enable", "disable", and "level" procfs fan commands, or the hwmon fan control sysfs interface. -Procfs notes: +Procfs notes +^^^^^^^^^^^^ -The fan may be enabled or disabled with the following commands: +The fan may be enabled or disabled with the following commands:: echo enable >/proc/acpi/ibm/fan echo disable >/proc/acpi/ibm/fan @@ -1219,7 +1282,7 @@ The fan may be enabled or disabled with the following commands: Placing a fan on level 0 is the same as disabling it. Enabling a fan will try to place it in a safe level if it is too slow or disabled. -The fan level can be controlled with the command: +The fan level can be controlled with the command:: echo 'level <level>' > /proc/acpi/ibm/fan @@ -1231,7 +1294,7 @@ compatibility. On the X31 and X40 (and ONLY on those models), the fan speed can be controlled to a certain degree. Once the fan is running, it can be -forced to run faster or slower with the following command: +forced to run faster or slower with the following command:: echo 'speed <speed>' > /proc/acpi/ibm/fan @@ -1241,13 +1304,14 @@ effect or the fan speed eventually settles somewhere in that range. The fan cannot be stopped or started with this command. This functionality is incomplete, and not available through the sysfs interface. -To program the safety watchdog, use the "watchdog" command. +To program the safety watchdog, use the "watchdog" command:: echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan If you want to disable the watchdog, use 0 as the interval. -Sysfs notes: +Sysfs notes +^^^^^^^^^^^ The sysfs interface follows the hwmon subsystem guidelines for the most part, and the exception is the fan safety watchdog. @@ -1261,10 +1325,10 @@ to the firmware). Features not yet implemented by the driver return ENOSYS. hwmon device attribute pwm1_enable: - 0: PWM offline (fan is set to full-speed mode) - 1: Manual PWM control (use pwm1 to set fan level) - 2: Hardware PWM control (EC "auto" mode) - 3: reserved (Software PWM control, not implemented yet) + - 0: PWM offline (fan is set to full-speed mode) + - 1: Manual PWM control (use pwm1 to set fan level) + - 2: Hardware PWM control (EC "auto" mode) + - 3: reserved (Software PWM control, not implemented yet) Modes 0 and 2 are not supported by all ThinkPads, and the driver is not always able to detect this. If it does know a @@ -1304,7 +1368,9 @@ WAN --- procfs: /proc/acpi/ibm/wan + sysfs device attribute: wwan_enable (deprecated) + sysfs rfkill class: switch "tpacpi_wwan_sw" This feature shows the presence and current state of the built-in @@ -1316,29 +1382,31 @@ so it is kept across reboots and power-off. It was tested on a Lenovo ThinkPad X60. It should probably work on other ThinkPad models which come with this module installed. -Procfs notes: +Procfs notes +^^^^^^^^^^^^ -If the W-WAN card is installed, the following commands can be used: +If the W-WAN card is installed, the following commands can be used:: echo enable > /proc/acpi/ibm/wan echo disable > /proc/acpi/ibm/wan -Sysfs notes: +Sysfs notes +^^^^^^^^^^^ If the W-WAN card is installed, it can be enabled / disabled through the "wwan_enable" thinkpad-acpi device attribute, and its current status can also be queried. enable: - 0: disables WWAN card / WWAN card is disabled - 1: enables WWAN card / WWAN card is enabled. + - 0: disables WWAN card / WWAN card is disabled + - 1: enables WWAN card / WWAN card is enabled. Note: this interface has been superseded by the generic rfkill class. It has been deprecated, and it will be removed in year 2010. rfkill controller switch "tpacpi_wwan_sw": refer to - Documentation/rfkill.txt for details. + Documentation/driver-api/rfkill.rst for details. EXPERIMENTAL: UWB @@ -1354,10 +1422,11 @@ sysfs rfkill class: switch "tpacpi_uwb_sw" This feature exports an rfkill controller for the UWB device, if one is present and enabled in the BIOS. -Sysfs notes: +Sysfs notes +^^^^^^^^^^^ rfkill controller switch "tpacpi_uwb_sw": refer to - Documentation/rfkill.txt for details. + Documentation/driver-api/rfkill.rst for details. Adaptive keyboard ----------------- @@ -1368,11 +1437,11 @@ This sysfs attribute controls the keyboard "face" that will be shown on the Lenovo X1 Carbon 2nd gen (2014)'s adaptive keyboard. The value can be read and set. -1 = Home mode -2 = Web-browser mode -3 = Web-conference mode -4 = Function mode -5 = Layflat mode +- 1 = Home mode +- 2 = Web-browser mode +- 3 = Web-conference mode +- 4 = Function mode +- 5 = Layflat mode For more details about which buttons will appear depending on the mode, please review the laptop's user guide: @@ -1382,13 +1451,13 @@ Multiple Commands, Module Parameters ------------------------------------ Multiple commands can be written to the proc files in one shot by -separating them with commas, for example: +separating them with commas, for example:: echo enable,0xffff > /proc/acpi/ibm/hotkey echo lcd_disable,crt_enable > /proc/acpi/ibm/video Commands can also be specified when loading the thinkpad-acpi module, -for example: +for example:: modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable @@ -1397,14 +1466,16 @@ Enabling debugging output ------------------------- The module takes a debug parameter which can be used to selectively -enable various classes of debugging output, for example: +enable various classes of debugging output, for example:: modprobe thinkpad_acpi debug=0xffff will enable all debugging output classes. It takes a bitmask, so to enable more than one output class, just add their values. + ============= ====================================== Debug bitmask Description + ============= ====================================== 0x8000 Disclose PID of userspace programs accessing some functions of the driver 0x0001 Initialization and probing @@ -1415,6 +1486,7 @@ to enable more than one output class, just add their values. 0x0010 Fan control 0x0020 Backlight brightness 0x0040 Audio mixer/volume control + ============= ====================================== There is also a kernel build option to enable more debugging information, which may be necessary to debug driver problems. @@ -1432,8 +1504,10 @@ the module parameter force_load=1. Regardless of whether this works or not, please contact ibm-acpi-devel@lists.sourceforge.net with a report. -Sysfs interface changelog: +Sysfs interface changelog +^^^^^^^^^^^^^^^^^^^^^^^^^ +========= =============================================================== 0x000100: Initial sysfs support, as a single platform driver and device. 0x000200: Hot key support for 32 hot keys, and radio slider switch @@ -1485,3 +1559,4 @@ Sysfs interface changelog: 0x030000: Thermal and fan sysfs attributes were moved to the hwmon device instead of being attached to the backing platform device. +========= =============================================================== diff --git a/Documentation/laptops/toshiba_haps.txt b/Documentation/admin-guide/laptops/toshiba_haps.rst index 0c1d88dedbde..d28b6c3f2849 100644 --- a/Documentation/laptops/toshiba_haps.txt +++ b/Documentation/admin-guide/laptops/toshiba_haps.rst @@ -1,18 +1,19 @@ -Kernel driver toshiba_haps +==================================== Toshiba HDD Active Protection Sensor ==================================== +Kernel driver: toshiba_haps + Author: Azael Avalos <coproscefalo@gmail.com> -0. Contents ------------ +.. 0. Contents -1. Description -2. Interface -3. Accelerometer axes -4. Supported devices -5. Usage + 1. Description + 2. Interface + 3. Accelerometer axes + 4. Supported devices + 5. Usage 1. Description @@ -32,17 +33,20 @@ file to set the desired protection level or sensor sensibility. ------------ This device comes with 3 methods: -_STA - Checks existence of the device, returning Zero if the device does not + +==== ===================================================================== +_STA Checks existence of the device, returning Zero if the device does not exists or is not supported. -PTLV - Sets the desired protection level. -RSSS - Shuts down the HDD protection interface for a few seconds, +PTLV Sets the desired protection level. +RSSS Shuts down the HDD protection interface for a few seconds, then restores normal operation. +==== ===================================================================== Note: -The presence of Solid State Drives (SSD) can make this driver to fail loading, -given the fact that such drives have no movable parts, and thus, not requiring -any "protection" as well as failing during the evaluation of the _STA method -found under this device. + The presence of Solid State Drives (SSD) can make this driver to fail loading, + given the fact that such drives have no movable parts, and thus, not requiring + any "protection" as well as failing during the evaluation of the _STA method + found under this device. 3. Accelerometer axes @@ -66,11 +70,18 @@ conventional HDD and not only SSD, or a combination of both HDD and SSD. -------- The sysfs files under /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/ are: -protection_level - The protection_level is readable and writeable, and + +================ ============================================================ +protection_level The protection_level is readable and writeable, and provides a way to let userspace query the current protection level, as well as set the desired protection level, the - available protection levels are: - 0 - Disabled | 1 - Low | 2 - Medium | 3 - High -reset_protection - The reset_protection entry is writeable only, being "1" + available protection levels are:: + + ============ ======= ========== ======== + 0 - Disabled 1 - Low 2 - Medium 3 - High + ============ ======= ========== ======== + +reset_protection The reset_protection entry is writeable only, being "1" the only parameter it accepts, it is used to trigger a reset of the protection interface. +================ ============================================================ diff --git a/Documentation/auxdisplay/lcd-panel-cgram.txt b/Documentation/admin-guide/lcd-panel-cgram.rst index 7f82c905763d..a3eb00c62f53 100644 --- a/Documentation/auxdisplay/lcd-panel-cgram.txt +++ b/Documentation/admin-guide/lcd-panel-cgram.rst @@ -1,3 +1,7 @@ +====================================== +Parallel port LCD/Keypad Panel support +====================================== + 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 @@ -7,7 +11,7 @@ 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 : +examples:: printf "\e[LG0010101050D1F0C04;" => 0 = [enter] printf "\e[LG1040E1F0000000000;" => 1 = [up] @@ -21,4 +25,3 @@ examples : printf "\e[LG00002061E1E060200;" => small speaker Willy - diff --git a/Documentation/ldm.txt b/Documentation/admin-guide/ldm.rst index 12c571368e73..12c571368e73 100644 --- a/Documentation/ldm.txt +++ b/Documentation/admin-guide/ldm.rst diff --git a/Documentation/lockup-watchdogs.txt b/Documentation/admin-guide/lockup-watchdogs.rst index 290840c160af..290840c160af 100644 --- a/Documentation/lockup-watchdogs.txt +++ b/Documentation/admin-guide/lockup-watchdogs.rst diff --git a/Documentation/cma/debugfs.txt b/Documentation/admin-guide/mm/cma_debugfs.rst index 6cef20a8cedc..4e06ffabd78a 100644 --- a/Documentation/cma/debugfs.txt +++ b/Documentation/admin-guide/mm/cma_debugfs.rst @@ -1,3 +1,7 @@ +===================== +CMA Debugfs Interface +===================== + The CMA debugfs interface is useful to retrieve basic information out of the different CMA areas and to test allocation/release in each of the areas. @@ -12,7 +16,7 @@ The structure of the files created under that directory is as follows: - [RO] count: Amount of memory in the CMA area. - [RO] order_per_bit: Order of pages represented by one bit. - [RO] bitmap: The bitmap of page states in the zone. - - [WO] alloc: Allocate N pages from that CMA area. For example: + - [WO] alloc: Allocate N pages from that CMA area. For example:: echo 5 > <debugfs>/cma/cma-2/alloc diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index ddf8d8d33377..11db46448354 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -11,7 +11,7 @@ processes address space and many other cool things. Linux memory management is a complex system with many configurable settings. Most of these settings are available via ``/proc`` filesystem and can be quired and adjusted using ``sysctl``. These APIs -are described in Documentation/sysctl/vm.txt and in `man 5 proc`_. +are described in Documentation/admin-guide/sysctl/vm.rst and in `man 5 proc`_. .. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html @@ -26,6 +26,7 @@ the Linux memory management. :maxdepth: 1 concepts + cma_debugfs hugetlbpage idle_page_tracking ksm diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index 9303786632d1..874eb0c77d34 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -59,7 +59,7 @@ MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. If a region of memory must be split into at least one new MADV_MERGEABLE or MADV_UNMERGEABLE region, the madvise may return ENOMEM if the process -will exceed ``vm.max_map_count`` (see Documentation/sysctl/vm.txt). +will exceed ``vm.max_map_count`` (see Documentation/admin-guide/sysctl/vm.rst). Like other madvise calls, they are intended for use on mapped areas of the user address space: they will report ENOMEM if the specified range diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index 546f174e5d6a..8463f5538fda 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -15,7 +15,7 @@ document attempts to describe the concepts and APIs of the 2.6 memory policy support. Memory policies should not be confused with cpusets -(``Documentation/cgroup-v1/cpusets.rst``) +(``Documentation/admin-guide/cgroup-v1/cpusets.rst``) which is an administrative mechanism for restricting the nodes from which memory may be allocated by a set of processes. Memory policies are a programming interface that a NUMA-aware application can take advantage of. When diff --git a/Documentation/namespaces/compatibility-list.txt b/Documentation/admin-guide/namespaces/compatibility-list.rst index defc5589bfcd..318800b2a943 100644 --- a/Documentation/namespaces/compatibility-list.txt +++ b/Documentation/admin-guide/namespaces/compatibility-list.rst @@ -1,4 +1,6 @@ - Namespaces compatibility list +============================= +Namespaces compatibility list +============================= This document contains the information about the problems user may have when creating tasks living in different namespaces. @@ -7,13 +9,16 @@ Here's the summary. This matrix shows the known problems, that occur when tasks share some namespace (the columns) while living in different other namespaces (the rows): - UTS IPC VFS PID User Net +==== === === === === ==== === +- UTS IPC VFS PID User Net +==== === === === === ==== === UTS X IPC X 1 VFS X PID 1 1 X User 2 2 X Net X +==== === === === === ==== === 1. Both the IPC and the PID namespaces provide IDs to address object inside the kernel. E.g. semaphore with IPCID or @@ -36,4 +41,3 @@ Net X even having equal UIDs. But currently this is not so. - diff --git a/Documentation/admin-guide/namespaces/index.rst b/Documentation/admin-guide/namespaces/index.rst new file mode 100644 index 000000000000..384f2e0f33d2 --- /dev/null +++ b/Documentation/admin-guide/namespaces/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +Namespaces +========== + +.. toctree:: + :maxdepth: 1 + + compatibility-list + resource-control diff --git a/Documentation/namespaces/resource-control.txt b/Documentation/admin-guide/namespaces/resource-control.rst index abc13c394738..369556e00f0c 100644 --- a/Documentation/namespaces/resource-control.txt +++ b/Documentation/admin-guide/namespaces/resource-control.rst @@ -1,3 +1,7 @@ +=========================== +Namespaces research control +=========================== + There are a lot of kinds of objects in the kernel that don't have individual limits or that have limits that are ineffective when a set of processes is allowed to switch user ids. With user namespaces diff --git a/Documentation/numastat.txt b/Documentation/admin-guide/numastat.rst index aaf1667489f8..aaf1667489f8 100644 --- a/Documentation/numastat.txt +++ b/Documentation/admin-guide/numastat.rst diff --git a/Documentation/perf/arm-ccn.txt b/Documentation/admin-guide/perf/arm-ccn.rst index 15cdb7bc57c3..832b0c64023a 100644 --- a/Documentation/perf/arm-ccn.txt +++ b/Documentation/admin-guide/perf/arm-ccn.rst @@ -1,3 +1,4 @@ +========================== ARM Cache Coherent Network ========================== @@ -29,6 +30,7 @@ Crosspoint watchpoint-based events (special "event" value 0xfe) require "xp" and "vc" as as above plus "port" (device port index), "dir" (transmit/receive direction), comparator values ("cmp_l" and "cmp_h") and "mask", being index of the comparator mask. + Masks are defined separately from the event description (due to limited number of the config values) in the "cmp_mask" directory, with first 8 configurable by user and additional @@ -44,16 +46,16 @@ request the events on this processor (if not, the perf_event->cpu value will be overwritten anyway). In case of this processor being offlined, the events are migrated to another one and the attribute is updated. -Example of perf tool use: +Example of perf tool use:: -/ # perf list | grep ccn - ccn/cycles/ [Kernel PMU event] -<...> - ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event] -<...> + / # perf list | grep ccn + ccn/cycles/ [Kernel PMU event] + <...> + ccn/xp_valid_flit,xp=?,port=?,vc=?,dir=?/ [Kernel PMU event] + <...> -/ # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \ - sleep 1 + / # perf stat -a -e ccn/cycles/,ccn/xp_valid_flit,xp=1,port=0,vc=1,dir=1/ \ + sleep 1 The driver does not support sampling, therefore "perf record" will not work. Per-task (without "-a") perf sessions are not supported. diff --git a/Documentation/perf/arm_dsu_pmu.txt b/Documentation/admin-guide/perf/arm_dsu_pmu.rst index d611e15f5add..7fd34db75d13 100644 --- a/Documentation/perf/arm_dsu_pmu.txt +++ b/Documentation/admin-guide/perf/arm_dsu_pmu.rst @@ -1,3 +1,4 @@ +================================== ARM DynamIQ Shared Unit (DSU) PMU ================================== @@ -13,7 +14,7 @@ PMU doesn't support process specific events and cannot be used in sampling mode. The DSU provides a bitmap for a subset of implemented events via hardware registers. There is no way for the driver to determine if the other events are available or not. Hence the driver exposes only those events advertised -by the DSU, in "events" directory under : +by the DSU, in "events" directory under:: /sys/bus/event_sources/devices/arm_dsu_<N>/ @@ -23,6 +24,6 @@ and use the raw event code for the unlisted events. The driver also exposes the CPUs connected to the DSU instance in "associated_cpus". -e.g usage : +e.g usage:: perf stat -a -e arm_dsu_0/cycles/ diff --git a/Documentation/perf/hisi-pmu.txt b/Documentation/admin-guide/perf/hisi-pmu.rst index 267a028b2741..404a5c3d9d00 100644 --- a/Documentation/perf/hisi-pmu.txt +++ b/Documentation/admin-guide/perf/hisi-pmu.rst @@ -1,5 +1,7 @@ +====================================================== HiSilicon SoC uncore Performance Monitoring Unit (PMU) ====================================================== + The HiSilicon SoC chip includes various independent system device PMUs such as L3 cache (L3C), Hydra Home Agent (HHA) and DDRC. These PMUs are independent and have hardware logic to gather statistics and performance @@ -11,11 +13,13 @@ called Super CPU cluster (SCCL) and is made up of 6 CCLs. Each SCCL has two HHAs (0 - 1) and four DDRCs (0 - 3), respectively. HiSilicon SoC uncore PMU driver ---------------------------------------- +------------------------------- + Each device PMU has separate registers for event counting, control and interrupt, and the PMU driver shall register perf PMU drivers like L3C, HHA and DDRC etc. The available events and configuration options shall -be described in the sysfs, see : +be described in the sysfs, see: + /sys/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>/, or /sys/bus/event_source/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>. The "perf list" command shall list the available events from sysfs. @@ -24,27 +28,30 @@ Each L3C, HHA and DDRC is registered as a separate PMU with perf. The PMU name will appear in event listing as hisi_sccl<sccl-id>_module<index-id>. where "sccl-id" is the identifier of the SCCL and "index-id" is the index of module. + e.g. hisi_sccl3_l3c0/rd_hit_cpipe is READ_HIT_CPIPE event of L3C index #0 in SCCL ID #3. + e.g. hisi_sccl1_hha0/rx_operations is RX_OPERATIONS event of HHA index #0 in SCCL ID #1. The driver also provides a "cpumask" sysfs attribute, which shows the CPU core ID used to count the uncore PMU event. -Example usage of perf: -$# perf list -hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event] ------------------------------------------- -hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event] ------------------------------------------- -hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event] ------------------------------------------- -hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event] ------------------------------------------- - -$# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5 -$# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5 +Example usage of perf:: + + $# perf list + hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + hisi_sccl3_l3c0/wr_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + hisi_sccl1_l3c0/rd_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + hisi_sccl1_l3c0/wr_hit_cpipe/ [kernel PMU event] + ------------------------------------------ + + $# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5 + $# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5 The current driver does not support sampling. So "perf record" is unsupported. Also attach to a task is unsupported as the events are all uncore. diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst new file mode 100644 index 000000000000..ee4bfd2a740f --- /dev/null +++ b/Documentation/admin-guide/perf/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +Performance monitor support +=========================== + +.. toctree:: + :maxdepth: 1 + + hisi-pmu + qcom_l2_pmu + qcom_l3_pmu + arm-ccn + xgene-pmu + arm_dsu_pmu + thunderx2-pmu diff --git a/Documentation/perf/qcom_l2_pmu.txt b/Documentation/admin-guide/perf/qcom_l2_pmu.rst index b25b97659ab9..c130178a4a55 100644 --- a/Documentation/perf/qcom_l2_pmu.txt +++ b/Documentation/admin-guide/perf/qcom_l2_pmu.rst @@ -1,3 +1,4 @@ +===================================================================== Qualcomm Technologies Level-2 Cache Performance Monitoring Unit (PMU) ===================================================================== @@ -28,7 +29,7 @@ The driver provides a "cpumask" sysfs attribute which contains a mask consisting of one CPU per cluster which will be used to handle all the PMU events on that cluster. -Examples for use with perf: +Examples for use with perf:: perf stat -e l2cache_0/config=0x001/,l2cache_0/config=0x042/ -a sleep 1 diff --git a/Documentation/perf/qcom_l3_pmu.txt b/Documentation/admin-guide/perf/qcom_l3_pmu.rst index 96b3a9444a0d..a3d014a46bfd 100644 --- a/Documentation/perf/qcom_l3_pmu.txt +++ b/Documentation/admin-guide/perf/qcom_l3_pmu.rst @@ -1,3 +1,4 @@ +=========================================================================== Qualcomm Datacenter Technologies L3 Cache Performance Monitoring Unit (PMU) =========================================================================== @@ -17,7 +18,7 @@ The hardware implements 32bit event counters and has a flat 8bit event space exposed via the "event" format attribute. In addition to the 32bit physical counters the driver supports virtual 64bit hardware counters by using hardware counter chaining. This feature is exposed via the "lc" (long counter) format -flag. E.g.: +flag. E.g.:: perf stat -e l3cache_0_0/read-miss,lc/ diff --git a/Documentation/perf/thunderx2-pmu.txt b/Documentation/admin-guide/perf/thunderx2-pmu.rst index dffc57143736..08e33675853a 100644 --- a/Documentation/perf/thunderx2-pmu.txt +++ b/Documentation/admin-guide/perf/thunderx2-pmu.rst @@ -1,3 +1,4 @@ +============================================================= Cavium ThunderX2 SoC Performance Monitoring Unit (PMU UNCORE) ============================================================= @@ -24,18 +25,18 @@ and configuration options under sysfs, see The driver does not support sampling, therefore "perf record" will not work. Per-task perf sessions are also not supported. -Examples: +Examples:: -# perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1 + # perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1 -# perf stat -a -e \ -uncore_dmc_0/cnt_cycles/,\ -uncore_dmc_0/data_transfers/,\ -uncore_dmc_0/read_txns/,\ -uncore_dmc_0/write_txns/ sleep 1 + # perf stat -a -e \ + uncore_dmc_0/cnt_cycles/,\ + uncore_dmc_0/data_transfers/,\ + uncore_dmc_0/read_txns/,\ + uncore_dmc_0/write_txns/ sleep 1 -# perf stat -a -e \ -uncore_l3c_0/read_request/,\ -uncore_l3c_0/read_hit/,\ -uncore_l3c_0/inv_request/,\ -uncore_l3c_0/inv_hit/ sleep 1 + # perf stat -a -e \ + uncore_l3c_0/read_request/,\ + uncore_l3c_0/read_hit/,\ + uncore_l3c_0/inv_request/,\ + uncore_l3c_0/inv_hit/ sleep 1 diff --git a/Documentation/perf/xgene-pmu.txt b/Documentation/admin-guide/perf/xgene-pmu.rst index d7cff4454e5b..644f8ed89152 100644 --- a/Documentation/perf/xgene-pmu.txt +++ b/Documentation/admin-guide/perf/xgene-pmu.rst @@ -1,3 +1,4 @@ +================================================ APM X-Gene SoC Performance Monitoring Unit (PMU) ================================================ @@ -33,7 +34,7 @@ each PMU, please refer to APM X-Gene User Manual. Each perf driver also provides a "cpumask" sysfs attribute, which contains a single CPU ID of the processor which will be used to handle all the PMU events. -Example for perf tool use: +Example for perf tool use:: / # perf list | grep -e l3c -e iob -e mcb -e mc l3c0/ackq-full/ [Kernel PMU event] diff --git a/Documentation/pnp.txt b/Documentation/admin-guide/pnp.rst index bab2d10631f0..bab2d10631f0 100644 --- a/Documentation/pnp.txt +++ b/Documentation/admin-guide/pnp.rst diff --git a/Documentation/driver-api/rapidio.rst b/Documentation/admin-guide/rapidio.rst index 71ff658ab78e..71ff658ab78e 100644 --- a/Documentation/driver-api/rapidio.rst +++ b/Documentation/admin-guide/rapidio.rst diff --git a/Documentation/rtc.txt b/Documentation/admin-guide/rtc.rst index 688c95b11919..688c95b11919 100644 --- a/Documentation/rtc.txt +++ b/Documentation/admin-guide/rtc.rst diff --git a/Documentation/svga.txt b/Documentation/admin-guide/svga.rst index b6c2f9acca92..b6c2f9acca92 100644 --- a/Documentation/svga.txt +++ b/Documentation/admin-guide/svga.rst diff --git a/Documentation/admin-guide/sysctl/abi.rst b/Documentation/admin-guide/sysctl/abi.rst new file mode 100644 index 000000000000..599bcde7f0b7 --- /dev/null +++ b/Documentation/admin-guide/sysctl/abi.rst @@ -0,0 +1,67 @@ +================================ +Documentation for /proc/sys/abi/ +================================ + +kernel version 2.6.0.test2 + +Copyright (c) 2003, Fabian Frederick <ffrederick@users.sourceforge.net> + +For general info: index.rst. + +------------------------------------------------------------------------------ + +This path is binary emulation relevant aka personality types aka abi. +When a process is executed, it's linked to an exec_domain whose +personality is defined using values available from /proc/sys/abi. +You can find further details about abi in include/linux/personality.h. + +Here are the files featuring in 2.6 kernel: + +- defhandler_coff +- defhandler_elf +- defhandler_lcall7 +- defhandler_libcso +- fake_utsname +- trace + +defhandler_coff +--------------- + +defined value: + PER_SCOSVR3:: + + 0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS | SHORT_INODE + +defhandler_elf +-------------- + +defined value: + PER_LINUX:: + + 0 + +defhandler_lcall7 +----------------- + +defined value : + PER_SVR4:: + + 0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO, + +defhandler_libsco +----------------- + +defined value: + PER_SVR4:: + + 0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO, + +fake_utsname +------------ + +Unused + +trace +----- + +Unused diff --git a/Documentation/sysctl/fs.txt b/Documentation/admin-guide/sysctl/fs.rst index ebc679bcb2dc..2a45119e3331 100644 --- a/Documentation/sysctl/fs.txt +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -1,10 +1,16 @@ -Documentation for /proc/sys/fs/* kernel version 2.2.10 - (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> - (c) 2009, Shen Feng<shen@cn.fujitsu.com> +=============================== +Documentation for /proc/sys/fs/ +=============================== -For general info and legal blurb, please look in README. +kernel version 2.2.10 -============================================================== +Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> + +Copyright (c) 2009, Shen Feng<shen@cn.fujitsu.com> + +For general info and legal blurb, please look in intro.rst. + +------------------------------------------------------------------------------ This file contains documentation for the sysctl files in /proc/sys/fs/ and is valid for Linux kernel version 2.2. @@ -16,9 +22,10 @@ system, it is advisable to read both documentation and source before actually making adjustments. 1. /proc/sys/fs ----------------------------------------------------------- +=============== Currently, these files are in /proc/sys/fs: + - aio-max-nr - aio-nr - dentry-state @@ -42,9 +49,9 @@ Currently, these files are in /proc/sys/fs: - super-max - super-nr -============================================================== -aio-nr & aio-max-nr: +aio-nr & aio-max-nr +------------------- aio-nr is the running total of the number of events specified on the io_setup system call for all currently active aio contexts. If aio-nr @@ -52,21 +59,20 @@ reaches aio-max-nr then io_setup will fail with EAGAIN. Note that raising aio-max-nr does not result in the pre-allocation or re-sizing of any kernel data structures. -============================================================== -dentry-state: +dentry-state +------------ -From linux/include/linux/dcache.h: --------------------------------------------------------------- -struct dentry_stat_t dentry_stat { +From linux/include/linux/dcache.h:: + + struct dentry_stat_t dentry_stat { int nr_dentry; int nr_unused; int age_limit; /* age in seconds */ int want_pages; /* pages requested by system */ int nr_negative; /* # of unused negative dentries */ int dummy; /* Reserved for future use */ -}; --------------------------------------------------------------- + }; Dentries are dynamically allocated and deallocated. @@ -84,9 +90,9 @@ negative dentries which do not map to any files. Instead, they help speeding up rejection of non-existing files provided by the users. -============================================================== -dquot-max & dquot-nr: +dquot-max & dquot-nr +-------------------- The file dquot-max shows the maximum number of cached disk quota entries. @@ -98,9 +104,9 @@ If the number of free cached disk quotas is very low and you have some awesome number of simultaneous system users, you might want to raise the limit. -============================================================== -file-max & file-nr: +file-max & file-nr +------------------ The value in file-max denotes the maximum number of file- handles that the Linux kernel will allocate. When you get lots @@ -119,18 +125,19 @@ used file handles. Attempts to allocate more file descriptors than file-max are reported with printk, look for "VFS: file-max limit <number> reached". -============================================================== -nr_open: + +nr_open +------- This denotes the maximum number of file-handles a process can allocate. Default value is 1024*1024 (1048576) which should be enough for most machines. Actual limit depends on RLIMIT_NOFILE resource limit. -============================================================== -inode-max, inode-nr & inode-state: +inode-max, inode-nr & inode-state +--------------------------------- As with file handles, the kernel allocates the inode structures dynamically, but can't free them yet. @@ -157,9 +164,9 @@ preshrink is nonzero when the nr_inodes > inode-max and the system needs to prune the inode list instead of allocating more. -============================================================== -overflowgid & overflowuid: +overflowgid & overflowuid +------------------------- Some filesystems only support 16-bit UIDs and GIDs, although in Linux UIDs and GIDs are 32 bits. When one of these filesystems is mounted @@ -169,18 +176,18 @@ to a fixed value before being written to disk. These sysctls allow you to change the value of the fixed UID and GID. The default is 65534. -============================================================== -pipe-user-pages-hard: +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: +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, @@ -190,9 +197,9 @@ 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_fifos: +protected_fifos +--------------- The intent of this protection is to avoid unintentional writes to an attacker-controlled FIFO, where a program expected to create a regular @@ -208,9 +215,9 @@ When set to "2" it also applies to group writable sticky directories. This protection is based on the restrictions in Openwall. -============================================================== -protected_hardlinks: +protected_hardlinks +-------------------- A long-standing class of security issues is the hardlink-based time-of-check-time-of-use race, most commonly seen in world-writable @@ -228,9 +235,9 @@ already own the source file, or do not have read/write access to it. This protection is based on the restrictions in Openwall and grsecurity. -============================================================== -protected_regular: +protected_regular +----------------- This protection is similar to protected_fifos, but it avoids writes to an attacker-controlled regular file, where a program @@ -244,9 +251,9 @@ owned by the owner of the directory. When set to "2" it also applies to group writable sticky directories. -============================================================== -protected_symlinks: +protected_symlinks +------------------ A long-standing class of security issues is the symlink-based time-of-check-time-of-use race, most commonly seen in world-writable @@ -264,34 +271,38 @@ follower match, or when the directory owner matches the symlink's owner. This protection is based on the restrictions in Openwall and grsecurity. -============================================================== suid_dumpable: +-------------- This value can be used to query and set the core dump mode for setuid or otherwise protected/tainted binaries. The modes are -0 - (default) - traditional behaviour. Any process which has changed - privilege levels or is execute only will not be dumped. -1 - (debug) - all processes dump core when possible. The core dump is - owned by the current user and no security is applied. This is - intended for system debugging situations only. Ptrace is unchecked. - This is insecure as it allows regular users to examine the memory - contents of privileged processes. -2 - (suidsafe) - any binary which normally would not be dumped is dumped - anyway, but only if the "core_pattern" kernel sysctl is set to - either a pipe handler or a fully qualified path. (For more details - on this limitation, see CVE-2006-2451.) This mode is appropriate - when administrators are attempting to debug problems in a normal - environment, and either have a core dump pipe handler that knows - to treat privileged core dumps with care, or specific directory - defined for catching core dumps. If a core dump happens without - a pipe handler or fully qualifid path, a message will be emitted - to syslog warning about the lack of a correct setting. - -============================================================== - -super-max & super-nr: += ========== =============================================================== +0 (default) traditional behaviour. Any process which has changed + privilege levels or is execute only will not be dumped. +1 (debug) all processes dump core when possible. The core dump is + owned by the current user and no security is applied. This is + intended for system debugging situations only. + Ptrace is unchecked. + This is insecure as it allows regular users to examine the + memory contents of privileged processes. +2 (suidsafe) any binary which normally would not be dumped is dumped + anyway, but only if the "core_pattern" kernel sysctl is set to + either a pipe handler or a fully qualified path. (For more + details on this limitation, see CVE-2006-2451.) This mode is + appropriate when administrators are attempting to debug + problems in a normal environment, and either have a core dump + pipe handler that knows to treat privileged core dumps with + care, or specific directory defined for catching core dumps. + If a core dump happens without a pipe handler or fully + qualified path, a message will be emitted to syslog warning + about the lack of a correct setting. += ========== =============================================================== + + +super-max & super-nr +-------------------- These numbers control the maximum number of superblocks, and thus the maximum number of mounted filesystems the kernel @@ -299,33 +310,33 @@ can have. You only need to increase super-max if you need to mount more filesystems than the current value in super-max allows you to. -============================================================== -aio-nr & aio-max-nr: +aio-nr & aio-max-nr +------------------- aio-nr shows the current system-wide number of asynchronous io requests. aio-max-nr allows you to change the maximum value aio-nr can grow to. -============================================================== -mount-max: +mount-max +--------- This denotes the maximum number of mounts that may exist in a mount namespace. -============================================================== 2. /proc/sys/fs/binfmt_misc ----------------------------------------------------------- +=========================== Documentation for the files in /proc/sys/fs/binfmt_misc is in Documentation/admin-guide/binfmt-misc.rst. 3. /proc/sys/fs/mqueue - POSIX message queues filesystem ----------------------------------------------------------- +======================================================== + The "mqueue" filesystem provides the necessary kernel features to enable the creation of a user space library that implements the POSIX message queues @@ -356,7 +367,7 @@ the default message size value if attr parameter of mq_open(2) is NULL. If it exceed msgsize_max, the default value is initialized msgsize_max. 4. /proc/sys/fs/epoll - Configuration options for the epoll interface --------------------------------------------------------- +===================================================================== This directory contains configuration options for the epoll(7) interface. @@ -371,4 +382,3 @@ Each "watch" costs roughly 90 bytes on a 32bit kernel, and roughly 160 bytes on a 64bit one. The current default value for max_user_watches is the 1/32 of the available low memory, divided for the "watch" cost in bytes. - diff --git a/Documentation/sysctl/README b/Documentation/admin-guide/sysctl/index.rst index d5f24ab0ecc3..03346f98c7b9 100644 --- a/Documentation/sysctl/README +++ b/Documentation/admin-guide/sysctl/index.rst @@ -1,5 +1,10 @@ -Documentation for /proc/sys/ kernel version 2.2.10 - (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> +=========================== +Documentation for /proc/sys +=========================== + +Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> + +------------------------------------------------------------------------------ 'Why', I hear you ask, 'would anyone even _want_ documentation for them sysctl files? If anybody really needs it, it's all in @@ -12,11 +17,12 @@ have the time or knowledge to read the source code. Furthermore, the programmers who built sysctl have built it to be actually used, not just for the fun of programming it :-) -============================================================== +------------------------------------------------------------------------------ Legal blurb: As usual, there are two main things to consider: + 1. you get what you pay for 2. it's free @@ -35,15 +41,17 @@ stories to: <riel@nl.linux.org> Rik van Riel. -============================================================== +-------------------------------------------------------------- -Introduction: +Introduction +============ Sysctl is a means of configuring certain aspects of the kernel at run-time, and the /proc/sys/ directory is there so that you don't even need special tools to do it! In fact, there are only four things needed to use these config facilities: + - a running Linux system - root access - common sense (this is especially hard to come by these days) @@ -54,7 +62,9 @@ several (arch-dependent?) subdirs. Each subdir is mainly about one part of the kernel, so you can do configuration on a piece by piece basis, or just some 'thematic frobbing'. -The subdirs are about: +This documentation is about: + +=============== =============================================================== abi/ execution domains & personalities debug/ <empty> dev/ device specific information (eg dev/cdrom/info) @@ -70,7 +80,19 @@ sunrpc/ SUN Remote Procedure Call (NFS) vm/ memory management tuning buffer and cache management user/ Per user per user namespace limits +=============== =============================================================== These are the subdirs I have on my system. There might be more or other subdirs in another setup. If you see another dir, I'd really like to hear about it :-) + +.. toctree:: + :maxdepth: 1 + + abi + fs + kernel + net + sunrpc + user + vm diff --git a/Documentation/sysctl/kernel.txt b/Documentation/admin-guide/sysctl/kernel.rst index 1b2fe17cd2fa..032c7cd3cede 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -1,10 +1,16 @@ -Documentation for /proc/sys/kernel/* kernel version 2.2.10 - (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> - (c) 2009, Shen Feng<shen@cn.fujitsu.com> +=================================== +Documentation for /proc/sys/kernel/ +=================================== -For general info and legal blurb, please look in README. +kernel version 2.2.10 -============================================================== +Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> + +Copyright (c) 2009, Shen Feng<shen@cn.fujitsu.com> + +For general info and legal blurb, please look in index.rst. + +------------------------------------------------------------------------------ This file contains documentation for the sysctl files in /proc/sys/kernel/ and is valid for Linux kernel version 2.2. @@ -101,9 +107,9 @@ show up in /proc/sys/kernel: - watchdog_thresh - version -============================================================== acct: +===== highwater lowwater frequency @@ -118,18 +124,18 @@ That is, suspend accounting if there left <= 2% free; resume it if we got >=4%; consider information about amount of free space valid for 30 seconds. -============================================================== acpi_video_flags: +================= flags See Doc*/kernel/power/video.txt, it allows mode of video boot to be set during run time. -============================================================== auto_msgmni: +============ This variable has no effect and may be removed in future kernel releases. Reading it always returns 0. @@ -139,9 +145,8 @@ Echoing "1" into this file enabled msgmni automatic recomputing. Echoing "0" turned it off. auto_msgmni default value was 1. -============================================================== - bootloader_type: +================ x86 bootloader identification @@ -156,9 +161,9 @@ the value 340 = 0x154. See the type_of_loader and ext_loader_type fields in Documentation/x86/boot.rst for additional information. -============================================================== bootloader_version: +=================== x86 bootloader version @@ -168,27 +173,31 @@ file will contain the value 564 = 0x234. See the type_of_loader and ext_loader_ver fields in Documentation/x86/boot.rst for additional information. -============================================================== -cap_last_cap +cap_last_cap: +============= Highest valid capability of the running kernel. Exports CAP_LAST_CAP from the kernel. -============================================================== core_pattern: +============= core_pattern is used to specify a core dumpfile pattern name. -. max length 127 characters; default value is "core" -. core_pattern is used as a pattern template for the output filename; + +* max length 127 characters; default value is "core" +* core_pattern is used as a pattern template for the output filename; certain string patterns (beginning with '%') are substituted with their actual values. -. backward compatibility with core_uses_pid: +* backward compatibility with core_uses_pid: + If core_pattern does not include "%p" (default does not) and core_uses_pid is set, then .PID will be appended to the filename. -. corename format specifiers: + +* corename format specifiers:: + %<NUL> '%' is dropped %% output one '%' %p pid @@ -205,13 +214,14 @@ core_pattern is used to specify a core dumpfile pattern name. %e executable filename (may be shortened) %E executable path %<OTHER> both are dropped -. If the first character of the pattern is a '|', the kernel will treat + +* If the first character of the pattern is a '|', the kernel will treat the rest of the pattern as a command to run. The core dump will be written to the standard input of that program instead of to a file. -============================================================== core_pipe_limit: +================ This sysctl is only applicable when core_pattern is configured to pipe core files to a user space helper (when the first character of @@ -232,9 +242,9 @@ parallel, but that no waiting will take place (i.e. the collecting process is not guaranteed access to /proc/<crashing pid>/). This value defaults to 0. -============================================================== core_uses_pid: +============== The default coredump filename is "core". By setting core_uses_pid to 1, the coredump filename becomes core.PID. @@ -242,9 +252,9 @@ If core_pattern does not include "%p" (default does not) and core_uses_pid is set, then .PID will be appended to the filename. -============================================================== ctrl-alt-del: +============= When the value in this file is 0, ctrl-alt-del is trapped and sent to the init(1) program to handle a graceful restart. @@ -252,14 +262,15 @@ When, however, the value is > 0, Linux's reaction to a Vulcan Nerve Pinch (tm) will be an immediate reboot, without even syncing its dirty buffers. -Note: when a program (like dosemu) has the keyboard in 'raw' -mode, the ctrl-alt-del is intercepted by the program before it -ever reaches the kernel tty layer, and it's up to the program -to decide what to do with it. +Note: + when a program (like dosemu) has the keyboard in 'raw' + mode, the ctrl-alt-del is intercepted by the program before it + ever reaches the kernel tty layer, and it's up to the program + to decide what to do with it. -============================================================== dmesg_restrict: +=============== This toggle indicates whether unprivileged users are prevented from using dmesg(8) to view messages from the kernel's log buffer. @@ -270,18 +281,21 @@ dmesg(8). The kernel config option CONFIG_SECURITY_DMESG_RESTRICT sets the default value of dmesg_restrict. -============================================================== domainname & hostname: +====================== These files can be used to set the NIS/YP domainname and the hostname of your box in exactly the same way as the commands -domainname and hostname, i.e.: -# echo "darkstar" > /proc/sys/kernel/hostname -# echo "mydomain" > /proc/sys/kernel/domainname -has the same effect as -# hostname "darkstar" -# domainname "mydomain" +domainname and hostname, i.e.:: + + # echo "darkstar" > /proc/sys/kernel/hostname + # echo "mydomain" > /proc/sys/kernel/domainname + +has the same effect as:: + + # hostname "darkstar" + # domainname "mydomain" Note, however, that the classic darkstar.frop.org has the hostname "darkstar" and DNS (Internet Domain Name Server) @@ -290,8 +304,9 @@ Information Service) or YP (Yellow Pages) domainname. These two 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 @@ -301,9 +316,10 @@ will be initiated. 0: do nothing. This is the default behavior. 1: on detection capture more debug information. -============================================================== + hardlockup_panic: +================= This parameter can be used to control whether the kernel panics when a hard lockup is detected. @@ -311,19 +327,19 @@ when a hard lockup is detected. 0 - don't panic on hard lockup 1 - panic on hard lockup -See Documentation/lockup-watchdogs.txt for more information. This can +See Documentation/admin-guide/lockup-watchdogs.rst for more information. This can also be set using the nmi_watchdog kernel parameter. -============================================================== hotplug: +======== Path for the hotplug policy agent. Default value is "/sbin/hotplug". -============================================================== hung_task_panic: +================ Controls the kernel's behavior when a hung task is detected. This file shows up if CONFIG_DETECT_HUNG_TASK is enabled. @@ -332,27 +348,28 @@ This file shows up if CONFIG_DETECT_HUNG_TASK is enabled. 1: panic immediately. -============================================================== hung_task_check_count: +====================== The upper bound on the number of tasks that are checked. This file shows up if CONFIG_DETECT_HUNG_TASK is enabled. -============================================================== hung_task_timeout_secs: +======================= When a task in D state did not get scheduled for more than this value report a warning. This file shows up if CONFIG_DETECT_HUNG_TASK is enabled. 0: means infinite timeout - no checking done. + Possible values to set are in range {0..LONG_MAX/HZ}. -============================================================== hung_task_check_interval_secs: +============================== Hung task check interval. If hung task checking is enabled (see hung_task_timeout_secs), the check is done every @@ -362,9 +379,9 @@ This file shows up if CONFIG_DETECT_HUNG_TASK is enabled. 0 (default): means use hung_task_timeout_secs as checking interval. Possible values to set are in range {0..LONG_MAX/HZ}. -============================================================== hung_task_warnings: +=================== The maximum number of warnings to report. During a check interval if a hung task is detected, this value is decreased by 1. @@ -373,9 +390,9 @@ This file shows up if CONFIG_DETECT_HUNG_TASK is enabled. -1: report an infinite number of warnings. -============================================================== hyperv_record_panic_msg: +======================== Controls whether the panic kmsg data should be reported to Hyper-V. @@ -383,9 +400,9 @@ Controls whether the panic kmsg data should be reported to Hyper-V. 1: report the panic kmsg data. This is the default behavior. -============================================================== kexec_load_disabled: +==================== A toggle indicating if the kexec_load syscall has been disabled. This value defaults to 0 (false: kexec_load enabled), but can be set to 1 @@ -395,9 +412,9 @@ loaded before disabling the syscall, allowing a system to set up (and later use) an image without it being altered. Generally used together with the "modules_disabled" sysctl. -============================================================== kptr_restrict: +============== This toggle indicates whether restrictions are placed on exposing kernel addresses via /proc and other interfaces. @@ -420,16 +437,16 @@ values to unprivileged users is a concern. When kptr_restrict is set to (2), kernel pointers printed using %pK will be replaced with 0's regardless of privileges. -============================================================== l2cr: (PPC only) +================ This flag controls the L2 cache of G3 processor boards. If 0, the cache is disabled. Enabled if nonzero. -============================================================== modules_disabled: +================= A toggle value indicating if modules are allowed to be loaded in an otherwise modular kernel. This toggle defaults to off @@ -437,9 +454,9 @@ in an otherwise modular kernel. This toggle defaults to off neither loaded nor unloaded, and the toggle cannot be set back to false. Generally used with the "kexec_load_disabled" toggle. -============================================================== msg_next_id, sem_next_id, and shm_next_id: +========================================== These three toggles allows to specify desired id for next allocated IPC object: message, semaphore or shared memory respectively. @@ -448,21 +465,22 @@ By default they are equal to -1, which means generic allocation logic. Possible values to set are in range {0..INT_MAX}. Notes: -1) kernel doesn't guarantee, that new object will have desired id. So, -it's up to userspace, how to handle an object with "wrong" id. -2) Toggle with non-default value will be set back to -1 by kernel after -successful IPC object allocation. If an IPC object allocation syscall -fails, it is undefined if the value remains unmodified or is reset to -1. + 1) kernel doesn't guarantee, that new object will have desired id. So, + it's up to userspace, how to handle an object with "wrong" id. + 2) Toggle with non-default value will be set back to -1 by kernel after + successful IPC object allocation. If an IPC object allocation syscall + fails, it is undefined if the value remains unmodified or is reset to -1. -============================================================== nmi_watchdog: +============= This parameter can be used to control the NMI watchdog (i.e. the hard lockup detector) on x86 systems. - 0 - disable the hard lockup detector - 1 - enable the hard lockup detector +0 - disable the hard lockup detector + +1 - enable the hard lockup detector The hard lockup detector monitors each CPU for its ability to respond to timer interrupts. The mechanism utilizes CPU performance counter registers @@ -470,15 +488,15 @@ that are programmed to generate Non-Maskable Interrupts (NMIs) periodically while a CPU is busy. Hence, the alternative name 'NMI watchdog'. The NMI watchdog is disabled by default if the kernel is running as a guest -in a KVM virtual machine. This default can be overridden by adding +in a KVM virtual machine. This default can be overridden by adding:: nmi_watchdog=1 to the guest kernel command line (see Documentation/admin-guide/kernel-parameters.rst). -============================================================== -numa_balancing +numa_balancing: +=============== Enables/disables automatic page fault based NUMA memory balancing. Memory is moved automatically to nodes @@ -500,10 +518,9 @@ faults may be controlled by the numa_balancing_scan_period_min_ms, numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms, numa_balancing_scan_size_mb, and numa_balancing_settle_count sysctls. -============================================================== +numa_balancing_scan_period_min_ms, numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms, numa_balancing_scan_size_mb +=============================================================================================================================== -numa_balancing_scan_period_min_ms, numa_balancing_scan_delay_ms, -numa_balancing_scan_period_max_ms, numa_balancing_scan_size_mb Automatic NUMA balancing scans tasks address space and unmaps pages to detect if pages are properly placed or if the data should be migrated to a @@ -539,16 +556,18 @@ rate for each task. numa_balancing_scan_size_mb is how many megabytes worth of pages are scanned for a given scan. -============================================================== osrelease, ostype & version: +============================ + +:: -# cat osrelease -2.1.88 -# cat ostype -Linux -# cat version -#5 Wed Feb 25 21:49:24 MET 1998 + # cat osrelease + 2.1.88 + # cat ostype + Linux + # cat version + #5 Wed Feb 25 21:49:24 MET 1998 The files osrelease and ostype should be clear enough. Version needs a little more clarification however. The '#5' means that @@ -556,9 +575,9 @@ this is the fifth kernel built from this source base and the date behind it indicates the time the kernel was built. The only way to tune these values is to rebuild the kernel :-) -============================================================== overflowgid & overflowuid: +========================== if your architecture did not always support 32-bit UIDs (i.e. arm, i386, m68k, sh, and sparc32), a fixed UID and GID will be returned to @@ -568,17 +587,17 @@ actual UID or GID would exceed 65535. These sysctls allow you to change the value of the fixed UID and GID. The default is 65534. -============================================================== panic: +====== The value in this file represents the number of seconds the kernel waits before rebooting on a panic. When you use the software watchdog, 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. @@ -591,20 +610,20 @@ an IO error. 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. 0: try to continue operation -1: panic immediately. If the `panic' sysctl is also non-zero then the +1: panic immediately. If the `panic` sysctl is also non-zero then the machine will be rebooted. -============================================================== panic_on_stackoverflow: +======================= Controls the kernel's behavior when detecting the overflows of kernel, IRQ and exception stacks except a user stack. @@ -614,9 +633,9 @@ This file shows up if CONFIG_DEBUG_STACKOVERFLOW is enabled. 1: panic immediately. -============================================================== panic_on_unrecovered_nmi: +========================= The default Linux behaviour on an NMI of either memory or unknown is to continue operation. For many environments such as scientific @@ -627,9 +646,9 @@ A small number of systems do generate NMI's for bizarre random reasons such as power management so the default is off. That sysctl works like the existing panic controls already in that directory. -============================================================== panic_on_warn: +============== Calls panic() in the WARN() path when set to 1. This is useful to avoid a kernel rebuild when attempting to kdump at the location of a WARN(). @@ -638,25 +657,28 @@ a kernel rebuild when attempting to kdump at the location of a WARN(). 1: call panic() after printing out WARN() location. -============================================================== panic_print: +============ Bitmask for printing system info when panic happens. User can chose combination of the following bits: -bit 0: print all tasks info -bit 1: print system memory info -bit 2: print timer info -bit 3: print locks info if CONFIG_LOCKDEP is on -bit 4: print ftrace buffer +===== ======================================== +bit 0 print all tasks info +bit 1 print system memory info +bit 2 print timer info +bit 3 print locks info if CONFIG_LOCKDEP is on +bit 4 print ftrace buffer +===== ======================================== + +So for example to print tasks and memory info on panic, user can:: -So for example to print tasks and memory info on panic, user can: echo 3 > /proc/sys/kernel/panic_print -============================================================== panic_on_rcu_stall: +=================== When set to 1, calls panic() after RCU stall detection messages. This is useful to define the root cause of RCU stalls using a vmcore. @@ -665,9 +687,9 @@ is useful to define the root cause of RCU stalls using a vmcore. 1: panic() after printing RCU stall messages. -============================================================== perf_cpu_time_max_percent: +========================== Hints to the kernel how much CPU time it should be allowed to use to handle perf sampling events. If the perf subsystem @@ -680,10 +702,12 @@ unexpectedly take too long to execute, the NMIs can become stacked up next to each other so much that nothing else is allowed to execute. -0: disable the mechanism. Do not monitor or correct perf's +0: + disable the mechanism. Do not monitor or correct perf's sampling rate no matter how CPU time it takes. -1-100: attempt to throttle perf's sample rate to this +1-100: + attempt to throttle perf's sample rate to this percentage of CPU. Note: the kernel calculates an "expected" length of each sample event. 100 here means 100% of that expected length. Even if this is set to @@ -691,23 +715,30 @@ allowed to execute. length is exceeded. Set to 0 if you truly do not care how much CPU is consumed. -============================================================== perf_event_paranoid: +==================== Controls use of the performance events system by unprivileged users (without CAP_SYS_ADMIN). The default value is 2. - -1: Allow use of (almost) all events by all users +=== ================================================================== + -1 Allow use of (almost) all events by all users + Ignore mlock limit after perf_event_mlock_kb without CAP_IPC_LOCK ->=0: Disallow ftrace function tracepoint by users without CAP_SYS_ADMIN + +>=0 Disallow ftrace function tracepoint by users without CAP_SYS_ADMIN + Disallow raw tracepoint access by users without CAP_SYS_ADMIN ->=1: Disallow CPU event access by users without CAP_SYS_ADMIN ->=2: Disallow kernel profiling by users without CAP_SYS_ADMIN -============================================================== +>=1 Disallow CPU event access by users without CAP_SYS_ADMIN + +>=2 Disallow kernel profiling by users without CAP_SYS_ADMIN +=== ================================================================== + perf_event_max_stack: +===================== Controls maximum number of stack frames to copy for (attr.sample_type & PERF_SAMPLE_CALLCHAIN) configured events, for instance, when using @@ -718,17 +749,17 @@ enabled, otherwise writing to this file will return -EBUSY. The default value is 127. -============================================================== perf_event_mlock_kb: +==================== Control size of per-cpu ring buffer not counted agains mlock limit. The default value is 512 + 1 page -============================================================== perf_event_max_contexts_per_stack: +================================== Controls maximum number of stack frame context entries for (attr.sample_type & PERF_SAMPLE_CALLCHAIN) configured events, for @@ -739,25 +770,25 @@ enabled, otherwise writing to this file will return -EBUSY. The default value is 8. -============================================================== pid_max: +======== PID allocation wrap value. When the kernel's next PID value reaches this value, it wraps back to a minimum PID value. PIDs of value pid_max or larger are not allocated. -============================================================== ns_last_pid: +============ The last pid allocated in the current (the one task using this sysctl lives in) pid namespace. When selecting a pid for a next task on fork kernel tries to allocate a number starting from this one. -============================================================== powersave-nap: (PPC only) +========================= If set, Linux-PPC will use the 'nap' mode of powersaving, otherwise the 'doze' mode will be used. @@ -765,6 +796,7 @@ otherwise the 'doze' mode will be used. ============================================================== printk: +======= The four values in printk denote: console_loglevel, default_message_loglevel, minimum_console_loglevel and @@ -774,25 +806,29 @@ These values influence printk() behavior when printing or logging error messages. See 'man 2 syslog' for more info on the different loglevels. -- console_loglevel: messages with a higher priority than - this will be printed to the console -- default_message_loglevel: messages without an explicit priority - will be printed with this priority -- minimum_console_loglevel: minimum (highest) value to which - console_loglevel can be set -- default_console_loglevel: default value for console_loglevel +- console_loglevel: + messages with a higher priority than + this will be printed to the console +- default_message_loglevel: + messages without an explicit priority + will be printed with this priority +- minimum_console_loglevel: + minimum (highest) value to which + console_loglevel can be set +- default_console_loglevel: + default value for console_loglevel -============================================================== printk_delay: +============= Delay each printk message in printk_delay milliseconds Value from 0 - 10000 is allowed. -============================================================== printk_ratelimit: +================= Some warning messages are rate limited. printk_ratelimit specifies the minimum length of time between these messages (in jiffies), by @@ -800,48 +836,52 @@ default we allow one every 5 seconds. A value of 0 will disable rate limiting. -============================================================== printk_ratelimit_burst: +======================= While long term we enforce one message per printk_ratelimit seconds, we do allow a burst of messages to pass through. printk_ratelimit_burst specifies the number of messages we can send before ratelimiting kicks in. -============================================================== printk_devkmsg: +=============== Control the logging to /dev/kmsg from userspace: -ratelimit: default, ratelimited +ratelimit: + default, ratelimited + on: unlimited logging to /dev/kmsg from userspace + off: logging to /dev/kmsg disabled The kernel command line parameter printk.devkmsg= overrides this and is a one-time setting until next reboot: once set, it cannot be changed by this sysctl interface anymore. -============================================================== randomize_va_space: +=================== This option can be used to select the type of process address space randomization that is used in the system, for architectures that support this feature. -0 - Turn the process address space randomization off. This is the +== =========================================================================== +0 Turn the process address space randomization off. This is the default for architectures that do not support this feature anyways, and kernels that are booted with the "norandmaps" parameter. -1 - Make the addresses of mmap base, stack and VDSO page randomized. +1 Make the addresses of mmap base, stack and VDSO page randomized. This, among other things, implies that shared libraries will be loaded to random addresses. Also for PIE-linked binaries, the location of code start is randomized. This is the default if the CONFIG_COMPAT_BRK option is enabled. -2 - Additionally enable heap randomization. This is the default if +2 Additionally enable heap randomization. This is the default if CONFIG_COMPAT_BRK is disabled. There are a few legacy applications out there (such as some ancient @@ -854,18 +894,19 @@ that support this feature. Systems with ancient and/or broken binaries should be configured with CONFIG_COMPAT_BRK enabled, which excludes the heap from process address space randomization. +== =========================================================================== -============================================================== reboot-cmd: (Sparc only) +======================== ??? This seems to be a way to give an argument to the Sparc ROM/Flash boot loader. Maybe to tell it what to do after rebooting. ??? -============================================================== rtsig-max & rtsig-nr: +===================== The file rtsig-max can be used to tune the maximum number of POSIX realtime (queued) signals that can be outstanding @@ -873,9 +914,9 @@ in the system. rtsig-nr shows the number of RT signals currently queued. -============================================================== sched_energy_aware: +=================== Enables/disables Energy Aware Scheduling (EAS). EAS starts automatically on platforms where it can run (that is, @@ -884,17 +925,17 @@ Model available). If your platform happens to meet the requirements for EAS but you do not want to use it, change this value to 0. -============================================================== 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. You can't tune it just yet, but you could change it on @@ -905,9 +946,9 @@ There shouldn't be any reason to change this value. If you can come up with one, you probably know what you are doing anyway :) -============================================================== shmall: +======= This parameter sets the total amount of shared memory pages that can be used system wide. Hence, SHMALL should always be at least @@ -916,20 +957,20 @@ ceil(shmmax/PAGE_SIZE). If you are not sure what the default PAGE_SIZE is on your Linux system, you can run the following command: -# getconf PAGE_SIZE + # getconf PAGE_SIZE -============================================================== shmmax: +======= This value can be used to query and set the run time limit on the maximum shared memory segment size that can be created. Shared memory segments up to 1Gb are now supported in the kernel. This value defaults to SHMMAX. -============================================================== shm_rmid_forced: +================ Linux lets you set resource limits, including how much memory one process can consume, via setrlimit(2). Unfortunately, shared memory @@ -948,28 +989,30 @@ need this. Note that if you change this from 0 to 1, already created segments without users and with a dead originative process will be destroyed. -============================================================== sysctl_writes_strict: +===================== Control how file position affects the behavior of updating sysctl values via the /proc/sys interface: - -1 - Legacy per-write sysctl value handling, with no printk warnings. + == ====================================================================== + -1 Legacy per-write sysctl value handling, with no printk warnings. 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 - Same behavior as above, but warn about processes that perform writes + 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 + 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. + == ====================================================================== -============================================================== softlockup_all_cpu_backtrace: +============================= This value controls the soft lockup detector thread's behavior when a soft lockup condition is detected as to whether or not @@ -983,13 +1026,14 @@ NMI. 1: on detection capture more debug information. -============================================================== -soft_watchdog +soft_watchdog: +============== This parameter can be used to control the soft lockup detector. 0 - disable the soft lockup detector + 1 - enable the soft lockup detector The soft lockup detector monitors CPUs for threads that are hogging the CPUs @@ -999,9 +1043,9 @@ interrupts which are needed for the 'watchdog/N' threads to be woken up by the watchdog timer function, otherwise the NMI watchdog - if enabled - can detect a hard lockup condition. -============================================================== -stack_erasing +stack_erasing: +============== This parameter can be used to control kernel stack erasing at the end of syscalls for kernels built with CONFIG_GCC_PLUGIN_STACKLEAK. @@ -1015,37 +1059,40 @@ compilation sees a 1% slowdown, other systems and workloads may vary. 1: kernel stack erasing is enabled (default), it is performed before returning to the userspace at the end of syscalls. -============================================================== + tainted +======= Non-zero if the kernel has been tainted. Numeric values, which can be ORed together. The letters are seen in "Tainted" line of Oops reports. - 1 (P): proprietary module was loaded - 2 (F): module was force loaded - 4 (S): SMP kernel oops on an officially SMP incapable processor - 8 (R): module was force unloaded - 16 (M): processor reported a Machine Check Exception (MCE) - 32 (B): bad page referenced or some unexpected page flags - 64 (U): taint requested by userspace application - 128 (D): kernel died recently, i.e. there was an OOPS or BUG - 256 (A): an ACPI table was overridden by user - 512 (W): kernel issued warning - 1024 (C): staging driver was loaded - 2048 (I): workaround for bug in platform firmware applied - 4096 (O): externally-built ("out-of-tree") module was loaded - 8192 (E): unsigned module was loaded - 16384 (L): soft lockup occurred - 32768 (K): kernel has been live patched - 65536 (X): Auxiliary taint, defined and used by for distros -131072 (T): The kernel was built with the struct randomization plugin +====== ===== ============================================================== + 1 `(P)` proprietary module was loaded + 2 `(F)` module was force loaded + 4 `(S)` SMP kernel oops on an officially SMP incapable processor + 8 `(R)` module was force unloaded + 16 `(M)` processor reported a Machine Check Exception (MCE) + 32 `(B)` bad page referenced or some unexpected page flags + 64 `(U)` taint requested by userspace application + 128 `(D)` kernel died recently, i.e. there was an OOPS or BUG + 256 `(A)` an ACPI table was overridden by user + 512 `(W)` kernel issued warning + 1024 `(C)` staging driver was loaded + 2048 `(I)` workaround for bug in platform firmware applied + 4096 `(O)` externally-built ("out-of-tree") module was loaded + 8192 `(E)` unsigned module was loaded + 16384 `(L)` soft lockup occurred + 32768 `(K)` kernel has been live patched + 65536 `(X)` Auxiliary taint, defined and used by for distros +131072 `(T)` The kernel was built with the struct randomization plugin +====== ===== ============================================================== See Documentation/admin-guide/tainted-kernels.rst for more information. -============================================================== -threads-max +threads-max: +============ This value controls the maximum number of threads that can be created using fork(). @@ -1055,8 +1102,10 @@ maximum number of threads is created, the thread structures occupy only a part (1/8th) of the available RAM pages. The minimum value that can be written to threads-max is 20. + The maximum value that can be written to threads-max is given by the constant FUTEX_TID_MASK (0x3fffffff). + If a value outside of this range is written to threads-max an error EINVAL occurs. @@ -1064,9 +1113,9 @@ The value written is checked against the available RAM pages. If the thread structures would occupy too much (more than 1/8th) of the available RAM pages threads-max is reduced accordingly. -============================================================== unknown_nmi_panic: +================== The value in this file affects behavior of handling NMI. When the value is non-zero, unknown NMI is trapped and then panic occurs. At @@ -1075,28 +1124,29 @@ that time, kernel debugging information is displayed on console. NMI switch that most IA32 servers have fires unknown NMI up, for example. If a system hangs up, try pressing the NMI switch. -============================================================== watchdog: +========= This parameter can be used to disable or enable the soft lockup detector _and_ the NMI watchdog (i.e. the hard lockup detector) at the same time. 0 - disable both lockup detectors + 1 - enable both lockup detectors The soft lockup detector and the NMI watchdog can also be disabled or enabled individually, using the soft_watchdog and nmi_watchdog parameters. -If the watchdog parameter is read, for example by executing +If the watchdog parameter is read, for example by executing:: cat /proc/sys/kernel/watchdog the output of this command (0 or 1) shows the logical OR of soft_watchdog and nmi_watchdog. -============================================================== watchdog_cpumask: +================= This value can be used to control on which cpus the watchdog may run. The default cpumask is all possible cores, but if NO_HZ_FULL is @@ -1111,13 +1161,13 @@ if a kernel lockup was suspected on those cores. The argument value is the standard cpulist format for cpumasks, so for example to enable the watchdog on cores 0, 2, 3, and 4 you -might say: +might say:: echo 0,2-4 > /proc/sys/kernel/watchdog_cpumask -============================================================== watchdog_thresh: +================ This value can be used to control the frequency of hrtimer and NMI events and the soft and hard lockup thresholds. The default threshold @@ -1125,5 +1175,3 @@ is 10 seconds. The softlockup threshold is (2 * watchdog_thresh). Setting this tunable to zero will disable lockup detection altogether. - -============================================================== diff --git a/Documentation/sysctl/net.txt b/Documentation/admin-guide/sysctl/net.rst index 2ae91d3873bb..a7d44e71019d 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/admin-guide/sysctl/net.rst @@ -1,12 +1,25 @@ -Documentation for /proc/sys/net/* - (c) 1999 Terrehon Bowden <terrehon@pacbell.net> - Bodo Bauer <bb@ricochet.net> - (c) 2000 Jorge Nerin <comandante@zaralinux.com> - (c) 2009 Shen Feng <shen@cn.fujitsu.com> +================================ +Documentation for /proc/sys/net/ +================================ -For general info and legal blurb, please look in README. +Copyright -============================================================== +Copyright (c) 1999 + + - Terrehon Bowden <terrehon@pacbell.net> + - Bodo Bauer <bb@ricochet.net> + +Copyright (c) 2000 + + - Jorge Nerin <comandante@zaralinux.com> + +Copyright (c) 2009 + + - Shen Feng <shen@cn.fujitsu.com> + +For general info and legal blurb, please look in index.rst. + +------------------------------------------------------------------------------ This file contains the documentation for the sysctl files in /proc/sys/net @@ -17,20 +30,22 @@ see only some of them, depending on your kernel's configuration. Table : Subdirectories in /proc/sys/net -.............................................................................. - Directory Content Directory Content - core General parameter appletalk Appletalk protocol - unix Unix domain sockets netrom NET/ROM - 802 E802 protocol ax25 AX25 - ethernet Ethernet protocol rose X.25 PLP layer - ipv4 IP version 4 x25 X.25 protocol - ipx IPX token-ring IBM token ring - bridge Bridging decnet DEC net - ipv6 IP version 6 tipc TIPC -.............................................................................. + + ========= =================== = ========== ================== + Directory Content Directory Content + ========= =================== = ========== ================== + core General parameter appletalk Appletalk protocol + unix Unix domain sockets netrom NET/ROM + 802 E802 protocol ax25 AX25 + ethernet Ethernet protocol rose X.25 PLP layer + ipv4 IP version 4 x25 X.25 protocol + ipx IPX token-ring IBM token ring + bridge Bridging decnet DEC net + ipv6 IP version 6 tipc TIPC + ========= =================== = ========== ================== 1. /proc/sys/net/core - Network core options -------------------------------------------------------- +============================================ bpf_jit_enable -------------- @@ -44,6 +59,7 @@ restricted C into a sequence of BPF instructions. After program load through bpf(2) and passing a verifier in the kernel, a JIT will then translate these BPF proglets into native CPU instructions. There are two flavors of JITs, the newer eBPF JIT currently supported on: + - x86_64 - x86_32 - arm64 @@ -55,6 +71,7 @@ two flavors of JITs, the newer eBPF JIT currently supported on: - riscv And the older cBPF JIT supported on the following archs: + - mips - ppc - sparc @@ -65,10 +82,11 @@ compile them transparently. Older cBPF JITs can only translate tcpdump filters, seccomp rules, etc, but not mentioned eBPF programs loaded through bpf(2). -Values : - 0 - disable the JIT (default value) - 1 - enable the JIT - 2 - enable the JIT and ask the compiler to emit traces on kernel log. +Values: + + - 0 - disable the JIT (default value) + - 1 - enable the JIT + - 2 - enable the JIT and ask the compiler to emit traces on kernel log. bpf_jit_harden -------------- @@ -76,10 +94,12 @@ bpf_jit_harden This enables hardening for the BPF JIT compiler. Supported are eBPF JIT backends. Enabling hardening trades off performance, but can mitigate JIT spraying. -Values : - 0 - disable JIT hardening (default value) - 1 - enable JIT hardening for unprivileged users only - 2 - enable JIT hardening for all users + +Values: + + - 0 - disable JIT hardening (default value) + - 1 - enable JIT hardening for unprivileged users only + - 2 - enable JIT hardening for all users bpf_jit_kallsyms ---------------- @@ -89,9 +109,11 @@ addresses to the kernel, meaning they neither show up in traces nor in /proc/kallsyms. This enables export of these addresses, which can be used for debugging/tracing. If bpf_jit_harden is enabled, this feature is disabled. + Values : - 0 - disable JIT kallsyms export (default value) - 1 - enable JIT kallsyms export for privileged users only + + - 0 - disable JIT kallsyms export (default value) + - 1 - enable JIT kallsyms export for privileged users only bpf_jit_limit ------------- @@ -102,7 +124,7 @@ been surpassed. bpf_jit_limit contains the value of the global limit in bytes. dev_weight --------------- +---------- The maximum number of packets that kernel can handle on a NAPI interrupt, it's a Per-CPU variable. For drivers that support LRO or GRO_HW, a hardware @@ -111,7 +133,7 @@ aggregated packet is counted as one packet in this context. Default: 64 dev_weight_rx_bias --------------- +------------------ RPS (e.g. RFS, aRFS) processing is competing with the registered NAPI poll function of the driver for the per softirq cycle netdev_budget. This parameter influences @@ -120,19 +142,22 @@ processing during RX softirq cycles. It is further meant for making current dev_weight adaptable for asymmetric CPU needs on RX/TX side of the network stack. (see dev_weight_tx_bias) It is effective on a per CPU basis. Determination is based on dev_weight and is calculated multiplicative (dev_weight * dev_weight_rx_bias). + Default: 1 dev_weight_tx_bias --------------- +------------------ Scales the maximum number of packets that can be processed during a TX softirq cycle. Effective on a per CPU basis. Allows scaling of current dev_weight for asymmetric net stack processing needs. Be careful to avoid making TX softirq processing a CPU hog. + Calculation is based on dev_weight (dev_weight * dev_weight_tx_bias). + Default: 1 default_qdisc --------------- +------------- The default queuing discipline to use for network devices. This allows overriding the default of pfifo_fast with an alternative. Since the default @@ -144,17 +169,21 @@ which require setting up classes and bandwidths. Note that physical multiqueue interfaces still use mq as root qdisc, which in turn uses this default for its leaves. Virtual devices (like e.g. lo or veth) ignore this setting and instead default to noqueue. + Default: pfifo_fast busy_read ----------------- +--------- + Low latency busy poll timeout for socket reads. (needs CONFIG_NET_RX_BUSY_POLL) Approximate time in us to busy loop waiting for packets on the device queue. This sets the default value of the SO_BUSY_POLL socket option. Can be set or overridden per socket by setting socket option SO_BUSY_POLL, which is the preferred method of enabling. If you need to enable the feature globally via sysctl, a value of 50 is recommended. + Will increase power usage. + Default: 0 (off) busy_poll @@ -167,7 +196,9 @@ For more than that you probably want to use epoll. Note that only sockets with SO_BUSY_POLL set will be busy polled, so you want to either selectively set SO_BUSY_POLL on those sockets or set sysctl.net.busy_read globally. + Will increase power usage. + Default: 0 (off) rmem_default @@ -185,6 +216,7 @@ tstamp_allow_data Allow processes to receive tx timestamps looped together with the original packet contents. If disabled, transmit timestamp requests from unprivileged processes are dropped unless socket option SOF_TIMESTAMPING_OPT_TSONLY is set. + Default: 1 (on) @@ -250,19 +282,24 @@ randomly generated. Some user space might need to gather its content even if drivers do not provide ethtool -x support yet. -myhost:~# cat /proc/sys/net/core/netdev_rss_key -84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8: ... (52 bytes total) +:: + + myhost:~# cat /proc/sys/net/core/netdev_rss_key + 84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8: ... (52 bytes total) File contains nul bytes if no driver ever called netdev_rss_key_fill() function. + Note: -/proc/sys/net/core/netdev_rss_key contains 52 bytes of key, -but most drivers only use 40 bytes of it. + /proc/sys/net/core/netdev_rss_key contains 52 bytes of key, + but most drivers only use 40 bytes of it. + +:: -myhost:~# ethtool -x eth0 -RX flow hash indirection table for eth0 with 8 RX ring(s): - 0: 0 1 2 3 4 5 6 7 -RSS hash key: -84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89 + myhost:~# ethtool -x eth0 + RX flow hash indirection table for eth0 with 8 RX ring(s): + 0: 0 1 2 3 4 5 6 7 + RSS hash key: + 84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89 netdev_tstamp_prequeue ---------------------- @@ -293,7 +330,7 @@ user space is responsible for creating them if needed. Default : 0 (for compatibility reasons) devconf_inherit_init_net ----------------------------- +------------------------ Controls if a new network namespace should inherit all current settings under /proc/sys/net/{ipv4,ipv6}/conf/{all,default}/. By @@ -307,7 +344,7 @@ forced to reset to their default values. Default : 0 (for compatibility reasons) 2. /proc/sys/net/unix - Parameters for Unix domain sockets -------------------------------------------------------- +---------------------------------------------------------- There is only one file in this directory. unix_dgram_qlen limits the max number of datagrams queued in Unix domain @@ -315,13 +352,13 @@ socket's buffer. It will not take effect unless PF_UNIX flag is specified. 3. /proc/sys/net/ipv4 - IPV4 settings -------------------------------------------------------- +------------------------------------- Please see: Documentation/networking/ip-sysctl.txt and ipvs-sysctl.txt for descriptions of these entries. 4. Appletalk -------------------------------------------------------- +------------ The /proc/sys/net/appletalk directory holds the Appletalk configuration data when Appletalk is loaded. The configurable parameters are: @@ -366,7 +403,7 @@ route flags, and the device the route is using. 5. IPX -------------------------------------------------------- +------ The IPX protocol has no tunable values in proc/sys/net. @@ -391,14 +428,16 @@ gives the destination network, the router node (or Directly) and the network address of the router (or Connected) for internal networks. 6. TIPC -------------------------------------------------------- +------- tipc_rmem ----------- +--------- The TIPC protocol now has a tunable for the receive memory, similar to the tcp_rmem - i.e. a vector of 3 INTEGERs: (min, default, max) +:: + # cat /proc/sys/net/tipc/tipc_rmem 4252725 34021800 68043600 # @@ -409,7 +448,7 @@ is not at this point in time used in any meaningful way, but the triplet is preserved in order to be consistent with things like tcp_rmem. named_timeout --------------- +------------- TIPC name table updates are distributed asynchronously in a cluster, without any form of transaction handling. This means that different race scenarios are diff --git a/Documentation/sysctl/sunrpc.txt b/Documentation/admin-guide/sysctl/sunrpc.rst index ae1ecac6f85a..09780a682afd 100644 --- a/Documentation/sysctl/sunrpc.txt +++ b/Documentation/admin-guide/sysctl/sunrpc.rst @@ -1,9 +1,14 @@ -Documentation for /proc/sys/sunrpc/* kernel version 2.2.10 - (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> +=================================== +Documentation for /proc/sys/sunrpc/ +=================================== -For general info and legal blurb, please look in README. +kernel version 2.2.10 -============================================================== +Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> + +For general info and legal blurb, please look in index.rst. + +------------------------------------------------------------------------------ This file contains the documentation for the sysctl files in /proc/sys/sunrpc and is valid for Linux kernel version 2.2. diff --git a/Documentation/sysctl/user.txt b/Documentation/admin-guide/sysctl/user.rst index a5882865836e..650eaa03f15e 100644 --- a/Documentation/sysctl/user.txt +++ b/Documentation/admin-guide/sysctl/user.rst @@ -1,7 +1,12 @@ -Documentation for /proc/sys/user/* kernel version 4.9.0 - (c) 2016 Eric Biederman <ebiederm@xmission.com> +================================= +Documentation for /proc/sys/user/ +================================= -============================================================== +kernel version 4.9.0 + +Copyright (c) 2016 Eric Biederman <ebiederm@xmission.com> + +------------------------------------------------------------------------------ This file contains the documentation for the sysctl files in /proc/sys/user. @@ -30,37 +35,44 @@ user namespace does not allow a user to escape their current limits. Currently, these files are in /proc/sys/user: -- max_cgroup_namespaces +max_cgroup_namespaces +===================== The maximum number of cgroup namespaces that any user in the current user namespace may create. -- max_ipc_namespaces +max_ipc_namespaces +================== The maximum number of ipc namespaces that any user in the current user namespace may create. -- max_mnt_namespaces +max_mnt_namespaces +================== The maximum number of mount namespaces that any user in the current user namespace may create. -- max_net_namespaces +max_net_namespaces +================== The maximum number of network namespaces that any user in the current user namespace may create. -- max_pid_namespaces +max_pid_namespaces +================== The maximum number of pid namespaces that any user in the current user namespace may create. -- max_user_namespaces +max_user_namespaces +=================== The maximum number of user namespaces that any user in the current user namespace may create. -- max_uts_namespaces +max_uts_namespaces +================== The maximum number of user namespaces that any user in the current user namespace may create. diff --git a/Documentation/sysctl/vm.txt b/Documentation/admin-guide/sysctl/vm.rst index 749322060f10..64aeee1009ca 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -1,10 +1,16 @@ -Documentation for /proc/sys/vm/* kernel version 2.6.29 - (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> - (c) 2008 Peter W. Morreale <pmorreale@novell.com> +=============================== +Documentation for /proc/sys/vm/ +=============================== -For general info and legal blurb, please look in README. +kernel version 2.6.29 -============================================================== +Copyright (c) 1998, 1999, Rik van Riel <riel@nl.linux.org> + +Copyright (c) 2008 Peter W. Morreale <pmorreale@novell.com> + +For general info and legal blurb, please look in index.rst. + +------------------------------------------------------------------------------ This file contains the documentation for the sysctl files in /proc/sys/vm and is valid for Linux kernel version 2.6.29. @@ -68,9 +74,9 @@ Currently, these files are in /proc/sys/vm: - watermark_scale_factor - zone_reclaim_mode -============================================================== admin_reserve_kbytes +==================== The amount of free memory in the system that should be reserved for users with the capability cap_sys_admin. @@ -97,25 +103,25 @@ On x86_64 this is about 128MB. Changing this takes effect whenever an application requests memory. -============================================================== block_dump +========== block_dump enables block I/O debugging when set to a nonzero value. More -information on block I/O debugging is in Documentation/laptops/laptop-mode.txt. +information on block I/O debugging is in Documentation/admin-guide/laptops/laptop-mode.rst. -============================================================== compact_memory +============== Available only when CONFIG_COMPACTION is set. When 1 is written to the file, all zones are compacted such that free memory is available in contiguous blocks where possible. This can be important for example in the allocation of huge pages although processes will also directly compact memory as required. -============================================================== compact_unevictable_allowed +=========================== Available only when CONFIG_COMPACTION is set. When set to 1, compaction is allowed to examine the unevictable lru (mlocked pages) for pages to compact. @@ -123,21 +129,22 @@ This should be used on systems where stalls for minor page faults are an acceptable trade for large contiguous free memory. Set to 0 to prevent compaction from moving pages that are unevictable. Default value is 1. -============================================================== dirty_background_bytes +====================== Contains the amount of dirty memory at which the background kernel flusher threads will start writeback. -Note: dirty_background_bytes is the counterpart of dirty_background_ratio. Only -one of them may be specified at a time. When one sysctl is written it is -immediately taken into account to evaluate the dirty memory limits and the -other appears as 0 when read. +Note: + dirty_background_bytes is the counterpart of dirty_background_ratio. Only + one of them may be specified at a time. When one sysctl is written it is + immediately taken into account to evaluate the dirty memory limits and the + other appears as 0 when read. -============================================================== dirty_background_ratio +====================== Contains, as a percentage of total available memory that contains free pages and reclaimable pages, the number of pages at which the background kernel @@ -145,9 +152,9 @@ flusher threads will start writing out dirty data. The total available memory is not equal to total system memory. -============================================================== dirty_bytes +=========== Contains the amount of dirty memory at which a process generating disk writes will itself start writeback. @@ -161,18 +168,18 @@ Note: the minimum value allowed for dirty_bytes is two pages (in bytes); any value lower than this limit will be ignored and the old configuration will be retained. -============================================================== dirty_expire_centisecs +====================== This tunable is used to define when dirty data is old enough to be eligible for writeout by the kernel flusher threads. It is expressed in 100'ths of a second. Data which has been dirty in-memory for longer than this interval will be written out next time a flusher thread wakes up. -============================================================== dirty_ratio +=========== 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 @@ -180,9 +187,9 @@ generating disk writes will itself start writing out dirty data. The total available memory is not equal to total system memory. -============================================================== dirtytime_expire_seconds +======================== When a lazytime inode is constantly having its pages dirtied, the inode with an updated timestamp will never get chance to be written out. And, if the @@ -192,34 +199,39 @@ eventually gets pushed out to disk. This tunable is used to define when dirty inode is old enough to be eligible for writeback by the kernel flusher threads. And, it is also used as the interval to wakeup dirtytime_writeback thread. -============================================================== dirty_writeback_centisecs +========================= -The kernel flusher threads will periodically wake up and write `old' data +The kernel flusher threads will periodically wake up and write `old` data out to disk. This tunable expresses the interval between those wakeups, in 100'ths of a second. Setting this to zero disables periodic writeback altogether. -============================================================== drop_caches +=========== Writing to this will cause the kernel to drop clean caches, as well as reclaimable slab objects like dentries and inodes. Once dropped, their memory becomes free. -To free pagecache: +To free pagecache:: + echo 1 > /proc/sys/vm/drop_caches -To free reclaimable slab objects (includes dentries and inodes): + +To free reclaimable slab objects (includes dentries and inodes):: + echo 2 > /proc/sys/vm/drop_caches -To free slab objects and pagecache: + +To free slab objects and pagecache:: + echo 3 > /proc/sys/vm/drop_caches This is a non-destructive operation and will not free any dirty objects. To increase the number of objects freed by this operation, the user may run -`sync' prior to writing to /proc/sys/vm/drop_caches. This will minimize the +`sync` prior to writing to /proc/sys/vm/drop_caches. This will minimize the number of dirty objects on the system and create more candidates to be dropped. @@ -233,16 +245,16 @@ dropped objects, especially if they were under heavy use. Because of this, use outside of a testing or debugging environment is not recommended. You may see informational messages in your kernel log when this file is -used: +used:: cat (1234): drop_caches: 3 These are informational only. They do not mean that anything is wrong with your system. To disable them, echo 4 (bit 2) into drop_caches. -============================================================== extfrag_threshold +================= This parameter affects whether the kernel will compact memory or direct reclaim to satisfy a high-order allocation. The extfrag/extfrag_index file in @@ -254,9 +266,9 @@ implies that the allocation will succeed as long as watermarks are met. The kernel will not compact memory in a zone if the fragmentation index is <= extfrag_threshold. The default value is 500. -============================================================== highmem_is_dirtyable +==================== Available only for systems with CONFIG_HIGHMEM enabled (32b systems). @@ -274,30 +286,30 @@ OOM killer because some writers (e.g. direct block device writes) can only use the low memory and they can fill it up with dirty data without any throttling. -============================================================== hugetlb_shm_group +================= hugetlb_shm_group contains group id that is allowed to create SysV shared memory segment using hugetlb page. -============================================================== laptop_mode +=========== laptop_mode is a knob that controls "laptop mode". All the things that are -controlled by this knob are discussed in Documentation/laptops/laptop-mode.txt. +controlled by this knob are discussed in Documentation/admin-guide/laptops/laptop-mode.rst. -============================================================== legacy_va_layout +================ If non-zero, this sysctl disables the new 32-bit mmap layout - the kernel will use the legacy (2.4) layout for all processes. -============================================================== lowmem_reserve_ratio +==================== For some specialised workloads on highmem machines it is dangerous for the kernel to allow process memory to be allocated from the "lowmem" @@ -308,7 +320,7 @@ And on large highmem machines this lack of reclaimable lowmem memory can be fatal. So the Linux page allocator has a mechanism which prevents allocations -which _could_ use highmem from using too much lowmem. This means that +which *could* use highmem from using too much lowmem. This means that a certain amount of lowmem is defended from the possibility of being captured into pinned user memory. @@ -316,39 +328,37 @@ captured into pinned user memory. mechanism will also defend that region from allocations which could use highmem or lowmem). -The `lowmem_reserve_ratio' tunable determines how aggressive the kernel is +The `lowmem_reserve_ratio` tunable determines how aggressive the kernel is in defending these lower zones. If you have a machine which uses highmem or ISA DMA and your applications are using mlock(), or if you are running with no swap then you probably should change the lowmem_reserve_ratio setting. -The lowmem_reserve_ratio is an array. You can see them by reading this file. -- -% cat /proc/sys/vm/lowmem_reserve_ratio -256 256 32 -- +The lowmem_reserve_ratio is an array. You can see them by reading this file:: + + % cat /proc/sys/vm/lowmem_reserve_ratio + 256 256 32 But, these values are not used directly. The kernel calculates # of protection pages for each zones from them. These are shown as array of protection pages in /proc/zoneinfo like followings. (This is an example of x86-64 box). -Each zone has an array of protection pages like this. - -- -Node 0, zone DMA - pages free 1355 - min 3 - low 3 - high 4 +Each zone has an array of protection pages like this:: + + Node 0, zone DMA + pages free 1355 + min 3 + low 3 + high 4 : : - numa_other 0 - protection: (0, 2004, 2004, 2004) + numa_other 0 + protection: (0, 2004, 2004, 2004) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - pagesets - cpu: 0 pcp: 0 - : -- + pagesets + cpu: 0 pcp: 0 + : + These protections are added to score to judge whether this zone should be used for page allocation or should be reclaimed. @@ -359,20 +369,24 @@ not be used because pages_free(1355) is smaller than watermark + protection[2] normal page requirement. If requirement is DMA zone(index=0), protection[0] (=0) is used. -zone[i]'s protection[j] is calculated by following expression. +zone[i]'s protection[j] is calculated by following expression:: -(i < j): - zone[i]->protection[j] - = (total sums of managed_pages from zone[i+1] to zone[j] on the node) - / lowmem_reserve_ratio[i]; -(i = j): - (should not be protected. = 0; -(i > j): - (not necessary, but looks 0) + (i < j): + zone[i]->protection[j] + = (total sums of managed_pages from zone[i+1] to zone[j] on the node) + / lowmem_reserve_ratio[i]; + (i = j): + (should not be protected. = 0; + (i > j): + (not necessary, but looks 0) The default values of lowmem_reserve_ratio[i] are + + === ==================================== 256 (if zone[i] means DMA or DMA32 zone) - 32 (others). + 32 (others) + === ==================================== + As above expression, they are reciprocal number of ratio. 256 means 1/256. # of protection pages becomes about "0.39%" of total managed pages of higher zones on the node. @@ -381,9 +395,9 @@ If you would like to protect more pages, smaller values are effective. The minimum value is 1 (1/1 -> 100%). The value less than 1 completely disables protection of the pages. -============================================================== max_map_count: +============== This file contains the maximum number of memory map areas a process may have. Memory map areas are used as a side-effect of calling @@ -396,9 +410,9 @@ e.g., up to one or two maps per allocation. The default value is 65536. -============================================================= memory_failure_early_kill: +========================== Control how to kill processes when uncorrected memory error (typically a 2bit error in a memory module) is detected in the background by hardware @@ -424,9 +438,9 @@ check handling and depends on the hardware capabilities. Applications can override this setting individually with the PR_MCE_KILL prctl -============================================================== memory_failure_recovery +======================= Enable memory failure recovery (when supported by the platform) @@ -434,9 +448,9 @@ Enable memory failure recovery (when supported by the platform) 0: Always panic on a memory failure. -============================================================== -min_free_kbytes: +min_free_kbytes +=============== This is used to force the Linux VM to keep a minimum number of kilobytes free. The VM uses this number to compute a @@ -450,9 +464,9 @@ become subtly broken, and prone to deadlock under high loads. Setting this too high will OOM your machine instantly. -============================================================= -min_slab_ratio: +min_slab_ratio +============== This is available only on NUMA kernels. @@ -468,9 +482,9 @@ Note that slab reclaim is triggered in a per zone / node fashion. The process of reclaiming slab memory is currently not node specific and may not be fast. -============================================================= -min_unmapped_ratio: +min_unmapped_ratio +================== This is available only on NUMA kernels. @@ -485,9 +499,9 @@ files and similar are considered. The default is 1 percent. -============================================================== mmap_min_addr +============= This file indicates the amount of address space which a user process will be restricted from mmapping. Since kernel null dereference bugs could @@ -498,9 +512,9 @@ security module. Setting this value to something like 64k will allow the vast majority of applications to work correctly and provide defense in depth against future potential kernel bugs. -============================================================== -mmap_rnd_bits: +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 @@ -511,9 +525,9 @@ 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: +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 @@ -525,35 +539,35 @@ 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. See Documentation/admin-guide/mm/hugetlbpage.rst -============================================================== nr_hugepages_mempolicy +====================== Change the size of the hugepage pool at run-time on a specific set of NUMA nodes. See Documentation/admin-guide/mm/hugetlbpage.rst -============================================================== nr_overcommit_hugepages +======================= Change the maximum size of the hugepage pool. The maximum is nr_hugepages + nr_overcommit_hugepages. See Documentation/admin-guide/mm/hugetlbpage.rst -============================================================== nr_trim_pages +============= This is available only on NOMMU kernels. @@ -568,16 +582,17 @@ The default value is 1. See Documentation/nommu-mmap.txt for more information. -============================================================== numa_zonelist_order +=================== This sysctl is only for NUMA and it is deprecated. Anything but Node order will fail! 'where the memory is allocated from' is controlled by zonelists. + (This documentation ignores ZONE_HIGHMEM/ZONE_DMA32 for simple explanation. - you may be able to read ZONE_DMA as ZONE_DMA32...) +you may be able to read ZONE_DMA as ZONE_DMA32...) In non-NUMA case, a zonelist for GFP_KERNEL is ordered as following. ZONE_NORMAL -> ZONE_DMA @@ -585,10 +600,10 @@ This means that a memory allocation request for GFP_KERNEL will get memory from ZONE_DMA only when ZONE_NORMAL is not available. In NUMA case, you can think of following 2 types of order. -Assume 2 node NUMA and below is zonelist of Node(0)'s GFP_KERNEL +Assume 2 node NUMA and below is zonelist of Node(0)'s GFP_KERNEL:: -(A) Node(0) ZONE_NORMAL -> Node(0) ZONE_DMA -> Node(1) ZONE_NORMAL -(B) Node(0) ZONE_NORMAL -> Node(1) ZONE_NORMAL -> Node(0) ZONE_DMA. + (A) Node(0) ZONE_NORMAL -> Node(0) ZONE_DMA -> Node(1) ZONE_NORMAL + (B) Node(0) ZONE_NORMAL -> Node(1) ZONE_NORMAL -> Node(0) ZONE_DMA. Type(A) offers the best locality for processes on Node(0), but ZONE_DMA will be used before ZONE_NORMAL exhaustion. This increases possibility of @@ -616,9 +631,9 @@ order will be selected. Default order is recommended unless this is causing problems for your system/application. -============================================================== oom_dump_tasks +============== Enables a system-wide task dump (excluding kernel threads) to be produced when the kernel performs an OOM-killing and includes such information as @@ -638,9 +653,9 @@ OOM killer actually kills a memory-hogging task. The default value is 1 (enabled). -============================================================== oom_kill_allocating_task +======================== This enables or disables killing the OOM-triggering task in out-of-memory situations. @@ -659,9 +674,9 @@ is used in oom_kill_allocating_task. The default value is 0. -============================================================== -overcommit_kbytes: +overcommit_kbytes +================= When overcommit_memory is set to 2, the committed address space is not permitted to exceed swap plus this amount of physical RAM. See below. @@ -670,9 +685,9 @@ Note: overcommit_kbytes is the counterpart of overcommit_ratio. Only one of them may be specified at a time. Setting one disables the other (which then appears as 0 when read). -============================================================== -overcommit_memory: +overcommit_memory +================= This value contains a flag that enables memory overcommitment. @@ -695,17 +710,17 @@ The default value is 0. See Documentation/vm/overcommit-accounting.rst and mm/util.c::__vm_enough_memory() for more information. -============================================================== -overcommit_ratio: +overcommit_ratio +================ When overcommit_memory is set to 2, the committed address space is not permitted to exceed swap plus this percentage of physical RAM. See above. -============================================================== page-cluster +============ page-cluster controls the number of pages up to which consecutive pages are read in from swap in a single attempt. This is the swap counterpart @@ -725,9 +740,9 @@ Lower values mean lower latencies for initial faults, but at the same time extra faults and I/O delays for following faults if they would have been part of that consecutive pages readahead would have brought in. -============================================================= panic_on_oom +============ This enables or disables panic on out-of-memory feature. @@ -747,14 +762,16 @@ above-mentioned. Even oom happens under memory cgroup, the whole system panics. The default value is 0. + 1 and 2 are for failover of clustering. Please select either according to your policy of failover. + panic_on_oom=2+kdump gives you very strong tool to investigate why oom happens. You can get snapshot. -============================================================= percpu_pagelist_fraction +======================== This is the fraction of pages at most (high mark pcp->high) in each zone that are allocated for each per cpu page list. The min value for this is 8. It @@ -770,16 +787,16 @@ The initial value is zero. Kernel does not use this value at boot time to set the high water marks for each per cpu page list. If the user writes '0' to this sysctl, it will revert to this default behavior. -============================================================== stat_interval +============= The time interval between which vm statistics are updated. The default is 1 second. -============================================================== stat_refresh +============ Any read or write (by root only) flushes all the per-cpu vm statistics into their global totals, for more accurate reports when testing @@ -790,24 +807,26 @@ as 0) and "fails" with EINVAL if any are found, with a warning in dmesg. (At time of writing, a few stats are known sometimes to be found negative, with no ill effects: errors and warnings on these stats are suppressed.) -============================================================== numa_stat +========= This interface allows runtime configuration of numa statistics. When page allocation performance becomes a bottleneck and you can tolerate some possible tool breakage and decreased numa counter precision, you can -do: +do:: + echo 0 > /proc/sys/vm/numa_stat When page allocation performance is not a bottleneck and you want all -tooling to work, you can do: +tooling to work, you can do:: + echo 1 > /proc/sys/vm/numa_stat -============================================================== swappiness +========== This control is used to define how aggressive the kernel will swap memory pages. Higher values will increase aggressiveness, lower values @@ -817,9 +836,9 @@ than the high water mark in a zone. The default value is 60. -============================================================== unprivileged_userfaultfd +======================== This flag controls whether unprivileged users can use the userfaultfd system calls. Set this to 1 to allow unprivileged users to use the @@ -828,9 +847,9 @@ privileged users (with SYS_CAP_PTRACE capability). The default value is 1. -============================================================== -- user_reserve_kbytes +user_reserve_kbytes +=================== When overcommit_memory is set to 2, "never overcommit" mode, reserve min(3% of current process size, user_reserve_kbytes) of free memory. @@ -846,10 +865,9 @@ Any subsequent attempts to execute a command will result in Changing this takes effect whenever an application requests memory. -============================================================== vfs_cache_pressure ------------------- +================== This percentage value controls the tendency of the kernel to reclaim the memory which is used for caching of directory and inode objects. @@ -867,9 +885,9 @@ 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_boost_factor: +watermark_boost_factor +====================== This factor controls the level of reclaim when memory is being fragmented. It defines the percentage of the high watermark of a zone that will be @@ -887,9 +905,9 @@ fragmentation events that occurred in the recent past. If this value is smaller than a pageblock then a pageblocks worth of pages will be reclaimed (e.g. 2MB on 64-bit x86). A boost factor of 0 will disable the feature. -============================================================= -watermark_scale_factor: +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 @@ -905,20 +923,22 @@ 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: +zone_reclaim_mode +================= Zone_reclaim_mode allows someone to set more or less aggressive approaches to reclaim memory when a zone runs out of memory. If it is set to zero then no zone reclaim occurs. Allocations will be satisfied from other zones / nodes in the system. -This is value ORed together of +This is value OR'ed together of -1 = Zone reclaim on -2 = Zone reclaim writes dirty pages out -4 = Zone reclaim swaps pages += =================================== +1 Zone reclaim on +2 Zone reclaim writes dirty pages out +4 Zone reclaim swaps pages += =================================== zone_reclaim_mode is disabled by default. For file servers or workloads that benefit from having their data cached, zone_reclaim_mode should be @@ -942,5 +962,3 @@ of other processes running on other nodes will not be affected. Allowing regular swap effectively restricts allocations to the local node unless explicitly overridden by memory policies or cpuset configurations. - -============ End of Document ================================= diff --git a/Documentation/video-output.txt b/Documentation/admin-guide/video-output.rst index 56d6fa2e2368..56d6fa2e2368 100644 --- a/Documentation/video-output.txt +++ b/Documentation/admin-guide/video-output.rst diff --git a/Documentation/filesystems/xfs.txt b/Documentation/admin-guide/xfs.rst index a5cbb5e0e3db..e76665a8f2f2 100644 --- a/Documentation/filesystems/xfs.txt +++ b/Documentation/admin-guide/xfs.rst @@ -1,4 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 +====================== The SGI XFS Filesystem ====================== @@ -18,8 +20,6 @@ Mount Options ============= When mounting an XFS filesystem, the following options are accepted. -For boolean mount options, the names with the (*) suffix is the -default behaviour. allocsize=size Sets the buffered I/O end-of-file preallocation size when @@ -31,46 +31,43 @@ default behaviour. preallocation size, which uses a set of heuristics to optimise the preallocation size based on the current allocation patterns within the file and the access patterns - to the file. Specifying a fixed allocsize value turns off + to the file. Specifying a fixed ``allocsize`` value turns off the dynamic behaviour. - attr2 - noattr2 + attr2 or noattr2 The options enable/disable an "opportunistic" improvement to be made in the way inline extended attributes are stored on-disk. When the new form is used for the first time when - attr2 is selected (either when setting or removing extended + ``attr2`` is selected (either when setting or removing extended attributes) the on-disk superblock feature bit field will be updated to reflect this format being in use. The default behaviour is determined by the on-disk feature - bit indicating that attr2 behaviour is active. If either - mount option it set, then that becomes the new default used + bit indicating that ``attr2`` behaviour is active. If either + mount option is set, then that becomes the new default used by the filesystem. - CRC enabled filesystems always use the attr2 format, and so - will reject the noattr2 mount option if it is set. + CRC enabled filesystems always use the ``attr2`` format, and so + will reject the ``noattr2`` mount option if it is set. - discard - nodiscard (*) + discard or nodiscard (default) Enable/disable the issuing of commands to let the block device reclaim space freed by the filesystem. This is useful for SSD devices, thinly provisioned LUNs and virtual machine images, but may have a performance impact. - Note: It is currently recommended that you use the fstrim - application to discard unused blocks rather than the discard + Note: It is currently recommended that you use the ``fstrim`` + application to ``discard`` unused blocks rather than the ``discard`` mount option because the performance impact of this option is quite severe. - grpid/bsdgroups - nogrpid/sysvgroups (*) + grpid/bsdgroups or nogrpid/sysvgroups (default) These options define what group ID a newly created file - gets. When grpid is set, it takes the group ID of the + gets. When ``grpid`` is set, it takes the group ID of the directory in which it is created; otherwise it takes the - fsgid of the current process, unless the directory has the - setgid bit set, in which case it takes the gid from the - parent directory, and also gets the setgid bit set if it is + ``fsgid`` of the current process, unless the directory has the + ``setgid`` bit set, in which case it takes the ``gid`` from the + parent directory, and also gets the ``setgid`` bit set if it is a directory itself. filestreams @@ -78,46 +75,42 @@ default behaviour. across the entire filesystem rather than just on directories configured to use it. - ikeep - noikeep (*) - When ikeep is specified, XFS does not delete empty inode - clusters and keeps them around on disk. When noikeep is + ikeep or noikeep (default) + When ``ikeep`` is specified, XFS does not delete empty inode + clusters and keeps them around on disk. When ``noikeep`` is specified, empty inode clusters are returned to the free space pool. - inode32 - inode64 (*) - When inode32 is specified, it indicates that XFS limits + inode32 or inode64 (default) + When ``inode32`` is specified, it indicates that XFS limits inode creation to locations which will not result in inode numbers with more than 32 bits of significance. - When inode64 is specified, it indicates that XFS is allowed + When ``inode64`` is specified, it indicates that XFS is allowed to create inodes at any location in the filesystem, including those which will result in inode numbers occupying - more than 32 bits of significance. + more than 32 bits of significance. - inode32 is provided for backwards compatibility with older + ``inode32`` is provided for backwards compatibility with older systems and applications, since 64 bits inode numbers might cause problems for some applications that cannot handle large inode numbers. If applications are in use which do - not handle inode numbers bigger than 32 bits, the inode32 + not handle inode numbers bigger than 32 bits, the ``inode32`` option should be specified. - - largeio - nolargeio (*) - If "nolargeio" is specified, the optimal I/O reported in - st_blksize by stat(2) will be as small as possible to allow + largeio or nolargeio (default) + If ``nolargeio`` is specified, the optimal I/O reported in + ``st_blksize`` by **stat(2)** will be as small as possible to allow user applications to avoid inefficient read/modify/write I/O. This is typically the page size of the machine, as this is the granularity of the page cache. - If "largeio" specified, a filesystem that was created with a - "swidth" specified will return the "swidth" value (in bytes) - in st_blksize. If the filesystem does not have a "swidth" - specified but does specify an "allocsize" then "allocsize" + If ``largeio`` is specified, a filesystem that was created with a + ``swidth`` specified will return the ``swidth`` value (in bytes) + in ``st_blksize``. If the filesystem does not have a ``swidth`` + specified but does specify an ``allocsize`` then ``allocsize`` (in bytes) will be returned instead. Otherwise the behaviour - is the same as if "nolargeio" was specified. + is the same as if ``nolargeio`` was specified. logbufs=value Set the number of in-memory log buffers. Valid numbers @@ -127,7 +120,7 @@ default behaviour. If the memory cost of 8 log buffers is too high on small systems, then it may be reduced at some cost to performance - on metadata intensive workloads. The logbsize option below + on metadata intensive workloads. The ``logbsize`` option below controls the size of each buffer and so is also relevant to this case. @@ -138,7 +131,7 @@ default behaviour. and 32768 (32k). Valid sizes for version 2 logs also include 65536 (64k), 131072 (128k) and 262144 (256k). The logbsize must be an integer multiple of the log - stripe unit configured at mkfs time. + stripe unit configured at **mkfs(8)** time. The default value for for version 1 logs is 32768, while the default value for version 2 logs is MAX(32768, log_sunit). @@ -153,21 +146,21 @@ default behaviour. noalign Data allocations will not be aligned at stripe unit boundaries. This is only relevant to filesystems created - with non-zero data alignment parameters (sunit, swidth) by - mkfs. + with non-zero data alignment parameters (``sunit``, ``swidth``) by + **mkfs(8)**. norecovery The filesystem will be mounted without running log recovery. If the filesystem was not cleanly unmounted, it is likely to - be inconsistent when mounted in "norecovery" mode. + be inconsistent when mounted in ``norecovery`` mode. Some files or directories may not be accessible because of this. - Filesystems mounted "norecovery" must be mounted read-only or + Filesystems mounted ``norecovery`` must be mounted read-only or the mount will fail. nouuid Don't check for double mounted file systems using the file - system uuid. This is useful to mount LVM snapshot volumes, - and often used in combination with "norecovery" for mounting + system ``uuid``. This is useful to mount LVM snapshot volumes, + and often used in combination with ``norecovery`` for mounting read-only snapshots. noquota @@ -176,15 +169,15 @@ default behaviour. uquota/usrquota/uqnoenforce/quota User disk quota accounting enabled, and limits (optionally) - enforced. Refer to xfs_quota(8) for further details. + enforced. Refer to **xfs_quota(8)** for further details. gquota/grpquota/gqnoenforce Group disk quota accounting enabled and limits (optionally) - enforced. Refer to xfs_quota(8) for further details. + enforced. Refer to **xfs_quota(8)** for further details. pquota/prjquota/pqnoenforce Project disk quota accounting enabled and limits (optionally) - enforced. Refer to xfs_quota(8) for further details. + enforced. Refer to **xfs_quota(8)** for further details. sunit=value and swidth=value Used to specify the stripe unit and width for a RAID device @@ -192,11 +185,11 @@ default behaviour. block units. These options are only relevant to filesystems that were created with non-zero data alignment parameters. - The sunit and swidth parameters specified must be compatible + The ``sunit`` and ``swidth`` parameters specified must be compatible with the existing filesystem alignment characteristics. In - general, that means the only valid changes to sunit are - increasing it by a power-of-2 multiple. Valid swidth values - are any integer multiple of a valid sunit value. + general, that means the only valid changes to ``sunit`` are + increasing it by a power-of-2 multiple. Valid ``swidth`` values + are any integer multiple of a valid ``sunit`` value. Typically the only time these mount options are necessary if after an underlying RAID device has had it's geometry @@ -221,22 +214,25 @@ default behaviour. Deprecated Mount Options ======================== +=========================== ================ Name Removal Schedule - ---- ---------------- +=========================== ================ +=========================== ================ Removed Mount Options ===================== +=========================== ======= Name Removed - ---- ------- +=========================== ======= delaylog/nodelaylog v4.0 ihashsize v4.0 irixsgid v4.0 osyncisdsync/osyncisosync v4.0 barrier v4.19 nobarrier v4.19 - +=========================== ======= sysctls ======= @@ -302,27 +298,27 @@ The following sysctls are available for the XFS filesystem: fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1) Setting this to "1" will cause the "sync" flag set - by the xfs_io(8) chattr command on a directory to be + by the **xfs_io(8)** chattr command on a directory to be inherited by files in that directory. fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1) Setting this to "1" will cause the "nodump" flag set - by the xfs_io(8) chattr command on a directory to be + by the **xfs_io(8)** chattr command on a directory to be inherited by files in that directory. fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1) Setting this to "1" will cause the "noatime" flag set - by the xfs_io(8) chattr command on a directory to be + by the **xfs_io(8)** chattr command on a directory to be inherited by files in that directory. fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1) Setting this to "1" will cause the "nosymlinks" flag set - by the xfs_io(8) chattr command on a directory to be + by the **xfs_io(8)** chattr command on a directory to be inherited by files in that directory. fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1) Setting this to "1" will cause the "nodefrag" flag set - by the xfs_io(8) chattr command on a directory to be + by the **xfs_io(8)** chattr command on a directory to be inherited by files in that directory. fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256) @@ -368,7 +364,7 @@ handler: -error handlers: Defines the behavior for a specific error. -The filesystem behavior during an error can be set via sysfs files. Each +The filesystem behavior during an error can be set via ``sysfs`` files. Each error handler works independently - the first condition met by an error handler for a specific class will cause the error to be propagated rather than reset and retried. @@ -419,7 +415,7 @@ level directory: handler configurations. Note: there is no guarantee that fail_at_unmount can be set while an - unmount is in progress. It is possible that the sysfs entries are + unmount is in progress. It is possible that the ``sysfs`` entries are removed by the unmounting filesystem before a "retry forever" error handler configuration causes unmount to hang, and hence the filesystem must be configured appropriately before unmount begins to prevent @@ -428,7 +424,7 @@ level directory: Each filesystem has specific error class handlers that define the error propagation behaviour for specific errors. There is also a "default" error handler defined, which defines the behaviour for all errors that don't have -specific handlers defined. Where multiple retry constraints are configuredi for +specific handlers defined. Where multiple retry constraints are configured for a single error, the first retry configuration that expires will cause the error to be propagated. The handler configurations are found in the directory: @@ -463,7 +459,7 @@ to be propagated. The handler configurations are found in the directory: Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the operation for up to "N" seconds before propagating the error. -Note: The default behaviour for a specific error handler is dependent on both +**Note:** The default behaviour for a specific error handler is dependent on both the class and error context. For example, the default values for "metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults to "fail immediately" behaviour. This is done because ENODEV is a fatal, diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README deleted file mode 100644 index 56ada27c53be..000000000000 --- a/Documentation/arm/Marvell/README +++ /dev/null @@ -1,395 +0,0 @@ -ARM Marvell SoCs -================ - -This document lists all the ARM Marvell SoCs that are currently -supported in mainline by the Linux kernel. As the Marvell families of -SoCs are large and complex, it is hard to understand where the support -for a particular SoC is available in the Linux kernel. This document -tries to help in understanding where those SoCs are supported, and to -match them with their corresponding public datasheet, when available. - -Orion family ------------- - - Flavors: - 88F5082 - 88F5181 - 88F5181L - 88F5182 - Datasheet : http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf - Programmer's User Guide : http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf - User Manual : http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf - 88F5281 - Datasheet : http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf - 88F6183 - Core: Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible - Linux kernel mach directory: arch/arm/mach-orion5x - Linux kernel plat directory: arch/arm/plat-orion - -Kirkwood family ---------------- - - Flavors: - 88F6282 a.k.a Armada 300 - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6283 a.k.a Armada 310 - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6190 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6192 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6182 - 88F6180 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6281 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - Homepage: http://www.marvell.com/embedded-processors/kirkwood/ - Core: Feroceon 88fr131 ARMv5 compatible - Linux kernel mach directory: arch/arm/mach-mvebu - Linux kernel plat directory: none - -Discovery family ----------------- - - Flavors: - MV78100 - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf - MV78200 - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf - MV76100 - Not supported by the Linux kernel. - - Core: Feroceon 88fr571-vd ARMv5 compatible - - Linux kernel mach directory: arch/arm/mach-mv78xx0 - Linux kernel plat directory: arch/arm/plat-orion - -EBU Armada family ------------------ - - Armada 370 Flavors: - 88F6710 - 88F6707 - 88F6W11 - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf - Hardware Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf - Core: Sheeva ARMv7 compatible PJ4B - - Armada 375 Flavors: - 88F6720 - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf - Core: ARM Cortex-A9 - - Armada 38x Flavors: - 88F6810 Armada 380 - 88F6820 Armada 385 - 88F6828 Armada 388 - Product infos: http://www.marvell.com/embedded-processors/armada-38x/ - Functional Spec: https://marvellcorp.wufoo.com/forms/marvell-armada-38x-functional-specifications/ - Core: ARM Cortex-A9 - - Armada 39x Flavors: - 88F6920 Armada 390 - 88F6928 Armada 398 - Product infos: http://www.marvell.com/embedded-processors/armada-39x/ - Core: ARM Cortex-A9 - - Armada XP Flavors: - MV78230 - MV78260 - MV78460 - NOTE: not to be confused with the non-SMP 78xx0 SoCs - Product Brief: http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf - Functional Spec: http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf - Hardware Specs: - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF - Core: Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP - - Linux kernel mach directory: arch/arm/mach-mvebu - Linux kernel plat directory: none - -EBU Armada family ARMv8 ------------------------ - - Armada 3710/3720 Flavors: - 88F3710 - 88F3720 - Core: ARM Cortex A53 (ARMv8) - - Homepage: http://www.marvell.com/embedded-processors/armada-3700/ - Product Brief: http://www.marvell.com/embedded-processors/assets/PB-88F3700-FNL.pdf - Device tree files: arch/arm64/boot/dts/marvell/armada-37* - - Armada 7K Flavors: - 88F7020 (AP806 Dual + one CP110) - 88F7040 (AP806 Quad + one CP110) - Core: ARM Cortex A72 - - Homepage: http://www.marvell.com/embedded-processors/armada-70xx/ - Product Brief: http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf - Device tree files: arch/arm64/boot/dts/marvell/armada-70* - - Armada 8K Flavors: - 88F8020 (AP806 Dual + two CP110) - 88F8040 (AP806 Quad + two CP110) - Core: ARM Cortex A72 - - Homepage: http://www.marvell.com/embedded-processors/armada-80xx/ - Product Brief: http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf - Device tree files: arch/arm64/boot/dts/marvell/armada-80* - -Avanta family -------------- - - Flavors: - 88F6510 - 88F6530P - 88F6550 - 88F6560 - Homepage : http://www.marvell.com/broadband/ - Product Brief: http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf - No public datasheet available. - - Core: ARMv5 compatible - - Linux kernel mach directory: no code in mainline yet, planned for the future - Linux kernel plat directory: no code in mainline yet, planned for the future - -Storage family --------------- - - Armada SP: - 88RC1580 - Product infos: http://www.marvell.com/storage/armada-sp/ - Core: Sheeva ARMv7 comatible Quad-core PJ4C - (not supported in upstream Linux kernel) - -Dove family (application processor) ------------------------------------ - - Flavors: - 88AP510 a.k.a Armada 510 - Product Brief : http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf - Hardware Spec : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf - Functional Spec : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf - Homepage: http://www.marvell.com/application-processors/armada-500/ - Core: ARMv7 compatible - - Directory: arch/arm/mach-mvebu (DT enabled platforms) - arch/arm/mach-dove (non-DT enabled platforms) - -PXA 2xx/3xx/93x/95x family --------------------------- - - Flavors: - PXA21x, PXA25x, PXA26x - Application processor only - Core: ARMv5 XScale1 core - PXA270, PXA271, PXA272 - Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf - Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf - Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf - Application processor only - Core: ARMv5 XScale2 core - PXA300, PXA310, PXA320 - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip - Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf - Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip - Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf - Application processor only - Core: ARMv5 XScale3 core - PXA930, PXA935 - Application processor with Communication processor - Core: ARMv5 XScale3 core - PXA955 - Application processor with Communication processor - Core: ARMv7 compatible Sheeva PJ4 core - - Comments: - - * This line of SoCs originates from the XScale family developed by - Intel and acquired by Marvell in ~2006. The PXA21x, PXA25x, - PXA26x, PXA27x, PXA3xx and PXA93x were developed by Intel, while - the later PXA95x were developed by Marvell. - - * Due to their XScale origin, these SoCs have virtually nothing in - common with the other (Kirkwood, Dove, etc.) families of Marvell - SoCs, except with the MMP/MMP2 family of SoCs. - - Linux kernel mach directory: arch/arm/mach-pxa - Linux kernel plat directory: arch/arm/plat-pxa - -MMP/MMP2/MMP3 family (communication processor) ------------------------------------------ - - Flavors: - PXA168, a.k.a Armada 168 - Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp - Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf - Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf - Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf - Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf - App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf - Application processor only - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - PXA910/PXA920 - Homepage : http://www.marvell.com/communication-processors/pxa910/ - Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf - Application processor with Communication processor - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - PXA688, a.k.a. MMP2, a.k.a Armada 610 - Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf - Application processor only - Core: ARMv7 compatible Sheeva PJ4 88sv581x core - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream) - Product Brief : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf - Application processor only - Core: Dual-core ARMv7 compatible Sheeva PJ4C core - PXA960/PXA968/PXA978 (Linux support not upstream) - Application processor with Communication Processor - Core: ARMv7 compatible Sheeva PJ4 core - PXA986/PXA988 (Linux support not upstream) - Application processor with Communication Processor - Core: Dual-core ARMv7 compatible Sheeva PJ4B-MP core - PXA1088/PXA1920 (Linux support not upstream) - Application processor with Communication Processor - Core: quad-core ARMv7 Cortex-A7 - PXA1908/PXA1928/PXA1936 - Application processor with Communication Processor - Core: multi-core ARMv8 Cortex-A53 - - Comments: - - * This line of SoCs originates from the XScale family developed by - Intel and acquired by Marvell in ~2006. All the processors of - this MMP/MMP2 family were developed by Marvell. - - * Due to their XScale origin, these SoCs have virtually nothing in - common with the other (Kirkwood, Dove, etc.) families of Marvell - SoCs, except with the PXA family of SoCs listed above. - - Linux kernel mach directory: arch/arm/mach-mmp - Linux kernel plat directory: arch/arm/plat-pxa - -Berlin family (Multimedia Solutions) -------------------------------------- - - Flavors: - 88DE3010, Armada 1000 (no Linux support) - Core: Marvell PJ1 (ARMv5TE), Dual-core - Product Brief: http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf - 88DE3005, Armada 1500 Mini - Design name: BG2CD - Core: ARM Cortex-A9, PL310 L2CC - 88DE3006, Armada 1500 Mini Plus - Design name: BG2CDP - Core: Dual Core ARM Cortex-A7 - 88DE3100, Armada 1500 - Design name: BG2 - Core: Marvell PJ4B-MP (ARMv7), Tauros3 L2CC - 88DE3114, Armada 1500 Pro - Design name: BG2Q - Core: Quad Core ARM Cortex-A9, PL310 L2CC - 88DE3214, Armada 1500 Pro 4K - Design name: BG3 - Core: ARM Cortex-A15, CA15 integrated L2CC - 88DE3218, ARMADA 1500 Ultra - Core: ARM Cortex-A53 - - Homepage: https://www.synaptics.com/products/multimedia-solutions - Directory: arch/arm/mach-berlin - - Comments: - - * This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs - with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, ETH, ...). - - * The Berlin family was acquired by Synaptics from Marvell in 2017. - -CPU Cores ---------- - -The XScale cores were designed by Intel, and shipped by Marvell in the older -PXA processors. Feroceon is a Marvell designed core that developed in-house, -and that evolved into Sheeva. The XScale and Feroceon cores were phased out -over time and replaced with Sheeva cores in later products, which subsequently -got replaced with licensed ARM Cortex-A cores. - - XScale 1 - CPUID 0x69052xxx - ARMv5, iWMMXt - XScale 2 - CPUID 0x69054xxx - ARMv5, iWMMXt - XScale 3 - CPUID 0x69056xxx or 0x69056xxx - ARMv5, iWMMXt - Feroceon-1850 88fr331 "Mohawk" - CPUID 0x5615331x or 0x41xx926x - ARMv5TE, single issue - Feroceon-2850 88fr531-vd "Jolteon" - CPUID 0x5605531x or 0x41xx926x - ARMv5TE, VFP, dual-issue - Feroceon 88fr571-vd "Jolteon" - CPUID 0x5615571x - ARMv5TE, VFP, dual-issue - Feroceon 88fr131 "Mohawk-D" - CPUID 0x5625131x - ARMv5TE, single-issue in-order - Sheeva PJ1 88sv331 "Mohawk" - CPUID 0x561584xx - ARMv5, single-issue iWMMXt v2 - Sheeva PJ4 88sv581x "Flareon" - CPUID 0x560f581x - ARMv7, idivt, optional iWMMXt v2 - Sheeva PJ4B 88sv581x - CPUID 0x561f581x - ARMv7, idivt, optional iWMMXt v2 - Sheeva PJ4B-MP / PJ4C - CPUID 0x562f584x - ARMv7, idivt/idiva, LPAE, optional iWMMXt v2 and/or NEON - -Long-term plans ---------------- - - * Unify the mach-dove/, mach-mv78xx0/, mach-orion5x/ into the - mach-mvebu/ to support all SoCs from the Marvell EBU (Engineering - Business Unit) in a single mach-<foo> directory. The plat-orion/ - would therefore disappear. - - * Unify the mach-mmp/ and mach-pxa/ into the same mach-pxa - directory. The plat-pxa/ would therefore disappear. - -Credits -------- - - Maen Suleiman <maen@marvell.com> - Lior Amsalem <alior@marvell.com> - Thomas Petazzoni <thomas.petazzoni@free-electrons.com> - Andrew Lunn <andrew@lunn.ch> - Nicolas Pitre <nico@fluxnic.net> - Eric Miao <eric.y.miao@gmail.com> diff --git a/Documentation/arm/Netwinder b/Documentation/arm/Netwinder deleted file mode 100644 index f1b457fbd3de..000000000000 --- a/Documentation/arm/Netwinder +++ /dev/null @@ -1,78 +0,0 @@ -NetWinder specific documentation -================================ - -The NetWinder is a small low-power computer, primarily designed -to run Linux. It is based around the StrongARM RISC processor, -DC21285 PCI bridge, with PC-type hardware glued around it. - -Port usage -========== - -Min - Max Description ---------------------------- -0x0000 - 0x000f DMA1 -0x0020 - 0x0021 PIC1 -0x0060 - 0x006f Keyboard -0x0070 - 0x007f RTC -0x0080 - 0x0087 DMA1 -0x0088 - 0x008f DMA2 -0x00a0 - 0x00a3 PIC2 -0x00c0 - 0x00df DMA2 -0x0180 - 0x0187 IRDA -0x01f0 - 0x01f6 ide0 -0x0201 Game port -0x0203 RWA010 configuration read -0x0220 - ? SoundBlaster -0x0250 - ? WaveArtist -0x0279 RWA010 configuration index -0x02f8 - 0x02ff Serial ttyS1 -0x0300 - 0x031f Ether10 -0x0338 GPIO1 -0x033a GPIO2 -0x0370 - 0x0371 W83977F configuration registers -0x0388 - ? AdLib -0x03c0 - 0x03df VGA -0x03f6 ide0 -0x03f8 - 0x03ff Serial ttyS0 -0x0400 - 0x0408 DC21143 -0x0480 - 0x0487 DMA1 -0x0488 - 0x048f DMA2 -0x0a79 RWA010 configuration write -0xe800 - 0xe80f ide0/ide1 BM DMA - - -Interrupt usage -=============== - -IRQ type Description ---------------------------- - 0 ISA 100Hz timer - 1 ISA Keyboard - 2 ISA cascade - 3 ISA Serial ttyS1 - 4 ISA Serial ttyS0 - 5 ISA PS/2 mouse - 6 ISA IRDA - 7 ISA Printer - 8 ISA RTC alarm - 9 ISA -10 ISA GP10 (Orange reset button) -11 ISA -12 ISA WaveArtist -13 ISA -14 ISA hda1 -15 ISA - -DMA usage -========= - -DMA type Description ---------------------------- - 0 ISA IRDA - 1 ISA - 2 ISA cascade - 3 ISA WaveArtist - 4 ISA - 5 ISA - 6 ISA - 7 ISA WaveArtist diff --git a/Documentation/arm/SA1100/FreeBird b/Documentation/arm/SA1100/FreeBird deleted file mode 100644 index ab9193663b2b..000000000000 --- a/Documentation/arm/SA1100/FreeBird +++ /dev/null @@ -1,21 +0,0 @@ -Freebird-1.1 is produced by Legend(C), Inc. -http://web.archive.org/web/*/http://www.legend.com.cn -and software/linux maintained by Coventive(C), Inc. -(http://www.coventive.com) - -Based on the Nicolas's strongarm kernel tree. - -=============================================================== -Maintainer: - -Chester Kuo <chester@coventive.com> - <chester@linux.org.tw> - -Author : -Tim wu <timwu@coventive.com> -CIH <cih@coventive.com> -Eric Peng <ericpeng@coventive.com> -Jeff Lee <jeff_lee@coventive.com> -Allen Cheng -Tony Liu <tonyliu@coventive.com> - diff --git a/Documentation/arm/SA1100/empeg b/Documentation/arm/SA1100/empeg deleted file mode 100644 index 4ece4849a42c..000000000000 --- a/Documentation/arm/SA1100/empeg +++ /dev/null @@ -1,2 +0,0 @@ -See ../empeg/README - diff --git a/Documentation/arm/SA1100/serial_UART b/Documentation/arm/SA1100/serial_UART deleted file mode 100644 index a63966f1d083..000000000000 --- a/Documentation/arm/SA1100/serial_UART +++ /dev/null @@ -1,47 +0,0 @@ -The SA1100 serial port had its major/minor numbers officially assigned: - -> Date: Sun, 24 Sep 2000 21:40:27 -0700 -> From: H. Peter Anvin <hpa@transmeta.com> -> To: Nicolas Pitre <nico@CAM.ORG> -> Cc: Device List Maintainer <device@lanana.org> -> Subject: Re: device -> -> Okay. Note that device numbers 204 and 205 are used for "low density -> serial devices", so you will have a range of minors on those majors (the -> tty device layer handles this just fine, so you don't have to worry about -> doing anything special.) -> -> So your assignments are: -> -> 204 char Low-density serial ports -> 5 = /dev/ttySA0 SA1100 builtin serial port 0 -> 6 = /dev/ttySA1 SA1100 builtin serial port 1 -> 7 = /dev/ttySA2 SA1100 builtin serial port 2 -> -> 205 char Low-density serial ports (alternate device) -> 5 = /dev/cusa0 Callout device for ttySA0 -> 6 = /dev/cusa1 Callout device for ttySA1 -> 7 = /dev/cusa2 Callout device for ttySA2 -> - -You must create those inodes in /dev on the root filesystem used -by your SA1100-based device: - - mknod ttySA0 c 204 5 - mknod ttySA1 c 204 6 - mknod ttySA2 c 204 7 - mknod cusa0 c 205 5 - mknod cusa1 c 205 6 - mknod cusa2 c 205 7 - -In addition to the creation of the appropriate device nodes above, you -must ensure your user space applications make use of the correct device -name. The classic example is the content of the /etc/inittab file where -you might have a getty process started on ttyS0. In this case: - -- replace occurrences of ttyS0 with ttySA0, ttyS1 with ttySA1, etc. - -- don't forget to add 'ttySA0', 'console', or the appropriate tty name - in /etc/securetty for root to be allowed to login as well. - - diff --git a/Documentation/arm/README b/Documentation/arm/arm.rst index 9d1e5b2c92e6..2edc509df92a 100644 --- a/Documentation/arm/README +++ b/Documentation/arm/arm.rst @@ -1,5 +1,6 @@ - ARM Linux 2.6 - ============= +======================= +ARM Linux 2.6 and upper +======================= Please check <ftp://ftp.arm.linux.org.uk/pub/armlinux> for updates. @@ -18,22 +19,28 @@ Compilation of kernel line as detailed below. If you wish to cross-compile, then alter the following lines in the top - level make file: + level make file:: ARCH = <whatever> - with + + with:: + ARCH = arm - and + and:: CROSS_COMPILE= - to + + to:: + CROSS_COMPILE=<your-path-to-your-compiler-without-gcc> - eg. + + eg.:: + CROSS_COMPILE=arm-linux- - Do a 'make config', followed by 'make Image' to build the kernel - (arch/arm/boot/Image). A compressed image can be built by doing a + Do a 'make config', followed by 'make Image' to build the kernel + (arch/arm/boot/Image). A compressed image can be built by doing a 'make zImage' instead of 'make Image'. @@ -46,7 +53,7 @@ Bug reports etc Bug reports should be sent to linux-arm-kernel@lists.arm.linux.org.uk, or submitted through the web form at - http://www.arm.linux.org.uk/developer/ + http://www.arm.linux.org.uk/developer/ When sending bug reports, please ensure that they contain all relevant information, eg. the kernel messages that were printed before/during @@ -60,11 +67,13 @@ Include files which are there to reduce the clutter in the top-level directory. These directories, and their purpose is listed below: - arch-* machine/platform specific header files - hardware driver-internal ARM specific data structures/definitions - mach descriptions of generic ARM to specific machine interfaces - proc-* processor dependent header files (currently only two + ============= ========================================================== + `arch-*` machine/platform specific header files + `hardware` driver-internal ARM specific data structures/definitions + `mach` descriptions of generic ARM to specific machine interfaces + `proc-*` processor dependent header files (currently only two categories) + ============= ========================================================== Machine/Platform support @@ -129,7 +138,7 @@ ST506 hard drives HDC base to the source. As of 31/3/96 it works with two drives (you should get the ADFS - *configure harddrive set to 2). I've got an internal 20MB and a great + `*configure` harddrive set to 2). I've got an internal 20MB and a great big external 5.25" FH 64MB drive (who could ever want more :-) ). I've just got 240K/s off it (a dd with bs=128k); thats about half of what @@ -149,13 +158,13 @@ ST506 hard drives are welcome. -CONFIG_MACH_ and CONFIG_ARCH_ ------------------------------ +`CONFIG_MACH_` and `CONFIG_ARCH_` +--------------------------------- A change was made in 2003 to the macro names for new machines. - Historically, CONFIG_ARCH_ was used for the bonafide architecture, + Historically, `CONFIG_ARCH_` was used for the bonafide architecture, e.g. SA1100, as well as implementations of the architecture, e.g. Assabet. It was decided to change the implementation macros - to read CONFIG_MACH_ for clarity. Moreover, a retroactive fixup has + to read `CONFIG_MACH_` for clarity. Moreover, a retroactive fixup has not been made because it would complicate patching. Previous registrations may be found online. @@ -163,7 +172,7 @@ CONFIG_MACH_ and CONFIG_ARCH_ <http://www.arm.linux.org.uk/developer/machines/> Kernel entry (head.S) --------------------------- +--------------------- The initial entry into the kernel is via head.S, which uses machine independent code. The machine is selected by the value of 'r1' on entry, which must be kept unique. @@ -201,4 +210,5 @@ Kernel entry (head.S) platform is DT-only, you do not need a registered machine type. --- + Russell King (15/03/2004) diff --git a/Documentation/arm/Booting b/Documentation/arm/booting.rst index f1f965ce93d6..4babb6c6ae1e 100644 --- a/Documentation/arm/Booting +++ b/Documentation/arm/booting.rst @@ -1,7 +1,9 @@ - Booting ARM Linux - ================= +================= +Booting ARM Linux +================= Author: Russell King + Date : 18 May 2002 The following documentation is relevant to 2.4.18-rmk6 and beyond. @@ -25,8 +27,10 @@ following: 1. Setup and initialise RAM --------------------------- -Existing boot loaders: MANDATORY -New boot loaders: MANDATORY +Existing boot loaders: + MANDATORY +New boot loaders: + MANDATORY The boot loader is expected to find and initialise all RAM that the kernel will use for volatile data storage in the system. It performs @@ -39,8 +43,10 @@ sees fit.) 2. Initialise one serial port ----------------------------- -Existing boot loaders: OPTIONAL, RECOMMENDED -New boot loaders: OPTIONAL, RECOMMENDED +Existing boot loaders: + OPTIONAL, RECOMMENDED +New boot loaders: + OPTIONAL, RECOMMENDED The boot loader should initialise and enable one serial port on the target. This allows the kernel serial driver to automatically detect @@ -57,8 +63,10 @@ serial format options as described in 3. Detect the machine type -------------------------- -Existing boot loaders: OPTIONAL -New boot loaders: MANDATORY except for DT-only platforms +Existing boot loaders: + OPTIONAL +New boot loaders: + MANDATORY except for DT-only platforms The boot loader should detect the machine type its running on by some method. Whether this is a hard coded value or some algorithm that @@ -74,8 +82,10 @@ necessary, but assures that it will not match any existing types. 4. Setup boot data ------------------ -Existing boot loaders: OPTIONAL, HIGHLY RECOMMENDED -New boot loaders: MANDATORY +Existing boot loaders: + OPTIONAL, HIGHLY RECOMMENDED +New boot loaders: + MANDATORY The boot loader must provide either a tagged list or a dtb image for passing configuration data to the kernel. The physical address of the @@ -97,15 +107,15 @@ entirety; some tags behave as the former, others the latter. The boot loader must pass at a minimum the size and location of the system memory, and root filesystem location. Therefore, the -minimum tagged list should look: +minimum tagged list should look:: - +-----------+ -base -> | ATAG_CORE | | - +-----------+ | - | ATAG_MEM | | increasing address - +-----------+ | - | ATAG_NONE | | - +-----------+ v + +-----------+ + base -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | increasing address + +-----------+ | + | ATAG_NONE | | + +-----------+ v The tagged list should be stored in system RAM. @@ -134,8 +144,10 @@ A safe location is just above the 128MiB boundary from start of RAM. 5. Load initramfs. ------------------ -Existing boot loaders: OPTIONAL -New boot loaders: OPTIONAL +Existing boot loaders: + OPTIONAL +New boot loaders: + OPTIONAL If an initramfs is in use then, as with the dtb, it must be placed in a region of memory where the kernel decompressor will not overwrite it @@ -149,8 +161,10 @@ recommended above. 6. Calling the kernel image --------------------------- -Existing boot loaders: MANDATORY -New boot loaders: MANDATORY +Existing boot loaders: + MANDATORY +New boot loaders: + MANDATORY There are two options for calling the kernel zImage. If the zImage is stored in flash, and is linked correctly to be run from flash, @@ -174,12 +188,14 @@ In any case, the following conditions must be met: you many hours of debug. - CPU register settings - r0 = 0, - r1 = machine type number discovered in (3) above. - r2 = physical address of tagged list in system RAM, or - physical address of device tree block (dtb) in system RAM + + - r0 = 0, + - r1 = machine type number discovered in (3) above. + - r2 = physical address of tagged list in system RAM, or + physical address of device tree block (dtb) in system RAM - CPU mode + All forms of interrupts must be disabled (IRQs and FIQs) For CPUs which do not include the ARM virtualization extensions, the @@ -195,8 +211,11 @@ In any case, the following conditions must be met: entered in SVC mode. - Caches, MMUs + The MMU must be off. + Instruction cache may be on or off. + Data cache must be off. If the kernel is entered in HYP mode, the above requirements apply to diff --git a/Documentation/arm/cluster-pm-race-avoidance.txt b/Documentation/arm/cluster-pm-race-avoidance.rst index 750b6fc24af9..aa58603d3f28 100644 --- a/Documentation/arm/cluster-pm-race-avoidance.txt +++ b/Documentation/arm/cluster-pm-race-avoidance.rst @@ -1,3 +1,4 @@ +========================================================= Cluster-wide Power-up/power-down race avoidance algorithm ========================================================= @@ -46,10 +47,12 @@ Basic model Each cluster and CPU is assigned a state, as follows: - DOWN - COMING_UP - UP - GOING_DOWN + - DOWN + - COMING_UP + - UP + - GOING_DOWN + +:: +---------> UP ----------+ | v @@ -60,18 +63,22 @@ Each cluster and CPU is assigned a state, as follows: +--------- DOWN <--------+ -DOWN: The CPU or cluster is not coherent, and is either powered off or +DOWN: + The CPU or cluster is not coherent, and is either powered off or suspended, or is ready to be powered off or suspended. -COMING_UP: The CPU or cluster has committed to moving to the UP state. +COMING_UP: + The CPU or cluster has committed to moving to the UP state. It may be part way through the process of initialisation and enabling coherency. -UP: The CPU or cluster is active and coherent at the hardware +UP: + The CPU or cluster is active and coherent at the hardware level. A CPU in this state is not necessarily being used actively by the kernel. -GOING_DOWN: The CPU or cluster has committed to moving to the DOWN +GOING_DOWN: + The CPU or cluster has committed to moving to the DOWN state. It may be part way through the process of teardown and coherency exit. @@ -86,8 +93,8 @@ CPUs in the cluster simultaneously modifying the state. The cluster- level states are described in the "Cluster state" section. To help distinguish the CPU states from cluster states in this -discussion, the state names are given a CPU_ prefix for the CPU states, -and a CLUSTER_ or INBOUND_ prefix for the cluster states. +discussion, the state names are given a `CPU_` prefix for the CPU states, +and a `CLUSTER_` or `INBOUND_` prefix for the cluster states. CPU state @@ -101,10 +108,12 @@ This means that CPUs fit the basic model closely. The algorithm defines the following states for each CPU in the system: - CPU_DOWN - CPU_COMING_UP - CPU_UP - CPU_GOING_DOWN + - CPU_DOWN + - CPU_COMING_UP + - CPU_UP + - CPU_GOING_DOWN + +:: cluster setup and CPU setup complete policy decision @@ -130,17 +139,17 @@ requirement for any external event to happen. CPU_DOWN: - A CPU reaches the CPU_DOWN state when it is ready for power-down. On reaching this state, the CPU will typically power itself down or suspend itself, via a WFI instruction or a firmware call. - Next state: CPU_COMING_UP - Conditions: none + Next state: + CPU_COMING_UP + Conditions: + none Trigger events: - a) an explicit hardware power-up operation, resulting from a policy decision on another CPU; @@ -148,15 +157,17 @@ CPU_DOWN: CPU_COMING_UP: - A CPU cannot start participating in hardware coherency until the cluster is set up and coherent. If the cluster is not ready, then the CPU will wait in the CPU_COMING_UP state until the cluster has been set up. - Next state: CPU_UP - Conditions: The CPU's parent cluster must be in CLUSTER_UP. - Trigger events: Transition of the parent cluster to CLUSTER_UP. + Next state: + CPU_UP + Conditions: + The CPU's parent cluster must be in CLUSTER_UP. + Trigger events: + Transition of the parent cluster to CLUSTER_UP. Refer to the "Cluster state" section for a description of the CLUSTER_UP state. @@ -178,20 +189,25 @@ CPU_UP: The CPU remains in this state until an explicit policy decision is made to shut down or suspend the CPU. - Next state: CPU_GOING_DOWN - Conditions: none - Trigger events: explicit policy decision + Next state: + CPU_GOING_DOWN + Conditions: + none + Trigger events: + explicit policy decision CPU_GOING_DOWN: - While in this state, the CPU exits coherency, including any operations required to achieve this (such as cleaning data caches). - Next state: CPU_DOWN - Conditions: local CPU teardown complete - Trigger events: (spontaneous) + Next state: + CPU_DOWN + Conditions: + local CPU teardown complete + Trigger events: + (spontaneous) Cluster state @@ -212,20 +228,20 @@ independently of the CPU which is tearing down the cluster. For this reason, the cluster state is split into two parts: "cluster" state: The global state of the cluster; or the state - on the outbound side: + on the outbound side: - CLUSTER_DOWN - CLUSTER_UP - CLUSTER_GOING_DOWN + - CLUSTER_DOWN + - CLUSTER_UP + - CLUSTER_GOING_DOWN "inbound" state: The state of the cluster on the inbound side. - INBOUND_NOT_COMING_UP - INBOUND_COMING_UP + - INBOUND_NOT_COMING_UP + - INBOUND_COMING_UP The different pairings of these states results in six possible - states for the cluster as a whole: + states for the cluster as a whole:: CLUSTER_UP +==========> INBOUND_NOT_COMING_UP -------------+ @@ -284,11 +300,12 @@ reason, the cluster state is split into two parts: CLUSTER_DOWN/INBOUND_NOT_COMING_UP: + Next state: + CLUSTER_DOWN/INBOUND_COMING_UP (inbound) + Conditions: + none - Next state: CLUSTER_DOWN/INBOUND_COMING_UP (inbound) - Conditions: none Trigger events: - a) an explicit hardware power-up operation, resulting from a policy decision on another CPU; @@ -306,9 +323,12 @@ CLUSTER_DOWN/INBOUND_COMING_UP: setup to enable other CPUs in the cluster to enter coherency safely. - Next state: CLUSTER_UP/INBOUND_COMING_UP (inbound) - Conditions: cluster-level setup and hardware coherency complete - Trigger events: (spontaneous) + Next state: + CLUSTER_UP/INBOUND_COMING_UP (inbound) + Conditions: + cluster-level setup and hardware coherency complete + Trigger events: + (spontaneous) CLUSTER_UP/INBOUND_COMING_UP: @@ -321,9 +341,12 @@ CLUSTER_UP/INBOUND_COMING_UP: CLUSTER_UP/INBOUND_NOT_COMING_UP. All other CPUs on the cluster should consider treat these two states as equivalent. - Next state: CLUSTER_UP/INBOUND_NOT_COMING_UP (inbound) - Conditions: none - Trigger events: (spontaneous) + Next state: + CLUSTER_UP/INBOUND_NOT_COMING_UP (inbound) + Conditions: + none + Trigger events: + (spontaneous) CLUSTER_UP/INBOUND_NOT_COMING_UP: @@ -335,9 +358,12 @@ CLUSTER_UP/INBOUND_NOT_COMING_UP: The cluster will remain in this state until a policy decision is made to power the cluster down. - Next state: CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP (outbound) - Conditions: none - Trigger events: policy decision to power down the cluster + Next state: + CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP (outbound) + Conditions: + none + Trigger events: + policy decision to power down the cluster CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP: @@ -359,13 +385,16 @@ CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP: Next states: CLUSTER_DOWN/INBOUND_NOT_COMING_UP (outbound) - Conditions: cluster torn down and ready to power off - Trigger events: (spontaneous) + Conditions: + cluster torn down and ready to power off + Trigger events: + (spontaneous) CLUSTER_GOING_DOWN/INBOUND_COMING_UP (inbound) - Conditions: none - Trigger events: + Conditions: + none + Trigger events: a) an explicit hardware power-up operation, resulting from a policy decision on another CPU; @@ -396,13 +425,19 @@ CLUSTER_GOING_DOWN/INBOUND_COMING_UP: Next states: CLUSTER_UP/INBOUND_COMING_UP (outbound) - Conditions: cluster-level setup and hardware + Conditions: + cluster-level setup and hardware coherency complete - Trigger events: (spontaneous) + + Trigger events: + (spontaneous) CLUSTER_DOWN/INBOUND_COMING_UP (outbound) - Conditions: cluster torn down and ready to power off - Trigger events: (spontaneous) + Conditions: + cluster torn down and ready to power off + + Trigger events: + (spontaneous) Last man and First man selection @@ -452,30 +487,30 @@ Implementation: arch/arm/common/mcpm_entry.c (everything else): __mcpm_cpu_going_down() signals the transition of a CPU to the - CPU_GOING_DOWN state. + CPU_GOING_DOWN state. __mcpm_cpu_down() signals the transition of a CPU to the CPU_DOWN - state. + state. A CPU transitions to CPU_COMING_UP and then to CPU_UP via the - low-level power-up code in mcpm_head.S. This could - involve CPU-specific setup code, but in the current - implementation it does not. + low-level power-up code in mcpm_head.S. This could + involve CPU-specific setup code, but in the current + implementation it does not. __mcpm_outbound_enter_critical() and __mcpm_outbound_leave_critical() - handle transitions from CLUSTER_UP to CLUSTER_GOING_DOWN - and from there to CLUSTER_DOWN or back to CLUSTER_UP (in - the case of an aborted cluster power-down). + handle transitions from CLUSTER_UP to CLUSTER_GOING_DOWN + and from there to CLUSTER_DOWN or back to CLUSTER_UP (in + the case of an aborted cluster power-down). - These functions are more complex than the __mcpm_cpu_*() - functions due to the extra inter-CPU coordination which - is needed for safe transitions at the cluster level. + These functions are more complex than the __mcpm_cpu_*() + functions due to the extra inter-CPU coordination which + is needed for safe transitions at the cluster level. A cluster transitions from CLUSTER_DOWN back to CLUSTER_UP via - the low-level power-up code in mcpm_head.S. This - typically involves platform-specific setup code, - provided by the platform-specific power_up_setup - function registered via mcpm_sync_init. + the low-level power-up code in mcpm_head.S. This + typically involves platform-specific setup code, + provided by the platform-specific power_up_setup + function registered via mcpm_sync_init. Deep topologies: diff --git a/Documentation/arm/firmware.txt b/Documentation/arm/firmware.rst index 7f175dbb427e..efd844baec1d 100644 --- a/Documentation/arm/firmware.txt +++ b/Documentation/arm/firmware.rst @@ -1,5 +1,7 @@ -Interface for registering and calling firmware-specific operations for ARM. ----- +========================================================================== +Interface for registering and calling firmware-specific operations for ARM +========================================================================== + Written by Tomasz Figa <t.figa@samsung.com> Some boards are running with secure firmware running in TrustZone secure @@ -9,7 +11,7 @@ operations and call them when needed. Firmware operations can be specified by filling in a struct firmware_ops with appropriate callbacks and then registering it with register_firmware_ops() -function. +function:: void register_firmware_ops(const struct firmware_ops *ops) @@ -19,7 +21,7 @@ and its members can be found in arch/arm/include/asm/firmware.h header. There is a default, empty set of operations provided, so there is no need to set anything if platform does not require firmware operations. -To call a firmware operation, a helper macro is provided +To call a firmware operation, a helper macro is provided:: #define call_firmware_op(op, ...) \ ((firmware_ops->op) ? firmware_ops->op(__VA_ARGS__) : (-ENOSYS)) @@ -28,7 +30,7 @@ the macro checks if the operation is provided and calls it or otherwise returns -ENOSYS to signal that given operation is not available (for example, to allow fallback to legacy operation). -Example of registering firmware operations: +Example of registering firmware operations:: /* board file */ @@ -56,7 +58,7 @@ Example of registering firmware operations: register_firmware_ops(&platformX_firmware_ops); } -Example of using a firmware operation: +Example of using a firmware operation:: /* some platform code, e.g. SMP initialization */ diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst new file mode 100644 index 000000000000..5fc072dd0c5e --- /dev/null +++ b/Documentation/arm/index.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +ARM Architecture +================ + +.. toctree:: + :maxdepth: 1 + + arm + booting + cluster-pm-race-avoidance + firmware + interrupts + kernel_mode_neon + kernel_user_helpers + memory + mem_alignment + tcm + setup + swp_emulation + uefi + vlocks + porting + +SoC-specific documents +====================== + +.. toctree:: + :maxdepth: 1 + + ixp4xx + + marvel + microchip + + netwinder + nwfpe/index + + keystone/overview + keystone/knav-qmss + + omap/index + + pxa/mfp + + + sa1100/index + + stm32/stm32f746-overview + stm32/overview + stm32/stm32h743-overview + stm32/stm32f769-overview + stm32/stm32f429-overview + stm32/stm32mp157-overview + + sunxi + + samsung/index + samsung-s3c24xx/index + + sunxi/clocks + + spear/overview + + sti/stih416-overview + sti/stih407-overview + sti/stih418-overview + sti/overview + sti/stih415-overview + + vfp/release-notes + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/arm/Interrupts b/Documentation/arm/interrupts.rst index f09ab1b90ef1..2ae70e0e9732 100644 --- a/Documentation/arm/Interrupts +++ b/Documentation/arm/interrupts.rst @@ -1,8 +1,10 @@ -2.5.2-rmk5 ----------- +========== +Interrupts +========== -This is the first kernel that contains a major shake up of some of the -major architecture-specific subsystems. +2.5.2-rmk5: + This is the first kernel that contains a major shake up of some of the + major architecture-specific subsystems. Firstly, it contains some pretty major changes to the way we handle the MMU TLB. Each MMU TLB variant is now handled completely separately - @@ -18,7 +20,7 @@ Unfortunately, this means that machine types that touch the irq_desc[] array (basically all machine types) will break, and this means every machine type that we currently have. -Lets take an example. On the Assabet with Neponset, we have: +Lets take an example. On the Assabet with Neponset, we have:: GPIO25 IRR:2 SA1100 ------------> Neponset -----------> SA1111 @@ -48,42 +50,47 @@ the irqdesc array). This doesn't have to be a real "IC"; indeed the SA11x0 IRQs are handled by two separate "chip" structures, one for GPIO0-10, and another for all the rest. It is just a container for the various operations (maybe this'll change to a better name). -This structure has the following operations: - -struct irqchip { - /* - * Acknowledge the IRQ. - * If this is a level-based IRQ, then it is expected to mask the IRQ - * as well. - */ - void (*ack)(unsigned int irq); - /* - * Mask the IRQ in hardware. - */ - void (*mask)(unsigned int irq); - /* - * Unmask the IRQ in hardware. - */ - void (*unmask)(unsigned int irq); - /* - * Re-run the IRQ - */ - void (*rerun)(unsigned int irq); - /* - * Set the type of the IRQ. - */ - int (*type)(unsigned int irq, unsigned int, type); -}; - -ack - required. May be the same function as mask for IRQs +This structure has the following operations:: + + struct irqchip { + /* + * Acknowledge the IRQ. + * If this is a level-based IRQ, then it is expected to mask the IRQ + * as well. + */ + void (*ack)(unsigned int irq); + /* + * Mask the IRQ in hardware. + */ + void (*mask)(unsigned int irq); + /* + * Unmask the IRQ in hardware. + */ + void (*unmask)(unsigned int irq); + /* + * Re-run the IRQ + */ + void (*rerun)(unsigned int irq); + /* + * Set the type of the IRQ. + */ + int (*type)(unsigned int irq, unsigned int, type); + }; + +ack + - required. May be the same function as mask for IRQs handled by do_level_IRQ. -mask - required. -unmask - required. -rerun - optional. Not required if you're using do_level_IRQ for all +mask + - required. +unmask + - required. +rerun + - optional. Not required if you're using do_level_IRQ for all IRQs that use this 'irqchip'. Generally expected to re-trigger the hardware IRQ if possible. If not, may call the handler directly. -type - optional. If you don't support changing the type of an IRQ, +type + - optional. If you don't support changing the type of an IRQ, it should be null so people can detect if they are unable to set the IRQ type. @@ -109,6 +116,7 @@ manipulation, nor state tracking. This is useful for things like the SMC9196 and USAR above. So, what's changed? +=================== 1. Machine implementations must not write to the irqdesc array. @@ -118,24 +126,19 @@ So, what's changed? absolutely necessary. set_irq_chip(irq,chip) - Set the mask/unmask methods for handling this IRQ set_irq_handler(irq,handler) - Set the handler for this IRQ (level, edge, simple) set_irq_chained_handler(irq,handler) - Set a "chained" handler for this IRQ - automatically enables this IRQ (eg, Neponset and SA1111 handlers). set_irq_flags(irq,flags) - Set the valid/probe/noautoenable flags. set_irq_type(irq,type) - Set active the IRQ edge(s)/level. This replaces the SA1111 INTPOL manipulation, and the set_GPIO_IRQ_edge() function. Type should be one of IRQ_TYPE_xxx defined in @@ -158,10 +161,9 @@ So, what's changed? be re-checked for pending events. (see the Neponset IRQ handler for details). -7. fixup_irq() is gone, as is arch/arm/mach-*/include/mach/irq.h +7. fixup_irq() is gone, as is `arch/arm/mach-*/include/mach/irq.h` Please note that this will not solve all problems - some of them are hardware based. Mixing level-based and edge-based IRQs on the same parent signal (eg neponset) is one such area where a software based solution can't provide the full answer to low IRQ latency. - diff --git a/Documentation/arm/IXP4xx b/Documentation/arm/ixp4xx.rst index e48b74de6ac0..a57235616294 100644 --- a/Documentation/arm/IXP4xx +++ b/Documentation/arm/ixp4xx.rst @@ -1,6 +1,6 @@ - -------------------------------------------------------------------------- +=========================================================== Release Notes for Linux on Intel's IXP4xx Network Processor +=========================================================== Maintained by Deepak Saxena <dsaxena@plexity.net> ------------------------------------------------------------------------- @@ -8,7 +8,7 @@ Maintained by Deepak Saxena <dsaxena@plexity.net> 1. Overview Intel's IXP4xx network processor is a highly integrated SOC that -is targeted for network applications, though it has become popular +is targeted for network applications, though it has become popular in industrial control and other areas due to low cost and power consumption. The IXP4xx family currently consists of several processors that support different network offload functions such as encryption, @@ -20,7 +20,7 @@ For more information on the various versions of the CPU, see: http://developer.intel.com/design/network/products/npfamily/ixp4xx.htm -Intel also made the IXCP1100 CPU for sometime which is an IXP4xx +Intel also made the IXCP1100 CPU for sometime which is an IXP4xx stripped of much of the network intelligence. 2. Linux Support @@ -31,7 +31,7 @@ Linux currently supports the following features on the IXP4xx chips: - PCI interface - Flash access (MTD/JFFS) - I2C through GPIO on IXP42x -- GPIO for input/output/interrupts +- GPIO for input/output/interrupts See arch/arm/mach-ixp4xx/include/mach/platform.h for access functions. - Timers (watchdog, OS) @@ -45,7 +45,7 @@ require the use of Intel's proprietary CSR software: If you need to use any of the above, you need to download Intel's software from: - http://developer.intel.com/design/network/products/npfamily/ixp425.htm + http://developer.intel.com/design/network/products/npfamily/ixp425.htm DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPRIETARY SOFTWARE. @@ -53,14 +53,14 @@ SOFTWARE. There are several websites that provide directions/pointers on using Intel's software: - http://sourceforge.net/projects/ixp4xx-osdg/ - Open Source Developer's Guide for using uClinux and the Intel libraries + - http://sourceforge.net/projects/ixp4xx-osdg/ + Open Source Developer's Guide for using uClinux and the Intel libraries -http://gatewaymaker.sourceforge.net/ - Simple one page summary of building a gateway using an IXP425 and Linux + - http://gatewaymaker.sourceforge.net/ + Simple one page summary of building a gateway using an IXP425 and Linux -http://ixp425.sourceforge.net/ - ATM device driver for IXP425 that relies on Intel's libraries + - http://ixp425.sourceforge.net/ + ATM device driver for IXP425 that relies on Intel's libraries 3. Known Issues/Limitations @@ -70,7 +70,7 @@ The IXP4xx family allows for up to 256MB of memory but the PCI interface can only expose 64MB of that memory to the PCI bus. This means that if you are running with > 64MB, all PCI buffers outside of the accessible range will be bounced using the routines in arch/arm/common/dmabounce.c. - + 3b. Limited outbound PCI window IXP4xx provides two methods of accessing PCI memory space: @@ -79,15 +79,15 @@ IXP4xx provides two methods of accessing PCI memory space: To access PCI via this space, we simply ioremap() the BAR into the kernel and we can use the standard read[bwl]/write[bwl] macros. This is the preffered method due to speed but it - limits the system to just 64MB of PCI memory. This can be + limits the system to just 64MB of PCI memory. This can be problamatic if using video cards and other memory-heavy devices. - -2) If > 64MB of memory space is required, the IXP4xx can be - configured to use indirect registers to access PCI This allows - for up to 128MB (0x48000000 to 0x4fffffff) of memory on the bus. - The disadvantage of this is that every PCI access requires - three local register accesses plus a spinlock, but in some - cases the performance hit is acceptable. In addition, you cannot + +2) If > 64MB of memory space is required, the IXP4xx can be + configured to use indirect registers to access PCI This allows + for up to 128MB (0x48000000 to 0x4fffffff) of memory on the bus. + The disadvantage of this is that every PCI access requires + three local register accesses plus a spinlock, but in some + cases the performance hit is acceptable. In addition, you cannot mmap() PCI devices in this case due to the indirect nature of the PCI window. @@ -96,14 +96,14 @@ you need more PCI memory, enable the IXP4XX_INDIRECT_PCI config option. 3c. GPIO as Interrupts -Currently the code only handles level-sensitive GPIO interrupts +Currently the code only handles level-sensitive GPIO interrupts 4. Supported platforms ADI Engineering Coyote Gateway Reference Platform http://www.adiengineering.com/productsCoyote.html - The ADI Coyote platform is reference design for those building + The ADI Coyote platform is reference design for those building small residential/office gateways. One NPE is connected to a 10/100 interface, one to 4-port 10/100 switch, and the third to and ADSL interface. In addition, it also supports to POTs interfaces connected @@ -119,9 +119,9 @@ http://www.gateworks.com/support/overview.php the expansion bus. Intel IXDP425 Development Platform -http://www.intel.com/design/network/products/npfamily/ixdpg425.htm +http://www.intel.com/design/network/products/npfamily/ixdpg425.htm - This is Intel's standard reference platform for the IXDP425 and is + This is Intel's standard reference platform for the IXDP425 and is also known as the Richfield board. It contains 4 PCI slots, 16MB of flash, two 10/100 ports and one ADSL port. @@ -161,11 +161,12 @@ The IXP4xx work has been funded by Intel Corp. and MontaVista Software, Inc. The following people have contributed patches/comments/etc: -Lennerty Buytenhek -Lutz Jaenicke -Justin Mayfield -Robert E. Ranslam -[I know I've forgotten others, please email me to be added] +- Lennerty Buytenhek +- Lutz Jaenicke +- Justin Mayfield +- Robert E. Ranslam + +[I know I've forgotten others, please email me to be added] ------------------------------------------------------------------------- diff --git a/Documentation/arm/kernel_mode_neon.txt b/Documentation/arm/kernel_mode_neon.rst index b9e060c5b61e..9bfb71a2a9b9 100644 --- a/Documentation/arm/kernel_mode_neon.txt +++ b/Documentation/arm/kernel_mode_neon.rst @@ -1,3 +1,4 @@ +================ Kernel mode NEON ================ @@ -86,6 +87,7 @@ instructions appearing in unexpected places if no special care is taken. Therefore, the recommended and only supported way of using NEON/VFP in the kernel is by adhering to the following rules: + * isolate the NEON code in a separate compilation unit and compile it with '-march=armv7-a -mfpu=neon -mfloat-abi=softfp'; * issue the calls to kernel_neon_begin(), kernel_neon_end() as well as the calls @@ -115,6 +117,7 @@ NEON intrinsics NEON intrinsics are also supported. However, as code using NEON intrinsics relies on the GCC header <arm_neon.h>, (which #includes <stdint.h>), you should observe the following in addition to the rules above: + * Compile the unit containing the NEON intrinsics with '-ffreestanding' so GCC uses its builtin version of <stdint.h> (this is a C99 header which the kernel does not supply); diff --git a/Documentation/arm/kernel_user_helpers.txt b/Documentation/arm/kernel_user_helpers.rst index 5673594717cf..eb6f3d916622 100644 --- a/Documentation/arm/kernel_user_helpers.txt +++ b/Documentation/arm/kernel_user_helpers.rst @@ -1,3 +1,4 @@ +============================ Kernel-provided User Helpers ============================ @@ -43,7 +44,7 @@ kuser_helper_version Location: 0xffff0ffc -Reference declaration: +Reference declaration:: extern int32_t __kuser_helper_version; @@ -53,17 +54,17 @@ Definition: running kernel. User space may read this to determine the availability of a particular helper. -Usage example: +Usage example:: -#define __kuser_helper_version (*(int32_t *)0xffff0ffc) + #define __kuser_helper_version (*(int32_t *)0xffff0ffc) -void check_kuser_version(void) -{ + void check_kuser_version(void) + { if (__kuser_helper_version < 2) { fprintf(stderr, "can't do atomic operations, kernel too old\n"); abort(); } -} + } Notes: @@ -77,7 +78,7 @@ kuser_get_tls Location: 0xffff0fe0 -Reference prototype: +Reference prototype:: void * __kuser_get_tls(void); @@ -97,16 +98,16 @@ Definition: Get the TLS value as previously set via the __ARM_NR_set_tls syscall. -Usage example: +Usage example:: -typedef void * (__kuser_get_tls_t)(void); -#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) + typedef void * (__kuser_get_tls_t)(void); + #define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) -void foo() -{ + void foo() + { void *tls = __kuser_get_tls(); printf("TLS = %p\n", tls); -} + } Notes: @@ -117,7 +118,7 @@ kuser_cmpxchg Location: 0xffff0fc0 -Reference prototype: +Reference prototype:: int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); @@ -139,18 +140,18 @@ Clobbered registers: Definition: - Atomically store newval in *ptr only if *ptr is equal to oldval. - Return zero if *ptr was changed or non-zero if no exchange happened. - The C flag is also set if *ptr was changed to allow for assembly + Atomically store newval in `*ptr` only if `*ptr` is equal to oldval. + Return zero if `*ptr` was changed or non-zero if no exchange happened. + The C flag is also set if `*ptr` was changed to allow for assembly optimization in the calling code. -Usage example: +Usage example:: -typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); -#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) + typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); + #define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) -int atomic_add(volatile int *ptr, int val) -{ + int atomic_add(volatile int *ptr, int val) + { int old, new; do { @@ -159,7 +160,7 @@ int atomic_add(volatile int *ptr, int val) } while(__kuser_cmpxchg(old, new, ptr)); return new; -} + } Notes: @@ -172,7 +173,7 @@ kuser_memory_barrier Location: 0xffff0fa0 -Reference prototype: +Reference prototype:: void __kuser_memory_barrier(void); @@ -193,10 +194,10 @@ Definition: Apply any needed memory barrier to preserve consistency with data modified manually and __kuser_cmpxchg usage. -Usage example: +Usage example:: -typedef void (__kuser_dmb_t)(void); -#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) + typedef void (__kuser_dmb_t)(void); + #define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) Notes: @@ -207,7 +208,7 @@ kuser_cmpxchg64 Location: 0xffff0f60 -Reference prototype: +Reference prototype:: int __kuser_cmpxchg64(const int64_t *oldval, const int64_t *newval, @@ -231,22 +232,22 @@ Clobbered registers: Definition: - Atomically store the 64-bit value pointed by *newval in *ptr only if *ptr - is equal to the 64-bit value pointed by *oldval. Return zero if *ptr was + Atomically store the 64-bit value pointed by `*newval` in `*ptr` only if `*ptr` + is equal to the 64-bit value pointed by `*oldval`. Return zero if `*ptr` was changed or non-zero if no exchange happened. - The C flag is also set if *ptr was changed to allow for assembly + The C flag is also set if `*ptr` was changed to allow for assembly optimization in the calling code. -Usage example: +Usage example:: -typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, - const int64_t *newval, - volatile int64_t *ptr); -#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) + typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); + #define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) -int64_t atomic_add64(volatile int64_t *ptr, int64_t val) -{ + int64_t atomic_add64(volatile int64_t *ptr, int64_t val) + { int64_t old, new; do { @@ -255,7 +256,7 @@ int64_t atomic_add64(volatile int64_t *ptr, int64_t val) } while(__kuser_cmpxchg64(&old, &new, ptr)); return new; -} + } Notes: diff --git a/Documentation/arm/keystone/knav-qmss.txt b/Documentation/arm/keystone/knav-qmss.rst index fcdb9fd5f53a..7f7638d80b42 100644 --- a/Documentation/arm/keystone/knav-qmss.txt +++ b/Documentation/arm/keystone/knav-qmss.rst @@ -1,4 +1,6 @@ -* Texas Instruments Keystone Navigator Queue Management SubSystem driver +====================================================================== +Texas Instruments Keystone Navigator Queue Management SubSystem driver +====================================================================== Driver source code path drivers/soc/ti/knav_qmss.c @@ -34,11 +36,13 @@ 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 diff --git a/Documentation/arm/keystone/Overview.txt b/Documentation/arm/keystone/overview.rst index 400c0c270d2e..cd90298c493c 100644 --- a/Documentation/arm/keystone/Overview.txt +++ b/Documentation/arm/keystone/overview.rst @@ -1,5 +1,6 @@ - TI Keystone Linux Overview - -------------------------- +========================== +TI Keystone Linux Overview +========================== Introduction ------------ @@ -9,47 +10,65 @@ for users to run Linux on Keystone based EVMs from Texas Instruments. Following SoCs & EVMs are currently supported:- ------------- K2HK SoC and EVM -------------------------------------------------- +K2HK SoC and EVM +================= a.k.a Keystone 2 Hawking/Kepler SoC TCI6636K2H & TCI6636K2K: See documentation at + http://www.ti.com/product/tci6638k2k http://www.ti.com/product/tci6638k2h EVM: -http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx + http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx ------------- K2E SoC and EVM --------------------------------------------------- +K2E SoC and EVM +=============== a.k.a Keystone 2 Edison SoC -K2E - 66AK2E05: See documentation at + +K2E - 66AK2E05: + +See documentation at + http://www.ti.com/product/66AK2E05/technicaldocuments EVM: -https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html + https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html ------------- K2L SoC and EVM --------------------------------------------------- +K2L SoC and EVM +=============== a.k.a Keystone 2 Lamarr SoC -K2L - TCI6630K2L: See documentation at + +K2L - TCI6630K2L: + +See documentation at http://www.ti.com/product/TCI6630K2L/technicaldocuments + EVM: -https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html + https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html Configuration ------------- All of the K2 SoCs/EVMs share a common defconfig, keystone_defconfig and same image is used to boot on individual EVMs. The platform configuration is -specified through DTS. Following are the DTS used:- - K2HK EVM : k2hk-evm.dts - K2E EVM : k2e-evm.dts - K2L EVM : k2l-evm.dts +specified through DTS. Following are the DTS used: + + K2HK EVM: + k2hk-evm.dts + K2E EVM: + k2e-evm.dts + K2L EVM: + k2l-evm.dts The device tree documentation for the keystone machines are located at + Documentation/devicetree/bindings/arm/keystone/keystone.txt Document Author --------------- Murali Karicheri <m-karicheri2@ti.com> + Copyright 2015 Texas Instruments diff --git a/Documentation/arm/marvel.rst b/Documentation/arm/marvel.rst new file mode 100644 index 000000000000..16ab2eb085b8 --- /dev/null +++ b/Documentation/arm/marvel.rst @@ -0,0 +1,488 @@ +================ +ARM Marvell SoCs +================ + +This document lists all the ARM Marvell SoCs that are currently +supported in mainline by the Linux kernel. As the Marvell families of +SoCs are large and complex, it is hard to understand where the support +for a particular SoC is available in the Linux kernel. This document +tries to help in understanding where those SoCs are supported, and to +match them with their corresponding public datasheet, when available. + +Orion family +------------ + + Flavors: + - 88F5082 + - 88F5181 + - 88F5181L + - 88F5182 + + - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf + - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf + - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf + - 88F5281 + + - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf + - 88F6183 + Core: + Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible + Linux kernel mach directory: + arch/arm/mach-orion5x + Linux kernel plat directory: + arch/arm/plat-orion + +Kirkwood family +--------------- + + Flavors: + - 88F6282 a.k.a Armada 300 + + - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - 88F6283 a.k.a Armada 310 + + - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - 88F6190 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6192 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6182 + - 88F6180 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6281 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + Homepage: + http://www.marvell.com/embedded-processors/kirkwood/ + Core: + Feroceon 88fr131 ARMv5 compatible + Linux kernel mach directory: + arch/arm/mach-mvebu + Linux kernel plat directory: + none + +Discovery family +---------------- + + Flavors: + - MV78100 + + - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - MV78200 + + - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - MV76100 + + Not supported by the Linux kernel. + + Core: + Feroceon 88fr571-vd ARMv5 compatible + + Linux kernel mach directory: + arch/arm/mach-mv78xx0 + Linux kernel plat directory: + arch/arm/plat-orion + +EBU Armada family +----------------- + + Armada 370 Flavors: + - 88F6710 + - 88F6707 + - 88F6W11 + + - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf + - Hardware Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf + + Core: + Sheeva ARMv7 compatible PJ4B + + Armada 375 Flavors: + - 88F6720 + + - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf + + Core: + ARM Cortex-A9 + + Armada 38x Flavors: + - 88F6810 Armada 380 + - 88F6820 Armada 385 + - 88F6828 Armada 388 + + - Product infos: http://www.marvell.com/embedded-processors/armada-38x/ + - Functional Spec: https://marvellcorp.wufoo.com/forms/marvell-armada-38x-functional-specifications/ + + Core: + ARM Cortex-A9 + + Armada 39x Flavors: + - 88F6920 Armada 390 + - 88F6928 Armada 398 + + - Product infos: http://www.marvell.com/embedded-processors/armada-39x/ + + Core: + ARM Cortex-A9 + + Armada XP Flavors: + - MV78230 + - MV78260 + - MV78460 + + NOTE: + not to be confused with the non-SMP 78xx0 SoCs + + Product Brief: + http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf + + Functional Spec: + http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf + + - Hardware Specs: + + - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF + - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF + - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF + + Core: + Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP + + Linux kernel mach directory: + arch/arm/mach-mvebu + Linux kernel plat directory: + none + +EBU Armada family ARMv8 +----------------------- + + Armada 3710/3720 Flavors: + - 88F3710 + - 88F3720 + + Core: + ARM Cortex A53 (ARMv8) + + Homepage: + http://www.marvell.com/embedded-processors/armada-3700/ + + Product Brief: + http://www.marvell.com/embedded-processors/assets/PB-88F3700-FNL.pdf + + Device tree files: + arch/arm64/boot/dts/marvell/armada-37* + + Armada 7K Flavors: + - 88F7020 (AP806 Dual + one CP110) + - 88F7040 (AP806 Quad + one CP110) + + Core: ARM Cortex A72 + + Homepage: + http://www.marvell.com/embedded-processors/armada-70xx/ + + Product Brief: + - http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf + - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf + + Device tree files: + arch/arm64/boot/dts/marvell/armada-70* + + Armada 8K Flavors: + - 88F8020 (AP806 Dual + two CP110) + - 88F8040 (AP806 Quad + two CP110) + Core: + ARM Cortex A72 + + Homepage: + http://www.marvell.com/embedded-processors/armada-80xx/ + + Product Brief: + - http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf + - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf + + Device tree files: + arch/arm64/boot/dts/marvell/armada-80* + +Avanta family +------------- + + Flavors: + - 88F6510 + - 88F6530P + - 88F6550 + - 88F6560 + + Homepage: + http://www.marvell.com/broadband/ + + Product Brief: + http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf + + No public datasheet available. + + Core: + ARMv5 compatible + + Linux kernel mach directory: + no code in mainline yet, planned for the future + Linux kernel plat directory: + no code in mainline yet, planned for the future + +Storage family +-------------- + + Armada SP: + - 88RC1580 + + Product infos: + http://www.marvell.com/storage/armada-sp/ + + Core: + Sheeva ARMv7 comatible Quad-core PJ4C + + (not supported in upstream Linux kernel) + +Dove family (application processor) +----------------------------------- + + Flavors: + - 88AP510 a.k.a Armada 510 + + Product Brief: + http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf + + Hardware Spec: + http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf + + Functional Spec: + http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf + + Homepage: + http://www.marvell.com/application-processors/armada-500/ + + Core: + ARMv7 compatible + + Directory: + - arch/arm/mach-mvebu (DT enabled platforms) + - arch/arm/mach-dove (non-DT enabled platforms) + +PXA 2xx/3xx/93x/95x family +-------------------------- + + Flavors: + - PXA21x, PXA25x, PXA26x + - Application processor only + - Core: ARMv5 XScale1 core + - PXA270, PXA271, PXA272 + - Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf + - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf + - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf + - Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf + - Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf + - Application processor only + - Core: ARMv5 XScale2 core + - PXA300, PXA310, PXA320 + - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf + - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf + - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf + - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf + - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip + - Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf + - Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip + - Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf + - Application processor only + - Core: ARMv5 XScale3 core + - PXA930, PXA935 + - Application processor with Communication processor + - Core: ARMv5 XScale3 core + - PXA955 + - Application processor with Communication processor + - Core: ARMv7 compatible Sheeva PJ4 core + + Comments: + + * This line of SoCs originates from the XScale family developed by + Intel and acquired by Marvell in ~2006. The PXA21x, PXA25x, + PXA26x, PXA27x, PXA3xx and PXA93x were developed by Intel, while + the later PXA95x were developed by Marvell. + + * Due to their XScale origin, these SoCs have virtually nothing in + common with the other (Kirkwood, Dove, etc.) families of Marvell + SoCs, except with the MMP/MMP2 family of SoCs. + + Linux kernel mach directory: + arch/arm/mach-pxa + Linux kernel plat directory: + arch/arm/plat-pxa + +MMP/MMP2/MMP3 family (communication processor) +---------------------------------------------- + + Flavors: + - PXA168, a.k.a Armada 168 + - Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp + - Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf + - Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf + - Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf + - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf + - Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf + - App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf + - Application processor only + - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) + - PXA910/PXA920 + - Homepage : http://www.marvell.com/communication-processors/pxa910/ + - Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf + - Application processor with Communication processor + - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) + - PXA688, a.k.a. MMP2, a.k.a Armada 610 + - Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf + - Application processor only + - Core: ARMv7 compatible Sheeva PJ4 88sv581x core + - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream) + - Product Brief : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf + - Application processor only + - Core: Dual-core ARMv7 compatible Sheeva PJ4C core + - PXA960/PXA968/PXA978 (Linux support not upstream) + - Application processor with Communication Processor + - Core: ARMv7 compatible Sheeva PJ4 core + - PXA986/PXA988 (Linux support not upstream) + - Application processor with Communication Processor + - Core: Dual-core ARMv7 compatible Sheeva PJ4B-MP core + - PXA1088/PXA1920 (Linux support not upstream) + - Application processor with Communication Processor + - Core: quad-core ARMv7 Cortex-A7 + - PXA1908/PXA1928/PXA1936 + - Application processor with Communication Processor + - Core: multi-core ARMv8 Cortex-A53 + + Comments: + + * This line of SoCs originates from the XScale family developed by + Intel and acquired by Marvell in ~2006. All the processors of + this MMP/MMP2 family were developed by Marvell. + + * Due to their XScale origin, these SoCs have virtually nothing in + common with the other (Kirkwood, Dove, etc.) families of Marvell + SoCs, except with the PXA family of SoCs listed above. + + Linux kernel mach directory: + arch/arm/mach-mmp + Linux kernel plat directory: + arch/arm/plat-pxa + +Berlin family (Multimedia Solutions) +------------------------------------- + + - Flavors: + - 88DE3010, Armada 1000 (no Linux support) + - Core: Marvell PJ1 (ARMv5TE), Dual-core + - Product Brief: http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf + - 88DE3005, Armada 1500 Mini + - Design name: BG2CD + - Core: ARM Cortex-A9, PL310 L2CC + - 88DE3006, Armada 1500 Mini Plus + - Design name: BG2CDP + - Core: Dual Core ARM Cortex-A7 + - 88DE3100, Armada 1500 + - Design name: BG2 + - Core: Marvell PJ4B-MP (ARMv7), Tauros3 L2CC + - 88DE3114, Armada 1500 Pro + - Design name: BG2Q + - Core: Quad Core ARM Cortex-A9, PL310 L2CC + - 88DE3214, Armada 1500 Pro 4K + - Design name: BG3 + - Core: ARM Cortex-A15, CA15 integrated L2CC + - 88DE3218, ARMADA 1500 Ultra + - Core: ARM Cortex-A53 + + Homepage: https://www.synaptics.com/products/multimedia-solutions + Directory: arch/arm/mach-berlin + + Comments: + + * This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs + with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, ETH, ...). + + * The Berlin family was acquired by Synaptics from Marvell in 2017. + +CPU Cores +--------- + +The XScale cores were designed by Intel, and shipped by Marvell in the older +PXA processors. Feroceon is a Marvell designed core that developed in-house, +and that evolved into Sheeva. The XScale and Feroceon cores were phased out +over time and replaced with Sheeva cores in later products, which subsequently +got replaced with licensed ARM Cortex-A cores. + + XScale 1 + CPUID 0x69052xxx + ARMv5, iWMMXt + XScale 2 + CPUID 0x69054xxx + ARMv5, iWMMXt + XScale 3 + CPUID 0x69056xxx or 0x69056xxx + ARMv5, iWMMXt + Feroceon-1850 88fr331 "Mohawk" + CPUID 0x5615331x or 0x41xx926x + ARMv5TE, single issue + Feroceon-2850 88fr531-vd "Jolteon" + CPUID 0x5605531x or 0x41xx926x + ARMv5TE, VFP, dual-issue + Feroceon 88fr571-vd "Jolteon" + CPUID 0x5615571x + ARMv5TE, VFP, dual-issue + Feroceon 88fr131 "Mohawk-D" + CPUID 0x5625131x + ARMv5TE, single-issue in-order + Sheeva PJ1 88sv331 "Mohawk" + CPUID 0x561584xx + ARMv5, single-issue iWMMXt v2 + Sheeva PJ4 88sv581x "Flareon" + CPUID 0x560f581x + ARMv7, idivt, optional iWMMXt v2 + Sheeva PJ4B 88sv581x + CPUID 0x561f581x + ARMv7, idivt, optional iWMMXt v2 + Sheeva PJ4B-MP / PJ4C + CPUID 0x562f584x + ARMv7, idivt/idiva, LPAE, optional iWMMXt v2 and/or NEON + +Long-term plans +--------------- + + * Unify the mach-dove/, mach-mv78xx0/, mach-orion5x/ into the + mach-mvebu/ to support all SoCs from the Marvell EBU (Engineering + Business Unit) in a single mach-<foo> directory. The plat-orion/ + would therefore disappear. + + * Unify the mach-mmp/ and mach-pxa/ into the same mach-pxa + directory. The plat-pxa/ would therefore disappear. + +Credits +------- + +- Maen Suleiman <maen@marvell.com> +- Lior Amsalem <alior@marvell.com> +- Thomas Petazzoni <thomas.petazzoni@free-electrons.com> +- Andrew Lunn <andrew@lunn.ch> +- Nicolas Pitre <nico@fluxnic.net> +- Eric Miao <eric.y.miao@gmail.com> diff --git a/Documentation/arm/mem_alignment b/Documentation/arm/mem_alignment.rst index e110e2781039..aa22893b62bc 100644 --- a/Documentation/arm/mem_alignment +++ b/Documentation/arm/mem_alignment.rst @@ -1,3 +1,7 @@ +================ +Memory alignment +================ + Too many problems popped up because of unnoticed misaligned memory access in kernel code lately. Therefore the alignment fixup is now unconditionally configured in for SA11x0 based targets. According to Alan Cox, this is a @@ -26,9 +30,9 @@ space, and might cause programs to fail unexpectedly. To change the alignment trap behavior, simply echo a number into /proc/cpu/alignment. The number is made up from various bits: +=== ======================================================== bit behavior when set ---- ----------------- - +=== ======================================================== 0 A user process performing an unaligned memory access will cause the kernel to print a message indicating process name, pid, pc, instruction, address, and the @@ -41,12 +45,13 @@ bit behavior when set 2 The kernel will send a SIGBUS signal to the user process performing the unaligned access. +=== ======================================================== Note that not all combinations are supported - only values 0 through 5. (6 and 7 don't make sense). For example, the following will turn on the warnings, but without -fixing up or sending SIGBUS signals: +fixing up or sending SIGBUS signals:: echo 1 > /proc/cpu/alignment diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.rst index 546a39048eb0..0521b4ce5c96 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.rst @@ -1,6 +1,9 @@ - Kernel Memory Layout on ARM Linux +================================= +Kernel Memory Layout on ARM Linux +================================= Russell King <rmk@arm.linux.org.uk> + November 17, 2005 (2.6.15) This document describes the virtual memory layout which the Linux @@ -15,8 +18,9 @@ As the ARM architecture matures, it becomes necessary to reserve certain regions of VM space for use for new facilities; therefore this document may reserve more VM space over time. +=============== =============== =============================================== Start End Use --------------------------------------------------------------------------- +=============== =============== =============================================== ffff8000 ffffffff copy_user_page / clear_user_page use. For SA11xx and Xscale, this is used to setup a minicache mapping. @@ -77,6 +81,7 @@ MODULES_VADDR MODULES_END-1 Kernel module space place their vector page here. NULL pointer dereferences by both the kernel and user space are also caught via this mapping. +=============== =============== =============================================== Please note that mappings which collide with the above areas may result in a non-bootable kernel, or may cause the kernel to (eventually) panic diff --git a/Documentation/arm/Microchip/README b/Documentation/arm/microchip.rst index a366f37d38f1..c9a44c98e868 100644 --- a/Documentation/arm/Microchip/README +++ b/Documentation/arm/microchip.rst @@ -1,3 +1,4 @@ +============================= ARM Microchip SoCs (aka AT91) ============================= @@ -22,32 +23,46 @@ the Microchip website: http://www.microchip.com. Flavors: * ARM 920 based SoC - at91rm9200 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-1768-32-bit-ARM920T-Embedded-Microprocessor-AT91RM9200_Datasheet.pdf * ARM 926 based SoCs - at91sam9260 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6221-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9260_Datasheet.pdf - at91sam9xe - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf - at91sam9261 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6062-ARM926EJ-S-Microprocessor-SAM9261_Datasheet.pdf - at91sam9263 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6249-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9263_Datasheet.pdf - at91sam9rl - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/doc6289.pdf - at91sam9g20 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001516A.pdf - at91sam9g45 family @@ -55,7 +70,9 @@ the Microchip website: http://www.microchip.com. - at91sam9g46 - at91sam9m10 - at91sam9m11 (device superset) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf - at91sam9x5 family (aka "The 5 series") @@ -64,33 +81,44 @@ the Microchip website: http://www.microchip.com. - at91sam9g35 - at91sam9x25 - at91sam9x35 - + Datasheet (can be considered as covering the whole family) + + * Datasheet (can be considered as covering the whole family) + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11055-32-bit-ARM926EJ-S-Microcontroller-SAM9X35_Datasheet.pdf - at91sam9n12 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001517A.pdf * ARM Cortex-A5 based SoCs - sama5d3 family + - sama5d31 - sama5d33 - sama5d34 - sama5d35 - sama5d36 (device superset) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11121-32-bit-Cortex-A5-Microcontroller-SAMA5D3_Datasheet.pdf * ARM Cortex-A5 + NEON based SoCs - sama5d4 family + - sama5d41 - sama5d42 - sama5d43 - sama5d44 (device superset) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/60001525A.pdf - sama5d2 family + - sama5d21 - sama5d22 - sama5d23 @@ -98,11 +126,14 @@ the Microchip website: http://www.microchip.com. - sama5d26 - sama5d27 (device superset) - sama5d28 (device superset + environmental monitors) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001476B.pdf * ARM Cortex-M7 MCUs - sams70 family + - sams70j19 - sams70j20 - sams70j21 @@ -114,6 +145,7 @@ the Microchip website: http://www.microchip.com. - sams70q21 - samv70 family + - samv70j19 - samv70j20 - samv70n19 @@ -122,6 +154,7 @@ the Microchip website: http://www.microchip.com. - samv70q20 - samv71 family + - samv71j19 - samv71j20 - samv71j21 @@ -132,7 +165,8 @@ the Microchip website: http://www.microchip.com. - samv71q20 - samv71q21 - + Datasheet + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/60001527A.pdf @@ -157,6 +191,7 @@ definition of a "Stable" binding/ABI. This statement will be removed by AT91 MAINTAINERS when appropriate. Naming conventions and best practice: + - SoCs Device Tree Source Include files are named after the official name of the product (at91sam9g20.dtsi or sama5d33.dtsi for instance). - Device Tree Source Include files (.dtsi) are used to collect common nodes that can be diff --git a/Documentation/arm/netwinder.rst b/Documentation/arm/netwinder.rst new file mode 100644 index 000000000000..8eab66caa2ac --- /dev/null +++ b/Documentation/arm/netwinder.rst @@ -0,0 +1,85 @@ +================================ +NetWinder specific documentation +================================ + +The NetWinder is a small low-power computer, primarily designed +to run Linux. It is based around the StrongARM RISC processor, +DC21285 PCI bridge, with PC-type hardware glued around it. + +Port usage +========== + +======= ====== =============================== +Min Max Description +======= ====== =============================== +0x0000 0x000f DMA1 +0x0020 0x0021 PIC1 +0x0060 0x006f Keyboard +0x0070 0x007f RTC +0x0080 0x0087 DMA1 +0x0088 0x008f DMA2 +0x00a0 0x00a3 PIC2 +0x00c0 0x00df DMA2 +0x0180 0x0187 IRDA +0x01f0 0x01f6 ide0 +0x0201 Game port +0x0203 RWA010 configuration read +0x0220 ? SoundBlaster +0x0250 ? WaveArtist +0x0279 RWA010 configuration index +0x02f8 0x02ff Serial ttyS1 +0x0300 0x031f Ether10 +0x0338 GPIO1 +0x033a GPIO2 +0x0370 0x0371 W83977F configuration registers +0x0388 ? AdLib +0x03c0 0x03df VGA +0x03f6 ide0 +0x03f8 0x03ff Serial ttyS0 +0x0400 0x0408 DC21143 +0x0480 0x0487 DMA1 +0x0488 0x048f DMA2 +0x0a79 RWA010 configuration write +0xe800 0xe80f ide0/ide1 BM DMA +======= ====== =============================== + + +Interrupt usage +=============== + +======= ======= ======================== +IRQ type Description +======= ======= ======================== + 0 ISA 100Hz timer + 1 ISA Keyboard + 2 ISA cascade + 3 ISA Serial ttyS1 + 4 ISA Serial ttyS0 + 5 ISA PS/2 mouse + 6 ISA IRDA + 7 ISA Printer + 8 ISA RTC alarm + 9 ISA +10 ISA GP10 (Orange reset button) +11 ISA +12 ISA WaveArtist +13 ISA +14 ISA hda1 +15 ISA +======= ======= ======================== + +DMA usage +========= + +======= ======= =========== +DMA type Description +======= ======= =========== + 0 ISA IRDA + 1 ISA + 2 ISA cascade + 3 ISA WaveArtist + 4 ISA + 5 ISA + 6 ISA + 7 ISA WaveArtist +======= ======= =========== diff --git a/Documentation/arm/nwfpe/index.rst b/Documentation/arm/nwfpe/index.rst new file mode 100644 index 000000000000..3c4d2f9aa10e --- /dev/null +++ b/Documentation/arm/nwfpe/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +NetWinder's floating point emulator +=================================== + +.. toctree:: + :maxdepth: 1 + + nwfpe + netwinder-fpe + notes + todo diff --git a/Documentation/arm/nwfpe/README.FPE b/Documentation/arm/nwfpe/netwinder-fpe.rst index 26f5d7bb9a41..cbb320960fc4 100644 --- a/Documentation/arm/nwfpe/README.FPE +++ b/Documentation/arm/nwfpe/netwinder-fpe.rst @@ -1,12 +1,18 @@ +============= +Current State +============= + The following describes the current state of the NetWinder's floating point emulator. In the following nomenclature is used to describe the floating point instructions. It follows the conventions in the ARM manual. -<S|D|E> = <single|double|extended>, no default -{P|M|Z} = {round to +infinity,round to -infinity,round to zero}, - default = round to nearest +:: + + <S|D|E> = <single|double|extended>, no default + {P|M|Z} = {round to +infinity,round to -infinity,round to zero}, + default = round to nearest Note: items enclosed in {} are optional. @@ -32,10 +38,10 @@ Form 2 syntax: <LFM|SFM>{cond}<FD,EA> Fd, <count>, [Rn]{!} These instructions are fully implemented. They store/load three words -for each floating point register into the memory location given in the +for each floating point register into the memory location given in the instruction. The format in memory is unlikely to be compatible with other implementations, in particular the actual hardware. Specific -mention of this is made in the ARM manuals. +mention of this is made in the ARM manuals. Floating Point Coprocessor Register Transfer Instructions (CPRT) ---------------------------------------------------------------- @@ -123,7 +129,7 @@ RPW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - reverse power POL{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - polar angle (arctan2) LOG{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base 10 -LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e +LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e EXP{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - exponent SIN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - sine COS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - cosine @@ -134,7 +140,7 @@ ATN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arctangent These are not implemented. They are not currently issued by the compiler, and are handled by routines in libc. These are not implemented by the FPA11 -hardware, but are handled by the floating point support code. They should +hardware, but are handled by the floating point support code. They should be implemented in future versions. Signalling: @@ -147,10 +153,10 @@ current_set[0] correctly. The kernel provided with this distribution (vmlinux-nwfpe-0.93) contains a fix for this problem and also incorporates the current version of the emulator directly. It is possible to run with no floating point module -loaded with this kernel. It is provided as a demonstration of the +loaded with this kernel. It is provided as a demonstration of the technology and for those who want to do floating point work that depends on signals. It is not strictly necessary to use the module. -A module (either the one provided by Russell King, or the one in this +A module (either the one provided by Russell King, or the one in this distribution) can be loaded to replace the functionality of the emulator built into the kernel. diff --git a/Documentation/arm/nwfpe/NOTES b/Documentation/arm/nwfpe/notes.rst index 40577b5a49d3..102e55af8439 100644 --- a/Documentation/arm/nwfpe/NOTES +++ b/Documentation/arm/nwfpe/notes.rst @@ -1,3 +1,6 @@ +Notes +===== + There seems to be a problem with exp(double) and our emulator. I haven't been able to track it down yet. This does not occur with the emulator supplied by Russell King. diff --git a/Documentation/arm/nwfpe/README b/Documentation/arm/nwfpe/nwfpe.rst index 771871de0c8b..35cd90dacbff 100644 --- a/Documentation/arm/nwfpe/README +++ b/Documentation/arm/nwfpe/nwfpe.rst @@ -1,4 +1,7 @@ -This directory contains the version 0.92 test release of the NetWinder +Introduction +============ + +This directory contains the version 0.92 test release of the NetWinder Floating Point Emulator. The majority of the code was written by me, Scott Bambrough It is @@ -31,7 +34,7 @@ SoftFloat to the ARM was done by Phil Blundell, based on an earlier port of SoftFloat version 1 by Neil Carson for NetBSD/arm32. The file README.FPE contains a description of what has been implemented -so far in the emulator. The file TODO contains a information on what +so far in the emulator. The file TODO contains a information on what remains to be done, and other ideas for the emulator. Bug reports, comments, suggestions should be directed to me at @@ -48,10 +51,11 @@ Legal Notices The NetWinder Floating Point Emulator is free software. Everything Rebel.com has written is provided under the GNU GPL. See the file COPYING for copying -conditions. Excluded from the above is the SoftFloat code. John Hauser's +conditions. Excluded from the above is the SoftFloat code. John Hauser's legal notice for SoftFloat is included below. ------------------------------------------------------------------------------- + SoftFloat Legal Notice SoftFloat was written by John R. Hauser. This work was made possible in diff --git a/Documentation/arm/nwfpe/TODO b/Documentation/arm/nwfpe/todo.rst index 8027061b60eb..393f11b14540 100644 --- a/Documentation/arm/nwfpe/TODO +++ b/Documentation/arm/nwfpe/todo.rst @@ -1,39 +1,42 @@ TODO LIST ---------- +========= -POW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - power -RPW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - reverse power -POL{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - polar angle (arctan2) +:: -LOG{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base 10 -LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e -EXP{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - exponent -SIN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - sine -COS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - cosine -TAN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - tangent -ASN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arcsine -ACS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arccosine -ATN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arctangent + POW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - power + RPW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - reverse power + POL{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - polar angle (arctan2) + + LOG{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base 10 + LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e + EXP{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - exponent + SIN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - sine + COS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - cosine + TAN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - tangent + ASN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arcsine + ACS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arccosine + ATN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arctangent These are not implemented. They are not currently issued by the compiler, and are handled by routines in libc. These are not implemented by the FPA11 -hardware, but are handled by the floating point support code. They should +hardware, but are handled by the floating point support code. They should be implemented in future versions. There are a couple of ways to approach the implementation of these. One -method would be to use accurate table methods for these routines. I have +method would be to use accurate table methods for these routines. I have a couple of papers by S. Gal from IBM's research labs in Haifa, Israel that seem to promise extreme accuracy (in the order of 99.8%) and reasonable speed. These methods are used in GLIBC for some of the transcendental functions. Another approach, which I know little about is CORDIC. This stands for -Coordinate Rotation Digital Computer, and is a method of computing +Coordinate Rotation Digital Computer, and is a method of computing transcendental functions using mostly shifts and adds and a few multiplications and divisions. The ARM excels at shifts and adds, -so such a method could be promising, but requires more research to +so such a method could be promising, but requires more research to determine if it is feasible. Rounding Methods +---------------- The IEEE standard defines 4 rounding modes. Round to nearest is the default, but rounding to + or - infinity or round to zero are also allowed. @@ -42,8 +45,8 @@ in a control register. Not so with the ARM FPA11 architecture. To change the rounding mode one must specify it with each instruction. This has made porting some benchmarks difficult. It is possible to -introduce such a capability into the emulator. The FPCR contains -bits describing the rounding mode. The emulator could be altered to +introduce such a capability into the emulator. The FPCR contains +bits describing the rounding mode. The emulator could be altered to examine a flag, which if set forced it to ignore the rounding mode in the instruction, and use the mode specified in the bits in the FPCR. @@ -52,7 +55,8 @@ in the FPCR. This requires a kernel call in ArmLinux, as WFC/RFC are supervisor only instructions. If anyone has any ideas or comments I would like to hear them. -[NOTE: pulled out from some docs on ARM floating point, specifically +NOTE: + pulled out from some docs on ARM floating point, specifically for the Acorn FPE, but not limited to it: The floating point control register (FPCR) may only be present in some @@ -64,4 +68,5 @@ would like to hear them. Hence, the answer is yes, you could do this, but then you will run a high risk of becoming isolated if and when hardware FP emulation comes out - -- Russell]. + + -- Russell. diff --git a/Documentation/arm/OMAP/DSS b/Documentation/arm/omap/dss.rst index 4484e021290e..a40c4d9c717a 100644 --- a/Documentation/arm/OMAP/DSS +++ b/Documentation/arm/omap/dss.rst @@ -1,5 +1,6 @@ +========================= OMAP2/3 Display Subsystem -------------------------- +========================= This is an almost total rewrite of the OMAP FB driver in drivers/video/omap (let's call it DSS1). The main differences between DSS1 and DSS2 are DSI, @@ -190,6 +191,8 @@ trans_key_value transparency color key (RGB24) default_color default background color (RGB24) /sys/devices/platform/omapdss/display? directory: + +=============== ============================================================= ctrl_name Controller name mirror 0=off, 1=on update_mode 0=off, 1=auto, 2=manual @@ -202,6 +205,7 @@ timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw) panel_name tear_elim Tearing elimination 0=off, 1=on output_type Output type (video encoder only): "composite" or "svideo" +=============== ============================================================= There are also some debugfs files at <debugfs>/omapdss/ which show information about clocks and registers. @@ -209,22 +213,22 @@ about clocks and registers. Examples -------- -The following definitions have been made for the examples below: +The following definitions have been made for the examples below:: -ovl0=/sys/devices/platform/omapdss/overlay0 -ovl1=/sys/devices/platform/omapdss/overlay1 -ovl2=/sys/devices/platform/omapdss/overlay2 + ovl0=/sys/devices/platform/omapdss/overlay0 + ovl1=/sys/devices/platform/omapdss/overlay1 + ovl2=/sys/devices/platform/omapdss/overlay2 -mgr0=/sys/devices/platform/omapdss/manager0 -mgr1=/sys/devices/platform/omapdss/manager1 + mgr0=/sys/devices/platform/omapdss/manager0 + mgr1=/sys/devices/platform/omapdss/manager1 -lcd=/sys/devices/platform/omapdss/display0 -dvi=/sys/devices/platform/omapdss/display1 -tv=/sys/devices/platform/omapdss/display2 + lcd=/sys/devices/platform/omapdss/display0 + dvi=/sys/devices/platform/omapdss/display1 + tv=/sys/devices/platform/omapdss/display2 -fb0=/sys/class/graphics/fb0 -fb1=/sys/class/graphics/fb1 -fb2=/sys/class/graphics/fb2 + fb0=/sys/class/graphics/fb0 + fb1=/sys/class/graphics/fb1 + fb2=/sys/class/graphics/fb2 Default setup on OMAP3 SDP -------------------------- @@ -232,55 +236,59 @@ Default setup on OMAP3 SDP Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI and TV-out are not in use. The columns from left to right are: framebuffers, overlays, overlay managers, displays. Framebuffers are -handled by omapfb, and the rest by the DSS. +handled by omapfb, and the rest by the DSS:: -FB0 --- GFX -\ DVI -FB1 --- VID1 --+- LCD ---- LCD -FB2 --- VID2 -/ TV ----- TV + FB0 --- GFX -\ DVI + FB1 --- VID1 --+- LCD ---- LCD + FB2 --- VID2 -/ TV ----- TV Example: Switch from LCD to DVI ----------------------- +------------------------------- + +:: -w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1` -h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1` + w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1` + h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1` -echo "0" > $lcd/enabled -echo "" > $mgr0/display -fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h -# at this point you have to switch the dvi/lcd dip-switch from the omap board -echo "dvi" > $mgr0/display -echo "1" > $dvi/enabled + echo "0" > $lcd/enabled + echo "" > $mgr0/display + fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h + # at this point you have to switch the dvi/lcd dip-switch from the omap board + echo "dvi" > $mgr0/display + echo "1" > $dvi/enabled -After this the configuration looks like: +After this the configuration looks like::: -FB0 --- GFX -\ -- DVI -FB1 --- VID1 --+- LCD -/ LCD -FB2 --- VID2 -/ TV ----- TV + FB0 --- GFX -\ -- DVI + FB1 --- VID1 --+- LCD -/ LCD + FB2 --- VID2 -/ TV ----- TV Example: Clone GFX overlay to LCD and TV -------------------------------- +---------------------------------------- + +:: -w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1` -h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1` + w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1` + h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1` -echo "0" > $ovl0/enabled -echo "0" > $ovl1/enabled + echo "0" > $ovl0/enabled + echo "0" > $ovl1/enabled -echo "" > $fb1/overlays -echo "0,1" > $fb0/overlays + echo "" > $fb1/overlays + echo "0,1" > $fb0/overlays -echo "$w,$h" > $ovl1/output_size -echo "tv" > $ovl1/manager + echo "$w,$h" > $ovl1/output_size + echo "tv" > $ovl1/manager -echo "1" > $ovl0/enabled -echo "1" > $ovl1/enabled + echo "1" > $ovl0/enabled + echo "1" > $ovl1/enabled -echo "1" > $tv/enabled + echo "1" > $tv/enabled -After this the configuration looks like (only relevant parts shown): +After this the configuration looks like (only relevant parts shown):: -FB0 +-- GFX ---- LCD ---- LCD - \- VID1 ---- TV ---- TV + FB0 +-- GFX ---- LCD ---- LCD + \- VID1 ---- TV ---- TV Misc notes ---------- @@ -351,12 +359,14 @@ TODO DSS locking Error checking + - Lots of checks are missing or implemented just as BUG() System DMA update for DSI + - Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how to skip the empty byte?) OMAP1 support -- Not sure if needed +- Not sure if needed diff --git a/Documentation/arm/omap/index.rst b/Documentation/arm/omap/index.rst new file mode 100644 index 000000000000..8b365b212e49 --- /dev/null +++ b/Documentation/arm/omap/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +TI OMAP +======= + +.. toctree:: + :maxdepth: 1 + + omap + omap_pm + dss diff --git a/Documentation/arm/OMAP/README b/Documentation/arm/omap/omap.rst index 90c6c57d61e8..f440c0f4613f 100644 --- a/Documentation/arm/OMAP/README +++ b/Documentation/arm/omap/omap.rst @@ -1,7 +1,13 @@ +============ +OMAP history +============ + This file contains documentation for running mainline kernel on omaps. +====== ====================================================== KERNEL NEW DEPENDENCIES +====== ====================================================== v4.3+ Update is needed for custom .config files to make sure CONFIG_REGULATOR_PBIAS is enabled for MMC1 to work properly. @@ -9,3 +15,4 @@ v4.3+ Update is needed for custom .config files to make sure v4.18+ Update is needed for custom .config files to make sure CONFIG_MMC_SDHCI_OMAP is enabled for all MMC instances to work in DRA7 and K2G based boards. +====== ====================================================== diff --git a/Documentation/arm/OMAP/omap_pm b/Documentation/arm/omap/omap_pm.rst index 4ae915a9f899..a335e4c8ce2c 100644 --- a/Documentation/arm/OMAP/omap_pm +++ b/Documentation/arm/omap/omap_pm.rst @@ -1,4 +1,4 @@ - +===================== The OMAP PM interface ===================== @@ -31,19 +31,24 @@ Drivers need to express PM parameters which: This document proposes the OMAP PM interface, including the following five power management functions for driver code: -1. Set the maximum MPU wakeup latency: +1. Set the maximum MPU wakeup latency:: + (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t) -2. Set the maximum device wakeup latency: +2. Set the maximum device wakeup latency:: + (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t) -3. Set the maximum system DMA transfer start latency (CORE pwrdm): +3. Set the maximum system DMA transfer start latency (CORE pwrdm):: + (*pdata->set_max_sdma_lat)(struct device *dev, long t) -4. Set the minimum bus throughput needed by a device: +4. Set the minimum bus throughput needed by a device:: + (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r) -5. Return the number of times the device has lost context +5. Return the number of times the device has lost context:: + (*pdata->get_dev_context_loss_count)(struct device *dev) @@ -65,12 +70,13 @@ Driver usage of the OMAP PM functions As the 'pdata' in the above examples indicates, these functions are exposed to drivers through function pointers in driver .platform_data -structures. The function pointers are initialized by the board-*.c +structures. The function pointers are initialized by the `board-*.c` files to point to the corresponding OMAP PM functions: -.set_max_dev_wakeup_lat will point to -omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do -not support these functions should leave these function pointers set -to NULL. Drivers should use the following idiom: + +- set_max_dev_wakeup_lat will point to + omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do + not support these functions should leave these function pointers set + to NULL. Drivers should use the following idiom:: if (pdata->set_max_dev_wakeup_lat) (*pdata->set_max_dev_wakeup_lat)(dev, t); @@ -81,7 +87,7 @@ becomes accessible. To accomplish this, driver writers should use the set_max_mpu_wakeup_lat() function to constrain the MPU wakeup latency, and the set_max_dev_wakeup_lat() function to constrain the device wakeup latency (from clk_enable() to accessibility). For -example, +example:: /* Limit MPU wakeup latency */ if (pdata->set_max_mpu_wakeup_lat) @@ -116,17 +122,17 @@ specialized cases to convert that input information (OPPs/MPU frequency) into the form that the underlying power management implementation needs: -6. (*pdata->dsp_get_opp_table)(void) +6. `(*pdata->dsp_get_opp_table)(void)` -7. (*pdata->dsp_set_min_opp)(u8 opp_id) +7. `(*pdata->dsp_set_min_opp)(u8 opp_id)` -8. (*pdata->dsp_get_opp)(void) +8. `(*pdata->dsp_get_opp)(void)` -9. (*pdata->cpu_get_freq_table)(void) +9. `(*pdata->cpu_get_freq_table)(void)` -10. (*pdata->cpu_set_freq)(unsigned long f) +10. `(*pdata->cpu_set_freq)(unsigned long f)` -11. (*pdata->cpu_get_freq)(void) +11. `(*pdata->cpu_get_freq)(void)` Customizing OPP for platform ============================ @@ -134,12 +140,15 @@ Defining CONFIG_PM should enable OPP layer for the silicon and the registration of OPP table should take place automatically. However, in special cases, the default OPP table may need to be tweaked, for e.g.: + * enable default OPPs which are disabled by default, but which could be enabled on a platform * Disable an unsupported OPP on the platform * Define and add a custom opp table entry -in these cases, the board file needs to do additional steps as follows: -arch/arm/mach-omapx/board-xyz.c + in these cases, the board file needs to do additional steps as follows: + +arch/arm/mach-omapx/board-xyz.c:: + #include "pm.h" .... static void __init omap_xyz_init_irq(void) @@ -150,5 +159,7 @@ arch/arm/mach-omapx/board-xyz.c /* Do customization to the defaults */ .... } -NOTE: omapx_opp_init will be omap3_opp_init or as required -based on the omap family. + +NOTE: + omapx_opp_init will be omap3_opp_init or as required + based on the omap family. diff --git a/Documentation/arm/Porting b/Documentation/arm/porting.rst index a492233931b9..bd21958bdb2d 100644 --- a/Documentation/arm/Porting +++ b/Documentation/arm/porting.rst @@ -1,3 +1,7 @@ +======= +Porting +======= + Taken from list archive at http://lists.arm.linux.org.uk/pipermail/linux-arm-kernel/2001-July/004064.html Initial definitions @@ -89,8 +93,7 @@ DATAADDR Virtual address for the kernel data segment. Must not be defined when using the decompressor. -VMALLOC_START -VMALLOC_END +VMALLOC_START / VMALLOC_END Virtual addresses bounding the vmalloc() area. There must not be any static mappings in this area; vmalloc will overwrite them. The addresses must also be in the kernel segment (see above). @@ -107,13 +110,13 @@ Architecture Specific Macros ---------------------------- BOOT_MEM(pram,pio,vio) - `pram' specifies the physical start address of RAM. Must always + `pram` specifies the physical start address of RAM. Must always be present, and should be the same as PHYS_OFFSET. - `pio' is the physical address of an 8MB region containing IO for + `pio` is the physical address of an 8MB region containing IO for use with the debugging macros in arch/arm/kernel/debug-armv.S. - `vio' is the virtual address of the 8MB debugging region. + `vio` is the virtual address of the 8MB debugging region. It is expected that the debugging region will be re-initialised by the architecture specific code later in the code (via the @@ -132,4 +135,3 @@ MAPIO(func) INITIRQ(func) Machine specific function to initialise interrupts. - diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.rst index 0b7cab978c02..ac34e5d7ee44 100644 --- a/Documentation/arm/pxa/mfp.txt +++ b/Documentation/arm/pxa/mfp.rst @@ -1,4 +1,6 @@ - MFP Configuration for PXA2xx/PXA3xx Processors +============================================== +MFP Configuration for PXA2xx/PXA3xx Processors +============================================== Eric Miao <eric.miao@marvell.com> @@ -6,15 +8,15 @@ MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and later PXA series processors. This document describes the existing MFP API, and how board/platform driver authors could make use of it. - Basic Concept -=============== +Basic Concept +============= Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP mechanism is introduced from PXA3xx to completely move the pin-mux functions out of the GPIO controller. In addition to pin-mux configurations, the MFP also controls the low power state, driving strength, pull-up/down and event detection of each pin. Below is a diagram of internal connections between -the MFP logic and the remaining SoC peripherals: +the MFP logic and the remaining SoC peripherals:: +--------+ | |--(GPIO19)--+ @@ -69,8 +71,8 @@ NOTE: with such a clear separation of MFP and GPIO, by GPIO<xx> we normally mean it is a GPIO signal, and by MFP<xxx> or pin xxx, we mean a physical pad (or ball). - MFP API Usage -=============== +MFP API Usage +============= For board code writers, here are some guidelines: @@ -94,9 +96,9 @@ For board code writers, here are some guidelines: PXA310 supporting some additional ones), thus the difference is actually covered in a single mfp-pxa300.h. -2. prepare an array for the initial pin configurations, e.g.: +2. prepare an array for the initial pin configurations, e.g.:: - static unsigned long mainstone_pin_config[] __initdata = { + static unsigned long mainstone_pin_config[] __initdata = { /* Chip Select */ GPIO15_nCS_1, @@ -116,7 +118,7 @@ For board code writers, here are some guidelines: /* GPIO */ GPIO1_GPIO | WAKEUP_ON_EDGE_BOTH, - }; + }; a) once the pin configurations are passed to pxa{2xx,3xx}_mfp_config(), and written to the actual registers, they are useless and may discard, @@ -143,17 +145,17 @@ For board code writers, here are some guidelines: d) although PXA3xx MFP supports edge detection on each pin, the internal logic will only wakeup the system when those specific bits in ADxER registers are set, which can be well mapped to the - corresponding peripheral, thus set_irq_wake() can be called with + corresponding peripheral, thus set_irq_wake() can be called with the peripheral IRQ to enable the wakeup. - MFP on PXA3xx -=============== +MFP on PXA3xx +============= Every external I/O pad on PXA3xx (excluding those for special purpose) has one MFP logic associated, and is controlled by one MFP register (MFPR). -The MFPR has the following bit definitions (for PXA300/PXA310/PXA320): +The MFPR has the following bit definitions (for PXA300/PXA310/PXA320):: 31 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ @@ -183,8 +185,8 @@ The MFPR has the following bit definitions (for PXA300/PXA310/PXA320): 0b006 - slow 10mA 0b007 - fast 10mA - MFP Design for PXA2xx/PXA3xx -============================== +MFP Design for PXA2xx/PXA3xx +============================ Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified MFP API is introduced to cover both series of processors. @@ -194,11 +196,11 @@ configurations, these definitions are processor and platform independent, and the actual API invoked to convert these definitions into register settings and make them effective there-after. - Files Involved - -------------- +Files Involved +-------------- - arch/arm/mach-pxa/include/mach/mfp.h - + for 1. Unified pin definitions - enum constants for all configurable pins 2. processor-neutral bit definitions for a possible MFP configuration @@ -226,42 +228,42 @@ make them effective there-after. for implementation of the pin configuration to take effect for the actual processor. - Pin Configuration - ----------------- +Pin Configuration +----------------- The following comments are copied from mfp.h (see the actual source code - for most updated info) - - /* - * a possible MFP configuration is represented by a 32-bit integer - * - * bit 0.. 9 - MFP Pin Number (1024 Pins Maximum) - * bit 10..12 - Alternate Function Selection - * bit 13..15 - Drive Strength - * bit 16..18 - Low Power Mode State - * bit 19..20 - Low Power Mode Edge Detection - * bit 21..22 - Run Mode Pull State - * - * to facilitate the definition, the following macros are provided - * - * MFP_CFG_DEFAULT - default MFP configuration value, with - * alternate function = 0, - * drive strength = fast 3mA (MFP_DS03X) - * low power mode = default - * edge detection = none - * - * MFP_CFG - default MFPR value with alternate function - * MFP_CFG_DRV - default MFPR value with alternate function and - * pin drive strength - * MFP_CFG_LPM - default MFPR value with alternate function and - * low power mode - * MFP_CFG_X - default MFPR value with alternate function, - * pin drive strength and low power mode - */ - - Examples of pin configurations are: - - #define GPIO94_SSP3_RXD MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT) + for most updated info):: + + /* + * a possible MFP configuration is represented by a 32-bit integer + * + * bit 0.. 9 - MFP Pin Number (1024 Pins Maximum) + * bit 10..12 - Alternate Function Selection + * bit 13..15 - Drive Strength + * bit 16..18 - Low Power Mode State + * bit 19..20 - Low Power Mode Edge Detection + * bit 21..22 - Run Mode Pull State + * + * to facilitate the definition, the following macros are provided + * + * MFP_CFG_DEFAULT - default MFP configuration value, with + * alternate function = 0, + * drive strength = fast 3mA (MFP_DS03X) + * low power mode = default + * edge detection = none + * + * MFP_CFG - default MFPR value with alternate function + * MFP_CFG_DRV - default MFPR value with alternate function and + * pin drive strength + * MFP_CFG_LPM - default MFPR value with alternate function and + * low power mode + * MFP_CFG_X - default MFPR value with alternate function, + * pin drive strength and low power mode + */ + + Examples of pin configurations are:: + + #define GPIO94_SSP3_RXD MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT) which reads GPIO94 can be configured as SSP3_RXD, with alternate function selection of 1, driving strength of 0b101, and a float state in low power @@ -272,8 +274,8 @@ make them effective there-after. do so, simply because this default setting is usually carefully encoded, and is supposed to work in most cases. - Register Settings - ----------------- +Register Settings +----------------- Register settings on PXA3xx for a pin configuration is actually very straight-forward, most bits can be converted directly into MFPR value diff --git a/Documentation/arm/SA1100/ADSBitsy b/Documentation/arm/sa1100/adsbitsy.rst index f9f62e8c0719..c179cb26b682 100644 --- a/Documentation/arm/SA1100/ADSBitsy +++ b/Documentation/arm/sa1100/adsbitsy.rst @@ -1,4 +1,7 @@ +=============================== ADS Bitsy Single Board Computer +=============================== + (It is different from Bitsy(iPAQ) of Compaq) For more details, contact Applied Data Systems or see @@ -15,7 +18,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000. Linux can be used with the ADS BootLoader that ships with the newer rev boards. See their documentation on how to load Linux. -Supported peripherals: +Supported peripherals +===================== + - SA1100 LCD frame buffer (8/16bpp...sort of) - SA1111 USB Master - SA1100 serial port @@ -25,10 +30,13 @@ Supported peripherals: - serial ports (ttyS[0-2]) - ttyS0 is default for serial console -To do: +To do +===== + - everything else! :-) -Notes: +Notes +===== - The flash on board is divided into 3 partitions. You should be careful to use flash on board. diff --git a/Documentation/arm/SA1100/Assabet b/Documentation/arm/sa1100/assabet.rst index e08a6739e72c..3e704831c311 100644 --- a/Documentation/arm/SA1100/Assabet +++ b/Documentation/arm/sa1100/assabet.rst @@ -1,3 +1,4 @@ +============================================ The Intel Assabet (SA-1110 evaluation) board ============================================ @@ -11,7 +12,7 @@ http://www.cs.cmu.edu/~wearable/software/assabet.html Building the kernel ------------------- -To build the kernel with current defaults: +To build the kernel with current defaults:: make assabet_config make oldconfig @@ -51,9 +52,9 @@ Brief examples on how to boot Linux with RedBoot are shown below. But first you need to have RedBoot installed in your flash memory. A known to work precompiled RedBoot binary is available from the following location: -ftp://ftp.netwinder.org/users/n/nico/ -ftp://ftp.arm.linux.org.uk/pub/linux/arm/people/nico/ -ftp://ftp.handhelds.org/pub/linux/arm/sa-1100-patches/ +- ftp://ftp.netwinder.org/users/n/nico/ +- ftp://ftp.arm.linux.org.uk/pub/linux/arm/people/nico/ +- ftp://ftp.handhelds.org/pub/linux/arm/sa-1100-patches/ Look for redboot-assabet*.tgz. Some installation infos are provided in redboot-assabet*.txt. @@ -71,12 +72,12 @@ Socket Communications Inc.), you should strongly consider using it for TFTP file transfers. You must insert it before RedBoot runs since it can't detect it dynamically. -To initialize the flash directory: +To initialize the flash directory:: fis init -f To initialize the non-volatile settings, like whether you want to use BOOTP or -a static IP address, etc, use this command: +a static IP address, etc, use this command:: fconfig -i @@ -85,15 +86,15 @@ Writing a kernel image into flash --------------------------------- First, the kernel image must be loaded into RAM. If you have the zImage file -available on a TFTP server: +available on a TFTP server:: load zImage -r -b 0x100000 -If you rather want to use Y-Modem upload over the serial port: +If you rather want to use Y-Modem upload over the serial port:: load -m ymodem -r -b 0x100000 -To write it to flash: +To write it to flash:: fis create "Linux kernel" -b 0x100000 -l 0xc0000 @@ -102,18 +103,18 @@ Booting the kernel ------------------ The kernel still requires a filesystem to boot. A ramdisk image can be loaded -as follows: +as follows:: load ramdisk_image.gz -r -b 0x800000 Again, Y-Modem upload can be used instead of TFTP by replacing the file name by '-y ymodem'. -Now the kernel can be retrieved from flash like this: +Now the kernel can be retrieved from flash like this:: fis load "Linux kernel" -or loaded as described previously. To boot the kernel: +or loaded as described previously. To boot the kernel:: exec -b 0x100000 -l 0xc0000 @@ -134,35 +135,35 @@ creating JFFS/JFFS2 images is available from the same site. For instance, a sample JFFS2 image can be retrieved from the same FTP sites mentioned below for the precompiled RedBoot image. -To load this file: +To load this file:: load sample_img.jffs2 -r -b 0x100000 -The result should look like: +The result should look like:: -RedBoot> load sample_img.jffs2 -r -b 0x100000 -Raw file loaded 0x00100000-0x00377424 + RedBoot> load sample_img.jffs2 -r -b 0x100000 + Raw file loaded 0x00100000-0x00377424 -Now we must know the size of the unallocated flash: +Now we must know the size of the unallocated flash:: fis free -Result: +Result:: -RedBoot> fis free - 0x500E0000 .. 0x503C0000 + RedBoot> fis free + 0x500E0000 .. 0x503C0000 The values above may be different depending on the size of the filesystem and the type of flash. See their usage below as an example and take care of substituting yours appropriately. -We must determine some values: +We must determine some values:: -size of unallocated flash: 0x503c0000 - 0x500e0000 = 0x2e0000 -size of the filesystem image: 0x00377424 - 0x00100000 = 0x277424 + size of unallocated flash: 0x503c0000 - 0x500e0000 = 0x2e0000 + size of the filesystem image: 0x00377424 - 0x00100000 = 0x277424 We want to fit the filesystem image of course, but we also want to give it all -the remaining flash space as well. To write it: +the remaining flash space as well. To write it:: fis unlock -f 0x500E0000 -l 0x2e0000 fis erase -f 0x500E0000 -l 0x2e0000 @@ -171,32 +172,32 @@ the remaining flash space as well. To write it: Now the filesystem is associated to a MTD "partition" once Linux has discovered what they are in the boot process. From Redboot, the 'fis list' command -displays them: - -RedBoot> fis list -Name FLASH addr Mem addr Length Entry point -RedBoot 0x50000000 0x50000000 0x00020000 0x00000000 -RedBoot config 0x503C0000 0x503C0000 0x00020000 0x00000000 -FIS directory 0x503E0000 0x503E0000 0x00020000 0x00000000 -Linux kernel 0x50020000 0x00100000 0x000C0000 0x00000000 -JFFS2 0x500E0000 0x500E0000 0x002E0000 0x00000000 - -However Linux should display something like: - -SA1100 flash: probing 32-bit flash bus -SA1100 flash: Found 2 x16 devices at 0x0 in 32-bit mode -Using RedBoot partition definition -Creating 5 MTD partitions on "SA1100 flash": -0x00000000-0x00020000 : "RedBoot" -0x00020000-0x000e0000 : "Linux kernel" -0x000e0000-0x003c0000 : "JFFS2" -0x003c0000-0x003e0000 : "RedBoot config" -0x003e0000-0x00400000 : "FIS directory" +displays them:: + + RedBoot> fis list + Name FLASH addr Mem addr Length Entry point + RedBoot 0x50000000 0x50000000 0x00020000 0x00000000 + RedBoot config 0x503C0000 0x503C0000 0x00020000 0x00000000 + FIS directory 0x503E0000 0x503E0000 0x00020000 0x00000000 + Linux kernel 0x50020000 0x00100000 0x000C0000 0x00000000 + JFFS2 0x500E0000 0x500E0000 0x002E0000 0x00000000 + +However Linux should display something like:: + + SA1100 flash: probing 32-bit flash bus + SA1100 flash: Found 2 x16 devices at 0x0 in 32-bit mode + Using RedBoot partition definition + Creating 5 MTD partitions on "SA1100 flash": + 0x00000000-0x00020000 : "RedBoot" + 0x00020000-0x000e0000 : "Linux kernel" + 0x000e0000-0x003c0000 : "JFFS2" + 0x003c0000-0x003e0000 : "RedBoot config" + 0x003e0000-0x00400000 : "FIS directory" What's important here is the position of the partition we are interested in, which is the third one. Within Linux, this correspond to /dev/mtdblock2. Therefore to boot Linux with the kernel and its root filesystem in flash, we -need this RedBoot command: +need this RedBoot command:: fis load "Linux kernel" exec -b 0x100000 -l 0xc0000 -c "root=/dev/mtdblock2" @@ -218,21 +219,21 @@ time the Assabet is rebooted. Therefore it's possible to automate the boot process using RedBoot's scripting capability. For example, I use this to boot Linux with both the kernel and the ramdisk -images retrieved from a TFTP server on the network: - -RedBoot> fconfig -Run script at boot: false true -Boot script: -Enter script, terminate with empty line ->> load zImage -r -b 0x100000 ->> load ramdisk_ks.gz -r -b 0x800000 ->> exec -b 0x100000 -l 0xc0000 ->> -Boot script timeout (1000ms resolution): 3 -Use BOOTP for network configuration: true -GDB connection port: 9000 -Network debug at boot time: false -Update RedBoot non-volatile configuration - are you sure (y/n)? y +images retrieved from a TFTP server on the network:: + + RedBoot> fconfig + Run script at boot: false true + Boot script: + Enter script, terminate with empty line + >> load zImage -r -b 0x100000 + >> load ramdisk_ks.gz -r -b 0x800000 + >> exec -b 0x100000 -l 0xc0000 + >> + Boot script timeout (1000ms resolution): 3 + Use BOOTP for network configuration: true + GDB connection port: 9000 + Network debug at boot time: false + Update RedBoot non-volatile configuration - are you sure (y/n)? y Then, rebooting the Assabet is just a matter of waiting for the login prompt. @@ -240,6 +241,7 @@ Then, rebooting the Assabet is just a matter of waiting for the login prompt. Nicolas Pitre nico@fluxnic.net + June 12, 2001 @@ -249,52 +251,51 @@ Status of peripherals in -rmk tree (updated 14/10/2001) Assabet: Serial ports: Radio: TX, RX, CTS, DSR, DCD, RI - PM: Not tested. - COM: TX, RX, CTS, DSR, DCD, RTS, DTR, PM - PM: Not tested. - I2C: Implemented, not fully tested. - L3: Fully tested, pass. - PM: Not tested. + - PM: Not tested. + - COM: TX, RX, CTS, DSR, DCD, RTS, DTR, PM + - PM: Not tested. + - I2C: Implemented, not fully tested. + - L3: Fully tested, pass. + - PM: Not tested. Video: - LCD: Fully tested. PM - (LCD doesn't like being blanked with - neponset connected) - Video out: Not fully + - LCD: Fully tested. PM + + (LCD doesn't like being blanked with neponset connected) + + - Video out: Not fully Audio: UDA1341: - Playback: Fully tested, pass. - Record: Implemented, not tested. - PM: Not tested. + - Playback: Fully tested, pass. + - Record: Implemented, not tested. + - PM: Not tested. UCB1200: - Audio play: Implemented, not heavily tested. - Audio rec: Implemented, not heavily tested. - Telco audio play: Implemented, not heavily tested. - Telco audio rec: Implemented, not heavily tested. - POTS control: No - Touchscreen: Yes - PM: Not tested. + - Audio play: Implemented, not heavily tested. + - Audio rec: Implemented, not heavily tested. + - Telco audio play: Implemented, not heavily tested. + - Telco audio rec: Implemented, not heavily tested. + - POTS control: No + - Touchscreen: Yes + - PM: Not tested. Other: - PCMCIA: - LPE: Fully tested, pass. - USB: No - IRDA: - SIR: Fully tested, pass. - FIR: Fully tested, pass. - PM: Not tested. + - PCMCIA: + - LPE: Fully tested, pass. + - USB: No + - IRDA: + - SIR: Fully tested, pass. + - FIR: Fully tested, pass. + - PM: Not tested. Neponset: Serial ports: - COM1,2: TX, RX, CTS, DSR, DCD, RTS, DTR - PM: Not tested. - USB: Implemented, not heavily tested. - PCMCIA: Implemented, not heavily tested. - PM: Not tested. - CF: Implemented, not heavily tested. - PM: Not tested. + - COM1,2: TX, RX, CTS, DSR, DCD, RTS, DTR + - PM: Not tested. + - USB: Implemented, not heavily tested. + - PCMCIA: Implemented, not heavily tested. + - CF: Implemented, not heavily tested. + - PM: Not tested. More stuff can be found in the -np (Nicolas Pitre's) tree. - diff --git a/Documentation/arm/SA1100/Brutus b/Documentation/arm/sa1100/brutus.rst index 6a3aa95e9bfd..e1a23bee6d44 100644 --- a/Documentation/arm/SA1100/Brutus +++ b/Documentation/arm/sa1100/brutus.rst @@ -1,9 +1,13 @@ -Brutus is an evaluation platform for the SA1100 manufactured by Intel. +====== +Brutus +====== + +Brutus is an evaluation platform for the SA1100 manufactured by Intel. For more details, see: http://developer.intel.com -To compile for Brutus, you must issue the following commands: +To compile for Brutus, you must issue the following commands:: make brutus_config make config @@ -16,25 +20,23 @@ must be loaded at 0xc0008000 in Brutus's memory and execution started at entry. But prior to execute the kernel, a ramdisk image must also be loaded in -memory. Use memory address 0xd8000000 for this. Note that the file +memory. Use memory address 0xd8000000 for this. Note that the file containing the (compressed) ramdisk image must not exceed 4 MB. Typically, you'll need angelboot to load the kernel. -The following angelboot.opt file should be used: - ------ begin angelboot.opt ----- -base 0xc0008000 -entry 0xc0008000 -r0 0x00000000 -r1 0x00000010 -device /dev/ttyS0 -options "9600 8N1" -baud 115200 -otherfile ramdisk_img.gz -otherbase 0xd8000000 ------ end angelboot.opt ----- - -Then load the kernel and ramdisk with: +The following angelboot.opt file should be used:: + + base 0xc0008000 + entry 0xc0008000 + r0 0x00000000 + r1 0x00000010 + device /dev/ttyS0 + options "9600 8N1" + baud 115200 + otherfile ramdisk_img.gz + otherbase 0xd8000000 + +Then load the kernel and ramdisk with:: angelboot -f angelboot.opt zImage @@ -44,14 +46,16 @@ console is provided through the second Brutus serial port. To access it, you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow control. -Currently supported: +Currently supported +=================== + - RS232 serial ports - audio output - LCD screen - keyboard - -The actual Brutus support may not be complete without extra patches. -If such patches exist, they should be found from + +The actual Brutus support may not be complete without extra patches. +If such patches exist, they should be found from ftp.netwinder.org/users/n/nico. A full PCMCIA support is still missing, although it's possible to hack @@ -63,4 +67,3 @@ Any contribution is welcome. Please send patches to nico@fluxnic.net Have Fun ! - diff --git a/Documentation/arm/SA1100/CERF b/Documentation/arm/sa1100/cerf.rst index b3d845301ef1..7fa71b609bf9 100644 --- a/Documentation/arm/SA1100/CERF +++ b/Documentation/arm/sa1100/cerf.rst @@ -1,3 +1,7 @@ +============== +CerfBoard/Cube +============== + *** The StrongARM version of the CerfBoard/Cube has been discontinued *** The Intrinsyc CerfBoard is a StrongARM 1110-based computer on a board @@ -9,7 +13,9 @@ Intrinsyc website, http://www.intrinsyc.com. This document describes the support in the Linux kernel for the Intrinsyc CerfBoard. -Supported in this version: +Supported in this version +========================= + - CompactFlash+ slot (select PCMCIA in General Setup and any options that may be required) - Onboard Crystal CS8900 Ethernet controller (Cerf CS8900A support in @@ -19,7 +25,7 @@ Supported in this version: In order to get this kernel onto your Cerf, you need a server that runs both BOOTP and TFTP. Detailed instructions should have come with your evaluation kit on how to use the bootloader. This series of commands -will suffice: +will suffice:: make ARCH=arm CROSS_COMPILE=arm-linux- cerfcube_defconfig make ARCH=arm CROSS_COMPILE=arm-linux- zImage diff --git a/Documentation/arm/sa1100/freebird.rst b/Documentation/arm/sa1100/freebird.rst new file mode 100644 index 000000000000..81043d0c6d64 --- /dev/null +++ b/Documentation/arm/sa1100/freebird.rst @@ -0,0 +1,25 @@ +======== +Freebird +======== + +Freebird-1.1 is produced by Legend(C), Inc. +`http://web.archive.org/web/*/http://www.legend.com.cn` +and software/linux maintained by Coventive(C), Inc. +(http://www.coventive.com) + +Based on the Nicolas's strongarm kernel tree. + +Maintainer: + +Chester Kuo + - <chester@coventive.com> + - <chester@linux.org.tw> + +Author: + +- Tim wu <timwu@coventive.com> +- CIH <cih@coventive.com> +- Eric Peng <ericpeng@coventive.com> +- Jeff Lee <jeff_lee@coventive.com> +- Allen Cheng +- Tony Liu <tonyliu@coventive.com> diff --git a/Documentation/arm/SA1100/GraphicsClient b/Documentation/arm/sa1100/graphicsclient.rst index 867bb35943af..a73d61c3ce91 100644 --- a/Documentation/arm/SA1100/GraphicsClient +++ b/Documentation/arm/sa1100/graphicsclient.rst @@ -1,9 +1,11 @@ +============================================= ADS GraphicsClient Plus Single Board Computer +============================================= For more details, contact Applied Data Systems or see http://www.applieddata.net/products.html -The original Linux support for this product has been provided by +The original Linux support for this product has been provided by Nicolas Pitre <nico@fluxnic.net>. Continued development work by Woojung Huh <whuh@applieddata.net> @@ -14,8 +16,8 @@ board supports MTD/JFFS, so you could also mount something on there. Use 'make graphicsclient_config' before any 'make config'. This will set up defaults for GraphicsClient Plus support. -The kernel zImage is linked to be loaded and executed at 0xc0200000. -Also the following registers should have the specified values upon entry: +The kernel zImage is linked to be loaded and executed at 0xc0200000. +Also the following registers should have the specified values upon entry:: r0 = 0 r1 = 29 (this is the GraphicsClient architecture number) @@ -31,23 +33,21 @@ as outlined below. In any case, if you're planning on deploying something en masse, you should probably get the newer board. If using Angel on the older boards, here is a typical angel.opt option file -if the kernel is loaded through the Angel Debug Monitor: - ------ begin angelboot.opt ----- -base 0xc0200000 -entry 0xc0200000 -r0 0x00000000 -r1 0x0000001d -device /dev/ttyS1 -options "38400 8N1" -baud 115200 -#otherfile ramdisk.gz -#otherbase 0xc0800000 -exec minicom ------ end angelboot.opt ----- +if the kernel is loaded through the Angel Debug Monitor:: + + base 0xc0200000 + entry 0xc0200000 + r0 0x00000000 + r1 0x0000001d + device /dev/ttyS1 + options "38400 8N1" + baud 115200 + #otherfile ramdisk.gz + #otherbase 0xc0800000 + exec minicom Then the kernel (and ramdisk if otherfile/otherbase lines above are -uncommented) would be loaded with: +uncommented) would be loaded with:: angelboot -f angelboot.opt zImage @@ -59,7 +59,9 @@ If any other bootloader is used, ensure it accomplish the same, especially for r0/r1 register values before jumping into the kernel. -Supported peripherals: +Supported peripherals +===================== + - SA1100 LCD frame buffer (8/16bpp...sort of) - on-board SMC 92C96 ethernet NIC - SA1100 serial port @@ -74,11 +76,14 @@ Supported peripherals: See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation and example user space code. ps/2 keybd is multiplexed through this driver -To do: +To do +===== + - UCB1200 audio with new ucb_generic layer - everything else! :-) -Notes: +Notes +===== - The flash on board is divided into 3 partitions. mtd0 is where the ADS boot ROM and zImage is stored. It's been marked as @@ -95,4 +100,3 @@ Notes: fixed soon. Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! - diff --git a/Documentation/arm/SA1100/GraphicsMaster b/Documentation/arm/sa1100/graphicsmaster.rst index 9145088a0ba2..e39892514f0c 100644 --- a/Documentation/arm/SA1100/GraphicsMaster +++ b/Documentation/arm/sa1100/graphicsmaster.rst @@ -1,4 +1,6 @@ +======================================== ADS GraphicsMaster Single Board Computer +======================================== For more details, contact Applied Data Systems or see http://www.applieddata.net/products.html @@ -15,7 +17,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000. Linux can be used with the ADS BootLoader that ships with the newer rev boards. See their documentation on how to load Linux. -Supported peripherals: +Supported peripherals +===================== + - SA1100 LCD frame buffer (8/16bpp...sort of) - SA1111 USB Master - on-board SMC 92C96 ethernet NIC @@ -31,10 +35,13 @@ Supported peripherals: See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation and example user space code. ps/2 keybd is multiplexed through this driver -To do: +To do +===== + - everything else! :-) -Notes: +Notes +===== - The flash on board is divided into 3 partitions. mtd0 is where the zImage is stored. It's been marked as read-only to keep you diff --git a/Documentation/arm/SA1100/HUW_WEBPANEL b/Documentation/arm/sa1100/huw_webpanel.rst index fd56b48d4833..1dc7ccb165f0 100644 --- a/Documentation/arm/SA1100/HUW_WEBPANEL +++ b/Documentation/arm/sa1100/huw_webpanel.rst @@ -1,9 +1,14 @@ +======================= +Hoeft & Wessel Webpanel +======================= + The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG If you want more information, please visit http://www.hoeft-wessel.de -To build the kernel: +To build the kernel:: + make huw_webpanel_config make oldconfig [accept all defaults] @@ -14,4 +19,3 @@ Roman Jordan jor@hoeft-wessel.de Christoph Schulz schu@hoeft-wessel.de 2000/12/18/ - diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arm/sa1100/index.rst new file mode 100644 index 000000000000..68c2a280a745 --- /dev/null +++ b/Documentation/arm/sa1100/index.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Intel StrongARM 1100 +==================== + +.. toctree:: + :maxdepth: 1 + + adsbitsy + assabet + brutus + cerf + freebird + graphicsclient + graphicsmaster + huw_webpanel + itsy + lart + nanoengine + pangolin + pleb + serial_uart + tifon + yopy diff --git a/Documentation/arm/SA1100/Itsy b/Documentation/arm/sa1100/itsy.rst index 44b94997fa0d..f49896ba3ef1 100644 --- a/Documentation/arm/SA1100/Itsy +++ b/Documentation/arm/sa1100/itsy.rst @@ -1,3 +1,7 @@ +==== +Itsy +==== + Itsy is a research project done by the Western Research Lab, and Systems Research Center in Palo Alto, CA. The Itsy project is one of several research projects at Compaq that are related to pocket computing. @@ -7,6 +11,7 @@ For more information, see: http://www.hpl.hp.com/downloads/crl/itsy/ Notes on initial 2.4 Itsy support (8/27/2000) : + The port was done on an Itsy version 1.5 machine with a daughtercard with 64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for serial console (to see what you're doing). No other devices have been @@ -18,8 +23,10 @@ Finally, you will need to cd to arch/arm/boot/tools and execute a make there to build the params-itsy program used to boot the kernel. In order to install the port of 2.4 to the itsy, You will need to set the -configuration parameters in the monitor as follows: -Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0 +configuration parameters in the monitor as follows:: + + Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0 + Make sure the start-routine address is set to 0x00060000. Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the @@ -29,7 +36,8 @@ flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000 handhelds.org. The serial connection we established was at: - 8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the + +8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the params-itsy program, and in the kernel itself. This can be changed, but not easily. The monitor parameters are easily changed, the params program setup is assembly outl's, and the kernel is a configuration item specific to diff --git a/Documentation/arm/SA1100/LART b/Documentation/arm/sa1100/lart.rst index 6d412b685598..94c0568d1095 100644 --- a/Documentation/arm/SA1100/LART +++ b/Documentation/arm/sa1100/lart.rst @@ -1,5 +1,6 @@ +==================================== Linux Advanced Radio Terminal (LART) ------------------------------------- +==================================== The LART is a small (7.5 x 10cm) SA-1100 board, designed for embedded applications. It has 32 MB DRAM, 4MB Flash ROM, double RS232 and all diff --git a/Documentation/arm/SA1100/nanoEngine b/Documentation/arm/sa1100/nanoengine.rst index 48a7934f95f6..47f1a14cf98a 100644 --- a/Documentation/arm/SA1100/nanoEngine +++ b/Documentation/arm/sa1100/nanoengine.rst @@ -1,11 +1,11 @@ +========== nanoEngine ----------- +========== -"nanoEngine" is a SA1110 based single board computer from +"nanoEngine" is a SA1110 based single board computer from Bright Star Engineering Inc. See www.brightstareng.com/arm for more info. (Ref: Stuart Adams <sja@brightstareng.com>) Also visit Larry Doolittle's "Linux for the nanoEngine" site: http://www.brightstareng.com/arm/nanoeng.htm - diff --git a/Documentation/arm/SA1100/Pangolin b/Documentation/arm/sa1100/pangolin.rst index 077a6120e129..f0c5c1618553 100644 --- a/Documentation/arm/SA1100/Pangolin +++ b/Documentation/arm/sa1100/pangolin.rst @@ -1,16 +1,22 @@ +======== +Pangolin +======== + Pangolin is a StrongARM 1110-based evaluation platform produced by Dialogue Technology (http://www.dialogue.com.tw/). It has EISA slots for ease of configuration with SDRAM/Flash memory card, USB/Serial/Audio card, Compact Flash card, PCMCIA/IDE card and TFT-LCD card. -To compile for Pangolin, you must issue the following commands: +To compile for Pangolin, you must issue the following commands:: make pangolin_config make oldconfig make zImage -Supported peripherals: +Supported peripherals +===================== + - SA1110 serial port (UART1/UART2/UART3) - flash memory access - compact flash driver diff --git a/Documentation/arm/SA1100/PLEB b/Documentation/arm/sa1100/pleb.rst index b9c8a631a351..d5b732967aa3 100644 --- a/Documentation/arm/SA1100/PLEB +++ b/Documentation/arm/sa1100/pleb.rst @@ -1,3 +1,7 @@ +==== +PLEB +==== + The PLEB project was started as a student initiative at the School of Computer Science and Engineering, University of New South Wales to make a pocket computer capable of running the Linux Kernel. @@ -7,5 +11,3 @@ PLEB support has yet to be fully integrated. For more information, see: http://www.cse.unsw.edu.au - - diff --git a/Documentation/arm/sa1100/serial_uart.rst b/Documentation/arm/sa1100/serial_uart.rst new file mode 100644 index 000000000000..ea983642b9be --- /dev/null +++ b/Documentation/arm/sa1100/serial_uart.rst @@ -0,0 +1,51 @@ +================== +SA1100 serial port +================== + +The SA1100 serial port had its major/minor numbers officially assigned:: + + > Date: Sun, 24 Sep 2000 21:40:27 -0700 + > From: H. Peter Anvin <hpa@transmeta.com> + > To: Nicolas Pitre <nico@CAM.ORG> + > Cc: Device List Maintainer <device@lanana.org> + > Subject: Re: device + > + > Okay. Note that device numbers 204 and 205 are used for "low density + > serial devices", so you will have a range of minors on those majors (the + > tty device layer handles this just fine, so you don't have to worry about + > doing anything special.) + > + > So your assignments are: + > + > 204 char Low-density serial ports + > 5 = /dev/ttySA0 SA1100 builtin serial port 0 + > 6 = /dev/ttySA1 SA1100 builtin serial port 1 + > 7 = /dev/ttySA2 SA1100 builtin serial port 2 + > + > 205 char Low-density serial ports (alternate device) + > 5 = /dev/cusa0 Callout device for ttySA0 + > 6 = /dev/cusa1 Callout device for ttySA1 + > 7 = /dev/cusa2 Callout device for ttySA2 + > + +You must create those inodes in /dev on the root filesystem used +by your SA1100-based device:: + + mknod ttySA0 c 204 5 + mknod ttySA1 c 204 6 + mknod ttySA2 c 204 7 + mknod cusa0 c 205 5 + mknod cusa1 c 205 6 + mknod cusa2 c 205 7 + +In addition to the creation of the appropriate device nodes above, you +must ensure your user space applications make use of the correct device +name. The classic example is the content of the /etc/inittab file where +you might have a getty process started on ttyS0. + +In this case: + +- replace occurrences of ttyS0 with ttySA0, ttyS1 with ttySA1, etc. + +- don't forget to add 'ttySA0', 'console', or the appropriate tty name + in /etc/securetty for root to be allowed to login as well. diff --git a/Documentation/arm/SA1100/Tifon b/Documentation/arm/sa1100/tifon.rst index dd1934d9c851..c26e910b9ea7 100644 --- a/Documentation/arm/SA1100/Tifon +++ b/Documentation/arm/sa1100/tifon.rst @@ -1,7 +1,7 @@ +===== Tifon ------ +===== More info has to come... Contact: Peter Danielsson <peter.danielsson@era-t.ericsson.se> - diff --git a/Documentation/arm/SA1100/Yopy b/Documentation/arm/sa1100/yopy.rst index e14f16d836ac..5b35a5f61a44 100644 --- a/Documentation/arm/SA1100/Yopy +++ b/Documentation/arm/sa1100/yopy.rst @@ -1,2 +1,5 @@ -See http://www.yopydeveloper.org for more. +==== +Yopy +==== +See http://www.yopydeveloper.org for more. diff --git a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt b/Documentation/arm/samsung-s3c24xx/cpufreq.rst index fa968aa99d67..2ddc26c03b1f 100644 --- a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt +++ b/Documentation/arm/samsung-s3c24xx/cpufreq.rst @@ -1,5 +1,6 @@ - S3C24XX CPUfreq support - ======================= +======================= +S3C24XX CPUfreq support +======================= Introduction ------------ diff --git a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst index b87292e05f2f..7863c93652f8 100644 --- a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt +++ b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst @@ -1,5 +1,6 @@ - Simtec Electronics EB2410ITX (BAST) - =================================== +=================================== +Simtec Electronics EB2410ITX (BAST) +=================================== http://www.simtec.co.uk/products/EB2410ITX/ diff --git a/Documentation/arm/Samsung-S3C24XX/GPIO.txt b/Documentation/arm/samsung-s3c24xx/gpio.rst index e8f918b96123..f7c3d7d011a2 100644 --- a/Documentation/arm/Samsung-S3C24XX/GPIO.txt +++ b/Documentation/arm/samsung-s3c24xx/gpio.rst @@ -1,5 +1,6 @@ - S3C24XX GPIO Control - ==================== +==================== +S3C24XX GPIO Control +==================== Introduction ------------ @@ -12,7 +13,7 @@ Introduction of the s3c2410 GPIO system, please read the Samsung provided data-sheet/users manual to find out the complete list. - See Documentation/arm/Samsung/GPIO.txt for the core implementation. + See Documentation/arm/samsung/gpio.rst for the core implementation. GPIOLIB @@ -26,16 +27,16 @@ GPIOLIB listed below will be removed (they may be marked as __deprecated in the near future). - The following functions now either have a s3c_ specific variant + The following functions now either have a `s3c_` specific variant or are merged into gpiolib. See the definitions in arch/arm/plat-samsung/include/plat/gpio-cfg.h: - s3c2410_gpio_setpin() gpio_set_value() or gpio_direction_output() - s3c2410_gpio_getpin() gpio_get_value() or gpio_direction_input() - s3c2410_gpio_getirq() gpio_to_irq() - s3c2410_gpio_cfgpin() s3c_gpio_cfgpin() - s3c2410_gpio_getcfg() s3c_gpio_getcfg() - s3c2410_gpio_pullup() s3c_gpio_setpull() + - s3c2410_gpio_setpin() gpio_set_value() or gpio_direction_output() + - s3c2410_gpio_getpin() gpio_get_value() or gpio_direction_input() + - s3c2410_gpio_getirq() gpio_to_irq() + - s3c2410_gpio_cfgpin() s3c_gpio_cfgpin() + - s3c2410_gpio_getcfg() s3c_gpio_getcfg() + - s3c2410_gpio_pullup() s3c_gpio_setpull() GPIOLIB conversion @@ -77,7 +78,7 @@ out s3c2410 API, then here are some notes on the process. 6) s3c2410_gpio_getirq() should be directly replaceable with the gpio_to_irq() call. -The s3c2410_gpio and gpio_ calls have always operated on the same gpio +The s3c2410_gpio and `gpio_` calls have always operated on the same gpio numberspace, so there is no problem with converting the gpio numbering between the calls. diff --git a/Documentation/arm/Samsung-S3C24XX/H1940.txt b/Documentation/arm/samsung-s3c24xx/h1940.rst index b738859b1fc0..62a562c178e3 100644 --- a/Documentation/arm/Samsung-S3C24XX/H1940.txt +++ b/Documentation/arm/samsung-s3c24xx/h1940.rst @@ -1,5 +1,6 @@ - HP IPAQ H1940 - ============= +============= +HP IPAQ H1940 +============= http://www.handhelds.org/projects/h1940.html diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst new file mode 100644 index 000000000000..5b8a7f9398d8 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +Samsung S3C24XX SoC Family +========================== + +.. toctree:: + :maxdepth: 1 + + h1940 + gpio + cpufreq + suspend + usb-host + s3c2412 + eb2410itx + nand + smdk2440 + s3c2413 + overview diff --git a/Documentation/arm/Samsung-S3C24XX/NAND.txt b/Documentation/arm/samsung-s3c24xx/nand.rst index bc478a3409b8..938995694ee7 100644 --- a/Documentation/arm/Samsung-S3C24XX/NAND.txt +++ b/Documentation/arm/samsung-s3c24xx/nand.rst @@ -1,5 +1,6 @@ - S3C24XX NAND Support - ==================== +==================== +S3C24XX NAND Support +==================== Introduction ------------ @@ -27,4 +28,3 @@ Document Author --------------- Ben Dooks, Copyright 2007 Simtec Electronics - diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/samsung-s3c24xx/overview.rst index 00d3c3141e21..e9a1dc7276b5 100644 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ b/Documentation/arm/samsung-s3c24xx/overview.rst @@ -1,5 +1,6 @@ - S3C24XX ARM Linux Overview - ========================== +========================== +S3C24XX ARM Linux Overview +========================== @@ -182,7 +183,7 @@ NAND controller. If there are any problems the latest linux-mtd code can be found from http://www.linux-mtd.infradead.org/ - For more information see Documentation/arm/Samsung-S3C24XX/NAND.txt + For more information see Documentation/arm/samsung-s3c24xx/nand.rst SD/MMC @@ -221,8 +222,8 @@ GPIO As of v2.6.34, the move towards using gpiolib support is almost complete, and very little of the old calls are left. - See Documentation/arm/Samsung-S3C24XX/GPIO.txt for the S3C24XX specific - support and Documentation/arm/Samsung/GPIO.txt for the core Samsung + See Documentation/arm/samsung-s3c24xx/gpio.rst for the S3C24XX specific + support and Documentation/arm/samsung/gpio.rst for the core Samsung implementation. @@ -276,18 +277,18 @@ Platform Data kmalloc()s an area of memory, and copies the __initdata and then sets the relevant device's platform data. Making the function `__init` takes care of ensuring it is discarded - with the rest of the initialisation code + with the rest of the initialisation code:: - static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd) - { - struct s3c2410_xxx_mach_info *npd; + static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd) + { + struct s3c2410_xxx_mach_info *npd; npd = kmalloc(sizeof(struct s3c2410_xxx_mach_info), GFP_KERNEL); if (npd) { memcpy(npd, pd, sizeof(struct s3c2410_xxx_mach_info)); s3c_device_xxx.dev.platform_data = npd; } else { - printk(KERN_ERR "no memory for xxx platform data\n"); + printk(KERN_ERR "no memory for xxx platform data\n"); } } diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt b/Documentation/arm/samsung-s3c24xx/s3c2412.rst index dc1fd362d3c1..68b985fc6bf4 100644 --- a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt +++ b/Documentation/arm/samsung-s3c24xx/s3c2412.rst @@ -1,5 +1,6 @@ - S3C2412 ARM Linux Overview - ========================== +========================== +S3C2412 ARM Linux Overview +========================== Introduction ------------ diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt b/Documentation/arm/samsung-s3c24xx/s3c2413.rst index 909bdc7dd7b5..1f51e207fc46 100644 --- a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt +++ b/Documentation/arm/samsung-s3c24xx/s3c2413.rst @@ -1,5 +1,6 @@ - S3C2413 ARM Linux Overview - ========================== +========================== +S3C2413 ARM Linux Overview +========================== Introduction ------------ @@ -10,7 +11,7 @@ Introduction Camera Interface ---------------- +---------------- This block is currently not supported. diff --git a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt b/Documentation/arm/samsung-s3c24xx/smdk2440.rst index 429390bd4684..524fd0b4afaf 100644 --- a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt +++ b/Documentation/arm/samsung-s3c24xx/smdk2440.rst @@ -1,5 +1,6 @@ - Samsung/Meritech SMDK2440 - ========================= +========================= +Samsung/Meritech SMDK2440 +========================= Introduction ------------ diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/samsung-s3c24xx/suspend.rst index cb4f0c0cdf9d..b4f3ae9fe76e 100644 --- a/Documentation/arm/Samsung-S3C24XX/Suspend.txt +++ b/Documentation/arm/samsung-s3c24xx/suspend.rst @@ -1,5 +1,6 @@ - S3C24XX Suspend Support - ======================= +======================= +S3C24XX Suspend Support +======================= Introduction @@ -57,16 +58,16 @@ Machine Support and will end up initialising all compiled machines' pm init! The following is an example of code used for testing wakeup from - an falling edge on IRQ_EINT0: + an falling edge on IRQ_EINT0:: -static irqreturn_t button_irq(int irq, void *pw) -{ + static irqreturn_t button_irq(int irq, void *pw) + { return IRQ_HANDLED; -} + } -statuc void __init machine_init(void) -{ + statuc void __init machine_init(void) + { ... request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING, @@ -75,7 +76,7 @@ statuc void __init machine_init(void) enable_irq_wake(IRQ_EINT0); s3c_pm_init(); -} + } Debugging @@ -134,4 +135,3 @@ Document Author --------------- Ben Dooks, Copyright 2004 Simtec Electronics - diff --git a/Documentation/arm/Samsung-S3C24XX/USB-Host.txt b/Documentation/arm/samsung-s3c24xx/usb-host.rst index f82b1faefad5..c84268bd1884 100644 --- a/Documentation/arm/Samsung-S3C24XX/USB-Host.txt +++ b/Documentation/arm/samsung-s3c24xx/usb-host.rst @@ -1,5 +1,6 @@ - S3C24XX USB Host support - ======================== +======================== +S3C24XX USB Host support +======================== @@ -13,7 +14,7 @@ Configuration Enable at least the following kernel options: - menuconfig: + menuconfig:: Device Drivers ---> USB support ---> @@ -22,8 +23,9 @@ Configuration .config: - CONFIG_USB - CONFIG_USB_OHCI_HCD + + - CONFIG_USB + - CONFIG_USB_OHCI_HCD Once these options are configured, the standard set of USB device @@ -60,17 +62,14 @@ Platform Data The ports are numbered 0 and 1. power_control: - Called to enable or disable the power on the port. enable_oc: - Called to enable or disable the over-current monitoring. This should claim or release the resources being used to check the power condition on the port, such as an IRQ. report_oc: - The OHCI driver fills this field in for the over-current code to call when there is a change to the over-current state on an port. The ports argument is a bitmask of 1 bit per port, @@ -80,7 +79,6 @@ Platform Data ensure this is called correctly. port[x]: - This is struct describes each port, 0 or 1. The platform driver should set the flags field of each port to S3C_HCDFLG_USED if the port is enabled. diff --git a/Documentation/arm/Samsung/Bootloader-interface.txt b/Documentation/arm/samsung/bootloader-interface.rst index d17ed518a7ea..a56f325dae78 100644 --- a/Documentation/arm/Samsung/Bootloader-interface.txt +++ b/Documentation/arm/samsung/bootloader-interface.rst @@ -1,7 +1,9 @@ - Interface between kernel and boot loaders on Exynos boards - ========================================================== +========================================================== +Interface between kernel and boot loaders on Exynos boards +========================================================== Author: Krzysztof Kozlowski + Date : 6 June 2015 The document tries to describe currently used interface between Linux kernel @@ -17,8 +19,10 @@ executing kernel. 1. Non-Secure mode Address: sysram_ns_base_addr + +============= ============================================ ================== Offset Value Purpose -============================================================================= +============= ============================================ ================== 0x08 exynos_cpu_resume_ns, mcpm_entry_point System suspend 0x0c 0x00000bad (Magic cookie) System suspend 0x1c exynos4_secondary_startup Secondary CPU boot @@ -27,22 +31,28 @@ Offset Value Purpose 0x24 exynos_cpu_resume_ns AFTR 0x28 + 4*cpu 0x8 (Magic cookie, Exynos3250) AFTR 0x28 0x0 or last value during resume (Exynos542x) System suspend +============= ============================================ ================== 2. Secure mode Address: sysram_base_addr + +============= ============================================ ================== Offset Value Purpose -============================================================================= +============= ============================================ ================== 0x00 exynos4_secondary_startup Secondary CPU boot 0x04 exynos4_secondary_startup (Exynos542x) Secondary CPU boot 4*cpu exynos4_secondary_startup (Exynos4412) Secondary CPU boot 0x20 exynos_cpu_resume (Exynos4210 r1.0) AFTR 0x24 0xfcba0d10 (Magic cookie, Exynos4210 r1.0) AFTR +============= ============================================ ================== Address: pmu_base_addr + +============= ============================================ ================== Offset Value Purpose -============================================================================= +============= ============================================ ================== 0x0800 exynos_cpu_resume AFTR, suspend 0x0800 mcpm_entry_point (Exynos542x with MCPM) AFTR, suspend 0x0804 0xfcba0d10 (Magic cookie) AFTR @@ -50,15 +60,18 @@ Offset Value Purpose 0x0814 exynos4_secondary_startup (Exynos4210 r1.1) Secondary CPU boot 0x0818 0xfcba0d10 (Magic cookie, Exynos4210 r1.1) AFTR 0x081C exynos_cpu_resume (Exynos4210 r1.1) AFTR - +============= ============================================ ================== 3. Other (regardless of secure/non-secure mode) Address: pmu_base_addr + +============= =============================== =============================== Offset Value Purpose -============================================================================= +============= =============================== =============================== 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 7be1b8aa7cd9..7be1b8aa7cd9 100755 --- a/Documentation/arm/Samsung/clksrc-change-registers.awk +++ b/Documentation/arm/samsung/clksrc-change-registers.awk diff --git a/Documentation/arm/Samsung/GPIO.txt b/Documentation/arm/samsung/gpio.rst index 795adfd88081..5f7cadd7159e 100644 --- a/Documentation/arm/Samsung/GPIO.txt +++ b/Documentation/arm/samsung/gpio.rst @@ -1,5 +1,6 @@ - Samsung GPIO implementation - =========================== +=========================== +Samsung GPIO implementation +=========================== Introduction ------------ @@ -11,7 +12,7 @@ specific calls provided alongside the drivers/gpio core. S3C24XX (Legacy) ---------------- -See Documentation/arm/Samsung-S3C24XX/GPIO.txt for more information +See Documentation/arm/samsung-s3c24xx/gpio.rst for more information about these devices. Their implementation has been brought into line with the core samsung implementation described in this document. diff --git a/Documentation/arm/samsung/index.rst b/Documentation/arm/samsung/index.rst new file mode 100644 index 000000000000..8142cce3d23e --- /dev/null +++ b/Documentation/arm/samsung/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========== +Samsung SoC +=========== + +.. toctree:: + :maxdepth: 1 + + gpio + bootloader-interface + overview diff --git a/Documentation/arm/Samsung/Overview.txt b/Documentation/arm/samsung/overview.rst index 8f7309bad460..e74307897416 100644 --- a/Documentation/arm/Samsung/Overview.txt +++ b/Documentation/arm/samsung/overview.rst @@ -1,5 +1,6 @@ - Samsung ARM Linux Overview - ========================== +========================== +Samsung ARM Linux Overview +========================== Introduction ------------ @@ -11,7 +12,7 @@ Introduction The currently supported SoCs are: - - S3C24XX: See Documentation/arm/Samsung-S3C24XX/Overview.txt for full list + - S3C24XX: See Documentation/arm/samsung-s3c24xx/overview.rst for full list - S3C64XX: S3C6400 and S3C6410 - S5PC110 / S5PV210 @@ -22,7 +23,7 @@ S3C24XX Systems There is still documentation in Documnetation/arm/Samsung-S3C24XX/ which deals with the architecture and drivers specific to these devices. - See Documentation/arm/Samsung-S3C24XX/Overview.txt for more information + See Documentation/arm/samsung-s3c24xx/overview.rst for more information on the implementation details and specific support. @@ -32,8 +33,10 @@ Configuration A number of configurations are supplied, as there is no current way of unifying all the SoCs into one kernel. - s5pc110_defconfig - S5PC110 specific default configuration - s5pv210_defconfig - S5PV210 specific default configuration + s5pc110_defconfig + - S5PC110 specific default configuration + s5pv210_defconfig + - S5PV210 specific default configuration Layout diff --git a/Documentation/arm/Setup b/Documentation/arm/setup.rst index 0cb1e64bde80..8e12ef3fb9a7 100644 --- a/Documentation/arm/Setup +++ b/Documentation/arm/setup.rst @@ -1,5 +1,6 @@ +============================================= Kernel initialisation parameters on ARM Linux ---------------------------------------------- +============================================= The following document describes the kernel initialisation parameter structure, otherwise known as 'struct param_struct' which is used @@ -14,12 +15,10 @@ There are a lot of parameters listed in there, and they are described below: page_size - This parameter must be set to the page size of the machine, and will be checked by the kernel. nr_pages - This is the total number of pages of memory in the system. If the memory is banked, then this should contain the total number of pages in the system. @@ -28,24 +27,22 @@ below: include this information. ramdisk_size - This is now obsolete, and should not be used. flags - Various kernel flags, including: - bit 0 - 1 = mount root read only - bit 1 - unused - bit 2 - 0 = load ramdisk - bit 3 - 0 = prompt for ramdisk - rootdev + ===== ======================== + bit 0 1 = mount root read only + bit 1 unused + bit 2 0 = load ramdisk + bit 3 0 = prompt for ramdisk + ===== ======================== + rootdev major/minor number pair of device to mount as the root filesystem. - video_num_cols - video_num_rows - + video_num_cols / video_num_rows These two together describe the character size of the dummy console, or VGA console character size. They should not be used for any other purpose. @@ -54,66 +51,50 @@ below: the equivalent character size of your fbcon display. This then allows all the bootup messages to be displayed correctly. - video_x - video_y - + video_x / video_y This describes the character position of cursor on VGA console, and is otherwise unused. (should not be used for other console types, and should not be used for other purposes). memc_control_reg - MEMC chip control register for Acorn Archimedes and Acorn A5000 based machines. May be used differently by different architectures. sounddefault - Default sound setting on Acorn machines. May be used differently by different architectures. adfsdrives - Number of ADFS/MFM disks. May be used differently by different architectures. - bytes_per_char_h - bytes_per_char_v - + bytes_per_char_h / bytes_per_char_v These are now obsolete, and should not be used. pages_in_bank[4] - Number of pages in each bank of the systems memory (used for RiscPC). This is intended to be used on systems where the physical memory is non-contiguous from the processors point of view. pages_in_vram - Number of pages in VRAM (used on Acorn RiscPC). This value may also be used by loaders if the size of the video RAM can't be obtained from the hardware. - initrd_start - initrd_size - + initrd_start / initrd_size This describes the kernel virtual start address and size of the initial ramdisk. rd_start - Start address in sectors of the ramdisk image on a floppy disk. system_rev - system revision number. - system_serial_low - system_serial_high - + system_serial_low / system_serial_high system 64-bit serial number mem_fclk_21285 - The speed of the external oscillator to the 21285 (footbridge), which control's the speed of the memory bus, timer & serial port. Depending upon the speed of the cpu its value can be between @@ -121,9 +102,7 @@ below: then a value of 50 Mhz is the default on 21285 architectures. paths[8][128] - These are now obsolete, and should not be used. commandline - Kernel command line parameters. Details can be found elsewhere. diff --git a/Documentation/arm/SH-Mobile/.gitignore b/Documentation/arm/sh-mobile/.gitignore index c928dbf3cc88..c928dbf3cc88 100644 --- a/Documentation/arm/SH-Mobile/.gitignore +++ b/Documentation/arm/sh-mobile/.gitignore diff --git a/Documentation/arm/SPEAr/overview.txt b/Documentation/arm/spear/overview.rst index 1b049be6c84f..1a77f6b213b6 100644 --- a/Documentation/arm/SPEAr/overview.txt +++ b/Documentation/arm/spear/overview.rst @@ -1,5 +1,6 @@ - SPEAr ARM Linux Overview - ========================== +======================== +SPEAr ARM Linux Overview +======================== Introduction ------------ @@ -14,6 +15,7 @@ Introduction Hierarchy in SPEAr is as follows: SPEAr (Platform) + - SPEAr3XX (3XX SOC series, based on ARM9) - SPEAr300 (SOC) - SPEAr300 Evaluation Board @@ -30,17 +32,18 @@ Introduction - SPEAr1340 (SOC) - SPEAr1340 Evaluation Board - Configuration - ------------- +Configuration +------------- A generic configuration is provided for each machine, and can be used as the - default by + default by:: + make spear13xx_defconfig make spear3xx_defconfig make spear6xx_defconfig - Layout - ------ +Layout +------ The common files for multiple machine families (SPEAr3xx, SPEAr6xx and SPEAr13xx) are located in the platform code contained in arch/arm/plat-spear @@ -57,7 +60,7 @@ Introduction support Flattened Device Tree. - Document Author - --------------- +Document Author +--------------- Viresh Kumar <vireshk@kernel.org>, (c) 2010-2012 ST Microelectronics diff --git a/Documentation/arm/sti/overview.txt b/Documentation/arm/sti/overview.rst index 1a4e93d6027f..70743617a74f 100644 --- a/Documentation/arm/sti/overview.txt +++ b/Documentation/arm/sti/overview.rst @@ -1,5 +1,6 @@ - STi ARM Linux Overview - ========================== +====================== +STi ARM Linux Overview +====================== Introduction ------------ @@ -10,15 +11,17 @@ Introduction B2000 and B2020 Reference boards. - configuration - ------------- +configuration +------------- A generic configuration is provided for both STiH415/416, and can be used as the - default by + default by:: + make stih41x_defconfig - Layout - ------ +Layout +------ + All the files for multiple machine families (STiH415, STiH416, and STiG125) are located in the platform code contained in arch/arm/mach-sti @@ -27,7 +30,7 @@ Introduction Device Trees. - Document Author - --------------- +Document Author +--------------- Srinivas Kandagatla <srinivas.kandagatla@st.com>, (c) 2013 ST Microelectronics diff --git a/Documentation/arm/sti/stih407-overview.txt b/Documentation/arm/sti/stih407-overview.rst index 3343f32f58bc..027e75bc7b7c 100644 --- a/Documentation/arm/sti/stih407-overview.txt +++ b/Documentation/arm/sti/stih407-overview.rst @@ -1,5 +1,6 @@ - STiH407 Overview - ================ +================ +STiH407 Overview +================ Introduction ------------ @@ -12,7 +13,7 @@ Introduction - ARM Cortex-A9 1.5 GHz dual core CPU (28nm) - SATA2, USB 3.0, PCIe, Gbit Ethernet - Document Author - --------------- +Document Author +--------------- Maxime Coquelin <maxime.coquelin@st.com>, (c) 2014 ST Microelectronics diff --git a/Documentation/arm/sti/stih415-overview.txt b/Documentation/arm/sti/stih415-overview.rst index 1383e33f265d..b67452d610c4 100644 --- a/Documentation/arm/sti/stih415-overview.txt +++ b/Documentation/arm/sti/stih415-overview.rst @@ -1,5 +1,6 @@ - STiH415 Overview - ================ +================ +STiH415 Overview +================ Introduction ------------ @@ -7,6 +8,7 @@ Introduction The STiH415 is the next generation of HD, AVC set-top box processors for satellite, cable, terrestrial and IP-STB markets. - Features + Features: + - ARM Cortex-A9 1.0 GHz, dual-core CPU - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2 diff --git a/Documentation/arm/sti/stih416-overview.txt b/Documentation/arm/sti/stih416-overview.rst index 558444c201c6..93f17d74d8db 100644 --- a/Documentation/arm/sti/stih416-overview.txt +++ b/Documentation/arm/sti/stih416-overview.rst @@ -1,5 +1,6 @@ - STiH416 Overview - ================ +================ +STiH416 Overview +================ Introduction ------------ diff --git a/Documentation/arm/sti/stih418-overview.txt b/Documentation/arm/sti/stih418-overview.rst index 1cd8fc80646d..b563c1f4fe5a 100644 --- a/Documentation/arm/sti/stih418-overview.txt +++ b/Documentation/arm/sti/stih418-overview.rst @@ -1,5 +1,6 @@ - STiH418 Overview - ================ +================ +STiH418 Overview +================ Introduction ------------ @@ -14,7 +15,7 @@ Introduction - HEVC L5.1 Main 10 - VP9 - Document Author - --------------- +Document Author +--------------- Maxime Coquelin <maxime.coquelin@st.com>, (c) 2015 ST Microelectronics diff --git a/Documentation/arm/stm32/overview.rst b/Documentation/arm/stm32/overview.rst index f7e734153860..85cfc8410798 100644 --- a/Documentation/arm/stm32/overview.rst +++ b/Documentation/arm/stm32/overview.rst @@ -1,5 +1,3 @@ -:orphan: - ======================== STM32 ARM Linux Overview ======================== diff --git a/Documentation/arm/stm32/stm32f429-overview.rst b/Documentation/arm/stm32/stm32f429-overview.rst index 65bbb1c3b423..a7ebe8ea6697 100644 --- a/Documentation/arm/stm32/stm32f429-overview.rst +++ b/Documentation/arm/stm32/stm32f429-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32F429 Overview ================== @@ -23,6 +22,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F429_) .. _STM32F429: http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1577/LN1806?ecmp=stm32f429-439_pron_pr-ces2014_nov2013 -:Authors: - -Maxime Coquelin <mcoquelin.stm32@gmail.com> +:Authors: Maxime Coquelin <mcoquelin.stm32@gmail.com> diff --git a/Documentation/arm/stm32/stm32f746-overview.rst b/Documentation/arm/stm32/stm32f746-overview.rst index 42d593085015..78befddc7740 100644 --- a/Documentation/arm/stm32/stm32f746-overview.rst +++ b/Documentation/arm/stm32/stm32f746-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32F746 Overview ================== @@ -30,6 +29,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F746_) .. _STM32F746: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32f7-series/stm32f7x6/stm32f746ng.html -:Authors: - -Alexandre Torgue <alexandre.torgue@st.com> +:Authors: Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm/stm32/stm32f769-overview.rst b/Documentation/arm/stm32/stm32f769-overview.rst index f6adac862b17..e482980ddf21 100644 --- a/Documentation/arm/stm32/stm32f769-overview.rst +++ b/Documentation/arm/stm32/stm32f769-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32F769 Overview ================== @@ -32,6 +31,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F769_) .. _STM32F769: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f7-series/stm32f7x9/stm32f769ni.html -:Authors: - -Alexandre Torgue <alexandre.torgue@st.com> +:Authors: Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm/stm32/stm32h743-overview.rst b/Documentation/arm/stm32/stm32h743-overview.rst index c525835e7473..4e15f1a42730 100644 --- a/Documentation/arm/stm32/stm32h743-overview.rst +++ b/Documentation/arm/stm32/stm32h743-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32H743 Overview ================== @@ -31,6 +30,4 @@ Datasheet and reference manual are publicly available on ST website (STM32H743_) .. _STM32H743: http://www.st.com/en/microcontrollers/stm32h7x3.html?querycriteria=productId=LN2033 -:Authors: - -Alexandre Torgue <alexandre.torgue@st.com> +:Authors: Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm/stm32/stm32mp157-overview.rst b/Documentation/arm/stm32/stm32mp157-overview.rst index 2c52cd020601..f62fdc8e7d8d 100644 --- a/Documentation/arm/stm32/stm32mp157-overview.rst +++ b/Documentation/arm/stm32/stm32mp157-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +=================== STM32MP157 Overview =================== diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi.rst index f8efc21998bf..b037428aee98 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi.rst @@ -1,3 +1,4 @@ +================== ARM Allwinner SoCs ================== @@ -10,93 +11,140 @@ SunXi family Linux kernel mach directory: arch/arm/mach-sunxi Flavors: + * ARM926 based SoCs - Allwinner F20 (sun3i) - + Not Supported + + * Not Supported * ARM Cortex-A8 based SoCs - Allwinner A10 (sun4i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A10/A10%20Datasheet%20-%20v1.21%20%282012-04-06%29.pdf - + User Manual + * User Manual + http://dl.linux-sunxi.org/A10/A10%20User%20Manual%20-%20v1.20%20%282012-04-09%2c%20DECRYPTED%29.pdf - Allwinner A10s (sun5i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A10s/A10s%20Datasheet%20-%20v1.20%20%282012-03-27%29.pdf - Allwinner A13 / R8 (sun5i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A13/A13%20Datasheet%20-%20v1.12%20%282012-03-29%29.pdf - + User Manual + * User Manual + http://dl.linux-sunxi.org/A13/A13%20User%20Manual%20-%20v1.2%20%282013-01-08%29.pdf - Next Thing Co GR8 (sun5i) * Single ARM Cortex-A7 based SoCs - Allwinner V3s (sun8i) - + Datasheet + + * Datasheet + http://linux-sunxi.org/File:Allwinner_V3s_Datasheet_V1.0.pdf * Dual ARM Cortex-A7 based SoCs - Allwinner A20 (sun7i) - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf - Allwinner A23 (sun8i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A23/A23%20User%20Manual%20V1.0%2020130830.pdf * Quad ARM Cortex-A7 based SoCs - Allwinner A31 (sun6i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf - Allwinner A31s (sun6i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20User%20Manual%20%20V1.0%2020130322.pdf - Allwinner A33 (sun8i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A33/A33%20Datasheet%20release%201.1.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A33/A33%20user%20manual%20release%201.1.pdf - Allwinner H2+ (sun8i) - + No document available now, but is known to be working properly with + + * No document available now, but is known to be working properly with H3 drivers and memory map. - Allwinner H3 (sun8i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/H3/Allwinner_H3_Datasheet_V1.0.pdf - Allwinner R40 (sun8i) - + Datasheet + + * Datasheet + https://github.com/tinalinux/docs/raw/r40-v1.y/R40_Datasheet_V1.0.pdf - + User Manual + + * User Manual + https://github.com/tinalinux/docs/raw/r40-v1.y/Allwinner_R40_User_Manual_V1.0.pdf * Quad ARM Cortex-A15, Quad ARM Cortex-A7 based SoCs - Allwinner A80 - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf * Octa ARM Cortex-A7 based SoCs - Allwinner A83T - + Datasheet + + * Datasheet + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf - + User Manual + + * User Manual + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_User_Manual_v1.5.1_20150513.pdf * Quad ARM Cortex-A53 based SoCs - Allwinner A64 - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf diff --git a/Documentation/arm/sunxi/clocks.txt b/Documentation/arm/sunxi/clocks.rst index e09a88aa3136..23bd03f3e21f 100644 --- a/Documentation/arm/sunxi/clocks.txt +++ b/Documentation/arm/sunxi/clocks.rst @@ -1,3 +1,4 @@ +======================================================= Frequently asked questions about the sunxi clock system ======================================================= @@ -12,7 +13,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated steps, one can gate it and keep the system running. Consider this simplified suspend example: - While the system is operational, you would see something like + While the system is operational, you would see something like:: 24MHz 32kHz | @@ -23,7 +24,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated [CPU] When you are about to suspend, you switch the CPU Mux to the 32kHz - oscillator: + oscillator:: 24Mhz 32kHz | | @@ -33,7 +34,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated | [CPU] - Finally you can gate the main oscillator + Finally you can gate the main oscillator:: 32kHz | diff --git a/Documentation/arm/swp_emulation b/Documentation/arm/swp_emulation.rst index af903d22fd93..6a608a9c3715 100644 --- a/Documentation/arm/swp_emulation +++ b/Documentation/arm/swp_emulation.rst @@ -11,17 +11,17 @@ sequence. If a memory access fault (an abort) occurs, a segmentation fault is signalled to the triggering process. /proc/cpu/swp_emulation holds some statistics/information, including the PID of -the last process to trigger the emulation to be invocated. For example: ---- -Emulated SWP: 12 -Emulated SWPB: 0 -Aborted SWP{B}: 1 -Last process: 314 ---- +the last process to trigger the emulation to be invocated. For example:: -NOTE: when accessing uncached shared regions, LDREX/STREX rely on an external -transaction monitoring block called a global monitor to maintain update -atomicity. If your system does not implement a global monitor, this option can -cause programs that perform SWP operations to uncached memory to deadlock, as -the STREX operation will always fail. + Emulated SWP: 12 + Emulated SWPB: 0 + Aborted SWP{B}: 1 + Last process: 314 + +NOTE: + when accessing uncached shared regions, LDREX/STREX rely on an external + transaction monitoring block called a global monitor to maintain update + atomicity. If your system does not implement a global monitor, this option can + cause programs that perform SWP operations to uncached memory to deadlock, as + the STREX operation will always fail. diff --git a/Documentation/arm/tcm.txt b/Documentation/arm/tcm.rst index 7c15871c1885..effd9c7bc968 100644 --- a/Documentation/arm/tcm.txt +++ b/Documentation/arm/tcm.rst @@ -1,5 +1,7 @@ +================================================== ARM TCM (Tightly-Coupled Memory) handling in Linux ----- +================================================== + Written by Linus Walleij <linus.walleij@stericsson.com> Some ARM SoC:s have a so-called TCM (Tightly-Coupled Memory). @@ -85,46 +87,50 @@ to have functions called locally inside the TCM without wasting space, there is also the __tcmlocalfunc prefix that will make the call relative. -Variables to go into dtcm can be tagged like this: -int __tcmdata foo; +Variables to go into dtcm can be tagged like this:: + + int __tcmdata foo; + +Constants can be tagged like this:: -Constants can be tagged like this: -int __tcmconst foo; + int __tcmconst foo; + +To put assembler into TCM just use:: + + .section ".tcm.text" or .section ".tcm.data" -To put assembler into TCM just use -.section ".tcm.text" or .section ".tcm.data" respectively. -Example code: +Example code:: -#include <asm/tcm.h> + #include <asm/tcm.h> -/* Uninitialized data */ -static u32 __tcmdata tcmvar; -/* Initialized data */ -static u32 __tcmdata tcmassigned = 0x2BADBABEU; -/* Constant */ -static const u32 __tcmconst tcmconst = 0xCAFEBABEU; + /* Uninitialized data */ + static u32 __tcmdata tcmvar; + /* Initialized data */ + static u32 __tcmdata tcmassigned = 0x2BADBABEU; + /* Constant */ + static const u32 __tcmconst tcmconst = 0xCAFEBABEU; -static void __tcmlocalfunc tcm_to_tcm(void) -{ + static void __tcmlocalfunc tcm_to_tcm(void) + { int i; for (i = 0; i < 100; i++) tcmvar ++; -} + } -static void __tcmfunc hello_tcm(void) -{ + static void __tcmfunc hello_tcm(void) + { /* Some abstract code that runs in ITCM */ int i; for (i = 0; i < 100; i++) { tcmvar ++; } tcm_to_tcm(); -} + } -static void __init test_tcm(void) -{ + static void __init test_tcm(void) + { u32 *tcmem; int i; @@ -152,4 +158,4 @@ static void __init test_tcm(void) printk("TCM tcmem[%d] = %08x\n", i, tcmem[i]); tcm_free(tcmem, 20); } -} + } diff --git a/Documentation/arm/uefi.txt b/Documentation/arm/uefi.rst index 6543a0adea8a..f868330df6be 100644 --- a/Documentation/arm/uefi.txt +++ b/Documentation/arm/uefi.rst @@ -1,3 +1,7 @@ +================================================ +The Unified Extensible Firmware Interface (UEFI) +================================================ + UEFI, the Unified Extensible Firmware Interface, is a specification governing the behaviours of compatible firmware interfaces. It is maintained by the UEFI Forum - http://www.uefi.org/. @@ -11,11 +15,13 @@ UEFI support in Linux ===================== Booting on a platform with firmware compliant with the UEFI specification makes it possible for the kernel to support additional features: + - UEFI Runtime Services - Retrieving various configuration information through the standardised interface of UEFI configuration tables. (ACPI, SMBIOS, ...) For actually enabling [U]EFI support, enable: + - CONFIG_EFI=y - CONFIG_EFI_VARS=y or m @@ -42,19 +48,20 @@ Instead, the kernel reads the UEFI memory map. The stub populates the FDT /chosen node with (and the kernel scans for) the following parameters: -________________________________________________________________________________ -Name | Size | Description -================================================================================ -linux,uefi-system-table | 64-bit | Physical address of the UEFI System Table. --------------------------------------------------------------------------------- -linux,uefi-mmap-start | 64-bit | Physical address of the UEFI memory map, - | | populated by the UEFI GetMemoryMap() call. --------------------------------------------------------------------------------- -linux,uefi-mmap-size | 32-bit | Size in bytes of the UEFI memory map - | | pointed to in previous entry. --------------------------------------------------------------------------------- -linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI - | | memory map. --------------------------------------------------------------------------------- -linux,uefi-mmap-desc-ver | 32-bit | Version of the mmap descriptor format. --------------------------------------------------------------------------------- + +========================== ====== =========================================== +Name Size Description +========================== ====== =========================================== +linux,uefi-system-table 64-bit Physical address of the UEFI System Table. + +linux,uefi-mmap-start 64-bit Physical address of the UEFI memory map, + populated by the UEFI GetMemoryMap() call. + +linux,uefi-mmap-size 32-bit Size in bytes of the UEFI memory map + pointed to in previous entry. + +linux,uefi-mmap-desc-size 32-bit Size in bytes of each entry in the UEFI + memory map. + +linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format. +========================== ====== =========================================== diff --git a/Documentation/arm/VFP/release-notes.txt b/Documentation/arm/vfp/release-notes.rst index 28a2795705ca..c6b04937cee3 100644 --- a/Documentation/arm/VFP/release-notes.txt +++ b/Documentation/arm/vfp/release-notes.rst @@ -1,7 +1,9 @@ +=============================================== Release notes for Linux Kernel VFP support code ------------------------------------------------ +=============================================== Date: 20 May 2004 + Author: Russell King This is the first release of the Linux Kernel VFP support code. It diff --git a/Documentation/arm/vlocks.txt b/Documentation/arm/vlocks.rst index 45731672c564..a40a1742110b 100644 --- a/Documentation/arm/vlocks.txt +++ b/Documentation/arm/vlocks.rst @@ -1,3 +1,4 @@ +====================================== vlocks for Bare-Metal Mutual Exclusion ====================================== @@ -26,7 +27,7 @@ started yet. Algorithm --------- -The easiest way to explain the vlocks algorithm is with some pseudo-code: +The easiest way to explain the vlocks algorithm is with some pseudo-code:: int currently_voting[NR_CPUS] = { 0, }; @@ -93,7 +94,7 @@ Features and limitations number of CPUs. vlocks can be cascaded in a voting hierarchy to permit better scaling - if necessary, as in the following hypothetical example for 4096 CPUs: + if necessary, as in the following hypothetical example for 4096 CPUs:: /* first level: local election */ my_town = towns[(this_cpu >> 4) & 0xf]; @@ -127,12 +128,12 @@ the basic algorithm: reduces the number of round-trips required to external memory. In the ARM implementation, this means that we can use a single load - and comparison: + and comparison:: LDR Rt, [Rn] CMP Rt, #0 - ...in place of code equivalent to: + ...in place of code equivalent to:: LDRB Rt, [Rn] CMP Rt, #0 diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst index 018b7836ecb7..96b696ba4e6c 100644 --- a/Documentation/arm64/index.rst +++ b/Documentation/arm64/index.rst @@ -1,5 +1,3 @@ -:orphan: - ================== ARM64 Architecture ================== diff --git a/Documentation/backlight/lp855x-driver.txt b/Documentation/backlight/lp855x-driver.txt deleted file mode 100644 index 01bce243d3d7..000000000000 --- a/Documentation/backlight/lp855x-driver.txt +++ /dev/null @@ -1,66 +0,0 @@ -Kernel driver lp855x -==================== - -Backlight driver for LP855x ICs - -Supported chips: - Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and - LP8557 - -Author: Milo(Woogyom) Kim <milo.kim@ti.com> - -Description ------------ - -* Brightness control - -Brightness can be controlled by the pwm input or the i2c command. -The lp855x driver supports both cases. - -* Device attributes - -1) bl_ctl_mode -Backlight control mode. -Value : pwm based or register based - -2) chip_id -The lp855x chip id. -Value : lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557 - -Platform data for lp855x ------------------------- - -For supporting platform specific data, the lp855x platform data can be used. - -* name : Backlight driver name. If it is not defined, default name is set. -* device_control : Value of DEVICE CONTROL register. -* initial_brightness : Initial value of backlight brightness. -* period_ns : Platform specific PWM period value. unit is nano. - Only valid when brightness is pwm input mode. -* size_program : Total size of lp855x_rom_data. -* rom_data : List of new eeprom/eprom registers. - -example 1) lp8552 platform data : i2c register mode with new eeprom data - -#define EEPROM_A5_ADDR 0xA5 -#define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */ - -static struct lp855x_rom_data lp8552_eeprom_arr[] = { - {EEPROM_A5_ADDR, EEPROM_A5_VAL}, -}; - -static struct lp855x_platform_data lp8552_pdata = { - .name = "lcd-bl", - .device_control = I2C_CONFIG(LP8552), - .initial_brightness = INITIAL_BRT, - .size_program = ARRAY_SIZE(lp8552_eeprom_arr), - .rom_data = lp8552_eeprom_arr, -}; - -example 2) lp8556 platform data : pwm input mode with default rom data - -static struct lp855x_platform_data lp8556_pdata = { - .device_control = PWM_CONFIG(LP8556), - .initial_brightness = INITIAL_BRT, - .period_ns = 1000000, -}; diff --git a/Documentation/block/bfq-iosched.txt b/Documentation/block/bfq-iosched.rst index bbd6eb5bbb07..0d237d402860 100644 --- a/Documentation/block/bfq-iosched.txt +++ b/Documentation/block/bfq-iosched.rst @@ -1,9 +1,11 @@ +========================== BFQ (Budget Fair Queueing) ========================== BFQ is a proportional-share I/O scheduler, with some extra low-latency capabilities. In addition to cgroups support (blkio or io controllers), BFQ's main features are: + - BFQ guarantees a high system and application responsiveness, and a low latency for time-sensitive applications, such as audio or video players; @@ -55,18 +57,18 @@ sustainable throughputs, on the same systems as above: BFQ works for multi-queue devices too. -The table of contents follow. Impatients can just jump to Section 3. +.. The table of contents follow. Impatients can just jump to Section 3. -CONTENTS +.. CONTENTS -1. When may BFQ be useful? - 1-1 Personal systems - 1-2 Server systems -2. How does BFQ work? -3. What are BFQ's tunables and how to properly configure BFQ? -4. BFQ group scheduling - 4-1 Service guarantees provided - 4-2 Interface + 1. When may BFQ be useful? + 1-1 Personal systems + 1-2 Server systems + 2. How does BFQ work? + 3. What are BFQ's tunables and how to properly configure BFQ? + 4. BFQ group scheduling + 4-1 Service guarantees provided + 4-2 Interface 1. When may BFQ be useful? ========================== @@ -77,17 +79,20 @@ BFQ provides the following benefits on personal and server systems. -------------------- Low latency for interactive applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Regardless of the actual background workload, BFQ guarantees that, for interactive tasks, the storage device is virtually as responsive as if it was idle. For example, even if one or more of the following background workloads are being executed: + - one or more large files are being read, written or copied, - a tree of source files is being compiled, - one or more virtual machines are performing I/O, - a software update is in progress, - indexing daemons are scanning filesystems and updating their databases, + starting an application or loading a file from within an application takes about the same time as if the storage device was idle. As a comparison, with CFQ, NOOP or DEADLINE, and in the same conditions, @@ -95,13 +100,14 @@ applications experience high latencies, or even become unresponsive until the background workload terminates (also on SSDs). Low latency for soft real-time applications - +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Also soft real-time applications, such as audio and video players/streamers, enjoy a low latency and a low drop rate, regardless of the background I/O workload. As a consequence, these applications do not suffer from almost any glitch due to the background workload. Higher speed for code-development tasks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If some additional workload happens to be executed in parallel, then BFQ executes the I/O-related components of typical code-development @@ -109,6 +115,7 @@ tasks (compilation, checkout, merge, ...) much more quickly than CFQ, NOOP or DEADLINE. High throughput +^^^^^^^^^^^^^^^ On hard disks, BFQ achieves up to 30% higher throughput than CFQ, and up to 150% higher throughput than DEADLINE and NOOP, with all the @@ -117,6 +124,7 @@ and with all the workloads on flash-based devices, BFQ achieves, instead, about the same throughput as the other schedulers. Strong fairness, bandwidth and delay guarantees +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ BFQ distributes the device throughput, and not just the device time, among I/O-bound applications in proportion their weights, with any @@ -133,15 +141,15 @@ Most benefits for server systems follow from the same service properties as above. In particular, regardless of whether additional, possibly heavy workloads are being served, BFQ guarantees: -. audio and video-streaming with zero or very low jitter and drop +* audio and video-streaming with zero or very low jitter and drop rate; -. fast retrieval of WEB pages and embedded objects; +* fast retrieval of WEB pages and embedded objects; -. real-time recording of data in live-dumping applications (e.g., +* real-time recording of data in live-dumping applications (e.g., packet logging); -. responsiveness in local and remote access to a server. +* responsiveness in local and remote access to a server. 2. How does BFQ work? @@ -151,7 +159,7 @@ BFQ is a proportional-share I/O scheduler, whose general structure, plus a lot of code, are borrowed from CFQ. - Each process doing I/O on a device is associated with a weight and a - (bfq_)queue. + `(bfq_)queue`. - BFQ grants exclusive access to the device, for a while, to one queue (process) at a time, and implements this service model by @@ -539,12 +547,13 @@ As for cgroups-v1 (blkio controller), the exact set of stat files created, and kept up-to-date by bfq, depends on whether CONFIG_BFQ_CGROUP_DEBUG is set. If it is set, then bfq creates all the stat files documented in -Documentation/cgroup-v1/blkio-controller.rst. If, instead, -CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files -blkio.bfq.io_service_bytes -blkio.bfq.io_service_bytes_recursive -blkio.bfq.io_serviced -blkio.bfq.io_serviced_recursive +Documentation/admin-guide/cgroup-v1/blkio-controller.rst. If, instead, +CONFIG_BFQ_CGROUP_DEBUG is not set, then bfq creates only the files:: + + blkio.bfq.io_service_bytes + blkio.bfq.io_service_bytes_recursive + blkio.bfq.io_serviced + blkio.bfq.io_serviced_recursive The value of CONFIG_BFQ_CGROUP_DEBUG greatly influences the maximum throughput sustainable with bfq, because updating the blkio.bfq.* @@ -567,17 +576,22 @@ weight of the queues associated with interactive and soft real-time applications. Unset this tunable if you need/want to control weights. -[1] P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O +[1] + P. Valente, A. Avanzini, "Evolution of the BFQ Storage I/O Scheduler", Proceedings of the First Workshop on Mobile System Technologies (MST-2015), May 2015. + http://algogroup.unimore.it/people/paolo/disk_sched/mst-2015.pdf -[2] P. Valente and M. Andreolini, "Improving Application +[2] + P. Valente and M. Andreolini, "Improving Application Responsiveness with the BFQ Disk I/O Scheduler", Proceedings of the 5th Annual International Systems and Storage Conference (SYSTOR '12), June 2012. + Slightly extended version: - http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite- - results.pdf -[3] https://github.com/Algodev-github/S + http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite-results.pdf + +[3] + https://github.com/Algodev-github/S diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.rst index 31c177663ed5..b964796ec9c7 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.rst @@ -1,15 +1,25 @@ - Notes on the Generic Block Layer Rewrite in Linux 2.5 - ===================================================== +===================================================== +Notes on the Generic Block Layer Rewrite in Linux 2.5 +===================================================== + +.. note:: + + It seems that there are lot of outdated stuff here. This seems + to be written somewhat as a task list. Yet, eventually, something + here might still be useful. Notes Written on Jan 15, 2002: - Jens Axboe <jens.axboe@oracle.com> - Suparna Bhattacharya <suparna@in.ibm.com> + + - Jens Axboe <jens.axboe@oracle.com> + - Suparna Bhattacharya <suparna@in.ibm.com> Last Updated May 2, 2002 + September 2003: Updated I/O Scheduler portions - Nick Piggin <npiggin@kernel.dk> + - Nick Piggin <npiggin@kernel.dk> -Introduction: +Introduction +============ These are some notes describing some aspects of the 2.5 block layer in the context of the bio rewrite. The idea is to bring out some of the key @@ -17,11 +27,11 @@ changes and a glimpse of the rationale behind those changes. Please mail corrections & suggestions to suparna@in.ibm.com. -Credits: ---------- +Credits +======= 2.5 bio rewrite: - Jens Axboe <jens.axboe@oracle.com> + - Jens Axboe <jens.axboe@oracle.com> Many aspects of the generic block layer redesign were driven by and evolved over discussions, prior patches and the collective experience of several @@ -29,62 +39,63 @@ people. See sections 8 and 9 for a list of some related references. The following people helped with review comments and inputs for this document: - Christoph Hellwig <hch@infradead.org> - Arjan van de Ven <arjanv@redhat.com> - Randy Dunlap <rdunlap@xenotime.net> - Andre Hedrick <andre@linux-ide.org> + + - Christoph Hellwig <hch@infradead.org> + - Arjan van de Ven <arjanv@redhat.com> + - Randy Dunlap <rdunlap@xenotime.net> + - Andre Hedrick <andre@linux-ide.org> The following people helped with fixes/contributions to the bio patches while it was still work-in-progress: - David S. Miller <davem@redhat.com> + - David S. Miller <davem@redhat.com> -Description of Contents: ------------------------- -1. Scope for tuning of logic to various needs - 1.1 Tuning based on device or low level driver capabilities +.. Description of Contents: + + 1. Scope for tuning of logic to various needs + 1.1 Tuning based on device or low level driver capabilities - Per-queue parameters - Highmem I/O support - I/O scheduler modularization - 1.2 Tuning based on high level requirements/capabilities + 1.2 Tuning based on high level requirements/capabilities 1.2.1 Request Priority/Latency - 1.3 Direct access/bypass to lower layers for diagnostics and special - device operations + 1.3 Direct access/bypass to lower layers for diagnostics and special + device operations 1.3.1 Pre-built commands -2. New flexible and generic but minimalist i/o structure or descriptor - (instead of using buffer heads at the i/o layer) - 2.1 Requirements/Goals addressed - 2.2 The bio struct in detail (multi-page io unit) - 2.3 Changes in the request structure -3. Using bios - 3.1 Setup/teardown (allocation, splitting) - 3.2 Generic bio helper routines - 3.2.1 Traversing segments and completion units in a request - 3.2.2 Setting up DMA scatterlists - 3.2.3 I/O completion - 3.2.4 Implications for drivers that do not interpret bios (don't handle - multiple segments) - 3.3 I/O submission -4. The I/O scheduler -5. Scalability related changes - 5.1 Granular locking: Removal of io_request_lock - 5.2 Prepare for transition to 64 bit sector_t -6. Other Changes/Implications - 6.1 Partition re-mapping handled by the generic block layer -7. A few tips on migration of older drivers -8. A list of prior/related/impacted patches/ideas -9. Other References/Discussion Threads + 2. New flexible and generic but minimalist i/o structure or descriptor + (instead of using buffer heads at the i/o layer) + 2.1 Requirements/Goals addressed + 2.2 The bio struct in detail (multi-page io unit) + 2.3 Changes in the request structure + 3. Using bios + 3.1 Setup/teardown (allocation, splitting) + 3.2 Generic bio helper routines + 3.2.1 Traversing segments and completion units in a request + 3.2.2 Setting up DMA scatterlists + 3.2.3 I/O completion + 3.2.4 Implications for drivers that do not interpret bios (don't handle + multiple segments) + 3.3 I/O submission + 4. The I/O scheduler + 5. Scalability related changes + 5.1 Granular locking: Removal of io_request_lock + 5.2 Prepare for transition to 64 bit sector_t + 6. Other Changes/Implications + 6.1 Partition re-mapping handled by the generic block layer + 7. A few tips on migration of older drivers + 8. A list of prior/related/impacted patches/ideas + 9. Other References/Discussion Threads ---------------------------------------------------------------------------- Bio Notes --------- +========= Let us discuss the changes in the context of how some overall goals for the block layer are addressed. 1. Scope for tuning the generic logic to satisfy various requirements +===================================================================== The block layer design supports adaptable abstractions to handle common processing with the ability to tune the logic to an appropriate extent @@ -97,6 +108,7 @@ and application/middleware software designed to take advantage of these capabilities. 1.1 Tuning based on low level device / driver capabilities +---------------------------------------------------------- Sophisticated devices with large built-in caches, intelligent i/o scheduling optimizations, high memory DMA support, etc may find some of the @@ -133,12 +145,12 @@ Some new queue property settings: Sets two variables that limit the size of the request. - The request queue's max_sectors, which is a soft size in - units of 512 byte sectors, and could be dynamically varied - by the core kernel. + units of 512 byte sectors, and could be dynamically varied + by the core kernel. - The request queue's max_hw_sectors, which is a hard limit - and reflects the maximum size request a driver can handle - in units of 512 byte sectors. + and reflects the maximum size request a driver can handle + in units of 512 byte sectors. The default for both max_sectors and max_hw_sectors is 255. The upper limit of max_sectors is 1024. @@ -161,8 +173,8 @@ Some new queue property settings: New queue flags: - QUEUE_FLAG_CLUSTER (see 3.2.2) - QUEUE_FLAG_QUEUED (see 3.2.4) + - QUEUE_FLAG_CLUSTER (see 3.2.2) + - QUEUE_FLAG_QUEUED (see 3.2.4) ii. High-mem i/o capabilities are now considered the default @@ -234,6 +246,7 @@ I/O scheduler wrappers are to be used instead of accessing the queue directly. See section 4. The I/O scheduler for details. 1.2 Tuning Based on High level code capabilities +------------------------------------------------ i. Application capabilities for raw i/o @@ -258,9 +271,11 @@ would need an additional mechanism either via open flags or ioctls, or some other upper level mechanism to communicate such settings to block. 1.2.1 Request Priority/Latency +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Todo/Under discussion: -Arjan's proposed request priority scheme allows higher levels some broad +Todo/Under discussion:: + + Arjan's proposed request priority scheme allows higher levels some broad control (high/med/low) over the priority of an i/o request vs other pending requests in the queue. For example it allows reads for bringing in an executable page on demand to be given a higher priority over pending write @@ -272,7 +287,9 @@ Arjan's proposed request priority scheme allows higher levels some broad 1.3 Direct Access to Low level Device/Driver Capabilities (Bypass mode) - (e.g Diagnostics, Systems Management) +----------------------------------------------------------------------- + +(e.g Diagnostics, Systems Management) There are situations where high-level code needs to have direct access to the low level device capabilities or requires the ability to issue commands @@ -308,28 +325,32 @@ involved. In the latter case, the driver would modify and manage the request->buffer, request->sector and request->nr_sectors or request->current_nr_sectors fields itself rather than using the block layer end_request or end_that_request_first completion interfaces. -(See 2.3 or Documentation/block/request.txt for a brief explanation of +(See 2.3 or Documentation/block/request.rst for a brief explanation of the request structure fields) -[TBD: end_that_request_last should be usable even in this case; -Perhaps an end_that_direct_request_first routine could be implemented to make -handling direct requests easier for such drivers; Also for drivers that -expect bios, a helper function could be provided for setting up a bio -corresponding to a data buffer] - -<JENS: I dont understand the above, why is end_that_request_first() not -usable? Or _last for that matter. I must be missing something> -<SUP: What I meant here was that if the request doesn't have a bio, then - end_that_request_first doesn't modify nr_sectors or current_nr_sectors, - and hence can't be used for advancing request state settings on the - completion of partial transfers. The driver has to modify these fields - directly by hand. - This is because end_that_request_first only iterates over the bio list, - and always returns 0 if there are none associated with the request. - _last works OK in this case, and is not a problem, as I mentioned earlier -> +:: + + [TBD: end_that_request_last should be usable even in this case; + Perhaps an end_that_direct_request_first routine could be implemented to make + handling direct requests easier for such drivers; Also for drivers that + expect bios, a helper function could be provided for setting up a bio + corresponding to a data buffer] + + <JENS: I dont understand the above, why is end_that_request_first() not + usable? Or _last for that matter. I must be missing something> + + <SUP: What I meant here was that if the request doesn't have a bio, then + end_that_request_first doesn't modify nr_sectors or current_nr_sectors, + and hence can't be used for advancing request state settings on the + completion of partial transfers. The driver has to modify these fields + directly by hand. + This is because end_that_request_first only iterates over the bio list, + and always returns 0 if there are none associated with the request. + _last works OK in this case, and is not a problem, as I mentioned earlier + > 1.3.1 Pre-built Commands +^^^^^^^^^^^^^^^^^^^^^^^^ A request can be created with a pre-built custom command to be sent directly to the device. The cmd block in the request structure has room for filling @@ -360,9 +381,11 @@ Aside: the pre-builder hook can be invoked there. -2. Flexible and generic but minimalist i/o structure/descriptor. +2. Flexible and generic but minimalist i/o structure/descriptor +=============================================================== 2.1 Reason for a new structure and requirements addressed +--------------------------------------------------------- Prior to 2.5, buffer heads were used as the unit of i/o at the generic block layer, and the low level request structure was associated with a chain of @@ -378,26 +401,26 @@ which were generated for each such chunk. The following were some of the goals and expectations considered in the redesign of the block i/o data structure in 2.5. -i. Should be appropriate as a descriptor for both raw and buffered i/o - +1. Should be appropriate as a descriptor for both raw and buffered i/o - avoid cache related fields which are irrelevant in the direct/page i/o path, or filesystem block size alignment restrictions which may not be relevant for raw i/o. -ii. Ability to represent high-memory buffers (which do not have a virtual +2. Ability to represent high-memory buffers (which do not have a virtual address mapping in kernel address space). -iii.Ability to represent large i/os w/o unnecessarily breaking them up (i.e +3. Ability to represent large i/os w/o unnecessarily breaking them up (i.e greater than PAGE_SIZE chunks in one shot) -iv. At the same time, ability to retain independent identity of i/os from +4. At the same time, ability to retain independent identity of i/os from different sources or i/o units requiring individual completion (e.g. for latency reasons) -v. Ability to represent an i/o involving multiple physical memory segments +5. Ability to represent an i/o involving multiple physical memory segments (including non-page aligned page fragments, as specified via readv/writev) without unnecessarily breaking it up, if the underlying device is capable of handling it. -vi. Preferably should be based on a memory descriptor structure that can be +6. Preferably should be based on a memory descriptor structure that can be passed around different types of subsystems or layers, maybe even networking, without duplication or extra copies of data/descriptor fields themselves in the process -vii.Ability to handle the possibility of splits/merges as the structure passes +7. Ability to handle the possibility of splits/merges as the structure passes through layered drivers (lvm, md, evms), with minimal overhead. The solution was to define a new structure (bio) for the block layer, @@ -408,6 +431,7 @@ bh structure for buffered i/o, and in the case of raw/direct i/o kiobufs are mapped to bio structures. 2.2 The bio struct +------------------ The bio structure uses a vector representation pointing to an array of tuples of <page, offset, len> to describe the i/o buffer, and has various other @@ -417,16 +441,18 @@ performing the i/o. Notice that this representation means that a bio has no virtual address mapping at all (unlike buffer heads). -struct bio_vec { +:: + + struct bio_vec { struct page *bv_page; unsigned short bv_len; unsigned short bv_offset; -}; + }; -/* - * main unit of I/O for the block layer and lower layers (ie drivers) - */ -struct bio { + /* + * main unit of I/O for the block layer and lower layers (ie drivers) + */ + struct bio { struct bio *bi_next; /* request queue link */ struct block_device *bi_bdev; /* target device */ unsigned long bi_flags; /* status, command, etc */ @@ -443,7 +469,7 @@ struct bio { bio_end_io_t *bi_end_io; /* bi_end_io (bio) */ atomic_t bi_cnt; /* pin count: free when it hits zero */ void *bi_private; -}; + }; With this multipage bio design: @@ -453,7 +479,7 @@ With this multipage bio design: - Splitting of an i/o request across multiple devices (as in the case of lvm or raid) is achieved by cloning the bio (where the clone points to the same bi_io_vec array, but with the index and size accordingly modified) -- A linked list of bios is used as before for unrelated merges (*) - this +- A linked list of bios is used as before for unrelated merges [#]_ - this avoids reallocs and makes independent completions easier to handle. - Code that traverses the req list can find all the segments of a bio by using rq_for_each_segment. This handles the fact that a request @@ -462,10 +488,12 @@ With this multipage bio design: field to keep track of the next bio_vec entry to process. (e.g a 1MB bio_vec needs to be handled in max 128kB chunks for IDE) [TBD: Should preferably also have a bi_voffset and bi_vlen to avoid modifying - bi_offset an len fields] + bi_offset an len fields] -(*) unrelated merges -- a request ends up containing two or more bios that - didn't originate from the same place. +.. [#] + + unrelated merges -- a request ends up containing two or more bios that + didn't originate from the same place. bi_end_io() i/o callback gets called on i/o completion of the entire bio. @@ -483,10 +511,11 @@ which in turn means that only raw I/O uses it (direct i/o may not work right now). The intent however is to enable clustering of pages etc to become possible. The pagebuf abstraction layer from SGI also uses multi-page bios, but that is currently not included in the stock development kernels. -The same is true of Andrew Morton's work-in-progress multipage bio writeout +The same is true of Andrew Morton's work-in-progress multipage bio writeout and readahead patches. 2.3 Changes in the Request Structure +------------------------------------ The request structure is the structure that gets passed down to low level drivers. The block layer make_request function builds up a request structure, @@ -499,11 +528,11 @@ request structure. Only some relevant fields (mainly those which changed or may be referred to in some of the discussion here) are listed below, not necessarily in the order in which they occur in the structure (see include/linux/blkdev.h) -Refer to Documentation/block/request.txt for details about all the request +Refer to Documentation/block/request.rst for details about all the request structure fields and a quick reference about the layers which are -supposed to use or modify those fields. +supposed to use or modify those fields:: -struct request { + struct request { struct list_head queuelist; /* Not meant to be directly accessed by the driver. Used by q->elv_next_request_fn @@ -548,11 +577,11 @@ struct request { . struct bio *bio, *biotail; /* bio list instead of bh */ struct request_list *rl; -} - + } + See the req_ops and req_flag_bits definitions for an explanation of the various flags available. Some bits are used by the block layer or i/o scheduler. - + The behaviour of the various sector counts are almost the same as before, except that since we have multi-segment bios, current_nr_sectors refers to the numbers of sectors in the current segment being processed which could @@ -578,8 +607,10 @@ a driver needs to be careful about interoperation with the block layer helper functions which the driver uses. (Section 1.3) 3. Using bios +============= 3.1 Setup/Teardown +------------------ There are routines for managing the allocation, and reference counting, and freeing of bios (bio_alloc, bio_get, bio_put). @@ -606,10 +637,13 @@ case of bio, these routines make use of the standard slab allocator. The caller of bio_alloc is expected to taken certain steps to avoid deadlocks, e.g. avoid trying to allocate more memory from the pool while already holding memory obtained from the pool. -[TBD: This is a potential issue, though a rare possibility - in the bounce bio allocation that happens in the current code, since - it ends up allocating a second bio from the same pool while - holding the original bio ] + +:: + + [TBD: This is a potential issue, though a rare possibility + in the bounce bio allocation that happens in the current code, since + it ends up allocating a second bio from the same pool while + holding the original bio ] Memory allocated from the pool should be released back within a limited amount of time (in the case of bio, that would be after the i/o is completed). @@ -635,14 +669,18 @@ same bio_vec_list). This would typically be used for splitting i/o requests in lvm or md. 3.2 Generic bio helper Routines +------------------------------- 3.2.1 Traversing segments and completion units in a request +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The macro rq_for_each_segment() should be used for traversing the bios in the request list (drivers should avoid directly trying to do it themselves). Using these helpers should also make it easier to cope with block changes in the future. +:: + struct req_iterator iter; rq_for_each_segment(bio_vec, rq, iter) /* bio_vec is now current segment */ @@ -653,6 +691,7 @@ which don't make a distinction between segments and completion units would need to be reorganized to support multi-segment bios. 3.2.2 Setting up DMA scatterlists +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The blk_rq_map_sg() helper routine would be used for setting up scatter gather lists from a request, so a driver need not do it on its own. @@ -683,6 +722,7 @@ of physical data segments in a request (i.e. the largest sized scatter list a driver could handle) 3.2.3 I/O completion +^^^^^^^^^^^^^^^^^^^^ The existing generic block layer helper routines end_request, end_that_request_first and end_that_request_last can be used for i/o @@ -691,8 +731,10 @@ request can be kicked of) as before. With the introduction of multi-page bio support, end_that_request_first requires an additional argument indicating the number of sectors completed. -3.2.4 Implications for drivers that do not interpret bios (don't handle - multiple segments) +3.2.4 Implications for drivers that do not interpret bios +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(don't handle multiple segments) Drivers that do not interpret bios e.g those which do not handle multiple segments and do not support i/o into high memory addresses (require bounce @@ -707,15 +749,18 @@ be used if only if the request has come down from block/bio path, not for direct access requests which only specify rq->buffer without a valid rq->bio) 3.3 I/O Submission +------------------ The routine submit_bio() is used to submit a single io. Higher level i/o routines make use of this: (a) Buffered i/o: + The routine submit_bh() invokes submit_bio() on a bio corresponding to the bh, allocating the bio if required. ll_rw_block() uses submit_bh() as before. (b) Kiobuf i/o (for raw/direct i/o): + The ll_rw_kio() routine breaks up the kiobuf into page sized chunks and maps the array to one or more multi-page bios, issuing submit_bio() to perform the i/o on each of these. @@ -738,6 +783,7 @@ Todo/Observation: (c) Page i/o: + Todo/Under discussion: Andrew Morton's multi-page bio patches attempt to issue multi-page @@ -753,6 +799,7 @@ Todo/Under discussion: abstraction, but intended to be as lightweight as possible). (d) Direct access i/o: + Direct access requests that do not contain bios would be submitted differently as discussed earlier in section 1.3. @@ -780,11 +827,13 @@ Aside: 4. The I/O scheduler +==================== + I/O scheduler, a.k.a. elevator, is implemented in two layers. Generic dispatch queue and specific I/O schedulers. Unless stated otherwise, elevator is used to refer to both parts and I/O scheduler to specific I/O schedulers. -Block layer implements generic dispatch queue in block/*.c. +Block layer implements generic dispatch queue in `block/*.c`. The generic dispatch queue is responsible for requeueing, handling non-fs requests and all other subtleties. @@ -802,8 +851,11 @@ doesn't implement a function, the switch does nothing or some minimal house keeping work. 4.1. I/O scheduler API +---------------------- The functions an elevator may implement are: (* are mandatory) + +=============================== ================================================ elevator_merge_fn called to query requests for merge with a bio elevator_merge_req_fn called when two requests get merged. the one @@ -843,11 +895,6 @@ elevator_latter_req_fn These return the request before or after the elevator_completed_req_fn called when a request is completed. -elevator_may_queue_fn returns true if the scheduler wants to allow the - current context to queue a new request even if - it is over the queue limit. This must be used - very carefully!! - elevator_set_req_fn elevator_put_req_fn Must be used to allocate and free any elevator specific storage for a request. @@ -862,8 +909,11 @@ elevator_deactivate_req_fn Called when device driver decides to delay elevator_init_fn* elevator_exit_fn Allocate and free any elevator specific storage for a queue. +=============================== ================================================ 4.2 Request flows seen by I/O schedulers +---------------------------------------- + All requests seen by I/O schedulers strictly follow one of the following three flows. @@ -877,9 +927,12 @@ flows. -> put_req_fn 4.3 I/O scheduler implementation +-------------------------------- + The generic i/o scheduler algorithm attempts to sort/merge/batch requests for optimal disk scan and request servicing performance (based on generic principles and device capabilities), optimized for: + i. improved throughput ii. improved latency iii. better utilization of h/w & CPU time @@ -933,15 +986,19 @@ Aside: a big request from the broken up pieces coming by. 4.4 I/O contexts +---------------- + I/O contexts provide a dynamically allocated per process data area. They may be used in I/O schedulers, and in the block layer (could be used for IO statis, -priorities for example). See *io_context in block/ll_rw_blk.c, and as-iosched.c +priorities for example). See `*io_context` in block/ll_rw_blk.c, and as-iosched.c for an example of usage in an i/o scheduler. 5. Scalability related changes +============================== 5.1 Granular Locking: io_request_lock replaced by a per-queue lock +------------------------------------------------------------------ The global io_request_lock has been removed as of 2.5, to avoid the scalability bottleneck it was causing, and has been replaced by more @@ -956,20 +1013,23 @@ request_fn execution which it means that lots of older drivers should still be SMP safe. Drivers are free to drop the queue lock themselves, if required. Drivers that explicitly used the io_request_lock for serialization need to be modified accordingly. -Usually it's as easy as adding a global lock: +Usually it's as easy as adding a global lock:: static DEFINE_SPINLOCK(my_driver_lock); and passing the address to that lock to blk_init_queue(). 5.2 64 bit sector numbers (sector_t prepares for 64 bit support) +---------------------------------------------------------------- The sector number used in the bio structure has been changed to sector_t, which could be defined as 64 bit in preparation for 64 bit sector support. 6. Other Changes/Implications +============================= 6.1 Partition re-mapping handled by the generic block layer +----------------------------------------------------------- In 2.5 some of the gendisk/partition related code has been reorganized. Now the generic block layer performs partition-remapping early and thus @@ -984,6 +1044,7 @@ sent are offset from the beginning of the device. 7. A Few Tips on Migration of older drivers +=========================================== Old-style drivers that just use CURRENT and ignores clustered requests, may not need much change. The generic layer will automatically handle @@ -1017,12 +1078,12 @@ blk_init_queue time. Drivers no longer have to map a {partition, sector offset} into the correct absolute location anymore, this is done by the block layer, so -where a driver received a request ala this before: +where a driver received a request ala this before:: rq->rq_dev = mk_kdev(3, 5); /* /dev/hda5 */ rq->sector = 0; /* first sector on hda5 */ - it will now see +it will now see:: rq->rq_dev = mk_kdev(3, 0); /* /dev/hda */ rq->sector = 123128; /* offset from start of disk */ @@ -1039,38 +1100,65 @@ a bio into the virtual address space. 8. Prior/Related/Impacted patches +================================= 8.1. Earlier kiobuf patches (sct/axboe/chait/hch/mkp) +----------------------------------------------------- + - orig kiobuf & raw i/o patches (now in 2.4 tree) - direct kiobuf based i/o to devices (no intermediate bh's) - page i/o using kiobuf - kiobuf splitting for lvm (mkp) - elevator support for kiobuf request merging (axboe) + 8.2. Zero-copy networking (Dave Miller) +--------------------------------------- + 8.3. SGI XFS - pagebuf patches - use of kiobufs +----------------------------------------------- 8.4. Multi-page pioent patch for bio (Christoph Hellwig) +-------------------------------------------------------- 8.5. Direct i/o implementation (Andrea Arcangeli) since 2.4.10-pre11 +-------------------------------------------------------------------- 8.6. Async i/o implementation patch (Ben LaHaise) +------------------------------------------------- 8.7. EVMS layering design (IBM EVMS team) -8.8. Larger page cache size patch (Ben LaHaise) and - Large page size (Daniel Phillips) +----------------------------------------- +8.8. Larger page cache size patch (Ben LaHaise) and Large page size (Daniel Phillips) +------------------------------------------------------------------------------------- + => larger contiguous physical memory buffers + 8.9. VM reservations patch (Ben LaHaise) +---------------------------------------- 8.10. Write clustering patches ? (Marcelo/Quintela/Riel ?) +---------------------------------------------------------- 8.11. Block device in page cache patch (Andrea Archangeli) - now in 2.4.10+ -8.12. Multiple block-size transfers for faster raw i/o (Shailabh Nagar, - Badari) +--------------------------------------------------------------------------- +8.12. Multiple block-size transfers for faster raw i/o (Shailabh Nagar, Badari) +------------------------------------------------------------------------------- 8.13 Priority based i/o scheduler - prepatches (Arjan van de Ven) +------------------------------------------------------------------ 8.14 IDE Taskfile i/o patch (Andre Hedrick) +-------------------------------------------- 8.15 Multi-page writeout and readahead patches (Andrew Morton) +--------------------------------------------------------------- 8.16 Direct i/o patches for 2.5 using kvec and bio (Badari Pulavarthy) +----------------------------------------------------------------------- -9. Other References: +9. Other References +=================== -9.1 The Splice I/O Model - Larry McVoy (and subsequent discussions on lkml, -and Linus' comments - Jan 2001) -9.2 Discussions about kiobuf and bh design on lkml between sct, linus, alan -et al - Feb-March 2001 (many of the initial thoughts that led to bio were -brought up in this discussion thread) -9.3 Discussions on mempool on lkml - Dec 2001. +9.1 The Splice I/O Model +------------------------ + +Larry McVoy (and subsequent discussions on lkml, and Linus' comments - Jan 2001 +9.2 Discussions about kiobuf and bh design +------------------------------------------ + +On lkml between sct, linus, alan et al - Feb-March 2001 (many of the +initial thoughts that led to bio were brought up in this discussion thread) + +9.3 Discussions on mempool on lkml - Dec 2001. +---------------------------------------------- diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.rst index ce6eccaf5df7..86fa66c87172 100644 --- a/Documentation/block/biovecs.txt +++ b/Documentation/block/biovecs.rst @@ -1,6 +1,6 @@ - -Immutable biovecs and biovec iterators: -======================================= +====================================== +Immutable biovecs and biovec iterators +====================================== Kent Overstreet <kmo@daterainc.com> @@ -121,10 +121,12 @@ Other implications: Usage of helpers: ================= -* The following helpers whose names have the suffix of "_all" can only be used -on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers -shouldn't use them because the bio may have been split before it reached the -driver. +* The following helpers whose names have the suffix of `_all` can only be used + on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers + shouldn't use them because the bio may have been split before it reached the + driver. + +:: bio_for_each_segment_all() bio_first_bvec_all() @@ -132,13 +134,13 @@ driver. bio_last_bvec_all() * The following helpers iterate over single-page segment. The passed 'struct -bio_vec' will contain a single-page IO vector during the iteration + bio_vec' will contain a single-page IO vector during the iteration:: bio_for_each_segment() bio_for_each_segment_all() * The following helpers iterate over multi-page bvec. The passed 'struct -bio_vec' will contain a multi-page IO vector during the iteration + bio_vec' will contain a multi-page IO vector during the iteration:: bio_for_each_bvec() rq_for_each_bvec() diff --git a/Documentation/block/capability.rst b/Documentation/block/capability.rst new file mode 100644 index 000000000000..2cf258d64bbe --- /dev/null +++ b/Documentation/block/capability.rst @@ -0,0 +1,18 @@ +=============================== +Generic Block Device Capability +=============================== + +This file documents the sysfs file block/<disk>/capability + +capability is a hex word indicating which capabilities a specific disk +supports. For more information on bits not listed here, see +include/linux/genhd.h + +GENHD_FL_MEDIA_CHANGE_NOTIFY +---------------------------- + +Value: 4 + +When this bit is set, the disk supports Asynchronous Notification +of media change events. These events will be broadcast to user +space via kernel uevent. diff --git a/Documentation/block/capability.txt b/Documentation/block/capability.txt deleted file mode 100644 index 2f1729424ef4..000000000000 --- a/Documentation/block/capability.txt +++ /dev/null @@ -1,15 +0,0 @@ -Generic Block Device Capability -=============================================================================== -This file documents the sysfs file block/<disk>/capability - -capability is a hex word indicating which capabilities a specific disk -supports. For more information on bits not listed here, see -include/linux/genhd.h - -Capability Value -------------------------------------------------------------------------------- -GENHD_FL_MEDIA_CHANGE_NOTIFY 4 - When this bit is set, the disk supports Asynchronous Notification - of media change events. These events will be broadcast to user - space via kernel uevent. - diff --git a/Documentation/block/cmdline-partition.txt b/Documentation/block/cmdline-partition.rst index 760a3f7c3ed4..530bedff548a 100644 --- a/Documentation/block/cmdline-partition.txt +++ b/Documentation/block/cmdline-partition.rst @@ -1,5 +1,6 @@ +============================================== Embedded device command line partition parsing -===================================================================== +============================================== The "blkdevparts" command line option adds support for reading the block device partition table from the kernel command line. @@ -22,12 +23,15 @@ blkdevparts=<blkdev-def>[;<blkdev-def>] <size> partition size, in bytes, such as: 512, 1m, 1G. size may contain an optional suffix of (upper or lower case): + K, M, G, T, P, E. + "-" is used to denote all remaining space. <offset> partition start address, in bytes. offset may contain an optional suffix of (upper or lower case): + K, M, G, T, P, E. (part-name) @@ -36,11 +40,14 @@ blkdevparts=<blkdev-def>[;<blkdev-def>] User space application can access partition by partition name. Example: + eMMC disk names are "mmcblk0" and "mmcblk0boot0". - bootargs: + bootargs:: + 'blkdevparts=mmcblk0:1G(data0),1G(data1),-;mmcblk0boot0:1m(boot),-(kernel)' - dmesg: + dmesg:: + mmcblk0: p1(data0) p2(data1) p3() mmcblk0boot0: p1(boot) p2(kernel) diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.rst index 934c44ea0c57..4f2452a95c43 100644 --- a/Documentation/block/data-integrity.txt +++ b/Documentation/block/data-integrity.rst @@ -1,5 +1,9 @@ ----------------------------------------------------------------------- -1. INTRODUCTION +============== +Data Integrity +============== + +1. Introduction +=============== Modern filesystems feature checksumming of data and metadata to protect against data corruption. However, the detection of the @@ -28,8 +32,8 @@ integrity of the I/O and reject it if corruption is detected. This allows not only corruption prevention but also isolation of the point of failure. ----------------------------------------------------------------------- -2. THE DATA INTEGRITY EXTENSIONS +2. The Data Integrity Extensions +================================ As written, the protocol extensions only protect the path between controller and storage device. However, many controllers actually @@ -75,8 +79,8 @@ Extensions. As these extensions are outside the scope of the protocol bodies (T10, T13), Oracle and its partners are trying to standardize them within the Storage Networking Industry Association. ----------------------------------------------------------------------- -3. KERNEL CHANGES +3. Kernel Changes +================= The data integrity framework in Linux enables protection information to be pinned to I/Os and sent to/received from controllers that @@ -123,10 +127,11 @@ access to manipulate the tags from user space. A passthrough interface for this is being worked on. ----------------------------------------------------------------------- -4. BLOCK LAYER IMPLEMENTATION DETAILS +4. Block Layer Implementation Details +===================================== -4.1 BIO +4.1 Bio +------- The data integrity patches add a new field to struct bio when CONFIG_BLK_DEV_INTEGRITY is enabled. bio_integrity(bio) returns a @@ -145,7 +150,8 @@ attached using bio_integrity_add_page(). bio_free() will automatically free the bip. -4.2 BLOCK DEVICE +4.2 Block Device +---------------- Because the format of the protection data is tied to the physical disk, each block device has been extended with a block integrity @@ -163,10 +169,11 @@ and MD linear, RAID0 and RAID1 are currently supported. RAID4/5/6 will require extra work due to the application tag. ----------------------------------------------------------------------- -5.0 BLOCK LAYER INTEGRITY API +5.0 Block Layer Integrity API +============================= -5.1 NORMAL FILESYSTEM +5.1 Normal Filesystem +--------------------- The normal filesystem is unaware that the underlying block device is capable of sending/receiving integrity metadata. The IMD will @@ -174,25 +181,26 @@ will require extra work due to the application tag. in case of a WRITE. A READ request will cause the I/O integrity to be verified upon completion. - IMD generation and verification can be toggled using the + IMD generation and verification can be toggled using the:: /sys/block/<bdev>/integrity/write_generate - and + and:: /sys/block/<bdev>/integrity/read_verify flags. -5.2 INTEGRITY-AWARE FILESYSTEM +5.2 Integrity-Aware Filesystem +------------------------------ A filesystem that is integrity-aware can prepare I/Os with IMD attached. It can also use the application tag space if this is supported by the block device. - bool bio_integrity_prep(bio); + `bool bio_integrity_prep(bio);` To generate IMD for WRITE and to set up buffers for READ, the filesystem must call bio_integrity_prep(bio). @@ -204,14 +212,15 @@ will require extra work due to the application tag. Complete bio with error if prepare failed for some reson. -5.3 PASSING EXISTING INTEGRITY METADATA +5.3 Passing Existing Integrity Metadata +--------------------------------------- Filesystems that either generate their own integrity metadata or are capable of transferring IMD from user space can use the following calls: - struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages); + `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);` Allocates the bio integrity payload and hangs it off of the bio. nr_pages indicate how many pages of protection data need to be @@ -220,7 +229,7 @@ will require extra work due to the application tag. The integrity payload will be freed at bio_free() time. - int bio_integrity_add_page(bio, page, len, offset); + `int bio_integrity_add_page(bio, page, len, offset);` Attaches a page containing integrity metadata to an existing bio. The bio must have an existing bip, @@ -241,21 +250,21 @@ will require extra work due to the application tag. integrity upon completion. -5.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY - METADATA +5.4 Registering A Block Device As Capable Of Exchanging Integrity Metadata +-------------------------------------------------------------------------- To enable integrity exchange on a block device the gendisk must be registered as capable: - int blk_integrity_register(gendisk, blk_integrity); + `int blk_integrity_register(gendisk, blk_integrity);` The blk_integrity struct is a template and should contain the - following: + following:: static struct blk_integrity my_profile = { .name = "STANDARDSBODY-TYPE-VARIANT-CSUM", .generate_fn = my_generate_fn, - .verify_fn = my_verify_fn, + .verify_fn = my_verify_fn, .tuple_size = sizeof(struct my_tuple_size), .tag_size = <tag bytes per hw sector>, }; @@ -278,4 +287,5 @@ will require extra work due to the application tag. 0 depending on the value of the Control Mode Page ATO bit. ---------------------------------------------------------------------- + 2007-12-24 Martin K. Petersen <martin.petersen@oracle.com> diff --git a/Documentation/block/deadline-iosched.txt b/Documentation/block/deadline-iosched.rst index 2d82c80322cb..9f5c5a4c370e 100644 --- a/Documentation/block/deadline-iosched.txt +++ b/Documentation/block/deadline-iosched.rst @@ -1,3 +1,4 @@ +============================== Deadline IO scheduler tunables ============================== @@ -7,15 +8,13 @@ of interest to power users. Selecting IO schedulers ----------------------- -Refer to Documentation/block/switching-sched.txt for information on +Refer to Documentation/block/switching-sched.rst for information on selecting an io scheduler on a per-device basis. - -******************************************************************************** - +------------------------------------------------------------------------------ read_expire (in ms) ------------ +----------------------- The goal of the deadline io scheduler is to attempt to guarantee a start service time for a request. As we focus mainly on read latencies, this is @@ -25,15 +24,15 @@ milliseconds. write_expire (in ms) ------------ +----------------------- Similar to read_expire mentioned above, but for writes. fifo_batch (number of requests) ----------- +------------------------------------ -Requests are grouped into ``batches'' of a particular data direction (read or +Requests are grouped into ``batches`` of a particular data direction (read or write) which are serviced in increasing sector order. To limit extra seeking, deadline expiries are only checked between batches. fifo_batch controls the maximum number of requests per batch. @@ -45,7 +44,7 @@ generally improves throughput, at the cost of latency variation. writes_starved (number of dispatches) --------------- +-------------------------------------- When we have to move requests from the io scheduler queue to the block device dispatch queue, we always give a preference to reads. However, we @@ -56,7 +55,7 @@ same criteria as reads. front_merges (bool) ------------- +---------------------- Sometimes it happens that a request enters the io scheduler that is contiguous with a request that is already on the queue. Either it fits in the back of that @@ -71,5 +70,3 @@ rbtree front sector lookup when the io scheduler merge function is called. Nov 11 2002, Jens Axboe <jens.axboe@oracle.com> - - diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst new file mode 100644 index 000000000000..3fa7a52fafa4 --- /dev/null +++ b/Documentation/block/index.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===== +Block +===== + +.. toctree:: + :maxdepth: 1 + + bfq-iosched + biodoc + biovecs + capability + cmdline-partition + data-integrity + deadline-iosched + ioprio + kyber-iosched + null_blk + pr + queue-sysfs + request + stat + switching-sched + writeback_cache_control diff --git a/Documentation/block/ioprio.txt b/Documentation/block/ioprio.rst index 8ed8c59380b4..f72b0de65af7 100644 --- a/Documentation/block/ioprio.txt +++ b/Documentation/block/ioprio.rst @@ -1,3 +1,4 @@ +=================== Block io priorities =================== @@ -40,81 +41,81 @@ class data, since it doesn't really apply here. Tools ----- -See below for a sample ionice tool. Usage: +See below for a sample ionice tool. Usage:: -# ionice -c<class> -n<level> -p<pid> + # ionice -c<class> -n<level> -p<pid> If pid isn't given, the current process is assumed. IO priority settings are inherited on fork, so you can use ionice to start the process at a given -level: +level:: -# ionice -c2 -n0 /bin/ls + # ionice -c2 -n0 /bin/ls will run ls at the best-effort scheduling class at the highest priority. -For a running process, you can give the pid instead: +For a running process, you can give the pid instead:: -# ionice -c1 -n2 -p100 + # ionice -c1 -n2 -p100 will change pid 100 to run at the realtime scheduling class, at priority 2. ----> snip ionice.c tool <--- - -#include <stdio.h> -#include <stdlib.h> -#include <errno.h> -#include <getopt.h> -#include <unistd.h> -#include <sys/ptrace.h> -#include <asm/unistd.h> - -extern int sys_ioprio_set(int, int, int); -extern int sys_ioprio_get(int, int); - -#if defined(__i386__) -#define __NR_ioprio_set 289 -#define __NR_ioprio_get 290 -#elif defined(__ppc__) -#define __NR_ioprio_set 273 -#define __NR_ioprio_get 274 -#elif defined(__x86_64__) -#define __NR_ioprio_set 251 -#define __NR_ioprio_get 252 -#elif defined(__ia64__) -#define __NR_ioprio_set 1274 -#define __NR_ioprio_get 1275 -#else -#error "Unsupported arch" -#endif - -static inline int ioprio_set(int which, int who, int ioprio) -{ +ionice.c tool:: + + #include <stdio.h> + #include <stdlib.h> + #include <errno.h> + #include <getopt.h> + #include <unistd.h> + #include <sys/ptrace.h> + #include <asm/unistd.h> + + extern int sys_ioprio_set(int, int, int); + extern int sys_ioprio_get(int, int); + + #if defined(__i386__) + #define __NR_ioprio_set 289 + #define __NR_ioprio_get 290 + #elif defined(__ppc__) + #define __NR_ioprio_set 273 + #define __NR_ioprio_get 274 + #elif defined(__x86_64__) + #define __NR_ioprio_set 251 + #define __NR_ioprio_get 252 + #elif defined(__ia64__) + #define __NR_ioprio_set 1274 + #define __NR_ioprio_get 1275 + #else + #error "Unsupported arch" + #endif + + static inline int ioprio_set(int which, int who, int ioprio) + { return syscall(__NR_ioprio_set, which, who, ioprio); -} + } -static inline int ioprio_get(int which, int who) -{ + static inline int ioprio_get(int which, int who) + { return syscall(__NR_ioprio_get, which, who); -} + } -enum { + enum { IOPRIO_CLASS_NONE, IOPRIO_CLASS_RT, IOPRIO_CLASS_BE, IOPRIO_CLASS_IDLE, -}; + }; -enum { + enum { IOPRIO_WHO_PROCESS = 1, IOPRIO_WHO_PGRP, IOPRIO_WHO_USER, -}; + }; -#define IOPRIO_CLASS_SHIFT 13 + #define IOPRIO_CLASS_SHIFT 13 -const char *to_prio[] = { "none", "realtime", "best-effort", "idle", }; + const char *to_prio[] = { "none", "realtime", "best-effort", "idle", }; -int main(int argc, char *argv[]) -{ + int main(int argc, char *argv[]) + { int ioprio = 4, set = 0, ioprio_class = IOPRIO_CLASS_BE; int c, pid = 0; @@ -175,9 +176,7 @@ int main(int argc, char *argv[]) } return 0; -} - ----> snip ionice.c tool <--- + } March 11 2005, Jens Axboe <jens.axboe@oracle.com> diff --git a/Documentation/block/kyber-iosched.txt b/Documentation/block/kyber-iosched.rst index e94feacd7edc..3e164dd0617c 100644 --- a/Documentation/block/kyber-iosched.txt +++ b/Documentation/block/kyber-iosched.rst @@ -1,5 +1,6 @@ +============================ Kyber I/O scheduler tunables -=========================== +============================ The only two tunables for the Kyber scheduler are the target latencies for reads and synchronous writes. Kyber will throttle requests in order to meet diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.rst index 41f0a3d33bbd..31451d80783c 100644 --- a/Documentation/block/null_blk.txt +++ b/Documentation/block/null_blk.rst @@ -1,33 +1,43 @@ +======================== Null block device driver -================================================================================ +======================== -I. Overview +1. Overview +=========== The null block device (/dev/nullb*) is used for benchmarking the various block-layer implementations. It emulates a block device of X gigabytes in size. The following instances are possible: Single-queue block-layer + - Request-based. - Single submission queue per device. - Implements IO scheduling algorithms (CFQ, Deadline, noop). + Multi-queue block-layer + - Request-based. - Configurable submission queues per device. + No block-layer (Known as bio-based) + - Bio-based. IO requests are submitted directly to the device driver. - Directly accepts bio data structure and returns them. All of them have a completion queue for each core in the system. -II. Module parameters applicable for all instances: +2. Module parameters applicable for all instances +================================================= queue_mode=[0-2]: Default: 2-Multi-queue Selects which block-layer the module should instantiate with. - 0: Bio-based. - 1: Single-queue. - 2: Multi-queue. + = ============ + 0 Bio-based + 1 Single-queue + 2 Multi-queue + = ============ home_node=[0--nr_nodes]: Default: NUMA_NO_NODE Selects what CPU node the data structures are allocated from. @@ -45,12 +55,14 @@ nr_devices=[Number of devices]: Default: 1 irqmode=[0-2]: Default: 1-Soft-irq The completion mode used for completing IOs to the block-layer. - 0: None. - 1: Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead + = =========================================================================== + 0 None. + 1 Soft-irq. Uses IPI to complete IOs across CPU nodes. Simulates the overhead when IOs are issued from another CPU node than the home the device is connected to. - 2: Timer: Waits a specific period (completion_nsec) for each IO before + 2 Timer: Waits a specific period (completion_nsec) for each IO before completion. + = =========================================================================== completion_nsec=[ns]: Default: 10,000ns Combined with irqmode=2 (timer). The time each completion event must wait. @@ -66,30 +78,45 @@ hw_queue_depth=[0..qdepth]: Default: 64 III: Multi-queue specific parameters use_per_node_hctx=[0/1]: Default: 0 - 0: The number of submit queues are set to the value of the submit_queues + + = ===================================================================== + 0 The number of submit queues are set to the value of the submit_queues parameter. - 1: The multi-queue block layer is instantiated with a hardware dispatch + 1 The multi-queue block layer is instantiated with a hardware dispatch queue for each CPU node in the system. + = ===================================================================== no_sched=[0/1]: Default: 0 - 0: nullb* use default blk-mq io scheduler. - 1: nullb* doesn't use io scheduler. + + = ====================================== + 0 nullb* use default blk-mq io scheduler + 1 nullb* doesn't use io scheduler + = ====================================== blocking=[0/1]: Default: 0 - 0: Register as a non-blocking blk-mq driver device. - 1: Register as a blocking blk-mq driver device, null_blk will set + + = =============================================================== + 0 Register as a non-blocking blk-mq driver device. + 1 Register as a blocking blk-mq driver device, null_blk will set the BLK_MQ_F_BLOCKING flag, indicating that it sometimes/always needs to block in its ->queue_rq() function. + = =============================================================== shared_tags=[0/1]: Default: 0 - 0: Tag set is not shared. - 1: Tag set shared between devices for blk-mq. Only makes sense with + + = ================================================================ + 0 Tag set is not shared. + 1 Tag set shared between devices for blk-mq. Only makes sense with nr_devices > 1, otherwise there's no tag set to share. + = ================================================================ zoned=[0/1]: Default: 0 - 0: Block device is exposed as a random-access block device. - 1: Block device is exposed as a host-managed zoned block device. Requires + + = ====================================================================== + 0 Block device is exposed as a random-access block device. + 1 Block device is exposed as a host-managed zoned block device. Requires CONFIG_BLK_DEV_ZONED. + = ====================================================================== zone_size=[MB]: Default: 256 Per zone size when exposed as a zoned block device. Must be a power of two. diff --git a/Documentation/block/pr.txt b/Documentation/block/pr.rst index ac9b8e70e64b..30ea1c2e39eb 100644 --- a/Documentation/block/pr.txt +++ b/Documentation/block/pr.rst @@ -1,4 +1,4 @@ - +=============================================== Block layer support for Persistent Reservations =============================================== @@ -23,22 +23,18 @@ 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 @@ -48,21 +44,21 @@ The following types of reservations are supported: 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. + 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. + 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, @@ -74,6 +70,7 @@ 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 @@ -82,12 +79,14 @@ 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 new reservation of type for the @@ -95,11 +94,13 @@ 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. @@ -111,7 +112,6 @@ 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. diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.rst index b40b5b7cebd9..6a8513af9201 100644 --- a/Documentation/block/queue-sysfs.txt +++ b/Documentation/block/queue-sysfs.rst @@ -1,3 +1,4 @@ +================= Queue sysfs files ================= @@ -10,7 +11,7 @@ Files denoted with a RO postfix are readonly and the RW postfix means read-write. add_random (RW) ----------------- +--------------- This file allows to turn off the disk entropy contribution. Default value of this file is '1'(on). @@ -30,13 +31,13 @@ used by CPU-addressable storage to bypass the pagecache. It shows '1' if true, '0' if not. discard_granularity (RO) ------------------------ +------------------------ This shows the size of internal allocation of the device in bytes, if reported by the device. A value of '0' means device does not support the discard functionality. discard_max_hw_bytes (RO) ----------------------- +------------------------- Devices that support discard functionality may have internal limits on the number of bytes that can be trimmed or unmapped in a single operation. The discard_max_bytes parameter is set by the device driver to the maximum diff --git a/Documentation/block/request.txt b/Documentation/block/request.rst index 754e104ed369..747021e1ffdb 100644 --- a/Documentation/block/request.txt +++ b/Documentation/block/request.rst @@ -1,26 +1,37 @@ - +============================ struct request documentation +============================ Jens Axboe <jens.axboe@oracle.com> 27/05/02 -1.0 -Index -2.0 Struct request members classification +.. FIXME: + No idea about what does mean - seems just some noise, so comment it + + 1.0 + Index + + 2.0 Struct request members classification + + 2.1 struct request members explanation - 2.1 struct request members explanation + 3.0 + + + 2.0 -3.0 -2.0 Short explanation of request members +==================================== Classification flags: + = ==================== D driver member B block layer member I I/O scheduler member + = ==================== Unless an entry contains a D classification, a device driver must not access this member. Some members may contain D classifications, but should only be @@ -28,14 +39,13 @@ access through certain macros or functions (eg ->flags). <linux/blkdev.h> -2.1 +=============================== ======= ======================================= Member Flag Comment ------- ---- ------- - +=============================== ======= ======================================= struct list_head queuelist BI Organization on various internal queues -void *elevator_private I I/O scheduler private data +``void *elevator_private`` I I/O scheduler private data unsigned char cmd[16] D Driver can use this for setting up a cdb before execution, see @@ -71,18 +81,19 @@ unsigned int hard_cur_sectors B Used to keep current_nr_sectors sane int tag DB TCQ tag, if assigned -void *special D Free to be used by driver +``void *special`` D Free to be used by driver -char *buffer D Map of first segment, also see +``char *buffer`` D Map of first segment, also see section on bouncing SECTION -struct completion *waiting D Can be used by driver to get signalled +``struct completion *waiting`` D Can be used by driver to get signalled on request completion -struct bio *bio DBI First bio in request +``struct bio *bio`` DBI First bio in request -struct bio *biotail DBI Last bio in request +``struct bio *biotail`` DBI Last bio in request -struct request_queue *q DB Request queue this request belongs to +``struct request_queue *q`` DB Request queue this request belongs to -struct request_list *rl B Request list this request came from +``struct request_list *rl`` B Request list this request came from +=============================== ======= ======================================= diff --git a/Documentation/block/stat.txt b/Documentation/block/stat.rst index 0aace9cc536c..9c07bc22b0bc 100644 --- a/Documentation/block/stat.txt +++ b/Documentation/block/stat.rst @@ -1,3 +1,4 @@ +=============================================== Block layer statistics in /sys/block/<dev>/stat =============================================== @@ -6,9 +7,12 @@ This file documents the contents of the /sys/block/<dev>/stat file. The stat file provides several statistics about the state of block device <dev>. -Q. Why are there multiple statistics in a single file? Doesn't sysfs +Q. + Why are there multiple statistics in a single file? Doesn't sysfs normally contain a single value per file? -A. By having a single file, the kernel can guarantee that the statistics + +A. + By having a single file, the kernel can guarantee that the statistics represent a consistent snapshot of the state of the device. If the statistics were exported as multiple files containing one statistic each, it would be impossible to guarantee that a set of readings @@ -18,8 +22,10 @@ The stat file consists of a single line of text containing 11 decimal values separated by whitespace. The fields are summarized in the following table, and described in more detail below. + +=============== ============= ================================================= Name units description ----- ----- ----------- +=============== ============= ================================================= read I/Os requests number of read I/Os processed read merges requests number of read I/Os merged with in-queue I/O read sectors sectors number of sectors read @@ -35,6 +41,7 @@ discard I/Os requests number of discard I/Os processed discard merges requests number of discard I/Os merged with in-queue I/O discard sectors sectors number of sectors discarded discard ticks milliseconds total wait time for discard requests +=============== ============= ================================================= read I/Os, write I/Os, discard I/0s =================================== diff --git a/Documentation/block/switching-sched.txt b/Documentation/block/switching-sched.rst index 7977f6fb8b20..42042417380e 100644 --- a/Documentation/block/switching-sched.txt +++ b/Documentation/block/switching-sched.rst @@ -1,35 +1,39 @@ +=================== +Switching Scheduler +=================== + To choose IO schedulers at boot time, use the argument 'elevator=deadline'. 'noop' and 'cfq' (the default) are also available. IO schedulers are assigned globally at boot time only presently. Each io queue has a set of io scheduler tunables associated with it. These tunables control how the io scheduler works. You can find these entries -in: +in:: -/sys/block/<device>/queue/iosched + /sys/block/<device>/queue/iosched assuming that you have sysfs mounted on /sys. If you don't have sysfs mounted, -you can do so by typing: +you can do so by typing:: -# mount none /sys -t sysfs + # mount none /sys -t sysfs It is possible to change the IO scheduler for a given block device on the fly to select one of mq-deadline, none, bfq, or kyber schedulers - which can improve that device's throughput. -To set a specific scheduler, simply do this: +To set a specific scheduler, simply do this:: -echo SCHEDNAME > /sys/block/DEV/queue/scheduler + echo SCHEDNAME > /sys/block/DEV/queue/scheduler where SCHEDNAME is the name of a defined IO scheduler, and DEV is the device name (hda, hdb, sga, or whatever you happen to have). The list of defined schedulers can be found by simply doing a "cat /sys/block/DEV/queue/scheduler" - the list of valid names -will be displayed, with the currently selected scheduler in brackets: +will be displayed, with the currently selected scheduler in brackets:: -# cat /sys/block/sda/queue/scheduler -[mq-deadline] kyber bfq none -# echo none >/sys/block/sda/queue/scheduler -# cat /sys/block/sda/queue/scheduler -[none] mq-deadline kyber bfq + # cat /sys/block/sda/queue/scheduler + [mq-deadline] kyber bfq none + # echo none >/sys/block/sda/queue/scheduler + # cat /sys/block/sda/queue/scheduler + [none] mq-deadline kyber bfq diff --git a/Documentation/block/writeback_cache_control.txt b/Documentation/block/writeback_cache_control.rst index 8a6bdada5f6b..2c752c57c14c 100644 --- a/Documentation/block/writeback_cache_control.txt +++ b/Documentation/block/writeback_cache_control.rst @@ -1,6 +1,6 @@ - +========================================== Explicit volatile write back cache control -===================================== +========================================== Introduction ------------ @@ -31,7 +31,7 @@ the blkdev_issue_flush() helper for a pure cache flush. Forced Unit Access ------------------ +------------------ The REQ_FUA flag can be OR ed into the r/w flags of a bio submitted from the filesystem and will make sure that I/O completion for this request is only @@ -62,14 +62,14 @@ flags themselves without any help from the block layer. Implementation details for request_fn based block drivers --------------------------------------------------------------- +--------------------------------------------------------- For devices that do not support volatile write caches there is no driver support required, the block layer completes empty REQ_PREFLUSH requests before entering the driver and strips off the REQ_PREFLUSH and REQ_FUA bits from requests that have a payload. For devices with volatile write caches the driver needs to tell the block layer that it supports flushing caches by -doing: +doing:: blk_queue_write_cache(sdkp->disk->queue, true, false); @@ -77,7 +77,7 @@ and handle empty REQ_OP_FLUSH requests in its prep_fn/request_fn. Note that REQ_PREFLUSH requests with a payload are automatically turned into a sequence of an empty REQ_OP_FLUSH request followed by the actual write by the block layer. For devices that also support the FUA bit the block layer needs -to be told to pass through the REQ_FUA bit using: +to be told to pass through the REQ_FUA bit using:: blk_queue_write_cache(sdkp->disk->queue, true, true); diff --git a/Documentation/cdrom/index.rst b/Documentation/cdrom/index.rst index efbd5d111825..338ad5f94e7c 100644 --- a/Documentation/cdrom/index.rst +++ b/Documentation/cdrom/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ===== cdrom diff --git a/Documentation/gcc-plugins.txt b/Documentation/core-api/gcc-plugins.rst index 8502f24396fb..8502f24396fb 100644 --- a/Documentation/gcc-plugins.txt +++ b/Documentation/core-api/gcc-plugins.rst diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 322ac954b390..da0ed972d224 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -36,6 +36,7 @@ Core utilities memory-hotplug protection-keys ../RCU/index + gcc-plugins Interfaces for kernel debugging diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 75d2bbe9813f..c6224d039bcb 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -119,7 +119,7 @@ Kernel Pointers For printing kernel pointers which should be hidden from unprivileged users. The behaviour of %pK depends on the kptr_restrict sysctl - see -Documentation/sysctl/kernel.txt for more details. +Documentation/admin-guide/sysctl/kernel.rst for more details. Unmodified Addresses -------------------- diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt index 073f128af5a7..55193e680250 100644 --- a/Documentation/cpu-freq/core.txt +++ b/Documentation/cpu-freq/core.txt @@ -95,7 +95,7 @@ flags - flags of the cpufreq driver 3. CPUFreq Table Generation with Operating Performance Point (OPP) ================================================================== -For details about OPP, see Documentation/power/opp.txt +For details about OPP, see Documentation/power/opp.rst dev_pm_opp_init_cpufreq_table - This function provides a ready to use conversion routine to translate diff --git a/Documentation/dev-tools/sparse.rst b/Documentation/dev-tools/sparse.rst index c401c952a340..6f4870528226 100644 --- a/Documentation/dev-tools/sparse.rst +++ b/Documentation/dev-tools/sparse.rst @@ -81,11 +81,6 @@ of sparse using git to clone:: git://git.kernel.org/pub/scm/devel/sparse/sparse.git -DaveJ has hourly generated tarballs of the git tree available at:: - - http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ - - Once you have it, just do:: make diff --git a/Documentation/devicetree/bindings/arm/amlogic.txt b/Documentation/devicetree/bindings/arm/amlogic.txt deleted file mode 100644 index 061f7b98a07f..000000000000 --- a/Documentation/devicetree/bindings/arm/amlogic.txt +++ /dev/null @@ -1,142 +0,0 @@ -Amlogic MesonX device tree bindings -------------------------------------------- - -Work in progress statement: - -Device tree files and bindings applying to Amlogic SoCs and boards are -considered "unstable". Any Amlogic device tree binding may change at -any time. Be sure to use a device tree binary and a kernel image -generated from the same source tree. - -Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a -stable binding/ABI. - ---------------------------------------------------------------- - -Boards with the Amlogic Meson6 SoC shall have the following properties: - Required root node property: - compatible: "amlogic,meson6" - -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"; - -Boards with the Amlogic Meson8m2 SoC shall have the following properties: - Required root node property: - compatible: "amlogic,meson8m2"; - -Boards with the Amlogic Meson GXBaby SoC shall have the following properties: - Required root node property: - compatible: "amlogic,meson-gxbb"; - -Boards with the Amlogic Meson GXL S905X SoC shall have the following properties: - Required root node property: - compatible: "amlogic,s905x", "amlogic,meson-gxl"; - -Boards with the Amlogic Meson GXL S905D SoC shall have the following properties: - Required root node property: - compatible: "amlogic,s905d", "amlogic,meson-gxl"; - -Boards with the Amlogic Meson GXL S805X SoC shall have the following properties: - Required root node property: - compatible: "amlogic,s805x", "amlogic,meson-gxl"; - -Boards with the Amlogic Meson GXL S905W SoC shall have the following properties: - Required root node property: - compatible: "amlogic,s905w", "amlogic,meson-gxl"; - -Boards with the Amlogic Meson GXM S912 SoC shall have the following properties: - Required root node property: - compatible: "amlogic,s912", "amlogic,meson-gxm"; - -Boards with the Amlogic Meson AXG A113D SoC shall have the following properties: - Required root node property: - compatible: "amlogic,a113d", "amlogic,meson-axg"; - -Boards with the Amlogic Meson G12A S905D2 SoC shall have the following properties: - Required root node property: - compatible: "amlogic,g12a"; - -Board compatible values (alphabetically, grouped by SoC): - - - "geniatech,atv1200" (Meson6) - - - "minix,neo-x8" (Meson8) - - - "endless,ec100" (Meson8b) - - "hardkernel,odroid-c1" (Meson8b) - - "tronfy,mxq" (Meson8b) - - - "tronsmart,mxiii-plus" (Meson8m2) - - - "amlogic,p200" (Meson gxbb) - - "amlogic,p201" (Meson gxbb) - - "friendlyarm,nanopi-k2" (Meson gxbb) - - "hardkernel,odroid-c2" (Meson gxbb) - - "nexbox,a95x" (Meson gxbb or Meson gxl s905x) - - "tronsmart,vega-s95-pro", "tronsmart,vega-s95" (Meson gxbb) - - "tronsmart,vega-s95-meta", "tronsmart,vega-s95" (Meson gxbb) - - "tronsmart,vega-s95-telos", "tronsmart,vega-s95" (Meson gxbb) - - "wetek,hub" (Meson gxbb) - - "wetek,play2" (Meson gxbb) - - - "amlogic,p212" (Meson gxl s905x) - - "hwacom,amazetv" (Meson gxl s905x) - - "khadas,vim" (Meson gxl s905x) - - "libretech,cc" (Meson gxl s905x) - - - "amlogic,p230" (Meson gxl s905d) - - "amlogic,p231" (Meson gxl s905d) - - "phicomm,n1" (Meson gxl s905d) - - - "amlogic,p241" (Meson gxl s805x) - - "libretech,aml-s805x-ac" (Meson gxl s805x) - - - "amlogic,p281" (Meson gxl s905w) - - "oranth,tx3-mini" (Meson gxl s905w) - - - "amlogic,q200" (Meson gxm s912) - - "amlogic,q201" (Meson gxm s912) - - "khadas,vim2" (Meson gxm s912) - - "kingnovel,r-box-pro" (Meson gxm S912) - - "nexbox,a1" (Meson gxm s912) - - "tronsmart,vega-s96" (Meson gxm s912) - - - "amlogic,s400" (Meson axg a113d) - - - "amlogic,u200" (Meson g12a s905d2) - - "amediatech,x96-max" (Meson g12a s905x2) - - "seirobotics,sei510" (Meson g12a s905x2) - -Amlogic Meson Firmware registers Interface ------------------------------------------- - -The Meson SoCs have a register bank with status and data shared with the -secure firmware. - -Required properties: - - compatible: For Meson GX SoCs, must be "amlogic,meson-gx-ao-secure", "syscon" - -Properties should indentify components of this register interface : - -Meson GX SoC Information ------------------------- -A firmware register encodes the SoC type, package and revision information on -the Meson GX SoCs. -If present, the following property should be added : - -Optional properties: - - amlogic,has-chip-id: If present, the interface gives the current SoC version. - -Example -------- - -ao-secure@140 { - compatible = "amlogic,meson-gx-ao-secure", "syscon"; - reg = <0x0 0x140 0x0 0x140>; - amlogic,has-chip-id; -}; diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml new file mode 100644 index 000000000000..325c6fd3566d --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -0,0 +1,144 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/amlogic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic MesonX device tree bindings + +maintainers: + - Kevin Hilman <khilman@baylibre.com> + +description: |+ + Work in progress statement: + + Device tree files and bindings applying to Amlogic SoCs and boards are + considered "unstable". Any Amlogic device tree binding may change at + any time. Be sure to use a device tree binary and a kernel image + generated from the same source tree. + + Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a + stable binding/ABI. + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: Boards with the Amlogic Meson6 SoC + items: + - enum: + - geniatech,atv1200 + - const: amlogic,meson6 + + - description: Boards with the Amlogic Meson8 SoC + items: + - enum: + - minix,neo-x8 + - const: amlogic,meson8 + + - description: Boards with the Amlogic Meson8m2 SoC + items: + - enum: + - tronsmart,mxiii-plus + - const: amlogic,meson8m2 + + - description: Boards with the Amlogic Meson8b SoC + items: + - enum: + - endless,ec100 + - hardkernel,odroid-c1 + - tronfy,mxq + - const: amlogic,meson8b + + - description: Boards with the Amlogic Meson GXBaby SoC + items: + - enum: + - amlogic,p200 + - amlogic,p201 + - friendlyarm,nanopi-k2 + - hardkernel,odroid-c2 + - nexbox,a95x + - wetek,hub + - wetek,play2 + - const: amlogic,meson-gxbb + + - description: Tronsmart Vega S95 devices + items: + - enum: + - tronsmart,vega-s95-pro + - tronsmart,vega-s95-meta + - tronsmart,vega-s95-telos + - const: tronsmart,vega-s95 + - const: amlogic,meson-gxbb + + - description: Boards with the Amlogic Meson GXL S805X SoC + items: + - enum: + - amlogic,p241 + - libretech,aml-s805x-ac + - const: amlogic,s805x + - const: amlogic,meson-gxl + + - description: Boards with the Amlogic Meson GXL S905W SoC + items: + - enum: + - amlogic,p281 + - oranth,tx3-mini + - const: amlogic,s905w + - const: amlogic,meson-gxl + + - description: Boards with the Amlogic Meson GXL S905X SoC + items: + - enum: + - amediatech,x96-max + - amlogic,p212 + - hwacom,amazetv + - khadas,vim + - libretech,cc + - nexbox,a95x + - seirobotics,sei510 + - const: amlogic,s905x + - const: amlogic,meson-gxl + + - description: Boards with the Amlogic Meson GXL S905D SoC + items: + - enum: + - amlogic,p230 + - amlogic,p231 + - phicomm,n1 + - const: amlogic,s905d + - const: amlogic,meson-gxl + + - description: Boards with the Amlogic Meson GXM S912 SoC + items: + - enum: + - amlogic,q200 + - amlogic,q201 + - khadas,vim2 + - kingnovel,r-box-pro + - nexbox,a1 + - tronsmart,vega-s96 + - const: amlogic,s912 + - const: amlogic,meson-gxm + + - description: Boards with the Amlogic Meson AXG A113D SoC + items: + - enum: + - amlogic,s400 + - const: amlogic,a113d + - const: amlogic,meson-axg + + - description: Boards with the Amlogic Meson G12A S905D2 SoC + items: + - enum: + - amlogic,u200 + - const: amlogic,g12a + + - description: Boards with the Amlogic Meson G12B S922X SoC + items: + - enum: + - hardkernel,odroid-n2 + - const: amlogic,g12b + +... diff --git a/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt new file mode 100644 index 000000000000..c67d9f48fb91 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amlogic/amlogic,meson-gx-ao-secure.txt @@ -0,0 +1,28 @@ +Amlogic Meson Firmware registers Interface +------------------------------------------ + +The Meson SoCs have a register bank with status and data shared with the +secure firmware. + +Required properties: + - compatible: For Meson GX SoCs, must be "amlogic,meson-gx-ao-secure", "syscon" + +Properties should indentify components of this register interface : + +Meson GX SoC Information +------------------------ +A firmware register encodes the SoC type, package and revision information on +the Meson GX SoCs. +If present, the following property should be added : + +Optional properties: + - amlogic,has-chip-id: If present, the interface gives the current SoC version. + +Example +------- + +ao-secure@140 { + compatible = "amlogic,meson-gx-ao-secure", "syscon"; + reg = <0x0 0x140 0x0 0x140>; + amlogic,has-chip-id; +}; diff --git a/Documentation/devicetree/bindings/arm/arm,scmi.txt b/Documentation/devicetree/bindings/arm/arm,scmi.txt index 5f3719ab7075..317a2fc3667a 100644 --- a/Documentation/devicetree/bindings/arm/arm,scmi.txt +++ b/Documentation/devicetree/bindings/arm/arm,scmi.txt @@ -6,7 +6,7 @@ that are provided by the hardware platform it is running on, including power and performance functions. This binding is intended to define the interface the firmware implementing -the SCMI as described in ARM document number ARM DUI 0922B ("ARM System Control +the SCMI as described in ARM document number ARM DEN 0056A ("ARM System Control and Management Interface Platform Design Document")[0] provide for OSPM in the device tree. diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.txt b/Documentation/devicetree/bindings/arm/atmel-at91.txt deleted file mode 100644 index 99dee23c74a4..000000000000 --- a/Documentation/devicetree/bindings/arm/atmel-at91.txt +++ /dev/null @@ -1,73 +0,0 @@ -Atmel AT91 device tree bindings. -================================ - -Boards with a SoC of the Atmel AT91 or SMART family shall have the following -properties: - -Required root node properties: -compatible: must be one of: - * "atmel,at91rm9200" - - * "atmel,at91sam9" for SoCs using an ARM926EJ-S core, shall be extended with - the specific SoC family or compatible: - o "atmel,at91sam9260" - o "atmel,at91sam9261" - o "atmel,at91sam9263" - o "atmel,at91sam9x5" for the 5 series, shall be extended with the specific - SoC compatible: - - "atmel,at91sam9g15" - - "atmel,at91sam9g25" - - "atmel,at91sam9g35" - - "atmel,at91sam9x25" - - "atmel,at91sam9x35" - o "atmel,at91sam9g20" - o "atmel,at91sam9g45" - o "atmel,at91sam9n12" - o "atmel,at91sam9rl" - o "atmel,at91sam9xe" - o "microchip,sam9x60" - * "atmel,sama5" for SoCs using a Cortex-A5, shall be extended with the specific - SoC family: - o "atmel,sama5d2" shall be extended with the specific SoC compatible: - - "atmel,sama5d27" - o "atmel,sama5d3" shall be extended with the specific SoC compatible: - - "atmel,sama5d31" - - "atmel,sama5d33" - - "atmel,sama5d34" - - "atmel,sama5d35" - - "atmel,sama5d36" - o "atmel,sama5d4" shall be extended with the specific SoC compatible: - - "atmel,sama5d41" - - "atmel,sama5d42" - - "atmel,sama5d43" - - "atmel,sama5d44" - - * "atmel,samv7" for MCUs using a Cortex-M7, shall be extended with the specific - SoC family: - o "atmel,sams70" shall be extended with the specific MCU compatible: - - "atmel,sams70j19" - - "atmel,sams70j20" - - "atmel,sams70j21" - - "atmel,sams70n19" - - "atmel,sams70n20" - - "atmel,sams70n21" - - "atmel,sams70q19" - - "atmel,sams70q20" - - "atmel,sams70q21" - o "atmel,samv70" shall be extended with the specific MCU compatible: - - "atmel,samv70j19" - - "atmel,samv70j20" - - "atmel,samv70n19" - - "atmel,samv70n20" - - "atmel,samv70q19" - - "atmel,samv70q20" - o "atmel,samv71" shall be extended with the specific MCU compatible: - - "atmel,samv71j19" - - "atmel,samv71j20" - - "atmel,samv71j21" - - "atmel,samv71n19" - - "atmel,samv71n20" - - "atmel,samv71n21" - - "atmel,samv71q19" - - "atmel,samv71q20" - - "atmel,samv71q21" diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml new file mode 100644 index 000000000000..6e168abcd4d1 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/atmel-at91.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel AT91 device tree bindings. + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + - Ludovic Desroches <ludovic.desroches@microchip.com> + +description: | + Boards with a SoC of the Atmel AT91 or SMART family shall have the following + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - const: atmel,at91rm9200 + - items: + - enum: + - olimex,sam9-l9260 + - enum: + - atmel,at91sam9260 + - atmel,at91sam9261 + - atmel,at91sam9263 + - atmel,at91sam9g20 + - atmel,at91sam9g45 + - atmel,at91sam9n12 + - atmel,at91sam9rl + - atmel,at91sam9xe + - atmel,at91sam9x60 + - const: atmel,at91sam9 + + - items: + - enum: + - atmel,at91sam9g15 + - atmel,at91sam9g25 + - atmel,at91sam9g35 + - atmel,at91sam9x25 + - atmel,at91sam9x35 + - const: atmel,at91sam9x5 + - const: atmel,at91sam9 + + - items: + - const: atmel,sama5d27 + - const: atmel,sama5d2 + - const: atmel,sama5 + + - description: Nattis v2 board with Natte v2 power board + items: + - const: axentia,nattis-2 + - const: axentia,natte-2 + - const: axentia,linea + - const: atmel,sama5d31 + - const: atmel,sama5d3 + - const: atmel,sama5 + + - description: TSE-850 v3 board + items: + - const: axentia,tse850v3 + - const: axentia,linea + - const: atmel,sama5d31 + - const: atmel,sama5d3 + - const: atmel,sama5 + + - items: + - const: axentia,linea + - const: atmel,sama5d31 + - const: atmel,sama5d3 + - const: atmel,sama5 + + - items: + - enum: + - atmel,sama5d31 + - atmel,sama5d33 + - atmel,sama5d34 + - atmel,sama5d35 + - atmel,sama5d36 + - const: atmel,sama5d3 + - const: atmel,sama5 + + - items: + - enum: + - atmel,sama5d41 + - atmel,sama5d42 + - atmel,sama5d43 + - atmel,sama5d44 + - const: atmel,sama5d4 + - const: atmel,sama5 + + - items: + - enum: + - atmel,sams70j19 + - atmel,sams70j20 + - atmel,sams70j21 + - atmel,sams70n19 + - atmel,sams70n20 + - atmel,sams70n21 + - atmel,sams70q19 + - atmel,sams70q20 + - atmel,sams70q21 + - const: atmel,sams70 + - const: atmel,samv7 + + - items: + - enum: + - atmel,samv70j19 + - atmel,samv70j20 + - atmel,samv70n19 + - atmel,samv70n20 + - atmel,samv70q19 + - atmel,samv70q20 + - const: atmel,samv70 + - const: atmel,samv7 + + - items: + - enum: + - atmel,samv71j19 + - atmel,samv71j20 + - atmel,samv71j21 + - atmel,samv71n19 + - atmel,samv71n20 + - atmel,samv71n21 + - atmel,samv71q19 + - atmel,samv71q20 + - atmel,samv71q21 + - const: atmel,samv71 + - const: atmel,samv7 + +... diff --git a/Documentation/devicetree/bindings/arm/emtrion.txt b/Documentation/devicetree/bindings/arm/emtrion.txt deleted file mode 100644 index 83329aefc483..000000000000 --- a/Documentation/devicetree/bindings/arm/emtrion.txt +++ /dev/null @@ -1,12 +0,0 @@ -Emtrion Devicetree Bindings -=========================== - -emCON Series: -------------- - -Required root node properties - - compatible: - - "emtrion,emcon-mx6", "fsl,imx6q"; : emCON-MX6D or emCON-MX6Q SoM - - "emtrion,emcon-mx6-avari", "fsl,imx6q"; : emCON-MX6D or emCON-MX6Q SoM on Avari Base - - "emtrion,emcon-mx6", "fsl,imx6dl"; : emCON-MX6S or emCON-MX6DL SoM - - "emtrion,emcon-mx6-avari", "fsl,imx6dl"; : emCON-MX6S or emCON-MX6DL SoM on Avari Base diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt index f378922906f6..a575e42f7fec 100644 --- a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt @@ -145,6 +145,16 @@ Optional Child nodes: - Data cells of ocotp: Detailed bindings are described in bindings/nvmem/nvmem.txt +Watchdog bindings based on SCU Message Protocol +------------------------------------------------------------ + +Required properties: +- compatible: should be: + "fsl,imx8qxp-sc-wdt" + followed by "fsl,imx-sc-wdt"; +Optional properties: +- timeout-sec: contains the watchdog timeout in seconds. + Example (imx8qxp): ------------- aliases { @@ -207,6 +217,11 @@ firmware { rtc: rtc { compatible = "fsl,imx8qxp-sc-rtc"; }; + + watchdog { + compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt"; + timeout-sec = <60>; + }; }; }; diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 407138ebc0d0..7294ac36f4c0 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -15,6 +15,13 @@ properties: const: '/' compatible: oneOf: + - description: i.MX1 based Boards + items: + - enum: + - armadeus,imx1-apf9328 + - fsl,imx1ads + - const: fsl,imx1 + - description: i.MX23 based Boards items: - enum: @@ -51,6 +58,25 @@ properties: - const: i2se,duckbill-2 - const: fsl,imx28 + - description: i.MX31 based Boards + items: + - enum: + - buglabs,imx31-bug + - logicpd,imx31-lite + - const: fsl,imx31 + + - description: i.MX35 based Boards + items: + - enum: + - fsl,imx35-pdk + - const: fsl,imx35 + + - description: i.MX35 Eukrea CPUIMX35 Board + items: + - const: eukrea,mbimxsd35-baseboard + - const: eukrea,cpuimx35 + - const: fsl,imx35 + - description: i.MX50 based Boards items: - enum: @@ -80,6 +106,8 @@ properties: - description: i.MX6Q based Boards items: - enum: + - emtrion,emcon-mx6 # emCON-MX6D or emCON-MX6Q SoM + - emtrion,emcon-mx6-avari # emCON-MX6D or emCON-MX6Q SoM on Avari Base - fsl,imx6q-arm2 - fsl,imx6q-sabreauto - fsl,imx6q-sabrelite @@ -99,6 +127,8 @@ properties: items: - enum: - eckelmann,imx6dl-ci4x10 + - emtrion,emcon-mx6 # emCON-MX6S or emCON-MX6DL SoM + - emtrion,emcon-mx6-avari # emCON-MX6S or emCON-MX6DL SoM on Avari Base - fsl,imx6dl-sabreauto # i.MX6 DualLite/Solo SABRE Automotive Board - fsl,imx6dl-sabresd # i.MX6 DualLite SABRE Smart Device Board - technologic,imx6dl-ts4900 @@ -156,6 +186,7 @@ properties: items: - enum: - fsl,imx7d-sdb # i.MX7 SabreSD Board + - novtech,imx7d-meerkat96 # i.MX7 Meerkat96 Board - tq,imx7d-mba7 # i.MX7D TQ MBa7 with TQMa7D SoM - zii,imx7d-rpu2 # ZII RPU2 Board - const: fsl,imx7d @@ -171,12 +202,25 @@ properties: - const: compulab,cl-som-imx7 - const: fsl,imx7d + - description: i.MX7ULP based Boards + items: + - enum: + - fsl,imx7ulp-evk # i.MX7ULP Evaluation Kit + - const: fsl,imx7ulp + - description: i.MX8MM based Boards items: - enum: - fsl,imx8mm-evk # i.MX8MM EVK Board - const: fsl,imx8mm + - description: i.MX8MQ based Boards + items: + - enum: + - fsl,imx8mq-evk # i.MX8MQ EVK Board + - purism,librem5-devkit # Purism Librem5 devkit + - const: fsl,imx8mq + - description: i.MX8QXP based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/mediatek.txt b/Documentation/devicetree/bindings/arm/mediatek.txt deleted file mode 100644 index 56ac7896d6d8..000000000000 --- a/Documentation/devicetree/bindings/arm/mediatek.txt +++ /dev/null @@ -1,89 +0,0 @@ -MediaTek SoC based Platforms Device Tree Bindings - -Boards with a MediaTek SoC shall have the following property: - -Required root node property: - -compatible: Must contain one of - "mediatek,mt2701" - "mediatek,mt2712" - "mediatek,mt6580" - "mediatek,mt6589" - "mediatek,mt6592" - "mediatek,mt6755" - "mediatek,mt6765" - "mediatek,mt6795" - "mediatek,mt6797" - "mediatek,mt7622" - "mediatek,mt7623" - "mediatek,mt7629" - "mediatek,mt8127" - "mediatek,mt8135" - "mediatek,mt8173" - "mediatek,mt8183" - - -Supported boards: - -- Evaluation board for MT2701: - Required root node properties: - - compatible = "mediatek,mt2701-evb", "mediatek,mt2701"; -- Evaluation board for MT2712: - Required root node properties: - - compatible = "mediatek,mt2712-evb", "mediatek,mt2712"; -- Evaluation board for MT6580: - Required root node properties: - - compatible = "mediatek,mt6580-evbp1", "mediatek,mt6580"; -- bq Aquaris5 smart phone: - Required root node properties: - - compatible = "mundoreader,bq-aquaris5", "mediatek,mt6589"; -- Evaluation board for MT6592: - Required root node properties: - - compatible = "mediatek,mt6592-evb", "mediatek,mt6592"; -- Evaluation phone for MT6755(Helio P10): - Required root node properties: - - compatible = "mediatek,mt6755-evb", "mediatek,mt6755"; -- Evaluation board for MT6765(Helio P22): - Required root node properties: - - compatible = "mediatek,mt6765-evb", "mediatek,mt6765"; -- Evaluation board for MT6795(Helio X10): - Required root node properties: - - compatible = "mediatek,mt6795-evb", "mediatek,mt6795"; -- Evaluation board for MT6797(Helio X20): - Required root node properties: - - compatible = "mediatek,mt6797-evb", "mediatek,mt6797"; -- Mediatek X20 Development Board: - Required root node properties: - - compatible = "archermind,mt6797-x20-dev", "mediatek,mt6797"; -- Reference board variant 1 for MT7622: - Required root node properties: - - compatible = "mediatek,mt7622-rfb1", "mediatek,mt7622"; -- Bananapi BPI-R64 for MT7622: - Required root node properties: - - compatible = "bananapi,bpi-r64", "mediatek,mt7622"; -- Reference board for MT7623a with eMMC: - Required root node properties: - - compatible = "mediatek,mt7623a-rfb-emmc", "mediatek,mt7623"; -- Reference board for MT7623a with NAND: - Required root node properties: - - compatible = "mediatek,mt7623a-rfb-nand", "mediatek,mt7623"; -- Reference board for MT7623n with eMMC: - Required root node properties: - - compatible = "mediatek,mt7623n-rfb-emmc", "mediatek,mt7623"; -- Bananapi BPI-R2 board: - - compatible = "bananapi,bpi-r2", "mediatek,mt7623"; -- Reference board for MT7629: - Required root node properties: - - compatible = "mediatek,mt7629-rfb", "mediatek,mt7629"; -- MTK mt8127 tablet moose EVB: - Required root node properties: - - compatible = "mediatek,mt8127-moose", "mediatek,mt8127"; -- MTK mt8135 tablet EVB: - Required root node properties: - - compatible = "mediatek,mt8135-evbp1", "mediatek,mt8135"; -- MTK mt8173 tablet EVB: - Required root node properties: - - compatible = "mediatek,mt8173-evb", "mediatek,mt8173"; -- Evaluation board for MT8183: - Required root node properties: - - compatible = "mediatek,mt8183-evb", "mediatek,mt8183"; diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml new file mode 100644 index 000000000000..a4ad2eb926f9 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/mediatek.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek SoC based Platforms Device Tree Bindings + +maintainers: + - Sean Wang <sean.wang@mediatek.com> + - Matthias Brugger <matthias.bgg@gmail.com> +description: | + Boards with a MediaTek SoC shall have the following properties. + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - enum: + - mediatek,mt2701-evb + - const: mediatek,mt2701 + + - items: + - enum: + - mediatek,mt2712-evb + - const: mediatek,mt2712 + - items: + - enum: + - mediatek,mt6580-evbp1 + - const: mediatek,mt6580 + - items: + - enum: + - mundoreader,bq-aquaris5 + - const: mediatek,mt6589 + - items: + - enum: + - mediatek,mt6592-evb + - const: mediatek,mt6592 + - items: + - enum: + - mediatek,mt6755-evb + - const: mediatek,mt6755 + - items: + - enum: + - mediatek,mt6765-evb + - const: mediatek,mt6765 + - items: + - enum: + - mediatek,mt6795-evb + - const: mediatek,mt6795 + - items: + - enum: + - archermind,mt6797-x20-dev + - mediatek,mt6797-evb + - const: mediatek,mt6797 + - items: + - enum: + - bananapi,bpi-r64 + - mediatek,mt7622-rfb1 + - const: mediatek,mt7622 + - items: + - enum: + - mediatek,mt7623a-rfb-emmc + - mediatek,mt7623a-rfb-nand + - mediatek,mt7623n-rfb-emmc + - bananapi,bpi-r2 + - const: mediatek,mt7623 + + - items: + - enum: + - mediatek,mt7629-rfb + - const: mediatek,mt7629 + - items: + - enum: + - mediatek,mt8127-moose + - const: mediatek,mt8127 + - items: + - enum: + - mediatek,mt8135-evbp1 + - const: mediatek,mt8135 + - items: + - enum: + - mediatek,mt8173-evb + - const: mediatek,mt8173 + - items: + - enum: + - mediatek,mt8183-evb + - const: mediatek,mt8183 +... diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt index f3cef1a6d95c..07c9d813465c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt @@ -10,6 +10,7 @@ Required Properties: - "mediatek,mt7622-audsys", "syscon" - "mediatek,mt7623-audsys", "mediatek,mt2701-audsys", "syscon" - "mediatek,mt8183-audiosys", "syscon" + - "mediatek,mt8516-audsys", "syscon" - #clock-cells: Must be 1 The AUDSYS controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index 1c1e48fd94b5..b301f753ed2c 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -160,6 +160,9 @@ Boards: - AM335X phyCORE-AM335x: Development kit compatible = "phytec,am335x-pcm-953", "phytec,am335x-phycore-som", "ti,am33xx" +- AM335x phyBOARD-REGOR: Single Board Computer + compatible = "phytec,am335x-regor", "phytec,am335x-phycore-som", "ti,am33xx" + - AM335X UC-8100-ME-T: Communication-centric industrial computing platform compatible = "moxa,uc-8100-me-t", "ti,am33xx"; diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml index 19f379863d50..08c923f8c257 100644 --- a/Documentation/devicetree/bindings/arm/renesas.yaml +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -106,6 +106,14 @@ properties: - description: RZ/G2M (R8A774A1) items: + - enum: + - hoperun,hihope-rzg2m # HopeRun HiHope RZ/G2M platform + - const: renesas,r8a774a1 + + - items: + - enum: + - hoperun,hihope-rzg2-ex # HopeRun expansion board for HiHope RZ/G2 platforms + - const: hoperun,hihope-rzg2m - const: renesas,r8a774a1 - description: RZ/G2E (R8A774C0) diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index 5c6bbf10abc9..34865042f4e4 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -316,6 +316,19 @@ properties: - const: haoyu,marsboard-rk3066 - const: rockchip,rk3066a + - description: Hugsun X99 TV Box + items: + - const: hugsun,x99 + - const: rockchip,rk3399 + + - description: Khadas Edge series boards + items: + - enum: + - khadas,edge + - khadas,edge-captain + - khadas,edge-v + - const: rockchip,rk3399 + - description: mqmaker MiQi items: - const: mqmaker,miqi diff --git a/Documentation/devicetree/bindings/arm/stm32/mlahb.txt b/Documentation/devicetree/bindings/arm/stm32/mlahb.txt new file mode 100644 index 000000000000..25307aa1eb9b --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32/mlahb.txt @@ -0,0 +1,37 @@ +ML-AHB interconnect bindings + +These bindings describe the STM32 SoCs ML-AHB interconnect bus which connects +a Cortex-M subsystem with dedicated memories. +The MCU SRAM and RETRAM memory parts can be accessed through different addresses +(see "RAM aliases" in [1]) using different buses (see [2]) : balancing the +Cortex-M firmware accesses among those ports allows to tune the system +performance. + +[1]: https://www.st.com/resource/en/reference_manual/dm00327659.pdf +[2]: https://wiki.st.com/stm32mpu/wiki/STM32MP15_RAM_mapping + +Required properties: +- compatible: should be "simple-bus" +- dma-ranges: describes memory addresses translation between the local CPU and + the remote Cortex-M processor. Each memory region, is declared with + 3 parameters: + - param 1: device base address (Cortex-M processor address) + - param 2: physical base address (local CPU address) + - param 3: size of the memory region. + +The Cortex-M remote processor accessed via the mlahb interconnect is described +by a child node. + +Example: +mlahb { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + dma-ranges = <0x00000000 0x38000000 0x10000>, + <0x10000000 0x10000000 0x60000>, + <0x30000000 0x30000000 0x60000>; + + m4_rproc: m4@10000000 { + ... + }; +}; diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.txt b/Documentation/devicetree/bindings/arm/stm32/stm32.txt deleted file mode 100644 index 6808ed9ddfd5..000000000000 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.txt +++ /dev/null @@ -1,10 +0,0 @@ -STMicroelectronics STM32 Platforms Device Tree Bindings - -Each device tree must specify which STM32 SoC it uses, -using one of the following compatible strings: - - st,stm32f429 - st,stm32f469 - st,stm32f746 - st,stm32h743 - st,stm32mp157 diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml new file mode 100644 index 000000000000..4d194f1eb03a --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/stm32/stm32.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32 Platforms Device Tree Bindings + +maintainers: + - Alexandre Torgue <alexandre.torgue@st.com> + +properties: + compatible: + oneOf: + - items: + - const: st,stm32f429 + + - items: + - const: st,stm32f469 + + - items: + - const: st,stm32f746 + + - items: + - const: st,stm32h743 + + - items: + - enum: + - arrow,stm32mp157a-avenger96 # Avenger96 + - const: st,stm32mp157 +... diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 285f4fc8519d..000a00d12d6a 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -263,7 +263,7 @@ properties: - description: ICNova A20 SWAC items: - - const: swac,icnova-a20-swac + - const: incircuit,icnova-a20-swac - const: incircuit,icnova-a20 - const: allwinner,sun7i-a20 diff --git a/Documentation/devicetree/bindings/arm/ti/k3.txt b/Documentation/devicetree/bindings/arm/ti/k3.txt index 6a059cabb2da..333e7256126a 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.txt +++ b/Documentation/devicetree/bindings/arm/ti/k3.txt @@ -13,6 +13,9 @@ architecture it uses, using one of the following compatible values: - AM654 compatible = "ti,am654"; +- J721E + compatible = "ti,j721e"; + Boards ------ diff --git a/Documentation/devicetree/bindings/arm/xen.txt b/Documentation/devicetree/bindings/arm/xen.txt index c9b9321434ea..db5c56db30ec 100644 --- a/Documentation/devicetree/bindings/arm/xen.txt +++ b/Documentation/devicetree/bindings/arm/xen.txt @@ -54,7 +54,7 @@ hypervisor { }; The format and meaning of the "xen,uefi-*" parameters are similar to those in -Documentation/arm/uefi.txt, which are provided by the regular UEFI stub. However +Documentation/arm/uefi.rst, which are provided by the regular UEFI stub. However they differ because they are provided by the Xen hypervisor, together with a set of UEFI runtime services implemented via hypercalls, see http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,platform.h.html. diff --git a/Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml b/Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml new file mode 100644 index 000000000000..be32f087c529 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/allwinner,sun8i-a23-rsb.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/allwinner,sun8i-a23-rsb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A23 RSB Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + compatible: + oneOf: + - const: allwinner,sun8i-a23-rsb + - items: + - const: allwinner,sun8i-a83t-rsb + - const: allwinner,sun8i-a23-rsb + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + clock-frequency: + minimum: 1 + maximum: 20000000 + +patternProperties: + "^.*@[0-9a-fA-F]+$": + type: object + properties: + reg: + maxItems: 1 + + required: + - reg + +required: + - compatible + - reg + - interrupts + - clocks + - resets + +examples: + - | + rsb@1f03400 { + 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>; + + /* ... */ + }; + }; + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/bus/sunxi-rsb.txt b/Documentation/devicetree/bindings/bus/sunxi-rsb.txt deleted file mode 100644 index eb3ed628c6f1..000000000000 --- a/Documentation/devicetree/bindings/bus/sunxi-rsb.txt +++ /dev/null @@ -1,47 +0,0 @@ -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@1f03400 { - 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/clock/allwinner,sun4i-a10-ccu.yaml b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml new file mode 100644 index 000000000000..c935405458fe --- /dev/null +++ b/Documentation/devicetree/bindings/clock/allwinner,sun4i-a10-ccu.yaml @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/allwinner,sun4i-a10-ccu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner Clock Control Unit Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#clock-cells": + const: 1 + + "#reset-cells": + const: 1 + + compatible: + enum: + - allwinner,sun4i-a10-ccu + - allwinner,sun5i-a10s-ccu + - allwinner,sun5i-a13-ccu + - allwinner,sun6i-a31-ccu + - allwinner,sun7i-a20-ccu + - allwinner,sun8i-a23-ccu + - allwinner,sun8i-a33-ccu + - allwinner,sun8i-a83t-ccu + - allwinner,sun8i-a83t-r-ccu + - allwinner,sun8i-h3-ccu + - allwinner,sun8i-h3-r-ccu + - allwinner,sun8i-r40-ccu + - allwinner,sun8i-v3s-ccu + - allwinner,sun9i-a80-ccu + - allwinner,sun50i-a64-ccu + - allwinner,sun50i-a64-r-ccu + - allwinner,sun50i-h5-ccu + - allwinner,sun50i-h6-ccu + - allwinner,sun50i-h6-r-ccu + - allwinner,suniv-f1c100s-ccu + - nextthing,gr8-ccu + + reg: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 4 + items: + - description: High Frequency Oscillator (usually at 24MHz) + - description: Low Frequency Oscillator (usually at 32kHz) + - description: Internal Oscillator + - description: Peripherals PLL + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: hosc + - const: losc + - const: iosc + - const: pll-periph + +required: + - "#clock-cells" + - "#reset-cells" + - compatible + - reg + - clocks + - clock-names + +if: + properties: + compatible: + enum: + - allwinner,sun8i-a83t-r-ccu + - allwinner,sun8i-h3-r-ccu + - allwinner,sun50i-a64-r-ccu + - allwinner,sun50i-h6-r-ccu + +then: + properties: + clocks: + minItems: 4 + maxItems: 4 + + clock-names: + minItems: 4 + maxItems: 4 + +else: + if: + properties: + compatible: + const: allwinner,sun50i-h6-ccu + + then: + properties: + clocks: + minItems: 3 + maxItems: 3 + + clock-names: + minItems: 3 + maxItems: 3 + + else: + properties: + clocks: + minItems: 2 + maxItems: 2 + + clock-names: + minItems: 2 + maxItems: 2 + +additionalProperties: false + +examples: + - | + ccu: clock@1c20000 { + compatible = "allwinner,sun8i-h3-ccu"; + reg = <0x01c20000 0x400>; + clocks = <&osc24M>, <&osc32k>; + clock-names = "hosc", "losc"; + #clock-cells = <1>; + #reset-cells = <1>; + }; + + - | + r_ccu: clock@1f01400 { + compatible = "allwinner,sun50i-a64-r-ccu"; + reg = <0x01f01400 0x100>; + clocks = <&osc24M>, <&osc32k>, <&iosc>, <&ccu 11>; + clock-names = "hosc", "losc", "iosc", "pll-periph"; + #clock-cells = <1>; + #reset-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt index 5c8b105be4d6..6eaa52092313 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt @@ -10,6 +10,7 @@ Required Properties: "amlogic,gxl-clkc" for GXL and GXM SoC, "amlogic,axg-clkc" for AXG SoC. "amlogic,g12a-clkc" for G12A SoC. + "amlogic,g12b-clkc" for G12B SoC. - clocks : list of clock phandle, one for each entry clock-names. - clock-names : should contain the following: * "xtal": the platform xtal diff --git a/Documentation/devicetree/bindings/clock/at91-clock.txt b/Documentation/devicetree/bindings/clock/at91-clock.txt index b520280e33ff..13f45db3b66d 100644 --- a/Documentation/devicetree/bindings/clock/at91-clock.txt +++ b/Documentation/devicetree/bindings/clock/at91-clock.txt @@ -9,10 +9,11 @@ Slow Clock controller: Required properties: - compatible : shall be one of the following: "atmel,at91sam9x5-sckc", - "atmel,sama5d3-sckc" or - "atmel,sama5d4-sckc": + "atmel,sama5d3-sckc", + "atmel,sama5d4-sckc" or + "microchip,sam9x60-sckc": at91 SCKC (Slow Clock Controller) -- #clock-cells : shall be 0. +- #clock-cells : shall be 1 for "microchip,sam9x60-sckc" otherwise shall be 0. - clocks : shall be the input parent clock phandle for the clock. Optional properties: diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt b/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt new file mode 100644 index 000000000000..3041657e2f96 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/brcm,bcm63xx-clocks.txt @@ -0,0 +1,22 @@ +Gated Clock Controller Bindings for MIPS based BCM63XX SoCs + +Required properties: +- compatible: must be one of: + "brcm,bcm3368-clocks" + "brcm,bcm6328-clocks" + "brcm,bcm6358-clocks" + "brcm,bcm6362-clocks" + "brcm,bcm6368-clocks" + "brcm,bcm63268-clocks" + +- reg: Address and length of the register set +- #clock-cells: must be <1> + + +Example: + +clkctl: clock-controller@10000004 { + compatible = "brcm,bcm6328-clocks"; + reg = <0x10000004 0x4>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt index b8d8ef3bdc5f..52a064c789ee 100644 --- a/Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt +++ b/Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt @@ -40,6 +40,7 @@ Optional properties: input audio clocks from host system. - ln-psia1-mclk, ln-psia2-mclk : Optional input audio clocks from external connector. + - ln-spdif-mclk : Optional input audio clock from SPDIF. - ln-spdif-clkout : Optional input audio clock from SPDIF. - ln-adat-mclk : Optional input audio clock from ADAT. - ln-pmic-32k : On board fixed clock. diff --git a/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt b/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt index 796c260c183d..d8f5c490f893 100644 --- a/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt +++ b/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt @@ -59,6 +59,7 @@ Required properties: "marvell,dove-core-clock" - for Dove SoC core clocks "marvell,kirkwood-core-clock" - for Kirkwood SoC (except mv88f6180) "marvell,mv88f6180-core-clock" - for Kirkwood MV88f6180 SoC + "marvell,mv98dx1135-core-clock" - for Kirkwood 98dx1135 SoC "marvell,mv88f5181-core-clock" - for Orion MV88F5181 SoC "marvell,mv88f5182-core-clock" - for Orion MV88F5182 SoC "marvell,mv88f5281-core-clock" - for Orion MV88F5281 SoC diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.txt b/Documentation/devicetree/bindings/clock/qcom,gpucc.txt index 4e5215ef1acd..269afe8a757e 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.txt @@ -2,13 +2,15 @@ Qualcomm Graphics Clock & Reset Controller Binding -------------------------------------------------- Required properties : -- compatible : shall contain "qcom,sdm845-gpucc" +- compatible : shall contain "qcom,sdm845-gpucc" or "qcom,msm8998-gpucc" - reg : shall contain base register location and length - #clock-cells : from common clock binding, shall contain 1 - #reset-cells : from common reset binding, shall contain 1 - #power-domain-cells : from generic power domain binding, shall contain 1 - clocks : shall contain the XO clock + shall contain the gpll0 out main clock (msm8998) - clock-names : shall be "xo" + shall be "gpll0" (msm8998) Example: gpucc: clock-controller@5090000 { diff --git a/Documentation/devicetree/bindings/clock/renesas,r9a06g032-sysctrl.txt b/Documentation/devicetree/bindings/clock/renesas,r9a06g032-sysctrl.txt index d60b99756bb9..aed713cf0831 100644 --- a/Documentation/devicetree/bindings/clock/renesas,r9a06g032-sysctrl.txt +++ b/Documentation/devicetree/bindings/clock/renesas,r9a06g032-sysctrl.txt @@ -13,6 +13,7 @@ Required Properties: - external (optional) RGMII_REFCLK - clock-names: Must be: clock-names = "mclk", "rtc", "jtag", "rgmii_ref_ext"; + - #power-domain-cells: Must be 0 Examples -------- @@ -27,6 +28,7 @@ Examples clocks = <&ext_mclk>, <&ext_rtc_clk>, <&ext_jtag_clk>, <&ext_rgmii_ref>; clock-names = "mclk", "rtc", "jtag", "rgmii_ref_ext"; + #power-domain-cells = <0>; }; - Other nodes can use the clocks provided by SYSCTRL as in: @@ -38,6 +40,7 @@ Examples interrupts = <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>; reg-shift = <2>; reg-io-width = <4>; - clocks = <&sysctrl R9A06G032_CLK_UART0>; - clock-names = "baudclk"; + clocks = <&sysctrl R9A06G032_CLK_UART0>, <&sysctrl R9A06G032_HCLK_UART0>; + clock-names = "baudclk", "apb_pclk"; + power-domains = <&sysctrl>; }; diff --git a/Documentation/devicetree/bindings/clock/silabs,si5341.txt b/Documentation/devicetree/bindings/clock/silabs,si5341.txt new file mode 100644 index 000000000000..a70c333e4cd4 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/silabs,si5341.txt @@ -0,0 +1,162 @@ +Binding for Silicon Labs Si5341 and Si5340 programmable i2c clock generator. + +Reference +[1] Si5341 Data Sheet + https://www.silabs.com/documents/public/data-sheets/Si5341-40-D-DataSheet.pdf +[2] Si5341 Reference Manual + https://www.silabs.com/documents/public/reference-manuals/Si5341-40-D-RM.pdf + +The Si5341 and Si5340 are programmable i2c clock generators with up to 10 output +clocks. The chip contains a PLL that sources 5 (or 4) multisynth clocks, which +in turn can be directed to any of the 10 (or 4) outputs through a divider. +The internal structure of the clock generators can be found in [2]. + +The driver can be used in "as is" mode, reading the current settings from the +chip at boot, in case you have a (pre-)programmed device. If the PLL is not +configured when the driver probes, it assumes the driver must fully initialize +it. + +The device type, speed grade and revision are determined runtime by probing. + +The driver currently only supports XTAL input mode, and does not support any +fancy input configurations. They can still be programmed into the chip and +the driver will leave them "as is". + +==I2C device node== + +Required properties: +- compatible: shall be one of the following: + "silabs,si5340" - Si5340 A/B/C/D + "silabs,si5341" - Si5341 A/B/C/D +- reg: i2c device address, usually 0x74 +- #clock-cells: from common clock binding; shall be set to 2. + The first value is "0" for outputs, "1" for synthesizers. + The second value is the output or synthesizer index. +- clocks: from common clock binding; list of parent clock handles, + corresponding to inputs. Use a fixed clock for the "xtal" input. + At least one must be present. +- clock-names: One of: "xtal", "in0", "in1", "in2" +- vdd-supply: Regulator node for VDD + +Optional properties: +- vdda-supply: Regulator node for VDDA +- vdds-supply: Regulator node for VDDS +- silabs,pll-m-num, silabs,pll-m-den: Numerator and denominator for PLL + feedback divider. Must be such that the PLL output is in the valid range. For + example, to create 14GHz from a 48MHz xtal, use m-num=14000 and m-den=48. Only + the fraction matters, using 3500 and 12 will deliver the exact same result. + If these are not specified, and the PLL is not yet programmed when the driver + probes, the PLL will be set to 14GHz. +- silabs,reprogram: When present, the driver will always assume the device must + be initialized, and always performs the soft-reset routine. Since this will + temporarily stop all output clocks, don't do this if the chip is generating + the CPU clock for example. +- interrupts: Interrupt for INTRb pin. +- #address-cells: shall be set to 1. +- #size-cells: shall be set to 0. + + +== Child nodes: Outputs == + +The child nodes list the output clocks. + +Each of the clock outputs can be overwritten individually by using a child node. +If a child node for a clock output is not set, the configuration remains +unchanged. + +Required child node properties: +- reg: number of clock output. + +Optional child node properties: +- vdd-supply: Regulator node for VDD for this output. The driver selects default + values for common-mode and amplitude based on the voltage. +- silabs,format: Output format, one of: + 1 = differential (defaults to LVDS levels) + 2 = low-power (defaults to HCSL levels) + 4 = LVCMOS +- silabs,common-mode: Manually override output common mode, see [2] for values +- silabs,amplitude: Manually override output amplitude, see [2] for values +- silabs,synth-master: boolean. If present, this output is allowed to change the + multisynth frequency dynamically. +- silabs,silabs,disable-high: boolean. If set, the clock output is driven HIGH + when disabled, otherwise it's driven LOW. + +==Example== + +/* 48MHz reference crystal */ +ref48: ref48M { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <48000000>; +}; + +i2c-master-node { + /* Programmable clock (for logic) */ + si5341: clock-generator@74 { + reg = <0x74>; + compatible = "silabs,si5341"; + #clock-cells = <2>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&ref48>; + clock-names = "xtal"; + + silabs,pll-m-num = <14000>; /* PLL at 14.0 GHz */ + silabs,pll-m-den = <48>; + silabs,reprogram; /* Chips are not programmed, always reset */ + + out@0 { + reg = <0>; + silabs,format = <1>; /* LVDS 3v3 */ + silabs,common-mode = <3>; + silabs,amplitude = <3>; + silabs,synth-master; + }; + + /* + * Output 6 configuration: + * LVDS 1v8 + */ + out@6 { + reg = <6>; + silabs,format = <1>; /* LVDS 1v8 */ + silabs,common-mode = <13>; + silabs,amplitude = <3>; + }; + + /* + * Output 8 configuration: + * HCSL 3v3 + */ + out@8 { + reg = <8>; + silabs,format = <2>; + silabs,common-mode = <11>; + silabs,amplitude = <3>; + }; + }; +}; + +some-video-node { + /* Standard clock bindings */ + clock-names = "pixel"; + clocks = <&si5341 0 7>; /* Output 7 */ + + /* Set output 7 to use syntesizer 3 as its parent */ + assigned-clocks = <&si5341 0 7>, <&si5341 1 3>; + assigned-clock-parents = <&si5341 1 3>; + /* Set output 7 to 148.5 MHz using a synth frequency of 594 MHz */ + assigned-clock-rates = <148500000>, <594000000>; +}; + +some-audio-node { + clock-names = "i2s-clk"; + clocks = <&si5341 0 0>; + /* + * since output 0 is a synth-master, the synth will be automatically set + * to an appropriate frequency when the audio driver requests another + * frequency. We give control over synth 2 to this output here. + */ + assigned-clocks = <&si5341 0 0>; + assigned-clock-parents = <&si5341 1 2>; +}; diff --git a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt deleted file mode 100644 index e3bd88ae456b..000000000000 --- a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt +++ /dev/null @@ -1,62 +0,0 @@ -Allwinner Clock Control Unit Binding ------------------------------------- - -Required properties : -- compatible: must contain one of the following compatibles: - - "allwinner,sun4i-a10-ccu" - - "allwinner,sun5i-a10s-ccu" - - "allwinner,sun5i-a13-ccu" - - "allwinner,sun6i-a31-ccu" - - "allwinner,sun7i-a20-ccu" - - "allwinner,sun8i-a23-ccu" - - "allwinner,sun8i-a33-ccu" - - "allwinner,sun8i-a83t-ccu" - - "allwinner,sun8i-a83t-r-ccu" - - "allwinner,sun8i-h3-ccu" - - "allwinner,sun8i-h3-r-ccu" -+ - "allwinner,sun8i-r40-ccu" - - "allwinner,sun8i-v3s-ccu" - - "allwinner,sun9i-a80-ccu" - - "allwinner,sun50i-a64-ccu" - - "allwinner,sun50i-a64-r-ccu" - - "allwinner,sun50i-h5-ccu" - - "allwinner,sun50i-h6-ccu" - - "allwinner,sun50i-h6-r-ccu" - - "allwinner,suniv-f1c100s-ccu" - - "nextthing,gr8-ccu" - -- reg: Must contain the registers base address and length -- clocks: phandle to the oscillators feeding the CCU. Two are needed: - - "hosc": the high frequency oscillator (usually at 24MHz) - - "losc": the low frequency oscillator (usually at 32kHz) - On the A83T, this is the internal 16MHz oscillator divided by 512 -- clock-names: Must contain the clock names described just above -- #clock-cells : must contain 1 -- #reset-cells : must contain 1 - -For the main CCU on H6, one more clock is needed: -- "iosc": the SoC's internal frequency oscillator - -For the PRCM CCUs on A83T/H3/A64/H6, two more clocks are needed: -- "pll-periph": the SoC's peripheral PLL from the main CCU -- "iosc": the SoC's internal frequency oscillator - -Example for generic CCU: -ccu: clock@1c20000 { - compatible = "allwinner,sun8i-h3-ccu"; - reg = <0x01c20000 0x400>; - clocks = <&osc24M>, <&osc32k>; - clock-names = "hosc", "losc"; - #clock-cells = <1>; - #reset-cells = <1>; -}; - -Example for PRCM CCU: -r_ccu: clock@1f01400 { - compatible = "allwinner,sun50i-a64-r-ccu"; - reg = <0x01f01400 0x100>; - clocks = <&osc24M>, <&osc32k>, <&iosc>, <&ccu CLK_PLL_PERIPH0>; - clock-names = "hosc", "losc", "iosc", "pll-periph"; - #clock-cells = <1>; - #reset-cells = <1>; -}; diff --git a/Documentation/devicetree/bindings/csky/pmu.txt b/Documentation/devicetree/bindings/csky/pmu.txt new file mode 100644 index 000000000000..728d05ca6a1c --- /dev/null +++ b/Documentation/devicetree/bindings/csky/pmu.txt @@ -0,0 +1,38 @@ +=============================== +C-SKY Performance Monitor Units +=============================== + +C-SKY Performance Monitor is designed for ck807/ck810/ck860 SMP soc and +it could count cpu's events for helping analysis performance issues. + +============================ +PMU node bindings definition +============================ + + Description: Describes PMU + + PROPERTIES + + - compatible + Usage: required + Value type: <string> + Definition: must be "csky,csky-pmu" + - interrupts + Usage: required + Value type: <u32 IRQ_TYPE_XXX> + Definition: must be pmu irq num defined by soc + - count-width + Usage: optional + Value type: <u32> + Definition: the width of pmu counter + +Examples: +--------- +#include <dt-bindings/interrupt-controller/irq.h> + + pmu: performace-monitor { + compatible = "csky,csky-pmu"; + interrupts = <23 IRQ_TYPE_EDGE_RISING>; + interrupt-parent = <&intc>; + count-width = <48>; + }; diff --git a/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml new file mode 100644 index 000000000000..47950fced28d --- /dev/null +++ b/Documentation/devicetree/bindings/display/allwinner,sun6i-a31-mipi-dsi.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun6i-a31-mipi-dsi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 MIPI-DSI Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#address-cells": true + "#size-cells": true + + compatible: + const: allwinner,sun6i-a31-mipi-dsi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: bus + - const: mod + + resets: + maxItems: 1 + + phys: + maxItems: 1 + + phy-names: + const: dphy + + port: + type: object + description: + A port node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. That + port should be the input endpoint, usually coming from the + associated TCON. + +patternProperties: + "^panel@[0-9]+$": true + +required: + - "#address-cells" + - "#size-cells" + - compatible + - reg + - interrupts + - clocks + - clock-names + - phys + - phy-names + - resets + - port + +additionalProperties: false + +examples: + - | + dsi0: dsi@1ca0000 { + compatible = "allwinner,sun6i-a31-mipi-dsi"; + reg = <0x01ca0000 0x1000>; + interrupts = <0 89 4>; + clocks = <&ccu 23>, <&ccu 96>; + clock-names = "bus", "mod"; + resets = <&ccu 4>; + phys = <&dphy0>; + phy-names = "dphy"; + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "bananapi,lhr050h41", "ilitek,ili9881c"; + reg = <0>; + power-gpios = <&pio 1 7 0>; /* PB07 */ + reset-gpios = <&r_pio 0 5 1>; /* PL05 */ + backlight = <&pwm_bl>; + }; + + port { + dsi0_in_tcon0: endpoint { + remote-endpoint = <&tcon0_out_dsi0>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/arm,komeda.txt b/Documentation/devicetree/bindings/display/arm,komeda.txt index 02b226532ebd..8513695ee47f 100644 --- a/Documentation/devicetree/bindings/display/arm,komeda.txt +++ b/Documentation/devicetree/bindings/display/arm,komeda.txt @@ -7,10 +7,13 @@ Required properties: - clocks: A list of phandle + clock-specifier pairs, one for each entry in 'clock-names' - clock-names: A list of clock names. It should contain: - - "mclk": for the main processor clock - - "pclk": for the APB interface clock + - "aclk": for the main processor clock - #address-cells: Must be 1 - #size-cells: Must be 0 +- iommus: configure the stream id to IOMMU, Must be configured if want to + enable iommu in display. for how to configure this node please reference + devicetree/bindings/iommu/arm,smmu-v3.txt, + devicetree/bindings/iommu/iommu.txt Required properties for sub-node: pipeline@nq Each device contains one or two pipeline sub-nodes (at least one), each @@ -20,7 +23,6 @@ pipeline node should provide properties: in 'clock-names' - clock-names: should contain: - "pxclk": pixel clock - - "aclk": AXI interface clock - port: each pipeline connect to an encoder input port. The connection is modeled using the OF graph bindings specified in @@ -42,12 +44,15 @@ Example: compatible = "arm,mali-d71"; reg = <0xc00000 0x20000>; interrupts = <0 168 4>; - clocks = <&dpu_mclk>, <&dpu_aclk>; - clock-names = "mclk", "pclk"; + clocks = <&dpu_aclk>; + clock-names = "aclk"; + iommus = <&smmu 0>, <&smmu 1>, <&smmu 2>, <&smmu 3>, + <&smmu 4>, <&smmu 5>, <&smmu 6>, <&smmu 7>, + <&smmu 8>, <&smmu 9>; dp0_pipe0: pipeline@0 { - clocks = <&fpgaosc2>, <&dpu_aclk>; - clock-names = "pxclk", "aclk"; + clocks = <&fpgaosc2>; + clock-names = "pxclk"; reg = <0>; port { @@ -58,8 +63,8 @@ Example: }; dp0_pipe1: pipeline@1 { - clocks = <&fpgaosc2>, <&dpu_aclk>; - clock-names = "pxclk", "aclk"; + clocks = <&fpgaosc2>; + clock-names = "pxclk"; reg = <1>; port { diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt index a41d280c3f9f..db680413e89c 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt @@ -12,10 +12,12 @@ following device-specific properties. Required properties: - compatible : Shall contain one or more of + - "renesas,r8a774a1-hdmi" for R8A774A1 (RZ/G2M) compatible HDMI TX - "renesas,r8a7795-hdmi" for R8A7795 (R-Car H3) compatible HDMI TX - "renesas,r8a7796-hdmi" for R8A7796 (R-Car M3-W) compatible HDMI TX - "renesas,r8a77965-hdmi" for R8A77965 (R-Car M3-N) compatible HDMI TX - - "renesas,rcar-gen3-hdmi" for the generic R-Car Gen3 compatible HDMI TX + - "renesas,rcar-gen3-hdmi" for the generic R-Car Gen3 and RZ/G2 compatible + HDMI TX When compatible with generic versions, nodes must list the SoC-specific version corresponding to the platform first, followed by the diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt index 900a884ad9f5..c6a196d0b075 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt +++ b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt @@ -9,6 +9,7 @@ Required properties: - compatible : Shall contain one of - "renesas,r8a7743-lvds" for R8A7743 (RZ/G1M) compatible LVDS encoders - "renesas,r8a7744-lvds" for R8A7744 (RZ/G1N) compatible LVDS encoders + - "renesas,r8a774a1-lvds" for R8A774A1 (RZ/G2M) compatible LVDS encoders - "renesas,r8a774c0-lvds" for R8A774C0 (RZ/G2E) compatible LVDS encoders - "renesas,r8a7790-lvds" for R8A7790 (R-Car H2) compatible LVDS encoders - "renesas,r8a7791-lvds" for R8A7791 (R-Car M2-W) compatible LVDS encoders @@ -45,14 +46,24 @@ OF graph bindings specified in Documentation/devicetree/bindings/graph.txt. Each port shall have a single endpoint. +Optional properties: + +- renesas,companion : phandle to the companion LVDS encoder. This property is + mandatory for the first LVDS encoder on D3 and E3 SoCs, and shall point to + the second encoder to be used as a companion in dual-link mode. It shall not + be set for any other LVDS encoder. + Example: lvds0: lvds@feb90000 { - compatible = "renesas,r8a7790-lvds"; - reg = <0 0xfeb90000 0 0x1c>; - clocks = <&cpg CPG_MOD 726>; - resets = <&cpg 726>; + compatible = "renesas,r8a77990-lvds"; + reg = <0 0xfeb90000 0 0x20>; + clocks = <&cpg CPG_MOD 727>; + power-domains = <&sysc R8A77990_PD_ALWAYS_ON>; + resets = <&cpg 727>; + + renesas,companion = <&lvds1>; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/bridge/sii902x.txt b/Documentation/devicetree/bindings/display/bridge/sii902x.txt index 72d2dc6c3e6b..2df44b7d3821 100644 --- a/Documentation/devicetree/bindings/display/bridge/sii902x.txt +++ b/Documentation/devicetree/bindings/display/bridge/sii902x.txt @@ -5,10 +5,44 @@ Required properties: - reg: i2c address of the bridge Optional properties: - - interrupts: describe the interrupt line used to inform the host + - interrupts: describe the interrupt line used to inform the host about hotplug events. - reset-gpios: OF device-tree gpio specification for RST_N pin. + HDMI audio properties: + - #sound-dai-cells: <0> or <1>. <0> if only i2s or spdif pin + is wired, <1> if the both are wired. HDMI audio is + configured only if this property is found. + - sil,i2s-data-lanes: Array of up to 4 integers with values of 0-3 + Each integer indicates which i2s pin is connected to which + audio fifo. The first integer selects i2s audio pin for the + first audio fifo#0 (HDMI channels 1&2), second for fifo#1 + (HDMI channels 3&4), and so on. There is 4 fifos and 4 i2s + pins (SD0 - SD3). Any i2s pin can be connected to any fifo, + but there can be no gaps. E.g. an i2s pin must be mapped to + fifo#0 and fifo#1 before mapping a channel to fifo#2. Default + value is <0>, describing SD0 pin beiging routed to hdmi audio + fifo #0. + - clocks: phandle and clock specifier for each clock listed in + the clock-names property + - clock-names: "mclk" + Describes SII902x MCLK input. MCLK is used to produce + HDMI audio CTS values. This property is required if + "#sound-dai-cells"-property is present. This property follows + Documentation/devicetree/bindings/clock/clock-bindings.txt + consumer binding. + + If HDMI audio is configured the sii902x device becomes an I2S + and/or spdif audio codec component (e.g a digital audio sink), + that can be used in configuring a full audio devices with + simple-card or audio-graph-card binding. See their binding + documents on how to describe the way the sii902x device is + connected to the rest of the audio system: + Documentation/devicetree/bindings/sound/simple-card.txt + Documentation/devicetree/bindings/sound/audio-graph-card.txt + Note: In case of the audio-graph-card binding the used port + index should be 3. + Optional subnodes: - video input: this subnode can contain a video input port node to connect the bridge to a display controller output (See this @@ -21,6 +55,12 @@ Example: compatible = "sil,sii9022"; reg = <0x39>; reset-gpios = <&pioA 1 0>; + + #sound-dai-cells = <0>; + sil,i2s-data-lanes = < 0 1 2 >; + clocks = <&mclk>; + clock-names = "mclk"; + ports { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.txt b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.txt index 37f0c04d5a28..d17d1e5820d7 100644 --- a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.txt +++ b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvd1024.txt @@ -28,6 +28,12 @@ Optional video port nodes: - port@1: Second LVDS input port - port@3: Second digital CMOS/TTL parallel output +The device can operate in single-link mode or dual-link mode. In single-link +mode, all pixels are received on port@0, and port@1 shall not contain any +endpoint. In dual-link mode, even-numbered pixels are received on port@0 and +odd-numbered pixels on port@1, and both port@0 and port@1 shall contain +endpoints. + Example: -------- diff --git a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.txt b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.txt index e3f6aa6a214d..583c5e9dbe6b 100644 --- a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.txt +++ b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358767.txt @@ -12,6 +12,7 @@ Optional properties: (active high shutdown input) - reset-gpios: OF device-tree gpio specification for RSTX pin (active low system reset) + - toshiba,hpd-pin: TC358767 GPIO pin number to which HPD is connected to (0 or 1) - ports: the ports node can contain video interface port nodes to connect to a DPI/DSI source and to an eDP/DP sink according to [1][2]: - port@0: DSI input port diff --git a/Documentation/devicetree/bindings/display/ingenic,lcd.txt b/Documentation/devicetree/bindings/display/ingenic,lcd.txt new file mode 100644 index 000000000000..7b536c8c6dde --- /dev/null +++ b/Documentation/devicetree/bindings/display/ingenic,lcd.txt @@ -0,0 +1,44 @@ +Ingenic JZ47xx LCD driver + +Required properties: +- compatible: one of: + * ingenic,jz4740-lcd + * ingenic,jz4725b-lcd +- reg: LCD registers location and length +- clocks: LCD pixclock and device clock specifiers. + The device clock is only required on the JZ4740. +- clock-names: "lcd_pclk" and "lcd" +- interrupts: Specifies the interrupt line the LCD controller is connected to. + +Example: + +panel { + compatible = "sharp,ls020b1dd01d"; + + backlight = <&backlight>; + power-supply = <&vcc>; + + port { + panel_input: endpoint { + remote-endpoint = <&panel_output>; + }; + }; +}; + + +lcd: lcd-controller@13050000 { + compatible = "ingenic,jz4725b-lcd"; + reg = <0x13050000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <31>; + + clocks = <&cgu JZ4725B_CLK_LCD>; + clock-names = "lcd"; + + port { + panel_output: endpoint { + remote-endpoint = <&panel_input>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/msm/dpu.txt b/Documentation/devicetree/bindings/display/msm/dpu.txt index ad2e8830324e..a61dd40f3792 100644 --- a/Documentation/devicetree/bindings/display/msm/dpu.txt +++ b/Documentation/devicetree/bindings/display/msm/dpu.txt @@ -28,6 +28,11 @@ Required properties: - #address-cells: number of address cells for the MDSS children. Should be 1. - #size-cells: Should be 1. - ranges: parent bus address space is the same as the child bus address space. +- interconnects : interconnect path specifier for MDSS according to + Documentation/devicetree/bindings/interconnect/interconnect.txt. Should be + 2 paths corresponding to 2 AXI ports. +- interconnect-names : MDSS will have 2 port names to differentiate between the + 2 interconnect paths defined with interconnect specifier. Optional properties: - assigned-clocks: list of clock specifiers for clocks needing rate assignment @@ -86,6 +91,11 @@ Example: interrupt-controller; #interrupt-cells = <1>; + interconnects = <&rsc_hlos MASTER_MDP0 &rsc_hlos SLAVE_EBI1>, + <&rsc_hlos MASTER_MDP1 &rsc_hlos SLAVE_EBI1>; + + interconnect-names = "mdp0-mem", "mdp1-mem"; + iommus = <&apps_iommu 0>; #address-cells = <2>; diff --git a/Documentation/devicetree/bindings/display/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt index 9ae946942720..af95586c898f 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi.txt +++ b/Documentation/devicetree/bindings/display/msm/dsi.txt @@ -88,6 +88,7 @@ Required properties: * "qcom,dsi-phy-28nm-8960" * "qcom,dsi-phy-14nm" * "qcom,dsi-phy-10nm" + * "qcom,dsi-phy-10nm-8998" - reg: Physical base address and length of the registers of PLL, PHY. Some revisions require the PHY regulator base address, whereas others require the PHY lane base address. See below for each PHY revision. diff --git a/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.txt b/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.txt new file mode 100644 index 000000000000..a30d63db3c8f --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/armadeus,st0700-adapt.txt @@ -0,0 +1,9 @@ +Armadeus ST0700 Adapt. A Santek ST0700I5Y-RBSLW 7.0" WVGA (800x480) TFT with +an adapter board. + +Required properties: +- compatible: "armadeus,st0700-adapt" +- power-supply: see panel-common.txt + +Optional properties: +- backlight: see panel-common.txt diff --git a/Documentation/devicetree/bindings/display/panel/edt,et-series.txt b/Documentation/devicetree/bindings/display/panel/edt,et-series.txt index f56b99ebd9be..be8684327ee4 100644 --- a/Documentation/devicetree/bindings/display/panel/edt,et-series.txt +++ b/Documentation/devicetree/bindings/display/panel/edt,et-series.txt @@ -6,6 +6,22 @@ Display bindings for EDT Display Technology Corp. Displays which are compatible with the simple-panel binding, which is specified in simple-panel.txt +3,5" QVGA TFT Panels +-------------------- ++-----------------+---------------------+-------------------------------------+ +| Identifier | compatbile | description | ++=================+=====================+=====================================+ +| ET035012DM6 | edt,et035012dm6 | 3.5" QVGA TFT LCD panel | ++-----------------+---------------------+-------------------------------------+ + +4,3" WVGA TFT Panels +-------------------- + ++-----------------+---------------------+-------------------------------------+ +| Identifier | compatbile | description | ++=================+=====================+=====================================+ +| ETM0430G0DH6 | edt,etm0430g0dh6 | 480x272 TFT Display | ++-----------------+---------------------+-------------------------------------+ 5,7" WVGA TFT Panels -------------------- diff --git a/Documentation/devicetree/bindings/display/panel/evervision,vgg804821.txt b/Documentation/devicetree/bindings/display/panel/evervision,vgg804821.txt new file mode 100644 index 000000000000..82d22e191ac3 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/evervision,vgg804821.txt @@ -0,0 +1,12 @@ +Evervision Electronics Co. Ltd. VGG804821 5.0" WVGA TFT LCD Panel + +Required properties: +- compatible: should be "evervision,vgg804821" +- power-supply: See simple-panel.txt + +Optional properties: +- backlight: See simple-panel.txt +- enable-gpios: See simple-panel.txt + +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/display/panel/friendlyarm,hd702e.txt b/Documentation/devicetree/bindings/display/panel/friendlyarm,hd702e.txt new file mode 100644 index 000000000000..6c9156fc3478 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/friendlyarm,hd702e.txt @@ -0,0 +1,32 @@ +FriendlyELEC HD702E 800x1280 LCD panel + +HD702E lcd is FriendlyELEC developed eDP LCD panel with 800x1280 +resolution. It has built in Goodix, GT9271 captive touchscreen +with backlight adjustable via PWM. + +Required properties: +- compatible: should be "friendlyarm,hd702e" +- power-supply: regulator to provide the supply voltage + +Optional properties: +- backlight: phandle of the backlight device attached to the panel + +Optional nodes: +- Video port for LCD panel input. + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. + +Example: + + panel { + compatible ="friendlyarm,hd702e", "simple-panel"; + backlight = <&backlight>; + power-supply = <&vcc3v3_sys>; + + port { + panel_in_edp: endpoint { + remote-endpoint = <&edp_out_panel>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/koe,tx14d24vm1bpa.txt b/Documentation/devicetree/bindings/display/panel/koe,tx14d24vm1bpa.txt new file mode 100644 index 000000000000..be7ac666807b --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/koe,tx14d24vm1bpa.txt @@ -0,0 +1,42 @@ +Kaohsiung Opto-Electronics Inc. 5.7" QVGA (320 x 240) TFT LCD panel + +Required properties: +- compatible: should be "koe,tx14d24vm1bpa" +- backlight: phandle of the backlight device attached to the panel +- power-supply: single regulator to provide the supply voltage + +Required nodes: +- port: Parallel port mapping to connect this display + +This panel needs single power supply voltage. Its backlight is conntrolled +via PWM signal. + +Example: +-------- + +Example device-tree definition when connected to iMX53 based board + + lcd_panel: lcd-panel { + compatible = "koe,tx14d24vm1bpa"; + backlight = <&backlight_lcd>; + power-supply = <®_3v3>; + + port { + lcd_panel_in: endpoint { + remote-endpoint = <&lcd_display_out>; + }; + }; + }; + +Then one needs to extend the dispX node: + + lcd_display: disp1 { + + port@1 { + reg = <1>; + + lcd_display_out: endpoint { + remote-endpoint = <&lcd_panel_in>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/osddisplays,osd101t2045-53ts.txt b/Documentation/devicetree/bindings/display/panel/osddisplays,osd101t2045-53ts.txt new file mode 100644 index 000000000000..85c0b2cacfda --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/osddisplays,osd101t2045-53ts.txt @@ -0,0 +1,11 @@ +One Stop Displays OSD101T2045-53TS 10.1" 1920x1200 panel + +Required properties: +- compatible: should be "osddisplays,osd101t2045-53ts" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding + +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/display/panel/osddisplays,osd101t2587-53ts.txt b/Documentation/devicetree/bindings/display/panel/osddisplays,osd101t2587-53ts.txt new file mode 100644 index 000000000000..9d88e96003fc --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/osddisplays,osd101t2587-53ts.txt @@ -0,0 +1,14 @@ +One Stop Displays OSD101T2587-53TS 10.1" 1920x1200 panel + +The panel is similar to OSD101T2045-53TS, but it needs additional +MIPI_DSI_TURN_ON_PERIPHERAL message from the host. + +Required properties: +- compatible: should be "osddisplays,osd101t2587-53ts" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding + +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/display/panel/samsung,s6e63m0.txt b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.txt new file mode 100644 index 000000000000..9fb9ebeef8e4 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e63m0.txt @@ -0,0 +1,33 @@ +Samsung s6e63m0 AMOLED LCD panel + +Required properties: + - compatible: "samsung,s6e63m0" + - reset-gpios: GPIO spec for reset pin + - vdd3-supply: VDD regulator + - vci-supply: VCI regulator + +The panel must obey rules for SPI slave device specified in document [1]. + +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/spi/spi-bus.txt +[2]: Documentation/devicetree/bindings/media/video-interfaces.txt + +Example: + + s6e63m0: display@0 { + compatible = "samsung,s6e63m0"; + reg = <0>; + reset-gpio = <&mp05 5 1>; + vdd3-supply = <&ldo12_reg>; + vci-supply = <&ldo11_reg>; + spi-max-frequency = <1200000>; + + port { + lcd_ep: endpoint { + remote-endpoint = <&fimd_ep>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.txt b/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.txt new file mode 100644 index 000000000000..dfb572f085eb --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/tfc,s9700rtwv43tr-01b.txt @@ -0,0 +1,15 @@ +TFC S9700RTWV43TR-01B 7" Three Five Corp 800x480 LCD panel with +resistive touch + +The panel is found on TI AM335x-evm. + +Required properties: +- compatible: should be "tfc,s9700rtwv43tr-01b" +- power-supply: See panel-common.txt + +Optional properties: +- enable-gpios: GPIO pin to enable or disable the panel, if there is one +- backlight: phandle of the backlight device attached to the panel + +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/display/panel/vl050_8048nt_c01.txt b/Documentation/devicetree/bindings/display/panel/vl050_8048nt_c01.txt new file mode 100644 index 000000000000..b42bf06bbd99 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/vl050_8048nt_c01.txt @@ -0,0 +1,12 @@ +VXT 800x480 color TFT LCD panel + +Required properties: +- compatible: should be "vxt,vl050-8048nt-c01" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding +- enable-gpios: as specified in the base binding + +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/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index aedb22b4d161..c97dfacad281 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -7,6 +7,7 @@ Required Properties: - "renesas,du-r8a7744" for R8A7744 (RZ/G1N) compatible DU - "renesas,du-r8a7745" for R8A7745 (RZ/G1E) compatible DU - "renesas,du-r8a77470" for R8A77470 (RZ/G1C) compatible DU + - "renesas,du-r8a774a1" for R8A774A1 (RZ/G2M) compatible DU - "renesas,du-r8a774c0" for R8A774C0 (RZ/G2E) compatible DU - "renesas,du-r8a7779" for R8A7779 (R-Car H1) compatible DU - "renesas,du-r8a7790" for R8A7790 (R-Car H2) compatible DU @@ -58,6 +59,7 @@ corresponding to each DU output. R8A7744 (RZ/G1N) DPAD 0 LVDS 0 - - R8A7745 (RZ/G1E) DPAD 0 DPAD 1 - - R8A77470 (RZ/G1C) DPAD 0 DPAD 1 LVDS 0 - + R8A774A1 (RZ/G2M) DPAD 0 HDMI 0 LVDS 0 - R8A774C0 (RZ/G2E) DPAD 0 LVDS 0 LVDS 1 - R8A7779 (R-Car H1) DPAD 0 DPAD 1 - - R8A7790 (R-Car H2) DPAD 0 LVDS 0 LVDS 1 - diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt index 39143424a474..3d32ce137e7f 100644 --- a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt @@ -12,6 +12,7 @@ following device-specific properties. Required properties: - compatible: should be one of the following: + "rockchip,rk3228-dw-hdmi" "rockchip,rk3288-dw-hdmi" "rockchip,rk3328-dw-hdmi" "rockchip,rk3399-dw-hdmi" @@ -38,6 +39,13 @@ Optional properties - phys: from general PHY binding: the phandle for the PHY device. - phy-names: Should be "hdmi" if phys references an external phy. +Optional pinctrl entry: +- If you have both a "unwedge" and "default" pinctrl entry, dw_hdmi + will switch to the unwedge pinctrl state for 10ms if it ever gets an + i2c timeout. It's intended that this unwedge pinctrl entry will + cause the SDA line to be driven low to work around a hardware + errata. + Example: hdmi: hdmi@ff980000 { diff --git a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt index 3eb1b48b47dd..60c54da4e526 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt +++ b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt @@ -40,6 +40,8 @@ Mandatory nodes specific to STM32 DSI: - panel or bridge node: A node containing the panel or bridge description as documented in [6]. - port: panel or bridge port node, connected to the DSI output port (port@1). +Optional properties: +- phy-dsi-supply: phandle of the regulator that provides the supply voltage. Note: You can find more documentation in the following references [1] Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -101,6 +103,7 @@ Example 2: DSI panel clock-names = "pclk", "ref"; resets = <&rcc STM32F4_APB2_RESET(DSI)>; reset-names = "apb"; + phy-dsi-supply = <®18>; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/sunxi/sun6i-dsi.txt b/Documentation/devicetree/bindings/display/sunxi/sun6i-dsi.txt deleted file mode 100644 index 6a6cf5de08b0..000000000000 --- a/Documentation/devicetree/bindings/display/sunxi/sun6i-dsi.txt +++ /dev/null @@ -1,93 +0,0 @@ -Allwinner A31 DSI Encoder -========================= - -The DSI pipeline consists of two separate blocks: the DSI controller -itself, and its associated D-PHY. - -DSI Encoder ------------ - -The DSI Encoder generates the DSI signal from the TCON's. - -Required properties: - - compatible: value must be one of: - * allwinner,sun6i-a31-mipi-dsi - - reg: base address and size of memory-mapped region - - interrupts: interrupt associated to this IP - - clocks: phandles to the clocks feeding the DSI encoder - * bus: the DSI interface clock - * mod: the DSI module clock - - clock-names: the clock names mentioned above - - phys: phandle to the D-PHY - - phy-names: must be "dphy" - - resets: phandle to the reset controller driving the encoder - - - ports: A ports node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The - first port should be the input endpoint, usually coming from the - associated TCON. - -Any MIPI-DSI device attached to this should be described according to -the bindings defined in ../mipi-dsi-bus.txt - -D-PHY ------ - -Required properties: - - compatible: value must be one of: - * allwinner,sun6i-a31-mipi-dphy - - reg: base address and size of memory-mapped region - - clocks: phandles to the clocks feeding the DSI encoder - * bus: the DSI interface clock - * mod: the DSI module clock - - clock-names: the clock names mentioned above - - resets: phandle to the reset controller driving the encoder - -Example: - -dsi0: dsi@1ca0000 { - compatible = "allwinner,sun6i-a31-mipi-dsi"; - reg = <0x01ca0000 0x1000>; - interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&ccu CLK_BUS_MIPI_DSI>, - <&ccu CLK_DSI_SCLK>; - clock-names = "bus", "mod"; - resets = <&ccu RST_BUS_MIPI_DSI>; - phys = <&dphy0>; - phy-names = "dphy"; - #address-cells = <1>; - #size-cells = <0>; - - panel@0 { - compatible = "bananapi,lhr050h41", "ilitek,ili9881c"; - reg = <0>; - power-gpios = <&pio 1 7 GPIO_ACTIVE_HIGH>; /* PB07 */ - reset-gpios = <&r_pio 0 5 GPIO_ACTIVE_LOW>; /* PL05 */ - backlight = <&pwm_bl>; - }; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - #address-cells = <1>; - #size-cells = <0>; - reg = <0>; - - dsi0_in_tcon0: endpoint { - remote-endpoint = <&tcon0_out_dsi0>; - }; - }; - }; -}; - -dphy0: d-phy@1ca1000 { - compatible = "allwinner,sun6i-a31-mipi-dphy"; - reg = <0x01ca1000 0x1000>; - clocks = <&ccu CLK_BUS_MIPI_DSI>, - <&ccu CLK_DSI_DPHY>; - clock-names = "bus", "mod"; - resets = <&ccu RST_BUS_MIPI_DSI>; - #phy-cells = <0>; -}; diff --git a/Documentation/devicetree/bindings/dma/8250_mtk_dma.txt b/Documentation/devicetree/bindings/dma/8250_mtk_dma.txt deleted file mode 100644 index 3fe0961bcf64..000000000000 --- a/Documentation/devicetree/bindings/dma/8250_mtk_dma.txt +++ /dev/null @@ -1,33 +0,0 @@ -* Mediatek UART APDMA Controller - -Required properties: -- compatible should contain: - * "mediatek,mt2712-uart-dma" for MT2712 compatible APDMA - * "mediatek,mt6577-uart-dma" for MT6577 and all of the above - -- reg: The base address of the APDMA register bank. - -- interrupts: A single interrupt specifier. - -- clocks : Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: The APDMA clock for register accesses - -Examples: - - apdma: dma-controller@11000380 { - compatible = "mediatek,mt2712-uart-dma"; - reg = <0 0x11000380 0 0x400>; - interrupts = <GIC_SPI 63 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 64 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 65 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 66 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 67 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 68 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 69 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 70 IRQ_TYPE_LEVEL_LOW>; - clocks = <&pericfg CLK_PERI_AP_DMA>; - clock-names = "apdma"; - #dma-cells = <1>; - }; - diff --git a/Documentation/devicetree/bindings/dma/arm-pl330.txt b/Documentation/devicetree/bindings/dma/arm-pl330.txt index db7e2260f9c5..2c7fd1941abb 100644 --- a/Documentation/devicetree/bindings/dma/arm-pl330.txt +++ b/Documentation/devicetree/bindings/dma/arm-pl330.txt @@ -16,6 +16,9 @@ Optional properties: - 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 + - resets: contains an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: must contain at least "dma", and optional is "dma-ocp". Example: diff --git a/Documentation/devicetree/bindings/dma/fsl-edma.txt b/Documentation/devicetree/bindings/dma/fsl-edma.txt index 97e213e07660..29dd3ccb1235 100644 --- a/Documentation/devicetree/bindings/dma/fsl-edma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-edma.txt @@ -9,15 +9,16 @@ group, DMAMUX0 or DMAMUX1, but not both. Required properties: - compatible : - "fsl,vf610-edma" for eDMA used similar to that on Vybrid vf610 SoC + - "fsl,imx7ulp-edma" for eDMA2 used similar to that on i.mx7ulp - reg : Specifies base physical address(s) and size of the eDMA registers. The 1st region is eDMA control register's address and size. The 2nd and the 3rd regions are programmable channel multiplexing control register's address and size. - interrupts : A list of interrupt-specifiers, one for each entry in - interrupt-names. -- interrupt-names : Should contain: - "edma-tx" - the transmission interrupt - "edma-err" - the error interrupt + interrupt-names on vf610 similar SoC. But for i.mx7ulp per channel + per transmission interrupt, total 16 channel interrupt and 1 + error interrupt(located in the last), no interrupt-names list on + i.mx7ulp for clean on dts. - #dma-cells : Must be <2>. The 1st cell specifies the DMAMUX(0 for DMAMUX0 and 1 for DMAMUX1). Specific request source can only be multiplexed by specific channels @@ -28,6 +29,7 @@ Required properties: - clock-names : A list of channel group clock names. Should contain: "dmamux0" - clock name of mux0 group "dmamux1" - clock name of mux1 group + Note: No dmamux0 on i.mx7ulp, but another 'dma' clk added on i.mx7ulp. - clocks : A list of phandle and clock-specifier pairs, one for each entry in clock-names. @@ -35,6 +37,10 @@ Optional properties: - big-endian: If present registers and hardware scatter/gather descriptors of the eDMA are implemented in big endian mode, otherwise in little mode. +- interrupt-names : Should contain the below on vf610 similar SoC but not used + on i.mx7ulp similar SoC: + "edma-tx" - the transmission interrupt + "edma-err" - the error interrupt Examples: @@ -52,8 +58,36 @@ edma0: dma-controller@40018000 { clock-names = "dmamux0", "dmamux1"; clocks = <&clks VF610_CLK_DMAMUX0>, <&clks VF610_CLK_DMAMUX1>; -}; +}; /* vf610 */ +edma1: dma-controller@40080000 { + #dma-cells = <2>; + compatible = "fsl,imx7ulp-edma"; + reg = <0x40080000 0x2000>, + <0x40210000 0x1000>; + dma-channels = <32>; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 6 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>, + /* last is eDMA2-ERR interrupt */ + <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "dma", "dmamux0"; + clocks = <&pcc2 IMX7ULP_CLK_DMA1>, + <&pcc2 IMX7ULP_CLK_DMA_MUX1>; +}; /* i.mx7ulp */ * DMA clients DMA client drivers that uses the DMA function must use the format described diff --git a/Documentation/devicetree/bindings/dma/fsl-qdma.txt b/Documentation/devicetree/bindings/dma/fsl-qdma.txt index 6a0ff9059e72..da371c4d406c 100644 --- a/Documentation/devicetree/bindings/dma/fsl-qdma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-qdma.txt @@ -7,6 +7,7 @@ Required properties: - compatible: Must be one of "fsl,ls1021a-qdma": for LS1021A Board + "fsl,ls1028a-qdma": for LS1028A Board "fsl,ls1043a-qdma": for ls1043A Board "fsl,ls1046a-qdma": for ls1046A Board - reg: Should contain the register's base address and length. diff --git a/Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt b/Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt new file mode 100644 index 000000000000..5d6f98c43e3d --- /dev/null +++ b/Documentation/devicetree/bindings/dma/mtk-uart-apdma.txt @@ -0,0 +1,54 @@ +* Mediatek UART APDMA Controller + +Required properties: +- compatible should contain: + * "mediatek,mt2712-uart-dma" for MT2712 compatible APDMA + * "mediatek,mt6577-uart-dma" for MT6577 and all of the above + +- reg: The base address of the APDMA register bank. + +- interrupts: A single interrupt specifier. + One interrupt per dma-requests, or 8 if no dma-requests property is present + +- dma-requests: The number of DMA channels + +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: The APDMA clock for register accesses + +- mediatek,dma-33bits: Present if the DMA requires support + +Examples: + + apdma: dma-controller@11000400 { + compatible = "mediatek,mt2712-uart-dma"; + reg = <0 0x11000400 0 0x80>, + <0 0x11000480 0 0x80>, + <0 0x11000500 0 0x80>, + <0 0x11000580 0 0x80>, + <0 0x11000600 0 0x80>, + <0 0x11000680 0 0x80>, + <0 0x11000700 0 0x80>, + <0 0x11000780 0 0x80>, + <0 0x11000800 0 0x80>, + <0 0x11000880 0 0x80>, + <0 0x11000900 0 0x80>, + <0 0x11000980 0 0x80>; + interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 105 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 106 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 107 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 108 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 109 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 110 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 111 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 112 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 113 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 114 IRQ_TYPE_LEVEL_LOW>; + dma-requests = <12>; + clocks = <&pericfg CLK_PERI_AP_DMA>; + clock-names = "apdma"; + mediatek,dma-33bits; + #dma-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/dma/sun6i-dma.txt b/Documentation/devicetree/bindings/dma/sun6i-dma.txt index 7fccc20d8331..cae31f4e77ba 100644 --- a/Documentation/devicetree/bindings/dma/sun6i-dma.txt +++ b/Documentation/devicetree/bindings/dma/sun6i-dma.txt @@ -28,12 +28,17 @@ Example: }; ------------------------------------------------------------------------------ -For A64 DMA controller: +For A64 and H6 DMA controller: Required properties: -- compatible: "allwinner,sun50i-a64-dma" +- compatible: Must be one of + "allwinner,sun50i-a64-dma" + "allwinner,sun50i-h6-dma" - dma-channels: Number of DMA channels supported by the controller. Refer to Documentation/devicetree/bindings/dma/dma.txt +- clocks: In addition to parent AHB clock, it should also contain mbus + clock (H6 only) +- clock-names: Should contain "bus" and "mbus" (H6 only) - all properties above, i.e. reg, interrupts, clocks, resets and #dma-cells Optional properties: diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt index 1b1a74129141..9b298edec5b2 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt +++ b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.txt @@ -15,7 +15,9 @@ Required properties: + "arm,mali-t860" + "arm,mali-t880" * which must be preceded by one of the following vendor specifics: + + "allwinner,sun50i-h6-mali" + "amlogic,meson-gxm-mali" + + "samsung,exynos5433-mali" + "rockchip,rk3288-mali" + "rockchip,rk3399-mali" @@ -31,21 +33,36 @@ Optional properties: - clocks : Phandle to clock for the Mali Midgard device. +- clock-names : Specify the names of the clocks specified in clocks + when multiple clocks are present. + * core: clock driving the GPU itself (When only one clock is present, + assume it's this clock.) + * bus: bus clock for the GPU + - mali-supply : Phandle to regulator for the Mali device. Refer to Documentation/devicetree/bindings/regulator/regulator.txt for details. - operating-points-v2 : Refer to Documentation/devicetree/bindings/opp/opp.txt for details. +- #cooling-cells: Refer to Documentation/devicetree/bindings/thermal/thermal.txt + for details. + - resets : Phandle of the GPU reset line. Vendor-specific bindings ------------------------ The Mali GPU is integrated very differently from one SoC to -another. In order to accomodate those differences, you have the option +another. In order to accommodate those differences, you have the option to specify one more vendor-specific compatible, among: +- "allwinner,sun50i-h6-mali" + Required properties: + - clocks : phandles to core and bus clocks + - clock-names : must contain "core" and "bus" + - resets: phandle to GPU reset line + - "amlogic,meson-gxm-mali" Required properties: - resets : Should contain phandles of : @@ -65,6 +82,7 @@ gpu@ffa30000 { mali-supply = <&vdd_gpu>; operating-points-v2 = <&gpu_opp_table>; power-domains = <&power RK3288_PD_GPU>; + #cooling-cells = <2>; }; gpu_opp_table: opp_table0 { diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt index ae63f09fda7d..b352a6851a06 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt +++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt @@ -17,6 +17,7 @@ Required properties: + amlogic,meson8b-mali + amlogic,meson-gxbb-mali + amlogic,meson-gxl-mali + + samsung,exynos4210-mali + rockchip,rk3036-mali + rockchip,rk3066-mali + rockchip,rk3188-mali diff --git a/Documentation/devicetree/bindings/hwlock/omap-hwspinlock.txt b/Documentation/devicetree/bindings/hwlock/omap-hwspinlock.txt index 2c9804f4f4ac..8d365f89694c 100644 --- a/Documentation/devicetree/bindings/hwlock/omap-hwspinlock.txt +++ b/Documentation/devicetree/bindings/hwlock/omap-hwspinlock.txt @@ -1,12 +1,16 @@ -OMAP4+ HwSpinlock Driver -======================== +TI HwSpinlock for OMAP and K3 based SoCs +========================================= Required properties: -- compatible: Should be "ti,omap4-hwspinlock" for - OMAP44xx, OMAP54xx, AM33xx, AM43xx, DRA7xx SoCs +- compatible: Should be one of the following, + "ti,omap4-hwspinlock" for + OMAP44xx, OMAP54xx, AM33xx, AM43xx, DRA7xx SoCs + "ti,am654-hwspinlock" for + K3 AM65x and J721E SoCs - reg: Contains the hwspinlock module register address space (base address and length) - ti,hwmods: Name of the hwmod associated with the hwspinlock device + (for OMAP architecture based SoCs only) - #hwlock-cells: Should be 1. The OMAP hwspinlock users will use a 0-indexed relative hwlock number as the argument specifier value for requesting a specific hwspinlock @@ -17,10 +21,21 @@ Please look at the generic hwlock binding for usage information for consumers, Example: -/* OMAP4 */ +1. OMAP4 SoCs hwspinlock: spinlock@4a0f6000 { compatible = "ti,omap4-hwspinlock"; reg = <0x4a0f6000 0x1000>; ti,hwmods = "spinlock"; #hwlock-cells = <1>; }; + +2. AM65x SoCs and J721E SoCs +&cbass_main { + cbass_main_navss: interconnect0 { + hwspinlock: spinlock@30e00000 { + compatible = "ti,am654-hwspinlock"; + reg = <0x00 0x30e00000 0x00 0x1000>; + #hwlock-cells = <1>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml b/Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml new file mode 100644 index 000000000000..f9d526b7da01 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/allwinner,sun6i-a31-p2wi.yaml @@ -0,0 +1,65 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/allwinner,sun6i-a31-p2wi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 P2WI (Push/Pull 2 Wires Interface) Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + +properties: + compatible: + const: allwinner,sun6i-a31-p2wi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + clock-frequency: + minimum: 1 + maximum: 6000000 + +required: + - compatible + - reg + - interrupts + - clocks + - resets + +# FIXME: We should set it, but it would report all the generic +# properties as additional properties. +# additionalProperties: false + +examples: + - | + i2c@1f03400 { + compatible = "allwinner,sun6i-a31-p2wi"; + reg = <0x01f03400 0x400>; + interrupts = <0 39 4>; + clocks = <&apb0_gates 3>; + clock-frequency = <100000>; + resets = <&apb0_rst 3>; + #address-cells = <1>; + #size-cells = <0>; + + axp221: pmic@68 { + compatible = "x-powers,axp221"; + reg = <0x68>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/i2c/i2c-mt7621.txt b/Documentation/devicetree/bindings/i2c/i2c-mt7621.txt new file mode 100644 index 000000000000..bc36f0eb94cd --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-mt7621.txt @@ -0,0 +1,25 @@ +MediaTek MT7621/MT7628 I2C master controller + +Required properties: + +- compatible: Should be one of the following: + - "mediatek,mt7621-i2c": for MT7621/MT7628/MT7688 platforms +- #address-cells: should be 1. +- #size-cells: should be 0. +- reg: Address and length of the register set for the device +- resets: phandle to the reset controller asserting this device in + reset + See ../reset/reset.txt for details. + +Optional properties : + +Example: + +i2c: i2c@900 { + compatible = "mediatek,mt7621-i2c"; + reg = <0x900 0x100>; + #address-cells = <1>; + #size-cells = <0>; + resets = <&rstctrl 16>; + reset-names = "i2c"; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt b/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt deleted file mode 100644 index 0ffe65a316ae..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt +++ /dev/null @@ -1,64 +0,0 @@ - -* Marvell MV64XXX I2C controller - -Required properties : - - - reg : Offset and length of the register set for the device - - compatible : Should be either: - - "allwinner,sun4i-a10-i2c" - - "allwinner,sun6i-a31-i2c" - - "marvell,mv64xxx-i2c" - - "marvell,mv78230-i2c" - - "marvell,mv78230-a0-i2c" - * Note: Only use "marvell,mv78230-a0-i2c" for a - very rare, initial version of the SoC which - had broken offload support. Linux - auto-detects this and sets it appropriately. - - interrupts : The interrupt number - -Optional properties : - - - clock-frequency : Desired I2C bus clock frequency in Hz. If not set the -default frequency is 100kHz - - - resets : phandle to the parent reset controller. Mandatory - whenever you're using the "allwinner,sun6i-a31-i2c" - compatible. - - - clocks: : pointers to the reference clocks for this device, the - first one is the one used for the clock on the i2c bus, - the second one is the clock used to acces the registers - of the controller - - - clock-names : names of used clocks, mandatory if the second clock is - used, the name must be "core", and "reg" (the latter is - only for Armada 7K/8K). - -Examples: - - i2c@11000 { - compatible = "marvell,mv64xxx-i2c"; - reg = <0x11000 0x20>; - interrupts = <29>; - clock-frequency = <100000>; - }; - -For the Armada XP: - - i2c@11000 { - compatible = "marvell,mv78230-i2c", "marvell,mv64xxx-i2c"; - reg = <0x11000 0x100>; - interrupts = <29>; - clock-frequency = <100000>; - }; - -For the Armada 7040: - - i2c@701000 { - compatible = "marvell,mv78230-i2c"; - reg = <0x701000 0x20>; - interrupts = <29>; - clock-frequency = <100000>; - clock-names = "core", "reg"; - clocks = <&core_clock>, <®_clock>; - }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-ocores.txt b/Documentation/devicetree/bindings/i2c/i2c-ocores.txt index 17bef9a34e50..6b25a80ae8d3 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-ocores.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-ocores.txt @@ -1,9 +1,13 @@ Device tree configuration for i2c-ocores Required properties: -- compatible : "opencores,i2c-ocores" or "aeroflexgaisler,i2cmst" +- compatible : "opencores,i2c-ocores" + "aeroflexgaisler,i2cmst" + "sifive,fu540-c000-i2c", "sifive,i2c0" + For Opencore based I2C IP block reimplemented in + FU540-C000 SoC. Please refer to sifive-blocks-ip-versioning.txt + for additional details. - reg : bus address start and address range size of device -- interrupts : interrupt number - clocks : handle to the controller clock; see the note below. Mutually exclusive with opencores,ip-clock-frequency - opencores,ip-clock-frequency: frequency of the controller clock in Hz; @@ -12,6 +16,7 @@ Required properties: - #size-cells : should be <0> Optional properties: +- interrupts : interrupt number. - clock-frequency : frequency of bus clock in Hz; see the note below. Defaults to 100 KHz when the property is not specified - reg-shift : device register offsets are shifted by this value diff --git a/Documentation/devicetree/bindings/i2c/i2c-omap.txt b/Documentation/devicetree/bindings/i2c/i2c-omap.txt index 4b90ba9f31b7..a44573d7c118 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-omap.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-omap.txt @@ -7,6 +7,7 @@ Required properties : "ti,omap3-i2c" for OMAP3 SoCs "ti,omap4-i2c" for OMAP4+ SoCs "ti,am654-i2c", "ti,omap4-i2c" for AM654 SoCs + "ti,j721e-i2c", "ti,omap4-i2c" for J721E SoCs - ti,hwmods : Must be "i2c<n>", n being the instance number (1-based) - #address-cells = <1>; - #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-stm32.txt b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt index f334738f7a35..ce3df2fff6c8 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-stm32.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt @@ -21,6 +21,8 @@ Optional properties: 100000 and 400000. For STM32F7, STM32H7 and STM32MP1 SoCs, Standard-mode, Fast-mode and Fast-mode Plus are supported, possible values are 100000, 400000 and 1000000. +- dmas: List of phandles to rx and tx DMA channels. Refer to stm32-dma.txt. +- dma-names: List of dma names. Valid names are: "rx" and "tx". - i2c-scl-rising-time-ns: I2C SCL Rising time for the board (default: 25) For STM32F7, STM32H7 and STM32MP1 only. - i2c-scl-falling-time-ns: I2C SCL Falling time for the board (default: 10) diff --git a/Documentation/devicetree/bindings/i2c/i2c-sun6i-p2wi.txt b/Documentation/devicetree/bindings/i2c/i2c-sun6i-p2wi.txt deleted file mode 100644 index 49df0053347a..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-sun6i-p2wi.txt +++ /dev/null @@ -1,41 +0,0 @@ - -* Allwinner P2WI (Push/Pull 2 Wire Interface) controller - -Required properties : - - - reg : Offset and length of the register set for the device. - - compatible : Should one of the following: - - "allwinner,sun6i-a31-p2wi" - - interrupts : The interrupt line connected to the P2WI peripheral. - - clocks : The gate clk connected to the P2WI peripheral. - - resets : The reset line connected to the P2WI peripheral. - -Optional properties : - - - clock-frequency : Desired P2WI bus clock frequency in Hz. If not set the -default frequency is 100kHz - -A P2WI may contain one child node encoding a P2WI slave device. - -Slave device properties: - Required properties: - - reg : the I2C slave address used during the initialization - process to switch from I2C to P2WI mode - -Example: - - p2wi@1f03400 { - compatible = "allwinner,sun6i-a31-p2wi"; - reg = <0x01f03400 0x400>; - interrupts = <0 39 4>; - clocks = <&apb0_gates 3>; - clock-frequency = <6000000>; - resets = <&apb0_rst 3>; - - axp221: pmic@68 { - compatible = "x-powers,axp221"; - reg = <0x68>; - - /* ... */ - }; - }; diff --git a/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml new file mode 100644 index 000000000000..001f2b7abad0 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml @@ -0,0 +1,124 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/marvell,mv64xxx-i2c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MV64XXX I2C Controller Device Tree Bindings + +maintainers: + - Gregory CLEMENT <gregory.clement@bootlin.com> + +properties: + compatible: + oneOf: + - const: allwinner,sun4i-a10-i2c + - items: + - const: allwinner,sun7i-a20-i2c + - const: allwinner,sun4i-a10-i2c + - const: allwinner,sun6i-a31-i2c + - items: + - const: allwinner,sun8i-a23-i2c + - const: allwinner,sun6i-a31-i2c + - items: + - const: allwinner,sun8i-a83t-i2c + - const: allwinner,sun6i-a31-i2c + - items: + - const: allwinner,sun50i-a64-i2c + - const: allwinner,sun6i-a31-i2c + + - const: marvell,mv64xxx-i2c + - const: marvell,mv78230-i2c + - const: marvell,mv78230-a0-i2c + + description: + Only use "marvell,mv78230-a0-i2c" for a very rare, initial + version of the SoC which had broken offload support. Linux + auto-detects this and sets it appropriately. + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 2 + items: + - description: Reference clock for the I2C bus + - description: Bus clock (Only for Armada 7K/8K) + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: core + - const: reg + description: + Mandatory if two clocks are used (only for Armada 7k and 8k). + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun4i-a10-i2c + - allwinner,sun6i-a31-i2c + + then: + required: + - clocks + + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-i2c + + then: + required: + - resets + +# FIXME: We should set it, but it would report all the generic +# properties as additional properties. +# additionalProperties: false + +examples: + - | + i2c@11000 { + compatible = "marvell,mv64xxx-i2c"; + reg = <0x11000 0x20>; + interrupts = <29>; + clock-frequency = <100000>; + }; + + - | + i2c@11000 { + compatible = "marvell,mv78230-i2c"; + reg = <0x11000 0x100>; + interrupts = <29>; + clock-frequency = <100000>; + }; + + - | + i2c@701000 { + compatible = "marvell,mv78230-i2c"; + reg = <0x701000 0x20>; + interrupts = <29>; + clock-frequency = <100000>; + clock-names = "core", "reg"; + clocks = <&core_clock>, <®_clock>; + }; + +... diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml index cf494a08b837..9692b7f719f5 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml @@ -114,42 +114,47 @@ patternProperties: examples: - | - adc@0 { - compatible = "adi,ad7124-4"; - reg = <0>; - spi-max-frequency = <5000000>; - interrupts = <25 2>; - interrupt-parent = <&gpio>; - refin1-supply = <&adc_vref>; - clocks = <&ad7124_mclk>; - clock-names = "mclk"; - + spi { #address-cells = <1>; #size-cells = <0>; - channel@0 { + adc@0 { + compatible = "adi,ad7124-4"; reg = <0>; - diff-channels = <0 1>; - adi,reference-select = <0>; - adi,buffered-positive; - }; - - channel@1 { - reg = <1>; - bipolar; - diff-channels = <2 3>; - adi,reference-select = <0>; - adi,buffered-positive; - adi,buffered-negative; - }; - - channel@2 { - reg = <2>; - diff-channels = <4 5>; - }; - - channel@3 { - reg = <3>; - diff-channels = <6 7>; + spi-max-frequency = <5000000>; + interrupts = <25 2>; + interrupt-parent = <&gpio>; + refin1-supply = <&adc_vref>; + clocks = <&ad7124_mclk>; + clock-names = "mclk"; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + diff-channels = <0 1>; + adi,reference-select = <0>; + adi,buffered-positive; + }; + + channel@1 { + reg = <1>; + bipolar; + diff-channels = <2 3>; + adi,reference-select = <0>; + adi,buffered-positive; + adi,buffered-negative; + }; + + channel@2 { + reg = <2>; + diff-channels = <4 5>; + }; + + channel@3 { + reg = <3>; + diff-channels = <6 7>; + }; }; }; diff --git a/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml index 8a4100ceeaf2..d76ece97c76c 100644 --- a/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml +++ b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml @@ -61,6 +61,6 @@ examples: compatible = "avia,hx711"; sck-gpios = <&gpio3 10 GPIO_ACTIVE_HIGH>; dout-gpios = <&gpio0 7 GPIO_ACTIVE_HIGH>; - avdd-suppy = <&avdd>; + avdd-supply = <&avdd>; clock-frequency = <100000>; }; diff --git a/Documentation/devicetree/bindings/input/elan_i2c.txt b/Documentation/devicetree/bindings/input/elan_i2c.txt index 797607460735..9963247706f2 100644 --- a/Documentation/devicetree/bindings/input/elan_i2c.txt +++ b/Documentation/devicetree/bindings/input/elan_i2c.txt @@ -13,9 +13,20 @@ Optional properties: pinctrl binding [1]). - vcc-supply: a phandle for the regulator supplying 3.3V power. - elan,trackpoint: touchpad can support a trackpoint (boolean) +- elan,clickpad: touchpad is a clickpad (the entire surface is a button) +- elan,middle-button: touchpad has a physical middle button +- elan,x_traces: number of antennas on the x axis +- elan,y_traces: number of antennas on the y axis +- some generic touchscreen properties [2]: + * touchscreen-size-x + * touchscreen-size-y + * touchscreen-x-mm + * touchscreen-y-mm + [0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt [1]: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +[2]: Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt Example: &i2c1 { diff --git a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt index 496125c6bfb7..507b737612ea 100644 --- a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt +++ b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt @@ -5,6 +5,7 @@ Required properties: - compatible: should be one of the following string: "allwinner,sun4i-a10-lradc-keys" "allwinner,sun8i-a83t-r-lradc" + "allwinner,sun50i-a64-lradc", "allwinner,sun8i-a83t-r-lradc" - reg: mmio address range of the chip - interrupts: interrupt to which the chip is connected - vref-supply: powersupply for the lradc reference voltage diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt index 0ef372656a3e..35c3f56b7f7b 100644 --- a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -1,4 +1,4 @@ -OMAP2+ Mailbox Driver +OMAP2+ and K3 Mailbox ===================== The OMAP mailbox hardware facilitates communication between different processors @@ -7,7 +7,7 @@ various processor subsystems and is connected on an interconnect bus. The communication is achieved through a set of registers for message storage and interrupt configuration registers. -Each mailbox IP block has a certain number of h/w fifo queues and output +Each mailbox IP block/cluster has a certain number of h/w fifo queues and output interrupt lines. An output interrupt line is routed to an interrupt controller within a processor subsystem, and there can be more than one line going to a specific processor's interrupt controller. The interrupt line connections are @@ -23,12 +23,16 @@ All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP instance. DRA7xx has multiple instances with different number of h/w fifo queues and interrupt lines between different instances. The interrupt lines can also be routed to different processor sub-systems on DRA7xx as they are routed through -the Crossbar, a kind of interrupt router/multiplexer. +the Crossbar, a kind of interrupt router/multiplexer. The K3 AM65x and J721E +SoCs has each of these instances form a cluster and combine multiple clusters +into a single IP block present within the Main NavSS. The interrupt lines from +all these clusters are multiplexed and routed to different processor subsystems +over a limited number of common interrupt output lines of an Interrupt Router. Mailbox Device Node: ==================== -A Mailbox device node is used to represent a Mailbox IP instance within a SoC. -The sub-mailboxes are represented as child nodes of this parent node. +A Mailbox device node is used to represent a Mailbox IP instance/cluster within +a SoC. The sub-mailboxes are represented as child nodes of this parent node. Required properties: -------------------- @@ -37,12 +41,12 @@ Required properties: "ti,omap3-mailbox" for OMAP3430, OMAP3630 SoCs "ti,omap4-mailbox" for OMAP44xx, OMAP54xx, AM33xx, AM43xx and DRA7xx SoCs + "ti,am654-mailbox" for K3 AM65x and J721E SoCs - reg: Contains the mailbox register address range (base address and length) - interrupts: Contains the interrupt information for the mailbox device. The format is dependent on which interrupt - controller the OMAP device uses -- ti,hwmods: Name of the hwmod associated with the mailbox + controller the Mailbox device uses - #mbox-cells: Common mailbox binding property to identify the number of cells required for the mailbox specifier. Should be 1 @@ -50,6 +54,23 @@ Required properties: device can interrupt - ti,mbox-num-fifos: Number of h/w fifo queues within the mailbox IP block +SoC-specific Required properties: +--------------------------------- +The following are mandatory properties for the OMAP architecture based SoCs +only: +- ti,hwmods: Name of the hwmod associated with the mailbox. This + should be defined in the mailbox node only if the node + is not defined as a child node of a corresponding sysc + interconnect node. + +The following are mandatory properties for the K3 AM65x and J721E SoCs only: +- interrupt-parent: Should contain a phandle to the TI-SCI interrupt + controller node that is used to dynamically program + the interrupt routes between the IP and the main GIC + controllers. See the following binding for additional + details, + Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt + Child Nodes: ============ A child node is used for representing the actual sub-mailbox device that is @@ -98,7 +119,7 @@ to be used by the client user. Example: -------- -/* OMAP4 */ +1. /* OMAP4 */ mailbox: mailbox@4a0f4000 { compatible = "ti,omap4-mailbox"; reg = <0x4a0f4000 0x200>; @@ -123,7 +144,7 @@ dsp { ... }; -/* AM33xx */ +2. /* AM33xx */ mailbox: mailbox@480c8000 { compatible = "ti,omap4-mailbox"; reg = <0x480C8000 0x200>; @@ -137,3 +158,23 @@ mailbox: mailbox@480c8000 { ti,mbox-rx = <0 0 3>; }; }; + +3. /* AM65x */ +&cbass_main { + cbass_main_navss: interconnect0 { + mailbox0_cluster0: mailbox@31f80000 { + compatible = "ti,am654-mailbox"; + reg = <0x00 0x31f80000 0x00 0x200>; + #mbox-cells = <1>; + ti,mbox-num-users = <4>; + ti,mbox-num-fifos = <16>; + interrupt-parent = <&intr_main_navss>; + interrupts = <164 0>; + + mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 { + ti,mbox-tx = <1 0 0>; + ti,mbox-rx = <0 0 0>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/cros-ec.txt b/Documentation/devicetree/bindings/mfd/cros-ec.txt index 6245c9b1a68b..4860eabd0f72 100644 --- a/Documentation/devicetree/bindings/mfd/cros-ec.txt +++ b/Documentation/devicetree/bindings/mfd/cros-ec.txt @@ -3,7 +3,7 @@ ChromeOS Embedded Controller Google's ChromeOS EC is a Cortex-M device which talks to the AP and implements various function such as keyboard and battery charging. -The EC can be connect through various means (I2C, SPI, LPC) and the +The EC can be connect through various means (I2C, SPI, LPC, RPMSG) and the compatible string used depends on the interface. Each connection method has its own driver which connects to the top level interface-agnostic EC driver. Other Linux driver (such as cros-ec-keyb for the matrix keyboard) connect to @@ -17,6 +17,9 @@ Required properties (SPI): - compatible: "google,cros-ec-spi" - reg: SPI chip select +Required properties (RPMSG): +- compatible: "google,cros-ec-rpmsg" + Optional properties (SPI): - google,cros-ec-spi-pre-delay: Some implementations of the EC need a little time to wake up from sleep before they can receive SPI transfers at a high diff --git a/Documentation/devicetree/bindings/mfd/lp87565.txt b/Documentation/devicetree/bindings/mfd/lp87565.txt index a48df7c08ab0..41671e0dc26b 100644 --- a/Documentation/devicetree/bindings/mfd/lp87565.txt +++ b/Documentation/devicetree/bindings/mfd/lp87565.txt @@ -41,3 +41,39 @@ lp87565_pmic: pmic@60 { }; }; }; + +TI LP87561 PMIC: + +This is a single output 4-phase regulator configuration + +Required properties: + - compatible: "ti,lp87561-q1" + - reg: I2C slave address. + - 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. + - xxx-in-supply: Phandle to parent supply node of each regulator + populated under regulators node. xxx should match + the supply_name populated in driver. +Example: + +lp87561_pmic: pmic@62 { + compatible = "ti,lp87561-q1"; + reg = <0x62>; + gpio-controller; + #gpio-cells = <2>; + + buck3210-in-supply = <&vsys_3v3>; + + regulators: regulators { + buck3210_reg: buck3210 { + /* VDD_CORE */ + regulator-name = "buck3210"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <800000>; + regulator-always-on; + regulator-boot-on; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/madera.txt b/Documentation/devicetree/bindings/mfd/madera.txt index db3266088386..cad0f2800502 100644 --- a/Documentation/devicetree/bindings/mfd/madera.txt +++ b/Documentation/devicetree/bindings/mfd/madera.txt @@ -11,10 +11,14 @@ bindings/sound/madera.txt Required properties: - compatible : One of the following chip-specific strings: + "cirrus,cs47l15" "cirrus,cs47l35" "cirrus,cs47l85" "cirrus,cs47l90" "cirrus,cs47l91" + "cirrus,cs42l92" + "cirrus,cs47l92" + "cirrus,cs47l93" "cirrus,wm1840" - reg : I2C slave address when connected using I2C, chip select number when @@ -22,7 +26,7 @@ Required properties: - DCVDD-supply : Power supply for the device as defined in bindings/regulator/regulator.txt - Mandatory on CS47L35, CS47L90, CS47L91 + Mandatory on CS47L15, CS47L35, CS47L90, CS47L91, CS42L92, CS47L92, CS47L93 Optional on CS47L85, WM1840 - AVDD-supply, DBVDD1-supply, DBVDD2-supply, CPVDD1-supply, CPVDD2-supply : @@ -35,7 +39,7 @@ Required properties: (CS47L85, WM1840) - SPKVDD-supply : Power supply for the device - (CS47L35) + (CS47L15, CS47L35) - interrupt-controller : Indicates that this device is an interrupt controller diff --git a/Documentation/devicetree/bindings/mfd/rk808.txt b/Documentation/devicetree/bindings/mfd/rk808.txt index 1683ec3245bc..04df07f6f793 100644 --- a/Documentation/devicetree/bindings/mfd/rk808.txt +++ b/Documentation/devicetree/bindings/mfd/rk808.txt @@ -3,11 +3,15 @@ RK8XX Power Management Integrated Circuit The rk8xx family current members: rk805 rk808 +rk809 +rk817 rk818 Required properties: - compatible: "rockchip,rk805" - compatible: "rockchip,rk808" +- compatible: "rockchip,rk809" +- compatible: "rockchip,rk817" - compatible: "rockchip,rk818" - reg: I2C slave address - interrupts: the interrupt outputs of the controller. @@ -45,6 +49,23 @@ Optional RK808 properties: the gpio controller. If DVS GPIOs aren't present, voltage changes will happen very quickly with no slow ramp time. +Optional shared RK809 and RK817 properties: +- vcc1-supply: The input supply for DCDC_REG1 +- vcc2-supply: The input supply for DCDC_REG2 +- vcc3-supply: The input supply for DCDC_REG3 +- vcc4-supply: The input supply for DCDC_REG4 +- vcc5-supply: The input supply for LDO_REG1, LDO_REG2, LDO_REG3 +- vcc6-supply: The input supply for LDO_REG4, LDO_REG5, LDO_REG6 +- vcc7-supply: The input supply for LDO_REG7, LDO_REG8, LDO_REG9 + +Optional RK809 properties: +- vcc8-supply: The input supply for SWITCH_REG1 +- vcc9-supply: The input supply for DCDC_REG5, SWITCH_REG2 + +Optional RK817 properties: +- vcc8-supply: The input supply for BOOST +- vcc9-supply: The input supply for OTG_SWITCH + Optional RK818 properties: - vcc1-supply: The input supply for DCDC_REG1 - vcc2-supply: The input supply for DCDC_REG2 @@ -86,6 +107,21 @@ number as described in RK808 datasheet. - SWITCH_REGn - valid values for n are 1 to 2 +Following regulators of the RK809 and RK817 PMIC blocks are supported. Note that +the 'n' in regulator name, as in DCDC_REGn or LDOn, represents the DCDC or LDO +number as described in RK809 and RK817 datasheets. + + - DCDC_REGn + - valid values for n are 1 to 5 for RK809. + - valid values for n are 1 to 4 for RK817. + - LDO_REGn + - valid values for n are 1 to 9 for RK809. + - valid values for n are 1 to 9 for RK817. + - SWITCH_REGn + - valid values for n are 1 to 2 for RK809. + - BOOST for RK817 + - OTG_SWITCH for RK817 + Following regulators of the RK818 PMIC block are supported. Note that the 'n' in regulator name, as in DCDC_REGn or LDOn, represents the DCDC or LDO number as described in RK818 datasheet. @@ -98,6 +134,14 @@ number as described in RK818 datasheet. - HDMI_SWITCH - OTG_SWITCH +It is necessary to configure three pins for both the RK809 and RK817, the three +pins are "gpio_ts" "gpio_gt" "gpio_slp". + The gpio_gt and gpio_ts pins support the gpio function. + The gpio_slp pin is for controlling the pmic states, as below: + - reset + - power down + - sleep + Standard regulator bindings are used inside regulator subnodes. Check Documentation/devicetree/bindings/regulator/regulator.txt for more details diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt b/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt new file mode 100644 index 000000000000..c3c02ce73cde --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt @@ -0,0 +1,102 @@ +* ROHM BD70528 Power Management Integrated Circuit bindings + +BD70528MWV is an ultra-low quiescent current general purpose, single-chip, +power management IC for battery-powered portable devices. The IC +integrates 3 ultra-low current consumption buck converters, 3 LDOs and 2 +LED Drivers. Also included are 4 GPIOs, a real-time clock (RTC), a 32kHz +clock gate, high-accuracy VREF for use with an external ADC, flexible +dual-input power path, 10 bit SAR ADC for battery temperature monitor and +1S battery charger with scalable charge currents. + +Required properties: + - compatible : Should be "rohm,bd70528" + - reg : I2C slave address. + - interrupts : The interrupt line the device is connected to. + - interrupt-controller : To indicate BD70528 acts as an interrupt controller. + - #interrupt-cells : Should be 2. Usage is compliant to the 2 cells + variant of ../interrupt-controller/interrupts.txt + - gpio-controller : To indicate BD70528 acts as a GPIO controller. + - #gpio-cells : Should be 2. The first cell is the pin number and + the second cell is used to specify flags. See + ../gpio/gpio.txt for more information. + - #clock-cells : Should be 0. + - regulators: : List of child nodes that specify the regulators. + Please see ../regulator/rohm,bd70528-regulator.txt + +Optional properties: + - clock-output-names : Should contain name for output clock. + +Example: +/* External oscillator */ +osc: oscillator { + compatible = "fixed-clock"; + #clock-cells = <1>; + clock-frequency = <32768>; + clock-output-names = "osc"; +}; + +pmic: pmic@4b { + compatible = "rohm,bd70528"; + reg = <0x4b>; + interrupt-parent = <&gpio1>; + interrupts = <29 GPIO_ACTIVE_LOW>; + clocks = <&osc 0>; + #clock-cells = <0>; + clock-output-names = "bd70528-32k-out"; + #gpio-cells = <2>; + gpio-controller; + interrupt-controller; + #interrupt-cells = <2>; + + regulators { + buck1: BUCK1 { + regulator-name = "buck1"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3400000>; + regulator-boot-on; + regulator-ramp-delay = <125>; + }; + buck2: BUCK2 { + regulator-name = "buck2"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-ramp-delay = <125>; + }; + buck3: BUCK3 { + regulator-name = "buck3"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + regulator-ramp-delay = <250>; + }; + ldo1: LDO1 { + regulator-name = "ldo1"; + regulator-min-microvolt = <1650000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + }; + ldo2: LDO2 { + regulator-name = "ldo2"; + regulator-min-microvolt = <1650000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + }; + + ldo3: LDO3 { + regulator-name = "ldo3"; + regulator-min-microvolt = <1650000>; + regulator-max-microvolt = <3300000>; + }; + led_ldo1: LED_LDO1 { + regulator-name = "led_ldo1"; + regulator-min-microvolt = <200000>; + regulator-max-microvolt = <300000>; + }; + led_ldo2: LED_LDO2 { + regulator-name = "led_ldo2"; + regulator-min-microvolt = <200000>; + regulator-max-microvolt = <300000>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt b/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt index d5f68ac78d15..f22d74c7a8db 100644 --- a/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt +++ b/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt @@ -8,6 +8,8 @@ and 6 LDOs. Datasheet for BD71837 is available at: https://www.rohm.com/datasheet/BD71837MWV/bd71837mwv-e +Datasheet for BD71847 is available at: +https://www.rohm.com/datasheet/BD71847AMWV/bd71847amwv-e Required properties: - compatible : Should be "rohm,bd71837" for bd71837 @@ -38,6 +40,14 @@ target state is set to READY by default. If SNVS state is used the boot crucial regulators must have the regulator-always-on and regulator-boot-on properties set in regulator node. +- rohm,short-press-ms : Short press duration in milliseconds +- rohm,long-press-ms : Long press duration in milliseconds + +Configure the "short press" and "long press" timers for the power button. +Values are rounded to what hardware supports (500ms multiple for short and +1000ms multiple for long). If these properties are not present the existing +configuration (from bootloader or OTP) is not touched. + Example: /* external oscillator node */ diff --git a/Documentation/devicetree/bindings/misc/fsl,dpaa2-console.txt b/Documentation/devicetree/bindings/misc/fsl,dpaa2-console.txt new file mode 100644 index 000000000000..1442ba5d2d98 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/fsl,dpaa2-console.txt @@ -0,0 +1,11 @@ +DPAA2 console support + +Required properties: + + - compatible + Value type: <string> + Definition: Must be "fsl,dpaa2-console". + - reg + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the region where the MCFBA + (MC firmware base address) register can be found. diff --git a/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt new file mode 100644 index 000000000000..8c4d649cdd8f --- /dev/null +++ b/Documentation/devicetree/bindings/misc/olpc,xo1.75-ec.txt @@ -0,0 +1,23 @@ +OLPC XO-1.75 Embedded Controller + +Required properties: +- compatible: Should be "olpc,xo1.75-ec". +- cmd-gpios: gpio specifier of the CMD pin + +The embedded controller requires the SPI controller driver to signal readiness +to receive a transfer (that is, when TX FIFO contains the response data) by +strobing the ACK pin with the ready signal. See the "ready-gpios" property of the +SSP binding as documented in: +<Documentation/devicetree/bindings/spi/spi-pxa2xx.txt>. + +Example: + &ssp3 { + spi-slave; + ready-gpios = <&gpio 125 GPIO_ACTIVE_HIGH>; + + slave { + compatible = "olpc,xo1.75-ec"; + spi-cpha; + cmd-gpios = <&gpio 155 GPIO_ACTIVE_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml index e5a411518be1..b5b3cf5b1ac2 100644 --- a/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml +++ b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml @@ -55,6 +55,7 @@ patternProperties: "^pinctrl-[0-9]+$": true "^nand@[a-f0-9]+$": + type: object properties: reg: minimum: 0 diff --git a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt index 0b7c3738b66c..82156dc8f304 100644 --- a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt +++ b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt @@ -28,6 +28,7 @@ Required properties: brcm,brcmnand-v7.0 brcm,brcmnand-v7.1 brcm,brcmnand-v7.2 + brcm,brcmnand-v7.3 brcm,brcmnand - reg : the register start and length for NAND register region. (optional) Flash DMA register range (if present) @@ -101,10 +102,10 @@ Required properties: number (e.g., 0, 1, 2, etc.) - #address-cells : see partition.txt - #size-cells : see partition.txt -- nand-ecc-strength : see nand-controller.yaml -- nand-ecc-step-size : must be 512 or 1024. See nand-controller.yaml Optional properties: +- nand-ecc-strength : see nand-controller.yaml +- nand-ecc-step-size : must be 512 or 1024. See nand-controller.yaml - nand-on-flash-bbt : boolean, to enable the on-flash BBT for this chip-select. See nand-controller.yaml - brcm,nand-oob-sector-size : integer, to denote the spare area sector size diff --git a/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt b/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt index 4345c3a6f530..945be7d5b236 100644 --- a/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt +++ b/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt @@ -35,6 +35,9 @@ custom properties: (qspi_n_ss_out). - cdns,tslch-ns : Delay in nanoseconds between setting qspi_n_ss_out low and first bit transfer. +- resets : Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names : Must include either "qspi" and/or "qspi-ocp". Example: @@ -50,6 +53,8 @@ Example: cdns,fifo-depth = <128>; cdns,fifo-width = <4>; cdns,trigger-address = <0x00000000>; + resets = <&rst QSPI_RESET>, <&rst QSPI_OCP_RESET>; + reset-names = "qspi", "qspi-ocp"; flash0: n25q00@0 { ... diff --git a/Documentation/devicetree/bindings/mtd/cypress,hyperflash.txt b/Documentation/devicetree/bindings/mtd/cypress,hyperflash.txt new file mode 100644 index 000000000000..ad42f4db32f1 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/cypress,hyperflash.txt @@ -0,0 +1,13 @@ +Bindings for HyperFlash NOR flash chips compliant with Cypress HyperBus +specification and supports Cypress CFI specification 1.5 command set. + +Required properties: +- compatible : "cypress,hyperflash", "cfi-flash" for HyperFlash NOR chips +- reg : Address of flash's memory map + +Example: + + flash@0 { + compatible = "cypress,hyperflash", "cfi-flash"; + reg = <0x0 0x4000000>; + }; diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index 199ba5ac2a06..d261b7096c69 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -40,6 +40,7 @@ properties: patternProperties: "^nand@[a-f0-9]$": + type: object properties: reg: description: diff --git a/Documentation/devicetree/bindings/mtd/stm32-quadspi.txt b/Documentation/devicetree/bindings/mtd/stm32-quadspi.txt deleted file mode 100644 index ddd18c135148..000000000000 --- a/Documentation/devicetree/bindings/mtd/stm32-quadspi.txt +++ /dev/null @@ -1,43 +0,0 @@ -* STMicroelectronics Quad Serial Peripheral Interface(QuadSPI) - -Required properties: -- compatible: should be "st,stm32f469-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 "qspi" "qspi_mm" -- interrupts: should contain the interrupt for the device -- clocks: the phandle of the clock needed by the QSPI controller -- A pinctrl must be defined to set pins in mode of operation for QSPI transfer - -Optional properties: -- resets: must contain the phandle to the reset controller. - -A spi flash must be a child of the nor_flash node and could have some -properties. Also see jedec,spi-nor.txt. - -Required properties: -- reg: chip-Select number (QSPI controller may connect 2 nor flashes) -- spi-max-frequency: max frequency of spi bus - -Optional property: -- spi-rx-bus-width: see ../spi/spi-bus.txt for the description - -Example: - -qspi: spi@a0001000 { - compatible = "st,stm32f469-qspi"; - reg = <0xa0001000 0x1000>, <0x90000000 0x10000000>; - reg-names = "qspi", "qspi_mm"; - interrupts = <91>; - resets = <&rcc STM32F4_AHB3_RESET(QSPI)>; - clocks = <&rcc 0 STM32F4_AHB3_CLOCK(QSPI)>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_qspi0>; - - flash@0 { - reg = <0>; - spi-rx-bus-width = <4>; - spi-max-frequency = <108000000>; - ... - }; -}; diff --git a/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.txt b/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.txt new file mode 100644 index 000000000000..faa81c2e5da6 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/ti,am654-hbmc.txt @@ -0,0 +1,51 @@ +Bindings for HyperBus Memory Controller (HBMC) on TI's K3 family of SoCs + +Required properties: +- compatible : "ti,am654-hbmc" for AM654 SoC +- reg : Two entries: + First entry pointed to the register space of HBMC controller + Second entry pointing to the memory map region dedicated for + MMIO access to attached flash devices +- ranges : Address translation from offset within CS to allocated MMIO + space in SoC + +Optional properties: +- mux-controls : phandle to the multiplexer that controls selection of + HBMC vs OSPI inside Flash SubSystem (FSS). Default is OSPI, + if property is absent. + See Documentation/devicetree/bindings/mux/reg-mux.txt + for mmio-mux binding details + +Example: + + system-controller@47000000 { + compatible = "syscon", "simple-mfd"; + reg = <0x0 0x47000000 0x0 0x100>; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + hbmc_mux: multiplexer { + compatible = "mmio-mux"; + #mux-control-cells = <1>; + mux-reg-masks = <0x4 0x2>; /* 0: reg 0x4, bit 1 */ + }; + }; + + hbmc: hyperbus@47034000 { + compatible = "ti,am654-hbmc"; + reg = <0x0 0x47034000 0x0 0x100>, + <0x5 0x00000000 0x1 0x0000000>; + power-domains = <&k3_pds 55>; + #address-cells = <2>; + #size-cells = <1>; + ranges = <0x0 0x0 0x5 0x00000000 0x4000000>, /* CS0 - 64MB */ + <0x1 0x0 0x5 0x04000000 0x4000000>; /* CS1 - 64MB */ + mux-controls = <&hbmc_mux 0>; + + /* Slave flash node */ + flash@0,0 { + compatible = "cypress,hyperflash", "cfi-flash"; + reg = <0x0 0x0 0x4000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 9936b9ee67c3..b463e1268ac4 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -6,6 +6,7 @@ Required properties: "renesas,can-r8a7744" if CAN controller is a part of R8A7744 SoC. "renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC. "renesas,can-r8a774a1" if CAN controller is a part of R8A774A1 SoC. + "renesas,can-r8a774c0" if CAN controller is a part of R8A774C0 SoC. "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. "renesas,can-r8a7779" if CAN controller is a part of R8A7779 SoC. "renesas,can-r8a7790" if CAN controller is a part of R8A7790 SoC. @@ -27,13 +28,8 @@ Required properties: - 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 2 CAN clock inputs for RZ/G2 - devices. - phandles and clock specifiers for 3 CAN clock inputs for every other - SoC. -- clock-names: 2 clock input name strings for RZ/G2: "clkp1", "can_clk". - 3 clock input name strings for every other SoC: "clkp1", "clkp2", - "can_clk". +- clocks: phandles and clock specifiers for 3 CAN clock inputs. +- clock-names: 3 clock input name strings: "clkp1", "clkp2", and "can_clk". - pinctrl-0: pin control group to be used for this controller. - pinctrl-names: must be "default". @@ -49,8 +45,7 @@ using the below properties: Optional properties: - renesas,can-clock-select: R-Car CAN Clock Source Select. Valid values are: <0x0> (default) : Peripheral clock (clkp1) - <0x1> : Peripheral clock (clkp2) (not supported by - RZ/G2 devices) + <0x1> : Peripheral clock (clkp2) <0x3> : External input clock Example diff --git a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt index ac71daa46195..32f051f6d338 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_canfd.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_canfd.txt @@ -3,11 +3,14 @@ Renesas R-Car CAN FD controller Device Tree Bindings Required properties: - compatible: Must contain one or more of the following: - - "renesas,rcar-gen3-canfd" for R-Car Gen3 compatible controller. + - "renesas,rcar-gen3-canfd" for R-Car Gen3 and RZ/G2 compatible controllers. + - "renesas,r8a774c0-canfd" for R8A774C0 (RZ/G2E) compatible controller. - "renesas,r8a7795-canfd" for R8A7795 (R-Car H3) compatible controller. - "renesas,r8a7796-canfd" for R8A7796 (R-Car M3-W) compatible controller. + - "renesas,r8a77965-canfd" for R8A77965 (R-Car M3-N) compatible controller. - "renesas,r8a77970-canfd" for R8A77970 (R-Car V3M) compatible controller. - "renesas,r8a77980-canfd" for R8A77980 (R-Car V3H) compatible controller. + - "renesas,r8a77990-canfd" for R8A77990 (R-Car E3) compatible controller. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first, followed by the @@ -26,12 +29,13 @@ The name of the child nodes are "channel0" and "channel1" respectively. Each child node supports the "status" property only, which is used to enable/disable the respective channel. -Required properties for "renesas,r8a7795-canfd" and "renesas,r8a7796-canfd" +Required properties for "renesas,r8a774c0-canfd", "renesas,r8a7795-canfd", +"renesas,r8a7796-canfd", "renesas,r8a77965-canfd", and "renesas,r8a77990-canfd" compatible: -In R8A7795 and R8A7796 SoCs, canfd clock 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: +In R8A774C0, R8A7795, R8A7796, R8A77965, and R8A77990 SoCs, canfd clock 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 canfd clock. - assigned-clock-rates: maximum frequency of this clock. diff --git a/Documentation/devicetree/bindings/pci/mobiveil-pcie.txt b/Documentation/devicetree/bindings/pci/mobiveil-pcie.txt index a618d4787dd7..64156993e052 100644 --- a/Documentation/devicetree/bindings/pci/mobiveil-pcie.txt +++ b/Documentation/devicetree/bindings/pci/mobiveil-pcie.txt @@ -10,8 +10,10 @@ Required properties: interrupt source. The value must be 1. - compatible: Should contain "mbvl,gpex40-pcie" - reg: Should contain PCIe registers location and length + Mandatory: "config_axi_slave": PCIe controller registers "csr_axi_slave" : Bridge config registers + Optional: "gpio_slave" : GPIO registers to control slot power "apb_csr" : MSI registers diff --git a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt index 145a4f04194f..7939bca47861 100644 --- a/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt +++ b/Documentation/devicetree/bindings/pci/nvidia,tegra20-pcie.txt @@ -65,6 +65,14 @@ Required properties: - afi - pcie_x +Optional properties: +- pinctrl-names: A list of pinctrl state names. Must contain the following + entries: + - "default": active state, puts PCIe I/O out of deep power down state + - "idle": puts PCIe I/O into deep power down state +- pinctrl-0: phandle for the default/active state of pin configurations. +- pinctrl-1: phandle for the idle state of pin configurations. + Required properties on Tegra124 and later (deprecated): - phys: Must contain an entry for each entry in phy-names. - phy-names: Must include the following entries: diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt index 92c01db610df..2a5d91024059 100644 --- a/Documentation/devicetree/bindings/pci/pci.txt +++ b/Documentation/devicetree/bindings/pci/pci.txt @@ -24,6 +24,9 @@ driver implementation may support the following properties: unsupported link speed, for instance, trying to do training for unsupported link speed, etc. Must be '4' for gen4, '3' for gen3, '2' for gen2, and '1' for gen1. Any other values are invalid. +- reset-gpios: + If present this property specifies PERST# GPIO. Host drivers can parse the + GPIO and apply fundamental reset to endpoints. PCI-PCI Bridge properties ------------------------- diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.txt b/Documentation/devicetree/bindings/pci/qcom,pcie.txt index 1fd703bd73e0..ada80b01bf0c 100644 --- a/Documentation/devicetree/bindings/pci/qcom,pcie.txt +++ b/Documentation/devicetree/bindings/pci/qcom,pcie.txt @@ -10,6 +10,7 @@ - "qcom,pcie-msm8996" for msm8996 or apq8096 - "qcom,pcie-ipq4019" for ipq4019 - "qcom,pcie-ipq8074" for ipq8074 + - "qcom,pcie-qcs404" for qcs404 - reg: Usage: required @@ -116,6 +117,15 @@ - "ahb" AHB clock - "aux" Auxiliary clock +- clock-names: + Usage: required for qcs404 + Value type: <stringlist> + Definition: Should contain the following entries + - "iface" AHB clock + - "aux" Auxiliary clock + - "master_bus" AXI Master clock + - "slave_bus" AXI Slave clock + - resets: Usage: required Value type: <prop-encoded-array> @@ -167,6 +177,17 @@ - "ahb" AHB Reset - "axi_m_sticky" AXI Master Sticky reset +- reset-names: + Usage: required for qcs404 + Value type: <stringlist> + Definition: Should contain the following entries + - "axi_m" AXI Master reset + - "axi_s" AXI Slave reset + - "axi_m_sticky" AXI Master Sticky reset + - "pipe_sticky" PIPE sticky reset + - "pwr" PWR reset + - "ahb" AHB reset + - power-domains: Usage: required for apq8084 and msm8996/apq8096 Value type: <prop-encoded-array> @@ -195,12 +216,12 @@ Definition: A phandle to the PCIe endpoint power supply - phys: - Usage: required for apq8084 + Usage: required for apq8084 and qcs404 Value type: <phandle> Definition: List of phandle(s) as listed in phy-names property - phy-names: - Usage: required for apq8084 + Usage: required for apq8084 and qcs404 Value type: <stringlist> Definition: Should contain "pciephy" diff --git a/Documentation/devicetree/bindings/pci/rcar-pci.txt b/Documentation/devicetree/bindings/pci/rcar-pci.txt index 6904882a0e94..45bba9f88a51 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci.txt +++ b/Documentation/devicetree/bindings/pci/rcar-pci.txt @@ -3,6 +3,7 @@ Required properties: compatible: "renesas,pcie-r8a7743" for the R8A7743 SoC; "renesas,pcie-r8a7744" for the R8A7744 SoC; + "renesas,pcie-r8a774a1" for the R8A774A1 SoC; "renesas,pcie-r8a774c0" for the R8A774C0 SoC; "renesas,pcie-r8a7779" for the R8A7779 SoC; "renesas,pcie-r8a7790" for the R8A7790 SoC; diff --git a/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml b/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml new file mode 100644 index 000000000000..250f9d5aabdf --- /dev/null +++ b/Documentation/devicetree/bindings/phy/allwinner,sun6i-a31-mipi-dphy.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/allwinner,sun6i-a31-mipi-dphy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 MIPI D-PHY Controller Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#phy-cells": + const: 0 + + compatible: + const: allwinner,sun6i-a31-mipi-dphy + + reg: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: bus + - const: mod + + resets: + maxItems: 1 + +required: + - "#phy-cells" + - compatible + - reg + - clocks + - clock-names + - resets + +additionalProperties: false + +examples: + - | + dphy0: d-phy@1ca1000 { + compatible = "allwinner,sun6i-a31-mipi-dphy"; + reg = <0x01ca1000 0x1000>; + clocks = <&ccu 23>, <&ccu 97>; + clock-names = "bus", "mod"; + resets = <&ccu 4>; + #phy-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/phy/phy-bindings.txt b/Documentation/devicetree/bindings/phy/phy-bindings.txt index a403b81d0679..c4eb38902533 100644 --- a/Documentation/devicetree/bindings/phy/phy-bindings.txt +++ b/Documentation/devicetree/bindings/phy/phy-bindings.txt @@ -1,5 +1,5 @@ This document explains only the device tree data binding. For general -information about PHY subsystem refer to Documentation/phy.txt +information about PHY subsystem refer to Documentation/driver-api/phy/phy.rst PHY device node =============== diff --git a/Documentation/devicetree/bindings/phy/phy-pxa-usb.txt b/Documentation/devicetree/bindings/phy/phy-pxa-usb.txt index 93fc09c12954..d80e36a77ec5 100644 --- a/Documentation/devicetree/bindings/phy/phy-pxa-usb.txt +++ b/Documentation/devicetree/bindings/phy/phy-pxa-usb.txt @@ -15,4 +15,4 @@ Example: }; This document explains the device tree binding. For general -information about PHY subsystem refer to Documentation/phy.txt +information about PHY subsystem refer to Documentation/driver-api/phy/phy.rst diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index cf96b7c20e4d..328585c6da58 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -24,6 +24,8 @@ Required properties: "allwinner,sun8i-h3-pinctrl" "allwinner,sun8i-h3-r-pinctrl" "allwinner,sun8i-r40-pinctrl" + "allwinner,sun8i-v3-pinctrl" + "allwinner,sun8i-v3s-pinctrl" "allwinner,sun50i-a64-pinctrl" "allwinner,sun50i-a64-r-pinctrl" "allwinner,sun50i-h5-pinctrl" diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml new file mode 100644 index 000000000000..125599a2dc5e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2400-pinctrl.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/aspeed,ast2400-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ASPEED AST2400 Pin Controller + +maintainers: + - Andrew Jeffery <andrew@aj.id.au> + +description: |+ + The pin controller node should be the child of a syscon node with the + required property: + + - compatible: Should be one of the following: + "aspeed,ast2400-scu", "syscon", "simple-mfd" + "aspeed,g4-scu", "syscon", "simple-mfd" + + Refer to the the bindings described in + Documentation/devicetree/bindings/mfd/syscon.txt + +properties: + compatible: + enum: + - aspeed,ast2400-pinctrl + - aspeed,g4-pinctrl + +patternProperties: + '^.*$': + if: + type: object + then: + patternProperties: + "^function|groups$": + allOf: + - $ref: "/schemas/types.yaml#/definitions/string" + - enum: [ "ACPI", "ADC0", "ADC1", "ADC10", "ADC11", "ADC12", "ADC13", + "ADC14", "ADC15", "ADC2", "ADC3", "ADC4", "ADC5", "ADC6", "ADC7", + "ADC8", "ADC9", "BMCINT", "DDCCLK", "DDCDAT", "EXTRST", "FLACK", + "FLBUSY", "FLWP", "GPID", "GPID0", "GPID2", "GPID4", "GPID6", + "GPIE0", "GPIE2", "GPIE4", "GPIE6", "I2C10", "I2C11", "I2C12", + "I2C13", "I2C14", "I2C3", "I2C4", "I2C5", "I2C6", "I2C7", "I2C8", + "I2C9", "LPCPD", "LPCPME", "LPCRST", "LPCSMI", "MAC1LINK", + "MAC2LINK", "MDIO1", "MDIO2", "NCTS1", "NCTS2", "NCTS3", "NCTS4", + "NDCD1", "NDCD2", "NDCD3", "NDCD4", "NDSR1", "NDSR2", "NDSR3", + "NDSR4", "NDTR1", "NDTR2", "NDTR3", "NDTR4", "NDTS4", "NRI1", + "NRI2", "NRI3", "NRI4", "NRTS1", "NRTS2", "NRTS3", "OSCCLK", + "PWM0", "PWM1", "PWM2", "PWM3", "PWM4", "PWM5", "PWM6", "PWM7", + "RGMII1", "RGMII2", "RMII1", "RMII2", "ROM16", "ROM8", "ROMCS1", + "ROMCS2", "ROMCS3", "ROMCS4", "RXD1", "RXD2", "RXD3", "RXD4", + "SALT1", "SALT2", "SALT3", "SALT4", "SD1", "SD2", "SGPMCK", + "SGPMI", "SGPMLD", "SGPMO", "SGPSCK", "SGPSI0", "SGPSI1", "SGPSLD", + "SIOONCTRL", "SIOPBI", "SIOPBO", "SIOPWREQ", "SIOPWRGD", "SIOS3", + "SIOS5", "SIOSCI", "SPI1", "SPI1DEBUG", "SPI1PASSTHRU", "SPICS1", + "TIMER3", "TIMER4", "TIMER5", "TIMER6", "TIMER7", "TIMER8", "TXD1", + "TXD2", "TXD3", "TXD4", "UART6", "USB11D1", "USB11H2", "USB2D1", + "USB2H1", "USBCKI", "VGABIOS_ROM", "VGAHS", "VGAVS", "VPI18", + "VPI24", "VPI30", "VPO12", "VPO24", "WDTRST1", "WDTRST2" ] + +required: + - compatible + +examples: + - | + syscon: scu@1e6e2000 { + compatible = "aspeed,ast2400-scu", "syscon", "simple-mfd"; + reg = <0x1e6e2000 0x1a8>; + + pinctrl: pinctrl { + compatible = "aspeed,g4-pinctrl"; + + pinctrl_i2c3_default: i2c3_default { + function = "I2C3"; + groups = "I2C3"; + }; + + pinctrl_gpioh0_unbiased_default: gpioh0 { + pins = "A8"; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml new file mode 100644 index 000000000000..3e6d85318577 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/aspeed,ast2500-pinctrl.yaml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/aspeed,ast2500-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ASPEED AST2500 Pin Controller + +maintainers: + - Andrew Jeffery <andrew@aj.id.au> + +description: |+ + The pin controller node should be the child of a syscon node with the + required property: + + - compatible: Should be one of the following: + "aspeed,ast2500-scu", "syscon", "simple-mfd" + "aspeed,g5-scu", "syscon", "simple-mfd" + + Refer to the the bindings described in + Documentation/devicetree/bindings/mfd/syscon.txt + +properties: + compatible: + enum: + - aspeed,ast2500-pinctrl + - aspeed,g5-pinctrl + aspeed,external-nodes: + minItems: 2 + maxItems: 2 + allOf: + - $ref: /schemas/types.yaml#/definitions/phandle-array + description: | + A cell of phandles to external controller nodes: + 0: compatible with "aspeed,ast2500-gfx", "syscon" + 1: compatible with "aspeed,ast2500-lhc", "syscon" + +patternProperties: + '^.*$': + if: + type: object + then: + patternProperties: + "^function|groups$": + allOf: + - $ref: "/schemas/types.yaml#/definitions/string" + - enum: [ "ACPI", "ADC0", "ADC1", "ADC10", "ADC11", "ADC12", "ADC13", + "ADC14", "ADC15", "ADC2", "ADC3", "ADC4", "ADC5", "ADC6", "ADC7", + "ADC8", "ADC9", "BMCINT", "DDCCLK", "DDCDAT", "ESPI", "FWSPICS1", + "FWSPICS2", "GPID0", "GPID2", "GPID4", "GPID6", "GPIE0", "GPIE2", + "GPIE4", "GPIE6", "I2C10", "I2C11", "I2C12", "I2C13", "I2C14", + "I2C3", "I2C4", "I2C5", "I2C6", "I2C7", "I2C8", "I2C9", "LAD0", + "LAD1", "LAD2", "LAD3", "LCLK", "LFRAME", "LPCHC", "LPCPD", + "LPCPLUS", "LPCPME", "LPCRST", "LPCSMI", "LSIRQ", "MAC1LINK", + "MAC2LINK", "MDIO1", "MDIO2", "NCTS1", "NCTS2", "NCTS3", "NCTS4", + "NDCD1", "NDCD2", "NDCD3", "NDCD4", "NDSR1", "NDSR2", "NDSR3", + "NDSR4", "NDTR1", "NDTR2", "NDTR3", "NDTR4", "NRI1", "NRI2", + "NRI3", "NRI4", "NRTS1", "NRTS2", "NRTS3", "NRTS4", "OSCCLK", + "PEWAKE", "PNOR", "PWM0", "PWM1", "PWM2", "PWM3", "PWM4", "PWM5", + "PWM6", "PWM7", "RGMII1", "RGMII2", "RMII1", "RMII2", "RXD1", + "RXD2", "RXD3", "RXD4", "SALT1", "SALT10", "SALT11", "SALT12", + "SALT13", "SALT14", "SALT2", "SALT3", "SALT4", "SALT5", "SALT6", + "SALT7", "SALT8", "SALT9", "SCL1", "SCL2", "SD1", "SD2", "SDA1", + "SDA2", "SGPS1", "SGPS2", "SIOONCTRL", "SIOPBI", "SIOPBO", + "SIOPWREQ", "SIOPWRGD", "SIOS3", "SIOS5", "SIOSCI", "SPI1", + "SPI1CS1", "SPI1DEBUG", "SPI1PASSTHRU", "SPI2CK", "SPI2CS0", + "SPI2CS1", "SPI2MISO", "SPI2MOSI", "TIMER3", "TIMER4", "TIMER5", + "TIMER6", "TIMER7", "TIMER8", "TXD1", "TXD2", "TXD3", "TXD4", + "UART6", "USB11BHID", "USB2AD", "USB2AH", "USB2BD", "USB2BH", + "USBCKI", "VGABIOSROM", "VGAHS", "VGAVS", "VPI24", "VPO", + "WDTRST1", "WDTRST2", ] + +required: + - compatible + - aspeed,external-nodes + +examples: + - | + apb { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + syscon: scu@1e6e2000 { + compatible = "aspeed,ast2500-scu", "syscon", "simple-mfd"; + reg = <0x1e6e2000 0x1a8>; + + pinctrl: pinctrl { + compatible = "aspeed,g5-pinctrl"; + aspeed,external-nodes = <&gfx>, <&lhc>; + + pinctrl_i2c3_default: i2c3_default { + function = "I2C3"; + groups = "I2C3"; + }; + + pinctrl_gpioh0_unbiased_default: gpioh0 { + pins = "A18"; + bias-disable; + }; + }; + }; + + gfx: display@1e6e6000 { + compatible = "aspeed,ast2500-gfx", "syscon"; + reg = <0x1e6e6000 0x1000>; + }; + }; + + lpc: lpc@1e789000 { + compatible = "aspeed,ast2500-lpc", "simple-mfd"; + reg = <0x1e789000 0x1000>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x1e789000 0x1000>; + + lpc_host: lpc-host@80 { + compatible = "aspeed,ast2500-lpc-host", "simple-mfd", "syscon"; + reg = <0x80 0x1e0>; + reg-io-width = <4>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x80 0x1e0>; + + lhc: lhc@20 { + compatible = "aspeed,ast2500-lhc"; + reg = <0x20 0x24 0x48 0x8>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt index ed34bb1ee81c..4980776122cc 100644 --- a/Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt @@ -14,7 +14,8 @@ 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 for BM1880 SoC -includes only pinmux as there is no pinconf support available in SoC. +includes pinmux and various pin configuration parameters, such as pull-up, +slew rate etc... Each configuration node can consist of multiple nodes describing the pinmux options. The name of each subnode is not important; all subnodes should be @@ -84,10 +85,37 @@ Required Properties: gpio66, gpio67, eth1, i2s0, i2s0_mclkin, i2s1, i2s1_mclkin, spi0 +Optional Properties: + +- bias-disable: No arguments. Disable pin bias. +- bias-pull-down: No arguments. The specified pins should be configured as + pull down. +- bias-pull-up: No arguments. The specified pins should be configured as + pull up. +- input-schmitt-enable: No arguments: Enable schmitt trigger for the specified + pins +- input-schmitt-disable: No arguments: Disable schmitt trigger for the specified + pins +- slew-rate: Integer. Sets slew rate for the specified pins. + Valid values are: + <0> - Slow + <1> - Fast +- drive-strength: Integer. Selects the drive strength for the specified + pins in mA. + Valid values are: + <4> + <8> + <12> + <16> + <20> + <24> + <28> + <32> + Example: - pinctrl: pinctrl@50 { + pinctrl: pinctrl@400 { compatible = "bitmain,bm1880-pinctrl"; - reg = <0x50 0x4B0>; + reg = <0x400 0x120>; pinctrl_uart0_default: uart0-default { pinmux { diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt index 3fac0a061bcc..ac6d614d74e0 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt @@ -5,6 +5,9 @@ controller, and pinmux/control device. Required properties: - compatible: "brcm,bcm2835-gpio" +- compatible: should be one of: + "brcm,bcm2835-gpio" - BCM2835 compatible pinctrl + "brcm,bcm7211-gpio" - BCM7211 compatible pinctrl - reg: Should contain the physical address of the GPIO module's registers. - gpio-controller: Marks the device node as a GPIO controller. - #gpio-cells : Should be two. The first cell is the pin number and the diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.txt index 524a16fca666..e4e01c05cf83 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mm-pinctrl.txt @@ -12,7 +12,7 @@ Required properties in sub-nodes: - 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 - <dt-bindings/pinctrl/imx8mm-pinfunc.h>. The last integer CONFIG is + <arch/arm64/boot/dts/freescale/imx8mm-pinfunc.h>. The last integer CONFIG is the pad setting value like pull-up on this pin. Please refer to i.MX8M Mini Reference Manual for detailed CONFIG settings. diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.txt new file mode 100644 index 000000000000..330716c971b9 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx8mn-pinctrl.txt @@ -0,0 +1,39 @@ +* Freescale IMX8MN IOMUX Controller + +Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory +for common binding part and usage. + +Required properties: +- compatible: "fsl,imx8mn-iomuxc" +- reg: should contain the base physical address and size of the iomuxc + registers. + +Required properties in sub-nodes: +- 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 + <arch/arm64/boot/dts/freescale/imx8mn-pinfunc.h>. The last integer CONFIG is + the pad setting value like pull-up on this pin. Please refer to i.MX8M Nano + Reference Manual for detailed CONFIG settings. + +Examples: + +&uart1 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_uart1>; +}; + +iomuxc: pinctrl@30330000 { + compatible = "fsl,imx8mn-iomuxc"; + reg = <0x0 0x30330000 0x0 0x10000>; + + pinctrl_uart1: uart1grp { + fsl,pins = < + MX8MN_IOMUXC_UART1_RXD_UART1_DCE_RX 0x140 + MX8MN_IOMUXC_UART1_TXD_UART1_DCE_TX 0x140 + MX8MN_IOMUXC_UART3_RXD_UART1_DCE_CTS_B 0x140 + MX8MN_IOMUXC_UART3_TXD_UART1_DCE_RTS_B 0x140 + MX8MN_IOMUXC_SD1_DATA4_GPIO2_IO6 0x19 + >; + }; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt index 6c0ea155b708..2932f171ee85 100644 --- a/Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt @@ -6,8 +6,8 @@ part and usage. Required properties: - compatible: "marvell,88f6180-pinctrl", "marvell,88f6190-pinctrl", "marvell,88f6192-pinctrl", - "marvell,88f6281-pinctrl", "marvell,88f6282-pinctrl" - "marvell,98dx4122-pinctrl" + "marvell,88f6281-pinctrl", "marvell,88f6282-pinctrl", + "marvell,98dx4122-pinctrl", "marvell,98dx1135-pinctrl" - reg: register specifier of MPP registers This driver supports all kirkwood variants, i.e. 88f6180, 88f619x, and 88f628x. @@ -317,3 +317,43 @@ mpp44 44 gpio mpp45 45 gpio mpp49 49 gpio +* Marvell Poncat2 98dx1135 + +name pins functions +================================================================================ + +mpp0 0 gpio, nand(io2), spi(cs) +mpp1 1 gpo, nand(io3), spi(mosi) +mpp2 2 gpo, nand(io4), spi(sck) +mpp3 3 gpo, nand(io5), spi(miso) +mpp4 4 gpio, nand(io6), uart0(rxd) +mpp5 5 gpo, nand(io7), uart0(txd) +mpp6 6 sysrst(out) +mpp7 7 gpo, spi(cs) +mpp8 8 gpio, twsi0(sda), uart1(rts) +mpp9 9 gpio, twsi(sck), uart1(cts) +mpp10 10 gpo, uart0(txd) +mpp11 11 gpio, uart0(rxd) +mpp13 13 gpio, uart1(txd) +mpp14 14 gpio, uart1(rxd) +mpp15 15 gpio, uart0(rts) +mpp16 16 gpio, uart0(cts) +mpp17 17 gpio, nand(cle) +mpp18 18 gpo, nand(io0) +mpp19 19 gpo, nand(io1) +mpp20 20 gpio +mpp21 21 gpio +mpp22 22 gpio +mpp23 23 gpio +mpp24 24 gpio +mpp25 25 gpio +mpp26 26 gpio +mpp27 27 gpio +mpp28 28 gpio, nand(ren) +mpp29 29 gpio, nand(wen) +mpp30 30 gpio +mpp31 31 gpio +mpp32 32 gpio +mpp33 33 gpio +mpp34 34 gpio, nand(ale) +mpp35 35 gpio, nand(cen) diff --git a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt index a47dd990a8d3..10dc4f7176ca 100644 --- a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt @@ -47,9 +47,19 @@ Required properties for pinmux nodes are: Required properties for configuration nodes: - pins: a list of pin names -Configuration nodes support the generic properties "bias-disable", -"bias-pull-up" and "bias-pull-down", described in file -pinctrl-bindings.txt +Configuration nodes support the following generic properties, as +described in file pinctrl-bindings.txt: + - "bias-disable" + - "bias-pull-up" + - "bias-pull-down" + - "output-enable" + - "output-disable" + - "output-low" + - "output-high" + +Optional properties : + - drive-strength-microamp: Drive strength for the specified pins in uA. + This property is only valid for G12A and newer. === Example === diff --git a/Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt index 29b72e303ebf..51efd2085113 100644 --- a/Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt @@ -5,7 +5,7 @@ Please refer to pinctrl-bindings.txt, ../gpio/gpio.txt, and 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 +used for a specific device or function. This node represents configurations of pins, optional function, and optional mux related configuration. Required properties for pin controller node: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt new file mode 100644 index 000000000000..8763f448c376 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra194-pinmux.txt @@ -0,0 +1,107 @@ +NVIDIA Tegra194 pinmux controller + +Required properties: +- compatible: "nvidia,tegra194-pinmux" +- reg: Should contain a list of base address and size pairs for: + - first entry: The APB_MISC_GP_*_PADCTRL registers (pad control) + - second entry: The PINMUX_AUX_* registers (pinmux) + +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". + +Tegra's 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, tristate, drive strength, etc. + +See the TRM to determine which properties and values apply to each pin/group. +Macro values for property values are defined in +include/dt-binding/pinctrl/pinctrl-tegra.h. + +Required subnode-properties: +- nvidia,pins : An array of strings. Each string contains the name of a pin or + group. Valid values for these names are listed below. + +Optional subnode-properties: +- nvidia,function: A string containing the name of the function to mux to the + pin or group. +- nvidia,pull: Integer, representing the pull-down/up to apply to the pin. + 0: none, 1: down, 2: up. +- nvidia,tristate: Integer. + 0: drive, 1: tristate. +- nvidia,enable-input: Integer. Enable the pin's input path. + enable :TEGRA_PIN_ENABLE and + disable or output only: TEGRA_PIN_DISABLE. +- nvidia,open-drain: Integer. + enable: TEGRA_PIN_ENABLE. + disable: TEGRA_PIN_DISABLE. +- nvidia,lock: Integer. Lock the pin configuration against further changes + until reset. + enable: TEGRA_PIN_ENABLE. + disable: TEGRA_PIN_DISABLE. +- nvidia,io-hv: Integer. Select high-voltage receivers. + normal: TEGRA_PIN_DISABLE + high: TEGRA_PIN_ENABLE +- nvidia,schmitt: Integer. Enables Schmitt Trigger on the input. + normal: TEGRA_PIN_DISABLE + high: TEGRA_PIN_ENABLE +- nvidia,drive-type: Integer. Valid range 0...3. +- nvidia,pull-down-strength: Integer. Controls drive strength. 0 is weakest. + The range of valid values depends on the pingroup. See "CAL_DRVDN" in the + Tegra TRM. +- nvidia,pull-up-strength: Integer. Controls drive strength. 0 is weakest. + The range of valid values depends on the pingroup. See "CAL_DRVUP" in the + Tegra TRM. + +Valid values for pin and group names (nvidia,pin) are: + + These correspond to Tegra PADCTL_* (pinmux) registers. + + Mux groups: + + These correspond to Tegra PADCTL_* (pinmux) registers. Any property + that exists in those registers may be set for the following pin names. + + pex_l5_clkreq_n_pgg0, pex_l5_rst_n_pgg1 + + Drive groups: + + These registers controls a single pin for which a mux group exists. + See the list above for the pin name to use when configuring the pinmux. + + pex_l5_clkreq_n_pgg0, pex_l5_rst_n_pgg1 + +Valid values for nvidia,functions are: + + pe5 + +Power Domain: + pex_l5_clkreq_n_pgg0 and pex_l5_rst_n_pgg1 are part of PCIE C5 power + partition. Client devices must enable this partition before accessing + these pins here. + + +Example: + + tegra_pinctrl: pinmux: pinmux@2430000 { + compatible = "nvidia,tegra194-pinmux"; + reg = <0x2430000 0x17000 + 0xc300000 0x4000>; + + pinctrl-names = "pex_rst"; + pinctrl-0 = <&pex_rst_c5_out_state>; + + pex_rst_c5_out_state: pex_rst_c5_out { + pex_rst { + nvidia,pins = "pex_l5_rst_n_pgg1"; + nvidia,schmitt = <TEGRA_PIN_DISABLE>; + nvidia,lpdr = <TEGRA_PIN_ENABLE>; + nvidia,enable-input = <TEGRA_PIN_DISABLE>; + nvidia,io-high-voltage = <TEGRA_PIN_ENABLE>; + nvidia,tristate = <TEGRA_PIN_DISABLE>; + nvidia,pull = <TEGRA_PIN_PULL_NONE>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt deleted file mode 100644 index 3b7266c7c438..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt +++ /dev/null @@ -1,172 +0,0 @@ -====================== -Aspeed Pin Controllers -====================== - -The Aspeed SoCs vary in functionality inside a generation but have a common mux -device register layout. - -Required properties for g4: -- compatible : Should be one of the following: - "aspeed,ast2400-pinctrl" - "aspeed,g4-pinctrl" - -Required properties for g5: -- compatible : Should be one of the following: - "aspeed,ast2500-pinctrl" - "aspeed,g5-pinctrl" - -- aspeed,external-nodes: A cell of phandles to external controller nodes: - 0: compatible with "aspeed,ast2500-gfx", "syscon" - 1: compatible with "aspeed,ast2500-lhc", "syscon" - -The pin controller node should be the child of a syscon node with the required -property: - -- compatible : Should be one of the following: - "aspeed,ast2400-scu", "syscon", "simple-mfd" - "aspeed,g4-scu", "syscon", "simple-mfd" - "aspeed,ast2500-scu", "syscon", "simple-mfd" - "aspeed,g5-scu", "syscon", "simple-mfd" - -Refer to the the bindings described in -Documentation/devicetree/bindings/mfd/syscon.txt - -Subnode Format -============== - -The required properties of pinmux child nodes are: -- function: the mux function to select -- groups : the list of groups to select with this function - -Required properties of pinconf child nodes are: -- groups: A list of groups to select (either this or "pins" must be - specified) -- pins : A list of ball names as strings, eg "D14" (either this or "groups" - must be specified) - -Optional properties of pinconf child nodes are: -- bias-disable : disable any pin bias -- bias-pull-down: pull down the pin -- drive-strength: sink or source at most X mA - -Definitions are as specified in -Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt, with any -further limitations as described above. - -For pinmux, each mux function has only one associated pin group. Each group is -named by its function. The following values for the function and groups -properties are supported: - -aspeed,ast2400-pinctrl, aspeed,g4-pinctrl: - -ACPI ADC0 ADC1 ADC10 ADC11 ADC12 ADC13 ADC14 ADC15 ADC2 ADC3 ADC4 ADC5 ADC6 -ADC7 ADC8 ADC9 BMCINT DDCCLK DDCDAT EXTRST FLACK FLBUSY FLWP GPID GPID0 GPID2 -GPID4 GPID6 GPIE0 GPIE2 GPIE4 GPIE6 I2C10 I2C11 I2C12 I2C13 I2C14 I2C3 I2C4 -I2C5 I2C6 I2C7 I2C8 I2C9 LPCPD LPCPME LPCRST LPCSMI MAC1LINK MAC2LINK MDIO1 -MDIO2 NCTS1 NCTS2 NCTS3 NCTS4 NDCD1 NDCD2 NDCD3 NDCD4 NDSR1 NDSR2 NDSR3 NDSR4 -NDTR1 NDTR2 NDTR3 NDTR4 NDTS4 NRI1 NRI2 NRI3 NRI4 NRTS1 NRTS2 NRTS3 OSCCLK PWM0 -PWM1 PWM2 PWM3 PWM4 PWM5 PWM6 PWM7 RGMII1 RGMII2 RMII1 RMII2 ROM16 ROM8 ROMCS1 -ROMCS2 ROMCS3 ROMCS4 RXD1 RXD2 RXD3 RXD4 SALT1 SALT2 SALT3 SALT4 SD1 SD2 SGPMCK -SGPMI SGPMLD SGPMO SGPSCK SGPSI0 SGPSI1 SGPSLD SIOONCTRL SIOPBI SIOPBO SIOPWREQ -SIOPWRGD SIOS3 SIOS5 SIOSCI SPI1 SPI1DEBUG SPI1PASSTHRU SPICS1 TIMER3 TIMER4 -TIMER5 TIMER6 TIMER7 TIMER8 TXD1 TXD2 TXD3 TXD4 UART6 USB11D1 USB11H2 USB2D1 -USB2H1 USBCKI VGABIOS_ROM VGAHS VGAVS VPI18 VPI24 VPI30 VPO12 VPO24 WDTRST1 -WDTRST2 - -aspeed,ast2500-pinctrl, aspeed,g5-pinctrl: - -ACPI ADC0 ADC1 ADC10 ADC11 ADC12 ADC13 ADC14 ADC15 ADC2 ADC3 ADC4 ADC5 ADC6 -ADC7 ADC8 ADC9 BMCINT DDCCLK DDCDAT ESPI FWSPICS1 FWSPICS2 GPID0 GPID2 GPID4 -GPID6 GPIE0 GPIE2 GPIE4 GPIE6 I2C10 I2C11 I2C12 I2C13 I2C14 I2C3 I2C4 I2C5 I2C6 -I2C7 I2C8 I2C9 LAD0 LAD1 LAD2 LAD3 LCLK LFRAME LPCHC LPCPD LPCPLUS LPCPME -LPCRST LPCSMI LSIRQ MAC1LINK MAC2LINK MDIO1 MDIO2 NCTS1 NCTS2 NCTS3 NCTS4 NDCD1 -NDCD2 NDCD3 NDCD4 NDSR1 NDSR2 NDSR3 NDSR4 NDTR1 NDTR2 NDTR3 NDTR4 NRI1 NRI2 -NRI3 NRI4 NRTS1 NRTS2 NRTS3 NRTS4 OSCCLK PEWAKE PNOR PWM0 PWM1 PWM2 PWM3 PWM4 -PWM5 PWM6 PWM7 RGMII1 RGMII2 RMII1 RMII2 RXD1 RXD2 RXD3 RXD4 SALT1 SALT10 -SALT11 SALT12 SALT13 SALT14 SALT2 SALT3 SALT4 SALT5 SALT6 SALT7 SALT8 SALT9 -SCL1 SCL2 SD1 SD2 SDA1 SDA2 SGPS1 SGPS2 SIOONCTRL SIOPBI SIOPBO SIOPWREQ -SIOPWRGD SIOS3 SIOS5 SIOSCI SPI1 SPI1CS1 SPI1DEBUG SPI1PASSTHRU SPI2CK SPI2CS0 -SPI2CS1 SPI2MISO SPI2MOSI TIMER3 TIMER4 TIMER5 TIMER6 TIMER7 TIMER8 TXD1 TXD2 -TXD3 TXD4 UART6 USB11BHID USB2AD USB2AH USB2BD USB2BH USBCKI VGABIOSROM VGAHS -VGAVS VPI24 VPO WDTRST1 WDTRST2 - -Examples -======== - -g4 Example ----------- - -syscon: scu@1e6e2000 { - compatible = "aspeed,ast2400-scu", "syscon", "simple-mfd"; - reg = <0x1e6e2000 0x1a8>; - - pinctrl: pinctrl { - compatible = "aspeed,g4-pinctrl"; - - pinctrl_i2c3_default: i2c3_default { - function = "I2C3"; - groups = "I2C3"; - }; - - pinctrl_gpioh0_unbiased_default: gpioh0 { - pins = "A8"; - bias-disable; - }; - }; -}; - -g5 Example ----------- - -ahb { - apb { - syscon: scu@1e6e2000 { - compatible = "aspeed,ast2500-scu", "syscon", "simple-mfd"; - reg = <0x1e6e2000 0x1a8>; - - pinctrl: pinctrl { - compatible = "aspeed,g5-pinctrl"; - aspeed,external-nodes = <&gfx &lhc>; - - pinctrl_i2c3_default: i2c3_default { - function = "I2C3"; - groups = "I2C3"; - }; - - pinctrl_gpioh0_unbiased_default: gpioh0 { - pins = "A18"; - bias-disable; - }; - }; - }; - - gfx: display@1e6e6000 { - compatible = "aspeed,ast2500-gfx", "syscon"; - reg = <0x1e6e6000 0x1000>; - }; - }; - - lpc: lpc@1e789000 { - compatible = "aspeed,ast2500-lpc", "simple-mfd"; - reg = <0x1e789000 0x1000>; - - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x1e789000 0x1000>; - - lpc_host: lpc-host@80 { - compatible = "aspeed,ast2500-lpc-host", "simple-mfd", "syscon"; - reg = <0x80 0x1e0>; - reg-io-width = <4>; - - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x80 0x1e0>; - - lhc: lhc@20 { - compatible = "aspeed,ast2500-lhc"; - reg = <0x20 0x24 0x48 0x8>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt index cef2b5855d60..fcd37e93ed4d 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt @@ -258,6 +258,7 @@ drive-push-pull - drive actively high and low drive-open-drain - drive with open drain drive-open-source - drive with open source drive-strength - sink or source at most X mA +drive-strength-microamp - sink or source at most X uA input-enable - enable input on pin (no effect on output, such as enabling an input buffer) input-disable - disable input on pin (no effect on output, such as @@ -326,6 +327,8 @@ arguments are described below. - drive-strength takes as argument the target strength in mA. +- drive-strength-microamp takes as argument the target strength in uA. + - input-debounce takes the debounce time in usec as argument or 0 to disable debouncing diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt index 68e93d5b7ede..c9782397ff14 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,apq8084-pinctrl.txt @@ -122,17 +122,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt index 6dd72f8599e9..7b151894f5a0 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt @@ -118,17 +118,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt index 86ecdcfc4fb8..d46973968873 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9615-pinctrl.txt @@ -97,17 +97,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt index 195a7a0ef0cc..3354a63296d9 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8916-pinctrl.txt @@ -130,17 +130,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt index 5034eb6653c7..a7dd213c77c6 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8960-pinctrl.txt @@ -124,17 +124,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt index f15443f6e78e..da52df6273bc 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8994-pinctrl.txt @@ -128,17 +128,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt index fa97f609fe45..a56cb882830c 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt @@ -149,17 +149,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt index e70c79bbbc5b..cdec1eeb2799 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt @@ -40,6 +40,14 @@ MSM8998 platform. Definition: must be 2. Specifying the pin number and flags, as defined in <dt-bindings/gpio/gpio.h> +- gpio-ranges: + Usage: required + Definition: see ../gpio/gpio.txt + +- gpio-reserved-ranges: + Usage: optional + Definition: see ../gpio/gpio.txt + Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for a general description of GPIO and interrupt bindings. @@ -135,17 +143,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional @@ -175,6 +183,8 @@ Example: interrupts = <0 208 0>; gpio-controller; #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 175>; + gpio-reserved-ranges = <0 4>, <81 4>; interrupt-controller; #interrupt-cells = <2>; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt index 2b8f77762edc..a50e74684195 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,qcs404-pinctrl.txt @@ -150,17 +150,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt index 769ca83bb40d..be034d329e10 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm660-pinctrl.txt @@ -142,17 +142,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt index 665aadb5ea28..7462e3743c68 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sdm845-pinctrl.txt @@ -79,7 +79,7 @@ to specify in a pin configuration subnode: gpio0-gpio149 Supports mux, bias and drive-strength - sdc2_clk, sdc2_cmd, sdc2_data + sdc2_clk, sdc2_cmd, sdc2_data, ufs_reset Supports bias and drive-strength - function: @@ -118,17 +118,17 @@ to specify in a pin configuration subnode: - bias-disable: Usage: optional Value type: <none> - Definition: The specified pins should be configued as no pull. + Definition: The specified pins should be configured as no pull. - bias-pull-down: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull down. + Definition: The specified pins should be configured as pull down. - bias-pull-up: Usage: optional Value type: <none> - Definition: The specified pins should be configued as pull up. + Definition: The specified pins should be configured as pull up. - output-high: Usage: optional diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt new file mode 100644 index 000000000000..fa37733e5102 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sm8150-pinctrl.txt @@ -0,0 +1,190 @@ +Qualcomm SM8150 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +QCS404 platform. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,sm8150-pinctrl" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: the base address and size of the north, south, west + and east TLMM tiles. + +- reg-names: + Usage: required + Value type: <prop-encoded-array> + Defintiion: names for the cells of reg, must contain "north", "south" + "west" and "east". + +- 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> + +- gpio-ranges: + Usage: required + Value type: <prop-encoded-array> + Definition: see ../gpio/gpio.txt + +- gpio-reserved-ranges: + Usage: optional + Value type: <prop-encoded-array> + Definition: see ../gpio/gpio.txt + +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 + + ufs_reset + 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: + + adsp_ext, agera_pll, aoss_cti, ddr_pxi2, atest_char, + atest_char0, atest_char1, atest_char2, atest_char3, + audio_ref, atest_usb1, atest_usb2, atest_usb10, + atest_usb11, atest_usb12, atest_usb13, atest_usb20, + atest_usb21, atest_usb22, atest_usb2, atest_usb23, + btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0, + cci_timer1, cci_timer2, cci_timer3, cci_timer4, + cri_trng, cri_trng0, cri_trng1, dbg_out, ddr_bist, + ddr_pxi0, ddr_pxi1, ddr_pxi3, edp_hot, edp_lcd, + emac_phy, emac_pps, gcc_gp1, gcc_gp2, gcc_gp3, gpio, + hs1_mi2s, hs2_mi2s, hs3_mi2s, jitter_bist, + lpass_slimbus, mdp_vsync, mdp_vsync0, mdp_vsync1, + mdp_vsync2, mdp_vsync3, mss_lte, m_voc, nav_pps, + pa_indicator, pci_e0, phase_flag, pll_bypassnl, + pll_bist, pci_e1, pll_reset, pri_mi2s, pri_mi2s_ws, + prng_rosc, qdss, qdss_cti, qlink_request, qlink_enable, + qspi0, qspi1, qspi2, qspi3, qspi_clk, qspi_cs, qua_mi2s, + qup0, qup1, qup2, qup3, qup4, qup5, qup6, qup7, qup8, + qup9, qup10, qup11, qup12, qup13, qup14, qup15, qup16, + qup17, qup18, qup19, qup_l4, qup_l5, qup_l6, rgmii, + sdc4, sd_write, sec_mi2s, spkr_i2s, sp_cmu, ter_mi2s, + tgu_ch0, tgu_ch1, tgu_ch2, tgu_ch3, tsense_pwm1, + tsense_pwm2, tsif1, tsif2, uim1, uim2, uim_batt, + usb2phy_ac, usb_phy, vfr_1, vsense_trigger, wlan1_adc0, + wlan1_adc1, wlan2_adc0, wlan2_adc1, wmss_reset + +- 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@3000000 { + compatible = "qcom,sm8150-pinctrl"; + reg = <0x03100000 0x300000>, + <0x03500000 0x300000>, + <0x03900000 0x300000>, + <0x03D00000 0x300000>; + reg-names = "west", "east", "north", "south"; + interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&tlmm 0 0 175>; + gpio-reserved-ranges = <0 4>, <126 4>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt deleted file mode 100644 index 00169255e48c..000000000000 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ /dev/null @@ -1,208 +0,0 @@ -* 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: - "st,stm32f429-pinctrl" - "st,stm32f469-pinctrl" - "st,stm32f746-pinctrl" - "st,stm32f769-pinctrl" - "st,stm32h743-pinctrl" - "st,stm32mp157-pinctrl" - "st,stm32mp157-z-pinctrl" - - #address-cells: The value of this property must be 1 - - #size-cells : The value of this property must be 1 - - ranges : defines mapping between pin controller node (parent) to - 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 - - st,syscfg: Should be phandle/offset/mask. - -The phandle to the syscon node which includes IRQ mux selection register. - -The offset of the IRQ mux selection register - -The field mask of IRQ mux, needed if different of 0xf. - - gpio-ranges: Define a dedicated mapping between a pin-controller and - a gpio controller. Format is <&phandle a b c> with: - -(phandle): phandle of pin-controller. - -(a): gpio base offset in range. - -(b): pin base offset in range. - -(c): gpio count in range - This entry has to be used either if there are holes inside a bank: - GPIOB0/B1/B2/B14/B15 (see example 2) - or if banks are not contiguous: - GPIOA/B/C/E... - NOTE: If "gpio-ranges" is used for a gpio controller, all gpio-controller - have to use a "gpio-ranges" entry. - More details in Documentation/devicetree/bindings/gpio/gpio.txt. - - st,bank-ioport: should correspond to the EXTI IOport selection (EXTI line - used to select GPIOs as interrupts). - - hwlocks: reference to a phandle of a hardware spinlock provider node. - - st,package: Indicates the SOC package used. - More details in include/dt-bindings/pinctrl/stm32-pinfunc.h - -Example 1: -#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... - }; - -Example 2: -#include <dt-bindings/pinctrl/stm32f429-pinfunc.h> -... - - pinctrl: 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"; - gpio-ranges = <&pinctrl 0 0 16>; - }; - - gpiob: gpio@40020400 { - gpio-controller; - #gpio-cells = <2>; - reg = <0x0 0x400>; - resets = <&reset_ahb1 0>; - st,bank-name = "GPIOB"; - ngpios = 4; - gpio-ranges = <&pinctrl 0 16 3>, - <&pinctrl 14 30 2>; - }; - - - ... - 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 - - To simplify the usage, macro is available to generate "pinmux" field. - This macro is available here: - - include/dt-bindings/pinctrl/stm32-pinfunc.h - - Some examples of using macro: - /* GPIO A9 set as alernate function 2 */ - ... { - pinmux = <STM32_PINMUX('A', 9, AF2)>; - }; - /* GPIO A9 set as GPIO */ - ... { - pinmux = <STM32_PINMUX('A', 9, GPIO)>; - }; - /* GPIO A9 set as analog */ - ... { - pinmux = <STM32_PINMUX('A', 9, 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 = <STM32_PINMUX('A', 9, AF7)>; - bias-disable; - drive-push-pull; - slew-rate = <0>; - }; - pins2 { - pinmux = <STM32_PINMUX('A', 10, AF7)>; - bias-disable; - }; - }; -}; - -&usart1 { - pinctrl-0 = <&usart1_pins_a>; - pinctrl-names = "default"; -}; diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml new file mode 100644 index 000000000000..91d3e78b3395 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml @@ -0,0 +1,271 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (C) STMicroelectronics 2019. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/st,stm32-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STM32 GPIO and Pin Mux/Config controller + +maintainers: + - Alexandre TORGUE <alexandre.torgue@st.com> + +description: | + 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. + +properties: + compatible: + enum: + - st,stm32f429-pinctrl + - st,stm32f469-pinctrl + - st,stm32f746-pinctrl + - st,stm32f769-pinctrl + - st,stm32h743-pinctrl + - st,stm32mp157-pinctrl + - st,stm32mp157-z-pinctrl + + '#address-cells': + const: 1 + '#size-cells': + const: 1 + + ranges: true + pins-are-numbered: true + hwlocks: true + + st,syscfg: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + description: Should be phandle/offset/mask + items: + - description: Phandle to the syscon node which includes IRQ mux selection. + - description: The offset of the IRQ mux selection register. + - description: The field mask of IRQ mux, needed if different of 0xf. + + st,package: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - enum: [1, 2, 4, 8] + description: + Indicates the SOC package used. + More details in include/dt-bindings/pinctrl/stm32-pinfunc.h + + +patternProperties: + '^gpio@[0-9a-f]*$': + type: object + properties: + gpio-controller: true + '#gpio-cells': + const: 2 + + reg: + maxItems: 1 + clocks: + maxItems: 1 + reset: + minItems: 1 + maxItems: 1 + gpio-ranges: + minItems: 1 + maxItems: 16 + ngpios: + description: + Number of available gpios in a bank. + minimum: 1 + maximum: 16 + + st,bank-name: + allOf: + - $ref: "/schemas/types.yaml#/definitions/string" + - enum: + - GPIOA + - GPIOB + - GPIOC + - GPIOD + - GPIOE + - GPIOF + - GPIOG + - GPIOH + - GPIOI + - GPIOJ + - GPIOK + - GPIOZ + description: + Should be a name string for this bank as specified in the datasheet. + + st,bank-ioport: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - minimum: 0 + - maximum: 11 + + description: + Should correspond to the EXTI IOport selection (EXTI line used + to select GPIOs as interrupts). + + required: + - gpio-controller + - '#gpio-cells' + - reg + - clocks + - st,bank-name + + '-[0-9]*$': + type: object + patternProperties: + '^pins': + type: object + description: | + 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. + properties: + pinmux: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32-array" + description: | + 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 + To simplify the usage, macro is available to generate "pinmux" field. + This macro is available here: + - include/dt-bindings/pinctrl/stm32-pinfunc.h + Some examples of using macro: + /* GPIO A9 set as alernate function 2 */ + ... { + pinmux = <STM32_PINMUX('A', 9, AF2)>; + }; + /* GPIO A9 set as GPIO */ + ... { + pinmux = <STM32_PINMUX('A', 9, GPIO)>; + }; + /* GPIO A9 set as analog */ + ... { + pinmux = <STM32_PINMUX('A', 9, ANALOG)>; + }; + + bias-disable: + type: boolean + bias-pull-down: + type: boolean + bias-pull-up: + type: boolean + drive-push-pull: + type: boolean + drive-open-drain: + type: boolean + output-low: + type: boolean + output-high: + type: boolean + slew-rate: + description: | + 0: Low speed + 1: Medium speed + 2: Fast speed + 3: High speed + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - enum: [0, 1, 2, 3] + + required: + - pinmux + +required: + - compatible + - '#address-cells' + - '#size-cells' + - ranges + - pins-are-numbered + +examples: + - | + #include <dt-bindings/pinctrl/stm32-pinfunc.h> + #include <dt-bindings/mfd/stm32f4-rcc.h> + //Example 1 + pinctrl@40020000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "st,stm32f429-pinctrl"; + ranges = <0 0x40020000 0x3000>; + pins-are-numbered; + + gpioa: gpio@0 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x0 0x400>; + resets = <&reset_ahb1 0>; + clocks = <&rcc 0 STM32F4_AHB1_CLOCK(GPIOA)>; + st,bank-name = "GPIOA"; + }; + }; + + //Example 2 (using gpio-ranges) + pinctrl@50020000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "st,stm32f429-pinctrl"; + ranges = <0 0x50020000 0x3000>; + pins-are-numbered; + + gpiob: gpio@1000 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x1000 0x400>; + resets = <&reset_ahb1 0>; + clocks = <&rcc 0 STM32F4_AHB1_CLOCK(GPIOB)>; + st,bank-name = "GPIOB"; + gpio-ranges = <&pinctrl 0 0 16>; + }; + + gpioc: gpio@2000 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x2000 0x400>; + resets = <&reset_ahb1 0>; + clocks = <&rcc 0 STM32F4_AHB1_CLOCK(GPIOC)>; + st,bank-name = "GPIOC"; + ngpios = <5>; + gpio-ranges = <&pinctrl 0 16 3>, + <&pinctrl 14 30 2>; + }; + }; + + //Example 3 pin groups + pinctrl@60020000 { + usart1_pins_a: usart1-0 { + pins1 { + pinmux = <STM32_PINMUX('A', 9, AF7)>; + bias-disable; + drive-push-pull; + slew-rate = <0>; + }; + pins2 { + pinmux = <STM32_PINMUX('A', 10, AF7)>; + bias-disable; + }; + }; + }; + + usart1 { + pinctrl-0 = <&usart1_pins_a>; + pinctrl-names = "default"; + }; + +... diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.txt b/Documentation/devicetree/bindings/power/qcom,rpmpd.txt index 980e5413d18f..eb35b22f9e23 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.txt +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.txt @@ -6,6 +6,8 @@ which then translates it into a corresponding voltage on a rail Required Properties: - compatible: Should be one of the following * qcom,msm8996-rpmpd: RPM Power domain for the msm8996 family of SoC + * qcom,msm8998-rpmpd: RPM Power domain for the msm8998 family of SoC + * qcom,qcs404-rpmpd: RPM Power domain for the qcs404 family of SoC * qcom,sdm845-rpmhpd: RPMh Power domain for the sdm845 family of SoC - #power-domain-cells: number of cells in Power domain specifier must be 1. diff --git a/Documentation/devicetree/bindings/power/reset/nvmem-reboot-mode.txt b/Documentation/devicetree/bindings/power/reset/nvmem-reboot-mode.txt new file mode 100644 index 000000000000..752d6126d5da --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/nvmem-reboot-mode.txt @@ -0,0 +1,26 @@ +NVMEM reboot mode driver + +This driver gets reboot mode magic value from reboot-mode driver +and stores it in a NVMEM cell named "reboot-mode". Then the bootloader +can read it and take different action according to the magic +value stored. + +Required properties: +- compatible: should be "nvmem-reboot-mode". +- nvmem-cells: A phandle to the reboot mode provided by a nvmem device. +- nvmem-cell-names: Should be "reboot-mode". + +The rest of the properties should follow the generic reboot-mode description +found in reboot-mode.txt + +Example: + reboot-mode { + compatible = "nvmem-reboot-mode"; + nvmem-cells = <&reboot_mode>; + nvmem-cell-names = "reboot-mode"; + + mode-normal = <0xAAAA5501>; + mode-bootloader = <0xBBBB5500>; + mode-recovery = <0xCCCC5502>; + mode-test = <0xDDDD5503>; + }; diff --git a/Documentation/devicetree/bindings/power/reset/qcom,pon.txt b/Documentation/devicetree/bindings/power/reset/qcom,pon.txt index 5705f575862d..0c0dc3a1e693 100644 --- a/Documentation/devicetree/bindings/power/reset/qcom,pon.txt +++ b/Documentation/devicetree/bindings/power/reset/qcom,pon.txt @@ -9,6 +9,7 @@ Required Properties: -compatible: Must be one of: "qcom,pm8916-pon" "qcom,pms405-pon" + "qcom,pm8998-pon" -reg: Specifies the physical address of the pon register diff --git a/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml new file mode 100644 index 000000000000..0ac52f83a58c --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/allwinner,sun4i-a10-pwm.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/allwinner,sun4i-a10-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 PWM Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#pwm-cells": + const: 3 + + compatible: + oneOf: + - const: allwinner,sun4i-a10-pwm + - const: allwinner,sun5i-a10s-pwm + - const: allwinner,sun5i-a13-pwm + - const: allwinner,sun7i-a20-pwm + - const: allwinner,sun8i-h3-pwm + - items: + - const: allwinner,sun8i-a83t-pwm + - const: allwinner,sun8i-h3-pwm + - items: + - const: allwinner,sun50i-a64-pwm + - const: allwinner,sun5i-a13-pwm + - items: + - const: allwinner,sun50i-h5-pwm + - const: allwinner,sun5i-a13-pwm + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - "#pwm-cells" + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + pwm: pwm@1c20e00 { + compatible = "allwinner,sun7i-a20-pwm"; + reg = <0x01c20e00 0xc>; + clocks = <&osc24M>; + #pwm-cells = <3>; + }; + +... diff --git a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt b/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt deleted file mode 100644 index 2a1affbff45e..000000000000 --- a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt +++ /dev/null @@ -1,24 +0,0 @@ -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" - - "allwinner,sun8i-h3-pwm" - - "allwinner,sun50i-a64-pwm", "allwinner,sun5i-a13-pwm" - - "allwinner,sun50i-h5-pwm", "allwinner,sun5i-a13-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 - the cells format. - - clocks: From common clock binding, handle to the parent clock. - -Example: - - pwm: pwm@1c20e00 { - compatible = "allwinner,sun7i-a20-pwm"; - reg = <0x01c20e00 0xc>; - clocks = <&osc24M>; - #pwm-cells = <3>; - }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp-pil.txt b/Documentation/devicetree/bindings/remoteproc/qcom,hexagon-v56.txt index 66af2c30944f..1337a3d93d35 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp-pil.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,hexagon-v56.txt @@ -1,12 +1,13 @@ -Qualcomm Technology Inc. ADSP Peripheral Image Loader +Qualcomm Technology Inc. Hexagon v56 Peripheral Image Loader This document defines the binding for a component that loads and boots firmware -on the Qualcomm Technology Inc. ADSP Hexagon core. +on the Qualcomm Technology Inc. Hexagon v56 core. - compatible: Usage: required Value type: <string> Definition: must be one of: + "qcom,qcs404-cdsp-pil", "qcom,sdm845-adsp-pil" - reg: @@ -28,10 +29,11 @@ on the Qualcomm Technology Inc. ADSP Hexagon core. - clocks: Usage: required Value type: <prop-encoded-array> - Definition: List of 8 phandle and clock specifier pairs for the adsp. + Definition: List of phandles and clock specifier pairs for the Hexagon, + per clock-names below. - clock-names: - Usage: required + Usage: required for SDM845 ADSP Value type: <stringlist> Definition: List of clock input name strings sorted in the same order as the clocks property. Definition must have @@ -39,6 +41,14 @@ on the Qualcomm Technology Inc. ADSP Hexagon core. "lpass_ahbm_aon_cbcr", "qdsp6ss_xo", "qdsp6ss_sleep" and "qdsp6ss_core". +- clock-names: + Usage: required for QCS404 CDSP + Value type: <stringlist> + Definition: List of clock input name strings sorted in the same + order as the clocks property. Definition must have + "xo", "sway", "tbu", "bimc", "ahb_aon", "q6ss_slave", + "q6ss_master", "q6_axim". + - power-domains: Usage: required Value type: <phandle> @@ -47,28 +57,33 @@ on the Qualcomm Technology Inc. ADSP Hexagon core. - resets: Usage: required Value type: <phandle> - Definition: reference to the list of 2 reset-controller for the adsp. + Definition: reference to the list of resets for the Hexagon. - reset-names: - Usage: required + Usage: required for SDM845 ADSP Value type: <stringlist> Definition: must be "pdc_sync" and "cc_lpass" +- reset-names: + Usage: required for QCS404 CDSP + Value type: <stringlist> + Definition: must be "restart" + - qcom,halt-regs: Usage: required Value type: <prop-encoded-array> Definition: a phandle reference to a syscon representing TCSR followed - by the offset within syscon for lpass halt register. + by the offset within syscon for Hexagon halt register. - memory-region: Usage: required Value type: <phandle> - Definition: reference to the reserved-memory for the ADSP + Definition: reference to the reserved-memory for the firmware - qcom,smem-states: Usage: required Value type: <phandle> - Definition: reference to the smem state for requesting the ADSP to + Definition: reference to the smem state for requesting the Hexagon to shut down - qcom,smem-state-names: @@ -79,7 +94,7 @@ on the Qualcomm Technology Inc. ADSP Hexagon core. = SUBNODES The adsp node may have an subnode named "glink-edge" that describes the -communication edge, channels and devices related to the ADSP. +communication edge, channels and devices related to the Hexagon. See ../soc/qcom/qcom,glink.txt for details on how to describe these. = EXAMPLE diff --git a/Documentation/devicetree/bindings/remoteproc/stm32-rproc.txt b/Documentation/devicetree/bindings/remoteproc/stm32-rproc.txt new file mode 100644 index 000000000000..5fa915a4b736 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/stm32-rproc.txt @@ -0,0 +1,63 @@ +STMicroelectronics STM32 Remoteproc +----------------------------------- +This document defines the binding for the remoteproc component that loads and +boots firmwares on the ST32MP family chipset. + +Required properties: +- compatible: Must be "st,stm32mp1-m4" +- reg: Address ranges of the RETRAM and MCU SRAM memories used by the + remote processor. +- resets: Reference to a reset controller asserting the remote processor. +- st,syscfg-holdboot: Reference to the system configuration which holds the + remote processor reset hold boot + 1st cell: phandle of syscon block + 2nd cell: register offset containing the hold boot setting + 3rd cell: register bitmask for the hold boot field +- st,syscfg-tz: Reference to the system configuration which holds the RCC trust + zone mode + 1st cell: phandle to syscon block + 2nd cell: register offset containing the RCC trust zone mode setting + 3rd cell: register bitmask for the RCC trust zone mode bit + +Optional properties: +- interrupts: Should contain the watchdog interrupt +- mboxes: This property is required only if the rpmsg/virtio functionality + is used. List of phandle and mailbox channel specifiers: + - a channel (a) used to communicate through virtqueues with the + remote proc. + Bi-directional channel: + - from local to remote = send message + - from remote to local = send message ack + - a channel (b) working the opposite direction of channel (a) + - a channel (c) used by the local proc to notify the remote proc + that it is about to be shut down. + Unidirectional channel: + - from local to remote, where ACK from the remote means + that it is ready for shutdown +- mbox-names: This property is required if the mboxes property is used. + - must be "vq0" for channel (a) + - must be "vq1" for channel (b) + - must be "shutdown" for channel (c) +- memory-region: List of phandles to the reserved memory regions associated with + the remoteproc device. This is variable and describes the + memories shared with the remote processor (eg: remoteproc + firmware and carveouts, rpmsg vrings, ...). + (see ../reserved-memory/reserved-memory.txt) +- st,syscfg-pdds: Reference to the system configuration which holds the remote + processor deep sleep setting + 1st cell: phandle to syscon block + 2nd cell: register offset containing the deep sleep setting + 3rd cell: register bitmask for the deep sleep bit +- st,auto-boot: If defined, when remoteproc is probed, it loads the default + firmware and starts the remote processor. + +Example: + m4_rproc: m4@10000000 { + compatible = "st,stm32mp1-m4"; + reg = <0x10000000 0x40000>, + <0x30000000 0x40000>, + <0x38000000 0x10000>; + resets = <&rcc MCU_R>; + st,syscfg-holdboot = <&rcc 0x10C 0x1>; + st,syscfg-tz = <&rcc 0x000 0x1>; + }; diff --git a/Documentation/devicetree/bindings/reset/bitmain,bm1880-reset.txt b/Documentation/devicetree/bindings/reset/bitmain,bm1880-reset.txt new file mode 100644 index 000000000000..a6f8455ae6c4 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/bitmain,bm1880-reset.txt @@ -0,0 +1,18 @@ +Bitmain BM1880 SoC Reset Controller +=================================== + +Please also refer to reset.txt in this directory for common reset +controller binding usage. + +Required properties: +- compatible: Should be "bitmain,bm1880-reset" +- reg: Offset and length of reset controller space in SCTRL. +- #reset-cells: Must be 1. + +Example: + + rst: reset-controller@c00 { + compatible = "bitmain,bm1880-reset"; + reg = <0xc00 0x8>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt index 2ecf33815d18..13e095182db4 100644 --- a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt +++ b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt @@ -45,6 +45,6 @@ Example: }; -For list of all valid reset indicies see +For list of all valid reset indices see <dt-bindings/reset/imx7-reset.h> for i.MX7 and <dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml index f97a4ecd7b91..c899111aa5e3 100644 --- a/Documentation/devicetree/bindings/riscv/cpus.yaml +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml @@ -10,97 +10,76 @@ maintainers: - Paul Walmsley <paul.walmsley@sifive.com> - Palmer Dabbelt <palmer@sifive.com> -allOf: - - $ref: /schemas/cpus.yaml# - properties: - $nodename: - const: cpus - description: Container of cpu nodes - - '#address-cells': - const: 1 - description: | - A single unsigned 32-bit integer uniquely identifies each RISC-V - hart in a system. (See the "reg" node under the "cpu" node, - below). - - '#size-cells': - const: 0 + compatible: + items: + - enum: + - sifive,rocket0 + - sifive,e5 + - sifive,e51 + - sifive,u54-mc + - sifive,u54 + - sifive,u5 + - const: riscv + description: + Identifies that the hart uses the RISC-V instruction set + and identifies the type of the hart. + + mmu-type: + allOf: + - $ref: "/schemas/types.yaml#/definitions/string" + - enum: + - riscv,sv32 + - riscv,sv39 + - riscv,sv48 + description: + Identifies the MMU address translation mode used on this + hart. These values originate from the RISC-V Privileged + Specification document, available from + https://riscv.org/specifications/ + + riscv,isa: + allOf: + - $ref: "/schemas/types.yaml#/definitions/string" + - enum: + - rv64imac + - rv64imafdc + description: + Identifies the specific RISC-V instruction set architecture + supported by the hart. These are documented in the RISC-V + User-Level ISA document, available from + https://riscv.org/specifications/ + + timebase-frequency: + type: integer + minimum: 1 + description: + Specifies the clock frequency of the system timer in Hz. + This value is common to all harts on a single system image. + + interrupt-controller: + type: object + description: Describes the CPU's local interrupt controller -patternProperties: - '^cpu@[0-9a-f]+$': properties: - compatible: - type: array - items: - - enum: - - sifive,rocket0 - - sifive,e5 - - sifive,e51 - - sifive,u54-mc - - sifive,u54 - - sifive,u5 - - const: riscv - description: - Identifies that the hart uses the RISC-V instruction set - and identifies the type of the hart. - - mmu-type: - allOf: - - $ref: "/schemas/types.yaml#/definitions/string" - - enum: - - riscv,sv32 - - riscv,sv39 - - riscv,sv48 - description: - Identifies the MMU address translation mode used on this - hart. These values originate from the RISC-V Privileged - Specification document, available from - https://riscv.org/specifications/ - - riscv,isa: - allOf: - - $ref: "/schemas/types.yaml#/definitions/string" - - enum: - - rv64imac - - rv64imafdc - description: - Identifies the specific RISC-V instruction set architecture - supported by the hart. These are documented in the RISC-V - User-Level ISA document, available from - https://riscv.org/specifications/ + '#interrupt-cells': + const: 1 - timebase-frequency: - type: integer - minimum: 1 - description: - Specifies the clock frequency of the system timer in Hz. - This value is common to all harts on a single system image. - - interrupt-controller: - type: object - description: Describes the CPU's local interrupt controller - - properties: - '#interrupt-cells': - const: 1 - - compatible: - const: riscv,cpu-intc - - interrupt-controller: true + compatible: + const: riscv,cpu-intc - required: - - '#interrupt-cells' - - compatible - - interrupt-controller + interrupt-controller: true required: - - riscv,isa - - timebase-frequency + - '#interrupt-cells' + - compatible - interrupt-controller +required: + - riscv,isa + - timebase-frequency + - interrupt-controller + examples: - | // Example 1: SiFive Freedom U540G Development Kit diff --git a/Documentation/devicetree/bindings/rtc/allwinner,sun4i-a10-rtc.yaml b/Documentation/devicetree/bindings/rtc/allwinner,sun4i-a10-rtc.yaml new file mode 100644 index 000000000000..46d69c32b89b --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/allwinner,sun4i-a10-rtc.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/allwinner,sun4i-a10-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 RTC Device Tree Bindings + +allOf: + - $ref: "rtc.yaml#" + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + compatible: + enum: + - allwinner,sun4i-a10-rtc + - allwinner,sun7i-a20-rtc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + rtc: rtc@1c20d00 { + compatible = "allwinner,sun4i-a10-rtc"; + reg = <0x01c20d00 0x20>; + interrupts = <24>; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml new file mode 100644 index 000000000000..924622f39c44 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/allwinner,sun6i-a31-rtc.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/allwinner,sun6i-a31-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A31 RTC Device Tree Bindings + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#clock-cells": + const: 1 + + compatible: + oneOf: + - const: allwinner,sun6i-a31-rtc + - const: allwinner,sun8i-a23-rtc + - const: allwinner,sun8i-h3-rtc + - const: allwinner,sun8i-r40-rtc + - const: allwinner,sun8i-v3-rtc + - const: allwinner,sun50i-h5-rtc + - items: + - const: allwinner,sun50i-a64-rtc + - const: allwinner,sun8i-h3-rtc + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 2 + items: + - description: RTC Alarm 0 + - description: RTC Alarm 1 + + clocks: + maxItems: 1 + + clock-output-names: + minItems: 1 + maxItems: 3 + description: + The RTC provides up to three clocks + - the Low Frequency Oscillator or LOSC, at index 0, + - the Low Frequency Oscillator External output (X32KFOUT in + the datasheet), at index 1, + - the Internal Oscillator, at index 2. + +allOf: + - $ref: "rtc.yaml#" + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-rtc + + then: + properties: + clock-output-names: + minItems: 1 + maxItems: 1 + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-a23-rtc + - allwinner,sun8i-r40-rtc + - allwinner,sun8i-v3-rtc + + then: + properties: + clock-output-names: + minItems: 2 + maxItems: 2 + + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun8i-h3-rtc + - allwinner,sun50i-h5-rtc + + then: + properties: + clock-output-names: + minItems: 3 + maxItems: 3 + + - if: + properties: + compatible: + contains: + const: allwinner,sun8i-r40-rtc + + then: + properties: + interrupts: + minItems: 1 + maxItems: 1 + + else: + properties: + interrupts: + minItems: 2 + maxItems: 2 + +required: + - "#clock-cells" + - compatible + - reg + - interrupts + - clocks + - clock-output-names + +additionalProperties: false + +examples: + - | + rtc: rtc@1f00000 { + compatible = "allwinner,sun6i-a31-rtc"; + reg = <0x01f00000 0x400>; + interrupts = <0 40 4>, <0 41 4>; + clock-output-names = "osc32k"; + clocks = <&ext_osc32k>; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/rtc/rtc.txt b/Documentation/devicetree/bindings/rtc/rtc.txt index a97fc6a9a75e..b8d36fce5e2d 100644 --- a/Documentation/devicetree/bindings/rtc/rtc.txt +++ b/Documentation/devicetree/bindings/rtc/rtc.txt @@ -1,72 +1 @@ -Generic device tree bindings for Real Time Clock devices -======================================================== - -This document describes generic bindings which can be used to describe Real Time -Clock devices in a device tree. - -Required properties -------------------- - -- compatible : name of RTC device following generic names recommended practice. - -For other required properties e.g. to describe register sets, -clocks, etc. check the binding documentation of the specific driver. - -Optional properties -------------------- - -- start-year : if provided, the default hardware range supported by the RTC is - shifted so the first usable year is the specified one. - -The following 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. -- trickle-resistor-ohms : Selected resistor for trickle charger. 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 -- wakeup-source : Enables wake up of host system on alarm -- quartz-load-femtofarads : The capacitive load of the quartz(x-tal), - expressed in femto Farad (fF). - The default value shall be listed (if optional), - and likewise all valid values. - -Trivial RTCs ------------- - -This is a list of trivial RTC devices that have simple device tree -bindings, consisting only of a compatible field, an address and -possibly an interrupt line. - - -Compatible Vendor / Chip -========== ============= -abracon,abb5zes3 AB-RTCMC-32.768kHz-B5ZE-S3: Real Time Clock/Calendar Module with I2C Interface -abracon,abeoz9 AB-RTCMC-32.768kHz-EOZ9: Real Time Clock/Calendar Module with I2C Interface -dallas,ds1374 I2C, 32-Bit Binary Counter Watchdog RTC with Trickle Charger and Reset Input/Output -dallas,ds1672 Dallas DS1672 Real-time Clock -dallas,ds3232 Extremely Accurate I²C RTC with Integrated Crystal and SRAM -epson,rx8010 I2C-BUS INTERFACE REAL TIME CLOCK MODULE -epson,rx8571 I2C-BUS INTERFACE REAL TIME CLOCK MODULE with Battery Backed RAM -epson,rx8581 I2C-BUS INTERFACE REAL TIME CLOCK MODULE -emmicro,em3027 EM Microelectronic EM3027 Real-time Clock -isil,isl1208 Intersil ISL1208 Low Power RTC with Battery Backed SRAM -isil,isl1218 Intersil ISL1218 Low Power RTC with Battery Backed SRAM -isil,isl12022 Intersil ISL12022 Real-time Clock -microcrystal,rv3028 Real Time Clock Module with I2C-Bus -microcrystal,rv3029 Real Time Clock Module with I2C-Bus -microcrystal,rv8523 Real Time Clock -nxp,pcf2127 Real-time clock -nxp,pcf2129 Real-time clock -nxp,pcf8563 Real-time clock/calendar -pericom,pt7c4338 Real-time Clock Module -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 -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 -sii,s35390a 2-wire CMOS real-time clock -whwave,sd3078 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC -xircom,x1205 Xircom X1205 I2C RTC +This file has been moved to rtc.yaml. diff --git a/Documentation/devicetree/bindings/rtc/rtc.yaml b/Documentation/devicetree/bindings/rtc/rtc.yaml new file mode 100644 index 000000000000..ee237b2ed66a --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: RTC Generic Binding + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +description: | + This document describes generic bindings which can be used to + describe Real Time Clock devices in a device tree. + +properties: + $nodename: + pattern: "^rtc(@.*|-[0-9a-f])*$" + + quartz-load-femtofarads: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The capacitive load of the quartz(x-tal), expressed in femto + Farad (fF). The default value shall be listed (if optional), + and likewise all valid values. + + start-year: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + If provided, the default hardware range supported by the RTC is + shifted so the first usable year is the specified one. + + trickle-diode-disable: + $ref: /schemas/types.yaml#/definitions/flag + description: + Do not use internal trickle charger diode. Should be given if + internal trickle charger diode should be disabled. + + trickle-resistor-ohms: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Selected resistor for trickle charger. Should be given + if trickle charger should be enabled. + + wakeup-source: + $ref: /schemas/types.yaml#/definitions/flag + description: + Enables wake up of host system on alarm. + +... diff --git a/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt b/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt deleted file mode 100644 index 6b732c41392b..000000000000 --- a/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt +++ /dev/null @@ -1,46 +0,0 @@ -* sun6i Real Time Clock - -RTC controller for the Allwinner A31 - -Required properties: -- compatible : Should be one of the following combinations: - - "allwinner,sun6i-a31-rtc" - - "allwinner,sun8i-a23-rtc" - - "allwinner,sun8i-h3-rtc" - - "allwinner,sun8i-r40-rtc", "allwinner,sun8i-h3-rtc" - - "allwinner,sun8i-v3-rtc" - - "allwinner,sun50i-a64-rtc", "allwinner,sun8i-h3-rtc" - - "allwinner,sun50i-h5-rtc" - - Where there are two or more compatible strings, this - denotes the hardware covered by the most specific one - is backward-compatible with the latter ones, and the - implementation for the latter ones can be used, albeit - with reduced functionality. - -- reg : physical base address of the controller and length of - memory mapped region. -- interrupts : IRQ lines for the RTC alarm 0 and alarm 1, in that order. - -Required properties for new device trees -- clocks : phandle to the 32kHz external oscillator -- clock-output-names : names of up to three clock outputs. See below. -- #clock-cells : must be equal to 1. - -The RTC provides the following clocks at the given indices: -- 0: LOSC -- 1: LOSC external output, known as X32KFOUT in the datasheet. - This clock is not available on the A31 and is deprecated for old - device trees still using the "allwinner,sun6i-a31-rtc" compatible. -- 2: InternalOSC, or internal RC oscillator (A64/H3/H5 only) - -Example: - -rtc: rtc@1f00000 { - compatible = "allwinner,sun6i-a31-rtc"; - reg = <0x01f00000 0x400>; - interrupts = <0 40 4>, <0 41 4>; - clock-output-names = "osc32k"; - clocks = <&ext_osc32k>; - #clock-cells = <1>; -}; diff --git a/Documentation/devicetree/bindings/rtc/sunxi-rtc.txt b/Documentation/devicetree/bindings/rtc/sunxi-rtc.txt deleted file mode 100644 index 4a8d79c1cf08..000000000000 --- a/Documentation/devicetree/bindings/rtc/sunxi-rtc.txt +++ /dev/null @@ -1,17 +0,0 @@ -* sun4i/sun7i Real Time Clock - -RTC controller for the Allwinner A10/A20 - -Required properties: -- compatible : Should be "allwinner,sun4i-a10-rtc" or "allwinner,sun7i-a20-rtc" -- reg: physical base address of the controller and length of memory mapped - region. -- interrupts: IRQ line for the RTC. - -Example: - -rtc: rtc@1c20d00 { - compatible = "allwinner,sun4i-a10-rtc"; - reg = <0x01c20d00 0x20>; - interrupts = <24>; -}; diff --git a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml new file mode 100644 index 000000000000..0c12ce9a9b45 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/trivial-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Trivial RTCs + +maintainers: + - Alexandre Belloni <alexandre.belloni@bootlin.com> + +description: | + This is a list of trivial RTC devices that have simple device tree + bindings, consisting only of a compatible field, an address and + possibly an interrupt line. + +allOf: + - $ref: "rtc.yaml#" + +properties: + compatible: + enum: + # AB-RTCMC-32.768kHz-B5ZE-S3: Real Time Clock/Calendar Module with I2C Interface + - abracon,abb5zes3 + # AB-RTCMC-32.768kHz-EOZ9: Real Time Clock/Calendar Module with I2C Interface + - abracon,abeoz9 + # I2C, 32-Bit Binary Counter Watchdog RTC with Trickle Charger and Reset Input/Output + - dallas,ds1374 + # Dallas DS1672 Real-time Clock + - dallas,ds1672 + # Extremely Accurate I²C RTC with Integrated Crystal and SRAM + - dallas,ds3232 + # I2C-BUS INTERFACE REAL TIME CLOCK MODULE + - epson,rx8010 + # I2C-BUS INTERFACE REAL TIME CLOCK MODULE with Battery Backed RAM + - epson,rx8571 + # I2C-BUS INTERFACE REAL TIME CLOCK MODULE + - epson,rx8581 + # Intersil ISL1208 Low Power RTC with Battery Backed SRAM + - isil,isl1208 + # Intersil ISL1218 Low Power RTC with Battery Backed SRAM + - isil,isl1218 + # Intersil ISL12022 Real-time Clock + - isil,isl12022 + # Real Time Clock Module with I2C-Bus + - microcrystal,rv3028 + # Real Time Clock Module with I2C-Bus + - microcrystal,rv3029 + # Real Time Clock + - microcrystal,rv8523 + # Real-time clock + - nxp,pcf2127 + # Real-time clock + - nxp,pcf2129 + # Real-time clock/calendar + - nxp,pcf8563 + # Real-time Clock Module + - pericom,pt7c4338 + # I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC + - 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 + - ricoh,rs5c372b + # I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC + - ricoh,rv5c386 + # I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC + - ricoh,rv5c387a + # 2-wire CMOS real-time clock + - sii,s35390a + # I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC + - whwave,sd3078 + # Xircom X1205 I2C RTC + - xircom,x1205 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + start-year: true + +required: + - compatible + - reg + +additionalProperties: false + +... diff --git a/Documentation/devicetree/bindings/serial/omap_serial.txt b/Documentation/devicetree/bindings/serial/omap_serial.txt index 0a9b5444f4e6..dcba86b0a0d0 100644 --- a/Documentation/devicetree/bindings/serial/omap_serial.txt +++ b/Documentation/devicetree/bindings/serial/omap_serial.txt @@ -1,6 +1,7 @@ OMAP UART controller Required properties: +- compatible : should be "ti,j721e-uart", "ti,am654-uart" for J721E controllers - compatible : should be "ti,am654-uart" for AM654 controllers - compatible : should be "ti,omap2-uart" for OMAP2 controllers - compatible : should be "ti,omap3-uart" for OMAP3 controllers diff --git a/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt b/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt index 436d2106e80d..e876f3ce54f6 100644 --- a/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt +++ b/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt @@ -2,8 +2,8 @@ Amlogic Canvas ================================ A canvas is a collection of metadata that describes a pixel buffer. -Those metadata include: width, height, phyaddr, wrapping, block mode -and endianness. +Those metadata include: width, height, phyaddr, wrapping and block mode. +Starting with GXBB the endianness can also be described. Many IPs within Amlogic SoCs rely on canvas indexes to read/write pixel data rather than use the phy addresses directly. For instance, this is the case for @@ -18,7 +18,11 @@ Video Lookup Table -------------------------- Required properties: -- compatible: "amlogic,canvas" +- compatible: has to be one of: + - "amlogic,meson8-canvas", "amlogic,canvas" on Meson8 + - "amlogic,meson8b-canvas", "amlogic,canvas" on Meson8b + - "amlogic,meson8m2-canvas", "amlogic,canvas" on Meson8m2 + - "amlogic,canvas" on GXBB and newer - reg: Base physical address and size of the canvas registers. Example: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt new file mode 100644 index 000000000000..954ffee0a9c4 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt @@ -0,0 +1,81 @@ +Qualcomm Always-On Subsystem side channel binding + +This binding describes the hardware component responsible for side channel +requests to the always-on subsystem (AOSS), used for certain power management +requests that is not handled by the standard RPMh interface. Each client in the +SoC has it's own block of message RAM and IRQ for communication with the AOSS. +The protocol used to communicate in the message RAM is known as Qualcomm +Messaging Protocol (QMP) + +The AOSS side channel exposes control over a set of resources, used to control +a set of debug related clocks and to affect the low power state of resources +related to the secondary subsystems. These resources are exposed as a set of +power-domains. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,sdm845-aoss-qmp" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: the base address and size of the message RAM for this + client's communication with the AOSS + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the AOSS message IRQ for this client + +- mboxes: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to the mailbox representing the outgoing doorbell + in APCS for this client, as described in mailbox/mailbox.txt + +- #clock-cells: + Usage: optional + Value type: <u32> + Definition: must be 0 + The single clock represents the QDSS clock. + +- #power-domain-cells: + Usage: optional + Value type: <u32> + Definition: must be 1 + The provided power-domains are: + CDSP state (0), LPASS state (1), modem state (2), SLPI + state (3), SPSS state (4) and Venus state (5). + += SUBNODES +The AOSS side channel also provides the controls for three cooling devices, +these are expressed as subnodes of the QMP node. The name of the node is used +to identify the resource and must therefor be "cx", "mx" or "ebi". + +- #cooling-cells: + Usage: optional + Value type: <u32> + Definition: must be 2 + += EXAMPLE + +The following example represents the AOSS side-channel message RAM and the +mechanism exposing the power-domains, as found in SDM845. + + aoss_qmp: qmp@c300000 { + compatible = "qcom,sdm845-aoss-qmp"; + reg = <0x0c300000 0x100000>; + interrupts = <GIC_SPI 389 IRQ_TYPE_EDGE_RISING>; + mboxes = <&apss_shared 0>; + + #power-domain-cells = <1>; + + cx_cdev: cx { + #cooling-cells = <2>; + }; + + mx_cdev: mx { + #cooling-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt index bcc612cc7423..db501269f47b 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,apr.txt @@ -9,7 +9,7 @@ used for audio/voice services on the QDSP. Value type: <stringlist> Definition: must be "qcom,apr-v<VERSION-NUMBER>", example "qcom,apr-v2" -- reg +- qcom,apr-domain Usage: required Value type: <u32> Definition: Destination processor ID. @@ -49,9 +49,9 @@ by the individual bindings for the specific service The following example represents a QDSP based sound card on a MSM8996 device which uses apr as communication between Apps and QDSP. - apr@4 { + apr { compatible = "qcom,apr-v2"; - reg = <APR_DOMAIN_ADSP>; + qcom,apr-domain = <APR_DOMAIN_ADSP>; q6core@3 { compatible = "qcom,q6core"; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt index cf759e5f9b10..1214192847ac 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt @@ -21,6 +21,11 @@ edge. Definition: should specify the IRQ used by the remote processor to signal this processor about communication related events +- qcom,remote-pid: + Usage: required for glink-smem + Value type: <u32> + Definition: specifies the identifier of the remote endpoint of this edge + - qcom,rpm-msg-ram: Usage: required for glink-rpm Value type: <prop-encoded-array> diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml index c374fd4923a6..6d1329c28170 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml @@ -50,6 +50,7 @@ properties: patternProperties: "^.*@[0-9a-f]+": + type: object properties: reg: items: diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml index bda7a5befd8b..f36c46d236d7 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml @@ -55,6 +55,7 @@ properties: patternProperties: "^.*@[0-9a-f]+": + type: object properties: reg: items: diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.txt b/Documentation/devicetree/bindings/timer/renesas,cmt.txt index c0594450e9ef..c5220bcd852b 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.txt +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.txt @@ -42,12 +42,18 @@ Required Properties: - "renesas,r8a7793-cmt1" for the 48-bit CMT1 device included in r8a7793. - "renesas,r8a7794-cmt0" for the 32-bit CMT0 device included in r8a7794. - "renesas,r8a7794-cmt1" for the 48-bit CMT1 device included in r8a7794. + - "renesas,r8a7795-cmt0" for the 32-bit CMT0 device included in r8a7795. + - "renesas,r8a7795-cmt1" for the 48-bit CMT1 device included in r8a7795. - "renesas,r8a7796-cmt0" for the 32-bit CMT0 device included in r8a7796. - "renesas,r8a7796-cmt1" for the 48-bit CMT1 device included in r8a7796. + - "renesas,r8a77965-cmt0" for the 32-bit CMT0 device included in r8a77965. + - "renesas,r8a77965-cmt1" for the 48-bit CMT1 device included in r8a77965. - "renesas,r8a77970-cmt0" for the 32-bit CMT0 device included in r8a77970. - "renesas,r8a77970-cmt1" for the 48-bit CMT1 device included in r8a77970. - "renesas,r8a77980-cmt0" for the 32-bit CMT0 device included in r8a77980. - "renesas,r8a77980-cmt1" for the 48-bit CMT1 device included in r8a77980. + - "renesas,r8a77990-cmt0" for the 32-bit CMT0 device included in r8a77990. + - "renesas,r8a77990-cmt1" for the 48-bit CMT1 device included in r8a77990. - "renesas,rcar-gen2-cmt0" for 32-bit CMT0 devices included in R-Car Gen2 and RZ/G1. diff --git a/Documentation/devicetree/bindings/usb/s3c2410-usb.txt b/Documentation/devicetree/bindings/usb/s3c2410-usb.txt index e45b38ce2986..26c85afd0b53 100644 --- a/Documentation/devicetree/bindings/usb/s3c2410-usb.txt +++ b/Documentation/devicetree/bindings/usb/s3c2410-usb.txt @@ -4,7 +4,7 @@ OHCI Required properties: - compatible: should be "samsung,s3c2410-ohci" for USB host controller - - reg: address and lenght of the controller memory mapped region + - reg: address and length of the controller memory mapped region - interrupts: interrupt number for the USB OHCI controller - clocks: Should reference the bus and host clocks - clock-names: Should contain two strings diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 18b79c4cf7d5..6992bbbbffab 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -307,6 +307,8 @@ patternProperties: description: Everest Semiconductor Co. Ltd. "^everspin,.*": description: Everspin Technologies, Inc. + "^evervision,.*": + description: Evervision Electronics Co. Ltd. "^exar,.*": description: Exar Corporation "^excito,.*": @@ -393,12 +395,16 @@ patternProperties: description: Holt Integrated Circuits, Inc. "^honeywell,.*": description: Honeywell + "^hoperun,.*": + description: Jiangsu HopeRun Software Co., Ltd. "^hp,.*": description: Hewlett Packard "^hsg,.*": description: HannStar Display Co. "^holtek,.*": description: Holtek Semiconductor, Inc. + "^hugsun,.*": + description: Shenzhen Hugsun Technology Co. Ltd. "^hwacom,.*": description: HwaCom Systems Inc. "^hyundai,.*": @@ -733,6 +739,8 @@ patternProperties: description: PROBOX2 (by W2COMP Co., Ltd.) "^pulsedlight,.*": description: PulsedLight, Inc + "^purism,.*": + description: Purism, SPC "^qca,.*": description: Qualcomm Atheros, Inc. "^qcom,.*": @@ -911,6 +919,8 @@ patternProperties: description: Shenzhen Techstar Electronics Co., Ltd. "^terasic,.*": description: Terasic Inc. + "^tfc,.*": + description: Three Five Corp "^thine,.*": description: THine Electronics, Inc. "^ti,.*": @@ -987,6 +997,8 @@ patternProperties: description: Voipac Technologies s.r.o. "^vot,.*": description: Vision Optical Technology Co., Ltd. + "^vxt,.*": + description: VXT Ltd "^wd,.*": description: Western Digital Corp. "^wetek,.*": diff --git a/Documentation/devicetree/bindings/virtio/iommu.txt b/Documentation/devicetree/bindings/virtio/iommu.txt new file mode 100644 index 000000000000..2407fea0651c --- /dev/null +++ b/Documentation/devicetree/bindings/virtio/iommu.txt @@ -0,0 +1,66 @@ +* virtio IOMMU PCI device + +When virtio-iommu uses the PCI transport, its programming interface is +discovered dynamically by the PCI probing infrastructure. However the +device tree statically describes the relation between IOMMU and DMA +masters. Therefore, the PCI root complex that hosts the virtio-iommu +contains a child node representing the IOMMU device explicitly. + +Required properties: + +- compatible: Should be "virtio,pci-iommu" +- reg: PCI address of the IOMMU. As defined in the PCI Bus + Binding reference [1], the reg property is a five-cell + address encoded as (phys.hi phys.mid phys.lo size.hi + size.lo). phys.hi should contain the device's BDF as + 0b00000000 bbbbbbbb dddddfff 00000000. The other cells + should be zero. +- #iommu-cells: Each platform DMA master managed by the IOMMU is assigned + an endpoint ID, described by the "iommus" property [2]. + For virtio-iommu, #iommu-cells must be 1. + +Notes: + +- DMA from the IOMMU device isn't managed by another IOMMU. Therefore the + virtio-iommu node doesn't have an "iommus" property, and is omitted from + the iommu-map property of the root complex. + +Example: + +pcie@10000000 { + compatible = "pci-host-ecam-generic"; + ... + + /* The IOMMU programming interface uses slot 00:01.0 */ + iommu0: iommu@0008 { + compatible = "virtio,pci-iommu"; + reg = <0x00000800 0 0 0 0>; + #iommu-cells = <1>; + }; + + /* + * The IOMMU manages all functions in this PCI domain except + * itself. Omit BDF 00:01.0. + */ + iommu-map = <0x0 &iommu0 0x0 0x8> + <0x9 &iommu0 0x9 0xfff7>; +}; + +pcie@20000000 { + compatible = "pci-host-ecam-generic"; + ... + /* + * The IOMMU also manages all functions from this domain, + * with endpoint IDs 0x10000 - 0x1ffff + */ + iommu-map = <0x0 &iommu0 0x10000 0x10000>; +}; + +ethernet@fe001000 { + ... + /* The IOMMU manages this platform device with endpoint ID 0x20000 */ + iommus = <&iommu0 0x20000>; +}; + +[1] Documentation/devicetree/bindings/pci/pci.txt +[2] Documentation/devicetree/bindings/iommu/iommu.txt diff --git a/Documentation/devicetree/bindings/virtio/mmio.txt b/Documentation/devicetree/bindings/virtio/mmio.txt index 5069c1b8e193..21af30fbb81f 100644 --- a/Documentation/devicetree/bindings/virtio/mmio.txt +++ b/Documentation/devicetree/bindings/virtio/mmio.txt @@ -8,10 +8,40 @@ Required properties: - reg: control registers base address and size including configuration space - interrupts: interrupt generated by the device +Required properties for virtio-iommu: + +- #iommu-cells: When the node corresponds to a virtio-iommu device, it is + linked to DMA masters using the "iommus" or "iommu-map" + properties [1][2]. #iommu-cells specifies the size of the + "iommus" property. For virtio-iommu #iommu-cells must be + 1, each cell describing a single endpoint ID. + +Optional properties: + +- iommus: If the device accesses memory through an IOMMU, it should + have an "iommus" property [1]. Since virtio-iommu itself + does not access memory through an IOMMU, the "virtio,mmio" + node cannot have both an "#iommu-cells" and an "iommus" + property. + Example: virtio_block@3000 { compatible = "virtio,mmio"; reg = <0x3000 0x100>; interrupts = <41>; + + /* Device has endpoint ID 23 */ + iommus = <&viommu 23> } + + viommu: iommu@3100 { + compatible = "virtio,mmio"; + reg = <0x3100 0x100>; + interrupts = <42>; + + #iommu-cells = <1> + } + +[1] Documentation/devicetree/bindings/iommu/iommu.txt +[2] Documentation/devicetree/bindings/pci/pci-iommu.txt diff --git a/Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt b/Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt deleted file mode 100644 index 02b87e92ae68..000000000000 --- a/Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt +++ /dev/null @@ -1,24 +0,0 @@ -* Freescale i.MX System Controller Watchdog - -i.MX system controller watchdog is for i.MX SoCs with system controller inside, -the watchdog is managed by system controller, users can ONLY communicate with -system controller from secure mode for watchdog operations, so Linux i.MX system -controller watchdog driver will call ARM SMC API and trap into ARM-Trusted-Firmware -for watchdog operations, ARM-Trusted-Firmware is running at secure EL3 mode and -it will request system controller to execute the watchdog operation passed from -Linux kernel. - -Required properties: -- compatible: Should be : - "fsl,imx8qxp-sc-wdt" - followed by "fsl,imx-sc-wdt"; - -Optional properties: -- timeout-sec : Contains the watchdog timeout in seconds. - -Examples: - -watchdog { - compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt"; - timeout-sec = <60>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt b/Documentation/devicetree/bindings/watchdog/renesas,wdt.txt index 9f365c1a3399..9f365c1a3399 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/renesas,wdt.txt diff --git a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt index 46055254e8dd..e65198d82a2b 100644 --- a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt @@ -6,6 +6,7 @@ Required properties: "allwinner,sun4i-a10-wdt" "allwinner,sun6i-a31-wdt" "allwinner,sun50i-a64-wdt","allwinner,sun6i-a31-wdt" + "allwinner,sun50i-h6-wdt","allwinner,sun6i-a31-wdt" "allwinner,suniv-f1c100s-wdt", "allwinner,sun4i-a10-wdt" - reg : Specifies base physical address and size of the registers. diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 60f8640f2b2f..4660ccee35a3 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -160,7 +160,7 @@ it with special cases. of the kernel image. That entry point supports two calling conventions. A summary of the interface is described here. A full description of the boot requirements is documented in - Documentation/arm/Booting + Documentation/arm/booting.rst a) ATAGS interface. Minimal information is passed from firmware to the kernel with a tagged list of predefined parameters. @@ -174,7 +174,7 @@ it with special cases. b) Entry with a flattened device-tree block. Firmware loads the physical address of the flattened device tree block (dtb) into r2, r1 is not used, but it is considered good practice to use a valid - machine number as described in Documentation/arm/Booting. + machine number as described in Documentation/arm/booting.rst. r0 : 0 diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 5eba889ea84d..9f4392876099 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -30,6 +30,7 @@ *.lzo *.mo *.moc +*.mod *.mod.c *.o *.o.* diff --git a/Documentation/driver-api/backlight/lp855x-driver.rst b/Documentation/driver-api/backlight/lp855x-driver.rst new file mode 100644 index 000000000000..1e0b224fc397 --- /dev/null +++ b/Documentation/driver-api/backlight/lp855x-driver.rst @@ -0,0 +1,81 @@ +==================== +Kernel driver lp855x +==================== + +Backlight driver for LP855x ICs + +Supported chips: + + Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and + LP8557 + +Author: Milo(Woogyom) Kim <milo.kim@ti.com> + +Description +----------- + +* Brightness control + + Brightness can be controlled by the pwm input or the i2c command. + The lp855x driver supports both cases. + +* Device attributes + + 1) bl_ctl_mode + + Backlight control mode. + + Value: pwm based or register based + + 2) chip_id + + The lp855x chip id. + + Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557 + +Platform data for lp855x +------------------------ + +For supporting platform specific data, the lp855x platform data can be used. + +* name: + Backlight driver name. If it is not defined, default name is set. +* device_control: + Value of DEVICE CONTROL register. +* initial_brightness: + Initial value of backlight brightness. +* period_ns: + Platform specific PWM period value. unit is nano. + Only valid when brightness is pwm input mode. +* size_program: + Total size of lp855x_rom_data. +* rom_data: + List of new eeprom/eprom registers. + +Examples +======== + +1) lp8552 platform data: i2c register mode with new eeprom data:: + + #define EEPROM_A5_ADDR 0xA5 + #define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */ + + static struct lp855x_rom_data lp8552_eeprom_arr[] = { + {EEPROM_A5_ADDR, EEPROM_A5_VAL}, + }; + + static struct lp855x_platform_data lp8552_pdata = { + .name = "lcd-bl", + .device_control = I2C_CONFIG(LP8552), + .initial_brightness = INITIAL_BRT, + .size_program = ARRAY_SIZE(lp8552_eeprom_arr), + .rom_data = lp8552_eeprom_arr, + }; + +2) lp8556 platform data: pwm input mode with default rom data:: + + static struct lp855x_platform_data lp8556_pdata = { + .device_control = PWM_CONFIG(LP8556), + .initial_brightness = INITIAL_BRT, + .period_ns = 1000000, + }; diff --git a/Documentation/bt8xxgpio.txt b/Documentation/driver-api/bt8xxgpio.rst index a845feb074de..a845feb074de 100644 --- a/Documentation/bt8xxgpio.txt +++ b/Documentation/driver-api/bt8xxgpio.rst diff --git a/Documentation/connector/connector.txt b/Documentation/driver-api/connector.rst index ab7ca897fab7..c100c7482289 100644 --- a/Documentation/connector/connector.txt +++ b/Documentation/driver-api/connector.rst @@ -1,6 +1,8 @@ -/*****************************************/ -Kernel Connector. -/*****************************************/ +.. SPDX-License-Identifier: GPL-2.0 + +================ +Kernel Connector +================ Kernel connector - new netlink based userspace <-> kernel space easy to use communication module. @@ -12,94 +14,55 @@ identifier, the appropriate callback will be called. From the userspace point of view it's quite straightforward: - socket(); - bind(); - send(); - recv(); + - socket(); + - bind(); + - send(); + - recv(); But if kernelspace wants to use the full power of such connections, the driver writer must create special sockets, must know about struct sk_buff handling, etc... The Connector driver allows any kernelspace agents to use netlink based networking for inter-process communication in a significantly -easier way: +easier way:: -int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); -void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); -void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); + int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); + void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); + void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); -struct cb_id -{ + struct cb_id + { __u32 idx; __u32 val; -}; + }; idx and val are unique identifiers which must be registered in the -connector.h header for in-kernel usage. void (*callback) (void *) is a +connector.h header for in-kernel usage. `void (*callback) (void *)` is a callback function which will be called when a message with above idx.val is received by the connector core. The argument for that function must -be dereferenced to struct cn_msg *. +be dereferenced to `struct cn_msg *`:: -struct cn_msg -{ + struct cn_msg + { struct cb_id id; __u32 seq; __u32 ack; - __u32 len; /* Length of the following data */ + __u32 len; /* Length of the following data */ __u8 data[0]; -}; - -/*****************************************/ -Connector interfaces. -/*****************************************/ - -int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); - - Registers new callback with connector core. - - struct cb_id *id - unique connector's user identifier. - It must be registered in connector.h for legal in-kernel users. - char *name - connector's callback symbolic name. - void (*callback) (struct cn..) - connector's callback. - cn_msg and the sender's credentials - - -void cn_del_callback(struct cb_id *id); - - Unregisters new callback with connector core. - - struct cb_id *id - unique connector's user identifier. - - -int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask); -int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask); + }; - Sends message to the specified groups. It can be safely called from - softirq context, but may silently fail under strong memory pressure. - If there are no listeners for given group -ESRCH can be returned. +Connector interfaces +==================== - struct cn_msg * - message header(with attached data). - u16 len - for *_multi multiple cn_msg messages can be sent - u32 port - destination port. - If non-zero the message will be sent to the - given port, which should be set to the - original sender. - u32 __group - destination group. - If port and __group is zero, then appropriate group will - be searched through all registered connector users, - and message will be delivered to the group which was - created for user with the same ID as in msg. - If __group is not zero, then message will be delivered - to the specified group. - int gfp_mask - GFP mask. + .. kernel-doc:: include/linux/connector.h - Note: When registering new callback user, connector core assigns - netlink group to the user which is equal to its id.idx. + Note: + When registering new callback user, connector core assigns + netlink group to the user which is equal to its id.idx. -/*****************************************/ -Protocol description. -/*****************************************/ +Protocol description +==================== The current framework offers a transport layer with fixed headers. The recommended protocol which uses such a header is as following: @@ -132,9 +95,8 @@ driver (it also registers itself with id={-1, -1}). As example of this usage can be found in the cn_test.c module which uses the connector to request notification and to send messages. -/*****************************************/ -Reliability. -/*****************************************/ +Reliability +=========== Netlink itself is not a reliable protocol. That means that messages can be lost due to memory pressure or process' receiving queue overflowed, @@ -142,32 +104,31 @@ so caller is warned that it must be prepared. That is why the struct cn_msg [main connector's message header] contains u32 seq and u32 ack fields. -/*****************************************/ -Userspace usage. -/*****************************************/ +Userspace usage +=============== 2.6.14 has a new netlink socket implementation, which by default does not allow people to send data to netlink groups other than 1. So, if you wish to use a netlink socket (for example using connector) with a different group number, the userspace application must subscribe to -that group first. It can be achieved by the following pseudocode: +that group first. It can be achieved by the following pseudocode:: -s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); + s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); -l_local.nl_family = AF_NETLINK; -l_local.nl_groups = 12345; -l_local.nl_pid = 0; + l_local.nl_family = AF_NETLINK; + l_local.nl_groups = 12345; + l_local.nl_pid = 0; -if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { + if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { perror("bind"); close(s); return -1; -} + } -{ + { int on = l_local.nl_groups; setsockopt(s, 270, 1, &on, sizeof(on)); -} + } Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket option. To drop a multicast subscription, one should call the above socket @@ -180,16 +141,15 @@ group number 12345, you must increment CN_NETLINK_USERS to that number. Additional 0xf numbers are allocated to be used by non-in-kernel users. Due to this limitation, group 0xffffffff does not work now, so one can -not use add/remove connector's group notifications, but as far as I know, +not use add/remove connector's group notifications, but as far as I know, only cn_test.c test module used it. Some work in netlink area is still being done, so things can be changed in 2.6.15 timeframe, if it will happen, documentation will be updated for that kernel. -/*****************************************/ Code samples -/*****************************************/ +============ Sample code for a connector test module and user space can be found in samples/connector/. To build this code, enable CONFIG_CONNECTOR diff --git a/Documentation/console/console.txt b/Documentation/driver-api/console.rst index d73c2ab4beda..8394ad7747ac 100644 --- a/Documentation/console/console.txt +++ b/Documentation/driver-api/console.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== Console Drivers =============== @@ -17,25 +20,26 @@ of driver occupying the consoles.) They can only take over the console that is occupied by the system driver. In the same token, if the modular driver is released by the console, the system driver will take over. -Modular drivers, from the programmer's point of view, have to call: +Modular drivers, from the programmer's point of view, have to call:: do_take_over_console() - load and bind driver to console layer give_up_console() - unload driver; it will only work if driver is fully unbound -In newer kernels, the following are also available: +In newer kernels, the following are also available:: do_register_con_driver() do_unregister_con_driver() If sysfs is enabled, the contents of /sys/class/vtconsole can be examined. This shows the console backends currently registered by the -system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus: +system which are named vtcon<n> where <n> is an integer from 0 to 15. +Thus:: ls /sys/class/vtconsole . .. vtcon0 vtcon1 -Each directory in /sys/class/vtconsole has 3 files: +Each directory in /sys/class/vtconsole has 3 files:: ls /sys/class/vtconsole/vtcon0 . .. bind name uevent @@ -46,27 +50,29 @@ What do these files signify? read, or acts to bind or unbind the driver to the virtual consoles when written to. The possible values are: - 0 - means the driver is not bound and if echo'ed, commands the driver + 0 + - means the driver is not bound and if echo'ed, commands the driver to unbind - 1 - means the driver is bound and if echo'ed, commands the driver to + 1 + - means the driver is bound and if echo'ed, commands the driver to bind - 2. name - read-only file. Shows the name of the driver in this format: + 2. name - read-only file. Shows the name of the driver in this format:: - cat /sys/class/vtconsole/vtcon0/name - (S) VGA+ + cat /sys/class/vtconsole/vtcon0/name + (S) VGA+ - '(S)' stands for a (S)ystem driver, i.e., it cannot be directly - commanded to bind or unbind + '(S)' stands for a (S)ystem driver, i.e., it cannot be directly + commanded to bind or unbind - 'VGA+' is the name of the driver + 'VGA+' is the name of the driver - cat /sys/class/vtconsole/vtcon1/name - (M) frame buffer device + cat /sys/class/vtconsole/vtcon1/name + (M) frame buffer device - In this case, '(M)' stands for a (M)odular driver, one that can be - directly commanded to bind or unbind. + In this case, '(M)' stands for a (M)odular driver, one that can be + directly commanded to bind or unbind. 3. uevent - ignore this file @@ -75,14 +81,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other hand, will bind the driver to the consoles that are currently occupied by a system driver. -NOTE1: Binding and unbinding must be selected in Kconfig. It's under: +NOTE1: + Binding and unbinding must be selected in Kconfig. It's under:: -Device Drivers -> Character devices -> Support for binding and unbinding -console drivers + Device Drivers -> + Character devices -> + Support for binding and unbinding console drivers -NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or -unbinding will not succeed. An example of an application that sets the console -to KD_GRAPHICS is X. +NOTE2: + If any of the virtual consoles are in KD_GRAPHICS mode, then binding or + unbinding will not succeed. An example of an application that sets the + console to KD_GRAPHICS is X. How useful is this feature? This is very useful for console driver developers. By unbinding the driver from the console layer, one can unload the @@ -92,10 +101,10 @@ framebuffer console to VGA console and vice versa, this feature also makes this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb for more details.) -Notes for developers: -===================== +Notes for developers +==================== -do_take_over_console() is now broken up into: +do_take_over_console() is now broken up into:: do_register_con_driver() do_bind_con_driver() - private function @@ -104,7 +113,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must be fully unbound for this call to succeed. con_is_bound() will check if the driver is bound or not. -Guidelines for console driver writers: +Guidelines for console driver writers ===================================== In order for binding to and unbinding from the console to properly work, @@ -140,6 +149,4 @@ The current crop of console drivers should still work correctly, but binding and unbinding them may cause problems. With minimal fixes, these drivers can be made to work correctly. -========================== Antonino Daplas <adaplas@pol.net> - diff --git a/Documentation/dcdbas.txt b/Documentation/driver-api/dcdbas.rst index 309cc57a7c1c..309cc57a7c1c 100644 --- a/Documentation/dcdbas.txt +++ b/Documentation/driver-api/dcdbas.rst diff --git a/Documentation/dell_rbu.txt b/Documentation/driver-api/dell_rbu.rst index 5d1ce7bcd04d..5d1ce7bcd04d 100644 --- a/Documentation/dell_rbu.txt +++ b/Documentation/driver-api/dell_rbu.rst diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index e78d070bb468..ee268d445d38 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -44,7 +44,8 @@ Example of usage:: dmatest.timeout=2000 dmatest.iterations=1 dmatest.channel=dma0chan0 dmatest.run=1 -Example of multi-channel test usage: +Example of multi-channel test usage (new in the 5.0 kernel):: + % modprobe dmatest % echo 2000 > /sys/module/dmatest/parameters/timeout % echo 1 > /sys/module/dmatest/parameters/iterations @@ -53,15 +54,18 @@ Example of multi-channel test usage: % echo dma0chan2 > /sys/module/dmatest/parameters/channel % echo 1 > /sys/module/dmatest/parameters/run -Note: the channel parameter should always be the last parameter set prior to -running the test (setting run=1), this is because upon setting the channel -parameter, that specific channel is requested using the dmaengine and a thread -is created with the existing parameters. This thread is set as pending -and will be executed once run is set to 1. Any parameters set after the thread -is created are not applied. +.. note:: + For all tests, starting in the 5.0 kernel, either single- or multi-channel, + the channel parameter(s) must be set after all other parameters. It is at + that time that the existing parameter values are acquired for use by the + thread(s). All other parameters are shared. Therefore, if changes are made + to any of the other parameters, and an additional channel specified, the + (shared) parameters used for all threads will use the new values. + After the channels are specified, each thread is set as pending. All threads + begin execution when the run parameter is set to 1. .. hint:: - available channel list could be extracted by running the following command:: + A list of available channels can be found by running the following command:: % ls -1 /sys/class/dma/ @@ -204,6 +208,7 @@ Releasing Channels Channels can be freed by setting run to 0. Example:: + % echo dma0chan1 > /sys/module/dmatest/parameters/channel dmatest: Added 1 threads using dma0chan1 % cat /sys/class/dma/dma0chan1/in_use diff --git a/Documentation/driver-model/binding.rst b/Documentation/driver-api/driver-model/binding.rst index 7ea1d7a41e1d..7ea1d7a41e1d 100644 --- a/Documentation/driver-model/binding.rst +++ b/Documentation/driver-api/driver-model/binding.rst diff --git a/Documentation/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst index 016b15a6e8ea..016b15a6e8ea 100644 --- a/Documentation/driver-model/bus.rst +++ b/Documentation/driver-api/driver-model/bus.rst diff --git a/Documentation/driver-model/class.rst b/Documentation/driver-api/driver-model/class.rst index fff55b80e86a..fff55b80e86a 100644 --- a/Documentation/driver-model/class.rst +++ b/Documentation/driver-api/driver-model/class.rst diff --git a/Documentation/driver-model/design-patterns.rst b/Documentation/driver-api/driver-model/design-patterns.rst index 41eb8f41f7dd..41eb8f41f7dd 100644 --- a/Documentation/driver-model/design-patterns.rst +++ b/Documentation/driver-api/driver-model/design-patterns.rst diff --git a/Documentation/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst index 2b868d49d349..2b868d49d349 100644 --- a/Documentation/driver-model/device.rst +++ b/Documentation/driver-api/driver-model/device.rst diff --git a/Documentation/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 4ac99122b5f1..a100bef54952 100644 --- a/Documentation/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -246,6 +246,10 @@ CLOCK devm_clk_get() devm_clk_get_optional() devm_clk_put() + devm_clk_bulk_get() + devm_clk_bulk_get_all() + devm_clk_bulk_get_optional() + devm_get_clk_from_childl() devm_clk_hw_register() devm_of_clk_add_hw_provider() devm_clk_hw_register_clkdev() diff --git a/Documentation/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst index 11d281506a04..11d281506a04 100644 --- a/Documentation/driver-model/driver.rst +++ b/Documentation/driver-api/driver-model/driver.rst diff --git a/Documentation/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst index 9f85d579ce56..755016422269 100644 --- a/Documentation/driver-model/index.rst +++ b/Documentation/driver-api/driver-model/index.rst @@ -1,5 +1,3 @@ -:orphan: - ============ Driver Model ============ diff --git a/Documentation/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst index d4d1e9b40e0c..d4d1e9b40e0c 100644 --- a/Documentation/driver-model/overview.rst +++ b/Documentation/driver-api/driver-model/overview.rst diff --git a/Documentation/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst index 334dd4071ae4..334dd4071ae4 100644 --- a/Documentation/driver-model/platform.rst +++ b/Documentation/driver-api/driver-model/platform.rst diff --git a/Documentation/driver-model/porting.rst b/Documentation/driver-api/driver-model/porting.rst index ae4bf843c1d6..931ea879af3f 100644 --- a/Documentation/driver-model/porting.rst +++ b/Documentation/driver-api/driver-model/porting.rst @@ -9,7 +9,7 @@ Patrick Mochel Overview -Please refer to `Documentation/driver-model/*.rst` for definitions of +Please refer to `Documentation/driver-api/driver-model/*.rst` for definitions of various driver types and concepts. Most of the work of porting devices drivers to the new model happens diff --git a/Documentation/early-userspace/buffer-format.txt b/Documentation/driver-api/early-userspace/buffer-format.rst index e1fd7f9dad16..7f74e301fdf3 100644 --- a/Documentation/early-userspace/buffer-format.txt +++ b/Documentation/driver-api/early-userspace/buffer-format.rst @@ -1,8 +1,10 @@ - initramfs buffer format - ----------------------- +======================= +initramfs buffer format +======================= - Al Viro, H. Peter Anvin - Last revision: 2002-01-13 +Al Viro, H. Peter Anvin + +Last revision: 2002-01-13 Starting with kernel 2.5.x, the old "initial ramdisk" protocol is getting {replaced/complemented} with the new "initial ramfs" @@ -18,7 +20,8 @@ archive can be compressed using gzip(1). One valid version of an initramfs buffer is thus a single .cpio.gz file. The full format of the initramfs buffer is defined by the following -grammar, where: +grammar, where:: + * is used to indicate "0 or more occurrences of" (|) indicates alternatives + indicates concatenation @@ -49,7 +52,9 @@ hexadecimal ASCII numbers fully padded with '0' on the left to the full width of the field, for example, the integer 4780 is represented by the ASCII string "000012ac"): +============= ================== ============================================== Field name Field size Meaning +============= ================== ============================================== c_magic 6 bytes The string "070701" or "070702" c_ino 8 bytes File inode number c_mode 8 bytes File mode and permissions @@ -65,6 +70,7 @@ c_rmin 8 bytes Minor part of device node reference c_namesize 8 bytes Length of filename, including final \0 c_chksum 8 bytes Checksum of data field if c_magic is 070702; otherwise zero +============= ================== ============================================== The c_mode field matches the contents of st_mode returned by stat(2) on Linux, and encodes the file type and file permissions. @@ -82,7 +88,8 @@ If the filename is "TRAILER!!!" this is actually an end-of-archive marker; the c_filesize for an end-of-archive marker must be zero. -*** Handling of hard links +Handling of hard links +====================== When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino) tuple is looked up in a tuple buffer. If not found, it is entered in diff --git a/Documentation/early-userspace/README b/Documentation/driver-api/early-userspace/early_userspace_support.rst index 955d667dc87e..3deefb34046b 100644 --- a/Documentation/early-userspace/README +++ b/Documentation/driver-api/early-userspace/early_userspace_support.rst @@ -1,3 +1,4 @@ +======================= Early userspace support ======================= @@ -26,6 +27,7 @@ archive to be used as the image or have the kernel build process build the image from specifications. CPIO ARCHIVE method +------------------- You can create a cpio archive that contains the early userspace image. Your cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it @@ -34,6 +36,7 @@ CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in combination with a cpio archive. IMAGE BUILDING method +--------------------- The kernel build process can also build an early userspace image from source parts rather than supplying a cpio archive. This method provides diff --git a/Documentation/driver-api/early-userspace/index.rst b/Documentation/driver-api/early-userspace/index.rst new file mode 100644 index 000000000000..149c1822f06d --- /dev/null +++ b/Documentation/driver-api/early-userspace/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +Early Userspace +=============== + +.. toctree:: + :maxdepth: 1 + + early_userspace_support + buffer-format + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/EDID/howto.rst b/Documentation/driver-api/edid.rst index 725fd49a88ca..b1b5acd501ed 100644 --- a/Documentation/EDID/howto.rst +++ b/Documentation/driver-api/edid.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ==== EDID diff --git a/Documentation/eisa.txt b/Documentation/driver-api/eisa.rst index f388545a85a7..c07565ba57da 100644 --- a/Documentation/eisa.txt +++ b/Documentation/driver-api/eisa.rst @@ -103,7 +103,7 @@ id_table an array of NULL terminated EISA id strings, (driver_data). driver a generic driver, such as described in - Documentation/driver-model/driver.rst. Only .name, + Documentation/driver-api/driver-model/driver.rst. Only .name, .probe and .remove members are mandatory. =============== ==================================================== @@ -152,7 +152,7 @@ state set of flags indicating the state of the device. Current flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED. res set of four 256 bytes I/O regions allocated to this device dma_mask DMA mask set from the parent device. -dev generic device (see Documentation/driver-model/device.rst) +dev generic device (see Documentation/driver-api/driver-model/device.rst) ======== ============================================================ You can get the 'struct eisa_device' from 'struct device' using the diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 349f2dc33029..921c71a3d683 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -399,7 +399,7 @@ symbol: will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks need to embed the gpio_chip in its state container and obtain a pointer to the container using container_of(). - (See Documentation/driver-model/design-patterns.rst) + (See Documentation/driver-api/driver-model/design-patterns.rst) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, as discussed above regarding different types of cascaded irqchips. The diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 0dbaa987aa11..d12a80f386a6 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -14,8 +14,10 @@ available subsections can be seen below. .. toctree:: :maxdepth: 2 + driver-model/index basics infrastructure + early-userspace/index pm/index clk device-io @@ -34,7 +36,9 @@ available subsections can be seen below. pci/index spi i2c + ipmb i3c/index + interconnect hsi edac scsi @@ -43,8 +47,11 @@ available subsections can be seen below. mtdnand miscellaneous mei/index + mtd/index + mmc/index + nvdimm/index w1 - rapidio + rapidio/index s390-drivers vme 80211/index @@ -52,13 +59,48 @@ available subsections can be seen below. firmware/index pinctl gpio/index + md/index misc_devices + nfc/index dmaengine/index slimbus soundwire/index fpga/index acpi/index + backlight/lp855x-driver.rst + bt8xxgpio + connector + console + dcdbas + dell_rbu + edid + eisa + isa + isapnp generic-counter + lightnvm-pblk + memory-devices/index + men-chameleon-bus + ntb + nvmem + parport-lowlevel + pps + ptp + phy/index + pti_intel_mid + pwm + rfkill + serial/index + sgi-ioc4 + sm501 + smsc_ece1099 + switchtec + sync_file + vfio-mediated-device + vfio + xilinx/index + xillybus + zorro .. only:: subproject and html diff --git a/Documentation/interconnect/interconnect.rst b/Documentation/driver-api/interconnect.rst index 56e331dab70e..c3e004893796 100644 --- a/Documentation/interconnect/interconnect.rst +++ b/Documentation/driver-api/interconnect.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -:orphan: - ===================================== GENERIC SYSTEM INTERCONNECT SUBSYSTEM ===================================== diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst new file mode 100644 index 000000000000..7e2265144157 --- /dev/null +++ b/Documentation/driver-api/ipmb.rst @@ -0,0 +1,105 @@ +============================== +IPMB Driver for a Satellite MC +============================== + +The Intelligent Platform Management Bus or IPMB, is an +I2C bus that provides a standardized interconnection between +different boards within a chassis. This interconnection is +between the baseboard management (BMC) and chassis electronics. +IPMB is also associated with the messaging protocol through the +IPMB bus. + +The devices using the IPMB are usually management +controllers that perform management functions such as servicing +the front panel interface, monitoring the baseboard, +hot-swapping disk drivers in the system chassis, etc... + +When an IPMB is implemented in the system, the BMC serves as +a controller to give system software access to the IPMB. The BMC +sends IPMI requests to a device (usually a Satellite Management +Controller or Satellite MC) via IPMB and the device +sends a response back to the BMC. + +For more information on IPMB and the format of an IPMB message, +refer to the IPMB and IPMI specifications. + +IPMB driver for Satellite MC +---------------------------- + +ipmb-dev-int - This is the driver needed on a Satellite MC to +receive IPMB messages from a BMC and send a response back. +This driver works with the I2C driver and a userspace +program such as OpenIPMI: + +1) It is an I2C slave backend driver. So, it defines a callback + function to set the Satellite MC as an I2C slave. + This callback function handles the received IPMI requests. + +2) It defines the read and write functions to enable a user + space program (such as OpenIPMI) to communicate with the kernel. + + +Load the IPMB driver +-------------------- + +The driver needs to be loaded at boot time or manually first. +First, make sure you have the following in your config file: +CONFIG_IPMB_DEVICE_INTERFACE=y + +1) If you want the driver to be loaded at boot time: + +a) Add this entry to your ACPI table, under the appropriate SMBus:: + + Device (SMB0) // Example SMBus host controller + { + Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID + Name (_UID, 0) // Unique ID of particular host controller + : + : + Device (IPMB) + { + Name (_HID, "IPMB0001") // IPMB device interface + Name (_UID, 0) // Unique device identifier + } + } + +b) Example for device tree:: + + &i2c2 { + status = "okay"; + + ipmb@10 { + compatible = "ipmb-dev"; + reg = <0x10>; + }; + }; + +2) Manually from Linux:: + + modprobe ipmb-dev-int + + +Instantiate the device +---------------------- + +After loading the driver, you can instantiate the device as +described in 'Documentation/i2c/instantiating-devices'. +If you have multiple BMCs, each connected to your Satellite MC via +a different I2C bus, you can instantiate a device for each of +those BMCs. + +The name of the instantiated device contains the I2C bus number +associated with it as follows:: + + BMC1 ------ IPMB/I2C bus 1 ---------| /dev/ipmb-1 + Satellite MC + BMC1 ------ IPMB/I2C bus 2 ---------| /dev/ipmb-2 + +For instance, you can instantiate the ipmb-dev-int device from +user space at the 7 bit address 0x10 on bus 2:: + + # echo ipmb-dev 0x1010 > /sys/bus/i2c/devices/i2c-2/new_device + +This will create the device file /dev/ipmb-2, which can be accessed +by the user space program. The device needs to be instantiated +before running the user space program. diff --git a/Documentation/isa.txt b/Documentation/driver-api/isa.rst index def4a7b690b5..def4a7b690b5 100644 --- a/Documentation/isa.txt +++ b/Documentation/driver-api/isa.rst diff --git a/Documentation/isapnp.txt b/Documentation/driver-api/isapnp.rst index 8d0840ac847b..8d0840ac847b 100644 --- a/Documentation/isapnp.txt +++ b/Documentation/driver-api/isapnp.rst diff --git a/Documentation/lightnvm/pblk.txt b/Documentation/driver-api/lightnvm-pblk.rst index 1040ed1cec81..1040ed1cec81 100644 --- a/Documentation/lightnvm/pblk.txt +++ b/Documentation/driver-api/lightnvm-pblk.rst diff --git a/Documentation/driver-api/md/index.rst b/Documentation/driver-api/md/index.rst new file mode 100644 index 000000000000..18f54a7d7d6e --- /dev/null +++ b/Documentation/driver-api/md/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +RAID +==== + +.. toctree:: + :maxdepth: 1 + + md-cluster + raid5-cache + raid5-ppl diff --git a/Documentation/md/md-cluster.txt b/Documentation/driver-api/md/md-cluster.rst index e1055f105cf5..96eb52cec7eb 100644 --- a/Documentation/md/md-cluster.txt +++ b/Documentation/driver-api/md/md-cluster.rst @@ -1,19 +1,24 @@ +========== +MD Cluster +========== + The cluster MD is a shared-device RAID for a cluster, it supports two levels: raid1 and raid10 (limited support). 1. On-disk format +================= 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: +and may not yet have finished. The on-disk layout is:: -0 4k 8k 12k -------------------------------------------------------------------- -| idle | md super | bm super [0] + bits | -| bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] | -| bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits | -| bm bits [3, contd] | | | + 0 4k 8k 12k + ------------------------------------------------------------------- + | idle | md super | bm super [0] + bits | + | bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] | + | 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 @@ -28,10 +33,12 @@ node) is writing. 2. DLM Locks for management +=========================== 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 bitmap000 for node 1, bitmap001 for node 2 and so on. When a @@ -48,6 +55,7 @@ There are three groups of locks for managing the device: 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 @@ -55,116 +63,155 @@ There are three groups of locks for managing the device: 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 +================ 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 six types of messages which are passed: - 3.1.1 METADATA_UPDATED: informs other nodes that the metadata has +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 RESYNCING: informs other nodes that a resync is initiated or +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 overrides any previous 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 +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 +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 + 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 + 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 - communicate. +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 receiving node that a node wants to communicate. The algorithm is: - 1. receive status - all nodes have concurrent-reader lock on "ack". + 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 on "token", + sender get EX on "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 + sender receiver receiver + "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. - 3. sender writes LVB. + 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 on "message" - receiver read LVB - receiver processes the message - [ wait finish ] - receiver releases "ack" - receiver tries to get PR on "message" + :: + + [ wait until all receivers have *processed* the "message" ] - sender receiver receiver - "token":EX "message":CR "message":CR - "message":CW - "ack":EX + [ triggered by bast of "ack" ] + receiver get CR on "message" + receiver read LVB + receiver processes the message + [ wait finish ] + 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 + :: + + receiver upconvert to PR on "message" + receiver get CR of "ack" + receiver release "message" + + sender receiver receiver + "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 number. The node starts a cluster recovery thread. The cluster @@ -177,11 +224,11 @@ 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. + 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 environment when a resync is performed, it needs to tell other nodes @@ -198,6 +245,7 @@ The algorithm is: particular I/O range should be suspended or not. 4.2 Device Failure +================== Device failures are handled and communicated with the metadata update routine. When a node detects a device failure it does not allow @@ -205,38 +253,41 @@ The algorithm is: 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: - 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues + 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues 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 + 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 + 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 + 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-dev" - 8. If node 1 gets the lock, it sends METADATA_UPDATED after + 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 + 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. +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 @@ -244,11 +295,13 @@ The algorithm is: 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 @@ -256,6 +309,7 @@ The algorithm is: 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 @@ -265,8 +319,8 @@ The algorithm is: 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(). +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 @@ -275,6 +329,7 @@ The algorithm is: can be used to release the lock. 6.6 area_resyncing() +-------------------- This combines two elements of functionality. @@ -289,6 +344,7 @@ The algorithm is: 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 @@ -300,17 +356,20 @@ The algorithm is: 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 @@ -319,6 +378,7 @@ The algorithm is: accordingly. 7. Unsupported features +======================= There are somethings which are not supported by cluster MD yet. diff --git a/Documentation/md/raid5-cache.txt b/Documentation/driver-api/md/raid5-cache.rst index 2b210f295786..d7a15f44a7c3 100644 --- a/Documentation/md/raid5-cache.txt +++ b/Documentation/driver-api/md/raid5-cache.rst @@ -1,4 +1,6 @@ -RAID5 cache +================ +RAID 4/5/6 cache +================ Raid 4/5/6 could include an extra disk for data cache besides normal RAID disks. The role of RAID disks isn't changed with the cache disk. The cache disk @@ -6,19 +8,19 @@ caches data to the RAID disks. The cache can be in write-through (supported since 4.4) or write-back mode (supported since 4.10). mdadm (supported since 3.4) has a new option '--write-journal' to create array with cache. Please refer to mdadm manual for details. By default (RAID array starts), the cache is -in write-through mode. A user can switch it to write-back mode by: +in write-through mode. A user can switch it to write-back mode by:: -echo "write-back" > /sys/block/md0/md/journal_mode + echo "write-back" > /sys/block/md0/md/journal_mode -And switch it back to write-through mode by: +And switch it back to write-through mode by:: -echo "write-through" > /sys/block/md0/md/journal_mode + echo "write-through" > /sys/block/md0/md/journal_mode In both modes, all writes to the array will hit cache disk first. This means the cache disk must be fast and sustainable. -------------------------------------- -write-through mode: +write-through mode +================== This mode mainly fixes the 'write hole' issue. For RAID 4/5/6 array, an unclean shutdown can cause data in some stripes to not be in consistent state, eg, data @@ -42,8 +44,8 @@ exposed to 'write hole' again. In write-through mode, the cache disk isn't required to be big. Several hundreds megabytes are enough. --------------------------------------- -write-back mode: +write-back mode +=============== write-back mode fixes the 'write hole' issue too, since all write data is cached on cache disk. But the main goal of 'write-back' cache is to speed up @@ -64,16 +66,16 @@ data loss. In write-back mode, MD also caches data in memory. The memory cache includes the same data stored on cache disk, so a power loss doesn't cause data loss. The memory cache size has performance impact for the array. It's recommended -the size is big. A user can configure the size by: +the size is big. A user can configure the size by:: -echo "2048" > /sys/block/md0/md/stripe_cache_size + echo "2048" > /sys/block/md0/md/stripe_cache_size Too small cache disk will make the write aggregation less efficient in this mode depending on the workloads. It's recommended to use a cache disk with at least several gigabytes size in write-back mode. --------------------------------------- -The implementation: +The implementation +================== The write-through and write-back cache use the same disk format. The cache disk is organized as a simple write log. The log consists of 'meta data' and 'data' diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/driver-api/md/raid5-ppl.rst index bfa092589e00..357e5515bc55 100644 --- a/Documentation/md/raid5-ppl.txt +++ b/Documentation/driver-api/md/raid5-ppl.rst @@ -1,4 +1,6 @@ +================== Partial Parity Log +================== Partial Parity Log (PPL) is a feature available for RAID5 arrays. The issue addressed by PPL is that after a dirty shutdown, parity of a particular stripe diff --git a/Documentation/driver-api/memory-devices/index.rst b/Documentation/driver-api/memory-devices/index.rst new file mode 100644 index 000000000000..28101458cda5 --- /dev/null +++ b/Documentation/driver-api/memory-devices/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Memory Controller drivers +========================= + +.. toctree:: + :maxdepth: 1 + + ti-emif + ti-gpmc + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/memory-devices/ti-emif.txt b/Documentation/driver-api/memory-devices/ti-emif.rst index f4ad9a7d0f4b..dea2ad9bcd7e 100644 --- a/Documentation/memory-devices/ti-emif.txt +++ b/Documentation/driver-api/memory-devices/ti-emif.rst @@ -1,20 +1,24 @@ -TI EMIF SDRAM Controller Driver: +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +TI EMIF SDRAM Controller Driver +=============================== Author -======== +====== Aneesh V <aneesh@ti.com> Location -============ +======== driver/memory/emif.c Supported SoCs: -=================== +=============== TI OMAP44xx TI OMAP54xx Menuconfig option: -========================== +================== Device Drivers Memory devices Texas Instruments EMIF driver @@ -29,10 +33,11 @@ functions of the driver includes re-configuring AC timing parameters and other settings during frequency, voltage and temperature changes -Platform Data (see include/linux/platform_data/emif_plat.h): -===================================================================== +Platform Data (see include/linux/platform_data/emif_plat.h) +=========================================================== DDR device details and other board dependent and SoC dependent information can be passed through platform data (struct emif_platform_data) + - DDR device details: 'struct ddr_device_info' - Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck' - Custom configurations: customizable policy options through @@ -40,17 +45,19 @@ information can be passed through platform data (struct emif_platform_data) - IP revision - PHY type -Interface to the external world: -================================ +Interface to the external world +=============================== EMIF driver registers notifiers for voltage and frequency changes affecting EMIF and takes appropriate actions when these are invoked. + - freq_pre_notify_handling() - freq_post_notify_handling() - volt_notify_handling() Debugfs -======== +======= The driver creates two debugfs entries per device. + - regcache_dump : dump of register values calculated and saved for all frequencies used so far. - mr4 : last polled value of MR4 register in the LPDDR2 device. MR4 diff --git a/Documentation/bus-devices/ti-gpmc.txt b/Documentation/driver-api/memory-devices/ti-gpmc.rst index cc9ce57e0a26..33efcb81f080 100644 --- a/Documentation/bus-devices/ti-gpmc.txt +++ b/Documentation/driver-api/memory-devices/ti-gpmc.rst @@ -1,8 +1,12 @@ -GPMC (General Purpose Memory Controller): -========================================= +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +GPMC (General Purpose Memory Controller) +======================================== GPMC is an unified memory controller dedicated to interfacing external memory devices like + * Asynchronous SRAM like memories and application specific integrated circuit devices. * Asynchronous, synchronous, and page mode burst NOR flash devices @@ -48,75 +52,128 @@ most of the datasheets & hardware (to be exact none of those supported in mainline having custom timing routine) and by simulation. gpmc timing dependency on peripheral timings: + [<gpmc_timing>: <peripheral timing1>, <peripheral timing2> ...] 1. common -cs_on: t_ceasu -adv_on: t_avdasu, t_ceavd + +cs_on: + t_ceasu +adv_on: + t_avdasu, t_ceavd 2. sync common -sync_clk: clk -page_burst_access: t_bacc -clk_activation: t_ces, t_avds + +sync_clk: + clk +page_burst_access: + t_bacc +clk_activation: + t_ces, t_avds 3. read async muxed -adv_rd_off: t_avdp_r -oe_on: t_oeasu, t_aavdh -access: t_iaa, t_oe, t_ce, t_aa -rd_cycle: t_rd_cycle, t_cez_r, t_oez + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu, t_aavdh +access: + t_iaa, t_oe, t_ce, t_aa +rd_cycle: + t_rd_cycle, t_cez_r, t_oez 4. read async non-muxed -adv_rd_off: t_avdp_r -oe_on: t_oeasu -access: t_iaa, t_oe, t_ce, t_aa -rd_cycle: t_rd_cycle, t_cez_r, t_oez + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu +access: + t_iaa, t_oe, t_ce, t_aa +rd_cycle: + t_rd_cycle, t_cez_r, t_oez 5. read sync muxed -adv_rd_off: t_avdp_r, t_avdh -oe_on: t_oeasu, t_ach, cyc_aavdh_oe -access: t_iaa, cyc_iaa, cyc_oe -rd_cycle: t_cez_r, t_oez, t_ce_rdyz + +adv_rd_off: + t_avdp_r, t_avdh +oe_on: + t_oeasu, t_ach, cyc_aavdh_oe +access: + t_iaa, cyc_iaa, cyc_oe +rd_cycle: + t_cez_r, t_oez, t_ce_rdyz 6. read sync non-muxed -adv_rd_off: t_avdp_r -oe_on: t_oeasu -access: t_iaa, cyc_iaa, cyc_oe -rd_cycle: t_cez_r, t_oez, t_ce_rdyz + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu +access: + t_iaa, cyc_iaa, cyc_oe +rd_cycle: + t_cez_r, t_oez, t_ce_rdyz 7. write async muxed -adv_wr_off: t_avdp_w -we_on, wr_data_mux_bus: t_weasu, t_aavdh, cyc_aavhd_we -we_off: t_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_wr_cycle + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu, t_aavdh, cyc_aavhd_we +we_off: + t_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_wr_cycle 8. write async non-muxed -adv_wr_off: t_avdp_w -we_on, wr_data_mux_bus: t_weasu -we_off: t_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_wr_cycle + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu +we_off: + t_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_wr_cycle 9. write sync muxed -adv_wr_off: t_avdp_w, t_avdh -we_on, wr_data_mux_bus: t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we -we_off: t_wpl, cyc_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_ce_rdyz + +adv_wr_off: + t_avdp_w, t_avdh +we_on, wr_data_mux_bus: + t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we +we_off: + t_wpl, cyc_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_ce_rdyz 10. write sync non-muxed -adv_wr_off: t_avdp_w -we_on, wr_data_mux_bus: t_weasu, t_rdyo -we_off: t_wpl, cyc_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_ce_rdyz - - -Note: Many of gpmc timings are dependent on other gpmc timings (a few -gpmc timings purely dependent on other gpmc timings, a reason that -some of the gpmc timings are missing above), and it will result in -indirect dependency of peripheral timings to gpmc timings other than -mentioned above, refer timing routine for more details. To know what -these peripheral timings correspond to, please see explanations in -struct gpmc_device_timings definition. And for gpmc timings refer -IP details (link above). + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu, t_rdyo +we_off: + t_wpl, cyc_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_ce_rdyz + + +Note: + Many of gpmc timings are dependent on other gpmc timings (a few + gpmc timings purely dependent on other gpmc timings, a reason that + some of the gpmc timings are missing above), and it will result in + indirect dependency of peripheral timings to gpmc timings other than + mentioned above, refer timing routine for more details. To know what + these peripheral timings correspond to, please see explanations in + struct gpmc_device_timings definition. And for gpmc timings refer + IP details (link above). diff --git a/Documentation/men-chameleon-bus.txt b/Documentation/driver-api/men-chameleon-bus.rst index 1b1f048aa748..1b1f048aa748 100644 --- a/Documentation/men-chameleon-bus.txt +++ b/Documentation/driver-api/men-chameleon-bus.rst diff --git a/Documentation/driver-api/mmc/index.rst b/Documentation/driver-api/mmc/index.rst new file mode 100644 index 000000000000..7339736ac774 --- /dev/null +++ b/Documentation/driver-api/mmc/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +MMC/SD/SDIO card support +======================== + +.. toctree:: + :maxdepth: 1 + + mmc-dev-attrs + mmc-dev-parts + mmc-async-req + mmc-tools diff --git a/Documentation/mmc/mmc-async-req.txt b/Documentation/driver-api/mmc/mmc-async-req.rst index ae1907b10e4a..0f7197c9c3b5 100644 --- a/Documentation/mmc/mmc-async-req.txt +++ b/Documentation/driver-api/mmc/mmc-async-req.rst @@ -1,13 +1,20 @@ +======================== +MMC Asynchronous Request +======================== + Rationale ========= How significant is the cache maintenance overhead? + It depends. Fast eMMC and multiple cache levels with speculative cache pre-fetch makes the cache overhead relatively significant. If the DMA preparations for the next request are done in parallel with the current transfer, the DMA preparation overhead would not affect the MMC performance. + The intention of non-blocking (asynchronous) MMC requests is to minimize the time between when an MMC request ends and another MMC request begins. + Using mmc_wait_for_req(), the MMC controller is idle while dma_map_sg and dma_unmap_sg are processing. Using non-blocking MMC requests makes it possible to prepare the caches for next job in parallel with an active @@ -17,6 +24,7 @@ MMC block driver ================ The mmc_blk_issue_rw_rq() in the MMC block driver is made non-blocking. + The increase in throughput is proportional to the time it takes to prepare (major part of preparations are dma_map_sg() and dma_unmap_sg()) a request and how fast the memory is. The faster the MMC/SD is the @@ -35,6 +43,7 @@ MMC core API extension ====================== There is one new public function mmc_start_req(). + It starts a new MMC command request for a host. The function isn't truly non-blocking. If there is an ongoing async request it waits for completion of that request and starts the new one and returns. It @@ -47,6 +56,7 @@ MMC host extensions There are two optional members in the mmc_host_ops -- pre_req() and post_req() -- that the host driver may implement in order to move work to before and after the actual mmc_host_ops.request() function is called. + In the DMA case pre_req() may do dma_map_sg() and prepare the DMA descriptor, and post_req() runs the dma_unmap_sg(). @@ -55,33 +65,34 @@ Optimize for the first request The first request in a series of requests can't be prepared in parallel with the previous transfer, since there is no previous request. + The argument is_first_req in pre_req() indicates that there is no previous request. The host driver may optimize for this scenario to minimize the performance loss. A way to optimize for this is to split the current request in two chunks, prepare the first chunk and start the request, and finally prepare the second chunk and start the transfer. -Pseudocode to handle is_first_req scenario with minimal prepare overhead: - -if (is_first_req && req->size > threshold) - /* start MMC transfer for the complete transfer size */ - mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE); - - /* - * Begin to prepare DMA while cmd is being processed by MMC. - * The first chunk of the request should take the same time - * to prepare as the "MMC process command time". - * If prepare time exceeds MMC cmd time - * the transfer is delayed, guesstimate max 4k as first chunk size. - */ - prepare_1st_chunk_for_dma(req); - /* flush pending desc to the DMAC (dmaengine.h) */ - dma_issue_pending(req->dma_desc); - - prepare_2nd_chunk_for_dma(req); - /* - * The second issue_pending should be called before MMC runs out - * of the first chunk. If the MMC runs out of the first data chunk - * before this call, the transfer is delayed. - */ - dma_issue_pending(req->dma_desc); +Pseudocode to handle is_first_req scenario with minimal prepare overhead:: + + if (is_first_req && req->size > threshold) + /* start MMC transfer for the complete transfer size */ + mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE); + + /* + * Begin to prepare DMA while cmd is being processed by MMC. + * The first chunk of the request should take the same time + * to prepare as the "MMC process command time". + * If prepare time exceeds MMC cmd time + * the transfer is delayed, guesstimate max 4k as first chunk size. + */ + prepare_1st_chunk_for_dma(req); + /* flush pending desc to the DMAC (dmaengine.h) */ + dma_issue_pending(req->dma_desc); + + prepare_2nd_chunk_for_dma(req); + /* + * The second issue_pending should be called before MMC runs out + * of the first chunk. If the MMC runs out of the first data chunk + * before this call, the transfer is delayed. + */ + dma_issue_pending(req->dma_desc); diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/driver-api/mmc/mmc-dev-attrs.rst index 4ad0bb17f343..4f44b1b730d6 100644 --- a/Documentation/mmc/mmc-dev-attrs.txt +++ b/Documentation/driver-api/mmc/mmc-dev-attrs.rst @@ -1,3 +1,4 @@ +================================== SD and MMC Block Device Attributes ================================== @@ -6,23 +7,29 @@ SD or MMC device. The following attributes are read/write. - force_ro Enforce read-only access even if write protect switch is off. + ======== =============================================== + force_ro Enforce read-only access even if write protect switch is off. + ======== =============================================== SD and MMC Device Attributes ============================ All attributes are read-only. + ====================== =============================================== cid Card Identification Register csd Card Specific Data Register scr SD Card Configuration Register (SD only) date Manufacturing Date (from CID Register) - fwrev Firmware/Product Revision (from CID Register) (SD and MMCv1 only) - hwrev Hardware/Product Revision (from CID Register) (SD and MMCv1 only) + fwrev Firmware/Product Revision (from CID Register) + (SD and MMCv1 only) + hwrev Hardware/Product Revision (from CID Register) + (SD and MMCv1 only) manfid Manufacturer ID (from CID Register) name Product Name (from CID Register) oemid OEM/Application ID (from CID Register) - prv Product Revision (from CID Register) (SD and MMCv4 only) + prv Product Revision (from CID Register) + (SD and MMCv4 only) serial Product Serial Number (from CID Register) erase_size Erase group size preferred_erase_size Preferred erase size @@ -30,7 +37,10 @@ All attributes are read-only. rel_sectors Reliable write sector count ocr Operation Conditions Register dsr Driver Stage Register - cmdq_en Command Queue enabled: 1 => enabled, 0 => not enabled + cmdq_en Command Queue enabled: + + 1 => enabled, 0 => not enabled + ====================== =============================================== Note on Erase Size and Preferred Erase Size: @@ -44,14 +54,15 @@ Note on Erase Size and Preferred Erase Size: SD/MMC cards can erase an arbitrarily large area up to and including the whole card. When erasing a large area it may be desirable to do it in smaller chunks for three reasons: - 1. A single erase command will make all other I/O on + + 1. A single erase command will make all other I/O on the card wait. This is not a problem if the whole card is being erased, but erasing one partition will make I/O for another partition on the same card wait for the duration of the erase - which could be a several minutes. - 2. To be able to inform the user of erase progress. - 3. The erase timeout becomes too large to be very + 2. To be able to inform the user of erase progress. + 3. The erase timeout becomes too large to be very useful. Because the erase timeout contains a margin which is multiplied by the size of the erase area, the value can end up being several minutes for large @@ -72,6 +83,9 @@ Note on Erase Size and Preferred Erase Size: "preferred_erase_size" is in bytes. Note on raw_rpmb_size_mult: + "raw_rpmb_size_mult" is a multiple of 128kB block. + RPMB size in byte is calculated by using the following equation: - RPMB partition size = 128kB x raw_rpmb_size_mult + + RPMB partition size = 128kB x raw_rpmb_size_mult diff --git a/Documentation/mmc/mmc-dev-parts.txt b/Documentation/driver-api/mmc/mmc-dev-parts.rst index f08d078d43cf..995922f1f744 100644 --- a/Documentation/mmc/mmc-dev-parts.txt +++ b/Documentation/driver-api/mmc/mmc-dev-parts.rst @@ -1,3 +1,4 @@ +============================ SD and MMC Device Partitions ============================ @@ -18,18 +19,18 @@ platform, write access is disabled by default to reduce the chance of accidental bricking. To enable write access to /dev/mmcblkXbootY, disable the forced read-only -access with: +access with:: -echo 0 > /sys/block/mmcblkXbootY/force_ro + echo 0 > /sys/block/mmcblkXbootY/force_ro -To re-enable read-only access: +To re-enable read-only access:: -echo 1 > /sys/block/mmcblkXbootY/force_ro + echo 1 > /sys/block/mmcblkXbootY/force_ro The boot partitions can also be locked read only until the next power on, -with: +with:: -echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on + echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on This is a feature of the card and not of the kernel. If the card does not support boot partition locking, the file will not exist. If the diff --git a/Documentation/mmc/mmc-tools.txt b/Documentation/driver-api/mmc/mmc-tools.rst index 735509c165d5..54406093768b 100644 --- a/Documentation/mmc/mmc-tools.txt +++ b/Documentation/driver-api/mmc/mmc-tools.rst @@ -1,14 +1,17 @@ +====================== MMC tools introduction ====================== There is one MMC test tools called mmc-utils, which is maintained by Chris Ball, you can find it at the below public git repository: -http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ + + http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ Functions ========= The mmc-utils tools can do the following: + - Print and parse extcsd data. - Determine the eMMC writeprotect status. - Set the eMMC writeprotect status. diff --git a/Documentation/driver-api/mtd/index.rst b/Documentation/driver-api/mtd/index.rst new file mode 100644 index 000000000000..436ba5a851d7 --- /dev/null +++ b/Documentation/driver-api/mtd/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Memory Technology Device (MTD) +============================== + +.. toctree:: + :maxdepth: 1 + + intel-spi + nand_ecc + spi-nor diff --git a/Documentation/mtd/intel-spi.txt b/Documentation/driver-api/mtd/intel-spi.rst index bc357729c2cb..0e6d9cd5388d 100644 --- a/Documentation/mtd/intel-spi.txt +++ b/Documentation/driver-api/mtd/intel-spi.rst @@ -1,5 +1,6 @@ +============================== Upgrading BIOS using intel-spi ------------------------------- +============================== Many Intel CPUs like Baytrail and Braswell include SPI serial flash host controller which is used to hold BIOS and other platform specific data. @@ -36,45 +37,45 @@ Linux. module parameter to modprobe). 4) Once the board is up and running again, find the right MTD partition - (it is named as "BIOS"): + (it is named as "BIOS"):: - # cat /proc/mtd - dev: size erasesize name - mtd0: 00800000 00001000 "BIOS" + # cat /proc/mtd + dev: size erasesize name + mtd0: 00800000 00001000 "BIOS" So here it will be /dev/mtd0 but it may vary. - 5) Make backup of the existing image first: + 5) Make backup of the existing image first:: - # dd if=/dev/mtd0ro of=bios.bak - 16384+0 records in - 16384+0 records out - 8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s + # dd if=/dev/mtd0ro of=bios.bak + 16384+0 records in + 16384+0 records out + 8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s - 6) Verify the backup + 6) Verify the backup: - # sha1sum /dev/mtd0ro bios.bak - fdbb011920572ca6c991377c4b418a0502668b73 /dev/mtd0ro - fdbb011920572ca6c991377c4b418a0502668b73 bios.bak + # sha1sum /dev/mtd0ro bios.bak + fdbb011920572ca6c991377c4b418a0502668b73 /dev/mtd0ro + fdbb011920572ca6c991377c4b418a0502668b73 bios.bak The SHA1 sums must match. Otherwise do not continue any further! 7) Erase the SPI serial flash. After this step, do not reboot the - board! Otherwise it will not start anymore. + board! Otherwise it will not start anymore:: - # flash_erase /dev/mtd0 0 0 - Erasing 4 Kibyte @ 7ff000 -- 100 % complete + # flash_erase /dev/mtd0 0 0 + Erasing 4 Kibyte @ 7ff000 -- 100 % complete 8) Once completed without errors you can write the new BIOS image: # dd if=MNW2MAX1.X64.0092.R01.1605221712.bin of=/dev/mtd0 9) Verify that the new content of the SPI serial flash matches the new - BIOS image: + BIOS image:: - # sha1sum /dev/mtd0ro MNW2MAX1.X64.0092.R01.1605221712.bin - 9b4df9e4be2057fceec3a5529ec3d950836c87a2 /dev/mtd0ro - 9b4df9e4be2057fceec3a5529ec3d950836c87a2 MNW2MAX1.X64.0092.R01.1605221712.bin + # sha1sum /dev/mtd0ro MNW2MAX1.X64.0092.R01.1605221712.bin + 9b4df9e4be2057fceec3a5529ec3d950836c87a2 /dev/mtd0ro + 9b4df9e4be2057fceec3a5529ec3d950836c87a2 MNW2MAX1.X64.0092.R01.1605221712.bin The SHA1 sums should match. @@ -84,5 +85,6 @@ Linux. References ---------- -[1] https://firmware.intel.com/sites/default/files/MinnowBoard.MAX_.X64.92.R01.zip +[1] https://firmware.intel.com/sites/default/files/MinnowBoard%2EMAX_%2EX64%2E92%2ER01%2Ezip + [2] http://www.linux-mtd.infradead.org/ diff --git a/Documentation/mtd/nand_ecc.txt b/Documentation/driver-api/mtd/nand_ecc.rst index f8c3284bf6a7..e8d3c53a5056 100644 --- a/Documentation/mtd/nand_ecc.txt +++ b/Documentation/driver-api/mtd/nand_ecc.rst @@ -1,3 +1,7 @@ +========================== +NAND Error-correction Code +========================== + Introduction ============ @@ -37,63 +41,79 @@ sometimes also referred to as xor. In C the operator for xor is ^ Back to ecc. Let's give a small figure: +========= ==== ==== ==== ==== ==== ==== ==== ==== === === === === ==== byte 0: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp2 rp4 ... rp14 byte 1: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp2 rp4 ... rp14 byte 2: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp3 rp4 ... rp14 byte 3: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp3 rp4 ... rp14 byte 4: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp2 rp5 ... rp14 -.... +... byte 254: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp0 rp3 rp5 ... rp15 byte 255: bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0 rp1 rp3 rp5 ... rp15 cp1 cp0 cp1 cp0 cp1 cp0 cp1 cp0 cp3 cp3 cp2 cp2 cp3 cp3 cp2 cp2 cp5 cp5 cp5 cp5 cp4 cp4 cp4 cp4 +========= ==== ==== ==== ==== ==== ==== ==== ==== === === === === ==== This figure represents a sector of 256 bytes. cp is my abbreviation for column parity, rp for row parity. Let's start to explain column parity. -cp0 is the parity that belongs to all bit0, bit2, bit4, bit6. -so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even. + +- cp0 is the parity that belongs to all bit0, bit2, bit4, bit6. + + so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even. + Similarly cp1 is the sum of all bit1, bit3, bit5 and bit7. -cp2 is the parity over bit0, bit1, bit4 and bit5 -cp3 is the parity over bit2, bit3, bit6 and bit7. -cp4 is the parity over bit0, bit1, bit2 and bit3. -cp5 is the parity over bit4, bit5, bit6 and bit7. + +- cp2 is the parity over bit0, bit1, bit4 and bit5 +- cp3 is the parity over bit2, bit3, bit6 and bit7. +- cp4 is the parity over bit0, bit1, bit2 and bit3. +- cp5 is the parity over bit4, bit5, bit6 and bit7. + Note that each of cp0 .. cp5 is exactly one bit. Row parity actually works almost the same. -rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254) -rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255) -rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ... -(so handle two bytes, then skip 2 bytes). -rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...) -for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc. -so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...) -and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, .. + +- rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254) +- rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255) +- rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ... + (so handle two bytes, then skip 2 bytes). +- rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...) +- for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc. + + so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...) +- and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, .. + The story now becomes quite boring. I guess you get the idea. -rp6 covers 8 bytes then skips 8 etc -rp7 skips 8 bytes then covers 8 etc -rp8 covers 16 bytes then skips 16 etc -rp9 skips 16 bytes then covers 16 etc -rp10 covers 32 bytes then skips 32 etc -rp11 skips 32 bytes then covers 32 etc -rp12 covers 64 bytes then skips 64 etc -rp13 skips 64 bytes then covers 64 etc -rp14 covers 128 bytes then skips 128 -rp15 skips 128 bytes then covers 128 + +- rp6 covers 8 bytes then skips 8 etc +- rp7 skips 8 bytes then covers 8 etc +- rp8 covers 16 bytes then skips 16 etc +- rp9 skips 16 bytes then covers 16 etc +- rp10 covers 32 bytes then skips 32 etc +- rp11 skips 32 bytes then covers 32 etc +- rp12 covers 64 bytes then skips 64 etc +- rp13 skips 64 bytes then covers 64 etc +- rp14 covers 128 bytes then skips 128 +- rp15 skips 128 bytes then covers 128 In the end the parity bits are grouped together in three bytes as follows: + +===== ===== ===== ===== ===== ===== ===== ===== ===== ECC Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 +===== ===== ===== ===== ===== ===== ===== ===== ===== ECC 0 rp07 rp06 rp05 rp04 rp03 rp02 rp01 rp00 ECC 1 rp15 rp14 rp13 rp12 rp11 rp10 rp09 rp08 ECC 2 cp5 cp4 cp3 cp2 cp1 cp0 1 1 +===== ===== ===== ===== ===== ===== ===== ===== ===== I detected after writing this that ST application note AN1823 (http://www.st.com/stonline/) gives a much nicer picture.(but they use line parity as term where I use row parity) Oh well, I'm graphically challenged, so suffer with me for a moment :-) + And I could not reuse the ST picture anyway for copyright reasons. @@ -101,9 +121,10 @@ Attempt 0 ========= Implementing the parity calculation is pretty simple. -In C pseudocode: -for (i = 0; i < 256; i++) -{ +In C pseudocode:: + + for (i = 0; i < 256; i++) + { if (i & 0x01) rp1 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp1; else @@ -142,7 +163,7 @@ for (i = 0; i < 256; i++) cp3 = bit7 ^ bit6 ^ bit3 ^ bit2 ^ cp3 cp4 = bit3 ^ bit2 ^ bit1 ^ bit0 ^ cp4 cp5 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ cp5 -} + } Analysis 0 @@ -167,82 +188,84 @@ This leads to: Attempt 1 ========= -const char parity[256] = { - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, - 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0 -}; - -void ecc1(const unsigned char *buf, unsigned char *code) -{ - int i; - const unsigned char *bp = buf; - unsigned char cur; - unsigned char rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7; - unsigned char rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15; - unsigned char par; - - par = 0; - rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0; - rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0; - rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0; - rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0; - - for (i = 0; i < 256; i++) - { - cur = *bp++; - par ^= cur; - if (i & 0x01) rp1 ^= cur; else rp0 ^= cur; - if (i & 0x02) rp3 ^= cur; else rp2 ^= cur; - if (i & 0x04) rp5 ^= cur; else rp4 ^= cur; - if (i & 0x08) rp7 ^= cur; else rp6 ^= cur; - if (i & 0x10) rp9 ^= cur; else rp8 ^= cur; - if (i & 0x20) rp11 ^= cur; else rp10 ^= cur; - if (i & 0x40) rp13 ^= cur; else rp12 ^= cur; - if (i & 0x80) rp15 ^= cur; else rp14 ^= cur; - } - code[0] = - (parity[rp7] << 7) | - (parity[rp6] << 6) | - (parity[rp5] << 5) | - (parity[rp4] << 4) | - (parity[rp3] << 3) | - (parity[rp2] << 2) | - (parity[rp1] << 1) | - (parity[rp0]); - code[1] = - (parity[rp15] << 7) | - (parity[rp14] << 6) | - (parity[rp13] << 5) | - (parity[rp12] << 4) | - (parity[rp11] << 3) | - (parity[rp10] << 2) | - (parity[rp9] << 1) | - (parity[rp8]); - code[2] = - (parity[par & 0xf0] << 7) | - (parity[par & 0x0f] << 6) | - (parity[par & 0xcc] << 5) | - (parity[par & 0x33] << 4) | - (parity[par & 0xaa] << 3) | - (parity[par & 0x55] << 2); - code[0] = ~code[0]; - code[1] = ~code[1]; - code[2] = ~code[2]; -} +:: + + const char parity[256] = { + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1, + 0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0 + }; + + void ecc1(const unsigned char *buf, unsigned char *code) + { + int i; + const unsigned char *bp = buf; + unsigned char cur; + unsigned char rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7; + unsigned char rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15; + unsigned char par; + + par = 0; + rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0; + rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0; + rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0; + rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0; + + for (i = 0; i < 256; i++) + { + cur = *bp++; + par ^= cur; + if (i & 0x01) rp1 ^= cur; else rp0 ^= cur; + if (i & 0x02) rp3 ^= cur; else rp2 ^= cur; + if (i & 0x04) rp5 ^= cur; else rp4 ^= cur; + if (i & 0x08) rp7 ^= cur; else rp6 ^= cur; + if (i & 0x10) rp9 ^= cur; else rp8 ^= cur; + if (i & 0x20) rp11 ^= cur; else rp10 ^= cur; + if (i & 0x40) rp13 ^= cur; else rp12 ^= cur; + if (i & 0x80) rp15 ^= cur; else rp14 ^= cur; + } + code[0] = + (parity[rp7] << 7) | + (parity[rp6] << 6) | + (parity[rp5] << 5) | + (parity[rp4] << 4) | + (parity[rp3] << 3) | + (parity[rp2] << 2) | + (parity[rp1] << 1) | + (parity[rp0]); + code[1] = + (parity[rp15] << 7) | + (parity[rp14] << 6) | + (parity[rp13] << 5) | + (parity[rp12] << 4) | + (parity[rp11] << 3) | + (parity[rp10] << 2) | + (parity[rp9] << 1) | + (parity[rp8]); + code[2] = + (parity[par & 0xf0] << 7) | + (parity[par & 0x0f] << 6) | + (parity[par & 0xcc] << 5) | + (parity[par & 0x33] << 4) | + (parity[par & 0xaa] << 3) | + (parity[par & 0x55] << 2); + code[0] = ~code[0]; + code[1] = ~code[1]; + code[2] = ~code[2]; + } Still pretty straightforward. The last three invert statements are there to give a checksum of 0xff 0xff 0xff for an empty flash. In an empty flash @@ -293,88 +316,90 @@ Let's give it a try... Attempt 2 ========= -extern const char parity[256]; - -void ecc2(const unsigned char *buf, unsigned char *code) -{ - int i; - const unsigned long *bp = (unsigned long *)buf; - unsigned long cur; - unsigned long rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7; - unsigned long rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15; - unsigned long par; - - par = 0; - rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0; - rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0; - rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0; - rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0; - - for (i = 0; i < 64; i++) - { - cur = *bp++; - par ^= cur; - if (i & 0x01) rp5 ^= cur; else rp4 ^= cur; - if (i & 0x02) rp7 ^= cur; else rp6 ^= cur; - if (i & 0x04) rp9 ^= cur; else rp8 ^= cur; - if (i & 0x08) rp11 ^= cur; else rp10 ^= cur; - if (i & 0x10) rp13 ^= cur; else rp12 ^= cur; - if (i & 0x20) rp15 ^= cur; else rp14 ^= cur; - } - /* - we need to adapt the code generation for the fact that rp vars are now - long; also the column parity calculation needs to be changed. - we'll bring rp4 to 15 back to single byte entities by shifting and - xoring - */ - rp4 ^= (rp4 >> 16); rp4 ^= (rp4 >> 8); rp4 &= 0xff; - rp5 ^= (rp5 >> 16); rp5 ^= (rp5 >> 8); rp5 &= 0xff; - rp6 ^= (rp6 >> 16); rp6 ^= (rp6 >> 8); rp6 &= 0xff; - rp7 ^= (rp7 >> 16); rp7 ^= (rp7 >> 8); rp7 &= 0xff; - rp8 ^= (rp8 >> 16); rp8 ^= (rp8 >> 8); rp8 &= 0xff; - rp9 ^= (rp9 >> 16); rp9 ^= (rp9 >> 8); rp9 &= 0xff; - rp10 ^= (rp10 >> 16); rp10 ^= (rp10 >> 8); rp10 &= 0xff; - rp11 ^= (rp11 >> 16); rp11 ^= (rp11 >> 8); rp11 &= 0xff; - rp12 ^= (rp12 >> 16); rp12 ^= (rp12 >> 8); rp12 &= 0xff; - rp13 ^= (rp13 >> 16); rp13 ^= (rp13 >> 8); rp13 &= 0xff; - rp14 ^= (rp14 >> 16); rp14 ^= (rp14 >> 8); rp14 &= 0xff; - rp15 ^= (rp15 >> 16); rp15 ^= (rp15 >> 8); rp15 &= 0xff; - rp3 = (par >> 16); rp3 ^= (rp3 >> 8); rp3 &= 0xff; - rp2 = par & 0xffff; rp2 ^= (rp2 >> 8); rp2 &= 0xff; - par ^= (par >> 16); - rp1 = (par >> 8); rp1 &= 0xff; - rp0 = (par & 0xff); - par ^= (par >> 8); par &= 0xff; - - code[0] = - (parity[rp7] << 7) | - (parity[rp6] << 6) | - (parity[rp5] << 5) | - (parity[rp4] << 4) | - (parity[rp3] << 3) | - (parity[rp2] << 2) | - (parity[rp1] << 1) | - (parity[rp0]); - code[1] = - (parity[rp15] << 7) | - (parity[rp14] << 6) | - (parity[rp13] << 5) | - (parity[rp12] << 4) | - (parity[rp11] << 3) | - (parity[rp10] << 2) | - (parity[rp9] << 1) | - (parity[rp8]); - code[2] = - (parity[par & 0xf0] << 7) | - (parity[par & 0x0f] << 6) | - (parity[par & 0xcc] << 5) | - (parity[par & 0x33] << 4) | - (parity[par & 0xaa] << 3) | - (parity[par & 0x55] << 2); - code[0] = ~code[0]; - code[1] = ~code[1]; - code[2] = ~code[2]; -} +:: + + extern const char parity[256]; + + void ecc2(const unsigned char *buf, unsigned char *code) + { + int i; + const unsigned long *bp = (unsigned long *)buf; + unsigned long cur; + unsigned long rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7; + unsigned long rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15; + unsigned long par; + + par = 0; + rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0; + rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0; + rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0; + rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0; + + for (i = 0; i < 64; i++) + { + cur = *bp++; + par ^= cur; + if (i & 0x01) rp5 ^= cur; else rp4 ^= cur; + if (i & 0x02) rp7 ^= cur; else rp6 ^= cur; + if (i & 0x04) rp9 ^= cur; else rp8 ^= cur; + if (i & 0x08) rp11 ^= cur; else rp10 ^= cur; + if (i & 0x10) rp13 ^= cur; else rp12 ^= cur; + if (i & 0x20) rp15 ^= cur; else rp14 ^= cur; + } + /* + we need to adapt the code generation for the fact that rp vars are now + long; also the column parity calculation needs to be changed. + we'll bring rp4 to 15 back to single byte entities by shifting and + xoring + */ + rp4 ^= (rp4 >> 16); rp4 ^= (rp4 >> 8); rp4 &= 0xff; + rp5 ^= (rp5 >> 16); rp5 ^= (rp5 >> 8); rp5 &= 0xff; + rp6 ^= (rp6 >> 16); rp6 ^= (rp6 >> 8); rp6 &= 0xff; + rp7 ^= (rp7 >> 16); rp7 ^= (rp7 >> 8); rp7 &= 0xff; + rp8 ^= (rp8 >> 16); rp8 ^= (rp8 >> 8); rp8 &= 0xff; + rp9 ^= (rp9 >> 16); rp9 ^= (rp9 >> 8); rp9 &= 0xff; + rp10 ^= (rp10 >> 16); rp10 ^= (rp10 >> 8); rp10 &= 0xff; + rp11 ^= (rp11 >> 16); rp11 ^= (rp11 >> 8); rp11 &= 0xff; + rp12 ^= (rp12 >> 16); rp12 ^= (rp12 >> 8); rp12 &= 0xff; + rp13 ^= (rp13 >> 16); rp13 ^= (rp13 >> 8); rp13 &= 0xff; + rp14 ^= (rp14 >> 16); rp14 ^= (rp14 >> 8); rp14 &= 0xff; + rp15 ^= (rp15 >> 16); rp15 ^= (rp15 >> 8); rp15 &= 0xff; + rp3 = (par >> 16); rp3 ^= (rp3 >> 8); rp3 &= 0xff; + rp2 = par & 0xffff; rp2 ^= (rp2 >> 8); rp2 &= 0xff; + par ^= (par >> 16); + rp1 = (par >> 8); rp1 &= 0xff; + rp0 = (par & 0xff); + par ^= (par >> 8); par &= 0xff; + + code[0] = + (parity[rp7] << 7) | + (parity[rp6] << 6) | + (parity[rp5] << 5) | + (parity[rp4] << 4) | + (parity[rp3] << 3) | + (parity[rp2] << 2) | + (parity[rp1] << 1) | + (parity[rp0]); + code[1] = + (parity[rp15] << 7) | + (parity[rp14] << 6) | + (parity[rp13] << 5) | + (parity[rp12] << 4) | + (parity[rp11] << 3) | + (parity[rp10] << 2) | + (parity[rp9] << 1) | + (parity[rp8]); + code[2] = + (parity[par & 0xf0] << 7) | + (parity[par & 0x0f] << 6) | + (parity[par & 0xcc] << 5) | + (parity[par & 0x33] << 4) | + (parity[par & 0xaa] << 3) | + (parity[par & 0x55] << 2); + code[0] = ~code[0]; + code[1] = ~code[1]; + code[2] = ~code[2]; + } The parity array is not shown any more. Note also that for these examples I kinda deviated from my regular programming style by allowing @@ -403,28 +428,32 @@ lookups Attempt 3 ========= -Odd replaced: - if (i & 0x01) rp5 ^= cur; else rp4 ^= cur; - if (i & 0x02) rp7 ^= cur; else rp6 ^= cur; - if (i & 0x04) rp9 ^= cur; else rp8 ^= cur; - if (i & 0x08) rp11 ^= cur; else rp10 ^= cur; - if (i & 0x10) rp13 ^= cur; else rp12 ^= cur; - if (i & 0x20) rp15 ^= cur; else rp14 ^= cur; -with - if (i & 0x01) rp5 ^= cur; - if (i & 0x02) rp7 ^= cur; - if (i & 0x04) rp9 ^= cur; - if (i & 0x08) rp11 ^= cur; - if (i & 0x10) rp13 ^= cur; - 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; +Odd replaced:: + + if (i & 0x01) rp5 ^= cur; else rp4 ^= cur; + if (i & 0x02) rp7 ^= cur; else rp6 ^= cur; + if (i & 0x04) rp9 ^= cur; else rp8 ^= cur; + if (i & 0x08) rp11 ^= cur; else rp10 ^= cur; + if (i & 0x10) rp13 ^= cur; else rp12 ^= cur; + if (i & 0x20) rp15 ^= cur; else rp14 ^= cur; + +with:: + + if (i & 0x01) rp5 ^= cur; + if (i & 0x02) rp7 ^= cur; + if (i & 0x04) rp9 ^= cur; + if (i & 0x08) rp11 ^= cur; + if (i & 0x10) rp13 ^= cur; + 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; 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. @@ -448,7 +477,7 @@ Attempt 4 ========= Unrolled the loop 1, 2, 3 and 4 times. -For 4 the code starts with: +For 4 the code starts with:: for (i = 0; i < 4; i++) { @@ -471,8 +500,11 @@ Analysis 4 ========== Unrolling once gains about 15% + Unrolling twice keeps the gain at about 15% + Unrolling three times gives a gain of 30% compared to attempt 2. + Unrolling four times gives a marginal improvement compared to unrolling three times. @@ -492,8 +524,10 @@ Attempt 5 Effectively so all odd digit rp assignments in the loop were removed. This included the else clause of the if statements. -Of course after the loop we need to correct things by adding code like: +Of course after the loop we need to correct things by adding code like:: + rp5 = par ^ rp4; + Also the initial assignments (rp5 = 0; etc) could be removed. Along the line I also removed the initialisation of rp0/1/2/3. @@ -513,7 +547,7 @@ statement. Time for yet another version! Attempt 6 ========= -THe code within the for loop was changed to: +THe code within the for loop was changed to:: for (i = 0; i < 4; i++) { @@ -564,13 +598,17 @@ million iterations in order not to lose too much accuracy. This one definitely seemed to be the jackpot! There is a little bit more room for improvement though. There are three -places with statements: -rp4 ^= cur; rp6 ^= cur; +places with statements:: + + rp4 ^= cur; rp6 ^= cur; + It seems more efficient to also maintain a variable rp4_6 in the while loop; This eliminates 3 statements per loop. Of course after the loop we -need to correct by adding: - rp4 ^= rp4_6; - rp6 ^= rp4_6 +need to correct by adding:: + + rp4 ^= rp4_6; + rp6 ^= rp4_6 + Furthermore there are 4 sequential assignments to rp8. This can be encoded slightly more efficiently by saving tmppar before those 4 lines and later do rp8 = rp8 ^ tmppar ^ notrp8; @@ -582,7 +620,7 @@ Time for a new test! Attempt 7 ========= -The new code now looks like: +The new code now looks like:: for (i = 0; i < 4; i++) { @@ -644,9 +682,12 @@ Although it seems that the code within the loop cannot be optimised further there is still room to optimize the generation of the ecc codes. We can simply calculate the total parity. If this is 0 then rp4 = rp5 etc. If the parity is 1, then rp4 = !rp5; + But if rp4 = rp5 we do not need rp5 etc. We can just write the even bits -in the result byte and then do something like +in the result byte and then do something like:: + code[0] |= (code[0] << 1); + Lets test this. @@ -657,11 +698,13 @@ Changed the code but again this slightly degrades performance. Tried all kind of other things, like having dedicated parity arrays to avoid the shift after parity[rp7] << 7; No gain. Change the lookup using the parity array by using shift operators (e.g. -replace parity[rp7] << 7 with: -rp7 ^= (rp7 << 4); -rp7 ^= (rp7 << 2); -rp7 ^= (rp7 << 1); -rp7 &= 0x80; +replace parity[rp7] << 7 with:: + + rp7 ^= (rp7 << 4); + rp7 ^= (rp7 << 2); + rp7 ^= (rp7 << 1); + rp7 &= 0x80; + No gain. The only marginal change was inverting the parity bits, so we can remove @@ -683,13 +726,16 @@ Correcting errors For correcting errors I again used the ST application note as a starter, but I also peeked at the existing code. + The algorithm itself is pretty straightforward. Just xor the given and the calculated ecc. If all bytes are 0 there is no problem. If 11 bits are 1 we have one correctable bit error. If there is 1 bit 1, we have an error in the given ecc code. + It proved to be fastest to do some table lookups. Performance gain introduced by this is about a factor 2 on my system when a repair had to be done, and 1% or so if no repair had to be done. + Code size increased from 330 bytes to 686 bytes for this function. (gcc 4.2, -O3) @@ -700,8 +746,10 @@ 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 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. @@ -711,4 +759,5 @@ out of it with an assembler program, but due to pipeline behaviour etc this is very tricky (at least for intel hw). Author: Frans Meulenbroeks + Copyright (C) 2008 Koninklijke Philips Electronics NV. diff --git a/Documentation/mtd/spi-nor.txt b/Documentation/driver-api/mtd/spi-nor.rst index da1fbff5a24c..f5333e3bf486 100644 --- a/Documentation/mtd/spi-nor.txt +++ b/Documentation/driver-api/mtd/spi-nor.rst @@ -1,5 +1,6 @@ - SPI NOR framework - ============================================ +================= +SPI NOR framework +================= Part I - Why do we need this framework? --------------------------------------- @@ -23,7 +24,7 @@ This framework just adds a new layer between the MTD and the SPI bus driver. With this new layer, the SPI NOR controller driver does not depend on the m25p80 code anymore. - Before this framework, the layer is like: +Before this framework, the layer is like:: MTD ------------------------ diff --git a/Documentation/driver-api/nfc/index.rst b/Documentation/driver-api/nfc/index.rst new file mode 100644 index 000000000000..b6e9eedbff29 --- /dev/null +++ b/Documentation/driver-api/nfc/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +Near Field Communication +======================== + +.. toctree:: + :maxdepth: 1 + + nfc-hci + nfc-pn544 diff --git a/Documentation/nfc/nfc-hci.txt b/Documentation/driver-api/nfc/nfc-hci.rst index 0dc078cab972..eb8a1a14e919 100644 --- a/Documentation/nfc/nfc-hci.txt +++ b/Documentation/driver-api/nfc/nfc-hci.rst @@ -1,7 +1,9 @@ +======================== HCI backend for NFC Core +======================== -Author: Eric Lapuyade, Samuel Ortiz -Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com +- Author: Eric Lapuyade, Samuel Ortiz +- Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com General ------- @@ -24,12 +26,13 @@ HCI events can also be received from the host controller. They will be handled and a translation will be forwarded to NFC Core as needed. There are hooks to let the HCI driver handle proprietary events or override standard behavior. HCI uses 2 execution contexts: + - one for executing commands : nfc_hci_msg_tx_work(). Only one command -can be executing at any given moment. + can be executing at any given moment. - one for dispatching received events and commands : nfc_hci_msg_rx_work(). -HCI Session initialization: ---------------------------- +HCI Session initialization +-------------------------- The Session initialization is an HCI standard which must unfortunately support proprietary gates. This is the reason why the driver will pass a list @@ -58,9 +61,9 @@ HCI Management -------------- A driver would normally register itself with HCI and provide the following -entry points: +entry points:: -struct nfc_hci_ops { + struct nfc_hci_ops { int (*open)(struct nfc_hci_dev *hdev); void (*close)(struct nfc_hci_dev *hdev); int (*hci_ready) (struct nfc_hci_dev *hdev); @@ -82,38 +85,38 @@ struct nfc_hci_ops { struct nfc_target *target); int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event, struct sk_buff *skb); -}; + }; - open() and close() shall turn the hardware on and off. - hci_ready() is an optional entry point that is called right after the hci -session has been set up. The driver can use it to do additional initialization -that must be performed using HCI commands. + session has been set up. The driver can use it to do additional initialization + that must be performed using HCI commands. - xmit() shall simply write a frame to the physical link. - start_poll() is an optional entrypoint that shall set the hardware in polling -mode. This must be implemented only if the hardware uses proprietary gates or a -mechanism slightly different from the HCI standard. + mode. This must be implemented only if the hardware uses proprietary gates or a + mechanism slightly different from the HCI standard. - dep_link_up() is called after a p2p target has been detected, to finish -the p2p connection setup with hardware parameters that need to be passed back -to nfc core. + the p2p connection setup with hardware parameters that need to be passed back + to nfc core. - dep_link_down() is called to bring the p2p link down. - target_from_gate() is an optional entrypoint to return the nfc protocols -corresponding to a proprietary gate. + corresponding to a proprietary gate. - complete_target_discovered() is an optional entry point to let the driver -perform additional proprietary processing necessary to auto activate the -discovered target. + perform additional proprietary processing necessary to auto activate the + discovered target. - im_transceive() must be implemented by the driver if proprietary HCI commands -are required to send data to the tag. Some tag types will require custom -commands, others can be written to using the standard HCI commands. The driver -can check the tag type and either do proprietary processing, or return 1 to ask -for standard processing. The data exchange command itself must be sent -asynchronously. + are required to send data to the tag. Some tag types will require custom + commands, others can be written to using the standard HCI commands. The driver + can check the tag type and either do proprietary processing, or return 1 to ask + for standard processing. The data exchange command itself must be sent + asynchronously. - tm_send() is called to send data in the case of a p2p connection - check_presence() is an optional entry point that will be called regularly -by the core to check that an activated tag is still in the field. If this is -not implemented, the core will not be able to push tag_lost events to the user -space + by the core to check that an activated tag is still in the field. If this is + not implemented, the core will not be able to push tag_lost events to the user + space - event_received() is called to handle an event coming from the chip. Driver -can handle the event or return 1 to let HCI attempt standard processing. + can handle the event or return 1 to let HCI attempt standard processing. On the rx path, the driver is responsible to push incoming HCP frames to HCI using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling @@ -122,20 +125,23 @@ This must be done from a context that can sleep. PHY Management -------------- -The physical link (i2c, ...) management is defined by the following structure: +The physical link (i2c, ...) management is defined by the following structure:: -struct nfc_phy_ops { + struct nfc_phy_ops { int (*write)(void *dev_id, struct sk_buff *skb); int (*enable)(void *dev_id); void (*disable)(void *dev_id); -}; - -enable(): turn the phy on (power on), make it ready to transfer data -disable(): turn the phy off -write(): Send a data frame to the chip. Note that to enable higher -layers such as an llc to store the frame for re-emission, this function must -not alter the skb. It must also not return a positive result (return 0 for -success, negative for failure). + }; + +enable(): + turn the phy on (power on), make it ready to transfer data +disable(): + turn the phy off +write(): + Send a data frame to the chip. Note that to enable higher + layers such as an llc to store the frame for re-emission, this + function must not alter the skb. It must also not return a positive + result (return 0 for success, negative for failure). Data coming from the chip shall be sent directly to nfc_hci_recv_frame(). @@ -145,9 +151,9 @@ LLC Communication between the CPU and the chip often requires some link layer protocol. Those are isolated as modules managed by the HCI layer. There are currently two modules : nop (raw transfert) and shdlc. -A new llc must implement the following functions: +A new llc must implement the following functions:: -struct nfc_llc_ops { + struct nfc_llc_ops { void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv, rcv_to_hci_t rcv_to_hci, int tx_headroom, int tx_tailroom, int *rx_headroom, int *rx_tailroom, @@ -157,17 +163,25 @@ struct nfc_llc_ops { int (*stop) (struct nfc_llc *llc); void (*rcv_from_drv) (struct nfc_llc *llc, struct sk_buff *skb); int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb); -}; - -- init() : allocate and init your private storage -- deinit() : cleanup -- start() : establish the logical connection -- stop () : terminate the logical connection -- rcv_from_drv() : handle data coming from the chip, going to HCI -- xmit_from_hci() : handle data sent by HCI, going to the chip + }; + +init(): + allocate and init your private storage +deinit(): + cleanup +start(): + establish the logical connection +stop (): + terminate the logical connection +rcv_from_drv(): + handle data coming from the chip, going to HCI +xmit_from_hci(): + handle data sent by HCI, going to the chip The llc must be registered with nfc before it can be used. Do that by -calling nfc_llc_register(const char *name, struct nfc_llc_ops *ops); +calling:: + + nfc_llc_register(const char *name, struct nfc_llc_ops *ops); Again, note that the llc does not handle the physical link. It is thus very easy to mix any physical link with any llc for a given chip driver. @@ -187,26 +201,32 @@ fast, cannot sleep. sends incoming frames to HCI where they are passed to the current llc. In case of shdlc, the frame is queued in shdlc rx queue. - SHDLC State Machine worker (SMW) -Only when llc_shdlc is used: handles shdlc rx & tx queues. -Dispatches HCI cmd responses. + + Only when llc_shdlc is used: handles shdlc rx & tx queues. + + Dispatches HCI cmd responses. - HCI Tx Cmd worker (MSGTXWQ) -Serializes execution of HCI commands. Completes execution in case of response -timeout. + + Serializes execution of HCI commands. + + Completes execution in case of response timeout. - HCI Rx worker (MSGRXWQ) -Dispatches incoming HCI commands or events. + + Dispatches incoming HCI commands or events. - Syscall context from a userspace call (SYSCALL) -Any entrypoint in HCI called from NFC Core + + Any entrypoint in HCI called from NFC Core Workflow executing an HCI command (using shdlc) ----------------------------------------------- Executing an HCI command can easily be performed synchronously using the -following API: +following API:: -int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd, + int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd, const u8 *param, size_t param_len, struct sk_buff **skb) The API must be invoked from a context that can sleep. Most of the time, this @@ -234,11 +254,11 @@ waiting command execution. Response processing involves invoking the completion callback that was provided by nfc_hci_msg_tx_work() when it sent the command. The completion callback will then wake the syscall context. -It is also possible to execute the command asynchronously using this API: +It is also possible to execute the command asynchronously using this API:: -static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd, - const u8 *param, size_t param_len, - data_exchange_cb_t cb, void *cb_context) + static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd, + const u8 *param, size_t param_len, + data_exchange_cb_t cb, void *cb_context) The workflow is the same, except that the API call returns immediately, and the callback will be called with the result from the SMW context. @@ -268,23 +288,24 @@ went wrong below and know that expected events will probably never happen. Handling of these errors is done as follows: - driver (pn544) fails to deliver an incoming frame: it stores the error such -that any subsequent call to the driver will result in this error. Then it calls -the standard nfc_shdlc_recv_frame() with a NULL argument to report the problem -above. shdlc stores a EREMOTEIO sticky status, which will trigger SMW to -report above in turn. + that any subsequent call to the driver will result in this error. Then it + calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the + problem above. shdlc stores a EREMOTEIO sticky status, which will trigger + SMW to report above in turn. - SMW is basically a background thread to handle incoming and outgoing shdlc -frames. This thread will also check the shdlc sticky status and report to HCI -when it discovers it is not able to run anymore because of an unrecoverable -error that happened within shdlc or below. If the problem occurs during shdlc -connection, the error is reported through the connect completion. + frames. This thread will also check the shdlc sticky status and report to HCI + when it discovers it is not able to run anymore because of an unrecoverable + error that happened within shdlc or below. If the problem occurs during shdlc + connection, the error is reported through the connect completion. - HCI: if an internal HCI error happens (frame is lost), or HCI is reported an -error from a lower layer, HCI will either complete the currently executing -command with that error, or notify NFC Core directly if no command is executing. + error from a lower layer, HCI will either complete the currently executing + command with that error, or notify NFC Core directly if no command is + executing. - NFC Core: when NFC Core is notified of an error from below and polling is -active, it will send a tag discovered event with an empty tag list to the user -space to let it know that the poll operation will never be able to detect a tag. -If polling is not active and the error was sticky, lower levels will return it -at next invocation. + active, it will send a tag discovered event with an empty tag list to the user + space to let it know that the poll operation will never be able to detect a + tag. If polling is not active and the error was sticky, lower levels will + return it at next invocation. diff --git a/Documentation/nfc/nfc-pn544.txt b/Documentation/driver-api/nfc/nfc-pn544.rst index b36ca14ca2d6..6b2d8aae0c4e 100644 --- a/Documentation/nfc/nfc-pn544.txt +++ b/Documentation/driver-api/nfc/nfc-pn544.rst @@ -1,5 +1,7 @@ -Kernel driver for the NXP Semiconductors PN544 Near Field -Communication chip +============================================================================ +Kernel driver for the NXP Semiconductors PN544 Near Field Communication chip +============================================================================ + General ------- diff --git a/Documentation/ntb.txt b/Documentation/driver-api/ntb.rst index 074a423c853c..87d1372da879 100644 --- a/Documentation/ntb.txt +++ b/Documentation/driver-api/ntb.rst @@ -200,6 +200,33 @@ Debugfs Files: This file is used to read and write peer scratchpads. See *spad* for details. +NTB MSI Test Client (ntb\_msi\_test) +------------------------------------ + +The MSI test client serves to test and debug the MSI library which +allows for passing MSI interrupts across NTB memory windows. The +test client is interacted with through the debugfs filesystem: + +* *debugfs*/ntb\_tool/*hw*/ + A directory in debugfs will be created for each + NTB device probed by the tool. This directory is shortened to *hw* + below. +* *hw*/port + This file describes the local port number +* *hw*/irq*_occurrences + One occurrences file exists for each interrupt and, when read, + returns the number of times the interrupt has been triggered. +* *hw*/peer*/port + This file describes the port number for each peer +* *hw*/peer*/count + This file describes the number of interrupts that can be + triggered on each peer +* *hw*/peer*/trigger + Writing an interrupt number (any number less than the value + specified in count) will trigger the interrupt on the + specified peer. That peer's interrupt's occurrence file + should be incremented. + NTB Hardware Drivers ==================== diff --git a/Documentation/nvdimm/btt.txt b/Documentation/driver-api/nvdimm/btt.rst index e293fb664924..107395c042ae 100644 --- a/Documentation/nvdimm/btt.txt +++ b/Documentation/driver-api/nvdimm/btt.rst @@ -1,9 +1,10 @@ +============================= BTT - Block Translation Table ============================= 1. Introduction ---------------- +=============== Persistent memory based storage is able to perform IO at byte (or more accurately, cache line) granularity. However, we often want to expose such @@ -25,7 +26,7 @@ provides atomic sector updates. 2. Static Layout ----------------- +================ The underlying storage on which a BTT can be laid out is not limited in any way. The BTT, however, splits the available space into chunks of up to 512 GiB, @@ -33,43 +34,43 @@ called "Arenas". Each arena follows the same layout for its metadata, and all references in an arena are internal to it (with the exception of one field that points to the -next arena). The following depicts the "On-disk" metadata layout: - - - Backing Store +-------> Arena -+---------------+ | +------------------+ -| | | | Arena info block | -| Arena 0 +---+ | 4K | -| 512G | +------------------+ -| | | | -+---------------+ | | -| | | | -| Arena 1 | | Data Blocks | -| 512G | | | -| | | | -+---------------+ | | -| . | | | -| . | | | -| . | | | -| | | | -| | | | -+---------------+ +------------------+ - | | - | BTT Map | - | | - | | - +------------------+ - | | - | BTT Flog | - | | - +------------------+ - | Info block copy | - | 4K | - +------------------+ +next arena). The following depicts the "On-disk" metadata layout:: + + + Backing Store +-------> Arena + +---------------+ | +------------------+ + | | | | Arena info block | + | Arena 0 +---+ | 4K | + | 512G | +------------------+ + | | | | + +---------------+ | | + | | | | + | Arena 1 | | Data Blocks | + | 512G | | | + | | | | + +---------------+ | | + | . | | | + | . | | | + | . | | | + | | | | + | | | | + +---------------+ +------------------+ + | | + | BTT Map | + | | + | | + +------------------+ + | | + | BTT Flog | + | | + +------------------+ + | Info block copy | + | 4K | + +------------------+ 3. Theory of Operation ----------------------- +====================== a. The BTT Map @@ -79,31 +80,37 @@ The map is a simple lookup/indirection table that maps an LBA to an internal block. Each map entry is 32 bits. The two most significant bits are special flags, and the remaining form the internal block number. +======== ============================================================= Bit Description -31 - 30 : Error and Zero flags - Used in the following way: - Bit Description - 31 30 - ----------------------------------------------------------------------- - 00 Initial state. Reads return zeroes; Premap = Postmap - 01 Zero state: Reads return zeroes - 10 Error state: Reads fail; Writes clear 'E' bit - 11 Normal Block – has valid postmap +======== ============================================================= +31 - 30 Error and Zero flags - Used in the following way:: + == == ==================================================== + 31 30 Description + == == ==================================================== + 0 0 Initial state. Reads return zeroes; Premap = Postmap + 0 1 Zero state: Reads return zeroes + 1 0 Error state: Reads fail; Writes clear 'E' bit + 1 1 Normal Block – has valid postmap + == == ==================================================== -29 - 0 : Mappings to internal 'postmap' blocks +29 - 0 Mappings to internal 'postmap' blocks +======== ============================================================= Some of the terminology that will be subsequently used: -External LBA : LBA as made visible to upper layers. -ABA : Arena Block Address - Block offset/number within an arena -Premap ABA : The block offset into an arena, which was decided upon by range +============ ================================================================ +External LBA LBA as made visible to upper layers. +ABA Arena Block Address - Block offset/number within an arena +Premap ABA The block offset into an arena, which was decided upon by range checking the External LBA -Postmap ABA : The block number in the "Data Blocks" area obtained after +Postmap ABA The block number in the "Data Blocks" area obtained after indirection from the map -nfree : The number of free blocks that are maintained at any given time. +nfree The number of free blocks that are maintained at any given time. This is the number of concurrent writes that can happen to the arena. +============ ================================================================ For example, after adding a BTT, we surface a disk of 1024G. We get a read for @@ -121,19 +128,21 @@ i.e. Every write goes to a "free" block. A running list of free blocks is maintained in the form of the BTT flog. 'Flog' is a combination of the words "free list" and "log". The flog contains 'nfree' entries, and an entry contains: -lba : The premap ABA that is being written to -old_map : The old postmap ABA - after 'this' write completes, this will be a +======== ===================================================================== +lba The premap ABA that is being written to +old_map The old postmap ABA - after 'this' write completes, this will be a free block. -new_map : The new postmap ABA. The map will up updated to reflect this +new_map The new postmap ABA. The map will up updated to reflect this lba->postmap_aba mapping, but we log it here in case we have to recover. -seq : Sequence number to mark which of the 2 sections of this flog entry is +seq Sequence number to mark which of the 2 sections of this flog entry is valid/newest. It cycles between 01->10->11->01 (binary) under normal operation, with 00 indicating an uninitialized state. -lba' : alternate lba entry -old_map': alternate old postmap entry -new_map': alternate new postmap entry -seq' : alternate sequence number. +lba' alternate lba entry +old_map' alternate old postmap entry +new_map' alternate new postmap entry +seq' alternate sequence number. +======== ===================================================================== Each of the above fields is 32-bit, making one entry 32 bytes. Entries are also padded to 64 bytes to avoid cache line sharing or aliasing. Flog updates are @@ -147,8 +156,10 @@ c. The concept of lanes While 'nfree' describes the number of concurrent IOs an arena can process concurrently, 'nlanes' is the number of IOs the BTT device as a whole can -process. - nlanes = min(nfree, num_cpus) +process:: + + nlanes = min(nfree, num_cpus) + A lane number is obtained at the start of any IO, and is used for indexing into all the on-disk and in-memory data structures for the duration of the IO. If there are more CPUs than the max number of available lanes, than lanes are @@ -180,10 +191,10 @@ e. In-memory data structure: map locks -------------------------------------- Consider a case where two writer threads are writing to the same LBA. There can -be a race in the following sequence of steps: +be a race in the following sequence of steps:: -free[lane] = map[premap_aba] -map[premap_aba] = postmap_aba + free[lane] = map[premap_aba] + map[premap_aba] = postmap_aba Both threads can update their respective free[lane] with the same old, freed postmap_aba. This has made the layout inconsistent by losing a free entry, and @@ -202,6 +213,7 @@ On startup, we analyze the BTT flog to create our list of free blocks. We walk through all the entries, and for each lane, of the set of two possible 'sections', we always look at the most recent one only (based on the sequence number). The reconstruction rules/steps are simple: + - Read map[log_entry.lba]. - If log_entry.new matches the map entry, then log_entry.old is free. - If log_entry.new does not match the map entry, then log_entry.new is free. @@ -228,7 +240,7 @@ Write: 1. Convert external LBA to Arena number + pre-map ABA 2. Get a lane (and take lane_lock) 3. Use lane to index into in-memory free list and obtain a new block, next flog - index, next sequence number + index, next sequence number 4. Scan the RTT to check if free block is present, and spin/wait if it is. 5. Write data to this free block 6. Read map to get the existing post-map ABA entry for this pre-map ABA @@ -245,6 +257,7 @@ Write: An arena would be in an error state if any of the metadata is corrupted irrecoverably, either due to a bug or a media error. The following conditions indicate an error: + - Info block checksum does not match (and recovering from the copy also fails) - All internal available blocks are not uniquely and entirely addressed by the sum of mapped blocks and free blocks (from the BTT flog). @@ -263,11 +276,10 @@ The BTT can be set up on any disk (namespace) exposed by the libnvdimm subsystem (pmem, or blk mode). The easiest way to set up such a namespace is using the 'ndctl' utility [1]: -For example, the ndctl command line to setup a btt with a 4k sector size is: +For example, the ndctl command line to setup a btt with a 4k sector size is:: ndctl create-namespace -f -e namespace0.0 -m sector -l 4k See ndctl create-namespace --help for more options. [1]: https://github.com/pmem/ndctl - diff --git a/Documentation/driver-api/nvdimm/index.rst b/Documentation/driver-api/nvdimm/index.rst new file mode 100644 index 000000000000..a4f8f98aeb94 --- /dev/null +++ b/Documentation/driver-api/nvdimm/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +Non-Volatile Memory Device (NVDIMM) +=================================== + +.. toctree:: + :maxdepth: 1 + + nvdimm + btt + security diff --git a/Documentation/nvdimm/nvdimm.txt b/Documentation/driver-api/nvdimm/nvdimm.rst index 1669f626b037..08f855cbb4e6 100644 --- a/Documentation/nvdimm/nvdimm.txt +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -1,8 +1,14 @@ - LIBNVDIMM: Non-Volatile Devices - libnvdimm - kernel / libndctl - userspace helper library - linux-nvdimm@lists.01.org - v13 +=============================== +LIBNVDIMM: Non-Volatile Devices +=============================== +libnvdimm - kernel / libndctl - userspace helper library + +linux-nvdimm@lists.01.org + +Version 13 + +.. contents: Glossary Overview @@ -40,49 +46,57 @@ Glossary --------- - -PMEM: A system-physical-address range where writes are persistent. A -block device composed of PMEM is capable of DAX. A PMEM address range -may span an interleave of several DIMMs. - -BLK: A set of one or more programmable memory mapped apertures provided -by a DIMM to access its media. This indirection precludes the -performance benefit of interleaving, but enables DIMM-bounded failure -modes. - -DPA: DIMM Physical Address, is a DIMM-relative offset. With one DIMM in -the system there would be a 1:1 system-physical-address:DPA association. -Once more DIMMs are added a memory controller interleave must be -decoded to determine the DPA associated with a given -system-physical-address. BLK capacity always has a 1:1 relationship -with a single-DIMM's DPA range. - -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 -table with atomic update semantics to front a PMEM/BLK block device -driver and present arbitrary atomic sector sizes. - -LABEL: Metadata stored on a DIMM device that partitions and identifies -(persistently names) storage between PMEM and BLK. It also partitions -BLK storage to host BTTs with different parameters per BLK-partition. -Note that traditional partition tables, GPT/MBR, are layered on top of a -BLK or PMEM device. +======== + +PMEM: + A system-physical-address range where writes are persistent. A + block device composed of PMEM is capable of DAX. A PMEM address range + may span an interleave of several DIMMs. + +BLK: + A set of one or more programmable memory mapped apertures provided + by a DIMM to access its media. This indirection precludes the + performance benefit of interleaving, but enables DIMM-bounded failure + modes. + +DPA: + DIMM Physical Address, is a DIMM-relative offset. With one DIMM in + the system there would be a 1:1 system-physical-address:DPA association. + Once more DIMMs are added a memory controller interleave must be + decoded to determine the DPA associated with a given + system-physical-address. BLK capacity always has a 1:1 relationship + with a single-DIMM's DPA range. + +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 + table with atomic update semantics to front a PMEM/BLK block device + driver and present arbitrary atomic sector sizes. + +LABEL: + Metadata stored on a DIMM device that partitions and identifies + (persistently names) storage between PMEM and BLK. It also partitions + BLK storage to host BTTs with different parameters per BLK-partition. + Note that traditional partition tables, GPT/MBR, are layered on top of a + BLK or PMEM device. Overview --------- +======== The LIBNVDIMM subsystem provides support for three types of NVDIMMs, namely, PMEM, BLK, and NVDIMM devices that can simultaneously support both PMEM @@ -96,19 +110,30 @@ accessible via BLK. When that occurs a LABEL is needed to reserve DPA for exclusive access via one mode a time. Supporting Documents -ACPI 6: http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf -NVDIMM Namespace: http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf -DSM Interface Example: http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf -Driver Writer's Guide: http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf +-------------------- + +ACPI 6: + http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf +NVDIMM Namespace: + http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf +DSM Interface Example: + http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf +Driver Writer's Guide: + http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf Git Trees -LIBNVDIMM: https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git -LIBNDCTL: https://github.com/pmem/ndctl.git -PMEM: https://github.com/01org/prd +--------- + +LIBNVDIMM: + https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git +LIBNDCTL: + https://github.com/pmem/ndctl.git +PMEM: + https://github.com/01org/prd LIBNVDIMM PMEM and BLK ------------------- +====================== Prior to the arrival of the NFIT, non-volatile memory was described to a system in various ad-hoc ways. Usually only the bare minimum was @@ -122,38 +147,39 @@ For each NVDIMM access method (PMEM, BLK), LIBNVDIMM provides a block device driver: 1. PMEM (nd_pmem.ko): Drives a system-physical-address range. This - range is contiguous in system memory and may be interleaved (hardware - memory controller striped) across multiple DIMMs. When interleaved the - platform may optionally provide details of which DIMMs are participating - in the interleave. - - Note that while LIBNVDIMM describes system-physical-address ranges that may - alias with BLK access as ND_NAMESPACE_PMEM ranges and those without - alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no - distinction. The different device-types are an implementation detail - that userspace can exploit to implement policies like "only interface - with address ranges from certain DIMMs". It is worth noting that when - aliasing is present and a DIMM lacks a label, then no block device can - be created by default as userspace needs to do at least one allocation - of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once - registered, can be immediately attached to nd_pmem. + range is contiguous in system memory and may be interleaved (hardware + memory controller striped) across multiple DIMMs. When interleaved the + platform may optionally provide details of which DIMMs are participating + in the interleave. + + Note that while LIBNVDIMM describes system-physical-address ranges that may + alias with BLK access as ND_NAMESPACE_PMEM ranges and those without + alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no + distinction. The different device-types are an implementation detail + that userspace can exploit to implement policies like "only interface + with address ranges from certain DIMMs". It is worth noting that when + aliasing is present and a DIMM lacks a label, then no block device can + be created by default as userspace needs to do at least one allocation + of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once + 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 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. + 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 have other designs for BLK I/O. For this reason + "nd_blk" calls back into platform-specific code to perform the I/O. - 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 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". + One such implementation is defined in the "Driver Writer's Guide" and "DSM + Interface Example". Why BLK? --------- +======== While PMEM provides direct byte-addressable CPU-load/store access to NVDIMM storage, it does not provide the best system RAS (recovery, @@ -162,12 +188,15 @@ 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. + Also, if an administrator ever wants to replace a memory it is easier to service a system at DIMM module boundaries. Compare this to PMEM where data could be interleaved in an opaque hardware specific manner across several DIMMs. PMEM vs BLK +----------- + 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. @@ -185,13 +214,14 @@ carved into an arbitrary number of BLK devices with discontiguous extents. BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX --------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One of the few reasons to allow multiple BLK namespaces per REGION is so that each BLK-namespace can be configured with a BTT with unique atomic sector sizes. While a PMEM device can host a BTT the LABEL specification does not provide for a sector size to be specified for a PMEM namespace. + This is due to the expectation that the primary usage model for PMEM is via DAX, and the BTT is incompatible with DAX. However, for the cases where an application or filesystem still needs atomic sector update @@ -200,52 +230,52 @@ LIBNVDIMM/NDCTL: Block Translation Table "btt" Example NVDIMM Platform ------------------------ +======================= For the remainder of this document the following diagram will be -referenced for any example sysfs layouts. - - - (a) (b) DIMM BLK-REGION - +-------------------+--------+--------+--------+ -+------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2 -| imc0 +--+- - - region0- - - +--------+ +--------+ -+--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3 - | +-------------------+--------v v--------+ -+--+---+ | | -| cpu0 | region1 -+--+---+ | | - | +----------------------------^ ^--------+ -+--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4 -| imc1 +--+----------------------------| +--------+ -+------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5 - +----------------------------+--------+--------+ +referenced for any example sysfs layouts:: + + + (a) (b) DIMM BLK-REGION + +-------------------+--------+--------+--------+ + +------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2 + | imc0 +--+- - - region0- - - +--------+ +--------+ + +--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3 + | +-------------------+--------v v--------+ + +--+---+ | | + | cpu0 | region1 + +--+---+ | | + | +----------------------------^ ^--------+ + +--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4 + | imc1 +--+----------------------------| +--------+ + +------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5 + +----------------------------+--------+--------+ In this platform we have four DIMMs and two memory controllers in one 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 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 - REGION3 where "blk2.0" and "blk3.0" are just human readable names that - could be set to any user-desired name in the LABEL. + 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 + REGION3 where "blk2.0" and "blk3.0" are just human readable names that + could be set to any user-desired name in the LABEL. 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 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". + system-physical-address range, REGION1, that spans those two DIMMs as + 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 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. + 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. This bus is provided by the kernel under the device /sys/devices/platform/nfit_test.0 when CONFIG_NFIT_TEST is enabled and @@ -254,7 +284,7 @@ by a region device with a dynamically assigned id (REGION0 - REGION5). 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 @@ -263,12 +293,18 @@ 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 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: struct ndctl_ctx *ctx; @@ -278,7 +314,7 @@ LIBNDCTL: instantiate a new library context example return NULL; LIBNVDIMM/LIBNDCTL: Bus -------------------- +----------------------- A bus has a 1:1 relationship with an NFIT. The current expectation for ACPI based systems is that there is only ever one platform-global NFIT. @@ -288,9 +324,10 @@ we use this capability to test multiple NFIT configurations in the unit test. LIBNVDIMM: control class device in /sys/class +--------------------------------------------- This character device accepts DSM messages to be passed to DIMM -identified by its NFIT handle. +identified by its NFIT handle:: /sys/class/nd/ndctl0 |-- dev @@ -300,10 +337,15 @@ identified by its NFIT handle. LIBNVDIMM: bus +-------------- + +:: struct nvdimm_bus *nvdimm_bus_register(struct device *parent, struct nvdimm_bus_descriptor *nfit_desc); +:: + /sys/devices/platform/nfit_test.0/ndbus0 |-- commands |-- nd @@ -324,7 +366,9 @@ LIBNVDIMM: bus `-- wait_probe LIBNDCTL: bus enumeration example -Find the bus handle that describes the bus from Example NVDIMM Platform +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Find the bus handle that describes the bus from Example NVDIMM Platform:: static struct ndctl_bus *get_bus_by_provider(struct ndctl_ctx *ctx, const char *provider) @@ -342,7 +386,7 @@ Find the bus handle that describes the bus from Example NVDIMM Platform LIBNVDIMM/LIBNDCTL: DIMM (NMEM) ---------------------------- +------------------------------- The DIMM device provides a character device for sending commands to hardware, and it is a container for LABELs. If the DIMM is defined by @@ -355,11 +399,16 @@ Range Mapping Structure", and there is no requirement that they actually be physical DIMMs, so we use a more generic name. LIBNVDIMM: DIMM (NMEM) +^^^^^^^^^^^^^^^^^^^^^^ + +:: struct nvdimm *nvdimm_create(struct nvdimm_bus *nvdimm_bus, void *provider_data, const struct attribute_group **groups, unsigned long flags, unsigned long *dsm_mask); +:: + /sys/devices/platform/nfit_test.0/ndbus0 |-- nmem0 | |-- available_slots @@ -384,15 +433,20 @@ LIBNVDIMM: DIMM (NMEM) LIBNDCTL: DIMM enumeration example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Note, in this example we are assuming NFIT-defined DIMMs which are identified by an "nfit_handle" a 32-bit value where: -Bit 3:0 DIMM number within the memory channel -Bit 7:4 memory channel number -Bit 11:8 memory controller ID -Bit 15:12 socket ID (within scope of a Node controller if node controller is present) -Bit 27:16 Node Controller ID -Bit 31:28 Reserved + + - Bit 3:0 DIMM number within the memory channel + - Bit 7:4 memory channel number + - Bit 11:8 memory controller ID + - Bit 15:12 socket ID (within scope of a Node controller if node + controller is present) + - Bit 27:16 Node Controller ID + - Bit 31:28 Reserved + +:: static struct ndctl_dimm *get_dimm_by_handle(struct ndctl_bus *bus, unsigned int handle) @@ -413,7 +467,7 @@ Bit 31:28 Reserved dimm = get_dimm_by_handle(bus, DIMM_HANDLE(0, 0, 0, 0, 0)); LIBNVDIMM/LIBNDCTL: Region ----------------------- +-------------------------- 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 @@ -435,13 +489,15 @@ emits, "devtype" duplicates the DEVTYPE variable stored by udev at the at the 'add' event, and finally, the optional "spa_index" is provided in the case where the region is defined by a SPA. -LIBNVDIMM: region +LIBNVDIMM: region:: struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus, struct nd_region_desc *ndr_desc); struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus, struct nd_region_desc *ndr_desc); +:: + /sys/devices/platform/nfit_test.0/ndbus0 |-- region0 | |-- available_size @@ -468,10 +524,11 @@ LIBNVDIMM: region [..] LIBNDCTL: region enumeration example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sample region retrieval routines based on NFIT-unique data like "spa_index" (interleave set id) for PMEM and "nfit_handle" (dimm id) for -BLK. +BLK:: static struct ndctl_region *get_pmem_region_by_spa_index(struct ndctl_bus *bus, unsigned int spa_index) @@ -518,33 +575,33 @@ REGION name generic and expects userspace to always consider the 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 - the constituent DIMM devices are known and anonymous PMEM. For BLK - regions the NFIT specification already anticipates vendor specific - implementations. The exact distinction of what a region contains is in - the region-attributes not the region-name or the region-devtype. + PMEM there are two subtypes. As mentioned previously we have PMEM where + the constituent DIMM devices are known and anonymous PMEM. For BLK + regions the NFIT specification already anticipates vendor specific + implementations. The exact distinction of what a region contains is in + the region-attributes not the region-name or the region-devtype. 2. A region with zero child-namespaces is a possible configuration. For - example, the NFIT allows for a DCR to be published without a - corresponding BLK-aperture. This equates to a DIMM that can only accept - control/configuration messages, but no i/o through a descendant block - device. Again, this "type" is advertised in the attributes ('mappings' - == 0) and the name does not tell you much. + example, the NFIT allows for a DCR to be published without a + corresponding BLK-aperture. This equates to a DIMM that can only accept + control/configuration messages, but no i/o through a descendant block + device. Again, this "type" is advertised in the attributes ('mappings' + == 0) and the name does not tell you much. 3. What if a third major interface type arises in the future? Outside - of vendor specific implementations, it's not difficult to envision a - third class of interface type beyond BLK and PMEM. With a generic name - for the REGION level of the device-hierarchy old userspace - implementations can still make sense of new kernel advertised - region-types. Userspace can always rely on the generic region - attributes like "mappings", "size", etc and the expected child devices - named "namespace". This generic format of the device-model hierarchy - allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and - future-proof. + of vendor specific implementations, it's not difficult to envision a + third class of interface type beyond BLK and PMEM. With a generic name + for the REGION level of the device-hierarchy old userspace + implementations can still make sense of new kernel advertised + region-types. Userspace can always rely on the generic region + attributes like "mappings", "size", etc and the expected child devices + named "namespace". This generic format of the device-model hierarchy + allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and + future-proof. 4. There are more robust mechanisms for determining the major type of a - region than a device name. See the next section, How Do I Determine the - Major Type of a Region? + region than a device name. See the next section, How Do I Determine the + Major Type of a Region? How Do I Determine the Major Type of a Region? ---------------------------------------------- @@ -553,7 +610,8 @@ Outside of the blanket recommendation of "use libndctl", or simply looking at the kernel header (/usr/include/linux/ndctl.h) to decode the "nstype" integer attribute, here are some other options. - 1. module alias lookup: +1. module alias lookup +^^^^^^^^^^^^^^^^^^^^^^ The whole point of region/namespace device type differentiation is to decide which block-device driver will attach to a given LIBNVDIMM namespace. @@ -569,28 +627,31 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the the resulting namespaces. The output from module resolution is more accurate than a region-name or region-devtype. - 2. udev: +2. udev +^^^^^^^ + + The kernel "devtype" is registered in the udev database:: - The kernel "devtype" is registered in the udev database - # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0 - P: /devices/platform/nfit_test.0/ndbus0/region0 - E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0 - E: DEVTYPE=nd_pmem - E: MODALIAS=nd:t2 - E: SUBSYSTEM=nd + # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0 + P: /devices/platform/nfit_test.0/ndbus0/region0 + E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0 + E: DEVTYPE=nd_pmem + E: MODALIAS=nd:t2 + E: SUBSYSTEM=nd - # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4 - P: /devices/platform/nfit_test.0/ndbus0/region4 - E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4 - E: DEVTYPE=nd_blk - E: MODALIAS=nd:t3 - E: SUBSYSTEM=nd + # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4 + P: /devices/platform/nfit_test.0/ndbus0/region4 + E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4 + E: DEVTYPE=nd_blk + E: MODALIAS=nd:t3 + E: SUBSYSTEM=nd ...and is available as a region attribute, but keep in mind that the "devtype" does not indicate sub-type variations and scripts should really be understanding the other attributes. - 3. type specific attributes: +3. type specific attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^ As it currently stands a BLK-aperture region will never have a "nfit/spa_index" attribute, but neither will a non-NFIT PMEM region. A @@ -600,7 +661,7 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the LIBNVDIMM/LIBNDCTL: Namespace -------------------------- +----------------------------- A REGION, after resolving DPA aliasing and LABEL specified boundaries, surfaces one or more "namespace" devices. The arrival of a "namespace" @@ -608,12 +669,14 @@ device currently triggers either the nd_blk or nd_pmem driver to load and register a disk/block device. LIBNVDIMM: namespace +^^^^^^^^^^^^^^^^^^^^ + Here is a sample layout from the three major types of NAMESPACE where namespace0.0 represents DIMM-info-backed PMEM (note that it has a 'uuid' attribute), namespace2.0 represents a BLK namespace (note it has a 'sector_size' attribute) that, and namespace6.0 represents an anonymous PMEM namespace (note that has no 'uuid' attribute due to not support a -LABEL). +LABEL):: /sys/devices/platform/nfit_test.0/ndbus0/region0/namespace0.0 |-- alt_name @@ -656,76 +719,84 @@ LABEL). `-- uevent LIBNDCTL: namespace enumeration example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Namespaces are indexed relative to their parent region, example below. These indexes are mostly static from boot to boot, but subsystem makes no guarantees in this regard. For a static namespace identifier use its 'uuid' attribute. -static struct ndctl_namespace *get_namespace_by_id(struct ndctl_region *region, - unsigned int id) -{ - struct ndctl_namespace *ndns; +:: - ndctl_namespace_foreach(region, ndns) - if (ndctl_namespace_get_id(ndns) == id) - return ndns; + static struct ndctl_namespace + *get_namespace_by_id(struct ndctl_region *region, unsigned int id) + { + struct ndctl_namespace *ndns; - return NULL; -} + ndctl_namespace_foreach(region, ndns) + if (ndctl_namespace_get_id(ndns) == id) + return ndns; + + return NULL; + } LIBNDCTL: namespace creation example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Idle namespaces are automatically created by the kernel if a given region has enough available capacity to create a new namespace. Namespace instantiation involves finding an idle namespace and configuring it. For the most part the setting of namespace attributes can occur in any order, the only constraint is that 'uuid' must be set before 'size'. This enables the kernel to track DPA allocations -internally with a static identifier. +internally with a static identifier:: -static int configure_namespace(struct ndctl_region *region, - struct ndctl_namespace *ndns, - struct namespace_parameters *parameters) -{ - char devname[50]; + static int configure_namespace(struct ndctl_region *region, + struct ndctl_namespace *ndns, + struct namespace_parameters *parameters) + { + char devname[50]; - snprintf(devname, sizeof(devname), "namespace%d.%d", - ndctl_region_get_id(region), paramaters->id); + snprintf(devname, sizeof(devname), "namespace%d.%d", + ndctl_region_get_id(region), paramaters->id); - ndctl_namespace_set_alt_name(ndns, devname); - /* 'uuid' must be set prior to setting size! */ - ndctl_namespace_set_uuid(ndns, paramaters->uuid); - ndctl_namespace_set_size(ndns, paramaters->size); - /* unlike pmem namespaces, blk namespaces have a sector size */ - if (parameters->lbasize) - ndctl_namespace_set_sector_size(ndns, parameters->lbasize); - ndctl_namespace_enable(ndns); -} + ndctl_namespace_set_alt_name(ndns, devname); + /* 'uuid' must be set prior to setting size! */ + ndctl_namespace_set_uuid(ndns, paramaters->uuid); + ndctl_namespace_set_size(ndns, paramaters->size); + /* unlike pmem namespaces, blk namespaces have a sector size */ + if (parameters->lbasize) + ndctl_namespace_set_sector_size(ndns, parameters->lbasize); + ndctl_namespace_enable(ndns); + } Why the Term "namespace"? +^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Why not "volume" for instance? "volume" ran the risk of confusing - ND (libnvdimm subsystem) to a volume manager like device-mapper. + 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: - http://www.nvmexpress.org/specifications/), and NFIT namespaces are - meant to parallel the capabilities and configurability of - NVME-namespaces. + within a NVME controller (see the nvme specification: + http://www.nvmexpress.org/specifications/), and NFIT namespaces are + meant to parallel the capabilities and configurability of + NVME-namespaces. LIBNVDIMM/LIBNDCTL: Block Translation Table "btt" ---------------------------------------------- +------------------------------------------------- A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked block device driver that fronts either the whole block device or a partition of a block device emitted by either a PMEM or BLK NAMESPACE. LIBNVDIMM: btt layout +^^^^^^^^^^^^^^^^^^^^^ + Every region will start out with at least one BTT device which is the seed device. To activate it set the "namespace", "uuid", and "sector_size" attributes and then bind the device to the nd_pmem or -nd_blk driver depending on the region type. +nd_blk driver depending on the region type:: /sys/devices/platform/nfit_test.1/ndbus0/region0/btt0/ |-- namespace @@ -739,10 +810,12 @@ nd_blk driver depending on the region type. `-- uuid LIBNDCTL: btt creation example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Similar to namespaces an idle BTT device is automatically created per region. Each time this "seed" btt device is configured and enabled a new seed is created. Creating a BTT configuration involves two steps of -finding and idle BTT and assigning it to consume a PMEM or BLK namespace. +finding and idle BTT and assigning it to consume a PMEM or BLK namespace:: static struct ndctl_btt *get_idle_btt(struct ndctl_region *region) { @@ -787,29 +860,28 @@ Summary LIBNDCTL Diagram ------------------------ 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" | - | | +---------+ +--------------+ +---------------+ -+-------+ | | +---------+ +--------------+ +---------------+ -| DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" | -+-------+ | | | +---------+ +--------------+ +---------------+ -| DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+ -+-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" | -| DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+ -+-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 | -| DIMM3 <-+ | +--------------+ +----------------------+ -+-------+ | +---------+ +--------------+ +---------------+ - +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" | - | +---------+ | +--------------+ +----------------------+ - | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 | - | +--------------+ +----------------------+ - | +---------+ +--------------+ +---------------+ - +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" | - | +---------+ +--------------+ +---------------+ - | +---------+ +--------------+ +----------------------+ - +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 | - +---------+ +--------------+ +---------------+------+ - - +LIBNDCTL API:: + + +---+ + |CTX| +---------+ +--------------+ +---------------+ + +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" | + | | +---------+ +--------------+ +---------------+ + +-------+ | | +---------+ +--------------+ +---------------+ + | DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" | + +-------+ | | | +---------+ +--------------+ +---------------+ + | DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+ + +-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" | + | DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+ + +-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 | + | DIMM3 <-+ | +--------------+ +----------------------+ + +-------+ | +---------+ +--------------+ +---------------+ + +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" | + | +---------+ | +--------------+ +----------------------+ + | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 | + | +--------------+ +----------------------+ + | +---------+ +--------------+ +---------------+ + +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" | + | +---------+ +--------------+ +---------------+ + | +---------+ +--------------+ +----------------------+ + +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 | + +---------+ +--------------+ +---------------+------+ diff --git a/Documentation/nvdimm/security.txt b/Documentation/driver-api/nvdimm/security.rst index 4c36c05ca98e..ad9dea099b34 100644 --- a/Documentation/nvdimm/security.txt +++ b/Documentation/driver-api/nvdimm/security.rst @@ -1,4 +1,5 @@ -NVDIMM SECURITY +=============== +NVDIMM Security =============== 1. Introduction @@ -138,4 +139,5 @@ This command is only available when the master security is enabled, indicated by the extended security status. [1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf + [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/driver-api/nvmem.rst index fc2fe4b18655..d9d958d5c824 100644 --- a/Documentation/nvmem/nvmem.txt +++ b/Documentation/driver-api/nvmem.rst @@ -1,5 +1,10 @@ - NVMEM SUBSYSTEM - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> +.. SPDX-License-Identifier: GPL-2.0 + +=============== +NVMEM Subsystem +=============== + + Srinivas Kandagatla <srinivas.kandagatla@linaro.org> This document explains the NVMEM Framework along with the APIs provided, and how to use it. @@ -40,54 +45,54 @@ nvmem_device pointer. nvmem_unregister(nvmem) is used to unregister a previously registered provider. -For example, a simple qfprom case: +For example, a simple qfprom case:: -static struct nvmem_config econfig = { + static struct nvmem_config econfig = { .name = "qfprom", .owner = THIS_MODULE, -}; + }; -static int qfprom_probe(struct platform_device *pdev) -{ + static int qfprom_probe(struct platform_device *pdev) + { ... econfig.dev = &pdev->dev; nvmem = nvmem_register(&econfig); ... -} + } It is mandatory that the NVMEM provider has a regmap associated with its struct device. Failure to do would return error code from nvmem_register(). Users of board files can define and register nvmem cells using the -nvmem_cell_table struct: +nvmem_cell_table struct:: -static struct nvmem_cell_info foo_nvmem_cells[] = { + static struct nvmem_cell_info foo_nvmem_cells[] = { { .name = "macaddr", .offset = 0x7f00, .bytes = ETH_ALEN, } -}; + }; -static struct nvmem_cell_table foo_nvmem_cell_table = { + static struct nvmem_cell_table foo_nvmem_cell_table = { .nvmem_name = "i2c-eeprom", .cells = foo_nvmem_cells, .ncells = ARRAY_SIZE(foo_nvmem_cells), -}; + }; -nvmem_add_cell_table(&foo_nvmem_cell_table); + nvmem_add_cell_table(&foo_nvmem_cell_table); Additionally it is possible to create nvmem cell lookup entries and register -them with the nvmem framework from machine code as shown in the example below: +them with the nvmem framework from machine code as shown in the example below:: -static struct nvmem_cell_lookup foo_nvmem_lookup = { + static struct nvmem_cell_lookup foo_nvmem_lookup = { .nvmem_name = "i2c-eeprom", .cell_name = "macaddr", .dev_id = "foo_mac.0", .con_id = "mac-address", -}; + }; -nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); + nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); NVMEM Consumers +++++++++++++++ @@ -99,43 +104,43 @@ read from and to NVMEM. ================================= NVMEM cells are the data entries/fields in the NVMEM. -The NVMEM framework provides 3 APIs to read/write NVMEM cells. +The NVMEM framework provides 3 APIs to read/write NVMEM cells:: -struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name); -struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name); + struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name); + struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name); -void nvmem_cell_put(struct nvmem_cell *cell); -void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); + void nvmem_cell_put(struct nvmem_cell *cell); + void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); -void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len); -int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len); + void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len); + int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len); -*nvmem_cell_get() apis will get a reference to nvmem cell for a given id, +`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id, and nvmem_cell_read/write() can then read or write to the cell. -Once the usage of the cell is finished the consumer should call *nvmem_cell_put() -to free all the allocation memory for the cell. +Once the usage of the cell is finished the consumer should call +`*nvmem_cell_put()` to free all the allocation memory for the cell. 4. Direct NVMEM device based consumer APIs ========================================== In some instances it is necessary to directly read/write the NVMEM. -To facilitate such consumers NVMEM framework provides below apis. +To facilitate such consumers NVMEM framework provides below apis:: -struct nvmem_device *nvmem_device_get(struct device *dev, const char *name); -struct nvmem_device *devm_nvmem_device_get(struct device *dev, + struct nvmem_device *nvmem_device_get(struct device *dev, const char *name); + struct nvmem_device *devm_nvmem_device_get(struct device *dev, const char *name); -void nvmem_device_put(struct nvmem_device *nvmem); -int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset, + void nvmem_device_put(struct nvmem_device *nvmem); + int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset, size_t bytes, void *buf); -int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset, + int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset, size_t bytes, void *buf); -int nvmem_device_cell_read(struct nvmem_device *nvmem, + int nvmem_device_cell_read(struct nvmem_device *nvmem, struct nvmem_cell_info *info, void *buf); -int nvmem_device_cell_write(struct nvmem_device *nvmem, + int nvmem_device_cell_write(struct nvmem_device *nvmem, struct nvmem_cell_info *info, void *buf); Before the consumers can read/write NVMEM directly, it should get hold -of nvmem_controller from one of the *nvmem_device_get() api. +of nvmem_controller from one of the `*nvmem_device_get()` api. The difference between these apis and cell based apis is that these apis always take nvmem_device as parameter. @@ -145,12 +150,12 @@ take nvmem_device as parameter. When a consumer no longer needs the NVMEM, it has to release the reference to the NVMEM it has obtained using the APIs mentioned in the above section. -The NVMEM framework provides 2 APIs to release a reference to the NVMEM. +The NVMEM framework provides 2 APIs to release a reference to the NVMEM:: -void nvmem_cell_put(struct nvmem_cell *cell); -void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); -void nvmem_device_put(struct nvmem_device *nvmem); -void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem); + void nvmem_cell_put(struct nvmem_cell *cell); + void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); + void nvmem_device_put(struct nvmem_device *nvmem); + void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem); Both these APIs are used to release a reference to the NVMEM and devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated @@ -162,20 +167,21 @@ Userspace 6. Userspace binary interface ============================== -Userspace can read/write the raw NVMEM file located at -/sys/bus/nvmem/devices/*/nvmem +Userspace can read/write the raw NVMEM file located at:: + + /sys/bus/nvmem/devices/*/nvmem -ex: +ex:: -hexdump /sys/bus/nvmem/devices/qfprom0/nvmem + hexdump /sys/bus/nvmem/devices/qfprom0/nvmem -0000000 0000 0000 0000 0000 0000 0000 0000 0000 -* -00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 -0000000 0000 0000 0000 0000 0000 0000 0000 0000 -... -* -0001000 + 0000000 0000 0000 0000 0000 0000 0000 0000 0000 + * + 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 + 0000000 0000 0000 0000 0000 0000 0000 0000 0000 + ... + * + 0001000 7. DeviceTree Binding ===================== diff --git a/Documentation/parport-lowlevel.txt b/Documentation/driver-api/parport-lowlevel.rst index 0633d70ffda7..0633d70ffda7 100644 --- a/Documentation/parport-lowlevel.txt +++ b/Documentation/driver-api/parport-lowlevel.rst diff --git a/Documentation/driver-api/phy/index.rst b/Documentation/driver-api/phy/index.rst new file mode 100644 index 000000000000..69ba1216de72 --- /dev/null +++ b/Documentation/driver-api/phy/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Generic PHY Framework +===================== + +.. toctree:: + + phy + samsung-usb2 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/phy.txt b/Documentation/driver-api/phy/phy.rst index 457c3e0f86d6..457c3e0f86d6 100644 --- a/Documentation/phy.txt +++ b/Documentation/driver-api/phy/phy.rst diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/driver-api/phy/samsung-usb2.rst index ed12d437189d..c48c8b9797b9 100644 --- a/Documentation/phy/samsung-usb2.txt +++ b/Documentation/driver-api/phy/samsung-usb2.rst @@ -1,9 +1,9 @@ -.------------------------------------------------------------------------------+ -| Samsung USB 2.0 PHY adaptation layer | -+-----------------------------------------------------------------------------+' +==================================== +Samsung USB 2.0 PHY adaptation layer +==================================== -| 1. Description -+---------------- +1. Description +-------------- The architecture of the USB 2.0 PHY module in Samsung SoCs is similar among many SoCs. In spite of the similarities it proved difficult to @@ -14,8 +14,8 @@ the PHY powering up process had to be altered. This adaptation layer is a compromise between having separate drivers and having a single driver with added support for many special cases. -| 2. Files description -+---------------------- +2. Files description +-------------------- - phy-samsung-usb2.c This is the main file of the adaptation layer. This file contains @@ -32,44 +32,45 @@ with added support for many special cases. driver. In addition it should contain extern declarations for structures that describe particular SoCs. -| 3. Supporting SoCs -+-------------------- +3. Supporting SoCs +------------------ To support a new SoC a new file should be added to the drivers/phy directory. Each SoC's configuration is stored in an instance of the -struct samsung_usb2_phy_config. +struct samsung_usb2_phy_config:: -struct samsung_usb2_phy_config { + struct samsung_usb2_phy_config { const struct samsung_usb2_common_phy *phys; int (*rate_to_clk)(unsigned long, u32 *); unsigned int num_phys; bool has_mode_switch; -}; + }; -The num_phys is the number of phys handled by the driver. *phys is an +The num_phys is the number of phys handled by the driver. `*phys` is an array that contains the configuration for each phy. The has_mode_switch property is a boolean flag that determines whether the SoC has USB host and device on a single pair of pins. If so, a special register has to be modified to change the internal routing of these pins between a USB device or host module. -For example the configuration for Exynos 4210 is following: +For example the configuration for Exynos 4210 is following:: -const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = { + const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = { .has_mode_switch = 0, .num_phys = EXYNOS4210_NUM_PHYS, .phys = exynos4210_phys, .rate_to_clk = exynos4210_rate_to_clk, -} + } + +- `int (*rate_to_clk)(unsigned long, u32 *)` -- int (*rate_to_clk)(unsigned long, u32 *) The rate_to_clk callback is to convert the rate of the clock used as the reference clock for the PHY module to the value that should be written in the hardware register. -The exynos4210_phys configuration array is as follows: +The exynos4210_phys configuration array is as follows:: -static const struct samsung_usb2_common_phy exynos4210_phys[] = { + static const struct samsung_usb2_common_phy exynos4210_phys[] = { { .label = "device", .id = EXYNOS4210_DEVICE, @@ -95,29 +96,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = { .power_off = exynos4210_power_off, }, {}, -}; + }; + +- `int (*power_on)(struct samsung_usb2_phy_instance *);` + `int (*power_off)(struct samsung_usb2_phy_instance *);` -- int (*power_on)(struct samsung_usb2_phy_instance *); -- int (*power_off)(struct samsung_usb2_phy_instance *); These two callbacks are used to power on and power off the phy by modifying appropriate registers. Final change to the driver is adding appropriate compatible value to the phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were -added to the struct of_device_id samsung_usb2_phy_of_match[] array: +added to the struct of_device_id samsung_usb2_phy_of_match[] array:: -#ifdef CONFIG_PHY_EXYNOS4210_USB2 + #ifdef CONFIG_PHY_EXYNOS4210_USB2 { .compatible = "samsung,exynos4210-usb2-phy", .data = &exynos4210_usb2_phy_config, }, -#endif + #endif To add further flexibility to the driver the Kconfig file enables to include support for selected SoCs in the compiled driver. The Kconfig -entry for Exynos 4210 is following: +entry for Exynos 4210 is following:: -config PHY_EXYNOS4210_USB2 + config PHY_EXYNOS4210_USB2 bool "Support for Exynos 4210" depends on PHY_SAMSUNG_USB2 depends on CPU_EXYNOS4210 @@ -128,8 +130,8 @@ config PHY_EXYNOS4210_USB2 phys are available - device, host, HSCI0 and HSCI1. The newly created file that supports the new SoC has to be also added to the -Makefile. In case of Exynos 4210 the added line is following: +Makefile. In case of Exynos 4210 the added line is following:: -obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o + obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o After completing these steps the support for the new SoC should be ready. diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 30835683616a..f66c7b9126ea 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -225,7 +225,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto` flag is clear. For more information about the runtime power management framework, refer to -:file:`Documentation/power/runtime_pm.txt`. +:file:`Documentation/power/runtime_pm.rst`. Calling Drivers to Enter and Leave System Sleep States @@ -728,7 +728,7 @@ it into account in any way. Devices may be defined as IRQ-safe which indicates to the PM core that their runtime PM callbacks may be invoked with disabled interrupts (see -:file:`Documentation/power/runtime_pm.txt` for more information). If an +:file:`Documentation/power/runtime_pm.rst` for more information). If an IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be disallowed, unless the domain itself is defined as IRQ-safe. However, it makes sense to define a PM domain as IRQ-safe only if all the devices in it @@ -795,7 +795,7 @@ so on) and the final state of the device must reflect the "active" runtime PM status in that case. During system-wide resume from a sleep state it's easiest to put devices into -the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`. +the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`. [Refer to that document for more information regarding this particular issue as well as for information on the device runtime power management framework in general.] diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst index 1456d2c32ebd..2d6b99766ee8 100644 --- a/Documentation/driver-api/pps.rst +++ b/Documentation/driver-api/pps.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ====================== PPS - Pulse Per Second diff --git a/Documentation/driver-api/pti_intel_mid.rst b/Documentation/driver-api/pti_intel_mid.rst new file mode 100644 index 000000000000..20f1cff42d5f --- /dev/null +++ b/Documentation/driver-api/pti_intel_mid.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +Intel MID PTI +============= + +The Intel MID PTI project is HW implemented in Intel Atom +system-on-a-chip designs based on the Parallel Trace +Interface for MIPI P1149.7 cJTAG standard. The kernel solution +for this platform involves the following files:: + + ./include/linux/pti.h + ./drivers/.../n_tracesink.h + ./drivers/.../n_tracerouter.c + ./drivers/.../n_tracesink.c + ./drivers/.../pti.c + +pti.c is the driver that enables various debugging features +popular on platforms from certain mobile manufacturers. +n_tracerouter.c and n_tracesink.c allow extra system information to +be collected and routed to the pti driver, such as trace +debugging data from a modem. Although n_tracerouter +and n_tracesink are a part of the complete PTI solution, +these two line disciplines can work separately from +pti.c and route any data stream from one /dev/tty node +to another /dev/tty node via kernel-space. This provides +a stable, reliable connection that will not break unless +the user-space application shuts down (plus avoids +kernel->user->kernel context switch overheads of routing +data). + +An example debugging usage for this driver system: + + * Hook /dev/ttyPTI0 to syslogd. Opening this port will also start + a console device to further capture debugging messages to PTI. + * Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW. + This is where n_tracerouter and n_tracesink are used. + * Hook /dev/pti to a user-level debugging application for writing + to PTI HW. + * `Use mipi_` Kernel Driver API in other device drivers for + debugging to PTI by first requesting a PTI write address via + mipi_request_masterchannel(1). + +Below is example pseudo-code on how a 'privileged' application +can hook up n_tracerouter and n_tracesink to any tty on +a system. 'Privileged' means the application has enough +privileges to successfully manipulate the ldisc drivers +but is not just blindly executing as 'root'. Keep in mind +the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter +and n_tracesink line discpline drivers but is a generic +operation for a program to use a line discpline driver +on a tty port other than the default n_tty:: + + /////////// To hook up n_tracerouter and n_tracesink ///////// + + // Note that n_tracerouter depends on n_tracesink. + #include <errno.h> + #define ONE_TTY "/dev/ttyOne" + #define TWO_TTY "/dev/ttyTwo" + + // needed global to hand onto ldisc connection + static int g_fd_source = -1; + static int g_fd_sink = -1; + + // these two vars used to grab LDISC values from loaded ldisc drivers + // in OS. Look at /proc/tty/ldiscs to get the right numbers from + // the ldiscs loaded in the system. + int source_ldisc_num, sink_ldisc_num = -1; + int retval; + + g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W + g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W + + if (g_fd_source <= 0) || (g_fd_sink <= 0) { + // doubt you'll want to use these exact error lines of code + printf("Error on open(). errno: %d\n",errno); + return errno; + } + + retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num); + if (retval < 0) { + printf("Error on ioctl(). errno: %d\n", errno); + return errno; + } + + retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num); + if (retval < 0) { + printf("Error on ioctl(). errno: %d\n", errno); + return errno; + } + + /////////// To disconnect n_tracerouter and n_tracesink //////// + + // First make sure data through the ldiscs has stopped. + + // Second, disconnect ldiscs. This provides a + // little cleaner shutdown on tty stack. + sink_ldisc_num = 0; + source_ldisc_num = 0; + ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num); + ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num); + + // Three, program closes connection, and cleanup: + close(g_fd_uart); + close(g_fd_gadget); + g_fd_uart = g_fd_gadget = NULL; diff --git a/Documentation/driver-api/ptp.rst b/Documentation/driver-api/ptp.rst index b6e65d66d37a..a15192e32347 100644 --- a/Documentation/driver-api/ptp.rst +++ b/Documentation/driver-api/ptp.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 =========================================== PTP hardware clock infrastructure for Linux diff --git a/Documentation/pwm.txt b/Documentation/driver-api/pwm.rst index ab62f1bb0366..ab62f1bb0366 100644 --- a/Documentation/pwm.txt +++ b/Documentation/driver-api/pwm.rst diff --git a/Documentation/driver-api/rapidio/index.rst b/Documentation/driver-api/rapidio/index.rst new file mode 100644 index 000000000000..a41b4242d16f --- /dev/null +++ b/Documentation/driver-api/rapidio/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +The Linux RapidIO Subsystem +=========================== + +.. toctree:: + :maxdepth: 1 + + rapidio + sysfs + + tsi721 + mport_cdev + rio_cm diff --git a/Documentation/rapidio/mport_cdev.txt b/Documentation/driver-api/rapidio/mport_cdev.rst index a53f786ee2e9..df77a7f7be7d 100644 --- a/Documentation/rapidio/mport_cdev.txt +++ b/Documentation/driver-api/rapidio/mport_cdev.rst @@ -1,13 +1,9 @@ -RapidIO subsystem mport character device driver (rio_mport_cdev.c) ================================================================== - -Version History: ----------------- - 1.0.0 - Initial driver release. - +RapidIO subsystem mport character device driver (rio_mport_cdev.c) ================================================================== -I. Overview +1. Overview +=========== This device driver is the result of collaboration within the RapidIO.org Software Task Group (STG) between Texas Instruments, Freescale, @@ -29,40 +25,41 @@ Using available set of ioctl commands user-space applications can perform following RapidIO bus and subsystem operations: - Reads and writes from/to configuration registers of mport devices - (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL) + (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL) - Reads and writes from/to configuration registers of remote RapidIO devices. This operations are defined as RapidIO Maintenance reads/writes in RIO spec. - (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE) + (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE) - Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET) - Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET) - Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET) - Query capabilities and RapidIO link configuration of mport devices - (RIO_MPORT_GET_PROPERTIES) + (RIO_MPORT_GET_PROPERTIES) - Enable/Disable reporting of RapidIO doorbell events to user-space applications - (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE) + (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE) - Enable/Disable reporting of RIO port-write events to user-space applications - (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE) + (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE) - Query/Control type of events reported through this driver: doorbells, port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK) - Configure/Map mport's outbound requests window(s) for specific size, RapidIO destination ID, hopcount and request type - (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND) + (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND) - Configure/Map mport's inbound requests window(s) for specific size, RapidIO base address and local memory base address - (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND) + (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND) - Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA) - Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER). Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data transfer modes. - Check/Wait for completion of asynchronous DMA data transfer - (RIO_WAIT_FOR_ASYNC) + (RIO_WAIT_FOR_ASYNC) - Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL). This allows implementation of various RapidIO fabric enumeration algorithms as user-space applications while using remaining functionality provided by kernel RapidIO subsystem. -II. Hardware Compatibility +2. Hardware Compatibility +========================= This device driver uses standard interfaces defined by kernel RapidIO subsystem and therefore it can be used with any mport device driver registered by RapidIO @@ -78,29 +75,35 @@ functionality of their platform when planning to use this driver: specific DMA engine support and therefore DMA data transfers mport_cdev driver are not available. -III. Module parameters +3. Module parameters +==================== -- 'dma_timeout' - DMA transfer completion timeout (in msec, default value 3000). +- 'dma_timeout' + - DMA transfer completion timeout (in msec, default value 3000). This parameter set a maximum completion wait time for SYNC mode DMA transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests. -- 'dbg_level' - This parameter allows to control amount of debug information +- 'dbg_level' + - This parameter allows to control amount of debug information generated by this device driver. This parameter is formed by set of bit masks that correspond to the specific functional blocks. For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c' This parameter can be changed dynamically. Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level. -IV. Known problems +4. Known problems +================= None. -V. User-space Applications and API +5. User-space Applications and API +================================== API library and applications that use this device driver are available from RapidIO.org. -VI. TODO List +6. TODO List +============ - Add support for sending/receiving "raw" RapidIO messaging packets. - Add memory mapped DMA data transfers as an option when RapidIO-specific DMA diff --git a/Documentation/rapidio/rapidio.txt b/Documentation/driver-api/rapidio/rapidio.rst index 28fbd877f85a..fb8942d3ba85 100644 --- a/Documentation/rapidio/rapidio.txt +++ b/Documentation/driver-api/rapidio/rapidio.rst @@ -1,6 +1,6 @@ - The Linux RapidIO Subsystem - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============ +Introduction +============ The RapidIO standard is a packet-based fabric interconnect standard designed for use in embedded systems. Development of the RapidIO standard is directed by the @@ -11,7 +11,7 @@ This document describes the basics of the Linux RapidIO subsystem and provides information on its major components. 1 Overview ----------- +========== Because the RapidIO subsystem follows the Linux device model it is integrated into the kernel similarly to other buses by defining RapidIO-specific device and @@ -22,7 +22,7 @@ architecture-specific interfaces that provide support for common RapidIO subsystem operations. 2. Core Components ------------------- +================== A typical RapidIO network is a combination of endpoints and switches. Each of these components is represented in the subsystem by an associated data @@ -30,6 +30,7 @@ structure. The core logical components of the RapidIO subsystem are defined in include/linux/rio.h file. 2.1 Master Port +--------------- A master port (or mport) is a RapidIO interface controller that is local to the processor executing the Linux code. A master port generates and receives RapidIO @@ -46,6 +47,7 @@ includes rio_ops data structure which contains pointers to hardware specific implementations of RapidIO functions. 2.2 Device +---------- A RapidIO device is any endpoint (other than mport) or switch in the network. All devices are presented in the RapidIO subsystem by corresponding rio_dev data @@ -53,6 +55,7 @@ structure. Devices form one global device list and per-network device lists (depending on number of available mports and networks). 2.3 Switch +---------- A RapidIO switch is a special class of device that routes packets between its ports towards their final destination. The packet destination port within a @@ -66,6 +69,7 @@ specific switch drivers that are designed to provide hardware-specific implementation of common switch management routines. 2.4 Network +----------- A RapidIO network is a combination of interconnected endpoint and switch devices. Each RapidIO network known to the system is represented by corresponding rio_net @@ -74,11 +78,13 @@ ports that form the same network. It also contains a pointer to the default master port that is used to communicate with devices within the network. 2.5 Device Drivers +------------------ RapidIO device-specific drivers follow Linux Kernel Driver Model and are intended to support specific RapidIO devices attached to the RapidIO network. 2.6 Subsystem Interfaces +------------------------ RapidIO interconnect specification defines features that may be used to provide one or more common service layers for all participating RapidIO devices. These @@ -90,7 +96,7 @@ subsystem interfaces. This allows to have multiple common services attached to the same device without blocking attachment of a device-specific driver. 3. Subsystem Initialization ---------------------------- +=========================== In order to initialize the RapidIO subsystem, a platform must initialize and register at least one master port within the RapidIO network. To register mport @@ -105,7 +111,7 @@ RapidIO subsystem can be configured to be built as a statically linked or modular component of the kernel (see details below). 4. Enumeration and Discovery ----------------------------- +============================ 4.1 Overview ------------ @@ -168,14 +174,16 @@ on RapidIO subsystem build configuration: (b) If the RapidIO subsystem core is built as a loadable module, in addition to the method shown above, the host destination ID(s) can be specified using traditional methods of passing module parameter "hdid=" during its loading: + - from command line: "modprobe rapidio hdid=-1,7", or - from modprobe configuration file using configuration command "options", like in this example: "options rapidio hdid=-1,7". An example of modprobe configuration file is provided in the section below. - NOTES: +NOTES: (i) if "hdid=" parameter is omitted all available mport will be assigned destination ID = -1; + (ii) the "hdid=" parameter in systems with multiple mports can have destination ID assignments omitted from the end of list (default = -1). @@ -317,8 +325,7 @@ must ensure that they are loaded before the enumeration/discovery starts. This process can be automated by specifying pre- or post- dependencies in the RapidIO-specific modprobe configuration file as shown in the example below. - File /etc/modprobe.d/rapidio.conf: - ---------------------------------- +File /etc/modprobe.d/rapidio.conf:: # Configure RapidIO subsystem modules @@ -335,17 +342,21 @@ RapidIO-specific modprobe configuration file as shown in the example below. -------------------------- -NOTE: In the example above, one of "softdep" commands must be removed or -commented out to keep required module loading sequence. +NOTE: + In the example above, one of "softdep" commands must be removed or + commented out to keep required module loading sequence. -A. References -------------- +5. References +============= [1] RapidIO Trade Association. RapidIO Interconnect Specifications. http://www.rapidio.org. + [2] Rapidio TA. Technology Comparisons. http://www.rapidio.org/education/technology_comparisons/ + [3] RapidIO support for Linux. http://lwn.net/Articles/139118/ + [4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005 http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf diff --git a/Documentation/rapidio/rio_cm.txt b/Documentation/driver-api/rapidio/rio_cm.rst index 27aa401f1126..5294430a7a74 100644 --- a/Documentation/rapidio/rio_cm.txt +++ b/Documentation/driver-api/rapidio/rio_cm.rst @@ -1,13 +1,10 @@ +========================================================================== RapidIO subsystem Channelized Messaging character device driver (rio_cm.c) ========================================================================== -Version History: ----------------- - 1.0.0 - Initial driver release. - -========================================================================== -I. Overview +1. Overview +=========== This device driver is the result of collaboration within the RapidIO.org Software Task Group (STG) between Texas Instruments, Prodrive Technologies, @@ -41,79 +38,98 @@ in /dev directory common for all registered RapidIO mport devices. Following ioctl commands are available to user-space applications: -- RIO_CM_MPORT_GET_LIST : Returns to caller list of local mport devices that +- RIO_CM_MPORT_GET_LIST: + Returns to caller list of local mport devices that support messaging operations (number of entries up to RIO_MAX_MPORTS). Each list entry is combination of mport's index in the system and RapidIO destination ID assigned to the port. -- RIO_CM_EP_GET_LIST_SIZE : Returns number of messaging capable remote endpoints +- RIO_CM_EP_GET_LIST_SIZE: + Returns number of messaging capable remote endpoints in a RapidIO network associated with the specified mport device. -- RIO_CM_EP_GET_LIST : Returns list of RapidIO destination IDs for messaging +- RIO_CM_EP_GET_LIST: + Returns list of RapidIO destination IDs for messaging capable remote endpoints (peers) available in a RapidIO network associated with the specified mport device. -- RIO_CM_CHAN_CREATE : Creates RapidIO message exchange channel data structure +- RIO_CM_CHAN_CREATE: + Creates RapidIO message exchange channel data structure with channel ID assigned automatically or as requested by a caller. -- RIO_CM_CHAN_BIND : Binds the specified channel data structure to the specified +- RIO_CM_CHAN_BIND: + Binds the specified channel data structure to the specified mport device. -- RIO_CM_CHAN_LISTEN : Enables listening for connection requests on the specified +- RIO_CM_CHAN_LISTEN: + Enables listening for connection requests on the specified channel. -- RIO_CM_CHAN_ACCEPT : Accepts a connection request from peer on the specified +- RIO_CM_CHAN_ACCEPT: + Accepts a connection request from peer on the specified channel. If wait timeout for this request is specified by a caller it is a blocking call. If timeout set to 0 this is non-blocking call - ioctl handler checks for a pending connection request and if one is not available exits with -EGAIN error status immediately. -- RIO_CM_CHAN_CONNECT : Sends a connection request to a remote peer/channel. -- RIO_CM_CHAN_SEND : Sends a data message through the specified channel. +- RIO_CM_CHAN_CONNECT: + Sends a connection request to a remote peer/channel. +- RIO_CM_CHAN_SEND: + Sends a data message through the specified channel. The handler for this request assumes that message buffer specified by a caller includes the reserved space for a packet header required by this driver. -- RIO_CM_CHAN_RECEIVE : Receives a data message through a connected channel. +- RIO_CM_CHAN_RECEIVE: + Receives a data message through a connected channel. If the channel does not have an incoming message ready to return this ioctl handler will wait for new message until timeout specified by a caller expires. If timeout value is set to 0, ioctl handler uses a default value defined by MAX_SCHEDULE_TIMEOUT. -- RIO_CM_CHAN_CLOSE : Closes a specified channel and frees associated buffers. +- RIO_CM_CHAN_CLOSE: + Closes a specified channel and frees associated buffers. If the specified channel is in the CONNECTED state, sends close notification to the remote peer. The ioctl command codes and corresponding data structures intended for use by user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'. -II. Hardware Compatibility +2. Hardware Compatibility +========================= This device driver uses standard interfaces defined by kernel RapidIO subsystem and therefore it can be used with any mport device driver registered by RapidIO subsystem with limitations set by available mport HW implementation of messaging mailboxes. -III. Module parameters +3. Module parameters +==================== -- 'dbg_level' - This parameter allows to control amount of debug information +- 'dbg_level' + - This parameter allows to control amount of debug information generated by this device driver. This parameter is formed by set of bit masks that correspond to the specific functional block. For mask definitions see 'drivers/rapidio/devices/rio_cm.c' This parameter can be changed dynamically. Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level. -- 'cmbox' - Number of RapidIO mailbox to use (default value is 1). +- 'cmbox' + - Number of RapidIO mailbox to use (default value is 1). This parameter allows to set messaging mailbox number that will be used within entire RapidIO network. It can be used when default mailbox is used by other device drivers or is not supported by some nodes in the RapidIO network. -- 'chstart' - Start channel number for dynamic assignment. Default value - 256. +- 'chstart' + - Start channel number for dynamic assignment. Default value - 256. Allows to exclude channel numbers below this parameter from dynamic allocation to avoid conflicts with software components that use reserved predefined channel numbers. -IV. Known problems +4. Known problems +================= None. -V. User-space Applications and API Library +5. User-space Applications and API Library +========================================== Messaging API library and applications that use this device driver are available from RapidIO.org. -VI. TODO List +6. TODO List +============ - Add support for system notification messages (reserved channel 0). diff --git a/Documentation/rapidio/sysfs.txt b/Documentation/driver-api/rapidio/sysfs.rst index a1adac888e6e..540f72683496 100644 --- a/Documentation/rapidio/sysfs.txt +++ b/Documentation/driver-api/rapidio/sysfs.rst @@ -1,3 +1,7 @@ +============= +Sysfs entries +============= + The RapidIO sysfs files have moved to: Documentation/ABI/testing/sysfs-bus-rapidio and Documentation/ABI/testing/sysfs-class-rapidio diff --git a/Documentation/rapidio/tsi721.txt b/Documentation/driver-api/rapidio/tsi721.rst index cd2a2935d51d..42aea438cd20 100644 --- a/Documentation/rapidio/tsi721.txt +++ b/Documentation/driver-api/rapidio/tsi721.rst @@ -1,7 +1,9 @@ +========================================================================= RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge. ========================================================================= -I. Overview +1. Overview +=========== This driver implements all currently defined RapidIO mport callback functions. It supports maintenance read and write operations, inbound and outbound RapidIO @@ -17,7 +19,9 @@ into the corresponding message queue. Messaging callbacks are implemented to be fully compatible with RIONET driver (Ethernet over RapidIO messaging services). 1. Module parameters: -- 'dbg_level' - This parameter allows to control amount of debug information + +- 'dbg_level' + - This parameter allows to control amount of debug information generated by this device driver. This parameter is formed by set of This parameter can be changed bit masks that correspond to the specific functional block. @@ -25,37 +29,44 @@ fully compatible with RIONET driver (Ethernet over RapidIO messaging services). This parameter can be changed dynamically. Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level. -- 'dma_desc_per_channel' - This parameter defines number of hardware buffer +- 'dma_desc_per_channel' + - This parameter defines number of hardware buffer descriptors allocated for each registered Tsi721 DMA channel. Its default value is 128. -- 'dma_txqueue_sz' - DMA transactions queue size. Defines number of pending +- 'dma_txqueue_sz' + - DMA transactions queue size. Defines number of pending transaction requests that can be accepted by each DMA channel. Default value is 16. -- 'dma_sel' - DMA channel selection mask. Bitmask that defines which hardware +- 'dma_sel' + - DMA channel selection mask. Bitmask that defines which hardware DMA channels (0 ... 6) will be registered with DmaEngine core. If bit is set to 1, the corresponding DMA channel will be registered. DMA channels not selected by this mask will not be used by this device driver. Default value is 0x7f (use all channels). -- 'pcie_mrrs' - override value for PCIe Maximum Read Request Size (MRRS). +- 'pcie_mrrs' + - override value for PCIe Maximum Read Request Size (MRRS). This parameter gives an ability to override MRRS value set during PCIe configuration process. Tsi721 supports read request sizes up to 4096B. Value for this parameter must be set as defined by PCIe specification: 0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B. Default value is '-1' (= keep platform setting). -- 'mbox_sel' - RIO messaging MBOX selection mask. This is a bitmask that defines +- 'mbox_sel' + - RIO messaging MBOX selection mask. This is a bitmask that defines messaging MBOXes are managed by this device driver. Mask bits 0 - 3 correspond to MBOX0 - MBOX3. MBOX is under driver's control if the corresponding bit is set to '1'. Default value is 0x0f (= all). -II. Known problems +2. Known problems +================= None. -III. DMA Engine Support +3. DMA Engine Support +===================== Tsi721 mport driver supports DMA data transfers between local system memory and remote RapidIO devices. This functionality is implemented according to SLAVE @@ -68,17 +79,21 @@ One BDMA channel is reserved for generation of maintenance read/write requests. If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included, this driver will accept DMA-specific module parameter: - "dma_desc_per_channel" - defines number of hardware buffer descriptors used by + + "dma_desc_per_channel" + - defines number of hardware buffer descriptors used by each BDMA channel of Tsi721 (by default - 128). -IV. Version History +4. Version History - 1.1.0 - DMA operations re-worked to support data scatter/gather lists larger + ===== ==================================================================== + 1.1.0 DMA operations re-worked to support data scatter/gather lists larger than hardware buffer descriptors ring. - 1.0.0 - Initial driver release. + 1.0.0 Initial driver release. + ===== ==================================================================== -V. License ------------------------------------------------ +5. License +=========== Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved. diff --git a/Documentation/rfkill.txt b/Documentation/driver-api/rfkill.rst index 7d3684e81df6..7d3684e81df6 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/driver-api/rfkill.rst diff --git a/Documentation/serial/cyclades_z.rst b/Documentation/driver-api/serial/cyclades_z.rst index 532ff67e2f1c..532ff67e2f1c 100644 --- a/Documentation/serial/cyclades_z.rst +++ b/Documentation/driver-api/serial/cyclades_z.rst diff --git a/Documentation/serial/driver.rst b/Documentation/driver-api/serial/driver.rst index 4537119bf624..31bd4e16fb1f 100644 --- a/Documentation/serial/driver.rst +++ b/Documentation/driver-api/serial/driver.rst @@ -311,7 +311,7 @@ hardware. This call must not sleep set_ldisc(port,termios) - Notifier for discipline change. See Documentation/serial/tty.rst. + Notifier for discipline change. See Documentation/driver-api/serial/tty.rst. Locking: caller holds tty_port->mutex diff --git a/Documentation/serial/index.rst b/Documentation/driver-api/serial/index.rst index d0ba22ea23bf..33ad10d05b26 100644 --- a/Documentation/serial/index.rst +++ b/Documentation/driver-api/serial/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ========================== Support for Serial devices diff --git a/Documentation/serial/moxa-smartio.rst b/Documentation/driver-api/serial/moxa-smartio.rst index 156100f17c3f..156100f17c3f 100644 --- a/Documentation/serial/moxa-smartio.rst +++ b/Documentation/driver-api/serial/moxa-smartio.rst diff --git a/Documentation/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst index f3ad9fd26408..f3ad9fd26408 100644 --- a/Documentation/serial/n_gsm.rst +++ b/Documentation/driver-api/serial/n_gsm.rst diff --git a/Documentation/serial/rocket.rst b/Documentation/driver-api/serial/rocket.rst index 23761eae4282..23761eae4282 100644 --- a/Documentation/serial/rocket.rst +++ b/Documentation/driver-api/serial/rocket.rst diff --git a/Documentation/serial/serial-iso7816.rst b/Documentation/driver-api/serial/serial-iso7816.rst index d990143de0c6..d990143de0c6 100644 --- a/Documentation/serial/serial-iso7816.rst +++ b/Documentation/driver-api/serial/serial-iso7816.rst diff --git a/Documentation/serial/serial-rs485.rst b/Documentation/driver-api/serial/serial-rs485.rst index 6bc824f948f9..6bc824f948f9 100644 --- a/Documentation/serial/serial-rs485.rst +++ b/Documentation/driver-api/serial/serial-rs485.rst diff --git a/Documentation/serial/tty.rst b/Documentation/driver-api/serial/tty.rst index dd972caacf3e..dd972caacf3e 100644 --- a/Documentation/serial/tty.rst +++ b/Documentation/driver-api/serial/tty.rst diff --git a/Documentation/sgi-ioc4.txt b/Documentation/driver-api/sgi-ioc4.rst index 72709222d3c0..72709222d3c0 100644 --- a/Documentation/sgi-ioc4.txt +++ b/Documentation/driver-api/sgi-ioc4.rst diff --git a/Documentation/SM501.txt b/Documentation/driver-api/sm501.rst index 882507453ba4..882507453ba4 100644 --- a/Documentation/SM501.txt +++ b/Documentation/driver-api/sm501.rst diff --git a/Documentation/smsc_ece1099.txt b/Documentation/driver-api/smsc_ece1099.rst index 079277421eaf..079277421eaf 100644 --- a/Documentation/smsc_ece1099.txt +++ b/Documentation/driver-api/smsc_ece1099.rst diff --git a/Documentation/switchtec.txt b/Documentation/driver-api/switchtec.rst index 30d6a64e53f7..7611fdc53e19 100644 --- a/Documentation/switchtec.txt +++ b/Documentation/driver-api/switchtec.rst @@ -97,6 +97,6 @@ the following configuration settings: NT EP BAR 2 will be dynamically configured as a Direct Window, and the configuration file does not need to configure it explicitly. -Please refer to Documentation/ntb.txt in Linux source tree for an overall +Please refer to Documentation/driver-api/ntb.rst in Linux source tree for an overall understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB Hardware Driver in this stack. diff --git a/Documentation/sync_file.txt b/Documentation/driver-api/sync_file.rst index 496fb2c3b3e6..496fb2c3b3e6 100644 --- a/Documentation/sync_file.txt +++ b/Documentation/driver-api/sync_file.rst diff --git a/Documentation/driver-api/usb/power-management.rst b/Documentation/driver-api/usb/power-management.rst index 4a74cf6f2797..2525c3622cae 100644 --- a/Documentation/driver-api/usb/power-management.rst +++ b/Documentation/driver-api/usb/power-management.rst @@ -46,7 +46,7 @@ device is turned off while the system as a whole remains running, we call it a "dynamic suspend" (also known as a "runtime suspend" or "selective suspend"). This document concentrates mostly on how dynamic PM is implemented in the USB subsystem, although system PM is -covered to some extent (see ``Documentation/power/*.txt`` for more +covered to some extent (see ``Documentation/power/*.rst`` for more information about system PM). System PM support is present only if the kernel was built with diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/driver-api/vfio-mediated-device.rst index c3f69bcaf96e..25eb7d5b834b 100644 --- a/Documentation/vfio-mediated-device.txt +++ b/Documentation/driver-api/vfio-mediated-device.rst @@ -408,7 +408,7 @@ card. References ========== -1. See Documentation/vfio.txt for more information on VFIO. +1. See Documentation/driver-api/vfio.rst for more information on VFIO. 2. struct mdev_driver in include/linux/mdev.h 3. struct mdev_parent_ops in include/linux/mdev.h 4. struct vfio_iommu_driver_ops in include/linux/vfio.h diff --git a/Documentation/vfio.txt b/Documentation/driver-api/vfio.rst index f1a4d3c3ba0b..f1a4d3c3ba0b 100644 --- a/Documentation/vfio.txt +++ b/Documentation/driver-api/vfio.rst diff --git a/Documentation/xilinx/eemi.rst b/Documentation/driver-api/xilinx/eemi.rst index 9dcbc6f18d75..9dcbc6f18d75 100644 --- a/Documentation/xilinx/eemi.rst +++ b/Documentation/driver-api/xilinx/eemi.rst diff --git a/Documentation/xilinx/index.rst b/Documentation/driver-api/xilinx/index.rst index 01cc1a0714df..13f7589ed442 100644 --- a/Documentation/xilinx/index.rst +++ b/Documentation/driver-api/xilinx/index.rst @@ -1,4 +1,3 @@ -:orphan: =========== Xilinx FPGA diff --git a/Documentation/xillybus.txt b/Documentation/driver-api/xillybus.rst index 2446ee303c09..2446ee303c09 100644 --- a/Documentation/xillybus.txt +++ b/Documentation/driver-api/xillybus.rst diff --git a/Documentation/zorro.txt b/Documentation/driver-api/zorro.rst index 664072b017e3..664072b017e3 100644 --- a/Documentation/zorro.txt +++ b/Documentation/driver-api/zorro.rst diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst index 92b5639ed07a..8408a8a91b34 100644 --- a/Documentation/fault-injection/index.rst +++ b/Documentation/fault-injection/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 =============== fault-injection diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 1da65b9000de..ebca41785abe 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -187,7 +187,7 @@ the hardware. Thus, in a VGA console:: Assuming the VGA driver can be unloaded, one must first unbind the VGA driver from the console layer before unloading the driver. The VGA driver cannot be unloaded if it is still bound to the console layer. (See -Documentation/console/console.txt for more information). +Documentation/driver-api/console.rst for more information). This is more complicated in the case of the framebuffer console (fbcon), because fbcon is an intermediate layer between the console and the drivers:: @@ -204,7 +204,7 @@ fbcon. Thus, there is no need to explicitly unbind the fbdev drivers from fbcon. So, how do we unbind fbcon from the console? Part of the answer is in -Documentation/console/console.txt. To summarize: +Documentation/driver-api/console.rst. To summarize: Echo a value to the bind file that represents the framebuffer console driver. So assuming vtcon1 represents fbcon, then:: diff --git a/Documentation/fb/index.rst b/Documentation/fb/index.rst index d47313714635..baf02393d8ee 100644 --- a/Documentation/fb/index.rst +++ b/Documentation/fb/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ============ Frame Buffer diff --git a/Documentation/fb/modedb.rst b/Documentation/fb/modedb.rst index 3c2397293977..9c4e3fd39e6d 100644 --- a/Documentation/fb/modedb.rst +++ b/Documentation/fb/modedb.rst @@ -53,6 +53,20 @@ Specifying the option multiple times for different ports is possible, e.g.:: video=LVDS-1:d video=HDMI-1:D +Options can also be passed after the mode, using commas as separator. + + Sample usage: 720x480,rotate=180 - 720x480 mode, rotated by 180 degrees + +Valid options are:: + + - margin_top, margin_bottom, margin_left, margin_right (integer): + Number of pixels in the margins, typically to deal with overscan on TVs + - reflect_x (boolean): Perform an axial symmetry on the X axis + - reflect_y (boolean): Perform an axial symmetry on the Y axis + - rotate (integer): Rotate the initial framebuffer by x + degrees. Valid values are 0, 90, 180 and 270. + + ----------------------------------------------------------------------------- What is the VESA(TM) Coordinated Video Timings (CVT)? diff --git a/Documentation/fb/vesafb.rst b/Documentation/fb/vesafb.rst index 2ed0dfb661cf..6821c87b7893 100644 --- a/Documentation/fb/vesafb.rst +++ b/Documentation/fb/vesafb.rst @@ -30,7 +30,7 @@ How to use it? ============== Switching modes is done using the vga=... boot parameter. Read -Documentation/svga.txt for details. +Documentation/admin-guide/svga.rst for details. You should compile in both vgacon (for text mode) and vesafb (for graphics mode). Which of them takes over the console depends on diff --git a/Documentation/filesystems/coda.txt b/Documentation/filesystems/coda.txt index 61311356025d..545262c167c3 100644 --- a/Documentation/filesystems/coda.txt +++ b/Documentation/filesystems/coda.txt @@ -481,7 +481,10 @@ kernel support. - + struct coda_timespec { + int64_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ + }; struct coda_vattr { enum coda_vtype va_type; /* vnode type (for create) */ @@ -493,9 +496,9 @@ kernel support. long va_fileid; /* file id */ u_quad_t va_size; /* file size in bytes */ long va_blocksize; /* blocksize preferred for i/o */ - struct timespec va_atime; /* time of last access */ - struct timespec va_mtime; /* time of last modification */ - struct timespec va_ctime; /* time file changed */ + struct coda_timespec va_atime; /* time of last access */ + struct coda_timespec va_mtime; /* time of last modification */ + struct coda_timespec va_ctime; /* time file changed */ u_long va_gen; /* generation number of file */ u_long va_flags; /* flags defined for file */ dev_t va_rdev; /* device special file represents */ diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt index 6d2c0d340dea..679729442fd2 100644 --- a/Documentation/filesystems/dax.txt +++ b/Documentation/filesystems/dax.txt @@ -76,7 +76,7 @@ exposure of uninitialized data through mmap. These filesystems may be used for inspiration: - ext2: see Documentation/filesystems/ext2.txt - ext4: see Documentation/filesystems/ext4/ -- xfs: see Documentation/filesystems/xfs.txt +- xfs: see Documentation/admin-guide/xfs.rst Handling Media Errors diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index d2963123eb1c..ae4332464560 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -239,7 +239,7 @@ rdinit=<executable file> A description of the process of mounting the root file system can be found in: - Documentation/early-userspace/README + Documentation/driver-api/early-userspace/early_userspace_support.rst diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index 2813a19389fe..6b7a41cfcaed 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -428,8 +428,19 @@ release it yourself. -- [mandatory] d_alloc_root() is gone, along with a lot of bugs caused by code -misusing it. Replacement: d_make_root(inode). The difference is, -d_make_root() drops the reference to inode if dentry allocation fails. +misusing it. Replacement: d_make_root(inode). On success d_make_root(inode) +allocates and returns a new dentry instantiated with the passed in inode. +On failure NULL is returned and the passed in inode is dropped so the reference +to inode is consumed in all cases and failure handling need not do any cleanup +for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL +and also requires no further error handling. Typical usage is: + + inode = foofs_new_inode(....); + s->s_root = d_make_root(inode); + if (!s->s_root) + /* Nothing needed for the inode cleanup */ + return -ENOMEM; + ... -- [mandatory] diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index d750b6926899..99ca040e3f90 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -486,8 +486,8 @@ 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. -"THPeligible" indicates whether the mapping is eligible for THP pages - 1 if -true, 0 otherwise. +"THPeligible" indicates whether the mapping is eligible for allocating THP +pages - 1 if true, 0 otherwise. It just shows the current status. "VmFlags" field deserves a separate description. This member represents the kernel flags associated with the particular virtual memory area in two letter encoded @@ -1500,7 +1500,7 @@ review the kernel documentation in the directory /usr/src/linux/Documentation. This chapter is heavily based on the documentation included in the pre 2.2 kernels, and became part of it in version 2.2.1 of the Linux kernel. -Please see: Documentation/sysctl/ directory for descriptions of these +Please see: Documentation/admin-guide/sysctl/ directory for descriptions of these entries. ------------------------------------------------------------------------------ diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.txt b/Documentation/filesystems/ramfs-rootfs-initramfs.txt index 79637d227e85..97d42ccaa92d 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.txt +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.txt @@ -105,7 +105,7 @@ All this differs from the old initrd in several ways: - The old initrd file was a gzipped filesystem image (in some file format, such as ext2, that needed a driver built into the kernel), while the new initramfs archive is a gzipped cpio archive (like tar only simpler, - see cpio(1) and Documentation/early-userspace/buffer-format.txt). The + see cpio(1) and Documentation/driver-api/early-userspace/buffer-format.rst). The kernel's cpio extraction code is not only extremely small, it's also __init text and data that can be discarded during the boot process. @@ -159,7 +159,7 @@ One advantage of the configuration file is that root access is not required to set permissions or create device nodes in the new archive. (Note that those two example "file" entries expect to find files named "init.sh" and "busybox" in a directory called "initramfs", under the linux-2.6.* directory. See -Documentation/early-userspace/README for more details.) +Documentation/driver-api/early-userspace/early_userspace_support.rst for more details.) The kernel does not depend on external cpio tools. If you specify a directory instead of a configuration file, the kernel's build infrastructure diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 5b5311f9358d..ddf15b1b0d5a 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -319,7 +319,7 @@ quick way to lookup the sysfs interface for a device from the result of a stat(2) operation. More information can driver-model specific features can be found in -Documentation/driver-model/. +Documentation/driver-api/driver-model/. TODO: Finish this section. diff --git a/Documentation/filesystems/tmpfs.txt b/Documentation/filesystems/tmpfs.txt index cad797a8a39e..5ecbc03e6b2f 100644 --- a/Documentation/filesystems/tmpfs.txt +++ b/Documentation/filesystems/tmpfs.txt @@ -98,7 +98,7 @@ A memory policy with a valid NodeList will be saved, as specified, for use at file creation time. When a task allocates a file in the file system, the mount option memory policy will be applied with a NodeList, if any, modified by the calling task's cpuset constraints -[See Documentation/cgroup-v1/cpusets.rst] and any optional flags, listed +[See Documentation/admin-guide/cgroup-v1/cpusets.rst] and any optional flags, listed below. If the resulting NodeLists is the empty set, the effective memory policy for the file will revert to "default" policy. diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 1252617b520f..0a72b6321f5f 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -316,7 +316,7 @@ specifies the path to the controller. In order to use these GPIOs in Linux we need to translate them to the corresponding Linux GPIO descriptors. There is a standard GPIO API for that and is documented in -Documentation/gpio/. +Documentation/admin-guide/gpio/. In the above example we can get the corresponding two GPIO descriptors with a code like this:: diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst index 2c87d1ea084f..f80f95667ca2 100644 --- a/Documentation/fpga/index.rst +++ b/Documentation/fpga/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ==== fpga diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst index a740e491dfcc..5acdd1842ea2 100644 --- a/Documentation/gpu/amdgpu.rst +++ b/Documentation/gpu/amdgpu.rst @@ -37,10 +37,10 @@ Buffer Objects PRIME Buffer Sharing -------------------- -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c :doc: PRIME Buffer Sharing -.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c :internal: MMU Notifier @@ -70,6 +70,26 @@ Interrupt Handling .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c :internal: +AMDGPU XGMI Support +=================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c + :doc: AMDGPU XGMI Support + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c + :internal: + +AMDGPU RAS debugfs control interface +==================================== + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS debugfs control interface + + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :internal: + + GPU Power/Thermal Controls and Monitoring ========================================= diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index 044a7025477c..4bfb7068e9f7 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -7,6 +7,7 @@ GPU Driver Documentation amdgpu amdgpu-dc i915 + mcde meson pl111 tegra diff --git a/Documentation/gpu/drm-client.rst b/Documentation/gpu/drm-client.rst index 7e672063e7eb..58b5a1d1219d 100644 --- a/Documentation/gpu/drm-client.rst +++ b/Documentation/gpu/drm-client.rst @@ -10,3 +10,6 @@ Kernel clients .. kernel-doc:: drivers/gpu/drm/drm_client.c :export: + +.. kernel-doc:: drivers/gpu/drm/drm_client_modeset.c + :export: diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 14102ae035dc..b327bbc11182 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -181,6 +181,21 @@ Panel Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c :export: +Panel Self Refresh Helper Reference +=================================== + +.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_self_refresh_helper.c + :export: + +HDCP Helper Functions Reference +=============================== + +.. kernel-doc:: drivers/gpu/drm/drm_hdcp.c + :export: + Display Port Helper Functions Reference ======================================= diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 54a696d961a7..c8ebd4f66a6a 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -79,7 +79,6 @@ count for the TTM, which will call your initialization function. See the radeon_ttm.c file for an example of usage. - The Graphics Execution Manager (GEM) ==================================== @@ -380,6 +379,39 @@ GEM CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c :export: +VRAM Helper Function Reference +============================== + +.. kernel-doc:: drivers/gpu/drm/drm_vram_helper_common.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_vram_helper.h + :internal: + +GEM VRAM Helper Functions Reference +----------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_vram_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c + :export: + +VRAM MM Helper Functions Reference +---------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_vram_mm_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_vram_mm_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_vram_mm_helper.c + :export: + VMA Offset Manager ================== diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index c9fd23efd957..94f90521f58c 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -85,16 +85,18 @@ leads to a few additional requirements: - The userspace side must be fully reviewed and tested to the standards of that userspace project. For e.g. mesa this means piglit testcases and review on the mailing list. This is again to ensure that the new interface actually gets the - job done. + job done. The userspace-side reviewer should also provide an Acked-by on the + kernel uAPI patch indicating that they believe the proposed uAPI is sound and + sufficiently documented and validated for userspace's consumption. - The userspace patches must be against the canonical upstream, not some vendor fork. This is to make sure that no one cheats on the review and testing requirements by doing a quick fork. - The kernel patch can only be merged after all the above requirements are met, - but it **must** be merged **before** the userspace patches land. uAPI always flows - from the kernel, doing things the other way round risks divergence of the uAPI - definitions and header files. + but it **must** be merged to either drm-next or drm-misc-next **before** the + userspace patches land. uAPI always flows from the kernel, doing things the + other way round risks divergence of the uAPI definitions and header files. These are fairly steep requirements, but have grown out from years of shared pain and experience with uAPI added hastily, and almost always regretted about @@ -327,3 +329,12 @@ DRM_IOCTL_MODESET_CTL mode setting, since on many devices the vertical blank counter is reset to 0 at some point during modeset. Modern drivers should not call this any more since with kernel mode setting it is a no-op. + +Userspace API Structures +======================== + +.. kernel-doc:: include/uapi/drm/drm_mode.h + :doc: overview + +.. kernel-doc:: include/uapi/drm/drm_mode.h + :internal: diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 055df45596c1..c38ef0dda605 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -61,7 +61,7 @@ Intel GVT-g Host Support(vGPU device model) Workarounds ----------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_workarounds.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c :doc: Hardware workarounds Display Hardware Handling @@ -82,13 +82,13 @@ change. Frontbuffer Tracking -------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c :doc: frontbuffer tracking -.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.h +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.h :internal: -.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c :internal: .. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c @@ -97,10 +97,10 @@ Frontbuffer Tracking Display FIFO Underrun Reporting ------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c :doc: fifo underrun handling -.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c :internal: Plane Configuration @@ -115,10 +115,10 @@ panel self refresh. Atomic Plane Helpers -------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c :doc: atomic plane helpers -.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic_plane.c :internal: Output Probing @@ -132,19 +132,19 @@ probing, so those sections fully apply. Hotplug ------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c :doc: Hotplug -.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_hotplug.c :internal: High Definition Audio --------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c :doc: High Definition Audio over HDMI and Display Port -.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_audio.c :internal: .. kernel-doc:: include/drm/i915_component.h @@ -153,58 +153,58 @@ High Definition Audio Intel HDMI LPE Audio Support ---------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c :doc: LPE Audio integration for HDMI or DP playback -.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lpe_audio.c :internal: Panel Self Refresh PSR (PSR/SRD) -------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c :doc: Panel Self Refresh (PSR/SRD) -.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_psr.c :internal: Frame Buffer Compression (FBC) ------------------------------ -.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c :doc: Frame Buffer Compression (FBC) -.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fbc.c :internal: Display Refresh Rate Switching (DRRS) ------------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :doc: Display Refresh Rate Switching (DRRS) -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_dp_set_drrs_state -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_enable -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_disable -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_invalidate -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_edp_drrs_flush -.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c :functions: intel_dp_drrs_init DPIO ---- -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpio_phy.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpio_phy.c :doc: DPIO CSR firmware support for DMC @@ -219,34 +219,34 @@ CSR firmware support for DMC Video BIOS Table (VBT) ---------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c :doc: Video BIOS Table (VBT) -.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_bios.c :internal: -.. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_vbt_defs.h :internal: Display clocks -------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c :doc: CDCLK / RAWCLK -.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_cdclk.c :internal: Display PLLs ------------ -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c :doc: Display PLLs -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.c :internal: -.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.h +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h :internal: Memory Management and Command Submission @@ -349,7 +349,7 @@ of buffer object caches. Shrinking is used to make main memory available. Note that this is mostly orthogonal to evicting buffer objects, which has the goal to make space in gpu virtual address spaces. -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_shrinker.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_shrinker.c :internal: Batchbuffer Parsing @@ -373,18 +373,15 @@ Batchbuffer Pools User Batchbuffer Execution -------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_execbuffer.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c :doc: User command execution Logical Rings, Logical Ring Contexts and Execlists -------------------------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_lrc.c :doc: Logical Rings, Logical Ring Contexts and Execlists -.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c - :internal: - Global GTT views ---------------- @@ -415,10 +412,10 @@ Hardware Tiling and Swizzling Details Object Tiling IOCTLs -------------------- -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c :internal: -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c :doc: buffer object tiling WOPCM @@ -478,12 +475,6 @@ i915_context_create and i915_context_free .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h :doc: i915_context_create and i915_context_free tracepoints -switch_mm ---------- - -.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h - :doc: switch_mm tracepoint - Perf ==== diff --git a/Documentation/gpu/mcde.rst b/Documentation/gpu/mcde.rst new file mode 100644 index 000000000000..c69e977defda --- /dev/null +++ b/Documentation/gpu/mcde.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================= + drm/mcde ST-Ericsson MCDE Multi-channel display engine +======================================================= + +.. kernel-doc:: drivers/gpu/drm/mcde/mcde_drv.c + :doc: ST-Ericsson MCDE DRM Driver diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 1528ad2d598b..0a49c5a1d9ce 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -10,25 +10,6 @@ graphics subsystem useful as newbie projects. Or for slow rainy days. Subsystem-wide refactorings =========================== -De-midlayer drivers -------------------- - -With the recent ``drm_bus`` cleanup patches for 3.17 it is no longer required -to have a ``drm_bus`` structure set up. Drivers can directly set up the -``drm_device`` structure instead of relying on bus methods in ``drm_usb.c`` -and ``drm_pci.c``. The goal is to get rid of the driver's ``->load`` / -``->unload`` callbacks and open-code the load/unload sequence properly, using -the new two-stage ``drm_device`` setup/teardown. - -Once all existing drivers are converted we can also remove those bus support -files for USB and platform devices. - -All you need is a GPU for a non-converted driver (currently almost all of -them, but also all the virtual ones used by KVM, so everyone qualifies). - -Contact: Daniel Vetter, Thierry Reding, respective driver maintainers - - Remove custom dumb_map_offset implementations --------------------------------------------- @@ -247,6 +228,12 @@ struct drm_gem_object_funcs GEM objects can now have a function table instead of having the callbacks on the DRM driver struct. This is now the preferred way and drivers can be moved over. +DRM_GEM_CMA_VMAP_DRIVER_OPS, DRM_GEM_SHMEM_DRIVER_OPS already support this, but +DRM_GEM_VRAM_DRIVER_PRIME does not yet and needs to be aligned with the previous +two. We also need a 2nd version of the CMA define that doesn't require the +vmapping to be present (different hook for prime importing). Plus this needs to +be rolled out to all drivers using their own implementations, too. + Use DRM_MODESET_LOCK_ALL_* helpers instead of boilerplate --------------------------------------------------------- @@ -300,6 +287,21 @@ it to use drm_mode_hsync() instead. Contact: Sean Paul +drm_fb_helper tasks +------------------- + +- drm_fb_helper_restore_fbdev_mode_unlocked() should call restore_fbdev_mode() + not the _force variant so it can bail out if there is a master. But first + these igt tests need to be fixed: kms_fbcon_fbt@psr and + kms_fbcon_fbt@psr-suspend. + +- The max connector argument for drm_fb_helper_init() and + drm_fb_helper_fbdev_setup() isn't used anymore and can be removed. + +- The helper doesn't keep an array of connectors anymore so these can be + removed: drm_fb_helper_single_add_all_connectors(), + drm_fb_helper_add_one_connector() and drm_fb_helper_remove_one_connector(). + Core refactorings ================= @@ -488,5 +490,20 @@ i915 device_link_add to model the dependency between i915 and snd_had. See https://dri.freedesktop.org/docs/drm/driver-api/device_link.html +Bootsplash +========== + +There is support in place now for writing internal DRM clients making it +possible to pick up the bootsplash work that was rejected because it was written +for fbdev. + +- [v6,8/8] drm/client: Hack: Add bootsplash example + https://patchwork.freedesktop.org/patch/306579/ + +- [RFC PATCH v2 00/13] Kernel based bootsplash + https://lkml.org/lkml/2017/12/13/764 + +Contact: Sam Ravnborg + Outside DRM =========== diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst index af4324902622..737d66dc16a1 100644 --- a/Documentation/hid/index.rst +++ b/Documentation/hid/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ============================= Human Interface Devices (HID) diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst index d5b05d3e54ba..452fc28d8e0b 100644 --- a/Documentation/hwmon/submitting-patches.rst +++ b/Documentation/hwmon/submitting-patches.rst @@ -89,7 +89,7 @@ increase the chances of your change being accepted. console. Excessive logging can seriously affect system performance. * Use devres functions whenever possible to allocate resources. For rationale - and supported functions, please see Documentation/driver-model/devres.rst. + and supported functions, please see Documentation/driver-api/driver-model/devres.rst. If a function is not supported by devres, consider using devm_add_action(). * If the driver has a detect function, make sure it is silent. Debug messages diff --git a/Documentation/hwspinlock.txt b/Documentation/hwspinlock.txt index ed640a278185..6f03713b7003 100644 --- a/Documentation/hwspinlock.txt +++ b/Documentation/hwspinlock.txt @@ -136,6 +136,39 @@ The function will never sleep. :: + int hwspin_lock_timeout_raw(struct hwspinlock *hwlock, unsigned int timeout); + +Lock a previously-assigned hwspinlock with a timeout limit (specified in +msecs). If the hwspinlock is already taken, the function will busy loop +waiting for it to be released, but give up when the timeout elapses. + +Caution: User must protect the routine of getting hardware lock with mutex +or spinlock to avoid dead-lock, that will let user can do some time-consuming +or sleepable operations under the hardware lock. + +Returns 0 when successful and an appropriate error code otherwise (most +notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs). + +The function will never sleep. + +:: + + int hwspin_lock_timeout_in_atomic(struct hwspinlock *hwlock, unsigned int to); + +Lock a previously-assigned hwspinlock with a timeout limit (specified in +msecs). If the hwspinlock is already taken, the function will busy loop +waiting for it to be released, but give up when the timeout elapses. + +This function shall be called only from an atomic context and the timeout +value shall not exceed a few msecs. + +Returns 0 when successful and an appropriate error code otherwise (most +notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs). + +The function will never sleep. + +:: + int hwspin_trylock(struct hwspinlock *hwlock); @@ -186,6 +219,34 @@ The function will never sleep. :: + int hwspin_trylock_raw(struct hwspinlock *hwlock); + +Attempt to lock a previously-assigned hwspinlock, but immediately fail if +it is already taken. + +Caution: User must protect the routine of getting hardware lock with mutex +or spinlock to avoid dead-lock, that will let user can do some time-consuming +or sleepable operations under the hardware lock. + +Returns 0 on success and an appropriate error code otherwise (most +notably -EBUSY if the hwspinlock was already taken). +The function will never sleep. + +:: + + int hwspin_trylock_in_atomic(struct hwspinlock *hwlock); + +Attempt to lock a previously-assigned hwspinlock, but immediately fail if +it is already taken. + +This function shall be called only from an atomic context. + +Returns 0 on success and an appropriate error code otherwise (most +notably -EBUSY if the hwspinlock was already taken). +The function will never sleep. + +:: + void hwspin_unlock(struct hwspinlock *hwlock); Unlock a previously-locked hwspinlock. Always succeed, and can be called @@ -222,6 +283,26 @@ the given flags. This function will never sleep. :: + void hwspin_unlock_raw(struct hwspinlock *hwlock); + +Unlock a previously-locked hwspinlock. + +The caller should **never** unlock an hwspinlock which is already unlocked. +Doing so is considered a bug (there is no protection against this). +This function will never sleep. + +:: + + void hwspin_unlock_in_atomic(struct hwspinlock *hwlock); + +Unlock a previously-locked hwspinlock. + +The caller should **never** unlock an hwspinlock which is already unlocked. +Doing so is considered a bug (there is no protection against this). +This function will never sleep. + +:: + int hwspin_lock_get_id(struct hwspinlock *hwlock); Retrieve id number of a given hwspinlock. This is needed when an diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index ee9984f35868..f426c13c63a9 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -37,6 +37,8 @@ Supported adapters: * Intel Cedar Fork (PCH) * Intel Ice Lake (PCH) * Intel Comet Lake (PCH) + * Intel Elkhart Lake (PCH) + * Intel Tiger Lake (PCH) Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller @@ -58,6 +60,7 @@ question doesn't work as intended for whatever reason. Bit values: 0x02 disable the block buffer 0x08 disable the I2C block read functionality 0x10 don't use interrupts + 0x20 disable SMBus Host Notify Description @@ -88,7 +91,7 @@ SMBus controller. Process Call Support -------------------- -Not supported. +Block process call is supported on the 82801EB (ICH5) and later chips. I2C Block Read Support @@ -118,16 +121,15 @@ BIOS to enable it, it means it has been hidden by the BIOS code. Asus is well known for first doing this on their P4B motherboard, and many other boards after that. Some vendor machines are affected as well. -The first thing to try is the "i2c_ec" ACPI driver. It could be that the +The first thing to try is the "i2c-scmi" ACPI driver. It could be that the SMBus was hidden on purpose because it'll be driven by ACPI. If the -i2c_ec driver works for you, just forget about the i2c-i801 driver and -don't try to unhide the ICH SMBus. Even if i2c_ec doesn't work, you +i2c-scmi driver works for you, just forget about the i2c-i801 driver and +don't try to unhide the ICH SMBus. Even if i2c-scmi doesn't work, you better make sure that the SMBus isn't used by the ACPI code. Try loading -the "fan" and "thermal" drivers, and check in /proc/acpi/fan and -/proc/acpi/thermal_zone. If you find anything there, it's likely that -the ACPI is accessing the SMBus and it's safer not to unhide it. Only -once you are certain that ACPI isn't using the SMBus, you can attempt -to unhide it. +the "fan" and "thermal" drivers, and check in /sys/class/thermal. If you +find a thermal zone with type "acpitz", it's likely that the ACPI is +accessing the SMBus and it's safer not to unhide it. Only once you are +certain that ACPI isn't using the SMBus, you can attempt to unhide it. In order to unhide the SMBus, we need to change the value of a PCI register before the kernel enumerates the PCI devices. This is done in diff --git a/Documentation/ia64/aliasing.txt b/Documentation/ia64/aliasing.rst index 5a4dea6abebd..a08b36aba015 100644 --- a/Documentation/ia64/aliasing.txt +++ b/Documentation/ia64/aliasing.rst @@ -1,20 +1,25 @@ - MEMORY ATTRIBUTE ALIASING ON IA-64 +================================== +Memory Attribute Aliasing on IA-64 +================================== - Bjorn Helgaas - <bjorn.helgaas@hp.com> - May 4, 2006 +Bjorn Helgaas <bjorn.helgaas@hp.com> +May 4, 2006 -MEMORY ATTRIBUTES + +Memory Attributes +================= Itanium supports several attributes for virtual memory references. The attribute is part of the virtual translation, i.e., it is contained in the TLB entry. The ones of most interest to the Linux kernel are: - WB Write-back (cacheable) + == ====================== + WB Write-back (cacheable) UC Uncacheable WC Write-coalescing + == ====================== System memory typically uses the WB attribute. The UC attribute is used for memory-mapped I/O devices. The WC attribute is uncacheable @@ -29,7 +34,8 @@ MEMORY ATTRIBUTES support either WB or UC access to main memory, while others support only WB access. -MEMORY MAP +Memory Map +========== Platform firmware describes the physical memory map and the supported attributes for each region. At boot-time, the kernel uses @@ -55,7 +61,8 @@ MEMORY MAP The efi_memmap table is preserved unmodified because the original boot-time information is required for kexec. -KERNEL IDENTITY MAPPINGS +Kernel Identify Mappings +======================== Linux/ia64 identity mappings are done with large pages, currently either 16MB or 64MB, referred to as "granules." Cacheable mappings @@ -74,17 +81,20 @@ KERNEL IDENTITY MAPPINGS are only partially populated, or populated with a combination of UC and WB regions. -USER MAPPINGS +User Mappings +============= User mappings are typically done with 16K or 64K pages. The smaller page size allows more flexibility because only 16K or 64K has to be homogeneous with respect to memory attributes. -POTENTIAL ATTRIBUTE ALIASING CASES +Potential Attribute Aliasing Cases +================================== There are several ways the kernel creates new mappings: - mmap of /dev/mem +mmap of /dev/mem +---------------- This uses remap_pfn_range(), which creates user mappings. These mappings may be either WB or UC. If the region being mapped @@ -98,7 +108,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES Since the EFI memory map does not describe MMIO on some machines, this should use an uncacheable mapping as a fallback. - mmap of /sys/class/pci_bus/.../legacy_mem +mmap of /sys/class/pci_bus/.../legacy_mem +----------------------------------------- This is very similar to mmap of /dev/mem, except that legacy_mem only allows mmap of the one megabyte "legacy MMIO" area for a @@ -112,9 +123,10 @@ POTENTIAL ATTRIBUTE ALIASING CASES The /dev/mem mmap constraints apply. - mmap of /proc/bus/pci/.../??.? +mmap of /proc/bus/pci/.../??.? +------------------------------ - This is an MMIO mmap of PCI functions, which additionally may or + This is an MMIO mmap of PCI functions, which additionally may or may not be requested as using the WC attribute. If WC is requested, and the region in kern_memmap is either WC @@ -124,7 +136,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES Otherwise, the user mapping must use the same attribute as the kernel mapping. - read/write of /dev/mem +read/write of /dev/mem +---------------------- This uses copy_from_user(), which implicitly uses a kernel identity mapping. This is obviously safe for things in @@ -138,7 +151,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES eight-byte accesses, and the copy_from_user() path doesn't allow any control over the access size, so this would be dangerous. - ioremap() +ioremap() +--------- This returns a mapping for use inside the kernel. @@ -155,9 +169,11 @@ POTENTIAL ATTRIBUTE ALIASING CASES Failing all of the above, we have to fall back to a UC mapping. -PAST PROBLEM CASES +Past Problem Cases +================== - mmap of various MMIO regions from /dev/mem by "X" on Intel platforms +mmap of various MMIO regions from /dev/mem by "X" on Intel platforms +-------------------------------------------------------------------- The EFI memory map may not report these MMIO regions. @@ -166,12 +182,16 @@ PAST PROBLEM CASES succeed. It may create either WB or UC user mappings, depending on whether the region is in kern_memmap or the EFI memory map. - mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled +mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled +---------------------------------------------------------------------- The EFI memory map reports the following attributes: + + =============== ======= ================== 0x00000-0x9FFFF WB only 0xA0000-0xBFFFF UC only (VGA frame buffer) 0xC0000-0xFFFFF WB only + =============== ======= ================== This mmap is done with user pages, not kernel identity mappings, so it is safe to use WB mappings. @@ -182,7 +202,8 @@ PAST PROBLEM CASES never generate an uncacheable reference to the WB-only areas unless the driver explicitly touches them. - mmap of 0x0-0xFFFFF legacy_mem by "X" +mmap of 0x0-0xFFFFF legacy_mem by "X" +------------------------------------- If the EFI memory map reports that the entire range supports the same attributes, we can allow the mmap (and we will prefer WB if @@ -197,15 +218,18 @@ PAST PROBLEM CASES that doesn't report the VGA frame buffer at all), we should fail the mmap and force the user to map just the specific region of interest. - mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled +mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled +------------------------------------------------------------------------ + + The EFI memory map reports the following attributes:: - The EFI memory map reports the following attributes: 0x00000-0xFFFFF WB only (no VGA MMIO hole) This is a special case of the previous case, and the mmap should fail for the same reason as above. - read of /sys/devices/.../rom +read of /sys/devices/.../rom +---------------------------- For VGA devices, this may cause an ioremap() of 0xC0000. This used to be done with a UC mapping, because the VGA frame buffer @@ -215,7 +239,8 @@ PAST PROBLEM CASES We should use WB page table mappings to avoid covering the VGA frame buffer. -NOTES +Notes +===== [1] SDM rev 2.2, vol 2, sec 4.4.1. [2] SDM rev 2.2, vol 2, sec 4.4.6. diff --git a/Documentation/ia64/efirtc.txt b/Documentation/ia64/efirtc.rst index 057e6bebda8f..2f7ff5026308 100644 --- a/Documentation/ia64/efirtc.txt +++ b/Documentation/ia64/efirtc.rst @@ -1,12 +1,16 @@ +========================== EFI Real Time Clock driver -------------------------------- +========================== + S. Eranian <eranian@hpl.hp.com> + March 2000 -I/ Introduction +1. Introduction +=============== This document describes the efirtc.c driver has provided for -the IA-64 platform. +the IA-64 platform. The purpose of this driver is to supply an API for kernel and user applications to get access to the Time Service offered by EFI version 0.92. @@ -16,112 +20,124 @@ SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this driver. We describe those calls as well the design of the driver in the following sections. -II/ Design Decisions +2. Design Decisions +=================== -The original ideas was to provide a very simple driver to get access to, -at first, the time of day service. This is required in order to access, in a -portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock +The original ideas was to provide a very simple driver to get access to, +at first, the time of day service. This is required in order to access, in a +portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock to initialize the system view of the time during boot. Because we wanted to minimize the impact on existing user-level apps using the CMOS clock, we decided to expose an API that was very similar to the one -used today with the legacy RTC driver (driver/char/rtc.c). However, because +used today with the legacy RTC driver (driver/char/rtc.c). However, because EFI provides a simpler services, not all ioctl() are available. Also -new ioctl()s have been introduced for things that EFI provides but not the +new ioctl()s have been introduced for things that EFI provides but not the legacy. EFI uses a slightly different way of representing the time, noticeably the reference date is different. Year is the using the full 4-digit format. The Epoch is January 1st 1998. For backward compatibility reasons we don't -expose this new way of representing time. Instead we use something very +expose this new way of representing time. Instead we use something very similar to the struct tm, i.e. struct rtc_time, as used by hwclock. One of the reasons for doing it this way is to allow for EFI to still evolve without necessarily impacting any of the user applications. The decoupling enables flexibility and permits writing wrapper code is ncase things change. The driver exposes two interfaces, one via the device file and a set of -ioctl()s. The other is read-only via the /proc filesystem. +ioctl()s. The other is read-only via the /proc filesystem. As of today we don't offer a /proc/sys interface. To allow for a uniform interface between the legacy RTC and EFI time service, -we have created the include/linux/rtc.h header file to contain only the -"public" API of the two drivers. The specifics of the legacy RTC are still +we have created the include/linux/rtc.h header file to contain only the +"public" API of the two drivers. The specifics of the legacy RTC are still in include/linux/mc146818rtc.h. - -III/ Time of day service + +3. Time of day service +====================== The part of the driver gives access to the time of day service of EFI. Two ioctl()s, compatible with the legacy RTC calls: - Read the CMOS clock: ioctl(d, RTC_RD_TIME, &rtc); + Read the CMOS clock:: + + ioctl(d, RTC_RD_TIME, &rtc); + + Write the CMOS clock:: - Write the CMOS clock: ioctl(d, RTC_SET_TIME, &rtc); + ioctl(d, RTC_SET_TIME, &rtc); The rtc is a pointer to a data structure defined in rtc.h which is close -to a struct tm: - -struct rtc_time { - int tm_sec; - int tm_min; - int tm_hour; - int tm_mday; - int tm_mon; - int tm_year; - int tm_wday; - int tm_yday; - int tm_isdst; -}; +to a struct tm:: + + struct rtc_time { + int tm_sec; + int tm_min; + int tm_hour; + int tm_mday; + int tm_mon; + int tm_year; + int tm_wday; + int tm_yday; + int tm_isdst; + }; The driver takes care of converting back an forth between the EFI time and this format. Those two ioctl()s can be exercised with the hwclock command: -For reading: -# /sbin/hwclock --show -Mon Mar 6 15:32:32 2000 -0.910248 seconds +For reading:: -For setting: -# /sbin/hwclock --systohc + # /sbin/hwclock --show + Mon Mar 6 15:32:32 2000 -0.910248 seconds + +For setting:: + + # /sbin/hwclock --systohc Root privileges are required to be able to set the time of day. -IV/ Wakeup Alarm service +4. Wakeup Alarm service +======================= EFI provides an API by which one can program when a machine should wakeup, i.e. reboot. This is very different from the alarm provided by the legacy RTC which is some kind of interval timer alarm. For this reason we don't use the same ioctl()s to get access to the service. Instead we have -introduced 2 news ioctl()s to the interface of an RTC. +introduced 2 news ioctl()s to the interface of an RTC. We have added 2 new ioctl()s that are specific to the EFI driver: - Read the current state of the alarm - ioctl(d, RTC_WKLAM_RD, &wkt) + Read the current state of the alarm:: + + ioctl(d, RTC_WKLAM_RD, &wkt) + + Set the alarm or change its status:: + + ioctl(d, RTC_WKALM_SET, &wkt) - Set the alarm or change its status - ioctl(d, RTC_WKALM_SET, &wkt) +The wkt structure encapsulates a struct rtc_time + 2 extra fields to get +status information:: -The wkt structure encapsulates a struct rtc_time + 2 extra fields to get -status information: - -struct rtc_wkalrm { + struct rtc_wkalrm { - unsigned char enabled; /* =1 if alarm is enabled */ - unsigned char pending; /* =1 if alarm is pending */ + unsigned char enabled; /* =1 if alarm is enabled */ + unsigned char pending; /* =1 if alarm is pending */ - struct rtc_time time; -} + struct rtc_time time; + } As of today, none of the existing user-level apps supports this feature. -However writing such a program should be hard by simply using those two -ioctl(). +However writing such a program should be hard by simply using those two +ioctl(). Root privileges are required to be able to set the alarm. -V/ References. +5. References +============= Checkout the following Web site for more information on EFI: diff --git a/Documentation/ia64/err_inject.txt b/Documentation/ia64/err_inject.rst index 9f651c181429..900f71e93a29 100644 --- a/Documentation/ia64/err_inject.txt +++ b/Documentation/ia64/err_inject.rst @@ -1,4 +1,4 @@ - +======================================== IPF Machine Check (MC) error inject tool ======================================== @@ -32,94 +32,94 @@ Errata: Itanium 2 Processors Specification Update lists some errata against the pal_mc_error_inject PAL procedure. The following err.conf has been tested on latest Montecito PAL. -err.conf: +err.conf:: -#This is configuration file for err_inject_tool. -#The format of the each line is: -#cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer -#where -# cpu: logical cpu number the error will be inject in. -# loop: times the error will be injected. -# interval: In second. every so often one error is injected. -# err_type_info, err_struct_info: PAL parameters. -# -#Note: All values are hex w/o or w/ 0x prefix. + #This is configuration file for err_inject_tool. + #The format of the each line is: + #cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer + #where + # cpu: logical cpu number the error will be inject in. + # loop: times the error will be injected. + # interval: In second. every so often one error is injected. + # err_type_info, err_struct_info: PAL parameters. + # + #Note: All values are hex w/o or w/ 0x prefix. -#On cpu2, inject only total 0x10 errors, interval 5 seconds -#corrected, data cache, hier-2, physical addr(assigned by tool code). -#working on Montecito latest PAL. -2, 10, 5, 4101, 95 + #On cpu2, inject only total 0x10 errors, interval 5 seconds + #corrected, data cache, hier-2, physical addr(assigned by tool code). + #working on Montecito latest PAL. + 2, 10, 5, 4101, 95 -#On cpu4, inject and consume total 0x10 errors, interval 5 seconds -#corrected, data cache, hier-2, physical addr(assigned by tool code). -#working on Montecito latest PAL. -4, 10, 5, 4109, 95 + #On cpu4, inject and consume total 0x10 errors, interval 5 seconds + #corrected, data cache, hier-2, physical addr(assigned by tool code). + #working on Montecito latest PAL. + 4, 10, 5, 4109, 95 -#On cpu15, inject and consume total 0x10 errors, interval 5 seconds -#recoverable, DTR0, hier-2. -#working on Montecito latest PAL. -0xf, 0x10, 5, 4249, 15 + #On cpu15, inject and consume total 0x10 errors, interval 5 seconds + #recoverable, DTR0, hier-2. + #working on Montecito latest PAL. + 0xf, 0x10, 5, 4249, 15 The sample application source code: -err_injection_tool.c: - -/* - * 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, GOOD TITLE or - * NON INFRINGEMENT. See the GNU General Public License for more - * details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * Copyright (C) 2006 Intel Co - * Fenghua Yu <fenghua.yu@intel.com> - * - */ -#include <sys/types.h> -#include <sys/stat.h> -#include <fcntl.h> -#include <stdio.h> -#include <sched.h> -#include <unistd.h> -#include <stdlib.h> -#include <stdarg.h> -#include <string.h> -#include <errno.h> -#include <time.h> -#include <sys/ipc.h> -#include <sys/sem.h> -#include <sys/wait.h> -#include <sys/mman.h> -#include <sys/shm.h> - -#define MAX_FN_SIZE 256 -#define MAX_BUF_SIZE 256 -#define DATA_BUF_SIZE 256 -#define NR_CPUS 512 -#define MAX_TASK_NUM 2048 -#define MIN_INTERVAL 5 // seconds -#define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte. -#define PARA_FIELD_NUM 5 -#define MASK_SIZE (NR_CPUS/64) -#define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/" - -int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask); - -int verbose; -#define vbprintf if (verbose) printf - -int log_info(int cpu, const char *fmt, ...) -{ +err_injection_tool.c:: + + /* + * 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, GOOD TITLE or + * NON INFRINGEMENT. See the GNU General Public License for more + * details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + * + * Copyright (C) 2006 Intel Co + * Fenghua Yu <fenghua.yu@intel.com> + * + */ + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <stdio.h> + #include <sched.h> + #include <unistd.h> + #include <stdlib.h> + #include <stdarg.h> + #include <string.h> + #include <errno.h> + #include <time.h> + #include <sys/ipc.h> + #include <sys/sem.h> + #include <sys/wait.h> + #include <sys/mman.h> + #include <sys/shm.h> + + #define MAX_FN_SIZE 256 + #define MAX_BUF_SIZE 256 + #define DATA_BUF_SIZE 256 + #define NR_CPUS 512 + #define MAX_TASK_NUM 2048 + #define MIN_INTERVAL 5 // seconds + #define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte. + #define PARA_FIELD_NUM 5 + #define MASK_SIZE (NR_CPUS/64) + #define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/" + + int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask); + + int verbose; + #define vbprintf if (verbose) printf + + int log_info(int cpu, const char *fmt, ...) + { FILE *log; char fn[MAX_FN_SIZE]; char buf[MAX_BUF_SIZE]; @@ -142,12 +142,12 @@ int log_info(int cpu, const char *fmt, ...) fclose(log); return 0; -} + } -typedef unsigned long u64; -typedef unsigned int u32; + typedef unsigned long u64; + typedef unsigned int u32; -typedef union err_type_info_u { + typedef union err_type_info_u { struct { u64 mode : 3, /* 0-2 */ err_inj : 3, /* 3-5 */ @@ -157,9 +157,9 @@ typedef union err_type_info_u { reserved : 48; /* 16-63 */ } err_type_info_u; u64 err_type_info; -} err_type_info_t; + } err_type_info_t; -typedef union err_struct_info_u { + typedef union err_struct_info_u { struct { u64 siv : 1, /* 0 */ c_t : 2, /* 1-2 */ @@ -197,9 +197,9 @@ typedef union err_struct_info_u { u64 reserved; } err_struct_info_bus_processor_interconnect; u64 err_struct_info; -} err_struct_info_t; + } err_struct_info_t; -typedef union err_data_buffer_u { + typedef union err_data_buffer_u { struct { u64 trigger_addr; /* 0-63 */ u64 inj_addr; /* 64-127 */ @@ -221,9 +221,9 @@ typedef union err_data_buffer_u { u64 reserved; /* 0-63 */ } err_data_buffer_bus_processor_interconnect; u64 err_data_buffer[ERR_DATA_BUFFER_SIZE]; -} err_data_buffer_t; + } err_data_buffer_t; -typedef union capabilities_u { + typedef union capabilities_u { struct { u64 i : 1, d : 1, @@ -276,9 +276,9 @@ typedef union capabilities_u { struct { u64 reserved; } capabilities_bus_processor_interconnect; -} capabilities_t; + } capabilities_t; -typedef struct resources_s { + typedef struct resources_s { u64 ibr0 : 1, ibr2 : 1, ibr4 : 1, @@ -288,24 +288,24 @@ typedef struct resources_s { dbr4 : 1, dbr6 : 1, reserved : 48; -} resources_t; + } resources_t; -long get_page_size(void) -{ + long get_page_size(void) + { long page_size=sysconf(_SC_PAGESIZE); return page_size; -} + } -#define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size()) -#define SHM_SIZE (2*PAGE_SIZE*NR_CPUS) -#define SHM_VA 0x2000000100000000 + #define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size()) + #define SHM_SIZE (2*PAGE_SIZE*NR_CPUS) + #define SHM_VA 0x2000000100000000 -int shmid; -void *shmaddr; + int shmid; + void *shmaddr; -int create_shm(void) -{ + int create_shm(void) + { key_t key; char fn[MAX_FN_SIZE]; @@ -343,34 +343,34 @@ int create_shm(void) mlock(shmaddr, SHM_SIZE); return 0; -} + } -int free_shm() -{ + int free_shm() + { munlock(shmaddr, SHM_SIZE); - shmdt(shmaddr); + shmdt(shmaddr); semctl(shmid, 0, IPC_RMID); return 0; -} + } -#ifdef _SEM_SEMUN_UNDEFINED -union semun -{ + #ifdef _SEM_SEMUN_UNDEFINED + union semun + { int val; struct semid_ds *buf; unsigned short int *array; struct seminfo *__buf; -}; -#endif + }; + #endif -u32 mode=1; /* 1: physical mode; 2: virtual mode. */ -int one_lock=1; -key_t key[NR_CPUS]; -int semid[NR_CPUS]; + u32 mode=1; /* 1: physical mode; 2: virtual mode. */ + int one_lock=1; + key_t key[NR_CPUS]; + int semid[NR_CPUS]; -int create_sem(int cpu) -{ + int create_sem(int cpu) + { union semun arg; char fn[MAX_FN_SIZE]; int sid; @@ -407,37 +407,37 @@ int create_sem(int cpu) } return 0; -} + } -static int lock(int cpu) -{ + static int lock(int cpu) + { struct sembuf lock; lock.sem_num = cpu; lock.sem_op = 1; semop(semid[cpu], &lock, 1); - return 0; -} + return 0; + } -static int unlock(int cpu) -{ + static int unlock(int cpu) + { struct sembuf unlock; unlock.sem_num = cpu; unlock.sem_op = -1; semop(semid[cpu], &unlock, 1); - return 0; -} + return 0; + } -void free_sem(int cpu) -{ + void free_sem(int cpu) + { semctl(semid[cpu], 0, IPC_RMID); -} + } -int wr_multi(char *fn, unsigned long *data, int size) -{ + int wr_multi(char *fn, unsigned long *data, int size) + { int fd; char buf[MAX_BUF_SIZE]; int ret; @@ -459,15 +459,15 @@ int wr_multi(char *fn, unsigned long *data, int size) ret=write(fd, buf, sizeof(buf)); close(fd); return ret; -} + } -int wr(char *fn, unsigned long data) -{ + int wr(char *fn, unsigned long data) + { return wr_multi(fn, &data, 1); -} + } -int rd(char *fn, unsigned long *data) -{ + int rd(char *fn, unsigned long *data) + { int fd; char buf[MAX_BUF_SIZE]; @@ -480,10 +480,10 @@ int rd(char *fn, unsigned long *data) *data=strtoul(buf, NULL, 16); close(fd); return 0; -} + } -int rd_status(char *path, int *status) -{ + int rd_status(char *path, int *status) + { char fn[MAX_FN_SIZE]; sprintf(fn, "%s/status", path); if (rd(fn, (u64*)status)<0) { @@ -492,10 +492,10 @@ int rd_status(char *path, int *status) } return 0; -} + } -int rd_capabilities(char *path, u64 *capabilities) -{ + int rd_capabilities(char *path, u64 *capabilities) + { char fn[MAX_FN_SIZE]; sprintf(fn, "%s/capabilities", path); if (rd(fn, capabilities)<0) { @@ -504,10 +504,10 @@ int rd_capabilities(char *path, u64 *capabilities) } return 0; -} + } -int rd_all(char *path) -{ + int rd_all(char *path) + { unsigned long err_type_info, err_struct_info, err_data_buffer; int status; unsigned long capabilities, resources; @@ -556,11 +556,11 @@ int rd_all(char *path) printf("resources=%lx\n", resources); return 0; -} + } -int query_capabilities(char *path, err_type_info_t err_type_info, + int query_capabilities(char *path, err_type_info_t err_type_info, u64 *capabilities) -{ + { char fn[MAX_FN_SIZE]; err_struct_info_t err_struct_info; err_data_buffer_t err_data_buffer; @@ -583,10 +583,10 @@ int query_capabilities(char *path, err_type_info_t err_type_info, return -1; return 0; -} + } -int query_all_capabilities() -{ + int query_all_capabilities() + { int status; err_type_info_t err_type_info; int err_sev, err_struct, struct_hier; @@ -629,12 +629,12 @@ int query_all_capabilities() } return 0; -} + } -int err_inject(int cpu, char *path, err_type_info_t err_type_info, + int err_inject(int cpu, char *path, err_type_info_t err_type_info, err_struct_info_t err_struct_info, err_data_buffer_t err_data_buffer) -{ + { int status; char fn[MAX_FN_SIZE]; @@ -667,13 +667,13 @@ int err_inject(int cpu, char *path, err_type_info_t err_type_info, } return status; -} + } -static int construct_data_buf(char *path, err_type_info_t err_type_info, + static int construct_data_buf(char *path, err_type_info_t err_type_info, err_struct_info_t err_struct_info, err_data_buffer_t *err_data_buffer, void *va1) -{ + { char fn[MAX_FN_SIZE]; u64 virt_addr=0, phys_addr=0; @@ -710,22 +710,22 @@ static int construct_data_buf(char *path, err_type_info_t err_type_info, } return 0; -} + } -typedef struct { + typedef struct { u64 cpu; u64 loop; u64 interval; u64 err_type_info; u64 err_struct_info; u64 err_data_buffer[ERR_DATA_BUFFER_SIZE]; -} parameters_t; + } parameters_t; -parameters_t line_para; -int para; + parameters_t line_para; + int para; -static int empty_data_buffer(u64 *err_data_buffer) -{ + static int empty_data_buffer(u64 *err_data_buffer) + { int empty=1; int i; @@ -734,10 +734,10 @@ static int empty_data_buffer(u64 *err_data_buffer) empty=0; return empty; -} + } -int err_inj() -{ + int err_inj() + { err_type_info_t err_type_info; err_struct_info_t err_struct_info; err_data_buffer_t err_data_buffer; @@ -951,10 +951,10 @@ int err_inj() printf("All done.\n"); return 0; -} + } -void help() -{ + void help() + { printf("err_inject_tool:\n"); printf("\t-q: query all capabilities. default: off\n"); printf("\t-m: procedure mode. 1: physical 2: virtual. default: 1\n"); @@ -977,10 +977,10 @@ void help() printf("The tool will take err.conf file as "); printf("input to inject single or multiple errors "); printf("on one or multiple cpus in parallel.\n"); -} + } -int main(int argc, char **argv) -{ + int main(int argc, char **argv) + { char c; int do_err_inj=0; int do_query_all=0; @@ -1031,7 +1031,7 @@ int main(int argc, char **argv) if (count!=PARA_FIELD_NUM+3) { line_para.err_data_buffer[0]=-1, line_para.err_data_buffer[1]=-1, - line_para.err_data_buffer[2]=-1; + line_para.err_data_buffer[2]=-1; count=sscanf(optarg, "%lx, %lx, %lx, %lx, %lx\n", &line_para.cpu, &line_para.loop, @@ -1064,5 +1064,4 @@ int main(int argc, char **argv) help(); return 0; -} - + } diff --git a/Documentation/ia64/fsys.txt b/Documentation/ia64/fsys.rst index 59dd689d9b86..a702d2cc94b6 100644 --- a/Documentation/ia64/fsys.txt +++ b/Documentation/ia64/fsys.rst @@ -1,9 +1,9 @@ --*-Mode: outline-*- - - Light-weight System Calls for IA-64 - ----------------------------------- +=================================== +Light-weight System Calls for IA-64 +=================================== Started: 13-Jan-2003 + Last update: 27-Sep-2003 David Mosberger-Tang @@ -52,12 +52,13 @@ privilege level is at level 0, this means that fsys-mode requires some care (see below). -* How to tell fsys-mode +How to tell fsys-mode +===================== Linux operates in fsys-mode when (a) the privilege level is 0 (most privileged) and (b) the stacks have NOT been switched to kernel memory yet. For convenience, the header file <asm-ia64/ptrace.h> provides -three macros: +three macros:: user_mode(regs) user_stack(task,regs) @@ -70,11 +71,12 @@ to by "regs" was executing in user mode (privilege level 3). user_stack() returns TRUE if the state pointed to by "regs" was executing on the user-level stack(s). Finally, fsys_mode() returns TRUE if the CPU state pointed to by "regs" was executing in fsys-mode. -The fsys_mode() macro is equivalent to the expression: +The fsys_mode() macro is equivalent to the expression:: !user_mode(regs) && user_stack(task,regs) -* How to write an fsyscall handler +How to write an fsyscall handler +================================ The file arch/ia64/kernel/fsys.S contains a table of fsyscall-handlers (fsyscall_table). This table contains one entry for each system call. @@ -87,66 +89,72 @@ of the getpid() system call. The entry and exit-state of an fsyscall handler is as follows: -** Machine state on entry to fsyscall handler: - - - r10 = 0 - - r11 = saved ar.pfs (a user-level value) - - r15 = system call number - - r16 = "current" task pointer (in normal kernel-mode, this is in r13) - - r32-r39 = system call arguments - - b6 = return address (a user-level value) - - ar.pfs = previous frame-state (a user-level value) - - PSR.be = cleared to zero (i.e., little-endian byte order is in effect) - - all other registers may contain values passed in from user-mode - -** Required machine state on exit to fsyscall handler: - - - r11 = saved ar.pfs (as passed into the fsyscall handler) - - r15 = system call number (as passed into the fsyscall handler) - - r32-r39 = system call arguments (as passed into the fsyscall handler) - - b6 = return address (as passed into the fsyscall handler) - - ar.pfs = previous frame-state (as passed into the fsyscall handler) +Machine state on entry to fsyscall handler +------------------------------------------ + + ========= =============================================================== + r10 0 + r11 saved ar.pfs (a user-level value) + r15 system call number + r16 "current" task pointer (in normal kernel-mode, this is in r13) + r32-r39 system call arguments + b6 return address (a user-level value) + ar.pfs previous frame-state (a user-level value) + PSR.be cleared to zero (i.e., little-endian byte order is in effect) + - all other registers may contain values passed in from user-mode + ========= =============================================================== + +Required machine state on exit to fsyscall handler +-------------------------------------------------- + + ========= =========================================================== + r11 saved ar.pfs (as passed into the fsyscall handler) + r15 system call number (as passed into the fsyscall handler) + r32-r39 system call arguments (as passed into the fsyscall handler) + b6 return address (as passed into the fsyscall handler) + ar.pfs previous frame-state (as passed into the fsyscall handler) + ========= =========================================================== Fsyscall handlers can execute with very little overhead, but with that speed comes a set of restrictions: - o Fsyscall-handlers MUST check for any pending work in the flags + * Fsyscall-handlers MUST check for any pending work in the flags member of the thread-info structure and if any of the TIF_ALLWORK_MASK flags are set, the handler needs to fall back on doing a full system call (by calling fsys_fallback_syscall). - o Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11, + * Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11, r15, b6, and ar.pfs) because they will be needed in case of a system call restart. Of course, all "preserved" registers also must be preserved, in accordance to the normal calling conventions. - o Fsyscall-handlers MUST check argument registers for containing a + * Fsyscall-handlers MUST check argument registers for containing a NaT value before using them in any way that could trigger a NaT-consumption fault. If a system call argument is found to contain a NaT value, an fsyscall-handler may return immediately with r8=EINVAL, r10=-1. - o Fsyscall-handlers MUST NOT use the "alloc" instruction or perform + * Fsyscall-handlers MUST NOT use the "alloc" instruction or perform any other operation that would trigger mandatory RSE (register-stack engine) traffic. - o Fsyscall-handlers MUST NOT write to any stacked registers because + * Fsyscall-handlers MUST NOT write to any stacked registers because it is not safe to assume that user-level called a handler with the proper number of arguments. - o Fsyscall-handlers need to be careful when accessing per-CPU variables: + * Fsyscall-handlers need to be careful when accessing per-CPU variables: unless proper safe-guards are taken (e.g., interruptions are avoided), execution may be pre-empted and resumed on another CPU at any given time. - o Fsyscall-handlers must be careful not to leak sensitive kernel' + * Fsyscall-handlers must be careful not to leak sensitive kernel' information back to user-level. In particular, before returning to user-level, care needs to be taken to clear any scratch registers that could contain sensitive information (note that the current task pointer is not considered sensitive: it's already exposed through ar.k6). - o Fsyscall-handlers MUST NOT access user-memory without first + * Fsyscall-handlers MUST NOT access user-memory without first validating access-permission (this can be done typically via probe.r.fault and/or probe.w.fault) and without guarding against memory access exceptions (this can be done with the EX() macros @@ -162,7 +170,8 @@ fast system call execution (while fully preserving system call semantics), but there is also a lot of flexibility in handling more complicated cases. -* Signal handling +Signal handling +=============== The delivery of (asynchronous) signals must be delayed until fsys-mode is exited. This is accomplished with the help of the lower-privilege @@ -173,7 +182,8 @@ PSR.lp and returns immediately. When fsys-mode is exited via the occur. The trap handler clears PSR.lp again and returns immediately. The kernel exit path then checks for and delivers any pending signals. -* PSR Handling +PSR Handling +============ The "epc" instruction doesn't change the contents of PSR at all. This is in contrast to a regular interruption, which clears almost all @@ -181,6 +191,7 @@ bits. Because of that, some care needs to be taken to ensure things work as expected. The following discussion describes how each PSR bit is handled. +======= ======================================================================= PSR.be Cleared when entering fsys-mode. A srlz.d instruction is used to ensure the CPU is in little-endian mode before the first load/store instruction is executed. PSR.be is normally NOT @@ -202,7 +213,8 @@ PSR.pp Unchanged. PSR.di Unchanged. PSR.si Unchanged. PSR.db Unchanged. The kernel prevents user-level from setting a hardware - breakpoint that triggers at any privilege level other than 3 (user-mode). + breakpoint that triggers at any privilege level other than + 3 (user-mode). PSR.lp Unchanged. PSR.tb Lazy redirect. If a taken-branch trap occurs while in fsys-mode, the trap-handler modifies the saved machine state @@ -235,47 +247,52 @@ PSR.ed Unchanged. Note: This bit could only have an effect if an fsys-mode PSR.bn Unchanged. Note: fsys-mode handlers may clear the bit, if needed. Doing so requires clearing PSR.i and PSR.ic as well. PSR.ia Unchanged. Note: the ia64 linux kernel never sets this bit. +======= ======================================================================= -* Using fast system calls +Using fast system calls +======================= To use fast system calls, userspace applications need simply call __kernel_syscall_via_epc(). For example -- example fgettimeofday() call -- + -- fgettimeofday.S -- -#include <asm/asmmacro.h> +:: + + #include <asm/asmmacro.h> -GLOBAL_ENTRY(fgettimeofday) -.prologue -.save ar.pfs, r11 -mov r11 = ar.pfs -.body + GLOBAL_ENTRY(fgettimeofday) + .prologue + .save ar.pfs, r11 + mov r11 = ar.pfs + .body -mov r2 = 0xa000000000020660;; // gate address - // found by inspection of System.map for the + mov r2 = 0xa000000000020660;; // gate address + // found by inspection of System.map for the // __kernel_syscall_via_epc() function. See // below for how to do this for real. -mov b7 = r2 -mov r15 = 1087 // gettimeofday syscall -;; -br.call.sptk.many b6 = b7 -;; + mov b7 = r2 + mov r15 = 1087 // gettimeofday syscall + ;; + br.call.sptk.many b6 = b7 + ;; -.restore sp + .restore sp -mov ar.pfs = r11 -br.ret.sptk.many rp;; // return to caller -END(fgettimeofday) + mov ar.pfs = r11 + br.ret.sptk.many rp;; // return to caller + END(fgettimeofday) -- end fgettimeofday.S -- In reality, getting the gate address is accomplished by two extra values passed via the ELF auxiliary vector (include/asm-ia64/elf.h) - o AT_SYSINFO : is the address of __kernel_syscall_via_epc() - o AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO + * AT_SYSINFO : is the address of __kernel_syscall_via_epc() + * AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO The ELF DSO is a pre-linked library that is mapped in by the kernel at the gate page. It is a proper ELF shared object so, with a dynamic diff --git a/Documentation/ia64/README b/Documentation/ia64/ia64.rst index aa17f2154cba..b725019a9492 100644 --- a/Documentation/ia64/README +++ b/Documentation/ia64/ia64.rst @@ -1,43 +1,49 @@ - Linux kernel release 2.4.xx for the IA-64 Platform +=========================================== +Linux kernel release for the IA-64 Platform +=========================================== - These are the release notes for Linux version 2.4 for IA-64 + These are the release notes for Linux since version 2.4 for IA-64 platform. This document provides information specific to IA-64 ONLY, to get additional information about the Linux kernel also read the original Linux README provided with the kernel. -INSTALLING the kernel: +Installing the Kernel +===================== - IA-64 kernel installation is the same as the other platforms, see original README for details. -SOFTWARE REQUIREMENTS +Software Requirements +===================== Compiling and running this kernel requires an IA-64 compliant GCC compiler. And various software packages also compiled with an IA-64 compliant GCC compiler. -CONFIGURING the kernel: +Configuring the Kernel +====================== Configuration is the same, see original README for details. -COMPILING the kernel: +Compiling the Kernel: - Compiling this kernel doesn't differ from other platform so read the original README for details BUT make sure you have an IA-64 compliant GCC compiler. -IA-64 SPECIFICS +IA-64 Specifics +=============== - General issues: - o Hardly any performance tuning has been done. Obvious targets + * Hardly any performance tuning has been done. Obvious targets include the library routines (IP checksum, etc.). Less obvious targets include making sure we don't flush the TLB needlessly, etc. - o SMP locks cleanup/optimization + * SMP locks cleanup/optimization - o IA32 support. Currently experimental. It mostly works. + * IA32 support. Currently experimental. It mostly works. diff --git a/Documentation/ia64/index.rst b/Documentation/ia64/index.rst new file mode 100644 index 000000000000..0436e1034115 --- /dev/null +++ b/Documentation/ia64/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +IA-64 Architecture +================== + +.. toctree:: + :maxdepth: 1 + + ia64 + aliasing + efirtc + err_inject + fsys + irq-redir + mca + serial + xen diff --git a/Documentation/ia64/IRQ-redir.txt b/Documentation/ia64/irq-redir.rst index f7bd72261283..39bf94484a15 100644 --- a/Documentation/ia64/IRQ-redir.txt +++ b/Documentation/ia64/irq-redir.rst @@ -1,6 +1,8 @@ +============================== IRQ affinity on IA64 platforms ------------------------------- - 07.01.2002, Erich Focht <efocht@ess.nec.de> +============================== + +07.01.2002, Erich Focht <efocht@ess.nec.de> By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be @@ -12,22 +14,27 @@ IRQ target is one particular CPU and cannot be a mask of several CPUs. Only the first non-zero bit is taken into account. -Usage examples: +Usage examples +============== The target CPU has to be specified as a hexadecimal CPU mask. The first non-zero bit is the selected CPU. This format has been kept for compatibility reasons with i386. Set the delivery mode of interrupt 41 to fixed and route the -interrupts to CPU #3 (logical CPU number) (2^3=0x08): +interrupts to CPU #3 (logical CPU number) (2^3=0x08):: + echo "8" >/proc/irq/41/smp_affinity Set the default route for IRQ number 41 to CPU 6 in lowest priority -delivery mode (redirectable): +delivery mode (redirectable):: + echo "r 40" >/proc/irq/41/smp_affinity -The output of the command +The output of the command:: + cat /proc/irq/IRQ#/smp_affinity + gives the target CPU mask for the specified interrupt vector. If the CPU mask is preceded by the character "r", the interrupt is redirectable (i.e. lowest priority mode routing is used), otherwise its route is @@ -35,7 +42,8 @@ fixed. -Initialization and default behavior: +Initialization and default behavior +=================================== If the platform features IRQ redirection (info provided by SAL) all IO-SAPIC interrupts are initialized with CPU#0 as their default target @@ -43,9 +51,11 @@ and the routing is the so called "lowest priority mode" (actually fixed SAPIC mode with hint). The XTP chipset registers are used as hints for the IRQ routing. Currently in Linux XTP registers can have three values: + - minimal for an idle task, - normal if any other task runs, - maximal if the CPU is going to be switched off. + The IRQ is routed to the CPU with lowest XTP register value, the search begins at the default CPU. Therefore most of the interrupts will be handled by CPU #0. @@ -53,12 +63,14 @@ will be handled by CPU #0. If the platform doesn't feature interrupt redirection IOSAPIC fixed routing is used. The target CPUs are distributed in a round robin manner. IRQs will be routed only to the selected target CPUs. Check -with +with:: + cat /proc/interrupts -Comments: +Comments +======== On large (multi-node) systems it is recommended to route the IRQs to the node to which the corresponding device is connected. @@ -66,4 +78,3 @@ For systems like the NEC AzusA we get IRQ node-affinity for free. This is because usually the chipsets on each node redirect the interrupts only to their own CPUs (as they cannot see the XTP registers on the other nodes). - diff --git a/Documentation/ia64/mca.txt b/Documentation/ia64/mca.rst index f097c60cba1b..08270bba44a4 100644 --- a/Documentation/ia64/mca.txt +++ b/Documentation/ia64/mca.rst @@ -1,5 +1,8 @@ -An ad-hoc collection of notes on IA64 MCA and INIT processing. Feel -free to update it with notes about any area that is not clear. +============================================================= +An ad-hoc collection of notes on IA64 MCA and INIT processing +============================================================= + +Feel free to update it with notes about any area that is not clear. --- @@ -82,7 +85,8 @@ if we have a choice here. own stack as running on that cpu. Then a recursive error gets a trace of the failing handler's "task". -[1] My (Keith Owens) original design called for ia64 to separate its +[1] + My (Keith Owens) original design called for ia64 to separate its struct task and the kernel stacks. Then the MCA/INIT data would be chained stacks like i386 interrupt stacks. But that required radical surgery on the rest of ia64, plus extra hard wired TLB diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.rst index a63d2c54329b..1de70c305a79 100644 --- a/Documentation/ia64/serial.txt +++ b/Documentation/ia64/serial.rst @@ -1,4 +1,9 @@ -SERIAL DEVICE NAMING +============== +Serial Devices +============== + +Serial Device Naming +==================== As of 2.6.10, serial devices on ia64 are named based on the order of ACPI and PCI enumeration. The first device in the @@ -30,17 +35,21 @@ SERIAL DEVICE NAMING (described in the ACPI namespace) plus an MP[2] (a PCI device) has these ports: - pre-2.6.10 pre-2.6.10 - MMIO (EFI console (EFI console - address on builtin) on MP port) 2.6.10 - ========== ========== ========== ====== + ========== ========== ============ ============ ======= + Type MMIO pre-2.6.10 pre-2.6.10 2.6.10+ + address + (EFI console (EFI console + on builtin) on MP port) + ========== ========== ============ ============ ======= builtin 0xff5e0000 ttyS0 ttyS1 ttyS0 MP UPS 0xf8031000 ttyS1 ttyS2 ttyS1 MP Console 0xf8030000 ttyS2 ttyS0 ttyS2 MP 2 0xf8030010 ttyS3 ttyS3 ttyS3 MP 3 0xf8030038 ttyS4 ttyS4 ttyS4 + ========== ========== ============ ============ ======= -CONSOLE SELECTION +Console Selection +================= EFI knows what your console devices are, but it doesn't tell the kernel quite enough to actually locate them. The DIG64 HCDP @@ -67,7 +76,8 @@ CONSOLE SELECTION entries in /etc/inittab (for getty) and /etc/securetty (to allow root login). -EARLY SERIAL CONSOLE +Early Serial Console +==================== The kernel can't start using a serial console until it knows where the device lives. Normally this happens when the driver enumerates @@ -80,7 +90,8 @@ EARLY SERIAL CONSOLE or if the EFI console path contains only a UART device and the firmware supplies an HCDP. -TROUBLESHOOTING SERIAL CONSOLE PROBLEMS +Troubleshooting Serial Console Problems +======================================= No kernel output after elilo prints "Uncompressing Linux... done": @@ -133,19 +144,22 @@ TROUBLESHOOTING SERIAL CONSOLE PROBLEMS -[1] http://www.dig64.org/specifications/agreement +[1] + http://www.dig64.org/specifications/agreement The table was originally defined as the "HCDP" for "Headless Console/Debug Port." The current version is the "PCDP" for "Primary Console and Debug Port Devices." -[2] The HP MP (management processor) is a PCI device that provides +[2] + The HP MP (management processor) is a PCI device that provides several UARTs. One of the UARTs is often used as a console; the EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart". The external connection is usually a 25-pin connector, and a special dongle converts that to three 9-pin connectors, one of which is labelled "Console." -[3] EFI console devices are configured using the EFI Boot Manager +[3] + EFI console devices are configured using the EFI Boot Manager "Boot option maintenance" menu. You may have to interrupt the boot sequence to use this menu, and you will have to reset the box after changing console configuration. diff --git a/Documentation/ia64/xen.rst b/Documentation/ia64/xen.rst new file mode 100644 index 000000000000..831339c74441 --- /dev/null +++ b/Documentation/ia64/xen.rst @@ -0,0 +1,206 @@ +******************************************************** +Recipe for getting/building/running Xen/ia64 with pv_ops +******************************************************** +This recipe describes how to get xen-ia64 source and build it, +and run domU with pv_ops. + +Requirements +============ + + - python + - mercurial + it (aka "hg") is an open-source source code + management software. See the below. + http://www.selenic.com/mercurial/wiki/ + - git + - bridge-utils + +Getting and Building Xen and Dom0 +================================= + + My environment is: + + - Machine : Tiger4 + - Domain0 OS : RHEL5 + - DomainU OS : RHEL5 + + 1. Download source:: + + # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg + # cd xen-unstable.hg + # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg + + 2. # make world + + 3. # make install-tools + + 4. copy kernels and xen:: + + # cp xen/xen.gz /boot/efi/efi/redhat/ + # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \ + /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen + + 5. make initrd for Dom0/DomU:: + + # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \ + O=$(pwd)/build-linux-2.6.18-xen_ia64 + # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \ + 2.6.18.8-xen --builtin mptspi --builtin mptbase \ + --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \ + --builtin ehci-hcd + +Making a disk image for guest OS +================================ + + 1. make file:: + + # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0 + # mke2fs -F -j /root/rhel5.img + # mount -o loop /root/rhel5.img /mnt + # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt + # mkdir /mnt/{root,proc,sys,home,tmp} + + Note: You may miss some device files. If so, please create them + with mknod. Or you can use tar instead of cp. + + 2. modify DomU's fstab:: + + # vi /mnt/etc/fstab + /dev/xvda1 / ext3 defaults 1 1 + none /dev/pts devpts gid=5,mode=620 0 0 + none /dev/shm tmpfs defaults 0 0 + none /proc proc defaults 0 0 + none /sys sysfs defaults 0 0 + + 3. modify inittab + + set runlevel to 3 to avoid X trying to start:: + + # vi /mnt/etc/inittab + id:3:initdefault: + + Start a getty on the hvc0 console:: + + X0:2345:respawn:/sbin/mingetty hvc0 + + tty1-6 mingetty can be commented out + + 4. add hvc0 into /etc/securetty:: + + # vi /mnt/etc/securetty (add hvc0) + + 5. umount:: + + # umount /mnt + +FYI, virt-manager can also make a disk image for guest OS. +It's GUI tools and easy to make it. + +Boot Xen & Domain0 +================== + + 1. replace elilo + elilo of RHEL5 can boot Xen and Dom0. + If you use old elilo (e.g RHEL4), please download from the below + http://elilo.sourceforge.net/cgi-bin/blosxom + and copy into /boot/efi/efi/redhat/:: + + # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi + + 2. modify elilo.conf (like the below):: + + # vi /boot/efi/efi/redhat/elilo.conf + prompt + timeout=20 + default=xen + relocatable + + image=vmlinuz-2.6.18.8-xen + label=xen + vmm=xen.gz + initrd=initrd-2.6.18.8-xen.img + read-only + append=" -- rhgb root=/dev/sda2" + +The append options before "--" are for xen hypervisor, +the options after "--" are for dom0. + +FYI, your machine may need console options like +"com1=19200,8n1 console=vga,com1". For example, +append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \ +console=ttyS0 root=/dev/sda2" + +Getting and Building domU with pv_ops +===================================== + + 1. get pv_ops tree:: + + # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/ + + 2. git branch (if necessary):: + + # cd linux-2.6-xen-ia64/ + # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19 + + Note: + The current branch is xen-ia64-domu-minimal-2008may19. + But you would find the new branch. You can see with + "git branch -r" to get the branch lists. + + http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/ + + is also available. + + The tree is based on + + git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test) + + 3. copy .config for pv_ops of domU:: + + # cp arch/ia64/configs/xen_domu_wip_defconfig .config + + 4. make kernel with pv_ops:: + + # make oldconfig + # make + + 5. install the kernel and initrd:: + + # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU + # make modules_install + # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \ + 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \ + --builtin mptbase --builtin mptscsih --builtin uhci-hcd \ + --builtin ohci-hcd --builtin ehci-hcd + +Boot DomainU with pv_ops +======================== + + 1. make config of DomU:: + + # vi /etc/xen/rhel5 + kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU" + ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img" + vcpus = 1 + memory = 512 + name = "rhel5" + disk = [ 'file:/root/rhel5.img,xvda1,w' ] + root = "/dev/xvda1 ro" + extra= "rhgb console=hvc0" + + 2. After boot xen and dom0, start xend:: + + # /etc/init.d/xend start + + ( In the debugging case, `# XEND_DEBUG=1 xend trace_start` ) + + 3. start domU:: + + # xm create -c rhel5 + +Reference +========= +- Wiki of Xen/IA64 upstream merge + http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge + +Written by Akio Takebe <takebe_akio@jp.fujitsu.com> on 28 May 2008 diff --git a/Documentation/ia64/xen.txt b/Documentation/ia64/xen.txt deleted file mode 100644 index a12c74ce2773..000000000000 --- a/Documentation/ia64/xen.txt +++ /dev/null @@ -1,183 +0,0 @@ - Recipe for getting/building/running Xen/ia64 with pv_ops - -------------------------------------------------------- - -This recipe describes how to get xen-ia64 source and build it, -and run domU with pv_ops. - -============ -Requirements -============ - - - python - - mercurial - it (aka "hg") is an open-source source code - management software. See the below. - http://www.selenic.com/mercurial/wiki/ - - git - - bridge-utils - -================================= -Getting and Building Xen and Dom0 -================================= - - My environment is; - Machine : Tiger4 - Domain0 OS : RHEL5 - DomainU OS : RHEL5 - - 1. Download source - # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg - # cd xen-unstable.hg - # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg - - 2. # make world - - 3. # make install-tools - - 4. copy kernels and xen - # cp xen/xen.gz /boot/efi/efi/redhat/ - # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \ - /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen - - 5. make initrd for Dom0/DomU - # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \ - O=$(pwd)/build-linux-2.6.18-xen_ia64 - # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \ - 2.6.18.8-xen --builtin mptspi --builtin mptbase \ - --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \ - --builtin ehci-hcd - -================================ -Making a disk image for guest OS -================================ - - 1. make file - # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0 - # mke2fs -F -j /root/rhel5.img - # mount -o loop /root/rhel5.img /mnt - # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt - # mkdir /mnt/{root,proc,sys,home,tmp} - - Note: You may miss some device files. If so, please create them - with mknod. Or you can use tar instead of cp. - - 2. modify DomU's fstab - # vi /mnt/etc/fstab - /dev/xvda1 / ext3 defaults 1 1 - none /dev/pts devpts gid=5,mode=620 0 0 - none /dev/shm tmpfs defaults 0 0 - none /proc proc defaults 0 0 - none /sys sysfs defaults 0 0 - - 3. modify inittab - set runlevel to 3 to avoid X trying to start - # vi /mnt/etc/inittab - id:3:initdefault: - Start a getty on the hvc0 console - X0:2345:respawn:/sbin/mingetty hvc0 - tty1-6 mingetty can be commented out - - 4. add hvc0 into /etc/securetty - # vi /mnt/etc/securetty (add hvc0) - - 5. umount - # umount /mnt - -FYI, virt-manager can also make a disk image for guest OS. -It's GUI tools and easy to make it. - -================== -Boot Xen & Domain0 -================== - - 1. replace elilo - elilo of RHEL5 can boot Xen and Dom0. - If you use old elilo (e.g RHEL4), please download from the below - http://elilo.sourceforge.net/cgi-bin/blosxom - and copy into /boot/efi/efi/redhat/ - # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi - - 2. modify elilo.conf (like the below) - # vi /boot/efi/efi/redhat/elilo.conf - prompt - timeout=20 - default=xen - relocatable - - image=vmlinuz-2.6.18.8-xen - label=xen - vmm=xen.gz - initrd=initrd-2.6.18.8-xen.img - read-only - append=" -- rhgb root=/dev/sda2" - -The append options before "--" are for xen hypervisor, -the options after "--" are for dom0. - -FYI, your machine may need console options like -"com1=19200,8n1 console=vga,com1". For example, -append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \ -console=ttyS0 root=/dev/sda2" - -===================================== -Getting and Building domU with pv_ops -===================================== - - 1. get pv_ops tree - # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/ - - 2. git branch (if necessary) - # cd linux-2.6-xen-ia64/ - # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19 - (Note: The current branch is xen-ia64-domu-minimal-2008may19. - But you would find the new branch. You can see with - "git branch -r" to get the branch lists. - http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/ - is also available. The tree is based on - git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test) - - - 3. copy .config for pv_ops of domU - # cp arch/ia64/configs/xen_domu_wip_defconfig .config - - 4. make kernel with pv_ops - # make oldconfig - # make - - 5. install the kernel and initrd - # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU - # make modules_install - # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \ - 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \ - --builtin mptbase --builtin mptscsih --builtin uhci-hcd \ - --builtin ohci-hcd --builtin ehci-hcd - -======================== -Boot DomainU with pv_ops -======================== - - 1. make config of DomU - # vi /etc/xen/rhel5 - kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU" - ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img" - vcpus = 1 - memory = 512 - name = "rhel5" - disk = [ 'file:/root/rhel5.img,xvda1,w' ] - root = "/dev/xvda1 ro" - extra= "rhgb console=hvc0" - - 2. After boot xen and dom0, start xend - # /etc/init.d/xend start - ( In the debugging case, # XEND_DEBUG=1 xend trace_start ) - - 3. start domU - # xm create -c rhel5 - -========= -Reference -========= -- Wiki of Xen/IA64 upstream merge - http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge - -Written by Akio Takebe <takebe_akio@jp.fujitsu.com> on 28 May 2008 diff --git a/Documentation/ide/index.rst b/Documentation/ide/index.rst index 45bc12d3957f..813dfe611a31 100644 --- a/Documentation/ide/index.rst +++ b/Documentation/ide/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ================================== Integrated Drive Electronics (IDE) diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 0593dca89a94..58b7a4ebac51 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ============== Industrial I/O diff --git a/Documentation/index.rst b/Documentation/index.rst index 216dc0e1e6f2..70ae148ec980 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,3 +1,4 @@ + .. The Linux Kernel documentation master file, created by sphinx-quickstart on Fri Feb 12 13:51:46 2016. You can adapt this file completely to your liking, but it should at least @@ -34,6 +35,7 @@ trying to get it to work optimally on a given system. :maxdepth: 2 admin-guide/index + kbuild/index Firmware-related documentation ------------------------------ @@ -55,6 +57,7 @@ the kernel interface as seen by application developers. :maxdepth: 2 userspace-api/index + ioctl/index Introduction to kernel development @@ -75,6 +78,9 @@ merged much easier. kernel-hacking/index trace/index maintainer/index + fault-injection/index + livepatch/index + Kernel API documentation ------------------------ @@ -90,8 +96,24 @@ needed). driver-api/index core-api/index + locking/index + accounting/index + block/index + cdrom/index + ide/index + fb/index + fpga/index + hid/index + iio/index + infiniband/index + leds/index media/index + netlabel/index networking/index + pcmcia/index + target/index + timers/index + watchdog/index input/index hwmon/index gpu/index @@ -102,7 +124,10 @@ needed). vm/index bpf/index usb/index + PCI/index misc-devices/index + mic/index + scheduler/index Architecture-specific documentation ----------------------------------- @@ -114,7 +139,16 @@ implementation. :maxdepth: 2 sh/index + arm/index + arm64/index + ia64/index + m68k/index + riscv/index + s390/index + sh/index + sparc/index x86/index + xtensa/index Filesystem Documentation ------------------------ diff --git a/Documentation/infiniband/core_locking.txt b/Documentation/infiniband/core_locking.rst index 4b1f36b6ada0..f34669beb4fe 100644 --- a/Documentation/infiniband/core_locking.txt +++ b/Documentation/infiniband/core_locking.rst @@ -1,4 +1,6 @@ -INFINIBAND MIDLAYER LOCKING +=========================== +InfiniBand Midlayer Locking +=========================== This guide is an attempt to make explicit the locking assumptions made by the InfiniBand midlayer. It describes the requirements on @@ -6,45 +8,47 @@ INFINIBAND MIDLAYER LOCKING protocols that use the midlayer. Sleeping and interrupt context +============================== With the following exceptions, a low-level driver implementation of all of the methods in struct ib_device may sleep. The exceptions are any methods from the list: - create_ah - modify_ah - query_ah - destroy_ah - post_send - post_recv - poll_cq - req_notify_cq - map_phys_fmr + - create_ah + - modify_ah + - query_ah + - destroy_ah + - post_send + - post_recv + - poll_cq + - req_notify_cq + - map_phys_fmr which may not sleep and must be callable from any context. The corresponding functions exported to upper level protocol consumers: - ib_create_ah - ib_modify_ah - ib_query_ah - ib_destroy_ah - ib_post_send - ib_post_recv - ib_req_notify_cq - ib_map_phys_fmr + - ib_create_ah + - ib_modify_ah + - ib_query_ah + - ib_destroy_ah + - ib_post_send + - ib_post_recv + - ib_req_notify_cq + - ib_map_phys_fmr are therefore safe to call from any context. In addition, the function - ib_dispatch_event + - ib_dispatch_event used by low-level drivers to dispatch asynchronous events through the midlayer is also safe to call from any context. Reentrancy +---------- All of the methods in struct ib_device exported by a low-level driver must be fully reentrant. The low-level driver is required to @@ -62,6 +66,7 @@ Reentrancy information between different calls of ib_poll_cq() is not defined. Callbacks +--------- A low-level driver must not perform a callback directly from the same callchain as an ib_device method call. For example, it is not @@ -74,18 +79,18 @@ Callbacks completion event handlers for the same CQ are not called simultaneously. The driver must guarantee that only one CQ event handler for a given CQ is running at a time. In other words, the - following situation is not allowed: + following situation is not allowed:: - CPU1 CPU2 + CPU1 CPU2 - low-level driver -> - consumer CQ event callback: - /* ... */ - ib_req_notify_cq(cq, ...); - low-level driver -> - /* ... */ consumer CQ event callback: - /* ... */ - return from CQ event handler + low-level driver -> + consumer CQ event callback: + /* ... */ + ib_req_notify_cq(cq, ...); + low-level driver -> + /* ... */ consumer CQ event callback: + /* ... */ + return from CQ event handler The context in which completion event and asynchronous event callbacks run is not defined. Depending on the low-level driver, it @@ -93,6 +98,7 @@ Callbacks Upper level protocol consumers may not sleep in a callback. Hot-plug +-------- A low-level driver announces that a device is ready for use by consumers when it calls ib_register_device(), all initialization diff --git a/Documentation/infiniband/index.rst b/Documentation/infiniband/index.rst new file mode 100644 index 000000000000..9cd7615438b9 --- /dev/null +++ b/Documentation/infiniband/index.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +InfiniBand +========== + +.. toctree:: + :maxdepth: 1 + + core_locking + ipoib + opa_vnic + sysfs + tag_matching + user_mad + user_verbs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/infiniband/ipoib.txt b/Documentation/infiniband/ipoib.rst index 47c1dd9818f2..0dd36154c0c9 100644 --- a/Documentation/infiniband/ipoib.txt +++ b/Documentation/infiniband/ipoib.rst @@ -1,4 +1,6 @@ -IP OVER INFINIBAND +================== +IP over InfiniBand +================== The ib_ipoib driver is an implementation of the IP over InfiniBand protocol as specified by RFC 4391 and 4392, issued by the IETF ipoib @@ -8,16 +10,17 @@ IP OVER INFINIBAND masqueraded to the kernel as ethernet interfaces). Partitions and P_Keys +===================== When the IPoIB driver is loaded, it creates one interface for each port using the P_Key at index 0. To create an interface with a different P_Key, write the desired P_Key into the main interface's - /sys/class/net/<intf name>/create_child file. For example: + /sys/class/net/<intf name>/create_child file. For example:: echo 0x8001 > /sys/class/net/ib0/create_child This will create an interface named ib0.8001 with P_Key 0x8001. To - remove a subinterface, use the "delete_child" file: + remove a subinterface, use the "delete_child" file:: echo 0x8001 > /sys/class/net/ib0/delete_child @@ -28,6 +31,7 @@ Partitions and P_Keys rtnl_link_ops, where children created using either way behave the same. Datagram vs Connected modes +=========================== The IPoIB driver supports two modes of operation: datagram and connected. The mode is set and read through an interface's @@ -51,6 +55,7 @@ Datagram vs Connected modes networking stack to use the smaller UD MTU for these neighbours. Stateless offloads +================== If the IB HW supports IPoIB stateless offloads, IPoIB advertises TCP/IP checksum and/or Large Send (LSO) offloading capability to the @@ -60,9 +65,10 @@ Stateless offloads on/off using ethtool calls. Currently LRO is supported only for checksum offload capable devices. - Stateless offloads are supported only in datagram mode. + Stateless offloads are supported only in datagram mode. Interrupt moderation +==================== If the underlying IB device supports CQ event moderation, one can use ethtool to set interrupt mitigation parameters and thus reduce @@ -71,6 +77,7 @@ Interrupt moderation moderation is supported. Debugging Information +===================== By compiling the IPoIB driver with CONFIG_INFINIBAND_IPOIB_DEBUG set to 'y', tracing messages are compiled into the driver. They are @@ -79,7 +86,7 @@ Debugging Information runtime through files in /sys/module/ib_ipoib/. CONFIG_INFINIBAND_IPOIB_DEBUG also enables files in the debugfs - virtual filesystem. By mounting this filesystem, for example with + virtual filesystem. By mounting this filesystem, for example with:: mount -t debugfs none /sys/kernel/debug @@ -96,10 +103,13 @@ Debugging Information performance, because it adds tests to the fast path. References +========== Transmission of IP over InfiniBand (IPoIB) (RFC 4391) - http://ietf.org/rfc/rfc4391.txt + http://ietf.org/rfc/rfc4391.txt + IP over InfiniBand (IPoIB) Architecture (RFC 4392) - http://ietf.org/rfc/rfc4392.txt + http://ietf.org/rfc/rfc4392.txt + IP over InfiniBand: Connected Mode (RFC 4755) http://ietf.org/rfc/rfc4755.txt diff --git a/Documentation/infiniband/opa_vnic.txt b/Documentation/infiniband/opa_vnic.rst index 282e17be798a..2f888d9ffec0 100644 --- a/Documentation/infiniband/opa_vnic.txt +++ b/Documentation/infiniband/opa_vnic.rst @@ -1,3 +1,7 @@ +================================================================= +Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC) +================================================================= + Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC) feature supports Ethernet functionality over Omni-Path fabric by encapsulating the Ethernet packets between HFI nodes. @@ -17,70 +21,72 @@ an independent Ethernet network. The configuration is performed by an Ethernet Manager (EM) which is part of the trusted Fabric Manager (FM) application. HFI nodes can have multiple VNICs each connected to a different virtual Ethernet switch. The below diagram presents a case -of two virtual Ethernet switches with two HFI nodes. - - +-------------------+ - | Subnet/ | - | Ethernet | - | Manager | - +-------------------+ - / / - / / - / / - / / -+-----------------------------+ +------------------------------+ -| Virtual Ethernet Switch | | Virtual Ethernet Switch | -| +---------+ +---------+ | | +---------+ +---------+ | -| | VPORT | | VPORT | | | | VPORT | | VPORT | | -+--+---------+----+---------+-+ +-+---------+----+---------+---+ - | \ / | - | \ / | - | \/ | - | / \ | - | / \ | - +-----------+------------+ +-----------+------------+ - | VNIC | VNIC | | VNIC | VNIC | - +-----------+------------+ +-----------+------------+ - | HFI | | HFI | - +------------------------+ +------------------------+ +of two virtual Ethernet switches with two HFI nodes:: + + +-------------------+ + | Subnet/ | + | Ethernet | + | Manager | + +-------------------+ + / / + / / + / / + / / + +-----------------------------+ +------------------------------+ + | Virtual Ethernet Switch | | Virtual Ethernet Switch | + | +---------+ +---------+ | | +---------+ +---------+ | + | | VPORT | | VPORT | | | | VPORT | | VPORT | | + +--+---------+----+---------+-+ +-+---------+----+---------+---+ + | \ / | + | \ / | + | \/ | + | / \ | + | / \ | + +-----------+------------+ +-----------+------------+ + | VNIC | VNIC | | VNIC | VNIC | + +-----------+------------+ +-----------+------------+ + | HFI | | HFI | + +------------------------+ +------------------------+ The Omni-Path encapsulated Ethernet packet format is as described below. -Bits Field ------------------------------------- +==================== ================================ +Bits Field +==================== ================================ Quad Word 0: -0-19 SLID (lower 20 bits) -20-30 Length (in Quad Words) -31 BECN bit -32-51 DLID (lower 20 bits) -52-56 SC (Service Class) -57-59 RC (Routing Control) -60 FECN bit -61-62 L2 (=10, 16B format) -63 LT (=1, Link Transfer Head Flit) +0-19 SLID (lower 20 bits) +20-30 Length (in Quad Words) +31 BECN bit +32-51 DLID (lower 20 bits) +52-56 SC (Service Class) +57-59 RC (Routing Control) +60 FECN bit +61-62 L2 (=10, 16B format) +63 LT (=1, Link Transfer Head Flit) Quad Word 1: -0-7 L4 type (=0x78 ETHERNET) -8-11 SLID[23:20] -12-15 DLID[23:20] -16-31 PKEY -32-47 Entropy -48-63 Reserved +0-7 L4 type (=0x78 ETHERNET) +8-11 SLID[23:20] +12-15 DLID[23:20] +16-31 PKEY +32-47 Entropy +48-63 Reserved Quad Word 2: -0-15 Reserved -16-31 L4 header -32-63 Ethernet Packet +0-15 Reserved +16-31 L4 header +32-63 Ethernet Packet Quad Words 3 to N-1: -0-63 Ethernet packet (pad extended) +0-63 Ethernet packet (pad extended) Quad Word N (last): -0-23 Ethernet packet (pad extended) -24-55 ICRC -56-61 Tail -62-63 LT (=01, Link Transfer Tail Flit) +0-23 Ethernet packet (pad extended) +24-55 ICRC +56-61 Tail +62-63 LT (=01, Link Transfer Tail Flit) +==================== ================================ Ethernet packet is padded on the transmit side to ensure that the VNIC OPA packet is quad word aligned. The 'Tail' field contains the number of bytes @@ -123,7 +129,7 @@ operation. It also handles the encapsulation of Ethernet packets with an Omni-Path header in the transmit path. For each VNIC interface, the information required for encapsulation is configured by the EM via VEMA MAD interface. It also passes any control information to the HW dependent driver -by invoking the RDMA netdev control operations. +by invoking the RDMA netdev control operations:: +-------------------+ +----------------------+ | | | Linux | diff --git a/Documentation/infiniband/sysfs.txt b/Documentation/infiniband/sysfs.rst index 9fab5062f84b..f0abd6fa48f4 100644 --- a/Documentation/infiniband/sysfs.txt +++ b/Documentation/infiniband/sysfs.rst @@ -1,4 +1,6 @@ -SYSFS FILES +=========== +Sysfs files +=========== The sysfs interface has moved to Documentation/ABI/stable/sysfs-class-infiniband. diff --git a/Documentation/infiniband/tag_matching.txt b/Documentation/infiniband/tag_matching.rst index d2a3bf819226..ef56ea585f92 100644 --- a/Documentation/infiniband/tag_matching.txt +++ b/Documentation/infiniband/tag_matching.rst @@ -1,12 +1,16 @@ +================== Tag matching logic +================== The MPI standard defines a set of rules, known as tag-matching, for matching source send operations to destination receives. The following parameters must match the following source and destination parameters: + * Communicator * User tag - wild card may be specified by the receiver * Source rank – wild car may be specified by the receiver * Destination rank – wild + The ordering rules require that when more than one pair of send and receive message envelopes may match, the pair that includes the earliest posted-send and the earliest posted-receive is the pair that must be used to satisfy the @@ -35,6 +39,7 @@ the header to initiate an RDMA READ operation directly to the matching buffer. A fin message needs to be received in order for the buffer to be reused. Tag matching implementation +=========================== There are two types of matching objects used, the posted receive list and the unexpected message list. The application posts receive buffers through calls diff --git a/Documentation/infiniband/user_mad.txt b/Documentation/infiniband/user_mad.rst index 7aca13a54a3a..d88abfc0e370 100644 --- a/Documentation/infiniband/user_mad.txt +++ b/Documentation/infiniband/user_mad.rst @@ -1,6 +1,9 @@ -USERSPACE MAD ACCESS +==================== +Userspace MAD access +==================== Device files +============ Each port of each InfiniBand device has a "umad" device and an "issm" device attached. For example, a two-port HCA will have two @@ -8,12 +11,13 @@ Device files device of each type (for switch port 0). Creating MAD agents +=================== A MAD agent can be created by filling in a struct ib_user_mad_reg_req and then calling the IB_USER_MAD_REGISTER_AGENT ioctl on a file descriptor for the appropriate device file. If the registration request succeeds, a 32-bit id will be returned in the structure. - For example: + For example:: struct ib_user_mad_reg_req req = { /* ... */ }; ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req); @@ -26,12 +30,14 @@ Creating MAD agents ioctl. Also, all agents registered through a file descriptor will be unregistered when the descriptor is closed. - 2014 -- a new registration ioctl is now provided which allows additional + 2014 + a new registration ioctl is now provided which allows additional fields to be provided during registration. Users of this registration call are implicitly setting the use of pkey_index (see below). Receiving MADs +============== MADs are received using read(). The receive side now supports RMPP. The buffer passed to read() must be at least one @@ -41,7 +47,8 @@ Receiving MADs MAD (RMPP), the errno is set to ENOSPC and the length of the buffer needed is set in mad.length. - Example for normal MAD (non RMPP) reads: + Example for normal MAD (non RMPP) reads:: + struct ib_user_mad *mad; mad = malloc(sizeof *mad + 256); ret = read(fd, mad, sizeof *mad + 256); @@ -50,7 +57,8 @@ Receiving MADs free(mad); } - Example for RMPP reads: + Example for RMPP reads:: + struct ib_user_mad *mad; mad = malloc(sizeof *mad + 256); ret = read(fd, mad, sizeof *mad + 256); @@ -76,11 +84,12 @@ Receiving MADs poll()/select() may be used to wait until a MAD can be read. Sending MADs +============ MADs are sent using write(). The agent ID for sending should be filled into the id field of the MAD, the destination LID should be filled into the lid field, and so on. The send side does support - RMPP so arbitrary length MAD can be sent. For example: + RMPP so arbitrary length MAD can be sent. For example:: struct ib_user_mad *mad; @@ -97,6 +106,7 @@ Sending MADs perror("write"); Transaction IDs +=============== Users of the umad devices can use the lower 32 bits of the transaction ID field (that is, the least significant half of the @@ -105,6 +115,7 @@ Transaction IDs the kernel and will be overwritten before a MAD is sent. P_Key Index Handling +==================== The old ib_umad interface did not allow setting the P_Key index for MADs that are sent and did not provide a way for obtaining the P_Key @@ -119,6 +130,7 @@ P_Key Index Handling default, and the IB_USER_MAD_ENABLE_PKEY ioctl will be removed. Setting IsSM Capability Bit +=========================== To set the IsSM capability bit for a port, simply open the corresponding issm device file. If the IsSM bit is already set, @@ -129,25 +141,26 @@ Setting IsSM Capability Bit the issm file. /dev files +========== To create the appropriate character device files automatically with - udev, a rule like + udev, a rule like:: KERNEL=="umad*", NAME="infiniband/%k" KERNEL=="issm*", NAME="infiniband/%k" - can be used. This will create device nodes named + can be used. This will create device nodes named:: /dev/infiniband/umad0 /dev/infiniband/issm0 for the first port, and so on. The InfiniBand device and port - associated with these devices can be determined from the files + associated with these devices can be determined from the files:: /sys/class/infiniband_mad/umad0/ibdev /sys/class/infiniband_mad/umad0/port - and + and:: /sys/class/infiniband_mad/issm0/ibdev /sys/class/infiniband_mad/issm0/port diff --git a/Documentation/infiniband/user_verbs.txt b/Documentation/infiniband/user_verbs.rst index 47ebf2f80b2b..8ddc4b1cfef2 100644 --- a/Documentation/infiniband/user_verbs.txt +++ b/Documentation/infiniband/user_verbs.rst @@ -1,4 +1,6 @@ -USERSPACE VERBS ACCESS +====================== +Userspace verbs access +====================== The ib_uverbs module, built by enabling CONFIG_INFINIBAND_USER_VERBS, enables direct userspace access to IB hardware via "verbs," as @@ -13,6 +15,7 @@ USERSPACE VERBS ACCESS libmthca userspace driver be installed. User-kernel communication +========================= Userspace communicates with the kernel for slow path, resource management operations via the /dev/infiniband/uverbsN character @@ -28,6 +31,7 @@ User-kernel communication system call. Resource management +=================== Since creation and destruction of all IB resources is done by commands passed through a file descriptor, the kernel can keep track @@ -41,6 +45,7 @@ Resource management prevent one process from touching another process's resources. Memory pinning +============== Direct userspace I/O requires that memory regions that are potential I/O targets be kept resident at the same physical address. The @@ -54,13 +59,14 @@ Memory pinning number of pages pinned by a process. /dev files +========== To create the appropriate character device files automatically with - udev, a rule like + udev, a rule like:: KERNEL=="uverbs*", NAME="infiniband/%k" - can be used. This will create device nodes named + can be used. This will create device nodes named:: /dev/infiniband/uverbs0 diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.rst index 883fb034bd04..ac697fef3545 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.rst @@ -1,3 +1,4 @@ +================================= (How to avoid) Botching up ioctls ================================= diff --git a/Documentation/ioctl/cdrom.rst b/Documentation/ioctl/cdrom.rst new file mode 100644 index 000000000000..3b4c0506de46 --- /dev/null +++ b/Documentation/ioctl/cdrom.rst @@ -0,0 +1,1233 @@ +============================ +Summary of CDROM ioctl calls +============================ + +- Edward A. Falk <efalk@google.com> + +November, 2004 + +This document attempts to describe the ioctl(2) calls supported by +the CDROM layer. These are by-and-large implemented (as of Linux 2.6) +in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c + +ioctl values are listed in <linux/cdrom.h>. As of this writing, they +are as follows: + + ====================== =============================================== + CDROMPAUSE Pause Audio Operation + CDROMRESUME Resume paused Audio Operation + CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) + CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) + CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) + CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) + CDROMSTOP Stop the cdrom drive + CDROMSTART Start the cdrom drive + CDROMEJECT Ejects the cdrom media + CDROMVOLCTRL Control output volume (struct cdrom_volctrl) + CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) + CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) + (struct cdrom_read) + CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) + (struct cdrom_read) + CDROMREADAUDIO (struct cdrom_read_audio) + CDROMEJECT_SW enable(1)/disable(0) auto-ejecting + CDROMMULTISESSION Obtain the start-of-last-session + address of multi session disks + (struct cdrom_multisession) + CDROM_GET_MCN Obtain the "Universal Product Code" + if available (struct cdrom_mcn) + CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead. + CDROMRESET hard-reset the drive + CDROMVOLREAD Get the drive's volume setting + (struct cdrom_volctrl) + CDROMREADRAW read data in raw mode (2352 Bytes) + (struct cdrom_read) + CDROMREADCOOKED read data in cooked mode + CDROMSEEK seek msf address + CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) + CDROMREADALL read all 2646 bytes + CDROMGETSPINDOWN return 4-bit spindown value + CDROMSETSPINDOWN set 4-bit spindown value + CDROMCLOSETRAY pendant of CDROMEJECT + CDROM_SET_OPTIONS Set behavior options + CDROM_CLEAR_OPTIONS Clear behavior options + CDROM_SELECT_SPEED Set the CD-ROM speed + CDROM_SELECT_DISC Select disc (for juke-boxes) + CDROM_MEDIA_CHANGED Check is media changed + CDROM_DRIVE_STATUS Get tray position, etc. + CDROM_DISC_STATUS Get disc type, etc. + CDROM_CHANGER_NSLOTS Get number of slots + CDROM_LOCKDOOR lock or unlock door + CDROM_DEBUG Turn debug messages on/off + CDROM_GET_CAPABILITY get capabilities + CDROMAUDIOBUFSIZ set the audio buffer size + DVD_READ_STRUCT Read structure + DVD_WRITE_STRUCT Write structure + DVD_AUTH Authentication + CDROM_SEND_PACKET send a packet to the drive + CDROM_NEXT_WRITABLE get next writable block + CDROM_LAST_WRITTEN get last block written on disc + ====================== =============================================== + + +The information that follows was determined from reading kernel source +code. It is likely that some corrections will be made over time. + +------------------------------------------------------------------------------ + +General: + + Unless otherwise specified, all ioctl calls return 0 on success + and -1 with errno set to an appropriate value on error. (Some + ioctls return non-negative data values.) + + Unless otherwise specified, all ioctl calls return -1 and set + errno to EFAULT on a failed attempt to copy data to or from user + address space. + + Individual drivers may return error codes not listed here. + + Unless otherwise specified, all data structures and constants + are defined in <linux/cdrom.h> + +------------------------------------------------------------------------------ + + +CDROMPAUSE + Pause Audio Operation + + + usage:: + + ioctl(fd, CDROMPAUSE, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + +CDROMRESUME + Resume paused Audio Operation + + + usage:: + + ioctl(fd, CDROMRESUME, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + +CDROMPLAYMSF + Play Audio MSF + + (struct cdrom_msf) + + + usage:: + + struct cdrom_msf msf; + + ioctl(fd, CDROMPLAYMSF, &msf); + + inputs: + cdrom_msf structure, describing a segment of music to play + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - MSF stands for minutes-seconds-frames + - LBA stands for logical block address + - Segment is described as start and end times, where each time + is described as minutes:seconds:frames. + A frame is 1/75 of a second. + + +CDROMPLAYTRKIND + Play Audio Track/index + + (struct cdrom_ti) + + + usage:: + + struct cdrom_ti ti; + + ioctl(fd, CDROMPLAYTRKIND, &ti); + + inputs: + cdrom_ti structure, describing a segment of music to play + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Segment is described as start and end times, where each time + is described as a track and an index. + + + +CDROMREADTOCHDR + Read TOC header + + (struct cdrom_tochdr) + + + usage:: + + cdrom_tochdr header; + + ioctl(fd, CDROMREADTOCHDR, &header); + + inputs: + cdrom_tochdr structure + + + outputs: + cdrom_tochdr structure + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMREADTOCENTRY + Read TOC entry + + (struct cdrom_tocentry) + + + usage:: + + struct cdrom_tocentry entry; + + ioctl(fd, CDROMREADTOCENTRY, &entry); + + inputs: + cdrom_tocentry structure + + + outputs: + cdrom_tocentry structure + + + error return: + - ENOSYS cd drive not audio-capable. + - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA + - EINVAL requested track out of bounds + - EIO I/O error reading TOC + + notes: + - TOC stands for Table Of Contents + - MSF stands for minutes-seconds-frames + - LBA stands for logical block address + + + +CDROMSTOP + Stop the cdrom drive + + + usage:: + + ioctl(fd, CDROMSTOP, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive down. + + +CDROMSTART + Start the cdrom drive + + + usage:: + + ioctl(fd, CDROMSTART, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive up and/or close the tray. + Other devices ignore the ioctl completely. + + +CDROMEJECT + - Ejects the cdrom media + + + usage:: + + ioctl(fd, CDROMEJECT, 0); + + + inputs: + none + + + outputs: + none + + + error returns: + - ENOSYS cd drive not capable of ejecting + - EBUSY other processes are accessing drive, or door is locked + + notes: + - See CDROM_LOCKDOOR, below. + + + + +CDROMCLOSETRAY + pendant of CDROMEJECT + + + usage:: + + ioctl(fd, CDROMCLOSETRAY, 0); + + + inputs: + none + + + outputs: + none + + + error returns: + - ENOSYS cd drive not capable of closing the tray + - EBUSY other processes are accessing drive, or door is locked + + notes: + - See CDROM_LOCKDOOR, below. + + + + +CDROMVOLCTRL + Control output volume (struct cdrom_volctrl) + + + usage:: + + struct cdrom_volctrl volume; + + ioctl(fd, CDROMVOLCTRL, &volume); + + inputs: + cdrom_volctrl structure containing volumes for up to 4 + channels. + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMVOLREAD + Get the drive's volume setting + + (struct cdrom_volctrl) + + + usage:: + + struct cdrom_volctrl volume; + + ioctl(fd, CDROMVOLREAD, &volume); + + inputs: + none + + + outputs: + The current volume settings. + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMSUBCHNL + Read subchannel data + + (struct cdrom_subchnl) + + + usage:: + + struct cdrom_subchnl q; + + ioctl(fd, CDROMSUBCHNL, &q); + + inputs: + cdrom_subchnl structure + + + outputs: + cdrom_subchnl structure + + + error return: + - ENOSYS cd drive not audio-capable. + - EINVAL format not CDROM_MSF or CDROM_LBA + + notes: + - Format is converted to CDROM_MSF or CDROM_LBA + as per user request on return + + + +CDROMREADRAW + read data in raw mode (2352 Bytes) + + (struct cdrom_read) + + usage:: + + union { + + struct cdrom_msf msf; /* input */ + char buffer[CD_FRAMESIZE_RAW]; /* return */ + } arg; + ioctl(fd, CDROMREADRAW, &arg); + + inputs: + cdrom_msf structure indicating an address to read. + + Only the start values are significant. + + outputs: + Data written to address provided by user. + + + error return: + - EINVAL address less than 0, or msf less than 0:2:0 + - ENOMEM out of memory + + notes: + - As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this + ioctl accepts a cdrom_read structure, but actual source code + reads a cdrom_msf structure and writes a buffer of data to + the same address. + + - MSF values are converted to LBA values via this formula:: + + lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET; + + + + +CDROMREADMODE1 + Read CDROM mode 1 data (2048 Bytes) + + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE (2048) bytes + + + +CDROMREADMODE2 + Read CDROM mode 2 data (2336 Bytes) + + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE_RAW0 (2336) bytes + + + +CDROMREADAUDIO + (struct cdrom_read_audio) + + usage:: + + struct cdrom_read_audio ra; + + ioctl(fd, CDROMREADAUDIO, &ra); + + inputs: + cdrom_read_audio structure containing read start + point and length + + outputs: + audio data, returned to buffer indicated by ra + + + error return: + - EINVAL format not CDROM_MSF or CDROM_LBA + - EINVAL nframes not in range [1 75] + - ENXIO drive has no queue (probably means invalid fd) + - ENOMEM out of memory + + +CDROMEJECT_SW + enable(1)/disable(0) auto-ejecting + + + usage:: + + int val; + + ioctl(fd, CDROMEJECT_SW, val); + + inputs: + Flag specifying auto-eject flag. + + + outputs: + none + + + error return: + - ENOSYS Drive is not capable of ejecting. + - EBUSY Door is locked + + + + +CDROMMULTISESSION + Obtain the start-of-last-session address of multi session disks + + (struct cdrom_multisession) + + usage:: + + struct cdrom_multisession ms_info; + + ioctl(fd, CDROMMULTISESSION, &ms_info); + + inputs: + cdrom_multisession structure containing desired + + format. + + outputs: + cdrom_multisession structure is filled with last_session + information. + + error return: + - EINVAL format not CDROM_MSF or CDROM_LBA + + +CDROM_GET_MCN + Obtain the "Universal Product Code" + if available + + (struct cdrom_mcn) + + + usage:: + + struct cdrom_mcn mcn; + + ioctl(fd, CDROM_GET_MCN, &mcn); + + inputs: + none + + + outputs: + Universal Product Code + + + error return: + - ENOSYS Drive is not capable of reading MCN data. + + notes: + - Source code comments state:: + + The following function is implemented, although very few + audio discs give Universal Product Code information, which + should just be the Medium Catalog Number on the box. Note, + that the way the code is written on the CD is /not/ uniform + across all discs! + + + + +CDROM_GET_UPC + CDROM_GET_MCN (deprecated) + + + Not implemented, as of 2.6.8.1 + + + +CDROMRESET + hard-reset the drive + + + usage:: + + ioctl(fd, CDROMRESET, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - EACCES Access denied: requires CAP_SYS_ADMIN + - ENOSYS Drive is not capable of resetting. + + + + +CDROMREADCOOKED + read data in cooked mode + + + usage:: + + u8 buffer[CD_FRAMESIZE] + + ioctl(fd, CDROMREADCOOKED, buffer); + + inputs: + none + + + outputs: + 2048 bytes of data, "cooked" mode. + + + notes: + Not implemented on all drives. + + + + + +CDROMREADALL + read all 2646 bytes + + + Same as CDROMREADCOOKED, but reads 2646 bytes. + + + +CDROMSEEK + seek msf address + + + usage:: + + struct cdrom_msf msf; + + ioctl(fd, CDROMSEEK, &msf); + + inputs: + MSF address to seek to. + + + outputs: + none + + + + +CDROMPLAYBLK + scsi-cd only + + (struct cdrom_blk) + + + usage:: + + struct cdrom_blk blk; + + ioctl(fd, CDROMPLAYBLK, &blk); + + inputs: + Region to play + + + outputs: + none + + + + +CDROMGETSPINDOWN + usage:: + + char spindown; + + ioctl(fd, CDROMGETSPINDOWN, &spindown); + + inputs: + none + + + outputs: + The value of the current 4-bit spindown value. + + + + + +CDROMSETSPINDOWN + usage:: + + char spindown + + ioctl(fd, CDROMSETSPINDOWN, &spindown); + + inputs: + 4-bit value used to control spindown (TODO: more detail here) + + + outputs: + none + + + + + + +CDROM_SET_OPTIONS + Set behavior options + + + usage:: + + int options; + + ioctl(fd, CDROM_SET_OPTIONS, options); + + inputs: + New values for drive options. The logical 'or' of: + + ============== ================================== + CDO_AUTO_CLOSE close tray on first open(2) + CDO_AUTO_EJECT open tray on last release + CDO_USE_FFLAGS use O_NONBLOCK information on open + CDO_LOCK lock tray on open files + CDO_CHECK_TYPE check type on open for data + ============== ================================== + + outputs: + Returns the resulting options settings in the + ioctl return value. Returns -1 on error. + + error return: + - ENOSYS selected option(s) not supported by drive. + + + + +CDROM_CLEAR_OPTIONS + Clear behavior options + + + Same as CDROM_SET_OPTIONS, except that selected options are + turned off. + + + +CDROM_SELECT_SPEED + Set the CD-ROM speed + + + usage:: + + int speed; + + ioctl(fd, CDROM_SELECT_SPEED, speed); + + inputs: + New drive speed. + + + outputs: + none + + + error return: + - ENOSYS speed selection not supported by drive. + + + +CDROM_SELECT_DISC + Select disc (for juke-boxes) + + + usage:: + + int disk; + + ioctl(fd, CDROM_SELECT_DISC, disk); + + inputs: + Disk to load into drive. + + + outputs: + none + + + error return: + - EINVAL Disk number beyond capacity of drive + + + +CDROM_MEDIA_CHANGED + Check is media changed + + + usage:: + + int slot; + + ioctl(fd, CDROM_MEDIA_CHANGED, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value is 0 or 1 depending on whether the media + + has been changed, or -1 on error. + + error returns: + - ENOSYS Drive can't detect media change + - EINVAL Slot number beyond capacity of drive + - ENOMEM Out of memory + + + +CDROM_DRIVE_STATUS + Get tray position, etc. + + + usage:: + + int slot; + + ioctl(fd, CDROM_DRIVE_STATUS, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value will be one of the following values + + from <linux/cdrom.h>: + + =================== ========================== + CDS_NO_INFO Information not available. + CDS_NO_DISC + CDS_TRAY_OPEN + CDS_DRIVE_NOT_READY + CDS_DISC_OK + -1 error + =================== ========================== + + error returns: + - ENOSYS Drive can't detect drive status + - EINVAL Slot number beyond capacity of drive + - ENOMEM Out of memory + + + + +CDROM_DISC_STATUS + Get disc type, etc. + + + usage:: + + ioctl(fd, CDROM_DISC_STATUS, 0); + + + inputs: + none + + + outputs: + Ioctl return value will be one of the following values + + from <linux/cdrom.h>: + + - CDS_NO_INFO + - CDS_AUDIO + - CDS_MIXED + - CDS_XA_2_2 + - CDS_XA_2_1 + - CDS_DATA_1 + + error returns: + none at present + + notes: + - Source code comments state:: + + + Ok, this is where problems start. The current interface for + the CDROM_DISC_STATUS ioctl is flawed. It makes the false + assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc. + Unfortunately, while this is often the case, it is also + very common for CDs to have some tracks with data, and some + tracks with audio. Just because I feel like it, I declare + the following to be the best way to cope. If the CD has + ANY data tracks on it, it will be returned as a data CD. + If it has any XA tracks, I will return it as that. Now I + could simplify this interface by combining these returns with + the above, but this more clearly demonstrates the problem + with the current interface. Too bad this wasn't designed + to use bitmasks... -Erik + + Well, now we have the option CDS_MIXED: a mixed-type CD. + User level programmers might feel the ioctl is not very + useful. + ---david + + + + +CDROM_CHANGER_NSLOTS + Get number of slots + + + usage:: + + ioctl(fd, CDROM_CHANGER_NSLOTS, 0); + + + inputs: + none + + + outputs: + The ioctl return value will be the number of slots in a + CD changer. Typically 1 for non-multi-disk devices. + + error returns: + none + + + +CDROM_LOCKDOOR + lock or unlock door + + + usage:: + + int lock; + + ioctl(fd, CDROM_LOCKDOOR, lock); + + inputs: + Door lock flag, 1=lock, 0=unlock + + + outputs: + none + + + error returns: + - EDRIVE_CANT_DO_THIS + + Door lock function not supported. + - EBUSY + + Attempt to unlock when multiple users + have the drive open and not CAP_SYS_ADMIN + + notes: + As of 2.6.8.1, the lock flag is a global lock, meaning that + all CD drives will be locked or unlocked together. This is + probably a bug. + + The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h> + and is currently (2.6.8.1) the same as EOPNOTSUPP + + + +CDROM_DEBUG + Turn debug messages on/off + + + usage:: + + int debug; + + ioctl(fd, CDROM_DEBUG, debug); + + inputs: + Cdrom debug flag, 0=disable, 1=enable + + + outputs: + The ioctl return value will be the new debug flag. + + + error return: + - EACCES Access denied: requires CAP_SYS_ADMIN + + + +CDROM_GET_CAPABILITY + get capabilities + + + usage:: + + ioctl(fd, CDROM_GET_CAPABILITY, 0); + + + inputs: + none + + + outputs: + The ioctl return value is the current device capability + flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc. + + + +CDROMAUDIOBUFSIZ + set the audio buffer size + + + usage:: + + int arg; + + ioctl(fd, CDROMAUDIOBUFSIZ, val); + + inputs: + New audio buffer size + + + outputs: + The ioctl return value is the new audio buffer size, or -1 + on error. + + error return: + - ENOSYS Not supported by this driver. + + notes: + Not supported by all drivers. + + + + +DVD_READ_STRUCT Read structure + + usage:: + + dvd_struct s; + + ioctl(fd, DVD_READ_STRUCT, &s); + + inputs: + dvd_struct structure, containing: + + =================== ========================================== + type specifies the information desired, one of + DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT, + DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA, + DVD_STRUCT_MANUFACT + physical.layer_num desired layer, indexed from 0 + copyright.layer_num desired layer, indexed from 0 + disckey.agid + =================== ========================================== + + outputs: + dvd_struct structure, containing: + + =================== ================================ + physical for type == DVD_STRUCT_PHYSICAL + copyright for type == DVD_STRUCT_COPYRIGHT + disckey.value for type == DVD_STRUCT_DISCKEY + bca.{len,value} for type == DVD_STRUCT_BCA + manufact.{len,valu} for type == DVD_STRUCT_MANUFACT + =================== ================================ + + error returns: + - EINVAL physical.layer_num exceeds number of layers + - EIO Received invalid response from drive + + + +DVD_WRITE_STRUCT Write structure + + Not implemented, as of 2.6.8.1 + + + +DVD_AUTH Authentication + + usage:: + + dvd_authinfo ai; + + ioctl(fd, DVD_AUTH, &ai); + + inputs: + dvd_authinfo structure. See <linux/cdrom.h> + + + outputs: + dvd_authinfo structure. + + + error return: + - ENOTTY ai.type not recognized. + + + +CDROM_SEND_PACKET + send a packet to the drive + + + usage:: + + struct cdrom_generic_command cgc; + + ioctl(fd, CDROM_SEND_PACKET, &cgc); + + inputs: + cdrom_generic_command structure containing the packet to send. + + + outputs: + none + + cdrom_generic_command structure containing results. + + error return: + - EIO + + command failed. + - EPERM + + Operation not permitted, either because a + write command was attempted on a drive which + is opened read-only, or because the command + requires CAP_SYS_RAWIO + - EINVAL + + cgc.data_direction not set + + + +CDROM_NEXT_WRITABLE + get next writable block + + + usage:: + + long next; + + ioctl(fd, CDROM_NEXT_WRITABLE, &next); + + inputs: + none + + + outputs: + The next writable block. + + + notes: + If the device does not support this ioctl directly, the + + ioctl will return CDROM_LAST_WRITTEN + 7. + + + +CDROM_LAST_WRITTEN + get last block written on disc + + + usage:: + + long last; + + ioctl(fd, CDROM_LAST_WRITTEN, &last); + + inputs: + none + + + outputs: + The last block written on disc + + + notes: + If the device does not support this ioctl directly, the + result is derived from the disc's table of contents. If the + table of contents can't be read, this ioctl returns an + error. diff --git a/Documentation/ioctl/cdrom.txt b/Documentation/ioctl/cdrom.txt deleted file mode 100644 index a4d62a9d6771..000000000000 --- a/Documentation/ioctl/cdrom.txt +++ /dev/null @@ -1,967 +0,0 @@ - Summary of CDROM ioctl calls. - ============================ - - Edward A. Falk <efalk@google.com> - - November, 2004 - -This document attempts to describe the ioctl(2) calls supported by -the CDROM layer. These are by-and-large implemented (as of Linux 2.6) -in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c - -ioctl values are listed in <linux/cdrom.h>. As of this writing, they -are as follows: - - CDROMPAUSE Pause Audio Operation - CDROMRESUME Resume paused Audio Operation - CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) - CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) - CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) - CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) - CDROMSTOP Stop the cdrom drive - CDROMSTART Start the cdrom drive - CDROMEJECT Ejects the cdrom media - CDROMVOLCTRL Control output volume (struct cdrom_volctrl) - CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) - CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) - (struct cdrom_read) - CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) - (struct cdrom_read) - CDROMREADAUDIO (struct cdrom_read_audio) - CDROMEJECT_SW enable(1)/disable(0) auto-ejecting - CDROMMULTISESSION Obtain the start-of-last-session - address of multi session disks - (struct cdrom_multisession) - CDROM_GET_MCN Obtain the "Universal Product Code" - if available (struct cdrom_mcn) - CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead. - CDROMRESET hard-reset the drive - CDROMVOLREAD Get the drive's volume setting - (struct cdrom_volctrl) - CDROMREADRAW read data in raw mode (2352 Bytes) - (struct cdrom_read) - CDROMREADCOOKED read data in cooked mode - CDROMSEEK seek msf address - CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) - CDROMREADALL read all 2646 bytes - CDROMGETSPINDOWN return 4-bit spindown value - CDROMSETSPINDOWN set 4-bit spindown value - CDROMCLOSETRAY pendant of CDROMEJECT - CDROM_SET_OPTIONS Set behavior options - CDROM_CLEAR_OPTIONS Clear behavior options - CDROM_SELECT_SPEED Set the CD-ROM speed - CDROM_SELECT_DISC Select disc (for juke-boxes) - CDROM_MEDIA_CHANGED Check is media changed - CDROM_DRIVE_STATUS Get tray position, etc. - CDROM_DISC_STATUS Get disc type, etc. - CDROM_CHANGER_NSLOTS Get number of slots - CDROM_LOCKDOOR lock or unlock door - CDROM_DEBUG Turn debug messages on/off - CDROM_GET_CAPABILITY get capabilities - CDROMAUDIOBUFSIZ set the audio buffer size - DVD_READ_STRUCT Read structure - DVD_WRITE_STRUCT Write structure - DVD_AUTH Authentication - CDROM_SEND_PACKET send a packet to the drive - CDROM_NEXT_WRITABLE get next writable block - CDROM_LAST_WRITTEN get last block written on disc - - -The information that follows was determined from reading kernel source -code. It is likely that some corrections will be made over time. - - - - - - - -General: - - Unless otherwise specified, all ioctl calls return 0 on success - and -1 with errno set to an appropriate value on error. (Some - ioctls return non-negative data values.) - - Unless otherwise specified, all ioctl calls return -1 and set - errno to EFAULT on a failed attempt to copy data to or from user - address space. - - Individual drivers may return error codes not listed here. - - Unless otherwise specified, all data structures and constants - are defined in <linux/cdrom.h> - - - - -CDROMPAUSE Pause Audio Operation - - usage: - - ioctl(fd, CDROMPAUSE, 0); - - inputs: none - - outputs: none - - error return: - ENOSYS cd drive not audio-capable. - - -CDROMRESUME Resume paused Audio Operation - - usage: - - ioctl(fd, CDROMRESUME, 0); - - inputs: none - - outputs: none - - error return: - ENOSYS cd drive not audio-capable. - - -CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) - - usage: - - struct cdrom_msf msf; - ioctl(fd, CDROMPLAYMSF, &msf); - - inputs: - cdrom_msf structure, describing a segment of music to play - - outputs: none - - error return: - ENOSYS cd drive not audio-capable. - - notes: - MSF stands for minutes-seconds-frames - LBA stands for logical block address - - Segment is described as start and end times, where each time - is described as minutes:seconds:frames. A frame is 1/75 of - a second. - - -CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) - - usage: - - struct cdrom_ti ti; - ioctl(fd, CDROMPLAYTRKIND, &ti); - - inputs: - cdrom_ti structure, describing a segment of music to play - - outputs: none - - error return: - ENOSYS cd drive not audio-capable. - - notes: - Segment is described as start and end times, where each time - is described as a track and an index. - - - -CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) - - usage: - - cdrom_tochdr header; - ioctl(fd, CDROMREADTOCHDR, &header); - - inputs: - cdrom_tochdr structure - - outputs: - cdrom_tochdr structure - - error return: - ENOSYS cd drive not audio-capable. - - - -CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) - - usage: - - struct cdrom_tocentry entry; - ioctl(fd, CDROMREADTOCENTRY, &entry); - - inputs: - cdrom_tocentry structure - - outputs: - cdrom_tocentry structure - - error return: - ENOSYS cd drive not audio-capable. - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA - EINVAL requested track out of bounds - EIO I/O error reading TOC - - notes: - TOC stands for Table Of Contents - MSF stands for minutes-seconds-frames - LBA stands for logical block address - - - -CDROMSTOP Stop the cdrom drive - - usage: - - ioctl(fd, CDROMSTOP, 0); - - inputs: none - - outputs: none - - error return: - ENOSYS cd drive not audio-capable. - - notes: - Exact interpretation of this ioctl depends on the device, - but most seem to spin the drive down. - - -CDROMSTART Start the cdrom drive - - usage: - - ioctl(fd, CDROMSTART, 0); - - inputs: none - - outputs: none - - error return: - ENOSYS cd drive not audio-capable. - - notes: - Exact interpretation of this ioctl depends on the device, - but most seem to spin the drive up and/or close the tray. - Other devices ignore the ioctl completely. - - -CDROMEJECT Ejects the cdrom media - - usage: - - ioctl(fd, CDROMEJECT, 0); - - inputs: none - - outputs: none - - error returns: - ENOSYS cd drive not capable of ejecting - EBUSY other processes are accessing drive, or door is locked - - notes: - See CDROM_LOCKDOOR, below. - - - -CDROMCLOSETRAY pendant of CDROMEJECT - - usage: - - ioctl(fd, CDROMCLOSETRAY, 0); - - inputs: none - - outputs: none - - error returns: - ENOSYS cd drive not capable of closing the tray - EBUSY other processes are accessing drive, or door is locked - - notes: - See CDROM_LOCKDOOR, below. - - - -CDROMVOLCTRL Control output volume (struct cdrom_volctrl) - - usage: - - struct cdrom_volctrl volume; - ioctl(fd, CDROMVOLCTRL, &volume); - - inputs: - cdrom_volctrl structure containing volumes for up to 4 - channels. - - outputs: none - - error return: - ENOSYS cd drive not audio-capable. - - - -CDROMVOLREAD Get the drive's volume setting - (struct cdrom_volctrl) - - usage: - - struct cdrom_volctrl volume; - ioctl(fd, CDROMVOLREAD, &volume); - - inputs: none - - outputs: - The current volume settings. - - error return: - ENOSYS cd drive not audio-capable. - - - -CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) - - usage: - - struct cdrom_subchnl q; - ioctl(fd, CDROMSUBCHNL, &q); - - inputs: - cdrom_subchnl structure - - outputs: - cdrom_subchnl structure - - error return: - ENOSYS cd drive not audio-capable. - EINVAL format not CDROM_MSF or CDROM_LBA - - notes: - Format is converted to CDROM_MSF or CDROM_LBA - as per user request on return - - - -CDROMREADRAW read data in raw mode (2352 Bytes) - (struct cdrom_read) - - usage: - - union { - struct cdrom_msf msf; /* input */ - char buffer[CD_FRAMESIZE_RAW]; /* return */ - } arg; - ioctl(fd, CDROMREADRAW, &arg); - - inputs: - cdrom_msf structure indicating an address to read. - Only the start values are significant. - - outputs: - Data written to address provided by user. - - error return: - EINVAL address less than 0, or msf less than 0:2:0 - ENOMEM out of memory - - notes: - As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this - ioctl accepts a cdrom_read structure, but actual source code - reads a cdrom_msf structure and writes a buffer of data to - the same address. - - MSF values are converted to LBA values via this formula: - - lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET; - - - - -CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) - (struct cdrom_read) - - notes: - Identical to CDROMREADRAW except that block size is - CD_FRAMESIZE (2048) bytes - - - -CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) - (struct cdrom_read) - - notes: - Identical to CDROMREADRAW except that block size is - CD_FRAMESIZE_RAW0 (2336) bytes - - - -CDROMREADAUDIO (struct cdrom_read_audio) - - usage: - - struct cdrom_read_audio ra; - ioctl(fd, CDROMREADAUDIO, &ra); - - inputs: - cdrom_read_audio structure containing read start - point and length - - outputs: - audio data, returned to buffer indicated by ra - - error return: - EINVAL format not CDROM_MSF or CDROM_LBA - EINVAL nframes not in range [1 75] - ENXIO drive has no queue (probably means invalid fd) - ENOMEM out of memory - - -CDROMEJECT_SW enable(1)/disable(0) auto-ejecting - - usage: - - int val; - ioctl(fd, CDROMEJECT_SW, val); - - inputs: - Flag specifying auto-eject flag. - - outputs: none - - error return: - ENOSYS Drive is not capable of ejecting. - EBUSY Door is locked - - - - -CDROMMULTISESSION Obtain the start-of-last-session - address of multi session disks - (struct cdrom_multisession) - usage: - - struct cdrom_multisession ms_info; - ioctl(fd, CDROMMULTISESSION, &ms_info); - - inputs: - cdrom_multisession structure containing desired - format. - - outputs: - cdrom_multisession structure is filled with last_session - information. - - error return: - EINVAL format not CDROM_MSF or CDROM_LBA - - -CDROM_GET_MCN Obtain the "Universal Product Code" - if available (struct cdrom_mcn) - - usage: - - struct cdrom_mcn mcn; - ioctl(fd, CDROM_GET_MCN, &mcn); - - inputs: none - - outputs: - Universal Product Code - - error return: - ENOSYS Drive is not capable of reading MCN data. - - notes: - Source code comments state: - - The following function is implemented, although very few - audio discs give Universal Product Code information, which - should just be the Medium Catalog Number on the box. Note, - that the way the code is written on the CD is /not/ uniform - across all discs! - - - - -CDROM_GET_UPC CDROM_GET_MCN (deprecated) - - Not implemented, as of 2.6.8.1 - - - -CDROMRESET hard-reset the drive - - usage: - - ioctl(fd, CDROMRESET, 0); - - inputs: none - - outputs: none - - error return: - EACCES Access denied: requires CAP_SYS_ADMIN - ENOSYS Drive is not capable of resetting. - - - - -CDROMREADCOOKED read data in cooked mode - - usage: - - u8 buffer[CD_FRAMESIZE] - ioctl(fd, CDROMREADCOOKED, buffer); - - inputs: none - - outputs: - 2048 bytes of data, "cooked" mode. - - notes: - Not implemented on all drives. - - - - -CDROMREADALL read all 2646 bytes - - Same as CDROMREADCOOKED, but reads 2646 bytes. - - - -CDROMSEEK seek msf address - - usage: - - struct cdrom_msf msf; - ioctl(fd, CDROMSEEK, &msf); - - inputs: - MSF address to seek to. - - outputs: none - - - -CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) - - usage: - - struct cdrom_blk blk; - ioctl(fd, CDROMPLAYBLK, &blk); - - inputs: - Region to play - - outputs: none - - - -CDROMGETSPINDOWN - - usage: - - char spindown; - ioctl(fd, CDROMGETSPINDOWN, &spindown); - - inputs: none - - outputs: - The value of the current 4-bit spindown value. - - - - -CDROMSETSPINDOWN - - usage: - - char spindown - ioctl(fd, CDROMSETSPINDOWN, &spindown); - - inputs: - 4-bit value used to control spindown (TODO: more detail here) - - outputs: none - - - - - -CDROM_SET_OPTIONS Set behavior options - - usage: - - int options; - ioctl(fd, CDROM_SET_OPTIONS, options); - - inputs: - New values for drive options. The logical 'or' of: - CDO_AUTO_CLOSE close tray on first open(2) - CDO_AUTO_EJECT open tray on last release - CDO_USE_FFLAGS use O_NONBLOCK information on open - CDO_LOCK lock tray on open files - CDO_CHECK_TYPE check type on open for data - - outputs: - Returns the resulting options settings in the - ioctl return value. Returns -1 on error. - - error return: - ENOSYS selected option(s) not supported by drive. - - - - -CDROM_CLEAR_OPTIONS Clear behavior options - - Same as CDROM_SET_OPTIONS, except that selected options are - turned off. - - - -CDROM_SELECT_SPEED Set the CD-ROM speed - - usage: - - int speed; - ioctl(fd, CDROM_SELECT_SPEED, speed); - - inputs: - New drive speed. - - outputs: none - - error return: - ENOSYS speed selection not supported by drive. - - - -CDROM_SELECT_DISC Select disc (for juke-boxes) - - usage: - - int disk; - ioctl(fd, CDROM_SELECT_DISC, disk); - - inputs: - Disk to load into drive. - - outputs: none - - error return: - EINVAL Disk number beyond capacity of drive - - - -CDROM_MEDIA_CHANGED Check is media changed - - usage: - - int slot; - ioctl(fd, CDROM_MEDIA_CHANGED, slot); - - inputs: - Slot number to be tested, always zero except for jukeboxes. - May also be special values CDSL_NONE or CDSL_CURRENT - - outputs: - Ioctl return value is 0 or 1 depending on whether the media - has been changed, or -1 on error. - - error returns: - ENOSYS Drive can't detect media change - EINVAL Slot number beyond capacity of drive - ENOMEM Out of memory - - - -CDROM_DRIVE_STATUS Get tray position, etc. - - usage: - - int slot; - ioctl(fd, CDROM_DRIVE_STATUS, slot); - - inputs: - Slot number to be tested, always zero except for jukeboxes. - May also be special values CDSL_NONE or CDSL_CURRENT - - outputs: - Ioctl return value will be one of the following values - from <linux/cdrom.h>: - - CDS_NO_INFO Information not available. - CDS_NO_DISC - CDS_TRAY_OPEN - CDS_DRIVE_NOT_READY - CDS_DISC_OK - -1 error - - error returns: - ENOSYS Drive can't detect drive status - EINVAL Slot number beyond capacity of drive - ENOMEM Out of memory - - - - -CDROM_DISC_STATUS Get disc type, etc. - - usage: - - ioctl(fd, CDROM_DISC_STATUS, 0); - - inputs: none - - outputs: - Ioctl return value will be one of the following values - from <linux/cdrom.h>: - CDS_NO_INFO - CDS_AUDIO - CDS_MIXED - CDS_XA_2_2 - CDS_XA_2_1 - CDS_DATA_1 - - error returns: none at present - - notes: - Source code comments state: - - Ok, this is where problems start. The current interface for - the CDROM_DISC_STATUS ioctl is flawed. It makes the false - assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc. - Unfortunately, while this is often the case, it is also - very common for CDs to have some tracks with data, and some - tracks with audio. Just because I feel like it, I declare - the following to be the best way to cope. If the CD has - ANY data tracks on it, it will be returned as a data CD. - If it has any XA tracks, I will return it as that. Now I - could simplify this interface by combining these returns with - the above, but this more clearly demonstrates the problem - with the current interface. Too bad this wasn't designed - to use bitmasks... -Erik - - Well, now we have the option CDS_MIXED: a mixed-type CD. - User level programmers might feel the ioctl is not very - useful. - ---david - - - - -CDROM_CHANGER_NSLOTS Get number of slots - - usage: - - ioctl(fd, CDROM_CHANGER_NSLOTS, 0); - - inputs: none - - outputs: - The ioctl return value will be the number of slots in a - CD changer. Typically 1 for non-multi-disk devices. - - error returns: none - - - -CDROM_LOCKDOOR lock or unlock door - - usage: - - int lock; - ioctl(fd, CDROM_LOCKDOOR, lock); - - inputs: - Door lock flag, 1=lock, 0=unlock - - outputs: none - - error returns: - EDRIVE_CANT_DO_THIS Door lock function not supported. - EBUSY Attempt to unlock when multiple users - have the drive open and not CAP_SYS_ADMIN - - notes: - As of 2.6.8.1, the lock flag is a global lock, meaning that - all CD drives will be locked or unlocked together. This is - probably a bug. - - The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h> - and is currently (2.6.8.1) the same as EOPNOTSUPP - - - -CDROM_DEBUG Turn debug messages on/off - - usage: - - int debug; - ioctl(fd, CDROM_DEBUG, debug); - - inputs: - Cdrom debug flag, 0=disable, 1=enable - - outputs: - The ioctl return value will be the new debug flag. - - error return: - EACCES Access denied: requires CAP_SYS_ADMIN - - - -CDROM_GET_CAPABILITY get capabilities - - usage: - - ioctl(fd, CDROM_GET_CAPABILITY, 0); - - inputs: none - - outputs: - The ioctl return value is the current device capability - flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc. - - - -CDROMAUDIOBUFSIZ set the audio buffer size - - usage: - - int arg; - ioctl(fd, CDROMAUDIOBUFSIZ, val); - - inputs: - New audio buffer size - - outputs: - The ioctl return value is the new audio buffer size, or -1 - on error. - - error return: - ENOSYS Not supported by this driver. - - notes: - Not supported by all drivers. - - - -DVD_READ_STRUCT Read structure - - usage: - - dvd_struct s; - ioctl(fd, DVD_READ_STRUCT, &s); - - inputs: - dvd_struct structure, containing: - type specifies the information desired, one of - DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT, - DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA, - DVD_STRUCT_MANUFACT - physical.layer_num desired layer, indexed from 0 - copyright.layer_num desired layer, indexed from 0 - disckey.agid - - outputs: - dvd_struct structure, containing: - physical for type == DVD_STRUCT_PHYSICAL - copyright for type == DVD_STRUCT_COPYRIGHT - disckey.value for type == DVD_STRUCT_DISCKEY - bca.{len,value} for type == DVD_STRUCT_BCA - manufact.{len,valu} for type == DVD_STRUCT_MANUFACT - - error returns: - EINVAL physical.layer_num exceeds number of layers - EIO Received invalid response from drive - - - -DVD_WRITE_STRUCT Write structure - - Not implemented, as of 2.6.8.1 - - - -DVD_AUTH Authentication - - usage: - - dvd_authinfo ai; - ioctl(fd, DVD_AUTH, &ai); - - inputs: - dvd_authinfo structure. See <linux/cdrom.h> - - outputs: - dvd_authinfo structure. - - error return: - ENOTTY ai.type not recognized. - - - -CDROM_SEND_PACKET send a packet to the drive - - usage: - - struct cdrom_generic_command cgc; - ioctl(fd, CDROM_SEND_PACKET, &cgc); - - inputs: - cdrom_generic_command structure containing the packet to send. - - outputs: none - cdrom_generic_command structure containing results. - - error return: - EIO command failed. - EPERM Operation not permitted, either because a - write command was attempted on a drive which - is opened read-only, or because the command - requires CAP_SYS_RAWIO - EINVAL cgc.data_direction not set - - - -CDROM_NEXT_WRITABLE get next writable block - - usage: - - long next; - ioctl(fd, CDROM_NEXT_WRITABLE, &next); - - inputs: none - - outputs: - The next writable block. - - notes: - If the device does not support this ioctl directly, the - ioctl will return CDROM_LAST_WRITTEN + 7. - - - -CDROM_LAST_WRITTEN get last block written on disc - - usage: - - long last; - ioctl(fd, CDROM_LAST_WRITTEN, &last); - - inputs: none - - outputs: - The last block written on disc - - notes: - If the device does not support this ioctl directly, the - result is derived from the disc's table of contents. If the - table of contents can't be read, this ioctl returns an - error. diff --git a/Documentation/ioctl/hdio.txt b/Documentation/ioctl/hdio.rst index 18eb98c44ffe..e822e3dff176 100644 --- a/Documentation/ioctl/hdio.txt +++ b/Documentation/ioctl/hdio.rst @@ -1,9 +1,10 @@ - Summary of HDIO_ ioctl calls. - ============================ +============================== +Summary of `HDIO_` ioctl calls +============================== - Edward A. Falk <efalk@google.com> +- Edward A. Falk <efalk@google.com> - November, 2004 +November, 2004 This document attempts to describe the ioctl(2) calls supported by the HD/IDE layer. These are by-and-large implemented (as of Linux 2.6) @@ -14,6 +15,7 @@ are as follows: ioctls that pass argument pointers to user space: + ======================= ======================================= HDIO_GETGEO get device geometry HDIO_GET_UNMASKINTR get current unmask setting HDIO_GET_MULTCOUNT get current IDE blockmode setting @@ -36,9 +38,11 @@ are as follows: HDIO_DRIVE_TASK execute task and special drive command HDIO_DRIVE_CMD execute a special drive command HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK + ======================= ======================================= ioctls that pass non-pointer values: + ======================= ======================================= HDIO_SET_MULTCOUNT change IDE blockmode HDIO_SET_UNMASKINTR permit other irqs during I/O HDIO_SET_KEEPSETTINGS keep ioctl settings on reset @@ -57,16 +61,13 @@ are as follows: HDIO_SET_IDE_SCSI Set scsi emulation mode on/off HDIO_SET_SCSI_IDE not implemented yet + ======================= ======================================= The information that follows was determined from reading kernel source code. It is likely that some corrections will be made over time. - - - - - +------------------------------------------------------------------------------ General: @@ -80,459 +81,610 @@ General: Unless otherwise specified, all data structures and constants are defined in <linux/hdreg.h> +------------------------------------------------------------------------------ +HDIO_GETGEO + get device geometry -HDIO_GETGEO get device geometry - usage: + usage:: struct hd_geometry geom; + ioctl(fd, HDIO_GETGEO, &geom); - inputs: none + inputs: + none + + outputs: + hd_geometry structure containing: - hd_geometry structure containing: + ========= ================================== heads number of heads sectors number of sectors/track cylinders number of cylinders, mod 65536 start starting sector of this partition. + ========= ================================== error returns: - EINVAL if the device is not a disk drive or floppy drive, - or if the user passes a null pointer + - EINVAL + + if the device is not a disk drive or floppy drive, + or if the user passes a null pointer notes: + Not particularly useful with modern disk drives, whose geometry + is a polite fiction anyway. Modern drives are addressed + purely by sector number nowadays (lba addressing), and the + drive geometry is an abstraction which is actually subject + to change. Currently (as of Nov 2004), the geometry values + are the "bios" values -- presumably the values the drive had + when Linux first booted. - Not particularly useful with modern disk drives, whose geometry - is a polite fiction anyway. Modern drives are addressed - purely by sector number nowadays (lba addressing), and the - drive geometry is an abstraction which is actually subject - to change. Currently (as of Nov 2004), the geometry values - are the "bios" values -- presumably the values the drive had - when Linux first booted. + In addition, the cylinders field of the hd_geometry is an + unsigned short, meaning that on most architectures, this + ioctl will not return a meaningful value on drives with more + than 65535 tracks. - In addition, the cylinders field of the hd_geometry is an - unsigned short, meaning that on most architectures, this - ioctl will not return a meaningful value on drives with more - than 65535 tracks. + The start field is unsigned long, meaning that it will not + contain a meaningful value for disks over 219 Gb in size. - The start field is unsigned long, meaning that it will not - contain a meaningful value for disks over 219 Gb in size. +HDIO_GET_UNMASKINTR + get current unmask setting -HDIO_GET_UNMASKINTR get current unmask setting - usage: + usage:: long val; + ioctl(fd, HDIO_GET_UNMASKINTR, &val); - inputs: none + inputs: + none + + outputs: - The value of the drive's current unmask setting + The value of the drive's current unmask setting -HDIO_SET_UNMASKINTR permit other irqs during I/O - usage: + +HDIO_SET_UNMASKINTR + permit other irqs during I/O + + + usage:: unsigned long val; + ioctl(fd, HDIO_SET_UNMASKINTR, val); inputs: - New value for unmask flag + New value for unmask flag + + + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 1] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + +HDIO_GET_MULTCOUNT + get current IDE blockmode setting -HDIO_GET_MULTCOUNT get current IDE blockmode setting - usage: + usage:: long val; + ioctl(fd, HDIO_GET_MULTCOUNT, &val); - inputs: none + inputs: + none + + outputs: - The value of the current IDE block mode setting. This - controls how many sectors the drive will transfer per - interrupt. + The value of the current IDE block mode setting. This + controls how many sectors the drive will transfer per + interrupt. + +HDIO_SET_MULTCOUNT + change IDE blockmode -HDIO_SET_MULTCOUNT change IDE blockmode - usage: + usage:: int val; + ioctl(fd, HDIO_SET_MULTCOUNT, val); inputs: - New value for IDE block mode setting. This controls how many - sectors the drive will transfer per interrupt. + New value for IDE block mode setting. This controls how many + sectors the drive will transfer per interrupt. + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range supported by disk. - EBUSY Controller busy or blockmode already set. - EIO Drive did not accept new block mode. + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range supported by disk. + - EBUSY Controller busy or blockmode already set. + - EIO Drive did not accept new block mode. notes: - - Source code comments read: + Source code comments read:: This is tightly woven into the driver->do_special cannot touch. DON'T do it again until a total personality rewrite is committed. If blockmode has already been set, this ioctl will fail with - EBUSY + -EBUSY -HDIO_GET_QDMA get use-qdma flag +HDIO_GET_QDMA + get use-qdma flag + Not implemented, as of 2.6.8.1 -HDIO_SET_XFER set transfer rate via proc +HDIO_SET_XFER + set transfer rate via proc + Not implemented, as of 2.6.8.1 -HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE +HDIO_OBSOLETE_IDENTITY + OBSOLETE, DO NOT USE + Same as HDIO_GET_IDENTITY (see below), except that it only returns the first 142 bytes of drive identity information. -HDIO_GET_IDENTITY get IDE identification info +HDIO_GET_IDENTITY + get IDE identification info + - usage: + usage:: unsigned char identity[512]; + ioctl(fd, HDIO_GET_IDENTITY, identity); - inputs: none + inputs: + none - outputs: - ATA drive identity information. For full description, see - the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in - the ATA specification. + + outputs: + ATA drive identity information. For full description, see + the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in + the ATA specification. error returns: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - ENOMSG IDENTIFY DEVICE information not available + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - ENOMSG IDENTIFY DEVICE information not available notes: + Returns information that was obtained when the drive was + probed. Some of this information is subject to change, and + this ioctl does not re-probe the drive to update the + information. - Returns information that was obtained when the drive was - probed. Some of this information is subject to change, and - this ioctl does not re-probe the drive to update the - information. + This information is also available from /proc/ide/hdX/identify - This information is also available from /proc/ide/hdX/identify +HDIO_GET_KEEPSETTINGS + get keep-settings-on-reset flag -HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag - usage: + usage:: long val; + ioctl(fd, HDIO_GET_KEEPSETTINGS, &val); - inputs: none + inputs: + none + + outputs: - The value of the current "keep settings" flag + The value of the current "keep settings" flag + + notes: + When set, indicates that kernel should restore settings + after a drive reset. - When set, indicates that kernel should restore settings - after a drive reset. +HDIO_SET_KEEPSETTINGS + keep ioctl settings on reset -HDIO_SET_KEEPSETTINGS keep ioctl settings on reset - usage: + usage:: long val; + ioctl(fd, HDIO_SET_KEEPSETTINGS, val); inputs: - New value for keep_settings flag + New value for keep_settings flag + + + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 1] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + +HDIO_GET_32BIT + get current io_32bit setting -HDIO_GET_32BIT get current io_32bit setting - usage: + usage:: long val; + ioctl(fd, HDIO_GET_32BIT, &val); - inputs: none + inputs: + none + + outputs: - The value of the current io_32bit setting + The value of the current io_32bit setting + + notes: + 0=16-bit, 1=32-bit, 2,3 = 32bit+sync + - 0=16-bit, 1=32-bit, 2,3 = 32bit+sync -HDIO_GET_NOWERR get ignore-write-error flag +HDIO_GET_NOWERR + get ignore-write-error flag - usage: + + usage:: long val; + ioctl(fd, HDIO_GET_NOWERR, &val); - inputs: none + inputs: + none + + outputs: - The value of the current ignore-write-error flag + The value of the current ignore-write-error flag -HDIO_GET_DMA get use-dma flag - usage: + +HDIO_GET_DMA + get use-dma flag + + + usage:: long val; + ioctl(fd, HDIO_GET_DMA, &val); - inputs: none + inputs: + none + + outputs: - The value of the current use-dma flag + The value of the current use-dma flag -HDIO_GET_NICE get nice flags - usage: + +HDIO_GET_NICE + get nice flags + + + usage:: long nice; + ioctl(fd, HDIO_GET_NICE, &nice); - inputs: none + inputs: + none + + outputs: + The drive's "nice" values. + - The drive's "nice" values. notes: + Per-drive flags which determine when the system will give more + bandwidth to other devices sharing the same IDE bus. - Per-drive flags which determine when the system will give more - bandwidth to other devices sharing the same IDE bus. - See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP. + See <linux/hdreg.h>, near symbol IDE_NICE_DSC_OVERLAP. -HDIO_SET_NICE set nice flags +HDIO_SET_NICE + set nice flags - usage: + + usage:: unsigned long nice; + ... ioctl(fd, HDIO_SET_NICE, nice); inputs: - bitmask of nice flags. + bitmask of nice flags. + + + + outputs: + none + - outputs: none error returns: - EACCES Access denied: requires CAP_SYS_ADMIN - EPERM Flags other than DSC_OVERLAP and NICE_1 set. - EPERM DSC_OVERLAP specified but not supported by drive + - EACCES Access denied: requires CAP_SYS_ADMIN + - EPERM Flags other than DSC_OVERLAP and NICE_1 set. + - EPERM DSC_OVERLAP specified but not supported by drive notes: + This ioctl sets the DSC_OVERLAP and NICE_1 flags from values + provided by the user. - This ioctl sets the DSC_OVERLAP and NICE_1 flags from values - provided by the user. + Nice flags are listed in <linux/hdreg.h>, starting with + IDE_NICE_DSC_OVERLAP. These values represent shifts. - Nice flags are listed in <linux/hdreg.h>, starting with - IDE_NICE_DSC_OVERLAP. These values represent shifts. +HDIO_GET_WCACHE + get write cache mode on|off -HDIO_GET_WCACHE get write cache mode on|off - usage: + usage:: long val; + ioctl(fd, HDIO_GET_WCACHE, &val); - inputs: none + inputs: + none + + outputs: - The value of the current write cache mode + The value of the current write cache mode -HDIO_GET_ACOUSTIC get acoustic value - usage: + +HDIO_GET_ACOUSTIC + get acoustic value + + + usage:: long val; + ioctl(fd, HDIO_GET_ACOUSTIC, &val); - inputs: none + inputs: + none + + outputs: - The value of the current acoustic settings + The value of the current acoustic settings + + notes: + See HDIO_SET_ACOUSTIC + - See HDIO_SET_ACOUSTIC HDIO_GET_ADDRESS + usage:: - usage: long val; + ioctl(fd, HDIO_GET_ADDRESS, &val); - inputs: none + inputs: + none + + outputs: - The value of the current addressing mode: - 0 = 28-bit - 1 = 48-bit - 2 = 48-bit doing 28-bit - 3 = 64-bit + The value of the current addressing mode: + + = =================== + 0 28-bit + 1 48-bit + 2 48-bit doing 28-bit + 3 64-bit + = =================== -HDIO_GET_BUSSTATE get the bus state of the hwif +HDIO_GET_BUSSTATE + get the bus state of the hwif - usage: + + usage:: long state; + ioctl(fd, HDIO_SCAN_HWIF, &state); - inputs: none + inputs: + none + + outputs: - Current power state of the IDE bus. One of BUSSTATE_OFF, - BUSSTATE_ON, or BUSSTATE_TRISTATE + Current power state of the IDE bus. One of BUSSTATE_OFF, + BUSSTATE_ON, or BUSSTATE_TRISTATE error returns: - EACCES Access denied: requires CAP_SYS_ADMIN + - EACCES Access denied: requires CAP_SYS_ADMIN -HDIO_SET_BUSSTATE set the bus state of the hwif +HDIO_SET_BUSSTATE + set the bus state of the hwif - usage: + + usage:: int state; + ... ioctl(fd, HDIO_SCAN_HWIF, state); inputs: - Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON, - or BUSSTATE_TRISTATE + Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON, + or BUSSTATE_TRISTATE + + outputs: + none + - outputs: none error returns: - EACCES Access denied: requires CAP_SYS_RAWIO - EOPNOTSUPP Hardware interface does not support bus power control + - EACCES Access denied: requires CAP_SYS_RAWIO + - EOPNOTSUPP Hardware interface does not support bus power control + +HDIO_TRISTATE_HWIF + execute a channel tristate -HDIO_TRISTATE_HWIF execute a channel tristate Not implemented, as of 2.6.8.1. See HDIO_SET_BUSSTATE -HDIO_DRIVE_RESET execute a device reset +HDIO_DRIVE_RESET + execute a device reset + - usage: + usage:: int args[3] + ... ioctl(fd, HDIO_DRIVE_RESET, args); - inputs: none + inputs: + none + + + + outputs: + none + - outputs: none error returns: - EACCES Access denied: requires CAP_SYS_ADMIN - ENXIO No such device: phy dead or ctl_addr == 0 - EIO I/O error: reset timed out or hardware error + - EACCES Access denied: requires CAP_SYS_ADMIN + - ENXIO No such device: phy dead or ctl_addr == 0 + - EIO I/O error: reset timed out or hardware error notes: - Execute a reset on the device as soon as the current IO - operation has completed. + - Execute a reset on the device as soon as the current IO + operation has completed. - Executes an ATAPI soft reset if applicable, otherwise - executes an ATA soft reset on the controller. + - Executes an ATAPI soft reset if applicable, otherwise + executes an ATA soft reset on the controller. -HDIO_DRIVE_TASKFILE execute raw taskfile +HDIO_DRIVE_TASKFILE + execute raw taskfile - Note: If you don't have a copy of the ANSI ATA specification - handy, you should probably ignore this ioctl. - Execute an ATA disk command directly by writing the "taskfile" - registers of the drive. Requires ADMIN and RAWIO access - privileges. + Note: + If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + - Execute an ATA disk command directly by writing the "taskfile" + registers of the drive. Requires ADMIN and RAWIO access + privileges. - usage: + usage:: struct { + ide_task_request_t req_task; u8 outbuf[OUTPUT_SIZE]; u8 inbuf[INPUT_SIZE]; @@ -548,6 +700,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile (See below for details on memory area passed to ioctl.) + ============ =================================================== io_ports[8] values to be written to taskfile registers hob_ports[8] high-order bytes, for extended commands. out_flags flags indicating which registers are valid @@ -557,24 +710,29 @@ HDIO_DRIVE_TASKFILE execute raw taskfile out_size size of output buffer outbuf buffer of data to be transmitted to disk inbuf buffer of data to be received from disk (see [1]) + ============ =================================================== outputs: + =========== ==================================================== io_ports[] values returned in the taskfile registers hob_ports[] high-order bytes, for extended commands. out_flags flags indicating which registers are valid (see [2]) in_flags flags indicating which registers should be returned outbuf buffer of data to be transmitted to disk (see [1]) inbuf buffer of data to be received from disk + =========== ==================================================== error returns: - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set. - ENOMSG Device is not a disk drive. - ENOMEM Unable to allocate memory for task - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8) - EPERM req_cmd == TASKFILE_MULTI_OUT and drive - multi-count not yet set. - EIO Drive failed the command. + - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set. + - ENOMSG Device is not a disk drive. + - ENOMEM Unable to allocate memory for task + - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8) + - EPERM + + req_cmd == TASKFILE_MULTI_OUT and drive + multi-count not yet set. + - EIO Drive failed the command. notes: @@ -615,22 +773,25 @@ HDIO_DRIVE_TASKFILE execute raw taskfile Command is passed to the disk drive via the ide_task_request_t structure, which contains these fields: + ============ =============================================== io_ports[8] values for the taskfile registers hob_ports[8] high-order bytes, for extended commands out_flags flags indicating which entries in the - io_ports[] and hob_ports[] arrays + io_ports[] and hob_ports[] arrays contain valid values. Type ide_reg_valid_t. in_flags flags indicating which entries in the - io_ports[] and hob_ports[] arrays + io_ports[] and hob_ports[] arrays are expected to contain valid values on return. data_phase See below req_cmd Command type, see below out_size output (user->drive) buffer size, bytes in_size input (drive->user) buffer size, bytes + ============ =============================================== When out_flags is zero, the following registers are loaded. + ============ =============================================== HOB_FEATURE If the drive supports LBA48 HOB_NSECTOR If the drive supports LBA48 HOB_SECTOR If the drive supports LBA48 @@ -644,9 +805,11 @@ HDIO_DRIVE_TASKFILE execute raw taskfile SELECT First, masked with 0xE0 if LBA48, 0xEF otherwise; then, or'ed with the default value of SELECT. + ============ =============================================== If any bit in out_flags is set, the following registers are loaded. + ============ =============================================== HOB_DATA If out_flags.b.data is set. HOB_DATA will travel on DD8-DD15 on little endian machines and on DD0-DD7 on big endian machines. @@ -664,6 +827,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile HCYL If out_flags.b.hcyl is set SELECT Or'ed with the default value of SELECT and loaded regardless of out_flags.b.select. + ============ =============================================== Taskfile registers are read back from the drive into {io|hob}_ports[] after the command completes iff one of the @@ -674,6 +838,7 @@ HDIO_DRIVE_TASKFILE execute raw taskfile 2. One or more than one bits are set in out_flags. 3. The requested data_phase is TASKFILE_NO_DATA. + ============ =============================================== HOB_DATA If in_flags.b.data is set. It will contain DD8-DD15 on little endian machines and DD0-DD7 on big endian machines. @@ -689,10 +854,12 @@ HDIO_DRIVE_TASKFILE execute raw taskfile SECTOR LCYL HCYL + ============ =============================================== The data_phase field describes the data transfer to be performed. Value is one of: + =================== ======================================== TASKFILE_IN TASKFILE_MULTI_IN TASKFILE_OUT @@ -708,15 +875,18 @@ HDIO_DRIVE_TASKFILE execute raw taskfile TASKFILE_P_OUT unimplemented TASKFILE_P_OUT_DMA unimplemented TASKFILE_P_OUT_DMAQ unimplemented + =================== ======================================== The req_cmd field classifies the command type. It may be one of: + ======================== ======================================= IDE_DRIVE_TASK_NO_DATA IDE_DRIVE_TASK_SET_XFER unimplemented IDE_DRIVE_TASK_IN IDE_DRIVE_TASK_OUT unimplemented IDE_DRIVE_TASK_RAW_WRITE + ======================== ======================================= [6] Do not access {in|out}_flags->all except for resetting all the bits. Always access individual bit fields. ->all @@ -726,45 +896,57 @@ HDIO_DRIVE_TASKFILE execute raw taskfile -HDIO_DRIVE_CMD execute a special drive command +HDIO_DRIVE_CMD + execute a special drive command + Note: If you don't have a copy of the ANSI ATA specification handy, you should probably ignore this ioctl. - usage: + usage:: u8 args[4+XFER_SIZE]; + ... ioctl(fd, HDIO_DRIVE_CMD, args); inputs: + Commands other than WIN_SMART: - Commands other than WIN_SMART + ======= ======= args[0] COMMAND args[1] NSECTOR args[2] FEATURE args[3] NSECTOR + ======= ======= + + WIN_SMART: - WIN_SMART + ======= ======= args[0] COMMAND args[1] SECTOR args[2] FEATURE args[3] NSECTOR + ======= ======= outputs: + args[] buffer is filled with register values followed by any + - args[] buffer is filled with register values followed by any data returned by the disk. + + ======== ==================================================== args[0] status args[1] error args[2] NSECTOR args[3] undefined args[4+] NSECTOR * 512 bytes of data returned by the command. + ======== ==================================================== error returns: - EACCES Access denied: requires CAP_SYS_RAWIO - ENOMEM Unable to allocate memory for task - EIO Drive reports error + - EACCES Access denied: requires CAP_SYS_RAWIO + - ENOMEM Unable to allocate memory for task + - EIO Drive reports error notes: @@ -789,20 +971,24 @@ HDIO_DRIVE_CMD execute a special drive command -HDIO_DRIVE_TASK execute task and special drive command +HDIO_DRIVE_TASK + execute task and special drive command + Note: If you don't have a copy of the ANSI ATA specification handy, you should probably ignore this ioctl. - usage: + usage:: u8 args[7]; + ... ioctl(fd, HDIO_DRIVE_TASK, args); inputs: + Taskfile register values: - Taskfile register values: + ======= ======= args[0] COMMAND args[1] FEATURE args[2] NSECTOR @@ -810,10 +996,13 @@ HDIO_DRIVE_TASK execute task and special drive command args[4] LCYL args[5] HCYL args[6] SELECT + ======= ======= outputs: + Taskfile register values: + - Taskfile register values: + ======= ======= args[0] status args[1] error args[2] NSECTOR @@ -821,12 +1010,13 @@ HDIO_DRIVE_TASK execute task and special drive command args[4] LCYL args[5] HCYL args[6] SELECT + ======= ======= error returns: - EACCES Access denied: requires CAP_SYS_RAWIO - ENOMEM Unable to allocate memory for task - ENOMSG Device is not a disk drive. - EIO Drive failed the command. + - EACCES Access denied: requires CAP_SYS_RAWIO + - ENOMEM Unable to allocate memory for task + - ENOMSG Device is not a disk drive. + - EIO Drive failed the command. notes: @@ -836,236 +1026,317 @@ HDIO_DRIVE_TASK execute task and special drive command -HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK +HDIO_DRIVE_CMD_AEB + HDIO_DRIVE_TASK + Not implemented, as of 2.6.8.1 -HDIO_SET_32BIT change io_32bit flags +HDIO_SET_32BIT + change io_32bit flags + - usage: + usage:: int val; + ioctl(fd, HDIO_SET_32BIT, val); inputs: - New value for io_32bit flag + New value for io_32bit flag + + + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 3] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 3] + - EBUSY Controller busy -HDIO_SET_NOWERR change ignore-write-error flag +HDIO_SET_NOWERR + change ignore-write-error flag - usage: + + usage:: int val; + ioctl(fd, HDIO_SET_NOWERR, val); inputs: - New value for ignore-write-error flag. Used for ignoring + New value for ignore-write-error flag. Used for ignoring + + WRERR_STAT - outputs: none + outputs: + none + + error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 1] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + +HDIO_SET_DMA + change use-dma flag -HDIO_SET_DMA change use-dma flag - usage: + usage:: long val; + ioctl(fd, HDIO_SET_DMA, val); inputs: - New value for use-dma flag + New value for use-dma flag + + + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 1] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + +HDIO_SET_PIO_MODE + reconfig interface to new speed -HDIO_SET_PIO_MODE reconfig interface to new speed - usage: + usage:: long val; + ioctl(fd, HDIO_SET_PIO_MODE, val); inputs: - New interface speed. + New interface speed. + + + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 255] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 255] + - EBUSY Controller busy + +HDIO_SCAN_HWIF + register and (re)scan interface -HDIO_SCAN_HWIF register and (re)scan interface - usage: + usage:: int args[3] + ... ioctl(fd, HDIO_SCAN_HWIF, args); inputs: + + ======= ========================= args[0] io address to probe + + args[1] control address to probe args[2] irq number + ======= ========================= + + outputs: + none + - outputs: none error returns: - EACCES Access denied: requires CAP_SYS_RAWIO - EIO Probe failed. + - EACCES Access denied: requires CAP_SYS_RAWIO + - EIO Probe failed. notes: + This ioctl initializes the addresses and irq for a disk + controller, probes for drives, and creates /proc/ide + interfaces as appropriate. - This ioctl initializes the addresses and irq for a disk - controller, probes for drives, and creates /proc/ide - interfaces as appropriate. +HDIO_UNREGISTER_HWIF + unregister interface -HDIO_UNREGISTER_HWIF unregister interface - usage: + usage:: int index; + ioctl(fd, HDIO_UNREGISTER_HWIF, index); inputs: - index index of hardware interface to unregister + index index of hardware interface to unregister + + + + outputs: + none + - outputs: none error returns: - EACCES Access denied: requires CAP_SYS_RAWIO + - EACCES Access denied: requires CAP_SYS_RAWIO notes: + This ioctl removes a hardware interface from the kernel. - This ioctl removes a hardware interface from the kernel. + Currently (2.6.8) this ioctl silently fails if any drive on + the interface is busy. - Currently (2.6.8) this ioctl silently fails if any drive on - the interface is busy. +HDIO_SET_WCACHE + change write cache enable-disable -HDIO_SET_WCACHE change write cache enable-disable - usage: + usage:: int val; + ioctl(fd, HDIO_SET_WCACHE, val); inputs: - New value for write cache enable + New value for write cache enable + + + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 1] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + +HDIO_SET_ACOUSTIC + change acoustic behavior -HDIO_SET_ACOUSTIC change acoustic behavior - usage: + usage:: int val; + ioctl(fd, HDIO_SET_ACOUSTIC, val); inputs: - New value for drive acoustic settings + New value for drive acoustic settings + + + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 254] - EBUSY Controller busy + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 254] + - EBUSY Controller busy -HDIO_SET_QDMA change use-qdma flag +HDIO_SET_QDMA + change use-qdma flag + Not implemented, as of 2.6.8.1 -HDIO_SET_ADDRESS change lba addressing modes +HDIO_SET_ADDRESS + change lba addressing modes + - usage: + usage:: int val; + ioctl(fd, HDIO_SET_ADDRESS, val); inputs: - New value for addressing mode - 0 = 28-bit - 1 = 48-bit - 2 = 48-bit doing 28-bit + New value for addressing mode + + = =================== + 0 28-bit + 1 48-bit + 2 48-bit doing 28-bit + = =================== + + outputs: + none + - outputs: none error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 2] - EBUSY Controller busy - EIO Drive does not support lba48 mode. + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 2] + - EBUSY Controller busy + - EIO Drive does not support lba48 mode. HDIO_SET_IDE_SCSI + usage:: - usage: long val; + ioctl(fd, HDIO_SET_IDE_SCSI, val); inputs: - New value for scsi emulation mode (?) + New value for scsi emulation mode (?) - outputs: none - error return: - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - EACCES Access denied: requires CAP_SYS_ADMIN - EINVAL value out of range [0 1] - EBUSY Controller busy + outputs: + none -HDIO_SET_SCSI_IDE - Not implemented, as of 2.6.8.1 + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + +HDIO_SET_SCSI_IDE + Not implemented, as of 2.6.8.1 diff --git a/Documentation/ioctl/index.rst b/Documentation/ioctl/index.rst new file mode 100644 index 000000000000..0f0a857f6615 --- /dev/null +++ b/Documentation/ioctl/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====== +IOCTLs +====== + +.. toctree:: + :maxdepth: 1 + + ioctl-number + + botching-up-ioctls + ioctl-decoding + + cdrom + hdio diff --git a/Documentation/ioctl/ioctl-decoding.txt b/Documentation/ioctl/ioctl-decoding.rst index e35efb0cec2e..380d6bb3e3ea 100644 --- a/Documentation/ioctl/ioctl-decoding.txt +++ b/Documentation/ioctl/ioctl-decoding.rst @@ -1,10 +1,16 @@ +============================== +Decoding an IOCTL Magic Number +============================== + To decode a hex IOCTL code: Most architectures use this generic format, but check include/ARCH/ioctl.h for specifics, e.g. powerpc uses 3 bits to encode read/write and 13 bits for size. - bits meaning + ====== ================================== + bits meaning + ====== ================================== 31-30 00 - no parameters: uses _IO macro 10 - read: _IOR 01 - write: _IOW @@ -16,9 +22,10 @@ uses 3 bits to encode read/write and 13 bits for size. unique to each driver 7-0 function # + ====== ================================== So for example 0x82187201 is a read with arg length of 0x218, -character 'r' function 1. Grepping the source reveals this is: +character 'r' function 1. Grepping the source reveals this is:: -#define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2]) + #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2]) diff --git a/Documentation/ioctl/ioctl-number.rst b/Documentation/ioctl/ioctl-number.rst new file mode 100644 index 000000000000..7f8dcae7a230 --- /dev/null +++ b/Documentation/ioctl/ioctl-number.rst @@ -0,0 +1,361 @@ +============= +Ioctl Numbers +============= + +19 October 1999 + +Michael Elizabeth Chastain +<mec@shout.net> + +If you are adding new ioctl's to the kernel, you should use the _IO +macros defined in <linux/ioctl.h>: + + ====== == ============================================ + _IO an ioctl with no parameters + _IOW an ioctl with write parameters (copy_from_user) + _IOR an ioctl with read parameters (copy_to_user) + _IOWR an ioctl with both write and read parameters. + ====== == ============================================ + +'Write' and 'read' are from the user's point of view, just like the +system calls 'write' and 'read'. For example, a SET_FOO ioctl would +be _IOW, although the kernel would actually read data from user space; +a GET_FOO ioctl would be _IOR, although the kernel would actually write +data to user space. + +The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter +or number from the table below. Because of the large number of drivers, +many drivers share a partial letter with other drivers. + +If you are writing a driver for a new device and need a letter, pick an +unused block with enough room for expansion: 32 to 256 ioctl commands. +You can register the block by patching this file and submitting the +patch to Linus Torvalds. Or you can e-mail me at <mec@shout.net> and +I'll register one for you. + +The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number +to distinguish ioctls from each other. The third argument to _IOW, +_IOR, or _IOWR is the type of the data going into the kernel or coming +out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use +sizeof(arg) as the third argument as this results in your ioctl thinking +it passes an argument of type size_t. + +Some devices use their major number as the identifier; this is OK, as +long as it is unique. Some devices are irregular and don't follow any +convention at all. + +Following this convention is good because: + +(1) Keeping the ioctl's globally unique helps error checking: + if a program calls an ioctl on the wrong device, it will get an + error rather than some unexpected behaviour. + +(2) The 'strace' build procedure automatically finds ioctl numbers + defined with _IO, _IOW, _IOR, or _IOWR. + +(3) 'strace' can decode numbers back into useful names when the + numbers are unique. + +(4) People looking for ioctls can grep for them more easily when + this convention is used to define the ioctl numbers. + +(5) When following the convention, the driver code can use generic + code to copy the parameters between user and kernel space. + +This table lists ioctls visible from user land for Linux/x86. It contains +most drivers up to 2.6.31, but I know I am missing some. There has been +no attempt to list non-X86 architectures or ioctls from drivers/staging/. + +==== ===== ======================================================= ================================================================ +Code Seq# Include File Comments + (hex) +==== ===== ======================================================= ================================================================ +0x00 00-1F linux/fs.h conflict! +0x00 00-1F scsi/scsi_ioctl.h conflict! +0x00 00-1F linux/fb.h conflict! +0x00 00-1F linux/wavefront.h conflict! +0x02 all linux/fd.h +0x03 all linux/hdreg.h +0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these. +0x06 all linux/lp.h +0x09 all linux/raid/md_u.h +0x10 00-0F drivers/char/s390/vmcp.h +0x10 10-1F arch/s390/include/uapi/sclp_ctl.h +0x10 20-2F arch/s390/include/uapi/asm/hypfs.h +0x12 all linux/fs.h + linux/blkpg.h +0x1b all InfiniBand Subsystem + <http://infiniband.sourceforge.net/> +0x20 all drivers/cdrom/cm206.h +0x22 all scsi/sg.h +'!' 00-1F uapi/linux/seccomp.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/> +'2' 01-04 linux/i2o.h +'3' 00-0F drivers/s390/char/raw3270.h conflict! +'3' 00-1F linux/suspend_ioctls.h, conflict! + kernel/power/user.c +'8' all SNP8023 advanced NIC card + <mailto:mcr@solidum.com> +';' 64-7F linux/vfio.h +'@' 00-0F linux/radeonfb.h conflict! +'@' 00-0F drivers/video/aty/aty128fb.c conflict! +'A' 00-1F linux/apm_bios.h conflict! +'A' 00-0F linux/agpgart.h, conflict! + drivers/char/agp/compat_ioctl.h +'A' 00-7F sound/asound.h conflict! +'B' 00-1F linux/cciss_ioctl.h conflict! +'B' 00-0F include/linux/pmu.h conflict! +'B' C0-FF advanced bbus <mailto:maassen@uni-freiburg.de> +'C' all linux/soundcard.h conflict! +'C' 01-2F linux/capi.h conflict! +'C' F0-FF drivers/net/wan/cosa.h conflict! +'D' all arch/s390/include/asm/dasd.h +'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h +'D' 05 drivers/scsi/pmcraid.h +'E' all linux/input.h conflict! +'E' 00-0F xen/evtchn.h conflict! +'F' all linux/fb.h conflict! +'F' 01-02 drivers/scsi/pmcraid.h conflict! +'F' 20 drivers/video/fsl-diu-fb.h conflict! +'F' 20 drivers/video/intelfb/intelfb.h conflict! +'F' 20 linux/ivtvfb.h conflict! +'F' 20 linux/matroxfb.h conflict! +'F' 20 drivers/video/aty/atyfb_base.c conflict! +'F' 00-0F video/da8xx-fb.h conflict! +'F' 80-8F linux/arcfb.h conflict! +'F' DD video/sstfb.h conflict! +'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict! +'G' 00-0F linux/gigaset_dev.h conflict! +'H' 00-7F linux/hiddev.h conflict! +'H' 00-0F linux/hidraw.h conflict! +'H' 01 linux/mei.h conflict! +'H' 02 linux/mei.h conflict! +'H' 03 linux/mei.h conflict! +'H' 00-0F sound/asound.h conflict! +'H' 20-40 sound/asound_fm.h conflict! +'H' 80-8F sound/sfnt_info.h conflict! +'H' 10-8F sound/emu10k1.h conflict! +'H' 10-1F sound/sb16_csp.h conflict! +'H' 10-1F sound/hda_hwdep.h conflict! +'H' 40-4F sound/hdspm.h conflict! +'H' 40-4F sound/hdsp.h conflict! +'H' 90 sound/usb/usx2y/usb_stream.h +'H' A0 uapi/linux/usb/cdc-wdm.h +'H' C0-F0 net/bluetooth/hci.h conflict! +'H' C0-DF net/bluetooth/hidp/hidp.h conflict! +'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict! +'H' C0-DF net/bluetooth/bnep/bnep.h conflict! +'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net> +'H' F8-FA sound/firewire.h +'I' all linux/isdn.h conflict! +'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict! +'I' 40-4F linux/mISDNif.h conflict! +'J' 00-1F drivers/scsi/gdth_ioctl.h +'K' all linux/kd.h +'L' 00-1F linux/loop.h conflict! +'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_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! +'M' 01-16 mtd/mtd-abi.h conflict! + and drivers/mtd/mtdchar.c +'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h +'M' 00-0F drivers/video/fsl-diu-fb.h conflict! +'N' 00-1F drivers/usb/scanner.h +'N' 40-7F drivers/block/nvme.c +'O' 00-06 mtd/ubi-user.h UBI +'P' all linux/soundcard.h conflict! +'P' 60-6F sound/sscape_ioctl.h conflict! +'P' 00-0F drivers/usb/class/usblp.c conflict! +'P' 01-09 drivers/misc/pci_endpoint_test.c conflict! +'Q' all linux/soundcard.h +'R' 00-1F linux/random.h conflict! +'R' 01 linux/rfkill.h conflict! +'R' C0-DF net/bluetooth/rfcomm.h +'S' all linux/cdrom.h conflict! +'S' 80-81 scsi/scsi_ioctl.h conflict! +'S' 82-FF scsi/scsi.h conflict! +'S' 00-7F sound/asequencer.h conflict! +'T' all linux/soundcard.h conflict! +'T' 00-AF sound/asound.h conflict! +'T' all arch/x86/include/asm/ioctls.h conflict! +'T' C0-DF linux/if_tun.h conflict! +'U' all sound/asound.h conflict! +'U' 00-CF linux/uinput.h conflict! +'U' 00-EF linux/usbdevice_fs.h +'U' C0-CF drivers/bluetooth/hci_uart.h +'V' all linux/vt.h conflict! +'V' all linux/videodev2.h conflict! +'V' C0 linux/ivtvfb.h conflict! +'V' C0 linux/ivtv.h conflict! +'V' C0 media/davinci/vpfe_capture.h conflict! +'V' C0 media/si4713.h conflict! +'W' 00-1F linux/watchdog.h conflict! +'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) +'W' 00-3F sound/asound.h conflict! +'W' 40-5F drivers/pci/switch/switchtec.c +'X' all fs/xfs/xfs_fs.h, conflict! + fs/xfs/linux-2.6/xfs_ioctl32.h, + include/linux/falloc.h, + linux/fs.h, +'X' all fs/ocfs2/ocfs_fs.h conflict! +'X' 01 linux/pktcdvd.h conflict! +'Y' all linux/cyclades.h +'Z' 14-15 drivers/message/fusion/mptctl.h +'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices + <mailto:gregkh@linuxfoundation.org> +'a' all linux/atm*.h, linux/sonet.h ATM on linux + <http://lrcwww.epfl.ch/> +'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver +'b' 00-FF conflict! bit3 vme host bridge + <mailto:natalia@nikhefk.nikhef.nl> +'c' all linux/cm4000_cs.h conflict! +'c' 00-7F linux/comstats.h conflict! +'c' 00-7F linux/coda.h conflict! +'c' 00-1F linux/chio.h conflict! +'c' 80-9F arch/s390/include/asm/chsc.h conflict! +'c' A0-AF arch/x86/include/asm/msr.h conflict! +'d' 00-FF linux/char/drm/drm.h conflict! +'d' 02-40 pcmcia/ds.h conflict! +'d' F0-FF linux/digi1.h +'e' all linux/digi1.h conflict! +'f' 00-1F linux/ext2_fs.h conflict! +'f' 00-1F linux/ext3_fs.h conflict! +'f' 00-0F fs/jfs/jfs_dinode.h conflict! +'f' 00-0F fs/ext4/ext4.h conflict! +'f' 00-0F linux/fs.h conflict! +'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict! +'g' 00-0F linux/usb/gadgetfs.h +'g' 20-2F linux/usb/g_printer.h +'h' 00-7F conflict! Charon filesystem + <mailto:zapman@interlan.net> +'h' 00-1F linux/hpet.h conflict! +'h' 80-8F fs/hfsplus/ioctl.c +'i' 00-3F linux/i2o-dev.h conflict! +'i' 0B-1F linux/ipmi.h conflict! +'i' 80-8F linux/i8k.h +'j' 00-3F linux/joystick.h +'k' 00-0F linux/spi/spidev.h conflict! +'k' 00-05 video/kyro.h conflict! +'k' 10-17 linux/hsi/hsi_char.h HSI character device +'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system + <http://web.archive.org/web/%2A/http://mikonos.dia.unisa.it/tcfs> +'l' 40-7F linux/udf_fs_i.h in development: + <http://sourceforge.net/projects/linux-udf/> +'m' 00-09 linux/mmtimer.h conflict! +'m' all linux/mtio.h conflict! +'m' all linux/soundcard.h conflict! +'m' all linux/synclink.h conflict! +'m' 00-19 drivers/message/fusion/mptctl.h conflict! +'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict! +'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c +'n' 80-8F uapi/linux/nilfs2_api.h NILFS2 +'n' E0-FF linux/matroxfb.h matroxfb +'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2 +'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps) +'o' 40-41 mtd/ubi-user.h UBI +'o' 01-A1 `linux/dvb/*.h` DVB +'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this) +'p' 00-1F linux/rtc.h conflict! +'p' 00-3F linux/mc146818rtc.h conflict! +'p' 40-7F linux/nvram.h +'p' 80-9F linux/ppdev.h user-space parport + <mailto:tim@cyberelk.net> +'p' A1-A5 linux/pps.h LinuxPPS + <mailto:giometti@linux.it> +'q' 00-1F linux/serio.h +'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK + linux/ixjuser.h <http://web.archive.org/web/%2A/http://www.quicknet.net> +'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c +'s' all linux/cdk.h +'t' 00-7F linux/ppp-ioctl.h +'t' 80-8F linux/isdn_ppp.h +'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM +'u' 00-1F linux/smb_fs.h gone +'u' 20-3F linux/uvcvideo.h USB video class host driver +'u' 40-4f linux/udmabuf.h userspace dma-buf misc device +'v' 00-1F linux/ext2_fs.h conflict! +'v' 00-1F linux/fs.h conflict! +'v' 00-0F linux/sonypi.h conflict! +'v' 00-0F media/v4l2-subdev.h conflict! +'v' C0-FF linux/meye.h conflict! +'w' all CERN SCI driver +'y' 00-1F packet based user level communications + <mailto:zapman@interlan.net> +'z' 00-3F CAN bus card conflict! + <mailto:hdstich@connectu.ulm.circular.de> +'z' 40-7F CAN bus card conflict! + <mailto:oe@port.de> +'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! +'|' 00-7F linux/media.h +0x80 00-1F linux/fb.h +0x89 00-06 arch/x86/include/asm/sockios.h +0x89 0B-DF linux/sockios.h +0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range +0x89 E0-EF linux/dn.h PROTOPRIVATE range +0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range +0x8B all linux/wireless.h +0x8C 00-3F WiNRADiO driver + <http://www.winradio.com.au/> +0x90 00 drivers/cdrom/sbpcd.h +0x92 00-0F drivers/usb/mon/mon_bin.c +0x93 60-7F linux/auto_fs.h +0x94 all fs/btrfs/ioctl.h Btrfs filesystem + and linux/fs.h some lifted to vfs/generic +0x97 00-7F fs/ceph/ioctl.h Ceph file system +0x99 00-0F 537-Addinboard driver + <mailto:buk@buks.ipn.de> +0xA0 all linux/sdp/sdp.h Industrial Device Project + <mailto:kenji@bitgate.com> +0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver +0xA3 80-8F Port ACL in development: + <mailto:tlewis@mindspring.com> +0xA3 90-9F linux/dtlk.h +0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem +0xAA 00-3F linux/uapi/linux/userfaultfd.h +0xAB 00-1F linux/nbd.h +0xAC 00-1F linux/raw.h +0xAD 00 Netfilter device in development: + <mailto:rusty@rustcorp.com.au> +0xAE all linux/kvm.h Kernel-based Virtual Machine + <mailto:kvm@vger.kernel.org> +0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor +0xB0 all RATIO devices in development: + <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> +0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> +0xB6 all linux/fpga-dfl.h +0xC0 00-0F linux/usb/iowarrior.h +0xCA 00-0F uapi/misc/cxl.h +0xCA 10-2F uapi/misc/ocxl.h +0xCA 80-BF uapi/scsi/cxlflash_ioctl.h +0xCB 00-1F CBM serial IEC bus in development: + <mailto:michael.klein@puffin.lb.shuttle.de> +0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver +0xCD 01 linux/reiserfs_fs.h +0xCF 02 fs/cifs/ioctl.c +0xDB 00-0F drivers/char/mwave/mwavepub.h +0xDD 00-3F ZFCP device driver see drivers/s390/scsi/ + <mailto:aherrman@de.ibm.com> +0xE5 00-3F linux/fuse.h +0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver +0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development) + <mailto:thomas@winischhofer.net> +0xF4 00-1F video/mbxfb.h mbxfb + <mailto:raph@8d.com> +0xF6 all LTTng Linux Trace Toolkit Next Generation + <mailto:mathieu.desnoyers@efficios.com> +0xFD all linux/dm-ioctl.h +0xFE all linux/isst_if.h +==== ===== ======================================================= ================================================================ diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt deleted file mode 100644 index c9558146ac58..000000000000 --- a/Documentation/ioctl/ioctl-number.txt +++ /dev/null @@ -1,350 +0,0 @@ -Ioctl Numbers -19 October 1999 -Michael Elizabeth Chastain -<mec@shout.net> - -If you are adding new ioctl's to the kernel, you should use the _IO -macros defined in <linux/ioctl.h>: - - _IO an ioctl with no parameters - _IOW an ioctl with write parameters (copy_from_user) - _IOR an ioctl with read parameters (copy_to_user) - _IOWR an ioctl with both write and read parameters. - -'Write' and 'read' are from the user's point of view, just like the -system calls 'write' and 'read'. For example, a SET_FOO ioctl would -be _IOW, although the kernel would actually read data from user space; -a GET_FOO ioctl would be _IOR, although the kernel would actually write -data to user space. - -The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter -or number from the table below. Because of the large number of drivers, -many drivers share a partial letter with other drivers. - -If you are writing a driver for a new device and need a letter, pick an -unused block with enough room for expansion: 32 to 256 ioctl commands. -You can register the block by patching this file and submitting the -patch to Linus Torvalds. Or you can e-mail me at <mec@shout.net> and -I'll register one for you. - -The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number -to distinguish ioctls from each other. The third argument to _IOW, -_IOR, or _IOWR is the type of the data going into the kernel or coming -out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use -sizeof(arg) as the third argument as this results in your ioctl thinking -it passes an argument of type size_t. - -Some devices use their major number as the identifier; this is OK, as -long as it is unique. Some devices are irregular and don't follow any -convention at all. - -Following this convention is good because: - -(1) Keeping the ioctl's globally unique helps error checking: - if a program calls an ioctl on the wrong device, it will get an - error rather than some unexpected behaviour. - -(2) The 'strace' build procedure automatically finds ioctl numbers - defined with _IO, _IOW, _IOR, or _IOWR. - -(3) 'strace' can decode numbers back into useful names when the - numbers are unique. - -(4) People looking for ioctls can grep for them more easily when - this convention is used to define the ioctl numbers. - -(5) When following the convention, the driver code can use generic - code to copy the parameters between user and kernel space. - -This table lists ioctls visible from user land for Linux/x86. It contains -most drivers up to 2.6.31, but I know I am missing some. There has been -no attempt to list non-X86 architectures or ioctls from drivers/staging/. - -Code Seq#(hex) Include File Comments -======================================================== -0x00 00-1F linux/fs.h conflict! -0x00 00-1F scsi/scsi_ioctl.h conflict! -0x00 00-1F linux/fb.h conflict! -0x00 00-1F linux/wavefront.h conflict! -0x02 all linux/fd.h -0x03 all linux/hdreg.h -0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these. -0x06 all linux/lp.h -0x09 all linux/raid/md_u.h -0x10 00-0F drivers/char/s390/vmcp.h -0x10 10-1F arch/s390/include/uapi/sclp_ctl.h -0x10 20-2F arch/s390/include/uapi/asm/hypfs.h -0x12 all linux/fs.h - linux/blkpg.h -0x1b all InfiniBand Subsystem <http://infiniband.sourceforge.net/> -0x20 all drivers/cdrom/cm206.h -0x22 all scsi/sg.h -'!' 00-1F uapi/linux/seccomp.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/> -'2' 01-04 linux/i2o.h -'3' 00-0F drivers/s390/char/raw3270.h conflict! -'3' 00-1F linux/suspend_ioctls.h conflict! - and kernel/power/user.c -'8' all SNP8023 advanced NIC card - <mailto:mcr@solidum.com> -';' 64-7F linux/vfio.h -'@' 00-0F linux/radeonfb.h conflict! -'@' 00-0F drivers/video/aty/aty128fb.c conflict! -'A' 00-1F linux/apm_bios.h conflict! -'A' 00-0F linux/agpgart.h conflict! - and drivers/char/agp/compat_ioctl.h -'A' 00-7F sound/asound.h conflict! -'B' 00-1F linux/cciss_ioctl.h conflict! -'B' 00-0F include/linux/pmu.h conflict! -'B' C0-FF advanced bbus - <mailto:maassen@uni-freiburg.de> -'C' all linux/soundcard.h conflict! -'C' 01-2F linux/capi.h conflict! -'C' F0-FF drivers/net/wan/cosa.h conflict! -'D' all arch/s390/include/asm/dasd.h -'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h -'D' 05 drivers/scsi/pmcraid.h -'E' all linux/input.h conflict! -'E' 00-0F xen/evtchn.h conflict! -'F' all linux/fb.h conflict! -'F' 01-02 drivers/scsi/pmcraid.h conflict! -'F' 20 drivers/video/fsl-diu-fb.h conflict! -'F' 20 drivers/video/intelfb/intelfb.h conflict! -'F' 20 linux/ivtvfb.h conflict! -'F' 20 linux/matroxfb.h conflict! -'F' 20 drivers/video/aty/atyfb_base.c conflict! -'F' 00-0F video/da8xx-fb.h conflict! -'F' 80-8F linux/arcfb.h conflict! -'F' DD video/sstfb.h conflict! -'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict! -'G' 00-0F linux/gigaset_dev.h conflict! -'H' 00-7F linux/hiddev.h conflict! -'H' 00-0F linux/hidraw.h conflict! -'H' 01 linux/mei.h conflict! -'H' 02 linux/mei.h conflict! -'H' 03 linux/mei.h conflict! -'H' 00-0F sound/asound.h conflict! -'H' 20-40 sound/asound_fm.h conflict! -'H' 80-8F sound/sfnt_info.h conflict! -'H' 10-8F sound/emu10k1.h conflict! -'H' 10-1F sound/sb16_csp.h conflict! -'H' 10-1F sound/hda_hwdep.h conflict! -'H' 40-4F sound/hdspm.h conflict! -'H' 40-4F sound/hdsp.h conflict! -'H' 90 sound/usb/usx2y/usb_stream.h -'H' A0 uapi/linux/usb/cdc-wdm.h -'H' C0-F0 net/bluetooth/hci.h conflict! -'H' C0-DF net/bluetooth/hidp/hidp.h conflict! -'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict! -'H' C0-DF net/bluetooth/bnep/bnep.h conflict! -'H' F1 linux/hid-roccat.h <mailto:erazor_de@users.sourceforge.net> -'H' F8-FA sound/firewire.h -'I' all linux/isdn.h conflict! -'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict! -'I' 40-4F linux/mISDNif.h conflict! -'J' 00-1F drivers/scsi/gdth_ioctl.h -'K' all linux/kd.h -'L' 00-1F linux/loop.h conflict! -'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_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! -'M' 01-16 mtd/mtd-abi.h conflict! - and drivers/mtd/mtdchar.c -'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h -'M' 00-0F drivers/video/fsl-diu-fb.h conflict! -'N' 00-1F drivers/usb/scanner.h -'N' 40-7F drivers/block/nvme.c -'O' 00-06 mtd/ubi-user.h UBI -'P' all linux/soundcard.h conflict! -'P' 60-6F sound/sscape_ioctl.h conflict! -'P' 00-0F drivers/usb/class/usblp.c conflict! -'P' 01-09 drivers/misc/pci_endpoint_test.c conflict! -'Q' all linux/soundcard.h -'R' 00-1F linux/random.h conflict! -'R' 01 linux/rfkill.h conflict! -'R' C0-DF net/bluetooth/rfcomm.h -'S' all linux/cdrom.h conflict! -'S' 80-81 scsi/scsi_ioctl.h conflict! -'S' 82-FF scsi/scsi.h conflict! -'S' 00-7F sound/asequencer.h conflict! -'T' all linux/soundcard.h conflict! -'T' 00-AF sound/asound.h conflict! -'T' all arch/x86/include/asm/ioctls.h conflict! -'T' C0-DF linux/if_tun.h conflict! -'U' all sound/asound.h conflict! -'U' 00-CF linux/uinput.h conflict! -'U' 00-EF linux/usbdevice_fs.h -'U' C0-CF drivers/bluetooth/hci_uart.h -'V' all linux/vt.h conflict! -'V' all linux/videodev2.h conflict! -'V' C0 linux/ivtvfb.h conflict! -'V' C0 linux/ivtv.h conflict! -'V' C0 media/davinci/vpfe_capture.h conflict! -'V' C0 media/si4713.h conflict! -'W' 00-1F linux/watchdog.h conflict! -'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) -'W' 00-3F sound/asound.h conflict! -'W' 40-5F drivers/pci/switch/switchtec.c -'X' all fs/xfs/xfs_fs.h conflict! - and fs/xfs/linux-2.6/xfs_ioctl32.h - and include/linux/falloc.h - and linux/fs.h -'X' all fs/ocfs2/ocfs_fs.h conflict! -'X' 01 linux/pktcdvd.h conflict! -'Y' all linux/cyclades.h -'Z' 14-15 drivers/message/fusion/mptctl.h -'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices - <mailto:gregkh@linuxfoundation.org> -'a' all linux/atm*.h, linux/sonet.h ATM on linux - <http://lrcwww.epfl.ch/> -'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver -'b' 00-FF conflict! bit3 vme host bridge - <mailto:natalia@nikhefk.nikhef.nl> -'c' all linux/cm4000_cs.h conflict! -'c' 00-7F linux/comstats.h conflict! -'c' 00-7F linux/coda.h conflict! -'c' 00-1F linux/chio.h conflict! -'c' 80-9F arch/s390/include/asm/chsc.h conflict! -'c' A0-AF arch/x86/include/asm/msr.h conflict! -'d' 00-FF linux/char/drm/drm.h conflict! -'d' 02-40 pcmcia/ds.h conflict! -'d' F0-FF linux/digi1.h -'e' all linux/digi1.h conflict! -'f' 00-1F linux/ext2_fs.h conflict! -'f' 00-1F linux/ext3_fs.h conflict! -'f' 00-0F fs/jfs/jfs_dinode.h conflict! -'f' 00-0F fs/ext4/ext4.h conflict! -'f' 00-0F linux/fs.h conflict! -'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict! -'g' 00-0F linux/usb/gadgetfs.h -'g' 20-2F linux/usb/g_printer.h -'h' 00-7F conflict! Charon filesystem - <mailto:zapman@interlan.net> -'h' 00-1F linux/hpet.h conflict! -'h' 80-8F fs/hfsplus/ioctl.c -'i' 00-3F linux/i2o-dev.h conflict! -'i' 0B-1F linux/ipmi.h conflict! -'i' 80-8F linux/i8k.h -'j' 00-3F linux/joystick.h -'k' 00-0F linux/spi/spidev.h conflict! -'k' 00-05 video/kyro.h conflict! -'k' 10-17 linux/hsi/hsi_char.h HSI character device -'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system - <http://web.archive.org/web/*/http://mikonos.dia.unisa.it/tcfs> -'l' 40-7F linux/udf_fs_i.h in development: - <http://sourceforge.net/projects/linux-udf/> -'m' 00-09 linux/mmtimer.h conflict! -'m' all linux/mtio.h conflict! -'m' all linux/soundcard.h conflict! -'m' all linux/synclink.h conflict! -'m' 00-19 drivers/message/fusion/mptctl.h conflict! -'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict! -'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c -'n' 80-8F uapi/linux/nilfs2_api.h NILFS2 -'n' E0-FF linux/matroxfb.h matroxfb -'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2 -'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps) -'o' 40-41 mtd/ubi-user.h UBI -'o' 01-A1 linux/dvb/*.h DVB -'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this) -'p' 00-1F linux/rtc.h conflict! -'p' 00-3F linux/mc146818rtc.h conflict! -'p' 40-7F linux/nvram.h -'p' 80-9F linux/ppdev.h user-space parport - <mailto:tim@cyberelk.net> -'p' A1-A5 linux/pps.h LinuxPPS - <mailto:giometti@linux.it> -'q' 00-1F linux/serio.h -'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK - linux/ixjuser.h <http://web.archive.org/web/*/http://www.quicknet.net> -'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c -'s' all linux/cdk.h -'t' 00-7F linux/ppp-ioctl.h -'t' 80-8F linux/isdn_ppp.h -'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM -'u' 00-1F linux/smb_fs.h gone -'u' 20-3F linux/uvcvideo.h USB video class host driver -'u' 40-4f linux/udmabuf.h userspace dma-buf misc device -'v' 00-1F linux/ext2_fs.h conflict! -'v' 00-1F linux/fs.h conflict! -'v' 00-0F linux/sonypi.h conflict! -'v' 00-0F media/v4l2-subdev.h conflict! -'v' C0-FF linux/meye.h conflict! -'w' all CERN SCI driver -'y' 00-1F packet based user level communications - <mailto:zapman@interlan.net> -'z' 00-3F CAN bus card conflict! - <mailto:hdstich@connectu.ulm.circular.de> -'z' 40-7F CAN bus card conflict! - <mailto:oe@port.de> -'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! -'|' 00-7F linux/media.h -0x80 00-1F linux/fb.h -0x89 00-06 arch/x86/include/asm/sockios.h -0x89 0B-DF linux/sockios.h -0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range -0x89 E0-EF linux/dn.h PROTOPRIVATE range -0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range -0x8B all linux/wireless.h -0x8C 00-3F WiNRADiO driver - <http://www.winradio.com.au/> -0x90 00 drivers/cdrom/sbpcd.h -0x92 00-0F drivers/usb/mon/mon_bin.c -0x93 60-7F linux/auto_fs.h -0x94 all fs/btrfs/ioctl.h Btrfs filesystem - and linux/fs.h some lifted to vfs/generic -0x97 00-7F fs/ceph/ioctl.h Ceph file system -0x99 00-0F 537-Addinboard driver - <mailto:buk@buks.ipn.de> -0xA0 all linux/sdp/sdp.h Industrial Device Project - <mailto:kenji@bitgate.com> -0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver -0xA3 80-8F Port ACL in development: - <mailto:tlewis@mindspring.com> -0xA3 90-9F linux/dtlk.h -0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem -0xAA 00-3F linux/uapi/linux/userfaultfd.h -0xAB 00-1F linux/nbd.h -0xAC 00-1F linux/raw.h -0xAD 00 Netfilter device in development: - <mailto:rusty@rustcorp.com.au> -0xAE all linux/kvm.h Kernel-based Virtual Machine - <mailto:kvm@vger.kernel.org> -0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor -0xB0 all RATIO devices in development: - <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> -0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> -0xB6 all linux/fpga-dfl.h -0xC0 00-0F linux/usb/iowarrior.h -0xCA 00-0F uapi/misc/cxl.h -0xCA 10-2F uapi/misc/ocxl.h -0xCA 80-BF uapi/scsi/cxlflash_ioctl.h -0xCB 00-1F CBM serial IEC bus in development: - <mailto:michael.klein@puffin.lb.shuttle.de> -0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver -0xCD 01 linux/reiserfs_fs.h -0xCF 02 fs/cifs/ioctl.c -0xDB 00-0F drivers/char/mwave/mwavepub.h -0xDD 00-3F ZFCP device driver see drivers/s390/scsi/ - <mailto:aherrman@de.ibm.com> -0xE5 00-3F linux/fuse.h -0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver -0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development) - <mailto:thomas@winischhofer.net> -0xF4 00-1F video/mbxfb.h mbxfb - <mailto:raph@8d.com> -0xF6 all LTTng Linux Trace Toolkit Next Generation - <mailto:mathieu.desnoyers@efficios.com> -0xFD all linux/dm-ioctl.h diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst index 42d4cbe4460c..e323a3f2cc81 100644 --- a/Documentation/kbuild/index.rst +++ b/Documentation/kbuild/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 =================== Kernel Build System diff --git a/Documentation/kbuild/issues.rst b/Documentation/kbuild/issues.rst index 9fdded4b681c..bdab01f733f6 100644 --- a/Documentation/kbuild/issues.rst +++ b/Documentation/kbuild/issues.rst @@ -1,11 +1,15 @@ -Recursion issue #1 ------------------- +================ +Recursion issues +================ - .. include:: Kconfig.recursion-issue-01 - :literal: +issue #1 +-------- -Recursion issue #2 ------------------- +.. literalinclude:: Kconfig.recursion-issue-01 + :language: kconfig - .. include:: Kconfig.recursion-issue-02 - :literal: +issue #2 +-------- + +.. literalinclude:: Kconfig.recursion-issue-02 + :language: kconfig diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst index b25548963d70..61b2181ed3ea 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -18,7 +18,7 @@ This file lists all modules that are built into the kernel. This is used by modprobe to not fail when trying to load something builtin. modules.builtin.modinfo --------------------------------------------------- +----------------------- This file contains modinfo from all modules that are built into the kernel. Unlike modinfo of a separate module, all fields are prefixed with module name. @@ -38,12 +38,11 @@ Additional options to the assembler (for built-in and modules). AFLAGS_MODULE ------------- -Additional module specific options to use for $(AS). +Additional assembler options for modules. AFLAGS_KERNEL ------------- -Additional options for $(AS) when used for assembler -code for code that is compiled as built-in. +Additional assembler options for built-in. KCFLAGS ------- @@ -153,6 +152,7 @@ Install script called when using "make install". The default name is "installkernel". The script will be called with the following arguments: + - $1 - kernel version - $2 - kernel image file - $3 - kernel map file diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 2bc8a7803365..74bef19f69f0 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -53,6 +53,7 @@ A menu entry can have a number of attributes. Not all of them are applicable everywhere (see syntax). - type definition: "bool"/"tristate"/"string"/"hex"/"int" + Every config option must have a type. There are only two basic types: tristate and string; the other types are based on these two. The type definition optionally accepts an input prompt, so these two examples @@ -66,11 +67,13 @@ applicable everywhere (see syntax). prompt "Networking support" - input prompt: "prompt" <prompt> ["if" <expr>] + Every menu entry can have at most one prompt, which is used to display to the user. Optionally dependencies only for this prompt can be added with "if". - default value: "default" <expr> ["if" <expr>] + A config option can have any number of default values. If multiple default values are visible, only the first defined one is active. Default values are not limited to the menu entry where they are @@ -112,6 +115,7 @@ applicable everywhere (see syntax). Optionally dependencies for this default value can be added with "if". - dependencies: "depends on" <expr> + This defines a dependency for this menu entry. If multiple dependencies are defined, they are connected with '&&'. Dependencies are applied to all other options within this menu entry (which also @@ -127,6 +131,7 @@ applicable everywhere (see syntax). default y - reverse dependencies: "select" <symbol> ["if" <expr>] + While normal dependencies reduce the upper limit of a symbol (see below), reverse dependencies can be used to force a lower limit of another symbol. The value of the current menu symbol is used as the @@ -146,6 +151,7 @@ applicable everywhere (see syntax). the illegal configurations all over. - weak reverse dependencies: "imply" <symbol> ["if" <expr>] + This is similar to "select" as it enforces a lower limit on another symbol except that the "implied" symbol's value may still be set to n from a direct dependency or with a visible prompt. @@ -176,6 +182,7 @@ applicable everywhere (see syntax). configure that subsystem out without also having to unset these drivers. - limiting menu display: "visible if" <expr> + This attribute is only applicable to menu blocks, if the condition is false, the menu block is not displayed to the user (the symbols contained there can still be selected by other symbols, though). It is @@ -183,12 +190,14 @@ applicable everywhere (see syntax). entries. Default value of "visible" is true. - numerical ranges: "range" <symbol> <symbol> ["if" <expr>] + This allows to limit the range of possible input values for int and hex symbols. The user can only input a value which is larger than or equal to the first symbol and smaller than or equal to the second symbol. - help text: "help" or "---help---" + This defines a help text. The end of the help text is determined by the indentation level, this means it ends at the first line which has a smaller indentation than the first line of the help text. @@ -197,6 +206,7 @@ applicable everywhere (see syntax). the file as an aid to developers. - misc options: "option" <symbol>[=<value>] + Various less common options can be defined via this option syntax, which can modify the behaviour of the menu entry and its config symbol. These options are currently possible: @@ -325,6 +335,7 @@ end a menu entry: The first five also start the definition of a menu entry. config:: + "config" <symbol> <config options> @@ -332,6 +343,7 @@ This defines a config symbol <symbol> and accepts any of above attributes as options. menuconfig:: + "menuconfig" <symbol> <config options> diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index 88129af7e539..a9a855f894b3 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -264,6 +264,7 @@ NCONFIG_MODE This mode shows all sub-menus in one large tree. Example:: + make NCONFIG_MODE=single_menu nconfig ---------------------------------------------------------------------- @@ -277,9 +278,12 @@ Searching in xconfig: names, so you have to know something close to what you are looking for. - Example: + Example:: + Ctrl-F hotplug - or + + or:: + Menu: File, Search, hotplug lists all config symbol entries that contain "hotplug" in diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 093f2d79ab95..f4f0f7ffde2b 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -328,7 +328,7 @@ more details, with real examples. variable $(KBUILD_CFLAGS) and uses it for compilation flags for the entire tree. - asflags-y specifies options for assembling with $(AS). + asflags-y specifies assembler options. Example:: @@ -384,6 +384,7 @@ more details, with real examples. ----------------------- Kbuild tracks dependencies on the following: + 1) All prerequisite files (both `*.c` and `*.h`) 2) `CONFIG_` options used in all prerequisite files 3) Command-line used to compile target @@ -489,7 +490,7 @@ more details, with real examples. as-instr checks if the assembler reports a specific instruction and then outputs either option1 or option2 C escapes are supported in the test instruction - Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options + Note: as-instr-option uses KBUILD_AFLAGS for assembler options cc-option cc-option is used to check if $(CC) supports a given option, and if @@ -905,7 +906,7 @@ When kbuild executes, the following steps are followed (roughly): vmlinux. The usage of $(call if_changed,xxx) will be described later. KBUILD_AFLAGS - $(AS) assembler flags + Assembler flags Default value - see top level Makefile Append or modify as required per architecture. @@ -948,16 +949,16 @@ When kbuild executes, the following steps are followed (roughly): to 'y' when selected. KBUILD_AFLAGS_KERNEL - $(AS) options specific for built-in + Assembler options specific for built-in $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile resident kernel code. KBUILD_AFLAGS_MODULE - Options for $(AS) when building modules + Assembler options specific for modules $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that - are used for $(AS). + are used for assembler. From commandline AFLAGS_MODULE shall be used (see kbuild.txt). diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index dc698ea456e0..a8518ac0d31d 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -1364,7 +1364,7 @@ Futex API reference Further reading =============== -- ``Documentation/locking/spinlocks.txt``: Linus Torvalds' spinlocking +- ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking tutorial in the kernel sources. - Unix Systems for Modern Architectures: Symmetric Multiprocessing and diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst index 9885f7c1b75d..060f4e485897 100644 --- a/Documentation/leds/index.rst +++ b/Documentation/leds/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ==== LEDs diff --git a/Documentation/livepatch/index.rst b/Documentation/livepatch/index.rst index edd291d51847..17674a9e21b2 100644 --- a/Documentation/livepatch/index.rst +++ b/Documentation/livepatch/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 =================== Kernel Livepatching diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst new file mode 100644 index 000000000000..626a463f7e42 --- /dev/null +++ b/Documentation/locking/index.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +locking +======= + +.. toctree:: + :maxdepth: 1 + + lockdep-design + lockstat + locktorture + mutex-design + rt-mutex-design + rt-mutex + spinlocks + ww-mutex-design + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.rst index f189d130e543..23fcbc4d3fc0 100644 --- a/Documentation/locking/lockdep-design.txt +++ b/Documentation/locking/lockdep-design.rst @@ -2,6 +2,7 @@ Runtime locking correctness validator ===================================== started by Ingo Molnar <mingo@redhat.com> + additions by Arjan van de Ven <arjan@linux.intel.com> Lock-class @@ -56,7 +57,7 @@ where the last 1 category is: When locking rules are violated, these usage bits are presented in the locking error messages, inside curlies, with a total of 2 * n STATEs bits. -A contrived example: +A contrived example:: modprobe/2287 is trying to acquire lock: (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24 @@ -70,12 +71,14 @@ of the lock and readlock (if exists), for each of the n STATEs listed above respectively, and the character displayed at each bit position indicates: + === =================================================== '.' acquired while irqs disabled and not in irq context '-' acquired in irq context '+' acquired with irqs enabled '?' acquired in irq context with irqs enabled. + === =================================================== -The bits are illustrated with an example: +The bits are illustrated with an example:: (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24 |||| @@ -90,13 +93,13 @@ context and whether that STATE is enabled yields four possible cases as shown in the table below. The bit character is able to indicate which exact case is for the lock as of the reporting time. - ------------------------------------------- + +--------------+-------------+--------------+ | | irq enabled | irq disabled | - |-------------------------------------------| + +--------------+-------------+--------------+ | ever in irq | ? | - | - |-------------------------------------------| + +--------------+-------------+--------------+ | never in irq | + | . | - ------------------------------------------- + +--------------+-------------+--------------+ The character '-' suggests irq is disabled because if otherwise the charactor '?' would have been shown instead. Similar deduction can be @@ -113,7 +116,7 @@ is irq-unsafe means it was ever acquired with irq enabled. A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The following states must be exclusive: only one of them is allowed to be set -for any lock-class based on its usage: +for any lock-class based on its usage:: <hardirq-safe> or <hardirq-unsafe> <softirq-safe> or <softirq-unsafe> @@ -134,7 +137,7 @@ Multi-lock dependency rules: The same lock-class must not be acquired twice, because this could lead to lock recursion deadlocks. -Furthermore, two locks can not be taken in inverse order: +Furthermore, two locks can not be taken in inverse order:: <L1> -> <L2> <L2> -> <L1> @@ -148,7 +151,7 @@ operations; the validator will still find whether these locks can be acquired in a circular fashion. Furthermore, the following usage based lock dependencies are not allowed -between any two lock-classes: +between any two lock-classes:: <hardirq-safe> -> <hardirq-unsafe> <softirq-safe> -> <softirq-unsafe> @@ -204,16 +207,16 @@ the ordering is not static. In order to teach the validator about this correct usage model, new versions of the various locking primitives were added that allow you to specify a "nesting level". An example call, for the block device mutex, -looks like this: +looks like this:: -enum bdev_bd_mutex_lock_class -{ + enum bdev_bd_mutex_lock_class + { BD_MUTEX_NORMAL, BD_MUTEX_WHOLE, BD_MUTEX_PARTITION -}; + }; - mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION); +mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION); In this case the locking is done on a bdev object that is known to be a partition. @@ -234,7 +237,7 @@ must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock). As the name suggests, lockdep_assert_held* family of macros assert that a particular lock is held at a certain time (and generate a WARN() otherwise). This annotation is largely used all over the kernel, e.g. kernel/sched/ -core.c +core.c:: void update_rq_clock(struct rq *rq) { @@ -253,7 +256,7 @@ out to be especially helpful to debug code with callbacks, where an upper layer assumes a lock remains taken, but a lower layer thinks it can maybe drop and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock() returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check -that nobody tampered with the lock, e.g. kernel/sched/sched.h +that nobody tampered with the lock, e.g. kernel/sched/sched.h:: static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) { @@ -280,7 +283,7 @@ correctness) in the sense that for every simple, standalone single-task locking sequence that occurred at least once during the lifetime of the kernel, the validator proves it with a 100% certainty that no combination and timing of these locking sequences can cause any class of -lock related deadlock. [*] +lock related deadlock. [1]_ I.e. complex multi-CPU and multi-task locking scenarios do not have to occur in practice to prove a deadlock: only the simple 'component' @@ -299,7 +302,9 @@ possible combination of locking interaction between CPUs, combined with every possible hardirq and softirq nesting scenario (which is impossible to do in practice). -[*] assuming that the validator itself is 100% correct, and no other +.. [1] + + assuming that the validator itself is 100% correct, and no other part of the system corrupts the state of the validator in any way. We also assume that all NMI/SMM paths [which could interrupt even hardirq-disabled codepaths] are correct and do not interfere @@ -310,7 +315,7 @@ to do in practice). Performance: ------------ -The above rules require _massive_ amounts of runtime checking. If we did +The above rules require **massive** amounts of runtime checking. If we did that for every lock taken and for every irqs-enable event, it would render the system practically unusably slow. The complexity of checking is O(N^2), so even with just a few hundred lock-classes we'd have to do @@ -369,17 +374,17 @@ be harder to do than to say. Of course, if you do run out of lock classes, the next thing to do is to find the offending lock classes. First, the following command gives -you the number of lock classes currently in use along with the maximum: +you the number of lock classes currently in use along with the maximum:: grep "lock-classes" /proc/lockdep_stats -This command produces the following output on a modest system: +This command produces the following output on a modest system:: - lock-classes: 748 [max: 8191] + lock-classes: 748 [max: 8191] If the number allocated (748 above) increases continually over time, then there is likely a leak. The following command can be used to -identify the leaking lock classes: +identify the leaking lock classes:: grep "BD" /proc/lockdep diff --git a/Documentation/locking/lockstat.rst b/Documentation/locking/lockstat.rst new file mode 100644 index 000000000000..536eab8dbd99 --- /dev/null +++ b/Documentation/locking/lockstat.rst @@ -0,0 +1,204 @@ +=============== +Lock Statistics +=============== + +What +==== + +As the name suggests, it provides statistics on locks. + + +Why +=== + +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/locking/lockdep-design.rst). +The graph below shows the relation between the lock functions and the various +hooks therein:: + + __acquire + | + lock _____ + | \ + | __contended + | | + | <wait> + | _______/ + |/ + | + __acquired + | + . + <hold> + . + | + __release + | + unlock + + lock, unlock - the regular lock functions + __* - the hooks + <> - states + +With these hooks we provide the following statistics: + + con-bounces + - number of lock contention that involved x-cpu data + contentions + - number of lock acquisitions that had to wait + wait time + min + - shortest (non-0) time we ever had to wait for a lock + max + - longest time we ever had to wait for a lock + total + - total time we spend waiting on this lock + avg + - average time spent waiting on this lock + acq-bounces + - number of lock acquisitions that involved x-cpu data + acquisitions + - number of times we took the lock + hold time + min + - shortest (non-0) time we ever held the lock + max + - longest time we ever held the lock + total + - total time this lock was held + avg + - average time this lock was held + +These numbers are gathered per lock class, per read/write state (when +applicable). + +It also tracks 4 contention points per class. A contention point is a call site +that had to wait on lock acquisition. + +Configuration +------------- + +Lock statistics are enabled via CONFIG_LOCK_STAT. + +Usage +----- + +Enable collection of statistics:: + + # echo 1 >/proc/sys/kernel/lock_stat + +Disable collection of statistics:: + + # echo 0 >/proc/sys/kernel/lock_stat + +Look at the current lock statistics:: + + ( line numbers not part of actual output, done for clarity in the explanation + below ) + + # less /proc/lock_stat + + 01 lock_stat version 0.4 + 02----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg + 04----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + 05 + 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99 + 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77 + 08 --------------- + 09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280 + 10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510 + 11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0 + 12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80 + 13 --------------- + 14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0 + 15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250 + 16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510 + 17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0 + 18 + 19............................................................................................................................................................................................................................. + 20 + 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48 + 22 --------------- + 23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0 + 24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250 + 25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230 + 26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0 + 27 --------------- + 28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250 + 29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0 + 30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230 + 31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0 + + +This excerpt shows the first two lock class statistics. Line 01 shows the +output version - each time the format changes this will be updated. Line 02-04 +show the header with column descriptions. Lines 05-18 and 20-31 show the actual +statistics. These statistics come in two parts; the actual stats separated by a +short separator (line 08, 13) from the contention points. + +Lines 09-12 show the first 4 recorded contention points (the code +which tries to get the lock) and lines 14-17 show the first 4 recorded +contended points (the lock holder). It is possible that the max +con-bounces point is missing in the statistics. + +The first lock (05-18) is a read/write lock, and shows two lines above the +short separator. The contention points don't match the column descriptors, +they have two: contentions and [<IP>] symbol. The second set of contention +points are the points we're contending with. + +The integer part of the time values is in us. + +Dealing with nested locks, subclasses may appear:: + + 32........................................................................................................................................................................................................................... + 33 + 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82 + 35 --------- + 36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75 + 37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a + 38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a + 39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb + 40 --------- + 41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75 + 42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a + 43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54 + 44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8 + 45 + 46........................................................................................................................................................................................................................... + 47 + 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84 + 49 ----------- + 50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54 + 51 ----------- + 52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54 + 53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8 + 54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54 + 55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a + +Line 48 shows statistics for the second subclass (/1) of &rq->lock class +(subclass starts from 0), since in this case, as line 50 suggests, +double_rq_lock actually acquires a nested lock of two spinlocks. + +View the top contending locks:: + + # grep : /proc/lock_stat | head + clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71 + tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59 + &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59 + &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69 + &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93 + tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72 + tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89 + rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89 + &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27 + rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76 + +Clear the statistics:: + + # echo 0 > /proc/lock_stat diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt deleted file mode 100644 index fdbeb0c45ef3..000000000000 --- a/Documentation/locking/lockstat.txt +++ /dev/null @@ -1,183 +0,0 @@ - -LOCK STATISTICS - -- WHAT - -As the name suggests, it provides statistics on locks. - -- WHY - -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/locking/lockdep-design.txt). -The graph below shows the relation between the lock functions and the various -hooks therein. - - __acquire - | - lock _____ - | \ - | __contended - | | - | <wait> - | _______/ - |/ - | - __acquired - | - . - <hold> - . - | - __release - | - unlock - -lock, unlock - the regular lock functions -__* - the hooks -<> - states - -With these hooks we provide the following statistics: - - con-bounces - number of lock contention that involved x-cpu data - contentions - number of lock acquisitions that had to wait - wait time min - shortest (non-0) time we ever had to wait for a lock - max - longest time we ever had to wait for a lock - total - total time we spend waiting on this lock - avg - average time spent waiting on this lock - acq-bounces - number of lock acquisitions that involved x-cpu data - acquisitions - number of times we took the lock - hold time min - shortest (non-0) time we ever held the lock - max - longest time we ever held the lock - total - total time this lock was held - avg - average time this lock was held - -These numbers are gathered per lock class, per read/write state (when -applicable). - -It also tracks 4 contention points per class. A contention point is a call site -that had to wait on lock acquisition. - - - CONFIGURATION - -Lock statistics are enabled via CONFIG_LOCK_STAT. - - - USAGE - -Enable collection of statistics: - -# echo 1 >/proc/sys/kernel/lock_stat - -Disable collection of statistics: - -# echo 0 >/proc/sys/kernel/lock_stat - -Look at the current lock statistics: - -( line numbers not part of actual output, done for clarity in the explanation - below ) - -# less /proc/lock_stat - -01 lock_stat version 0.4 -02----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg -04----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -05 -06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99 -07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77 -08 --------------- -09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280 -10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510 -11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0 -12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80 -13 --------------- -14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0 -15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250 -16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510 -17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0 -18 -19............................................................................................................................................................................................................................. -20 -21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48 -22 --------------- -23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0 -24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250 -25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230 -26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0 -27 --------------- -28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250 -29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0 -30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230 -31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0 - - -This excerpt shows the first two lock class statistics. Line 01 shows the -output version - each time the format changes this will be updated. Line 02-04 -show the header with column descriptions. Lines 05-18 and 20-31 show the actual -statistics. These statistics come in two parts; the actual stats separated by a -short separator (line 08, 13) from the contention points. - -Lines 09-12 show the first 4 recorded contention points (the code -which tries to get the lock) and lines 14-17 show the first 4 recorded -contended points (the lock holder). It is possible that the max -con-bounces point is missing in the statistics. - -The first lock (05-18) is a read/write lock, and shows two lines above the -short separator. The contention points don't match the column descriptors, -they have two: contentions and [<IP>] symbol. The second set of contention -points are the points we're contending with. - -The integer part of the time values is in us. - -Dealing with nested locks, subclasses may appear: - -32........................................................................................................................................................................................................................... -33 -34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82 -35 --------- -36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75 -37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a -38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a -39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb -40 --------- -41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75 -42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a -43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54 -44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8 -45 -46........................................................................................................................................................................................................................... -47 -48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84 -49 ----------- -50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54 -51 ----------- -52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54 -53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8 -54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54 -55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a - -Line 48 shows statistics for the second subclass (/1) of &rq->lock class -(subclass starts from 0), since in this case, as line 50 suggests, -double_rq_lock actually acquires a nested lock of two spinlocks. - -View the top contending locks: - -# grep : /proc/lock_stat | head - clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71 - tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59 - &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59 - &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69 - &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93 - tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72 - tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89 - rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89 - &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27 - rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76 - -Clear the statistics: - -# echo 0 > /proc/lock_stat diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.rst index 6a8df4cd19bf..e79eeeca3ac6 100644 --- a/Documentation/locking/locktorture.txt +++ b/Documentation/locking/locktorture.rst @@ -1,6 +1,9 @@ +================================== Kernel Lock Torture Test Operation +================================== CONFIG_LOCK_TORTURE_TEST +======================== The CONFIG LOCK_TORTURE_TEST config option provides a kernel module that runs torture tests on core kernel locking primitives. The kernel @@ -18,61 +21,77 @@ can be simulated by either enlarging this critical region hold time and/or creating more kthreads. -MODULE PARAMETERS +Module Parameters +================= This module has the following parameters: - ** Locktorture-specific ** +Locktorture-specific +-------------------- -nwriters_stress Number of kernel threads that will stress exclusive lock +nwriters_stress + Number of kernel threads that will stress exclusive lock ownership (writers). The default value is twice the number of online CPUs. -nreaders_stress Number of kernel threads that will stress shared lock +nreaders_stress + Number of kernel threads that will stress shared lock ownership (readers). The default is the same amount of writer locks. If the user did not specify nwriters_stress, then both readers and writers be the amount of online CPUs. -torture_type Type of lock to torture. By default, only spinlocks will +torture_type + Type of lock to torture. By default, only spinlocks will be tortured. This module can torture the following locks, with string values as follows: - o "lock_busted": Simulates a buggy lock implementation. + - "lock_busted": + Simulates a buggy lock implementation. - o "spin_lock": spin_lock() and spin_unlock() pairs. + - "spin_lock": + spin_lock() and spin_unlock() pairs. - o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq() - pairs. + - "spin_lock_irq": + spin_lock_irq() and spin_unlock_irq() pairs. - o "rw_lock": read/write lock() and unlock() rwlock pairs. + - "rw_lock": + read/write lock() and unlock() rwlock pairs. - o "rw_lock_irq": read/write lock_irq() and unlock_irq() - rwlock pairs. + - "rw_lock_irq": + read/write lock_irq() and unlock_irq() + rwlock pairs. - o "mutex_lock": mutex_lock() and mutex_unlock() pairs. + - "mutex_lock": + mutex_lock() and mutex_unlock() pairs. - o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock() - pairs. Kernel must have CONFIG_RT_MUTEX=y. + - "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. + - "rwsem_lock": + read/write down() and up() semaphore pairs. - ** Torture-framework (RCU + locking) ** +Torture-framework (RCU + locking) +--------------------------------- -shutdown_secs The number of seconds to run the test before terminating +shutdown_secs + The number of seconds to run the test before terminating the test and powering off the system. The default is zero, which disables test termination and system shutdown. This capability is useful for automated testing. -onoff_interval The number of seconds between each attempt to execute a +onoff_interval + The number of seconds between each attempt to execute a randomly selected CPU-hotplug operation. Defaults to zero, which disables CPU hotplugging. In CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently refuse to do any CPU-hotplug operations regardless of what value is specified for onoff_interval. -onoff_holdoff The number of seconds to wait until starting CPU-hotplug +onoff_holdoff + The number of seconds to wait until starting CPU-hotplug operations. This would normally only be used when locktorture was built into the kernel and started automatically at boot time, in which case it is useful @@ -80,53 +99,59 @@ onoff_holdoff The number of seconds to wait until starting CPU-hotplug coming and going. This parameter is only useful if CONFIG_HOTPLUG_CPU is enabled. -stat_interval Number of seconds between statistics-related printk()s. +stat_interval + Number of seconds between statistics-related printk()s. By default, locktorture will report stats every 60 seconds. Setting the interval to zero causes the statistics to be printed -only- when the module is unloaded, and this is the default. -stutter The length of time to run the test before pausing for this +stutter + The length of time to run the test before pausing for this same period of time. Defaults to "stutter=5", so as to run and pause for (roughly) five-second intervals. Specifying "stutter=0" causes the test to run continuously without pausing, which is the old default behavior. -shuffle_interval The number of seconds to keep the test threads affinitied +shuffle_interval + The number of seconds to keep the test threads affinitied to a particular subset of the CPUs, defaults to 3 seconds. Used in conjunction with test_no_idle_hz. -verbose Enable verbose debugging printing, via printk(). Enabled +verbose + Enable verbose debugging printing, via printk(). Enabled by default. This extra information is mostly related to high-level errors and reports from the main 'torture' framework. -STATISTICS +Statistics +========== -Statistics are printed in the following format: +Statistics are printed in the following format:: -spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 - (A) (B) (C) (D) (E) + spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 + (A) (B) (C) (D) (E) -(A): Lock type that is being tortured -- torture_type parameter. + (A): Lock type that is being tortured -- torture_type parameter. -(B): Number of writer lock acquisitions. If dealing with a read/write primitive - a second "Reads" statistics line is printed. + (B): Number of writer lock acquisitions. If dealing with a read/write + primitive a second "Reads" statistics line is printed. -(C): Number of times the lock was acquired. + (C): Number of times the lock was acquired. -(D): Min and max number of times threads failed to acquire the lock. + (D): Min and max number of times threads failed to acquire the lock. -(E): true/false values if there were errors acquiring the lock. This should - -only- be positive if there is a bug in the locking primitive's - implementation. Otherwise a lock should never fail (i.e., spin_lock()). - Of course, the same applies for (C), above. A dummy example of this is - the "lock_busted" type. + (E): true/false values if there were errors acquiring the lock. This should + -only- be positive if there is a bug in the locking primitive's + implementation. Otherwise a lock should never fail (i.e., spin_lock()). + Of course, the same applies for (C), above. A dummy example of this is + the "lock_busted" type. -USAGE +Usage +===== -The following script may be used to torture locks: +The following script may be used to torture locks:: #!/bin/sh diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.rst index 818aca19612f..4d8236b81fa5 100644 --- a/Documentation/locking/mutex-design.txt +++ b/Documentation/locking/mutex-design.rst @@ -1,6 +1,9 @@ +======================= Generic Mutex Subsystem +======================= started by Ingo Molnar <mingo@redhat.com> + updated by Davidlohr Bueso <davidlohr@hp.com> What are mutexes? @@ -23,7 +26,7 @@ Implementation Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h and implemented in kernel/locking/mutex.c. These locks use an atomic variable (->owner) to keep track of the lock state during its lifetime. Field owner -actually contains 'struct task_struct *' to the current lock owner and it is +actually contains `struct task_struct *` to the current lock owner and it is therefore NULL if not currently owned. Since task_struct pointers are aligned at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., if waiter list is non-empty). In its most basic form it also includes a @@ -101,29 +104,36 @@ features that make lock debugging easier and faster: Interfaces ---------- -Statically define the mutex: +Statically define the mutex:: + DEFINE_MUTEX(name); -Dynamically initialize the mutex: +Dynamically initialize the mutex:: + mutex_init(mutex); -Acquire the mutex, uninterruptible: +Acquire the mutex, uninterruptible:: + void mutex_lock(struct mutex *lock); void mutex_lock_nested(struct mutex *lock, unsigned int subclass); int mutex_trylock(struct mutex *lock); -Acquire the mutex, interruptible: +Acquire the mutex, interruptible:: + int mutex_lock_interruptible_nested(struct mutex *lock, unsigned int subclass); int mutex_lock_interruptible(struct mutex *lock); -Acquire the mutex, interruptible, if dec to 0: +Acquire the mutex, interruptible, if dec to 0:: + int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); -Unlock the mutex: +Unlock the mutex:: + void mutex_unlock(struct mutex *lock); -Test if the mutex is taken: +Test if the mutex is taken:: + int mutex_is_locked(struct mutex *lock); Disadvantages diff --git a/Documentation/locking/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.rst index 3d7b865539cc..59c2a64efb21 100644 --- a/Documentation/locking/rt-mutex-design.txt +++ b/Documentation/locking/rt-mutex-design.rst @@ -1,14 +1,15 @@ -# -# Copyright (c) 2006 Steven Rostedt -# Licensed under the GNU Free Documentation License, Version 1.2 -# - +============================== RT-mutex implementation design ------------------------------- +============================== + +Copyright (c) 2006 Steven Rostedt + +Licensed under the GNU Free Documentation License, Version 1.2 + This document tries to describe the design of the rtmutex.c implementation. It doesn't describe the reasons why rtmutex.c exists. For that please see -Documentation/locking/rt-mutex.txt. Although this document does explain problems +Documentation/locking/rt-mutex.rst. Although this document does explain problems that happen without this code, but that is in the concept to understand what the code actually is doing. @@ -41,17 +42,17 @@ to release the lock, because for all we know, B is a CPU hog and will never give C a chance to release the lock. This is called unbounded priority inversion. -Here's a little ASCII art to show the problem. +Here's a little ASCII art to show the problem:: - grab lock L1 (owned by C) - | -A ---+ - C preempted by B - | -C +----+ + grab lock L1 (owned by C) + | + A ---+ + C preempted by B + | + C +----+ -B +--------> - B now keeps A from running. + B +--------> + B now keeps A from running. Priority Inheritance (PI) @@ -75,24 +76,29 @@ Terminology Here I explain some terminology that is used in this document to help describe the design that is used to implement PI. -PI chain - The PI chain is an ordered series of locks and processes that cause +PI chain + - The PI chain is an ordered series of locks and processes that cause processes to inherit priorities from a previous process that is blocked on one of its locks. This is described in more detail later in this document. -mutex - In this document, to differentiate from locks that implement +mutex + - In this document, to differentiate from locks that implement PI and spin locks that are used in the PI code, from now on the PI locks will be called a mutex. -lock - In this document from now on, I will use the term lock when +lock + - In this document from now on, I will use the term lock when referring to spin locks that are used to protect parts of the PI algorithm. These locks disable preemption for UP (when CONFIG_PREEMPT is enabled) and on SMP prevents multiple CPUs from entering critical sections simultaneously. -spin lock - Same as lock above. +spin lock + - Same as lock above. -waiter - A waiter is a struct that is stored on the stack of a blocked +waiter + - A waiter is a struct that is stored on the stack of a blocked process. Since the scope of the waiter is within the code for a process being blocked on the mutex, it is fine to allocate the waiter on the process's stack (local variable). This @@ -104,14 +110,18 @@ waiter - A waiter is a struct that is stored on the stack of a blocked waiter is sometimes used in reference to the task that is waiting on a mutex. This is the same as waiter->task. -waiters - A list of processes that are blocked on a mutex. +waiters + - A list of processes that are blocked on a mutex. -top waiter - The highest priority process waiting on a specific mutex. +top waiter + - The highest priority process waiting on a specific mutex. -top pi waiter - The highest priority process waiting on one of the mutexes +top pi waiter + - The highest priority process waiting on one of the mutexes that a specific process owns. -Note: task and process are used interchangeably in this document, mostly to +Note: + task and process are used interchangeably in this document, mostly to differentiate between two processes that are being described together. @@ -123,7 +133,7 @@ inheritance to take place. Multiple chains may converge, but a chain would never diverge, since a process can't be blocked on more than one mutex at a time. -Example: +Example:: Process: A, B, C, D, E Mutexes: L1, L2, L3, L4 @@ -137,21 +147,21 @@ Example: D owns L4 E blocked on L4 -The chain would be: +The chain would be:: E->L4->D->L3->C->L2->B->L1->A To show where two chains merge, we could add another process F and another mutex L5 where B owns L5 and F is blocked on mutex L5. -The chain for F would be: +The chain for F would be:: F->L5->B->L1->A Since a process may own more than one mutex, but never be blocked on more than one, the chains merge. -Here we show both chains: +Here we show both chains:: E->L4->D->L3->C->L2-+ | @@ -165,12 +175,12 @@ than the processes to the left or below in the chain. Also since a mutex may have more than one process blocked on it, we can have multiple chains merge at mutexes. If we add another process G that is -blocked on mutex L2: +blocked on mutex L2:: G->L2->B->L1->A And once again, to show how this can grow I will show the merging chains -again. +again:: E->L4->D->L3->C-+ +->L2-+ @@ -184,7 +194,7 @@ the chain (A and B in this example), must have their priorities increased to that of G. Mutex Waiters Tree ------------------ +------------------ Every mutex keeps track of all the waiters that are blocked on itself. The mutex has a rbtree to store these waiters by priority. This tree is protected @@ -219,19 +229,19 @@ defined. But is very complex to figure it out, since it depends on all the nesting of mutexes. Let's look at the example where we have 3 mutexes, L1, L2, and L3, and four separate functions func1, func2, func3 and func4. The following shows a locking order of L1->L2->L3, but may not actually -be directly nested that way. +be directly nested that way:: -void func1(void) -{ + void func1(void) + { mutex_lock(L1); /* do anything */ mutex_unlock(L1); -} + } -void func2(void) -{ + void func2(void) + { mutex_lock(L1); mutex_lock(L2); @@ -239,10 +249,10 @@ void func2(void) mutex_unlock(L2); mutex_unlock(L1); -} + } -void func3(void) -{ + void func3(void) + { mutex_lock(L2); mutex_lock(L3); @@ -250,30 +260,30 @@ void func3(void) mutex_unlock(L3); mutex_unlock(L2); -} + } -void func4(void) -{ + void func4(void) + { mutex_lock(L3); /* do something again */ mutex_unlock(L3); -} + } Now we add 4 processes that run each of these functions separately. Processes A, B, C, and D which run functions func1, func2, func3 and func4 respectively, and such that D runs first and A last. With D being preempted -in func4 in the "do something again" area, we have a locking that follows: +in func4 in the "do something again" area, we have a locking that follows:: -D owns L3 - C blocked on L3 - C owns L2 - B blocked on L2 - B owns L1 - A blocked on L1 + D owns L3 + C blocked on L3 + C owns L2 + B blocked on L2 + B owns L1 + A blocked on L1 -And thus we have the chain A->L1->B->L2->C->L3->D. + And thus we have the chain A->L1->B->L2->C->L3->D. This gives us a PI depth of 4 (four processes), but looking at any of the functions individually, it seems as though they only have at most a locking @@ -298,7 +308,7 @@ not true, the rtmutex.c code will be broken!), this allows for the least significant bit to be used as a flag. Bit 0 is used as the "Has Waiters" flag. It's set whenever there are waiters on a mutex. -See Documentation/locking/rt-mutex.txt for further details. +See Documentation/locking/rt-mutex.rst for further details. cmpxchg Tricks -------------- @@ -307,17 +317,17 @@ Some architectures implement an atomic cmpxchg (Compare and Exchange). This is used (when applicable) to keep the fast path of grabbing and releasing mutexes short. -cmpxchg is basically the following function performed atomically: +cmpxchg is basically the following function performed atomically:: -unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C) -{ + unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C) + { unsigned long T = *A; if (*A == *B) { *A = *C; } return T; -} -#define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c) + } + #define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c) This is really nice to have, since it allows you to only update a variable if the variable is what you expect it to be. You know if it succeeded if @@ -352,9 +362,10 @@ Then rt_mutex_setprio is called to adjust the priority of the task to the new priority. Note that rt_mutex_setprio is defined in kernel/sched/core.c to implement the actual change in priority. -(Note: For the "prio" field in task_struct, the lower the number, the +Note: + For the "prio" field in task_struct, the lower the number, the higher the priority. A "prio" of 5 is of higher priority than a - "prio" of 10.) + "prio" of 10. It is interesting to note that rt_mutex_adjust_prio can either increase or decrease the priority of the task. In the case that a higher priority @@ -439,6 +450,7 @@ wait_lock, which this code currently holds. So setting the "Has Waiters" flag forces the current owner to synchronize with this code. The lock is taken if the following are true: + 1) The lock has no owner 2) The current task is the highest priority against all other waiters of the lock @@ -546,10 +558,13 @@ Credits ------- Author: Steven Rostedt <rostedt@goodmis.org> + Updated: Alex Shi <alex.shi@linaro.org> - 7/6/2017 -Original Reviewers: Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and +Original Reviewers: + Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and Randy Dunlap + Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior Updates diff --git a/Documentation/locking/rt-mutex.txt b/Documentation/locking/rt-mutex.rst index 35793e003041..c365dc302081 100644 --- a/Documentation/locking/rt-mutex.txt +++ b/Documentation/locking/rt-mutex.rst @@ -1,5 +1,6 @@ +================================== RT-mutex subsystem with PI support ----------------------------------- +================================== RT-mutexes with priority inheritance are used to support PI-futexes, which enable pthread_mutex_t priority inheritance attributes @@ -46,27 +47,30 @@ The state of the rt-mutex is tracked via the owner field of the rt-mutex structure: lock->owner holds the task_struct pointer of the owner. Bit 0 is used to -keep track of the "lock has waiters" state. +keep track of the "lock has waiters" state: - owner bit0 + ============ ======= ================================================ + owner bit0 Notes + ============ ======= ================================================ NULL 0 lock is free (fast acquire possible) NULL 1 lock is free and has waiters and the top waiter - is going to take the lock* + is going to take the lock [1]_ taskpointer 0 lock is held (fast release possible) - taskpointer 1 lock is held and has waiters** + taskpointer 1 lock is held and has waiters [2]_ + ============ ======= ================================================ The fast atomic compare exchange based acquire and release is only possible when bit 0 of lock->owner is 0. -(*) It also can be a transitional state when grabbing the lock -with ->wait_lock is held. To prevent any fast path cmpxchg to the lock, -we need to set the bit0 before looking at the lock, and the owner may be -NULL in this small time, hence this can be a transitional state. +.. [1] It also can be a transitional state when grabbing the lock + with ->wait_lock is held. To prevent any fast path cmpxchg to the lock, + we need to set the bit0 before looking at the lock, and the owner may + be NULL in this small time, hence this can be a transitional state. -(**) There is a small time when bit 0 is set but there are no -waiters. This can happen when grabbing the lock in the slow path. -To prevent a cmpxchg of the owner releasing the lock, we need to -set this bit before looking at the lock. +.. [2] There is a small time when bit 0 is set but there are no + waiters. This can happen when grabbing the lock in the slow path. + To prevent a cmpxchg of the owner releasing the lock, we need to + set this bit before looking at the lock. BTW, there is still technically a "Pending Owner", it's just not called that anymore. The pending owner happens to be the top_waiter of a lock diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.rst index ff35e40bdf5b..098107fb7d86 100644 --- a/Documentation/locking/spinlocks.txt +++ b/Documentation/locking/spinlocks.rst @@ -1,8 +1,13 @@ +=============== +Locking lessons +=============== + Lesson 1: Spin locks +==================== -The most basic primitive for locking is spinlock. +The most basic primitive for locking is spinlock:: -static DEFINE_SPINLOCK(xxx_lock); + static DEFINE_SPINLOCK(xxx_lock); unsigned long flags; @@ -19,23 +24,25 @@ worry about UP vs SMP issues: the spinlocks work correctly under both. NOTE! Implications of spin_locks for memory are further described in: Documentation/memory-barriers.txt + (5) LOCK operations. + (6) UNLOCK operations. The above is usually pretty simple (you usually need and want only one spinlock for most things - using more than one spinlock can make things a lot more complex and even slower and is usually worth it only for -sequences that you _know_ need to be split up: avoid it at all cost if you +sequences that you **know** need to be split up: avoid it at all cost if you aren't sure). This is really the only really hard part about spinlocks: once you start using spinlocks they tend to expand to areas you might not have noticed before, because you have to make sure the spinlocks correctly protect the -shared data structures _everywhere_ they are used. The spinlocks are most +shared data structures **everywhere** they are used. The spinlocks are most easily added to places that are completely independent of other code (for example, internal driver data structures that nobody else ever touches). - NOTE! The spin-lock is safe only when you _also_ use the lock itself + NOTE! The spin-lock is safe only when you **also** use the lock itself to do locking across CPU's, which implies that EVERYTHING that touches a shared variable has to agree about the spinlock they want to use. @@ -43,6 +50,7 @@ example, internal driver data structures that nobody else ever touches). ---- Lesson 2: reader-writer spinlocks. +================================== If your data accesses have a very natural pattern where you usually tend to mostly read from the shared variables, the reader-writer locks @@ -54,7 +62,7 @@ to change the variables it has to get an exclusive write lock. simple spinlocks. Unless the reader critical section is long, you are better off just using spinlocks. -The routines look the same as above: +The routines look the same as above:: rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); @@ -71,7 +79,7 @@ The routines look the same as above: The above kind of lock may be useful for complex data structures like linked lists, especially searching for entries without changing the list itself. The read lock allows many concurrent readers. Anything that -_changes_ the list will have to get the write lock. +**changes** the list will have to get the write lock. NOTE! RCU is better for list traversal, but requires careful attention to design detail (see Documentation/RCU/listRCU.txt). @@ -87,10 +95,11 @@ to get the write-lock at the very beginning. ---- Lesson 3: spinlocks revisited. +============================== The single spin-lock primitives above are by no means the only ones. They are the most safe ones, and the ones that work under all circumstances, -but partly _because_ they are safe they are also fairly slow. They are slower +but partly **because** they are safe they are also fairly slow. They are slower than they'd need to be, because they do have to disable interrupts (which is just a single instruction on a x86, but it's an expensive one - and on other architectures it can be worse). @@ -98,7 +107,7 @@ and on other architectures it can be worse). If you have a case where you have to protect a data structure across several CPU's and you want to use spinlocks you can potentially use cheaper versions of the spinlocks. IFF you know that the spinlocks are -never used in interrupt handlers, you can use the non-irq versions: +never used in interrupt handlers, you can use the non-irq versions:: spin_lock(&lock); ... @@ -110,7 +119,7 @@ This is useful if you know that the data in question is only ever manipulated from a "process context", ie no interrupts involved. The reasons you mustn't use these versions if you have interrupts that -play with the spinlock is that you can get deadlocks: +play with the spinlock is that you can get deadlocks:: spin_lock(&lock); ... @@ -147,9 +156,10 @@ indeed), while write-locks need to protect themselves against interrupts. ---- Reference information: +====================== For dynamic initialization, use spin_lock_init() or rwlock_init() as -appropriate: +appropriate:: spinlock_t xxx_lock; rwlock_t xxx_rw_lock; diff --git a/Documentation/locking/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.rst index f0ed7c30e695..1846c199da23 100644 --- a/Documentation/locking/ww-mutex-design.txt +++ b/Documentation/locking/ww-mutex-design.rst @@ -1,3 +1,4 @@ +====================================== Wound/Wait Deadlock-Proof Mutex Design ====================================== @@ -85,6 +86,7 @@ Furthermore there are three different class of w/w lock acquire functions: no deadlock potential and hence the ww_mutex_lock call will block and not prematurely return -EDEADLK. The advantage of the _slow functions is in interface safety: + - ww_mutex_lock has a __must_check int return type, whereas ww_mutex_lock_slow has a void return type. Note that since ww mutex code needs loops/retries anyway the __must_check doesn't result in spurious warnings, even though the @@ -115,36 +117,36 @@ expect the number of simultaneous competing transactions to be typically small, and you want to reduce the number of rollbacks. Three different ways to acquire locks within the same w/w class. Common -definitions for methods #1 and #2: +definitions for methods #1 and #2:: -static DEFINE_WW_CLASS(ww_class); + static DEFINE_WW_CLASS(ww_class); -struct obj { + struct obj { struct ww_mutex lock; /* obj data */ -}; + }; -struct obj_entry { + struct obj_entry { struct list_head head; struct obj *obj; -}; + }; Method 1, using a list in execbuf->buffers that's not allowed to be reordered. This is useful if a list of required objects is already tracked somewhere. Furthermore the lock helper can use propagate the -EALREADY return code back to the caller as a signal that an object is twice on the list. This is useful if the list is constructed from userspace input and the ABI requires userspace to -not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl). +not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl):: -int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj *res_obj = NULL; struct obj_entry *contended_entry = NULL; struct obj_entry *entry; ww_acquire_init(ctx, &ww_class); -retry: + retry: list_for_each_entry (entry, list, head) { if (entry->obj == res_obj) { res_obj = NULL; @@ -160,7 +162,7 @@ retry: ww_acquire_done(ctx); return 0; -err: + err: list_for_each_entry_continue_reverse (entry, list, head) ww_mutex_unlock(&entry->obj->lock); @@ -176,14 +178,14 @@ err: ww_acquire_fini(ctx); return ret; -} + } Method 2, using a list in execbuf->buffers that can be reordered. Same semantics of duplicate entry detection using -EALREADY as method 1 above. But the -list-reordering allows for a bit more idiomatic code. +list-reordering allows for a bit more idiomatic code:: -int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj_entry *entry, *entry2; ww_acquire_init(ctx, &ww_class); @@ -216,24 +218,25 @@ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) ww_acquire_done(ctx); return 0; -} + } -Unlocking works the same way for both methods #1 and #2: +Unlocking works the same way for both methods #1 and #2:: -void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj_entry *entry; list_for_each_entry (entry, list, head) ww_mutex_unlock(&entry->obj->lock); ww_acquire_fini(ctx); -} + } Method 3 is useful if the list of objects is constructed ad-hoc and not upfront, e.g. when adjusting edges in a graph where each node has its own ww_mutex lock, and edges can only be changed when holding the locks of all involved nodes. w/w mutexes are a natural fit for such a case for two reasons: + - They can handle lock-acquisition in any order which allows us to start walking a graph from a starting point and then iteratively discovering new edges and locking down the nodes those edges connect to. @@ -243,6 +246,7 @@ mutexes are a natural fit for such a case for two reasons: as a starting point). Note that this approach differs in two important ways from the above methods: + - Since the list of objects is dynamically constructed (and might very well be different when retrying due to hitting the -EDEADLK die condition) there's no need to keep any object on a persistent list when it's not locked. We can @@ -260,17 +264,17 @@ any interface misuse for these cases. Also, method 3 can't fail the lock acquisition step since it doesn't return -EALREADY. Of course this would be different when using the _interruptible -variants, but that's outside of the scope of these examples here. +variants, but that's outside of the scope of these examples here:: -struct obj { + struct obj { struct ww_mutex ww_mutex; struct list_head locked_list; -}; + }; -static DEFINE_WW_CLASS(ww_class); + static DEFINE_WW_CLASS(ww_class); -void __unlock_objs(struct list_head *list) -{ + void __unlock_objs(struct list_head *list) + { struct obj *entry, *temp; list_for_each_entry_safe (entry, temp, list, locked_list) { @@ -279,15 +283,15 @@ void __unlock_objs(struct list_head *list) list_del(&entry->locked_list); ww_mutex_unlock(entry->ww_mutex) } -} + } -void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj *obj; ww_acquire_init(ctx, &ww_class); -retry: + retry: /* re-init loop start state */ loop { /* magic code which walks over a graph and decides which objects @@ -312,13 +316,13 @@ retry: ww_acquire_done(ctx); return 0; -} + } -void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { __unlock_objs(list); ww_acquire_fini(ctx); -} + } Method 4: Only lock one single objects. In that case deadlock detection and prevention is obviously overkill, since with grabbing just one lock you can't @@ -329,11 +333,14 @@ Implementation Details ---------------------- Design: +^^^^^^^ + ww_mutex currently encapsulates a struct mutex, this means no extra overhead for normal mutex locks, which are far more common. As such there is only a small increase in code size if wait/wound mutexes are not used. We maintain the following invariants for the wait list: + (1) Waiters with an acquire context are sorted by stamp order; waiters without an acquire context are interspersed in FIFO order. (2) For Wait-Die, among waiters with contexts, only the first one can have @@ -355,6 +362,8 @@ Design: therefore be directed towards the uncontended cases. Lockdep: +^^^^^^^^ + Special care has been taken to warn for as many cases of api abuse as possible. Some common api abuses will be caught with CONFIG_DEBUG_MUTEXES, but CONFIG_PROVE_LOCKING is recommended. @@ -379,5 +388,6 @@ Lockdep: having called ww_acquire_fini on the first. - 'normal' deadlocks that can occur. -FIXME: Update this section once we have the TASK_DEADLOCK task state flag magic -implemented. +FIXME: + Update this section once we have the TASK_DEADLOCK task state flag magic + implemented. diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst new file mode 100644 index 000000000000..3a5ba7fe1703 --- /dev/null +++ b/Documentation/m68k/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +m68k Architecture +================= + +.. toctree:: + :maxdepth: 2 + + kernel-options + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.rst index 79d21246c75a..cabd9419740d 100644 --- a/Documentation/m68k/kernel-options.txt +++ b/Documentation/m68k/kernel-options.rst @@ -1,22 +1,24 @@ - - - Command Line Options for Linux/m68k - =================================== +=================================== +Command Line Options for Linux/m68k +=================================== Last Update: 2 May 1999 + Linux/m68k version: 2.2.6 + Author: Roman.Hodek@informatik.uni-erlangen.de (Roman Hodek) + Update: jds@kom.auc.dk (Jes Sorensen) and faq@linux-m68k.org (Chris Lawrence) 0) Introduction =============== - Often I've been asked which command line options the Linux/m68k +Often I've been asked which command line options the Linux/m68k kernel understands, or how the exact syntax for the ... option is, or ... about the option ... . I hope, this document supplies all the answers... - Note that some options might be outdated, their descriptions being +Note that some options might be outdated, their descriptions being incomplete or missing. Please update the information and send in the patches. @@ -38,11 +40,11 @@ argument contains an '=', it is of class 2, and the definition is put into init's environment. All other arguments are passed to init as command line options. - This document describes the valid kernel options for Linux/m68k in +This document describes the valid kernel options for Linux/m68k in the version mentioned at the start of this file. Later revisions may add new such options, and some may be missing in older versions. - In general, the value (the part after the '=') of an option is a +In general, the value (the part after the '=') of an option is a list of values separated by commas. The interpretation of these values is up to the driver that "owns" the option. This association of options with drivers is also the reason that some are further @@ -55,21 +57,21 @@ subdivided. 2.1) root= ---------- -Syntax: root=/dev/<device> - or: root=<hex_number> +:Syntax: root=/dev/<device> +:or: root=<hex_number> This tells the kernel which device it should mount as the root filesystem. The device must be a block device with a valid filesystem on it. - The first syntax gives the device by name. These names are converted +The first syntax gives the device by name. These names are converted into a major/minor number internally in the kernel in an unusual way. Normally, this "conversion" is done by the device files in /dev, but this isn't possible here, because the root filesystem (with /dev) isn't mounted yet... So the kernel parses the name itself, with some hardcoded name to number mappings. The name must always be a combination of two or three letters, followed by a decimal number. -Valid names are: +Valid names are:: /dev/ram: -> 0x0100 (initial ramdisk) /dev/hda: -> 0x0300 (first IDE disk) @@ -81,7 +83,7 @@ Valid names are: /dev/sde: -> 0x0840 (fifth SCSI disk) /dev/fd : -> 0x0200 (floppy disk) - The name must be followed by a decimal number, that stands for the +The name must be followed by a decimal number, that stands for the partition number. Internally, the value of the number is just added to the device number mentioned in the table above. The exceptions are /dev/ram and /dev/fd, where /dev/ram refers to an @@ -100,12 +102,12 @@ the kernel command line. [Strange and maybe uninteresting stuff ON] - This unusual translation of device names has some strange +This unusual translation of device names has some strange consequences: If, for example, you have a symbolic link from /dev/fd to /dev/fd0D720 as an abbreviation for floppy driver #0 in DD format, you cannot use this name for specifying the root device, because the kernel cannot see this symlink before mounting the root FS and it -isn't in the table above. If you use it, the root device will not be +isn't in the table above. If you use it, the root device will not be set at all, without an error message. Another example: You cannot use a partition on e.g. the sixth SCSI disk as the root filesystem, if you want to specify it by name. This is, because only the devices up to @@ -118,7 +120,7 @@ knowledge that each disk uses 16 minors, and write "root=/dev/sde17" [Strange and maybe uninteresting stuff OFF] - If the device containing your root partition isn't in the table +If the device containing your root partition isn't in the table above, you can also specify it by major and minor numbers. These are written in hex, with no prefix and no separator between. E.g., if you have a CD with contents appropriate as a root filesystem in the first @@ -136,6 +138,7 @@ known partition UUID as the starting point. For example, if partition 5 of the device has the UUID of 00112233-4455-6677-8899-AABBCCDDEEFF then partition 3 may be found as follows: + PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2 Authoritative information can be found in @@ -145,8 +148,8 @@ Authoritative information can be found in 2.2) ro, rw ----------- -Syntax: ro - or: rw +:Syntax: ro +:or: rw These two options tell the kernel whether it should mount the root filesystem read-only or read-write. The default is read-only, except @@ -156,7 +159,7 @@ for ramdisks, which default to read-write. 2.3) debug ---------- -Syntax: debug +:Syntax: debug This raises the kernel log level to 10 (the default is 7). This is the same level as set by the "dmesg" command, just that the maximum level @@ -166,7 +169,7 @@ selectable by dmesg is 8. 2.4) debug= ----------- -Syntax: debug=<device> +:Syntax: debug=<device> This option causes certain kernel messages be printed to the selected debugging device. This can aid debugging the kernel, since the @@ -175,7 +178,7 @@ devices are possible depends on the machine type. There are no checks for the validity of the device name. If the device isn't implemented, nothing happens. - Messages logged this way are in general stack dumps after kernel +Messages logged this way are in general stack dumps after kernel memory faults or bad kernel traps, and kernel panics. To be exact: all messages of level 0 (panic messages) and all messages printed while the log level is 8 or more (their level doesn't matter). Before stack @@ -185,19 +188,27 @@ at least 8 can also be set by the "debug" command line option (see Devices possible for Amiga: - - "ser": built-in serial port; parameters: 9600bps, 8N1 - - "mem": Save the messages to a reserved area in chip mem. After + - "ser": + built-in serial port; parameters: 9600bps, 8N1 + - "mem": + Save the messages to a reserved area in chip mem. After rebooting, they can be read under AmigaOS with the tool 'dmesg'. Devices possible for Atari: - - "ser1": ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1 - - "ser2": SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1 - - "ser" : default serial port + - "ser1": + ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1 + - "ser2": + SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1 + - "ser" : + default serial port This is "ser2" for a Falcon, and "ser1" for any other machine - - "midi": The MIDI port; parameters: 31250bps, 8N1 - - "par" : parallel port + - "midi": + The MIDI port; parameters: 31250bps, 8N1 + - "par" : + parallel port + The printing routine for this implements a timeout for the case there's no printer connected (else the kernel would lock up). The timeout is not exact, but usually a few @@ -205,26 +216,29 @@ Devices possible for Atari: 2.6) ramdisk_size= -------------- +------------------ -Syntax: ramdisk_size=<size> +:Syntax: ramdisk_size=<size> - This option instructs the kernel to set up a ramdisk of the given +This option instructs the kernel to set up a ramdisk of the given size in KBytes. Do not use this option if the ramdisk contents are passed by bootstrap! In this case, the size is selected automatically and should not be overwritten. - The only application is for root filesystems on floppy disks, that +The only application is for root filesystems on floppy disks, that should be loaded into memory. To do that, select the corresponding size of the disk as ramdisk size, and set the root device to the disk drive (with "root="). 2.7) swap= + + I can't find any sign of this option in 2.2.6. + 2.8) buff= ----------- - I can't find any sign of these options in 2.2.6. + I can't find any sign of this option in 2.2.6. 3) General Device Options (Amiga and Atari) @@ -233,13 +247,13 @@ drive (with "root="). 3.1) ether= ----------- -Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name> +:Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name> - <dev-name> is the name of a net driver, as specified in +<dev-name> is the name of a net driver, as specified in drivers/net/Space.c in the Linux source. Most prominent are eth0, ... eth3, sl0, ... sl3, ppp0, ..., ppp3, dummy, and lo. - The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the +The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the settings by this options. Also, the existing ethernet drivers for Linux/m68k (ariadne, a2065, hydra) don't use them because Zorro boards are really Plug-'n-Play, so the "ether=" option is useless altogether @@ -249,9 +263,9 @@ for Linux/m68k. 3.2) hd= -------- -Syntax: hd=<cylinders>,<heads>,<sectors> +:Syntax: hd=<cylinders>,<heads>,<sectors> - This option sets the disk geometry of an IDE disk. The first hd= +This option sets the disk geometry of an IDE disk. The first hd= option is for the first IDE disk, the second for the second one. (I.e., you can give this option twice.) In most cases, you won't have to use this option, since the kernel can obtain the geometry data @@ -262,9 +276,9 @@ disks. 3.3) max_scsi_luns= ------------------- -Syntax: max_scsi_luns=<n> +:Syntax: max_scsi_luns=<n> - Sets the maximum number of LUNs (logical units) of SCSI devices to +Sets the maximum number of LUNs (logical units) of SCSI devices to be scanned. Valid values for <n> are between 1 and 8. Default is 8 if "Probe all LUNs on each SCSI device" was selected during the kernel configuration, else 1. @@ -273,9 +287,9 @@ configuration, else 1. 3.4) st= -------- -Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]] +:Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]] - Sets several parameters of the SCSI tape driver. <buffer_size> is +Sets several parameters of the SCSI tape driver. <buffer_size> is the number of 512-byte buffers reserved for tape operations for each device. <write_thres> sets the number of blocks which must be filled to start an actual write operation to the tape. Maximum value is the @@ -286,9 +300,9 @@ buffers allocated for all tape devices. 3.5) dmasound= -------------- -Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]] +:Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]] - This option controls some configurations of the Linux/m68k DMA sound +This option controls some configurations of the Linux/m68k DMA sound driver (Amiga and Atari): <buffers> is the number of buffers you want to use (minimum 4, default 4), <buffer-size> is the size of each buffer in kilobytes (minimum 4, default 32) and <catch-radius> says @@ -305,20 +319,22 @@ don't need to expand the sound. 4.1) video= ----------- -Syntax: video=<fbname>:<sub-options...> +:Syntax: video=<fbname>:<sub-options...> The <fbname> parameter specifies the name of the frame buffer, -eg. most atari users will want to specify `atafb' here. The +eg. most atari users will want to specify `atafb` here. The <sub-options> is a comma-separated list of the sub-options listed below. -NB: Please notice that this option was renamed from `atavideo' to - `video' during the development of the 1.3.x kernels, thus you +NB: + Please notice that this option was renamed from `atavideo` to + `video` during the development of the 1.3.x kernels, thus you might need to update your boot-scripts if upgrading to 2.x from an 1.2.x kernel. -NBB: The behavior of video= was changed in 2.1.57 so the recommended -option is to specify the name of the frame buffer. +NBB: + The behavior of video= was changed in 2.1.57 so the recommended + option is to specify the name of the frame buffer. 4.1.1) Video Mode ----------------- @@ -341,11 +357,11 @@ mode, if the hardware allows. Currently defined names are: - falh2 : 896x608x1, Falcon only - falh16 : 896x608x4, Falcon only - If no video mode is given on the command line, the kernel tries the +If no video mode is given on the command line, the kernel tries the modes names "default<n>" in turn, until one is possible with the hardware in use. - A video mode setting doesn't make sense, if the external driver is +A video mode setting doesn't make sense, if the external driver is activated by a "external:" sub-option. 4.1.2) inverse @@ -358,17 +374,17 @@ option, you can make the background white. 4.1.3) font ----------- -Syntax: font:<fontname> +:Syntax: font:<fontname> Specify the font to use in text modes. Currently you can choose only -between `VGA8x8', `VGA8x16' and `PEARL8x8'. `VGA8x8' is default, if the +between `VGA8x8`, `VGA8x16` and `PEARL8x8`. `VGA8x8` is default, if the vertical size of the display is less than 400 pixel rows. Otherwise, the -`VGA8x16' font is the default. +`VGA8x16` font is the default. -4.1.4) hwscroll_ ----------------- +4.1.4) `hwscroll_` +------------------ -Syntax: hwscroll_<n> +:Syntax: `hwscroll_<n>` The number of additional lines of video memory to reserve for speeding up the scrolling ("hardware scrolling"). Hardware scrolling @@ -378,7 +394,7 @@ possible with plain STs and graphics cards (The former because the base address must be on a 256 byte boundary there, the latter because the kernel doesn't know how to set the base address at all.) - By default, <n> is set to the number of visible text lines on the +By default, <n> is set to the number of visible text lines on the display. Thus, the amount of video memory is doubled, compared to no hardware scrolling. You can turn off the hardware scrolling altogether by setting <n> to 0. @@ -386,31 +402,31 @@ by setting <n> to 0. 4.1.5) internal: ---------------- -Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>] +:Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>] This option specifies the capabilities of some extended internal video hardware, like e.g. OverScan. <xres> and <yres> give the (extended) dimensions of the screen. - If your OverScan needs a black border, you have to write the last +If your OverScan needs a black border, you have to write the last three arguments of the "internal:". <xres_max> is the maximum line length the hardware allows, <yres_max> the maximum number of lines. <offset> is the offset of the visible part of the screen memory to its physical start, in bytes. - Often, extended interval video hardware has to be activated somehow. +Often, extended interval video hardware has to be activated somehow. For this, see the "sw_*" options below. 4.1.6) external: ---------------- -Syntax: - external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>\ - [;<colw>[;<coltype>[;<xres_virtual>]]]]] +:Syntax: + external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase> + [;<colw>[;<coltype>[;<xres_virtual>]]]]] -[I had to break this line...] +.. I had to break this line... - This is probably the most complicated parameter... It specifies that +This is probably the most complicated parameter... It specifies that you have some external video hardware (a graphics board), and how to use it under Linux/m68k. The kernel cannot know more about the hardware than you tell it here! The kernel also is unable to set or change any @@ -418,38 +434,44 @@ video modes, since it doesn't know about any board internal. So, you have to switch to that video mode before you start Linux, and cannot switch to another mode once Linux has started. - The first 3 parameters of this sub-option should be obvious: <xres>, +The first 3 parameters of this sub-option should be obvious: <xres>, <yres> and <depth> give the dimensions of the screen and the number of planes (depth). The depth is the logarithm to base 2 of the number of colors possible. (Or, the other way round: The number of colors is 2^depth). - You have to tell the kernel furthermore how the video memory is +You have to tell the kernel furthermore how the video memory is organized. This is done by a letter as <org> parameter: - 'n': "normal planes", i.e. one whole plane after another - 'i': "interleaved planes", i.e. 16 bit of the first plane, than 16 bit + 'n': + "normal planes", i.e. one whole plane after another + 'i': + "interleaved planes", i.e. 16 bit of the first plane, than 16 bit of the next, and so on... This mode is used only with the - built-in Atari video modes, I think there is no card that - supports this mode. - 'p': "packed pixels", i.e. <depth> consecutive bits stand for all - planes of one pixel; this is the most common mode for 8 planes - (256 colors) on graphic cards - 't': "true color" (more or less packed pixels, but without a color - lookup table); usually depth is 24 + built-in Atari video modes, I think there is no card that + supports this mode. + 'p': + "packed pixels", i.e. <depth> consecutive bits stand for all + planes of one pixel; this is the most common mode for 8 planes + (256 colors) on graphic cards + 't': + "true color" (more or less packed pixels, but without a color + lookup table); usually depth is 24 For monochrome modes (i.e., <depth> is 1), the <org> letter has a different meaning: - 'n': normal colors, i.e. 0=white, 1=black - 'i': inverted colors, i.e. 0=black, 1=white + 'n': + normal colors, i.e. 0=white, 1=black + 'i': + inverted colors, i.e. 0=black, 1=white - The next important information about the video hardware is the base +The next important information about the video hardware is the base address of the video memory. That is given in the <scrmem> parameter, as a hexadecimal number with a "0x" prefix. You have to find out this address in the documentation of your hardware. - The next parameter, <scrlen>, tells the kernel about the size of the +The next parameter, <scrlen>, tells the kernel about the size of the video memory. If it's missing, the size is calculated from <xres>, <yres>, and <depth>. For now, it is not useful to write a value here. It would be used only for hardware scrolling (which isn't possible @@ -460,7 +482,7 @@ empty, either by ending the "external:" after the video address or by writing two consecutive semicolons, if you want to give a <vgabase> (it is allowed to leave this parameter empty). - The <vgabase> parameter is optional. If it is not given, the kernel +The <vgabase> parameter is optional. If it is not given, the kernel cannot read or write any color registers of the video hardware, and thus you have to set appropriate colors before you start Linux. But if your card is somehow VGA compatible, you can tell the kernel the base @@ -472,18 +494,18 @@ uses the addresses vgabase+0x3c7...vgabase+0x3c9. The <vgabase> parameter is written in hexadecimal with a "0x" prefix, just as <scrmem>. - <colw> is meaningful only if <vgabase> is specified. It tells the +<colw> is meaningful only if <vgabase> is specified. It tells the kernel how wide each of the color register is, i.e. the number of bits per single color (red/green/blue). Default is 6, another quite usual value is 8. - Also <coltype> is used together with <vgabase>. It tells the kernel +Also <coltype> is used together with <vgabase>. It tells the kernel about the color register model of your gfx board. Currently, the types "vga" (which is also the default) and "mv300" (SANG MV300) are implemented. - Parameter <xres_virtual> is required for ProMST or ET4000 cards where -the physical linelength differs from the visible length. With ProMST, +Parameter <xres_virtual> is required for ProMST or ET4000 cards where +the physical linelength differs from the visible length. With ProMST, xres_virtual must be set to 2048. For ET4000, xres_virtual depends on the initialisation of the video-card. If you're missing a corresponding yres_virtual: the external part is legacy, @@ -499,13 +521,13 @@ currently works only with the ScreenWonder! 4.1.8) monitorcap: ------------------- -Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax> +:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax> This describes the capabilities of a multisync monitor. Don't use it with a fixed-frequency monitor! For now, only the Falcon frame buffer uses the settings of "monitorcap:". - <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies +<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies your monitor can work with, in Hz. <hmin> and <hmax> are the same for the horizontal frequency, in kHz. @@ -520,28 +542,28 @@ If this option is given, the framebuffer device doesn't do any video mode calculations and settings on its own. The only Atari fb device that does this currently is the Falcon. - What you reach with this: Settings for unknown video extensions +What you reach with this: Settings for unknown video extensions aren't overridden by the driver, so you can still use the mode found when booting, when the driver doesn't know to set this mode itself. But this also means, that you can't switch video modes anymore... - An example where you may want to use "keep" is the ScreenBlaster for +An example where you may want to use "keep" is the ScreenBlaster for the Falcon. 4.2) atamouse= -------------- -Syntax: atamouse=<x-threshold>,[<y-threshold>] +:Syntax: atamouse=<x-threshold>,[<y-threshold>] - With this option, you can set the mouse movement reporting threshold. +With this option, you can set the mouse movement reporting threshold. This is the number of pixels of mouse movement that have to accumulate before the IKBD sends a new mouse packet to the kernel. Higher values reduce the mouse interrupt load and thus reduce the chance of keyboard overruns. Lower values give a slightly faster mouse responses and slightly better mouse tracking. - You can set the threshold in x and y separately, but usually this is +You can set the threshold in x and y separately, but usually this is of little practical use. If there's just one number in the option, it is used for both dimensions. The default value is 2 for both thresholds. @@ -550,7 +572,7 @@ thresholds. 4.3) ataflop= ------------- -Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]] +:Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]] The drive type may be 0, 1, or 2, for DD, HD, and ED, resp. This setting affects how many buffers are reserved and which formats are @@ -563,15 +585,15 @@ Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]] no for the Medusa and yes for all others. With the two following parameters, you can change the default - steprate used for drive A and B, resp. + steprate used for drive A and B, resp. 4.4) atascsi= ------------- -Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]] +:Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]] - This option sets some parameters for the Atari native SCSI driver. +This option sets some parameters for the Atari native SCSI driver. Generally, any number of arguments can be omitted from the end. And for each of the numbers, a negative value means "use default". The defaults depend on whether TT-style or Falcon-style SCSI is used. @@ -597,11 +619,14 @@ ignored (others aren't affected). 32). Default: 8/1. (Note: Values > 1 seem to cause problems on a Falcon, cause not yet known.) - The <cmd_per_lun> value at a great part determines the amount of + The <cmd_per_lun> value at a great part determines the amount of memory SCSI reserves for itself. The formula is rather complicated, but I can give you some hints: - no scatter-gather : cmd_per_lun * 232 bytes - full scatter-gather: cmd_per_lun * approx. 17 Kbytes + + no scatter-gather: + cmd_per_lun * 232 bytes + full scatter-gather: + cmd_per_lun * approx. 17 Kbytes <scat-gat>: Size of the scatter-gather table, i.e. the number of requests @@ -634,19 +659,23 @@ ignored (others aren't affected). 4.5 switches= ------------- -Syntax: switches=<list of switches> +:Syntax: switches=<list of switches> - With this option you can switch some hardware lines that are often +With this option you can switch some hardware lines that are often used to enable/disable certain hardware extensions. Examples are OverScan, overclocking, ... - The <list of switches> is a comma-separated list of the following +The <list of switches> is a comma-separated list of the following items: - ikbd: set RTS of the keyboard ACIA high - midi: set RTS of the MIDI ACIA high - snd6: set bit 6 of the PSG port A - snd7: set bit 6 of the PSG port A + ikbd: + set RTS of the keyboard ACIA high + midi: + set RTS of the MIDI ACIA high + snd6: + set bit 6 of the PSG port A + snd7: + set bit 6 of the PSG port A It doesn't make sense to mention a switch more than once (no difference to only once), but you can give as many switches as you @@ -654,16 +683,16 @@ want to enable different features. The switch lines are set as early as possible during kernel initialization (even before determining the present hardware.) - All of the items can also be prefixed with "ov_", i.e. "ov_ikbd", -"ov_midi", ... These options are meant for switching on an OverScan +All of the items can also be prefixed with `ov_`, i.e. `ov_ikbd`, +`ov_midi`, ... These options are meant for switching on an OverScan video extension. The difference to the bare option is that the switch-on is done after video initialization, and somehow synchronized to the HBLANK. A speciality is that ov_ikbd and ov_midi are switched off before rebooting, so that OverScan is disabled and TOS boots correctly. - If you give an option both, with and without the "ov_" prefix, the -earlier initialization ("ov_"-less) takes precedence. But the +If you give an option both, with and without the `ov_` prefix, the +earlier initialization (`ov_`-less) takes precedence. But the switching-off on reset still happens in this case. 5) Options for Amiga Only: @@ -672,10 +701,10 @@ switching-off on reset still happens in this case. 5.1) video= ----------- -Syntax: video=<fbname>:<sub-options...> +:Syntax: video=<fbname>:<sub-options...> The <fbname> parameter specifies the name of the frame buffer, valid -options are `amifb', `cyber', 'virge', `retz3' and `clgen', provided +options are `amifb`, `cyber`, 'virge', `retz3` and `clgen`, provided that the respective frame buffer devices have been compiled into the kernel (or compiled as loadable modules). The behavior of the <fbname> option was changed in 2.1.57 so it is now recommended to specify this @@ -697,9 +726,11 @@ predefined video modes are available: NTSC modes: - ntsc : 640x200, 15 kHz, 60 Hz - ntsc-lace : 640x400, 15 kHz, 60 Hz interlaced + PAL modes: - pal : 640x256, 15 kHz, 50 Hz - pal-lace : 640x512, 15 kHz, 50 Hz interlaced + ECS modes: - multiscan : 640x480, 29 kHz, 57 Hz - multiscan-lace : 640x960, 29 kHz, 57 Hz interlaced @@ -715,6 +746,7 @@ ECS modes: - dblpal-lace : 640x1024, 27 kHz, 47 Hz interlaced - dblntsc : 640x200, 27 kHz, 57 Hz doublescan - dblpal : 640x256, 27 kHz, 47 Hz doublescan + VGA modes: - vga : 640x480, 31 kHz, 60 Hz - vga70 : 640x400, 31 kHz, 70 Hz @@ -726,7 +758,7 @@ chipset and 8-bit color for the AGA chipset. 5.1.2) depth ------------ -Syntax: depth:<nr. of bit-planes> +:Syntax: depth:<nr. of bit-planes> Specify the number of bit-planes for the selected video-mode. @@ -739,32 +771,32 @@ Use inverted display (black on white). Functionally the same as the 5.1.4) font ----------- -Syntax: font:<fontname> +:Syntax: font:<fontname> Specify the font to use in text modes. Functionally the same as the -"font" sub-option for the Atari, except that `PEARL8x8' is used instead -of `VGA8x8' if the vertical size of the display is less than 400 pixel +"font" sub-option for the Atari, except that `PEARL8x8` is used instead +of `VGA8x8` if the vertical size of the display is less than 400 pixel rows. 5.1.5) monitorcap: ------------------- -Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax> +:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax> This describes the capabilities of a multisync monitor. For now, only the color frame buffer uses the settings of "monitorcap:". - <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies +<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies your monitor can work with, in Hz. <hmin> and <hmax> are the same for the horizontal frequency, in kHz. - The defaults are 50;90;15;38 (Generic Amiga multisync monitor). +The defaults are 50;90;15;38 (Generic Amiga multisync monitor). 5.2) fd_def_df0= ---------------- -Syntax: fd_def_df0=<value> +:Syntax: fd_def_df0=<value> Sets the df0 value for "silent" floppy drives. The value should be in hexadecimal with "0x" prefix. @@ -773,7 +805,7 @@ hexadecimal with "0x" prefix. 5.3) wd33c93= ------------- -Syntax: wd33c93=<sub-options...> +:Syntax: wd33c93=<sub-options...> These options affect the A590/A2091, A3000 and GVP Series II SCSI controllers. @@ -784,9 +816,9 @@ below. 5.3.1) nosync ------------- -Syntax: nosync:bitmask +:Syntax: nosync:bitmask - bitmask is a byte where the 1st 7 bits correspond with the 7 +bitmask is a byte where the 1st 7 bits correspond with the 7 possible SCSI devices. Set a bit to prevent sync negotiation on that device. To maintain backwards compatibility, a command-line such as "wd33c93=255" will be automatically translated to @@ -796,35 +828,35 @@ all devices, eg. nosync:0xff. 5.3.2) period ------------- -Syntax: period:ns +:Syntax: period:ns - `ns' is the minimum # of nanoseconds in a SCSI data transfer +`ns` is the minimum # of nanoseconds in a SCSI data transfer period. Default is 500; acceptable values are 250 - 1000. 5.3.3) disconnect ----------------- -Syntax: disconnect:x +:Syntax: disconnect:x - Specify x = 0 to never allow disconnects, 2 to always allow them. +Specify x = 0 to never allow disconnects, 2 to always allow them. x = 1 does 'adaptive' disconnects, which is the default and generally the best choice. 5.3.4) debug ------------ -Syntax: debug:x +:Syntax: debug:x - If `DEBUGGING_ON' is defined, x is a bit mask that causes various +If `DEBUGGING_ON` is defined, x is a bit mask that causes various types of debug output to printed - see the DB_xxx defines in wd33c93.h. 5.3.5) clock ------------ -Syntax: clock:x +:Syntax: clock:x - x = clock input in MHz for WD33c93 chip. Normal values would be from +x = clock input in MHz for WD33c93 chip. Normal values would be from 8 through 20. The default value depends on your hostadapter(s), default for the A3000 internal controller is 14, for the A2091 it's 8 and for the GVP hostadapters it's either 8 or 14, depending on the @@ -834,15 +866,15 @@ hostadapters. 5.3.6) next ----------- - No argument. Used to separate blocks of keywords when there's more +No argument. Used to separate blocks of keywords when there's more than one wd33c93-based host adapter in the system. 5.3.7) nodma ------------ -Syntax: nodma:x +:Syntax: nodma:x - If x is 1 (or if the option is just written as "nodma"), the WD33c93 +If x is 1 (or if the option is just written as "nodma"), the WD33c93 controller will not use DMA (= direct memory access) to access the Amiga's memory. This is useful for some systems (like A3000's and A4000's with the A3640 accelerator, revision 3.0) that have problems @@ -853,32 +885,27 @@ possible. 5.4) gvp11= ----------- -Syntax: gvp11=<addr-mask> +:Syntax: gvp11=<addr-mask> - The earlier versions of the GVP driver did not handle DMA +The earlier versions of the GVP driver did not handle DMA address-mask settings correctly which made it necessary for some people to use this option, in order to get their GVP controller running under Linux. These problems have hopefully been solved and the use of this option is now highly unrecommended! - Incorrect use can lead to unpredictable behavior, so please only use +Incorrect use can lead to unpredictable behavior, so please only use this option if you *know* what you are doing and have a reason to do so. In any case if you experience problems and need to use this option, please inform us about it by mailing to the Linux/68k kernel mailing list. - The address mask set by this option specifies which addresses are +The address mask set by this option specifies which addresses are valid for DMA with the GVP Series II SCSI controller. An address is valid, if no bits are set except the bits that are set in the mask, too. - Some versions of the GVP can only DMA into a 24 bit address range, +Some versions of the GVP can only DMA into a 24 bit address range, some can address a 25 bit address range while others can use the whole 32 bit address range for DMA. The correct setting depends on your controller and should be autodetected by the driver. An example is the 24 bit region which is specified by a mask of 0x00fffffe. - - -/* Local Variables: */ -/* mode: text */ -/* End: */ diff --git a/Documentation/mic/index.rst b/Documentation/mic/index.rst index 082fa8f6a260..3a8d06367ef1 100644 --- a/Documentation/mic/index.rst +++ b/Documentation/mic/index.rst @@ -1,5 +1,3 @@ -:orphan: - ============================================= Intel Many Integrated Core (MIC) architecture ============================================= diff --git a/Documentation/netlabel/index.rst b/Documentation/netlabel/index.rst index 47f1e0e5acd1..984e1b191b12 100644 --- a/Documentation/netlabel/index.rst +++ b/Documentation/netlabel/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ======== NetLabel diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index d3e5dd26db12..e3abfbd32f71 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -706,9 +706,9 @@ num_unsol_na unsolicited IPv6 Neighbor Advertisements) to be issued after a failover event. As soon as the link is up on the new slave (possibly immediately) a peer notification is sent on the - bonding device and each VLAN sub-device. This is repeated at - each link monitor interval (arp_interval or miimon, whichever - is active) if the number is greater than 1. + bonding device and each VLAN sub-device. This is repeated at + the rate specified by peer_notif_delay if the number is + greater than 1. The valid range is 0 - 255; the default value is 1. These options affect only the active-backup mode. These options were added for @@ -727,6 +727,16 @@ packets_per_slave The valid range is 0 - 65535; the default value is 1. This option has effect only in balance-rr mode. +peer_notif_delay + + Specify the delay, in milliseconds, between each peer + notification (gratuitous ARP and unsolicited IPv6 Neighbor + Advertisement) when they are issued after a failover event. + This delay should be a multiple of the link monitor interval + (arp_interval or miimon, whichever is active). The default + value is 0 which means to match the value of the link monitor + interval. + primary A string (eth0, eth2, etc) specifying which slave is the diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 48c79e78817b..df33674799b5 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -2287,7 +2287,7 @@ addr_scope_policy - INTEGER /proc/sys/net/core/* - Please see: Documentation/sysctl/net.txt for descriptions of these entries. + Please see: Documentation/admin-guide/sysctl/net.rst for descriptions of these entries. /proc/sys/net/unix/* diff --git a/Documentation/pcmcia/index.rst b/Documentation/pcmcia/index.rst index 779c8527109e..7ae1f62fca14 100644 --- a/Documentation/pcmcia/index.rst +++ b/Documentation/pcmcia/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ====== pcmcia diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.txt index b154f6c0c36e..c33ba2befbf8 100644 --- a/Documentation/pi-futex.txt +++ b/Documentation/pi-futex.txt @@ -119,4 +119,4 @@ properties of futexes, and all four combinations are possible: futex, robust-futex, PI-futex, robust+PI-futex. More details about priority inheritance can be found in -Documentation/locking/rt-mutex.txt. +Documentation/locking/rt-mutex.rst. diff --git a/Documentation/power/apm-acpi.txt b/Documentation/power/apm-acpi.rst index 6cc423d3662e..5b90d947126d 100644 --- a/Documentation/power/apm-acpi.txt +++ b/Documentation/power/apm-acpi.rst @@ -1,5 +1,7 @@ +============ APM or ACPI? ------------- +============ + If you have a relatively recent x86 mobile, desktop, or server system, odds are it supports either Advanced Power Management (APM) or Advanced Configuration and Power Interface (ACPI). ACPI is the newer @@ -28,5 +30,7 @@ and be sure that they are started sometime in the system boot process. Go ahead and start both. If ACPI or APM is not available on your system the associated daemon will exit gracefully. - apmd: http://ftp.debian.org/pool/main/a/apmd/ - acpid: http://acpid.sf.net/ + ===== ======================================= + apmd http://ftp.debian.org/pool/main/a/apmd/ + acpid http://acpid.sf.net/ + ===== ======================================= diff --git a/Documentation/power/basic-pm-debugging.txt b/Documentation/power/basic-pm-debugging.rst index 708f87f78a75..69862e759c30 100644 --- a/Documentation/power/basic-pm-debugging.txt +++ b/Documentation/power/basic-pm-debugging.rst @@ -1,12 +1,16 @@ +================================= Debugging hibernation and suspend +================================= + (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL 1. Testing hibernation (aka suspend to disk or STD) +=================================================== -To check if hibernation works, you can try to hibernate in the "reboot" mode: +To check if hibernation works, you can try to hibernate in the "reboot" mode:: -# echo reboot > /sys/power/disk -# echo disk > /sys/power/state + # echo reboot > /sys/power/disk + # echo disk > /sys/power/state and the system should create a hibernation image, reboot, resume and get back to the command prompt where you have started the transition. If that happens, @@ -15,20 +19,21 @@ test at least a couple of times in a row for confidence. [This is necessary, because some problems only show up on a second attempt at suspending and resuming the system.] Moreover, hibernating in the "reboot" and "shutdown" modes causes the PM core to skip some platform-related callbacks which on ACPI -systems might be necessary to make hibernation work. Thus, if your machine fails -to hibernate or resume in the "reboot" mode, you should try the "platform" mode: +systems might be necessary to make hibernation work. Thus, if your machine +fails to hibernate or resume in the "reboot" mode, you should try the +"platform" mode:: -# echo platform > /sys/power/disk -# echo disk > /sys/power/state + # echo platform > /sys/power/disk + # echo disk > /sys/power/state which is the default and recommended mode of hibernation. Unfortunately, the "platform" mode of hibernation does not work on some systems with broken BIOSes. In such cases the "shutdown" mode of hibernation might -work: +work:: -# echo shutdown > /sys/power/disk -# echo disk > /sys/power/state + # echo shutdown > /sys/power/disk + # echo disk > /sys/power/state (it is similar to the "reboot" mode, but it requires you to press the power button to make the system resume). @@ -37,6 +42,7 @@ If neither "platform" nor "shutdown" hibernation mode works, you will need to identify what goes wrong. a) Test modes of hibernation +---------------------------- To find out why hibernation fails on your system, you can use a special testing facility available if the kernel is compiled with CONFIG_PM_DEBUG set. Then, @@ -44,36 +50,38 @@ there is the file /sys/power/pm_test that can be used to make the hibernation core run in a test mode. There are 5 test modes available: freezer -- test the freezing of processes + - test the freezing of processes devices -- test the freezing of processes and suspending of devices + - test the freezing of processes and suspending of devices platform -- test the freezing of processes, suspending of devices and platform - global control methods(*) + - test the freezing of processes, suspending of devices and platform + global control methods [1]_ processors -- test the freezing of processes, suspending of devices, platform - global control methods(*) and the disabling of nonboot CPUs + - test the freezing of processes, suspending of devices, platform + global control methods [1]_ and the disabling of nonboot CPUs core -- test the freezing of processes, suspending of devices, platform global - control methods(*), the disabling of nonboot CPUs and suspending of - platform/system devices + - test the freezing of processes, suspending of devices, platform global + control methods\ [1]_, the disabling of nonboot CPUs and suspending + of platform/system devices + +.. [1] -(*) the platform global control methods are only available on ACPI systems + the platform global control methods are only available on ACPI systems and are only tested if the hibernation mode is set to "platform" To use one of them it is necessary to write the corresponding string to /sys/power/pm_test (eg. "devices" to test the freezing of processes and suspending devices) and issue the standard hibernation commands. For example, to use the "devices" test mode along with the "platform" mode of hibernation, -you should do the following: +you should do the following:: -# echo devices > /sys/power/pm_test -# echo platform > /sys/power/disk -# echo disk > /sys/power/state + # echo devices > /sys/power/pm_test + # echo platform > /sys/power/disk + # echo disk > /sys/power/state Then, the kernel will try to freeze processes, suspend devices, wait a few seconds (5 by default, but configurable by the suspend.pm_test_delay module @@ -108,11 +116,12 @@ If the "devices" test fails, most likely there is a driver that cannot suspend or resume its device (in the latter case the system may hang or become unstable after the test, so please take that into consideration). To find this driver, you can carry out a binary search according to the rules: + - if the test fails, unload a half of the drivers currently loaded and repeat -(that would probably involve rebooting the system, so always note what drivers -have been loaded before the test), + (that would probably involve rebooting the system, so always note what drivers + have been loaded before the test), - if the test succeeds, load a half of the drivers you have unloaded most -recently and repeat. + recently and repeat. Once you have found the failing driver (there can be more than just one of them), you have to unload it every time before hibernation. In that case please @@ -146,6 +155,7 @@ indicates a serious problem that very well may be related to the hardware, but please report it anyway. b) Testing minimal configuration +-------------------------------- If all of the hibernation test modes work, you can boot the system with the "init=/bin/bash" command line parameter and attempt to hibernate in the @@ -165,14 +175,15 @@ Again, if you find the offending module(s), it(they) must be unloaded every time before hibernation, and please report the problem with it(them). c) Using the "test_resume" hibernation option +--------------------------------------------- /sys/power/disk generally tells the kernel what to do after creating a hibernation image. One of the available options is "test_resume" which causes the just created image to be used for immediate restoration. Namely, -after doing: +after doing:: -# echo test_resume > /sys/power/disk -# echo disk > /sys/power/state + # echo test_resume > /sys/power/disk + # echo disk > /sys/power/state a hibernation image will be created and a resume from it will be triggered immediately without involving the platform firmware in any way. @@ -190,6 +201,7 @@ to resume may be related to the differences between the restore and image kernels. d) Advanced debugging +--------------------- In case that hibernation does not work on your system even in the minimal configuration and compiling more drivers as modules is not practical or some @@ -200,9 +212,10 @@ kernel messages using the serial console. This may provide you with some information about the reasons of the suspend (resume) failure. Alternatively, it may be possible to use a FireWire port for debugging with firescope (http://v3.sk/~lkundrak/firescope/). On x86 it is also possible to -use the PM_TRACE mechanism documented in Documentation/power/s2ram.txt . +use the PM_TRACE mechanism documented in Documentation/power/s2ram.rst . 2. Testing suspend to RAM (STR) +=============================== To verify that the STR works, it is generally more convenient to use the s2ram tool available from http://suspend.sf.net and documented at @@ -230,7 +243,8 @@ you will have to unload them every time before an STR transition (ie. before you run s2ram), and please report the problems with them. There is a debugfs entry which shows the suspend to RAM statistics. Here is an -example of its output. +example of its output:: + # mount -t debugfs none /sys/kernel/debug # cat /sys/kernel/debug/suspend_stats success: 20 @@ -248,6 +262,7 @@ example of its output. -16 last_failed_step: suspend suspend + Field success means the success number of suspend to RAM, and field fail means the failure number. Others are the failure number of different steps of suspend to RAM. suspend_stats just lists the last 2 failed devices, error number and diff --git a/Documentation/power/charger-manager.txt b/Documentation/power/charger-manager.rst index 9ff1105e58d6..84fab9376792 100644 --- a/Documentation/power/charger-manager.txt +++ b/Documentation/power/charger-manager.rst @@ -1,4 +1,7 @@ +=============== Charger Manager +=============== + (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL Charger Manager provides in-kernel battery charger management that @@ -55,41 +58,39 @@ Charger Manager supports the following: notification to users with UEVENT. 2. Global Charger-Manager Data related with suspend_again -======================================================== +========================================================= In order to setup Charger Manager with suspend-again feature (in-suspend monitoring), the user should provide charger_global_desc -with setup_charger_manager(struct charger_global_desc *). +with setup_charger_manager(`struct charger_global_desc *`). This charger_global_desc data for in-suspend monitoring is global as the name suggests. Thus, the user needs to provide only once even if there are multiple batteries. If there are multiple batteries, the multiple instances of Charger Manager share the same charger_global_desc and it will manage in-suspend monitoring for all instances of Charger Manager. -The user needs to provide all the three entries properly in order to activate -in-suspend monitoring: - -struct charger_global_desc { +The user needs to provide all the three entries to `struct charger_global_desc` +properly in order to activate in-suspend monitoring: -char *rtc_name; - : The name of rtc (e.g., "rtc0") used to wakeup the system from +`char *rtc_name;` + The name of rtc (e.g., "rtc0") used to wakeup the system from suspend for Charger Manager. The alarm interrupt (AIE) of the rtc should be able to wake up the system from suspend. Charger Manager saves and restores the alarm value and use the previously-defined alarm if it is going to go off earlier than Charger Manager so that Charger Manager does not interfere with previously-defined alarms. -bool (*rtc_only_wakeup)(void); - : This callback should let CM know whether +`bool (*rtc_only_wakeup)(void);` + This callback should let CM know whether the wakeup-from-suspend is caused only by the alarm of "rtc" in the same struct. If there is any other wakeup source triggered the wakeup, it should return false. If the "rtc" is the only wakeup reason, it should return true. -bool assume_timer_stops_in_suspend; - : if true, Charger Manager assumes that +`bool assume_timer_stops_in_suspend;` + if true, Charger Manager assumes that the timer (CM uses jiffies as timer) stops during suspend. Then, CM assumes that the suspend-duration is same as the alarm length. -}; + 3. How to setup suspend_again ============================= @@ -109,26 +110,28 @@ if the system was woken up by Charger Manager and the polling ============================================= For each battery charged independently from other batteries (if a series of batteries are charged by a single charger, they are counted as one independent -battery), an instance of Charger Manager is attached to it. +battery), an instance of Charger Manager is attached to it. The following -struct charger_desc { +struct charger_desc elements: -char *psy_name; - : The power-supply-class name of the battery. Default is +`char *psy_name;` + The power-supply-class name of the battery. Default is "battery" if psy_name is NULL. Users can access the psy entries at "/sys/class/power_supply/[psy_name]/". -enum polling_modes polling_mode; - : CM_POLL_DISABLE: do not poll this battery. - CM_POLL_ALWAYS: always poll this battery. - CM_POLL_EXTERNAL_POWER_ONLY: poll this battery if and only if - an external power source is attached. - CM_POLL_CHARGING_ONLY: poll this battery if and only if the - battery is being charged. - -unsigned int fullbatt_vchkdrop_ms; -unsigned int fullbatt_vchkdrop_uV; - : If both have non-zero values, Charger Manager will check the +`enum polling_modes polling_mode;` + CM_POLL_DISABLE: + do not poll this battery. + CM_POLL_ALWAYS: + always poll this battery. + CM_POLL_EXTERNAL_POWER_ONLY: + poll this battery if and only if an external power + source is attached. + CM_POLL_CHARGING_ONLY: + poll this battery if and only if the battery is being charged. + +`unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;` + If both have non-zero values, Charger Manager will check the battery voltage drop fullbatt_vchkdrop_ms after the battery is fully charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger Manager will try to recharge the battery by disabling and enabling @@ -136,50 +139,52 @@ unsigned int fullbatt_vchkdrop_uV; condition) is needed to be implemented with hardware interrupts from fuel gauges or charger devices/chips. -unsigned int fullbatt_uV; - : If specified with a non-zero value, Charger Manager assumes +`unsigned int fullbatt_uV;` + If specified with a non-zero value, Charger Manager assumes that the battery is full (capacity = 100) if the battery is not being charged and the battery voltage is equal to or greater than fullbatt_uV. -unsigned int polling_interval_ms; - : Required polling interval in ms. Charger Manager will poll +`unsigned int polling_interval_ms;` + Required polling interval in ms. Charger Manager will poll this battery every polling_interval_ms or more frequently. -enum data_source battery_present; - : CM_BATTERY_PRESENT: assume that the battery exists. - CM_NO_BATTERY: assume that the battery does not exists. - CM_FUEL_GAUGE: get battery presence information from fuel gauge. - CM_CHARGER_STAT: get battery presence from chargers. - -char **psy_charger_stat; - : An array ending with NULL that has power-supply-class names of +`enum data_source battery_present;` + CM_BATTERY_PRESENT: + assume that the battery exists. + CM_NO_BATTERY: + assume that the battery does not exists. + CM_FUEL_GAUGE: + get battery presence information from fuel gauge. + CM_CHARGER_STAT: + get battery presence from chargers. + +`char **psy_charger_stat;` + An array ending with NULL that has power-supply-class names of chargers. Each power-supply-class should provide "PRESENT" (if battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an external power source is attached or not), and "STATUS" (shows whether the battery is {"FULL" or not FULL} or {"FULL", "Charging", "Discharging", "NotCharging"}). -int num_charger_regulators; -struct regulator_bulk_data *charger_regulators; - : Regulators representing the chargers in the form for +`int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;` + Regulators representing the chargers in the form for regulator framework's bulk functions. -char *psy_fuel_gauge; - : Power-supply-class name of the fuel gauge. +`char *psy_fuel_gauge;` + Power-supply-class name of the fuel gauge. -int (*temperature_out_of_range)(int *mC); -bool measure_battery_temp; - : This callback returns 0 if the temperature is safe for charging, +`int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;` + This callback returns 0 if the temperature is safe for charging, a positive number if it is too hot to charge, and a negative number if it is too cold to charge. With the variable mC, the callback returns the temperature in 1/1000 of centigrade. The source of temperature can be battery or ambient one according to the value of measure_battery_temp. -}; + 5. Notify Charger-Manager of charger events: cm_notify_event() -========================================================= +============================================================== If there is an charger event is required to notify Charger Manager, a charger device driver that triggers the event can call cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager. diff --git a/Documentation/power/drivers-testing.txt b/Documentation/power/drivers-testing.rst index 638afdf4d6b8..e53f1999fc39 100644 --- a/Documentation/power/drivers-testing.txt +++ b/Documentation/power/drivers-testing.rst @@ -1,7 +1,11 @@ +==================================================== Testing suspend and resume support in device drivers +==================================================== + (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL 1. Preparing the test system +============================ Unfortunately, to effectively test the support for the system-wide suspend and resume transitions in a driver, it is necessary to suspend and resume a fully @@ -14,19 +18,20 @@ the machine's BIOS. Of course, for this purpose the test system has to be known to suspend and resume without the driver being tested. Thus, if possible, you should first resolve all suspend/resume-related problems in the test system before you start -testing the new driver. Please see Documentation/power/basic-pm-debugging.txt +testing the new driver. Please see Documentation/power/basic-pm-debugging.rst for more information about the debugging of suspend/resume functionality. 2. Testing the driver +===================== Once you have resolved the suspend/resume-related problems with your test system without the new driver, you are ready to test it: a) Build the driver as a module, load it and try the test modes of hibernation - (see: Documentation/power/basic-pm-debugging.txt, 1). + (see: Documentation/power/basic-pm-debugging.rst, 1). b) Load the driver and attempt to hibernate in the "reboot", "shutdown" and - "platform" modes (see: Documentation/power/basic-pm-debugging.txt, 1). + "platform" modes (see: Documentation/power/basic-pm-debugging.rst, 1). c) Compile the driver directly into the kernel and try the test modes of hibernation. @@ -34,12 +39,12 @@ c) Compile the driver directly into the kernel and try the test modes of d) Attempt to hibernate with the driver compiled directly into the kernel in the "reboot", "shutdown" and "platform" modes. -e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.txt, +e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.rst, 2). [As far as the STR tests are concerned, it should not matter whether or not the driver is built as a module.] f) Attempt to suspend to RAM using the s2ram tool with the driver loaded - (see: Documentation/power/basic-pm-debugging.txt, 2). + (see: Documentation/power/basic-pm-debugging.rst, 2). Each of the above tests should be repeated several times and the STD tests should be mixed with the STR tests. If any of them fails, the driver cannot be diff --git a/Documentation/power/energy-model.txt b/Documentation/power/energy-model.rst index a2b0ae4c76bd..90a345d57ae9 100644 --- a/Documentation/power/energy-model.txt +++ b/Documentation/power/energy-model.rst @@ -1,6 +1,6 @@ - ==================== - Energy Model of CPUs - ==================== +==================== +Energy Model of CPUs +==================== 1. Overview ----------- @@ -20,7 +20,7 @@ kernel, hence enabling to avoid redundant work. The figure below depicts an example of drivers (Arm-specific here, but the approach is applicable to any architecture) providing power costs to the EM -framework, and interested clients reading the data from it. +framework, and interested clients reading the data from it:: +---------------+ +-----------------+ +---------------+ | Thermal (IPA) | | Scheduler (EAS) | | Other | @@ -58,15 +58,17 @@ micro-architectures. 2. Core APIs ------------ - 2.1 Config options +2.1 Config options +^^^^^^^^^^^^^^^^^^ CONFIG_ENERGY_MODEL must be enabled to use the EM framework. - 2.2 Registration of performance domains +2.2 Registration of performance domains +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Drivers are expected to register performance domains into the EM framework by -calling the following API: +calling the following API:: int em_register_perf_domain(cpumask_t *span, unsigned int nr_states, struct em_data_callback *cb); @@ -80,7 +82,8 @@ callback, and kernel/power/energy_model.c for further documentation on this API. - 2.3 Accessing performance domains +2.3 Accessing performance domains +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Subsystems interested in the energy model of a CPU can retrieve it using the em_cpu_get() API. The energy model tables are allocated once upon creation of @@ -99,46 +102,46 @@ More details about the above APIs can be found in include/linux/energy_model.h. This section provides a simple example of a CPUFreq driver registering a performance domain in the Energy Model framework using the (fake) 'foo' protocol. The driver implements an est_power() function to be provided to the -EM framework. - - -> drivers/cpufreq/foo_cpufreq.c - -01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu) -02 { -03 long freq, power; -04 -05 /* Use the 'foo' protocol to ceil the frequency */ -06 freq = foo_get_freq_ceil(cpu, *KHz); -07 if (freq < 0); -08 return freq; -09 -10 /* Estimate the power cost for the CPU at the relevant freq. */ -11 power = foo_estimate_power(cpu, freq); -12 if (power < 0); -13 return power; -14 -15 /* Return the values to the EM framework */ -16 *mW = power; -17 *KHz = freq; -18 -19 return 0; -20 } -21 -22 static int foo_cpufreq_init(struct cpufreq_policy *policy) -23 { -24 struct em_data_callback em_cb = EM_DATA_CB(est_power); -25 int nr_opp, ret; -26 -27 /* Do the actual CPUFreq init work ... */ -28 ret = do_foo_cpufreq_init(policy); -29 if (ret) -30 return ret; -31 -32 /* Find the number of OPPs for this policy */ -33 nr_opp = foo_get_nr_opp(policy); -34 -35 /* And register the new performance domain */ -36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb); -37 -38 return 0; -39 } +EM framework:: + + -> drivers/cpufreq/foo_cpufreq.c + + 01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu) + 02 { + 03 long freq, power; + 04 + 05 /* Use the 'foo' protocol to ceil the frequency */ + 06 freq = foo_get_freq_ceil(cpu, *KHz); + 07 if (freq < 0); + 08 return freq; + 09 + 10 /* Estimate the power cost for the CPU at the relevant freq. */ + 11 power = foo_estimate_power(cpu, freq); + 12 if (power < 0); + 13 return power; + 14 + 15 /* Return the values to the EM framework */ + 16 *mW = power; + 17 *KHz = freq; + 18 + 19 return 0; + 20 } + 21 + 22 static int foo_cpufreq_init(struct cpufreq_policy *policy) + 23 { + 24 struct em_data_callback em_cb = EM_DATA_CB(est_power); + 25 int nr_opp, ret; + 26 + 27 /* Do the actual CPUFreq init work ... */ + 28 ret = do_foo_cpufreq_init(policy); + 29 if (ret) + 30 return ret; + 31 + 32 /* Find the number of OPPs for this policy */ + 33 nr_opp = foo_get_nr_opp(policy); + 34 + 35 /* And register the new performance domain */ + 36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb); + 37 + 38 return 0; + 39 } diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.rst index cd283190855a..ef110fe55e82 100644 --- a/Documentation/power/freezing-of-tasks.txt +++ b/Documentation/power/freezing-of-tasks.rst @@ -1,13 +1,18 @@ +================= Freezing of tasks - (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL +================= + +(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL I. What is the freezing of tasks? +================================= The freezing of tasks is a mechanism by which user space processes and some kernel threads are controlled during hibernation or system-wide suspend (on some architectures). II. How does it work? +===================== There are three per-task flags used for that, PF_NOFREEZE, PF_FROZEN and PF_FREEZER_SKIP (the last one is auxiliary). The tasks that have @@ -41,7 +46,7 @@ explicitly in suitable places or use the wait_event_freezable() or wait_event_freezable_timeout() macros (defined in include/linux/freezer.h) that combine interruptible sleep with checking if the task is to be frozen and calling try_to_freeze(). The main loop of a freezable kernel thread may look -like the following one: +like the following one:: set_freezable(); do { @@ -65,7 +70,7 @@ order to clear the PF_FROZEN flag for each frozen task. Then, the tasks that have been frozen leave __refrigerator() and continue running. -Rationale behind the functions dealing with freezing and thawing of tasks: +Rationale behind the functions dealing with freezing and thawing of tasks ------------------------------------------------------------------------- freeze_processes(): @@ -86,6 +91,7 @@ thaw_processes(): III. Which kernel threads are freezable? +======================================== Kernel threads are not freezable by default. However, a kernel thread may clear PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE @@ -93,37 +99,39 @@ directly is not allowed). From this point it is regarded as freezable and must call try_to_freeze() in a suitable place. IV. Why do we do that? +====================== Generally speaking, there is a couple of reasons to use the freezing of tasks: 1. The principal reason is to prevent filesystems from being damaged after -hibernation. At the moment we have no simple means of checkpointing -filesystems, so if there are any modifications made to filesystem data and/or -metadata on disks, we cannot bring them back to the state from before the -modifications. At the same time each hibernation image contains some -filesystem-related information that must be consistent with the state of the -on-disk data and metadata after the system memory state has been restored from -the image (otherwise the filesystems will be damaged in a nasty way, usually -making them almost impossible to repair). We therefore freeze tasks that might -cause the on-disk filesystems' data and metadata to be modified after the -hibernation image has been created and before the system is finally powered off. -The majority of these are user space processes, but if any of the kernel threads -may cause something like this to happen, they have to be freezable. + hibernation. At the moment we have no simple means of checkpointing + filesystems, so if there are any modifications made to filesystem data and/or + metadata on disks, we cannot bring them back to the state from before the + modifications. At the same time each hibernation image contains some + filesystem-related information that must be consistent with the state of the + on-disk data and metadata after the system memory state has been restored + from the image (otherwise the filesystems will be damaged in a nasty way, + usually making them almost impossible to repair). We therefore freeze + tasks that might cause the on-disk filesystems' data and metadata to be + modified after the hibernation image has been created and before the + system is finally powered off. The majority of these are user space + processes, but if any of the kernel threads may cause something like this + to happen, they have to be freezable. 2. Next, to create the hibernation image we need to free a sufficient amount of -memory (approximately 50% of available RAM) and we need to do that before -devices are deactivated, because we generally need them for swapping out. Then, -after the memory for the image has been freed, we don't want tasks to allocate -additional memory and we prevent them from doing that by freezing them earlier. -[Of course, this also means that device drivers should not allocate substantial -amounts of memory from their .suspend() callbacks before hibernation, but this -is a separate issue.] + memory (approximately 50% of available RAM) and we need to do that before + devices are deactivated, because we generally need them for swapping out. + Then, after the memory for the image has been freed, we don't want tasks + to allocate additional memory and we prevent them from doing that by + freezing them earlier. [Of course, this also means that device drivers + should not allocate substantial amounts of memory from their .suspend() + callbacks before hibernation, but this is a separate issue.] 3. The third reason is to prevent user space processes and some kernel threads -from interfering with the suspending and resuming of devices. A user space -process running on a second CPU while we are suspending devices may, for -example, be troublesome and without the freezing of tasks we would need some -safeguards against race conditions that might occur in such a case. + from interfering with the suspending and resuming of devices. A user space + process running on a second CPU while we are suspending devices may, for + example, be troublesome and without the freezing of tasks we would need some + safeguards against race conditions that might occur in such a case. Although Linus Torvalds doesn't like the freezing of tasks, he said this in one of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608): @@ -132,7 +140,7 @@ of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608): Linus: In many ways, 'at all'. -I _do_ realize the IO request queue issues, and that we cannot actually do +I **do** realize the IO request queue issues, and that we cannot actually do s2ram with some devices in the middle of a DMA. So we want to be able to avoid *that*, there's no question about that. And I suspect that stopping user threads and then waiting for a sync is practically one of the easier @@ -150,17 +158,18 @@ thawed after the driver's .resume() callback has run, so it won't be accessing the device while it's suspended. 4. Another reason for freezing tasks is to prevent user space processes from -realizing that hibernation (or suspend) operation takes place. Ideally, user -space processes should not notice that such a system-wide operation has occurred -and should continue running without any problems after the restore (or resume -from suspend). Unfortunately, in the most general case this is quite difficult -to achieve without the freezing of tasks. Consider, for example, a process -that depends on all CPUs being online while it's running. Since we need to -disable nonboot CPUs during the hibernation, if this process is not frozen, it -may notice that the number of CPUs has changed and may start to work incorrectly -because of that. + realizing that hibernation (or suspend) operation takes place. Ideally, user + space processes should not notice that such a system-wide operation has + occurred and should continue running without any problems after the restore + (or resume from suspend). Unfortunately, in the most general case this + is quite difficult to achieve without the freezing of tasks. Consider, + for example, a process that depends on all CPUs being online while it's + running. Since we need to disable nonboot CPUs during the hibernation, + if this process is not frozen, it may notice that the number of CPUs has + changed and may start to work incorrectly because of that. V. Are there any problems related to the freezing of tasks? +=========================================================== Yes, there are. @@ -172,11 +181,12 @@ may be undesirable. That's why kernel threads are not freezable by default. Second, there are the following two problems related to the freezing of user space processes: + 1. Putting processes into an uninterruptible sleep distorts the load average. 2. Now that we have FUSE, plus the framework for doing device drivers in -userspace, it gets even more complicated because some userspace processes are -now doing the sorts of things that kernel threads do -(https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html). + userspace, it gets even more complicated because some userspace processes are + now doing the sorts of things that kernel threads do + (https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html). The problem 1. seems to be fixable, although it hasn't been fixed so far. The other one is more serious, but it seems that we can work around it by using @@ -201,6 +211,7 @@ requested early enough using the suspend notifier API described in Documentation/driver-api/pm/notifiers.rst. VI. Are there any precautions to be taken to prevent freezing failures? +======================================================================= Yes, there are. @@ -226,6 +237,8 @@ So, to summarize, use [un]lock_system_sleep() instead of directly using mutex_[un]lock(&system_transition_mutex). That would prevent freezing failures. V. Miscellaneous +================ + /sys/power/pm_freeze_timeout controls how long it will cost at most to freeze all user space processes or all freezable kernel threads, in unit of millisecond. The default value is 20000, with range of unsigned integer. diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst new file mode 100644 index 000000000000..20415f21e48a --- /dev/null +++ b/Documentation/power/index.rst @@ -0,0 +1,46 @@ +:orphan: + +================ +Power Management +================ + +.. toctree:: + :maxdepth: 1 + + apm-acpi + basic-pm-debugging + charger-manager + drivers-testing + energy-model + freezing-of-tasks + interface + opp + pci + pm_qos_interface + power_supply_class + runtime_pm + s2ram + suspend-and-cpuhotplug + suspend-and-interrupts + swsusp-and-swap-files + swsusp-dmcrypt + swsusp + video + tricks + + userland-swsusp + + powercap/powercap + + regulator/consumer + regulator/design + regulator/machine + regulator/overview + regulator/regulator + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/power/interface.txt b/Documentation/power/interface.rst index 27df7f98668a..8d270ed27228 100644 --- a/Documentation/power/interface.txt +++ b/Documentation/power/interface.rst @@ -1,4 +1,6 @@ +=========================================== Power Management Interface for System Sleep +=========================================== Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> @@ -11,10 +13,10 @@ mounted at /sys). Reading from it returns a list of supported sleep states, encoded as: -'freeze' (Suspend-to-Idle) -'standby' (Power-On Suspend) -'mem' (Suspend-to-RAM) -'disk' (Suspend-to-Disk) +- 'freeze' (Suspend-to-Idle) +- 'standby' (Power-On Suspend) +- 'mem' (Suspend-to-RAM) +- 'disk' (Suspend-to-Disk) Suspend-to-Idle is always supported. Suspend-to-Disk is always supported too as long the kernel has been configured to support hibernation at all @@ -32,18 +34,18 @@ Specifically, it tells the kernel what to do after creating a hibernation image. Reading from it returns a list of supported options encoded as: -'platform' (put the system into sleep using a platform-provided method) -'shutdown' (shut the system down) -'reboot' (reboot the system) -'suspend' (trigger a Suspend-to-RAM transition) -'test_resume' (resume-after-hibernation test mode) +- 'platform' (put the system into sleep using a platform-provided method) +- 'shutdown' (shut the system down) +- 'reboot' (reboot the system) +- 'suspend' (trigger a Suspend-to-RAM transition) +- 'test_resume' (resume-after-hibernation test mode) The currently selected option is printed in square brackets. The 'platform' option is only available if the platform provides a special mechanism to put the system to sleep after creating a hibernation image (ACPI does that, for example). The 'suspend' option is available if Suspend-to-RAM -is supported. Refer to Documentation/power/basic-pm-debugging.txt for the +is supported. Refer to Documentation/power/basic-pm-debugging.rst for the description of the 'test_resume' option. To select an option, write the string representing it to /sys/power/disk. @@ -71,7 +73,7 @@ If /sys/power/pm_trace contains '1', the fingerprint of each suspend/resume event point in turn will be stored in the RTC memory (overwriting the actual RTC information), so it will survive a system crash if one occurs right after storing it and it can be used later to identify the driver that caused the crash -to happen (see Documentation/power/s2ram.txt for more information). +to happen (see Documentation/power/s2ram.rst for more information). Initially it contains '0' which may be changed to '1' by writing a string representing a nonzero integer into it. diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.rst index 0c007e250cd1..b3cf1def9dee 100644 --- a/Documentation/power/opp.txt +++ b/Documentation/power/opp.rst @@ -1,20 +1,23 @@ +========================================== Operating Performance Points (OPP) Library ========================================== (C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated -Contents --------- -1. Introduction -2. Initial OPP List Registration -3. OPP Search Functions -4. OPP Availability Control Functions -5. OPP Data Retrieval Functions -6. Data Structures +.. Contents + + 1. Introduction + 2. Initial OPP List Registration + 3. OPP Search Functions + 4. OPP Availability Control Functions + 5. OPP Data Retrieval Functions + 6. Data Structures 1. Introduction =============== + 1.1 What is an Operating Performance Point (OPP)? +------------------------------------------------- Complex SoCs of today consists of a multiple sub-modules working in conjunction. In an operational system executing varied use cases, not all modules in the SoC @@ -28,16 +31,19 @@ the device will support per domain are called Operating Performance Points or OPPs. As an example: + Let us consider an MPU device which supports the following: {300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V}, {1GHz at minimum voltage of 1.3V} We can represent these as three OPPs as the following {Hz, uV} tuples: -{300000000, 1000000} -{800000000, 1200000} -{1000000000, 1300000} + +- {300000000, 1000000} +- {800000000, 1200000} +- {1000000000, 1300000} 1.2 Operating Performance Points Library +---------------------------------------- OPP library provides a set of helper functions to organize and query the OPP information. The library is located in drivers/base/power/opp.c and the header @@ -46,9 +52,10 @@ CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to optionally boot at a certain OPP without needing cpufreq. -Typical usage of the OPP library is as follows: -(users) -> registers a set of default OPPs -> (library) -SoC framework -> modifies on required cases certain OPPs -> OPP layer +Typical usage of the OPP library is as follows:: + + (users) -> registers a set of default OPPs -> (library) + SoC framework -> modifies on required cases certain OPPs -> OPP layer -> queries to search/retrieve information -> OPP layer expects each domain to be represented by a unique device pointer. SoC @@ -57,8 +64,9 @@ list is expected to be an optimally small number typically around 5 per device. This initial list contains a set of OPPs that the framework expects to be safely enabled by default in the system. -Note on OPP Availability: ------------------------- +Note on OPP Availability +^^^^^^^^^^^^^^^^^^^^^^^^ + As the system proceeds to operate, SoC framework may choose to make certain OPPs available or not available on each device based on various external factors. Example usage: Thermal management or other exceptional situations where @@ -88,7 +96,8 @@ registering the OPPs is maintained by OPP library throughout the device operation. The SoC framework can subsequently control the availability of the OPPs dynamically using the dev_pm_opp_enable / disable functions. -dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer. +dev_pm_opp_add + Add a new OPP for a specific domain represented by the device pointer. The OPP is defined using the frequency and voltage. Once added, the OPP is assumed to be available and control of it's availability can be done with the dev_pm_opp_enable/disable functions. OPP library internally stores @@ -96,9 +105,11 @@ dev_pm_opp_add - Add a new OPP for a specific domain represented by the device p used by SoC framework to define a optimal list as per the demands of SoC usage environment. - WARNING: Do not use this function in interrupt context. + WARNING: + Do not use this function in interrupt context. + + Example:: - Example: soc_pm_init() { /* Do things */ @@ -125,12 +136,15 @@ Callers of these functions shall call dev_pm_opp_put() after they have used the OPP. Otherwise the memory for the OPP will never get freed and result in memleak. -dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and +dev_pm_opp_find_freq_exact + Search for an OPP based on an *exact* frequency and availability. This function is especially useful to enable an OPP which is not available by default. Example: In a case when SoC framework detects a situation where a higher frequency could be made available, it can use this function to - find the OPP prior to call the dev_pm_opp_enable to actually make it available. + find the OPP prior to call the dev_pm_opp_enable to actually make + it available:: + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); dev_pm_opp_put(opp); /* dont operate on the pointer.. just do a sanity check.. */ @@ -141,27 +155,34 @@ dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and dev_pm_opp_enable(dev,1000000000); } - NOTE: This is the only search function that operates on OPPs which are - not available. + NOTE: + This is the only search function that operates on OPPs which are + not available. -dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the +dev_pm_opp_find_freq_floor + Search for an available OPP which is *at most* the provided frequency. This function is useful while searching for a lesser match OR operating on OPP information in the order of decreasing frequency. - Example: To find the highest opp for a device: + Example: To find the highest opp for a device:: + freq = ULONG_MAX; opp = dev_pm_opp_find_freq_floor(dev, &freq); dev_pm_opp_put(opp); -dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the +dev_pm_opp_find_freq_ceil + Search for an available OPP which is *at least* the provided frequency. This function is useful while searching for a higher match OR operating on OPP information in the order of increasing frequency. - Example 1: To find the lowest opp for a device: + Example 1: To find the lowest opp for a device:: + freq = 0; opp = dev_pm_opp_find_freq_ceil(dev, &freq); dev_pm_opp_put(opp); - Example 2: A simplified implementation of a SoC cpufreq_driver->target: + + Example 2: A simplified implementation of a SoC cpufreq_driver->target:: + soc_cpufreq_target(..) { /* Do stuff like policy checks etc. */ @@ -184,12 +205,15 @@ fine grained dynamic control of which sets of OPPs are operationally available. These functions are intended to *temporarily* remove an OPP in conditions such as thermal considerations (e.g. don't use OPPx until the temperature drops). -WARNING: Do not use these functions in interrupt context. +WARNING: + Do not use these functions in interrupt context. -dev_pm_opp_enable - Make a OPP available for operation. +dev_pm_opp_enable + Make a OPP available for operation. Example: Lets say that 1GHz OPP is to be made available only if the SoC temperature is lower than a certain threshold. The SoC framework - implementation might choose to do something as follows: + implementation might choose to do something as follows:: + if (cur_temp < temp_low_thresh) { /* Enable 1GHz if it was disabled */ opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); @@ -201,10 +225,12 @@ dev_pm_opp_enable - Make a OPP available for operation. goto try_something_else; } -dev_pm_opp_disable - Make an OPP to be not available for operation +dev_pm_opp_disable + Make an OPP to be not available for operation Example: Lets say that 1GHz OPP is to be disabled if the temperature exceeds a threshold value. The SoC framework implementation might - choose to do something as follows: + choose to do something as follows:: + if (cur_temp > temp_high_thresh) { /* Disable 1GHz if it was enabled */ opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true); @@ -223,11 +249,13 @@ information from the OPP structure is necessary. Once an OPP pointer is retrieved using the search functions, the following functions can be used by SoC framework to retrieve the information represented inside the OPP layer. -dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer. +dev_pm_opp_get_voltage + Retrieve the voltage represented by the opp pointer. Example: At a cpufreq transition to a different frequency, SoC framework requires to set the voltage represented by the OPP using the regulator framework to the Power Management chip providing the - voltage. + voltage:: + soc_switch_to_freq_voltage(freq) { /* do things */ @@ -239,10 +267,12 @@ dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer. /* do other things */ } -dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer. +dev_pm_opp_get_freq + Retrieve the freq represented by the opp pointer. Example: Lets say the SoC framework uses a couple of helper functions we could pass opp pointers instead of doing additional parameters to - handle quiet a bit of data parameters. + handle quiet a bit of data parameters:: + soc_cpufreq_target(..) { /* do things.. */ @@ -264,9 +294,11 @@ dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer. /* do things.. */ } -dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device +dev_pm_opp_get_opp_count + Retrieve the number of available opps for a device Example: Lets say a co-processor in the SoC needs to know the available - frequencies in a table, the main processor can notify as following: + frequencies in a table, the main processor can notify as following:: + soc_notify_coproc_available_frequencies() { /* Do things */ @@ -289,54 +321,59 @@ dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device ================== Typically an SoC contains multiple voltage domains which are variable. Each domain is represented by a device pointer. The relationship to OPP can be -represented as follows: -SoC - |- device 1 - | |- opp 1 (availability, freq, voltage) - | |- opp 2 .. - ... ... - | `- opp n .. - |- device 2 - ... - `- device m +represented as follows:: + + SoC + |- device 1 + | |- opp 1 (availability, freq, voltage) + | |- opp 2 .. + ... ... + | `- opp n .. + |- device 2 + ... + `- device m OPP library maintains a internal list that the SoC framework populates and accessed by various functions as described above. However, the structures representing the actual OPPs and domains are internal to the OPP library itself to allow for suitable abstraction reusable across systems. -struct dev_pm_opp - The internal data structure of OPP library which is used to +struct dev_pm_opp + The internal data structure of OPP library which is used to represent an OPP. In addition to the freq, voltage, availability information, it also contains internal book keeping information required for the OPP library to operate on. Pointer to this structure is provided back to the users such as SoC framework to be used as a identifier for OPP in the interactions with OPP layer. - WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the - users. The defaults of for an instance is populated by dev_pm_opp_add, but the - availability of the OPP can be modified by dev_pm_opp_enable/disable functions. + WARNING: + The struct dev_pm_opp pointer should not be parsed or modified by the + users. The defaults of for an instance is populated by + dev_pm_opp_add, but the availability of the OPP can be modified + by dev_pm_opp_enable/disable functions. -struct device - This is used to identify a domain to the OPP layer. The +struct device + This is used to identify a domain to the OPP layer. The nature of the device and it's implementation is left to the user of OPP library such as the SoC framework. Overall, in a simplistic view, the data structure operations is represented as -following: +following:: -Initialization / modification: - +-----+ /- dev_pm_opp_enable -dev_pm_opp_add --> | opp | <------- - | +-----+ \- dev_pm_opp_disable - \-------> domain_info(device) + Initialization / modification: + +-----+ /- dev_pm_opp_enable + dev_pm_opp_add --> | opp | <------- + | +-----+ \- dev_pm_opp_disable + \-------> domain_info(device) -Search functions: - /-- dev_pm_opp_find_freq_ceil ---\ +-----+ -domain_info<---- dev_pm_opp_find_freq_exact -----> | opp | - \-- dev_pm_opp_find_freq_floor ---/ +-----+ + Search functions: + /-- dev_pm_opp_find_freq_ceil ---\ +-----+ + domain_info<---- dev_pm_opp_find_freq_exact -----> | opp | + \-- dev_pm_opp_find_freq_floor ---/ +-----+ -Retrieval functions: -+-----+ /- dev_pm_opp_get_voltage -| opp | <--- -+-----+ \- dev_pm_opp_get_freq + Retrieval functions: + +-----+ /- dev_pm_opp_get_voltage + | opp | <--- + +-----+ \- dev_pm_opp_get_freq -domain_info <- dev_pm_opp_get_opp_count + domain_info <- dev_pm_opp_get_opp_count diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.rst index 8eaf9ee24d43..0e2ef7429304 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.rst @@ -1,4 +1,6 @@ +==================== PCI Power Management +==================== Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. @@ -9,14 +11,14 @@ management. Based on previous work by Patrick Mochel <mochel@transmeta.com> This document only covers the aspects of power management specific to PCI devices. For general description of the kernel's interfaces related to device power management refer to Documentation/driver-api/pm/devices.rst and -Documentation/power/runtime_pm.txt. +Documentation/power/runtime_pm.rst. ---------------------------------------------------------------------------- +.. contents: -1. Hardware and Platform Support for PCI Power Management -2. PCI Subsystem and Device Power Management -3. PCI Device Drivers and Power Management -4. Resources + 1. Hardware and Platform Support for PCI Power Management + 2. PCI Subsystem and Device Power Management + 3. PCI Device Drivers and Power Management + 4. Resources 1. Hardware and Platform Support for PCI Power Management @@ -24,6 +26,7 @@ Documentation/power/runtime_pm.txt. 1.1. Native and Platform-Based Power Management ----------------------------------------------- + In general, power management is a feature allowing one to save energy by putting devices into states in which they draw less power (low-power states) at the price of reduced functionality or performance. @@ -67,6 +70,7 @@ mechanisms have to be used simultaneously to obtain the desired result. 1.2. Native PCI Power Management -------------------------------- + The PCI Bus Power Management Interface Specification (PCI PM Spec) was introduced between the PCI 2.1 and PCI 2.2 Specifications. It defined a standard interface for performing various operations related to power @@ -134,6 +138,7 @@ sufficiently active to generate a wakeup signal. 1.3. ACPI Device Power Management --------------------------------- + The platform firmware support for the power management of PCI devices is system-specific. However, if the system in question is compliant with the Advanced Configuration and Power Interface (ACPI) Specification, like the @@ -194,6 +199,7 @@ enabled for the device to be able to generate wakeup signals. 1.4. Wakeup Signaling --------------------- + Wakeup signals generated by PCI devices, either as native PCI PMEs, or as a result of the execution of the _DSW (or _PSW) ACPI control method before putting the device into a low-power state, have to be caught and handled as @@ -265,14 +271,15 @@ the native PCI Express PME signaling cannot be used by the kernel in that case. 2.1. Device Power Management Callbacks -------------------------------------- + The PCI Subsystem participates in the power management of PCI devices in a number of ways. First of all, it provides an intermediate code layer between the device power management core (PM core) and PCI device drivers. Specifically, the pm field of the PCI subsystem's struct bus_type object, pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing -pointers to several device power management callbacks: +pointers to several device power management callbacks:: -const struct dev_pm_ops pci_dev_pm_ops = { + const struct dev_pm_ops pci_dev_pm_ops = { .prepare = pci_pm_prepare, .complete = pci_pm_complete, .suspend = pci_pm_suspend, @@ -290,7 +297,7 @@ const struct dev_pm_ops pci_dev_pm_ops = { .runtime_suspend = pci_pm_runtime_suspend, .runtime_resume = pci_pm_runtime_resume, .runtime_idle = pci_pm_runtime_idle, -}; + }; These callbacks are executed by the PM core in various situations related to device power management and they, in turn, execute power management callbacks @@ -299,9 +306,9 @@ involving some standard configuration registers of PCI devices that device drivers need not know or care about. The structure representing a PCI device, struct pci_dev, contains several fields -that these callbacks operate on: +that these callbacks operate on:: -struct pci_dev { + struct pci_dev { ... pci_power_t current_state; /* Current operating state. */ int pm_cap; /* PM capability offset in the @@ -315,13 +322,14 @@ struct pci_dev { unsigned int wakeup_prepared:1; /* Device prepared for wake up */ unsigned int d3_delay; /* D3->D0 transition time in ms */ ... -}; + }; They also indirectly use some fields of the struct device that is embedded in struct pci_dev. 2.2. Device Initialization -------------------------- + The PCI subsystem's first task related to device power management is to prepare the device for power management and initialize the fields of struct pci_dev used for this purpose. This happens in two functions defined in @@ -348,10 +356,11 @@ during system-wide transitions to a sleep state and back to the working state. 2.3. Runtime Device Power Management ------------------------------------ + The PCI subsystem plays a vital role in the runtime power management of PCI devices. For this purpose it uses the general runtime power management -(runtime PM) framework described in Documentation/power/runtime_pm.txt. -Namely, it provides subsystem-level callbacks: +(runtime PM) framework described in Documentation/power/runtime_pm.rst. +Namely, it provides subsystem-level callbacks:: pci_pm_runtime_suspend() pci_pm_runtime_resume() @@ -425,13 +434,14 @@ to the given subsystem before the next phase begins. These phases always run after tasks have been frozen. 2.4.1. System Suspend +^^^^^^^^^^^^^^^^^^^^^ When the system is going into a sleep state in which the contents of memory will be preserved, such as one of the ACPI sleep states S1-S3, the phases are: prepare, suspend, suspend_noirq. -The following PCI bus type's callbacks, respectively, are used in these phases: +The following PCI bus type's callbacks, respectively, are used in these phases:: pci_pm_prepare() pci_pm_suspend() @@ -492,6 +502,7 @@ this purpose). PCI device drivers are not encouraged to do that, but in some rare cases doing that in the driver may be the optimum approach. 2.4.2. System Resume +^^^^^^^^^^^^^^^^^^^^ When the system is undergoing a transition from a sleep state in which the contents of memory have been preserved, such as one of the ACPI sleep states @@ -500,7 +511,7 @@ S1-S3, into the working state (ACPI S0), the phases are: resume_noirq, resume, complete. The following PCI bus type's callbacks, respectively, are executed in these -phases: +phases:: pci_pm_resume_noirq() pci_pm_resume() @@ -539,6 +550,7 @@ The pci_pm_complete() routine only executes the device driver's pm->complete() callback, if defined. 2.4.3. System Hibernation +^^^^^^^^^^^^^^^^^^^^^^^^^ System hibernation is more complicated than system suspend, because it requires a system image to be created and written into a persistent storage medium. The @@ -551,7 +563,7 @@ to be free) in the following three phases: prepare, freeze, freeze_noirq -that correspond to the PCI bus type's callbacks: +that correspond to the PCI bus type's callbacks:: pci_pm_prepare() pci_pm_freeze() @@ -580,7 +592,7 @@ back to the fully functional state and this is done in the following phases: thaw_noirq, thaw, complete -using the following PCI bus type's callbacks: +using the following PCI bus type's callbacks:: pci_pm_thaw_noirq() pci_pm_thaw() @@ -608,7 +620,7 @@ three phases: where the prepare phase is exactly the same as for system suspend. The other two phases are analogous to the suspend and suspend_noirq phases, respectively. -The PCI subsystem-level callbacks they correspond to +The PCI subsystem-level callbacks they correspond to:: pci_pm_poweroff() pci_pm_poweroff_noirq() @@ -618,6 +630,7 @@ although they don't attempt to save the device's standard configuration registers. 2.4.4. System Restore +^^^^^^^^^^^^^^^^^^^^^ System restore requires a hibernation image to be loaded into memory and the pre-hibernation memory contents to be restored before the pre-hibernation system @@ -653,7 +666,7 @@ phases: The first two of these are analogous to the resume_noirq and resume phases described above, respectively, and correspond to the following PCI subsystem -callbacks: +callbacks:: pci_pm_restore_noirq() pci_pm_restore() @@ -671,6 +684,7 @@ resume. 3.1. Power Management Callbacks ------------------------------- + PCI device drivers participate in power management by providing callbacks to be executed by the PCI subsystem's power management routines described above and by controlling the runtime power management of their devices. @@ -698,6 +712,7 @@ defined, though, they are expected to behave as described in the following subsections. 3.1.1. prepare() +^^^^^^^^^^^^^^^^ The prepare() callback is executed during system suspend, during hibernation (when a hibernation image is about to be created), during power-off after @@ -716,6 +731,7 @@ preallocated earlier, for example in a suspend/hibernate notifier as described in Documentation/driver-api/pm/notifiers.rst). 3.1.2. suspend() +^^^^^^^^^^^^^^^^ The suspend() callback is only executed during system suspend, after prepare() callbacks have been executed for all devices in the system. @@ -742,6 +758,7 @@ operations relying on the driver's ability to handle interrupts should be carried out in this callback. 3.1.3. suspend_noirq() +^^^^^^^^^^^^^^^^^^^^^^ The suspend_noirq() callback is only executed during system suspend, after suspend() callbacks have been executed for all devices in the system and @@ -753,6 +770,7 @@ suspend_noirq() can carry out operations that would cause race conditions to arise if they were performed in suspend(). 3.1.4. freeze() +^^^^^^^^^^^^^^^ The freeze() callback is hibernation-specific and is executed in two situations, during hibernation, after prepare() callbacks have been executed for all devices @@ -770,6 +788,7 @@ or put it into a low-power state. Still, either it or freeze_noirq() should save the device's standard configuration registers using pci_save_state(). 3.1.5. freeze_noirq() +^^^^^^^^^^^^^^^^^^^^^ The freeze_noirq() callback is hibernation-specific. It is executed during hibernation, after prepare() and freeze() callbacks have been executed for all @@ -786,6 +805,7 @@ The difference between freeze_noirq() and freeze() is analogous to the difference between suspend_noirq() and suspend(). 3.1.6. poweroff() +^^^^^^^^^^^^^^^^^ The poweroff() callback is hibernation-specific. It is executed when the system is about to be powered off after saving a hibernation image to a persistent @@ -802,6 +822,7 @@ into a low-power state, respectively, but it need not save the device's standard configuration registers. 3.1.7. poweroff_noirq() +^^^^^^^^^^^^^^^^^^^^^^^ The poweroff_noirq() callback is hibernation-specific. It is executed after poweroff() callbacks have been executed for all devices in the system. @@ -814,6 +835,7 @@ The difference between poweroff_noirq() and poweroff() is analogous to the difference between suspend_noirq() and suspend(). 3.1.8. resume_noirq() +^^^^^^^^^^^^^^^^^^^^^ The resume_noirq() callback is only executed during system resume, after the PM core has enabled the non-boot CPUs. The driver's interrupt handler will not @@ -827,6 +849,7 @@ it should only be used for performing operations that would lead to race conditions if carried out by resume(). 3.1.9. resume() +^^^^^^^^^^^^^^^ The resume() callback is only executed during system resume, after resume_noirq() callbacks have been executed for all devices in the system and @@ -837,6 +860,7 @@ device and bringing it back to the fully functional state. The device should be able to process I/O in a usual way after resume() has returned. 3.1.10. thaw_noirq() +^^^^^^^^^^^^^^^^^^^^ The thaw_noirq() callback is hibernation-specific. It is executed after a system image has been created and the non-boot CPUs have been enabled by the PM @@ -851,6 +875,7 @@ freeze() and freeze_noirq(), so in general it does not need to modify the contents of the device's registers. 3.1.11. thaw() +^^^^^^^^^^^^^^ The thaw() callback is hibernation-specific. It is executed after thaw_noirq() callbacks have been executed for all devices in the system and after device @@ -860,6 +885,7 @@ This callback is responsible for restoring the pre-freeze configuration of the device, so that it will work in a usual way after thaw() has returned. 3.1.12. restore_noirq() +^^^^^^^^^^^^^^^^^^^^^^^ The restore_noirq() callback is hibernation-specific. It is executed in the restore_noirq phase of hibernation, when the boot kernel has passed control to @@ -875,6 +901,7 @@ For the vast majority of PCI device drivers there is no difference between resume_noirq() and restore_noirq(). 3.1.13. restore() +^^^^^^^^^^^^^^^^^ The restore() callback is hibernation-specific. It is executed after restore_noirq() callbacks have been executed for all devices in the system and @@ -888,14 +915,17 @@ For the vast majority of PCI device drivers there is no difference between resume() and restore(). 3.1.14. complete() +^^^^^^^^^^^^^^^^^^ The complete() callback is executed in the following situations: + - during system resume, after resume() callbacks have been executed for all devices, - during hibernation, before saving the system image, after thaw() callbacks have been executed for all devices, - during system restore, when the system is going back to its pre-hibernation state, after restore() callbacks have been executed for all devices. + It also may be executed if the loading of a hibernation image into memory fails (in that case it is run after thaw() callbacks have been executed for all devices that have drivers in the boot kernel). @@ -904,6 +934,7 @@ This callback is entirely optional, although it may be necessary if the prepare() callback performs operations that need to be reversed. 3.1.15. runtime_suspend() +^^^^^^^^^^^^^^^^^^^^^^^^^ The runtime_suspend() callback is specific to device runtime power management (runtime PM). It is executed by the PM core's runtime PM framework when the @@ -915,6 +946,7 @@ put into a low-power state, but it must allow the PCI subsystem to perform all of the PCI-specific actions necessary for suspending the device. 3.1.16. runtime_resume() +^^^^^^^^^^^^^^^^^^^^^^^^ The runtime_resume() callback is specific to device runtime PM. It is executed by the PM core's runtime PM framework when the device is about to be resumed @@ -927,6 +959,7 @@ The device is expected to be able to process I/O in the usual way after runtime_resume() has returned. 3.1.17. runtime_idle() +^^^^^^^^^^^^^^^^^^^^^^ The runtime_idle() callback is specific to device runtime PM. It is executed by the PM core's runtime PM framework whenever it may be desirable to suspend @@ -939,6 +972,7 @@ PCI subsystem will call pm_runtime_suspend() for the device, which in turn will cause the driver's runtime_suspend() callback to be executed. 3.1.18. Pointing Multiple Callback Pointers to One Routine +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Although in principle each of the callbacks described in the previous subsections can be defined as a separate function, it often is convenient to @@ -962,6 +996,7 @@ dev_pm_ops to indicate that one suspend routine is to be pointed to by the be pointed to by the .resume(), .thaw(), and .restore() members. 3.1.19. Driver Flags for Power Management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The PM core allows device drivers to set flags that influence the handling of power management for the devices by the core itself and by middle layer code @@ -1007,6 +1042,7 @@ it. 3.2. Device Runtime Power Management ------------------------------------ + In addition to providing device power management callbacks PCI device drivers are responsible for controlling the runtime power management (runtime PM) of their devices. @@ -1073,22 +1109,27 @@ device the PM core automatically queues a request to check if the device is idle), device drivers are generally responsible for queuing power management requests for their devices. For this purpose they should use the runtime PM helper functions provided by the PM core, discussed in -Documentation/power/runtime_pm.txt. +Documentation/power/runtime_pm.rst. Devices can also be suspended and resumed synchronously, without placing a request into pm_wq. In the majority of cases this also is done by their drivers that use helper functions provided by the PM core for this purpose. For more information on the runtime PM of devices refer to -Documentation/power/runtime_pm.txt. +Documentation/power/runtime_pm.rst. 4. Resources ============ PCI Local Bus Specification, Rev. 3.0 + PCI Bus Power Management Interface Specification, Rev. 1.2 + Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b + PCI Express Base Specification, Rev. 2.0 + Documentation/driver-api/pm/devices.rst -Documentation/power/runtime_pm.txt + +Documentation/power/runtime_pm.rst diff --git a/Documentation/power/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.rst index 19c5f7b1a7ba..69921f072ce1 100644 --- a/Documentation/power/pm_qos_interface.txt +++ b/Documentation/power/pm_qos_interface.rst @@ -1,4 +1,6 @@ -PM Quality Of Service Interface. +=============================== +PM Quality Of Service Interface +=============================== This interface provides a kernel and user mode interface for registering performance expectations by drivers, subsystems and user space applications on @@ -11,6 +13,7 @@ memory_bandwidth. constraints and PM QoS flags. Each parameters have defined units: + * latency: usec * timeout: usec * throughput: kbs (kilo bit / sec) @@ -18,6 +21,7 @@ Each parameters have defined units: 1. PM QoS framework +=================== The infrastructure exposes multiple misc device nodes one per implemented parameter. The set of parameters implement is defined by pm_qos_power_init() @@ -37,38 +41,39 @@ reading the aggregated value does not require any locking mechanism. From kernel mode the use of this interface is simple: void pm_qos_add_request(handle, param_class, target_value): -Will insert an element into the list for that identified PM QoS class with the -target value. Upon change to this list the new target is recomputed and any -registered notifiers are called only if the target value is now different. -Clients of pm_qos need to save the returned handle for future use in other -pm_qos API functions. + Will insert an element into the list for that identified PM QoS class with the + target value. Upon change to this list the new target is recomputed and any + registered notifiers are called only if the target value is now different. + Clients of pm_qos need to save the returned handle for future use in other + pm_qos API functions. void pm_qos_update_request(handle, new_target_value): -Will update the list element pointed to by the handle with the new target value -and recompute the new aggregated target, calling the notification tree if the -target is changed. + Will update the list element pointed to by the handle with the new target value + and recompute the new aggregated target, calling the notification tree if the + target is changed. void pm_qos_remove_request(handle): -Will remove the element. After removal it will update the aggregate target and -call the notification tree if the target was changed as a result of removing -the request. + Will remove the element. After removal it will update the aggregate target and + call the notification tree if the target was changed as a result of removing + the request. int pm_qos_request(param_class): -Returns the aggregated value for a given PM QoS class. + Returns the aggregated value for a given PM QoS class. int pm_qos_request_active(handle): -Returns if the request is still active, i.e. it has not been removed from a -PM QoS class constraints list. + Returns if the request is still active, i.e. it has not been removed from a + PM QoS class constraints list. int pm_qos_add_notifier(param_class, notifier): -Adds a notification callback function to the PM QoS class. The callback is -called when the aggregated value for the PM QoS class is changed. + Adds a notification callback function to the PM QoS class. The callback is + called when the aggregated value for the PM QoS class is changed. int pm_qos_remove_notifier(int param_class, notifier): -Removes the notification callback function for the PM QoS class. + Removes the notification callback function for the PM QoS class. From user mode: + Only processes can register a pm_qos request. To provide for automatic cleanup of a process, the interface requires the process to register its parameter requests in the following way: @@ -89,6 +94,7 @@ node. 2. PM QoS per-device latency and flags framework +================================================ For each device, there are three lists of PM QoS requests. Two of them are maintained along with the aggregated targets of resume latency and active @@ -107,73 +113,82 @@ the aggregated value does not require any locking mechanism. From kernel mode the use of this interface is the following: int dev_pm_qos_add_request(device, handle, type, value): -Will insert an element into the list for that identified device with the -target value. Upon change to this list the new target is recomputed and any -registered notifiers are called only if the target value is now different. -Clients of dev_pm_qos need to save the handle for future use in other -dev_pm_qos API functions. + Will insert an element into the list for that identified device with the + target value. Upon change to this list the new target is recomputed and any + registered notifiers are called only if the target value is now different. + Clients of dev_pm_qos need to save the handle for future use in other + dev_pm_qos API functions. int dev_pm_qos_update_request(handle, new_value): -Will update the list element pointed to by the handle with the new target value -and recompute the new aggregated target, calling the notification trees if the -target is changed. + Will update the list element pointed to by the handle with the new target + value and recompute the new aggregated target, calling the notification + trees if the target is changed. int dev_pm_qos_remove_request(handle): -Will remove the element. After removal it will update the aggregate target and -call the notification trees if the target was changed as a result of removing -the request. + Will remove the element. After removal it will update the aggregate target + and call the notification trees if the target was changed as a result of + removing the request. -s32 dev_pm_qos_read_value(device): -Returns the aggregated value for a given device's constraints list. +s32 dev_pm_qos_read_value(device, type): + Returns the aggregated value for a given device's constraints list. enum pm_qos_flags_status dev_pm_qos_flags(device, mask) -Check PM QoS flags of the given device against the given mask of flags. -The meaning of the return values is as follows: - PM_QOS_FLAGS_ALL: All flags from the mask are set - PM_QOS_FLAGS_SOME: Some flags from the mask are set - PM_QOS_FLAGS_NONE: No flags from the mask are set - PM_QOS_FLAGS_UNDEFINED: The device's PM QoS structure has not been - initialized or the list of requests is empty. + Check PM QoS flags of the given device against the given mask of flags. + The meaning of the return values is as follows: + + PM_QOS_FLAGS_ALL: + All flags from the mask are set + PM_QOS_FLAGS_SOME: + Some flags from the mask are set + PM_QOS_FLAGS_NONE: + No flags from the mask are set + PM_QOS_FLAGS_UNDEFINED: + The device's PM QoS structure has not been initialized + or the list of requests is empty. int dev_pm_qos_add_ancestor_request(dev, handle, type, value) -Add a PM QoS request for the first direct ancestor of the given device whose -power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests) -or whose power.set_latency_tolerance callback pointer is not NULL (for -DEV_PM_QOS_LATENCY_TOLERANCE requests). + Add a PM QoS request for the first direct ancestor of the given device whose + power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests) + or whose power.set_latency_tolerance callback pointer is not NULL (for + DEV_PM_QOS_LATENCY_TOLERANCE requests). int dev_pm_qos_expose_latency_limit(device, value) -Add a request to the device's PM QoS list of resume latency constraints and -create a sysfs attribute pm_qos_resume_latency_us under the device's power -directory allowing user space to manipulate that request. + Add a request to the device's PM QoS list of resume latency constraints and + create a sysfs attribute pm_qos_resume_latency_us under the device's power + directory allowing user space to manipulate that request. void dev_pm_qos_hide_latency_limit(device) -Drop the request added by dev_pm_qos_expose_latency_limit() from the device's -PM QoS list of resume latency constraints and remove sysfs attribute -pm_qos_resume_latency_us from the device's power directory. + Drop the request added by dev_pm_qos_expose_latency_limit() from the device's + PM QoS list of resume latency constraints and remove sysfs attribute + pm_qos_resume_latency_us from the device's power directory. int dev_pm_qos_expose_flags(device, value) -Add a request to the device's PM QoS list of flags and create sysfs attribute -pm_qos_no_power_off under the device's power directory allowing user space to -change the value of the PM_QOS_FLAG_NO_POWER_OFF flag. + Add a request to the device's PM QoS list of flags and create sysfs attribute + pm_qos_no_power_off under the device's power directory allowing user space to + change the value of the PM_QOS_FLAG_NO_POWER_OFF flag. void dev_pm_qos_hide_flags(device) -Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list -of flags and remove sysfs attribute pm_qos_no_power_off from the device's power -directory. + Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list + of flags and remove sysfs attribute pm_qos_no_power_off from the device's power + directory. Notification mechanisms: + The per-device PM QoS framework has a per-device notification tree. -int dev_pm_qos_add_notifier(device, notifier): -Adds a notification callback function for the device. -The callback is called when the aggregated value of the device constraints list -is changed (for resume latency device PM QoS only). +int dev_pm_qos_add_notifier(device, notifier, type): + Adds a notification callback function for the device for a particular request + type. + + The callback is called when the aggregated value of the device constraints list + is changed. -int dev_pm_qos_remove_notifier(device, notifier): -Removes the notification callback function for the device. +int dev_pm_qos_remove_notifier(device, notifier, type): + Removes the notification callback function for the device. Active state latency tolerance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This device PM QoS type is used to support systems in which hardware may switch to energy-saving operation modes on the fly. In those systems, if the operation diff --git a/Documentation/power/power_supply_class.rst b/Documentation/power/power_supply_class.rst new file mode 100644 index 000000000000..7b8c42f8b1de --- /dev/null +++ b/Documentation/power/power_supply_class.rst @@ -0,0 +1,288 @@ +======================== +Linux power supply class +======================== + +Synopsis +~~~~~~~~ +Power supply class used to represent battery, UPS, AC or DC power supply +properties to user-space. + +It defines core set of attributes, which should be applicable to (almost) +every power supply out there. Attributes are available via sysfs and uevent +interfaces. + +Each attribute has well defined meaning, up to unit of measure used. While +the attributes provided are believed to be universally applicable to any +power supply, specific monitoring hardware may not be able to provide them +all, so any of them may be skipped. + +Power supply class is extensible, and allows to define drivers own attributes. +The core attribute set is subject to the standard Linux evolution (i.e. +if it will be found that some attribute is applicable to many power supply +types or their drivers, it can be added to the core set). + +It also integrates with LED framework, for the purpose of providing +typically expected feedback of battery charging/fully charged status and +AC/USB power supply online status. (Note that specific details of the +indication (including whether to use it at all) are fully controllable by +user and/or specific machine defaults, per design principles of LED +framework). + + +Attributes/properties +~~~~~~~~~~~~~~~~~~~~~ +Power supply class has predefined set of attributes, this eliminates code +duplication across drivers. Power supply class insist on reusing its +predefined attributes *and* their units. + +So, userspace gets predictable set of attributes and their units for any +kind of power supply, and can process/present them to a user in consistent +manner. Results for different power supplies and machines are also directly +comparable. + +See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c +for the example how to declare and handle attributes. + + +Units +~~~~~ +Quoting include/linux/power_supply.h: + + All voltages, currents, charges, energies, time and temperatures in µV, + µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise + stated. It's driver's job to convert its raw values to units in which + this class operates. + + +Attributes/properties detailed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++--------------------------------------------------------------------------+ +| **Charge/Energy/Capacity - how to not confuse** | ++--------------------------------------------------------------------------+ +| **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" | +| of battery, this class distinguish these terms. Don't mix them!** | +| | +| - `CHARGE_*` | +| attributes represents capacity in µAh only. | +| - `ENERGY_*` | +| attributes represents capacity in µWh only. | +| - `CAPACITY` | +| attribute represents capacity in *percents*, from 0 to 100. | ++--------------------------------------------------------------------------+ + +Postfixes: + +_AVG + *hardware* averaged value, use it if your hardware is really able to + report averaged values. +_NOW + momentary/instantaneous values. + +STATUS + this attribute represents operating status (charging, full, + discharging (i.e. powering a load), etc.). This corresponds to + `BATTERY_STATUS_*` values, as defined in battery.h. + +CHARGE_TYPE + batteries can typically charge at different rates. + This defines trickle and fast charges. For batteries that + are already charged or discharging, 'n/a' can be displayed (or + 'unknown', if the status is not known). + +AUTHENTIC + indicates the power supply (battery or charger) connected + to the platform is authentic(1) or non authentic(0). + +HEALTH + represents health of the battery, values corresponds to + POWER_SUPPLY_HEALTH_*, defined in battery.h. + +VOLTAGE_OCV + open circuit voltage of the battery. + +VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN + design values for maximal and minimal power supply voltages. + Maximal/minimal means values of voltages when battery considered + "full"/"empty" at normal conditions. Yes, there is no direct relation + between voltage and battery capacity, but some dumb + batteries use voltage for very approximated calculation of capacity. + Battery driver also can use this attribute just to inform userspace + about maximal and minimal voltage thresholds of a given battery. + +VOLTAGE_MAX, VOLTAGE_MIN + same as _DESIGN voltage values except that these ones should be used + if hardware could only guess (measure and retain) the thresholds of a + given power supply. + +VOLTAGE_BOOT + Reports the voltage measured during boot + +CURRENT_BOOT + Reports the current measured during boot + +CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN + design charge values, when battery considered full/empty. + +ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN + same as above but for energy. + +CHARGE_FULL, CHARGE_EMPTY + These attributes means "last remembered value of charge when battery + became full/empty". It also could mean "value of charge when battery + considered full/empty at given conditions (temperature, age)". + I.e. these attributes represents real thresholds, not design values. + +ENERGY_FULL, ENERGY_EMPTY + same as above but for energy. + +CHARGE_COUNTER + the current charge counter (in µAh). This could easily + be negative; there is no empty or full value. It is only useful for + relative, time-based measurements. + +PRECHARGE_CURRENT + the maximum charge current during precharge phase of charge cycle + (typically 20% of battery capacity). + +CHARGE_TERM_CURRENT + Charge termination current. The charge cycle terminates when battery + voltage is above recharge threshold, and charge current is below + this setting (typically 10% of battery capacity). + +CONSTANT_CHARGE_CURRENT + constant charge current programmed by charger. + + +CONSTANT_CHARGE_CURRENT_MAX + maximum charge current supported by the power supply object. + +CONSTANT_CHARGE_VOLTAGE + constant charge voltage programmed by charger. +CONSTANT_CHARGE_VOLTAGE_MAX + maximum charge voltage supported by the power supply object. + +INPUT_CURRENT_LIMIT + input current limit programmed by charger. Indicates + the current drawn from a charging source. +INPUT_VOLTAGE_LIMIT + input voltage limit programmed by charger. Indicates + the voltage limit from a charging source. +INPUT_POWER_LIMIT + input power limit programmed by charger. Indicates + the power limit from a charging source. + +CHARGE_CONTROL_LIMIT + current charge control limit setting +CHARGE_CONTROL_LIMIT_MAX + maximum charge control limit setting + +CALIBRATE + battery or coulomb counter calibration status + +CAPACITY + capacity in percents. +CAPACITY_ALERT_MIN + minimum capacity alert value in percents. +CAPACITY_ALERT_MAX + maximum capacity alert value in percents. +CAPACITY_LEVEL + capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*. + +TEMP + temperature of the power supply. +TEMP_ALERT_MIN + minimum battery temperature alert. +TEMP_ALERT_MAX + maximum battery temperature alert. +TEMP_AMBIENT + ambient temperature. +TEMP_AMBIENT_ALERT_MIN + minimum ambient temperature alert. +TEMP_AMBIENT_ALERT_MAX + maximum ambient temperature alert. +TEMP_MIN + minimum operatable temperature +TEMP_MAX + maximum operatable temperature + +TIME_TO_EMPTY + seconds left for battery to be considered empty + (i.e. while battery powers a load) +TIME_TO_FULL + seconds left for battery to be considered full + (i.e. while battery is charging) + + +Battery <-> external power supply interaction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Often power supplies are acting as supplies and supplicants at the same +time. Batteries are good example. So, batteries usually care if they're +externally powered or not. + +For that case, power supply class implements notification mechanism for +batteries. + +External power supply (AC) lists supplicants (batteries) names in +"supplied_to" struct member, and each power_supply_changed() call +issued by external power supply will notify supplicants via +external_power_changed callback. + + +Devicetree battery characteristics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Drivers should call power_supply_get_battery_info() to obtain battery +characteristics from a devicetree battery node, defined in +Documentation/devicetree/bindings/power/supply/battery.txt. This is +implemented in drivers/power/supply/bq27xxx_battery.c. + +Properties in struct power_supply_battery_info and their counterparts in the +battery node have names corresponding to elements in enum power_supply_property, +for naming consistency between sysfs attributes and battery node properties. + + +QA +~~ + +Q: + Where is POWER_SUPPLY_PROP_XYZ attribute? +A: + If you cannot find attribute suitable for your driver needs, feel free + to add it and send patch along with your driver. + + The attributes available currently are the ones currently provided by the + drivers written. + + Good candidates to add in future: model/part#, cycle_time, manufacturer, + etc. + + +Q: + I have some very specific attribute (e.g. battery color), should I add + this attribute to standard ones? +A: + Most likely, no. Such attribute can be placed in the driver itself, if + it is useful. Of course, if the attribute in question applicable to + large set of batteries, provided by many drivers, and/or comes from + some general battery specification/standard, it may be a candidate to + be added to the core attribute set. + + +Q: + Suppose, my battery monitoring chip/firmware does not provides capacity + in percents, but provides charge_{now,full,empty}. Should I calculate + percentage capacity manually, inside the driver, and register CAPACITY + attribute? The same question about time_to_empty/time_to_full. +A: + Most likely, no. This class is designed to export properties which are + directly measurable by the specific hardware available. + + Inferring not available properties using some heuristics or mathematical + model is not subject of work for a battery driver. Such functionality + should be factored out, and in fact, apm_power, the driver to serve + legacy APM API on top of power supply class, uses a simple heuristic of + approximating remaining battery capacity based on its charge, current, + voltage and so on. But full-fledged battery model is likely not subject + for kernel at all, as it would require floating point calculation to deal + with things like differential equations and Kalman filters. This is + better be handled by batteryd/libbattery, yet to be written. diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt deleted file mode 100644 index 300d37896e51..000000000000 --- a/Documentation/power/power_supply_class.txt +++ /dev/null @@ -1,231 +0,0 @@ -Linux power supply class -======================== - -Synopsis -~~~~~~~~ -Power supply class used to represent battery, UPS, AC or DC power supply -properties to user-space. - -It defines core set of attributes, which should be applicable to (almost) -every power supply out there. Attributes are available via sysfs and uevent -interfaces. - -Each attribute has well defined meaning, up to unit of measure used. While -the attributes provided are believed to be universally applicable to any -power supply, specific monitoring hardware may not be able to provide them -all, so any of them may be skipped. - -Power supply class is extensible, and allows to define drivers own attributes. -The core attribute set is subject to the standard Linux evolution (i.e. -if it will be found that some attribute is applicable to many power supply -types or their drivers, it can be added to the core set). - -It also integrates with LED framework, for the purpose of providing -typically expected feedback of battery charging/fully charged status and -AC/USB power supply online status. (Note that specific details of the -indication (including whether to use it at all) are fully controllable by -user and/or specific machine defaults, per design principles of LED -framework). - - -Attributes/properties -~~~~~~~~~~~~~~~~~~~~~ -Power supply class has predefined set of attributes, this eliminates code -duplication across drivers. Power supply class insist on reusing its -predefined attributes *and* their units. - -So, userspace gets predictable set of attributes and their units for any -kind of power supply, and can process/present them to a user in consistent -manner. Results for different power supplies and machines are also directly -comparable. - -See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c -for the example how to declare and handle attributes. - - -Units -~~~~~ -Quoting include/linux/power_supply.h: - - All voltages, currents, charges, energies, time and temperatures in µV, - µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise - stated. It's driver's job to convert its raw values to units in which - this class operates. - - -Attributes/properties detailed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -~ ~ ~ ~ ~ ~ ~ Charge/Energy/Capacity - how to not confuse ~ ~ ~ ~ ~ ~ ~ -~ ~ -~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity" ~ -~ of battery, this class distinguish these terms. Don't mix them! ~ -~ ~ -~ CHARGE_* attributes represents capacity in µAh only. ~ -~ ENERGY_* attributes represents capacity in µWh only. ~ -~ CAPACITY attribute represents capacity in *percents*, from 0 to 100. ~ -~ ~ -~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ - -Postfixes: -_AVG - *hardware* averaged value, use it if your hardware is really able to -report averaged values. -_NOW - momentary/instantaneous values. - -STATUS - this attribute represents operating status (charging, full, -discharging (i.e. powering a load), etc.). This corresponds to -BATTERY_STATUS_* values, as defined in battery.h. - -CHARGE_TYPE - batteries can typically charge at different rates. -This defines trickle and fast charges. For batteries that -are already charged or discharging, 'n/a' can be displayed (or -'unknown', if the status is not known). - -AUTHENTIC - indicates the power supply (battery or charger) connected -to the platform is authentic(1) or non authentic(0). - -HEALTH - represents health of the battery, values corresponds to -POWER_SUPPLY_HEALTH_*, defined in battery.h. - -VOLTAGE_OCV - open circuit voltage of the battery. - -VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and -minimal power supply voltages. Maximal/minimal means values of voltages -when battery considered "full"/"empty" at normal conditions. Yes, there is -no direct relation between voltage and battery capacity, but some dumb -batteries use voltage for very approximated calculation of capacity. -Battery driver also can use this attribute just to inform userspace -about maximal and minimal voltage thresholds of a given battery. - -VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that -these ones should be used if hardware could only guess (measure and -retain) the thresholds of a given power supply. - -VOLTAGE_BOOT - Reports the voltage measured during boot - -CURRENT_BOOT - Reports the current measured during boot - -CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when -battery considered full/empty. - -ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy. - -CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value -of charge when battery became full/empty". It also could mean "value of -charge when battery considered full/empty at given conditions (temperature, -age)". I.e. these attributes represents real thresholds, not design values. - -ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. - -CHARGE_COUNTER - the current charge counter (in µAh). This could easily -be negative; there is no empty or full value. It is only useful for -relative, time-based measurements. - -PRECHARGE_CURRENT - the maximum charge current during precharge phase -of charge cycle (typically 20% of battery capacity). -CHARGE_TERM_CURRENT - Charge termination current. The charge cycle -terminates when battery voltage is above recharge threshold, and charge -current is below this setting (typically 10% of battery capacity). - -CONSTANT_CHARGE_CURRENT - constant charge current programmed by charger. -CONSTANT_CHARGE_CURRENT_MAX - maximum charge current supported by the -power supply object. - -CONSTANT_CHARGE_VOLTAGE - constant charge voltage programmed by charger. -CONSTANT_CHARGE_VOLTAGE_MAX - maximum charge voltage supported by the -power supply object. - -INPUT_CURRENT_LIMIT - input current limit programmed by charger. Indicates -the current drawn from a charging source. - -CHARGE_CONTROL_LIMIT - current charge control limit setting -CHARGE_CONTROL_LIMIT_MAX - maximum charge control limit setting - -CALIBRATE - battery or coulomb counter calibration status - -CAPACITY - capacity in percents. -CAPACITY_ALERT_MIN - minimum capacity alert value in percents. -CAPACITY_ALERT_MAX - maximum capacity alert value in percents. -CAPACITY_LEVEL - capacity level. This corresponds to -POWER_SUPPLY_CAPACITY_LEVEL_*. - -TEMP - temperature of the power supply. -TEMP_ALERT_MIN - minimum battery temperature alert. -TEMP_ALERT_MAX - maximum battery temperature alert. -TEMP_AMBIENT - ambient temperature. -TEMP_AMBIENT_ALERT_MIN - minimum ambient temperature alert. -TEMP_AMBIENT_ALERT_MAX - maximum ambient temperature alert. -TEMP_MIN - minimum operatable temperature -TEMP_MAX - maximum operatable temperature - -TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e. -while battery powers a load) -TIME_TO_FULL - seconds left for battery to be considered full (i.e. -while battery is charging) - - -Battery <-> external power supply interaction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Often power supplies are acting as supplies and supplicants at the same -time. Batteries are good example. So, batteries usually care if they're -externally powered or not. - -For that case, power supply class implements notification mechanism for -batteries. - -External power supply (AC) lists supplicants (batteries) names in -"supplied_to" struct member, and each power_supply_changed() call -issued by external power supply will notify supplicants via -external_power_changed callback. - - -Devicetree battery characteristics -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Drivers should call power_supply_get_battery_info() to obtain battery -characteristics from a devicetree battery node, defined in -Documentation/devicetree/bindings/power/supply/battery.txt. This is -implemented in drivers/power/supply/bq27xxx_battery.c. - -Properties in struct power_supply_battery_info and their counterparts in the -battery node have names corresponding to elements in enum power_supply_property, -for naming consistency between sysfs attributes and battery node properties. - - -QA -~~ -Q: Where is POWER_SUPPLY_PROP_XYZ attribute? -A: If you cannot find attribute suitable for your driver needs, feel free - to add it and send patch along with your driver. - - The attributes available currently are the ones currently provided by the - drivers written. - - Good candidates to add in future: model/part#, cycle_time, manufacturer, - etc. - - -Q: I have some very specific attribute (e.g. battery color), should I add - this attribute to standard ones? -A: Most likely, no. Such attribute can be placed in the driver itself, if - it is useful. Of course, if the attribute in question applicable to - large set of batteries, provided by many drivers, and/or comes from - some general battery specification/standard, it may be a candidate to - be added to the core attribute set. - - -Q: Suppose, my battery monitoring chip/firmware does not provides capacity - in percents, but provides charge_{now,full,empty}. Should I calculate - percentage capacity manually, inside the driver, and register CAPACITY - attribute? The same question about time_to_empty/time_to_full. -A: Most likely, no. This class is designed to export properties which are - directly measurable by the specific hardware available. - - Inferring not available properties using some heuristics or mathematical - model is not subject of work for a battery driver. Such functionality - should be factored out, and in fact, apm_power, the driver to serve - legacy APM API on top of power supply class, uses a simple heuristic of - approximating remaining battery capacity based on its charge, current, - voltage and so on. But full-fledged battery model is likely not subject - for kernel at all, as it would require floating point calculation to deal - with things like differential equations and Kalman filters. This is - better be handled by batteryd/libbattery, yet to be written. diff --git a/Documentation/power/powercap/powercap.rst b/Documentation/power/powercap/powercap.rst new file mode 100644 index 000000000000..7ae3b44c7624 --- /dev/null +++ b/Documentation/power/powercap/powercap.rst @@ -0,0 +1,257 @@ +======================= +Power Capping Framework +======================= + +The power capping framework provides a consistent interface between the kernel +and the user space that allows power capping drivers to expose the settings to +user space in a uniform way. + +Terminology +=========== + +The framework exposes power capping devices to user space via sysfs in the +form of a tree of objects. The objects at the root level of the tree represent +'control types', which correspond to different methods of power capping. For +example, the intel-rapl control type represents the Intel "Running Average +Power Limit" (RAPL) technology, whereas the 'idle-injection' control type +corresponds to the use of idle injection for controlling power. + +Power zones represent different parts of the system, which can be controlled and +monitored using the power capping method determined by the control type the +given zone belongs to. They each contain attributes for monitoring power, as +well as controls represented in the form of power constraints. If the parts of +the system represented by different power zones are hierarchical (that is, one +bigger part consists of multiple smaller parts that each have their own power +controls), those power zones may also be organized in a hierarchy with one +parent power zone containing multiple subzones and so on to reflect the power +control topology of the system. In that case, it is possible to apply power +capping to a set of devices together using the parent power zone and if more +fine grained control is required, it can be applied through the subzones. + + +Example sysfs interface tree:: + + /sys/devices/virtual/powercap + └──intel-rapl + ├──intel-rapl:0 + │  ├──constraint_0_name + │  ├──constraint_0_power_limit_uw + │  ├──constraint_0_time_window_us + │  ├──constraint_1_name + │  ├──constraint_1_power_limit_uw + │  ├──constraint_1_time_window_us + │  ├──device -> ../../intel-rapl + │  ├──energy_uj + │  ├──intel-rapl:0:0 + │  │  ├──constraint_0_name + │  │  ├──constraint_0_power_limit_uw + │  │  ├──constraint_0_time_window_us + │  │  ├──constraint_1_name + │  │  ├──constraint_1_power_limit_uw + │  │  ├──constraint_1_time_window_us + │  │  ├──device -> ../../intel-rapl:0 + │  │  ├──energy_uj + │  │  ├──max_energy_range_uj + │  │  ├──name + │  │  ├──enabled + │  │  ├──power + │  │  │  ├──async + │  │  │  [] + │  │  ├──subsystem -> ../../../../../../class/power_cap + │  │  └──uevent + │  ├──intel-rapl:0:1 + │  │  ├──constraint_0_name + │  │  ├──constraint_0_power_limit_uw + │  │  ├──constraint_0_time_window_us + │  │  ├──constraint_1_name + │  │  ├──constraint_1_power_limit_uw + │  │  ├──constraint_1_time_window_us + │  │  ├──device -> ../../intel-rapl:0 + │  │  ├──energy_uj + │  │  ├──max_energy_range_uj + │  │  ├──name + │  │  ├──enabled + │  │  ├──power + │  │  │  ├──async + │  │  │  [] + │  │  ├──subsystem -> ../../../../../../class/power_cap + │  │  └──uevent + │  ├──max_energy_range_uj + │  ├──max_power_range_uw + │  ├──name + │  ├──enabled + │  ├──power + │  │  ├──async + │  │  [] + │  ├──subsystem -> ../../../../../class/power_cap + │  ├──enabled + │  ├──uevent + ├──intel-rapl:1 + │  ├──constraint_0_name + │  ├──constraint_0_power_limit_uw + │  ├──constraint_0_time_window_us + │  ├──constraint_1_name + │  ├──constraint_1_power_limit_uw + │  ├──constraint_1_time_window_us + │  ├──device -> ../../intel-rapl + │  ├──energy_uj + │  ├──intel-rapl:1:0 + │  │  ├──constraint_0_name + │  │  ├──constraint_0_power_limit_uw + │  │  ├──constraint_0_time_window_us + │  │  ├──constraint_1_name + │  │  ├──constraint_1_power_limit_uw + │  │  ├──constraint_1_time_window_us + │  │  ├──device -> ../../intel-rapl:1 + │  │  ├──energy_uj + │  │  ├──max_energy_range_uj + │  │  ├──name + │  │  ├──enabled + │  │  ├──power + │  │  │  ├──async + │  │  │  [] + │  │  ├──subsystem -> ../../../../../../class/power_cap + │  │  └──uevent + │  ├──intel-rapl:1:1 + │  │  ├──constraint_0_name + │  │  ├──constraint_0_power_limit_uw + │  │  ├──constraint_0_time_window_us + │  │  ├──constraint_1_name + │  │  ├──constraint_1_power_limit_uw + │  │  ├──constraint_1_time_window_us + │  │  ├──device -> ../../intel-rapl:1 + │  │  ├──energy_uj + │  │  ├──max_energy_range_uj + │  │  ├──name + │  │  ├──enabled + │  │  ├──power + │  │  │  ├──async + │  │  │  [] + │  │  ├──subsystem -> ../../../../../../class/power_cap + │  │  └──uevent + │  ├──max_energy_range_uj + │  ├──max_power_range_uw + │  ├──name + │  ├──enabled + │  ├──power + │  │  ├──async + │  │  [] + │  ├──subsystem -> ../../../../../class/power_cap + │  ├──uevent + ├──power + │  ├──async + │  [] + ├──subsystem -> ../../../../class/power_cap + ├──enabled + └──uevent + +The above example illustrates a case in which the Intel RAPL technology, +available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one +control type called intel-rapl which contains two power zones, intel-rapl:0 and +intel-rapl:1, representing CPU packages. Each of these power zones contains +two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the +"core" and the "uncore" parts of the given CPU package, respectively. All of +the zones and subzones contain energy monitoring attributes (energy_uj, +max_energy_range_uj) and constraint attributes (constraint_*) allowing controls +to be applied (the constraints in the 'package' power zones apply to the whole +CPU packages and the subzone constraints only apply to the respective parts of +the given package individually). Since Intel RAPL doesn't provide instantaneous +power value, there is no power_uw attribute. + +In addition to that, each power zone contains a name attribute, allowing the +part of the system represented by that zone to be identified. +For example:: + + cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name + +package-0 +--------- + +The Intel RAPL technology allows two constraints, short term and long term, +with two different time windows to be applied to each power zone. Thus for +each zone there are 2 attributes representing the constraint names, 2 power +limits and 2 attributes representing the sizes of the time windows. Such that, +constraint_j_* attributes correspond to the jth constraint (j = 0,1). + +For example:: + + constraint_0_name + constraint_0_power_limit_uw + constraint_0_time_window_us + constraint_1_name + constraint_1_power_limit_uw + constraint_1_time_window_us + +Power Zone Attributes +===================== + +Monitoring attributes +--------------------- + +energy_uj (rw) + Current energy counter in micro joules. Write "0" to reset. + If the counter can not be reset, then this attribute is read only. + +max_energy_range_uj (ro) + Range of the above energy counter in micro-joules. + +power_uw (ro) + Current power in micro watts. + +max_power_range_uw (ro) + Range of the above power value in micro-watts. + +name (ro) + Name of this power zone. + +It is possible that some domains have both power ranges and energy counter ranges; +however, only one is mandatory. + +Constraints +----------- + +constraint_X_power_limit_uw (rw) + Power limit in micro watts, which should be applicable for the + time window specified by "constraint_X_time_window_us". + +constraint_X_time_window_us (rw) + Time window in micro seconds. + +constraint_X_name (ro) + An optional name of the constraint + +constraint_X_max_power_uw(ro) + Maximum allowed power in micro watts. + +constraint_X_min_power_uw(ro) + Minimum allowed power in micro watts. + +constraint_X_max_time_window_us(ro) + Maximum allowed time window in micro seconds. + +constraint_X_min_time_window_us(ro) + Minimum allowed time window in micro seconds. + +Except power_limit_uw and time_window_us other fields are optional. + +Common zone and control type attributes +--------------------------------------- + +enabled (rw): Enable/Disable controls at zone level or for all zones using +a control type. + +Power Cap Client Driver Interface +================================= + +The API summary: + +Call powercap_register_control_type() to register control type object. +Call powercap_register_zone() to register a power zone (under a given +control type), either as a top-level power zone or as a subzone of another +power zone registered earlier. +The number of constraints in a power zone and the corresponding callbacks have +to be defined prior to calling powercap_register_zone() to register that zone. + +To Free a power zone call powercap_unregister_zone(). +To free a control type object call powercap_unregister_control_type(). +Detailed API can be generated using kernel-doc on include/linux/powercap.h. diff --git a/Documentation/power/powercap/powercap.txt b/Documentation/power/powercap/powercap.txt deleted file mode 100644 index 1e6ef164e07a..000000000000 --- a/Documentation/power/powercap/powercap.txt +++ /dev/null @@ -1,236 +0,0 @@ -Power Capping Framework -================================== - -The power capping framework provides a consistent interface between the kernel -and the user space that allows power capping drivers to expose the settings to -user space in a uniform way. - -Terminology -========================= -The framework exposes power capping devices to user space via sysfs in the -form of a tree of objects. The objects at the root level of the tree represent -'control types', which correspond to different methods of power capping. For -example, the intel-rapl control type represents the Intel "Running Average -Power Limit" (RAPL) technology, whereas the 'idle-injection' control type -corresponds to the use of idle injection for controlling power. - -Power zones represent different parts of the system, which can be controlled and -monitored using the power capping method determined by the control type the -given zone belongs to. They each contain attributes for monitoring power, as -well as controls represented in the form of power constraints. If the parts of -the system represented by different power zones are hierarchical (that is, one -bigger part consists of multiple smaller parts that each have their own power -controls), those power zones may also be organized in a hierarchy with one -parent power zone containing multiple subzones and so on to reflect the power -control topology of the system. In that case, it is possible to apply power -capping to a set of devices together using the parent power zone and if more -fine grained control is required, it can be applied through the subzones. - - -Example sysfs interface tree: - -/sys/devices/virtual/powercap -??? intel-rapl - ??? intel-rapl:0 - ?  ??? constraint_0_name - ?  ??? constraint_0_power_limit_uw - ?  ??? constraint_0_time_window_us - ?  ??? constraint_1_name - ?  ??? constraint_1_power_limit_uw - ?  ??? constraint_1_time_window_us - ?  ??? device -> ../../intel-rapl - ?  ??? energy_uj - ?  ??? intel-rapl:0:0 - ?  ?  ??? constraint_0_name - ?  ?  ??? constraint_0_power_limit_uw - ?  ?  ??? constraint_0_time_window_us - ?  ?  ??? constraint_1_name - ?  ?  ??? constraint_1_power_limit_uw - ?  ?  ??? constraint_1_time_window_us - ?  ?  ??? device -> ../../intel-rapl:0 - ?  ?  ??? energy_uj - ?  ?  ??? max_energy_range_uj - ?  ?  ??? name - ?  ?  ??? enabled - ?  ?  ??? power - ?  ?  ?  ??? async - ?  ?  ?  [] - ?  ?  ??? subsystem -> ../../../../../../class/power_cap - ?  ?  ??? uevent - ?  ??? intel-rapl:0:1 - ?  ?  ??? constraint_0_name - ?  ?  ??? constraint_0_power_limit_uw - ?  ?  ??? constraint_0_time_window_us - ?  ?  ??? constraint_1_name - ?  ?  ??? constraint_1_power_limit_uw - ?  ?  ??? constraint_1_time_window_us - ?  ?  ??? device -> ../../intel-rapl:0 - ?  ?  ??? energy_uj - ?  ?  ??? max_energy_range_uj - ?  ?  ??? name - ?  ?  ??? enabled - ?  ?  ??? power - ?  ?  ?  ??? async - ?  ?  ?  [] - ?  ?  ??? subsystem -> ../../../../../../class/power_cap - ?  ?  ??? uevent - ?  ??? max_energy_range_uj - ?  ??? max_power_range_uw - ?  ??? name - ?  ??? enabled - ?  ??? power - ?  ?  ??? async - ?  ?  [] - ?  ??? subsystem -> ../../../../../class/power_cap - ?  ??? enabled - ?  ??? uevent - ??? intel-rapl:1 - ?  ??? constraint_0_name - ?  ??? constraint_0_power_limit_uw - ?  ??? constraint_0_time_window_us - ?  ??? constraint_1_name - ?  ??? constraint_1_power_limit_uw - ?  ??? constraint_1_time_window_us - ?  ??? device -> ../../intel-rapl - ?  ??? energy_uj - ?  ??? intel-rapl:1:0 - ?  ?  ??? constraint_0_name - ?  ?  ??? constraint_0_power_limit_uw - ?  ?  ??? constraint_0_time_window_us - ?  ?  ??? constraint_1_name - ?  ?  ??? constraint_1_power_limit_uw - ?  ?  ??? constraint_1_time_window_us - ?  ?  ??? device -> ../../intel-rapl:1 - ?  ?  ??? energy_uj - ?  ?  ??? max_energy_range_uj - ?  ?  ??? name - ?  ?  ??? enabled - ?  ?  ??? power - ?  ?  ?  ??? async - ?  ?  ?  [] - ?  ?  ??? subsystem -> ../../../../../../class/power_cap - ?  ?  ??? uevent - ?  ??? intel-rapl:1:1 - ?  ?  ??? constraint_0_name - ?  ?  ??? constraint_0_power_limit_uw - ?  ?  ??? constraint_0_time_window_us - ?  ?  ??? constraint_1_name - ?  ?  ??? constraint_1_power_limit_uw - ?  ?  ??? constraint_1_time_window_us - ?  ?  ??? device -> ../../intel-rapl:1 - ?  ?  ??? energy_uj - ?  ?  ??? max_energy_range_uj - ?  ?  ??? name - ?  ?  ??? enabled - ?  ?  ??? power - ?  ?  ?  ??? async - ?  ?  ?  [] - ?  ?  ??? subsystem -> ../../../../../../class/power_cap - ?  ?  ??? uevent - ?  ??? max_energy_range_uj - ?  ??? max_power_range_uw - ?  ??? name - ?  ??? enabled - ?  ??? power - ?  ?  ??? async - ?  ?  [] - ?  ??? subsystem -> ../../../../../class/power_cap - ?  ??? uevent - ??? power - ?  ??? async - ?  [] - ??? subsystem -> ../../../../class/power_cap - ??? enabled - ??? uevent - -The above example illustrates a case in which the Intel RAPL technology, -available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one -control type called intel-rapl which contains two power zones, intel-rapl:0 and -intel-rapl:1, representing CPU packages. Each of these power zones contains -two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the -"core" and the "uncore" parts of the given CPU package, respectively. All of -the zones and subzones contain energy monitoring attributes (energy_uj, -max_energy_range_uj) and constraint attributes (constraint_*) allowing controls -to be applied (the constraints in the 'package' power zones apply to the whole -CPU packages and the subzone constraints only apply to the respective parts of -the given package individually). Since Intel RAPL doesn't provide instantaneous -power value, there is no power_uw attribute. - -In addition to that, each power zone contains a name attribute, allowing the -part of the system represented by that zone to be identified. -For example: - -cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name -package-0 - -The Intel RAPL technology allows two constraints, short term and long term, -with two different time windows to be applied to each power zone. Thus for -each zone there are 2 attributes representing the constraint names, 2 power -limits and 2 attributes representing the sizes of the time windows. Such that, -constraint_j_* attributes correspond to the jth constraint (j = 0,1). - -For example: - constraint_0_name - constraint_0_power_limit_uw - constraint_0_time_window_us - constraint_1_name - constraint_1_power_limit_uw - constraint_1_time_window_us - -Power Zone Attributes -================================= -Monitoring attributes ----------------------- - -energy_uj (rw): Current energy counter in micro joules. Write "0" to reset. -If the counter can not be reset, then this attribute is read only. - -max_energy_range_uj (ro): Range of the above energy counter in micro-joules. - -power_uw (ro): Current power in micro watts. - -max_power_range_uw (ro): Range of the above power value in micro-watts. - -name (ro): Name of this power zone. - -It is possible that some domains have both power ranges and energy counter ranges; -however, only one is mandatory. - -Constraints ----------------- -constraint_X_power_limit_uw (rw): Power limit in micro watts, which should be -applicable for the time window specified by "constraint_X_time_window_us". - -constraint_X_time_window_us (rw): Time window in micro seconds. - -constraint_X_name (ro): An optional name of the constraint - -constraint_X_max_power_uw(ro): Maximum allowed power in micro watts. - -constraint_X_min_power_uw(ro): Minimum allowed power in micro watts. - -constraint_X_max_time_window_us(ro): Maximum allowed time window in micro seconds. - -constraint_X_min_time_window_us(ro): Minimum allowed time window in micro seconds. - -Except power_limit_uw and time_window_us other fields are optional. - -Common zone and control type attributes ----------------------------------------- -enabled (rw): Enable/Disable controls at zone level or for all zones using -a control type. - -Power Cap Client Driver Interface -================================== -The API summary: - -Call powercap_register_control_type() to register control type object. -Call powercap_register_zone() to register a power zone (under a given -control type), either as a top-level power zone or as a subzone of another -power zone registered earlier. -The number of constraints in a power zone and the corresponding callbacks have -to be defined prior to calling powercap_register_zone() to register that zone. - -To Free a power zone call powercap_unregister_zone(). -To free a control type object call powercap_unregister_control_type(). -Detailed API can be generated using kernel-doc on include/linux/powercap.h. diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.rst index e51564c1a140..0cd8cc1275a7 100644 --- a/Documentation/power/regulator/consumer.txt +++ b/Documentation/power/regulator/consumer.rst @@ -1,3 +1,4 @@ +=================================== Regulator Consumer Driver Interface =================================== @@ -8,73 +9,77 @@ Please see overview.txt for a description of the terms used in this text. 1. Consumer Regulator Access (static & dynamic drivers) ======================================================= -A consumer driver can get access to its supply regulator by calling :- +A consumer driver can get access to its supply regulator by calling :: -regulator = regulator_get(dev, "Vcc"); + regulator = regulator_get(dev, "Vcc"); The consumer passes in its struct device pointer and power supply ID. The core then finds the correct regulator by consulting a machine specific lookup table. If the lookup is successful then this call will return a pointer to the struct regulator that supplies this consumer. -To release the regulator the consumer driver should call :- +To release the regulator the consumer driver should call :: -regulator_put(regulator); + regulator_put(regulator); Consumers can be supplied by more than one regulator e.g. codec consumer with -analog and digital supplies :- +analog and digital supplies :: -digital = regulator_get(dev, "Vcc"); /* digital core */ -analog = regulator_get(dev, "Avdd"); /* analog */ + digital = regulator_get(dev, "Vcc"); /* digital core */ + analog = regulator_get(dev, "Avdd"); /* analog */ The regulator access functions regulator_get() and regulator_put() will usually be called in your device drivers probe() and remove() respectively. 2. Regulator Output Enable & Disable (static & dynamic drivers) -==================================================================== +=============================================================== + -A consumer can enable its power supply by calling:- +A consumer can enable its power supply by calling:: -int regulator_enable(regulator); + int regulator_enable(regulator); -NOTE: The supply may already be enabled before regulator_enabled() is called. -This may happen if the consumer shares the regulator or the regulator has been -previously enabled by bootloader or kernel board initialization code. +NOTE: + The supply may already be enabled before regulator_enabled() is called. + This may happen if the consumer shares the regulator or the regulator has been + previously enabled by bootloader or kernel board initialization code. -A consumer can determine if a regulator is enabled by calling :- +A consumer can determine if a regulator is enabled by calling:: -int regulator_is_enabled(regulator); + int regulator_is_enabled(regulator); This will return > zero when the regulator is enabled. -A consumer can disable its supply when no longer needed by calling :- +A consumer can disable its supply when no longer needed by calling:: -int regulator_disable(regulator); + int regulator_disable(regulator); -NOTE: This may not disable the supply if it's shared with other consumers. The -regulator will only be disabled when the enabled reference count is zero. +NOTE: + This may not disable the supply if it's shared with other consumers. The + regulator will only be disabled when the enabled reference count is zero. -Finally, a regulator can be forcefully disabled in the case of an emergency :- +Finally, a regulator can be forcefully disabled in the case of an emergency:: -int regulator_force_disable(regulator); + int regulator_force_disable(regulator); -NOTE: this will immediately and forcefully shutdown the regulator output. All -consumers will be powered off. +NOTE: + this will immediately and forcefully shutdown the regulator output. All + consumers will be powered off. 3. Regulator Voltage Control & Status (dynamic drivers) -====================================================== +======================================================= Some consumer drivers need to be able to dynamically change their supply voltage to match system operating points. e.g. CPUfreq drivers can scale voltage along with frequency to save power, SD drivers may need to select the correct card voltage, etc. -Consumers can control their supply voltage by calling :- +Consumers can control their supply voltage by calling:: -int regulator_set_voltage(regulator, min_uV, max_uV); + int regulator_set_voltage(regulator, min_uV, max_uV); Where min_uV and max_uV are the minimum and maximum acceptable voltages in microvolts. @@ -84,47 +89,50 @@ when enabled, then the voltage changes instantly, otherwise the voltage configuration changes and the voltage is physically set when the regulator is next enabled. -The regulators configured voltage output can be found by calling :- +The regulators configured voltage output can be found by calling:: -int regulator_get_voltage(regulator); + int regulator_get_voltage(regulator); -NOTE: get_voltage() will return the configured output voltage whether the -regulator is enabled or disabled and should NOT be used to determine regulator -output state. However this can be used in conjunction with is_enabled() to -determine the regulator physical output voltage. +NOTE: + get_voltage() will return the configured output voltage whether the + regulator is enabled or disabled and should NOT be used to determine regulator + output state. However this can be used in conjunction with is_enabled() to + determine the regulator physical output voltage. 4. Regulator Current Limit Control & Status (dynamic drivers) -=========================================================== +============================================================= Some consumer drivers need to be able to dynamically change their supply current limit to match system operating points. e.g. LCD backlight driver can change the current limit to vary the backlight brightness, USB drivers may want to set the limit to 500mA when supplying power. -Consumers can control their supply current limit by calling :- +Consumers can control their supply current limit by calling:: -int regulator_set_current_limit(regulator, min_uA, max_uA); + int regulator_set_current_limit(regulator, min_uA, max_uA); Where min_uA and max_uA are the minimum and maximum acceptable current limit in microamps. -NOTE: this can be called when the regulator is enabled or disabled. If called -when enabled, then the current limit changes instantly, otherwise the current -limit configuration changes and the current limit is physically set when the -regulator is next enabled. +NOTE: + this can be called when the regulator is enabled or disabled. If called + when enabled, then the current limit changes instantly, otherwise the current + limit configuration changes and the current limit is physically set when the + regulator is next enabled. -A regulators current limit can be found by calling :- +A regulators current limit can be found by calling:: -int regulator_get_current_limit(regulator); + int regulator_get_current_limit(regulator); -NOTE: get_current_limit() will return the current limit whether the regulator -is enabled or disabled and should not be used to determine regulator current -load. +NOTE: + get_current_limit() will return the current limit whether the regulator + is enabled or disabled and should not be used to determine regulator current + load. 5. Regulator Operating Mode Control & Status (dynamic drivers) -============================================================= +============================================================== Some consumers can further save system power by changing the operating mode of their supply regulator to be more efficient when the consumers operating state @@ -135,9 +143,9 @@ Regulator operating mode can be changed indirectly or directly. Indirect operating mode control. -------------------------------- Consumer drivers can request a change in their supply regulator operating mode -by calling :- +by calling:: -int regulator_set_load(struct regulator *regulator, int load_uA); + int regulator_set_load(struct regulator *regulator, int load_uA); This will cause the core to recalculate the total load on the regulator (based on all its consumers) and change operating mode (if necessary and permitted) @@ -153,12 +161,13 @@ consumers. Direct operating mode control. ------------------------------ + Bespoke or tightly coupled drivers may want to directly control regulator operating mode depending on their operating point. This can be achieved by -calling :- +calling:: -int regulator_set_mode(struct regulator *regulator, unsigned int mode); -unsigned int regulator_get_mode(struct regulator *regulator); + int regulator_set_mode(struct regulator *regulator, unsigned int mode); + unsigned int regulator_get_mode(struct regulator *regulator); Direct mode will only be used by consumers that *know* about the regulator and are not sharing the regulator with other consumers. @@ -166,24 +175,26 @@ are not sharing the regulator with other consumers. 6. Regulator Events =================== + Regulators can notify consumers of external events. Events could be received by consumers under regulator stress or failure conditions. -Consumers can register interest in regulator events by calling :- +Consumers can register interest in regulator events by calling:: -int regulator_register_notifier(struct regulator *regulator, - struct notifier_block *nb); + int regulator_register_notifier(struct regulator *regulator, + struct notifier_block *nb); -Consumers can unregister interest by calling :- +Consumers can unregister interest by calling:: -int regulator_unregister_notifier(struct regulator *regulator, - struct notifier_block *nb); + int regulator_unregister_notifier(struct regulator *regulator, + struct notifier_block *nb); Regulators use the kernel notifier framework to send event to their interested consumers. 7. Regulator Direct Register Access =================================== + Some kinds of power management hardware or firmware are designed such that they need to do low-level hardware access to regulators, with no involvement from the kernel. Examples of such devices are: @@ -199,20 +210,20 @@ to it. The regulator framework provides the following helpers for querying these details. Bus-specific details, like I2C addresses or transfer rates are handled by the -regmap framework. To get the regulator's regmap (if supported), use :- +regmap framework. To get the regulator's regmap (if supported), use:: -struct regmap *regulator_get_regmap(struct regulator *regulator); + struct regmap *regulator_get_regmap(struct regulator *regulator); To obtain the hardware register offset and bitmask for the regulator's voltage -selector register, use :- +selector register, use:: -int regulator_get_hardware_vsel_register(struct regulator *regulator, - unsigned *vsel_reg, - unsigned *vsel_mask); + int regulator_get_hardware_vsel_register(struct regulator *regulator, + unsigned *vsel_reg, + unsigned *vsel_mask); To convert a regulator framework voltage selector code (used by regulator_list_voltage) to a hardware-specific voltage selector that can be -directly written to the voltage selector register, use :- +directly written to the voltage selector register, use:: -int regulator_list_hardware_vsel(struct regulator *regulator, - unsigned selector); + int regulator_list_hardware_vsel(struct regulator *regulator, + unsigned selector); diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.rst index fdd919b96830..3b09c6841dc4 100644 --- a/Documentation/power/regulator/design.txt +++ b/Documentation/power/regulator/design.rst @@ -1,3 +1,4 @@ +========================== Regulator API design notes ========================== @@ -14,7 +15,9 @@ Safety have different power requirements, and not all components with power requirements are visible to software. - => The API should make no changes to the hardware state unless it has +.. note:: + + The API should make no changes to the hardware state unless it has specific knowledge that these changes are safe to perform on this particular system. @@ -28,6 +31,8 @@ Consumer use cases - Many of the power supplies in the system will be shared between many different consumers. - => The consumer API should be structured so that these use cases are +.. note:: + + The consumer API should be structured so that these use cases are very easy to handle and so that consumers will work with shared supplies without any additional effort. diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.rst index eff4dcaaa252..22fffefaa3ad 100644 --- a/Documentation/power/regulator/machine.txt +++ b/Documentation/power/regulator/machine.rst @@ -1,10 +1,11 @@ +================================== Regulator Machine Driver Interface -=================================== +================================== The regulator machine driver interface is intended for board/machine specific initialisation code to configure the regulator subsystem. -Consider the following machine :- +Consider the following machine:: Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V] | @@ -13,31 +14,31 @@ Consider the following machine :- The drivers for consumers A & B must be mapped to the correct regulator in order to control their power supplies. This mapping can be achieved in machine initialisation code by creating a struct regulator_consumer_supply for -each regulator. +each regulator:: -struct regulator_consumer_supply { + struct regulator_consumer_supply { const char *dev_name; /* consumer dev_name() */ const char *supply; /* consumer supply - e.g. "vcc" */ -}; + }; -e.g. for the machine above +e.g. for the machine above:: -static struct regulator_consumer_supply regulator1_consumers[] = { + static struct regulator_consumer_supply regulator1_consumers[] = { REGULATOR_SUPPLY("Vcc", "consumer B"), -}; + }; -static struct regulator_consumer_supply regulator2_consumers[] = { + static struct regulator_consumer_supply regulator2_consumers[] = { REGULATOR_SUPPLY("Vcc", "consumer A"), -}; + }; This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2 to the 'Vcc' supply for Consumer A. Constraints can now be registered by defining a struct regulator_init_data for each regulator power domain. This structure also maps the consumers -to their supply regulators :- +to their supply regulators:: -static struct regulator_init_data regulator1_data = { + static struct regulator_init_data regulator1_data = { .constraints = { .name = "Regulator-1", .min_uV = 3300000, @@ -46,7 +47,7 @@ static struct regulator_init_data regulator1_data = { }, .num_consumer_supplies = ARRAY_SIZE(regulator1_consumers), .consumer_supplies = regulator1_consumers, -}; + }; The name field should be set to something that is usefully descriptive for the board for configuration of supplies for other regulators and @@ -57,9 +58,9 @@ name is provided then the subsystem will choose one. Regulator-1 supplies power to Regulator-2. This relationship must be registered with the core so that Regulator-1 is also enabled when Consumer A enables its supply (Regulator-2). The supply regulator is set by the supply_regulator -field below and co:- +field below and co:: -static struct regulator_init_data regulator2_data = { + static struct regulator_init_data regulator2_data = { .supply_regulator = "Regulator-1", .constraints = { .min_uV = 1800000, @@ -69,11 +70,11 @@ static struct regulator_init_data regulator2_data = { }, .num_consumer_supplies = ARRAY_SIZE(regulator2_consumers), .consumer_supplies = regulator2_consumers, -}; + }; -Finally the regulator devices must be registered in the usual manner. +Finally the regulator devices must be registered in the usual manner:: -static struct platform_device regulator_devices[] = { + static struct platform_device regulator_devices[] = { { .name = "regulator", .id = DCDC_1, @@ -88,9 +89,9 @@ static struct platform_device regulator_devices[] = { .platform_data = ®ulator2_data, }, }, -}; -/* register regulator 1 device */ -platform_device_register(®ulator_devices[0]); + }; + /* register regulator 1 device */ + platform_device_register(®ulator_devices[0]); -/* register regulator 2 device */ -platform_device_register(®ulator_devices[1]); + /* register regulator 2 device */ + platform_device_register(®ulator_devices[1]); diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.rst index 721b4739ec32..ee494c70a7c4 100644 --- a/Documentation/power/regulator/overview.txt +++ b/Documentation/power/regulator/overview.rst @@ -1,3 +1,4 @@ +============================================= Linux voltage and current regulator framework ============================================= @@ -13,26 +14,30 @@ regulators (where voltage output is controllable) and current sinks (where current limit is controllable). (C) 2008 Wolfson Microelectronics PLC. + Author: Liam Girdwood <lrg@slimlogic.co.uk> Nomenclature ============ -Some terms used in this document:- +Some terms used in this document: - o Regulator - Electronic device that supplies power to other devices. + - Regulator + - Electronic device that supplies power to other devices. Most regulators can enable and disable their output while some can control their output voltage and or current. Input Voltage -> Regulator -> Output Voltage - o PMIC - Power Management IC. An IC that contains numerous regulators - and often contains other subsystems. + - PMIC + - Power Management IC. An IC that contains numerous + regulators and often contains other subsystems. - o Consumer - Electronic device that is supplied power by a regulator. + - Consumer + - Electronic device that is supplied power by a regulator. Consumers can be classified into two types:- Static: consumer does not change its supply voltage or @@ -44,46 +49,48 @@ Some terms used in this document:- current limit to meet operation demands. - o Power Domain - Electronic circuit that is supplied its input power by the + - Power Domain + - Electronic circuit that is supplied its input power by the output power of a regulator, switch or by another power domain. - The supply regulator may be behind a switch(s). i.e. + The supply regulator may be behind a switch(s). i.e.:: - Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A] - | | - | +-> [Consumer B], [Consumer C] - | - +-> [Consumer D], [Consumer E] + Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A] + | | + | +-> [Consumer B], [Consumer C] + | + +-> [Consumer D], [Consumer E] That is one regulator and three power domains: - Domain 1: Switch-1, Consumers D & E. - Domain 2: Switch-2, Consumers B & C. - Domain 3: Consumer A. + - Domain 1: Switch-1, Consumers D & E. + - Domain 2: Switch-2, Consumers B & C. + - Domain 3: Consumer A. and this represents a "supplies" relationship: Domain-1 --> Domain-2 --> Domain-3. A power domain may have regulators that are supplied power - by other regulators. i.e. + by other regulators. i.e.:: - Regulator-1 -+-> Regulator-2 -+-> [Consumer A] - | - +-> [Consumer B] + Regulator-1 -+-> Regulator-2 -+-> [Consumer A] + | + +-> [Consumer B] This gives us two regulators and two power domains: - Domain 1: Regulator-2, Consumer B. - Domain 2: Consumer A. + - Domain 1: Regulator-2, Consumer B. + - Domain 2: Consumer A. and a "supplies" relationship: Domain-1 --> Domain-2 - o Constraints - Constraints are used to define power levels for performance + - Constraints + - Constraints are used to define power levels for performance and hardware protection. Constraints exist at three levels: Regulator Level: This is defined by the regulator hardware @@ -141,7 +148,7 @@ relevant to non SoC devices and is split into the following four interfaces:- limit. This also compiles out if not in use so drivers can be reused in systems with no regulator based power control. - See Documentation/power/regulator/consumer.txt + See Documentation/power/regulator/consumer.rst 2. Regulator driver interface. @@ -149,7 +156,7 @@ relevant to non SoC devices and is split into the following four interfaces:- operations to the core. It also has a notifier call chain for propagating regulator events to clients. - See Documentation/power/regulator/regulator.txt + See Documentation/power/regulator/regulator.rst 3. Machine interface. @@ -160,7 +167,7 @@ relevant to non SoC devices and is split into the following four interfaces:- allows the creation of a regulator tree whereby some regulators are supplied by others (similar to a clock tree). - See Documentation/power/regulator/machine.txt + See Documentation/power/regulator/machine.rst 4. Userspace ABI. diff --git a/Documentation/power/regulator/regulator.rst b/Documentation/power/regulator/regulator.rst new file mode 100644 index 000000000000..794b3256fbb9 --- /dev/null +++ b/Documentation/power/regulator/regulator.rst @@ -0,0 +1,32 @@ +========================== +Regulator Driver Interface +========================== + +The regulator driver interface is relatively simple and designed to allow +regulator drivers to register their services with the core framework. + + +Registration +============ + +Drivers can register a regulator by calling:: + + struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc, + const struct regulator_config *config); + +This will register the regulator's capabilities and operations to the regulator +core. + +Regulators can be unregistered by calling:: + + void regulator_unregister(struct regulator_dev *rdev); + + +Regulator Events +================ + +Regulators can send events (e.g. overtemperature, undervoltage, etc) to +consumer drivers by calling:: + + int regulator_notifier_call_chain(struct regulator_dev *rdev, + unsigned long event, void *data); diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt deleted file mode 100644 index b17e5833ce21..000000000000 --- a/Documentation/power/regulator/regulator.txt +++ /dev/null @@ -1,30 +0,0 @@ -Regulator Driver Interface -========================== - -The regulator driver interface is relatively simple and designed to allow -regulator drivers to register their services with the core framework. - - -Registration -============ - -Drivers can register a regulator by calling :- - -struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc, - const struct regulator_config *config); - -This will register the regulator's capabilities and operations to the regulator -core. - -Regulators can be unregistered by calling :- - -void regulator_unregister(struct regulator_dev *rdev); - - -Regulator Events -================ -Regulators can send events (e.g. overtemperature, undervoltage, etc) to -consumer drivers by calling :- - -int regulator_notifier_call_chain(struct regulator_dev *rdev, - unsigned long event, void *data); diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.rst index 937e33c46211..2c2ec99b5088 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.rst @@ -1,10 +1,15 @@ +================================================== Runtime Power Management Framework for I/O Devices +================================================== (C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. + (C) 2010 Alan Stern <stern@rowland.harvard.edu> + (C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> 1. Introduction +=============== Support for runtime power management (runtime PM) of I/O devices is provided at the power management core (PM core) level by means of: @@ -33,16 +38,17 @@ fields of 'struct dev_pm_info' and the core helper functions provided for runtime PM are described below. 2. Device Runtime PM Callbacks +============================== -There are three device runtime PM callbacks defined in 'struct dev_pm_ops': +There are three device runtime PM callbacks defined in 'struct dev_pm_ops':: -struct dev_pm_ops { + struct dev_pm_ops { ... int (*runtime_suspend)(struct device *dev); int (*runtime_resume)(struct device *dev); int (*runtime_idle)(struct device *dev); ... -}; + }; The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks are executed by the PM core for the device's subsystem that may be either of @@ -112,7 +118,7 @@ low-power state during the execution of the suspend callback, it is expected that remote wakeup will be enabled for the device. Generally, remote wakeup should be enabled for all input devices put into low-power states at run time. -The subsystem-level resume callback, if present, is _entirely_ _responsible_ for +The subsystem-level resume callback, if present, is **entirely responsible** for handling the resume of the device as appropriate, which may, but need not include executing the device driver's own ->runtime_resume() callback (from the PM core's point of view it is not necessary to implement a ->runtime_resume() @@ -197,95 +203,96 @@ rules: except for scheduled autosuspends. 3. Runtime PM Device Fields +=========================== The following device runtime PM fields are present in 'struct dev_pm_info', as defined in include/linux/pm.h: - struct timer_list suspend_timer; + `struct timer_list suspend_timer;` - timer used for scheduling (delayed) suspend and autosuspend requests - unsigned long timer_expires; + `unsigned long timer_expires;` - timer expiration time, in jiffies (if this is different from zero, the timer is running and will expire at that time, otherwise the timer is not running) - struct work_struct work; + `struct work_struct work;` - work structure used for queuing up requests (i.e. work items in pm_wq) - wait_queue_head_t wait_queue; + `wait_queue_head_t wait_queue;` - wait queue used if any of the helper functions needs to wait for another one to complete - spinlock_t lock; + `spinlock_t lock;` - lock used for synchronization - atomic_t usage_count; + `atomic_t usage_count;` - the usage counter of the device - atomic_t child_count; + `atomic_t child_count;` - the count of 'active' children of the device - unsigned int ignore_children; + `unsigned int ignore_children;` - if set, the value of child_count is ignored (but still updated) - unsigned int disable_depth; + `unsigned int disable_depth;` - used for disabling the helper functions (they work normally if this is equal to zero); the initial value of it is 1 (i.e. runtime PM is initially disabled for all devices) - int runtime_error; + `int runtime_error;` - if set, there was a fatal error (one of the callbacks returned error code as described in Section 2), so the helper functions will not work until this flag is cleared; this is the error code returned by the failing callback - unsigned int idle_notification; + `unsigned int idle_notification;` - if set, ->runtime_idle() is being executed - unsigned int request_pending; + `unsigned int request_pending;` - if set, there's a pending request (i.e. a work item queued up into pm_wq) - enum rpm_request request; + `enum rpm_request request;` - type of request that's pending (valid if request_pending is set) - unsigned int deferred_resume; + `unsigned int deferred_resume;` - set if ->runtime_resume() is about to be run while ->runtime_suspend() is being executed for that device and it is not practical to wait for the suspend to complete; means "start a resume as soon as you've suspended" - enum rpm_status runtime_status; + `enum rpm_status runtime_status;` - the runtime PM status of the device; this field's initial value is RPM_SUSPENDED, which means that each device is initially regarded by the PM core as 'suspended', regardless of its real hardware status - unsigned int runtime_auto; + `unsigned int runtime_auto;` - if set, indicates that the user space has allowed the device driver to power manage the device at run time via the /sys/devices/.../power/control - interface; it may only be modified with the help of the pm_runtime_allow() + `interface;` it may only be modified with the help of the pm_runtime_allow() and pm_runtime_forbid() helper functions - unsigned int no_callbacks; + `unsigned int no_callbacks;` - indicates that the device does not use the runtime PM callbacks (see Section 8); it may be modified only by the pm_runtime_no_callbacks() helper function - unsigned int irq_safe; + `unsigned int irq_safe;` - indicates that the ->runtime_suspend() and ->runtime_resume() callbacks will be invoked with the spinlock held and interrupts disabled - unsigned int use_autosuspend; + `unsigned int use_autosuspend;` - indicates that the device's driver supports delayed autosuspend (see Section 9); it may be modified only by the pm_runtime{_dont}_use_autosuspend() helper functions - unsigned int timer_autosuspends; + `unsigned int timer_autosuspends;` - indicates that the PM core should attempt to carry out an autosuspend when the timer expires rather than a normal suspend - int autosuspend_delay; + `int autosuspend_delay;` - the delay time (in milliseconds) to be used for autosuspend - unsigned long last_busy; + `unsigned long last_busy;` - the time (in jiffies) when the pm_runtime_mark_last_busy() helper function was last called for this device; used in calculating inactivity periods for autosuspend @@ -293,37 +300,38 @@ defined in include/linux/pm.h: All of the above fields are members of the 'power' member of 'struct device'. 4. Runtime PM Device Helper Functions +===================================== The following runtime PM helper functions are defined in drivers/base/power/runtime.c and include/linux/pm_runtime.h: - void pm_runtime_init(struct device *dev); + `void pm_runtime_init(struct device *dev);` - initialize the device runtime PM fields in 'struct dev_pm_info' - void pm_runtime_remove(struct device *dev); + `void pm_runtime_remove(struct device *dev);` - make sure that the runtime PM of the device will be disabled after removing the device from device hierarchy - int pm_runtime_idle(struct device *dev); + `int pm_runtime_idle(struct device *dev);` - execute the subsystem-level idle callback for the device; returns an error code on failure, where -EINPROGRESS means that ->runtime_idle() is already being executed; if there is no callback or the callback returns 0 then run pm_runtime_autosuspend(dev) and return its result - int pm_runtime_suspend(struct device *dev); + `int pm_runtime_suspend(struct device *dev);` - execute the subsystem-level suspend callback for the device; returns 0 on success, 1 if the device's runtime PM status was already 'suspended', or error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt to suspend the device again in future and -EACCES means that 'power.disable_depth' is different from 0 - int pm_runtime_autosuspend(struct device *dev); + `int pm_runtime_autosuspend(struct device *dev);` - same as pm_runtime_suspend() except that the autosuspend delay is taken - into account; if pm_runtime_autosuspend_expiration() says the delay has + `into account;` if pm_runtime_autosuspend_expiration() says the delay has not yet expired then an autosuspend is scheduled for the appropriate time and 0 is returned - int pm_runtime_resume(struct device *dev); + `int pm_runtime_resume(struct device *dev);` - execute the subsystem-level resume callback for the device; returns 0 on success, 1 if the device's runtime PM status was already 'active' or error code on failure, where -EAGAIN means it may be safe to attempt to @@ -331,17 +339,17 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: checked additionally, and -EACCES means that 'power.disable_depth' is different from 0 - int pm_request_idle(struct device *dev); + `int pm_request_idle(struct device *dev);` - submit a request to execute the subsystem-level idle callback for the device (the request is represented by a work item in pm_wq); returns 0 on success or error code if the request has not been queued up - int pm_request_autosuspend(struct device *dev); + `int pm_request_autosuspend(struct device *dev);` - schedule the execution of the subsystem-level suspend callback for the device when the autosuspend delay has expired; if the delay has already expired then the work item is queued up immediately - int pm_schedule_suspend(struct device *dev, unsigned int delay); + `int pm_schedule_suspend(struct device *dev, unsigned int delay);` - schedule the execution of the subsystem-level suspend callback for the device in future, where 'delay' is the time to wait before queuing up a suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work @@ -351,58 +359,58 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: ->runtime_suspend() is already scheduled and not yet expired, the new value of 'delay' will be used as the time to wait - int pm_request_resume(struct device *dev); + `int pm_request_resume(struct device *dev);` - submit a request to execute the subsystem-level resume callback for the device (the request is represented by a work item in pm_wq); returns 0 on success, 1 if the device's runtime PM status was already 'active', or error code if the request hasn't been queued up - void pm_runtime_get_noresume(struct device *dev); + `void pm_runtime_get_noresume(struct device *dev);` - increment the device's usage counter - int pm_runtime_get(struct device *dev); + `int pm_runtime_get(struct device *dev);` - increment the device's usage counter, run pm_request_resume(dev) and return its result - int pm_runtime_get_sync(struct device *dev); + `int pm_runtime_get_sync(struct device *dev);` - 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); + `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); + `void pm_runtime_put_noidle(struct device *dev);` - decrement the device's usage counter - int pm_runtime_put(struct device *dev); + `int pm_runtime_put(struct device *dev);` - decrement the device's usage counter; if the result is 0 then run pm_request_idle(dev) and return its result - int pm_runtime_put_autosuspend(struct device *dev); + `int pm_runtime_put_autosuspend(struct device *dev);` - decrement the device's usage counter; if the result is 0 then run pm_request_autosuspend(dev) and return its result - int pm_runtime_put_sync(struct device *dev); + `int pm_runtime_put_sync(struct device *dev);` - decrement the device's usage counter; if the result is 0 then run pm_runtime_idle(dev) and return its result - int pm_runtime_put_sync_suspend(struct device *dev); + `int pm_runtime_put_sync_suspend(struct device *dev);` - decrement the device's usage counter; if the result is 0 then run pm_runtime_suspend(dev) and return its result - int pm_runtime_put_sync_autosuspend(struct device *dev); + `int pm_runtime_put_sync_autosuspend(struct device *dev);` - decrement the device's usage counter; if the result is 0 then run pm_runtime_autosuspend(dev) and return its result - void pm_runtime_enable(struct device *dev); + `void pm_runtime_enable(struct device *dev);` - decrement the device's 'power.disable_depth' field; if that field is equal to zero, the runtime PM helper functions can execute subsystem-level callbacks described in Section 2 for the device - int pm_runtime_disable(struct device *dev); + `int pm_runtime_disable(struct device *dev);` - increment the device's 'power.disable_depth' field (if the value of that field was previously zero, this prevents subsystem-level runtime PM callbacks from being run for the device), make sure that all of the @@ -411,7 +419,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: necessary to execute the subsystem-level resume callback for the device to satisfy that request, otherwise 0 is returned - int pm_runtime_barrier(struct device *dev); + `int pm_runtime_barrier(struct device *dev);` - check if there's a resume request pending for the device and resume it (synchronously) in that case, cancel any other pending runtime PM requests regarding it and wait for all runtime PM operations on it in progress to @@ -419,10 +427,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: necessary to execute the subsystem-level resume callback for the device to satisfy that request, otherwise 0 is returned - void pm_suspend_ignore_children(struct device *dev, bool enable); + `void pm_suspend_ignore_children(struct device *dev, bool enable);` - set/unset the power.ignore_children flag of the device - int pm_runtime_set_active(struct device *dev); + `int pm_runtime_set_active(struct device *dev);` - clear the device's 'power.runtime_error' flag, set the device's runtime PM status to 'active' and update its parent's counter of 'active' children as appropriate (it is only valid to use this function if @@ -430,61 +438,61 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: zero); it will fail and return error code if the device has a parent which is not active and the 'power.ignore_children' flag of which is unset - void pm_runtime_set_suspended(struct device *dev); + `void pm_runtime_set_suspended(struct device *dev);` - clear the device's 'power.runtime_error' flag, set the device's runtime PM status to 'suspended' and update its parent's counter of 'active' children as appropriate (it is only valid to use this function if 'power.runtime_error' is set or 'power.disable_depth' is greater than zero) - bool pm_runtime_active(struct device *dev); + `bool pm_runtime_active(struct device *dev);` - return true if the device's runtime PM status is 'active' or its 'power.disable_depth' field is not equal to zero, or false otherwise - bool pm_runtime_suspended(struct device *dev); + `bool pm_runtime_suspended(struct device *dev);` - return true if the device's runtime PM status is 'suspended' and its 'power.disable_depth' field is equal to zero, or false otherwise - bool pm_runtime_status_suspended(struct device *dev); + `bool pm_runtime_status_suspended(struct device *dev);` - return true if the device's runtime PM status is 'suspended' - void pm_runtime_allow(struct device *dev); + `void pm_runtime_allow(struct device *dev);` - set the power.runtime_auto flag for the device and decrease its usage counter (used by the /sys/devices/.../power/control interface to effectively allow the device to be power managed at run time) - void pm_runtime_forbid(struct device *dev); + `void pm_runtime_forbid(struct device *dev);` - unset the power.runtime_auto flag for the device and increase its usage counter (used by the /sys/devices/.../power/control interface to effectively prevent the device from being power managed at run time) - void pm_runtime_no_callbacks(struct device *dev); + `void pm_runtime_no_callbacks(struct device *dev);` - set the power.no_callbacks flag for the device and remove the runtime PM attributes from /sys/devices/.../power (or prevent them from being added when the device is registered) - void pm_runtime_irq_safe(struct device *dev); + `void pm_runtime_irq_safe(struct device *dev);` - set the power.irq_safe flag for the device, causing the runtime-PM callbacks to be invoked with interrupts off - bool pm_runtime_is_irq_safe(struct device *dev); + `bool pm_runtime_is_irq_safe(struct device *dev);` - return true if power.irq_safe flag was set for the device, causing the runtime-PM callbacks to be invoked with interrupts off - void pm_runtime_mark_last_busy(struct device *dev); + `void pm_runtime_mark_last_busy(struct device *dev);` - set the power.last_busy field to the current time - void pm_runtime_use_autosuspend(struct device *dev); + `void pm_runtime_use_autosuspend(struct device *dev);` - set the power.use_autosuspend flag, enabling autosuspend delays; call pm_runtime_get_sync if the flag was previously cleared and power.autosuspend_delay is negative - void pm_runtime_dont_use_autosuspend(struct device *dev); + `void pm_runtime_dont_use_autosuspend(struct device *dev);` - clear the power.use_autosuspend flag, disabling autosuspend delays; decrement the device's usage counter if the flag was previously set and power.autosuspend_delay is negative; call pm_runtime_idle - void pm_runtime_set_autosuspend_delay(struct device *dev, int delay); + `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);` - set the power.autosuspend_delay value to 'delay' (expressed in milliseconds); if 'delay' is negative then runtime suspends are prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be @@ -493,7 +501,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: changed to or from a negative value; if power.use_autosuspend is clear, pm_runtime_idle is called - unsigned long pm_runtime_autosuspend_expiration(struct device *dev); + `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);` - calculate the time when the current autosuspend delay period will expire, based on power.last_busy and power.autosuspend_delay; if the delay time is 1000 ms or larger then the expiration time is rounded up to the @@ -503,36 +511,37 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: It is safe to execute the following helper functions from interrupt context: -pm_request_idle() -pm_request_autosuspend() -pm_schedule_suspend() -pm_request_resume() -pm_runtime_get_noresume() -pm_runtime_get() -pm_runtime_put_noidle() -pm_runtime_put() -pm_runtime_put_autosuspend() -pm_runtime_enable() -pm_suspend_ignore_children() -pm_runtime_set_active() -pm_runtime_set_suspended() -pm_runtime_suspended() -pm_runtime_mark_last_busy() -pm_runtime_autosuspend_expiration() +- pm_request_idle() +- pm_request_autosuspend() +- pm_schedule_suspend() +- pm_request_resume() +- pm_runtime_get_noresume() +- pm_runtime_get() +- pm_runtime_put_noidle() +- pm_runtime_put() +- pm_runtime_put_autosuspend() +- pm_runtime_enable() +- pm_suspend_ignore_children() +- pm_runtime_set_active() +- pm_runtime_set_suspended() +- pm_runtime_suspended() +- pm_runtime_mark_last_busy() +- pm_runtime_autosuspend_expiration() If pm_runtime_irq_safe() has been called for a device then the following helper functions may also be used in interrupt context: -pm_runtime_idle() -pm_runtime_suspend() -pm_runtime_autosuspend() -pm_runtime_resume() -pm_runtime_get_sync() -pm_runtime_put_sync() -pm_runtime_put_sync_suspend() -pm_runtime_put_sync_autosuspend() +- pm_runtime_idle() +- pm_runtime_suspend() +- pm_runtime_autosuspend() +- pm_runtime_resume() +- pm_runtime_get_sync() +- pm_runtime_put_sync() +- pm_runtime_put_sync_suspend() +- pm_runtime_put_sync_autosuspend() 5. Runtime PM Initialization, Device Probing and Removal +======================================================== Initially, the runtime PM is disabled for all devices, which means that the majority of the runtime PM helper functions described in Section 4 will return @@ -608,6 +617,7 @@ manage the device at run time, the driver may confuse it by using pm_runtime_forbid() this way. 6. Runtime PM and System Sleep +============================== Runtime PM and system sleep (i.e., system suspend and hibernation, also known as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of @@ -647,9 +657,9 @@ brought back to full power during resume, then its runtime PM status will have to be updated to reflect the actual post-system sleep status. The way to do this is: - pm_runtime_disable(dev); - pm_runtime_set_active(dev); - pm_runtime_enable(dev); + - pm_runtime_disable(dev); + - pm_runtime_set_active(dev); + - pm_runtime_enable(dev); The PM core always increments the runtime usage counter before calling the ->suspend() callback and decrements it after calling the ->resume() callback. @@ -705,66 +715,66 @@ Subsystems may wish to conserve code space by using the set of generic power management callbacks provided by the PM core, defined in driver/base/power/generic_ops.c: - int pm_generic_runtime_suspend(struct device *dev); + `int pm_generic_runtime_suspend(struct device *dev);` - invoke the ->runtime_suspend() callback provided by the driver of this device and return its result, or return 0 if not defined - int pm_generic_runtime_resume(struct device *dev); + `int pm_generic_runtime_resume(struct device *dev);` - invoke the ->runtime_resume() callback provided by the driver of this device and return its result, or return 0 if not defined - int pm_generic_suspend(struct device *dev); + `int pm_generic_suspend(struct device *dev);` - if the device has not been suspended at run time, invoke the ->suspend() callback provided by its driver and return its result, or return 0 if not defined - int pm_generic_suspend_noirq(struct device *dev); + `int pm_generic_suspend_noirq(struct device *dev);` - if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq() callback provided by the device's driver and return its result, or return 0 if not defined - int pm_generic_resume(struct device *dev); + `int pm_generic_resume(struct device *dev);` - invoke the ->resume() callback provided by the driver of this device and, if successful, change the device's runtime PM status to 'active' - int pm_generic_resume_noirq(struct device *dev); + `int pm_generic_resume_noirq(struct device *dev);` - invoke the ->resume_noirq() callback provided by the driver of this device - int pm_generic_freeze(struct device *dev); + `int pm_generic_freeze(struct device *dev);` - if the device has not been suspended at run time, invoke the ->freeze() callback provided by its driver and return its result, or return 0 if not defined - int pm_generic_freeze_noirq(struct device *dev); + `int pm_generic_freeze_noirq(struct device *dev);` - if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq() callback provided by the device's driver and return its result, or return 0 if not defined - int pm_generic_thaw(struct device *dev); + `int pm_generic_thaw(struct device *dev);` - if the device has not been suspended at run time, invoke the ->thaw() callback provided by its driver and return its result, or return 0 if not defined - int pm_generic_thaw_noirq(struct device *dev); + `int pm_generic_thaw_noirq(struct device *dev);` - if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq() callback provided by the device's driver and return its result, or return 0 if not defined - int pm_generic_poweroff(struct device *dev); + `int pm_generic_poweroff(struct device *dev);` - if the device has not been suspended at run time, invoke the ->poweroff() callback provided by its driver and return its result, or return 0 if not defined - int pm_generic_poweroff_noirq(struct device *dev); + `int pm_generic_poweroff_noirq(struct device *dev);` - if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq() callback provided by the device's driver and return its result, or return 0 if not defined - int pm_generic_restore(struct device *dev); + `int pm_generic_restore(struct device *dev);` - invoke the ->restore() callback provided by the driver of this device and, if successful, change the device's runtime PM status to 'active' - int pm_generic_restore_noirq(struct device *dev); + `int pm_generic_restore_noirq(struct device *dev);` - invoke the ->restore_noirq() callback provided by the device's driver These functions are the defaults used by the PM core, if a subsystem doesn't @@ -781,6 +791,7 @@ UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its last argument to NULL). 8. "No-Callback" Devices +======================== Some "devices" are only logical sub-devices of their parent and cannot be power-managed on their own. (The prototype example is a USB interface. Entire @@ -807,6 +818,7 @@ parent must take responsibility for telling the device's driver when the parent's power state changes. 9. Autosuspend, or automatically-delayed suspends +================================================= Changing a device's power state isn't free; it requires both time and energy. A device should be put in a low-power state only when there's some reason to @@ -832,8 +844,8 @@ registration the length should be controlled by user space, using the In order to use autosuspend, subsystems or drivers must call pm_runtime_use_autosuspend() (preferably before registering the device), and -thereafter they should use the various *_autosuspend() helper functions instead -of the non-autosuspend counterparts: +thereafter they should use the various `*_autosuspend()` helper functions +instead of the non-autosuspend counterparts:: Instead of: pm_runtime_suspend use: pm_runtime_autosuspend; Instead of: pm_schedule_suspend use: pm_request_autosuspend; @@ -858,7 +870,7 @@ The implementation is well suited for asynchronous use in interrupt contexts. However such use inevitably involves races, because the PM core can't synchronize ->runtime_suspend() callbacks with the arrival of I/O requests. This synchronization must be handled by the driver, using its private lock. -Here is a schematic pseudo-code example: +Here is a schematic pseudo-code example:: foo_read_or_write(struct foo_priv *foo, void *data) { diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.rst index 4685aee197fd..d739aa7c742c 100644 --- a/Documentation/power/s2ram.txt +++ b/Documentation/power/s2ram.rst @@ -1,7 +1,9 @@ - How to get s2ram working - ~~~~~~~~~~~~~~~~~~~~~~~~ - 2006 Linus Torvalds - 2006 Pavel Machek +======================== +How to get s2ram working +======================== + +2006 Linus Torvalds +2006 Pavel Machek 1) Check suspend.sf.net, program s2ram there has long whitelist of "known ok" machines, along with tricks to use on each one. @@ -12,8 +14,8 @@ 3) You can use Linus' TRACE_RESUME infrastructure, described below. - Using TRACE_RESUME - ~~~~~~~~~~~~~~~~~~ +Using TRACE_RESUME +~~~~~~~~~~~~~~~~~~ I've been working at making the machines I have able to STR, and almost always it's a driver that is buggy. Thank God for the suspend/resume @@ -27,7 +29,7 @@ machine that doesn't boot) is: - enable PM_DEBUG, and PM_TRACE - - use a script like this: + - use a script like this:: #!/bin/sh sync @@ -38,7 +40,7 @@ machine that doesn't boot) is: - if it doesn't come back up (which is usually the problem), reboot by holding the power button down, and look at the dmesg output for things - like + like:: Magic number: 4:156:725 hash matches drivers/base/power/resume.c:28 @@ -52,7 +54,7 @@ machine that doesn't boot) is: If no device matches the hash (or any matches appear to be false positives), the culprit may be a device from a loadable kernel module that is not loaded until after the hash is checked. You can check the hash against the current - devices again after more modules are loaded using sysfs: + devices again after more modules are loaded using sysfs:: cat /sys/power/pm_trace_dev_match diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst index a8751b8df10e..7ac8e1f549f4 100644 --- a/Documentation/power/suspend-and-cpuhotplug.txt +++ b/Documentation/power/suspend-and-cpuhotplug.rst @@ -1,10 +1,15 @@ +==================================================================== Interaction of Suspend code (S3) with the CPU hotplug infrastructure +==================================================================== - (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com> +(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com> -I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM - infrastructure uses it internally? And where do they share common code? +I. Differences between CPU hotplug and Suspend-to-RAM +====================================================== + +How does the regular CPU hotplug code differ from how the Suspend-to-RAM +infrastructure uses it internally? And where do they share common code? Well, a picture is worth a thousand words... So ASCII art follows :-) @@ -16,13 +21,13 @@ of describing where they take different paths and where they share code. What happens when regular CPU hotplug and Suspend-to-RAM race with each other is not depicted here.] -On a high level, the suspend-resume cycle goes like this: +On a high level, the suspend-resume cycle goes like this:: -|Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw | -|tasks | | cpus | | | | cpus | |tasks| + |Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw | + |tasks | | cpus | | | | cpus | |tasks| -More details follow: +More details follow:: Suspend call path ----------------- @@ -87,7 +92,9 @@ More details follow: Resuming back is likewise, with the counterparts being (in the order of execution during resume): -* enable_nonboot_cpus() which involves: + +* enable_nonboot_cpus() which involves:: + | Acquire cpu_add_remove_lock | Decrease cpu_hotplug_disabled, thereby enabling regular cpu hotplug | Call _cpu_up() [for all those cpus in the frozen_cpus mask, in a loop] @@ -103,6 +110,8 @@ It is to be noted here that the system_transition_mutex lock is acquired at the beginning, when we are just starting out to suspend, and then released only after the entire cycle is complete (i.e., suspend + resume). +:: + Regular CPU hotplug call path @@ -152,16 +161,16 @@ with the 'tasks_frozen' argument set to 1. Important files and functions/entry points: ------------------------------------------- +------------------------------------------- -kernel/power/process.c : freeze_processes(), thaw_processes() -kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish() -kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus() +- kernel/power/process.c : freeze_processes(), thaw_processes() +- kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish() +- kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus() II. What are the issues involved in CPU hotplug? - ------------------------------------------- +------------------------------------------------ There are some interesting situations involving CPU hotplug and microcode update on the CPUs, as discussed below: @@ -243,8 +252,11 @@ d. Handling microcode update during suspend/hibernate: cycles). -III. Are there any known problems when regular CPU hotplug and suspend race - with each other? +III. Known problems +=================== + +Are there any known problems when regular CPU hotplug and suspend race +with each other? Yes, they are listed below: diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.rst index 8afb29a8604a..4cda6617709a 100644 --- a/Documentation/power/suspend-and-interrupts.txt +++ b/Documentation/power/suspend-and-interrupts.rst @@ -1,4 +1,6 @@ +==================================== System Suspend and Device Interrupts +==================================== Copyright (C) 2014 Intel Corp. Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> diff --git a/Documentation/power/swsusp-and-swap-files.txt b/Documentation/power/swsusp-and-swap-files.rst index f281886de490..a33a2919dbe4 100644 --- a/Documentation/power/swsusp-and-swap-files.txt +++ b/Documentation/power/swsusp-and-swap-files.rst @@ -1,4 +1,7 @@ +=============================================== Using swap files with software suspend (swsusp) +=============================================== + (C) 2006 Rafael J. Wysocki <rjw@sisk.pl> The Linux kernel handles swap files almost in the same way as it handles swap @@ -21,20 +24,20 @@ units. In order to use a swap file with swsusp, you need to: -1) Create the swap file and make it active, eg. +1) Create the swap file and make it active, eg.:: -# dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k> -# mkswap <swap_file_path> -# swapon <swap_file_path> + # dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k> + # mkswap <swap_file_path> + # swapon <swap_file_path> 2) Use an application that will bmap the swap file with the help of the FIBMAP ioctl and determine the location of the file's swap header, as the offset, in <PAGE_SIZE> units, from the beginning of the partition which holds the swap file. -3) Add the following parameters to the kernel command line: +3) Add the following parameters to the kernel command line:: -resume=<swap_file_partition> resume_offset=<swap_file_offset> + resume=<swap_file_partition> resume_offset=<swap_file_offset> where <swap_file_partition> is the partition on which the swap file is located and <swap_file_offset> is the offset of the swap header determined by the @@ -46,7 +49,7 @@ OR Use a userland suspend application that will set the partition and offset with the help of the SNAPSHOT_SET_SWAP_AREA ioctl described in -Documentation/power/userland-swsusp.txt (this is the only method to suspend +Documentation/power/userland-swsusp.rst (this is the only method to suspend to a swap file allowing the resume to be initiated from an initrd or initramfs image). diff --git a/Documentation/power/swsusp-dmcrypt.txt b/Documentation/power/swsusp-dmcrypt.rst index b802fbfd95ef..426df59172cd 100644 --- a/Documentation/power/swsusp-dmcrypt.txt +++ b/Documentation/power/swsusp-dmcrypt.rst @@ -1,13 +1,15 @@ +======================================= +How to use dm-crypt and swsusp together +======================================= + Author: Andreas Steinmetz <ast@domdv.de> -How to use dm-crypt and swsusp together: -======================================== Some prerequisites: You know how dm-crypt works. If not, visit the following web page: http://www.saout.de/misc/dm-crypt/ -You have read Documentation/power/swsusp.txt and understand it. +You have read Documentation/power/swsusp.rst and understand it. You did read Documentation/admin-guide/initrd.rst and know how an initrd works. You know how to create or how to modify an initrd. @@ -29,23 +31,23 @@ a way that the swap device you suspend to/resume from has always the same major/minor within the initrd as well as within your running system. The easiest way to achieve this is to always set up this swap device first with dmsetup, so that -it will always look like the following: +it will always look like the following:: -brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0 + brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0 Now set up your kernel to use /dev/mapper/swap0 as the default -resume partition, so your kernel .config contains: +resume partition, so your kernel .config contains:: -CONFIG_PM_STD_PARTITION="/dev/mapper/swap0" + CONFIG_PM_STD_PARTITION="/dev/mapper/swap0" Prepare your boot loader to use the initrd you will create or modify. For lilo the simplest setup looks like the following -lines: +lines:: -image=/boot/vmlinuz -initrd=/boot/initrd.gz -label=linux -append="root=/dev/ram0 init=/linuxrc rw" + image=/boot/vmlinuz + initrd=/boot/initrd.gz + label=linux + append="root=/dev/ram0 init=/linuxrc rw" Finally you need to create or modify your initrd. Lets assume you create an initrd that reads the required dm-crypt setup @@ -53,66 +55,66 @@ from a pcmcia flash disk card. The card is formatted with an ext2 fs which resides on /dev/hde1 when the card is inserted. The card contains at least the encrypted swap setup in a file named "swapkey". /etc/fstab of your initrd contains something -like the following: +like the following:: -/dev/hda1 /mnt ext3 ro 0 0 -none /proc proc defaults,noatime,nodiratime 0 0 -none /sys sysfs defaults,noatime,nodiratime 0 0 + /dev/hda1 /mnt ext3 ro 0 0 + none /proc proc defaults,noatime,nodiratime 0 0 + none /sys sysfs defaults,noatime,nodiratime 0 0 /dev/hda1 contains an unencrypted mini system that sets up all of your crypto devices, again by reading the setup from the pcmcia flash disk. What follows now is a /linuxrc for your initrd that allows you to resume from encrypted swap and that continues boot with your mini system on /dev/hda1 if resume -does not happen: - -#!/bin/sh -PATH=/sbin:/bin:/usr/sbin:/usr/bin -mount /proc -mount /sys -mapped=0 -noresume=`grep -c noresume /proc/cmdline` -if [ "$*" != "" ] -then - noresume=1 -fi -dmesg -n 1 -/sbin/cardmgr -q -for i in 1 2 3 4 5 6 7 8 9 0 -do - if [ -f /proc/ide/hde/media ] +does not happen:: + + #!/bin/sh + PATH=/sbin:/bin:/usr/sbin:/usr/bin + mount /proc + mount /sys + mapped=0 + noresume=`grep -c noresume /proc/cmdline` + if [ "$*" != "" ] then - usleep 500000 - mount -t ext2 -o ro /dev/hde1 /mnt - if [ -f /mnt/swapkey ] + noresume=1 + fi + dmesg -n 1 + /sbin/cardmgr -q + for i in 1 2 3 4 5 6 7 8 9 0 + do + if [ -f /proc/ide/hde/media ] then - dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1 + usleep 500000 + mount -t ext2 -o ro /dev/hde1 /mnt + if [ -f /mnt/swapkey ] + then + dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1 + fi + umount /mnt + break fi - umount /mnt - break - fi - usleep 500000 -done -killproc /sbin/cardmgr -dmesg -n 6 -if [ $mapped = 1 ] -then - if [ $noresume != 0 ] + usleep 500000 + done + killproc /sbin/cardmgr + dmesg -n 6 + if [ $mapped = 1 ] then - mkswap /dev/mapper/swap0 > /dev/null 2>&1 + if [ $noresume != 0 ] + then + mkswap /dev/mapper/swap0 > /dev/null 2>&1 + fi + echo 254:0 > /sys/power/resume + dmsetup remove swap0 fi - echo 254:0 > /sys/power/resume - dmsetup remove swap0 -fi -umount /sys -mount /mnt -umount /proc -cd /mnt -pivot_root . mnt -mount /proc -umount -l /mnt -umount /proc -exec chroot . /sbin/init $* < dev/console > dev/console 2>&1 + umount /sys + mount /mnt + umount /proc + cd /mnt + pivot_root . mnt + mount /proc + umount -l /mnt + umount /proc + exec chroot . /sbin/init $* < dev/console > dev/console 2>&1 Please don't mind the weird loop above, busybox's msh doesn't know the let statement. Now, what is happening in the script? diff --git a/Documentation/power/swsusp.rst b/Documentation/power/swsusp.rst new file mode 100644 index 000000000000..d000312f6965 --- /dev/null +++ b/Documentation/power/swsusp.rst @@ -0,0 +1,501 @@ +============ +Swap suspend +============ + +Some warnings, first. + +.. warning:: + + **BIG FAT WARNING** + + If you touch anything on disk between suspend and resume... + ...kiss your data goodbye. + + If you do resume from initrd after your filesystems are mounted... + ...bye bye root partition. + + [this is actually same case as above] + + If you have unsupported ( ) devices using DMA, you may have some + problems. If your disk driver does not support suspend... (IDE does), + it may cause some problems, too. If you change kernel command line + between suspend and resume, it may do something wrong. If you change + your hardware while system is suspended... well, it was not good idea; + but it will probably only crash. + + ( ) suspend/resume support is needed to make it safe. + + If you have any filesystems on USB devices mounted before software suspend, + they won't be accessible after resume and you may lose data, as though + you have unplugged the USB devices with mounted filesystems on them; + see the FAQ below for details. (This is not true for more traditional + power states like "standby", which normally don't turn USB off.) + +Swap partition: + You need to append resume=/dev/your_swap_partition to kernel command + line or specify it using /sys/power/resume. + +Swap file: + If using a swapfile you can also specify a resume offset using + resume_offset=<number> on the kernel command line or specify it + in /sys/power/resume_offset. + +After preparing then you suspend by:: + + echo shutdown > /sys/power/disk; echo disk > /sys/power/state + +- If you feel ACPI works pretty well on your system, you might try:: + + echo platform > /sys/power/disk; echo disk > /sys/power/state + +- If you would like to write hibernation image to swap and then suspend + to RAM (provided your platform supports it), you can try:: + + echo suspend > /sys/power/disk; echo disk > /sys/power/state + +- If you have SATA disks, you'll need recent kernels with SATA suspend + support. For suspend and resume to work, make sure your disk drivers + are built into kernel -- not modules. [There's way to make + suspend/resume with modular disk drivers, see FAQ, but you probably + should not do that.] + +If you want to limit the suspend image size to N bytes, do:: + + echo N > /sys/power/image_size + +before suspend (it is limited to around 2/5 of available RAM by default). + +- The resume process checks for the presence of the resume device, + if found, it then checks the contents for the hibernation image signature. + If both are found, it resumes the hibernation image. + +- The resume process may be triggered in two ways: + + 1) During lateinit: If resume=/dev/your_swap_partition is specified on + the kernel command line, lateinit runs the resume process. If the + resume device has not been probed yet, the resume process fails and + bootup continues. + 2) Manually from an initrd or initramfs: May be run from + the init script by using the /sys/power/resume file. It is vital + that this be done prior to remounting any filesystems (even as + read-only) otherwise data may be corrupted. + +Article about goals and implementation of Software Suspend for Linux +==================================================================== + +Author: Gábor Kuti +Last revised: 2003-10-20 by Pavel Machek + +Idea and goals to achieve +------------------------- + +Nowadays it is common in several laptops that they have a suspend button. It +saves the state of the machine to a filesystem or to a partition and switches +to standby mode. Later resuming the machine the saved state is loaded back to +ram and the machine can continue its work. It has two real benefits. First we +save ourselves the time machine goes down and later boots up, energy costs +are real high when running from batteries. The other gain is that we don't have +to interrupt our programs so processes that are calculating something for a long +time shouldn't need to be written interruptible. + +swsusp saves the state of the machine into active swaps and then reboots or +powerdowns. You must explicitly specify the swap partition to resume from with +`resume=` kernel option. If signature is found it loads and restores saved +state. If the option `noresume` is specified as a boot parameter, it skips +the resuming. If the option `hibernate=nocompress` is specified as a boot +parameter, it saves hibernation image without compression. + +In the meantime while the system is suspended you should not add/remove any +of the hardware, write to the filesystems, etc. + +Sleep states summary +==================== + +There are three different interfaces you can use, /proc/acpi should +work like this: + +In a really perfect world:: + + echo 1 > /proc/acpi/sleep # for standby + echo 2 > /proc/acpi/sleep # for suspend to ram + echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative + echo 4 > /proc/acpi/sleep # for suspend to disk + echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system + +and perhaps:: + + echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios + +Frequently Asked Questions +========================== + +Q: + well, suspending a server is IMHO a really stupid thing, + but... (Diego Zuccato): + +A: + You bought new UPS for your server. How do you install it without + bringing machine down? Suspend to disk, rearrange power cables, + resume. + + You have your server on UPS. Power died, and UPS is indicating 30 + seconds to failure. What do you do? Suspend to disk. + + +Q: + Maybe I'm missing something, but why don't the regular I/O paths work? + +A: + We do use the regular I/O paths. However we cannot restore the data + to its original location as we load it. That would create an + inconsistent kernel state which would certainly result in an oops. + Instead, we load the image into unused memory and then atomically copy + it back to it original location. This implies, of course, a maximum + image size of half the amount of memory. + + There are two solutions to this: + + * require half of memory to be free during suspend. That way you can + read "new" data onto free spots, then cli and copy + + * assume we had special "polling" ide driver that only uses memory + between 0-640KB. That way, I'd have to make sure that 0-640KB is free + during suspending, but otherwise it would work... + + suspend2 shares this fundamental limitation, but does not include user + data and disk caches into "used memory" by saving them in + advance. That means that the limitation goes away in practice. + +Q: + Does linux support ACPI S4? + +A: + Yes. That's what echo platform > /sys/power/disk does. + +Q: + What is 'suspend2'? + +A: + suspend2 is 'Software Suspend 2', a forked implementation of + suspend-to-disk which is available as separate patches for 2.4 and 2.6 + kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB + highmem and preemption. It also has a extensible architecture that + allows for arbitrary transformations on the image (compression, + encryption) and arbitrary backends for writing the image (eg to swap + or an NFS share[Work In Progress]). Questions regarding suspend2 + should be sent to the mailing list available through the suspend2 + website, and not to the Linux Kernel Mailing List. We are working + toward merging suspend2 into the mainline kernel. + +Q: + What is the freezing of tasks and why are we using it? + +A: + The freezing of tasks is a mechanism by which user space processes and some + kernel threads are controlled during hibernation or system-wide suspend (on some + architectures). See freezing-of-tasks.txt for details. + +Q: + What is the difference between "platform" and "shutdown"? + +A: + shutdown: + save state in linux, then tell bios to powerdown + + platform: + save state in linux, then tell bios to powerdown and blink + "suspended led" + + "platform" is actually right thing to do where supported, but + "shutdown" is most reliable (except on ACPI systems). + +Q: + I do not understand why you have such strong objections to idea of + selective suspend. + +A: + Do selective suspend during runtime power management, that's okay. But + it's useless for suspend-to-disk. (And I do not see how you could use + it for suspend-to-ram, I hope you do not want that). + + Lets see, so you suggest to + + * SUSPEND all but swap device and parents + * Snapshot + * Write image to disk + * SUSPEND swap device and parents + * Powerdown + + Oh no, that does not work, if swap device or its parents uses DMA, + you've corrupted data. You'd have to do + + * SUSPEND all but swap device and parents + * FREEZE swap device and parents + * Snapshot + * UNFREEZE swap device and parents + * Write + * SUSPEND swap device and parents + + Which means that you still need that FREEZE state, and you get more + complicated code. (And I have not yet introduce details like system + devices). + +Q: + There don't seem to be any generally useful behavioral + distinctions between SUSPEND and FREEZE. + +A: + Doing SUSPEND when you are asked to do FREEZE is always correct, + but it may be unnecessarily slow. If you want your driver to stay simple, + slowness may not matter to you. It can always be fixed later. + + For devices like disk it does matter, you do not want to spindown for + FREEZE. + +Q: + After resuming, system is paging heavily, leading to very bad interactivity. + +A: + Try running:: + + cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file + do + test -f "$file" && cat "$file" > /dev/null + done + + after resume. swapoff -a; swapon -a may also be useful. + +Q: + What happens to devices during swsusp? They seem to be resumed + during system suspend? + +A: + That's correct. We need to resume them if we want to write image to + disk. Whole sequence goes like + + **Suspend part** + + running system, user asks for suspend-to-disk + + user processes are stopped + + suspend(PMSG_FREEZE): devices are frozen so that they don't interfere + with state snapshot + + state snapshot: copy of whole used memory is taken with interrupts disabled + + resume(): devices are woken up so that we can write image to swap + + write image to swap + + suspend(PMSG_SUSPEND): suspend devices so that we can power off + + turn the power off + + **Resume part** + + (is actually pretty similar) + + running system, user asks for suspend-to-disk + + user processes are stopped (in common case there are none, + but with resume-from-initrd, no one knows) + + read image from disk + + suspend(PMSG_FREEZE): devices are frozen so that they don't interfere + with image restoration + + image restoration: rewrite memory with image + + resume(): devices are woken up so that system can continue + + thaw all user processes + +Q: + What is this 'Encrypt suspend image' for? + +A: + First of all: it is not a replacement for dm-crypt encrypted swap. + It cannot protect your computer while it is suspended. Instead it does + protect from leaking sensitive data after resume from suspend. + + Think of the following: you suspend while an application is running + that keeps sensitive data in memory. The application itself prevents + the data from being swapped out. Suspend, however, must write these + data to swap to be able to resume later on. Without suspend encryption + your sensitive data are then stored in plaintext on disk. This means + that after resume your sensitive data are accessible to all + applications having direct access to the swap device which was used + for suspend. If you don't need swap after resume these data can remain + on disk virtually forever. Thus it can happen that your system gets + broken in weeks later and sensitive data which you thought were + encrypted and protected are retrieved and stolen from the swap device. + To prevent this situation you should use 'Encrypt suspend image'. + + During suspend a temporary key is created and this key is used to + encrypt the data written to disk. When, during resume, the data was + read back into memory the temporary key is destroyed which simply + means that all data written to disk during suspend are then + inaccessible so they can't be stolen later on. The only thing that + you must then take care of is that you call 'mkswap' for the swap + partition used for suspend as early as possible during regular + boot. This asserts that any temporary key from an oopsed suspend or + from a failed or aborted resume is erased from the swap device. + + As a rule of thumb use encrypted swap to protect your data while your + system is shut down or suspended. Additionally use the encrypted + suspend image to prevent sensitive data from being stolen after + resume. + +Q: + Can I suspend to a swap file? + +A: + Generally, yes, you can. However, it requires you to use the "resume=" and + "resume_offset=" kernel command line parameters, so the resume from a swap file + cannot be initiated from an initrd or initramfs image. See + swsusp-and-swap-files.txt for details. + +Q: + Is there a maximum system RAM size that is supported by swsusp? + +A: + It should work okay with highmem. + +Q: + Does swsusp (to disk) use only one swap partition or can it use + multiple swap partitions (aggregate them into one logical space)? + +A: + Only one swap partition, sorry. + +Q: + If my application(s) causes lots of memory & swap space to be used + (over half of the total system RAM), is it correct that it is likely + to be useless to try to suspend to disk while that app is running? + +A: + No, it should work okay, as long as your app does not mlock() + it. Just prepare big enough swap partition. + +Q: + What information is useful for debugging suspend-to-disk problems? + +A: + Well, last messages on the screen are always useful. If something + is broken, it is usually some kernel driver, therefore trying with as + little as possible modules loaded helps a lot. I also prefer people to + suspend from console, preferably without X running. Booting with + init=/bin/bash, then swapon and starting suspend sequence manually + usually does the trick. Then it is good idea to try with latest + vanilla kernel. + +Q: + How can distributions ship a swsusp-supporting kernel with modular + disk drivers (especially SATA)? + +A: + Well, it can be done, load the drivers, then do echo into + /sys/power/resume file from initrd. Be sure not to mount + anything, not even read-only mount, or you are going to lose your + data. + +Q: + How do I make suspend more verbose? + +A: + If you want to see any non-error kernel messages on the virtual + terminal the kernel switches to during suspend, you have to set the + kernel console loglevel to at least 4 (KERN_WARNING), for example by + doing:: + + # save the old loglevel + read LOGLEVEL DUMMY < /proc/sys/kernel/printk + # set the loglevel so we see the progress bar. + # if the level is higher than needed, we leave it alone. + if [ $LOGLEVEL -lt 5 ]; then + echo 5 > /proc/sys/kernel/printk + fi + + IMG_SZ=0 + read IMG_SZ < /sys/power/image_size + echo -n disk > /sys/power/state + RET=$? + # + # the logic here is: + # if image_size > 0 (without kernel support, IMG_SZ will be zero), + # then try again with image_size set to zero. + if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size + echo 0 > /sys/power/image_size + echo -n disk > /sys/power/state + RET=$? + fi + + # restore previous loglevel + echo $LOGLEVEL > /proc/sys/kernel/printk + exit $RET + +Q: + Is this true that if I have a mounted filesystem on a USB device and + I suspend to disk, I can lose data unless the filesystem has been mounted + with "sync"? + +A: + That's right ... if you disconnect that device, you may lose data. + In fact, even with "-o sync" you can lose data if your programs have + information in buffers they haven't written out to a disk you disconnect, + or if you disconnect before the device finished saving data you wrote. + + Software suspend normally powers down USB controllers, which is equivalent + to disconnecting all USB devices attached to your system. + + Your system might well support low-power modes for its USB controllers + while the system is asleep, maintaining the connection, using true sleep + modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the + /sys/power/state file; write "standby" or "mem".) We've not seen any + hardware that can use these modes through software suspend, although in + theory some systems might support "platform" modes that won't break the + USB connections. + + Remember that it's always a bad idea to unplug a disk drive containing a + mounted filesystem. That's true even when your system is asleep! The + safest thing is to unmount all filesystems on removable media (such USB, + Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays) + before suspending; then remount them after resuming. + + There is a work-around for this problem. For more information, see + Documentation/driver-api/usb/persist.rst. + +Q: + Can I suspend-to-disk using a swap partition under LVM? + +A: + Yes and No. You can suspend successfully, but the kernel will not be able + to resume on its own. You need an initramfs that can recognize the resume + situation, activate the logical volume containing the swap volume (but not + touch any filesystems!), and eventually call:: + + echo -n "$major:$minor" > /sys/power/resume + + where $major and $minor are the respective major and minor device numbers of + the swap volume. + + uswsusp works with LVM, too. See http://suspend.sourceforge.net/ + +Q: + I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were + compiled with the similar configuration files. Anyway I found that + suspend to disk (and resume) is much slower on 2.6.16 compared to + 2.6.15. Any idea for why that might happen or how can I speed it up? + +A: + This is because the size of the suspend image is now greater than + for 2.6.15 (by saving more data we can get more responsive system + after resume). + + There's the /sys/power/image_size knob that controls the size of the + image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as + root), the 2.6.15 behavior should be restored. If it is still too + slow, take a look at suspend.sf.net -- userland suspend is faster and + supports LZF compression to speed it up further. diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt deleted file mode 100644 index 236d1fb13640..000000000000 --- a/Documentation/power/swsusp.txt +++ /dev/null @@ -1,446 +0,0 @@ -Some warnings, first. - - * BIG FAT WARNING ********************************************************* - * - * If you touch anything on disk between suspend and resume... - * ...kiss your data goodbye. - * - * If you do resume from initrd after your filesystems are mounted... - * ...bye bye root partition. - * [this is actually same case as above] - * - * If you have unsupported (*) devices using DMA, you may have some - * problems. If your disk driver does not support suspend... (IDE does), - * it may cause some problems, too. If you change kernel command line - * between suspend and resume, it may do something wrong. If you change - * your hardware while system is suspended... well, it was not good idea; - * but it will probably only crash. - * - * (*) suspend/resume support is needed to make it safe. - * - * If you have any filesystems on USB devices mounted before software suspend, - * they won't be accessible after resume and you may lose data, as though - * you have unplugged the USB devices with mounted filesystems on them; - * see the FAQ below for details. (This is not true for more traditional - * power states like "standby", which normally don't turn USB off.) - -Swap partition: -You need to append resume=/dev/your_swap_partition to kernel command -line or specify it using /sys/power/resume. - -Swap file: -If using a swapfile you can also specify a resume offset using -resume_offset=<number> on the kernel command line or specify it -in /sys/power/resume_offset. - -After preparing then you suspend by - -echo shutdown > /sys/power/disk; echo disk > /sys/power/state - -. If you feel ACPI works pretty well on your system, you might try - -echo platform > /sys/power/disk; echo disk > /sys/power/state - -. If you would like to write hibernation image to swap and then suspend -to RAM (provided your platform supports it), you can try - -echo suspend > /sys/power/disk; echo disk > /sys/power/state - -. If you have SATA disks, you'll need recent kernels with SATA suspend -support. For suspend and resume to work, make sure your disk drivers -are built into kernel -- not modules. [There's way to make -suspend/resume with modular disk drivers, see FAQ, but you probably -should not do that.] - -If you want to limit the suspend image size to N bytes, do - -echo N > /sys/power/image_size - -before suspend (it is limited to around 2/5 of available RAM by default). - -. The resume process checks for the presence of the resume device, -if found, it then checks the contents for the hibernation image signature. -If both are found, it resumes the hibernation image. - -. The resume process may be triggered in two ways: - 1) During lateinit: If resume=/dev/your_swap_partition is specified on - the kernel command line, lateinit runs the resume process. If the - resume device has not been probed yet, the resume process fails and - bootup continues. - 2) Manually from an initrd or initramfs: May be run from - the init script by using the /sys/power/resume file. It is vital - that this be done prior to remounting any filesystems (even as - read-only) otherwise data may be corrupted. - -Article about goals and implementation of Software Suspend for Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Author: Gábor Kuti -Last revised: 2003-10-20 by Pavel Machek - -Idea and goals to achieve - -Nowadays it is common in several laptops that they have a suspend button. It -saves the state of the machine to a filesystem or to a partition and switches -to standby mode. Later resuming the machine the saved state is loaded back to -ram and the machine can continue its work. It has two real benefits. First we -save ourselves the time machine goes down and later boots up, energy costs -are real high when running from batteries. The other gain is that we don't have to -interrupt our programs so processes that are calculating something for a long -time shouldn't need to be written interruptible. - -swsusp saves the state of the machine into active swaps and then reboots or -powerdowns. You must explicitly specify the swap partition to resume from with -``resume='' kernel option. If signature is found it loads and restores saved -state. If the option ``noresume'' is specified as a boot parameter, it skips -the resuming. If the option ``hibernate=nocompress'' is specified as a boot -parameter, it saves hibernation image without compression. - -In the meantime while the system is suspended you should not add/remove any -of the hardware, write to the filesystems, etc. - -Sleep states summary -==================== - -There are three different interfaces you can use, /proc/acpi should -work like this: - -In a really perfect world: -echo 1 > /proc/acpi/sleep # for standby -echo 2 > /proc/acpi/sleep # for suspend to ram -echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative -echo 4 > /proc/acpi/sleep # for suspend to disk -echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system - -and perhaps -echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios - -Frequently Asked Questions -========================== - -Q: well, suspending a server is IMHO a really stupid thing, -but... (Diego Zuccato): - -A: You bought new UPS for your server. How do you install it without -bringing machine down? Suspend to disk, rearrange power cables, -resume. - -You have your server on UPS. Power died, and UPS is indicating 30 -seconds to failure. What do you do? Suspend to disk. - - -Q: Maybe I'm missing something, but why don't the regular I/O paths work? - -A: We do use the regular I/O paths. However we cannot restore the data -to its original location as we load it. That would create an -inconsistent kernel state which would certainly result in an oops. -Instead, we load the image into unused memory and then atomically copy -it back to it original location. This implies, of course, a maximum -image size of half the amount of memory. - -There are two solutions to this: - -* require half of memory to be free during suspend. That way you can -read "new" data onto free spots, then cli and copy - -* assume we had special "polling" ide driver that only uses memory -between 0-640KB. That way, I'd have to make sure that 0-640KB is free -during suspending, but otherwise it would work... - -suspend2 shares this fundamental limitation, but does not include user -data and disk caches into "used memory" by saving them in -advance. That means that the limitation goes away in practice. - -Q: Does linux support ACPI S4? - -A: Yes. That's what echo platform > /sys/power/disk does. - -Q: What is 'suspend2'? - -A: suspend2 is 'Software Suspend 2', a forked implementation of -suspend-to-disk which is available as separate patches for 2.4 and 2.6 -kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB -highmem and preemption. It also has a extensible architecture that -allows for arbitrary transformations on the image (compression, -encryption) and arbitrary backends for writing the image (eg to swap -or an NFS share[Work In Progress]). Questions regarding suspend2 -should be sent to the mailing list available through the suspend2 -website, and not to the Linux Kernel Mailing List. We are working -toward merging suspend2 into the mainline kernel. - -Q: What is the freezing of tasks and why are we using it? - -A: The freezing of tasks is a mechanism by which user space processes and some -kernel threads are controlled during hibernation or system-wide suspend (on some -architectures). See freezing-of-tasks.txt for details. - -Q: What is the difference between "platform" and "shutdown"? - -A: - -shutdown: save state in linux, then tell bios to powerdown - -platform: save state in linux, then tell bios to powerdown and blink - "suspended led" - -"platform" is actually right thing to do where supported, but -"shutdown" is most reliable (except on ACPI systems). - -Q: I do not understand why you have such strong objections to idea of -selective suspend. - -A: Do selective suspend during runtime power management, that's okay. But -it's useless for suspend-to-disk. (And I do not see how you could use -it for suspend-to-ram, I hope you do not want that). - -Lets see, so you suggest to - -* SUSPEND all but swap device and parents -* Snapshot -* Write image to disk -* SUSPEND swap device and parents -* Powerdown - -Oh no, that does not work, if swap device or its parents uses DMA, -you've corrupted data. You'd have to do - -* SUSPEND all but swap device and parents -* FREEZE swap device and parents -* Snapshot -* UNFREEZE swap device and parents -* Write -* SUSPEND swap device and parents - -Which means that you still need that FREEZE state, and you get more -complicated code. (And I have not yet introduce details like system -devices). - -Q: There don't seem to be any generally useful behavioral -distinctions between SUSPEND and FREEZE. - -A: Doing SUSPEND when you are asked to do FREEZE is always correct, -but it may be unnecessarily slow. If you want your driver to stay simple, -slowness may not matter to you. It can always be fixed later. - -For devices like disk it does matter, you do not want to spindown for -FREEZE. - -Q: After resuming, system is paging heavily, leading to very bad interactivity. - -A: Try running - -cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file -do - test -f "$file" && cat "$file" > /dev/null -done - -after resume. swapoff -a; swapon -a may also be useful. - -Q: What happens to devices during swsusp? They seem to be resumed -during system suspend? - -A: That's correct. We need to resume them if we want to write image to -disk. Whole sequence goes like - - Suspend part - ~~~~~~~~~~~~ - running system, user asks for suspend-to-disk - - user processes are stopped - - suspend(PMSG_FREEZE): devices are frozen so that they don't interfere - with state snapshot - - state snapshot: copy of whole used memory is taken with interrupts disabled - - resume(): devices are woken up so that we can write image to swap - - write image to swap - - suspend(PMSG_SUSPEND): suspend devices so that we can power off - - turn the power off - - Resume part - ~~~~~~~~~~~ - (is actually pretty similar) - - running system, user asks for suspend-to-disk - - user processes are stopped (in common case there are none, but with resume-from-initrd, no one knows) - - read image from disk - - suspend(PMSG_FREEZE): devices are frozen so that they don't interfere - with image restoration - - image restoration: rewrite memory with image - - resume(): devices are woken up so that system can continue - - thaw all user processes - -Q: What is this 'Encrypt suspend image' for? - -A: First of all: it is not a replacement for dm-crypt encrypted swap. -It cannot protect your computer while it is suspended. Instead it does -protect from leaking sensitive data after resume from suspend. - -Think of the following: you suspend while an application is running -that keeps sensitive data in memory. The application itself prevents -the data from being swapped out. Suspend, however, must write these -data to swap to be able to resume later on. Without suspend encryption -your sensitive data are then stored in plaintext on disk. This means -that after resume your sensitive data are accessible to all -applications having direct access to the swap device which was used -for suspend. If you don't need swap after resume these data can remain -on disk virtually forever. Thus it can happen that your system gets -broken in weeks later and sensitive data which you thought were -encrypted and protected are retrieved and stolen from the swap device. -To prevent this situation you should use 'Encrypt suspend image'. - -During suspend a temporary key is created and this key is used to -encrypt the data written to disk. When, during resume, the data was -read back into memory the temporary key is destroyed which simply -means that all data written to disk during suspend are then -inaccessible so they can't be stolen later on. The only thing that -you must then take care of is that you call 'mkswap' for the swap -partition used for suspend as early as possible during regular -boot. This asserts that any temporary key from an oopsed suspend or -from a failed or aborted resume is erased from the swap device. - -As a rule of thumb use encrypted swap to protect your data while your -system is shut down or suspended. Additionally use the encrypted -suspend image to prevent sensitive data from being stolen after -resume. - -Q: Can I suspend to a swap file? - -A: Generally, yes, you can. However, it requires you to use the "resume=" and -"resume_offset=" kernel command line parameters, so the resume from a swap file -cannot be initiated from an initrd or initramfs image. See -swsusp-and-swap-files.txt for details. - -Q: Is there a maximum system RAM size that is supported by swsusp? - -A: It should work okay with highmem. - -Q: Does swsusp (to disk) use only one swap partition or can it use -multiple swap partitions (aggregate them into one logical space)? - -A: Only one swap partition, sorry. - -Q: If my application(s) causes lots of memory & swap space to be used -(over half of the total system RAM), is it correct that it is likely -to be useless to try to suspend to disk while that app is running? - -A: No, it should work okay, as long as your app does not mlock() -it. Just prepare big enough swap partition. - -Q: What information is useful for debugging suspend-to-disk problems? - -A: Well, last messages on the screen are always useful. If something -is broken, it is usually some kernel driver, therefore trying with as -little as possible modules loaded helps a lot. I also prefer people to -suspend from console, preferably without X running. Booting with -init=/bin/bash, then swapon and starting suspend sequence manually -usually does the trick. Then it is good idea to try with latest -vanilla kernel. - -Q: How can distributions ship a swsusp-supporting kernel with modular -disk drivers (especially SATA)? - -A: Well, it can be done, load the drivers, then do echo into -/sys/power/resume file from initrd. Be sure not to mount -anything, not even read-only mount, or you are going to lose your -data. - -Q: How do I make suspend more verbose? - -A: If you want to see any non-error kernel messages on the virtual -terminal the kernel switches to during suspend, you have to set the -kernel console loglevel to at least 4 (KERN_WARNING), for example by -doing - - # save the old loglevel - read LOGLEVEL DUMMY < /proc/sys/kernel/printk - # set the loglevel so we see the progress bar. - # if the level is higher than needed, we leave it alone. - if [ $LOGLEVEL -lt 5 ]; then - echo 5 > /proc/sys/kernel/printk - fi - - IMG_SZ=0 - read IMG_SZ < /sys/power/image_size - echo -n disk > /sys/power/state - RET=$? - # - # the logic here is: - # if image_size > 0 (without kernel support, IMG_SZ will be zero), - # then try again with image_size set to zero. - if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size - echo 0 > /sys/power/image_size - echo -n disk > /sys/power/state - RET=$? - fi - - # restore previous loglevel - echo $LOGLEVEL > /proc/sys/kernel/printk - exit $RET - -Q: Is this true that if I have a mounted filesystem on a USB device and -I suspend to disk, I can lose data unless the filesystem has been mounted -with "sync"? - -A: That's right ... if you disconnect that device, you may lose data. -In fact, even with "-o sync" you can lose data if your programs have -information in buffers they haven't written out to a disk you disconnect, -or if you disconnect before the device finished saving data you wrote. - -Software suspend normally powers down USB controllers, which is equivalent -to disconnecting all USB devices attached to your system. - -Your system might well support low-power modes for its USB controllers -while the system is asleep, maintaining the connection, using true sleep -modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the -/sys/power/state file; write "standby" or "mem".) We've not seen any -hardware that can use these modes through software suspend, although in -theory some systems might support "platform" modes that won't break the -USB connections. - -Remember that it's always a bad idea to unplug a disk drive containing a -mounted filesystem. That's true even when your system is asleep! The -safest thing is to unmount all filesystems on removable media (such USB, -Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays) -before suspending; then remount them after resuming. - -There is a work-around for this problem. For more information, see -Documentation/driver-api/usb/persist.rst. - -Q: Can I suspend-to-disk using a swap partition under LVM? - -A: Yes and No. You can suspend successfully, but the kernel will not be able -to resume on its own. You need an initramfs that can recognize the resume -situation, activate the logical volume containing the swap volume (but not -touch any filesystems!), and eventually call - -echo -n "$major:$minor" > /sys/power/resume - -where $major and $minor are the respective major and minor device numbers of -the swap volume. - -uswsusp works with LVM, too. See http://suspend.sourceforge.net/ - -Q: I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were -compiled with the similar configuration files. Anyway I found that -suspend to disk (and resume) is much slower on 2.6.16 compared to -2.6.15. Any idea for why that might happen or how can I speed it up? - -A: This is because the size of the suspend image is now greater than -for 2.6.15 (by saving more data we can get more responsive system -after resume). - -There's the /sys/power/image_size knob that controls the size of the -image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as -root), the 2.6.15 behavior should be restored. If it is still too -slow, take a look at suspend.sf.net -- userland suspend is faster and -supports LZF compression to speed it up further. diff --git a/Documentation/power/tricks.txt b/Documentation/power/tricks.rst index a1b8f7249f4c..ca787f142c3f 100644 --- a/Documentation/power/tricks.txt +++ b/Documentation/power/tricks.rst @@ -1,5 +1,7 @@ - swsusp/S3 tricks - ~~~~~~~~~~~~~~~~ +================ +swsusp/S3 tricks +================ + Pavel Machek <pavel@ucw.cz> If you want to trick swsusp/S3 into working, you might want to try: diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.rst index bbfcd1bbedc5..a0fa51bb1a4d 100644 --- a/Documentation/power/userland-swsusp.txt +++ b/Documentation/power/userland-swsusp.rst @@ -1,4 +1,7 @@ +===================================================== Documentation for userland software suspend interface +===================================================== + (C) 2006 Rafael J. Wysocki <rjw@sisk.pl> First, the warnings at the beginning of swsusp.txt still apply. @@ -30,13 +33,16 @@ called. The ioctl() commands recognized by the device are: -SNAPSHOT_FREEZE - freeze user space processes (the current process is +SNAPSHOT_FREEZE + freeze user space processes (the current process is not frozen); this is required for SNAPSHOT_CREATE_IMAGE and SNAPSHOT_ATOMIC_RESTORE to succeed -SNAPSHOT_UNFREEZE - thaw user space processes frozen by SNAPSHOT_FREEZE +SNAPSHOT_UNFREEZE + thaw user space processes frozen by SNAPSHOT_FREEZE -SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the +SNAPSHOT_CREATE_IMAGE + create a snapshot of the system memory; the last argument of ioctl() should be a pointer to an int variable, the value of which will indicate whether the call returned after creating the snapshot (1) or after restoring the system memory state @@ -45,48 +51,59 @@ SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the has been created the read() operation can be used to transfer it out of the kernel -SNAPSHOT_ATOMIC_RESTORE - restore the system memory state from the +SNAPSHOT_ATOMIC_RESTORE + restore the system memory state from the uploaded snapshot image; before calling it you should transfer the system memory snapshot back to the kernel using the write() operation; this call will not succeed if the snapshot image is not available to the kernel -SNAPSHOT_FREE - free memory allocated for the snapshot image +SNAPSHOT_FREE + free memory allocated for the snapshot image -SNAPSHOT_PREF_IMAGE_SIZE - set the preferred maximum size of the image +SNAPSHOT_PREF_IMAGE_SIZE + set the preferred maximum size of the image (the kernel will do its best to ensure the image size will not exceed this number, but if it turns out to be impossible, the kernel will create the smallest image possible) -SNAPSHOT_GET_IMAGE_SIZE - return the actual size of the hibernation image +SNAPSHOT_GET_IMAGE_SIZE + return the actual size of the hibernation image -SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the +SNAPSHOT_AVAIL_SWAP_SIZE + return the amount of available swap in bytes (the last argument should be a pointer to an unsigned int variable that will contain the result if the call is successful). -SNAPSHOT_ALLOC_SWAP_PAGE - allocate a swap page from the resume partition +SNAPSHOT_ALLOC_SWAP_PAGE + allocate a swap page from the resume partition (the last argument should be a pointer to a loff_t variable that will contain the swap page offset if the call is successful) -SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated by +SNAPSHOT_FREE_SWAP_PAGES + free all swap pages allocated by SNAPSHOT_ALLOC_SWAP_PAGE -SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE> +SNAPSHOT_SET_SWAP_AREA + set the resume partition and the offset (in <PAGE_SIZE> units) from the beginning of the partition at which the swap header is located (the last ioctl() argument should point to a struct resume_swap_area, as defined in kernel/power/suspend_ioctls.h, containing the resume device specification and the offset); for swap partitions the offset is always 0, but it is different from zero for - swap files (see Documentation/power/swsusp-and-swap-files.txt for + swap files (see Documentation/power/swsusp-and-swap-files.rst for details). -SNAPSHOT_PLATFORM_SUPPORT - enable/disable the hibernation platform support, +SNAPSHOT_PLATFORM_SUPPORT + enable/disable the hibernation platform support, depending on the argument value (enable, if the argument is nonzero) -SNAPSHOT_POWER_OFF - make the kernel transition the system to the hibernation +SNAPSHOT_POWER_OFF + make the kernel transition the system to the hibernation state (eg. ACPI S4) using the platform (eg. ACPI) driver -SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to +SNAPSHOT_S2RAM + suspend to RAM; using this call causes the kernel to immediately enter the suspend-to-RAM state, so this call must always be preceded by the SNAPSHOT_FREEZE call and it is also necessary to use the SNAPSHOT_UNFREEZE call after the system wakes up. This call @@ -98,10 +115,11 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: + - you cannot read() more than one virtual memory page at a time - read()s across page boundaries are impossible (ie. if you read() 1/2 of - a page in the previous call, you will only be able to read() - _at_ _most_ 1/2 of the page in the next call) + a page in the previous call, you will only be able to read() + **at most** 1/2 of the page in the next call) The device's write() operation is used for uploading the system memory snapshot into the kernel. It has the same limitations as the read() operation. @@ -143,8 +161,10 @@ preferably using mlockall(), before calling SNAPSHOT_FREEZE. The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE in the memory location pointed to by the last argument of ioctl() and proceed in accordance with it: + 1. If the value is 1 (ie. the system memory snapshot has just been created and the system is ready for saving it): + (a) The suspending utility MUST NOT close the snapshot device _unless_ the whole suspend procedure is to be cancelled, in which case, if the snapshot image has already been saved, the @@ -158,6 +178,7 @@ in accordance with it: called. However, it MAY mount a file system that was not mounted at that time and perform some operations on it (eg. use it for saving the image). + 2. If the value is 0 (ie. the system state has just been restored from the snapshot image), the suspending utility MUST close the snapshot device. Afterwards it will be treated as a regular userland process, diff --git a/Documentation/power/video.txt b/Documentation/power/video.rst index 3e6272bc4472..337a2ba9f32f 100644 --- a/Documentation/power/video.txt +++ b/Documentation/power/video.rst @@ -1,7 +1,8 @@ +=========================== +Video issues with S3 resume +=========================== - Video issues with S3 resume - ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 2003-2006, Pavel Machek +2003-2006, Pavel Machek During S3 resume, hardware needs to be reinitialized. For most devices, this is easy, and kernel driver knows how to do @@ -41,37 +42,37 @@ There are a few types of systems where video works after S3 resume: (1) systems where video state is preserved over S3. (2) systems where it is possible to call the video BIOS during S3 - resume. Unfortunately, it is not correct to call the video BIOS at - that point, but it happens to work on some machines. Use - acpi_sleep=s3_bios. + resume. Unfortunately, it is not correct to call the video BIOS at + that point, but it happens to work on some machines. Use + acpi_sleep=s3_bios. (3) systems that initialize video card into vga text mode and where - the BIOS works well enough to be able to set video mode. Use - acpi_sleep=s3_mode on these. + the BIOS works well enough to be able to set video mode. Use + acpi_sleep=s3_mode on these. (4) on some systems s3_bios kicks video into text mode, and - acpi_sleep=s3_bios,s3_mode is needed. + acpi_sleep=s3_bios,s3_mode is needed. (5) radeon systems, where X can soft-boot your video card. You'll need - a new enough X, and a plain text console (no vesafb or radeonfb). See - http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information. - Alternatively, you should use vbetool (6) instead. + a new enough X, and a plain text console (no vesafb or radeonfb). See + http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information. + Alternatively, you should use vbetool (6) instead. (6) other radeon systems, where vbetool is enough to bring system back - to life. It needs text console to be working. Do vbetool vbestate - save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool - vbestate restore < /tmp/delme; setfont <whatever>, and your video - should work. + to life. It needs text console to be working. Do vbetool vbestate + save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool + vbestate restore < /tmp/delme; setfont <whatever>, and your video + should work. (7) on some systems, it is possible to boot most of kernel, and then - POSTing bios works. Ole Rohne has patch to do just that at - http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2. + POSTing bios works. Ole Rohne has patch to do just that at + http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2. -(8) on some systems, you can use the video_post utility and or - do echo 3 > /sys/power/state && /usr/sbin/video_post - which will - initialize the display in console mode. If you are in X, you can switch - to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get - the display working in graphical mode again. +(8) on some systems, you can use the video_post utility and or + do echo 3 > /sys/power/state && /usr/sbin/video_post - which will + initialize the display in console mode. If you are in X, you can switch + to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get + the display working in graphical mode again. Now, if you pass acpi_sleep=something, and it does not work with your bios, you'll get a hard crash during resume. Be careful. Also it is @@ -87,99 +88,126 @@ chance of working. Table of known working notebooks: + +=============================== =============================================== Model hack (or "how to do it") ------------------------------------------------------------------------------- +=============================== =============================================== Acer Aspire 1406LC ole's late BIOS init (7), turn off DRI Acer TM 230 s3_bios (2) Acer TM 242FX vbetool (6) Acer TM C110 video_post (8) -Acer TM C300 vga=normal (only suspend on console, not in X), vbetool (6) or video_post (8) +Acer TM C300 vga=normal (only suspend on console, not in X), + vbetool (6) or video_post (8) Acer TM 4052LCi s3_bios (2) Acer TM 636Lci s3_bios,s3_mode (4) -Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text console back -Acer TM 660 ??? (*) -Acer TM 800 vga=normal, X patches, see webpage (5) or vbetool (6) -Acer TM 803 vga=normal, X patches, see webpage (5) or vbetool (6) +Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text + console back +Acer TM 660 ??? [#f1]_ +Acer TM 800 vga=normal, X patches, see webpage (5) + or vbetool (6) +Acer TM 803 vga=normal, X patches, see webpage (5) + or vbetool (6) Acer TM 803LCi vga=normal, vbetool (6) Arima W730a vbetool needed (6) -Asus L2400D s3_mode (3)(***) (S1 also works OK) +Asus L2400D s3_mode (3) [#f2]_ (S1 also works OK) Asus L3350M (SiS 740) (6) Asus L3800C (Radeon M7) s3_bios (2) (S1 also works OK) -Asus M6887Ne vga=normal, s3_bios (2), use radeon driver instead of fglrx in x.org +Asus M6887Ne vga=normal, s3_bios (2), use radeon driver + instead of fglrx in x.org Athlon64 desktop prototype s3_bios (2) -Compal CL-50 ??? (*) +Compal CL-50 ??? [#f1]_ Compaq Armada E500 - P3-700 none (1) (S1 also works OK) Compaq Evo N620c vga=normal, s3_bios (2) Dell 600m, ATI R250 Lf none (1), but needs xorg-x11-6.8.1.902-1 Dell D600, ATI RV250 vga=normal and X, or try vbestate (6) -Dell D610 vga=normal and X (possibly vbestate (6) too, but not tested) -Dell Inspiron 4000 ??? (*) -Dell Inspiron 500m ??? (*) +Dell D610 vga=normal and X (possibly vbestate (6) too, + but not tested) +Dell Inspiron 4000 ??? [#f1]_ +Dell Inspiron 500m ??? [#f1]_ Dell Inspiron 510m ??? Dell Inspiron 5150 vbetool needed (6) -Dell Inspiron 600m ??? (*) -Dell Inspiron 8200 ??? (*) -Dell Inspiron 8500 ??? (*) -Dell Inspiron 8600 ??? (*) -eMachines athlon64 machines vbetool needed (6) (someone please get me model #s) -HP NC6000 s3_bios, may not use radeonfb (2); or vbetool (6) -HP NX7000 ??? (*) -HP Pavilion ZD7000 vbetool post needed, need open-source nv driver for X +Dell Inspiron 600m ??? [#f1]_ +Dell Inspiron 8200 ??? [#f1]_ +Dell Inspiron 8500 ??? [#f1]_ +Dell Inspiron 8600 ??? [#f1]_ +eMachines athlon64 machines vbetool needed (6) (someone please get + me model #s) +HP NC6000 s3_bios, may not use radeonfb (2); + or vbetool (6) +HP NX7000 ??? [#f1]_ +HP Pavilion ZD7000 vbetool post needed, need open-source nv + driver for X HP Omnibook XE3 athlon version none (1) HP Omnibook XE3GC none (1), video is S3 Savage/IX-MV HP Omnibook XE3L-GF vbetool (6) HP Omnibook 5150 none (1), (S1 also works OK) -IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294 Savage/IX-MV, vesafb gets "interesting" but X work. -IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with BIOS 1.04 2002-08-23, but not at all with BIOS 1.11 2004-11-05 :-(] +IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294 + Savage/IX-MV, vesafb gets "interesting" + but X work. +IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with + BIOS 1.04 2002-08-23, but not at all with + BIOS 1.11 2004-11-05 :-(] IBM TP R32 / Type 2658-MMG none (1) -IBM TP R40 2722B3G ??? (*) +IBM TP R40 2722B3G ??? [#f1]_ IBM TP R50p / Type 1832-22U s3_bios (2) IBM TP R51 none (1) -IBM TP T30 236681A ??? (*) +IBM TP T30 236681A ??? [#f1]_ IBM TP T40 / Type 2373-MU4 none (1) IBM TP T40p none (1) IBM TP R40p s3_bios (2) IBM TP T41p s3_bios (2), switch to X after resume IBM TP T42 s3_bios (2) IBM ThinkPad T42p (2373-GTG) s3_bios (2) -IBM TP X20 ??? (*) +IBM TP X20 ??? [#f1]_ IBM TP X30 s3_bios, s3_mode (4) -IBM TP X31 / Type 2672-XXH none (1), use radeontool (http://fdd.com/software/radeon/) to turn off backlight. -IBM TP X32 none (1), but backlight is on and video is trashed after long suspend. s3_bios,s3_mode (4) works too. Perhaps that gets better results? +IBM TP X31 / Type 2672-XXH none (1), use radeontool + (http://fdd.com/software/radeon/) to + turn off backlight. +IBM TP X32 none (1), but backlight is on and video is + trashed after long suspend. s3_bios, + s3_mode (4) works too. Perhaps that gets + better results? IBM Thinkpad X40 Type 2371-7JG s3_bios,s3_mode (4) -IBM TP 600e none(1), but a switch to console and back to X is needed -Medion MD4220 ??? (*) +IBM TP 600e none(1), but a switch to console and + back to X is needed +Medion MD4220 ??? [#f1]_ Samsung P35 vbetool needed (6) Sharp PC-AR10 (ATI rage) none (1), backlight does not switch off Sony Vaio PCG-C1VRX/K s3_bios (2) -Sony Vaio PCG-F403 ??? (*) +Sony Vaio PCG-F403 ??? [#f1]_ Sony Vaio PCG-GRT995MP none (1), works with 'nv' X driver -Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use radeontool (http://fdd.com/software/radeon/) to turn off backlight. -Sony Vaio PCG-N505SN ??? (*) +Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use + radeontool (http://fdd.com/software/radeon/) + to turn off backlight. +Sony Vaio PCG-N505SN ??? [#f1]_ Sony Vaio vgn-s260 X or boot-radeon can init it (5) -Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will be blank unless you return to X. +Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will + be blank unless you return to X. Sony Vaio vgn-FS115B s3_bios (2),s3_mode (4) Toshiba Libretto L5 none (1) Toshiba Libretto 100CT/110CT vbetool (6) Toshiba Portege 3020CT s3_mode (3) Toshiba Satellite 4030CDT s3_mode (3) (S1 also works OK) Toshiba Satellite 4080XCDT s3_mode (3) (S1 also works OK) -Toshiba Satellite 4090XCDT ??? (*) -Toshiba Satellite P10-554 s3_bios,s3_mode (4)(****) +Toshiba Satellite 4090XCDT ??? [#f1]_ +Toshiba Satellite P10-554 s3_bios,s3_mode (4)[#f3]_ Toshiba M30 (2) xor X with nvidia driver using internal AGP -Uniwill 244IIO ??? (*) +Uniwill 244IIO ??? [#f1]_ +=============================== =============================================== Known working desktop systems ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=================== ============================= ======================== Mainboard Graphics card hack (or "how to do it") ------------------------------------------------------------------------------- +=================== ============================= ======================== Asus A7V8X nVidia RIVA TNT2 model 64 s3_bios,s3_mode (4) +=================== ============================= ======================== -(*) from https://wiki.ubuntu.com/HoaryPMResults, not sure - which options to use. If you know, please tell me. +.. [#f1] from https://wiki.ubuntu.com/HoaryPMResults, not sure + which options to use. If you know, please tell me. -(***) To be tested with a newer kernel. +.. [#f2] To be tested with a newer kernel. -(****) Not with SMP kernel, UP only. +.. [#f3] Not with SMP kernel, UP only. diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt index 0c41d6d463f3..10e7f4d16c14 100644 --- a/Documentation/powerpc/firmware-assisted-dump.txt +++ b/Documentation/powerpc/firmware-assisted-dump.txt @@ -59,7 +59,7 @@ as follows: the default calculated size. Use this option if default boot memory size is not sufficient for second kernel to boot successfully. For syntax of crashkernel= parameter, - refer to Documentation/kdump/kdump.rst. If any offset is + refer to Documentation/admin-guide/kdump/kdump.rst. If any offset is provided in crashkernel= parameter, it will be ignored as fadump uses a predefined offset to reserve memory for boot memory dump preservation in case of a crash. diff --git a/Documentation/powerpc/vcpudispatch_stats.txt b/Documentation/powerpc/vcpudispatch_stats.txt new file mode 100644 index 000000000000..e21476bfd78c --- /dev/null +++ b/Documentation/powerpc/vcpudispatch_stats.txt @@ -0,0 +1,68 @@ +VCPU Dispatch Statistics: +========================= + +For Shared Processor LPARs, the POWER Hypervisor maintains a relatively +static mapping of the LPAR processors (vcpus) to physical processor +chips (representing the "home" node) and tries to always dispatch vcpus +on their associated physical processor chip. However, under certain +scenarios, vcpus may be dispatched on a different processor chip (away +from its home node). + +/proc/powerpc/vcpudispatch_stats can be used to obtain statistics +related to the vcpu dispatch behavior. Writing '1' to this file enables +collecting the statistics, while writing '0' disables the statistics. +By default, the DTLB log for each vcpu is processed 50 times a second so +as not to miss any entries. This processing frequency can be changed +through /proc/powerpc/vcpudispatch_stats_freq. + +The statistics themselves are available by reading the procfs file +/proc/powerpc/vcpudispatch_stats. Each line in the output corresponds to +a vcpu as represented by the first field, followed by 8 numbers. + +The first number corresponds to: +1. total vcpu dispatches since the beginning of statistics collection + +The next 4 numbers represent vcpu dispatch dispersions: +2. number of times this vcpu was dispatched on the same processor as last + time +3. number of times this vcpu was dispatched on a different processor core + as last time, but within the same chip +4. number of times this vcpu was dispatched on a different chip +5. number of times this vcpu was dispatches on a different socket/drawer +(next numa boundary) + +The final 3 numbers represent statistics in relation to the home node of +the vcpu: +6. number of times this vcpu was dispatched in its home node (chip) +7. number of times this vcpu was dispatched in a different node +8. number of times this vcpu was dispatched in a node further away (numa +distance) + +An example output: + $ sudo cat /proc/powerpc/vcpudispatch_stats + cpu0 6839 4126 2683 30 0 6821 18 0 + cpu1 2515 1274 1229 12 0 2509 6 0 + cpu2 2317 1198 1109 10 0 2312 5 0 + cpu3 2259 1165 1088 6 0 2256 3 0 + cpu4 2205 1143 1056 6 0 2202 3 0 + cpu5 2165 1121 1038 6 0 2162 3 0 + cpu6 2183 1127 1050 6 0 2180 3 0 + cpu7 2193 1133 1052 8 0 2187 6 0 + cpu8 2165 1115 1032 18 0 2156 9 0 + cpu9 2301 1252 1033 16 0 2293 8 0 + cpu10 2197 1138 1041 18 0 2187 10 0 + cpu11 2273 1185 1062 26 0 2260 13 0 + cpu12 2186 1125 1043 18 0 2177 9 0 + cpu13 2161 1115 1030 16 0 2153 8 0 + cpu14 2206 1153 1033 20 0 2196 10 0 + cpu15 2163 1115 1032 16 0 2155 8 0 + +In the output above, for vcpu0, there have been 6839 dispatches since +statistics were enabled. 4126 of those dispatches were on the same +physical cpu as the last time. 2683 were on a different core, but within +the same chip, while 30 dispatches were on a different chip compared to +its last dispatch. + +Also, out of the total of 6839 dispatches, we see that there have been +6821 dispatches on the vcpu's home node, while 18 dispatches were +outside its home node, on a neighbouring chip. diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 365efc9e4aa8..8e56337d422d 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -107,7 +107,7 @@ and elsewhere regarding submitting Linux kernel patches. and why. 26) If any ioctl's are added by the patch, then also update - ``Documentation/ioctl/ioctl-number.txt``. + ``Documentation/ioctl/ioctl-number.rst``. 27) If your modified source code depends on or uses any of the kernel APIs or features that are related to the following ``Kconfig`` symbols, diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 58bc047e7b95..1acaa14903d6 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -117,7 +117,7 @@ PM support: implemented") error. You should also try to make sure that your driver uses as little power as possible when it's not doing anything. For the driver testing instructions see - Documentation/power/drivers-testing.txt and for a relatively + Documentation/power/drivers-testing.rst and for a relatively complete overview of the power management issues related to drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`. diff --git a/Documentation/pti/pti_intel_mid.txt b/Documentation/pti/pti_intel_mid.txt deleted file mode 100644 index e7a5b6d1f7a9..000000000000 --- a/Documentation/pti/pti_intel_mid.txt +++ /dev/null @@ -1,99 +0,0 @@ -The Intel MID PTI project is HW implemented in Intel Atom -system-on-a-chip designs based on the Parallel Trace -Interface for MIPI P1149.7 cJTAG standard. The kernel solution -for this platform involves the following files: - -./include/linux/pti.h -./drivers/.../n_tracesink.h -./drivers/.../n_tracerouter.c -./drivers/.../n_tracesink.c -./drivers/.../pti.c - -pti.c is the driver that enables various debugging features -popular on platforms from certain mobile manufacturers. -n_tracerouter.c and n_tracesink.c allow extra system information to -be collected and routed to the pti driver, such as trace -debugging data from a modem. Although n_tracerouter -and n_tracesink are a part of the complete PTI solution, -these two line disciplines can work separately from -pti.c and route any data stream from one /dev/tty node -to another /dev/tty node via kernel-space. This provides -a stable, reliable connection that will not break unless -the user-space application shuts down (plus avoids -kernel->user->kernel context switch overheads of routing -data). - -An example debugging usage for this driver system: - *Hook /dev/ttyPTI0 to syslogd. Opening this port will also start - a console device to further capture debugging messages to PTI. - *Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW. - This is where n_tracerouter and n_tracesink are used. - *Hook /dev/pti to a user-level debugging application for writing - to PTI HW. - *Use mipi_* Kernel Driver API in other device drivers for - debugging to PTI by first requesting a PTI write address via - mipi_request_masterchannel(1). - -Below is example pseudo-code on how a 'privileged' application -can hook up n_tracerouter and n_tracesink to any tty on -a system. 'Privileged' means the application has enough -privileges to successfully manipulate the ldisc drivers -but is not just blindly executing as 'root'. Keep in mind -the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter -and n_tracesink line discpline drivers but is a generic -operation for a program to use a line discpline driver -on a tty port other than the default n_tty. - -/////////// To hook up n_tracerouter and n_tracesink ///////// - -// Note that n_tracerouter depends on n_tracesink. -#include <errno.h> -#define ONE_TTY "/dev/ttyOne" -#define TWO_TTY "/dev/ttyTwo" - -// needed global to hand onto ldisc connection -static int g_fd_source = -1; -static int g_fd_sink = -1; - -// these two vars used to grab LDISC values from loaded ldisc drivers -// in OS. Look at /proc/tty/ldiscs to get the right numbers from -// the ldiscs loaded in the system. -int source_ldisc_num, sink_ldisc_num = -1; -int retval; - -g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W -g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W - -if (g_fd_source <= 0) || (g_fd_sink <= 0) { - // doubt you'll want to use these exact error lines of code - printf("Error on open(). errno: %d\n",errno); - return errno; -} - -retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num); -if (retval < 0) { - printf("Error on ioctl(). errno: %d\n", errno); - return errno; -} - -retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num); -if (retval < 0) { - printf("Error on ioctl(). errno: %d\n", errno); - return errno; -} - -/////////// To disconnect n_tracerouter and n_tracesink //////// - -// First make sure data through the ldiscs has stopped. - -// Second, disconnect ldiscs. This provides a -// little cleaner shutdown on tty stack. -sink_ldisc_num = 0; -source_ldisc_num = 0; -ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num); -ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num); - -// Three, program closes connection, and cleanup: -close(g_fd_uart); -close(g_fd_gadget); -g_fd_uart = g_fd_gadget = NULL; diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt index c42a21b99046..523d54b60087 100644 --- a/Documentation/rbtree.txt +++ b/Documentation/rbtree.txt @@ -204,21 +204,21 @@ potentially expensive tree iterations. This is done at negligible runtime overhead for maintanence; albeit larger memory footprint. Similar to the rb_root structure, cached rbtrees are initialized to be -empty via: +empty via:: struct rb_root_cached mytree = RB_ROOT_CACHED; Cached rbtree is simply a regular rb_root with an extra pointer to cache the leftmost node. This allows rb_root_cached to exist wherever rb_root does, which permits augmented trees to be supported as well as only a few extra -interfaces: +interfaces:: struct rb_node *rb_first_cached(struct rb_root_cached *tree); void rb_insert_color_cached(struct rb_node *, struct rb_root_cached *, bool); void rb_erase_cached(struct rb_node *node, struct rb_root_cached *); Both insert and erase calls have their respective counterpart of augmented -trees: +trees:: void rb_insert_augmented_cached(struct rb_node *node, struct rb_root_cached *, bool, struct rb_augment_callbacks *); diff --git a/Documentation/remoteproc.txt b/Documentation/remoteproc.txt index 77fb03acdbb4..03c3d2e568b0 100644 --- a/Documentation/remoteproc.txt +++ b/Documentation/remoteproc.txt @@ -314,6 +314,8 @@ Here are the various resource types that are currently supported:: * @RSC_VDEV: declare support for a virtio device, and serve as its * virtio header. * @RSC_LAST: just keep this one at the end + * @RSC_VENDOR_START: start of the vendor specific resource types range + * @RSC_VENDOR_END: end of the vendor specific resource types range * * Please note that these values are used as indices to the rproc_handle_rsc * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to @@ -321,11 +323,13 @@ Here are the various resource types that are currently supported:: * please update it as needed. */ enum fw_resource_type { - RSC_CARVEOUT = 0, - RSC_DEVMEM = 1, - RSC_TRACE = 2, - RSC_VDEV = 3, - RSC_LAST = 4, + RSC_CARVEOUT = 0, + RSC_DEVMEM = 1, + RSC_TRACE = 2, + RSC_VDEV = 3, + RSC_LAST = 4, + RSC_VENDOR_START = 128, + RSC_VENDOR_END = 512, }; For more details regarding a specific resource type, please see its diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.txt new file mode 100644 index 000000000000..1b73fea23b39 --- /dev/null +++ b/Documentation/riscv/boot-image-header.txt @@ -0,0 +1,50 @@ + Boot image header in RISC-V Linux + ============================================= + +Author: Atish Patra <atish.patra@wdc.com> +Date : 20 May 2019 + +This document only describes the boot image header details for RISC-V Linux. +The complete booting guide will be available at Documentation/riscv/booting.txt. + +The following 64-byte header is present in decompressed Linux kernel image. + + u32 code0; /* Executable code */ + u32 code1; /* Executable code */ + u64 text_offset; /* Image load offset, little endian */ + u64 image_size; /* Effective Image size, little endian */ + u64 flags; /* kernel flags, little endian */ + u32 version; /* Version of this header */ + u32 res1 = 0; /* Reserved */ + u64 res2 = 0; /* Reserved */ + u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ + u32 res3; /* Reserved for additional RISC-V specific header */ + u32 res4; /* Reserved for PE COFF offset */ + +This header format is compliant with PE/COFF header and largely inspired from +ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common +header in future. + +Notes: +- This header can also be reused to support EFI stub for RISC-V in future. EFI + specification needs PE/COFF image header in the beginning of the kernel image + in order to load it as an EFI application. In order to support EFI stub, + code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should + point to the rest of the PE/COFF header. + +- version field indicate header version number. + Bits 0:15 - Minor version + Bits 16:31 - Major version + + This preserves compatibility across newer and older version of the header. + The current version is defined as 0.1. + +- res3 is reserved for offset to any other additional fields. This makes the + header extendible in future. One example would be to accommodate ISA + extension for RISC-V in future. For current version, it is set to be zero. + +- In current header, the flag field has only one field. + Bit 0: Kernel endianness. 1 if BE, 0 if LE. + +- Image size is mandatory for boot loader to load kernel image. Booting will + fail otherwise. diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst index c4b906d9b5a7..e3ca0922a8c2 100644 --- a/Documentation/riscv/index.rst +++ b/Documentation/riscv/index.rst @@ -1,5 +1,3 @@ -:orphan: - =================== RISC-V architecture =================== diff --git a/Documentation/s390/debugging390.rst b/Documentation/s390/debugging390.rst index d49305fd5e1a..73ad0b06c666 100644 --- a/Documentation/s390/debugging390.rst +++ b/Documentation/s390/debugging390.rst @@ -170,7 +170,7 @@ currently running at. | +----------------+-------------------------------------------------+ | | 32 | Basic Addressing Mode | | | | | -| | | Used to set addressing mode | +| | | Used to set addressing mode:: | | | | | | | | +---------+----------+----------+ | | | | | PSW 31 | PSW 32 | | | diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst index 1a914da2a07b..4602312909d3 100644 --- a/Documentation/s390/index.rst +++ b/Documentation/s390/index.rst @@ -1,5 +1,3 @@ -:orphan: - ================= s390 Architecture ================= diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst index 1f6d0b56d53e..1e210c6afa88 100644 --- a/Documentation/s390/vfio-ccw.rst +++ b/Documentation/s390/vfio-ccw.rst @@ -38,7 +38,7 @@ every detail. More information/reference could be found here: qemu/hw/s390x/css.c For vfio mediated device framework: -- Documentation/vfio-mediated-device.txt +- Documentation/driver-api/vfio-mediated-device.rst Motivation of vfio-ccw ---------------------- @@ -322,5 +322,5 @@ Reference 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204) 3. https://en.wikipedia.org/wiki/Channel_I/O 4. Documentation/s390/cds.rst -5. Documentation/vfio.txt -6. Documentation/vfio-mediated-device.txt +5. Documentation/driver-api/vfio.rst +6. Documentation/driver-api/vfio-mediated-device.rst diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst index 058be77a4c34..69074e5de9c4 100644 --- a/Documentation/scheduler/index.rst +++ b/Documentation/scheduler/index.rst @@ -1,5 +1,3 @@ -:orphan: - =============== Linux Scheduler =============== diff --git a/Documentation/scheduler/sched-deadline.rst b/Documentation/scheduler/sched-deadline.rst index 3391e86d810c..14a2f7bf63fe 100644 --- a/Documentation/scheduler/sched-deadline.rst +++ b/Documentation/scheduler/sched-deadline.rst @@ -669,7 +669,7 @@ Deadline Task Scheduling -deadline tasks cannot have an affinity mask smaller that the entire root_domain they are created on. However, affinities can be specified - through the cpuset facility (Documentation/cgroup-v1/cpusets.rst). + through the cpuset facility (Documentation/admin-guide/cgroup-v1/cpusets.rst). 5.1 SCHED_DEADLINE and cpusets HOWTO ------------------------------------ diff --git a/Documentation/scheduler/sched-design-CFS.rst b/Documentation/scheduler/sched-design-CFS.rst index 53b30d1967cf..a96c72651877 100644 --- a/Documentation/scheduler/sched-design-CFS.rst +++ b/Documentation/scheduler/sched-design-CFS.rst @@ -222,7 +222,7 @@ SCHED_BATCH) tasks. These options need CONFIG_CGROUPS to be defined, and let the administrator create arbitrary groups of tasks, using the "cgroup" pseudo filesystem. See - Documentation/cgroup-v1/cgroups.rst for more information about this filesystem. + Documentation/admin-guide/cgroup-v1/cgroups.rst for more information about this filesystem. When CONFIG_FAIR_GROUP_SCHED is defined, a "cpu.shares" file is created for each group created using the pseudo filesystem. See example steps below to create diff --git a/Documentation/scheduler/sched-energy.rst b/Documentation/scheduler/sched-energy.rst index fce5858c9082..9580c57a52bc 100644 --- a/Documentation/scheduler/sched-energy.rst +++ b/Documentation/scheduler/sched-energy.rst @@ -22,7 +22,7 @@ the highest. The actual EM used by EAS is _not_ maintained by the scheduler, but by a dedicated framework. For details about this framework and what it provides, -please refer to its documentation (see Documentation/power/energy-model.txt). +please refer to its documentation (see Documentation/power/energy-model.rst). 2. Background and Terminology @@ -81,7 +81,7 @@ through the arch_scale_cpu_capacity() callback. The rest of platform knowledge used by EAS is directly read from the Energy Model (EM) framework. The EM of a platform is composed of a power cost table -per 'performance domain' in the system (see Documentation/power/energy-model.txt +per 'performance domain' in the system (see Documentation/power/energy-model.rst for futher details about performance domains). The scheduler manages references to the EM objects in the topology code when the @@ -353,7 +353,7 @@ could be amended in the future if proven otherwise. EAS uses the EM of a platform to estimate the impact of scheduling decisions on energy. So, your platform must provide power cost tables to the EM framework in order to make EAS start. To do so, please refer to documentation of the -independent EM framework in Documentation/power/energy-model.txt. +independent EM framework in Documentation/power/energy-model.rst. Please also note that the scheduling domains need to be re-built after the EM has been registered in order to start EAS. diff --git a/Documentation/scheduler/sched-rt-group.rst b/Documentation/scheduler/sched-rt-group.rst index d27d3f3712fd..655a096ec8fb 100644 --- a/Documentation/scheduler/sched-rt-group.rst +++ b/Documentation/scheduler/sched-rt-group.rst @@ -133,7 +133,7 @@ This uses the cgroup virtual file system and "<cgroup>/cpu.rt_runtime_us" to control the CPU time reserved for each control group. For more information on working with control groups, you should read -Documentation/cgroup-v1/cgroups.rst as well. +Documentation/admin-guide/cgroup-v1/cgroups.rst as well. Group settings are checked against the following limits in order to keep the configuration schedulable: diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index aad6d92ffe31..fc503dd689a7 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -8,7 +8,10 @@ Security Documentation credentials IMA-templates keys/index - LSM + lsm + lsm-development + sak SCTP self-protection + siphash tpm/index diff --git a/Documentation/security/LSM.rst b/Documentation/security/lsm-development.rst index 31d92bc5fdd2..31d92bc5fdd2 100644 --- a/Documentation/security/LSM.rst +++ b/Documentation/security/lsm-development.rst diff --git a/Documentation/lsm.txt b/Documentation/security/lsm.rst index ad4dfd020e0d..ad4dfd020e0d 100644 --- a/Documentation/lsm.txt +++ b/Documentation/security/lsm.rst diff --git a/Documentation/SAK.txt b/Documentation/security/sak.rst index 260e1d3687bd..260e1d3687bd 100644 --- a/Documentation/SAK.txt +++ b/Documentation/security/sak.rst diff --git a/Documentation/siphash.txt b/Documentation/security/siphash.rst index 9965821ab333..9965821ab333 100644 --- a/Documentation/siphash.txt +++ b/Documentation/security/siphash.rst diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst index af77a7bbb070..3296533e54cf 100644 --- a/Documentation/security/tpm/index.rst +++ b/Documentation/security/tpm/index.rst @@ -5,3 +5,4 @@ Trusted Platform Module documentation .. toctree:: tpm_vtpm_proxy + xen-tpmfront diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.rst index 69346de87ff3..00d5b1db227d 100644 --- a/Documentation/security/tpm/xen-tpmfront.txt +++ b/Documentation/security/tpm/xen-tpmfront.rst @@ -1,4 +1,6 @@ +============================= Virtual TPM interface for Xen +============================= Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) @@ -6,7 +8,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for Xen. The reader is assumed to have familiarity with building and installing Xen, Linux, and a basic understanding of the TPM and vTPM concepts. -INTRODUCTION +Introduction +------------ The goal of this work is to provide a TPM functionality to a virtual guest operating system (in Xen terms, a DomU). This allows programs to interact with @@ -24,81 +27,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by IBM and Intel corporation. -DESIGN OVERVIEW +Design Overview --------------- -The architecture of vTPM is described below: - -+------------------+ -| Linux DomU | ... -| | ^ | -| v | | -| xen-tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpm-stubdom | ... -| | ^ | -| v | | -| mini-os/tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpmmgr-stubdom | -| | ^ | -| v | | -| mini-os/tpm_tis | -+------------------+ - | ^ - v | -+------------------+ -| Hardware TPM | -+------------------+ - - * Linux DomU: The Linux based guest that wants to use a vTPM. There may be +The architecture of vTPM is described below:: + + +------------------+ + | Linux DomU | ... + | | ^ | + | v | | + | xen-tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpm-stubdom | ... + | | ^ | + | v | | + | mini-os/tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpmmgr-stubdom | + | | ^ | + | v | | + | mini-os/tpm_tis | + +------------------+ + | ^ + v | + +------------------+ + | Hardware TPM | + +------------------+ + +* Linux DomU: + The Linux based guest that wants to use a vTPM. There may be more than one of these. - * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver +* xen-tpmfront.ko: + Linux kernel virtual TPM frontend driver. This driver provides vTPM access to a Linux-based DomU. - * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver +* mini-os/tpmback: + Mini-os TPM backend driver. The Linux frontend driver connects to this backend driver to facilitate communications between the Linux DomU and its vTPM. This driver is also used by vtpmmgr-stubdom to communicate with vtpm-stubdom. - * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a +* vtpm-stubdom: + A mini-os stub domain that implements a vTPM. There is a one to one mapping between running vtpm-stubdom instances and logical vtpms on the system. The vTPM Platform Configuration Registers (PCRs) are normally all initialized to zero. - * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain +* mini-os/tpmfront: + Mini-os TPM frontend driver. The vTPM mini-os domain vtpm-stubdom uses this driver to communicate with vtpmmgr-stubdom. This driver is also used in mini-os domains such as pv-grub that talk to the vTPM domain. - * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is +* vtpmmgr-stubdom: + A mini-os domain that implements the vTPM manager. There is only one vTPM manager and it should be running during the entire lifetime of the machine. This domain regulates access to the physical TPM on the system and secures the persistent state of each vTPM. - * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS) +* mini-os/tpm_tis: + Mini-os TPM version 1.2 TPM Interface Specification (TIS) driver. This driver used by vtpmmgr-stubdom to talk directly to the hardware TPM. Communication is facilitated by mapping hardware memory pages into vtpmmgr-stubdom. - * Hardware TPM: The physical TPM that is soldered onto the motherboard. +* Hardware TPM: + The physical TPM that is soldered onto the motherboard. -INTEGRATION WITH XEN +Integration With Xen -------------------- Support for the vTPM driver was added in Xen using the libxl toolstack in Xen diff --git a/Documentation/sparc/index.rst b/Documentation/sparc/index.rst index 91f7d6643dd5..71cff621f243 100644 --- a/Documentation/sparc/index.rst +++ b/Documentation/sparc/index.rst @@ -1,5 +1,3 @@ -:orphan: - ================== Sparc Architecture ================== diff --git a/Documentation/sysctl/abi.txt b/Documentation/sysctl/abi.txt deleted file mode 100644 index 63f4ebcf652c..000000000000 --- a/Documentation/sysctl/abi.txt +++ /dev/null @@ -1,54 +0,0 @@ -Documentation for /proc/sys/abi/* kernel version 2.6.0.test2 - (c) 2003, Fabian Frederick <ffrederick@users.sourceforge.net> - -For general info : README. - -============================================================== - -This path is binary emulation relevant aka personality types aka abi. -When a process is executed, it's linked to an exec_domain whose -personality is defined using values available from /proc/sys/abi. -You can find further details about abi in include/linux/personality.h. - -Here are the files featuring in 2.6 kernel : - -- defhandler_coff -- defhandler_elf -- defhandler_lcall7 -- defhandler_libcso -- fake_utsname -- trace - -=========================================================== -defhandler_coff: -defined value : -PER_SCOSVR3 -0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS | SHORT_INODE - -=========================================================== -defhandler_elf: -defined value : -PER_LINUX -0 - -=========================================================== -defhandler_lcall7: -defined value : -PER_SVR4 -0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO, - -=========================================================== -defhandler_libsco: -defined value: -PER_SVR4 -0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO, - -=========================================================== -fake_utsname: -Unused - -=========================================================== -trace: -Unused - -=========================================================== diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst index b68f48982392..4b24f81f747e 100644 --- a/Documentation/target/index.rst +++ b/Documentation/target/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ================== TCM Virtual Device diff --git a/Documentation/thermal/cpu-cooling-api.txt b/Documentation/thermal/cpu-cooling-api.rst index 7df567eaea1a..645d914c45a6 100644 --- a/Documentation/thermal/cpu-cooling-api.txt +++ b/Documentation/thermal/cpu-cooling-api.rst @@ -1,5 +1,6 @@ +======================= CPU cooling APIs How To -=================================== +======================= Written by Amit Daniel Kachhap <amit.kachhap@linaro.org> @@ -8,40 +9,54 @@ Updated: 6 Jan 2015 Copyright (c) 2012 Samsung Electronics Co., Ltd(http://www.samsung.com) 0. Introduction +=============== The generic cpu cooling(freq clipping) provides registration/unregistration APIs to the caller. The binding of the cooling devices to the trip point is left for the user. The registration APIs returns the cooling device pointer. 1. cpu cooling APIs +=================== 1.1 cpufreq registration/unregistration APIs -1.1.1 struct thermal_cooling_device *cpufreq_cooling_register( - struct cpumask *clip_cpus) +-------------------------------------------- + + :: + + struct thermal_cooling_device + *cpufreq_cooling_register(struct cpumask *clip_cpus) This interface function registers the cpufreq cooling device with the name "thermal-cpufreq-%x". This api can support multiple instances of cpufreq cooling devices. - clip_cpus: cpumask of cpus where the frequency constraints will happen. + clip_cpus: + cpumask of cpus where the frequency constraints will happen. + + :: -1.1.2 struct thermal_cooling_device *of_cpufreq_cooling_register( - struct cpufreq_policy *policy) + struct thermal_cooling_device + *of_cpufreq_cooling_register(struct cpufreq_policy *policy) This interface function registers the cpufreq cooling device with the name "thermal-cpufreq-%x" linking it with a device tree node, in order to bind it via the thermal DT code. This api can support multiple instances of cpufreq cooling devices. - policy: CPUFreq policy. + policy: + CPUFreq policy. + + + :: -1.1.3 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev) + void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev) This interface function unregisters the "thermal-cpufreq-%x" cooling device. cdev: Cooling device pointer which has to be unregistered. 2. Power models +=============== The power API registration functions provide a simple power model for CPUs. The current power is calculated as dynamic power (static power isn't @@ -65,9 +80,9 @@ For a given processor implementation the primary factors are: variation. In pathological cases this variation can be significant, but typically it is of a much lesser impact than the factors above. -A high level dynamic power consumption model may then be represented as: +A high level dynamic power consumption model may then be represented as:: -Pdyn = f(run) * Voltage^2 * Frequency * Utilisation + Pdyn = f(run) * Voltage^2 * Frequency * Utilisation f(run) here represents the described execution behaviour and its result has a units of Watts/Hz/Volt^2 (this often expressed in @@ -80,9 +95,9 @@ factors. Therefore, in initial implementation that contribution is represented as a constant coefficient. This is a simplification consistent with the relative contribution to overall power variation. -In this simplified representation our model becomes: +In this simplified representation our model becomes:: -Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation + Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation Where `capacitance` is a constant that represents an indicative running time dynamic power coefficient in fundamental units of diff --git a/Documentation/thermal/exynos_thermal b/Documentation/thermal/exynos_thermal.rst index 9010c4416967..5bd556566c70 100644 --- a/Documentation/thermal/exynos_thermal +++ b/Documentation/thermal/exynos_thermal.rst @@ -1,8 +1,11 @@ +======================== Kernel driver exynos_tmu -================= +======================== Supported chips: + * ARM SAMSUNG EXYNOS4, EXYNOS5 series of SoC + Datasheet: Not publicly available Authors: Donggeun Kim <dg77.kim@samsung.com> @@ -19,32 +22,39 @@ Temperature can be taken from the temperature code. There are three equations converting from temperature to temperature code. The three equations are: - 1. Two point trimming + 1. Two point trimming:: + Tc = (T - 25) * (TI2 - TI1) / (85 - 25) + TI1 - 2. One point trimming + 2. One point trimming:: + Tc = T + TI1 - 25 - 3. No trimming + 3. No trimming:: + Tc = T + 50 - Tc: Temperature code, T: Temperature, - TI1: Trimming info for 25 degree Celsius (stored at TRIMINFO register) + Tc: + Temperature code, T: Temperature, + TI1: + Trimming info for 25 degree Celsius (stored at TRIMINFO register) Temperature code measured at 25 degree Celsius which is unchanged - TI2: Trimming info for 85 degree Celsius (stored at TRIMINFO register) + TI2: + Trimming info for 85 degree Celsius (stored at TRIMINFO register) Temperature code measured at 85 degree Celsius which is unchanged TMU(Thermal Management Unit) in EXYNOS4/5 generates interrupt when temperature exceeds pre-defined levels. The maximum number of configurable threshold is five. -The threshold levels are defined as follows: +The threshold levels are defined as follows:: + Level_0: current temperature > trigger_level_0 + threshold Level_1: current temperature > trigger_level_1 + threshold Level_2: current temperature > trigger_level_2 + threshold Level_3: current temperature > trigger_level_3 + threshold - The threshold and each trigger_level are set - through the corresponding registers. +The threshold and each trigger_level are set +through the corresponding registers. When an interrupt occurs, this driver notify kernel thermal framework with the function exynos_report_trigger. @@ -54,24 +64,27 @@ it can be used to synchronize the cooling action. TMU driver description: ----------------------- -The exynos thermal driver is structured as, +The exynos thermal driver is structured as:: Kernel Core thermal framework (thermal_core.c, step_wise.c, cpu_cooling.c) ^ | | -TMU configuration data -------> TMU Driver <------> Exynos Core thermal wrapper -(exynos_tmu_data.c) (exynos_tmu.c) (exynos_thermal_common.c) -(exynos_tmu_data.h) (exynos_tmu.h) (exynos_thermal_common.h) + TMU configuration data -----> TMU Driver <----> Exynos Core thermal wrapper + (exynos_tmu_data.c) (exynos_tmu.c) (exynos_thermal_common.c) + (exynos_tmu_data.h) (exynos_tmu.h) (exynos_thermal_common.h) -a) TMU configuration data: This consist of TMU register offsets/bitfields +a) TMU configuration data: + This consist of TMU register offsets/bitfields described through structure exynos_tmu_registers. Also several other platform data (struct exynos_tmu_platform_data) members are used to configure the TMU. -b) TMU driver: This component initialises the TMU controller and sets different +b) TMU driver: + This component initialises the TMU controller and sets different thresholds. It invokes core thermal implementation with the call exynos_report_trigger. -c) Exynos Core thermal wrapper: This provides 3 wrapper function to use the +c) Exynos Core thermal wrapper: + This provides 3 wrapper function to use the Kernel core thermal framework. They are exynos_unregister_thermal, exynos_register_thermal and exynos_report_trigger. diff --git a/Documentation/thermal/exynos_thermal_emulation b/Documentation/thermal/exynos_thermal_emulation deleted file mode 100644 index b15efec6ca28..000000000000 --- a/Documentation/thermal/exynos_thermal_emulation +++ /dev/null @@ -1,53 +0,0 @@ -EXYNOS EMULATION MODE -======================== - -Copyright (C) 2012 Samsung Electronics - -Written by Jonghwa Lee <jonghwa3.lee@samsung.com> - -Description ------------ - -Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for thermal management unit. -Thermal emulation mode supports software debug for TMU's operation. User can set temperature -manually with software code and TMU will read current temperature from user value not from -sensor's value. - -Enabling CONFIG_THERMAL_EMULATION option will make this support available. -When it's enabled, sysfs node will be created as -/sys/devices/virtual/thermal/thermal_zone'zone id'/emul_temp. - -The sysfs node, 'emul_node', will contain value 0 for the initial state. When you input any -temperature you want to update to sysfs node, it automatically enable emulation mode and -current temperature will be changed into it. -(Exynos also supports user changeable delay time which would be used to delay of - changing temperature. However, this node only uses same delay of real sensing time, 938us.) - -Exynos emulation mode requires synchronous of value changing and enabling. It means when you -want to update the any value of delay or next temperature, then you have to enable emulation -mode at the same time. (Or you have to keep the mode enabling.) If you don't, it fails to -change the value to updated one and just use last succeessful value repeatedly. That's why -this node gives users the right to change termerpature only. Just one interface makes it more -simply to use. - -Disabling emulation mode only requires writing value 0 to sysfs node. - - -TEMP 120 | - | - 100 | - | - 80 | - | +----------- - 60 | | | - | +-------------| | - 40 | | | | - | | | | - 20 | | | +---------- - | | | | | - 0 |______________|_____________|__________|__________|_________ - A A A A TIME - |<----->| |<----->| |<----->| | - | 938us | | | | | | -emulation : 0 50 | 70 | 20 | 0 -current temp : sensor 50 70 20 sensor diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/thermal/exynos_thermal_emulation.rst new file mode 100644 index 000000000000..c21d10838bc5 --- /dev/null +++ b/Documentation/thermal/exynos_thermal_emulation.rst @@ -0,0 +1,61 @@ +===================== +Exynos Emulation Mode +===================== + +Copyright (C) 2012 Samsung Electronics + +Written by Jonghwa Lee <jonghwa3.lee@samsung.com> + +Description +----------- + +Exynos 4x12 (4212, 4412) and 5 series provide emulation mode for thermal +management unit. Thermal emulation mode supports software debug for +TMU's operation. User can set temperature manually with software code +and TMU will read current temperature from user value not from sensor's +value. + +Enabling CONFIG_THERMAL_EMULATION option will make this support +available. When it's enabled, sysfs node will be created as +/sys/devices/virtual/thermal/thermal_zone'zone id'/emul_temp. + +The sysfs node, 'emul_node', will contain value 0 for the initial state. +When you input any temperature you want to update to sysfs node, it +automatically enable emulation mode and current temperature will be +changed into it. + +(Exynos also supports user changeable delay time which would be used to +delay of changing temperature. However, this node only uses same delay +of real sensing time, 938us.) + +Exynos emulation mode requires synchronous of value changing and +enabling. It means when you want to update the any value of delay or +next temperature, then you have to enable emulation mode at the same +time. (Or you have to keep the mode enabling.) If you don't, it fails to +change the value to updated one and just use last succeessful value +repeatedly. That's why this node gives users the right to change +termerpature only. Just one interface makes it more simply to use. + +Disabling emulation mode only requires writing value 0 to sysfs node. + +:: + + + TEMP 120 | + | + 100 | + | + 80 | + | +----------- + 60 | | | + | +-------------| | + 40 | | | | + | | | | + 20 | | | +---------- + | | | | | + 0 |______________|_____________|__________|__________|_________ + A A A A TIME + |<----->| |<----->| |<----->| | + | 938us | | | | | | + emulation : 0 50 | 70 | 20 | 0 + current temp: sensor 50 70 20 sensor diff --git a/Documentation/thermal/index.rst b/Documentation/thermal/index.rst new file mode 100644 index 000000000000..8c1c00146cad --- /dev/null +++ b/Documentation/thermal/index.rst @@ -0,0 +1,18 @@ +:orphan: + +======= +Thermal +======= + +.. toctree:: + :maxdepth: 1 + + cpu-cooling-api + sysfs-api + power_allocator + + exynos_thermal + exynos_thermal_emulation + intel_powerclamp + nouveau_thermal + x86_pkg_temperature_thermal diff --git a/Documentation/thermal/intel_powerclamp.txt b/Documentation/thermal/intel_powerclamp.rst index b5df21168fbc..3f6dfb0b3ea6 100644 --- a/Documentation/thermal/intel_powerclamp.txt +++ b/Documentation/thermal/intel_powerclamp.rst @@ -1,10 +1,13 @@ - ======================= - INTEL POWERCLAMP DRIVER - ======================= -By: Arjan van de Ven <arjan@linux.intel.com> - Jacob Pan <jacob.jun.pan@linux.intel.com> +======================= +Intel Powerclamp Driver +======================= + +By: + - Arjan van de Ven <arjan@linux.intel.com> + - Jacob Pan <jacob.jun.pan@linux.intel.com> + +.. Contents: -Contents: (*) Introduction - Goals and Objectives @@ -23,7 +26,6 @@ Contents: - Generic Thermal Layer (sysfs) - Kernel APIs (TBD) -============ INTRODUCTION ============ @@ -47,7 +49,6 @@ scalability, and user experience. In many cases, clear advantage is shown over taking the CPU offline or modulating the CPU clock. -=================== THEORY OF OPERATION =================== @@ -57,11 +58,12 @@ Idle Injection On modern Intel processors (Nehalem or later), package level C-state residency is available in MSRs, thus also available to the kernel. -These MSRs are: - #define MSR_PKG_C2_RESIDENCY 0x60D - #define MSR_PKG_C3_RESIDENCY 0x3F8 - #define MSR_PKG_C6_RESIDENCY 0x3F9 - #define MSR_PKG_C7_RESIDENCY 0x3FA +These MSRs are:: + + #define MSR_PKG_C2_RESIDENCY 0x60D + #define MSR_PKG_C3_RESIDENCY 0x3F8 + #define MSR_PKG_C6_RESIDENCY 0x3F9 + #define MSR_PKG_C7_RESIDENCY 0x3FA If the kernel can also inject idle time to the system, then a closed-loop control system can be established that manages package @@ -96,19 +98,21 @@ are not masked. Tests show that the extra wakeups from scheduler tick have a dramatic impact on the effectiveness of the powerclamp driver on large scale systems (Westmere system with 80 processors). -CPU0 - ____________ ____________ -kidle_inject/0 | sleep | mwait | sleep | - _________| |________| |_______ - duration -CPU1 - ____________ ____________ -kidle_inject/1 | sleep | mwait | sleep | - _________| |________| |_______ - ^ - | - | - roundup(jiffies, interval) +:: + + CPU0 + ____________ ____________ + kidle_inject/0 | sleep | mwait | sleep | + _________| |________| |_______ + duration + CPU1 + ____________ ____________ + kidle_inject/1 | sleep | mwait | sleep | + _________| |________| |_______ + ^ + | + | + roundup(jiffies, interval) Only one CPU is allowed to collect statistics and update global control parameters. This CPU is referred to as the controlling CPU in @@ -148,7 +152,7 @@ b) determine the amount of compensation needed at each target ratio Compensation to each target ratio consists of two parts: - a) steady state error compensation + a) steady state error compensation This is to offset the error occurring when the system can enter idle without extra wakeups (such as external interrupts). @@ -158,41 +162,42 @@ Compensation to each target ratio consists of two parts: slowing down CPU activities. A debugfs file is provided for the user to examine compensation -progress and results, such as on a Westmere system. -[jacob@nex01 ~]$ cat -/sys/kernel/debug/intel_powerclamp/powerclamp_calib -controlling cpu: 0 -pct confidence steady dynamic (compensation) -0 0 0 0 -1 1 0 0 -2 1 1 0 -3 3 1 0 -4 3 1 0 -5 3 1 0 -6 3 1 0 -7 3 1 0 -8 3 1 0 -... -30 3 2 0 -31 3 2 0 -32 3 1 0 -33 3 2 0 -34 3 1 0 -35 3 2 0 -36 3 1 0 -37 3 2 0 -38 3 1 0 -39 3 2 0 -40 3 3 0 -41 3 1 0 -42 3 2 0 -43 3 1 0 -44 3 1 0 -45 3 2 0 -46 3 3 0 -47 3 0 0 -48 3 2 0 -49 3 3 0 +progress and results, such as on a Westmere system:: + + [jacob@nex01 ~]$ cat + /sys/kernel/debug/intel_powerclamp/powerclamp_calib + controlling cpu: 0 + pct confidence steady dynamic (compensation) + 0 0 0 0 + 1 1 0 0 + 2 1 1 0 + 3 3 1 0 + 4 3 1 0 + 5 3 1 0 + 6 3 1 0 + 7 3 1 0 + 8 3 1 0 + ... + 30 3 2 0 + 31 3 2 0 + 32 3 1 0 + 33 3 2 0 + 34 3 1 0 + 35 3 2 0 + 36 3 1 0 + 37 3 2 0 + 38 3 1 0 + 39 3 2 0 + 40 3 3 0 + 41 3 1 0 + 42 3 2 0 + 43 3 1 0 + 44 3 1 0 + 45 3 2 0 + 46 3 3 0 + 47 3 0 0 + 48 3 2 0 + 49 3 3 0 Calibration occurs during runtime. No offline method is available. Steady state compensation is used only when confidence levels of all @@ -217,9 +222,8 @@ keeps track of clamping kernel threads, even after they are migrated to other CPUs, after a CPU offline event. -===================== Performance Analysis -===================== +==================== This section describes the general performance data collected on multiple systems, including Westmere (80P) and Ivy Bridge (4P, 8P). @@ -257,16 +261,15 @@ achieve up to 40% better performance per watt. (measured by a spin counter summed over per CPU counting threads spawned for all running CPUs). -==================== Usage and Interfaces ==================== The powerclamp driver is registered to the generic thermal layer as a -cooling device. Currently, it’s not bound to any thermal zones. +cooling device. Currently, it’s not bound to any thermal zones:: -jacob@chromoly:/sys/class/thermal/cooling_device14$ grep . * -cur_state:0 -max_state:50 -type:intel_powerclamp + jacob@chromoly:/sys/class/thermal/cooling_device14$ grep . * + cur_state:0 + max_state:50 + type:intel_powerclamp cur_state allows user to set the desired idle percentage. Writing 0 to cur_state will stop idle injection. Writing a value between 1 and @@ -278,9 +281,9 @@ cur_state returns value -1 instead of 0 which is to avoid confusing 100% busy state with the disabled state. Example usage: -- To inject 25% idle time -$ sudo sh -c "echo 25 > /sys/class/thermal/cooling_device80/cur_state -" +- To inject 25% idle time:: + + $ sudo sh -c "echo 25 > /sys/class/thermal/cooling_device80/cur_state If the system is not busy and has more than 25% idle time already, then the powerclamp driver will not start idle injection. Using Top @@ -292,23 +295,23 @@ idle time is accounted as normal idle in that common code path is taken as the idle task. In this example, 24.1% idle is shown. This helps the system admin or -user determine the cause of slowdown, when a powerclamp driver is in action. - - -Tasks: 197 total, 1 running, 196 sleeping, 0 stopped, 0 zombie -Cpu(s): 71.2%us, 4.7%sy, 0.0%ni, 24.1%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st -Mem: 3943228k total, 1689632k used, 2253596k free, 74960k buffers -Swap: 4087804k total, 0k used, 4087804k free, 945336k cached - - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 3352 jacob 20 0 262m 644 428 S 286 0.0 0:17.16 spin - 3341 root -51 0 0 0 0 D 25 0.0 0:01.62 kidle_inject/0 - 3344 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/3 - 3342 root -51 0 0 0 0 D 25 0.0 0:01.61 kidle_inject/1 - 3343 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/2 - 2935 jacob 20 0 696m 125m 35m S 5 3.3 0:31.11 firefox - 1546 root 20 0 158m 20m 6640 S 3 0.5 0:26.97 Xorg - 2100 jacob 20 0 1223m 88m 30m S 3 2.3 0:23.68 compiz +user determine the cause of slowdown, when a powerclamp driver is in action:: + + + Tasks: 197 total, 1 running, 196 sleeping, 0 stopped, 0 zombie + Cpu(s): 71.2%us, 4.7%sy, 0.0%ni, 24.1%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 3943228k total, 1689632k used, 2253596k free, 74960k buffers + Swap: 4087804k total, 0k used, 4087804k free, 945336k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 3352 jacob 20 0 262m 644 428 S 286 0.0 0:17.16 spin + 3341 root -51 0 0 0 0 D 25 0.0 0:01.62 kidle_inject/0 + 3344 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/3 + 3342 root -51 0 0 0 0 D 25 0.0 0:01.61 kidle_inject/1 + 3343 root -51 0 0 0 0 D 25 0.0 0:01.60 kidle_inject/2 + 2935 jacob 20 0 696m 125m 35m S 5 3.3 0:31.11 firefox + 1546 root 20 0 158m 20m 6640 S 3 0.5 0:26.97 Xorg + 2100 jacob 20 0 1223m 88m 30m S 3 2.3 0:23.68 compiz Tests have shown that by using the powerclamp driver as a cooling device, a PID based userspace thermal controller can manage to diff --git a/Documentation/thermal/nouveau_thermal b/Documentation/thermal/nouveau_thermal.rst index 6e17a11efcb0..37255fd6735d 100644 --- a/Documentation/thermal/nouveau_thermal +++ b/Documentation/thermal/nouveau_thermal.rst @@ -1,13 +1,15 @@ +===================== Kernel driver nouveau -=================== +===================== Supported chips: + * NV43+ Authors: Martin Peres (mupuf) <martin.peres@free.fr> Description ---------- +----------- This driver allows to read the GPU core temperature, drive the GPU fan and set temperature alarms. @@ -19,20 +21,25 @@ interface is likely not to work. This document may then not cover your situation entirely. Temperature management --------------------- +---------------------- Temperature is exposed under as a read-only HWMON attribute temp1_input. In order to protect the GPU from overheating, Nouveau supports 4 configurable temperature thresholds: - * Fan_boost: Fan speed is set to 100% when reaching this temperature; - * Downclock: The GPU will be downclocked to reduce its power dissipation; - * Critical: The GPU is put on hold to further lower power dissipation; - * Shutdown: Shut the computer down to protect your GPU. + * Fan_boost: + Fan speed is set to 100% when reaching this temperature; + * Downclock: + The GPU will be downclocked to reduce its power dissipation; + * Critical: + The GPU is put on hold to further lower power dissipation; + * Shutdown: + Shut the computer down to protect your GPU. -WARNING: Some of these thresholds may not be used by Nouveau depending -on your chipset. +WARNING: + Some of these thresholds may not be used by Nouveau depending + on your chipset. The default value for these thresholds comes from the GPU's vbios. These thresholds can be configured thanks to the following HWMON attributes: @@ -46,19 +53,24 @@ NOTE: Remember that the values are stored as milli degrees Celsius. Don't forget to multiply! Fan management ------------- +-------------- Not all cards have a drivable fan. If you do, then the following HWMON attributes should be available: - * pwm1_enable: Current fan management mode (NONE, MANUAL or AUTO); - * pwm1: Current PWM value (power percentage); - * pwm1_min: The minimum PWM speed allowed; - * pwm1_max: The maximum PWM speed allowed (bypassed when hitting Fan_boost); + * pwm1_enable: + Current fan management mode (NONE, MANUAL or AUTO); + * pwm1: + Current PWM value (power percentage); + * pwm1_min: + The minimum PWM speed allowed; + * pwm1_max: + The maximum PWM speed allowed (bypassed when hitting Fan_boost); You may also have the following attribute: - * fan1_input: Speed in RPM of your fan. + * fan1_input: + Speed in RPM of your fan. Your fan can be driven in different modes: @@ -66,14 +78,16 @@ Your fan can be driven in different modes: * 1: The fan can be driven in manual (use pwm1 to change the speed); * 2; The fan is driven automatically depending on the temperature. -NOTE: Be sure to use the manual mode if you want to drive the fan speed manually +NOTE: + Be sure to use the manual mode if you want to drive the fan speed manually -NOTE2: When operating in manual mode outside the vbios-defined -[PWM_min, PWM_max] range, the reported fan speed (RPM) may not be accurate -depending on your hardware. +NOTE2: + When operating in manual mode outside the vbios-defined + [PWM_min, PWM_max] range, the reported fan speed (RPM) may not be accurate + depending on your hardware. Bug reports ---------- +----------- Thermal management on Nouveau is new and may not work on all cards. If you have inquiries, please ping mupuf on IRC (#nouveau, freenode). diff --git a/Documentation/thermal/power_allocator.txt b/Documentation/thermal/power_allocator.rst index 9fb0ff06dca9..67b6a3297238 100644 --- a/Documentation/thermal/power_allocator.txt +++ b/Documentation/thermal/power_allocator.rst @@ -1,3 +1,4 @@ +================================= Power allocator governor tunables ================================= @@ -25,36 +26,36 @@ temperature as the control input and power as the controlled output: P_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_power where - e = desired_temperature - current_temperature - err_integral is the sum of previous errors - diff_err = e - previous_error - -It is similar to the one depicted below: - - k_d - | -current_temp | - | v - | +----------+ +---+ - | +----->| diff_err |-->| X |------+ - | | +----------+ +---+ | - | | | tdp actor - | | k_i | | get_requested_power() - | | | | | | | - | | | | | | | ... - v | v v v v v - +---+ | +-------+ +---+ +---+ +---+ +----------+ - | S |-------+----->| sum e |----->| X |--->| S |-->| S |-->|power | - +---+ | +-------+ +---+ +---+ +---+ |allocation| - ^ | ^ +----------+ - | | | | | - | | +---+ | | | - | +------->| X |-------------------+ v v - | +---+ granted performance -desired_temperature ^ - | - | - k_po/k_pu + - e = desired_temperature - current_temperature + - err_integral is the sum of previous errors + - diff_err = e - previous_error + +It is similar to the one depicted below:: + + k_d + | + current_temp | + | v + | +----------+ +---+ + | +----->| diff_err |-->| X |------+ + | | +----------+ +---+ | + | | | tdp actor + | | k_i | | get_requested_power() + | | | | | | | + | | | | | | | ... + v | v v v v v + +---+ | +-------+ +---+ +---+ +---+ +----------+ + | S |-----+----->| sum e |----->| X |--->| S |-->| S |-->|power | + +---+ | +-------+ +---+ +---+ +---+ |allocation| + ^ | ^ +----------+ + | | | | | + | | +---+ | | | + | +------->| X |-------------------+ v v + | +---+ granted performance + desired_temperature ^ + | + | + k_po/k_pu Sustainable power ----------------- @@ -73,7 +74,7 @@ is typically 2000mW, while on a 10" tablet is around 4500mW (may vary depending on screen size). If you are using device tree, do add it as a property of the -thermal-zone. For example: +thermal-zone. For example:: thermal-zones { soc_thermal { @@ -85,7 +86,7 @@ thermal-zone. For example: Instead, if the thermal zone is registered from the platform code, pass a `thermal_zone_params` that has a `sustainable_power`. If no `thermal_zone_params` were being passed, then something like below -will suffice: +will suffice:: static const struct thermal_zone_params tz_params = { .sustainable_power = 3500, @@ -112,18 +113,18 @@ available capacity at a low temperature. On the other hand, a high value of `k_pu` will result in the governor granting very high power while temperature is low, and may lead to temperature overshooting. -The default value for `k_pu` is: +The default value for `k_pu` is:: 2 * sustainable_power / (desired_temperature - switch_on_temp) This means that at `switch_on_temp` the output of the controller's proportional term will be 2 * `sustainable_power`. The default value -for `k_po` is: +for `k_po` is:: sustainable_power / (desired_temperature - switch_on_temp) Focusing on the proportional and feed forward values of the PID -controller equation we have: +controller equation we have:: P_max = k_p * e + sustainable_power @@ -134,21 +135,23 @@ is the desired one, then the proportional component is zero and thermal equilibrium under constant load. `sustainable_power` is only an estimate, which is the reason for closed-loop control such as this. -Expanding `k_pu` we get: +Expanding `k_pu` we get:: + P_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) + - sustainable_power + sustainable_power -where - T_set is the desired temperature - T is the current temperature - T_on is the switch on temperature +where: + + - T_set is the desired temperature + - T is the current temperature + - T_on is the switch on temperature When the current temperature is the switch_on temperature, the above -formula becomes: +formula becomes:: P_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) + - sustainable_power = 2 * sustainable_power + sustainable_power = - 3 * sustainable_power + sustainable_power = 2 * sustainable_power + sustainable_power = + 3 * sustainable_power Therefore, the proportional term alone linearly decreases power from 3 * `sustainable_power` to `sustainable_power` as the temperature @@ -178,11 +181,18 @@ Cooling device power API Cooling devices controlled by this governor must supply the additional "power" API in their `cooling_device_ops`. It consists on three ops: -1. int get_requested_power(struct thermal_cooling_device *cdev, - struct thermal_zone_device *tz, u32 *power); -@cdev: The `struct thermal_cooling_device` pointer -@tz: thermal zone in which we are currently operating -@power: pointer in which to store the calculated power +1. :: + + int get_requested_power(struct thermal_cooling_device *cdev, + struct thermal_zone_device *tz, u32 *power); + + +@cdev: + The `struct thermal_cooling_device` pointer +@tz: + thermal zone in which we are currently operating +@power: + pointer in which to store the calculated power `get_requested_power()` calculates the power requested by the device in milliwatts and stores it in @power . It should return 0 on @@ -190,23 +200,37 @@ success, -E* on failure. This is currently used by the power allocator governor to calculate how much power to give to each cooling device. -2. int state2power(struct thermal_cooling_device *cdev, struct - thermal_zone_device *tz, unsigned long state, u32 *power); -@cdev: The `struct thermal_cooling_device` pointer -@tz: thermal zone in which we are currently operating -@state: A cooling device state -@power: pointer in which to store the equivalent power +2. :: + + int state2power(struct thermal_cooling_device *cdev, struct + thermal_zone_device *tz, unsigned long state, + u32 *power); + +@cdev: + The `struct thermal_cooling_device` pointer +@tz: + thermal zone in which we are currently operating +@state: + A cooling device state +@power: + pointer in which to store the equivalent power Convert cooling device state @state into power consumption in milliwatts and store it in @power. It should return 0 on success, -E* on failure. This is currently used by thermal core to calculate the maximum power that an actor can consume. -3. int power2state(struct thermal_cooling_device *cdev, u32 power, - unsigned long *state); -@cdev: The `struct thermal_cooling_device` pointer -@power: power in milliwatts -@state: pointer in which to store the resulting state +3. :: + + int power2state(struct thermal_cooling_device *cdev, u32 power, + unsigned long *state); + +@cdev: + The `struct thermal_cooling_device` pointer +@power: + power in milliwatts +@state: + pointer in which to store the resulting state Calculate a cooling device state that would make the device consume at most @power mW and store it in @state. It should return 0 on success, diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.rst index c3fa500df92c..e4930761d3e5 100644 --- a/Documentation/thermal/sysfs-api.txt +++ b/Documentation/thermal/sysfs-api.rst @@ -1,3 +1,4 @@ +=================================== Generic Thermal Sysfs driver How To =================================== @@ -9,6 +10,7 @@ Copyright (c) 2008 Intel Corporation 0. Introduction +=============== The generic thermal sysfs provides a set of interfaces for thermal zone devices (sensors) and thermal cooling devices (fan, processor...) to register @@ -25,59 +27,90 @@ An intelligent thermal management application can make decisions based on inputs from thermal zone attributes (the current temperature and trip point temperature) and throttle appropriate devices. -[0-*] denotes any positive number starting from 0 -[1-*] denotes any positive number starting from 1 +- `[0-*]` denotes any positive number starting from 0 +- `[1-*]` denotes any positive number starting from 1 1. thermal sysfs driver interface functions +=========================================== 1.1 thermal zone device interface -1.1.1 struct thermal_zone_device *thermal_zone_device_register(char *type, - int trips, int mask, void *devdata, - struct thermal_zone_device_ops *ops, - const struct thermal_zone_params *tzp, - int passive_delay, int polling_delay)) +--------------------------------- + + :: + + struct thermal_zone_device + *thermal_zone_device_register(char *type, + int trips, int mask, void *devdata, + struct thermal_zone_device_ops *ops, + const struct thermal_zone_params *tzp, + int passive_delay, int polling_delay)) This interface function adds a new thermal zone device (sensor) to - /sys/class/thermal folder as thermal_zone[0-*]. It tries to bind all the + /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the thermal cooling devices registered at the same time. - type: the thermal zone type. - trips: the total number of trip points this thermal zone supports. - mask: Bit string: If 'n'th bit is set, then trip point 'n' is writeable. - devdata: device private data - ops: thermal zone device call-backs. - .bind: bind the thermal zone device with a thermal cooling device. - .unbind: unbind the thermal zone device with a thermal cooling device. - .get_temp: get the current temperature of the thermal zone. - .set_trips: set the trip points window. Whenever the current temperature + type: + the thermal zone type. + trips: + the total number of trip points this thermal zone supports. + mask: + Bit string: If 'n'th bit is set, then trip point 'n' is writeable. + devdata: + device private data + ops: + thermal zone device call-backs. + + .bind: + bind the thermal zone device with a thermal cooling device. + .unbind: + unbind the thermal zone device with a thermal cooling device. + .get_temp: + get the current temperature of the thermal zone. + .set_trips: + set the trip points window. Whenever the current temperature is updated, the trip points immediately below and above the current temperature are found. - .get_mode: get the current mode (enabled/disabled) of the thermal zone. - - "enabled" means the kernel thermal management is enabled. - - "disabled" will prevent kernel thermal driver action upon trip points - so that user applications can take charge of thermal management. - .set_mode: set the mode (enabled/disabled) of the thermal zone. - .get_trip_type: get the type of certain trip point. - .get_trip_temp: get the temperature above which the certain trip point + .get_mode: + get the current mode (enabled/disabled) of the thermal zone. + + - "enabled" means the kernel thermal management is + enabled. + - "disabled" will prevent kernel thermal driver action + upon trip points so that user applications can take + charge of thermal management. + .set_mode: + set the mode (enabled/disabled) of the thermal zone. + .get_trip_type: + get the type of certain trip point. + .get_trip_temp: + get the temperature above which the certain trip point will be fired. - .set_emul_temp: set the emulation temperature which helps in debugging + .set_emul_temp: + set the emulation temperature which helps in debugging different threshold temperature points. - tzp: thermal zone platform parameters. - passive_delay: number of milliseconds to wait between polls when + tzp: + thermal zone platform parameters. + passive_delay: + number of milliseconds to wait between polls when performing passive cooling. - polling_delay: number of milliseconds to wait between polls when checking + polling_delay: + number of milliseconds to wait between polls when checking whether trip points have been crossed (0 for interrupt driven systems). + :: -1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz) + void thermal_zone_device_unregister(struct thermal_zone_device *tz) This interface function removes the thermal zone device. It deletes the corresponding entry from /sys/class/thermal folder and unbinds all the thermal cooling devices it uses. -1.1.3 struct thermal_zone_device *thermal_zone_of_sensor_register( - struct device *dev, int sensor_id, void *data, - const struct thermal_zone_of_device_ops *ops) + :: + + struct thermal_zone_device + *thermal_zone_of_sensor_register(struct device *dev, int sensor_id, + void *data, + const struct thermal_zone_of_device_ops *ops) This interface adds a new sensor to a DT thermal zone. This function will search the list of thermal zones described in @@ -87,25 +120,33 @@ temperature) and throttle appropriate devices. thermal zone device. The parameters for this interface are: - dev: Device node of sensor containing valid node pointer in + + dev: + Device node of sensor containing valid node pointer in dev->of_node. - sensor_id: a sensor identifier, in case the sensor IP has more + sensor_id: + a sensor identifier, in case the sensor IP has more than one sensors - data: a private pointer (owned by the caller) that will be + data: + a private pointer (owned by the caller) that will be passed back, when a temperature reading is needed. - ops: struct thermal_zone_of_device_ops *. + ops: + `struct thermal_zone_of_device_ops *`. - get_temp: a pointer to a function that reads the + ============== ======================================= + get_temp a pointer to a function that reads the sensor temperature. This is mandatory callback provided by sensor driver. - set_trips: a pointer to a function that sets a + set_trips a pointer to a function that sets a temperature window. When this window is left the driver must inform the thermal core via thermal_zone_device_update. - get_trend: a pointer to a function that reads the + get_trend a pointer to a function that reads the sensor temperature trend. - set_emul_temp: a pointer to a function that sets + set_emul_temp a pointer to a function that sets sensor emulated temperature. + ============== ======================================= + The thermal zone temperature is provided by the get_temp() function pointer of thermal_zone_of_device_ops. When called, it will have the private pointer @data back. @@ -114,8 +155,10 @@ temperature) and throttle appropriate devices. handle. Caller should check the return handle with IS_ERR() for finding whether success or not. -1.1.4 void thermal_zone_of_sensor_unregister(struct device *dev, - struct thermal_zone_device *tzd) + :: + + void thermal_zone_of_sensor_unregister(struct device *dev, + struct thermal_zone_device *tzd) This interface unregisters a sensor from a DT thermal zone which was successfully added by interface thermal_zone_of_sensor_register(). @@ -124,21 +167,29 @@ temperature) and throttle appropriate devices. interface. It will also silent the zone by remove the .get_temp() and get_trend() thermal zone device callbacks. -1.1.5 struct thermal_zone_device *devm_thermal_zone_of_sensor_register( - struct device *dev, int sensor_id, - void *data, const struct thermal_zone_of_device_ops *ops) + :: + + struct thermal_zone_device + *devm_thermal_zone_of_sensor_register(struct device *dev, + int sensor_id, + void *data, + const struct thermal_zone_of_device_ops *ops) This interface is resource managed version of thermal_zone_of_sensor_register(). + All details of thermal_zone_of_sensor_register() described in section 1.1.3 is applicable here. + The benefit of using this interface to register sensor is that it is not require to explicitly call thermal_zone_of_sensor_unregister() in error path or during driver unbinding as this is done by driver resource manager. -1.1.6 void devm_thermal_zone_of_sensor_unregister(struct device *dev, - struct thermal_zone_device *tzd) + :: + + void devm_thermal_zone_of_sensor_unregister(struct device *dev, + struct thermal_zone_device *tzd) This interface is resource managed version of thermal_zone_of_sensor_unregister(). @@ -147,123 +198,186 @@ temperature) and throttle appropriate devices. Normally this function will not need to be called and the resource management code will ensure that the resource is freed. -1.1.7 int thermal_zone_get_slope(struct thermal_zone_device *tz) + :: + + int thermal_zone_get_slope(struct thermal_zone_device *tz) This interface is used to read the slope attribute value for the thermal zone device, which might be useful for platform drivers for temperature calculations. -1.1.8 int thermal_zone_get_offset(struct thermal_zone_device *tz) + :: + + int thermal_zone_get_offset(struct thermal_zone_device *tz) This interface is used to read the offset attribute value for the thermal zone device, which might be useful for platform drivers for temperature calculations. 1.2 thermal cooling device interface -1.2.1 struct thermal_cooling_device *thermal_cooling_device_register(char *name, - void *devdata, struct thermal_cooling_device_ops *) +------------------------------------ + + + :: + + struct thermal_cooling_device + *thermal_cooling_device_register(char *name, + void *devdata, struct thermal_cooling_device_ops *) This interface function adds a new thermal cooling device (fan/processor/...) - to /sys/class/thermal/ folder as cooling_device[0-*]. It tries to bind itself + to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself to all the thermal zone devices registered at the same time. - name: the cooling device name. - devdata: device private data. - ops: thermal cooling devices call-backs. - .get_max_state: get the Maximum throttle state of the cooling device. - .get_cur_state: get the Currently requested throttle state of the cooling device. - .set_cur_state: set the Current throttle state of the cooling device. -1.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev) + name: + the cooling device name. + devdata: + device private data. + ops: + thermal cooling devices call-backs. + + .get_max_state: + get the Maximum throttle state of the cooling device. + .get_cur_state: + get the Currently requested throttle state of the + cooling device. + .set_cur_state: + set the Current throttle state of the cooling device. + + :: + + void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev) This interface function removes the thermal cooling device. It deletes the corresponding entry from /sys/class/thermal folder and unbinds itself from all the thermal zone devices using it. 1.3 interface for binding a thermal zone device with a thermal cooling device -1.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz, - int trip, struct thermal_cooling_device *cdev, - unsigned long upper, unsigned long lower, unsigned int weight); +----------------------------------------------------------------------------- + + :: + + int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz, + int trip, struct thermal_cooling_device *cdev, + unsigned long upper, unsigned long lower, unsigned int weight); This interface function binds a thermal cooling device to a particular trip point of a thermal zone device. + This function is usually called in the thermal zone device .bind callback. - tz: the thermal zone device - cdev: thermal cooling device - trip: indicates which trip point in this thermal zone the cooling device - is associated with. - upper:the Maximum cooling state for this trip point. - THERMAL_NO_LIMIT means no upper limit, + + tz: + the thermal zone device + cdev: + thermal cooling device + trip: + indicates which trip point in this thermal zone the cooling device + is associated with. + upper: + the Maximum cooling state for this trip point. + THERMAL_NO_LIMIT means no upper limit, and the cooling device can be in max_state. - lower:the Minimum cooling state can be used for this trip point. - THERMAL_NO_LIMIT means no lower limit, + lower: + the Minimum cooling state can be used for this trip point. + THERMAL_NO_LIMIT means no lower limit, and the cooling device can be in cooling state 0. - weight: the influence of this cooling device in this thermal - zone. See 1.4.1 below for more information. + weight: + the influence of this cooling device in this thermal + zone. See 1.4.1 below for more information. -1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz, - int trip, struct thermal_cooling_device *cdev); + :: + + int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz, + int trip, struct thermal_cooling_device *cdev); This interface function unbinds a thermal cooling device from a particular trip point of a thermal zone device. This function is usually called in the thermal zone device .unbind callback. - tz: the thermal zone device - cdev: thermal cooling device - trip: indicates which trip point in this thermal zone the cooling device - is associated with. + + tz: + the thermal zone device + cdev: + thermal cooling device + trip: + indicates which trip point in this thermal zone the cooling device + is associated with. 1.4 Thermal Zone Parameters -1.4.1 struct thermal_bind_params +--------------------------- + + :: + + struct thermal_bind_params + This structure defines the following parameters that are used to bind a zone with a cooling device for a particular trip point. - .cdev: The cooling device pointer - .weight: The 'influence' of a particular cooling device on this - zone. This is relative to the rest of the cooling - devices. For example, if all cooling devices have a - weight of 1, then they all contribute the same. You can - use percentages if you want, but it's not mandatory. A - weight of 0 means that this cooling device doesn't - contribute to the cooling of this zone unless all cooling - devices have a weight of 0. If all weights are 0, then - they all contribute the same. - .trip_mask:This is a bit mask that gives the binding relation between - this thermal zone and cdev, for a particular trip point. - If nth bit is set, then the cdev and thermal zone are bound - for trip point n. - .binding_limits: This is an array of cooling state limits. Must have - exactly 2 * thermal_zone.number_of_trip_points. It is an - array consisting of tuples <lower-state upper-state> of - state limits. Each trip will be associated with one state - limit tuple when binding. A NULL pointer means - <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips. - These limits are used when binding a cdev to a trip point. - .match: This call back returns success(0) if the 'tz and cdev' need to + + .cdev: + The cooling device pointer + .weight: + The 'influence' of a particular cooling device on this + zone. This is relative to the rest of the cooling + devices. For example, if all cooling devices have a + weight of 1, then they all contribute the same. You can + use percentages if you want, but it's not mandatory. A + weight of 0 means that this cooling device doesn't + contribute to the cooling of this zone unless all cooling + devices have a weight of 0. If all weights are 0, then + they all contribute the same. + .trip_mask: + This is a bit mask that gives the binding relation between + this thermal zone and cdev, for a particular trip point. + If nth bit is set, then the cdev and thermal zone are bound + for trip point n. + .binding_limits: + This is an array of cooling state limits. Must have + exactly 2 * thermal_zone.number_of_trip_points. It is an + array consisting of tuples <lower-state upper-state> of + state limits. Each trip will be associated with one state + limit tuple when binding. A NULL pointer means + <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips. + These limits are used when binding a cdev to a trip point. + .match: + This call back returns success(0) if the 'tz and cdev' need to be bound, as per platform data. -1.4.2 struct thermal_zone_params + + :: + + struct thermal_zone_params + This structure defines the platform level parameters for a thermal zone. This data, for each thermal zone should come from the platform layer. This is an optional feature where some platforms can choose not to provide this data. - .governor_name: Name of the thermal governor used for this zone - .no_hwmon: a boolean to indicate if the thermal to hwmon sysfs interface - is required. when no_hwmon == false, a hwmon sysfs interface - will be created. when no_hwmon == true, nothing will be done. - In case the thermal_zone_params is NULL, the hwmon interface - will be created (for backward compatibility). - .num_tbps: Number of thermal_bind_params entries for this zone - .tbp: thermal_bind_params entries + + .governor_name: + Name of the thermal governor used for this zone + .no_hwmon: + a boolean to indicate if the thermal to hwmon sysfs interface + is required. when no_hwmon == false, a hwmon sysfs interface + will be created. when no_hwmon == true, nothing will be done. + In case the thermal_zone_params is NULL, the hwmon interface + will be created (for backward compatibility). + .num_tbps: + Number of thermal_bind_params entries for this zone + .tbp: + thermal_bind_params entries 2. sysfs attributes structure +============================= +== ================ RO read only value WO write only value RW read/write value +== ================ Thermal sysfs attributes will be represented under /sys/class/thermal. Hwmon sysfs I/F extension is also available under /sys/class/hwmon if hwmon is compiled in or built as a module. -Thermal zone device sys I/F, created once it's registered: -/sys/class/thermal/thermal_zone[0-*]: +Thermal zone device sys I/F, created once it's registered:: + + /sys/class/thermal/thermal_zone[0-*]: |---type: Type of the thermal zone |---temp: Current temperature |---mode: Working mode of the thermal zone @@ -282,8 +396,9 @@ Thermal zone device sys I/F, created once it's registered: |---slope: Slope constant applied as linear extrapolation |---offset: Offset constant applied as linear extrapolation -Thermal cooling device sys I/F, created once it's registered: -/sys/class/thermal/cooling_device[0-*]: +Thermal cooling device sys I/F, created once it's registered:: + + /sys/class/thermal/cooling_device[0-*]: |---type: Type of the cooling device(processor/fan/...) |---max_state: Maximum cooling state of the cooling device |---cur_state: Current cooling state of the cooling device @@ -299,11 +414,13 @@ the relationship between a thermal zone and its associated cooling device. They are created/removed for each successful execution of thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device. -/sys/class/thermal/thermal_zone[0-*]: +:: + + /sys/class/thermal/thermal_zone[0-*]: |---cdev[0-*]: [0-*]th cooling device in current thermal zone |---cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with |---cdev[0-*]_weight: Influence of the cooling device in - this thermal zone + this thermal zone Besides the thermal zone device sysfs I/F and cooling device sysfs I/F, the generic thermal driver also creates a hwmon sysfs I/F for each _type_ @@ -311,16 +428,17 @@ of thermal zone device. E.g. the generic thermal driver registers one hwmon class device and build the associated hwmon sysfs I/F for all the registered ACPI thermal zones. -/sys/class/hwmon/hwmon[0-*]: +:: + + /sys/class/hwmon/hwmon[0-*]: |---name: The type of the thermal zone devices |---temp[1-*]_input: The current temperature of thermal zone [1-*] |---temp[1-*]_critical: The critical trip point of thermal zone [1-*] Please read Documentation/hwmon/sysfs-interface.rst for additional information. -*************************** -* Thermal zone attributes * -*************************** +Thermal zone attributes +----------------------- type Strings which represent the thermal zone type. @@ -340,54 +458,67 @@ mode This file gives information about the algorithm that is currently managing the thermal zone. It can be either default kernel based algorithm or user space application. - enabled = enable Kernel Thermal management. - disabled = Preventing kernel thermal zone driver actions upon + + enabled + enable Kernel Thermal management. + disabled + Preventing kernel thermal zone driver actions upon trip points so that user application can take full charge of the thermal management. + RW, Optional policy One of the various thermal governors used for a particular zone. + RW, Required available_policies Available thermal governors which can be used for a particular zone. + RO, Required -trip_point_[0-*]_temp +`trip_point_[0-*]_temp` The temperature above which trip point will be fired. + Unit: millidegree Celsius + RO, Optional -trip_point_[0-*]_type +`trip_point_[0-*]_type` Strings which indicate the type of the trip point. - E.g. it can be one of critical, hot, passive, active[0-*] for ACPI + + E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI thermal zone. + RO, Optional -trip_point_[0-*]_hyst +`trip_point_[0-*]_hyst` The hysteresis value for a trip point, represented as an integer Unit: Celsius RW, Optional -cdev[0-*] +`cdev[0-*]` Sysfs link to the thermal cooling device node where the sys I/F for cooling device throttling control represents. + RO, Optional -cdev[0-*]_trip_point - The trip point in this thermal zone which cdev[0-*] is associated +`cdev[0-*]_trip_point` + The trip point in this thermal zone which `cdev[0-*]` is associated with; -1 means the cooling device is not associated with any trip point. + RO, Optional -cdev[0-*]_weight - The influence of cdev[0-*] in this thermal zone. This value - is relative to the rest of cooling devices in the thermal - zone. For example, if a cooling device has a weight double - than that of other, it's twice as effective in cooling the - thermal zone. - RW, Optional +`cdev[0-*]_weight` + The influence of `cdev[0-*]` in this thermal zone. This value + is relative to the rest of cooling devices in the thermal + zone. For example, if a cooling device has a weight double + than that of other, it's twice as effective in cooling the + thermal zone. + + RW, Optional passive Attribute is only present for zones in which the passive cooling @@ -395,8 +526,11 @@ passive and can be set to a temperature (in millidegrees) to enable a passive trip point for the zone. Activation is done by polling with an interval of 1 second. + Unit: millidegrees Celsius + Valid values: 0 (disabled) or greater than 1000 + RW, Optional emul_temp @@ -407,17 +541,21 @@ emul_temp threshold and its associated cooling action. This is write only node and writing 0 on this node should disable emulation. Unit: millidegree Celsius + WO, Optional - WARNING: Be careful while enabling this option on production systems, - because userland can easily disable the thermal policy by simply - flooding this sysfs node with low temperature values. + WARNING: + Be careful while enabling this option on production systems, + because userland can easily disable the thermal policy by simply + flooding this sysfs node with low temperature values. sustainable_power An estimate of the sustained power that can be dissipated by the thermal zone. Used by the power allocator governor. For - more information see Documentation/thermal/power_allocator.txt + more information see Documentation/thermal/power_allocator.rst + Unit: milliwatts + RW, Optional k_po @@ -425,7 +563,8 @@ k_po controller during temperature overshoot. Temperature overshoot is when the current temperature is above the "desired temperature" trip point. For more information see - Documentation/thermal/power_allocator.txt + Documentation/thermal/power_allocator.rst + RW, Optional k_pu @@ -433,20 +572,23 @@ k_pu controller during temperature undershoot. Temperature undershoot is when the current temperature is below the "desired temperature" trip point. For more information see - Documentation/thermal/power_allocator.txt + Documentation/thermal/power_allocator.rst + RW, Optional k_i The integral term of the power allocator governor's PID controller. This term allows the PID controller to compensate for long term drift. For more information see - Documentation/thermal/power_allocator.txt + Documentation/thermal/power_allocator.rst + RW, Optional k_d The derivative term of the power allocator governor's PID controller. For more information see - Documentation/thermal/power_allocator.txt + Documentation/thermal/power_allocator.rst + RW, Optional integral_cutoff @@ -456,8 +598,10 @@ integral_cutoff example, if integral_cutoff is 0, then the integral term only accumulates error when temperature is above the desired temperature trip point. For more information see - Documentation/thermal/power_allocator.txt + Documentation/thermal/power_allocator.rst + Unit: millidegree Celsius + RW, Optional slope @@ -465,6 +609,7 @@ slope to determine a hotspot temperature based off the sensor's raw readings. It is up to the device driver to determine the usage of these values. + RW, Optional offset @@ -472,28 +617,33 @@ offset to determine a hotspot temperature based off the sensor's raw readings. It is up to the device driver to determine the usage of these values. + RW, Optional -***************************** -* Cooling device attributes * -***************************** +Cooling device attributes +------------------------- type String which represents the type of device, e.g: + - for generic ACPI: should be "Fan", "Processor" or "LCD" - for memory controller device on intel_menlow platform: should be "Memory controller". + RO, Required max_state The maximum permissible cooling state of this cooling device. + RO, Required cur_state The current cooling state of this cooling device. The value can any integer numbers between 0 and max_state: + - cur_state == 0 means no cooling - cur_state == max_state means the maximum cooling. + RW, Required stats/reset @@ -508,9 +658,11 @@ stats/time_in_state_ms: units here is 10mS (similar to other time exported in /proc). RO, Required + stats/total_trans: A single positive value showing the total number of times the state of a cooling device is changed. + RO, Required stats/trans_table: @@ -522,6 +674,7 @@ stats/trans_table: RO, Required 3. A simple implementation +========================== ACPI thermal zone may support multiple trip points like critical, hot, passive, active. If an ACPI thermal zone supports critical, passive, @@ -532,11 +685,10 @@ thermal_cooling_device. Both are considered to have the same effectiveness in cooling the thermal zone. If the processor is listed in _PSL method, and the fan is listed in _AL0 -method, the sys I/F structure will be built like this: +method, the sys I/F structure will be built like this:: -/sys/class/thermal: - -|thermal_zone1: + /sys/class/thermal: + |thermal_zone1: |---type: acpitz |---temp: 37000 |---mode: enabled @@ -557,24 +709,24 @@ method, the sys I/F structure will be built like this: |---cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/ |---cdev1_weight: 1024 -|cooling_device0: + |cooling_device0: |---type: Processor |---max_state: 8 |---cur_state: 0 -|cooling_device3: + |cooling_device3: |---type: Fan |---max_state: 2 |---cur_state: 0 -/sys/class/hwmon: - -|hwmon0: + /sys/class/hwmon: + |hwmon0: |---name: acpitz |---temp1_input: 37000 |---temp1_crit: 100000 4. Event Notification +===================== The framework includes a simple notification mechanism, in the form of a netlink event. Netlink socket initialization is done during the _init_ @@ -587,21 +739,28 @@ event will be one of:{THERMAL_AUX0, THERMAL_AUX1, THERMAL_CRITICAL, THERMAL_DEV_FAULT}. Notification can be sent when the current temperature crosses any of the configured thresholds. -5. Export Symbol APIs: +5. Export Symbol APIs +===================== + +5.1. get_tz_trend +----------------- -5.1: get_tz_trend: This function returns the trend of a thermal zone, i.e the rate of change of temperature of the thermal zone. Ideally, the thermal sensor drivers are supposed to implement the callback. If they don't, the thermal framework calculated the trend by comparing the previous and the current temperature values. -5.2:get_thermal_instance: +5.2. get_thermal_instance +------------------------- + This function returns the thermal_instance corresponding to a given {thermal_zone, cooling_device, trip_point} combination. Returns NULL if such an instance does not exist. -5.3:thermal_notify_framework: +5.3. thermal_notify_framework +----------------------------- + This function handles the trip events from sensor drivers. It starts throttling the cooling devices according to the policy configured. For CRITICAL and HOT trip points, this notifies the respective drivers, @@ -609,12 +768,15 @@ and does actual throttling for other trip points i.e ACTIVE and PASSIVE. The throttling policy is based on the configured platform data; if no platform data is provided, this uses the step_wise throttling policy. -5.4:thermal_cdev_update: +5.4. thermal_cdev_update +------------------------ + This function serves as an arbitrator to set the state of a cooling device. It sets the cooling device to the deepest cooling state if possible. -6. thermal_emergency_poweroff: +6. thermal_emergency_poweroff +============================= On an event of critical trip temperature crossing. Thermal framework allows the system to shutdown gracefully by calling orderly_poweroff(). diff --git a/Documentation/thermal/x86_pkg_temperature_thermal b/Documentation/thermal/x86_pkg_temperature_thermal.rst index 17a3a4c0a0ca..f134dbd3f5a9 100644 --- a/Documentation/thermal/x86_pkg_temperature_thermal +++ b/Documentation/thermal/x86_pkg_temperature_thermal.rst @@ -1,19 +1,23 @@ +=================================== Kernel driver: x86_pkg_temp_thermal -=================== +=================================== Supported chips: + * x86: with package level thermal management + (Verify using: CPUID.06H:EAX[bit 6] =1) Authors: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com> Reference ---- +--------- + Intel® 64 and IA-32 Architectures Software Developer’s Manual (Jan, 2013): Chapter 14.6: PACKAGE LEVEL THERMAL MANAGEMENT Description ---------- +----------- This driver register CPU digital temperature package level sensor as a thermal zone with maximum two user mode configurable trip points. Number of trip points @@ -25,23 +29,27 @@ take any action to control temperature. Threshold management -------------------- Each package will register as a thermal zone under /sys/class/thermal. -Example: -/sys/class/thermal/thermal_zone1 + +Example:: + + /sys/class/thermal/thermal_zone1 This contains two trip points: + - trip_point_0_temp - trip_point_1_temp User can set any temperature between 0 to TJ-Max temperature. Temperature units -are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.txt" for +are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for thermal sys-fs details. Any value other than 0 in these trip points, can trigger thermal notifications. Setting 0, stops sending thermal notifications. -Thermal notifications: To get kobject-uevent notifications, set the thermal zone -policy to "user_space". For example: echo -n "user_space" > policy - - +Thermal notifications: +To get kobject-uevent notifications, set the thermal zone +policy to "user_space". +For example:: + echo -n "user_space" > policy diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst index 91f6f8263c48..df510ad0c989 100644 --- a/Documentation/timers/index.rst +++ b/Documentation/timers/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ====== timers diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt index f07e38094b40..1a660a39e3c0 100644 --- a/Documentation/trace/coresight-cpu-debug.txt +++ b/Documentation/trace/coresight-cpu-debug.txt @@ -151,7 +151,7 @@ At the runtime you can disable idle states with below methods: It is possible to disable CPU idle states by way of the PM QoS subsystem, more specifically by using the "/dev/cpu_dma_latency" -interface (see Documentation/power/pm_qos_interface.txt for more +interface (see Documentation/power/pm_qos_interface.rst for more details). As specified in the PM QoS documentation the requested parameter will stay in effect until the file descriptor is released. For example: diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index 7d2b0178d3f3..fbb314bfa112 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -51,15 +51,17 @@ Synopsis of kprobe_events $argN : Fetch the Nth function argument. (N >= 1) (\*1) $retval : Fetch return value.(\*2) $comm : Fetch current task comm. - +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(\*3) + +|-[u]OFFS(FETCHARG) : Fetch memory at FETCHARG +|- OFFS address.(\*3)(\*4) NAME=FETCHARG : Set NAME as the argument name of FETCHARG. FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types (u8/u16/u32/u64/s8/s16/s32/s64), hexadecimal types - (x8/x16/x32/x64), "string" and bitfield are supported. + (x8/x16/x32/x64), "string", "ustring" and bitfield + are supported. (\*1) only for the probe on function entry (offs == 0). (\*2) only for return probe. (\*3) this is useful for fetching a field of data structures. + (\*4) "u" means user-space dereference. See :ref:`user_mem_access`. Types ----- @@ -77,7 +79,8 @@ apply it to registers/stack-entries etc. (for example, '$stack1:x8[8]' is wrong, but '+8($stack):x8[8]' is OK.) String type is a special type, which fetches a "null-terminated" string from kernel space. This means it will fail and store NULL if the string container -has been paged out. +has been paged out. "ustring" type is an alternative of string for user-space. +See :ref:`user_mem_access` for more info.. The string array type is a bit different from other types. For other base types, <base-type>[1] is equal to <base-type> (e.g. +0(%di):x32[1] is same as +0(%di):x32.) But string[1] is not equal to string. The string type itself @@ -92,6 +95,25 @@ Symbol type('symbol') is an alias of u32 or u64 type (depends on BITS_PER_LONG) which shows given pointer in "symbol+offset" style. For $comm, the default type is "string"; any other type is invalid. +.. _user_mem_access: +User Memory Access +------------------ +Kprobe events supports user-space memory access. For that purpose, you can use +either user-space dereference syntax or 'ustring' type. + +The user-space dereference syntax allows you to access a field of a data +structure in user-space. This is done by adding the "u" prefix to the +dereference syntax. For example, +u4(%si) means it will read memory from the +address in the register %si offset by 4, and the memory is expected to be in +user-space. You can use this for strings too, e.g. +u0(%si):string will read +a string from the address in the register %si that is expected to be in user- +space. 'ustring' is a shortcut way of performing the same task. That is, ++0(%si):ustring is equivalent to +u0(%si):string. + +Note that kprobe-event provides the user-memory access syntax but it doesn't +use it transparently. This means if you use normal dereference or string type +for user memory, it might fail, and may always fail on some archs. The user +has to carefully check if the target data is in kernel or user space. Per-Probe Event Filtering ------------------------- @@ -124,6 +146,20 @@ You can check the total number of probe hits and probe miss-hits via The first column is event name, the second is the number of probe hits, the third is the number of probe miss-hits. +Kernel Boot Parameter +--------------------- +You can add and enable new kprobe events when booting up the kernel by +"kprobe_event=" parameter. The parameter accepts a semicolon-delimited +kprobe events, which format is similar to the kprobe_events. +The difference is that the probe definition parameters are comma-delimited +instead of space. For example, adding myprobe event on do_sys_open like below + + p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack) + +should be below for kernel boot parameter (just replace spaces with comma) + + p:myprobe,do_sys_open,dfd=%ax,filename=%dx,flags=%cx,mode=+4($stack) + Usage examples -------------- diff --git a/Documentation/trace/uprobetracer.rst b/Documentation/trace/uprobetracer.rst index 0b21305fabdc..6e75a6c5a2c8 100644 --- a/Documentation/trace/uprobetracer.rst +++ b/Documentation/trace/uprobetracer.rst @@ -42,16 +42,18 @@ Synopsis of uprobe_tracer @+OFFSET : Fetch memory at OFFSET (OFFSET from same file as PATH) $stackN : Fetch Nth entry of stack (N >= 0) $stack : Fetch stack address. - $retval : Fetch return value.(*) + $retval : Fetch return value.(\*1) $comm : Fetch current task comm. - +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(**) + +|-[u]OFFS(FETCHARG) : Fetch memory at FETCHARG +|- OFFS address.(\*2)(\*3) NAME=FETCHARG : Set NAME as the argument name of FETCHARG. FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types (u8/u16/u32/u64/s8/s16/s32/s64), hexadecimal types (x8/x16/x32/x64), "string" and bitfield are supported. - (*) only for return probe. - (**) this is useful for fetching a field of data structures. + (\*1) only for return probe. + (\*2) this is useful for fetching a field of data structures. + (\*3) Unlike kprobe event, "u" prefix will just be ignored, becuse uprobe + events can access only user-space memory. Types ----- diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 5fd8a1abd2be..b9a6be4b8499 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -1404,7 +1404,7 @@ Riferimento per l'API dei Futex Approfondimenti =============== -- ``Documentation/locking/spinlocks.txt``: la guida di Linus Torvalds agli +- ``Documentation/locking/spinlocks.rst``: la guida di Linus Torvalds agli spinlock del kernel. - Unix Systems for Modern Architectures: Symmetric Multiprocessing and diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst index ea74cae958d7..995ee69fab11 100644 --- a/Documentation/translations/it_IT/process/submit-checklist.rst +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -117,7 +117,7 @@ sottomissione delle patch, in particolare sorgenti che ne spieghi la logica: cosa fanno e perché. 25) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate - ``Documentation/ioctl/ioctl-number.txt``. + ``Documentation/ioctl/ioctl-number.rst``. 26) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o funzionalità del kernel che è associata a uno dei seguenti simboli diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting index 1fe866f8218f..562e9a2957e6 100644 --- a/Documentation/translations/zh_CN/arm/Booting +++ b/Documentation/translations/zh_CN/arm/Booting @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm/Booting +Chinese translated version of Documentation/arm/booting.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Russell King <linux@arm.linux.org.uk> Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> --------------------------------------------------------------------- -Documentation/arm/Booting çš„ä¸æ–‡ç¿»è¯‘ +Documentation/arm/booting.rst çš„ä¸æ–‡ç¿»è¯‘ 如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ 交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 diff --git a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt index cd7fc8f34cf9..99af4363984d 100644 --- a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt +++ b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm/kernel_user_helpers.txt +Chinese translated version of Documentation/arm/kernel_user_helpers.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -10,7 +10,7 @@ Maintainer: Nicolas Pitre <nicolas.pitre@linaro.org> Dave Martin <dave.martin@linaro.org> Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> --------------------------------------------------------------------- -Documentation/arm/kernel_user_helpers.txt çš„ä¸æ–‡ç¿»è¯‘ +Documentation/arm/kernel_user_helpers.rst çš„ä¸æ–‡ç¿»è¯‘ 如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ 交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt index 452271dda141..ee1f37da5b23 100644 --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -288,7 +288,7 @@ dev/ 包å«ä¸¤ä¸ªå目录： char/ å’Œ block/。在这两个å目录ä¸ï¼Œæœ‰ä ä¸ç›¸åº”的设备。/sys/dev æ供一个通过一个 stat(2) æ“作结果，查找 设备 sysfs 接å£å¿«æ·çš„方法。 -更多有关 driver-model 的特性信æ¯å¯ä»¥åœ¨ Documentation/driver-model/ +更多有关 driver-model 的特性信æ¯å¯ä»¥åœ¨ Documentation/driver-api/driver-model/ ä¸æ‰¾åˆ°ã€‚ diff --git a/Documentation/translations/zh_CN/gpio.txt b/Documentation/translations/zh_CN/gpio.txt index 4cb1ba8b8fed..a23ee14fc927 100644 --- a/Documentation/translations/zh_CN/gpio.txt +++ b/Documentation/translations/zh_CN/gpio.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/gpio +Chinese translated version of Documentation/admin-guide/gpio If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -10,7 +10,7 @@ Maintainer: Grant Likely <grant.likely@secretlab.ca> Linus Walleij <linus.walleij@linaro.org> Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> --------------------------------------------------------------------- -Documentation/gpio çš„ä¸æ–‡ç¿»è¯‘ +Documentation/admin-guide/gpio çš„ä¸æ–‡ç¿»è¯‘ 如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ 交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt index 368ddd05b304..c5f3bda7abcb 100644 --- a/Documentation/translations/zh_CN/oops-tracing.txt +++ b/Documentation/translations/zh_CN/oops-tracing.txt @@ -53,8 +53,8 @@ cat /proc/kmsg > file， ç„¶è€Œä½ å¿…é¡»ä»‹å…¥ä¸æ¢ä¼ 输， kmsgæ˜¯ä¸€ä¸ªâ€œæ° ï¼ˆ2）用串å£ç»ˆç«¯å¯åŠ¨ï¼ˆè¯·å‚看Documentation/admin-guide/serial-console.rst），è¿è¡Œä¸€ä¸ªnull modem到å¦ä¸€å°æœºå™¨å¹¶ç”¨ä½ 喜欢的通讯工具获å–输出。Minicom工作地很好。 -（3）使用Kdump（请å‚看Documentation/kdump/kdump.rst）， -使用在Documentation/kdump/gdbmacros.txtä¸å®šä¹‰çš„dmesg gdbå®ï¼Œä»Žæ—§çš„内å˜ä¸æå–å†…æ ¸ +（3）使用Kdump（请å‚看Documentation/admin-guide/kdump/kdump.rst）， +使用在Documentation/admin-guide/kdump/gdbmacros.txtä¸å®šä¹‰çš„dmesg gdbå®ï¼Œä»Žæ—§çš„内å˜ä¸æå–å†…æ ¸ 环形缓冲区。 å®Œæ•´ä¿¡æ¯ diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index f4785d2b0491..8738c55e42a2 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -97,7 +97,7 @@ Linuxå†…æ ¸è¡¥ä¸æäº¤æ¸…å• 24) 所有内å˜å±éšœä¾‹å¦‚ ``barrier()``, ``rmb()``, ``wmb()`` 都需è¦æºä»£ç ä¸çš„注 释æ¥è§£é‡Šå®ƒä»¬æ£åœ¨æ‰§è¡Œçš„æ“作åŠå…¶åŽŸå› 的逻辑。 -25) 如果补ä¸æ·»åŠ 了任何ioctl，那么也è¦æ›´æ–° ``Documentation/ioctl/ioctl-number.txt`` +25) 如果补ä¸æ·»åŠ 了任何ioctl，那么也è¦æ›´æ–° ``Documentation/ioctl/ioctl-number.rst`` 26) 如果修改åŽçš„æºä»£ç ä¾èµ–或使用与以下 ``Kconfig`` 符å·ç›¸å…³çš„ä»»ä½•å†…æ ¸API或 功能，则在ç¦ç”¨ç›¸å…³ ``Kconfig`` 符å·å’Œ/或 ``=m`` （如果该选项å¯ç”¨ï¼‰çš„情况 diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst index 72f4f45c98de..d99885c27aed 100644 --- a/Documentation/translations/zh_CN/process/submitting-drivers.rst +++ b/Documentation/translations/zh_CN/process/submitting-drivers.rst @@ -97,7 +97,7 @@ Linux 2.6: 函数定义æˆè¿”回 -ENOSYSï¼ˆåŠŸèƒ½æœªå®žçŽ°ï¼‰é”™è¯¯ã€‚ä½ è¿˜åº”è¯¥å°è¯•ç¡® ä¿ä½ 的驱动在什么都ä¸å¹²çš„情况下将耗电é™åˆ°æœ€ä½Žã€‚è¦èŽ·å¾—驱动 程åºæµ‹è¯•çš„指导，请å‚阅 - Documentation/power/drivers-testing.txt。有关驱动程åºç”µ + Documentation/power/drivers-testing.rst。有关驱动程åºç”µ æºç®¡ç†é—®é¢˜ç›¸å¯¹å…¨é¢çš„概述，请å‚阅 Documentation/driver-api/pm/devices.rst。 diff --git a/Documentation/translations/zh_CN/sparse.txt b/Documentation/translations/zh_CN/sparse.txt index 47fc4a06ebe8..0f444b83d639 100644 --- a/Documentation/translations/zh_CN/sparse.txt +++ b/Documentation/translations/zh_CN/sparse.txt @@ -73,10 +73,6 @@ __bitwise"类型。 git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git -DaveJ 把æ¯å°æ—¶è‡ªåŠ¨ç”Ÿæˆçš„ git æºç æ ‘ tar 包放在以下地å€ï¼š - - http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ - ä¸€æ—¦ä½ ä¸‹è½½äº†æºç ，åªè¦ä»¥æ™®é€šç”¨æˆ·èº«ä»½è¿è¡Œï¼š make diff --git a/Documentation/accelerators/ocxl.rst b/Documentation/userspace-api/accelerators/ocxl.rst index b1cea19a90f5..14cefc020e2d 100644 --- a/Documentation/accelerators/ocxl.rst +++ b/Documentation/userspace-api/accelerators/ocxl.rst @@ -1,5 +1,3 @@ -:orphan: - ======================================================== OpenCAPI (Open Coherent Accelerator Processor Interface) ======================================================== diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index a3233da7fa88..ad494da40009 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -20,6 +20,7 @@ place where this information is gathered. seccomp_filter unshare spec_ctrl + accelerators/ocxl .. only:: subproject and html diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst index 7cdf7282e022..7d90964abbb0 100644 --- a/Documentation/vm/hmm.rst +++ b/Documentation/vm/hmm.rst @@ -10,7 +10,7 @@ of this being specialized struct page for such memory (see sections 5 to 7 of this document). HMM also provides optional helpers for SVM (Share Virtual Memory), i.e., -allowing a device to transparently access program address coherently with +allowing a device to transparently access program addresses coherently with the CPU meaning that any valid pointer on the CPU is also a valid pointer for the device. This is becoming mandatory to simplify the use of advanced heterogeneous computing where GPU, DSP, or FPGA are used to perform various @@ -22,8 +22,8 @@ expose the hardware limitations that are inherent to many platforms. The third section gives an overview of the HMM design. The fourth section explains how CPU page-table mirroring works and the purpose of HMM in this context. The fifth section deals with how device memory is represented inside the kernel. -Finally, the last section presents a new migration helper that allows lever- -aging the device DMA engine. +Finally, the last section presents a new migration helper that allows +leveraging the device DMA engine. .. contents:: :local: @@ -39,20 +39,20 @@ address space. I use shared address space to refer to the opposite situation: i.e., one in which any application memory region can be used by a device transparently. -Split address space happens because device can only access memory allocated -through device specific API. This implies that all memory objects in a program +Split address space happens because devices can only access memory allocated +through a device specific API. This implies that all memory objects in a program are not equal from the device point of view which complicates large programs that rely on a wide set of libraries. -Concretely this means that code that wants to leverage devices like GPUs needs -to copy object between generically allocated memory (malloc, mmap private, mmap +Concretely, this means that code that wants to leverage devices like GPUs needs +to copy objects between generically allocated memory (malloc, mmap private, mmap share) and memory allocated through the device driver API (this still ends up with an mmap but of the device file). For flat data sets (array, grid, image, ...) this isn't too hard to achieve but -complex data sets (list, tree, ...) are hard to get right. Duplicating a +for complex data sets (list, tree, ...) it's hard to get right. Duplicating a complex data set needs to re-map all the pointer relations between each of its -elements. This is error prone and program gets harder to debug because of the +elements. This is error prone and programs get harder to debug because of the duplicate data set and addresses. Split address space also means that libraries cannot transparently use data @@ -77,12 +77,12 @@ I/O bus, device memory characteristics I/O buses cripple shared address spaces due to a few limitations. Most I/O buses only allow basic memory access from device to main memory; even cache -coherency is often optional. Access to device memory from CPU is even more +coherency is often optional. Access to device memory from a CPU is even more limited. More often than not, it is not cache coherent. If we only consider the PCIE bus, then a device can access main memory (often through an IOMMU) and be cache coherent with the CPUs. However, it only allows -a limited set of atomic operations from device on main memory. This is worse +a limited set of atomic operations from the device on main memory. This is worse in the other direction: the CPU can only access a limited range of the device memory and cannot perform atomic operations on it. Thus device memory cannot be considered the same as regular memory from the kernel point of view. @@ -93,20 +93,20 @@ The final limitation is latency. Access to main memory from the device has an order of magnitude higher latency than when the device accesses its own memory. Some platforms are developing new I/O buses or additions/modifications to PCIE -to address some of these limitations (OpenCAPI, CCIX). They mainly allow two- -way cache coherency between CPU and device and allow all atomic operations the +to address some of these limitations (OpenCAPI, CCIX). They mainly allow +two-way cache coherency between CPU and device and allow all atomic operations the architecture supports. Sadly, not all platforms are following this trend and some major architectures are left without hardware solutions to these problems. So for shared address space to make sense, not only must we allow devices to access any memory but we must also permit any memory to be migrated to device -memory while device is using it (blocking CPU access while it happens). +memory while the device is using it (blocking CPU access while it happens). Shared address space and migration ================================== -HMM intends to provide two main features. First one is to share the address +HMM intends to provide two main features. The first one is to share the address space by duplicating the CPU page table in the device page table so the same address points to the same physical memory for any valid main memory address in the process address space. @@ -121,14 +121,14 @@ why HMM provides helpers to factor out everything that can be while leaving the hardware specific details to the device driver. The second mechanism HMM provides is a new kind of ZONE_DEVICE memory that -allows allocating a struct page for each page of the device memory. Those pages +allows allocating a struct page for each page of device memory. Those pages are special because the CPU cannot map them. However, they allow migrating main memory to device memory using existing migration mechanisms and everything -looks like a page is swapped out to disk from the CPU point of view. Using a -struct page gives the easiest and cleanest integration with existing mm mech- -anisms. Here again, HMM only provides helpers, first to hotplug new ZONE_DEVICE +looks like a page that is swapped out to disk from the CPU point of view. Using a +struct page gives the easiest and cleanest integration with existing mm +mechanisms. Here again, HMM only provides helpers, first to hotplug new ZONE_DEVICE memory for the device memory and second to perform migration. Policy decisions -of what and when to migrate things is left to the device driver. +of what and when to migrate is left to the device driver. Note that any CPU access to a device page triggers a page fault and a migration back to main memory. For example, when a page backing a given CPU address A is @@ -136,8 +136,8 @@ migrated from a main memory page to a device page, then any CPU access to address A triggers a page fault and initiates a migration back to main memory. With these two features, HMM not only allows a device to mirror process address -space and keeping both CPU and device page table synchronized, but also lever- -ages device memory by migrating the part of the data set that is actively being +space and keeps both CPU and device page tables synchronized, but also +leverages device memory by migrating the part of the data set that is actively being used by the device. @@ -151,21 +151,28 @@ registration of an hmm_mirror struct:: int hmm_mirror_register(struct hmm_mirror *mirror, struct mm_struct *mm); - int hmm_mirror_register_locked(struct hmm_mirror *mirror, - struct mm_struct *mm); - -The locked variant is to be used when the driver is already holding mmap_sem -of the mm in write mode. The mirror struct has a set of callbacks that are used +The mirror struct has a set of callbacks that are used to propagate CPU page tables:: struct hmm_mirror_ops { + /* release() - release hmm_mirror + * + * @mirror: pointer to struct hmm_mirror + * + * This is called when the mm_struct is being released. The callback + * must ensure that all access to any pages obtained from this mirror + * is halted before the callback returns. All future access should + * fault. + */ + void (*release)(struct hmm_mirror *mirror); + /* sync_cpu_device_pagetables() - synchronize page tables * * @mirror: pointer to struct hmm_mirror - * @update_type: type of update that occurred to the CPU page table - * @start: virtual start address of the range to update - * @end: virtual end address of the range to update + * @update: update information (see struct mmu_notifier_range) + * Return: -EAGAIN if update.blockable false and callback need to + * block, 0 otherwise. * * This callback ultimately originates from mmu_notifiers when the CPU * page table is updated. The device driver must update its page table @@ -176,14 +183,12 @@ to propagate CPU page tables:: * page tables are completely updated (TLBs flushed, etc); this is a * synchronous call. */ - void (*update)(struct hmm_mirror *mirror, - enum hmm_update action, - unsigned long start, - unsigned long end); + int (*sync_cpu_device_pagetables)(struct hmm_mirror *mirror, + const struct hmm_update *update); }; The device driver must perform the update action to the range (mark range -read only, or fully unmap, ...). The device must be done with the update before +read only, or fully unmap, etc.). The device must complete the update before the driver callback returns. When the device driver wants to populate a range of virtual addresses, it can @@ -194,17 +199,18 @@ use either:: The first one (hmm_range_snapshot()) will only fetch present CPU page table entries and will not trigger a page fault on missing or non-present entries. -The second one does trigger a page fault on missing or read-only entry if the -write parameter is true. Page faults use the generic mm page fault code path -just like a CPU page fault. +The second one does trigger a page fault on missing or read-only entries if +write access is requested (see below). Page faults use the generic mm page +fault code path just like a CPU page fault. Both functions copy CPU page table entries into their pfns array argument. Each entry in that array corresponds to an address in the virtual range. HMM provides a set of flags to help the driver identify special CPU page table entries. -Locking with the update() callback is the most important aspect the driver must -respect in order to keep things properly synchronized. The usage pattern is:: +Locking within the sync_cpu_device_pagetables() callback is the most important +aspect the driver must respect in order to keep things properly synchronized. +The usage pattern is:: int driver_populate_range(...) { @@ -239,11 +245,11 @@ respect in order to keep things properly synchronized. The usage pattern is:: hmm_range_wait_until_valid(&range, TIMEOUT_IN_MSEC); goto again; } - hmm_mirror_unregister(&range); + hmm_range_unregister(&range); return ret; } take_lock(driver->update); - if (!range.valid) { + if (!hmm_range_valid(&range)) { release_lock(driver->update); up_read(&mm->mmap_sem); goto again; @@ -251,15 +257,15 @@ respect in order to keep things properly synchronized. The usage pattern is:: // Use pfns array content to update device page table - hmm_mirror_unregister(&range); + hmm_range_unregister(&range); release_lock(driver->update); up_read(&mm->mmap_sem); return 0; } The driver->update lock is the same lock that the driver takes inside its -update() callback. That lock must be held before checking the range.valid -field to avoid any race with a concurrent CPU page table update. +sync_cpu_device_pagetables() callback. That lock must be held before calling +hmm_range_valid() to avoid any race with a concurrent CPU page table update. HMM implements all this on top of the mmu_notifier API because we wanted a simpler API and also to be able to perform optimizations latter on like doing @@ -279,46 +285,47 @@ concurrently). Leverage default_flags and pfn_flags_mask ========================================= -The hmm_range struct has 2 fields default_flags and pfn_flags_mask that allows -to set fault or snapshot policy for a whole range instead of having to set them -for each entries in the range. +The hmm_range struct has 2 fields, default_flags and pfn_flags_mask, that specify +fault or snapshot policy for the whole range instead of having to set them +for each entry in the pfns array. + +For instance, if the device flags for range.flags are:: -For instance if the device flags for device entries are: - VALID (1 << 63) - WRITE (1 << 62) + range.flags[HMM_PFN_VALID] = (1 << 63); + range.flags[HMM_PFN_WRITE] = (1 << 62); -Now let say that device driver wants to fault with at least read a range then -it does set:: +and the device driver wants pages for a range with at least read permission, +it sets:: range->default_flags = (1 << 63); range->pfn_flags_mask = 0; -and calls hmm_range_fault() as described above. This will fill fault all page +and calls hmm_range_fault() as described above. This will fill fault all pages in the range with at least read permission. -Now let say driver wants to do the same except for one page in the range for -which its want to have write. Now driver set:: +Now let's say the driver wants to do the same except for one page in the range for +which it wants to have write permission. Now driver set:: range->default_flags = (1 << 63); range->pfn_flags_mask = (1 << 62); range->pfns[index_of_write] = (1 << 62); -With this HMM will fault in all page with at least read (ie valid) and for the +With this, HMM will fault in all pages with at least read (i.e., valid) and for the address == range->start + (index_of_write << PAGE_SHIFT) it will fault with -write permission ie if the CPU pte does not have write permission set then HMM +write permission i.e., if the CPU pte does not have write permission set then HMM will call handle_mm_fault(). -Note that HMM will populate the pfns array with write permission for any entry -that have write permission within the CPU pte no matter what are the values set +Note that HMM will populate the pfns array with write permission for any page +that is mapped with CPU write permission no matter what values are set in default_flags or pfn_flags_mask. Represent and manage device memory from core kernel point of view ================================================================= -Several different designs were tried to support device memory. First one used -a device specific data structure to keep information about migrated memory and -HMM hooked itself in various places of mm code to handle any access to +Several different designs were tried to support device memory. The first one +used a device specific data structure to keep information about migrated memory +and HMM hooked itself in various places of mm code to handle any access to addresses that were backed by device memory. It turns out that this ended up replicating most of the fields of struct page and also needed many kernel code paths to be updated to understand this new kind of memory. @@ -329,33 +336,6 @@ directly using struct page for device memory which left most kernel code paths unaware of the difference. We only need to make sure that no one ever tries to map those pages from the CPU side. -HMM provides a set of helpers to register and hotplug device memory as a new -region needing a struct page. This is offered through a very simple API:: - - struct hmm_devmem *hmm_devmem_add(const struct hmm_devmem_ops *ops, - struct device *device, - unsigned long size); - void hmm_devmem_remove(struct hmm_devmem *devmem); - -The hmm_devmem_ops is where most of the important things are:: - - struct hmm_devmem_ops { - void (*free)(struct hmm_devmem *devmem, struct page *page); - int (*fault)(struct hmm_devmem *devmem, - struct vm_area_struct *vma, - unsigned long addr, - struct page *page, - unsigned flags, - pmd_t *pmdp); - }; - -The first callback (free()) happens when the last reference on a device page is -dropped. This means the device page is now free and no longer used by anyone. -The second callback happens whenever the CPU tries to access a device page -which it cannot do. This second callback must trigger a migration back to -system memory. - - Migration to and from device memory =================================== @@ -417,9 +397,9 @@ willing to pay to keep all the code simpler. Memory cgroup (memcg) and rss accounting ======================================== -For now device memory is accounted as any regular page in rss counters (either +For now, device memory is accounted as any regular page in rss counters (either anonymous if device page is used for anonymous, file if device page is used for -file backed page or shmem if device page is used for shared memory). This is a +file backed page, or shmem if device page is used for shared memory). This is a deliberate choice to keep existing applications, that might start using device memory without knowing about it, running unimpacted. @@ -439,6 +419,6 @@ get more experience in how device memory is used and its impact on memory resource control. -Note that device memory can never be pinned by device driver nor through GUP +Note that device memory can never be pinned by a device driver nor through GUP and thus such memory is always free upon process exit. Or when last reference is dropped in case of shared memory or file backed memory. diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst index 382f72ace1fc..58a12376b7df 100644 --- a/Documentation/vm/memory-model.rst +++ b/Documentation/vm/memory-model.rst @@ -181,3 +181,43 @@ that is eventually passed to vmemmap_populate() through a long chain of function calls. The vmemmap_populate() implementation may use the `vmem_altmap` along with :c:func:`altmap_alloc_block_buf` helper to allocate memory map on the persistent memory device. + +ZONE_DEVICE +=========== +The `ZONE_DEVICE` facility builds upon `SPARSEMEM_VMEMMAP` to offer +`struct page` `mem_map` services for device driver identified physical +address ranges. The "device" aspect of `ZONE_DEVICE` relates to the fact +that the page objects for these address ranges are never marked online, +and that a reference must be taken against the device, not just the page +to keep the memory pinned for active use. `ZONE_DEVICE`, via +:c:func:`devm_memremap_pages`, performs just enough memory hotplug to +turn on :c:func:`pfn_to_page`, :c:func:`page_to_pfn`, and +:c:func:`get_user_pages` service for the given range of pfns. Since the +page reference count never drops below 1 the page is never tracked as +free memory and the page's `struct list_head lru` space is repurposed +for back referencing to the host device / driver that mapped the memory. + +While `SPARSEMEM` presents memory as a collection of sections, +optionally collected into memory blocks, `ZONE_DEVICE` users have a need +for smaller granularity of populating the `mem_map`. Given that +`ZONE_DEVICE` memory is never marked online it is subsequently never +subject to its memory ranges being exposed through the sysfs memory +hotplug api on memory block boundaries. The implementation relies on +this lack of user-api constraint to allow sub-section sized memory +ranges to be specified to :c:func:`arch_add_memory`, the top-half of +memory hotplug. Sub-section support allows for 2MB as the cross-arch +common alignment granularity for :c:func:`devm_memremap_pages`. + +The users of `ZONE_DEVICE` are: + +* pmem: Map platform persistent memory to be used as a direct-I/O target + via DAX mappings. + +* hmm: Extend `ZONE_DEVICE` with `->page_fault()` and `->page_free()` + event callbacks to allow a device-driver to coordinate memory management + events related to device-memory, typically GPU memory. See + Documentation/vm/hmm.rst. + +* p2pdma: Create `struct page` objects to allow peer devices in a + PCI/-E topology to coordinate direct-DMA operations between themselves, + i.e. bypass host memory. diff --git a/Documentation/vm/numa.rst b/Documentation/vm/numa.rst index 130f3cfa1c19..99fdeca917ca 100644 --- a/Documentation/vm/numa.rst +++ b/Documentation/vm/numa.rst @@ -67,7 +67,7 @@ nodes. Each emulated node will manage a fraction of the underlying cells' physical memory. NUMA emluation is useful for testing NUMA kernel and application features on non-NUMA platforms, and as a sort of memory resource management mechanism when used together with cpusets. -[see Documentation/cgroup-v1/cpusets.rst] +[see Documentation/admin-guide/cgroup-v1/cpusets.rst] For each node with memory, Linux constructs an independent memory management subsystem, complete with its own free page lists, in-use page lists, usage @@ -114,7 +114,7 @@ allocation behavior using Linux NUMA memory policy. [see System administrators can restrict the CPUs and nodes' memories that a non- privileged user can specify in the scheduling or NUMA commands and functions -using control groups and CPUsets. [see Documentation/cgroup-v1/cpusets.rst] +using control groups and CPUsets. [see Documentation/admin-guide/cgroup-v1/cpusets.rst] On architectures that do not hide memoryless nodes, Linux will include only zones [nodes] with memory in the zonelists. This means that for a memoryless diff --git a/Documentation/vm/page_migration.rst b/Documentation/vm/page_migration.rst index 35bba27d5fff..1d6cd7db4e43 100644 --- a/Documentation/vm/page_migration.rst +++ b/Documentation/vm/page_migration.rst @@ -41,7 +41,7 @@ locations. Larger installations usually partition the system using cpusets into sections of nodes. Paul Jackson has equipped cpusets with the ability to move pages when a task is moved to another cpuset (See -Documentation/cgroup-v1/cpusets.rst). +Documentation/admin-guide/cgroup-v1/cpusets.rst). Cpusets allows the automation of process locality. If a task is moved to a new cpuset then also all its pages are moved with it so that the performance of the process does not sink dramatically. Also the pages diff --git a/Documentation/vm/unevictable-lru.rst b/Documentation/vm/unevictable-lru.rst index c6d94118fbcc..17d0861b0f1d 100644 --- a/Documentation/vm/unevictable-lru.rst +++ b/Documentation/vm/unevictable-lru.rst @@ -98,7 +98,7 @@ Memory Control Group Interaction -------------------------------- The unevictable LRU facility interacts with the memory control group [aka -memory controller; see Documentation/cgroup-v1/memory.rst] by extending the +memory controller; see Documentation/admin-guide/cgroup-v1/memory.rst] by extending the lru_list enum. The memory controller data structure automatically gets a per-zone unevictable @@ -439,7 +439,7 @@ Compacting MLOCKED Pages The unevictable LRU can be scanned for compactable regions and the default behavior is to do so. /proc/sys/vm/compact_unevictable_allowed controls -this behavior (see Documentation/sysctl/vm.txt). Once scanning of the +this behavior (see Documentation/admin-guide/sysctl/vm.rst). Once scanning of the unevictable LRU is enabled, the work of compaction is mostly handled by the page migration code and the same work flow as described in MIGRATING MLOCKED PAGES will apply. diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1.netlink index ef2727192d69..94ad4c420828 100644 --- a/Documentation/w1/w1.netlink +++ b/Documentation/w1/w1.netlink @@ -183,7 +183,7 @@ acknowledge number is set to seq+1. Additional documantion, source code examples. ============================================ -1. Documentation/connector +1. Documentation/driver-api/connector.rst 2. http://www.ioremap.net/archive/w1 This archive includes userspace application w1d.c which uses read/write/search commands for all master/slave devices found on the bus. diff --git a/Documentation/watchdog/hpwdt.rst b/Documentation/watchdog/hpwdt.rst index 94a96371113e..c165d92cfd12 100644 --- a/Documentation/watchdog/hpwdt.rst +++ b/Documentation/watchdog/hpwdt.rst @@ -39,6 +39,10 @@ Last reviewed: 08/20/2018 Default value is set when compiling the kernel. If it is set to "Y", then there is no way of disabling the watchdog once it has been started. + kdumptimeout Minimum timeout in seconds to apply upon receipt of an NMI + before calling panic. (-1) disables the watchdog. When value + is > 0, the timer is reprogrammed with the greater of + value or current timeout value. ============ ================================================================ NOTE: diff --git a/Documentation/watchdog/index.rst b/Documentation/watchdog/index.rst index 33a0de631e84..c177645081d8 100644 --- a/Documentation/watchdog/index.rst +++ b/Documentation/watchdog/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ====================== Linux Watchdog Support diff --git a/Documentation/watchdog/watchdog-parameters.rst b/Documentation/watchdog/watchdog-parameters.rst index b121caae7798..a3985cc5aeda 100644 --- a/Documentation/watchdog/watchdog-parameters.rst +++ b/Documentation/watchdog/watchdog-parameters.rst @@ -13,6 +13,17 @@ modules. ------------------------------------------------- +watchdog core: + open_timeout: + Maximum time, in seconds, for which the watchdog framework will take + care of pinging a running hardware watchdog until userspace opens the + corresponding /dev/watchdogN device. A value of 0 means an infinite + timeout. Setting this to a non-zero value can be useful to ensure that + either userspace comes up properly, or the board gets reset and allows + fallback logic in the bootloader to try something else. + +------------------------------------------------- + acquirewdt: wdt_stop: Acquire WDT 'stop' io port (default 0x43) diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst index f2de1b2d3ac7..af64c4bb4447 100644 --- a/Documentation/x86/index.rst +++ b/Documentation/x86/index.rst @@ -20,6 +20,8 @@ x86-specific Documentation mtrr pat intel_mpx + intel-iommu + intel_txt amd-memory-encryption pti mds diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/x86/intel-iommu.rst index 9dae6b47e398..9dae6b47e398 100644 --- a/Documentation/Intel-IOMMU.txt +++ b/Documentation/x86/intel-iommu.rst diff --git a/Documentation/intel_txt.txt b/Documentation/x86/intel_txt.rst index d83c1a2122c9..d83c1a2122c9 100644 --- a/Documentation/intel_txt.txt +++ b/Documentation/x86/intel_txt.rst diff --git a/Documentation/x86/topology.rst b/Documentation/x86/topology.rst index 8e9704f61017..e29739904e37 100644 --- a/Documentation/x86/topology.rst +++ b/Documentation/x86/topology.rst @@ -9,7 +9,7 @@ representation in the kernel. Update/change when doing changes to the respective code. The architecture-agnostic topology definitions are in -Documentation/cputopology.txt. This file holds x86-specific +Documentation/admin-guide/cputopology.rst. This file holds x86-specific differences/specialities which must not necessarily apply to the generic definitions. Thus, the way to read up on Linux topology on x86 is to start with the generic one and look at this one in parallel for the x86 specifics. diff --git a/Documentation/x86/x86_64/fake-numa-for-cpusets.rst b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst index 30108684ae87..ff9bcfd2cc14 100644 --- a/Documentation/x86/x86_64/fake-numa-for-cpusets.rst +++ b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst @@ -15,7 +15,7 @@ assign them to cpusets and their attached tasks. This is a way of limiting the amount of system memory that are available to a certain class of tasks. For more information on the features of cpusets, see -Documentation/cgroup-v1/cpusets.rst. +Documentation/admin-guide/cgroup-v1/cpusets.rst. There are a number of different configurations you can use for your needs. For more information on the numa=fake command line option and its various ways of configuring fake nodes, see Documentation/x86/x86_64/boot-options.rst. @@ -40,7 +40,7 @@ A machine may be split as follows with "numa=fake=4*512," as reported by dmesg:: On node 3 totalpages: 131072 Now following the instructions for mounting the cpusets filesystem from -Documentation/cgroup-v1/cpusets.rst, you can assign fake nodes (i.e. contiguous memory +Documentation/admin-guide/cgroup-v1/cpusets.rst, you can assign fake nodes (i.e. contiguous memory address spaces) to individual cpusets:: [root@xroads /]# mkdir exampleset diff --git a/Documentation/xtensa/atomctl.txt b/Documentation/xtensa/atomctl.rst index 1da783ac200c..1ecbd0ba9a2e 100644 --- a/Documentation/xtensa/atomctl.txt +++ b/Documentation/xtensa/atomctl.rst @@ -1,3 +1,7 @@ +=========================================== +Atomic Operation Control (ATOMCTL) Register +=========================================== + We Have Atomic Operation Control (ATOMCTL) Register. This register determines the effect of using a S32C1I instruction with various combinations of: @@ -8,7 +12,7 @@ with various combinations of: 2. With and without An Intelligent Memory Controller which can do Atomic Transactions itself. -The Core comes up with a default value of for the three types of cache ops: +The Core comes up with a default value of for the three types of cache ops:: 0x28: (WB: Internal, WT: Internal, BY:Exception) @@ -30,15 +34,18 @@ CUSTOMER-WARNING: Developers might find using RCW in Bypass mode convenient when testing with the cache being bypassed; for example studying cache alias problems. -See Section 4.3.12.4 of ISA; Bits: +See Section 4.3.12.4 of ISA; Bits:: WB WT BY 5 4 | 3 2 | 1 0 + +========= ================== ================== =============== 2 Bit Field Values WB - Write Back WT - Write Thru BY - Bypass ---------- --------------- ----------------- ---------------- +========= ================== ================== =============== 0 Exception Exception Exception 1 RCW Transaction RCW Transaction RCW Transaction 2 Internal Operation Internal Operation Reserved 3 Reserved Reserved Reserved +========= ================== ================== =============== diff --git a/Documentation/xtensa/booting.txt b/Documentation/xtensa/booting.rst index 402b33a2619f..e1b83707e5b6 100644 --- a/Documentation/xtensa/booting.txt +++ b/Documentation/xtensa/booting.rst @@ -1,10 +1,13 @@ -Passing boot parameters to the kernel. +===================================== +Passing boot parameters to the kernel +===================================== Boot parameters are represented as a TLV list in the memory. Please see arch/xtensa/include/asm/bootparam.h for definition of the bp_tag structure and tag value constants. First entry in the list must have type BP_TAG_FIRST, last entry must have type BP_TAG_LAST. The address of the first list entry is passed to the kernel in the register a2. The address type depends on MMU type: + - For configurations without MMU, with region protection or with MPU the address must be the physical address. - For configurations with region translarion MMU or with MMUv3 and CONFIG_MMU=n diff --git a/Documentation/xtensa/index.rst b/Documentation/xtensa/index.rst new file mode 100644 index 000000000000..52fa04eb39a3 --- /dev/null +++ b/Documentation/xtensa/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +Xtensa Architecture +=================== + +.. toctree:: + :maxdepth: 1 + + atomctl + booting + mmu diff --git a/Documentation/xtensa/mmu.rst b/Documentation/xtensa/mmu.rst new file mode 100644 index 000000000000..e52a12960fdc --- /dev/null +++ b/Documentation/xtensa/mmu.rst @@ -0,0 +1,195 @@ +============================= +MMUv3 initialization sequence +============================= + +The code in the initialize_mmu macro sets up MMUv3 memory mapping +identically to MMUv2 fixed memory mapping. Depending on +CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is +located in addresses it was linked for (symbol undefined), or not +(symbol defined), so it needs to be position-independent. + +The code has the following assumptions: + + - This code fragment is run only on an MMU v3. + - TLBs are in their reset state. + - ITLBCFG and DTLBCFG are zero (reset state). + - RASID is 0x04030201 (reset state). + - PS.RING is zero (reset state). + - LITBASE is zero (reset state, PC-relative literals); required to be PIC. + +TLB setup proceeds along the following steps. + + Legend: + + - VA = virtual address (two upper nibbles of it); + - PA = physical address (two upper nibbles of it); + - pc = physical range that contains this code; + +After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff +or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below +0x40000000 or above. That address corresponds to next instruction to execute +in this code. After step 4, we jump to intended (linked) address of this code. +The scheme below assumes that the kernel is loaded below 0x40000000. + + ====== ===== ===== ===== ===== ====== ===== ===== + - Step0 Step1 Step2 Step3 Step4 Step5 + + VA PA PA PA PA VA PA PA + ====== ===== ===== ===== ===== ====== ===== ===== + E0..FF -> E0 -> E0 -> E0 F0..FF -> F0 -> F0 + C0..DF -> C0 -> C0 -> C0 E0..EF -> F0 -> F0 + A0..BF -> A0 -> A0 -> A0 D8..DF -> 00 -> 00 + 80..9F -> 80 -> 80 -> 80 D0..D7 -> 00 -> 00 + 60..7F -> 60 -> 60 -> 60 + 40..5F -> 40 -> pc -> pc 40..5F -> pc + 20..3F -> 20 -> 20 -> 20 + 00..1F -> 00 -> 00 -> 00 + ====== ===== ===== ===== ===== ====== ===== ===== + +The default location of IO peripherals is above 0xf0000000. This may be changed +using a "ranges" property in a device tree simple-bus node. See the Devicetree +Specification, section 4.5 for details on the syntax and semantics of +simple-bus nodes. The following limitations apply: + +1. Only top level simple-bus nodes are considered + +2. Only one (first) simple-bus node is considered + +3. Empty "ranges" properties are not supported + +4. Only the first triplet in the "ranges" property is considered + +5. The parent-bus-address value is rounded down to the nearest 256MB boundary + +6. The IO area covers the entire 256MB segment of parent-bus-address; the + "ranges" triplet length field is ignored + + +MMUv3 address space layouts. +============================ + +Default MMUv2-compatible layout:: + + Symbol VADDR Size + +------------------+ + | Userspace | 0x00000000 TASK_SIZE + +------------------+ 0x40000000 + +------------------+ + | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE + +------------------+ + | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE + +------------------+ 0x8e400000 + +------------------+ + | VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB + +------------------+ VMALLOC_END + | Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE + | remap area 1 | + +------------------+ + | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE + | remap area 2 | + +------------------+ + +------------------+ + | KMAP area | PKMAP_BASE PTRS_PER_PTE * + | | DCACHE_N_COLORS * + | | PAGE_SIZE + | | (4MB * DCACHE_N_COLORS) + +------------------+ + | Atomic KMAP area | FIXADDR_START KM_TYPE_NR * + | | NR_CPUS * + | | DCACHE_N_COLORS * + | | PAGE_SIZE + +------------------+ FIXADDR_TOP 0xcffff000 + +------------------+ + | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xd0000000 128MB + +------------------+ + | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xd8000000 128MB + +------------------+ + | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB + +------------------+ + | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB + +------------------+ + + +256MB cached + 256MB uncached layout:: + + Symbol VADDR Size + +------------------+ + | Userspace | 0x00000000 TASK_SIZE + +------------------+ 0x40000000 + +------------------+ + | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE + +------------------+ + | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE + +------------------+ 0x8e400000 + +------------------+ + | VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB + +------------------+ VMALLOC_END + | Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE + | remap area 1 | + +------------------+ + | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE + | remap area 2 | + +------------------+ + +------------------+ + | KMAP area | PKMAP_BASE PTRS_PER_PTE * + | | DCACHE_N_COLORS * + | | PAGE_SIZE + | | (4MB * DCACHE_N_COLORS) + +------------------+ + | Atomic KMAP area | FIXADDR_START KM_TYPE_NR * + | | NR_CPUS * + | | DCACHE_N_COLORS * + | | PAGE_SIZE + +------------------+ FIXADDR_TOP 0xaffff000 + +------------------+ + | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xb0000000 256MB + +------------------+ + | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 256MB + +------------------+ + +------------------+ + | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB + +------------------+ + | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB + +------------------+ + + +512MB cached + 512MB uncached layout:: + + Symbol VADDR Size + +------------------+ + | Userspace | 0x00000000 TASK_SIZE + +------------------+ 0x40000000 + +------------------+ + | Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE + +------------------+ + | KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE + +------------------+ 0x8e400000 + +------------------+ + | VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB + +------------------+ VMALLOC_END + | Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE + | remap area 1 | + +------------------+ + | Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE + | remap area 2 | + +------------------+ + +------------------+ + | KMAP area | PKMAP_BASE PTRS_PER_PTE * + | | DCACHE_N_COLORS * + | | PAGE_SIZE + | | (4MB * DCACHE_N_COLORS) + +------------------+ + | Atomic KMAP area | FIXADDR_START KM_TYPE_NR * + | | NR_CPUS * + | | DCACHE_N_COLORS * + | | PAGE_SIZE + +------------------+ FIXADDR_TOP 0x9ffff000 + +------------------+ + | Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xa0000000 512MB + +------------------+ + | Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 512MB + +------------------+ + | Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB + +------------------+ + | Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB + +------------------+ diff --git a/Documentation/xtensa/mmu.txt b/Documentation/xtensa/mmu.txt deleted file mode 100644 index 318114de63f3..000000000000 --- a/Documentation/xtensa/mmu.txt +++ /dev/null @@ -1,189 +0,0 @@ -MMUv3 initialization sequence. - -The code in the initialize_mmu macro sets up MMUv3 memory mapping -identically to MMUv2 fixed memory mapping. Depending on -CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is -located in addresses it was linked for (symbol undefined), or not -(symbol defined), so it needs to be position-independent. - -The code has the following assumptions: - This code fragment is run only on an MMU v3. - TLBs are in their reset state. - ITLBCFG and DTLBCFG are zero (reset state). - RASID is 0x04030201 (reset state). - PS.RING is zero (reset state). - LITBASE is zero (reset state, PC-relative literals); required to be PIC. - -TLB setup proceeds along the following steps. - - Legend: - VA = virtual address (two upper nibbles of it); - PA = physical address (two upper nibbles of it); - pc = physical range that contains this code; - -After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff -or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below -0x40000000 or above. That address corresponds to next instruction to execute -in this code. After step 4, we jump to intended (linked) address of this code. -The scheme below assumes that the kernel is loaded below 0x40000000. - - Step0 Step1 Step2 Step3 Step4 Step5 - ===== ===== ===== ===== ===== ===== - VA PA PA PA PA VA PA PA - ------ -- -- -- -- ------ -- -- - E0..FF -> E0 -> E0 -> E0 F0..FF -> F0 -> F0 - C0..DF -> C0 -> C0 -> C0 E0..EF -> F0 -> F0 - A0..BF -> A0 -> A0 -> A0 D8..DF -> 00 -> 00 - 80..9F -> 80 -> 80 -> 80 D0..D7 -> 00 -> 00 - 60..7F -> 60 -> 60 -> 60 - 40..5F -> 40 -> pc -> pc 40..5F -> pc - 20..3F -> 20 -> 20 -> 20 - 00..1F -> 00 -> 00 -> 00 - -The default location of IO peripherals is above 0xf0000000. This may be changed -using a "ranges" property in a device tree simple-bus node. See the Devicetree -Specification, section 4.5 for details on the syntax and semantics of -simple-bus nodes. The following limitations apply: - -1. Only top level simple-bus nodes are considered - -2. Only one (first) simple-bus node is considered - -3. Empty "ranges" properties are not supported - -4. Only the first triplet in the "ranges" property is considered - -5. The parent-bus-address value is rounded down to the nearest 256MB boundary - -6. The IO area covers the entire 256MB segment of parent-bus-address; the - "ranges" triplet length field is ignored - - -MMUv3 address space layouts. -============================ - -Default MMUv2-compatible layout. - - Symbol VADDR Size -+------------------+ -| Userspace | 0x00000000 TASK_SIZE -+------------------+ 0x40000000 -+------------------+ -| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE -+------------------+ -| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE -+------------------+ 0x8e400000 -+------------------+ -| VMALLOC area | VMALLOC_START 0xc0000000 128MB - 64KB -+------------------+ VMALLOC_END -| Cache aliasing | TLBTEMP_BASE_1 0xc7ff0000 DCACHE_WAY_SIZE -| remap area 1 | -+------------------+ -| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE -| remap area 2 | -+------------------+ -+------------------+ -| KMAP area | PKMAP_BASE PTRS_PER_PTE * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -| | (4MB * DCACHE_N_COLORS) -+------------------+ -| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * -| | NR_CPUS * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -+------------------+ FIXADDR_TOP 0xcffff000 -+------------------+ -| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xd0000000 128MB -+------------------+ -| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xd8000000 128MB -+------------------+ -| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB -+------------------+ -| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB -+------------------+ - - -256MB cached + 256MB uncached layout. - - Symbol VADDR Size -+------------------+ -| Userspace | 0x00000000 TASK_SIZE -+------------------+ 0x40000000 -+------------------+ -| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE -+------------------+ -| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE -+------------------+ 0x8e400000 -+------------------+ -| VMALLOC area | VMALLOC_START 0xa0000000 128MB - 64KB -+------------------+ VMALLOC_END -| Cache aliasing | TLBTEMP_BASE_1 0xa7ff0000 DCACHE_WAY_SIZE -| remap area 1 | -+------------------+ -| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE -| remap area 2 | -+------------------+ -+------------------+ -| KMAP area | PKMAP_BASE PTRS_PER_PTE * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -| | (4MB * DCACHE_N_COLORS) -+------------------+ -| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * -| | NR_CPUS * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -+------------------+ FIXADDR_TOP 0xaffff000 -+------------------+ -| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xb0000000 256MB -+------------------+ -| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 256MB -+------------------+ -+------------------+ -| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB -+------------------+ -| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB -+------------------+ - - -512MB cached + 512MB uncached layout. - - Symbol VADDR Size -+------------------+ -| Userspace | 0x00000000 TASK_SIZE -+------------------+ 0x40000000 -+------------------+ -| Page table | XCHAL_PAGE_TABLE_VADDR 0x80000000 XCHAL_PAGE_TABLE_SIZE -+------------------+ -| KASAN shadow map | KASAN_SHADOW_START 0x80400000 KASAN_SHADOW_SIZE -+------------------+ 0x8e400000 -+------------------+ -| VMALLOC area | VMALLOC_START 0x90000000 128MB - 64KB -+------------------+ VMALLOC_END -| Cache aliasing | TLBTEMP_BASE_1 0x97ff0000 DCACHE_WAY_SIZE -| remap area 1 | -+------------------+ -| Cache aliasing | TLBTEMP_BASE_2 DCACHE_WAY_SIZE -| remap area 2 | -+------------------+ -+------------------+ -| KMAP area | PKMAP_BASE PTRS_PER_PTE * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -| | (4MB * DCACHE_N_COLORS) -+------------------+ -| Atomic KMAP area | FIXADDR_START KM_TYPE_NR * -| | NR_CPUS * -| | DCACHE_N_COLORS * -| | PAGE_SIZE -+------------------+ FIXADDR_TOP 0x9ffff000 -+------------------+ -| Cached KSEG | XCHAL_KSEG_CACHED_VADDR 0xa0000000 512MB -+------------------+ -| Uncached KSEG | XCHAL_KSEG_BYPASS_VADDR 0xc0000000 512MB -+------------------+ -| Cached KIO | XCHAL_KIO_CACHED_VADDR 0xe0000000 256MB -+------------------+ -| Uncached KIO | XCHAL_KIO_BYPASS_VADDR 0xf0000000 256MB -+------------------+ |
