diff options
Diffstat (limited to 'Documentation')
565 files changed, 25176 insertions, 11061 deletions
diff --git a/Documentation/ABI/obsolete/sysfs-firmware-acpi b/Documentation/ABI/obsolete/sysfs-firmware-acpi new file mode 100644 index 000000000000..6715a71bec3d --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-firmware-acpi @@ -0,0 +1,8 @@ +What: /sys/firmware/acpi/hotplug/force_remove +Date: Mar 2017 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + Since the force_remove is inherently broken and dangerous to + use for some hotplugable resources like memory (because ignoring + the offline failure might lead to memory corruption and crashes) + enabling this knob is not safe and thus unsupported. diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb index 831f15d9672f..b832eeff9999 100644 --- a/Documentation/ABI/stable/sysfs-bus-usb +++ b/Documentation/ABI/stable/sysfs-bus-usb @@ -9,7 +9,7 @@ Description: hubs this facility is always enabled and their device directories will not contain this file. - For more information, see Documentation/usb/persist.txt. + For more information, see Documentation/driver-api/usb/persist.rst. What: /sys/bus/usb/devices/.../power/autosuspend Date: March 2007 diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso index 7cdfc28cc2c6..55406ec8a35a 100644 --- a/Documentation/ABI/stable/vdso +++ b/Documentation/ABI/stable/vdso @@ -16,7 +16,8 @@ The vDSO uses symbol versioning; whenever you request a symbol from the vDSO, specify the version you are expecting. Programs that dynamically link to glibc will use the vDSO automatically. -Otherwise, you can use the reference parser in Documentation/vDSO/parse_vdso.c. +Otherwise, you can use the reference parser in +tools/testing/selftests/vDSO/parse_vdso.c. Unless otherwise noted, the set of symbols with any given version and the ABI of those symbols is considered stable. It may vary across architectures, diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index 2da04ce6aeef..dea212db9df3 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -213,14 +213,8 @@ What: /sys/block/<disk>/queue/discard_zeroes_data Date: May 2011 Contact: Martin K. Petersen <martin.petersen@oracle.com> Description: - Devices that support discard functionality may return - stale or random data when a previously discarded block - is read back. This can cause problems if the filesystem - expects discarded blocks to be explicitly cleared. If a - device reports that it deterministically returns zeroes - when a discarded area is read the discard_zeroes_data - parameter will be set to one. Otherwise it will be 0 and - the result of reading a discarded area is undefined. + Will always return 0. Don't rely on any specific behavior + for discards, and don't read this file. What: /sys/block/<disk>/queue/write_same_max_bytes Date: January 2012 diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 530809ccfacf..8c24d0892f61 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -55,6 +55,7 @@ Description: then it is to be found in the base device directory. What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available +What: /sys/bus/iio/devices/iio:deviceX/in_proximity_sampling_frequency_available What: /sys/.../iio:deviceX/buffer/sampling_frequency_available What: /sys/bus/iio/devices/triggerX/sampling_frequency_available KernelVersion: 2.6.35 @@ -1593,7 +1594,7 @@ Description: can be processed to siemens per meter. What: /sys/bus/iio/devices/iio:deviceX/in_countY_raw -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Raw counter device counts from channel Y. For quadrature @@ -1601,10 +1602,24 @@ Description: the counts of a single quadrature signal phase from channel Y. What: /sys/bus/iio/devices/iio:deviceX/in_indexY_raw -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Raw counter device index value from channel Y. This attribute provides an absolute positional reference (e.g. a pulse once per revolution) which may be used to home positional systems as required. + +What: /sys/bus/iio/devices/iio:deviceX/in_count_count_direction_available +KernelVersion: 4.12 +Contact: linux-iio@vger.kernel.org +Description: + A list of possible counting directions which are: + - "up" : counter device is increasing. + - "down": counter device is decreasing. + +What: /sys/bus/iio/devices/iio:deviceX/in_countY_count_direction +KernelVersion: 4.12 +Contact: linux-iio@vger.kernel.org +Description: + Raw counter device counters direction for channel Y. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-max9611 b/Documentation/ABI/testing/sysfs-bus-iio-adc-max9611 new file mode 100644 index 000000000000..6d2d2b094941 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-max9611 @@ -0,0 +1,17 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_power_shunt_resistor +Date: March 2017 +KernelVersion: 4.12 +Contact: linux-iio@vger.kernel.org +Description: The value of the shunt resistor used to compute power drain on + common input voltage pin (RS+). In Ohms. + +What: /sys/bus/iio/devices/iio:deviceX/in_current_shunt_resistor +Date: March 2017 +KernelVersion: 4.12 +Contact: linux-iio@vger.kernel.org +Description: The value of the shunt resistor used to compute current flowing + between RS+ and RS- voltage sense inputs. In Ohms. + +These attributes describe a single physical component, exposed as two distinct +attributes as it is used to calculate two different values: power load and +current flowing between RS+ and RS- inputs. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 b/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 index ba676520b953..7fac2c268d9a 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 +++ b/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 @@ -1,24 +1,16 @@ -What: /sys/bus/iio/devices/iio:deviceX/in_count_count_direction_available What: /sys/bus/iio/devices/iio:deviceX/in_count_count_mode_available What: /sys/bus/iio/devices/iio:deviceX/in_count_noise_error_available What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available What: /sys/bus/iio/devices/iio:deviceX/in_index_index_polarity_available What: /sys/bus/iio/devices/iio:deviceX/in_index_synchronous_mode_available -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Discrete set of available values for the respective counter configuration are listed in this file. -What: /sys/bus/iio/devices/iio:deviceX/in_countY_count_direction -KernelVersion: 4.9 -Contact: linux-iio@vger.kernel.org -Description: - Read-only attribute that indicates whether the counter for - channel Y is counting up or down. - What: /sys/bus/iio/devices/iio:deviceX/in_countY_count_mode -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Count mode for channel Y. Four count modes are available: @@ -52,7 +44,7 @@ Description: continuously throughout. What: /sys/bus/iio/devices/iio:deviceX/in_countY_noise_error -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Read-only attribute that indicates whether excessive noise is @@ -60,14 +52,14 @@ Description: irrelevant in non-quadrature clock mode. What: /sys/bus/iio/devices/iio:deviceX/in_countY_preset -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: If the counter device supports preset registers, the preset count for channel Y is provided by this attribute. What: /sys/bus/iio/devices/iio:deviceX/in_countY_quadrature_mode -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Configure channel Y counter for non-quadrature or quadrature @@ -88,7 +80,7 @@ Description: decoded for UP/DN clock. What: /sys/bus/iio/devices/iio:deviceX/in_countY_set_to_preset_on_index -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Whether to set channel Y counter with channel Y preset value @@ -96,14 +88,14 @@ Description: Valid attribute values are boolean. What: /sys/bus/iio/devices/iio:deviceX/in_indexY_index_polarity -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Active level of channel Y index input; irrelevant in non-synchronous load mode. What: /sys/bus/iio/devices/iio:deviceX/in_indexY_synchronous_mode -KernelVersion: 4.9 +KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: Configure channel Y counter for non-synchronous or synchronous diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 index 6534a60037ff..230020e06677 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 @@ -3,11 +3,15 @@ KernelVersion: 4.11 Contact: benjamin.gaignard@st.com Description: Reading returns the list possible master modes which are: - - "reset" : The UG bit from the TIMx_EGR register is used as trigger output (TRGO). - - "enable" : The Counter Enable signal CNT_EN is used as trigger output. + - "reset" : The UG bit from the TIMx_EGR register is + used as trigger output (TRGO). + - "enable" : The Counter Enable signal CNT_EN is used + as trigger output. - "update" : The update event is selected as trigger output. - For instance a master timer can then be used as a prescaler for a slave timer. - - "compare_pulse" : The trigger output send a positive pulse when the CC1IF flag is to be set. + For instance a master timer can then be used + as a prescaler for a slave timer. + - "compare_pulse" : The trigger output send a positive pulse + when the CC1IF flag is to be set. - "OC1REF" : OC1REF signal is used as trigger output. - "OC2REF" : OC2REF signal is used as trigger output. - "OC3REF" : OC3REF signal is used as trigger output. @@ -27,3 +31,62 @@ Description: Reading returns the current sampling frequency. Writing an value different of 0 set and start sampling. Writing 0 stop sampling. + +What: /sys/bus/iio/devices/iio:deviceX/in_count0_preset +KernelVersion: 4.12 +Contact: benjamin.gaignard@st.com +Description: + Reading returns the current preset value. + Writing sets the preset value. + When counting up the counter starts from 0 and fires an + event when reach preset value. + When counting down the counter start from preset value + and fire event when reach 0. + +What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available +KernelVersion: 4.12 +Contact: benjamin.gaignard@st.com +Description: + Reading returns the list possible quadrature modes. + +What: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode +KernelVersion: 4.12 +Contact: benjamin.gaignard@st.com +Description: + Configure the device counter quadrature modes: + channel_A: + Encoder A input servers as the count input and B as + the UP/DOWN direction control input. + + channel_B: + Encoder B input serves as the count input and A as + the UP/DOWN direction control input. + + quadrature: + Encoder A and B inputs are mixed to get direction + and count with a scale of 0.25. + +What: /sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available +KernelVersion: 4.12 +Contact: benjamin.gaignard@st.com +Description: + Reading returns the list possible enable modes. + +What: /sys/bus/iio/devices/iio:deviceX/in_count0_enable_mode +KernelVersion: 4.12 +Contact: benjamin.gaignard@st.com +Description: + Configure the device counter enable modes, in all case + counting direction is set by in_count0_count_direction + attribute and the counter is clocked by the internal clock. + always: + Counter is always ON. + + gated: + Counting is enabled when connected trigger signal + level is high else counting is disabled. + + triggered: + Counting is enabled on rising edge of the connected + trigger, and remains enabled for the duration of this + selected mode. diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 5a1732b78707..44d4b2be92fd 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -299,5 +299,27 @@ What: /sys/bus/pci/devices/.../revision Date: November 2016 Contact: Emil Velikov <emil.l.velikov@gmail.com> Description: - This file contains the revision field of the the PCI device. + This file contains the revision field of the PCI device. The value comes from device config space. The file is read only. + +What: /sys/bus/pci/devices/.../sriov_drivers_autoprobe +Date: April 2017 +Contact: Bodong Wang<bodong@mellanox.com> +Description: + This file is associated with the PF of a device that + supports SR-IOV. It determines whether newly-enabled VFs + are immediately bound to a driver. It initially contains + 1, which means the kernel automatically binds VFs to a + compatible driver immediately after they are enabled. If + an application writes 0 to the file before enabling VFs, + the kernel will not bind VFs to a driver. + + A typical use case is to write 0 to this file, then enable + VFs, then assign the newly-created VFs to virtual machines. + Note that changing this file does not affect already- + enabled VFs. In this scenario, the user must first disable + the VFs, write 0 to sriov_drivers_autoprobe, then re-enable + the VFs. + + This is similar to /sys/bus/pci/drivers_autoprobe, but + affects only the VFs associated with a specific PF. diff --git a/Documentation/ABI/testing/sysfs-class-net-qmi b/Documentation/ABI/testing/sysfs-class-net-qmi index fa5a00bb1143..7122d6264c49 100644 --- a/Documentation/ABI/testing/sysfs-class-net-qmi +++ b/Documentation/ABI/testing/sysfs-class-net-qmi @@ -21,3 +21,30 @@ Description: is responsible for coordination of driver and firmware link framing mode, changing this setting to 'Y' if the firmware is configured for 'raw-ip' mode. + +What: /sys/class/net/<iface>/qmi/add_mux +Date: March 2017 +KernelVersion: 4.11 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Unsigned integer. + + Write a number ranging from 1 to 127 to add a qmap mux + based network device, supported by recent Qualcomm based + modems. + + The network device will be called qmimux. + + Userspace is in charge of managing the qmux network device + activation and data stream setup on the modem side by + using the proper QMI protocol requests. + +What: /sys/class/net/<iface>/qmi/del_mux +Date: March 2017 +KernelVersion: 4.11 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Unsigned integer. + + Write a number ranging from 1 to 127 to delete a previously + created qmap mux based network device. diff --git a/Documentation/ABI/testing/sysfs-class-switchtec b/Documentation/ABI/testing/sysfs-class-switchtec new file mode 100644 index 000000000000..48cb4c15e430 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-switchtec @@ -0,0 +1,96 @@ +switchtec - Microsemi Switchtec PCI Switch Management Endpoint + +For details on this subsystem look at Documentation/switchtec.txt. + +What: /sys/class/switchtec +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: The switchtec class subsystem folder. + Each registered switchtec driver is represented by a switchtecX + subfolder (X being an integer >= 0). + + +What: /sys/class/switchtec/switchtec[0-9]+/component_id +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Component identifier as stored in the hardware (eg. PM8543) + (read only) +Values: arbitrary string. + + +What: /sys/class/switchtec/switchtec[0-9]+/component_revision +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Component revision stored in the hardware (read only) +Values: integer. + + +What: /sys/class/switchtec/switchtec[0-9]+/component_vendor +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Component vendor as stored in the hardware (eg. MICROSEM) + (read only) +Values: arbitrary string. + + +What: /sys/class/switchtec/switchtec[0-9]+/device_version +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Device version as stored in the hardware (read only) +Values: integer. + + +What: /sys/class/switchtec/switchtec[0-9]+/fw_version +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Currently running firmware version (read only) +Values: integer (in hexadecimal). + + +What: /sys/class/switchtec/switchtec[0-9]+/partition +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Partition number for this device in the switch (read only) +Values: integer. + + +What: /sys/class/switchtec/switchtec[0-9]+/partition_count +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Total number of partitions in the switch (read only) +Values: integer. + + +What: /sys/class/switchtec/switchtec[0-9]+/product_id +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Product identifier as stored in the hardware (eg. PSX 48XG3) + (read only) +Values: arbitrary string. + + +What: /sys/class/switchtec/switchtec[0-9]+/product_revision +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Product revision stored in the hardware (eg. RevB) + (read only) +Values: arbitrary string. + + +What: /sys/class/switchtec/switchtec[0-9]+/product_vendor +Date: 05-Jan-2017 +KernelVersion: v4.11 +Contact: Logan Gunthorpe <logang@deltatee.com> +Description: Product vendor as stored in the hardware (eg. MICROSEM) + (read only) +Values: arbitrary string. diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec new file mode 100644 index 000000000000..d4a3d23eb09c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-typec @@ -0,0 +1,276 @@ +USB Type-C port devices (eg. /sys/class/typec/port0/) + +What: /sys/class/typec/<port>/data_role +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The supported USB data roles. This attribute can be used for + requesting data role swapping on the port. Swapping is supported + as synchronous operation, so write(2) to the attribute will not + return until the operation has finished. The attribute is + notified about role changes so that poll(2) on the attribute + wakes up. Change on the role will also generate uevent + KOBJ_CHANGE on the port. The current role is show in brackets, + for example "[host] device" when DRP port is in host mode. + + Valid values: host, device + +What: /sys/class/typec/<port>/power_role +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The supported power roles. This attribute can be used to request + power role swap on the port when the port supports USB Power + Delivery. Swapping is supported as synchronous operation, so + write(2) to the attribute will not return until the operation + has finished. The attribute is notified about role changes so + that poll(2) on the attribute wakes up. Change on the role will + also generate uevent KOBJ_CHANGE. The current role is show in + brackets, for example "[source] sink" when in source mode. + + Valid values: source, sink + +What: /sys/class/typec/<port>/vconn_source +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows is the port VCONN Source. This attribute can be used to + request VCONN swap to change the VCONN Source during connection + when both the port and the partner support USB Power Delivery. + Swapping is supported as synchronous operation, so write(2) to + the attribute will not return until the operation has finished. + The attribute is notified about VCONN source changes so that + poll(2) on the attribute wakes up. Change on VCONN source also + generates uevent KOBJ_CHANGE. + + Valid values: + - "no" when the port is not the VCONN Source + - "yes" when the port is the VCONN Source + +What: /sys/class/typec/<port>/power_operation_mode +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows the current power operational mode the port is in. The + power operation mode means current level for VBUS. In case USB + Power Delivery communication is used for negotiating the levels, + power operation mode should show "usb_power_delivery". + + Valid values: + - default + - 1.5A + - 3.0A + - usb_power_delivery + +What: /sys/class/typec/<port>/preferred_role +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The user space can notify the driver about the preferred role. + It should be handled as enabling of Try.SRC or Try.SNK, as + defined in USB Type-C specification, in the port drivers. By + default the preferred role should come from the platform. + + Valid values: source, sink, none (to remove preference) + +What: /sys/class/typec/<port>/supported_accessory_modes +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Space separated list of accessory modes, defined in the USB + Type-C specification, the port supports. + +What: /sys/class/typec/<port>/usb_power_delivery_revision +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Revision number of the supported USB Power Delivery + specification, or 0 when USB Power Delivery is not supported. + +What: /sys/class/typec/<port>/usb_typec_revision +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Revision number of the supported USB Type-C specification. + + +USB Type-C partner devices (eg. /sys/class/typec/port0-partner/) + +What: /sys/class/typec/<port>-partner/accessory_mode +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows the Accessory Mode name when the partner is an Accessory. + The Accessory Modes are defined in USB Type-C Specification. + +What: /sys/class/typec/<port>-partner/supports_usb_power_delivery +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows if the partner supports USB Power Delivery communication: + Valid values: yes, no + +What: /sys/class/typec/<port>-partner>/identity/ +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + This directory appears only if the port device driver is capable + of showing the result of Discover Identity USB power delivery + command. That will not always be possible even when USB power + delivery is supported, for example when USB power delivery + communication for the port is mostly handled in firmware. If the + directory exists, it will have an attribute file for every VDO + in Discover Identity command result. + +What: /sys/class/typec/<port>-partner/identity/id_header +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + ID Header VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-partner/identity/cert_stat +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Cert Stat VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-partner/identity/product +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Product VDO part of Discover Identity command result. The value + will show 0 until Discover Identity command result becomes + available. The value can be polled. + + +USB Type-C cable devices (eg. /sys/class/typec/port0-cable/) + +Note: Electronically Marked Cables will have a device also for one cable plug +(eg. /sys/class/typec/port0-plug0). If the cable is active and has also SOP +Double Prime controller (USB Power Deliver specification ch. 2.4) it will have +second device also for the other plug. Both plugs may have alternate modes as +described in USB Type-C and USB Power Delivery specifications. + +What: /sys/class/typec/<port>-cable/type +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows if the cable is active. + Valid values: active, passive + +What: /sys/class/typec/<port>-cable/plug_type +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows type of the plug on the cable: + - type-a - Standard A + - type-b - Standard B + - type-c + - captive + +What: /sys/class/typec/<port>-cable/identity/ +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + This directory appears only if the port device driver is capable + of showing the result of Discover Identity USB power delivery + command. That will not always be possible even when USB power + delivery is supported. If the directory exists, it will have an + attribute for every VDO returned by Discover Identity command. + +What: /sys/class/typec/<port>-cable/identity/id_header +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + ID Header VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-cable/identity/cert_stat +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Cert Stat VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-cable/identity/product +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Product VDO part of Discover Identity command result. The value + will show 0 until Discover Identity command result becomes + available. The value can be polled. + + +Alternate Mode devices. + +The alternate modes will have Standard or Vendor ID (SVID) assigned by USB-IF. +The ports, partners and cable plugs can have alternate modes. A supported SVID +will consist of a set of modes. Every SVID a port/partner/plug supports will +have a device created for it, and every supported mode for a supported SVID will +have its own directory under that device. Below <dev> refers to the device for +the alternate mode. + +What: /sys/class/typec/<port|partner|cable>/<dev>/svid +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The SVID (Standard or Vendor ID) assigned by USB-IF for this + alternate mode. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/ +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Every supported mode will have its own directory. The name of + a mode will be "mode<index>" (for example mode1), where <index> + is the actual index to the mode VDO returned by Discover Modes + USB power delivery command. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/description +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows description of the mode. The description is optional for + the drivers, just like with the Billboard Devices. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/vdo +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows the VDO in hexadecimal returned by Discover Modes command + for this mode. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/active +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows if the mode is active or not. The attribute can be used + for entering/exiting the mode with partners and cable plugs, and + with the port alternate modes it can be used for disabling + support for specific alternate modes. Entering/exiting modes is + supported as synchronous operation so write(2) to the attribute + does not return until the enter/exit mode operation has + finished. The attribute is notified when the mode is + entered/exited so poll(2) on the attribute wakes up. + Entering/exiting a mode will also generate uevent KOBJ_CHANGE. + + Valid values: yes, no + +What: /sys/class/typec/<port>/<dev>/mode<index>/supported_roles +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Space separated list of the supported roles. + + This attribute is available for the devices describing the + alternate modes a port supports, and it will not be exposed with + the devices presenting the alternate modes the partners or cable + plugs support. + + Valid values: source, sink diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 2a4a423d08e0..f3d5817c4ef0 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -366,3 +366,10 @@ Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org> Description: AArch64 CPU registers 'identification' directory exposes the CPU ID registers for identifying model and revision of the CPU. + +What: /sys/devices/system/cpu/cpu#/cpu_capacity +Date: December 2016 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: information about CPUs heterogeneity. + + cpu_capacity: capacity of cpu#. diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi index c7fc72d4495c..613f42a9d5cd 100644 --- a/Documentation/ABI/testing/sysfs-firmware-acpi +++ b/Documentation/ABI/testing/sysfs-firmware-acpi @@ -44,16 +44,6 @@ Description: or 0 (unset). Attempts to write any other values to it will cause -EINVAL to be returned. -What: /sys/firmware/acpi/hotplug/force_remove -Date: May 2013 -Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> -Description: - The number in this file (0 or 1) determines whether (1) or not - (0) the ACPI subsystem will allow devices to be hot-removed even - if they cannot be put offline gracefully (from the kernel's - viewpoint). That number can be changed by writing a boolean - value to this file. - What: /sys/firmware/acpi/interrupts/ Date: February 2008 Contact: Len Brown <lenb@kernel.org> diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch index da87f43aec58..d5d39748382f 100644 --- a/Documentation/ABI/testing/sysfs-kernel-livepatch +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -25,6 +25,14 @@ Description: code is currently applied. Writing 0 will disable the patch while writing 1 will re-enable the patch. +What: /sys/kernel/livepatch/<patch>/transition +Date: Feb 2017 +KernelVersion: 4.12.0 +Contact: live-patching@vger.kernel.org +Description: + An attribute which indicates whether the patch is currently in + transition. + What: /sys/kernel/livepatch/<patch>/<object> Date: Nov 2014 KernelVersion: 3.19.0 diff --git a/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 b/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 new file mode 100644 index 000000000000..b0f4684a83fe --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-chipidea-usb2 @@ -0,0 +1,9 @@ +What: /sys/bus/platform/devices/ci_hdrc.0/role +Date: Mar 2017 +Contact: Peter Chen <peter.chen@nxp.com> +Description: + It returns string "gadget" or "host" when read it, it indicates + current controller role. + + It will do role switch when write "gadget" or "host" to it. + Only controller at dual-role configuration supports writing. diff --git a/Documentation/ABI/testing/sysfs-platform-renesas_usb3 b/Documentation/ABI/testing/sysfs-platform-renesas_usb3 new file mode 100644 index 000000000000..5621c15d5dc0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-renesas_usb3 @@ -0,0 +1,15 @@ +What: /sys/devices/platform/<renesas_usb3's name>/role +Date: March 2017 +KernelVersion: 4.13 +Contact: Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> +Description: + This file can be read and write. + The file can show/change the drd mode of usb. + + Write the following string to change the mode: + "host" - switching mode from peripheral to host. + "peripheral" - switching mode from host to peripheral. + + Read the file, then it shows the following strings: + "host" - The mode is host now. + "peripheral" - The mode is peripheral now. diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 164c1c76971f..85916f13d330 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,12 +8,11 @@ DOCBOOKS := z8530book.xml \ kernel-hacking.xml kernel-locking.xml \ - writing_usb_driver.xml networking.xml \ - kernel-api.xml filesystems.xml lsm.xml kgdb.xml \ - gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ - genericirq.xml s390-drivers.xml scsi.xml \ - sh.xml w1.xml \ - writing_musb_glue_layer.xml + networking.xml \ + filesystems.xml lsm.xml kgdb.xml \ + libata.xml mtdnand.xml librs.xml rapidio.xml \ + s390-drivers.xml scsi.xml \ + sh.xml w1.xml ifeq ($(DOCBOOKS),) @@ -62,11 +61,14 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) find $(obj)/man -name '*.9' | xargs gzip -nf +# Default location for installed man pages +export INSTALL_MAN_PATH = $(objtree)/usr + installmandocs: mandocs - mkdir -p /usr/local/man/man9/ + mkdir -p $(INSTALL_MAN_PATH)/man/man9/ find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \ sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ - xargs install -m 644 -t /usr/local/man/man9/ + xargs install -m 644 -t $(INSTALL_MAN_PATH)/man/man9/ # no-op for the DocBook toolchain epubdocs: @@ -238,7 +240,9 @@ dochelp: @echo ' psdocs - Postscript' @echo ' xmldocs - XML DocBook' @echo ' mandocs - man pages' - @echo ' installmandocs - install man pages generated by mandocs' + @echo ' installmandocs - install man pages generated by mandocs to INSTALL_MAN_PATH'; \ + echo ' (default: $(INSTALL_MAN_PATH))'; \ + echo '' @echo ' cleandocs - clean all generated DocBook files' @echo @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl deleted file mode 100644 index 641629221176..000000000000 --- a/Documentation/DocBook/gadget.tmpl +++ /dev/null @@ -1,793 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="USB-Gadget-API"> - <bookinfo> - <title>USB Gadget API for Linux</title> - <date>20 August 2004</date> - <edition>20 August 2004</edition> - - <legalnotice> - <para> - This documentation 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. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - <copyright> - <year>2003-2004</year> - <holder>David Brownell</holder> - </copyright> - - <author> - <firstname>David</firstname> - <surname>Brownell</surname> - <affiliation> - <address><email>dbrownell@users.sourceforge.net</email></address> - </affiliation> - </author> - </bookinfo> - -<toc></toc> - -<chapter id="intro"><title>Introduction</title> - -<para>This document presents a Linux-USB "Gadget" -kernel mode -API, for use within peripherals and other USB devices -that embed Linux. -It provides an overview of the API structure, -and shows how that fits into a system development project. -This is the first such API released on Linux to address -a number of important problems, including: </para> - -<itemizedlist> - <listitem><para>Supports USB 2.0, for high speed devices which - can stream data at several dozen megabytes per second. - </para></listitem> - <listitem><para>Handles devices with dozens of endpoints just as - well as ones with just two fixed-function ones. Gadget drivers - can be written so they're easy to port to new hardware. - </para></listitem> - <listitem><para>Flexible enough to expose more complex USB device - capabilities such as multiple configurations, multiple interfaces, - composite devices, - and alternate interface settings. - </para></listitem> - <listitem><para>USB "On-The-Go" (OTG) support, in conjunction - with updates to the Linux-USB host side. - </para></listitem> - <listitem><para>Sharing data structures and API models with the - Linux-USB host side API. This helps the OTG support, and - looks forward to more-symmetric frameworks (where the same - I/O model is used by both host and device side drivers). - </para></listitem> - <listitem><para>Minimalist, so it's easier to support new device - controller hardware. I/O processing doesn't imply large - demands for memory or CPU resources. - </para></listitem> -</itemizedlist> - - -<para>Most Linux developers will not be able to use this API, since they -have USB "host" hardware in a PC, workstation, or server. -Linux users with embedded systems are more likely to -have USB peripheral hardware. -To distinguish drivers running inside such hardware from the -more familiar Linux "USB device drivers", -which are host side proxies for the real USB devices, -a different term is used: -the drivers inside the peripherals are "USB gadget drivers". -In USB protocol interactions, the device driver is the master -(or "client driver") -and the gadget driver is the slave (or "function driver"). -</para> - -<para>The gadget API resembles the host side Linux-USB API in that both -use queues of request objects to package I/O buffers, and those requests -may be submitted or canceled. -They share common definitions for the standard USB -<emphasis>Chapter 9</emphasis> messages, structures, and constants. -Also, both APIs bind and unbind drivers to devices. -The APIs differ in detail, since the host side's current -URB framework exposes a number of implementation details -and assumptions that are inappropriate for a gadget API. -While the model for control transfers and configuration -management is necessarily different (one side is a hardware-neutral master, -the other is a hardware-aware slave), the endpoint I/0 API used here -should also be usable for an overhead-reduced host side API. -</para> - -</chapter> - -<chapter id="structure"><title>Structure of Gadget Drivers</title> - -<para>A system running inside a USB peripheral -normally has at least three layers inside the kernel to handle -USB protocol processing, and may have additional layers in -user space code. -The "gadget" API is used by the middle layer to interact -with the lowest level (which directly handles hardware). -</para> - -<para>In Linux, from the bottom up, these layers are: -</para> - -<variablelist> - - <varlistentry> - <term><emphasis>USB Controller Driver</emphasis></term> - - <listitem> - <para>This is the lowest software level. - It is the only layer that talks to hardware, - through registers, fifos, dma, irqs, and the like. - The <filename><linux/usb/gadget.h></filename> API abstracts - the peripheral controller endpoint hardware. - That hardware is exposed through endpoint objects, which accept - streams of IN/OUT buffers, and through callbacks that interact - with gadget drivers. - Since normal USB devices only have one upstream - port, they only have one of these drivers. - The controller driver can support any number of different - gadget drivers, but only one of them can be used at a time. - </para> - - <para>Examples of such controller hardware include - the PCI-based NetChip 2280 USB 2.0 high speed controller, - the SA-11x0 or PXA-25x UDC (found within many PDAs), - and a variety of other products. - </para> - - </listitem></varlistentry> - - <varlistentry> - <term><emphasis>Gadget Driver</emphasis></term> - - <listitem> - <para>The lower boundary of this driver implements hardware-neutral - USB functions, using calls to the controller driver. - Because such hardware varies widely in capabilities and restrictions, - and is used in embedded environments where space is at a premium, - the gadget driver is often configured at compile time - to work with endpoints supported by one particular controller. - Gadget drivers may be portable to several different controllers, - using conditional compilation. - (Recent kernels substantially simplify the work involved in - supporting new hardware, by <emphasis>autoconfiguring</emphasis> - endpoints automatically for many bulk-oriented drivers.) - Gadget driver responsibilities include: - </para> - <itemizedlist> - <listitem><para>handling setup requests (ep0 protocol responses) - possibly including class-specific functionality - </para></listitem> - <listitem><para>returning configuration and string descriptors - </para></listitem> - <listitem><para>(re)setting configurations and interface - altsettings, including enabling and configuring endpoints - </para></listitem> - <listitem><para>handling life cycle events, such as managing - bindings to hardware, - USB suspend/resume, remote wakeup, - and disconnection from the USB host. - </para></listitem> - <listitem><para>managing IN and OUT transfers on all currently - enabled endpoints - </para></listitem> - </itemizedlist> - - <para> - Such drivers may be modules of proprietary code, although - that approach is discouraged in the Linux community. - </para> - </listitem></varlistentry> - - <varlistentry> - <term><emphasis>Upper Level</emphasis></term> - - <listitem> - <para>Most gadget drivers have an upper boundary that connects - to some Linux driver or framework in Linux. - Through that boundary flows the data which the gadget driver - produces and/or consumes through protocol transfers over USB. - Examples include: - </para> - <itemizedlist> - <listitem><para>user mode code, using generic (gadgetfs) - or application specific files in - <filename>/dev</filename> - </para></listitem> - <listitem><para>networking subsystem (for network gadgets, - like the CDC Ethernet Model gadget driver) - </para></listitem> - <listitem><para>data capture drivers, perhaps video4Linux or - a scanner driver; or test and measurement hardware. - </para></listitem> - <listitem><para>input subsystem (for HID gadgets) - </para></listitem> - <listitem><para>sound subsystem (for audio gadgets) - </para></listitem> - <listitem><para>file system (for PTP gadgets) - </para></listitem> - <listitem><para>block i/o subsystem (for usb-storage gadgets) - </para></listitem> - <listitem><para>... and more </para></listitem> - </itemizedlist> - </listitem></varlistentry> - - <varlistentry> - <term><emphasis>Additional Layers</emphasis></term> - - <listitem> - <para>Other layers may exist. - These could include kernel layers, such as network protocol stacks, - as well as user mode applications building on standard POSIX - system call APIs such as - <emphasis>open()</emphasis>, <emphasis>close()</emphasis>, - <emphasis>read()</emphasis> and <emphasis>write()</emphasis>. - On newer systems, POSIX Async I/O calls may be an option. - Such user mode code will not necessarily be subject to - the GNU General Public License (GPL). - </para> - </listitem></varlistentry> - - -</variablelist> - -<para>OTG-capable systems will also need to include a standard Linux-USB -host side stack, -with <emphasis>usbcore</emphasis>, -one or more <emphasis>Host Controller Drivers</emphasis> (HCDs), -<emphasis>USB Device Drivers</emphasis> to support -the OTG "Targeted Peripheral List", -and so forth. -There will also be an <emphasis>OTG Controller Driver</emphasis>, -which is visible to gadget and device driver developers only indirectly. -That helps the host and device side USB controllers implement the -two new OTG protocols (HNP and SRP). -Roles switch (host to peripheral, or vice versa) using HNP -during USB suspend processing, and SRP can be viewed as a -more battery-friendly kind of device wakeup protocol. -</para> - -<para>Over time, reusable utilities are evolving to help make some -gadget driver tasks simpler. -For example, building configuration descriptors from vectors of -descriptors for the configurations interfaces and endpoints is -now automated, and many drivers now use autoconfiguration to -choose hardware endpoints and initialize their descriptors. - -A potential example of particular interest -is code implementing standard USB-IF protocols for -HID, networking, storage, or audio classes. -Some developers are interested in KDB or KGDB hooks, to let -target hardware be remotely debugged. -Most such USB protocol code doesn't need to be hardware-specific, -any more than network protocols like X11, HTTP, or NFS are. -Such gadget-side interface drivers should eventually be combined, -to implement composite devices. -</para> - -</chapter> - - -<chapter id="api"><title>Kernel Mode Gadget API</title> - -<para>Gadget drivers declare themselves through a -<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for -most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>. -The response to a set_configuration usually involves -enabling one or more of the <emphasis>struct usb_ep</emphasis> objects -exposed by the gadget, and submitting one or more -<emphasis>struct usb_request</emphasis> buffers to transfer data. -Understand those four data types, and their operations, and -you will understand how this API works. -</para> - -<note><title>Incomplete Data Type Descriptions</title> - -<para>This documentation was prepared using the standard Linux -kernel <filename>docproc</filename> tool, which turns text -and in-code comments into SGML DocBook and then into usable -formats such as HTML or PDF. -Other than the "Chapter 9" data types, most of the significant -data types and functions are described here. -</para> - -<para>However, docproc does not understand all the C constructs -that are used, so some relevant information is likely omitted from -what you are reading. -One example of such information is endpoint autoconfiguration. -You'll have to read the header file, and use example source -code (such as that for "Gadget Zero"), to fully understand the API. -</para> - -<para>The part of the API implementing some basic -driver capabilities is specific to the version of the -Linux kernel that's in use. -The 2.6 kernel includes a <emphasis>driver model</emphasis> -framework that has no analogue on earlier kernels; -so those parts of the gadget API are not fully portable. -(They are implemented on 2.4 kernels, but in a different way.) -The driver model state is another part of this API that is -ignored by the kerneldoc tools. -</para> -</note> - -<para>The core API does not expose -every possible hardware feature, only the most widely available ones. -There are significant hardware features, such as device-to-device DMA -(without temporary storage in a memory buffer) -that would be added using hardware-specific APIs. -</para> - -<para>This API allows drivers to use conditional compilation to handle -endpoint capabilities of different hardware, but doesn't require that. -Hardware tends to have arbitrary restrictions, relating to -transfer types, addressing, packet sizes, buffering, and availability. -As a rule, such differences only matter for "endpoint zero" logic -that handles device configuration and management. -The API supports limited run-time -detection of capabilities, through naming conventions for endpoints. -Many drivers will be able to at least partially autoconfigure -themselves. -In particular, driver init sections will often have endpoint -autoconfiguration logic that scans the hardware's list of endpoints -to find ones matching the driver requirements -(relying on those conventions), to eliminate some of the most -common reasons for conditional compilation. -</para> - -<para>Like the Linux-USB host side API, this API exposes -the "chunky" nature of USB messages: I/O requests are in terms -of one or more "packets", and packet boundaries are visible to drivers. -Compared to RS-232 serial protocols, USB resembles -synchronous protocols like HDLC -(N bytes per frame, multipoint addressing, host as the primary -station and devices as secondary stations) -more than asynchronous ones -(tty style: 8 data bits per frame, no parity, one stop bit). -So for example the controller drivers won't buffer -two single byte writes into a single two-byte USB IN packet, -although gadget drivers may do so when they implement -protocols where packet boundaries (and "short packets") -are not significant. -</para> - -<sect1 id="lifecycle"><title>Driver Life Cycle</title> - -<para>Gadget drivers make endpoint I/O requests to hardware without -needing to know many details of the hardware, but driver -setup/configuration code needs to handle some differences. -Use the API like this: -</para> - -<orderedlist numeration='arabic'> - -<listitem><para>Register a driver for the particular device side -usb controller hardware, -such as the net2280 on PCI (USB 2.0), -sa11x0 or pxa25x as found in Linux PDAs, -and so on. -At this point the device is logically in the USB ch9 initial state -("attached"), drawing no power and not usable -(since it does not yet support enumeration). -Any host should not see the device, since it's not -activated the data line pullup used by the host to -detect a device, even if VBUS power is available. -</para></listitem> - -<listitem><para>Register a gadget driver that implements some higher level -device function. That will then bind() to a usb_gadget, which -activates the data line pullup sometime after detecting VBUS. -</para></listitem> - -<listitem><para>The hardware driver can now start enumerating. -The steps it handles are to accept USB power and set_address requests. -Other steps are handled by the gadget driver. -If the gadget driver module is unloaded before the host starts to -enumerate, steps before step 7 are skipped. -</para></listitem> - -<listitem><para>The gadget driver's setup() call returns usb descriptors, -based both on what the bus interface hardware provides and on the -functionality being implemented. -That can involve alternate settings or configurations, -unless the hardware prevents such operation. -For OTG devices, each configuration descriptor includes -an OTG descriptor. -</para></listitem> - -<listitem><para>The gadget driver handles the last step of enumeration, -when the USB host issues a set_configuration call. -It enables all endpoints used in that configuration, -with all interfaces in their default settings. -That involves using a list of the hardware's endpoints, enabling each -endpoint according to its descriptor. -It may also involve using <function>usb_gadget_vbus_draw</function> -to let more power be drawn from VBUS, as allowed by that configuration. -For OTG devices, setting a configuration may also involve reporting -HNP capabilities through a user interface. -</para></listitem> - -<listitem><para>Do real work and perform data transfers, possibly involving -changes to interface settings or switching to new configurations, until the -device is disconnect()ed from the host. -Queue any number of transfer requests to each endpoint. -It may be suspended and resumed several times before being disconnected. -On disconnect, the drivers go back to step 3 (above). -</para></listitem> - -<listitem><para>When the gadget driver module is being unloaded, -the driver unbind() callback is issued. That lets the controller -driver be unloaded. -</para></listitem> - -</orderedlist> - -<para>Drivers will normally be arranged so that just loading the -gadget driver module (or statically linking it into a Linux kernel) -allows the peripheral device to be enumerated, but some drivers -will defer enumeration until some higher level component (like -a user mode daemon) enables it. -Note that at this lowest level there are no policies about how -ep0 configuration logic is implemented, -except that it should obey USB specifications. -Such issues are in the domain of gadget drivers, -including knowing about implementation constraints -imposed by some USB controllers -or understanding that composite devices might happen to -be built by integrating reusable components. -</para> - -<para>Note that the lifecycle above can be slightly different -for OTG devices. -Other than providing an additional OTG descriptor in each -configuration, only the HNP-related differences are particularly -visible to driver code. -They involve reporting requirements during the SET_CONFIGURATION -request, and the option to invoke HNP during some suspend callbacks. -Also, SRP changes the semantics of -<function>usb_gadget_wakeup</function> -slightly. -</para> - -</sect1> - -<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title> - -<para>Gadget drivers -rely on common USB structures and constants -defined in the -<filename><linux/usb/ch9.h></filename> -header file, which is standard in Linux 2.6 kernels. -These are the same types and constants used by host -side drivers (and usbcore). -</para> - -!Iinclude/linux/usb/ch9.h -</sect1> - -<sect1 id="core"><title>Core Objects and Methods</title> - -<para>These are declared in -<filename><linux/usb/gadget.h></filename>, -and are used by gadget drivers to interact with -USB peripheral controller drivers. -</para> - - <!-- yeech, this is ugly in nsgmls PDF output. - - the PDF bookmark and refentry output nesting is wrong, - and the member/argument documentation indents ugly. - - plus something (docproc?) adds whitespace before the - descriptive paragraph text, so it can't line up right - unless the explanations are trivial. - --> - -!Iinclude/linux/usb/gadget.h -</sect1> - -<sect1 id="utils"><title>Optional Utilities</title> - -<para>The core API is sufficient for writing a USB Gadget Driver, -but some optional utilities are provided to simplify common tasks. -These utilities include endpoint autoconfiguration. -</para> - -!Edrivers/usb/gadget/usbstring.c -!Edrivers/usb/gadget/config.c -<!-- !Edrivers/usb/gadget/epautoconf.c --> -</sect1> - -<sect1 id="composite"><title>Composite Device Framework</title> - -<para>The core API is sufficient for writing drivers for composite -USB devices (with more than one function in a given configuration), -and also multi-configuration devices (also more than one function, -but not necessarily sharing a given configuration). -There is however an optional framework which makes it easier to -reuse and combine functions. -</para> - -<para>Devices using this framework provide a <emphasis>struct -usb_composite_driver</emphasis>, which in turn provides one or -more <emphasis>struct usb_configuration</emphasis> instances. -Each such configuration includes at least one -<emphasis>struct usb_function</emphasis>, which packages a user -visible role such as "network link" or "mass storage device". -Management functions may also exist, such as "Device Firmware -Upgrade". -</para> - -!Iinclude/linux/usb/composite.h -!Edrivers/usb/gadget/composite.c - -</sect1> - -<sect1 id="functions"><title>Composite Device Functions</title> - -<para>At this writing, a few of the current gadget drivers have -been converted to this framework. -Near-term plans include converting all of them, except for "gadgetfs". -</para> - -!Edrivers/usb/gadget/function/f_acm.c -!Edrivers/usb/gadget/function/f_ecm.c -!Edrivers/usb/gadget/function/f_subset.c -!Edrivers/usb/gadget/function/f_obex.c -!Edrivers/usb/gadget/function/f_serial.c - -</sect1> - - -</chapter> - -<chapter id="controllers"><title>Peripheral Controller Drivers</title> - -<para>The first hardware supporting this API was the NetChip 2280 -controller, which supports USB 2.0 high speed and is based on PCI. -This is the <filename>net2280</filename> driver module. -The driver supports Linux kernel versions 2.4 and 2.6; -contact NetChip Technologies for development boards and product -information. -</para> - -<para>Other hardware working in the "gadget" framework includes: -Intel's PXA 25x and IXP42x series processors -(<filename>pxa2xx_udc</filename>), -Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>), -Renesas SH7705/7727 (<filename>sh_udc</filename>), -MediaQ 11xx (<filename>mq11xx_udc</filename>), -Hynix HMS30C7202 (<filename>h7202_udc</filename>), -National 9303/4 (<filename>n9604_udc</filename>), -Texas Instruments OMAP (<filename>omap_udc</filename>), -Sharp LH7A40x (<filename>lh7a40x_udc</filename>), -and more. -Most of those are full speed controllers. -</para> - -<para>At this writing, there are people at work on drivers in -this framework for several other USB device controllers, -with plans to make many of them be widely available. -</para> - -<!-- !Edrivers/usb/gadget/net2280.c --> - -<para>A partial USB simulator, -the <filename>dummy_hcd</filename> driver, is available. -It can act like a net2280, a pxa25x, or an sa11x0 in terms -of available endpoints and device speeds; and it simulates -control, bulk, and to some extent interrupt transfers. -That lets you develop some parts of a gadget driver on a normal PC, -without any special hardware, and perhaps with the assistance -of tools such as GDB running with User Mode Linux. -At least one person has expressed interest in adapting that -approach, hooking it up to a simulator for a microcontroller. -Such simulators can help debug subsystems where the runtime hardware -is unfriendly to software development, or is not yet available. -</para> - -<para>Support for other controllers is expected to be developed -and contributed -over time, as this driver framework evolves. -</para> - -</chapter> - -<chapter id="gadget"><title>Gadget Drivers</title> - -<para>In addition to <emphasis>Gadget Zero</emphasis> -(used primarily for testing and development with drivers -for usb controller hardware), other gadget drivers exist. -</para> - -<para>There's an <emphasis>ethernet</emphasis> gadget -driver, which implements one of the most useful -<emphasis>Communications Device Class</emphasis> (CDC) models. -One of the standards for cable modem interoperability even -specifies the use of this ethernet model as one of two -mandatory options. -Gadgets using this code look to a USB host as if they're -an Ethernet adapter. -It provides access to a network where the gadget's CPU is one host, -which could easily be bridging, routing, or firewalling -access to other networks. -Since some hardware can't fully implement the CDC Ethernet -requirements, this driver also implements a "good parts only" -subset of CDC Ethernet. -(That subset doesn't advertise itself as CDC Ethernet, -to avoid creating problems.) -</para> - -<para>Support for Microsoft's <emphasis>RNDIS</emphasis> -protocol has been contributed by Pengutronix and Auerswald GmbH. -This is like CDC Ethernet, but it runs on more slightly USB hardware -(but less than the CDC subset). -However, its main claim to fame is being able to connect directly to -recent versions of Windows, using drivers that Microsoft bundles -and supports, making it much simpler to network with Windows. -</para> - -<para>There is also support for user mode gadget drivers, -using <emphasis>gadgetfs</emphasis>. -This provides a <emphasis>User Mode API</emphasis> that presents -each endpoint as a single file descriptor. I/O is done using -normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls. -Familiar tools like GDB and pthreads can be used to -develop and debug user mode drivers, so that once a robust -controller driver is available many applications for it -won't require new kernel mode software. -Linux 2.6 <emphasis>Async I/O (AIO)</emphasis> -support is available, so that user mode software -can stream data with only slightly more overhead -than a kernel driver. -</para> - -<para>There's a USB Mass Storage class driver, which provides -a different solution for interoperability with systems such -as MS-Windows and MacOS. -That <emphasis>Mass Storage</emphasis> driver uses a -file or block device as backing store for a drive, -like the <filename>loop</filename> driver. -The USB host uses the BBB, CB, or CBI versions of the mass -storage class specification, using transparent SCSI commands -to access the data from the backing store. -</para> - -<para>There's a "serial line" driver, useful for TTY style -operation over USB. -The latest version of that driver supports CDC ACM style -operation, like a USB modem, and so on most hardware it can -interoperate easily with MS-Windows. -One interesting use of that driver is in boot firmware (like a BIOS), -which can sometimes use that model with very small systems without -real serial lines. -</para> - -<para>Support for other kinds of gadget is expected to -be developed and contributed -over time, as this driver framework evolves. -</para> - -</chapter> - -<chapter id="otg"><title>USB On-The-GO (OTG)</title> - -<para>USB OTG support on Linux 2.6 was initially developed -by Texas Instruments for -<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx -series processors. -Other OTG systems should work in similar ways, but the -hardware level details could be very different. -</para> - -<para>Systems need specialized hardware support to implement OTG, -notably including a special <emphasis>Mini-AB</emphasis> jack -and associated transceiver to support <emphasis>Dual-Role</emphasis> -operation: -they can act either as a host, using the standard -Linux-USB host side driver stack, -or as a peripheral, using this "gadget" framework. -To do that, the system software relies on small additions -to those programming interfaces, -and on a new internal component (here called an "OTG Controller") -affecting which driver stack connects to the OTG port. -In each role, the system can re-use the existing pool of -hardware-neutral drivers, layered on top of the controller -driver interfaces (<emphasis>usb_bus</emphasis> or -<emphasis>usb_gadget</emphasis>). -Such drivers need at most minor changes, and most of the calls -added to support OTG can also benefit non-OTG products. -</para> - -<itemizedlist> - <listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis> - flag, and use it to determine whether or not to include - an OTG descriptor in each of their configurations. - </para></listitem> - <listitem><para>Gadget drivers may need changes to support the - two new OTG protocols, exposed in new gadget attributes - such as <emphasis>b_hnp_enable</emphasis> flag. - HNP support should be reported through a user interface - (two LEDs could suffice), and is triggered in some cases - when the host suspends the peripheral. - SRP support can be user-initiated just like remote wakeup, - probably by pressing the same button. - </para></listitem> - <listitem><para>On the host side, USB device drivers need - to be taught to trigger HNP at appropriate moments, using - <function>usb_suspend_device()</function>. - That also conserves battery power, which is useful even - for non-OTG configurations. - </para></listitem> - <listitem><para>Also on the host side, a driver must support the - OTG "Targeted Peripheral List". That's just a whitelist, - used to reject peripherals not supported with a given - Linux OTG host. - <emphasis>This whitelist is product-specific; - each product must modify <filename>otg_whitelist.h</filename> - to match its interoperability specification. - </emphasis> - </para> - <para>Non-OTG Linux hosts, like PCs and workstations, - normally have some solution for adding drivers, so that - peripherals that aren't recognized can eventually be supported. - That approach is unreasonable for consumer products that may - never have their firmware upgraded, and where it's usually - unrealistic to expect traditional PC/workstation/server kinds - of support model to work. - For example, it's often impractical to change device firmware - once the product has been distributed, so driver bugs can't - normally be fixed if they're found after shipment. - </para></listitem> -</itemizedlist> - -<para> -Additional changes are needed below those hardware-neutral -<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis> -driver interfaces; those aren't discussed here in any detail. -Those affect the hardware-specific code for each USB Host or Peripheral -controller, and how the HCD initializes (since OTG can be active only -on a single port). -They also involve what may be called an <emphasis>OTG Controller -Driver</emphasis>, managing the OTG transceiver and the OTG state -machine logic as well as much of the root hub behavior for the -OTG port. -The OTG controller driver needs to activate and deactivate USB -controllers depending on the relevant device role. -Some related changes were needed inside usbcore, so that it -can identify OTG-capable devices and respond appropriately -to HNP or SRP protocols. -</para> - -</chapter> - -</book> -<!-- - vim:syntax=sgml:sw=4 ---> diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl deleted file mode 100644 index 59fb5c077541..000000000000 --- a/Documentation/DocBook/genericirq.tmpl +++ /dev/null @@ -1,520 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Generic-IRQ-Guide"> - <bookinfo> - <title>Linux generic IRQ handling</title> - - <authorgroup> - <author> - <firstname>Thomas</firstname> - <surname>Gleixner</surname> - <affiliation> - <address> - <email>tglx@linutronix.de</email> - </address> - </affiliation> - </author> - <author> - <firstname>Ingo</firstname> - <surname>Molnar</surname> - <affiliation> - <address> - <email>mingo@elte.hu</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2005-2010</year> - <holder>Thomas Gleixner</holder> - </copyright> - <copyright> - <year>2005-2006</year> - <holder>Ingo Molnar</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The generic interrupt handling layer is designed to provide a - complete abstraction of interrupt handling for device drivers. - It is able to handle all the different types of interrupt controller - hardware. Device drivers use generic API functions to request, enable, - disable and free interrupts. The drivers do not have to know anything - about interrupt hardware details, so they can be used on different - platforms without code changes. - </para> - <para> - This documentation is provided to developers who want to implement - an interrupt subsystem based for their architecture, with the help - of the generic IRQ handling layer. - </para> - </chapter> - - <chapter id="rationale"> - <title>Rationale</title> - <para> - The original implementation of interrupt handling in Linux uses - the __do_IRQ() super-handler, which is able to deal with every - type of interrupt logic. - </para> - <para> - Originally, Russell King identified different types of handlers to - build a quite universal set for the ARM interrupt handler - implementation in Linux 2.5/2.6. He distinguished between: - <itemizedlist> - <listitem><para>Level type</para></listitem> - <listitem><para>Edge type</para></listitem> - <listitem><para>Simple type</para></listitem> - </itemizedlist> - During the implementation we identified another type: - <itemizedlist> - <listitem><para>Fast EOI type</para></listitem> - </itemizedlist> - In the SMP world of the __do_IRQ() super-handler another type - was identified: - <itemizedlist> - <listitem><para>Per CPU type</para></listitem> - </itemizedlist> - </para> - <para> - This split implementation of high-level IRQ handlers allows us to - optimize the flow of the interrupt handling for each specific - interrupt type. This reduces complexity in that particular code path - and allows the optimized handling of a given type. - </para> - <para> - The original general IRQ implementation used hw_interrupt_type - structures and their ->ack(), ->end() [etc.] callbacks to - differentiate the flow control in the super-handler. This leads to - a mix of flow logic and low-level hardware logic, and it also leads - to unnecessary code duplication: for example in i386, there is an - ioapic_level_irq and an ioapic_edge_irq IRQ-type which share many - of the low-level details but have different flow handling. - </para> - <para> - A more natural abstraction is the clean separation of the - 'irq flow' and the 'chip details'. - </para> - <para> - Analysing a couple of architecture's IRQ subsystem implementations - reveals that most of them can use a generic set of 'irq flow' - methods and only need to add the chip-level specific code. - The separation is also valuable for (sub)architectures - which need specific quirks in the IRQ flow itself but not in the - chip details - and thus provides a more transparent IRQ subsystem - design. - </para> - <para> - Each interrupt descriptor is assigned its own high-level flow - handler, which is normally one of the generic - implementations. (This high-level flow handler implementation also - makes it simple to provide demultiplexing handlers which can be - found in embedded platforms on various architectures.) - </para> - <para> - The separation makes the generic interrupt handling layer more - flexible and extensible. For example, an (sub)architecture can - use a generic IRQ-flow implementation for 'level type' interrupts - and add a (sub)architecture specific 'edge type' implementation. - </para> - <para> - To make the transition to the new model easier and prevent the - breakage of existing implementations, the __do_IRQ() super-handler - is still available. This leads to a kind of duality for the time - being. Over time the new model should be used in more and more - architectures, as it enables smaller and cleaner IRQ subsystems. - It's deprecated for three years now and about to be removed. - </para> - </chapter> - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None (knock on wood). - </para> - </chapter> - - <chapter id="Abstraction"> - <title>Abstraction layers</title> - <para> - There are three main levels of abstraction in the interrupt code: - <orderedlist> - <listitem><para>High-level driver API</para></listitem> - <listitem><para>High-level IRQ flow handlers</para></listitem> - <listitem><para>Chip-level hardware encapsulation</para></listitem> - </orderedlist> - </para> - <sect1 id="Interrupt_control_flow"> - <title>Interrupt control flow</title> - <para> - Each interrupt is described by an interrupt descriptor structure - irq_desc. The interrupt is referenced by an 'unsigned int' numeric - value which selects the corresponding interrupt description structure - in the descriptor structures array. - The descriptor structure contains status information and pointers - to the interrupt flow method and the interrupt chip structure - which are assigned to this interrupt. - </para> - <para> - Whenever an interrupt triggers, the low-level architecture code calls - into the generic interrupt code by calling desc->handle_irq(). - This high-level IRQ handling function only uses desc->irq_data.chip - primitives referenced by the assigned chip descriptor structure. - </para> - </sect1> - <sect1 id="Highlevel_Driver_API"> - <title>High-level Driver API</title> - <para> - The high-level Driver API consists of following functions: - <itemizedlist> - <listitem><para>request_irq()</para></listitem> - <listitem><para>free_irq()</para></listitem> - <listitem><para>disable_irq()</para></listitem> - <listitem><para>enable_irq()</para></listitem> - <listitem><para>disable_irq_nosync() (SMP only)</para></listitem> - <listitem><para>synchronize_irq() (SMP only)</para></listitem> - <listitem><para>irq_set_irq_type()</para></listitem> - <listitem><para>irq_set_irq_wake()</para></listitem> - <listitem><para>irq_set_handler_data()</para></listitem> - <listitem><para>irq_set_chip()</para></listitem> - <listitem><para>irq_set_chip_data()</para></listitem> - </itemizedlist> - See the autogenerated function documentation for details. - </para> - </sect1> - <sect1 id="Highlevel_IRQ_flow_handlers"> - <title>High-level IRQ flow handlers</title> - <para> - The generic layer provides a set of pre-defined irq-flow methods: - <itemizedlist> - <listitem><para>handle_level_irq</para></listitem> - <listitem><para>handle_edge_irq</para></listitem> - <listitem><para>handle_fasteoi_irq</para></listitem> - <listitem><para>handle_simple_irq</para></listitem> - <listitem><para>handle_percpu_irq</para></listitem> - <listitem><para>handle_edge_eoi_irq</para></listitem> - <listitem><para>handle_bad_irq</para></listitem> - </itemizedlist> - The interrupt flow handlers (either pre-defined or architecture - specific) are assigned to specific interrupts by the architecture - either during bootup or during device initialization. - </para> - <sect2 id="Default_flow_implementations"> - <title>Default flow implementations</title> - <sect3 id="Helper_functions"> - <title>Helper functions</title> - <para> - The helper functions call the chip primitives and - are used by the default flow implementations. - The following helper functions are implemented (simplified excerpt): - <programlisting> -default_enable(struct irq_data *data) -{ - desc->irq_data.chip->irq_unmask(data); -} - -default_disable(struct irq_data *data) -{ - if (!delay_disable(data)) - desc->irq_data.chip->irq_mask(data); -} - -default_ack(struct irq_data *data) -{ - chip->irq_ack(data); -} - -default_mask_ack(struct irq_data *data) -{ - if (chip->irq_mask_ack) { - chip->irq_mask_ack(data); - } else { - chip->irq_mask(data); - chip->irq_ack(data); - } -} - -noop(struct irq_data *data)) -{ -} - - </programlisting> - </para> - </sect3> - </sect2> - <sect2 id="Default_flow_handler_implementations"> - <title>Default flow handler implementations</title> - <sect3 id="Default_Level_IRQ_flow_handler"> - <title>Default Level IRQ flow handler</title> - <para> - handle_level_irq provides a generic implementation - for level-triggered interrupts. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -desc->irq_data.chip->irq_mask_ack(); -handle_irq_event(desc->action); -desc->irq_data.chip->irq_unmask(); - </programlisting> - </para> - </sect3> - <sect3 id="Default_FASTEOI_IRQ_flow_handler"> - <title>Default Fast EOI IRQ flow handler</title> - <para> - handle_fasteoi_irq provides a generic implementation - for interrupts, which only need an EOI at the end of - the handler. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -handle_irq_event(desc->action); -desc->irq_data.chip->irq_eoi(); - </programlisting> - </para> - </sect3> - <sect3 id="Default_Edge_IRQ_flow_handler"> - <title>Default Edge IRQ flow handler</title> - <para> - handle_edge_irq provides a generic implementation - for edge-triggered interrupts. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -if (desc->status & running) { - desc->irq_data.chip->irq_mask_ack(); - desc->status |= pending | masked; - return; -} -desc->irq_data.chip->irq_ack(); -desc->status |= running; -do { - if (desc->status & masked) - desc->irq_data.chip->irq_unmask(); - desc->status &= ~pending; - handle_irq_event(desc->action); -} while (status & pending); -desc->status &= ~running; - </programlisting> - </para> - </sect3> - <sect3 id="Default_simple_IRQ_flow_handler"> - <title>Default simple IRQ flow handler</title> - <para> - handle_simple_irq provides a generic implementation - for simple interrupts. - </para> - <para> - Note: The simple flow handler does not call any - handler/chip primitives. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -handle_irq_event(desc->action); - </programlisting> - </para> - </sect3> - <sect3 id="Default_per_CPU_flow_handler"> - <title>Default per CPU flow handler</title> - <para> - handle_percpu_irq provides a generic implementation - for per CPU interrupts. - </para> - <para> - Per CPU interrupts are only available on SMP and - the handler provides a simplified version without - locking. - </para> - <para> - The following control flow is implemented (simplified excerpt): - <programlisting> -if (desc->irq_data.chip->irq_ack) - desc->irq_data.chip->irq_ack(); -handle_irq_event(desc->action); -if (desc->irq_data.chip->irq_eoi) - desc->irq_data.chip->irq_eoi(); - </programlisting> - </para> - </sect3> - <sect3 id="EOI_Edge_IRQ_flow_handler"> - <title>EOI Edge IRQ flow handler</title> - <para> - handle_edge_eoi_irq provides an abnomination of the edge - handler which is solely used to tame a badly wreckaged - irq controller on powerpc/cell. - </para> - </sect3> - <sect3 id="BAD_IRQ_flow_handler"> - <title>Bad IRQ flow handler</title> - <para> - handle_bad_irq is used for spurious interrupts which - have no real handler assigned.. - </para> - </sect3> - </sect2> - <sect2 id="Quirks_and_optimizations"> - <title>Quirks and optimizations</title> - <para> - The generic functions are intended for 'clean' architectures and chips, - which have no platform-specific IRQ handling quirks. If an architecture - needs to implement quirks on the 'flow' level then it can do so by - overriding the high-level irq-flow handler. - </para> - </sect2> - <sect2 id="Delayed_interrupt_disable"> - <title>Delayed interrupt disable</title> - <para> - This per interrupt selectable feature, which was introduced by Russell - King in the ARM interrupt implementation, does not mask an interrupt - at the hardware level when disable_irq() is called. The interrupt is - kept enabled and is masked in the flow handler when an interrupt event - happens. This prevents losing edge interrupts on hardware which does - not store an edge interrupt event while the interrupt is disabled at - the hardware level. When an interrupt arrives while the IRQ_DISABLED - flag is set, then the interrupt is masked at the hardware level and - the IRQ_PENDING bit is set. When the interrupt is re-enabled by - enable_irq() the pending bit is checked and if it is set, the - interrupt is resent either via hardware or by a software resend - mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when - you want to use the delayed interrupt disable feature and your - hardware is not capable of retriggering an interrupt.) - The delayed interrupt disable is not configurable. - </para> - </sect2> - </sect1> - <sect1 id="Chiplevel_hardware_encapsulation"> - <title>Chip-level hardware encapsulation</title> - <para> - The chip-level hardware descriptor structure irq_chip - contains all the direct chip relevant functions, which - can be utilized by the irq flow implementations. - <itemizedlist> - <listitem><para>irq_ack()</para></listitem> - <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem> - <listitem><para>irq_mask()</para></listitem> - <listitem><para>irq_unmask()</para></listitem> - <listitem><para>irq_eoi() - Optional, required for EOI flow handlers</para></listitem> - <listitem><para>irq_retrigger() - Optional</para></listitem> - <listitem><para>irq_set_type() - Optional</para></listitem> - <listitem><para>irq_set_wake() - Optional</para></listitem> - </itemizedlist> - These primitives are strictly intended to mean what they say: ack means - ACK, masking means masking of an IRQ line, etc. It is up to the flow - handler(s) to use these basic units of low-level functionality. - </para> - </sect1> - </chapter> - - <chapter id="doirq"> - <title>__do_IRQ entry point</title> - <para> - The original implementation __do_IRQ() was an alternative entry - point for all types of interrupts. It no longer exists. - </para> - <para> - This handler turned out to be not suitable for all - interrupt hardware and was therefore reimplemented with split - functionality for edge/level/simple/percpu interrupts. This is not - only a functional optimization. It also shortens code paths for - interrupts. - </para> - </chapter> - - <chapter id="locking"> - <title>Locking on SMP</title> - <para> - The locking of chip registers is up to the architecture that - defines the chip primitives. The per-irq structure is - protected via desc->lock, by the generic layer. - </para> - </chapter> - - <chapter id="genericchip"> - <title>Generic interrupt chip</title> - <para> - To avoid copies of identical implementations of IRQ chips the - core provides a configurable generic interrupt chip - implementation. Developers should check carefully whether the - generic chip fits their needs before implementing the same - functionality slightly differently themselves. - </para> -!Ekernel/irq/generic-chip.c - </chapter> - - <chapter id="structs"> - <title>Structures</title> - <para> - This chapter contains the autogenerated documentation of the structures which are - used in the generic IRQ layer. - </para> -!Iinclude/linux/irq.h -!Iinclude/linux/interrupt.h - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> - <para> - This chapter contains the autogenerated documentation of the kernel API functions - which are exported. - </para> -!Ekernel/irq/manage.c -!Ekernel/irq/chip.c - </chapter> - - <chapter id="intfunctions"> - <title>Internal Functions Provided</title> - <para> - This chapter contains the autogenerated documentation of the internal functions. - </para> -!Ikernel/irq/irqdesc.c -!Ikernel/irq/handle.c -!Ikernel/irq/chip.c - </chapter> - - <chapter id="credits"> - <title>Credits</title> - <para> - The following people have contributed to this document: - <orderedlist> - <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> - <listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem> - </orderedlist> - </para> - </chapter> -</book> diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl deleted file mode 100644 index ecfd0ea40661..000000000000 --- a/Documentation/DocBook/kernel-api.tmpl +++ /dev/null @@ -1,331 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="LinuxKernelAPI"> - <bookinfo> - <title>The Linux Kernel API</title> - - <legalnotice> - <para> - This documentation 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. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="adt"> - <title>Data Types</title> - <sect1><title>Doubly Linked Lists</title> -!Iinclude/linux/list.h - </sect1> - </chapter> - - <chapter id="libc"> - <title>Basic C Library Functions</title> - - <para> - When writing drivers, you cannot in general use routines which are - from the C Library. Some of the functions have been found generally - useful and they are listed below. The behaviour of these functions - may vary slightly from those defined by ANSI, and these deviations - are noted in the text. - </para> - - <sect1><title>String Conversions</title> -!Elib/vsprintf.c -!Finclude/linux/kernel.h kstrtol -!Finclude/linux/kernel.h kstrtoul -!Elib/kstrtox.c - </sect1> - <sect1><title>String Manipulation</title> -<!-- All functions are exported at now -X!Ilib/string.c - --> -!Elib/string.c - </sect1> - <sect1><title>Bit Operations</title> -!Iarch/x86/include/asm/bitops.h - </sect1> - </chapter> - - <chapter id="kernel-lib"> - <title>Basic Kernel Library Functions</title> - - <para> - The Linux kernel provides more basic utility functions. - </para> - - <sect1><title>Bitmap Operations</title> -!Elib/bitmap.c -!Ilib/bitmap.c - </sect1> - - <sect1><title>Command-line Parsing</title> -!Elib/cmdline.c - </sect1> - - <sect1 id="crc"><title>CRC Functions</title> -!Elib/crc7.c -!Elib/crc16.c -!Elib/crc-itu-t.c -!Elib/crc32.c -!Elib/crc-ccitt.c - </sect1> - - <sect1 id="idr"><title>idr/ida Functions</title> -!Pinclude/linux/idr.h idr sync -!Plib/idr.c IDA description -!Elib/idr.c - </sect1> - </chapter> - - <chapter id="mm"> - <title>Memory Management in Linux</title> - <sect1><title>The Slab Cache</title> -!Iinclude/linux/slab.h -!Emm/slab.c -!Emm/util.c - </sect1> - <sect1><title>User Space Memory Access</title> -!Iarch/x86/include/asm/uaccess_32.h -!Earch/x86/lib/usercopy_32.c - </sect1> - <sect1><title>More Memory Management Functions</title> -!Emm/readahead.c -!Emm/filemap.c -!Emm/memory.c -!Emm/vmalloc.c -!Imm/page_alloc.c -!Emm/mempool.c -!Emm/dmapool.c -!Emm/page-writeback.c -!Emm/truncate.c - </sect1> - </chapter> - - - <chapter id="ipc"> - <title>Kernel IPC facilities</title> - - <sect1><title>IPC utilities</title> -!Iipc/util.c - </sect1> - </chapter> - - <chapter id="kfifo"> - <title>FIFO Buffer</title> - <sect1><title>kfifo interface</title> -!Iinclude/linux/kfifo.h - </sect1> - </chapter> - - <chapter id="relayfs"> - <title>relay interface support</title> - - <para> - Relay interface support - is designed to provide an efficient mechanism for tools and - facilities to relay large amounts of data from kernel space to - user space. - </para> - - <sect1><title>relay interface</title> -!Ekernel/relay.c -!Ikernel/relay.c - </sect1> - </chapter> - - <chapter id="modload"> - <title>Module Support</title> - <sect1><title>Module Loading</title> -!Ekernel/kmod.c - </sect1> - <sect1><title>Inter Module support</title> - <para> - Refer to the file kernel/module.c for more information. - </para> -<!-- FIXME: Removed for now since no structured comments in source -X!Ekernel/module.c ---> - </sect1> - </chapter> - - <chapter id="hardware"> - <title>Hardware Interfaces</title> - <sect1><title>Interrupt Handling</title> -!Ekernel/irq/manage.c - </sect1> - - <sect1><title>DMA Channels</title> -!Ekernel/dma.c - </sect1> - - <sect1><title>Resources Management</title> -!Ikernel/resource.c -!Ekernel/resource.c - </sect1> - - <sect1><title>MTRR Handling</title> -!Earch/x86/kernel/cpu/mtrr/main.c - </sect1> - - <sect1><title>PCI Support Library</title> -!Edrivers/pci/pci.c -!Edrivers/pci/pci-driver.c -!Edrivers/pci/remove.c -!Edrivers/pci/search.c -!Edrivers/pci/msi.c -!Edrivers/pci/bus.c -!Edrivers/pci/access.c -!Edrivers/pci/irq.c -!Edrivers/pci/htirq.c -<!-- FIXME: Removed for now since no structured comments in source -X!Edrivers/pci/hotplug.c ---> -!Edrivers/pci/probe.c -!Edrivers/pci/slot.c -!Edrivers/pci/rom.c -!Edrivers/pci/iov.c -!Idrivers/pci/pci-sysfs.c - </sect1> - <sect1><title>PCI Hotplug Support Library</title> -!Edrivers/pci/hotplug/pci_hotplug_core.c - </sect1> - </chapter> - - <chapter id="firmware"> - <title>Firmware Interfaces</title> - <sect1><title>DMI Interfaces</title> -!Edrivers/firmware/dmi_scan.c - </sect1> - <sect1><title>EDD Interfaces</title> -!Idrivers/firmware/edd.c - </sect1> - </chapter> - - <chapter id="security"> - <title>Security Framework</title> -!Isecurity/security.c -!Esecurity/inode.c - </chapter> - - <chapter id="audit"> - <title>Audit Interfaces</title> -!Ekernel/audit.c -!Ikernel/auditsc.c -!Ikernel/auditfilter.c - </chapter> - - <chapter id="accounting"> - <title>Accounting Framework</title> -!Ikernel/acct.c - </chapter> - - <chapter id="blkdev"> - <title>Block Devices</title> -!Eblock/blk-core.c -!Iblock/blk-core.c -!Eblock/blk-map.c -!Iblock/blk-sysfs.c -!Eblock/blk-settings.c -!Eblock/blk-exec.c -!Eblock/blk-flush.c -!Eblock/blk-lib.c -!Eblock/blk-tag.c -!Iblock/blk-tag.c -!Eblock/blk-integrity.c -!Ikernel/trace/blktrace.c -!Iblock/genhd.c -!Eblock/genhd.c - </chapter> - - <chapter id="chrdev"> - <title>Char devices</title> -!Efs/char_dev.c - </chapter> - - <chapter id="miscdev"> - <title>Miscellaneous Devices</title> -!Edrivers/char/misc.c - </chapter> - - <chapter id="clk"> - <title>Clock Framework</title> - - <para> - The clock framework defines programming interfaces to support - software management of the system clock tree. - This framework is widely used with System-On-Chip (SOC) platforms - to support power management and various devices which may need - custom clock rates. - Note that these "clocks" don't relate to timekeeping or real - time clocks (RTCs), each of which have separate frameworks. - These <structname>struct clk</structname> instances may be used - to manage for example a 96 MHz signal that is used to shift bits - into and out of peripherals or busses, or otherwise trigger - synchronous state machine transitions in system hardware. - </para> - - <para> - Power management is supported by explicit software clock gating: - unused clocks are disabled, so the system doesn't waste power - changing the state of transistors that aren't in active use. - On some systems this may be backed by hardware clock gating, - where clocks are gated without being disabled in software. - Sections of chips that are powered but not clocked may be able - to retain their last state. - This low power state is often called a <emphasis>retention - mode</emphasis>. - This mode still incurs leakage currents, especially with finer - circuit geometries, but for CMOS circuits power is mostly used - by clocked state changes. - </para> - - <para> - Power-aware drivers only enable their clocks when the device - they manage is in active use. Also, system sleep states often - differ according to which clock domains are active: while a - "standby" state may allow wakeup from several active domains, a - "mem" (suspend-to-RAM) state may require a more wholesale shutdown - of clocks derived from higher speed PLLs and oscillators, limiting - the number of possible wakeup event sources. A driver's suspend - method may need to be aware of system-specific clock constraints - on the target sleep state. - </para> - - <para> - Some platforms support programmable clock generators. These - can be used by external chips of various kinds, such as other - CPUs, multimedia codecs, and devices with strict requirements - for interface clocking. - </para> - -!Iinclude/linux/clk.h - </chapter> - -</book> diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl index 50479360d845..ac3cca3399a1 100644 --- a/Documentation/DocBook/rapidio.tmpl +++ b/Documentation/DocBook/rapidio.tmpl @@ -129,9 +129,6 @@ <sect1 id="Device_model_support"><title>Device model support</title> !Idrivers/rapidio/rio-driver.c </sect1> - <sect1 id="Sysfs_support"><title>Sysfs support</title> -!Idrivers/rapidio/rio-sysfs.c - </sect1> <sect1 id="PPC32_support"><title>PPC32 support</title> !Iarch/powerpc/sysdev/fsl_rio.c </sect1> diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl deleted file mode 100644 index 837eca77f274..000000000000 --- a/Documentation/DocBook/writing_musb_glue_layer.tmpl +++ /dev/null @@ -1,873 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="Writing-MUSB-Glue-Layer"> - <bookinfo> - <title>Writing an MUSB Glue Layer</title> - - <authorgroup> - <author> - <firstname>Apelete</firstname> - <surname>Seketeli</surname> - <affiliation> - <address> - <email>apelete at seketeli.net</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2014</year> - <holder>Apelete Seketeli</holder> - </copyright> - - <legalnotice> - <para> - This documentation 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. - </para> - - <para> - This documentation is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public License - along with this documentation; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA - 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the Linux kernel source - tree. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="introduction"> - <title>Introduction</title> - <para> - The Linux MUSB subsystem is part of the larger Linux USB - subsystem. It provides support for embedded USB Device Controllers - (UDC) that do not use Universal Host Controller Interface (UHCI) - or Open Host Controller Interface (OHCI). - </para> - <para> - Instead, these embedded UDC rely on the USB On-the-Go (OTG) - specification which they implement at least partially. The silicon - reference design used in most cases is the Multipoint USB - Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor - Graphics Inventraâ„¢ design. - </para> - <para> - As a self-taught exercise I have written an MUSB glue layer for - the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers - in the kernel source tree. This layer can be found at - drivers/usb/musb/jz4740.c. In this documentation I will walk - through the basics of the jz4740.c glue layer, explaining the - different pieces and what needs to be done in order to write your - own device glue layer. - </para> - </chapter> - - <chapter id="linux-musb-basics"> - <title>Linux MUSB Basics</title> - <para> - To get started on the topic, please read USB On-the-Go Basics (see - Resources) which provides an introduction of USB OTG operation at - the hardware level. A couple of wiki pages by Texas Instruments - and Analog Devices also provide an overview of the Linux kernel - MUSB configuration, albeit focused on some specific devices - provided by these companies. Finally, getting acquainted with the - USB specification at USB home page may come in handy, with - practical instance provided through the Writing USB Device Drivers - documentation (again, see Resources). - </para> - <para> - Linux USB stack is a layered architecture in which the MUSB - controller hardware sits at the lowest. The MUSB controller driver - abstract the MUSB controller hardware to the Linux USB stack. - </para> - <programlisting> - ------------------------ - | | <------- drivers/usb/gadget - | Linux USB Core Stack | <------- drivers/usb/host - | | <------- drivers/usb/core - ------------------------ - ⬠- -------------------------- - | | <------ drivers/usb/musb/musb_gadget.c - | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c - | | <------ drivers/usb/musb/musb_core.c - -------------------------- - ⬠- --------------------------------- - | MUSB Platform Specific Driver | - | | <-- drivers/usb/musb/jz4740.c - | aka "Glue Layer" | - --------------------------------- - ⬠- --------------------------------- - | MUSB Controller Hardware | - --------------------------------- - </programlisting> - <para> - As outlined above, the glue layer is actually the platform - specific code sitting in between the controller driver and the - controller hardware. - </para> - <para> - Just like a Linux USB driver needs to register itself with the - Linux USB subsystem, the MUSB glue layer needs first to register - itself with the MUSB controller driver. This will allow the - controller driver to know about which device the glue layer - supports and which functions to call when a supported device is - detected or released; remember we are talking about an embedded - controller chip here, so no insertion or removal at run-time. - </para> - <para> - All of this information is passed to the MUSB controller driver - through a platform_driver structure defined in the glue layer as: - </para> - <programlisting linenumbering="numbered"> -static struct platform_driver jz4740_driver = { - .probe = jz4740_probe, - .remove = jz4740_remove, - .driver = { - .name = "musb-jz4740", - }, -}; - </programlisting> - <para> - The probe and remove function pointers are called when a matching - device is detected and, respectively, released. The name string - describes the device supported by this glue layer. In the current - case it matches a platform_device structure declared in - arch/mips/jz4740/platform.c. Note that we are not using device - tree bindings here. - </para> - <para> - In order to register itself to the controller driver, the glue - layer goes through a few steps, basically allocating the - controller hardware resources and initialising a couple of - circuits. To do so, it needs to keep track of the information used - throughout these steps. This is done by defining a private - jz4740_glue structure: - </para> - <programlisting linenumbering="numbered"> -struct jz4740_glue { - struct device *dev; - struct platform_device *musb; - struct clk *clk; -}; - </programlisting> - <para> - The dev and musb members are both device structure variables. The - first one holds generic information about the device, since it's - the basic device structure, and the latter holds information more - closely related to the subsystem the device is registered to. The - clk variable keeps information related to the device clock - operation. - </para> - <para> - Let's go through the steps of the probe function that leads the - glue layer to register itself to the controller driver. - </para> - <para> - N.B.: For the sake of readability each function will be split in - logical parts, each part being shown as if it was independent from - the others. - </para> - <programlisting linenumbering="numbered"> -static int jz4740_probe(struct platform_device *pdev) -{ - struct platform_device *musb; - struct jz4740_glue *glue; - struct clk *clk; - int ret; - - glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); - if (!glue) - return -ENOMEM; - - musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); - if (!musb) { - dev_err(&pdev->dev, "failed to allocate musb device\n"); - return -ENOMEM; - } - - clk = devm_clk_get(&pdev->dev, "udc"); - if (IS_ERR(clk)) { - dev_err(&pdev->dev, "failed to get clock\n"); - ret = PTR_ERR(clk); - goto err_platform_device_put; - } - - ret = clk_prepare_enable(clk); - if (ret) { - dev_err(&pdev->dev, "failed to enable clock\n"); - goto err_platform_device_put; - } - - musb->dev.parent = &pdev->dev; - - glue->dev = &pdev->dev; - glue->musb = musb; - glue->clk = clk; - - return 0; - -err_platform_device_put: - platform_device_put(musb); - return ret; -} - </programlisting> - <para> - The first few lines of the probe function allocate and assign the - glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows - the allocation process to sleep and wait for memory, thus being - usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line - 12) allows automatic allocation and management of device IDs in - order to avoid device namespace collisions with explicit IDs. With - devm_clk_get() (line 18) the glue layer allocates the clock -- the - <literal>devm_</literal> prefix indicates that clk_get() is - managed: it automatically frees the allocated clock resource data - when the device is released -- and enable it. - </para> - <para> - Then comes the registration steps: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_probe(struct platform_device *pdev) -{ - struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; - - pdata->platform_ops = &jz4740_musb_ops; - - platform_set_drvdata(pdev, glue); - - ret = platform_device_add_resources(musb, pdev->resource, - pdev->num_resources); - if (ret) { - dev_err(&pdev->dev, "failed to add resources\n"); - goto err_clk_disable; - } - - ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); - if (ret) { - dev_err(&pdev->dev, "failed to add platform_data\n"); - goto err_clk_disable; - } - - return 0; - -err_clk_disable: - clk_disable_unprepare(clk); -err_platform_device_put: - platform_device_put(musb); - return ret; -} - </programlisting> - <para> - The first step is to pass the device data privately held by the - glue layer on to the controller driver through - platform_set_drvdata() (line 7). Next is passing on the device - resources information, also privately held at that point, through - platform_device_add_resources() (line 9). - </para> - <para> - Finally comes passing on the platform specific data to the - controller driver (line 16). Platform data will be discussed in - <link linkend="device-platform-data">Chapter 4</link>, but here - we are looking at the platform_ops function pointer (line 5) in - musb_hdrc_platform_data structure (line 3). This function - pointer allows the MUSB controller driver to know which function - to call for device operation: - </para> - <programlisting linenumbering="numbered"> -static const struct musb_platform_ops jz4740_musb_ops = { - .init = jz4740_musb_init, - .exit = jz4740_musb_exit, -}; - </programlisting> - <para> - Here we have the minimal case where only init and exit functions - are called by the controller driver when needed. Fact is the - JZ4740 MUSB controller is a basic controller, lacking some - features found in other controllers, otherwise we may also have - pointers to a few other functions like a power management function - or a function to switch between OTG and non-OTG modes, for - instance. - </para> - <para> - At that point of the registration process, the controller driver - actually calls the init function: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_init(struct musb *musb) -{ - musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); - if (!musb->xceiv) { - pr_err("HS UDC: no transceiver configured\n"); - return -ENODEV; - } - - /* Silicon does not implement ConfigData register. - * Set dyn_fifo to avoid reading EP config from hardware. - */ - musb->dyn_fifo = true; - - musb->isr = jz4740_musb_interrupt; - - return 0; -} - </programlisting> - <para> - The goal of jz4740_musb_init() is to get hold of the transceiver - driver data of the MUSB controller hardware and pass it on to the - MUSB controller driver, as usual. The transceiver is the circuitry - inside the controller hardware responsible for sending/receiving - the USB data. Since it is an implementation of the physical layer - of the OSI model, the transceiver is also referred to as PHY. - </para> - <para> - Getting hold of the MUSB PHY driver data is done with - usb_get_phy() which returns a pointer to the structure - containing the driver instance data. The next couple of - instructions (line 12 and 14) are used as a quirk and to setup - IRQ handling respectively. Quirks and IRQ handling will be - discussed later in <link linkend="device-quirks">Chapter - 5</link> and <link linkend="handling-irqs">Chapter 3</link>. - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_exit(struct musb *musb) -{ - usb_put_phy(musb->xceiv); - - return 0; -} - </programlisting> - <para> - Acting as the counterpart of init, the exit function releases the - MUSB PHY driver when the controller hardware itself is about to be - released. - </para> - <para> - Again, note that init and exit are fairly simple in this case due - to the basic set of features of the JZ4740 controller hardware. - When writing an musb glue layer for a more complex controller - hardware, you might need to take care of more processing in those - two functions. - </para> - <para> - Returning from the init function, the MUSB controller driver jumps - back into the probe function: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_probe(struct platform_device *pdev) -{ - ret = platform_device_add(musb); - if (ret) { - dev_err(&pdev->dev, "failed to register musb device\n"); - goto err_clk_disable; - } - - return 0; - -err_clk_disable: - clk_disable_unprepare(clk); -err_platform_device_put: - platform_device_put(musb); - return ret; -} - </programlisting> - <para> - This is the last part of the device registration process where the - glue layer adds the controller hardware device to Linux kernel - device hierarchy: at this stage, all known information about the - device is passed on to the Linux USB core stack. - </para> - <programlisting linenumbering="numbered"> -static int jz4740_remove(struct platform_device *pdev) -{ - struct jz4740_glue *glue = platform_get_drvdata(pdev); - - platform_device_unregister(glue->musb); - clk_disable_unprepare(glue->clk); - - return 0; -} - </programlisting> - <para> - Acting as the counterpart of probe, the remove function unregister - the MUSB controller hardware (line 5) and disable the clock (line - 6), allowing it to be gated. - </para> - </chapter> - - <chapter id="handling-irqs"> - <title>Handling IRQs</title> - <para> - Additionally to the MUSB controller hardware basic setup and - registration, the glue layer is also responsible for handling the - IRQs: - </para> - <programlisting linenumbering="numbered"> -static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) -{ - unsigned long flags; - irqreturn_t retval = IRQ_NONE; - struct musb *musb = __hci; - - spin_lock_irqsave(&musb->lock, flags); - - musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); - musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); - musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); - - /* - * The controller is gadget only, the state of the host mode IRQ bits is - * undefined. Mask them to make sure that the musb driver core will - * never see them set - */ - musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | - MUSB_INTR_RESET | MUSB_INTR_SOF; - - if (musb->int_usb || musb->int_tx || musb->int_rx) - retval = musb_interrupt(musb); - - spin_unlock_irqrestore(&musb->lock, flags); - - return retval; -} - </programlisting> - <para> - Here the glue layer mostly has to read the relevant hardware - registers and pass their values on to the controller driver which - will handle the actual event that triggered the IRQ. - </para> - <para> - The interrupt handler critical section is protected by the - spin_lock_irqsave() and counterpart spin_unlock_irqrestore() - functions (line 7 and 24 respectively), which prevent the - interrupt handler code to be run by two different threads at the - same time. - </para> - <para> - Then the relevant interrupt registers are read (line 9 to 11): - </para> - <itemizedlist> - <listitem> - <para> - MUSB_INTRUSB: indicates which USB interrupts are currently - active, - </para> - </listitem> - <listitem> - <para> - MUSB_INTRTX: indicates which of the interrupts for TX - endpoints are currently active, - </para> - </listitem> - <listitem> - <para> - MUSB_INTRRX: indicates which of the interrupts for TX - endpoints are currently active. - </para> - </listitem> - </itemizedlist> - <para> - Note that musb_readb() is used to read 8-bit registers at most, - while musb_readw() allows us to read at most 16-bit registers. - There are other functions that can be used depending on the size - of your device registers. See musb_io.h for more information. - </para> - <para> - Instruction on line 18 is another quirk specific to the JZ4740 - USB device controller, which will be discussed later in <link - linkend="device-quirks">Chapter 5</link>. - </para> - <para> - The glue layer still needs to register the IRQ handler though. - Remember the instruction on line 14 of the init function: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_init(struct musb *musb) -{ - musb->isr = jz4740_musb_interrupt; - - return 0; -} - </programlisting> - <para> - This instruction sets a pointer to the glue layer IRQ handler - function, in order for the controller hardware to call the handler - back when an IRQ comes from the controller hardware. The interrupt - handler is now implemented and registered. - </para> - </chapter> - - <chapter id="device-platform-data"> - <title>Device Platform Data</title> - <para> - In order to write an MUSB glue layer, you need to have some data - describing the hardware capabilities of your controller hardware, - which is called the platform data. - </para> - <para> - Platform data is specific to your hardware, though it may cover a - broad range of devices, and is generally found somewhere in the - arch/ directory, depending on your device architecture. - </para> - <para> - For instance, platform data for the JZ4740 SoC is found in - arch/mips/jz4740/platform.c. In the platform.c file each device of - the JZ4740 SoC is described through a set of structures. - </para> - <para> - Here is the part of arch/mips/jz4740/platform.c that covers the - USB Device Controller (UDC): - </para> - <programlisting linenumbering="numbered"> -/* USB Device Controller */ -struct platform_device jz4740_udc_xceiv_device = { - .name = "usb_phy_gen_xceiv", - .id = 0, -}; - -static struct resource jz4740_udc_resources[] = { - [0] = { - .start = JZ4740_UDC_BASE_ADDR, - .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1, - .flags = IORESOURCE_MEM, - }, - [1] = { - .start = JZ4740_IRQ_UDC, - .end = JZ4740_IRQ_UDC, - .flags = IORESOURCE_IRQ, - .name = "mc", - }, -}; - -struct platform_device jz4740_udc_device = { - .name = "musb-jz4740", - .id = -1, - .dev = { - .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask, - .coherent_dma_mask = DMA_BIT_MASK(32), - }, - .num_resources = ARRAY_SIZE(jz4740_udc_resources), - .resource = jz4740_udc_resources, -}; - </programlisting> - <para> - The jz4740_udc_xceiv_device platform device structure (line 2) - describes the UDC transceiver with a name and id number. - </para> - <para> - At the time of this writing, note that - "usb_phy_gen_xceiv" is the specific name to be used for - all transceivers that are either built-in with reference USB IP or - autonomous and doesn't require any PHY programming. You will need - to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make - use of the corresponding transceiver driver. The id field could be - set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to - PLATFORM_DEVID_AUTO) or start with 0 for the first device of this - kind if we want a specific id number. - </para> - <para> - The jz4740_udc_resources resource structure (line 7) defines the - UDC registers base addresses. - </para> - <para> - The first array (line 9 to 11) defines the UDC registers base - memory addresses: start points to the first register memory - address, end points to the last register memory address and the - flags member defines the type of resource we are dealing with. So - IORESOURCE_MEM is used to define the registers memory addresses. - The second array (line 14 to 17) defines the UDC IRQ registers - addresses. Since there is only one IRQ register available for the - JZ4740 UDC, start and end point at the same address. The - IORESOURCE_IRQ flag tells that we are dealing with IRQ resources, - and the name "mc" is in fact hard-coded in the MUSB core - in order for the controller driver to retrieve this IRQ resource - by querying it by its name. - </para> - <para> - Finally, the jz4740_udc_device platform device structure (line 21) - describes the UDC itself. - </para> - <para> - The "musb-jz4740" name (line 22) defines the MUSB - driver that is used for this device; remember this is in fact - the name that we used in the jz4740_driver platform driver - structure in <link linkend="linux-musb-basics">Chapter - 2</link>. The id field (line 23) is set to -1 (equivalent to - PLATFORM_DEVID_NONE) since we do not need an id for the device: - the MUSB controller driver was already set to allocate an - automatic id in <link linkend="linux-musb-basics">Chapter - 2</link>. In the dev field we care for DMA related information - here. The dma_mask field (line 25) defines the width of the DMA - mask that is going to be used, and coherent_dma_mask (line 26) - has the same purpose but for the alloc_coherent DMA mappings: in - both cases we are using a 32 bits mask. Then the resource field - (line 29) is simply a pointer to the resource structure defined - before, while the num_resources field (line 28) keeps track of - the number of arrays defined in the resource structure (in this - case there were two resource arrays defined before). - </para> - <para> - With this quick overview of the UDC platform data at the arch/ - level now done, let's get back to the MUSB glue layer specific - platform data in drivers/usb/musb/jz4740.c: - </para> - <programlisting linenumbering="numbered"> -static struct musb_hdrc_config jz4740_musb_config = { - /* Silicon does not implement USB OTG. */ - .multipoint = 0, - /* Max EPs scanned, driver will decide which EP can be used. */ - .num_eps = 4, - /* RAMbits needed to configure EPs from table */ - .ram_bits = 9, - .fifo_cfg = jz4740_musb_fifo_cfg, - .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg), -}; - -static struct musb_hdrc_platform_data jz4740_musb_platform_data = { - .mode = MUSB_PERIPHERAL, - .config = &jz4740_musb_config, -}; - </programlisting> - <para> - First the glue layer configures some aspects of the controller - driver operation related to the controller hardware specifics. - This is done through the jz4740_musb_config musb_hdrc_config - structure. - </para> - <para> - Defining the OTG capability of the controller hardware, the - multipoint member (line 3) is set to 0 (equivalent to false) - since the JZ4740 UDC is not OTG compatible. Then num_eps (line - 5) defines the number of USB endpoints of the controller - hardware, including endpoint 0: here we have 3 endpoints + - endpoint 0. Next is ram_bits (line 7) which is the width of the - RAM address bus for the MUSB controller hardware. This - information is needed when the controller driver cannot - automatically configure endpoints by reading the relevant - controller hardware registers. This issue will be discussed when - we get to device quirks in <link linkend="device-quirks">Chapter - 5</link>. Last two fields (line 8 and 9) are also about device - quirks: fifo_cfg points to the USB endpoints configuration table - and fifo_cfg_size keeps track of the size of the number of - entries in that configuration table. More on that later in <link - linkend="device-quirks">Chapter 5</link>. - </para> - <para> - Then this configuration is embedded inside - jz4740_musb_platform_data musb_hdrc_platform_data structure (line - 11): config is a pointer to the configuration structure itself, - and mode tells the controller driver if the controller hardware - may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG - which is a dual mode. - </para> - <para> - Remember that jz4740_musb_platform_data is then used to convey - platform data information as we have seen in the probe function - in <link linkend="linux-musb-basics">Chapter 2</link> - </para> - </chapter> - - <chapter id="device-quirks"> - <title>Device Quirks</title> - <para> - Completing the platform data specific to your device, you may also - need to write some code in the glue layer to work around some - device specific limitations. These quirks may be due to some - hardware bugs, or simply be the result of an incomplete - implementation of the USB On-the-Go specification. - </para> - <para> - The JZ4740 UDC exhibits such quirks, some of which we will discuss - here for the sake of insight even though these might not be found - in the controller hardware you are working on. - </para> - <para> - Let's get back to the init function first: - </para> - <programlisting linenumbering="numbered"> -static int jz4740_musb_init(struct musb *musb) -{ - musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); - if (!musb->xceiv) { - pr_err("HS UDC: no transceiver configured\n"); - return -ENODEV; - } - - /* Silicon does not implement ConfigData register. - * Set dyn_fifo to avoid reading EP config from hardware. - */ - musb->dyn_fifo = true; - - musb->isr = jz4740_musb_interrupt; - - return 0; -} - </programlisting> - <para> - Instruction on line 12 helps the MUSB controller driver to work - around the fact that the controller hardware is missing registers - that are used for USB endpoints configuration. - </para> - <para> - Without these registers, the controller driver is unable to read - the endpoints configuration from the hardware, so we use line 12 - instruction to bypass reading the configuration from silicon, and - rely on a hard-coded table that describes the endpoints - configuration instead: - </para> - <programlisting linenumbering="numbered"> -static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = { -{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, }, -{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, }, -{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, }, -}; - </programlisting> - <para> - Looking at the configuration table above, we see that each - endpoints is described by three fields: hw_ep_num is the endpoint - number, style is its direction (either FIFO_TX for the controller - driver to send packets in the controller hardware, or FIFO_RX to - receive packets from hardware), and maxpacket defines the maximum - size of each data packet that can be transmitted over that - endpoint. Reading from the table, the controller driver knows that - endpoint 1 can be used to send and receive USB data packets of 512 - bytes at once (this is in fact a bulk in/out endpoint), and - endpoint 2 can be used to send data packets of 64 bytes at once - (this is in fact an interrupt endpoint). - </para> - <para> - Note that there is no information about endpoint 0 here: that one - is implemented by default in every silicon design, with a - predefined configuration according to the USB specification. For - more examples of endpoint configuration tables, see musb_core.c. - </para> - <para> - Let's now get back to the interrupt handler function: - </para> - <programlisting linenumbering="numbered"> -static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) -{ - unsigned long flags; - irqreturn_t retval = IRQ_NONE; - struct musb *musb = __hci; - - spin_lock_irqsave(&musb->lock, flags); - - musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); - musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); - musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); - - /* - * The controller is gadget only, the state of the host mode IRQ bits is - * undefined. Mask them to make sure that the musb driver core will - * never see them set - */ - musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | - MUSB_INTR_RESET | MUSB_INTR_SOF; - - if (musb->int_usb || musb->int_tx || musb->int_rx) - retval = musb_interrupt(musb); - - spin_unlock_irqrestore(&musb->lock, flags); - - return retval; -} - </programlisting> - <para> - Instruction on line 18 above is a way for the controller driver to - work around the fact that some interrupt bits used for USB host - mode operation are missing in the MUSB_INTRUSB register, thus left - in an undefined hardware state, since this MUSB controller - hardware is used in peripheral mode only. As a consequence, the - glue layer masks these missing bits out to avoid parasite - interrupts by doing a logical AND operation between the value read - from MUSB_INTRUSB and the bits that are actually implemented in - the register. - </para> - <para> - These are only a couple of the quirks found in the JZ4740 USB - device controller. Some others were directly addressed in the MUSB - core since the fixes were generic enough to provide a better - handling of the issues for others controller hardware eventually. - </para> - </chapter> - - <chapter id="conclusion"> - <title>Conclusion</title> - <para> - Writing a Linux MUSB glue layer should be a more accessible task, - as this documentation tries to show the ins and outs of this - exercise. - </para> - <para> - The JZ4740 USB device controller being fairly simple, I hope its - glue layer serves as a good example for the curious mind. Used - with the current MUSB glue layers, this documentation should - provide enough guidance to get started; should anything gets out - of hand, the linux-usb mailing list archive is another helpful - resource to browse through. - </para> - </chapter> - - <chapter id="acknowledgements"> - <title>Acknowledgements</title> - <para> - Many thanks to Lars-Peter Clausen and Maarten ter Huurne for - answering my questions while I was writing the JZ4740 glue layer - and for helping me out getting the code in good shape. - </para> - <para> - I would also like to thank the Qi-Hardware community at large for - its cheerful guidance and support. - </para> - </chapter> - - <chapter id="resources"> - <title>Resources</title> - <para> - USB Home Page: - <ulink url="http://www.usb.org">http://www.usb.org</ulink> - </para> - <para> - linux-usb Mailing List Archives: - <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink> - </para> - <para> - USB On-the-Go Basics: - <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink> - </para> - <para> - Writing USB Device Drivers: - <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink> - </para> - <para> - Texas Instruments USB Configuration Wiki Page: - <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink> - </para> - <para> - Analog Devices Blackfin MUSB Configuration: - <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink> - </para> - </chapter> - -</book> diff --git a/Documentation/DocBook/writing_usb_driver.tmpl b/Documentation/DocBook/writing_usb_driver.tmpl deleted file mode 100644 index 3210dcf741c9..000000000000 --- a/Documentation/DocBook/writing_usb_driver.tmpl +++ /dev/null @@ -1,412 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="USBDeviceDriver"> - <bookinfo> - <title>Writing USB Device Drivers</title> - - <authorgroup> - <author> - <firstname>Greg</firstname> - <surname>Kroah-Hartman</surname> - <affiliation> - <address> - <email>greg@kroah.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2001-2002</year> - <holder>Greg Kroah-Hartman</holder> - </copyright> - - <legalnotice> - <para> - This documentation 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. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - - <para> - This documentation is based on an article published in - Linux Journal Magazine, October 2001, Issue 90. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The Linux USB subsystem has grown from supporting only two different - types of devices in the 2.2.7 kernel (mice and keyboards), to over 20 - different types of devices in the 2.4 kernel. Linux currently supports - almost all USB class devices (standard types of devices like keyboards, - mice, modems, printers and speakers) and an ever-growing number of - vendor-specific devices (such as USB to serial converters, digital - cameras, Ethernet devices and MP3 players). For a full list of the - different USB devices currently supported, see Resources. - </para> - <para> - The remaining kinds of USB devices that do not have support on Linux are - almost all vendor-specific devices. Each vendor decides to implement a - custom protocol to talk to their device, so a custom driver usually needs - to be created. Some vendors are open with their USB protocols and help - with the creation of Linux drivers, while others do not publish them, and - developers are forced to reverse-engineer. See Resources for some links - to handy reverse-engineering tools. - </para> - <para> - Because each different protocol causes a new driver to be created, I have - written a generic USB driver skeleton, modelled after the pci-skeleton.c - file in the kernel source tree upon which many PCI network drivers have - been based. This USB skeleton can be found at drivers/usb/usb-skeleton.c - in the kernel source tree. In this article I will walk through the basics - of the skeleton driver, explaining the different pieces and what needs to - be done to customize it to your specific device. - </para> - </chapter> - - <chapter id="basics"> - <title>Linux USB Basics</title> - <para> - If you are going to write a Linux USB driver, please become familiar with - the USB protocol specification. It can be found, along with many other - useful documents, at the USB home page (see Resources). An excellent - introduction to the Linux USB subsystem can be found at the USB Working - Devices List (see Resources). It explains how the Linux USB subsystem is - structured and introduces the reader to the concept of USB urbs - (USB Request Blocks), which are essential to USB drivers. - </para> - <para> - The first thing a Linux USB driver needs to do is register itself with - the Linux USB subsystem, giving it some information about which devices - the driver supports and which functions to call when a device supported - by the driver is inserted or removed from the system. All of this - information is passed to the USB subsystem in the usb_driver structure. - The skeleton driver declares a usb_driver as: - </para> - <programlisting> -static struct usb_driver skel_driver = { - .name = "skeleton", - .probe = skel_probe, - .disconnect = skel_disconnect, - .fops = &skel_fops, - .minor = USB_SKEL_MINOR_BASE, - .id_table = skel_table, -}; - </programlisting> - <para> - The variable name is a string that describes the driver. It is used in - informational messages printed to the system log. The probe and - disconnect function pointers are called when a device that matches the - information provided in the id_table variable is either seen or removed. - </para> - <para> - The fops and minor variables are optional. Most USB drivers hook into - another kernel subsystem, such as the SCSI, network or TTY subsystem. - These types of drivers register themselves with the other kernel - subsystem, and any user-space interactions are provided through that - interface. But for drivers that do not have a matching kernel subsystem, - such as MP3 players or scanners, a method of interacting with user space - is needed. The USB subsystem provides a way to register a minor device - number and a set of file_operations function pointers that enable this - user-space interaction. The skeleton driver needs this kind of interface, - so it provides a minor starting number and a pointer to its - file_operations functions. - </para> - <para> - The USB driver is then registered with a call to usb_register, usually in - the driver's init function, as shown here: - </para> - <programlisting> -static int __init usb_skel_init(void) -{ - int result; - - /* register this driver with the USB subsystem */ - result = usb_register(&skel_driver); - if (result < 0) { - err("usb_register failed for the "__FILE__ "driver." - "Error number %d", result); - return -1; - } - - return 0; -} -module_init(usb_skel_init); - </programlisting> - <para> - When the driver is unloaded from the system, it needs to deregister - itself with the USB subsystem. This is done with the usb_deregister - function: - </para> - <programlisting> -static void __exit usb_skel_exit(void) -{ - /* deregister this driver with the USB subsystem */ - usb_deregister(&skel_driver); -} -module_exit(usb_skel_exit); - </programlisting> - <para> - To enable the linux-hotplug system to load the driver automatically when - the device is plugged in, you need to create a MODULE_DEVICE_TABLE. The - following code tells the hotplug scripts that this module supports a - single device with a specific vendor and product ID: - </para> - <programlisting> -/* table of devices that work with this driver */ -static struct usb_device_id skel_table [] = { - { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) }, - { } /* Terminating entry */ -}; -MODULE_DEVICE_TABLE (usb, skel_table); - </programlisting> - <para> - There are other macros that can be used in describing a usb_device_id for - drivers that support a whole class of USB drivers. See usb.h for more - information on this. - </para> - </chapter> - - <chapter id="device"> - <title>Device operation</title> - <para> - When a device is plugged into the USB bus that matches the device ID - pattern that your driver registered with the USB core, the probe function - is called. The usb_device structure, interface number and the interface ID - are passed to the function: - </para> - <programlisting> -static int skel_probe(struct usb_interface *interface, - const struct usb_device_id *id) - </programlisting> - <para> - The driver now needs to verify that this device is actually one that it - can accept. If so, it returns 0. - If not, or if any error occurs during initialization, an errorcode - (such as <literal>-ENOMEM</literal> or <literal>-ENODEV</literal>) - is returned from the probe function. - </para> - <para> - In the skeleton driver, we determine what end points are marked as bulk-in - and bulk-out. We create buffers to hold the data that will be sent and - received from the device, and a USB urb to write data to the device is - initialized. - </para> - <para> - Conversely, when the device is removed from the USB bus, the disconnect - function is called with the device pointer. The driver needs to clean any - private data that has been allocated at this time and to shut down any - pending urbs that are in the USB system. - </para> - <para> - Now that the device is plugged into the system and the driver is bound to - the device, any of the functions in the file_operations structure that - were passed to the USB subsystem will be called from a user program trying - to talk to the device. The first function called will be open, as the - program tries to open the device for I/O. We increment our private usage - count and save a pointer to our internal structure in the file - structure. This is done so that future calls to file operations will - enable the driver to determine which device the user is addressing. All - of this is done with the following code: - </para> - <programlisting> -/* increment our usage count for the module */ -++skel->open_count; - -/* save our object in the file's private structure */ -file->private_data = dev; - </programlisting> - <para> - After the open function is called, the read and write functions are called - to receive and send data to the device. In the skel_write function, we - receive a pointer to some data that the user wants to send to the device - and the size of the data. The function determines how much data it can - send to the device based on the size of the write urb it has created (this - size depends on the size of the bulk out end point that the device has). - Then it copies the data from user space to kernel space, points the urb to - the data and submits the urb to the USB subsystem. This can be seen in - the following code: - </para> - <programlisting> -/* we can only write as much as 1 urb will hold */ -bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count; - -/* copy the data from user space into our urb */ -copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written); - -/* set up our urb */ -usb_fill_bulk_urb(skel->write_urb, - skel->dev, - usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr), - skel->write_urb->transfer_buffer, - bytes_written, - skel_write_bulk_callback, - skel); - -/* send the data out the bulk port */ -result = usb_submit_urb(skel->write_urb); -if (result) { - err("Failed submitting write urb, error %d", result); -} - </programlisting> - <para> - When the write urb is filled up with the proper information using the - usb_fill_bulk_urb function, we point the urb's completion callback to call our - own skel_write_bulk_callback function. This function is called when the - urb is finished by the USB subsystem. The callback function is called in - interrupt context, so caution must be taken not to do very much processing - at that time. Our implementation of skel_write_bulk_callback merely - reports if the urb was completed successfully or not and then returns. - </para> - <para> - The read function works a bit differently from the write function in that - we do not use an urb to transfer data from the device to the driver. - Instead we call the usb_bulk_msg function, which can be used to send or - receive data from a device without having to create urbs and handle - urb completion callback functions. We call the usb_bulk_msg function, - giving it a buffer into which to place any data received from the device - and a timeout value. If the timeout period expires without receiving any - data from the device, the function will fail and return an error message. - This can be shown with the following code: - </para> - <programlisting> -/* do an immediate bulk read to get data from the device */ -retval = usb_bulk_msg (skel->dev, - usb_rcvbulkpipe (skel->dev, - skel->bulk_in_endpointAddr), - skel->bulk_in_buffer, - skel->bulk_in_size, - &count, HZ*10); -/* if the read was successful, copy the data to user space */ -if (!retval) { - if (copy_to_user (buffer, skel->bulk_in_buffer, count)) - retval = -EFAULT; - else - retval = count; -} - </programlisting> - <para> - The usb_bulk_msg function can be very useful for doing single reads or - writes to a device; however, if you need to read or write constantly to a - device, it is recommended to set up your own urbs and submit them to the - USB subsystem. - </para> - <para> - When the user program releases the file handle that it has been using to - talk to the device, the release function in the driver is called. In this - function we decrement our private usage count and wait for possible - pending writes: - </para> - <programlisting> -/* decrement our usage count for the device */ ---skel->open_count; - </programlisting> - <para> - One of the more difficult problems that USB drivers must be able to handle - smoothly is the fact that the USB device may be removed from the system at - any point in time, even if a program is currently talking to it. It needs - to be able to shut down any current reads and writes and notify the - user-space programs that the device is no longer there. The following - code (function <function>skel_delete</function>) - is an example of how to do this: </para> - <programlisting> -static inline void skel_delete (struct usb_skel *dev) -{ - kfree (dev->bulk_in_buffer); - if (dev->bulk_out_buffer != NULL) - usb_free_coherent (dev->udev, dev->bulk_out_size, - dev->bulk_out_buffer, - dev->write_urb->transfer_dma); - usb_free_urb (dev->write_urb); - kfree (dev); -} - </programlisting> - <para> - If a program currently has an open handle to the device, we reset the flag - <literal>device_present</literal>. For - every read, write, release and other functions that expect a device to be - present, the driver first checks this flag to see if the device is - still present. If not, it releases that the device has disappeared, and a - -ENODEV error is returned to the user-space program. When the release - function is eventually called, it determines if there is no device - and if not, it does the cleanup that the skel_disconnect - function normally does if there are no open files on the device (see - Listing 5). - </para> - </chapter> - - <chapter id="iso"> - <title>Isochronous Data</title> - <para> - This usb-skeleton driver does not have any examples of interrupt or - isochronous data being sent to or from the device. Interrupt data is sent - almost exactly as bulk data is, with a few minor exceptions. Isochronous - data works differently with continuous streams of data being sent to or - from the device. The audio and video camera drivers are very good examples - of drivers that handle isochronous data and will be useful if you also - need to do this. - </para> - </chapter> - - <chapter id="Conclusion"> - <title>Conclusion</title> - <para> - Writing Linux USB device drivers is not a difficult task as the - usb-skeleton driver shows. This driver, combined with the other current - USB drivers, should provide enough examples to help a beginning author - create a working driver in a minimal amount of time. The linux-usb-devel - mailing list archives also contain a lot of helpful information. - </para> - </chapter> - - <chapter id="resources"> - <title>Resources</title> - <para> - The Linux USB Project: <ulink url="http://www.linux-usb.org">http://www.linux-usb.org/</ulink> - </para> - <para> - Linux Hotplug Project: <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net/</ulink> - </para> - <para> - Linux USB Working Devices List: <ulink url="http://www.qbik.ch/usb/devices">http://www.qbik.ch/usb/devices/</ulink> - </para> - <para> - linux-usb-devel Mailing List Archives: <ulink url="http://marc.theaimsgroup.com/?l=linux-usb-devel">http://marc.theaimsgroup.com/?l=linux-usb-devel</ulink> - </para> - <para> - Programming Guide for Linux USB Device Drivers: <ulink url="http://usb.cs.tum.edu/usbdoc">http://usb.cs.tum.edu/usbdoc</ulink> - </para> - <para> - USB Home Page: <ulink url="http://www.usb.org">http://www.usb.org</ulink> - </para> - </chapter> - -</book> diff --git a/Documentation/EDID/edid.S b/Documentation/EDID/edid.S index 7ac03276d7a2..ef082dcc6084 100644 --- a/Documentation/EDID/edid.S +++ b/Documentation/EDID/edid.S @@ -59,9 +59,9 @@ /* Fixed header pattern */ header: .byte 0x00,0xff,0xff,0xff,0xff,0xff,0xff,0x00 -mfg_id: .word swap16(mfgname2id(MFG_LNX1, MFG_LNX2, MFG_LNX3)) +mfg_id: .hword swap16(mfgname2id(MFG_LNX1, MFG_LNX2, MFG_LNX3)) -prod_code: .word 0 +prod_code: .hword 0 /* Serial number. 32 bits, little endian. */ serial_number: .long SERIAL @@ -177,7 +177,7 @@ std_vres: .byte (XY_RATIO<<6)+VFREQ-60 descriptor1: /* Pixel clock in 10 kHz units. (0.-655.35 MHz, little-endian) */ -clock: .word CLOCK/10 +clock: .hword CLOCK/10 /* Horizontal active pixels 8 lsbits (0-4095) */ x_act_lsb: .byte XPIX&0xff diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX index 147231f1613e..00c9a90b6f38 100644 --- a/Documentation/PCI/00-INDEX +++ b/Documentation/PCI/00-INDEX @@ -12,3 +12,13 @@ pci.txt - info on the PCI subsystem for device driver authors pcieaer-howto.txt - the PCI Express Advanced Error Reporting Driver Guide HOWTO +endpoint/pci-endpoint.txt + - guide to add endpoint controller driver and endpoint function driver. +endpoint/pci-endpoint-cfs.txt + - guide to use configfs to configure the PCI endpoint function. +endpoint/pci-test-function.txt + - specification of *PCI test* function device. +endpoint/pci-test-howto.txt + - userguide for PCI endpoint test function. +endpoint/function/binding/ + - binding documentation for PCI endpoint function diff --git a/Documentation/PCI/endpoint/function/binding/pci-test.txt b/Documentation/PCI/endpoint/function/binding/pci-test.txt new file mode 100644 index 000000000000..3b68b955fb50 --- /dev/null +++ b/Documentation/PCI/endpoint/function/binding/pci-test.txt @@ -0,0 +1,17 @@ +PCI TEST ENDPOINT FUNCTION + +name: Should be "pci_epf_test" to bind to the pci_epf_test driver. + +Configurable Fields: +vendorid : should be 0x104c +deviceid : should be 0xb500 for DRA74x and 0xb501 for DRA72x +revid : don't care +progif_code : don't care +subclass_code : don't care +baseclass_code : should be 0xff +cache_line_size : don't care +subsys_vendor_id : don't care +subsys_id : don't care +interrupt_pin : Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD +msi_interrupts : Should be 1 to 32 depending on the number of MSI interrupts + to test diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt new file mode 100644 index 000000000000..d740f29960a4 --- /dev/null +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt @@ -0,0 +1,105 @@ + CONFIGURING PCI ENDPOINT USING CONFIGFS + 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 + +The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs +directory. configfs can be mounted using the following command. + + mount -t configfs none /sys/kernel/config + +*) 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/ + +*) 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>/ + +In order to create a <EPF device> of the type probed by <EPF Driver>, the +user has to create a directory inside <EPF DriverN>. + +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 + +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 + +The <EPC Device> directory will have a list of symbolic links to +<EPF Device>. These symbolic links should be created by the user to +represent the functions present in the endpoint device. + +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>/ + | <Symbolic Link: Function> + | start + | functions/ + | <Directory: EPF driver>/ + | <Directory: EPF device>/ + | vendorid + | deviceid + | revid + | progif_code + | subclass_code + | baseclass_code + | cache_line_size + | subsys_vendor_id + | subsys_id + | interrupt_pin + | function + +[1] -> Documentation/PCI/endpoint/pci-endpoint.txt diff --git a/Documentation/PCI/endpoint/pci-endpoint.txt b/Documentation/PCI/endpoint/pci-endpoint.txt new file mode 100644 index 000000000000..9b1d66829290 --- /dev/null +++ b/Documentation/PCI/endpoint/pci-endpoint.txt @@ -0,0 +1,215 @@ + PCI ENDPOINT FRAMEWORK + 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 + +Linux has a comprehensive PCI subsystem to support PCI controllers that +operates in Root Complex mode. The subsystem has capability to scan PCI bus, +assign memory resources and IRQ resources, load PCI driver (based on +vendor ID, device ID), support other services like hot-plug, power management, +advanced error reporting and virtual channels. + +However the PCI controller IP integrated in some SoCs is capable of operating +either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will +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 + +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 + +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 + +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() + + 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 + * alloc_addr_space: ops to allocate in PCI controller address space + * free_addr_space: ops to free the allocated address space + * raise_irq: ops to raise a legacy or MSI interrupt + * start: ops to start the PCI link + * stop: ops to stop the PCI link + + 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() + + 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() + + 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() + + Initialize the pci_epc_mem structure used for allocating EPC addr space. + +*) 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 + +This section lists the APIs that the PCI Endpoint core provides to be used +by the PCI endpoint function driver. + +*) 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() + + 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() + + The PCI endpoint function driver should use pci_epc_clear_bar() to reset + the BAR. + +*) pci_epc_raise_irq() + + The PCI endpoint function driver should use pci_epc_raise_irq() to raise + Legacy Interrupt or MSI Interrupt. + +*) 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() + + 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 + +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() + + Get a reference to the PCI endpoint controller based on the device name of + the controller. + +*) pci_epc_put() + + Release the reference to the PCI endpoint controller obtained using + pci_epc_get() + +*) 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() + + Remove the PCI endpoint function from PCI endpoint controller. + +*) 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() + + The PCI endpoint function driver should invoke pci_epc_stop() to stop + the PCI LINK. + +2.2 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 + +This section lists the APIs that the PCI Endpoint core provides to be used +by the PCI endpoint function 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 + * unbind: ops to perform when a binding has been lost between a EPC + device and EPF device + * linkup: ops to perform when the EPC device has established a + connection with a host system + + The PCI Function driver can then register the PCI EPF driver by using + pci_epf_register_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() + + The PCI Function driver can allocate space for a particular BAR using + pci_epf_alloc_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 +This section lists the APIs that the PCI Endpoint core provides to be used +by the PCI endpoint controller library. + +*) 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 +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() + + 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() + + Destroy the created PCI EPF device. + +*) 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() 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.txt new file mode 100644 index 000000000000..0c519c9bf94a --- /dev/null +++ b/Documentation/PCI/endpoint/pci-test-function.txt @@ -0,0 +1,66 @@ + PCI TEST + 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. +However with the addition of EP-core in linux kernel, it is possible +to configure a PCI controller that can operate in EP mode to work as +a test device. + +The PCI endpoint test device is a virtual device (defined in software) +used to test the endpoint functionality and serve as a sample driver +for other PCI endpoint devices (to use the EP framework). + +The PCI endpoint test device has the following registers: + + 1) PCI_ENDPOINT_TEST_MAGIC + 2) PCI_ENDPOINT_TEST_COMMAND + 3) PCI_ENDPOINT_TEST_STATUS + 4) PCI_ENDPOINT_TEST_SRC_ADDR + 5) PCI_ENDPOINT_TEST_DST_ADDR + 6) PCI_ENDPOINT_TEST_SIZE + 7) PCI_ENDPOINT_TEST_CHECKSUM + +*) 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: + +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 - 7 : MSI interrupt number + Bit 8 : read command (read data from RC buffer) + Bit 9 : write command (write data to RC buffer) + Bit 10 : copy command (copy data from one RC buffer to another + RC buffer) + +*) 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 + +This register contains the source address (RC buffer address) for the +COPY/READ command. + +*) PCI_ENDPOINT_TEST_DST_ADDR + +This register contains the destination address (RC buffer address) for +the COPY/WRITE command. diff --git a/Documentation/PCI/endpoint/pci-test-howto.txt b/Documentation/PCI/endpoint/pci-test-howto.txt new file mode 100644 index 000000000000..75f48c3bb191 --- /dev/null +++ b/Documentation/PCI/endpoint/pci-test-howto.txt @@ -0,0 +1,179 @@ + PCI TEST USERGUIDE + 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 + +1.1 Endpoint Controller Devices + +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 + # 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: + + # ls /sys/bus/pci-epf/drivers + pci_epf_test + +If PCI_ENDPOINT_CONFIGFS is enabled + # ls /sys/kernel/config/pci_ep/functions + pci_epf_test + +1.3 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 + + # mount -t configfs none /sys/kernel/config + # cd /sys/kernel/config/pci_ep/ + # mkdir functions/pci_epf_test/func1 + +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. + + # ls functions/pci_epf_test/func1 + baseclass_code interrupt_pin revid subsys_vendor_id + cache_line_size msi_interrupts subclass_code vendorid + deviceid progif_code subsys_id + +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 + + # cat functions/pci_epf_test/func1/vendorid + 0xffff + # cat functions/pci_epf_test/func1/interrupt_pin + 0x0001 + +1.4 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. + + # 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 + +1.5 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. + + # 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 + +In order for the endpoint device to establish a link with the host, the _start_ +field should be populated with '1'. + + # echo 1 > controllers/51000000.pcie_ep/start + +2. RootComplex Device + +2.1 lspci Output + +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 + +pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint +tests. Before pcitest.sh can be used pcitest.c should be compiled using the +following commands. + + cd <kernel-dir> + make headers_install ARCH=arm + arm-linux-gnueabihf-gcc -Iusr/include tools/pci/pcitest.c -o pcitest + cp pcitest <rootfs>/usr/sbin/ + cp tools/pci/pcitest.sh <rootfs> + +2.2.1 pcitest.sh Output + # ./pcitest.sh + BAR tests + + BAR0: OKAY + BAR1: OKAY + BAR2: OKAY + BAR3: OKAY + BAR4: NOT OKAY + BAR5: NOT OKAY + + Interrupt tests + + LEGACY IRQ: NOT OKAY + MSI1: OKAY + MSI2: OKAY + MSI3: OKAY + MSI4: OKAY + MSI5: OKAY + MSI6: OKAY + MSI7: OKAY + MSI8: OKAY + MSI9: OKAY + MSI10: OKAY + MSI11: OKAY + MSI12: OKAY + MSI13: OKAY + MSI14: OKAY + MSI15: OKAY + MSI16: OKAY + MSI17: NOT OKAY + MSI18: NOT OKAY + MSI19: NOT OKAY + MSI20: NOT OKAY + MSI21: NOT OKAY + MSI22: NOT OKAY + MSI23: NOT OKAY + MSI24: NOT OKAY + MSI25: NOT OKAY + MSI26: NOT OKAY + MSI27: NOT OKAY + MSI28: NOT OKAY + MSI29: NOT OKAY + MSI30: NOT OKAY + MSI31: NOT OKAY + MSI32: NOT OKAY + + Read Tests + + READ ( 1 bytes): OKAY + READ ( 1024 bytes): OKAY + READ ( 1025 bytes): OKAY + READ (1024000 bytes): OKAY + READ (1024001 bytes): OKAY + + Write Tests + + WRITE ( 1 bytes): OKAY + WRITE ( 1024 bytes): OKAY + WRITE ( 1025 bytes): OKAY + WRITE (1024000 bytes): OKAY + WRITE (1024001 bytes): OKAY + + Copy Tests + + COPY ( 1 bytes): OKAY + COPY ( 1024 bytes): OKAY + COPY ( 1025 bytes): OKAY + COPY (1024000 bytes): OKAY + COPY (1024001 bytes): OKAY diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.txt index da3b2176d5da..0b6bb3ef449e 100644 --- a/Documentation/PCI/pci-error-recovery.txt +++ b/Documentation/PCI/pci-error-recovery.txt @@ -11,7 +11,7 @@ Many PCI bus controllers are able to detect a variety of hardware PCI errors on the bus, such as parity errors on the data and address -busses, as well as SERR and PERR errors. Some of the more advanced +buses, as well as SERR and PERR errors. Some of the more advanced chipsets are able to deal with these errors; these include PCI-E chipsets, and the PCI-host bridges found on IBM Power4, Power5 and Power6-based pSeries boxes. A typical action taken is to disconnect the affected device, @@ -173,7 +173,7 @@ is STEP 6 (Permanent Failure). >>> 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 +>>> and prints an error to syslog. A reboot is then required to >>> get the device working again. STEP 2: MMIO Enabled @@ -231,14 +231,14 @@ proceeds to STEP 4 (Slot Reset) STEP 3: Link Reset ------------------ The platform resets the link. This is a PCI-Express specific step -and is done whenever a non-fatal error has been detected that can be +and is done whenever a fatal error has been detected that can be "solved" by resetting the link. STEP 4: Slot Reset ------------------ In response to a return value of PCI_ERS_RESULT_NEED_RESET, the -the platform will perform a slot reset on the requesting PCI device(s). +the platform will perform a slot reset on the requesting PCI device(s). The actual steps taken by a platform to perform a slot reset will be platform-dependent. Upon completion of slot reset, the platform will call the device slot_reset() callback. @@ -258,7 +258,7 @@ configuration registers to initialize to their default conditions. For most PCI devices, a soft reset will be sufficient for recovery. Optional fundamental reset is provided to support a limited number -of PCI Express PCI devices for which a soft reset is not sufficient +of PCI Express devices for which a soft reset is not sufficient for recovery. If the platform supports PCI hotplug, then the reset might be @@ -303,7 +303,7 @@ driver performs device init only from PCI function 0: 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. +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: diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.txt index 2d91ae251982..d2a84151e99c 100644 --- a/Documentation/PCI/pci-iov-howto.txt +++ b/Documentation/PCI/pci-iov-howto.txt @@ -68,6 +68,18 @@ To disable SR-IOV capability: 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 Following piece of code illustrates the usage of the SR-IOV API. diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt index 5f62aa4a493b..e851cc5de63f 100644 --- a/Documentation/acpi/aml-debugger.txt +++ b/Documentation/acpi/aml-debugger.txt @@ -15,7 +15,7 @@ kernel. CONFIG_ACPI_DEBUGGER=y CONFIG_ACPI_DEBUGGER_USER=m - The userspace utlities can be built from the kernel source tree using + The userspace utilities can be built from the kernel source tree using the following commands: $ cd tools diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt new file mode 100644 index 000000000000..ac09e3138b79 --- /dev/null +++ b/Documentation/acpi/dsd/graph.txt @@ -0,0 +1,162 @@ +Graphs + + +_DSD +---- + +_DSD (Device Specific Data) [7] is a predefined ACPI device +configuration object that can be used to convey information on +hardware features which are not specifically covered by the ACPI +specification [1][6]. There are two _DSD extensions that are relevant +for graphs: property [4] and hierarchical data extensions [5]. The +property extension provides generic key-value pairs whereas the +hierarchical data extension supports nodes with references to other +nodes, forming a tree. The nodes in the tree may contain properties as +defined by the property extension. The two extensions together provide +a tree-like structure with zero or more properties (key-value pairs) +in each node of the tree. + +The data structure may be accessed at runtime by using the device_* +and fwnode_* functions defined in include/linux/fwnode.h . + +Fwnode represents a generic firmware node object. It is independent on +the firmware type. In ACPI, fwnodes are _DSD hierarchical data +extensions objects. A device's _DSD object is represented by an +fwnode. + +The data structure may be referenced to elsewhere in the ACPI tables +by using a hard reference to the device itself and an index to the +hierarchical data extension array on each depth. + + +Ports and endpoints +------------------- + +The port and endpoint concepts are very similar to those in Devicetree +[3]. A port represents an interface in a device, and an endpoint +represents a connection to that interface. + +All port nodes are located under the device's "_DSD" node in the +hierarchical data extension tree. The property extension related to +each port node must contain the key "port" and an integer value which +is the number of the port. The object it refers to should be called "PRTX", +where "X" is the number of the port. + +Further on, endpoints are located under the individual port nodes. The +first hierarchical data extension package list entry of the endpoint +nodes must begin with "endpoint" and must be followed by the number +of the endpoint. The object it refers to should be called "EPXY", where +"X" is the number of the port and "Y" is the number of the endpoint. + +Each port node contains a property extension key "port", the value of +which is the number of the port node. The each endpoint is similarly numbered +with a property extension key "endpoint". Port numbers must be unique within a +device and endpoint numbers must be unique within a port. + +The endpoint reference uses property extension with "remote-endpoint" property +name followed by a reference in the same package. Such references consist of the +the remote device reference, number of the port in the device and finally the +number of the endpoint in that port. Individual references thus appear as: + + Package() { device, port_number, endpoint_number } + +The references to endpoints must be always done both ways, to the +remote endpoint and back from the referred remote endpoint node. + +A simple example of this is show below: + + Scope (\_SB.PCI0.I2C2) + { + Device (CAM0) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "compatible", Package () { "nokia,smia" } }, + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "port0", "PRT0" }, + } + }) + Name (PRT0, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "port", 0 }, + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "endpoint0", "EP00" }, + } + }) + Name (EP00, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "endpoint", 0 }, + Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, 4, 0 } }, + } + }) + } + } + + Scope (\_SB.PCI0) + { + Device (ISP) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "port4", "PRT4" }, + } + }) + + Name (PRT4, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "port", 4 }, /* CSI-2 port number */ + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "endpoint0", "EP40" }, + } + }) + + Name (EP40, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "endpoint", 0 }, + Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, 0, 0 } }, + } + }) + } + } + +Here, the port 0 of the "CAM0" device is connected to the port 4 of +the "ISP" device and vice versa. + + +References +---------- + +[1] _DSD (Device Specific Data) Implementation Guide. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>, + referenced 2016-10-03. + +[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03. + +[3] Documentation/devicetree/bindings/graph.txt + +[4] Device Properties UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + referenced 2016-10-04. + +[5] Hierarchical Data Extension UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf>, + referenced 2016-10-04. + +[6] Advanced Configuration and Power Interface Specification. + <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>, + referenced 2016-10-04. + +[7] _DSD Device Properties Usage Rules. + Documentation/acpi/DSD-properties-rules.txt diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt index 209a5eba6b87..7bcf9c3d9fbe 100644 --- a/Documentation/acpi/enumeration.txt +++ b/Documentation/acpi/enumeration.txt @@ -367,10 +367,10 @@ resulting child platform device. Device Tree namespace link device ID ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Device Tree protocol uses device indentification based on the "compatible" +The Device Tree protocol uses device identification based on the "compatible" property whose value is a string or an array of strings recognized as device identifiers by drivers and the driver core. The set of all those strings may be -regarded as a device indentification namespace analogous to the ACPI/PNP device +regarded as a device identification namespace analogous to the ACPI/PNP device ID namespace. Consequently, in principle it should not be necessary to allocate a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing identification string in the Device Tree (DT) namespace, especially if that ID @@ -381,7 +381,7 @@ In ACPI, the device identification object called _CID (Compatible ID) is used to list the IDs of devices the given one is compatible with, but those IDs must belong to one of the namespaces prescribed by the ACPI specification (see Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them. -Moreover, the specification mandates that either a _HID or an _ADR identificaion +Moreover, the specification mandates that either a _HID or an _ADR identification object be present for all ACPI objects representing devices (Section 6.1 of ACPI 6.0). For non-enumerable bus types that object must be _HID and its value must be a device ID from one of the namespaces prescribed by the specification too. diff --git a/Documentation/acpi/linuxized-acpica.txt b/Documentation/acpi/linuxized-acpica.txt index defe2eec5331..3ad7b0dfb083 100644 --- a/Documentation/acpi/linuxized-acpica.txt +++ b/Documentation/acpi/linuxized-acpica.txt @@ -24,7 +24,7 @@ upstream. The homepage of ACPICA project is: www.acpica.org, it is maintained and supported by Intel Corporation. - The following figure depicts the Linux ACPI subystem where the ACPICA + The following figure depicts the Linux ACPI subsystem where the ACPICA adaptation is included: +---------------------------------------------------------+ @@ -110,7 +110,7 @@ upstream. Linux patches. The patches generated by this process are referred to as "linuxized ACPICA patches". The release process is carried out on a local copy the ACPICA git repository. Each commit in the monthly release is - converted into a linuxized ACPICA patch. Together, they form the montly + converted into a linuxized ACPICA patch. Together, they form the monthly ACPICA release patchset for the Linux ACPI community. This process is illustrated in the following figure: @@ -165,7 +165,7 @@ upstream. <http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>. Before the linuxized ACPICA patches are sent to the Linux ACPI community - for review, there is a quality ensurance build test process to reduce + for review, there is a quality assurance build test process to reduce porting issues. Currently this build process only takes care of the following kernel configuration options: CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER @@ -195,12 +195,12 @@ upstream. release utilities (please refer to Section 4 below for the details). 3. Linux specific features - Sometimes it's impossible to use the current ACPICA APIs to implement features required by the Linux kernel, - so Linux developers occasionaly have to change ACPICA code directly. + so Linux developers occasionally have to change ACPICA code directly. Those changes may not be acceptable by ACPICA upstream and in such cases they are left as committed ACPICA divergences unless the ACPICA side can implement new mechanisms as replacements for them. 4. ACPICA release fixups - ACPICA only tests commits using a set of the - user space simulation utilies, thus the linuxized ACPICA patches may + user space simulation utilities, thus the linuxized ACPICA patches may break the Linux kernel, leaving us build/boot failures. In order to avoid breaking Linux bisection, fixes are applied directly to the linuxized ACPICA patches during the release process. When the release diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 697a00ccec25..02f639aab06e 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -27,7 +27,7 @@ On what hardware does it run? today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS, - Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures. + Xtensa, Tilera TILE, ARC and Renesas M32R architectures. Linux is easily portable to most general-purpose 32- or 64-bit architectures as long as they have a paged memory management unit (PMMU) and a port of the diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 8ddae4e4299a..8c60a8a32a1a 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -60,6 +60,7 @@ configure specific aspects of kernel behavior to your liking. mono java ras + pm/index .. only:: subproject and html diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index b516164999a8..d76ab3907e2b 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -1,3 +1,5 @@ +.. _kernelparameters: + The kernel's command-line parameters ==================================== @@ -86,7 +88,6 @@ parameter is applicable:: APIC APIC support is enabled. APM Advanced Power Management support is enabled. ARM ARM architecture is enabled. - AVR32 AVR32 architecture is enabled. AX25 Appropriate AX.25 support is enabled. BLACKFIN Blackfin architecture is enabled. CLK Common clock infrastructure is enabled. @@ -197,7 +198,7 @@ and is between 256 and 4096 characters. It is defined in the file Finally, the [KMG] suffix is commonly described after a number of kernel parameter values. These 'K', 'M', and 'G' letters represent the _binary_ -multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 +multipliers 'Kilo', 'Mega', and 'Giga', equaling 2^10, 2^20, and 2^30 bytes respectively. Such letter suffixes can also be entirely omitted: .. include:: kernel-parameters.txt diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 2ba45caabada..e4c9e0e46b95 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -531,7 +531,6 @@ [ACPI] acpi_pm [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, pxa_timer,timer3,32k_counter,timer0_1 - [AVR32] avr32 [X86-32] pit,hpet,tsc; scx200_hrt on Geode; cyclone on IBM x440 [MIPS] MIPS @@ -989,6 +988,7 @@ earlyprintk=ttySn[,baudrate] earlyprintk=dbgp[debugController#] earlyprintk=pciserial,bus:device.function[,baudrate] + earlyprintk=xdbc[xhciController#] earlyprintk is useful when the kernel crashes before the normal console is initialized. It is not enabled by @@ -1725,6 +1725,12 @@ kernel and module base offset ASLR (Address Space Layout Randomization). + kasan_multi_shot + [KNL] Enforce KASAN (Kernel Address Sanitizer) to print + report on every invalid memory access. Without this + parameter KASAN will print report only for the first + invalid access. + keepinitrd [HW,ARM] kernelcore= [KNL,X86,IA-64,PPC] @@ -2419,7 +2425,7 @@ osd-targets. Please see: Documentation/filesystems/pnfs.txt for more explanations - nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take + nmi_debug= [KNL,SH] Specify one or more actions to take when a NMI is triggered. Format: [state][,regs][,debounce][,die] @@ -3172,6 +3178,12 @@ ramdisk_size= [RAM] Sizes of RAM disks in kilobytes See Documentation/blockdev/ramdisk.txt. + ras=option[,option,...] [KNL] RAS-specific options + + cec_disable [X86] + Disable the Correctable Errors Collector, + see CONFIG_RAS_CEC help text. + rcu_nocbs= [KNL] The argument is a cpu list, as described above. @@ -4115,6 +4127,9 @@ usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. + usbhid.jspoll= + [USBHID] The interval which joysticks are to be polled at. + usb-storage.delay_use= [UMS] The delay in seconds before a new device is scanned for Logical Units (default 1). diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index 1e61bf50595c..84de718f24a4 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -276,14 +276,14 @@ All md devices contain: array creation it will default to 0, though starting the array as ``clean`` will set it much larger. - new_dev + new_dev This file can be written but not read. The value written should be a block device number as major:minor. e.g. 8:0 This will cause that device to be attached to the array, if it is available. It will then appear at md/dev-XXX (depending on the name of the device) and further configuration is then possible. - safe_mode_delay + safe_mode_delay When an md array has seen no write requests for a certain period of time, it will be marked as ``clean``. When another write request arrives, the array is marked as ``dirty`` before the write @@ -292,7 +292,7 @@ All md devices contain: period as a number of seconds. The default is 200msec (0.200). Writing a value of 0 disables safemode. - array_state + array_state This file contains a single word which describes the current state of the array. In many cases, the state can be set by writing the word for the desired state, however some states @@ -401,7 +401,30 @@ All md devices contain: once the array becomes non-degraded, and this fact has been recorded in the metadata. + consistency_policy + This indicates how the array maintains consistency in case of unexpected + shutdown. It can be: + none + Array has no redundancy information, e.g. raid0, linear. + + resync + Full resync is performed and all redundancy is regenerated when the + array is started after unclean shutdown. + + bitmap + Resync assisted by a write-intent bitmap. + + journal + For raid4/5/6, journal device is used to log transactions and replay + after unclean shutdown. + + ppl + For raid5 only, Partial Parity Log is used to close the write hole and + eliminate resync. + + The accepted values when writing to this file are ``ppl`` and ``resync``, + used to enable and disable PPL. As component devices are added to an md array, they appear in the ``md`` @@ -563,6 +586,9 @@ Each directory contains: adds bad blocks without acknowledging them. This is largely for testing. + ppl_sector, ppl_size + Location and size (in sectors) of the space used for Partial Parity Log + on this device. An active md device will also contain an entry for each active device diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst new file mode 100644 index 000000000000..289c80f7760e --- /dev/null +++ b/Documentation/admin-guide/pm/cpufreq.rst @@ -0,0 +1,700 @@ +.. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>` + +======================= +CPU Performance Scaling +======================= + +:: + + Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> + +The Concept of CPU Performance Scaling +====================================== + +The majority of modern processors are capable of operating in a number of +different clock frequency and voltage configurations, often referred to as +Operating Performance Points or P-states (in ACPI terminology). As a rule, +the higher the clock frequency and the higher the voltage, the more instructions +can be retired by the CPU over a unit of time, but also the higher the clock +frequency and the higher the voltage, the more energy is consumed over a unit of +time (or the more power is drawn) by the CPU in the given P-state. Therefore +there is a natural tradeoff between the CPU capacity (the number of instructions +that can be executed over a unit of time) and the power drawn by the CPU. + +In some situations it is desirable or even necessary to run the program as fast +as possible and then there is no reason to use any P-states different from the +highest one (i.e. the highest-performance frequency/voltage configuration +available). In some other cases, however, it may not be necessary to execute +instructions so quickly and maintaining the highest available CPU capacity for a +relatively long time without utilizing it entirely may be regarded as wasteful. +It also may not be physically possible to maintain maximum CPU capacity for too +long for thermal or power supply capacity reasons or similar. To cover those +cases, there are hardware interfaces allowing CPUs to be switched between +different frequency/voltage configurations or (in the ACPI terminology) to be +put into different P-states. + +Typically, they are used along with algorithms to estimate the required CPU +capacity, so as to decide which P-states to put the CPUs into. Of course, since +the utilization of the system generally changes over time, that has to be done +repeatedly on a regular basis. The activity by which this happens is referred +to as CPU performance scaling or CPU frequency scaling (because it involves +adjusting the CPU clock frequency). + + +CPU Performance Scaling in Linux +================================ + +The Linux kernel supports CPU performance scaling by means of the ``CPUFreq`` +(CPU Frequency scaling) subsystem that consists of three layers of code: the +core, scaling governors and scaling drivers. + +The ``CPUFreq`` core provides the common code infrastructure and user space +interfaces for all platforms that support CPU performance scaling. It defines +the basic framework in which the other components operate. + +Scaling governors implement algorithms to estimate the required CPU capacity. +As a rule, each governor implements one, possibly parametrized, scaling +algorithm. + +Scaling drivers talk to the hardware. They provide scaling governors with +information on the available P-states (or P-state ranges in some cases) and +access platform-specific hardware interfaces to change CPU P-states as requested +by scaling governors. + +In principle, all available scaling governors can be used with every scaling +driver. That design is based on the observation that the information used by +performance scaling algorithms for P-state selection can be represented in a +platform-independent form in the majority of cases, so it should be possible +to use the same performance scaling algorithm implemented in exactly the same +way regardless of which scaling driver is used. Consequently, the same set of +scaling governors should be suitable for every supported platform. + +However, that observation may not hold for performance scaling algorithms +based on information provided by the hardware itself, for example through +feedback registers, as that information is typically specific to the hardware +interface it comes from and may not be easily represented in an abstract, +platform-independent way. For this reason, ``CPUFreq`` allows scaling drivers +to bypass the governor layer and implement their own performance scaling +algorithms. That is done by the ``intel_pstate`` scaling driver. + + +``CPUFreq`` Policy Objects +========================== + +In some cases the hardware interface for P-state control is shared by multiple +CPUs. That is, for example, the same register (or set of registers) is used to +control the P-state of multiple CPUs at the same time and writing to it affects +all of those CPUs simultaneously. + +Sets of CPUs sharing hardware P-state control interfaces are represented by +``CPUFreq`` as |struct cpufreq_policy| objects. For consistency, +|struct cpufreq_policy| is also used when there is only one CPU in the given +set. + +The ``CPUFreq`` core maintains a pointer to a |struct cpufreq_policy| object for +every CPU in the system, including CPUs that are currently offline. If multiple +CPUs share the same hardware P-state control interface, all of the pointers +corresponding to them point to the same |struct cpufreq_policy| object. + +``CPUFreq`` uses |struct cpufreq_policy| as its basic data type and the design +of its user space interface is based on the policy concept. + + +CPU Initialization +================== + +First of all, a scaling driver has to be registered for ``CPUFreq`` to work. +It is only possible to register one scaling driver at a time, so the scaling +driver is expected to be able to handle all CPUs in the system. + +The scaling driver may be registered before or after CPU registration. If +CPUs are registered earlier, the driver core invokes the ``CPUFreq`` core to +take a note of all of the already registered CPUs during the registration of the +scaling driver. In turn, if any CPUs are registered after the registration of +the scaling driver, the ``CPUFreq`` core will be invoked to take note of them +at their registration time. + +In any case, the ``CPUFreq`` core is invoked to take note of any logical CPU it +has not seen so far as soon as it is ready to handle that CPU. [Note that the +logical CPU may be a physical single-core processor, or a single core in a +multicore processor, or a hardware thread in a physical processor or processor +core. In what follows "CPU" always means "logical CPU" unless explicitly stated +otherwise and the word "processor" is used to refer to the physical part +possibly including multiple logical CPUs.] + +Once invoked, the ``CPUFreq`` core checks if the policy pointer is already set +for the given CPU and if so, it skips the policy object creation. Otherwise, +a new policy object is created and initialized, which involves the creation of +a new policy directory in ``sysfs``, and the policy pointer corresponding to +the given CPU is set to the new policy object's address in memory. + +Next, the scaling driver's ``->init()`` callback is invoked with the policy +pointer of the new CPU passed to it as the argument. That callback is expected +to initialize the performance scaling hardware interface for the given CPU (or, +more precisely, for the set of CPUs sharing the hardware interface it belongs +to, represented by its policy object) and, if the policy object it has been +called for is new, to set parameters of the policy, like the minimum and maximum +frequencies supported by the hardware, the table of available frequencies (if +the set of supported P-states is not a continuous range), and the mask of CPUs +that belong to the same policy (including both online and offline CPUs). That +mask is then used by the core to populate the policy pointers for all of the +CPUs in it. + +The next major initialization step for a new policy object is to attach a +scaling governor to it (to begin with, that is the default scaling governor +determined by the kernel configuration, but it may be changed later +via ``sysfs``). First, a pointer to the new policy object is passed to the +governor's ``->init()`` callback which is expected to initialize all of the +data structures necessary to handle the given policy and, possibly, to add +a governor ``sysfs`` interface to it. Next, the governor is started by +invoking its ``->start()`` callback. + +That callback it expected to register per-CPU utilization update callbacks for +all of the online CPUs belonging to the given policy with the CPU scheduler. +The utilization update callbacks will be invoked by the CPU scheduler on +important events, like task enqueue and dequeue, on every iteration of the +scheduler tick or generally whenever the CPU utilization may change (from the +scheduler's perspective). They are expected to carry out computations needed +to determine the P-state to use for the given policy going forward and to +invoke the scaling driver to make changes to the hardware in accordance with +the P-state selection. The scaling driver may be invoked directly from +scheduler context or asynchronously, via a kernel thread or workqueue, depending +on the configuration and capabilities of the scaling driver and the governor. + +Similar steps are taken for policy objects that are not new, but were "inactive" +previously, meaning that all of the CPUs belonging to them were offline. The +only practical difference in that case is that the ``CPUFreq`` core will attempt +to use the scaling governor previously used with the policy that became +"inactive" (and is re-initialized now) instead of the default governor. + +In turn, if a previously offline CPU is being brought back online, but some +other CPUs sharing the policy object with it are online already, there is no +need to re-initialize the policy object at all. In that case, it only is +necessary to restart the scaling governor so that it can take the new online CPU +into account. That is achieved by invoking the governor's ``->stop`` and +``->start()`` callbacks, in this order, for the entire policy. + +As mentioned before, the ``intel_pstate`` scaling driver bypasses the scaling +governor layer of ``CPUFreq`` and provides its own P-state selection algorithms. +Consequently, if ``intel_pstate`` is used, scaling governors are not attached to +new policy objects. Instead, the driver's ``->setpolicy()`` callback is invoked +to register per-CPU utilization update callbacks for each policy. These +callbacks are invoked by the CPU scheduler in the same way as for scaling +governors, but in the ``intel_pstate`` case they both determine the P-state to +use and change the hardware configuration accordingly in one go from scheduler +context. + +The policy objects created during CPU initialization and other data structures +associated with them are torn down when the scaling driver is unregistered +(which happens when the kernel module containing it is unloaded, for example) or +when the last CPU belonging to the given policy in unregistered. + + +Policy Interface in ``sysfs`` +============================= + +During the initialization of the kernel, the ``CPUFreq`` core creates a +``sysfs`` directory (kobject) called ``cpufreq`` under +:file:`/sys/devices/system/cpu/`. + +That directory contains a ``policyX`` subdirectory (where ``X`` represents an +integer number) for every policy object maintained by the ``CPUFreq`` core. +Each ``policyX`` directory is pointed to by ``cpufreq`` symbolic links +under :file:`/sys/devices/system/cpu/cpuY/` (where ``Y`` represents an integer +that may be different from the one represented by ``X``) for all of the CPUs +associated with (or belonging to) the given policy. The ``policyX`` directories +in :file:`/sys/devices/system/cpu/cpufreq` each contain policy-specific +attributes (files) to control ``CPUFreq`` behavior for the corresponding policy +objects (that is, for all of the CPUs associated with them). + +Some of those attributes are generic. They are created by the ``CPUFreq`` core +and their behavior generally does not depend on what scaling driver is in use +and what scaling governor is attached to the given policy. Some scaling drivers +also add driver-specific attributes to the policy directories in ``sysfs`` to +control policy-specific aspects of driver behavior. + +The generic attributes under :file:`/sys/devices/system/cpu/cpufreq/policyX/` +are the following: + +``affected_cpus`` + List of online CPUs belonging to this policy (i.e. sharing the hardware + performance scaling interface represented by the ``policyX`` policy + object). + +``bios_limit`` + If the platform firmware (BIOS) tells the OS to apply an upper limit to + CPU frequencies, that limit will be reported through this attribute (if + present). + + The existence of the limit may be a result of some (often unintentional) + BIOS settings, restrictions coming from a service processor or another + BIOS/HW-based mechanisms. + + This does not cover ACPI thermal limitations which can be discovered + through a generic thermal driver. + + This attribute is not present if the scaling driver in use does not + support it. + +``cpuinfo_max_freq`` + Maximum possible operating frequency the CPUs belonging to this policy + can run at (in kHz). + +``cpuinfo_min_freq`` + Minimum possible operating frequency the CPUs belonging to this policy + can run at (in kHz). + +``cpuinfo_transition_latency`` + The time it takes to switch the CPUs belonging to this policy from one + P-state to another, in nanoseconds. + + If unknown or if known to be so high that the scaling driver does not + work with the `ondemand`_ governor, -1 (:c:macro:`CPUFREQ_ETERNAL`) + will be returned by reads from this attribute. + +``related_cpus`` + List of all (online and offline) CPUs belonging to this policy. + +``scaling_available_governors`` + List of ``CPUFreq`` scaling governors present in the kernel that can + be attached to this policy or (if the ``intel_pstate`` scaling driver is + in use) list of scaling algorithms provided by the driver that can be + applied to this policy. + + [Note that some governors are modular and it may be necessary to load a + kernel module for the governor held by it to become available and be + listed by this attribute.] + +``scaling_cur_freq`` + Current frequency of all of the CPUs belonging to this policy (in kHz). + + For the majority of scaling drivers, this is the frequency of the last + P-state requested by the driver from the hardware using the scaling + interface provided by it, which may or may not reflect the frequency + the CPU is actually running at (due to hardware design and other + limitations). + + Some scaling drivers (e.g. ``intel_pstate``) attempt to provide + information more precisely reflecting the current CPU frequency through + this attribute, but that still may not be the exact current CPU + frequency as seen by the hardware at the moment. + +``scaling_driver`` + The scaling driver currently in use. + +``scaling_governor`` + The scaling governor currently attached to this policy or (if the + ``intel_pstate`` scaling driver is in use) the scaling algorithm + provided by the driver that is currently applied to this policy. + + This attribute is read-write and writing to it will cause a new scaling + governor to be attached to this policy or a new scaling algorithm + provided by the scaling driver to be applied to it (in the + ``intel_pstate`` case), as indicated by the string written to this + attribute (which must be one of the names listed by the + ``scaling_available_governors`` attribute described above). + +``scaling_max_freq`` + Maximum frequency the CPUs belonging to this policy are allowed to be + running at (in kHz). + + This attribute is read-write and writing a string representing an + integer to it will cause a new limit to be set (it must not be lower + than the value of the ``scaling_min_freq`` attribute). + +``scaling_min_freq`` + Minimum frequency the CPUs belonging to this policy are allowed to be + running at (in kHz). + + This attribute is read-write and writing a string representing a + non-negative integer to it will cause a new limit to be set (it must not + be higher than the value of the ``scaling_max_freq`` attribute). + +``scaling_setspeed`` + This attribute is functional only if the `userspace`_ scaling governor + is attached to the given policy. + + It returns the last frequency requested by the governor (in kHz) or can + be written to in order to set a new frequency for the policy. + + +Generic Scaling Governors +========================= + +``CPUFreq`` provides generic scaling governors that can be used with all +scaling drivers. As stated before, each of them implements a single, possibly +parametrized, performance scaling algorithm. + +Scaling governors are attached to policy objects and different policy objects +can be handled by different scaling governors at the same time (although that +may lead to suboptimal results in some cases). + +The scaling governor for a given policy object can be changed at any time with +the help of the ``scaling_governor`` policy attribute in ``sysfs``. + +Some governors expose ``sysfs`` attributes to control or fine-tune the scaling +algorithms implemented by them. Those attributes, referred to as governor +tunables, can be either global (system-wide) or per-policy, depending on the +scaling driver in use. If the driver requires governor tunables to be +per-policy, they are located in a subdirectory of each policy directory. +Otherwise, they are located in a subdirectory under +:file:`/sys/devices/system/cpu/cpufreq/`. In either case the name of the +subdirectory containing the governor tunables is the name of the governor +providing them. + +``performance`` +--------------- + +When attached to a policy object, this governor causes the highest frequency, +within the ``scaling_max_freq`` policy limit, to be requested for that policy. + +The request is made once at that time the governor for the policy is set to +``performance`` and whenever the ``scaling_max_freq`` or ``scaling_min_freq`` +policy limits change after that. + +``powersave`` +------------- + +When attached to a policy object, this governor causes the lowest frequency, +within the ``scaling_min_freq`` policy limit, to be requested for that policy. + +The request is made once at that time the governor for the policy is set to +``powersave`` and whenever the ``scaling_max_freq`` or ``scaling_min_freq`` +policy limits change after that. + +``userspace`` +------------- + +This governor does not do anything by itself. Instead, it allows user space +to set the CPU frequency for the policy it is attached to by writing to the +``scaling_setspeed`` attribute of that policy. + +``schedutil`` +------------- + +This governor uses CPU utilization data available from the CPU scheduler. It +generally is regarded as a part of the CPU scheduler, so it can access the +scheduler's internal data structures directly. + +It runs entirely in scheduler context, although in some cases it may need to +invoke the scaling driver asynchronously when it decides that the CPU frequency +should be changed for a given policy (that depends on whether or not the driver +is capable of changing the CPU frequency from scheduler context). + +The actions of this governor for a particular CPU depend on the scheduling class +invoking its utilization update callback for that CPU. If it is invoked by the +RT or deadline scheduling classes, the governor will increase the frequency to +the allowed maximum (that is, the ``scaling_max_freq`` policy limit). In turn, +if it is invoked by the CFS scheduling class, the governor will use the +Per-Entity Load Tracking (PELT) metric for the root control group of the +given CPU as the CPU utilization estimate (see the `Per-entity load tracking`_ +LWN.net article for a description of the PELT mechanism). Then, the new +CPU frequency to apply is computed in accordance with the formula + + f = 1.25 * ``f_0`` * ``util`` / ``max`` + +where ``util`` is the PELT number, ``max`` is the theoretical maximum of +``util``, and ``f_0`` is either the maximum possible CPU frequency for the given +policy (if the PELT number is frequency-invariant), or the current CPU frequency +(otherwise). + +This governor also employs a mechanism allowing it to temporarily bump up the +CPU frequency for tasks that have been waiting on I/O most recently, called +"IO-wait boosting". That happens when the :c:macro:`SCHED_CPUFREQ_IOWAIT` flag +is passed by the scheduler to the governor callback which causes the frequency +to go up to the allowed maximum immediately and then draw back to the value +returned by the above formula over time. + +This governor exposes only one tunable: + +``rate_limit_us`` + Minimum time (in microseconds) that has to pass between two consecutive + runs of governor computations (default: 1000 times the scaling driver's + transition latency). + + The purpose of this tunable is to reduce the scheduler context overhead + of the governor which might be excessive without it. + +This governor generally is regarded as a replacement for the older `ondemand`_ +and `conservative`_ governors (described below), as it is simpler and more +tightly integrated with the CPU scheduler, its overhead in terms of CPU context +switches and similar is less significant, and it uses the scheduler's own CPU +utilization metric, so in principle its decisions should not contradict the +decisions made by the other parts of the scheduler. + +``ondemand`` +------------ + +This governor uses CPU load as a CPU frequency selection metric. + +In order to estimate the current CPU load, it measures the time elapsed between +consecutive invocations of its worker routine and computes the fraction of that +time in which the given CPU was not idle. The ratio of the non-idle (active) +time to the total CPU time is taken as an estimate of the load. + +If this governor is attached to a policy shared by multiple CPUs, the load is +estimated for all of them and the greatest result is taken as the load estimate +for the entire policy. + +The worker routine of this governor has to run in process context, so it is +invoked asynchronously (via a workqueue) and CPU P-states are updated from +there if necessary. As a result, the scheduler context overhead from this +governor is minimum, but it causes additional CPU context switches to happen +relatively often and the CPU P-state updates triggered by it can be relatively +irregular. Also, it affects its own CPU load metric by running code that +reduces the CPU idle time (even though the CPU idle time is only reduced very +slightly by it). + +It generally selects CPU frequencies proportional to the estimated load, so that +the value of the ``cpuinfo_max_freq`` policy attribute corresponds to the load of +1 (or 100%), and the value of the ``cpuinfo_min_freq`` policy attribute +corresponds to the load of 0, unless when the load exceeds a (configurable) +speedup threshold, in which case it will go straight for the highest frequency +it is allowed to use (the ``scaling_max_freq`` policy limit). + +This governor exposes the following tunables: + +``sampling_rate`` + This is how often the governor's worker routine should run, in + microseconds. + + Typically, it is set to values of the order of 10000 (10 ms). Its + default value is equal to the value of ``cpuinfo_transition_latency`` + for each policy this governor is attached to (but since the unit here + is greater by 1000, this means that the time represented by + ``sampling_rate`` is 1000 times greater than the transition latency by + default). + + If this tunable is per-policy, the following shell command sets the time + represented by it to be 750 times as high as the transition latency:: + + # echo `$(($(cat cpuinfo_transition_latency) * 750 / 1000)) > ondemand/sampling_rate + + +``min_sampling_rate`` + The minimum value of ``sampling_rate``. + + Equal to 10000 (10 ms) if :c:macro:`CONFIG_NO_HZ_COMMON` and + :c:data:`tick_nohz_active` are both set or to 20 times the value of + :c:data:`jiffies` in microseconds otherwise. + +``up_threshold`` + If the estimated CPU load is above this value (in percent), the governor + will set the frequency to the maximum value allowed for the policy. + Otherwise, the selected frequency will be proportional to the estimated + CPU load. + +``ignore_nice_load`` + If set to 1 (default 0), it will cause the CPU load estimation code to + treat the CPU time spent on executing tasks with "nice" levels greater + than 0 as CPU idle time. + + This may be useful if there are tasks in the system that should not be + taken into account when deciding what frequency to run the CPUs at. + Then, to make that happen it is sufficient to increase the "nice" level + of those tasks above 0 and set this attribute to 1. + +``sampling_down_factor`` + Temporary multiplier, between 1 (default) and 100 inclusive, to apply to + the ``sampling_rate`` value if the CPU load goes above ``up_threshold``. + + This causes the next execution of the governor's worker routine (after + setting the frequency to the allowed maximum) to be delayed, so the + frequency stays at the maximum level for a longer time. + + Frequency fluctuations in some bursty workloads may be avoided this way + at the cost of additional energy spent on maintaining the maximum CPU + capacity. + +``powersave_bias`` + Reduction factor to apply to the original frequency target of the + governor (including the maximum value used when the ``up_threshold`` + value is exceeded by the estimated CPU load) or sensitivity threshold + for the AMD frequency sensitivity powersave bias driver + (:file:`drivers/cpufreq/amd_freq_sensitivity.c`), between 0 and 1000 + inclusive. + + If the AMD frequency sensitivity powersave bias driver is not loaded, + the effective frequency to apply is given by + + f * (1 - ``powersave_bias`` / 1000) + + where f is the governor's original frequency target. The default value + of this attribute is 0 in that case. + + If the AMD frequency sensitivity powersave bias driver is loaded, the + value of this attribute is 400 by default and it is used in a different + way. + + On Family 16h (and later) AMD processors there is a mechanism to get a + measured workload sensitivity, between 0 and 100% inclusive, from the + hardware. That value can be used to estimate how the performance of the + workload running on a CPU will change in response to frequency changes. + + The performance of a workload with the sensitivity of 0 (memory-bound or + IO-bound) is not expected to increase at all as a result of increasing + the CPU frequency, whereas workloads with the sensitivity of 100% + (CPU-bound) are expected to perform much better if the CPU frequency is + increased. + + If the workload sensitivity is less than the threshold represented by + the ``powersave_bias`` value, the sensitivity powersave bias driver + will cause the governor to select a frequency lower than its original + target, so as to avoid over-provisioning workloads that will not benefit + from running at higher CPU frequencies. + +``conservative`` +---------------- + +This governor uses CPU load as a CPU frequency selection metric. + +It estimates the CPU load in the same way as the `ondemand`_ governor described +above, but the CPU frequency selection algorithm implemented by it is different. + +Namely, it avoids changing the frequency significantly over short time intervals +which may not be suitable for systems with limited power supply capacity (e.g. +battery-powered). To achieve that, it changes the frequency in relatively +small steps, one step at a time, up or down - depending on whether or not a +(configurable) threshold has been exceeded by the estimated CPU load. + +This governor exposes the following tunables: + +``freq_step`` + Frequency step in percent of the maximum frequency the governor is + allowed to set (the ``scaling_max_freq`` policy limit), between 0 and + 100 (5 by default). + + This is how much the frequency is allowed to change in one go. Setting + it to 0 will cause the default frequency step (5 percent) to be used + and setting it to 100 effectively causes the governor to periodically + switch the frequency between the ``scaling_min_freq`` and + ``scaling_max_freq`` policy limits. + +``down_threshold`` + Threshold value (in percent, 20 by default) used to determine the + frequency change direction. + + If the estimated CPU load is greater than this value, the frequency will + go up (by ``freq_step``). If the load is less than this value (and the + ``sampling_down_factor`` mechanism is not in effect), the frequency will + go down. Otherwise, the frequency will not be changed. + +``sampling_down_factor`` + Frequency decrease deferral factor, between 1 (default) and 10 + inclusive. + + It effectively causes the frequency to go down ``sampling_down_factor`` + times slower than it ramps up. + + +Frequency Boost Support +======================= + +Background +---------- + +Some processors support a mechanism to raise the operating frequency of some +cores in a multicore package temporarily (and above the sustainable frequency +threshold for the whole package) under certain conditions, for example if the +whole chip is not fully utilized and below its intended thermal or power budget. + +Different names are used by different vendors to refer to this functionality. +For Intel processors it is referred to as "Turbo Boost", AMD calls it +"Turbo-Core" or (in technical documentation) "Core Performance Boost" and so on. +As a rule, it also is implemented differently by different vendors. The simple +term "frequency boost" is used here for brevity to refer to all of those +implementations. + +The frequency boost mechanism may be either hardware-based or software-based. +If it is hardware-based (e.g. on x86), the decision to trigger the boosting is +made by the hardware (although in general it requires the hardware to be put +into a special state in which it can control the CPU frequency within certain +limits). If it is software-based (e.g. on ARM), the scaling driver decides +whether or not to trigger boosting and when to do that. + +The ``boost`` File in ``sysfs`` +------------------------------- + +This file is located under :file:`/sys/devices/system/cpu/cpufreq/` and controls +the "boost" setting for the whole system. It is not present if the underlying +scaling driver does not support the frequency boost mechanism (or supports it, +but provides a driver-specific interface for controlling it, like +``intel_pstate``). + +If the value in this file is 1, the frequency boost mechanism is enabled. This +means that either the hardware can be put into states in which it is able to +trigger boosting (in the hardware-based case), or the software is allowed to +trigger boosting (in the software-based case). It does not mean that boosting +is actually in use at the moment on any CPUs in the system. It only means a +permission to use the frequency boost mechanism (which still may never be used +for other reasons). + +If the value in this file is 0, the frequency boost mechanism is disabled and +cannot be used at all. + +The only values that can be written to this file are 0 and 1. + +Rationale for Boost Control Knob +-------------------------------- + +The frequency boost mechanism is generally intended to help to achieve optimum +CPU performance on time scales below software resolution (e.g. below the +scheduler tick interval) and it is demonstrably suitable for many workloads, but +it may lead to problems in certain situations. + +For this reason, many systems make it possible to disable the frequency boost +mechanism in the platform firmware (BIOS) setup, but that requires the system to +be restarted for the setting to be adjusted as desired, which may not be +practical at least in some cases. For example: + + 1. Boosting means overclocking the processor, although under controlled + conditions. Generally, the processor's energy consumption increases + as a result of increasing its frequency and voltage, even temporarily. + That may not be desirable on systems that switch to power sources of + limited capacity, such as batteries, so the ability to disable the boost + mechanism while the system is running may help there (but that depends on + the workload too). + + 2. In some situations deterministic behavior is more important than + performance or energy consumption (or both) and the ability to disable + boosting while the system is running may be useful then. + + 3. To examine the impact of the frequency boost mechanism itself, it is useful + to be able to run tests with and without boosting, preferably without + restarting the system in the meantime. + + 4. Reproducible results are important when running benchmarks. Since + the boosting functionality depends on the load of the whole package, + single-thread performance may vary because of it which may lead to + unreproducible results sometimes. That can be avoided by disabling the + frequency boost mechanism before running benchmarks sensitive to that + issue. + +Legacy AMD ``cpb`` Knob +----------------------- + +The AMD powernow-k8 scaling driver supports a ``sysfs`` knob very similar to +the global ``boost`` one. It is used for disabling/enabling the "Core +Performance Boost" feature of some AMD processors. + +If present, that knob is located in every ``CPUFreq`` policy directory in +``sysfs`` (:file:`/sys/devices/system/cpu/cpufreq/policyX/`) and is called +``cpb``, which indicates a more fine grained control interface. The actual +implementation, however, works on the system-wide basis and setting that knob +for one policy causes the same value of it to be set for all of the other +policies at the same time. + +That knob is still supported on AMD processors that support its underlying +hardware feature, but it may be configured out of the kernel (via the +:c:macro:`CONFIG_X86_ACPI_CPUFREQ_CPB` configuration option) and the global +``boost`` knob is present regardless. Thus it is always possible use the +``boost`` knob instead of the ``cpb`` one which is highly recommended, as that +is more consistent with what all of the other systems do (and the ``cpb`` knob +may not be supported any more in the future). + +The ``cpb`` knob is never present for any processors without the underlying +hardware feature (e.g. all Intel ones), even if the +:c:macro:`CONFIG_X86_ACPI_CPUFREQ_CPB` configuration option is set. + + +.. _Per-entity load tracking: https://lwn.net/Articles/531853/ diff --git a/Documentation/admin-guide/pm/index.rst b/Documentation/admin-guide/pm/index.rst new file mode 100644 index 000000000000..c80f087321fc --- /dev/null +++ b/Documentation/admin-guide/pm/index.rst @@ -0,0 +1,15 @@ +================ +Power Management +================ + +.. toctree:: + :maxdepth: 2 + + cpufreq + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/ras.rst index 1b90c6f00a92..8c7bbf2c88d2 100644 --- a/Documentation/admin-guide/ras.rst +++ b/Documentation/admin-guide/ras.rst @@ -8,7 +8,7 @@ RAS concepts ************ Reliability, Availability and Serviceability (RAS) is a concept used on -servers meant to measure their robusteness. +servers meant to measure their robustness. Reliability is the probability that a system will produce correct outputs. @@ -42,13 +42,13 @@ Among the monitoring measures, the most usual ones include: * CPU – detect errors at instruction execution and at L1/L2/L3 caches; * Memory – add error correction logic (ECC) to detect and correct errors; -* I/O – add CRC checksums for tranfered data; +* I/O – add CRC checksums for transferred data; * Storage – RAID, journal file systems, checksums, Self-Monitoring, Analysis and Reporting Technology (SMART). By monitoring the number of occurrences of error detections, it is possible to identify if the probability of hardware errors is increasing, and, on such -case, do a preventive maintainance to replace a degrated component while +case, do a preventive maintenance to replace a degraded component while those errors are correctable. Types of errors @@ -121,7 +121,7 @@ using the ``dmidecode`` tool. For example, on a desktop machine, it shows:: On the above example, a DDR4 SO-DIMM memory module is located at the system's memory labeled as "BANK 0", as given by the *bank locator* field. Please notice that, on such system, the *total width* is equal to the -*data witdh*. It means that such memory module doesn't have error +*data width*. It means that such memory module doesn't have error detection/correction mechanisms. Unfortunately, not all systems use the same field to specify the memory @@ -145,7 +145,7 @@ bank. On this example, from an older server, ``dmidecode`` shows:: There, the DDR3 RDIMM memory module is located at the system's memory labeled as "DIMM_A1", as given by the *locator* field. Please notice that this -memory module has 64 bits of *data witdh* and 72 bits of *total width*. So, +memory module has 64 bits of *data width* and 72 bits of *total width*. So, it has 8 extra bits to be used by error detection and correction mechanisms. Such kind of memory is called Error-correcting code memory (ECC memory). @@ -186,7 +186,7 @@ Architecture (MCA)\ [#f3]_. .. [#f1] Please notice that several memory controllers allow operation on a mode called "Lock-Step", where it groups two memory modules together, doing 128-bit reads/writes. That gives 16 bits for error correction, with - significatively improves the error correction mechanism, at the expense + significantly improves the error correction mechanism, at the expense that, when an error happens, there's no way to know what memory module is to blame. So, it has to blame both memory modules. diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst index 4f7414cad586..47574b382d75 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -14,14 +14,17 @@ Contact The Linux kernel security team can be contacted by email at <security@kernel.org>. This is a private list of security officers who will help verify the bug report and develop and release a fix. -It is possible that the security team will bring in extra help from -area maintainers to understand and fix the security vulnerability. +If you already have a fix, please include it with your report, as +that can speed up the process considerably. It is possible that the +security team will bring in extra help from area maintainers to +understand and fix the security vulnerability. As it is with any bug, the more information provided the easier it will be to diagnose and fix. Please review the procedure outlined in -admin-guide/reporting-bugs.rst if you are unclear about what information is helpful. -Any exploit code is very helpful and will not be released without -consent from the reporter unless it has already been made public. +admin-guide/reporting-bugs.rst if you are unclear about what +information is helpful. Any exploit code is very helpful and will not +be released without consent from the reporter unless it has already been +made public. Disclosure ---------- @@ -39,6 +42,32 @@ disclosure is from immediate (esp. if it's already publicly known) to a few weeks. As a basic default policy, we expect report date to disclosure date to be on the order of 7 days. +Coordination +------------ + +Fixes for sensitive bugs, such as those that might lead to privilege +escalations, may need to be coordinated with the private +<linux-distros@vs.openwall.org> mailing list so that distribution vendors +are well prepared to issue a fixed kernel upon public disclosure of the +upstream fix. Distros will need some time to test the proposed patch and +will generally request at least a few days of embargo, and vendor update +publication prefers to happen Tuesday through Thursday. When appropriate, +the security team can assist with this coordination, or the reporter can +include linux-distros from the start. In this case, remember to prefix +the email Subject line with "[vs]" as described in the linux-distros wiki: +<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists> + +CVE assignment +-------------- + +The security team does not normally assign CVEs, nor do we require them +for reports or fixes, as this can needlessly complicate the process and +may delay the bug handling. If a reporter wishes to have a CVE identifier +assigned ahead of public disclosure, they will need to contact the private +linux-distros list, described above. When such a CVE identifier is known +before a patch is provided, it is desirable to mention it in the commit +message, though. + Non-disclosure agreements ------------------------- diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index d1712ea2d314..7b9035c01a2e 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -212,7 +212,8 @@ I hit SysRq, but nothing seems to happen, what's wrong? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are some keyboards that produce a different keycode for SysRq than the -pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or +pre-defined value of 99 +(see ``KEY_SYSRQ`` in ``include/uapi/linux/input-event-codes.h``), or which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find an appropriate scancode sequence, and use ``setkeycodes <sequence> 99`` to map this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's diff --git a/Documentation/arm/mem_alignment b/Documentation/arm/mem_alignment index c7c7a114c78c..6335fcacbba9 100644 --- a/Documentation/arm/mem_alignment +++ b/Documentation/arm/mem_alignment @@ -48,7 +48,7 @@ Note that not all combinations are supported - only values 0 through 5. For example, the following will turn on the warnings, but without fixing up or sending SIGBUS signals: - echo 1 > /proc/sys/debug/alignment + echo 1 > /proc/cpu/alignment You can also read the content of the same file to get statistical information on unaligned access occurrences plus the current mode of diff --git a/Documentation/arm/stm32/stm32h743-overview.txt b/Documentation/arm/stm32/stm32h743-overview.txt new file mode 100644 index 000000000000..3031cbae31a5 --- /dev/null +++ b/Documentation/arm/stm32/stm32h743-overview.txt @@ -0,0 +1,30 @@ + STM32H743 Overview + ================== + + Introduction + ------------ + The STM32H743 is a Cortex-M7 MCU aimed at various applications. + It features: + - Cortex-M7 core running up to @400MHz + - 2MB internal flash, 1MBytes internal RAM + - FMC controller to connect SDRAM, NOR and NAND memories + - Dual mode QSPI + - SD/MMC/SDIO support + - Ethernet controller + - USB OTFG FS & HS controllers + - I2C, SPI, CAN busses support + - Several 16 & 32 bits general purpose timers + - Serial Audio interface + - LCD controller + - HDMI-CEC + - SPDIFRX + - DFSDM + + Resources + --------- + Datasheet and reference manual are publicly available on ST website: + - http://www.st.com/en/microcontrollers/stm32h7x3.html?querycriteria=productId=LN2033 + + Document Author + --------------- + Alexandre Torgue <alexandre.torgue@st.com> diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.txt index 61ca21ebef1a..d1c97f9f51cc 100644 --- a/Documentation/arm64/cpu-feature-registers.txt +++ b/Documentation/arm64/cpu-feature-registers.txt @@ -169,6 +169,18 @@ infrastructure: as available on the CPU where it is fetched and is not a system wide safe value. + 4) ID_AA64ISAR1_EL1 - Instruction set attribute register 1 + + x--------------------------------------------------x + | Name | bits | visible | + |--------------------------------------------------| + | LRCPC | [23-20] | y | + |--------------------------------------------------| + | FCMA | [19-16] | y | + |--------------------------------------------------| + | JSCVT | [15-12] | y | + x--------------------------------------------------x + Appendix I: Example --------------------------- diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt index 2f66683500b8..10f2dddbf449 100644 --- a/Documentation/arm64/silicon-errata.txt +++ b/Documentation/arm64/silicon-errata.txt @@ -54,6 +54,7 @@ stable kernels. | ARM | Cortex-A57 | #852523 | N/A | | ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | | ARM | Cortex-A72 | #853709 | N/A | +| ARM | Cortex-A73 | #858921 | ARM64_ERRATUM_858921 | | ARM | MMU-500 | #841119,#826419 | N/A | | | | | | | Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | diff --git a/Documentation/block/00-INDEX b/Documentation/block/00-INDEX index e55103ace382..8d55b4bbb5e2 100644 --- a/Documentation/block/00-INDEX +++ b/Documentation/block/00-INDEX @@ -1,5 +1,7 @@ 00-INDEX - This file +bfq-iosched.txt + - BFQ IO scheduler and its tunables biodoc.txt - Notes on the Generic Block Layer Rewrite in Linux 2.5 biovecs.txt diff --git a/Documentation/block/bfq-iosched.txt b/Documentation/block/bfq-iosched.txt new file mode 100644 index 000000000000..1b87df6cd476 --- /dev/null +++ b/Documentation/block/bfq-iosched.txt @@ -0,0 +1,531 @@ +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; +- BFQ distributes bandwidth, and not just time, among processes or + groups (switching back to time distribution when needed to keep + throughput high). + +On average CPUs, the current version of BFQ can handle devices +performing at most ~30K IOPS; at most ~50 KIOPS on faster CPUs. As a +reference, 30-50 KIOPS correspond to very high bandwidths with +sequential I/O (e.g., 8-12 GB/s if I/O requests are 256 KB large), and +to 120-200 MB/s with 4KB random I/O. BFQ has not yet been tested on +multi-queue devices. + +The table of contents follow. Impatients can just jump to Section 3. + +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 tunable? +4. BFQ group scheduling + 4-1 Service guarantees provided + 4-2 Interface + +1. When may BFQ be useful? +========================== + +BFQ provides the following benefits on personal and server systems. + +1-1 Personal 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, +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 +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 +sequential workloads considered in our tests. With random workloads, +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 +workload and regardless of the device parameters. From these bandwidth +guarantees, it is possible to compute tight per-I/O-request delay +guarantees by a simple formula. If not configured for strict service +guarantees, BFQ switches to time-based resource sharing (only) for +applications that would otherwise cause a throughput loss. + +1-2 Server systems +------------------ + +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 + rate; + +. fast retrieval of WEB pages and embedded objects; + +. real-time recording of data in live-dumping applications (e.g., + packet logging); + +. responsiveness in local and remote access to a server. + + +2. How does BFQ work? +===================== + +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 grants exclusive access to the device, for a while, to one queue + (process) at a time, and implements this service model by + associating every queue with a budget, measured in number of + sectors. + + - After a queue is granted access to the device, the budget of the + queue is decremented, on each request dispatch, by the size of the + request. + + - The in-service queue is expired, i.e., its service is suspended, + only if one of the following events occurs: 1) the queue finishes + its budget, 2) the queue empties, 3) a "budget timeout" fires. + + - The budget timeout prevents processes doing random I/O from + holding the device for too long and dramatically reducing + throughput. + + - Actually, as in CFQ, a queue associated with a process issuing + sync requests may not be expired immediately when it empties. In + contrast, BFQ may idle the device for a short time interval, + giving the process the chance to go on being served if it issues + a new request in time. Device idling typically boosts the + throughput on rotational devices, if processes do synchronous + and sequential I/O. In addition, under BFQ, device idling is + also instrumental in guaranteeing the desired throughput + fraction to processes issuing sync requests (see the description + of the slice_idle tunable in this document, or [1, 2], for more + details). + + - With respect to idling for service guarantees, if several + processes are competing for the device at the same time, but + all processes (and groups, after the following commit) have + the same weight, then BFQ guarantees the expected throughput + distribution without ever idling the device. Throughput is + thus as high as possible in this common scenario. + + - If low-latency mode is enabled (default configuration), BFQ + executes some special heuristics to detect interactive and soft + real-time applications (e.g., video or audio players/streamers), + and to reduce their latency. The most important action taken to + achieve this goal is to give to the queues associated with these + applications more than their fair share of the device + throughput. For brevity, we call just "weight-raising" the whole + sets of actions taken by BFQ to privilege these queues. In + particular, BFQ provides a milder form of weight-raising for + interactive applications, and a stronger form for soft real-time + applications. + + - BFQ automatically deactivates idling for queues born in a burst of + queue creations. In fact, these queues are usually associated with + the processes of applications and services that benefit mostly + from a high throughput. Examples are systemd during boot, or git + grep. + + - As CFQ, BFQ merges queues performing interleaved I/O, i.e., + performing random I/O that becomes mostly sequential if + merged. Differently from CFQ, BFQ achieves this goal with a more + reactive mechanism, called Early Queue Merge (EQM). EQM is so + responsive in detecting interleaved I/O (cooperating processes), + that it enables BFQ to achieve a high throughput, by queue + merging, even for queues for which CFQ needs a different + mechanism, preemption, to get a high throughput. As such EQM is a + unified mechanism to achieve a high throughput with interleaved + I/O. + + - Queues are scheduled according to a variant of WF2Q+, named + B-WF2Q+, and implemented using an augmented rb-tree to preserve an + O(log N) overall complexity. See [2] for more details. B-WF2Q+ is + also ready for hierarchical scheduling. However, for a cleaner + logical breakdown, the code that enables and completes + hierarchical support is provided in the next commit, which focuses + exactly on this feature. + + - B-WF2Q+ guarantees a tight deviation with respect to an ideal, + perfectly fair, and smooth service. In particular, B-WF2Q+ + guarantees that each queue receives a fraction of the device + throughput proportional to its weight, even if the throughput + fluctuates, and regardless of: the device parameters, the current + workload and the budgets assigned to the queue. + + - The last, budget-independence, property (although probably + counterintuitive in the first place) is definitely beneficial, for + the following reasons: + + - First, with any proportional-share scheduler, the maximum + deviation with respect to an ideal service is proportional to + the maximum budget (slice) assigned to queues. As a consequence, + BFQ can keep this deviation tight not only because of the + accurate service of B-WF2Q+, but also because BFQ *does not* + need to assign a larger budget to a queue to let the queue + receive a higher fraction of the device throughput. + + - Second, BFQ is free to choose, for every process (queue), the + budget that best fits the needs of the process, or best + leverages the I/O pattern of the process. In particular, BFQ + updates queue budgets with a simple feedback-loop algorithm that + allows a high throughput to be achieved, while still providing + tight latency guarantees to time-sensitive applications. When + the in-service queue expires, this algorithm computes the next + budget of the queue so as to: + + - Let large budgets be eventually assigned to the queues + associated with I/O-bound applications performing sequential + I/O: in fact, the longer these applications are served once + got access to the device, the higher the throughput is. + + - Let small budgets be eventually assigned to the queues + associated with time-sensitive applications (which typically + perform sporadic and short I/O), because, the smaller the + budget assigned to a queue waiting for service is, the sooner + B-WF2Q+ will serve that queue (Subsec 3.3 in [2]). + +- If several processes are competing for the device at the same time, + but all processes and groups have the same weight, then BFQ + guarantees the expected throughput distribution without ever idling + the device. It uses preemption instead. Throughput is then much + higher in this common scenario. + +- ioprio classes are served in strict priority order, i.e., + lower-priority queues are not served as long as there are + higher-priority queues. Among queues in the same class, the + bandwidth is distributed in proportion to the weight of each + queue. A very thin extra bandwidth is however guaranteed to + the Idle class, to prevent it from starving. + + +3. What are BFQ's tunable? +========================== + +The tunables back_seek-max, back_seek_penalty, fifo_expire_async and +fifo_expire_sync below are the same as in CFQ. Their description is +just copied from that for CFQ. Some considerations in the description +of slice_idle are copied from CFQ too. + +per-process ioprio and weight +----------------------------- + +Unless the cgroups interface is used (see "4. BFQ group scheduling"), +weights can be assigned to processes only indirectly, through I/O +priorities, and according to the relation: +weight = (IOPRIO_BE_NR - ioprio) * 10. + +Beware that, if low-latency is set, then BFQ automatically raises the +weight of the queues associated with interactive and soft real-time +applications. Unset this tunable if you need/want to control weights. + +slice_idle +---------- + +This parameter specifies how long BFQ should idle for next I/O +request, when certain sync BFQ queues become empty. By default +slice_idle is a non-zero value. Idling has a double purpose: boosting +throughput and making sure that the desired throughput distribution is +respected (see the description of how BFQ works, and, if needed, the +papers referred there). + +As for throughput, idling can be very helpful on highly seeky media +like single spindle SATA/SAS disks where we can cut down on overall +number of seeks and see improved throughput. + +Setting slice_idle to 0 will remove all the idling on queues and one +should see an overall improved throughput on faster storage devices +like multiple SATA/SAS disks in hardware RAID configuration. + +So depending on storage and workload, it might be useful to set +slice_idle=0. In general for SATA/SAS disks and software RAID of +SATA/SAS disks keeping slice_idle enabled should be useful. For any +configurations where there are multiple spindles behind single LUN +(Host based hardware RAID controller or for storage arrays), setting +slice_idle=0 might end up in better throughput and acceptable +latencies. + +Idling is however necessary to have service guarantees enforced in +case of differentiated weights or differentiated I/O-request lengths. +To see why, suppose that a given BFQ queue A must get several I/O +requests served for each request served for another queue B. Idling +ensures that, if A makes a new I/O request slightly after becoming +empty, then no request of B is dispatched in the middle, and thus A +does not lose the possibility to get more than one request dispatched +before the next request of B is dispatched. Note that idling +guarantees the desired differentiated treatment of queues only in +terms of I/O-request dispatches. To guarantee that the actual service +order then corresponds to the dispatch order, the strict_guarantees +tunable must be set too. + +There is an important flipside for idling: apart from the above cases +where it is beneficial also for throughput, idling can severely impact +throughput. One important case is random workload. Because of this +issue, BFQ tends to avoid idling as much as possible, when it is not +beneficial also for throughput. As a consequence of this behavior, and +of further issues described for the strict_guarantees tunable, +short-term service guarantees may be occasionally violated. And, in +some cases, these guarantees may be more important than guaranteeing +maximum throughput. For example, in video playing/streaming, a very +low drop rate may be more important than maximum throughput. In these +cases, consider setting the strict_guarantees parameter. + +strict_guarantees +----------------- + +If this parameter is set (default: unset), then BFQ + +- always performs idling when the in-service queue becomes empty; + +- forces the device to serve one I/O request at a time, by dispatching a + new request only if there is no outstanding request. + +In the presence of differentiated weights or I/O-request sizes, both +the above conditions are needed to guarantee that every BFQ queue +receives its allotted share of the bandwidth. The first condition is +needed for the reasons explained in the description of the slice_idle +tunable. The second condition is needed because all modern storage +devices reorder internally-queued requests, which may trivially break +the service guarantees enforced by the I/O scheduler. + +Setting strict_guarantees may evidently affect throughput. + +back_seek_max +------------- + +This specifies, given in Kbytes, the maximum "distance" for backward seeking. +The distance is the amount of space from the current head location to the +sectors that are backward in terms of distance. + +This parameter allows the scheduler to anticipate requests in the "backward" +direction and consider them as being the "next" if they are within this +distance from the current head location. + +back_seek_penalty +----------------- + +This parameter is used to compute the cost of backward seeking. If the +backward distance of request is just 1/back_seek_penalty from a "front" +request, then the seeking cost of two requests is considered equivalent. + +So scheduler will not bias toward one or the other request (otherwise scheduler +will bias toward front request). Default value of back_seek_penalty is 2. + +fifo_expire_async +----------------- + +This parameter is used to set the timeout of asynchronous requests. Default +value of this is 248ms. + +fifo_expire_sync +---------------- + +This parameter is used to set the timeout of synchronous requests. Default +value of this is 124ms. In case to favor synchronous requests over asynchronous +one, this value should be decreased relative to fifo_expire_async. + +low_latency +----------- + +This parameter is used to enable/disable BFQ's low latency mode. By +default, low latency mode is enabled. If enabled, interactive and soft +real-time applications are privileged and experience a lower latency, +as explained in more detail in the description of how BFQ works. + +DO NOT enable this mode if you need full control on bandwidth +distribution. In fact, if it is enabled, then BFQ automatically +increases the bandwidth share of privileged applications, as the main +means to guarantee a lower latency to them. + +timeout_sync +------------ + +Maximum amount of device time that can be given to a task (queue) once +it has been selected for service. On devices with costly seeks, +increasing this time usually increases maximum throughput. On the +opposite end, increasing this time coarsens the granularity of the +short-term bandwidth and latency guarantees, especially if the +following parameter is set to zero. + +max_budget +---------- + +Maximum amount of service, measured in sectors, that can be provided +to a BFQ queue once it is set in service (of course within the limits +of the above timeout). According to what said in the description of +the algorithm, larger values increase the throughput in proportion to +the percentage of sequential I/O requests issued. The price of larger +values is that they coarsen the granularity of short-term bandwidth +and latency guarantees. + +The default value is 0, which enables auto-tuning: BFQ sets max_budget +to the maximum number of sectors that can be served during +timeout_sync, according to the estimated peak rate. + +weights +------- + +Read-only parameter, used to show the weights of the currently active +BFQ queues. + + +wr_ tunables +------------ + +BFQ exports a few parameters to control/tune the behavior of +low-latency heuristics. + +wr_coeff + +Factor by which the weight of a weight-raised queue is multiplied. If +the queue is deemed soft real-time, then the weight is further +multiplied by an additional, constant factor. + +wr_max_time + +Maximum duration of a weight-raising period for an interactive task +(ms). If set to zero (default value), then this value is computed +automatically, as a function of the peak rate of the device. In any +case, when the value of this parameter is read, it always reports the +current duration, regardless of whether it has been set manually or +computed automatically. + +wr_max_softrt_rate + +Maximum service rate below which a queue is deemed to be associated +with a soft real-time application, and is then weight-raised +accordingly (sectors/sec). + +wr_min_idle_time + +Minimum idle period after which interactive weight-raising may be +reactivated for a queue (in ms). + +wr_rt_max_time + +Maximum weight-raising duration for soft real-time queues (in ms). The +start time from which this duration is considered is automatically +moved forward if the queue is detected to be still soft real-time +before the current soft real-time weight-raising period finishes. + +wr_min_inter_arr_async + +Minimum period between I/O request arrivals after which weight-raising +may be reactivated for an already busy async queue (in ms). + + +4. Group scheduling with BFQ +============================ + +BFQ supports both cgroups-v1 and cgroups-v2 io controllers, namely +blkio and io. In particular, BFQ supports weight-based proportional +share. To activate cgroups support, set BFQ_GROUP_IOSCHED. + +4-1 Service guarantees provided +------------------------------- + +With BFQ, proportional share means true proportional share of the +device bandwidth, according to group weights. For example, a group +with weight 200 gets twice the bandwidth, and not just twice the time, +of a group with weight 100. + +BFQ supports hierarchies (group trees) of any depth. Bandwidth is +distributed among groups and processes in the expected way: for each +group, the children of the group share the whole bandwidth of the +group in proportion to their weights. In particular, this implies +that, for each leaf group, every process of the group receives the +same share of the whole group bandwidth, unless the ioprio of the +process is modified. + +The resource-sharing guarantee for a group may partially or totally +switch from bandwidth to time, if providing bandwidth guarantees to +the group lowers the throughput too much. This switch occurs on a +per-process basis: if a process of a leaf group causes throughput loss +if served in such a way to receive its share of the bandwidth, then +BFQ switches back to just time-based proportional share for that +process. + +4-2 Interface +------------- + +To get proportional sharing of bandwidth with BFQ for a given device, +BFQ must of course be the active scheduler for that device. + +Within each group directory, the names of the files associated with +BFQ-specific cgroup parameters and stats begin with the "bfq." +prefix. So, with cgroups-v1 or cgroups-v2, the full prefix for +BFQ-specific files is "blkio.bfq." or "io.bfq." For example, the group +parameter to set the weight of a group with BFQ is blkio.bfq.weight +or io.bfq.weight. + +Parameters to set +----------------- + +For each group, there is only the following parameter to set. + +weight (namely blkio.bfq.weight or io.bfq-weight): the weight of the +group inside its parent. Available values: 1..10000 (default 100). The +linear mapping between ioprio and weights, described at the beginning +of the tunable section, is still valid, but all weights higher than +IOPRIO_BE_NR*10 are mapped to ioprio 0. + +Recall that, if low-latency is set, then BFQ automatically raises the +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 + 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 + 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 diff --git a/Documentation/block/kyber-iosched.txt b/Documentation/block/kyber-iosched.txt new file mode 100644 index 000000000000..e94feacd7edc --- /dev/null +++ b/Documentation/block/kyber-iosched.txt @@ -0,0 +1,14 @@ +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 +these target latencies. + +read_lat_nsec +------------- +Target latency for reads (in nanoseconds). + +write_lat_nsec +-------------- +Target latency for synchronous writes (in nanoseconds). diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt index c0a3bb5a6e4e..2c1e67058fd3 100644 --- a/Documentation/block/queue-sysfs.txt +++ b/Documentation/block/queue-sysfs.txt @@ -43,11 +43,6 @@ large discards are issued, setting this value lower will make Linux issue smaller discards and potentially help reduce latencies induced by large discard operations. -discard_zeroes_data (RO) ------------------------- -When read, this file will show if the discarded block are zeroed by the -device or not. If its value is '1' the blocks are zeroed otherwise not. - hw_sector_size (RO) ------------------- This is the hardware sector size of the device, in bytes. @@ -192,5 +187,11 @@ scaling back writes. Writing a value of '0' to this file disables the feature. Writing a value of '-1' to this file resets the value to the default setting. +throttle_sample_time (RW) +------------------------- +This is the time window that blk-throttle samples data, in millisecond. +blk-throttle makes decision based on the samplings. Lower time means cgroups +have more smooth throughput, but higher CPU overhead. This exists only when +CONFIG_BLK_DEV_THROTTLING_LOW is enabled. Jens Axboe <jens.axboe@oracle.com>, February 2009 diff --git a/Documentation/blockdev/mflash.txt b/Documentation/blockdev/mflash.txt deleted file mode 100644 index f7e050551487..000000000000 --- a/Documentation/blockdev/mflash.txt +++ /dev/null @@ -1,84 +0,0 @@ -This document describes m[g]flash support in linux. - -Contents - 1. Overview - 2. Reserved area configuration - 3. Example of mflash platform driver registration - -1. Overview - -Mflash and gflash are embedded flash drive. The only difference is mflash is -MCP(Multi Chip Package) device. These two device operate exactly same way. -So the rest mflash repersents mflash and gflash altogether. - -Internally, mflash has nand flash and other hardware logics and supports -2 different operation (ATA, IO) modes. ATA mode doesn't need any new -driver and currently works well under standard IDE subsystem. Actually it's -one chip SSD. IO mode is ATA-like custom mode for the host that doesn't have -IDE interface. - -Following are brief descriptions about IO mode. -A. IO mode based on ATA protocol and uses some custom command. (read confirm, -write confirm) -B. IO mode uses SRAM bus interface. -C. IO mode supports 4kB boot area, so host can boot from mflash. - -2. Reserved area configuration -If host boot from mflash, usually needs raw area for boot loader image. All of -the mflash's block device operation will be taken this value as start offset. -Note that boot loader's size of reserved area and kernel configuration value -must be same. - -3. Example of mflash platform driver registration -Working mflash is very straight forward. Adding platform device stuff to board -configuration file is all. Here is some pseudo example. - -static struct mg_drv_data mflash_drv_data = { - /* If you want to polling driver set to 1 */ - .use_polling = 0, - /* device attribution */ - .dev_attr = MG_BOOT_DEV -}; - -static struct resource mg_mflash_rsc[] = { - /* Base address of mflash */ - [0] = { - .start = 0x08000000, - .end = 0x08000000 + SZ_64K - 1, - .flags = IORESOURCE_MEM - }, - /* mflash interrupt pin */ - [1] = { - .start = IRQ_GPIO(84), - .end = IRQ_GPIO(84), - .flags = IORESOURCE_IRQ - }, - /* mflash reset pin */ - [2] = { - .start = 43, - .end = 43, - .name = MG_RST_PIN, - .flags = IORESOURCE_IO - }, - /* mflash reset-out pin - * If you use mflash as storage device (i.e. other than MG_BOOT_DEV), - * should assign this */ - [3] = { - .start = 51, - .end = 51, - .name = MG_RSTOUT_PIN, - .flags = IORESOURCE_IO - } -}; - -static struct platform_device mflash_dev = { - .name = MG_DEV_NAME, - .id = -1, - .dev = { - .platform_data = &mflash_drv_data, - }, - .num_resources = ARRAY_SIZE(mg_mflash_rsc), - .resource = mg_mflash_rsc -}; - -platform_device_register(&mflash_dev); diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt index 3b8449f8ac7e..e50b95c25868 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/cgroup-v2.txt @@ -871,6 +871,11 @@ PAGE_SIZE multiple when read back. Amount of memory used in network transmission buffers + shmem + + Amount of cached filesystem data that is swap-backed, + such as tmpfs, shm segments, shared anonymous mmap()s + file_mapped Amount of cached filesystem data mapped with mmap() @@ -1142,16 +1147,17 @@ used by the kernel. pids.max - A read-write single value file which exists on non-root cgroups. The - default is "max". + A read-write single value file which exists on non-root + cgroups. The default is "max". - Hard limit of number of processes. + Hard limit of number of processes. pids.current - A read-only single value file which exists on all cgroups. + A read-only single value file which exists on all cgroups. - The number of processes currently in the cgroup and its descendants. + The number of processes currently in the cgroup and its + descendants. Organisational operations are not blocked by cgroup policies, so it is possible to have pids.current > pids.max. This can be done by either diff --git a/Documentation/conf.py b/Documentation/conf.py index 7fadb3b83293..bacf9d337c89 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -17,7 +17,7 @@ import os import sphinx # Get Sphinx version -major, minor, patch = map(int, sphinx.__version__.split(".")) +major, minor, patch = sphinx.version_info[:3] # If extensions (or modules to document with autodoc) are in another directory, @@ -29,12 +29,12 @@ from load_config import loadConfig # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '1.2' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure'] # The name of the math extension changed on Sphinx 1.4 if major == 1 and minor > 3: @@ -348,6 +348,8 @@ latex_documents = [ 'The kernel development community', 'manual'), ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual', 'The kernel development community', 'manual'), + ('input/index', 'linux-input.tex', 'The Linux input driver subsystem', + 'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation', diff --git a/Documentation/core-api/flexible-arrays.rst b/Documentation/core-api/flexible-arrays.rst new file mode 100644 index 000000000000..b6b85a1b518e --- /dev/null +++ b/Documentation/core-api/flexible-arrays.rst @@ -0,0 +1,130 @@ + +=================================== +Using flexible arrays in the kernel +=================================== + +Large contiguous memory allocations can be unreliable in the Linux kernel. +Kernel programmers will sometimes respond to this problem by allocating +pages with :c:func:`vmalloc()`. This solution not ideal, though. On 32-bit +systems, memory from vmalloc() must be mapped into a relatively small address +space; it's easy to run out. On SMP systems, the page table changes required +by vmalloc() allocations can require expensive cross-processor interrupts on +all CPUs. And, on all systems, use of space in the vmalloc() range increases +pressure on the translation lookaside buffer (TLB), reducing the performance +of the system. + +In many cases, the need for memory from vmalloc() can be eliminated by piecing +together an array from smaller parts; the flexible array library exists to make +this task easier. + +A flexible array holds an arbitrary (within limits) number of fixed-sized +objects, accessed via an integer index. Sparse arrays are handled +reasonably well. Only single-page allocations are made, so memory +allocation failures should be relatively rare. The down sides are that the +arrays cannot be indexed directly, individual object size cannot exceed the +system page size, and putting data into a flexible array requires a copy +operation. It's also worth noting that flexible arrays do no internal +locking at all; if concurrent access to an array is possible, then the +caller must arrange for appropriate mutual exclusion. + +The creation of a flexible array is done with :c:func:`flex_array_alloc()`:: + + #include <linux/flex_array.h> + + struct flex_array *flex_array_alloc(int element_size, + unsigned int total, + gfp_t flags); + +The individual object size is provided by ``element_size``, while total is the +maximum number of objects which can be stored in the array. The flags +argument is passed directly to the internal memory allocation calls. With +the current code, using flags to ask for high memory is likely to lead to +notably unpleasant side effects. + +It is also possible to define flexible arrays at compile time with:: + + DEFINE_FLEX_ARRAY(name, element_size, total); + +This macro will result in a definition of an array with the given name; the +element size and total will be checked for validity at compile time. + +Storing data into a flexible array is accomplished with a call to +:c:func:`flex_array_put()`:: + + int flex_array_put(struct flex_array *array, unsigned int element_nr, + void *src, gfp_t flags); + +This call will copy the data from src into the array, in the position +indicated by ``element_nr`` (which must be less than the maximum specified when +the array was created). If any memory allocations must be performed, flags +will be used. The return value is zero on success, a negative error code +otherwise. + +There might possibly be a need to store data into a flexible array while +running in some sort of atomic context; in this situation, sleeping in the +memory allocator would be a bad thing. That can be avoided by using +``GFP_ATOMIC`` for the flags value, but, often, there is a better way. The +trick is to ensure that any needed memory allocations are done before +entering atomic context, using :c:func:`flex_array_prealloc()`:: + + int flex_array_prealloc(struct flex_array *array, unsigned int start, + unsigned int nr_elements, gfp_t flags); + +This function will ensure that memory for the elements indexed in the range +defined by ``start`` and ``nr_elements`` has been allocated. Thereafter, a +``flex_array_put()`` call on an element in that range is guaranteed not to +block. + +Getting data back out of the array is done with :c:func:`flex_array_get()`:: + + void *flex_array_get(struct flex_array *fa, unsigned int element_nr); + +The return value is a pointer to the data element, or NULL if that +particular element has never been allocated. + +Note that it is possible to get back a valid pointer for an element which +has never been stored in the array. Memory for array elements is allocated +one page at a time; a single allocation could provide memory for several +adjacent elements. Flexible array elements are normally initialized to the +value ``FLEX_ARRAY_FREE`` (defined as 0x6c in <linux/poison.h>), so errors +involving that number probably result from use of unstored array entries. +Note that, if array elements are allocated with ``__GFP_ZERO``, they will be +initialized to zero and this poisoning will not happen. + +Individual elements in the array can be cleared with +:c:func:`flex_array_clear()`:: + + int flex_array_clear(struct flex_array *array, unsigned int element_nr); + +This function will set the given element to ``FLEX_ARRAY_FREE`` and return +zero. If storage for the indicated element is not allocated for the array, +``flex_array_clear()`` will return ``-EINVAL`` instead. Note that clearing an +element does not release the storage associated with it; to reduce the +allocated size of an array, call :c:func:`flex_array_shrink()`:: + + int flex_array_shrink(struct flex_array *array); + +The return value will be the number of pages of memory actually freed. +This function works by scanning the array for pages containing nothing but +``FLEX_ARRAY_FREE`` bytes, so (1) it can be expensive, and (2) it will not work +if the array's pages are allocated with ``__GFP_ZERO``. + +It is possible to remove all elements of an array with a call to +:c:func:`flex_array_free_parts()`:: + + void flex_array_free_parts(struct flex_array *array); + +This call frees all elements, but leaves the array itself in place. +Freeing the entire array is done with :c:func:`flex_array_free()`:: + + void flex_array_free(struct flex_array *array); + +As of this writing, there are no users of flexible arrays in the mainline +kernel. The functions described here are also not exported to modules; +that will probably be fixed when somebody comes up with a need for it. + + +Flexible array functions +------------------------ + +.. kernel-doc:: include/linux/flex_array.h diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst new file mode 100644 index 000000000000..0054bd48be84 --- /dev/null +++ b/Documentation/core-api/genericirq.rst @@ -0,0 +1,440 @@ +.. include:: <isonum.txt> + +========================== +Linux generic IRQ handling +========================== + +:Copyright: |copy| 2005-2010: Thomas Gleixner +:Copyright: |copy| 2005-2006: Ingo Molnar + +Introduction +============ + +The generic interrupt handling layer is designed to provide a complete +abstraction of interrupt handling for device drivers. It is able to +handle all the different types of interrupt controller hardware. Device +drivers use generic API functions to request, enable, disable and free +interrupts. The drivers do not have to know anything about interrupt +hardware details, so they can be used on different platforms without +code changes. + +This documentation is provided to developers who want to implement an +interrupt subsystem based for their architecture, with the help of the +generic IRQ handling layer. + +Rationale +========= + +The original implementation of interrupt handling in Linux uses the +:c:func:`__do_IRQ` super-handler, which is able to deal with every type of +interrupt logic. + +Originally, Russell King identified different types of handlers to build +a quite universal set for the ARM interrupt handler implementation in +Linux 2.5/2.6. He distinguished between: + +- Level type + +- Edge type + +- Simple type + +During the implementation we identified another type: + +- Fast EOI type + +In the SMP world of the :c:func:`__do_IRQ` super-handler another type was +identified: + +- Per CPU type + +This split implementation of high-level IRQ handlers allows us to +optimize the flow of the interrupt handling for each specific interrupt +type. This reduces complexity in that particular code path and allows +the optimized handling of a given type. + +The original general IRQ implementation used hw_interrupt_type +structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate +the flow control in the super-handler. This leads to a mix of flow logic +and low-level hardware logic, and it also leads to unnecessary code +duplication: for example in i386, there is an ``ioapic_level_irq`` and an +``ioapic_edge_irq`` IRQ-type which share many of the low-level details but +have different flow handling. + +A more natural abstraction is the clean separation of the 'irq flow' and +the 'chip details'. + +Analysing a couple of architecture's IRQ subsystem implementations +reveals that most of them can use a generic set of 'irq flow' methods +and only need to add the chip-level specific code. The separation is +also valuable for (sub)architectures which need specific quirks in the +IRQ flow itself but not in the chip details - and thus provides a more +transparent IRQ subsystem design. + +Each interrupt descriptor is assigned its own high-level flow handler, +which is normally one of the generic implementations. (This high-level +flow handler implementation also makes it simple to provide +demultiplexing handlers which can be found in embedded platforms on +various architectures.) + +The separation makes the generic interrupt handling layer more flexible +and extensible. For example, an (sub)architecture can use a generic +IRQ-flow implementation for 'level type' interrupts and add a +(sub)architecture specific 'edge type' implementation. + +To make the transition to the new model easier and prevent the breakage +of existing implementations, the :c:func:`__do_IRQ` super-handler is still +available. This leads to a kind of duality for the time being. Over time +the new model should be used in more and more architectures, as it +enables smaller and cleaner IRQ subsystems. It's deprecated for three +years now and about to be removed. + +Known Bugs And Assumptions +========================== + +None (knock on wood). + +Abstraction layers +================== + +There are three main levels of abstraction in the interrupt code: + +1. High-level driver API + +2. High-level IRQ flow handlers + +3. Chip-level hardware encapsulation + +Interrupt control flow +---------------------- + +Each interrupt is described by an interrupt descriptor structure +irq_desc. The interrupt is referenced by an 'unsigned int' numeric +value which selects the corresponding interrupt description structure in +the descriptor structures array. The descriptor structure contains +status information and pointers to the interrupt flow method and the +interrupt chip structure which are assigned to this interrupt. + +Whenever an interrupt triggers, the low-level architecture code calls +into the generic interrupt code by calling :c:func:`desc->handle_irq`. This +high-level IRQ handling function only uses desc->irq_data.chip +primitives referenced by the assigned chip descriptor structure. + +High-level Driver API +--------------------- + +The high-level Driver API consists of following functions: + +- :c:func:`request_irq` + +- :c:func:`free_irq` + +- :c:func:`disable_irq` + +- :c:func:`enable_irq` + +- :c:func:`disable_irq_nosync` (SMP only) + +- :c:func:`synchronize_irq` (SMP only) + +- :c:func:`irq_set_irq_type` + +- :c:func:`irq_set_irq_wake` + +- :c:func:`irq_set_handler_data` + +- :c:func:`irq_set_chip` + +- :c:func:`irq_set_chip_data` + +See the autogenerated function documentation for details. + +High-level IRQ flow handlers +---------------------------- + +The generic layer provides a set of pre-defined irq-flow methods: + +- :c:func:`handle_level_irq` + +- :c:func:`handle_edge_irq` + +- :c:func:`handle_fasteoi_irq` + +- :c:func:`handle_simple_irq` + +- :c:func:`handle_percpu_irq` + +- :c:func:`handle_edge_eoi_irq` + +- :c:func:`handle_bad_irq` + +The interrupt flow handlers (either pre-defined or architecture +specific) are assigned to specific interrupts by the architecture either +during bootup or during device initialization. + +Default flow implementations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Helper functions +^^^^^^^^^^^^^^^^ + +The helper functions call the chip primitives and are used by the +default flow implementations. The following helper functions are +implemented (simplified excerpt):: + + default_enable(struct irq_data *data) + { + desc->irq_data.chip->irq_unmask(data); + } + + default_disable(struct irq_data *data) + { + if (!delay_disable(data)) + desc->irq_data.chip->irq_mask(data); + } + + default_ack(struct irq_data *data) + { + chip->irq_ack(data); + } + + default_mask_ack(struct irq_data *data) + { + if (chip->irq_mask_ack) { + chip->irq_mask_ack(data); + } else { + chip->irq_mask(data); + chip->irq_ack(data); + } + } + + noop(struct irq_data *data)) + { + } + + + +Default flow handler implementations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Default Level IRQ flow handler +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_level_irq provides a generic implementation for level-triggered +interrupts. + +The following control flow is implemented (simplified excerpt):: + + :c:func:`desc->irq_data.chip->irq_mask_ack`; + handle_irq_event(desc->action); + :c:func:`desc->irq_data.chip->irq_unmask`; + + +Default Fast EOI IRQ flow handler +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_fasteoi_irq provides a generic implementation for interrupts, +which only need an EOI at the end of the handler. + +The following control flow is implemented (simplified excerpt):: + + handle_irq_event(desc->action); + :c:func:`desc->irq_data.chip->irq_eoi`; + + +Default Edge IRQ flow handler +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_edge_irq provides a generic implementation for edge-triggered +interrupts. + +The following control flow is implemented (simplified excerpt):: + + if (desc->status & running) { + :c:func:`desc->irq_data.chip->irq_mask_ack`; + desc->status |= pending | masked; + return; + } + :c:func:`desc->irq_data.chip->irq_ack`; + desc->status |= running; + do { + if (desc->status & masked) + :c:func:`desc->irq_data.chip->irq_unmask`; + desc->status &= ~pending; + handle_irq_event(desc->action); + } while (status & pending); + desc->status &= ~running; + + +Default simple IRQ flow handler +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_simple_irq provides a generic implementation for simple +interrupts. + +.. note:: + + The simple flow handler does not call any handler/chip primitives. + +The following control flow is implemented (simplified excerpt):: + + handle_irq_event(desc->action); + + +Default per CPU flow handler +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_percpu_irq provides a generic implementation for per CPU +interrupts. + +Per CPU interrupts are only available on SMP and the handler provides a +simplified version without locking. + +The following control flow is implemented (simplified excerpt):: + + if (desc->irq_data.chip->irq_ack) + :c:func:`desc->irq_data.chip->irq_ack`; + handle_irq_event(desc->action); + if (desc->irq_data.chip->irq_eoi) + :c:func:`desc->irq_data.chip->irq_eoi`; + + +EOI Edge IRQ flow handler +^^^^^^^^^^^^^^^^^^^^^^^^^ + +handle_edge_eoi_irq provides an abnomination of the edge handler +which is solely used to tame a badly wreckaged irq controller on +powerpc/cell. + +Bad IRQ flow handler +^^^^^^^^^^^^^^^^^^^^ + +handle_bad_irq is used for spurious interrupts which have no real +handler assigned.. + +Quirks and optimizations +~~~~~~~~~~~~~~~~~~~~~~~~ + +The generic functions are intended for 'clean' architectures and chips, +which have no platform-specific IRQ handling quirks. If an architecture +needs to implement quirks on the 'flow' level then it can do so by +overriding the high-level irq-flow handler. + +Delayed interrupt disable +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This per interrupt selectable feature, which was introduced by Russell +King in the ARM interrupt implementation, does not mask an interrupt at +the hardware level when :c:func:`disable_irq` is called. The interrupt is kept +enabled and is masked in the flow handler when an interrupt event +happens. This prevents losing edge interrupts on hardware which does not +store an edge interrupt event while the interrupt is disabled at the +hardware level. When an interrupt arrives while the IRQ_DISABLED flag +is set, then the interrupt is masked at the hardware level and the +IRQ_PENDING bit is set. When the interrupt is re-enabled by +:c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt +is resent either via hardware or by a software resend mechanism. (It's +necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use +the delayed interrupt disable feature and your hardware is not capable +of retriggering an interrupt.) The delayed interrupt disable is not +configurable. + +Chip-level hardware encapsulation +--------------------------------- + +The chip-level hardware descriptor structure :c:type:`irq_chip` contains all +the direct chip relevant functions, which can be utilized by the irq flow +implementations. + +- ``irq_ack`` + +- ``irq_mask_ack`` - Optional, recommended for performance + +- ``irq_mask`` + +- ``irq_unmask`` + +- ``irq_eoi`` - Optional, required for EOI flow handlers + +- ``irq_retrigger`` - Optional + +- ``irq_set_type`` - Optional + +- ``irq_set_wake`` - Optional + +These primitives are strictly intended to mean what they say: ack means +ACK, masking means masking of an IRQ line, etc. It is up to the flow +handler(s) to use these basic units of low-level functionality. + +__do_IRQ entry point +==================== + +The original implementation :c:func:`__do_IRQ` was an alternative entry point +for all types of interrupts. It no longer exists. + +This handler turned out to be not suitable for all interrupt hardware +and was therefore reimplemented with split functionality for +edge/level/simple/percpu interrupts. This is not only a functional +optimization. It also shortens code paths for interrupts. + +Locking on SMP +============== + +The locking of chip registers is up to the architecture that defines the +chip primitives. The per-irq structure is protected via desc->lock, by +the generic layer. + +Generic interrupt chip +====================== + +To avoid copies of identical implementations of IRQ chips the core +provides a configurable generic interrupt chip implementation. +Developers should check carefully whether the generic chip fits their +needs before implementing the same functionality slightly differently +themselves. + +.. kernel-doc:: kernel/irq/generic-chip.c + :export: + +Structures +========== + +This chapter contains the autogenerated documentation of the structures +which are used in the generic IRQ layer. + +.. kernel-doc:: include/linux/irq.h + :internal: + +.. kernel-doc:: include/linux/interrupt.h + :internal: + +Public Functions Provided +========================= + +This chapter contains the autogenerated documentation of the kernel API +functions which are exported. + +.. kernel-doc:: kernel/irq/manage.c + +.. kernel-doc:: kernel/irq/chip.c + +Internal Functions Provided +=========================== + +This chapter contains the autogenerated documentation of the internal +functions. + +.. kernel-doc:: kernel/irq/irqdesc.c + +.. kernel-doc:: kernel/irq/handle.c + +.. kernel-doc:: kernel/irq/chip.c + +Credits +======= + +The following people have contributed to this document: + +1. Thomas Gleixner tglx@linutronix.de + +2. Ingo Molnar mingo@elte.hu diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 0d93d8089136..62abd36bfffb 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -11,11 +11,14 @@ Core utilities .. toctree:: :maxdepth: 1 + kernel-api assoc_array atomic_ops cpu_hotplug local_ops workqueue + genericirq + flexible-arrays Interfaces for kernel debugging =============================== diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst new file mode 100644 index 000000000000..9ec8488319dc --- /dev/null +++ b/Documentation/core-api/kernel-api.rst @@ -0,0 +1,346 @@ +==================== +The Linux Kernel API +==================== + +Data Types +========== + +Doubly Linked Lists +------------------- + +.. kernel-doc:: include/linux/list.h + :internal: + +Basic C Library Functions +========================= + +When writing drivers, you cannot in general use routines which are from +the C Library. Some of the functions have been found generally useful +and they are listed below. The behaviour of these functions may vary +slightly from those defined by ANSI, and these deviations are noted in +the text. + +String Conversions +------------------ + +.. kernel-doc:: lib/vsprintf.c + :export: + +.. kernel-doc:: include/linux/kernel.h + :functions: kstrtol + +.. kernel-doc:: include/linux/kernel.h + :functions: kstrtoul + +.. kernel-doc:: lib/kstrtox.c + :export: + +String Manipulation +------------------- + +.. kernel-doc:: lib/string.c + :export: + +Bit Operations +-------------- + +.. kernel-doc:: arch/x86/include/asm/bitops.h + :internal: + +Basic Kernel Library Functions +============================== + +The Linux kernel provides more basic utility functions. + +Bitmap Operations +----------------- + +.. kernel-doc:: lib/bitmap.c + :export: + +.. kernel-doc:: lib/bitmap.c + :internal: + +Command-line Parsing +-------------------- + +.. kernel-doc:: lib/cmdline.c + :export: + +CRC Functions +------------- + +.. kernel-doc:: lib/crc7.c + :export: + +.. kernel-doc:: lib/crc16.c + :export: + +.. kernel-doc:: lib/crc-itu-t.c + :export: + +.. kernel-doc:: lib/crc32.c + +.. kernel-doc:: lib/crc-ccitt.c + :export: + +idr/ida Functions +----------------- + +.. kernel-doc:: include/linux/idr.h + :doc: idr sync + +.. kernel-doc:: lib/idr.c + :doc: IDA description + +.. kernel-doc:: lib/idr.c + :export: + +Memory Management in Linux +========================== + +The Slab Cache +-------------- + +.. kernel-doc:: include/linux/slab.h + :internal: + +.. kernel-doc:: mm/slab.c + :export: + +.. kernel-doc:: mm/util.c + :export: + +User Space Memory Access +------------------------ + +.. kernel-doc:: arch/x86/include/asm/uaccess_32.h + :internal: + +.. kernel-doc:: arch/x86/lib/usercopy_32.c + :export: + +More Memory Management Functions +-------------------------------- + +.. kernel-doc:: mm/readahead.c + :export: + +.. kernel-doc:: mm/filemap.c + :export: + +.. kernel-doc:: mm/memory.c + :export: + +.. kernel-doc:: mm/vmalloc.c + :export: + +.. kernel-doc:: mm/page_alloc.c + :internal: + +.. kernel-doc:: mm/mempool.c + :export: + +.. kernel-doc:: mm/dmapool.c + :export: + +.. kernel-doc:: mm/page-writeback.c + :export: + +.. kernel-doc:: mm/truncate.c + :export: + +Kernel IPC facilities +===================== + +IPC utilities +------------- + +.. kernel-doc:: ipc/util.c + :internal: + +FIFO Buffer +=========== + +kfifo interface +--------------- + +.. kernel-doc:: include/linux/kfifo.h + :internal: + +relay interface support +======================= + +Relay interface support is designed to provide an efficient mechanism +for tools and facilities to relay large amounts of data from kernel +space to user space. + +relay interface +--------------- + +.. kernel-doc:: kernel/relay.c + :export: + +.. kernel-doc:: kernel/relay.c + :internal: + +Module Support +============== + +Module Loading +-------------- + +.. kernel-doc:: kernel/kmod.c + :export: + +Inter Module support +-------------------- + +Refer to the file kernel/module.c for more information. + +Hardware Interfaces +=================== + +Interrupt Handling +------------------ + +.. kernel-doc:: kernel/irq/manage.c + :export: + +DMA Channels +------------ + +.. kernel-doc:: kernel/dma.c + :export: + +Resources Management +-------------------- + +.. kernel-doc:: kernel/resource.c + :internal: + +.. kernel-doc:: kernel/resource.c + :export: + +MTRR Handling +------------- + +.. kernel-doc:: arch/x86/kernel/cpu/mtrr/main.c + :export: + +Security Framework +================== + +.. kernel-doc:: security/security.c + :internal: + +.. kernel-doc:: security/inode.c + :export: + +Audit Interfaces +================ + +.. kernel-doc:: kernel/audit.c + :export: + +.. kernel-doc:: kernel/auditsc.c + :internal: + +.. kernel-doc:: kernel/auditfilter.c + :internal: + +Accounting Framework +==================== + +.. kernel-doc:: kernel/acct.c + :internal: + +Block Devices +============= + +.. kernel-doc:: block/blk-core.c + :export: + +.. kernel-doc:: block/blk-core.c + :internal: + +.. kernel-doc:: block/blk-map.c + :export: + +.. kernel-doc:: block/blk-sysfs.c + :internal: + +.. kernel-doc:: block/blk-settings.c + :export: + +.. kernel-doc:: block/blk-exec.c + :export: + +.. kernel-doc:: block/blk-flush.c + :export: + +.. kernel-doc:: block/blk-lib.c + :export: + +.. kernel-doc:: block/blk-tag.c + :export: + +.. kernel-doc:: block/blk-tag.c + :internal: + +.. kernel-doc:: block/blk-integrity.c + :export: + +.. kernel-doc:: kernel/trace/blktrace.c + :internal: + +.. kernel-doc:: block/genhd.c + :internal: + +.. kernel-doc:: block/genhd.c + :export: + +Char devices +============ + +.. kernel-doc:: fs/char_dev.c + :export: + +Clock Framework +=============== + +The clock framework defines programming interfaces to support software +management of the system clock tree. This framework is widely used with +System-On-Chip (SOC) platforms to support power management and various +devices which may need custom clock rates. Note that these "clocks" +don't relate to timekeeping or real time clocks (RTCs), each of which +have separate frameworks. These :c:type:`struct clk <clk>` +instances may be used to manage for example a 96 MHz signal that is used +to shift bits into and out of peripherals or busses, or otherwise +trigger synchronous state machine transitions in system hardware. + +Power management is supported by explicit software clock gating: unused +clocks are disabled, so the system doesn't waste power changing the +state of transistors that aren't in active use. On some systems this may +be backed by hardware clock gating, where clocks are gated without being +disabled in software. Sections of chips that are powered but not clocked +may be able to retain their last state. This low power state is often +called a *retention mode*. This mode still incurs leakage currents, +especially with finer circuit geometries, but for CMOS circuits power is +mostly used by clocked state changes. + +Power-aware drivers only enable their clocks when the device they manage +is in active use. Also, system sleep states often differ according to +which clock domains are active: while a "standby" state may allow wakeup +from several active domains, a "mem" (suspend-to-RAM) state may require +a more wholesale shutdown of clocks derived from higher speed PLLs and +oscillators, limiting the number of possible wakeup event sources. A +driver's suspend method may need to be aware of system-specific clock +constraints on the target sleep state. + +Some platforms support programmable clock generators. These can be used +by external chips of various kinds, such as other CPUs, multimedia +codecs, and devices with strict requirements for interface clocking. + +.. kernel-doc:: include/linux/clk.h + :internal: diff --git a/Documentation/cpu-freq/boost.txt b/Documentation/cpu-freq/boost.txt deleted file mode 100644 index dd62e1334f0a..000000000000 --- a/Documentation/cpu-freq/boost.txt +++ /dev/null @@ -1,93 +0,0 @@ -Processor boosting control - - - information for users - - -Quick guide for the impatient: --------------------- -/sys/devices/system/cpu/cpufreq/boost -controls the boost setting for the whole system. You can read and write -that file with either "0" (boosting disabled) or "1" (boosting allowed). -Reading or writing 1 does not mean that the system is boosting at this -very moment, but only that the CPU _may_ raise the frequency at it's -discretion. --------------------- - -Introduction -------------- -Some CPUs support a functionality to raise the operating frequency of -some cores in a multi-core package if certain conditions apply, mostly -if the whole chip is not fully utilized and below it's intended thermal -budget. The decision about boost disable/enable is made either at hardware -(e.g. x86) or software (e.g ARM). -On Intel CPUs this is called "Turbo Boost", AMD calls it "Turbo-Core", -in technical documentation "Core performance boost". In Linux we use -the term "boost" for convenience. - -Rationale for disable switch ----------------------------- - -Though the idea is to just give better performance without any user -intervention, sometimes the need arises to disable this functionality. -Most systems offer a switch in the (BIOS) firmware to disable the -functionality at all, but a more fine-grained and dynamic control would -be desirable: -1. While running benchmarks, reproducible results are important. Since - the boosting functionality depends on the load of the whole package, - single thread performance can vary. By explicitly disabling the boost - functionality at least for the benchmark's run-time the system will run - at a fixed frequency and results are reproducible again. -2. To examine the impact of the boosting functionality it is helpful - to do tests with and without boosting. -3. Boosting means overclocking the processor, though under controlled - conditions. By raising the frequency and the voltage the processor - will consume more power than without the boosting, which may be - undesirable for instance for mobile users. Disabling boosting may - save power here, though this depends on the workload. - - -User controlled switch ----------------------- - -To allow the user to toggle the boosting functionality, the cpufreq core -driver exports a sysfs knob to enable or disable it. There is a file: -/sys/devices/system/cpu/cpufreq/boost -which can either read "0" (boosting disabled) or "1" (boosting enabled). -The file is exported only when cpufreq driver supports boosting. -Explicitly changing the permissions and writing to that file anyway will -return EINVAL. - -On supported CPUs one can write either a "0" or a "1" into this file. -This will either disable the boost functionality on all cores in the -whole system (0) or will allow the software or hardware to boost at will -(1). - -Writing a "1" does not explicitly boost the system, but just allows the -CPU to boost at their discretion. Some implementations take external -factors like the chip's temperature into account, so boosting once does -not necessarily mean that it will occur every time even using the exact -same software setup. - - -AMD legacy cpb switch ---------------------- -The AMD powernow-k8 driver used to support a very similar switch to -disable or enable the "Core Performance Boost" feature of some AMD CPUs. -This switch was instantiated in each CPU's cpufreq directory -(/sys/devices/system/cpu[0-9]*/cpufreq) and was called "cpb". -Though the per CPU existence hints at a more fine grained control, the -actual implementation only supported a system-global switch semantics, -which was simply reflected into each CPU's file. Writing a 0 or 1 into it -would pull the other CPUs to the same state. -For compatibility reasons this file and its behavior is still supported -on AMD CPUs, though it is now protected by a config switch -(X86_ACPI_CPUFREQ_CPB). On Intel CPUs this file will never be created, -even with the config option set. -This functionality is considered legacy and will be removed in some future -kernel version. - -More fine grained boosting control ----------------------------------- - -Technically it is possible to switch the boosting functionality at least -on a per package basis, for some CPUs even per core. Currently the driver -does not support it, but this may be implemented in the future. diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.txt index f71e6be26b83..434c49cc7330 100644 --- a/Documentation/cpu-freq/cpu-drivers.txt +++ b/Documentation/cpu-freq/cpu-drivers.txt @@ -231,7 +231,7 @@ the reference implementation in drivers/cpufreq/longrun.c Only for drivers with target_index() and CPUFREQ_ASYNC_NOTIFICATION unset. get_intermediate should return a stable intermediate frequency platform wants to -switch to, and target_intermediate() should set CPU to to that frequency, before +switch to, and target_intermediate() should set CPU to that frequency, before jumping to the frequency corresponding to 'index'. Core will take care of sending notifications and driver doesn't have to handle them in target_intermediate() or target_index(). diff --git a/Documentation/cpu-freq/governors.txt b/Documentation/cpu-freq/governors.txt deleted file mode 100644 index 61b3184b6c24..000000000000 --- a/Documentation/cpu-freq/governors.txt +++ /dev/null @@ -1,301 +0,0 @@ - CPU frequency and voltage scaling code in the Linux(TM) kernel - - - L i n u x C P U F r e q - - C P U F r e q G o v e r n o r s - - - information for users and developers - - - - Dominik Brodowski <linux@brodo.de> - some additions and corrections by Nico Golde <nico@ngolde.de> - Rafael J. Wysocki <rafael.j.wysocki@intel.com> - Viresh Kumar <viresh.kumar@linaro.org> - - - - Clock scaling allows you to change the clock speed of the CPUs on the - fly. This is a nice method to save battery power, because the lower - the clock speed, the less power the CPU consumes. - - -Contents: ---------- -1. What is a CPUFreq Governor? - -2. Governors In the Linux Kernel -2.1 Performance -2.2 Powersave -2.3 Userspace -2.4 Ondemand -2.5 Conservative -2.6 Schedutil - -3. The Governor Interface in the CPUfreq Core - -4. References - - -1. What Is A CPUFreq Governor? -============================== - -Most cpufreq drivers (except the intel_pstate and longrun) or even most -cpu frequency scaling algorithms only allow the CPU frequency to be set -to predefined fixed values. In order to offer dynamic frequency -scaling, the cpufreq core must be able to tell these drivers of a -"target frequency". So these specific drivers will be transformed to -offer a "->target/target_index/fast_switch()" call instead of the -"->setpolicy()" call. For set_policy drivers, all stays the same, -though. - -How to decide what frequency within the CPUfreq policy should be used? -That's done using "cpufreq governors". - -Basically, it's the following flow graph: - -CPU can be set to switch independently | CPU can only be set - within specific "limits" | to specific frequencies - - "CPUfreq policy" - consists of frequency limits (policy->{min,max}) - and CPUfreq governor to be used - / \ - / \ - / the cpufreq governor decides - / (dynamically or statically) - / what target_freq to set within - / the limits of policy->{min,max} - / \ - / \ - Using the ->setpolicy call, Using the ->target/target_index/fast_switch call, - the limits and the the frequency closest - "policy" is set. to target_freq is set. - It is assured that it - is within policy->{min,max} - - -2. Governors In the Linux Kernel -================================ - -2.1 Performance ---------------- - -The CPUfreq governor "performance" sets the CPU statically to the -highest frequency within the borders of scaling_min_freq and -scaling_max_freq. - - -2.2 Powersave -------------- - -The CPUfreq governor "powersave" sets the CPU statically to the -lowest frequency within the borders of scaling_min_freq and -scaling_max_freq. - - -2.3 Userspace -------------- - -The CPUfreq governor "userspace" allows the user, or any userspace -program running with UID "root", to set the CPU to a specific frequency -by making a sysfs file "scaling_setspeed" available in the CPU-device -directory. - - -2.4 Ondemand ------------- - -The CPUfreq governor "ondemand" sets the CPU frequency depending on the -current system load. Load estimation is triggered by the scheduler -through the update_util_data->func hook; when triggered, cpufreq checks -the CPU-usage statistics over the last period and the governor sets the -CPU accordingly. The CPU must have the capability to switch the -frequency very quickly. - -Sysfs files: - -* sampling_rate: - - Measured in uS (10^-6 seconds), this is how often you want the kernel - to look at the CPU usage and to make decisions on what to do about the - frequency. Typically this is set to values of around '10000' or more. - It's default value is (cmp. with users-guide.txt): transition_latency - * 1000. Be aware that transition latency is in ns and sampling_rate - is in us, so you get the same sysfs value by default. Sampling rate - should always get adjusted considering the transition latency to set - the sampling rate 750 times as high as the transition latency in the - bash (as said, 1000 is default), do: - - $ echo `$(($(cat cpuinfo_transition_latency) * 750 / 1000)) > ondemand/sampling_rate - -* sampling_rate_min: - - The sampling rate is limited by the HW transition latency: - transition_latency * 100 - - Or by kernel restrictions: - - If CONFIG_NO_HZ_COMMON is set, the limit is 10ms fixed. - - If CONFIG_NO_HZ_COMMON is not set or nohz=off boot parameter is - used, the limits depend on the CONFIG_HZ option: - HZ=1000: min=20000us (20ms) - HZ=250: min=80000us (80ms) - HZ=100: min=200000us (200ms) - - The highest value of kernel and HW latency restrictions is shown and - used as the minimum sampling rate. - -* up_threshold: - - This defines what the average CPU usage between the samplings of - 'sampling_rate' needs to be for the kernel to make a decision on - whether it should increase the frequency. For example when it is set - to its default value of '95' it means that between the checking - intervals the CPU needs to be on average more than 95% in use to then - decide that the CPU frequency needs to be increased. - -* ignore_nice_load: - - This parameter takes a value of '0' or '1'. When set to '0' (its - default), all processes are counted towards the 'cpu utilisation' - value. When set to '1', the processes that are run with a 'nice' - value will not count (and thus be ignored) in the overall usage - calculation. This is useful if you are running a CPU intensive - calculation on your laptop that you do not care how long it takes to - complete as you can 'nice' it and prevent it from taking part in the - deciding process of whether to increase your CPU frequency. - -* sampling_down_factor: - - This parameter controls the rate at which the kernel makes a decision - on when to decrease the frequency while running at top speed. When set - to 1 (the default) decisions to reevaluate load are made at the same - interval regardless of current clock speed. But when set to greater - than 1 (e.g. 100) it acts as a multiplier for the scheduling interval - for reevaluating load when the CPU is at its top speed due to high - load. This improves performance by reducing the overhead of load - evaluation and helping the CPU stay at its top speed when truly busy, - rather than shifting back and forth in speed. This tunable has no - effect on behavior at lower speeds/lower CPU loads. - -* powersave_bias: - - This parameter takes a value between 0 to 1000. It defines the - percentage (times 10) value of the target frequency that will be - shaved off of the target. For example, when set to 100 -- 10%, when - ondemand governor would have targeted 1000 MHz, it will target - 1000 MHz - (10% of 1000 MHz) = 900 MHz instead. This is set to 0 - (disabled) by default. - - When AMD frequency sensitivity powersave bias driver -- - drivers/cpufreq/amd_freq_sensitivity.c is loaded, this parameter - defines the workload frequency sensitivity threshold in which a lower - frequency is chosen instead of ondemand governor's original target. - The frequency sensitivity is a hardware reported (on AMD Family 16h - Processors and above) value between 0 to 100% that tells software how - the performance of the workload running on a CPU will change when - frequency changes. A workload with sensitivity of 0% (memory/IO-bound) - will not perform any better on higher core frequency, whereas a - workload with sensitivity of 100% (CPU-bound) will perform better - higher the frequency. When the driver is loaded, this is set to 400 by - default -- for CPUs running workloads with sensitivity value below - 40%, a lower frequency is chosen. Unloading the driver or writing 0 - will disable this feature. - - -2.5 Conservative ----------------- - -The CPUfreq governor "conservative", much like the "ondemand" -governor, sets the CPU frequency depending on the current usage. It -differs in behaviour in that it gracefully increases and decreases the -CPU speed rather than jumping to max speed the moment there is any load -on the CPU. This behaviour is more suitable in a battery powered -environment. The governor is tweaked in the same manner as the -"ondemand" governor through sysfs with the addition of: - -* freq_step: - - This describes what percentage steps the cpu freq should be increased - and decreased smoothly by. By default the cpu frequency will increase - in 5% chunks of your maximum cpu frequency. You can change this value - to anywhere between 0 and 100 where '0' will effectively lock your CPU - at a speed regardless of its load whilst '100' will, in theory, make - it behave identically to the "ondemand" governor. - -* down_threshold: - - Same as the 'up_threshold' found for the "ondemand" governor but for - the opposite direction. For example when set to its default value of - '20' it means that if the CPU usage needs to be below 20% between - samples to have the frequency decreased. - -* sampling_down_factor: - - Similar functionality as in "ondemand" governor. But in - "conservative", it controls the rate at which the kernel makes a - decision on when to decrease the frequency while running in any speed. - Load for frequency increase is still evaluated every sampling rate. - - -2.6 Schedutil -------------- - -The "schedutil" governor aims at better integration with the Linux -kernel scheduler. Load estimation is achieved through the scheduler's -Per-Entity Load Tracking (PELT) mechanism, which also provides -information about the recent load [1]. This governor currently does -load based DVFS only for tasks managed by CFS. RT and DL scheduler tasks -are always run at the highest frequency. Unlike all the other -governors, the code is located under the kernel/sched/ directory. - -Sysfs files: - -* rate_limit_us: - - This contains a value in microseconds. The governor waits for - rate_limit_us time before reevaluating the load again, after it has - evaluated the load once. - -For an in-depth comparison with the other governors refer to [2]. - - -3. The Governor Interface in the CPUfreq Core -============================================= - -A new governor must register itself with the CPUfreq core using -"cpufreq_register_governor". The struct cpufreq_governor, which has to -be passed to that function, must contain the following values: - -governor->name - A unique name for this governor. -governor->owner - .THIS_MODULE for the governor module (if appropriate). - -plus a set of hooks to the functions implementing the governor's logic. - -The CPUfreq governor may call the CPU processor driver using one of -these two functions: - -int cpufreq_driver_target(struct cpufreq_policy *policy, - unsigned int target_freq, - unsigned int relation); - -int __cpufreq_driver_target(struct cpufreq_policy *policy, - unsigned int target_freq, - unsigned int relation); - -target_freq must be within policy->min and policy->max, of course. -What's the difference between these two functions? When your governor is -in a direct code path of a call to governor callbacks, like -governor->start(), the policy->rwsem is still held in the cpufreq core, -and there's no need to lock it again (in fact, this would cause a -deadlock). So use __cpufreq_driver_target only in these cases. In all -other cases (for example, when there's a "daemonized" function that -wakes up every second), use cpufreq_driver_target to take policy->rwsem -before the command is passed to the cpufreq driver. - -4. References -============= - -[1] Per-entity load tracking: https://lwn.net/Articles/531853/ -[2] Improvements in CPU frequency management: https://lwn.net/Articles/682391/ - diff --git a/Documentation/cpu-freq/index.txt b/Documentation/cpu-freq/index.txt index ef1d39247b05..03a7cee6ac73 100644 --- a/Documentation/cpu-freq/index.txt +++ b/Documentation/cpu-freq/index.txt @@ -21,8 +21,6 @@ Documents in this directory: amd-powernow.txt - AMD powernow driver specific file. -boost.txt - Frequency boosting support. - core.txt - General description of the CPUFreq core and of CPUFreq notifiers. @@ -32,17 +30,12 @@ cpufreq-nforce2.txt - nVidia nForce2 platform specific file. cpufreq-stats.txt - General description of sysfs cpufreq stats. -governors.txt - What are cpufreq governors and how to - implement them? - index.txt - File index, Mailing list and Links (this document) intel-pstate.txt - Intel pstate cpufreq driver specific file. pcc-cpufreq.txt - PCC cpufreq driver specific file. -user-guide.txt - User Guide to CPUFreq - Mailing List ------------ diff --git a/Documentation/cpu-freq/user-guide.txt b/Documentation/cpu-freq/user-guide.txt deleted file mode 100644 index 391da64e9492..000000000000 --- a/Documentation/cpu-freq/user-guide.txt +++ /dev/null @@ -1,228 +0,0 @@ - CPU frequency and voltage scaling code in the Linux(TM) kernel - - - L i n u x C P U F r e q - - U S E R G U I D E - - - Dominik Brodowski <linux@brodo.de> - - - - Clock scaling allows you to change the clock speed of the CPUs on the - fly. This is a nice method to save battery power, because the lower - the clock speed, the less power the CPU consumes. - - -Contents: ---------- -1. Supported Architectures and Processors -1.1 ARM and ARM64 -1.2 x86 -1.3 sparc64 -1.4 ppc -1.5 SuperH -1.6 Blackfin - -2. "Policy" / "Governor"? -2.1 Policy -2.2 Governor - -3. How to change the CPU cpufreq policy and/or speed -3.1 Preferred interface: sysfs - - - -1. Supported Architectures and Processors -========================================= - -1.1 ARM and ARM64 ------------------ - -Almost all ARM and ARM64 platforms support CPU frequency scaling. - -1.2 x86 -------- - -The following processors for the x86 architecture are supported by cpufreq: - -AMD Elan - SC400, SC410 -AMD mobile K6-2+ -AMD mobile K6-3+ -AMD mobile Duron -AMD mobile Athlon -AMD Opteron -AMD Athlon 64 -Cyrix Media GXm -Intel mobile PIII and Intel mobile PIII-M on certain chipsets -Intel Pentium 4, Intel Xeon -Intel Pentium M (Centrino) -National Semiconductors Geode GX -Transmeta Crusoe -Transmeta Efficeon -VIA Cyrix 3 / C3 -various processors on some ACPI 2.0-compatible systems [*] -And many more - -[*] Only if "ACPI Processor Performance States" are available -to the ACPI<->BIOS interface. - - -1.3 sparc64 ------------ - -The following processors for the sparc64 architecture are supported by -cpufreq: - -UltraSPARC-III - - -1.4 ppc -------- - -Several "PowerBook" and "iBook2" notebooks are supported. -The following POWER processors are supported in powernv mode: -POWER8 -POWER9 - -1.5 SuperH ----------- - -All SuperH processors supporting rate rounding through the clock -framework are supported by cpufreq. - -1.6 Blackfin ------------- - -The following Blackfin processors are supported by cpufreq: - -BF522, BF523, BF524, BF525, BF526, BF527, Rev 0.1 or higher -BF531, BF532, BF533, Rev 0.3 or higher -BF534, BF536, BF537, Rev 0.2 or higher -BF561, Rev 0.3 or higher -BF542, BF544, BF547, BF548, BF549, Rev 0.1 or higher - - -2. "Policy" / "Governor" ? -========================== - -Some CPU frequency scaling-capable processor switch between various -frequencies and operating voltages "on the fly" without any kernel or -user involvement. This guarantees very fast switching to a frequency -which is high enough to serve the user's needs, but low enough to save -power. - - -2.1 Policy ----------- - -On these systems, all you can do is select the lower and upper -frequency limit as well as whether you want more aggressive -power-saving or more instantly available processing power. - - -2.2 Governor ------------- - -On all other cpufreq implementations, these boundaries still need to -be set. Then, a "governor" must be selected. Such a "governor" decides -what speed the processor shall run within the boundaries. One such -"governor" is the "userspace" governor. This one allows the user - or -a yet-to-implement userspace program - to decide what specific speed -the processor shall run at. - - -3. How to change the CPU cpufreq policy and/or speed -==================================================== - -3.1 Preferred Interface: sysfs ------------------------------- - -The preferred interface is located in the sysfs filesystem. If you -mounted it at /sys, the cpufreq interface is located in a subdirectory -"cpufreq" within the cpu-device directory -(e.g. /sys/devices/system/cpu/cpu0/cpufreq/ for the first CPU). - -affected_cpus : List of Online CPUs that require software - coordination of frequency. - -cpuinfo_cur_freq : Current frequency of the CPU as obtained from - the hardware, in KHz. This is the frequency - the CPU actually runs at. - -cpuinfo_min_freq : this file shows the minimum operating - frequency the processor can run at(in kHz) - -cpuinfo_max_freq : this file shows the maximum operating - frequency the processor can run at(in kHz) - -cpuinfo_transition_latency The time it takes on this CPU to - switch between two frequencies in nano - seconds. If unknown or known to be - that high that the driver does not - work with the ondemand governor, -1 - (CPUFREQ_ETERNAL) will be returned. - Using this information can be useful - to choose an appropriate polling - frequency for a kernel governor or - userspace daemon. Make sure to not - switch the frequency too often - resulting in performance loss. - -related_cpus : List of Online + Offline CPUs that need software - coordination of frequency. - -scaling_available_frequencies : List of available frequencies, in KHz. - -scaling_available_governors : this file shows the CPUfreq governors - available in this kernel. You can see the - currently activated governor in - -scaling_cur_freq : Current frequency of the CPU as determined by - the governor and cpufreq core, in KHz. This is - the frequency the kernel thinks the CPU runs - at. - -scaling_driver : this file shows what cpufreq driver is - used to set the frequency on this CPU - -scaling_governor, and by "echoing" the name of another - governor you can change it. Please note - that some governors won't load - they only - work on some specific architectures or - processors. - -scaling_min_freq and -scaling_max_freq show the current "policy limits" (in - kHz). By echoing new values into these - files, you can change these limits. - NOTE: when setting a policy you need to - first set scaling_max_freq, then - scaling_min_freq. - -scaling_setspeed This can be read to get the currently programmed - value by the governor. This can be written to - change the current frequency for a group of - CPUs, represented by a policy. This is supported - currently only by the userspace governor. - -bios_limit : If the BIOS tells the OS to limit a CPU to - lower frequencies, the user can read out the - maximum available frequency from this file. - This typically can happen through (often not - intended) BIOS settings, restrictions - triggered through a service processor or other - BIOS/HW based implementations. - This does not cover thermal ACPI limitations - which can be detected through the generic - thermal driver. - -If you have selected the "userspace" governor which allows you to -set the CPU operating frequency to a specific value, you can read out -the current frequency in - -scaling_setspeed. By "echoing" a new frequency into this - you can change the speed of the CPU, - but only within the limits of - scaling_min_freq and scaling_max_freq. diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt index f722f227a73b..127c9d8c2174 100644 --- a/Documentation/cputopology.txt +++ b/Documentation/cputopology.txt @@ -100,7 +100,7 @@ not defined by include/asm-XXX/topology.h: For architectures that don't support books (CONFIG_SCHED_BOOK) there are no default definitions for topology_book_id() and topology_book_cpumask(). -For architectures that don't support drawes (CONFIG_SCHED_DRAWER) there are +For architectures that don't support drawers (CONFIG_SCHED_DRAWER) there are no default definitions for topology_drawer_id() and topology_drawer_cpumask(). Additionally, CPU topology information is provided under diff --git a/Documentation/crypto/api-samples.rst b/Documentation/crypto/api-samples.rst index 0a10819f6107..d021fd96a76d 100644 --- a/Documentation/crypto/api-samples.rst +++ b/Documentation/crypto/api-samples.rst @@ -155,9 +155,9 @@ Code Example For Use of Operational State Memory With SHASH char ctx[]; }; - static struct sdescinit_sdesc(struct crypto_shash *alg) + static struct sdesc init_sdesc(struct crypto_shash *alg) { - struct sdescsdesc; + struct sdesc sdesc; int size; size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); @@ -172,7 +172,7 @@ Code Example For Use of Operational State Memory With SHASH static int calc_hash(struct crypto_shashalg, const unsigned chardata, unsigned int datalen, unsigned chardigest) { - struct sdescsdesc; + struct sdesc sdesc; int ret; sdesc = init_sdesc(alg); diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.txt index 2b7816dea370..5ad6480e3fb9 100644 --- a/Documentation/crypto/asymmetric-keys.txt +++ b/Documentation/crypto/asymmetric-keys.txt @@ -311,3 +311,54 @@ Functions are provided to register and unregister parsers: Parsers may not have the same name. The names are otherwise only used for displaying in debugging messages. + + +========================= +KEYRING LINK RESTRICTIONS +========================= + +Keyrings created from userspace using add_key can be configured to check the +signature of the key being linked. + +Several restriction methods are available: + + (1) Restrict using the kernel builtin trusted keyring + + - Option string used with KEYCTL_RESTRICT_KEYRING: + - "builtin_trusted" + + The kernel builtin trusted keyring will be searched for the signing + key. The ca_keys kernel parameter also affects which keys are used for + signature verification. + + (2) Restrict using the kernel builtin and secondary trusted keyrings + + - Option string used with KEYCTL_RESTRICT_KEYRING: + - "builtin_and_secondary_trusted" + + The kernel builtin and secondary trusted keyrings will be searched for the + signing key. The ca_keys kernel parameter also affects which keys are used + for signature verification. + + (3) Restrict using a separate key or keyring + + - Option string used with KEYCTL_RESTRICT_KEYRING: + - "key_or_keyring:<key or keyring serial number>[:chain]" + + Whenever a key link is requested, the link will only succeed if the key + being linked is signed by one of the designated keys. This key may be + specified directly by providing a serial number for one asymmetric key, or + a group of keys may be searched for the signing key by providing the + serial number for a keyring. + + When the "chain" option is provided at the end of the string, the keys + within the destination keyring will also be searched for signing keys. + This allows for verification of certificate chains by adding each + cert in order (starting closest to the root) to one keyring. + +In all of these cases, if the signing key is found the signature of the key to +be linked will be verified using the signing key. The requested key is added +to the keyring only if the signature is successfully verified. -ENOKEY is +returned if the parent certificate could not be found, or -EKEYREJECTED is +returned if the signature check fails or the key is blacklisted. Other errors +may be returned if the signature check could not be performed. diff --git a/Documentation/debugging-via-ohci1394.txt b/Documentation/debugging-via-ohci1394.txt index 03703afc4d30..9ff026d22b75 100644 --- a/Documentation/debugging-via-ohci1394.txt +++ b/Documentation/debugging-via-ohci1394.txt @@ -100,8 +100,8 @@ Step-by-step instructions for using firescope with early OHCI initialization: CardBus and even some Express cards which are fully compliant to OHCI-1394 specification are available. If it requires no driver for Windows operating systems, it most likely is. Only specialized shops have cards which are not - compliant, they are based on TI PCILynx chips and require drivers for Win- - dows operating systems. + compliant, they are based on TI PCILynx chips and require drivers for Windows + operating systems. The mentioned kernel log message contains the string "physUB" if the controller implements a writable Physical Upper Bound register. This is diff --git a/Documentation/device-mapper/cache.txt b/Documentation/device-mapper/cache.txt index f228604ddbcd..cdfd0feb294e 100644 --- a/Documentation/device-mapper/cache.txt +++ b/Documentation/device-mapper/cache.txt @@ -290,7 +290,7 @@ message, which takes an arbitrary number of cblock ranges. Each cblock range's end value is "one past the end", meaning 5-10 expresses a range of values from 5 to 9. Each cblock must be expressed as a decimal value, in the future a variant message that takes cblock ranges -expressed in hexidecimal may be needed to better support efficient +expressed in hexadecimal may be needed to better support efficient invalidation of larger caches. The cache must be in passthrough mode when invalidate_cblocks is used. diff --git a/Documentation/device-mapper/dm-crypt.txt b/Documentation/device-mapper/dm-crypt.txt index ff1f87bf26e8..3b3e1de21c9c 100644 --- a/Documentation/device-mapper/dm-crypt.txt +++ b/Documentation/device-mapper/dm-crypt.txt @@ -11,14 +11,31 @@ Parameters: <cipher> <key> <iv_offset> <device path> \ <offset> [<#opt_params> <opt_params>] <cipher> - Encryption cipher and an optional IV generation mode. - (In format cipher[:keycount]-chainmode-ivmode[:ivopts]). + Encryption cipher, encryption mode and Initial Vector (IV) generator. + + The cipher specifications format is: + cipher[:keycount]-chainmode-ivmode[:ivopts] Examples: - des aes-cbc-essiv:sha256 - twofish-ecb + aes-xts-plain64 + serpent-xts-plain64 + + Cipher format also supports direct specification with kernel crypt API + format (selected by capi: prefix). The IV specification is the same + as for the first format type. + This format is mainly used for specification of authenticated modes. - /proc/crypto contains supported crypto modes + The crypto API cipher specifications format is: + capi:cipher_api_spec-ivmode[:ivopts] + Examples: + capi:cbc(aes)-essiv:sha256 + capi:xts(aes)-plain64 + Examples of authenticated modes: + capi:gcm(aes)-random + capi:authenc(hmac(sha256),xts(aes))-random + capi:rfc7539(chacha20,poly1305)-random + + The /proc/crypto contains a list of curently loaded crypto modes. <key> Key used for encryption. It is encoded either as a hexadecimal number @@ -93,6 +110,32 @@ submit_from_crypt_cpus thread because it benefits CFQ to have writes submitted using the same context. +integrity:<bytes>:<type> + The device requires additional <bytes> metadata per-sector stored + in per-bio integrity structure. This metadata must by provided + by underlying dm-integrity target. + + The <type> can be "none" if metadata is used only for persistent IV. + + For Authenticated Encryption with Additional Data (AEAD) + the <type> is "aead". An AEAD mode additionally calculates and verifies + integrity for the encrypted device. The additional space is then + used for storing authentication tag (and persistent IV if needed). + +sector_size:<bytes> + Use <bytes> as the encryption unit instead of 512 bytes sectors. + This option can be in range 512 - 4096 bytes and must be power of two. + Virtual device will announce this size as a minimal IO and logical sector. + +iv_large_sectors + IV generators will use sector number counted in <sector_size> units + instead of default 512 bytes sectors. + + For example, if <sector_size> is 4096 bytes, plain64 IV for the second + sector will be 8 (without flag) and 1 if iv_large_sectors is present. + The <iv_offset> must be multiple of <sector_size> (in 512 bytes units) + if this flag is specified. + Example scripts =============== LUKS (Linux Unified Key Setup) is now the preferred way to set up disk diff --git a/Documentation/device-mapper/dm-integrity.txt b/Documentation/device-mapper/dm-integrity.txt new file mode 100644 index 000000000000..f33e3ade7a09 --- /dev/null +++ b/Documentation/device-mapper/dm-integrity.txt @@ -0,0 +1,199 @@ +The dm-integrity target emulates a block device that has additional +per-sector tags that can be used for storing integrity information. + +A general problem with storing integrity tags with every sector is that +writing the sector and the integrity tag must be atomic - i.e. in case of +crash, either both sector and integrity tag or none of them is written. + +To guarantee write atomicity, the dm-integrity target uses journal, it +writes sector data and integrity tags into a journal, commits the journal +and then copies the data and integrity tags to their respective location. + +The dm-integrity target can be used with the dm-crypt target - in this +situation the dm-crypt target creates the integrity data and passes them +to the dm-integrity target via bio_integrity_payload attached to the bio. +In this mode, the dm-crypt and dm-integrity targets provide authenticated +disk encryption - if the attacker modifies the encrypted device, an I/O +error is returned instead of random data. + +The dm-integrity target can also be used as a standalone target, in this +mode it calculates and verifies the integrity tag internally. In this +mode, the dm-integrity target can be used to detect silent data +corruption on the disk or in the I/O path. + + +When loading the target for the first time, the kernel driver will format +the device. But it will only format the device if the superblock contains +zeroes. If the superblock is neither valid nor zeroed, the dm-integrity +target can't be loaded. + +To use the target for the first time: +1. overwrite the superblock with zeroes +2. load the dm-integrity target with one-sector size, the kernel driver + will format the device +3. unload the dm-integrity target +4. read the "provided_data_sectors" value from the superblock +5. load the dm-integrity target with the the target size + "provided_data_sectors" +6. if you want to use dm-integrity with dm-crypt, load the dm-crypt target + with the size "provided_data_sectors" + + +Target arguments: + +1. the underlying block device + +2. the number of reserved sector at the beginning of the device - the + dm-integrity won't read of write these sectors + +3. the size of the integrity tag (if "-" is used, the size is taken from + the internal-hash algorithm) + +4. mode: + D - direct writes (without journal) - in this mode, journaling is + not used and data sectors and integrity tags are written + separately. In case of crash, it is possible that the data + and integrity tag doesn't match. + J - journaled writes - data and integrity tags are written to the + journal and atomicity is guaranteed. In case of crash, + either both data and tag or none of them are written. The + journaled mode degrades write throughput twice because the + data have to be written twice. + R - recovery mode - in this mode, journal is not replayed, + checksums are not checked and writes to the device are not + allowed. This mode is useful for data recovery if the + device cannot be activated in any of the other standard + modes. + +5. the number of additional arguments + +Additional arguments: + +journal_sectors:number + The size of journal, this argument is used only if formatting the + device. If the device is already formatted, the value from the + superblock is used. + +interleave_sectors:number + The number of interleaved sectors. This values is rounded down to + a power of two. If the device is already formatted, the value from + the superblock is used. + +buffer_sectors:number + The number of sectors in one buffer. The value is rounded down to + a power of two. + + The tag area is accessed using buffers, the buffer size is + configurable. The large buffer size means that the I/O size will + be larger, but there could be less I/Os issued. + +journal_watermark:number + The journal watermark in percents. When the size of the journal + exceeds this watermark, the thread that flushes the journal will + be started. + +commit_time:number + Commit time in milliseconds. When this time passes, the journal is + written. The journal is also written immediatelly if the FLUSH + request is received. + +internal_hash:algorithm(:key) (the key is optional) + Use internal hash or crc. + When this argument is used, the dm-integrity target won't accept + integrity tags from the upper target, but it will automatically + generate and verify the integrity tags. + + You can use a crc algorithm (such as crc32), then integrity target + will protect the data against accidental corruption. + You can also use a hmac algorithm (for example + "hmac(sha256):0123456789abcdef"), in this mode it will provide + cryptographic authentication of the data without encryption. + + When this argument is not used, the integrity tags are accepted + from an upper layer target, such as dm-crypt. The upper layer + target should check the validity of the integrity tags. + +journal_crypt:algorithm(:key) (the key is optional) + Encrypt the journal using given algorithm to make sure that the + attacker can't read the journal. You can use a block cipher here + (such as "cbc(aes)") or a stream cipher (for example "chacha20", + "salsa20", "ctr(aes)" or "ecb(arc4)"). + + The journal contains history of last writes to the block device, + an attacker reading the journal could see the last sector nubmers + that were written. From the sector numbers, the attacker can infer + the size of files that were written. To protect against this + situation, you can encrypt the journal. + +journal_mac:algorithm(:key) (the key is optional) + Protect sector numbers in the journal from accidental or malicious + modification. To protect against accidental modification, use a + crc algorithm, to protect against malicious modification, use a + hmac algorithm with a key. + + This option is not needed when using internal-hash because in this + mode, the integrity of journal entries is checked when replaying + the journal. Thus, modified sector number would be detected at + this stage. + +block_size:number + The size of a data block in bytes. The larger the block size the + less overhead there is for per-block integrity metadata. + Supported values are 512, 1024, 2048 and 4096 bytes. If not + specified the default block size is 512 bytes. + +The journal mode (D/J), buffer_sectors, journal_watermark, commit_time can +be changed when reloading the target (load an inactive table and swap the +tables with suspend and resume). The other arguments should not be changed +when reloading the target because the layout of disk data depend on them +and the reloaded target would be non-functional. + + +The layout of the formatted block device: +* reserved sectors (they are not used by this target, they can be used for + storing LUKS metadata or for other purpose), the size of the reserved + area is specified in the target arguments +* superblock (4kiB) + * magic string - identifies that the device was formatted + * version + * log2(interleave sectors) + * integrity tag size + * the number of journal sections + * provided data sectors - the number of sectors that this target + provides (i.e. the size of the device minus the size of all + metadata and padding). The user of this target should not send + bios that access data beyond the "provided data sectors" limit. + * flags - a flag is set if journal_mac is used +* journal + The journal is divided into sections, each section contains: + * metadata area (4kiB), it contains journal entries + every journal entry contains: + * logical sector (specifies where the data and tag should + be written) + * last 8 bytes of data + * integrity tag (the size is specified in the superblock) + every metadata sector ends with + * mac (8-bytes), all the macs in 8 metadata sectors form a + 64-byte value. It is used to store hmac of sector + numbers in the journal section, to protect against a + possibility that the attacker tampers with sector + numbers in the journal. + * commit id + * data area (the size is variable; it depends on how many journal + entries fit into the metadata area) + every sector in the data area contains: + * data (504 bytes of data, the last 8 bytes are stored in + the journal entry) + * commit id + To test if the whole journal section was written correctly, every + 512-byte sector of the journal ends with 8-byte commit id. If the + commit id matches on all sectors in a journal section, then it is + assumed that the section was written correctly. If the commit id + doesn't match, the section was written partially and it should not + be replayed. +* one or more runs of interleaved tags and data. Each run contains: + * tag area - it contains integrity tags. There is one tag for each + sector in the data area + * data area - it contains data sectors. The number of data sectors + in one run must be a power of two. log2 of this value is stored + in the superblock. diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index cd2cb2fc85ea..7e06e65586d4 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -170,6 +170,13 @@ The target is named "raid" and it accepts the following parameters: Takeover/reshape is not possible with a raid4/5/6 journal device; it has to be deconfigured before requesting these. + [journal_mode <mode>] + This option sets the caching mode on journaled raid4/5/6 raid sets + (see 'journal_dev <dev>' above) to 'writethrough' or 'writeback'. + If 'writeback' is selected the journal device has to be resilient + and must not suffer from the 'write hole' problem itself (e.g. use + raid1 or raid10) to avoid a single point of failure. + <#raid_devs>: The number of devices composing the array. Each device consists of two entries. The first is the device containing the metadata (if any); the second is the one containing the @@ -254,7 +261,8 @@ recovery. Here is a fuller description of the individual fields: <data_offset> The current data offset to the start of the user data on each component device of a raid set (see the respective raid parameter to support out-of-place reshaping). - <journal_char> 'A' - active raid4/5/6 journal device. + <journal_char> 'A' - active write-through journal device. + 'a' - active write-back journal device. 'D' - dead journal device. '-' - no journal device. @@ -331,3 +339,7 @@ Version History 'D' on the status line. If '- -' is passed into the constructor, emit '- -' on the table line and '-' as the status line health character. 1.10.0 Add support for raid4/5/6 journal device +1.10.1 Fix data corruption on reshape request +1.11.0 Fix table line argument order + (wrong raid10_copies/raid10_format sequence) +1.11.1 Add raid4/5/6 journal write-back support via journal_mode option diff --git a/Documentation/devicetree/bindings/arm/l2c2x0.txt b/Documentation/devicetree/bindings/arm/l2c2x0.txt index 917199f17965..d9650c1788f4 100644 --- a/Documentation/devicetree/bindings/arm/l2c2x0.txt +++ b/Documentation/devicetree/bindings/arm/l2c2x0.txt @@ -90,6 +90,9 @@ Optional properties: - arm,standby-mode: L2 standby mode enable. Value <0> (forcibly disable), <1> (forcibly enable), property absent (OS specific behavior, preferably retain firmware settings) +- arm,early-bresp-disable : Disable the CA9 optimization Early BRESP (PL310) +- arm,full-line-zero-disable : Disable the CA9 optimization Full line of zero + write (PL310) Example: diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt index 30c546900b60..07dbb358182c 100644 --- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt +++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt @@ -45,7 +45,7 @@ The following clocks are available: - 1 15 SATA - 1 16 SATA USB - 1 17 Main - - 1 18 SD/MMC + - 1 18 SD/MMC/GOP - 1 21 Slow IO (SPI, NOR, BootROM, I2C, UART) - 1 22 USB3H0 - 1 23 USB3H1 @@ -65,7 +65,7 @@ Required properties: "cpm-audio", "cpm-communit", "cpm-nand", "cpm-ppv2", "cpm-sdio", "cpm-mg-domain", "cpm-mg-core", "cpm-xor1", "cpm-xor0", "cpm-gop-dp", "none", "cpm-pcie_x10", "cpm-pcie_x11", "cpm-pcie_x4", "cpm-pcie-xor", "cpm-sata", - "cpm-sata-usb", "cpm-main", "cpm-sd-mmc", "none", "none", "cpm-slow-io", + "cpm-sata-usb", "cpm-main", "cpm-sd-mmc-gop", "none", "none", "cpm-slow-io", "cpm-usb3h0", "cpm-usb3h1", "cpm-usb3dev", "cpm-eip150", "cpm-eip197"; Example: @@ -78,6 +78,6 @@ Example: gate-clock-output-names = "cpm-audio", "cpm-communit", "cpm-nand", "cpm-ppv2", "cpm-sdio", "cpm-mg-domain", "cpm-mg-core", "cpm-xor1", "cpm-xor0", "cpm-gop-dp", "none", "cpm-pcie_x10", "cpm-pcie_x11", "cpm-pcie_x4", "cpm-pcie-xor", "cpm-sata", - "cpm-sata-usb", "cpm-main", "cpm-sd-mmc", "none", "none", "cpm-slow-io", + "cpm-sata-usb", "cpm-main", "cpm-sd-mmc-gop", "none", "none", "cpm-slow-io", "cpm-usb3h0", "cpm-usb3h1", "cpm-usb3dev", "cpm-eip150", "cpm-eip197"; }; diff --git a/Documentation/devicetree/bindings/arm/sprd.txt b/Documentation/devicetree/bindings/arm/sprd.txt index 31a629dc75b8..3df034b13e28 100644 --- a/Documentation/devicetree/bindings/arm/sprd.txt +++ b/Documentation/devicetree/bindings/arm/sprd.txt @@ -1,11 +1,14 @@ Spreadtrum SoC Platforms Device Tree Bindings ---------------------------------------------------- -Sharkl64 is a Spreadtrum's SoC Platform which is based -on ARM 64-bit processor. +SC9836 openphone Board +Required root node properties: + - compatible = "sprd,sc9836-openphone", "sprd,sc9836"; -SC9836 openphone board with SC9836 SoC based on the -Sharkl64 Platform shall have the following properties. +SC9860 SoC +Required root node properties: + - compatible = "sprd,sc9860" +SP9860G 3GFHD Board Required root node properties: - - compatible = "sprd,sc9836-openphone", "sprd,sc9836"; + - compatible = "sprd,sp9860g-1h10", "sprd,sc9860"; diff --git a/Documentation/devicetree/bindings/ata/ahci-dm816.txt b/Documentation/devicetree/bindings/ata/ahci-dm816.txt new file mode 100644 index 000000000000..f8c535f3541f --- /dev/null +++ b/Documentation/devicetree/bindings/ata/ahci-dm816.txt @@ -0,0 +1,21 @@ +Device tree binding for the TI DM816 AHCI SATA Controller +--------------------------------------------------------- + +Required properties: + - compatible: must be "ti,dm816-ahci" + - reg: physical base address and size of the register region used by + the controller (as defined by the AHCI 1.1 standard) + - interrupts: interrupt specifier (refer to the interrupt binding) + - clocks: list of phandle and clock specifier pairs (or only + phandles for clock providers with '0' defined for + #clock-cells); two clocks must be specified: the functional + clock and an external reference clock + +Example: + + sata: sata@4a140000 { + compatible = "ti,dm816-ahci"; + reg = <0x4a140000 0x10000>; + interrupts = <16>; + clocks = <&sysclk5_ck>, <&sata_refclk>; + }; diff --git a/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.txt b/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.txt new file mode 100644 index 000000000000..2aa24b889923 --- /dev/null +++ b/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.txt @@ -0,0 +1,45 @@ +DT bindings for the Hitachi HD44780 Character LCD Controller + +The Hitachi HD44780 Character LCD Controller is commonly used on character LCDs +that can display one or more lines of text. It exposes an M6800 bus interface, +which can be used in either 4-bit or 8-bit mode. + +Required properties: + - compatible: Must contain "hit,hd44780", + - data-gpios: Must contain an array of either 4 or 8 GPIO specifiers, + referring to the GPIO pins connected to the data signal lines DB0-DB7 + (8-bit mode) or DB4-DB7 (4-bit mode) of the LCD Controller's bus interface, + - enable-gpios: Must contain a GPIO specifier, referring to the GPIO pin + connected to the "E" (Enable) signal line of the LCD Controller's bus + interface, + - rs-gpios: Must contain a GPIO specifier, referring to the GPIO pin + connected to the "RS" (Register Select) signal line of the LCD Controller's + bus interface, + - display-height-chars: Height of the display, in character cells, + - display-width-chars: Width of the display, in character cells. + +Optional properties: + - rw-gpios: Must contain a GPIO specifier, referring to the GPIO pin + connected to the "RW" (Read/Write) signal line of the LCD Controller's bus + interface, + - backlight-gpios: Must contain a GPIO specifier, referring to the GPIO pin + used for enabling the LCD's backlight, + - internal-buffer-width: Internal buffer width (default is 40 for displays + with 1 or 2 lines, and display-width-chars for displays with more than 2 + lines). + +Example: + + auxdisplay { + compatible = "hit,hd44780"; + + data-gpios = <&hc595 0 GPIO_ACTIVE_HIGH>, + <&hc595 1 GPIO_ACTIVE_HIGH>, + <&hc595 2 GPIO_ACTIVE_HIGH>, + <&hc595 3 GPIO_ACTIVE_HIGH>; + enable-gpios = <&hc595 4 GPIO_ACTIVE_HIGH>; + rs-gpios = <&hc595 5 GPIO_ACTIVE_HIGH>; + + display-height-chars = <2>; + display-width-chars = <16>; + }; diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt index 6ae9d82d4c37..b5e39af4ddc0 100644 --- a/Documentation/devicetree/bindings/chosen.txt +++ b/Documentation/devicetree/bindings/chosen.txt @@ -52,3 +52,48 @@ This property is set (currently only on PowerPC, and only needed on book3e) by some versions of kexec-tools to tell the new kernel that it is being booted by kexec, as the booting environment may differ (e.g. a different secondary CPU release mechanism) + +linux,usable-memory-range +------------------------- + +This property (arm64 only) holds a base address and size, describing a +limited region in which memory may be considered available for use by +the kernel. Memory outside of this range is not available for use. + +This property describes a limitation: memory within this range is only +valid when also described through another mechanism that the kernel +would otherwise use to determine available memory (e.g. memory nodes +or the EFI memory map). Valid memory may be sparse within the range. +e.g. + +/ { + chosen { + linux,usable-memory-range = <0x9 0xf0000000 0x0 0x10000000>; + }; +}; + +The main usage is for crash dump kernel to identify its own usable +memory and exclude, at its boot time, any other memory areas that are +part of the panicked kernel's memory. + +While this property does not represent a real hardware, the address +and the size are expressed in #address-cells and #size-cells, +respectively, of the root node. + +linux,elfcorehdr +---------------- + +This property (currently used only on arm64) holds the memory range, +the address and the size, of the elf core header which mainly describes +the panicked kernel's memory layout as PT_LOAD segments of elf format. +e.g. + +/ { + chosen { + linux,elfcorehdr = <0x9 0xfffff000 0x0 0x800>; + }; +}; + +While this property does not represent a real hardware, the address +and the size are expressed in #address-cells and #size-cells, +respectively, of the root node. diff --git a/Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt b/Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt index a88f1f05fbd6..4c0807f28cfa 100644 --- a/Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt +++ b/Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt @@ -5,6 +5,7 @@ reading the gpio latch register. This node must be a subnode of the node exposing the register address of the GPIO block where the gpio latch is located. +See Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt Required properties: - compatible : shall be one of the following: @@ -16,9 +17,9 @@ Optional properties: output names ("xtal") Example: -gpio1: gpio@13800 { - compatible = "marvell,armada-3700-gpio", "syscon", "simple-mfd"; - reg = <0x13800 0x1000>; +pinctrl_nb: pinctrl-nb@13800 { + compatible = "armada3710-nb-pinctrl", "syscon", "simple-mfd"; + reg = <0x13800 0x100>, <0x13C00 0x20>; xtalclk: xtal-clk { compatible = "marvell,armada-3700-xtal-clock"; diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-crc.txt b/Documentation/devicetree/bindings/crypto/st,stm32-crc.txt new file mode 100644 index 000000000000..3ba92a5e9b36 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/st,stm32-crc.txt @@ -0,0 +1,16 @@ +* STMicroelectronics STM32 CRC + +Required properties: +- compatible: Should be "st,stm32f7-crc". +- reg: The address and length of the peripheral registers space +- clocks: The input clock of the CRC instance + +Optional properties: none + +Example: + +crc: crc@40023000 { + compatible = "st,stm32f7-crc"; + reg = <0x40023000 0x400>; + clocks = <&rcc 0 12>; +}; diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt new file mode 100644 index 000000000000..7f040edc16fe --- /dev/null +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt @@ -0,0 +1,111 @@ +Amlogic specific extensions to the Synopsys Designware HDMI Controller +====================================================================== + +The Amlogic Meson Synopsys Designware Integration is composed of : +- A Synopsys DesignWare HDMI Controller IP +- A TOP control block controlling the Clocks and PHY +- A custom HDMI PHY in order to convert video to TMDS signal + ___________________________________ +| HDMI TOP |<= HPD +|___________________________________| +| | | +| Synopsys HDMI | HDMI PHY |=> TMDS +| Controller |________________| +|___________________________________|<=> DDC + +The HDMI TOP block only supports HPD sensing. +The Synopsys HDMI Controller interrupt is routed through the +TOP Block interrupt. +Communication to the TOP Block and the Synopsys HDMI Controller is done +via a pair of dedicated addr+read/write registers. +The HDMI PHY is configured by registers in the HHI register block. + +Pixel data arrives in 4:4:4 format from the VENC block and the VPU HDMI mux +selects either the ENCI encoder for the 576i or 480i formats or the ENCP +encoder for all the other formats including interlaced HD formats. + +The VENC uses a DVI encoder on top of the ENCI or ENCP encoders to generate +DVI timings for the HDMI controller. + +Amlogic Meson GXBB, GXL and GXM SoCs families embeds the Synopsys DesignWare +HDMI TX IP version 2.01a with HDCP and I2C & S/PDIF +audio source interfaces. + +Required properties: +- compatible: value should be different for each SoC family as : + - GXBB (S905) : "amlogic,meson-gxbb-dw-hdmi" + - GXL (S905X, S905D) : "amlogic,meson-gxl-dw-hdmi" + - GXM (S912) : "amlogic,meson-gxm-dw-hdmi" + followed by the common "amlogic,meson-gx-dw-hdmi" +- reg: Physical base address and length of the controller's registers. +- interrupts: The HDMI interrupt number +- clocks, clock-names : must have the phandles to the HDMI iahb and isfr clocks, + and the Amlogic Meson venci clocks as described in + Documentation/devicetree/bindings/clock/clock-bindings.txt, + the clocks are soc specific, the clock-names should be "iahb", "isfr", "venci" +- resets, resets-names: must have the phandles to the HDMI apb, glue and phy + resets as described in : + Documentation/devicetree/bindings/reset/reset.txt, + the reset-names should be "hdmitx_apb", "hdmitx", "hdmitx_phy" + +Required nodes: + +The connections to the HDMI ports are modeled using the OF graph +bindings specified in Documentation/devicetree/bindings/graph.txt. + +The following table lists for each supported model the port number +corresponding to each HDMI output and input. + + Port 0 Port 1 +----------------------------------------- + S905 (GXBB) VENC Input TMDS Output + S905X (GXL) VENC Input TMDS Output + S905D (GXL) VENC Input TMDS Output + S912 (GXM) VENC Input TMDS Output + +Example: + +hdmi-connector { + compatible = "hdmi-connector"; + type = "a"; + + port { + hdmi_connector_in: endpoint { + remote-endpoint = <&hdmi_tx_tmds_out>; + }; + }; +}; + +hdmi_tx: hdmi-tx@c883a000 { + compatible = "amlogic,meson-gxbb-dw-hdmi", "amlogic,meson-gx-dw-hdmi"; + reg = <0x0 0xc883a000 0x0 0x1c>; + interrupts = <GIC_SPI 57 IRQ_TYPE_EDGE_RISING>; + resets = <&reset RESET_HDMITX_CAPB3>, + <&reset RESET_HDMI_SYSTEM_RESET>, + <&reset RESET_HDMI_TX>; + reset-names = "hdmitx_apb", "hdmitx", "hdmitx_phy"; + clocks = <&clkc CLKID_HDMI_PCLK>, + <&clkc CLKID_CLK81>, + <&clkc CLKID_GCLK_VENCI_INT0>; + clock-names = "isfr", "iahb", "venci"; + #address-cells = <1>; + #size-cells = <0>; + + /* VPU VENC Input */ + hdmi_tx_venc_port: port@0 { + reg = <0>; + + hdmi_tx_in: endpoint { + remote-endpoint = <&hdmi_tx_out>; + }; + }; + + /* TMDS Output */ + hdmi_tx_tmds_port: port@1 { + reg = <1>; + + hdmi_tx_tmds_out: endpoint { + remote-endpoint = <&hdmi_connector_in>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt index ebc1a914bda3..ec94468b35be 100644 --- a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt +++ b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt @@ -1,7 +1,7 @@ Device-Tree bindings for Atmel's HLCDC (High LCD Controller) DRM driver The Atmel HLCDC Display Controller is subdevice of the HLCDC MFD device. -See ../mfd/atmel-hlcdc.txt for more details. +See ../../mfd/atmel-hlcdc.txt for more details. Required properties: - compatible: value should be "atmel,hlcdc-display-controller" diff --git a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt index 34c7fddcea39..ca02d3e4db91 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt +++ b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt @@ -34,6 +34,9 @@ Optional properties for HDMI: - hpd-gpios: The GPIO pin for HDMI hotplug detect (if it doesn't appear as an interrupt/status bit in the HDMI controller itself). See bindings/pinctrl/brcm,bcm2835-gpio.txt +- dmas: Should contain one entry pointing to the DMA channel used to + transfer audio data +- dma-names: Should contain "audio-rx" Required properties for DPI: - compatible: Should be "brcm,bcm2835-dpi" diff --git a/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt b/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt new file mode 100644 index 000000000000..fd39ad34c383 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt @@ -0,0 +1,64 @@ +Parallel to LVDS Encoder +------------------------ + +This binding supports the parallel to LVDS encoders that don't require any +configuration. + +LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple +incompatible data link layers have been used over time to transmit image data +to LVDS panels. This binding targets devices compatible with the following +specifications only. + +[JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February +1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA) +[LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National +Semiconductor +[VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video +Electronics Standards Association (VESA) + +Those devices have been marketed under the FPD-Link and FlatLink brand names +among others. + + +Required properties: + +- compatible: Must be "lvds-encoder" + +Required nodes: + +This device has two video ports. Their connections are modeled using the OF +graph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 for parallel input +- Video port 1 for LVDS output + + +Example +------- + +lvds-encoder { + compatible = "lvds-encoder"; + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + lvds_enc_in: endpoint { + remote-endpoint = <&display_out_rgb>; + }; + }; + + port@1 { + reg = <1>; + + lvds_enc_out: endpoint { + remote-endpoint = <&lvds_panel_in>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/bridge/megachips-stdpxxxx-ge-b850v3-fw.txt b/Documentation/devicetree/bindings/display/bridge/megachips-stdpxxxx-ge-b850v3-fw.txt new file mode 100644 index 000000000000..7baa6582517e --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/megachips-stdpxxxx-ge-b850v3-fw.txt @@ -0,0 +1,94 @@ +Drivers for the second video output of the GE B850v3: + STDP4028-ge-b850v3-fw bridges (LVDS-DP) + STDP2690-ge-b850v3-fw bridges (DP-DP++) + +The video processing pipeline on the second output on the GE B850v3: + + Host -> LVDS|--(STDP4028)--|DP -> DP|--(STDP2690)--|DP++ -> Video output + +Each bridge has a dedicated flash containing firmware for supporting the custom +design. The result is that, in this design, neither the STDP4028 nor the +STDP2690 behave as the stock bridges would. The compatible strings include the +suffix "-ge-b850v3-fw" to make it clear that the driver is for the bridges with +the firmware specific for the GE B850v3. + +The hardware do not provide control over the video processing pipeline, as the +two bridges behaves as a single one. The only interfaces exposed by the +hardware are EDID, HPD, and interrupts. + +stdp4028-ge-b850v3-fw required properties: + - compatible : "megachips,stdp4028-ge-b850v3-fw" + - reg : I2C bus address + - interrupt-parent : phandle of the interrupt controller that services + interrupts to the device + - interrupts : one interrupt should be described here, as in + <0 IRQ_TYPE_LEVEL_HIGH> + - ports : One input port(reg = <0>) and one output port(reg = <1>) + +stdp2690-ge-b850v3-fw required properties: + compatible : "megachips,stdp2690-ge-b850v3-fw" + - reg : I2C bus address + - ports : One input port(reg = <0>) and one output port(reg = <1>) + +Example: + +&mux2_i2c2 { + status = "okay"; + clock-frequency = <100000>; + + stdp4028@73 { + compatible = "megachips,stdp4028-ge-b850v3-fw"; + #address-cells = <1>; + #size-cells = <0>; + + reg = <0x73>; + + interrupt-parent = <&gpio2>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + stdp4028_in: endpoint { + remote-endpoint = <&lvds0_out>; + }; + }; + port@1 { + reg = <1>; + stdp4028_out: endpoint { + remote-endpoint = <&stdp2690_in>; + }; + }; + }; + }; + + stdp2690@72 { + compatible = "megachips,stdp2690-ge-b850v3-fw"; + #address-cells = <1>; + #size-cells = <0>; + + reg = <0x72>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + stdp2690_in: endpoint { + remote-endpoint = <&stdp4028_out>; + }; + }; + + port@1 { + reg = <1>; + stdp2690_out: endpoint { + /* Connector for external display */ + }; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt new file mode 100644 index 000000000000..f6b3f36d422b --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt @@ -0,0 +1,75 @@ +Renesas Gen3 DWC HDMI TX Encoder +================================ + +The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP +with a companion PHY IP. + +These DT bindings follow the Synopsys DWC HDMI TX bindings defined in +Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the +following device-specific properties. + + +Required properties: + +- compatible : Shall contain one or more of + - "renesas,r8a7795-hdmi" for R8A7795 (R-Car H3) compatible HDMI TX + - "renesas,rcar-gen3-hdmi" for the generic R-Car Gen3 compatible HDMI TX + + When compatible with generic versions, nodes must list the SoC-specific + version corresponding to the platform first, followed by the + family-specific version. + +- reg: See dw_hdmi.txt. +- interrupts: HDMI interrupt number +- clocks: See dw_hdmi.txt. +- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. +- ports: See dw_hdmi.txt. The DWC HDMI shall have one port numbered 0 + corresponding to the video input of the controller and one port numbered 1 + corresponding to its HDMI output. Each port shall have a single endpoint. + +Optional properties: + +- power-domains: Shall reference the power domain that contains the DWC HDMI, + if any. + + +Example: + + hdmi0: hdmi0@fead0000 { + compatible = "renesas,r8a7795-dw-hdmi"; + reg = <0 0xfead0000 0 0x10000>; + interrupts = <0 389 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_CORE R8A7795_CLK_S0D4>, <&cpg CPG_MOD 729>; + clock-names = "iahb", "isfr"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + status = "disabled"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + dw_hdmi0_in: endpoint { + remote-endpoint = <&du_out_hdmi0>; + }; + }; + port@1 { + reg = <1>; + rcar_dw_hdmi0_out: endpoint { + remote-endpoint = <&hdmi0_con>; + }; + }; + }; + }; + + hdmi0-out { + compatible = "hdmi-connector"; + label = "HDMI0 OUT"; + type = "a"; + + port { + hdmi0_con: endpoint { + remote-endpoint = <&rcar_dw_hdmi0_out>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt index a78265993665..ca5204b3bc21 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt @@ -4,7 +4,6 @@ Required properties: - compatible: value should be one of the following "samsung,exynos3250-mipi-dsi" /* for Exynos3250/3472 SoCs */ "samsung,exynos4210-mipi-dsi" /* for Exynos4 SoCs */ - "samsung,exynos4415-mipi-dsi" /* for Exynos4415 SoC */ "samsung,exynos5410-mipi-dsi" /* for Exynos5410/5420/5440 SoCs */ "samsung,exynos5422-mipi-dsi" /* for Exynos5422/5800 SoCs */ "samsung,exynos5433-mipi-dsi" /* for Exynos5433 SoCs */ diff --git a/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt index 18645e0228b0..5837402c3ade 100644 --- a/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt +++ b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt @@ -11,7 +11,6 @@ Required properties: "samsung,s5pv210-fimd"; /* for S5PV210 SoC */ "samsung,exynos3250-fimd"; /* for Exynos3250/3472 SoCs */ "samsung,exynos4210-fimd"; /* for Exynos4 SoCs */ - "samsung,exynos4415-fimd"; /* for Exynos4415 SoC */ "samsung,exynos5250-fimd"; /* for Exynos5250 SoCs */ "samsung,exynos5420-fimd"; /* for Exynos5420/5422/5800 SoCs */ diff --git a/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt index 971c3eedb1c7..fa01db7eb66c 100644 --- a/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt +++ b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt @@ -21,13 +21,19 @@ Freescale i.MX IPUv3 ==================== Required properties: -- compatible: Should be "fsl,<chip>-ipu" +- compatible: Should be "fsl,<chip>-ipu" where <chip> is one of + - imx51 + - imx53 + - imx6q + - imx6qp - reg: should be register base and length as documented in the datasheet - interrupts: Should contain sync interrupt and error interrupt, in this order. - resets: phandle pointing to the system reset controller and reset line index, see reset/fsl,imx-src.txt for details +Additional required properties for fsl,imx6qp-ipu: +- fsl,prg: phandle to prg node associated with this IPU instance Optional properties: - port@[0-3]: Port nodes with endpoint definitions as defined in Documentation/devicetree/bindings/media/video-interfaces.txt. @@ -53,6 +59,57 @@ ipu: ipu@18000000 { }; }; +Freescale i.MX PRE (Prefetch Resolve Engine) +============================================ + +Required properties: +- compatible: should be "fsl,imx6qp-pre" +- reg: should be register base and length as documented in the + datasheet +- clocks : phandle to the PRE axi clock input, as described + in Documentation/devicetree/bindings/clock/clock-bindings.txt and + Documentation/devicetree/bindings/clock/imx6q-clock.txt. +- clock-names: should be "axi" +- interrupts: should contain the PRE interrupt +- fsl,iram: phandle pointing to the mmio-sram device node, that should be + used for the PRE SRAM double buffer. + +example: + +pre@21c8000 { + compatible = "fsl,imx6qp-pre"; + reg = <0x021c8000 0x1000>; + interrupts = <GIC_SPI 90 IRQ_TYPE_EDGE_RISING>; + clocks = <&clks IMX6QDL_CLK_PRE0>; + clock-names = "axi"; + fsl,iram = <&ocram2>; +}; + +Freescale i.MX PRG (Prefetch Resolve Gasket) +============================================ + +Required properties: +- compatible: should be "fsl,imx6qp-prg" +- reg: should be register base and length as documented in the + datasheet +- clocks : phandles to the PRG ipg and axi clock inputs, as described + in Documentation/devicetree/bindings/clock/clock-bindings.txt and + Documentation/devicetree/bindings/clock/imx6q-clock.txt. +- clock-names: should be "ipg" and "axi" +- fsl,pres: phandles to the PRE units attached to this PRG, with the fixed + PRE as the first entry and the muxable PREs following. + +example: + +prg@21cc000 { + compatible = "fsl,imx6qp-prg"; + reg = <0x021cc000 0x1000>; + clocks = <&clks IMX6QDL_CLK_PRG0_APB>, + <&clks IMX6QDL_CLK_PRG0_AXI>; + clock-names = "ipg", "axi"; + fsl,pres = <&pre1>, <&pre2>, <&pre3>; +}; + Parallel display support ======================== diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt index 708f5664a316..383183a89164 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt @@ -40,6 +40,7 @@ Required properties (all function blocks): "mediatek,<chip>-dpi" - DPI controller, see mediatek,dpi.txt "mediatek,<chip>-disp-mutex" - display mutex "mediatek,<chip>-disp-od" - overdrive + the supported chips are mt2701 and mt8173. - reg: Physical base address and length of the function block register space - interrupts: The interrupt signal from the function block (required, except for merge and split function blocks). @@ -54,6 +55,7 @@ Required properties (DMA function blocks): "mediatek,<chip>-disp-ovl" "mediatek,<chip>-disp-rdma" "mediatek,<chip>-disp-wdma" + the supported chips are mt2701 and mt8173. - larb: Should contain a phandle pointing to the local arbiter device as defined in Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt - iommus: Should point to the respective IOMMU block with master port as diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt index 2b1585a34b85..fadf327c7cdf 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dsi.txt @@ -7,6 +7,7 @@ channel output. Required properties: - compatible: "mediatek,<chip>-dsi" + the supported chips are mt2701 and mt8173. - reg: Physical base address and length of the controller's registers - interrupts: The interrupt signal from the function block. - clocks: device clocks @@ -25,6 +26,7 @@ The MIPI TX configuration module controls the MIPI D-PHY. Required properties: - compatible: "mediatek,<chip>-mipi-tx" + the supported chips are mt2701 and mt8173. - reg: Physical base address and length of the controller's registers - clocks: PLL reference clock - clock-output-names: name of the output clock line to the DSI encoder diff --git a/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.txt b/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.txt new file mode 100644 index 000000000000..6812280cb109 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/ampire,am-480272h3tmqw-t01h.txt @@ -0,0 +1,26 @@ +Ampire AM-480272H3TMQW-T01H 4.3" WQVGA TFT LCD panel + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. + +Required properties: +- compatible: should be "ampire,am-480272h3tmqw-t01h" + +Optional properties: +- power-supply: regulator to provide the supply voltage +- enable-gpios: GPIO pin to enable or disable the panel +- backlight: phandle of the backlight device attached to the panel + +Optional nodes: +- Video port for RGB input. + +Example: + panel_rgb: panel-rgb { + compatible = "ampire,am-480272h3tmqw-t01h"; + enable-gpios = <&gpioa 8 1>; + port { + panel_in_rgb: endpoint { + remote-endpoint = <&controller_out_rgb>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.txt b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.txt new file mode 100644 index 000000000000..ced0121aed7d --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa104xd12.txt @@ -0,0 +1,47 @@ +Mitsubishi AA204XD12 LVDS Display Panel +======================================= + +The AA104XD12 is a 10.4" XGA TFT-LCD display panel. + +These DT bindings follow the LVDS panel bindings defined in panel-lvds.txt +with the following device-specific properties. + + +Required properties: + +- compatible: Shall contain "mitsubishi,aa121td01" and "panel-lvds", in that + order. +- vcc-supply: Reference to the regulator powering the panel VCC pins. + + +Example +------- + +panel { + compatible = "mitsubishi,aa104xd12", "panel-lvds"; + vcc-supply = <&vcc_3v3>; + + width-mm = <210>; + height-mm = <158>; + + data-mapping = "jeida-24"; + + panel-timing { + /* 1024x768 @65Hz */ + clock-frequency = <65000000>; + hactive = <1024>; + vactive = <768>; + hsync-len = <136>; + hfront-porch = <20>; + hback-porch = <160>; + vfront-porch = <3>; + vback-porch = <29>; + vsync-len = <6>; + }; + + port { + panel_in: endpoint { + remote-endpoint = <&lvds_encoder>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.txt b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.txt new file mode 100644 index 000000000000..d6e1097504fe --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa121td01.txt @@ -0,0 +1,47 @@ +Mitsubishi AA121TD01 LVDS Display Panel +======================================= + +The AA121TD01 is a 12.1" WXGA TFT-LCD display panel. + +These DT bindings follow the LVDS panel bindings defined in panel-lvds.txt +with the following device-specific properties. + + +Required properties: + +- compatible: Shall contain "mitsubishi,aa121td01" and "panel-lvds", in that + order. +- vcc-supply: Reference to the regulator powering the panel VCC pins. + + +Example +------- + +panel { + compatible = "mitsubishi,aa121td01", "panel-lvds"; + vcc-supply = <&vcc_3v3>; + + width-mm = <261>; + height-mm = <163>; + + data-mapping = "jeida-24"; + + panel-timing { + /* 1280x800 @60Hz */ + clock-frequency = <71000000>; + hactive = <1280>; + vactive = <800>; + hsync-len = <70>; + hfront-porch = <20>; + hback-porch = <70>; + vsync-len = <5>; + vfront-porch = <3>; + vback-porch = <15>; + }; + + port { + panel_in: endpoint { + remote-endpoint = <&lvds_encoder>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.txt b/Documentation/devicetree/bindings/display/panel/panel-common.txt new file mode 100644 index 000000000000..ec52c472c845 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panel-common.txt @@ -0,0 +1,91 @@ +Common Properties for Display Panel +=================================== + +This document defines device tree properties common to several classes of +display panels. It doesn't constitue a device tree binding specification by +itself but is meant to be referenced by device tree bindings. + +When referenced from panel device tree bindings the properties defined in this +document are defined as follows. The panel device tree bindings are +responsible for defining whether each property is required or optional. + + +Descriptive Properties +---------------------- + +- width-mm, +- height-mm: The width-mm and height-mm specify the width and height of the + physical area where images are displayed. These properties are expressed in + millimeters and rounded to the closest unit. + +- label: The label property specifies a symbolic name for the panel as a + string suitable for use by humans. It typically contains a name inscribed on + the system (e.g. as an affixed label) or specified in the system's + documentation (e.g. in the user's manual). + + If no such name exists, and unless the property is mandatory according to + device tree bindings, it shall rather be omitted than constructed of + non-descriptive information. For instance an LCD panel in a system that + contains a single panel shall not be labelled "LCD" if that name is not + inscribed on the system or used in a descriptive fashion in system + documentation. + + +Display Timings +--------------- + +- panel-timing: Most display panels are restricted to a single resolution and + require specific display timings. The panel-timing subnode expresses those + timings as specified in the timing subnode section of the display timing + bindings defined in + Documentation/devicetree/bindings/display/display-timing.txt. + + +Connectivity +------------ + +- ports: Panels receive video data through one or multiple connections. While + the nature of those connections is specific to the panel type, the + connectivity is expressed in a standard fashion using ports as specified in + the device graph bindings defined in + Documentation/devicetree/bindings/graph.txt. + +- ddc-i2c-bus: Some panels expose EDID information through an I2C-compatible + bus such as DDC2 or E-DDC. For such panels the ddc-i2c-bus contains a + phandle to the system I2C controller connected to that bus. + + +Control I/Os +------------ + +Many display panels can be controlled through pins driven by GPIOs. The nature +and timing of those control signals are device-specific and left for panel +device tree bindings to specify. The following GPIO specifiers can however be +used for panels that implement compatible control signals. + +- enable-gpios: Specifier for a GPIO connected to the panel enable control + signal. The enable signal is active high and enables operation of the panel. + This property can also be used for panels implementing an active low power + down signal, which is a negated version of the enable signal. Active low + enable signals (or active high power down signals) can be supported by + inverting the GPIO specifier polarity flag. + + Note that the enable signal control panel operation only and must not be + confused with a backlight enable signal. + +- reset-gpios: Specifier for a GPIO coonnected to the panel reset control + signal. The reset signal is active low and resets the panel internal logic + while active. Active high reset signals can be supported by inverting the + GPIO specifier polarity flag. + + +Backlight +--------- + +Most display panels include a backlight. Some of them also include a backlight +controller exposed through a control bus such as I2C or DSI. Others expose +backlight control through GPIO, PWM or other signals connected to an external +backlight controller. + +- backlight: For panels whose backlight is controlled by an external backlight + controller, this property contains a phandle that references the controller. diff --git a/Documentation/devicetree/bindings/display/panel/panel-dpi.txt b/Documentation/devicetree/bindings/display/panel/panel-dpi.txt index d4add13e592d..6b203bc4d932 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-dpi.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-dpi.txt @@ -9,6 +9,7 @@ Optional properties: - enable-gpios: panel enable gpio - reset-gpios: GPIO to control the RESET pin - vcc-supply: phandle of regulator that will be used to enable power to the display +- backlight: phandle of the backlight device Required nodes: - "panel-timing" containing video timings @@ -22,6 +23,8 @@ lcd0: display@0 { compatible = "samsung,lte430wq-f0c", "panel-dpi"; label = "lcd"; + backlight = <&backlight>; + port { lcd_in: endpoint { remote-endpoint = <&dpi_out>; diff --git a/Documentation/devicetree/bindings/display/panel/panel-lvds.txt b/Documentation/devicetree/bindings/display/panel/panel-lvds.txt new file mode 100644 index 000000000000..b938269f841e --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panel-lvds.txt @@ -0,0 +1,120 @@ +LVDS Display Panel +================== + +LVDS is a physical layer specification defined in ANSI/TIA/EIA-644-A. Multiple +incompatible data link layers have been used over time to transmit image data +to LVDS panels. This bindings supports display panels compatible with the +following specifications. + +[JEIDA] "Digital Interface Standards for Monitor", JEIDA-59-1999, February +1999 (Version 1.0), Japan Electronic Industry Development Association (JEIDA) +[LDI] "Open LVDS Display Interface", May 1999 (Version 0.95), National +Semiconductor +[VESA] "VESA Notebook Panel Standard", October 2007 (Version 1.0), Video +Electronics Standards Association (VESA) + +Device compatible with those specifications have been marketed under the +FPD-Link and FlatLink brands. + + +Required properties: + +- compatible: Shall contain "panel-lvds" in addition to a mandatory + panel-specific compatible string defined in individual panel bindings. The + "panel-lvds" value shall never be used on its own. +- width-mm: See panel-common.txt. +- height-mm: See panel-common.txt. +- data-mapping: The color signals mapping order, "jeida-18", "jeida-24" + or "vesa-24". + +Optional properties: + +- label: See panel-common.txt. +- gpios: See panel-common.txt. +- backlight: See panel-common.txt. +- data-mirror: If set, reverse the bit order described in the data mappings + below on all data lanes, transmitting bits for slots 6 to 0 instead of + 0 to 6. + +Required nodes: + +- panel-timing: See panel-common.txt. +- ports: See panel-common.txt. These bindings require a single port subnode + corresponding to the panel LVDS input. + + +LVDS data mappings are defined as follows. + +- "jeida-18" - 18-bit data mapping compatible with the [JEIDA], [LDI] and + [VESA] specifications. Data are transferred as follows on 3 LVDS lanes. + +Slot 0 1 2 3 4 5 6 + ________________ _________________ +Clock \_______________________/ + ______ ______ ______ ______ ______ ______ ______ +DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__>< +DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__>< +DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__>< + +- "jeida-24" - 24-bit data mapping compatible with the [DSIM] and [LDI] + specifications. Data are transferred as follows on 4 LVDS lanes. + +Slot 0 1 2 3 4 5 6 + ________________ _________________ +Clock \_______________________/ + ______ ______ ______ ______ ______ ______ ______ +DATA0 ><__G2__><__R7__><__R6__><__R5__><__R4__><__R3__><__R2__>< +DATA1 ><__B3__><__B2__><__G7__><__G6__><__G5__><__G4__><__G3__>< +DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B7__><__B6__><__B5__><__B4__>< +DATA3 ><_CTL3_><__B1__><__B0__><__G1__><__G0__><__R1__><__R0__>< + +- "vesa-24" - 24-bit data mapping compatible with the [VESA] specification. + Data are transferred as follows on 4 LVDS lanes. + +Slot 0 1 2 3 4 5 6 + ________________ _________________ +Clock \_______________________/ + ______ ______ ______ ______ ______ ______ ______ +DATA0 ><__G0__><__R5__><__R4__><__R3__><__R2__><__R1__><__R0__>< +DATA1 ><__B1__><__B0__><__G5__><__G4__><__G3__><__G2__><__G1__>< +DATA2 ><_CTL2_><_CTL1_><_CTL0_><__B5__><__B4__><__B3__><__B2__>< +DATA3 ><_CTL3_><__B7__><__B6__><__G7__><__G6__><__R7__><__R6__>< + +Control signals are mapped as follows. + +CTL0: HSync +CTL1: VSync +CTL2: Data Enable +CTL3: 0 + + +Example +------- + +panel { + compatible = "mitsubishi,aa121td01", "panel-lvds"; + + width-mm = <261>; + height-mm = <163>; + + data-mapping = "jeida-24"; + + panel-timing { + /* 1280x800 @60Hz */ + clock-frequency = <71000000>; + hactive = <1280>; + vactive = <800>; + hsync-len = <70>; + hfront-porch = <20>; + hback-porch = <70>; + vsync-len = <5>; + vfront-porch = <3>; + vback-porch = <15>; + }; + + port { + panel_in: endpoint { + remote-endpoint = <&lvds_encoder>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e3ha2.txt b/Documentation/devicetree/bindings/display/panel/samsung,s6e3ha2.txt new file mode 100644 index 000000000000..18854f4c8376 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e3ha2.txt @@ -0,0 +1,28 @@ +Samsung S6E3HA2 5.7" 1440x2560 AMOLED panel + +Required properties: + - compatible: "samsung,s6e3ha2" + - reg: the virtual channel number of a DSI peripheral + - vdd3-supply: I/O voltage supply + - vci-supply: voltage supply for analog circuits + - reset-gpios: a GPIO spec for the reset pin (active low) + - enable-gpios: a GPIO spec for the panel enable pin (active high) + +Optional properties: + - te-gpios: a GPIO spec for the tearing effect synchronization signal + gpio pin (active high) + +Example: +&dsi { + ... + + panel@0 { + compatible = "samsung,s6e3ha2"; + reg = <0>; + vdd3-supply = <&ldo27_reg>; + vci-supply = <&ldo28_reg>; + reset-gpios = <&gpg0 0 GPIO_ACTIVE_LOW>; + enable-gpios = <&gpf1 5 GPIO_ACTIVE_HIGH>; + te-gpios = <&gpf1 3 GPIO_ACTIVE_HIGH>; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.txt b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.txt new file mode 100644 index 000000000000..c6995dde641b --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sitronix,st7789v.txt @@ -0,0 +1,37 @@ +Sitronix ST7789V RGB panel with SPI control bus + +Required properties: + - compatible: "sitronix,st7789v" + - reg: Chip select of the panel on the SPI bus + - reset-gpios: a GPIO phandle for the reset pin + - power-supply: phandle of the regulator that provides the supply voltage + +Optional properties: + - backlight: phandle to the backlight used + +The generic bindings for the SPI slaves documented in [1] also applies + +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/graph.txt + +Example: + +panel@0 { + compatible = "sitronix,st7789v"; + reg = <0>; + reset-gpios = <&pio 6 11 GPIO_ACTIVE_LOW>; + backlight = <&pwm_bl>; + spi-max-frequency = <100000>; + spi-cpol; + spi-cpha; + + port { + panel_input: endpoint { + remote-endpoint = <&tcon0_out_panel>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/winstar,wf35ltiacd.txt b/Documentation/devicetree/bindings/display/panel/winstar,wf35ltiacd.txt new file mode 100644 index 000000000000..2a7e6e3ba64c --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/winstar,wf35ltiacd.txt @@ -0,0 +1,48 @@ +Winstar Display Corporation 3.5" QVGA (320x240) TFT LCD panel + +Required properties: +- compatible: should be "winstar,wf35ltiacd" +- power-supply: regulator to provide the VCC supply voltage (3.3 volts) + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. + +Example: + backlight: backlight { + compatible = "pwm-backlight"; + pwms = <&hlcdc_pwm 0 50000 PWM_POLARITY_INVERTED>; + brightness-levels = <0 31 63 95 127 159 191 223 255>; + default-brightness-level = <191>; + power-supply = <&bl_reg>; + }; + + bl_reg: backlight_regulator { + compatible = "regulator-fixed"; + regulator-name = "backlight-power-supply"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + }; + + panel: panel { + compatible = "winstar,wf35ltiacd", "simple-panel"; + backlight = <&backlight>; + power-supply = <&panel_reg>; + #address-cells = <1>; + #size-cells = <0>; + + port { + #address-cells = <1>; + #size-cells = <0>; + + panel_input: endpoint { + remote-endpoint = <&hlcdc_panel_output>; + }; + }; + }; + + panel_reg: panel_regulator { + compatible = "regulator-fixed"; + regulator-name = "panel-power-supply"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index 1a02f099a0ff..c6cb96a4fa93 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -36,6 +36,9 @@ Required Properties: When supplied they must be named "dclkin.x" with "x" being the input clock numerical index. + - vsps: A list of phandles to the VSP nodes that handle the memory + interfaces for the DU channels. + Required nodes: The connections to the DU output video ports are modeled using the OF graph diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt index 1753f0cc6fad..543b07435f4f 100644 --- a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt @@ -5,16 +5,24 @@ Required properties: - #address-cells: Should be <1>. - #size-cells: Should be <0>. - compatible: "rockchip,rk3288-mipi-dsi", "snps,dw-mipi-dsi". + "rockchip,rk3399-mipi-dsi", "snps,dw-mipi-dsi". - reg: Represent the physical address range of the controller. - interrupts: Represent the controller's interrupt to the CPU(s). - clocks, clock-names: Phandles to the controller's pll reference - clock(ref) and APB clock(pclk), as described in [1]. + clock(ref) and APB clock(pclk). For RK3399, a phy config clock + (phy_cfg) and a grf clock(grf) are required. As described in [1]. - rockchip,grf: this soc should set GRF regs to mux vopl/vopb. - ports: contain a port node with endpoint definitions as defined in [2]. For vopb,set the reg = <0> and set the reg = <1> for vopl. +Optional properties: +- power-domains: a phandle to mipi dsi power domain node. +- resets: list of phandle + reset specifier pairs, as described in [3]. +- reset-names: string reset name, must be "apb". + [1] Documentation/devicetree/bindings/clock/clock-bindings.txt [2] Documentation/devicetree/bindings/media/video-interfaces.txt +[3] Documentation/devicetree/bindings/reset/reset.txt Example: mipi_dsi: mipi@ff960000 { @@ -25,6 +33,8 @@ Example: interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; clocks = <&cru SCLK_MIPI_24M>, <&cru PCLK_MIPI_DSI0>; clock-names = "ref", "pclk"; + resets = <&cru SRST_MIPIDSI0>; + reset-names = "apb"; rockchip,grf = <&grf>; status = "okay"; diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt index 0fad7ed2ea19..74e1e8add5a1 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt @@ -249,6 +249,19 @@ of the following host1x client modules: See ../pinctrl/nvidia,tegra124-dpaux-padctl.txt for information regarding the DPAUX pad controller bindings. +- vic: Video Image Compositor + - compatible : "nvidia,tegra<chip>-vic" + - reg: Physical base address and length of the controller's registers. + - interrupts: The interrupt outputs from the controller. + - clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must include the following entries: + - vic: clock input for the VIC hardware + - resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must include the following entries: + - vic + Example: / { diff --git a/Documentation/devicetree/bindings/firmware/coreboot.txt b/Documentation/devicetree/bindings/firmware/coreboot.txt new file mode 100644 index 000000000000..4c955703cea8 --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/coreboot.txt @@ -0,0 +1,33 @@ +COREBOOT firmware information + +The device tree node to communicate the location of coreboot's memory-resident +bookkeeping structures to the kernel. Since coreboot itself cannot boot a +device-tree-based kernel (yet), this node needs to be inserted by a +second-stage bootloader (a coreboot "payload"). + +Required properties: + - compatible: Should be "coreboot" + - reg: Address and length of the following two memory regions, in order: + 1.) The coreboot table. This is a list of variable-sized descriptors + that contain various compile- and run-time generated firmware + parameters. It is identified by the magic string "LBIO" in its first + four bytes. + See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for + details. + 2.) The CBMEM area. This is a downward-growing memory region used by + coreboot to dynamically allocate data structures that remain resident. + It may or may not include the coreboot table as one of its members. It + is identified by a root node descriptor with the magic number + 0xc0389481 that resides in the topmost 8 bytes of the area. + See coreboot's src/include/imd.h for details. + +Example: + firmware { + ranges; + + coreboot { + compatible = "coreboot"; + reg = <0xfdfea000 0x264>, + <0xfdfea000 0x16000>; + } + }; diff --git a/Documentation/devicetree/bindings/fpga/altera-pr-ip.txt b/Documentation/devicetree/bindings/fpga/altera-pr-ip.txt new file mode 100644 index 000000000000..52a294cf2730 --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/altera-pr-ip.txt @@ -0,0 +1,12 @@ +Altera Arria10 Partial Reconfiguration IP + +Required properties: +- compatible : should contain "altr,a10-pr-ip" +- reg : base address and size for memory mapped io. + +Example: + + fpga_mgr: fpga-mgr@ff20c000 { + compatible = "altr,a10-pr-ip"; + reg = <0xff20c000 0x10>; + }; diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt index 3b32ba15a717..6db8aeda461a 100644 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -186,12 +186,15 @@ Optional properties: otherwise full reconfiguration is done. - external-fpga-config : boolean, set if the FPGA has already been configured prior to OS boot up. +- encrypted-fpga-config : boolean, set if the bitstream is encrypted - region-unfreeze-timeout-us : The maximum time in microseconds to wait for bridges to successfully become enabled after the region has been programmed. - region-freeze-timeout-us : The maximum time in microseconds to wait for bridges to successfully become disabled before the region has been programmed. +- config-complete-timeout-us : The maximum time in microseconds time for the + FPGA to go to operating mode after the region has been programmed. - child nodes : devices in the FPGA after programming. In the example below, when an overlay is applied targeting fpga-region0, diff --git a/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt new file mode 100644 index 000000000000..4dc412437b08 --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt @@ -0,0 +1,21 @@ +Lattice iCE40 FPGA Manager + +Required properties: +- compatible: Should contain "lattice,ice40-fpga-mgr" +- reg: SPI chip select +- spi-max-frequency: Maximum SPI frequency (>=1000000, <=25000000) +- cdone-gpios: GPIO input connected to CDONE pin +- reset-gpios: Active-low GPIO output connected to CRESET_B pin. Note + that unless the GPIO is held low during startup, the + FPGA will enter Master SPI mode and drive SCK with a + clock signal potentially jamming other devices on the + bus until the firmware is loaded. + +Example: + fpga: fpga@0 { + compatible = "lattice,ice40-fpga-mgr"; + reg = <0>; + spi-max-frequency = <1000000>; + cdone-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio 22 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt new file mode 100644 index 000000000000..9766f7472f51 --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt @@ -0,0 +1,44 @@ +Xilinx Slave Serial SPI FPGA Manager + +Xilinx Spartan-6 FPGAs support a method of loading the bitstream over +what is referred to as "slave serial" interface. +The slave serial link is not technically SPI, and might require extra +circuits in order to play nicely with other SPI slaves on the same bus. + +See https://www.xilinx.com/support/documentation/user_guides/ug380.pdf + +Required properties: +- compatible: should contain "xlnx,fpga-slave-serial" +- reg: spi chip select of the FPGA +- prog_b-gpios: config pin (referred to as PROGRAM_B in the manual) +- done-gpios: config status pin (referred to as DONE in the manual) + +Example for full FPGA configuration: + + fpga-region0 { + compatible = "fpga-region"; + fpga-mgr = <&fpga_mgr_spi>; + #address-cells = <0x1>; + #size-cells = <0x1>; + }; + + spi1: spi@10680 { + compatible = "marvell,armada-xp-spi", "marvell,orion-spi"; + pinctrl-0 = <&spi0_pins>; + pinctrl-names = "default"; + #address-cells = <1>; + #size-cells = <0>; + cell-index = <1>; + interrupts = <92>; + clocks = <&coreclk 0>; + status = "okay"; + + fpga_mgr_spi: fpga-mgr@0 { + compatible = "xlnx,fpga-slave-serial"; + spi-max-frequency = <60000000>; + spi-cpha; + reg = <0>; + done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>; + prog_b-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/gpio/cortina,gemini-gpio.txt b/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.txt index 5c9246c054e5..d04236558619 100644 --- a/Documentation/devicetree/bindings/gpio/cortina,gemini-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/faraday,ftgpio010.txt @@ -1,8 +1,11 @@ -Cortina Systems Gemini GPIO Controller +Faraday Technology FTGPIO010 GPIO Controller Required properties: -- compatible : Must be "cortina,gemini-gpio" +- compatible : Should be one of + "cortina,gemini-gpio", "faraday,ftgpio010" + "moxa,moxart-gpio", "faraday,ftgpio010" + "faraday,ftgpio010" - reg : Should contain registers location and length - interrupts : Should contain the interrupt line for the GPIO block - gpio-controller : marks this as a GPIO controller @@ -14,7 +17,7 @@ Required properties: Example: gpio@4d000000 { - compatible = "cortina,gemini-gpio"; + compatible = "cortina,gemini-gpio", "faraday,ftgpio010"; reg = <0x4d000000 0x100>; interrupts = <22 IRQ_TYPE_LEVEL_HIGH>; gpio-controller; diff --git a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt index 393bb2ed8a77..c756afa88cc6 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt @@ -17,7 +17,8 @@ Required properties: Optional properties: -- interrupt-parent : The parent interrupt controller, optional if inherited +- interrupt-parent : The parent interrupt controller, optional if inherited +- clocks : A phandle to the HPLL clock node for debounce timings The gpio and interrupt properties are further described in their respective bindings documentation: diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt index a6f3bec1da7d..42c3bb2d53e8 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt @@ -38,6 +38,24 @@ Required properties: - #gpio-cells: Should be two. The first cell is the pin number. The second cell is reserved for flags, unused at the moment. +Optional properties: + +In order to use the GPIO lines in PWM mode, some additional optional +properties are required. Only Armada 370 and XP support these properties. + +- compatible: Must contain "marvell,armada-370-xp-gpio" + +- reg: an additional register set is needed, for the GPIO Blink + Counter on/off registers. + +- reg-names: Must contain an entry "pwm" corresponding to the + additional register range needed for PWM operation. + +- #pwm-cells: Should be two. The first cell is the GPIO line number. The + second cell is the period in nanoseconds. + +- clocks: Must be a phandle to the clock for the GPIO controller. + Example: gpio0: gpio@d0018100 { @@ -51,3 +69,17 @@ Example: #interrupt-cells = <2>; interrupts = <16>, <17>, <18>, <19>; }; + + gpio1: gpio@18140 { + compatible = "marvell,armada-370-xp-gpio"; + reg = <0x18140 0x40>, <0x181c8 0x08>; + reg-names = "gpio", "pwm"; + ngpios = <17>; + gpio-controller; + #gpio-cells = <2>; + #pwm-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <87>, <88>, <89>; + clocks = <&coreclk 0>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index e63935710011..7f57271df2bc 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -26,6 +26,7 @@ Required properties: ti,tca6416 ti,tca6424 ti,tca9539 + ti,tca9554 onsemi,pca9654 exar,xra1202 diff --git a/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt b/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt index ada4e2973323..7d3bd631d011 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pcf857x.txt @@ -25,7 +25,6 @@ Required Properties: - "nxp,pcf8574": For the NXP PCF8574 - "nxp,pcf8574a": For the NXP PCF8574A - "nxp,pcf8575": For the NXP PCF8575 - - "ti,tca9554": For the TI TCA9554 - reg: I2C slave address. diff --git a/Documentation/devicetree/bindings/gpio/gpio-thunderx.txt b/Documentation/devicetree/bindings/gpio/gpio-thunderx.txt new file mode 100644 index 000000000000..3f883ae29d11 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-thunderx.txt @@ -0,0 +1,27 @@ +Cavium ThunderX/OCTEON-TX GPIO controller bindings + +Required Properties: +- reg: The controller bus address. +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells: Must be 2. + - First cell is the GPIO pin number relative to the controller. + - Second cell is a standard generic flag bitfield as described in gpio.txt. + +Optional Properties: +- compatible: "cavium,thunder-8890-gpio", unused as PCI driver binding is used. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Must be present and have value of 2 if + "interrupt-controller" is present. + - First cell is the GPIO pin number relative to the controller. + - Second cell is triggering flags as defined in interrupts.txt. + +Example: + +gpio_6_0: gpio@6,0 { + compatible = "cavium,thunder-8890-gpio"; + reg = <0x3000 0 0 0 0>; /* DEVFN = 0x30 (6:0) */ + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-xra1403.txt b/Documentation/devicetree/bindings/gpio/gpio-xra1403.txt new file mode 100644 index 000000000000..e13cc399b363 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-xra1403.txt @@ -0,0 +1,46 @@ +GPIO Driver for XRA1403 16-BIT GPIO Expander With Reset Input from EXAR + +The XRA1403 is an 16-bit GPIO expander with an SPI interface. Features available: + - Individually programmable inputs: + - Internal pull-up resistors + - Polarity inversion + - Individual interrupt enable + - Rising edge and/or Falling edge interrupt + - Input filter + - Individually programmable outputs + - Output Level Control + - Output Three-State Control + +Properties +---------- +Check documentation for SPI and GPIO controllers regarding properties needed to configure the node. + + - compatible = "exar,xra1403". + - reg - SPI id of the device. + - gpio-controller - marks the node as gpio. + - #gpio-cells - should be two where the first cell is the pin number + and the second one is used for optional parameters. + +Optional properties: +------------------- + - reset-gpios: in case available used to control the device reset line. + - interrupt-controller - marks the node as interrupt controller. + - #interrupt-cells - should be two and represents the number of cells + needed to encode interrupt source. + +Example +-------- + + gpioxra0: gpio@2 { + compatible = "exar,xra1403"; + reg = <2>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + + reset-gpios = <&gpio3 6 GPIO_ACTIVE_LOW>; + spi-max-frequency = <1000000>; + }; diff --git a/Documentation/devicetree/bindings/gpio/moxa,moxart-gpio.txt b/Documentation/devicetree/bindings/gpio/moxa,moxart-gpio.txt deleted file mode 100644 index f8e8f185a3db..000000000000 --- a/Documentation/devicetree/bindings/gpio/moxa,moxart-gpio.txt +++ /dev/null @@ -1,19 +0,0 @@ -MOXA ART GPIO Controller - -Required properties: - -- #gpio-cells : Should be 2, The first cell is the pin number, - the second cell is used to specify polarity: - 0 = active high - 1 = active low -- compatible : Must be "moxa,moxart-gpio" -- reg : Should contain registers location and length - -Example: - - gpio: gpio@98700000 { - gpio-controller; - #gpio-cells = <2>; - compatible = "moxa,moxart-gpio"; - reg = <0x98700000 0xC>; - }; diff --git a/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt b/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt new file mode 100644 index 000000000000..ca2f8c745a27 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt @@ -0,0 +1,38 @@ +Bindings for the National Instruments 169445 GPIO NAND controller + +The 169445 GPIO NAND controller has two memory mapped GPIO registers, one +for input (the ready signal) and one for output (control signals). It is +intended to be used with the GPIO NAND driver. + +Required properties: + - compatible: should be "ni,169445-nand-gpio" + - reg-names: must contain + "dat" - data register + - reg: address + size pairs describing the GPIO register sets; + order must correspond with the order of entries in reg-names + - #gpio-cells: must be set to 2. The first cell is the pin number and + the second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low + - gpio-controller: Marks the device node as a gpio controller. + +Optional properties: + - no-output: disables driving output on the pins + +Examples: + gpio1: nand-gpio-out@1f300010 { + compatible = "ni,169445-nand-gpio"; + reg = <0x1f300010 0x4>; + reg-names = "dat"; + gpio-controller; + #gpio-cells = <2>; + }; + + gpio2: nand-gpio-in@1f300014 { + compatible = "ni,169445-nand-gpio"; + reg = <0x1f300014 0x4>; + reg-names = "dat"; + gpio-controller; + #gpio-cells = <2>; + no-output; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ads7828.txt b/Documentation/devicetree/bindings/hwmon/ads7828.txt new file mode 100644 index 000000000000..fe0cc4ad7ea9 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ads7828.txt @@ -0,0 +1,25 @@ +ads7828 properties + +Required properties: +- compatible: Should be one of + ti,ads7828 + ti,ads7830 +- reg: I2C address + +Optional properties: + +- ti,differential-input + Set to use the device in differential mode. +- vref-supply + The external reference on the device is set to this regulators output. If it + does not exists the internal reference will be used and output by the ads78xx + on the "external vref" pin. + + Example ADS7828 node: + + ads7828: ads@48 { + comatible = "ti,ads7828"; + reg = <0x48>; + vref-supply = <&vref>; + ti,differential-input; + }; diff --git a/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt new file mode 100644 index 000000000000..cf4460564adb --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/aspeed-pwm-tacho.txt @@ -0,0 +1,68 @@ +ASPEED AST2400/AST2500 PWM and Fan Tacho controller device driver + +The ASPEED PWM controller can support upto 8 PWM outputs. The ASPEED Fan Tacho +controller can support upto 16 Fan tachometer inputs. + +There can be upto 8 fans supported. Each fan can have one PWM output and +one/two Fan tach inputs. + +Required properties for pwm-tacho node: +- #address-cells : should be 1. + +- #size-cells : should be 1. + +- reg : address and length of the register set for the device. + +- pinctrl-names : a pinctrl state named "default" must be defined. + +- pinctrl-0 : phandle referencing pin configuration of the PWM ports. + +- compatible : should be "aspeed,ast2400-pwm-tacho" for AST2400 and + "aspeed,ast2500-pwm-tacho" for AST2500. + +- clocks : a fixed clock providing input clock frequency(PWM + and Fan Tach clock) + +fan subnode format: +=================== +Under fan subnode there can upto 8 child nodes, with each child node +representing a fan. If there are 8 fans each fan can have one PWM port and +one/two Fan tach inputs. + +Required properties for each child node: +- reg : should specify PWM source port. + integer value in the range 0 to 7 with 0 indicating PWM port A and + 7 indicating PWM port H. + +- aspeed,fan-tach-ch : should specify the Fan tach input channel. + integer value in the range 0 through 15, with 0 indicating + Fan tach channel 0 and 15 indicating Fan tach channel 15. + Atleast one Fan tach input channel is required. + +Examples: + +pwm_tacho_fixed_clk: fixedclk { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <24000000>; +}; + +pwm_tacho: pwmtachocontroller@1e786000 { + #address-cells = <1>; + #size-cells = <1>; + reg = <0x1E786000 0x1000>; + compatible = "aspeed,ast2500-pwm-tacho"; + clocks = <&pwm_tacho_fixed_clk>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pwm0_default &pinctrl_pwm1_default>; + + fan@0 { + reg = <0x00>; + aspeed,fan-tach-ch = /bits/ 8 <0x00>; + }; + + fan@1 { + reg = <0x01>; + aspeed,fan-tach-ch = /bits/ 8 <0x01 0x02>; + }; +}; diff --git a/Documentation/devicetree/bindings/hwmon/lm87.txt b/Documentation/devicetree/bindings/hwmon/lm87.txt new file mode 100644 index 000000000000..e1b79903f204 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/lm87.txt @@ -0,0 +1,30 @@ +*LM87 hwmon sensor. + +Required properties: +- compatible: Should be + "ti,lm87" + +- reg: I2C address + +optional properties: +- has-temp3: This configures pins 18 and 19 to be used as a second + remote temperature sensing channel. By default the pins + are configured as voltage input pins in0 and in5. + +- has-in6: When set, pin 5 is configured to be used as voltage input + in6. Otherwise the pin is set as FAN1 input. + +- has-in7: When set, pin 6 is configured to be used as voltage input + in7. Otherwise the pin is set as FAN2 input. + +- vcc-supply: a Phandle for the regulator supplying power, can be + cofigured to measure 5.0V power supply. Default is 3.3V. + +Example: + +lm87@2e { + compatible = "ti,lm87"; + reg = <0x2e>; + has-temp3; + vcc-supply = <®_5v0>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-meson.txt b/Documentation/devicetree/bindings/i2c/i2c-meson.txt index 386357d1aab0..611b934c7e10 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-meson.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-meson.txt @@ -8,6 +8,8 @@ Required properties: - #address-cells: should be <1> - #size-cells: should be <0> +For details regarding the following core I2C bindings see also i2c.txt. + Optional properties: - clock-frequency: the desired I2C bus clock frequency in Hz; in absence of this property the default value is used (100 kHz). diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt new file mode 100644 index 000000000000..1e98c6b3a721 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt @@ -0,0 +1,61 @@ +* Linear Technology / Analog Devices I2C bus switch + +Required Properties: + + - compatible: Must contain one of the following. + "lltc,ltc4305", "lltc,ltc4306" + - reg: The I2C address of the device. + + The following required properties are defined externally: + + - Standard I2C mux properties. See i2c-mux.txt in this directory. + - I2C child bus nodes. See i2c-mux.txt in this directory. + +Optional Properties: + + - enable-gpios: Reference to the GPIO connected to the enable input. + - i2c-mux-idle-disconnect: Boolean; if defined, forces mux to disconnect all + children in idle state. This is necessary for example, if there are several + multiplexers on the bus and the devices behind them use same I2C addresses. + - 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. + - ltc,downstream-accelerators-enable: Enables the rise time accelerators + on the downstream port. + - ltc,upstream-accelerators-enable: Enables the rise time accelerators + on the upstream port. + +Example: + + ltc4306: i2c-mux@4a { + compatible = "lltc,ltc4306"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x4a>; + + gpio-controller; + #gpio-cells = <2>; + + i2c@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + eeprom@50 { + compatible = "at,24c02"; + reg = <0x50>; + }; + }; + + i2c@1 { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + eeprom@50 { + compatible = "at,24c02"; + reg = <0x50>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-rk3x.txt b/Documentation/devicetree/bindings/i2c/i2c-rk3x.txt index bbc5a1ed5fa1..e18445d0980c 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-rk3x.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-rk3x.txt @@ -11,6 +11,7 @@ Required properties : - "rockchip,rk3188-i2c": for rk3188 - "rockchip,rk3228-i2c": for rk3228 - "rockchip,rk3288-i2c": for rk3288 + - "rockchip,rk3328-i2c", "rockchip,rk3399-i2c": for rk3328 - "rockchip,rk3399-i2c": for rk3399 - interrupts : interrupt number - clocks: See ../clock/clock-bindings.txt diff --git a/Documentation/devicetree/bindings/iio/accel/adxl345.txt b/Documentation/devicetree/bindings/iio/accel/adxl345.txt new file mode 100644 index 000000000000..e7111b02c02c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/adxl345.txt @@ -0,0 +1,38 @@ +Analog Devices ADXL345 3-Axis, +/-(2g/4g/8g/16g) Digital Accelerometer + +http://www.analog.com/en/products/mems/accelerometers/adxl345.html + +Required properties: + - compatible : should be "adi,adxl345" + - reg : the I2C address or SPI chip select number of the sensor + +Required properties for SPI bus usage: + - spi-max-frequency : set maximum clock frequency, must be 5000000 + - spi-cpol and spi-cpha : must be defined for adxl345 to enable SPI mode 3 + +Optional properties: + - interrupt-parent : phandle to the parent interrupt controller as documented + in Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + - interrupts: interrupt mapping for IRQ as documented in + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +Example for a I2C device node: + + accelerometer@2a { + compatible = "adi,adxl345"; + reg = <0x53>; + interrupt-parent = <&gpio1>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + +Example for a SPI device node: + + accelerometer@0 { + compatible = "adi,adxl345"; + reg = <0>; + spi-max-frequency = <5000000>; + spi-cpol; + spi-cpha; + interrupt-parent = <&gpio1>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt index f9e3ff2c656e..047189192aec 100644 --- a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt +++ b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt @@ -7,6 +7,7 @@ Required properties: - "amlogic,meson-gxm-saradc" for GXM along with the generic "amlogic,meson-saradc" - reg: the physical base address and length of the registers +- interrupts: the interrupt indicating end of sampling - clocks: phandle and clock identifier (see clock-names) - clock-names: mandatory clocks: - "clkin" for the reference clock (typically XTAL) @@ -23,6 +24,7 @@ Example: compatible = "amlogic,meson-gxl-saradc", "amlogic,meson-saradc"; #io-channel-cells = <1>; reg = <0x0 0x8680 0x0 0x34>; + interrupts = <GIC_SPI 73 IRQ_TYPE_EDGE_RISING>; clocks = <&xtal>, <&clkc CLKID_SAR_ADC>, <&clkc CLKID_SANA>, diff --git a/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt b/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt new file mode 100644 index 000000000000..674e133b7cd7 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt @@ -0,0 +1,20 @@ +Aspeed ADC + +This device is a 10-bit converter for 16 voltage channels. All inputs are +single ended. + +Required properties: +- compatible: Should be "aspeed,ast2400-adc" or "aspeed,ast2500-adc" +- reg: memory window mapping address and length +- clocks: Input clock used to derive the sample clock. Expected to be the + SoC's APB clock. +- #io-channel-cells: Must be set to <1> to indicate channels are selected + by index. + +Example: + adc@1e6e9000 { + compatible = "aspeed,ast2400-adc"; + reg = <0x1e6e9000 0xb0>; + clocks = <&clk_apb>; + #io-channel-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/cpcap-adc.txt b/Documentation/devicetree/bindings/iio/adc/cpcap-adc.txt new file mode 100644 index 000000000000..487ea966858e --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/cpcap-adc.txt @@ -0,0 +1,18 @@ +Motorola CPCAP PMIC ADC binding + +Required properties: +- compatible: Should be "motorola,cpcap-adc" or "motorola,mapphone-cpcap-adc" +- interrupt-parent: The interrupt controller +- interrupts: The interrupt number for the ADC device +- interrupt-names: Should be "adcdone" +- #io-channel-cells: Number of cells in an IIO specifier + +Example: + +cpcap_adc: adc { + compatible = "motorola,mapphone-cpcap-adc"; + interrupt-parent = <&cpcap>; + interrupts = <8 IRQ_TYPE_NONE>; + interrupt-names = "adcdone"; + #io-channel-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/ltc2497.txt b/Documentation/devicetree/bindings/iio/adc/ltc2497.txt new file mode 100644 index 000000000000..a237ed99c0d8 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ltc2497.txt @@ -0,0 +1,13 @@ +* Linear Technology / Analog Devices LTC2497 ADC + +Required properties: + - compatible: Must be "lltc,ltc2497" + - reg: Must contain the ADC I2C address + - vref-supply: The regulator supply for ADC reference voltage + +Example: + ltc2497: adc@76 { + compatible = "lltc,ltc2497"; + reg = <0x76>; + vref-supply = <<c2497_reg>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/max1118.txt b/Documentation/devicetree/bindings/iio/adc/max1118.txt new file mode 100644 index 000000000000..cf33d0b15a6d --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/max1118.txt @@ -0,0 +1,21 @@ +* MAX1117/MAX1118/MAX1119 8-bit, dual-channel ADCs + +Required properties: + - compatible: Should be one of + * "maxim,max1117" + * "maxim,max1118" + * "maxim,max1119" + - reg: spi chip select number for the device + - (max1118 only) vref-supply: The regulator supply for ADC reference voltage + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Example: +adc@0 { + compatible = "maxim,max1118"; + reg = <0>; + vref-supply = <&vdd_supply>; + spi-max-frequency = <1000000>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/max9611.txt b/Documentation/devicetree/bindings/iio/adc/max9611.txt new file mode 100644 index 000000000000..ab4f43145ae5 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/max9611.txt @@ -0,0 +1,27 @@ +* Maxim max9611/max9612 current sense amplifier with 12-bits ADC interface + +Maxim max9611/max9612 is an high-side current sense amplifier with integrated +12-bits ADC communicating over I2c bus. +The device node for this driver shall be a child of a I2c controller. + +Required properties + - compatible: Should be "maxim,max9611" or "maxim,max9612" + - reg: The 7-bits long I2c address of the device + - shunt-resistor-micro-ohms: Value, in micro Ohms, of the current sense shunt + resistor + +Example: + +&i2c4 { + csa: adc@7c { + compatible = "maxim,max9611"; + reg = <0x7c>; + + shunt-resistor-micro-ohms = <5000>; + }; +}; + +This device node describes a current sense amplifier sitting on I2c4 bus +with address 0x7c (read address is 0xf9, write address is 0xf8). +A sense resistor of 0,005 Ohm is installed between RS+ and RS- current-sensing +inputs. diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,pm8xxx-xoadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,pm8xxx-xoadc.txt index 53cd146d8096..3ae06127789e 100644 --- a/Documentation/devicetree/bindings/iio/adc/qcom,pm8xxx-xoadc.txt +++ b/Documentation/devicetree/bindings/iio/adc/qcom,pm8xxx-xoadc.txt @@ -19,32 +19,42 @@ Required properties: with PMIC variant but is typically something like 2.2 or 1.8V. The following required properties are standard for IO channels, see -iio-bindings.txt for more details: +iio-bindings.txt for more details, but notice that this particular +ADC has a special addressing scheme that require two cells for +identifying each ADC channel: -- #address-cells: should be set to <1> +- #address-cells: should be set to <2>, the first cell is the + prescaler (on PM8058) or premux (on PM8921) with two valid bits + so legal values are 0x00, 0x01 or 0x02. The second cell + is the main analog mux setting (0x00..0x0f). The combination + of prescaler/premux and analog mux uniquely addresses a hardware + channel on all systems. - #size-cells: should be set to <0> -- #io-channel-cells: should be set to <1> +- #io-channel-cells: should be set to <2>, again the cells are + precaler or premux followed by the analog muxing line. - interrupts: should refer to the parent PMIC interrupt controller and reference the proper ADC interrupt. Required subnodes: -The ADC channels are configured as subnodes of the ADC. Since some of -them are used for calibrating the ADC, these nodes are compulsory: +The ADC channels are configured as subnodes of the ADC. + +Since some of them are used for calibrating the ADC, these nodes are +compulsory: adc-channel@c { - reg = <0x0c>; + reg = <0x00 0x0c>; }; adc-channel@d { - reg = <0x0d>; + reg = <0x00 0x0d>; }; adc-channel@f { - reg = <0x0f>; + reg = <0x00 0x0f>; }; These three nodes are used for absolute and ratiometric calibration @@ -52,13 +62,13 @@ and only need to have these reg values: they are by hardware definition 1:1 ratio converters that sample 625, 1250 and 0 milliV and create an interpolation calibration for all other ADCs. -Optional subnodes: any channels other than channel 0x0c, 0x0d and -0x0f are optional. +Optional subnodes: any channels other than channels [0x00 0x0c], +[0x00 0x0d] and [0x00 0x0f] are optional. Required channel node properties: - reg: should contain the hardware channel number in the range - 0 .. 0x0f (4 bits). The hardware only supports 16 channels. + 0 .. 0xff (8 bits). Optional channel node properties: @@ -94,56 +104,54 @@ Example: xoadc: xoadc@197 { compatible = "qcom,pm8058-adc"; reg = <0x197>; - interrupt-parent = <&pm8058>; - interrupts = <76 1>; - #address-cells = <1>; + interrupts-extended = <&pm8058 76 IRQ_TYPE_EDGE_RISING>; + #address-cells = <2>; #size-cells = <0>; - #io-channel-cells = <1>; + #io-channel-cells = <2>; vcoin: adc-channel@0 { - reg = <0x00>; + reg = <0x00 0x00>; }; vbat: adc-channel@1 { - reg = <0x01>; + reg = <0x00 0x01>; }; dcin: adc-channel@2 { - reg = <0x02>; + reg = <0x00 0x02>; }; ichg: adc-channel@3 { - reg = <0x03>; + reg = <0x00 0x03>; }; vph_pwr: adc-channel@4 { - reg = <0x04>; + reg = <0x00 0x04>; }; usb_vbus: adc-channel@a { - reg = <0x0a>; + reg = <0x00 0x0a>; }; die_temp: adc-channel@b { - reg = <0x0b>; + reg = <0x00 0x0b>; }; ref_625mv: adc-channel@c { - reg = <0x0c>; + reg = <0x00 0x0c>; }; ref_1250mv: adc-channel@d { - reg = <0x0d>; + reg = <0x00 0x0d>; }; ref_325mv: adc-channel@e { - reg = <0x0e>; + reg = <0x00 0x0e>; }; ref_muxoff: adc-channel@f { - reg = <0x0f>; + reg = <0x00 0x0f>; }; }; - /* IIO client node */ iio-hwmon { compatible = "iio-hwmon"; - io-channels = <&xoadc 0x01>, /* Battery */ - <&xoadc 0x02>, /* DC in (charger) */ - <&xoadc 0x04>, /* VPH the main system voltage */ - <&xoadc 0x0b>, /* Die temperature */ - <&xoadc 0x0c>, /* Reference voltage 1.25V */ - <&xoadc 0x0d>, /* Reference voltage 0.625V */ - <&xoadc 0x0e>; /* Reference voltage 0.325V */ + io-channels = <&xoadc 0x00 0x01>, /* Battery */ + <&xoadc 0x00 0x02>, /* DC in (charger) */ + <&xoadc 0x00 0x04>, /* VPH the main system voltage */ + <&xoadc 0x00 0x0b>, /* Die temperature */ + <&xoadc 0x00 0x0c>, /* Reference voltage 1.25V */ + <&xoadc 0x00 0x0d>, /* Reference voltage 0.625V */ + <&xoadc 0x00 0x0e>; /* Reference voltage 0.325V */ }; diff --git a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt index 205593f56fe7..e0a9b9d6d6fd 100644 --- a/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt +++ b/Documentation/devicetree/bindings/iio/adc/rockchip-saradc.txt @@ -4,6 +4,7 @@ Required properties: - compatible: should be "rockchip,<name>-saradc" or "rockchip,rk3066-tsadc" - "rockchip,saradc": for rk3188, rk3288 - "rockchip,rk3066-tsadc": for rk3036 + - "rockchip,rk3328-saradc", "rockchip,rk3399-saradc": for rk3328 - "rockchip,rk3399-saradc": for rk3399 - reg: physical base address of the controller and length of memory mapped diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt index 5dfc88ec24a4..e35f9f1b3200 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt @@ -57,6 +57,9 @@ Optional properties: - dmas: Phandle to dma channel for this ADC instance. See ../../dma/dma.txt for details. - dma-names: Must be "rx" when dmas property is being used. +- assigned-resolution-bits: Resolution (bits) to use for conversions. Must + match device available resolutions (e.g. can be 6, 8, 10 or 12 on stm32f4). + Default is maximum resolution if unset. Example: adc: adc@40012000 { @@ -84,6 +87,7 @@ Example: st,adc-channels = <8>; dmas = <&dma2 0 0 0x400 0x0>; dma-names = "rx"; + assigned-resolution-bits = <8>; }; ... other adc child nodes follow... diff --git a/Documentation/devicetree/bindings/iio/dac/ltc2632.txt b/Documentation/devicetree/bindings/iio/dac/ltc2632.txt new file mode 100644 index 000000000000..eb911e5a8ab4 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/ltc2632.txt @@ -0,0 +1,23 @@ +Linear Technology LTC2632 DAC device driver + +Required properties: + - compatible: Has to contain one of the following: + lltc,ltc2632-l12 + lltc,ltc2632-l10 + lltc,ltc2632-l8 + lltc,ltc2632-h12 + lltc,ltc2632-h10 + lltc,ltc2632-h8 + +Property rules described in Documentation/devicetree/bindings/spi/spi-bus.txt +apply. In particular, "reg" and "spi-max-frequency" properties must be given. + +Example: + + spi_master { + dac: ltc2632@0 { + compatible = "lltc,ltc2632-l12"; + reg = <0>; /* CS0 */ + spi-max-frequency = <1000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.txt b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.txt new file mode 100644 index 000000000000..bcee71f808d0 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.txt @@ -0,0 +1,61 @@ +STMicroelectronics STM32 DAC + +The STM32 DAC is a 12-bit voltage output digital-to-analog converter. The DAC +may be configured in 8 or 12-bit mode. It has two output channels, each with +its own converter. +It has built-in noise and triangle waveform generator and supports external +triggers for conversions. The DAC's output buffer allows a high drive output +current. + +Contents of a stm32 dac root node: +----------------------------------- +Required properties: +- compatible: Must be "st,stm32h7-dac-core". +- reg: Offset and length of the device's register set. +- clocks: Must contain an entry for pclk (which feeds the peripheral bus + interface) +- clock-names: Must be "pclk". +- vref-supply: Phandle to the vref+ input analog reference supply. +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties: +- resets: Must contain the phandle to the reset controller. +- A pinctrl state named "default" for each DAC channel may be defined to set + DAC_OUTx pin in mode of operation for analog output on external pin. + +Contents of a stm32 dac child node: +----------------------------------- +DAC core node should contain at least one subnode, representing a +DAC instance/channel available on the machine. + +Required properties: +- compatible: Must be "st,stm32-dac". +- reg: Must be either 1 or 2, to define (single) channel in use +- #io-channel-cells = <1>: See the IIO bindings section "IIO consumers" in + Documentation/devicetree/bindings/iio/iio-bindings.txt + +Example: + dac: dac@40007400 { + compatible = "st,stm32h7-dac-core"; + reg = <0x40007400 0x400>; + clocks = <&clk>; + clock-names = "pclk"; + vref-supply = <®_vref>; + pinctrl-names = "default"; + pinctrl-0 = <&dac_out1 &dac_out2>; + #address-cells = <1>; + #size-cells = <0>; + + dac1: dac@1 { + compatible = "st,stm32-dac"; + #io-channels-cells = <1>; + reg = <1>; + }; + + dac2: dac@2 { + compatible = "st,stm32-dac"; + #io-channels-cells = <1>; + reg = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/health/max30102.txt b/Documentation/devicetree/bindings/iio/health/max30102.txt new file mode 100644 index 000000000000..c695e7cbeefb --- /dev/null +++ b/Documentation/devicetree/bindings/iio/health/max30102.txt @@ -0,0 +1,30 @@ +Maxim MAX30102 heart rate and pulse oximeter sensor + +* https://datasheets.maximintegrated.com/en/ds/MAX30102.pdf + +Required properties: + - compatible: must be "maxim,max30102" + - reg: the I2C address of the sensor + - interrupt-parent: should be the phandle for the interrupt controller + - interrupts: the sole interrupt generated by the device + + Refer to interrupt-controller/interrupts.txt for generic + interrupt client node bindings. + +Optional properties: + - maxim,red-led-current-microamp: configuration for RED LED current + - maxim,ir-led-current-microamp: configuration for IR LED current + + Note that each step is approximately 200 microamps, ranging from 0 uA to + 50800 uA. + +Example: + +max30100@57 { + compatible = "maxim,max30102"; + reg = <0x57>; + maxim,red-led-current-microamp = <7000>; + maxim,ir-led-current-microamp = <7000>; + interrupt-parent = <&gpio1>; + interrupts = <16 2>; +}; diff --git a/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt b/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt index a9fc11e43b45..2b4514592f83 100644 --- a/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt +++ b/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt @@ -3,14 +3,21 @@ InvenSense MPU-6050 Six-Axis (Gyro + Accelerometer) MEMS MotionTracking Device http://www.invensense.com/mems/gyro/mpu6050.html Required properties: - - compatible : should be "invensense,mpu6050" + - compatible : should be one of + "invensense,mpu6050" + "invensense,mpu6500" + "invensense,mpu9150" + "invensense,mpu9250" + "invensense,icm20608" - reg : the I2C address of the sensor - interrupt-parent : should be the phandle for the interrupt controller - interrupts : interrupt mapping for GPIO IRQ Optional properties: - mount-matrix: an optional 3x3 mounting rotation matrix - + - i2c-gate node. These devices also support an auxiliary i2c bus. This is + simple enough to be described using the i2c-gate binding. See + i2c/i2c-gate.txt for more details. Example: mpu6050@68 { @@ -28,3 +35,19 @@ Example: "0", /* y2 */ "0.984807753012208"; /* z2 */ }; + + + mpu9250@68 { + compatible = "invensense,mpu9250"; + reg = <0x68>; + interrupt-parent = <&gpio3>; + interrupts = <21 1>; + i2c-gate { + #address-cells = <1>; + #size-cells = <0>; + ax8975@c { + compatible = "ak,ak8975"; + reg = <0x0c>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt index cf81afdf7803..8305fb05ffda 100644 --- a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt +++ b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt @@ -3,6 +3,8 @@ Required properties: - compatible: must be one of: "st,lsm6ds3" + "st,lsm6ds3h" + "st,lsm6dsl" "st,lsm6dsm" - reg: i2c address of the sensor / spi cs line diff --git a/Documentation/devicetree/bindings/iio/light/vl6180.txt b/Documentation/devicetree/bindings/iio/light/vl6180.txt new file mode 100644 index 000000000000..2c52952715a0 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/vl6180.txt @@ -0,0 +1,15 @@ +STMicro VL6180 - ALS, range and proximity sensor + +Link to datasheet: http://www.st.com/resource/en/datasheet/vl6180x.pdf + +Required properties: + + -compatible: should be "st,vl6180" + -reg: the I2C address of the sensor + +Example: + +vl6180@29 { + compatible = "st,vl6180"; + reg = <0x29>; +}; diff --git a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.txt b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.txt new file mode 100644 index 000000000000..d4dc7a227e2e --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.txt @@ -0,0 +1,28 @@ +* Devantech SRF04 ultrasonic range finder + Bit-banging driver using two GPIOs + +Required properties: + - compatible: Should be "devantech,srf04" + + - trig-gpios: Definition of the GPIO for the triggering (output) + This GPIO is set for about 10 us by the driver to tell the + device it should initiate the measurement cycle. + + - echo-gpios: Definition of the GPIO for the echo (input) + This GPIO is set by the device as soon as an ultrasonic + burst is sent out and reset when the first echo is + received. + Thus this GPIO is set while the ultrasonic waves are doing + one round trip. + It needs to be an GPIO which is able to deliver an + interrupt because the time between two interrupts is + measured in the driver. + See Documentation/devicetree/bindings/gpio/gpio.txt for + information on how to specify a consumer gpio. + +Example: +srf04@0 { + compatible = "devantech,srf04"; + trig-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; + echo-gpios = <&gpio2 6 GPIO_ACTIVE_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/input/cpcap-pwrbutton.txt b/Documentation/devicetree/bindings/input/cpcap-pwrbutton.txt new file mode 100644 index 000000000000..0dd0076daf71 --- /dev/null +++ b/Documentation/devicetree/bindings/input/cpcap-pwrbutton.txt @@ -0,0 +1,20 @@ +Motorola CPCAP on key + +This module is part of the CPCAP. For more details about the whole +chip see Documentation/devicetree/bindings/mfd/motorola-cpcap.txt. + +This module provides a simple power button event via an Interrupt. + +Required properties: +- compatible: should be one of the following + - "motorola,cpcap-pwrbutton" +- interrupts: irq specifier for CPCAP's ON IRQ + +Example: + +&cpcap { + cpcap_pwrbutton: pwrbutton { + compatible = "motorola,cpcap-pwrbutton"; + interrupts = <23 IRQ_TYPE_NONE>; + }; +}; diff --git a/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt b/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt index d0ea09ba249f..570dc10f0cd7 100644 --- a/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt +++ b/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt @@ -24,6 +24,8 @@ Optional Properties: - debounce-delay-ms: debounce interval in milliseconds - col-scan-delay-us: delay, measured in microseconds, that is needed before we can scan keypad after activating column gpio +- drive-inactive-cols: drive inactive columns during scan, + default is to turn inactive columns into inputs. Example: matrix-keypad { diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt index 488edcb264c4..28e8bd8b7d64 100644 --- a/Documentation/devicetree/bindings/input/hid-over-i2c.txt +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.txt @@ -17,6 +17,22 @@ Required properties: - interrupt-parent: the phandle for the interrupt controller - interrupts: interrupt line +Additional optional properties: + +Some devices may support additional optional properties to help with, e.g., +power sequencing. The following properties can be supported by one or more +device-specific compatible properties, which should be used in addition to the +"hid-over-i2c" string. + +- compatible: + * "wacom,w9013" (Wacom W9013 digitizer). Supports: + - vdd-supply + - post-power-on-delay-ms + +- vdd-supply: phandle of the regulator that provides the supply voltage. +- post-power-on-delay-ms: time required by the device after enabling its regulators + before it is ready for communication. Must be used with 'vdd-supply'. + Example: i2c-hid-dev@2c { diff --git a/Documentation/devicetree/bindings/input/pwm-beeper.txt b/Documentation/devicetree/bindings/input/pwm-beeper.txt index 529408b4431a..8fc0e48c20db 100644 --- a/Documentation/devicetree/bindings/input/pwm-beeper.txt +++ b/Documentation/devicetree/bindings/input/pwm-beeper.txt @@ -8,6 +8,7 @@ Required properties: Optional properties: - amp-supply: phandle to a regulator that acts as an amplifier for the beeper +- beeper-hz: bell frequency in Hz Example: diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt index 4ed467b1e402..64bb990075c3 100644 --- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt +++ b/Documentation/devicetree/bindings/input/qcom,pm8xxx-vib.txt @@ -7,6 +7,7 @@ PROPERTIES Value type: <string> Definition: must be one of: "qcom,pm8058-vib" + "qcom,pm8916-vib" "qcom,pm8921-vib" - reg: diff --git a/Documentation/devicetree/bindings/input/rotary-encoder.txt b/Documentation/devicetree/bindings/input/rotary-encoder.txt index e85ce3dea480..f99fe5cdeaec 100644 --- a/Documentation/devicetree/bindings/input/rotary-encoder.txt +++ b/Documentation/devicetree/bindings/input/rotary-encoder.txt @@ -12,7 +12,7 @@ Optional properties: - rotary-encoder,relative-axis: register a relative axis rather than an absolute one. Relative axis will only generate +1/-1 events on the input device, hence no steps need to be passed. -- rotary-encoder,rollover: Automatic rollove when the rotary value becomes +- rotary-encoder,rollover: Automatic rollover when the rotary value becomes greater than the specified steps or smaller than 0. For absolute axis only. - rotary-encoder,steps-per-period: Number of steps (stable states) per period. The values have the following meaning: diff --git a/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt b/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt index e3f22d23fc8f..3c8614c451f2 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt @@ -35,6 +35,7 @@ Optional properties: - adi,conversion-interval: : 0 : convert one time only 1-255: 515us + val * 35us (up to 9.440ms) This property has to be a '/bits/ 8' value +- gpio-controller : Switch AUX/VBAT/GPIO pin to GPIO mode Example: @@ -51,3 +52,21 @@ Example: adi,averaging = /bits/ 8 <1>; adi,conversion-interval = /bits/ 8 <255>; }; + + ad7879@1 { + compatible = "adi,ad7879"; + spi-max-frequency = <5000000>; + reg = <1>; + spi-cpol; + spi-cpha; + gpio-controller; + interrupt-parent = <&gpio1>; + interrupts = <13 IRQ_TYPE_EDGE_FALLING>; + touchscreen-max-pressure = <4096>; + adi,resistance-plate-x = <120>; + adi,first-conversion-delay = /bits/ 8 <3>; + adi,acquisition-time = /bits/ 8 <1>; + adi,median-filter-size = /bits/ 8 <2>; + adi,averaging = /bits/ 8 <1>; + adi,conversion-interval = /bits/ 8 <255>; + }; diff --git a/Documentation/devicetree/bindings/input/ads7846.txt b/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt index 9fc47b006fd1..9fc47b006fd1 100644 --- a/Documentation/devicetree/bindings/input/ads7846.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/ads7846.txt diff --git a/Documentation/devicetree/bindings/input/touchscreen/ar1021.txt b/Documentation/devicetree/bindings/input/touchscreen/ar1021.txt new file mode 100644 index 000000000000..e459e8546f34 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/ar1021.txt @@ -0,0 +1,16 @@ +* Microchip AR1020 and AR1021 touchscreen interface (I2C) + +Required properties: +- compatible : "microchip,ar1021-i2c" +- reg : I2C slave address +- interrupt-parent : the phandle for the interrupt controller +- interrupts : touch controller interrupt + +Example: + + touchscreen@4d { + compatible = "microchip,ar1021-i2c"; + reg = <0x4d>; + interrupt-parent = <&gpio3>; + interrupts = <11 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/max11801-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/max11801-ts.txt new file mode 100644 index 000000000000..40ac0fe94df6 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/max11801-ts.txt @@ -0,0 +1,18 @@ +* MAXI MAX11801 Resistive touch screen controller with i2c interface + +Required properties: +- compatible: must be "maxim,max11801" +- reg: i2c slave address +- interrupt-parent: the phandle for the interrupt controller +- interrupts: touch controller interrupt + +Example: + +&i2c1 { + max11801: touchscreen@48 { + compatible = "maxim,max11801"; + reg = <0x48>; + interrupt-parent = <&gpio3>; + interrupts = <31 IRQ_TYPE_EDGE_FALLING>; + }; +}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt index ce85ee508238..6aa625e0cb8d 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt @@ -1,7 +1,12 @@ * GSL 1680 touchscreen controller Required properties: -- compatible : "silead,gsl1680" +- compatible : Must be one of the following, depending on the model: + "silead,gsl1680" + "silead,gsl1688" + "silead,gsl3670" + "silead,gsl3675" + "silead,gsl3692" - reg : I2C slave address of the chip (0x40) - interrupt-parent : a phandle pointing to the interrupt controller serving the interrupt for this chip diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.txt new file mode 100644 index 000000000000..386ab37a383f --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,nvic.txt @@ -0,0 +1,36 @@ +* ARM Nested Vector Interrupt Controller (NVIC) + +The NVIC provides an interrupt controller that is tightly coupled to +Cortex-M based processor cores. The NVIC implemented on different SoCs +vary in the number of interrupts and priority bits per interrupt. + +Main node required properties: + +- compatible : should be one of: + "arm,v6m-nvic" + "arm,v7m-nvic" + "arm,v8m-nvic" +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt source. The type shall be a <u32> and the value shall be 2. + + The 1st cell contains the interrupt number for the interrupt type. + + The 2nd cell is the priority of the interrupt. + +- reg : Specifies base physical address(s) and size of the NVIC registers. + This is at a fixed address (0xe000e100) and size (0xc00). + +- arm,num-irq-priority-bits: The number of priority bits implemented by the + given SoC + +Example: + + intc: interrupt-controller@e000e100 { + compatible = "arm,v7m-nvic"; + #interrupt-cells = <2>; + #address-cells = <1>; + interrupt-controller; + reg = <0xe000e100 0xc00>; + arm,num-irq-priority-bits = <4>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/cortina,gemini-interrupt-controller.txt b/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.txt index 97c1167fa533..24428d47f487 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/cortina,gemini-interrupt-controller.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/faraday,ftintc010.txt @@ -1,9 +1,12 @@ -* Cortina Systems Gemini interrupt controller +* Faraday Technologt FTINTC010 interrupt controller -This interrupt controller is found on the Gemini SoCs. +This interrupt controller is a stock IP block from Faraday Technology found +in the Gemini SoCs and other designs. Required properties: -- compatible: must be "cortina,gemini-interrupt-controller" +- compatible: must be one of + "faraday,ftintc010" + "cortina,gemini-interrupt-controller" (deprecated) - reg: The register bank for the interrupt controller. - interrupt-controller: Identifies the node as an interrupt controller - #interrupt-cells: The number of cells to define the interrupts. @@ -15,7 +18,7 @@ Required properties: Example: interrupt-controller@48000000 { - compatible = "cortina,gemini-interrupt-controller"; + compatible = "faraday,ftintc010" reg = <0x48000000 0x1000>; interrupt-controller; #interrupt-cells = <2>; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt new file mode 100644 index 000000000000..a7efdbc3de5b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,cirq.txt @@ -0,0 +1,35 @@ +* Mediatek 27xx cirq + +In Mediatek SOCs, the CIRQ is a low power interrupt controller designed to +work outside MCUSYS which comprises with Cortex-Ax cores,CCI and GIC. +The external interrupts (outside MCUSYS) will feed through CIRQ and connect +to GIC in MCUSYS. When CIRQ is enabled, it will record the edge-sensitive +interrupts and generate a pulse signal to parent interrupt controller when +flush command is executed. With CIRQ, MCUSYS can be completely turned off +to improve the system power consumption without losing interrupts. + +Required properties: +- compatible: should be one of + - "mediatek,mt2701-cirq" for mt2701 CIRQ + - "mediatek,mt8135-cirq" for mt8135 CIRQ + - "mediatek,mt8173-cirq" for mt8173 CIRQ + and "mediatek,cirq" as a fallback. +- interrupt-controller : Identifies the node as an interrupt controller. +- #interrupt-cells : Use the same format as specified by GIC in arm,gic.txt. +- interrupt-parent: phandle of irq parent for cirq. The parent must + use the same interrupt-cells format as GIC. +- reg: Physical base address of the cirq registers and length of memory + mapped region. +- mediatek,ext-irq-range: Identifies external irq number range in different + SOCs. + +Example: + cirq: interrupt-controller@10204000 { + compatible = "mediatek,mt2701-cirq", + "mediatek,mtk-cirq"; + interrupt-controller; + #interrupt-cells = <3>; + interrupt-parent = <&sysirq>; + reg = <0 0x10204000 0 0x400>; + mediatek,ext-irq-start = <32 200>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt index 9d1d72c65489..a89c03bb1a81 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt @@ -21,13 +21,16 @@ Required properties: - interrupt-parent: phandle of irq parent for sysirq. The parent must use the same interrupt-cells format as GIC. - reg: Physical base address of the intpol registers and length of memory - mapped region. + mapped region. Could be multiple bases here. Ex: mt6797 needs 2 reg, others + need 1. Example: - sysirq: interrupt-controller@10200100 { - compatible = "mediatek,mt6589-sysirq", "mediatek,mt6577-sysirq"; + sysirq: intpol-controller@10200620 { + compatible = "mediatek,mt6797-sysirq", + "mediatek,mt6577-sysirq"; interrupt-controller; #interrupt-cells = <3>; interrupt-parent = <&gic>; - reg = <0 0x10200100 0 0x1c>; + reg = <0 0x10220620 0 0x20>, + <0 0x10220690 0 0x10>; }; diff --git a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt index 6f28969af9dc..028268fd99ee 100644 --- a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt +++ b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt @@ -6,7 +6,9 @@ perform in-band IPMI communication with their host. Required properties: -- compatible : should be "aspeed,ast2400-ibt-bmc" +- compatible : should be one of + "aspeed,ast2400-ibt-bmc" + "aspeed,ast2500-ibt-bmc" - reg: physical address and size of the registers Optional properties: diff --git a/Documentation/devicetree/bindings/leds/backlight/arcxcnn_bl.txt b/Documentation/devicetree/bindings/leds/backlight/arcxcnn_bl.txt new file mode 100644 index 000000000000..230abdefd6e7 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/arcxcnn_bl.txt @@ -0,0 +1,33 @@ +Binding for ArcticSand arc2c0608 LED driver + +Required properties: +- compatible: should be "arc,arc2c0608" +- reg: slave address + +Optional properties: +- default-brightness: brightness value on boot, value from: 0-4095 +- label: The name of the backlight device + See Documentation/devicetree/bindings/leds/common.txt +- led-sources: List of enabled channels from 0 to 5. + See Documentation/devicetree/bindings/leds/common.txt + +- arc,led-config-0: setting for register ILED_CONFIG_0 +- arc,led-config-1: setting for register ILED_CONFIG_1 +- arc,dim-freq: PWM mode frequence setting (bits [3:0] used) +- arc,comp-config: setting for register CONFIG_COMP +- arc,filter-config: setting for register FILTER_CONFIG +- arc,trim-config: setting for register IMAXTUNE + +Note: Optional properties not specified will default to values in IC EPROM + +Example: + +arc2c0608@30 { + compatible = "arc,arc2c0608"; + reg = <0x30>; + default-brightness = <500>; + label = "lcd-backlight"; + linux,default-trigger = "backlight"; + led-sources = <0 1 2 5>; +}; + diff --git a/Documentation/devicetree/bindings/leds/leds-cpcap.txt b/Documentation/devicetree/bindings/leds/leds-cpcap.txt new file mode 100644 index 000000000000..ebf7cdc7f70c --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-cpcap.txt @@ -0,0 +1,29 @@ +Motorola CPCAP PMIC LEDs +------------------------ + +This module is part of the CPCAP. For more details about the whole +chip see Documentation/devicetree/bindings/mfd/motorola-cpcap.txt. + +Requires node properties: +- compatible: should be one of + * "motorola,cpcap-led-mdl" (Main Display Lighting) + * "motorola,cpcap-led-kl" (Keyboard Lighting) + * "motorola,cpcap-led-adl" (Aux Display Lighting) + * "motorola,cpcap-led-red" (Red Triode) + * "motorola,cpcap-led-green" (Green Triode) + * "motorola,cpcap-led-blue" (Blue Triode) + * "motorola,cpcap-led-cf" (Camera Flash) + * "motorola,cpcap-led-bt" (Bluetooth) + * "motorola,cpcap-led-cp" (Camera Privacy LED) +- label: see Documentation/devicetree/bindings/leds/common.txt +- vdd-supply: A phandle to the regulator powering the LED + +Example: + +&cpcap { + cpcap_led_red: red-led { + compatible = "motorola,cpcap-led-red"; + label = "cpcap:red"; + vdd-supply = <&sw5>; + }; +}; diff --git a/Documentation/devicetree/bindings/leds/leds-mt6323.txt b/Documentation/devicetree/bindings/leds/leds-mt6323.txt new file mode 100644 index 000000000000..45bf9f7d85f3 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-mt6323.txt @@ -0,0 +1,60 @@ +Device Tree Bindings for LED support on MT6323 PMIC + +MT6323 LED controller is subfunction provided by MT6323 PMIC, so the LED +controllers are defined as the subnode of the function node provided by MT6323 +PMIC controller that is being defined as one kind of Muti-Function Device (MFD) +using shared bus called PMIC wrapper for each subfunction to access remote +MT6323 PMIC hardware. + +For MT6323 MFD bindings see: +Documentation/devicetree/bindings/mfd/mt6397.txt +For MediaTek PMIC wrapper bindings see: +Documentation/devicetree/bindings/soc/mediatek/pwrap.txt + +Required properties: +- compatible : Must be "mediatek,mt6323-led" +- address-cells : Must be 1 +- size-cells : Must be 0 + +Each led is represented as a child node of the mediatek,mt6323-led that +describes the initial behavior for each LED physically and currently only four +LED child nodes can be supported. + +Required properties for the LED child node: +- reg : LED channel number (0..3) + +Optional properties for the LED child node: +- label : See Documentation/devicetree/bindings/leds/common.txt +- linux,default-trigger : See Documentation/devicetree/bindings/leds/common.txt +- default-state: See Documentation/devicetree/bindings/leds/common.txt + +Example: + + mt6323: pmic { + compatible = "mediatek,mt6323"; + + ... + + mt6323led: leds { + compatible = "mediatek,mt6323-led"; + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + label = "LED0"; + linux,default-trigger = "timer"; + default-state = "on"; + }; + led@1 { + reg = <1>; + label = "LED1"; + default-state = "off"; + }; + led@2 { + reg = <2>; + label = "LED2"; + default-state = "on"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/leds-pca9532.txt b/Documentation/devicetree/bindings/leds/leds-pca9532.txt index 198f3ba0e01f..f769c52e3643 100644 --- a/Documentation/devicetree/bindings/leds/leds-pca9532.txt +++ b/Documentation/devicetree/bindings/leds/leds-pca9532.txt @@ -17,6 +17,8 @@ Optional sub-node properties: - label: see Documentation/devicetree/bindings/leds/common.txt - type: Output configuration, see dt-bindings/leds/leds-pca9532.h (default NONE) - linux,default-trigger: see Documentation/devicetree/bindings/leds/common.txt + - default-state: see Documentation/devicetree/bindings/leds/common.txt + This property is only valid for sub-nodes of type <PCA9532_TYPE_LED>. Example: #include <dt-bindings/leds/leds-pca9532.h> @@ -33,6 +35,14 @@ Example: label = "pca:green:power"; type = <PCA9532_TYPE_LED>; }; + kernel-booting { + type = <PCA9532_TYPE_LED>; + default-state = "on"; + }; + sys-stat { + type = <PCA9532_TYPE_LED>; + default-state = "keep"; // don't touch, was set by U-Boot + }; }; For more product information please see the link below: diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt b/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt new file mode 100644 index 000000000000..752ae6b00d26 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/brcm,iproc-flexrm-mbox.txt @@ -0,0 +1,59 @@ +Broadcom FlexRM Ring Manager +============================ +The Broadcom FlexRM ring manager provides a set of rings which can be +used to submit work to offload engines. An SoC may have multiple FlexRM +hardware blocks. There is one device tree entry per FlexRM block. The +FlexRM driver will create a mailbox-controller instance for given FlexRM +hardware block where each mailbox channel is a separate FlexRM ring. + +Required properties: +-------------------- +- compatible: Should be "brcm,iproc-flexrm-mbox" +- reg: Specifies base physical address and size of the FlexRM + ring registers +- msi-parent: Phandles (and potential Device IDs) to MSI controllers + The FlexRM engine will send MSIs (instead of wired + interrupts) to CPU. There is one MSI for each FlexRM ring. + Refer devicetree/bindings/interrupt-controller/msi.txt +- #mbox-cells: Specifies the number of cells needed to encode a mailbox + channel. This should be 3. + + The 1st cell is the mailbox channel number. + + The 2nd cell contains MSI completion threshold. This is the + number of completion messages for which FlexRM will inject + one MSI interrupt to CPU. + + The 3nd cell contains MSI timer value representing time for + which FlexRM will wait to accumulate N completion messages + where N is the value specified by 2nd cell above. If FlexRM + does not get required number of completion messages in time + specified by this cell then it will inject one MSI interrupt + to CPU provided atleast one completion message is available. + +Optional properties: +-------------------- +- dma-coherent: Present if DMA operations made by the FlexRM engine (such + as DMA descriptor access, access to buffers pointed by DMA + descriptors and read/write pointer updates to DDR) are + cache coherent with the CPU. + +Example: +-------- +crypto_mbox: mbox@67000000 { + compatible = "brcm,iproc-flexrm-mbox"; + reg = <0x67000000 0x200000>; + msi-parent = <&gic_its 0x7f00>; + #mbox-cells = <3>; +}; + +crypto@672c0000 { + compatible = "brcm,spu2-v2-crypto"; + reg = <0x672c0000 0x1000>; + mboxes = <&crypto_mbox 0 0x1 0xffff>, + <&crypto_mbox 1 0x1 0xffff>, + <&crypto_mbox 16 0x1 0xffff>, + <&crypto_mbox 17 0x1 0xffff>, + <&crypto_mbox 30 0x1 0xffff>, + <&crypto_mbox 31 0x1 0xffff>; +}; diff --git a/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt b/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt index 411ccf421584..0f3ee81d92c2 100644 --- a/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt +++ b/Documentation/devicetree/bindings/mailbox/brcm,iproc-pdc-mbox.txt @@ -1,9 +1,11 @@ The PDC driver manages data transfer to and from various offload engines on some Broadcom SoCs. An SoC may have multiple PDC hardware blocks. There is -one device tree entry per block. +one device tree entry per block. On some chips, the PDC functionality is +handled by the FA2 (Northstar Plus). Required properties: -- compatible : Should be "brcm,iproc-pdc-mbox". +- compatible : Should be "brcm,iproc-pdc-mbox" or "brcm,iproc-fa2-mbox" for + FA2/Northstar Plus. - reg: Should contain PDC registers location and length. - interrupts: Should contain the IRQ line for the PDC. - #mbox-cells: 1 diff --git a/Documentation/devicetree/bindings/media/atmel-isi.txt b/Documentation/devicetree/bindings/media/atmel-isi.txt index 251f008f220c..332513a151cc 100644 --- a/Documentation/devicetree/bindings/media/atmel-isi.txt +++ b/Documentation/devicetree/bindings/media/atmel-isi.txt @@ -1,51 +1,66 @@ -Atmel Image Sensor Interface (ISI) SoC Camera Subsystem ----------------------------------------------- - -Required properties: -- compatible: must be "atmel,at91sam9g45-isi" -- reg: physical base address and length of the registers set for the device; -- interrupts: should contain IRQ line for the ISI; -- clocks: list of clock specifiers, corresponding to entries in - the clock-names property; -- clock-names: must contain "isi_clk", which is the isi peripherial clock. - -ISI supports a single port node with parallel bus. It should contain one +Atmel Image Sensor Interface (ISI) +---------------------------------- + +Required properties for ISI: +- compatible: must be "atmel,at91sam9g45-isi". +- reg: physical base address and length of the registers set for the device. +- interrupts: should contain IRQ line for the ISI. +- clocks: list of clock specifiers, corresponding to entries in the clock-names + property; please refer to clock-bindings.txt. +- clock-names: required elements: "isi_clk". +- pinctrl-names, pinctrl-0: please refer to pinctrl-bindings.txt. + +ISI supports a single port node with parallel bus. It shall contain one 'port' child node with child 'endpoint' node. Please refer to the bindings defined in Documentation/devicetree/bindings/media/video-interfaces.txt. -Example: - isi: isi@f0034000 { - compatible = "atmel,at91sam9g45-isi"; - reg = <0xf0034000 0x4000>; - interrupts = <37 IRQ_TYPE_LEVEL_HIGH 5>; - - clocks = <&isi_clk>; - clock-names = "isi_clk"; +Endpoint node properties +------------------------ - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_isi>; +- bus-width: <8> or <10> (mandatory) +- hsync-active (default: active high) +- vsync-active (default: active high) +- pclk-sample (default: sample on falling edge) +- remote-endpoint: A phandle to the bus receiver's endpoint node (mandatory). - port { - #address-cells = <1>; - #size-cells = <0>; +Example: - isi_0: endpoint { - remote-endpoint = <&ov2640_0>; - bus-width = <8>; - }; +isi: isi@f0034000 { + compatible = "atmel,at91sam9g45-isi"; + reg = <0xf0034000 0x4000>; + interrupts = <37 IRQ_TYPE_LEVEL_HIGH 5>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_isi_data_0_7>; + clocks = <&isi_clk>; + clock-names = "isi_clk"; + port { + isi_0: endpoint { + remote-endpoint = <&ov2640_0>; + bus-width = <8>; + vsync-active = <1>; + hsync-active = <1>; }; }; +}; - i2c1: i2c@f0018000 { - ov2640: camera@0x30 { - compatible = "ovti,ov2640"; - reg = <0x30>; +i2c1: i2c@f0018000 { + ov2640: camera@30 { + compatible = "ovti,ov2640"; + reg = <0x30>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pck0_as_isi_mck &pinctrl_sensor_power &pinctrl_sensor_reset>; + resetb-gpios = <&pioE 11 GPIO_ACTIVE_LOW>; + pwdn-gpios = <&pioE 13 GPIO_ACTIVE_HIGH>; + clocks = <&pck0>; + clock-names = "xvclk"; + assigned-clocks = <&pck0>; + assigned-clock-rates = <25000000>; - port { - ov2640_0: endpoint { - remote-endpoint = <&isi_0>; - bus-width = <8>; - }; + port { + ov2640_0: endpoint { + remote-endpoint = <&isi_0>; + bus-width = <8>; }; }; }; +}; diff --git a/Documentation/devicetree/bindings/media/i2c/ov2640.txt b/Documentation/devicetree/bindings/media/i2c/ov2640.txt index c429b5bdcaa0..989ce6cb6ac3 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov2640.txt +++ b/Documentation/devicetree/bindings/media/i2c/ov2640.txt @@ -1,8 +1,8 @@ * Omnivision OV2640 CMOS sensor -The Omnivision OV2640 sensor support multiple resolutions output, such as -CIF, SVGA, UXGA. It also can support YUV422/420, RGB565/555 or raw RGB -output format. +The Omnivision OV2640 sensor supports multiple resolutions output, such as +CIF, SVGA, UXGA. It also can support the YUV422/420, RGB565/555 or raw RGB +output formats. Required Properties: - compatible: should be "ovti,ov2640" @@ -20,26 +20,21 @@ Documentation/devicetree/bindings/media/video-interfaces.txt. Example: i2c1: i2c@f0018000 { - ov2640: camera@0x30 { + ov2640: camera@30 { compatible = "ovti,ov2640"; reg = <0x30>; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_pck1 &pinctrl_ov2640_pwdn &pinctrl_ov2640_resetb>; - - resetb-gpios = <&pioE 24 GPIO_ACTIVE_LOW>; - pwdn-gpios = <&pioE 29 GPIO_ACTIVE_HIGH>; - - clocks = <&pck1>; + pinctrl-0 = <&pinctrl_pck0_as_isi_mck &pinctrl_sensor_power &pinctrl_sensor_reset>; + resetb-gpios = <&pioE 11 GPIO_ACTIVE_LOW>; + pwdn-gpios = <&pioE 13 GPIO_ACTIVE_HIGH>; + clocks = <&pck0>; clock-names = "xvclk"; - - assigned-clocks = <&pck1>; + assigned-clocks = <&pck0>; assigned-clock-rates = <25000000>; port { ov2640_0: endpoint { remote-endpoint = <&isi_0>; - bus-width = <8>; }; }; }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov5645.txt b/Documentation/devicetree/bindings/media/i2c/ov5645.txt new file mode 100644 index 000000000000..fd7aec9f8e24 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov5645.txt @@ -0,0 +1,54 @@ +* Omnivision 1/4-Inch 5Mp CMOS Digital Image Sensor + +The Omnivision OV5645 is a 1/4-Inch CMOS active pixel digital image sensor with +an active array size of 2592H x 1944V. It is programmable through a serial I2C +interface. + +Required Properties: +- compatible: Value should be "ovti,ov5645". +- clocks: Reference to the xclk clock. +- clock-names: Should be "xclk". +- clock-frequency: Frequency of the xclk clock. +- enable-gpios: Chip enable GPIO. Polarity is GPIO_ACTIVE_HIGH. This corresponds + to the hardware pin PWDNB which is physically active low. +- reset-gpios: Chip reset GPIO. Polarity is GPIO_ACTIVE_LOW. This corresponds to + the hardware pin RESETB. +- vdddo-supply: Chip digital IO regulator. +- vdda-supply: Chip analog regulator. +- vddd-supply: Chip digital core regulator. + +The device node must contain one 'port' child node for its digital output +video port, in accordance with the video interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + + &i2c1 { + ... + + ov5645: ov5645@78 { + compatible = "ovti,ov5645"; + reg = <0x78>; + + enable-gpios = <&gpio1 6 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio5 20 GPIO_ACTIVE_LOW>; + pinctrl-names = "default"; + pinctrl-0 = <&camera_rear_default>; + + clocks = <&clks 200>; + clock-names = "xclk"; + clock-frequency = <23880000>; + + vdddo-supply = <&camera_dovdd_1v8>; + vdda-supply = <&camera_avdd_2v8>; + vddd-supply = <&camera_dvdd_1v2>; + + port { + ov5645_ep: endpoint { + clock-lanes = <1>; + data-lanes = <0 2>; + remote-endpoint = <&csi0_ep>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov5647.txt b/Documentation/devicetree/bindings/media/i2c/ov5647.txt new file mode 100644 index 000000000000..22e44945b661 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov5647.txt @@ -0,0 +1,35 @@ +Omnivision OV5647 raw image sensor +--------------------------------- + +OV5647 is a raw image sensor with MIPI CSI-2 and CCP2 image data interfaces +and CCI (I2C compatible) control bus. + +Required properties: + +- compatible : "ovti,ov5647". +- reg : I2C slave address of the sensor. +- clocks : Reference to the xclk clock. + +The common video interfaces bindings (see video-interfaces.txt) should be +used to specify link to the image data receiver. The OV5647 device +node should contain one 'port' child node with an 'endpoint' subnode. + +Endpoint node mandatory properties: + +- remote-endpoint: A phandle to the bus receiver's endpoint node. + +Example: + + i2c@2000 { + ... + ov: camera@36 { + compatible = "ovti,ov5647"; + reg = <0x36>; + clocks = <&camera_clk>; + port { + camera_1: endpoint { + remote-endpoint = <&csi1_ep1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/ov7670.txt b/Documentation/devicetree/bindings/media/i2c/ov7670.txt new file mode 100644 index 000000000000..826b6563b009 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov7670.txt @@ -0,0 +1,43 @@ +* Omnivision OV7670 CMOS sensor + +The Omnivision OV7670 sensor supports multiple resolutions output, such as +CIF, SVGA, UXGA. It also can support the YUV422/420, RGB565/555 or raw RGB +output formats. + +Required Properties: +- compatible: should be "ovti,ov7670" +- clocks: reference to the xclk input clock. +- clock-names: should be "xclk". + +Optional Properties: +- reset-gpios: reference to the GPIO connected to the resetb pin, if any. + Active is low. +- powerdown-gpios: reference to the GPIO connected to the pwdn pin, if any. + Active is high. + +The device node must contain one 'port' child node for its digital output +video port, in accordance with the video interface bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + + i2c1: i2c@f0018000 { + ov7670: camera@21 { + compatible = "ovti,ov7670"; + reg = <0x21>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pck0_as_isi_mck &pinctrl_sensor_power &pinctrl_sensor_reset>; + reset-gpios = <&pioE 11 GPIO_ACTIVE_LOW>; + powerdown-gpios = <&pioE 13 GPIO_ACTIVE_HIGH>; + clocks = <&pck0>; + clock-names = "xclk"; + assigned-clocks = <&pck0>; + assigned-clock-rates = <25000000>; + + port { + ov7670_0: endpoint { + remote-endpoint = <&isi_0>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt new file mode 100644 index 000000000000..3813947b4d4f --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt @@ -0,0 +1,37 @@ +* Mediatek JPEG Decoder + +Mediatek JPEG Decoder is the JPEG decode hardware present in Mediatek SoCs + +Required properties: +- compatible : must be one of the following string: + "mediatek,mt8173-jpgdec" + "mediatek,mt2701-jpgdec" +- reg : physical base address of the jpeg decoder registers and length of + memory mapped region. +- interrupts : interrupt number to the interrupt controller. +- clocks: device clocks, see + Documentation/devicetree/bindings/clock/clock-bindings.txt for details. +- clock-names: must contain "jpgdec-smi" and "jpgdec". +- power-domains: a phandle to the power domain, see + Documentation/devicetree/bindings/power/power_domain.txt for details. +- mediatek,larb: must contain the local arbiters in the current Socs, see + Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt + for details. +- iommus: should point to the respective IOMMU block with master port as + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + for details. + +Example: + jpegdec: jpegdec@15004000 { + compatible = "mediatek,mt2701-jpgdec"; + reg = <0 0x15004000 0 0x1000>; + interrupts = <GIC_SPI 143 IRQ_TYPE_LEVEL_LOW>; + clocks = <&imgsys CLK_IMG_JPGDEC_SMI>, + <&imgsys CLK_IMG_JPGDEC>; + clock-names = "jpgdec-smi", + "jpgdec"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_ISP>; + mediatek,larb = <&larb2>; + iommus = <&iommu MT2701_M4U_PORT_JPGDEC_WDMA>, + <&iommu MT2701_M4U_PORT_JPGDEC_BSDMA>; + }; diff --git a/Documentation/devicetree/bindings/media/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt index 925ab4d72eaa..4bb08d9d940b 100644 --- a/Documentation/devicetree/bindings/media/s5p-cec.txt +++ b/Documentation/devicetree/bindings/media/s5p-cec.txt @@ -15,6 +15,7 @@ Required properties: - clock-names : from common clock binding: must contain "hdmicec", corresponding to entry in the clocks property. - samsung,syscon-phandle - phandle to the PMU system controller + - hdmi-phandle - phandle to the HDMI controller Example: @@ -25,6 +26,7 @@ hdmicec: cec@100B0000 { clocks = <&clock CLK_HDMI_CEC>; clock-names = "hdmicec"; samsung,syscon-phandle = <&pmu_system_controller>; + hdmi-phandle = <&hdmi>; pinctrl-names = "default"; pinctrl-0 = <&hdmi_cec>; status = "okay"; diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt index 2c901286d818..d3404b5d4d17 100644 --- a/Documentation/devicetree/bindings/media/s5p-mfc.txt +++ b/Documentation/devicetree/bindings/media/s5p-mfc.txt @@ -28,7 +28,7 @@ Optional properties: - memory-region : from reserved memory binding: phandles to two reserved memory regions, first is for "left" mfc memory bus interfaces, second if for the "right" mfc memory bus, used when no SYSMMU - support is available + support is available; used only by MFC v5 present in Exynos4 SoCs Obsolete properties: - samsung,mfc-r, samsung,mfc-l : support removed, please use memory-region diff --git a/Documentation/devicetree/bindings/media/stih-cec.txt b/Documentation/devicetree/bindings/media/stih-cec.txt index 71c4b2f4bcef..289a08b33651 100644 --- a/Documentation/devicetree/bindings/media/stih-cec.txt +++ b/Documentation/devicetree/bindings/media/stih-cec.txt @@ -9,6 +9,7 @@ Required properties: - pinctrl-names: Contains only one value - "default" - pinctrl-0: Specifies the pin control groups used for CEC hardware. - resets: Reference to a reset controller + - hdmi-phandle: Phandle to the HDMI controller Example for STIH407: @@ -22,4 +23,5 @@ sti-cec@094a087c { pinctrl-names = "default"; pinctrl-0 = <&pinctrl_cec0_default>; resets = <&softreset STIH407_LPM_SOFTRESET>; + hdmi-phandle = <&hdmi>; }; diff --git a/Documentation/devicetree/bindings/media/ti,da850-vpif.txt b/Documentation/devicetree/bindings/media/ti,da850-vpif.txt index 6d25d7f23d26..df7182a63e59 100644 --- a/Documentation/devicetree/bindings/media/ti,da850-vpif.txt +++ b/Documentation/devicetree/bindings/media/ti,da850-vpif.txt @@ -16,8 +16,10 @@ Required properties: Video Capture: VPIF has a 16-bit parallel bus input, supporting 2 8-bit channels or a -single 16-bit channel. It should contain at least one port child node -with child 'endpoint' node. Please refer to the bindings defined in +single 16-bit channel. It should contain one or two port child nodes +with child 'endpoint' node. If there are two ports then port@0 must +describe the input and port@1 output channels. Please refer to the +bindings defined in Documentation/devicetree/bindings/media/video-interfaces.txt. Example using 2 8-bit input channels, one of which is connected to an @@ -28,17 +30,24 @@ I2C-connected TVP5147 decoder: reg = <0x217000 0x1000>; interrupts = <92>; - port { - vpif_ch0: endpoint@0 { - reg = <0>; - bus-width = <8>; - remote-endpoint = <&composite>; + port@0 { + vpif_input_ch0: endpoint@0 { + reg = <0>; + bus-width = <8>; + remote-endpoint = <&composite_in>; + }; + + vpif_input_ch1: endpoint@1 { + reg = <1>; + bus-width = <8>; + data-shift = <8>; }; + }; - vpif_ch1: endpoint@1 { - reg = <1>; - bus-width = <8>; - data-shift = <8>; + port@1 { + vpif_output_ch0: endpoint { + bus-width = <8>; + remote-endpoint = <&composite_out>; }; }; }; @@ -53,13 +62,28 @@ I2C-connected TVP5147 decoder: status = "okay"; port { - composite: endpoint { + composite_in: endpoint { hsync-active = <1>; vsync-active = <1>; pclk-sample = <0>; /* VPIF channel 0 (lower 8-bits) */ - remote-endpoint = <&vpif_ch0>; + remote-endpoint = <&vpif_input_ch0>; + bus-width = <8>; + }; + }; + }; + + adv7343@2a { + compatible = "adi,adv7343"; + reg = <0x2a>; + + port { + composite_out: endpoint { + adi,dac-enable = <1 1 1>; + adi,sd-dac-enable = <1>; + + remote-endpoint = <&vpif_output_ch0>; bus-width = <8>; }; }; diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt index ea151f295ad7..c8a736554b4b 100644 --- a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt @@ -18,6 +18,7 @@ The A10SR consists of these sub-devices: Device Description ------ ---------- a10sr_gpio GPIO Controller +a10sr_rst Reset Controller Arria10 GPIO Required Properties: @@ -27,6 +28,11 @@ Required Properties: the second cell is used to specify flags. See ../gpio/gpio.txt for more information. +Arria10 Peripheral PHY Reset +Required Properties: +- compatible : Should be "altr,a10sr-reset" +- #reset-cells : Should be one. + Example: resource-manager@0 { @@ -43,4 +49,9 @@ Example: gpio-controller; #gpio-cells = <2>; }; + + a10sr_rst: reset-controller { + compatible = "altr,a10sr-reset"; + #reset-cells = <1>; + }; }; diff --git a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt index 670831b29565..eec40be7f79a 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt @@ -15,7 +15,7 @@ Required properties: The HLCDC IP exposes two subdevices: - a PWM chip: see ../pwm/atmel-hlcdc-pwm.txt - - a Display Controller: see ../display/atmel-hlcdc-dc.txt + - a Display Controller: see ../display/atmel/hlcdc-dc.txt Example: diff --git a/Documentation/devicetree/bindings/mfd/axp20x.txt b/Documentation/devicetree/bindings/mfd/axp20x.txt index 8f3ad9ab4637..aca09af66514 100644 --- a/Documentation/devicetree/bindings/mfd/axp20x.txt +++ b/Documentation/devicetree/bindings/mfd/axp20x.txt @@ -6,12 +6,19 @@ axp202 (X-Powers) axp209 (X-Powers) axp221 (X-Powers) axp223 (X-Powers) +axp803 (X-Powers) axp809 (X-Powers) Required properties: -- compatible: "x-powers,axp152", "x-powers,axp202", "x-powers,axp209", - "x-powers,axp221", "x-powers,axp223", "x-powers,axp806", - "x-powers,axp809" +- compatible: should be one of: + * "x-powers,axp152" + * "x-powers,axp202" + * "x-powers,axp209" + * "x-powers,axp221" + * "x-powers,axp223" + * "x-powers,axp803" + * "x-powers,axp806" + * "x-powers,axp809" - reg: The I2C slave address or RSB hardware address for the AXP chip - interrupt-parent: The parent interrupt controller - interrupts: SoC NMI / GPIO interrupt connected to the PMIC's IRQ pin @@ -28,6 +35,9 @@ Optional properties: regulator to drive the OTG VBus, rather then as an input pin which signals whether the board is driving OTG VBus or not. +- x-powers,master-mode: Boolean (axp806 only). Set this when the PMIC is + wired for master mode. The default is slave mode. + - <input>-supply: a phandle to the regulator supply node. May be omitted if inputs are unregulated, such as using the IPSOUT output from the PMIC. @@ -86,6 +96,33 @@ LDO_IO1 : LDO : ips-supply : GPIO 1 RTC_LDO : LDO : ips-supply : always on DRIVEVBUS : Enable output : drivevbus-supply : external regulator +AXP803 regulators, type, and corresponding input supply names: + +Regulator Type Supply Name Notes +--------- ---- ----------- ----- +DCDC1 : DC-DC buck : vin1-supply +DCDC2 : DC-DC buck : vin2-supply : poly-phase capable +DCDC3 : DC-DC buck : vin3-supply : poly-phase capable +DCDC4 : DC-DC buck : vin4-supply +DCDC5 : DC-DC buck : vin5-supply : poly-phase capable +DCDC6 : DC-DC buck : vin6-supply : poly-phase capable +DC1SW : On/Off Switch : : DCDC1 secondary output +ALDO1 : LDO : aldoin-supply : shared supply +ALDO2 : LDO : aldoin-supply : shared supply +ALDO3 : LDO : aldoin-supply : shared supply +DLDO1 : LDO : dldoin-supply : shared supply +DLDO2 : LDO : dldoin-supply : shared supply +DLDO3 : LDO : dldoin-supply : shared supply +DLDO4 : LDO : dldoin-supply : shared supply +ELDO1 : LDO : eldoin-supply : shared supply +ELDO2 : LDO : eldoin-supply : shared supply +ELDO3 : LDO : eldoin-supply : shared supply +FLDO1 : LDO : fldoin-supply : shared supply +FLDO2 : LDO : fldoin-supply : shared supply +LDO_IO0 : LDO : ips-supply : GPIO 0 +LDO_IO1 : LDO : ips-supply : GPIO 1 +RTC_LDO : LDO : ips-supply : always on + AXP806 regulators, type, and corresponding input supply names: Regulator Type Supply Name Notes diff --git a/Documentation/devicetree/bindings/mfd/da9062.txt b/Documentation/devicetree/bindings/mfd/da9062.txt index 38802b54d48a..c0a418c27e9d 100644 --- a/Documentation/devicetree/bindings/mfd/da9062.txt +++ b/Documentation/devicetree/bindings/mfd/da9062.txt @@ -1,22 +1,39 @@ * Dialog DA9062 Power Management Integrated Circuit (PMIC) -DA9062 consists of a large and varied group of sub-devices: +Product information for the DA9062 and DA9061 devices can be found here: +- http://www.dialog-semiconductor.com/products/da9062 +- http://www.dialog-semiconductor.com/products/da9061 + +The DA9062 PMIC consists of: Device Supply Names Description ------ ------------ ----------- da9062-regulator : : LDOs & BUCKs da9062-rtc : : Real-Time Clock +da9062-onkey : : On Key +da9062-watchdog : : Watchdog Timer +da9062-thermal : : Thermal + +The DA9061 PMIC consists of: + +Device Supply Names Description +------ ------------ ----------- +da9062-regulator : : LDOs & BUCKs +da9062-onkey : : On Key da9062-watchdog : : Watchdog Timer +da9062-thermal : : Thermal ====== Required properties: -- compatible : Should be "dlg,da9062". +- compatible : Should be + "dlg,da9062" for DA9062 + "dlg,da9061" for DA9061 - reg : Specifies the I2C slave address (this defaults to 0x58 but it can be modified to match the chip's OTP settings). - interrupt-parent : Specifies the reference to the interrupt controller for - the DA9062. + the DA9062 or DA9061. - interrupts : IRQ line information. - interrupt-controller @@ -25,8 +42,8 @@ further information on IRQ bindings. Sub-nodes: -- regulators : This node defines the settings for the LDOs and BUCKs. The - DA9062 regulators are bound using their names listed below: +- regulators : This node defines the settings for the LDOs and BUCKs. + The DA9062 regulators are bound using their names listed below: buck1 : BUCK_1 buck2 : BUCK_2 @@ -37,19 +54,29 @@ Sub-nodes: ldo3 : LDO_3 ldo4 : LDO_4 + The DA9061 regulators are bound using their names listed below: + + buck1 : BUCK_1 + buck2 : BUCK_2 + buck3 : BUCK_3 + ldo1 : LDO_1 + ldo2 : LDO_2 + ldo3 : LDO_3 + ldo4 : LDO_4 + The component follows the standard regulator framework and the bindings details of individual regulator device can be found in: Documentation/devicetree/bindings/regulator/regulator.txt - - rtc : This node defines settings required for the Real-Time Clock associated with the DA9062. There are currently no entries in this binding, however compatible = "dlg,da9062-rtc" should be added if a node is created. -- watchdog: This node defines the settings for the watchdog driver associated - with the DA9062 PMIC. The compatible = "dlg,da9062-watchdog" should be added - if a node is created. +- onkey : See ../input/da9062-onkey.txt + +- watchdog: See ../watchdog/da9062-watchdog.txt +- thermal : See ../thermal/da9062-thermal.txt Example: @@ -64,10 +91,6 @@ Example: compatible = "dlg,da9062-rtc"; }; - watchdog { - compatible = "dlg,da9062-watchdog"; - }; - regulators { DA9062_BUCK1: buck1 { regulator-name = "BUCK1"; diff --git a/Documentation/devicetree/bindings/mfd/mt6397.txt b/Documentation/devicetree/bindings/mfd/mt6397.txt index c568d52af5af..522a3bbf1bac 100644 --- a/Documentation/devicetree/bindings/mfd/mt6397.txt +++ b/Documentation/devicetree/bindings/mfd/mt6397.txt @@ -6,6 +6,7 @@ MT6397/MT6323 is a multifunction device with the following sub modules: - Audio codec - GPIO - Clock +- LED It is interfaced to host controller using SPI interface by a proprietary hardware called PMIC wrapper or pwrap. MT6397/MT6323 MFD is a child device of pwrap. diff --git a/Documentation/devicetree/bindings/iio/adc/mxs-lradc.txt b/Documentation/devicetree/bindings/mfd/mxs-lradc.txt index 555fb117d4fa..555fb117d4fa 100644 --- a/Documentation/devicetree/bindings/iio/adc/mxs-lradc.txt +++ b/Documentation/devicetree/bindings/mfd/mxs-lradc.txt diff --git a/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.txt b/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.txt index c110e118b79f..df664018c148 100644 --- a/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.txt +++ b/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.txt @@ -5,7 +5,10 @@ Required properties: - compatible : "samsung,exynos5433-lpass" - reg : should contain the LPASS top SFR region location and size - - samsung,pmu-syscon : the phandle to the Power Management Unit node + - clock-names : should contain following required clocks: "sfr0_ctrl" + - clocks : should contain clock specifiers of all clocks, which + input names have been specified in clock-names + property, in same order. - #address-cells : should be 1 - #size-cells : should be 1 - ranges : must be present @@ -25,7 +28,8 @@ Example: audio-subsystem { compatible = "samsung,exynos5433-lpass"; reg = <0x11400000 0x100>, <0x11500000 0x08>; - samsung,pmu-syscon = <&pmu_system_controller>; + clocks = <&cmu_aud CLK_PCLK_SFR0_CTRL>; + clock-names = "sfr0_ctrl"; #address-cells = <1>; #size-cells = <1>; ranges; diff --git a/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt b/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt index 89abecd938cb..badff3611a98 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/sun4i.txt +++ b/Documentation/devicetree/bindings/mfd/sun4i-gpadc.txt @@ -1,3 +1,24 @@ +Allwinner SoCs' GPADC Device Tree bindings +------------------------------------------ +The Allwinner SoCs all have an ADC that can also act as a thermal sensor +and sometimes as a touchscreen controller. + +Required properties: + - compatible: "allwinner,sun8i-a33-ths", + - reg: mmio address range of the chip, + - #thermal-sensor-cells: shall be 0, + - #io-channel-cells: shall be 0, + +Example: + ths: ths@01c25000 { + compatible = "allwinner,sun8i-a33-ths"; + reg = <0x01c25000 0x100>; + #thermal-sensor-cells = <0>; + #io-channel-cells = <0>; + }; + +sun4i, sun5i and sun6i SoCs are also supported via the older binding: + sun4i resistive touchscreen controller -------------------------------------- diff --git a/Documentation/devicetree/bindings/mfd/ti-lmu.txt b/Documentation/devicetree/bindings/mfd/ti-lmu.txt new file mode 100644 index 000000000000..c885cf89b8ce --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ti-lmu.txt @@ -0,0 +1,243 @@ +TI LMU (Lighting Management Unit) device tree bindings + +TI LMU driver supports lighting devices below. + + Name Child nodes + ------ --------------------------------- + LM3532 Backlight + LM3631 Backlight and regulator + LM3632 Backlight and regulator + LM3633 Backlight, LED and fault monitor + LM3695 Backlight + LM3697 Backlight and fault monitor + +Required properties: + - compatible: Should be one of: + "ti,lm3532" + "ti,lm3631" + "ti,lm3632" + "ti,lm3633" + "ti,lm3695" + "ti,lm3697" + - reg: I2C slave address. + 0x11 for LM3632 + 0x29 for LM3631 + 0x36 for LM3633, LM3697 + 0x38 for LM3532 + 0x63 for LM3695 + +Optional property: + - enable-gpios: A GPIO specifier for hardware enable pin. + +Required node: + - backlight: All LMU devices have backlight child nodes. + For the properties, please refer to [1]. + +Optional nodes: + - fault-monitor: Hardware fault monitoring driver for LM3633 and LM3697. + Required properties: + - compatible: Should be one of: + "ti,lm3633-fault-monitor" + "ti,lm3697-fault-monitor" + - leds: LED properties for LM3633. Please refer to [2]. + - regulators: Regulator properties for LM3631 and LM3632. + Please refer to [3]. + +[1] ../leds/backlight/ti-lmu-backlight.txt +[2] ../leds/leds-lm3633.txt +[3] ../regulator/lm363x-regulator.txt + +lm3532@38 { + compatible = "ti,lm3532"; + reg = <0x38>; + + enable-gpios = <&pioC 2 GPIO_ACTIVE_HIGH>; + + backlight { + compatible = "ti,lm3532-backlight"; + + lcd { + led-sources = <0 1 2>; + ramp-up-msec = <30>; + ramp-down-msec = <0>; + }; + }; +}; + +lm3631@29 { + compatible = "ti,lm3631"; + reg = <0x29>; + + regulators { + compatible = "ti,lm363x-regulator"; + + vboost { + regulator-name = "lcd_boost"; + regulator-min-microvolt = <4500000>; + regulator-max-microvolt = <6350000>; + regulator-always-on; + }; + + vcont { + regulator-name = "lcd_vcont"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + }; + + voref { + regulator-name = "lcd_voref"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + }; + + vpos { + regulator-name = "lcd_vpos"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + regulator-boot-on; + }; + + vneg { + regulator-name = "lcd_vneg"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + regulator-boot-on; + }; + }; + + backlight { + compatible = "ti,lm3631-backlight"; + + lcd_bl { + led-sources = <0 1>; + ramp-up-msec = <300>; + }; + }; +}; + +lm3632@11 { + compatible = "ti,lm3632"; + reg = <0x11>; + + enable-gpios = <&pioC 2 GPIO_ACTIVE_HIGH>; /* PC2 */ + + regulators { + compatible = "ti,lm363x-regulator"; + + ti,lcm-en1-gpio = <&pioC 0 GPIO_ACTIVE_HIGH>; /* PC0 */ + ti,lcm-en2-gpio = <&pioC 1 GPIO_ACTIVE_HIGH>; /* PC1 */ + + vboost { + regulator-name = "lcd_boost"; + regulator-min-microvolt = <4500000>; + regulator-max-microvolt = <6400000>; + regulator-always-on; + }; + + vpos { + regulator-name = "lcd_vpos"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + }; + + vneg { + regulator-name = "lcd_vneg"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + }; + }; + + backlight { + compatible = "ti,lm3632-backlight"; + + pwms = <&pwm0 0 10000 0>; /* pwm number, period, polarity */ + pwm-names = "lmu-backlight"; + + lcd { + led-sources = <0 1>; + pwm-period = <10000>; + }; + }; +}; + +lm3633@36 { + compatible = "ti,lm3633"; + reg = <0x36>; + + enable-gpios = <&pioC 2 GPIO_ACTIVE_HIGH>; + + backlight { + compatible = "ti,lm3633-backlight"; + + main { + label = "main_lcd"; + led-sources = <1 2>; + ramp-up-msec = <500>; + ramp-down-msec = <500>; + }; + + front { + label = "front_lcd"; + led-sources = <0>; + ramp-up-msec = <1000>; + ramp-down-msec = <0>; + }; + }; + + leds { + compatible = "ti,lm3633-leds"; + + chan1 { + label = "status"; + led-sources = <1>; + led-max-microamp = <6000>; + }; + + chan345 { + label = "rgb"; + led-sources = <3 4 5>; + led-max-microamp = <10000>; + }; + }; + + fault-monitor { + compatible = "ti,lm3633-fault-monitor"; + }; +}; + +lm3695@63 { + compatible = "ti,lm3695"; + reg = <0x63>; + + enable-gpios = <&pioC 2 GPIO_ACTIVE_HIGH>; + + backlight { + compatible = "ti,lm3695-backlight"; + + lcd { + label = "bl"; + led-sources = <0 1>; + }; + }; +}; + +lm3697@36 { + compatible = "ti,lm3697"; + reg = <0x36>; + + enable-gpios = <&pioC 2 GPIO_ACTIVE_HIGH>; + + backlight { + compatible = "ti,lm3697-backlight"; + + lcd { + led-sources = <0 1 2>; + ramp-up-msec = <200>; + ramp-down-msec = <200>; + }; + }; + + fault-monitor { + compatible = "ti,lm3697-fault-monitor"; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/wm831x.txt b/Documentation/devicetree/bindings/mfd/wm831x.txt new file mode 100644 index 000000000000..9f8b7430673c --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/wm831x.txt @@ -0,0 +1,81 @@ +Cirrus Logic/Wolfson Microelectronics wm831x PMICs + +System PMICs with a wide range of additional features. + +Required properties: + + - compatible : One of the following chip-specific strings: + "wlf,wm8310" + "wlf,wm8311" + "wlf,wm8312" + "wlf,wm8320" + "wlf,wm8321" + "wlf,wm8325" + "wlf,wm8326" + + - reg : I2C slave address when connected using I2C, chip select number + when using SPI. + + - gpio-controller : Indicates this device is a GPIO controller. + - #gpio-cells : Must be 2. The first cell is the pin number and the + second cell is used to specify optional parameters (currently unused). + + - interrupts : The interrupt line the IRQ signal for the device is + connected to. + - interrupt-parent : The parent interrupt controller. + + - interrupt-controller : wm831x devices contain interrupt controllers and + may provide interrupt services to other devices. + - #interrupt-cells: Must be 2. The first cell is the IRQ number, and the + second cell is the flags, encoded as the trigger masks from + ../interrupt-controller/interrupts.txt + +Optional sub-nodes: + - regulators : Contains sub-nodes for each of the regulators supplied by + the device. The regulators are bound using their names listed below: + + dcdc1 : DCDC1 + dcdc2 : DCDC2 + dcdc3 : DCDC3 + dcdc4 : DCDC3 + isink1 : ISINK1 + isink2 : ISINK2 + ldo1 : LDO1 + ldo2 : LDO2 + ldo3 : LDO3 + ldo4 : LDO4 + ldo5 : LDO5 + ldo7 : LDO7 + ldo11 : LDO11 + + The bindings details of each regulator can be found in: + ../regulator/regulator.txt + +Example: + +wm8310: pmic@36 { + compatible = "wlf,wm8310"; + reg = <0x36>; + + gpio-controller; + #gpio-cells = <2>; + + interrupts = <347>; + interrupt-parent = <&gic>; + + interrupt-controller; + #interrupt-cells = <2>; + + regulators { + dcdc1: dcdc1 { + regulator-name = "DCDC1"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <600000>; + }; + ldo1: ldo1 { + regulator-name = "LDO1"; + regulator-min-microvolt = <1700000>; + regulator-max-microvolt = <1700000>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.txt b/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.txt new file mode 100644 index 000000000000..d876580ae3b8 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,bcm2835-sdhost.txt @@ -0,0 +1,23 @@ +Broadcom BCM2835 SDHOST controller + +This file documents differences between the core properties described +by mmc.txt and the properties that represent the BCM2835 controller. + +Required properties: +- compatible: Should be "brcm,bcm2835-sdhost". +- clocks: The clock feeding the SDHOST controller. + +Optional properties: +- dmas: DMA channel for read and write. + See Documentation/devicetree/bindings/dma/dma.txt for details + +Example: + +sdhost: mmc@7e202000 { + compatible = "brcm,bcm2835-sdhost"; + reg = <0x7e202000 0x100>; + interrupts = <2 24>; + clocks = <&clocks BCM2835_CLOCK_VPU>; + dmas = <&dma 13>; + dma-names = "rx-tx"; +}; diff --git a/Documentation/devicetree/bindings/mmc/cavium-mmc.txt b/Documentation/devicetree/bindings/mmc/cavium-mmc.txt new file mode 100644 index 000000000000..1433e6201dff --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/cavium-mmc.txt @@ -0,0 +1,57 @@ +* Cavium Octeon & ThunderX MMC controller + +The highspeed MMC host controller on Caviums SoCs provides an interface +for MMC and SD types of memory cards. + +Supported maximum speeds are the ones of the eMMC standard 4.41 as well +as the speed of SD standard 4.0. Only 3.3 Volt is supported. + +Required properties: + - compatible : should be one of: + cavium,octeon-6130-mmc + cavium,octeon-7890-mmc + cavium,thunder-8190-mmc + cavium,thunder-8390-mmc + mmc-slot + - reg : mmc controller base registers + - clocks : phandle + +Optional properties: + - for cd, bus-width and additional generic mmc parameters + please refer to mmc.txt within this directory + - cavium,cmd-clk-skew : number of coprocessor clocks before sampling command + - cavium,dat-clk-skew : number of coprocessor clocks before sampling data + +Deprecated properties: +- spi-max-frequency : use max-frequency instead +- cavium,bus-max-width : use bus-width instead +- power-gpios : use vmmc-supply instead +- cavium,octeon-6130-mmc-slot : use mmc-slot instead + +Examples: + mmc_1_4: mmc@1,4 { + compatible = "cavium,thunder-8390-mmc"; + reg = <0x0c00 0 0 0 0>; /* DEVFN = 0x0c (1:4) */ + #address-cells = <1>; + #size-cells = <0>; + clocks = <&sclk>; + + mmc-slot@0 { + compatible = "mmc-slot"; + reg = <0>; + vmmc-supply = <&mmc_supply_3v3>; + max-frequency = <42000000>; + bus-width = <4>; + cap-sd-highspeed; + }; + + mmc-slot@1 { + compatible = "mmc-slot"; + reg = <1>; + vmmc-supply = <&mmc_supply_3v3>; + max-frequency = <42000000>; + bus-width = <8>; + cap-mmc-highspeed; + non-removable; + }; + }; diff --git a/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.txt b/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.txt new file mode 100644 index 000000000000..b878a1e305af --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/marvell,xenon-sdhci.txt @@ -0,0 +1,170 @@ +Marvell Xenon SDHCI Controller device tree bindings +This file documents differences between the core mmc properties +described by mmc.txt and the properties used by the Xenon implementation. + +Multiple SDHCs might be put into a single Xenon IP, to save size and cost. +Each SDHC is independent and owns independent resources, such as register sets, +clock and PHY. +Each SDHC should have an independent device tree node. + +Required Properties: +- compatible: should be one of the following + - "marvell,armada-3700-sdhci": For controllers on Armada-3700 SoC. + Must provide a second register area and marvell,pad-type. + - "marvell,armada-ap806-sdhci": For controllers on Armada AP806. + - "marvell,armada-cp110-sdhci": For controllers on Armada CP110. + +- clocks: + Array of clocks required for SDHC. + Require at least input clock for Xenon IP core. + +- clock-names: + Array of names corresponding to clocks property. + The input clock for Xenon IP core should be named as "core". + +- reg: + * For "marvell,armada-3700-sdhci", two register areas. + The first one for Xenon IP register. The second one for the Armada 3700 SoC + PHY PAD Voltage Control register. + Please follow the examples with compatible "marvell,armada-3700-sdhci" + in below. + Please also check property marvell,pad-type in below. + + * For other compatible strings, one register area for Xenon IP. + +Optional Properties: +- marvell,xenon-sdhc-id: + Indicate the corresponding bit index of current SDHC in + SDHC System Operation Control Register Bit[7:0]. + Set/clear the corresponding bit to enable/disable current SDHC. + If Xenon IP contains only one SDHC, this property is optional. + +- marvell,xenon-phy-type: + Xenon support multiple types of PHYs. + To select eMMC 5.1 PHY, set: + marvell,xenon-phy-type = "emmc 5.1 phy" + eMMC 5.1 PHY is the default choice if this property is not provided. + To select eMMC 5.0 PHY, set: + marvell,xenon-phy-type = "emmc 5.0 phy" + + All those types of PHYs can support eMMC, SD and SDIO. + Please note that this property only presents the type of PHY. + It doesn't stand for the entire SDHC type or property. + For example, "emmc 5.1 phy" doesn't mean that this Xenon SDHC only + supports eMMC 5.1. + +- marvell,xenon-phy-znr: + Set PHY ZNR value. + Only available for eMMC PHY. + Valid range = [0:0x1F]. + ZNR is set as 0xF by default if this property is not provided. + +- marvell,xenon-phy-zpr: + Set PHY ZPR value. + Only available for eMMC PHY. + Valid range = [0:0x1F]. + ZPR is set as 0xF by default if this property is not provided. + +- marvell,xenon-phy-nr-success-tun: + Set the number of required consecutive successful sampling points + used to identify a valid sampling window, in tuning process. + Valid range = [1:7]. + Set as 0x4 by default if this property is not provided. + +- marvell,xenon-phy-tun-step-divider: + Set the divider for calculating TUN_STEP. + Set as 64 by default if this property is not provided. + +- marvell,xenon-phy-slow-mode: + If this property is selected, transfers will bypass PHY. + Only available when bus frequency lower than 55MHz in SDR mode. + Disabled by default. Please only try this property if timing issues + always occur with PHY enabled in eMMC HS SDR, SD SDR12, SD SDR25, + SD Default Speed and HS mode and eMMC legacy speed mode. + +- marvell,xenon-tun-count: + Xenon SDHC SoC usually doesn't provide re-tuning counter in + Capabilities Register 3 Bit[11:8]. + This property provides the re-tuning counter. + If this property is not set, default re-tuning counter will + be set as 0x9 in driver. + +- marvell,pad-type: + Type of Armada 3700 SoC PHY PAD Voltage Controller register. + Only valid when "marvell,armada-3700-sdhci" is selected. + Two types: "sd" and "fixed-1-8v". + If "sd" is selected, SoC PHY PAD is set as 3.3V at the beginning and is + switched to 1.8V when later in higher speed mode. + If "fixed-1-8v" is selected, SoC PHY PAD is fixed 1.8V, such as for eMMC. + Please follow the examples with compatible "marvell,armada-3700-sdhci" + in below. + +Example: +- For eMMC: + + sdhci@aa0000 { + compatible = "marvell,armada-ap806-sdhci"; + reg = <0xaa0000 0x1000>; + interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH> + clocks = <&emmc_clk>; + clock-names = "core"; + bus-width = <4>; + marvell,xenon-phy-slow-mode; + marvell,xenon-tun-count = <11>; + non-removable; + no-sd; + no-sdio; + + /* Vmmc and Vqmmc are both fixed */ + }; + +- For SD/SDIO: + + sdhci@ab0000 { + compatible = "marvell,armada-cp110-sdhci"; + reg = <0xab0000 0x1000>; + interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH> + vqmmc-supply = <&sd_vqmmc_regulator>; + vmmc-supply = <&sd_vmmc_regulator>; + clocks = <&sdclk>; + clock-names = "core"; + bus-width = <4>; + marvell,xenon-tun-count = <9>; + }; + +- For eMMC with compatible "marvell,armada-3700-sdhci": + + sdhci@aa0000 { + compatible = "marvell,armada-3700-sdhci"; + reg = <0xaa0000 0x1000>, + <phy_addr 0x4>; + interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH> + clocks = <&emmcclk>; + clock-names = "core"; + bus-width = <8>; + mmc-ddr-1_8v; + mmc-hs400-1_8v; + non-removable; + no-sd; + no-sdio; + + /* Vmmc and Vqmmc are both fixed */ + + marvell,pad-type = "fixed-1-8v"; + }; + +- For SD/SDIO with compatible "marvell,armada-3700-sdhci": + + sdhci@ab0000 { + compatible = "marvell,armada-3700-sdhci"; + reg = <0xab0000 0x1000>, + <phy_addr 0x4>; + interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH> + vqmmc-supply = <&sd_regulator>; + /* Vmmc is fixed */ + clocks = <&sdclk>; + clock-names = "core"; + bus-width = <4>; + + marvell,pad-type = "sd"; + }; diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.txt b/Documentation/devicetree/bindings/mmc/mtk-sd.txt index 0120c7f1109c..4182ea36ca5b 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.txt +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.txt @@ -21,6 +21,15 @@ Optional properties: - assigned-clocks: PLL of the source clock - assigned-clock-parents: parent of source clock, used for HS400 mode to get 400Mhz source clock - hs400-ds-delay: HS400 DS delay setting +- mediatek,hs200-cmd-int-delay: HS200 command internal delay setting. + This field has total 32 stages. + The value is an integer from 0 to 31. +- mediatek,hs400-cmd-int-delay: HS400 command internal delay setting + This field has total 32 stages. + The value is an integer from 0 to 31. +- mediatek,hs400-cmd-resp-sel-rising: HS400 command response sample selection + If present,HS400 command responses are sampled on rising edges. + If not present,HS400 command responses are sampled on falling edges. Examples: mmc0: mmc@11230000 { @@ -38,4 +47,7 @@ mmc0: mmc@11230000 { assigned-clocks = <&topckgen CLK_TOP_MSDC50_0_SEL>; assigned-clock-parents = <&topckgen CLK_TOP_MSDCPLL_D2>; hs400-ds-delay = <0x14015>; + mediatek,hs200-cmd-int-delay = <26>; + mediatek,hs400-cmd-int-delay = <14>; + mediatek,hs400-cmd-resp-sel-rising; }; diff --git a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt index 15b8368ee1f2..9bce57862ed6 100644 --- a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt @@ -7,11 +7,13 @@ This file documents differences between the core properties described by mmc.txt and the properties used by the sdhci-tegra driver. Required properties: -- compatible : For Tegra20, must contain "nvidia,tegra20-sdhci". - For Tegra30, must contain "nvidia,tegra30-sdhci". For Tegra114, - must contain "nvidia,tegra114-sdhci". For Tegra124, must contain - "nvidia,tegra124-sdhci". Otherwise, must contain "nvidia,<chip>-sdhci", - plus one of the above, where <chip> is tegra132 or tegra210. +- compatible : should be one of: + - "nvidia,tegra20-sdhci": for Tegra20 + - "nvidia,tegra30-sdhci": for Tegra30 + - "nvidia,tegra114-sdhci": for Tegra114 + - "nvidia,tegra124-sdhci": for Tegra124 and Tegra132 + - "nvidia,tegra210-sdhci": for Tegra210 + - "nvidia,tegra186-sdhci": for Tegra186 - clocks : Must contain one entry, for the module clock. See ../clocks/clock-bindings.txt for details. - resets : Must contain an entry for each entry in reset-names. diff --git a/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt b/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt index e4ba92aa035e..c32dc5a9dbe6 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt +++ b/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt @@ -8,6 +8,7 @@ Required properties: - compatible: should be "renesas,mmcif-<soctype>", "renesas,sh-mmcif" as a fallback. Examples with <soctype> are: + - "renesas,mmcif-r7s72100" for the MMCIF found in r7s72100 SoCs - "renesas,mmcif-r8a73a4" for the MMCIF found in r8a73a4 SoCs - "renesas,mmcif-r8a7740" for the MMCIF found in r8a7740 SoCs - "renesas,mmcif-r8a7778" for the MMCIF found in r8a7778 SoCs @@ -17,6 +18,13 @@ Required properties: - "renesas,mmcif-r8a7794" for the MMCIF found in r8a7794 SoCs - "renesas,mmcif-sh73a0" for the MMCIF found in sh73a0 SoCs +- interrupts: Some SoCs have only 1 shared interrupt, while others have either + 2 or 3 individual interrupts (error, int, card detect). Below is the number + of interrupts for each SoC: + 1: r8a73a4, r8a7778, r8a7790, r8a7791, r8a7793, r8a7794 + 2: r8a7740, sh73a0 + 3: r7s72100 + - clocks: reference to the functional clock - dmas: reference to the DMA channels, one per channel name listed in the diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt index ea9c1c9607f6..520d61dad6dd 100644 --- a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt @@ -13,7 +13,7 @@ Required Properties: - "rockchip,rk2928-dw-mshc": for Rockchip RK2928 and following, before RK3288 - "rockchip,rk3288-dw-mshc": for Rockchip RK3288 - - "rockchip,rk1108-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK1108 + - "rockchip,rv1108-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RV1108 - "rockchip,rk3036-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3036 - "rockchip,rk3368-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3368 - "rockchip,rk3399-dw-mshc", "rockchip,rk3288-dw-mshc": for Rockchip RK3399 diff --git a/Documentation/devicetree/bindings/mmc/samsung,s3cmci.txt b/Documentation/devicetree/bindings/mmc/samsung,s3cmci.txt new file mode 100644 index 000000000000..5f68feb9f9d6 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/samsung,s3cmci.txt @@ -0,0 +1,42 @@ +* Samsung's S3C24XX MMC/SD/SDIO controller device tree bindings + +Samsung's S3C24XX MMC/SD/SDIO controller is used as a connectivity interface +with external MMC, SD and SDIO storage mediums. + +This file documents differences between the core mmc properties described by +mmc.txt and the properties used by the Samsung S3C24XX MMC/SD/SDIO controller +implementation. + +Required SoC Specific Properties: +- compatible: should be one of the following + - "samsung,s3c2410-sdi": for controllers compatible with s3c2410 + - "samsung,s3c2412-sdi": for controllers compatible with s3c2412 + - "samsung,s3c2440-sdi": for controllers compatible with s3c2440 +- reg: register location and length +- interrupts: mmc controller interrupt +- clocks: Should reference the controller clock +- clock-names: Should contain "sdi" + +Required Board Specific Properties: +- pinctrl-0: Should specify pin control groups used for this controller. +- pinctrl-names: Should contain only one value - "default". + +Optional Properties: +- bus-width: number of data lines (see mmc.txt) +- cd-gpios: gpio for card detection (see mmc.txt) +- wp-gpios: gpio for write protection (see mmc.txt) + +Example: + + mmc0: mmc@5a000000 { + compatible = "samsung,s3c2440-sdi"; + pinctrl-names = "default"; + pinctrl-0 = <&sdi_pins>; + reg = <0x5a000000 0x100000>; + interrupts = <0 0 21 3>; + clocks = <&clocks PCLK_SDI>; + clock-names = "sdi"; + bus-width = <4>; + cd-gpios = <&gpg 8 GPIO_ACTIVE_LOW>; + wp-gpios = <&gph 8 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-cadence.txt b/Documentation/devicetree/bindings/mmc/sdhci-cadence.txt index c0f37cb41a9b..fa423c277853 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-cadence.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-cadence.txt @@ -19,6 +19,53 @@ if supported. See mmc.txt for details. - mmc-hs400-1_8v - mmc-hs400-1_2v +Some PHY delays can be configured by following properties. +PHY DLL input delays: +They are used to delay the data valid window, and align the window +to sampling clock. The delay starts from 5ns (for delay parameter equal to 0) +and it is increased by 2.5ns in each step. +- cdns,phy-input-delay-sd-highspeed: + Value of the delay in the input path for SD high-speed timing + Valid range = [0:0x1F]. +- cdns,phy-input-delay-legacy: + Value of the delay in the input path for legacy timing + Valid range = [0:0x1F]. +- cdns,phy-input-delay-sd-uhs-sdr12: + Value of the delay in the input path for SD UHS SDR12 timing + Valid range = [0:0x1F]. +- cdns,phy-input-delay-sd-uhs-sdr25: + Value of the delay in the input path for SD UHS SDR25 timing + Valid range = [0:0x1F]. +- cdns,phy-input-delay-sd-uhs-sdr50: + Value of the delay in the input path for SD UHS SDR50 timing + Valid range = [0:0x1F]. +- cdns,phy-input-delay-sd-uhs-ddr50: + Value of the delay in the input path for SD UHS DDR50 timing + Valid range = [0:0x1F]. +- cdns,phy-input-delay-mmc-highspeed: + Value of the delay in the input path for MMC high-speed timing + Valid range = [0:0x1F]. +- cdns,phy-input-delay-mmc-ddr: + Value of the delay in the input path for eMMC high-speed DDR timing + Valid range = [0:0x1F]. + +PHY DLL clock delays: +Each delay property represents the fraction of the clock period. +The approximate delay value will be +(<delay property value>/128)*sdmclk_clock_period. +- cdns,phy-dll-delay-sdclk: + Value of the delay introduced on the sdclk output + for all modes except HS200, HS400 and HS400_ES. + Valid range = [0:0x7F]. +- cdns,phy-dll-delay-sdclk-hsmmc: + Value of the delay introduced on the sdclk output + for HS200, HS400 and HS400_ES speed modes. + Valid range = [0:0x7F]. +- cdns,phy-dll-delay-strobe: + Value of the delay introduced on the dat_strobe input + used in HS400 / HS400_ES speed modes. + Valid range = [0:0x7F]. + Example: emmc: sdhci@5a000000 { compatible = "socionext,uniphier-sd4hc", "cdns,sd4hc"; @@ -29,4 +76,5 @@ Example: mmc-ddr-1_8v; mmc-hs200-1_8v; mmc-hs400-1_8v; + cdns,phy-dll-delay-sdclk = <0>; }; diff --git a/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt b/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt index 10587bdadbbe..26c77d985faf 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt @@ -2,11 +2,14 @@ Required properties: - compatible: should contain one of "brcm,genet-v1", "brcm,genet-v2", - "brcm,genet-v3", "brcm,genet-v4". + "brcm,genet-v3", "brcm,genet-v4", "brcm,genet-v5". - reg: address and length of the register set for the device -- interrupts: must be two cells, the first cell is the general purpose - interrupt line, while the second cell is the interrupt for the ring - RX and TX queues operating in ring mode +- interrupts and/or interrupts-extended: must be two cells, the first cell + is the general purpose interrupt line, while the second cell is the + interrupt for the ring RX and TX queues operating in ring mode. An + optional third interrupt cell for Wake-on-LAN can be specified. + See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + for information on the property specifics. - phy-mode: see ethernet.txt file in the same directory - #address-cells: should be 1 - #size-cells: should be 1 @@ -29,15 +32,15 @@ Optional properties: Required child nodes: -- mdio bus node: this node should always be present regarless of the PHY +- mdio bus node: this node should always be present regardless of the PHY configuration of the GENET instance MDIO bus node required properties: - compatible: should contain one of "brcm,genet-mdio-v1", "brcm,genet-mdio-v2" - "brcm,genet-mdio-v3", "brcm,genet-mdio-v4", the version has to match the - parent node compatible property (e.g: brcm,genet-v4 pairs with - brcm,genet-mdio-v4) + "brcm,genet-mdio-v3", "brcm,genet-mdio-v4", "brcm,genet-mdio-v5", the version + has to match the parent node compatible property (e.g: brcm,genet-v4 pairs + with brcm,genet-mdio-v4) - reg: address and length relative to the parent node base register address - #address-cells: address cell for MDIO bus addressing, should be 1 - #size-cells: size of the cells for MDIO bus addressing, should be 0 diff --git a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt index ab0bb4247d14..4648948f7c3b 100644 --- a/Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt +++ b/Documentation/devicetree/bindings/net/brcm,unimac-mdio.txt @@ -2,8 +2,9 @@ Required properties: - compatible: should one from "brcm,genet-mdio-v1", "brcm,genet-mdio-v2", - "brcm,genet-mdio-v3", "brcm,genet-mdio-v4" or "brcm,unimac-mdio" -- reg: address and length of the regsiter set for the device, first one is the + "brcm,genet-mdio-v3", "brcm,genet-mdio-v4", "brcm,genet-mdio-v5" or + "brcm,unimac-mdio" +- reg: address and length of the register set for the device, first one is the base register, and the second one is optional and for indirect accesses to larger than 16-bits MDIO transactions - reg-names: name(s) of the register must be "mdio" and optional "mdio_indir_rw" diff --git a/Documentation/devicetree/bindings/net/can/holt_hi311x.txt b/Documentation/devicetree/bindings/net/can/holt_hi311x.txt new file mode 100644 index 000000000000..23aa94eab207 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/holt_hi311x.txt @@ -0,0 +1,24 @@ +* Holt HI-311X stand-alone CAN controller device tree bindings + +Required properties: + - compatible: Should be one of the following: + - "holt,hi3110" for HI-3110 + - reg: SPI chip select. + - clocks: The clock feeding the CAN controller. + - interrupt-parent: The parent interrupt controller. + - interrupts: Should contain IRQ line for the CAN controller. + +Optional properties: + - vdd-supply: Regulator that powers the CAN controller. + - xceiver-supply: Regulator that powers the CAN transceiver. + +Example: + can0: can@1 { + compatible = "holt,hi3110"; + reg = <1>; + clocks = <&clk32m>; + interrupt-parent = <&gpio4>; + interrupts = <13 IRQ_TYPE_EDGE_RISING>; + vdd-supply = <®5v0>; + xceiver-supply = <®5v0>; + }; diff --git a/Documentation/devicetree/bindings/net/can/ti_hecc.txt b/Documentation/devicetree/bindings/net/can/ti_hecc.txt new file mode 100644 index 000000000000..e0f0a7cfe329 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/ti_hecc.txt @@ -0,0 +1,32 @@ +Texas Instruments High End CAN Controller (HECC) +================================================ + +This file provides information, what the device node +for the hecc interface contains. + +Required properties: +- compatible: "ti,am3517-hecc" +- reg: addresses and lengths of the register spaces for 'hecc', 'hecc-ram' + and 'mbx' +- reg-names :"hecc", "hecc-ram", "mbx" +- interrupts: interrupt mapping for the hecc interrupts sources +- clocks: clock phandles (see clock bindings for details) + +Optional properties: +- ti,use-hecc1int: if provided configures HECC to produce all interrupts + on HECC1INT interrupt line. By default HECC0INT interrupt + line will be used. +- xceiver-supply: regulator that powers the CAN transceiver + +Example: + +For am3517evm board: + hecc: can@5c050000 { + compatible = "ti,am3517-hecc"; + reg = <0x5c050000 0x80>, + <0x5c053000 0x180>, + <0x5c052000 0x200>; + reg-names = "hecc", "hecc-ram", "mbx"; + interrupts = <24>; + clocks = <&hecc_ck>; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/lan9303.txt b/Documentation/devicetree/bindings/net/dsa/lan9303.txt new file mode 100644 index 000000000000..04f2965a4467 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/lan9303.txt @@ -0,0 +1,105 @@ +SMSC/MicroChip LAN9303 three port ethernet switch +------------------------------------------------- + +Required properties: + +- compatible: should be + - "smsc,lan9303-i2c" for I2C managed mode + or + - "smsc,lan9303-mdio" for mdio managed mode + +Optional properties: + +- reset-gpios: GPIO to be used to reset the whole device +- reset-duration: reset duration in milliseconds, defaults to 200 ms + +Subnodes: + +The integrated switch subnode should be specified according to the binding +described in dsa/dsa.txt. The CPU port of this switch is always port 0. + +Note: always use 'reg = <0/1/2>;' for the three DSA ports, even if the device is +configured to use 1/2/3 instead. This hardware configuration will be +auto-detected and mapped accordingly. + +Example: + +I2C managed mode: + + master: masterdevice@X { + status = "okay"; + + fixed-link { /* RMII fixed link to LAN9303 */ + speed = <100>; + full-duplex; + }; + }; + + switch: switch@a { + compatible = "smsc,lan9303-i2c"; + reg = <0xa>; + status = "okay"; + reset-gpios = <&gpio7 6 GPIO_ACTIVE_LOW>; + reset-duration = <200>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { /* RMII fixed link to master */ + reg = <0>; + label = "cpu"; + ethernet = <&master>; + }; + + port@1 { /* external port 1 */ + reg = <1>; + label = "lan1; + }; + + port@2 { /* external port 2 */ + reg = <2>; + label = "lan2"; + }; + }; + }; + +MDIO managed mode: + + master: masterdevice@X { + status = "okay"; + phy-handle = <&switch>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + switch: switch-phy@0 { + compatible = "smsc,lan9303-mdio"; + reg = <0>; + reset-gpios = <&gpio7 6 GPIO_ACTIVE_LOW>; + reset-duration = <100>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + label = "cpu"; + ethernet = <&master>; + }; + + port@1 { /* external port 1 */ + reg = <1>; + label = "lan1; + }; + + port@2 { /* external port 2 */ + reg = <2>; + label = "lan2"; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/mt7530.txt b/Documentation/devicetree/bindings/net/dsa/mt7530.txt new file mode 100644 index 000000000000..a9bc27b93ee3 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/mt7530.txt @@ -0,0 +1,92 @@ +Mediatek MT7530 Ethernet switch +================================ + +Required properties: + +- compatible: Must be compatible = "mediatek,mt7530"; +- #address-cells: Must be 1. +- #size-cells: Must be 0. +- mediatek,mcm: Boolean; if defined, indicates that either MT7530 is the part + on multi-chip module belong to MT7623A has or the remotely standalone + chip as the function MT7623N reference board provided for. +- core-supply: Phandle to the regulator node necessary for the core power. +- io-supply: Phandle to the regulator node necessary for the I/O power. + See Documentation/devicetree/bindings/regulator/mt6323-regulator.txt + for details for the regulator setup on these boards. + +If the property mediatek,mcm isn't defined, following property is required + +- reset-gpios: Should be a gpio specifier for a reset line. + +Else, following properties are required + +- resets : Phandle pointing to the system reset controller with + line index for the ethsys. +- reset-names : Should be set to "mcm". + +Required properties for the child nodes within ports container: + +- reg: Port address described must be 6 for CPU port and from 0 to 5 for + user ports. +- phy-mode: String, must be either "trgmii" or "rgmii" for port labeled + "cpu". + +See Documentation/devicetree/bindings/dsa/dsa.txt for a list of additional +required, optional properties and how the integrated switch subnodes must +be specified. + +Example: + + &mdio0 { + switch@0 { + compatible = "mediatek,mt7530"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + core-supply = <&mt6323_vpa_reg>; + io-supply = <&mt6323_vemc3v3_reg>; + reset-gpios = <&pio 33 0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + port@0 { + reg = <0>; + label = "lan0"; + }; + + port@1 { + reg = <1>; + label = "lan1"; + }; + + port@2 { + reg = <2>; + label = "lan2"; + }; + + port@3 { + reg = <3>; + label = "lan3"; + }; + + port@4 { + reg = <4>; + label = "wan"; + }; + + port@6 { + reg = <6>; + label = "cpu"; + ethernet = <&gmac0>; + phy-mode = "trgmii"; + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/moxa,moxart-mac.txt b/Documentation/devicetree/bindings/net/faraday,ftmac.txt index 583418b2c127..be4f55e23bf7 100644 --- a/Documentation/devicetree/bindings/net/moxa,moxart-mac.txt +++ b/Documentation/devicetree/bindings/net/faraday,ftmac.txt @@ -1,8 +1,11 @@ -MOXA ART Ethernet Controller +Faraday Ethernet Controller Required properties: -- compatible : Must be "moxa,moxart-mac" +- compatible : Must contain "faraday,ftmac", as well as one of + the SoC specific identifiers: + "andestech,atmac100" + "moxa,moxart-mac" - reg : Should contain register location and length - interrupts : Should contain the mac interrupt number diff --git a/Documentation/devicetree/bindings/net/ftgmac100.txt b/Documentation/devicetree/bindings/net/ftgmac100.txt new file mode 100644 index 000000000000..c1ce1680246f --- /dev/null +++ b/Documentation/devicetree/bindings/net/ftgmac100.txt @@ -0,0 +1,35 @@ +* Faraday Technology FTGMAC100 gigabit ethernet controller + +Required properties: +- compatible: "faraday,ftgmac100" + + Must also contain one of these if used as part of an Aspeed AST2400 + or 2500 family SoC as they have some subtle tweaks to the + implementation: + + - "aspeed,ast2400-mac" + - "aspeed,ast2500-mac" + +- reg: Address and length of the register set for the device +- interrupts: Should contain ethernet controller interrupt + +Optional properties: +- phy-mode: See ethernet.txt file in the same directory. If the property is + absent, "rgmii" is assumed. Supported values are "rgmii*" and "rmii" for + aspeed parts. Other (unknown) parts will accept any value. +- use-ncsi: Use the NC-SI stack instead of an MDIO PHY. Currently assumes + rmii (100bT) but kept as a separate property in case NC-SI grows support + for a gigabit link. +- no-hw-checksum: Used to disable HW checksum support. Here for backward + compatibility as the driver now should have correct defaults based on + the SoC. + +Example: + + mac0: ethernet@1e660000 { + compatible = "aspeed,ast2500-mac", "faraday,ftgmac100"; + reg = <0x1e660000 0x180>; + interrupts = <2>; + status = "okay"; + use-ncsi; + }; diff --git a/Documentation/devicetree/bindings/net/ieee802154/ca8210.txt b/Documentation/devicetree/bindings/net/ieee802154/ca8210.txt new file mode 100644 index 000000000000..a1046e636fa1 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ieee802154/ca8210.txt @@ -0,0 +1,28 @@ +* CA8210 IEEE 802.15.4 * + +Required properties: + - compatible: Should be "cascoda,ca8210" + - reg: Controlling chip select + - spi-max-frequency: Maximum clock speed, should be *less than* + 4000000 + - spi-cpol: Requires inverted clock polarity + - reset-gpio: GPIO attached to reset + - irq-gpio: GPIO attached to IRQ +Optional properties: + - extclock-enable: Include for the ca8210 to route its 16MHz clock + to an output + - extclock-freq: Frequency in Hz of the external clock + - extclock-gpio: GPIO of the ca8210 to output the clock on + +Example: + ca8210@0 { + compatible = "cascoda,ca8210"; + reg = <0>; + spi-max-frequency = <3000000>; + spi-cpol; + reset-gpio = <&gpio1 1 GPIO_ACTIVE_HIGH>; + irq-gpio = <&gpio1 2 GPIO_ACTIVE_HIGH>; + extclock-enable; + extclock-freq = 16000000; + extclock-gpio = 2; + }; diff --git a/Documentation/devicetree/bindings/net/marvell-orion-mdio.txt b/Documentation/devicetree/bindings/net/marvell-orion-mdio.txt index 9417e54c26c0..ccdabdcc8618 100644 --- a/Documentation/devicetree/bindings/net/marvell-orion-mdio.txt +++ b/Documentation/devicetree/bindings/net/marvell-orion-mdio.txt @@ -7,17 +7,20 @@ interface. Required properties: - compatible: "marvell,orion-mdio" -- reg: address and length of the SMI register +- reg: address and length of the MDIO registers. When an interrupt is + not present, the length is the size of the SMI register (4 bytes) + otherwise it must be 0x84 bytes to cover the interrupt control + registers. Optional properties: - interrupts: interrupt line number for the SMI error/done interrupt -- clocks: Phandle to the clock control device and gate bit +- clocks: phandle for up to three required clocks for the MDIO instance The child nodes of the MDIO driver are the individual PHY devices connected to this MDIO bus. They must have a "reg" property given the PHY address on the MDIO bus. -Example at the SoC level: +Example at the SoC level without an interrupt property: mdio { #address-cells = <1>; @@ -26,6 +29,16 @@ mdio { reg = <0xd0072004 0x4>; }; +Example with an interrupt property: + +mdio { + #address-cells = <1>; + #size-cells = <0>; + compatible = "marvell,orion-mdio"; + reg = <0xd0072004 0x84>; + interrupts = <30>; +}; + And at the board level: mdio { diff --git a/Documentation/devicetree/bindings/net/marvell-pp2.txt b/Documentation/devicetree/bindings/net/marvell-pp2.txt index 4754364df4c6..6b4956beff8c 100644 --- a/Documentation/devicetree/bindings/net/marvell-pp2.txt +++ b/Documentation/devicetree/bindings/net/marvell-pp2.txt @@ -1,17 +1,28 @@ -* Marvell Armada 375 Ethernet Controller (PPv2) +* Marvell Armada 375 Ethernet Controller (PPv2.1) + Marvell Armada 7K/8K Ethernet Controller (PPv2.2) Required properties: -- compatible: should be "marvell,armada-375-pp2" +- compatible: should be one of: + "marvell,armada-375-pp2" + "marvell,armada-7k-pp2" - reg: addresses and length of the register sets for the device. - Must contain the following register sets: + For "marvell,armada-375-pp2", must contain the following register + sets: - common controller registers - LMS registers - In addition, at least one port register set is required. -- clocks: a pointer to the reference clocks for this device, consequently: - - main controller clock - - GOP clock -- clock-names: names of used clocks, must be "pp_clk" and "gop_clk". + - one register area per Ethernet port + For "marvell,armada-7k-pp2", must contain the following register + sets: + - packet processor registers + - networking interfaces registers + +- clocks: pointers to the reference clocks for this device, consequently: + - main controller clock (for both armada-375-pp2 and armada-7k-pp2) + - GOP clock (for both armada-375-pp2 and armada-7k-pp2) + - MG clock (only for armada-7k-pp2) +- clock-names: names of used clocks, must be "pp_clk", "gop_clk" and + "mg_clk" (the latter only for armada-7k-pp2). The ethernet ports are represented by subnodes. At least one port is required. @@ -19,8 +30,10 @@ required. Required properties (port): - interrupts: interrupt for the port -- port-id: should be '0' or '1' for ethernet ports, and '2' for the - loopback port +- port-id: ID of the port from the MAC point of view +- gop-port-id: only for marvell,armada-7k-pp2, ID of the port from the + GOP (Group Of Ports) point of view. This ID is used to index the + per-port registers in the second register area. - phy-mode: See ethernet.txt file in the same directory Optional properties (port): @@ -29,7 +42,7 @@ Optional properties (port): - phy: a phandle to a phy node defining the PHY address (as the reg property, a single integer). -Example: +Example for marvell,armada-375-pp2: ethernet@f0000 { compatible = "marvell,armada-375-pp2"; @@ -57,3 +70,30 @@ ethernet@f0000 { phy-mode = "gmii"; }; }; + +Example for marvell,armada-7k-pp2: + +cpm_ethernet: ethernet@0 { + compatible = "marvell,armada-7k-pp22"; + reg = <0x0 0x100000>, <0x129000 0xb000>; + clocks = <&cpm_syscon0 1 3>, <&cpm_syscon0 1 9>, <&cpm_syscon0 1 5>; + clock-names = "pp_clk", "gop_clk", "gp_clk"; + + eth0: eth0 { + interrupts = <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>; + port-id = <0>; + gop-port-id = <0>; + }; + + eth1: eth1 { + interrupts = <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>; + port-id = <1>; + gop-port-id = <2>; + }; + + eth2: eth2 { + interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>; + port-id = <2>; + gop-port-id = <3>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/mdio.txt b/Documentation/devicetree/bindings/net/mdio.txt new file mode 100644 index 000000000000..96a53f89aa6e --- /dev/null +++ b/Documentation/devicetree/bindings/net/mdio.txt @@ -0,0 +1,37 @@ +Common MDIO bus properties. + +These are generic properties that can apply to any MDIO bus. + +Optional properties: +- reset-gpios: One GPIO that control the RESET lines of all PHYs on that MDIO + bus. +- reset-delay-us: RESET pulse width in microseconds. + +A list of child nodes, one per device on the bus is expected. These +should follow the generic phy.txt, or a device specific binding document. + +The 'reset-delay-us' indicates the RESET signal pulse width in microseconds and +applies to all PHY devices. It must therefore be appropriately determined based +on all PHY requirements (maximum value of all per-PHY RESET pulse widths). + +Example : +This example shows these optional properties, plus other properties +required for the TI Davinci MDIO driver. + + davinci_mdio: ethernet@0x5c030000 { + compatible = "ti,davinci_mdio"; + reg = <0x5c030000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + + reset-gpios = <&gpio2 5 GPIO_ACTIVE_LOW>; + reset-delay-us = <2>; + + ethphy0: ethernet-phy@1 { + reg = <1>; + }; + + ethphy1: ethernet-phy@3 { + reg = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/nfc/trf7970a.txt b/Documentation/devicetree/bindings/net/nfc/trf7970a.txt index 32b35a07abe4..c627bbb3009e 100644 --- a/Documentation/devicetree/bindings/net/nfc/trf7970a.txt +++ b/Documentation/devicetree/bindings/net/nfc/trf7970a.txt @@ -5,8 +5,8 @@ Required properties: - spi-max-frequency: Maximum SPI frequency (<= 2000000). - interrupt-parent: phandle of parent interrupt handler. - interrupts: A single interrupt specifier. -- ti,enable-gpios: Two GPIO entries used for 'EN' and 'EN2' pins on the - TRF7970A. +- ti,enable-gpios: One or two GPIO entries used for 'EN' and 'EN2' pins on the + TRF7970A. EN2 is optional. - vin-supply: Regulator for supply voltage to VIN pin Optional SoC Specific Properties: @@ -21,6 +21,8 @@ Optional SoC Specific Properties: - t5t-rmb-extra-byte-quirk: Specify that the trf7970a has the erratum where an extra byte is returned by Read Multiple Block commands issued to Type 5 tags. +- vdd-io-supply: Regulator specifying voltage for vdd-io +- clock-frequency: Set to specify that the input frequency to the trf7970a is 13560000Hz or 27120000Hz Example (for ARM-based BeagleBone with TRF7970A on SPI1): @@ -39,10 +41,12 @@ Example (for ARM-based BeagleBone with TRF7970A on SPI1): <&gpio2 5 GPIO_ACTIVE_LOW>; vin-supply = <&ldo3_reg>; vin-voltage-override = <5000000>; + vdd-io-supply = <&ldo2_reg>; autosuspend-delay = <30000>; irq-status-read-quirk; en2-rf-quirk; t5t-rmb-extra-byte-quirk; + clock-frequency = <27120000>; status = "okay"; }; }; diff --git a/Documentation/devicetree/bindings/net/nokia-bluetooth.txt b/Documentation/devicetree/bindings/net/nokia-bluetooth.txt new file mode 100644 index 000000000000..42be7dc9a70b --- /dev/null +++ b/Documentation/devicetree/bindings/net/nokia-bluetooth.txt @@ -0,0 +1,51 @@ +Nokia Bluetooth Chips +--------------------- + +Nokia phones often come with UART connected bluetooth chips from different +vendors and modified device API. Those devices speak a protocol named H4+ +(also known as h4p) by Nokia, which is similar to the H4 protocol from the +Bluetooth standard. In addition to the H4 protocol it specifies two more +UART status lines for wakeup of UART transceivers to improve power management +and a few new packet types used to negotiate uart speed. + +Required properties: + + - compatible: should contain "nokia,h4p-bluetooth" as well as one of the following: + * "brcm,bcm2048-nokia" + * "ti,wl1271-bluetooth-nokia" + - reset-gpios: GPIO specifier, used to reset the BT module (active low) + - bluetooth-wakeup-gpios: GPIO specifier, used to wakeup the BT module (active high) + - host-wakeup-gpios: GPIO specifier, used to wakeup the host processor (active high) + - clock-names: should be "sysclk" + - clocks: should contain a clock specifier for every name in clock-names + +Optional properties: + + - None + +Example: + +/ { + /* controlled (enabled/disabled) directly by BT module */ + bluetooth_clk: vctcxo { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <38400000>; + }; +}; + +&uart2 { + pinctrl-names = "default"; + pinctrl-0 = <&uart2_pins>; + + bluetooth { + compatible = "ti,wl1271-bluetooth-nokia", "nokia,h4p-bluetooth"; + + reset-gpios = <&gpio1 26 GPIO_ACTIVE_LOW>; /* gpio26 */ + host-wakeup-gpios = <&gpio4 5 GPIO_ACTIVE_HIGH>; /* gpio101 */ + bluetooth-wakeup-gpios = <&gpio2 5 GPIO_ACTIVE_HIGH>; /* gpio37 */ + + clocks = <&bluetooth_clk>; + clock-names = "sysclk"; + }; +}; diff --git a/Documentation/devicetree/bindings/net/stmmac.txt b/Documentation/devicetree/bindings/net/stmmac.txt index d3bfc2b30fb5..c3a7be6615c5 100644 --- a/Documentation/devicetree/bindings/net/stmmac.txt +++ b/Documentation/devicetree/bindings/net/stmmac.txt @@ -7,9 +7,12 @@ Required properties: - interrupt-parent: Should be the phandle for the interrupt controller that services interrupts for this device - interrupts: Should contain the STMMAC interrupts -- interrupt-names: Should contain the interrupt names "macirq" - "eth_wake_irq" if this interrupt is supported in the "interrupts" - property +- interrupt-names: Should contain a list of interrupt names corresponding to + the interrupts in the interrupts property, if available. + Valid interrupt names are: + - "macirq" (combined signal for various interrupt events) + - "eth_wake_irq" (the interrupt to manage the remote wake-up packet detection) + - "eth_lpi" (the interrupt that occurs when Tx or Rx enters/exits LPI state) - phy-mode: See ethernet.txt file in the same directory. - snps,reset-gpio gpio number for phy reset. - snps,reset-active-low boolean flag to indicate if phy reset is active low. @@ -28,9 +31,9 @@ Optional properties: clocks may be specified in derived bindings. - clock-names: One name for each entry in the clocks property, the first one should be "stmmaceth" and the second one should be "pclk". -- clk_ptp_ref: this is the PTP reference clock; in case of the PTP is - available this clock is used for programming the Timestamp Addend Register. - If not passed then the system clock will be used and this is fine on some +- ptp_ref: this is the PTP reference clock; in case of the PTP is available + this clock is used for programming the Timestamp Addend Register. If not + passed then the system clock will be used and this is fine on some platforms. - tx-fifo-depth: See ethernet.txt file in the same directory - rx-fifo-depth: See ethernet.txt file in the same directory @@ -72,7 +75,45 @@ Optional properties: - snps,mb: mixed-burst - snps,rb: rebuild INCRx Burst - mdio: with compatible = "snps,dwmac-mdio", create and register mdio bus. - +- Multiple RX Queues parameters: below the list of all the parameters to + configure the multiple RX queues: + - snps,rx-queues-to-use: number of RX queues to be used in the driver + - Choose one of these RX scheduling algorithms: + - snps,rx-sched-sp: Strict priority + - snps,rx-sched-wsp: Weighted Strict priority + - For each RX queue + - Choose one of these modes: + - snps,dcb-algorithm: Queue to be enabled as DCB + - snps,avb-algorithm: Queue to be enabled as AVB + - snps,map-to-dma-channel: Channel to map + - Specifiy specific packet routing: + - snps,route-avcp: AV Untagged Control packets + - snps,route-ptp: PTP Packets + - snps,route-dcbcp: DCB Control Packets + - snps,route-up: Untagged Packets + - snps,route-multi-broad: Multicast & Broadcast Packets + - snps,priority: RX queue priority (Range: 0x0 to 0xF) +- Multiple TX Queues parameters: below the list of all the parameters to + configure the multiple TX queues: + - snps,tx-queues-to-use: number of TX queues to be used in the driver + - Choose one of these TX scheduling algorithms: + - snps,tx-sched-wrr: Weighted Round Robin + - snps,tx-sched-wfq: Weighted Fair Queuing + - snps,tx-sched-dwrr: Deficit Weighted Round Robin + - snps,tx-sched-sp: Strict priority + - For each TX queue + - snps,weight: TX queue weight (if using a DCB weight algorithm) + - Choose one of these modes: + - snps,dcb-algorithm: TX queue will be working in DCB + - snps,avb-algorithm: TX queue will be working in AVB + [Attention] Queue 0 is reserved for legacy traffic + and so no AVB is available in this queue. + - Configure Credit Base Shaper (if AVB Mode selected): + - snps,send_slope: enable Low Power Interface + - snps,idle_slope: unlock on WoL + - snps,high_credit: max write outstanding req. limit + - snps,low_credit: max read outstanding req. limit + - snps,priority: TX queue priority (Range: 0x0 to 0xF) Examples: stmmac_axi_setup: stmmac-axi-config { @@ -81,12 +122,41 @@ Examples: snps,blen = <256 128 64 32 0 0 0>; }; + mtl_rx_setup: rx-queues-config { + snps,rx-queues-to-use = <1>; + snps,rx-sched-sp; + queue0 { + snps,dcb-algorithm; + snps,map-to-dma-channel = <0x0>; + snps,priority = <0x0>; + }; + }; + + mtl_tx_setup: tx-queues-config { + snps,tx-queues-to-use = <2>; + snps,tx-sched-wrr; + queue0 { + snps,weight = <0x10>; + snps,dcb-algorithm; + snps,priority = <0x0>; + }; + + queue1 { + snps,avb-algorithm; + snps,send_slope = <0x1000>; + snps,idle_slope = <0x1000>; + snps,high_credit = <0x3E800>; + snps,low_credit = <0xFFC18000>; + snps,priority = <0x1>; + }; + }; + gmac0: ethernet@e0800000 { compatible = "st,spear600-gmac"; reg = <0xe0800000 0x8000>; interrupt-parent = <&vic1>; - interrupts = <24 23>; - interrupt-names = "macirq", "eth_wake_irq"; + interrupts = <24 23 22>; + interrupt-names = "macirq", "eth_wake_irq", "eth_lpi"; mac-address = [000000000000]; /* Filled in by U-Boot */ max-frame-size = <3800>; phy-mode = "gmii"; @@ -104,4 +174,6 @@ Examples: phy1: ethernet-phy@0 { }; }; + snps,mtl-rx-config = <&mtl_rx_setup>; + snps,mtl-tx-config = <&mtl_tx_setup>; }; diff --git a/Documentation/devicetree/bindings/net/ti,wilink-st.txt b/Documentation/devicetree/bindings/net/ti,wilink-st.txt new file mode 100644 index 000000000000..cbad73a84ac4 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ti,wilink-st.txt @@ -0,0 +1,35 @@ +TI WiLink 7/8 (wl12xx/wl18xx) Shared Transport BT/FM/GPS devices + +TI WiLink devices have a UART interface for providing Bluetooth, FM radio, +and GPS over what's called "shared transport". The shared transport is +standard BT HCI protocol with additional channels for the other functions. + +These devices also have a separate WiFi interface as described in +wireless/ti,wlcore.txt. + +This bindings follows the UART slave device binding in +../serial/slave-device.txt. + +Required properties: + - compatible: should be one of the following: + "ti,wl1271-st" + "ti,wl1273-st" + "ti,wl1831-st" + "ti,wl1835-st" + "ti,wl1837-st" + +Optional properties: + - enable-gpios : GPIO signal controlling enabling of BT. Active high. + - vio-supply : Vio input supply (1.8V) + - vbat-supply : Vbat input supply (2.9-4.8V) + +Example: + +&serial0 { + compatible = "ns16550a"; + ... + bluetooth { + compatible = "ti,wl1835-st"; + enable-gpios = <&gpio1 7 GPIO_ACTIVE_HIGH>; + }; +}; diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt index d543ed3f5363..ef06d061913c 100644 --- a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt +++ b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt @@ -1,7 +1,11 @@ Allwinner sunxi-sid Required properties: -- compatible: "allwinner,sun4i-a10-sid" or "allwinner,sun7i-a20-sid" +- compatible: Should be one of the following: + "allwinner,sun4i-a10-sid" + "allwinner,sun7i-a20-sid" + "allwinner,sun8i-h3-sid" + - reg: Should contain registers location and length = Data cells = diff --git a/Documentation/devicetree/bindings/nvmem/imx-iim.txt b/Documentation/devicetree/bindings/nvmem/imx-iim.txt new file mode 100644 index 000000000000..1978c5bcd96d --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/imx-iim.txt @@ -0,0 +1,22 @@ +Freescale i.MX IC Identification Module (IIM) device tree bindings + +This binding represents the IC Identification Module (IIM) found on +i.MX25, i.MX27, i.MX31, i.MX35, i.MX51 and i.MX53 SoCs. + +Required properties: +- compatible: should be one of + "fsl,imx25-iim", "fsl,imx27-iim", + "fsl,imx31-iim", "fsl,imx35-iim", + "fsl,imx51-iim", "fsl,imx53-iim", +- reg: Should contain the register base and length. +- interrupts: Should contain the interrupt for the IIM +- clocks: Should contain a phandle pointing to the gated peripheral clock. + +Example: + + iim: iim@63f98000 { + compatible = "fsl,imx53-iim", "fsl,imx27-iim"; + reg = <0x63f98000 0x4000>; + interrupts = <69>; + clocks = <&clks IMX5_CLK_IIM_GATE>; + }; diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt index 966a72ecc6bd..70d791b03ea1 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -9,14 +9,19 @@ Required properties: "fsl,imx6sl-ocotp" (i.MX6SL), or "fsl,imx6sx-ocotp" (i.MX6SX), "fsl,imx6ul-ocotp" (i.MX6UL), + "fsl,imx7d-ocotp" (i.MX7D/S), followed by "syscon". - reg: Should contain the register base and length. - clocks: Should contain a phandle pointing to the gated peripheral clock. +Optional properties: +- read-only: disable write access + Example: ocotp: ocotp@021bc000 { compatible = "fsl,imx6q-ocotp", "syscon"; reg = <0x021bc000 0x4000>; clocks = <&clks IMX6QDL_CLK_IIM>; + read-only; }; diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt index 1392c705ceca..b2480dd38c11 100644 --- a/Documentation/devicetree/bindings/pci/designware-pcie.txt +++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt @@ -6,30 +6,40 @@ Required properties: - reg-names: Must be "config" for the PCIe configuration space. (The old way of getting the configuration address space from "ranges" is deprecated and should be avoided.) +- num-lanes: number of lanes to use +RC mode: - #address-cells: set to <3> - #size-cells: set to <2> - device_type: set to "pci" - ranges: ranges for the PCI memory and I/O regions - #interrupt-cells: set to <1> -- interrupt-map-mask and interrupt-map: standard PCI properties - to define the mapping of the PCIe interface to interrupt +- interrupt-map-mask and interrupt-map: standard PCI + properties to define the mapping of the PCIe interface to interrupt numbers. -- num-lanes: number of lanes to use +EP mode: +- num-ib-windows: number of inbound address translation + windows +- num-ob-windows: number of outbound address translation + windows Optional properties: -- num-viewport: number of view ports configured in hardware. If a platform - does not specify it, the driver assumes 2. - num-lanes: number of lanes to use (this property should be specified unless the link is brought already up in BIOS) - reset-gpio: gpio pin number of power good signal -- bus-range: PCI bus numbers covered (it is recommended for new devicetrees to - specify this property, to keep backwards compatibility a range of 0x00-0xff - is assumed if not present) - clocks: Must contain an entry for each entry in clock-names. See ../clocks/clock-bindings.txt for details. - clock-names: Must include the following entries: - "pcie" - "pcie_bus" +RC mode: +- num-viewport: number of view ports configured in + hardware. If a platform does not specify it, the driver assumes 2. +- bus-range: PCI bus numbers covered (it is recommended + for new devicetrees to specify this property, to keep backwards + compatibility a range of 0x00-0xff is assumed if not present) +EP mode: +- max-functions: maximum number of functions that can be + configured Example configuration: diff --git a/Documentation/devicetree/bindings/pci/faraday,ftpci100.txt b/Documentation/devicetree/bindings/pci/faraday,ftpci100.txt new file mode 100644 index 000000000000..35d4a979bb7b --- /dev/null +++ b/Documentation/devicetree/bindings/pci/faraday,ftpci100.txt @@ -0,0 +1,129 @@ +Faraday Technology FTPCI100 PCI Host Bridge + +This PCI bridge is found inside that Cortina Systems Gemini SoC platform and +is a generic IP block from Faraday Technology. It exists in two variants: +plain and dual PCI. The plain version embeds a cascading interrupt controller +into the host bridge. The dual version routes the interrupts to the host +chips interrupt controller. + +The host controller appear on the PCI bus with vendor ID 0x159b (Faraday +Technology) and product ID 0x4321. + +Mandatory properties: + +- compatible: ranging from specific to generic, should be one of + "cortina,gemini-pci", "faraday,ftpci100" + "cortina,gemini-pci-dual", "faraday,ftpci100-dual" + "faraday,ftpci100" + "faraday,ftpci100-dual" +- reg: memory base and size for the host bridge +- #address-cells: set to <3> +- #size-cells: set to <2> +- #interrupt-cells: set to <1> +- bus-range: set to <0x00 0xff> +- device_type, set to "pci" +- ranges: see pci.txt +- interrupt-map-mask: see pci.txt +- interrupt-map: see pci.txt +- dma-ranges: three ranges for the inbound memory region. The ranges must + be aligned to a 1MB boundary, and may be 1MB, 2MB, 4MB, 8MB, 16MB, 32MB, 64MB, + 128MB, 256MB, 512MB, 1GB or 2GB in size. The memory should be marked as + pre-fetchable. + +Mandatory subnodes: +- For "faraday,ftpci100" a node representing the interrupt-controller inside the + host bridge is mandatory. It has the following mandatory properties: + - interrupt: see interrupt-controller/interrupts.txt + - interrupt-parent: see interrupt-controller/interrupts.txt + - interrupt-controller: see interrupt-controller/interrupts.txt + - #address-cells: set to <0> + - #interrupt-cells: set to <1> + +I/O space considerations: + +The plain variant has 128MiB of non-prefetchable memory space, whereas the +"dual" variant has 64MiB. Take this into account when describing the ranges. + +Interrupt map considerations: + +The "dual" variant will get INT A, B, C, D from the system interrupt controller +and should point to respective interrupt in that controller in its +interrupt-map. + +The code which is the only documentation of how the Faraday PCI (the non-dual +variant) interrupts assigns the default interrupt mapping/swizzling has +typically been like this, doing the swizzling on the interrupt controller side +rather than in the interconnect: + +interrupt-map-mask = <0xf800 0 0 7>; +interrupt-map = + <0x4800 0 0 1 &pci_intc 0>, /* Slot 9 */ + <0x4800 0 0 2 &pci_intc 1>, + <0x4800 0 0 3 &pci_intc 2>, + <0x4800 0 0 4 &pci_intc 3>, + <0x5000 0 0 1 &pci_intc 1>, /* Slot 10 */ + <0x5000 0 0 2 &pci_intc 2>, + <0x5000 0 0 3 &pci_intc 3>, + <0x5000 0 0 4 &pci_intc 0>, + <0x5800 0 0 1 &pci_intc 2>, /* Slot 11 */ + <0x5800 0 0 2 &pci_intc 3>, + <0x5800 0 0 3 &pci_intc 0>, + <0x5800 0 0 4 &pci_intc 1>, + <0x6000 0 0 1 &pci_intc 3>, /* Slot 12 */ + <0x6000 0 0 2 &pci_intc 0>, + <0x6000 0 0 3 &pci_intc 1>, + <0x6000 0 0 4 &pci_intc 2>; + +Example: + +pci@50000000 { + compatible = "cortina,gemini-pci", "faraday,ftpci100"; + reg = <0x50000000 0x100>; + interrupts = <8 IRQ_TYPE_LEVEL_HIGH>, /* PCI A */ + <26 IRQ_TYPE_LEVEL_HIGH>, /* PCI B */ + <27 IRQ_TYPE_LEVEL_HIGH>, /* PCI C */ + <28 IRQ_TYPE_LEVEL_HIGH>; /* PCI D */ + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + + bus-range = <0x00 0xff>; + ranges = /* 1MiB I/O space 0x50000000-0x500fffff */ + <0x01000000 0 0 0x50000000 0 0x00100000>, + /* 128MiB non-prefetchable memory 0x58000000-0x5fffffff */ + <0x02000000 0 0x58000000 0x58000000 0 0x08000000>; + + /* DMA ranges */ + dma-ranges = + /* 128MiB at 0x00000000-0x07ffffff */ + <0x02000000 0 0x00000000 0x00000000 0 0x08000000>, + /* 64MiB at 0x00000000-0x03ffffff */ + <0x02000000 0 0x00000000 0x00000000 0 0x04000000>, + /* 64MiB at 0x00000000-0x03ffffff */ + <0x02000000 0 0x00000000 0x00000000 0 0x04000000>; + + interrupt-map-mask = <0xf800 0 0 7>; + interrupt-map = + <0x4800 0 0 1 &pci_intc 0>, /* Slot 9 */ + <0x4800 0 0 2 &pci_intc 1>, + <0x4800 0 0 3 &pci_intc 2>, + <0x4800 0 0 4 &pci_intc 3>, + <0x5000 0 0 1 &pci_intc 1>, /* Slot 10 */ + <0x5000 0 0 2 &pci_intc 2>, + <0x5000 0 0 3 &pci_intc 3>, + <0x5000 0 0 4 &pci_intc 0>, + <0x5800 0 0 1 &pci_intc 2>, /* Slot 11 */ + <0x5800 0 0 2 &pci_intc 3>, + <0x5800 0 0 3 &pci_intc 0>, + <0x5800 0 0 4 &pci_intc 1>, + <0x6000 0 0 1 &pci_intc 3>, /* Slot 12 */ + <0x6000 0 0 2 &pci_intc 0>, + <0x6000 0 0 3 &pci_intc 0>, + <0x6000 0 0 4 &pci_intc 0>; + pci_intc: interrupt-controller { + interrupt-parent = <&intcon>; + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + }; +}; diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt index 83aeb1f5a645..e3d5680875b1 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt @@ -4,7 +4,11 @@ This PCIe host controller is based on the Synopsis Designware PCIe IP and thus inherits all the common properties defined in designware-pcie.txt. Required properties: -- compatible: "fsl,imx6q-pcie", "fsl,imx6sx-pcie", "fsl,imx6qp-pcie" +- compatible: + - "fsl,imx6q-pcie" + - "fsl,imx6sx-pcie", + - "fsl,imx6qp-pcie" + - "fsl,imx7d-pcie" - reg: base address and length of the PCIe controller - interrupts: A list of interrupt outputs of the controller. Must contain an entry for each entry in the interrupt-names property. @@ -34,6 +38,14 @@ Additional required properties for imx6sx-pcie: - clock names: Must include the following additional entries: - "pcie_inbound_axi" +Additional required properties for imx7d-pcie: +- power-domains: Must be set to a phandle pointing to PCIE_PHY power domain +- resets: Must contain phandles to PCIe-related reset lines exposed by SRC + IP block +- reset-names: Must contain the following entires: + - "pciephy" + - "apps" + Example: pcie@0x01000000 { diff --git a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt index b7fa3b97986d..a339dbb15493 100644 --- a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt +++ b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt @@ -44,13 +44,19 @@ Hip05 Example (note that Hip06 is the same except compatible): }; HiSilicon Hip06/Hip07 PCIe host bridge DT (almost-ECAM) description. + +Some BIOSes place the host controller in a mode where it is ECAM +compliant for all devices other than the root complex. In such cases, +the host controller should be described as below. + The properties and their meanings are identical to those described in host-generic-pci.txt except as listed below. Properties of the host controller node that differ from host-generic-pci.txt: -- compatible : Must be "hisilicon,pcie-almost-ecam" +- compatible : Must be "hisilicon,hip06-pcie-ecam", or + "hisilicon,hip07-pcie-ecam" - reg : Two entries: First the ECAM configuration space for any other bus underneath the root bus. Second, the base @@ -59,7 +65,7 @@ host-generic-pci.txt: Example: pcie0: pcie@a0090000 { - compatible = "hisilicon,pcie-almost-ecam"; + compatible = "hisilicon,hip06-pcie-ecam"; reg = <0 0xb0000000 0 0x2000000>, /* ECAM configuration space */ <0 0xa0090000 0 0x10000>; /* host bridge registers */ bus-range = <0 31>; diff --git a/Documentation/devicetree/bindings/pci/ti-pci.txt b/Documentation/devicetree/bindings/pci/ti-pci.txt index 60e25161f351..6a07c96227e0 100644 --- a/Documentation/devicetree/bindings/pci/ti-pci.txt +++ b/Documentation/devicetree/bindings/pci/ti-pci.txt @@ -1,17 +1,22 @@ TI PCI Controllers PCIe Designware Controller - - compatible: Should be "ti,dra7-pcie"" - - reg : Two register ranges as listed in the reg-names property - - reg-names : The first entry must be "ti-conf" for the TI specific registers - The second entry must be "rc-dbics" for the designware pcie - registers - The third entry must be "config" for the PCIe configuration space + - compatible: Should be "ti,dra7-pcie" for RC + Should be "ti,dra7-pcie-ep" for EP - phys : list of PHY specifiers (used by generic PHY framework) - phy-names : must be "pcie-phy0", "pcie-phy1", "pcie-phyN".. based on the number of PHYs as specified in *phys* property. - ti,hwmods : Name of the hwmod associated to the pcie, "pcie<X>", where <X> is the instance number of the pcie from the HW spec. + - num-lanes as specified in ../designware-pcie.txt + +HOST MODE +========= + - reg : Two register ranges as listed in the reg-names property + - reg-names : The first entry must be "ti-conf" for the TI specific registers + The second entry must be "rc-dbics" for the DesignWare PCIe + registers + The third entry must be "config" for the PCIe configuration space - interrupts : Two interrupt entries must be specified. The first one is for main interrupt line and the second for MSI interrupt line. - #address-cells, @@ -19,13 +24,36 @@ PCIe Designware Controller #interrupt-cells, device_type, ranges, - num-lanes, interrupt-map-mask, interrupt-map : as specified in ../designware-pcie.txt +DEVICE MODE +=========== + - reg : Four register ranges as listed in the reg-names property + - reg-names : "ti-conf" for the TI specific registers + "ep_dbics" for the standard configuration registers as + they are locally accessed within the DIF CS space + "ep_dbics2" for the standard configuration registers as + they are locally accessed within the DIF CS2 space + "addr_space" used to map remote RC address space + - interrupts : one interrupt entries must be specified for main interrupt. + - num-ib-windows : number of inbound address translation windows + - num-ob-windows : number of outbound address translation windows + - ti,syscon-unaligned-access: phandle to the syscon DT node. The 1st argument + should contain the register offset within syscon + and the 2nd argument should contain the bit field + for setting the bit to enable unaligned + access. + Optional Property: - gpios : Should be added if a gpio line is required to drive PERST# line +NOTE: Two DT nodes may be added for each PCI controller; one for host +mode and another for device mode. So in order for PCI to +work in host mode, EP mode DT node should be disabled and in order to PCI to +work in EP mode, host mode DT node should be disabled. Host mode and EP +mode are mutually exclusive. + Example: axi { compatible = "simple-bus"; diff --git a/Documentation/devicetree/bindings/phy/brcm,nsp-usb3-phy.txt b/Documentation/devicetree/bindings/phy/brcm,nsp-usb3-phy.txt deleted file mode 100644 index e68ae5dec9c9..000000000000 --- a/Documentation/devicetree/bindings/phy/brcm,nsp-usb3-phy.txt +++ /dev/null @@ -1,39 +0,0 @@ -Broadcom USB3 phy binding for northstar plus SoC -The USB3 phy is internal to the SoC and is accessed using mdio interface. - -Required mdio bus properties: -- reg: Should be 0x0 for SoC internal USB3 phy -- #address-cells: must be 1 -- #size-cells: must be 0 - -Required USB3 PHY properties: -- compatible: should be "brcm,nsp-usb3-phy" -- reg: USB3 Phy address on SoC internal MDIO bus and it should be 0x10. -- usb3-ctrl-syscon: handler of syscon node defining physical address - of usb3 control register. -- #phy-cells: must be 0 - -Required usb3 control properties: -- compatible: should be "brcm,nsp-usb3-ctrl" -- reg: offset and length of the control registers - -Example: - - mdio@0 { - reg = <0x0>; - #address-cells = <1>; - #size-cells = <0>; - - usb3_phy: usb-phy@10 { - compatible = "brcm,nsp-usb3-phy"; - reg = <0x10>; - usb3-ctrl-syscon = <&usb3_ctrl>; - #phy-cells = <0>; - status = "disabled"; - }; - }; - - usb3_ctrl: syscon@104408 { - compatible = "brcm,nsp-usb3-ctrl", "syscon"; - reg = <0x104408 0x3fc>; - }; diff --git a/Documentation/devicetree/bindings/phy/phy-mt65xx-usb.txt b/Documentation/devicetree/bindings/phy/phy-mt65xx-usb.txt index 33a2b1ee3f3e..0acc5a99fb79 100644 --- a/Documentation/devicetree/bindings/phy/phy-mt65xx-usb.txt +++ b/Documentation/devicetree/bindings/phy/phy-mt65xx-usb.txt @@ -6,12 +6,11 @@ This binding describes a usb3.0 phy for mt65xx platforms of Medaitek SoC. Required properties (controller (parent) node): - compatible : should be one of "mediatek,mt2701-u3phy" + "mediatek,mt2712-u3phy" "mediatek,mt8173-u3phy" - - reg : offset and length of register for phy, exclude port's - register. - - clocks : a list of phandle + clock-specifier pairs, one for each - entry in clock-names - - clock-names : must contain + - clocks : (deprecated, use port's clocks instead) a list of phandle + + clock-specifier pairs, one for each entry in clock-names + - clock-names : (deprecated, use port's one instead) must contain "u3phya_ref": for reference clock of usb3.0 analog phy. Required nodes : a sub-node is required for each port the controller @@ -19,8 +18,19 @@ Required nodes : a sub-node is required for each port the controller 'reg' property is used inside these nodes to describe the controller's topology. +Optional properties (controller (parent) node): + - reg : offset and length of register shared by multiple ports, + exclude port's private register. It is needed on mt2701 + and mt8173, but not on mt2712. + Required properties (port (child) node): - reg : address and length of the register set for the port. +- clocks : a list of phandle + clock-specifier pairs, one for each + entry in clock-names +- clock-names : must contain + "ref": 48M reference clock for HighSpeed analog phy; and 26M + reference clock for SuperSpeed analog phy, sometimes is + 24M, 25M or 27M, depended on platform. - #phy-cells : should be 1 (See second example) cell after port phandle is phy type from: - PHY_TYPE_USB2 @@ -31,21 +41,31 @@ Example: u3phy: usb-phy@11290000 { compatible = "mediatek,mt8173-u3phy"; reg = <0 0x11290000 0 0x800>; - clocks = <&apmixedsys CLK_APMIXED_REF2USB_TX>; - clock-names = "u3phya_ref"; #address-cells = <2>; #size-cells = <2>; ranges; status = "okay"; - phy_port0: port@11290800 { - reg = <0 0x11290800 0 0x800>; + u2port0: usb-phy@11290800 { + reg = <0 0x11290800 0 0x100>; + clocks = <&apmixedsys CLK_APMIXED_REF2USB_TX>; + clock-names = "ref"; #phy-cells = <1>; status = "okay"; }; - phy_port1: port@11291000 { - reg = <0 0x11291000 0 0x800>; + u3port0: usb-phy@11290900 { + reg = <0 0x11290800 0 0x700>; + clocks = <&clk26m>; + clock-names = "ref"; + #phy-cells = <1>; + status = "okay"; + }; + + u2port1: usb-phy@11291000 { + reg = <0 0x11291000 0 0x100>; + clocks = <&apmixedsys CLK_APMIXED_REF2USB_TX>; + clock-names = "ref"; #phy-cells = <1>; status = "okay"; }; @@ -64,7 +84,54 @@ Example: usb30: usb@11270000 { ... - phys = <&phy_port0 PHY_TYPE_USB3>; - phy-names = "usb3-0"; + phys = <&u2port0 PHY_TYPE_USB2>, <&u3port0 PHY_TYPE_USB3>; + phy-names = "usb2-0", "usb3-0"; ... }; + + +Layout differences of banks between mt8173/mt2701 and mt2712 +------------------------------------------------------------- +mt8173 and mt2701: +port offset bank +shared 0x0000 SPLLC + 0x0100 FMREG +u2 port0 0x0800 U2PHY_COM +u3 port0 0x0900 U3PHYD + 0x0a00 U3PHYD_BANK2 + 0x0b00 U3PHYA + 0x0c00 U3PHYA_DA +u2 port1 0x1000 U2PHY_COM +u3 port1 0x1100 U3PHYD + 0x1200 U3PHYD_BANK2 + 0x1300 U3PHYA + 0x1400 U3PHYA_DA +u2 port2 0x1800 U2PHY_COM + ... + +mt2712: +port offset bank +u2 port0 0x0000 MISC + 0x0100 FMREG + 0x0300 U2PHY_COM +u3 port0 0x0700 SPLLC + 0x0800 CHIP + 0x0900 U3PHYD + 0x0a00 U3PHYD_BANK2 + 0x0b00 U3PHYA + 0x0c00 U3PHYA_DA +u2 port1 0x1000 MISC + 0x1100 FMREG + 0x1300 U2PHY_COM +u3 port1 0x1700 SPLLC + 0x1800 CHIP + 0x1900 U3PHYD + 0x1a00 U3PHYD_BANK2 + 0x1b00 U3PHYA + 0x1c00 U3PHYA_DA +u2 port2 0x2000 MISC + ... + + SPLLC shared by u3 ports and FMREG shared by u2 ports on +mt8173/mt2701 are put back into each port; a new bank MISC for +u2 ports and CHIP for u3 ports are added on mt2712. diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt index 3c29c77a7018..e71a8d23f4a8 100644 --- a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt @@ -2,6 +2,7 @@ ROCKCHIP USB2.0 PHY WITH INNO IP BLOCK Required properties (phy (parent) node): - compatible : should be one of the listed compatibles: + * "rockchip,rk3328-usb2phy" * "rockchip,rk3366-usb2phy" * "rockchip,rk3399-usb2phy" - reg : the address offset of grf for usb-phy configuration. @@ -11,6 +12,11 @@ Required properties (phy (parent) node): Optional properties: - clocks : phandle + phy specifier pair, for the input clock of phy. - clock-names : input clock name of phy, must be "phyclk". + - assigned-clocks : phandle of usb 480m clock. + - assigned-clock-parents : parent of usb 480m clock, select between + usb-phy output 480m and xin24m. + Refer to clk/clock-bindings.txt for generic clock + consumer properties. Required nodes : a sub-node is required for each port the phy provides. The sub-node name is used to identify host or otg port, diff --git a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt new file mode 100644 index 000000000000..e11c563a65ec --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt @@ -0,0 +1,106 @@ +Qualcomm QMP PHY controller +=========================== + +QMP phy controller supports physical layer functionality for a number of +controllers on Qualcomm chipsets, such as, PCIe, UFS, and USB. + +Required properties: + - compatible: compatible list, contains: + "qcom,msm8996-qmp-pcie-phy" for 14nm PCIe phy on msm8996, + "qcom,msm8996-qmp-usb3-phy" for 14nm USB3 phy on msm8996. + + - reg: offset and length of register set for PHY's common serdes block. + + - #clock-cells: must be 1 + - Phy pll outputs a bunch of clocks for Tx, Rx and Pipe + interface (for pipe based PHYs). These clock are then gate-controlled + by gcc. + - #address-cells: must be 1 + - #size-cells: must be 1 + - ranges: must be present + + - clocks: a list of phandles and clock-specifier pairs, + one for each entry in clock-names. + - clock-names: "cfg_ahb" for phy config clock, + "aux" for phy aux clock, + "ref" for 19.2 MHz ref clk, + For "qcom,msm8996-qmp-pcie-phy" must contain: + "aux", "cfg_ahb", "ref". + For "qcom,msm8996-qmp-usb3-phy" must contain: + "aux", "cfg_ahb", "ref". + + - resets: a list of phandles and reset controller specifier pairs, + one for each entry in reset-names. + - reset-names: "phy" for reset of phy block, + "common" for phy common block reset, + "cfg" for phy's ahb cfg block reset (Optional). + For "qcom,msm8996-qmp-pcie-phy" must contain: + "phy", "common", "cfg". + For "qcom,msm8996-qmp-usb3-phy" must contain + "phy", "common". + + - vdda-phy-supply: Phandle to a regulator supply to PHY core block. + - vdda-pll-supply: Phandle to 1.8V regulator supply to PHY refclk pll block. + +Optional properties: + - vddp-ref-clk-supply: Phandle to a regulator supply to any specific refclk + pll block. + +Required nodes: + - Each device node of QMP phy is required to have as many child nodes as + the number of lanes the PHY has. + +Required properties for child node: + - reg: list of offset and length pairs of register sets for PHY blocks - + tx, rx and pcs. + + - #phy-cells: must be 0 + + - clocks: a list of phandles and clock-specifier pairs, + one for each entry in clock-names. + - clock-names: Must contain following for pcie and usb qmp phys: + "pipe<lane-number>" for pipe clock specific to each lane. + + - resets: a list of phandles and reset controller specifier pairs, + one for each entry in reset-names. + - reset-names: Must contain following for pcie qmp phys: + "lane<lane-number>" for reset specific to each lane. + +Example: + phy@34000 { + compatible = "qcom,msm8996-qmp-pcie-phy"; + reg = <0x34000 0x488>; + #clock-cells = <1>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + clocks = <&gcc GCC_PCIE_PHY_AUX_CLK>, + <&gcc GCC_PCIE_PHY_CFG_AHB_CLK>, + <&gcc GCC_PCIE_CLKREF_CLK>; + clock-names = "aux", "cfg_ahb", "ref"; + + vdda-phy-supply = <&pm8994_l28>; + vdda-pll-supply = <&pm8994_l12>; + + resets = <&gcc GCC_PCIE_PHY_BCR>, + <&gcc GCC_PCIE_PHY_COM_BCR>, + <&gcc GCC_PCIE_PHY_COM_NOCSR_BCR>; + reset-names = "phy", "common", "cfg"; + + pciephy_0: lane@35000 { + reg = <0x35000 0x130>, + <0x35200 0x200>, + <0x35400 0x1dc>; + #phy-cells = <0>; + + clocks = <&gcc GCC_PCIE_0_PIPE_CLK>; + clock-names = "pipe0"; + resets = <&gcc GCC_PCIE_0_PHY_BCR>; + reset-names = "lane0"; + }; + + pciephy_1: lane@36000 { + ... + ... + }; diff --git a/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt b/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt new file mode 100644 index 000000000000..aa0fcb05acb3 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt @@ -0,0 +1,43 @@ +Qualcomm QUSB2 phy controller +============================= + +QUSB2 controller supports LS/FS/HS usb connectivity on Qualcomm chipsets. + +Required properties: + - compatible: compatible list, contains "qcom,msm8996-qusb2-phy". + - reg: offset and length of the PHY register set. + - #phy-cells: must be 0. + + - clocks: a list of phandles and clock-specifier pairs, + one for each entry in clock-names. + - clock-names: must be "cfg_ahb" for phy config clock, + "ref" for 19.2 MHz ref clk, + "iface" for phy interface clock (Optional). + + - vdda-pll-supply: Phandle to 1.8V regulator supply to PHY refclk pll block. + - vdda-phy-dpdm-supply: Phandle to 3.1V regulator supply to Dp/Dm port signals. + + - resets: Phandle to reset to phy block. + +Optional properties: + - nvmem-cells: Phandle to nvmem cell that contains 'HS Tx trim' + tuning parameter value for qusb2 phy. + + - qcom,tcsr-syscon: Phandle to TCSR syscon register region. + +Example: + hsusb_phy: phy@7411000 { + compatible = "qcom,msm8996-qusb2-phy"; + reg = <0x7411000 0x180>; + #phy-cells = <0>; + + clocks = <&gcc GCC_USB_PHY_CFG_AHB2PHY_CLK>, + <&gcc GCC_RX1_USB2_CLKREF_CLK>, + clock-names = "cfg_ahb", "ref"; + + vdda-pll-supply = <&pm8994_l12>; + vdda-phy-dpdm-supply = <&pm8994_l24>; + + resets = <&gcc GCC_QUSB2PHY_PRIM_BCR>; + nvmem-cells = <&qusb2p_hstx_trim>; + }; diff --git a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt index 57dc388e2fa2..4ed569046daf 100644 --- a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt @@ -30,6 +30,7 @@ Optional Properties: - reset-names: Only allow the following entries: - phy-reset - resets: Must contain an entry for each entry in reset-names. +- vbus-supply: power-supply phandle for vbus power source Example: diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt index e42334258185..005bc22938ff 100644 --- a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt @@ -15,6 +15,7 @@ Required properties: - reg : a list of offset + length pairs - reg-names : * "phy_ctrl" + * "pmu0" for H3, V3s and A64 * "pmu1" * "pmu2" for sun4i, sun6i or sun7i - #phy-cells : from the generic phy bindings, must be 1 diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index 2fd688c8dbdb..b53224473672 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -23,7 +23,8 @@ Required properties: "allwinner,sun8i-h3-pinctrl" "allwinner,sun8i-h3-r-pinctrl" "allwinner,sun50i-a64-pinctrl" - "allwinner,sun50i-h5-r-pinctrl" + "allwinner,sun50i-a64-r-pinctrl" + "allwinner,sun50i-h5-pinctrl" "nextthing,gr8-pinctrl" - reg: Should contain the register physical address and length for the diff --git a/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt index 9a8a45d9d8ab..590e60378be3 100644 --- a/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/atmel,at91-pinctrl.txt @@ -4,7 +4,7 @@ The AT91 Pinmux Controller, enables the IC to share one PAD to several functional blocks. The sharing is done by multiplexing the PAD input/output signals. For each PAD there are up to 8 muxing options (called periph modes). Since different modules require -different PAD settings (like pull up, keeper, etc) the contoller controls +different PAD settings (like pull up, keeper, etc) the controller controls also the PAD settings parameters. Please refer to pinctrl-bindings.txt in this directory for details of the diff --git a/Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt new file mode 100644 index 000000000000..47284f85ec80 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/axis,artpec6-pinctrl.txt @@ -0,0 +1,85 @@ +Axis ARTPEC-6 Pin Controller + +Required properties: +- compatible: "axis,artpec6-pinctrl". +- reg: Should contain the register physical address and length for the pin + controller. + +A pinctrl node should contain at least one subnode representing the pinctrl +groups available on the machine. Each subnode will list the mux function +required and what pin group it will use. Each subnode will also configure the +drive strength and bias pullup of the pin group. If either of these options is +not set, its actual value will be unspecified. + + +Required subnode-properties: +- function: Function to mux. +- groups: Name of the pin group to use for the function above. + + Available functions and groups (function: group0, group1...): + gpio: cpuclkoutgrp0, udlclkoutgrp0, i2c1grp0, i2c2grp0, + i2c3grp0, i2s0grp0, i2s1grp0, i2srefclkgrp0, spi0grp0, + spi1grp0, pciedebuggrp0, uart0grp0, uart0grp1, uart1grp0, + uart2grp0, uart2grp1, uart3grp0, uart4grp0, uart5grp0 + cpuclkout: cpuclkoutgrp0 + udlclkout: udlclkoutgrp0 + i2c1: i2c1grp0 + i2c2: i2c2grp0 + i2c3: i2c3grp0 + i2s0: i2s0grp0 + i2s1: i2s1grp0 + i2srefclk: i2srefclkgrp0 + spi0: spi0grp0 + spi1: spi1grp0 + pciedebug: pciedebuggrp0 + uart0: uart0grp0, uart0grp1 + uart1: uart1grp0 + uart2: uart2grp0, uart2grp1 + uart3: uart3grp0 + uart4: uart4grp0 + uart5: uart5grp0 + nand: nandgrp0 + sdio0: sdio0grp0 + sdio1: sdio1grp0 + ethernet: ethernetgrp0 + + +Optional subnode-properties (see pinctrl-bindings.txt): +- drive-strength: 4, 6, 8, 9 mA. For SD and NAND pins, this is for 3.3V VCCQ3. +- bias-pull-up +- bias-disable + +Examples: +pinctrl@f801d000 { + compatible = "axis,artpec6-pinctrl"; + reg = <0xf801d000 0x400>; + + pinctrl_uart0: uart0grp { + function = "uart0"; + groups = "uart0grp0"; + drive-strength = <4>; + bias-pull-up; + }; + pinctrl_uart3: uart3grp { + function = "uart3"; + groups = "uart3grp0"; + }; +}; +uart0: uart@f8036000 { + compatible = "arm,pl011", "arm,primecell"; + reg = <0xf8036000 0x1000>; + interrupts = <0 104 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&pll2div24>, <&apb_pclk>; + clock-names = "uart_clk", "apb_pclk"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_uart0>; +}; +uart3: uart@f8039000 { + compatible = "arm,pl011", "arm,primecell"; + reg = <0xf8039000 0x1000>; + interrupts = <0 128 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&pll2div24>, <&apb_pclk>; + clock-names = "uart_clk", "apb_pclk"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_uart3>; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt new file mode 100644 index 000000000000..f64060908d5a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/marvell,armada-37xx-pinctrl.txt @@ -0,0 +1,183 @@ +* Marvell Armada 37xx SoC pin and gpio controller + +Each Armada 37xx SoC come with two pin and gpio controller one for the +south bridge and the other for the north bridge. + +Inside this set of register the gpio latch allows exposing some +configuration of the SoC and especially the clock frequency of the +xtal. Hence, this node is a represent as syscon allowing sharing the +register between multiple hardware block. + +GPIO and pin controller: +------------------------ + +Main node: + +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". + +Required properties for pinctrl driver: + +- compatible: "marvell,armada3710-sb-pinctrl", "syscon, "simple-mfd" + for the south bridge + "marvell,armada3710-nb-pinctrl", "syscon, "simple-mfd" + for the north bridge +- reg: The first set of register are for pinctrl/gpio and the second + set for the interrupt controller +- interrupts: list of the interrupt use by the gpio + +Available groups and functions for the North bridge: + +group: jtag + - pins 20-24 + - functions jtag, gpio + +group sdio0 + - pins 8-10 + - functions sdio, gpio + +group emmc_nb + - pins 27-35 + - functions emmc, gpio + +group pwm0 + - pin 11 (GPIO1-11) + - functions pwm, gpio + +group pwm1 + - pin 12 + - functions pwm, gpio + +group pwm2 + - pin 13 + - functions pwm, gpio + +group pwm3 + - pin 14 + - functions pwm, gpio + +group pmic1 + - pin 17 + - functions pmic, gpio + +group pmic0 + - pin 16 + - functions pmic, gpio + +group i2c2 + - pins 2-3 + - functions i2c, gpio + +group i2c1 + - pins 0-1 + - functions i2c, gpio + +group spi_cs1 + - pin 17 + - functions spi, gpio + +group spi_cs2 + - pin 18 + - functions spi, gpio + +group spi_cs3 + - pin 19 + - functions spi, gpio + +group onewire + - pin 4 + - functions onewire, gpio + +group uart1 + - pins 25-26 + - functions uart, gpio + +group spi_quad + - pins 15-16 + - functions spi, gpio + +group uart_2 + - pins 9-10 + - functions uart, gpio + +Available groups and functions for the South bridge: + +group usb32_drvvbus0 + - pin 36 + - functions drvbus, gpio + +group usb2_drvvbus1 + - pin 37 + - functions drvbus, gpio + +group sdio_sb + - pins 60-64 + - functions sdio, gpio + +group rgmii + - pins 42-55 + - functions mii, gpio + +group pcie1 + - pins 39-40 + - functions pcie, gpio + +group ptp + - pins 56-58 + - functions ptp, gpio + +group ptp_clk + - pin 57 + - functions ptp, mii + +group ptp_trig + - pin 58 + - functions ptp, mii + +group mii_col + - pin 59 + - functions mii, mii_err + +GPIO subnode: + +Please refer to gpio.txt in this directory for details of gpio-ranges property +and the common GPIO bindings used by client devices. + +Required properties for gpio driver under the gpio subnode: +- interrupts: List of interrupt specifier for the controllers interrupt. +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Should be 2. The first cell is the GPIO number and the + second cell specifies GPIO flags, as defined in + <dt-bindings/gpio/gpio.h>. Only the GPIO_ACTIVE_HIGH and + GPIO_ACTIVE_LOW flags are supported. +- gpio-ranges: Range of pins managed by the GPIO controller. + +Xtal Clock bindings for Marvell Armada 37xx SoCs +------------------------------------------------ + +see Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt + + +Example: +pinctrl_sb: pinctrl-sb@18800 { + compatible = "marvell,armada3710-sb-pinctrl", "syscon", "simple-mfd"; + reg = <0x18800 0x100>, <0x18C00 0x20>; + gpio { + #gpio-cells = <2>; + gpio-ranges = <&pinctrl_sb 0 0 29>; + gpio-controller; + interrupts = + <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 159 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 158 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 157 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 156 IRQ_TYPE_LEVEL_HIGH>; + }; + + rgmii_pins: mii-pins { + groups = "rgmii"; + function = "mii"; + }; + +}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt index b98e6f030da8..ca01710ee29a 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt @@ -34,13 +34,28 @@ Documentation/devicetree/bindings/mfd/syscon.txt Subnode Format ============== -The required properties of child nodes are (as defined in pinctrl-bindings): -- function -- groups +The required properties of pinmux child nodes are: +- function: the mux function to select +- groups : the list of groups to select with this function -Each 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: +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: @@ -90,6 +105,11 @@ syscon: scu@1e6e2000 { function = "I2C3"; groups = "I2C3"; }; + + pinctrl_gpioh0_unbiased_default: gpioh0 { + pins = "A8"; + bias-disable; + }; }; }; @@ -110,6 +130,11 @@ ahb { function = "I2C3"; groups = "I2C3"; }; + + pinctrl_gpioh0_unbiased_default: gpioh0 { + pins = "A18"; + bias-disable; + }; }; }; @@ -143,6 +168,3 @@ ahb { }; }; }; - -Please refer to pinctrl-bindings.txt in this directory for details of the -common pinctrl bindings used by client devices. diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt index bf3f7b014724..71a3c134af1b 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt @@ -162,8 +162,8 @@ state_2_node_a { pins = "mfio29", "mfio30"; }; -Optionally an altenative binding can be used if more suitable depending on the -pin controller hardware. For hardaware where there is a large number of identical +Optionally an alternative binding can be used if more suitable depending on the +pin controller hardware. For hardware where there is a large number of identical pin controller instances, naming each pin and function can easily become unmaintainable. This is especially the case if the same controller is used for different pins and functions depending on the SoC revision and packaging. @@ -198,6 +198,28 @@ registers, and must not be a virtual index of pin instances. The reason for this is to avoid mapping of the index in the dts files and the pin controller driver as it can change. +For hardware where pin multiplexing configurations have to be specified for +each single pin the number of required sub-nodes containing "pin" and +"function" properties can quickly escalate and become hard to write and +maintain. + +For cases like this, the pin controller driver may use the pinmux helper +property, where the pin identifier is packed with mux configuration settings +in a single integer. + +The pinmux property accepts an array of integers, each of them describing +a single pin multiplexing configuration. + +pincontroller { + state_0_node_a { + pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ...; + }; +}; + +Each individual pin controller driver bindings documentation shall specify +how those values (pin IDs and pin multiplexing configuration) are defined and +assembled together. + == Generic pin configuration node content == Many data items that are represented in a pin configuration node are common @@ -210,18 +232,22 @@ structure of the DT nodes that contain these properties. Supported generic properties are: pins - the list of pins that properties in the node - apply to (either this or "group" has to be + apply to (either this, "group" or "pinmux" has to be specified) group - the group to apply the properties to, if the driver supports configuration of whole groups rather than - individual pins (either this or "pins" has to be - specified) + individual pins (either this, "pins" or "pinmux" has + to be specified) +pinmux - the list of numeric pin ids and their mux settings + that properties in the node apply to (either this, + "pins" or "groups" have to be specified) bias-disable - disable any pin bias bias-high-impedance - high impedance mode ("third-state", "floating") bias-bus-hold - latch weakly bias-pull-up - pull up the pin bias-pull-down - pull down the pin bias-pull-pin-default - use pin-default pull state +bi-directional - pin supports simultaneous input/output operations drive-push-pull - drive actively high and low drive-open-drain - drive with open drain drive-open-source - drive with open source @@ -234,6 +260,7 @@ input-debounce - debounce mode with debound time X power-source - select between different power supplies low-power-enable - enable low power mode low-power-disable - disable low power mode +output-enable - enable output on pin regardless of output value output-low - set the pin to output mode with low level output-high - set the pin to output mode with high level slew-rate - set the slew rate @@ -258,6 +285,12 @@ state_2_node_a { bias-pull-up; }; }; +state_3_node_a { + mux { + pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>; + input-enable; + }; +}; Some of the generic properties take arguments. For those that do, the arguments are described below. @@ -266,6 +299,11 @@ arguments are described below. binding for the hardware defines: - Whether the entries are integers or strings, and their meaning. +- pinmux takes a list of pin IDs and mux settings as required argument. The + specific bindings for the hardware defines: + - How pin IDs and mux settings are defined and assembled together in a single + integer. + - bias-pull-up, -down and -pin-default take as optional argument on hardware supporting it the pull strength in Ohm. bias-disable will disable the pull. diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt index 4722bc61a1a2..ee01ab58224d 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt @@ -19,11 +19,18 @@ The pins are grouped into up to 5 individual pin banks which need to be defined as gpio sub-nodes of the pinmux controller. Required properties for iomux controller: - - compatible: one of "rockchip,rk1108-pinctrl", "rockchip,rk2928-pinctrl" - "rockchip,rk3066a-pinctrl", "rockchip,rk3066b-pinctrl" - "rockchip,rk3188-pinctrl", "rockchip,rk3228-pinctrl" - "rockchip,rk3288-pinctrl", "rockchip,rk3368-pinctrl" - "rockchip,rk3399-pinctrl" + - compatible: should be + "rockchip,rv1108-pinctrl": for Rockchip RV1108 + "rockchip,rk2928-pinctrl": for Rockchip RK2928 + "rockchip,rk3066a-pinctrl": for Rockchip RK3066a + "rockchip,rk3066b-pinctrl": for Rockchip RK3066b + "rockchip,rk3188-pinctrl": for Rockchip RK3188 + "rockchip,rk3228-pinctrl": for Rockchip RK3228 + "rockchip,rk3288-pinctrl": for Rockchip RK3288 + "rockchip,rk3328-pinctrl": for Rockchip RK3328 + "rockchip,rk3368-pinctrl": for Rockchip RK3368 + "rockchip,rk3399-pinctrl": for Rockchip RK3399 + - rockchip,grf: phandle referencing a syscon providing the "general register files" diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt index eac20aa33907..d907a74f8dc0 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -9,6 +9,7 @@ Pin controller node: Required properies: - compatible: value should be one of the following: "st,stm32f429-pinctrl" + "st,stm32f469-pinctrl" "st,stm32f746-pinctrl" "st,stm32h743-pinctrl" - #address-cells: The value of this property must be 1 @@ -38,8 +39,6 @@ Optional properties: - st,syscfg: Should be phandle/offset pair. The phandle to the syscon node which includes IRQ mux selection register, and the offset of the IRQ mux selection register. - - ngpios: Number of gpios in a bank (to use if bank gpio numbers is less - than 16). - 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. diff --git a/Documentation/devicetree/bindings/power/power_domain.txt b/Documentation/devicetree/bindings/power/power_domain.txt index 723e1ad937da..940707d095cc 100644 --- a/Documentation/devicetree/bindings/power/power_domain.txt +++ b/Documentation/devicetree/bindings/power/power_domain.txt @@ -31,7 +31,9 @@ Optional properties: - domain-idle-states : A phandle of an idle-state that shall be soaked into a generic domain power state. The idle state definitions are - compatible with domain-idle-state specified in [1]. + compatible with domain-idle-state specified in [1]. phandles + that are not compatible with domain-idle-state will be + ignored. The domain-idle-state property reflects the idle state of this PM domain and not the idle states of the devices or sub-domains in the PM domain. Devices and sub-domains have their own idle-states independent of the parent diff --git a/Documentation/devicetree/bindings/power/reset/gemini-poweroff.txt b/Documentation/devicetree/bindings/power/reset/gemini-poweroff.txt new file mode 100644 index 000000000000..7fec3e100214 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/gemini-poweroff.txt @@ -0,0 +1,17 @@ +* Device-Tree bindings for Cortina Systems Gemini Poweroff + +This is a special IP block in the Cortina Gemini SoC that only +deals with different ways to power the system down. + +Required properties: +- compatible: should be "cortina,gemini-power-controller" +- reg: should contain the physical memory base and size +- interrupts: should contain the power management interrupt + +Example: + +power-controller@4b000000 { + compatible = "cortina,gemini-power-controller"; + reg = <0x4b000000 0x100>; + interrupts = <26 IRQ_TYPE_EDGE_FALLING>; +}; diff --git a/Documentation/devicetree/bindings/power/reset/syscon-poweroff.txt b/Documentation/devicetree/bindings/power/reset/syscon-poweroff.txt index 1e2546f8b08a..022ed1f3bc80 100644 --- a/Documentation/devicetree/bindings/power/reset/syscon-poweroff.txt +++ b/Documentation/devicetree/bindings/power/reset/syscon-poweroff.txt @@ -3,13 +3,20 @@ Generic SYSCON mapped register poweroff driver This is a generic poweroff driver using syscon to map the poweroff register. The poweroff is generally performed with a write to the poweroff register defined by the register map pointed by syscon reference plus the offset -with the mask defined in the poweroff node. +with the value and mask defined in the poweroff node. Required properties: - compatible: should contain "syscon-poweroff" - regmap: this is phandle to the register map node - offset: offset in the register map for the poweroff register (in bytes) -- mask: the poweroff value written to the poweroff register (32 bit access) +- value: the poweroff value written to the poweroff register (32 bit access) + +Optional properties: +- mask: update only the register bits defined by the mask (32 bit) + +Legacy usage: +If a node doesn't contain a value property but contains a mask property, the +mask property is used as the value. Default will be little endian mode, 32 bit access only. diff --git a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt index d23dc002a87e..d3a5a93a65cd 100644 --- a/Documentation/devicetree/bindings/power/rockchip-io-domain.txt +++ b/Documentation/devicetree/bindings/power/rockchip-io-domain.txt @@ -33,6 +33,7 @@ Required properties: - compatible: should be one of: - "rockchip,rk3188-io-voltage-domain" for rk3188 - "rockchip,rk3288-io-voltage-domain" for rk3288 + - "rockchip,rk3328-io-voltage-domain" for rk3328 - "rockchip,rk3368-io-voltage-domain" for rk3368 - "rockchip,rk3368-pmu-io-voltage-domain" for rk3368 pmu-domains - "rockchip,rk3399-io-voltage-domain" for rk3399 diff --git a/Documentation/devicetree/bindings/power/supply/cpcap-charger.txt b/Documentation/devicetree/bindings/power/supply/cpcap-charger.txt new file mode 100644 index 000000000000..80bd873c3b1d --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/cpcap-charger.txt @@ -0,0 +1,37 @@ +Motorola CPCAP PMIC battery charger binding + +Required properties: +- compatible: Shall be "motorola,mapphone-cpcap-charger" +- interrupts: Interrupt specifier for each name in interrupt-names +- interrupt-names: Should contain the following entries: + "chrg_det", "rvrs_chrg", "chrg_se1b", "se0conn", + "rvrs_mode", "chrgcurr1", "vbusvld", "battdetb" +- io-channels: IIO ADC channel specifier for each name in io-channel-names +- io-channel-names: Should contain the following entries: + "battdetb", "battp", "vbus", "chg_isense", "batti" + +Optional properties: +- mode-gpios: Optionally CPCAP charger can have a companion wireless + charge controller that is controlled with two GPIOs + that are active low. + +Example: + +cpcap_charger: charger { + compatible = "motorola,mapphone-cpcap-charger"; + interrupts-extended = < + &cpcap 13 0 &cpcap 12 0 &cpcap 29 0 &cpcap 28 0 + &cpcap 22 0 &cpcap 20 0 &cpcap 19 0 &cpcap 54 0 + >; + interrupt-names = + "chrg_det", "rvrs_chrg", "chrg_se1b", "se0conn", + "rvrs_mode", "chrgcurr1", "vbusvld", "battdetb"; + mode-gpios = <&gpio3 29 GPIO_ACTIVE_LOW + &gpio3 23 GPIO_ACTIVE_LOW>; + io-channels = <&cpcap_adc 0 &cpcap_adc 1 + &cpcap_adc 2 &cpcap_adc 5 + &cpcap_adc 6>; + io-channel-names = "battdetb", "battp", + "vbus", "chg_isense", + "batti"; +}; diff --git a/Documentation/devicetree/bindings/power/supply/lego_ev3_battery.txt b/Documentation/devicetree/bindings/power/supply/lego_ev3_battery.txt new file mode 100644 index 000000000000..5485633b1faa --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/lego_ev3_battery.txt @@ -0,0 +1,21 @@ +LEGO MINDSTORMS EV3 Battery +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +LEGO MINDSTORMS EV3 has some built-in capability for monitoring the battery. +It uses 6 AA batteries or a special Li-ion rechargeable battery pack that is +detected by a key switch in the battery compartment. + +Required properties: + - compatible: Must be "lego,ev3-battery" + - io-channels: phandles to analog inputs for reading voltage and current + - io-channel-names: Must be "voltage", "current" + - rechargeable-gpios: phandle to the rechargeable battery indication gpio + +Example: + + battery { + compatible = "lego,ev3-battery"; + io-channels = <&adc 4>, <&adc 3>; + io-channel-names = "voltage", "current"; + rechargeable-gpios = <&gpio 136 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/ltc2941.txt b/Documentation/devicetree/bindings/power/supply/ltc2941.txt index ea42ae12d924..a9d7aa60558b 100644 --- a/Documentation/devicetree/bindings/power/supply/ltc2941.txt +++ b/Documentation/devicetree/bindings/power/supply/ltc2941.txt @@ -6,8 +6,8 @@ temperature monitoring, and uses a slightly different conversion formula for the charge counter. Required properties: -- compatible: Should contain "ltc2941" or "ltc2943" which also indicates the - type of I2C chip attached. +- compatible: Should contain "lltc,ltc2941" or "lltc,ltc2943" which also + indicates the type of I2C chip attached. - reg: The 7-bit I2C address. - lltc,resistor-sense: The sense resistor value in milli-ohms. Can be a 32-bit negative value when the battery has been connected to the wrong end of the @@ -20,7 +20,7 @@ Required properties: Example from the Topic Miami Florida board: fuelgauge: ltc2943@64 { - compatible = "ltc2943"; + compatible = "lltc,ltc2943"; reg = <0x64>; lltc,resistor-sense = <15>; lltc,prescaler-exponent = <5>; /* 2^(2*5) = 1024 */ diff --git a/Documentation/devicetree/bindings/power/supply/max8925_batter.txt b/Documentation/devicetree/bindings/power/supply/max8925_battery.txt index d7e3e0c0f71d..d7e3e0c0f71d 100644 --- a/Documentation/devicetree/bindings/power/supply/max8925_batter.txt +++ b/Documentation/devicetree/bindings/power/supply/max8925_battery.txt diff --git a/Documentation/devicetree/bindings/powerpc/4xx/emac.txt b/Documentation/devicetree/bindings/powerpc/4xx/emac.txt index 712baf6c3e24..44b842b6ca15 100644 --- a/Documentation/devicetree/bindings/powerpc/4xx/emac.txt +++ b/Documentation/devicetree/bindings/powerpc/4xx/emac.txt @@ -71,6 +71,9 @@ For Axon it can be absent, though my current driver doesn't handle phy-address yet so for now, keep 0x00ffffff in it. + - phy-handle : Used to describe configurations where a external PHY + is used. Please refer to: + Documentation/devicetree/bindings/net/ethernet.txt - rx-fifo-size-gige : 1 cell, Rx fifo size in bytes for 1000 Mb/sec operations (if absent the value is the same as rx-fifo-size). For Axon, either absent or 2048. @@ -81,8 +84,22 @@ offload, phandle of the TAH device node. - tah-channel : 1 cell, optional. If appropriate, channel used on the TAH engine. + - fixed-link : Fixed-link subnode describing a link to a non-MDIO + managed entity. See + Documentation/devicetree/bindings/net/fixed-link.txt + for details. + - mdio subnode : When the EMAC has a phy connected to its local + mdio, which us supported by the kernel's network + PHY library in drivers/net/phy, there must be device + tree subnode with the following required properties: + - #address-cells: Must be <1>. + - #size-cells: Must be <0>. - Example: + For PHY definitions: Please refer to + Documentation/devicetree/bindings/net/phy.txt and + Documentation/devicetree/bindings/net/ethernet.txt + + Examples: EMAC0: ethernet@40000800 { device_type = "network"; @@ -104,6 +121,48 @@ zmii-channel = <0>; }; + EMAC1: ethernet@ef600c00 { + device_type = "network"; + compatible = "ibm,emac-apm821xx", "ibm,emac4sync"; + interrupt-parent = <&EMAC1>; + interrupts = <0 1>; + #interrupt-cells = <1>; + #address-cells = <0>; + #size-cells = <0>; + interrupt-map = <0 &UIC2 0x10 IRQ_TYPE_LEVEL_HIGH /* Status */ + 1 &UIC2 0x14 IRQ_TYPE_LEVEL_HIGH /* Wake */>; + reg = <0xef600c00 0x000000c4>; + local-mac-address = [000000000000]; /* Filled in by U-Boot */ + mal-device = <&MAL0>; + mal-tx-channel = <0>; + mal-rx-channel = <0>; + cell-index = <0>; + max-frame-size = <9000>; + rx-fifo-size = <16384>; + tx-fifo-size = <2048>; + fifo-entry-size = <10>; + phy-mode = "rgmii"; + phy-handle = <&phy0>; + phy-map = <0x00000000>; + rgmii-device = <&RGMII0>; + rgmii-channel = <0>; + tah-device = <&TAH0>; + tah-channel = <0>; + has-inverted-stacr-oc; + has-new-stacr-staopc; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + phy0: ethernet-phy@0 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <0>; + }; + }; + }; + + ii) McMAL node Required properties: @@ -145,4 +204,3 @@ - revision : as provided by the RGMII new version register if available. For Axon: 0x0000012a - diff --git a/Documentation/devicetree/bindings/regulator/anatop-regulator.txt b/Documentation/devicetree/bindings/regulator/anatop-regulator.txt index 1d58c8cfdbc0..a3106c72fbea 100644 --- a/Documentation/devicetree/bindings/regulator/anatop-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/anatop-regulator.txt @@ -2,6 +2,7 @@ Anatop Voltage regulators Required properties: - compatible: Must be "fsl,anatop-regulator" +- regulator-name: A string used as a descriptive name for regulator outputs - anatop-reg-offset: Anatop MFD register offset - anatop-vol-bit-shift: Bit shift for the register - anatop-vol-bit-width: Number of bits used in the register diff --git a/Documentation/devicetree/bindings/regulator/lm363x-regulator.txt b/Documentation/devicetree/bindings/regulator/lm363x-regulator.txt index 8f14df9d1205..cc5a6151d85f 100644 --- a/Documentation/devicetree/bindings/regulator/lm363x-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/lm363x-regulator.txt @@ -8,8 +8,8 @@ Required property: Optional properties: LM3632 has external enable pins for two LDOs. - - ti,lcm-en1-gpio: A GPIO specifier for Vpos control pin. - - ti,lcm-en2-gpio: A GPIO specifier for Vneg control pin. + - enable-gpios: Two GPIO specifiers for Vpos and Vneg control pins. + The first entry is Vpos, the second is Vneg enable pin. Child nodes: LM3631 @@ -30,5 +30,79 @@ Child nodes: Examples: Please refer to ti-lmu dt-bindings [2]. +lm3631@29 { + compatible = "ti,lm3631"; + reg = <0x29>; + + regulators { + compatible = "ti,lm363x-regulator"; + + vboost { + regulator-name = "lcd_boost"; + regulator-min-microvolt = <4500000>; + regulator-max-microvolt = <6350000>; + regulator-always-on; + }; + + vcont { + regulator-name = "lcd_vcont"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + }; + + voref { + regulator-name = "lcd_voref"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + }; + + vpos { + regulator-name = "lcd_vpos"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + regulator-boot-on; + }; + + vneg { + regulator-name = "lcd_vneg"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + regulator-boot-on; + }; + }; +}; + +lm3632@11 { + compatible = "ti,lm3632"; + reg = <0x11>; + + regulators { + compatible = "ti,lm363x-regulator"; + + /* GPIO1_16 for Vpos, GPIO1_28 is for Vneg */ + enable-gpios = <&gpio1 16 GPIO_ACTIVE_HIGH>, + <&gpio1 28 GPIO_ACTIVE_HIGH>; + + vboost { + regulator-name = "lcd_boost"; + regulator-min-microvolt = <4500000>; + regulator-max-microvolt = <6400000>; + regulator-always-on; + }; + + vpos { + regulator-name = "lcd_vpos"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + }; + + vneg { + regulator-name = "lcd_vneg"; + regulator-min-microvolt = <4000000>; + regulator-max-microvolt = <6000000>; + }; + }; +}; + [1] ../regulator/regulator.txt [2] ../mfd/ti-lmu.txt diff --git a/Documentation/devicetree/bindings/regulator/pfuze100.txt b/Documentation/devicetree/bindings/regulator/pfuze100.txt index 9b40db88f637..444c47831a40 100644 --- a/Documentation/devicetree/bindings/regulator/pfuze100.txt +++ b/Documentation/devicetree/bindings/regulator/pfuze100.txt @@ -13,7 +13,7 @@ Required child node: --PFUZE100 sw1ab,sw1c,sw2,sw3a,sw3b,sw4,swbst,vsnvs,vrefddr,vgen1~vgen6 --PFUZE200 - sw1ab,sw2,sw3a,sw3b,swbst,vsnvs,vrefddr,vgen1~vgen6 + sw1ab,sw2,sw3a,sw3b,swbst,vsnvs,vrefddr,vgen1~vgen6,coin --PFUZE3000 sw1a,sw1b,sw2,sw3,swbst,vsnvs,vrefddr,vldo1,vldo2,vccsd,v33,vldo3,vldo4 @@ -205,6 +205,12 @@ Example 2: PFUZE200 regulator-max-microvolt = <3300000>; regulator-always-on; }; + + coin_reg: coin { + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; }; }; diff --git a/Documentation/devicetree/bindings/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index 6ab5aef619d9..d18edb075e1c 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -21,6 +21,9 @@ Optional properties: design requires. This property describes the total system ramp time required due to the combination of internal ramping of the regulator itself, and board design issues such as trace capacitance and load on the supply. +- regulator-settling-time-us: Settling time, in microseconds, for voltage + change if regulator have the constant time for any level voltage change. + This is useful when regulator have exponential voltage change. - regulator-soft-start: Enable soft start so that voltage ramps slowly - regulator-state-mem sub-root node for Suspend-to-RAM mode : suspend to memory, the device goes to sleep, but all data stored in memory, diff --git a/Documentation/devicetree/bindings/regulator/tps65132-regulator.txt b/Documentation/devicetree/bindings/regulator/tps65132-regulator.txt new file mode 100644 index 000000000000..3a3505520c69 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/tps65132-regulator.txt @@ -0,0 +1,46 @@ +TPS65132 regulators + +Required properties: +- compatible: "ti,tps65132" +- reg: I2C slave address + +Optional Subnode: +Device supports two regulators OUTP and OUTN. A sub node within the + device node describe the properties of these regulators. The sub-node + names must be as follows: + -For regulator outp, the sub node name should be "outp". + -For regulator outn, the sub node name should be "outn". + +-enable-gpios:(active high, output) Regulators are controlled by the input pins. + If it is connected to GPIO through host system then provide the + gpio number as per gpio.txt. +-active-discharge-gpios: (active high, output) Some configurations use delay mechanisms + on the enable pin, to keep the regulator enabled for some time after + the enable signal goes low. This GPIO is used to actively discharge + the delay mechanism. Requires specification of ti,active-discharge-time-us +-ti,active-discharge-time-us: how long the active discharge gpio should be + asserted for during active discharge, in microseconds. + +Each regulator is defined using the standard binding for regulators. + +Example: + + tps65132@3e { + compatible = "ti,tps65132"; + reg = <0x3e>; + + outp { + regulator-name = "outp"; + regulator-boot-on; + regulator-always-on; + enable-gpios = <&gpio 23 0>; + }; + + outn { + regulator-name = "outn"; + regulator-boot-on; + regulator-always-on; + regulator-active-discharge = <0>; + enable-gpios = <&gpio 40 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/vctrl.txt b/Documentation/devicetree/bindings/regulator/vctrl.txt new file mode 100644 index 000000000000..601328d7fdbb --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/vctrl.txt @@ -0,0 +1,49 @@ +Bindings for Voltage controlled regulators +========================================== + +Required properties: +-------------------- +- compatible : must be "vctrl-regulator". +- regulator-min-microvolt : smallest voltage consumers may set +- regulator-max-microvolt : largest voltage consumers may set +- ctrl-supply : The regulator supplying the control voltage. +- ctrl-voltage-range : an array of two integer values describing the range + (min/max) of the control voltage. The values specify + the control voltage needed to generate the corresponding + regulator-min/max-microvolt output voltage. + +Optional properties: +-------------------- +- ovp-threshold-percent : overvoltage protection (OVP) threshold of the + regulator in percent. Some regulators have an OVP + circuitry which shuts down the regulator when the + actual output voltage deviates beyond a certain + margin from the expected value for a given control + voltage. On larger voltage decreases this can occur + undesiredly since the output voltage does not adjust + inmediately to changes in the control voltage. To + avoid this situation the vctrl driver breaks down + larger voltage decreases into multiple steps, where + each step is within the OVP threshold. +- min-slew-down-rate : Describes how slowly the regulator voltage will decay + down in the worst case (lightest expected load). + Specified in uV / us (like main regulator ramp rate). + This value is required when ovp-threshold-percent is + specified. + +Example: + + vctrl-reg { + compatible = "vctrl-regulator"; + regulator-name = "vctrl_reg"; + + ctrl-supply = <&ctrl_reg>; + + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1500000>; + + ctrl-voltage-range = <200000 500000>; + + min-slew-down-rate = <225>; + ovp-threshold-percent = <16>; + }; diff --git a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.txt b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.txt index 202f2d09a23f..4d403645ac9b 100644 --- a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.txt +++ b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.txt @@ -6,9 +6,16 @@ Required properties: - compatible : should be "amlogic,meson-rng" - reg : Specifies base physical address and size of the registers. +Optional properties: + +- clocks : phandle to the following named clocks +- clock-names: Name of core clock, must be "core" + Example: rng { - compatible = "amlogic,meson-rng"; - reg = <0x0 0xc8834000 0x0 0x4>; + compatible = "amlogic,meson-rng"; + reg = <0x0 0xc8834000 0x0 0x4>; + clocks = <&clkc CLKID_RNG0>; + clock-names = "core"; }; diff --git a/Documentation/devicetree/bindings/rng/mtk-rng.txt b/Documentation/devicetree/bindings/rng/mtk-rng.txt new file mode 100644 index 000000000000..a6d62a2abd39 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/mtk-rng.txt @@ -0,0 +1,18 @@ +Device-Tree bindings for Mediatek random number generator +found in Mediatek SoC family + +Required properties: +- compatible : Should be "mediatek,mt7623-rng" +- clocks : list of clock specifiers, corresponding to + entries in clock-names property; +- clock-names : Should contain "rng" entries; +- reg : Specifies base physical address and size of the registers + +Example: + +rng: rng@1020f000 { + compatible = "mediatek,mt7623-rng"; + reg = <0 0x1020f000 0 0x1000>; + clocks = <&infracfg CLK_INFRA_TRNG>; + clock-names = "rng"; +}; diff --git a/Documentation/devicetree/bindings/rng/omap_rng.txt b/Documentation/devicetree/bindings/rng/omap_rng.txt index 471477299ece..9cf7876ab434 100644 --- a/Documentation/devicetree/bindings/rng/omap_rng.txt +++ b/Documentation/devicetree/bindings/rng/omap_rng.txt @@ -12,7 +12,8 @@ Required properties: - reg : Offset and length of the register set for the module - interrupts : the interrupt number for the RNG module. Used for "ti,omap4-rng" and "inside-secure,safexcel-eip76" -- clocks: the trng clock source +- clocks: the trng clock source. Only mandatory for the + "inside-secure,safexcel-eip76" compatible. Example: /* AM335x */ diff --git a/Documentation/devicetree/bindings/serial/sprd-uart.txt b/Documentation/devicetree/bindings/serial/sprd-uart.txt index 2aff0f22c9fa..cab40f0f6f49 100644 --- a/Documentation/devicetree/bindings/serial/sprd-uart.txt +++ b/Documentation/devicetree/bindings/serial/sprd-uart.txt @@ -1,7 +1,19 @@ * Spreadtrum serial UART Required properties: -- compatible: must be "sprd,sc9836-uart" +- compatible: must be one of: + * "sprd,sc9836-uart" + * "sprd,sc9860-uart", "sprd,sc9836-uart" + - reg: offset and length of the register set for the device - interrupts: exactly one interrupt specifier - clocks: phandles to input clocks. + +Example: + uart0: serial@0 { + compatible = "sprd,sc9860-uart", + "sprd,sc9836-uart"; + reg = <0x0 0x100>; + interrupts = <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ext_26m>; + }; diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.txt b/Documentation/devicetree/bindings/soc/rockchip/grf.txt index a0685c209218..13ec0992de0f 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.txt +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.txt @@ -8,6 +8,8 @@ From RK3368 SoCs, the GRF is divided into two sections, - SGRF, used for general secure system, - PMUGRF, used for always on system +On RK3328 SoCs, the GRF adds a section for USB2PHYGRF, + Required Properties: - compatible: GRF should be one of the following: @@ -23,6 +25,8 @@ Required Properties: - "rockchip,rk3399-pmugrf", "syscon": for rk3399 - compatible: SGRF should be one of the following - "rockchip,rk3288-sgrf", "syscon": for rk3288 +- compatible: USB2PHYGRF should be one of the followings + - "rockchip,rk3328-usb2phy-grf", "syscon": for rk3328 - reg: physical base address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/sound/cs35l35.txt b/Documentation/devicetree/bindings/sound/cs35l35.txt new file mode 100644 index 000000000000..016b768bc722 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cs35l35.txt @@ -0,0 +1,180 @@ +CS35L35 Boosted Speaker Amplifier + +Required properties: + + - compatible : "cirrus,cs35l35" + + - reg : the I2C address of the device for I2C + + - VA-supply, VP-supply : power supplies for the device, + as covered in + Documentation/devicetree/bindings/regulator/regulator.txt. + + - interrupt-parent : Specifies the phandle of the interrupt controller to + which the IRQs from CS35L35 are delivered to. + - interrupts : IRQ line info CS35L35. + (See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + for further information relating to interrupt properties) + +Optional properties: + - reset-gpios : gpio used to reset the amplifier + + - cirrus,stereo-config : Boolean to determine if there are 2 AMPs for a + Stereo configuration + + - cirrus,audio-channel : Set Location of Audio Signal on Serial Port + 0 = Data Packet received on Left I2S Channel + 1 = Data Packet received on Right I2S Channel + + - cirrus,advisory-channel : Set Location of Advisory Signal on Serial Port + 0 = Data Packet received on Left I2S Channel + 1 = Data Packet received on Right I2S Channel + + - cirrus,shared-boost : Boolean to enable ClassH tracking of Advisory Signal + if 2 Devices share Boost BST_CTL + + - cirrus,external-boost : Boolean to specify the device is using an external + boost supply, note that sharing a boost from another cs35l35 would constitute + using an external supply for the slave device + + - cirrus,sp-drv-strength : Value for setting the Serial Port drive strength + Table 3-10 of the datasheet lists drive-strength specifications + 0 = 1x (Default) + 1 = .5x + - cirrus,sp-drv-unused : Determines how unused slots should be driven on the + Serial Port. + 0 - Hi-Z + 2 - Drive 0's (Default) + 3 - Drive 1's + + - cirrus,bst-pdn-fet-on : Boolean to determine if the Boost PDN control + powers down with a rectification FET On or Off. If VSPK is supplied + externally then FET is off. + + - cirrus,boost-ctl-millivolt : Boost Voltage Value. Configures the boost + converter's output voltage in mV. The range is from 2600mV to 9000mV with + increments of 100mV. + (Default) VP + + - cirrus,boost-peak-milliamp : Boost-converter peak current limit in mA. + Configures the peak current by monitoring the current through the boost FET. + Range starts at 1680mA and goes to a maximum of 4480mA with increments of + 110mA. + (Default) 2.46 Amps + + - cirrus,amp-gain-zc : Boolean to determine if to use Amplifier gain-change + zero-cross + +Optional H/G Algorithm sub-node: + + The cs35l35 node can have a single "cirrus,classh-internal-algo" sub-node + that will disable automatic control of the internal H/G Algorithm. + + It is strongly recommended that the Datasheet be referenced when adjusting + or using these Class H Algorithm controls over the internal Algorithm. + Serious damage can occur to the Device and surrounding components. + + - cirrus,classh-internal-algo : Sub-node for the Internal Class H Algorithm + See Section 4.3 Internal Class H Algorithm in the Datasheet. + If not used, the device manages the ClassH Algorithm internally. + +Optional properties for the "cirrus,classh-internal-algo" Sub-node + + Section 7.29 Class H Control + - cirrus,classh-bst-overide : Boolean + - cirrus,classh-bst-max-limit + - cirrus,classh-mem-depth + + Section 7.30 Class H Headroom Control + - cirrus,classh-headroom + + Section 7.31 Class H Release Rate + - cirrus,classh-release-rate + + Section 7.32 Class H Weak FET Drive Control + - cirrus,classh-wk-fet-disable + - cirrus,classh-wk-fet-delay + - cirrus,classh-wk-fet-thld + + Section 7.34 Class H VP Control + - cirrus,classh-vpch-auto + - cirrus,classh-vpch-rate + - cirrus,classh-vpch-man + +Optional Monitor Signal Format sub-node: + + The cs35l35 node can have a single "cirrus,monitor-signal-format" sub-node + for adjusting the Depth, Location and Frame of the Monitoring Signals + for Algorithms. + + See Sections 4.8.2 through 4.8.4 Serial-Port Control in the Datasheet + + -cirrus,monitor-signal-format : Sub-node for the Monitor Signaling Formating + on the I2S Port. Each of the 3 8 bit values in the array contain the settings + for depth, location, and frame. + + If not used, the defaults for the 6 monitor signals is used. + + Sections 7.44 - 7.53 lists values for the depth, location, and frame + for each monitoring signal. + + - cirrus,imon : 4 8 bit values to set the depth, location, frame and ADC + scale of the IMON monitor signal. + + - cirrus,vmon : 3 8 bit values to set the depth, location, and frame + of the VMON monitor signal. + + - cirrus,vpmon : 3 8 bit values to set the depth, location, and frame + of the VPMON monitor signal. + + - cirrus,vbstmon : 3 8 bit values to set the depth, location, and frame + of the VBSTMON monitor signal + + - cirrus,vpbrstat : 3 8 bit values to set the depth, location, and frame + of the VPBRSTAT monitor signal + + - cirrus,zerofill : 3 8 bit values to set the depth, location, and frame\ + of the ZEROFILL packet in the monitor signal + +Example: + +cs35l35: cs35l35@20 { + compatible = "cirrus,cs35l35"; + reg = <0x20>; + VA-supply = <&dummy_vreg>; + VP-supply = <&dummy_vreg>; + reset-gpios = <&axi_gpio 54 0>; + interrupt-parent = <&gpio8>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + cirrus,boost-ctl-millivolt = <9000>; + + cirrus,stereo-config; + cirrus,audio-channel = <0x00>; + cirrus,advisory-channel = <0x01>; + cirrus,shared-boost; + + cirrus,classh-internal-algo { + cirrus,classh-bst-overide; + cirrus,classh-bst-max-limit = <0x01>; + cirrus,classh-mem-depth = <0x01>; + cirrus,classh-release-rate = <0x08>; + cirrus,classh-headroom-millivolt = <0x0B>; + cirrus,classh-wk-fet-disable = <0x01>; + cirrus,classh-wk-fet-delay = <0x04>; + cirrus,classh-wk-fet-thld = <0x01>; + cirrus,classh-vpch-auto = <0x01>; + cirrus,classh-vpch-rate = <0x02>; + cirrus,classh-vpch-man = <0x05>; + }; + + /* Depth, Location, Frame */ + cirrus,monitor-signal-format { + cirrus,imon = /bits/ 8 <0x03 0x00 0x01>; + cirrus,vmon = /bits/ 8 <0x03 0x00 0x00>; + cirrus,vpmon = /bits/ 8 <0x03 0x04 0x00>; + cirrus,vbstmon = /bits/ 8 <0x03 0x04 0x01>; + cirrus,vpbrstat = /bits/ 8 <0x00 0x04 0x00>; + cirrus,zerofill = /bits/ 8 <0x00 0x00 0x00>; + }; + +}; diff --git a/Documentation/devicetree/bindings/sound/dioo,dio2125.txt b/Documentation/devicetree/bindings/sound/dioo,dio2125.txt new file mode 100644 index 000000000000..63dbfe0f11d0 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/dioo,dio2125.txt @@ -0,0 +1,12 @@ +DIO2125 Audio Driver + +Required properties: +- compatible : "dioo,dio2125" +- enable-gpios : the gpio connected to the enable pin of the dio2125 + +Example: + +amp: analog-amplifier { + compatible = "dioo,dio2125"; + enable-gpios = <&gpio GPIOH_3 0>; +}; diff --git a/Documentation/devicetree/bindings/sound/everest,es7134.txt b/Documentation/devicetree/bindings/sound/everest,es7134.txt new file mode 100644 index 000000000000..5495a3cb8b7b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/everest,es7134.txt @@ -0,0 +1,10 @@ +ES7134 i2s DA converter + +Required properties: +- compatible : "everest,es7134" or "everest,es7144" + +Example: + +i2s_codec: external-codec { + compatible = "everest,es7134"; +}; diff --git a/Documentation/devicetree/bindings/sound/fsl,ssi.txt b/Documentation/devicetree/bindings/sound/fsl,ssi.txt index 5b76be45d18b..d415888e1316 100644 --- a/Documentation/devicetree/bindings/sound/fsl,ssi.txt +++ b/Documentation/devicetree/bindings/sound/fsl,ssi.txt @@ -20,24 +20,8 @@ Required properties: have. - interrupt-parent: The phandle for the interrupt controller that services interrupts for this device. -- fsl,playback-dma: Phandle to a node for the DMA channel to use for - playback of audio. This is typically dictated by SOC - design. See the notes below. -- fsl,capture-dma: Phandle to a node for the DMA channel to use for - capture (recording) of audio. This is typically dictated - by SOC design. See the notes below. - fsl,fifo-depth: The number of elements in the transmit and receive FIFOs. This number is the maximum allowed value for SFCSR[TFWM0]. -- fsl,ssi-asynchronous: - If specified, the SSI is to be programmed in asynchronous - mode. In this mode, pins SRCK, STCK, SRFS, and STFS must - all be connected to valid signals. In synchronous mode, - SRCK and SRFS are ignored. Asynchronous mode allows - playback and capture to use different sample sizes and - sample rates. Some drivers may require that SRCK and STCK - be connected together, and SRFS and STFS be connected - together. This would still allow different sample sizes, - but not different sample rates. - clocks: "ipg" - Required clock for the SSI unit "baud" - Required clock for SSI master mode. Otherwise this clock is not used @@ -61,6 +45,24 @@ Optional properties: - fsl,mode: The operating mode for the AC97 interface only. "ac97-slave" - AC97 mode, SSI is clock slave "ac97-master" - AC97 mode, SSI is clock master +- fsl,ssi-asynchronous: + If specified, the SSI is to be programmed in asynchronous + mode. In this mode, pins SRCK, STCK, SRFS, and STFS must + all be connected to valid signals. In synchronous mode, + SRCK and SRFS are ignored. Asynchronous mode allows + playback and capture to use different sample sizes and + sample rates. Some drivers may require that SRCK and STCK + be connected together, and SRFS and STFS be connected + together. This would still allow different sample sizes, + but not different sample rates. +- fsl,playback-dma: Phandle to a node for the DMA channel to use for + playback of audio. This is typically dictated by SOC + design. See the notes below. + Only used on Power Architecture. +- fsl,capture-dma: Phandle to a node for the DMA channel to use for + capture (recording) of audio. This is typically dictated + by SOC design. See the notes below. + Only used on Power Architecture. Child 'codec' node required properties: - compatible: Compatible list, contains the name of the codec diff --git a/Documentation/devicetree/bindings/sound/hisilicon,hi6210-i2s.txt b/Documentation/devicetree/bindings/sound/hisilicon,hi6210-i2s.txt new file mode 100644 index 000000000000..7a296784eb37 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/hisilicon,hi6210-i2s.txt @@ -0,0 +1,42 @@ +* Hisilicon 6210 i2s controller + +Required properties: + +- compatible: should be one of the following: + - "hisilicon,hi6210-i2s" +- reg: physical base address of the i2s controller unit and length of + memory mapped region. +- interrupts: should contain the i2s interrupt. +- clocks: a list of phandle + clock-specifier pairs, one for each entry + in clock-names. +- clock-names: should contain following: + - "dacodec" + - "i2s-base" +- dmas: DMA specifiers for tx dma. See the DMA client binding, + Documentation/devicetree/bindings/dma/dma.txt +- dma-names: should be "tx" and "rx" +- hisilicon,sysctrl-syscon: phandle to sysctrl syscon +- #sound-dai-cells: Should be set to 1 (for multi-dai) + - The dai cell indexes reference the following interfaces: + 0: S2 interface + (Currently that is the only one available, but more may be + supported in the future) + +Example for the hi6210 i2s controller: + +i2s0: i2s@f7118000{ + compatible = "hisilicon,hi6210-i2s"; + reg = <0x0 0xf7118000 0x0 0x8000>; /* i2s unit */ + interrupts = <GIC_SPI 123 IRQ_TYPE_LEVEL_HIGH>; /* 155 "DigACodec_intr"-32 */ + clocks = <&sys_ctrl HI6220_DACODEC_PCLK>, + <&sys_ctrl HI6220_BBPPLL0_DIV>; + clock-names = "dacodec", "i2s-base"; + dmas = <&dma0 15 &dma0 14>; + dma-names = "rx", "tx"; + hisilicon,sysctrl-syscon = <&sys_ctrl>; + #sound-dai-cells = <1>; +}; + +Then when referencing the i2s controller: + sound-dai = <&i2s0 0>; /* index 0 => S2 interface */ + diff --git a/Documentation/devicetree/bindings/sound/max98925.txt b/Documentation/devicetree/bindings/sound/max98925.txt deleted file mode 100644 index 27be63e2aa0d..000000000000 --- a/Documentation/devicetree/bindings/sound/max98925.txt +++ /dev/null @@ -1,22 +0,0 @@ -max98925 audio CODEC - -This device supports I2C. - -Required properties: - - - compatible : "maxim,max98925" - - - vmon-slot-no : slot number used to send voltage information - - - imon-slot-no : slot number used to send current information - - - reg : the I2C address of the device for I2C - -Example: - -codec: max98925@1a { - compatible = "maxim,max98925"; - vmon-slot-no = <0>; - imon-slot-no = <2>; - reg = <0x1a>; -}; diff --git a/Documentation/devicetree/bindings/sound/max98926.txt b/Documentation/devicetree/bindings/sound/max98926.txt deleted file mode 100644 index 0b7f4e4d5f9a..000000000000 --- a/Documentation/devicetree/bindings/sound/max98926.txt +++ /dev/null @@ -1,32 +0,0 @@ -max98926 audio CODEC - -This device supports I2C. - -Required properties: - - - compatible : "maxim,max98926" - - - vmon-slot-no : slot number used to send voltage information - or in inteleave mode this will be used as - interleave slot. - - - imon-slot-no : slot number used to send current information - - - interleave-mode : When using two MAX98926 in a system it is - possible to create ADC data that that will - overflow the frame size. Digital Audio Interleave - mode provides a means to output VMON and IMON data - from two devices on a single DOUT line when running - smaller frames sizes such as 32 BCLKS per LRCLK or - 48 BCLKS per LRCLK. - - - reg : the I2C address of the device for I2C - -Example: - -codec: max98926@1a { - compatible = "maxim,max98926"; - vmon-slot-no = <0>; - imon-slot-no = <2>; - reg = <0x1a>; -}; diff --git a/Documentation/devicetree/bindings/sound/max9892x.txt b/Documentation/devicetree/bindings/sound/max9892x.txt new file mode 100644 index 000000000000..f6171591ddc6 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/max9892x.txt @@ -0,0 +1,41 @@ +Maxim Integrated MAX98925/MAX98926/MAX98927 Speaker Amplifier + +This device supports I2C. + +Required properties: + + - compatible : should be one of the following + - "maxim,max98925" + - "maxim,max98926" + - "maxim,max98927" + + - vmon-slot-no : slot number used to send voltage information + or in inteleave mode this will be used as + interleave slot. + MAX98925/MAX98926 slot range : 0 ~ 30, Default : 0 + MAX98927 slot range : 0 ~ 15, Default : 0 + + - imon-slot-no : slot number used to send current information + MAX98925/MAX98926 slot range : 0 ~ 30, Default : 0 + MAX98927 slot range : 0 ~ 15, Default : 0 + + - interleave-mode : When using two MAX9892X in a system it is + possible to create ADC data that that will + overflow the frame size. Digital Audio Interleave + mode provides a means to output VMON and IMON data + from two devices on a single DOUT line when running + smaller frames sizes such as 32 BCLKS per LRCLK or + 48 BCLKS per LRCLK. + Range : 0 (off), 1 (on), Default : 0 + + - reg : the I2C address of the device for I2C + +Example: + +codec: max98927@3a { + compatible = "maxim,max98927"; + vmon-slot-no = <0>; + imon-slot-no = <1>; + interleave-mode = <0>; + reg = <0x3a>; +}; diff --git a/Documentation/devicetree/bindings/sound/mt2701-wm8960.txt b/Documentation/devicetree/bindings/sound/mt2701-wm8960.txt new file mode 100644 index 000000000000..809b609ea9d0 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt2701-wm8960.txt @@ -0,0 +1,24 @@ +MT2701 with WM8960 CODEC + +Required properties: +- compatible: "mediatek,mt2701-wm8960-machine" +- mediatek,platform: the phandle of MT2701 ASoC platform +- audio-routing: a list of the connections between audio +- mediatek,audio-codec: the phandles of wm8960 codec +- pinctrl-names: Should contain only one value - "default" +- pinctrl-0: Should specify pin control groups used for this controller. + +Example: + + sound:sound { + compatible = "mediatek,mt2701-wm8960-machine"; + mediatek,platform = <&afe>; + audio-routing = + "Headphone", "HP_L", + "Headphone", "HP_R", + "LINPUT1", "AMIC", + "RINPUT1", "AMIC"; + mediatek,audio-codec = <&wm8960>; + pinctrl-names = "default"; + pinctrl-0 = <&aud_pins_default>; + }; diff --git a/Documentation/devicetree/bindings/sound/nau8824.txt b/Documentation/devicetree/bindings/sound/nau8824.txt new file mode 100644 index 000000000000..e0058b97e49a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nau8824.txt @@ -0,0 +1,88 @@ +Nuvoton NAU8824 audio codec + +This device supports I2C only. + +Required properties: + - compatible : Must be "nuvoton,nau8824" + + - reg : the I2C address of the device. This is either 0x1a (CSB=0) or 0x1b (CSB=1). + +Optional properties: + - nuvoton,jkdet-polarity: JKDET pin polarity. 0 - active high, 1 - active low. + + - nuvoton,vref-impedance: VREF Impedance selection + 0 - Open + 1 - 25 kOhm + 2 - 125 kOhm + 3 - 2.5 kOhm + + - nuvoton,micbias-voltage: Micbias voltage level. + 0 - VDDA + 1 - VDDA + 2 - VDDA * 1.1 + 3 - VDDA * 1.2 + 4 - VDDA * 1.3 + 5 - VDDA * 1.4 + 6 - VDDA * 1.53 + 7 - VDDA * 1.53 + + - nuvoton,sar-threshold-num: Number of buttons supported + - nuvoton,sar-threshold: Impedance threshold for each button. Array that contains up to 8 buttons configuration. SAR value is calculated as + SAR = 255 * MICBIAS / SAR_VOLTAGE * R / (2000 + R) + where MICBIAS is configured by 'nuvoton,micbias-voltage', SAR_VOLTAGE is configured by 'nuvoton,sar-voltage', R - button impedance. + Refer datasheet section 10.2 for more information about threshold calculation. + + - nuvoton,sar-hysteresis: Button impedance measurement hysteresis. + + - nuvoton,sar-voltage: Reference voltage for button impedance measurement. + 0 - VDDA + 1 - VDDA + 2 - VDDA * 1.1 + 3 - VDDA * 1.2 + 4 - VDDA * 1.3 + 5 - VDDA * 1.4 + 6 - VDDA * 1.53 + 7 - VDDA * 1.53 + + - nuvoton,sar-compare-time: SAR compare time + 0 - 500 ns + 1 - 1 us + 2 - 2 us + 3 - 4 us + + - nuvoton,sar-sampling-time: SAR sampling time + 0 - 2 us + 1 - 4 us + 2 - 8 us + 3 - 16 us + + - nuvoton,short-key-debounce: Button short key press debounce time. + 0 - 30 ms + 1 - 50 ms + 2 - 100 ms + + - nuvoton,jack-eject-debounce: Jack ejection debounce time. + 0 - 0 ms + 1 - 1 ms + 2 - 10 ms + + +Example: + + headset: nau8824@1a { + compatible = "nuvoton,nau8824"; + reg = <0x1a>; + interrupt-parent = <&gpio>; + interrupts = <TEGRA_GPIO(E, 6) IRQ_TYPE_LEVEL_LOW>; + nuvoton,vref-impedance = <2>; + nuvoton,micbias-voltage = <6>; + // Setup 4 buttons impedance according to Android specification + nuvoton,sar-threshold-num = <4>; + nuvoton,sar-threshold = <0xc 0x1e 0x38 0x60>; + nuvoton,sar-hysteresis = <0>; + nuvoton,sar-voltage = <6>; + nuvoton,sar-compare-time = <1>; + nuvoton,sar-sampling-time = <1>; + nuvoton,short-key-debounce = <0>; + nuvoton,jack-eject-debounce = <1>; + }; diff --git a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt index a6600f6dea64..206aba1b34bb 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt +++ b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt @@ -9,6 +9,7 @@ Required properties: - "rockchip,rk3066-i2s": for rk3066 - "rockchip,rk3188-i2s", "rockchip,rk3066-i2s": for rk3188 - "rockchip,rk3288-i2s", "rockchip,rk3066-i2s": for rk3288 + - "rockchip,rk3368-i2s", "rockchip,rk3066-i2s": for rk3368 - "rockchip,rk3399-i2s", "rockchip,rk3066-i2s": for rk3399 - reg: physical base address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/sound/samsung,odroid.txt b/Documentation/devicetree/bindings/sound/samsung,odroid.txt new file mode 100644 index 000000000000..c1ac70cb0afb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/samsung,odroid.txt @@ -0,0 +1,57 @@ +Samsung Exynos Odroid XU3/XU4 audio complex with MAX98090 codec + +Required properties: + + - compatible - "samsung,odroidxu3-audio" - for Odroid XU3 board, + "samsung,odroidxu4-audio" - for Odroid XU4 board + - model - the user-visible name of this sound complex + - 'cpu' subnode with a 'sound-dai' property containing the phandle of the I2S + controller + - 'codec' subnode with a 'sound-dai' property containing list of phandles + to the CODEC nodes, first entry must be corresponding to the MAX98090 + CODEC and the second entry must be the phandle of the HDMI IP block node + - clocks - should contain entries matching clock names in the clock-names + property + - clock-names - should contain following entries: + - "epll" - indicating the EPLL output clock + - "i2s_rclk" - indicating the RCLK (root) clock of the I2S0 controller + - samsung,audio-widgets - this property specifies off-codec audio elements + like headphones or speakers, for details see widgets.txt + - samsung,audio-routing - a list of the connections between audio + components; each entry is a pair of strings, the first being the + connection's sink, the second being the connection's source; + valid names for sources and sinks are the MAX98090's pins (as + documented in its binding), and the jacks on the board + + For Odroid X2: + "Headphone Jack", "Mic Jack", "DMIC" + + For Odroid U3, XU3: + "Headphone Jack", "Speakers" + + For Odroid XU4: + no entries + +Example: + +sound { + compatible = "samsung,odroidxu3-audio"; + samsung,cpu-dai = <&i2s0>; + samsung,codec-dai = <&max98090>; + model = "Odroid-XU3"; + samsung,audio-routing = + "Headphone Jack", "HPL", + "Headphone Jack", "HPR", + "IN1", "Mic Jack", + "Mic Jack", "MICBIAS"; + + clocks = <&clock CLK_FOUT_EPLL>, <&i2s0 CLK_I2S_RCLK_SRC>; + clock-names = "epll", "sclk_i2s"; + + cpu { + sound-dai = <&i2s0 0>; + }; + codec { + sound-dai = <&hdmi>, <&max98090>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.txt b/Documentation/devicetree/bindings/sound/sgtl5000.txt index 5666da7b8605..7a73a9d62015 100644 --- a/Documentation/devicetree/bindings/sound/sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/sgtl5000.txt @@ -26,6 +26,15 @@ Optional properties: If this node is not mentioned or the value is unknown, then the value is set to 1.25V. +- lrclk-strength: the LRCLK pad strength. Possible values are: +0, 1, 2 and 3 as per the table below: + +VDDIO 1.8V 2.5V 3.3V +0 = Disable +1 = 1.66 mA 2.87 mA 4.02 mA +2 = 3.33 mA 5.74 mA 8.03 mA +3 = 4.99 mA 8.61 mA 12.05 mA + Example: codec: sgtl5000@0a { diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.txt b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt new file mode 100644 index 000000000000..c59a3d779e06 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.txt @@ -0,0 +1,89 @@ +STMicroelectronics STM32 Serial Audio Interface (SAI). + +The SAI interface (Serial Audio Interface) offers a wide set of audio protocols +as I2S standards, LSB or MSB-justified, PCM/DSP, TDM, and AC'97. +The SAI contains two independent audio sub-blocks. Each sub-block has +its own clock generator and I/O lines controller. + +Required properties: + - compatible: Should be "st,stm32f4-sai" + - reg: Base address and size of SAI common register set. + - clocks: Must contain phandle and clock specifier pairs for each entry + in clock-names. + - clock-names: Must contain "x8k" and "x11k" + "x8k": SAI parent clock for sampling rates multiple of 8kHz. + "x11k": SAI parent clock for sampling rates multiple of 11.025kHz. + - interrupts: cpu DAI interrupt line shared by SAI sub-blocks + +Optional properties: + - resets: Reference to a reset controller asserting the SAI + +SAI subnodes: +Two subnodes corresponding to SAI sub-block instances A et B can be defined. +Subnode can be omitted for unsused sub-block. + +SAI subnodes required properties: + - compatible: Should be "st,stm32-sai-sub-a" or "st,stm32-sai-sub-b" + for SAI sub-block A or B respectively. + - reg: Base address and size of SAI sub-block register set. + - clocks: Must contain one phandle and clock specifier pair + for sai_ck which feeds the internal clock generator. + - clock-names: Must contain "sai_ck". + - dmas: see Documentation/devicetree/bindings/dma/stm32-dma.txt + - dma-names: identifier string for each DMA request line + "tx": if sai sub-block is configured as playback DAI + "rx": if sai sub-block is configured as capture DAI + - pinctrl-names: should contain only value "default" + - pinctrl-0: see Documentation/devicetree/bindings/pinctrl/pinctrl-stm32.txt + +Example: +sound_card { + compatible = "audio-graph-card"; + dais = <&sai1b_port>; +}; + +sai1: sai1@40015800 { + compatible = "st,stm32f4-sai"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + reg = <0x40015800 0x4>; + clocks = <&rcc 1 CLK_SAIQ_PDIV>, <&rcc 1 CLK_I2SQ_PDIV>; + clock-names = "x8k", "x11k"; + interrupts = <87>; + + sai1b: audio-controller@40015824 { + #sound-dai-cells = <0>; + compatible = "st,stm32-sai-sub-b"; + reg = <0x40015824 0x1C>; + clocks = <&rcc 1 CLK_SAI2>; + clock-names = "sai_ck"; + dmas = <&dma2 5 0 0x400 0x0>; + dma-names = "tx"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_sai1b>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + sai1b_port: port@0 { + reg = <0>; + cpu_endpoint: endpoint { + remote-endpoint = <&codec_endpoint>; + audio-graph-card,format = "i2s"; + audio-graph-card,bitclock-master = <&codec_endpoint>; + audio-graph-card,frame-master = <&codec_endpoint>; + }; + }; + }; + }; +}; + +audio-codec { + codec_port: port { + codec_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/tas2552.txt b/Documentation/devicetree/bindings/sound/tas2552.txt index c49992c0b62a..2d71eb05c1d3 100644 --- a/Documentation/devicetree/bindings/sound/tas2552.txt +++ b/Documentation/devicetree/bindings/sound/tas2552.txt @@ -5,7 +5,8 @@ The tas2552 serial control bus communicates through I2C protocols Required properties: - compatible - One of: "ti,tas2552" - TAS2552 - - reg - I2C slave address + - reg - I2C slave address: it can be 0x40 if ADDR pin is 0 + or 0x41 if ADDR pin is 1. - supply-*: Required supply regulators are: "vbat" battery voltage "iovdd" I/O Voltage @@ -14,17 +15,20 @@ Required properties: Optional properties: - enable-gpio - gpio pin to enable/disable the device -tas2552 can receive it's reference clock via MCLK, BCLK, IVCLKIN pin or use the +tas2552 can receive its reference clock via MCLK, BCLK, IVCLKIN pin or use the internal 1.8MHz. This CLKIN is used by the PLL. In addition to PLL, the PDM reference clock is also selectable: PLL, IVCLKIN, BCLK or MCLK. For system integration the dt-bindings/sound/tas2552.h header file provides -defined values to selct and configure the PLL and PDM reference clocks. +defined values to select and configure the PLL and PDM reference clocks. Example: tas2552: tas2552@41 { compatible = "ti,tas2552"; reg = <0x41>; + vbat-supply = <®_vbat>; + iovdd-supply = <®_iovdd>; + avdd-supply = <®_avdd>; enable-gpio = <&gpio4 2 GPIO_ACTIVE_HIGH>; }; diff --git a/Documentation/devicetree/bindings/sound/wm8903.txt b/Documentation/devicetree/bindings/sound/wm8903.txt index 94ec32c194bb..afc51caf1137 100644 --- a/Documentation/devicetree/bindings/sound/wm8903.txt +++ b/Documentation/devicetree/bindings/sound/wm8903.txt @@ -28,6 +28,14 @@ Optional properties: performed. If any entry has the value 0xffffffff, that GPIO's configuration will not be modified. + - AVDD-supply : Analog power supply regulator on the AVDD pin. + + - CPVDD-supply : Charge pump supply regulator on the CPVDD pin. + + - DBVDD-supply : Digital buffer supply regulator for the DBVDD pin. + + - DCVDD-supply : Digital core supply regulator for the DCVDD pin. + Pins on the device (for linking into audio routes): * IN1L @@ -54,6 +62,11 @@ codec: wm8903@1a { reg = <0x1a>; interrupts = < 347 >; + AVDD-supply = <&fooreg_a>; + CPVDD-supply = <&fooreg_b>; + DBVDD-supply = <&fooreg_c>; + DCVDC-supply = <&fooreg_d>; + gpio-controller; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/sound/zte,tdm.txt b/Documentation/devicetree/bindings/sound/zte,tdm.txt new file mode 100644 index 000000000000..2a07ca655264 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/zte,tdm.txt @@ -0,0 +1,30 @@ +ZTE TDM DAI driver + +Required properties: + +- compatible : should be one of the following. + * zte,zx296718-tdm +- reg : physical base address of the controller and length of memory mapped + region. +- clocks : Pairs of phandle and specifier referencing the controller's clocks. +- clock-names: "wclk" for the wclk. + "pclk" for the pclk. +-#clock-cells: should be 1. +- zte,tdm-dma-sysctrl : Reference to the sysctrl controller controlling + the dma. includes: + phandle of sysctrl. + register offset in sysctrl for control dma. + mask of the register that be written to sysctrl. + +Example: + + tdm: tdm@1487000 { + compatible = "zte,zx296718-tdm"; + reg = <0x01487000 0x1000>; + clocks = <&audiocrm AUDIO_TDM_WCLK>, <&audiocrm AUDIO_TDM_PCLK>; + clock-names = "wclk", "pclk"; + #clock-cells = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&tdm_global_pin>; + zte,tdm-dma-sysctrl = <&sysctrl 0x10c 4>; + }; diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt index 8bc95e2fc47f..31b5b21598ff 100644 --- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt +++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt @@ -23,6 +23,12 @@ See the clock consumer binding, Obsolete properties: - fsl,spi-num-chipselects : Contains the number of the chipselect +Optional properties: +- fsl,spi-rdy-drctl: Integer, representing the value of DRCTL, the register +controlling the SPI_READY handling. Note that to enable the DRCTL consideration, +the SPI_READY mode-flag needs to be set too. +Valid values are: 0 (disabled), 1 (edge-triggered burst) and 2 (level-triggered burst). + Example: ecspi@70010000 { @@ -35,4 +41,5 @@ ecspi@70010000 { <&gpio3 25 0>; /* GPIO3_25 */ dmas = <&sdma 3 7 1>, <&sdma 4 7 2>; dma-names = "rx", "tx"; + fsl,spi-rdy-drctl = <1>; }; diff --git a/Documentation/devicetree/bindings/spi/spi-bcm63xx-hsspi.txt b/Documentation/devicetree/bindings/spi/spi-bcm63xx-hsspi.txt new file mode 100644 index 000000000000..37b29ee13860 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-bcm63xx-hsspi.txt @@ -0,0 +1,33 @@ +Binding for Broadcom BCM6328 High Speed SPI controller + +Required properties: +- compatible: must contain of "brcm,bcm6328-hsspi". +- reg: Base address and size of the controllers memory area. +- interrupts: Interrupt for the SPI block. +- clocks: phandles of the SPI clock and the PLL clock. +- clock-names: must be "hsspi", "pll". +- #address-cells: <1>, as required by generic SPI binding. +- #size-cells: <0>, also as required by generic SPI binding. + +Optional properties: +- num-cs: some controllers have less than 8 cs signals. Defaults to 8 + if absent. + +Child nodes as per the generic SPI binding. + +Example: + + spi@10001000 { + compatible = "brcm,bcm6328-hsspi"; + reg = <0x10001000 0x600>; + + interrupts = <29>; + + clocks = <&clkctl 9>, <&hsspi_pll>; + clock-names = "hsspi", "pll"; + + num-cs = <2>; + + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/spi/spi-bcm63xx.txt b/Documentation/devicetree/bindings/spi/spi-bcm63xx.txt new file mode 100644 index 000000000000..1c16f6692613 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-bcm63xx.txt @@ -0,0 +1,33 @@ +Binding for Broadcom BCM6348/BCM6358 SPI controller + +Required properties: +- compatible: must contain one of "brcm,bcm6348-spi", "brcm,bcm6358-spi". +- reg: Base address and size of the controllers memory area. +- interrupts: Interrupt for the SPI block. +- clocks: phandle of the SPI clock. +- clock-names: has to be "spi". +- #address-cells: <1>, as required by generic SPI binding. +- #size-cells: <0>, also as required by generic SPI binding. + +Optional properties: +- num-cs: some controllers have less than 8 cs signals. Defaults to 8 + if absent. + +Child nodes as per the generic SPI binding. + +Example: + + spi@10000800 { + compatible = "brcm,bcm6368-spi", "brcm,bcm6358-spi"; + reg = <0x10000800 0x70c>; + + interrupts = <1>; + + clocks = <&clkctl 9>; + clock-names = "spi"; + + num-cs = <5>; + + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/spi/spi_pl022.txt b/Documentation/devicetree/bindings/spi/spi_pl022.txt index 4d1673ca8cf8..7638b4968ddb 100644 --- a/Documentation/devicetree/bindings/spi/spi_pl022.txt +++ b/Documentation/devicetree/bindings/spi/spi_pl022.txt @@ -30,7 +30,10 @@ contain the following properties. 0: SPI 1: Texas Instruments Synchronous Serial Frame Format 2: Microwire (Half Duplex) -- pl022,com-mode : polling, interrupt or dma +- pl022,com-mode : specifies the transfer mode: + 0: interrupt mode + 1: polling mode (default mode if property not present) + 2: DMA mode - pl022,rx-level-trig : Rx FIFO watermark level - pl022,tx-level-trig : Tx FIFO watermark level - pl022,ctrl-len : Microwire interface: Control length @@ -56,9 +59,7 @@ Example: spi-max-frequency = <12000000>; spi-cpol; spi-cpha; - pl022,hierarchy = <0>; pl022,interface = <0>; - pl022,slave-tx-disable; pl022,com-mode = <0x2>; pl022,rx-level-trig = <0>; pl022,tx-level-trig = <0>; @@ -67,4 +68,3 @@ Example: pl022,duplex = <0>; }; }; - diff --git a/Documentation/devicetree/bindings/timer/cortina,gemini-timer.txt b/Documentation/devicetree/bindings/timer/cortina,gemini-timer.txt deleted file mode 100644 index 16ea1d3b2e9e..000000000000 --- a/Documentation/devicetree/bindings/timer/cortina,gemini-timer.txt +++ /dev/null @@ -1,22 +0,0 @@ -Cortina Systems Gemini timer - -This timer is embedded in the Cortina Systems Gemini SoCs. - -Required properties: - -- compatible : Must be "cortina,gemini-timer" -- reg : Should contain registers location and length -- interrupts : Should contain the three timer interrupts with - flags for rising edge -- syscon : a phandle to the global Gemini system controller - -Example: - -timer@43000000 { - compatible = "cortina,gemini-timer"; - reg = <0x43000000 0x1000>; - interrupts = <14 IRQ_TYPE_EDGE_RISING>, /* Timer 1 */ - <15 IRQ_TYPE_EDGE_RISING>, /* Timer 2 */ - <16 IRQ_TYPE_EDGE_RISING>; /* Timer 3 */ - syscon = <&syscon>; -}; diff --git a/Documentation/devicetree/bindings/timer/faraday,fttmr010.txt b/Documentation/devicetree/bindings/timer/faraday,fttmr010.txt new file mode 100644 index 000000000000..b73ca6cd07f8 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/faraday,fttmr010.txt @@ -0,0 +1,33 @@ +Faraday Technology timer + +This timer is a generic IP block from Faraday Technology, embedded in the +Cortina Systems Gemini SoCs and other designs. + +Required properties: + +- compatible : Must be one of + "faraday,fttmr010" + "cortina,gemini-timer" +- reg : Should contain registers location and length +- interrupts : Should contain the three timer interrupts usually with + flags for falling edge + +Optionally required properties: + +- clocks : a clock to provide the tick rate for "faraday,fttmr010" +- clock-names : should be "EXTCLK" and "PCLK" for the external tick timer + and peripheral clock respectively, for "faraday,fttmr010" +- syscon : a phandle to the global Gemini system controller if the compatible + type is "cortina,gemini-timer" + +Example: + +timer@43000000 { + compatible = "faraday,fttmr010"; + reg = <0x43000000 0x1000>; + interrupts = <14 IRQ_TYPE_EDGE_FALLING>, /* Timer 1 */ + <15 IRQ_TYPE_EDGE_FALLING>, /* Timer 2 */ + <16 IRQ_TYPE_EDGE_FALLING>; /* Timer 3 */ + clocks = <&extclk>, <&pclk>; + clock-names = "EXTCLK", "PCLK"; +}; diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt index a41b184d5538..16a5f4577a61 100644 --- a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt +++ b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt @@ -1,9 +1,15 @@ Rockchip rk timer Required properties: -- compatible: shall be one of: - "rockchip,rk3288-timer" - for rk3066, rk3036, rk3188, rk322x, rk3288, rk3368 - "rockchip,rk3399-timer" - for rk3399 +- compatible: should be: + "rockchip,rk3036-timer", "rockchip,rk3288-timer": for Rockchip RK3036 + "rockchip,rk3066-timer", "rockchip,rk3288-timer": for Rockchip RK3066 + "rockchip,rk3188-timer", "rockchip,rk3288-timer": for Rockchip RK3188 + "rockchip,rk3228-timer", "rockchip,rk3288-timer": for Rockchip RK3228 + "rockchip,rk3229-timer", "rockchip,rk3288-timer": for Rockchip RK3229 + "rockchip,rk3288-timer": for Rockchip RK3288 + "rockchip,rk3368-timer", "rockchip,rk3288-timer": for Rockchip RK3368 + "rockchip,rk3399-timer": for Rockchip RK3399 - reg: base address of the timer register starting with TIMERS CONTROL register - interrupts: should contain the interrupts for Timer0 - clocks : must contain an entry for each entry in clock-names diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/trivial-devices.txt index ad10fbe61562..ad10fbe61562 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/trivial-devices.txt diff --git a/Documentation/devicetree/bindings/usb/ehci-orion.txt b/Documentation/devicetree/bindings/usb/ehci-orion.txt index 17c3bc858b86..2855bae79fda 100644 --- a/Documentation/devicetree/bindings/usb/ehci-orion.txt +++ b/Documentation/devicetree/bindings/usb/ehci-orion.txt @@ -1,7 +1,9 @@ * EHCI controller, Orion Marvell variants Required properties: -- compatible: must be "marvell,orion-ehci" +- compatible: must be one of the following + "marvell,orion-ehci" + "marvell,armada-3700-ehci" - reg: physical base address of the controller and length of memory mapped region. - interrupts: The EHCI interrupt diff --git a/Documentation/devicetree/bindings/usb/generic.txt b/Documentation/devicetree/bindings/usb/generic.txt index bfadeb1c3bab..0a74ab8dfdc2 100644 --- a/Documentation/devicetree/bindings/usb/generic.txt +++ b/Documentation/devicetree/bindings/usb/generic.txt @@ -22,6 +22,7 @@ Optional properties: property is used if any real OTG features(HNP/SRP/ADP) is enabled, if ADP is required, otg-rev should be 0x0200 or above. + - companion: phandle of a companion - hnp-disable: tells OTG controllers we want to disable OTG HNP, normally HNP is the basic function of real OTG except you want it to be a srp-capable only B device. diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index ec0bfb9bbebd..ee558477e164 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -51,6 +51,7 @@ brcm Broadcom Corporation buffalo Buffalo, Inc. calxeda Calxeda capella Capella Microsystems, Inc +cascoda Cascoda, Ltd. cavium Cavium, Inc. cdns Cadence Design Systems Inc. ceva Ceva, Inc. @@ -79,6 +80,7 @@ denx Denx Software Engineering devantech Devantech, Ltd. digi Digi International Inc. digilent Diglent, Inc. +dioo Dioo Microcircuit Co., Ltd dlg Dialog Semiconductor dlink D-Link Corporation dmo Data Modul AG @@ -102,6 +104,7 @@ ettus NI Ettus Research eukrea Eukréa Electromatique everest Everest Semiconductor Co. Ltd. everspin Everspin Technologies, Inc. +exar Exar Corporation excito Excito ezchip EZchip Semiconductor faraday Faraday Technology Corporation @@ -178,6 +181,7 @@ maxim Maxim Integrated Products mcube mCube meas Measurement Specialties mediatek MediaTek Inc. +megachips MegaChips melexis Melexis N.V. melfas MELFAS Inc. memsic MEMSIC Inc. @@ -212,6 +216,7 @@ newhaven Newhaven Display International ni National Instruments nintendo Nintendo nokia Nokia +nordic Nordic Semiconductor nuvoton Nuvoton Technology Corporation nvd New Vision Display nvidia NVIDIA @@ -258,6 +263,7 @@ richtek Richtek Technology Corporation ricoh Ricoh Co. Ltd. rikomagic Rikomagic Tech Corp. Ltd rockchip Fuzhou Rockchip Electronics Co., Ltd +rohm ROHM Semiconductor Co., Ltd samsung Samsung Semiconductor samtec Samtec/Softing company sandisk Sandisk Corporation @@ -265,6 +271,7 @@ sbs Smart Battery System schindler Schindler seagate Seagate Technology PLC semtech Semtech Corporation +sensirion Sensirion AG sgx SGX Sensortech sharp Sharp Corporation si-en Si-En Technology Ltd. @@ -335,6 +342,7 @@ wd Western Digital Corp. wetek WeTek Electronics, limited. wexler Wexler winbond Winbond Electronics corp. +winstar Winstar Display Corp. wlf Wolfson Microelectronics wm Wondermedia Technologies, Inc. x-powers X-Powers diff --git a/Documentation/doc-guide/hello.dot b/Documentation/doc-guide/hello.dot new file mode 100644 index 000000000000..504621dfc595 --- /dev/null +++ b/Documentation/doc-guide/hello.dot @@ -0,0 +1,3 @@ +graph G { + Hello -- World +} diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 96fe7ccb2c67..731334de3efd 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -34,8 +34,9 @@ format-specific subdirectories under ``Documentation/output``. To generate documentation, Sphinx (``sphinx-build``) must obviously be installed. For prettier HTML output, the Read the Docs Sphinx theme -(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also -needed. All of these are widely available and packaged in distributions. +(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need +``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org). +All of these are widely available and packaged in distributions. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose @@ -73,7 +74,16 @@ Specific guidelines for the kernel documentation Here are some specific guidelines for the kernel documentation: -* Please don't go overboard with reStructuredText markup. Keep it simple. +* Please don't go overboard with reStructuredText markup. Keep it + simple. For the most part the documentation should be plain text with + just enough consistency in formatting that it can be converted to + other formats. + +* Please keep the formatting changes minimal when converting existing + documentation to reStructuredText. + +* Also update the content, not just the formatting, when converting + documentation. * Please stick to this order of heading adornments: @@ -103,6 +113,12 @@ Here are some specific guidelines for the kernel documentation: the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. +* For inserting fixed width text blocks (for code examples, use case + examples, etc.), use ``::`` for anything that doesn't really benefit + from syntax highlighting, especially short snippets. Use + ``.. code-block:: <language>`` for longer code blocks that benefit + from highlighting. + the C domain ------------ @@ -217,3 +233,96 @@ Rendered as: * .. _`last row`: - column 3 + + +Figures & Images +================ + +If you want to add an image, you should use the ``kernel-figure`` and +``kernel-image`` directives. E.g. to insert a figure with a scalable +image format use SVG (:ref:`svg_image_example`):: + + .. kernel-figure:: svg_image.svg + :alt: simple SVG image + + SVG image example + +.. _svg_image_example: + +.. kernel-figure:: svg_image.svg + :alt: simple SVG image + + SVG image example + +The kernel figure (and image) directive support **DOT** formated files, see + +* DOT: http://graphviz.org/pdf/dotguide.pdf +* Graphviz: http://www.graphviz.org/content/dot-language + +A simple example (:ref:`hello_dot_file`):: + + .. kernel-figure:: hello.dot + :alt: hello world + + DOT's hello world example + +.. _hello_dot_file: + +.. kernel-figure:: hello.dot + :alt: hello world + + DOT's hello world example + +Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the +``kernel-render`` directives.:: + + .. kernel-render:: DOT + :alt: foobar digraph + :caption: Embedded **DOT** (Graphviz) code + + digraph foo { + "bar" -> "baz"; + } + +How this will be rendered depends on the installed tools. If Graphviz is +installed, you will see an vector image. If not the raw markup is inserted as +*literal-block* (:ref:`hello_dot_render`). + +.. _hello_dot_render: + +.. kernel-render:: DOT + :alt: foobar digraph + :caption: Embedded **DOT** (Graphviz) code + + digraph foo { + "bar" -> "baz"; + } + +The *render* directive has all the options known from the *figure* directive, +plus option ``caption``. If ``caption`` has a value, a *figure* node is +inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if +you want to refer it (:ref:`hello_svg_render`). + +Embedded **SVG**:: + + .. kernel-render:: SVG + :caption: Embedded **SVG** markup + :alt: so-nw-arrow + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> + ... + </svg> + +.. _hello_svg_render: + +.. kernel-render:: SVG + :caption: Embedded **SVG** markup + :alt: so-nw-arrow + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" + version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> + </svg> diff --git a/Documentation/doc-guide/svg_image.svg b/Documentation/doc-guide/svg_image.svg new file mode 100644 index 000000000000..5405f85b8137 --- /dev/null +++ b/Documentation/doc-guide/svg_image.svg @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- originate: https://commons.wikimedia.org/wiki/File:Variable_Resistor.svg --> +<svg xmlns="http://www.w3.org/2000/svg" + version="1.1" baseProfile="full" + width="70px" height="40px" viewBox="0 0 700 400"> + <line x1="0" y1="200" x2="700" y2="200" stroke="black" stroke-width="20px"/> + <rect x="100" y="100" width="500" height="200" fill="white" stroke="black" stroke-width="20px"/> + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> +</svg> diff --git a/Documentation/driver-api/80211/cfg80211.rst b/Documentation/driver-api/80211/cfg80211.rst index eca534ab6172..8ffac57e1f5b 100644 --- a/Documentation/driver-api/80211/cfg80211.rst +++ b/Documentation/driver-api/80211/cfg80211.rst @@ -2,6 +2,9 @@ cfg80211 subsystem ================== +.. kernel-doc:: include/net/cfg80211.h + :doc: Introduction + Device registration =================== @@ -180,6 +183,12 @@ Actions and configuration :functions: cfg80211_ibss_joined .. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_resp_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_done + +.. kernel-doc:: include/net/cfg80211.h :functions: cfg80211_connect_result .. kernel-doc:: include/net/cfg80211.h diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 935b9b8d456c..472e7a664d13 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -7,6 +7,12 @@ Driver Entry and Exit points .. kernel-doc:: include/linux/init.h :internal: +Driver device table +------------------- + +.. kernel-doc:: include/linux/mod_devicetable.h + :internal: + Atomic and pointer manipulation ------------------------------- diff --git a/Documentation/driver-api/firmware/index.rst b/Documentation/driver-api/firmware/index.rst index 1abe01793031..29da39ec4b8a 100644 --- a/Documentation/driver-api/firmware/index.rst +++ b/Documentation/driver-api/firmware/index.rst @@ -7,6 +7,7 @@ Linux Firmware API introduction core request_firmware + other_interfaces .. only:: subproject and html diff --git a/Documentation/driver-api/firmware/other_interfaces.rst b/Documentation/driver-api/firmware/other_interfaces.rst new file mode 100644 index 000000000000..36c47b1e9824 --- /dev/null +++ b/Documentation/driver-api/firmware/other_interfaces.rst @@ -0,0 +1,15 @@ +Other Firmware Interfaces +========================= + +DMI Interfaces +-------------- + +.. kernel-doc:: drivers/firmware/dmi_scan.c + :export: + +EDD Interfaces +-------------- + +.. kernel-doc:: drivers/firmware/edd.c + :internal: + diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 60db00d1532b..8058a87c1c74 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -26,7 +26,8 @@ available subsections can be seen below. regulator iio/index input - usb + usb/index + pci spi i2c hsi @@ -36,6 +37,7 @@ available subsections can be seen below. 80211/index uio-howto firmware/index + misc_devices .. only:: subproject and html diff --git a/Documentation/driver-api/misc_devices.rst b/Documentation/driver-api/misc_devices.rst new file mode 100644 index 000000000000..c7ee7b02ba88 --- /dev/null +++ b/Documentation/driver-api/misc_devices.rst @@ -0,0 +1,5 @@ +Miscellaneous Devices +===================== + +.. kernel-doc:: drivers/char/misc.c + :export: diff --git a/Documentation/driver-api/pci.rst b/Documentation/driver-api/pci.rst new file mode 100644 index 000000000000..01a6c8b7d3a7 --- /dev/null +++ b/Documentation/driver-api/pci.rst @@ -0,0 +1,50 @@ +PCI Support Library +------------------- + +.. kernel-doc:: drivers/pci/pci.c + :export: + +.. kernel-doc:: drivers/pci/pci-driver.c + :export: + +.. kernel-doc:: drivers/pci/remove.c + :export: + +.. kernel-doc:: drivers/pci/search.c + :export: + +.. kernel-doc:: drivers/pci/msi.c + :export: + +.. kernel-doc:: drivers/pci/bus.c + :export: + +.. kernel-doc:: drivers/pci/access.c + :export: + +.. kernel-doc:: drivers/pci/irq.c + :export: + +.. kernel-doc:: drivers/pci/htirq.c + :export: + +.. kernel-doc:: drivers/pci/probe.c + :export: + +.. kernel-doc:: drivers/pci/slot.c + :export: + +.. kernel-doc:: drivers/pci/rom.c + :export: + +.. kernel-doc:: drivers/pci/iov.c + :export: + +.. kernel-doc:: drivers/pci/pci-sysfs.c + :internal: + +PCI Hotplug Support Library +--------------------------- + +.. kernel-doc:: drivers/pci/hotplug/pci_hotplug_core.c + :export: diff --git a/Documentation/usb/URB.txt b/Documentation/driver-api/usb/URB.rst index 50da0d455444..61a54da9fce9 100644 --- a/Documentation/usb/URB.txt +++ b/Documentation/driver-api/usb/URB.rst @@ -1,28 +1,37 @@ -Revised: 2000-Dec-05. -Again: 2002-Jul-06 -Again: 2005-Sep-19 +.. _usb-urb: - NOTE: +USB Request Block (URB) +~~~~~~~~~~~~~~~~~~~~~~~ - The USB subsystem now has a substantial section in "The Linux Kernel API" - guide (in Documentation/DocBook), generated from the current source - code. This particular documentation file isn't particularly current or - complete; don't rely on it except for a quick overview. +:Revised: 2000-Dec-05 +:Again: 2002-Jul-06 +:Again: 2005-Sep-19 +:Again: 2017-Mar-29 -1.1. Basic concept or 'What is an URB?' +.. note:: -The basic idea of the new driver is message passing, the message itself is -called USB Request Block, or URB for short. + The USB subsystem now has a substantial section at :ref:`usb-hostside-api` + section, generated from the current source code. + This particular documentation file isn't complete and may not be + updated to the last version; don't rely on it except for a quick + overview. -- An URB consists of all relevant information to execute any USB transaction - and deliver the data and status back. +Basic concept or 'What is an URB?' +================================== -- Execution of an URB is inherently an asynchronous operation, i.e. the - usb_submit_urb(urb) call returns immediately after it has successfully +The basic idea of the new driver is message passing, the message itself is +called USB Request Block, or URB for short. + +- An URB consists of all relevant information to execute any USB transaction + and deliver the data and status back. + +- Execution of an URB is inherently an asynchronous operation, i.e. the + :c:func:`usb_submit_urb` call returns immediately after it has successfully queued the requested action. -- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. +- Transfers for one URB can be canceled with :c:func:`usb_unlink_urb` + at any time. - Each URB has a completion handler, which is called after the action has been successfully completed or canceled. The URB also contains a @@ -35,53 +44,55 @@ called USB Request Block, or URB for short. of data to (or from) devices when using periodic transfer modes. -1.2. The URB structure +The URB structure +================= -Some of the fields in an URB are: +Some of the fields in struct :c:type:`urb` are:: -struct urb -{ -// (IN) device and pipe specify the endpoint queue + struct urb + { + // (IN) device and pipe specify the endpoint queue struct usb_device *dev; // pointer to associated USB device unsigned int pipe; // endpoint information - unsigned int transfer_flags; // ISO_ASAP, SHORT_NOT_OK, etc. + unsigned int transfer_flags; // URB_ISO_ASAP, URB_SHORT_NOT_OK, etc. -// (IN) all urbs need completion routines + // (IN) all urbs need completion routines void *context; // context for completion routine - void (*complete)(struct urb *); // pointer to completion routine + usb_complete_t complete; // pointer to completion routine -// (OUT) status after each completion + // (OUT) status after each completion int status; // returned status -// (IN) buffer used for data transfers + // (IN) buffer used for data transfers void *transfer_buffer; // associated data buffer - int transfer_buffer_length; // data buffer length + u32 transfer_buffer_length; // data buffer length int number_of_packets; // size of iso_frame_desc -// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used - int actual_length; // actual data buffer length + // (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used + u32 actual_length; // actual data buffer length -// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) - unsigned char* setup_packet; // setup packet (control only) + // (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) + unsigned char *setup_packet; // setup packet (control only) -// Only for PERIODIC transfers (ISO, INTERRUPT) - // (IN/OUT) start_frame is set unless ISO_ASAP isn't set + // Only for PERIODIC transfers (ISO, INTERRUPT) + // (IN/OUT) start_frame is set unless URB_ISO_ASAP isn't set int start_frame; // start frame int interval; // polling interval // ISO only: packets are only "best effort"; each can have errors int error_count; // number of errors struct usb_iso_packet_descriptor iso_frame_desc[0]; -}; + }; Your driver must create the "pipe" value using values from the appropriate endpoint descriptor in an interface that it's claimed. -1.3. How to get an URB? +How to get an URB? +================== -URBs are allocated with the following call +URBs are allocated by calling :c:func:`usb_alloc_urb`:: struct urb *usb_alloc_urb(int isoframes, int mem_flags) @@ -91,7 +102,7 @@ you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter holds standard memory allocation flags, letting you control (among other things) whether the underlying code may block or not. -To free an URB, use +To free an URB, use :c:func:`usb_free_urb`:: void usb_free_urb(struct urb *urb) @@ -100,78 +111,84 @@ returned to you in a completion callback. It will automatically be deallocated when it is no longer in use. -1.4. What has to be filled in? +What has to be filled in? +========================= -Depending on the type of transaction, there are some inline functions -defined in <linux/usb.h> to simplify the initialization, such as -fill_control_urb() and fill_bulk_urb(). In general, they need the usb -device pointer, the pipe (usual format from usb.h), the transfer buffer, -the desired transfer length, the completion handler, and its context. -Take a look at the some existing drivers to see how they're used. +Depending on the type of transaction, there are some inline functions +defined in ``linux/usb.h`` to simplify the initialization, such as +:c:func:`usb_fill_control_urb`, :c:func:`usb_fill_bulk_urb` and +:c:func:`usb_fill_int_urb`. In general, they need the usb device pointer, +the pipe (usual format from usb.h), the transfer buffer, the desired transfer +length, the completion handler, and its context. Take a look at the some +existing drivers to see how they're used. Flags: -For ISO there are two startup behaviors: Specified start_frame or ASAP. -For ASAP set URB_ISO_ASAP in transfer_flags. -If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in +- For ISO there are two startup behaviors: Specified start_frame or ASAP. +- For ASAP set ``URB_ISO_ASAP`` in transfer_flags. + +If short packets should NOT be tolerated, set ``URB_SHORT_NOT_OK`` in transfer_flags. -1.5. How to submit an URB? +How to submit an URB? +===================== -Just call +Just call :c:func:`usb_submit_urb`:: int usb_submit_urb(struct urb *urb, int mem_flags) -The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation, -such as whether the lower levels may block when memory is tight. +The ``mem_flags`` parameter, such as ``GFP_ATOMIC``, controls memory +allocation, such as whether the lower levels may block when memory is tight. It immediately returns, either with status 0 (request queued) or some error code, usually caused by the following: -- Out of memory (-ENOMEM) -- Unplugged device (-ENODEV) -- Stalled endpoint (-EPIPE) -- Too many queued ISO transfers (-EAGAIN) -- Too many requested ISO frames (-EFBIG) -- Invalid INT interval (-EINVAL) -- More than one packet for INT (-EINVAL) +- Out of memory (``-ENOMEM``) +- Unplugged device (``-ENODEV``) +- Stalled endpoint (``-EPIPE``) +- Too many queued ISO transfers (``-EAGAIN``) +- Too many requested ISO frames (``-EFBIG``) +- Invalid INT interval (``-EINVAL``) +- More than one packet for INT (``-EINVAL``) -After submission, urb->status is -EINPROGRESS; however, you should never -look at that value except in your completion callback. +After submission, ``urb->status`` is ``-EINPROGRESS``; however, you should +never look at that value except in your completion callback. For isochronous endpoints, your completion handlers should (re)submit -URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering, -to get seamless ISO streaming. +URBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using +multi-buffering, to get seamless ISO streaming. -1.6. How to cancel an already running URB? +How to cancel an already running URB? +===================================== There are two ways to cancel an URB you've submitted but which hasn't been returned to your driver yet. For an asynchronous cancel, call +:c:func:`usb_unlink_urb`:: int usb_unlink_urb(struct urb *urb) It removes the urb from the internal list and frees all allocated HW descriptors. The status is changed to reflect unlinking. Note -that the URB will not normally have finished when usb_unlink_urb() +that the URB will not normally have finished when :c:func:`usb_unlink_urb` returns; you must still wait for the completion handler to be called. -To cancel an URB synchronously, call +To cancel an URB synchronously, call :c:func:`usb_kill_urb`:: void usb_kill_urb(struct urb *urb) -It does everything usb_unlink_urb does, and in addition it waits +It does everything :c:func:`usb_unlink_urb` does, and in addition it waits until after the URB has been returned and the completion handler has finished. It also marks the URB as temporarily unusable, so that if the completion handler or anyone else tries to resubmit it -they will get a -EPERM error. Thus you can be sure that when -usb_kill_urb() returns, the URB is totally idle. +they will get a ``-EPERM`` error. Thus you can be sure that when +:c:func:`usb_kill_urb` returns, the URB is totally idle. There is a lifetime issue to consider. An URB may complete at any time, and the completion handler may free the URB. If this happens -while usb_unlink_urb or usb_kill_urb is running, it will cause a -memory-access violation. The driver is responsible for avoiding this, +while :c:func:`usb_unlink_urb` or :c:func:`usb_kill_urb` is running, it will +cause a memory-access violation. The driver is responsible for avoiding this, which often means some sort of lock will be needed to prevent the URB from being deallocated while it is still in use. @@ -181,24 +198,25 @@ when usb_unlink_urb is invoked. The general solution to this problem is to increment the URB's reference count while holding the lock, then drop the lock and call usb_unlink_urb or usb_kill_urb, and then decrement the URB's reference count. You increment the reference -count by calling +count by calling :c:func`usb_get_urb`:: struct urb *usb_get_urb(struct urb *urb) (ignore the return value; it is the same as the argument) and -decrement the reference count by calling usb_free_urb. Of course, +decrement the reference count by calling :c:func:`usb_free_urb`. Of course, none of this is necessary if there's no danger of the URB being freed by the completion handler. -1.7. What about the completion handler? +What about the completion handler? +================================== -The handler is of the following type: +The handler is of the following type:: typedef void (*usb_complete_t)(struct urb *) I.e., it gets the URB that caused the completion call. In the completion -handler, you should have a look at urb->status to detect any USB errors. +handler, you should have a look at ``urb->status`` to detect any USB errors. Since the context parameter is included in the URB, you can pass information to the completion handler. @@ -208,54 +226,65 @@ sixteen packets to transfer your 1KByte buffer, and ten of them might have transferred successfully before the completion was called. -NOTE: ***** WARNING ***** -NEVER SLEEP IN A COMPLETION HANDLER. These are often called in atomic -context. +.. warning:: + + NEVER SLEEP IN A COMPLETION HANDLER. + + These are often called in atomic context. In the current kernel, completion handlers run with local interrupts disabled, but in the future this will be changed, so don't assume that local IRQs are always disabled inside completion handlers. -1.8. How to do isochronous (ISO) transfers? +How to do isochronous (ISO) transfers? +====================================== + +Besides the fields present on a bulk transfer, for ISO, you also +also have to set ``urb->interval`` to say how often to make transfers; it's +often one per frame (which is once every microframe for highspeed devices). +The actual interval used will be a power of two that's no bigger than what +you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill +most ISO transfer fields. -For ISO transfers you have to fill a usb_iso_packet_descriptor structure, -allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each -packet you want to schedule. You also have to set urb->interval to say -how often to make transfers; it's often one per frame (which is once -every microframe for highspeed devices). The actual interval used will -be a power of two that's no bigger than what you specify. +For ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor` +structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for +each packet you want to schedule. -The usb_submit_urb() call modifies urb->interval to the implemented interval -value that is less than or equal to the requested interval value. If -ISO_ASAP scheduling is used, urb->start_frame is also updated. +The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented +interval value that is less than or equal to the requested interval value. If +``URB_ISO_ASAP`` scheduling is used, ``urb->start_frame`` is also updated. For each entry you have to specify the data offset for this frame (base is transfer_buffer), and the length you want to write/expect to read. -After completion, actual_length contains the actual transferred length and +After completion, actual_length contains the actual transferred length and status contains the resulting status for the ISO transfer for this frame. It is allowed to specify a varying length from frame to frame (e.g. for -audio synchronisation/adaptive transfer rates). You can also use the length +audio synchronisation/adaptive transfer rates). You can also use the length 0 to omit one or more frames (striping). -For scheduling you can choose your own start frame or ISO_ASAP. As explained -earlier, if you always keep at least one URB queued and your completion -keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb -bandwidth utilization allows). +For scheduling you can choose your own start frame or ``URB_ISO_ASAP``. As +explained earlier, if you always keep at least one URB queued and your +completion keeps (re)submitting a later URB, you'll get smooth ISO streaming +(if usb bandwidth utilization allows). If you specify your own start frame, make sure it's several frames in advance of the current frame. You might want this model if you're synchronizing ISO data with some other event stream. -1.9. How to start interrupt (INT) transfers? +How to start interrupt (INT) transfers? +======================================= Interrupt transfers, like isochronous transfers, are periodic, and happen in intervals that are powers of two (1, 2, 4 etc) units. Units are frames for full and low speed devices, and microframes for high speed ones. -The usb_submit_urb() call modifies urb->interval to the implemented interval -value that is less than or equal to the requested interval value. +You can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields. + +The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented +interval value that is less than or equal to the requested interval value. In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically restarted when they complete. They end when the completion handler is called, just like other URBs. If you want an interrupt URB to be restarted, your completion handler must resubmit it. +s diff --git a/Documentation/usb/anchors.txt b/Documentation/driver-api/usb/anchors.rst index fe6a99a32bbd..4b248e691bd6 100644 --- a/Documentation/usb/anchors.txt +++ b/Documentation/driver-api/usb/anchors.rst @@ -1,3 +1,6 @@ +USB Anchors +~~~~~~~~~~~ + What is anchor? =============== @@ -13,7 +16,7 @@ Allocation and Initialisation ============================= There's no API to allocate an anchor. It is simply declared -as struct usb_anchor. init_usb_anchor() must be called to +as struct usb_anchor. :c:func:`init_usb_anchor` must be called to initialise the data structure. Deallocation @@ -26,52 +29,53 @@ Association and disassociation of URBs with anchors =================================================== An association of URBs to an anchor is made by an explicit -call to usb_anchor_urb(). The association is maintained until +call to :c:func:`usb_anchor_urb`. The association is maintained until an URB is finished by (successful) completion. Thus disassociation is automatic. A function is provided to forcibly finish (kill) all URBs associated with an anchor. -Furthermore, disassociation can be made with usb_unanchor_urb() +Furthermore, disassociation can be made with :c:func:`usb_unanchor_urb` Operations on multitudes of URBs ================================ -usb_kill_anchored_urbs() ------------------------- +:c:func:`usb_kill_anchored_urbs` +-------------------------------- This function kills all URBs associated with an anchor. The URBs are called in the reverse temporal order they were submitted. This way no data can be reordered. -usb_unlink_anchored_urbs() --------------------------- +:c:func:`usb_unlink_anchored_urbs` +---------------------------------- + This function unlinks all URBs associated with an anchor. The URBs are processed in the reverse temporal order they were submitted. -This is similar to usb_kill_anchored_urbs(), but it will not sleep. +This is similar to :c:func:`usb_kill_anchored_urbs`, but it will not sleep. Therefore no guarantee is made that the URBs have been unlinked when the call returns. They may be unlinked later but will be unlinked in finite time. -usb_scuttle_anchored_urbs() ---------------------------- +:c:func:`usb_scuttle_anchored_urbs` +----------------------------------- All URBs of an anchor are unanchored en masse. -usb_wait_anchor_empty_timeout() -------------------------------- +:c:func:`usb_wait_anchor_empty_timeout` +--------------------------------------- This function waits for all URBs associated with an anchor to finish or a timeout, whichever comes first. Its return value will tell you whether the timeout was reached. -usb_anchor_empty() ------------------- +:c:func:`usb_anchor_empty` +-------------------------- Returns true if no URBs are associated with an anchor. Locking is the caller's responsibility. -usb_get_from_anchor() ---------------------- +:c:func:`usb_get_from_anchor` +----------------------------- Returns the oldest anchored URB of an anchor. The URB is unanchored and returned with a reference. As you may mix URBs to several diff --git a/Documentation/usb/bulk-streams.txt b/Documentation/driver-api/usb/bulk-streams.rst index ffc02021863e..99b515babdeb 100644 --- a/Documentation/usb/bulk-streams.txt +++ b/Documentation/driver-api/usb/bulk-streams.rst @@ -1,3 +1,6 @@ +USB bulk streams +~~~~~~~~~~~~~~~~ + Background ========== @@ -25,7 +28,9 @@ time. Driver implications =================== -int usb_alloc_streams(struct usb_interface *interface, +:: + + int usb_alloc_streams(struct usb_interface *interface, struct usb_host_endpoint **eps, unsigned int num_eps, unsigned int num_streams, gfp_t mem_flags); @@ -53,7 +58,7 @@ controller driver, and may change in the future. Picking new Stream IDs to use -============================ +============================= Stream ID 0 is reserved, and should not be used to communicate with devices. If usb_alloc_streams() returns with a value of N, you may use streams 1 though N. @@ -68,9 +73,9 @@ Clean up ======== If a driver wishes to stop using streams to communicate with the device, it -should call +should call:: -void usb_free_streams(struct usb_interface *interface, + void usb_free_streams(struct usb_interface *interface, struct usb_host_endpoint **eps, unsigned int num_eps, gfp_t mem_flags); diff --git a/Documentation/usb/callbacks.txt b/Documentation/driver-api/usb/callbacks.rst index 9e85846bdb98..2b80cf54bcc3 100644 --- a/Documentation/usb/callbacks.txt +++ b/Documentation/driver-api/usb/callbacks.rst @@ -1,3 +1,6 @@ +USB core callbacks +~~~~~~~~~~~~~~~~~~ + What callbacks will usbcore do? =============================== @@ -5,40 +8,52 @@ Usbcore will call into a driver through callbacks defined in the driver structure and through the completion handler of URBs a driver submits. Only the former are in the scope of this document. These two kinds of callbacks are completely independent of each other. Information on the -completion callback can be found in Documentation/usb/URB.txt. +completion callback can be found in :ref:`usb-urb`. The callbacks defined in the driver structure are: 1. Hotplugging callbacks: - * @probe: Called to see if the driver is willing to manage a particular - * interface on a device. - * @disconnect: Called when the interface is no longer accessible, usually - * because its device has been (or is being) disconnected or the - * driver module is being unloaded. + - @probe: + Called to see if the driver is willing to manage a particular + interface on a device. + + - @disconnect: + Called when the interface is no longer accessible, usually + because its device has been (or is being) disconnected or the + driver module is being unloaded. 2. Odd backdoor through usbfs: - * @ioctl: Used for drivers that want to talk to userspace through - * the "usbfs" filesystem. This lets devices provide ways to - * expose information to user space regardless of where they - * do (or don't) show up otherwise in the filesystem. + - @ioctl: + Used for drivers that want to talk to userspace through + the "usbfs" filesystem. This lets devices provide ways to + expose information to user space regardless of where they + do (or don't) show up otherwise in the filesystem. 3. Power management (PM) callbacks: - * @suspend: Called when the device is going to be suspended. - * @resume: Called when the device is being resumed. - * @reset_resume: Called when the suspended device has been reset instead - * of being resumed. + - @suspend: + Called when the device is going to be suspended. + + - @resume: + Called when the device is being resumed. + + - @reset_resume: + Called when the suspended device has been reset instead + of being resumed. 4. Device level operations: - * @pre_reset: Called when the device is about to be reset. - * @post_reset: Called after the device has been reset + - @pre_reset: + Called when the device is about to be reset. + + - @post_reset: + Called after the device has been reset The ioctl interface (2) should be used only if you have a very good reason. Sysfs is preferred these days. The PM callbacks are covered -separately in Documentation/usb/power-management.txt. +separately in :ref:`usb-power-management`. Calling conventions =================== @@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive. The probe() callback -------------------- -int (*probe) (struct usb_interface *intf, +:: + + int (*probe) (struct usb_interface *intf, const struct usb_device_id *id); Accept or decline an interface. If you accept the device return 0, @@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here. The disconnect() callback ------------------------- -void (*disconnect) (struct usb_interface *intf); +:: + + void (*disconnect) (struct usb_interface *intf); This callback is a signal to break any connection with an interface. You are not allowed any IO to a device after returning from this @@ -93,7 +112,9 @@ Device level callbacks pre_reset --------- -int (*pre_reset)(struct usb_interface *intf); +:: + + int (*pre_reset)(struct usb_interface *intf); A driver or user space is triggering a reset on the device which contains the interface passed as an argument. Cease IO, wait for all @@ -107,7 +128,9 @@ are in atomic context. post_reset ---------- -int (*post_reset)(struct usb_interface *intf); +:: + + int (*post_reset)(struct usb_interface *intf); The reset has completed. Restore any saved device state and begin using the device again. diff --git a/Documentation/usb/dma.txt b/Documentation/driver-api/usb/dma.rst index 444651e70d95..59d5aee89e37 100644 --- a/Documentation/usb/dma.txt +++ b/Documentation/driver-api/usb/dma.rst @@ -1,16 +1,19 @@ +USB DMA +~~~~~~~ + In Linux 2.5 kernels (and later), USB device drivers have additional control over how DMA may be used to perform I/O operations. The APIs are detailed in the kernel usb programming guide (kerneldoc, from the source code). - -API OVERVIEW +API overview +============ The big picture is that USB drivers can continue to ignore most DMA issues, though they still must provide DMA-ready buffers (see -Documentation/DMA-API-HOWTO.txt). That's how they've worked through -the 2.4 (and earlier) kernels. +``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through +the 2.4 (and earlier) kernels, or they can now be DMA-aware. -OR: they can now be DMA-aware. +DMA-aware usb drivers: - New calls enable DMA-aware drivers, letting them allocate dma buffers and manage dma mappings for existing dma-ready buffers (see below). @@ -20,15 +23,15 @@ OR: they can now be DMA-aware. drivers must not use it.) - "usbcore" will map this DMA address, if a DMA-aware driver didn't do - it first and set URB_NO_TRANSFER_DMA_MAP. HCDs + it first and set ``URB_NO_TRANSFER_DMA_MAP``. HCDs don't manage dma mappings for URBs. - There's a new "generic DMA API", parts of which are usable by USB device drivers. Never use dma_set_mask() on any USB interface or device; that would potentially break all devices sharing that bus. - -ELIMINATING COPIES +Eliminating copies +================== It's good to avoid making CPUs copy data needlessly. The costs can add up, and effects like cache-trashing can impose subtle penalties. @@ -41,7 +44,7 @@ and effects like cache-trashing can impose subtle penalties. For those specific cases, USB has primitives to allocate less expensive memory. They work like kmalloc and kfree versions that give you the right kind of addresses to store in urb->transfer_buffer and urb->transfer_dma. - You'd also set URB_NO_TRANSFER_DMA_MAP in urb->transfer_flags: + You'd also set ``URB_NO_TRANSFER_DMA_MAP`` in urb->transfer_flags:: void *usb_alloc_coherent (struct usb_device *dev, size_t size, int mem_flags, dma_addr_t *dma); @@ -49,15 +52,15 @@ and effects like cache-trashing can impose subtle penalties. void usb_free_coherent (struct usb_device *dev, size_t size, void *addr, dma_addr_t dma); - Most drivers should *NOT* be using these primitives; they don't need + Most drivers should **NOT** be using these primitives; they don't need to use this type of memory ("dma-coherent"), and memory returned from - kmalloc() will work just fine. + :c:func:`kmalloc` will work just fine. The memory buffer returned is "dma-coherent"; sometimes you might need to force a consistent memory access ordering by using memory barriers. It's not using a streaming DMA mapping, so it's good for small transfers on systems where the I/O would otherwise thrash an IOMMU mapping. (See - Documentation/DMA-API-HOWTO.txt for definitions of "coherent" and + ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and "streaming" DMA mappings.) Asking for 1/Nth of a page (as well as asking for N pages) is reasonably @@ -75,15 +78,15 @@ and effects like cache-trashing can impose subtle penalties. way to expose these capabilities ... and in any case, HIGHMEM is mostly a design wart specific to x86_32. So your best bet is to ensure you never pass a highmem buffer into a USB driver. That's easy; it's the default - behavior. Just don't override it; e.g. with NETIF_F_HIGHDMA. + behavior. Just don't override it; e.g. with ``NETIF_F_HIGHDMA``. This may force your callers to do some bounce buffering, copying from high memory to "normal" DMA memory. If you can come up with a good way to fix this issue (for x86_32 machines with over 1 GByte of memory), feel free to submit patches. - -WORKING WITH EXISTING BUFFERS +Working with existing buffers +============================= Existing buffers aren't usable for DMA without first being mapped into the DMA address space of the device. However, most buffers passed to your @@ -92,7 +95,7 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") - When you're using scatterlists, you can map everything at once. On some systems, this kicks in an IOMMU and turns the scatterlists into single - DMA transactions: + DMA transactions:: int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe, struct scatterlist *sg, int nents); @@ -103,7 +106,7 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe, struct scatterlist *sg, int n_hw_ents); - It's probably easier to use the new usb_sg_*() calls, which do the DMA + It's probably easier to use the new ``usb_sg_*()`` calls, which do the DMA mapping and apply other tweaks to make scatterlist i/o be fast. - Some drivers may prefer to work with the model that they're mapping large @@ -112,10 +115,10 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") here, since it's cheaper to just synchronize the buffer than to unmap it each time an urb completes and then re-map it on during resubmission. - These calls all work with initialized urbs: urb->dev, urb->pipe, - urb->transfer_buffer, and urb->transfer_buffer_length must all be - valid when these calls are used (urb->setup_packet must be valid too - if urb is a control request): + These calls all work with initialized urbs: ``urb->dev``, ``urb->pipe``, + ``urb->transfer_buffer``, and ``urb->transfer_buffer_length`` must all be + valid when these calls are used (``urb->setup_packet`` must be valid too + if urb is a control request):: struct urb *usb_buffer_map (struct urb *urb); @@ -123,9 +126,9 @@ of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") void usb_buffer_unmap (struct urb *urb); - The calls manage urb->transfer_dma for you, and set URB_NO_TRANSFER_DMA_MAP - so that usbcore won't map or unmap the buffer. They cannot be used for - setup_packet buffers in control requests. + The calls manage ``urb->transfer_dma`` for you, and set + ``URB_NO_TRANSFER_DMA_MAP`` so that usbcore won't map or unmap the buffer. + They cannot be used for setup_packet buffers in control requests. Note that several of those interfaces are currently commented out, since they don't have current users. See the source code. Other than the dmasync diff --git a/Documentation/driver-api/usb/error-codes.rst b/Documentation/driver-api/usb/error-codes.rst new file mode 100644 index 000000000000..a3e84bfac776 --- /dev/null +++ b/Documentation/driver-api/usb/error-codes.rst @@ -0,0 +1,207 @@ +.. _usb-error-codes: + +USB Error codes +~~~~~~~~~~~~~~~ + +:Revised: 2004-Oct-21 + +This is the documentation of (hopefully) all possible error codes (and +their interpretation) that can be returned from usbcore. + +Some of them are returned by the Host Controller Drivers (HCDs), which +device drivers only see through usbcore. As a rule, all the HCDs should +behave the same except for transfer speed dependent behaviors and the +way certain faults are reported. + + +Error codes returned by :c:func:`usb_submit_urb` +================================================ + +Non-USB-specific: + + +=============== =============================================== +0 URB submission went fine + +``-ENOMEM`` no memory for allocation of internal structures +=============== =============================================== + +USB-specific: + +======================= ======================================================= +``-EBUSY`` The URB is already active. + +``-ENODEV`` specified USB-device or bus doesn't exist + +``-ENOENT`` specified interface or endpoint does not exist or + is not enabled + +``-ENXIO`` host controller driver does not support queuing of + this type of urb. (treat as a host controller bug.) + +``-EINVAL`` a) Invalid transfer type specified (or not supported) + b) Invalid or unsupported periodic transfer interval + c) ISO: attempted to change transfer interval + d) ISO: ``number_of_packets`` is < 0 + e) various other cases + +``-EXDEV`` ISO: ``URB_ISO_ASAP`` wasn't specified and all the + frames the URB would be scheduled in have already + expired. + +``-EFBIG`` Host controller driver can't schedule that many ISO + frames. + +``-EPIPE`` The pipe type specified in the URB doesn't match the + endpoint's actual type. + +``-EMSGSIZE`` (a) endpoint maxpacket size is zero; it is not usable + in the current interface altsetting. + (b) ISO packet is larger than the endpoint maxpacket. + (c) requested data transfer length is invalid: negative + or too large for the host controller. + +``-ENOSPC`` This request would overcommit the usb bandwidth reserved + for periodic transfers (interrupt, isochronous). + +``-ESHUTDOWN`` The device or host controller has been disabled due to + some problem that could not be worked around. + +``-EPERM`` Submission failed because ``urb->reject`` was set. + +``-EHOSTUNREACH`` URB was rejected because the device is suspended. + +``-ENOEXEC`` A control URB doesn't contain a Setup packet. +======================= ======================================================= + +Error codes returned by ``in urb->status`` or in ``iso_frame_desc[n].status`` (for ISO) +======================================================================================= + +USB device drivers may only test urb status values in completion handlers. +This is because otherwise there would be a race between HCDs updating +these values on one CPU, and device drivers testing them on another CPU. + +A transfer's actual_length may be positive even when an error has been +reported. That's because transfers often involve several packets, so that +one or more packets could finish before an error stops further endpoint I/O. + +For isochronous URBs, the urb status value is non-zero only if the URB is +unlinked, the device is removed, the host controller is disabled, or the total +transferred length is less than the requested length and the +``URB_SHORT_NOT_OK`` flag is set. Completion handlers for isochronous URBs +should only see ``urb->status`` set to zero, ``-ENOENT``, ``-ECONNRESET``, +``-ESHUTDOWN``, or ``-EREMOTEIO``. Individual frame descriptor status fields +may report more status codes. + + +=============================== =============================================== +0 Transfer completed successfully + +``-ENOENT`` URB was synchronously unlinked by + :c:func:`usb_unlink_urb` + +``-EINPROGRESS`` URB still pending, no results yet + (That is, if drivers see this it's a bug.) + +``-EPROTO`` [#f1]_, [#f2]_ a) bitstuff error + b) no response packet received within the + prescribed bus turn-around time + c) unknown USB error + +``-EILSEQ`` [#f1]_, [#f2]_ a) CRC mismatch + b) no response packet received within the + prescribed bus turn-around time + c) unknown USB error + + Note that often the controller hardware does + not distinguish among cases a), b), and c), so + a driver cannot tell whether there was a + protocol error, a failure to respond (often + caused by device disconnect), or some other + fault. + +``-ETIME`` [#f2]_ No response packet received within the + prescribed bus turn-around time. This error + may instead be reported as + ``-EPROTO`` or ``-EILSEQ``. + +``-ETIMEDOUT`` Synchronous USB message functions use this code + to indicate timeout expired before the transfer + completed, and no other error was reported + by HC. + +``-EPIPE`` [#f2]_ Endpoint stalled. For non-control endpoints, + reset this status with + :c:func:`usb_clear_halt`. + +``-ECOMM`` During an IN transfer, the host controller + received data from an endpoint faster than it + could be written to system memory + +``-ENOSR`` During an OUT transfer, the host controller + could not retrieve data from system memory fast + enough to keep up with the USB data rate + +``-EOVERFLOW`` [#f1]_ The amount of data returned by the endpoint was + greater than either the max packet size of the + endpoint or the remaining buffer size. + "Babble". + +``-EREMOTEIO`` The data read from the endpoint did not fill + the specified buffer, and ``URB_SHORT_NOT_OK`` + was set in ``urb->transfer_flags``. + +``-ENODEV`` Device was removed. Often preceded by a burst + of other errors, since the hub driver doesn't + detect device removal events immediately. + +``-EXDEV`` ISO transfer only partially completed + (only set in ``iso_frame_desc[n].status``, + not ``urb->status``) + +``-EINVAL`` ISO madness, if this happens: Log off and + go home + +``-ECONNRESET`` URB was asynchronously unlinked by + :c:func:`usb_unlink_urb` + +``-ESHUTDOWN`` The device or host controller has been + disabled due to some problem that could not + be worked around, such as a physical + disconnect. +=============================== =============================================== + + +.. [#f1] + + Error codes like ``-EPROTO``, ``-EILSEQ`` and ``-EOVERFLOW`` normally + indicate hardware problems such as bad devices (including firmware) + or cables. + +.. [#f2] + + This is also one of several codes that different kinds of host + controller use to indicate a transfer has failed because of device + disconnect. In the interval before the hub driver starts disconnect + processing, devices may receive such fault reports for every request. + + + +Error codes returned by usbcore-functions +========================================= + +.. note:: expect also other submit and transfer status codes + +:c:func:`usb_register`: + +======================= =================================== +``-EINVAL`` error during registering new driver +======================= =================================== + +``usb_get_*/usb_set_*()``, +:c:func:`usb_control_msg`, +:c:func:`usb_bulk_msg()`: + +======================= ============================================== +``-ETIMEDOUT`` Timeout expired before the transfer completed. +======================= ============================================== diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst new file mode 100644 index 000000000000..3e8a3809c0b8 --- /dev/null +++ b/Documentation/driver-api/usb/gadget.rst @@ -0,0 +1,510 @@ +======================== +USB Gadget API for Linux +======================== + +:Author: David Brownell +:Date: 20 August 2004 + +Introduction +============ + +This document presents a Linux-USB "Gadget" kernel mode API, for use +within peripherals and other USB devices that embed Linux. It provides +an overview of the API structure, and shows how that fits into a system +development project. This is the first such API released on Linux to +address a number of important problems, including: + +- Supports USB 2.0, for high speed devices which can stream data at + several dozen megabytes per second. + +- Handles devices with dozens of endpoints just as well as ones with + just two fixed-function ones. Gadget drivers can be written so + they're easy to port to new hardware. + +- Flexible enough to expose more complex USB device capabilities such + as multiple configurations, multiple interfaces, composite devices, + and alternate interface settings. + +- USB "On-The-Go" (OTG) support, in conjunction with updates to the + Linux-USB host side. + +- Sharing data structures and API models with the Linux-USB host side + API. This helps the OTG support, and looks forward to more-symmetric + frameworks (where the same I/O model is used by both host and device + side drivers). + +- Minimalist, so it's easier to support new device controller hardware. + I/O processing doesn't imply large demands for memory or CPU + resources. + +Most Linux developers will not be able to use this API, since they have +USB ``host`` hardware in a PC, workstation, or server. Linux users with +embedded systems are more likely to have USB peripheral hardware. To +distinguish drivers running inside such hardware from the more familiar +Linux "USB device drivers", which are host side proxies for the real USB +devices, a different term is used: the drivers inside the peripherals +are "USB gadget drivers". In USB protocol interactions, the device +driver is the master (or "client driver") and the gadget driver is the +slave (or "function driver"). + +The gadget API resembles the host side Linux-USB API in that both use +queues of request objects to package I/O buffers, and those requests may +be submitted or canceled. They share common definitions for the standard +USB *Chapter 9* messages, structures, and constants. Also, both APIs +bind and unbind drivers to devices. The APIs differ in detail, since the +host side's current URB framework exposes a number of implementation +details and assumptions that are inappropriate for a gadget API. While +the model for control transfers and configuration management is +necessarily different (one side is a hardware-neutral master, the other +is a hardware-aware slave), the endpoint I/0 API used here should also +be usable for an overhead-reduced host side API. + +Structure of Gadget Drivers +=========================== + +A system running inside a USB peripheral normally has at least three +layers inside the kernel to handle USB protocol processing, and may have +additional layers in user space code. The ``gadget`` API is used by the +middle layer to interact with the lowest level (which directly handles +hardware). + +In Linux, from the bottom up, these layers are: + +*USB Controller Driver* + This is the lowest software level. It is the only layer that talks + to hardware, through registers, fifos, dma, irqs, and the like. The + ``<linux/usb/gadget.h>`` API abstracts the peripheral controller + endpoint hardware. That hardware is exposed through endpoint + objects, which accept streams of IN/OUT buffers, and through + callbacks that interact with gadget drivers. Since normal USB + devices only have one upstream port, they only have one of these + drivers. The controller driver can support any number of different + gadget drivers, but only one of them can be used at a time. + + Examples of such controller hardware include the PCI-based NetChip + 2280 USB 2.0 high speed controller, the SA-11x0 or PXA-25x UDC + (found within many PDAs), and a variety of other products. + +*Gadget Driver* + The lower boundary of this driver implements hardware-neutral USB + functions, using calls to the controller driver. Because such + hardware varies widely in capabilities and restrictions, and is used + in embedded environments where space is at a premium, the gadget + driver is often configured at compile time to work with endpoints + supported by one particular controller. Gadget drivers may be + portable to several different controllers, using conditional + compilation. (Recent kernels substantially simplify the work + involved in supporting new hardware, by *autoconfiguring* endpoints + automatically for many bulk-oriented drivers.) Gadget driver + responsibilities include: + + - handling setup requests (ep0 protocol responses) possibly + including class-specific functionality + + - returning configuration and string descriptors + + - (re)setting configurations and interface altsettings, including + enabling and configuring endpoints + + - handling life cycle events, such as managing bindings to + hardware, USB suspend/resume, remote wakeup, and disconnection + from the USB host. + + - managing IN and OUT transfers on all currently enabled endpoints + + Such drivers may be modules of proprietary code, although that + approach is discouraged in the Linux community. + +*Upper Level* + Most gadget drivers have an upper boundary that connects to some + Linux driver or framework in Linux. Through that boundary flows the + data which the gadget driver produces and/or consumes through + protocol transfers over USB. Examples include: + + - user mode code, using generic (gadgetfs) or application specific + files in ``/dev`` + + - networking subsystem (for network gadgets, like the CDC Ethernet + Model gadget driver) + + - data capture drivers, perhaps video4Linux or a scanner driver; or + test and measurement hardware. + + - input subsystem (for HID gadgets) + + - sound subsystem (for audio gadgets) + + - file system (for PTP gadgets) + + - block i/o subsystem (for usb-storage gadgets) + + - ... and more + +*Additional Layers* + Other layers may exist. These could include kernel layers, such as + network protocol stacks, as well as user mode applications building + on standard POSIX system call APIs such as ``open()``, ``close()``, + ``read()`` and ``write()``. On newer systems, POSIX Async I/O calls may + be an option. Such user mode code will not necessarily be subject to + the GNU General Public License (GPL). + +OTG-capable systems will also need to include a standard Linux-USB host +side stack, with ``usbcore``, one or more *Host Controller Drivers* +(HCDs), *USB Device Drivers* to support the OTG "Targeted Peripheral +List", and so forth. There will also be an *OTG Controller Driver*, +which is visible to gadget and device driver developers only indirectly. +That helps the host and device side USB controllers implement the two +new OTG protocols (HNP and SRP). Roles switch (host to peripheral, or +vice versa) using HNP during USB suspend processing, and SRP can be +viewed as a more battery-friendly kind of device wakeup protocol. + +Over time, reusable utilities are evolving to help make some gadget +driver tasks simpler. For example, building configuration descriptors +from vectors of descriptors for the configurations interfaces and +endpoints is now automated, and many drivers now use autoconfiguration +to choose hardware endpoints and initialize their descriptors. A +potential example of particular interest is code implementing standard +USB-IF protocols for HID, networking, storage, or audio classes. Some +developers are interested in KDB or KGDB hooks, to let target hardware +be remotely debugged. Most such USB protocol code doesn't need to be +hardware-specific, any more than network protocols like X11, HTTP, or +NFS are. Such gadget-side interface drivers should eventually be +combined, to implement composite devices. + +Kernel Mode Gadget API +====================== + +Gadget drivers declare themselves through a struct +:c:type:`usb_gadget_driver`, which is responsible for most parts of enumeration +for a struct :c:type:`usb_gadget`. The response to a set_configuration usually +involves enabling one or more of the struct :c:type:`usb_ep` objects exposed by +the gadget, and submitting one or more struct :c:type:`usb_request` buffers to +transfer data. Understand those four data types, and their operations, +and you will understand how this API works. + +.. Note:: + + Other than the "Chapter 9" data types, most of the significant data + types and functions are described here. + + However, some relevant information is likely omitted from what you + are reading. One example of such information is endpoint + autoconfiguration. You'll have to read the header file, and use + example source code (such as that for "Gadget Zero"), to fully + understand the API. + + The part of the API implementing some basic driver capabilities is + specific to the version of the Linux kernel that's in use. The 2.6 + and upper kernel versions include a *driver model* framework that has + no analogue on earlier kernels; so those parts of the gadget API are + not fully portable. (They are implemented on 2.4 kernels, but in a + different way.) The driver model state is another part of this API that is + ignored by the kerneldoc tools. + +The core API does not expose every possible hardware feature, only the +most widely available ones. There are significant hardware features, +such as device-to-device DMA (without temporary storage in a memory +buffer) that would be added using hardware-specific APIs. + +This API allows drivers to use conditional compilation to handle +endpoint capabilities of different hardware, but doesn't require that. +Hardware tends to have arbitrary restrictions, relating to transfer +types, addressing, packet sizes, buffering, and availability. As a rule, +such differences only matter for "endpoint zero" logic that handles +device configuration and management. The API supports limited run-time +detection of capabilities, through naming conventions for endpoints. +Many drivers will be able to at least partially autoconfigure +themselves. In particular, driver init sections will often have endpoint +autoconfiguration logic that scans the hardware's list of endpoints to +find ones matching the driver requirements (relying on those +conventions), to eliminate some of the most common reasons for +conditional compilation. + +Like the Linux-USB host side API, this API exposes the "chunky" nature +of USB messages: I/O requests are in terms of one or more "packets", and +packet boundaries are visible to drivers. Compared to RS-232 serial +protocols, USB resembles synchronous protocols like HDLC (N bytes per +frame, multipoint addressing, host as the primary station and devices as +secondary stations) more than asynchronous ones (tty style: 8 data bits +per frame, no parity, one stop bit). So for example the controller +drivers won't buffer two single byte writes into a single two-byte USB +IN packet, although gadget drivers may do so when they implement +protocols where packet boundaries (and "short packets") are not +significant. + +Driver Life Cycle +----------------- + +Gadget drivers make endpoint I/O requests to hardware without needing to +know many details of the hardware, but driver setup/configuration code +needs to handle some differences. Use the API like this: + +1. Register a driver for the particular device side usb controller + hardware, such as the net2280 on PCI (USB 2.0), sa11x0 or pxa25x as + found in Linux PDAs, and so on. At this point the device is logically + in the USB ch9 initial state (``attached``), drawing no power and not + usable (since it does not yet support enumeration). Any host should + not see the device, since it's not activated the data line pullup + used by the host to detect a device, even if VBUS power is available. + +2. Register a gadget driver that implements some higher level device + function. That will then bind() to a :c:type:`usb_gadget`, which activates + the data line pullup sometime after detecting VBUS. + +3. The hardware driver can now start enumerating. The steps it handles + are to accept USB ``power`` and ``set_address`` requests. Other steps are + handled by the gadget driver. If the gadget driver module is unloaded + before the host starts to enumerate, steps before step 7 are skipped. + +4. The gadget driver's ``setup()`` call returns usb descriptors, based both + on what the bus interface hardware provides and on the functionality + being implemented. That can involve alternate settings or + configurations, unless the hardware prevents such operation. For OTG + devices, each configuration descriptor includes an OTG descriptor. + +5. The gadget driver handles the last step of enumeration, when the USB + host issues a ``set_configuration`` call. It enables all endpoints used + in that configuration, with all interfaces in their default settings. + That involves using a list of the hardware's endpoints, enabling each + endpoint according to its descriptor. It may also involve using + ``usb_gadget_vbus_draw`` to let more power be drawn from VBUS, as + allowed by that configuration. For OTG devices, setting a + configuration may also involve reporting HNP capabilities through a + user interface. + +6. Do real work and perform data transfers, possibly involving changes + to interface settings or switching to new configurations, until the + device is disconnect()ed from the host. Queue any number of transfer + requests to each endpoint. It may be suspended and resumed several + times before being disconnected. On disconnect, the drivers go back + to step 3 (above). + +7. When the gadget driver module is being unloaded, the driver unbind() + callback is issued. That lets the controller driver be unloaded. + +Drivers will normally be arranged so that just loading the gadget driver +module (or statically linking it into a Linux kernel) allows the +peripheral device to be enumerated, but some drivers will defer +enumeration until some higher level component (like a user mode daemon) +enables it. Note that at this lowest level there are no policies about +how ep0 configuration logic is implemented, except that it should obey +USB specifications. Such issues are in the domain of gadget drivers, +including knowing about implementation constraints imposed by some USB +controllers or understanding that composite devices might happen to be +built by integrating reusable components. + +Note that the lifecycle above can be slightly different for OTG devices. +Other than providing an additional OTG descriptor in each configuration, +only the HNP-related differences are particularly visible to driver +code. They involve reporting requirements during the ``SET_CONFIGURATION`` +request, and the option to invoke HNP during some suspend callbacks. +Also, SRP changes the semantics of ``usb_gadget_wakeup`` slightly. + +USB 2.0 Chapter 9 Types and Constants +------------------------------------- + +Gadget drivers rely on common USB structures and constants defined in +the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in +Linux 2.6+ kernels. These are the same types and constants used by host side +drivers (and usbcore). + +Core Objects and Methods +------------------------ + +These are declared in ``<linux/usb/gadget.h>``, and are used by gadget +drivers to interact with USB peripheral controller drivers. + +.. kernel-doc:: include/linux/usb/gadget.h + :internal: + +Optional Utilities +------------------ + +The core API is sufficient for writing a USB Gadget Driver, but some +optional utilities are provided to simplify common tasks. These +utilities include endpoint autoconfiguration. + +.. kernel-doc:: drivers/usb/gadget/usbstring.c + :export: + +.. kernel-doc:: drivers/usb/gadget/config.c + :export: + +Composite Device Framework +-------------------------- + +The core API is sufficient for writing drivers for composite USB devices +(with more than one function in a given configuration), and also +multi-configuration devices (also more than one function, but not +necessarily sharing a given configuration). There is however an optional +framework which makes it easier to reuse and combine functions. + +Devices using this framework provide a struct :c:type:`usb_composite_driver`, +which in turn provides one or more struct :c:type:`usb_configuration` +instances. Each such configuration includes at least one struct +:c:type:`usb_function`, which packages a user visible role such as "network +link" or "mass storage device". Management functions may also exist, +such as "Device Firmware Upgrade". + +.. kernel-doc:: include/linux/usb/composite.h + :internal: + +.. kernel-doc:: drivers/usb/gadget/composite.c + :export: + +Composite Device Functions +-------------------------- + +At this writing, a few of the current gadget drivers have been converted +to this framework. Near-term plans include converting all of them, +except for ``gadgetfs``. + +Peripheral Controller Drivers +============================= + +The first hardware supporting this API was the NetChip 2280 controller, +which supports USB 2.0 high speed and is based on PCI. This is the +``net2280`` driver module. The driver supports Linux kernel versions 2.4 +and 2.6; contact NetChip Technologies for development boards and product +information. + +Other hardware working in the ``gadget`` framework includes: Intel's PXA +25x and IXP42x series processors (``pxa2xx_udc``), Toshiba TC86c001 +"Goku-S" (``goku_udc``), Renesas SH7705/7727 (``sh_udc``), MediaQ 11xx +(``mq11xx_udc``), Hynix HMS30C7202 (``h7202_udc``), National 9303/4 +(``n9604_udc``), Texas Instruments OMAP (``omap_udc``), Sharp LH7A40x +(``lh7a40x_udc``), and more. Most of those are full speed controllers. + +At this writing, there are people at work on drivers in this framework +for several other USB device controllers, with plans to make many of +them be widely available. + +A partial USB simulator, the ``dummy_hcd`` driver, is available. It can +act like a net2280, a pxa25x, or an sa11x0 in terms of available +endpoints and device speeds; and it simulates control, bulk, and to some +extent interrupt transfers. That lets you develop some parts of a gadget +driver on a normal PC, without any special hardware, and perhaps with +the assistance of tools such as GDB running with User Mode Linux. At +least one person has expressed interest in adapting that approach, +hooking it up to a simulator for a microcontroller. Such simulators can +help debug subsystems where the runtime hardware is unfriendly to +software development, or is not yet available. + +Support for other controllers is expected to be developed and +contributed over time, as this driver framework evolves. + +Gadget Drivers +============== + +In addition to *Gadget Zero* (used primarily for testing and development +with drivers for usb controller hardware), other gadget drivers exist. + +There's an ``ethernet`` gadget driver, which implements one of the most +useful *Communications Device Class* (CDC) models. One of the standards +for cable modem interoperability even specifies the use of this ethernet +model as one of two mandatory options. Gadgets using this code look to a +USB host as if they're an Ethernet adapter. It provides access to a +network where the gadget's CPU is one host, which could easily be +bridging, routing, or firewalling access to other networks. Since some +hardware can't fully implement the CDC Ethernet requirements, this +driver also implements a "good parts only" subset of CDC Ethernet. (That +subset doesn't advertise itself as CDC Ethernet, to avoid creating +problems.) + +Support for Microsoft's ``RNDIS`` protocol has been contributed by +Pengutronix and Auerswald GmbH. This is like CDC Ethernet, but it runs +on more slightly USB hardware (but less than the CDC subset). However, +its main claim to fame is being able to connect directly to recent +versions of Windows, using drivers that Microsoft bundles and supports, +making it much simpler to network with Windows. + +There is also support for user mode gadget drivers, using ``gadgetfs``. +This provides a *User Mode API* that presents each endpoint as a single +file descriptor. I/O is done using normal ``read()`` and ``read()`` calls. +Familiar tools like GDB and pthreads can be used to develop and debug +user mode drivers, so that once a robust controller driver is available +many applications for it won't require new kernel mode software. Linux +2.6 *Async I/O (AIO)* support is available, so that user mode software +can stream data with only slightly more overhead than a kernel driver. + +There's a USB Mass Storage class driver, which provides a different +solution for interoperability with systems such as MS-Windows and MacOS. +That *Mass Storage* driver uses a file or block device as backing store +for a drive, like the ``loop`` driver. The USB host uses the BBB, CB, or +CBI versions of the mass storage class specification, using transparent +SCSI commands to access the data from the backing store. + +There's a "serial line" driver, useful for TTY style operation over USB. +The latest version of that driver supports CDC ACM style operation, like +a USB modem, and so on most hardware it can interoperate easily with +MS-Windows. One interesting use of that driver is in boot firmware (like +a BIOS), which can sometimes use that model with very small systems +without real serial lines. + +Support for other kinds of gadget is expected to be developed and +contributed over time, as this driver framework evolves. + +USB On-The-GO (OTG) +=================== + +USB OTG support on Linux 2.6 was initially developed by Texas +Instruments for `OMAP <http://www.omap.com>`__ 16xx and 17xx series +processors. Other OTG systems should work in similar ways, but the +hardware level details could be very different. + +Systems need specialized hardware support to implement OTG, notably +including a special *Mini-AB* jack and associated transceiver to support +*Dual-Role* operation: they can act either as a host, using the standard +Linux-USB host side driver stack, or as a peripheral, using this +``gadget`` framework. To do that, the system software relies on small +additions to those programming interfaces, and on a new internal +component (here called an "OTG Controller") affecting which driver stack +connects to the OTG port. In each role, the system can re-use the +existing pool of hardware-neutral drivers, layered on top of the +controller driver interfaces (:c:type:`usb_bus` or :c:type:`usb_gadget`). +Such drivers need at most minor changes, and most of the calls added to +support OTG can also benefit non-OTG products. + +- Gadget drivers test the ``is_otg`` flag, and use it to determine + whether or not to include an OTG descriptor in each of their + configurations. + +- Gadget drivers may need changes to support the two new OTG protocols, + exposed in new gadget attributes such as ``b_hnp_enable`` flag. HNP + support should be reported through a user interface (two LEDs could + suffice), and is triggered in some cases when the host suspends the + peripheral. SRP support can be user-initiated just like remote + wakeup, probably by pressing the same button. + +- On the host side, USB device drivers need to be taught to trigger HNP + at appropriate moments, using ``usb_suspend_device()``. That also + conserves battery power, which is useful even for non-OTG + configurations. + +- Also on the host side, a driver must support the OTG "Targeted + Peripheral List". That's just a whitelist, used to reject peripherals + not supported with a given Linux OTG host. *This whitelist is + product-specific; each product must modify* ``otg_whitelist.h`` *to + match its interoperability specification.* + + Non-OTG Linux hosts, like PCs and workstations, normally have some + solution for adding drivers, so that peripherals that aren't + recognized can eventually be supported. That approach is unreasonable + for consumer products that may never have their firmware upgraded, + and where it's usually unrealistic to expect traditional + PC/workstation/server kinds of support model to work. For example, + it's often impractical to change device firmware once the product has + been distributed, so driver bugs can't normally be fixed if they're + found after shipment. + +Additional changes are needed below those hardware-neutral :c:type:`usb_bus` +and :c:type:`usb_gadget` driver interfaces; those aren't discussed here in any +detail. Those affect the hardware-specific code for each USB Host or +Peripheral controller, and how the HCD initializes (since OTG can be +active only on a single port). They also involve what may be called an +*OTG Controller Driver*, managing the OTG transceiver and the OTG state +machine logic as well as much of the root hub behavior for the OTG port. +The OTG controller driver needs to activate and deactivate USB +controllers depending on the relevant device role. Some related changes +were needed inside usbcore, so that it can identify OTG-capable devices +and respond appropriately to HNP or SRP protocols. diff --git a/Documentation/usb/hotplug.txt b/Documentation/driver-api/usb/hotplug.rst index 5b243f315b2c..79663e653ca1 100644 --- a/Documentation/usb/hotplug.txt +++ b/Documentation/driver-api/usb/hotplug.rst @@ -1,4 +1,9 @@ -LINUX HOTPLUGGING +USB hotplugging +~~~~~~~~~~~~~~~ + +Linux Hotplugging +================= + In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices into the bus with power on. In most cases, users expect the devices to become @@ -30,11 +35,11 @@ Because some of those actions rely on information about drivers (metadata) that is currently available only when the drivers are dynamically linked, you get the best hotplugging when you configure a highly modular system. +Kernel Hotplug Helper (``/sbin/hotplug``) +========================================= -KERNEL HOTPLUG HELPER (/sbin/hotplug) - -There is a kernel parameter: /proc/sys/kernel/hotplug, which normally -holds the pathname "/sbin/hotplug". That parameter names a program +There is a kernel parameter: ``/proc/sys/kernel/hotplug``, which normally +holds the pathname ``/sbin/hotplug``. That parameter names a program which the kernel may invoke at various times. The /sbin/hotplug program can be invoked by any subsystem as part of its @@ -51,26 +56,26 @@ Hotplug software and other resources is available at: Mailing list information is also available at that site. --------------------------------------------------------------------------- - +USB Policy Agent +================ -USB POLICY AGENT - -The USB subsystem currently invokes /sbin/hotplug when USB devices +The USB subsystem currently invokes ``/sbin/hotplug`` when USB devices are added or removed from system. The invocation is done by the kernel hub workqueue [hub_wq], or else as part of root hub initialization (done by init, modprobe, kapmd, etc). Its single command line parameter is the string "usb", and it passes these environment variables: - ACTION ... "add", "remove" - PRODUCT ... USB vendor, product, and version codes (hex) - TYPE ... device class codes (decimal) - INTERFACE ... interface 0 class codes (decimal) +========== ============================================ +ACTION ``add``, ``remove`` +PRODUCT USB vendor, product, and version codes (hex) +TYPE device class codes (decimal) +INTERFACE interface 0 class codes (decimal) +========== ============================================ If "usbdevfs" is configured, DEVICE and DEVFS are also passed. DEVICE is the pathname of the device, and is useful for devices with multiple and/or alternate interfaces that complicate driver selection. By design, USB -hotplugging is independent of "usbdevfs": you can do most essential parts +hotplugging is independent of ``usbdevfs``: you can do most essential parts of USB device setup without using that filesystem, and without running a user mode daemon to detect changes in system configuration. @@ -79,19 +84,20 @@ modules, and can invoke driver-specific setup scripts. The newest ones leverage USB module-init-tools support. Later agents might unload drivers. -USB MODUTILS SUPPORT +USB Modutils Support +==================== -Current versions of module-init-tools will create a "modules.usbmap" file -which contains the entries from each driver's MODULE_DEVICE_TABLE. Such +Current versions of module-init-tools will create a ``modules.usbmap`` file +which contains the entries from each driver's ``MODULE_DEVICE_TABLE``. Such files can be used by various user mode policy agents to make sure all the right driver modules get loaded, either at boot time or later. -See <linux/usb.h> for full information about such table entries; or look +See ``linux/usb.h`` for full information about such table entries; or look at existing drivers. Each table entry describes one or more criteria to be used when matching a driver to a device or class of devices. The specific criteria are identified by bits set in "match_flags", paired with field values. You can construct the criteria directly, or with -macros such as these, and use driver_info to store more information. +macros such as these, and use driver_info to store more information:: USB_DEVICE (vendorId, productId) ... matching devices with specified vendor and product ids @@ -103,7 +109,7 @@ macros such as these, and use driver_info to store more information. ... matching specified device class info A short example, for a driver that supports several specific USB devices -and their quirks, might have a MODULE_DEVICE_TABLE like this: +and their quirks, might have a MODULE_DEVICE_TABLE like this:: static const struct usb_device_id mydriver_id_table[] = { { USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X }, @@ -116,10 +122,10 @@ and their quirks, might have a MODULE_DEVICE_TABLE like this: Most USB device drivers should pass these tables to the USB subsystem as well as to the module management subsystem. Not all, though: some driver frameworks connect using interfaces layered over USB, and so they won't -need such a "struct usb_driver". +need such a struct :c:type:`usb_driver`. Drivers that connect directly to the USB subsystem should be declared -something like this: +something like this:: static struct usb_driver mydriver = { .name = "mydriver", @@ -138,11 +144,11 @@ something like this: When the USB subsystem knows about a driver's device ID table, it's used when choosing drivers to probe(). The thread doing new device processing checks -drivers' device ID entries from the MODULE_DEVICE_TABLE against interface and -device descriptors for the device. It will only call probe() if there is a -match, and the third argument to probe() will be the entry that matched. - -If you don't provide an id_table for your driver, then your driver may get -probed for each new device; the third parameter to probe() will be null. - - +drivers' device ID entries from the ``MODULE_DEVICE_TABLE`` against interface +and device descriptors for the device. It will only call ``probe()`` if there +is a match, and the third argument to ``probe()`` will be the entry that +matched. + +If you don't provide an ``id_table`` for your driver, then your driver may get +probed for each new device; the third parameter to ``probe()`` will be +``NULL``. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst new file mode 100644 index 000000000000..1bf64edc8c8a --- /dev/null +++ b/Documentation/driver-api/usb/index.rst @@ -0,0 +1,26 @@ +============= +Linux USB API +============= + +.. toctree:: + + usb + gadget + anchors + bulk-streams + callbacks + dma + URB + power-management + hotplug + persist + error-codes + writing_usb_driver + writing_musb_glue_layer + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/usb/persist.txt b/Documentation/driver-api/usb/persist.rst index 35d70eda9ad6..08cafc6292c1 100644 --- a/Documentation/usb/persist.txt +++ b/Documentation/driver-api/usb/persist.rst @@ -1,11 +1,14 @@ - USB device persistence during system suspend +.. _usb-persist: - Alan Stern <stern@rowland.harvard.edu> +USB device persistence during system suspend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - September 2, 2006 (Updated February 25, 2008) +:Author: Alan Stern <stern@rowland.harvard.edu> +:Date: September 2, 2006 (Updated February 25, 2008) - What is the problem? +What is the problem? +==================== According to the USB specification, when a USB bus is suspended the bus must continue to supply suspend current (around 1-5 mA). This @@ -63,7 +66,8 @@ suspended -- but it will crash as soon as it wakes up, which isn't much better.) - What is the solution? +What is the solution? +===================== The kernel includes a feature called USB-persist. It tries to work around these issues by allowing the core USB device data structures to @@ -99,7 +103,7 @@ now a good and happy place. Note that the "USB-persist" feature will be applied only to those devices for which it is enabled. You can enable the feature by doing -(as root): +(as root):: echo 1 >/sys/bus/usb/devices/.../power/persist @@ -110,7 +114,8 @@ doesn't even exist, so you only have to worry about setting it for devices where it really matters. - Is this the best solution? +Is this the best solution? +========================== Perhaps not. Arguably, keeping track of mounted filesystems and memory mappings across device disconnects should be handled by a @@ -130,7 +135,8 @@ just mass-storage devices. It might turn out to be equally useful for other device types, such as network interfaces. - WARNING: USB-persist can be dangerous!! +WARNING: USB-persist can be dangerous!! +======================================= When recovering an interrupted power session the kernel does its best to make sure the USB device hasn't been changed; that is, the same diff --git a/Documentation/usb/power-management.txt b/Documentation/driver-api/usb/power-management.rst index 00e706997130..79beb807996b 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/driver-api/usb/power-management.rst @@ -1,10 +1,12 @@ - Power Management for USB +.. _usb-power-management: - Alan Stern <stern@rowland.harvard.edu> - - Last-updated: February 2014 +Power Management for USB +~~~~~~~~~~~~~~~~~~~~~~~~ +:Author: Alan Stern <stern@rowland.harvard.edu> +:Date: Last-updated: February 2014 +.. Contents: --------- * What is Power Management? @@ -25,14 +27,14 @@ * Suggested Userspace Port Power Policy - What is Power Management? - ------------------------- +What is Power Management? +------------------------- Power Management (PM) is the practice of saving energy by suspending parts of a computer system when they aren't being used. While a -component is "suspended" it is in a nonfunctional low-power state; it +component is ``suspended`` it is in a nonfunctional low-power state; it might even be turned off completely. A suspended component can be -"resumed" (returned to a functional full-power state) when the kernel +``resumed`` (returned to a functional full-power state) when the kernel needs to use it. (There also are forms of PM in which components are placed in a less functional but still usable state instead of being suspended; an example would be reducing the CPU's clock rate. This @@ -44,22 +46,25 @@ 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/*.txt`` for more information about system PM). -System PM support is present only if the kernel was built with CONFIG_SUSPEND -or CONFIG_HIBERNATION enabled. Dynamic PM support for USB is present whenever -the kernel was built with CONFIG_PM enabled. +System PM support is present only if the kernel was built with +``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled. Dynamic PM support + +for USB is present whenever +the kernel was built with ``CONFIG_PM`` enabled. [Historically, dynamic PM support for USB was present only if the -kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on -CONFIG_PM_RUNTIME). Starting with the 3.10 kernel release, dynamic PM support -for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME -enabled. The CONFIG_USB_SUSPEND option had been eliminated.] +kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on +``CONFIG_PM_RUNTIME``). Starting with the 3.10 kernel release, dynamic PM +support for USB was present whenever the kernel was built with +``CONFIG_PM_RUNTIME`` enabled. The ``CONFIG_USB_SUSPEND`` option had been +eliminated.] - What is Remote Wakeup? - ---------------------- +What is Remote Wakeup? +---------------------- When a device has been suspended, it generally doesn't resume until the computer tells it to. Likewise, if the entire computer has been @@ -76,8 +81,8 @@ event. Examples include a suspended keyboard resuming when a key is pressed, or a suspended USB hub resuming when a device is plugged in. - When is a USB device idle? - -------------------------- +When is a USB device idle? +-------------------------- A device is idle whenever the kernel thinks it's not busy doing anything important and thus is a candidate for being suspended. The @@ -92,11 +97,11 @@ If a USB device has no driver, its usbfs file isn't open, and it isn't being accessed through sysfs, then it definitely is idle. - Forms of dynamic PM - ------------------- +Forms of dynamic PM +------------------- Dynamic suspends occur when the kernel decides to suspend an idle -device. This is called "autosuspend" for short. In general, a device +device. This is called ``autosuspend`` for short. In general, a device won't be autosuspended unless it has been idle for some minimum period of time, the so-called idle-delay time. @@ -125,51 +130,51 @@ all dynamic suspend events are internal; external agents are not allowed to issue dynamic suspends. - The user interface for dynamic PM - --------------------------------- +The user interface for dynamic PM +--------------------------------- -The user interface for controlling dynamic PM is located in the power/ +The user interface for controlling dynamic PM is located in the ``power/`` subdirectory of each USB device's sysfs directory, that is, in -/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The +``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The relevant attribute files are: wakeup, control, and -autosuspend_delay_ms. (There may also be a file named "level"; this +``autosuspend_delay_ms``. (There may also be a file named ``level``; this file was deprecated as of the 2.6.35 kernel and replaced by the -"control" file. In 2.6.38 the "autosuspend" file will be deprecated -and replaced by the "autosuspend_delay_ms" file. The only difference +``control`` file. In 2.6.38 the ``autosuspend`` file will be deprecated +and replaced by the ``autosuspend_delay_ms`` file. The only difference is that the newer file expresses the delay in milliseconds whereas the older file uses seconds. Confusingly, both files are present in 2.6.37 -but only "autosuspend" works.) +but only ``autosuspend`` works.) - power/wakeup + ``power/wakeup`` This file is empty if the device does not support remote wakeup. Otherwise the file contains either the - word "enabled" or the word "disabled", and you can + word ``enabled`` or the word ``disabled``, and you can write those words to the file. The setting determines whether or not remote wakeup will be enabled when the device is next suspended. (If the setting is changed while the device is suspended, the change won't take effect until the following suspend.) - power/control + ``power/control`` - This file contains one of two words: "on" or "auto". + This file contains one of two words: ``on`` or ``auto``. You can write those words to the file to change the device's setting. - "on" means that the device should be resumed and - autosuspend is not allowed. (Of course, system - suspends are still allowed.) + - ``on`` means that the device should be resumed and + autosuspend is not allowed. (Of course, system + suspends are still allowed.) - "auto" is the normal state in which the kernel is - allowed to autosuspend and autoresume the device. + - ``auto`` is the normal state in which the kernel is + allowed to autosuspend and autoresume the device. (In kernels up to 2.6.32, you could also specify - "suspend", meaning that the device should remain + ``suspend``, meaning that the device should remain suspended and autoresume was not allowed. This setting is no longer supported.) - power/autosuspend_delay_ms + ``power/autosuspend_delay_ms`` This file contains an integer value, which is the number of milliseconds the device should remain idle @@ -180,31 +185,31 @@ but only "autosuspend" works.) number to the file to change the autosuspend idle-delay time. -Writing "-1" to power/autosuspend_delay_ms and writing "on" to -power/control do essentially the same thing -- they both prevent the +Writing ``-1`` to ``power/autosuspend_delay_ms`` and writing ``on`` to +``power/control`` do essentially the same thing -- they both prevent the device from being autosuspended. Yes, this is a redundancy in the API. -(In 2.6.21 writing "0" to power/autosuspend would prevent the device +(In 2.6.21 writing ``0`` to ``power/autosuspend`` would prevent the device from being autosuspended; the behavior was changed in 2.6.22. The -power/autosuspend attribute did not exist prior to 2.6.21, and the -power/level attribute did not exist prior to 2.6.22. power/control -was added in 2.6.34, and power/autosuspend_delay_ms was added in +``power/autosuspend`` attribute did not exist prior to 2.6.21, and the +``power/level`` attribute did not exist prior to 2.6.22. ``power/control`` +was added in 2.6.34, and ``power/autosuspend_delay_ms`` was added in 2.6.37 but did not become functional until 2.6.38.) - Changing the default idle-delay time - ------------------------------------ +Changing the default idle-delay time +------------------------------------ The default autosuspend idle-delay time (in seconds) is controlled by a module parameter in usbcore. You can specify the value when usbcore is loaded. For example, to set it to 5 seconds instead of 2 you would -do: +do:: modprobe usbcore autosuspend=5 Equivalently, you could add to a configuration file in /etc/modprobe.d -a line saying: +a line saying:: options usbcore autosuspend=5 @@ -214,14 +219,14 @@ image. To alter the parameter value you would have to rebuild that image. If usbcore is compiled into the kernel rather than built as a loadable -module, you can add +module, you can add:: usbcore.autosuspend=5 to the kernel's boot command line. Finally, the parameter value can be changed while the system is -running. If you do: +running. If you do:: echo 5 >/sys/module/usbcore/parameters/autosuspend @@ -234,8 +239,8 @@ autosuspend of any USB device. This has the benefit of allowing you then to enable autosuspend for selected devices. - Warnings - -------- +Warnings +-------- The USB specification states that all USB devices must support power management. Nevertheless, the sad fact is that many devices do not @@ -246,7 +251,7 @@ among printers and scanners, but plenty of other types of device have the same deficiency. For this reason, by default the kernel disables autosuspend (the -power/control attribute is initialized to "on") for all devices other +``power/control`` attribute is initialized to ``on``) for all devices other than hubs. Hubs, at least, appear to be reasonably well-behaved in this regard. @@ -284,30 +289,30 @@ device by suspending it at the wrong time. (Highly unlikely, but possible.) Take care. - The driver interface for Power Management - ----------------------------------------- +The driver interface for Power Management +----------------------------------------- The requirements for a USB driver to support external power management -are pretty modest; the driver need only define +are pretty modest; the driver need only define:: .suspend .resume .reset_resume -methods in its usb_driver structure, and the reset_resume method is -optional. The methods' jobs are quite simple: +methods in its :c:type:`usb_driver` structure, and the ``reset_resume`` method +is optional. The methods' jobs are quite simple: - The suspend method is called to warn the driver that the + - The ``suspend`` method is called to warn the driver that the device is going to be suspended. If the driver returns a negative error code, the suspend will be aborted. Normally the driver will return 0, in which case it must cancel all - outstanding URBs (usb_kill_urb()) and not submit any more. + outstanding URBs (:c:func:`usb_kill_urb`) and not submit any more. - The resume method is called to tell the driver that the + - The ``resume`` method is called to tell the driver that the device has been resumed and the driver can return to normal operation. URBs may once more be submitted. - The reset_resume method is called to tell the driver that + - The ``reset_resume`` method is called to tell the driver that the device has been resumed and it also has been reset. The driver should redo any necessary device initialization, since the device has probably lost most or all of its state @@ -315,22 +320,22 @@ optional. The methods' jobs are quite simple: before the suspend). If the device is disconnected or powered down while it is suspended, -the disconnect method will be called instead of the resume or -reset_resume method. This is also quite likely to happen when +the ``disconnect`` method will be called instead of the ``resume`` or +``reset_resume`` method. This is also quite likely to happen when waking up from hibernation, as many systems do not maintain suspend current to the USB host controllers during hibernation. (It's possible to work around the hibernation-forces-disconnect problem by using the USB Persist facility.) -The reset_resume method is used by the USB Persist facility (see -Documentation/usb/persist.txt) and it can also be used under certain -circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a +The ``reset_resume`` method is used by the USB Persist facility (see +:ref:`usb-persist`) and it can also be used under certain +circumstances when ``CONFIG_USB_PERSIST`` is not enabled. Currently, if a device is reset during a resume and the driver does not have a -reset_resume method, the driver won't receive any notification about -the resume. Later kernels will call the driver's disconnect method; +``reset_resume`` method, the driver won't receive any notification about +the resume. Later kernels will call the driver's ``disconnect`` method; 2.6.23 doesn't do this. -USB drivers are bound to interfaces, so their suspend and resume +USB drivers are bound to interfaces, so their ``suspend`` and ``resume`` methods get called when the interfaces are suspended or resumed. In principle one might want to suspend some interfaces on a device (i.e., force the drivers for those interface to stop all activity) without @@ -341,15 +346,15 @@ to suspend or resume some but not all of a device's interfaces. The closest you can come is to unbind the interfaces' drivers. - The driver interface for autosuspend and autoresume - --------------------------------------------------- +The driver interface for autosuspend and autoresume +--------------------------------------------------- To support autosuspend and autoresume, a driver should implement all three of the methods listed above. In addition, a driver indicates -that it supports autosuspend by setting the .supports_autosuspend flag +that it supports autosuspend by setting the ``.supports_autosuspend`` flag in its usb_driver structure. It is then responsible for informing the USB core whenever one of its interfaces becomes busy or idle. The -driver does so by calling these six functions: +driver does so by calling these six functions:: int usb_autopm_get_interface(struct usb_interface *intf); void usb_autopm_put_interface(struct usb_interface *intf); @@ -368,41 +373,41 @@ autosuspend the device. Drivers need not be concerned about balancing changes to the usage counter; the USB core will undo any remaining "get"s when a driver is unbound from its interface. As a corollary, drivers must not call -any of the usb_autopm_* functions after their disconnect() routine has -returned. +any of the ``usb_autopm_*`` functions after their ``disconnect`` +routine has returned. Drivers using the async routines are responsible for their own synchronization and mutual exclusion. - usb_autopm_get_interface() increments the usage counter and + :c:func:`usb_autopm_get_interface` increments the usage counter and does an autoresume if the device is suspended. If the autoresume fails, the counter is decremented back. - usb_autopm_put_interface() decrements the usage counter and + :c:func:`usb_autopm_put_interface` decrements the usage counter and attempts an autosuspend if the new value is = 0. - usb_autopm_get_interface_async() and - usb_autopm_put_interface_async() do almost the same things as + :c:func:`usb_autopm_get_interface_async` and + :c:func:`usb_autopm_put_interface_async` do almost the same things as their non-async counterparts. The big difference is that they use a workqueue to do the resume or suspend part of their jobs. As a result they can be called in an atomic context, such as an URB's completion handler, but when they return the device will generally not yet be in the desired state. - usb_autopm_get_interface_no_resume() and - usb_autopm_put_interface_no_suspend() merely increment or + :c:func:`usb_autopm_get_interface_no_resume` and + :c:func:`usb_autopm_put_interface_no_suspend` merely increment or decrement the usage counter; they do not attempt to carry out an autoresume or an autosuspend. Hence they can be called in an atomic context. The simplest usage pattern is that a driver calls -usb_autopm_get_interface() in its open routine and -usb_autopm_put_interface() in its close or release routine. But other +:c:func:`usb_autopm_get_interface` in its open routine and +:c:func:`usb_autopm_put_interface` in its close or release routine. But other patterns are possible. The autosuspend attempts mentioned above will often fail for one -reason or another. For example, the power/control attribute might be -set to "on", or another interface in the same device might not be +reason or another. For example, the ``power/control`` attribute might be +set to ``on``, or another interface in the same device might not be idle. This is perfectly normal. If the reason for failure was that the device hasn't been idle for long enough, a timer is scheduled to carry out the operation automatically when the autosuspend idle-delay @@ -413,37 +418,37 @@ the device is no longer present or operating properly. Unlike autosuspend, there's no idle-delay for an autoresume. - Other parts of the driver interface - ----------------------------------- +Other parts of the driver interface +----------------------------------- -Drivers can enable autosuspend for their devices by calling +Drivers can enable autosuspend for their devices by calling:: usb_enable_autosuspend(struct usb_device *udev); -in their probe() routine, if they know that the device is capable of +in their :c:func:`probe` routine, if they know that the device is capable of suspending and resuming correctly. This is exactly equivalent to -writing "auto" to the device's power/control attribute. Likewise, -drivers can disable autosuspend by calling +writing ``auto`` to the device's ``power/control`` attribute. Likewise, +drivers can disable autosuspend by calling:: usb_disable_autosuspend(struct usb_device *udev); -This is exactly the same as writing "on" to the power/control attribute. +This is exactly the same as writing ``on`` to the ``power/control`` attribute. Sometimes a driver needs to make sure that remote wakeup is enabled during autosuspend. For example, there's not much point autosuspending a keyboard if the user can't cause the keyboard to do a remote wakeup by typing on it. If the driver sets -intf->needs_remote_wakeup to 1, the kernel won't autosuspend the +``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the device if remote wakeup isn't available. (If the device is already autosuspended, though, setting this flag won't cause the kernel to -autoresume it. Normally a driver would set this flag in its probe +autoresume it. Normally a driver would set this flag in its ``probe`` method, at which time the device is guaranteed not to be autosuspended.) If a driver does its I/O asynchronously in interrupt context, it -should call usb_autopm_get_interface_async() before starting output and -usb_autopm_put_interface_async() when the output queue drains. When -it receives an input event, it should call +should call :c:func:`usb_autopm_get_interface_async` before starting output and +:c:func:`usb_autopm_put_interface_async` when the output queue drains. When +it receives an input event, it should call:: usb_mark_last_busy(struct usb_device *udev); @@ -453,41 +458,41 @@ be pushed back. Many of the usb_autopm_* routines also make this call, so drivers need to worry only when interrupt-driven input arrives. Asynchronous operation is always subject to races. For example, a -driver may call the usb_autopm_get_interface_async() routine at a time +driver may call the :c:func:`usb_autopm_get_interface_async` routine at a time when the core has just finished deciding the device has been idle for -long enough but not yet gotten around to calling the driver's suspend -method. The suspend method must be responsible for synchronizing with +long enough but not yet gotten around to calling the driver's ``suspend`` +method. The ``suspend`` method must be responsible for synchronizing with the I/O request routine and the URB completion handler; it should cause autosuspends to fail with -EBUSY if the driver needs to use the device. External suspend calls should never be allowed to fail in this way, only autosuspend calls. The driver can tell them apart by applying -the PMSG_IS_AUTO() macro to the message argument to the suspend +the :c:func:`PMSG_IS_AUTO` macro to the message argument to the ``suspend`` method; it will return True for internal PM events (autosuspend) and False for external PM events. - Mutual exclusion - ---------------- +Mutual exclusion +---------------- For external events -- but not necessarily for autosuspend or autoresume -- the device semaphore (udev->dev.sem) will be held when a -suspend or resume method is called. This implies that external -suspend/resume events are mutually exclusive with calls to probe, -disconnect, pre_reset, and post_reset; the USB core guarantees that +``suspend`` or ``resume`` method is called. This implies that external +suspend/resume events are mutually exclusive with calls to ``probe``, +``disconnect``, ``pre_reset``, and ``post_reset``; the USB core guarantees that this is true of autosuspend/autoresume events as well. If a driver wants to block all suspend/resume calls during some critical section, the best way is to lock the device and call -usb_autopm_get_interface() (and do the reverse at the end of the +:c:func:`usb_autopm_get_interface` (and do the reverse at the end of the critical section). Holding the device semaphore will block all -external PM calls, and the usb_autopm_get_interface() will prevent any +external PM calls, and the :c:func:`usb_autopm_get_interface` will prevent any internal PM calls, even if it fails. (Exercise: Why?) - Interaction between dynamic PM and system PM - -------------------------------------------- +Interaction between dynamic PM and system PM +-------------------------------------------- Dynamic power management and system power management can interact in a couple of ways. @@ -512,8 +517,8 @@ wakeup may fail and get lost. Which outcome occurs depends on timing and on the hardware and firmware design. - xHCI hardware link PM - --------------------- +xHCI hardware link PM +--------------------- xHCI host controller provides hardware link power management to usb2.0 (xHCI 1.0 feature) and usb3.0 devices which support link PM. By @@ -522,11 +527,11 @@ lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), which state device can enter and resume very quickly. The user interface for controlling hardware LPM is located in the -power/ subdirectory of each USB device's sysfs directory, that is, in -/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The -relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm. +``power/`` subdirectory of each USB device's sysfs directory, that is, in +``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The +relevant attribute files are ``usb2_hardware_lpm`` and ``usb3_hardware_lpm``. - power/usb2_hardware_lpm + ``power/usb2_hardware_lpm`` When a USB2 device which support LPM is plugged to a xHCI host root hub which support software LPM, the @@ -537,8 +542,8 @@ relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm. can write y/Y/1 or n/N/0 to the file to enable/disable USB2 hardware LPM manually. This is for test purpose mainly. - power/usb3_hardware_lpm_u1 - power/usb3_hardware_lpm_u2 + ``power/usb3_hardware_lpm_u1`` + ``power/usb3_hardware_lpm_u2`` When a USB 3.0 lpm-capable device is plugged in to a xHCI host which supports link PM, it will check if U1 @@ -550,29 +555,31 @@ relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm. indicating whether or not USB3 hardware LPM U1 or U2 is enabled for the device. - USB Port Power Control - ---------------------- +USB Port Power Control +---------------------- In addition to suspending endpoint devices and enabling hardware controlled link power management, the USB subsystem also has the capability to disable power to ports under some conditions. Power is -controlled through Set/ClearPortFeature(PORT_POWER) requests to a hub. +controlled through ``Set/ClearPortFeature(PORT_POWER)`` requests to a hub. In the case of a root or platform-internal hub the host controller -driver translates PORT_POWER requests into platform firmware (ACPI) +driver translates ``PORT_POWER`` requests into platform firmware (ACPI) method calls to set the port power state. For more background see the -Linux Plumbers Conference 2012 slides [1] and video [2]: +Linux Plumbers Conference 2012 slides [#f1]_ and video [#f2]_: -Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is -logically off, and may trigger the actual loss of VBUS to the port [3]. +Upon receiving a ``ClearPortFeature(PORT_POWER)`` request a USB port is +logically off, and may trigger the actual loss of VBUS to the port [#f3]_. VBUS may be maintained in the case where a hub gangs multiple ports into a shared power well causing power to remain until all ports in the gang are turned off. VBUS may also be maintained by hub ports configured for a charging application. In any event a logically off port will lose connection with its device, not respond to hotplug events, and not -respond to remote wakeup events*. +respond to remote wakeup events. + +.. warning:: -WARNING: turning off a port may result in the inability to hot add a device. -Please see "User Interface for Port Power Control" for details. + turning off a port may result in the inability to hot add a device. + Please see "User Interface for Port Power Control" for details. As far as the effect on the device itself it is similar to what a device goes through during system suspend, i.e. the power session is lost. Any @@ -581,38 +588,49 @@ similarly affected by a port power cycle event. For this reason the implementation shares the same device recovery path (and honors the same quirks) as the system resume path for the hub. -[1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf -[2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/ -[3]: USB 3.1 Section 10.12 -* wakeup note: if a device is configured to send wakeup events the port +.. [#f1] + + http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf + +.. [#f2] + + http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/ + +.. [#f3] + + USB 3.1 Section 10.12 + + wakeup note: if a device is configured to send wakeup events the port power control implementation will block poweroff attempts on that port. - User Interface for Port Power Control - ------------------------------------- +User Interface for Port Power Control +------------------------------------- The port power control mechanism uses the PM runtime system. Poweroff is -requested by clearing the power/pm_qos_no_power_off flag of the port device +requested by clearing the ``power/pm_qos_no_power_off`` flag of the port device (defaults to 1). If the port is disconnected it will immediately receive a -ClearPortFeature(PORT_POWER) request. Otherwise, it will honor the pm runtime -rules and require the attached child device and all descendants to be suspended. -This mechanism is dependent on the hub advertising port power switching in its -hub descriptor (wHubCharacteristics logical power switching mode field). +``ClearPortFeature(PORT_POWER)`` request. Otherwise, it will honor the pm +runtime rules and require the attached child device and all descendants to be +suspended. This mechanism is dependent on the hub advertising port power +switching in its hub descriptor (wHubCharacteristics logical power switching +mode field). Note, some interface devices/drivers do not support autosuspend. Userspace may -need to unbind the interface drivers before the usb_device will suspend. An -unbound interface device is suspended by default. When unbinding, be careful -to unbind interface drivers, not the driver of the parent usb device. Also, -leave hub interface drivers bound. If the driver for the usb device (not -interface) is unbound the kernel is no longer able to resume the device. If a -hub interface driver is unbound, control of its child ports is lost and all -attached child-devices will disconnect. A good rule of thumb is that if the -'driver/module' link for a device points to /sys/module/usbcore then unbinding -it will interfere with port power control. +need to unbind the interface drivers before the :c:type:`usb_device` will +suspend. An unbound interface device is suspended by default. When unbinding, +be careful to unbind interface drivers, not the driver of the parent usb +device. Also, leave hub interface drivers bound. If the driver for the usb +device (not interface) is unbound the kernel is no longer able to resume the +device. If a hub interface driver is unbound, control of its child ports is +lost and all attached child-devices will disconnect. A good rule of thumb is +that if the 'driver/module' link for a device points to +``/sys/module/usbcore`` then unbinding it will interfere with port power +control. Example of the relevant files for port power control. Note, in this example -these files are relative to a usb hub device (prefix). +these files are relative to a usb hub device (prefix):: prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1 @@ -631,10 +649,10 @@ these files are relative to a usb hub device (prefix). In addition to these files some ports may have a 'peer' link to a port on another hub. The expectation is that all superspeed ports have a -hi-speed peer. +hi-speed peer:: -$prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1 -../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1 + $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1 + ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1 Distinct from 'companion ports', or 'ehci/xhci shared switchover ports' peer ports are simply the hi-speed and superspeed interface pins that @@ -645,24 +663,26 @@ While a superspeed port is powered off a device may downgrade its connection and attempt to connect to the hi-speed pins. The implementation takes steps to prevent this: -1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off +1. Port suspend is sequenced to guarantee that hi-speed ports are powered-off before their superspeed peer is permitted to power-off. The implication is - that the setting pm_qos_no_power_off to zero on a superspeed port may not cause - the port to power-off until its highspeed peer has gone to its runtime suspend - state. Userspace must take care to order the suspensions if it wants to - guarantee that a superspeed port will power-off. + that the setting ``pm_qos_no_power_off`` to zero on a superspeed port may + not cause the port to power-off until its highspeed peer has gone to its + runtime suspend state. Userspace must take care to order the suspensions + if it wants to guarantee that a superspeed port will power-off. -2/ Port resume is sequenced to force a superspeed port to power-on prior to its +2. Port resume is sequenced to force a superspeed port to power-on prior to its highspeed peer. -3/ Port resume always triggers an attached child device to resume. After a +3. Port resume always triggers an attached child device to resume. After a power session is lost the device may have been removed, or need reset. Resuming the child device when the parent port regains power resolves those - states and clamps the maximum port power cycle frequency at the rate the child - device can suspend (autosuspend-delay) and resume (reset-resume latency). + states and clamps the maximum port power cycle frequency at the rate the + child device can suspend (autosuspend-delay) and resume (reset-resume + latency). Sysfs files relevant for port power control: - <hubdev-portX>/power/pm_qos_no_power_off: + + ``<hubdev-portX>/power/pm_qos_no_power_off``: This writable flag controls the state of an idle port. Once all children and descendants have suspended the port may suspend/poweroff provided that @@ -670,24 +690,24 @@ Sysfs files relevant for port power control: '1' the port will remain active/powered regardless of the stats of descendants. Defaults to 1. - <hubdev-portX>/power/runtime_status: + ``<hubdev-portX>/power/runtime_status``: This file reflects whether the port is 'active' (power is on) or 'suspended' (logically off). There is no indication to userspace whether VBUS is still supplied. - <hubdev-portX>/connect_type: + ``<hubdev-portX>/connect_type``: An advisory read-only flag to userspace indicating the location and connection type of the port. It returns one of four values 'hotplug', 'hardwired', 'not used', and 'unknown'. All values, besides unknown, are set by platform firmware. - "hotplug" indicates an externally connectable/visible + ``hotplug`` indicates an externally connectable/visible port on the platform. Typically userspace would choose to keep such a port powered to handle new device connection events. - "hardwired" refers to a port that is not visible but + ``hardwired`` refers to a port that is not visible but connectable. Examples are internal ports for USB bluetooth that can be disconnected via an external switch or a port with a hardwired USB camera. It is @@ -698,48 +718,50 @@ Sysfs files relevant for port power control: powering off, or to activate the port prior to enabling connection via a switch. - "not used" refers to an internal port that is expected + ``not used`` refers to an internal port that is expected to never have a device connected to it. These may be empty internal ports, or ports that are not physically exposed on a platform. Considered safe to be powered-off at all times. - "unknown" means platform firmware does not provide + ``unknown`` means platform firmware does not provide information for this port. Most commonly refers to external hub ports which should be considered 'hotplug' for policy decisions. - NOTE1: since we are relying on the BIOS to get this ACPI - information correct, the USB port descriptions may be - missing or wrong. + .. note:: + + - since we are relying on the BIOS to get this ACPI + information correct, the USB port descriptions may + be missing or wrong. - NOTE2: Take care in clearing pm_qos_no_power_off. Once - power is off this port will - not respond to new connect events. + - Take care in clearing ``pm_qos_no_power_off``. Once + power is off this port will + not respond to new connect events. Once a child device is attached additional constraints are applied before the port is allowed to poweroff. - <child>/power/control: - Must be 'auto', and the port will not - power down until <child>/power/runtime_status + ``<child>/power/control``: + Must be ``auto``, and the port will not + power down until ``<child>/power/runtime_status`` reflects the 'suspended' state. Default value is controlled by child device driver. - <child>/power/persist: - This defaults to '1' for most devices and indicates if + ``<child>/power/persist``: + This defaults to ``1`` for most devices and indicates if kernel can persist the device's configuration across a power session loss (suspend / port-power event). When - this value is '0' (quirky devices), port poweroff is + this value is ``0`` (quirky devices), port poweroff is disabled. - <child>/driver/unbind: + ``<child>/driver/unbind``: Wakeup capable devices will block port poweroff. At this time the only mechanism to clear the usb-internal wakeup-capability for an interface device is to unbind its driver. -Summary of poweroff pre-requisite settings relative to a port device: +Summary of poweroff pre-requisite settings relative to a port device:: echo 0 > power/pm_qos_no_power_off echo 0 > peer/power/pm_qos_no_power_off # if it exists @@ -747,14 +769,14 @@ Summary of poweroff pre-requisite settings relative to a port device: echo auto > <child>/power/control echo 1 > <child>/power/persist # this is the default value - Suggested Userspace Port Power Policy - ------------------------------------- +Suggested Userspace Port Power Policy +------------------------------------- As noted above userspace needs to be careful and deliberate about what ports are enabled for poweroff. The default configuration is that all ports start with -power/pm_qos_no_power_off set to '1' causing ports to always remain +``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain active. Given confidence in the platform firmware's description of the ports @@ -764,7 +786,7 @@ done for 'hardwired' ports provided poweroff is coordinated with any connection switch for the port. A more aggressive userspace policy is to enable USB port power off for -all ports (set <hubdev-portX>/power/pm_qos_no_power_off to '0') when +all ports (set ``<hubdev-portX>/power/pm_qos_no_power_off`` to ``0``) when some external factor indicates the user has stopped interacting with the system. For example, a distro may want to enable power off all USB ports when the screen blanks, and re-power them when the screen becomes diff --git a/Documentation/driver-api/usb.rst b/Documentation/driver-api/usb/usb.rst index 851cc40b66b5..dba0f876b36f 100644 --- a/Documentation/driver-api/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -1,3 +1,5 @@ +.. _usb-hostside-api: + =========================== The Linux-USB Host Side API =========================== @@ -102,16 +104,21 @@ disconnect testing (while the device is active) with each different host controller driver, to make sure drivers don't have bugs of their own as well as to make sure they aren't relying on some HCD-specific behavior. +.. _usb_chapter9: + USB-Standard Types ================== In ``<linux/usb/ch9.h>`` you will find the USB data types defined in chapter 9 of the USB specification. These data types are used throughout -USB, and in APIs including this host side API, gadget APIs, and usbfs. +USB, and in APIs including this host side API, gadget APIs, usb character +devices and debugfs interfaces. .. kernel-doc:: include/linux/usb/ch9.h :internal: +.. _usb_header: + Host-Side Data Types and Macros =============================== @@ -198,173 +205,110 @@ significantly reduce hcd-specific behaviors. .. kernel-doc:: drivers/usb/core/buffer.c :internal: -The USB Filesystem (usbfs) -========================== +The USB character device nodes +============================== -This chapter presents the Linux *usbfs*. You may prefer to avoid writing -new kernel code for your USB driver; that's the problem that usbfs set -out to solve. User mode device drivers are usually packaged as -applications or libraries, and may use usbfs through some programming -library that wraps it. Such libraries include -`libusb <http://libusb.sourceforge.net>`__ for C/C++, and -`jUSB <http://jUSB.sourceforge.net>`__ for Java. +This chapter presents the Linux character device nodes. You may prefer +to avoid writing new kernel code for your USB driver. User mode device +drivers are usually packaged as applications or libraries, and may use +character devices through some programming library that wraps it. +Such libraries include: - **Note** + - `libusb <http://libusb.sourceforge.net>`__ for C/C++, and + - `jUSB <http://jUSB.sourceforge.net>`__ for Java. - This particular documentation is incomplete, especially with respect - to the asynchronous mode. As of kernel 2.5.66 the code and this - (new) documentation need to be cross-reviewed. +Some old information about it can be seen at the "USB Device Filesystem" +section of the USB Guide. The latest copy of the USB Guide can be found +at http://www.linux-usb.org/ -Configure usbfs into Linux kernels by enabling the *USB filesystem* -option (CONFIG_USB_DEVICEFS), and you get basic support for user mode -USB device drivers. Until relatively recently it was often (confusingly) -called *usbdevfs* although it wasn't solving what *devfs* was. Every USB -device will appear in usbfs, regardless of whether or not it has a -kernel driver. +.. note:: -What files are in "usbfs"? --------------------------- + - They were used to be implemented via *usbfs*, but this is not part of + the sysfs debug interface. -Conventionally mounted at ``/proc/bus/usb``, usbfs features include: + - This particular documentation is incomplete, especially with respect + to the asynchronous mode. As of kernel 2.5.66 the code and this + (new) documentation need to be cross-reviewed. -- ``/proc/bus/usb/devices`` ... a text file showing each of the USB - devices on known to the kernel, and their configuration descriptors. - You can also poll() this to learn about new devices. +What files are in "devtmpfs"? +----------------------------- -- ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's +Conventionally mounted at ``/dev/bus/usb/``, usbfs features include: + +- ``/dev/bus/usb/BBB/DDD`` ... magic files exposing the each device's configuration descriptors, and supporting a series of ioctls for making device requests, including I/O to devices. (Purely for access by programs.) -Each bus is given a number (BBB) based on when it was enumerated; within -each bus, each device is given a similar number (DDD). Those BBB/DDD +Each bus is given a number (``BBB``) based on when it was enumerated; within +each bus, each device is given a similar number (``DDD``). Those ``BBB/DDD`` paths are not "stable" identifiers; expect them to change even if you always leave the devices plugged in to the same hub port. *Don't even think of saving these in application configuration files.* Stable identifiers are available, for user mode applications that want to use them. HID and networking devices expose these stable IDs, so that for example you can be sure that you told the right UPS to power down its -second server. "usbfs" doesn't (yet) expose those IDs. - -Mounting and Access Control ---------------------------- - -There are a number of mount options for usbfs, which will be of most -interest to you if you need to override the default access control -policy. That policy is that only root may read or write device files -(``/proc/bus/BBB/DDD``) although anyone may read the ``devices`` or -``drivers`` files. I/O requests to the device also need the -CAP_SYS_RAWIO capability, - -The significance of that is that by default, all user mode device -drivers need super-user privileges. You can change modes or ownership in -a driver setup when the device hotplugs, or maye just start the driver -right then, as a privileged server (or some activity within one). That's -the most secure approach for multi-user systems, but for single user -systems ("trusted" by that user) it's more convenient just to grant -everyone all access (using the *devmode=0666* option) so the driver can -start whenever it's needed. - -The mount options for usbfs, usable in /etc/fstab or in command line -invocations of *mount*, are: - -*busgid*\ =NNNNN - Controls the GID used for the /proc/bus/usb/BBB directories. - (Default: 0) - -*busmode*\ =MMM - Controls the file mode used for the /proc/bus/usb/BBB directories. - (Default: 0555) - -*busuid*\ =NNNNN - Controls the UID used for the /proc/bus/usb/BBB directories. - (Default: 0) - -*devgid*\ =NNNNN - Controls the GID used for the /proc/bus/usb/BBB/DDD files. (Default: - 0) - -*devmode*\ =MMM - Controls the file mode used for the /proc/bus/usb/BBB/DDD files. - (Default: 0644) - -*devuid*\ =NNNNN - Controls the UID used for the /proc/bus/usb/BBB/DDD files. (Default: - 0) - -*listgid*\ =NNNNN - Controls the GID used for the /proc/bus/usb/devices and drivers - files. (Default: 0) - -*listmode*\ =MMM - Controls the file mode used for the /proc/bus/usb/devices and - drivers files. (Default: 0444) +second server. Pleast note that it doesn't (yet) expose those IDs. -*listuid*\ =NNNNN - Controls the UID used for the /proc/bus/usb/devices and drivers - files. (Default: 0) - -Note that many Linux distributions hard-wire the mount options for usbfs -in their init scripts, such as ``/etc/rc.d/rc.sysinit``, rather than -making it easy to set this per-system policy in ``/etc/fstab``. - -/proc/bus/usb/devices ---------------------- - -This file is handy for status viewing tools in user mode, which can scan -the text format and ignore most of it. More detailed device status -(including class and vendor status) is available from device-specific -files. For information about the current format of this file, see the -``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel -sources. - -This file, in combination with the poll() system call, can also be used -to detect when devices are added or removed: - -:: - - int fd; - struct pollfd pfd; - - fd = open("/proc/bus/usb/devices", O_RDONLY); - pfd = { fd, POLLIN, 0 }; - for (;;) { - /* The first time through, this call will return immediately. */ - poll(&pfd, 1, -1); - - /* To see what's changed, compare the file's previous and current - contents or scan the filesystem. (Scanning is more precise.) */ - } - -Note that this behavior is intended to be used for informational and -debug purposes. It would be more appropriate to use programs such as -udev or HAL to initialize a device or start a user-mode helper program, -for instance. - -/proc/bus/usb/BBB/DDD ---------------------- +/dev/bus/usb/BBB/DDD +-------------------- Use these files in one of these basic ways: -*They can be read,* producing first the device descriptor (18 bytes) and -then the descriptors for the current configuration. See the USB 2.0 spec -for details about those binary data formats. You'll need to convert most -multibyte values from little endian format to your native host byte -order, although a few of the fields in the device descriptor (both of -the BCD-encoded fields, and the vendor and product IDs) will be -byteswapped for you. Note that configuration descriptors include -descriptors for interfaces, altsettings, endpoints, and maybe additional -class descriptors. - -*Perform USB operations* using *ioctl()* requests to make endpoint I/O -requests (synchronously or asynchronously) or manage the device. These -requests need the CAP_SYS_RAWIO capability, as well as filesystem -access permissions. Only one ioctl request can be made on one of these -device files at a time. This means that if you are synchronously reading -an endpoint from one thread, you won't be able to write to a different -endpoint from another thread until the read completes. This works for -*half duplex* protocols, but otherwise you'd use asynchronous i/o -requests. +- *They can be read,* producing first the device descriptor (18 bytes) and + then the descriptors for the current configuration. See the USB 2.0 spec + for details about those binary data formats. You'll need to convert most + multibyte values from little endian format to your native host byte + order, although a few of the fields in the device descriptor (both of + the BCD-encoded fields, and the vendor and product IDs) will be + byteswapped for you. Note that configuration descriptors include + descriptors for interfaces, altsettings, endpoints, and maybe additional + class descriptors. + +- *Perform USB operations* using *ioctl()* requests to make endpoint I/O + requests (synchronously or asynchronously) or manage the device. These + requests need the ``CAP_SYS_RAWIO`` capability, as well as filesystem + access permissions. Only one ioctl request can be made on one of these + device files at a time. This means that if you are synchronously reading + an endpoint from one thread, you won't be able to write to a different + endpoint from another thread until the read completes. This works for + *half duplex* protocols, but otherwise you'd use asynchronous i/o + requests. + +Each connected USB device has one file. The ``BBB`` indicates the bus +number. The ``DDD`` indicates the device address on that bus. Both +of these numbers are assigned sequentially, and can be reused, so +you can't rely on them for stable access to devices. For example, +it's relatively common for devices to re-enumerate while they are +still connected (perhaps someone jostled their power supply, hub, +or USB cable), so a device might be ``002/027`` when you first connect +it and ``002/048`` sometime later. + +These files can be read as binary data. The binary data consists +of first the device descriptor, then the descriptors for each +configuration of the device. Multi-byte fields in the device descriptor +are converted to host endianness by the kernel. The configuration +descriptors are in bus endian format! The configuration descriptor +are wTotalLength bytes apart. If a device returns less configuration +descriptor data than indicated by wTotalLength there will be a hole in +the file for the missing bytes. This information is also shown +in text form by the ``/sys/kernel/debug/usb/devices`` file, described later. + +These files may also be used to write user-level drivers for the USB +devices. You would open the ``/dev/bus/usb/BBB/DDD`` file read/write, +read its descriptors to make sure it's the device you expect, and then +bind to an interface (or perhaps several) using an ioctl call. You +would issue more ioctls to the device to communicate to it using +control, bulk, or other kinds of USB transfers. The IOCTLs are +listed in the ``<linux/usbdevice_fs.h>`` file, and at this writing the +source code (``linux/drivers/usb/core/devio.c``) is the primary reference +for how to access devices through those files. + +Note that since by default these ``BBB/DDD`` files are writable only by +root, only root can write such user mode drivers. You can selectively +grant read/write permissions to other users by using ``chmod``. Also, +usbfs mount options such as ``devmode=0666`` may be helpful. + Life Cycle of User Mode Drivers ------------------------------- @@ -372,7 +316,7 @@ Life Cycle of User Mode Drivers Such a driver first needs to find a device file for a device it knows how to handle. Maybe it was told about it because a ``/sbin/hotplug`` event handling agent chose that driver to handle the new device. Or -maybe it's an application that scans all the /proc/bus/usb device files, +maybe it's an application that scans all the ``/dev/bus/usb`` device files, and ignores most devices. In either case, it should :c:func:`read()` all the descriptors from the device file, and check them against what it knows how to handle. It might just reject everything except a particular @@ -407,9 +351,7 @@ The ioctl() Requests -------------------- To use these ioctls, you need to include the following headers in your -userspace program: - -:: +userspace program:: #include <linux/usb.h> #include <linux/usbdevice_fs.h> @@ -422,8 +364,8 @@ header. Unless noted otherwise, the ioctl requests described here will update the modification time on the usbfs file to which they are applied (unless they fail). A return of zero indicates success; otherwise, a -standard USB error code is returned. (These are documented in -``Documentation/usb/error-codes.txt`` in your kernel sources.) +standard USB error code is returned (These are documented in +:ref:`usb-error-codes`). Each of these files multiplexes access to several I/O streams, one per endpoint. Each device has one control endpoint (endpoint zero) which @@ -458,14 +400,12 @@ USBDEVFS_CLAIMINTERFACE USBDEVFS_CONNECTINFO Says whether the device is lowspeed. The ioctl parameter points to a - structure like this: - - :: + structure like this:: - struct usbdevfs_connectinfo { - unsigned int devnum; - unsigned char slow; - }; + struct usbdevfs_connectinfo { + unsigned int devnum; + unsigned char slow; + }; File modification time is not updated by this request. @@ -477,45 +417,41 @@ USBDEVFS_CONNECTINFO USBDEVFS_GETDRIVER Returns the name of the kernel driver bound to a given interface (a string). Parameter is a pointer to this structure, which is - modified: + modified:: - :: - - struct usbdevfs_getdriver { - unsigned int interface; - char driver[USBDEVFS_MAXDRIVERNAME + 1]; - }; + struct usbdevfs_getdriver { + unsigned int interface; + char driver[USBDEVFS_MAXDRIVERNAME + 1]; + }; File modification time is not updated by this request. USBDEVFS_IOCTL Passes a request from userspace through to a kernel driver that has - an ioctl entry in the *struct usb_driver* it registered. - - :: - - struct usbdevfs_ioctl { - int ifno; - int ioctl_code; - void *data; - }; - - /* user mode call looks like this. - * 'request' becomes the driver->ioctl() 'code' parameter. - * the size of 'param' is encoded in 'request', and that data - * is copied to or from the driver->ioctl() 'buf' parameter. - */ - static int - usbdev_ioctl (int fd, int ifno, unsigned request, void *param) - { - struct usbdevfs_ioctl wrapper; - - wrapper.ifno = ifno; - wrapper.ioctl_code = request; - wrapper.data = param; - - return ioctl (fd, USBDEVFS_IOCTL, &wrapper); - } + an ioctl entry in the *struct usb_driver* it registered:: + + struct usbdevfs_ioctl { + int ifno; + int ioctl_code; + void *data; + }; + + /* user mode call looks like this. + * 'request' becomes the driver->ioctl() 'code' parameter. + * the size of 'param' is encoded in 'request', and that data + * is copied to or from the driver->ioctl() 'buf' parameter. + */ + static int + usbdev_ioctl (int fd, int ifno, unsigned request, void *param) + { + struct usbdevfs_ioctl wrapper; + + wrapper.ifno = ifno; + wrapper.ioctl_code = request; + wrapper.data = param; + + return ioctl (fd, USBDEVFS_IOCTL, &wrapper); + } File modification time is not updated by this request. @@ -534,11 +470,11 @@ USBDEVFS_RELEASEINTERFACE the number of the interface (bInterfaceNumber from descriptor); File modification time is not updated by this request. - **Warning** + .. warning:: - *No security check is made to ensure that the task which made - the claim is the one which is releasing it. This means that user - mode driver may interfere other ones.* + *No security check is made to ensure that the task which made + the claim is the one which is releasing it. This means that user + mode driver may interfere other ones.* USBDEVFS_RESETEP Resets the data toggle value for an endpoint (bulk or interrupt) to @@ -546,13 +482,13 @@ USBDEVFS_RESETEP as identified in the endpoint descriptor), with USB_DIR_IN added if the device's endpoint sends data to the host. - **Warning** + .. Warning:: - *Avoid using this request. It should probably be removed.* Using - it typically means the device and driver will lose toggle - synchronization. If you really lost synchronization, you likely - need to completely handshake with the device, using a request - like CLEAR_HALT or SET_INTERFACE. + *Avoid using this request. It should probably be removed.* Using + it typically means the device and driver will lose toggle + synchronization. If you really lost synchronization, you likely + need to completely handshake with the device, using a request + like CLEAR_HALT or SET_INTERFACE. USBDEVFS_DROP_PRIVILEGES This is used to relinquish the ability to do certain operations @@ -574,21 +510,19 @@ a time. USBDEVFS_BULK Issues a bulk read or write request to the device. The ioctl - parameter is a pointer to this structure: - - :: + parameter is a pointer to this structure:: - struct usbdevfs_bulktransfer { - unsigned int ep; - unsigned int len; - unsigned int timeout; /* in milliseconds */ - void *data; - }; + struct usbdevfs_bulktransfer { + unsigned int ep; + unsigned int len; + unsigned int timeout; /* in milliseconds */ + void *data; + }; - The "ep" value identifies a bulk endpoint number (1 to 15, as + The ``ep`` value identifies a bulk endpoint number (1 to 15, as identified in an endpoint descriptor), masked with USB_DIR_IN when referring to an endpoint which sends data to the host from the - device. The length of the data buffer is identified by "len"; Recent + device. The length of the data buffer is identified by ``len``; Recent kernels support requests up to about 128KBytes. *FIXME say how read length is returned, and how short reads are handled.*. @@ -600,31 +534,29 @@ USBDEVFS_CLEAR_HALT which sends data to the host from the device. Use this on bulk or interrupt endpoints which have stalled, - returning *-EPIPE* status to a data transfer request. Do not issue + returning ``-EPIPE`` status to a data transfer request. Do not issue the control request directly, since that could invalidate the host's record of the data toggle. USBDEVFS_CONTROL Issues a control request to the device. The ioctl parameter points - to a structure like this: - - :: - - struct usbdevfs_ctrltransfer { - __u8 bRequestType; - __u8 bRequest; - __u16 wValue; - __u16 wIndex; - __u16 wLength; - __u32 timeout; /* in milliseconds */ - void *data; - }; + to a structure like this:: + + struct usbdevfs_ctrltransfer { + __u8 bRequestType; + __u8 bRequest; + __u16 wValue; + __u16 wIndex; + __u16 wLength; + __u32 timeout; /* in milliseconds */ + void *data; + }; The first eight bytes of this structure are the contents of the SETUP packet to be sent to the device; see the USB 2.0 specification for details. The bRequestType value is composed by combining a - USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\* - value (from *<linux/usb.h>*). If wLength is nonzero, it describes + ``USB_TYPE_*`` value, a ``USB_DIR_*`` value, and a ``USB_RECIP_*`` + value (from ``linux/usb.h``). If wLength is nonzero, it describes the length of the data buffer, which is either written to the device (USB_DIR_OUT) or read from the device (USB_DIR_IN). @@ -638,22 +570,20 @@ USBDEVFS_RESET the reset, this rebinds all device interfaces. File modification time is not updated by this request. - **Warning** +.. warning:: - *Avoid using this call* until some usbcore bugs get fixed, since - it does not fully synchronize device, interface, and driver (not - just usbfs) state. + *Avoid using this call* until some usbcore bugs get fixed, since + it does not fully synchronize device, interface, and driver (not + just usbfs) state. USBDEVFS_SETINTERFACE Sets the alternate setting for an interface. The ioctl parameter is - a pointer to a structure like this: + a pointer to a structure like this:: - :: - - struct usbdevfs_setinterface { - unsigned int interface; - unsigned int altsetting; - }; + struct usbdevfs_setinterface { + unsigned int interface; + unsigned int altsetting; + }; File modification time is not updated by this request. @@ -669,11 +599,11 @@ USBDEVFS_SETCONFIGURATION configuration (bConfigurationValue from descriptor). File modification time is not updated by this request. - **Warning** +.. warning:: - *Avoid using this call* until some usbcore bugs get fixed, since - it does not fully synchronize device, interface, and driver (not - just usbfs) state. + *Avoid using this call* until some usbcore bugs get fixed, since + it does not fully synchronize device, interface, and driver (not + just usbfs) state. Asynchronous I/O Support ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -688,7 +618,7 @@ the blocking is separate. These requests are packaged into a structure that resembles the URB used by kernel device drivers. (No POSIX Async I/O support here, sorry.) It -identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint +identifies the endpoint type (``USBDEVFS_URB_TYPE_*``), endpoint (number, masked with USB_DIR_IN as appropriate), buffer and length, and a user "context" value serving to uniquely identify each request. (It's usually a pointer to per-request data.) Flags can modify requests @@ -702,30 +632,28 @@ When usbfs returns these urbs, the status value is updated, and the buffer may have been modified. Except for isochronous transfers, the actual_length is updated to say how many bytes were transferred; if the USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if -fewer bytes were read than were requested then you get an error report. - -:: +fewer bytes were read than were requested then you get an error report:: struct usbdevfs_iso_packet_desc { - unsigned int length; - unsigned int actual_length; - unsigned int status; + unsigned int length; + unsigned int actual_length; + unsigned int status; }; struct usbdevfs_urb { - unsigned char type; - unsigned char endpoint; - int status; - unsigned int flags; - void *buffer; - int buffer_length; - int actual_length; - int start_frame; - int number_of_packets; - int error_count; - unsigned int signr; - void *usercontext; - struct usbdevfs_iso_packet_desc iso_frame_desc[]; + unsigned char type; + unsigned char endpoint; + int status; + unsigned int flags; + void *buffer; + int buffer_length; + int actual_length; + int start_frame; + int number_of_packets; + int error_count; + unsigned int signr; + void *usercontext; + struct usbdevfs_iso_packet_desc iso_frame_desc[]; }; For these asynchronous requests, the file modification time reflects @@ -746,3 +674,374 @@ USBDEVFS_REAPURBNDELAY USBDEVFS_SUBMITURB *TBS* + +The USB devices +=============== + +The USB devices are now exported via debugfs: + +- ``/sys/kernel/debug/usb/devices`` ... a text file showing each of the USB + devices on known to the kernel, and their configuration descriptors. + You can also poll() this to learn about new devices. + +/sys/kernel/debug/usb/devices +----------------------------- + +This file is handy for status viewing tools in user mode, which can scan +the text format and ignore most of it. More detailed device status +(including class and vendor status) is available from device-specific +files. For information about the current format of this file, see the +``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel +sources. + +This file, in combination with the poll() system call, can also be used +to detect when devices are added or removed:: + + int fd; + struct pollfd pfd; + + fd = open("/sys/kernel/debug/usb/devices", O_RDONLY); + pfd = { fd, POLLIN, 0 }; + for (;;) { + /* The first time through, this call will return immediately. */ + poll(&pfd, 1, -1); + + /* To see what's changed, compare the file's previous and current + contents or scan the filesystem. (Scanning is more precise.) */ + } + +Note that this behavior is intended to be used for informational and +debug purposes. It would be more appropriate to use programs such as +udev or HAL to initialize a device or start a user-mode helper program, +for instance. + +In this file, each device's output has multiple lines of ASCII output. + +I made it ASCII instead of binary on purpose, so that someone +can obtain some useful data from it without the use of an +auxiliary program. However, with an auxiliary program, the numbers +in the first 4 columns of each ``T:`` line (topology info: +Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram. + +Each line is tagged with a one-character ID for that line:: + + T = Topology (etc.) + B = Bandwidth (applies only to USB host controllers, which are + virtualized as root hubs) + D = Device descriptor info. + P = Product ID info. (from Device descriptor, but they won't fit + together on one line) + S = String descriptors. + C = Configuration descriptor info. (* = active configuration) + I = Interface descriptor info. + E = Endpoint descriptor info. + +/sys/kernel/debug/usb/devices output format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Legend:: + d = decimal number (may have leading spaces or 0's) + x = hexadecimal number (may have leading spaces or 0's) + s = string + + + +Topology info +^^^^^^^^^^^^^ + +:: + + T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd + | | | | | | | | |__MaxChildren + | | | | | | | |__Device Speed in Mbps + | | | | | | |__DeviceNumber + | | | | | |__Count of devices at this level + | | | | |__Connector/Port on Parent for this device + | | | |__Parent DeviceNumber + | | |__Level in topology for this bus + | |__Bus number + |__Topology info tag + +Speed may be: + + ======= ====================================================== + 1.5 Mbit/s for low speed USB + 12 Mbit/s for full speed USB + 480 Mbit/s for high speed USB (added for USB 2.0); + also used for Wireless USB, which has no fixed speed + 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) + ======= ====================================================== + +For reasons lost in the mists of time, the Port number is always +too low by 1. For example, a device plugged into port 4 will +show up with ``Port=03``. + +Bandwidth info +^^^^^^^^^^^^^^ + +:: + + B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd + | | | |__Number of isochronous requests + | | |__Number of interrupt requests + | |__Total Bandwidth allocated to this bus + |__Bandwidth info tag + +Bandwidth allocation is an approximation of how much of one frame +(millisecond) is in use. It reflects only periodic transfers, which +are the only transfers that reserve bandwidth. Control and bulk +transfers use all other bandwidth, including reserved bandwidth that +is not used for transfers (such as for short packets). + +The percentage is how much of the "reserved" bandwidth is scheduled by +those transfers. For a low or full speed bus (loosely, "USB 1.1"), +90% of the bus bandwidth is reserved. For a high speed bus (loosely, +"USB 2.0") 80% is reserved. + + +Device descriptor info & Product ID info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd + P: Vendor=xxxx ProdID=xxxx Rev=xx.xx + +where:: + + D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd + | | | | | | |__NumberConfigurations + | | | | | |__MaxPacketSize of Default Endpoint + | | | | |__DeviceProtocol + | | | |__DeviceSubClass + | | |__DeviceClass + | |__Device USB version + |__Device info tag #1 + +where:: + + P: Vendor=xxxx ProdID=xxxx Rev=xx.xx + | | | |__Product revision number + | | |__Product ID code + | |__Vendor ID code + |__Device info tag #2 + + +String descriptor info +^^^^^^^^^^^^^^^^^^^^^^ +:: + + S: Manufacturer=ssss + | |__Manufacturer of this device as read from the device. + | For USB host controller drivers (virtual root hubs) this may + | be omitted, or (for newer drivers) will identify the kernel + | version and the driver which provides this hub emulation. + |__String info tag + + S: Product=ssss + | |__Product description of this device as read from the device. + | For older USB host controller drivers (virtual root hubs) this + | indicates the driver; for newer ones, it's a product (and vendor) + | description that often comes from the kernel's PCI ID database. + |__String info tag + + S: SerialNumber=ssss + | |__Serial Number of this device as read from the device. + | For USB host controller drivers (virtual root hubs) this is + | some unique ID, normally a bus ID (address or slot name) that + | can't be shared with any other device. + |__String info tag + + + +Configuration descriptor info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:: + + C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA + | | | | | |__MaxPower in mA + | | | | |__Attributes + | | | |__ConfiguratioNumber + | | |__NumberOfInterfaces + | |__ "*" indicates the active configuration (others are " ") + |__Config info tag + +USB devices may have multiple configurations, each of which act +rather differently. For example, a bus-powered configuration +might be much less capable than one that is self-powered. Only +one device configuration can be active at a time; most devices +have only one configuration. + +Each configuration consists of one or more interfaces. Each +interface serves a distinct "function", which is typically bound +to a different USB device driver. One common example is a USB +speaker with an audio interface for playback, and a HID interface +for use with software volume control. + +Interface descriptor info (can be multiple per Config) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:: + + I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss + | | | | | | | | |__Driver name + | | | | | | | | or "(none)" + | | | | | | | |__InterfaceProtocol + | | | | | | |__InterfaceSubClass + | | | | | |__InterfaceClass + | | | | |__NumberOfEndpoints + | | | |__AlternateSettingNumber + | | |__InterfaceNumber + | |__ "*" indicates the active altsetting (others are " ") + |__Interface info tag + +A given interface may have one or more "alternate" settings. +For example, default settings may not use more than a small +amount of periodic bandwidth. To use significant fractions +of bus bandwidth, drivers must select a non-default altsetting. + +Only one setting for an interface may be active at a time, and +only one driver may bind to an interface at a time. Most devices +have only one alternate setting per interface. + + +Endpoint descriptor info (can be multiple per Interface) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss + | | | | |__Interval (max) between transfers + | | | |__EndpointMaxPacketSize + | | |__Attributes(EndpointType) + | |__EndpointAddress(I=In,O=Out) + |__Endpoint info tag + +The interval is nonzero for all periodic (interrupt or isochronous) +endpoints. For high speed endpoints the transfer interval may be +measured in microseconds rather than milliseconds. + +For high speed periodic endpoints, the ``EndpointMaxPacketSize`` reflects +the per-microframe data transfer size. For "high bandwidth" +endpoints, that can reflect two or three packets (for up to +3KBytes every 125 usec) per endpoint. + +With the Linux-USB stack, periodic bandwidth reservations use the +transfer intervals and sizes provided by URBs, which can be less +than those found in endpoint descriptor. + +Usage examples +~~~~~~~~~~~~~~ + +If a user or script is interested only in Topology info, for +example, use something like ``grep ^T: /sys/kernel/debug/usb/devices`` +for only the Topology lines. A command like +``grep -i ^[tdp]: /sys/kernel/debug/usb/devices`` can be used to list +only the lines that begin with the characters in square brackets, +where the valid characters are TDPCIE. With a slightly more able +script, it can display any selected lines (for example, only T, D, +and P lines) and change their output format. (The ``procusb`` +Perl script is the beginning of this idea. It will list only +selected lines [selected from TBDPSCIE] or "All" lines from +``/sys/kernel/debug/usb/devices``.) + +The Topology lines can be used to generate a graphic/pictorial +of the USB devices on a system's root hub. (See more below +on how to do this.) + +The Interface lines can be used to determine what driver is +being used for each device, and which altsetting it activated. + +The Configuration lines could be used to list maximum power +(in milliamps) that a system's USB devices are using. +For example, ``grep ^C: /sys/kernel/debug/usb/devices``. + + +Here's an example, from a system which has a UHCI root hub, +an external hub connected to the root hub, and a mouse and +a serial converter connected to the external hub. + +:: + + T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 + B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 + D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0000 ProdID=0000 Rev= 0.00 + S: Product=USB UHCI Root Hub + S: SerialNumber=dce0 + C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub + E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms + + T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 + D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0451 ProdID=1446 Rev= 1.00 + C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub + E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms + + T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 + D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=04b4 ProdID=0001 Rev= 0.00 + C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse + E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms + + T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 + D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0565 ProdID=0001 Rev= 1.08 + S: Manufacturer=Peracom Networks, Inc. + S: Product=Peracom USB to Serial Converter + C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial + E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms + E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms + E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms + + +Selecting only the ``T:`` and ``I:`` lines from this (for example, by using +``procusb ti``), we have + +:: + + T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 + T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 + I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub + T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 + I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse + T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 + I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial + + +Physically this looks like (or could be converted to):: + + +------------------+ + | PC/root_hub (12)| Dev# = 1 + +------------------+ (nn) is Mbps. + Level 0 | CN.0 | CN.1 | [CN = connector/port #] + +------------------+ + / + / + +-----------------------+ + Level 1 | Dev#2: 4-port hub (12)| + +-----------------------+ + |CN.0 |CN.1 |CN.2 |CN.3 | + +-----------------------+ + \ \____________________ + \_____ \ + \ \ + +--------------------+ +--------------------+ + Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)| + +--------------------+ +--------------------+ + + + +Or, in a more tree-like structure (ports [Connectors] without +connections could be omitted):: + + PC: Dev# 1, root hub, 2 ports, 12 Mbps + |_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps + |_ CN.0: Dev #3, mouse, 1.5 Mbps + |_ CN.1: + |_ CN.2: Dev #4, serial, 12 Mbps + |_ CN.3: + |_ CN.1: diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst new file mode 100644 index 000000000000..e90e8fa95600 --- /dev/null +++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst @@ -0,0 +1,723 @@ +========================= +Writing a MUSB Glue Layer +========================= + +:Author: Apelete Seketeli + +Introduction +============ + +The Linux MUSB subsystem is part of the larger Linux USB subsystem. It +provides support for embedded USB Device Controllers (UDC) that do not +use Universal Host Controller Interface (UHCI) or Open Host Controller +Interface (OHCI). + +Instead, these embedded UDC rely on the USB On-the-Go (OTG) +specification which they implement at least partially. The silicon +reference design used in most cases is the Multipoint USB Highspeed +Dual-Role Controller (MUSB HDRC) found in the Mentor Graphics Inventraâ„¢ +design. + +As a self-taught exercise I have written an MUSB glue layer for the +Ingenic JZ4740 SoC, modelled after the many MUSB glue layers in the +kernel source tree. This layer can be found at +``drivers/usb/musb/jz4740.c``. In this documentation I will walk through the +basics of the ``jz4740.c`` glue layer, explaining the different pieces and +what needs to be done in order to write your own device glue layer. + +.. _musb-basics: + +Linux MUSB Basics +================= + +To get started on the topic, please read USB On-the-Go Basics (see +Resources) which provides an introduction of USB OTG operation at the +hardware level. A couple of wiki pages by Texas Instruments and Analog +Devices also provide an overview of the Linux kernel MUSB configuration, +albeit focused on some specific devices provided by these companies. +Finally, getting acquainted with the USB specification at USB home page +may come in handy, with practical instance provided through the Writing +USB Device Drivers documentation (again, see Resources). + +Linux USB stack is a layered architecture in which the MUSB controller +hardware sits at the lowest. The MUSB controller driver abstract the +MUSB controller hardware to the Linux USB stack:: + + ------------------------ + | | <------- drivers/usb/gadget + | Linux USB Core Stack | <------- drivers/usb/host + | | <------- drivers/usb/core + ------------------------ + ⬠+ -------------------------- + | | <------ drivers/usb/musb/musb_gadget.c + | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c + | | <------ drivers/usb/musb/musb_core.c + -------------------------- + ⬠+ --------------------------------- + | MUSB Platform Specific Driver | + | | <-- drivers/usb/musb/jz4740.c + | aka "Glue Layer" | + --------------------------------- + ⬠+ --------------------------------- + | MUSB Controller Hardware | + --------------------------------- + +As outlined above, the glue layer is actually the platform specific code +sitting in between the controller driver and the controller hardware. + +Just like a Linux USB driver needs to register itself with the Linux USB +subsystem, the MUSB glue layer needs first to register itself with the +MUSB controller driver. This will allow the controller driver to know +about which device the glue layer supports and which functions to call +when a supported device is detected or released; remember we are talking +about an embedded controller chip here, so no insertion or removal at +run-time. + +All of this information is passed to the MUSB controller driver through +a :c:type:`platform_driver` structure defined in the glue layer as:: + + static struct platform_driver jz4740_driver = { + .probe = jz4740_probe, + .remove = jz4740_remove, + .driver = { + .name = "musb-jz4740", + }, + }; + +The probe and remove function pointers are called when a matching device +is detected and, respectively, released. The name string describes the +device supported by this glue layer. In the current case it matches a +platform_device structure declared in ``arch/mips/jz4740/platform.c``. Note +that we are not using device tree bindings here. + +In order to register itself to the controller driver, the glue layer +goes through a few steps, basically allocating the controller hardware +resources and initialising a couple of circuits. To do so, it needs to +keep track of the information used throughout these steps. This is done +by defining a private ``jz4740_glue`` structure:: + + struct jz4740_glue { + struct device *dev; + struct platform_device *musb; + struct clk *clk; + }; + + +The dev and musb members are both device structure variables. The first +one holds generic information about the device, since it's the basic +device structure, and the latter holds information more closely related +to the subsystem the device is registered to. The clk variable keeps +information related to the device clock operation. + +Let's go through the steps of the probe function that leads the glue +layer to register itself to the controller driver. + +.. note:: + + For the sake of readability each function will be split in logical + parts, each part being shown as if it was independent from the others. + +.. code-block:: c + :emphasize-lines: 8,12,18 + + static int jz4740_probe(struct platform_device *pdev) + { + struct platform_device *musb; + struct jz4740_glue *glue; + struct clk *clk; + int ret; + + glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); + if (!glue) + return -ENOMEM; + + musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); + if (!musb) { + dev_err(&pdev->dev, "failed to allocate musb device\n"); + return -ENOMEM; + } + + clk = devm_clk_get(&pdev->dev, "udc"); + if (IS_ERR(clk)) { + dev_err(&pdev->dev, "failed to get clock\n"); + ret = PTR_ERR(clk); + goto err_platform_device_put; + } + + ret = clk_prepare_enable(clk); + if (ret) { + dev_err(&pdev->dev, "failed to enable clock\n"); + goto err_platform_device_put; + } + + musb->dev.parent = &pdev->dev; + + glue->dev = &pdev->dev; + glue->musb = musb; + glue->clk = clk; + + return 0; + + err_platform_device_put: + platform_device_put(musb); + return ret; + } + +The first few lines of the probe function allocate and assign the glue, +musb and clk variables. The ``GFP_KERNEL`` flag (line 8) allows the +allocation process to sleep and wait for memory, thus being usable in a +locking situation. The ``PLATFORM_DEVID_AUTO`` flag (line 12) allows +automatic allocation and management of device IDs in order to avoid +device namespace collisions with explicit IDs. With :c:func:`devm_clk_get` +(line 18) the glue layer allocates the clock -- the ``devm_`` prefix +indicates that :c:func:`clk_get` is managed: it automatically frees the +allocated clock resource data when the device is released -- and enable +it. + + + +Then comes the registration steps: + +.. code-block:: c + :emphasize-lines: 3,5,7,9,16 + + static int jz4740_probe(struct platform_device *pdev) + { + struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; + + pdata->platform_ops = &jz4740_musb_ops; + + platform_set_drvdata(pdev, glue); + + ret = platform_device_add_resources(musb, pdev->resource, + pdev->num_resources); + if (ret) { + dev_err(&pdev->dev, "failed to add resources\n"); + goto err_clk_disable; + } + + ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); + if (ret) { + dev_err(&pdev->dev, "failed to add platform_data\n"); + goto err_clk_disable; + } + + return 0; + + err_clk_disable: + clk_disable_unprepare(clk); + err_platform_device_put: + platform_device_put(musb); + return ret; + } + +The first step is to pass the device data privately held by the glue +layer on to the controller driver through :c:func:`platform_set_drvdata` +(line 7). Next is passing on the device resources information, also privately +held at that point, through :c:func:`platform_device_add_resources` (line 9). + +Finally comes passing on the platform specific data to the controller +driver (line 16). Platform data will be discussed in +:ref:`musb-dev-platform-data`, but here we are looking at the +``platform_ops`` function pointer (line 5) in ``musb_hdrc_platform_data`` +structure (line 3). This function pointer allows the MUSB controller +driver to know which function to call for device operation:: + + static const struct musb_platform_ops jz4740_musb_ops = { + .init = jz4740_musb_init, + .exit = jz4740_musb_exit, + }; + +Here we have the minimal case where only init and exit functions are +called by the controller driver when needed. Fact is the JZ4740 MUSB +controller is a basic controller, lacking some features found in other +controllers, otherwise we may also have pointers to a few other +functions like a power management function or a function to switch +between OTG and non-OTG modes, for instance. + +At that point of the registration process, the controller driver +actually calls the init function: + + .. code-block:: c + :emphasize-lines: 12,14 + + static int jz4740_musb_init(struct musb *musb) + { + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); + if (!musb->xceiv) { + pr_err("HS UDC: no transceiver configured\n"); + return -ENODEV; + } + + /* Silicon does not implement ConfigData register. + * Set dyn_fifo to avoid reading EP config from hardware. + */ + musb->dyn_fifo = true; + + musb->isr = jz4740_musb_interrupt; + + return 0; + } + +The goal of ``jz4740_musb_init()`` is to get hold of the transceiver +driver data of the MUSB controller hardware and pass it on to the MUSB +controller driver, as usual. The transceiver is the circuitry inside the +controller hardware responsible for sending/receiving the USB data. +Since it is an implementation of the physical layer of the OSI model, +the transceiver is also referred to as PHY. + +Getting hold of the ``MUSB PHY`` driver data is done with ``usb_get_phy()`` +which returns a pointer to the structure containing the driver instance +data. The next couple of instructions (line 12 and 14) are used as a +quirk and to setup IRQ handling respectively. Quirks and IRQ handling +will be discussed later in :ref:`musb-dev-quirks` and +:ref:`musb-handling-irqs`\ :: + + static int jz4740_musb_exit(struct musb *musb) + { + usb_put_phy(musb->xceiv); + + return 0; + } + +Acting as the counterpart of init, the exit function releases the MUSB +PHY driver when the controller hardware itself is about to be released. + +Again, note that init and exit are fairly simple in this case due to the +basic set of features of the JZ4740 controller hardware. When writing an +musb glue layer for a more complex controller hardware, you might need +to take care of more processing in those two functions. + +Returning from the init function, the MUSB controller driver jumps back +into the probe function:: + + static int jz4740_probe(struct platform_device *pdev) + { + ret = platform_device_add(musb); + if (ret) { + dev_err(&pdev->dev, "failed to register musb device\n"); + goto err_clk_disable; + } + + return 0; + + err_clk_disable: + clk_disable_unprepare(clk); + err_platform_device_put: + platform_device_put(musb); + return ret; + } + +This is the last part of the device registration process where the glue +layer adds the controller hardware device to Linux kernel device +hierarchy: at this stage, all known information about the device is +passed on to the Linux USB core stack: + + .. code-block:: c + :emphasize-lines: 5,6 + + static int jz4740_remove(struct platform_device *pdev) + { + struct jz4740_glue *glue = platform_get_drvdata(pdev); + + platform_device_unregister(glue->musb); + clk_disable_unprepare(glue->clk); + + return 0; + } + +Acting as the counterpart of probe, the remove function unregister the +MUSB controller hardware (line 5) and disable the clock (line 6), +allowing it to be gated. + +.. _musb-handling-irqs: + +Handling IRQs +============= + +Additionally to the MUSB controller hardware basic setup and +registration, the glue layer is also responsible for handling the IRQs: + + .. code-block:: c + :emphasize-lines: 7,9-11,14,24 + + static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) + { + unsigned long flags; + irqreturn_t retval = IRQ_NONE; + struct musb *musb = __hci; + + spin_lock_irqsave(&musb->lock, flags); + + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); + + /* + * The controller is gadget only, the state of the host mode IRQ bits is + * undefined. Mask them to make sure that the musb driver core will + * never see them set + */ + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | + MUSB_INTR_RESET | MUSB_INTR_SOF; + + if (musb->int_usb || musb->int_tx || musb->int_rx) + retval = musb_interrupt(musb); + + spin_unlock_irqrestore(&musb->lock, flags); + + return retval; + } + +Here the glue layer mostly has to read the relevant hardware registers +and pass their values on to the controller driver which will handle the +actual event that triggered the IRQ. + +The interrupt handler critical section is protected by the +:c:func:`spin_lock_irqsave` and counterpart :c:func:`spin_unlock_irqrestore` +functions (line 7 and 24 respectively), which prevent the interrupt +handler code to be run by two different threads at the same time. + +Then the relevant interrupt registers are read (line 9 to 11): + +- ``MUSB_INTRUSB``: indicates which USB interrupts are currently active, + +- ``MUSB_INTRTX``: indicates which of the interrupts for TX endpoints are + currently active, + +- ``MUSB_INTRRX``: indicates which of the interrupts for TX endpoints are + currently active. + +Note that :c:func:`musb_readb` is used to read 8-bit registers at most, while +:c:func:`musb_readw` allows us to read at most 16-bit registers. There are +other functions that can be used depending on the size of your device +registers. See ``musb_io.h`` for more information. + +Instruction on line 18 is another quirk specific to the JZ4740 USB +device controller, which will be discussed later in :ref:`musb-dev-quirks`. + +The glue layer still needs to register the IRQ handler though. Remember +the instruction on line 14 of the init function:: + + static int jz4740_musb_init(struct musb *musb) + { + musb->isr = jz4740_musb_interrupt; + + return 0; + } + +This instruction sets a pointer to the glue layer IRQ handler function, +in order for the controller hardware to call the handler back when an +IRQ comes from the controller hardware. The interrupt handler is now +implemented and registered. + +.. _musb-dev-platform-data: + +Device Platform Data +==================== + +In order to write an MUSB glue layer, you need to have some data +describing the hardware capabilities of your controller hardware, which +is called the platform data. + +Platform data is specific to your hardware, though it may cover a broad +range of devices, and is generally found somewhere in the ``arch/`` +directory, depending on your device architecture. + +For instance, platform data for the JZ4740 SoC is found in +``arch/mips/jz4740/platform.c``. In the ``platform.c`` file each device of the +JZ4740 SoC is described through a set of structures. + +Here is the part of ``arch/mips/jz4740/platform.c`` that covers the USB +Device Controller (UDC): + + .. code-block:: c + :emphasize-lines: 2,7,14-17,21,22,25,26,28,29 + + /* USB Device Controller */ + struct platform_device jz4740_udc_xceiv_device = { + .name = "usb_phy_gen_xceiv", + .id = 0, + }; + + static struct resource jz4740_udc_resources[] = { + [0] = { + .start = JZ4740_UDC_BASE_ADDR, + .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1, + .flags = IORESOURCE_MEM, + }, + [1] = { + .start = JZ4740_IRQ_UDC, + .end = JZ4740_IRQ_UDC, + .flags = IORESOURCE_IRQ, + .name = "mc", + }, + }; + + struct platform_device jz4740_udc_device = { + .name = "musb-jz4740", + .id = -1, + .dev = { + .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask, + .coherent_dma_mask = DMA_BIT_MASK(32), + }, + .num_resources = ARRAY_SIZE(jz4740_udc_resources), + .resource = jz4740_udc_resources, + }; + +The ``jz4740_udc_xceiv_device`` platform device structure (line 2) +describes the UDC transceiver with a name and id number. + +At the time of this writing, note that ``usb_phy_gen_xceiv`` is the +specific name to be used for all transceivers that are either built-in +with reference USB IP or autonomous and doesn't require any PHY +programming. You will need to set ``CONFIG_NOP_USB_XCEIV=y`` in the +kernel configuration to make use of the corresponding transceiver +driver. The id field could be set to -1 (equivalent to +``PLATFORM_DEVID_NONE``), -2 (equivalent to ``PLATFORM_DEVID_AUTO``) or +start with 0 for the first device of this kind if we want a specific id +number. + +The ``jz4740_udc_resources`` resource structure (line 7) defines the UDC +registers base addresses. + +The first array (line 9 to 11) defines the UDC registers base memory +addresses: start points to the first register memory address, end points +to the last register memory address and the flags member defines the +type of resource we are dealing with. So ``IORESOURCE_MEM`` is used to +define the registers memory addresses. The second array (line 14 to 17) +defines the UDC IRQ registers addresses. Since there is only one IRQ +register available for the JZ4740 UDC, start and end point at the same +address. The ``IORESOURCE_IRQ`` flag tells that we are dealing with IRQ +resources, and the name ``mc`` is in fact hard-coded in the MUSB core in +order for the controller driver to retrieve this IRQ resource by +querying it by its name. + +Finally, the ``jz4740_udc_device`` platform device structure (line 21) +describes the UDC itself. + +The ``musb-jz4740`` name (line 22) defines the MUSB driver that is used +for this device; remember this is in fact the name that we used in the +``jz4740_driver`` platform driver structure in :ref:`musb-basics`. +The id field (line 23) is set to -1 (equivalent to ``PLATFORM_DEVID_NONE``) +since we do not need an id for the device: the MUSB controller driver was +already set to allocate an automatic id in :ref:`musb-basics`. In the dev field +we care for DMA related information here. The ``dma_mask`` field (line 25) +defines the width of the DMA mask that is going to be used, and +``coherent_dma_mask`` (line 26) has the same purpose but for the +``alloc_coherent`` DMA mappings: in both cases we are using a 32 bits mask. +Then the resource field (line 29) is simply a pointer to the resource +structure defined before, while the ``num_resources`` field (line 28) keeps +track of the number of arrays defined in the resource structure (in this +case there were two resource arrays defined before). + +With this quick overview of the UDC platform data at the ``arch/`` level now +done, let's get back to the MUSB glue layer specific platform data in +``drivers/usb/musb/jz4740.c``: + + .. code-block:: c + :emphasize-lines: 3,5,7-9,11 + + static struct musb_hdrc_config jz4740_musb_config = { + /* Silicon does not implement USB OTG. */ + .multipoint = 0, + /* Max EPs scanned, driver will decide which EP can be used. */ + .num_eps = 4, + /* RAMbits needed to configure EPs from table */ + .ram_bits = 9, + .fifo_cfg = jz4740_musb_fifo_cfg, + .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg), + }; + + static struct musb_hdrc_platform_data jz4740_musb_platform_data = { + .mode = MUSB_PERIPHERAL, + .config = &jz4740_musb_config, + }; + +First the glue layer configures some aspects of the controller driver +operation related to the controller hardware specifics. This is done +through the ``jz4740_musb_config`` :c:type:`musb_hdrc_config` structure. + +Defining the OTG capability of the controller hardware, the multipoint +member (line 3) is set to 0 (equivalent to false) since the JZ4740 UDC +is not OTG compatible. Then ``num_eps`` (line 5) defines the number of USB +endpoints of the controller hardware, including endpoint 0: here we have +3 endpoints + endpoint 0. Next is ``ram_bits`` (line 7) which is the width +of the RAM address bus for the MUSB controller hardware. This +information is needed when the controller driver cannot automatically +configure endpoints by reading the relevant controller hardware +registers. This issue will be discussed when we get to device quirks in +:ref:`musb-dev-quirks`. Last two fields (line 8 and 9) are also +about device quirks: ``fifo_cfg`` points to the USB endpoints configuration +table and ``fifo_cfg_size`` keeps track of the size of the number of +entries in that configuration table. More on that later in +:ref:`musb-dev-quirks`. + +Then this configuration is embedded inside ``jz4740_musb_platform_data`` +:c:type:`musb_hdrc_platform_data` structure (line 11): config is a pointer to +the configuration structure itself, and mode tells the controller driver +if the controller hardware may be used as ``MUSB_HOST`` only, +``MUSB_PERIPHERAL`` only or ``MUSB_OTG`` which is a dual mode. + +Remember that ``jz4740_musb_platform_data`` is then used to convey +platform data information as we have seen in the probe function in +:ref:`musb-basics`. + +.. _musb-dev-quirks: + +Device Quirks +============= + +Completing the platform data specific to your device, you may also need +to write some code in the glue layer to work around some device specific +limitations. These quirks may be due to some hardware bugs, or simply be +the result of an incomplete implementation of the USB On-the-Go +specification. + +The JZ4740 UDC exhibits such quirks, some of which we will discuss here +for the sake of insight even though these might not be found in the +controller hardware you are working on. + +Let's get back to the init function first: + + .. code-block:: c + :emphasize-lines: 12 + + static int jz4740_musb_init(struct musb *musb) + { + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); + if (!musb->xceiv) { + pr_err("HS UDC: no transceiver configured\n"); + return -ENODEV; + } + + /* Silicon does not implement ConfigData register. + * Set dyn_fifo to avoid reading EP config from hardware. + */ + musb->dyn_fifo = true; + + musb->isr = jz4740_musb_interrupt; + + return 0; + } + +Instruction on line 12 helps the MUSB controller driver to work around +the fact that the controller hardware is missing registers that are used +for USB endpoints configuration. + +Without these registers, the controller driver is unable to read the +endpoints configuration from the hardware, so we use line 12 instruction +to bypass reading the configuration from silicon, and rely on a +hard-coded table that describes the endpoints configuration instead:: + + static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = { + { .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, }, + { .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, }, + { .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, }, + }; + +Looking at the configuration table above, we see that each endpoints is +described by three fields: ``hw_ep_num`` is the endpoint number, style is +its direction (either ``FIFO_TX`` for the controller driver to send packets +in the controller hardware, or ``FIFO_RX`` to receive packets from +hardware), and maxpacket defines the maximum size of each data packet +that can be transmitted over that endpoint. Reading from the table, the +controller driver knows that endpoint 1 can be used to send and receive +USB data packets of 512 bytes at once (this is in fact a bulk in/out +endpoint), and endpoint 2 can be used to send data packets of 64 bytes +at once (this is in fact an interrupt endpoint). + +Note that there is no information about endpoint 0 here: that one is +implemented by default in every silicon design, with a predefined +configuration according to the USB specification. For more examples of +endpoint configuration tables, see ``musb_core.c``. + +Let's now get back to the interrupt handler function: + + .. code-block:: c + :emphasize-lines: 18-19 + + static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) + { + unsigned long flags; + irqreturn_t retval = IRQ_NONE; + struct musb *musb = __hci; + + spin_lock_irqsave(&musb->lock, flags); + + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); + + /* + * The controller is gadget only, the state of the host mode IRQ bits is + * undefined. Mask them to make sure that the musb driver core will + * never see them set + */ + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | + MUSB_INTR_RESET | MUSB_INTR_SOF; + + if (musb->int_usb || musb->int_tx || musb->int_rx) + retval = musb_interrupt(musb); + + spin_unlock_irqrestore(&musb->lock, flags); + + return retval; + } + +Instruction on line 18 above is a way for the controller driver to work +around the fact that some interrupt bits used for USB host mode +operation are missing in the ``MUSB_INTRUSB`` register, thus left in an +undefined hardware state, since this MUSB controller hardware is used in +peripheral mode only. As a consequence, the glue layer masks these +missing bits out to avoid parasite interrupts by doing a logical AND +operation between the value read from ``MUSB_INTRUSB`` and the bits that +are actually implemented in the register. + +These are only a couple of the quirks found in the JZ4740 USB device +controller. Some others were directly addressed in the MUSB core since +the fixes were generic enough to provide a better handling of the issues +for others controller hardware eventually. + +Conclusion +========== + +Writing a Linux MUSB glue layer should be a more accessible task, as +this documentation tries to show the ins and outs of this exercise. + +The JZ4740 USB device controller being fairly simple, I hope its glue +layer serves as a good example for the curious mind. Used with the +current MUSB glue layers, this documentation should provide enough +guidance to get started; should anything gets out of hand, the linux-usb +mailing list archive is another helpful resource to browse through. + +Acknowledgements +================ + +Many thanks to Lars-Peter Clausen and Maarten ter Huurne for answering +my questions while I was writing the JZ4740 glue layer and for helping +me out getting the code in good shape. + +I would also like to thank the Qi-Hardware community at large for its +cheerful guidance and support. + +Resources +========= + +USB Home Page: http://www.usb.org + +linux-usb Mailing List Archives: http://marc.info/?l=linux-usb + +USB On-the-Go Basics: +http://www.maximintegrated.com/app-notes/index.mvp/id/1822 + +:ref:`Writing USB Device Drivers <writing-usb-driver>` + +Texas Instruments USB Configuration Wiki Page: +http://processors.wiki.ti.com/index.php/Usbgeneralpage + +Analog Devices Blackfin MUSB Configuration: +http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst new file mode 100644 index 000000000000..69f077dcdb78 --- /dev/null +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -0,0 +1,326 @@ +.. _writing-usb-driver: + +========================== +Writing USB Device Drivers +========================== + +:Author: Greg Kroah-Hartman + +Introduction +============ + +The Linux USB subsystem has grown from supporting only two different +types of devices in the 2.2.7 kernel (mice and keyboards), to over 20 +different types of devices in the 2.4 kernel. Linux currently supports +almost all USB class devices (standard types of devices like keyboards, +mice, modems, printers and speakers) and an ever-growing number of +vendor-specific devices (such as USB to serial converters, digital +cameras, Ethernet devices and MP3 players). For a full list of the +different USB devices currently supported, see Resources. + +The remaining kinds of USB devices that do not have support on Linux are +almost all vendor-specific devices. Each vendor decides to implement a +custom protocol to talk to their device, so a custom driver usually +needs to be created. Some vendors are open with their USB protocols and +help with the creation of Linux drivers, while others do not publish +them, and developers are forced to reverse-engineer. See Resources for +some links to handy reverse-engineering tools. + +Because each different protocol causes a new driver to be created, I +have written a generic USB driver skeleton, modelled after the +pci-skeleton.c file in the kernel source tree upon which many PCI +network drivers have been based. This USB skeleton can be found at +drivers/usb/usb-skeleton.c in the kernel source tree. In this article I +will walk through the basics of the skeleton driver, explaining the +different pieces and what needs to be done to customize it to your +specific device. + +Linux USB Basics +================ + +If you are going to write a Linux USB driver, please become familiar +with the USB protocol specification. It can be found, along with many +other useful documents, at the USB home page (see Resources). An +excellent introduction to the Linux USB subsystem can be found at the +USB Working Devices List (see Resources). It explains how the Linux USB +subsystem is structured and introduces the reader to the concept of USB +urbs (USB Request Blocks), which are essential to USB drivers. + +The first thing a Linux USB driver needs to do is register itself with +the Linux USB subsystem, giving it some information about which devices +the driver supports and which functions to call when a device supported +by the driver is inserted or removed from the system. All of this +information is passed to the USB subsystem in the :c:type:`usb_driver` +structure. The skeleton driver declares a :c:type:`usb_driver` as:: + + static struct usb_driver skel_driver = { + .name = "skeleton", + .probe = skel_probe, + .disconnect = skel_disconnect, + .fops = &skel_fops, + .minor = USB_SKEL_MINOR_BASE, + .id_table = skel_table, + }; + + +The variable name is a string that describes the driver. It is used in +informational messages printed to the system log. The probe and +disconnect function pointers are called when a device that matches the +information provided in the ``id_table`` variable is either seen or +removed. + +The fops and minor variables are optional. Most USB drivers hook into +another kernel subsystem, such as the SCSI, network or TTY subsystem. +These types of drivers register themselves with the other kernel +subsystem, and any user-space interactions are provided through that +interface. But for drivers that do not have a matching kernel subsystem, +such as MP3 players or scanners, a method of interacting with user space +is needed. The USB subsystem provides a way to register a minor device +number and a set of :c:type:`file_operations` function pointers that enable +this user-space interaction. The skeleton driver needs this kind of +interface, so it provides a minor starting number and a pointer to its +:c:type:`file_operations` functions. + +The USB driver is then registered with a call to :c:func:`usb_register`, +usually in the driver's init function, as shown here:: + + static int __init usb_skel_init(void) + { + int result; + + /* register this driver with the USB subsystem */ + result = usb_register(&skel_driver); + if (result < 0) { + err("usb_register failed for the "__FILE__ "driver." + "Error number %d", result); + return -1; + } + + return 0; + } + module_init(usb_skel_init); + + +When the driver is unloaded from the system, it needs to deregister +itself with the USB subsystem. This is done with the :c:func:`usb_deregister` +function:: + + static void __exit usb_skel_exit(void) + { + /* deregister this driver with the USB subsystem */ + usb_deregister(&skel_driver); + } + module_exit(usb_skel_exit); + + +To enable the linux-hotplug system to load the driver automatically when +the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``. +The following code tells the hotplug scripts that this module supports a +single device with a specific vendor and product ID:: + + /* table of devices that work with this driver */ + static struct usb_device_id skel_table [] = { + { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) }, + { } /* Terminating entry */ + }; + MODULE_DEVICE_TABLE (usb, skel_table); + + +There are other macros that can be used in describing a struct +:c:type:`usb_device_id` for drivers that support a whole class of USB +drivers. See :ref:`usb.h <usb_header>` for more information on this. + +Device operation +================ + +When a device is plugged into the USB bus that matches the device ID +pattern that your driver registered with the USB core, the probe +function is called. The :c:type:`usb_device` structure, interface number and +the interface ID are passed to the function:: + + static int skel_probe(struct usb_interface *interface, + const struct usb_device_id *id) + + +The driver now needs to verify that this device is actually one that it +can accept. If so, it returns 0. If not, or if any error occurs during +initialization, an errorcode (such as ``-ENOMEM`` or ``-ENODEV``) is +returned from the probe function. + +In the skeleton driver, we determine what end points are marked as +bulk-in and bulk-out. We create buffers to hold the data that will be +sent and received from the device, and a USB urb to write data to the +device is initialized. + +Conversely, when the device is removed from the USB bus, the disconnect +function is called with the device pointer. The driver needs to clean +any private data that has been allocated at this time and to shut down +any pending urbs that are in the USB system. + +Now that the device is plugged into the system and the driver is bound +to the device, any of the functions in the :c:type:`file_operations` structure +that were passed to the USB subsystem will be called from a user program +trying to talk to the device. The first function called will be open, as +the program tries to open the device for I/O. We increment our private +usage count and save a pointer to our internal structure in the file +structure. This is done so that future calls to file operations will +enable the driver to determine which device the user is addressing. All +of this is done with the following code:: + + /* increment our usage count for the module */ + ++skel->open_count; + + /* save our object in the file's private structure */ + file->private_data = dev; + + +After the open function is called, the read and write functions are +called to receive and send data to the device. In the ``skel_write`` +function, we receive a pointer to some data that the user wants to send +to the device and the size of the data. The function determines how much +data it can send to the device based on the size of the write urb it has +created (this size depends on the size of the bulk out end point that +the device has). Then it copies the data from user space to kernel +space, points the urb to the data and submits the urb to the USB +subsystem. This can be seen in the following code:: + + /* we can only write as much as 1 urb will hold */ + bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count; + + /* copy the data from user space into our urb */ + copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written); + + /* set up our urb */ + usb_fill_bulk_urb(skel->write_urb, + skel->dev, + usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr), + skel->write_urb->transfer_buffer, + bytes_written, + skel_write_bulk_callback, + skel); + + /* send the data out the bulk port */ + result = usb_submit_urb(skel->write_urb); + if (result) { + err("Failed submitting write urb, error %d", result); + } + + +When the write urb is filled up with the proper information using the +:c:func:`usb_fill_bulk_urb` function, we point the urb's completion callback +to call our own ``skel_write_bulk_callback`` function. This function is +called when the urb is finished by the USB subsystem. The callback +function is called in interrupt context, so caution must be taken not to +do very much processing at that time. Our implementation of +``skel_write_bulk_callback`` merely reports if the urb was completed +successfully or not and then returns. + +The read function works a bit differently from the write function in +that we do not use an urb to transfer data from the device to the +driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used +to send or receive data from a device without having to create urbs and +handle urb completion callback functions. We call the :c:func:`usb_bulk_msg` +function, giving it a buffer into which to place any data received from +the device and a timeout value. If the timeout period expires without +receiving any data from the device, the function will fail and return an +error message. This can be shown with the following code:: + + /* do an immediate bulk read to get data from the device */ + retval = usb_bulk_msg (skel->dev, + usb_rcvbulkpipe (skel->dev, + skel->bulk_in_endpointAddr), + skel->bulk_in_buffer, + skel->bulk_in_size, + &count, HZ*10); + /* if the read was successful, copy the data to user space */ + if (!retval) { + if (copy_to_user (buffer, skel->bulk_in_buffer, count)) + retval = -EFAULT; + else + retval = count; + } + + +The :c:func:`usb_bulk_msg` function can be very useful for doing single reads +or writes to a device; however, if you need to read or write constantly to +a device, it is recommended to set up your own urbs and submit them to +the USB subsystem. + +When the user program releases the file handle that it has been using to +talk to the device, the release function in the driver is called. In +this function we decrement our private usage count and wait for possible +pending writes:: + + /* decrement our usage count for the device */ + --skel->open_count; + + +One of the more difficult problems that USB drivers must be able to +handle smoothly is the fact that the USB device may be removed from the +system at any point in time, even if a program is currently talking to +it. It needs to be able to shut down any current reads and writes and +notify the user-space programs that the device is no longer there. The +following code (function ``skel_delete``) is an example of how to do +this:: + + static inline void skel_delete (struct usb_skel *dev) + { + kfree (dev->bulk_in_buffer); + if (dev->bulk_out_buffer != NULL) + usb_free_coherent (dev->udev, dev->bulk_out_size, + dev->bulk_out_buffer, + dev->write_urb->transfer_dma); + usb_free_urb (dev->write_urb); + kfree (dev); + } + + +If a program currently has an open handle to the device, we reset the +flag ``device_present``. For every read, write, release and other +functions that expect a device to be present, the driver first checks +this flag to see if the device is still present. If not, it releases +that the device has disappeared, and a ``-ENODEV`` error is returned to the +user-space program. When the release function is eventually called, it +determines if there is no device and if not, it does the cleanup that +the ``skel_disconnect`` function normally does if there are no open files +on the device (see Listing 5). + +Isochronous Data +================ + +This usb-skeleton driver does not have any examples of interrupt or +isochronous data being sent to or from the device. Interrupt data is +sent almost exactly as bulk data is, with a few minor exceptions. +Isochronous data works differently with continuous streams of data being +sent to or from the device. The audio and video camera drivers are very +good examples of drivers that handle isochronous data and will be useful +if you also need to do this. + +Conclusion +========== + +Writing Linux USB device drivers is not a difficult task as the +usb-skeleton driver shows. This driver, combined with the other current +USB drivers, should provide enough examples to help a beginning author +create a working driver in a minimal amount of time. The linux-usb-devel +mailing list archives also contain a lot of helpful information. + +Resources +========= + +The Linux USB Project: +http://www.linux-usb.org/ + +Linux Hotplug Project: +http://linux-hotplug.sourceforge.net/ + +Linux USB Working Devices List: +http://www.qbik.ch/usb/devices/ + +linux-usb-devel Mailing List Archives: +http://marc.theaimsgroup.com/?l=linux-usb-devel + +Programming Guide for Linux USB Device Drivers: +http://usb.cs.tum.edu/usbdoc + +USB Home Page: http://www.usb.org diff --git a/Documentation/driver-api/vme.rst b/Documentation/driver-api/vme.rst index 89776fb3c8bd..def139c13410 100644 --- a/Documentation/driver-api/vme.rst +++ b/Documentation/driver-api/vme.rst @@ -6,36 +6,15 @@ Driver registration As with other subsystems within the Linux kernel, VME device drivers register with the VME subsystem, typically called from the devices init routine. This is -achieved via a call to the following function: +achieved via a call to :c:func:`vme_register_driver`. -.. code-block:: c - - int vme_register_driver (struct vme_driver *driver, unsigned int ndevs); +A pointer to a structure of type :c:type:`struct vme_driver <vme_driver>` must +be provided to the registration function. Along with the maximum number of +devices your driver is able to support. -If driver registration is successful this function returns zero, if an error -occurred a negative error code will be returned. - -A pointer to a structure of type 'vme_driver' must be provided to the -registration function. Along with ndevs, which is the number of devices your -driver is able to support. The structure is as follows: - -.. code-block:: c - - struct vme_driver { - struct list_head node; - const char *name; - int (*match)(struct vme_dev *); - int (*probe)(struct vme_dev *); - int (*remove)(struct vme_dev *); - void (*shutdown)(void); - struct device_driver driver; - struct list_head devices; - unsigned int ndev; - }; - -At the minimum, the '.name', '.match' and '.probe' elements of this structure -should be correctly set. The '.name' element is a pointer to a string holding -the device driver's name. +At the minimum, the '.name', '.match' and '.probe' elements of +:c:type:`struct vme_driver <vme_driver>` should be correctly set. The '.name' +element is a pointer to a string holding the device driver's name. The '.match' function allows control over which VME devices should be registered with the driver. The match function should return 1 if a device should be @@ -54,29 +33,16 @@ the number of devices probed to one: } The '.probe' element should contain a pointer to the probe routine. The -probe routine is passed a 'struct vme_dev' pointer as an argument. The -'struct vme_dev' structure looks like the following: - -.. code-block:: c - - struct vme_dev { - int num; - struct vme_bridge *bridge; - struct device dev; - struct list_head drv_list; - struct list_head bridge_list; - }; +probe routine is passed a :c:type:`struct vme_dev <vme_dev>` pointer as an +argument. Here, the 'num' field refers to the sequential device ID for this specific driver. The bridge number (or bus number) can be accessed using dev->bridge->num. -A function is also provided to unregister the driver from the VME core and is -usually called from the device driver's exit routine: - -.. code-block:: c - - void vme_unregister_driver (struct vme_driver *driver); +A function is also provided to unregister the driver from the VME core called +:c:func:`vme_unregister_driver` and should usually be called from the device +driver's exit routine. Resource management @@ -90,47 +56,29 @@ driver is called. The probe routine is passed a pointer to the devices device structure. This pointer should be saved, it will be required for requesting VME resources. -The driver can request ownership of one or more master windows, slave windows -and/or dma channels. Rather than allowing the device driver to request a -specific window or DMA channel (which may be used by a different driver) this -driver allows a resource to be assigned based on the required attributes of the -driver in question: - -.. code-block:: c - - struct vme_resource * vme_master_request(struct vme_dev *dev, - u32 aspace, u32 cycle, u32 width); - - struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace, - u32 cycle); - - struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route); - -For slave windows these attributes are split into the VME address spaces that -need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'. -Master windows add a further set of attributes in 'width' specifying the -required data transfer widths. These attributes are defined as bitmasks and as -such any combination of the attributes can be requested for a single window, -the core will assign a window that meets the requirements, returning a pointer -of type vme_resource that should be used to identify the allocated resource -when it is used. For DMA controllers, the request function requires the -potential direction of any transfers to be provided in the route attributes. -This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can -support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation. -If an unallocated window fitting the requirements can not be found a NULL -pointer will be returned. +The driver can request ownership of one or more master windows +(:c:func:`vme_master_request`), slave windows (:c:func:`vme_slave_request`) +and/or dma channels (:c:func:`vme_dma_request`). Rather than allowing the device +driver to request a specific window or DMA channel (which may be used by a +different driver) the API allows a resource to be assigned based on the required +attributes of the driver in question. For slave windows these attributes are +split into the VME address spaces that need to be accessed in 'aspace' and VME +bus cycle types required in 'cycle'. Master windows add a further set of +attributes in 'width' specifying the required data transfer widths. These +attributes are defined as bitmasks and as such any combination of the +attributes can be requested for a single window, the core will assign a window +that meets the requirements, returning a pointer of type vme_resource that +should be used to identify the allocated resource when it is used. For DMA +controllers, the request function requires the potential direction of any +transfers to be provided in the route attributes. This is typically VME-to-MEM +and/or MEM-to-VME, though some hardware can support VME-to-VME and MEM-to-MEM +transfers as well as test pattern generation. If an unallocated window fitting +the requirements can not be found a NULL pointer will be returned. Functions are also provided to free window allocations once they are no longer -required. These functions should be passed the pointer to the resource provided -during resource allocation: - -.. code-block:: c - - void vme_master_free(struct vme_resource *res); - - void vme_slave_free(struct vme_resource *res); - - void vme_dma_free(struct vme_resource *res); +required. These functions (:c:func:`vme_master_free`, :c:func:`vme_slave_free` +and :c:func:`vme_dma_free`) should be passed the pointer to the resource +provided during resource allocation. Master windows @@ -144,61 +92,22 @@ the underlying chipset. A window must be configured before it can be used. Master window configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once a master window has been assigned the following functions can be used to -configure it and retrieve the current settings: - -.. code-block:: c - - int vme_master_set (struct vme_resource *res, int enabled, - unsigned long long base, unsigned long long size, u32 aspace, - u32 cycle, u32 width); - - int vme_master_get (struct vme_resource *res, int *enabled, - unsigned long long *base, unsigned long long *size, u32 *aspace, - u32 *cycle, u32 *width); - -The address spaces, transfer widths and cycle types are the same as described +Once a master window has been assigned :c:func:`vme_master_set` can be used to +configure it and :c:func:`vme_master_get` to retrieve the current settings. The +address spaces, transfer widths and cycle types are the same as described under resource management, however some of the options are mutually exclusive. For example, only one address space may be specified. -These functions return 0 on success or an error code should the call fail. - Master window access ~~~~~~~~~~~~~~~~~~~~ -The following functions can be used to read from and write to configured master -windows. These functions return the number of bytes copied: - -.. code-block:: c - - ssize_t vme_master_read(struct vme_resource *res, void *buf, - size_t count, loff_t offset); - - ssize_t vme_master_write(struct vme_resource *res, void *buf, - size_t count, loff_t offset); - -In addition to simple reads and writes, a function is provided to do a -read-modify-write transaction. This function returns the original value of the -VME bus location : - -.. code-block:: c - - unsigned int vme_master_rmw (struct vme_resource *res, - unsigned int mask, unsigned int compare, unsigned int swap, - loff_t offset); - -This functions by reading the offset, applying the mask. If the bits selected in -the mask match with the values of the corresponding bits in the compare field, -the value of swap is written the specified offset. - -Parts of a VME window can be mapped into user space memory using the following -function: +The function :c:func:`vme_master_read` can be used to read from and +:c:func:`vme_master_write` used to write to configured master windows. -.. code-block:: c - - int vme_master_mmap(struct vme_resource *resource, - struct vm_area_struct *vma) +In addition to simple reads and writes, :c:func:`vme_master_rmw` is provided to +do a read-modify-write transaction. Parts of a VME window can also be mapped +into user space memory using :c:func:`vme_master_mmap`. Slave windows @@ -213,41 +122,23 @@ it can be used. Slave window configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once a slave window has been assigned the following functions can be used to -configure it and retrieve the current settings: - -.. code-block:: c - - int vme_slave_set (struct vme_resource *res, int enabled, - unsigned long long base, unsigned long long size, - dma_addr_t mem, u32 aspace, u32 cycle); - - int vme_slave_get (struct vme_resource *res, int *enabled, - unsigned long long *base, unsigned long long *size, - dma_addr_t *mem, u32 *aspace, u32 *cycle); +Once a slave window has been assigned :c:func:`vme_slave_set` can be used to +configure it and :c:func:`vme_slave_get` to retrieve the current settings. The address spaces, transfer widths and cycle types are the same as described under resource management, however some of the options are mutually exclusive. For example, only one address space may be specified. -These functions return 0 on success or an error code should the call fail. - Slave window buffer allocation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Functions are provided to allow the user to allocate and free a contiguous -buffers which will be accessible by the VME bridge. These functions do not have -to be used, other methods can be used to allocate a buffer, though care must be -taken to ensure that they are contiguous and accessible by the VME bridge: - -.. code-block:: c - - void * vme_alloc_consistent(struct vme_resource *res, size_t size, - dma_addr_t *mem); - - void vme_free_consistent(struct vme_resource *res, size_t size, - void *virt, dma_addr_t mem); +Functions are provided to allow the user to allocate +(:c:func:`vme_alloc_consistent`) and free (:c:func:`vme_free_consistent`) +contiguous buffers which will be accessible by the VME bridge. These functions +do not have to be used, other methods can be used to allocate a buffer, though +care must be taken to ensure that they are contiguous and accessible by the VME +bridge. Slave window access @@ -269,29 +160,18 @@ executed, reused and destroyed. List Management ~~~~~~~~~~~~~~~ -The following functions are provided to create and destroy DMA lists. Execution -of a list will not automatically destroy the list, thus enabling a list to be -reused for repetitive tasks: - -.. code-block:: c - - struct vme_dma_list *vme_new_dma_list(struct vme_resource *res); - - int vme_dma_list_free(struct vme_dma_list *list); +The function :c:func:`vme_new_dma_list` is provided to create and +:c:func:`vme_dma_list_free` to destroy DMA lists. Execution of a list will not +automatically destroy the list, thus enabling a list to be reused for repetitive +tasks. List Population ~~~~~~~~~~~~~~~ -An item can be added to a list using the following function ( the source and +An item can be added to a list using :c:func:`vme_dma_list_add` (the source and destination attributes need to be created before calling this function, this is -covered under "Transfer Attributes"): - -.. code-block:: c - - int vme_dma_list_add(struct vme_dma_list *list, - struct vme_dma_attr *src, struct vme_dma_attr *dest, - size_t count); +covered under "Transfer Attributes"). .. note:: @@ -310,41 +190,19 @@ an item to a list. This is due to the diverse attributes required for each type of source and destination. There are functions to create attributes for PCI, VME and pattern sources and destinations (where appropriate): -Pattern source: - -.. code-block:: c - - struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type); - -PCI source or destination: - -.. code-block:: c - - struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem); - -VME source or destination: + - PCI source or destination: :c:func:`vme_dma_pci_attribute` + - VME source or destination: :c:func:`vme_dma_vme_attribute` + - Pattern source: :c:func:`vme_dma_pattern_attribute` -.. code-block:: c - - struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base, - u32 aspace, u32 cycle, u32 width); - -The following function should be used to free an attribute: - -.. code-block:: c - - void vme_dma_free_attribute(struct vme_dma_attr *attr); +The function :c:func:`vme_dma_free_attribute` should be used to free an +attribute. List Execution ~~~~~~~~~~~~~~ -The following function queues a list for execution. The function will return -once the list has been executed: - -.. code-block:: c - - int vme_dma_list_exec(struct vme_dma_list *list); +The function :c:func:`vme_dma_list_exec` queues a list for execution and will +return once the list has been executed. Interrupts @@ -358,20 +216,13 @@ specific VME level and status IDs. Attaching Interrupt Handlers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following functions can be used to attach and free a specific VME level and -status ID combination. Any given combination can only be assigned a single -callback function. A void pointer parameter is provided, the value of which is -passed to the callback function, the use of this pointer is user undefined: - -.. code-block:: c - - int vme_irq_request(struct vme_dev *dev, int level, int statid, - void (*callback)(int, int, void *), void *priv); - - void vme_irq_free(struct vme_dev *dev, int level, int statid); - -The callback parameters are as follows. Care must be taken in writing a callback -function, callback functions run in interrupt context: +The function :c:func:`vme_irq_request` can be used to attach and +:c:func:`vme_irq_free` to free a specific VME level and status ID combination. +Any given combination can only be assigned a single callback function. A void +pointer parameter is provided, the value of which is passed to the callback +function, the use of this pointer is user undefined. The callback parameters are +as follows. Care must be taken in writing a callback function, callback +functions run in interrupt context: .. code-block:: c @@ -381,12 +232,8 @@ function, callback functions run in interrupt context: Interrupt Generation ~~~~~~~~~~~~~~~~~~~~ -The following function can be used to generate a VME interrupt at a given VME -level and VME status ID: - -.. code-block:: c - - int vme_irq_generate(struct vme_dev *dev, int level, int statid); +The function :c:func:`vme_irq_generate` can be used to generate a VME interrupt +at a given VME level and VME status ID. Location monitors @@ -399,54 +246,29 @@ monitor. Location Monitor Management ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following functions are provided to request the use of a block of location -monitors and to free them after they are no longer required: - -.. code-block:: c - - struct vme_resource * vme_lm_request(struct vme_dev *dev); - - void vme_lm_free(struct vme_resource * res); - -Each block may provide a number of location monitors, monitoring adjacent -locations. The following function can be used to determine how many locations -are provided: - -.. code-block:: c - - int vme_lm_count(struct vme_resource * res); +The function :c:func:`vme_lm_request` is provided to request the use of a block +of location monitors and :c:func:`vme_lm_free` to free them after they are no +longer required. Each block may provide a number of location monitors, +monitoring adjacent locations. The function :c:func:`vme_lm_count` can be used +to determine how many locations are provided. Location Monitor Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once a bank of location monitors has been allocated, the following functions -are provided to configure the location and mode of the location monitor: - -.. code-block:: c - - int vme_lm_set(struct vme_resource *res, unsigned long long base, - u32 aspace, u32 cycle); - - int vme_lm_get(struct vme_resource *res, unsigned long long *base, - u32 *aspace, u32 *cycle); +Once a bank of location monitors has been allocated, the function +:c:func:`vme_lm_set` is provided to configure the location and mode of the +location monitor. The function :c:func:`vme_lm_get` can be used to retrieve +existing settings. Location Monitor Use ~~~~~~~~~~~~~~~~~~~~ -The following functions allow a callback to be attached and detached from each -location monitor location. Each location monitor can monitor a number of -adjacent locations: - -.. code-block:: c - - int vme_lm_attach(struct vme_resource *res, int num, - void (*callback)(void *)); - - int vme_lm_detach(struct vme_resource *res, int num); - -The callback function is declared as follows. +The function :c:func:`vme_lm_attach` enables a callback to be attached and +:c:func:`vme_lm_detach` allows on to be detached from each location monitor +location. Each location monitor can monitor a number of adjacent locations. The +callback function is declared as follows. .. code-block:: c @@ -456,19 +278,20 @@ The callback function is declared as follows. Slot Detection -------------- -This function returns the slot ID of the provided bridge. - -.. code-block:: c - - int vme_slot_num(struct vme_dev *dev); +The function :c:func:`vme_slot_num` returns the slot ID of the provided bridge. Bus Detection ------------- -This function returns the bus ID of the provided bridge. +The function :c:func:`vme_bus_num` returns the bus ID of the provided bridge. -.. code-block:: c - int vme_bus_num(struct vme_dev *dev); +VME API +------- + +.. kernel-doc:: include/linux/vme.h + :internal: +.. kernel-doc:: drivers/vme/vme.c + :export: diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index bf34d5b3a733..e72587fe477d 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -342,8 +342,10 @@ PER-CPU MEM devm_free_percpu() PCI - pcim_enable_device() : after success, all PCI ops become managed - pcim_pin_device() : keep PCI device enabled after release + devm_pci_remap_cfgspace() : ioremap PCI configuration space + devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource + pcim_enable_device() : after success, all PCI ops become managed + pcim_pin_device() : keep PCI device enabled after release PHY devm_usb_get_phy() diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/README index 93e63a9af30b..2c00b072a4c8 100644 --- a/Documentation/early-userspace/README +++ b/Documentation/early-userspace/README @@ -86,7 +86,7 @@ early userspace useful. The klibc distribution is currently maintained separately from the kernel. You can obtain somewhat infrequent snapshots of klibc from -ftp://ftp.kernel.org/pub/linux/libs/klibc/ +https://www.kernel.org/pub/linux/libs/klibc/ For active users, you are better off using the klibc git repository, at http://git.kernel.org/?p=libs/klibc/klibc.git diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/extcon/intel-int3496.txt index af0b366c25b7..8155dbc7fad3 100644 --- a/Documentation/extcon/intel-int3496.txt +++ b/Documentation/extcon/intel-int3496.txt @@ -20,3 +20,8 @@ Index 1: The output gpio for enabling Vbus output from the device to the otg Index 2: The output gpio for muxing of the data pins between the USB host and the USB peripheral controller, write 1 to mux to the peripheral controller + +There is a mapping between indices and GPIO connection IDs as follows + id index 0 + vbus index 1 + mux index 2 diff --git a/Documentation/extcon/porting-android-switch-class b/Documentation/extcon/porting-android-switch-class deleted file mode 100644 index 49c81caef84d..000000000000 --- a/Documentation/extcon/porting-android-switch-class +++ /dev/null @@ -1,123 +0,0 @@ - - Staging/Android Switch Class Porting Guide - (linux/drivers/staging/android/switch) - (c) Copyright 2012 Samsung Electronics - -AUTHORS -MyungJoo Ham <myungjoo.ham@samsung.com> - -/***************************************************************** - * CHAPTER 1. * - * PORTING SWITCH CLASS DEVICE DRIVERS * - *****************************************************************/ - -****** STEP 1. Basic Functionality - No extcon extended feature, but switch features only. - -- struct switch_dev (fed to switch_dev_register/unregister) - @name: no change - @dev: no change - @index: drop (not used in switch device driver side anyway) - @state: no change - If you have used @state with magic numbers, keep it - at this step. - @print_name: no change but type change (switch_dev->extcon_dev) - @print_state: no change but type change (switch_dev->extcon_dev) - -- switch_dev_register(sdev, dev) - => extcon_dev_register(edev) - : type change (sdev->edev) - : remove second param('dev'). if edev has parent device, should store - 'dev' to 'edev.dev.parent' before registering extcon device -- switch_dev_unregister(sdev) - => extcon_dev_unregister(edev) - : no change but type change (sdev->edev) -- switch_get_state(sdev) - => extcon_get_state(edev) - : no change but type change (sdev->edev) and (return: int->u32) -- switch_set_state(sdev, state) - => extcon_set_state(edev, state) - : no change but type change (sdev->edev) and (state: int->u32) - -With this changes, the ex-switch extcon class device works as it once -worked as switch class device. However, it will now have additional -interfaces (both ABI and in-kernel API) and different ABI locations. -However, if CONFIG_ANDROID is enabled without CONFIG_ANDROID_SWITCH, -/sys/class/switch/* will be symbolically linked to /sys/class/extcon/ -so that they are still compatible with legacy userspace processes. - -****** STEP 2. Multistate (no more magic numbers in state value) - Extcon's extended features for switch device drivers with - complex features usually required magic numbers in state - value of switch_dev. With extcon, such magic numbers that - support multiple cables are no more required or supported. - - 1. Define cable names at edev->supported_cable. - 2. (Recommended) remove print_state callback. - 3. Use extcon_get_cable_state_(edev, index) or - extcon_get_cable_state(edev, cable_name) instead of - extcon_get_state(edev) if you intend to get a state of a specific - cable. Same for set_state. This way, you can remove the usage of - magic numbers in state value. - 4. Use extcon_update_state() if you are updating specific bits of - the state value. - -Example: a switch device driver w/ magic numbers for two cables. - "0x00": no cables connected. - "0x01": cable 1 connected - "0x02": cable 2 connected - "0x03": cable 1 and 2 connected - 1. edev->supported_cable = {"1", "2", NULL}; - 2. edev->print_state = NULL; - 3. extcon_get_cable_state_(edev, 0) shows cable 1's state. - extcon_get_cable_state(edev, "1") shows cable 1's state. - extcon_set_cable_state_(edev, 1) sets cable 2's state. - extcon_set_cable_state(edev, "2") sets cable 2's state - 4. extcon_update_state(edev, 0x01, 0) sets the least bit's 0. - -****** STEP 3. Notify other device drivers - - You can notify others of the cable attach/detach events with -notifier chains. - - At the side of other device drivers (the extcon device itself -does not need to get notified of its own events), there are two -methods to register notifier_block for cable events: -(a) for a specific cable or (b) for every cable. - - (a) extcon_register_interest(obj, extcon_name, cable_name, nb) - Example: want to get news of "MAX8997_MUIC"'s "USB" cable - - obj = kzalloc(sizeof(struct extcon_specific_cable_nb), - GFP_KERNEL); - nb->notifier_call = the_callback_to_handle_usb; - - extcon_register_intereset(obj, "MAX8997_MUIC", "USB", nb); - - (b) extcon_register_notifier(edev, nb) - Call nb for any changes in edev. - - Please note that in order to properly behave with method (a), -the extcon device driver should support multistate feature (STEP 2). - -****** STEP 4. Inter-cable relation (mutually exclusive) - - You can provide inter-cable mutually exclusiveness information -for an extcon device. When cables A and B are declared to be mutually -exclusive, the two cables cannot be in ATTACHED state simulteneously. - - -/***************************************************************** - * CHAPTER 2. * - * PORTING USERSPACE w/ SWITCH CLASS DEVICE SUPPORT * - *****************************************************************/ - -****** ABI Location - - If "CONFIG_ANDROID" is enabled, /sys/class/switch/* are created -as symbolic links to /sys/class/extcon/*. - - The two files of switch class, name and state, are provided with -extcon, too. When the multistate support (STEP 2 of CHAPTER 1.) is -not enabled or print_state callback is supplied, the output of -state ABI is same with switch class. diff --git a/Documentation/features/core/BPF-JIT/arch-support.txt b/Documentation/features/core/BPF-JIT/arch-support.txt index c1b4f917238f..5575d2d09625 100644 --- a/Documentation/features/core/BPF-JIT/arch-support.txt +++ b/Documentation/features/core/BPF-JIT/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt index 6d930fcbe519..abb5f271a792 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | ok | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index 136868b636e6..dbdaffcc5110 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index 728061d763b1..5e97a89420ef 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | ok | | c6x: | ok | | cris: | TODO | diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index 703f5784bc90..76bbd7fe27b3 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt index 38dea8eeba0a..830dbe801aaf 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 862e15d6f79e..0217bf6e942d 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | ok | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index 40f44d041fb4..1e84be3c142e 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | @@ -27,7 +26,7 @@ | nios2: | TODO | | openrisc: | TODO | | parisc: | TODO | - | powerpc: | TODO | + | powerpc: | ok | | s390: | TODO | | score: | TODO | | sh: | TODO | diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index a44bfff6940b..529f66eda679 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | TODO | - | avr32: | ok | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index d87c1ce24204..43353242e439 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index b8999d8544ca..f559f1ba5416 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt index 0fa423313409..d7acd7bd3619 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index d605c3fc38fd..53ed42b0e7e5 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt index 44cc1ff3f603..149443936de9 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/io/dma-api-debug/arch-support.txt b/Documentation/features/io/dma-api-debug/arch-support.txt index ffa522a9bdfd..6be920643be6 100644 --- a/Documentation/features/io/dma-api-debug/arch-support.txt +++ b/Documentation/features/io/dma-api-debug/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | ok | | cris: | TODO | diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index 83d2cf989ea3..0eb08e1e32b8 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/io/sg-chain/arch-support.txt b/Documentation/features/io/sg-chain/arch-support.txt index 6ca98f9911bb..514ad3468aa5 100644 --- a/Documentation/features/io/sg-chain/arch-support.txt +++ b/Documentation/features/io/sg-chain/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/lib/strncasecmp/arch-support.txt b/Documentation/features/lib/strncasecmp/arch-support.txt index 12b1c9358e57..532c6f0fc15c 100644 --- a/Documentation/features/lib/strncasecmp/arch-support.txt +++ b/Documentation/features/lib/strncasecmp/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt index d9c310889bc1..f3eec26c8cf8 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt index cf90635bdcbb..9756abc680a7 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | ok | | blackfin: | ok | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index 68c3a5ddd9b9..62f4ee5c156c 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index e973b1a9572f..321b32f6e63c 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt b/Documentation/features/locking/rwsem-optimized/arch-support.txt index ac93d7ab66c4..79bfa4d6e41f 100644 --- a/Documentation/features/locking/rwsem-optimized/arch-support.txt +++ b/Documentation/features/locking/rwsem-optimized/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 4660bf222db1..00f1606bbf45 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt index f179b1fb26ef..7d516eacf7b9 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt index 85777c5c6353..f974b8df5d82 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index ac7cd6b1502b..1d3c0f669152 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -10,7 +10,6 @@ | arc: | .. | | arm: | .. | | arm64: | .. | - | avr32: | .. | | blackfin: | .. | | c6x: | .. | | cris: | .. | diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index 4f66ec133951..a32d5b207679 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt index 8acb439a4a17..caee8f64d1bc 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index ff670b2207f1..1cd87f6cd07d 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | ok | | blackfin: | ok | | c6x: | ok | | cris: | ok | diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index a1e3eea7003f..e6d7c7b2253c 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index 4199ffecc0ff..15c6071788ae 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/time/modern-timekeeping/arch-support.txt b/Documentation/features/time/modern-timekeeping/arch-support.txt index 17f68a02e84d..baee7611ba3d 100644 --- a/Documentation/features/time/modern-timekeeping/arch-support.txt +++ b/Documentation/features/time/modern-timekeeping/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | TODO | | arm64: | ok | - | avr32: | ok | | blackfin: | TODO | | c6x: | ok | | cris: | TODO | diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt index cf3c3e383d15..9129530cb73c 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index ec4dd28e1297..f6829af3255f 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt index 991974275a3e..1a09ea99d486 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index 523f8307b9cd..d170e6236503 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | .. | | blackfin: | .. | | c6x: | .. | | cris: | .. | diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 261b92e2fb1a..abfab4080a91 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | TODO | - | avr32: | .. | | blackfin: | TODO | | c6x: | .. | | cris: | .. | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index df1d1f3c9af2..f81f09b22b08 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -10,7 +10,6 @@ | arc: | TODO | | arm: | TODO | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index 90c53749fde7..0cc3e11c42e2 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | TODO | | arm64: | TODO | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/features/vm/numa-memblock/arch-support.txt b/Documentation/features/vm/numa-memblock/arch-support.txt index e7c252a0c531..9a3fdac42ce1 100644 --- a/Documentation/features/vm/numa-memblock/arch-support.txt +++ b/Documentation/features/vm/numa-memblock/arch-support.txt @@ -10,7 +10,6 @@ | arc: | .. | | arm: | .. | | arm64: | .. | - | avr32: | .. | | blackfin: | .. | | c6x: | .. | | cris: | .. | diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index 3de5434c857c..dfaa39e664ff 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -10,7 +10,6 @@ | arc: | ok | | arm: | ok | | arm64: | ok | - | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | | cris: | TODO | diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index fdcfdd79682a..fe25787ff6d4 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -58,8 +58,7 @@ prototypes: int (*permission) (struct inode *, int, unsigned int); int (*get_acl)(struct inode *, int); int (*setattr) (struct dentry *, struct iattr *); - int (*getattr) (const struct path *, struct dentry *, struct kstat *, - u32, unsigned int); + int (*getattr) (const struct path *, struct kstat *, u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); void (*update_time)(struct inode *, struct timespec *, int); diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index 3698ed3146e3..5a8f7f4d2bca 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -25,7 +25,7 @@ Note: More extensive information for getting started with ext4 can be or - ftp://ftp.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/ + https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/ or grab the latest git repository from: diff --git a/Documentation/filesystems/nfs/nfs-rdma.txt b/Documentation/filesystems/nfs/nfs-rdma.txt index 1e6564545edf..22dc0dd6889c 100644 --- a/Documentation/filesystems/nfs/nfs-rdma.txt +++ b/Documentation/filesystems/nfs/nfs-rdma.txt @@ -110,10 +110,10 @@ Installation - Install a Linux kernel with NFS/RDMA The NFS/RDMA client and server are both included in the mainline Linux - kernel version 2.6.25 and later. This and other versions of the 2.6 Linux + kernel version 2.6.25 and later. This and other versions of the Linux kernel can be found at: - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ + https://www.kernel.org/pub/linux/kernel/ Download the sources and place them in an appropriate location. diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index 95280079c0b3..5fb17f49f7a2 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -600,3 +600,9 @@ in your dentry operations instead. [recommended] ->readlink is optional for symlinks. Don't set, unless filesystem needs to fake something for readlink(2). +-- +[mandatory] + ->getattr() is now passed a struct path rather than a vfsmount and + dentry separately, and it now has request_mask and query_flags arguments + to specify the fields and sync type requested by statx. Filesystems not + supporting any statx-specific features may ignore the new arguments. diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index c94b4675d021..4cddbce85ac9 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -44,6 +44,7 @@ Table of Contents 3.8 /proc/<pid>/fdinfo/<fd> - Information about opened file 3.9 /proc/<pid>/map_files - Information about memory mapped files 3.10 /proc/<pid>/timerslack_ns - Task timerslack value + 3.11 /proc/<pid>/patch_state - Livepatch patch operation state 4 Configuring procfs 4.1 Mount options @@ -412,6 +413,7 @@ Private_Clean: 0 kB Private_Dirty: 0 kB Referenced: 892 kB Anonymous: 0 kB +LazyFree: 0 kB AnonHugePages: 0 kB ShmemPmdMapped: 0 kB Shared_Hugetlb: 0 kB @@ -441,6 +443,11 @@ accessed. "Anonymous" shows the amount of memory that does not belong to any file. Even a mapping associated with a file may contain anonymous pages: when MAP_PRIVATE and a page is modified, the file page is replaced by a private anonymous copy. +"LazyFree" shows the amount of memory which is marked by madvise(MADV_FREE). +The memory isn't freed immediately with madvise(). It's freed in memory +pressure if the memory is clean. Please note that the printed value might +be lower than the real value due to optimizations used in the current +implementation. If this is not desirable please file a bug report. "AnonHugePages" shows the ammount of memory backed by transparent hugepage. "ShmemPmdMapped" shows the ammount of shared (shmem/tmpfs) memory backed by huge pages. @@ -1887,6 +1894,23 @@ Valid values are from 0 - ULLONG_MAX An application setting the value must have PTRACE_MODE_ATTACH_FSCREDS level permissions on the task specified to change its timerslack_ns value. +3.11 /proc/<pid>/patch_state - Livepatch patch operation state +----------------------------------------------------------------- +When CONFIG_LIVEPATCH is enabled, this file displays the value of the +patch state for the task. + +A value of '-1' indicates that no patch is in transition. + +A value of '0' indicates that a patch is in transition and the task is +unpatched. If the patch is being enabled, then the task hasn't been +patched yet. If the patch is being disabled, then the task has already +been unpatched. + +A value of '1' indicates that a patch is in transition and the task is +patched. If the patch is being enabled, then the task has already been +patched. If the patch is being disabled, then the task hasn't been +unpatched yet. + ------------------------------------------------------------------------------ Configuring procfs diff --git a/Documentation/filesystems/sysfs-pci.txt b/Documentation/filesystems/sysfs-pci.txt index 6ea1ceda6f52..06f1d64c6f70 100644 --- a/Documentation/filesystems/sysfs-pci.txt +++ b/Documentation/filesystems/sysfs-pci.txt @@ -113,9 +113,18 @@ Supporting PCI access on new platforms -------------------------------------- In order to support PCI resource mapping as described above, Linux platform -code must define HAVE_PCI_MMAP and provide a pci_mmap_page_range function. -Platforms are free to only support subsets of the mmap functionality, but -useful return codes should be provided. +code should ideally define ARCH_GENERIC_PCI_MMAP_RESOURCE and use the generic +implementation of that functionality. To support the historical interface of +mmap() through files in /proc/bus/pci, platforms may also set HAVE_PCI_MMAP. + +Alternatively, platforms which set HAVE_PCI_MMAP may provide their own +implementation of pci_mmap_page_range() instead of defining +ARCH_GENERIC_PCI_MMAP_RESOURCE. + +Platforms which support write-combining maps of PCI resources must define +arch_can_pci_mmap_wc() which shall evaluate to non-zero at runtime when +write-combining is permitted. Platforms which support maps of I/O resources +define arch_can_pci_mmap_io() similarly. Legacy resources are protected by the HAVE_PCI_LEGACY define. Platforms wishing to support legacy functionality should define it and provide diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 569211703721..f42b90687d40 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -382,8 +382,7 @@ struct inode_operations { int (*permission) (struct inode *, int); int (*get_acl)(struct inode *, int); int (*setattr) (struct dentry *, struct iattr *); - int (*getattr) (const struct path *, struct dentry *, struct kstat *, - u32, unsigned int); + int (*getattr) (const struct path *, struct kstat *, u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); void (*update_time)(struct inode *, struct timespec *, int); int (*atomic_open)(struct inode *, struct dentry *, struct file *, @@ -695,8 +694,7 @@ struct address_space_operations { write_end: After a successful write_begin, and data copy, write_end must be called. len is the original len passed to write_begin, and copied - is the amount that was able to be copied (copied == len is always true - if write_begin was called with the AOP_FLAG_UNINTERRUPTIBLE flag). + is the amount that was able to be copied. The filesystem must take care of unlocking the page and releasing it refcount, and updating i_size. diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.txt index 891c69464434..433eaefb4aa1 100644 --- a/Documentation/gcc-plugins.txt +++ b/Documentation/gcc-plugins.txt @@ -18,8 +18,8 @@ because gcc versions 4.5 and 4.6 are compiled by a C compiler, gcc-4.7 can be compiled by a C or a C++ compiler, and versions 4.8+ can only be compiled by a C++ compiler. -Currently the GCC plugin infrastructure supports only the x86, arm and arm64 -architectures. +Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and +powerpc architectures. This infrastructure was ported from grsecurity [6] and PaX [7]. diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 05676fdacfe3..912568baabb9 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -70,6 +70,12 @@ instead of -ENOENT if no GPIO has been assigned to the requested function: unsigned int index, enum gpiod_flags flags) +Note that gpio_get*_optional() functions (and their managed variants), unlike +the rest of gpiolib API, also return NULL when gpiolib support is disabled. +This is helpful to driver authors, since they do not need to special case +-ENOSYS return codes. System integrators should however be careful to enable +gpiolib on systems that need it. + For a function using multiple GPIOs all of those can be obtained with one call: struct gpio_descs *gpiod_get_array(struct device *dev, diff --git a/Documentation/gpu/bridge/dw-hdmi.rst b/Documentation/gpu/bridge/dw-hdmi.rst new file mode 100644 index 000000000000..486faadf00af --- /dev/null +++ b/Documentation/gpu/bridge/dw-hdmi.rst @@ -0,0 +1,15 @@ +======================================================= + drm/bridge/dw-hdmi Synopsys DesignWare HDMI Controller +======================================================= + +Synopsys DesignWare HDMI Controller +=================================== + +This section covers everything related to the Synopsys DesignWare HDMI +Controller implemented as a DRM bridge. + +Supported Input Formats and Encodings +------------------------------------- + +.. kernel-doc:: include/drm/bridge/dw_hdmi.h + :doc: Supported input formats and encodings diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index e35920db1f4c..babfb6143bd9 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -140,12 +140,12 @@ Device Instance and Driver Handling .. kernel-doc:: drivers/gpu/drm/drm_drv.c :doc: driver instance overview -.. kernel-doc:: drivers/gpu/drm/drm_drv.c - :export: - .. kernel-doc:: include/drm/drm_drv.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_drv.c + :export: + Driver Load ----------- @@ -240,120 +240,21 @@ drivers. .. kernel-doc:: drivers/gpu/drm/drm_pci.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_platform.c - :export: - Open/Close, File Operations and IOCTLs ====================================== -Open and Close --------------- - -Open and close handlers. None of those methods are mandatory:: - - int (*firstopen) (struct drm_device *); - void (*lastclose) (struct drm_device *); - int (*open) (struct drm_device *, struct drm_file *); - void (*preclose) (struct drm_device *, struct drm_file *); - void (*postclose) (struct drm_device *, struct drm_file *); - -The firstopen method is called by the DRM core for legacy UMS (User Mode -Setting) drivers only when an application opens a device that has no -other opened file handle. UMS drivers can implement it to acquire device -resources. KMS drivers can't use the method and must acquire resources -in the load method instead. - -Similarly the lastclose method is called when the last application -holding a file handle opened on the device closes it, for both UMS and -KMS drivers. Additionally, the method is also called at module unload -time or, for hot-pluggable devices, when the device is unplugged. The -firstopen and lastclose calls can thus be unbalanced. - -The open method is called every time the device is opened by an -application. Drivers can allocate per-file private data in this method -and store them in the struct :c:type:`struct drm_file -<drm_file>` driver_priv field. Note that the open method is -called before firstopen. - -The close operation is split into preclose and postclose methods. -Drivers must stop and cleanup all per-file operations in the preclose -method. For instance pending vertical blanking and page flip events must -be cancelled. No per-file operation is allowed on the file handle after -returning from the preclose method. - -Finally the postclose method is called as the last step of the close -operation, right before calling the lastclose method if no other open -file handle exists for the device. Drivers that have allocated per-file -private data in the open method should free it here. - -The lastclose method should restore CRTC and plane properties to default -value, so that a subsequent open of the device will not inherit state -from the previous user. It can also be used to execute delayed power -switching state changes, e.g. in conjunction with the :ref:`vga_switcheroo` -infrastructure. Beyond that KMS drivers should not do any -further cleanup. Only legacy UMS drivers might need to clean up device -state so that the vga console or an independent fbdev driver could take -over. - File Operations --------------- -.. kernel-doc:: drivers/gpu/drm/drm_fops.c +.. kernel-doc:: drivers/gpu/drm/drm_file.c :doc: file operations -.. kernel-doc:: drivers/gpu/drm/drm_fops.c - :export: - -IOCTLs ------- - -struct drm_ioctl_desc \*ioctls; int num_ioctls; - Driver-specific ioctls descriptors table. - -Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls -descriptors table is indexed by the ioctl number offset from the base -value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize -the table entries. - -:: - - DRM_IOCTL_DEF_DRV(ioctl, func, flags) - -``ioctl`` is the ioctl name. Drivers must define the DRM_##ioctl and -DRM_IOCTL_##ioctl macros to the ioctl number offset from -DRM_COMMAND_BASE and the ioctl number respectively. The first macro is -private to the device while the second must be exposed to userspace in a -public header. - -``func`` is a pointer to the ioctl handler function compatible with the -``drm_ioctl_t`` type. - -:: - - typedef int drm_ioctl_t(struct drm_device *dev, void *data, - struct drm_file *file_priv); - -``flags`` is a bitmask combination of the following values. It restricts -how the ioctl is allowed to be called. - -- DRM_AUTH - Only authenticated callers allowed - -- DRM_MASTER - The ioctl can only be called on the master file handle - -- DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed - -- DRM_CONTROL_ALLOW - The ioctl can only be called on a control - device - -- DRM_UNLOCKED - The ioctl handler will be called without locking the - DRM global mutex. This is the enforced default for kms drivers (i.e. - using the DRIVER_MODESET flag) and hence shouldn't be used any more - for new drivers. +.. kernel-doc:: include/drm/drm_file.h + :internal: -.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c +.. kernel-doc:: drivers/gpu/drm/drm_file.c :export: - Misc Utilities ============== diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 03040aa14fe8..c075aadd7078 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -37,10 +37,12 @@ Modeset Helper Reference for Common Vtables =========================================== .. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :internal: + :doc: overview .. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :doc: overview + :internal: + +.. _drm_atomic_helper: Atomic Modeset Helper Functions Reference ========================================= @@ -84,27 +86,27 @@ Legacy CRTC/Modeset Helper Functions Reference Simple KMS Helper Reference =========================== +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c + :doc: overview + .. kernel-doc:: include/drm/drm_simple_kms_helper.h :internal: .. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :doc: overview - fbdev Helper Functions Reference ================================ .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c :doc: fbdev helpers -.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c - :export: - .. kernel-doc:: include/drm/drm_fb_helper.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c + :export: + Framebuffer CMA Helper Functions Reference ========================================== @@ -114,6 +116,8 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export: +.. _drm_bridges: + Bridges ======= @@ -139,18 +143,20 @@ Bridge Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_bridge.c :export: +.. _drm_panel_helper: + Panel Helper Reference ====================== +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :doc: drm panel + .. kernel-doc:: include/drm/drm_panel.h :internal: .. kernel-doc:: drivers/gpu/drm/drm_panel.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :doc: drm panel - Display Port Helper Functions Reference ======================================= @@ -217,6 +223,18 @@ EDID Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_edid.c :export: +SCDC Helper Functions Reference +=============================== + +.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c + :doc: scdc helpers + +.. kernel-doc:: include/drm/drm_scdc_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c + :export: + Rectangle Utilities Reference ============================= diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 4d4068855ec4..bfecd21a8cdf 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -15,35 +15,271 @@ be setup by initializing the following fields. - struct drm_mode_config_funcs \*funcs; Mode setting functions. -Mode Configuration +Overview +======== + +.. kernel-render:: DOT + :alt: KMS Display Pipeline + :caption: KMS Display Pipeline Overview + + digraph "KMS" { + node [shape=box] + + subgraph cluster_static { + style=dashed + label="Static Objects" + + node [bgcolor=grey style=filled] + "drm_plane A" -> "drm_crtc" + "drm_plane B" -> "drm_crtc" + "drm_crtc" -> "drm_encoder A" + "drm_crtc" -> "drm_encoder B" + } + + subgraph cluster_user_created { + style=dashed + label="Userspace-Created" + + node [shape=oval] + "drm_framebuffer 1" -> "drm_plane A" + "drm_framebuffer 2" -> "drm_plane B" + } + + subgraph cluster_connector { + style=dashed + label="Hotpluggable" + + "drm_encoder A" -> "drm_connector A" + "drm_encoder B" -> "drm_connector B" + } + } + +The basic object structure KMS presents to userspace is fairly simple. +Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`, +see `Frame Buffer Abstraction`_) feed into planes. One or more (or even no) +planes feed their pixel data into a CRTC (represented by :c:type:`struct +drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise +blending step is explained in more detail in `Plane Composition Properties`_ and +related chapters. + +For the output routing the first step is encoders (represented by +:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those +are really just internal artifacts of the helper libraries used to implement KMS +drivers. Besides that they make it unecessarily more complicated for userspace +to figure out which connections between a CRTC and a connector are possible, and +what kind of cloning is supported, they serve no purpose in the userspace API. +Unfortunately encoders have been exposed to userspace, hence can't remove them +at this point. Futhermore the exposed restrictions are often wrongly set by +drivers, and in many cases not powerful enough to express the real restrictions. +A CRTC can be connected to multiple encoders, and for an active CRTC there must +be at least one encoder. + +The final, and real, endpoint in the display chain is the connector (represented +by :c:type:`struct drm_connector <drm_connector>`, see `Connector +Abstraction`_). Connectors can have different possible encoders, but the kernel +driver selects which encoder to use for each connector. The use case is DVI, +which could switch between an analog and a digital encoder. Encoders can also +drive multiple different connectors. There is exactly one active connector for +every active encoder. + +Internally the output pipeline is a bit more complex and matches today's +hardware more closely: + +.. kernel-render:: DOT + :alt: KMS Output Pipeline + :caption: KMS Output Pipeline + + digraph "Output Pipeline" { + node [shape=box] + + subgraph { + "drm_crtc" [bgcolor=grey style=filled] + } + + subgraph cluster_internal { + style=dashed + label="Internal Pipeline" + { + node [bgcolor=grey style=filled] + "drm_encoder A"; + "drm_encoder B"; + "drm_encoder C"; + } + + { + node [bgcolor=grey style=filled] + "drm_encoder B" -> "drm_bridge B" + "drm_encoder C" -> "drm_bridge C1" + "drm_bridge C1" -> "drm_bridge C2"; + } + } + + "drm_crtc" -> "drm_encoder A" + "drm_crtc" -> "drm_encoder B" + "drm_crtc" -> "drm_encoder C" + + + subgraph cluster_output { + style=dashed + label="Outputs" + + "drm_encoder A" -> "drm_connector A"; + "drm_bridge B" -> "drm_connector B"; + "drm_bridge C2" -> "drm_connector C"; + + "drm_panel" + } + } + +Internally two additional helper objects come into play. First, to be able to +share code for encoders (sometimes on the same SoC, sometimes off-chip) one or +more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge +<drm_bridge>`) can be linked to an encoder. This link is static and cannot be +changed, which means the cross-bar (if there is any) needs to be mapped between +the CRTC and any encoders. Often for drivers with bridges there's no code left +at the encoder level. Atomic drivers can leave out all the encoder callbacks to +essentially only leave a dummy routing object behind, which is needed for +backwards compatibility since encoders are exposed to userspace. + +The second object is for panels, represented by :c:type:`struct drm_panel +<drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding +point, but are generally linked to the driver private structure that embeds +:c:type:`struct drm_connector <drm_connector>`. + +Note that currently the bridge chaining and interactions with connectors and +panels are still in-flux and not really fully sorted out yet. KMS Core Structures and Functions ================================= -.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c - :export: - .. kernel-doc:: include/drm/drm_mode_config.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c + :export: + Modeset Base Object Abstraction =============================== +.. kernel-render:: DOT + :alt: Mode Objects and Properties + :caption: Mode Objects and Properties + + digraph { + node [shape=box] + + "drm_property A" -> "drm_mode_object A" + "drm_property A" -> "drm_mode_object B" + "drm_property B" -> "drm_mode_object A" + } + +The base structure for all KMS objects is :c:type:`struct drm_mode_object +<drm_mode_object>`. One of the base services it provides is tracking properties, +which are especially important for the atomic IOCTL (see `Atomic Mode +Setting`_). The somewhat surprising part here is that properties are not +directly instantiated on each object, but free-standing mode objects themselves, +represented by :c:type:`struct drm_property <drm_property>`, which only specify +the type and value range of a property. Any given property can be attached +multiple times to different objects using :c:func:`drm_object_attach_property() +<drm_object_attach_property>`. + .. kernel-doc:: include/drm/drm_mode_object.h :internal: .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c :export: -Atomic Mode Setting Function Reference -====================================== +Atomic Mode Setting +=================== -.. kernel-doc:: drivers/gpu/drm/drm_atomic.c - :export: + +.. kernel-render:: DOT + :alt: Mode Objects and Properties + :caption: Mode Objects and Properties + + digraph { + node [shape=box] + + subgraph cluster_state { + style=dashed + label="Free-standing state" + + "drm_atomic_state" -> "duplicated drm_plane_state A" + "drm_atomic_state" -> "duplicated drm_plane_state B" + "drm_atomic_state" -> "duplicated drm_crtc_state" + "drm_atomic_state" -> "duplicated drm_connector_state" + "drm_atomic_state" -> "duplicated driver private state" + } + + subgraph cluster_current { + style=dashed + label="Current state" + + "drm_device" -> "drm_plane A" + "drm_device" -> "drm_plane B" + "drm_device" -> "drm_crtc" + "drm_device" -> "drm_connector" + "drm_device" -> "driver private object" + + "drm_plane A" -> "drm_plane_state A" + "drm_plane B" -> "drm_plane_state B" + "drm_crtc" -> "drm_crtc_state" + "drm_connector" -> "drm_connector_state" + "driver private object" -> "driver private state" + } + + "drm_atomic_state" -> "drm_device" [label="atomic_commit"] + "duplicated drm_plane_state A" -> "drm_device"[style=invis] + } + +Atomic provides transactional modeset (including planes) updates, but a +bit differently from the usual transactional approach of try-commit and +rollback: + +- Firstly, no hardware changes are allowed when the commit would fail. This + allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows + userspace to explore whether certain configurations would work or not. + +- This would still allow setting and rollback of just the software state, + simplifying conversion of existing drivers. But auditing drivers for + correctness of the atomic_check code becomes really hard with that: Rolling + back changes in data structures all over the place is hard to get right. + +- Lastly, for backwards compatibility and to support all use-cases, atomic + updates need to be incremental and be able to execute in parallel. Hardware + doesn't always allow it, but where possible plane updates on different CRTCs + should not interfere, and not get stalled due to output routing changing on + different CRTCs. + +Taken all together there's two consequences for the atomic design: + +- The overall state is split up into per-object state structures: + :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct + drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct + drm_connector_state <drm_connector_state>` for connectors. These are the only + objects with userspace-visible and settable state. For internal state drivers + can subclass these structures through embeddeding, or add entirely new state + structures for their globally shared hardware functions. + +- An atomic update is assembled and validated as an entirely free-standing pile + of structures within the :c:type:`drm_atomic_state <drm_atomic_state>` + container. Again drivers can subclass that container for their own state + structure tracking needs. Only when a state is committed is it applied to the + driver and modeset objects. This way rolling back an update boils down to + releasing memory and unreferencing objects like framebuffers. + +Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed +coverage of specific topics. + +Atomic Mode Setting Function Reference +-------------------------------------- .. kernel-doc:: include/drm/drm_atomic.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c + :export: + CRTC Abstraction ================ @@ -68,12 +304,12 @@ Frame Buffer Abstraction Frame Buffer Functions Reference -------------------------------- -.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c - :export: - .. kernel-doc:: include/drm/drm_framebuffer.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c + :export: + DRM Format Handling =================== @@ -376,8 +612,8 @@ operation handler. Vertical Blanking and Interrupt Handling Functions Reference ------------------------------------------------------------ -.. kernel-doc:: drivers/gpu/drm/drm_irq.c - :export: - .. kernel-doc:: include/drm/drm_irq.h :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_irq.c + :export: diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index f5760b140f13..96b9c34c21e4 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -183,14 +183,12 @@ GEM Objects Lifetime -------------------- All GEM objects are reference-counted by the GEM core. References can be -acquired and release by :c:func:`calling -drm_gem_object_reference()` and -:c:func:`drm_gem_object_unreference()` respectively. The caller -must hold the :c:type:`struct drm_device <drm_device>` -struct_mutex lock when calling -:c:func:`drm_gem_object_reference()`. As a convenience, GEM -provides :c:func:`drm_gem_object_unreference_unlocked()` -functions that can be called without holding the lock. +acquired and release by :c:func:`calling drm_gem_object_get()` and +:c:func:`drm_gem_object_put()` respectively. The caller must hold the +:c:type:`struct drm_device <drm_device>` struct_mutex lock when calling +:c:func:`drm_gem_object_get()`. As a convenience, GEM provides +:c:func:`drm_gem_object_put_unlocked()` functions that can be called without +holding the lock. When the last reference to a GEM object is released the GEM core calls the :c:type:`struct drm_driver <drm_driver>` gem_free_object @@ -367,36 +365,36 @@ from the client in libdrm. GEM Function Reference ---------------------- -.. kernel-doc:: drivers/gpu/drm/drm_gem.c - :export: - .. kernel-doc:: include/drm/drm_gem.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_gem.c + :export: + GEM CMA Helper Functions Reference ---------------------------------- .. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c :doc: cma helpers -.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c - :export: - .. kernel-doc:: include/drm/drm_gem_cma_helper.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c + :export: + VMA Offset Manager ================== .. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c :doc: vma offset manager -.. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c - :export: - .. kernel-doc:: include/drm/drm_vma_manager.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c + :export: + PRIME Buffer Sharing ==================== @@ -451,6 +449,9 @@ PRIME Helper Functions PRIME Function References ------------------------- +.. kernel-doc:: include/drm/drm_prime.h + :internal: + .. kernel-doc:: drivers/gpu/drm/drm_prime.c :export: @@ -472,12 +473,12 @@ LRU Scan/Eviction Support DRM MM Range Allocator Function References ------------------------------------------ -.. kernel-doc:: drivers/gpu/drm/drm_mm.c - :export: - .. kernel-doc:: include/drm/drm_mm.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_mm.c + :export: + DRM Cache Handling ================== diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index fcc228ef5bc4..858457567d3d 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -21,6 +21,8 @@ libdrm Device Lookup :doc: getunique and setversion story +.. _drm_primary_node: + Primary Nodes, DRM Master and Authentication ============================================ @@ -103,6 +105,8 @@ is already rather painful for the DRM subsystem, with multiple different uAPIs for the same thing co-existing. If we add a few more complete mistakes into the mix every year it would be entirely unmanageable. +.. _drm_render_node: + Render nodes ============ @@ -156,6 +160,20 @@ other hand, a driver requires shared state between clients which is visible to user-space and accessible beyond open-file boundaries, they cannot support render nodes. +IOCTL Support on Device Nodes +============================= + +.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c + :doc: driver specific ioctls + +.. kernel-doc:: include/drm/drm_ioctl.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c + :export: + +.. kernel-doc:: drivers/gpu/drm/drm_ioc32.c + :export: Testing and validation ====================== @@ -203,6 +221,28 @@ Display CRC Support .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c :doc: CRC ABI +.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c + :export: + +Debugfs Support +--------------- + +.. kernel-doc:: include/drm/drm_debugfs.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_debugfs.c + :export: + +Sysfs Support +============= + +.. kernel-doc:: drivers/gpu/drm/drm_sysfs.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_sysfs.c + :export: + + VBlank event handling ===================== diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index b0d6709b8600..9c7ed3e3f1e9 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -222,6 +222,15 @@ Video BIOS Table (VBT) .. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h :internal: +Display clocks +-------------- + +.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c + :doc: CDCLK / RAWCLK + +.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c + :internal: + Display PLLs ------------ diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index f81278a7c2cc..c572f092739e 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -11,9 +11,13 @@ Linux GPU Driver Developer's Guide drm-kms-helpers drm-uapi i915 + meson tinydrm + vc4 vga-switcheroo vgaarbiter + bridge/dw-hdmi + todo .. only:: subproject and html diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index eb284eb748ba..fccbe375244d 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -50,3 +50,49 @@ names are "Notes" with information for dangerous or tricky corner cases, and "FIXME" where the interface could be cleaned up. Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`. + +Getting Started +=============== + +Developers interested in helping out with the DRM subsystem are very welcome. +Often people will resort to sending in patches for various issues reported by +checkpatch or sparse. We welcome such contributions. + +Anyone looking to kick it up a notch can find a list of janitorial tasks on +the :ref:`TODO list <todo>`. + +Contribution Process +==================== + +Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the +main process guidelines and documentation <process_index>` for how things work. +Here we just document some of the specialities of the GPU subsystem. + +Feature Merge Deadlines +----------------------- + +All feature work must be in the linux-next tree by the -rc6 release of the +current release cycle, otherwise they must be postponed and can't reach the next +merge window. All patches must have landed in the drm-next tree by latest -rc7, +but if your branch is not in linux-next then this must have happened by -rc6 +already. + +After that point only bugfixes (like after the upstream merge window has closed +with the -rc1 release) are allowed. No new platform enabling or new drivers are +allowed. + +This means that there's a blackout-period of about one month where feature work +can't be merged. The recommended way to deal with that is having a -next tree +that's always open, but making sure to not feed it into linux-next during the +blackout period. As an example, drm-misc works like that. + +Code of Conduct +--------------- + +As a freedesktop.org project, dri-devel, and the DRM community, follows the +Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct + +Please conduct yourself in a respectful and civilised manner when +interacting with community members on mailing lists, IRC, or bug +trackers. The community represents the project as a whole, and abusive +or bullying behaviour is not tolerated by the project. diff --git a/Documentation/gpu/kms-properties.csv b/Documentation/gpu/kms-properties.csv index 981873a05d14..927b65e14219 100644 --- a/Documentation/gpu/kms-properties.csv +++ b/Documentation/gpu/kms-properties.csv @@ -1,10 +1,5 @@ Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,Description/Restrictions ,,“scaling modeâ€,ENUM,"{ ""None"", ""Full"", ""Center"", ""Full aspect"" }",Connector,"Supported by: amdgpu, gma500, i915, nouveau and radeon." -,Connector,“EDIDâ€,BLOB | IMMUTABLE,0,Connector,Contains id of edid blob ptr object. -,,“DPMSâ€,ENUM,"{ “Onâ€, “Standbyâ€, “Suspendâ€, “Off†}",Connector,Contains DPMS operation mode value. -,,“PATHâ€,BLOB | IMMUTABLE,0,Connector,Contains topology path to a connector. -,,“TILEâ€,BLOB | IMMUTABLE,0,Connector,Contains tiling information for a connector. -,,“CRTC_IDâ€,OBJECT,DRM_MODE_OBJECT_CRTC,Connector,CRTC that connector is attached to (atomic) ,DVI-I,“subconnectorâ€,ENUM,"{ “Unknownâ€, “DVI-Dâ€, “DVI-A†}",Connector,TBD ,,“select subconnectorâ€,ENUM,"{ “Automaticâ€, “DVI-Dâ€, “DVI-A†}",Connector,TBD ,TV,“subconnectorâ€,ENUM,"{ ""Unknown"", ""Composite"", ""SVIDEO"", ""Component"", ""SCART"" }",Connector,TBD diff --git a/Documentation/gpu/meson.rst b/Documentation/gpu/meson.rst new file mode 100644 index 000000000000..479f6f51a13b --- /dev/null +++ b/Documentation/gpu/meson.rst @@ -0,0 +1,61 @@ +============================================= +drm/meson AmLogic Meson Video Processing Unit +============================================= + +.. kernel-doc:: drivers/gpu/drm/meson/meson_drv.c + :doc: Video Processing Unit + +Video Processing Unit +===================== + +The Amlogic Meson Display controller is composed of several components +that are going to be documented below: + +.. code:: + + DMC|---------------VPU (Video Processing Unit)----------------|------HHI------| + | vd1 _______ _____________ _________________ | | + D |-------| |----| | | | | HDMI PLL | + D | vd2 | VIU | | Video Post | | Video Encoders |<---|-----VCLK | + R |-------| |----| Processing | | | | | + | osd2 | | | |---| Enci ----------|----|-----VDAC------| + R |-------| CSC |----| Scalers | | Encp ----------|----|----HDMI-TX----| + A | osd1 | | | Blenders | | Encl ----------|----|---------------| + M |-------|______|----|____________| |________________| | | + ___|__________________________________________________________|_______________| + +Video Input Unit +================ + +.. kernel-doc:: drivers/gpu/drm/meson/meson_viu.c + :doc: Video Input Unit + +Video Post Processing +===================== + +.. kernel-doc:: drivers/gpu/drm/meson/meson_vpp.c + :doc: Video Post Processing + +Video Encoder +============= + +.. kernel-doc:: drivers/gpu/drm/meson/meson_venc.c + :doc: Video Encoder + +Video Canvas Management +======================= + +.. kernel-doc:: drivers/gpu/drm/meson/meson_canvas.c + :doc: Canvas + +Video Clocks +============ + +.. kernel-doc:: drivers/gpu/drm/meson/meson_vclk.c + :doc: Video Clocks + +HDMI Video Output +================= + +.. kernel-doc:: drivers/gpu/drm/meson/meson_dw_hdmi.c + :doc: HDMI Output diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst new file mode 100644 index 000000000000..1bdb7356a310 --- /dev/null +++ b/Documentation/gpu/todo.rst @@ -0,0 +1,407 @@ +.. _todo: + +========= +TODO list +========= + +This section contains a list of smaller janitorial tasks in the kernel DRM +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 + +Switch from reference/unreference to get/put +-------------------------------------------- + +For some reason DRM core uses ``reference``/``unreference`` suffixes for +refcounting functions, but kernel uses ``get``/``put`` (e.g. +``kref_get``/``put()``). It would be good to switch over for consistency, and +it's shorter. Needs to be done in 3 steps for each pair of functions: + +* Create new ``get``/``put`` functions, define the old names as compatibility + wrappers +* Switch over each file/driver using a cocci-generated spatch. +* Once all users of the old names are gone, remove them. + +This way drivers/patches in the progress of getting merged won't break. + +Contact: Daniel Vetter + +Convert existing KMS drivers to atomic modesetting +-------------------------------------------------- + +3.19 has the atomic modeset interfaces and helpers, so drivers can now be +converted over. Modern compositors like Wayland or Surfaceflinger on Android +really want an atomic modeset interface, so this is all about the bright +future. + +There is a conversion guide for atomic and all you need is a GPU for a +non-converted driver (again virtual HW drivers for KVM are still all +suitable). + +As part of this drivers also need to convert to universal plane (which means +exposing primary & cursor as proper plane objects). But that's much easier to +do by directly using the new atomic helper driver callbacks. + +Contact: Daniel Vetter, respective driver maintainers + +Clean up the clipped coordination confusion around planes +--------------------------------------------------------- + +We have a helper to get this right with drm_plane_helper_check_update(), but +it's not consistently used. This should be fixed, preferrably in the atomic +helpers (and drivers then moved over to clipped coordinates). Probably the +helper should also be moved from drm_plane_helper.c to the atomic helpers, to +avoid confusion - the other helpers in that file are all deprecated legacy +helpers. + +Contact: Ville Syrjälä, Daniel Vetter, driver maintainers + +Implement deferred fbdev setup in the helper +-------------------------------------------- + +Many (especially embedded drivers) want to delay fbdev setup until there's a +real screen plugged in. This is to avoid the dreaded fallback to the low-res +fbdev default. Many drivers have a hacked-up (and often broken) version of this, +better to do it once in the shared helpers. Thierry has a patch series, but that +one needs to be rebased and final polish applied. + +Contact: Thierry Reding, Daniel Vetter, driver maintainers + +Convert early atomic drivers to async commit helpers +---------------------------------------------------- + +For the first year the atomic modeset helpers didn't support asynchronous / +nonblocking commits, and every driver had to hand-roll them. This is fixed +now, but there's still a pile of existing drivers that easily could be +converted over to the new infrastructure. + +One issue with the helpers is that they require that drivers handle completion +events for atomic commits correctly. But fixing these bugs is good anyway. + +Contact: Daniel Vetter, respective driver maintainers + +Better manual-upload support for atomic +--------------------------------------- + +This would be especially useful for tinydrm: + +- Add a struct drm_rect dirty_clip to drm_crtc_state. When duplicating the + crtc state, clear that to the max values, x/y = 0 and w/h = MAX_INT, in + __drm_atomic_helper_crtc_duplicate_state(). + +- Move tinydrm_merge_clips into drm_framebuffer.c, dropping the tinydrm_ + prefix ofc and using drm_fb_. drm_framebuffer.c makes sense since this + is a function useful to implement the fb->dirty function. + +- Create a new drm_fb_dirty function which does essentially what e.g. + mipi_dbi_fb_dirty does. You can use e.g. drm_atomic_helper_update_plane as the + template. But instead of doing a simple full-screen plane update, this new + helper also sets crtc_state->dirty_clip to the right coordinates. And of + course it needs to check whether the fb is actually active (and maybe where), + so there's some book-keeping involved. There's also some good fun involved in + scaling things appropriately. For that case we might simply give up and + declare the entire area covered by the plane as dirty. + +Contact: Noralf Trønnes, Daniel Vetter + +Fallout from atomic KMS +----------------------- + +``drm_atomic_helper.c`` provides a batch of functions which implement legacy +IOCTLs on top of the new atomic driver interface. Which is really nice for +gradual conversion of drivers, but unfortunately the semantic mismatches are +a bit too severe. So there's some follow-up work to adjust the function +interfaces to fix these issues: + +* atomic needs the lock acquire context. At the moment that's passed around + implicitly with some horrible hacks, and it's also allocate with + ``GFP_NOFAIL`` behind the scenes. All legacy paths need to start allocating + the acquire context explicitly on stack and then also pass it down into + drivers explicitly so that the legacy-on-atomic functions can use them. + +* A bunch of the vtable hooks are now in the wrong place: DRM has a split + between core vfunc tables (named ``drm_foo_funcs``), which are used to + implement the userspace ABI. And then there's the optional hooks for the + helper libraries (name ``drm_foo_helper_funcs``), which are purely for + internal use. Some of these hooks should be move from ``_funcs`` to + ``_helper_funcs`` since they are not part of the core ABI. There's a + ``FIXME`` comment in the kerneldoc for each such case in ``drm_crtc.h``. + +* There's a new helper ``drm_atomic_helper_best_encoder()`` which could be + used by all atomic drivers which don't select the encoder for a given + connector at runtime. That's almost all of them, and would allow us to get + rid of a lot of ``best_encoder`` boilerplate in drivers. + +Contact: Daniel Vetter + +Get rid of dev->struct_mutex from GEM drivers +--------------------------------------------- + +``dev->struct_mutex`` is the Big DRM Lock from legacy days and infested +everything. Nowadays in modern drivers the only bit where it's mandatory is +serializing GEM buffer object destruction. Which unfortunately means drivers +have to keep track of that lock and either call ``unreference`` or +``unreference_locked`` depending upon context. + +Core GEM doesn't have a need for ``struct_mutex`` any more since kernel 4.8, +and there's a ``gem_free_object_unlocked`` callback for any drivers which are +entirely ``struct_mutex`` free. + +For drivers that need ``struct_mutex`` it should be replaced with a driver- +private lock. The tricky part is the BO free functions, since those can't +reliably take that lock any more. Instead state needs to be protected with +suitable subordinate locks or some cleanup work pushed to a worker thread. For +performance-critical drivers it might also be better to go with a more +fine-grained per-buffer object and per-context lockings scheme. Currently the +following drivers still use ``struct_mutex``: ``msm``, ``omapdrm`` and +``udl``. + +Contact: Daniel Vetter, respective driver maintainers + +Switch to drm_connector_list_iter for any connector_list walking +---------------------------------------------------------------- + +Connectors can be hotplugged, and we now have a special list of helpers to walk +the connector_list in a race-free fashion, without incurring deadlocks on +mutexes and other fun stuff. + +Unfortunately most drivers are not converted yet. At least all those supporting +DP MST hotplug should be converted, since for those drivers the difference +matters. See drm_for_each_connector_iter() vs. drm_for_each_connector(). + +Contact: Daniel Vetter + +Core refactorings +================= + +Use new IDR deletion interface to clean up drm_gem_handle_delete() +------------------------------------------------------------------ + +See the "This is gross" comment -- apparently the IDR system now can return an +error code instead of oopsing. + +Clean up the DRM header mess +---------------------------- + +Currently the DRM subsystem has only one global header, ``drmP.h``. This is +used both for functions exported to helper libraries and drivers and functions +only used internally in the ``drm.ko`` module. The goal would be to move all +header declarations not needed outside of ``drm.ko`` into +``drivers/gpu/drm/drm_*_internal.h`` header files. ``EXPORT_SYMBOL`` also +needs to be dropped for these functions. + +This would nicely tie in with the below task to create kerneldoc after the API +is cleaned up. Or with the "hide legacy cruft better" task. + +Note that this is well in progress, but ``drmP.h`` is still huge. The updated +plan is to switch to per-file driver API headers, which will also structure +the kerneldoc better. This should also allow more fine-grained ``#include`` +directives. + +In the end no .c file should need to include ``drmP.h`` anymore. + +Contact: Daniel Vetter + +Add missing kerneldoc for exported functions +-------------------------------------------- + +The DRM reference documentation is still lacking kerneldoc in a few areas. The +task would be to clean up interfaces like moving functions around between +files to better group them and improving the interfaces like dropping return +values for functions that never fail. Then write kerneldoc for all exported +functions and an overview section and integrate it all into the drm DocBook. + +See https://dri.freedesktop.org/docs/drm/ for what's there already. + +Contact: Daniel Vetter + +Hide legacy cruft better +------------------------ + +Way back DRM supported only drivers which shadow-attached to PCI devices with +userspace or fbdev drivers setting up outputs. Modern DRM drivers take charge +of the entire device, you can spot them with the DRIVER_MODESET flag. + +Unfortunately there's still large piles of legacy code around which needs to +be hidden so that driver writers don't accidentally end up using it. And to +prevent security issues in those legacy IOCTLs from being exploited on modern +drivers. This has multiple possible subtasks: + +* Extract support code for legacy features into a ``drm-legacy.ko`` kernel + module and compile it only when one of the legacy drivers is enabled. + +This is mostly done, the only thing left is to split up ``drm_irq.c`` into +legacy cruft and the parts needed by modern KMS drivers. + +Contact: Daniel Vetter + +Make panic handling work +------------------------ + +This is a really varied tasks with lots of little bits and pieces: + +* The panic path can't be tested currently, leading to constant breaking. The + main issue here is that panics can be triggered from hardirq contexts and + hence all panic related callback can run in hardirq context. It would be + awesome if we could test at least the fbdev helper code and driver code by + e.g. trigger calls through drm debugfs files. hardirq context could be + achieved by using an IPI to the local processor. + +* There's a massive confusion of different panic handlers. DRM fbdev emulation + helpers have one, but on top of that the fbcon code itself also has one. We + need to make sure that they stop fighting over each another. + +* ``drm_can_sleep()`` is a mess. It hides real bugs in normal operations and + isn't a full solution for panic paths. We need to make sure that it only + returns true if there's a panic going on for real, and fix up all the + fallout. + +* The panic handler must never sleep, which also means it can't ever + ``mutex_lock()``. Also it can't grab any other lock unconditionally, not + even spinlocks (because NMI and hardirq can panic too). We need to either + make sure to not call such paths, or trylock everything. Really tricky. + +* For the above locking troubles reasons it's pretty much impossible to + attempt a synchronous modeset from panic handlers. The only thing we could + try to achive is an atomic ``set_base`` of the primary plane, and hope that + it shows up. Everything else probably needs to be delayed to some worker or + something else which happens later on. Otherwise it just kills the box + harder, prevent the panic from going out on e.g. netconsole. + +* There's also proposal for a simplied DRM console instead of the full-blown + fbcon and DRM fbdev emulation. Any kind of panic handling tricks should + obviously work for both console, in case we ever get kmslog merged. + +Contact: Daniel Vetter + +Clean up the debugfs support +---------------------------- + +There's a bunch of issues with it: + +- The drm_info_list ->show() function doesn't even bother to cast to the drm + structure for you. This is lazy. + +- We probably want to have some support for debugfs files on crtc/connectors and + maybe other kms objects directly in core. There's even drm_print support in + the funcs for these objects to dump kms state, so it's all there. And then the + ->show() functions should obviously give you a pointer to the right object. + +- The drm_info_list stuff is centered on drm_minor instead of drm_device. For + anything we want to print drm_device (or maybe drm_file) is the right thing. + +- The drm_driver->debugfs_init hooks we have is just an artifact of the old + midlayered load sequence. DRM debugfs should work more like sysfs, where you + can create properties/files for an object anytime you want, and the core + takes care of publishing/unpuplishing all the files at register/unregister + time. Drivers shouldn't need to worry about these technicalities, and fixing + this (together with the drm_minor->drm_device move) would allow us to remove + debugfs_init. + +Contact: Daniel Vetter + +Better Testing +============== + +Enable trinity for DRM +---------------------- + +And fix up the fallout. Should be really interesting ... + +Make KMS tests in i-g-t generic +------------------------------- + +The i915 driver team maintains an extensive testsuite for the i915 DRM driver, +including tons of testcases for corner-cases in the modesetting API. It would +be awesome if those tests (at least the ones not relying on Intel-specific GEM +features) could be made to run on any KMS driver. + +Basic work to run i-g-t tests on non-i915 is done, what's now missing is mass- +converting things over. For modeset tests we also first need a bit of +infrastructure to use dumb buffers for untiled buffers, to be able to run all +the non-i915 specific modeset tests. + +Contact: Daniel Vetter + +Create a virtual KMS driver for testing (vkms) +---------------------------------------------- + +With all the latest helpers it should be fairly simple to create a virtual KMS +driver useful for testing, or for running X or similar on headless machines +(to be able to still use the GPU). This would be similar to vgem, but aimed at +the modeset side. + +Once the basics are there there's tons of possibilities to extend it. + +Contact: Daniel Vetter + +Driver Specific +=============== + +tinydrm +------- + +Tinydrm is the helper driver for really simple fb drivers. The goal is to make +those drivers as simple as possible, so lots of room for refactoring: + +- backlight helpers, probably best to put them into a new drm_backlight.c. + This is because drivers/video is de-facto unmaintained. We could also + move drivers/video/backlight to drivers/gpu/backlight and take it all + over within drm-misc, but that's more work. + +- spi helpers, probably best put into spi core/helper code. Thierry said + the spi maintainer is fast&reactive, so shouldn't be a big issue. + +- extract the mipi-dbi helper (well, the non-tinydrm specific parts at + least) into a separate helper, like we have for mipi-dsi already. Or follow + one of the ideas for having a shared dsi/dbi helper, abstracting away the + transport details more. + +- tinydrm_lastclose could be drm_fb_helper_lastclose. Only thing we need + for that is to store the drm_fb_helper pointer somewhere in + drm_device->mode_config. And then we could roll that out to all the + drivers. + +- tinydrm_gem_cma_prime_import_sg_table should probably go into the cma + helpers, as a _vmapped variant (since not every driver needs the vmap). + And tinydrm_gem_cma_free_object could the be merged into + drm_gem_cma_free_object(). + +- tinydrm_fb_create we could move into drm_simple_pipe, only need to add + the fb_create hook to drm_simple_pipe_funcs, which would again simplify a + bunch of things (since it gives you a one-stop vfunc for simple drivers). + +- Quick aside: The unregister devm stuff is kinda getting the lifetimes of + a drm_device wrong. Doesn't matter, since everyone else gets it wrong + too :-) + +- With the fbdev pointer in dev->mode_config we could also make + suspend/resume helpers entirely generic, at least if we add a + dev->mode_config.suspend_state. We could even provide a generic pm_ops + structure with those. + +- also rework the drm_framebuffer_funcs->dirty hook wire-up, see above. + +Contact: Noralf Trønnes, Daniel Vetter + +Outside DRM +=========== diff --git a/Documentation/gpu/vc4.rst b/Documentation/gpu/vc4.rst new file mode 100644 index 000000000000..5df1d98b9544 --- /dev/null +++ b/Documentation/gpu/vc4.rst @@ -0,0 +1,89 @@ +===================================== + drm/vc4 Broadcom VC4 Graphics Driver +===================================== + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_drv.c + :doc: Broadcom VC4 Graphics Driver + +Display Hardware Handling +========================= + +This section covers everything related to the display hardware including +the mode setting infrastructure, plane, sprite and cursor handling and +display, output probing and related topics. + +Pixel Valve (DRM CRTC) +---------------------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_crtc.c + :doc: VC4 CRTC module + +HVS +--- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_hvs.c + :doc: VC4 HVS module. + +HVS planes +---------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_plane.c + :doc: VC4 plane module + +HDMI encoder +------------ + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_hdmi.c + :doc: VC4 Falcon HDMI module + +DSI encoder +----------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_dsi.c + :doc: VC4 DSI0/DSI1 module + +DPI encoder +----------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_dpi.c + :doc: VC4 DPI module + +VEC (Composite TV out) encoder +------------------------------ + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_vec.c + :doc: VC4 SDTV module + +Memory Management and 3D Command Submission +=========================================== + +This section covers the GEM implementation in the vc4 driver. + +GPU buffer object (BO) management +--------------------------------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_bo.c + :doc: VC4 GEM BO management support + +V3D binner command list (BCL) validation +---------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_validate.c + :doc: Command list validator for VC4. + +V3D render command list (RCL) generation +---------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_render_cl.c + :doc: Render command list generation + +Shader validator for VC4 +--------------------------- +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_validate_shaders.c + :doc: Shader validator for VC4. + +V3D Interrupts +-------------- + +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_irq.c + :doc: Interrupt management for the V3D engine diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.txt index 029e6cb9a7e8..c8436e354f44 100644 --- a/Documentation/hid/hidraw.txt +++ b/Documentation/hid/hidraw.txt @@ -81,7 +81,7 @@ of: BUS_HIL BUS_BLUETOOTH BUS_VIRTUAL -which are defined in linux/input.h. +which are defined in uapi/linux/input.h. HIDIOCGRAWNAME(len): Get Raw Name This ioctl returns a string containing the vendor and product strings of diff --git a/Documentation/hwmon/aspeed-pwm-tacho b/Documentation/hwmon/aspeed-pwm-tacho new file mode 100644 index 000000000000..7cfb34977460 --- /dev/null +++ b/Documentation/hwmon/aspeed-pwm-tacho @@ -0,0 +1,22 @@ +Kernel driver aspeed-pwm-tacho +============================== + +Supported chips: + ASPEED AST2400/2500 + +Authors: + <jaghu@google.com> + +Description: +------------ +This driver implements support for ASPEED AST2400/2500 PWM and Fan Tacho +controller. The PWM controller supports upto 8 PWM outputs. The Fan tacho +controller supports up to 16 tachometer inputs. + +The driver provides the following sensor accesses in sysfs: + +fanX_input ro provide current fan rotation value in RPM as reported + by the fan to the device. + +pwmX rw get or set PWM fan control value. This is an integer + value between 0(off) and 255(full speed). diff --git a/Documentation/hwmon/tc654 b/Documentation/hwmon/tc654 index 91a2843f5f98..47636a8077b4 100644 --- a/Documentation/hwmon/tc654 +++ b/Documentation/hwmon/tc654 @@ -2,7 +2,7 @@ Kernel driver tc654 =================== Supported chips: - * Microship TC654 and TC655 + * Microchip TC654 and TC655 Prefix: 'tc654' Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/20001734C.pdf diff --git a/Documentation/index.rst b/Documentation/index.rst index f6e641a54bbc..61306a22888d 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -24,6 +24,18 @@ trying to get it to work optimally on a given system. admin-guide/index +Application-developer documentation +----------------------------------- + +The user-space API manual gathers together documents describing aspects of +the kernel interface as seen by application developers. + +.. toctree:: + :maxdepth: 2 + + userspace-api/index + + Introduction to kernel development ---------------------------------- @@ -76,6 +88,14 @@ Chinese translations translations/zh_CN/index +Japanese translations +--------------------- + +.. toctree:: + :maxdepth: 1 + + translations/ja_JP/index + Indices and tables ================== diff --git a/Documentation/infiniband/opa_vnic.txt b/Documentation/infiniband/opa_vnic.txt new file mode 100644 index 000000000000..282e17be798a --- /dev/null +++ b/Documentation/infiniband/opa_vnic.txt @@ -0,0 +1,153 @@ +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. + +Architecture +============= +The patterns of exchanges of Omni-Path encapsulated Ethernet packets +involves one or more virtual Ethernet switches overlaid on the Omni-Path +fabric topology. A subset of HFI nodes on the Omni-Path fabric are +permitted to exchange encapsulated Ethernet packets across a particular +virtual Ethernet switch. The virtual Ethernet switches are logical +abstractions achieved by configuring the HFI nodes on the fabric for +header generation and processing. In the simplest configuration all HFI +nodes across the fabric exchange encapsulated Ethernet packets over a +single virtual Ethernet switch. A virtual Ethernet switch, is effectively +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 | + +------------------------+ +------------------------+ + + +The Omni-Path encapsulated Ethernet packet format is as described below. + +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) + +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 + +Quad Word 2: +0-15 Reserved +16-31 L4 header +32-63 Ethernet Packet + +Quad Words 3 to N-1: +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) + +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 +padded. On the receive side the 'Tail' field is read and the padding is +removed (along with ICRC, Tail and OPA header) before passing packet up +the network stack. + +The L4 header field contains the virtual Ethernet switch id the VNIC port +belongs to. On the receive side, this field is used to de-multiplex the +received VNIC packets to different VNIC ports. + +Driver Design +============== +Intel OPA VNIC software design is presented in the below diagram. +OPA VNIC functionality has a HW dependent component and a HW +independent component. + +The support has been added for IB device to allocate and free the RDMA +netdev devices. The RDMA netdev supports interfacing with the network +stack thus creating standard network interfaces. OPA_VNIC is an RDMA +netdev device type. + +The HW dependent VNIC functionality is part of the HFI1 driver. It +implements the verbs to allocate and free the OPA_VNIC RDMA netdev. +It involves HW resource allocation/management for VNIC functionality. +It interfaces with the network stack and implements the required +net_device_ops functions. It expects Omni-Path encapsulated Ethernet +packets in the transmit path and provides HW access to them. It strips +the Omni-Path header from the received packets before passing them up +the network stack. It also implements the RDMA netdev control operations. + +The OPA VNIC module implements the HW independent VNIC functionality. +It consists of two parts. The VNIC Ethernet Management Agent (VEMA) +registers itself with IB core as an IB client and interfaces with the +IB MAD stack. It exchanges the management information with the Ethernet +Manager (EM) and the VNIC netdev. The VNIC netdev part allocates and frees +the OPA_VNIC RDMA netdev devices. It overrides the net_device_ops functions +set by HW dependent VNIC driver where required to accommodate any control +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. + + +-------------------+ +----------------------+ + | | | Linux | + | IB MAD | | Network | + | | | Stack | + +-------------------+ +----------------------+ + | | | + | | | + +----------------------------+ | + | | | + | OPA VNIC Module | | + | (OPA VNIC RDMA Netdev | | + | & EMA functions) | | + | | | + +----------------------------+ | + | | + | | + +------------------+ | + | IB core | | + +------------------+ | + | | + | | + +--------------------------------------------+ + | | + | HFI1 Driver with VNIC support | + | | + +--------------------------------------------+ diff --git a/Documentation/input/cd32.txt b/Documentation/input/cd32.txt deleted file mode 100644 index a003d9b41eca..000000000000 --- a/Documentation/input/cd32.txt +++ /dev/null @@ -1,19 +0,0 @@ -I have written a small patch that let's me use my Amiga CD32 -joypad connected to the parallel port. Thought I'd share it with you so -you can add it to the list of supported joysticks (hopefully someone will -find it useful). - -It needs the following wiring: - -CD32 pad | Parallel port ----------------------------- -1 (Up) | 2 (D0) -2 (Down) | 3 (D1) -3 (Left) | 4 (D2) -4 (Right) | 5 (D3) -5 (Fire3) | 14 (AUTOFD) -6 (Fire1) | 17 (SELIN) -7 (+5V) | 1 (STROBE) -8 (Gnd) | 18 (Gnd) -9 (Fire2) | 7 (D5) - diff --git a/Documentation/input/conf.py b/Documentation/input/conf.py new file mode 100644 index 000000000000..d2352fdc92ed --- /dev/null +++ b/Documentation/input/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = "The Linux input driver subsystem" + +tags.add("subproject") + +latex_documents = [ + ('index', 'linux-input.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/input/alps.txt b/Documentation/input/devices/alps.rst index 8d1341ccde64..6779148e428c 100644 --- a/Documentation/input/alps.txt +++ b/Documentation/input/devices/alps.rst @@ -1,10 +1,11 @@ +---------------------- ALPS Touchpad Protocol ---------------------- Introduction ------------ Currently the ALPS touchpad driver supports seven protocol versions in use by -ALPS touchpads, called versions 1, 2, 3, 4, 5, 6 and 7. +ALPS touchpads, called versions 1, 2, 3, 4, 5, 6, 7 and 8. Since roughly mid-2010 several new ALPS touchpads have been released and integrated into a variety of laptops and netbooks. These new touchpads @@ -78,7 +79,7 @@ of the EC response. Packet Format ------------- -In the following tables, the following notation is used. +In the following tables, the following notation is used:: CAPITALS = stick, miniscules = touchpad @@ -88,6 +89,8 @@ extra buttons, stick buttons on a dualpoint, etc. PS/2 packet format ------------------ +:: + byte 0: 0 0 YSGN XSGN 1 M R L byte 1: X7 X6 X5 X4 X3 X2 X1 X0 byte 2: Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 @@ -99,7 +102,9 @@ are on the touchpad, the M R L bits signal the combined status of both the pointingstick and touchpad buttons. ALPS Absolute Mode - Protocol Version 1 --------------------------------------- +--------------------------------------- + +:: byte 0: 1 0 0 0 1 x9 x8 x7 byte 1: 0 x6 x5 x4 x3 x2 x1 x0 @@ -111,6 +116,8 @@ ALPS Absolute Mode - Protocol Version 1 ALPS Absolute Mode - Protocol Version 2 --------------------------------------- +:: + byte 0: 1 ? ? ? 1 PSM PSR PSL byte 1: 0 x6 x5 x4 x3 x2 x1 x0 byte 2: 0 x10 x9 x8 x7 ? fin ges @@ -127,6 +134,8 @@ and PSL bits. Dualpoint device -- interleaved packet format --------------------------------------------- +:: + byte 0: 1 1 0 0 1 1 1 1 byte 1: 0 x6 x5 x4 x3 x2 x1 x0 byte 2: 0 x10 x9 x8 x7 0 fin ges @@ -149,7 +158,7 @@ ALPS protocol version 3 has three different packet formats. The first two are associated with touchpad events, and the third is associated with trackstick events. -The first type is the touchpad position packet. +The first type is the touchpad position packet:: byte 0: 1 ? x1 x0 1 1 1 1 byte 1: 0 x10 x9 x8 x7 x6 x5 x4 @@ -165,7 +174,7 @@ The second packet type contains bitmaps representing the x and y axes. In the bitmaps a given bit is set if there is a finger covering that position on the given axis. Thus the bitmap packet can be used for low-resolution multi-touch data, although finger tracking is not possible. This packet also encodes the -number of contacts (f1 and f0 in the table below). +number of contacts (f1 and f0 in the table below):: byte 0: 1 1 x1 x0 1 1 1 1 byte 1: 0 x8 x7 x6 x5 x4 x3 x2 @@ -178,7 +187,7 @@ This packet only appears after a position packet with the mt bit set, and usually only appears when there are two or more contacts (although occasionally it's seen with only a single contact). -The final v3 packet type is the trackstick packet. +The final v3 packet type is the trackstick packet:: byte 0: 1 1 x7 y7 1 1 1 1 byte 1: 0 x6 x5 x4 x3 x2 x1 x0 @@ -190,7 +199,7 @@ The final v3 packet type is the trackstick packet. ALPS Absolute Mode - Protocol Version 4 --------------------------------------- -Protocol version 4 has an 8-byte packet format. +Protocol version 4 has an 8-byte packet format:: byte 0: 1 ? x1 x0 1 1 1 1 byte 1: 0 x10 x9 x8 x7 x6 x5 x4 @@ -203,7 +212,7 @@ Protocol version 4 has an 8-byte packet format. The last two bytes represent a partial bitmap packet, with 3 full packets required to construct a complete bitmap packet. Once assembled, the 6-byte -bitmap packet has the following format: +bitmap packet has the following format:: byte 0: 0 1 x7 x6 x5 x4 x3 x2 byte 1: 0 x1 x0 y4 y3 y2 y1 y0 @@ -238,7 +247,7 @@ decode. It uses the same alps_process_touchpad_packet_v3 call with a specialized decode_fields function pointer to correctly interpret the packets. This appears to only be used by the Dolphin devices. -For single-touch, the 6-byte packet format is: +For single-touch, the 6-byte packet format is:: byte 0: 1 1 0 0 1 0 0 0 byte 1: 0 x6 x5 x4 x3 x2 x1 x0 @@ -247,7 +256,7 @@ For single-touch, the 6-byte packet format is: byte 4: y10 y9 y8 y7 x10 x9 x8 x7 byte 5: 0 z6 z5 z4 z3 z2 z1 z0 -For mt, the format is: +For mt, the format is:: byte 0: 1 1 1 n3 1 n2 n1 x24 byte 1: 1 y7 y6 y5 y4 y3 y2 y1 @@ -259,7 +268,7 @@ For mt, the format is: ALPS Absolute Mode - Protocol Version 6 --------------------------------------- -For trackstick packet, the format is: +For trackstick packet, the format is:: byte 0: 1 1 1 1 1 1 1 1 byte 1: 0 X6 X5 X4 X3 X2 X1 X0 @@ -268,7 +277,7 @@ For trackstick packet, the format is: byte 4: Z7 Z6 Z5 Z4 Z3 Z2 Z1 Z0 byte 5: 0 1 1 1 1 1 1 1 -For touchpad packet, the format is: +For touchpad packet, the format is:: byte 0: 1 1 1 1 1 1 1 1 byte 1: 0 0 0 0 x3 x2 x1 x0 @@ -282,7 +291,7 @@ For touchpad packet, the format is: ALPS Absolute Mode - Protocol Version 7 --------------------------------------- -For trackstick packet, the format is: +For trackstick packet, the format is:: byte 0: 0 1 0 0 1 0 0 0 byte 1: 1 1 * * 1 M R L @@ -291,7 +300,7 @@ For trackstick packet, the format is: byte 4: Y7 0 Y5 Y4 Y3 1 1 0 byte 5: T&P 0 Z5 Z4 Z3 Z2 Z1 Z0 -For touchpad packet, the format is: +For touchpad packet, the format is:: packet-fmt b7 b6 b5 b4 b3 b2 b1 b0 byte 0: TWO & MULTI L 1 R M 1 Y0-2 Y0-1 Y0-0 @@ -328,7 +337,7 @@ Spoken by SS4 (73 03 14) and SS5 (73 03 28) hardware. The packet type is given by the APD field, bits 4-5 of byte 3. -Touchpad packet (APD = 0x2): +Touchpad packet (APD = 0x2):: b7 b6 b5 b4 b3 b2 b1 b0 byte 0: SWM SWR SWL 1 1 0 0 X7 @@ -340,7 +349,7 @@ Touchpad packet (APD = 0x2): SWM, SWR, SWL: Middle, Right, and Left button states -Touchpad 1 Finger packet (APD = 0x0): +Touchpad 1 Finger packet (APD = 0x0):: b7 b6 b5 b4 b3 b2 b1 b0 byte 0: SWM SWR SWL 1 1 X2 X1 X0 @@ -353,7 +362,7 @@ Touchpad 1 Finger packet (APD = 0x0): TAPF: ??? LFB: ??? -Touchpad 2 Finger packet (APD = 0x1): +Touchpad 2 Finger packet (APD = 0x1):: b7 b6 b5 b4 b3 b2 b1 b0 byte 0: SWM SWR SWL 1 1 AX6 AX5 AX4 @@ -365,7 +374,7 @@ Touchpad 2 Finger packet (APD = 0x1): CONT: A 3-or-4 Finger packet is to follow -Touchpad 3-or-4 Finger packet (APD = 0x3): +Touchpad 3-or-4 Finger packet (APD = 0x3):: b7 b6 b5 b4 b3 b2 b1 b0 byte 0: SWM SWR SWL 1 1 AX6 AX5 AX4 diff --git a/Documentation/input/amijoy.txt b/Documentation/input/devices/amijoy.rst index 7dc4f175943c..8df7b11cd98d 100644 --- a/Documentation/input/amijoy.txt +++ b/Documentation/input/devices/amijoy.rst @@ -1,67 +1,101 @@ +~~~~~~~~~~~~~~~~~~~~~~~~~ +Amiga joystick extensions +~~~~~~~~~~~~~~~~~~~~~~~~~ + + Amiga 4-joystick parport extension ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Parallel port pins: - (2) - Up1 (6) - Up2 - (3) - Down1 (7) - Down2 - (4) - Left1 (8) - Left2 - (5) - Right1 (9) - Right2 -(13) - Fire1 (11) - Fire2 -(18) - Gnd1 (18) - Gnd2 + +===== ======== ==== ========== +Pin Meaning Pin Meaning +===== ======== ==== ========== + 2 Up1 6 Up2 + 3 Down1 7 Down2 + 4 Left1 8 Left2 + 5 Right1 9 Right2 +13 Fire1 11 Fire2 +18 Gnd1 18 Gnd2 +===== ======== ==== ========== Amiga digital joystick pinout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -(1) - Up -(2) - Down -(3) - Left -(4) - Right -(5) - n/c -(6) - Fire button -(7) - +5V (50mA) -(8) - Gnd -(9) - Thumb button + +=== ============ +Pin Meaning +=== ============ +1 Up +2 Down +3 Left +4 Right +5 n/c +6 Fire button +7 +5V (50mA) +8 Gnd +9 Thumb button +=== ============ Amiga mouse pinout ~~~~~~~~~~~~~~~~~~ -(1) - V-pulse -(2) - H-pulse -(3) - VQ-pulse -(4) - HQ-pulse -(5) - Middle button -(6) - Left button -(7) - +5V (50mA) -(8) - Gnd -(9) - Right button + +=== ============ +Pin Meaning +=== ============ +1 V-pulse +2 H-pulse +3 VQ-pulse +4 HQ-pulse +5 Middle button +6 Left button +7 +5V (50mA) +8 Gnd +9 Right button +=== ============ Amiga analog joystick pinout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -(1) - Top button -(2) - Top2 button -(3) - Trigger button -(4) - Thumb button -(5) - Analog X -(6) - n/c -(7) - +5V (50mA) -(8) - Gnd -(9) - Analog Y + +=== ============== +Pin Meaning +=== ============== +1 Top button +2 Top2 button +3 Trigger button +4 Thumb button +5 Analog X +6 n/c +7 +5V (50mA) +8 Gnd +9 Analog Y +=== ============== Amiga lightpen pinout ~~~~~~~~~~~~~~~~~~~~~ -(1) - n/c -(2) - n/c -(3) - n/c -(4) - n/c -(5) - Touch button -(6) - /Beamtrigger -(7) - +5V (50mA) -(8) - Gnd -(9) - Stylus button + +=== ============= +Pin Meaning +=== ============= +1 n/c +2 n/c +3 n/c +4 n/c +5 Touch button +6 /Beamtrigger +7 +5V (50mA) +8 Gnd +9 Stylus button +=== ============= ------------------------------------------------------------------------------- +======== === ==== ==== ====== ======================================== NAME rev ADDR type chip Description +======== === ==== ==== ====== ======================================== JOY0DAT 00A R Denise Joystick-mouse 0 data (left vert, horiz) JOY1DAT 00C R Denise Joystick-mouse 1 data (right vert,horiz) +======== === ==== ==== ====== ======================================== These addresses each read a 16 bit register. These in turn are loaded from the MDAT serial stream and are clocked in on @@ -71,12 +105,17 @@ JOY1DAT 00C R Denise Joystick-mouse 1 data (right vert,horiz) controller ports (8 total) plus 8 miscellaneous control bits which are new for LISA and can be read in upper 8 bits of LISAID. + Register bits are as follows: - Mouse counter usage (pins 1,3 =Yclock, pins 2,4 =Xclock) + - Mouse counter usage (pins 1,3 =Yclock, pins 2,4 =Xclock) + +======== === === === === === === === === ====== === === === === === === === BIT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 +======== === === === === === === === === ====== === === === === === === === JOY0DAT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 JOY1DAT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 +======== === === === === === === === === ====== === === === === === === === 0=LEFT CONTROLLER PAIR, 1=RIGHT CONTROLLER PAIR. (4 counters total). The bit usage for both left and right @@ -86,14 +125,21 @@ JOY1DAT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 +-------------------+-----------------------------------------+ | Serial | Bit Name | Description | - +--------+----------+-----------------------------------------+ + +========+==========+=========================================+ | 0 | M0H | JOY0DAT Horizontal Clock | + +--------+----------+-----------------------------------------+ | 1 | M0HQ | JOY0DAT Horizontal Clock (quadrature) | + +--------+----------+-----------------------------------------+ | 2 | M0V | JOY0DAT Vertical Clock | + +--------+----------+-----------------------------------------+ | 3 | M0VQ | JOY0DAT Vertical Clock (quadrature) | + +--------+----------+-----------------------------------------+ | 4 | M1V | JOY1DAT Horizontal Clock | + +--------+----------+-----------------------------------------+ | 5 | M1VQ | JOY1DAT Horizontal Clock (quadrature) | + +--------+----------+-----------------------------------------+ | 6 | M1V | JOY1DAT Vertical Clock | + +--------+----------+-----------------------------------------+ | 7 | M1VQ | JOY1DAT Vertical Clock (quadrature) | +--------+----------+-----------------------------------------+ @@ -104,46 +150,65 @@ JOY1DAT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 +------------+------+---------------------------------+ | Directions | Pin# | Counter bits | - +------------+------+---------------------------------+ + +============+======+=================================+ | Forward | 1 | Y1 xor Y0 (BIT#09 xor BIT#08) | + +------------+------+---------------------------------+ | Left | 3 | Y1 | + +------------+------+---------------------------------+ | Back | 2 | X1 xor X0 (BIT#01 xor BIT#00) | + +------------+------+---------------------------------+ | Right | 4 | X1 | +------------+------+---------------------------------+ ------------------------------------------------------------------------------- +======== === ==== ==== ====== ================================================= NAME rev ADDR type chip Description +======== === ==== ==== ====== ================================================= JOYTEST 036 W Denise Write to all 4 joystick-mouse counters at once. +======== === ==== ==== ====== ================================================= Mouse counter write test data: + +========= === === === === === === === === ====== === === === === === === === BIT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 +========= === === === === === === === === ====== === === === === === === === JOYxDAT Y7 Y6 Y5 Y4 Y3 Y2 xx xx X7 X6 X5 X4 X3 X2 xx xx JOYxDAT Y7 Y6 Y5 Y4 Y3 Y2 xx xx X7 X6 X5 X4 X3 X2 xx xx +========= === === === === === === === === ====== === === === === === === === ------------------------------------------------------------------------------- +======= === ==== ==== ====== ======================================== NAME rev ADDR type chip Description +======= === ==== ==== ====== ======================================== POT0DAT h 012 R Paula Pot counter data left pair (vert, horiz) POT1DAT h 014 R Paula Pot counter data right pair (vert,horiz) +======= === ==== ==== ====== ======================================== These addresses each read a pair of 8 bit pot counters. (4 counters total). The bit assignment for both addresses is shown below. The counters are stopped by signals from 2 controller connectors (left-right) with 2 pins each. +====== === === === === === === === === ====== === === === === === === === BIT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 +====== === === === === === === === === ====== === === === === === === === RIGHT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 LEFT Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0 X7 X6 X5 X4 X3 X2 X1 X0 +====== === === === === === === === === ====== === === === === === === === +--------------------------+-------+ | CONNECTORS | PAULA | +-------+------+-----+-----+-------+ | Loc. | Dir. | Sym | pin | pin | - +-------+------+-----+-----+-------+ + +=======+======+=====+=====+=======+ | RIGHT | Y | RX | 9 | 33 | + +-------+------+-----+-----+-------+ | RIGHT | X | RX | 5 | 32 | + +-------+------+-----+-----+-------+ | LEFT | Y | LY | 9 | 36 | + +-------+------+-----+-----+-------+ | LEFT | X | LX | 5 | 35 | +-------+------+-----+-----+-------+ @@ -155,30 +220,44 @@ POT1DAT h 014 R Paula Pot counter data right pair (vert,horiz) ------------------------------------------------------------------------------- +====== === ==== ==== ====== ================================================ NAME rev ADDR type chip Description -POTGO 034 W Paula Pot port (4 bit) bi-direction and data, and pot counter start. +====== === ==== ==== ====== ================================================ +POTGO 034 W Paula Pot port (4 bit) bi-direction and data, and pot + counter start. +====== === ==== ==== ====== ================================================ ------------------------------------------------------------------------------- +====== === ==== ==== ====== ================================================ NAME rev ADDR type chip Description +====== === ==== ==== ====== ================================================ POTINP 016 R Paula Pot pin data read +====== === ==== ==== ====== ================================================ This register controls a 4 bit bi-direction I/O port that shares the same 4 pins as the 4 pot counters above. +-------+----------+---------------------------------------------+ | BIT# | FUNCTION | DESCRIPTION | - +-------+----------+---------------------------------------------+ + +=======+==========+=============================================+ | 15 | OUTRY | Output enable for Paula pin 33 | + +-------+----------+---------------------------------------------+ | 14 | DATRY | I/O data Paula pin 33 | + +-------+----------+---------------------------------------------+ | 13 | OUTRX | Output enable for Paula pin 32 | + +-------+----------+---------------------------------------------+ | 12 | DATRX | I/O data Paula pin 32 | + +-------+----------+---------------------------------------------+ | 11 | OUTLY | Out put enable for Paula pin 36 | + +-------+----------+---------------------------------------------+ | 10 | DATLY | I/O data Paula pin 36 | + +-------+----------+---------------------------------------------+ | 09 | OUTLX | Output enable for Paula pin 35 | + +-------+----------+---------------------------------------------+ | 08 | DATLX | I/O data Paula pin 35 | + +-------+----------+---------------------------------------------+ | 07-01 | X | Not used | + +-------+----------+---------------------------------------------+ | 00 | START | Start pots (dump capacitors,start counters) | +-------+----------+---------------------------------------------+ - -------------------------------------------------------------------------------- diff --git a/Documentation/input/appletouch.txt b/Documentation/input/devices/appletouch.rst index b13de3f89108..c94470e66533 100644 --- a/Documentation/input/appletouch.txt +++ b/Documentation/input/devices/appletouch.rst @@ -1,12 +1,17 @@ +.. include:: <isonum.txt> + +---------------------------------- Apple Touchpad Driver (appletouch) ---------------------------------- - Copyright (C) 2005 Stelian Pop <stelian@popies.net> + +:Copyright: |copy| 2005 Stelian Pop <stelian@popies.net> appletouch is a Linux kernel driver for the USB touchpad found on post February 2005 and October 2005 Apple Aluminium Powerbooks. -This driver is derived from Johannes Berg's appletrackpad driver[1], but it has -been improved in some areas: +This driver is derived from Johannes Berg's appletrackpad driver [#f1]_, +but it has been improved in some areas: + * appletouch is a full kernel driver, no userspace program is necessary * appletouch can be interfaced with the synaptics X11 driver, in order to have touchpad acceleration, scrolling, etc. @@ -16,8 +21,8 @@ Frank Arnold for further improvements, and Alex Harper for some additional information about the inner workings of the touchpad sensors. Michael Hanselmann added support for the October 2005 models. -Usage: ------- +Usage +----- In order to use the touchpad in the basic mode, compile the driver and load the module. A new input device will be detected and you will be able to read @@ -27,13 +32,13 @@ In X11, you can configure the touchpad to use the synaptics X11 driver, which will give additional functionalities, like acceleration, scrolling, 2 finger tap for middle button mouse emulation, 3 finger tap for right button mouse emulation, etc. In order to do this, make sure you're using a recent version of -the synaptics driver (tested with 0.14.2, available from [2]), and configure a -new input device in your X11 configuration file (take a look below for an -example). For additional configuration, see the synaptics driver documentation. +the synaptics driver (tested with 0.14.2, available from [#f2]_), and configure +a new input device in your X11 configuration file (take a look below for an +example). For additional configuration, see the synaptics driver documentation:: Section "InputDevice" - Identifier "Synaptics Touchpad" - Driver "synaptics" + Identifier "Synaptics Touchpad" + Driver "synaptics" Option "SendCoreEvents" "true" Option "Device" "/dev/input/mice" Option "Protocol" "auto-dev" @@ -60,8 +65,8 @@ example). For additional configuration, see the synaptics driver documentation. ... EndSection -Fuzz problems: --------------- +Fuzz problems +------------- The touchpad sensors are very sensitive to heat, and will generate a lot of noise when the temperature changes. This is especially true when you power-on @@ -73,13 +78,17 @@ the driver. You can activate debugging using the 'debug' module parameter. A value of 0 deactivates any debugging, 1 activates tracing of invalid samples, 2 activates -full tracing (each sample is being traced): +full tracing (each sample is being traced):: + modprobe appletouch debug=1 - or + +or:: + echo "1" > /sys/module/appletouch/parameters/debug -Links: ------- -[1]: http://johannes.sipsolutions.net/PowerBook/touchpad/ -[2]: http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html +.. Links: + +.. [#f1] http://johannes.sipsolutions.net/PowerBook/touchpad/ + +.. [#f2] `<http://web.archive.org/web/*/http://web.telia.com/~u89404340/touchpad/index.html>`_ diff --git a/Documentation/input/atarikbd.txt b/Documentation/input/devices/atarikbd.rst index f3a3ba8847ba..745e7a1ff122 100644 --- a/Documentation/input/atarikbd.txt +++ b/Documentation/input/devices/atarikbd.rst @@ -1,7 +1,10 @@ +==================================== Intelligent Keyboard (ikbd) Protocol +==================================== -1. Introduction +Introduction +============ The Atari Corp. Intelligent Keyboard (ikbd) is a general purpose keyboard controller that is flexible enough that it can be used in a variety of @@ -18,7 +21,8 @@ different applications of the keyboard, joysticks, or mouse. Limited use of the controller is possible in applications in which only a unidirectional communications medium is available by carefully designing the default modes. -3. Keyboard +Keyboard +======== The keyboard always returns key make/break scan codes. The ikbd generates keyboard scan codes for each key press and release. The key scan make (key @@ -28,19 +32,25 @@ exists in that position on a particular keyboard. The break code for each key is obtained by ORing 0x80 with the make code. The special codes 0xF6 through 0xFF are reserved for use as follows: + +=================== ==================================================== + Code Command +=================== ==================================================== 0xF6 status report 0xF7 absolute mouse position record 0xF8-0xFB relative mouse position records (lsbs determined by - mouse button states) + mouse button states) 0xFC time-of-day 0xFD joystick report (both sticks) 0xFE joystick 0 event 0xFF joystick 1 event +=================== ==================================================== The two shift keys return different scan codes in this mode. The ENTER key and the RETurn key are also distinct. -4. Mouse +Mouse +===== The mouse port should be capable of supporting a mouse with resolution of approximately 200 counts (phase changes or 'clicks') per inch of travel. The @@ -53,7 +63,8 @@ key equivalents. The mouse buttons can be treated as part of the mouse or as additional keyboard keys. -4.1 Relative Position Reporting +Relative Position Reporting +--------------------------- In relative position mode, the ikbd will return relative mouse position records whenever a mouse event occurs. A mouse event consists of a mouse @@ -67,7 +78,8 @@ been 'paused' ( the event will be stored until keyboard communications is resumed) (b) while any event is being transmitted. The relative mouse position record is a three byte record of the form -(regardless of keyboard mode): +(regardless of keyboard mode):: + %111110xy ; mouse position record flag ; where y is the right button state ; and x is the left button state @@ -81,13 +93,15 @@ If the accumulated motion before the report packet is generated exceeds the Note that the sign of the delta y reported is a function of the Y origin selected. -4.2 Absolute Position reporting +Absolute Position reporting +--------------------------- The ikbd can also maintain absolute mouse position. Commands exist for resetting the mouse position, setting X/Y scaling, and interrogating the current mouse position. -4.3 Mouse Cursor Key Mode +Mouse Cursor Key Mode +--------------------- The ikbd can translate mouse motion into the equivalent cursor keystrokes. The number of mouse clicks per keystroke is independently programmable in @@ -99,32 +113,38 @@ break code for the appropriate cursor key. The mouse buttons produce scan codes above those normally assigned for the largest envisioned keyboard (i.e. LEFT=0x74 & RIGHT=0x75). -5. Joystick +Joystick +======== -5.1 Joystick Event Reporting +Joystick Event Reporting +------------------------ In this mode, the ikbd generates a record whenever the joystick position is changed (i.e. for each opening or closing of a joystick switch or trigger). -The joystick event record is two bytes of the form: +The joystick event record is two bytes of the form:: + %1111111x ; Joystick event marker ; where x is Joystick 0 or 1 %x000yyyy ; where yyyy is the stick position ; and x is the trigger -5.2 Joystick Interrogation +Joystick Interrogation +---------------------- The current state of the joystick ports may be interrogated at any time in this mode by sending an 'Interrogate Joystick' command to the ikbd. -The ikbd response to joystick interrogation is a three byte report of the form +The ikbd response to joystick interrogation is a three byte report of the form:: + 0xFD ; joystick report header %x000yyyy ; Joystick 0 %x000yyyy ; Joystick 1 ; where x is the trigger ; and yyy is the stick position -5.3 Joystick Monitoring +Joystick Monitoring +------------------- A mode is available that devotes nearly all of the keyboard communications time to reporting the state of the joystick ports at a user specifiable rate. @@ -132,7 +152,8 @@ It remains in this mode until reset or commanded into another mode. The PAUSE command in this mode not only stop the output but also temporarily stops scanning the joysticks (samples are not queued). -5.4 Fire Button Monitoring +Fire Button Monitoring +---------------------- A mode is provided to permit monitoring a single input bit at a high rate. In this mode the ikbd monitors the state of the Joystick 1 fire button at the @@ -142,7 +163,8 @@ until reset or commanded into another mode. The PAUSE command in this mode not only stops the output but also temporarily stops scanning the button (samples are not queued). -5.5 Joystick Key Code Mode +Joystick Key Code Mode +---------------------- The ikbd may be commanded to translate the use of either joystick into the equivalent cursor control keystroke(s). The ikbd provides a single breakpoint @@ -152,18 +174,21 @@ for the appropriate cursor motion keys. The trigger or fire buttons of the joysticks produce pseudo key scan codes above those used by the largest key matrix envisioned (i.e. JOYSTICK0=0x74, JOYSTICK1=0x75). -6. Time-of-Day Clock +Time-of-Day Clock +================= The ikbd also maintains a time-of-day clock for the system. Commands are available to set and interrogate the timer-of-day clock. Time-keeping is maintained down to a resolution of one second. -7. Status Inquiries +Status Inquiries +================ The current state of ikbd modes and parameters may be found by sending status inquiry commands that correspond to the ikbd set commands. -8. Power-Up Mode +Power-Up Mode +============= The keyboard controller will perform a simple self-test on power-up to detect major controller faults (ROM checksum and RAM test) and such things as stuck @@ -183,13 +208,17 @@ both buttons are logically connected to it. If a mouse disable command is received while port 0 is presumed to be a mouse, the button is logically assigned to Joystick1 (until the mouse is reenabled by another mouse command). -9. ikbd Command Set +ikbd Command Set +================ This section contains a list of commands that can be sent to the ikbd. Command codes (such as 0x00) which are not specified should perform no operation (NOPs). -9.1 RESET +RESET +----- + +:: 0x80 0x01 @@ -208,7 +237,10 @@ ikbd will then scan the key matrix for any stuck (closed) keys. Any keys found closed will cause the break scan code to be generated (the break code arriving without being preceded by the make code is a flag for a key matrix error). -9.2. SET MOUSE BUTTON ACTION +SET MOUSE BUTTON ACTION +----------------------- + +:: 0x07 %00000mss ; mouse button action @@ -217,14 +249,17 @@ without being preceded by the make code is a flag for a key matrix error). ; position report ; where y=1, mouse key press causes absolute report ; and x=1, mouse key release causes absolute report - ; mss=100, mouse buttons act like keys + ; mss=100, mouse buttons act like keys This command sets how the ikbd should treat the buttons on the mouse. The default mouse button action mode is %00000000, the buttons are treated as part of the mouse logically. When buttons act like keys, LEFT=0x74 & RIGHT=0x75. -9.3 SET RELATIVE MOUSE POSITION REPORTING +SET RELATIVE MOUSE POSITION REPORTING +------------------------------------- + +:: 0x08 @@ -235,14 +270,17 @@ key mode, mouse position reports may also be generated when either mouse button is pressed or released. Otherwise the mouse buttons behave as if they were keyboard keys. -9.4 SET ABSOLUTE MOUSE POSITIONING +SET ABSOLUTE MOUSE POSITIONING +------------------------------ + +:: 0x09 XMSB ; X maximum (in scaled mouse clicks) XLSB YMSB ; Y maximum (in scaled mouse clicks) YLSB - + Set absolute mouse position maintenance. Resets the ikbd maintained X and Y coordinates. In this mode, the value of the internally maintained coordinates does NOT wrap @@ -250,7 +288,10 @@ between 0 and large positive numbers. Excess motion below 0 is ignored. The command sets the maximum positive value that can be attained in the scaled coordinate system. Motion beyond that value is also ignored. -9.5 SET MOUSE KEYCODE MOSE +SET MOUSE KEYCODE MOSE +---------------------- + +:: 0x0A deltax ; distance in X clicks to return (LEFT) or (RIGHT) @@ -263,7 +304,10 @@ either axis. When the keyboard is in key scan code mode, mouse motion will cause the make code immediately followed by the break code. Note that this command is not affected by the mouse motion origin. -9..6 SET MOUSE THRESHOLD +SET MOUSE THRESHOLD +------------------- + +:: 0x0B X ; x threshold in mouse ticks (positive integers) @@ -274,7 +318,10 @@ it does NOT affect the resolution of the data returned to the host. This command is valid only in RELATIVE MOUSE POSITIONING mode. The thresholds default to 1 at RESET (or power-up). -9.7 SET MOUSE SCALE +SET MOUSE SCALE +--------------- + +:: 0x0C X ; horizontal mouse ticks per internal X @@ -288,7 +335,10 @@ information is available only by interrogating the ikbd in the ABSOLUTE MOUSE POSITIONING mode unless the ikbd has been commanded to report on button press or release (see SET MOSE BUTTON ACTION). -9.8 INTERROGATE MOUSE POSITION +INTERROGATE MOUSE POSITION +-------------------------- + +:: 0x0D Returns: @@ -306,7 +356,10 @@ or release (see SET MOSE BUTTON ACTION). The INTERROGATE MOUSE POSITION command is valid when in the ABSOLUTE MOUSE POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION. -9.9 LOAD MOUSE POSITION +LOAD MOUSE POSITION +------------------- + +:: 0x0E 0x00 ; filler @@ -318,7 +371,10 @@ POSITIONING mode, regardless of the setting of the MOUSE BUTTON ACTION. This command allows the user to preset the internally maintained absolute mouse position. -9.10 SET Y=0 AT BOTTOM +SET Y=0 AT BOTTOM +----------------- + +:: 0x0F @@ -327,7 +383,10 @@ logical coordinate system internal to the ikbd for all relative or absolute mouse motion. This causes mouse motion toward the user to be negative in sign and away from the user to be positive. -9.11 SET Y=0 AT TOP +SET Y=0 AT TOP +-------------- + +:: 0x10 @@ -336,7 +395,10 @@ system within the ikbd for all relative or absolute mouse motion. (DEFAULT) This causes mouse motion toward the user to be positive in sign and away from the user to be negative. -9.12 RESUME +RESUME +------ + +:: 0x11 @@ -345,7 +407,10 @@ its output has been paused also causes an implicit RESUME this command can be thought of as a NO OPERATION command. If this command is received by the ikbd and it is not PAUSED, it is simply ignored. -9.13 DISABLE MOUSE +DISABLE MOUSE +------------- + +:: 0x12 @@ -356,7 +421,10 @@ ABSOLUTE MOUSE POSITIONING, and SET MOUSE KEYCODE MODE. ) N.B. If the mouse buttons have been commanded to act like keyboard keys, this command DOES affect their actions. -9.14 PAUSE OUTPUT +PAUSE OUTPUT +------------ + +:: 0x13 @@ -381,21 +449,30 @@ When the ikbd is in either the JOYSTICK MONITORING mode or the FIRE BUTTON MONITORING mode, the PAUSE OUTPUT command also temporarily stops the monitoring process (i.e. the samples are not enqueued for transmission). -0.15 SET JOYSTICK EVENT REPORTING +SET JOYSTICK EVENT REPORTING +---------------------------- + +:: 0x14 Enter JOYSTICK EVENT REPORTING mode (DEFAULT). Each opening or closure of a joystick switch or trigger causes a joystick event record to be generated. -9.16 SET JOYSTICK INTERROGATION MODE +SET JOYSTICK INTERROGATION MODE +------------------------------- + +:: 0x15 Disables JOYSTICK EVENT REPORTING. Host must send individual JOYSTICK INTERROGATE commands to sense joystick state. -9.17 JOYSTICK INTERROGATE +JOYSTICK INTERROGATE +-------------------- + +:: 0x16 @@ -403,7 +480,10 @@ Return a record indicating the current state of the joysticks. This command is valid in either the JOYSTICK EVENT REPORTING mode or the JOYSTICK INTERROGATION MODE. -9.18 SET JOYSTICK MONITORING +SET JOYSTICK MONITORING +----------------------- + +:: 0x17 rate ; time between samples in hundredths of a second @@ -419,7 +499,10 @@ between joystick samples. N.B. The user should not set the rate higher than the serial communications channel will allow the 2 bytes packets to be transmitted. -9.19 SET FIRE BUTTON MONITORING +SET FIRE BUTTON MONITORING +-------------------------- + +:: 0x18 Returns: (as long as in mode) @@ -432,7 +515,10 @@ is scanned at a rate that causes 8 samples to be made in the time it takes for the previous byte to be sent to the host (i.e. scan rate = 8/10 * baud rate). The sample interval should be as constant as possible. -9.20 SET JOYSTICK KEYCODE MODE +SET JOYSTICK KEYCODE MODE +------------------------- + +:: 0x19 RX ; length of time (in tenths of seconds) until @@ -462,7 +548,10 @@ Note that by setting RX and/or Ry to zero, the velocity feature can be disabled. The values of TX and TY then become meaningless, and the generation of cursor 'keystrokes' is set by VX and VY. -9.21 DISABLE JOYSTICKS +DISABLE JOYSTICKS +----------------- + +:: 0x1A @@ -472,7 +561,10 @@ joystick mode commands are SET JOYSTICK EVENT REPORTING, SET JOYSTICK INTERROGATION MODE, SET JOYSTICK MONITORING, SET FIRE BUTTON MONITORING, and SET JOYSTICK KEYCODE MODE.) -9.22 TIME-OF-DAY CLOCK SET +TIME-OF-DAY CLOCK SET +--------------------- + +:: 0x1B YY ; year (2 least significant digits) @@ -487,7 +579,10 @@ Any digit that is not a valid BCD digit should be treated as a 'don't care' and not alter that particular field of the date or time. This permits setting only some subfields of the time-of-day clock. -9.23 INTERROGATE TIME-OF-DAT CLOCK +INTERROGATE TIME-OF-DAT CLOCK +----------------------------- + +:: 0x1C Returns: @@ -501,7 +596,10 @@ only some subfields of the time-of-day clock. All time-of-day is sent in packed BCD format. -9.24 MEMORY LOAD +MEMORY LOAD +----------- + +:: 0x20 ADRMSB ; address in controller @@ -512,7 +610,10 @@ only some subfields of the time-of-day clock. This command permits the host to load arbitrary values into the ikbd controller memory. The time between data bytes must be less than 20ms. -9.25 MEMORY READ +MEMORY READ +----------- + +:: 0x21 ADRMSB ; address in controller @@ -524,7 +625,10 @@ controller memory. The time between data bytes must be less than 20ms. This command permits the host to read from the ikbd controller memory. -9.26 CONTROLLER EXECUTE +CONTROLLER EXECUTE +------------------ + +:: 0x22 ADRMSB ; address of subroutine in @@ -533,8 +637,11 @@ This command permits the host to read from the ikbd controller memory. This command allows the host to command the execution of a subroutine in the ikbd controller memory. -9.27 STATUS INQUIRIES - +STATUS INQUIRIES +---------------- + +:: + Status commands are formed by inclusively ORing 0x80 with the relevant SET command. @@ -568,7 +675,7 @@ off the status report header byte) and later send them back as commands to ikbd to restore its state. The 0 pad bytes will be treated as NOPs by the ikbd. - Valid STATUS INQUIRY commands are: + Valid STATUS INQUIRY commands are:: 0x87 mouse button action 0x88 mouse mode @@ -595,14 +702,17 @@ STATUS INQUIRY commands are not valid if the ikbd is in JOYSTICK MONITORING mode or FIRE BUTTON MONITORING mode. -10. SCAN CODES +SCAN CODES +========== The key scan codes returned by the ikbd are chosen to simplify the implementation of GSX. -GSX Standard Keyboard Mapping. +GSX Standard Keyboard Mapping +======= ============ Hex Keytop +======= ============ 01 Esc 02 1 03 2 @@ -614,8 +724,8 @@ Hex Keytop 09 8 0A 9 0B 0 -0C - -0D == +0C \- +0D \= 0E BS 0F TAB 10 Q @@ -643,9 +753,9 @@ Hex Keytop 26 L 27 ; 28 ' -29 ` +29 \` 2A (LEFT) SHIFT -2B \ +2B \\ 2C Z 2D X 2E C @@ -707,3 +817,4 @@ Hex Keytop 70 KEYPAD 0 71 KEYPAD . 72 KEYPAD ENTER +======= ============ diff --git a/Documentation/input/bcm5974.txt b/Documentation/input/devices/bcm5974.rst index 74d3876d6f34..4aca199b0aa6 100644 --- a/Documentation/input/bcm5974.txt +++ b/Documentation/input/devices/bcm5974.rst @@ -1,19 +1,25 @@ +.. include:: <isonum.txt> + +------------------------ BCM5974 Driver (bcm5974) ------------------------ - Copyright (C) 2008-2009 Henrik Rydberg <rydberg@euromail.se> + +:Copyright: |copy| 2008-2009 Henrik Rydberg <rydberg@euromail.se> The USB initialization and package decoding was made by Scott Shawcroft as part of the touchd user-space driver project: - Copyright (C) 2008 Scott Shawcroft (scott.shawcroft@gmail.com) + +:Copyright: |copy| 2008 Scott Shawcroft (scott.shawcroft@gmail.com) The BCM5974 driver is based on the appletouch driver: - Copyright (C) 2001-2004 Greg Kroah-Hartman (greg@kroah.com) - Copyright (C) 2005 Johannes Berg (johannes@sipsolutions.net) - Copyright (C) 2005 Stelian Pop (stelian@popies.net) - Copyright (C) 2005 Frank Arnold (frank@scirocco-5v-turbo.de) - Copyright (C) 2005 Peter Osterlund (petero2@telia.com) - Copyright (C) 2005 Michael Hanselmann (linux-kernel@hansmi.ch) - Copyright (C) 2006 Nicolas Boichat (nicolas@boichat.ch) + +:Copyright: |copy| 2001-2004 Greg Kroah-Hartman (greg@kroah.com) +:Copyright: |copy| 2005 Johannes Berg (johannes@sipsolutions.net) +:Copyright: |copy| 2005 Stelian Pop (stelian@popies.net) +:Copyright: |copy| 2005 Frank Arnold (frank@scirocco-5v-turbo.de) +:Copyright: |copy| 2005 Peter Osterlund (petero2@telia.com) +:Copyright: |copy| 2005 Michael Hanselmann (linux-kernel@hansmi.ch) +:Copyright: |copy| 2006 Nicolas Boichat (nicolas@boichat.ch) This driver adds support for the multi-touch trackpad on the new Apple Macbook Air and Macbook Pro laptops. It replaces the appletouch driver on @@ -44,22 +50,21 @@ Debug output To ease the development for new hardware version, verbose packet output can be switched on with the debug kernel module parameter. The range [1-9] -yields different levels of verbosity. Example (as root): +yields different levels of verbosity. Example (as root):: -echo -n 9 > /sys/module/bcm5974/parameters/debug + echo -n 9 > /sys/module/bcm5974/parameters/debug -tail -f /var/log/debug + tail -f /var/log/debug -echo -n 0 > /sys/module/bcm5974/parameters/debug + echo -n 0 > /sys/module/bcm5974/parameters/debug Trivia ------ -The driver was developed at the ubuntu forums in June 2008 [1], and now has -a more permanent home at bitmath.org [2]. +The driver was developed at the ubuntu forums in June 2008 [#f1]_, and now has +a more permanent home at bitmath.org [#f2]_. -Links ------ +.. Links -[1] http://ubuntuforums.org/showthread.php?t=840040 -[2] http://bitmath.org/code/ +.. [#f1] http://ubuntuforums.org/showthread.php?t=840040 +.. [#f2] http://bitmath.org/code/ diff --git a/Documentation/input/cma3000_d0x.txt b/Documentation/input/devices/cma3000_d0x.rst index 29d088db4afd..8bc8e61487b0 100644 --- a/Documentation/input/cma3000_d0x.txt +++ b/Documentation/input/devices/cma3000_d0x.rst @@ -1,30 +1,37 @@ -Kernel driver for CMA3000-D0x -============================ +CMA3000-D0x Accelerometer +========================= Supported chips: * VTI CMA3000-D0x + Datasheet: CMA3000-D0X Product Family Specification 8281000A.02.pdf <http://www.vti.fi/en/> -Author: Hemanth V <hemanthv@ti.com> +:Author: Hemanth V <hemanthv@ti.com> Description ----------- + CMA3000 Tri-axis accelerometer supports Motion detect, Measurement and Free fall modes. -Motion Detect Mode: Its the low power mode where interrupts are generated only -when motion exceeds the defined thresholds. +Motion Detect Mode: + Its the low power mode where interrupts are generated only + when motion exceeds the defined thresholds. -Measurement Mode: This mode is used to read the acceleration data on X,Y,Z -axis and supports 400, 100, 40 Hz sample frequency. +Measurement Mode: + This mode is used to read the acceleration data on X,Y,Z + axis and supports 400, 100, 40 Hz sample frequency. -Free fall Mode: This mode is intended to save system resources. +Free fall Mode: + This mode is intended to save system resources. -Threshold values: Chip supports defining threshold values for above modes -which includes time and g value. Refer product specifications for more details. +Threshold values: + Chip supports defining threshold values for above modes + which includes time and g value. Refer product specifications for + more details. CMA3000 chip supports mutually exclusive I2C and SPI interfaces for communication, currently the driver supports I2C based communication only. @@ -38,28 +45,40 @@ Platform data need to be configured for initial default values. Platform Data ------------- -fuzz_x: Noise on X Axis -fuzz_y: Noise on Y Axis +fuzz_x: + Noise on X Axis -fuzz_z: Noise on Z Axis +fuzz_y: + Noise on Y Axis -g_range: G range in milli g i.e 2000 or 8000 +fuzz_z: + Noise on Z Axis -mode: Default Operating mode +g_range: + G range in milli g i.e 2000 or 8000 -mdthr: Motion detect g range threshold value +mode: + Default Operating mode + +mdthr: + Motion detect g range threshold value -mdfftmr: Motion detect and free fall time threshold value +mdfftmr: + Motion detect and free fall time threshold value -ffthr: Free fall g range threshold value +ffthr: + Free fall g range threshold value Input Interface --------------- +--------------- + Input driver version is 1.0.0 Input device ID: bus 0x18 vendor 0x0 product 0x0 version 0x0 Input device name: "cma3000-accelerometer" -Supported events: + +Supported events:: + Event type 0 (Sync) Event type 3 (Absolute) Event code 0 (X) @@ -87,7 +106,8 @@ Supported events: Register/Platform parameters Description ---------------------------------------- -mode: +mode:: + 0: power down mode 1: 100 Hz Measurement mode 2: 400 Hz Measurement mode @@ -97,19 +117,23 @@ mode: 6: 40 Hz Free fall mode 7: Power off mode -grange: +grange:: + 2000: 2000 mg or 2G Range 8000: 8000 mg or 8G Range -mdthr: +mdthr:: + X: X * 71mg (8G Range) X: X * 18mg (2G Range) -mdfftmr: +mdfftmr:: + X: (X & 0x70) * 100 ms (MDTMR) (X & 0x0F) * 2.5 ms (FFTMR 400 Hz) (X & 0x0F) * 10 ms (FFTMR 100 Hz) -ffthr: +ffthr:: + X: (X >> 2) * 18mg (2G Range) X: (X & 0x0F) * 71 mg (8G Range) diff --git a/Documentation/input/cs461x.txt b/Documentation/input/devices/cs461x.rst index 202e9dbacec3..b1e6d508ad26 100644 --- a/Documentation/input/cs461x.txt +++ b/Documentation/input/devices/cs461x.rst @@ -1,36 +1,34 @@ -Preface. +Crystal SoundFusion CS4610/CS4612/CS461 joystick +================================================ This is a new low-level driver to support analog joystick attached to -Crystal SoundFusion CS4610/CS4612/CS4615. This code is based upon +Crystal SoundFusion CS4610/CS4612/CS4615. This code is based upon Vortex/Solo drivers as an example of decoration style, and ALSA 0.5.8a kernel drivers as an chipset documentation and samples. -This version does not have cooked mode support; the basic code -is present here, but have not tested completely. The button analysis -is completed in this mode, but the axis movement is not. +This version does not have cooked mode support; the basic code +is present here, but have not tested completely. The button analysis +is completed in this mode, but the axis movement is not. Raw mode works fine with analog joystick front-end driver and cs461x -driver as a backend. I've tested this driver with CS4610, 4-axis and +driver as a backend. I've tested this driver with CS4610, 4-axis and 4-button joystick; I mean the jstest utility. Also I've tried to play in xracer game using joystick, and the result is better than keyboard only mode. The sensitivity and calibrate quality have not been tested; the two -reasons are performed: the same hardware cannot work under Win95 (blue -screen in VJOYD); I have no documentation on my chip; and the existing -behavior in my case was not raised the requirement of joystick calibration. +reasons are performed: the same hardware cannot work under Win95 (blue +screen in VJOYD); I have no documentation on my chip; and the existing +behavior in my case was not raised the requirement of joystick calibration. So the driver have no code to perform hardware related calibration. -The patch contains minor changes of Config.in and Makefile files. All -needed code have been moved to one separate file cs461x.c like ns558.c This driver have the basic support for PCI devices only; there is no -ISA or PnP ISA cards supported. AFAIK the ns558 have support for Crystal -ISA and PnP ISA series. +ISA or PnP ISA cards supported. The driver works with ALSA drivers simultaneously. For example, the xracer uses joystick as input device and PCM device as sound output in one time. There are no sound or input collisions detected. The source code have -comments about them; but I've found the joystick can be initialized +comments about them; but I've found the joystick can be initialized separately of ALSA modules. So, you can use only one joystick driver without ALSA drivers. The ALSA drivers are not needed to compile or run this driver. @@ -38,7 +36,7 @@ run this driver. There are no debug information print have been placed in source, and no specific options required to work this driver. The found chipset parameters are printed via printk(KERN_INFO "..."), see the /var/log/messages to -inspect cs461x: prefixed messages to determine possible card detection +inspect cs461x: prefixed messages to determine possible card detection errors. Regards, diff --git a/Documentation/input/edt-ft5x06.txt b/Documentation/input/devices/edt-ft5x06.rst index 2032f0b7a8fa..2032f0b7a8fa 100644 --- a/Documentation/input/edt-ft5x06.txt +++ b/Documentation/input/devices/edt-ft5x06.rst diff --git a/Documentation/input/elantech.txt b/Documentation/input/devices/elantech.rst index 1ec0db7879d3..c3374a7ce7af 100644 --- a/Documentation/input/elantech.txt +++ b/Documentation/input/devices/elantech.rst @@ -10,9 +10,7 @@ Elantech Touchpad Driver received from Woody at Xandros and forwarded to me by user StewieGriffin at the eeeuser.com forum - -Contents -~~~~~~~~ +.. Contents 1. Introduction 2. Extra knobs @@ -45,8 +43,8 @@ Contents -1. Introduction - ~~~~~~~~~~~~ +Introduction +~~~~~~~~~~~~ Currently the Linux Elantech touchpad driver is aware of four different hardware versions unimaginatively called version 1,version 2, version 3 @@ -88,11 +86,8 @@ available Elantech documentation the information is provided here anyway for completeness sake. -///////////////////////////////////////////////////////////////////////////// - - -2. Extra knobs - ~~~~~~~~~~~ +Extra knobs +~~~~~~~~~~~ Currently the Linux Elantech touchpad driver provides three extra knobs under /sys/bus/serio/drivers/psmouse/serio? for the user. @@ -142,18 +137,17 @@ Currently the Linux Elantech touchpad driver provides three extra knobs under Reading the crc_enabled value will show the active value. Echoing "0" or "1" to this file will set the state to "0" or "1". -///////////////////////////////////////////////////////////////////////////// +Differentiating hardware versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -3. Differentiating hardware versions - ================================= - -To detect the hardware version, read the version number as param[0].param[1].param[2] +To detect the hardware version, read the version number as param[0].param[1].param[2]:: 4 bytes version: (after the arrow is the name given in the Dell-provided driver) 02.00.22 => EF013 02.06.00 => EF019 + In the wild, there appear to be more versions, such as 00.01.64, 01.00.21, -02.00.00, 02.00.04, 02.00.06. +02.00.00, 02.00.04, 02.00.06:: 6 bytes: 02.00.30 => EF113 @@ -162,6 +156,7 @@ In the wild, there appear to be more versions, such as 00.01.64, 01.00.21, 02.0B.00 => EF215 04.01.XX => Scroll_EF051 04.02.XX => EF051 + In the wild, there appear to be more versions, such as 04.03.01, 04.04.11. There appears to be almost no difference, except for EF113, which does not report pressure/width and has different data consistency checks. @@ -170,21 +165,20 @@ Probably all the versions with param[0] <= 01 can be considered as 4 bytes/firmware 1. The versions < 02.08.00, with the exception of 02.00.30, as 4 bytes/firmware 2. Everything >= 02.08.00 can be considered as 6 bytes. -///////////////////////////////////////////////////////////////////////////// -4. Hardware version 1 - ================== +Hardware version 1 +~~~~~~~~~~~~~~~~~~ -4.1 Registers - ~~~~~~~~~ +Registers +--------- By echoing a hexadecimal value to a register it contents can be altered. -For example: +For example:: echo -n 0x16 > reg_10 -* reg_10 +* reg_10:: bit 7 6 5 4 3 2 1 0 B C T D L A S E @@ -198,7 +192,7 @@ For example: C: 1 = enable corner tap B: 1 = swap left and right button -* reg_11 +* reg_11:: bit 7 6 5 4 3 2 1 0 1 0 0 H V 1 F P @@ -208,40 +202,41 @@ For example: V: 1 = enable vertical scroll area H: 1 = enable horizontal scroll area -* reg_20 +* reg_20:: single finger width? -* reg_21 +* reg_21:: scroll area width (small: 0x40 ... wide: 0xff) -* reg_22 +* reg_22:: drag lock time out (short: 0x14 ... long: 0xfe; 0xff = tap again to release) -* reg_23 +* reg_23:: tap make timeout? -* reg_24 +* reg_24:: tap release timeout? -* reg_25 +* reg_25:: smart edge cursor speed (0x02 = slow, 0x03 = medium, 0x04 = fast) -* reg_26 +* reg_26:: smart edge activation area width? -4.2 Native relative mode 4 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Native relative mode 4 byte packet format +----------------------------------------- + +byte 0:: -byte 0: bit 7 6 5 4 3 2 1 0 c c p2 p1 1 M R L @@ -251,20 +246,23 @@ byte 0: p1..p2 = byte 1 and 2 odd parity bit c = 1 when corner tap detected -byte 1: +byte 1:: + bit 7 6 5 4 3 2 1 0 dx7 dx6 dx5 dx4 dx3 dx2 dx1 dx0 dx7..dx0 = x movement; positive = right, negative = left byte 1 = 0xf0 when corner tap detected -byte 2: +byte 2:: + bit 7 6 5 4 3 2 1 0 dy7 dy6 dy5 dy4 dy3 dy2 dy1 dy0 dy7..dy0 = y movement; positive = up, negative = down -byte 3: +byte 3:: + parity checking enabled (reg_11, P = 1): bit 7 6 5 4 3 2 1 0 @@ -296,14 +294,15 @@ byte 3: positive = down -4.3 Native absolute mode 4 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Native absolute mode 4 byte packet format +----------------------------------------- EF013 and EF019 have a special behaviour (due to a bug in the firmware?), and when 1 finger is touching, the first 2 position reports must be discarded. This counting is reset whenever a different number of fingers is reported. -byte 0: +byte 0:: + firmware version 1.x: bit 7 6 5 4 3 2 1 0 @@ -322,7 +321,8 @@ byte 0: p1..p3 = byte 1..3 odd parity bit n1..n0 = number of fingers on touchpad -byte 1: +byte 1:: + firmware version 1.x: bit 7 6 5 4 3 2 1 0 @@ -337,65 +337,68 @@ byte 1: bit 7 6 5 4 3 2 1 0 . . . . x9 x8 y9 y8 -byte 2: +byte 2:: + bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x3 x2 x1 x0 x9..x0 = absolute x value (horizontal) -byte 3: +byte 3:: + bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 y9..y0 = absolute y value (vertical) -///////////////////////////////////////////////////////////////////////////// - +Hardware version 2 +~~~~~~~~~~~~~~~~~~ -5. Hardware version 2 - ================== - -5.1 Registers - ~~~~~~~~~ +Registers +--------- By echoing a hexadecimal value to a register it contents can be altered. -For example: +For example:: echo -n 0x56 > reg_10 -* reg_10 +* reg_10:: bit 7 6 5 4 3 2 1 0 0 1 0 1 0 1 D 0 D: 1 = enable drag and drop -* reg_11 +* reg_11:: bit 7 6 5 4 3 2 1 0 1 0 0 0 S 0 1 0 S: 1 = enable vertical scroll -* reg_21 +* reg_21:: unknown (0x00) -* reg_22 +* reg_22:: drag and drop release time out (short: 0x70 ... long 0x7e; 0x7f = never i.e. tap again to release) -5.2 Native absolute mode 6 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -5.2.1 Parity checking and packet re-synchronization +Native absolute mode 6 byte packet format +----------------------------------------- + +Parity checking and packet re-synchronization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + There is no parity checking, however some consistency checks can be performed. -For instance for EF113: +For instance for EF113:: + SA1= packet[0]; A1 = packet[1]; B1 = packet[2]; @@ -410,7 +413,8 @@ For instance for EF113: (((SA1 & 0xC0) != 0x80) && (( C1 & 0xF0) != 0x00)) ) // check Byte 5 // error detected -For all the other ones, there are just a few constant bits: +For all the other ones, there are just a few constant bits:: + if( ((packet[0] & 0x0C) != 0x04) || ((packet[3] & 0x0f) != 0x02) ) // error detected @@ -418,10 +422,10 @@ For all the other ones, there are just a few constant bits: In case an error is detected, all the packets are shifted by one (and packet[0] is discarded). -5.2.2 One/Three finger touch - ~~~~~~~~~~~~~~~~ +One/Three finger touch +^^^^^^^^^^^^^^^^^^^^^^ -byte 0: +byte 0:: bit 7 6 5 4 3 2 1 0 n1 n0 w3 w2 . . R L @@ -429,19 +433,19 @@ byte 0: L, R = 1 when Left, Right mouse button pressed n1..n0 = number of fingers on touchpad -byte 1: +byte 1:: bit 7 6 5 4 3 2 1 0 p7 p6 p5 p4 x11 x10 x9 x8 -byte 2: +byte 2:: bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x3 x2 x1 x0 x11..x0 = absolute x value (horizontal) -byte 3: +byte 3:: bit 7 6 5 4 3 2 1 0 n4 vf w1 w0 . . . b2 @@ -460,14 +464,14 @@ byte 3: 6 = Another one 7 = Another one -byte 4: +byte 4:: bit 7 6 5 4 3 2 1 0 p3 p1 p2 p0 y11 y10 y9 y8 p7..p0 = pressure (not EF113) -byte 5: +byte 5:: bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 @@ -475,15 +479,15 @@ byte 5: y11..y0 = absolute y value (vertical) -5.2.3 Two finger touch - ~~~~~~~~~~~~~~~~ +Two finger touch +^^^^^^^^^^^^^^^^ Note that the two pairs of coordinates are not exactly the coordinates of the two fingers, but only the pair of the lower-left and upper-right coordinates. So the actual fingers might be situated on the other diagonal of the square defined by these two points. -byte 0: +byte 0:: bit 7 6 5 4 3 2 1 0 n1 n0 ay8 ax8 . . R L @@ -491,47 +495,46 @@ byte 0: L, R = 1 when Left, Right mouse button pressed n1..n0 = number of fingers on touchpad -byte 1: +byte 1:: bit 7 6 5 4 3 2 1 0 ax7 ax6 ax5 ax4 ax3 ax2 ax1 ax0 ax8..ax0 = lower-left finger absolute x value -byte 2: +byte 2:: bit 7 6 5 4 3 2 1 0 ay7 ay6 ay5 ay4 ay3 ay2 ay1 ay0 ay8..ay0 = lower-left finger absolute y value -byte 3: +byte 3:: bit 7 6 5 4 3 2 1 0 . . by8 bx8 . . . . -byte 4: +byte 4:: bit 7 6 5 4 3 2 1 0 bx7 bx6 bx5 bx4 bx3 bx2 bx1 bx0 bx8..bx0 = upper-right finger absolute x value -byte 5: +byte 5:: bit 7 6 5 4 3 2 1 0 by7 by8 by5 by4 by3 by2 by1 by0 by8..by0 = upper-right finger absolute y value -///////////////////////////////////////////////////////////////////////////// +Hardware version 3 +~~~~~~~~~~~~~~~~~~ -6. Hardware version 3 - ================== +Registers +--------- -6.1 Registers - ~~~~~~~~~ -* reg_10 +* reg_10:: bit 7 6 5 4 3 2 1 0 0 0 0 0 R F T A @@ -541,8 +544,9 @@ byte 5: F: 1 = disable ABS Position Filter R: 1 = enable real hardware resolution -6.2 Native absolute mode 6 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Native absolute mode 6 byte packet format +----------------------------------------- + 1 and 3 finger touch shares the same 6-byte packet format, except that 3 finger touch only reports the position of the center of all three fingers. @@ -552,19 +556,21 @@ Note on debounce: In case the box has unstable power supply or other electricity issues, or when number of finger changes, F/W would send "debounce packet" to inform driver that the hardware is in debounce status. -The debouce packet has the following signature: +The debouce packet has the following signature:: + byte 0: 0xc4 byte 1: 0xff byte 2: 0xff byte 3: 0x02 byte 4: 0xff byte 5: 0xff + When we encounter this kind of packet, we just ignore it. -6.2.1 One/Three finger touch - ~~~~~~~~~~~~~~~~~~~~~~ +One/Three finger touch +^^^^^^^^^^^^^^^^^^^^^^ -byte 0: +byte 0:: bit 7 6 5 4 3 2 1 0 n1 n0 w3 w2 0 1 R L @@ -572,63 +578,63 @@ byte 0: L, R = 1 when Left, Right mouse button pressed n1..n0 = number of fingers on touchpad -byte 1: +byte 1:: bit 7 6 5 4 3 2 1 0 p7 p6 p5 p4 x11 x10 x9 x8 -byte 2: +byte 2:: bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x3 x2 x1 x0 x11..x0 = absolute x value (horizontal) -byte 3: +byte 3:: bit 7 6 5 4 3 2 1 0 0 0 w1 w0 0 0 1 0 w3..w0 = width of the finger touch -byte 4: +byte 4:: bit 7 6 5 4 3 2 1 0 p3 p1 p2 p0 y11 y10 y9 y8 p7..p0 = pressure -byte 5: +byte 5:: bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 y11..y0 = absolute y value (vertical) -6.2.2 Two finger touch - ~~~~~~~~~~~~~~~~ +Two finger touch +^^^^^^^^^^^^^^^^ The packet format is exactly the same for two finger touch, except the hardware sends two 6 byte packets. The first packet contains data for the first finger, the second packet has data for the second finger. So for two finger touch a total of 12 bytes are sent. -///////////////////////////////////////////////////////////////////////////// +Hardware version 4 +~~~~~~~~~~~~~~~~~~ -7. Hardware version 4 - ================== +Registers +--------- -7.1 Registers - ~~~~~~~~~ -* reg_07 +* reg_07:: bit 7 6 5 4 3 2 1 0 0 0 0 0 0 0 0 A A: 1 = enable absolute tracking -7.2 Native absolute mode 6 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Native absolute mode 6 byte packet format +----------------------------------------- + v4 hardware is a true multitouch touchpad, capable of tracking up to 5 fingers. Unfortunately, due to PS/2's limited bandwidth, its packet format is rather complex. @@ -647,45 +653,49 @@ position, until we receive a status packet. One exception is one finger touch. when a status packet tells us there is only one finger, the hardware would just send head packets afterwards. -7.2.1 Status packet - ~~~~~~~~~~~~~ +Status packet +^^^^^^^^^^^^^ -byte 0: +byte 0:: bit 7 6 5 4 3 2 1 0 . . . . 0 1 R L L, R = 1 when Left, Right mouse button pressed -byte 1: +byte 1:: bit 7 6 5 4 3 2 1 0 . . . ft4 ft3 ft2 ft1 ft0 ft4 ft3 ft2 ft1 ft0 ftn = 1 when finger n is on touchpad -byte 2: not used +byte 2:: + + not used -byte 3: +byte 3:: bit 7 6 5 4 3 2 1 0 . . . 1 0 0 0 0 constant bits -byte 4: +byte 4:: bit 7 6 5 4 3 2 1 0 p . . . . . . . p = 1 for palm -byte 5: not used +byte 5:: -7.2.2 Head packet - ~~~~~~~~~~~ + not used -byte 0: +Head packet +^^^^^^^^^^^ + +byte 0:: bit 7 6 5 4 3 2 1 0 w3 w2 w1 w0 0 1 R L @@ -693,43 +703,43 @@ byte 0: L, R = 1 when Left, Right mouse button pressed w3..w0 = finger width (spans how many trace lines) -byte 1: +byte 1:: bit 7 6 5 4 3 2 1 0 p7 p6 p5 p4 x11 x10 x9 x8 -byte 2: +byte 2:: bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x3 x2 x1 x0 x11..x0 = absolute x value (horizontal) -byte 3: +byte 3:: bit 7 6 5 4 3 2 1 0 id2 id1 id0 1 0 0 0 1 id2..id0 = finger id -byte 4: +byte 4:: bit 7 6 5 4 3 2 1 0 p3 p1 p2 p0 y11 y10 y9 y8 p7..p0 = pressure -byte 5: +byte 5:: bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 y11..y0 = absolute y value (vertical) -7.2.3 Motion packet - ~~~~~~~~~~~~~ +Motion packet +^^^^^^^^^^^^^ -byte 0: +byte 0:: bit 7 6 5 4 3 2 1 0 id2 id1 id0 w 0 1 R L @@ -739,35 +749,35 @@ byte 0: w = 1 when delta overflows (> 127 or < -128), in this case firmware sends us (delta x / 5) and (delta y / 5) -byte 1: +byte 1:: bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x3 x2 x1 x0 x7..x0 = delta x (two's complement) -byte 2: +byte 2:: bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 y7..y0 = delta y (two's complement) -byte 3: +byte 3:: bit 7 6 5 4 3 2 1 0 id2 id1 id0 1 0 0 1 0 id2..id0 = finger id -byte 4: +byte 4:: bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x3 x2 x1 x0 x7..x0 = delta x (two's complement) -byte 5: +byte 5:: bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 @@ -778,33 +788,47 @@ byte 5: byte 3 ~ 5 for another -8. Trackpoint (for Hardware version 3 and 4) - ========================================= -8.1 Registers - ~~~~~~~~~ +Trackpoint (for Hardware version 3 and 4) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Registers +--------- + No special registers have been identified. -8.2 Native relative mode 6 byte packet format - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -8.2.1 Status Packet - ~~~~~~~~~~~~~ +Native relative mode 6 byte packet format +----------------------------------------- + +Status Packet +^^^^^^^^^^^^^ + +byte 0:: -byte 0: bit 7 6 5 4 3 2 1 0 0 0 sx sy 0 M R L -byte 1: + +byte 1:: + bit 7 6 5 4 3 2 1 0 ~sx 0 0 0 0 0 0 0 -byte 2: + +byte 2:: + bit 7 6 5 4 3 2 1 0 ~sy 0 0 0 0 0 0 0 -byte 3: + +byte 3:: + bit 7 6 5 4 3 2 1 0 0 0 ~sy ~sx 0 1 1 0 -byte 4: + +byte 4:: + bit 7 6 5 4 3 2 1 0 x7 x6 x5 x4 x3 x2 x1 x0 -byte 5: + +byte 5:: + bit 7 6 5 4 3 2 1 0 y7 y6 y5 y4 y3 y2 y1 y0 diff --git a/Documentation/input/devices/gpio-tilt.rst b/Documentation/input/devices/gpio-tilt.rst new file mode 100644 index 000000000000..fa6e64570aa7 --- /dev/null +++ b/Documentation/input/devices/gpio-tilt.rst @@ -0,0 +1,103 @@ +Driver for tilt-switches connected via GPIOs +============================================ + +Generic driver to read data from tilt switches connected via gpios. +Orientation can be provided by one or more than one tilt switches, +i.e. each tilt switch providing one axis, and the number of axes +is also not limited. + + +Data structures +--------------- + +The array of struct gpio in the gpios field is used to list the gpios +that represent the current tilt state. + +The array of struct gpio_tilt_axis describes the axes that are reported +to the input system. The values set therein are used for the +input_set_abs_params calls needed to init the axes. + +The array of struct gpio_tilt_state maps gpio states to the corresponding +values to report. The gpio state is represented as a bitfield where the +bit-index corresponds to the index of the gpio in the struct gpio array. +In the same manner the values stored in the axes array correspond to +the elements of the gpio_tilt_axis-array. + + +Example +------- + +Example configuration for a single TS1003 tilt switch that rotates around +one axis in 4 steps and emits the current tilt via two GPIOs:: + + static int sg060_tilt_enable(struct device *dev) { + /* code to enable the sensors */ + }; + + static void sg060_tilt_disable(struct device *dev) { + /* code to disable the sensors */ + }; + + static struct gpio sg060_tilt_gpios[] = { + { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" }, + { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" }, + }; + + static struct gpio_tilt_state sg060_tilt_states[] = { + { + .gpios = (0 << 1) | (0 << 0), + .axes = (int[]) { + 0, + }, + }, { + .gpios = (0 << 1) | (1 << 0), + .axes = (int[]) { + 1, /* 90 degrees */ + }, + }, { + .gpios = (1 << 1) | (1 << 0), + .axes = (int[]) { + 2, /* 180 degrees */ + }, + }, { + .gpios = (1 << 1) | (0 << 0), + .axes = (int[]) { + 3, /* 270 degrees */ + }, + }, + }; + + static struct gpio_tilt_axis sg060_tilt_axes[] = { + { + .axis = ABS_RY, + .min = 0, + .max = 3, + .fuzz = 0, + .flat = 0, + }, + }; + + static struct gpio_tilt_platform_data sg060_tilt_pdata= { + .gpios = sg060_tilt_gpios, + .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios), + + .axes = sg060_tilt_axes, + .nr_axes = ARRAY_SIZE(sg060_tilt_axes), + + .states = sg060_tilt_states, + .nr_states = ARRAY_SIZE(sg060_tilt_states), + + .debounce_interval = 100, + + .poll_interval = 1000, + .enable = sg060_tilt_enable, + .disable = sg060_tilt_disable, + }; + + static struct platform_device sg060_device_tilt = { + .name = "gpio-tilt-polled", + .id = -1, + .dev = { + .platform_data = &sg060_tilt_pdata, + }, + }; diff --git a/Documentation/input/devices/iforce-protocol.rst b/Documentation/input/devices/iforce-protocol.rst new file mode 100644 index 000000000000..8634beac3fdb --- /dev/null +++ b/Documentation/input/devices/iforce-protocol.rst @@ -0,0 +1,381 @@ +=============== +Iforce Protocol +=============== + +:Author: Johann Deneux <johann.deneux@gmail.com> + +Home page at `<http://web.archive.org/web/*/http://www.esil.univ-mrs.fr>`_ + +:Additions: by Vojtech Pavlik. + + +Introduction +============ + +This document describes what I managed to discover about the protocol used to +specify force effects to I-Force 2.0 devices. None of this information comes +from Immerse. That's why you should not trust what is written in this +document. This document is intended to help understanding the protocol. +This is not a reference. Comments and corrections are welcome. To contact me, +send an email to: johann.deneux@gmail.com + +.. warning:: + + I shall not be held responsible for any damage or harm caused if you try to + send data to your I-Force device based on what you read in this document. + +Preliminary Notes +================= + +All values are hexadecimal with big-endian encoding (msb on the left). Beware, +values inside packets are encoded using little-endian. Bytes whose roles are +unknown are marked ??? Information that needs deeper inspection is marked (?) + +General form of a packet +------------------------ + +This is how packets look when the device uses the rs232 to communicate. + +== == === ==== == +2B OP LEN DATA CS +== == === ==== == + +CS is the checksum. It is equal to the exclusive or of all bytes. + +When using USB: + +== ==== +OP DATA +== ==== + +The 2B, LEN and CS fields have disappeared, probably because USB handles +frames and data corruption is handled or unsignificant. + +First, I describe effects that are sent by the device to the computer + +Device input state +================== + +This packet is used to indicate the state of each button and the value of each +axis:: + + OP= 01 for a joystick, 03 for a wheel + LEN= Varies from device to device + 00 X-Axis lsb + 01 X-Axis msb + 02 Y-Axis lsb, or gas pedal for a wheel + 03 Y-Axis msb, or brake pedal for a wheel + 04 Throttle + 05 Buttons + 06 Lower 4 bits: Buttons + Upper 4 bits: Hat + 07 Rudder + +Device effects states +===================== + +:: + + OP= 02 + LEN= Varies + 00 ? Bit 1 (Value 2) is the value of the deadman switch + 01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id. + 02 ?? + 03 Address of parameter block changed (lsb) + 04 Address of parameter block changed (msb) + 05 Address of second parameter block changed (lsb) + ... depending on the number of parameter blocks updated + +Force effect +------------ + +:: + + OP= 01 + LEN= 0e + 00 Channel (when playing several effects at the same time, each must + be assigned a channel) + 01 Wave form + Val 00 Constant + Val 20 Square + Val 21 Triangle + Val 22 Sine + Val 23 Sawtooth up + Val 24 Sawtooth down + Val 40 Spring (Force = f(pos)) + Val 41 Friction (Force = f(velocity)) and Inertia + (Force = f(acceleration)) + + + 02 Axes affected and trigger + Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction + Val 4 = X axis only. Byte 05 must contain 5a + Val 8 = Y axis only. Byte 05 must contain b4 + Val c = X and Y axes. Bytes 05 must contain 60 + Bits 0-3: Val 0 = No trigger + Val x+1 = Button x triggers the effect + When the whole byte is 0, cancel the previously set trigger + + 03-04 Duration of effect (little endian encoding, in ms) + + 05 Direction of effect, if applicable. Else, see 02 for value to assign. + + 06-07 Minimum time between triggering. + + 08-09 Address of periodicity or magnitude parameters + 0a-0b Address of attack and fade parameters, or ffff if none. + *or* + 08-09 Address of interactive parameters for X-axis, + or ffff if not applicable + 0a-0b Address of interactive parameters for Y-axis, + or ffff if not applicable + + 0c-0d Delay before execution of effect (little endian encoding, in ms) + + +Time based parameters +--------------------- + +Attack and fade +^^^^^^^^^^^^^^^ + +:: + + OP= 02 + LEN= 08 + 00-01 Address where to store the parameters + 02-03 Duration of attack (little endian encoding, in ms) + 04 Level at end of attack. Signed byte. + 05-06 Duration of fade. + 07 Level at end of fade. + +Magnitude +^^^^^^^^^ + +:: + + OP= 03 + LEN= 03 + 00-01 Address + 02 Level. Signed byte. + +Periodicity +^^^^^^^^^^^ + +:: + + OP= 04 + LEN= 07 + 00-01 Address + 02 Magnitude. Signed byte. + 03 Offset. Signed byte. + 04 Phase. Val 00 = 0 deg, Val 40 = 90 degs. + 05-06 Period (little endian encoding, in ms) + +Interactive parameters +---------------------- + +:: + + OP= 05 + LEN= 0a + 00-01 Address + 02 Positive Coeff + 03 Negative Coeff + 04+05 Offset (center) + 06+07 Dead band (Val 01F4 = 5000 (decimal)) + 08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal)) + 09 Negative saturation + +The encoding is a bit funny here: For coeffs, these are signed values. The +maximum value is 64 (100 decimal), the min is 9c. +For the offset, the minimum value is FE0C, the maximum value is 01F4. +For the deadband, the minimum value is 0, the max is 03E8. + +Controls +-------- + +:: + + OP= 41 + LEN= 03 + 00 Channel + 01 Start/Stop + Val 00: Stop + Val 01: Start and play once. + Val 41: Start and play n times (See byte 02 below) + 02 Number of iterations n. + +Init +---- + + +Querying features +^^^^^^^^^^^^^^^^^ +:: + + OP= ff + Query command. Length varies according to the query type. + The general format of this packet is: + ff 01 QUERY [INDEX] CHECKSUM + responses are of the same form: + FF LEN QUERY VALUE_QUERIED CHECKSUM2 + where LEN = 1 + length(VALUE_QUERIED) + +Query ram size +~~~~~~~~~~~~~~ + +:: + + QUERY = 42 ('B'uffer size) + +The device should reply with the same packet plus two additional bytes +containing the size of the memory: +ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available. + +Query number of effects +~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + QUERY = 4e ('N'umber of effects) + +The device should respond by sending the number of effects that can be played +at the same time (one byte) +ff 02 4e 14 CS would stand for 20 effects. + +Vendor's id +~~~~~~~~~~~ + +:: + + QUERY = 4d ('M'anufacturer) + +Query the vendors'id (2 bytes) + +Product id +~~~~~~~~~~ + +:: + + QUERY = 50 ('P'roduct) + +Query the product id (2 bytes) + +Open device +~~~~~~~~~~~ + +:: + + QUERY = 4f ('O'pen) + +No data returned. + +Close device +~~~~~~~~~~~~ + +:: + + QUERY = 43 ('C')lose + +No data returned. + +Query effect +~~~~~~~~~~~~ + +:: + + QUERY = 45 ('E') + +Send effect type. +Returns nonzero if supported (2 bytes) + +Firmware Version +~~~~~~~~~~~~~~~~ + +:: + + QUERY = 56 ('V'ersion) + +Sends back 3 bytes - major, minor, subminor + +Initialisation of the device +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set Control +~~~~~~~~~~~ + +.. note:: + Device dependent, can be different on different models! + +:: + + OP= 40 <idx> <val> [<val>] + LEN= 2 or 3 + 00 Idx + Idx 00 Set dead zone (0..2048) + Idx 01 Ignore Deadman sensor (0..1) + Idx 02 Enable comm watchdog (0..1) + Idx 03 Set the strength of the spring (0..100) + Idx 04 Enable or disable the spring (0/1) + Idx 05 Set axis saturation threshold (0..2048) + +Set Effect State +~~~~~~~~~~~~~~~~ + +:: + + OP= 42 <val> + LEN= 1 + 00 State + Bit 3 Pause force feedback + Bit 2 Enable force feedback + Bit 0 Stop all effects + +Set overall +~~~~~~~~~~~ + +:: + + OP= 43 <val> + LEN= 1 + 00 Gain + Val 00 = 0% + Val 40 = 50% + Val 80 = 100% + +Parameter memory +---------------- + +Each device has a certain amount of memory to store parameters of effects. +The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below +is the amount of memory apparently needed for every set of parameters: + + - period : 0c + - magnitude : 02 + - attack and fade : 0e + - interactive : 08 + +Appendix: How to study the protocol? +==================================== + +1. Generate effects using the force editor provided with the DirectX SDK, or +use Immersion Studio (freely available at their web site in the developer section: +www.immersion.com) +2. Start a soft spying RS232 or USB (depending on where you connected your +joystick/wheel). I used ComPortSpy from fCoder (alpha version!) +3. Play the effect, and watch what happens on the spy screen. + +A few words about ComPortSpy: +At first glance, this software seems, hum, well... buggy. In fact, data appear with a +few seconds latency. Personally, I restart it every time I play an effect. +Remember it's free (as in free beer) and alpha! + +URLS +==== + +Check http://www.immerse.com for Immersion Studio, +and http://www.fcoder.com for ComPortSpy. + + +I-Force is trademark of Immersion Corp. diff --git a/Documentation/input/devices/index.rst b/Documentation/input/devices/index.rst new file mode 100644 index 000000000000..95a453782bad --- /dev/null +++ b/Documentation/input/devices/index.rst @@ -0,0 +1,19 @@ +Driver-specific documentation +============================= + +This section provides information about various devices supported by the +Linux kernel, their protocols, and driver details. + +.. toctree:: + :maxdepth: 2 + :numbered: + :glob: + + * + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/input/devices/joystick-parport.rst b/Documentation/input/devices/joystick-parport.rst new file mode 100644 index 000000000000..e8ce16ee799a --- /dev/null +++ b/Documentation/input/devices/joystick-parport.rst @@ -0,0 +1,611 @@ +.. include:: <isonum.txt> + +.. _joystick-parport: + +============================== +Parallel Port Joystick Drivers +============================== + +:Copyright: |copy| 1998-2000 Vojtech Pavlik <vojtech@ucw.cz> +:Copyright: |copy| 1998 Andree Borrmann <a.borrmann@tu-bs.de> + + +Sponsored by SuSE + +Disclaimer +========== + +Any information in this file is provided as-is, without any guarantee that +it will be true. So, use it at your own risk. The possible damages that can +happen include burning your parallel port, and/or the sticks and joystick +and maybe even more. Like when a lightning kills you it is not our problem. + +Introduction +============ + +The joystick parport drivers are used for joysticks and gamepads not +originally designed for PCs and other computers Linux runs on. Because of +that, PCs usually lack the right ports to connect these devices to. Parallel +port, because of its ability to change single bits at will, and providing +both output and input bits is the most suitable port on the PC for +connecting such devices. + +Devices supported +================= + +Many console and 8-bit computer gamepads and joysticks are supported. The +following subsections discuss usage of each. + +NES and SNES +------------ + +The Nintendo Entertainment System and Super Nintendo Entertainment System +gamepads are widely available, and easy to get. Also, they are quite easy to +connect to a PC, and don't need much processing speed (108 us for NES and +165 us for SNES, compared to about 1000 us for PC gamepads) to communicate +with them. + +All NES and SNES use the same synchronous serial protocol, clocked from +the computer's side (and thus timing insensitive). To allow up to 5 NES +and/or SNES gamepads and/or SNES mice connected to the parallel port at once, +the output lines of the parallel port are shared, while one of 5 available +input lines is assigned to each gamepad. + +This protocol is handled by the gamecon.c driver, so that's the one +you'll use for NES, SNES gamepads and SNES mice. + +The main problem with PC parallel ports is that they don't have +5V power +source on any of their pins. So, if you want a reliable source of power +for your pads, use either keyboard or joystick port, and make a pass-through +cable. You can also pull the power directly from the power supply (the red +wire is +5V). + +If you want to use the parallel port only, you can take the power is from +some data pin. For most gamepad and parport implementations only one pin is +needed, and I'd recommend pin 9 for that, the highest data bit. On the other +hand, if you are not planning to use anything else than NES / SNES on the +port, anything between and including pin 4 and pin 9 will work:: + + (pin 9) -----> Power + +Unfortunately, there are pads that need a lot more of power, and parallel +ports that can't give much current through the data pins. If this is your +case, you'll need to use diodes (as a prevention of destroying your parallel +port), and combine the currents of two or more data bits together:: + + Diodes + (pin 9) ----|>|-------+------> Power + | + (pin 8) ----|>|-------+ + | + (pin 7) ----|>|-------+ + | + <and so on> : + | + (pin 4) ----|>|-------+ + +Ground is quite easy. On PC's parallel port the ground is on any of the +pins from pin 18 to pin 25. So use any pin of these you like for the ground:: + + (pin 18) -----> Ground + +NES and SNES pads have two input bits, Clock and Latch, which drive the +serial transfer. These are connected to pins 2 and 3 of the parallel port, +respectively:: + + (pin 2) -----> Clock + (pin 3) -----> Latch + +And the last thing is the NES / SNES data wire. Only that isn't shared and +each pad needs its own data pin. The parallel port pins are:: + + (pin 10) -----> Pad 1 data + (pin 11) -----> Pad 2 data + (pin 12) -----> Pad 3 data + (pin 13) -----> Pad 4 data + (pin 15) -----> Pad 5 data + +Note that pin 14 is not used, since it is not an input pin on the parallel +port. + +This is everything you need on the PC's side of the connection, now on to +the gamepads side. The NES and SNES have different connectors. Also, there +are quite a lot of NES clones, and because Nintendo used proprietary +connectors for their machines, the cloners couldn't and used standard D-Cannon +connectors. Anyway, if you've got a gamepad, and it has buttons A, B, Turbo +A, Turbo B, Select and Start, and is connected through 5 wires, then it is +either a NES or NES clone and will work with this connection. SNES gamepads +also use 5 wires, but have more buttons. They will work as well, of course:: + + Pinout for NES gamepads Pinout for SNES gamepads and mice + + +----> Power +-----------------------\ + | 7 | o o o o | x x o | 1 + 5 +---------+ 7 +-----------------------/ + | x x o \ | | | | | + | o o o o | | | | | +-> Ground + 4 +------------+ 1 | | | +------------> Data + | | | | | | +---------------> Latch + | | | +-> Ground | +------------------> Clock + | | +----> Clock +---------------------> Power + | +-------> Latch + +----------> Data + + Pinout for NES clone (db9) gamepads Pinout for NES clone (db15) gamepads + + +---------> Clock +-----------------> Data + | +-------> Latch | +---> Ground + | | +-----> Data | | + | | | ___________________ + _____________ 8 \ o x x x x x x o / 1 + 5 \ x o o o x / 1 \ o x x o x x o / + \ x o x o / 15 `~~~~~~~~~~~~~' 9 + 9 `~~~~~~~' 6 | | | + | | | | +----> Clock + | +----> Power | +----------> Latch + +--------> Ground +----------------> Power + +Multisystem joysticks +--------------------- + +In the era of 8-bit machines, there was something like de-facto standard +for joystick ports. They were all digital, and all used D-Cannon 9 pin +connectors (db9). Because of that, a single joystick could be used without +hassle on Atari (130, 800XE, 800XL, 2600, 7200), Amiga, Commodore C64, +Amstrad CPC, Sinclair ZX Spectrum and many other machines. That's why these +joysticks are called "Multisystem". + +Now their pinout:: + + +---------> Right + | +-------> Left + | | +-----> Down + | | | +---> Up + | | | | + _____________ + 5 \ x o o o o / 1 + \ x o x o / + 9 `~~~~~~~' 6 + | | + | +----> Button + +--------> Ground + +However, as time passed, extensions to this standard developed, and these +were not compatible with each other:: + + + Atari 130, 800/XL/XE MSX + + +-----------> Power + +---------> Right | +---------> Right + | +-------> Left | | +-------> Left + | | +-----> Down | | | +-----> Down + | | | +---> Up | | | | +---> Up + | | | | | | | | | + _____________ _____________ + 5 \ x o o o o / 1 5 \ o o o o o / 1 + \ x o o o / \ o o o o / + 9 `~~~~~~~' 6 9 `~~~~~~~' 6 + | | | | | | | + | | +----> Button | | | +----> Button 1 + | +------> Power | | +------> Button 2 + +--------> Ground | +--------> Output 3 + +----------> Ground + + Amstrad CPC Commodore C64 + + +-----------> Analog Y + +---------> Right | +---------> Right + | +-------> Left | | +-------> Left + | | +-----> Down | | | +-----> Down + | | | +---> Up | | | | +---> Up + | | | | | | | | | + _____________ _____________ + 5 \ x o o o o / 1 5 \ o o o o o / 1 + \ x o o o / \ o o o o / + 9 `~~~~~~~' 6 9 `~~~~~~~' 6 + | | | | | | | + | | +----> Button 1 | | | +----> Button + | +------> Button 2 | | +------> Power + +--------> Ground | +--------> Ground + +----------> Analog X + + Sinclair Spectrum +2A/+3 Amiga 1200 + + +-----------> Up +-----------> Button 3 + | +---------> Fire | +---------> Right + | | | | +-------> Left + | | +-----> Ground | | | +-----> Down + | | | | | | | +---> Up + | | | | | | | | + _____________ _____________ + 5 \ o o x o x / 1 5 \ o o o o o / 1 + \ o o o o / \ o o o o / + 9 `~~~~~~~' 6 9 `~~~~~~~' 6 + | | | | | | | | + | | | +----> Right | | | +----> Button 1 + | | +------> Left | | +------> Power + | +--------> Ground | +--------> Ground + +----------> Down +----------> Button 2 + + And there were many others. + +Multisystem joysticks using db9.c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For the Multisystem joysticks, and their derivatives, the db9.c driver +was written. It allows only one joystick / gamepad per parallel port, but +the interface is easy to build and works with almost anything. + +For the basic 1-button Multisystem joystick you connect its wires to the +parallel port like this:: + + (pin 1) -----> Power + (pin 18) -----> Ground + + (pin 2) -----> Up + (pin 3) -----> Down + (pin 4) -----> Left + (pin 5) -----> Right + (pin 6) -----> Button 1 + +However, if the joystick is switch based (eg. clicks when you move it), +you might or might not, depending on your parallel port, need 10 kOhm pullup +resistors on each of the direction and button signals, like this:: + + (pin 2) ------------+------> Up + Resistor | + (pin 1) --[10kOhm]--+ + +Try without, and if it doesn't work, add them. For TTL based joysticks / +gamepads the pullups are not needed. + +For joysticks with two buttons you connect the second button to pin 7 on +the parallel port:: + + (pin 7) -----> Button 2 + +And that's it. + +On a side note, if you have already built a different adapter for use with +the digital joystick driver 0.8.0.2, this is also supported by the db9.c +driver, as device type 8. (See section 3.2) + +Multisystem joysticks using gamecon.c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For some people just one joystick per parallel port is not enough, and/or +want to use them on one parallel port together with NES/SNES/PSX pads. This is +possible using the gamecon.c. It supports up to 5 devices of the above types, +including 1 and 2 buttons Multisystem joysticks. + +However, there is nothing for free. To allow more sticks to be used at +once, you need the sticks to be purely switch based (that is non-TTL), and +not to need power. Just a plain simple six switches inside. If your +joystick can do more (eg. turbofire) you'll need to disable it totally first +if you want to use gamecon.c. + +Also, the connection is a bit more complex. You'll need a bunch of diodes, +and one pullup resistor. First, you connect the Directions and the button +the same as for db9, however with the diodes between:: + + Diodes + (pin 2) -----|<|----> Up + (pin 3) -----|<|----> Down + (pin 4) -----|<|----> Left + (pin 5) -----|<|----> Right + (pin 6) -----|<|----> Button 1 + +For two button sticks you also connect the other button:: + + (pin 7) -----|<|----> Button 2 + +And finally, you connect the Ground wire of the joystick, like done in +this little schematic to Power and Data on the parallel port, as described +for the NES / SNES pads in section 2.1 of this file - that is, one data pin +for each joystick. The power source is shared:: + + Data ------------+-----> Ground + Resistor | + Power --[10kOhm]--+ + +And that's all, here we go! + +Multisystem joysticks using turbografx.c +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The TurboGraFX interface, designed by + + Steffen Schwenke <schwenke@burg-halle.de> + +allows up to 7 Multisystem joysticks connected to the parallel port. In +Steffen's version, there is support for up to 5 buttons per joystick. However, +since this doesn't work reliably on all parallel ports, the turbografx.c driver +supports only one button per joystick. For more information on how to build the +interface, see: + + http://www2.burg-halle.de/~schwenke/parport.html + +Sony Playstation +---------------- + +The PSX controller is supported by the gamecon.c. Pinout of the PSX +controller (compatible with DirectPadPro):: + + +---------+---------+---------+ + 9 | o o o | o o o | o o o | 1 parallel + \________|_________|________/ port pins + | | | | | | + | | | | | +--------> Clock --- (4) + | | | | +------------> Select --- (3) + | | | +---------------> Power --- (5-9) + | | +------------------> Ground --- (18-25) + | +-------------------------> Command --- (2) + +----------------------------> Data --- (one of 10,11,12,13,15) + +The driver supports these controllers: + + * Standard PSX Pad + * NegCon PSX Pad + * Analog PSX Pad (red mode) + * Analog PSX Pad (green mode) + * PSX Rumble Pad + * PSX DDR Pad + +Sega +---- + +All the Sega controllers are more or less based on the standard 2-button +Multisystem joystick. However, since they don't use switches and use TTL +logic, the only driver usable with them is the db9.c driver. + +Sega Master System +~~~~~~~~~~~~~~~~~~ + +The SMS gamepads are almost exactly the same as normal 2-button +Multisystem joysticks. Set the driver to Multi2 mode, use the corresponding +parallel port pins, and the following schematic:: + + +-----------> Power + | +---------> Right + | | +-------> Left + | | | +-----> Down + | | | | +---> Up + | | | | | + _____________ + 5 \ o o o o o / 1 + \ o o x o / + 9 `~~~~~~~' 6 + | | | + | | +----> Button 1 + | +--------> Ground + +----------> Button 2 + +Sega Genesis aka MegaDrive +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension +to the Sega Master System pads. They use more buttons (3+1, 5+1, 6+1). Use +the following schematic:: + + +-----------> Power + | +---------> Right + | | +-------> Left + | | | +-----> Down + | | | | +---> Up + | | | | | + _____________ + 5 \ o o o o o / 1 + \ o o o o / + 9 `~~~~~~~' 6 + | | | | + | | | +----> Button 1 + | | +------> Select + | +--------> Ground + +----------> Button 2 + +The Select pin goes to pin 14 on the parallel port:: + + (pin 14) -----> Select + +The rest is the same as for Multi2 joysticks using db9.c + +Sega Saturn +~~~~~~~~~~~ + +Sega Saturn has eight buttons, and to transfer that, without hacks like +Genesis 6 pads use, it needs one more select pin. Anyway, it is still +handled by the db9.c driver. Its pinout is very different from anything +else. Use this schematic:: + + +-----------> Select 1 + | +---------> Power + | | +-------> Up + | | | +-----> Down + | | | | +---> Ground + | | | | | + _____________ + 5 \ o o o o o / 1 + \ o o o o / + 9 `~~~~~~~' 6 + | | | | + | | | +----> Select 2 + | | +------> Right + | +--------> Left + +----------> Power + +Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the +parallel port:: + + (pin 14) -----> Select 1 + (pin 16) -----> Select 2 + +The other pins (Up, Down, Right, Left, Power, Ground) are the same as for +Multi joysticks using db9.c + +Amiga CD32 +---------- + +Amiga CD32 joypad uses the following pinout:: + + +-----------> Button 3 + | +---------> Right + | | +-------> Left + | | | +-----> Down + | | | | +---> Up + | | | | | + _____________ + 5 \ o o o o o / 1 + \ o o o o / + 9 `~~~~~~~' 6 + | | | | + | | | +----> Button 1 + | | +------> Power + | +--------> Ground + +----------> Button 2 + +It can be connected to the parallel port and driven by db9.c driver. It needs the following wiring: + + ============ ============= + CD32 pad Parallel port + ============ ============= + 1 (Up) 2 (D0) + 2 (Down) 3 (D1) + 3 (Left) 4 (D2) + 4 (Right) 5 (D3) + 5 (Button 3) 14 (AUTOFD) + 6 (Button 1) 17 (SELIN) + 7 (+5V) 1 (STROBE) + 8 (Gnd) 18 (Gnd) + 9 (Button 2) 7 (D5) + ============ ============= + +The drivers +=========== + +There are three drivers for the parallel port interfaces. Each, as +described above, allows to connect a different group of joysticks and pads. +Here are described their command lines: + +gamecon.c +--------- + +Using gamecon.c you can connect up to five devices to one parallel port. It +uses the following kernel/module command line:: + + gamecon.map=port,pad1,pad2,pad3,pad4,pad5 + +Where ``port`` the number of the parport interface (eg. 0 for parport0). + +And ``pad1`` to ``pad5`` are pad types connected to different data input pins +(10,11,12,13,15), as described in section 2.1 of this file. + +The types are: + + ===== ============================= + Type Joystick/Pad + ===== ============================= + 0 None + 1 SNES pad + 2 NES pad + 4 Multisystem 1-button joystick + 5 Multisystem 2-button joystick + 6 N64 pad + 7 Sony PSX controller + 8 Sony PSX DDR controller + 9 SNES mouse + ===== ============================= + +The exact type of the PSX controller type is autoprobed when used, so +hot swapping should work (but is not recommended). + +Should you want to use more than one of parallel ports at once, you can use +gamecon.map2 and gamecon.map3 as additional command line parameters for two +more parallel ports. + +There are two options specific to PSX driver portion. gamecon.psx_delay sets +the command delay when talking to the controllers. The default of 25 should +work but you can try lowering it for better performance. If your pads don't +respond try raising it until they work. Setting the type to 8 allows the +driver to be used with Dance Dance Revolution or similar games. Arrow keys are +registered as key presses instead of X and Y axes. + +db9.c +----- + +Apart from making an interface, there is nothing difficult on using the +db9.c driver. It uses the following kernel/module command line:: + + db9.dev=port,type + +Where ``port`` is the number of the parport interface (eg. 0 for parport0). + +Caveat here: This driver only works on bidirectional parallel ports. If +your parallel port is recent enough, you should have no trouble with this. +Old parallel ports may not have this feature. + +``Type`` is the type of joystick or pad attached: + + ===== ====================================================== + Type Joystick/Pad + ===== ====================================================== + 0 None + 1 Multisystem 1-button joystick + 2 Multisystem 2-button joystick + 3 Genesis pad (3+1 buttons) + 5 Genesis pad (5+1 buttons) + 6 Genesis pad (6+2 buttons) + 7 Saturn pad (8 buttons) + 8 Multisystem 1-button joystick (v0.8.0.2 pin-out) + 9 Two Multisystem 1-button joysticks (v0.8.0.2 pin-out) + 10 Amiga CD32 pad + ===== ====================================================== + +Should you want to use more than one of these joysticks/pads at once, you +can use db9.dev2 and db9.dev3 as additional command line parameters for two +more joysticks/pads. + +turbografx.c +------------ + +The turbografx.c driver uses a very simple kernel/module command line:: + + turbografx.map=port,js1,js2,js3,js4,js5,js6,js7 + +Where ``port`` is the number of the parport interface (eg. 0 for parport0). + +``jsX`` is the number of buttons the Multisystem joysticks connected to the +interface ports 1-7 have. For a standard multisystem joystick, this is 1. + +Should you want to use more than one of these interfaces at once, you can +use turbografx.map2 and turbografx.map3 as additional command line parameters +for two more interfaces. + +PC parallel port pinout +======================= + +:: + + .----------------------------------------. + At the PC: \ 13 12 11 10 9 8 7 6 5 4 3 2 1 / + \ 25 24 23 22 21 20 19 18 17 16 15 14 / + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +====== ======= ============= + Pin Name Description +====== ======= ============= + 1 /STROBE Strobe + 2-9 D0-D7 Data Bit 0-7 + 10 /ACK Acknowledge + 11 BUSY Busy + 12 PE Paper End + 13 SELIN Select In + 14 /AUTOFD Autofeed + 15 /ERROR Error + 16 /INIT Initialize + 17 /SEL Select + 18-25 GND Signal Ground +====== ======= ============= + + +That's all, folks! Have fun! diff --git a/Documentation/input/ntrig.txt b/Documentation/input/devices/ntrig.rst index be1fd981f73f..a6b22ce6c61c 100644 --- a/Documentation/input/ntrig.txt +++ b/Documentation/input/devices/ntrig.rst @@ -1,7 +1,11 @@ +.. include:: <isonum.txt> + +========================= N-Trig touchscreen Driver -------------------------- - Copyright (c) 2008-2010 Rafi Rubin <rafi@seas.upenn.edu> - Copyright (c) 2009-2010 Stephane Chatty +========================= + +:Copyright: |copy| 2008-2010 Rafi Rubin <rafi@seas.upenn.edu> +:Copyright: |copy| 2009-2010 Stephane Chatty This driver provides support for N-Trig pen and multi-touch sensors. Single and multi-touch events are translated to the appropriate protocols for @@ -22,16 +26,18 @@ but only for that one device. The following parameters are used to configure filters to reduce noise: -activate_slack number of fingers to ignore before processing events - -activation_height size threshold to activate immediately -activation_width - -min_height size threshold bellow which fingers are ignored -min_width both to decide activation and during activity - -deactivate_slack the number of "no contact" frames to ignore before - propagating the end of activity events ++-----------------------+-----------------------------------------------------+ +|activate_slack |number of fingers to ignore before processing events | ++-----------------------+-----------------------------------------------------+ +|activation_height, |size threshold to activate immediately | +|activation_width | | ++-----------------------+-----------------------------------------------------+ +|min_height, |size threshold bellow which fingers are ignored | +|min_width |both to decide activation and during activity | ++-----------------------+-----------------------------------------------------+ +|deactivate_slack |the number of "no contact" frames to ignore before | +| |propagating the end of activity events | ++-----------------------+-----------------------------------------------------+ When the last finger is removed from the device, it sends a number of empty frames. By holding off on deactivation for a few frames we can tolerate false @@ -44,15 +50,20 @@ Additional sysfs items ---------------------- These nodes just provide easy access to the ranges reported by the device. -sensor_logical_height the range for positions reported during activity -sensor_logical_width -sensor_physical_height internal ranges not used for normal events but -sensor_physical_width useful for tuning ++-----------------------+-----------------------------------------------------+ +|sensor_logical_height, | the range for positions reported during activity | +|sensor_logical_width | | ++-----------------------+-----------------------------------------------------+ +|sensor_physical_height,| internal ranges not used for normal events but | +|sensor_physical_width | useful for tuning | ++-----------------------+-----------------------------------------------------+ All N-Trig devices with product id of 1 report events in the ranges of -X: 0-9600 -Y: 0-7200 + +* X: 0-9600 +* Y: 0-7200 + However not all of these devices have the same physical dimensions. Most seem to be 12" sensors (Dell Latitude XT and XT2 and the HP TX2), and at least one model (Dell Studio 17) has a 17" sensor. The ratio of physical diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/devices/rotary-encoder.rst index 46a74f0c551a..b07b20a295ac 100644 --- a/Documentation/input/rotary-encoder.txt +++ b/Documentation/input/devices/rotary-encoder.rst @@ -1,8 +1,11 @@ +============================================================ rotary-encoder - a generic driver for GPIO connected devices -Daniel Mack <daniel@caiaq.de>, Feb 2009 +============================================================ -0. Function ------------ +:Author: Daniel Mack <daniel@caiaq.de>, Feb 2009 + +Function +-------- Rotary encoders are devices which are connected to the CPU or other peripherals with two wires. The outputs are phase-shifted by 90 degrees @@ -13,7 +16,7 @@ Some encoders have both outputs low in stable states, others also have a stable state with both outputs high (half-period mode) and some have a stable state in all steps (quarter-period mode). -The phase diagram of these two outputs look like this: +The phase diagram of these two outputs look like this:: _____ _____ _____ | | | | | | @@ -40,8 +43,8 @@ For more information, please see https://en.wikipedia.org/wiki/Rotary_encoder -1. Events / state machine -------------------------- +Events / state machine +---------------------- In half-period mode, state a) and c) above are used to determine the rotational direction based on the last stable state. Events are reported in @@ -65,62 +68,64 @@ d) Falling edge on channel B, channel A in low state should have happened, unless it flipped back on half the way. The 'armed' state tells us about that. -2. Platform requirements ------------------------- +Platform requirements +--------------------- As there is no hardware dependent call in this driver, the platform it is used with must support gpiolib. Another requirement is that IRQs must be able to fire on both edges. -3. Board integration --------------------- +Board integration +----------------- To use this driver in your system, register a platform_device with the name 'rotary-encoder' and associate the IRQs and some specific platform -data with it. - -struct rotary_encoder_platform_data is declared in -include/linux/rotary-encoder.h and needs to be filled with the number of -steps the encoder has and can carry information about externally inverted -signals (because of an inverting buffer or other reasons). The encoder -can be set up to deliver input information as either an absolute or relative -axes. For relative axes the input event returns +/-1 for each step. For -absolute axes the position of the encoder can either roll over between zero -and the number of steps or will clamp at the maximum and zero depending on -the configuration. - -Because GPIO to IRQ mapping is platform specific, this information must -be given in separately to the driver. See the example below. - ----------<snip>--------- - -/* board support file example */ - -#include <linux/input.h> -#include <linux/rotary_encoder.h> - -#define GPIO_ROTARY_A 1 -#define GPIO_ROTARY_B 2 - -static struct rotary_encoder_platform_data my_rotary_encoder_info = { - .steps = 24, - .axis = ABS_X, - .relative_axis = false, - .rollover = false, - .gpio_a = GPIO_ROTARY_A, - .gpio_b = GPIO_ROTARY_B, - .inverted_a = 0, - .inverted_b = 0, - .half_period = false, - .wakeup_source = false, -}; - -static struct platform_device rotary_encoder_device = { - .name = "rotary-encoder", - .id = 0, - .dev = { - .platform_data = &my_rotary_encoder_info, - } -}; - +data with it. Because the driver uses generic device properties, this can +be done either via device tree, ACPI, or using static board files, like in +example below: + +:: + + /* board support file example */ + + #include <linux/input.h> + #include <linux/gpio/machine.h> + #include <linux/property.h> + + #define GPIO_ROTARY_A 1 + #define GPIO_ROTARY_B 2 + + static struct gpiod_lookup_table rotary_encoder_gpios = { + .dev_id = "rotary-encoder.0", + .table = { + GPIO_LOOKUP_IDX("gpio-0", + GPIO_ROTARY_A, NULL, 0, GPIO_ACTIVE_LOW), + GPIO_LOOKUP_IDX("gpio-0", + GPIO_ROTARY_B, NULL, 1, GPIO_ACTIVE_HIGH), + { }, + }, + }; + + static const struct property_entry rotary_encoder_properties[] __initconst = { + PROPERTY_ENTRY_INTEGER("rotary-encoder,steps-per-period", u32, 24), + PROPERTY_ENTRY_INTEGER("linux,axis", u32, ABS_X), + PROPERTY_ENTRY_INTEGER("rotary-encoder,relative_axis", u32, 0), + { }, + }; + + static struct platform_device rotary_encoder_device = { + .name = "rotary-encoder", + .id = 0, + }; + + ... + + gpiod_add_lookup_table(&rotary_encoder_gpios); + device_add_properties(&rotary_encoder_device, rotary_encoder_properties); + platform_device_register(&rotary_encoder_device); + + ... + +Please consult device tree binding documentation to see all properties +supported by the driver. diff --git a/Documentation/input/devices/sentelic.rst b/Documentation/input/devices/sentelic.rst new file mode 100644 index 000000000000..d7ad603dd77e --- /dev/null +++ b/Documentation/input/devices/sentelic.rst @@ -0,0 +1,901 @@ +.. include:: <isonum.txt> + +================= +Sentelic Touchpad +================= + + +:Copyright: |copy| 2002-2011 Sentelic Corporation. + +:Last update: Dec-07-2011 + +Finger Sensing Pad Intellimouse Mode (scrolling wheel, 4th and 5th buttons) +============================================================================ + +A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward + page (5th button) + +1. Set sample rate to 200; +2. Set sample rate to 200; +3. Set sample rate to 80; +4. Issuing the "Get device ID" command (0xF2) and waits for the response; +5. FSP will respond 0x04. + +:: + + Packet 1 + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|W|W|W|W| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7 => Y overflow + Bit6 => X overflow + Bit5 => Y sign bit + Bit4 => X sign bit + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: X Movement(9-bit 2's complement integers) + Byte 3: Y Movement(9-bit 2's complement integers) + Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report. + valid values, -8 ~ +7 + Bit4 => 1 = 4th mouse button is pressed, Forward one page. + 0 = 4th mouse button is not pressed. + Bit5 => 1 = 5th mouse button is pressed, Backward one page. + 0 = 5th mouse button is not pressed. + +B) MSID 6: Horizontal and Vertical scrolling + +- Set bit 1 in register 0x40 to 1 + +FSP replaces scrolling wheel's movement as 4 bits to show horizontal and +vertical scrolling. + +:: + + Packet 1 + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|r|l|u|d| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7 => Y overflow + Bit6 => X overflow + Bit5 => Y sign bit + Bit4 => X sign bit + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: X Movement(9-bit 2's complement integers) + Byte 3: Y Movement(9-bit 2's complement integers) + Byte 4: Bit0 => the Vertical scrolling movement downward. + Bit1 => the Vertical scrolling movement upward. + Bit2 => the Horizontal scrolling movement leftward. + Bit3 => the Horizontal scrolling movement rightward. + Bit4 => 1 = 4th mouse button is pressed, Forward one page. + 0 = 4th mouse button is not pressed. + Bit5 => 1 = 5th mouse button is pressed, Backward one page. + 0 = 5th mouse button is not pressed. + +C) MSID 7 + +FSP uses 2 packets (8 Bytes) to represent Absolute Position. +so we have PACKET NUMBER to identify packets. + + If PACKET NUMBER is 0, the packet is Packet 1. + If PACKET NUMBER is 1, the packet is Packet 2. + Please count this number in program. + +MSID6 special packet will be enable at the same time when enable MSID 7. + +Absolute position for STL3886-G0 +================================ + +1. Set bit 2 or 3 in register 0x40 to 1 +2. Set bit 6 in register 0x40 to 1 + +:: + + Packet 1 (ABSOLUTE POSITION) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|V|1|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|d|u|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + Bit5 => valid bit + Bit4 => 1 + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: X coordinate (xpos[9:2]) + Byte 3: Y coordinate (ypos[9:2]) + Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit4 => scroll up + Bit5 => scroll down + Bit6 => scroll left + Bit7 => scroll right + + Notify Packet for G0 + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |1|0|0|1|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |M|M|M|M|M|M|M|M| 4 |0|0|0|0|0|0|0|0| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + Bit5 => 0 + Bit4 => 1 + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: Message Type => 0x5A (Enable/Disable status packet) + Mode Type => 0xA5 (Normal/Icon mode status) + Byte 3: Message Type => 0x00 (Disabled) + => 0x01 (Enabled) + Mode Type => 0x00 (Normal) + => 0x01 (Icon) + Byte 4: Bit7~Bit0 => Don't Care + +Absolute position for STL3888-Ax +================================ + +:: + + Packet 1 (ABSOLUTE POSITION) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|V|A|1|L|0|1| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + => 11, Normal data packet with on-pad click + Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. + When both fingers are up, the last two reports have zero valid + bit. + Bit4 => arc + Bit3 => 1 + Bit2 => Left Button, 1 is pressed, 0 is released. + Bit1 => 0 + Bit0 => 1 + Byte 2: X coordinate (xpos[9:2]) + Byte 3: Y coordinate (ypos[9:2]) + Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit5~Bit4 => y1_g + Bit7~Bit6 => x1_g + + Packet 2 (ABSOLUTE POSITION) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|V|A|1|R|1|0| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordinates packet + => 10, Notify packet + => 11, Normal data packet with on-pad click + Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. + When both fingers are up, the last two reports have zero valid + bit. + Bit4 => arc + Bit3 => 1 + Bit2 => Right Button, 1 is pressed, 0 is released. + Bit1 => 1 + Bit0 => 0 + Byte 2: X coordinate (xpos[9:2]) + Byte 3: Y coordinate (ypos[9:2]) + Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit5~Bit4 => y2_g + Bit7~Bit6 => x2_g + + Notify Packet for STL3888-Ax + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|d|u|0|0|0|0| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordinates packet + => 10, Notify packet + => 11, Normal data packet with on-pad click + Bit5 => 1 + Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): + 0: left button is generated by the on-pad command + 1: left button is generated by the external button + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) + Byte 3: Bit7~Bit6 => Don't care + Bit5~Bit4 => Number of fingers + Bit3~Bit1 => Reserved + Bit0 => 1: enter gesture mode; 0: leaving gesture mode + Byte 4: Bit7 => scroll right button + Bit6 => scroll left button + Bit5 => scroll down button + Bit4 => scroll up button + * Note that if gesture and additional button (Bit4~Bit7) + happen at the same time, the button information will not + be sent. + Bit3~Bit0 => Reserved + +Sample sequence of Multi-finger, Multi-coordinate mode: + + notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, + abs pkt 2, ..., notify packet (valid bit == 0) + +Absolute position for STL3888-B0 +================================ + +:: + + Packet 1(ABSOLUTE POSITION) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|V|F|1|0|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordinates packet + => 10, Notify packet + => 11, Normal data packet with on-pad click + Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. + When both fingers are up, the last two reports have zero valid + bit. + Bit4 => finger up/down information. 1: finger down, 0: finger up. + Bit3 => 1 + Bit2 => finger index, 0 is the first finger, 1 is the second finger. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: X coordinate (xpos[9:2]) + Byte 3: Y coordinate (ypos[9:2]) + Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit4 => scroll down button + Bit5 => scroll up button + Bit6 => scroll left button + Bit7 => scroll right button + + Packet 2 (ABSOLUTE POSITION) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|V|F|1|1|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + => 11, Normal data packet with on-pad click + Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. + When both fingers are up, the last two reports have zero valid + bit. + Bit4 => finger up/down information. 1: finger down, 0: finger up. + Bit3 => 1 + Bit2 => finger index, 0 is the first finger, 1 is the second finger. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: X coordinate (xpos[9:2]) + Byte 3: Y coordinate (ypos[9:2]) + Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit4 => scroll down button + Bit5 => scroll up button + Bit6 => scroll left button + Bit7 => scroll right button + +Notify Packet for STL3888-B0:: + + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|u|d|0|0|0|0| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + => 11, Normal data packet with on-pad click + Bit5 => 1 + Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): + 0: left button is generated by the on-pad command + 1: left button is generated by the external button + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) + Byte 3: Bit7~Bit6 => Don't care + Bit5~Bit4 => Number of fingers + Bit3~Bit1 => Reserved + Bit0 => 1: enter gesture mode; 0: leaving gesture mode + Byte 4: Bit7 => scroll right button + Bit6 => scroll left button + Bit5 => scroll up button + Bit4 => scroll down button + * Note that if gesture and additional button(Bit4~Bit7) + happen at the same time, the button information will not + be sent. + Bit3~Bit0 => Reserved + +Sample sequence of Multi-finger, Multi-coordinate mode: + + notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, + abs pkt 2, ..., notify packet (valid bit == 0) + +Absolute position for STL3888-Cx and STL3888-Dx +=============================================== + +:: + + Single Finger, Absolute Coordinate Mode (SFAC) + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|0|P|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|B|F|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordinates packet + => 10, Notify packet + Bit5 => Coordinate mode(always 0 in SFAC mode): + 0: single-finger absolute coordinates (SFAC) mode + 1: multi-finger, multiple coordinates (MFMC) mode + Bit4 => 0: The LEFT button is generated by on-pad command (OPC) + 1: The LEFT button is generated by external button + Default is 1 even if the LEFT button is not pressed. + Bit3 => Always 1, as specified by PS/2 protocol. + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: X coordinate (xpos[9:2]) + Byte 3: Y coordinate (ypos[9:2]) + Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit4 => 4th mouse button(forward one page) + Bit5 => 5th mouse button(backward one page) + Bit6 => scroll left button + Bit7 => scroll right button + + Multi Finger, Multiple Coordinates Mode (MFMC): + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |0|1|1|P|1|F|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|B|F|X|X|Y|Y| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordination packet + => 10, Notify packet + Bit5 => Coordinate mode (always 1 in MFMC mode): + 0: single-finger absolute coordinates (SFAC) mode + 1: multi-finger, multiple coordinates (MFMC) mode + Bit4 => 0: The LEFT button is generated by on-pad command (OPC) + 1: The LEFT button is generated by external button + Default is 1 even if the LEFT button is not pressed. + Bit3 => Always 1, as specified by PS/2 protocol. + Bit2 => Finger index, 0 is the first finger, 1 is the second finger. + If bit 1 and 0 are all 1 and bit 4 is 0, the middle external + button is pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: X coordinate (xpos[9:2]) + Byte 3: Y coordinate (ypos[9:2]) + Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) + Bit3~Bit2 => X coordinate (ypos[1:0]) + Bit4 => 4th mouse button(forward one page) + Bit5 => 5th mouse button(backward one page) + Bit6 => scroll left button + Bit7 => scroll right button + +When one of the two fingers is up, the device will output four consecutive +MFMC#0 report packets with zero X and Y to represent 1st finger is up or +four consecutive MFMC#1 report packets with zero X and Y to represent that +the 2nd finger is up. On the other hand, if both fingers are up, the device +will output four consecutive single-finger, absolute coordinate(SFAC) packets +with zero X and Y. + +Notify Packet for STL3888-Cx/Dx:: + + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |1|0|0|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|u|d|0|0|0|0| + |---------------| |---------------| |---------------| |---------------| + + Byte 1: Bit7~Bit6 => 00, Normal data packet + => 01, Absolute coordinates packet + => 10, Notify packet + Bit5 => Always 0 + Bit4 => 0: The LEFT button is generated by on-pad command(OPC) + 1: The LEFT button is generated by external button + Default is 1 even if the LEFT button is not pressed. + Bit3 => 1 + Bit2 => Middle Button, 1 is pressed, 0 is not pressed. + Bit1 => Right Button, 1 is pressed, 0 is not pressed. + Bit0 => Left Button, 1 is pressed, 0 is not pressed. + Byte 2: Message type: + 0xba => gesture information + 0xc0 => one finger hold-rotating gesture + Byte 3: The first parameter for the received message: + 0xba => gesture ID (refer to the 'Gesture ID' section) + 0xc0 => region ID + Byte 4: The second parameter for the received message: + 0xba => N/A + 0xc0 => finger up/down information + +Sample sequence of Multi-finger, Multi-coordinates mode: + + notify packet (valid bit == 1), MFMC packet 1 (byte 1, bit 2 == 0), + MFMC packet 2 (byte 1, bit 2 == 1), MFMC packet 1, MFMC packet 2, + ..., notify packet (valid bit == 0) + + That is, when the device is in MFMC mode, the host will receive + interleaved absolute coordinate packets for each finger. + +FSP Enable/Disable packet +========================= + +:: + + Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 + BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| + 1 |Y|X|0|0|1|M|R|L| 2 |0|1|0|1|1|0|1|E| 3 | | | | | | | | | 4 | | | | | | | | | + |---------------| |---------------| |---------------| |---------------| + + FSP will send out enable/disable packet when FSP receive PS/2 enable/disable + command. Host will receive the packet which Middle, Right, Left button will + be set. The packet only use byte 0 and byte 1 as a pattern of original packet. + Ignore the other bytes of the packet. + + Byte 1: Bit7 => 0, Y overflow + Bit6 => 0, X overflow + Bit5 => 0, Y sign bit + Bit4 => 0, X sign bit + Bit3 => 1 + Bit2 => 1, Middle Button + Bit1 => 1, Right Button + Bit0 => 1, Left Button + Byte 2: Bit7~1 => (0101101b) + Bit0 => 1 = Enable + 0 = Disable + Byte 3: Don't care + Byte 4: Don't care (MOUSE ID 3, 4) + Byte 5~8: Don't care (Absolute packet) + +PS/2 Command Set +================ + +FSP supports basic PS/2 commanding set and modes, refer to following URL for +details about PS/2 commands: + +http://www.computer-engineering.org/ps2mouse/ + +Programming Sequence for Determining Packet Parsing Flow +======================================================== + +1. Identify FSP by reading device ID(0x00) and version(0x01) register + +2. For FSP version < STL3888 Cx, determine number of buttons by reading + the 'test mode status' (0x20) register:: + + buttons = reg[0x20] & 0x30 + + if buttons == 0x30 or buttons == 0x20: + # two/four buttons + Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' + section A for packet parsing detail(ignore byte 4, bit ~ 7) + elif buttons == 0x10: + # 6 buttons + Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' + section B for packet parsing detail + elif buttons == 0x00: + # 6 buttons + Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' + section A for packet parsing detail + +3. For FSP version >= STL3888 Cx: + Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' + section A for packet parsing detail (ignore byte 4, bit ~ 7) + +Programming Sequence for Register Reading/Writing +================================================= + +Register inversion requirement: + +Following values needed to be inverted(the '~' operator in C) before being +sent to FSP:: + + 0xe8, 0xe9, 0xee, 0xf2, 0xf3 and 0xff. + +Register swapping requirement: + +Following values needed to have their higher 4 bits and lower 4 bits being +swapped before being sent to FSP:: + + 10, 20, 40, 60, 80, 100 and 200. + +Register reading sequence: + + 1. send 0xf3 PS/2 command to FSP; + + 2. send 0x66 PS/2 command to FSP; + + 3. send 0x88 PS/2 command to FSP; + + 4. send 0xf3 PS/2 command to FSP; + + 5. if the register address being to read is not required to be + inverted(refer to the 'Register inversion requirement' section), + goto step 6 + + a. send 0x68 PS/2 command to FSP; + + b. send the inverted register address to FSP and goto step 8; + + 6. if the register address being to read is not required to be + swapped(refer to the 'Register swapping requirement' section), + goto step 7 + + a. send 0xcc PS/2 command to FSP; + + b. send the swapped register address to FSP and goto step 8; + + 7. send 0x66 PS/2 command to FSP; + + a. send the original register address to FSP and goto step 8; + + 8. send 0xe9(status request) PS/2 command to FSP; + + 9. the 4th byte of the response read from FSP should be the + requested register value(?? indicates don't care byte):: + + host: 0xe9 + 3888: 0xfa (??) (??) (val) + + * Note that since the Cx release, the hardware will return 1's + complement of the register value at the 3rd byte of status request + result:: + + host: 0xe9 + 3888: 0xfa (??) (~val) (val) + +Register writing sequence: + + 1. send 0xf3 PS/2 command to FSP; + + 2. if the register address being to write is not required to be + inverted(refer to the 'Register inversion requirement' section), + goto step 3 + + a. send 0x74 PS/2 command to FSP; + + b. send the inverted register address to FSP and goto step 5; + + 3. if the register address being to write is not required to be + swapped(refer to the 'Register swapping requirement' section), + goto step 4 + + a. send 0x77 PS/2 command to FSP; + + b. send the swapped register address to FSP and goto step 5; + + 4. send 0x55 PS/2 command to FSP; + + a. send the register address to FSP and goto step 5; + + 5. send 0xf3 PS/2 command to FSP; + + 6. if the register value being to write is not required to be + inverted(refer to the 'Register inversion requirement' section), + goto step 7 + + a. send 0x47 PS/2 command to FSP; + + b. send the inverted register value to FSP and goto step 9; + + 7. if the register value being to write is not required to be + swapped(refer to the 'Register swapping requirement' section), + goto step 8 + + a. send 0x44 PS/2 command to FSP; + + b. send the swapped register value to FSP and goto step 9; + + 8. send 0x33 PS/2 command to FSP; + + a. send the register value to FSP; + + 9. the register writing sequence is completed. + + * Since the Cx release, the hardware will return 1's + complement of the register value at the 3rd byte of status request + result. Host can optionally send another 0xe9 (status request) PS/2 + command to FSP at the end of register writing to verify that the + register writing operation is successful (?? indicates don't care + byte):: + + host: 0xe9 + 3888: 0xfa (??) (~val) (val) + +Programming Sequence for Page Register Reading/Writing +====================================================== + +In order to overcome the limitation of maximum number of registers +supported, the hardware separates register into different groups called +'pages.' Each page is able to include up to 255 registers. + +The default page after power up is 0x82; therefore, if one has to get +access to register 0x8301, one has to use following sequence to switch +to page 0x83, then start reading/writing from/to offset 0x01 by using +the register read/write sequence described in previous section. + +Page register reading sequence: + + 1. send 0xf3 PS/2 command to FSP; + + 2. send 0x66 PS/2 command to FSP; + + 3. send 0x88 PS/2 command to FSP; + + 4. send 0xf3 PS/2 command to FSP; + + 5. send 0x83 PS/2 command to FSP; + + 6. send 0x88 PS/2 command to FSP; + + 7. send 0xe9(status request) PS/2 command to FSP; + + 8. the response read from FSP should be the requested page value. + + +Page register writing sequence: + + 1. send 0xf3 PS/2 command to FSP; + + 2. send 0x38 PS/2 command to FSP; + + 3. send 0x88 PS/2 command to FSP; + + 4. send 0xf3 PS/2 command to FSP; + + 5. if the page address being written is not required to be + inverted(refer to the 'Register inversion requirement' section), + goto step 6 + + a. send 0x47 PS/2 command to FSP; + + b. send the inverted page address to FSP and goto step 9; + + 6. if the page address being written is not required to be + swapped(refer to the 'Register swapping requirement' section), + goto step 7 + + a. send 0x44 PS/2 command to FSP; + + b. send the swapped page address to FSP and goto step 9; + + 7. send 0x33 PS/2 command to FSP; + + 8. send the page address to FSP; + + 9. the page register writing sequence is completed. + +Gesture ID +========== + +Unlike other devices which sends multiple fingers' coordinates to host, +FSP processes multiple fingers' coordinates internally and convert them +into a 8 bits integer, namely 'Gesture ID.' Following is a list of +supported gesture IDs: + + ======= ================================== + ID Description + ======= ================================== + 0x86 2 finger straight up + 0x82 2 finger straight down + 0x80 2 finger straight right + 0x84 2 finger straight left + 0x8f 2 finger zoom in + 0x8b 2 finger zoom out + 0xc0 2 finger curve, counter clockwise + 0xc4 2 finger curve, clockwise + 0x2e 3 finger straight up + 0x2a 3 finger straight down + 0x28 3 finger straight right + 0x2c 3 finger straight left + 0x38 palm + ======= ================================== + +Register Listing +================ + +Registers are represented in 16 bits values. The higher 8 bits represent +the page address and the lower 8 bits represent the relative offset within +that particular page. Refer to the 'Programming Sequence for Page Register +Reading/Writing' section for instructions on how to change current page +address:: + + offset width default r/w name + 0x8200 bit7~bit0 0x01 RO device ID + + 0x8201 bit7~bit0 RW version ID + 0xc1: STL3888 Ax + 0xd0 ~ 0xd2: STL3888 Bx + 0xe0 ~ 0xe1: STL3888 Cx + 0xe2 ~ 0xe3: STL3888 Dx + + 0x8202 bit7~bit0 0x01 RO vendor ID + + 0x8203 bit7~bit0 0x01 RO product ID + + 0x8204 bit3~bit0 0x01 RW revision ID + + 0x820b test mode status 1 + bit3 1 RO 0: rotate 180 degree + 1: no rotation + *only supported by H/W prior to Cx + + 0x820f register file page control + bit2 0 RW 1: rotate 180 degree + 0: no rotation + *supported since Cx + + bit0 0 RW 1 to enable page 1 register files + *only supported by H/W prior to Cx + + 0x8210 RW system control 1 + bit0 1 RW Reserved, must be 1 + bit1 0 RW Reserved, must be 0 + bit4 0 RW Reserved, must be 0 + bit5 1 RW register clock gating enable + 0: read only, 1: read/write enable + (Note that following registers does not require clock gating being + enabled prior to write: 05 06 07 08 09 0c 0f 10 11 12 16 17 18 23 2e + 40 41 42 43. In addition to that, this bit must be 1 when gesture + mode is enabled) + + 0x8220 test mode status + bit5~bit4 RO number of buttons + 11 => 2, lbtn/rbtn + 10 => 4, lbtn/rbtn/scru/scrd + 01 => 6, lbtn/rbtn/scru/scrd/scrl/scrr + 00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn + *only supported by H/W prior to Cx + + 0x8231 RW on-pad command detection + bit7 0 RW on-pad command left button down tag + enable + 0: disable, 1: enable + *only supported by H/W prior to Cx + + 0x8234 RW on-pad command control 5 + bit4~bit0 0x05 RW XLO in 0s/4/1, so 03h = 0010.1b = 2.5 + (Note that position unit is in 0.5 scanline) + *only supported by H/W prior to Cx + + bit7 0 RW on-pad tap zone enable + 0: disable, 1: enable + *only supported by H/W prior to Cx + + 0x8235 RW on-pad command control 6 + bit4~bit0 0x1d RW XHI in 0s/4/1, so 19h = 1100.1b = 12.5 + (Note that position unit is in 0.5 scanline) + *only supported by H/W prior to Cx + + 0x8236 RW on-pad command control 7 + bit4~bit0 0x04 RW YLO in 0s/4/1, so 03h = 0010.1b = 2.5 + (Note that position unit is in 0.5 scanline) + *only supported by H/W prior to Cx + + 0x8237 RW on-pad command control 8 + bit4~bit0 0x13 RW YHI in 0s/4/1, so 11h = 1000.1b = 8.5 + (Note that position unit is in 0.5 scanline) + *only supported by H/W prior to Cx + + 0x8240 RW system control 5 + bit1 0 RW FSP Intellimouse mode enable + 0: disable, 1: enable + *only supported by H/W prior to Cx + + bit2 0 RW movement + abs. coordinate mode enable + 0: disable, 1: enable + (Note that this function has the functionality of bit 1 even when + bit 1 is not set. However, the format is different from that of bit 1. + In addition, when bit 1 and bit 2 are set at the same time, bit 2 will + override bit 1.) + *only supported by H/W prior to Cx + + bit3 0 RW abs. coordinate only mode enable + 0: disable, 1: enable + (Note that this function has the functionality of bit 1 even when + bit 1 is not set. However, the format is different from that of bit 1. + In addition, when bit 1, bit 2 and bit 3 are set at the same time, + bit 3 will override bit 1 and 2.) + *only supported by H/W prior to Cx + + bit5 0 RW auto switch enable + 0: disable, 1: enable + *only supported by H/W prior to Cx + + bit6 0 RW G0 abs. + notify packet format enable + 0: disable, 1: enable + (Note that the absolute/relative coordinate output still depends on + bit 2 and 3. That is, if any of those bit is 1, host will receive + absolute coordinates; otherwise, host only receives packets with + relative coordinate.) + *only supported by H/W prior to Cx + + bit7 0 RW EN_PS2_F2: PS/2 gesture mode 2nd + finger packet enable + 0: disable, 1: enable + *only supported by H/W prior to Cx + + 0x8243 RW on-pad control + bit0 0 RW on-pad control enable + 0: disable, 1: enable + (Note that if this bit is cleared, bit 3/5 will be ineffective) + *only supported by H/W prior to Cx + + bit3 0 RW on-pad fix vertical scrolling enable + 0: disable, 1: enable + *only supported by H/W prior to Cx + + bit5 0 RW on-pad fix horizontal scrolling enable + 0: disable, 1: enable + *only supported by H/W prior to Cx + + 0x8290 RW software control register 1 + bit0 0 RW absolute coordination mode + 0: disable, 1: enable + *supported since Cx + + bit1 0 RW gesture ID output + 0: disable, 1: enable + *supported since Cx + + bit2 0 RW two fingers' coordinates output + 0: disable, 1: enable + *supported since Cx + + bit3 0 RW finger up one packet output + 0: disable, 1: enable + *supported since Cx + + bit4 0 RW absolute coordination continuous mode + 0: disable, 1: enable + *supported since Cx + + bit6~bit5 00 RW gesture group selection + 00: basic + 01: suite + 10: suite pro + 11: advanced + *supported since Cx + + bit7 0 RW Bx packet output compatible mode + 0: disable, 1: enable + *supported since Cx + *supported since Cx + + + 0x833d RW on-pad command control 1 + bit7 1 RW on-pad command detection enable + 0: disable, 1: enable + *supported since Cx + + 0x833e RW on-pad command detection + bit7 0 RW on-pad command left button down tag + enable. Works only in H/W based PS/2 + data packet mode. + 0: disable, 1: enable + *supported since Cx diff --git a/Documentation/input/walkera0701.txt b/Documentation/input/devices/walkera0701.rst index 49e3ac60dcef..2adda99ca717 100644 --- a/Documentation/input/walkera0701.txt +++ b/Documentation/input/devices/walkera0701.rst @@ -1,3 +1,6 @@ +=========================== +Walkera WK-0701 transmitter +=========================== Walkera WK-0701 transmitter is supplied with a ready to fly Walkera helicopters such as HM36, HM37, HM60. The walkera0701 module enables to use @@ -10,7 +13,8 @@ or use cogito: cg-clone http://zub.fei.tuke.sk/GIT/walkera0701-joystick -Connecting to PC: +Connecting to PC +================ At back side of transmitter S-video connector can be found. Modulation pulses from processor to HF part can be found at pin 2 of this connector, @@ -19,7 +23,8 @@ modulation pulses to PC, signal pulses must be amplified. Cable: (walkera TX to parport) -Walkera WK-0701 TX S-VIDEO connector: +Walkera WK-0701 TX S-VIDEO connector:: + (back side of TX) __ __ S-video: canon25 / |_| \ pin 2 (signal) NPN parport @@ -30,10 +35,10 @@ Walkera WK-0701 TX S-VIDEO connector: ------- 3 __________________________________|________________ 25 GND E - I use green LED and BC109 NPN transistor. -Software: +Software +======== Build kernel with walkera0701 module. Module walkera0701 need exclusive access to parport, modules like lp must be unloaded before loading @@ -44,7 +49,8 @@ be changed by TX "joystick", check output from /proc/interrupts. Value for -Technical details: +Technical details +================= Driver use interrupt from parport ACK input bit to measure pulse length using hrtimers. @@ -53,17 +59,29 @@ Frame format: Based on walkera WK-0701 PCM Format description by Shaul Eizikovich. (downloaded from http://www.smartpropoplus.com/Docs/Walkera_Wk-0701_PCM.pdf) -Signal pulses: - (ANALOG) - SYNC BIN OCT - +---------+ +------+ - | | | | ---+ +------+ +--- +Signal pulses +------------- + +:: + + (ANALOG) + SYNC BIN OCT + +---------+ +------+ + | | | | + --+ +------+ +--- + +Frame +----- + +:: -Frame: SYNC , BIN1, OCT1, BIN2, OCT2 ... BIN24, OCT24, BIN25, next frame SYNC .. -pulse length: +pulse length +------------ + +:: + Binary values: Analog octal values: 288 uS Binary 0 318 uS 000 @@ -80,7 +98,8 @@ pulse length: (Warning, pulses on ACK are inverted by transistor, irq is raised up on sync to bin change or octal value to bin change). -Binary data representations: +Binary data representations +--------------------------- One binary and octal value can be grouped to nibble. 24 nibbles + one binary values can be sampled between sync pulses. @@ -100,10 +119,10 @@ binary value can be sampled. This bit and magic number is not used in software driver. Some details about this magic numbers can be found in Walkera_Wk-0701_PCM.pdf. -Checksum calculation: +Checksum calculation +-------------------- Summary of octal values in nibbles must be same as octal value in checksum nibble (only first 3 bits are used). Binary value for checksum nibble is calculated by sum of binary values in checked nibbles + sum of octal values in checked nibbles divided by 8. Only bit 0 of this sum is used. - diff --git a/Documentation/input/xpad.txt b/Documentation/input/devices/xpad.rst index d1b23f295db4..5a709ab77c8d 100644 --- a/Documentation/input/xpad.txt +++ b/Documentation/input/devices/xpad.rst @@ -1,4 +1,6 @@ +======================================================= xpad - Linux USB driver for Xbox compatible controllers +======================================================= This driver exposes all first-party and third-party Xbox compatible controllers. It has a long history and has enjoyed considerable usage @@ -15,9 +17,11 @@ the Xbox One's rumble protocol has not been reverse engineered but in the future could be supported. -0. Notes --------- +Notes +===== + The number of buttons/axes reported varies based on 3 things: + - if you are using a known controller - if you are using a known dance pad - if using an unknown device (one not listed below), what you set in the @@ -35,8 +39,9 @@ This is not true. Both dpad_to_buttons and triggers_to_buttons only affect unknown controllers. -0.1 Normal Controllers ----------------------- +Normal Controllers +------------------ + With a normal controller, the directional pad is mapped to its own X/Y axes. The jstest-program from joystick-1.2.15 (jstest-version 2.1.0) will report 8 axes and 10 buttons. @@ -55,8 +60,9 @@ in game functionality were OK. However, I find it rather difficult to play first person shooters with a pad. Your mileage may vary. -0.2 Xbox Dance Pads -------------------- +Xbox Dance Pads +--------------- + When using a known dance pad, jstest will report 6 axes and 14 buttons. For dance style pads (like the redoctane pad) several changes @@ -73,24 +79,21 @@ of buttons, see section 0.3 - Unknown Controllers I've tested this with Stepmania, and it works quite well. -0.3 Unknown Controllers ----------------------- +Unknown Controllers +------------------- + If you have an unknown xbox controller, it should work just fine with the default settings. HOWEVER if you have an unknown dance pad not listed below, it will not work UNLESS you set "dpad_to_buttons" to 1 in the module configuration. -PLEASE, if you have an unknown controller, email Dom <binary1230@yahoo.com> with -a dump from /proc/bus/usb and a description of the pad (manufacturer, country, -whether it is a dance pad or normal controller) so that we can add your pad -to the list of supported devices, ensuring that it will work out of the -box in the future. +USB adapters +============ -1. USB adapters --------------- All generations of Xbox controllers speak USB over the wire. + - Original Xbox controllers use a proprietary connector and require adapters. - Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver for Windows' @@ -101,8 +104,9 @@ All generations of Xbox controllers speak USB over the wire. -1.1 Original Xbox USB adapters --------------- +Original Xbox USB adapters +-------------------------- + Using this driver with an Original Xbox controller requires an adapter cable to break out the proprietary connector's pins to USB. You can buy these online fairly cheap, or build your own. @@ -115,7 +119,7 @@ the controller device) with the only difference in a nonstandard connector You just need to solder a USB connector onto the cable and keep the yellow wire unconnected. The other pins have the same order on both connectors so there is no magic to it. Detailed info on these matters -can be found on the net ([1], [2], [3]). +can be found on the net ([1]_, [2]_, [3]_). Thanks to the trip splitter found on the cable you don't even need to cut the original one. You can buy an extension cable and cut that instead. That way, @@ -123,22 +127,46 @@ you can still use the controller with your X-Box, if you have one ;) -2. Driver Installation ----------------------- +Driver Installation +=================== Once you have the adapter cable, if needed, and the controller connected the xpad module should be auto loaded. To confirm you can cat -/proc/bus/usb/devices. There should be an entry like the one at the end [4]. +/sys/kernel/debug/usb/devices. There should be an entry like those: + +.. code-block:: none + :caption: dump from InterAct PowerPad Pro (Germany) + + T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0 + D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1 + P: Vendor=05fd ProdID=107a Rev= 1.00 + C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none) + E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms + E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms +.. code-block:: none + :caption: dump from Redoctane Xbox Dance Pad (US) + T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0 + D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0c12 ProdID=8809 Rev= 0.01 + S: Product=XBOX DDR + C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA + I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad + E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms + E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms + + +Supported Controllers +===================== -3. Supported Controllers ------------------------- For a full list of supported controllers and associated vendor and product -IDs see the xpad_device[] array[6]. +IDs see the xpad_device[] array\ [4]_. As of the historic version 0.0.6 (2006-10-10) the following devices -were supported: +were supported:: + original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285 @@ -152,14 +180,16 @@ the module option 'dpad_to_buttons'. If you have an unrecognized controller please see 0.3 - Unknown Controllers -4. Manual Testing ------------------ +Manual Testing +============== + To test this driver's functionality you may use 'jstest'. -For example: -> modprobe xpad -> modprobe joydev -> jstest /dev/js0 +For example:: + + > modprobe xpad + > modprobe joydev + > jstest /dev/js0 If you're using a normal controller, there should be a single line showing 18 inputs (8 axes, 10 buttons), and its values should change if you move @@ -170,57 +200,34 @@ It works? Voila, you're done ;) -5. Thanks ---------- +Thanks +====== I have to thank ITO Takayuki for the detailed info on his site - http://euc.jp/periphs/xbox-controller.ja.html. - + http://euc.jp/periphs/xbox-controller.ja.html. + His useful info and both the usb-skeleton as well as the iforce input driver (Greg Kroah-Hartmann; Vojtech Pavlik) helped a lot in rapid prototyping the basic functionality. -6. References -------------- - -[1]: http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) -[2]: http://xpad.xbox-scene.com/ -[3]: http://www.markosweb.com/www/xboxhackz.com/ -[4]: /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): - -T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0 -D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1 -P: Vendor=05fd ProdID=107a Rev= 1.00 -C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none) -E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms -E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms - -[5]: /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US): - -T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0 -D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0c12 ProdID=8809 Rev= 0.01 -S: Product=XBOX DDR -C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad -E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms -E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms +References +========== -[6]: http://lxr.free-electrons.com/ident?i=xpad_device +.. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki) +.. [2] http://xpad.xbox-scene.com/ +.. [3] http://www.markosweb.com/www/xboxhackz.com/ +.. [4] http://lxr.free-electrons.com/ident?i=xpad_device +Historic Edits +============== -7. Historic Edits ------------------ -Marko Friedemann <mfr@bmx-chemnitz.de> -2002-07-16 +2002-07-16 - Marko Friedemann <mfr@bmx-chemnitz.de> - original doc -Dominic Cerquetti <binary1230@yahoo.com> -2005-03-19 +2005-03-19 - Dominic Cerquetti <binary1230@yahoo.com> - added stuff for dance pads, new d-pad->axes mappings Later changes may be viewed with 'git log Documentation/input/xpad.txt' diff --git a/Documentation/input/yealink.txt b/Documentation/input/devices/yealink.rst index 8277b76ec506..bb5a1aafeca2 100644 --- a/Documentation/input/yealink.txt +++ b/Documentation/input/devices/yealink.rst @@ -1,8 +1,12 @@ +=============================================== Driver documentation for yealink usb-p1k phones +=============================================== + +Status +====== -0. Status -~~~~~~~~~ The p1k is a relatively cheap usb 1.1 phone with: + - keyboard full support, yealink.ko / input event API - LCD full support, yealink.ko / sysfs API - LED full support, yealink.ko / sysfs API @@ -14,38 +18,11 @@ The p1k is a relatively cheap usb 1.1 phone with: For vendor documentation see http://www.yealink.com -1. Compilation (stand alone version) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Currently only kernel 2.6.x.y versions are supported. -In order to build the yealink.ko module do - - make - -If you encounter problems please check if in the MAKE_OPTS variable in -the Makefile is pointing to the location where your kernel sources -are located, default /usr/src/linux. - - -1.1 Troubleshooting -~~~~~~~~~~~~~~~~~~~ -Q: Module yealink compiled and installed without any problem but phone - is not initialized and does not react to any actions. -A: If you see something like: - hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone - in dmesg, it means that the hid driver has grabbed the device first. Try to - load module yealink before any other usb hid driver. Please see the - instructions provided by your distribution on module configuration. - -Q: Phone is working now (displays version and accepts keypad input) but I can't - find the sysfs files. -A: The sysfs files are located on the particular usb endpoint. On most - distributions you can do: "find /sys/ -name get_icons" for a hint. - +keyboard features +================= -2. keyboard features -~~~~~~~~~~~~~~~~~~~~ The current mapping in the kernel is provided by the map_p1k_to_key -function: +function:: Physical USB-P1K button layout input events @@ -60,14 +37,15 @@ function: 7 8 9 7, 8, 9, * 0 # *, 0, #, - The "up" and "down" keys, are symbolised by arrows on the button. - The "pickup" and "hangup" keys are symbolised by a green and red phone - on the button. +The "up" and "down" keys, are symbolised by arrows on the button. +The "pickup" and "hangup" keys are symbolised by a green and red phone +on the button. -3. LCD features -~~~~~~~~~~~~~~~ -The LCD is divided and organised as a 3 line display: +LCD features +============ + +The LCD is divided and organised as a 3 line display:: |[] [][] [][] [][] in |[][] |[] M [][] D [][] : [][] out |[][] @@ -79,18 +57,19 @@ The LCD is divided and organised as a 3 line display: [] [] [] [] [] [] [] [] [] [] [] [] -Line 1 Format (see below) : 18.e8.M8.88...188 - Icon names : M D : IN OUT STORE -Line 2 Format : ......... - Icon name : NEW REP SU MO TU WE TH FR SA -Line 3 Format : 888888888888 + Line 1 Format (see below) : 18.e8.M8.88...188 + Icon names : M D : IN OUT STORE + Line 2 Format : ......... + Icon name : NEW REP SU MO TU WE TH FR SA + Line 3 Format : 888888888888 Format description: From a userspace perspective the world is separated into "digits" and "icons". A digit can have a character set, an icon can only be ON or OFF. - Format specifier + Format specifier:: + '8' : Generic 7 segment digit with individual addressable segments Reduced capability 7 segment digit, when segments are hard wired together. @@ -105,9 +84,11 @@ Format description: elements. -4. Driver usage -~~~~~~~~~~~~~~~ -For userland the following interfaces are available using the sysfs interface: +Driver usage +============ + +For userland the following interfaces are available using the sysfs interface:: + /sys/.../ line1 Read/Write, lcd line1 line2 Read/Write, lcd line2 @@ -118,38 +99,43 @@ For userland the following interfaces are available using the sysfs interface: show_icon Write, display the element by writing the icon name. map_seg7 Read/Write, the 7 segments char set, common for all - yealink phones. (see map_to_7segment.h) + yealink phones. (see map_to_7segment.h) ringtone Write, upload binary representation of a ringtone, - see yealink.c. status EXPERIMENTAL due to potential + see yealink.c. status EXPERIMENTAL due to potential races between async. and sync usb calls. -4.1 lineX -~~~~~~~~~ -Reading /sys/../lineX will return the format string with its current value: +lineX +~~~~~ + +Reading /sys/../lineX will return the format string with its current value. + + Example:: - Example: - cat ./line3 - 888888888888 - Linux Rocks! + cat ./line3 + 888888888888 + Linux Rocks! Writing to /sys/../lineX will set the corresponding LCD line. + - Excess characters are ignored. - If less characters are written than allowed, the remaining digits are unchanged. - The tab '\t'and '\n' char does not overwrite the original content. - Writing a space to an icon will always hide its content. - Example: - date +"%m.%e.%k:%M" | sed 's/^0/ /' > ./line1 + Example:: + + date +"%m.%e.%k:%M" | sed 's/^0/ /' > ./line1 Will update the LCD with the current date & time. -4.2 get_icons -~~~~~~~~~~~~~ -Reading will return all available icon names and its current settings: +get_icons +~~~~~~~~~ + +Reading will return all available icon names and its current settings:: cat ./get_icons on M @@ -172,45 +158,68 @@ Reading will return all available icon names and its current settings: RINGTONE -4.3 show/hide icons -~~~~~~~~~~~~~~~~~~~ +show/hide icons +~~~~~~~~~~~~~~~ + Writing to these files will update the state of the icon. Only one icon at a time can be updated. If an icon is also on a ./lineX the corresponding value is updated with the first letter of the icon. - Example - light up the store icon: - echo -n "STORE" > ./show_icon + Example - light up the store icon:: + + echo -n "STORE" > ./show_icon + + cat ./line1 + 18.e8.M8.88...188 + S + + Example - sound the ringtone for 10 seconds:: - cat ./line1 - 18.e8.M8.88...188 - S + echo -n RINGTONE > /sys/..../show_icon + sleep 10 + echo -n RINGTONE > /sys/..../hide_icon - Example - sound the ringtone for 10 seconds: - echo -n RINGTONE > /sys/..../show_icon - sleep 10 - echo -n RINGTONE > /sys/..../hide_icon +Sound features +============== -5. Sound features -~~~~~~~~~~~~~~~~~ Sound is supported by the ALSA driver: snd_usb_audio One 16-bit channel with sample and playback rates of 8000 Hz is the practical limit of the device. - Example - recording test: - arecord -v -d 10 -r 8000 -f S16_LE -t wav foobar.wav + Example - recording test:: - Example - playback test: - aplay foobar.wav + arecord -v -d 10 -r 8000 -f S16_LE -t wav foobar.wav + Example - playback test:: + + aplay foobar.wav + + +Troubleshooting +=============== + +:Q: Module yealink compiled and installed without any problem but phone + is not initialized and does not react to any actions. +:A: If you see something like: + hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone + in dmesg, it means that the hid driver has grabbed the device first. Try to + load module yealink before any other usb hid driver. Please see the + instructions provided by your distribution on module configuration. + +:Q: Phone is working now (displays version and accepts keypad input) but I can't + find the sysfs files. +:A: The sysfs files are located on the particular usb endpoint. On most + distributions you can do: "find /sys/ -name get_icons" for a hint. + + +Credits & Acknowledgments +========================= -6. Credits & Acknowledgments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Olivier Vandorpe, for starting the usbb2k-api project doing much of - the reverse engineering. + the reverse engineering. - Martin Diehl, for pointing out how to handle USB memory allocation. - Dmitry Torokhov, for the numerous code reviews and suggestions. - diff --git a/Documentation/input/event-codes.txt b/Documentation/input/event-codes.rst index 36ea940e5bb9..a8c0873beb95 100644 --- a/Documentation/input/event-codes.txt +++ b/Documentation/input/event-codes.rst @@ -1,3 +1,10 @@ +.. _input-event-codes: + +================= +Input event codes +================= + + The input protocol uses a map of types and codes to express input device values to userspace. This document describes the types and codes and how and when they may be used. @@ -17,82 +24,102 @@ reports supported by a device are also provided by sysfs in class/input/event*/device/capabilities/, and the properties of a device are provided in class/input/event*/device/properties. -Event types: +Event types =========== + Event types are groupings of codes under a logical input construct. Each type has a set of applicable codes to be used in generating events. See the Codes section for details on valid codes for each type. * EV_SYN: + - Used as markers to separate events. Events may be separated in time or in space, such as with the multitouch protocol. * EV_KEY: + - Used to describe state changes of keyboards, buttons, or other key-like devices. * EV_REL: + - Used to describe relative axis value changes, e.g. moving the mouse 5 units to the left. * EV_ABS: + - Used to describe absolute axis value changes, e.g. describing the coordinates of a touch on a touchscreen. * EV_MSC: + - Used to describe miscellaneous input data that do not fit into other types. * EV_SW: + - Used to describe binary state input switches. * EV_LED: + - Used to turn LEDs on devices on and off. * EV_SND: + - Used to output sound to devices. * EV_REP: + - Used for autorepeating devices. * EV_FF: + - Used to send force feedback commands to an input device. * EV_PWR: + - A special type for power button and switch input. * EV_FF_STATUS: + - Used to receive force feedback device status. -Event codes: +Event codes =========== + Event codes define the precise type of event. -EV_SYN: ----------- +EV_SYN +------ + EV_SYN event values are undefined. Their usage is defined only by when they are sent in the evdev event stream. * SYN_REPORT: + - Used to synchronize and separate events into packets of input data changes occurring at the same moment in time. For example, motion of a mouse may set the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next motion will emit more REL_X and REL_Y values and send another SYN_REPORT. * SYN_CONFIG: + - TBD * SYN_MT_REPORT: + - Used to synchronize and separate touch events. See the multi-touch-protocol.txt document for more information. * SYN_DROPPED: + - Used to indicate buffer overrun in the evdev client's event queue. Client should ignore all events up to and including next SYN_REPORT event and query the device (using EVIOCG* ioctls) to obtain its current state. -EV_KEY: ----------- +EV_KEY +------ + EV_KEY events take the form KEY_<name> or BTN_<name>. For example, KEY_A is used to represent the 'A' key on a keyboard. When a key is depressed, an event with the key's code is emitted with value 1. When the key is released, an event is @@ -103,6 +130,7 @@ BTN_<name> is used for other types of momentary switch events. A few EV_KEY codes have special meanings: * BTN_TOOL_<name>: + - These codes are used in conjunction with input trackpads, tablets, and touchscreens. These devices may be used with fingers, pens, or other tools. When an event occurs and a tool is used, the corresponding BTN_TOOL_<name> @@ -112,6 +140,7 @@ A few EV_KEY codes have special meanings: code when events are generated. * BTN_TOUCH: + BTN_TOUCH is used for touch contact. While an input tool is determined to be within meaningful physical contact, the value of this property must be set to 1. Meaningful physical contact may mean any contact, or it may mean @@ -132,6 +161,7 @@ future, this distinction will be deprecated and the device properties ioctl EVIOCGPROP, defined in linux/input.h, will be used to convey the device type. * BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: + - These codes denote one, two, three, and four finger interaction on a trackpad or touchscreen. For example, if the user uses two fingers and moves them on the touchpad in an effort to scroll content on screen, @@ -147,8 +177,9 @@ a value of 1 in the same synchronization frame. This usage is deprecated. Note: In multitouch drivers, the input_mt_report_finger_count() function should be used to emit these codes. Please see multi-touch-protocol.txt for details. -EV_REL: ----------- +EV_REL +------ + EV_REL events describe relative changes in a property. For example, a mouse may move to the left by a certain number of units, but its absolute position in space is unknown. If the absolute position is known, EV_ABS codes should be used @@ -157,17 +188,20 @@ instead of EV_REL codes. A few EV_REL codes have special meanings: * REL_WHEEL, REL_HWHEEL: + - These codes are used for vertical and horizontal scroll wheels, respectively. -EV_ABS: ----------- +EV_ABS +------ + EV_ABS events describe absolute changes in a property. For example, a touchpad may emit coordinates for a touch location. A few EV_ABS codes have special meanings: * ABS_DISTANCE: + - Used to describe the distance of a tool from an interaction surface. This event should only be emitted while the tool is hovering, meaning in close proximity of the device and while the value of the BTN_TOUCH code is 0. If @@ -179,11 +213,13 @@ A few EV_ABS codes have special meanings: hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH. * ABS_MT_<name>: + - Used to describe multitouch input events. Please see multi-touch-protocol.txt for details. -EV_SW: ----------- +EV_SW +----- + EV_SW events describe stateful binary switches. For example, the SW_LID code is used to denote when a laptop lid is closed. @@ -195,14 +231,16 @@ Upon resume, if the switch state is the same as before suspend, then the input subsystem will filter out the duplicate switch state reports. The driver does not need to keep the state of the switch at any time. -EV_MSC: ----------- +EV_MSC +------ + EV_MSC events are used for input and output events that do not fall under other categories. A few EV_MSC codes have special meaning: * MSC_TIMESTAMP: + - Used to report the number of microseconds since the last reset. This event should be coded as an uint32 value, which is allowed to wrap around with no special consequence. It is assumed that the time difference between two @@ -211,39 +249,46 @@ A few EV_MSC codes have special meaning: unknown. If the device does not provide this information, the driver must not provide it to user space. -EV_LED: ----------- +EV_LED +------ + EV_LED events are used for input and output to set and query the state of various LEDs on devices. -EV_REP: ----------- +EV_REP +------ + EV_REP events are used for specifying autorepeating events. -EV_SND: ----------- +EV_SND +------ + EV_SND events are used for sending sound commands to simple sound output devices. -EV_FF: ----------- +EV_FF +----- + EV_FF events are used to initialize a force feedback capable device and to cause such device to feedback. -EV_PWR: ----------- +EV_PWR +------ + EV_PWR events are a special type of event used specifically for power management. Its usage is not well defined. To be addressed later. -Device properties: +Device properties ================= + Normally, userspace sets up an input device based on the data it emits, i.e., the event types. In the case of two devices emitting the same event types, additional information can be provided in the form of device properties. -INPUT_PROP_DIRECT + INPUT_PROP_POINTER: +INPUT_PROP_DIRECT + INPUT_PROP_POINTER -------------------------------------- + The INPUT_PROP_DIRECT property indicates that device coordinates should be directly mapped to screen coordinates (not taking into account trivial transformations, such as scaling, flipping and rotating). Non-direct input @@ -260,8 +305,9 @@ If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is considered undefined and the device type should be deduced in the traditional way, using emitted event types. -INPUT_PROP_BUTTONPAD: +INPUT_PROP_BUTTONPAD -------------------- + For touchpads where the button is placed beneath the surface, such that pressing down on the pad causes a button click, this property should be set. Common in clickpad notebooks and macbooks from 2009 and onwards. @@ -270,8 +316,9 @@ Originally, the buttonpad property was coded into the bcm5974 driver version field under the name integrated button. For backwards compatibility, both methods need to be checked in userspace. -INPUT_PROP_SEMI_MT: +INPUT_PROP_SEMI_MT ------------------ + Some touchpads, most common between 2008 and 2011, can detect the presence of multiple contacts without resolving the individual positions; only the number of contacts and a rectangular shape is known. For such @@ -285,9 +332,10 @@ gestures can normally be extracted from it. If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT device. -INPUT_PROP_TOPBUTTONPAD: +INPUT_PROP_TOPBUTTONPAD ----------------------- -Some laptops, most notably the Lenovo *40 series provide a trackstick + +Some laptops, most notably the Lenovo 40 series provide a trackstick device but do not have physical buttons associated with the trackstick device. Instead, the top area of the touchpad is marked to show visual/haptic areas for left, middle, right buttons intended to be used @@ -299,26 +347,33 @@ The kernel does not provide button emulation for such devices but treats them as any other INPUT_PROP_BUTTONPAD device. INPUT_PROP_ACCELEROMETER -------------------------- +------------------------ + Directional axes on this device (absolute and/or relative x, y, z) represent -accelerometer data. All other axes retain their meaning. A device must not mix +accelerometer data. Some devices also report gyroscope data, which devices +can report through the rotational axes (absolute and/or relative rx, ry, rz). + +All other axes retain their meaning. A device must not mix regular directional axes and accelerometer axes on the same event node. -Guidelines: +Guidelines ========== + The guidelines below ensure proper single-touch and multi-finger functionality. For multi-touch functionality, see the multi-touch-protocol.txt document for more information. -Mice: ----------- +Mice +---- + REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report scroll wheel events where available. -Touchscreens: ----------- +Touchscreens +------------ + ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be used to report when a touch is active on the screen. BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch @@ -326,8 +381,9 @@ contact. BTN_TOOL_<name> events should be reported where possible. For new hardware, INPUT_PROP_DIRECT should be set. -Trackpads: ----------- +Trackpads +--------- + Legacy trackpads that only provide relative position information must report events like mice described above. @@ -338,8 +394,9 @@ be used to report the number of touches active on the trackpad. For new hardware, INPUT_PROP_POINTER should be set. -Tablets: ----------- +Tablets +------- + BTN_TOOL_<name> events must be reported when a stylus or other tool is active on the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH should be used to report when the tool is in contact with the tablet. diff --git a/Documentation/input/ff.txt b/Documentation/input/ff.rst index b3867bf49f8f..6a265a6934e6 100644 --- a/Documentation/input/ff.txt +++ b/Documentation/input/ff.rst @@ -1,12 +1,16 @@ -Force feedback for Linux. -By Johann Deneux <johann.deneux@gmail.com> on 2001/04/22. -Updated by Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09. -You may redistribute this file. Please remember to include shape.fig and -interactive.fig as well. ----------------------------------------------------------------------------- - -1. Introduction -~~~~~~~~~~~~~~~ +======================== +Force feedback for Linux +======================== + +:Author: Johann Deneux <johann.deneux@gmail.com> on 2001/04/22. +:Updated: Anssi Hannula <anssi.hannula@gmail.com> on 2006/04/09. + +You may redistribute this file. Please remember to include shape.svg and +interactive.svg as well. + +Introduction +~~~~~~~~~~~~ + This document describes how to use force feedback devices under Linux. The goal is not to support these devices as if they were simple input-only devices (as it is already the case), but to really enable the rendering of force @@ -15,8 +19,9 @@ This document only describes the force feedback part of the Linux input interface. Please read joystick.txt and input.txt before reading further this document. -2. Instructions to the user -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Instructions to the user +~~~~~~~~~~~~~~~~~~~~~~~~ + To enable force feedback, you have to: 1. have your kernel configured with evdev and a driver that supports your @@ -33,39 +38,48 @@ something goes wrong. If you have a serial iforce device, you need to start inputattach. See joystick.txt for details. -2.1 Does it work ? -~~~~~~~~~~~~~~~~~~ -There is an utility called fftest that will allow you to test the driver. -% fftest /dev/input/eventXX +Does it work ? +-------------- + +There is an utility called fftest that will allow you to test the driver:: + + % fftest /dev/input/eventXX + +Instructions to the developer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -3. Instructions to the developer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All interactions are done using the event API. That is, you can use ioctl() and write() on /dev/input/eventXX. This information is subject to change. -3.1 Querying device capabilities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#include <linux/input.h> -#include <sys/ioctl.h> +Querying device capabilities +---------------------------- + +:: -#define BITS_TO_LONGS(x) \ - (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) -unsigned long features[BITS_TO_LONGS(FF_CNT)]; -int ioctl(int file_descriptor, int request, unsigned long *features); + #include <linux/input.h> + #include <sys/ioctl.h> + + #define BITS_TO_LONGS(x) \ + (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) + unsigned long features[BITS_TO_LONGS(FF_CNT)]; + int ioctl(int file_descriptor, int request, unsigned long *features); "request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) Returns the features supported by the device. features is a bitfield with the following bits: + - FF_CONSTANT can render constant force effects - FF_PERIODIC can render periodic effects with the following waveforms: + - FF_SQUARE square waveform - FF_TRIANGLE triangle waveform - FF_SINE sine waveform - FF_SAW_UP sawtooth up waveform - FF_SAW_DOWN sawtooth down waveform - FF_CUSTOM custom waveform + - FF_RAMP can render ramp effects - FF_SPRING can simulate the presence of a spring - FF_FRICTION can simulate friction @@ -75,24 +89,30 @@ following bits: - FF_GAIN gain is adjustable - FF_AUTOCENTER autocenter is adjustable -Note: In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All +.. note:: + + - In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, sine) and the other way around. -Note: The exact syntax FF_CUSTOM is undefined for the time being as no driver + - The exact syntax FF_CUSTOM is undefined for the time being as no driver supports it yet. +:: -int ioctl(int fd, EVIOCGEFFECTS, int *n); + int ioctl(int fd, EVIOCGEFFECTS, int *n); Returns the number of effects the device can keep in its memory. -3.2 Uploading effects to the device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#include <linux/input.h> -#include <sys/ioctl.h> +Uploading effects to the device +------------------------------- + +:: -int ioctl(int file_descriptor, int request, struct ff_effect *effect); + #include <linux/input.h> + #include <sys/ioctl.h> + + int ioctl(int file_descriptor, int request, struct ff_effect *effect); "request" must be EVIOCSFF. @@ -106,38 +126,53 @@ allocate a new effect. Effects are file descriptor specific. -See <linux/input.h> for a description of the ff_effect struct. You should also -find help in a few sketches, contained in files shape.fig and interactive.fig. -You need xfig to visualize these files. +See <uapi/linux/input.h> for a description of the ff_effect struct. You +should also find help in a few sketches, contained in files shape.svg +and interactive.svg: + +.. figure:: shape.svg -3.3 Removing an effect from the device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -int ioctl(int fd, EVIOCRMFF, effect.id); + Shape + +.. figure:: interactive.svg + + Interactive + + +Removing an effect from the device +---------------------------------- + +:: + + int ioctl(int fd, EVIOCRMFF, effect.id); This makes room for new effects in the device's memory. Note that this also stops the effect if it was playing. -3.4 Controlling the playback of effects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Controlling the playback of effects +----------------------------------- + Control of playing is done with write(). Below is an example: -#include <linux/input.h> -#include <unistd.h> +:: + + #include <linux/input.h> + #include <unistd.h> struct input_event play; struct input_event stop; struct ff_effect effect; int fd; -... + ... fd = open("/dev/input/eventXX", O_RDWR); -... + ... /* Play three times */ play.type = EV_FF; play.code = effect.id; play.value = 3; write(fd, (const void*) &play, sizeof(play)); -... + ... /* Stop an effect */ stop.type = EV_FF; stop.code = effect.id; @@ -145,43 +180,50 @@ Control of playing is done with write(). Below is an example: write(fd, (const void*) &play, sizeof(stop)); -3.5 Setting the gain -~~~~~~~~~~~~~~~~~~~~ +Setting the gain +---------------- + Not all devices have the same strength. Therefore, users should set a gain factor depending on how strong they want effects to be. This setting is persistent across access to the driver. -/* Set the gain of the device -int gain; /* between 0 and 100 */ -struct input_event ie; /* structure used to communicate with the driver */ +:: + + /* Set the gain of the device + int gain; /* between 0 and 100 */ + struct input_event ie; /* structure used to communicate with the driver */ -ie.type = EV_FF; -ie.code = FF_GAIN; -ie.value = 0xFFFFUL * gain / 100; + ie.type = EV_FF; + ie.code = FF_GAIN; + ie.value = 0xFFFFUL * gain / 100; -if (write(fd, &ie, sizeof(ie)) == -1) + if (write(fd, &ie, sizeof(ie)) == -1) perror("set gain"); -3.6 Enabling/Disabling autocenter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Enabling/Disabling autocenter +----------------------------- + The autocenter feature quite disturbs the rendering of effects in my opinion, and I think it should be an effect, which computation depends on the game type. But you can enable it if you want. -int autocenter; /* between 0 and 100 */ -struct input_event ie; +:: + + int autocenter; /* between 0 and 100 */ + struct input_event ie; -ie.type = EV_FF; -ie.code = FF_AUTOCENTER; -ie.value = 0xFFFFUL * autocenter / 100; + ie.type = EV_FF; + ie.code = FF_AUTOCENTER; + ie.value = 0xFFFFUL * autocenter / 100; -if (write(fd, &ie, sizeof(ie)) == -1) + if (write(fd, &ie, sizeof(ie)) == -1) perror("set auto-center"); A value of 0 means "no auto-center". -3.7 Dynamic update of an effect -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Dynamic update of an effect +--------------------------- + Proceed as if you wanted to upload a new effect, except that instead of setting the id field to -1, you set it to the wanted effect id. Normally, the effect is not stopped and restarted. However, depending on the @@ -192,30 +234,32 @@ case, the driver stops the effect, up-load it, and restart it. Therefore it is recommended to dynamically change direction while the effect is playing only when it is ok to restart the effect with a replay count of 1. -3.8 Information about the status of effects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Information about the status of effects +--------------------------------------- + Every time the status of an effect is changed, an event is sent. The values -and meanings of the fields of the event are as follows: +and meanings of the fields of the event are as follows:: -struct input_event { -/* When the status of the effect changed */ - struct timeval time; + struct input_event { + /* When the status of the effect changed */ + struct timeval time; -/* Set to EV_FF_STATUS */ - unsigned short type; + /* Set to EV_FF_STATUS */ + unsigned short type; -/* Contains the id of the effect */ - unsigned short code; + /* Contains the id of the effect */ + unsigned short code; -/* Indicates the status */ - unsigned int value; -}; + /* Indicates the status */ + unsigned int value; + }; -FF_STATUS_STOPPED The effect stopped playing -FF_STATUS_PLAYING The effect started to play + FF_STATUS_STOPPED The effect stopped playing + FF_STATUS_PLAYING The effect started to play -NOTE: Status feedback is only supported by iforce driver. If you have +.. note:: + + - Status feedback is only supported by iforce driver. If you have a really good reason to use this, please contact linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com so that support for it can be added to the rest of the drivers. - diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.rst index 3f6d8a5e9cdc..4d5e7fb80a84 100644 --- a/Documentation/input/gamepad.txt +++ b/Documentation/input/gamepad.rst @@ -1,15 +1,19 @@ - Linux Gamepad API ----------------------------------------------------------------------------- +--------------------------- +Linux Gamepad Specification +--------------------------- -1. Intro -~~~~~~~~ +:Author: 2013 by David Herrmann <dh.herrmann@gmail.com> + + +Introduction +~~~~~~~~~~~~ Linux provides many different input drivers for gamepad hardware. To avoid having user-space deal with different button-mappings for each gamepad, this document defines how gamepads are supposed to report their data. -2. Geometry -~~~~~~~~~~~ -As "gamepad" we define devices which roughly look like this: +Geometry +~~~~~~~~ +As "gamepad" we define devices which roughly look like this:: ____________________________ __ / [__ZL__] [__ZR__] \ | @@ -35,6 +39,7 @@ As "gamepad" we define devices which roughly look like this: Menu Pad Most gamepads have the following features: + - Action-Pad 4 buttons in diamonds-shape (on the right side). The buttons are differently labeled on most devices so we define them as NORTH, @@ -58,8 +63,9 @@ Most gamepads have the following features: Many devices provide force-feedback features. But are mostly just simple rumble motors. -3. Detection -~~~~~~~~~~~~ +Detection +~~~~~~~~~ + All gamepads that follow the protocol described here map BTN_GAMEPAD. This is an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such. However, not all gamepads provide all features, so you need to test for all @@ -85,75 +91,101 @@ devices that report a small subset of the events. No other devices, that do not look/feel like a gamepad, shall report these events. -4. Events -~~~~~~~~~ +Events +~~~~~~ + Gamepads report the following events: -Action-Pad: +- Action-Pad: + Every gamepad device has at least 2 action buttons. This means, that every device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless of the labels on the buttons, the codes are sent according to the physical position of the buttons. + Please note that 2- and 3-button pads are fairly rare and old. You might want to filter gamepads that do not report all four. - 2-Button Pad: + + - 2-Button Pad: + If only 2 action-buttons are present, they are reported as BTN_SOUTH and BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For horizontal layouts, the button more on the right is BTN_EAST. - 3-Button Pad: + + - 3-Button Pad: + If only 3 action-buttons are present, they are reported as (from left to right): BTN_WEST, BTN_SOUTH, BTN_EAST If the buttons are aligned perfectly vertically, they are reported as (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST - 4-Button Pad: + + - 4-Button Pad: + If all 4 action-buttons are present, they can be aligned in two different formations. If diamond-shaped, they are reported as BTN_NORTH, BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location. If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST. -D-Pad: +- D-Pad: + Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right Some of these are available as digital buttons, some as analog buttons. Some may even report both. The kernel does not convert between these so applications should support both and choose what is more appropriate if both are reported. - Digital buttons are reported as: + + - Digital buttons are reported as: + BTN_DPAD_* - Analog buttons are reported as: + + - Analog buttons are reported as: + ABS_HAT0X and ABS_HAT0Y - (for ABS values negative is left/up, positive is right/down) -Analog-Sticks: + (for ABS values negative is left/up, positive is right/down) + +- Analog-Sticks: + The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present. If analog-sticks provide digital buttons, they are mapped accordingly as BTN_THUMBL (first/left) and BTN_THUMBR (second/right). - (for ABS values negative is left/up, positive is right/down) -Triggers: + (for ABS values negative is left/up, positive is right/down) + +- Triggers: + Trigger buttons can be available as digital or analog buttons or both. User- space must correctly deal with any situation and choose the most appropriate mode. + Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL). + If only one trigger-button combination is present (upper+lower), they are reported as "right" triggers (BTN_TR/ABS_HAT1X). - (ABS trigger values start at 0, pressure is reported as positive values) -Menu-Pad: + (ABS trigger values start at 0, pressure is reported as positive values) + +- Menu-Pad: + Menu buttons are always digital and are mapped according to their location instead of their labels. That is: - 1-button Pad: Mapped as BTN_START - 2-button Pad: Left button mapped as BTN_SELECT, right button mapped as - BTN_START + + - 1-button Pad: + + Mapped as BTN_START + + - 2-button Pad: + + Left button mapped as BTN_SELECT, right button mapped as BTN_START + Many pads also have a third button which is branded or has a special symbol and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo "HOME" button, the XBox "X"-button or Sony "PS" button. -Rumble: - Rumble is advertised as FF_RUMBLE. +- Rumble: ----------------------------------------------------------------------------- - Written 2013 by David Herrmann <dh.herrmann@gmail.com> + Rumble is advertised as FF_RUMBLE. diff --git a/Documentation/input/gameport-programming.txt b/Documentation/input/gameport-programming.rst index 03a74fc3b496..c96911df1c54 100644 --- a/Documentation/input/gameport-programming.txt +++ b/Documentation/input/gameport-programming.rst @@ -1,11 +1,12 @@ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Programming gameport drivers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. A basic classic gameport -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A basic classic gameport +~~~~~~~~~~~~~~~~~~~~~~~~ If the gameport doesn't provide more than the inb()/outb() functionality, -the code needed to register it with the joystick drivers is simple: +the code needed to register it with the joystick drivers is simple:: struct gameport gameport; @@ -37,12 +38,12 @@ space only when something really is using it. Disable it again in the callback, so that it doesn't fail if some of the possible addresses are already occupied by other gameports. -2. Memory mapped gameport -~~~~~~~~~~~~~~~~~~~~~~~~~ +Memory mapped gameport +~~~~~~~~~~~~~~~~~~~~~~ When a gameport can be accessed through MMIO, this way is preferred, because it is faster, allowing more reads per second. Registering such a gameport -isn't as easy as a basic IO one, but not so much complex: +isn't as easy as a basic IO one, but not so much complex:: struct gameport gameport; @@ -53,19 +54,21 @@ isn't as easy as a basic IO one, but not so much complex: unsigned char my_read(struct gameport *gameport) { - return my_mmio; + return my_mmio; } gameport.read = my_read; gameport.trigger = my_trigger; gameport_register_port(&gameport); -3. Cooked mode gameport -~~~~~~~~~~~~~~~~~~~~~~~ +.. _gameport_pgm_cooked_mode: + +Cooked mode gameport +~~~~~~~~~~~~~~~~~~~~ There are gameports that can report the axis values as numbers, that means the driver doesn't have to measure them the old way - an ADC is built into -the gameport. To register a cooked gameport: +the gameport. To register a cooked gameport:: struct gameport gameport; @@ -95,8 +98,8 @@ See analog.c and input.c for handling of fuzz - the fuzz value determines the size of a gaussian filter window that is used to eliminate the noise in the data. -4. More complex gameports -~~~~~~~~~~~~~~~~~~~~~~~~~ +More complex gameports +~~~~~~~~~~~~~~~~~~~~~~ Gameports can support both raw and cooked modes. In that case combine either examples 1+2 or 1+3. Gameports can support internal calibration - see below, @@ -104,65 +107,91 @@ and also lightning.c and analog.c on how that works. If your driver supports more than one gameport instance simultaneously, use the ->private member of the gameport struct to point to your data. -5. Unregistering a gameport -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Unregistering a gameport +~~~~~~~~~~~~~~~~~~~~~~~~ + +Simple:: + + gameport_unregister_port(&gameport); + +The gameport structure +~~~~~~~~~~~~~~~~~~~~~~ -Simple: +.. note:: -gameport_unregister_port(&gameport); + This section is outdated. There are several fields here that don't + match what's there at include/linux/gameport.h. -6. The gameport structure -~~~~~~~~~~~~~~~~~~~~~~~~~ +:: -struct gameport { + struct gameport { void *private; A private pointer for free use in the gameport driver. (Not the joystick driver!) +:: + int number; Number assigned to the gameport when registered. Informational purpose only. +:: + int io; I/O address for use with raw mode. You have to either set this, or ->read() to some value if your gameport supports raw mode. +:: + int speed; Raw mode speed of the gameport reads in thousands of reads per second. +:: + int fuzz; If the gameport supports cooked mode, this should be set to a value that -represents the amount of noise in the data. See section 3. +represents the amount of noise in the data. See +:ref:`gameport_pgm_cooked_mode`. + +:: void (*trigger)(struct gameport *); Trigger. This function should trigger the ns558 oneshots. If set to NULL, outb(0xff, io) will be used. +:: + unsigned char (*read)(struct gameport *); Read the buttons and ns558 oneshot bits. If set to NULL, inb(io) will be used instead. - int (*cooked_read)(struct gameport *, int *axes, int *buttons); +:: + + int (*cooked_read)(struct gameport *, int *axes, int *buttons); If the gameport supports cooked mode, it should point this to its cooked read function. It should fill axes[0..3] with four values of the joystick axes and buttons[0] with four bits representing the buttons. - int (*calibrate)(struct gameport *, int *axes, int *max); +:: + + int (*calibrate)(struct gameport *, int *axes, int *max); Function for calibrating the ADC hardware. When called, axes[0..3] should be pre-filled by cooked data by the caller, max[0..3] should be pre-filled with expected maximums for each axis. The calibrate() function should set the sensitivity of the ADC hardware so that the maximums fit in its range and recompute the axes[] values to match the new sensitivity or re-read them from -the hardware so that they give valid values. +the hardware so that they give valid values. + +:: int (*open)(struct gameport *, int mode); @@ -172,16 +201,22 @@ Second, resource allocation can happen here. The port can also be enabled here. Prior to this call, other fields of the gameport struct (namely the io member) need not to be valid. +:: + void (*close)(struct gameport *); Close() should free the resources allocated by open, possibly disabling the gameport. +:: + struct gameport_dev *dev; struct gameport *next; For internal use by the gameport layer. -}; +:: + + }; Enjoy! diff --git a/Documentation/input/gpio-tilt.txt b/Documentation/input/gpio-tilt.txt deleted file mode 100644 index 2cdfd9bcb1af..000000000000 --- a/Documentation/input/gpio-tilt.txt +++ /dev/null @@ -1,103 +0,0 @@ -Driver for tilt-switches connected via GPIOs -============================================ - -Generic driver to read data from tilt switches connected via gpios. -Orientation can be provided by one or more than one tilt switches, -i.e. each tilt switch providing one axis, and the number of axes -is also not limited. - - -Data structures: ----------------- - -The array of struct gpio in the gpios field is used to list the gpios -that represent the current tilt state. - -The array of struct gpio_tilt_axis describes the axes that are reported -to the input system. The values set therein are used for the -input_set_abs_params calls needed to init the axes. - -The array of struct gpio_tilt_state maps gpio states to the corresponding -values to report. The gpio state is represented as a bitfield where the -bit-index corresponds to the index of the gpio in the struct gpio array. -In the same manner the values stored in the axes array correspond to -the elements of the gpio_tilt_axis-array. - - -Example: --------- - -Example configuration for a single TS1003 tilt switch that rotates around -one axis in 4 steps and emits the current tilt via two GPIOs. - -static int sg060_tilt_enable(struct device *dev) { - /* code to enable the sensors */ -}; - -static void sg060_tilt_disable(struct device *dev) { - /* code to disable the sensors */ -}; - -static struct gpio sg060_tilt_gpios[] = { - { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" }, - { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" }, -}; - -static struct gpio_tilt_state sg060_tilt_states[] = { - { - .gpios = (0 << 1) | (0 << 0), - .axes = (int[]) { - 0, - }, - }, { - .gpios = (0 << 1) | (1 << 0), - .axes = (int[]) { - 1, /* 90 degrees */ - }, - }, { - .gpios = (1 << 1) | (1 << 0), - .axes = (int[]) { - 2, /* 180 degrees */ - }, - }, { - .gpios = (1 << 1) | (0 << 0), - .axes = (int[]) { - 3, /* 270 degrees */ - }, - }, -}; - -static struct gpio_tilt_axis sg060_tilt_axes[] = { - { - .axis = ABS_RY, - .min = 0, - .max = 3, - .fuzz = 0, - .flat = 0, - }, -}; - -static struct gpio_tilt_platform_data sg060_tilt_pdata= { - .gpios = sg060_tilt_gpios, - .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios), - - .axes = sg060_tilt_axes, - .nr_axes = ARRAY_SIZE(sg060_tilt_axes), - - .states = sg060_tilt_states, - .nr_states = ARRAY_SIZE(sg060_tilt_states), - - .debounce_interval = 100, - - .poll_interval = 1000, - .enable = sg060_tilt_enable, - .disable = sg060_tilt_disable, -}; - -static struct platform_device sg060_device_tilt = { - .name = "gpio-tilt-polled", - .id = -1, - .dev = { - .platform_data = &sg060_tilt_pdata, - }, -}; diff --git a/Documentation/input/iforce-protocol.txt b/Documentation/input/iforce-protocol.txt deleted file mode 100644 index 66287151c54a..000000000000 --- a/Documentation/input/iforce-protocol.txt +++ /dev/null @@ -1,258 +0,0 @@ -** Introduction -This document describes what I managed to discover about the protocol used to -specify force effects to I-Force 2.0 devices. None of this information comes -from Immerse. That's why you should not trust what is written in this -document. This document is intended to help understanding the protocol. -This is not a reference. Comments and corrections are welcome. To contact me, -send an email to: johann.deneux@gmail.com - -** WARNING ** -I shall not be held responsible for any damage or harm caused if you try to -send data to your I-Force device based on what you read in this document. - -** Preliminary Notes: -All values are hexadecimal with big-endian encoding (msb on the left). Beware, -values inside packets are encoded using little-endian. Bytes whose roles are -unknown are marked ??? Information that needs deeper inspection is marked (?) - -** General form of a packet ** -This is how packets look when the device uses the rs232 to communicate. -2B OP LEN DATA CS -CS is the checksum. It is equal to the exclusive or of all bytes. - -When using USB: -OP DATA -The 2B, LEN and CS fields have disappeared, probably because USB handles frames and -data corruption is handled or unsignificant. - -First, I describe effects that are sent by the device to the computer - -** Device input state -This packet is used to indicate the state of each button and the value of each -axis -OP= 01 for a joystick, 03 for a wheel -LEN= Varies from device to device -00 X-Axis lsb -01 X-Axis msb -02 Y-Axis lsb, or gas pedal for a wheel -03 Y-Axis msb, or brake pedal for a wheel -04 Throttle -05 Buttons -06 Lower 4 bits: Buttons - Upper 4 bits: Hat -07 Rudder - -** Device effects states -OP= 02 -LEN= Varies -00 ? Bit 1 (Value 2) is the value of the deadman switch -01 Bit 8 is set if the effect is playing. Bits 0 to 7 are the effect id. -02 ?? -03 Address of parameter block changed (lsb) -04 Address of parameter block changed (msb) -05 Address of second parameter block changed (lsb) -... depending on the number of parameter blocks updated - -** Force effect ** -OP= 01 -LEN= 0e -00 Channel (when playing several effects at the same time, each must be assigned a channel) -01 Wave form - Val 00 Constant - Val 20 Square - Val 21 Triangle - Val 22 Sine - Val 23 Sawtooth up - Val 24 Sawtooth down - Val 40 Spring (Force = f(pos)) - Val 41 Friction (Force = f(velocity)) and Inertia (Force = f(acceleration)) - - -02 Axes affected and trigger - Bits 4-7: Val 2 = effect along one axis. Byte 05 indicates direction - Val 4 = X axis only. Byte 05 must contain 5a - Val 8 = Y axis only. Byte 05 must contain b4 - Val c = X and Y axes. Bytes 05 must contain 60 - Bits 0-3: Val 0 = No trigger - Val x+1 = Button x triggers the effect - When the whole byte is 0, cancel the previously set trigger - -03-04 Duration of effect (little endian encoding, in ms) - -05 Direction of effect, if applicable. Else, see 02 for value to assign. - -06-07 Minimum time between triggering. - -08-09 Address of periodicity or magnitude parameters -0a-0b Address of attack and fade parameters, or ffff if none. -*or* -08-09 Address of interactive parameters for X-axis, or ffff if not applicable -0a-0b Address of interactive parameters for Y-axis, or ffff if not applicable - -0c-0d Delay before execution of effect (little endian encoding, in ms) - - -** Time based parameters ** - -*** Attack and fade *** -OP= 02 -LEN= 08 -00-01 Address where to store the parameters -02-03 Duration of attack (little endian encoding, in ms) -04 Level at end of attack. Signed byte. -05-06 Duration of fade. -07 Level at end of fade. - -*** Magnitude *** -OP= 03 -LEN= 03 -00-01 Address -02 Level. Signed byte. - -*** Periodicity *** -OP= 04 -LEN= 07 -00-01 Address -02 Magnitude. Signed byte. -03 Offset. Signed byte. -04 Phase. Val 00 = 0 deg, Val 40 = 90 degs. -05-06 Period (little endian encoding, in ms) - -** Interactive parameters ** -OP= 05 -LEN= 0a -00-01 Address -02 Positive Coeff -03 Negative Coeff -04+05 Offset (center) -06+07 Dead band (Val 01F4 = 5000 (decimal)) -08 Positive saturation (Val 0a = 1000 (decimal) Val 64 = 10000 (decimal)) -09 Negative saturation - -The encoding is a bit funny here: For coeffs, these are signed values. The -maximum value is 64 (100 decimal), the min is 9c. -For the offset, the minimum value is FE0C, the maximum value is 01F4. -For the deadband, the minimum value is 0, the max is 03E8. - -** Controls ** -OP= 41 -LEN= 03 -00 Channel -01 Start/Stop - Val 00: Stop - Val 01: Start and play once. - Val 41: Start and play n times (See byte 02 below) -02 Number of iterations n. - -** Init ** - -*** Querying features *** -OP= ff -Query command. Length varies according to the query type. -The general format of this packet is: -ff 01 QUERY [INDEX] CHECKSUM -responses are of the same form: -FF LEN QUERY VALUE_QUERIED CHECKSUM2 -where LEN = 1 + length(VALUE_QUERIED) - -**** Query ram size **** -QUERY = 42 ('B'uffer size) -The device should reply with the same packet plus two additional bytes -containing the size of the memory: -ff 03 42 03 e8 CS would mean that the device has 1000 bytes of ram available. - -**** Query number of effects **** -QUERY = 4e ('N'umber of effects) -The device should respond by sending the number of effects that can be played -at the same time (one byte) -ff 02 4e 14 CS would stand for 20 effects. - -**** Vendor's id **** -QUERY = 4d ('M'anufacturer) -Query the vendors'id (2 bytes) - -**** Product id ***** -QUERY = 50 ('P'roduct) -Query the product id (2 bytes) - -**** Open device **** -QUERY = 4f ('O'pen) -No data returned. - -**** Close device ***** -QUERY = 43 ('C')lose -No data returned. - -**** Query effect **** -QUERY = 45 ('E') -Send effect type. -Returns nonzero if supported (2 bytes) - -**** Firmware Version **** -QUERY = 56 ('V'ersion) -Sends back 3 bytes - major, minor, subminor - -*** Initialisation of the device *** - -**** Set Control **** -!!! Device dependent, can be different on different models !!! -OP= 40 <idx> <val> [<val>] -LEN= 2 or 3 -00 Idx - Idx 00 Set dead zone (0..2048) - Idx 01 Ignore Deadman sensor (0..1) - Idx 02 Enable comm watchdog (0..1) - Idx 03 Set the strength of the spring (0..100) - Idx 04 Enable or disable the spring (0/1) - Idx 05 Set axis saturation threshold (0..2048) - -**** Set Effect State **** -OP= 42 <val> -LEN= 1 -00 State - Bit 3 Pause force feedback - Bit 2 Enable force feedback - Bit 0 Stop all effects - -**** Set overall gain **** -OP= 43 <val> -LEN= 1 -00 Gain - Val 00 = 0% - Val 40 = 50% - Val 80 = 100% - -** Parameter memory ** - -Each device has a certain amount of memory to store parameters of effects. -The amount of RAM may vary, I encountered values from 200 to 1000 bytes. Below -is the amount of memory apparently needed for every set of parameters: - - period : 0c - - magnitude : 02 - - attack and fade : 0e - - interactive : 08 - -** Appendix: How to study the protocol ? ** - -1. Generate effects using the force editor provided with the DirectX SDK, or -use Immersion Studio (freely available at their web site in the developer section: -www.immersion.com) -2. Start a soft spying RS232 or USB (depending on where you connected your -joystick/wheel). I used ComPortSpy from fCoder (alpha version!) -3. Play the effect, and watch what happens on the spy screen. - -A few words about ComPortSpy: -At first glance, this software seems, hum, well... buggy. In fact, data appear with a -few seconds latency. Personally, I restart it every time I play an effect. -Remember it's free (as in free beer) and alpha! - -** URLS ** -Check www.immerse.com for Immersion Studio, and www.fcoder.com for ComPortSpy. - -** Author of this document ** -Johann Deneux <johann.deneux@gmail.com> -Home page at http://web.archive.org/web/*/http://www.esil.univ-mrs.fr - -Additions by Vojtech Pavlik. - -I-Force is trademark of Immersion Corp. diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst new file mode 100644 index 000000000000..7a3e71c2bd00 --- /dev/null +++ b/Documentation/input/index.rst @@ -0,0 +1,20 @@ +============================= +The Linux Input Documentation +============================= + +Contents: + +.. toctree:: + :maxdepth: 2 + :numbered: + + input_uapi + input_kapi + devices/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.rst index 7f8b9d97bc47..45a4c6e05e39 100644 --- a/Documentation/input/input-programming.txt +++ b/Documentation/input/input-programming.rst @@ -1,77 +1,75 @@ -Programming input drivers -~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== +Creating an input device driver +=============================== -1. Creating an input device driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1.0 The simplest example -~~~~~~~~~~~~~~~~~~~~~~~~ +The simplest example +~~~~~~~~~~~~~~~~~~~~ Here comes a very simple example of an input device driver. The device has just one button and the button is accessible at i/o port BUTTON_PORT. When -pressed or released a BUTTON_IRQ happens. The driver could look like: - -#include <linux/input.h> -#include <linux/module.h> -#include <linux/init.h> - -#include <asm/irq.h> -#include <asm/io.h> - -static struct input_dev *button_dev; - -static irqreturn_t button_interrupt(int irq, void *dummy) -{ - input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1); - input_sync(button_dev); - return IRQ_HANDLED; -} - -static int __init button_init(void) -{ - int error; - - if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { - printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); - return -EBUSY; - } - - button_dev = input_allocate_device(); - if (!button_dev) { - printk(KERN_ERR "button.c: Not enough memory\n"); - error = -ENOMEM; - goto err_free_irq; - } - - button_dev->evbit[0] = BIT_MASK(EV_KEY); - button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0); - - error = input_register_device(button_dev); - if (error) { - printk(KERN_ERR "button.c: Failed to register device\n"); - goto err_free_dev; - } - - return 0; - - err_free_dev: - input_free_device(button_dev); - err_free_irq: - free_irq(BUTTON_IRQ, button_interrupt); - return error; -} - -static void __exit button_exit(void) -{ - input_unregister_device(button_dev); - free_irq(BUTTON_IRQ, button_interrupt); -} - -module_init(button_init); -module_exit(button_exit); - -1.1 What the example does -~~~~~~~~~~~~~~~~~~~~~~~~~ +pressed or released a BUTTON_IRQ happens. The driver could look like:: + + #include <linux/input.h> + #include <linux/module.h> + #include <linux/init.h> + + #include <asm/irq.h> + #include <asm/io.h> + + static struct input_dev *button_dev; + + static irqreturn_t button_interrupt(int irq, void *dummy) + { + input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1); + input_sync(button_dev); + return IRQ_HANDLED; + } + + static int __init button_init(void) + { + int error; + + if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { + printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); + return -EBUSY; + } + + button_dev = input_allocate_device(); + if (!button_dev) { + printk(KERN_ERR "button.c: Not enough memory\n"); + error = -ENOMEM; + goto err_free_irq; + } + + button_dev->evbit[0] = BIT_MASK(EV_KEY); + button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0); + + error = input_register_device(button_dev); + if (error) { + printk(KERN_ERR "button.c: Failed to register device\n"); + goto err_free_dev; + } + + return 0; + + err_free_dev: + input_free_device(button_dev); + err_free_irq: + free_irq(BUTTON_IRQ, button_interrupt); + return error; + } + + static void __exit button_exit(void) + { + input_unregister_device(button_dev); + free_irq(BUTTON_IRQ, button_interrupt); + } + + module_init(button_init); + module_exit(button_exit); + +What the example does +~~~~~~~~~~~~~~~~~~~~~ First it has to include the <linux/input.h> file, which interfaces to the input subsystem. This provides all the definitions needed. @@ -85,7 +83,7 @@ and sets up input bitfields. This way the device driver tells the other parts of the input systems what it is - what events can be generated or accepted by this input device. Our example device can only generate EV_KEY type events, and from those only BTN_0 event code. Thus we only set these -two bits. We could have used +two bits. We could have used:: set_bit(EV_KEY, button_dev.evbit); set_bit(BTN_0, button_dev.keybit); @@ -93,7 +91,7 @@ two bits. We could have used as well, but with more than single bits the first approach tends to be shorter. -Then the example driver registers the input device structure by calling +Then the example driver registers the input device structure by calling:: input_register_device(&button_dev); @@ -102,12 +100,12 @@ calls device handler modules _connect functions to tell them a new input device has appeared. input_register_device() may sleep and therefore must not be called from an interrupt or with a spinlock held. -While in use, the only used function of the driver is +While in use, the only used function of the driver is:: button_interrupt() which upon every interrupt from the button checks its state and reports it -via the +via the:: input_report_key() @@ -116,7 +114,7 @@ routine isn't reporting two same value events (press, press for example) to the input system, because the input_report_* functions check that themselves. -Then there is the +Then there is the:: input_sync() @@ -125,38 +123,38 @@ This doesn't seem important in the one button case, but is quite important for for example mouse movement, where you don't want the X and Y values to be interpreted separately, because that'd result in a different movement. -1.2 dev->open() and dev->close() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +dev->open() and dev->close() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In case the driver has to repeatedly poll the device, because it doesn't have an interrupt coming from it and the polling is too expensive to be done all the time, or if the device uses a valuable resource (eg. interrupt), it can use the open and close callback to know when it can stop polling or release the interrupt and when it must resume polling or grab the interrupt -again. To do that, we would add this to our example driver: - -static int button_open(struct input_dev *dev) -{ - if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { - printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); - return -EBUSY; - } - - return 0; -} - -static void button_close(struct input_dev *dev) -{ - free_irq(IRQ_AMIGA_VERTB, button_interrupt); -} - -static int __init button_init(void) -{ - ... - button_dev->open = button_open; - button_dev->close = button_close; - ... -} +again. To do that, we would add this to our example driver:: + + static int button_open(struct input_dev *dev) + { + if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { + printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); + return -EBUSY; + } + + return 0; + } + + static void button_close(struct input_dev *dev) + { + free_irq(IRQ_AMIGA_VERTB, button_interrupt); + } + + static int __init button_init(void) + { + ... + button_dev->open = button_open; + button_dev->close = button_close; + ... + } Note that input core keeps track of number of users for the device and makes sure that dev->open() is called only when the first user connects @@ -166,16 +164,16 @@ disconnects. Calls to both callbacks are serialized. The open() callback should return a 0 in case of success or any nonzero value in case of failure. The close() callback (which is void) must always succeed. -1.3 Basic event types -~~~~~~~~~~~~~~~~~~~~~ +Basic event types +~~~~~~~~~~~~~~~~~ The most simple event type is EV_KEY, which is used for keys and buttons. -It's reported to the input system via: +It's reported to the input system via:: input_report_key(struct input_dev *dev, int code, int value) -See linux/input.h for the allowable values of code (from 0 to KEY_MAX). -Value is interpreted as a truth value, ie any nonzero value means key +See uapi/linux/input-event-codes.h for the allowable values of code (from 0 to +KEY_MAX). Value is interpreted as a truth value, ie any nonzero value means key pressed, zero value means key released. The input code generates events only in case the value is different from before. @@ -188,7 +186,7 @@ events are namely for joysticks and digitizers - devices that do work in an absolute coordinate systems. Having the device report EV_REL buttons is as simple as with EV_KEY, simply -set the corresponding bits and call the +set the corresponding bits and call the:: input_report_rel(struct input_dev *dev, int code, int value) @@ -197,14 +195,14 @@ function. Events are generated only for nonzero value. However EV_ABS requires a little special care. Before calling input_register_device, you have to fill additional fields in the input_dev struct for each absolute axis your device has. If our button device had also -the ABS_X axis: +the ABS_X axis:: button_dev.absmin[ABS_X] = 0; button_dev.absmax[ABS_X] = 255; button_dev.absfuzz[ABS_X] = 4; button_dev.absflat[ABS_X] = 8; -Or, you can just say: +Or, you can just say:: input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 8); @@ -218,18 +216,18 @@ If you don't need absfuzz and absflat, you can set them to zero, which mean that the thing is precise and always returns to exactly the center position (if it has any). -1.4 BITS_TO_LONGS(), BIT_WORD(), BIT_MASK() -~~~~~~~~~~~~~~~~~~~~~~~~~~ +BITS_TO_LONGS(), BIT_WORD(), BIT_MASK() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These three macros from bitops.h help some bitfield computations: +These three macros from bitops.h help some bitfield computations:: BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for x bits BIT_WORD(x) - returns the index in the array in longs for bit x BIT_MASK(x) - returns the index in a long for bit x -1.5 The id* and name fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The id* and name fields +~~~~~~~~~~~~~~~~~~~~~~~ The dev->name should be set before registering the input device by the input device driver. It's a string like 'Generic button device' containing a @@ -245,8 +243,8 @@ driver. The id and name fields can be passed to userland via the evdev interface. -1.6 The keycode, keycodemax, keycodesize fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The keycode, keycodemax, keycodesize fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These three fields should be used by input devices that have dense keymaps. The keycode is an array used to map from scancodes to input system keycodes. @@ -259,14 +257,15 @@ When a device has all 3 aforementioned fields filled in, the driver may rely on kernel's default implementation of setting and querying keycode mappings. -1.7 dev->getkeycode() and dev->setkeycode() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +dev->getkeycode() and dev->setkeycode() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + getkeycode() and setkeycode() callbacks allow drivers to override default keycode/keycodesize/keycodemax mapping mechanism provided by input core and implement sparse keycode maps. -1.8 Key autorepeat -~~~~~~~~~~~~~~~~~~ +Key autorepeat +~~~~~~~~~~~~~~ ... is simple. It is handled by the input.c module. Hardware autorepeat is not used, because it's not present in many devices and even where it is @@ -274,29 +273,30 @@ present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable autorepeat for your device, just set EV_REP in dev->evbit. All will be handled by the input system. -1.9 Other event types, handling output events -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Other event types, handling output events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The other event types up to now are: -EV_LED - used for the keyboard LEDs. -EV_SND - used for keyboard beeps. +- EV_LED - used for the keyboard LEDs. +- EV_SND - used for keyboard beeps. They are very similar to for example key events, but they go in the other direction - from the system to the input device driver. If your input device driver can handle these events, it has to set the respective bits in evbit, -*and* also the callback routine: - - button_dev->event = button_event; - -int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); -{ - if (type == EV_SND && code == SND_BELL) { - outb(value, BUTTON_BELL); - return 0; - } - return -1; -} +*and* also the callback routine:: + + button_dev->event = button_event; + + int button_event(struct input_dev *dev, unsigned int type, + unsigned int code, int value) + { + if (type == EV_SND && code == SND_BELL) { + outb(value, BUTTON_BELL); + return 0; + } + return -1; + } This callback routine can be called from an interrupt or a BH (although that isn't a rule), and thus must not sleep, and must not take too long to finish. diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst new file mode 100644 index 000000000000..3b3a22975106 --- /dev/null +++ b/Documentation/input/input.rst @@ -0,0 +1,281 @@ +.. include:: <isonum.txt> + +============ +Introduction +============ + +:Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE + +Architecture +============ + +Input subsystem a collection of drivers that is designed to support +all input devices under Linux. Most of the drivers reside in +drivers/input, although quite a few live in drivers/hid and +drivers/platform. + +The core of the input subsystem is the input module, which must be +loaded before any other of the input modules - it serves as a way of +communication between two groups of modules: + +Device drivers +-------------- + +These modules talk to the hardware (for example via USB), and provide +events (keystrokes, mouse movements) to the input module. + +Event handlers +-------------- + +These modules get events from input core and pass them where needed +via various interfaces - keystrokes to the kernel, mouse movements via +a simulated PS/2 interface to GPM and X, and so on. + +Simple Usage +============ + +For the most usual configuration, with one USB mouse and one USB keyboard, +you'll have to load the following modules (or have them built in to the +kernel):: + + input + mousedev + usbcore + uhci_hcd or ohci_hcd or ehci_hcd + usbhid + hid_generic + +After this, the USB keyboard will work straight away, and the USB mouse +will be available as a character device on major 13, minor 63:: + + crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice + +This device usually created automatically by the system. The commands +to create it by hand are:: + + cd /dev + mkdir input + mknod input/mice c 13 63 + +After that you have to point GPM (the textmode mouse cut&paste tool) and +XFree to this device to use it - GPM should be called like:: + + gpm -t ps2 -m /dev/input/mice + +And in X:: + + Section "Pointer" + Protocol "ImPS/2" + Device "/dev/input/mice" + ZAxisMapping 4 5 + EndSection + +When you do all of the above, you can use your USB mouse and keyboard. + +Detailed Description +==================== + +Event handlers +-------------- + +Event handlers distribute the events from the devices to userspace and +in-kernel consumers, as needed. + +evdev +~~~~~ + +``evdev`` is the generic input event interface. It passes the events +generated in the kernel straight to the program, with timestamps. The +event codes are the same on all architectures and are hardware +independent. + +This is the preferred interface for userspace to consume user +input, and all clients are encouraged to use it. + +See :ref:`event-interface` for notes on API. + +The devices are in /dev/input:: + + crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0 + crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1 + crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2 + crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3 + ... + +There are two ranges of minors: 64 through 95 is the static legacy +range. If there are more than 32 input devices in a system, additional +evdev nodes are created with minors starting with 256. + +keyboard +~~~~~~~~ + +``keyboard`` is in-kernel input handler ad is a part of VT code. It +consumes keyboard keystrokes and handles user input for VT consoles. + +mousedev +~~~~~~~~ + +``mousedev`` is a hack to make legacy programs that use mouse input +work. It takes events from either mice or digitizers/tablets and makes +a PS/2-style (a la /dev/psaux) mouse device available to the +userland. + +Mousedev devices in /dev/input (as shown above) are:: + + crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0 + crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1 + crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2 + crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3 + ... + ... + crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30 + crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice + +Each ``mouse`` device is assigned to a single mouse or digitizer, except +the last one - ``mice``. This single character device is shared by all +mice and digitizers, and even if none are connected, the device is +present. This is useful for hotplugging USB mice, so that older programs +that do not handle hotplug can open the device even when no mice are +present. + +CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are +the size of your screen (in pixels) in XFree86. This is needed if you +want to use your digitizer in X, because its movement is sent to X +via a virtual PS/2 mouse and thus needs to be scaled +accordingly. These values won't be used if you use a mouse only. + +Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or +ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the +program reading the data wishes. You can set GPM and X to any of +these. You'll need ImPS/2 if you want to make use of a wheel on a USB +mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. + +joydev +~~~~~~ + +``joydev`` implements v0.x and v1.x Linux joystick API. See +:ref:`joystick-api` for details. + +As soon as any joystick is connected, it can be accessed in /dev/input on:: + + crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0 + crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1 + crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2 + crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3 + ... + +And so on up to js31 in legacy range, and additional nodes with minors +above 256 if there are more joystick devices. + +Device drivers +-------------- + +Device drivers are the modules that generate events. + +hid-generic +~~~~~~~~~~~ + +``hid-generic`` is one of the largest and most complex driver of the +whole suite. It handles all HID devices, and because there is a very +wide variety of them, and because the USB HID specification isn't +simple, it needs to be this big. + +Currently, it handles USB mice, joysticks, gamepads, steering wheels +keyboards, trackballs and digitizers. + +However, USB uses HID also for monitor controls, speaker controls, UPSs, +LCDs and many other purposes. + +The monitor and speaker controls should be easy to add to the hid/input +interface, but for the UPSs and LCDs it doesn't make much sense. For this, +the hiddev interface was designed. See Documentation/hid/hiddev.txt +for more information about it. + +The usage of the usbhid module is very simple, it takes no parameters, +detects everything automatically and when a HID device is inserted, it +detects it appropriately. + +However, because the devices vary wildly, you might happen to have a +device that doesn't work well. In that case #define DEBUG at the beginning +of hid-core.c and send me the syslog traces. + +usbmouse +~~~~~~~~ + +For embedded systems, for mice with broken HID descriptors and just any +other use when the big usbhid wouldn't be a good choice, there is the +usbmouse driver. It handles USB mice only. It uses a simpler HIDBP +protocol. This also means the mice must support this simpler protocol. Not +all do. If you don't have any strong reason to use this module, use usbhid +instead. + +usbkbd +~~~~~~ + +Much like usbmouse, this module talks to keyboards with a simplified +HIDBP protocol. It's smaller, but doesn't support any extra special keys. +Use usbhid instead if there isn't any special reason to use this. + +psmouse +~~~~~~~ + +This is driver for all flavors of pointing devices using PS/2 +protocol, including Synaptics and ALPS touchpads, Intellimouse +Explorer devices, Logitech PS/2 mice and so on. + +atkbd +~~~~~ + +This is driver for PS/2 (AT) keyboards. + +iforce +~~~~~~ + +A driver for I-Force joysticks and wheels, both over USB and RS232. +It includes Force Feedback support now, even though Immersion +Corp. considers the protocol a trade secret and won't disclose a word +about it. + +Verifying if it works +===================== + +Typing a couple keys on the keyboard should be enough to check that +a keyboard works and is correctly connected to the kernel keyboard +driver. + +Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse +is also emulated; characters should appear if you move it. + +You can test the joystick emulation with the ``jstest`` utility, +available in the joystick package (see :ref:`joystick-doc`). + +You can test the event devices with the ``evtest`` utility. + +.. _event-interface: + +Event interface +=============== + +You can use blocking and nonblocking reads, and also select() on the +/dev/input/eventX devices, and you'll always get a whole number of input +events on a read. Their layout is:: + + struct input_event { + struct timeval time; + unsigned short type; + unsigned short code; + unsigned int value; + }; + +``time`` is the timestamp, it returns the time at which the event happened. +Type is for example EV_REL for relative moment, EV_KEY for a keypress or +release. More types are defined in include/uapi/linux/input-event-codes.h. + +``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete +list is in include/uapi/linux/input-event-codes.h. + +``value`` is the value the event carries. Either a relative change for +EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for +release, 1 for keypress and 2 for autorepeat. + +See :ref:`input-event-codes` for more information about various even codes. diff --git a/Documentation/input/input.txt b/Documentation/input/input.txt deleted file mode 100644 index 7ebce100fe90..000000000000 --- a/Documentation/input/input.txt +++ /dev/null @@ -1,290 +0,0 @@ - Linux Input drivers v1.0 - (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE ----------------------------------------------------------------------------- - -0. Disclaimer -~~~~~~~~~~~~~ - This program is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the Free -Software Foundation; either version 2 of the License, or (at your option) -any later version. - - This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for -more details. - - You should have received a copy of the GNU General Public License along -with this program; if not, write to the Free Software Foundation, Inc., 59 -Temple Place, Suite 330, Boston, MA 02111-1307 USA - - Should you need to contact me, the author, you can do so either by e-mail -- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik, -Simunkova 1594, Prague 8, 182 00 Czech Republic - - For your convenience, the GNU General Public License version 2 is included -in the package: See the file COPYING. - -1. Introduction -~~~~~~~~~~~~~~~ - This is a collection of drivers that is designed to support all input -devices under Linux. While it is currently used only on for USB input -devices, future use (say 2.5/2.6) is expected to expand to replace -most of the existing input system, which is why it lives in -drivers/input/ instead of drivers/usb/. - - The centre of the input drivers is the input module, which must be -loaded before any other of the input modules - it serves as a way of -communication between two groups of modules: - -1.1 Device drivers -~~~~~~~~~~~~~~~~~~ - These modules talk to the hardware (for example via USB), and provide -events (keystrokes, mouse movements) to the input module. - -1.2 Event handlers -~~~~~~~~~~~~~~~~~~ - These modules get events from input and pass them where needed via -various interfaces - keystrokes to the kernel, mouse movements via a -simulated PS/2 interface to GPM and X and so on. - -2. Simple Usage -~~~~~~~~~~~~~~~ - For the most usual configuration, with one USB mouse and one USB keyboard, -you'll have to load the following modules (or have them built in to the -kernel): - - input - mousedev - keybdev - usbcore - uhci_hcd or ohci_hcd or ehci_hcd - usbhid - - After this, the USB keyboard will work straight away, and the USB mouse -will be available as a character device on major 13, minor 63: - - crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice - - This device has to be created. - The commands to create it by hand are: - - cd /dev - mkdir input - mknod input/mice c 13 63 - - After that you have to point GPM (the textmode mouse cut&paste tool) and -XFree to this device to use it - GPM should be called like: - - gpm -t ps2 -m /dev/input/mice - - And in X: - - Section "Pointer" - Protocol "ImPS/2" - Device "/dev/input/mice" - ZAxisMapping 4 5 - EndSection - - When you do all of the above, you can use your USB mouse and keyboard. - -3. Detailed Description -~~~~~~~~~~~~~~~~~~~~~~~ -3.1 Device drivers -~~~~~~~~~~~~~~~~~~ - Device drivers are the modules that generate events. The events are -however not useful without being handled, so you also will need to use some -of the modules from section 3.2. - -3.1.1 usbhid -~~~~~~~~~~~~ - usbhid is the largest and most complex driver of the whole suite. It -handles all HID devices, and because there is a very wide variety of them, -and because the USB HID specification isn't simple, it needs to be this big. - - Currently, it handles USB mice, joysticks, gamepads, steering wheels -keyboards, trackballs and digitizers. - - However, USB uses HID also for monitor controls, speaker controls, UPSs, -LCDs and many other purposes. - - The monitor and speaker controls should be easy to add to the hid/input -interface, but for the UPSs and LCDs it doesn't make much sense. For this, -the hiddev interface was designed. See Documentation/hid/hiddev.txt -for more information about it. - - The usage of the usbhid module is very simple, it takes no parameters, -detects everything automatically and when a HID device is inserted, it -detects it appropriately. - - However, because the devices vary wildly, you might happen to have a -device that doesn't work well. In that case #define DEBUG at the beginning -of hid-core.c and send me the syslog traces. - -3.1.2 usbmouse -~~~~~~~~~~~~~~ - For embedded systems, for mice with broken HID descriptors and just any -other use when the big usbhid wouldn't be a good choice, there is the -usbmouse driver. It handles USB mice only. It uses a simpler HIDBP -protocol. This also means the mice must support this simpler protocol. Not -all do. If you don't have any strong reason to use this module, use usbhid -instead. - -3.1.3 usbkbd -~~~~~~~~~~~~ - Much like usbmouse, this module talks to keyboards with a simplified -HIDBP protocol. It's smaller, but doesn't support any extra special keys. -Use usbhid instead if there isn't any special reason to use this. - -3.1.4 wacom -~~~~~~~~~~~ - This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom -PenPartner, that one is handled by the HID driver. Although the Intuos and -Graphire tablets claim that they are HID tablets as well, they are not and -thus need this specific driver. - -3.1.5 iforce -~~~~~~~~~~~~ - A driver for I-Force joysticks and wheels, both over USB and RS232. -It includes ForceFeedback support now, even though Immersion -Corp. considers the protocol a trade secret and won't disclose a word -about it. - -3.2 Event handlers -~~~~~~~~~~~~~~~~~~ - Event handlers distribute the events from the devices to userland and -kernel, as needed. - -3.2.1 keybdev -~~~~~~~~~~~~~ - keybdev is currently a rather ugly hack that translates the input -events into architecture-specific keyboard raw mode (Xlated AT Set2 on -x86), and passes them into the handle_scancode function of the -keyboard.c module. This works well enough on all architectures that -keybdev can generate rawmode on, other architectures can be added to -it. - - The right way would be to pass the events to keyboard.c directly, -best if keyboard.c would itself be an event handler. This is done in -the input patch, available on the webpage mentioned below. - -3.2.2 mousedev -~~~~~~~~~~~~~~ - mousedev is also a hack to make programs that use mouse input -work. It takes events from either mice or digitizers/tablets and makes -a PS/2-style (a la /dev/psaux) mouse device available to the -userland. Ideally, the programs could use a more reasonable interface, -for example evdev - - Mousedev devices in /dev/input (as shown above) are: - - crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0 - crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1 - crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2 - crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3 - ... - ... - crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30 - crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice - -Each 'mouse' device is assigned to a single mouse or digitizer, except -the last one - 'mice'. This single character device is shared by all -mice and digitizers, and even if none are connected, the device is -present. This is useful for hotplugging USB mice, so that programs -can open the device even when no mice are present. - - CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are -the size of your screen (in pixels) in XFree86. This is needed if you -want to use your digitizer in X, because its movement is sent to X -via a virtual PS/2 mouse and thus needs to be scaled -accordingly. These values won't be used if you use a mouse only. - - Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or -ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the -program reading the data wishes. You can set GPM and X to any of -these. You'll need ImPS/2 if you want to make use of a wheel on a USB -mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. - -3.2.3 joydev -~~~~~~~~~~~~ - Joydev implements v0.x and v1.x Linux joystick api, much like -drivers/char/joystick/joystick.c used to in earlier versions. See -joystick-api.txt in the Documentation subdirectory for details. As -soon as any joystick is connected, it can be accessed in /dev/input -on: - - crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0 - crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1 - crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2 - crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3 - ... - -And so on up to js31. - -3.2.4 evdev -~~~~~~~~~~~ - evdev is the generic input event interface. It passes the events -generated in the kernel straight to the program, with timestamps. The -API is still evolving, but should be usable now. It's described in -section 5. - - This should be the way for GPM and X to get keyboard and mouse -events. It allows for multihead in X without any specific multihead -kernel support. The event codes are the same on all architectures and -are hardware independent. - - The devices are in /dev/input: - - crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0 - crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1 - crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2 - crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3 - ... - -And so on up to event31. - -4. Verifying if it works -~~~~~~~~~~~~~~~~~~~~~~~~ - Typing a couple keys on the keyboard should be enough to check that -a USB keyboard works and is correctly connected to the kernel keyboard -driver. - - Doing a "cat /dev/input/mouse0" (c, 13, 32) will verify that a mouse -is also emulated; characters should appear if you move it. - - You can test the joystick emulation with the 'jstest' utility, -available in the joystick package (see Documentation/input/joystick.txt). - - You can test the event devices with the 'evtest' utility available -in the LinuxConsole project CVS archive (see the URL below). - -5. Event interface -~~~~~~~~~~~~~~~~~~ - Should you want to add event device support into any application (X, gpm, -svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I -can. Here goes a description of the current state of things, which is going -to be extended, but not changed incompatibly as time goes: - - You can use blocking and nonblocking reads, also select() on the -/dev/input/eventX devices, and you'll always get a whole number of input -events on a read. Their layout is: - -struct input_event { - struct timeval time; - unsigned short type; - unsigned short code; - unsigned int value; -}; - - 'time' is the timestamp, it returns the time at which the event happened. -Type is for example EV_REL for relative moment, EV_KEY for a keypress or -release. More types are defined in include/uapi/linux/input-event-codes.h. - - 'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete -list is in include/uapi/linux/input-event-codes.h. - - 'value' is the value the event carries. Either a relative change for -EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for -release, 1 for keypress and 2 for autorepeat. - diff --git a/Documentation/input/input_kapi.rst b/Documentation/input/input_kapi.rst new file mode 100644 index 000000000000..41f1b7e6b78e --- /dev/null +++ b/Documentation/input/input_kapi.rst @@ -0,0 +1,17 @@ +.. include:: <isonum.txt> + +################################ +Linux Input Subsystem kernel API +################################ + +.. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 2 + :numbered: + + input-programming + gameport-programming + notifier diff --git a/Documentation/input/input_uapi.rst b/Documentation/input/input_uapi.rst new file mode 100644 index 000000000000..4a0391609327 --- /dev/null +++ b/Documentation/input/input_uapi.rst @@ -0,0 +1,22 @@ +.. include:: <isonum.txt> + +################################### +Linux Input Subsystem userspace API +################################### + +.. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 2 + :numbered: + + input + event-codes + multi-touch-protocol + gamepad + ff + joydev/index + uinput + userio diff --git a/Documentation/input/interactive.fig b/Documentation/input/interactive.fig deleted file mode 100644 index 1e7de387723a..000000000000 --- a/Documentation/input/interactive.fig +++ /dev/null @@ -1,42 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -2 1 0 2 0 7 50 0 -1 6.000 0 0 -1 0 0 6 - 1200 3600 1800 3600 2400 4800 3000 4800 4200 5700 4800 5700 -2 2 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 - 1200 3150 4800 3150 4800 6300 1200 6300 1200 3150 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 1200 4800 4800 4800 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 - 2400 4800 2400 6525 1950 7125 1950 7800 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 - 3000 4800 3000 6525 3600 7125 3600 7800 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3 - 0 0 1.00 60.00 120.00 - 3825 5400 4125 5100 5400 5100 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3 - 0 0 1.00 60.00 120.00 - 2100 4200 2400 3900 5400 3900 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 4800 5700 5400 5700 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 1800 3600 5400 3600 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 1 3 - 0 0 1.00 60.00 120.00 - 2700 4800 2700 4425 5400 4425 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 1950 7800 3600 7800 -4 1 0 50 0 0 12 0.0000 4 135 810 2775 7725 Dead band\001 -4 0 0 50 0 0 12 0.0000 4 180 1155 5400 5700 right saturation\001 -4 0 0 50 0 0 12 0.0000 4 135 1065 5400 3600 left saturation\001 -4 0 0 50 0 0 12 0.0000 4 180 2505 5400 3900 left coeff ( positive in that case )\001 -4 0 0 50 0 0 12 0.0000 4 180 2640 5475 5100 right coeff ( negative in that case )\001 -4 0 0 50 0 0 12 0.0000 4 105 480 5400 4425 center\001 diff --git a/Documentation/input/interactive.svg b/Documentation/input/interactive.svg new file mode 100644 index 000000000000..a3513709a09b --- /dev/null +++ b/Documentation/input/interactive.svg @@ -0,0 +1,24 @@ +<svg width="5.75in" height="3.90in" version="1.1" viewBox="1178 3138 6779.9424 4671.3427" xmlns="http://www.w3.org/2000/svg"> + <polyline transform="translate(-18.5,-16.294)" points="1200 3600 1800 3600 2400 4800 3e3 4800 4200 5700 4800 5700" fill="none" stroke="#000" stroke-width="15"/> + <rect x="1181.5" y="3133.7" width="3600" height="3150" rx="0" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="1200 4800 4800 4800" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="2400 4800 2400 6525 1950 7125 1950 7800" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="3e3 4800 3e3 6525 3600 7125 3600 7800" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="3837 5389 4125 5100 5400 5100" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="3889 5292 3826 5398 3932 5334" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="2112 4189 2400 3900 5400 3900" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="2164 4092 2101 4198 2207 4134" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="4800 5700 5400 5700" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="1800 3600 5400 3600" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="2700 4784 2700 4425 5400 4425" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="2670 4678 2700 4798 2730 4678" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="1967 7800 3583 7800" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="3478 7830 3598 7800 3478 7770" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-18.5,-16.294)" points="2072 7770 1952 7800 2072 7830" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <text x="2775" y="7725" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Dead band</text> + <text x="5400" y="5700" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">right saturation</text> + <text x="5400" y="3600" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">left saturation</text> + <text x="5400" y="3900" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">left coeff ( positive in that case )</text> + <text x="5475" y="5100" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">right coeff ( negative in that case )</text> + <text x="5400" y="4425" font-family="sans-serif" font-size="144px" stroke="#000000" stroke-width=".025in" xml:space="preserve">center</text> +</svg> diff --git a/Documentation/input/joydev/index.rst b/Documentation/input/joydev/index.rst new file mode 100644 index 000000000000..8d9666c7561c --- /dev/null +++ b/Documentation/input/joydev/index.rst @@ -0,0 +1,18 @@ +.. include:: <isonum.txt> + +====================== +Linux Joystick support +====================== + +:Copyright: |copy| 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE + +.. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 3 + :numbered: + + joystick + joystick-api diff --git a/Documentation/input/joystick-api.txt b/Documentation/input/joydev/joystick-api.rst index 943b18eac918..95803e2e8cd0 100644 --- a/Documentation/input/joystick-api.txt +++ b/Documentation/input/joydev/joystick-api.rst @@ -1,31 +1,54 @@ - Joystick API Documentation -*-Text-*- +.. _joystick-api: - Ragnar Hojland Espinosa - <ragnar@macula.net> +===================== +Programming Interface +===================== - 7 Aug 1998 +:Author: Ragnar Hojland Espinosa <ragnar@macula.net> - 7 Aug 1998 -1. Initialization -~~~~~~~~~~~~~~~~~ +Introduction +============ + +.. important:: + This document describes legacy ``js`` interface. Newer clients are + encouraged to switch to the generic event (``evdev``) interface. + +The 1.0 driver uses a new, event based approach to the joystick driver. +Instead of the user program polling for the joystick values, the joystick +driver now reports only any changes of its state. See joystick-api.txt, +joystick.h and jstest.c included in the joystick package for more +information. The joystick device can be used in either blocking or +nonblocking mode, and supports select() calls. + +For backward compatibility the old (v0.x) interface is still included. +Any call to the joystick driver using the old interface will return values +that are compatible to the old interface. This interface is still limited +to 2 axes, and applications using it usually decode only 2 buttons, although +the driver provides up to 32. + +Initialization +============== Open the joystick device following the usual semantics (that is, with open). Since the driver now reports events instead of polling for changes, immediately after the open it will issue a series of synthetic events -(JS_EVENT_INIT) that you can read to check the initial state of the +(JS_EVENT_INIT) that you can read to obtain the initial state of the joystick. -By default, the device is opened in blocking mode. +By default, the device is opened in blocking mode:: int fd = open ("/dev/input/js0", O_RDONLY); -2. Event Reading -~~~~~~~~~~~~~~~~ +Event Reading +============= + +:: struct js_event e; read (fd, &e, sizeof(e)); -where js_event is defined as +where js_event is defined as:: struct js_event { __u32 time; /* event timestamp in milliseconds */ @@ -38,10 +61,10 @@ If the read is successful, it will return sizeof(e), unless you wanted to read more than one event per read as described in section 3.1. -2.1 js_event.type -~~~~~~~~~~~~~~~~~ +js_event.type +------------- -The possible values of ``type'' are +The possible values of ``type`` are:: #define JS_EVENT_BUTTON 0x01 /* button pressed/released */ #define JS_EVENT_AXIS 0x02 /* joystick moved */ @@ -49,47 +72,50 @@ The possible values of ``type'' are As mentioned above, the driver will issue synthetic JS_EVENT_INIT ORed events on open. That is, if it's issuing a INIT BUTTON event, the -current type value will be +current type value will be:: int type = JS_EVENT_BUTTON | JS_EVENT_INIT; /* 0x81 */ If you choose not to differentiate between synthetic or real events -you can turn off the JS_EVENT_INIT bits +you can turn off the JS_EVENT_INIT bits:: type &= ~JS_EVENT_INIT; /* 0x01 */ -2.2 js_event.number -~~~~~~~~~~~~~~~~~~~ +js_event.number +--------------- -The values of ``number'' correspond to the axis or button that +The values of ``number`` correspond to the axis or button that generated the event. Note that they carry separate numeration (that is, you have both an axis 0 and a button 0). Generally, - number + =============== ======= + Axis number + =============== ======= 1st Axis X 0 1st Axis Y 1 2nd Axis X 2 2nd Axis Y 3 ...and so on + =============== ======= Hats vary from one joystick type to another. Some can be moved in 8 directions, some only in 4, The driver, however, always reports a hat as two independent axis, even if the hardware doesn't allow independent movement. -2.3 js_event.value -~~~~~~~~~~~~~~~~~~ +js_event.value +-------------- -For an axis, ``value'' is a signed integer between -32767 and +32767 +For an axis, ``value`` is a signed integer between -32767 and +32767 representing the position of the joystick along that axis. If you -don't read a 0 when the joystick is `dead', or if it doesn't span the +don't read a 0 when the joystick is ``dead``, or if it doesn't span the full range, you should recalibrate it (with, for example, jscal). -For a button, ``value'' for a press button event is 1 and for a release +For a button, ``value`` for a press button event is 1 and for a release button event is 0. -Though this +Though this:: if (js_event.type == JS_EVENT_BUTTON) { buttons_state ^= (1 << js_event.number); @@ -97,6 +123,8 @@ Though this may work well if you handle JS_EVENT_INIT events separately, +:: + if ((js_event.type & ~JS_EVENT_INIT) == JS_EVENT_BUTTON) { if (js_event.value) buttons_state |= (1 << js_event.number); @@ -109,17 +137,17 @@ have to write a separate handler for JS_EVENT_INIT events in the first snippet, this ends up being shorter. -2.4 js_event.time -~~~~~~~~~~~~~~~~~ +js_event.time +------------- -The time an event was generated is stored in ``js_event.time''. It's a time +The time an event was generated is stored in ``js_event.time``. It's a time in milliseconds since ... well, since sometime in the past. This eases the task of detecting double clicks, figuring out if movement of axis and button presses happened at the same time, and similar. -3. Reading -~~~~~~~~~~ +Reading +======= If you open the device in blocking mode, a read will block (that is, wait) forever until an event is generated and effectively read. There @@ -133,8 +161,8 @@ admittedly, a long time;) b) open the device in non-blocking mode (O_NONBLOCK) -3.1 O_NONBLOCK -~~~~~~~~~~~~~~ +O_NONBLOCK +---------- If read returns -1 when reading in O_NONBLOCK mode, this isn't necessarily a "real" error (check errno(3)); it can just mean there @@ -143,6 +171,8 @@ all events on the queue (that is, until you get a -1). For example, +:: + while (1) { while (read (fd, &e, sizeof(e)) > 0) { process_event (e); @@ -171,14 +201,17 @@ the driver will switch to startup mode and next time you read it, synthetic events (JS_EVENT_INIT) will be generated to inform you of the actual state of the joystick. -[As for version 1.2.8, the queue is circular and able to hold 64 + +.. note:: + + As of version 1.2.8, the queue is circular and able to hold 64 events. You can increment this size bumping up JS_BUFF_SIZE in - joystick.h and recompiling the driver.] + joystick.h and recompiling the driver. In the above code, you might as well want to read more than one event at a time using the typical read(2) functionality. For that, you would -replace the read above with something like +replace the read above with something like:: struct js_event mybuffer[0xff]; int i = read (fd, mybuffer, sizeof(mybuffer)); @@ -189,10 +222,10 @@ sizeof(js_event) Again, if the buffer was full, it's a good idea to process the events and keep reading it until you empty the driver queue. -4. IOCTLs -~~~~~~~~~ +IOCTLs +====== -The joystick driver defines the following ioctl(2) operations. +The joystick driver defines the following ioctl(2) operations:: /* function 3rd arg */ #define JSIOCGAXES /* get number of axes char */ @@ -202,31 +235,31 @@ The joystick driver defines the following ioctl(2) operations. #define JSIOCSCORR /* set correction values &js_corr */ #define JSIOCGCORR /* get correction values &js_corr */ -For example, to read the number of axes +For example, to read the number of axes:: char number_of_axes; ioctl (fd, JSIOCGAXES, &number_of_axes); -4.1 JSIOGCVERSION -~~~~~~~~~~~~~~~~~ +JSIOGCVERSION +------------- JSIOGCVERSION is a good way to check in run-time whether the running driver is 1.0+ and supports the event interface. If it is not, the IOCTL will fail. For a compile-time decision, you can test the -JS_VERSION symbol +JS_VERSION symbol:: #ifdef JS_VERSION #if JS_VERSION > 0xsomething -4.2 JSIOCGNAME -~~~~~~~~~~~~~~ +JSIOCGNAME +---------- JSIOCGNAME(len) allows you to get the name string of the joystick - the same as is being printed at boot time. The 'len' argument is the length of the buffer provided by the application asking for the name. It is used to avoid -possible overrun should the name be too long. +possible overrun should the name be too long:: char name[128]; if (ioctl(fd, JSIOCGNAME(sizeof(name)), name) < 0) @@ -234,8 +267,8 @@ possible overrun should the name be too long. printf("Name: %s\n", name); -4.3 JSIOC[SG]CORR -~~~~~~~~~~~~~~~~~ +JSIOC[SG]CORR +------------- For usage on JSIOC[SG]CORR I suggest you to look into jscal.c They are not needed in a normal program, only in joystick calibration software @@ -246,7 +279,7 @@ warning in following releases of the driver. Both JSIOCSCORR and JSIOCGCORR expect &js_corr to be able to hold information for all axis. That is, struct js_corr corr[MAX_AXIS]; -struct js_corr is defined as +struct js_corr is defined as:: struct js_corr { __s32 coef[8]; @@ -254,17 +287,17 @@ struct js_corr is defined as __u16 type; }; -and ``type'' +and ``type``:: #define JS_CORR_NONE 0x00 /* returns raw values */ #define JS_CORR_BROKEN 0x01 /* broken line */ -5. Backward compatibility -~~~~~~~~~~~~~~~~~~~~~~~~~ +Backward compatibility +====================== The 0.x joystick driver API is quite limited and its usage is deprecated. -The driver offers backward compatibility, though. Here's a quick summary: +The driver offers backward compatibility, though. Here's a quick summary:: struct JS_DATA_TYPE js; while (1) { @@ -275,7 +308,7 @@ The driver offers backward compatibility, though. Here's a quick summary: } As you can figure out from the example, the read returns immediately, -with the actual state of the joystick. +with the actual state of the joystick:: struct JS_DATA_TYPE { int buttons; /* immediate button state */ @@ -283,12 +316,14 @@ with the actual state of the joystick. int y; /* immediate y axis value */ }; -and JS_RETURN is defined as +and JS_RETURN is defined as:: #define JS_RETURN sizeof(struct JS_DATA_TYPE) To test the state of the buttons, +:: + first_button_state = js.buttons & 1; second_button_state = js.buttons & 2; @@ -302,13 +337,12 @@ called Multisystem joysticks in this driver), under /dev/djsX. This driver doesn't try to be compatible with that interface. -6. Final Notes -~~~~~~~~~~~~~~ +Final Notes +=========== -____/| Comments, additions, and specially corrections are welcome. -\ o.O| Documentation valid for at least version 1.2.8 of the joystick - =(_)= driver and as usual, the ultimate source for documentation is - U to "Use The Source Luke" or, at your convenience, Vojtech ;) +:: - - Ragnar -EOF + ____/| Comments, additions, and specially corrections are welcome. + \ o.O| Documentation valid for at least version 1.2.8 of the joystick + =(_)= driver and as usual, the ultimate source for documentation is + U to "Use The Source Luke" or, at your convenience, Vojtech ;) diff --git a/Documentation/input/joydev/joystick.rst b/Documentation/input/joydev/joystick.rst new file mode 100644 index 000000000000..9746fd76cc58 --- /dev/null +++ b/Documentation/input/joydev/joystick.rst @@ -0,0 +1,585 @@ +.. include:: <isonum.txt> + +.. _joystick-doc: + +Introduction +============ + +The joystick driver for Linux provides support for a variety of joysticks +and similar devices. It is based on a larger project aiming to support all +input devices in Linux. + +The mailing list for the project is: + + linux-input@vger.kernel.org + +send "subscribe linux-input" to majordomo@vger.kernel.org to subscribe to it. + +Usage +===== + +For basic usage you just choose the right options in kernel config and +you should be set. + +Utilities +--------- + +For testing and other purposes (for example serial devices), there is a set +of utilities, such as ``jstest``, ``jscal``, and ``evtest``, +usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on. + +``inputattach`` utility is required if your joystick is connected to a +serial port. + +Device nodes +------------ + +For applications to be able to use the joysticks, device nodes should be +created in /dev. Normally it is done automatically by the system, but +it can also be done by hand:: + + cd /dev + rm js* + mkdir input + mknod input/js0 c 13 0 + mknod input/js1 c 13 1 + mknod input/js2 c 13 2 + mknod input/js3 c 13 3 + ln -s input/js0 js0 + ln -s input/js1 js1 + ln -s input/js2 js2 + ln -s input/js3 js3 + +For testing with inpututils it's also convenient to create these:: + + mknod input/event0 c 13 64 + mknod input/event1 c 13 65 + mknod input/event2 c 13 66 + mknod input/event3 c 13 67 + +Modules needed +-------------- + +For all joystick drivers to function, you'll need the userland interface +module in kernel, either loaded or compiled in:: + + modprobe joydev + +For gameport joysticks, you'll have to load the gameport driver as well:: + + modprobe ns558 + +And for serial port joysticks, you'll need the serial input line +discipline module loaded and the inputattach utility started:: + + modprobe serport + inputattach -xxx /dev/tts/X & + +In addition to that, you'll need the joystick driver module itself, most +usually you'll have an analog joystick:: + + modprobe analog + +For automatic module loading, something like this might work - tailor to +your needs:: + + alias tty-ldisc-2 serport + alias char-major-13 input + above input joydev ns558 analog + options analog map=gamepad,none,2btn + +Verifying that it works +----------------------- + +For testing the joystick driver functionality, there is the jstest +program in the utilities package. You run it by typing:: + + jstest /dev/input/js0 + +And it should show a line with the joystick values, which update as you +move the stick, and press its buttons. The axes should all be zero when the +joystick is in the center position. They should not jitter by themselves to +other close values, and they also should be steady in any other position of +the stick. They should have the full range from -32767 to 32767. If all this +is met, then it's all fine, and you can play the games. :) + +If it's not, then there might be a problem. Try to calibrate the joystick, +and if it still doesn't work, read the drivers section of this file, the +troubleshooting section, and the FAQ. + +Calibration +----------- + +For most joysticks you won't need any manual calibration, since the +joystick should be autocalibrated by the driver automagically. However, with +some analog joysticks, that either do not use linear resistors, or if you +want better precision, you can use the jscal program:: + + jscal -c /dev/input/js0 + +included in the joystick package to set better correction coefficients than +what the driver would choose itself. + +After calibrating the joystick you can verify if you like the new +calibration using the jstest command, and if you do, you then can save the +correction coefficients into a file:: + + jscal -p /dev/input/js0 > /etc/joystick.cal + +And add a line to your rc script executing that file:: + + source /etc/joystick.cal + +This way, after the next reboot your joystick will remain calibrated. You +can also add the ``jscal -p`` line to your shutdown script. + +HW specific driver information +============================== + +In this section each of the separate hardware specific drivers is described. + +Analog joysticks +---------------- + +The analog.c uses the standard analog inputs of the gameport, and thus +supports all standard joysticks and gamepads. It uses a very advanced +routine for this, allowing for data precision that can't be found on any +other system. + +It also supports extensions like additional hats and buttons compatible +with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek +Cyborg 'digital' joysticks are also supported by this driver, because +they're basically souped up CHF sticks. + +However the only types that can be autodetected are: + +* 2-axis, 4-button joystick +* 3-axis, 4-button joystick +* 4-axis, 4-button joystick +* Saitek Cyborg 'digital' joysticks + +For other joystick types (more/less axes, hats, and buttons) support +you'll need to specify the types either on the kernel command line or on the +module command line, when inserting analog into the kernel. The +parameters are:: + + analog.map=<type1>,<type2>,<type3>,.... + +'type' is type of the joystick from the table below, defining joysticks +present on gameports in the system, starting with gameport0, second 'type' +entry defining joystick on gameport1 and so on. + + ========= ===================================================== + Type Meaning + ========= ===================================================== + none No analog joystick on that port + auto Autodetect joystick + 2btn 2-button n-axis joystick + y-joy Two 2-button 2-axis joysticks on an Y-cable + y-pad Two 2-button 2-axis gamepads on an Y-cable + fcs Thrustmaster FCS compatible joystick + chf Joystick with a CH Flightstick compatible hat + fullchf CH Flightstick compatible with two hats and 6 buttons + gamepad 4/6-button n-axis gamepad + gamepad8 8-button 2-axis gamepad + ========= ===================================================== + +In case your joystick doesn't fit in any of the above categories, you can +specify the type as a number by combining the bits in the table below. This +is not recommended unless you really know what are you doing. It's not +dangerous, but not simple either. + + ==== ========================= + Bit Meaning + ==== ========================= + 0 Axis X1 + 1 Axis Y1 + 2 Axis X2 + 3 Axis Y2 + 4 Button A + 5 Button B + 6 Button C + 7 Button D + 8 CHF Buttons X and Y + 9 CHF Hat 1 + 10 CHF Hat 2 + 11 FCS Hat + 12 Pad Button X + 13 Pad Button Y + 14 Pad Button U + 15 Pad Button V + 16 Saitek F1-F4 Buttons + 17 Saitek Digital Mode + 19 GamePad + 20 Joy2 Axis X1 + 21 Joy2 Axis Y1 + 22 Joy2 Axis X2 + 23 Joy2 Axis Y2 + 24 Joy2 Button A + 25 Joy2 Button B + 26 Joy2 Button C + 27 Joy2 Button D + 31 Joy2 GamePad + ==== ========================= + +Microsoft SideWinder joysticks +------------------------------ + +Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c +module. All currently supported joysticks: + +* Microsoft SideWinder 3D Pro +* Microsoft SideWinder Force Feedback Pro +* Microsoft SideWinder Force Feedback Wheel +* Microsoft SideWinder FreeStyle Pro +* Microsoft SideWinder GamePad (up to four, chained) +* Microsoft SideWinder Precision Pro +* Microsoft SideWinder Precision Pro USB + +are autodetected, and thus no module parameters are needed. + +There is one caveat with the 3D Pro. There are 9 buttons reported, +although the joystick has only 8. The 9th button is the mode switch on the +rear side of the joystick. However, moving it, you'll reset the joystick, +and make it unresponsive for about a one third of a second. Furthermore, the +joystick will also re-center itself, taking the position it was in during +this time as a new center position. Use it if you want, but think first. + +The SideWinder Standard is not a digital joystick, and thus is supported +by the analog driver described above. + +Logitech ADI devices +-------------------- + +Logitech ADI protocol is supported by the adi.c module. It should support +any Logitech device using this protocol. This includes, but is not limited +to: + +* Logitech CyberMan 2 +* Logitech ThunderPad Digital +* Logitech WingMan Extreme Digital +* Logitech WingMan Formula +* Logitech WingMan Interceptor +* Logitech WingMan GamePad +* Logitech WingMan GamePad USB +* Logitech WingMan GamePad Extreme +* Logitech WingMan Extreme Digital 3D + +ADI devices are autodetected, and the driver supports up to two (any +combination of) devices on a single gameport, using an Y-cable or chained +together. + +Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan +Extreme and Logitech WingMan ThunderPad are not digital joysticks and are +handled by the analog driver described above. Logitech WingMan Warrior and +Logitech Magellan are supported by serial drivers described below. Logitech +WingMan Force and Logitech WingMan Formula Force are supported by the +I-Force driver described below. Logitech CyberMan is not supported yet. + +Gravis GrIP +----------- + +Gravis GrIP protocol is supported by the grip.c module. It currently +supports: + +* Gravis GamePad Pro +* Gravis BlackHawk Digital +* Gravis Xterminator +* Gravis Xterminator DualControl + +All these devices are autodetected, and you can even use any combination +of up to two of these pads either chained together or using an Y-cable on a +single gameport. + +GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is +supported by the stinger driver. Other Gravis joysticks are supported by the +analog driver. + +FPGaming A3D and MadCatz A3D +---------------------------- + +The Assassin 3D protocol created by FPGaming, is used both by FPGaming +themselves and is licensed to MadCatz. A3D devices are supported by the +a3d.c module. It currently supports: + +* FPGaming Assassin 3D +* MadCatz Panther +* MadCatz Panther XL + +All these devices are autodetected. Because the Assassin 3D and the Panther +allow connecting analog joysticks to them, you'll need to load the analog +driver as well to handle the attached joysticks. + +The trackball should work with USB mousedev module as a normal mouse. See +the USB documentation for how to setup an USB mouse. + +ThrustMaster DirectConnect (BSP) +-------------------------------- + +The TM DirectConnect (BSP) protocol is supported by the tmdc.c +module. This includes, but is not limited to: + +* ThrustMaster Millennium 3D Interceptor +* ThrustMaster 3D Rage Pad +* ThrustMaster Fusion Digital Game Pad + +Devices not directly supported, but hopefully working are: + +* ThrustMaster FragMaster +* ThrustMaster Attack Throttle + +If you have one of these, contact me. + +TMDC devices are autodetected, and thus no parameters to the module +are needed. Up to two TMDC devices can be connected to one gameport, using +an Y-cable. + +Creative Labs Blaster +--------------------- + +The Blaster protocol is supported by the cobra.c module. It supports only +the: + +* Creative Blaster GamePad Cobra + +Up to two of these can be used on a single gameport, using an Y-cable. + +Genius Digital joysticks +------------------------ + +The Genius digitally communicating joysticks are supported by the gf2k.c +module. This includes: + +* Genius Flight2000 F-23 joystick +* Genius Flight2000 F-31 joystick +* Genius G-09D gamepad + +Other Genius digital joysticks are not supported yet, but support can be +added fairly easily. + +InterAct Digital joysticks +-------------------------- + +The InterAct digitally communicating joysticks are supported by the +interact.c module. This includes: + +* InterAct HammerHead/FX gamepad +* InterAct ProPad8 gamepad + +Other InterAct digital joysticks are not supported yet, but support can be +added fairly easily. + +PDPI Lightning 4 gamecards +-------------------------- + +PDPI Lightning 4 gamecards are supported by the lightning.c module. +Once the module is loaded, the analog driver can be used to handle the +joysticks. Digitally communicating joystick will work only on port 0, while +using Y-cables, you can connect up to 8 analog joysticks to a single L4 +card, 16 in case you have two in your system. + +Trident 4DWave / Aureal Vortex +------------------------------ + +Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets +provide an "Enhanced Game Port" mode where the soundcard handles polling the +joystick. This mode is supported by the pcigame.c module. Once loaded the +analog driver can use the enhanced features of these gameports.. + +Crystal SoundFusion +------------------- + +Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game +Port", much like the 4DWave or Vortex above. This, and also the normal mode +for the port of the SoundFusion is supported by the cs461x.c module. + +SoundBlaster Live! +------------------ + +The Live! has a special PCI gameport, which, although it doesn't provide +any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than +its ISA counterparts. It also requires special support, hence the +emu10k1-gp.c module for it instead of the normal ns558.c one. + +SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes +------------------------------------------------------------------------ + +These PCI soundcards have specific gameports. They are handled by the +sound drivers themselves. Make sure you select gameport support in the +joystick menu and sound card support in the sound menu for your appropriate +card. + +Amiga +----- + +Amiga joysticks, connected to an Amiga, are supported by the amijoy.c +driver. Since they can't be autodetected, the driver has a command line: + + amijoy.map=<a>,<b> + +a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of +the Amiga. + + ====== =========================== + Value Joystick type + ====== =========================== + 0 None + 1 1-button digital joystick + ====== =========================== + +No more joystick types are supported now, but that should change in the +future if I get an Amiga in the reach of my fingers. + +Game console and 8-bit pads and joysticks +----------------------------------------- + +These pads and joysticks are not designed for PCs and other computers +Linux runs on, and usually require a special connector for attaching +them through a parallel port. + +See :ref:`joystick-parport` for more info. + +SpaceTec/LabTec devices +----------------------- + +SpaceTec serial devices communicate using the SpaceWare protocol. It is +supported by the spaceorb.c and spaceball.c drivers. The devices currently +supported by spaceorb.c are: + +* SpaceTec SpaceBall Avenger +* SpaceTec SpaceOrb 360 + +Devices currently supported by spaceball.c are: + +* SpaceTec SpaceBall 4000 FLX + +In addition to having the spaceorb/spaceball and serport modules in the +kernel, you also need to attach a serial port to it. to do that, run the +inputattach program:: + + inputattach --spaceorb /dev/tts/x & + +or:: + + inputattach --spaceball /dev/tts/x & + +where /dev/tts/x is the serial port which the device is connected to. After +doing this, the device will be reported and will start working. + +There is one caveat with the SpaceOrb. The button #6, the on the bottom +side of the orb, although reported as an ordinary button, causes internal +recentering of the spaceorb, moving the zero point to the position in which +the ball is at the moment of pressing the button. So, think first before +you bind it to some other function. + +SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet. + +Logitech SWIFT devices +---------------------- + +The SWIFT serial protocol is supported by the warrior.c module. It +currently supports only the: + +* Logitech WingMan Warrior + +but in the future, Logitech CyberMan (the original one, not CM2) could be +supported as well. To use the module, you need to run inputattach after you +insert/compile the module into your kernel:: + + inputattach --warrior /dev/tts/x & + +/dev/tts/x is the serial port your Warrior is attached to. + +Magellan / Space Mouse +---------------------- + +The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space +Systems), for many other companies (Logitech, HP, ...) is supported by the +joy-magellan module. It currently supports only the: + +* Magellan 3D +* Space Mouse + +models, the additional buttons on the 'Plus' versions are not supported yet. + +To use it, you need to attach the serial port to the driver using the:: + + inputattach --magellan /dev/tts/x & + +command. After that the Magellan will be detected, initialized, will beep, +and the /dev/input/jsX device should become usable. + +I-Force devices +--------------- + +All I-Force devices are supported by the iforce module. This includes: + +* AVB Mag Turbo Force +* AVB Top Shot Pegasus +* AVB Top Shot Force Feedback Racing Wheel +* Logitech WingMan Force +* Logitech WingMan Force Wheel +* Guillemot Race Leader Force Feedback +* Guillemot Force Feedback Racing Wheel +* Thrustmaster Motor Sport GT + +To use it, you need to attach the serial port to the driver using the:: + + inputattach --iforce /dev/tts/x & + +command. After that the I-Force device will be detected, and the +/dev/input/jsX device should become usable. + +In case you're using the device via the USB port, the inputattach command +isn't needed. + +The I-Force driver now supports force feedback via the event interface. + +Please note that Logitech WingMan 3D devices are _not_ supported by this +module, rather by hid. Force feedback is not supported for those devices. +Logitech gamepads are also hid devices. + +Gravis Stinger gamepad +---------------------- + +The Gravis Stinger serial port gamepad, designed for use with laptop +computers, is supported by the stinger.c module. To use it, attach the +serial port to the driver using:: + + inputattach --stinger /dev/tty/x & + +where x is the number of the serial port. + +Troubleshooting +=============== + +There is quite a high probability that you run into some problems. For +testing whether the driver works, if in doubt, use the jstest utility in +some of its modes. The most useful modes are "normal" - for the 1.x +interface, and "old" for the "0.x" interface. You run it by typing:: + + jstest --normal /dev/input/js0 + jstest --old /dev/input/js0 + +Additionally you can do a test with the evtest utility:: + + evtest /dev/input/event0 + +Oh, and read the FAQ! :) + +FAQ +=== + +:Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the + cause? +:A: The device files don't exist. Create them (see section 2.2). + +:Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick + or pad that uses a 9-pin D-type cannon connector to the serial port of my + PC? +:A: Yes, it is possible, but it'll burn your serial port or the pad. It + won't work, of course. + +:Q: My joystick doesn't work with Quake / Quake 2. What's the cause? +:A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses + for them. diff --git a/Documentation/input/joystick-parport.txt b/Documentation/input/joystick-parport.txt deleted file mode 100644 index 56870c70a796..000000000000 --- a/Documentation/input/joystick-parport.txt +++ /dev/null @@ -1,542 +0,0 @@ - Linux Joystick parport drivers v2.0 - (c) 1998-2000 Vojtech Pavlik <vojtech@ucw.cz> - (c) 1998 Andree Borrmann <a.borrmann@tu-bs.de> - Sponsored by SuSE ----------------------------------------------------------------------------- - -0. Disclaimer -~~~~~~~~~~~~~ - Any information in this file is provided as-is, without any guarantee that -it will be true. So, use it at your own risk. The possible damages that can -happen include burning your parallel port, and/or the sticks and joystick -and maybe even more. Like when a lightning kills you it is not our problem. - -1. Intro -~~~~~~~~ - The joystick parport drivers are used for joysticks and gamepads not -originally designed for PCs and other computers Linux runs on. Because of -that, PCs usually lack the right ports to connect these devices to. Parallel -port, because of its ability to change single bits at will, and providing -both output and input bits is the most suitable port on the PC for -connecting such devices. - -2. Devices supported -~~~~~~~~~~~~~~~~~~~~ - Many console and 8-bit computer gamepads and joysticks are supported. The -following subsections discuss usage of each. - -2.1 NES and SNES -~~~~~~~~~~~~~~~~ - The Nintendo Entertainment System and Super Nintendo Entertainment System -gamepads are widely available, and easy to get. Also, they are quite easy to -connect to a PC, and don't need much processing speed (108 us for NES and -165 us for SNES, compared to about 1000 us for PC gamepads) to communicate -with them. - - All NES and SNES use the same synchronous serial protocol, clocked from -the computer's side (and thus timing insensitive). To allow up to 5 NES -and/or SNES gamepads and/or SNES mice connected to the parallel port at once, -the output lines of the parallel port are shared, while one of 5 available -input lines is assigned to each gamepad. - - This protocol is handled by the gamecon.c driver, so that's the one -you'll use for NES, SNES gamepads and SNES mice. - - The main problem with PC parallel ports is that they don't have +5V power -source on any of their pins. So, if you want a reliable source of power -for your pads, use either keyboard or joystick port, and make a pass-through -cable. You can also pull the power directly from the power supply (the red -wire is +5V). - - If you want to use the parallel port only, you can take the power is from -some data pin. For most gamepad and parport implementations only one pin is -needed, and I'd recommend pin 9 for that, the highest data bit. On the other -hand, if you are not planning to use anything else than NES / SNES on the -port, anything between and including pin 4 and pin 9 will work. - -(pin 9) -----> Power - - Unfortunately, there are pads that need a lot more of power, and parallel -ports that can't give much current through the data pins. If this is your -case, you'll need to use diodes (as a prevention of destroying your parallel -port), and combine the currents of two or more data bits together. - - Diodes -(pin 9) ----|>|-------+------> Power - | -(pin 8) ----|>|-------+ - | -(pin 7) ----|>|-------+ - | - <and so on> : - | -(pin 4) ----|>|-------+ - - Ground is quite easy. On PC's parallel port the ground is on any of the -pins from pin 18 to pin 25. So use any pin of these you like for the ground. - -(pin 18) -----> Ground - - NES and SNES pads have two input bits, Clock and Latch, which drive the -serial transfer. These are connected to pins 2 and 3 of the parallel port, -respectively. - -(pin 2) -----> Clock -(pin 3) -----> Latch - - And the last thing is the NES / SNES data wire. Only that isn't shared and -each pad needs its own data pin. The parallel port pins are: - -(pin 10) -----> Pad 1 data -(pin 11) -----> Pad 2 data -(pin 12) -----> Pad 3 data -(pin 13) -----> Pad 4 data -(pin 15) -----> Pad 5 data - - Note that pin 14 is not used, since it is not an input pin on the parallel -port. - - This is everything you need on the PC's side of the connection, now on to -the gamepads side. The NES and SNES have different connectors. Also, there -are quite a lot of NES clones, and because Nintendo used proprietary -connectors for their machines, the cloners couldn't and used standard D-Cannon -connectors. Anyway, if you've got a gamepad, and it has buttons A, B, Turbo -A, Turbo B, Select and Start, and is connected through 5 wires, then it is -either a NES or NES clone and will work with this connection. SNES gamepads -also use 5 wires, but have more buttons. They will work as well, of course. - -Pinout for NES gamepads Pinout for SNES gamepads and mice - - +----> Power +-----------------------\ - | 7 | o o o o | x x o | 1 - 5 +---------+ 7 +-----------------------/ - | x x o \ | | | | | - | o o o o | | | | | +-> Ground - 4 +------------+ 1 | | | +------------> Data - | | | | | | +---------------> Latch - | | | +-> Ground | +------------------> Clock - | | +----> Clock +---------------------> Power - | +-------> Latch - +----------> Data - -Pinout for NES clone (db9) gamepads Pinout for NES clone (db15) gamepads - - +---------> Clock +-----------------> Data - | +-------> Latch | +---> Ground - | | +-----> Data | | - | | | ___________________ - _____________ 8 \ o x x x x x x o / 1 - 5 \ x o o o x / 1 \ o x x o x x o / - \ x o x o / 15 `~~~~~~~~~~~~~' 9 - 9 `~~~~~~~' 6 | | | - | | | | +----> Clock - | +----> Power | +----------> Latch - +--------> Ground +----------------> Power - -2.2 Multisystem joysticks -~~~~~~~~~~~~~~~~~~~~~~~~~ - In the era of 8-bit machines, there was something like de-facto standard -for joystick ports. They were all digital, and all used D-Cannon 9 pin -connectors (db9). Because of that, a single joystick could be used without -hassle on Atari (130, 800XE, 800XL, 2600, 7200), Amiga, Commodore C64, -Amstrad CPC, Sinclair ZX Spectrum and many other machines. That's why these -joysticks are called "Multisystem". - - Now their pinout: - - +---------> Right - | +-------> Left - | | +-----> Down - | | | +---> Up - | | | | - _____________ -5 \ x o o o o / 1 - \ x o x o / - 9 `~~~~~~~' 6 - | | - | +----> Button - +--------> Ground - - However, as time passed, extensions to this standard developed, and these -were not compatible with each other: - - - Atari 130, 800/XL/XE MSX - - +-----------> Power - +---------> Right | +---------> Right - | +-------> Left | | +-------> Left - | | +-----> Down | | | +-----> Down - | | | +---> Up | | | | +---> Up - | | | | | | | | | - _____________ _____________ -5 \ x o o o o / 1 5 \ o o o o o / 1 - \ x o o o / \ o o o o / - 9 `~~~~~~~' 6 9 `~~~~~~~' 6 - | | | | | | | - | | +----> Button | | | +----> Button 1 - | +------> Power | | +------> Button 2 - +--------> Ground | +--------> Output 3 - +----------> Ground - - Amstrad CPC Commodore C64 - - +-----------> Analog Y - +---------> Right | +---------> Right - | +-------> Left | | +-------> Left - | | +-----> Down | | | +-----> Down - | | | +---> Up | | | | +---> Up - | | | | | | | | | - _____________ _____________ -5 \ x o o o o / 1 5 \ o o o o o / 1 - \ x o o o / \ o o o o / - 9 `~~~~~~~' 6 9 `~~~~~~~' 6 - | | | | | | | - | | +----> Button 1 | | | +----> Button - | +------> Button 2 | | +------> Power - +--------> Ground | +--------> Ground - +----------> Analog X - - Sinclair Spectrum +2A/+3 Amiga 1200 - - +-----------> Up +-----------> Button 3 - | +---------> Fire | +---------> Right - | | | | +-------> Left - | | +-----> Ground | | | +-----> Down - | | | | | | | +---> Up - | | | | | | | | - _____________ _____________ -5 \ o o x o x / 1 5 \ o o o o o / 1 - \ o o o o / \ o o o o / - 9 `~~~~~~~' 6 9 `~~~~~~~' 6 - | | | | | | | | - | | | +----> Right | | | +----> Button 1 - | | +------> Left | | +------> Power - | +--------> Ground | +--------> Ground - +----------> Down +----------> Button 2 - - And there were many others. - -2.2.1 Multisystem joysticks using db9.c -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For the Multisystem joysticks, and their derivatives, the db9.c driver -was written. It allows only one joystick / gamepad per parallel port, but -the interface is easy to build and works with almost anything. - - For the basic 1-button Multisystem joystick you connect its wires to the -parallel port like this: - -(pin 1) -----> Power -(pin 18) -----> Ground - -(pin 2) -----> Up -(pin 3) -----> Down -(pin 4) -----> Left -(pin 5) -----> Right -(pin 6) -----> Button 1 - - However, if the joystick is switch based (eg. clicks when you move it), -you might or might not, depending on your parallel port, need 10 kOhm pullup -resistors on each of the direction and button signals, like this: - -(pin 2) ------------+------> Up - Resistor | -(pin 1) --[10kOhm]--+ - - Try without, and if it doesn't work, add them. For TTL based joysticks / -gamepads the pullups are not needed. - - For joysticks with two buttons you connect the second button to pin 7 on -the parallel port. - -(pin 7) -----> Button 2 - - And that's it. - - On a side note, if you have already built a different adapter for use with -the digital joystick driver 0.8.0.2, this is also supported by the db9.c -driver, as device type 8. (See section 3.2) - -2.2.2 Multisystem joysticks using gamecon.c -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For some people just one joystick per parallel port is not enough, and/or -want to use them on one parallel port together with NES/SNES/PSX pads. This is -possible using the gamecon.c. It supports up to 5 devices of the above types, -including 1 and 2 buttons Multisystem joysticks. - - However, there is nothing for free. To allow more sticks to be used at -once, you need the sticks to be purely switch based (that is non-TTL), and -not to need power. Just a plain simple six switches inside. If your -joystick can do more (eg. turbofire) you'll need to disable it totally first -if you want to use gamecon.c. - - Also, the connection is a bit more complex. You'll need a bunch of diodes, -and one pullup resistor. First, you connect the Directions and the button -the same as for db9, however with the diodes between. - - Diodes -(pin 2) -----|<|----> Up -(pin 3) -----|<|----> Down -(pin 4) -----|<|----> Left -(pin 5) -----|<|----> Right -(pin 6) -----|<|----> Button 1 - - For two button sticks you also connect the other button. - -(pin 7) -----|<|----> Button 2 - - And finally, you connect the Ground wire of the joystick, like done in -this little schematic to Power and Data on the parallel port, as described -for the NES / SNES pads in section 2.1 of this file - that is, one data pin -for each joystick. The power source is shared. - -Data ------------+-----> Ground - Resistor | -Power --[10kOhm]--+ - - And that's all, here we go! - -2.2.3 Multisystem joysticks using turbografx.c -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The TurboGraFX interface, designed by - - Steffen Schwenke <schwenke@burg-halle.de> - - allows up to 7 Multisystem joysticks connected to the parallel port. In -Steffen's version, there is support for up to 5 buttons per joystick. However, -since this doesn't work reliably on all parallel ports, the turbografx.c driver -supports only one button per joystick. For more information on how to build the -interface, see - - http://www2.burg-halle.de/~schwenke/parport.html - -2.3 Sony Playstation -~~~~~~~~~~~~~~~~~~~~ - - The PSX controller is supported by the gamecon.c. Pinout of the PSX -controller (compatible with DirectPadPro): - - +---------+---------+---------+ -9 | o o o | o o o | o o o | 1 parallel - \________|_________|________/ port pins - | | | | | | - | | | | | +--------> Clock --- (4) - | | | | +------------> Select --- (3) - | | | +---------------> Power --- (5-9) - | | +------------------> Ground --- (18-25) - | +-------------------------> Command --- (2) - +----------------------------> Data --- (one of 10,11,12,13,15) - - The driver supports these controllers: - - * Standard PSX Pad - * NegCon PSX Pad - * Analog PSX Pad (red mode) - * Analog PSX Pad (green mode) - * PSX Rumble Pad - * PSX DDR Pad - -2.4 Sega -~~~~~~~~ - All the Sega controllers are more or less based on the standard 2-button -Multisystem joystick. However, since they don't use switches and use TTL -logic, the only driver usable with them is the db9.c driver. - -2.4.1 Sega Master System -~~~~~~~~~~~~~~~~~~~~~~~~ - The SMS gamepads are almost exactly the same as normal 2-button -Multisystem joysticks. Set the driver to Multi2 mode, use the corresponding -parallel port pins, and the following schematic: - - +-----------> Power - | +---------> Right - | | +-------> Left - | | | +-----> Down - | | | | +---> Up - | | | | | - _____________ -5 \ o o o o o / 1 - \ o o x o / - 9 `~~~~~~~' 6 - | | | - | | +----> Button 1 - | +--------> Ground - +----------> Button 2 - -2.4.2 Sega Genesis aka MegaDrive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The Sega Genesis (in Europe sold as Sega MegaDrive) pads are an extension -to the Sega Master System pads. They use more buttons (3+1, 5+1, 6+1). Use -the following schematic: - - +-----------> Power - | +---------> Right - | | +-------> Left - | | | +-----> Down - | | | | +---> Up - | | | | | - _____________ -5 \ o o o o o / 1 - \ o o o o / - 9 `~~~~~~~' 6 - | | | | - | | | +----> Button 1 - | | +------> Select - | +--------> Ground - +----------> Button 2 - - The Select pin goes to pin 14 on the parallel port. - -(pin 14) -----> Select - - The rest is the same as for Multi2 joysticks using db9.c - -2.4.3 Sega Saturn -~~~~~~~~~~~~~~~~~ - Sega Saturn has eight buttons, and to transfer that, without hacks like -Genesis 6 pads use, it needs one more select pin. Anyway, it is still -handled by the db9.c driver. Its pinout is very different from anything -else. Use this schematic: - - +-----------> Select 1 - | +---------> Power - | | +-------> Up - | | | +-----> Down - | | | | +---> Ground - | | | | | - _____________ -5 \ o o o o o / 1 - \ o o o o / - 9 `~~~~~~~' 6 - | | | | - | | | +----> Select 2 - | | +------> Right - | +--------> Left - +----------> Power - - Select 1 is pin 14 on the parallel port, Select 2 is pin 16 on the -parallel port. - -(pin 14) -----> Select 1 -(pin 16) -----> Select 2 - - The other pins (Up, Down, Right, Left, Power, Ground) are the same as for -Multi joysticks using db9.c - -3. The drivers -~~~~~~~~~~~~~~ - There are three drivers for the parallel port interfaces. Each, as -described above, allows to connect a different group of joysticks and pads. -Here are described their command lines: - -3.1 gamecon.c -~~~~~~~~~~~~~ - Using gamecon.c you can connect up to five devices to one parallel port. It -uses the following kernel/module command line: - - gamecon.map=port,pad1,pad2,pad3,pad4,pad5 - - Where 'port' the number of the parport interface (eg. 0 for parport0). - - And 'pad1' to 'pad5' are pad types connected to different data input pins -(10,11,12,13,15), as described in section 2.1 of this file. - - The types are: - - Type | Joystick/Pad - -------------------- - 0 | None - 1 | SNES pad - 2 | NES pad - 4 | Multisystem 1-button joystick - 5 | Multisystem 2-button joystick - 6 | N64 pad - 7 | Sony PSX controller - 8 | Sony PSX DDR controller - 9 | SNES mouse - - The exact type of the PSX controller type is autoprobed when used, so -hot swapping should work (but is not recommended). - - Should you want to use more than one of parallel ports at once, you can use -gamecon.map2 and gamecon.map3 as additional command line parameters for two -more parallel ports. - - There are two options specific to PSX driver portion. gamecon.psx_delay sets -the command delay when talking to the controllers. The default of 25 should -work but you can try lowering it for better performance. If your pads don't -respond try raising it until they work. Setting the type to 8 allows the -driver to be used with Dance Dance Revolution or similar games. Arrow keys are -registered as key presses instead of X and Y axes. - -3.2 db9.c -~~~~~~~~~ - Apart from making an interface, there is nothing difficult on using the -db9.c driver. It uses the following kernel/module command line: - - db9.dev=port,type - - Where 'port' is the number of the parport interface (eg. 0 for parport0). - - Caveat here: This driver only works on bidirectional parallel ports. If -your parallel port is recent enough, you should have no trouble with this. -Old parallel ports may not have this feature. - - 'Type' is the type of joystick or pad attached: - - Type | Joystick/Pad - -------------------- - 0 | None - 1 | Multisystem 1-button joystick - 2 | Multisystem 2-button joystick - 3 | Genesis pad (3+1 buttons) - 5 | Genesis pad (5+1 buttons) - 6 | Genesis pad (6+2 buttons) - 7 | Saturn pad (8 buttons) - 8 | Multisystem 1-button joystick (v0.8.0.2 pin-out) - 9 | Two Multisystem 1-button joysticks (v0.8.0.2 pin-out) - 10 | Amiga CD32 pad - - Should you want to use more than one of these joysticks/pads at once, you -can use db9.dev2 and db9.dev3 as additional command line parameters for two -more joysticks/pads. - -3.3 turbografx.c -~~~~~~~~~~~~~~~~ - The turbografx.c driver uses a very simple kernel/module command line: - - turbografx.map=port,js1,js2,js3,js4,js5,js6,js7 - - Where 'port' is the number of the parport interface (eg. 0 for parport0). - - 'jsX' is the number of buttons the Multisystem joysticks connected to the -interface ports 1-7 have. For a standard multisystem joystick, this is 1. - - Should you want to use more than one of these interfaces at once, you can -use turbografx.map2 and turbografx.map3 as additional command line parameters -for two more interfaces. - -3.4 PC parallel port pinout -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .----------------------------------------. - At the PC: \ 13 12 11 10 9 8 7 6 5 4 3 2 1 / - \ 25 24 23 22 21 20 19 18 17 16 15 14 / - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Pin | Name | Description - ~~~~~~|~~~~~~~~~|~~~~~~~~~~ - 1 | /STROBE | Strobe - 2-9 | D0-D7 | Data Bit 0-7 - 10 | /ACK | Acknowledge - 11 | BUSY | Busy - 12 | PE | Paper End - 13 | SELIN | Select In - 14 | /AUTOFD | Autofeed - 15 | /ERROR | Error - 16 | /INIT | Initialize - 17 | /SEL | Select - 18-25 | GND | Signal Ground - -3.5 End -~~~~~~~ - That's all, folks! Have fun! diff --git a/Documentation/input/joystick.txt b/Documentation/input/joystick.txt deleted file mode 100644 index 8d027dc86c1f..000000000000 --- a/Documentation/input/joystick.txt +++ /dev/null @@ -1,586 +0,0 @@ - Linux Joystick driver v2.0.0 - (c) 1996-2000 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE ----------------------------------------------------------------------------- - -0. Disclaimer -~~~~~~~~~~~~~ - This program is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the Free -Software Foundation; either version 2 of the License, or (at your option) -any later version. - - This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for -more details. - - You should have received a copy of the GNU General Public License along -with this program; if not, write to the Free Software Foundation, Inc., 59 -Temple Place, Suite 330, Boston, MA 02111-1307 USA - - Should you need to contact me, the author, you can do so either by e-mail -- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik, -Simunkova 1594, Prague 8, 182 00 Czech Republic - - For your convenience, the GNU General Public License version 2 is included -in the package: See the file COPYING. - -1. Intro -~~~~~~~~ - The joystick driver for Linux provides support for a variety of joysticks -and similar devices. It is based on a larger project aiming to support all -input devices in Linux. - - Should you encounter any problems while using the driver, or joysticks -this driver can't make complete use of, I'm very interested in hearing about -them. Bug reports and success stories are also welcome. - - The input project website is at: - - http://atrey.karlin.mff.cuni.cz/~vojtech/input/ - - There is also a mailing list for the driver at: - - listproc@atrey.karlin.mff.cuni.cz - -send "subscribe linux-joystick Your Name" to subscribe to it. - -2. Usage -~~~~~~~~ - For basic usage you just choose the right options in kernel config and -you should be set. - -2.1 inpututils -~~~~~~~~~~~~~~ -For testing and other purposes (for example serial devices), a set of -utilities is available at the abovementioned website. I suggest you download -and install it before going on. - -2.2 Device nodes -~~~~~~~~~~~~~~~~ -For applications to be able to use the joysticks, -you'll have to manually create these nodes in /dev: - -cd /dev -rm js* -mkdir input -mknod input/js0 c 13 0 -mknod input/js1 c 13 1 -mknod input/js2 c 13 2 -mknod input/js3 c 13 3 -ln -s input/js0 js0 -ln -s input/js1 js1 -ln -s input/js2 js2 -ln -s input/js3 js3 - -For testing with inpututils it's also convenient to create these: - -mknod input/event0 c 13 64 -mknod input/event1 c 13 65 -mknod input/event2 c 13 66 -mknod input/event3 c 13 67 - -2.4 Modules needed -~~~~~~~~~~~~~~~~~~ - For all joystick drivers to function, you'll need the userland interface -module in kernel, either loaded or compiled in: - - modprobe joydev - - For gameport joysticks, you'll have to load the gameport driver as well; - - modprobe ns558 - - And for serial port joysticks, you'll need the serial input line -discipline module loaded and the inputattach utility started: - - modprobe serport - inputattach -xxx /dev/tts/X & - - In addition to that, you'll need the joystick driver module itself, most -usually you'll have an analog joystick: - - modprobe analog - - For automatic module loading, something like this might work - tailor to -your needs: - - alias tty-ldisc-2 serport - alias char-major-13 input - above input joydev ns558 analog - options analog map=gamepad,none,2btn - -2.5 Verifying that it works -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For testing the joystick driver functionality, there is the jstest -program in the utilities package. You run it by typing: - - jstest /dev/input/js0 - - And it should show a line with the joystick values, which update as you -move the stick, and press its buttons. The axes should all be zero when the -joystick is in the center position. They should not jitter by themselves to -other close values, and they also should be steady in any other position of -the stick. They should have the full range from -32767 to 32767. If all this -is met, then it's all fine, and you can play the games. :) - - If it's not, then there might be a problem. Try to calibrate the joystick, -and if it still doesn't work, read the drivers section of this file, the -troubleshooting section, and the FAQ. - -2.6. Calibration -~~~~~~~~~~~~~~~~ - For most joysticks you won't need any manual calibration, since the -joystick should be autocalibrated by the driver automagically. However, with -some analog joysticks, that either do not use linear resistors, or if you -want better precision, you can use the jscal program - - jscal -c /dev/input/js0 - - included in the joystick package to set better correction coefficients than -what the driver would choose itself. - - After calibrating the joystick you can verify if you like the new -calibration using the jstest command, and if you do, you then can save the -correction coefficients into a file - - jscal -p /dev/input/js0 > /etc/joystick.cal - - And add a line to your rc script executing that file - - source /etc/joystick.cal - - This way, after the next reboot your joystick will remain calibrated. You -can also add the jscal -p line to your shutdown script. - - -3. HW specific driver information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In this section each of the separate hardware specific drivers is described. - -3.1 Analog joysticks -~~~~~~~~~~~~~~~~~~~~ - The analog.c uses the standard analog inputs of the gameport, and thus -supports all standard joysticks and gamepads. It uses a very advanced -routine for this, allowing for data precision that can't be found on any -other system. - - It also supports extensions like additional hats and buttons compatible -with CH Flightstick Pro, ThrustMaster FCS or 6 and 8 button gamepads. Saitek -Cyborg 'digital' joysticks are also supported by this driver, because -they're basically souped up CHF sticks. - - However the only types that can be autodetected are: - -* 2-axis, 4-button joystick -* 3-axis, 4-button joystick -* 4-axis, 4-button joystick -* Saitek Cyborg 'digital' joysticks - - For other joystick types (more/less axes, hats, and buttons) support -you'll need to specify the types either on the kernel command line or on the -module command line, when inserting analog into the kernel. The -parameters are: - - analog.map=<type1>,<type2>,<type3>,.... - - 'type' is type of the joystick from the table below, defining joysticks -present on gameports in the system, starting with gameport0, second 'type' -entry defining joystick on gameport1 and so on. - - Type | Meaning - ----------------------------------- - none | No analog joystick on that port - auto | Autodetect joystick - 2btn | 2-button n-axis joystick - y-joy | Two 2-button 2-axis joysticks on an Y-cable - y-pad | Two 2-button 2-axis gamepads on an Y-cable - fcs | Thrustmaster FCS compatible joystick - chf | Joystick with a CH Flightstick compatible hat - fullchf | CH Flightstick compatible with two hats and 6 buttons - gamepad | 4/6-button n-axis gamepad - gamepad8 | 8-button 2-axis gamepad - - In case your joystick doesn't fit in any of the above categories, you can -specify the type as a number by combining the bits in the table below. This -is not recommended unless you really know what are you doing. It's not -dangerous, but not simple either. - - Bit | Meaning - -------------------------- - 0 | Axis X1 - 1 | Axis Y1 - 2 | Axis X2 - 3 | Axis Y2 - 4 | Button A - 5 | Button B - 6 | Button C - 7 | Button D - 8 | CHF Buttons X and Y - 9 | CHF Hat 1 - 10 | CHF Hat 2 - 11 | FCS Hat - 12 | Pad Button X - 13 | Pad Button Y - 14 | Pad Button U - 15 | Pad Button V - 16 | Saitek F1-F4 Buttons - 17 | Saitek Digital Mode - 19 | GamePad - 20 | Joy2 Axis X1 - 21 | Joy2 Axis Y1 - 22 | Joy2 Axis X2 - 23 | Joy2 Axis Y2 - 24 | Joy2 Button A - 25 | Joy2 Button B - 26 | Joy2 Button C - 27 | Joy2 Button D - 31 | Joy2 GamePad - -3.2 Microsoft SideWinder joysticks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Microsoft 'Digital Overdrive' protocol is supported by the sidewinder.c -module. All currently supported joysticks: - -* Microsoft SideWinder 3D Pro -* Microsoft SideWinder Force Feedback Pro -* Microsoft SideWinder Force Feedback Wheel -* Microsoft SideWinder FreeStyle Pro -* Microsoft SideWinder GamePad (up to four, chained) -* Microsoft SideWinder Precision Pro -* Microsoft SideWinder Precision Pro USB - - are autodetected, and thus no module parameters are needed. - - There is one caveat with the 3D Pro. There are 9 buttons reported, -although the joystick has only 8. The 9th button is the mode switch on the -rear side of the joystick. However, moving it, you'll reset the joystick, -and make it unresponsive for about a one third of a second. Furthermore, the -joystick will also re-center itself, taking the position it was in during -this time as a new center position. Use it if you want, but think first. - - The SideWinder Standard is not a digital joystick, and thus is supported -by the analog driver described above. - -3.3 Logitech ADI devices -~~~~~~~~~~~~~~~~~~~~~~~~ - Logitech ADI protocol is supported by the adi.c module. It should support -any Logitech device using this protocol. This includes, but is not limited -to: - -* Logitech CyberMan 2 -* Logitech ThunderPad Digital -* Logitech WingMan Extreme Digital -* Logitech WingMan Formula -* Logitech WingMan Interceptor -* Logitech WingMan GamePad -* Logitech WingMan GamePad USB -* Logitech WingMan GamePad Extreme -* Logitech WingMan Extreme Digital 3D - - ADI devices are autodetected, and the driver supports up to two (any -combination of) devices on a single gameport, using an Y-cable or chained -together. - - Logitech WingMan Joystick, Logitech WingMan Attack, Logitech WingMan -Extreme and Logitech WingMan ThunderPad are not digital joysticks and are -handled by the analog driver described above. Logitech WingMan Warrior and -Logitech Magellan are supported by serial drivers described below. Logitech -WingMan Force and Logitech WingMan Formula Force are supported by the -I-Force driver described below. Logitech CyberMan is not supported yet. - -3.4 Gravis GrIP -~~~~~~~~~~~~~~~ - Gravis GrIP protocol is supported by the grip.c module. It currently -supports: - -* Gravis GamePad Pro -* Gravis BlackHawk Digital -* Gravis Xterminator -* Gravis Xterminator DualControl - - All these devices are autodetected, and you can even use any combination -of up to two of these pads either chained together or using an Y-cable on a -single gameport. - -GrIP MultiPort isn't supported yet. Gravis Stinger is a serial device and is -supported by the stinger driver. Other Gravis joysticks are supported by the -analog driver. - -3.5 FPGaming A3D and MadCatz A3D -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The Assassin 3D protocol created by FPGaming, is used both by FPGaming -themselves and is licensed to MadCatz. A3D devices are supported by the -a3d.c module. It currently supports: - -* FPGaming Assassin 3D -* MadCatz Panther -* MadCatz Panther XL - - All these devices are autodetected. Because the Assassin 3D and the Panther -allow connecting analog joysticks to them, you'll need to load the analog -driver as well to handle the attached joysticks. - - The trackball should work with USB mousedev module as a normal mouse. See -the USB documentation for how to setup an USB mouse. - -3.6 ThrustMaster DirectConnect (BSP) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The TM DirectConnect (BSP) protocol is supported by the tmdc.c -module. This includes, but is not limited to: - -* ThrustMaster Millennium 3D Interceptor -* ThrustMaster 3D Rage Pad -* ThrustMaster Fusion Digital Game Pad - - Devices not directly supported, but hopefully working are: - -* ThrustMaster FragMaster -* ThrustMaster Attack Throttle - - If you have one of these, contact me. - - TMDC devices are autodetected, and thus no parameters to the module -are needed. Up to two TMDC devices can be connected to one gameport, using -an Y-cable. - -3.7 Creative Labs Blaster -~~~~~~~~~~~~~~~~~~~~~~~~~ - The Blaster protocol is supported by the cobra.c module. It supports only -the: - -* Creative Blaster GamePad Cobra - - Up to two of these can be used on a single gameport, using an Y-cable. - -3.8 Genius Digital joysticks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The Genius digitally communicating joysticks are supported by the gf2k.c -module. This includes: - -* Genius Flight2000 F-23 joystick -* Genius Flight2000 F-31 joystick -* Genius G-09D gamepad - - Other Genius digital joysticks are not supported yet, but support can be -added fairly easily. - -3.9 InterAct Digital joysticks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The InterAct digitally communicating joysticks are supported by the -interact.c module. This includes: - -* InterAct HammerHead/FX gamepad -* InterAct ProPad8 gamepad - - Other InterAct digital joysticks are not supported yet, but support can be -added fairly easily. - -3.10 PDPI Lightning 4 gamecards -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - PDPI Lightning 4 gamecards are supported by the lightning.c module. -Once the module is loaded, the analog driver can be used to handle the -joysticks. Digitally communicating joystick will work only on port 0, while -using Y-cables, you can connect up to 8 analog joysticks to a single L4 -card, 16 in case you have two in your system. - -3.11 Trident 4DWave / Aureal Vortex -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Soundcards with a Trident 4DWave DX/NX or Aureal Vortex/Vortex2 chipsets -provide an "Enhanced Game Port" mode where the soundcard handles polling the -joystick. This mode is supported by the pcigame.c module. Once loaded the -analog driver can use the enhanced features of these gameports.. - -3.13 Crystal SoundFusion -~~~~~~~~~~~~~~~~~~~~~~~~ - Soundcards with Crystal SoundFusion chipsets provide an "Enhanced Game -Port", much like the 4DWave or Vortex above. This, and also the normal mode -for the port of the SoundFusion is supported by the cs461x.c module. - -3.14 SoundBlaster Live! -~~~~~~~~~~~~~~~~~~~~~~~~ - The Live! has a special PCI gameport, which, although it doesn't provide -any "Enhanced" stuff like 4DWave and friends, is quite a bit faster than -its ISA counterparts. It also requires special support, hence the -emu10k1-gp.c module for it instead of the normal ns558.c one. - -3.15 SoundBlaster 64 and 128 - ES1370 and ES1371, ESS Solo1 and S3 SonicVibes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - These PCI soundcards have specific gameports. They are handled by the -sound drivers themselves. Make sure you select gameport support in the -joystick menu and sound card support in the sound menu for your appropriate -card. - -3.16 Amiga -~~~~~~~~~~ - Amiga joysticks, connected to an Amiga, are supported by the amijoy.c -driver. Since they can't be autodetected, the driver has a command line. - - amijoy.map=<a>,<b> - - a and b define the joysticks connected to the JOY0DAT and JOY1DAT ports of -the Amiga. - - Value | Joystick type - --------------------- - 0 | None - 1 | 1-button digital joystick - - No more joystick types are supported now, but that should change in the -future if I get an Amiga in the reach of my fingers. - -3.17 Game console and 8-bit pads and joysticks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See joystick-parport.txt for more info. - -3.18 SpaceTec/LabTec devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - SpaceTec serial devices communicate using the SpaceWare protocol. It is -supported by the spaceorb.c and spaceball.c drivers. The devices currently -supported by spaceorb.c are: - -* SpaceTec SpaceBall Avenger -* SpaceTec SpaceOrb 360 - -Devices currently supported by spaceball.c are: - -* SpaceTec SpaceBall 4000 FLX - - In addition to having the spaceorb/spaceball and serport modules in the -kernel, you also need to attach a serial port to it. to do that, run the -inputattach program: - - inputattach --spaceorb /dev/tts/x & -or - inputattach --spaceball /dev/tts/x & - -where /dev/tts/x is the serial port which the device is connected to. After -doing this, the device will be reported and will start working. - - There is one caveat with the SpaceOrb. The button #6, the on the bottom -side of the orb, although reported as an ordinary button, causes internal -recentering of the spaceorb, moving the zero point to the position in which -the ball is at the moment of pressing the button. So, think first before -you bind it to some other function. - -SpaceTec SpaceBall 2003 FLX and 3003 FLX are not supported yet. - -3.19 Logitech SWIFT devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The SWIFT serial protocol is supported by the warrior.c module. It -currently supports only the: - -* Logitech WingMan Warrior - -but in the future, Logitech CyberMan (the original one, not CM2) could be -supported as well. To use the module, you need to run inputattach after you -insert/compile the module into your kernel: - - inputattach --warrior /dev/tts/x & - -/dev/tts/x is the serial port your Warrior is attached to. - -3.20 Magellan / Space Mouse -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The Magellan (or Space Mouse), manufactured by LogiCad3d (formerly Space -Systems), for many other companies (Logitech, HP, ...) is supported by the -joy-magellan module. It currently supports only the: - -* Magellan 3D -* Space Mouse - -models, the additional buttons on the 'Plus' versions are not supported yet. - - To use it, you need to attach the serial port to the driver using the - - inputattach --magellan /dev/tts/x & - -command. After that the Magellan will be detected, initialized, will beep, -and the /dev/input/jsX device should become usable. - -3.21 I-Force devices -~~~~~~~~~~~~~~~~~~~~ - All I-Force devices are supported by the iforce module. This includes: - -* AVB Mag Turbo Force -* AVB Top Shot Pegasus -* AVB Top Shot Force Feedback Racing Wheel -* Logitech WingMan Force -* Logitech WingMan Force Wheel -* Guillemot Race Leader Force Feedback -* Guillemot Force Feedback Racing Wheel -* Thrustmaster Motor Sport GT - - To use it, you need to attach the serial port to the driver using the - - inputattach --iforce /dev/tts/x & - -command. After that the I-Force device will be detected, and the -/dev/input/jsX device should become usable. - - In case you're using the device via the USB port, the inputattach command -isn't needed. - - The I-Force driver now supports force feedback via the event interface. - - Please note that Logitech WingMan *3D devices are _not_ supported by this -module, rather by hid. Force feedback is not supported for those devices. -Logitech gamepads are also hid devices. - -3.22 Gravis Stinger gamepad -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The Gravis Stinger serial port gamepad, designed for use with laptop -computers, is supported by the stinger.c module. To use it, attach the -serial port to the driver using: - - inputattach --stinger /dev/tty/x & - -where x is the number of the serial port. - -4. Troubleshooting -~~~~~~~~~~~~~~~~~~ - There is quite a high probability that you run into some problems. For -testing whether the driver works, if in doubt, use the jstest utility in -some of its modes. The most useful modes are "normal" - for the 1.x -interface, and "old" for the "0.x" interface. You run it by typing: - - jstest --normal /dev/input/js0 - jstest --old /dev/input/js0 - - Additionally you can do a test with the evtest utility: - - evtest /dev/input/event0 - - Oh, and read the FAQ! :) - -5. FAQ -~~~~~~ -Q: Running 'jstest /dev/input/js0' results in "File not found" error. What's the - cause? -A: The device files don't exist. Create them (see section 2.2). - -Q: Is it possible to connect my old Atari/Commodore/Amiga/console joystick - or pad that uses a 9-pin D-type cannon connector to the serial port of my - PC? -A: Yes, it is possible, but it'll burn your serial port or the pad. It - won't work, of course. - -Q: My joystick doesn't work with Quake / Quake 2. What's the cause? -A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses - for them. - -6. Programming Interface -~~~~~~~~~~~~~~~~~~~~~~~~ - The 1.0 driver uses a new, event based approach to the joystick driver. -Instead of the user program polling for the joystick values, the joystick -driver now reports only any changes of its state. See joystick-api.txt, -joystick.h and jstest.c included in the joystick package for more -information. The joystick device can be used in either blocking or -nonblocking mode and supports select() calls. - - For backward compatibility the old (v0.x) interface is still included. -Any call to the joystick driver using the old interface will return values -that are compatible to the old interface. This interface is still limited -to 2 axes, and applications using it usually decode only 2 buttons, although -the driver provides up to 32. diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.rst index c51f1146f3bd..8035868c56bc 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.rst @@ -1,6 +1,10 @@ +.. include:: <isonum.txt> + +========================= Multi-touch (MT) Protocol -------------------------- - Copyright (C) 2009-2010 Henrik Rydberg <rydberg@euromail.se> +========================= + +:Copyright: |copy| 2009-2010 Henrik Rydberg <rydberg@euromail.se> Introduction @@ -18,6 +22,9 @@ describes how to send the raw data for all contacts to the receiver. For devices capable of tracking identifiable contacts (type B), the protocol describes how to send updates for individual contacts via event slots. +.. note:: + MT potocol type A is obsolete, all kernel drivers have been + converted to use type B. Protocol Usage -------------- @@ -47,12 +54,12 @@ The main difference between the stateless type A protocol and the stateful type B slot protocol lies in the usage of identifiable contacts to reduce the amount of data sent to userspace. The slot protocol requires the use of the ABS_MT_TRACKING_ID, either provided by the hardware or computed from -the raw data [5]. +the raw data [#f5]_. For type A devices, the kernel driver should generate an arbitrary enumeration of the full set of anonymous contacts currently on the surface. The order in which the packets appear in the event stream is not -important. Event filtering and finger tracking is left to user space [3]. +important. Event filtering and finger tracking is left to user space [#f3]_. For type B devices, the kernel driver should associate a slot with each identified contact, and use that slot to propagate changes for the contact. @@ -86,7 +93,7 @@ Protocol Example A ------------------ Here is what a minimal event sequence for a two-contact touch would look -like for a type A device: +like for a type A device:: ABS_MT_POSITION_X x[0] ABS_MT_POSITION_Y y[0] @@ -100,14 +107,14 @@ The sequence after moving one of the contacts looks exactly the same; the raw data for all present contacts are sent between every synchronization with SYN_REPORT. -Here is the sequence after lifting the first contact: +Here is the sequence after lifting the first contact:: ABS_MT_POSITION_X x[1] ABS_MT_POSITION_Y y[1] SYN_MT_REPORT SYN_REPORT -And here is the sequence after lifting the second contact: +And here is the sequence after lifting the second contact:: SYN_MT_REPORT SYN_REPORT @@ -122,7 +129,7 @@ Protocol Example B ------------------ Here is what a minimal event sequence for a two-contact touch would look -like for a type B device: +like for a type B device:: ABS_MT_SLOT 0 ABS_MT_TRACKING_ID 45 @@ -134,13 +141,13 @@ like for a type B device: ABS_MT_POSITION_Y y[1] SYN_REPORT -Here is the sequence after moving contact 45 in the x direction: +Here is the sequence after moving contact 45 in the x direction:: ABS_MT_SLOT 0 ABS_MT_POSITION_X x[0] SYN_REPORT -Here is the sequence after lifting the contact in slot 0: +Here is the sequence after lifting the contact in slot 0:: ABS_MT_TRACKING_ID -1 SYN_REPORT @@ -149,7 +156,7 @@ The slot being modified is already 0, so the ABS_MT_SLOT is omitted. The message removes the association of slot 0 with contact 45, thereby destroying contact 45 and freeing slot 0 to be reused for another contact. -Finally, here is the sequence after lifting the second contact: +Finally, here is the sequence after lifting the second contact:: ABS_MT_SLOT 1 ABS_MT_TRACKING_ID -1 @@ -181,6 +188,8 @@ ABS_MT_PRESSURE may be used to provide the pressure on the contact area instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to indicate the distance between the contact and the surface. +:: + Linux MT Win8 __________ _______________________ @@ -212,7 +221,7 @@ via ABS_MT_BLOB_ID. The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event -may be used to track identified contacts over time [5]. +may be used to track identified contacts over time [#f5]_. In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are implicitly handled by input core; drivers should instead call @@ -223,117 +232,103 @@ Event Semantics --------------- ABS_MT_TOUCH_MAJOR - -The length of the major axis of the contact. The length should be given in -surface units. If the surface has an X times Y resolution, the largest -possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4]. + The length of the major axis of the contact. The length should be given in + surface units. If the surface has an X times Y resolution, the largest + possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [#f4]_. ABS_MT_TOUCH_MINOR - -The length, in surface units, of the minor axis of the contact. If the -contact is circular, this event can be omitted [4]. + The length, in surface units, of the minor axis of the contact. If the + contact is circular, this event can be omitted [#f4]_. ABS_MT_WIDTH_MAJOR - -The length, in surface units, of the major axis of the approaching -tool. This should be understood as the size of the tool itself. The -orientation of the contact and the approaching tool are assumed to be the -same [4]. + The length, in surface units, of the major axis of the approaching + tool. This should be understood as the size of the tool itself. The + orientation of the contact and the approaching tool are assumed to be the + same [#f4]_. ABS_MT_WIDTH_MINOR + The length, in surface units, of the minor axis of the approaching + tool. Omit if circular [#f4]_. -The length, in surface units, of the minor axis of the approaching -tool. Omit if circular [4]. - -The above four values can be used to derive additional information about -the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates -the notion of pressure. The fingers of the hand and the palm all have -different characteristic widths. + The above four values can be used to derive additional information about + the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates + the notion of pressure. The fingers of the hand and the palm all have + different characteristic widths. ABS_MT_PRESSURE - -The pressure, in arbitrary units, on the contact area. May be used instead -of TOUCH and WIDTH for pressure-based devices or any device with a spatial -signal intensity distribution. + The pressure, in arbitrary units, on the contact area. May be used instead + of TOUCH and WIDTH for pressure-based devices or any device with a spatial + signal intensity distribution. ABS_MT_DISTANCE - -The distance, in surface units, between the contact and the surface. Zero -distance means the contact is touching the surface. A positive number means -the contact is hovering above the surface. + The distance, in surface units, between the contact and the surface. Zero + distance means the contact is touching the surface. A positive number means + the contact is hovering above the surface. ABS_MT_ORIENTATION - -The orientation of the touching ellipse. The value should describe a signed -quarter of a revolution clockwise around the touch center. The signed value -range is arbitrary, but zero should be returned for an ellipse aligned with -the Y axis of the surface, a negative value when the ellipse is turned to -the left, and a positive value when the ellipse is turned to the -right. When completely aligned with the X axis, the range max should be -returned. - -Touch ellipsis are symmetrical by default. For devices capable of true 360 -degree orientation, the reported orientation must exceed the range max to -indicate more than a quarter of a revolution. For an upside-down finger, -range max * 2 should be returned. - -Orientation can be omitted if the touch area is circular, or if the -information is not available in the kernel driver. Partial orientation -support is possible if the device can distinguish between the two axis, but -not (uniquely) any values in between. In such cases, the range of -ABS_MT_ORIENTATION should be [0, 1] [4]. + The orientation of the touching ellipse. The value should describe a signed + quarter of a revolution clockwise around the touch center. The signed value + range is arbitrary, but zero should be returned for an ellipse aligned with + the Y axis of the surface, a negative value when the ellipse is turned to + the left, and a positive value when the ellipse is turned to the + right. When completely aligned with the X axis, the range max should be + returned. + + Touch ellipsis are symmetrical by default. For devices capable of true 360 + degree orientation, the reported orientation must exceed the range max to + indicate more than a quarter of a revolution. For an upside-down finger, + range max * 2 should be returned. + + Orientation can be omitted if the touch area is circular, or if the + information is not available in the kernel driver. Partial orientation + support is possible if the device can distinguish between the two axis, but + not (uniquely) any values in between. In such cases, the range of + ABS_MT_ORIENTATION should be [0, 1] [#f4]_. ABS_MT_POSITION_X - -The surface X coordinate of the center of the touching ellipse. + The surface X coordinate of the center of the touching ellipse. ABS_MT_POSITION_Y - -The surface Y coordinate of the center of the touching ellipse. + The surface Y coordinate of the center of the touching ellipse. ABS_MT_TOOL_X - -The surface X coordinate of the center of the approaching tool. Omit if -the device cannot distinguish between the intended touch point and the -tool itself. + The surface X coordinate of the center of the approaching tool. Omit if + the device cannot distinguish between the intended touch point and the + tool itself. ABS_MT_TOOL_Y + The surface Y coordinate of the center of the approaching tool. Omit if the + device cannot distinguish between the intended touch point and the tool + itself. -The surface Y coordinate of the center of the approaching tool. Omit if the -device cannot distinguish between the intended touch point and the tool -itself. - -The four position values can be used to separate the position of the touch -from the position of the tool. If both positions are present, the major -tool axis points towards the touch point [1]. Otherwise, the tool axes are -aligned with the touch axes. + The four position values can be used to separate the position of the touch + from the position of the tool. If both positions are present, the major + tool axis points towards the touch point [#f1]_. Otherwise, the tool axes are + aligned with the touch axes. ABS_MT_TOOL_TYPE - -The type of approaching tool. A lot of kernel drivers cannot distinguish -between different tool types, such as a finger or a pen. In such cases, the -event should be omitted. The protocol currently supports MT_TOOL_FINGER, -MT_TOOL_PEN, and MT_TOOL_PALM [2]. For type B devices, this event is handled -by input core; drivers should instead use input_mt_report_slot_state(). -A contact's ABS_MT_TOOL_TYPE may change over time while still touching the -device, because the firmware may not be able to determine which tool is being -used when it first appears. + The type of approaching tool. A lot of kernel drivers cannot distinguish + between different tool types, such as a finger or a pen. In such cases, the + event should be omitted. The protocol currently supports MT_TOOL_FINGER, + MT_TOOL_PEN, and MT_TOOL_PALM [#f2]_. For type B devices, this event is + handled by input core; drivers should instead use + input_mt_report_slot_state(). A contact's ABS_MT_TOOL_TYPE may change over + time while still touching the device, because the firmware may not be able + to determine which tool is being used when it first appears. ABS_MT_BLOB_ID - -The BLOB_ID groups several packets together into one arbitrarily shaped -contact. The sequence of points forms a polygon which defines the shape of -the contact. This is a low-level anonymous grouping for type A devices, and -should not be confused with the high-level trackingID [5]. Most type A -devices do not have blob capability, so drivers can safely omit this event. + The BLOB_ID groups several packets together into one arbitrarily shaped + contact. The sequence of points forms a polygon which defines the shape of + the contact. This is a low-level anonymous grouping for type A devices, and + should not be confused with the high-level trackingID [#f5]_. Most type A + devices do not have blob capability, so drivers can safely omit this event. ABS_MT_TRACKING_ID - -The TRACKING_ID identifies an initiated contact throughout its life cycle -[5]. The value range of the TRACKING_ID should be large enough to ensure -unique identification of a contact maintained over an extended period of -time. For type B devices, this event is handled by input core; drivers -should instead use input_mt_report_slot_state(). + The TRACKING_ID identifies an initiated contact throughout its life cycle + [#f5]_. The value range of the TRACKING_ID should be large enough to ensure + unique identification of a contact maintained over an extended period of + time. For type B devices, this event is handled by input core; drivers + should instead use input_mt_report_slot_state(). Event Computation @@ -346,7 +341,7 @@ this section gives recipes for how to compute certain events. For devices reporting contacts as rectangular shapes, signed orientation cannot be obtained. Assuming X and Y are the lengths of the sides of the touching rectangle, here is a simple formula that retains the most -information possible: +information possible:: ABS_MT_TOUCH_MAJOR := max(X, Y) ABS_MT_TOUCH_MINOR := min(X, Y) @@ -356,7 +351,7 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that the device can distinguish between a finger along the Y axis (0) and a finger along the X axis (1). -For win8 devices with both T and C coordinates, the position mapping is +For win8 devices with both T and C coordinates, the position mapping is:: ABS_MT_POSITION_X := T_X ABS_MT_POSITION_Y := T_Y @@ -365,7 +360,7 @@ For win8 devices with both T and C coordinates, the position mapping is Unfortunately, there is not enough information to specify both the touching ellipse and the tool ellipse, so one has to resort to approximations. One -simple scheme, which is compatible with earlier usage, is: +simple scheme, which is compatible with earlier usage, is:: ABS_MT_TOUCH_MAJOR := min(X, Y) ABS_MT_TOUCH_MINOR := <not used> @@ -386,7 +381,7 @@ The process of finger tracking, i.e., to assign a unique trackingID to each initiated contact on the surface, is a Euclidian Bipartite Matching problem. At each event synchronization, the set of actual contacts is matched to the set of contacts from the previous synchronization. A full -implementation can be found in [3]. +implementation can be found in [#f3]_. Gestures @@ -408,11 +403,8 @@ in a finger packet must not be recognized as single-touch events. For type A devices, all finger data bypasses input filtering, since subsequent events of the same type refer to different fingers. -For example usage of the type A protocol, see the bcm5974 driver. For -example usage of the type B protocol, see the hid-egalax driver. - -[1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt. -[2] The list can of course be extended. -[3] The mtdev project: http://bitmath.org/code/mtdev/. -[4] See the section on event computation. -[5] See the section on finger tracking. +.. [#f1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt. +.. [#f2] The list can of course be extended. +.. [#f3] The mtdev project: http://bitmath.org/code/mtdev/. +.. [#f4] See the section on event computation. +.. [#f5] See the section on finger tracking. diff --git a/Documentation/input/notifier.txt b/Documentation/input/notifier.rst index 95172ca6f3d2..161350cb865e 100644 --- a/Documentation/input/notifier.txt +++ b/Documentation/input/notifier.rst @@ -1,4 +1,6 @@ +================= Keyboard notifier +================= One can use register_keyboard_notifier to get called back on keyboard events (see kbd_keycode() function for details). The passed structure is @@ -23,9 +25,9 @@ For each kind of event but the last, the callback may return NOTIFY_STOP in order to "eat" the event: the notify loop is stopped and the keyboard event is dropped. -In a rough C snippet, we have: +In a rough C snippet, we have:: -kbd_keycode(keycode) { + kbd_keycode(keycode) { ... params.value = keycode; if (notifier_call_chain(KBD_KEYCODE,¶ms) == NOTIFY_STOP) @@ -47,6 +49,6 @@ kbd_keycode(keycode) { return; apply keysym; notifier_call_chain(KBD_POST_KEYSYM,¶ms); -} + } -NOTE: This notifier is usually called from interrupt context. +.. note:: This notifier is usually called from interrupt context. diff --git a/Documentation/input/sentelic.txt b/Documentation/input/sentelic.txt deleted file mode 100644 index 89251e2a3eba..000000000000 --- a/Documentation/input/sentelic.txt +++ /dev/null @@ -1,873 +0,0 @@ -Copyright (C) 2002-2011 Sentelic Corporation. -Last update: Dec-07-2011 - -============================================================================== -* Finger Sensing Pad Intellimouse Mode(scrolling wheel, 4th and 5th buttons) -============================================================================== -A) MSID 4: Scrolling wheel mode plus Forward page(4th button) and Backward - page (5th button) -@1. Set sample rate to 200; -@2. Set sample rate to 200; -@3. Set sample rate to 80; -@4. Issuing the "Get device ID" command (0xF2) and waits for the response; -@5. FSP will respond 0x04. - -Packet 1 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|W|W|W|W| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7 => Y overflow - Bit6 => X overflow - Bit5 => Y sign bit - Bit4 => X sign bit - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X Movement(9-bit 2's complement integers) -Byte 3: Y Movement(9-bit 2's complement integers) -Byte 4: Bit3~Bit0 => the scrolling wheel's movement since the last data report. - valid values, -8 ~ +7 - Bit4 => 1 = 4th mouse button is pressed, Forward one page. - 0 = 4th mouse button is not pressed. - Bit5 => 1 = 5th mouse button is pressed, Backward one page. - 0 = 5th mouse button is not pressed. - -B) MSID 6: Horizontal and Vertical scrolling. -@ Set bit 1 in register 0x40 to 1 - -# FSP replaces scrolling wheel's movement as 4 bits to show horizontal and - vertical scrolling. - -Packet 1 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |Y|X|y|x|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 | | |B|F|r|l|u|d| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7 => Y overflow - Bit6 => X overflow - Bit5 => Y sign bit - Bit4 => X sign bit - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X Movement(9-bit 2's complement integers) -Byte 3: Y Movement(9-bit 2's complement integers) -Byte 4: Bit0 => the Vertical scrolling movement downward. - Bit1 => the Vertical scrolling movement upward. - Bit2 => the Horizontal scrolling movement leftward. - Bit3 => the Horizontal scrolling movement rightward. - Bit4 => 1 = 4th mouse button is pressed, Forward one page. - 0 = 4th mouse button is not pressed. - Bit5 => 1 = 5th mouse button is pressed, Backward one page. - 0 = 5th mouse button is not pressed. - -C) MSID 7: -# FSP uses 2 packets (8 Bytes) to represent Absolute Position. - so we have PACKET NUMBER to identify packets. - If PACKET NUMBER is 0, the packet is Packet 1. - If PACKET NUMBER is 1, the packet is Packet 2. - Please count this number in program. - -# MSID6 special packet will be enable at the same time when enable MSID 7. - -============================================================================== -* Absolute position for STL3886-G0. -============================================================================== -@ Set bit 2 or 3 in register 0x40 to 1 -@ Set bit 6 in register 0x40 to 1 - -Packet 1 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|1|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|d|u|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - Bit5 => valid bit - Bit4 => 1 - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => scroll up - Bit5 => scroll down - Bit6 => scroll left - Bit7 => scroll right - -Notify Packet for G0 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|0|1|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |M|M|M|M|M|M|M|M| 4 |0|0|0|0|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - Bit5 => 0 - Bit4 => 1 - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message Type => 0x5A (Enable/Disable status packet) - Mode Type => 0xA5 (Normal/Icon mode status) -Byte 3: Message Type => 0x00 (Disabled) - => 0x01 (Enabled) - Mode Type => 0x00 (Normal) - => 0x01 (Icon) -Byte 4: Bit7~Bit0 => Don't Care - -============================================================================== -* Absolute position for STL3888-Ax. -============================================================================== -Packet 1 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|A|1|L|0|1| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => arc - Bit3 => 1 - Bit2 => Left Button, 1 is pressed, 0 is released. - Bit1 => 0 - Bit0 => 1 -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit5~Bit4 => y1_g - Bit7~Bit6 => x1_g - -Packet 2 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|A|1|R|1|0| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |x|x|y|y|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => arc - Bit3 => 1 - Bit2 => Right Button, 1 is pressed, 0 is released. - Bit1 => 1 - Bit0 => 0 -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit5~Bit4 => y2_g - Bit7~Bit6 => x2_g - -Notify Packet for STL3888-Ax - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|d|u|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => 1 - Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): - 0: left button is generated by the on-pad command - 1: left button is generated by the external button - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) -Byte 3: Bit7~Bit6 => Don't care - Bit5~Bit4 => Number of fingers - Bit3~Bit1 => Reserved - Bit0 => 1: enter gesture mode; 0: leaving gesture mode -Byte 4: Bit7 => scroll right button - Bit6 => scroll left button - Bit5 => scroll down button - Bit4 => scroll up button - * Note that if gesture and additional button (Bit4~Bit7) - happen at the same time, the button information will not - be sent. - Bit3~Bit0 => Reserved - -Sample sequence of Multi-finger, Multi-coordinate mode: - - notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, - abs pkt 2, ..., notify packet (valid bit == 0) - -============================================================================== -* Absolute position for STL3888-B0. -============================================================================== -Packet 1(ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|F|1|0|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => finger up/down information. 1: finger down, 0: finger up. - Bit3 => 1 - Bit2 => finger index, 0 is the first finger, 1 is the second finger. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => scroll down button - Bit5 => scroll up button - Bit6 => scroll left button - Bit7 => scroll right button - -Packet 2 (ABSOLUTE POSITION) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|V|F|1|1|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|u|d|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => Valid bit, 0 means that the coordinate is invalid or finger up. - When both fingers are up, the last two reports have zero valid - bit. - Bit4 => finger up/down information. 1: finger down, 0: finger up. - Bit3 => 1 - Bit2 => finger index, 0 is the first finger, 1 is the second finger. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => scroll down button - Bit5 => scroll up button - Bit6 => scroll left button - Bit7 => scroll right button - -Notify Packet for STL3888-B0 - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|1|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|u|d|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - => 11, Normal data packet with on-pad click - Bit5 => 1 - Bit4 => when in absolute coordinates mode (valid when EN_PKT_GO is 1): - 0: left button is generated by the on-pad command - 1: left button is generated by the external button - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message Type => 0xB7 (Multi Finger, Multi Coordinate mode) -Byte 3: Bit7~Bit6 => Don't care - Bit5~Bit4 => Number of fingers - Bit3~Bit1 => Reserved - Bit0 => 1: enter gesture mode; 0: leaving gesture mode -Byte 4: Bit7 => scroll right button - Bit6 => scroll left button - Bit5 => scroll up button - Bit4 => scroll down button - * Note that if gesture and additional button(Bit4~Bit7) - happen at the same time, the button information will not - be sent. - Bit3~Bit0 => Reserved - -Sample sequence of Multi-finger, Multi-coordinate mode: - - notify packet (valid bit == 1), abs pkt 1, abs pkt 2, abs pkt 1, - abs pkt 2, ..., notify packet (valid bit == 0) - -============================================================================== -* Absolute position for STL3888-Cx and STL3888-Dx. -============================================================================== -Single Finger, Absolute Coordinate Mode (SFAC) - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|0|P|1|M|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|B|F|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - Bit5 => Coordinate mode(always 0 in SFAC mode): - 0: single-finger absolute coordinates (SFAC) mode - 1: multi-finger, multiple coordinates (MFMC) mode - Bit4 => 0: The LEFT button is generated by on-pad command (OPC) - 1: The LEFT button is generated by external button - Default is 1 even if the LEFT button is not pressed. - Bit3 => Always 1, as specified by PS/2 protocol. - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => 4th mouse button(forward one page) - Bit5 => 5th mouse button(backward one page) - Bit6 => scroll left button - Bit7 => scroll right button - -Multi Finger, Multiple Coordinates Mode (MFMC): - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |0|1|1|P|1|F|R|L| 2 |X|X|X|X|X|X|X|X| 3 |Y|Y|Y|Y|Y|Y|Y|Y| 4 |r|l|B|F|X|X|Y|Y| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordination packet - => 10, Notify packet - Bit5 => Coordinate mode (always 1 in MFMC mode): - 0: single-finger absolute coordinates (SFAC) mode - 1: multi-finger, multiple coordinates (MFMC) mode - Bit4 => 0: The LEFT button is generated by on-pad command (OPC) - 1: The LEFT button is generated by external button - Default is 1 even if the LEFT button is not pressed. - Bit3 => Always 1, as specified by PS/2 protocol. - Bit2 => Finger index, 0 is the first finger, 1 is the second finger. - If bit 1 and 0 are all 1 and bit 4 is 0, the middle external - button is pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: X coordinate (xpos[9:2]) -Byte 3: Y coordinate (ypos[9:2]) -Byte 4: Bit1~Bit0 => Y coordinate (xpos[1:0]) - Bit3~Bit2 => X coordinate (ypos[1:0]) - Bit4 => 4th mouse button(forward one page) - Bit5 => 5th mouse button(backward one page) - Bit6 => scroll left button - Bit7 => scroll right button - - When one of the two fingers is up, the device will output four consecutive -MFMC#0 report packets with zero X and Y to represent 1st finger is up or -four consecutive MFMC#1 report packets with zero X and Y to represent that -the 2nd finger is up. On the other hand, if both fingers are up, the device -will output four consecutive single-finger, absolute coordinate(SFAC) packets -with zero X and Y. - -Notify Packet for STL3888-Cx/Dx - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |1|0|0|P|1|M|R|L| 2 |C|C|C|C|C|C|C|C| 3 |0|0|F|F|0|0|0|i| 4 |r|l|u|d|0|0|0|0| - |---------------| |---------------| |---------------| |---------------| - -Byte 1: Bit7~Bit6 => 00, Normal data packet - => 01, Absolute coordinates packet - => 10, Notify packet - Bit5 => Always 0 - Bit4 => 0: The LEFT button is generated by on-pad command(OPC) - 1: The LEFT button is generated by external button - Default is 1 even if the LEFT button is not pressed. - Bit3 => 1 - Bit2 => Middle Button, 1 is pressed, 0 is not pressed. - Bit1 => Right Button, 1 is pressed, 0 is not pressed. - Bit0 => Left Button, 1 is pressed, 0 is not pressed. -Byte 2: Message type: - 0xba => gesture information - 0xc0 => one finger hold-rotating gesture -Byte 3: The first parameter for the received message: - 0xba => gesture ID (refer to the 'Gesture ID' section) - 0xc0 => region ID -Byte 4: The second parameter for the received message: - 0xba => N/A - 0xc0 => finger up/down information - -Sample sequence of Multi-finger, Multi-coordinates mode: - - notify packet (valid bit == 1), MFMC packet 1 (byte 1, bit 2 == 0), - MFMC packet 2 (byte 1, bit 2 == 1), MFMC packet 1, MFMC packet 2, - ..., notify packet (valid bit == 0) - - That is, when the device is in MFMC mode, the host will receive - interleaved absolute coordinate packets for each finger. - -============================================================================== -* FSP Enable/Disable packet -============================================================================== - Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -BYTE |---------------|BYTE |---------------|BYTE|---------------|BYTE|---------------| - 1 |Y|X|0|0|1|M|R|L| 2 |0|1|0|1|1|0|1|E| 3 | | | | | | | | | 4 | | | | | | | | | - |---------------| |---------------| |---------------| |---------------| - -FSP will send out enable/disable packet when FSP receive PS/2 enable/disable -command. Host will receive the packet which Middle, Right, Left button will -be set. The packet only use byte 0 and byte 1 as a pattern of original packet. -Ignore the other bytes of the packet. - -Byte 1: Bit7 => 0, Y overflow - Bit6 => 0, X overflow - Bit5 => 0, Y sign bit - Bit4 => 0, X sign bit - Bit3 => 1 - Bit2 => 1, Middle Button - Bit1 => 1, Right Button - Bit0 => 1, Left Button -Byte 2: Bit7~1 => (0101101b) - Bit0 => 1 = Enable - 0 = Disable -Byte 3: Don't care -Byte 4: Don't care (MOUSE ID 3, 4) -Byte 5~8: Don't care (Absolute packet) - -============================================================================== -* PS/2 Command Set -============================================================================== - -FSP supports basic PS/2 commanding set and modes, refer to following URL for -details about PS/2 commands: - -http://www.computer-engineering.org/ps2mouse/ - -============================================================================== -* Programming Sequence for Determining Packet Parsing Flow -============================================================================== -1. Identify FSP by reading device ID(0x00) and version(0x01) register - -2a. For FSP version < STL3888 Cx, determine number of buttons by reading - the 'test mode status' (0x20) register: - - buttons = reg[0x20] & 0x30 - - if buttons == 0x30 or buttons == 0x20: - # two/four buttons - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section A for packet parsing detail(ignore byte 4, bit ~ 7) - elif buttons == 0x10: - # 6 buttons - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section B for packet parsing detail - elif buttons == 0x00: - # 6 buttons - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section A for packet parsing detail - -2b. For FSP version >= STL3888 Cx: - Refer to 'Finger Sensing Pad PS/2 Mouse Intellimouse' - section A for packet parsing detail (ignore byte 4, bit ~ 7) - -============================================================================== -* Programming Sequence for Register Reading/Writing -============================================================================== - -Register inversion requirement: - - Following values needed to be inverted(the '~' operator in C) before being -sent to FSP: - - 0xe8, 0xe9, 0xee, 0xf2, 0xf3 and 0xff. - -Register swapping requirement: - - Following values needed to have their higher 4 bits and lower 4 bits being -swapped before being sent to FSP: - - 10, 20, 40, 60, 80, 100 and 200. - -Register reading sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. send 0x66 PS/2 command to FSP; - - 3. send 0x88 PS/2 command to FSP; - - 4. send 0xf3 PS/2 command to FSP; - - 5. if the register address being to read is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 6 - - 5a. send 0x68 PS/2 command to FSP; - - 5b. send the inverted register address to FSP and goto step 8; - - 6. if the register address being to read is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 7 - - 6a. send 0xcc PS/2 command to FSP; - - 6b. send the swapped register address to FSP and goto step 8; - - 7. send 0x66 PS/2 command to FSP; - - 7a. send the original register address to FSP and goto step 8; - - 8. send 0xe9(status request) PS/2 command to FSP; - - 9. the 4th byte of the response read from FSP should be the - requested register value(?? indicates don't care byte): - - host: 0xe9 - 3888: 0xfa (??) (??) (val) - - * Note that since the Cx release, the hardware will return 1's - complement of the register value at the 3rd byte of status request - result: - - host: 0xe9 - 3888: 0xfa (??) (~val) (val) - -Register writing sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. if the register address being to write is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 3 - - 2a. send 0x74 PS/2 command to FSP; - - 2b. send the inverted register address to FSP and goto step 5; - - 3. if the register address being to write is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 4 - - 3a. send 0x77 PS/2 command to FSP; - - 3b. send the swapped register address to FSP and goto step 5; - - 4. send 0x55 PS/2 command to FSP; - - 4a. send the register address to FSP and goto step 5; - - 5. send 0xf3 PS/2 command to FSP; - - 6. if the register value being to write is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 7 - - 6a. send 0x47 PS/2 command to FSP; - - 6b. send the inverted register value to FSP and goto step 9; - - 7. if the register value being to write is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 8 - - 7a. send 0x44 PS/2 command to FSP; - - 7b. send the swapped register value to FSP and goto step 9; - - 8. send 0x33 PS/2 command to FSP; - - 8a. send the register value to FSP; - - 9. the register writing sequence is completed. - - * Note that since the Cx release, the hardware will return 1's - complement of the register value at the 3rd byte of status request - result. Host can optionally send another 0xe9 (status request) PS/2 - command to FSP at the end of register writing to verify that the - register writing operation is successful (?? indicates don't care - byte): - - host: 0xe9 - 3888: 0xfa (??) (~val) (val) - -============================================================================== -* Programming Sequence for Page Register Reading/Writing -============================================================================== - - In order to overcome the limitation of maximum number of registers -supported, the hardware separates register into different groups called -'pages.' Each page is able to include up to 255 registers. - - The default page after power up is 0x82; therefore, if one has to get -access to register 0x8301, one has to use following sequence to switch -to page 0x83, then start reading/writing from/to offset 0x01 by using -the register read/write sequence described in previous section. - -Page register reading sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. send 0x66 PS/2 command to FSP; - - 3. send 0x88 PS/2 command to FSP; - - 4. send 0xf3 PS/2 command to FSP; - - 5. send 0x83 PS/2 command to FSP; - - 6. send 0x88 PS/2 command to FSP; - - 7. send 0xe9(status request) PS/2 command to FSP; - - 8. the response read from FSP should be the requested page value. - -Page register writing sequence: - - 1. send 0xf3 PS/2 command to FSP; - - 2. send 0x38 PS/2 command to FSP; - - 3. send 0x88 PS/2 command to FSP; - - 4. send 0xf3 PS/2 command to FSP; - - 5. if the page address being written is not required to be - inverted(refer to the 'Register inversion requirement' section), - goto step 6 - - 5a. send 0x47 PS/2 command to FSP; - - 5b. send the inverted page address to FSP and goto step 9; - - 6. if the page address being written is not required to be - swapped(refer to the 'Register swapping requirement' section), - goto step 7 - - 6a. send 0x44 PS/2 command to FSP; - - 6b. send the swapped page address to FSP and goto step 9; - - 7. send 0x33 PS/2 command to FSP; - - 8. send the page address to FSP; - - 9. the page register writing sequence is completed. - -============================================================================== -* Gesture ID -============================================================================== - - Unlike other devices which sends multiple fingers' coordinates to host, -FSP processes multiple fingers' coordinates internally and convert them -into a 8 bits integer, namely 'Gesture ID.' Following is a list of -supported gesture IDs: - - ID Description - 0x86 2 finger straight up - 0x82 2 finger straight down - 0x80 2 finger straight right - 0x84 2 finger straight left - 0x8f 2 finger zoom in - 0x8b 2 finger zoom out - 0xc0 2 finger curve, counter clockwise - 0xc4 2 finger curve, clockwise - 0x2e 3 finger straight up - 0x2a 3 finger straight down - 0x28 3 finger straight right - 0x2c 3 finger straight left - 0x38 palm - -============================================================================== -* Register Listing -============================================================================== - - Registers are represented in 16 bits values. The higher 8 bits represent -the page address and the lower 8 bits represent the relative offset within -that particular page. Refer to the 'Programming Sequence for Page Register -Reading/Writing' section for instructions on how to change current page -address. - -offset width default r/w name -0x8200 bit7~bit0 0x01 RO device ID - -0x8201 bit7~bit0 RW version ID - 0xc1: STL3888 Ax - 0xd0 ~ 0xd2: STL3888 Bx - 0xe0 ~ 0xe1: STL3888 Cx - 0xe2 ~ 0xe3: STL3888 Dx - -0x8202 bit7~bit0 0x01 RO vendor ID - -0x8203 bit7~bit0 0x01 RO product ID - -0x8204 bit3~bit0 0x01 RW revision ID - -0x820b test mode status 1 - bit3 1 RO 0: rotate 180 degree - 1: no rotation - *only supported by H/W prior to Cx - -0x820f register file page control - bit2 0 RW 1: rotate 180 degree - 0: no rotation - *supported since Cx - - bit0 0 RW 1 to enable page 1 register files - *only supported by H/W prior to Cx - -0x8210 RW system control 1 - bit0 1 RW Reserved, must be 1 - bit1 0 RW Reserved, must be 0 - bit4 0 RW Reserved, must be 0 - bit5 1 RW register clock gating enable - 0: read only, 1: read/write enable - (Note that following registers does not require clock gating being - enabled prior to write: 05 06 07 08 09 0c 0f 10 11 12 16 17 18 23 2e - 40 41 42 43. In addition to that, this bit must be 1 when gesture - mode is enabled) - -0x8220 test mode status - bit5~bit4 RO number of buttons - 11 => 2, lbtn/rbtn - 10 => 4, lbtn/rbtn/scru/scrd - 01 => 6, lbtn/rbtn/scru/scrd/scrl/scrr - 00 => 6, lbtn/rbtn/scru/scrd/fbtn/bbtn - *only supported by H/W prior to Cx - -0x8231 RW on-pad command detection - bit7 0 RW on-pad command left button down tag - enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8234 RW on-pad command control 5 - bit4~bit0 0x05 RW XLO in 0s/4/1, so 03h = 0010.1b = 2.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - - bit7 0 RW on-pad tap zone enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8235 RW on-pad command control 6 - bit4~bit0 0x1d RW XHI in 0s/4/1, so 19h = 1100.1b = 12.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - -0x8236 RW on-pad command control 7 - bit4~bit0 0x04 RW YLO in 0s/4/1, so 03h = 0010.1b = 2.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - -0x8237 RW on-pad command control 8 - bit4~bit0 0x13 RW YHI in 0s/4/1, so 11h = 1000.1b = 8.5 - (Note that position unit is in 0.5 scanline) - *only supported by H/W prior to Cx - -0x8240 RW system control 5 - bit1 0 RW FSP Intellimouse mode enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - - bit2 0 RW movement + abs. coordinate mode enable - 0: disable, 1: enable - (Note that this function has the functionality of bit 1 even when - bit 1 is not set. However, the format is different from that of bit 1. - In addition, when bit 1 and bit 2 are set at the same time, bit 2 will - override bit 1.) - *only supported by H/W prior to Cx - - bit3 0 RW abs. coordinate only mode enable - 0: disable, 1: enable - (Note that this function has the functionality of bit 1 even when - bit 1 is not set. However, the format is different from that of bit 1. - In addition, when bit 1, bit 2 and bit 3 are set at the same time, - bit 3 will override bit 1 and 2.) - *only supported by H/W prior to Cx - - bit5 0 RW auto switch enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - - bit6 0 RW G0 abs. + notify packet format enable - 0: disable, 1: enable - (Note that the absolute/relative coordinate output still depends on - bit 2 and 3. That is, if any of those bit is 1, host will receive - absolute coordinates; otherwise, host only receives packets with - relative coordinate.) - *only supported by H/W prior to Cx - - bit7 0 RW EN_PS2_F2: PS/2 gesture mode 2nd - finger packet enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8243 RW on-pad control - bit0 0 RW on-pad control enable - 0: disable, 1: enable - (Note that if this bit is cleared, bit 3/5 will be ineffective) - *only supported by H/W prior to Cx - - bit3 0 RW on-pad fix vertical scrolling enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - - bit5 0 RW on-pad fix horizontal scrolling enable - 0: disable, 1: enable - *only supported by H/W prior to Cx - -0x8290 RW software control register 1 - bit0 0 RW absolute coordination mode - 0: disable, 1: enable - *supported since Cx - - bit1 0 RW gesture ID output - 0: disable, 1: enable - *supported since Cx - - bit2 0 RW two fingers' coordinates output - 0: disable, 1: enable - *supported since Cx - - bit3 0 RW finger up one packet output - 0: disable, 1: enable - *supported since Cx - - bit4 0 RW absolute coordination continuous mode - 0: disable, 1: enable - *supported since Cx - - bit6~bit5 00 RW gesture group selection - 00: basic - 01: suite - 10: suite pro - 11: advanced - *supported since Cx - - bit7 0 RW Bx packet output compatible mode - 0: disable, 1: enable *supported since Cx - *supported since Cx - - -0x833d RW on-pad command control 1 - bit7 1 RW on-pad command detection enable - 0: disable, 1: enable - *supported since Cx - -0x833e RW on-pad command detection - bit7 0 RW on-pad command left button down tag - enable. Works only in H/W based PS/2 - data packet mode. - 0: disable, 1: enable - *supported since Cx diff --git a/Documentation/input/shape.fig b/Documentation/input/shape.fig deleted file mode 100644 index c22bff83d06f..000000000000 --- a/Documentation/input/shape.fig +++ /dev/null @@ -1,65 +0,0 @@ -#FIG 3.2 -Landscape -Center -Inches -Letter -100.00 -Single --2 -1200 2 -2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 6 - 4200 3600 4200 3075 4950 2325 7425 2325 8250 3150 8250 3600 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 4200 3675 4200 5400 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 8250 3675 8250 5400 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 3675 3600 8700 3600 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 8775 3600 10200 3600 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 8325 3150 9075 3150 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 7500 2325 10200 2325 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 3600 3600 3000 3600 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 4125 3075 3000 3075 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 4200 5400 8175 5400 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 10125 2325 10125 3600 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 3000 3150 3000 3600 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 9075 3150 9075 3600 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 4950 2325 4950 1200 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 2 - 7425 2325 7425 1200 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 - 4200 3075 4200 2400 3600 1800 3600 1200 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 0 0 4 - 8250 3150 8250 2475 8775 1950 8775 1200 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 3600 1275 4950 1275 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 7425 1275 8700 1275 -4 1 0 50 0 0 12 0.0000 4 135 1140 6075 5325 Effect duration\001 -4 0 0 50 0 0 12 0.0000 4 180 1305 10200 3000 Effect magnitude\001 -4 0 0 50 0 0 12 0.0000 4 135 780 9150 3450 Fade level\001 -4 1 0 50 0 0 12 0.0000 4 180 1035 4275 1200 Attack length\001 -4 1 0 50 0 0 12 0.0000 4 180 885 8175 1200 Fade length\001 -4 2 0 50 0 0 12 0.0000 4 135 930 2925 3375 Attack level\001 diff --git a/Documentation/input/shape.svg b/Documentation/input/shape.svg new file mode 100644 index 000000000000..fc0af44db3f7 --- /dev/null +++ b/Documentation/input/shape.svg @@ -0,0 +1,39 @@ +<svg width="7.95in" height="3.70in" version="1.1" viewBox="1956 1041 9354.492 4306.001" xmlns="http://www.w3.org/2000/svg"> + <polyline transform="translate(-121.88 -68.4)" points="4200 3600 4200 3075 4950 2325 7425 2325 8250 3150 8250 3600" fill="none" stroke="#000" stroke-width="15"/> + <polyline transform="translate(-121.88 -68.4)" points="4200 3675 4200 5400" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="8250 3675 8250 5400" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="3675 3600 8700 3600" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="8775 3600 10200 3600" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="8325 3150 9075 3150" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="7500 2325 10200 2325" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="3600 3600 3e3 3600" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="4125 3075 3e3 3075" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="4217 5400 8158 5400" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="8053 5430 8173 5400 8053 5370" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="4322 5370 4202 5400 4322 5430" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="10125 2342 10125 3583" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="10095 3478 10125 3598 10155 3478" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="10155 2447 10125 2327 10095 2447" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="3e3 3167 3e3 3583" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="2970 3478 3e3 3598 3030 3478" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="3030 3272 3e3 3152 2970 3272" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="9075 3167 9075 3583" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="9045 3478 9075 3598 9105 3478" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="9105 3272 9075 3152 9045 3272" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="4950 2325 4950 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="7425 2325 7425 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="4200 3075 4200 2400 3600 1800 3600 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="8250 3150 8250 2475 8775 1950 8775 1200" fill="none" stroke="#000" stroke-dasharray="40, 40" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="3617 1275 4933 1275" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="4828 1305 4948 1275 4828 1245" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="3722 1245 3602 1275 3722 1305" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="7442 1275 8683 1275" fill="none" stroke="#000" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="8578 1305 8698 1275 8578 1245" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <polyline transform="translate(-121.88 -68.4)" points="7547 1245 7427 1275 7547 1305" fill="none" stroke="#000" stroke-miterlimit="8" stroke-width="7"/> + <text x="5953.125" y="5256.6001" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Effect duration</text> + <text x="10078.125" y="2931.5999" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" xml:space="preserve">Effect magnitude</text> + <text x="9028.125" y="3381.5999" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" xml:space="preserve">Fade level</text> + <text x="4153.125" y="1131.6" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Attack length</text> + <text x="8053.125" y="1131.6" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="middle" xml:space="preserve">Fade length</text> + <text x="2803.125" y="3306.5999" fill="#000000" font-family="sans-serif" font-size="144px" stroke-width=".025in" text-anchor="end" xml:space="preserve">Attack level</text> +</svg> diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst new file mode 100644 index 000000000000..b8e90b6a126c --- /dev/null +++ b/Documentation/input/uinput.rst @@ -0,0 +1,245 @@ +============= +uinput module +============= + +Introduction +============ + +uinput is a kernel module that makes it possible to emulate input devices +from userspace. By writing to /dev/uinput (or /dev/input/uinput) device, a +process can create a virtual input device with specific capabilities. Once +this virtual device is created, the process can send events through it, +that will be delivered to userspace and in-kernel consumers. + +Interface +========= + +:: + + linux/uinput.h + +The uinput header defines ioctls to create, set up, and destroy virtual +devices. + +libevdev +======== + +libevdev is a wrapper library for evdev devices that provides interfaces to +create uinput devices and send events. libevdev is less error-prone than +accessing uinput directly, and should be considered for new software. + +For examples and more information about libevdev: +https://www.freedesktop.org/software/libevdev/doc/latest/ + +Examples +======== + +Keyboard events +--------------- + +This first example shows how to create a new virtual device, and how to +send a key event. All default imports and error handlers were removed for +the sake of simplicity. + +.. code-block:: c + + #include <linux/uinput.h> + + void emit(int fd, int type, int code, int val) + { + struct input_event ie; + + ie.type = type; + ie.code = code; + ie.value = val; + /* timestamp values below are ignored */ + ie.time.tv_sec = 0; + ie.time.tv_usec = 0; + + write(fd, &ie, sizeof(ie)); + } + + int main(void) + { + struct uinput_setup usetup; + + int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK); + + + /* + * The ioctls below will enable the device that is about to be + * created, to pass key events, in this case the space key. + */ + ioctl(fd, UI_SET_EVBIT, EV_KEY); + ioctl(fd, UI_SET_KEYBIT, KEY_SPACE); + + memset(&usetup, 0, sizeof(usetup)); + usetup.id.bustype = BUS_USB; + usetup.id.vendor = 0x1234; /* sample vendor */ + usetup.id.product = 0x5678; /* sample product */ + strcpy(usetup.name, "Example device"); + + ioctl(fd, UI_DEV_SETUP, &usetup); + ioctl(fd, UI_DEV_CREATE); + + /* + * On UI_DEV_CREATE the kernel will create the device node for this + * device. We are inserting a pause here so that userspace has time + * to detect, initialize the new device, and can start listening to + * the event, otherwise it will not notice the event we are about + * to send. This pause is only needed in our example code! + */ + sleep(1); + + /* Key press, report the event, send key release, and report again */ + emit(fd, EV_KEY, KEY_SPACE, 1); + emit(fd, EV_SYN, SYN_REPORT, 0); + emit(fd, EV_KEY, KEY_SPACE, 0); + emit(fd, EV_SYN, SYN_REPORT, 0); + + /* + * Give userspace some time to read the events before we destroy the + * device with UI_DEV_DESTOY. + */ + sleep(1); + + ioctl(fd, UI_DEV_DESTROY); + close(fd); + + return 0; + } + +Mouse movements +--------------- + +This example shows how to create a virtual device that behaves like a physical +mouse. + +.. code-block:: c + + #include <linux/uinput.h> + + /* emit function is identical to of the first example */ + + int main(void) + { + struct uinput_setup usetup; + int i = 50; + + int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK); + + /* enable mouse button left and relative events */ + ioctl(fd, UI_SET_EVBIT, EV_KEY); + ioctl(fd, UI_SET_KEYBIT, BTN_LEFT); + + ioctl(fd, UI_SET_EVBIT, EV_REL); + ioctl(fd, UI_SET_RELBIT, REL_X); + ioctl(fd, UI_SET_RELBIT, REL_Y); + + memset(&usetup, 0, sizeof(usetup)); + usetup.id.bustype = BUS_USB; + usetup.id.vendor = 0x1234; /* sample vendor */ + usetup.id.product = 0x5678; /* sample product */ + strcpy(usetup.name, "Example device"); + + ioctl(fd, UI_DEV_SETUP, &usetup); + ioctl(fd, UI_DEV_CREATE); + + /* + * On UI_DEV_CREATE the kernel will create the device node for this + * device. We are inserting a pause here so that userspace has time + * to detect, initialize the new device, and can start listening to + * the event, otherwise it will not notice the event we are about + * to send. This pause is only needed in our example code! + */ + sleep(1); + + /* Move the mouse diagonally, 5 units per axis */ + while (i--) { + emit(fd, EV_REL, REL_X, 5); + emit(fd, EV_REL, REL_Y, 5); + emit(fd, EV_SYN, SYN_REPORT, 0); + usleep(15000); + } + + /* + * Give userspace some time to read the events before we destroy the + * device with UI_DEV_DESTOY. + */ + sleep(1); + + ioctl(fd, UI_DEV_DESTROY); + close(fd); + + return 0; + } + + +uinput old interface +-------------------- + +Before uinput version 5, there wasn't a dedicated ioctl to set up a virtual +device. Programs supportinf older versions of uinput interface need to fill +a uinput_user_dev structure and write it to the uinput file descriptor to +configure the new uinput device. New code should not use the old interface +but interact with uinput via ioctl calls, or use libevdev. + +.. code-block:: c + + #include <linux/uinput.h> + + /* emit function is identical to of the first example */ + + int main(void) + { + struct uinput_user_dev uud; + int version, rc, fd; + + fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK); + rc = ioctl(fd, UI_GET_VERSION, &version); + + if (rc == 0 && version >= 5) { + /* use UI_DEV_SETUP */ + return 0; + } + + /* + * The ioctls below will enable the device that is about to be + * created, to pass key events, in this case the space key. + */ + ioctl(fd, UI_SET_EVBIT, EV_KEY); + ioctl(fd, UI_SET_KEYBIT, KEY_SPACE); + + memset(&uud, 0, sizeof(uud)); + snprintf(uud.name, UINPUT_MAX_NAME_SIZE, "uinput old interface"); + write(fd, &uud, sizeof(uud)); + + ioctl(fd, UI_DEV_CREATE); + + /* + * On UI_DEV_CREATE the kernel will create the device node for this + * device. We are inserting a pause here so that userspace has time + * to detect, initialize the new device, and can start listening to + * the event, otherwise it will not notice the event we are about + * to send. This pause is only needed in our example code! + */ + sleep(1); + + /* Key press, report the event, send key release, and report again */ + emit(fd, EV_KEY, KEY_SPACE, 1); + emit(fd, EV_SYN, SYN_REPORT, 0); + emit(fd, EV_KEY, KEY_SPACE, 0); + emit(fd, EV_SYN, SYN_REPORT, 0); + + /* + * Give userspace some time to read the events before we destroy the + * device with UI_DEV_DESTOY. + */ + sleep(1); + + ioctl(fd, UI_DEV_DESTROY); + + close(fd); + return 0; + } + diff --git a/Documentation/input/userio.txt b/Documentation/input/userio.rst index 0880c0f447a6..f780c77931fe 100644 --- a/Documentation/input/userio.txt +++ b/Documentation/input/userio.rst @@ -1,37 +1,47 @@ - The userio Protocol - (c) 2015 Stephen Chandler Paul <thatslyude@gmail.com> - Sponsored by Red Hat --------------------------------------------------------------------------------- - -1. Introduction -~~~~~~~~~~~~~~~ - This module is intended to try to make the lives of input driver developers +.. include:: <isonum.txt> + +=================== +The userio Protocol +=================== + + +:Copyright: |copy| 2015 Stephen Chandler Paul <thatslyude@gmail.com> + +Sponsored by Red Hat + + +Introduction +============= + +This module is intended to try to make the lives of input driver developers easier by allowing them to test various serio devices (mainly the various touchpads found on laptops) without having to have the physical device in front of them. userio accomplishes this by allowing any privileged userspace program to directly interact with the kernel's serio driver and control a virtual serio port from there. -2. Usage overview -~~~~~~~~~~~~~~~~~ - In order to interact with the userio kernel module, one simply opens the +Usage overview +============== + +In order to interact with the userio kernel module, one simply opens the /dev/userio character device in their applications. Commands are sent to the kernel module by writing to the device, and any data received from the serio driver is read as-is from the /dev/userio device. All of the structures and macros you need to interact with the device are defined in <linux/userio.h> and <linux/serio.h>. -3. Command Structure -~~~~~~~~~~~~~~~~~~~~ - The struct used for sending commands to /dev/userio is as follows: +Command Structure +================= + +The struct used for sending commands to /dev/userio is as follows:: struct userio_cmd { __u8 type; __u8 data; }; - "type" describes the type of command that is being sent. This can be any one -of the USERIO_CMD macros defined in <linux/userio.h>. "data" is the argument +``type`` describes the type of command that is being sent. This can be any one +of the USERIO_CMD macros defined in <linux/userio.h>. ``data`` is the argument that goes along with the command. In the event that the command doesn't have an argument, this field can be left untouched and will be ignored by the kernel. Each command should be sent by writing the struct directly to the character @@ -39,31 +49,36 @@ device. In the event that the command you send is invalid, an error will be returned by the character device and a more descriptive error will be printed to the kernel log. Only one command can be sent at a time, any additional data written to the character device after the initial command will be ignored. - To close the virtual serio port, just close /dev/userio. -4. Commands -~~~~~~~~~~~ +To close the virtual serio port, just close /dev/userio. + +Commands +======== + +USERIO_CMD_REGISTER +~~~~~~~~~~~~~~~~~~~ -4.1 USERIO_CMD_REGISTER -~~~~~~~~~~~~~~~~~~~~~~~ - Registers the port with the serio driver and begins transmitting data back and +Registers the port with the serio driver and begins transmitting data back and forth. Registration can only be performed once a port type is set with USERIO_CMD_SET_PORT_TYPE. Has no argument. -4.2 USERIO_CMD_SET_PORT_TYPE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Sets the type of port we're emulating, where "data" is the port type being +USERIO_CMD_SET_PORT_TYPE +~~~~~~~~~~~~~~~~~~~~~~~~ + +Sets the type of port we're emulating, where ``data`` is the port type being set. Can be any of the macros from <linux/serio.h>. For example: SERIO_8042 would set the port type to be a normal PS/2 port. -4.3 USERIO_CMD_SEND_INTERRUPT -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Sends an interrupt through the virtual serio port to the serio driver, where -"data" is the interrupt data being sent. +USERIO_CMD_SEND_INTERRUPT +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sends an interrupt through the virtual serio port to the serio driver, where +``data`` is the interrupt data being sent. + +Userspace tools +=============== -5. Userspace tools -~~~~~~~~~~~~~~~~~~ - The userio userspace tools are able to record PS/2 devices using some of the +The userio userspace tools are able to record PS/2 devices using some of the debugging information from i8042, and play back the devices on /dev/userio. The latest version of these tools can be found at: diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 08244bea5048..eccb675a2852 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -191,6 +191,7 @@ Code Seq#(hex) Include File Comments '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 @@ -212,7 +213,7 @@ Code Seq#(hex) Include File Comments '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' 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! diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index b0eb27b956d9..615434d81108 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -18,7 +18,7 @@ memory image to a dump file on the local disk, or across the network to a remote system. Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64, -s390x and arm architectures. +s390x, arm and arm64 architectures. When the system kernel boots, it reserves a small section of memory for the dump-capture kernel. This ensures that ongoing Direct Memory Access @@ -249,6 +249,13 @@ Dump-capture kernel config options (Arch Dependent, arm) AUTO_ZRELADDR=y +Dump-capture kernel config options (Arch Dependent, arm64) +---------------------------------------------------------- + +- Please note that kvm of the dump-capture kernel will not be enabled + on non-VHE systems even if it is configured. This is because the CPU + will not be reset to EL2 on panic. + Extended crashkernel syntax =========================== @@ -305,6 +312,8 @@ Boot into System Kernel kernel will automatically locate the crash kernel image within the first 512MB of RAM if X is not given. + On arm64, use "crashkernel=Y[@X]". Note that the start address of + the kernel, X if explicitly specified, must be aligned to 2MiB (0x200000). Load the Dump-capture Kernel ============================ @@ -327,6 +336,8 @@ For s390x: - Use image or bzImage For arm: - Use zImage +For arm64: + - Use vmlinux or Image If you are using a uncompressed vmlinux image then use following command to load dump-capture kernel. @@ -370,6 +381,9 @@ For s390x: For arm: "1 maxcpus=1 reset_devices" +For arm64: + "1 maxcpus=1 reset_devices" + Notes on loading the dump-capture kernel: * By default, the ELF headers are stored in ELF64 format to support diff --git a/Documentation/kref.txt b/Documentation/kref.txt index ddf85a5dde0c..d26a27ca964d 100644 --- a/Documentation/kref.txt +++ b/Documentation/kref.txt @@ -84,6 +84,7 @@ int my_data_handler(void) task = kthread_run(more_data_handling, data, "more_data_handling"); if (task == ERR_PTR(-ENOMEM)) { rv = -ENOMEM; + kref_put(&data->refcount, data_release); goto out; } diff --git a/Documentation/leds/leds-lp55xx.txt b/Documentation/leds/leds-lp55xx.txt index bcea12a0c584..e23fa91ea722 100644 --- a/Documentation/leds/leds-lp55xx.txt +++ b/Documentation/leds/leds-lp55xx.txt @@ -117,7 +117,7 @@ As soon as 'loading' is set to 0, registered callback is called. Inside the callback, the selected engine is loaded and memory is updated. To run programmed pattern, 'run_engine' attribute should be enabled. -The pattern sqeuence of LP8501 is similar to LP5523. +The pattern sequence of LP8501 is similar to LP5523. However pattern data is specific. Ex 1) Engine 1 is used echo 1 > /sys/bus/i2c/devices/xxxx/select_engine diff --git a/Documentation/lightnvm/pblk.txt b/Documentation/lightnvm/pblk.txt new file mode 100644 index 000000000000..1040ed1cec81 --- /dev/null +++ b/Documentation/lightnvm/pblk.txt @@ -0,0 +1,21 @@ +pblk: Physical Block Device Target +================================== + +pblk implements a fully associative, host-based FTL that exposes a traditional +block I/O interface. Its primary responsibilities are: + + - Map logical addresses onto physical addresses (4KB granularity) in a + logical-to-physical (L2P) table. + - Maintain the integrity and consistency of the L2P table as well as its + recovery from normal tear down and power outage. + - Deal with controller- and media-specific constrains. + - Handle I/O errors. + - Implement garbage collection. + - Maintain consistency across the I/O stack during synchronization points. + +For more information please refer to: + + http://lightnvm.io + +which maintains updated FAQs, manual pages, technical documentation, tools, +contacts, etc. diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt index 9d2096c7160d..ecdb18104ab0 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.txt @@ -72,7 +72,8 @@ example, they add a NULL pointer or a boundary check, fix a race by adding a missing memory barrier, or add some locking around a critical section. Most of these changes are self contained and the function presents itself the same way to the rest of the system. In this case, the functions might -be updated independently one by one. +be updated independently one by one. (This can be done by setting the +'immediate' flag in the klp_patch struct.) But there are more complex fixes. For example, a patch might change ordering of locking in multiple functions at the same time. Or a patch @@ -86,20 +87,141 @@ or no data are stored in the modified structures at the moment. The theory about how to apply functions a safe way is rather complex. The aim is to define a so-called consistency model. It attempts to define conditions when the new implementation could be used so that the system -stays consistent. The theory is not yet finished. See the discussion at -https://lkml.kernel.org/r/20141107140458.GA21774@suse.cz - -The current consistency model is very simple. It guarantees that either -the old or the new function is called. But various functions get redirected -one by one without any synchronization. - -In other words, the current implementation _never_ modifies the behavior -in the middle of the call. It is because it does _not_ rewrite the entire -function in the memory. Instead, the function gets redirected at the -very beginning. But this redirection is used immediately even when -some other functions from the same patch have not been redirected yet. - -See also the section "Limitations" below. +stays consistent. + +Livepatch has a consistency model which is a hybrid of kGraft and +kpatch: it uses kGraft's per-task consistency and syscall barrier +switching combined with kpatch's stack trace switching. There are also +a number of fallback options which make it quite flexible. + +Patches are applied on a per-task basis, when the task is deemed safe to +switch over. When a patch is enabled, livepatch enters into a +transition state where tasks are converging to the patched state. +Usually this transition state can complete in a few seconds. The same +sequence occurs when a patch is disabled, except the tasks converge from +the patched state to the unpatched state. + +An interrupt handler inherits the patched state of the task it +interrupts. The same is true for forked tasks: the child inherits the +patched state of the parent. + +Livepatch uses several complementary approaches to determine when it's +safe to patch tasks: + +1. The first and most effective approach is stack checking of sleeping + tasks. If no affected functions are on the stack of a given task, + the task is patched. In most cases this will patch most or all of + the tasks on the first try. Otherwise it'll keep trying + periodically. This option is only available if the architecture has + reliable stacks (HAVE_RELIABLE_STACKTRACE). + +2. The second approach, if needed, is kernel exit switching. A + task is switched when it returns to user space from a system call, a + user space IRQ, or a signal. It's useful in the following cases: + + a) Patching I/O-bound user tasks which are sleeping on an affected + function. In this case you have to send SIGSTOP and SIGCONT to + force it to exit the kernel and be patched. + b) Patching CPU-bound user tasks. If the task is highly CPU-bound + then it will get patched the next time it gets interrupted by an + IRQ. + c) In the future it could be useful for applying patches for + architectures which don't yet have HAVE_RELIABLE_STACKTRACE. In + this case you would have to signal most of the tasks on the + system. However this isn't supported yet because there's + currently no way to patch kthreads without + HAVE_RELIABLE_STACKTRACE. + +3. For idle "swapper" tasks, since they don't ever exit the kernel, they + instead have a klp_update_patch_state() call in the idle loop which + allows them to be patched before the CPU enters the idle state. + + (Note there's not yet such an approach for kthreads.) + +All the above approaches may be skipped by setting the 'immediate' flag +in the 'klp_patch' struct, which will disable per-task consistency and +patch all tasks immediately. This can be useful if the patch doesn't +change any function or data semantics. Note that, even with this flag +set, it's possible that some tasks may still be running with an old +version of the function, until that function returns. + +There's also an 'immediate' flag in the 'klp_func' struct which allows +you to specify that certain functions in the patch can be applied +without per-task consistency. This might be useful if you want to patch +a common function like schedule(), and the function change doesn't need +consistency but the rest of the patch does. + +For architectures which don't have HAVE_RELIABLE_STACKTRACE, the user +must set patch->immediate which causes all tasks to be patched +immediately. This option should be used with care, only when the patch +doesn't change any function or data semantics. + +In the future, architectures which don't have HAVE_RELIABLE_STACKTRACE +may be allowed to use per-task consistency if we can come up with +another way to patch kthreads. + +The /sys/kernel/livepatch/<patch>/transition file shows whether a patch +is in transition. Only a single patch (the topmost patch on the stack) +can be in transition at a given time. A patch can remain in transition +indefinitely, if any of the tasks are stuck in the initial patch state. + +A transition can be reversed and effectively canceled by writing the +opposite value to the /sys/kernel/livepatch/<patch>/enabled file while +the transition is in progress. Then all the tasks will attempt to +converge back to the original patch state. + +There's also a /proc/<pid>/patch_state file which can be used to +determine which tasks are blocking completion of a patching operation. +If a patch is in transition, this file shows 0 to indicate the task is +unpatched and 1 to indicate it's patched. Otherwise, if no patch is in +transition, it shows -1. Any tasks which are blocking the transition +can be signaled with SIGSTOP and SIGCONT to force them to change their +patched state. + + +3.1 Adding consistency model support to new architectures +--------------------------------------------------------- + +For adding consistency model support to new architectures, there are a +few options: + +1) Add CONFIG_HAVE_RELIABLE_STACKTRACE. This means porting objtool, and + for non-DWARF unwinders, also making sure there's a way for the stack + tracing code to detect interrupts on the stack. + +2) Alternatively, ensure that every kthread has a call to + klp_update_patch_state() in a safe location. Kthreads are typically + in an infinite loop which does some action repeatedly. The safe + location to switch the kthread's patch state would be at a designated + point in the loop where there are no locks taken and all data + structures are in a well-defined state. + + The location is clear when using workqueues or the kthread worker + API. These kthreads process independent actions in a generic loop. + + It's much more complicated with kthreads which have a custom loop. + There the safe location must be carefully selected on a case-by-case + basis. + + In that case, arches without HAVE_RELIABLE_STACKTRACE would still be + able to use the non-stack-checking parts of the consistency model: + + a) patching user tasks when they cross the kernel/user space + boundary; and + + b) patching kthreads and idle tasks at their designated patch points. + + This option isn't as good as option 1 because it requires signaling + user tasks and waking kthreads to patch them. But it could still be + a good backup option for those architectures which don't have + reliable stack traces yet. + +In the meantime, patches for such architectures can bypass the +consistency model by setting klp_patch.immediate to true. This option +is perfectly fine for patches which don't change the semantics of the +patched functions. In practice, this is usable for ~90% of security +fixes. Use of this option also means the patch can't be unloaded after +it has been disabled. 4. Livepatch module @@ -134,7 +256,7 @@ Documentation/livepatch/module-elf-format.txt for more details. 4.2. Metadata ------------- +------------- The patch is described by several structures that split the information into three levels: @@ -156,6 +278,9 @@ into three levels: only for a particular object ( vmlinux or a kernel module ). Note that kallsyms allows for searching symbols according to the object name. + There's also an 'immediate' flag which, when set, patches the + function immediately, bypassing the consistency model safety checks. + + struct klp_object defines an array of patched functions (struct klp_func) in the same object. Where the object is either vmlinux (NULL) or a module name. @@ -172,10 +297,13 @@ into three levels: This structure handles all patched functions consistently and eventually, synchronously. The whole patch is applied only when all patched symbols are found. The only exception are symbols from objects - (kernel modules) that have not been loaded yet. Also if a more complex - consistency model is supported then a selected unit (thread, - kernel as a whole) will see the new code from the entire patch - only when it is in a safe state. + (kernel modules) that have not been loaded yet. + + Setting the 'immediate' flag applies the patch to all tasks + immediately, bypassing the consistency model safety checks. + + For more details on how the patch is applied on a per-task basis, + see the "Consistency model" section. 4.3. Livepatch module handling @@ -188,8 +316,15 @@ section "Livepatch life-cycle" below for more details about these two operations. Module removal is only safe when there are no users of the underlying -functions. The immediate consistency model is not able to detect this; -therefore livepatch modules cannot be removed. See "Limitations" below. +functions. The immediate consistency model is not able to detect this. The +code just redirects the functions at the very beginning and it does not +check if the functions are in use. In other words, it knows when the +functions get called but it does not know when the functions return. +Therefore it cannot be decided when the livepatch module can be safely +removed. This is solved by a hybrid consistency model. When the system is +transitioned to a new patch state (patched/unpatched) it is guaranteed that +no task sleeps or runs in the old code. + 5. Livepatch life-cycle ======================= @@ -239,9 +374,15 @@ Registered patches might be enabled either by calling klp_enable_patch() or by writing '1' to /sys/kernel/livepatch/<name>/enabled. The system will start using the new implementation of the patched functions at this stage. -In particular, if an original function is patched for the first time, a -function specific struct klp_ops is created and an universal ftrace handler -is registered. +When a patch is enabled, livepatch enters into a transition state where +tasks are converging to the patched state. This is indicated by a value +of '1' in /sys/kernel/livepatch/<name>/transition. Once all tasks have +been patched, the 'transition' value changes to '0'. For more +information about this process, see the "Consistency model" section. + +If an original function is patched for the first time, a function +specific struct klp_ops is created and an universal ftrace handler is +registered. Functions might be patched multiple times. The ftrace handler is registered only once for the given function. Further patches just add an entry to the @@ -261,6 +402,12 @@ by writing '0' to /sys/kernel/livepatch/<name>/enabled. At this stage either the code from the previously enabled patch or even the original code gets used. +When a patch is disabled, livepatch enters into a transition state where +tasks are converging to the unpatched state. This is indicated by a +value of '1' in /sys/kernel/livepatch/<name>/transition. Once all tasks +have been unpatched, the 'transition' value changes to '0'. For more +information about this process, see the "Consistency model" section. + Here all the functions (struct klp_func) associated with the to-be-disabled patch are removed from the corresponding struct klp_ops. The ftrace handler is unregistered and the struct klp_ops is freed when the func_stack list @@ -329,23 +476,6 @@ The current Livepatch implementation has several limitations: by "notrace". - + Livepatch modules can not be removed. - - The current implementation just redirects the functions at the very - beginning. It does not check if the functions are in use. In other - words, it knows when the functions get called but it does not - know when the functions return. Therefore it can not decide when - the livepatch module can be safely removed. - - This will get most likely solved once a more complex consistency model - is supported. The idea is that a safe state for patching should also - mean a safe state for removing the patch. - - Note that the patch itself might get disabled by writing zero - to /sys/kernel/livepatch/<patch>/enabled. It causes that the new - code will not longer get called. But it does not guarantee - that anyone is not sleeping anywhere in the new code. - + Livepatch works reliably only when the dynamic ftrace is located at the very beginning of the function. diff --git a/Documentation/md/md-cluster.txt b/Documentation/md/md-cluster.txt index 38883276d31c..82ee51604e9a 100644 --- a/Documentation/md/md-cluster.txt +++ b/Documentation/md/md-cluster.txt @@ -77,7 +77,7 @@ There are three groups of locks for managing the device: 3.1.2 RESYNCING: informs other nodes that a resync is initiated or ended so that each node may suspend or resume the region. Each RESYNCING message identifies a range of the devices that the - sending node is about to resync. This over-rides any pervious + 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. @@ -321,4 +321,4 @@ The algorithm is: There are somethings which are not supported by cluster MD yet. -- update size and change array_sectors. +- change array_sectors. diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/md/raid5-ppl.txt new file mode 100644 index 000000000000..127072b09363 --- /dev/null +++ b/Documentation/md/raid5-ppl.txt @@ -0,0 +1,44 @@ +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 +may become inconsistent with data on other member disks. If the array is also +in degraded state, there is no way to recalculate parity, because one of the +disks is missing. This can lead to silent data corruption when rebuilding the +array or using it is as degraded - data calculated from parity for array blocks +that have not been touched by a write request during the unclean shutdown can +be incorrect. Such condition is known as the RAID5 Write Hole. Because of +this, md by default does not allow starting a dirty degraded array. + +Partial parity for a write operation is the XOR of stripe data chunks not +modified by this write. It is just enough data needed for recovering from the +write hole. XORing partial parity with the modified chunks produces parity for +the stripe, consistent with its state before the write operation, regardless of +which chunk writes have completed. If one of the not modified data disks of +this stripe is missing, this updated parity can be used to recover its +contents. PPL recovery is also performed when starting an array after an +unclean shutdown and all disks are available, eliminating the need to resync +the array. Because of this, using write-intent bitmap and PPL together is not +supported. + +When handling a write request PPL writes partial parity before new data and +parity are dispatched to disks. PPL is a distributed log - it is stored on +array member drives in the metadata area, on the parity drive of a particular +stripe. It does not require a dedicated journaling drive. Write performance is +reduced by up to 30%-40% but it scales with the number of drives in the array +and the journaling drive does not become a bottleneck or a single point of +failure. + +Unlike raid5-cache, the other solution in md for closing the write hole, PPL is +not a true journal. It does not protect from losing in-flight data, only from +silent data corruption. If a dirty disk of a stripe is lost, no PPL recovery is +performed for this stripe (parity is not updated). So it is possible to have +arbitrary data in the written part of a stripe if that disk is lost. In such +case the behavior is the same as in plain raid5. + +PPL is available for md version-1 metadata and external (specifically IMSM) +metadata arrays. It can be enabled using mdadm option --consistency-policy=ppl. + +Currently, volatile write-back cache should be disabled on all member drives +when using PPL. Otherwise it cannot guarantee consistency in case of power +failure. diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile index 9b3e70b2cab2..36166952d555 100644 --- a/Documentation/media/Makefile +++ b/Documentation/media/Makefile @@ -1,51 +1,6 @@ -# Rules to convert DOT and SVG to Sphinx images - -SRC_DIR=$(srctree)/Documentation/media - -DOTS = \ - uapi/v4l/pipeline.dot \ - -IMAGES = \ - typical_media_device.svg \ - uapi/dvb/dvbstb.svg \ - uapi/v4l/bayer.svg \ - uapi/v4l/constraints.svg \ - uapi/v4l/crop.svg \ - uapi/v4l/fieldseq_bt.svg \ - uapi/v4l/fieldseq_tb.svg \ - uapi/v4l/nv12mt.svg \ - uapi/v4l/nv12mt_example.svg \ - uapi/v4l/pipeline.svg \ - uapi/v4l/selection.svg \ - uapi/v4l/subdev-image-processing-full.svg \ - uapi/v4l/subdev-image-processing-scaling-multi-source.svg \ - uapi/v4l/subdev-image-processing-crop.svg \ - uapi/v4l/vbi_525.svg \ - uapi/v4l/vbi_625.svg \ - uapi/v4l/vbi_hsync.svg \ - -DOTTGT := $(patsubst %.dot,%.svg,$(DOTS)) -IMGDOT := $(patsubst %,$(SRC_DIR)/%,$(DOTTGT)) - -IMGTGT := $(patsubst %.svg,%.pdf,$(IMAGES)) -IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT)) - -cmd = $(echo-cmd) $(cmd_$(1)) - -quiet_cmd_genpdf = GENPDF $2 - cmd_genpdf = convert $2 $3 - -quiet_cmd_gendot = DOT $2 - cmd_gendot = dot -Tsvg $2 > $3 || { rm -f $3; exit 1; } - -%.pdf: %.svg - @$(call cmd,genpdf,$<,$@) - -%.svg: %.dot - @$(call cmd,gendot,$<,$@) - # Rules to convert a .h file to inline RST documentation +SRC_DIR=$(srctree)/Documentation/media PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl UAPI = $(srctree)/include/uapi/linux KAPI = $(srctree)/include/linux diff --git a/Documentation/media/intro.rst b/Documentation/media/intro.rst index 8f7490c9a8ef..9ce2e23a0236 100644 --- a/Documentation/media/intro.rst +++ b/Documentation/media/intro.rst @@ -13,9 +13,9 @@ A typical media device hardware is shown at :ref:`typical_media_device`. .. _typical_media_device: -.. figure:: typical_media_device.* - :alt: typical_media_device.pdf / typical_media_device.svg - :align: center +.. kernel-figure:: typical_media_device.svg + :alt: typical_media_device.svg + :align: center Typical Media Device diff --git a/Documentation/media/kapi/cec-core.rst b/Documentation/media/kapi/cec-core.rst index 81c6d8e93774..7a04c5386dc8 100644 --- a/Documentation/media/kapi/cec-core.rst +++ b/Documentation/media/kapi/cec-core.rst @@ -27,11 +27,8 @@ HDMI 1.3a specification is sufficient: http://www.microprocessor.org/HDMISpecification13a.pdf -The Kernel Interface -==================== - -CEC Adapter ------------ +CEC Adapter Interface +--------------------- The struct cec_adapter represents the CEC adapter hardware. It is created by calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): @@ -51,6 +48,7 @@ ops: priv: will be stored in adap->priv and can be used by the adapter ops. + Use cec_get_drvdata(adap) to get the priv pointer. name: the name of the CEC adapter. Note: this name will be copied. @@ -65,6 +63,10 @@ available_las: the number of simultaneous logical addresses that this adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. +To obtain the priv pointer use this helper function: + +.. c:function:: + void *cec_get_drvdata(const struct cec_adapter *adap); To register the /dev/cecX device node and the remote control device (if CEC_CAP_RC is set) you call: diff --git a/Documentation/media/kapi/csi2.rst b/Documentation/media/kapi/csi2.rst index 2004db00b12b..e33fcb967922 100644 --- a/Documentation/media/kapi/csi2.rst +++ b/Documentation/media/kapi/csi2.rst @@ -45,10 +45,11 @@ where * - bits_per_sample - Number of bits per sample. -The transmitter drivers must configure the CSI-2 transmitter to *LP-11 -mode* whenever the transmitter is powered on but not active. Some -transmitters do this automatically but some have to be explicitly -programmed to do so. +The transmitter drivers must, if possible, configure the CSI-2 +transmitter to *LP-11 mode* whenever the transmitter is powered on but +not active. Some transmitters do this automatically but some have to +be explicitly programmed to do so, and some are unable to do so +altogether due to hardware constraints. Receiver drivers ---------------- diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index e9677150ed99..d8f6c46d26d5 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -1,4 +1,4 @@ -Video2Linux devices +Video4Linux devices ------------------- .. toctree:: diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index 246c850151d7..c130617a9986 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -35,7 +35,6 @@ ignore define PULSE_MASK ignore define LIRC_MODE2_SPACE ignore define LIRC_MODE2_PULSE -ignore define LIRC_MODE2_TIMEOUT ignore define LIRC_VALUE_MASK ignore define LIRC_MODE2_MASK diff --git a/Documentation/media/uapi/cec/cec-func-ioctl.rst b/Documentation/media/uapi/cec/cec-func-ioctl.rst index 7dcfd178fb24..22fb6304a2df 100644 --- a/Documentation/media/uapi/cec/cec-func-ioctl.rst +++ b/Documentation/media/uapi/cec/cec-func-ioctl.rst @@ -30,7 +30,7 @@ Arguments ``request`` CEC ioctl request code as defined in the cec.h header file, for - example :c:func:`CEC_ADAP_G_CAPS`. + example :ref:`CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`. ``argp`` Pointer to a request-specific structure. diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst index 0304388cd159..18dfb62f2efe 100644 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ b/Documentation/media/uapi/cec/cec-func-open.rst @@ -33,7 +33,7 @@ Arguments Open flags. Access mode must be ``O_RDWR``. When the ``O_NONBLOCK`` flag is given, the - :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :c:func:`CEC_DQEVENT` ioctls + :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls will return the ``EAGAIN`` error code when no message or event is available, and ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`, :ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and diff --git a/Documentation/media/uapi/cec/cec-func-poll.rst b/Documentation/media/uapi/cec/cec-func-poll.rst index 6a863cfda6e0..fa0abd8fb160 100644 --- a/Documentation/media/uapi/cec/cec-func-poll.rst +++ b/Documentation/media/uapi/cec/cec-func-poll.rst @@ -30,7 +30,7 @@ Arguments List of FD events to be watched ``nfds`` - Number of FD efents at the \*ufds array + Number of FD events at the \*ufds array ``timeout`` Timeout to wait for events @@ -49,7 +49,7 @@ is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in the ``revents`` field if there are messages in the receive queue. If the transmit queue has room for new messages, the ``POLLOUT`` and ``POLLWRNORM`` flags are set. If there are events in the event queue, -then the ``POLLPRI`` flag is set. When the function timed out it returns +then the ``POLLPRI`` flag is set. When the function times out it returns a value of zero, on failure it returns -1 and the ``errno`` variable is set appropriately. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst index 09f09bbe28d4..fcf863ab6f43 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst @@ -351,3 +351,16 @@ On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. +The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` can return the following +error codes: + +ENOTTY + The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported. + +EBUSY + The CEC adapter is currently configuring itself, or it is already configured and + ``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or + initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``. + +EINVAL + The contents of struct :c:type:`cec_log_addrs` is invalid. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst index a3cdc75cec3e..9e49d4be35d5 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst @@ -78,3 +78,16 @@ Return Value On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. + +The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following +error codes: + +ENOTTY + The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported. + +EBUSY + Another filehandle is in exclusive follower or initiator mode, or the filehandle + is in mode ``CEC_MODE_NO_INITIATOR``. + +EINVAL + The physical address is malformed. diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst index 6e589a1fae17..4d3570c2e0b3 100644 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst @@ -56,7 +56,7 @@ it is guaranteed that the state did change in between the two events. * - __u16 - ``phys_addr`` - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no - valid physical address is set. + valid physical address is set. * - __u16 - ``log_addr_mask`` - The current set of claimed logical addresses. This is 0 if no logical @@ -174,3 +174,14 @@ Return Value On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. + +The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following +error codes: + +EAGAIN + This is returned when the filehandle is in non-blocking mode and there + are no pending events. + +ERESTARTSYS + An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for + events to arrive. diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst index e4ded9df0a84..664f0d47bbcd 100644 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst @@ -249,3 +249,15 @@ Return Value On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. + +The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following +error codes: + +EINVAL + The requested mode is invalid. + +EPERM + Monitor mode is requested without having root permissions + +EBUSY + Someone else is already an exclusive follower or initiator. diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst index dc2adb391c0a..267044f7ac30 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -51,13 +51,13 @@ A received message can be: be non-zero). To send a CEC message the application has to fill in the struct -:c:type:` cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. +:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if ``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit queue, then it will return -1 and set errno to the ``EBUSY`` error code. The transmit queue has enough room for 18 messages (about 1 second worth of 2-byte messages). Note that the CEC kernel framework will also reply -to core messages (see :ref:cec-core-processing), so it is not a good +to core messages (see :ref:`cec-core-processing`), so it is not a good idea to fully fill up the transmit queue. If the file descriptor is in non-blocking mode then the transmit will @@ -69,6 +69,18 @@ The ``sequence`` field is filled in for every transmit and this can be checked against the received messages to find the corresponding transmit result. +Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical +address is invalid (due to e.g. a disconnect) will return ``ENONET``. + +However, the CEC specification allows sending messages from 'Unregistered' to +'TV' when the physical address is invalid since some TVs pull the hotplug detect +pin of the HDMI connector low when they go into standby, or when switching to +another input. + +When the hotplug detect pin goes low the EDID disappears, and thus the +physical address, but the cable is still connected and CEC still works. +In order to detect/wake up the device it is allowed to send poll and 'Image/Text +View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}| @@ -289,3 +301,42 @@ Return Value On success 0 is returned, on error -1 and the ``errno`` variable is set appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. + +The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following +error codes: + +EAGAIN + No messages are in the receive queue, and the filehandle is in non-blocking mode. + +ETIMEDOUT + The ``timeout`` was reached while waiting for a message. + +ERESTARTSYS + The wait for a message was interrupted (e.g. by Ctrl-C). + +The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following +error codes: + +ENOTTY + The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported. + +EPERM + The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` + has never been called. + +ENONET + The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` + was called, but the physical address is invalid so no logical address was claimed. + An exception is made in this case for transmits from initiator 0xf ('Unregistered') + to destination 0 ('TV'). In that case the transmit will proceed as usual. + +EBUSY + Another filehandle is in exclusive follower or initiator mode, or the filehandle + is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit + queue is full. + +EINVAL + The contents of struct :c:type:`cec_msg` is invalid. + +ERESTARTSYS + The wait for a successful transmit was interrupted (e.g. by Ctrl-C). diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst index 2ed5c23102b4..652c4aacd2c6 100644 --- a/Documentation/media/uapi/dvb/intro.rst +++ b/Documentation/media/uapi/dvb/intro.rst @@ -55,9 +55,9 @@ Overview .. _stb_components: -.. figure:: dvbstb.* - :alt: dvbstb.pdf / dvbstb.svg - :align: center +.. kernel-figure:: dvbstb.svg + :alt: dvbstb.svg + :align: center Components of a DVB card/STB diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst index 3e03dc2e6003..2a5164aea2b4 100644 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ b/Documentation/media/uapi/mediactl/media-types.rst @@ -284,7 +284,8 @@ Types and flags used to represent the media graph elements supported scaling ratios is entity-specific and can differ between the horizontal and vertical directions (in particular scaling can be supported in one direction only). Binning and - skipping are considered as scaling. + sub-sampling (occasionally also referred to as skipping) are + considered as scaling. - .. row 28 diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index ef97e40f2fd8..d1936eeb9ce0 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -27,6 +27,8 @@ What you should see for a chardev: $ ls -l /dev/lirc* crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 +.. _lirc_modes: + ********** LIRC modes ********** @@ -38,25 +40,62 @@ on the following table. ``LIRC_MODE_MODE2`` - The driver returns a sequence of pulse and space codes to userspace. + The driver returns a sequence of pulse and space codes to userspace, + as a series of u32 values. This mode is used only for IR receive. + The upper 8 bits determine the packet type, and the lower 24 bits + the payload. Use ``LIRC_VALUE()`` macro to get the payload, and + the macro ``LIRC_MODE2()`` will give you the type, which + is one of: + + ``LIRC_MODE2_PULSE`` + + Signifies the presence of IR in microseconds. + + ``LIRC_MODE2_SPACE`` + + Signifies absence of IR in microseconds. + + ``LIRC_MODE2_FREQUENCY`` + + If measurement of the carrier frequency was enabled with + :ref:`lirc_set_measure_carrier_mode` then this packet gives you + the carrier frequency in Hertz. + + ``LIRC_MODE2_TIMEOUT`` + + If timeout reports are enabled with + :ref:`lirc_set_rec_timeout_reports`, when the timeout set with + :ref:`lirc_set_rec_timeout` expires due to no IR being detected, + this packet will be sent, with the number of microseconds with + no IR. + .. _lirc-mode-lirccode: ``LIRC_MODE_LIRCCODE`` - The IR signal is decoded internally by the receiver. The LIRC interface - returns the scancode as an integer value. This is the usual mode used - by several TV media cards. + This mode can be used for IR receive and send. - This mode is used only for IR receive. + The IR signal is decoded internally by the receiver, or encoded by the + transmitter. The LIRC interface represents the scancode as byte string, + which might not be a u32, it can be any length. The value is entirely + driver dependent. This mode is used by some older lirc drivers. + + The length of each code depends on the driver, which can be retrieved + with :ref:`lirc_get_length`. This length is used both + for transmitting and receiving IR. .. _lirc-mode-pulse: ``LIRC_MODE_PULSE`` - On puse mode, a sequence of pulse/space integer values are written to the - lirc device using :Ref:`lirc-write`. + In pulse mode, a sequence of pulse/space integer values are written to the + lirc device using :ref:`lirc-write`. + + The values are alternating pulse and space lengths, in microseconds. The + first and last entry must be a pulse, so there must be an odd number + of entries. This mode is used only for IR send. diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst index 79e07b4d44d6..64f89a4f9d9c 100644 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ b/Documentation/media/uapi/rc/lirc-get-features.rst @@ -48,8 +48,8 @@ LIRC features ``LIRC_CAN_REC_PULSE`` - The driver is capable of receiving using - :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`. + Unused. Kept just to avoid breaking uAPI. + :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` can only be used for transmitting. .. _LIRC-CAN-REC-MODE2: @@ -156,19 +156,22 @@ LIRC features ``LIRC_CAN_SEND_PULSE`` - The driver supports sending using :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`. + The driver supports sending (also called as IR blasting or IR TX) using + :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`. .. _LIRC-CAN-SEND-MODE2: ``LIRC_CAN_SEND_MODE2`` - The driver supports sending using :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`. + Unused. Kept just to avoid breaking uAPI. + :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` can only be used for receiving. .. _LIRC-CAN-SEND-LIRCCODE: ``LIRC_CAN_SEND_LIRCCODE`` - The driver supports sending codes (also called as IR blasting or IR TX). + The driver supports sending (also called as IR blasting or IR TX) using + :ref:`LIRC_MODE_LIRCCODE <lirc-mode-LIRCCODE>`. Return Value diff --git a/Documentation/media/uapi/rc/lirc-get-length.rst b/Documentation/media/uapi/rc/lirc-get-length.rst index 8c2747c8d2c9..3990af5de0e9 100644 --- a/Documentation/media/uapi/rc/lirc-get-length.rst +++ b/Documentation/media/uapi/rc/lirc-get-length.rst @@ -30,7 +30,8 @@ Arguments Description =========== -Retrieves the code length in bits (only for ``LIRC-MODE-LIRCCODE``). +Retrieves the code length in bits (only for +:ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>`). Reads on the device must be done in blocks matching the bit count. The bit could should be rounded up so that it matches full bytes. diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst index a5023e0194c1..a4eb6c0a26e9 100644 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst @@ -35,8 +35,8 @@ Description Get/set supported receive modes. Only :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` and :ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` are supported for IR -receive. - +receive. Use :ref:`lirc_get_features` to find out which modes the driver +supports. Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst index 51ac13428969..a169b234290e 100644 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst @@ -34,9 +34,12 @@ Arguments Description =========== -Get/set supported transmit mode. +Get/set current transmit mode. -Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` is supported by for IR send. +Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` and +:ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` is supported by for IR send, +depending on the driver. Use :ref:`lirc_get_features` to find out which +modes the driver supports. Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst index 4c678f60e872..ff14a69104e5 100644 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -44,17 +44,13 @@ descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, :ref:`read() <lirc-read>` returns zero and has no other results. If ``count`` is greater than ``SSIZE_MAX``, the result is unspecified. -The lircd userspace daemon reads raw IR data from the LIRC chardev. The -exact format of the data depends on what modes a driver supports, and -what mode has been selected. lircd obtains supported modes and sets the -active mode via the ioctl interface, detailed at :ref:`lirc_func`. -The generally preferred mode for receive is -:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`, in which packets containing an -int value describing an IR signal are read from the chardev. +The exact format of the data depends on what :ref:`lirc_modes` a driver +uses. Use :ref:`lirc_get_features` to get the supported mode. -See also -`http://www.lirc.org/html/technical.html <http://www.lirc.org/html/technical.html>`__ -for more info. +The generally preferred mode for receive is +:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`, +in which packets containing an int value describing an IR signal are +read from the chardev. Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst index a83fbbfa0d3b..a89246806c4b 100644 --- a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst +++ b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst @@ -9,7 +9,7 @@ ioctl LIRC_SET_REC_CARRIER_RANGE Name ==== -LIRC_SET_REC_CARRIER_RANGE - Set lower bond of the carrier used to modulate +LIRC_SET_REC_CARRIER_RANGE - Set lower bound of the carrier used to modulate IR receive. Synopsis diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst index 9c501bbf4c62..86353e602695 100644 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst +++ b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst @@ -31,6 +31,8 @@ Arguments Description =========== +.. _lirc-mode2-timeout: + Enable or disable timeout reports for IR receive. By default, timeout reports should be turned off. diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index 3b035c6613b1..2aad0fef4a5b 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -42,13 +42,16 @@ Description referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. -The data written to the chardev is a pulse/space sequence of integer -values. Pulses and spaces are only marked implicitly by their position. -The data must start and end with a pulse, therefore, the data must -always include an uneven number of samples. The write function must -block until the data has been transmitted by the hardware. If more data -is provided than the hardware can send, the driver returns ``EINVAL``. - +The exact format of the data depends on what mode a driver uses, use +:ref:`lirc_get_features` to get the supported mode. + +When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to +the chardev is a pulse/space sequence of integer values. Pulses and spaces +are only marked implicitly by their position. The data must start and end +with a pulse, therefore, the data must always include an uneven number of +samples. The write function must block until the data has been transmitted +by the hardware. If more data is provided than the hardware can send, the +driver returns ``EINVAL``. Return Value ============ diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index ac58966ccb9b..ae6ee73f151c 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -34,6 +34,125 @@ flags are copied from the OUTPUT video buffer to the CAPTURE video buffer. +Interactions between formats, controls and buffers +================================================== + +V4L2 exposes parameters that influence the buffer size, or the way data is +laid out in the buffer. Those parameters are exposed through both formats and +controls. One example of such a control is the ``V4L2_CID_ROTATE`` control +that modifies the direction in which pixels are stored in the buffer, as well +as the buffer size when the selected format includes padding at the end of +lines. + +The set of information needed to interpret the content of a buffer (e.g. the +pixel format, the line stride, the tiling orientation or the rotation) is +collectively referred to in the rest of this section as the buffer layout. + +Controls that can modify the buffer layout shall set the +``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag. + +Modifying formats or controls that influence the buffer size or layout require +the stream to be stopped. Any attempt at such a modification while the stream +is active shall cause the ioctl setting the format or the control to return +the ``EBUSY`` error code. In that case drivers shall also set the +``V4L2_CTRL_FLAG_GRABBED`` flag when calling +:c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a +control while the stream is active. + +.. note:: + + The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for + instance if the device doesn't include a scaler), modify the format in + addition to the selection rectangle. Similarly, the + :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD` + and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and + selection rectangles. When those ioctls result in a buffer size or layout + change, drivers shall handle that condition as they would handle it in the + :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section. + +Controls that only influence the buffer layout can be modified at any time +when the stream is stopped. As they don't influence the buffer size, no +special handling is needed to synchronize those controls with buffer +allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the +stream is stopped. + +Formats and controls that influence the buffer size interact with buffer +allocation. The simplest way to handle this is for drivers to always require +buffers to be reallocated in order to change those formats or controls. In +that case, to perform such changes, userspace applications shall first stop +the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running +and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are +allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag +for controls is cleared. The format or controls can then be modified, and +buffers shall then be reallocated and the stream restarted. A typical ioctl +sequence is + + #. VIDIOC_STREAMOFF + #. VIDIOC_REQBUFS(0) + #. VIDIOC_S_EXT_CTRLS + #. VIDIOC_S_FMT + #. VIDIOC_REQBUFS(n) + #. VIDIOC_QBUF + #. VIDIOC_STREAMON + +The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control +value into account to compute the buffer size to allocate. Applications can +also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed. + +.. note:: + + The API doesn't mandate the above order for control (3.) and format (4.) + changes. Format and controls can be set in a different order, or even + interleaved, depending on the device and use case. For instance some + controls might behave differently for different pixel formats, in which + case the format might need to be set first. + +When reallocation is required, any attempt to modify format or controls that +influences the buffer size while buffers are allocated shall cause the format +or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a +buffer too small for the current format or controls shall cause the +:c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error. + +Buffer reallocation is an expensive operation. To avoid that cost, drivers can +(and are encouraged to) allow format or controls that influence the buffer +size to be changed with buffers allocated. In that case, a typical ioctl +sequence to modify format and controls is + + #. VIDIOC_STREAMOFF + #. VIDIOC_S_EXT_CTRLS + #. VIDIOC_S_FMT + #. VIDIOC_QBUF + #. VIDIOC_STREAMON + +For this sequence to operate correctly, queued buffers need to be large enough +for the new format or controls. Drivers shall return a ``ENOSPC`` error in +response to format change (:c:func:`VIDIOC_S_FMT`) or control changes +(:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small +for the new format are currently queued. As a simplification, drivers are +allowed to return a ``EBUSY`` error from these ioctls if any buffer is +currently queued, without checking the queued buffers sizes. + +Additionally, drivers shall return a ``EINVAL`` error from the +:c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the +current format or controls. Together, these requirements ensure that queued +buffers will always be large enough for the configured format and controls. + +Userspace applications can query the buffer size required for a given format +and controls by first setting the desired control values and then trying the +desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required +buffer size. + + #. VIDIOC_S_EXT_CTRLS(x) + #. VIDIOC_TRY_FMT() + #. VIDIOC_S_EXT_CTRLS(y) + #. VIDIOC_TRY_FMT() + +The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers +based on the queried sizes (for instance by allocating a set of buffers large +enough for all the desired formats and controls, or by allocating separate set +of appropriately sized buffers for each use case). + + .. c:type:: v4l2_buffer struct v4l2_buffer @@ -330,6 +449,9 @@ enum v4l2_buf_type - 12 - Buffer for Software Defined Radio (SDR) output stream, see :ref:`sdr`. + * - ``V4L2_BUF_TYPE_META_CAPTURE`` + - 13 + - Buffer for metadata capture, see :ref:`metadata`. diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst index be58894c9c89..182565b9ace4 100644 --- a/Documentation/media/uapi/v4l/crop.rst +++ b/Documentation/media/uapi/v4l/crop.rst @@ -53,8 +53,8 @@ Cropping Structures .. _crop-scale: -.. figure:: crop.* - :alt: crop.pdf / crop.svg +.. kernel-figure:: crop.svg + :alt: crop.svg :align: center Image Cropping, Insertion and Scaling diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst index 82f183870aae..d1641e9687a6 100644 --- a/Documentation/media/uapi/v4l/depth-formats.rst +++ b/Documentation/media/uapi/v4l/depth-formats.rst @@ -12,4 +12,5 @@ Depth data provides distance to points, mapped onto the image plane .. toctree:: :maxdepth: 1 + pixfmt-inzi pixfmt-z16 diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst index 32b32055d070..4218742ab5d9 100644 --- a/Documentation/media/uapi/v4l/dev-capture.rst +++ b/Documentation/media/uapi/v4l/dev-capture.rst @@ -42,8 +42,8 @@ Video capture devices shall support :ref:`audio input <audio>`, :ref:`tuner`, :ref:`controls <control>`, :ref:`cropping and scaling <crop>` and :ref:`streaming parameter <streaming-par>` ioctls as needed. The -:ref:`video input <video>` and :ref:`video standard <standard>` -ioctls must be supported by all video capture devices. +:ref:`video input <video>` ioctls must be supported by all video +capture devices. Image Format Negotiation diff --git a/Documentation/media/uapi/v4l/dev-meta.rst b/Documentation/media/uapi/v4l/dev-meta.rst new file mode 100644 index 000000000000..62518adfe37b --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-meta.rst @@ -0,0 +1,58 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _metadata: + +****************** +Metadata Interface +****************** + +Metadata refers to any non-image data that supplements video frames with +additional information. This may include statistics computed over the image +or frame capture parameters supplied by the image source. This interface is +intended for transfer of metadata to userspace and control of that operation. + +The metadata interface is implemented on video capture device nodes. The device +can be dedicated to metadata or can implement both video and metadata capture +as specified in its reported capabilities. + +Querying Capabilities +===================== + +Device nodes supporting the metadata interface set the ``V4L2_CAP_META_CAPTURE`` +flag in the ``device_caps`` field of the +:c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP` +ioctl. That flag means the device can capture metadata to memory. + +At least one of the read/write or streaming I/O methods must be supported. + + +Data Format Negotiation +======================= + +The metadata device uses the :ref:`format` ioctls to select the capture format. +The metadata buffer content format is bound to that selected format. In addition +to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be +supported as well. + +To use the :ref:`format` ioctls applications set the ``type`` field of the +:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` and use the +:c:type:`v4l2_meta_format` ``meta`` member of the ``fmt`` union as needed per +the desired operation. Both drivers and applications must set the remainder of +the :c:type:`v4l2_format` structure to 0. + +.. _v4l2-meta-format: + +.. flat-table:: struct v4l2_meta_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``dataformat`` + - The data format, set by the application. This is a little endian + :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats + in :ref:`meta-formats`. + * - __u32 + - ``buffersize`` + - Maximum buffer size in bytes required for data. The value is set by the + driver. diff --git a/Documentation/media/uapi/v4l/dev-output.rst b/Documentation/media/uapi/v4l/dev-output.rst index 25ae8ec96fdf..342eb4931f5c 100644 --- a/Documentation/media/uapi/v4l/dev-output.rst +++ b/Documentation/media/uapi/v4l/dev-output.rst @@ -40,8 +40,8 @@ Video output devices shall support :ref:`audio output <audio>`, :ref:`modulator <tuner>`, :ref:`controls <control>`, :ref:`cropping and scaling <crop>` and :ref:`streaming parameter <streaming-par>` ioctls as needed. The -:ref:`video output <video>` and :ref:`video standard <standard>` -ioctls must be supported by all video output devices. +:ref:`video output <video>` ioctls must be supported by all video +output devices. Image Format Negotiation diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst index baf5f2483927..2e6878b624f6 100644 --- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst @@ -221,33 +221,29 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does .. _vbi-hsync: -.. figure:: vbi_hsync.* - :alt: vbi_hsync.pdf / vbi_hsync.svg - :align: center +.. kernel-figure:: vbi_hsync.svg + :alt: vbi_hsync.svg + :align: center **Figure 4.1. Line synchronization** .. _vbi-525: -.. figure:: vbi_525.* - :alt: vbi_525.pdf / vbi_525.svg - :align: center +.. kernel-figure:: vbi_525.svg + :alt: vbi_525.svg + :align: center **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)** - - .. _vbi-625: -.. figure:: vbi_625.* - :alt: vbi_625.pdf / vbi_625.svg - :align: center +.. kernel-figure:: vbi_625.svg + :alt: vbi_625.svg + :align: center **Figure 4.3. ITU-R 625 line numbering** - - Remember the VBI image format depends on the selected video standard, therefore the application must choose a new standard or query the current standard first. Attempts to read or write data ahead of format diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst index cd2870180208..f0e762167730 100644 --- a/Documentation/media/uapi/v4l/dev-subdev.rst +++ b/Documentation/media/uapi/v4l/dev-subdev.rst @@ -99,9 +99,9 @@ the video sensor and the host image processing hardware. .. _pipeline-scaling: -.. figure:: pipeline.* - :alt: pipeline.pdf / pipeline.svg - :align: center +.. kernel-figure:: pipeline.dot + :alt: pipeline.dot + :align: center Image Format Negotiation on Pipelines @@ -404,9 +404,9 @@ selection will refer to the sink pad format dimensions instead. .. _subdev-image-processing-crop: -.. figure:: subdev-image-processing-crop.* - :alt: subdev-image-processing-crop.pdf / subdev-image-processing-crop.svg - :align: center +.. kernel-figure:: subdev-image-processing-crop.svg + :alt: subdev-image-processing-crop.svg + :align: center **Figure 4.5. Image processing in subdevs: simple crop example** @@ -421,9 +421,9 @@ pad. .. _subdev-image-processing-scaling-multi-source: -.. figure:: subdev-image-processing-scaling-multi-source.* - :alt: subdev-image-processing-scaling-multi-source.pdf / subdev-image-processing-scaling-multi-source.svg - :align: center +.. kernel-figure:: subdev-image-processing-scaling-multi-source.svg + :alt: subdev-image-processing-scaling-multi-source.svg + :align: center **Figure 4.6. Image processing in subdevs: scaling with multiple sources** @@ -437,8 +437,8 @@ an area at location specified by the source crop rectangle from it. .. _subdev-image-processing-full: -.. figure:: subdev-image-processing-full.* - :alt: subdev-image-processing-full.pdf / subdev-image-processing-full.svg +.. kernel-figure:: subdev-image-processing-full.svg + :alt: subdev-image-processing-full.svg :align: center **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources** diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst index 5c3d6c29e12c..fb7f8c26cf09 100644 --- a/Documentation/media/uapi/v4l/devices.rst +++ b/Documentation/media/uapi/v4l/devices.rst @@ -25,3 +25,4 @@ Interfaces dev-touch dev-event dev-subdev + dev-meta diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index e05fb1041363..5f3f82cbfa34 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -141,17 +141,20 @@ enum v4l2_field Field Order, Top Field First Transmitted ======================================== -.. figure:: fieldseq_tb.* - :alt: fieldseq_tb.pdf / fieldseq_tb.svg +.. kernel-figure:: fieldseq_tb.svg + :alt: fieldseq_tb.svg :align: center + Field Order, Top Field First Transmitted + .. _fieldseq-bt: Field Order, Bottom Field First Transmitted =========================================== -.. figure:: fieldseq_bt.* - :alt: fieldseq_bt.pdf / fieldseq_bt.svg +.. kernel-figure:: fieldseq_bt.svg + :alt: fieldseq_bt.svg :align: center + Field Order, Bottom Field First Transmitted diff --git a/Documentation/media/uapi/v4l/meta-formats.rst b/Documentation/media/uapi/v4l/meta-formats.rst new file mode 100644 index 000000000000..01e24e3df571 --- /dev/null +++ b/Documentation/media/uapi/v4l/meta-formats.rst @@ -0,0 +1,16 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _meta-formats: + +**************** +Metadata Formats +**************** + +These formats are used for the :ref:`metadata` interface only. + + +.. toctree:: + :maxdepth: 1 + + pixfmt-meta-vsp1-hgo + pixfmt-meta-vsp1-hgt diff --git a/Documentation/media/uapi/v4l/pixfmt-007.rst b/Documentation/media/uapi/v4l/pixfmt-007.rst index 95a23a28c595..0c30ee2577d3 100644 --- a/Documentation/media/uapi/v4l/pixfmt-007.rst +++ b/Documentation/media/uapi/v4l/pixfmt-007.rst @@ -174,7 +174,7 @@ this colorspace: The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range [0…1]. The resulting Y', Cb and Cr values are -scaled and offset: +scaled and offset according to the limited range formula: .. math:: @@ -187,7 +187,7 @@ scaled and offset: The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is similar to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range [0…1]. The resulting Y', Cb and Cr values are -scaled and offset: +scaled and offset according to the limited range formula: .. math:: @@ -198,9 +198,14 @@ scaled and offset: Cr = \frac{224}{256} * (0.5R' - 0.4187G' - 0.0813B') Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be +[-0.5…0.5] and quantized without further scaling or offsets. +The non-standard xvYCC 709 or xvYCC 601 encodings can be used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``. -The xvYCC encodings always use full range quantization. +As seen by the xvYCC formulas these encodings always use limited range quantization, +there is no full range variant. The whole point of these extended gamut encodings +is that values outside the limited range are still valid, although they +map to R', G' and B' values outside the [0…1] range and are therefore outside +the Rec. 709 colorspace gamut. .. _col-srgb: diff --git a/Documentation/media/uapi/v4l/pixfmt-inzi.rst b/Documentation/media/uapi/v4l/pixfmt-inzi.rst new file mode 100644 index 000000000000..9849e799f205 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-inzi.rst @@ -0,0 +1,81 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-INZI: + +************************** +V4L2_PIX_FMT_INZI ('INZI') +************************** + +Infrared 10-bit linked with Depth 16-bit images + + +Description +=========== + +Proprietary multi-planar format used by Intel SR300 Depth cameras, comprise of +Infrared image followed by Depth data. The pixel definition is 32-bpp, +with the Depth and Infrared Data split into separate continuous planes of +identical dimensions. + + + +The first plane - Infrared data - is stored according to +:ref:`V4L2_PIX_FMT_Y10 <V4L2-PIX-FMT-Y10>` greyscale format. +Each pixel is 16-bit cell, with actual data stored in the 10 LSBs +with values in range 0 to 1023. +The six remaining MSBs are padded with zeros. + + +The second plane provides 16-bit per-pixel Depth data arranged in +:ref:`V4L2-PIX-FMT-Z16 <V4L2-PIX-FMT-Z16>` format. + + +**Frame Structure.** +Each cell is a 16-bit word with more significant data stored at higher +memory address (byte order is little-endian). + +.. raw:: latex + + \newline\newline\begin{adjustbox}{width=\columnwidth} + +.. tabularcolumns:: |p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 1 + :widths: 1 1 1 1 1 1 + + * - Ir\ :sub:`0,0` + - Ir\ :sub:`0,1` + - Ir\ :sub:`0,2` + - ... + - ... + - ... + * - :cspan:`5` ... + * - :cspan:`5` Infrared Data + * - :cspan:`5` ... + * - ... + - ... + - ... + - Ir\ :sub:`n-1,n-3` + - Ir\ :sub:`n-1,n-2` + - Ir\ :sub:`n-1,n-1` + * - Depth\ :sub:`0,0` + - Depth\ :sub:`0,1` + - Depth\ :sub:`0,2` + - ... + - ... + - ... + * - :cspan:`5` ... + * - :cspan:`5` Depth Data + * - :cspan:`5` ... + * - ... + - ... + - ... + - Depth\ :sub:`n-1,n-3` + - Depth\ :sub:`n-1,n-2` + - Depth\ :sub:`n-1,n-1` + +.. raw:: latex + + \end{adjustbox}\newline\newline diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst new file mode 100644 index 000000000000..67796594fd48 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst @@ -0,0 +1,168 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-meta-fmt-vsp1-hgo: + +******************************* +V4L2_META_FMT_VSP1_HGO ('VSPH') +******************************* + +Renesas R-Car VSP1 1-D Histogram Data + + +Description +=========== + +This format describes histogram data generated by the Renesas R-Car VSP1 1-D +Histogram (HGO) engine. + +The VSP1 HGO is a histogram computation engine that can operate on RGB, YCrCb +or HSV data. It operates on a possibly cropped and subsampled input image and +computes the minimum, maximum and sum of all pixels as well as per-channel +histograms. + +The HGO can compute histograms independently per channel, on the maximum of the +three channels (RGB data only) or on the Y channel only (YCbCr only). It can +additionally output the histogram with 64 or 256 bins, resulting in four +possible modes of operation. + +- In *64 bins normal mode*, the HGO operates on the three channels independently + to compute three 64-bins histograms. RGB, YCbCr and HSV image formats are + supported. +- In *64 bins maximum mode*, the HGO operates on the maximum of the (R, G, B) + channels to compute a single 64-bins histogram. Only the RGB image format is + supported. +- In *256 bins normal mode*, the HGO operates on the Y channel to compute a + single 256-bins histogram. Only the YCbCr image format is supported. +- In *256 bins maximum mode*, the HGO operates on the maximum of the (R, G, B) + channels to compute a single 256-bins histogram. Only the RGB image format is + supported. + +**Byte Order.** +All data is stored in memory in little endian format. Each cell in the tables +contains one byte. + +.. flat-table:: VSP1 HGO Data - 64 Bins, Normal Mode (792 bytes) + :header-rows: 2 + :stub-columns: 0 + + * - Offset + - :cspan:`4` Memory + * - + - [31:24] + - [23:16] + - [15:8] + - [7:0] + * - 0 + - + - R/Cr/H max [7:0] + - + - R/Cr/H min [7:0] + * - 4 + - + - G/Y/S max [7:0] + - + - G/Y/S min [7:0] + * - 8 + - + - B/Cb/V max [7:0] + - + - B/Cb/V min [7:0] + * - 12 + - :cspan:`4` R/Cr/H sum [31:0] + * - 16 + - :cspan:`4` G/Y/S sum [31:0] + * - 20 + - :cspan:`4` B/Cb/V sum [31:0] + * - 24 + - :cspan:`4` R/Cr/H bin 0 [31:0] + * - + - :cspan:`4` ... + * - 276 + - :cspan:`4` R/Cr/H bin 63 [31:0] + * - 280 + - :cspan:`4` G/Y/S bin 0 [31:0] + * - + - :cspan:`4` ... + * - 532 + - :cspan:`4` G/Y/S bin 63 [31:0] + * - 536 + - :cspan:`4` B/Cb/V bin 0 [31:0] + * - + - :cspan:`4` ... + * - 788 + - :cspan:`4` B/Cb/V bin 63 [31:0] + +.. flat-table:: VSP1 HGO Data - 64 Bins, Max Mode (264 bytes) + :header-rows: 2 + :stub-columns: 0 + + * - Offset + - :cspan:`4` Memory + * - + - [31:24] + - [23:16] + - [15:8] + - [7:0] + * - 0 + - + - max(R,G,B) max [7:0] + - + - max(R,G,B) min [7:0] + * - 4 + - :cspan:`4` max(R,G,B) sum [31:0] + * - 8 + - :cspan:`4` max(R,G,B) bin 0 [31:0] + * - + - :cspan:`4` ... + * - 260 + - :cspan:`4` max(R,G,B) bin 63 [31:0] + +.. flat-table:: VSP1 HGO Data - 256 Bins, Normal Mode (1032 bytes) + :header-rows: 2 + :stub-columns: 0 + + * - Offset + - :cspan:`4` Memory + * - + - [31:24] + - [23:16] + - [15:8] + - [7:0] + * - 0 + - + - Y max [7:0] + - + - Y min [7:0] + * - 4 + - :cspan:`4` Y sum [31:0] + * - 8 + - :cspan:`4` Y bin 0 [31:0] + * - + - :cspan:`4` ... + * - 1028 + - :cspan:`4` Y bin 255 [31:0] + +.. flat-table:: VSP1 HGO Data - 256 Bins, Max Mode (1032 bytes) + :header-rows: 2 + :stub-columns: 0 + + * - Offset + - :cspan:`4` Memory + * - + - [31:24] + - [23:16] + - [15:8] + - [7:0] + * - 0 + - + - max(R,G,B) max [7:0] + - + - max(R,G,B) min [7:0] + * - 4 + - :cspan:`4` max(R,G,B) sum [31:0] + * - 8 + - :cspan:`4` max(R,G,B) bin 0 [31:0] + * - + - :cspan:`4` ... + * - 1028 + - :cspan:`4` max(R,G,B) bin 255 [31:0] diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst new file mode 100644 index 000000000000..fb9f79466319 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst @@ -0,0 +1,120 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-meta-fmt-vsp1-hgt: + +******************************* +V4L2_META_FMT_VSP1_HGT ('VSPT') +******************************* + +Renesas R-Car VSP1 2-D Histogram Data + + +Description +=========== + +This format describes histogram data generated by the Renesas R-Car VSP1 +2-D Histogram (HGT) engine. + +The VSP1 HGT is a histogram computation engine that operates on HSV +data. It operates on a possibly cropped and subsampled input image and +computes the sum, maximum and minimum of the S component as well as a +weighted frequency histogram based on the H and S components. + +The histogram is a matrix of 6 Hue and 32 Saturation buckets, 192 in +total. Each HSV value is added to one or more buckets with a weight +between 1 and 16 depending on the Hue areas configuration. Finding the +corresponding buckets is done by inspecting the H and S value independently. + +The Saturation position **n** (0 - 31) of the bucket in the matrix is +found by the expression: + + n = S / 8 + +The Hue position **m** (0 - 5) of the bucket in the matrix depends on +how the HGT Hue areas are configured. There are 6 user configurable Hue +Areas which can be configured to cover overlapping Hue values: + +:: + + Area 0 Area 1 Area 2 Area 3 Area 4 Area 5 + ________ ________ ________ ________ ________ ________ + \ /| |\ /| |\ /| |\ /| |\ /| |\ /| |\ / + \ / | | \ / | | \ / | | \ / | | \ / | | \ / | | \ / + X | | X | | X | | X | | X | | X | | X + / \ | | / \ | | / \ | | / \ | | / \ | | / \ | | / \ + / \| |/ \| |/ \| |/ \| |/ \| |/ \| |/ \ + 5U 0L 0U 1L 1U 2L 2U 3L 3U 4L 4U 5L 5U 0L + <0..............................Hue Value............................255> + +When two consecutive areas don't overlap (n+1L is equal to nU) the boundary +value is considered as part of the lower area. + +Pixels with a hue value included in the centre of an area (between nL and nU +included) are attributed to that single area and given a weight of 16. Pixels +with a hue value included in the overlapping region between two areas (between +n+1L and nU excluded) are attributed to both areas and given a weight for each +of these areas proportional to their position along the diagonal lines +(rounded down). + +The Hue area setup must match one of the following constrains: + +:: + + 0L <= 0U <= 1L <= 1U <= 2L <= 2U <= 3L <= 3U <= 4L <= 4U <= 5L <= 5U + +:: + + 0U <= 1L <= 1U <= 2L <= 2U <= 3L <= 3U <= 4L <= 4U <= 5L <= 5U <= 0L + +**Byte Order.** +All data is stored in memory in little endian format. Each cell in the tables +contains one byte. + +.. flat-table:: VSP1 HGT Data - (776 bytes) + :header-rows: 2 + :stub-columns: 0 + + * - Offset + - :cspan:`4` Memory + * - + - [31:24] + - [23:16] + - [15:8] + - [7:0] + * - 0 + - - + - S max [7:0] + - - + - S min [7:0] + * - 4 + - :cspan:`4` S sum [31:0] + * - 8 + - :cspan:`4` Histogram bucket (m=0, n=0) [31:0] + * - 12 + - :cspan:`4` Histogram bucket (m=0, n=1) [31:0] + * - + - :cspan:`4` ... + * - 132 + - :cspan:`4` Histogram bucket (m=0, n=31) [31:0] + * - 136 + - :cspan:`4` Histogram bucket (m=1, n=0) [31:0] + * - + - :cspan:`4` ... + * - 264 + - :cspan:`4` Histogram bucket (m=2, n=0) [31:0] + * - + - :cspan:`4` ... + * - 392 + - :cspan:`4` Histogram bucket (m=3, n=0) [31:0] + * - + - :cspan:`4` ... + * - 520 + - :cspan:`4` Histogram bucket (m=4, n=0) [31:0] + * - + - :cspan:`4` ... + * - 648 + - :cspan:`4` Histogram bucket (m=5, n=0) [31:0] + * - + - :cspan:`4` ... + * - 772 + - :cspan:`4` Histogram bucket (m=5, n=31) [31:0] diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst index 32d0c8743460..172a3825604e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst @@ -33,8 +33,8 @@ Layout of macroblocks in memory is presented in the following figure. .. _nv12mt: -.. figure:: nv12mt.* - :alt: nv12mt.pdf / nv12mt.svg +.. kernel-figure:: nv12mt.svg + :alt: nv12mt.svg :align: center V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout @@ -50,8 +50,8 @@ interleaved. Height of the buffer is aligned to 32. .. _nv12mt_ex: -.. figure:: nv12mt_example.* - :alt: nv12mt_example.pdf / nv12mt_example.svg +.. kernel-figure:: nv12mt_example.svg + :alt: nv12mt_example.svg :align: center Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst index 4f184c7aedab..00737152497b 100644 --- a/Documentation/media/uapi/v4l/pixfmt.rst +++ b/Documentation/media/uapi/v4l/pixfmt.rst @@ -34,4 +34,5 @@ see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.) pixfmt-013 sdr-formats tch-formats + meta-formats pixfmt-reserved diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst index 21686f93c38f..bf7e76dfbdf9 100644 --- a/Documentation/media/uapi/v4l/selection-api-003.rst +++ b/Documentation/media/uapi/v4l/selection-api-003.rst @@ -7,9 +7,9 @@ Selection targets .. _sel-targets-capture: -.. figure:: selection.* - :alt: selection.pdf / selection.svg - :align: center +.. kernel-figure:: selection.svg + :alt: selection.svg + :align: center Cropping and composing targets diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index d6152c907b8b..8e73bb00c0d5 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -1258,6 +1258,319 @@ The following tables list existing packed RGB formats. - b\ :sub:`2` - b\ :sub:`1` - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-RGB101010-1X30: + + - MEDIA_BUS_FMT_RGB101010_1X30 + - 0x1018 + - + - 0 + - 0 + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + +.. raw:: latex + + \endgroup + + +The following table list existing packed 36bit wide RGB formats. + +.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + +.. _v4l2-mbus-pixelcode-rgb-36: + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. flat-table:: 36bit RGB formats + :header-rows: 2 + :stub-columns: 0 + :widths: 36 7 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 + + * - Identifier + - Code + - + - :cspan:`35` Data organization + * - + - + - Bit + - 35 + - 34 + - 33 + - 32 + - 31 + - 30 + - 29 + - 28 + - 27 + - 26 + - 25 + - 24 + - 23 + - 22 + - 21 + - 20 + - 19 + - 18 + - 17 + - 16 + - 15 + - 14 + - 13 + - 12 + - 11 + - 10 + - 9 + - 8 + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _MEDIA-BUS-FMT-RGB121212-1X36: + + - MEDIA_BUS_FMT_RGB121212_1X36 + - 0x1019 + - + - r\ :sub:`11` + - r\ :sub:`10` + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`11` + - g\ :sub:`10` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`11` + - b\ :sub:`10` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + +.. raw:: latex + + \endgroup + + +The following table list existing packed 48bit wide RGB formats. + +.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + +.. _v4l2-mbus-pixelcode-rgb-48: + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. flat-table:: 48bit RGB formats + :header-rows: 3 + :stub-columns: 0 + :widths: 36 7 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 + + * - Identifier + - Code + - + - :cspan:`31` Data organization + * - + - + - Bit + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - 47 + - 46 + - 45 + - 44 + - 43 + - 42 + - 41 + - 40 + - 39 + - 38 + - 37 + - 36 + - 35 + - 34 + - 33 + - 32 + * - + - + - + - 31 + - 30 + - 29 + - 28 + - 27 + - 26 + - 25 + - 24 + - 23 + - 22 + - 21 + - 20 + - 19 + - 18 + - 17 + - 16 + - 15 + - 14 + - 13 + - 12 + - 11 + - 10 + - 9 + - 8 + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _MEDIA-BUS-FMT-RGB161616-1X48: + + - MEDIA_BUS_FMT_RGB161616_1X48 + - 0x101a + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - r\ :sub:`15` + - r\ :sub:`14` + - r\ :sub:`13` + - r\ :sub:`12` + - r\ :sub:`11` + - r\ :sub:`10` + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * - + - + - + - g\ :sub:`15` + - g\ :sub:`14` + - g\ :sub:`13` + - g\ :sub:`12` + - g\ :sub:`11` + - g\ :sub:`10` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`15` + - b\ :sub:`14` + - b\ :sub:`13` + - b\ :sub:`12` + - b\ :sub:`11` + - b\ :sub:`10` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` .. raw:: latex @@ -1514,8 +1827,8 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``. .. _bayer-patterns: -.. figure:: bayer.* - :alt: bayer.pdf / bayer.svg +.. kernel-figure:: bayer.svg + :alt: bayer.svg :align: center **Figure 4.8 Bayer Patterns** @@ -1577,10 +1890,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -1598,10 +1911,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -1619,10 +1932,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -1640,10 +1953,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` @@ -1661,10 +1974,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -1682,10 +1995,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -1703,10 +2016,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -1724,10 +2037,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` @@ -1745,10 +2058,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -1766,10 +2079,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -1787,10 +2100,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -1808,10 +2121,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` @@ -1829,10 +2142,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - 0 - 0 - 0 @@ -1848,10 +2161,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -1869,10 +2182,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -1888,10 +2201,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - 0 - 0 - 0 @@ -1909,10 +2222,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`9` - b\ :sub:`8` - b\ :sub:`7` @@ -1928,10 +2241,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`1` - b\ :sub:`0` - 0 @@ -1949,10 +2262,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`1` - b\ :sub:`0` - 0 @@ -1968,10 +2281,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`9` - b\ :sub:`8` - b\ :sub:`7` @@ -1987,10 +2300,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`9` - b\ :sub:`8` - b\ :sub:`7` @@ -2008,10 +2321,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`9` - g\ :sub:`8` - g\ :sub:`7` @@ -2029,10 +2342,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`9` - g\ :sub:`8` - g\ :sub:`7` @@ -2050,10 +2363,10 @@ organization is given as an example for the first pixel only. - - - - - - - - - - - - - - - + - + - + - + - - r\ :sub:`9` - r\ :sub:`8` - r\ :sub:`7` @@ -2069,10 +2382,10 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SBGGR12_1X12 - 0x3008 - - - - - - - - - - - - - + - + - + - + - - b\ :sub:`11` - b\ :sub:`10` - b\ :sub:`9` @@ -2090,10 +2403,10 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SGBRG12_1X12 - 0x3010 - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`11` - g\ :sub:`10` - g\ :sub:`9` @@ -2111,10 +2424,10 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SGRBG12_1X12 - 0x3011 - - - - - - - - - - - - - + - + - + - + - - g\ :sub:`11` - g\ :sub:`10` - g\ :sub:`9` @@ -2132,10 +2445,10 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SRGGB12_1X12 - 0x3012 - - - - - - - - - - - - - + - + - + - + - - r\ :sub:`11` - r\ :sub:`10` - r\ :sub:`9` @@ -2153,8 +2466,8 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SBGGR14_1X14 - 0x3019 - - - - - - - + - + - - b\ :sub:`13` - b\ :sub:`12` - b\ :sub:`11` @@ -2174,8 +2487,8 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SGBRG14_1X14 - 0x301a - - - - - - - + - + - - g\ :sub:`13` - g\ :sub:`12` - g\ :sub:`11` @@ -2195,8 +2508,8 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SGRBG14_1X14 - 0x301b - - - - - - - + - + - - g\ :sub:`13` - g\ :sub:`12` - g\ :sub:`11` @@ -2216,8 +2529,8 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SRGGB14_1X14 - 0x301c - - - - - - - + - + - - r\ :sub:`13` - r\ :sub:`12` - r\ :sub:`11` @@ -2344,7 +2657,8 @@ The format code is made of the following information. - The number of bus samples per pixel. Pixels that are wider than the bus width must be transferred in multiple samples. Common values are - 1, 1.5 (encoded as 1_5) and 2. + 0.5 (encoded as 0_5; in this case two pixels are transferred per bus + sample), 1, 1.5 (encoded as 1_5) and 2. - The bus width. When the bus width is larger than the number of bits per pixel component, several components are packed in a single bus @@ -5962,6 +6276,78 @@ the following codes. - v\ :sub:`2` - v\ :sub:`1` - v\ :sub:`0` + * .. _MEDIA-BUS-FMT-UYYVYY8-0-5X24: + + - MEDIA_BUS_FMT_UYYVYY8_0_5X24 + - 0x2026 + - + - + - + - + - + - + - + - + - + - u\ :sub:`7` + - u\ :sub:`6` + - u\ :sub:`5` + - u\ :sub:`4` + - u\ :sub:`3` + - u\ :sub:`2` + - u\ :sub:`1` + - u\ :sub:`0` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - v\ :sub:`7` + - v\ :sub:`6` + - v\ :sub:`5` + - v\ :sub:`4` + - v\ :sub:`3` + - v\ :sub:`2` + - v\ :sub:`1` + - v\ :sub:`0` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` * .. _MEDIA-BUS-FMT-UYVY12-1X24: - MEDIA_BUS_FMT_UYVY12_1X24 @@ -6287,6 +6673,78 @@ the following codes. - v\ :sub:`2` - v\ :sub:`1` - v\ :sub:`0` + * .. _MEDIA-BUS-FMT-UYYVYY10-0-5X30: + + - MEDIA_BUS_FMT_UYYVYY10_0_5X30 + - 0x2027 + - + - + - + - u\ :sub:`9` + - u\ :sub:`8` + - u\ :sub:`7` + - u\ :sub:`6` + - u\ :sub:`5` + - u\ :sub:`4` + - u\ :sub:`3` + - u\ :sub:`2` + - u\ :sub:`1` + - u\ :sub:`0` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + * - + - + - + - + - + - v\ :sub:`9` + - v\ :sub:`8` + - v\ :sub:`7` + - v\ :sub:`6` + - v\ :sub:`5` + - v\ :sub:`4` + - v\ :sub:`3` + - v\ :sub:`2` + - v\ :sub:`1` + - v\ :sub:`0` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` * .. _MEDIA-BUS-FMT-AYUV8-1X32: - MEDIA_BUS_FMT_AYUV8_1X32 @@ -6330,6 +6788,506 @@ the following codes. \endgroup + +The following table list existing packed 36bit wide YUV formats. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + +.. _v4l2-mbus-pixelcode-yuv8-36bit: + +.. flat-table:: 36bit YUV Formats + :header-rows: 2 + :stub-columns: 0 + :widths: 36 7 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 + + * - Identifier + - Code + - + - :cspan:`35` Data organization + * - + - + - Bit + - 35 + - 34 + - 33 + - 32 + - 31 + - 30 + - 29 + - 28 + - 27 + - 26 + - 25 + - 24 + - 23 + - 22 + - 21 + - 10 + - 19 + - 18 + - 17 + - 16 + - 15 + - 14 + - 13 + - 12 + - 11 + - 10 + - 9 + - 8 + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _MEDIA-BUS-FMT-UYYVYY12-0-5X36: + + - MEDIA_BUS_FMT_UYYVYY12_0_5X36 + - 0x2028 + - + - u\ :sub:`11` + - u\ :sub:`10` + - u\ :sub:`9` + - u\ :sub:`8` + - u\ :sub:`7` + - u\ :sub:`6` + - u\ :sub:`5` + - u\ :sub:`4` + - u\ :sub:`3` + - u\ :sub:`2` + - u\ :sub:`1` + - u\ :sub:`0` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + * - + - + - + - v\ :sub:`11` + - v\ :sub:`10` + - v\ :sub:`9` + - v\ :sub:`8` + - v\ :sub:`7` + - v\ :sub:`6` + - v\ :sub:`5` + - v\ :sub:`4` + - v\ :sub:`3` + - v\ :sub:`2` + - v\ :sub:`1` + - v\ :sub:`0` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + * .. _MEDIA-BUS-FMT-YUV12-1X36: + + - MEDIA_BUS_FMT_YUV12_1X36 + - 0x2029 + - + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - u\ :sub:`11` + - u\ :sub:`10` + - u\ :sub:`9` + - u\ :sub:`8` + - u\ :sub:`7` + - u\ :sub:`6` + - u\ :sub:`5` + - u\ :sub:`4` + - u\ :sub:`3` + - u\ :sub:`2` + - u\ :sub:`1` + - u\ :sub:`0` + - v\ :sub:`11` + - v\ :sub:`10` + - v\ :sub:`9` + - v\ :sub:`8` + - v\ :sub:`7` + - v\ :sub:`6` + - v\ :sub:`5` + - v\ :sub:`4` + - v\ :sub:`3` + - v\ :sub:`2` + - v\ :sub:`1` + - v\ :sub:`0` + + +.. raw:: latex + + \endgroup + + +The following table list existing packed 48bit wide YUV formats. + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + +.. _v4l2-mbus-pixelcode-yuv8-48bit: + +.. flat-table:: 48bit YUV Formats + :header-rows: 3 + :stub-columns: 0 + :widths: 36 7 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 + + * - Identifier + - Code + - + - :cspan:`31` Data organization + * - + - + - Bit + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - 47 + - 46 + - 45 + - 44 + - 43 + - 42 + - 41 + - 40 + - 39 + - 38 + - 37 + - 36 + - 35 + - 34 + - 33 + - 32 + * - + - + - + - 31 + - 30 + - 29 + - 28 + - 27 + - 26 + - 25 + - 24 + - 23 + - 22 + - 21 + - 10 + - 19 + - 18 + - 17 + - 16 + - 15 + - 14 + - 13 + - 12 + - 11 + - 10 + - 9 + - 8 + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _MEDIA-BUS-FMT-YUV16-1X48: + + - MEDIA_BUS_FMT_YUV16_1X48 + - 0x202a + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`8` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + * - + - + - + - u\ :sub:`15` + - u\ :sub:`14` + - u\ :sub:`13` + - u\ :sub:`12` + - u\ :sub:`11` + - u\ :sub:`10` + - u\ :sub:`9` + - u\ :sub:`8` + - u\ :sub:`7` + - u\ :sub:`6` + - u\ :sub:`5` + - u\ :sub:`4` + - u\ :sub:`3` + - u\ :sub:`2` + - u\ :sub:`1` + - u\ :sub:`0` + - v\ :sub:`15` + - v\ :sub:`14` + - v\ :sub:`13` + - v\ :sub:`12` + - v\ :sub:`11` + - v\ :sub:`10` + - v\ :sub:`9` + - v\ :sub:`8` + - v\ :sub:`7` + - v\ :sub:`6` + - v\ :sub:`5` + - v\ :sub:`4` + - v\ :sub:`3` + - v\ :sub:`2` + - v\ :sub:`1` + - v\ :sub:`0` + * .. _MEDIA-BUS-FMT-UYYVYY16-0-5X48: + + - MEDIA_BUS_FMT_UYYVYY16_0_5X48 + - 0x202b + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - u\ :sub:`15` + - u\ :sub:`14` + - u\ :sub:`13` + - u\ :sub:`12` + - u\ :sub:`11` + - u\ :sub:`10` + - u\ :sub:`9` + - u\ :sub:`8` + - u\ :sub:`7` + - u\ :sub:`6` + - u\ :sub:`5` + - u\ :sub:`4` + - u\ :sub:`3` + - u\ :sub:`2` + - u\ :sub:`1` + - u\ :sub:`0` + * - + - + - + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`8` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - v\ :sub:`15` + - v\ :sub:`14` + - v\ :sub:`13` + - v\ :sub:`12` + - v\ :sub:`11` + - v\ :sub:`10` + - v\ :sub:`9` + - v\ :sub:`8` + - v\ :sub:`7` + - v\ :sub:`6` + - v\ :sub:`5` + - v\ :sub:`4` + - v\ :sub:`3` + - v\ :sub:`2` + - v\ :sub:`1` + - v\ :sub:`0` + * - + - + - + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`9` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + - y\ :sub:`15` + - y\ :sub:`14` + - y\ :sub:`13` + - y\ :sub:`12` + - y\ :sub:`11` + - y\ :sub:`10` + - y\ :sub:`8` + - y\ :sub:`8` + - y\ :sub:`7` + - y\ :sub:`6` + - y\ :sub:`5` + - y\ :sub:`4` + - y\ :sub:`3` + - y\ :sub:`2` + - y\ :sub:`1` + - y\ :sub:`0` + + +.. raw:: latex + + \endgroup + HSV/HSL Formats ^^^^^^^^^^^^^^^ diff --git a/Documentation/media/uapi/v4l/video.rst b/Documentation/media/uapi/v4l/video.rst index a205fb87d566..d2bc06b064ad 100644 --- a/Documentation/media/uapi/v4l/video.rst +++ b/Documentation/media/uapi/v4l/video.rst @@ -8,9 +8,10 @@ Video Inputs and Outputs Video inputs and outputs are physical connectors of a device. These can be for example RF connectors (antenna/cable), CVBS a.k.a. Composite -Video, S-Video or RGB connectors. Video and VBI capture devices have -inputs. Video and VBI output devices have outputs, at least one each. -Radio devices have no video inputs or outputs. +Video, S-Video and RGB connectors. Camera sensors are also considered to +be a video input. Video and VBI capture devices have inputs. Video and +VBI output devices have outputs, at least one each. Radio devices have +no video inputs or outputs. To learn about the number and attributes of the available inputs and outputs applications can enumerate them with the diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst index 17aaaf939757..266e48ab237f 100644 --- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst +++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst @@ -33,7 +33,7 @@ Description To query the attributes of a video input applications initialize the ``index`` field of struct :c:type:`v4l2_input` and call the -:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers +:ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all inputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. @@ -117,8 +117,9 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - This input uses a tuner (RF demodulator). * - ``V4L2_INPUT_TYPE_CAMERA`` - 2 - - Analog baseband input, for example CVBS / Composite Video, - S-Video, RGB. + - Any non-tuner video input, for example Composite Video, + S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical, + today we would have called it ``_TYPE_VIDEO``. * - ``V4L2_INPUT_TYPE_TOUCH`` - 3 - This input is a touch device for capturing raw touch data. @@ -209,11 +210,11 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. * - ``V4L2_IN_CAP_DV_TIMINGS`` - 0x00000002 - This input supports setting video timings by using - VIDIOC_S_DV_TIMINGS. + ``VIDIOC_S_DV_TIMINGS``. * - ``V4L2_IN_CAP_STD`` - 0x00000004 - This input supports setting the TV standard by using - VIDIOC_S_STD. + ``VIDIOC_S_STD``. * - ``V4L2_IN_CAP_NATIVE_SIZE`` - 0x00000008 - This input supports setting the native size using the diff --git a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst index d7dd2742475a..93a2cf3b310c 100644 --- a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst +++ b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst @@ -33,11 +33,11 @@ Description To query the attributes of a video outputs applications initialize the ``index`` field of struct :c:type:`v4l2_output` and call -the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure. +the :ref:`VIDIOC_ENUMOUTPUT` with a pointer to this structure. Drivers fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all outputs applications shall begin at index zero, incrementing by one until the driver returns -EINVAL. +``EINVAL``. .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -112,11 +112,12 @@ EINVAL. - This output is an analog TV modulator. * - ``V4L2_OUTPUT_TYPE_ANALOG`` - 2 - - Analog baseband output, for example Composite / CVBS, S-Video, - RGB. + - Any non-modulator video output, for example Composite Video, + S-Video, HDMI. The naming as ``_TYPE_ANALOG`` is historical, + today we would have called it ``_TYPE_VIDEO``. * - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY`` - 3 - - [?] + - The video output will be copied to a :ref:`video overlay <overlay>`. @@ -132,11 +133,11 @@ EINVAL. * - ``V4L2_OUT_CAP_DV_TIMINGS`` - 0x00000002 - This output supports setting video timings by using - VIDIOC_S_DV_TIMINGS. + ``VIDIOC_S_DV_TIMINGS``. * - ``V4L2_OUT_CAP_STD`` - 0x00000004 - This output supports setting the TV standard by using - VIDIOC_S_STD. + ``VIDIOC_S_STD``. * - ``V4L2_OUT_CAP_NATIVE_SIZE`` - 0x00000008 - This output supports setting the native size using the diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst index aea276502f5e..e573c74138de 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst @@ -146,8 +146,20 @@ EBUSY - ``flags`` - Several flags giving more information about the format. See :ref:`dv-bt-flags` for a description of the flags. - * - __u32 - - ``reserved[14]`` + * - struct :c:type:`v4l2_fract` + - ``picture_aspect`` + - The picture aspect if the pixels are not square. Only valid if the + ``V4L2_DV_FL_HAS_PICTURE_ASPECT`` flag is set. + * - __u8 + - ``cea861_vic`` + - The Video Identification Code according to the CEA-861 standard. + Only valid if the ``V4L2_DV_FL_HAS_CEA861_VIC`` flag is set. + * - __u8 + - ``hdmi_vic`` + - The Video Identification Code according to the HDMI standard. + Only valid if the ``V4L2_DV_FL_HAS_HDMI_VIC`` flag is set. + * - __u8 + - ``reserved[46]`` - Reserved for future extensions. Drivers and applications must set the array to zero. diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst index 165d8314327e..12e0d9a63cd8 100644 --- a/Documentation/media/uapi/v4l/vidioc-querycap.rst +++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst @@ -236,6 +236,9 @@ specification the ioctl returns an ``EINVAL`` error code. * - ``V4L2_CAP_SDR_OUTPUT`` - 0x00400000 - The device supports the :ref:`SDR Output <sdr>` interface. + * - ``V4L2_CAP_META_CAPTURE`` + - 0x00800000 + - The device supports the :ref:`metadata` capture interface. * - ``V4L2_CAP_READWRITE`` - 0x01000000 - The device supports the :ref:`read() <rw>` and/or diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index 82769de801b1..41c5744a1239 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -301,12 +301,12 @@ See also the examples in :ref:`control`. - ``name``\ [32] - Name of the menu item, a NUL-terminated ASCII string. This information is intended for the user. This field is valid for - ``V4L2_CTRL_FLAG_MENU`` type controls. + ``V4L2_CTRL_TYPE_MENU`` type controls. * - - __s64 - ``value`` - Value of the integer menu item. This field is valid for - ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls. + ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls. * - __u32 - - ``reserved`` @@ -507,6 +507,19 @@ See also the examples in :ref:`control`. represents an action on the hardware. For example: clearing an error flag or triggering the flash. All the controls of the type ``V4L2_CTRL_TYPE_BUTTON`` have this flag set. + * .. _FLAG_MODIFY_LAYOUT: + + - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` + - 0x0400 + - Changing this control value may modify the layout of the + buffer (for video devices) or the media bus format (for sub-devices). + + A typical example would be the ``V4L2_CID_ROTATE`` control. + + Note that typically controls with this flag will also set the + ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or + streaming is in progress since most drivers do not support changing + the format in that case. Return Value diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index a606d1cdac13..90fe22a6414a 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -45,6 +45,7 @@ For more details see the file COPYING in the source distribution of Linux. meye omap3isp omap4_camera + philips pvrusb2 pxa_camera radiotrack diff --git a/Documentation/media/v4l-drivers/philips.rst b/Documentation/media/v4l-drivers/philips.rst new file mode 100644 index 000000000000..4f68947e6a13 --- /dev/null +++ b/Documentation/media/v4l-drivers/philips.rst @@ -0,0 +1,245 @@ +Philips webcams (pwc driver) +============================ + +This file contains some additional information for the Philips and OEM webcams. +E-mail: webcam@smcc.demon.nl Last updated: 2004-01-19 +Site: http://www.smcc.demon.nl/webcam/ + +As of this moment, the following cameras are supported: + + * Philips PCA645 + * Philips PCA646 + * Philips PCVC675 + * Philips PCVC680 + * Philips PCVC690 + * Philips PCVC720/40 + * Philips PCVC730 + * Philips PCVC740 + * Philips PCVC750 + * Askey VC010 + * Creative Labs Webcam 5 + * Creative Labs Webcam Pro Ex + * Logitech QuickCam 3000 Pro + * Logitech QuickCam 4000 Pro + * Logitech QuickCam Notebook Pro + * Logitech QuickCam Zoom + * Logitech QuickCam Orbit + * Logitech QuickCam Sphere + * Samsung MPC-C10 + * Samsung MPC-C30 + * Sotec Afina Eye + * AME CU-001 + * Visionite VCS-UM100 + * Visionite VCS-UC300 + +The main webpage for the Philips driver is at the address above. It contains +a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin +contains decompression routines that allow you to use higher image sizes and +framerates; in addition the webcam uses less bandwidth on the USB bus (handy +if you want to run more than 1 camera simultaneously). These routines fall +under a NDA, and may therefore not be distributed as source; however, its use +is completely optional. + +You can build this code either into your kernel, or as a module. I recommend +the latter, since it makes troubleshooting a lot easier. The built-in +microphone is supported through the USB Audio class. + +When you load the module you can set some default settings for the +camera; some programs depend on a particular image-size or -format and +don't know how to set it properly in the driver. The options are: + +size + Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or + 'vga', for an image size of resp. 128x96, 160x120, 176x144, + 320x240, 352x288 and 640x480 (of course, only for those cameras that + support these resolutions). + +fps + Specifies the desired framerate. Is an integer in the range of 4-30. + +fbufs + This parameter specifies the number of internal buffers to use for storing + frames from the cam. This will help if the process that reads images from + the cam is a bit slow or momentarily busy. However, on slow machines it + only introduces lag, so choose carefully. The default is 3, which is + reasonable. You can set it between 2 and 5. + +mbufs + This is an integer between 1 and 10. It will tell the module the number of + buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends. + The default is 2, which is adequate for most applications (double + buffering). + + Should you experience a lot of 'Dumping frame...' messages during + grabbing with a tool that uses mmap(), you might want to increase if. + However, it doesn't really buffer images, it just gives you a bit more + slack when your program is behind. But you need a multi-threaded or + forked program to really take advantage of these buffers. + + The absolute maximum is 10, but don't set it too high! Every buffer takes + up 460 KB of RAM, so unless you have a lot of memory setting this to + something more than 4 is an absolute waste. This memory is only + allocated during open(), so nothing is wasted when the camera is not in + use. + +power_save + When power_save is enabled (set to 1), the module will try to shut down + the cam on close() and re-activate on open(). This will save power and + turn off the LED. Not all cameras support this though (the 645 and 646 + don't have power saving at all), and some models don't work either (they + will shut down, but never wake up). Consider this experimental. By + default this option is disabled. + +compression (only useful with the plugin) + With this option you can control the compression factor that the camera + uses to squeeze the image through the USB bus. You can set the + parameter between 0 and 3:: + + 0 = prefer uncompressed images; if the requested mode is not available + in an uncompressed format, the driver will silently switch to low + compression. + 1 = low compression. + 2 = medium compression. + 3 = high compression. + + High compression takes less bandwidth of course, but it could also + introduce some unwanted artefacts. The default is 2, medium compression. + See the FAQ on the website for an overview of which modes require + compression. + + The compression parameter does not apply to the 645 and 646 cameras + and OEM models derived from those (only a few). Most cams honour this + parameter. + +leds + This settings takes 2 integers, that define the on/off time for the LED + (in milliseconds). One of the interesting things that you can do with + this is let the LED blink while the camera is in use. This:: + + leds=500,500 + + will blink the LED once every second. But with:: + + leds=0,0 + + the LED never goes on, making it suitable for silent surveillance. + + By default the camera's LED is on solid while in use, and turned off + when the camera is not used anymore. + + This parameter works only with the ToUCam range of cameras (720, 730, 740, + 750) and OEMs. For other cameras this command is silently ignored, and + the LED cannot be controlled. + + Finally: this parameters does not take effect UNTIL the first time you + open the camera device. Until then, the LED remains on. + +dev_hint + A long standing problem with USB devices is their dynamic nature: you + never know what device a camera gets assigned; it depends on module load + order, the hub configuration, the order in which devices are plugged in, + and the phase of the moon (i.e. it can be random). With this option you + can give the driver a hint as to what video device node (/dev/videoX) it + should use with a specific camera. This is also handy if you have two + cameras of the same model. + + A camera is specified by its type (the number from the camera model, + like PCA645, PCVC750VC, etc) and optionally the serial number (visible + in /sys/kernel/debug/usb/devices). A hint consists of a string with the + following format:: + + [type[.serialnumber]:]node + + The square brackets mean that both the type and the serialnumber are + optional, but a serialnumber cannot be specified without a type (which + would be rather pointless). The serialnumber is separated from the type + by a '.'; the node number by a ':'. + + This somewhat cryptic syntax is best explained by a few examples:: + + dev_hint=3,5 The first detected cam gets assigned + /dev/video3, the second /dev/video5. Any + other cameras will get the first free + available slot (see below). + + dev_hint=645:1,680:2 The PCA645 camera will get /dev/video1, + and a PCVC680 /dev/video2. + + dev_hint=645.0123:3,645.4567:0 The PCA645 camera with serialnumber + 0123 goes to /dev/video3, the same + camera model with the 4567 serial + gets /dev/video0. + + dev_hint=750:1,4,5,6 The PCVC750 camera will get /dev/video1, the + next 3 Philips cams will use /dev/video4 + through /dev/video6. + + Some points worth knowing: + + - Serialnumbers are case sensitive and must be written full, including + leading zeroes (it's treated as a string). + - If a device node is already occupied, registration will fail and + the webcam is not available. + - You can have up to 64 video devices; be sure to make enough device + nodes in /dev if you want to spread the numbers. + After /dev/video9 comes /dev/video10 (not /dev/videoA). + - If a camera does not match any dev_hint, it will simply get assigned + the first available device node, just as it used to be. + +trace + In order to better detect problems, it is now possible to turn on a + 'trace' of some of the calls the module makes; it logs all items in your + kernel log at debug level. + + The trace variable is a bitmask; each bit represents a certain feature. + If you want to trace something, look up the bit value(s) in the table + below, add the values together and supply that to the trace variable. + + ====== ======= ================================================ ======= + Value Value Description Default + (dec) (hex) + ====== ======= ================================================ ======= + 1 0x1 Module initialization; this will log messages On + while loading and unloading the module + + 2 0x2 probe() and disconnect() traces On + + 4 0x4 Trace open() and close() calls Off + + 8 0x8 read(), mmap() and associated ioctl() calls Off + + 16 0x10 Memory allocation of buffers, etc. Off + + 32 0x20 Showing underflow, overflow and Dumping frame On + messages + + 64 0x40 Show viewport and image sizes Off + + 128 0x80 PWCX debugging Off + ====== ======= ================================================ ======= + + For example, to trace the open() & read() functions, sum 8 + 4 = 12, + so you would supply trace=12 during insmod or modprobe. If + you want to turn the initialization and probing tracing off, set trace=0. + The default value for trace is 35 (0x23). + + + +Example:: + + # modprobe pwc size=cif fps=15 power_save=1 + +The fbufs, mbufs and trace parameters are global and apply to all connected +cameras. Each camera has its own set of buffers. + +size and fps only specify defaults when you open() the device; this is to +accommodate some tools that don't set the size. You can change these +settings after open() with the Video4Linux ioctl() calls. The default of +defaults is QCIF size at 10 fps. + +The compression parameter is semiglobal; it sets the initial compression +preference for all camera's, but this parameter can be set per camera with +the VIDIOCPWCSCQUAL ioctl() call. + +All parameters are optional. + diff --git a/Documentation/media/v4l-drivers/soc-camera.rst b/Documentation/media/v4l-drivers/soc-camera.rst index ba0c15dd092c..79d09e423700 100644 --- a/Documentation/media/v4l-drivers/soc-camera.rst +++ b/Documentation/media/v4l-drivers/soc-camera.rst @@ -12,7 +12,7 @@ The following terms are used in this document: control and configuration, and a parallel or a serial bus for data. - camera host - an interface, to which a camera is connected. Typically a specialised interface, present on many SoCs, e.g. PXA27x and PXA3xx, SuperH, - AVR32, i.MX27, i.MX31. + i.MX27, i.MX31. - camera host bus - a connection between a camera host and a camera. Can be parallel or serial, consists of data and control lines, e.g. clock, vertical and horizontal synchronization signals. diff --git a/Documentation/media/v4l-drivers/vivid.rst b/Documentation/media/v4l-drivers/vivid.rst index c8cf371e8bb9..3e44b2217f2d 100644 --- a/Documentation/media/v4l-drivers/vivid.rst +++ b/Documentation/media/v4l-drivers/vivid.rst @@ -263,6 +263,14 @@ all configurable using the following module options: removed. Unless overridden by ccs_cap_mode and/or ccs_out_mode the will default to enabling crop, compose and scaling. +- allocators: + + memory allocator selection, default is 0. It specifies the way buffers + will be allocated. + + - 0: vmalloc + - 1: dma-contig + Taken together, all these module options allow you to precisely customize the driver behavior and test your application with all sorts of permutations. It is also very suitable to emulate hardware that is not yet available, e.g. diff --git a/Documentation/media/v4l-drivers/zr364xx.rst b/Documentation/media/v4l-drivers/zr364xx.rst index f5280e366826..3d193f01d8bb 100644 --- a/Documentation/media/v4l-drivers/zr364xx.rst +++ b/Documentation/media/v4l-drivers/zr364xx.rst @@ -30,7 +30,7 @@ You can try the experience changing the vendor/product ID values (look at the source code). You can get these values by looking at /var/log/messages when you plug -your camera, or by typing : cat /proc/bus/usb/devices. +your camera, or by typing : cat /sys/kernel/debug/usb/devices. If you manage to use your cam with this code, you can send me a mail (royale@zerezo.com) with the name of your cam and a patch if needed. diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index e11a0d0a8931..a5cb0a8686ac 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -27,6 +27,7 @@ replace symbol V4L2_FIELD_SEQ_TB :c:type:`v4l2_field` replace symbol V4L2_FIELD_TOP :c:type:`v4l2_field` # Documented enum v4l2_buf_type +replace symbol V4L2_BUF_TYPE_META_CAPTURE :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SDR_CAPTURE :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SDR_OUTPUT :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SLICED_VBI_CAPTURE :c:type:`v4l2_buf_type` @@ -152,6 +153,7 @@ replace define V4L2_CAP_MODULATOR device-capabilities replace define V4L2_CAP_SDR_CAPTURE device-capabilities replace define V4L2_CAP_EXT_PIX_FORMAT device-capabilities replace define V4L2_CAP_SDR_OUTPUT device-capabilities +replace define V4L2_CAP_META_CAPTURE device-capabilities replace define V4L2_CAP_READWRITE device-capabilities replace define V4L2_CAP_ASYNCIO device-capabilities replace define V4L2_CAP_STREAMING device-capabilities @@ -339,6 +341,7 @@ replace define V4L2_CTRL_FLAG_WRITE_ONLY control-flags replace define V4L2_CTRL_FLAG_VOLATILE control-flags replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags +replace define V4L2_CTRL_FLAG_MODIFY_LAYOUT control-flags replace define V4L2_CTRL_FLAG_NEXT_CTRL control replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control diff --git a/Documentation/misc-devices/pci-endpoint-test.txt b/Documentation/misc-devices/pci-endpoint-test.txt new file mode 100644 index 000000000000..4ebc3594b32c --- /dev/null +++ b/Documentation/misc-devices/pci-endpoint-test.txt @@ -0,0 +1,35 @@ +Driver for PCI Endpoint Test Function + +This driver should be used as a host side driver if the root complex is +connected to a configurable PCI endpoint running *pci_epf_test* function +driver configured according to [1]. + +The "pci_endpoint_test" driver can be used to perform the following tests. + +The PCI driver for the test device performs the following tests + *) verifying addresses programmed in BAR + *) raise legacy IRQ + *) raise MSI IRQ + *) read data + *) write data + *) copy data + +This misc driver creates /dev/pci-endpoint-test.<num> for every +*pci_epf_test* function connected to the root complex and "ioctls" +should be used to perform the above tests. + +ioctl +----- + PCITEST_BAR: Tests the BAR. The number of the BAR to be tested + should be passed as argument. + PCITEST_LEGACY_IRQ: Tests legacy IRQ + PCITEST_MSI: Tests message signalled interrupts. The MSI number + to be tested should be passed as argument. + PCITEST_WRITE: Perform write tests. The size of the buffer should be passed + as argument. + PCITEST_READ: Perform read tests. The size of the buffer should be passed + as argument. + PCITEST_COPY: Perform read tests. The size of the buffer should be passed + as argument. + +[1] -> Documentation/PCI/endpoint/function/binding/pci-test.txt diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/mmc/mmc-dev-attrs.txt index 404a0e9e92b0..4ad0bb17f343 100644 --- a/Documentation/mmc/mmc-dev-attrs.txt +++ b/Documentation/mmc/mmc-dev-attrs.txt @@ -13,7 +13,7 @@ SD and MMC Device Attributes All attributes are read-only. - cid Card Identifaction Register + cid Card Identification Register csd Card Specific Data Register scr SD Card Configuration Register (SD only) date Manufacturing Date (from CID Register) @@ -30,6 +30,7 @@ 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 Note on Erase Size and Preferred Erase Size: @@ -71,6 +72,6 @@ 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 mutliple of 128kB block. + "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 diff --git a/Documentation/networking/cdc_mbim.txt b/Documentation/networking/cdc_mbim.txt index b9482ca10254..e4c376abbdad 100644 --- a/Documentation/networking/cdc_mbim.txt +++ b/Documentation/networking/cdc_mbim.txt @@ -332,7 +332,7 @@ References [5] "MBIM (Mobile Broadband Interface Model) Registry" - http://compliance.usb.org/mbim/ -[6] "/proc/bus/usb filesystem output" +[6] "/dev/bus/usb filesystem output" - Documentation/usb/proc_usb_info.txt [7] "/sys/bus/usb/devices/.../descriptors" diff --git a/Documentation/networking/e100.txt b/Documentation/networking/e100.txt index 42ddbd4b52a9..54810b82c01a 100644 --- a/Documentation/networking/e100.txt +++ b/Documentation/networking/e100.txt @@ -130,7 +130,7 @@ Additional Configurations version 1.6 or later is required for this functionality. The latest release of ethtool can be found from - http://ftp.kernel.org/pub/software/network/ethtool/ + https://www.kernel.org/pub/software/network/ethtool/ Enabling Wake on LAN* (WoL) --------------------------- diff --git a/Documentation/networking/e1000.txt b/Documentation/networking/e1000.txt index 437b2099cced..1f6ed848363d 100644 --- a/Documentation/networking/e1000.txt +++ b/Documentation/networking/e1000.txt @@ -435,7 +435,7 @@ Additional Configurations version 1.6 or later is required for this functionality. The latest release of ethtool can be found from - http://ftp.kernel.org/pub/software/network/ethtool/ + https://www.kernel.org/pub/software/network/ethtool/ Enabling Wake on LAN* (WoL) --------------------------- diff --git a/Documentation/networking/e1000e.txt b/Documentation/networking/e1000e.txt index ad2d9f38ce14..12089547baed 100644 --- a/Documentation/networking/e1000e.txt +++ b/Documentation/networking/e1000e.txt @@ -274,7 +274,7 @@ Additional Configurations diagnostics, as well as displaying statistical information. We strongly recommend downloading the latest version of ethtool at: - http://ftp.kernel.org/pub/software/network/ethtool/ + https://kernel.org/pub/software/network/ethtool/ NOTE: When validating enable/disable tests on some parts (82578, for example) you need to add a few seconds between tests when working with ethtool. diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index 683ada5ad81d..b69b205501de 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -595,10 +595,9 @@ got from bpf_prog_create(), and 'ctx' the given context (e.g. skb pointer). All constraints and restrictions from bpf_check_classic() apply before a conversion to the new layout is being done behind the scenes! -Currently, the classic BPF format is being used for JITing on most of the -architectures. x86-64, aarch64 and s390x perform JIT compilation from eBPF -instruction set, however, future work will migrate other JIT compilers as well, -so that they will profit from the very same benefits. +Currently, the classic BPF format is being used for JITing on most 32-bit +architectures, whereas x86-64, aarch64, s390x, powerpc64, sparc64 perform JIT +compilation from eBPF instruction set. Some core changes of the new internal format: diff --git a/Documentation/networking/i40e.txt b/Documentation/networking/i40e.txt index a251bf4fe9c9..57e616ed10b0 100644 --- a/Documentation/networking/i40e.txt +++ b/Documentation/networking/i40e.txt @@ -63,6 +63,78 @@ Additional Configurations The latest release of ethtool can be found from https://www.kernel.org/pub/software/network/ethtool + + Flow Director n-ntuple traffic filters (FDir) + --------------------------------------------- + The driver utilizes the ethtool interface for configuring ntuple filters, + via "ethtool -N <device> <filter>". + + The sctp4, ip4, udp4, and tcp4 flow types are supported with the standard + fields including src-ip, dst-ip, src-port and dst-port. The driver only + supports fully enabling or fully masking the fields, so use of the mask + fields for partial matches is not supported. + + Additionally, the driver supports using the action to specify filters for a + Virtual Function. You can specify the action as a 64bit value, where the + lower 32 bits represents the queue number, while the next 8 bits represent + which VF. Note that 0 is the PF, so the VF identifier is offset by 1. For + example: + + ... action 0x800000002 ... + + Would indicate to direct traffic for Virtual Function 7 (8 minus 1) on queue + 2 of that VF. + + The driver also supports using the user-defined field to specify 2 bytes of + arbitrary data to match within the packet payload in addition to the regular + fields. The data is specified in the lower 32bits of the user-def field in + the following way: + + +----------------------------+---------------------------+ + | 31 28 24 20 16 | 15 12 8 4 0| + +----------------------------+---------------------------+ + | offset into packet payload | 2 bytes of flexible data | + +----------------------------+---------------------------+ + + As an example, + + ... user-def 0x4FFFF .... + + means to match the value 0xFFFF 4 bytes into the packet payload. Note that + the offset is based on the beginning of the payload, and not the beginning + of the packet. Thus + + flow-type tcp4 ... user-def 0x8BEAF .... + + would match TCP/IPv4 packets which have the value 0xBEAF 8bytes into the + TCP/IPv4 payload. + + For ICMP, the hardware parses the ICMP header as 4 bytes of header and 4 + bytes of payload, so if you want to match an ICMP frames payload you may need + to add 4 to the offset in order to match the data. + + Furthermore, the offset can only be up to a value of 64, as the hardware + will only read up to 64 bytes of data from the payload. It must also be even + as the flexible data is 2 bytes long and must be aligned to byte 0 of the + packet payload. + + When programming filters, the hardware is limited to using a single input + set for each flow type. This means that it is an error to program two + different filters with the same type that don't match on the same fields. + Thus the second of the following two commands will fail: + + ethtool -N <device> flow-type tcp4 src-ip 192.168.0.7 action 5 + ethtool -N <device> flow-type tcp4 dst-ip 192.168.15.18 action 1 + + This is because the first filter will be accepted and reprogram the input + set for TCPv4 filters, but the second filter will be unable to reprogram the + input set until all the conflicting TCPv4 filters are first removed. + + Note that the user-defined flexible offset is also considered part of the + input set and cannot be programmed separately for multiple filters of the + same type. However, the flexible data is not part of the input set and + multiple filters may use the same offset but match against different data. + Data Center Bridging (DCB) -------------------------- DCB configuration is not currently supported. diff --git a/Documentation/networking/igb.txt b/Documentation/networking/igb.txt index 15534fdd09a8..f90643ef39c9 100644 --- a/Documentation/networking/igb.txt +++ b/Documentation/networking/igb.txt @@ -63,7 +63,7 @@ Additional Configurations diagnostics, as well as displaying statistical information. The latest version of ethtool can be found at: - http://ftp.kernel.org/pub/software/network/ethtool/ + https://www.kernel.org/pub/software/network/ethtool/ Enabling Wake on LAN* (WoL) --------------------------- diff --git a/Documentation/networking/igbvf.txt b/Documentation/networking/igbvf.txt index 40db17a6665b..bd404735fb46 100644 --- a/Documentation/networking/igbvf.txt +++ b/Documentation/networking/igbvf.txt @@ -62,7 +62,7 @@ Additional Configurations version 3.0 or later is required for this functionality, although we strongly recommend downloading the latest version at: - http://ftp.kernel.org/pub/software/network/ethtool/ + https://www.kernel.org/pub/software/network/ethtool/ Support ======= diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index fc73eeb7b3b8..974ab47ae53a 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -73,6 +73,14 @@ fib_multipath_use_neigh - BOOLEAN 0 - disabled 1 - enabled +fib_multipath_hash_policy - INTEGER + Controls which hash policy to use for multipath routes. Only valid + for kernels built with CONFIG_IP_ROUTE_MULTIPATH enabled. + Default: 0 (Layer 3) + Possible values: + 0 - Layer 3 + 1 - Layer 4 + route/max_size - INTEGER Maximum number of routes allowed in the kernel. Increase this when using large numbers of interfaces and/or routes. @@ -594,6 +602,14 @@ tcp_fastopen - INTEGER Note that that additional client or server features are only effective if the basic support (0x1 and 0x2) are enabled respectively. +tcp_fastopen_blackhole_timeout_sec - INTEGER + Initial time period in second to disable Fastopen on active TCP sockets + when a TFO firewall blackhole issue happens. + This time period will grow exponentially when more blackhole issues + get detected right after Fastopen is re-enabled and will reset to + initial value when the blackhole issue goes away. + By default, it is set to 1hr. + tcp_syn_retries - INTEGER Number of times initial SYNs for an active TCP connection attempt will be retransmitted. Should not be higher than 127. Default value @@ -640,11 +656,6 @@ tcp_tso_win_divisor - INTEGER building larger TSO frames. Default: 3 -tcp_tw_recycle - BOOLEAN - Enable fast recycling TIME-WAIT sockets. Default value is 0. - It should not be changed without advice/request of technical - experts. - tcp_tw_reuse - BOOLEAN Allow to reuse TIME-WAIT sockets for new connections when it is safe from protocol viewpoint. Default value is 0. @@ -853,12 +864,21 @@ ip_dynaddr - BOOLEAN ip_early_demux - BOOLEAN Optimize input packet processing down to one demux for certain kinds of local sockets. Currently we only do this - for established TCP sockets. + for established TCP and connected UDP sockets. It may add an additional cost for pure routing workloads that reduces overall throughput, in such case you should disable it. Default: 1 +tcp_early_demux - BOOLEAN + Enable early demux for established TCP sockets. + Default: 1 + +udp_early_demux - BOOLEAN + Enable early demux for connected UDP sockets. Disable this if + your system could experience more unconnected load. + Default: 1 + icmp_echo_ignore_all - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO requests sent to it. @@ -1006,7 +1026,8 @@ accept_redirects - BOOLEAN FALSE (router) forwarding - BOOLEAN - Enable IP forwarding on this interface. + Enable IP forwarding on this interface. This controls whether packets + received _on_ this interface can be forwarded. mc_forwarding - BOOLEAN Do multicast routing. The kernel needs to be compiled with CONFIG_MROUTE @@ -1457,11 +1478,20 @@ accept_ra_pinfo - BOOLEAN Functional default: enabled if accept_ra is enabled. disabled if accept_ra is disabled. +accept_ra_rt_info_min_plen - INTEGER + Minimum prefix length of Route Information in RA. + + Route Information w/ prefix smaller than this variable shall + be ignored. + + Functional default: 0 if accept_ra_rtr_pref is enabled. + -1 if accept_ra_rtr_pref is disabled. + accept_ra_rt_info_max_plen - INTEGER Maximum prefix length of Route Information in RA. - Route Information w/ prefix larger than or equal to this - variable shall be ignored. + Route Information w/ prefix larger than this variable shall + be ignored. Functional default: 0 if accept_ra_rtr_pref is enabled. -1 if accept_ra_rtr_pref is disabled. diff --git a/Documentation/networking/ipvs-sysctl.txt b/Documentation/networking/ipvs-sysctl.txt index e6b1c025fdd8..056898685d40 100644 --- a/Documentation/networking/ipvs-sysctl.txt +++ b/Documentation/networking/ipvs-sysctl.txt @@ -175,6 +175,14 @@ nat_icmp_send - BOOLEAN for VS/NAT when the load balancer receives packets from real servers but the connection entries don't exist. +pmtu_disc - BOOLEAN + 0 - disabled + not 0 - enabled (default) + + By default, reject with FRAG_NEEDED all DF packets that exceed + the PMTU, irrespective of the forwarding method. For TUN method + the flag can be disabled to fragment such packets. + secure_tcp - INTEGER 0 - disabled (default) @@ -185,15 +193,59 @@ secure_tcp - INTEGER The value definition is the same as that of drop_entry and drop_packet. -sync_threshold - INTEGER - default 3 +sync_threshold - vector of 2 INTEGERs: sync_threshold, sync_period + default 3 50 + + It sets synchronization threshold, which is the minimum number + of incoming packets that a connection needs to receive before + the connection will be synchronized. A connection will be + synchronized, every time the number of its incoming packets + modulus sync_period equals the threshold. The range of the + threshold is from 0 to sync_period. + + When sync_period and sync_refresh_period are 0, send sync only + for state changes or only once when pkts matches sync_threshold + +sync_refresh_period - UNSIGNED INTEGER + default 0 + + In seconds, difference in reported connection timer that triggers + new sync message. It can be used to avoid sync messages for the + specified period (or half of the connection timeout if it is lower) + if connection state is not changed since last sync. + + This is useful for normal connections with high traffic to reduce + sync rate. Additionally, retry sync_retries times with period of + sync_refresh_period/8. + +sync_retries - INTEGER + default 0 + + Defines sync retries with period of sync_refresh_period/8. Useful + to protect against loss of sync messages. The range of the + sync_retries is from 0 to 3. + +sync_qlen_max - UNSIGNED LONG + + Hard limit for queued sync messages that are not sent yet. It + defaults to 1/32 of the memory pages but actually represents + number of messages. It will protect us from allocating large + parts of memory when the sending rate is lower than the queuing + rate. + +sync_sock_size - INTEGER + default 0 + + Configuration of SNDBUF (master) or RCVBUF (slave) socket limit. + Default value is 0 (preserve system defaults). + +sync_ports - INTEGER + default 1 - It sets synchronization threshold, which is the minimum number - of incoming packets that a connection needs to receive before - the connection will be synchronized. A connection will be - synchronized, every time the number of its incoming packets - modulus 50 equals the threshold. The range of the threshold is - from 0 to 49. + The number of threads that master and backup servers can use for + sync traffic. Every thread will use single UDP port, thread 0 will + use the default port 8848 while last thread will use port + 8848+sync_ports-1. snat_reroute - BOOLEAN 0 - disabled diff --git a/Documentation/networking/ixgb.txt b/Documentation/networking/ixgb.txt index 9b4a10a1cf50..09f71d71920a 100644 --- a/Documentation/networking/ixgb.txt +++ b/Documentation/networking/ixgb.txt @@ -313,7 +313,7 @@ Additional Configurations version 1.6 or later is required for this functionality. The latest release of ethtool can be found from - http://ftp.kernel.org/pub/software/network/ethtool/ + https://www.kernel.org/pub/software/network/ethtool/ NOTE: The ethtool version 1.6 only supports a limited set of ethtool options. Support for a more complete ethtool feature set can be enabled by diff --git a/Documentation/networking/ixgbe.txt b/Documentation/networking/ixgbe.txt index 6f0cb57b59c6..687835415707 100644 --- a/Documentation/networking/ixgbe.txt +++ b/Documentation/networking/ixgbe.txt @@ -272,7 +272,7 @@ Additional Configurations ethtool version is required for this functionality. The latest release of ethtool can be found from - http://ftp.kernel.org/pub/software/network/ethtool/ + https://www.kernel.org/pub/software/network/ethtool/ FCoE ---- diff --git a/Documentation/networking/mpls-sysctl.txt b/Documentation/networking/mpls-sysctl.txt index 15d8d16934fd..2f24a1912a48 100644 --- a/Documentation/networking/mpls-sysctl.txt +++ b/Documentation/networking/mpls-sysctl.txt @@ -19,6 +19,25 @@ platform_labels - INTEGER Possible values: 0 - 1048575 Default: 0 +ip_ttl_propagate - BOOL + Control whether TTL is propagated from the IPv4/IPv6 header to + the MPLS header on imposing labels and propagated from the + MPLS header to the IPv4/IPv6 header on popping the last label. + + If disabled, the MPLS transport network will appear as a + single hop to transit traffic. + + 0 - disabled / RFC 3443 [Short] Pipe Model + 1 - enabled / RFC 3443 Uniform Model (default) + +default_ttl - BOOL + Default TTL value to use for MPLS packets where it cannot be + propagated from an IP header, either because one isn't present + or ip_ttl_propagate has been disabled. + + Possible values: 1 - 255 + Default: 255 + conf/<interface>/input - BOOL Control whether packets can be input on this interface. diff --git a/Documentation/networking/switchdev.txt b/Documentation/networking/switchdev.txt index 2bbac05ab9e2..3e7b946dea27 100644 --- a/Documentation/networking/switchdev.txt +++ b/Documentation/networking/switchdev.txt @@ -13,43 +13,43 @@ an example setup using a data-center-class switch ASIC chip. Other setups with SR-IOV or soft switches, such as OVS, are possible. -                             User-space tools                                  -                                                                               -       user space                   |                                          -      +-------------------------------------------------------------------+    -       kernel                       | Netlink                                  -                                    |                                          -                     +--------------+-------------------------------+          -                     |         Network stack                        |          -                     |           (Linux)                            |          -                     |                                              |          -                     +----------------------------------------------+          -                                                                               +                             User-space tools + +       user space                   | +      +-------------------------------------------------------------------+ +       kernel                       | Netlink +                                    | +                     +--------------+-------------------------------+ +                     |         Network stack                        | +                     |           (Linux)                            | +                     |                                              | +                     +----------------------------------------------+ + sw1p2 sw1p4 sw1p6 -                      sw1p1  + sw1p3 +  sw1p5 +         eth1              -                        +    |    +    |    +    |            +                -                        |    |    |    |    |    |            |                -                     +--+----+----+----+-+--+----+---+  +-----+-----+          -                     |         Switch driver         |  |    mgmt   |          -                     |        (this document)        |  |   driver  |          -                     |                               |  |           |          -                     +--------------+----------------+  +-----------+          -                                    |                                          -       kernel                       | HW bus (eg PCI)                          -      +-------------------------------------------------------------------+    -       hardware                     |                                          -                     +--------------+---+------------+                         -                     |         Switch device (sw1)   |                         -                     |  +----+                       +--------+                -                     |  |    v offloaded data path   | mgmt port               -                     |  |    |                       |                         -                     +--|----|----+----+----+----+---+                         -                        |    |    |    |    |    |                             -                        +    +    +    +    +    +                             +                      sw1p1  + sw1p3 +  sw1p5 +         eth1 +                        +    |    +    |    +    |            + +                        |    |    |    |    |    |            | +                     +--+----+----+----+-+--+----+---+  +-----+-----+ +                     |         Switch driver         |  |    mgmt   | +                     |        (this document)        |  |   driver  | +                     |                               |  |           | +                     +--------------+----------------+  +-----------+ +                                    | +       kernel                       | HW bus (eg PCI) +      +-------------------------------------------------------------------+ +       hardware                     | +                     +--------------+---+------------+ +                     |         Switch device (sw1)   | +                     |  +----+                       +--------+ +                     |  |    v offloaded data path   | mgmt port +                     |  |    |                       | +                     +--|----|----+----+----+----+---+ +                        |    |    |    |    |    | +                        +    +    +    +    +    +                        p1   p2   p3   p4   p5   p6 -                                        -                             front-panel ports                                 -                                                                               + +                             front-panel ports + Fig 1. diff --git a/Documentation/perf/qcom_l3_pmu.txt b/Documentation/perf/qcom_l3_pmu.txt new file mode 100644 index 000000000000..96b3a9444a0d --- /dev/null +++ b/Documentation/perf/qcom_l3_pmu.txt @@ -0,0 +1,25 @@ +Qualcomm Datacenter Technologies L3 Cache Performance Monitoring Unit (PMU) +=========================================================================== + +This driver supports the L3 cache PMUs found in Qualcomm Datacenter Technologies +Centriq SoCs. The L3 cache on these SOCs is composed of multiple slices, shared +by all cores within a socket. Each slice is exposed as a separate uncore perf +PMU with device name l3cache_<socket>_<instance>. User space is responsible +for aggregating across slices. + +The driver provides a description of its available events and configuration +options in sysfs, see /sys/devices/l3cache*. Given that these are uncore PMUs +the driver also exposes a "cpumask" sysfs attribute which contains a mask +consisting of one CPU per socket which will be used to handle all the PMU +events on that socket. + +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.: + + perf stat -e l3cache_0_0/read-miss,lc/ + +Given that these are uncore PMUs the driver does not support sampling, therefore +"perf record" will not work. Per-task perf sessions are not supported. diff --git a/Documentation/phy.txt b/Documentation/phy.txt index 0aa994bd9a91..383cdd863f08 100644 --- a/Documentation/phy.txt +++ b/Documentation/phy.txt @@ -97,7 +97,7 @@ should contain the phy name as given in the dt data and in the case of non-dt boot, it should contain the label of the PHY. The two devm_phy_get associates the device with the PHY using devres on successful PHY get. On driver detach, release function is invoked on -the the devres data and devres data is freed. phy_optional_get and +the devres data and devres data is freed. phy_optional_get and devm_phy_optional_get should be used when the phy is optional. These two functions will never return -ENODEV, but instead returns NULL when the phy cannot be found.Some generic drivers, such as ehci, may use multiple diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 54bd5faa8782..f2af35f6d6b2 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -77,9 +77,15 @@ static struct pinctrl_desc foo_desc = { int __init foo_probe(void) { + int error; + struct pinctrl_dev *pctl; - return pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl); + error = pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl); + if (error) + return error; + + return pinctrl_enable(pctl); } To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 64546eb9a16a..ee69d7532172 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -478,15 +478,23 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: - set the power.last_busy field to the current time void pm_runtime_use_autosuspend(struct device *dev); - - set the power.use_autosuspend flag, enabling autosuspend delays + - 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); - - clear the power.use_autosuspend flag, disabling autosuspend delays + - 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); - set the power.autosuspend_delay value to 'delay' (expressed in milliseconds); if 'delay' is negative then runtime suspends are - prevented + prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be + called or the device's usage counter may be decremented and + pm_runtime_idle called depending on if power.autosuspend_delay is + 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); - calculate the time when the current autosuspend delay period will expire, @@ -836,9 +844,8 @@ of the non-autosuspend counterparts: Instead of: pm_runtime_put_sync use: pm_runtime_put_sync_autosuspend. Drivers may also continue to use the non-autosuspend helper functions; they -will behave normally, not taking the autosuspend delay into account. -Similarly, if the power.use_autosuspend field isn't set then the autosuspend -helper functions will behave just like the non-autosuspend counterparts. +will behave normally, which means sometimes taking the autosuspend delay into +account (see pm_runtime_idle). Under some circumstances a driver or subsystem may want to prevent a device from autosuspending immediately, even though the usage counter is zero and the diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index 8cc17ca71813..9f2f942a01cf 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -406,7 +406,7 @@ 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/usb/persist.txt. +Documentation/driver-api/usb/persist.rst. Q: Can I suspend-to-disk using a swap partition under LVM? diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.txt index d5506ba0fef7..c5e8d5098ed3 100644 --- a/Documentation/powerpc/cxl.txt +++ b/Documentation/powerpc/cxl.txt @@ -21,7 +21,7 @@ Introduction Hardware overview ================= - POWER8 FPGA + POWER8/9 FPGA +----------+ +---------+ | | | | | CPU | | AFU | @@ -34,7 +34,7 @@ Hardware overview | | CAPP |<------>| | +---+------+ PCIE +---------+ - The POWER8 chip has a Coherently Attached Processor Proxy (CAPP) + The POWER8/9 chip has a Coherently Attached Processor Proxy (CAPP) unit which is part of the PCIe Host Bridge (PHB). This is managed by Linux by calls into OPAL. Linux doesn't directly program the CAPP. @@ -59,6 +59,17 @@ Hardware overview the fault. The context to which this fault is serviced is based on who owns that acceleration function. + POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0. + POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0. + This PSL Version 9 provides new features such as: + * Interaction with the nest MMU on the P9 chip. + * Native DMA support. + * Supports sending ASB_Notify messages for host thread wakeup. + * Supports Atomic operations. + * .... + + Cards with a PSL9 won't work on a POWER8 system and cards with a + PSL8 won't work on a POWER9 system. AFU Modes ========= diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.txt index 6d9a2ed32cad..66b4496d6619 100644 --- a/Documentation/powerpc/cxlflash.txt +++ b/Documentation/powerpc/cxlflash.txt @@ -239,6 +239,11 @@ DK_CXLFLASH_USER_VIRTUAL resource handle that is provided is already referencing provisioned storage. This is reflected by the last LBA being a non-zero value. + When a LUN is accessible from more than one port, this ioctl will + return with the DK_CXLFLASH_ALL_PORTS_ACTIVE return flag set. This + provides the user with a hint that I/O can be retried in the event + of an I/O error as the LUN can be reached over multiple paths. + DK_CXLFLASH_VLUN_RESIZE ----------------------- This ioctl is responsible for resizing a previously created virtual diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt index 3007bc98af28..9cabaf8a207e 100644 --- a/Documentation/powerpc/firmware-assisted-dump.txt +++ b/Documentation/powerpc/firmware-assisted-dump.txt @@ -55,10 +55,14 @@ as follows: booted with restricted memory. By default, the boot memory size will be the larger of 5% of system RAM or 256MB. Alternatively, user can also specify boot memory size - through boot parameter 'fadump_reserve_mem=' which will - override the default calculated size. Use this option - if default boot memory size is not sufficient for second - kernel to boot successfully. + through boot parameter 'crashkernel=' which will override + 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.txt. If any offset is + provided in crashkernel= parameter, it will be ignored + as fadump reserves memory at end of RAM for boot memory + dump preservation in case of a crash. -- After the low memory (boot memory) area has been saved, the firmware will reset PCI and other hardware state. It will @@ -105,21 +109,21 @@ memory is held. If there is no waiting dump data, then only the memory required to hold CPU state, HPTE region, boot memory dump and elfcore -header, is reserved at the top of memory (see Fig. 1). This area -is *not* released: this region will be kept permanently reserved, -so that it can act as a receptacle for a copy of the boot memory -content in addition to CPU state and HPTE region, in the case a -crash does occur. +header, is usually reserved at an offset greater than boot memory +size (see Fig. 1). This area is *not* released: this region will +be kept permanently reserved, so that it can act as a receptacle +for a copy of the boot memory content in addition to CPU state +and HPTE region, in the case a crash does occur. o Memory Reservation during first kernel - Low memory Top of memory + Low memory Top of memory 0 boot memory size | - | | |<--Reserved dump area -->| - V V | Permanent Reservation V - +-----------+----------/ /----------+---+----+-----------+----+ - | | |CPU|HPTE| DUMP |ELF | - +-----------+----------/ /----------+---+----+-----------+----+ + | | |<--Reserved dump area -->| | + V V | Permanent Reservation | V + +-----------+----------/ /---+---+----+-----------+----+------+ + | | |CPU|HPTE| DUMP |ELF | | + +-----------+----------/ /---+---+----+-----------+----+------+ | ^ | | \ / @@ -135,12 +139,12 @@ crash does occur. 0 boot memory size | | |<------------- Reserved dump area ----------- -->| V V V - +-----------+----------/ /----------+---+----+-----------+----+ - | | |CPU|HPTE| DUMP |ELF | - +-----------+----------/ /----------+---+----+-----------+----+ - | | - V V - Used by second /proc/vmcore + +-----------+----------/ /---+---+----+-----------+----+------+ + | | |CPU|HPTE| DUMP |ELF | | + +-----------+----------/ /---+---+----+-----------+----+------+ + | | + V V + Used by second /proc/vmcore kernel to boot Fig. 2 @@ -158,13 +162,16 @@ How to enable firmware-assisted dump (fadump): 1. Set config option CONFIG_FA_DUMP=y and build kernel. 2. Boot into linux kernel with 'fadump=on' kernel cmdline option. -3. Optionally, user can also set 'fadump_reserve_mem=' kernel cmdline +3. Optionally, user can also set 'crashkernel=' kernel cmdline to specify size of the memory to reserve for boot memory dump preservation. -NOTE: If firmware-assisted dump fails to reserve memory then it will - fallback to existing kdump mechanism if 'crashkernel=' option - is set at kernel cmdline. +NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead + use 'crashkernel=' to specify size of the memory to reserve + for boot memory dump preservation. + 2. If firmware-assisted dump fails to reserve memory then it + will fallback to existing kdump mechanism if 'crashkernel=' + option is set at kernel cmdline. Sysfs/debugfs files: ------------ diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 2a728d898fc5..6df19943dd4d 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -22,11 +22,11 @@ Coding style ************ The kernel has long had a standard coding style, described in -Documentation/process/coding-style.rst. For much of that time, the policies described -in that file were taken as being, at most, advisory. As a result, there is -a substantial amount of code in the kernel which does not meet the coding -style guidelines. The presence of that code leads to two independent -hazards for kernel developers. +:ref:`Documentation/process/coding-style.rst <codingstyle>`. For much of +that time, the policies described in that file were taken as being, at most, +advisory. As a result, there is a substantial amount of code in the kernel +which does not meet the coding style guidelines. The presence of that code +leads to two independent hazards for kernel developers. The first of these is to believe that the kernel coding standards do not matter and are not enforced. The truth of the matter is that adding new @@ -343,9 +343,10 @@ user-space developers to know what they are working with. See Documentation/ABI/README for a description of how this documentation should be formatted and what information needs to be provided. -The file Documentation/admin-guide/kernel-parameters.rst describes all of the kernel's -boot-time parameters. Any patch which adds new parameters should add the -appropriate entries to this file. +The file :ref:`Documentation/admin-guide/kernel-parameters.rst +<kernelparameters>` describes all of the kernel's boot-time parameters. +Any patch which adds new parameters should add the appropriate entries to +this file. Any new configuration options must be accompanied by help text which clearly explains the options and when the user might want to select them. diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index 87825cf96f33..a0d058cc6d25 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -250,17 +250,11 @@ specific homes. The 4.x.y (-stable) and 4.x patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ + https://www.kernel.org/pub/linux/kernel/v4.x/ The -rc patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ - -In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a -country code. This way you'll be downloading from a mirror site that's most -likely geographically closer to you, resulting in faster downloads for you, -less bandwidth used globally and less load on the main kernel.org servers -- -these are good things, so do use mirrors when possible. + https://www.kernel.org/pub/linux/kernel/v4.x/testing/ The 4.x kernels @@ -317,7 +311,7 @@ the current stable kernel. The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ + https://www.kernel.org/pub/linux/kernel/v4.x/incr/ These patches are not incremental, meaning that for example the 4.7.3 patch does not apply on top of the 4.7.2 kernel source, but rather on top diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 56ce66114665..e25d63f8c0da 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -30,7 +30,7 @@ you probably needn't concern yourself with isdn4k-utils. Program Minimal version Command to check the version ====================== =============== ======================================== GNU C 3.2 gcc --version -GNU make 3.80 make --version +GNU make 3.81 make --version binutils 2.12 ld -v util-linux 2.10o fdformat --version module-init-tools 0.9.10 depmod -V @@ -70,7 +70,7 @@ computer. Make ---- -You will need GNU make 3.80 or later to build the kernel. +You will need GNU make 3.81 or later to build the kernel. Binutils -------- @@ -318,9 +318,10 @@ PDF outputs, it is recommended to use version 1.4.6. .. note:: Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` - version 3.14159265. Depending on the distribution, you may also need - to install a series of ``texlive`` packages that provide the minimal - set of functionalities required for ``XeLaTex`` to work. + version 3.14159265. Depending on the distribution, you may also need to + install a series of ``texlive`` packages that provide the minimal set of + functionalities required for ``XeLaTex`` to work. For PDF output you'll also + need ``convert(1)`` from ImageMagick (https://www.imagemagick.org). Other tools ----------- @@ -348,7 +349,7 @@ Make Binutils -------- -- <ftp://ftp.kernel.org/pub/linux/devel/binutils/> +- <https://www.kernel.org/pub/linux/devel/binutils/> OpenSSL ------- @@ -361,17 +362,17 @@ System utilities Util-linux ---------- -- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/> +- <https://www.kernel.org/pub/linux/utils/util-linux/> Ksymoops -------- -- <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/> +- <https://www.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/> Module-Init-Tools ----------------- -- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/> +- <https://www.kernel.org/pub/linux/utils/kernel/module-init-tools/> Mkinitrd -------- @@ -401,7 +402,7 @@ Xfsprogs Pcmciautils ----------- -- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/> +- <https://www.kernel.org/pub/linux/utils/kernel/pcmcia/> Quota-tools ----------- diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 10aa6920709a..82fc399fcd33 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -3,6 +3,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* +.. _process_index: Working with the kernel development community ============================================= diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 11ec2d93a5e0..61e9c78bd6d1 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -124,7 +124,7 @@ specified in the following format in the sign-off area: .. code-block:: none - Cc: <stable@vger.kernel.org> # 3.3.x- + Cc: <stable@vger.kernel.org> # 3.3.x The tag has the meaning of: diff --git a/Documentation/s390/00-INDEX b/Documentation/s390/00-INDEX index 9189535f6cd2..317f0378ae01 100644 --- a/Documentation/s390/00-INDEX +++ b/Documentation/s390/00-INDEX @@ -22,5 +22,7 @@ qeth.txt - HiperSockets Bridge Port Support. s390dbf.txt - information on using the s390 debug feature. +vfio-ccw.txt + information on the vfio-ccw I/O subchannel driver. zfcpdump.txt - information on the s390 SCSI dump tool. diff --git a/Documentation/s390/vfio-ccw.txt b/Documentation/s390/vfio-ccw.txt new file mode 100644 index 000000000000..90b3dfead81b --- /dev/null +++ b/Documentation/s390/vfio-ccw.txt @@ -0,0 +1,303 @@ +vfio-ccw: the basic infrastructure +================================== + +Introduction +------------ + +Here we describe the vfio support for I/O subchannel devices for +Linux/s390. Motivation for vfio-ccw is to passthrough subchannels to a +virtual machine, while vfio is the means. + +Different than other hardware architectures, s390 has defined a unified +I/O access method, which is so called Channel I/O. It has its own access +patterns: +- Channel programs run asynchronously on a separate (co)processor. +- The channel subsystem will access any memory designated by the caller + in the channel program directly, i.e. there is no iommu involved. +Thus when we introduce vfio support for these devices, we realize it +with a mediated device (mdev) implementation. The vfio mdev will be +added to an iommu group, so as to make itself able to be managed by the +vfio framework. And we add read/write callbacks for special vfio I/O +regions to pass the channel programs from the mdev to its parent device +(the real I/O subchannel device) to do further address translation and +to perform I/O instructions. + +This document does not intend to explain the s390 I/O architecture in +every detail. More information/reference could be found here: +- A good start to know Channel I/O in general: + https://en.wikipedia.org/wiki/Channel_I/O +- s390 architecture: + s390 Principles of Operation manual (IBM Form. No. SA22-7832) +- The existing Qemu code which implements a simple emulated channel + subsystem could also be a good reference. It makes it easier to follow + the flow. + qemu/hw/s390x/css.c + +For vfio mediated device framework: +- Documentation/vfio-mediated-device.txt + +Motivation of vfio-ccw +---------------------- + +Currently, a guest virtualized via qemu/kvm on s390 only sees +paravirtualized virtio devices via the "Virtio Over Channel I/O +(virtio-ccw)" transport. This makes virtio devices discoverable via +standard operating system algorithms for handling channel devices. + +However this is not enough. On s390 for the majority of devices, which +use the standard Channel I/O based mechanism, we also need to provide +the functionality of passing through them to a Qemu virtual machine. +This includes devices that don't have a virtio counterpart (e.g. tape +drives) or that have specific characteristics which guests want to +exploit. + +For passing a device to a guest, we want to use the same interface as +everybody else, namely vfio. Thus, we would like to introduce vfio +support for channel devices. And we would like to name this new vfio +device "vfio-ccw". + +Access patterns of CCW devices +------------------------------ + +s390 architecture has implemented a so called channel subsystem, that +provides a unified view of the devices physically attached to the +systems. Though the s390 hardware platform knows about a huge variety of +different peripheral attachments like disk devices (aka. DASDs), tapes, +communication controllers, etc. They can all be accessed by a well +defined access method and they are presenting I/O completion a unified +way: I/O interruptions. + +All I/O requires the use of channel command words (CCWs). A CCW is an +instruction to a specialized I/O channel processor. A channel program is +a sequence of CCWs which are executed by the I/O channel subsystem. To +issue a channel program to the channel subsystem, it is required to +build an operation request block (ORB), which can be used to point out +the format of the CCW and other control information to the system. The +operating system signals the I/O channel subsystem to begin executing +the channel program with a SSCH (start sub-channel) instruction. The +central processor is then free to proceed with non-I/O instructions +until interrupted. The I/O completion result is received by the +interrupt handler in the form of interrupt response block (IRB). + +Back to vfio-ccw, in short: +- ORBs and channel programs are built in guest kernel (with guest + physical addresses). +- ORBs and channel programs are passed to the host kernel. +- Host kernel translates the guest physical addresses to real addresses + and starts the I/O with issuing a privileged Channel I/O instruction + (e.g SSCH). +- channel programs run asynchronously on a separate processor. +- I/O completion will be signaled to the host with I/O interruptions. + And it will be copied as IRB to user space to pass it back to the + guest. + +Physical vfio ccw device and its child mdev +------------------------------------------- + +As mentioned above, we realize vfio-ccw with a mdev implementation. + +Channel I/O does not have IOMMU hardware support, so the physical +vfio-ccw device does not have an IOMMU level translation or isolation. + +Sub-channel I/O instructions are all privileged instructions, When +handling the I/O instruction interception, vfio-ccw has the software +policing and translation how the channel program is programmed before +it gets sent to hardware. + +Within this implementation, we have two drivers for two types of +devices: +- The vfio_ccw driver for the physical subchannel device. + This is an I/O subchannel driver for the real subchannel device. It + realizes a group of callbacks and registers to the mdev framework as a + parent (physical) device. As a consequence, mdev provides vfio_ccw a + generic interface (sysfs) to create mdev devices. A vfio mdev could be + created by vfio_ccw then and added to the mediated bus. It is the vfio + device that added to an IOMMU group and a vfio group. + vfio_ccw also provides an I/O region to accept channel program + request from user space and store I/O interrupt result for user + space to retrieve. To notify user space an I/O completion, it offers + an interface to setup an eventfd fd for asynchronous signaling. + +- The vfio_mdev driver for the mediated vfio ccw device. + This is provided by the mdev framework. It is a vfio device driver for + the mdev that created by vfio_ccw. + It realize a group of vfio device driver callbacks, adds itself to a + vfio group, and registers itself to the mdev framework as a mdev + driver. + It uses a vfio iommu backend that uses the existing map and unmap + ioctls, but rather than programming them into an IOMMU for a device, + it simply stores the translations for use by later requests. This + means that a device programmed in a VM with guest physical addresses + can have the vfio kernel convert that address to process virtual + address, pin the page and program the hardware with the host physical + address in one step. + For a mdev, the vfio iommu backend will not pin the pages during the + VFIO_IOMMU_MAP_DMA ioctl. Mdev framework will only maintain a database + of the iova<->vaddr mappings in this operation. And they export a + vfio_pin_pages and a vfio_unpin_pages interfaces from the vfio iommu + backend for the physical devices to pin and unpin pages by demand. + +Below is a high Level block diagram. + + +-------------+ + | | + | +---------+ | mdev_register_driver() +--------------+ + | | Mdev | +<-----------------------+ | + | | bus | | | vfio_mdev.ko | + | | driver | +----------------------->+ |<-> VFIO user + | +---------+ | probe()/remove() +--------------+ APIs + | | + | MDEV CORE | + | MODULE | + | mdev.ko | + | +---------+ | mdev_register_device() +--------------+ + | |Physical | +<-----------------------+ | + | | device | | | vfio_ccw.ko |<-> subchannel + | |interface| +----------------------->+ | device + | +---------+ | callback +--------------+ + +-------------+ + +The process of how these work together. +1. vfio_ccw.ko drives the physical I/O subchannel, and registers the + physical device (with callbacks) to mdev framework. + When vfio_ccw probing the subchannel device, it registers device + pointer and callbacks to the mdev framework. Mdev related file nodes + under the device node in sysfs would be created for the subchannel + device, namely 'mdev_create', 'mdev_destroy' and + 'mdev_supported_types'. +2. Create a mediated vfio ccw device. + Use the 'mdev_create' sysfs file, we need to manually create one (and + only one for our case) mediated device. +3. vfio_mdev.ko drives the mediated ccw device. + vfio_mdev is also the vfio device drvier. It will probe the mdev and + add it to an iommu_group and a vfio_group. Then we could pass through + the mdev to a guest. + +vfio-ccw I/O region +------------------- + +An I/O region is used to accept channel program request from user +space and store I/O interrupt result for user space to retrieve. The +defination of the region is: + +struct ccw_io_region { +#define ORB_AREA_SIZE 12 + __u8 orb_area[ORB_AREA_SIZE]; +#define SCSW_AREA_SIZE 12 + __u8 scsw_area[SCSW_AREA_SIZE]; +#define IRB_AREA_SIZE 96 + __u8 irb_area[IRB_AREA_SIZE]; + __u32 ret_code; +} __packed; + +While starting an I/O request, orb_area should be filled with the +guest ORB, and scsw_area should be filled with the SCSW of the Virtual +Subchannel. + +irb_area stores the I/O result. + +ret_code stores a return code for each access of the region. + +vfio-ccw patches overview +------------------------- + +For now, our patches are rebased on the latest mdev implementation. +vfio-ccw follows what vfio-pci did on the s390 paltform and uses +vfio-iommu-type1 as the vfio iommu backend. It's a good start to launch +the code review for vfio-ccw. Note that the implementation is far from +complete yet; but we'd like to get feedback for the general +architecture. + +* CCW translation APIs +- Description: + These introduce a group of APIs (start with 'cp_') to do CCW + translation. The CCWs passed in by a user space program are + organized with their guest physical memory addresses. These APIs + will copy the CCWs into the kernel space, and assemble a runnable + kernel channel program by updating the guest physical addresses with + their corresponding host physical addresses. +- Patches: + vfio: ccw: introduce channel program interfaces + +* vfio_ccw device driver +- Description: + The following patches utilizes the CCW translation APIs and introduce + vfio_ccw, which is the driver for the I/O subchannel devices you want + to pass through. + vfio_ccw implements the following vfio ioctls: + VFIO_DEVICE_GET_INFO + VFIO_DEVICE_GET_IRQ_INFO + VFIO_DEVICE_GET_REGION_INFO + VFIO_DEVICE_RESET + VFIO_DEVICE_SET_IRQS + This provides an I/O region, so that the user space program can pass a + channel program to the kernel, to do further CCW translation before + issuing them to a real device. + This also provides the SET_IRQ ioctl to setup an event notifier to + notify the user space program the I/O completion in an asynchronous + way. +- Patches: + vfio: ccw: basic implementation for vfio_ccw driver + vfio: ccw: introduce ccw_io_region + vfio: ccw: realize VFIO_DEVICE_GET_REGION_INFO ioctl + vfio: ccw: realize VFIO_DEVICE_RESET ioctl + vfio: ccw: realize VFIO_DEVICE_G(S)ET_IRQ_INFO ioctls + +The user of vfio-ccw is not limited to Qemu, while Qemu is definitely a +good example to get understand how these patches work. Here is a little +bit more detail how an I/O request triggered by the Qemu guest will be +handled (without error handling). + +Explanation: +Q1-Q7: Qemu side process. +K1-K5: Kernel side process. + +Q1. Get I/O region info during initialization. +Q2. Setup event notifier and handler to handle I/O completion. + +... ... + +Q3. Intercept a ssch instruction. +Q4. Write the guest channel program and ORB to the I/O region. + K1. Copy from guest to kernel. + K2. Translate the guest channel program to a host kernel space + channel program, which becomes runnable for a real device. + K3. With the necessary information contained in the orb passed in + by Qemu, issue the ccwchain to the device. + K4. Return the ssch CC code. +Q5. Return the CC code to the guest. + +... ... + + K5. Interrupt handler gets the I/O result and write the result to + the I/O region. + K6. Signal Qemu to retrieve the result. +Q6. Get the signal and event handler reads out the result from the I/O + region. +Q7. Update the irb for the guest. + +Limitations +----------- + +The current vfio-ccw implementation focuses on supporting basic commands +needed to implement block device functionality (read/write) of DASD/ECKD +device only. Some commands may need special handling in the future, for +example, anything related to path grouping. + +DASD is a kind of storage device. While ECKD is a data recording format. +More information for DASD and ECKD could be found here: +https://en.wikipedia.org/wiki/Direct-access_storage_device +https://en.wikipedia.org/wiki/Count_key_data + +Together with the corresponding work in Qemu, we can bring the passed +through DASD/ECKD device online in a guest now and use it as a block +device. + +Reference +--------- +1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832) +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.txt +5. Documentation/vfio.txt +6. Documentation/vfio-mediated-device.txt diff --git a/Documentation/scheduler/sched-pelt.c b/Documentation/scheduler/sched-pelt.c new file mode 100644 index 000000000000..e4219139386a --- /dev/null +++ b/Documentation/scheduler/sched-pelt.c @@ -0,0 +1,108 @@ +/* + * The following program is used to generate the constants for + * computing sched averages. + * + * ============================================================== + * C program (compile with -lm) + * ============================================================== + */ + +#include <math.h> +#include <stdio.h> + +#define HALFLIFE 32 +#define SHIFT 32 + +double y; + +void calc_runnable_avg_yN_inv(void) +{ + int i; + unsigned int x; + + printf("static const u32 runnable_avg_yN_inv[] = {"); + for (i = 0; i < HALFLIFE; i++) { + x = ((1UL<<32)-1)*pow(y, i); + + if (i % 6 == 0) printf("\n\t"); + printf("0x%8x, ", x); + } + printf("\n};\n\n"); +} + +int sum = 1024; + +void calc_runnable_avg_yN_sum(void) +{ + int i; + + printf("static const u32 runnable_avg_yN_sum[] = {\n\t 0,"); + for (i = 1; i <= HALFLIFE; i++) { + if (i == 1) + sum *= y; + else + sum = sum*y + 1024*y; + + if (i % 11 == 0) + printf("\n\t"); + + printf("%5d,", sum); + } + printf("\n};\n\n"); +} + +int n = -1; +/* first period */ +long max = 1024; + +void calc_converged_max(void) +{ + long last = 0, y_inv = ((1UL<<32)-1)*y; + + for (; ; n++) { + if (n > -1) + max = ((max*y_inv)>>SHIFT) + 1024; + /* + * This is the same as: + * max = max*y + 1024; + */ + + if (last == max) + break; + + last = max; + } + n--; + printf("#define LOAD_AVG_PERIOD %d\n", HALFLIFE); + printf("#define LOAD_AVG_MAX %ld\n", max); +// printf("#define LOAD_AVG_MAX_N %d\n\n", n); +} + +void calc_accumulated_sum_32(void) +{ + int i, x = sum; + + printf("static const u32 __accumulated_sum_N32[] = {\n\t 0,"); + for (i = 1; i <= n/HALFLIFE+1; i++) { + if (i > 1) + x = x/2 + sum; + + if (i % 6 == 0) + printf("\n\t"); + + printf("%6d,", x); + } + printf("\n};\n\n"); +} + +void main(void) +{ + printf("/* Generated by Documentation/scheduler/sched-pelt; do not modify. */\n\n"); + + y = pow(0.5, 1/(double)HALFLIFE); + + calc_runnable_avg_yN_inv(); +// calc_runnable_avg_yN_sum(); + calc_converged_max(); +// calc_accumulated_sum_32(); +} diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.txt index 37eca00796ee..11e447bdb3a5 100644 --- a/Documentation/scsi/scsi_eh.txt +++ b/Documentation/scsi/scsi_eh.txt @@ -70,7 +70,7 @@ with the command. scmd is requeued to blk queue. - otherwise - scsi_eh_scmd_add(scmd, 0) is invoked for the command. See + scsi_eh_scmd_add(scmd) is invoked for the command. See [1-3] for details of this function. @@ -103,13 +103,14 @@ function eh_timed_out() callback did not handle the command. Step #2 is taken. - 2. If the host supports asynchronous completion (as indicated by the - no_async_abort setting in the host template) scsi_abort_command() - is invoked to schedule an asynchrous abort. If that fails - Step #3 is taken. + 2. scsi_abort_command() is invoked to schedule an asynchrous abort. + Asynchronous abort are not invoked for commands which the + SCSI_EH_ABORT_SCHEDULED flag is set (this indicates that the command + already had been aborted once, and this is a retry which failed), + or when the EH deadline is expired. In these case Step #3 is taken. - 2. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the - command. See [1-3] for more information. + 3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the + command. See [1-4] for more information. [1-3] Asynchronous command aborts @@ -124,16 +125,13 @@ function scmds enter EH via scsi_eh_scmd_add(), which does the following. - 1. Turns on scmd->eh_eflags as requested. It's 0 for error - completions and SCSI_EH_CANCEL_CMD for timeouts. + 1. Links scmd->eh_entry to shost->eh_cmd_q - 2. Links scmd->eh_entry to shost->eh_cmd_q + 2. Sets SHOST_RECOVERY bit in shost->shost_state - 3. Sets SHOST_RECOVERY bit in shost->shost_state + 3. Increments shost->host_failed - 4. Increments shost->host_failed - - 5. Wakes up SCSI EH thread if shost->host_busy == shost->host_failed + 4. Wakes up SCSI EH thread if shost->host_busy == shost->host_failed As can be seen above, once any scmd is added to shost->eh_cmd_q, SHOST_RECOVERY shost_state bit is turned on. This prevents any new @@ -249,7 +247,6 @@ scmd->allowed. 1. Error completion / time out ACTION: scsi_eh_scmd_add() is invoked for scmd - - set scmd->eh_eflags - add scmd to shost->eh_cmd_q - set SHOST_RECOVERY - shost->host_failed++ @@ -263,7 +260,6 @@ scmd->allowed. 3. scmd recovered ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd - - clear scmd->eh_eflags - scsi_setup_cmd_retry() - move from local eh_work_q to local eh_done_q LOCKING: none @@ -456,8 +452,6 @@ except for #1 must be implemented by eh_strategy_handler(). - shost->host_failed is zero. - - Each scmd's eh_eflags field is cleared. - - Each scmd is in such a state that scsi_setup_cmd_retry() on the scmd doesn't make any difference. diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt index 0e03baf271bd..cd5019934d7f 100644 --- a/Documentation/security/keys.txt +++ b/Documentation/security/keys.txt @@ -827,7 +827,7 @@ The keyctl syscall functions are: long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params, char *buffer, size_t buflen, - void *reserved); + struct keyctl_kdf_params *kdf); The params struct contains serial numbers for three keys: @@ -844,18 +844,61 @@ The keyctl syscall functions are: public key. If the base is the remote public key, the result is the shared secret. - The reserved argument must be set to NULL. + If the parameter kdf is NULL, the following applies: - The buffer length must be at least the length of the prime, or zero. + - The buffer length must be at least the length of the prime, or zero. - If the buffer length is nonzero, the length of the result is - returned when it is successfully calculated and copied in to the - buffer. When the buffer length is zero, the minimum required - buffer length is returned. + - If the buffer length is nonzero, the length of the result is + returned when it is successfully calculated and copied in to the + buffer. When the buffer length is zero, the minimum required + buffer length is returned. + + The kdf parameter allows the caller to apply a key derivation function + (KDF) on the Diffie-Hellman computation where only the result + of the KDF is returned to the caller. The KDF is characterized with + struct keyctl_kdf_params as follows: + + - char *hashname specifies the NUL terminated string identifying + the hash used from the kernel crypto API and applied for the KDF + operation. The KDF implemenation complies with SP800-56A as well + as with SP800-108 (the counter KDF). + + - char *otherinfo specifies the OtherInfo data as documented in + SP800-56A section 5.8.1.2. The length of the buffer is given with + otherinfolen. The format of OtherInfo is defined by the caller. + The otherinfo pointer may be NULL if no OtherInfo shall be used. This function will return error EOPNOTSUPP if the key type is not supported, error ENOKEY if the key could not be found, or error - EACCES if the key is not readable by the caller. + EACCES if the key is not readable by the caller. In addition, the + function will return EMSGSIZE when the parameter kdf is non-NULL + and either the buffer length or the OtherInfo length exceeds the + allowed length. + + (*) Restrict keyring linkage + + long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring, + const char *type, const char *restriction); + + An existing keyring can restrict linkage of additional keys by evaluating + the contents of the key according to a restriction scheme. + + "keyring" is the key ID for an existing keyring to apply a restriction + to. It may be empty or may already have keys linked. Existing linked keys + will remain in the keyring even if the new restriction would reject them. + + "type" is a registered key type. + + "restriction" is a string describing how key linkage is to be restricted. + The format varies depending on the key type, and the string is passed to + the lookup_restriction() function for the requested type. It may specify + a method and relevant data for the restriction such as signature + verification or constraints on key payload. If the requested key type is + later unregistered, no keys may be added to the keyring after the key type + is removed. + + To apply a keyring restriction the process must have Set Attribute + permission and the keyring must not be previously restricted. =============== KERNEL SERVICES @@ -1032,10 +1075,7 @@ payload contents" for more information. struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid, const struct cred *cred, key_perm_t perm, - int (*restrict_link)(struct key *, - const struct key_type *, - unsigned long, - const union key_payload *), + struct key_restriction *restrict_link, unsigned long flags, struct key *dest); @@ -1047,20 +1087,23 @@ payload contents" for more information. KEY_ALLOC_NOT_IN_QUOTA in flags if the keyring shouldn't be accounted towards the user's quota). Error ENOMEM can also be returned. - If restrict_link not NULL, it should point to a function that will be - called each time an attempt is made to link a key into the new keyring. - This function is called to check whether a key may be added into the keying - or not. Callers of key_create_or_update() within the kernel can pass - KEY_ALLOC_BYPASS_RESTRICTION to suppress the check. An example of using - this is to manage rings of cryptographic keys that are set up when the - kernel boots where userspace is also permitted to add keys - provided they - can be verified by a key the kernel already has. + If restrict_link is not NULL, it should point to a structure that contains + the function that will be called each time an attempt is made to link a + key into the new keyring. The structure may also contain a key pointer + and an associated key type. The function is called to check whether a key + may be added into the keyring or not. The key type is used by the garbage + collector to clean up function or data pointers in this structure if the + given key type is unregistered. Callers of key_create_or_update() within + the kernel can pass KEY_ALLOC_BYPASS_RESTRICTION to suppress the check. + An example of using this is to manage rings of cryptographic keys that are + set up when the kernel boots where userspace is also permitted to add keys + - provided they can be verified by a key the kernel already has. When called, the restriction function will be passed the keyring being - added to, the key flags value and the type and payload of the key being - added. Note that when a new key is being created, this is called between - payload preparsing and actual key creation. The function should return 0 - to allow the link or an error to reject it. + added to, the key type, the payload of the key being added, and data to be + used in the restriction check. Note that when a new key is being created, + this is called between payload preparsing and actual key creation. The + function should return 0 to allow the link or an error to reject it. A convenience function, restrict_link_reject, exists to always return -EPERM to in this case. @@ -1445,6 +1488,15 @@ The structure has a number of fields, some of which are mandatory: The authorisation key. + (*) struct key_restriction *(*lookup_restriction)(const char *params); + + This optional method is used to enable userspace configuration of keyring + restrictions. The restriction parameter string (not including the key type + name) is passed in, and this method returns a pointer to a key_restriction + structure containing the relevant functions and data to evaluate each + attempted key link operation. If there is no match, -EINVAL is returned. + + ============================ REQUEST-KEY CALLBACK SERVICE ============================ diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index 9eeb9b468706..f59c3cdbfaf4 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -494,6 +494,8 @@ add_hp_mic (bool) hp_mic_detect (bool) enable/disable the hp/mic shared input for a single built-in mic case; default true +vmaster (bool) + enable/disable the virtual Master control; default true mixer_nid (int) specifies the widget NID of the analog-loopback mixer diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index df0419c62096..cf13ff3a656c 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -44,7 +44,7 @@ from sphinx.domains.c import CDomain as Base_CDomain __version__ = '1.0' # Get Sphinx version -major, minor, patch = map(int, sphinx.__version__.split(".")) +major, minor, patch = sphinx.version_info[:3] def setup(app): diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py new file mode 100644 index 000000000000..cef4ad19624c --- /dev/null +++ b/Documentation/sphinx/kfigure.py @@ -0,0 +1,551 @@ +# -*- coding: utf-8; mode: python -*- +# pylint: disable=C0103, R0903, R0912, R0915 +u""" + scalable figure and image handling + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Sphinx extension which implements scalable image handling. + + :copyright: Copyright (C) 2016 Markus Heiser + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The build for image formats depend on image's source format and output's + destination format. This extension implement methods to simplify image + handling from the author's POV. Directives like ``kernel-figure`` implement + methods *to* always get the best output-format even if some tools are not + installed. For more details take a look at ``convert_image(...)`` which is + the core of all conversions. + + * ``.. kernel-image``: for image handling / a ``.. image::`` replacement + + * ``.. kernel-figure``: for figure handling / a ``.. figure::`` replacement + + * ``.. kernel-render``: for render markup / a concept to embed *render* + markups (or languages). Supported markups (see ``RENDER_MARKUP_EXT``) + + - ``DOT``: render embedded Graphviz's **DOC** + - ``SVG``: render embedded Scalable Vector Graphics (**SVG**) + - ... *developable* + + Used tools: + + * ``dot(1)``: Graphviz (http://www.graphviz.org). If Graphviz is not + available, the DOT language is inserted as literal-block. + + * SVG to PDF: To generate PDF, you need at least one of this tools: + + - ``convert(1)``: ImageMagick (https://www.imagemagick.org) + + List of customizations: + + * generate PDF from SVG / used by PDF (LaTeX) builder + + * generate SVG (html-builder) and PDF (latex-builder) from DOT files. + DOT: see http://www.graphviz.org/content/dot-language + + """ + +import os +from os import path +import subprocess +from hashlib import sha1 +import sys + +from docutils import nodes +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives +from docutils.parsers.rst.directives import images +import sphinx + +from sphinx.util.nodes import clean_astext +from six import iteritems + +PY3 = sys.version_info[0] == 3 + +if PY3: + _unicode = str +else: + _unicode = unicode + +# Get Sphinx version +major, minor, patch = sphinx.version_info[:3] +if major == 1 and minor > 3: + # patches.Figure only landed in Sphinx 1.4 + from sphinx.directives.patches import Figure # pylint: disable=C0413 +else: + Figure = images.Figure + +__version__ = '1.0.0' + +# simple helper +# ------------- + +def which(cmd): + """Searches the ``cmd`` in the ``PATH`` enviroment. + + This *which* searches the PATH for executable ``cmd`` . First match is + returned, if nothing is found, ``None` is returned. + """ + envpath = os.environ.get('PATH', None) or os.defpath + for folder in envpath.split(os.pathsep): + fname = folder + os.sep + cmd + if path.isfile(fname): + return fname + +def mkdir(folder, mode=0o775): + if not path.isdir(folder): + os.makedirs(folder, mode) + +def file2literal(fname): + with open(fname, "r") as src: + data = src.read() + node = nodes.literal_block(data, data) + return node + +def isNewer(path1, path2): + """Returns True if ``path1`` is newer than ``path2`` + + If ``path1`` exists and is newer than ``path2`` the function returns + ``True`` is returned otherwise ``False`` + """ + return (path.exists(path1) + and os.stat(path1).st_ctime > os.stat(path2).st_ctime) + +def pass_handle(self, node): # pylint: disable=W0613 + pass + +# setup conversion tools and sphinx extension +# ------------------------------------------- + +# Graphviz's dot(1) support +dot_cmd = None + +# ImageMagick' convert(1) support +convert_cmd = None + + +def setup(app): + # check toolchain first + app.connect('builder-inited', setupTools) + + # image handling + app.add_directive("kernel-image", KernelImage) + app.add_node(kernel_image, + html = (visit_kernel_image, pass_handle), + latex = (visit_kernel_image, pass_handle), + texinfo = (visit_kernel_image, pass_handle), + text = (visit_kernel_image, pass_handle), + man = (visit_kernel_image, pass_handle), ) + + # figure handling + app.add_directive("kernel-figure", KernelFigure) + app.add_node(kernel_figure, + html = (visit_kernel_figure, pass_handle), + latex = (visit_kernel_figure, pass_handle), + texinfo = (visit_kernel_figure, pass_handle), + text = (visit_kernel_figure, pass_handle), + man = (visit_kernel_figure, pass_handle), ) + + # render handling + app.add_directive('kernel-render', KernelRender) + app.add_node(kernel_render, + html = (visit_kernel_render, pass_handle), + latex = (visit_kernel_render, pass_handle), + texinfo = (visit_kernel_render, pass_handle), + text = (visit_kernel_render, pass_handle), + man = (visit_kernel_render, pass_handle), ) + + app.connect('doctree-read', add_kernel_figure_to_std_domain) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + + +def setupTools(app): + u""" + Check available build tools and log some *verbose* messages. + + This function is called once, when the builder is initiated. + """ + global dot_cmd, convert_cmd # pylint: disable=W0603 + app.verbose("kfigure: check installed tools ...") + + dot_cmd = which('dot') + convert_cmd = which('convert') + + if dot_cmd: + app.verbose("use dot(1) from: " + dot_cmd) + else: + app.warn("dot(1) not found, for better output quality install " + "graphviz from http://www.graphviz.org") + if convert_cmd: + app.verbose("use convert(1) from: " + convert_cmd) + else: + app.warn( + "convert(1) not found, for SVG to PDF conversion install " + "ImageMagick (https://www.imagemagick.org)") + + +# integrate conversion tools +# -------------------------- + +RENDER_MARKUP_EXT = { + # The '.ext' must be handled by convert_image(..) function's *in_ext* input. + # <name> : <.ext> + 'DOT' : '.dot', + 'SVG' : '.svg' +} + +def convert_image(img_node, translator, src_fname=None): + """Convert a image node for the builder. + + Different builder prefer different image formats, e.g. *latex* builder + prefer PDF while *html* builder prefer SVG format for images. + + This function handles output image formats in dependence of source the + format (of the image) and the translator's output format. + """ + app = translator.builder.app + + fname, in_ext = path.splitext(path.basename(img_node['uri'])) + if src_fname is None: + src_fname = path.join(translator.builder.srcdir, img_node['uri']) + if not path.exists(src_fname): + src_fname = path.join(translator.builder.outdir, img_node['uri']) + + dst_fname = None + + # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages + + app.verbose('assert best format for: ' + img_node['uri']) + + if in_ext == '.dot': + + if not dot_cmd: + app.verbose("dot from graphviz not available / include DOT raw.") + img_node.replace_self(file2literal(src_fname)) + + elif translator.builder.format == 'latex': + dst_fname = path.join(translator.builder.outdir, fname + '.pdf') + img_node['uri'] = fname + '.pdf' + img_node['candidates'] = {'*': fname + '.pdf'} + + + elif translator.builder.format == 'html': + dst_fname = path.join( + translator.builder.outdir, + translator.builder.imagedir, + fname + '.svg') + img_node['uri'] = path.join( + translator.builder.imgpath, fname + '.svg') + img_node['candidates'] = { + '*': path.join(translator.builder.imgpath, fname + '.svg')} + + else: + # all other builder formats will include DOT as raw + img_node.replace_self(file2literal(src_fname)) + + elif in_ext == '.svg': + + if translator.builder.format == 'latex': + if convert_cmd is None: + app.verbose("no SVG to PDF conversion available / include SVG raw.") + img_node.replace_self(file2literal(src_fname)) + else: + dst_fname = path.join(translator.builder.outdir, fname + '.pdf') + img_node['uri'] = fname + '.pdf' + img_node['candidates'] = {'*': fname + '.pdf'} + + if dst_fname: + # the builder needs not to copy one more time, so pop it if exists. + translator.builder.images.pop(img_node['uri'], None) + _name = dst_fname[len(translator.builder.outdir) + 1:] + + if isNewer(dst_fname, src_fname): + app.verbose("convert: {out}/%s already exists and is newer" % _name) + + else: + ok = False + mkdir(path.dirname(dst_fname)) + + if in_ext == '.dot': + app.verbose('convert DOT to: {out}/' + _name) + ok = dot2format(app, src_fname, dst_fname) + + elif in_ext == '.svg': + app.verbose('convert SVG to: {out}/' + _name) + ok = svg2pdf(app, src_fname, dst_fname) + + if not ok: + img_node.replace_self(file2literal(src_fname)) + + +def dot2format(app, dot_fname, out_fname): + """Converts DOT file to ``out_fname`` using ``dot(1)``. + + * ``dot_fname`` pathname of the input DOT file, including extension ``.dot`` + * ``out_fname`` pathname of the output file, including format extension + + The *format extension* depends on the ``dot`` command (see ``man dot`` + option ``-Txxx``). Normally you will use one of the following extensions: + + - ``.ps`` for PostScript, + - ``.svg`` or ``svgz`` for Structured Vector Graphics, + - ``.fig`` for XFIG graphics and + - ``.png`` or ``gif`` for common bitmap graphics. + + """ + out_format = path.splitext(out_fname)[1][1:] + cmd = [dot_cmd, '-T%s' % out_format, dot_fname] + exit_code = 42 + + with open(out_fname, "w") as out: + exit_code = subprocess.call(cmd, stdout = out) + if exit_code != 0: + app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + return bool(exit_code == 0) + +def svg2pdf(app, svg_fname, pdf_fname): + """Converts SVG to PDF with ``convert(1)`` command. + + Uses ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for + conversion. Returns ``True`` on success and ``False`` if an error occurred. + + * ``svg_fname`` pathname of the input SVG file with extension (``.svg``) + * ``pdf_name`` pathname of the output PDF file with extension (``.pdf``) + + """ + cmd = [convert_cmd, svg_fname, pdf_fname] + # use stdout and stderr from parent + exit_code = subprocess.call(cmd) + if exit_code != 0: + app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd))) + return bool(exit_code == 0) + + +# image handling +# --------------------- + +def visit_kernel_image(self, node): # pylint: disable=W0613 + """Visitor of the ``kernel_image`` Node. + + Handles the ``image`` child-node with the ``convert_image(...)``. + """ + img_node = node[0] + convert_image(img_node, self) + +class kernel_image(nodes.image): + """Node for ``kernel-image`` directive.""" + pass + +class KernelImage(images.Image): + u"""KernelImage directive + + Earns everything from ``.. image::`` directive, except *remote URI* and + *glob* pattern. The KernelImage wraps a image node into a + kernel_image node. See ``visit_kernel_image``. + """ + + def run(self): + uri = self.arguments[0] + if uri.endswith('.*') or uri.find('://') != -1: + raise self.severe( + 'Error in "%s: %s": glob pattern and remote images are not allowed' + % (self.name, uri)) + result = images.Image.run(self) + if len(result) == 2 or isinstance(result[0], nodes.system_message): + return result + (image_node,) = result + # wrap image node into a kernel_image node / see visitors + node = kernel_image('', image_node) + return [node] + +# figure handling +# --------------------- + +def visit_kernel_figure(self, node): # pylint: disable=W0613 + """Visitor of the ``kernel_figure`` Node. + + Handles the ``image`` child-node with the ``convert_image(...)``. + """ + img_node = node[0][0] + convert_image(img_node, self) + +class kernel_figure(nodes.figure): + """Node for ``kernel-figure`` directive.""" + +class KernelFigure(Figure): + u"""KernelImage directive + + Earns everything from ``.. figure::`` directive, except *remote URI* and + *glob* pattern. The KernelFigure wraps a figure node into a kernel_figure + node. See ``visit_kernel_figure``. + """ + + def run(self): + uri = self.arguments[0] + if uri.endswith('.*') or uri.find('://') != -1: + raise self.severe( + 'Error in "%s: %s":' + ' glob pattern and remote images are not allowed' + % (self.name, uri)) + result = Figure.run(self) + if len(result) == 2 or isinstance(result[0], nodes.system_message): + return result + (figure_node,) = result + # wrap figure node into a kernel_figure node / see visitors + node = kernel_figure('', figure_node) + return [node] + + +# render handling +# --------------------- + +def visit_kernel_render(self, node): + """Visitor of the ``kernel_render`` Node. + + If rendering tools available, save the markup of the ``literal_block`` child + node into a file and replace the ``literal_block`` node with a new created + ``image`` node, pointing to the saved markup file. Afterwards, handle the + image child-node with the ``convert_image(...)``. + """ + app = self.builder.app + srclang = node.get('srclang') + + app.verbose('visit kernel-render node lang: "%s"' % (srclang)) + + tmp_ext = RENDER_MARKUP_EXT.get(srclang, None) + if tmp_ext is None: + app.warn('kernel-render: "%s" unknow / include raw.' % (srclang)) + return + + if not dot_cmd and tmp_ext == '.dot': + app.verbose("dot from graphviz not available / include raw.") + return + + literal_block = node[0] + + code = literal_block.astext() + hashobj = code.encode('utf-8') # str(node.attributes) + fname = path.join('%s-%s' % (srclang, sha1(hashobj).hexdigest())) + + tmp_fname = path.join( + self.builder.outdir, self.builder.imagedir, fname + tmp_ext) + + if not path.isfile(tmp_fname): + mkdir(path.dirname(tmp_fname)) + with open(tmp_fname, "w") as out: + out.write(code) + + img_node = nodes.image(node.rawsource, **node.attributes) + img_node['uri'] = path.join(self.builder.imgpath, fname + tmp_ext) + img_node['candidates'] = { + '*': path.join(self.builder.imgpath, fname + tmp_ext)} + + literal_block.replace_self(img_node) + convert_image(img_node, self, tmp_fname) + + +class kernel_render(nodes.General, nodes.Inline, nodes.Element): + """Node for ``kernel-render`` directive.""" + pass + +class KernelRender(Figure): + u"""KernelRender directive + + Render content by external tool. Has all the options known from the + *figure* directive, plus option ``caption``. If ``caption`` has a + value, a figure node with the *caption* is inserted. If not, a image node is + inserted. + + The KernelRender directive wraps the text of the directive into a + literal_block node and wraps it into a kernel_render node. See + ``visit_kernel_render``. + """ + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + + # earn options from 'figure' + option_spec = Figure.option_spec.copy() + option_spec['caption'] = directives.unchanged + + def run(self): + return [self.build_node()] + + def build_node(self): + + srclang = self.arguments[0].strip() + if srclang not in RENDER_MARKUP_EXT.keys(): + return [self.state_machine.reporter.warning( + 'Unknow source language "%s", use one of: %s.' % ( + srclang, ",".join(RENDER_MARKUP_EXT.keys())), + line=self.lineno)] + + code = '\n'.join(self.content) + if not code.strip(): + return [self.state_machine.reporter.warning( + 'Ignoring "%s" directive without content.' % ( + self.name), + line=self.lineno)] + + node = kernel_render() + node['alt'] = self.options.get('alt','') + node['srclang'] = srclang + literal_node = nodes.literal_block(code, code) + node += literal_node + + caption = self.options.get('caption') + if caption: + # parse caption's content + parsed = nodes.Element() + self.state.nested_parse( + ViewList([caption], source=''), self.content_offset, parsed) + caption_node = nodes.caption( + parsed[0].rawsource, '', *parsed[0].children) + caption_node.source = parsed[0].source + caption_node.line = parsed[0].line + + figure_node = nodes.figure('', node) + for k,v in self.options.items(): + figure_node[k] = v + figure_node += caption_node + + node = figure_node + + return node + +def add_kernel_figure_to_std_domain(app, doctree): + """Add kernel-figure anchors to 'std' domain. + + The ``StandardDomain.process_doc(..)`` method does not know how to resolve + the caption (label) of ``kernel-figure`` directive (it only knows about + standard nodes, e.g. table, figure etc.). Without any additional handling + this will result in a 'undefined label' for kernel-figures. + + This handle adds labels of kernel-figure to the 'std' domain labels. + """ + + std = app.env.domains["std"] + docname = app.env.docname + labels = std.data["labels"] + + for name, explicit in iteritems(doctree.nametypes): + if not explicit: + continue + labelid = doctree.nameids[name] + if labelid is None: + continue + node = doctree.ids[labelid] + + if node.tagname == 'kernel_figure': + for n in node.next_node(): + if n.tagname == 'caption': + sectname = clean_astext(n) + # add label to std domain + labels[name] = docname, labelid, sectname + break diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt index 909a73065e0a..6848f0a26fa5 100755 --- a/Documentation/sphinx/tmplcvt +++ b/Documentation/sphinx/tmplcvt @@ -7,13 +7,22 @@ # fix \_ # title line? # +set -eu + +if [ "$#" != "2" ]; then + echo "$0 <docbook file> <rst file>" + exit +fi + +DIR=$(dirname $0) in=$1 rst=$2 tmp=$rst.tmp cp $in $tmp -sed --in-place -f convert_template.sed $tmp +sed --in-place -f $DIR/convert_template.sed $tmp pandoc -s -S -f docbook -t rst -o $rst $tmp -sed --in-place -f post_convert.sed $rst +sed --in-place -f $DIR/post_convert.sed $rst rm $tmp +echo "book writen to $rst" diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.txt index 32a25fad0c1b..ef419fd0897f 100644 --- a/Documentation/static-keys.txt +++ b/Documentation/static-keys.txt @@ -118,7 +118,7 @@ Or: Keys defined via DEFINE_STATIC_KEY_TRUE(), or DEFINE_STATIC_KEY_FALSE, may be used in either static_branch_likely() or static_branch_unlikely() -statemnts. +statements. Branch(es) can be set true via: diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt new file mode 100644 index 000000000000..a0a9c7b3d4d5 --- /dev/null +++ b/Documentation/switchtec.txt @@ -0,0 +1,80 @@ +======================== +Linux Switchtec Support +======================== + +Microsemi's "Switchtec" line of PCI switch devices is already +supported by the kernel with standard PCI switch drivers. However, the +Switchtec device advertises a special management endpoint which +enables some additional functionality. This includes: + +* Packet and Byte Counters +* Firmware Upgrades +* Event and Error logs +* Querying port link status +* Custom user firmware commands + +The switchtec kernel module implements this functionality. + + +Interface +========= + +The primary means of communicating with the Switchtec management firmware is +through the Memory-mapped Remote Procedure Call (MRPC) interface. +Commands are submitted to the interface with a 4-byte command +identifier and up to 1KB of command specific data. The firmware will +respond with a 4 bytes return code and up to 1KB of command specific +data. The interface only processes a single command at a time. + + +Userspace Interface +=================== + +The MRPC interface will be exposed to userspace through a simple char +device: /dev/switchtec#, one for each management endpoint in the system. + +The char device has the following semantics: + +* A write must consist of at least 4 bytes and no more than 1028 bytes. + The first four bytes will be interpreted as the command to run and + the remainder will be used as the input data. A write will send the + command to the firmware to begin processing. + +* Each write must be followed by exactly one read. Any double write will + produce an error and any read that doesn't follow a write will + produce an error. + +* A read will block until the firmware completes the command and return + the four bytes of status plus up to 1024 bytes of output data. (The + length will be specified by the size parameter of the read call -- + reading less than 4 bytes will produce an error. + +* The poll call will also be supported for userspace applications that + need to do other things while waiting for the command to complete. + +The following IOCTLs are also supported by the device: + +* SWITCHTEC_IOCTL_FLASH_INFO - Retrieve firmware length and number + of partitions in the device. + +* SWITCHTEC_IOCTL_FLASH_PART_INFO - Retrieve address and lengeth for + any specified partition in flash. + +* SWITCHTEC_IOCTL_EVENT_SUMMARY - Read a structure of bitmaps + indicating all uncleared events. + +* SWITCHTEC_IOCTL_EVENT_CTL - Get the current count, clear and set flags + for any event. This ioctl takes in a switchtec_ioctl_event_ctl struct + with the event_id, index and flags set (index being the partition or PFF + number for non-global events). It returns whether the event has + occurred, the number of times and any event specific data. The flags + can be used to clear the count or enable and disable actions to + happen when the event occurs. + By using the SWITCHTEC_IOCTL_EVENT_FLAG_EN_POLL flag, + you can set an event to trigger a poll command to return with + POLLPRI. In this way, userspace can wait for events to occur. + +* SWITCHTEC_IOCTL_PFF_TO_PORT and SWITCHTEC_IOCTL_PORT_TO_PFF convert + between PCI Function Framework number (used by the event system) + and Switchtec Logic Port ID and Partition number (which is more + user friendly). diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.txt index 269681a6faec..c3d033a06e8d 100644 --- a/Documentation/sync_file.txt +++ b/Documentation/sync_file.txt @@ -37,7 +37,7 @@ dma_fence_signal(), when it has finished using (or processing) that buffer. Out-fences are fences that the driver creates. On the other hand if the driver receives fence(s) through a sync_file from -userspace we call these fence(s) 'in-fences'. Receiveing in-fences means that +userspace we call these fence(s) 'in-fences'. Receiving in-fences means that we need to wait for the fence(s) to signal before using any buffer related to the in-fences. diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index 2ebabc93014a..14db18c970b1 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -188,7 +188,16 @@ netdev_budget Maximum number of packets taken from all interfaces in one polling cycle (NAPI poll). In one polling cycle interfaces which are registered to polling are -probed in a round-robin manner. +probed in a round-robin manner. Also, a polling cycle may not exceed +netdev_budget_usecs microseconds, even if netdev_budget has not been +exhausted. + +netdev_budget_usecs +--------------------- + +Maximum number of microseconds in one NAPI polling cycle. Polling +will exit when either netdev_budget_usecs have elapsed during the +poll cycle or the number of packets processed reaches netdev_budget. netdev_max_backlog ------------------ diff --git a/Documentation/thermal/intel_powerclamp.txt b/Documentation/thermal/intel_powerclamp.txt index 60073dc9f748..b5df21168fbc 100644 --- a/Documentation/thermal/intel_powerclamp.txt +++ b/Documentation/thermal/intel_powerclamp.txt @@ -268,6 +268,15 @@ 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 +max_state will start the idle injection. Reading cur_state returns the +actual and current idle percentage. This may not be the same value +set by the user in that current idle percentage depends on workload +and includes natural idle. When idle injection is disabled, reading +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 @@ -278,11 +287,12 @@ then the powerclamp driver will not start idle injection. Using Top will not show idle injection kernel threads. If the system is busy (spin test below) and has less than 25% natural -idle time, powerclamp kernel threads will do idle injection, which -appear running to the scheduler. But the overall system idle is still -reflected. 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. +idle time, powerclamp kernel threads will do idle injection. Forced +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 diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index 006f47c7d913..94a987bd2bc5 100644 --- a/Documentation/trace/ftrace.txt +++ b/Documentation/trace/ftrace.txt @@ -1546,7 +1546,7 @@ Note, that the trace data shows the internal priority (99 - rtprio). <idle>-0 3d..3 5us : 0:120:R ==> [003] 2389: 94:R sleep -The 0:120:R means idle was running with a nice priority of 0 (120 - 20) +The 0:120:R means idle was running with a nice priority of 0 (120 - 120) and in the running state 'R'. The sleep task was scheduled in with 2389: 94:R. That is the priority is the kernel rtprio (99 - 5 = 94) and it too is in the running state. diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.txt index 41ef9d8efe95..1a3a3d6bc2a8 100644 --- a/Documentation/trace/kprobetrace.txt +++ b/Documentation/trace/kprobetrace.txt @@ -8,8 +8,9 @@ Overview -------- These events are similar to tracepoint based events. Instead of Tracepoint, this is based on kprobes (kprobe and kretprobe). So it can probe wherever -kprobes can probe (this means, all functions body except for __kprobes -functions). Unlike the Tracepoint based event, this can be added and removed +kprobes can probe (this means, all functions except those with +__kprobes/nokprobe_inline annotation and those marked NOKPROBE_SYMBOL). +Unlike the Tracepoint based event, this can be added and removed dynamically, on the fly. To enable this feature, build your kernel with CONFIG_KPROBE_EVENTS=y. @@ -23,7 +24,7 @@ current_tracer. Instead of that, add probe points via Synopsis of kprobe_events ------------------------- p[:[GRP/]EVENT] [MOD:]SYM[+offs]|MEMADDR [FETCHARGS] : Set a probe - r[:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS] : Set a return probe + r[MAXACTIVE][:[GRP/]EVENT] [MOD:]SYM[+0] [FETCHARGS] : Set a return probe -:[GRP/]EVENT : Clear a probe GRP : Group name. If omitted, use "kprobes" for it. @@ -32,6 +33,9 @@ Synopsis of kprobe_events MOD : Module name which has given SYM. SYM[+offs] : Symbol+offset where the probe is inserted. MEMADDR : Address where the probe is inserted. + MAXACTIVE : Maximum number of instances of the specified function that + can be probed simultaneously, or 0 for the default value + as defined in Documentation/kprobes.txt section 1.3.1. FETCHARGS : Arguments. Each probe can have up to 128 args. %REG : Fetch register REG diff --git a/Documentation/translations/ja_JP/HOWTO b/Documentation/translations/ja_JP/howto.rst index 4ebd20750ef1..4511eed0fabb 100644 --- a/Documentation/translations/ja_JP/HOWTO +++ b/Documentation/translations/ja_JP/howto.rst @@ -1,95 +1,81 @@ NOTE: This is a version of Documentation/HOWTO translated into Japanese. This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com> -and the JF Project team <www.linux.or.jp/JF>. -If you find any difference between this document and the original file -or a problem with the translation, -please contact the maintainer of this file or JF project. - -Please also note that the purpose of this file is to be easier to read -for non English (read: Japanese) speakers and is not intended as a -fork. So if you have any comments or updates for this file, please try -to update the original English file first. - -Last Updated: 2013/07/19 -================================== -ã“ã‚Œã¯ã€ -linux-3.10/Documentation/HOWTO +If you find any difference between this document and the original file or +a problem with the translation, please contact the maintainer of this file. + +Please also note that the purpose of this file is to be easier to +read for non English (read: Japanese) speakers and is not intended as +a fork. So if you have any comments or updates for this file, please +try to update the original English file first. + +---------------------------------- + +ã“ã®æ–‡æ›¸ã¯ã€ +Documentation/process/howto.rst ã®å’Œè¨³ã§ã™ã€‚ -翻訳団体： JF プãƒã‚¸ã‚§ã‚¯ãƒˆ < http://linuxjf.sourceforge.jp/ > -翻訳日： 2013/7/19 -翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> -æ ¡æ£è€…： æ¾å€‰ã•ã‚“ <nbh--mats at nifty dot com> - å°æž— é›…å…¸ã•ã‚“ (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> - æ¦äº•ä¼¸å…‰ã•ã‚“ã€<takei at webmasters dot gr dot jp> - ã‹ãã“ã•ã‚“ (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp> - 野å£ã•ã‚“ (Kenji Noguchi) <tokyo246 at gmail dot com> - 河内ã•ã‚“ (Takayoshi Kochi) <t-kochi at bq dot jp dot nec dot com> - 岩本ã•ã‚“ (iwamoto) <iwamoto.kn at ncos dot nec dot co dot jp> - 内田ã•ã‚“ (Satoshi Uchida) <s-uchida at ap dot jp dot nec dot com> -================================== +翻訳者： Tsugikazu Shibata <tshibata@ab.jp.nec.com> + +---------------------------------- Linux カーãƒãƒ«é–‹ç™ºã®ã‚„ã‚Šæ–¹ -------------------------------- +========================== ã“ã‚Œã¯ä¸Šã®ãƒˆãƒ”ック( Linux カーãƒãƒ«é–‹ç™ºã®ã‚„ã‚Šæ–¹)ã®é‡è¦ãªäº‹æŸ„を網羅ã—㟠-ドã‚ュメントã§ã™ã€‚ã“ã“ã«ã¯ Linux カーãƒãƒ«é–‹ç™ºè€…ã«ãªã‚‹ãŸã‚ã®æ–¹æ³•ã¨ -Linux カーãƒãƒ«é–‹ç™ºã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¨å…±ã«æ´»å‹•ã™ã‚‹ã‚„り方をå¦ã¶æ–¹æ³•ãŒå«ã¾ã‚Œã¦ -ã„ã¾ã™ã€‚カーãƒãƒ«ãƒ—ãƒã‚°ãƒ©ãƒŸãƒ³ã‚°ã«é–¢ã™ã‚‹æŠ€è¡“çš„ãªé …ç›®ã«é–¢ã™ã‚‹ã“ã¨ã¯ä½•ã‚‚å« -ã‚ãªã„よã†ã«ã—ã¦ã„ã¾ã™ãŒã€ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºè€…ã¨ãªã‚‹ãŸã‚ã®æ£ã—ã„æ–¹å‘ã«å‘ã‹ã† -手助ã‘ã«ãªã‚Šã¾ã™ã€‚ +ドã‚ュメントã§ã™ã€‚ã“ã“ã«ã¯ Linux カーãƒãƒ«é–‹ç™ºè€…ã«ãªã‚‹ãŸã‚ã®æ–¹æ³•ã¨Linux +カーãƒãƒ«é–‹ç™ºã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¨å…±ã«æ´»å‹•ã™ã‚‹ã‚„り方をå¦ã¶æ–¹æ³•ãŒå«ã¾ã‚Œã¦ã„ã¾ã™ã€‚ +カーãƒãƒ«ãƒ—ãƒã‚°ãƒ©ãƒŸãƒ³ã‚°ã«é–¢ã™ã‚‹æŠ€è¡“çš„ãªé …ç›®ã«é–¢ã™ã‚‹ã“ã¨ã¯ä½•ã‚‚å«ã‚ãªã„よ +ã†ã«ã—ã¦ã„ã¾ã™ãŒã€ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºè€…ã¨ãªã‚‹ãŸã‚ã®æ£ã—ã„æ–¹å‘ã«å‘ã‹ã†æ‰‹åŠ©ã‘ã« +ãªã‚Šã¾ã™ã€‚ -ã‚‚ã—ã€ã“ã®ãƒ‰ã‚ュメントã®ã©ã“ã‹ãŒå¤ããªã£ã¦ã„ãŸå ´åˆã«ã¯ã€ã“ã®ãƒ‰ã‚ュメン -トã®æœ€å¾Œã«ãƒªã‚¹ãƒˆã—ãŸãƒ¡ãƒ³ãƒ†ãƒŠã«ãƒ‘ッãƒã‚’é€ã£ã¦ãã ã•ã„。 +ã‚‚ã—ã€ã“ã®ãƒ‰ã‚ュメントã®ã©ã“ã‹ãŒå¤ããªã£ã¦ã„ãŸå ´åˆã«ã¯ã€ã“ã®ãƒ‰ã‚ュメント +ã®æœ€å¾Œã«ãƒªã‚¹ãƒˆã—ãŸãƒ¡ãƒ³ãƒ†ãƒŠã«ãƒ‘ッãƒã‚’é€ã£ã¦ãã ã•ã„。 ã¯ã˜ã‚ã« --------- -ã‚ãªãŸã¯ã€€Linux カーãƒãƒ«ã®é–‹ç™ºè€…ã«ãªã‚‹æ–¹æ³•ã‚’å¦ã³ãŸã„ã®ã§ã—ょã†ã‹ï¼Ÿã€€ã -ã‚Œã¨ã‚‚ã‚ãªãŸã¯ä¸Šå¸ã‹ã‚‰ã€Œã“ã®ãƒ‡ãƒã‚¤ã‚¹ã® Linux ドライãƒã‚’書ãよã†ã«ã€ã¨ -言ã‚ã‚Œã¦ã„ã‚‹ã®ã§ã—ょã†ã‹ï¼Ÿã€€ -ã“ã®æ–‡æ›¸ã®ç›®çš„ã¯ã€ã‚ãªãŸãŒè¸ã‚€ã¹ãæ‰‹é †ã¨ã€ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¨ä¸€ç·’ã«ã†ã¾ãåƒ -ãヒントを書ã下ã™ã“ã¨ã§ã€ã‚ãªãŸãŒçŸ¥ã‚‹ã¹ãå…¨ã¦ã®ã“ã¨ã‚’æ•™ãˆã‚‹ã“ã¨ã§ã™ã€‚ -ã¾ãŸã€ã“ã®ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ãŒãªãœä»Šã†ã¾ãã¾ã‚ã£ã¦ã„ã‚‹ã®ã‹ã¨ã„ã†ç†ç”±ã®ä¸€éƒ¨ã‚‚ -説明ã—よã†ã¨è©¦ã¿ã¦ã„ã¾ã™ã€‚ - - -カーãƒãƒ«ã¯ å°‘é‡ã®ã‚¢ãƒ¼ã‚テクãƒãƒ£ä¾å˜éƒ¨åˆ†ãŒã‚¢ã‚»ãƒ³ãƒ–リ言語ã§æ›¸ã‹ã‚Œã¦ã„ã‚‹ -以外ã¯å¤§éƒ¨åˆ†ã¯ C 言語ã§æ›¸ã‹ã‚Œã¦ã„ã¾ã™ã€‚C言語をよãç†è§£ã—ã¦ã„ã‚‹ã“ã¨ã¯ã‚«ãƒ¼ -ãƒãƒ«é–‹ç™ºè€…ã«ã¯å¿…è¦ã§ã™ã€‚アーã‚テクãƒãƒ£å‘ã‘ã®ä½Žãƒ¬ãƒ™ãƒ«éƒ¨åˆ†ã®é–‹ç™ºã‚’ã™ã‚‹ã® -ã§ãªã‘ã‚Œã°ã€(ã©ã‚“ãªã‚¢ãƒ¼ã‚テクãƒãƒ£ã§ã‚‚)アセンブリ(訳注: 言語)ã¯å¿…è¦ã‚ã‚Š -ã¾ã›ã‚“。以下ã®æœ¬ã¯ã€C 言語ã®å分ãªçŸ¥è˜ã‚„何年もã®çµŒé¨“ã«å–ã£ã¦ä»£ã‚ã‚‹ã‚‚ã® -ã§ã¯ã‚ã‚Šã¾ã›ã‚“ãŒã€å°‘ãªãã¨ã‚‚リファレンスã¨ã—ã¦ã¯è‰¯ã„本ã§ã™ã€‚ +ã‚ãªãŸã¯ Linux カーãƒãƒ«ã®é–‹ç™ºè€…ã«ãªã‚‹æ–¹æ³•ã‚’å¦ã³ãŸã„ã®ã§ã—ょã†ã‹ï¼Ÿã€€ã +ã‚Œã¨ã‚‚上å¸ã‹ã‚‰ã€Œã“ã®ãƒ‡ãƒã‚¤ã‚¹ã® Linux ドライãƒã‚’書ãよã†ã«ã€ã¨è¨€ã‚れ㟠+ã®ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。ã“ã®æ–‡æ›¸ã®ç›®çš„ã¯ã€ã‚ãªãŸãŒè¸ã‚€ã¹ãæ‰‹é †ã¨ã€ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ +ã¨ä¸€ç·’ã«ã†ã¾ãåƒãヒントを書ã下ã™ã“ã¨ã§ã€ã‚ãªãŸãŒçŸ¥ã‚‹ã¹ãå…¨ã¦ã®ã“ã¨ã‚’ +æ•™ãˆã‚‹ã“ã¨ã§ã™ã€‚ã¾ãŸã€ã“ã®ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ãŒãªãœä»Šã†ã¾ãã¾ã‚ã£ã¦ã„ã‚‹ã®ã‹ã¨ +ã„ã†ç†ç”±ã‚‚説明ã—よã†ã¨è©¦ã¿ã¦ã„ã¾ã™ã€‚ + +カーãƒãƒ«ã¯å°‘é‡ã®ã‚¢ãƒ¼ã‚テクãƒãƒ£ä¾å˜éƒ¨åˆ†ãŒã‚¢ã‚»ãƒ³ãƒ–リ言語ã§æ›¸ã‹ã‚Œã¦ã„る以 +外ã®å¤§éƒ¨åˆ†ã¯ C 言語ã§æ›¸ã‹ã‚Œã¦ã„ã¾ã™ã€‚C言語をよãç†è§£ã—ã¦ã„ã‚‹ã“ã¨ã¯ã‚«ãƒ¼ +ãƒãƒ«é–‹ç™ºã«å¿…è¦ã§ã™ã€‚低レベルã®ã‚¢ãƒ¼ã‚テクãƒãƒ£é–‹ç™ºã‚’ã™ã‚‹ã®ã§ãªã‘ã‚Œã°ã€ +(ã©ã‚“ãªã‚¢ãƒ¼ã‚テクãƒãƒ£ã§ã‚‚)アセンブリ(訳注: 言語)ã¯å¿…è¦ã‚ã‚Šã¾ã›ã‚“。以下 +ã®æœ¬ã¯ã€C 言語ã®å分ãªçŸ¥è˜ã‚„何年もã®çµŒé¨“ã«å–ã£ã¦ä»£ã‚ã‚‹ã‚‚ã®ã§ã¯ã‚ã‚Šã¾ã› +ã‚“ãŒã€å°‘ãªãã¨ã‚‚リファレンスã¨ã—ã¦ã¯è‰¯ã„本ã§ã™ã€‚ + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - -『プãƒã‚°ãƒ©ãƒŸãƒ³ã‚°è¨€èªžï¼£ç¬¬2版ã€(B.W. カーニãƒãƒ³/D.M. リッãƒãƒ¼è‘— 石田晴久訳) [共立出版] + - 『プãƒã‚°ãƒ©ãƒŸãƒ³ã‚°è¨€èªžï¼£ç¬¬2版ã€(B.W. カーニãƒãƒ³/D.M. リッãƒãƒ¼è‘— 石田晴久訳) [共立出版] - "Practical C Programming" by Steve Oualline [O'Reilly] - 『C実践プãƒã‚°ãƒ©ãƒŸãƒ³ã‚°ç¬¬3版ã€(Steve Ouallineè‘— 望月康å¸ç›£è¨³ è°·å£åŠŸè¨³) [オライリージャパン] - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] - - 『新・詳説 C 言語 H&S リファレンス〠- (サミュエル P ãƒãƒ¼ãƒ“ソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトãƒãƒ³ã‚¯] + - 『新・詳説 C 言語 H&S リファレンス〠(サミュエル P ãƒãƒ¼ãƒ“ソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトãƒãƒ³ã‚¯] カーãƒãƒ«ã¯ GNU C 㨠GNU ツールãƒã‚§ã‚¤ãƒ³ã‚’使ã£ã¦æ›¸ã‹ã‚Œã¦ã„ã¾ã™ã€‚カーãƒãƒ« 㯠ISO C89 仕様ã«æº–æ‹ ã—ã¦æ›¸ã一方ã§ã€æ¨™æº–ã«ã¯ç„¡ã„言語拡張を多ã使ã£ã¦ -ã„ã¾ã™ã€‚カーãƒãƒ«ã¯æ¨™æº– C ライブラリã¨ã¯é–¢ä¿‚ãŒãªã„ã¨ã„ã£ãŸã€C 言語フリー -スタンディング環境ã§ã™ã€‚ãã®ãŸã‚ã€C ã®æ¨™æº–ã§ä½¿ãˆãªã„ã‚‚ã®ã‚‚ã‚ã‚Šã¾ã™ã€‚ä»» -æ„ã® long long ã®é™¤ç®—や浮動å°æ•°ç‚¹ã¯ä½¿ãˆã¾ã›ã‚“。 -ã¨ãã©ãã€ã‚«ãƒ¼ãƒãƒ«ãŒãƒ„ールãƒã‚§ã‚¤ãƒ³ã‚„ C 言語拡張ã«ç½®ã„ã¦ã„ã‚‹å‰æãŒã©ã† -ãªã£ã¦ã„ã‚‹ã®ã‹ã‚ã‹ã‚Šã«ãã„ã“ã¨ãŒã‚ã‚Šã€ã¾ãŸã€æ®‹å¿µãªã“ã¨ã«æ±ºå®šçš„ãªãƒªãƒ•ã‚¡ -レンスã¯å˜åœ¨ã—ã¾ã›ã‚“ã€‚æƒ…å ±ã‚’å¾—ã‚‹ã«ã¯ã€gcc ã® info ページ( info gcc )ã‚’ -見ã¦ãã ã•ã„。 +ã„ã¾ã™ã€‚カーãƒãƒ«ã¯æ¨™æº– C ライブラリã«ä¾å˜ã—ãªã„ã€C 言語éžä¾å˜ç’°å¢ƒã§ã™ã€‚ +ãã®ãŸã‚ã€C ã®æ¨™æº–ã®ä¸ã§ä½¿ãˆãªã„ã‚‚ã®ã‚‚ã‚ã‚Šã¾ã™ã€‚特ã«ä»»æ„ã® long long +ã®é™¤ç®—や浮動å°æ•°ç‚¹ã¯ä½¿ãˆã¾ã›ã‚“。カーãƒãƒ«ãŒãƒ„ールãƒã‚§ã‚¤ãƒ³ã‚„ C 言語拡張 +ã«ç½®ã„ã¦ã„ã‚‹å‰æãŒã©ã†ãªã£ã¦ã„ã‚‹ã®ã‹ã‚ã‹ã‚Šã«ãã„ã“ã¨ãŒæ™‚々ã‚ã‚Šã€ã¾ãŸã€ +残念ãªã“ã¨ã«æ±ºå®šçš„ãªãƒªãƒ•ã‚¡ãƒ¬ãƒ³ã‚¹ã¯å˜åœ¨ã—ã¾ã›ã‚“ã€‚æƒ…å ±ã‚’å¾—ã‚‹ã«ã¯ã€gcc ã® +info ページ( info gcc )を見ã¦ãã ã•ã„。 ã‚ãªãŸã¯æ—¢å˜ã®é–‹ç™ºã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¨ä¸€ç·’ã«ä½œæ¥ã™ã‚‹æ–¹æ³•ã‚’å¦ã¼ã†ã¨ã—ã¦ã„ã‚‹ã“ -ã¨ã«ç•™æ„ã—ã¦ãã ã•ã„。ãã®ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯ã€ã‚³ãƒ¼ãƒ‡ã‚£ãƒ³ã‚°ã€ã‚¹ã‚¿ã‚¤ãƒ«ã€ -é–‹ç™ºæ‰‹é †ã«ã¤ã„ã¦é«˜åº¦ãªæ¨™æº–ã‚’æŒã¤ã€å¤šæ§˜ãªäººã®é›†ã¾ã‚Šã§ã™ã€‚ -地ç†çš„ã«åˆ†æ•£ã—ãŸå¤§è¦æ¨¡ãªãƒãƒ¼ãƒ ã«å¯¾ã—ã¦ã‚‚ã£ã¨ã‚‚ã†ã¾ãã„ãã¨ã‚ã‹ã£ãŸã“㨠-をベースã«ã—ãªãŒã‚‰ã€ã“れらã®æ¨™æº–ã¯é•·ã„時間をã‹ã‘ã¦ç¯‰ã‹ã‚Œã¦ãã¾ã—ãŸã€‚ -ã“れらã¯ãã¡ã‚“ã¨æ–‡æ›¸åŒ–ã•ã‚Œã¦ã„ã¾ã™ã‹ã‚‰ã€äº‹å‰ã«ã“れらã®æ¨™æº–ã«ã¤ã„ã¦ã§ã -ã‚‹ã ã‘ãŸãã•ã‚“å¦ã‚“ã§ãã ã•ã„。ã¾ãŸçš†ãŒã‚ãªãŸã‚„ã‚ãªãŸã®ä¼šç¤¾ã®ã‚„ã‚Šæ–¹ã«åˆã‚ -ã›ã¦ãれるã¨æ€ã‚ãªã„ã§ãã ã•ã„。 +ã¨ã«æ€ã„出ã—ã¦ãã ã•ã„。ãã®ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯ã€ã‚³ãƒ¼ãƒ‡ã‚£ãƒ³ã‚°ã€ã‚¹ã‚¿ã‚¤ãƒ«ã€é–‹ +ç™ºæ‰‹é †ã«ã¤ã„ã¦é«˜åº¦ãªæ¨™æº–ã‚’æŒã¤ã€å¤šæ§˜ãªäººã®é›†ã¾ã‚Šã§ã™ã€‚地ç†çš„ã«åˆ†æ•£ã—㟠+大è¦æ¨¡ãªãƒãƒ¼ãƒ ã«å¯¾ã—ã¦ã‚‚ã£ã¨ã‚‚ã†ã¾ãã„ãã¨ã‚ã‹ã£ãŸã“ã¨ã‚’ベースã«ã—ãªãŒ +らã€ã“れらã®æ¨™æº–ã¯é•·ã„時間をã‹ã‘ã¦ç¯‰ã‹ã‚Œã¦ãã¾ã—ãŸã€‚ã“れらã¯ãã¡ã‚“ã¨æ–‡ +書化ã•ã‚Œã¦ã„ã¾ã™ã‹ã‚‰ã€äº‹å‰ã«ã“れらã®æ¨™æº–ã«ã¤ã„ã¦äº‹å‰ã«ã§ãã‚‹ã ã‘ãŸãã• +ã‚“å¦ã‚“ã§ãã ã•ã„。ã¾ãŸçš†ãŒã‚ãªãŸã‚„ã‚ãªãŸã®ä¼šç¤¾ã®ã‚„ã‚Šæ–¹ã«åˆã‚ã›ã¦ãれる +ã¨æ€ã‚ãªã„ã§ãã ã•ã„。 法的å•é¡Œ ------------- +-------- Linux カーãƒãƒ«ã®ã‚½ãƒ¼ã‚¹ã‚³ãƒ¼ãƒ‰ã¯ GPL ライセンスã®ä¸‹ã§ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã¦ã„ã¾ ã™ã€‚ライセンスã®è©³ç´°ã«ã¤ã„ã¦ã¯ã€ã‚½ãƒ¼ã‚¹ãƒ„リーã®ãƒ¡ã‚¤ãƒ³ãƒ‡ã‚£ãƒ¬ã‚¯ãƒˆãƒªã«å˜åœ¨ @@ -98,8 +84,9 @@ Linux カーãƒãƒ«ã®ã‚½ãƒ¼ã‚¹ã‚³ãƒ¼ãƒ‰ã¯ GPL ライセンスã®ä¸‹ã§ãƒªãƒªãƒ¼ 法律家ã«ç›¸è«‡ã—ã¦ãã ã•ã„。メーリングリストã®äººé”ã¯æ³•å¾‹å®¶ã§ã¯ãªãã€æ³•çš„ å•é¡Œã«ã¤ã„ã¦ã¯å½¼ã‚‰ã®å£°æ˜Žã¯ã‚ã¦ã«ã™ã‚‹ã¹ãã§ã¯ã‚ã‚Šã¾ã›ã‚“。 -GPL ã«é–¢ã™ã‚‹å…±é€šã®è³ªå•ã‚„回ç”ã«ã¤ã„ã¦ã¯ã€ä»¥ä¸‹ã‚’å‚ç…§ã—ã¦ãã ã•ã„。 - http://www.gnu.org/licenses/gpl-faq.html +GPL ã«é–¢ã™ã‚‹å…±é€šã®è³ªå•ã‚„回ç”ã«ã¤ã„ã¦ã¯ã€ä»¥ä¸‹ã‚’å‚ç…§ã—ã¦ãã ã•ã„- + + https://www.gnu.org/licenses/gpl-faq.html ドã‚ュメント ------------ @@ -119,111 +106,129 @@ linux-api@vger.kernel.org ã«é€ã‚‹ã“ã¨ã‚’勧ã‚ã¾ã™ã€‚ README ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã¯ Linuxカーãƒãƒ«ã®ç°¡å˜ãªèƒŒæ™¯ã¨ã‚«ãƒ¼ãƒãƒ«ã‚’è¨å®š(訳注 configure )ã—ã€ç”Ÿæˆ(訳注 build )ã™ã‚‹ãŸã‚ã«å¿…è¦ãªã“ã¨ã¯ä½•ã‹ãŒæ›¸ã‹ã‚Œ - ã¦ã„ã¾ã™ã€‚カーãƒãƒ«ã«é–¢ã—ã¦åˆã‚ã¦ã®äººã¯ã“ã“ã‹ã‚‰ã‚¹ã‚¿ãƒ¼ãƒˆã™ã‚‹ã¨è‰¯ã„㧠- ã—ょã†ã€‚ + ã¦ã„ã¾ã™ã€‚ カーãƒãƒ«ã«é–¢ã—ã¦åˆã‚ã¦ã®äººã¯ã“ã“ã‹ã‚‰ã‚¹ã‚¿ãƒ¼ãƒˆã™ã‚‹ã¨è‰¯ã„ + ã§ã—ょã†ã€‚ - Documentation/Changes - ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã¯ã‚«ãƒ¼ãƒãƒ«ã‚’ã†ã¾ã生æˆ(訳注 build )ã—ã€èµ°ã‚‰ã›ã‚‹ã®ã«æœ€ - å°é™ã®ãƒ¬ãƒ™ãƒ«ã§å¿…è¦ãªæ•°ã€…ã®ã‚½ãƒ•ãƒˆã‚¦ã‚§ã‚¢ãƒ‘ッケージã®ä¸€è¦§ã‚’示ã—ã¦ã„ - ã¾ã™ã€‚ + :ref:`Documentation/Process/changes.rst <changes>` + ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã¯ã‚«ãƒ¼ãƒãƒ«ã‚’ã†ã¾ã生æˆ(訳注 build )ã—ã€èµ°ã‚‰ã›ã‚‹ã®ã«æœ€ + å°é™ã®ãƒ¬ãƒ™ãƒ«ã§å¿…è¦ãªæ•°ã€…ã®ã‚½ãƒ•ãƒˆã‚¦ã‚§ã‚¢ãƒ‘ッケージã®ä¸€è¦§ã‚’示ã—ã¦ã„ + ã¾ã™ã€‚ - Documentation/process/coding-style.rst + :ref:`Documentation/process/coding-style.rst <codingstyle>` ã“れ㯠Linux カーãƒãƒ«ã®ã‚³ãƒ¼ãƒ‡ã‚£ãƒ³ã‚°ã‚¹ã‚¿ã‚¤ãƒ«ã¨èƒŒæ™¯ã«ã‚ã‚‹ç†ç”±ã‚’記述 ã—ã¦ã„ã¾ã™ã€‚å…¨ã¦ã®æ–°ã—ã„コードã¯ã“ã®ãƒ‰ã‚ュメントã«ã‚るガイドライン ã«å¾“ã£ã¦ã„ã‚‹ã“ã¨ã‚’期待ã•ã‚Œã¦ã„ã¾ã™ã€‚大部分ã®ãƒ¡ãƒ³ãƒ†ãƒŠã¯ã“れらã®ãƒ«ãƒ¼ ルã«å¾“ã£ã¦ã„ã‚‹ã‚‚ã®ã ã‘ã‚’å—ã‘付ã‘ã€å¤šãã®äººã¯æ£ã—ã„スタイルã®ã‚³ãƒ¼ãƒ‰ ã ã‘をレビューã—ã¾ã™ã€‚ - Documentation/process/submitting-patches.rst - Documentation/process/submitting-drivers.rst - ã“れらã®ãƒ•ã‚¡ã‚¤ãƒ«ã«ã¯ã€ã©ã†ã‚„ã£ã¦ã†ã¾ãパッãƒã‚’作ã£ã¦æŠ•ç¨¿ã™ã‚‹ã‹ã« - ã¤ã„ã¦éžå¸¸ã«è©³ã—ã書ã‹ã‚Œã¦ãŠã‚Šã€ä»¥ä¸‹ã‚’å«ã¿ã¾ã™(ã“ã‚Œã ã‘ã«é™ã‚‰ãªã„ - ã‘ã‚Œã©ã‚‚) - - Email ã«å«ã‚€ã“㨠- - Email ã®å½¢å¼ - - ã ã‚Œã«é€ã‚‹ã‹ - ã“れらã®ãƒ«ãƒ¼ãƒ«ã«å¾“ãˆã°ã†ã¾ãã„ãã“ã¨ã‚’ä¿è¨¼ã™ã‚‹ã“ã¨ã§ã¯ã‚ã‚Šã¾ã›ã‚“ - ㌠(ã™ã¹ã¦ã®ãƒ‘ッãƒã¯å†…容ã¨ã‚¹ã‚¿ã‚¤ãƒ«ã«ã¤ã„ã¦ç²¾æŸ»ã‚’å—ã‘ã‚‹ã®ã§)〠- ルールã«å¾“ã‚ãªã‘ã‚Œã°é–“é•ã„ãªãã†ã¾ãã„ã‹ãªã„ã§ã—ょã†ã€‚ - - ã“ã®ä»–ã«ãƒ‘ッãƒã‚’作る方法ã«ã¤ã„ã¦ã®ã‚ˆãã§ããŸè¨˜è¿°ã¯- - - "The Perfect Patch" + :ref:`Documentation/process/submitting-patches.rst <codingstyle>` 㨠:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + ã“れらã®ãƒ•ã‚¡ã‚¤ãƒ«ã«ã¯ã€ã©ã†ã‚„ã£ã¦ã†ã¾ãパッãƒã‚’作ã£ã¦æŠ•ç¨¿ã™ã‚‹ã‹ã«ã¤ + ã„ã¦éžå¸¸ã«è©³ã—ã書ã‹ã‚Œã¦ãŠã‚Šã€ä»¥ä¸‹ã‚’å«ã¿ã¾ã™ (ã“ã‚Œã ã‘ã«é™ã‚‰ãªã„ + ã‘ã‚Œã©ã‚‚) + + - Email ã«å«ã‚€ã“㨠+ - Email ã®å½¢å¼ + - ã ã‚Œã«é€ã‚‹ã‹ + + ã“れらã®ãƒ«ãƒ¼ãƒ«ã«å¾“ãˆã°ã†ã¾ãã„ãã“ã¨ã‚’ä¿è¨¼ã™ã‚‹ã“ã¨ã§ã¯ã‚ã‚Šã¾ã›ã‚“ + ㌠(ã™ã¹ã¦ã®ãƒ‘ッãƒã¯å†…容ã¨ã‚¹ã‚¿ã‚¤ãƒ«ã«ã¤ã„ã¦ç²¾æŸ»ã‚’å—ã‘ã‚‹ã®ã§)〠+ ルールã«å¾“ã‚ãªã‘ã‚Œã°é–“é•ã„ãªãã†ã¾ãã„ã‹ãªã„ã§ã—ょã†ã€‚ + + ã“ã®ä»–ã«ãƒ‘ッãƒã‚’作る方法ã«ã¤ã„ã¦ã®ã‚ˆãã§ããŸè¨˜è¿°ã¯- + + "The Perfect Patch" http://www.ozlabs.org/~akpm/stuff/tpp.txt - "Linux kernel patch submission format" + "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/process/stable-api-nonsense.rst - ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã¯ã‚«ãƒ¼ãƒãƒ«ã®ä¸ã«ä¸å¤‰ã®APIã‚’æŒãŸãªã„ã“ã¨ã«ã—ãŸæ„è˜çš„㪠- 決æ–ã®èƒŒæ™¯ã«ã‚ã‚‹ç†ç”±ã«ã¤ã„ã¦æ›¸ã‹ã‚Œã¦ã„ã¾ã™ã€‚以下ã®ã‚ˆã†ãªã“ã¨ã‚’å« - ã‚“ã§ã„ã¾ã™- - - サブシステムã¨ã®é–“ã«å±¤ã‚’作るã“ã¨(コンパãƒãƒ“リティã®ãŸã‚?) - - オペレーティングシステム間ã®ãƒ‰ãƒ©ã‚¤ãƒã®ç§»æ¤æ€§ - - カーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã®ç´ æ—©ã„変更をé…らã›ã‚‹(ã‚‚ã—ãã¯ç´ æ—©ã„変更 - を妨ã’ã‚‹) - ã“ã®ãƒ‰ã‚ュメント㯠Linux 開発ã®æ€æƒ³ã‚’ç†è§£ã™ã‚‹ã®ã«éžå¸¸ã«é‡è¦ã§ã™ã€‚ - ãã—ã¦ã€ä»–ã®OSã§ã®é–‹ç™ºè€…㌠Linux ã«ç§»ã‚‹æ™‚ã«ã¨ã¦ã‚‚é‡è¦ã§ã™ã€‚ - - Documentation/admin-guide/security-bugs.rst + :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` + ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã¯ã‚«ãƒ¼ãƒãƒ«ã®ä¸ã«ä¸å¤‰ã® API ã‚’æŒãŸãªã„ã“ã¨ã«ã—ãŸæ„è˜çš„ + ãªæ±ºæ–ã®èƒŒæ™¯ã«ã‚ã‚‹ç†ç”±ã«ã¤ã„ã¦æ›¸ã‹ã‚Œã¦ã„ã¾ã™ã€‚以下ã®ã‚ˆã†ãªã“ã¨ã‚’å« + ã‚“ã§ã„ã¾ã™- + + - サブシステムã¨ã®é–“ã«å±¤ã‚’作るã“ã¨(コンパãƒãƒ“リティã®ãŸã‚?) + - オペレーティングシステム間ã®ãƒ‰ãƒ©ã‚¤ãƒã®ç§»æ¤æ€§ + - カーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã®ç´ æ—©ã„変更をé…らã›ã‚‹(ã‚‚ã—ãã¯ç´ æ—©ã„変更を妨ã’ã‚‹) + + ã“ã®ãƒ‰ã‚ュメント㯠Linux 開発ã®æ€æƒ³ã‚’ç†è§£ã™ã‚‹ã®ã«éžå¸¸ã«é‡è¦ã§ã™ã€‚ + ãã—ã¦ã€ä»–ã®OSã§ã®é–‹ç™ºè€…㌠Linux ã«ç§»ã‚‹æ™‚ã«ã¨ã¦ã‚‚é‡è¦ã§ã™ã€‚ + + :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` ã‚‚ã— Linux カーãƒãƒ«ã§ã‚»ã‚ュリティå•é¡Œã‚’発見ã—ãŸã‚ˆã†ã«æ€ã£ãŸã‚‰ã€ã“ ã®ãƒ‰ã‚ュメントã®ã‚¹ãƒ†ãƒƒãƒ—ã«å¾“ã£ã¦ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºè€…ã«é€£çµ¡ã—ã€å•é¡Œè§£æ±ºã‚’ 支æ´ã—ã¦ãã ã•ã„。 - Documentation/process/management-style.rst + :ref:`Documentation/process/management-style.rst <managementstyle>` ã“ã®ãƒ‰ã‚ュメント㯠Linux カーãƒãƒ«ã®ãƒ¡ãƒ³ãƒ†ãƒŠé”ãŒã©ã†è¡Œå‹•ã™ã‚‹ã‹ã€ 彼らã®æ‰‹æ³•ã®èƒŒæ™¯ã«ã‚る共有ã•ã‚Œã¦ã„る精神ã«ã¤ã„ã¦è¨˜è¿°ã—ã¦ã„ã¾ã™ã€‚ã“ ã‚Œã¯ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºã®åˆå¿ƒè€…ãªã‚‰ï¼ˆã‚‚ã—ãã¯ã€å˜ã«èˆˆå‘³ãŒã‚ã‚‹ã ã‘ã®äººã§ã‚‚） é‡è¦ã§ã™ã€‚ãªãœãªã‚‰ã“ã®ãƒ‰ã‚ュメントã¯ã€ã‚«ãƒ¼ãƒãƒ«ãƒ¡ãƒ³ãƒ†ãƒŠé”ã®ç‹¬ç‰¹ãª 行動ã«ã¤ã„ã¦ã®å¤šãã®èª¤è§£ã‚„混乱を解消ã™ã‚‹ã‹ã‚‰ã§ã™ã€‚ - Documentation/process/stable-kernel-rules.rst + :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã¯ã©ã®ã‚ˆã†ã« stable カーãƒãƒ«ã®ãƒªãƒªãƒ¼ã‚¹ãŒè¡Œã‚れるã‹ã®ãƒ«ãƒ¼ ルãŒè¨˜è¿°ã•ã‚Œã¦ã„ã¾ã™ã€‚ãã—ã¦ã“れらã®ãƒªãƒªãƒ¼ã‚¹ã®ä¸ã®ã©ã“ã‹ã§å¤‰æ›´ã‚’å– ã‚Šå…¥ã‚Œã¦ã‚‚らã„ãŸã„å ´åˆã«ä½•ã‚’ã™ã‚Œã°è‰¯ã„ã‹ãŒç¤ºã•ã‚Œã¦ã„ã¾ã™ã€‚ - Documentation/process/kernel-docs.rst -　　カーãƒãƒ«é–‹ç™ºã«ä»˜éšã™ã‚‹å¤–部ドã‚ュメントã®ãƒªã‚¹ãƒˆã§ã™ã€‚ã‚‚ã—ã‚ãªãŸãŒ - 探ã—ã¦ã„ã‚‹ã‚‚ã®ãŒã‚«ãƒ¼ãƒãƒ«å†…ã®ãƒ‰ã‚ュメントã§ã¿ã¤ã‹ã‚‰ãªã‹ã£ãŸå ´åˆã€ - ã“ã®ãƒªã‚¹ãƒˆã‚’ã‚ãŸã£ã¦ã¿ã¦ãã ã•ã„。 + :Ref:`Documentation/process/kernel-docs.rst <kernel_docs>` + カーãƒãƒ«é–‹ç™ºã«ä»˜éšã™ã‚‹å¤–部ドã‚ュメントã®ãƒªã‚¹ãƒˆã§ã™ã€‚ã‚‚ã—ã‚ãªãŸãŒæŽ¢ + ã—ã¦ã„ã‚‹ã‚‚ã®ãŒã‚«ãƒ¼ãƒãƒ«å†…ã®ãƒ‰ã‚ュメントã§ã¿ã¤ã‹ã‚‰ãªã‹ã£ãŸå ´åˆã€ã“ã® + リストをã‚ãŸã£ã¦ã¿ã¦ãã ã•ã„。 - Documentation/process/applying-patches.rst + :ref:`Documentation/process/applying-patches.rst <applying_patches>` パッãƒã¨ã¯ãªã«ã‹ã€ãƒ‘ッãƒã‚’ã©ã†ã‚„ã£ã¦æ§˜ã€…ãªã‚«ãƒ¼ãƒãƒ«ã®é–‹ç™ºãƒ–ランãƒã« é©ç”¨ã™ã‚‹ã®ã‹ã«ã¤ã„ã¦æ£ç¢ºã«è¨˜è¿°ã—ãŸè‰¯ã„入門書ã§ã™ã€‚ -カーãƒãƒ«ã¯ã‚½ãƒ¼ã‚¹ã‚³ãƒ¼ãƒ‰ã‹ã‚‰è‡ªå‹•çš„ã«ç”Ÿæˆå¯èƒ½ãªå¤šæ•°ã®ãƒ‰ã‚ュメントを自分自 -身ã§ã‚‚ã£ã¦ã„ã¾ã™ã€‚ã“ã‚Œã«ã¯ã‚«ãƒ¼ãƒãƒ«å†… API ã®ã™ã¹ã¦ã®è¨˜è¿°ã‚„ã€ã©ã†æ£ã—ã -ãƒãƒƒã‚¯ã‚’ã‹ã‘ã‚‹ã‹ã®è¦å‰‡ãŒå«ã¾ã‚Œã¾ã™ã€‚ã“ã®ãƒ‰ã‚ュメント㯠-Documentation/DocBook/ ディレクトリã«ä½œã‚‰ã‚Œã€ä»¥ä¸‹ã®ã‚ˆã†ã« - make pdfdocs - make psdocs - make htmldocs - make mandocs -コマンドを実行ã™ã‚‹ã¨ãƒ¡ã‚¤ãƒ³ã‚«ãƒ¼ãƒãƒ«ã®ã‚½ãƒ¼ã‚¹ãƒ‡ã‚£ãƒ¬ã‚¯ãƒˆãƒªã‹ã‚‰ -ãã‚Œãžã‚Œã€PDF, Postscript, HTML, man page ã®å½¢å¼ã§ç”Ÿæˆã•ã‚Œã¾ã™ã€‚ +カーãƒãƒ«ã¯ã‚½ãƒ¼ã‚¹ã‚³ãƒ¼ãƒ‰ãã®ã‚‚ã®ã‚„ã€ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã®ã‚ˆã†ãªãƒªã‚¹ãƒˆãƒ©ã‚¯ãƒãƒ£ãƒ¼ +ドテã‚ストマークアップ(ReST)ã‹ã‚‰è‡ªå‹•çš„ã«ç”Ÿæˆå¯èƒ½ãªå¤šæ•°ã®ãƒ‰ã‚ュメントを +ã‚‚ã£ã¦ã„ã¾ã™ã€‚ã“ã‚Œã«ã¯ã‚«ãƒ¼ãƒãƒ«å†…APIã®å®Œå…¨ãªè¨˜è¿°ã‚„ã€æ£ã—ããƒãƒƒã‚¯ã‚’ã‹ã‘ +ã‚‹ãŸã‚ã®è¦å‰‡ãªã©ãŒå«ã¾ã‚Œã¾ã™ã€‚ + +ã“れら全ã¦ã®ãƒ‰ã‚ュメントを PDF ã‚„ HTML ã§ç”Ÿæˆã™ã‚‹ã«ã¯ä»¥ä¸‹ã‚’実行ã—ã¾ã™ - :: + + make pdfdocs + make htmldocs + +ãã‚Œãžã‚Œãƒ¡ã‚¤ãƒ³ã‚«ãƒ¼ãƒãƒ«ã®ã‚½ãƒ¼ã‚¹ãƒ‡ã‚£ãƒ¬ã‚¯ãƒˆãƒªã‹ã‚‰å®Ÿè¡Œã—ã¾ã™ã€‚ + +ReSTマークアップを使ã£ãŸãƒ‰ã‚ュメント㯠Documentation/outputã«ç”Ÿæˆã•ã‚Œ +ã¾ã™ã€‚Latex ã¨ePub å½¢å¼ã§ç”Ÿæˆã™ã‚‹ã«ã¯ - :: + + make latexdocs + make epubdocs + +ç¾åœ¨ã€å¹¾ã¤ã‹ã® DocBookå½¢å¼ã§æ›¸ã‹ã‚ŒãŸãƒ‰ã‚ュメント㯠ReSTå½¢å¼ã«è»¢æ›ä¸ã§ +ã™ã€‚ãれらã®ãƒ‰ã‚ュメントã¯Documentation/DocBook ディレクトリã«ç”Ÿæˆã•ã‚Œã€ +Postscript ã¾ãŸã¯ man ページã®å½¢å¼ã‚’生æˆã™ã‚‹ã«ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ã—ã¾ã™ - :: + + make psdocs + make mandocs カーãƒãƒ«é–‹ç™ºè€…ã«ãªã‚‹ã«ã¯ ---------------------------- +------------------------ -ã‚‚ã—ã‚ãªãŸãŒã€Linux カーãƒãƒ«é–‹ç™ºã«ã¤ã„ã¦ä½•ã‚‚知らãªã„ãªã‚‰ã°ã€ +ã‚‚ã—ã‚ãªãŸãŒã€Linux カーãƒãƒ«é–‹ç™ºã«ã¤ã„ã¦ä½•ã‚‚知らãªã„ã®ãªã‚‰ã°ã€ KernelNewbies プãƒã‚¸ã‚§ã‚¯ãƒˆã‚’見るã¹ãã§ã™ - http://kernelnewbies.org + + https://kernelnewbies.org ã“ã®ã‚µã‚¤ãƒˆã«ã¯å½¹ã«ç«‹ã¤ãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ãƒˆãŒã‚ã‚Šã€åŸºæœ¬çš„ãªã‚«ãƒ¼ãƒãƒ«é–‹ç™ºã«é–¢ ã™ã‚‹ã»ã¨ã‚“ã©ã©ã‚“ãªç¨®é¡žã®è³ªå•ã‚‚ã§ãã¾ã™ (æ—¢ã«å›žç”ã•ã‚Œã¦ã„るよã†ãªã“ã¨ã‚’ -èžãå‰ã«ã¾ãšã¯ã‚¢ãƒ¼ã‚«ã‚¤ãƒ–を調ã¹ã¦ãã ã•ã„)。 -ã¾ãŸã“ã“ã«ã¯ã€ãƒªã‚¢ãƒ«ã‚¿ã‚¤ãƒ ã§è³ªå•ã‚’èžãã“ã¨ãŒã§ãã‚‹ IRC ãƒãƒ£ãƒãƒ«ã‚„ã€Linux -カーãƒãƒ«ã®é–‹ç™ºã«é–¢ã—ã¦å¦ã¶ã®ã«ä¾¿åˆ©ãªãŸãã•ã‚“ã®å½¹ã«ç«‹ã¤ãƒ‰ã‚ュメントãŒã‚ -ã‚Šã¾ã™ã€‚ +èžãå‰ã«ã¾ãšã¯ã‚¢ãƒ¼ã‚«ã‚¤ãƒ–を調ã¹ã¦ãã ã•ã„)。ã¾ãŸã“ã“ã«ã¯ã€ãƒªã‚¢ãƒ«ã‚¿ã‚¤ãƒ +ã§è³ªå•ã‚’èžãã“ã¨ãŒã§ãã‚‹ IRC ãƒãƒ£ãƒãƒ«ã‚„ã€Linuxカーãƒãƒ«ã®é–‹ç™ºã«é–¢ã—ã¦å¦ +ã¶ã®ã«ä¾¿åˆ©ãªãŸãã•ã‚“ã®å½¹ã«ç«‹ã¤ãƒ‰ã‚ュメントãŒã‚ã‚Šã¾ã™ã€‚ -web サイトã«ã¯ã€ã‚³ãƒ¼ãƒ‰ã®æ§‹æˆã€ã‚µãƒ–システムã€ç¾åœ¨å˜åœ¨ã™ã‚‹ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆ(ツ -リーã«ã‚ã‚‹ã‚‚ã®ç„¡ã„ã‚‚ã®ã®ä¸¡æ–¹)ã®åŸºæœ¬çš„ãªç®¡ç†æƒ…å ±ãŒã‚ã‚Šã¾ã™ã€‚ -ã“ã“ã«ã¯ã€ã¾ãŸã€ã‚«ãƒ¼ãƒãƒ«ã®ã‚³ãƒ³ãƒ‘イルã®ã‚„り方やパッãƒã®å½“ã¦æ–¹ãªã©ã®é–“接 -çš„ãªåŸºæœ¬æƒ…å ±ã‚‚è¨˜è¿°ã•ã‚Œã¦ã„ã¾ã™ã€‚ +Web サイトã«ã¯ã€ã‚³ãƒ¼ãƒ‰ã®æ§‹æˆã€ã‚µãƒ–システムã€ç¾åœ¨å˜åœ¨ã™ã‚‹ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆ +(ツリーã«ã‚ã‚‹ã‚‚ã®ç„¡ã„ã‚‚ã®ã®ä¸¡æ–¹)ã®åŸºæœ¬çš„ãªç®¡ç†æƒ…å ±ãŒã‚ã‚Šã¾ã™ã€‚ã“ã“ã«ã¯ã€ +ã¾ãŸã€ã‚«ãƒ¼ãƒãƒ«ã®ã‚³ãƒ³ãƒ‘イルã®ã‚„り方やパッãƒã®å½“ã¦æ–¹ãªã©ã®é–“接的ãªåŸºæœ¬æƒ… +å ±ã‚‚è¨˜è¿°ã•ã‚Œã¦ã„ã¾ã™ã€‚ ã‚ãªãŸãŒã©ã“ã‹ã‚‰ã‚¹ã‚¿ãƒ¼ãƒˆã—ã¦è‰¯ã„ã‹ã‚ã‹ã‚‰ãªã„ãŒã€Linux カーãƒãƒ«é–‹ç™ºã‚³ãƒŸãƒ¥ -ニティã«å‚åŠ ã—ã¦ä½•ã‹ã™ã‚‹ã“ã¨ã‚’ã•ãŒã—ã¦ã„ã‚‹å ´åˆã«ã¯ã€Linux kernel +ニティã«å‚åŠ ã—ã¦ä½•ã‹ã™ã‚‹ã“ã¨ã‚’ã•ãŒã—ã¦ã„ã‚‹ã®ã§ã‚ã‚Œã°ã€Linux kernel Janitor's プãƒã‚¸ã‚§ã‚¯ãƒˆã«ã„ã‘ã°è‰¯ã„ã§ã—ょㆠ- - http://kernelnewbies.org/KernelJanitors + + https://kernelnewbies.org/KernelJanitors + ã“ã“ã¯ãã®ã‚ˆã†ãªã‚¹ã‚¿ãƒ¼ãƒˆã‚’ã™ã‚‹ã®ã«ã†ã£ã¦ã¤ã‘ã®å ´æ‰€ã§ã™ã€‚ã“ã“ã«ã¯ã€ Linux カーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã®ä¸ã«å«ã¾ã‚Œã‚‹ã€ãã‚Œã„ã«ã—ã€ä¿®æ£ã—ãªã‘ã‚Œã°ãª らãªã„ã€å˜ç´”ãªå•é¡Œã®ãƒªã‚¹ãƒˆãŒè¨˜è¿°ã•ã‚Œã¦ã„ã¾ã™ã€‚ã“ã®ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆã«é–¢ã‚ã‚‹ @@ -232,10 +237,11 @@ Linux カーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã®ä¸ã«å«ã¾ã‚Œã‚‹ã€ãã‚Œã„ã«ã—ã€ä¿ ã¦ã„ãªã„å ´åˆã«ã¯ã€æ¬¡ã«ã‚„る仕事ã®æ–¹å‘性ãŒè¦‹ãˆã¦ãã‚‹ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。 ã‚‚ã—ã‚ãªãŸãŒã€ã™ã§ã«ã²ã¨ã¾ã¨ã¾ã‚Šã‚³ãƒ¼ãƒ‰ã‚’書ã„ã¦ã„ã¦ã€ã‚«ãƒ¼ãƒãƒ«ãƒ„リーã«å…¥ -ã‚ŒãŸã„ã¨æ€ã£ã¦ã„ãŸã‚Šã€ãã‚Œã«é–¢ã™ã‚‹é©åˆ‡ãªæ”¯æ´ã‚’求ã‚ãŸã„å ´åˆã€ã‚«ãƒ¼ãƒãƒ« -メンターズプãƒã‚¸ã‚§ã‚¯ãƒˆã¯ãã®ã‚ˆã†ãªçš†ã•ã‚“を助ã‘ã‚‹ãŸã‚ã«ã§ãã¾ã—ãŸã€‚ -ã“ã“ã«ã¯ãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ãƒˆãŒã‚ã‚Šã€ä»¥ä¸‹ã‹ã‚‰å‚ç…§ã§ãã¾ã™ - http://selenic.com/mailman/listinfo/kernel-mentors +ã‚ŒãŸã„ã¨æ€ã£ã¦ã„ãŸã‚Šã€ãã‚Œã«é–¢ã™ã‚‹é©åˆ‡ãªæ”¯æ´ã‚’求ã‚ãŸã„å ´åˆã€ã‚«ãƒ¼ãƒãƒ«ãƒ¡ +ンターズプãƒã‚¸ã‚§ã‚¯ãƒˆã¯ãã®ã‚ˆã†ãªçš†ã•ã‚“を助ã‘ã‚‹ãŸã‚ã«ã§ãã¾ã—ãŸã€‚ã“ã“ã« +ã¯ãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ãƒˆãŒã‚ã‚Šã€ä»¥ä¸‹ã‹ã‚‰å‚ç…§ã§ãã¾ã™ - + + https://selenic.com/mailman/listinfo/kernel-mentors 実際㫠Linux カーãƒãƒ«ã®ã‚³ãƒ¼ãƒ‰ã«ã¤ã„ã¦ä¿®æ£ã‚’åŠ ãˆã‚‹å‰ã«ã€ã©ã†ã‚„ã£ã¦ã㮠コードãŒå‹•ä½œã™ã‚‹ã®ã‹ã‚’ç†è§£ã™ã‚‹ã“ã¨ãŒå¿…è¦ã§ã™ã€‚ãã®ãŸã‚ã«ã¯ã€ç‰¹åˆ¥ãªãƒ„ー @@ -244,27 +250,29 @@ Linux カーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ„リーã®ä¸ã«å«ã¾ã‚Œã‚‹ã€ãã‚Œã„ã«ã—ã€ä¿ 特ã«ãŠã™ã™ã‚ãªã®ã¯ã€Linux クãƒã‚¹ãƒªãƒ•ã‚¡ãƒ¬ãƒ³ã‚¹ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆã§ã™ã€‚ã“ã‚Œã¯ã€ 自己å‚照方å¼ã§ã€ç´¢å¼•ãŒã¤ã„㟠web å½¢å¼ã§ã€ã‚½ãƒ¼ã‚¹ã‚³ãƒ¼ãƒ‰ã‚’å‚ç…§ã™ã‚‹ã“ã¨ãŒ ã§ãã¾ã™ã€‚ã“ã®æœ€æ–°ã®ç´ æ™´ã—ã„カーãƒãƒ«ã‚³ãƒ¼ãƒ‰ã®ãƒªãƒã‚¸ãƒˆãƒªã¯ä»¥ä¸‹ã§è¦‹ã¤ã‹ã‚Š -ã¾ã™- +ã¾ã™ - + http://lxr.free-electrons.com/ 開発プãƒã‚»ã‚¹ ------------------------ +------------ Linux カーãƒãƒ«ã®é–‹ç™ºãƒ—ãƒã‚»ã‚¹ã¯ç¾åœ¨å¹¾ã¤ã‹ã®ç•°ãªã‚‹ãƒ¡ã‚¤ãƒ³ã‚«ãƒ¼ãƒãƒ«ã€Œãƒ–ラン -ãƒã€ã¨å¤šæ•°ã®ã‚µãƒ–システム毎ã®ã‚«ãƒ¼ãƒãƒ«ãƒ–ランãƒã‹ã‚‰æ§‹æˆã•ã‚Œã¾ã™ã€‚ -ã“れらã®ãƒ–ランãƒã¨ã¯- - - メイン㮠3.x カーãƒãƒ«ãƒ„リー - - 3.x.y -stable カーãƒãƒ«ãƒ„リー - - 3.x -git カーãƒãƒ«ãƒ‘ッム+ãƒã€ã¨å¤šæ•°ã®ã‚µãƒ–システム毎ã®ã‚«ãƒ¼ãƒãƒ«ãƒ–ランãƒã‹ã‚‰æ§‹æˆã•ã‚Œã¾ã™ã€‚ã“れら㮠+ブランãƒã¨ã¯ - + + - メイン㮠4.x カーãƒãƒ«ãƒ„リー + - 4.x.y -stable カーãƒãƒ«ãƒ„リー + - 4.x -git カーãƒãƒ«ãƒ‘ッム- サブシステム毎ã®ã‚«ãƒ¼ãƒãƒ«ãƒ„リーã¨ãƒ‘ッム- - çµ±åˆãƒ†ã‚¹ãƒˆã®ãŸã‚ã® 3.x -next カーãƒãƒ«ãƒ„リー + - çµ±åˆãƒ†ã‚¹ãƒˆã®ãŸã‚ã® 4.x -next カーãƒãƒ«ãƒ„リー -3.x カーãƒãƒ«ãƒ„リー ------------------ +4.x カーãƒãƒ«ãƒ„リー +~~~~~~~~~~~~~~~~~~ -3.x カーãƒãƒ«ã¯ Linus Torvalds ã«ã‚ˆã£ã¦ãƒ¡ãƒ³ãƒ†ãƒŠãƒ³ã‚¹ã•ã‚Œã€kernel.org -ã® pub/linux/kernel/v3.x/ ディレクトリã«å˜åœ¨ã—ã¾ã™ã€‚ã“ã®é–‹ç™ºãƒ—ãƒã‚»ã‚¹ã¯ -以下ã®ã¨ãŠã‚Š- +4.x カーãƒãƒ«ã¯ Linus Torvalds ã«ã‚ˆã£ã¦ãƒ¡ãƒ³ãƒ†ãƒŠãƒ³ã‚¹ã•ã‚Œã€ +https://kernel.org ã® pub/linux/kernel/v4.x/ ディレクトリã«å˜åœ¨ã—ã¾ã™ã€‚ +ã“ã®é–‹ç™ºãƒ—ãƒã‚»ã‚¹ã¯ä»¥ä¸‹ã®ã¨ãŠã‚Š - - æ–°ã—ã„カーãƒãƒ«ãŒãƒªãƒªãƒ¼ã‚¹ã•ã‚ŒãŸç›´å¾Œã«ã€2週間ã®ç‰¹åˆ¥æœŸé–“ãŒè¨ã‘られ〠ã“ã®æœŸé–“ä¸ã«ã€ãƒ¡ãƒ³ãƒ†ãƒŠé”㯠Linus ã«å¤§ããªå·®åˆ†ã‚’é€ã‚‹ã“ã¨ãŒã§ãã¾ã™ã€‚ @@ -272,7 +280,6 @@ Linux カーãƒãƒ«ã®é–‹ç™ºãƒ—ãƒã‚»ã‚¹ã¯ç¾åœ¨å¹¾ã¤ã‹ã®ç•°ãªã‚‹ãƒ¡ã‚¤ãƒ³ã‚ 大ããªå¤‰æ›´ã¯ git(カーãƒãƒ«ã®ã‚½ãƒ¼ã‚¹ç®¡ç†ãƒ„ールã€è©³ç´°ã¯ http://git-scm.com/ å‚ç…§) を使ã£ã¦é€ã‚‹ã®ãŒå¥½ã¾ã—ã„ã‚„ã‚Šæ–¹ã§ã™ãŒã€ãƒ‘ッ ãƒãƒ•ã‚¡ã‚¤ãƒ«ã®å½¢å¼ã®ã¾ã¾é€ã‚‹ã®ã§ã‚‚å分ã§ã™ã€‚ - - 2週間後ã€-rc1 カーãƒãƒ«ãŒãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã€ã“ã®å¾Œã«ã¯ã‚«ãƒ¼ãƒãƒ«å…¨ä½“ã®å®‰å®š 性ã«å½±éŸ¿ã‚’ã‚ãŸãˆã‚‹ã‚ˆã†ãªæ–°æ©Ÿèƒ½ã¯å«ã¾ãªã„é¡žã®ãƒ‘ッãƒã—ã‹å–り込むã“㨠ã¯ã§ãã¾ã›ã‚“。新ã—ã„ドライãƒ(ã‚‚ã—ãã¯ãƒ•ã‚¡ã‚¤ãƒ«ã‚·ã‚¹ãƒ†ãƒ )ã®ãƒ‘ッãƒã¯ @@ -282,44 +289,45 @@ Linux カーãƒãƒ«ã®é–‹ç™ºãƒ—ãƒã‚»ã‚¹ã¯ç¾åœ¨å¹¾ã¤ã‹ã®ç•°ãªã‚‹ãƒ¡ã‚¤ãƒ³ã‚ Linus ã¸ãƒ‘ッãƒã‚’é€ä»˜ã™ã‚‹ã®ã« git を使ã†ã“ã¨ã‚‚ã§ãã¾ã™ãŒã€ãƒ‘ッãƒã¯ レビューã®ãŸã‚ã«ã€ãƒ‘ブリックãªãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ãƒˆã¸ã‚‚åŒæ™‚ã«é€ã‚‹å¿…è¦ãŒ ã‚ã‚Šã¾ã™ã€‚ - - æ–°ã—ã„ -rc 㯠Linus ãŒã€æœ€æ–°ã® git ツリーãŒãƒ†ã‚¹ãƒˆç›®çš„ã§ã‚ã‚Œã°å分 ã«å®‰å®šã—ãŸçŠ¶æ…‹ã«ã‚ã‚‹ã¨åˆ¤æ–ã—ãŸã¨ãã«ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã¾ã™ã€‚目標ã¯æ¯Žé€±æ–° ã—ã„ -rc カーãƒãƒ«ã‚’リリースã™ã‚‹ã“ã¨ã§ã™ã€‚ - - ã“ã®ãƒ—ãƒã‚»ã‚¹ã¯ã‚«ãƒ¼ãƒãƒ«ãŒ 「準備ãŒã§ããŸã€ã¨è€ƒãˆã‚‰ã‚Œã‚‹ã¾ã§ç¶™ç¶šã—ã¾ ã™ã€‚ã“ã®ãƒ—ãƒã‚»ã‚¹ã¯ã ã„ãŸã„ 6週間継続ã—ã¾ã™ã€‚ Andrew Morton ㌠Linux-kernel メーリングリストã«ã‚«ãƒ¼ãƒãƒ«ãƒªãƒªãƒ¼ã‚¹ã«ã¤ã„ -ã¦æ›¸ã„ãŸã“ã¨ã‚’ã“ã“ã§è¨€ã£ã¦ãŠãã“ã¨ã¯ä¾¡å€¤ãŒã‚ã‚Šã¾ã™- - 「カーãƒãƒ«ãŒã„ã¤ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã‚‹ã‹ã¯èª°ã‚‚知りã¾ã›ã‚“。ãªãœãªã‚‰ã€ã“ã‚Œã¯ç¾ - 実ã«èªè˜ã•ã‚ŒãŸãƒã‚°ã®çŠ¶æ³ã«ã‚ˆã‚Šãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã‚‹ã®ã§ã‚ã‚Šã€å‰ã‚‚ã£ã¦æ±ºã‚ら - ã‚ŒãŸè¨ˆç”»ã«ã‚ˆã£ã¦ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã‚‹ã‚‚ã®ã§ã¯ãªã„ã‹ã‚‰ã§ã™ã€‚〠+ã¦æ›¸ã„ãŸã“ã¨ã‚’ã“ã“ã§è¨€ã£ã¦ãŠãã“ã¨ã¯ä¾¡å€¤ãŒã‚ã‚Šã¾ã™ - + + *「カーãƒãƒ«ãŒã„ã¤ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã‚‹ã‹ã¯èª°ã‚‚知りã¾ã›ã‚“。ãªãœãªã‚‰ã€ + ã“ã‚Œã¯ç¾å®Ÿã«èªè˜ã•ã‚ŒãŸãƒã‚°ã®çŠ¶æ³ã«ã‚ˆã‚Šãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã‚‹ã®ã§ã‚り〠+ å‰ã‚‚ã£ã¦æ±ºã‚られãŸè¨ˆç”»ã«ã‚ˆã£ã¦ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã‚‹ã‚‚ã®ã§ã¯ãªã„ã‹ã‚‰ + ã§ã™ã€‚ã€* -3.x.y -stable カーãƒãƒ«ãƒ„リー ---------------------------- +4.x.y -stable カーãƒãƒ«ãƒ„リー +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ãƒãƒ¼ã‚¸ãƒ§ãƒ³ç•ªå·ãŒ3ã¤ã®æ•°å—ã«åˆ†ã‹ã‚Œã¦ã„るカーãƒãƒ«ã¯ -stable カーãƒãƒ«ã§ã™ã€‚ -ã“ã‚Œã«ã¯ã€3.x カーãƒãƒ«ã§è¦‹ã¤ã‹ã£ãŸã‚»ã‚ュリティå•é¡Œã‚„é‡å¤§ãªå¾Œæˆ»ã‚Šã«å¯¾ -ã™ã‚‹æ¯”較的å°ã•ã„é‡è¦ãªä¿®æ£ãŒå«ã¾ã‚Œã¾ã™ã€‚ +ã“ã‚Œã«ã¯ã€4.x カーãƒãƒ«ã§è¦‹ã¤ã‹ã£ãŸã‚»ã‚ュリティå•é¡Œã‚„é‡å¤§ãªå¾Œæˆ»ã‚Šã«å¯¾ã™ +る比較的å°ã•ã„é‡è¦ãªä¿®æ£ãŒå«ã¾ã‚Œã¾ã™ã€‚ -ã“ã‚Œã¯ã€é–‹ç™º/実験的ãƒãƒ¼ã‚¸ãƒ§ãƒ³ã®ãƒ†ã‚¹ãƒˆã«å”力ã™ã‚‹ã“ã¨ã«èˆˆå‘³ãŒç„¡ã〠-最新ã®å®‰å®šã—ãŸã‚«ãƒ¼ãƒãƒ«ã‚’使ã„ãŸã„ユーザã«æŽ¨å¥¨ã™ã‚‹ãƒ–ランãƒã§ã™ã€‚ +ã“ã‚Œã¯ã€é–‹ç™º/実験的ãƒãƒ¼ã‚¸ãƒ§ãƒ³ã®ãƒ†ã‚¹ãƒˆã«å”力ã™ã‚‹ã“ã¨ã«èˆˆå‘³ãŒç„¡ãã€æœ€æ–° +ã®å®‰å®šã—ãŸã‚«ãƒ¼ãƒãƒ«ã‚’使ã„ãŸã„ユーザã«æŽ¨å¥¨ã™ã‚‹ãƒ–ランãƒã§ã™ã€‚ -ã‚‚ã—ã€3.x.y カーãƒãƒ«ãŒå˜åœ¨ã—ãªã„å ´åˆã«ã¯ã€ç•ªå·ãŒä¸€ç•ªå¤§ãã„ 3.x ㌠-最新ã®å®‰å®šç‰ˆã‚«ãƒ¼ãƒãƒ«ã§ã™ã€‚ +ã‚‚ã—ã€4.x.y カーãƒãƒ«ãŒå˜åœ¨ã—ãªã„å ´åˆã«ã¯ã€ç•ªå·ãŒä¸€ç•ªå¤§ãã„ 4.x ãŒæœ€æ–° +ã®å®‰å®šç‰ˆã‚«ãƒ¼ãƒãƒ«ã§ã™ã€‚ -3.x.y 㯠"stable" ãƒãƒ¼ãƒ <stable@vger.kernel.org> ã§ãƒ¡ãƒ³ãƒ†ã•ã‚Œã¦ãŠã‚Šã€å¿… -è¦ã«å¿œã˜ã¦ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã¾ã™ã€‚通常ã®ãƒªãƒªãƒ¼ã‚¹æœŸé–“㯠2週間毎ã§ã™ãŒã€å·®ã—迫㣠-ãŸå•é¡ŒãŒãªã‘ã‚Œã°ã‚‚ã†å°‘ã—é•·ããªã‚‹ã“ã¨ã‚‚ã‚ã‚Šã¾ã™ã€‚ã‚»ã‚ュリティ関連ã®å•é¡Œ -ã®å ´åˆã¯ã“ã‚Œã«å¯¾ã—ã¦ã ã„ãŸã„ã®å ´åˆã€ã™ãã«ãƒªãƒªãƒ¼ã‚¹ãŒã•ã‚Œã¾ã™ã€‚ +4.x.y 㯠"stable" ãƒãƒ¼ãƒ <stable@vger.kernel.org> ã§ãƒ¡ãƒ³ãƒ†ã•ã‚Œã¦ãŠã‚Šã€ +å¿…è¦ã«å¿œã˜ã¦ãƒªãƒªãƒ¼ã‚¹ã•ã‚Œã¾ã™ã€‚通常ã®ãƒªãƒªãƒ¼ã‚¹æœŸé–“㯠2週間毎ã§ã™ãŒã€å·® +ã—è¿«ã£ãŸå•é¡ŒãŒãªã‘ã‚Œã°ã‚‚ã†å°‘ã—é•·ããªã‚‹ã“ã¨ã‚‚ã‚ã‚Šã¾ã™ã€‚ã‚»ã‚ュリティ関 +連ã®å•é¡Œã®å ´åˆã¯ã“ã‚Œã«å¯¾ã—ã¦ã ã„ãŸã„ã®å ´åˆã€ã™ãã«ãƒªãƒªãƒ¼ã‚¹ãŒã•ã‚Œã¾ã™ã€‚ -カーãƒãƒ«ãƒ„リーã«å…¥ã£ã¦ã„ã‚‹ã€Documentation/process/stable-kernel-rules.rst ファ -イルã«ã¯ã©ã®ã‚ˆã†ãªç¨®é¡žã®å¤‰æ›´ãŒ -stable ツリーã«å—ã‘入れå¯èƒ½ã‹ã€ã¾ãŸãƒª -リースプãƒã‚»ã‚¹ãŒã©ã†å‹•ãã‹ãŒè¨˜è¿°ã•ã‚Œã¦ã„ã¾ã™ã€‚ +カーãƒãƒ«ãƒ„リーã«å…¥ã£ã¦ã„る〠+Documentation/process/stable-kernel-rules.rst ファイルã«ã¯ã©ã®ã‚ˆã†ãªç¨® +é¡žã®å¤‰æ›´ãŒ -stable ツリーã«å—ã‘入れå¯èƒ½ã‹ã€ã¾ãŸãƒªãƒªãƒ¼ã‚¹ãƒ—ãƒã‚»ã‚¹ãŒã©ã† +å‹•ãã‹ãŒè¨˜è¿°ã•ã‚Œã¦ã„ã¾ã™ã€‚ -3.x -git パッム------------------- +4.x -git パッム+~~~~~~~~~~~~~~~ git リãƒã‚¸ãƒˆãƒªã§ç®¡ç†ã•ã‚Œã¦ã„ã‚‹Linus ã®ã‚«ãƒ¼ãƒãƒ«ãƒ„リーã®æ¯Žæ—¥ã®ã‚¹ãƒŠãƒƒãƒ— ショットãŒã‚ã‚Šã¾ã™ã€‚(ã ã‹ã‚‰ -git ã¨ã„ã†åå‰ãŒã¤ã„ã¦ã„ã¾ã™)。ã“れらã®ãƒ‘ッ @@ -328,7 +336,7 @@ git リãƒã‚¸ãƒˆãƒªã§ç®¡ç†ã•ã‚Œã¦ã„ã‚‹Linus ã®ã‚«ãƒ¼ãƒãƒ«ãƒ„リーã®æ¯Žæ ã«ç”Ÿæˆã•ã‚Œã‚‹ã®ã§ã€ã‚ˆã‚Šå®Ÿé¨“çš„ã§ã™ã€‚ サブシステム毎ã®ã‚«ãƒ¼ãƒãƒ«ãƒ„リーã¨ãƒ‘ッム-------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ãã‚Œãžã‚Œã®ã‚«ãƒ¼ãƒãƒ«ã‚µãƒ–システムã®ãƒ¡ãƒ³ãƒ†ãƒŠé”㯠--- ãã—ã¦å¤šãã®ã‚«ãƒ¼ãƒãƒ« サブシステムã®é–‹ç™ºè€…é”ã‚‚ --- å„自ã®æœ€æ–°ã®é–‹ç™ºçŠ¶æ³ã‚’ソースリãƒã‚¸ãƒˆãƒªã« @@ -340,42 +348,45 @@ git リãƒã‚¸ãƒˆãƒªã§ç®¡ç†ã•ã‚Œã¦ã„ã‚‹Linus ã®ã‚«ãƒ¼ãƒãƒ«ãƒ„リーã®æ¯Žæ 大部分ã®ã“れらã®ãƒªãƒã‚¸ãƒˆãƒªã¯ git ツリーã§ã™ã€‚ã—ã‹ã—ãã®ä»–ã® SCM ã‚„ quilt シリーズã¨ã—ã¦å…¬é–‹ã•ã‚Œã¦ã„るパッãƒã‚ューも使ã‚ã‚Œã¦ã„ã¾ã™ã€‚ã“れら ã®ã‚µãƒ–システムリãƒã‚¸ãƒˆãƒªã®ã‚¢ãƒ‰ãƒ¬ã‚¹ã¯ MAINTAINERS ファイルã«ãƒªã‚¹ãƒˆã•ã‚Œ -ã¦ã„ã¾ã™ã€‚ã“れらã®å¤šã㯠http://git.kernel.org/ ã§å‚ç…§ã™ã‚‹ã“ã¨ãŒã§ãã¾ +ã¦ã„ã¾ã™ã€‚ã“れらã®å¤šã㯠https://git.kernel.org/ ã§å‚ç…§ã™ã‚‹ã“ã¨ãŒã§ãã¾ ã™ã€‚ æ案ã•ã‚ŒãŸãƒ‘ッãƒãŒã“ã®ã‚ˆã†ãªã‚µãƒ–システムツリーã«ã‚³ãƒŸãƒƒãƒˆã•ã‚Œã‚‹å‰ã«ã€ãƒ¡ãƒ¼ リングリストã§äº‹å‰ã«ãƒ¬ãƒ“ューã«ã‹ã‘られã¾ã™ï¼ˆä»¥ä¸‹ã®å¯¾å¿œã™ã‚‹ã‚»ã‚¯ã‚·ãƒ§ãƒ³ã‚’ -å‚照）。ã„ãã¤ã‹ã®ã‚«ãƒ¼ãƒãƒ«ã‚µãƒ–システムã§ã¯ã€ã“ã®ãƒ¬ãƒ“ュー㯠patchwork -ã¨ã„ã†ãƒ„ールã«ã‚ˆã£ã¦è¿½è·¡ã•ã‚Œã¾ã™ã€‚Patchwork 㯠web インターフェイス㫠-よã£ã¦ãƒ‘ッãƒæŠ•ç¨¿ã®è¡¨ç¤ºã€ãƒ‘ッãƒã¸ã®ã‚³ãƒ¡ãƒ³ãƒˆä»˜ã‘や改訂ãªã©ãŒã§ãã€ãã—㦠-メンテナã¯ãƒ‘ッãƒã«å¯¾ã—ã¦ã€ãƒ¬ãƒ“ューä¸ã€å—付済ã¿ã€æ‹’å¦ã¨ã„ã†ã‚ˆã†ãªãƒžãƒ¼ã‚¯ -ã‚’ã¤ã‘ã‚‹ã“ã¨ãŒã§ãã¾ã™ã€‚大部分ã®ã“れら㮠patchwork ã®ã‚µã‚¤ãƒˆã¯ -http://patchwork.kernel.org/ ã§ãƒªã‚¹ãƒˆã•ã‚Œã¦ã„ã¾ã™ã€‚ - -çµ±åˆãƒ†ã‚¹ãƒˆã®ãŸã‚ã® 3.x -next カーãƒãƒ«ãƒ„リー ---------------------------------------------- - -サブシステムツリーã®æ›´æ–°å†…容ãŒãƒ¡ã‚¤ãƒ³ãƒ©ã‚¤ãƒ³ã® 3.x ツリーã«ãƒžãƒ¼ã‚¸ã•ã‚Œ -ã‚‹å‰ã«ã€ãれらã¯çµ±åˆãƒ†ã‚¹ãƒˆã•ã‚Œã‚‹å¿…è¦ãŒã‚ã‚Šã¾ã™ã€‚ã“ã®ç›®çš„ã®ãŸã‚ã€å®Ÿè³ªçš„ -ã«å…¨ã‚µãƒ–システムツリーã‹ã‚‰ã»ã¼æ¯Žæ—¥ãƒ—ルã•ã‚Œã¦ã§ãる特別ãªãƒ†ã‚¹ãƒˆç”¨ã®ãƒª -ãƒã‚¸ãƒˆãƒªãŒå˜åœ¨ã—ã¾ã™- - http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git +å‚照）。ã„ãã¤ã‹ã®ã‚«ãƒ¼ãƒãƒ«ã‚µãƒ–システムã§ã¯ã€ã“ã®ãƒ¬ãƒ“ュー㯠patchwork㨠+ã„ã†ãƒ„ールã«ã‚ˆã£ã¦è¿½è·¡ã•ã‚Œã¾ã™ã€‚Patchwork 㯠web インターフェイスã«ã‚ˆã£ +ã¦ãƒ‘ッãƒæŠ•ç¨¿ã®è¡¨ç¤ºã€ãƒ‘ッãƒã¸ã®ã‚³ãƒ¡ãƒ³ãƒˆä»˜ã‘や改訂ãªã©ãŒã§ãã€ãã—ã¦ãƒ¡ãƒ³ +テナã¯ãƒ‘ッãƒã«å¯¾ã—ã¦ã€ãƒ¬ãƒ“ューä¸ã€å—付済ã¿ã€æ‹’å¦ã¨ã„ã†ã‚ˆã†ãªãƒžãƒ¼ã‚¯ã‚’㤠+ã‘ã‚‹ã“ã¨ãŒã§ãã¾ã™ã€‚大部分ã®ã“れら㮠patchwork ã®ã‚µã‚¤ãƒˆã¯ +https://patchwork.kernel.org/ ã§ãƒªã‚¹ãƒˆã•ã‚Œã¦ã„ã¾ã™ã€‚ + +çµ±åˆãƒ†ã‚¹ãƒˆã®ãŸã‚ã® 4.x -next カーãƒãƒ«ãƒ„リー +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サブシステムツリーã®æ›´æ–°å†…容ãŒãƒ¡ã‚¤ãƒ³ãƒ©ã‚¤ãƒ³ã® 4.x ツリーã«ãƒžãƒ¼ã‚¸ã•ã‚Œã‚‹ +å‰ã«ã€ãれらã¯çµ±åˆãƒ†ã‚¹ãƒˆã•ã‚Œã‚‹å¿…è¦ãŒã‚ã‚Šã¾ã™ã€‚ã“ã®ç›®çš„ã®ãŸã‚ã€å®Ÿè³ªçš„ã« +全サブシステムツリーã‹ã‚‰ã»ã¼æ¯Žæ—¥ãƒ—ルã•ã‚Œã¦ã§ãる特別ãªãƒ†ã‚¹ãƒˆç”¨ã®ãƒªãƒã‚¸ +トリãŒå˜åœ¨ã—ã¾ã™- + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git ã“ã®ã‚„ã‚Šæ–¹ã«ã‚ˆã£ã¦ã€-next カーãƒãƒ«ã¯æ¬¡ã®ãƒžãƒ¼ã‚¸æ©Ÿä¼šã§ã©ã‚“ãªã‚‚ã®ãŒãƒ¡ã‚¤ãƒ³ -ラインカーãƒãƒ«ã«ãƒžãƒ¼ã‚¸ã•ã‚Œã‚‹ã‹ã€ãŠãŠã¾ã‹ãªã®å±•æœ›ã‚’æä¾›ã—ã¾ã™ã€‚-next -カーãƒãƒ«ã®å®Ÿè¡Œãƒ†ã‚¹ãƒˆã‚’è¡Œã†å†’険好ããªãƒ†ã‚¹ã‚¿ãƒ¼ã¯å¤§ã„ã«æ“è¿Žã•ã‚Œã¾ã™ +ラインカーãƒãƒ«ã«ãƒžãƒ¼ã‚¸ã•ã‚Œã‚‹ã‹ã€ãŠãŠã¾ã‹ãªã®å±•æœ›ã‚’æä¾›ã—ã¾ã™ã€‚-next カー +ãƒãƒ«ã®å®Ÿè¡Œãƒ†ã‚¹ãƒˆã‚’è¡Œã†å†’険好ããªãƒ†ã‚¹ã‚¿ãƒ¼ã¯å¤§ã„ã«æ“è¿Žã•ã‚Œã¾ã™ã€‚ ãƒã‚°ãƒ¬ãƒãƒ¼ãƒˆ ------------- -bugzilla.kernel.org 㯠Linux カーãƒãƒ«é–‹ç™ºè€…ãŒã‚«ãƒ¼ãƒãƒ«ã®ãƒã‚°ã‚’追跡ã™ã‚‹ -å ´æ‰€ã§ã™ã€‚ユーザã¯è¦‹ã¤ã‘ãŸãƒã‚°ã®å…¨ã¦ã‚’ã“ã®ãƒ„ールã§å ±å‘Šã™ã¹ãã§ã™ã€‚ -ã©ã† kernel bugzilla を使ã†ã‹ã®è©³ç´°ã¯ã€ä»¥ä¸‹ã‚’å‚ç…§ã—ã¦ãã ã•ã„- - http://bugzilla.kernel.org/page.cgi?id=faq.html -メインカーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ‡ã‚£ãƒ¬ã‚¯ãƒˆãƒªã«ã‚るファイル admin-guide/reporting-bugs.rst ã¯ã‚«ãƒ¼ãƒ -ルãƒã‚°ã‚‰ã—ã„ã‚‚ã®ã«ã¤ã„ã¦ã©ã†ãƒ¬ãƒãƒ¼ãƒˆã™ã‚‹ã‹ã®è‰¯ã„テンプレートã§ã‚ã‚Šã€å• -é¡Œã®è¿½è·¡ã‚’助ã‘ã‚‹ãŸã‚ã«ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºè€…ã«ã¨ã£ã¦ã©ã‚“ãªæƒ…å ±ãŒå¿…è¦ãªã®ã‹ã®è©³ -ç´°ãŒæ›¸ã‹ã‚Œã¦ã„ã¾ã™ã€‚ +https://bugzilla.kernel.org 㯠Linux カーãƒãƒ«é–‹ç™ºè€…ãŒã‚«ãƒ¼ãƒãƒ«ã®ãƒã‚°ã‚’追跡ã™ã‚‹ +å ´æ‰€ã§ã™ã€‚ユーザã¯è¦‹ã¤ã‘ãŸãƒã‚°ã®å…¨ã¦ã‚’ã“ã®ãƒ„ールã§å ±å‘Šã™ã¹ãã§ã™ã€‚ã©ã† +kernel bugzilla を使ã†ã‹ã®è©³ç´°ã¯ã€ä»¥ä¸‹ã‚’å‚ç…§ã—ã¦ãã ã•ã„ - + + https://bugzilla.kernel.org/page.cgi?id=faq.html + +メインカーãƒãƒ«ã‚½ãƒ¼ã‚¹ãƒ‡ã‚£ãƒ¬ã‚¯ãƒˆãƒªã«ã‚るファイル +admin-guide/reporting-bugs.rstã¯ã‚«ãƒ¼ãƒãƒ«ãƒã‚°ã‚‰ã—ã„ã‚‚ã®ã«ã¤ã„ã¦ã©ã†ãƒ¬ãƒãƒ¼ +トã™ã‚‹ã‹ã®è‰¯ã„テンプレートã§ã‚ã‚Šã€å•é¡Œã®è¿½è·¡ã‚’助ã‘ã‚‹ãŸã‚ã«ã‚«ãƒ¼ãƒãƒ«é–‹ç™º +者ã«ã¨ã£ã¦ã©ã‚“ãªæƒ…å ±ãŒå¿…è¦ãªã®ã‹ã®è©³ç´°ãŒæ›¸ã‹ã‚Œã¦ã„ã¾ã™ã€‚ ãƒã‚°ãƒ¬ãƒãƒ¼ãƒˆã®ç®¡ç† ------------------- @@ -383,74 +394,78 @@ bugzilla.kernel.org 㯠Linux カーãƒãƒ«é–‹ç™ºè€…ãŒã‚«ãƒ¼ãƒãƒ«ã®ãƒã‚°ã‚’è¿ ã‚ãªãŸã®ãƒãƒƒã‚ングã®ã‚¹ã‚ルを訓練ã™ã‚‹æœ€é«˜ã®æ–¹æ³•ã®ã²ã¨ã¤ã«ã€ä»–人ãŒãƒ¬ãƒãƒ¼ トã—ãŸãƒã‚°ã‚’ä¿®æ£ã™ã‚‹ã“ã¨ãŒã‚ã‚Šã¾ã™ã€‚ã‚ãªãŸãŒã‚«ãƒ¼ãƒãƒ«ã‚’より安定化ã•ã›ã‚‹ ã“ã«å¯„与ã™ã‚‹ã¨ã„ã†ã“ã¨ã ã‘ã§ãªãã€ã‚ãªãŸã¯ ç¾å®Ÿã®å•é¡Œã‚’ä¿®æ£ã™ã‚‹ã“ã¨ã‚’ -å¦ã³ã€è‡ªåˆ†ã®ã‚¹ã‚ルも強化ã§ãã€ã¾ãŸä»–ã®é–‹ç™ºè€…ãŒã‚ãªãŸã®å˜åœ¨ã«æ°—ãŒã¤ã -ã¾ã™ã€‚ãƒã‚°ã‚’ä¿®æ£ã™ã‚‹ã“ã¨ã¯ã€å¤šãã®é–‹ç™ºè€…ã®ä¸ã‹ã‚‰è‡ªåˆ†ãŒåŠŸç¸¾ã‚’ã‚ã’る最善 -ã®é“ã§ã™ã€ãªãœãªã‚‰å¤šãã®äººã¯ä»–人ã®ãƒã‚°ã®ä¿®æ£ã«æ™‚間を浪費ã™ã‚‹ã“ã¨ã‚’好㾠-ãªã„ã‹ã‚‰ã§ã™ã€‚ +å¦ã³ã€è‡ªåˆ†ã®ã‚¹ã‚ルも強化ã§ãã€ã¾ãŸä»–ã®é–‹ç™ºè€…ãŒã‚ãªãŸã®å˜åœ¨ã«æ°—ãŒã¤ãã¾ +ã™ã€‚ãƒã‚°ã‚’ä¿®æ£ã™ã‚‹ã“ã¨ã¯ã€å¤šãã®é–‹ç™ºè€…ã®ä¸ã‹ã‚‰è‡ªåˆ†ãŒåŠŸç¸¾ã‚’ã‚ã’る最善㮠+é“ã§ã™ã€ãªãœãªã‚‰å¤šãã®äººã¯ä»–人ã®ãƒã‚°ã®ä¿®æ£ã«æ™‚間を浪費ã™ã‚‹ã“ã¨ã‚’好ã¾ãª +ã„ã‹ã‚‰ã§ã™ã€‚ ã™ã§ã«ãƒ¬ãƒãƒ¼ãƒˆã•ã‚ŒãŸãƒã‚°ã®ãŸã‚ã«ä»•äº‹ã‚’ã™ã‚‹ãŸã‚ã«ã¯ã€ -http://bugzilla.kernel.org ã«è¡Œã£ã¦ãã ã•ã„。もã—今後ã®ãƒã‚°ãƒ¬ãƒãƒ¼ãƒˆã« +https://bugzilla.kernel.org ã«è¡Œã£ã¦ãã ã•ã„。もã—今後ã®ãƒã‚°ãƒ¬ãƒãƒ¼ãƒˆã« ã¤ã„ã¦ã‚¢ãƒ‰ãƒã‚¤ã‚¹ã‚’å—ã‘ãŸã„ã®ã§ã‚ã‚Œã°ã€bugme-new メーリングリスト(æ–°ã— ã„ãƒã‚°ãƒ¬ãƒãƒ¼ãƒˆã ã‘ãŒã“ã“ã«ãƒ¡ãƒ¼ãƒ«ã•ã‚Œã‚‹) ã¾ãŸã¯ bugme-janitor メーリン グリスト(bugzilla ã®å¤‰æ›´æ¯Žã«ã“ã“ã«ãƒ¡ãƒ¼ãƒ«ã•ã‚Œã‚‹)ã‚’è³¼èªã§ãã¾ã™ã€‚ - http://lists.linux-foundation.org/mailman/listinfo/bugme-new - http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors メーリングリスト -------------- +---------------- 上ã®ã„ãã¤ã‹ã®ãƒ‰ã‚ュメントã§è¿°ã¹ã¦ã„ã¾ã™ãŒã€ã‚³ã‚¢ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºè€…ã®å¤§éƒ¨åˆ† 㯠Linux kernel メーリングリストã«å‚åŠ ã—ã¦ã„ã¾ã™ã€‚ã“ã®ãƒªã‚¹ãƒˆã®ç™»éŒ²/脱 退ã®æ–¹æ³•ã«ã¤ã„ã¦ã¯ä»¥ä¸‹ã‚’å‚ç…§ã—ã¦ãã ã•ã„- + http://vger.kernel.org/vger-lists.html#linux-kernel ã“ã®ãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ãƒˆã®ã‚¢ãƒ¼ã‚«ã‚¤ãƒ–㯠web 上ã®å¤šæ•°ã®å ´æ‰€ã«å˜åœ¨ã—ã¾ã™ã€‚㓠れらã®ã‚¢ãƒ¼ã‚«ã‚¤ãƒ–を探ã™ã«ã¯ã‚µãƒ¼ãƒã‚¨ãƒ³ã‚¸ãƒ³ã‚’使ã„ã¾ã—ょã†ã€‚例ãˆã°- + http://dir.gmane.org/gmane.linux.kernel リストã«æŠ•ç¨¿ã™ã‚‹å‰ã«ã™ã§ã«ãã®è©±é¡ŒãŒã‚¢ãƒ¼ã‚«ã‚¤ãƒ–ã«å˜åœ¨ã™ã‚‹ã‹ã©ã†ã‹ã‚’検索 -ã™ã‚‹ã“ã¨ã‚’是éžã‚„ã£ã¦ãã ã•ã„。多数ã®äº‹ãŒã™ã§ã«è©³ç´°ã«æ¸¡ã£ã¦è°è«–ã•ã‚Œã¦ -ãŠã‚Šã€ã‚¢ãƒ¼ã‚«ã‚¤ãƒ–ã«ã®ã¿è¨˜éŒ²ã•ã‚Œã¦ã„ã¾ã™ã€‚ +ã™ã‚‹ã“ã¨ã‚’是éžã‚„ã£ã¦ãã ã•ã„。多数ã®äº‹ãŒã™ã§ã«è©³ç´°ã«æ¸¡ã£ã¦è°è«–ã•ã‚Œã¦ãŠ +ã‚Šã€ã‚¢ãƒ¼ã‚«ã‚¤ãƒ–ã«ã®ã¿è¨˜éŒ²ã•ã‚Œã¦ã„ã¾ã™ã€‚ 大部分ã®ã‚«ãƒ¼ãƒãƒ«ã‚µãƒ–システムも自分ã®å€‹åˆ¥ã®é–‹ç™ºã‚’実施ã™ã‚‹ãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ トをæŒã£ã¦ã„ã¾ã™ã€‚個々ã®ã‚°ãƒ«ãƒ¼ãƒ—ãŒã©ã‚“ãªãƒªã‚¹ãƒˆã‚’æŒã£ã¦ã„ã‚‹ã‹ã¯ã€ MAINTAINERS ファイルã«ãƒªã‚¹ãƒˆãŒã‚ã‚Šã¾ã™ã®ã§å‚ç…§ã—ã¦ãã ã•ã„。 多ãã®ãƒªã‚¹ãƒˆã¯ kernel.org ã§ãƒ›ã‚¹ãƒˆã•ã‚Œã¦ã„ã¾ã™ã€‚ã“れらã®æƒ…å ±ã¯ä»¥ä¸‹ã«ã‚ -ã‚Šã¾ã™- +ã‚Šã¾ã™ - + http://vger.kernel.org/vger-lists.html -メーリングリストを使ã†å ´åˆã€è‰¯ã„行動習慣ã«å¾“ã†ã‚ˆã†ã«ã—ã¾ã—ょã†ã€‚ -å°‘ã—安ã£ã½ã„ãŒã€ä»¥ä¸‹ã® URL ã¯ä¸Šã®ãƒªã‚¹ãƒˆ(ã‚„ä»–ã®ãƒªã‚¹ãƒˆ)ã§ä¼šè©±ã™ã‚‹å ´åˆã® -シンプルãªã‚¬ã‚¤ãƒ‰ãƒ©ã‚¤ãƒ³ã‚’示ã—ã¦ã„ã¾ã™- +メーリングリストを使ã†å ´åˆã€è‰¯ã„行動習慣ã«å¾“ã†ã‚ˆã†ã«ã—ã¾ã—ょã†ã€‚å°‘ã—安㣠+ã½ã„ãŒã€ä»¥ä¸‹ã® URL ã¯ä¸Šã®ãƒªã‚¹ãƒˆ(ã‚„ä»–ã®ãƒªã‚¹ãƒˆ)ã§ä¼šè©±ã™ã‚‹å ´åˆã®ã‚·ãƒ³ãƒ—ル +ãªã‚¬ã‚¤ãƒ‰ãƒ©ã‚¤ãƒ³ã‚’示ã—ã¦ã„ã¾ã™ - + http://www.albion.com/netiquette/ ã‚‚ã—複数ã®äººãŒã‚ãªãŸã®ãƒ¡ãƒ¼ãƒ«ã«è¿”事をã—ãŸå ´åˆã€CC: ã§å—ã‘る人ã®ãƒªã‚¹ãƒˆã¯ -ã ã„ã¶å¤šããªã‚‹ã§ã—ょã†ã€‚良ã„ç†ç”±ãŒãªã„å ´åˆã€CC: リストã‹ã‚‰èª°ã‹ã‚’削除を -ã—ãªã„よã†ã«ã€ã¾ãŸã€ãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ãƒˆã®ã‚¢ãƒ‰ãƒ¬ã‚¹ã ã‘ã«ãƒªãƒ—ライã™ã‚‹ã“ã¨ã® -ãªã„よã†ã«ã—ã¾ã—ょã†ã€‚1ã¤ã¯é€ä¿¡è€…ã‹ã‚‰ã€ã‚‚ã†1ã¤ã¯ãƒªã‚¹ãƒˆã‹ã‚‰ã®ã‚ˆã†ã«ã€ãƒ¡ãƒ¼ -ルを2回å—ã‘ã‚‹ã“ã¨ã«ãªã£ã¦ã‚‚ãã‚Œã«æ…£ã‚Œã€ã—ゃれãŸãƒ¡ãƒ¼ãƒ«ãƒ˜ãƒƒãƒ€ãƒ¼ã‚’è¿½åŠ ã— -ã¦ã“ã®çŠ¶æ…‹ã‚’変ãˆã‚ˆã†ã¨ã—ãªã„よã†ã«ã€‚人々ã¯ãã®ã‚ˆã†ãªã“ã¨ã¯å¥½ã¿ã¾ã›ã‚“。 +ã ã„ã¶å¤šããªã‚‹ã§ã—ょã†ã€‚æ£å½“ãªç†ç”±ãŒãªã„é™ã‚Šã€CC: リストã‹ã‚‰èª°ã‹ã‚’削除 +ã‚’ã—ãªã„よã†ã«ã€ã¾ãŸã€ãƒ¡ãƒ¼ãƒªãƒ³ã‚°ãƒªã‚¹ãƒˆã®ã‚¢ãƒ‰ãƒ¬ã‚¹ã ã‘ã«ãƒªãƒ—ライã™ã‚‹ã“㨠+ã®ãªã„よã†ã«ã—ã¾ã—ょã†ã€‚1ã¤ã¯é€ä¿¡è€…ã‹ã‚‰ã€ã‚‚ã†1ã¤ã¯ãƒªã‚¹ãƒˆã‹ã‚‰ã®ã‚ˆã†ã«ã€ +メールを2回å—ã‘ã‚‹ã“ã¨ã«ãªã£ã¦ã‚‚ãã‚Œã«æ…£ã‚Œã€ã—ゃれãŸãƒ¡ãƒ¼ãƒ«ãƒ˜ãƒƒãƒ€ãƒ¼ã‚’追 +åŠ ã—ã¦ã“ã®çŠ¶æ…‹ã‚’変ãˆã‚ˆã†ã¨ã—ãªã„よã†ã«ã€‚人々ã¯ãã®ã‚ˆã†ãªã“ã¨ã¯å¥½ã¿ã¾ã› +ん。 今ã¾ã§ã®ãƒ¡ãƒ¼ãƒ«ã§ã®ã‚„ã‚Šã¨ã‚Šã¨ãã®é–“ã®ã‚ãªãŸã®ç™ºè¨€ã¯ãã®ã¾ã¾æ®‹ã—〠"John Kernelhacker wrote ...:" ã®è¡Œã‚’ã‚ãªãŸã®ãƒªãƒ—ライã®å…ˆé è¡Œã«ã—ã¦ã€ メールã®å…ˆé ã§ãªãã€å„引用行ã®é–“ã«ã‚ãªãŸã®è¨€ã„ãŸã„ã“ã¨ã‚’è¿½åŠ ã™ã‚‹ã¹ã㧠ã™ã€‚ -ã‚‚ã—パッãƒã‚’メールã«ä»˜ã‘ã‚‹å ´åˆã¯ã€Documentation/process/submitting-patches.rst ã«æ -示ã•ã‚Œã¦ã„るよã†ã«ã€ãれ㯠プレーンãªå¯èªãƒ†ã‚ストã«ã™ã‚‹ã“ã¨ã‚’忘れãªã„ -よã†ã«ã—ã¾ã—ょã†ã€‚カーãƒãƒ«é–‹ç™ºè€…㯠添付や圧縮ã—ãŸãƒ‘ッãƒã‚’扱ã„ãŸãŒã‚Šã¾ -ã›ã‚“- -彼らã¯ã‚ãªãŸã®ãƒ‘ッãƒã®è¡Œæ¯Žã«ã‚³ãƒ¡ãƒ³ãƒˆã‚’入れãŸã„ã®ã§ã€ãã®ãŸã‚ã«ã¯ãã†ã™ -ã‚‹ã—ã‹ã‚ã‚Šã¾ã›ã‚“。ã‚ãªãŸã®ãƒ¡ãƒ¼ãƒ«ãƒ—ãƒã‚°ãƒ©ãƒ ãŒç©ºç™½ã‚„タブを圧縮ã—ãªã„よㆠ-ã«ç¢ºèªã—ãŸæ–¹ãŒè‰¯ã„ã§ã™ã€‚最åˆã®è‰¯ã„テストã¨ã—ã¦ã¯ã€è‡ªåˆ†ã«ãƒ¡ãƒ¼ãƒ«ã‚’é€ã£ã¦ -ã¿ã¦ã€ãã®ãƒ‘ッãƒã‚’自分ã§å½“ã¦ã¦ã¿ã‚‹ã“ã¨ã§ã™ã€‚ã‚‚ã—ãã‚ŒãŒã†ã¾ãè¡Œã‹ãªã„㪠-らã€ã‚ãªãŸã®ãƒ¡ãƒ¼ãƒ«ãƒ—ãƒã‚°ãƒ©ãƒ ã‚’ç›´ã—ã¦ã‚‚らã†ã‹ã€æ£ã—ãå‹•ãよã†ã«å¤‰ãˆã‚‹ã¹ -ãã§ã™ã€‚ +ã‚‚ã—パッãƒã‚’メールã«ä»˜ã‘ã‚‹å ´åˆã¯ã€ +Documentation/process/submitting-patches.rst ã«æ示ã•ã‚Œã¦ã„るよã†ã«ã€ã +れ㯠プレーンãªå¯èªãƒ†ã‚ストã«ã™ã‚‹ã“ã¨ã‚’忘れãªã„よã†ã«ã—ã¾ã—ょã†ã€‚カー +ãƒãƒ«é–‹ç™ºè€…㯠添付や圧縮ã—ãŸãƒ‘ッãƒã‚’扱ã„ãŸãŒã‚Šã¾ã›ã‚“。彼らã¯ã‚ãªãŸã®ãƒ‘ッ +ãƒã®è¡Œæ¯Žã«ã‚³ãƒ¡ãƒ³ãƒˆã‚’入れãŸã„ã®ã§ã€ãã†ã™ã‚‹ã—ã‹ã‚ã‚Šã¾ã›ã‚“。ã‚ãªãŸã®ãƒ¡ãƒ¼ +ルプãƒã‚°ãƒ©ãƒ ãŒç©ºç™½ã‚„タブを圧縮ã—ãªã„よã†ã«ç¢ºèªã—ã¾ã—ょã†ã€‚最åˆã®è‰¯ã„テ +ストã¨ã—ã¦ã¯ã€è‡ªåˆ†ã«ãƒ¡ãƒ¼ãƒ«ã‚’é€ã£ã¦ã¿ã¦ã€ãã®ãƒ‘ッãƒã‚’自分ã§å½“ã¦ã¦ã¿ã‚‹ã“ +ã¨ã§ã™ã€‚ã‚‚ã—ãã‚ŒãŒã†ã¾ãè¡Œã‹ãªã„ãªã‚‰ã€ã‚ãªãŸã®ãƒ¡ãƒ¼ãƒ«ãƒ—ãƒã‚°ãƒ©ãƒ ã‚’ç›´ã—㦠+もらã†ã‹ã€æ£ã—ãå‹•ãよã†ã«å¤‰ãˆã‚‹ã¹ãã§ã™ã€‚ -ã¨ã‚Šã‚ã‘ã€ä»–ã®ç™»éŒ²è€…ã«å¯¾ã™ã‚‹å°Šæ•¬ã‚’表ã™ã‚ˆã†ã«ã™ã‚‹ã“ã¨ã‚’覚ãˆã¦ãŠã„ã¦ãã -ã•ã„。 +何をãŠã„ã¦ã‚‚ã€ä»–ã®è³¼èªè€…ã«å¯¾ã™ã‚‹æ•¬æ„を表ã™ã“ã¨ã‚’忘れãªã„ã§ãã ã•ã„。 コミュニティã¨å…±ã«åƒãã“㨠-------------------------- @@ -459,21 +474,22 @@ MAINTAINERS ファイルã«ãƒªã‚¹ãƒˆãŒã‚ã‚Šã¾ã™ã®ã§å‚ç…§ã—ã¦ãã ã•ã ã§ã™ã€‚ã‚ãªãŸãŒãƒ‘ッãƒã‚’å—ã‘入れã¦ã‚‚らã†ãŸã‚ã«æŠ•ç¨¿ã—ãŸå ´åˆã€ãã‚Œã¯ã€æŠ€è¡“ 的メリットã ã‘ãŒãƒ¬ãƒ“ューã•ã‚Œã¾ã™ã€‚ãã®éš›ã€ã‚ãªãŸã¯ä½•ã‚’予想ã™ã¹ãã§ã—ょ ã†ã‹? + - 批判 - コメント - 変更ã®è¦æ±‚ - パッãƒã®æ£å½“性ã®è¨¼æ˜Žè¦æ±‚ - 沈黙 -æ€ã„出ã—ã¦ãã ã•ã„ã€ã“ã“ã¯ã‚ãªãŸã®ãƒ‘ッãƒã‚’カーãƒãƒ«ã«å…¥ã‚Œã‚‹è©±ã§ã™ã€‚ã‚ -ãªãŸã¯ã€ã‚ãªãŸã®ãƒ‘ッãƒã«å¯¾ã™ã‚‹æ‰¹åˆ¤ã¨ã‚³ãƒ¡ãƒ³ãƒˆã‚’å—ã‘入れるã¹ãã§ã€ãれら -を技術的レベルã§è©•ä¾¡ã—ã¦ã€ãƒ‘ッãƒã‚’å†ä½œæˆã™ã‚‹ã‹ã€ãªãœãれらã®å¤‰æ›´ã‚’ã™ã¹ -ãã§ãªã„ã‹ã‚’明確ã§ç°¡æ½”ãªç†ç”±ã®èª¬æ˜Žã‚’æä¾›ã—ã¦ãã ã•ã„。 -ã‚‚ã—ã€ã‚ãªãŸã®ãƒ‘ッãƒã«ä½•ã‚‚åå¿œãŒãªã„å ´åˆã€ãŸã¾ã«ã¯ãƒ¡ãƒ¼ãƒ«ã®å±±ã«åŸ‹ã‚‚れ㦠-見逃ã•ã‚Œã€ã‚ãªãŸã®æŠ•ç¨¿ãŒå¿˜ã‚Œã‚‰ã‚Œã¦ã—ã¾ã†ã“ã¨ã‚‚ã‚ã‚‹ã®ã§ã€æ•°æ—¥å¾…ã£ã¦å†åº¦ -投稿ã—ã¦ãã ã•ã„。 +æ€ã„出ã—ã¦ãã ã•ã„ã€ã“ã‚Œã¯ã‚ãªãŸã®ãƒ‘ッãƒã‚’カーãƒãƒ«ã«å…¥ã‚Œã‚‹è©±ã§ã™ã€‚ã‚㪠+ãŸã¯ã€ã‚ãªãŸã®ãƒ‘ッãƒã«å¯¾ã™ã‚‹æ‰¹åˆ¤ã¨ã‚³ãƒ¡ãƒ³ãƒˆã‚’å—ã‘入れるã¹ãã§ã€ãれらを +技術的レベルã§è©•ä¾¡ã—ã¦ã€ãƒ‘ッãƒã‚’å†ä½œæˆã™ã‚‹ã‹ã€ãªãœãれらã®å¤‰æ›´ã‚’ã™ã¹ã +ã§ãªã„ã‹ã‚’明確ã§ç°¡æ½”ãªç†ç”±ã®èª¬æ˜Žã‚’æä¾›ã—ã¦ãã ã•ã„。もã—ã€ã‚ãªãŸã®ãƒ‘ッ +ãƒã«ä½•ã‚‚åå¿œãŒãªã„å ´åˆã€ãŸã¾ã«ã¯ãƒ¡ãƒ¼ãƒ«ã®å±±ã«åŸ‹ã‚‚ã‚Œã¦è¦‹é€ƒã•ã‚Œã€ã‚ãªãŸã® +投稿ãŒå¿˜ã‚Œã‚‰ã‚Œã¦ã—ã¾ã†ã“ã¨ã‚‚ã‚ã‚‹ã®ã§ã€æ•°æ—¥å¾…ã£ã¦å†åº¦æŠ•ç¨¿ã—ã¦ãã ã•ã„。 + +ã‚ãªãŸãŒã‚„ã‚‹ã¹ãã§ãªã„ã“ã¨ã¯? -ã‚ãªãŸãŒã‚„ã‚‹ã¹ãã§ãªã„ã‚‚ã®ã¯? - 質å•ãªã—ã«ã‚ãªãŸã®ãƒ‘ッãƒãŒå—ã‘入れられるã¨æƒ³åƒã™ã‚‹ã“㨠- 守りã«å…¥ã‚‹ã“㨠- コメントを無視ã™ã‚‹ã“㨠@@ -489,37 +505,37 @@ MAINTAINERS ファイルã«ãƒªã‚¹ãƒˆãŒã‚ã‚Šã¾ã™ã®ã§å‚ç…§ã—ã¦ãã ã•ã ã‚ãªãŸã®æœ€åˆã®ãƒ‘ッãƒã«å˜ã« 1ダースもã®ä¿®æ£ã‚’求ã‚るリストã®è¿”ç”ã«ãªã‚‹ã“ ã¨ã‚‚普通ã®ã“ã¨ã§ã™ã€‚ã“ã‚Œã¯ã‚ãªãŸã®ãƒ‘ッãƒãŒå—ã‘入れられãªã„ã¨ã„ã†ã“ã¨ã§ -㯠*ã‚ã‚Šã¾ã›ã‚“*ã€ãã—ã¦ã‚ãªãŸè‡ªèº«ã«å対ã™ã‚‹ã“ã¨ã‚’æ„味ã™ã‚‹ã®ã§ã‚‚ *ã‚ã‚Šã¾ -ã›ã‚“*。å˜ã«è‡ªåˆ†ã®ãƒ‘ッãƒã«å¯¾ã—ã¦æŒ‡æ‘˜ã•ã‚ŒãŸå•é¡Œã‚’å…¨ã¦ä¿®æ£ã—ã¦å†é€ã™ã‚Œã° -良ã„ã®ã§ã™ã€‚ +㯠**ã‚ã‚Šã¾ã›ã‚“**ã€ãã—ã¦ã‚ãªãŸè‡ªèº«ã«å対ã™ã‚‹ã“ã¨ã‚’æ„味ã™ã‚‹ã®ã§ã‚‚ **ã‚ +ã‚Šã¾ã›ã‚“**。å˜ã«è‡ªåˆ†ã®ãƒ‘ッãƒã«å¯¾ã—ã¦æŒ‡æ‘˜ã•ã‚ŒãŸå•é¡Œã‚’å…¨ã¦ä¿®æ£ã—ã¦å†é€ã™ +ã‚Œã°è‰¯ã„ã®ã§ã™ã€‚ カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¨ä¼æ¥çµ„ç¹”ã®ã¡ãŒã„ ----------------------------------------------------------------- カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯å¤§éƒ¨åˆ†ã®ä¼çµ±çš„ãªä¼šç¤¾ã®é–‹ç™ºç’°å¢ƒã¨ã¯ç•°ã£ãŸã‚„り方㧠-å‹•ã„ã¦ã„ã¾ã™ã€‚以下ã¯å•é¡Œã‚’é¿ã‘ã‚‹ãŸã‚ã«ã§ãã‚‹ã¨è‰¯ã„ã“ã¨ã®ãƒªã‚¹ãƒˆã§ã™- +å‹•ã„ã¦ã„ã¾ã™ã€‚以下ã¯å•é¡Œã‚’é¿ã‘ã‚‹ãŸã‚ã«ã§ãã‚‹ã¨è‰¯ã„ã“ã¨ã®ãƒªã‚¹ãƒˆã§ã™ã€‚ - ã‚ãªãŸã®æ案ã™ã‚‹å¤‰æ›´ã«ã¤ã„ã¦è¨€ã†ã¨ãã®ã†ã¾ã„言ã„方： + ã‚ãªãŸã®æ案ã™ã‚‹å¤‰æ›´ã«ã¤ã„ã¦è¨€ã†ã¨ãã®ã†ã¾ã„言ã„æ–¹ - - "ã“ã‚Œã¯è¤‡æ•°ã®å•é¡Œã‚’解決ã—ã¾ã™" - "ã“ã‚Œã¯2000è¡Œã®ã‚³ãƒ¼ãƒ‰ã‚’削除ã—ã¾ã™" - "以下ã®ãƒ‘ッãƒã¯ã€ç§ãŒè¨€ãŠã†ã¨ã—ã¦ã„ã‚‹ã“ã¨ã‚’説明ã™ã‚‹ã‚‚ã®ã§ã™" - "ç§ã¯ã“れを5ã¤ã®ç•°ãªã‚‹ã‚¢ãƒ¼ã‚テクãƒãƒ£ã§ãƒ†ã‚¹ãƒˆã—ãŸã®ã§ã™ãŒ..." - "以下ã¯ä¸€é€£ã®å°ã•ãªãƒ‘ッãƒç¾¤ã§ã™ãŒ..." - - "ã“ã‚Œã¯å…¸åž‹çš„ãªãƒžã‚·ãƒ³ã§ã®æ€§èƒ½ã‚’å‘上ã•ã›ã¾ã™.." + - "ã“ã‚Œã¯å…¸åž‹çš„ãªãƒžã‚·ãƒ³ã§ã®æ€§èƒ½ã‚’å‘上ã•ã›ã¾ã™..." - ã‚„ã‚ãŸæ–¹ãŒè‰¯ã„悪ã„言ã„方： + ã‚„ã‚ãŸæ–¹ãŒè‰¯ã„悪ã„言ã„æ–¹ - - - ã“ã®ã‚„り方㧠AIX/ptx/Solaris ã§ã¯ã§ããŸã®ã§ã€ã§ãã‚‹ã¯ãšã - - ç§ã¯ã“れを20å¹´ã‚‚ã®é–“ã‚„ã£ã¦ããŸã€ã ã‹ã‚‰ - - ã“ã‚Œã¯ã€ç§ã®ä¼šç¤¾ãŒé‡‘儲ã‘ã‚’ã™ã‚‹ãŸã‚ã«å¿…è¦ã - - ã“ã‚Œã¯æˆ‘々ã®ã‚¨ãƒ³ã‚¿ãƒ¼ãƒ—ライズå‘ã‘商å“ラインã®ãŸã‚ã§ã‚ã‚‹ - - ã“れ㯠ç§ãŒè‡ªåˆ†ã®ã‚¢ã‚¤ãƒ‡ã‚£ã‚¢ã‚’記述ã—ãŸã€1000ページã®è¨è¨ˆè³‡æ–™ã§ã‚ã‚‹ - - ç§ã¯ã“ã‚Œã«ã¤ã„ã¦ã€6ケ月作æ¥ã—ã¦ã„る。 - - 以下㯠... ã«é–¢ã™ã‚‹5000è¡Œã®ãƒ‘ッãƒã§ã™ - - ç§ã¯ç¾åœ¨ã®ãã¡ã‚ƒãã¡ã‚ƒã‚’全部書ãç›´ã—ãŸã€ãã‚ŒãŒä»¥ä¸‹ã§ã™... - - ç§ã¯ã€†åˆ‡ãŒã‚ã‚‹ã€ãã®ãŸã‚ã“ã®ãƒ‘ッãƒã¯ä»Šã™ãé©ç”¨ã•ã‚Œã‚‹å¿…è¦ãŒã‚ã‚‹ + - "ã“ã®ã‚„り方㧠AIX/ptx/Solaris ã§ã¯ã§ããŸã®ã§ã€ã§ãã‚‹ã¯ãšã ..." + - "ç§ã¯ã“れを20å¹´ã‚‚ã®é–“ã‚„ã£ã¦ããŸã€ã ã‹ã‚‰..." + - "ã“ã‚Œã¯ç§ã®ä¼šç¤¾ãŒé‡‘儲ã‘ã‚’ã™ã‚‹ãŸã‚ã«å¿…è¦ã " + - "ã“ã‚Œã¯æˆ‘々ã®ã‚¨ãƒ³ã‚¿ãƒ¼ãƒ—ライズå‘ã‘商å“ラインã®ãŸã‚ã§ã‚ã‚‹" + - "ã“ã‚Œã¯ç§ãŒè‡ªåˆ†ã®ã‚¢ã‚¤ãƒ‡ã‚£ã‚¢ã‚’記述ã—ãŸã€1000ページã®è¨è¨ˆè³‡æ–™ã§ã‚ã‚‹" + - "ç§ã¯ã“ã‚Œã«ã¤ã„ã¦ã€6ケ月作æ¥ã—ã¦ã„ã‚‹..." + - "以下㯠... ã«é–¢ã™ã‚‹5000è¡Œã®ãƒ‘ッãƒã§ã™" + - "ç§ã¯ç¾åœ¨ã®ãã¡ã‚ƒãã¡ã‚ƒã‚’全部書ãç›´ã—ãŸã€ãã‚ŒãŒä»¥ä¸‹ã§ã™..." + - "ç§ã¯ã€†åˆ‡ãŒã‚ã‚‹ã€ãã®ãŸã‚ã“ã®ãƒ‘ッãƒã¯ä»Šã™ãé©ç”¨ã•ã‚Œã‚‹å¿…è¦ãŒã‚ã‚‹" カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ãŒå¤§éƒ¨åˆ†ã®ä¼çµ±çš„ãªã‚½ãƒ•ãƒˆã‚¦ã‚§ã‚¢ã‚¨ãƒ³ã‚¸ãƒ‹ã‚¢ãƒªãƒ³ã‚°ã®åŠ´ åƒç’°å¢ƒã¨ç•°ãªã‚‹ã‚‚ã†ä¸€ã¤ã®ç‚¹ã¯ã€ã‚„ã‚Šã¨ã‚Šã«é¡”ã‚’åˆã‚ã›ãªã„ã¨ã„ã†ã“ã¨ã§ã™ã€‚ @@ -535,13 +551,13 @@ Patricia (主ã«å¥³æ€§å)ã‚„ Patrick (主ã«ç”·æ€§å)ã®ç•¥ç§°)。 Linux カーãƒãƒ«ã®æ´»å‹•ã‚’ã—ã¦ã€æ„見を表明ã—ãŸã“ã¨ãŒã‚る大部分ã®å¥³æ€§ã¯ã€å‰ å‘ããªçµŒé¨“ã‚’ã‚‚ã£ã¦ã„ã¾ã™ã€‚ -言葉ã®å£ã¯è‹±èªžãŒå¾—æ„ã§ãªã„一部ã®äººã«ã¯å•é¡Œã«ãªã‚Šã¾ã™ã€‚ -メーリングリストã®ä¸ã§ãã¡ã‚“ã¨ã‚¢ã‚¤ãƒ‡ã‚£ã‚¢ã‚’交æ›ã™ã‚‹ã«ã¯ã€ç›¸å½“ã†ã¾ã英語 -ã‚’æ“れる必è¦ãŒã‚ã‚‹ã“ã¨ã‚‚ã‚ã‚Šã¾ã™ã€‚ãã®ãŸã‚ã€ã‚ãªãŸã¯è‡ªåˆ†ã®ãƒ¡ãƒ¼ãƒ« -ã‚’é€ã‚‹å‰ã«è‹±èªžã§æ„味ãŒé€šã˜ã¦ã„ã‚‹ã‹ã‚’ãƒã‚§ãƒƒã‚¯ã™ã‚‹ã“ã¨ã‚’ãŠè–¦ã‚ã—ã¾ã™ã€‚ +言葉ã®å£ã¯è‹±èªžãŒå¾—æ„ã§ãªã„一部ã®äººã«ã¯å•é¡Œã«ãªã‚Šã¾ã™ã€‚メーリングリスト +ã®ä¸ã§ã€ãã¡ã‚“ã¨ã‚¢ã‚¤ãƒ‡ã‚£ã‚¢ã‚’交æ›ã™ã‚‹ã«ã¯ã€ç›¸å½“ã†ã¾ã英語をæ“れる必è¦ãŒ +ã‚ã‚‹ã“ã¨ã‚‚ã‚ã‚Šã¾ã™ã€‚ãã®ãŸã‚ã€è‡ªåˆ†ã®ãƒ¡ãƒ¼ãƒ«ã‚’é€ã‚‹å‰ã«è‹±èªžã§æ„味ãŒé€šã˜ã¦ +ã„ã‚‹ã‹ã‚’ãƒã‚§ãƒƒã‚¯ã™ã‚‹ã“ã¨ã‚’ãŠè–¦ã‚ã—ã¾ã™ã€‚ 変更を分割ã™ã‚‹ ---------------------- +-------------- Linux カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯ã€ä¸€åº¦ã«å¤§é‡ã®ã‚³ãƒ¼ãƒ‰ã®å¡Šã‚’喜んã§å—容ã™ã‚‹ã“ ã¨ã¯ã‚ã‚Šã¾ã›ã‚“。変更ã¯æ£ç¢ºã«èª¬æ˜Žã•ã‚Œã‚‹å¿…è¦ãŒã‚ã‚Šã€è°è«–ã•ã‚Œã€å°ã•ã„ã€å€‹ @@ -555,7 +571,7 @@ Linux カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯ã€ä¸€åº¦ã«å¤§é‡ã®ã‚³ãƒ¼ãƒ‰ã®å¡Šã‚’å– ã‚„ã£ã¦ã¯ã„ã‘ã¾ã›ã‚“ã€ã‚ãªãŸã®ãƒ‘ッãƒç¾¤ã¯ã„ã¤ã‚‚ã©ã‚“ãªæ™‚ã§ã‚‚ãれよりã¯å°ã• ããªã‘ã‚Œã°ãªã‚Šã¾ã›ã‚“。 -パッãƒã‚’分割ã™ã‚‹ç†ç”±ã¯ä»¥ä¸‹ã§ã™- +パッãƒã‚’分割ã™ã‚‹ç†ç”±ã¯ä»¥ä¸‹ - 1) å°ã•ã„パッãƒã¯ã‚ãªãŸã®ãƒ‘ッãƒãŒé©ç”¨ã•ã‚Œã‚‹è¦‹è¾¼ã¿ã‚’大ããã—ã¾ã™ã€ã‚«ãƒ¼ ãƒãƒ«ã®äººé”ã¯ãƒ‘ッãƒãŒæ£ã—ã„ã‹ã©ã†ã‹ã‚’確èªã™ã‚‹æ™‚間や労力をã‹ã‘ãªã„ã‹ @@ -571,41 +587,41 @@ Linux カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯ã€ä¸€åº¦ã«å¤§é‡ã®ã‚³ãƒ¼ãƒ‰ã®å¡Šã‚’å– 2) å°ã•ã„パッãƒã‚’é€ã‚‹ã ã‘ã§ãªãã€é€ã‚‹ã¾ãˆã«ã€æ›¸ãç›´ã—ã¦ã€ã‚·ãƒ³ãƒ—ルã«ã™ ã‚‹(ã‚‚ã—ãã¯ã€å˜ã«é †ç•ªã‚’変ãˆã‚‹ã ã‘ã§ã‚‚)ã“ã¨ã‚‚ã€ã¨ã¦ã‚‚é‡è¦ã§ã™ã€‚ -以下ã¯ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºè€…ã® Al Viro ã®ãŸã¨ãˆè©±ã§ã™ï¼š +以下ã¯ã‚«ãƒ¼ãƒãƒ«é–‹ç™ºè€…ã® Al Viro ã®ãŸã¨ãˆè©±ã§ã™ - - "生徒ã®æ•°å¦ã®å®¿é¡Œã‚’採点ã™ã‚‹å…ˆç”Ÿã®ã“ã¨ã‚’考ãˆã¦ã¿ã¦ãã ã•ã„ã€å…ˆ - 生ã¯ç”Ÿå¾’ãŒè§£ã«åˆ°é”ã™ã‚‹ã¾ã§ã®è©¦è¡ŒéŒ¯èª¤ã‚’見ãŸã„ã¨ã¯æ€ã‚ãªã„ã§ã—ょ - ã†ã€‚先生ã¯ç°¡æ½”ãªæœ€é«˜ã®è§£ã‚’見ãŸã„ã®ã§ã™ã€‚良ã„生徒ã¯ã“れを知ã£ã¦ - ãŠã‚Šã€ãã—ã¦æœ€çµ‚解ã®å‰ã®ä¸é–“作æ¥ã‚’æ出ã™ã‚‹ã“ã¨ã¯æ±ºã—ã¦ãªã„ã®ã§ - ã™" + *"生徒ã®æ•°å¦ã®å®¿é¡Œã‚’採点ã™ã‚‹å…ˆç”Ÿã®ã“ã¨ã‚’考ãˆã¦ã¿ã¦ãã ã•ã„〠+ 先生ã¯ç”Ÿå¾’ãŒè§£ã«åˆ°é”ã™ã‚‹ã¾ã§ã®è©¦è¡ŒéŒ¯èª¤ã‚’見ãŸã„ã¨ã¯æ€ã‚ãªã„ã§ã— + ょã†ã€‚先生ã¯ç°¡æ½”ãªæœ€é«˜ã®è§£ã‚’見ãŸã„ã®ã§ã™ã€‚良ã„生徒ã¯ã“れを知㣠+ ã¦ãŠã‚Šã€ãã—ã¦æœ€çµ‚解ã®å‰ã®ä¸é–“作æ¥ã‚’æ出ã™ã‚‹ã“ã¨ã¯æ±ºã—ã¦ãªã„ã® + ã§ã™* - カーãƒãƒ«é–‹ç™ºã§ã‚‚ã“ã‚Œã¯åŒã˜ã§ã™ã€‚メンテナé”ã¨ãƒ¬ãƒ“ューアé”ã¯ã€ + *カーãƒãƒ«é–‹ç™ºã§ã‚‚ã“ã‚Œã¯åŒã˜ã§ã™ã€‚メンテナé”ã¨ãƒ¬ãƒ“ューアé”ã¯ã€ å•é¡Œã‚’解決ã™ã‚‹è§£ã®èƒŒå¾Œã«ãªã‚‹æ€è€ƒãƒ—ãƒã‚»ã‚¹ã‚’見ãŸã„ã¨ã¯æ€ã„ã¾ã›ã‚“。 - 彼らã¯å˜ç´”ã§ã‚ã–ã‚„ã‹ãªè§£æ±ºæ–¹æ³•ã‚’見ãŸã„ã®ã§ã™ã€‚ + 彼らã¯å˜ç´”ã§ã‚ã–ã‚„ã‹ãªè§£æ±ºæ–¹æ³•ã‚’見ãŸã„ã®ã§ã™ã€‚"* ã‚ã–ã‚„ã‹ãªè§£ã‚’説明ã™ã‚‹ã®ã¨ã€ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¨å…±ã«ä»•äº‹ã‚’ã—ã€æœªè§£æ±ºã®ä»•äº‹ã‚’ -è°è«–ã™ã‚‹ã“ã¨ã®ãƒãƒ©ãƒ³ã‚¹ã‚’ã‚ープã™ã‚‹ã®ã¯é›£ã—ã„ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。 -ã§ã™ã‹ã‚‰ã€é–‹ç™ºãƒ—ãƒã‚»ã‚¹ã®æ—©æœŸæ®µéšŽã§æ”¹å–„ã®ãŸã‚ã®ãƒ•ã‚£ãƒ¼ãƒ‰ãƒãƒƒã‚¯ã‚’もらã†ã‚ˆ -ã†ã«ã™ã‚‹ã®ã‚‚良ã„ã§ã™ãŒã€å¤‰æ›´ç‚¹ã‚’å°ã•ã„部分ã«åˆ†å‰²ã—ã¦å…¨ä½“ã§ã¯ã¾ã 完æˆã— -ã¦ã„ãªã„仕事を(部分的ã«)å–り込んã§ã‚‚らãˆã‚‹ã‚ˆã†ã«ã™ã‚‹ã“ã¨ã‚‚良ã„ã“ã¨ã§ã™ã€‚ +è°è«–ã™ã‚‹ã“ã¨ã®ãƒãƒ©ãƒ³ã‚¹ã‚’ã‚ープã™ã‚‹ã®ã¯é›£ã—ã„ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。ã§ã™ã‹ã‚‰ã€ +開発プãƒã‚»ã‚¹ã®æ—©æœŸæ®µéšŽã§æ”¹å–„ã®ãŸã‚ã®ãƒ•ã‚£ãƒ¼ãƒ‰ãƒãƒƒã‚¯ã‚’もらã†ã‚ˆã†ã«ã™ã‚‹ã® +も良ã„ã§ã™ãŒã€å¤‰æ›´ç‚¹ã‚’å°ã•ã„部分ã«åˆ†å‰²ã—ã¦å…¨ä½“ã§ã¯ã¾ã 完æˆã—ã¦ã„ãªã„仕 +事を(部分的ã«)å–り込んã§ã‚‚らãˆã‚‹ã‚ˆã†ã«ã™ã‚‹ã“ã¨ã‚‚良ã„ã“ã¨ã§ã™ã€‚ ã¾ãŸã€ã§ã上ãŒã£ã¦ã„ãªã„ã‚‚ã®ã‚„ã€"å°†æ¥ç›´ã™" よã†ãªãƒ‘ッãƒã‚’ã€æœ¬æµã«å«ã‚ ã¦ã‚‚らã†ã‚ˆã†ã«é€ã£ã¦ã‚‚ã€ãã‚Œã¯å—ã‘付ã‘られãªã„ã“ã¨ã‚’ç†è§£ã—ã¦ãã ã•ã„。 ã‚ãªãŸã®å¤‰æ›´ã‚’æ£å½“化ã™ã‚‹ -------------------- +------------------------ ã‚ãªãŸã®ãƒ‘ッãƒã‚’分割ã™ã‚‹ã®ã¨åŒæ™‚ã«ã€ãªãœãã®å¤‰æ›´ã‚’è¿½åŠ ã—ãªã‘ã‚Œã°ãªã‚‰ãª ã„ã‹ã‚’ Linux コミュニティã«çŸ¥ã‚‰ã›ã‚‹ã“ã¨ã¯ã¨ã¦ã‚‚é‡è¦ã§ã™ã€‚新機能ã¯å¿…è¦ æ€§ã¨æœ‰ç”¨æ€§ã§æ£å½“化ã•ã‚Œãªã‘ã‚Œã°ãªã‚Šã¾ã›ã‚“。 -ã‚ãªãŸã®å¤‰æ›´ã®èª¬æ˜Ž --------------------- +ã‚ãªãŸã®å¤‰æ›´ã‚’説明ã™ã‚‹ +---------------------- ã‚ãªãŸã®ãƒ‘ッãƒã‚’é€ä»˜ã™ã‚‹å ´åˆã«ã¯ã€ãƒ¡ãƒ¼ãƒ«ã®ä¸ã®ãƒ†ã‚ストã§ä½•ã‚’言ã†ã‹ã«ã¤ ã„ã¦ã€ç‰¹åˆ¥ã«æ³¨æ„を払ã£ã¦ãã ã•ã„。ã“ã®æƒ…å ±ã¯ãƒ‘ッãƒã® ChangeLog ã«ä½¿ã‚ ã‚Œã€ã„ã¤ã‚‚皆ãŒã¿ã‚‰ã‚Œã‚‹ã‚ˆã†ã«ä¿ç®¡ã•ã‚Œã¾ã™ã€‚ã“ã‚Œã¯æ¬¡ã®ã‚ˆã†ãªé …目をå«ã‚〠-パッãƒã‚’完全ã«è¨˜è¿°ã™ã‚‹ã¹ãã§ã™- +パッãƒã‚’完全ã«è¨˜è¿°ã™ã‚‹ã¹ãã§ã™ - - ãªãœå¤‰æ›´ãŒå¿…è¦ã‹ - パッãƒå…¨ä½“ã®è¨è¨ˆã‚¢ãƒ—ãƒãƒ¼ãƒ @@ -613,18 +629,24 @@ Linux カーãƒãƒ«ã‚³ãƒŸãƒ¥ãƒ‹ãƒ†ã‚£ã¯ã€ä¸€åº¦ã«å¤§é‡ã®ã‚³ãƒ¼ãƒ‰ã®å¡Šã‚’å– - テストçµæžœ ã“ã‚Œã«ã¤ã„ã¦å…¨ã¦ãŒã©ã®ã‚ˆã†ã«ã‚ã‚‹ã¹ãã‹ã«ã¤ã„ã¦ã®è©³ç´°ã¯ã€ä»¥ä¸‹ã®ãƒ‰ã‚ュメ -ント㮠ChangeLog セクションを見ã¦ãã ã•ã„- +ント㮠ChangeLog セクションを見ã¦ãã ã•ã„ - + "The Perfect Patch" http://www.ozlabs.org/~akpm/stuff/tpp.txt -ã“れらã®ã©ã‚Œã‚‚ãŒã€æ™‚ã«ã¯ã¨ã¦ã‚‚困難ã§ã™ã€‚ã“れらã®æ…£ä¾‹ã‚’完璧ã«å®Ÿæ–½ã™ã‚‹ã« -ã¯æ•°å¹´ã‹ã‹ã‚‹ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。ã“ã‚Œã¯ç¶™ç¶šçš„ãªæ”¹å–„ã®ãƒ—ãƒã‚»ã‚¹ã§ã‚ã‚Šã€ãã®ãŸ -ã‚ã«ã¯å¤šæ•°ã®å¿è€ã¨æ±ºæ„ã‚’å¿…è¦ã¨ã™ã‚‹ã‚‚ã®ã§ã™ã€‚ã§ã‚‚ã€è«¦ã‚ãªã„ã§ã€ã“ã‚Œã¯å¯ -能ãªã“ã¨ã§ã™ã€‚多数ã®äººãŒã™ã§ã«ã§ãã¦ã„ã¾ã™ã—ã€å½¼ã‚‰ã‚‚皆最åˆã¯ã‚ãªãŸã¨åŒ -ã˜ã¨ã“ã‚ã‹ã‚‰ã‚¹ã‚¿ãƒ¼ãƒˆã—ãŸã®ã§ã™ã‹ã‚‰ã€‚ +ã“れらã¯ã©ã‚Œã‚‚ã€å®Ÿè¡Œã™ã‚‹ã“ã¨ãŒæ™‚ã«ã¯ã¨ã¦ã‚‚困難ã§ã™ã€‚ã“れらã®ä¾‹ã‚’完璧㫠+実施ã™ã‚‹ã«ã¯æ•°å¹´ã‹ã‹ã‚‹ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。ã“ã‚Œã¯ç¶™ç¶šçš„ãªæ”¹å–„ã®ãƒ—ãƒã‚»ã‚¹ã§ã‚ +ã‚Šã€å¤šãã®å¿è€ã¨æ±ºæ„ã‚’å¿…è¦ã¨ã™ã‚‹ã‚‚ã®ã§ã™ã€‚ã§ã‚‚諦ã‚ãªã„ã§ã€å®Ÿç¾ã¯å¯èƒ½ã§ +ã™ã€‚多数ã®äººãŒã™ã§ã«ã§ãã¦ã„ã¾ã™ã—ã€å½¼ã‚‰ã‚‚最åˆã¯ã‚ãªãŸã¨åŒã˜ã¨ã“ã‚ã‹ã‚‰ +スタートã—ãŸã®ã§ã™ã‹ã‚‰ã€‚ + + + + +---------- Paolo Ciarrocchi ã«æ„Ÿè¬ã€å½¼ã¯å½¼ã®æ›¸ã„㟠"Development Process" -(http://lwn.net/Articles/94386/) セクションをã“ã®ãƒ†ã‚ストã®åŽŸåž‹ã«ã™ã‚‹ +(https://lwn.net/Articles/94386/) セクションをã“ã®ãƒ†ã‚ストã®åŽŸåž‹ã«ã™ã‚‹ ã“ã¨ã‚’許å¯ã—ã¦ãã‚Œã¾ã—ãŸã€‚Rundy Dunlap 㨠Gerrit Huizenga ã¯ãƒ¡ãƒ¼ãƒªãƒ³ã‚° リストã§ã‚„ã‚‹ã¹ãã“ã¨ã¨ã‚„ã£ã¦ã¯ã„ã‘ãªã„ã“ã¨ã®ãƒªã‚¹ãƒˆã‚’æä¾›ã—ã¦ãã‚Œã¾ã—ãŸã€‚ 以下ã®äººã€…ã®ãƒ¬ãƒ“ューã€ã‚³ãƒ¡ãƒ³ãƒˆã€è²¢çŒ®ã«æ„Ÿè¬ã€‚ @@ -634,4 +656,6 @@ Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael Kerrisk, 㨠Alex Shepard 彼らã®æ”¯æ´ãªã—ã§ã¯ã€ã“ã®ãƒ‰ã‚ュメントã¯ã§ããªã‹ã£ãŸã§ã—ょã†ã€‚ + + Maintainer: Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst new file mode 100644 index 000000000000..2f91b895e3c2 --- /dev/null +++ b/Documentation/translations/ja_JP/index.rst @@ -0,0 +1,12 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +Japanese translations +===================== + +.. toctree:: + :maxdepth: 1 + + howto diff --git a/Documentation/translations/zh_CN/sparse.txt b/Documentation/translations/zh_CN/sparse.txt index e41dc940e162..2f728962a8e2 100644 --- a/Documentation/translations/zh_CN/sparse.txt +++ b/Documentation/translations/zh_CN/sparse.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/sparse.txt +Chinese translated version of Documentation/dev-tools/sparse.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Li Yang <leo@zh-kernel.org> --------------------------------------------------------------------- -Documentation/sparse.txt çš„ä¸æ–‡ç¿»è¯‘ +Documentation/dev-tools/sparse.rst çš„ä¸æ–‡ç¿»è¯‘ 如果想评论或更新本文的内容，请直接è”ç³»åŽŸæ–‡æ¡£çš„ç»´æŠ¤è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ 交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘ä¸æ–‡ç‰ˆç»´æŠ¤è€…求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻 diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt index 17f5c2e1a570..903abca10517 100644 --- a/Documentation/usb/acm.txt +++ b/Documentation/usb/acm.txt @@ -64,7 +64,7 @@ minicom, ppp and mgetty with them. 2. Verifying that it works ~~~~~~~~~~~~~~~~~~~~~~~~~~ - The first step would be to check /proc/bus/usb/devices, it should look + The first step would be to check /sys/kernel/debug/usb/devices, it should look like this: T: Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 diff --git a/Documentation/usb/error-codes.txt b/Documentation/usb/error-codes.txt deleted file mode 100644 index 9c3eb845ebe5..000000000000 --- a/Documentation/usb/error-codes.txt +++ /dev/null @@ -1,175 +0,0 @@ -Revised: 2004-Oct-21 - -This is the documentation of (hopefully) all possible error codes (and -their interpretation) that can be returned from usbcore. - -Some of them are returned by the Host Controller Drivers (HCDs), which -device drivers only see through usbcore. As a rule, all the HCDs should -behave the same except for transfer speed dependent behaviors and the -way certain faults are reported. - - -************************************************************************** -* Error codes returned by usb_submit_urb * -************************************************************************** - -Non-USB-specific: - -0 URB submission went fine - --ENOMEM no memory for allocation of internal structures - -USB-specific: - --EBUSY The URB is already active. - --ENODEV specified USB-device or bus doesn't exist - --ENOENT specified interface or endpoint does not exist or - is not enabled - --ENXIO host controller driver does not support queuing of this type - of urb. (treat as a host controller bug.) - --EINVAL a) Invalid transfer type specified (or not supported) - b) Invalid or unsupported periodic transfer interval - c) ISO: attempted to change transfer interval - d) ISO: number_of_packets is < 0 - e) various other cases - --EXDEV ISO: URB_ISO_ASAP wasn't specified and all the frames - the URB would be scheduled in have already expired. - --EFBIG Host controller driver can't schedule that many ISO frames. - --EPIPE The pipe type specified in the URB doesn't match the - endpoint's actual type. - --EMSGSIZE (a) endpoint maxpacket size is zero; it is not usable - in the current interface altsetting. - (b) ISO packet is larger than the endpoint maxpacket. - (c) requested data transfer length is invalid: negative - or too large for the host controller. - --ENOSPC This request would overcommit the usb bandwidth reserved - for periodic transfers (interrupt, isochronous). - --ESHUTDOWN The device or host controller has been disabled due to some - problem that could not be worked around. - --EPERM Submission failed because urb->reject was set. - --EHOSTUNREACH URB was rejected because the device is suspended. - --ENOEXEC A control URB doesn't contain a Setup packet. - - -************************************************************************** -* Error codes returned by in urb->status * -* or in iso_frame_desc[n].status (for ISO) * -************************************************************************** - -USB device drivers may only test urb status values in completion handlers. -This is because otherwise there would be a race between HCDs updating -these values on one CPU, and device drivers testing them on another CPU. - -A transfer's actual_length may be positive even when an error has been -reported. That's because transfers often involve several packets, so that -one or more packets could finish before an error stops further endpoint I/O. - -For isochronous URBs, the urb status value is non-zero only if the URB is -unlinked, the device is removed, the host controller is disabled, or the total -transferred length is less than the requested length and the URB_SHORT_NOT_OK -flag is set. Completion handlers for isochronous URBs should only see -urb->status set to zero, -ENOENT, -ECONNRESET, -ESHUTDOWN, or -EREMOTEIO. -Individual frame descriptor status fields may report more status codes. - - -0 Transfer completed successfully - --ENOENT URB was synchronously unlinked by usb_unlink_urb - --EINPROGRESS URB still pending, no results yet - (That is, if drivers see this it's a bug.) - --EPROTO (*, **) a) bitstuff error - b) no response packet received within the - prescribed bus turn-around time - c) unknown USB error - --EILSEQ (*, **) a) CRC mismatch - b) no response packet received within the - prescribed bus turn-around time - c) unknown USB error - - Note that often the controller hardware does not - distinguish among cases a), b), and c), so a - driver cannot tell whether there was a protocol - error, a failure to respond (often caused by - device disconnect), or some other fault. - --ETIME (**) No response packet received within the prescribed - bus turn-around time. This error may instead be - reported as -EPROTO or -EILSEQ. - --ETIMEDOUT Synchronous USB message functions use this code - to indicate timeout expired before the transfer - completed, and no other error was reported by HC. - --EPIPE (**) Endpoint stalled. For non-control endpoints, - reset this status with usb_clear_halt(). - --ECOMM During an IN transfer, the host controller - received data from an endpoint faster than it - could be written to system memory - --ENOSR During an OUT transfer, the host controller - could not retrieve data from system memory fast - enough to keep up with the USB data rate - --EOVERFLOW (*) The amount of data returned by the endpoint was - greater than either the max packet size of the - endpoint or the remaining buffer size. "Babble". - --EREMOTEIO The data read from the endpoint did not fill the - specified buffer, and URB_SHORT_NOT_OK was set in - urb->transfer_flags. - --ENODEV Device was removed. Often preceded by a burst of - other errors, since the hub driver doesn't detect - device removal events immediately. - --EXDEV ISO transfer only partially completed - (only set in iso_frame_desc[n].status, not urb->status) - --EINVAL ISO madness, if this happens: Log off and go home - --ECONNRESET URB was asynchronously unlinked by usb_unlink_urb - --ESHUTDOWN The device or host controller has been disabled due - to some problem that could not be worked around, - such as a physical disconnect. - - -(*) Error codes like -EPROTO, -EILSEQ and -EOVERFLOW normally indicate -hardware problems such as bad devices (including firmware) or cables. - -(**) This is also one of several codes that different kinds of host -controller use to indicate a transfer has failed because of device -disconnect. In the interval before the hub driver starts disconnect -processing, devices may receive such fault reports for every request. - - - -************************************************************************** -* Error codes returned by usbcore-functions * -* (expect also other submit and transfer status codes) * -************************************************************************** - -usb_register(): --EINVAL error during registering new driver - -usb_get_*/usb_set_*(): -usb_control_msg(): -usb_bulk_msg(): --ETIMEDOUT Timeout expired before the transfer completed. diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index 6b4a88a8c8e3..d1def3186782 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -189,7 +189,7 @@ Once the gadget serial driver is loaded and the USB device connected to the Linux host with a USB cable, the host system should recognize the gadget serial device. For example, the command - cat /proc/bus/usb/devices + cat /sys/kernel/debug/usb/devices should show something like this: @@ -221,7 +221,7 @@ Once the gadget serial driver is loaded and the USB device connected to the Linux host with a USB cable, the host system should recognize the gadget serial device. For example, the command - cat /proc/bus/usb/devices + cat /sys/kernel/debug/usb/devices should show something like this: diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt deleted file mode 100644 index 98be91982677..000000000000 --- a/Documentation/usb/proc_usb_info.txt +++ /dev/null @@ -1,390 +0,0 @@ -/proc/bus/usb filesystem output -=============================== -(version 2010.09.13) - - -The usbfs filesystem for USB devices is traditionally mounted at -/proc/bus/usb. It provides the /proc/bus/usb/devices file, as well as -the /proc/bus/usb/BBB/DDD files. - -In many modern systems the usbfs filesystem isn't used at all. Instead -USB device nodes are created under /dev/usb/ or someplace similar. The -"devices" file is available in debugfs, typically as -/sys/kernel/debug/usb/devices. - - -**NOTE**: If /proc/bus/usb appears empty, and a host controller - driver has been linked, then you need to mount the - filesystem. Issue the command (as root): - - mount -t usbfs none /proc/bus/usb - - An alternative and more permanent method would be to add - - none /proc/bus/usb usbfs defaults 0 0 - - to /etc/fstab. This will mount usbfs at each reboot. - You can then issue `cat /proc/bus/usb/devices` to extract - USB device information, and user mode drivers can use usbfs - to interact with USB devices. - - There are a number of mount options supported by usbfs. - Consult the source code (linux/drivers/usb/core/inode.c) for - information about those options. - -**NOTE**: The filesystem has been renamed from "usbdevfs" to - "usbfs", to reduce confusion with "devfs". You may - still see references to the older "usbdevfs" name. - -For more information on mounting the usbfs file system, see the -"USB Device Filesystem" section of the USB Guide. The latest copy -of the USB Guide can be found at http://www.linux-usb.org/ - - -THE /proc/bus/usb/BBB/DDD FILES: --------------------------------- -Each connected USB device has one file. The BBB indicates the bus -number. The DDD indicates the device address on that bus. Both -of these numbers are assigned sequentially, and can be reused, so -you can't rely on them for stable access to devices. For example, -it's relatively common for devices to re-enumerate while they are -still connected (perhaps someone jostled their power supply, hub, -or USB cable), so a device might be 002/027 when you first connect -it and 002/048 sometime later. - -These files can be read as binary data. The binary data consists -of first the device descriptor, then the descriptors for each -configuration of the device. Multi-byte fields in the device descriptor -are converted to host endianness by the kernel. The configuration -descriptors are in bus endian format! The configuration descriptor -are wTotalLength bytes apart. If a device returns less configuration -descriptor data than indicated by wTotalLength there will be a hole in -the file for the missing bytes. This information is also shown -in text form by the /proc/bus/usb/devices file, described later. - -These files may also be used to write user-level drivers for the USB -devices. You would open the /proc/bus/usb/BBB/DDD file read/write, -read its descriptors to make sure it's the device you expect, and then -bind to an interface (or perhaps several) using an ioctl call. You -would issue more ioctls to the device to communicate to it using -control, bulk, or other kinds of USB transfers. The IOCTLs are -listed in the <linux/usbdevice_fs.h> file, and at this writing the -source code (linux/drivers/usb/core/devio.c) is the primary reference -for how to access devices through those files. - -Note that since by default these BBB/DDD files are writable only by -root, only root can write such user mode drivers. You can selectively -grant read/write permissions to other users by using "chmod". Also, -usbfs mount options such as "devmode=0666" may be helpful. - - - -THE /proc/bus/usb/devices FILE: -------------------------------- -In /proc/bus/usb/devices, each device's output has multiple -lines of ASCII output. -I made it ASCII instead of binary on purpose, so that someone -can obtain some useful data from it without the use of an -auxiliary program. However, with an auxiliary program, the numbers -in the first 4 columns of each "T:" line (topology info: -Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram. - -Each line is tagged with a one-character ID for that line: - -T = Topology (etc.) -B = Bandwidth (applies only to USB host controllers, which are - virtualized as root hubs) -D = Device descriptor info. -P = Product ID info. (from Device descriptor, but they won't fit - together on one line) -S = String descriptors. -C = Configuration descriptor info. (* = active configuration) -I = Interface descriptor info. -E = Endpoint descriptor info. - -======================================================================= - -/proc/bus/usb/devices output format: - -Legend: - d = decimal number (may have leading spaces or 0's) - x = hexadecimal number (may have leading spaces or 0's) - s = string - - -Topology info: - -T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=dddd MxCh=dd -| | | | | | | | |__MaxChildren -| | | | | | | |__Device Speed in Mbps -| | | | | | |__DeviceNumber -| | | | | |__Count of devices at this level -| | | | |__Connector/Port on Parent for this device -| | | |__Parent DeviceNumber -| | |__Level in topology for this bus -| |__Bus number -|__Topology info tag - - Speed may be: - 1.5 Mbit/s for low speed USB - 12 Mbit/s for full speed USB - 480 Mbit/s for high speed USB (added for USB 2.0); - also used for Wireless USB, which has no fixed speed - 5000 Mbit/s for SuperSpeed USB (added for USB 3.0) - - For reasons lost in the mists of time, the Port number is always - too low by 1. For example, a device plugged into port 4 will - show up with "Port=03". - -Bandwidth info: -B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd -| | | |__Number of isochronous requests -| | |__Number of interrupt requests -| |__Total Bandwidth allocated to this bus -|__Bandwidth info tag - - Bandwidth allocation is an approximation of how much of one frame - (millisecond) is in use. It reflects only periodic transfers, which - are the only transfers that reserve bandwidth. Control and bulk - transfers use all other bandwidth, including reserved bandwidth that - is not used for transfers (such as for short packets). - - The percentage is how much of the "reserved" bandwidth is scheduled by - those transfers. For a low or full speed bus (loosely, "USB 1.1"), - 90% of the bus bandwidth is reserved. For a high speed bus (loosely, - "USB 2.0") 80% is reserved. - - -Device descriptor info & Product ID info: - -D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd -P: Vendor=xxxx ProdID=xxxx Rev=xx.xx - -where -D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd -| | | | | | |__NumberConfigurations -| | | | | |__MaxPacketSize of Default Endpoint -| | | | |__DeviceProtocol -| | | |__DeviceSubClass -| | |__DeviceClass -| |__Device USB version -|__Device info tag #1 - -where -P: Vendor=xxxx ProdID=xxxx Rev=xx.xx -| | | |__Product revision number -| | |__Product ID code -| |__Vendor ID code -|__Device info tag #2 - - -String descriptor info: - -S: Manufacturer=ssss -| |__Manufacturer of this device as read from the device. -| For USB host controller drivers (virtual root hubs) this may -| be omitted, or (for newer drivers) will identify the kernel -| version and the driver which provides this hub emulation. -|__String info tag - -S: Product=ssss -| |__Product description of this device as read from the device. -| For older USB host controller drivers (virtual root hubs) this -| indicates the driver; for newer ones, it's a product (and vendor) -| description that often comes from the kernel's PCI ID database. -|__String info tag - -S: SerialNumber=ssss -| |__Serial Number of this device as read from the device. -| For USB host controller drivers (virtual root hubs) this is -| some unique ID, normally a bus ID (address or slot name) that -| can't be shared with any other device. -|__String info tag - - - -Configuration descriptor info: - -C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA -| | | | | |__MaxPower in mA -| | | | |__Attributes -| | | |__ConfiguratioNumber -| | |__NumberOfInterfaces -| |__ "*" indicates the active configuration (others are " ") -|__Config info tag - - USB devices may have multiple configurations, each of which act - rather differently. For example, a bus-powered configuration - might be much less capable than one that is self-powered. Only - one device configuration can be active at a time; most devices - have only one configuration. - - Each configuration consists of one or more interfaces. Each - interface serves a distinct "function", which is typically bound - to a different USB device driver. One common example is a USB - speaker with an audio interface for playback, and a HID interface - for use with software volume control. - - -Interface descriptor info (can be multiple per Config): - -I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss -| | | | | | | | |__Driver name -| | | | | | | | or "(none)" -| | | | | | | |__InterfaceProtocol -| | | | | | |__InterfaceSubClass -| | | | | |__InterfaceClass -| | | | |__NumberOfEndpoints -| | | |__AlternateSettingNumber -| | |__InterfaceNumber -| |__ "*" indicates the active altsetting (others are " ") -|__Interface info tag - - A given interface may have one or more "alternate" settings. - For example, default settings may not use more than a small - amount of periodic bandwidth. To use significant fractions - of bus bandwidth, drivers must select a non-default altsetting. - - Only one setting for an interface may be active at a time, and - only one driver may bind to an interface at a time. Most devices - have only one alternate setting per interface. - - -Endpoint descriptor info (can be multiple per Interface): - -E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss -| | | | |__Interval (max) between transfers -| | | |__EndpointMaxPacketSize -| | |__Attributes(EndpointType) -| |__EndpointAddress(I=In,O=Out) -|__Endpoint info tag - - The interval is nonzero for all periodic (interrupt or isochronous) - endpoints. For high speed endpoints the transfer interval may be - measured in microseconds rather than milliseconds. - - For high speed periodic endpoints, the "MaxPacketSize" reflects - the per-microframe data transfer size. For "high bandwidth" - endpoints, that can reflect two or three packets (for up to - 3KBytes every 125 usec) per endpoint. - - With the Linux-USB stack, periodic bandwidth reservations use the - transfer intervals and sizes provided by URBs, which can be less - than those found in endpoint descriptor. - - -======================================================================= - - -If a user or script is interested only in Topology info, for -example, use something like "grep ^T: /proc/bus/usb/devices" -for only the Topology lines. A command like -"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list -only the lines that begin with the characters in square brackets, -where the valid characters are TDPCIE. With a slightly more able -script, it can display any selected lines (for example, only T, D, -and P lines) and change their output format. (The "procusb" -Perl script is the beginning of this idea. It will list only -selected lines [selected from TBDPSCIE] or "All" lines from -/proc/bus/usb/devices.) - -The Topology lines can be used to generate a graphic/pictorial -of the USB devices on a system's root hub. (See more below -on how to do this.) - -The Interface lines can be used to determine what driver is -being used for each device, and which altsetting it activated. - -The Configuration lines could be used to list maximum power -(in milliamps) that a system's USB devices are using. -For example, "grep ^C: /proc/bus/usb/devices". - - -Here's an example, from a system which has a UHCI root hub, -an external hub connected to the root hub, and a mouse and -a serial converter connected to the external hub. - -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 -B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0 -D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0000 ProdID=0000 Rev= 0.00 -S: Product=USB UHCI Root Hub -S: SerialNumber=dce0 -C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms - -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 -D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0451 ProdID=1446 Rev= 1.00 -C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms - -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 -D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=04b4 ProdID=0001 Rev= 0.00 -C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse -E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms - -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 -D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0565 ProdID=0001 Rev= 1.08 -S: Manufacturer=Peracom Networks, Inc. -S: Product=Peracom USB to Serial Converter -C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA -I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial -E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms -E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms -E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms - - -Selecting only the "T:" and "I:" lines from this (for example, by using -"procusb ti"), we have: - -T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2 -T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4 -I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub -T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 -I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse -T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 -I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial - - -Physically this looks like (or could be converted to): - - +------------------+ - | PC/root_hub (12)| Dev# = 1 - +------------------+ (nn) is Mbps. - Level 0 | CN.0 | CN.1 | [CN = connector/port #] - +------------------+ - / - / - +-----------------------+ - Level 1 | Dev#2: 4-port hub (12)| - +-----------------------+ - |CN.0 |CN.1 |CN.2 |CN.3 | - +-----------------------+ - \ \____________________ - \_____ \ - \ \ - +--------------------+ +--------------------+ - Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)| - +--------------------+ +--------------------+ - - - -Or, in a more tree-like structure (ports [Connectors] without -connections could be omitted): - -PC: Dev# 1, root hub, 2 ports, 12 Mbps -|_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps - |_ CN.0: Dev #3, mouse, 1.5 Mbps - |_ CN.1: - |_ CN.2: Dev #4, serial, 12 Mbps - |_ CN.3: -|_ CN.1: - - - ### END ### diff --git a/Documentation/usb/typec.rst b/Documentation/usb/typec.rst new file mode 100644 index 000000000000..b67a46779de9 --- /dev/null +++ b/Documentation/usb/typec.rst @@ -0,0 +1,184 @@ + +USB Type-C connector class +========================== + +Introduction +------------ + +The typec class is meant for describing the USB Type-C ports in a system to the +user space in unified fashion. The class is designed to provide nothing else +except the user space interface implementation in hope that it can be utilized +on as many platforms as possible. + +The platforms are expected to register every USB Type-C port they have with the +class. In a normal case the registration will be done by a USB Type-C or PD PHY +driver, but it may be a driver for firmware interface such as UCSI, driver for +USB PD controller or even driver for Thunderbolt3 controller. This document +considers the component registering the USB Type-C ports with the class as "port +driver". + +On top of showing the capabilities, the class also offer user space control over +the roles and alternate modes of ports, partners and cable plugs when the port +driver is capable of supporting those features. + +The class provides an API for the port drivers described in this document. The +attributes are described in Documentation/ABI/testing/sysfs-class-typec. + +User space interface +-------------------- +Every port will be presented as its own device under /sys/class/typec/. The +first port will be named "port0", the second "port1" and so on. + +When connected, the partner will be presented also as its own device under +/sys/class/typec/. The parent of the partner device will always be the port it +is attached to. The partner attached to port "port0" will be named +"port0-partner". Full path to the device would be +/sys/class/typec/port0/port0-partner/. + +The cable and the two plugs on it may also be optionally presented as their own +devices under /sys/class/typec/. The cable attached to the port "port0" port +will be named port0-cable and the plug on the SOP Prime end (see USB Power +Delivery Specification ch. 2.4) will be named "port0-plug0" and on the SOP +Double Prime end "port0-plug1". The parent of a cable will always be the port, +and the parent of the cable plugs will always be the cable. + +If the port, partner or cable plug supports Alternate Modes, every supported +Alternate Mode SVID will have their own device describing them. Note that the +Alternate Mode devices will not be attached to the typec class. The parent of an +alternate mode will be the device that supports it, so for example an alternate +mode of port0-partner will be presented under /sys/class/typec/port0-partner/. +Every mode that is supported will have its own group under the Alternate Mode +device named "mode<index>", for example /sys/class/typec/port0/<alternate +mode>/mode1/. The requests for entering/exiting a mode can be done with "active" +attribute file in that group. + +Driver API +---------- + +Registering the ports +~~~~~~~~~~~~~~~~~~~~~ + +The port drivers will describe every Type-C port they control with struct +typec_capability data structure, and register them with the following API: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_register_port typec_unregister_port + +When registering the ports, the prefer_role member in struct typec_capability +deserves special notice. If the port that is being registered does not have +initial role preference, which means the port does not execute Try.SNK or +Try.SRC by default, the member must have value TYPEC_NO_PREFERRED_ROLE. +Otherwise if the port executes Try.SNK by default, the member must have value +TYPEC_DEVICE, and with Try.SRC the value must be TYPEC_HOST. + +Registering Partners +~~~~~~~~~~~~~~~~~~~~ + +After successful connection of a partner, the port driver needs to register the +partner with the class. Details about the partner need to be described in struct +typec_partner_desc. The class copies the details of the partner during +registration. The class offers the following API for registering/unregistering +partners. + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_register_partner typec_unregister_partner + +The class will provide a handle to struct typec_partner if the registration was +successful, or NULL. + +If the partner is USB Power Delivery capable, and the port driver is able to +show the result of Discover Identity command, the partner descriptor structure +should include handle to struct usb_pd_identity instance. The class will then +create a sysfs directory for the identity under the partner device. The result +of Discover Identity command can then be reported with the following API: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_partner_set_identity + +Registering Cables +~~~~~~~~~~~~~~~~~~ + +After successful connection of a cable that supports USB Power Delivery +Structured VDM "Discover Identity", the port driver needs to register the cable +and one or two plugs, depending if there is CC Double Prime controller present +in the cable or not. So a cable capable of SOP Prime communication, but not SOP +Double Prime communication, should only have one plug registered. For more +information about SOP communication, please read chapter about it from the +latest USB Power Delivery specification. + +The plugs are represented as their own devices. The cable is registered first, +followed by registration of the cable plugs. The cable will be the parent device +for the plugs. Details about the cable need to be described in struct +typec_cable_desc and about a plug in struct typec_plug_desc. The class copies +the details during registration. The class offers the following API for +registering/unregistering cables and their plugs: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_register_cable typec_unregister_cable typec_register_plug + typec_unregister_plug + +The class will provide a handle to struct typec_cable and struct typec_plug if +the registration is successful, or NULL if it isn't. + +If the cable is USB Power Delivery capable, and the port driver is able to show +the result of Discover Identity command, the cable descriptor structure should +include handle to struct usb_pd_identity instance. The class will then create a +sysfs directory for the identity under the cable device. The result of Discover +Identity command can then be reported with the following API: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_cable_set_identity + +Notifications +~~~~~~~~~~~~~ + +When the partner has executed a role change, or when the default roles change +during connection of a partner or cable, the port driver must use the following +APIs to report it to the class: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role + typec_set_pwr_opmode + +Alternate Modes +~~~~~~~~~~~~~~~ + +USB Type-C ports, partners and cable plugs may support Alternate Modes. Each +Alternate Mode will have identifier called SVID, which is either a Standard ID +given by USB-IF or vendor ID, and each supported SVID can have 1 - 6 modes. The +class provides struct typec_mode_desc for describing individual mode of a SVID, +and struct typec_altmode_desc which is a container for all the supported modes. + +Ports that support Alternate Modes need to register each SVID they support with +the following API: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_port_register_altmode + +If a partner or cable plug provides a list of SVIDs as response to USB Power +Delivery Structured VDM Discover SVIDs message, each SVID needs to be +registered. + +API for the partners: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_partner_register_altmode + +API for the Cable Plugs: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_plug_register_altmode + +So ports, partners and cable plugs will register the alternate modes with their +own functions, but the registration will always return a handle to struct +typec_altmode on success, or NULL. The unregistration will happen with the same +function: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_unregister_altmode + +If a partner or cable plug enters or exits a mode, the port driver needs to +notify the class with the following API: + +.. kernel-doc:: drivers/usb/typec/typec.c + :functions: typec_altmode_update_active diff --git a/Documentation/usb/usb3-debug-port.rst b/Documentation/usb/usb3-debug-port.rst new file mode 100644 index 000000000000..feb1a36a65b7 --- /dev/null +++ b/Documentation/usb/usb3-debug-port.rst @@ -0,0 +1,100 @@ +=============== +USB3 debug port +=============== + +:Author: Lu Baolu <baolu.lu@linux.intel.com> +:Date: March 2017 + +GENERAL +======= + +This is a HOWTO for using the USB3 debug port on x86 systems. + +Before using any kernel debugging functionality based on USB3 +debug port, you need to:: + + 1) check whether any USB3 debug port is available in + your system; + 2) check which port is used for debugging purposes; + 3) have a USB 3.0 super-speed A-to-A debugging cable. + +INTRODUCTION +============ + +The xHCI debug capability (DbC) is an optional but standalone +functionality provided by the xHCI host controller. The xHCI +specification describes DbC in the section 7.6. + +When DbC is initialized and enabled, it will present a debug +device through the debug port (normally the first USB3 +super-speed port). The debug device is fully compliant with +the USB framework and provides the equivalent of a very high +performance full-duplex serial link between the debug target +(the system under debugging) and a debug host. + +EARLY PRINTK +============ + +DbC has been designed to log early printk messages. One use for +this feature is kernel debugging. For example, when your machine +crashes very early before the regular console code is initialized. +Other uses include simpler, lockless logging instead of a full- +blown printk console driver and klogd. + +On the debug target system, you need to customize a debugging +kernel with CONFIG_EARLY_PRINTK_USB_XDBC enabled. And, add below +kernel boot parameter:: + + "earlyprintk=xdbc" + +If there are multiple xHCI controllers in your system, you can +append a host contoller index to this kernel parameter. This +index starts from 0. + +Current design doesn't support DbC runtime suspend/resume. As +the result, you'd better disable runtime power management for +USB subsystem by adding below kernel boot parameter:: + + "usbcore.autosuspend=-1" + +Before starting the debug target, you should connect the debug +port to a USB port (root port or port of any external hub) on +the debug host. The cable used to connect these two ports +should be a USB 3.0 super-speed A-to-A debugging cable. + +During early boot of the debug target, DbC will be detected and +initialized. After initialization, the debug host should be able +to enumerate the debug device in debug target. The debug host +will then bind the debug device with the usb_debug driver module +and create the /dev/ttyUSB device. + +If the debug device enumeration goes smoothly, you should be able +to see below kernel messages on the debug host:: + + # tail -f /var/log/kern.log + [ 1815.983374] usb 4-3: new SuperSpeed USB device number 4 using xhci_hcd + [ 1815.999595] usb 4-3: LPM exit latency is zeroed, disabling LPM. + [ 1815.999899] usb 4-3: New USB device found, idVendor=1d6b, idProduct=0004 + [ 1815.999902] usb 4-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 1815.999903] usb 4-3: Product: Remote GDB + [ 1815.999904] usb 4-3: Manufacturer: Linux + [ 1815.999905] usb 4-3: SerialNumber: 0001 + [ 1816.000240] usb_debug 4-3:1.0: xhci_dbc converter detected + [ 1816.000360] usb 4-3: xhci_dbc converter now attached to ttyUSB0 + +You can use any communication program, for example minicom, to +read and view the messages. Below simple bash scripts can help +you to check the sanity of the setup. + +.. code-block:: sh + + ===== start of bash scripts ============= + #!/bin/bash + + while true ; do + while [ ! -d /sys/class/tty/ttyUSB0 ] ; do + : + done + cat /dev/ttyUSB0 + done + ===== end of bash scripts =============== diff --git a/Documentation/userspace-api/conf.py b/Documentation/userspace-api/conf.py new file mode 100644 index 000000000000..2eaf59f844e5 --- /dev/null +++ b/Documentation/userspace-api/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = "The Linux kernel user-space API guide" + +tags.add("subproject") + +latex_documents = [ + ('index', 'userspace-api.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst new file mode 100644 index 000000000000..a9d01b44a659 --- /dev/null +++ b/Documentation/userspace-api/index.rst @@ -0,0 +1,26 @@ +===================================== +The Linux kernel user-space API guide +===================================== + +.. _man-pages: https://www.kernel.org/doc/man-pages/ + +While much of the kernel's user-space API is documented elsewhere +(particularly in the man-pages_ project), some user-space information can +also be found in the kernel tree itself. This manual is intended to be the +place where this information is gathered. + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + + unshare + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/unshare.txt b/Documentation/userspace-api/unshare.rst index a8643513a5f6..737c192cf4e7 100644 --- a/Documentation/unshare.txt +++ b/Documentation/userspace-api/unshare.rst @@ -1,17 +1,17 @@ +unshare system call +=================== -unshare system call: --------------------- -This document describes the new system call, unshare. The document +This document describes the new system call, unshare(). The document provides an overview of the feature, why it is needed, how it can be used, its interface specification, design, implementation and how it can be tested. -Change Log: ------------ +Change Log +---------- version 0.1 Initial document, Janak Desai (janak@us.ibm.com), Jan 11, 2006 -Contents: ---------- +Contents +-------- 1) Overview 2) Benefits 3) Cost @@ -24,6 +24,7 @@ Contents: 1) Overview ----------- + Most legacy operating system kernels support an abstraction of threads as multiple execution contexts within a process. These kernels provide special resources and mechanisms to maintain these "threads". The Linux @@ -38,33 +39,35 @@ threads. On Linux, at the time of thread creation using the clone system call, applications can selectively choose which resources to share between threads. -unshare system call adds a primitive to the Linux thread model that +unshare() system call adds a primitive to the Linux thread model that allows threads to selectively 'unshare' any resources that were being -shared at the time of their creation. unshare was conceptualized by +shared at the time of their creation. unshare() was conceptualized by Al Viro in the August of 2000, on the Linux-Kernel mailing list, as part -of the discussion on POSIX threads on Linux. unshare augments the +of the discussion on POSIX threads on Linux. unshare() augments the usefulness of Linux threads for applications that would like to control -shared resources without creating a new process. unshare is a natural +shared resources without creating a new process. unshare() is a natural addition to the set of available primitives on Linux that implement the concept of process/thread as a virtual machine. 2) Benefits ----------- -unshare would be useful to large application frameworks such as PAM + +unshare() would be useful to large application frameworks such as PAM where creating a new process to control sharing/unsharing of process resources is not possible. Since namespaces are shared by default -when creating a new process using fork or clone, unshare can benefit +when creating a new process using fork or clone, unshare() can benefit even non-threaded applications if they have a need to disassociate from default shared namespace. The following lists two use-cases -where unshare can be used. +where unshare() can be used. 2.1 Per-security context namespaces ------------------------------------ -unshare can be used to implement polyinstantiated directories using +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +unshare() can be used to implement polyinstantiated directories using the kernel's per-process namespace mechanism. Polyinstantiated directories, such as per-user and/or per-security context instance of /tmp, /var/tmp or per-security context instance of a user's home directory, isolate user -processes when working with these directories. Using unshare, a PAM +processes when working with these directories. Using unshare(), a PAM module can easily setup a private namespace for a user at login. Polyinstantiated directories are required for Common Criteria certification with Labeled System Protection Profile, however, with the availability @@ -74,33 +77,36 @@ polyinstantiating /tmp, /var/tmp and other directories deemed appropriate by system administrators. 2.2 unsharing of virtual memory and/or open files -------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Consider a client/server application where the server is processing client requests by creating processes that share resources such as -virtual memory and open files. Without unshare, the server has to +virtual memory and open files. Without unshare(), the server has to decide what needs to be shared at the time of creating the process -which services the request. unshare allows the server an ability to +which services the request. unshare() allows the server an ability to disassociate parts of the context during the servicing of the request. For large and complex middleware application frameworks, this -ability to unshare after the process was created can be very +ability to unshare() after the process was created can be very useful. 3) Cost ------- -In order to not duplicate code and to handle the fact that unshare + +In order to not duplicate code and to handle the fact that unshare() works on an active task (as opposed to clone/fork working on a newly -allocated inactive task) unshare had to make minor reorganizational +allocated inactive task) unshare() had to make minor reorganizational changes to copy_* functions utilized by clone/fork system call. There is a cost associated with altering existing, well tested and stable code to implement a new feature that may not get exercised extensively in the beginning. However, with proper design and code -review of the changes and creation of an unshare test for the LTP +review of the changes and creation of an unshare() test for the LTP the benefits of this new feature can exceed its cost. 4) Requirements --------------- -unshare reverses sharing that was done using clone(2) system call, -so unshare should have a similar interface as clone(2). That is, + +unshare() reverses sharing that was done using clone(2) system call, +so unshare() should have a similar interface as clone(2). That is, since flags in clone(int flags, void *stack) specifies what should be shared, similar flags in unshare(int flags) should specify what should be unshared. Unfortunately, this may appear to invert @@ -108,13 +114,14 @@ the meaning of the flags from the way they are used in clone(2). However, there was no easy solution that was less confusing and that allowed incremental context unsharing in future without an ABI change. -unshare interface should accommodate possible future addition of +unshare() interface should accommodate possible future addition of new context flags without requiring a rebuild of old applications. -If and when new context flags are added, unshare design should allow +If and when new context flags are added, unshare() design should allow incremental unsharing of those resources on an as needed basis. 5) Functional Specification --------------------------- + NAME unshare - disassociate parts of the process execution context @@ -124,7 +131,7 @@ SYNOPSIS int unshare(int flags); DESCRIPTION - unshare allows a process to disassociate parts of its execution + unshare() allows a process to disassociate parts of its execution context that are currently being shared with other processes. Part of execution context, such as the namespace, is shared by default when a new process is created using fork(2), while other parts, @@ -132,7 +139,7 @@ DESCRIPTION shared by explicit request to share them when creating a process using clone(2). - The main use of unshare is to allow a process to control its + The main use of unshare() is to allow a process to control its shared execution context without creating a new process. The flags argument specifies one or bitwise-or'ed of several of @@ -176,17 +183,20 @@ SEE ALSO 6) High Level Design -------------------- -Depending on the flags argument, the unshare system call allocates + +Depending on the flags argument, the unshare() system call allocates appropriate process context structures, populates it with values from the current shared version, associates newly duplicated structures with the current task structure and releases corresponding shared versions. Helper functions of clone (copy_*) could not be used -directly by unshare because of the following two reasons. +directly by unshare() because of the following two reasons. + 1) clone operates on a newly allocated not-yet-active task - structure, where as unshare operates on the current active - task. Therefore unshare has to take appropriate task_lock() + structure, where as unshare() operates on the current active + task. Therefore unshare() has to take appropriate task_lock() before associating newly duplicated context structures - 2) unshare has to allocate and duplicate all context structures + + 2) unshare() has to allocate and duplicate all context structures that are being unshared, before associating them with the current task and releasing older shared structures. Failure do so will create race conditions and/or oops when trying @@ -202,94 +212,121 @@ Therefore code from copy_* functions that allocated and duplicated current context structure was moved into new dup_* functions. Now, copy_* functions call dup_* functions to allocate and duplicate appropriate context structures and then associate them with the -task structure that is being constructed. unshare system call on +task structure that is being constructed. unshare() system call on the other hand performs the following: + 1) Check flags to force missing, but implied, flags - 2) For each context structure, call the corresponding unshare + + 2) For each context structure, call the corresponding unshare() helper function to allocate and duplicate a new context structure, if the appropriate bit is set in the flags argument. + 3) If there is no error in allocation and duplication and there are new context structures then lock the current task structure, associate new context structures with the current task structure, and release the lock on the current task structure. + 4) Appropriately release older, shared, context structures. 7) Low Level Design ------------------- -Implementation of unshare can be grouped in the following 4 different + +Implementation of unshare() can be grouped in the following 4 different items: + a) Reorganization of existing copy_* functions - b) unshare system call service function - c) unshare helper functions for each different process context + + b) unshare() system call service function + + c) unshare() helper functions for each different process context + d) Registration of system call number for different architectures - 7.1) Reorganization of copy_* functions - Each copy function such as copy_mm, copy_namespace, copy_files, - etc, had roughly two components. The first component allocated - and duplicated the appropriate structure and the second component - linked it to the task structure passed in as an argument to the copy - function. The first component was split into its own function. - These dup_* functions allocated and duplicated the appropriate - context structure. The reorganized copy_* functions invoked - their corresponding dup_* functions and then linked the newly - duplicated structures to the task structure with which the - copy function was called. - - 7.2) unshare system call service function +7.1) Reorganization of copy_* functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each copy function such as copy_mm, copy_namespace, copy_files, +etc, had roughly two components. The first component allocated +and duplicated the appropriate structure and the second component +linked it to the task structure passed in as an argument to the copy +function. The first component was split into its own function. +These dup_* functions allocated and duplicated the appropriate +context structure. The reorganized copy_* functions invoked +their corresponding dup_* functions and then linked the newly +duplicated structures to the task structure with which the +copy function was called. + +7.2) unshare() system call service function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * Check flags Force implied flags. If CLONE_THREAD is set force CLONE_VM. If CLONE_VM is set, force CLONE_SIGHAND. If CLONE_SIGHAND is set and signals are also being shared, force CLONE_THREAD. If CLONE_NEWNS is set, force CLONE_FS. + * For each context flag, invoke the corresponding unshare_* helper routine with flags passed into the system call and a reference to pointer pointing the new unshared structure + * If any new structures are created by unshare_* helper functions, take the task_lock() on the current task, modify appropriate context pointers, and release the task lock. + * For all newly unshared structures, release the corresponding older, shared, structures. - 7.3) unshare_* helper functions - For unshare_* helpers corresponding to CLONE_SYSVSEM, CLONE_SIGHAND, - and CLONE_THREAD, return -EINVAL since they are not implemented yet. - For others, check the flag value to see if the unsharing is - required for that structure. If it is, invoke the corresponding - dup_* function to allocate and duplicate the structure and return - a pointer to it. +7.3) unshare_* helper functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 7.4) Appropriately modify architecture specific code to register the - new system call. +For unshare_* helpers corresponding to CLONE_SYSVSEM, CLONE_SIGHAND, +and CLONE_THREAD, return -EINVAL since they are not implemented yet. +For others, check the flag value to see if the unsharing is +required for that structure. If it is, invoke the corresponding +dup_* function to allocate and duplicate the structure and return +a pointer to it. + +7.4) Finally +~~~~~~~~~~~~ + +Appropriately modify architecture specific code to register the +new system call. 8) Test Specification --------------------- -The test for unshare should test the following: + +The test for unshare() should test the following: + 1) Valid flags: Test to check that clone flags for signal and - signal handlers, for which unsharing is not implemented - yet, return -EINVAL. + signal handlers, for which unsharing is not implemented + yet, return -EINVAL. + 2) Missing/implied flags: Test to make sure that if unsharing - namespace without specifying unsharing of filesystem, correctly - unshares both namespace and filesystem information. + namespace without specifying unsharing of filesystem, correctly + unshares both namespace and filesystem information. + 3) For each of the four (namespace, filesystem, files and vm) - supported unsharing, verify that the system call correctly - unshares the appropriate structure. Verify that unsharing - them individually as well as in combination with each - other works as expected. + supported unsharing, verify that the system call correctly + unshares the appropriate structure. Verify that unsharing + them individually as well as in combination with each + other works as expected. + 4) Concurrent execution: Use shared memory segments and futex on - an address in the shm segment to synchronize execution of - about 10 threads. Have a couple of threads execute execve, - a couple _exit and the rest unshare with different combination - of flags. Verify that unsharing is performed as expected and - that there are no oops or hangs. + an address in the shm segment to synchronize execution of + about 10 threads. Have a couple of threads execute execve, + a couple _exit and the rest unshare with different combination + of flags. Verify that unsharing is performed as expected and + that there are no oops or hangs. 9) Future Work -------------- -The current implementation of unshare does not allow unsharing of + +The current implementation of unshare() does not allow unsharing of signals and signal handlers. Signals are complex to begin with and to unshare signals and/or signal handlers of a currently running process is even more complex. If in the future there is a specific need to allow unsharing of signals and/or signal handlers, it can -be incrementally added to unshare without affecting legacy -applications using unshare. +be incrementally added to unshare() without affecting legacy +applications using unshare(). diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt index d226c7a5ba8b..e5e57b40f8af 100644 --- a/Documentation/vfio-mediated-device.txt +++ b/Documentation/vfio-mediated-device.txt @@ -217,9 +217,9 @@ Directories and files under the sysfs for Each Physical Device * [<type-id>] - The [<type-id>] name is created by adding the the device driver string as a - prefix to the string provided by the vendor driver. This format of this name - is as follows: + The [<type-id>] name is created by adding the device driver string as a prefix + to the string provided by the vendor driver. This format of this name is as + follows: sprintf(buf, "%s-%s", dev_driver_string(parent->dev), group->name); @@ -380,7 +380,7 @@ card. /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10 /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10 -6. Using a minicom or any terminal enulation program, open port /dev/ttyS1 or +6. Using minicom or any terminal emulation program, open port /dev/ttyS1 or /dev/ttyS2 with hardware flow control disabled. 7. Type data on the minicom terminal or send data to the terminal emulation diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index 3c248f772ae6..4029943887a3 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -110,17 +110,18 @@ Type: system ioctl Parameters: machine type identifier (KVM_VM_*) Returns: a VM fd that can be used to control the new virtual machine. -The new VM has no virtual cpus and no memory. An mmap() of a VM fd -will access the virtual machine's physical address space; offset zero -corresponds to guest physical address zero. Use of mmap() on a VM fd -is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is -available. -You most certainly want to use 0 as machine type. +The new VM has no virtual cpus and no memory. +You probably want to use 0 as machine type. In order to create user controlled virtual machines on S390, check KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as privileged user (CAP_SYS_ADMIN). +To use hardware assisted virtualization on MIPS (VZ ASE) rather than +the default trap & emulate implementation (which changes the virtual +memory layout to fit in user mode), check KVM_CAP_MIPS_VZ and use the +flag KVM_VM_MIPS_VZ. + 4.3 KVM_GET_MSR_INDEX_LIST @@ -1321,130 +1322,6 @@ The flags bitmap is defined as: /* the host supports the ePAPR idle hcall #define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0) -4.48 KVM_ASSIGN_PCI_DEVICE (deprecated) - -Capability: none -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_assigned_pci_dev (in) -Returns: 0 on success, -1 on error - -Assigns a host PCI device to the VM. - -struct kvm_assigned_pci_dev { - __u32 assigned_dev_id; - __u32 busnr; - __u32 devfn; - __u32 flags; - __u32 segnr; - union { - __u32 reserved[11]; - }; -}; - -The PCI device is specified by the triple segnr, busnr, and devfn. -Identification in succeeding service requests is done via assigned_dev_id. The -following flags are specified: - -/* Depends on KVM_CAP_IOMMU */ -#define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0) -/* The following two depend on KVM_CAP_PCI_2_3 */ -#define KVM_DEV_ASSIGN_PCI_2_3 (1 << 1) -#define KVM_DEV_ASSIGN_MASK_INTX (1 << 2) - -If KVM_DEV_ASSIGN_PCI_2_3 is set, the kernel will manage legacy INTx interrupts -via the PCI-2.3-compliant device-level mask, thus enable IRQ sharing with other -assigned devices or host devices. KVM_DEV_ASSIGN_MASK_INTX specifies the -guest's view on the INTx mask, see KVM_ASSIGN_SET_INTX_MASK for details. - -The KVM_DEV_ASSIGN_ENABLE_IOMMU flag is a mandatory option to ensure -isolation of the device. Usages not specifying this flag are deprecated. - -Only PCI header type 0 devices with PCI BAR resources are supported by -device assignment. The user requesting this ioctl must have read/write -access to the PCI sysfs resource files associated with the device. - -Errors: - ENOTTY: kernel does not support this ioctl - - Other error conditions may be defined by individual device types or - have their standard meanings. - - -4.49 KVM_DEASSIGN_PCI_DEVICE (deprecated) - -Capability: none -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_assigned_pci_dev (in) -Returns: 0 on success, -1 on error - -Ends PCI device assignment, releasing all associated resources. - -See KVM_ASSIGN_PCI_DEVICE for the data structure. Only assigned_dev_id is -used in kvm_assigned_pci_dev to identify the device. - -Errors: - ENOTTY: kernel does not support this ioctl - - Other error conditions may be defined by individual device types or - have their standard meanings. - -4.50 KVM_ASSIGN_DEV_IRQ (deprecated) - -Capability: KVM_CAP_ASSIGN_DEV_IRQ -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_assigned_irq (in) -Returns: 0 on success, -1 on error - -Assigns an IRQ to a passed-through device. - -struct kvm_assigned_irq { - __u32 assigned_dev_id; - __u32 host_irq; /* ignored (legacy field) */ - __u32 guest_irq; - __u32 flags; - union { - __u32 reserved[12]; - }; -}; - -The following flags are defined: - -#define KVM_DEV_IRQ_HOST_INTX (1 << 0) -#define KVM_DEV_IRQ_HOST_MSI (1 << 1) -#define KVM_DEV_IRQ_HOST_MSIX (1 << 2) - -#define KVM_DEV_IRQ_GUEST_INTX (1 << 8) -#define KVM_DEV_IRQ_GUEST_MSI (1 << 9) -#define KVM_DEV_IRQ_GUEST_MSIX (1 << 10) - -It is not valid to specify multiple types per host or guest IRQ. However, the -IRQ type of host and guest can differ or can even be null. - -Errors: - ENOTTY: kernel does not support this ioctl - - Other error conditions may be defined by individual device types or - have their standard meanings. - - -4.51 KVM_DEASSIGN_DEV_IRQ (deprecated) - -Capability: KVM_CAP_ASSIGN_DEV_IRQ -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_assigned_irq (in) -Returns: 0 on success, -1 on error - -Ends an IRQ assignment to a passed-through device. - -See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified -by assigned_dev_id, flags must correspond to the IRQ type specified on -KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed. - - 4.52 KVM_SET_GSI_ROUTING Capability: KVM_CAP_IRQ_ROUTING @@ -1531,52 +1408,6 @@ struct kvm_irq_routing_hv_sint { __u32 sint; }; -4.53 KVM_ASSIGN_SET_MSIX_NR (deprecated) - -Capability: none -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_assigned_msix_nr (in) -Returns: 0 on success, -1 on error - -Set the number of MSI-X interrupts for an assigned device. The number is -reset again by terminating the MSI-X assignment of the device via -KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier -point will fail. - -struct kvm_assigned_msix_nr { - __u32 assigned_dev_id; - __u16 entry_nr; - __u16 padding; -}; - -#define KVM_MAX_MSIX_PER_DEV 256 - - -4.54 KVM_ASSIGN_SET_MSIX_ENTRY (deprecated) - -Capability: none -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_assigned_msix_entry (in) -Returns: 0 on success, -1 on error - -Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting -the GSI vector to zero means disabling the interrupt. - -struct kvm_assigned_msix_entry { - __u32 assigned_dev_id; - __u32 gsi; - __u16 entry; /* The index of entry in the MSI-X table */ - __u16 padding[3]; -}; - -Errors: - ENOTTY: kernel does not support this ioctl - - Other error conditions may be defined by individual device types or - have their standard meanings. - 4.55 KVM_SET_TSC_KHZ @@ -1728,40 +1559,6 @@ should skip processing the bitmap and just invalidate everything. It must be set to the number of set bits in the bitmap. -4.61 KVM_ASSIGN_SET_INTX_MASK (deprecated) - -Capability: KVM_CAP_PCI_2_3 -Architectures: x86 -Type: vm ioctl -Parameters: struct kvm_assigned_pci_dev (in) -Returns: 0 on success, -1 on error - -Allows userspace to mask PCI INTx interrupts from the assigned device. The -kernel will not deliver INTx interrupts to the guest between setting and -clearing of KVM_ASSIGN_SET_INTX_MASK via this interface. This enables use of -and emulation of PCI 2.3 INTx disable command register behavior. - -This may be used for both PCI 2.3 devices supporting INTx disable natively and -older devices lacking this support. Userspace is responsible for emulating the -read value of the INTx disable bit in the guest visible PCI command register. -When modifying the INTx disable state, userspace should precede updating the -physical device command register by calling this ioctl to inform the kernel of -the new intended INTx mask state. - -Note that the kernel uses the device INTx disable bit to internally manage the -device interrupt state for PCI 2.3 devices. Reads of this register may -therefore not match the expected value. Writes should always use the guest -intended INTx disable value rather than attempting to read-copy-update the -current physical device state. Races between user and kernel updates to the -INTx disable bit are handled lazily in the kernel. It's possible the device -may generate unintended interrupts, but they will not be injected into the -guest. - -See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified -by assigned_dev_id. In the flags field, only KVM_DEV_ASSIGN_MASK_INTX is -evaluated. - - 4.62 KVM_CREATE_SPAPR_TCE Capability: KVM_CAP_SPAPR_TCE @@ -2068,11 +1865,23 @@ registers, find a list below: MIPS | KVM_REG_MIPS_CP0_ENTRYLO0 | 64 MIPS | KVM_REG_MIPS_CP0_ENTRYLO1 | 64 MIPS | KVM_REG_MIPS_CP0_CONTEXT | 64 + MIPS | KVM_REG_MIPS_CP0_CONTEXTCONFIG| 32 MIPS | KVM_REG_MIPS_CP0_USERLOCAL | 64 + MIPS | KVM_REG_MIPS_CP0_XCONTEXTCONFIG| 64 MIPS | KVM_REG_MIPS_CP0_PAGEMASK | 32 + MIPS | KVM_REG_MIPS_CP0_PAGEGRAIN | 32 + MIPS | KVM_REG_MIPS_CP0_SEGCTL0 | 64 + MIPS | KVM_REG_MIPS_CP0_SEGCTL1 | 64 + MIPS | KVM_REG_MIPS_CP0_SEGCTL2 | 64 + MIPS | KVM_REG_MIPS_CP0_PWBASE | 64 + MIPS | KVM_REG_MIPS_CP0_PWFIELD | 64 + MIPS | KVM_REG_MIPS_CP0_PWSIZE | 64 MIPS | KVM_REG_MIPS_CP0_WIRED | 32 + MIPS | KVM_REG_MIPS_CP0_PWCTL | 32 MIPS | KVM_REG_MIPS_CP0_HWRENA | 32 MIPS | KVM_REG_MIPS_CP0_BADVADDR | 64 + MIPS | KVM_REG_MIPS_CP0_BADINSTR | 32 + MIPS | KVM_REG_MIPS_CP0_BADINSTRP | 32 MIPS | KVM_REG_MIPS_CP0_COUNT | 32 MIPS | KVM_REG_MIPS_CP0_ENTRYHI | 64 MIPS | KVM_REG_MIPS_CP0_COMPARE | 32 @@ -2089,6 +1898,7 @@ registers, find a list below: MIPS | KVM_REG_MIPS_CP0_CONFIG4 | 32 MIPS | KVM_REG_MIPS_CP0_CONFIG5 | 32 MIPS | KVM_REG_MIPS_CP0_CONFIG7 | 32 + MIPS | KVM_REG_MIPS_CP0_XCONTEXT | 64 MIPS | KVM_REG_MIPS_CP0_ERROREPC | 64 MIPS | KVM_REG_MIPS_CP0_KSCRATCH1 | 64 MIPS | KVM_REG_MIPS_CP0_KSCRATCH2 | 64 @@ -2096,6 +1906,7 @@ registers, find a list below: MIPS | KVM_REG_MIPS_CP0_KSCRATCH4 | 64 MIPS | KVM_REG_MIPS_CP0_KSCRATCH5 | 64 MIPS | KVM_REG_MIPS_CP0_KSCRATCH6 | 64 + MIPS | KVM_REG_MIPS_CP0_MAAR(0..63) | 64 MIPS | KVM_REG_MIPS_COUNT_CTL | 64 MIPS | KVM_REG_MIPS_COUNT_RESUME | 64 MIPS | KVM_REG_MIPS_COUNT_HZ | 64 @@ -2162,6 +1973,10 @@ hardware, host kernel, guest, and whether XPA is present in the guest, i.e. with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and the PFNX field starting at bit 30. +MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit +patterns: + 0x7030 0000 0001 01 <reg:8> + MIPS KVM control registers (see above) have the following id bit patterns: 0x7030 0000 0002 <reg:16> @@ -3377,6 +3192,69 @@ struct kvm_ppc_resize_hpt { __u32 pad; }; +4.104 KVM_X86_GET_MCE_CAP_SUPPORTED + +Capability: KVM_CAP_MCE +Architectures: x86 +Type: system ioctl +Parameters: u64 mce_cap (out) +Returns: 0 on success, -1 on error + +Returns supported MCE capabilities. The u64 mce_cap parameter +has the same format as the MSR_IA32_MCG_CAP register. Supported +capabilities will have the corresponding bits set. + +4.105 KVM_X86_SETUP_MCE + +Capability: KVM_CAP_MCE +Architectures: x86 +Type: vcpu ioctl +Parameters: u64 mcg_cap (in) +Returns: 0 on success, + -EFAULT if u64 mcg_cap cannot be read, + -EINVAL if the requested number of banks is invalid, + -EINVAL if requested MCE capability is not supported. + +Initializes MCE support for use. The u64 mcg_cap parameter +has the same format as the MSR_IA32_MCG_CAP register and +specifies which capabilities should be enabled. The maximum +supported number of error-reporting banks can be retrieved when +checking for KVM_CAP_MCE. The supported capabilities can be +retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED. + +4.106 KVM_X86_SET_MCE + +Capability: KVM_CAP_MCE +Architectures: x86 +Type: vcpu ioctl +Parameters: struct kvm_x86_mce (in) +Returns: 0 on success, + -EFAULT if struct kvm_x86_mce cannot be read, + -EINVAL if the bank number is invalid, + -EINVAL if VAL bit is not set in status field. + +Inject a machine check error (MCE) into the guest. The input +parameter is: + +struct kvm_x86_mce { + __u64 status; + __u64 addr; + __u64 misc; + __u64 mcg_status; + __u8 bank; + __u8 pad1[7]; + __u64 pad2[3]; +}; + +If the MCE being reported is an uncorrected error, KVM will +inject it as an MCE exception into the guest. If the guest +MCG_STATUS register reports that an MCE is in progress, KVM +causes an KVM_EXIT_SHUTDOWN vmexit. + +Otherwise, if the MCE is a corrected error, KVM will just +store it in the corresponding bank (provided this bank is +not holding a previously reported uncorrected error). + 5. The kvm_run structure ------------------------ @@ -4101,6 +3979,23 @@ to take care of that. This capability can be enabled dynamically even if VCPUs were already created and are running. +7.9 KVM_CAP_S390_GS + +Architectures: s390 +Parameters: none +Returns: 0 on success; -EINVAL if the machine does not support + guarded storage; -EBUSY if a VCPU has already been created. + +Allows use of guarded storage for the KVM guest. + +7.10 KVM_CAP_S390_AIS + +Architectures: s390 +Parameters: none + +Allow use of adapter-interruption suppression. +Returns: 0 on success; -EBUSY if a VCPU has already been created. + 8. Other capabilities. ---------------------- @@ -4147,3 +4042,118 @@ This capability, if KVM_CHECK_EXTENSION indicates that it is available, means that that the kernel can support guests using the hashed page table MMU defined in Power ISA V3.00 (as implemented in the POWER9 processor), including in-memory segment tables. + +8.5 KVM_CAP_MIPS_VZ + +Architectures: mips + +This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that +it is available, means that full hardware assisted virtualization capabilities +of the hardware are available for use through KVM. An appropriate +KVM_VM_MIPS_* type must be passed to KVM_CREATE_VM to create a VM which +utilises it. + +If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is +available, it means that the VM is using full hardware assisted virtualization +capabilities of the hardware. This is useful to check after creating a VM with +KVM_VM_MIPS_DEFAULT. + +The value returned by KVM_CHECK_EXTENSION should be compared against known +values (see below). All other values are reserved. This is to allow for the +possibility of other hardware assisted virtualization implementations which +may be incompatible with the MIPS VZ ASE. + + 0: The trap & emulate implementation is in use to run guest code in user + mode. Guest virtual memory segments are rearranged to fit the guest in the + user mode address space. + + 1: The MIPS VZ ASE is in use, providing full hardware assisted + virtualization, including standard guest virtual memory segments. + +8.6 KVM_CAP_MIPS_TE + +Architectures: mips + +This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that +it is available, means that the trap & emulate implementation is available to +run guest code in user mode, even if KVM_CAP_MIPS_VZ indicates that hardware +assisted virtualisation is also available. KVM_VM_MIPS_TE (0) must be passed +to KVM_CREATE_VM to create a VM which utilises it. + +If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is +available, it means that the VM is using trap & emulate. + +8.7 KVM_CAP_MIPS_64BIT + +Architectures: mips + +This capability indicates the supported architecture type of the guest, i.e. the +supported register and address width. + +The values returned when this capability is checked by KVM_CHECK_EXTENSION on a +kvm VM handle correspond roughly to the CP0_Config.AT register field, and should +be checked specifically against known values (see below). All other values are +reserved. + + 0: MIPS32 or microMIPS32. + Both registers and addresses are 32-bits wide. + It will only be possible to run 32-bit guest code. + + 1: MIPS64 or microMIPS64 with access only to 32-bit compatibility segments. + Registers are 64-bits wide, but addresses are 32-bits wide. + 64-bit guest code may run but cannot access MIPS64 memory segments. + It will also be possible to run 32-bit guest code. + + 2: MIPS64 or microMIPS64 with access to all address segments. + Both registers and addresses are 64-bits wide. + It will be possible to run 64-bit or 32-bit guest code. + +8.8 KVM_CAP_X86_GUEST_MWAIT + +Architectures: x86 + +This capability indicates that guest using memory monotoring instructions +(MWAIT/MWAITX) to stop the virtual CPU will not cause a VM exit. As such time +spent while virtual CPU is halted in this way will then be accounted for as +guest running time on the host (as opposed to e.g. HLT). + +8.9 KVM_CAP_ARM_USER_IRQ + +Architectures: arm, arm64 +This capability, if KVM_CHECK_EXTENSION indicates that it is available, means +that if userspace creates a VM without an in-kernel interrupt controller, it +will be notified of changes to the output level of in-kernel emulated devices, +which can generate virtual interrupts, presented to the VM. +For such VMs, on every return to userspace, the kernel +updates the vcpu's run->s.regs.device_irq_level field to represent the actual +output level of the device. + +Whenever kvm detects a change in the device output level, kvm guarantees at +least one return to userspace before running the VM. This exit could either +be a KVM_EXIT_INTR or any other exit event, like KVM_EXIT_MMIO. This way, +userspace can always sample the device output level and re-compute the state of +the userspace interrupt controller. Userspace should always check the state +of run->s.regs.device_irq_level on every kvm exit. +The value in run->s.regs.device_irq_level can represent both level and edge +triggered interrupt signals, depending on the device. Edge triggered interrupt +signals will exit to userspace with the bit in run->s.regs.device_irq_level +set exactly once per edge signal. + +The field run->s.regs.device_irq_level is available independent of +run->kvm_valid_regs or run->kvm_dirty_regs bits. + +If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a +number larger than 0 indicating the version of this capability is implemented +and thereby which bits in in run->s.regs.device_irq_level can signal values. + +Currently the following bits are defined for the device_irq_level bitmap: + + KVM_CAP_ARM_USER_IRQ >= 1: + + KVM_ARM_DEV_EL1_VTIMER - EL1 virtual timer + KVM_ARM_DEV_EL1_PTIMER - EL1 physical timer + KVM_ARM_DEV_PMU - ARM PMU overflow interrupt signal + +Future versions of kvm may implement additional events. These will get +indicated by returning a higher number from KVM_CHECK_EXTENSION and will be +listed above. diff --git a/Documentation/virtual/kvm/arm/hyp-abi.txt b/Documentation/virtual/kvm/arm/hyp-abi.txt new file mode 100644 index 000000000000..a20a0bee268d --- /dev/null +++ b/Documentation/virtual/kvm/arm/hyp-abi.txt @@ -0,0 +1,53 @@ +* Internal ABI between the kernel and HYP + +This file documents the interaction between the Linux kernel and the +hypervisor layer when running Linux as a hypervisor (for example +KVM). It doesn't cover the interaction of the kernel with the +hypervisor when running as a guest (under Xen, KVM or any other +hypervisor), or any hypervisor-specific interaction when the kernel is +used as a host. + +On arm and arm64 (without VHE), the kernel doesn't run in hypervisor +mode, but still needs to interact with it, allowing a built-in +hypervisor to be either installed or torn down. + +In order to achieve this, the kernel must be booted at HYP (arm) or +EL2 (arm64), allowing it to install a set of stubs before dropping to +SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction, +and only act on individual CPUs. + +Unless specified otherwise, any built-in hypervisor must implement +these functions (see arch/arm{,64}/include/asm/virt.h): + +* r0/x0 = HVC_SET_VECTORS + r1/x1 = vectors + + Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors' + must be a physical address, and respect the alignment requirements + of the architecture. Only implemented by the initial stubs, not by + Linux hypervisors. + +* r0/x0 = HVC_RESET_VECTORS + + Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials + stubs' exception vector value. This effectively disables an existing + hypervisor. + +* r0/x0 = HVC_SOFT_RESTART + r1/x1 = restart address + x2 = x0's value when entering the next payload (arm64) + x3 = x1's value when entering the next payload (arm64) + x4 = x2's value when entering the next payload (arm64) + + Mask all exceptions, disable the MMU, move the arguments into place + (arm64 only), and jump to the restart address while at HYP/EL2. This + hypercall is not expected to return to its caller. + +Any other value of r0/x0 triggers a hypervisor-specific handling, +which is not documented here. + +The return value of a stub hypercall is held by r0/x0, and is 0 on +success, and HVC_STUB_ERR on error. A stub hypercall is allowed to +clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and +ip on arm). It is thus recommended to use a function call to perform +the hypercall. diff --git a/Documentation/virtual/kvm/devices/arm-vgic.txt b/Documentation/virtual/kvm/devices/arm-vgic.txt index 76e61c883347..b2f60ca8b60c 100644 --- a/Documentation/virtual/kvm/devices/arm-vgic.txt +++ b/Documentation/virtual/kvm/devices/arm-vgic.txt @@ -83,6 +83,12 @@ Groups: Bits for undefined preemption levels are RAZ/WI. + For historical reasons and to provide ABI compatibility with userspace we + export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask + field in the lower 5 bits of a word, meaning that userspace must always + use the lower 5 bits to communicate with the KVM device and must shift the + value left by 3 places to obtain the actual priority mask level. + Limitations: - Priorities are not implemented, and registers are RAZ/WI - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2. diff --git a/Documentation/virtual/kvm/devices/s390_flic.txt b/Documentation/virtual/kvm/devices/s390_flic.txt index 6b0e115301c8..c2518cea8ab4 100644 --- a/Documentation/virtual/kvm/devices/s390_flic.txt +++ b/Documentation/virtual/kvm/devices/s390_flic.txt @@ -14,6 +14,8 @@ FLIC provides support to - purge one pending floating I/O interrupt (KVM_DEV_FLIC_CLEAR_IO_IRQ) - enable/disable for the guest transparent async page faults - register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*) +- modify AIS (adapter-interruption-suppression) mode state (KVM_DEV_FLIC_AISM) +- inject adapter interrupts on a specified adapter (KVM_DEV_FLIC_AIRQ_INJECT) Groups: KVM_DEV_FLIC_ENQUEUE @@ -64,12 +66,18 @@ struct kvm_s390_io_adapter { __u8 isc; __u8 maskable; __u8 swap; - __u8 pad; + __u8 flags; }; id contains the unique id for the adapter, isc the I/O interruption subclass - to use, maskable whether this adapter may be masked (interrupts turned off) - and swap whether the indicators need to be byte swapped. + to use, maskable whether this adapter may be masked (interrupts turned off), + swap whether the indicators need to be byte swapped, and flags contains + further characteristics of the adapter. + Currently defined values for 'flags' are: + - KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS + (adapter-interrupt-suppression) facility. This flag only has an effect if + the AIS capability is enabled. + Unknown flag values are ignored. KVM_DEV_FLIC_ADAPTER_MODIFY @@ -101,6 +109,33 @@ struct kvm_s390_io_adapter_req { release a userspace page for the translated address specified in addr from the list of mappings + KVM_DEV_FLIC_AISM + modify the adapter-interruption-suppression mode for a given isc if the + AIS capability is enabled. Takes a kvm_s390_ais_req describing: + +struct kvm_s390_ais_req { + __u8 isc; + __u16 mode; +}; + + isc contains the target I/O interruption subclass, mode the target + adapter-interruption-suppression mode. The following modes are + currently supported: + - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection + is always allowed; + - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq + injection is only allowed once and the following adapter interrupts + will be suppressed until the mode is set again to ALL-Interruptions + or SINGLE-Interruption mode. + + KVM_DEV_FLIC_AIRQ_INJECT + Inject adapter interrupts on a specified adapter. + attr->attr contains the unique id for the adapter, which allows for + adapter-specific checks and actions. + For adapters subject to AIS, handle the airq injection suppression for + an isc according to the adapter-interruption-suppression mode on condition + that the AIS capability is enabled. + Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on FLIC with an unknown group or attribute gives the error code EINVAL (instead of ENXIO, as specified in the API documentation). It is not possible to conclude diff --git a/Documentation/virtual/kvm/devices/vfio.txt b/Documentation/virtual/kvm/devices/vfio.txt index ef51740c67ca..528c77c8022c 100644 --- a/Documentation/virtual/kvm/devices/vfio.txt +++ b/Documentation/virtual/kvm/devices/vfio.txt @@ -16,7 +16,21 @@ Groups: KVM_DEV_VFIO_GROUP attributes: KVM_DEV_VFIO_GROUP_ADD: Add a VFIO group to VFIO-KVM device tracking + kvm_device_attr.addr points to an int32_t file descriptor + for the VFIO group. KVM_DEV_VFIO_GROUP_DEL: Remove a VFIO group from VFIO-KVM device tracking + kvm_device_attr.addr points to an int32_t file descriptor + for the VFIO group. + KVM_DEV_VFIO_GROUP_SET_SPAPR_TCE: attaches a guest visible TCE table + allocated by sPAPR KVM. + kvm_device_attr.addr points to a struct: -For each, kvm_device_attr.addr points to an int32_t file descriptor -for the VFIO group. + struct kvm_vfio_spapr_tce { + __s32 groupfd; + __s32 tablefd; + }; + + where + @groupfd is a file descriptor for a VFIO group; + @tablefd is a file descriptor for a TCE table allocated via + KVM_CREATE_SPAPR_TCE. diff --git a/Documentation/virtual/kvm/devices/vm.txt b/Documentation/virtual/kvm/devices/vm.txt index b6cda49f2ba4..575ccb022aac 100644 --- a/Documentation/virtual/kvm/devices/vm.txt +++ b/Documentation/virtual/kvm/devices/vm.txt @@ -140,7 +140,8 @@ struct kvm_s390_vm_cpu_subfunc { u8 kmo[16]; # valid with Message-Security-Assist-Extension 4 u8 pcc[16]; # valid with Message-Security-Assist-Extension 4 u8 ppno[16]; # valid with Message-Security-Assist-Extension 5 - u8 reserved[1824]; # reserved for future instructions + u8 kma[16]; # valid with Message-Security-Assist-Extension 8 + u8 reserved[1808]; # reserved for future instructions }; Parameters: address of a buffer to load the subfunction blocks from. diff --git a/Documentation/virtual/kvm/hypercalls.txt b/Documentation/virtual/kvm/hypercalls.txt index feaaa634f154..a890529c63ed 100644 --- a/Documentation/virtual/kvm/hypercalls.txt +++ b/Documentation/virtual/kvm/hypercalls.txt @@ -28,6 +28,11 @@ S390: property inside the device tree's /hypervisor node. For more information refer to Documentation/virtual/kvm/ppc-pv.txt +MIPS: + KVM hypercalls use the HYPCALL instruction with code 0 and the hypercall + number in $2 (v0). Up to four arguments may be placed in $4-$7 (a0-a3) and + the return value is placed in $2 (v0). + KVM Hypercalls Documentation =========================== The template for each hypercall is: diff --git a/Documentation/vm/00-INDEX b/Documentation/vm/00-INDEX index 6a5e2a102a45..11d3d8dcb449 100644 --- a/Documentation/vm/00-INDEX +++ b/Documentation/vm/00-INDEX @@ -12,6 +12,8 @@ highmem.txt - Outline of highmem and common issues. hugetlbpage.txt - a brief summary of hugetlbpage support in the Linux kernel. +hugetlbfs_reserv.txt + - A brief overview of hugetlbfs reservation design/implementation. hwpoison.txt - explains what hwpoison is idle_page_tracking.txt diff --git a/Documentation/vm/hugetlbfs_reserv.txt b/Documentation/vm/hugetlbfs_reserv.txt new file mode 100644 index 000000000000..9aca09a76bed --- /dev/null +++ b/Documentation/vm/hugetlbfs_reserv.txt @@ -0,0 +1,529 @@ +Hugetlbfs Reservation Overview +------------------------------ +Huge pages as described at 'Documentation/vm/hugetlbpage.txt' are typically +preallocated for application use. These huge pages are instantiated in a +task's address space at page fault time if the VMA indicates huge pages are +to be used. If no huge page exists at page fault time, the task is sent +a SIGBUS and often dies an unhappy death. Shortly after huge page support +was added, it was determined that it would be better to detect a shortage +of huge pages at mmap() time. The idea is that if there were not enough +huge pages to cover the mapping, the mmap() would fail. This was first +done with a simple check in the code at mmap() time to determine if there +were enough free huge pages to cover the mapping. Like most things in the +kernel, the code has evolved over time. However, the basic idea was to +'reserve' huge pages at mmap() time to ensure that huge pages would be +available for page faults in that mapping. The description below attempts to +describe how huge page reserve processing is done in the v4.10 kernel. + + +Audience +-------- +This description is primarily targeted at kernel developers who are modifying +hugetlbfs code. + + +The Data Structures +------------------- +resv_huge_pages + This is a global (per-hstate) count of reserved huge pages. Reserved + huge pages are only available to the task which reserved them. + Therefore, the number of huge pages generally available is computed + as (free_huge_pages - resv_huge_pages). +Reserve Map + A reserve map is described by the structure: + struct resv_map { + struct kref refs; + spinlock_t lock; + struct list_head regions; + long adds_in_progress; + struct list_head region_cache; + long region_cache_count; + }; + There is one reserve map for each huge page mapping in the system. + The regions list within the resv_map describes the regions within + the mapping. A region is described as: + struct file_region { + struct list_head link; + long from; + long to; + }; + The 'from' and 'to' fields of the file region structure are huge page + indices into the mapping. Depending on the type of mapping, a + region in the reserv_map may indicate reservations exist for the + range, or reservations do not exist. +Flags for MAP_PRIVATE Reservations + These are stored in the bottom bits of the reservation map pointer. + #define HPAGE_RESV_OWNER (1UL << 0) Indicates this task is the + owner of the reservations associated with the mapping. + #define HPAGE_RESV_UNMAPPED (1UL << 1) Indicates task originally + mapping this range (and creating reserves) has unmapped a + page from this task (the child) due to a failed COW. +Page Flags + The PagePrivate page flag is used to indicate that a huge page + reservation must be restored when the huge page is freed. More + details will be discussed in the "Freeing huge pages" section. + + +Reservation Map Location (Private or Shared) +-------------------------------------------- +A huge page mapping or segment is either private or shared. If private, +it is typically only available to a single address space (task). If shared, +it can be mapped into multiple address spaces (tasks). The location and +semantics of the reservation map is significantly different for two types +of mappings. Location differences are: +- For private mappings, the reservation map hangs off the the VMA structure. + Specifically, vma->vm_private_data. This reserve map is created at the + time the mapping (mmap(MAP_PRIVATE)) is created. +- For shared mappings, the reservation map hangs off the inode. Specifically, + inode->i_mapping->private_data. Since shared mappings are always backed + by files in the hugetlbfs filesystem, the hugetlbfs code ensures each inode + contains a reservation map. As a result, the reservation map is allocated + when the inode is created. + + +Creating Reservations +--------------------- +Reservations are created when a huge page backed shared memory segment is +created (shmget(SHM_HUGETLB)) or a mapping is created via mmap(MAP_HUGETLB). +These operations result in a call to the routine hugetlb_reserve_pages() + +int hugetlb_reserve_pages(struct inode *inode, + long from, long to, + struct vm_area_struct *vma, + vm_flags_t vm_flags) + +The first thing hugetlb_reserve_pages() does is check for the NORESERVE +flag was specified in either the shmget() or mmap() call. If NORESERVE +was specified, then this routine returns immediately as no reservation +are desired. + +The arguments 'from' and 'to' are huge page indices into the mapping or +underlying file. For shmget(), 'from' is always 0 and 'to' corresponds to +the length of the segment/mapping. For mmap(), the offset argument could +be used to specify the offset into the underlying file. In such a case +the 'from' and 'to' arguments have been adjusted by this offset. + +One of the big differences between PRIVATE and SHARED mappings is the way +in which reservations are represented in the reservation map. +- For shared mappings, an entry in the reservation map indicates a reservation + exists or did exist for the corresponding page. As reservations are + consumed, the reservation map is not modified. +- For private mappings, the lack of an entry in the reservation map indicates + a reservation exists for the corresponding page. As reservations are + consumed, entries are added to the reservation map. Therefore, the + reservation map can also be used to determine which reservations have + been consumed. + +For private mappings, hugetlb_reserve_pages() creates the reservation map and +hangs it off the VMA structure. In addition, the HPAGE_RESV_OWNER flag is set +to indicate this VMA owns the reservations. + +The reservation map is consulted to determine how many huge page reservations +are needed for the current mapping/segment. For private mappings, this is +always the value (to - from). However, for shared mappings it is possible that some reservations may already exist within the range (to - from). See the +section "Reservation Map Modifications" for details on how this is accomplished. + +The mapping may be associated with a subpool. If so, the subpool is consulted +to ensure there is sufficient space for the mapping. It is possible that the +subpool has set aside reservations that can be used for the mapping. See the +section "Subpool Reservations" for more details. + +After consulting the reservation map and subpool, the number of needed new +reservations is known. The routine hugetlb_acct_memory() is called to check +for and take the requested number of reservations. hugetlb_acct_memory() +calls into routines that potentially allocate and adjust surplus page counts. +However, within those routines the code is simply checking to ensure there +are enough free huge pages to accommodate the reservation. If there are, +the global reservation count resv_huge_pages is adjusted something like the +following. + if (resv_needed <= (resv_huge_pages - free_huge_pages)) + resv_huge_pages += resv_needed; +Note that the global lock hugetlb_lock is held when checking and adjusting +these counters. + +If there were enough free huge pages and the global count resv_huge_pages +was adjusted, then the reservation map associated with the mapping is +modified to reflect the reservations. In the case of a shared mapping, a +file_region will exist that includes the range 'from' 'to'. For private +mappings, no modifications are made to the reservation map as lack of an +entry indicates a reservation exists. + +If hugetlb_reserve_pages() was successful, the global reservation count and +reservation map associated with the mapping will be modified as required to +ensure reservations exist for the range 'from' - 'to'. + + +Consuming Reservations/Allocating a Huge Page +--------------------------------------------- +Reservations are consumed when huge pages associated with the reservations +are allocated and instantiated in the corresponding mapping. The allocation +is performed within the routine alloc_huge_page(). +struct page *alloc_huge_page(struct vm_area_struct *vma, + unsigned long addr, int avoid_reserve) +alloc_huge_page is passed a VMA pointer and a virtual address, so it can +consult the reservation map to determine if a reservation exists. In addition, +alloc_huge_page takes the argument avoid_reserve which indicates reserves +should not be used even if it appears they have been set aside for the +specified address. The avoid_reserve argument is most often used in the case +of Copy on Write and Page Migration where additional copies of an existing +page are being allocated. + +The helper routine vma_needs_reservation() is called to determine if a +reservation exists for the address within the mapping(vma). See the section +"Reservation Map Helper Routines" for detailed information on what this +routine does. The value returned from vma_needs_reservation() is generally +0 or 1. 0 if a reservation exists for the address, 1 if no reservation exists. +If a reservation does not exist, and there is a subpool associated with the +mapping the subpool is consulted to determine if it contains reservations. +If the subpool contains reservations, one can be used for this allocation. +However, in every case the avoid_reserve argument overrides the use of +a reservation for the allocation. After determining whether a reservation +exists and can be used for the allocation, the routine dequeue_huge_page_vma() +is called. This routine takes two arguments related to reservations: +- avoid_reserve, this is the same value/argument passed to alloc_huge_page() +- chg, even though this argument is of type long only the values 0 or 1 are + passed to dequeue_huge_page_vma. If the value is 0, it indicates a + reservation exists (see the section "Memory Policy and Reservations" for + possible issues). If the value is 1, it indicates a reservation does not + exist and the page must be taken from the global free pool if possible. +The free lists associated with the memory policy of the VMA are searched for +a free page. If a page is found, the value free_huge_pages is decremented +when the page is removed from the free list. If there was a reservation +associated with the page, the following adjustments are made: + SetPagePrivate(page); /* Indicates allocating this page consumed + * a reservation, and if an error is + * encountered such that the page must be + * freed, the reservation will be restored. */ + resv_huge_pages--; /* Decrement the global reservation count */ +Note, if no huge page can be found that satisfies the VMA's memory policy +an attempt will be made to allocate one using the buddy allocator. This +brings up the issue of surplus huge pages and overcommit which is beyond +the scope reservations. Even if a surplus page is allocated, the same +reservation based adjustments as above will be made: SetPagePrivate(page) and +resv_huge_pages--. + +After obtaining a new huge page, (page)->private is set to the value of +the subpool associated with the page if it exists. This will be used for +subpool accounting when the page is freed. + +The routine vma_commit_reservation() is then called to adjust the reserve +map based on the consumption of the reservation. In general, this involves +ensuring the page is represented within a file_region structure of the region +map. For shared mappings where the the reservation was present, an entry +in the reserve map already existed so no change is made. However, if there +was no reservation in a shared mapping or this was a private mapping a new +entry must be created. + +It is possible that the reserve map could have been changed between the call +to vma_needs_reservation() at the beginning of alloc_huge_page() and the +call to vma_commit_reservation() after the page was allocated. This would +be possible if hugetlb_reserve_pages was called for the same page in a shared +mapping. In such cases, the reservation count and subpool free page count +will be off by one. This rare condition can be identified by comparing the +return value from vma_needs_reservation and vma_commit_reservation. If such +a race is detected, the subpool and global reserve counts are adjusted to +compensate. See the section "Reservation Map Helper Routines" for more +information on these routines. + + +Instantiate Huge Pages +---------------------- +After huge page allocation, the page is typically added to the page tables +of the allocating task. Before this, pages in a shared mapping are added +to the page cache and pages in private mappings are added to an anonymous +reverse mapping. In both cases, the PagePrivate flag is cleared. Therefore, +when a huge page that has been instantiated is freed no adjustment is made +to the global reservation count (resv_huge_pages). + + +Freeing Huge Pages +------------------ +Huge page freeing is performed by the routine free_huge_page(). This routine +is the destructor for hugetlbfs compound pages. As a result, it is only +passed a pointer to the page struct. When a huge page is freed, reservation +accounting may need to be performed. This would be the case if the page was +associated with a subpool that contained reserves, or the page is being freed +on an error path where a global reserve count must be restored. + +The page->private field points to any subpool associated with the page. +If the PagePrivate flag is set, it indicates the global reserve count should +be adjusted (see the section "Consuming Reservations/Allocating a Huge Page" +for information on how these are set). + +The routine first calls hugepage_subpool_put_pages() for the page. If this +routine returns a value of 0 (which does not equal the value passed 1) it +indicates reserves are associated with the subpool, and this newly free page +must be used to keep the number of subpool reserves above the minimum size. +Therefore, the global resv_huge_pages counter is incremented in this case. + +If the PagePrivate flag was set in the page, the global resv_huge_pages counter +will always be incremented. + + +Subpool Reservations +-------------------- +There is a struct hstate associated with each huge page size. The hstate +tracks all huge pages of the specified size. A subpool represents a subset +of pages within a hstate that is associated with a mounted hugetlbfs +filesystem. + +When a hugetlbfs filesystem is mounted a min_size option can be specified +which indicates the minimum number of huge pages required by the filesystem. +If this option is specified, the number of huge pages corresponding to +min_size are reserved for use by the filesystem. This number is tracked in +the min_hpages field of a struct hugepage_subpool. At mount time, +hugetlb_acct_memory(min_hpages) is called to reserve the specified number of +huge pages. If they can not be reserved, the mount fails. + +The routines hugepage_subpool_get/put_pages() are called when pages are +obtained from or released back to a subpool. They perform all subpool +accounting, and track any reservations associated with the subpool. +hugepage_subpool_get/put_pages are passed the number of huge pages by which +to adjust the subpool 'used page' count (down for get, up for put). Normally, +they return the same value that was passed or an error if not enough pages +exist in the subpool. + +However, if reserves are associated with the subpool a return value less +than the passed value may be returned. This return value indicates the +number of additional global pool adjustments which must be made. For example, +suppose a subpool contains 3 reserved huge pages and someone asks for 5. +The 3 reserved pages associated with the subpool can be used to satisfy part +of the request. But, 2 pages must be obtained from the global pools. To +relay this information to the caller, the value 2 is returned. The caller +is then responsible for attempting to obtain the additional two pages from +the global pools. + + +COW and Reservations +-------------------- +Since shared mappings all point to and use the same underlying pages, the +biggest reservation concern for COW is private mappings. In this case, +two tasks can be pointing at the same previously allocated page. One task +attempts to write to the page, so a new page must be allocated so that each +task points to its own page. + +When the page was originally allocated, the reservation for that page was +consumed. When an attempt to allocate a new page is made as a result of +COW, it is possible that no free huge pages are free and the allocation +will fail. + +When the private mapping was originally created, the owner of the mapping +was noted by setting the HPAGE_RESV_OWNER bit in the pointer to the reservation +map of the owner. Since the owner created the mapping, the owner owns all +the reservations associated with the mapping. Therefore, when a write fault +occurs and there is no page available, different action is taken for the owner +and non-owner of the reservation. + +In the case where the faulting task is not the owner, the fault will fail and +the task will typically receive a SIGBUS. + +If the owner is the faulting task, we want it to succeed since it owned the +original reservation. To accomplish this, the page is unmapped from the +non-owning task. In this way, the only reference is from the owning task. +In addition, the HPAGE_RESV_UNMAPPED bit is set in the reservation map pointer +of the non-owning task. The non-owning task may receive a SIGBUS if it later +faults on a non-present page. But, the original owner of the +mapping/reservation will behave as expected. + + +Reservation Map Modifications +----------------------------- +The following low level routines are used to make modifications to a +reservation map. Typically, these routines are not called directly. Rather, +a reservation map helper routine is called which calls one of these low level +routines. These low level routines are fairly well documented in the source +code (mm/hugetlb.c). These routines are: +long region_chg(struct resv_map *resv, long f, long t); +long region_add(struct resv_map *resv, long f, long t); +void region_abort(struct resv_map *resv, long f, long t); +long region_count(struct resv_map *resv, long f, long t); + +Operations on the reservation map typically involve two operations: +1) region_chg() is called to examine the reserve map and determine how + many pages in the specified range [f, t) are NOT currently represented. + + The calling code performs global checks and allocations to determine if + there are enough huge pages for the operation to succeed. + +2a) If the operation can succeed, region_add() is called to actually modify + the reservation map for the same range [f, t) previously passed to + region_chg(). +2b) If the operation can not succeed, region_abort is called for the same range + [f, t) to abort the operation. + +Note that this is a two step process where region_add() and region_abort() +are guaranteed to succeed after a prior call to region_chg() for the same +range. region_chg() is responsible for pre-allocating any data structures +necessary to ensure the subsequent operations (specifically region_add())) +will succeed. + +As mentioned above, region_chg() determines the number of pages in the range +which are NOT currently represented in the map. This number is returned to +the caller. region_add() returns the number of pages in the range added to +the map. In most cases, the return value of region_add() is the same as the +return value of region_chg(). However, in the case of shared mappings it is +possible for changes to the reservation map to be made between the calls to +region_chg() and region_add(). In this case, the return value of region_add() +will not match the return value of region_chg(). It is likely that in such +cases global counts and subpool accounting will be incorrect and in need of +adjustment. It is the responsibility of the caller to check for this condition +and make the appropriate adjustments. + +The routine region_del() is called to remove regions from a reservation map. +It is typically called in the following situations: +- When a file in the hugetlbfs filesystem is being removed, the inode will + be released and the reservation map freed. Before freeing the reservation + map, all the individual file_region structures must be freed. In this case + region_del is passed the range [0, LONG_MAX). +- When a hugetlbfs file is being truncated. In this case, all allocated pages + after the new file size must be freed. In addition, any file_region entries + in the reservation map past the new end of file must be deleted. In this + case, region_del is passed the range [new_end_of_file, LONG_MAX). +- When a hole is being punched in a hugetlbfs file. In this case, huge pages + are removed from the middle of the file one at a time. As the pages are + removed, region_del() is called to remove the corresponding entry from the + reservation map. In this case, region_del is passed the range + [page_idx, page_idx + 1). +In every case, region_del() will return the number of pages removed from the +reservation map. In VERY rare cases, region_del() can fail. This can only +happen in the hole punch case where it has to split an existing file_region +entry and can not allocate a new structure. In this error case, region_del() +will return -ENOMEM. The problem here is that the reservation map will +indicate that there is a reservation for the page. However, the subpool and +global reservation counts will not reflect the reservation. To handle this +situation, the routine hugetlb_fix_reserve_counts() is called to adjust the +counters so that they correspond with the reservation map entry that could +not be deleted. + +region_count() is called when unmapping a private huge page mapping. In +private mappings, the lack of a entry in the reservation map indicates that +a reservation exists. Therefore, by counting the number of entries in the +reservation map we know how many reservations were consumed and how many are +outstanding (outstanding = (end - start) - region_count(resv, start, end)). +Since the mapping is going away, the subpool and global reservation counts +are decremented by the number of outstanding reservations. + + +Reservation Map Helper Routines +------------------------------- +Several helper routines exist to query and modify the reservation maps. +These routines are only interested with reservations for a specific huge +page, so they just pass in an address instead of a range. In addition, +they pass in the associated VMA. From the VMA, the type of mapping (private +or shared) and the location of the reservation map (inode or VMA) can be +determined. These routines simply call the underlying routines described +in the section "Reservation Map Modifications". However, they do take into +account the 'opposite' meaning of reservation map entries for private and +shared mappings and hide this detail from the caller. + +long vma_needs_reservation(struct hstate *h, + struct vm_area_struct *vma, unsigned long addr) +This routine calls region_chg() for the specified page. If no reservation +exists, 1 is returned. If a reservation exists, 0 is returned. + +long vma_commit_reservation(struct hstate *h, + struct vm_area_struct *vma, unsigned long addr) +This calls region_add() for the specified page. As in the case of region_chg +and region_add, this routine is to be called after a previous call to +vma_needs_reservation. It will add a reservation entry for the page. It +returns 1 if the reservation was added and 0 if not. The return value should +be compared with the return value of the previous call to +vma_needs_reservation. An unexpected difference indicates the reservation +map was modified between calls. + +void vma_end_reservation(struct hstate *h, + struct vm_area_struct *vma, unsigned long addr) +This calls region_abort() for the specified page. As in the case of region_chg +and region_abort, this routine is to be called after a previous call to +vma_needs_reservation. It will abort/end the in progress reservation add +operation. + +long vma_add_reservation(struct hstate *h, + struct vm_area_struct *vma, unsigned long addr) +This is a special wrapper routine to help facilitate reservation cleanup +on error paths. It is only called from the routine restore_reserve_on_error(). +This routine is used in conjunction with vma_needs_reservation in an attempt +to add a reservation to the reservation map. It takes into account the +different reservation map semantics for private and shared mappings. Hence, +region_add is called for shared mappings (as an entry present in the map +indicates a reservation), and region_del is called for private mappings (as +the absence of an entry in the map indicates a reservation). See the section +"Reservation cleanup in error paths" for more information on what needs to +be done on error paths. + + +Reservation Cleanup in Error Paths +---------------------------------- +As mentioned in the section "Reservation Map Helper Routines", reservation +map modifications are performed in two steps. First vma_needs_reservation +is called before a page is allocated. If the allocation is successful, +then vma_commit_reservation is called. If not, vma_end_reservation is called. +Global and subpool reservation counts are adjusted based on success or failure +of the operation and all is well. + +Additionally, after a huge page is instantiated the PagePrivate flag is +cleared so that accounting when the page is ultimately freed is correct. + +However, there are several instances where errors are encountered after a huge +page is allocated but before it is instantiated. In this case, the page +allocation has consumed the reservation and made the appropriate subpool, +reservation map and global count adjustments. If the page is freed at this +time (before instantiation and clearing of PagePrivate), then free_huge_page +will increment the global reservation count. However, the reservation map +indicates the reservation was consumed. This resulting inconsistent state +will cause the 'leak' of a reserved huge page. The global reserve count will +be higher than it should and prevent allocation of a pre-allocated page. + +The routine restore_reserve_on_error() attempts to handle this situation. It +is fairly well documented. The intention of this routine is to restore +the reservation map to the way it was before the page allocation. In this +way, the state of the reservation map will correspond to the global reservation +count after the page is freed. + +The routine restore_reserve_on_error itself may encounter errors while +attempting to restore the reservation map entry. In this case, it will +simply clear the PagePrivate flag of the page. In this way, the global +reserve count will not be incremented when the page is freed. However, the +reservation map will continue to look as though the reservation was consumed. +A page can still be allocated for the address, but it will not use a reserved +page as originally intended. + +There is some code (most notably userfaultfd) which can not call +restore_reserve_on_error. In this case, it simply modifies the PagePrivate +so that a reservation will not be leaked when the huge page is freed. + + +Reservations and Memory Policy +------------------------------ +Per-node huge page lists existed in struct hstate when git was first used +to manage Linux code. The concept of reservations was added some time later. +When reservations were added, no attempt was made to take memory policy +into account. While cpusets are not exactly the same as memory policy, this +comment in hugetlb_acct_memory sums up the interaction between reservations +and cpusets/memory policy. + /* + * When cpuset is configured, it breaks the strict hugetlb page + * reservation as the accounting is done on a global variable. Such + * reservation is completely rubbish in the presence of cpuset because + * the reservation is not checked against page availability for the + * current cpuset. Application can still potentially OOM'ed by kernel + * with lack of free htlb page in cpuset that the task is in. + * Attempt to enforce strict accounting with cpuset is almost + * impossible (or too ugly) because cpuset is too fluid that + * task or memory node can be dynamically moved between cpusets. + * + * The change of semantics for shared hugetlb mapping with cpuset is + * undesirable. However, in order to preserve some of the semantics, + * we fall back to check against current free page availability as + * a best attempt and hopefully to minimize the impact of changing + * semantics that cpuset has. + */ + +Huge page reservations were added to prevent unexpected page allocation +failures (OOM) at page fault time. However, if an application makes use +of cpusets or memory policy there is no guarantee that huge pages will be +available on the required nodes. This is true even if there are a sufficient +number of global reservations. + + +Mike Kravetz, 7 April 2017 diff --git a/Documentation/vm/transhuge.txt b/Documentation/vm/transhuge.txt index cd28d5ee5273..4dde03b44ad1 100644 --- a/Documentation/vm/transhuge.txt +++ b/Documentation/vm/transhuge.txt @@ -266,7 +266,7 @@ for each mapping. The number of file transparent huge pages mapped to userspace is available by reading ShmemPmdMapped and ShmemHugePages fields in /proc/meminfo. -To identify what applications are mapping file transparent huge pages, it +To identify what applications are mapping file transparent huge pages, it is necessary to read /proc/PID/smaps and count the FileHugeMapped fields for each mapping. @@ -292,7 +292,7 @@ thp_collapse_alloc_failed is incremented if khugepaged found a range the allocation. thp_file_alloc is incremented every time a file huge page is successfully -i allocated. + allocated. thp_file_mapped is incremented every time a file huge page is mapped into user address space. @@ -501,7 +501,7 @@ scanner can get reference to a page is get_page_unless_zero(). All tail pages have zero ->_refcount until atomic_add(). This prevents the scanner from getting a reference to the tail page up to that point. After the -atomic_add() we don't care about the ->_refcount value. We already known how +atomic_add() we don't care about the ->_refcount value. We already known how many references should be uncharged from the head page. For head page get_page_unless_zero() will succeed and we don't mind. It's @@ -519,8 +519,8 @@ comes. Splitting will free up unused subpages. Splitting the page right away is not an option due to locking context in the place where we can detect partial unmap. It's also might be -counterproductive since in many cases partial unmap unmap happens during -exit(2) if an THP crosses VMA boundary. +counterproductive since in many cases partial unmap happens during exit(2) if +a THP crosses a VMA boundary. Function deferred_split_huge_page() is used to queue page for splitting. The splitting itself will happen when we get memory pressure via shrinker diff --git a/Documentation/w1/slaves/00-INDEX b/Documentation/w1/slaves/00-INDEX index 6e18c70c3474..8d76718e1ea2 100644 --- a/Documentation/w1/slaves/00-INDEX +++ b/Documentation/w1/slaves/00-INDEX @@ -2,7 +2,11 @@ - This file w1_therm - The Maxim/Dallas Semiconductor ds18*20 temperature sensor. +w1_ds2413 + - The Maxim/Dallas Semiconductor ds2413 dual channel addressable switch. w1_ds2423 - The Maxim/Dallas Semiconductor ds2423 counter device. +w1_ds2438 + - The Maxim/Dallas Semiconductor ds2438 smart battery monitor. w1_ds28e04 - The Maxim/Dallas Semiconductor ds28e04 eeprom. diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413 new file mode 100644 index 000000000000..936263a8ccb4 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2413 @@ -0,0 +1,50 @@ +Kernel driver w1_ds2413 +======================= + +Supported chips: + * Maxim DS2413 1-Wire Dual Channel Addressable Switch + +supported family codes: + W1_FAMILY_DS2413 0x3A + +Author: Mariusz Bialonczyk <manio@skyboo.net> + +Description +----------- + +The DS2413 chip has two open-drain outputs (PIO A and PIO B). +Support is provided through the sysfs files "output" and "state". + +Reading state +------------- +The "state" file provides one-byte value which is in the same format as for +the chip PIO_ACCESS_READ command (refer the datasheet for details): + +Bit 0: PIOA Pin State +Bit 1: PIOA Output Latch State +Bit 2: PIOB Pin State +Bit 3: PIOB Output Latch State +Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module) + +This file is readonly. + +Writing output +-------------- +You can set the PIO pins using the "output" file. +It is writable, you can write one-byte value to this sysfs file. +Similarly the byte format is the same as for the PIO_ACCESS_WRITE command: + +Bit 0: PIOA +Bit 1: PIOB +Bit 2-7: No matter (driver will set it to "1"s) + + +The chip has some kind of basic protection against transmission errors. +When reading the state, there is a four complement bits. +The driver is checking this complement, and when it is wrong then it is +returning I/O error. + +When writing output, the master must repeat the PIO Output Data byte in +its inverted form and it is waiting for a confirmation. +If the write is unsuccessful for three times, the write also returns +I/O error. diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438 new file mode 100644 index 000000000000..b99f3674c5b4 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2438 @@ -0,0 +1,63 @@ +Kernel driver w1_ds2438 +======================= + +Supported chips: + * Maxim DS2438 Smart Battery Monitor + +supported family codes: + W1_FAMILY_DS2438 0x26 + +Author: Mariusz Bialonczyk <manio@skyboo.net> + +Description +----------- + +The DS2438 chip provides several functions that are desirable to carry in +a battery pack. It also has a 40 bytes of nonvolatile EEPROM. +Because the ability of temperature, current and voltage measurement, the chip +is also often used in weather stations and applications such as: rain gauge, +wind speed/direction measuring, humidity sensing, etc. + +Current support is provided through the following sysfs files (all files +except "iad" are readonly): + +"iad" +----- +This file controls the 'Current A/D Control Bit' (IAD) in the +Status/Configuration Register. +Writing a zero value will clear the IAD bit and disables the current +measurements. +Writing value "1" is setting the IAD bit (enables the measurements). +The IAD bit is enabled by default in the DS2438. + +When writing to sysfs file bits 2-7 are ignored, so it's safe to write ASCII. +An I/O error is returned when there is a problem setting the new value. + +"page0" +------- +This file provides full 8 bytes of the chip Page 0 (00h). +This page contains the most frequently accessed information of the DS2438. +Internally when this file is read, the additional CRC byte is also obtained +from the slave device. If it is correct, the 8 bytes page data are passed +to userspace, otherwise an I/O error is returned. + +"temperature" +------------- +Opening and reading this file initiates the CONVERT_T (temperature conversion) +command of the chip, afterwards the temperature is read from the device +registers and provided as an ASCII decimal value. + +Important: The returned value has to be divided by 256 to get a real +temperature in degrees Celsius. + +"vad", "vdd" +------------ +Opening and reading this file initiates the CONVERT_V (voltage conversion) +command of the chip. + +Depending on a sysfs filename a different input for the A/D will be selected: +vad: general purpose A/D input (VAD) +vdd: battery input (VDD) + +After the voltage conversion the value is returned as decimal ASCII. +Note: The value is in mV, so to get a volts the value has to be divided by 10. diff --git a/Documentation/x86/intel_rdt_ui.txt b/Documentation/x86/intel_rdt_ui.txt index 51cf6fa5591f..0f6d8477b66c 100644 --- a/Documentation/x86/intel_rdt_ui.txt +++ b/Documentation/x86/intel_rdt_ui.txt @@ -4,6 +4,7 @@ Copyright (C) 2016 Intel Corporation Fenghua Yu <fenghua.yu@intel.com> Tony Luck <tony.luck@intel.com> +Vikas Shivappa <vikas.shivappa@intel.com> This feature is enabled by the CONFIG_INTEL_RDT_A Kconfig and the X86 /proc/cpuinfo flag bits "rdt", "cat_l3" and "cdp_l3". @@ -22,19 +23,34 @@ Info directory The 'info' directory contains information about the enabled resources. Each resource has its own subdirectory. The subdirectory -names reflect the resource names. Each subdirectory contains the -following files: +names reflect the resource names. +Cache resource(L3/L2) subdirectory contains the following files: -"num_closids": The number of CLOSIDs which are valid for this - resource. The kernel uses the smallest number of - CLOSIDs of all enabled resources as limit. +"num_closids": The number of CLOSIDs which are valid for this + resource. The kernel uses the smallest number of + CLOSIDs of all enabled resources as limit. -"cbm_mask": The bitmask which is valid for this resource. This - mask is equivalent to 100%. +"cbm_mask": The bitmask which is valid for this resource. + This mask is equivalent to 100%. -"min_cbm_bits": The minimum number of consecutive bits which must be - set when writing a mask. +"min_cbm_bits": The minimum number of consecutive bits which + must be set when writing a mask. +Memory bandwitdh(MB) subdirectory contains the following files: + +"min_bandwidth": The minimum memory bandwidth percentage which + user can request. + +"bandwidth_gran": The granularity in which the memory bandwidth + percentage is allocated. The allocated + b/w percentage is rounded off to the next + control step available on the hardware. The + available bandwidth control steps are: + min_bandwidth + N * bandwidth_gran. + +"delay_linear": Indicates if the delay scale is linear or + non-linear. This field is purely informational + only. Resource groups --------------- @@ -59,6 +75,9 @@ There are three files associated with each group: given to the default (root) group. You cannot remove CPUs from the default group. +"cpus_list": One or more CPU ranges of logical CPUs assigned to this + group. Same rules apply like for the "cpus" file. + "schemata": A list of all the resources available to this group. Each resource has its own line and format - see below for details. @@ -107,6 +126,22 @@ and 0xA are not. On a system with a 20-bit mask each bit represents 5% of the capacity of the cache. You could partition the cache into four equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. +Memory bandwidth(b/w) percentage +-------------------------------- +For Memory b/w resource, user controls the resource by indicating the +percentage of total memory b/w. + +The minimum bandwidth percentage value for each cpu model is predefined +and can be looked up through "info/MB/min_bandwidth". The bandwidth +granularity that is allocated is also dependent on the cpu model and can +be looked up at "info/MB/bandwidth_gran". The available bandwidth +control steps are: min_bw + N * bw_gran. Intermediate values are rounded +to the next control step available on the hardware. + +The bandwidth throttling is a core specific mechanism on some of Intel +SKUs. Using a high bandwidth and a low bandwidth setting on two threads +sharing a core will result in both threads being throttled to use the +low bandwidth. L3 details (code and data prioritization disabled) -------------------------------------------------- @@ -129,16 +164,38 @@ schemata format is always: L2:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... +Memory b/w Allocation details +----------------------------- + +Memory b/w domain is L3 cache. + + MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;... + +Reading/writing the schemata file +--------------------------------- +Reading the schemata file will show the state of all resources +on all domains. When writing you only need to specify those values +which you wish to change. E.g. + +# cat schemata +L3DATA:0=fffff;1=fffff;2=fffff;3=fffff +L3CODE:0=fffff;1=fffff;2=fffff;3=fffff +# echo "L3DATA:2=3c0;" > schemata +# cat schemata +L3DATA:0=fffff;1=fffff;2=3c0;3=fffff +L3CODE:0=fffff;1=fffff;2=fffff;3=fffff + Example 1 --------- On a two socket machine (one L3 cache per socket) with just four bits -for cache bit masks +for cache bit masks, minimum b/w of 10% with a memory bandwidth +granularity of 10% # mount -t resctrl resctrl /sys/fs/resctrl # cd /sys/fs/resctrl # mkdir p0 p1 -# echo "L3:0=3;1=c" > /sys/fs/resctrl/p0/schemata -# echo "L3:0=3;1=3" > /sys/fs/resctrl/p1/schemata +# echo "L3:0=3;1=c\nMB:0=50;1=50" > /sys/fs/resctrl/p0/schemata +# echo "L3:0=3;1=3\nMB:0=50;1=50" > /sys/fs/resctrl/p1/schemata The default resource group is unmodified, so we have access to all parts of all caches (its schemata file reads "L3:0=f;1=f"). @@ -147,6 +204,14 @@ Tasks that are under the control of group "p0" may only allocate from the "lower" 50% on cache ID 0, and the "upper" 50% of cache ID 1. Tasks in group "p1" use the "lower" 50% of cache on both sockets. +Similarly, tasks that are under the control of group "p0" may use a +maximum memory b/w of 50% on socket0 and 50% on socket 1. +Tasks in group "p1" may also use 50% memory b/w on both sockets. +Note that unlike cache masks, memory b/w cannot specify whether these +allocations can overlap or not. The allocations specifies the maximum +b/w that the group may be able to use and the system admin can configure +the b/w accordingly. + Example 2 --------- Again two sockets, but this time with a more realistic 20-bit mask. @@ -160,9 +225,10 @@ of L3 cache on socket 0. # cd /sys/fs/resctrl First we reset the schemata for the default group so that the "upper" -50% of the L3 cache on socket 0 cannot be used by ordinary tasks: +50% of the L3 cache on socket 0 and 50% of memory b/w cannot be used by +ordinary tasks: -# echo "L3:0=3ff;1=fffff" > schemata +# echo "L3:0=3ff;1=fffff\nMB:0=50;1=100" > schemata Next we make a resource group for our first real time task and give it access to the "top" 25% of the cache on socket 0. @@ -185,6 +251,20 @@ Ditto for the second real time task (with the remaining 25% of cache): # echo 5678 > p1/tasks # taskset -cp 2 5678 +For the same 2 socket system with memory b/w resource and CAT L3 the +schemata would look like(Assume min_bandwidth 10 and bandwidth_gran is +10): + +For our first real time task this would request 20% memory b/w on socket +0. + +# echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata + +For our second real time task this would request an other 20% memory b/w +on socket 0. + +# echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata + Example 3 --------- @@ -198,18 +278,22 @@ the tasks. # cd /sys/fs/resctrl First we reset the schemata for the default group so that the "upper" -50% of the L3 cache on socket 0 cannot be used by ordinary tasks: +50% of the L3 cache on socket 0, and 50% of memory bandwidth on socket 0 +cannot be used by ordinary tasks: -# echo "L3:0=3ff" > schemata +# echo "L3:0=3ff\nMB:0=50" > schemata -Next we make a resource group for our real time cores and give -it access to the "top" 50% of the cache on socket 0. +Next we make a resource group for our real time cores and give it access +to the "top" 50% of the cache on socket 0 and 50% of memory bandwidth on +socket 0. # mkdir p0 -# echo "L3:0=ffc00;" > p0/schemata +# echo "L3:0=ffc00\nMB:0=50" > p0/schemata Finally we move core 4-7 over to the new group and make sure that the -kernel and the tasks running there get 50% of the cache. +kernel and the tasks running there get 50% of the cache. They should +also get 50% of memory bandwidth assuming that the cores 4-7 are SMT +siblings and only the real time threads are scheduled on the cores 4-7. # echo C0 > p0/cpus diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index 5724092db811..b0798e281aa6 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -4,7 +4,7 @@ Virtual memory map with 4 level page tables: 0000000000000000 - 00007fffffffffff (=47 bits) user space, different per mm -hole caused by [48:63] sign extension +hole caused by [47:63] sign extension ffff800000000000 - ffff87ffffffffff (=43 bits) guard hole, reserved for hypervisor ffff880000000000 - ffffc7ffffffffff (=64 TB) direct mapping of all phys. memory ffffc80000000000 - ffffc8ffffffffff (=40 bits) hole @@ -19,16 +19,43 @@ ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks ffffffef00000000 - fffffffeffffffff (=64 GB) EFI region mapping space ... unused hole ... ffffffff80000000 - ffffffff9fffffff (=512 MB) kernel text mapping, from phys 0 +ffffffffa0000000 - ffffffffff5fffff (=1526 MB) module mapping space (variable) +ffffffffff600000 - ffffffffffdfffff (=8 MB) vsyscalls +ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole + +Virtual memory map with 5 level page tables: + +0000000000000000 - 00ffffffffffffff (=56 bits) user space, different per mm +hole caused by [56:63] sign extension +ff00000000000000 - ff0fffffffffffff (=52 bits) guard hole, reserved for hypervisor +ff10000000000000 - ff8fffffffffffff (=55 bits) direct mapping of all phys. memory +ff90000000000000 - ff91ffffffffffff (=49 bits) hole +ff92000000000000 - ffd1ffffffffffff (=54 bits) vmalloc/ioremap space +ffd2000000000000 - ffd3ffffffffffff (=49 bits) hole +ffd4000000000000 - ffd5ffffffffffff (=49 bits) virtual memory map (512TB) +... unused hole ... +ffd8000000000000 - fff7ffffffffffff (=53 bits) kasan shadow memory (8PB) +... unused hole ... +ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks +... unused hole ... +ffffffef00000000 - fffffffeffffffff (=64 GB) EFI region mapping space +... unused hole ... +ffffffff80000000 - ffffffff9fffffff (=512 MB) kernel text mapping, from phys 0 ffffffffa0000000 - ffffffffff5fffff (=1526 MB) module mapping space ffffffffff600000 - ffffffffffdfffff (=8 MB) vsyscalls ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole +Architecture defines a 64-bit virtual address. Implementations can support +less. Currently supported are 48- and 57-bit virtual addresses. Bits 63 +through to the most-significant implemented bit are set to either all ones +or all zero. This causes hole between user space and kernel addresses. + The direct mapping covers all memory in the system up to the highest memory address (this means in some cases it can also include PCI memory holes). -vmalloc space is lazily synchronized into the different PML4 pages of -the processes using the page fault handler, with init_level4_pgt as +vmalloc space is lazily synchronized into the different PML4/PML5 pages of +the processes using the page fault handler, with init_top_pgt as reference. Current X86-64 implementations support up to 46 bits of address space (64 TB), @@ -39,6 +66,9 @@ memory window (this size is arbitrary, it can be raised later if needed). The mappings are not part of any other kernel PGD and are only available during EFI runtime calls. +The module mapping space size changes based on the CONFIG requirements for the +following fixmap section. + Note that if CONFIG_RANDOMIZE_MEMORY is enabled, the direct mapping of all physical memory, vmalloc/ioremap space and virtual memory map are randomized. Their order is preserved but their base will be offset early at boot time. diff --git a/Documentation/x86/zero-page.txt b/Documentation/x86/zero-page.txt index b8527c6b7646..97b7adbceda4 100644 --- a/Documentation/x86/zero-page.txt +++ b/Documentation/x86/zero-page.txt @@ -27,7 +27,7 @@ Offset Proto Name Meaning 1C0/020 ALL efi_info EFI 32 information (struct efi_info) 1E0/004 ALL alk_mem_k Alternative mem check, in KB 1E4/004 ALL scratch Scratch field for the kernel setup code -1E8/001 ALL e820_entries Number of entries in e820_map (below) +1E8/001 ALL e820_entries Number of entries in e820_table (below) 1E9/001 ALL eddbuf_entries Number of entries in eddbuf (below) 1EA/001 ALL edd_mbr_sig_buf_entries Number of entries in edd_mbr_sig_buffer (below) @@ -35,6 +35,6 @@ Offset Proto Name Meaning 1EC/001 ALL secure_boot Secure boot is enabled in the firmware 1EF/001 ALL sentinel Used to detect broken bootloaders 290/040 ALL edd_mbr_sig_buffer EDD MBR signatures -2D0/A00 ALL e820_map E820 memory map table - (array of struct e820entry) +2D0/A00 ALL e820_table E820 memory map table + (array of struct e820_entry) D00/1EC ALL eddbuf EDD data (array of struct edd_info) diff --git a/Documentation/zorro.txt b/Documentation/zorro.txt index 90a64d52bea2..d530971beb00 100644 --- a/Documentation/zorro.txt +++ b/Documentation/zorro.txt @@ -11,7 +11,7 @@ Last revised: September 5, 2003 The Zorro bus is the bus used in the Amiga family of computers. Thanks to AutoConfig(tm), it's 100% Plug-and-Play. -There are two types of Zorro busses, Zorro II and Zorro III: +There are two types of Zorro buses, Zorro II and Zorro III: - The Zorro II address space is 24-bit and lies within the first 16 MB of the Amiga's address map. |
