diff options
Diffstat (limited to 'Documentation')
719 files changed, 27988 insertions, 10313 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-net-batman-adv b/Documentation/ABI/obsolete/sysfs-class-net-batman-adv index 898106849e27..5bdbc8d40256 100644 --- a/Documentation/ABI/testing/sysfs-class-net-batman-adv +++ b/Documentation/ABI/obsolete/sysfs-class-net-batman-adv @@ -1,3 +1,5 @@ +This ABI is deprecated and will be removed after 2021. It is +replaced with the batadv generic netlink family. What: /sys/class/net/<iface>/batman-adv/elp_interval Date: Feb 2014 diff --git a/Documentation/ABI/testing/sysfs-class-net-mesh b/Documentation/ABI/obsolete/sysfs-class-net-mesh index c2b956d44a95..04c1a2932507 100644 --- a/Documentation/ABI/testing/sysfs-class-net-mesh +++ b/Documentation/ABI/obsolete/sysfs-class-net-mesh @@ -1,3 +1,5 @@ +This ABI is deprecated and will be removed after 2021. It is +replaced with the batadv generic netlink family. What: /sys/class/net/<mesh_iface>/mesh/aggregated_ogms Date: May 2010 diff --git a/Documentation/ABI/stable/sysfs-bus-nvmem b/Documentation/ABI/stable/sysfs-bus-nvmem index 5923ab4620c5..9ffba8576f7b 100644 --- a/Documentation/ABI/stable/sysfs-bus-nvmem +++ b/Documentation/ABI/stable/sysfs-bus-nvmem @@ -6,6 +6,8 @@ Description: This file allows user to read/write the raw NVMEM contents. Permissions for write to this file depends on the nvmem provider configuration. + Note: This file is only present if CONFIG_NVMEM_SYSFS + is enabled ex: hexdump /sys/bus/nvmem/devices/qfprom0/nvmem diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index 826689dcc2e6..8e8d167eca31 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -81,7 +81,9 @@ What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/latency Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: Channel signaling latency +Description: Channel signaling latency. This file is available only for + performance critical channels (storage, network, etc.) that use + the monitor page mechanism. Users: Debugging tools What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/out_mask @@ -95,7 +97,9 @@ What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/pending Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: Channel interrupt pending state +Description: Channel interrupt pending state. This file is available only for + performance critical channels (storage, network, etc.) that use + the monitor page mechanism. Users: Debugging tools What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/read_avail @@ -137,7 +141,9 @@ What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/monitor_id Date: January. 2018 KernelVersion: 4.16 Contact: Stephen Hemminger <sthemmin@microsoft.com> -Description: Monitor bit associated with channel +Description: Monitor bit associated with channel. This file is available only + for performance critical channels (storage, network, etc.) that + use the monitor page mechanism. Users: Debugging tools and userspace drivers What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/ring diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node index 3e90e1f3bf0a..f7ce68fbd4b9 100644 --- a/Documentation/ABI/stable/sysfs-devices-node +++ b/Documentation/ABI/stable/sysfs-devices-node @@ -90,4 +90,89 @@ Date: December 2009 Contact: Lee Schermerhorn <lee.schermerhorn@hp.com> Description: The node's huge page size control/query attributes. - See Documentation/admin-guide/mm/hugetlbpage.rst
\ No newline at end of file + See Documentation/admin-guide/mm/hugetlbpage.rst + +What: /sys/devices/system/node/nodeX/accessY/ +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The node's relationship to other nodes for access class "Y". + +What: /sys/devices/system/node/nodeX/accessY/initiators/ +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The directory containing symlinks to memory initiator + nodes that have class "Y" access to this target node's + memory. CPUs and other memory initiators in nodes not in + the list accessing this node's memory may have different + performance. + +What: /sys/devices/system/node/nodeX/accessY/targets/ +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The directory containing symlinks to memory targets that + this initiator node has class "Y" access. + +What: /sys/devices/system/node/nodeX/accessY/initiators/read_bandwidth +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + This node's read bandwidth in MB/s when accessed from + nodes found in this access class's linked initiators. + +What: /sys/devices/system/node/nodeX/accessY/initiators/read_latency +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + This node's read latency in nanoseconds when accessed + from nodes found in this access class's linked initiators. + +What: /sys/devices/system/node/nodeX/accessY/initiators/write_bandwidth +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + This node's write bandwidth in MB/s when accessed from + found in this access class's linked initiators. + +What: /sys/devices/system/node/nodeX/accessY/initiators/write_latency +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + This node's write latency in nanoseconds when access + from nodes found in this class's linked initiators. + +What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/ +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The directory containing attributes for the memory-side cache + level 'Y'. + +What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/indexing +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The caches associativity indexing: 0 for direct mapped, + non-zero if indexed. + +What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/line_size +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The number of bytes accessed from the next cache level on a + cache miss. + +What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/size +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The size of this memory side cache in bytes. + +What: /sys/devices/system/node/nodeX/memory_side_cache/indexY/write_policy +Date: December 2018 +Contact: Keith Busch <keith.busch@intel.com> +Description: + The cache write policy: 0 for write-back, 1 for write-through, + other or unknown. diff --git a/Documentation/ABI/testing/debugfs-wilco-ec b/Documentation/ABI/testing/debugfs-wilco-ec index f814f112e213..73a5a66ddca6 100644 --- a/Documentation/ABI/testing/debugfs-wilco-ec +++ b/Documentation/ABI/testing/debugfs-wilco-ec @@ -1,23 +1,46 @@ +What: /sys/kernel/debug/wilco_ec/h1_gpio +Date: April 2019 +KernelVersion: 5.2 +Description: + As part of Chrome OS's FAFT (Fully Automated Firmware Testing) + tests, we need to ensure that the H1 chip is properly setting + some GPIO lines. The h1_gpio attribute exposes the state + of the lines: + - ENTRY_TO_FACT_MODE in BIT(0) + - SPI_CHROME_SEL in BIT(1) + + Output will formatted with "0x%02x\n". + What: /sys/kernel/debug/wilco_ec/raw Date: January 2019 KernelVersion: 5.1 Description: Write and read raw mailbox commands to the EC. - For writing: - Bytes 0-1 indicate the message type: - 00 F0 = Execute Legacy Command - 00 F2 = Read/Write NVRAM Property - Byte 2 provides the command code - Bytes 3+ consist of the data passed in the request + You can write a hexadecimal sentence to raw, and that series of + bytes will be sent to the EC. Then, you can read the bytes of + response by reading from raw. - At least three bytes are required, for the msg type and command, - with additional bytes optional for additional data. + For writing, bytes 0-1 indicate the message type, one of enum + wilco_ec_msg_type. Byte 2+ consist of the data passed in the + request, starting at MBOX[0] + + At least three bytes are required for writing, two for the type + and at least a single byte of data. Only the first + EC_MAILBOX_DATA_SIZE bytes of MBOX will be used. Example: // Request EC info type 3 (EC firmware build date) - $ echo 00 f0 38 00 03 00 > raw + // Corresponds with sending type 0x00f0 with + // MBOX = [38, 00, 03, 00] + $ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw // View the result. The decoded ASCII result "12/21/18" is // included after the raw hex. - $ cat raw - 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 .12/21/18.8... + // Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, 38, ...] + $ cat /sys/kernel/debug/wilco_ec/raw + 00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00 ..12/21/18.8... + + Note that the first 32 bytes of the received MBOX[] will be + printed, even if some of the data is junk. It is up to you to + know how many of the first bytes of data are the actual + response. diff --git a/Documentation/ABI/testing/sysfs-bus-counter b/Documentation/ABI/testing/sysfs-bus-counter new file mode 100644 index 000000000000..566bd99fe0a5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-counter @@ -0,0 +1,230 @@ +What: /sys/bus/counter/devices/counterX/countY/count +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Count data of Count Y represented as a string. + +What: /sys/bus/counter/devices/counterX/countY/ceiling +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Count value ceiling for Count Y. This is the upper limit for the + respective counter. + +What: /sys/bus/counter/devices/counterX/countY/floor +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Count value floor for Count Y. This is the lower limit for the + respective counter. + +What: /sys/bus/counter/devices/counterX/countY/count_mode +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Count mode for channel Y. The ceiling and floor values for + Count Y are used by the count mode where required. The following + count modes are available: + + normal: + Counting is continuous in either direction. + + range limit: + An upper or lower limit is set, mimicking limit switches + in the mechanical counterpart. The upper limit is set to + the Count Y ceiling value, while the lower limit is set + to the Count Y floor value. The counter freezes at + count = ceiling when counting up, and at count = floor + when counting down. At either of these limits, the + counting is resumed only when the count direction is + reversed. + + non-recycle: + The counter is disabled whenever a counter overflow or + underflow takes place. The counter is re-enabled when a + new count value is loaded to the counter via a preset + operation or direct write. + + modulo-n: + A count value boundary is set between the Count Y floor + value and the Count Y ceiling value. The counter is + reset to the Count Y floor value at count = ceiling when + counting up, while the counter is set to the Count Y + ceiling value at count = floor when counting down; the + counter does not freeze at the boundary points, but + counts continuously throughout. + +What: /sys/bus/counter/devices/counterX/countY/count_mode_available +What: /sys/bus/counter/devices/counterX/countY/error_noise_available +What: /sys/bus/counter/devices/counterX/countY/function_available +What: /sys/bus/counter/devices/counterX/countY/signalZ_action_available +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Discrete set of available values for the respective Count Y + configuration are listed in this file. Values are delimited by + newline characters. + +What: /sys/bus/counter/devices/counterX/countY/direction +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only attribute that indicates the count direction of Count + Y. Two count directions are available: forward and backward. + + Some counter devices are able to determine the direction of + their counting. For example, quadrature encoding counters can + determine the direction of movement by evaluating the leading + phase of the respective A and B quadrature encoding signals. + This attribute exposes such count directions. + +What: /sys/bus/counter/devices/counterX/countY/enable +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Whether channel Y counter is enabled. Valid attribute values are + boolean. + + This attribute is intended to serve as a pause/unpause mechanism + for Count Y. Suppose a counter device is used to count the total + movement of a conveyor belt: this attribute allows an operator + to temporarily pause the counter, service the conveyor belt, + and then finally unpause the counter to continue where it had + left off. + +What: /sys/bus/counter/devices/counterX/countY/error_noise +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only attribute that indicates whether excessive noise is + present at the channel Y counter inputs. + +What: /sys/bus/counter/devices/counterX/countY/function +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Count function mode of Count Y; count function evaluation is + triggered by conditions specified by the Count Y signalZ_action + attributes. The following count functions are available: + + increase: + Accumulated count is incremented. + + decrease: + Accumulated count is decremented. + + pulse-direction: + Rising edges on signal A updates the respective count. + The input level of signal B determines direction. + + quadrature x1 a: + If direction is forward, rising edges on quadrature pair + signal A updates the respective count; if the direction + is backward, falling edges on quadrature pair signal A + updates the respective count. Quadrature encoding + determines the direction. + + quadrature x1 b: + If direction is forward, rising edges on quadrature pair + signal B updates the respective count; if the direction + is backward, falling edges on quadrature pair signal B + updates the respective count. Quadrature encoding + determines the direction. + + quadrature x2 a: + Any state transition on quadrature pair signal A updates + the respective count. Quadrature encoding determines the + direction. + + quadrature x2 b: + Any state transition on quadrature pair signal B updates + the respective count. Quadrature encoding determines the + direction. + + quadrature x4: + Any state transition on either quadrature pair signals + updates the respective count. Quadrature encoding + determines the direction. + +What: /sys/bus/counter/devices/counterX/countY/name +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only attribute that indicates the device-specific name of + Count Y. If possible, this should match the name of the + respective channel as it appears in the device datasheet. + +What: /sys/bus/counter/devices/counterX/countY/preset +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + If the counter device supports preset registers -- registers + used to load counter channels to a set count upon device-defined + preset operation trigger events -- the preset count for channel + Y is provided by this attribute. + +What: /sys/bus/counter/devices/counterX/countY/preset_enable +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Whether channel Y counter preset operation is enabled. Valid + attribute values are boolean. + +What: /sys/bus/counter/devices/counterX/countY/signalZ_action +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Action mode of Count Y for Signal Z. This attribute indicates + the condition of Signal Z that triggers the count function + evaluation for Count Y. The following action modes are + available: + + none: + Signal does not trigger the count function. In + Pulse-Direction count function mode, this Signal is + evaluated as Direction. + + rising edge: + Low state transitions to high state. + + falling edge: + High state transitions to low state. + + both edges: + Any state transition. + +What: /sys/bus/counter/devices/counterX/name +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only attribute that indicates the device-specific name of + the Counter. This should match the name of the device as it + appears in its respective datasheet. + +What: /sys/bus/counter/devices/counterX/num_counts +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only attribute that indicates the total number of Counts + belonging to the Counter. + +What: /sys/bus/counter/devices/counterX/num_signals +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only attribute that indicates the total number of Signals + belonging to the Counter. + +What: /sys/bus/counter/devices/counterX/signalY/signal +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Signal data of Signal Y represented as a string. + +What: /sys/bus/counter/devices/counterX/signalY/name +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only attribute that indicates the device-specific name of + Signal Y. If possible, this should match the name of the + respective signal as it appears in the device datasheet. diff --git a/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8 b/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8 new file mode 100644 index 000000000000..46b1f33b2fce --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-counter-104-quad-8 @@ -0,0 +1,36 @@ +What: /sys/bus/counter/devices/counterX/signalY/index_polarity +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Active level of index input Signal Y; irrelevant in + non-synchronous load mode. + +What: /sys/bus/counter/devices/counterX/signalY/index_polarity_available +What: /sys/bus/counter/devices/counterX/signalY/synchronous_mode_available +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Discrete set of available values for the respective Signal Y + configuration are listed in this file. + +What: /sys/bus/counter/devices/counterX/signalY/synchronous_mode +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Configure the counter associated with Signal Y for + non-synchronous or synchronous load mode. Synchronous load mode + cannot be selected in non-quadrature (Pulse-Direction) clock + mode. + + non-synchronous: + A logic low level is the active level at this index + input. The index function (as enabled via preset_enable) + is performed directly on the active level of the index + input. + + synchronous: + Intended for interfacing with encoder Index output in + quadrature clock mode. The active level is configured + via index_polarity. The index function (as enabled via + preset_enable) is performed synchronously with the + quadrature clock on the active level of the index input. diff --git a/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec b/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec new file mode 100644 index 000000000000..7d2e7b363467 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec @@ -0,0 +1,16 @@ +What: /sys/bus/counter/devices/counterX/countY/prescaler_available +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Discrete set of available values for the respective Count Y + configuration are listed in this file. Values are delimited by + newline characters. + +What: /sys/bus/counter/devices/counterX/countY/prescaler +KernelVersion: 5.2 +Contact: linux-iio@vger.kernel.org +Description: + Configure the prescaler value associated with Count Y. + On the FlexTimer, the counter clock source passes through a + prescaler (i.e. a counter). This acts like a clock + divider. diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x new file mode 100644 index 000000000000..0b0de8cd0d13 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x @@ -0,0 +1,20 @@ +What: /sys/bus/i2c/.../idle_state +Date: January 2019 +KernelVersion: 5.2 +Contact: Robert Shearman <robert.shearman@att.com> +Description: + Value that exists only for mux devices that can be + written to control the behaviour of the multiplexer on + idle. Possible values: + -2 - disconnect on idle, i.e. deselect the last used + channel, which is useful when there is a device + with an address that conflicts with another + device on another mux on the same parent bus. + -1 - leave the mux as-is, which is the most optimal + setting in terms of I2C operations and is the + default mode. + 0..<nchans> - set the mux to a predetermined channel, + which is useful if there is one channel that is + used almost always, and you want to reduce the + latency for normal operations after rare + transactions on other channels diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 864f8efd12e5..6aef7dbbde44 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -1656,6 +1656,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_countY_raw KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Raw counter device counts from channel Y. For quadrature counters, multiplication by an available [Y]_scale results in the counts of a single quadrature signal phase from channel Y. @@ -1664,6 +1666,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_indexY_raw KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + 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 @@ -1673,6 +1677,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_count_count_direction_available KernelVersion: 4.12 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + A list of possible counting directions which are: - "up" : counter device is increasing. - "down": counter device is decreasing. @@ -1681,6 +1687,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_countY_count_direction KernelVersion: 4.12 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Raw counter device counters direction for channel Y. What: /sys/bus/iio/devices/iio:deviceX/in_phaseY_raw 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 7fac2c268d9a..bac3d0d48b7b 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 +++ b/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 @@ -6,6 +6,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_index_synchronous_mode_available KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Discrete set of available values for the respective counter configuration are listed in this file. @@ -13,6 +15,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_countY_count_mode KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Count mode for channel Y. Four count modes are available: normal, range limit, non-recycle, and modulo-n. The preset value for channel Y is used by the count mode where required. @@ -47,6 +51,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_countY_noise_error KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Read-only attribute that indicates whether excessive noise is present at the channel Y count inputs in quadrature clock mode; irrelevant in non-quadrature clock mode. @@ -55,6 +61,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_countY_preset KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + If the counter device supports preset registers, the preset count for channel Y is provided by this attribute. @@ -62,6 +70,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_countY_quadrature_mode KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Configure channel Y counter for non-quadrature or quadrature clock mode. Selecting non-quadrature clock mode will disable synchronous load mode. In quadrature clock mode, the channel Y @@ -83,6 +93,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_countY_set_to_preset_on_index KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Whether to set channel Y counter with channel Y preset value when channel Y index input is active, or continuously count. Valid attribute values are boolean. @@ -91,6 +103,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_indexY_index_polarity KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Active level of channel Y index input; irrelevant in non-synchronous load mode. @@ -98,6 +112,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_indexY_synchronous_mode KernelVersion: 4.10 Contact: linux-iio@vger.kernel.org Description: + This interface is deprecated; please use the Counter subsystem. + Configure channel Y counter for non-synchronous or synchronous load mode. Synchronous load mode cannot be selected in non-quadrature clock mode. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-impedance-analyzer-ad5933 b/Documentation/ABI/testing/sysfs-bus-iio-impedance-analyzer-ad5933 new file mode 100644 index 000000000000..0e86747c67f8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-impedance-analyzer-ad5933 @@ -0,0 +1,35 @@ +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_start +Date: March 2019 +KernelVersion: 3.1.0 +Contact: linux-iio@vger.kernel.org +Description: + Frequency sweep start frequency in Hz. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_increment +Date: March 2019 +KernelVersion: 3.1.0 +Contact: linux-iio@vger.kernel.org +Description: + Frequency increment in Hz (step size) between consecutive + frequency points along the sweep. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_points +Date: March 2019 +KernelVersion: 3.1.0 +Contact: linux-iio@vger.kernel.org +Description: + Number of frequency points (steps) in the frequency sweep. + This value, in conjunction with the + out_altvoltageY_frequency_start and the + out_altvoltageY_frequency_increment, determines the frequency + sweep range for the sweep operation. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_settling_cycles +Date: March 2019 +KernelVersion: 3.1.0 +Contact: linux-iio@vger.kernel.org +Description: + Number of output excitation cycles (settling time cycles) + that are allowed to pass through the unknown impedance, + after each frequency increment, and before the ADC is triggered + to perform a conversion sequence of the response signal. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sps30 b/Documentation/ABI/testing/sysfs-bus-iio-sps30 index 143df8e89d08..06e1c272537b 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-sps30 +++ b/Documentation/ABI/testing/sysfs-bus-iio-sps30 @@ -1,6 +1,6 @@ What: /sys/bus/iio/devices/iio:deviceX/start_cleaning Date: December 2018 -KernelVersion: 4.22 +KernelVersion: 5.0 Contact: linux-iio@vger.kernel.org Description: Writing 1 starts sensor self cleaning. Internal fan accelerates diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 new file mode 100644 index 000000000000..3b3509a3ef2f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 @@ -0,0 +1,24 @@ +What: /sys/bus/iio/devices/iio:deviceX/fault_oc +KernelVersion: 5.1 +Contact: linux-iio@vger.kernel.org +Description: + Open-circuit fault. The detection of open-circuit faults, + such as those caused by broken thermocouple wires. + Reading returns either '1' or '0'. + '1' = An open circuit such as broken thermocouple wires + has been detected. + '0' = No open circuit or broken thermocouple wires are detected + +What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv +KernelVersion: 5.1 +Contact: linux-iio@vger.kernel.org +Description: + Overvoltage or Undervoltage Input Fault. The internal circuitry + is protected from excessive voltages applied to the thermocouple + cables by integrated MOSFETs at the T+ and T- inputs, and the + BIAS output. These MOSFETs turn off when the input voltage is + negative or greater than VDD. + Reading returns either '1' or '0'. + '1' = The input voltage is negative or greater than VDD. + '0' = The input voltage is positive and less than VDD (normal + state). diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc index b940c5d91cf7..f54ae244f3f1 100644 --- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc @@ -30,4 +30,12 @@ Description: (RW) Configure MSC buffer size for "single" or "multi" modes. there are no active users and tracing is not enabled) and then allocates a new one. +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/win_switch +Date: May 2019 +KernelVersion: 5.2 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Trigger window switch for the MSC's buffer, in + multi-window mode. In "multi" mode, accepts writes of "1", thereby + triggering a window switch for the buffer. Returns an error in any + other operating mode or attempts to write something other than "1". diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei index 17d7444a2397..a92d844f806e 100644 --- a/Documentation/ABI/testing/sysfs-class-mei +++ b/Documentation/ABI/testing/sysfs-class-mei @@ -65,3 +65,18 @@ Description: Display the ME firmware version. <platform>:<major>.<minor>.<milestone>.<build_no>. There can be up to three such blocks for different FW components. + +What: /sys/class/mei/meiN/dev_state +Date: Mar 2019 +KernelVersion: 5.1 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Display the ME device state. + + The device state can have following values: + INITIALIZING + INIT_CLIENTS + ENABLED + RESETTING + DISABLED + POWER_DOWN + POWER_UP diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ipmi b/Documentation/ABI/testing/sysfs-devices-platform-ipmi index 2a781e7513b7..afb5db856e1c 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-ipmi +++ b/Documentation/ABI/testing/sysfs-devices-platform-ipmi @@ -212,7 +212,7 @@ Description: Messages may be broken into parts if they are long. - receieved_messages: (RO) Number of message responses + received_messages: (RO) Number of message responses received. received_message_parts: (RO) Number of message fragments diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 5eea46fefcb2..1528239f69b2 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -484,6 +484,7 @@ What: /sys/devices/system/cpu/vulnerabilities /sys/devices/system/cpu/vulnerabilities/spectre_v2 /sys/devices/system/cpu/vulnerabilities/spec_store_bypass /sys/devices/system/cpu/vulnerabilities/l1tf + /sys/devices/system/cpu/vulnerabilities/mds Date: January 2018 Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> Description: Information about CPU vulnerabilities @@ -496,8 +497,7 @@ Description: Information about CPU vulnerabilities "Vulnerable" CPU is affected and no mitigation in effect "Mitigation: $M" CPU is affected and mitigation $M is in effect - Details about the l1tf file can be found in - Documentation/admin-guide/l1tf.rst + See also: Documentation/admin-guide/hw-vuln/index.rst What: /sys/devices/system/cpu/smt /sys/devices/system/cpu/smt/active @@ -520,3 +520,21 @@ Description: Control Symetric Multi Threading (SMT) If control status is "forceoff" or "notsupported" writes are rejected. + +What: /sys/devices/system/cpu/cpu#/power/energy_perf_bias +Date: March 2019 +Contact: linux-pm@vger.kernel.org +Description: Intel Energy and Performance Bias Hint (EPB) + + EPB for the given CPU in a sliding scale 0 - 15, where a value + of 0 corresponds to a hint preference for highest performance + and a value of 15 corresponds to the maximum energy savings. + + In order to change the EPB value for the CPU, write either + a number in the 0 - 15 sliding scale above, or one of the + strings: "performance", "balance-performance", "normal", + "balance-power", "power" (that represent values reflected by + their meaning), to this attribute. + + This attribute is present for all online CPUs supporting the + Intel EPB feature. diff --git a/Documentation/ABI/testing/sysfs-driver-ucsi-ccg b/Documentation/ABI/testing/sysfs-driver-ucsi-ccg new file mode 100644 index 000000000000..45cf62ad89e9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-ucsi-ccg @@ -0,0 +1,6 @@ +What: /sys/bus/i2c/drivers/ucsi_ccg/.../do_flash +Date: May 2019 +Contact: Ajay Gupta <ajayg@nvidia.com> +Description: + Tell the driver for Cypress CCGx Type-C controller to attempt + firmware upgrade by writing [Yy1] to the file. diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch index 85db352f68f9..bea7bd5a1d5f 100644 --- a/Documentation/ABI/testing/sysfs-kernel-livepatch +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -45,7 +45,7 @@ Description: use this feature without a clearance from a patch distributor. Removal (rmmod) of patch modules is permanently disabled when the feature is used. See - Documentation/livepatch/livepatch.txt for more information. + Documentation/livepatch/livepatch.rst for more information. What: /sys/kernel/livepatch/<patch>/<object> Date: Nov 2014 diff --git a/Documentation/ABI/testing/usb-uevent b/Documentation/ABI/testing/usb-uevent new file mode 100644 index 000000000000..d35c3cad892c --- /dev/null +++ b/Documentation/ABI/testing/usb-uevent @@ -0,0 +1,27 @@ +What: Raise a uevent when a USB Host Controller has died +Date: 2019-04-17 +KernelVersion: 5.2 +Contact: linux-usb@vger.kernel.org +Description: When the USB Host Controller has entered a state where it is no + longer functional a uevent will be raised. The uevent will + contain ACTION=offline and ERROR=DEAD. + + Here is an example taken using udevadm monitor -p: + + KERNEL[130.428945] offline /devices/pci0000:00/0000:00:10.0/usb2 (usb) + ACTION=offline + BUSNUM=002 + DEVNAME=/dev/bus/usb/002/001 + DEVNUM=001 + DEVPATH=/devices/pci0000:00/0000:00:10.0/usb2 + DEVTYPE=usb_device + DRIVER=usb + ERROR=DEAD + MAJOR=189 + MINOR=128 + PRODUCT=1d6b/2/414 + SEQNUM=2168 + SUBSYSTEM=usb + TYPE=9/0/1 + +Users: chromium-os-dev@chromium.org diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 1a721d0f35c8..cb712a02f59f 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -147,7 +147,7 @@ networking subsystems make sure that the buffers they use are valid for you to DMA from/to. DMA addressing capabilities -========================== +=========================== By default, the kernel assumes that your device can address 32-bits of DMA addressing. For a 64-bit capable device, this needs to be increased, and for @@ -365,13 +365,12 @@ __get_free_pages() (but takes size instead of a page order). If your driver needs regions sized smaller than a page, you may prefer using the dma_pool interface, described below. -The consistent DMA mapping interfaces, for non-NULL dev, will by -default return a DMA address which is 32-bit addressable. Even if the -device indicates (via DMA mask) that it may address the upper 32-bits, -consistent allocation will only return > 32-bit addresses for DMA if -the consistent DMA mask has been explicitly changed via -dma_set_coherent_mask(). This is true of the dma_pool interface as -well. +The consistent DMA mapping interfaces, will by default return a DMA address +which is 32-bit addressable. Even if the device indicates (via the DMA mask) +that it may address the upper 32-bits, consistent allocation will only +return > 32-bit addresses for DMA if the consistent DMA mask has been +explicitly changed via dma_set_coherent_mask(). This is true of the +dma_pool interface as well. dma_alloc_coherent() returns two values: the virtual address which you can use to access it from the CPU and dma_handle which you pass to the diff --git a/Documentation/Makefile b/Documentation/Makefile index 9786957c6a35..e889e7cb8511 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -28,8 +28,13 @@ ifeq ($(HAVE_SPHINX),0) else # HAVE_SPHINX -# User-friendly check for pdflatex +# User-friendly check for pdflatex and latexmk HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) +HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi) + +ifeq ($(HAVE_LATEXMK),1) + PDFLATEX := latexmk -$(PDFLATEX) +endif #HAVE_LATEXMK # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 @@ -82,7 +87,7 @@ pdfdocs: else # HAVE_PDFLATEX pdfdocs: latexdocs - $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) endif # HAVE_PDFLATEX diff --git a/Documentation/accounting/psi.txt b/Documentation/accounting/psi.txt index 7e71c9c1d8e9..5cbe5659e3b7 100644 --- a/Documentation/accounting/psi.txt +++ b/Documentation/accounting/psi.txt @@ -63,6 +63,110 @@ as well as medium and long term trends. The total absolute stall time spikes which wouldn't necessarily make a dent in the time averages, or to average trends over custom time frames. +Monitoring for pressure thresholds +================================== + +Users can register triggers and use poll() to be woken up when resource +pressure exceeds certain thresholds. + +A trigger describes the maximum cumulative stall time over a specific +time window, e.g. 100ms of total stall time within any 500ms window to +generate a wakeup event. + +To register a trigger user has to open psi interface file under +/proc/pressure/ representing the resource to be monitored and write the +desired threshold and time window. The open file descriptor should be +used to wait for trigger events using select(), poll() or epoll(). +The following format is used: + +<some|full> <stall amount in us> <time window in us> + +For example writing "some 150000 1000000" into /proc/pressure/memory +would add 150ms threshold for partial memory stall measured within +1sec time window. Writing "full 50000 1000000" into /proc/pressure/io +would add 50ms threshold for full io stall measured within 1sec time window. + +Triggers can be set on more than one psi metric and more than one trigger +for the same psi metric can be specified. However for each trigger a separate +file descriptor is required to be able to poll it separately from others, +therefore for each trigger a separate open() syscall should be made even +when opening the same psi interface file. + +Monitors activate only when system enters stall state for the monitored +psi metric and deactivates upon exit from the stall state. While system is +in the stall state psi signal growth is monitored at a rate of 10 times per +tracking window. + +The kernel accepts window sizes ranging from 500ms to 10s, therefore min +monitoring update interval is 50ms and max is 1s. Min limit is set to +prevent overly frequent polling. Max limit is chosen as a high enough number +after which monitors are most likely not needed and psi averages can be used +instead. + +When activated, psi monitor stays active for at least the duration of one +tracking window to avoid repeated activations/deactivations when system is +bouncing in and out of the stall state. + +Notifications to the userspace are rate-limited to one per tracking window. + +The trigger will de-register when the file descriptor used to define the +trigger is closed. + +Userspace monitor usage example +=============================== + +#include <errno.h> +#include <fcntl.h> +#include <stdio.h> +#include <poll.h> +#include <string.h> +#include <unistd.h> + +/* + * Monitor memory partial stall with 1s tracking window size + * and 150ms threshold. + */ +int main() { + const char trig[] = "some 150000 1000000"; + struct pollfd fds; + int n; + + fds.fd = open("/proc/pressure/memory", O_RDWR | O_NONBLOCK); + if (fds.fd < 0) { + printf("/proc/pressure/memory open error: %s\n", + strerror(errno)); + return 1; + } + fds.events = POLLPRI; + + if (write(fds.fd, trig, strlen(trig) + 1) < 0) { + printf("/proc/pressure/memory write error: %s\n", + strerror(errno)); + return 1; + } + + printf("waiting for events...\n"); + while (1) { + n = poll(&fds, 1, -1); + if (n < 0) { + printf("poll error: %s\n", strerror(errno)); + return 1; + } + if (fds.revents & POLLERR) { + printf("got POLLERR, event source is gone\n"); + return 0; + } + if (fds.revents & POLLPRI) { + printf("event triggered!\n"); + } else { + printf("unknown event received: 0x%x\n", fds.revents); + return 1; + } + } + + return 0; +} + Cgroup2 interface ================= @@ -71,3 +175,6 @@ mounted, pressure stall information is also tracked for tasks grouped into cgroups. Each subdirectory in the cgroupfs mountpoint contains cpu.pressure, memory.pressure, and io.pressure files; the format is the same as the /proc/pressure/ files. + +Per-cgroup psi monitors can be specified and used the same way as +system-wide ones. diff --git a/Documentation/acpi/dsd/leds.txt b/Documentation/acpi/dsd/leds.txt new file mode 100644 index 000000000000..81a63af42ed2 --- /dev/null +++ b/Documentation/acpi/dsd/leds.txt @@ -0,0 +1,99 @@ +Describing and referring to LEDs in ACPI + +Individual LEDs are described by hierarchical data extension [6] nodes under the +device node, the LED driver chip. The "reg" property in the LED specific nodes +tells the numerical ID of each individual LED output to which the LEDs are +connected. [3] The hierarchical data nodes are named "led@X", where X is the +number of the LED output. + +Referring to LEDs in Device tree is documented in [4], in "flash-leds" property +documentation. In short, LEDs are directly referred to by using phandles. + +While Device tree allows referring to any node in the tree[1], in ACPI +references are limited to device nodes only [2]. For this reason using the same +mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes +is documented in [7]. + +ACPI allows (as does DT) using integer arguments after the reference. A +combination of the LED driver device reference and an integer argument, +referring to the "reg" property of the relevant LED, is used to identify +individual LEDs. The value of the "reg" property is a contract between the +firmware and software, it uniquely identifies the LED driver outputs. + +Under the LED driver device, The first hierarchical data extension package list +entry shall contain the string "led@" followed by the number of the LED, +followed by the referred object name. That object shall be named "LED" followed +by the number of the LED. + +An ASL example of a camera sensor device and a LED driver device for two LEDs. +Objects not relevant for LEDs or the references to them have been omitted. + + Device (LED) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "led@0", LED0 }, + Package () { "led@1", LED1 }, + } + }) + Name (LED0, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "flash-max-microamp", 1000000 }, + Package () { "flash-timeout-us", 200000 }, + Package () { "led-max-microamp", 100000 }, + Package () { "label", "white:flash" }, + } + }) + Name (LED1, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 1 }, + Package () { "led-max-microamp", 10000 }, + Package () { "label", "red:indicator" }, + } + }) + } + + Device (SEN) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { + "flash-leds", + Package () { ^LED, "led@0", ^LED, "led@1" }, + } + } + }) + } + +where + + LED LED driver device + LED0 First LED + LED1 Second LED + SEN Camera sensor device (or another device the LED is + related to) + +[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21. + +[2] Advanced Configuration and Power Interface Specification. + <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>, + referenced 2019-02-21. + +[3] Documentation/devicetree/bindings/leds/common.txt + +[4] Documentation/devicetree/bindings/media/video-interfaces.txt + +[5] Device Properties UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + referenced 2019-02-21. + +[6] Hierarchical Data Extension UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, + referenced 2019-02-21. + +[7] Documentation/acpi/dsd/data-node-reference.txt diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 20f92c16ffbf..88e746074252 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -864,6 +864,8 @@ All cgroup core files are prefixed with "cgroup." populated 1 if the cgroup or its descendants contains any live processes; otherwise, 0. + frozen + 1 if the cgroup is frozen; otherwise, 0. cgroup.max.descendants A read-write single value files. The default is "max". @@ -897,6 +899,31 @@ All cgroup core files are prefixed with "cgroup." A dying cgroup can consume system resources not exceeding limits, which were active at the moment of cgroup deletion. + cgroup.freeze + A read-write single value file which exists on non-root cgroups. + Allowed values are "0" and "1". The default is "0". + + Writing "1" to the file causes freezing of the cgroup and all + descendant cgroups. This means that all belonging processes will + be stopped and will not run until the cgroup will be explicitly + unfrozen. Freezing of the cgroup may take some time; when this action + is completed, the "frozen" value in the cgroup.events control file + will be updated to "1" and the corresponding notification will be + issued. + + A cgroup can be frozen either by its own settings, or by settings + of any ancestor cgroups. If any of ancestor cgroups is frozen, the + cgroup will remain frozen. + + Processes in the frozen cgroup can be killed by a fatal signal. + They also can enter and leave a frozen cgroup: either by an explicit + move by a user, or if freezing of the cgroup races with fork(). + If a process is moved to a frozen cgroup, it stops. If a process is + moved out of a frozen cgroup, it becomes running. + + Frozen status of a cgroup doesn't affect any cgroup tree operations: + it's possible to delete a frozen (and empty) cgroup, as well as + create new sub-cgroups. Controllers =========== diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst index e506d3dae510..059ddcbe769d 100644 --- a/Documentation/admin-guide/ext4.rst +++ b/Documentation/admin-guide/ext4.rst @@ -91,10 +91,48 @@ Currently Available * large block (up to pagesize) support * efficient new ordered mode in JBD2 and ext4 (avoid using buffer head to force the ordering) +* Case-insensitive file name lookups [1] Filesystems with a block size of 1k may see a limit imposed by the directory hash tree having a maximum depth of two. +case-insensitive file name lookups +====================================================== + +The case-insensitive file name lookup feature is supported on a +per-directory basis, allowing the user to mix case-insensitive and +case-sensitive directories in the same filesystem. It is enabled by +flipping the +F inode attribute of an empty directory. The +case-insensitive string match operation is only defined when we know how +text in encoded in a byte sequence. For that reason, in order to enable +case-insensitive directories, the filesystem must have the +casefold feature, which stores the filesystem-wide encoding +model used. By default, the charset adopted is the latest version of +Unicode (12.1.0, by the time of this writing), encoded in the UTF-8 +form. The comparison algorithm is implemented by normalizing the +strings to the Canonical decomposition form, as defined by Unicode, +followed by a byte per byte comparison. + +The case-awareness is name-preserving on the disk, meaning that the file +name provided by userspace is a byte-per-byte match to what is actually +written in the disk. The Unicode normalization format used by the +kernel is thus an internal representation, and not exposed to the +userspace nor to the disk, with the important exception of disk hashes, +used on large case-insensitive directories with DX feature. On DX +directories, the hash must be calculated using the casefolded version of +the filename, meaning that the normalization format used actually has an +impact on where the directory entry is stored. + +When we change from viewing filenames as opaque byte sequences to seeing +them as encoded strings we need to address what happens when a program +tries to create a file with an invalid name. The Unicode subsystem +within the kernel leaves the decision of what to do in this case to the +filesystem, which select its preferred behavior by enabling/disabling +the strict mode. When Ext4 encounters one of those strings and the +filesystem did not require strict mode, it falls back to considering the +entire string as an opaque byte sequence, which still allows the user to +operate on that file, but the case-insensitive lookups won't work. + Options ======= diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst new file mode 100644 index 000000000000..ffc064c1ec68 --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/index.rst @@ -0,0 +1,13 @@ +======================== +Hardware vulnerabilities +======================== + +This section describes CPU vulnerabilities and provides an overview of the +possible mitigations along with guidance for selecting mitigations if they +are configurable at compile, boot or run time. + +.. toctree:: + :maxdepth: 1 + + l1tf + mds diff --git a/Documentation/admin-guide/l1tf.rst b/Documentation/admin-guide/hw-vuln/l1tf.rst index 9af977384168..31653a9f0e1b 100644 --- a/Documentation/admin-guide/l1tf.rst +++ b/Documentation/admin-guide/hw-vuln/l1tf.rst @@ -445,6 +445,7 @@ The default is 'cond'. If 'l1tf=full,force' is given on the kernel command line, then 'always' is enforced and the kvm-intel.vmentry_l1d_flush module parameter is ignored and writes to the sysfs file are rejected. +.. _mitigation_selection: Mitigation selection guide -------------------------- diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst new file mode 100644 index 000000000000..e3a796c0d3a2 --- /dev/null +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -0,0 +1,308 @@ +MDS - Microarchitectural Data Sampling +====================================== + +Microarchitectural Data Sampling is a hardware vulnerability which allows +unprivileged speculative access to data which is available in various CPU +internal buffers. + +Affected processors +------------------- + +This vulnerability affects a wide range of Intel processors. The +vulnerability is not present on: + + - Processors from AMD, Centaur and other non Intel vendors + + - Older processor models, where the CPU family is < 6 + + - Some Atoms (Bonnell, Saltwell, Goldmont, GoldmontPlus) + + - Intel processors which have the ARCH_CAP_MDS_NO bit set in the + IA32_ARCH_CAPABILITIES MSR. + +Whether a processor is affected or not can be read out from the MDS +vulnerability file in sysfs. See :ref:`mds_sys_info`. + +Not all processors are affected by all variants of MDS, but the mitigation +is identical for all of them so the kernel treats them as a single +vulnerability. + +Related CVEs +------------ + +The following CVE entries are related to the MDS vulnerability: + + ============== ===== =================================================== + CVE-2018-12126 MSBDS Microarchitectural Store Buffer Data Sampling + CVE-2018-12130 MFBDS Microarchitectural Fill Buffer Data Sampling + CVE-2018-12127 MLPDS Microarchitectural Load Port Data Sampling + CVE-2019-11091 MDSUM Microarchitectural Data Sampling Uncacheable Memory + ============== ===== =================================================== + +Problem +------- + +When performing store, load, L1 refill operations, processors write data +into temporary microarchitectural structures (buffers). The data in the +buffer can be forwarded to load operations as an optimization. + +Under certain conditions, usually a fault/assist caused by a load +operation, data unrelated to the load memory address can be speculatively +forwarded from the buffers. Because the load operation causes a fault or +assist and its result will be discarded, the forwarded data will not cause +incorrect program execution or state changes. But a malicious operation +may be able to forward this speculative data to a disclosure gadget which +allows in turn to infer the value via a cache side channel attack. + +Because the buffers are potentially shared between Hyper-Threads cross +Hyper-Thread attacks are possible. + +Deeper technical information is available in the MDS specific x86 +architecture section: :ref:`Documentation/x86/mds.rst <mds>`. + + +Attack scenarios +---------------- + +Attacks against the MDS vulnerabilities can be mounted from malicious non +priviledged user space applications running on hosts or guest. Malicious +guest OSes can obviously mount attacks as well. + +Contrary to other speculation based vulnerabilities the MDS vulnerability +does not allow the attacker to control the memory target address. As a +consequence the attacks are purely sampling based, but as demonstrated with +the TLBleed attack samples can be postprocessed successfully. + +Web-Browsers +^^^^^^^^^^^^ + + It's unclear whether attacks through Web-Browsers are possible at + all. The exploitation through Java-Script is considered very unlikely, + but other widely used web technologies like Webassembly could possibly be + abused. + + +.. _mds_sys_info: + +MDS system information +----------------------- + +The Linux kernel provides a sysfs interface to enumerate the current MDS +status of the system: whether the system is vulnerable, and which +mitigations are active. The relevant sysfs file is: + +/sys/devices/system/cpu/vulnerabilities/mds + +The possible values in this file are: + + .. list-table:: + + * - 'Not affected' + - The processor is not vulnerable + * - 'Vulnerable' + - The processor is vulnerable, but no mitigation enabled + * - 'Vulnerable: Clear CPU buffers attempted, no microcode' + - The processor is vulnerable but microcode is not updated. + + The mitigation is enabled on a best effort basis. See :ref:`vmwerv` + * - 'Mitigation: Clear CPU buffers' + - The processor is vulnerable and the CPU buffer clearing mitigation is + enabled. + +If the processor is vulnerable then the following information is appended +to the above information: + + ======================== ============================================ + 'SMT vulnerable' SMT is enabled + 'SMT mitigated' SMT is enabled and mitigated + 'SMT disabled' SMT is disabled + 'SMT Host state unknown' Kernel runs in a VM, Host SMT state unknown + ======================== ============================================ + +.. _vmwerv: + +Best effort mitigation mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + If the processor is vulnerable, but the availability of the microcode based + mitigation mechanism is not advertised via CPUID the kernel selects a best + effort mitigation mode. This mode invokes the mitigation instructions + without a guarantee that they clear the CPU buffers. + + This is done to address virtualization scenarios where the host has the + microcode update applied, but the hypervisor is not yet updated to expose + the CPUID to the guest. If the host has updated microcode the protection + takes effect otherwise a few cpu cycles are wasted pointlessly. + + The state in the mds sysfs file reflects this situation accordingly. + + +Mitigation mechanism +------------------------- + +The kernel detects the affected CPUs and the presence of the microcode +which is required. + +If a CPU is affected and the microcode is available, then the kernel +enables the mitigation by default. The mitigation can be controlled at boot +time via a kernel command line option. See +:ref:`mds_mitigation_control_command_line`. + +.. _cpu_buffer_clear: + +CPU buffer clearing +^^^^^^^^^^^^^^^^^^^ + + The mitigation for MDS clears the affected CPU buffers on return to user + space and when entering a guest. + + If SMT is enabled it also clears the buffers on idle entry when the CPU + is only affected by MSBDS and not any other MDS variant, because the + other variants cannot be protected against cross Hyper-Thread attacks. + + For CPUs which are only affected by MSBDS the user space, guest and idle + transition mitigations are sufficient and SMT is not affected. + +.. _virt_mechanism: + +Virtualization mitigation +^^^^^^^^^^^^^^^^^^^^^^^^^ + + The protection for host to guest transition depends on the L1TF + vulnerability of the CPU: + + - CPU is affected by L1TF: + + If the L1D flush mitigation is enabled and up to date microcode is + available, the L1D flush mitigation is automatically protecting the + guest transition. + + If the L1D flush mitigation is disabled then the MDS mitigation is + invoked explicit when the host MDS mitigation is enabled. + + For details on L1TF and virtualization see: + :ref:`Documentation/admin-guide/hw-vuln//l1tf.rst <mitigation_control_kvm>`. + + - CPU is not affected by L1TF: + + CPU buffers are flushed before entering the guest when the host MDS + mitigation is enabled. + + The resulting MDS protection matrix for the host to guest transition: + + ============ ===== ============= ============ ================= + L1TF MDS VMX-L1FLUSH Host MDS MDS-State + + Don't care No Don't care N/A Not affected + + Yes Yes Disabled Off Vulnerable + + Yes Yes Disabled Full Mitigated + + Yes Yes Enabled Don't care Mitigated + + No Yes N/A Off Vulnerable + + No Yes N/A Full Mitigated + ============ ===== ============= ============ ================= + + This only covers the host to guest transition, i.e. prevents leakage from + host to guest, but does not protect the guest internally. Guests need to + have their own protections. + +.. _xeon_phi: + +XEON PHI specific considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The XEON PHI processor family is affected by MSBDS which can be exploited + cross Hyper-Threads when entering idle states. Some XEON PHI variants allow + to use MWAIT in user space (Ring 3) which opens an potential attack vector + for malicious user space. The exposure can be disabled on the kernel + command line with the 'ring3mwait=disable' command line option. + + XEON PHI is not affected by the other MDS variants and MSBDS is mitigated + before the CPU enters a idle state. As XEON PHI is not affected by L1TF + either disabling SMT is not required for full protection. + +.. _mds_smt_control: + +SMT control +^^^^^^^^^^^ + + All MDS variants except MSBDS can be attacked cross Hyper-Threads. That + means on CPUs which are affected by MFBDS or MLPDS it is necessary to + disable SMT for full protection. These are most of the affected CPUs; the + exception is XEON PHI, see :ref:`xeon_phi`. + + Disabling SMT can have a significant performance impact, but the impact + depends on the type of workloads. + + See the relevant chapter in the L1TF mitigation documentation for details: + :ref:`Documentation/admin-guide/hw-vuln/l1tf.rst <smt_control>`. + + +.. _mds_mitigation_control_command_line: + +Mitigation control on the kernel command line +--------------------------------------------- + +The kernel command line allows to control the MDS mitigations at boot +time with the option "mds=". The valid arguments for this option are: + + ============ ============================================================= + full If the CPU is vulnerable, enable all available mitigations + for the MDS vulnerability, CPU buffer clearing on exit to + userspace and when entering a VM. Idle transitions are + protected as well if SMT is enabled. + + It does not automatically disable SMT. + + full,nosmt The same as mds=full, with SMT disabled on vulnerable + CPUs. This is the complete mitigation. + + off Disables MDS mitigations completely. + + ============ ============================================================= + +Not specifying this option is equivalent to "mds=full". + + +Mitigation selection guide +-------------------------- + +1. Trusted userspace +^^^^^^^^^^^^^^^^^^^^ + + If all userspace applications are from a trusted source and do not + execute untrusted code which is supplied externally, then the mitigation + can be disabled. + + +2. Virtualization with trusted guests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The same considerations as above versus trusted user space apply. + +3. Virtualization with untrusted guests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The protection depends on the state of the L1TF mitigations. + See :ref:`virt_mechanism`. + + If the MDS mitigation is enabled and SMT is disabled, guest to host and + guest to guest attacks are prevented. + +.. _mds_default_mitigations: + +Default mitigations +------------------- + + The kernel default mitigations for vulnerable processors are: + + - Enable CPU buffer clearing + + The kernel does not by default enforce the disabling of SMT, which leaves + SMT systems vulnerable when running untrusted code. The same rationale as + for L1TF applies. + See :ref:`Documentation/admin-guide/hw-vuln//l1tf.rst <default_mitigations>`. diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 5b8286fdd91b..8001917ee012 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -17,14 +17,12 @@ etc. kernel-parameters devices -This section describes CPU vulnerabilities and provides an overview of the -possible mitigations along with guidance for selecting mitigations if they -are configurable at compile, boot or run time. +This section describes CPU vulnerabilities and their mitigations. .. toctree:: :maxdepth: 1 - l1tf + hw-vuln/index Here is a set of documents aimed at users who are trying to track down problems and bugs in particular. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index fd03e2b629bb..d1d1da911085 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1588,7 +1588,7 @@ Format: { "off" | "enforce" | "fix" | "log" } default: "enforce" - ima_appraise_tcb [IMA] + ima_appraise_tcb [IMA] Deprecated. Use ima_policy= instead. The builtin appraise policy appraises all files owned by uid=0. @@ -1615,8 +1615,7 @@ uid=0. The "appraise_tcb" policy appraises the integrity of - all files owned by root. (This is the equivalent - of ima_appraise_tcb.) + all files owned by root. The "secure_boot" policy appraises the integrity of files (eg. kexec kernel image, kernel modules, @@ -1831,6 +1830,9 @@ ip= [IP_PNP] See Documentation/filesystems/nfs/nfsroot.txt. + ipcmni_extend [KNL] Extend the maximum number of unique System V + IPC identifiers from 32,768 to 16,777,216. + irqaffinity= [SMP] Set the default irq affinity mask The argument is a cpu list, as described above. @@ -2144,7 +2146,7 @@ Default is 'flush'. - For details see: Documentation/admin-guide/l1tf.rst + For details see: Documentation/admin-guide/hw-vuln/l1tf.rst l2cr= [PPC] @@ -2390,6 +2392,32 @@ Format: <first>,<last> Specifies range of consoles to be captured by the MDA. + mds= [X86,INTEL] + Control mitigation for the Micro-architectural Data + Sampling (MDS) vulnerability. + + Certain CPUs are vulnerable to an exploit against CPU + internal buffers which can forward information to a + disclosure gadget under certain conditions. + + In vulnerable processors, the speculatively + forwarded data can be used in a cache side channel + attack, to access data to which the attacker does + not have direct access. + + This parameter controls the MDS mitigation. The + options are: + + full - Enable MDS mitigation on vulnerable CPUs + full,nosmt - Enable MDS mitigation and disable + SMT on vulnerable CPUs + off - Unconditionally disable MDS mitigation + + Not specifying this option is equivalent to + mds=full. + + For details see: Documentation/admin-guide/hw-vuln/mds.rst + mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory Amount of memory to be used when the kernel is not able to see the whole system memory or for test. @@ -2566,6 +2594,7 @@ spec_store_bypass_disable=off [X86,PPC] ssbd=force-off [ARM64] l1tf=off [X86] + mds=off [X86] auto (default) Mitigate all CPU vulnerabilities, but leave SMT @@ -2580,6 +2609,7 @@ if needed. This is for users who always want to be fully mitigated, even if it means losing SMT. Equivalent to: l1tf=flush,nosmt [X86] + mds=full,nosmt [X86] mminit_loglevel= [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this @@ -2876,11 +2906,11 @@ noexec=on: enable non-executable mappings (default) noexec=off: disable non-executable mappings - nosmap [X86] + nosmap [X86,PPC] Disable SMAP (Supervisor Mode Access Prevention) even if it is supported by processor. - nosmep [X86] + nosmep [X86,PPC] Disable SMEP (Supervisor Mode Execution Prevention) even if it is supported by processor. @@ -3147,6 +3177,16 @@ This will also cause panics on machine check exceptions. Useful together with panic=30 to trigger a reboot. + page_alloc.shuffle= + [KNL] Boolean flag to control whether the page allocator + should randomize its free lists. The randomization may + be automatically enabled if the kernel detects it is + running on a platform with a direct-mapped memory-side + cache, and this parameter can be used to + override/disable that behavior. The state of the flag + can be read from sysfs at: + /sys/module/page_alloc/parameters/shuffle. + page_owner= [KNL] Boot-time page_owner enabling option. Storage of the information about who allocated each page is disabled in default. With this switch, @@ -4027,7 +4067,9 @@ [[,]s[mp]#### \ [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ [[,]f[orce] - Where reboot_mode is one of warm (soft) or cold (hard) or gpio, + Where reboot_mode is one of warm (soft) or cold (hard) or gpio + (prefix with 'panic_' to set mode for panic + reboot only), reboot_type is one of bios, acpi, kbd, triple, efi, or pci, reboot_force is either force or not specified, reboot_cpu is s[mp]#### with #### being the processor diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst new file mode 100644 index 000000000000..b79f70c04397 --- /dev/null +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -0,0 +1,169 @@ +.. _numaperf: + +============= +NUMA Locality +============= + +Some platforms may have multiple types of memory attached to a compute +node. These disparate memory ranges may share some characteristics, such +as CPU cache coherence, but may have different performance. For example, +different media types and buses affect bandwidth and latency. + +A system supports such heterogeneous memory by grouping each memory type +under different domains, or "nodes", based on locality and performance +characteristics. Some memory may share the same node as a CPU, and others +are provided as memory only nodes. While memory only nodes do not provide +CPUs, they may still be local to one or more compute nodes relative to +other nodes. The following diagram shows one such example of two compute +nodes with local memory and a memory only node for each of compute node: + + +------------------+ +------------------+ + | Compute Node 0 +-----+ Compute Node 1 | + | Local Node0 Mem | | Local Node1 Mem | + +--------+---------+ +--------+---------+ + | | + +--------+---------+ +--------+---------+ + | Slower Node2 Mem | | Slower Node3 Mem | + +------------------+ +--------+---------+ + +A "memory initiator" is a node containing one or more devices such as +CPUs or separate memory I/O devices that can initiate memory requests. +A "memory target" is a node containing one or more physical address +ranges accessible from one or more memory initiators. + +When multiple memory initiators exist, they may not all have the same +performance when accessing a given memory target. Each initiator-target +pair may be organized into different ranked access classes to represent +this relationship. The highest performing initiator to a given target +is considered to be one of that target's local initiators, and given +the highest access class, 0. Any given target may have one or more +local initiators, and any given initiator may have multiple local +memory targets. + +To aid applications matching memory targets with their initiators, the +kernel provides symlinks to each other. The following example lists the +relationship for the access class "0" memory initiators and targets:: + + # symlinks -v /sys/devices/system/node/nodeX/access0/targets/ + relative: /sys/devices/system/node/nodeX/access0/targets/nodeY -> ../../nodeY + + # symlinks -v /sys/devices/system/node/nodeY/access0/initiators/ + relative: /sys/devices/system/node/nodeY/access0/initiators/nodeX -> ../../nodeX + +A memory initiator may have multiple memory targets in the same access +class. The target memory's initiators in a given class indicate the +nodes' access characteristics share the same performance relative to other +linked initiator nodes. Each target within an initiator's access class, +though, do not necessarily perform the same as each other. + +================ +NUMA Performance +================ + +Applications may wish to consider which node they want their memory to +be allocated from based on the node's performance characteristics. If +the system provides these attributes, the kernel exports them under the +node sysfs hierarchy by appending the attributes directory under the +memory node's access class 0 initiators as follows:: + + /sys/devices/system/node/nodeY/access0/initiators/ + +These attributes apply only when accessed from nodes that have the +are linked under the this access's inititiators. + +The performance characteristics the kernel provides for the local initiators +are exported are as follows:: + + # tree -P "read*|write*" /sys/devices/system/node/nodeY/access0/initiators/ + /sys/devices/system/node/nodeY/access0/initiators/ + |-- read_bandwidth + |-- read_latency + |-- write_bandwidth + `-- write_latency + +The bandwidth attributes are provided in MiB/second. + +The latency attributes are provided in nanoseconds. + +The values reported here correspond to the rated latency and bandwidth +for the platform. + +========== +NUMA Cache +========== + +System memory may be constructed in a hierarchy of elements with various +performance characteristics in order to provide large address space of +slower performing memory cached by a smaller higher performing memory. The +system physical addresses memory initiators are aware of are provided +by the last memory level in the hierarchy. The system meanwhile uses +higher performing memory to transparently cache access to progressively +slower levels. + +The term "far memory" is used to denote the last level memory in the +hierarchy. Each increasing cache level provides higher performing +initiator access, and the term "near memory" represents the fastest +cache provided by the system. + +This numbering is different than CPU caches where the cache level (ex: +L1, L2, L3) uses the CPU-side view where each increased level is lower +performing. In contrast, the memory cache level is centric to the last +level memory, so the higher numbered cache level corresponds to memory +nearer to the CPU, and further from far memory. + +The memory-side caches are not directly addressable by software. When +software accesses a system address, the system will return it from the +near memory cache if it is present. If it is not present, the system +accesses the next level of memory until there is either a hit in that +cache level, or it reaches far memory. + +An application does not need to know about caching attributes in order +to use the system. Software may optionally query the memory cache +attributes in order to maximize the performance out of such a setup. +If the system provides a way for the kernel to discover this information, +for example with ACPI HMAT (Heterogeneous Memory Attribute Table), +the kernel will append these attributes to the NUMA node memory target. + +When the kernel first registers a memory cache with a node, the kernel +will create the following directory:: + + /sys/devices/system/node/nodeX/memory_side_cache/ + +If that directory is not present, the system either does not not provide +a memory-side cache, or that information is not accessible to the kernel. + +The attributes for each level of cache is provided under its cache +level index:: + + /sys/devices/system/node/nodeX/memory_side_cache/indexA/ + /sys/devices/system/node/nodeX/memory_side_cache/indexB/ + /sys/devices/system/node/nodeX/memory_side_cache/indexC/ + +Each cache level's directory provides its attributes. For example, the +following shows a single cache level and the attributes available for +software to query:: + + # tree sys/devices/system/node/node0/memory_side_cache/ + /sys/devices/system/node/node0/memory_side_cache/ + |-- index1 + | |-- indexing + | |-- line_size + | |-- size + | `-- write_policy + +The "indexing" will be 0 if it is a direct-mapped cache, and non-zero +for any other indexed based, multi-way associativity. + +The "line_size" is the number of bytes accessed from the next cache +level on a miss. + +The "size" is the number of bytes provided by this cache level. + +The "write_policy" will be 0 for write-back, and non-zero for +write-through caching. + +======== +See Also +======== +.. [1] https://www.uefi.org/sites/default/files/resources/ACPI_6_2.pdf + Section 5.2.27 diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst index 7eca9026a9ed..0c74a7784964 100644 --- a/Documentation/admin-guide/pm/cpufreq.rst +++ b/Documentation/admin-guide/pm/cpufreq.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + .. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>` .. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>` @@ -5,9 +8,10 @@ CPU Performance Scaling ======================= -:: +:Copyright: |copy| 2017 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> The Concept of CPU Performance Scaling ====================================== @@ -396,8 +400,8 @@ 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 +given CPU as the CPU utilization estimate (see the *Per-entity load tracking* +LWN.net article [1]_ 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`` @@ -698,4 +702,8 @@ 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/ +References +========== + +.. [1] Jonathan Corbet, *Per-entity load tracking*, + https://lwn.net/Articles/531853/ diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index 9c58b35a81cb..e70b365dbc60 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + .. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>` .. |cpufreq| replace:: :doc:`CPU Performance Scaling <cpufreq>` @@ -5,9 +8,10 @@ CPU Idle Time Management ======================== -:: +:Copyright: |copy| 2018 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> - Copyright (c) 2018 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> Concepts ======== diff --git a/Documentation/admin-guide/pm/index.rst b/Documentation/admin-guide/pm/index.rst index 49237ac73442..39f8f9f81e7a 100644 --- a/Documentation/admin-guide/pm/index.rst +++ b/Documentation/admin-guide/pm/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================ Power Management ================ diff --git a/Documentation/admin-guide/pm/intel_epb.rst b/Documentation/admin-guide/pm/intel_epb.rst new file mode 100644 index 000000000000..005121167af7 --- /dev/null +++ b/Documentation/admin-guide/pm/intel_epb.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +====================================== +Intel Performance and Energy Bias Hint +====================================== + +:Copyright: |copy| 2019 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> + + +.. kernel-doc:: arch/x86/kernel/cpu/intel_epb.c + :doc: overview + +Intel Performance and Energy Bias Attribute in ``sysfs`` +======================================================== + +The Intel Performance and Energy Bias Hint (EPB) value for a given (logical) CPU +can be checked or updated through a ``sysfs`` attribute (file) under +:file:`/sys/devices/system/cpu/cpu<N>/power/`, where the CPU number ``<N>`` +is allocated at the system initialization time: + +``energy_perf_bias`` + Shows the current EPB value for the CPU in a sliding scale 0 - 15, where + a value of 0 corresponds to a hint preference for highest performance + and a value of 15 corresponds to the maximum energy savings. + + In order to update the EPB value for the CPU, this attribute can be + written to, either with a number in the 0 - 15 sliding scale above, or + with one of the strings: "performance", "balance-performance", "normal", + "balance-power", "power" that represent values reflected by their + meaning. + + This attribute is present for all online CPUs supporting the EPB + feature. + +Note that while the EPB interface to the processor is defined at the logical CPU +level, the physical register backing it may be shared by multiple CPUs (for +example, SMT siblings or cores in one package). For this reason, updating the +EPB value for one CPU may cause the EPB values for other CPUs to change. diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst index ec0f7c111f65..67e414e34f37 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -1,10 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + =============================================== ``intel_pstate`` CPU Performance Scaling Driver =============================================== -:: +:Copyright: |copy| 2017 Intel Corporation - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> General Information @@ -20,11 +23,10 @@ you have not done that yet.] For the processors supported by ``intel_pstate``, the P-state concept is broader than just an operating frequency or an operating performance point (see the -`LinuxCon Europe 2015 presentation by Kristen Accardi <LCEU2015_>`_ for more +LinuxCon Europe 2015 presentation by Kristen Accardi [1]_ for more information about that). For this reason, the representation of P-states used by ``intel_pstate`` internally follows the hardware specification (for details -refer to `Intel® 64 and IA-32 Architectures Software Developer’s Manual -Volume 3: System Programming Guide <SDM_>`_). However, the ``CPUFreq`` core +refer to Intel Software Developer’s Manual [2]_). However, the ``CPUFreq`` core uses frequencies for identifying operating performance points of CPUs and frequencies are involved in the user space interface exposed by it, so ``intel_pstate`` maps its internal representation of P-states to frequencies too @@ -561,9 +563,9 @@ or to pin every task potentially sensitive to them to a specific CPU.] On the majority of systems supported by ``intel_pstate``, the ACPI tables provided by the platform firmware contain ``_PSS`` objects returning information -that can be used for CPU performance scaling (refer to the `ACPI specification`_ -for details on the ``_PSS`` objects and the format of the information returned -by them). +that can be used for CPU performance scaling (refer to the ACPI specification +[3]_ for details on the ``_PSS`` objects and the format of the information +returned by them). The information returned by the ACPI ``_PSS`` objects is used by the ``acpi-cpufreq`` scaling driver. On systems supported by ``intel_pstate`` @@ -728,6 +730,14 @@ P-state is called, the ``ftrace`` filter can be set to to <idle>-0 [000] ..s. 2537.654843: intel_pstate_set_pstate <-intel_pstate_timer_func -.. _LCEU2015: http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf -.. _SDM: http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html -.. _ACPI specification: http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf +References +========== + +.. [1] Kristen Accardi, *Balancing Power and Performance in the Linux Kernel*, + http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf + +.. [2] *Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 3: System Programming Guide*, + http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html + +.. [3] *Advanced Configuration and Power Interface Specification*, + https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf diff --git a/Documentation/admin-guide/pm/sleep-states.rst b/Documentation/admin-guide/pm/sleep-states.rst index dbf5acd49f35..cd3a28cb81f4 100644 --- a/Documentation/admin-guide/pm/sleep-states.rst +++ b/Documentation/admin-guide/pm/sleep-states.rst @@ -1,10 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + =================== System Sleep States =================== -:: +:Copyright: |copy| 2017 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> Sleep states are global low-power states of the entire system in which user space code cannot be executed and the overall system activity is significantly diff --git a/Documentation/admin-guide/pm/strategies.rst b/Documentation/admin-guide/pm/strategies.rst index afe4d3f831fe..dd0362e32fa5 100644 --- a/Documentation/admin-guide/pm/strategies.rst +++ b/Documentation/admin-guide/pm/strategies.rst @@ -1,10 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + =========================== Power Management Strategies =========================== -:: +:Copyright: |copy| 2017 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> The Linux kernel supports two major high-level power management strategies. diff --git a/Documentation/admin-guide/pm/system-wide.rst b/Documentation/admin-guide/pm/system-wide.rst index 0c81e4c5de39..2b1f987b34f0 100644 --- a/Documentation/admin-guide/pm/system-wide.rst +++ b/Documentation/admin-guide/pm/system-wide.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ============================ System-Wide Power Management ============================ diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst index b6cef9b5e961..fc298eb1234b 100644 --- a/Documentation/admin-guide/pm/working-state.rst +++ b/Documentation/admin-guide/pm/working-state.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ============================== Working-State Power Management ============================== @@ -8,3 +10,4 @@ Working-State Power Management cpuidle cpufreq intel_pstate + intel_epb diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.txt index be70b32c95d9..093cdaefdb37 100644 --- a/Documentation/atomic_bitops.txt +++ b/Documentation/atomic_bitops.txt @@ -1,6 +1,6 @@ - -On atomic bitops. - +============= +Atomic bitops +============= While our bitmap_{}() functions are non-atomic, we have a number of operations operating on single bits in a bitmap that are atomic. diff --git a/Documentation/block/bfq-iosched.txt b/Documentation/block/bfq-iosched.txt index 98a8dd5ee385..1a0f2ac02eb6 100644 --- a/Documentation/block/bfq-iosched.txt +++ b/Documentation/block/bfq-iosched.txt @@ -20,13 +20,26 @@ for that device, by setting low_latency to 0. See Section 3 for details on how to configure BFQ for the desired tradeoff between latency and throughput, or on how to maximize throughput. -BFQ has a non-null overhead, which limits the maximum IOPS that a CPU -can process for a device scheduled with BFQ. To give an idea of the -limits on slow or average CPUs, here are, first, the limits of BFQ for -three different CPUs, on, respectively, an average laptop, an old -desktop, and a cheap embedded system, in case full hierarchical -support is enabled (i.e., CONFIG_BFQ_GROUP_IOSCHED is set), but -CONFIG_DEBUG_BLK_CGROUP is not set (Section 4-2): +As every I/O scheduler, BFQ adds some overhead to per-I/O-request +processing. To give an idea of this overhead, the total, +single-lock-protected, per-request processing time of BFQ---i.e., the +sum of the execution times of the request insertion, dispatch and +completion hooks---is, e.g., 1.9 us on an Intel Core i7-2760QM@2.40GHz +(dated CPU for notebooks; time measured with simple code +instrumentation, and using the throughput-sync.sh script of the S +suite [1], in performance-profiling mode). To put this result into +context, the total, single-lock-protected, per-request execution time +of the lightest I/O scheduler available in blk-mq, mq-deadline, is 0.7 +us (mq-deadline is ~800 LOC, against ~10500 LOC for BFQ). + +Scheduling overhead further limits the maximum IOPS that a CPU can +process (already limited by the execution of the rest of the I/O +stack). To give an idea of the limits with BFQ, on slow or average +CPUs, here are, first, the limits of BFQ for three different CPUs, on, +respectively, an average laptop, an old desktop, and a cheap embedded +system, in case full hierarchical support is enabled (i.e., +CONFIG_BFQ_GROUP_IOSCHED is set), but CONFIG_DEBUG_BLK_CGROUP is not +set (Section 4-2): - Intel i7-4850HQ: 400 KIOPS - AMD A8-3850: 250 KIOPS - ARM CortexTM-A53 Octa-core: 80 KIOPS @@ -566,3 +579,5 @@ applications. Unset this tunable if you need/want to control weights. Slightly extended version: http://algogroup.unimore.it/people/paolo/disk_sched/bfq-v1-suite- results.pdf + +[3] https://github.com/Algodev-github/S diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.txt index 4cad1024fff7..41f0a3d33bbd 100644 --- a/Documentation/block/null_blk.txt +++ b/Documentation/block/null_blk.txt @@ -93,3 +93,7 @@ zoned=[0/1]: Default: 0 zone_size=[MB]: Default: 256 Per zone size when exposed as a zoned block device. Must be a power of two. + +zone_nr_conv=[nr_conv]: Default: 0 + The number of conventional zones to create when block device is zoned. If + zone_nr_conv >= nr_zones, it will be reduced to nr_zones - 1. diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index 10453c627135..cb402c59eca5 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -85,8 +85,33 @@ Q: Can loops be supported in a safe way? A: It's not clear yet. BPF developers are trying to find a way to -support bounded loops where the verifier can guarantee that -the program terminates in less than 4096 instructions. +support bounded loops. + +Q: What are the verifier limits? +-------------------------------- +A: The only limit known to the user space is BPF_MAXINSNS (4096). +It's the maximum number of instructions that the unprivileged bpf +program can have. The verifier has various internal limits. +Like the maximum number of instructions that can be explored during +program analysis. Currently, that limit is set to 1 million. +Which essentially means that the largest program can consist +of 1 million NOP instructions. There is a limit to the maximum number +of subsequent branches, a limit to the number of nested bpf-to-bpf +calls, a limit to the number of the verifier states per instruction, +a limit to the number of maps used by the program. +All these limits can be hit with a sufficiently complex program. +There are also non-numerical limits that can cause the program +to be rejected. The verifier used to recognize only pointer + constant +expressions. Now it can recognize pointer + bounded_register. +bpf_lookup_map_elem(key) had a requirement that 'key' must be +a pointer to the stack. Now, 'key' can be a pointer to map value. +The verifier is steadily getting 'smarter'. The limits are +being removed. The only way to know that the program is going to +be accepted by the verifier is to try to load it. +The bpf development process guarantees that the future kernel +versions will accept all bpf programs that were accepted by +the earlier versions. + Instruction level questions --------------------------- diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst index 7313d354f20e..8820360d00da 100644 --- a/Documentation/bpf/btf.rst +++ b/Documentation/bpf/btf.rst @@ -82,6 +82,8 @@ sequentially and type id is assigned to each recognized type starting from id #define BTF_KIND_RESTRICT 11 /* Restrict */ #define BTF_KIND_FUNC 12 /* Function */ #define BTF_KIND_FUNC_PROTO 13 /* Function Proto */ + #define BTF_KIND_VAR 14 /* Variable */ + #define BTF_KIND_DATASEC 15 /* Section */ Note that the type section encodes debug info, not just pure types. ``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram. @@ -393,6 +395,61 @@ refers to parameter type. If the function has variable arguments, the last parameter is encoded with ``name_off = 0`` and ``type = 0``. +2.2.14 BTF_KIND_VAR +~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: offset to a valid C identifier + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_VAR + * ``info.vlen``: 0 + * ``type``: the type of the variable + +``btf_type`` is followed by a single ``struct btf_variable`` with the +following data:: + + struct btf_var { + __u32 linkage; + }; + +``struct btf_var`` encoding: + * ``linkage``: currently only static variable 0, or globally allocated + variable in ELF sections 1 + +Not all type of global variables are supported by LLVM at this point. +The following is currently available: + + * static variables with or without section attributes + * global variables with section attributes + +The latter is for future extraction of map key/value type id's from a +map definition. + +2.2.15 BTF_KIND_DATASEC +~~~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: offset to a valid name associated with a variable or + one of .data/.bss/.rodata + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_DATASEC + * ``info.vlen``: # of variables + * ``size``: total section size in bytes (0 at compilation time, patched + to actual size by BPF loaders such as libbpf) + +``btf_type`` is followed by ``info.vlen`` number of ``struct btf_var_secinfo``.:: + + struct btf_var_secinfo { + __u32 type; + __u32 offset; + __u32 size; + }; + +``struct btf_var_secinfo`` encoding: + * ``type``: the type of the BTF_KIND_VAR variable + * ``offset``: the in-section offset of the variable + * ``size``: the size of the variable in bytes + 3. BTF Kernel API ***************** @@ -521,6 +578,7 @@ For line_info, the line number and column number are defined as below: #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff) 3.4 BPF_{PROG,MAP}_GET_NEXT_ID +============================== In kernel, every loaded program, map or btf has a unique id. The id won't change during the lifetime of a program, map, or btf. @@ -530,6 +588,7 @@ each command, to user space, for bpf program or maps, respectively, so an inspection tool can inspect all programs and maps. 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID +=============================== An introspection tool cannot use id to get details about program or maps. A file descriptor needs to be obtained first for reference-counting purpose. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 4e77932959cc..d3fe4cac0c90 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -36,6 +36,16 @@ Two sets of Questions and Answers (Q&A) are maintained. bpf_devel_QA +Program types +============= + +.. toctree:: + :maxdepth: 1 + + prog_cgroup_sysctl + prog_flow_dissector + + .. Links: .. _Documentation/networking/filter.txt: ../networking/filter.txt .. _man-pages: https://www.kernel.org/doc/man-pages/ diff --git a/Documentation/bpf/prog_cgroup_sysctl.rst b/Documentation/bpf/prog_cgroup_sysctl.rst new file mode 100644 index 000000000000..677d6c637cf3 --- /dev/null +++ b/Documentation/bpf/prog_cgroup_sysctl.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +=========================== +BPF_PROG_TYPE_CGROUP_SYSCTL +=========================== + +This document describes ``BPF_PROG_TYPE_CGROUP_SYSCTL`` program type that +provides cgroup-bpf hook for sysctl. + +The hook has to be attached to a cgroup and will be called every time a +process inside that cgroup tries to read from or write to sysctl knob in proc. + +1. Attach type +************** + +``BPF_CGROUP_SYSCTL`` attach type has to be used to attach +``BPF_PROG_TYPE_CGROUP_SYSCTL`` program to a cgroup. + +2. Context +********** + +``BPF_PROG_TYPE_CGROUP_SYSCTL`` provides access to the following context from +BPF program:: + + struct bpf_sysctl { + __u32 write; + __u32 file_pos; + }; + +* ``write`` indicates whether sysctl value is being read (``0``) or written + (``1``). This field is read-only. + +* ``file_pos`` indicates file position sysctl is being accessed at, read + or written. This field is read-write. Writing to the field sets the starting + position in sysctl proc file ``read(2)`` will be reading from or ``write(2)`` + will be writing to. Writing zero to the field can be used e.g. to override + whole sysctl value by ``bpf_sysctl_set_new_value()`` on ``write(2)`` even + when it's called by user space on ``file_pos > 0``. Writing non-zero + value to the field can be used to access part of sysctl value starting from + specified ``file_pos``. Not all sysctl support access with ``file_pos != + 0``, e.g. writes to numeric sysctl entries must always be at file position + ``0``. See also ``kernel.sysctl_writes_strict`` sysctl. + +See `linux/bpf.h`_ for more details on how context field can be accessed. + +3. Return code +************** + +``BPF_PROG_TYPE_CGROUP_SYSCTL`` program must return one of the following +return codes: + +* ``0`` means "reject access to sysctl"; +* ``1`` means "proceed with access". + +If program returns ``0`` user space will get ``-1`` from ``read(2)`` or +``write(2)`` and ``errno`` will be set to ``EPERM``. + +4. Helpers +********** + +Since sysctl knob is represented by a name and a value, sysctl specific BPF +helpers focus on providing access to these properties: + +* ``bpf_sysctl_get_name()`` to get sysctl name as it is visible in + ``/proc/sys`` into provided by BPF program buffer; + +* ``bpf_sysctl_get_current_value()`` to get string value currently held by + sysctl into provided by BPF program buffer. This helper is available on both + ``read(2)`` from and ``write(2)`` to sysctl; + +* ``bpf_sysctl_get_new_value()`` to get new string value currently being + written to sysctl before actual write happens. This helper can be used only + on ``ctx->write == 1``; + +* ``bpf_sysctl_set_new_value()`` to override new string value currently being + written to sysctl before actual write happens. Sysctl value will be + overridden starting from the current ``ctx->file_pos``. If the whole value + has to be overridden BPF program can set ``file_pos`` to zero before calling + to the helper. This helper can be used only on ``ctx->write == 1``. New + string value set by the helper is treated and verified by kernel same way as + an equivalent string passed by user space. + +BPF program sees sysctl value same way as user space does in proc filesystem, +i.e. as a string. Since many sysctl values represent an integer or a vector +of integers, the following helpers can be used to get numeric value from the +string: + +* ``bpf_strtol()`` to convert initial part of the string to long integer + similar to user space `strtol(3)`_; +* ``bpf_strtoul()`` to convert initial part of the string to unsigned long + integer similar to user space `strtoul(3)`_; + +See `linux/bpf.h`_ for more details on helpers described here. + +5. Examples +*********** + +See `test_sysctl_prog.c`_ for an example of BPF program in C that access +sysctl name and value, parses string value to get vector of integers and uses +the result to make decision whether to allow or deny access to sysctl. + +6. Notes +******** + +``BPF_PROG_TYPE_CGROUP_SYSCTL`` is intended to be used in **trusted** root +environment, for example to monitor sysctl usage or catch unreasonable values +an application, running as root in a separate cgroup, is trying to set. + +Since `task_dfl_cgroup(current)` is called at `sys_read` / `sys_write` time it +may return results different from that at `sys_open` time, i.e. process that +opened sysctl file in proc filesystem may differ from process that is trying +to read from / write to it and two such processes may run in different +cgroups, what means ``BPF_PROG_TYPE_CGROUP_SYSCTL`` should not be used as a +security mechanism to limit sysctl usage. + +As with any cgroup-bpf program additional care should be taken if an +application running as root in a cgroup should not be allowed to +detach/replace BPF program attached by administrator. + +.. Links +.. _linux/bpf.h: ../../include/uapi/linux/bpf.h +.. _strtol(3): http://man7.org/linux/man-pages/man3/strtol.3p.html +.. _strtoul(3): http://man7.org/linux/man-pages/man3/strtoul.3p.html +.. _test_sysctl_prog.c: + ../../tools/testing/selftests/bpf/progs/test_sysctl_prog.c diff --git a/Documentation/networking/bpf_flow_dissector.rst b/Documentation/bpf/prog_flow_dissector.rst index b375ae2ec2c4..ed343abe541e 100644 --- a/Documentation/networking/bpf_flow_dissector.rst +++ b/Documentation/bpf/prog_flow_dissector.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -================== -BPF Flow Dissector -================== +============================ +BPF_PROG_TYPE_FLOW_DISSECTOR +============================ Overview ======== diff --git a/Documentation/clearing-warn-once.txt b/Documentation/clearing-warn-once.txt index 5b1f5d547be1..211fd926cf00 100644 --- a/Documentation/clearing-warn-once.txt +++ b/Documentation/clearing-warn-once.txt @@ -1,5 +1,7 @@ +Clearing WARN_ONCE +------------------ -WARN_ONCE / WARN_ON_ONCE only print a warning once. +WARN_ONCE / WARN_ON_ONCE / printk_once only emit a message once. echo 1 > /sys/kernel/debug/clear_warn_once diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 6870baffef82..ee1bb8983a88 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -22,7 +22,6 @@ Core utilities workqueue genericirq xarray - flexible-arrays librs genalloc errseq diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 71f5d2fe39b7..a29c99d13331 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -147,10 +147,10 @@ Division Functions .. kernel-doc:: include/linux/math64.h :internal: -.. kernel-doc:: lib/div64.c +.. kernel-doc:: lib/math/div64.c :functions: div_s64_rem div64_u64_rem div64_u64 div64_s64 -.. kernel-doc:: lib/gcd.c +.. kernel-doc:: lib/math/gcd.c :export: UUID/GUID diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index c37ec7cd9c06..75d2bbe9813f 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -58,6 +58,14 @@ A raw pointer value may be printed with %p which will hash the address before printing. The kernel also supports extended specifiers for printing pointers of different types. +Some of the extended specifiers print the data on the given address instead +of printing the address itself. In this case, the following error messages +might be printed instead of the unreachable information:: + + (null) data on plain NULL address + (efault) data on invalid address + (einval) invalid data on a valid address + Plain Pointers -------------- diff --git a/Documentation/crypto/api-samples.rst b/Documentation/crypto/api-samples.rst index 0f6ca8b7261e..f14afaaf2f32 100644 --- a/Documentation/crypto/api-samples.rst +++ b/Documentation/crypto/api-samples.rst @@ -133,7 +133,6 @@ Code Example For Use of Operational State Memory With SHASH if (!sdesc) return ERR_PTR(-ENOMEM); sdesc->shash.tfm = alg; - sdesc->shash.flags = 0x0; return sdesc; } diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst index 69a7d90c320a..46aae52a41d0 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -34,10 +34,6 @@ Configure the kernel with:: CONFIG_DEBUG_FS=y CONFIG_GCOV_KERNEL=y -select the gcc's gcov format, default is autodetect based on gcc version:: - - CONFIG_GCOV_FORMAT_AUTODETECT=y - and to get coverage data for the entire kernel:: CONFIG_GCOV_PROFILE_ALL=y @@ -169,6 +165,20 @@ b) gcov is run on the BUILD machine [user@build] gcov -o /tmp/coverage/tmp/out/init main.c +Note on compilers +----------------- + +GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with +GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang. + +.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html + +Build differences between GCC and Clang gcov are handled by Kconfig. It +automatically selects the appropriate gcov format depending on the detected +toolchain. + + Troubleshooting --------------- diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 7756f7a7c23b..25604904fa6e 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -7,6 +7,11 @@ directory. These are intended to be small tests to exercise individual code paths in the kernel. Tests are intended to be run after building, installing and booting a kernel. +You can find additional information on Kselftest framework, how to +write new tests using the framework on Kselftest wiki: + +https://kselftest.wiki.kernel.org/ + On some systems, hot-plug tests could hang forever waiting for cpu and memory to be ready to be offlined. A special hot-plug target is created to run the full range of hot-plug tests. In default mode, hot-plug tests run @@ -14,6 +19,10 @@ in safe mode with a limited scope. In limited mode, cpu-hotplug test is run on a single cpu as opposed to all hotplug capable cpus, and memory hotplug test is run on 2% of hotplug capable memory instead of 10%. +kselftest runs as a userspace process. Tests that can be written/run in +userspace may wish to use the `Test Harness`_. Tests that need to be +run in kernel space may wish to use a `Test Module`_. + Running the selftests (hotplug tests are run in limited mode) ============================================================= @@ -31,17 +40,32 @@ To build and run the tests with a single command, use:: Note that some tests will require root privileges. -Build and run from user specific object directory (make O=dir):: +Kselftest supports saving output files in a separate directory and then +running tests. To locate output files in a separate directory two syntaxes +are supported. In both cases the working directory must be the root of the +kernel src. This is applicable to "Running a subset of selftests" section +below. + +To build, save output files in a separate directory with O= :: $ make O=/tmp/kselftest kselftest -Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=):: +To build, save output files in a separate directory with KBUILD_OUTPUT :: + + $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest - $ make KBUILD_OUTPUT=/tmp/kselftest kselftest +The O= assignment takes precedence over the KBUILD_OUTPUT environment +variable. -The above commands run the tests and print pass/fail summary to make it -easier to understand the test results. Please find the detailed individual -test results for each test in /tmp/testname file(s). +The above commands by default run the tests and print full pass/fail report. +Kselftest supports "summary" option to make it easier to understand the test +results. Please find the detailed individual test results for each test in +/tmp/testname file(s) when summary option is specified. This is applicable +to "Running a subset of selftests" section below. + +To run kselftest with summary option enabled :: + + $ make summary=1 kselftest Running a subset of selftests ============================= @@ -57,17 +81,13 @@ You can specify multiple tests to build and run:: $ make TARGETS="size timers" kselftest -Build and run from user specific object directory (make O=dir):: +To build, save output files in a separate directory with O= :: $ make O=/tmp/kselftest TARGETS="size timers" kselftest -Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=):: +To build, save output files in a separate directory with KBUILD_OUTPUT :: - $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest - -The above commands run the tests and print pass/fail summary to make it -easier to understand the test results. Please find the detailed individual -test results for each test in /tmp/testname file(s). + $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest See the top-level tools/testing/selftests/Makefile for the list of all possible targets. @@ -161,11 +181,97 @@ Contributing new tests (details) e.g: tools/testing/selftests/android/config +Test Module +=========== + +Kselftest tests the kernel from userspace. Sometimes things need +testing from within the kernel, one method of doing this is to create a +test module. We can tie the module into the kselftest framework by +using a shell script test runner. ``kselftest_module.sh`` is designed +to facilitate this process. There is also a header file provided to +assist writing kernel modules that are for use with kselftest: + +- ``tools/testing/kselftest/kselftest_module.h`` +- ``tools/testing/kselftest/kselftest_module.sh`` + +How to use +---------- + +Here we show the typical steps to create a test module and tie it into +kselftest. We use kselftests for lib/ as an example. + +1. Create the test module + +2. Create the test script that will run (load/unload) the module + e.g. ``tools/testing/selftests/lib/printf.sh`` + +3. Add line to config file e.g. ``tools/testing/selftests/lib/config`` + +4. Add test script to makefile e.g. ``tools/testing/selftests/lib/Makefile`` + +5. Verify it works: + +.. code-block:: sh + + # Assumes you have booted a fresh build of this kernel tree + cd /path/to/linux/tree + make kselftest-merge + make modules + sudo make modules_install + make TARGETS=lib kselftest + +Example Module +-------------- + +A bare bones test module might look like this: + +.. code-block:: c + + // SPDX-License-Identifier: GPL-2.0+ + + #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt + + #include "../tools/testing/selftests/kselftest_module.h" + + KSTM_MODULE_GLOBALS(); + + /* + * Kernel module for testing the foobinator + */ + + static int __init test_function() + { + ... + } + + static void __init selftest(void) + { + KSTM_CHECK_ZERO(do_test_case("", 0)); + } + + KSTM_MODULE_LOADERS(test_foo); + MODULE_AUTHOR("John Developer <jd@fooman.org>"); + MODULE_LICENSE("GPL"); + +Example test script +------------------- + +.. code-block:: sh + + #!/bin/bash + # SPDX-License-Identifier: GPL-2.0+ + $(dirname $0)/../kselftest_module.sh "foo" test_foo + + Test Harness ============ -The kselftest_harness.h file contains useful helpers to build tests. The tests -from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example. +The kselftest_harness.h file contains useful helpers to build tests. The +test harness is for userspace testing, for kernel space testing see `Test +Module`_ above. + +The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as +example. Example ------- diff --git a/Documentation/devicetree/bindings/arm/altera/socfpga-system.txt b/Documentation/devicetree/bindings/arm/altera/socfpga-system.txt index f4d04a067282..82edbaaa3f85 100644 --- a/Documentation/devicetree/bindings/arm/altera/socfpga-system.txt +++ b/Documentation/devicetree/bindings/arm/altera/socfpga-system.txt @@ -11,3 +11,15 @@ Example: reg = <0xffd08000 0x1000>; cpu1-start-addr = <0xffd080c4>; }; + +ARM64 - Stratix10 +Required properties: +- compatible : "altr,sys-mgr-s10" +- reg : Should contain 1 register range(address and length) + for system manager register. + +Example: + sysmgr@ffd12000 { + compatible = "altr,sys-mgr-s10"; + reg = <0xffd12000 0x228>; + }; diff --git a/Documentation/devicetree/bindings/arm/coresight.txt b/Documentation/devicetree/bindings/arm/coresight.txt index f8aff65ab921..8a88ddebc1a2 100644 --- a/Documentation/devicetree/bindings/arm/coresight.txt +++ b/Documentation/devicetree/bindings/arm/coresight.txt @@ -8,7 +8,8 @@ through the intermediate links connecting the source to the currently selected sink. Each CoreSight component device should use these properties to describe its hardware characteristcs. -* Required properties for all components *except* non-configurable replicators: +* Required properties for all components *except* non-configurable replicators + and non-configurable funnels: * compatible: These have to be supplemented with "arm,primecell" as drivers are using the AMBA bus interface. Possible values include: @@ -24,8 +25,10 @@ its hardware characteristcs. discovered at boot time when the device is probed. "arm,coresight-tmc", "arm,primecell"; - - Trace Funnel: - "arm,coresight-funnel", "arm,primecell"; + - Trace Programmable Funnel: + "arm,coresight-dynamic-funnel", "arm,primecell"; + "arm,coresight-funnel", "arm,primecell"; (OBSOLETE. For + backward compatibility and will be removed) - Embedded Trace Macrocell (version 3.x) and Program Flow Trace Macrocell: @@ -65,11 +68,17 @@ its hardware characteristcs. "stm-stimulus-base", each corresponding to the areas defined in "reg". * Required properties for devices that don't show up on the AMBA bus, such as - non-configurable replicators: + non-configurable replicators and non-configurable funnels: * compatible: Currently supported value is (note the absence of the AMBA markee): - - "arm,coresight-replicator" + - Coresight Non-configurable Replicator: + "arm,coresight-static-replicator"; + "arm,coresight-replicator"; (OBSOLETE. For backward + compatibility and will be removed) + + - Coresight Non-configurable Funnel: + "arm,coresight-static-funnel"; * port or ports: see "Graph bindings for Coresight" below. @@ -169,7 +178,7 @@ Example: /* non-configurable replicators don't show up on the * AMBA bus. As such no need to add "arm,primecell". */ - compatible = "arm,coresight-replicator"; + compatible = "arm,coresight-static-replicator"; out-ports { #address-cells = <1>; @@ -200,8 +209,45 @@ Example: }; }; + funnel { + /* + * non-configurable funnel don't show up on the AMBA + * bus. As such no need to add "arm,primecell". + */ + compatible = "arm,coresight-static-funnel"; + clocks = <&crg_ctrl HI3660_PCLK>; + clock-names = "apb_pclk"; + + out-ports { + port { + combo_funnel_out: endpoint { + remote-endpoint = <&top_funnel_in>; + }; + }; + }; + + in-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + combo_funnel_in0: endpoint { + remote-endpoint = <&cluster0_etf_out>; + }; + }; + + port@1 { + reg = <1>; + combo_funnel_in1: endpoint { + remote-endpoint = <&cluster1_etf_out>; + }; + }; + }; + }; + funnel@20040000 { - compatible = "arm,coresight-funnel", "arm,primecell"; + compatible = "arm,coresight-dynamic-funnel", "arm,primecell"; reg = <0 0x20040000 0 0x1000>; clocks = <&oscclk6a>; diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 82dd7582e945..591bbd012d63 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -67,6 +67,7 @@ properties: patternProperties: '^cpu@[0-9a-f]+$': + type: object properties: device_type: const: cpu diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt index de4075413d91..161e63a6c254 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt @@ -14,6 +14,8 @@ Required Properties: - "mediatek,mt7629-apmixedsys" - "mediatek,mt8135-apmixedsys" - "mediatek,mt8173-apmixedsys" + - "mediatek,mt8183-apmixedsys", "syscon" + - "mediatek,mt8516-apmixedsys" - #clock-cells: Must be 1 The apmixedsys controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt index d1606b2c3e63..f3cef1a6d95c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt @@ -9,6 +9,7 @@ Required Properties: - "mediatek,mt2701-audsys", "syscon" - "mediatek,mt7622-audsys", "syscon" - "mediatek,mt7623-audsys", "mediatek,mt2701-audsys", "syscon" + - "mediatek,mt8183-audiosys", "syscon" - #clock-cells: Must be 1 The AUDSYS controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt new file mode 100644 index 000000000000..d8930f64aa98 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,camsys.txt @@ -0,0 +1,22 @@ +MediaTek CAMSYS controller +============================ + +The MediaTek camsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be one of: + - "mediatek,mt8183-camsys", "syscon" +- #clock-cells: Must be 1 + +The camsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +camsys: camsys@1a000000 { + compatible = "mediatek,mt8183-camsys", "syscon"; + reg = <0 0x1a000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt index 3f99672163e3..e3bc4a1e7a6e 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt @@ -11,6 +11,7 @@ Required Properties: - "mediatek,mt6797-imgsys", "syscon" - "mediatek,mt7623-imgsys", "mediatek,mt2701-imgsys", "syscon" - "mediatek,mt8173-imgsys", "syscon" + - "mediatek,mt8183-imgsys", "syscon" - #clock-cells: Must be 1 The imgsys controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt index 417bd83d1378..a90913988d7e 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt @@ -15,6 +15,8 @@ Required Properties: - "mediatek,mt7629-infracfg", "syscon" - "mediatek,mt8135-infracfg", "syscon" - "mediatek,mt8173-infracfg", "syscon" + - "mediatek,mt8183-infracfg", "syscon" + - "mediatek,mt8516-infracfg", "syscon" - #clock-cells: Must be 1 - #reset-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ipu.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ipu.txt new file mode 100644 index 000000000000..aabc8c5c8ed2 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ipu.txt @@ -0,0 +1,43 @@ +Mediatek IPU controller +============================ + +The Mediatek ipu controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be one of: + - "mediatek,mt8183-ipu_conn", "syscon" + - "mediatek,mt8183-ipu_adl", "syscon" + - "mediatek,mt8183-ipu_core0", "syscon" + - "mediatek,mt8183-ipu_core1", "syscon" +- #clock-cells: Must be 1 + +The ipu controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +ipu_conn: syscon@19000000 { + compatible = "mediatek,mt8183-ipu_conn", "syscon"; + reg = <0 0x19000000 0 0x1000>; + #clock-cells = <1>; +}; + +ipu_adl: syscon@19010000 { + compatible = "mediatek,mt8183-ipu_adl", "syscon"; + reg = <0 0x19010000 0 0x1000>; + #clock-cells = <1>; +}; + +ipu_core0: syscon@19180000 { + compatible = "mediatek,mt8183-ipu_core0", "syscon"; + reg = <0 0x19180000 0 0x1000>; + #clock-cells = <1>; +}; + +ipu_core1: syscon@19280000 { + compatible = "mediatek,mt8183-ipu_core1", "syscon"; + reg = <0 0x19280000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mcucfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mcucfg.txt index b8fb03f3613e..2b882b7ca72e 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mcucfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mcucfg.txt @@ -7,6 +7,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2712-mcucfg", "syscon" + - "mediatek,mt8183-mcucfg", "syscon" - #clock-cells: Must be 1 The mcucfg controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt index 859e67b416d5..72787e7dd227 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mfgcfg.txt @@ -7,6 +7,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2712-mfgcfg", "syscon" + - "mediatek,mt8183-mfgcfg", "syscon" - #clock-cells: Must be 1 The mfgcfg controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt index 15d977afad31..545eab717c96 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt @@ -11,6 +11,7 @@ Required Properties: - "mediatek,mt6797-mmsys", "syscon" - "mediatek,mt7623-mmsys", "mediatek,mt2701-mmsys", "syscon" - "mediatek,mt8173-mmsys", "syscon" + - "mediatek,mt8183-mmsys", "syscon" - #clock-cells: Must be 1 The mmsys controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt index d160c2b4b6fe..a023b8338960 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt @@ -14,6 +14,8 @@ Required Properties: - "mediatek,mt7629-topckgen" - "mediatek,mt8135-topckgen" - "mediatek,mt8173-topckgen" + - "mediatek,mt8183-topckgen", "syscon" + - "mediatek,mt8516-topckgen" - #clock-cells: Must be 1 The topckgen controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt index 3212afc753c8..57176bb8dbb5 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt @@ -11,6 +11,7 @@ Required Properties: - "mediatek,mt6797-vdecsys", "syscon" - "mediatek,mt7623-vdecsys", "mediatek,mt2701-vdecsys", "syscon" - "mediatek,mt8173-vdecsys", "syscon" + - "mediatek,mt8183-vdecsys", "syscon" - #clock-cells: Must be 1 The vdecsys controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt index 851545357e94..c9faa6269087 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt @@ -9,6 +9,7 @@ Required Properties: - "mediatek,mt2712-vencsys", "syscon" - "mediatek,mt6797-vencsys", "syscon" - "mediatek,mt8173-vencsys", "syscon" + - "mediatek,mt8183-vencsys", "syscon" - #clock-cells: Must be 1 The vencsys controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt b/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt index 99980aee26e5..c92d411fd023 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt +++ b/Documentation/devicetree/bindings/arm/stm32/stm32-syscon.txt @@ -5,10 +5,12 @@ Properties: - " st,stm32mp157-syscfg " - for stm32mp157 based SoCs, second value must be always "syscon". - reg : offset and length of the register set. + - clocks: phandle to the syscfg clock Example: syscfg: syscon@50020000 { compatible = "st,stm32mp157-syscfg", "syscon"; reg = <0x50020000 0x400>; + clocks = <&rcc SYSCFG>; }; diff --git a/Documentation/devicetree/bindings/arm/sunxi/sunxi-mbus.txt b/Documentation/devicetree/bindings/arm/sunxi/sunxi-mbus.txt new file mode 100644 index 000000000000..1464a4713553 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sunxi/sunxi-mbus.txt @@ -0,0 +1,36 @@ +Allwinner Memory Bus (MBUS) controller + +The MBUS controller drives the MBUS that other devices in the SoC will +use to perform DMA. It also has a register interface that allows to +monitor and control the bandwidth and priorities for masters on that +bus. + +Required properties: + - compatible: Must be one of: + - allwinner,sun5i-a13-mbus + - reg: Offset and length of the register set for the controller + - clocks: phandle to the clock driving the controller + - dma-ranges: See section 2.3.9 of the DeviceTree Specification + - #interconnect-cells: Must be one, with the argument being the MBUS + port ID + +Each device having to perform their DMA through the MBUS must have the +interconnects and interconnect-names properties set to the MBUS +controller and with "dma-mem" as the interconnect name. + +Example: + +mbus: dram-controller@1c01000 { + compatible = "allwinner,sun5i-a13-mbus"; + reg = <0x01c01000 0x1000>; + clocks = <&ccu CLK_MBUS>; + dma-ranges = <0x00000000 0x40000000 0x20000000>; + #interconnect-cells = <1>; +}; + +fe0: display-frontend@1e00000 { + compatible = "allwinner,sun5i-a13-display-frontend"; + ... + interconnects = <&mbus 19>; + interconnect-names = "dma-mem"; +}; diff --git a/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt index 61777ad24f61..0f777749f4f1 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,axg-audio-clkc.txt @@ -6,7 +6,8 @@ devices. Required Properties: -- compatible : should be "amlogic,axg-audio-clkc" for the A113X and A113D +- compatible : should be "amlogic,axg-audio-clkc" for the A113X and A113D, + "amlogic,g12a-audio-clkc" for G12A. - reg : physical base address of the clock controller and length of memory mapped region. - clocks : a list of phandle + clock-specifier pairs for the clocks listed diff --git a/Documentation/devicetree/bindings/clock/at91-clock.txt b/Documentation/devicetree/bindings/clock/at91-clock.txt index e9f70fcdfe80..b520280e33ff 100644 --- a/Documentation/devicetree/bindings/clock/at91-clock.txt +++ b/Documentation/devicetree/bindings/clock/at91-clock.txt @@ -8,35 +8,30 @@ Slow Clock controller: Required properties: - compatible : shall be one of the following: - "atmel,at91sam9x5-sckc" or + "atmel,at91sam9x5-sckc", + "atmel,sama5d3-sckc" or "atmel,sama5d4-sckc": at91 SCKC (Slow Clock Controller) - This node contains the slow clock definitions. - - "atmel,at91sam9x5-clk-slow-osc": - at91 slow oscillator - - "atmel,at91sam9x5-clk-slow-rc-osc": - at91 internal slow RC oscillator -- reg : defines the IO memory reserved for the SCKC. -- #size-cells : shall be 0 (reg is used to encode clk id). -- #address-cells : shall be 1 (reg is used to encode clk id). +- #clock-cells : shall be 0. +- clocks : shall be the input parent clock phandle for the clock. +Optional properties: +- atmel,osc-bypass : boolean property. Set this when a clock signal is directly + provided on XIN. For example: - sckc: sckc@fffffe50 { - compatible = "atmel,sama5d3-pmc"; - reg = <0xfffffe50 0x4> - #size-cells = <0>; - #address-cells = <1>; - - /* put at91 slow clocks here */ + sckc@fffffe50 { + compatible = "atmel,at91sam9x5-sckc"; + reg = <0xfffffe50 0x4>; + clocks = <&slow_xtal>; + #clock-cells = <0>; }; Power Management Controller (PMC): Required properties: -- compatible : shall be "atmel,<chip>-pmc", "syscon": +- compatible : shall be "atmel,<chip>-pmc", "syscon" or + "microchip,sam9x60-pmc" <chip> can be: at91rm9200, at91sam9260, at91sam9261, at91sam9263, at91sam9g45, at91sam9n12, at91sam9rl, at91sam9g15, at91sam9g25, at91sam9g35, at91sam9x25, at91sam9x35, at91sam9x5, diff --git a/Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt new file mode 100644 index 000000000000..b8d8ef3bdc5f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/cirrus,lochnagar.txt @@ -0,0 +1,93 @@ +Cirrus Logic Lochnagar Audio Development Board + +Lochnagar is an evaluation and development board for Cirrus Logic +Smart CODEC and Amp devices. It allows the connection of most Cirrus +Logic devices on mini-cards, as well as allowing connection of +various application processor systems to provide a full evaluation +platform. Audio system topology, clocking and power can all be +controlled through the Lochnagar, allowing the device under test +to be used in a variety of possible use cases. + +This binding document describes the binding for the clock portion of +the driver. + +Also see these documents for generic binding information: + [1] Clock : ../clock/clock-bindings.txt + +And these for relevant defines: + [2] include/dt-bindings/clock/lochnagar.h + +This binding must be part of the Lochnagar MFD binding: + [3] ../mfd/cirrus,lochnagar.txt + +Required properties: + + - compatible : One of the following strings: + "cirrus,lochnagar1-clk" + "cirrus,lochnagar2-clk" + + - #clock-cells : Must be 1. The first cell indicates the clock + number, see [2] for available clocks and [1]. + +Optional properties: + + - clocks : Must contain an entry for each clock in clock-names. + - clock-names : May contain entries for each of the following + clocks: + - ln-cdc-clkout : Output clock from CODEC card. + - ln-dsp-clkout : Output clock from DSP card. + - ln-gf-mclk1,ln-gf-mclk2,ln-gf-mclk3,ln-gf-mclk4 : Optional + input audio clocks from host system. + - ln-psia1-mclk, ln-psia2-mclk : Optional input audio clocks from + external connector. + - ln-spdif-clkout : Optional input audio clock from SPDIF. + - ln-adat-mclk : Optional input audio clock from ADAT. + - ln-pmic-32k : On board fixed clock. + - ln-clk-12m : On board fixed clock. + - ln-clk-11m : On board fixed clock. + - ln-clk-24m : On board fixed clock. + - ln-clk-22m : On board fixed clock. + - ln-clk-8m : On board fixed clock. + - ln-usb-clk-24m : On board fixed clock. + - ln-usb-clk-12m : On board fixed clock. + + - assigned-clocks : A list of Lochnagar clocks to be reparented, see + [2] for available clocks. + - assigned-clock-parents : Parents to be assigned to the clocks + listed in "assigned-clocks". + +Optional nodes: + + - fixed-clock nodes may be registered for the following on board clocks: + - ln-pmic-32k : 32768 Hz + - ln-clk-12m : 12288000 Hz + - ln-clk-11m : 11298600 Hz + - ln-clk-24m : 24576000 Hz + - ln-clk-22m : 22579200 Hz + - ln-clk-8m : 8192000 Hz + - ln-usb-clk-24m : 24576000 Hz + - ln-usb-clk-12m : 12288000 Hz + +Example: + +lochnagar { + lochnagar-clk { + compatible = "cirrus,lochnagar2-clk"; + + #clock-cells = <1>; + + clocks = <&clk-audio>, <&clk_pmic>; + clock-names = "ln-gf-mclk2", "ln-pmic-32k"; + + assigned-clocks = <&lochnagar-clk LOCHNAGAR_CDC_MCLK1>, + <&lochnagar-clk LOCHNAGAR_CDC_MCLK2>; + assigned-clock-parents = <&clk-audio>, + <&clk-pmic>; + }; + + clk-pmic: clk-pmic { + compatible = "fixed-clock"; + clock-cells = <0>; + clock-frequency = <32768>; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml b/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml new file mode 100644 index 000000000000..5cf0b811821e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/milbeaut-clock.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bindings/clock/milbeaut-clock.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Milbeaut SoCs Clock Controller Binding + +maintainers: + - Taichi Sugaya <sugaya.taichi@socionext.com> + +description: | + Milbeaut SoCs Clock controller is an integrated clock controller, which + generates and supplies to all modules. + + This binding uses common clock bindings + [1] Documentation/devicetree/bindings/clock/clock-bindings.txt + +properties: + compatible: + oneOf: + - items: + - enum: + - socionext,milbeaut-m10v-ccu + clocks: + maxItems: 1 + description: external clock + + '#clock-cells': + const: 1 + +required: + - compatible + - reg + - clocks + - '#clock-cells' + +examples: + # Clock controller node: + - | + m10v-clk-ctrl@1d021000 { + compatible = "socionext,milbeaut-m10v-clk-ccu"; + reg = <0x1d021000 0x4000>; + #clock-cells = <1>; + clocks = <&clki40mhz>; + }; + + # Required an external clock for Clock controller node: + - | + clocks { + clki40mhz: clki40mhz { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <40000000>; + }; + /* other clocks */ + }; + + # The clock consumer shall specify the desired clock-output of the clock + # controller as below by specifying output-id in its "clk" phandle cell. + # 2: uart + # 4: 32-bit timer + # 7: UHS-I/II + - | + serial@1e700010 { + compatible = "socionext,milbeaut-usio-uart"; + reg = <0x1e700010 0x10>; + interrupts = <0 141 0x4>, <0 149 0x4>; + interrupt-names = "rx", "tx"; + clocks = <&clk 2>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,turingcc.txt b/Documentation/devicetree/bindings/clock/qcom,turingcc.txt new file mode 100644 index 000000000000..126517de5f9a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,turingcc.txt @@ -0,0 +1,19 @@ +Qualcomm Turing Clock & Reset Controller Binding +------------------------------------------------ + +Required properties : +- compatible: shall contain "qcom,qcs404-turingcc". +- reg: shall contain base register location and length. +- clocks: ahb clock for the TuringCC +- #clock-cells: from common clock binding, shall contain 1. +- #reset-cells: from common reset binding, shall contain 1. + +Example: + turingcc: clock-controller@800000 { + compatible = "qcom,qcs404-turingcc"; + reg = <0x00800000 0x30000>; + clocks = <&gcc GCC_CDSP_CFG_AHB_CLK>; + + #clock-cells = <1>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index c655f28d5918..f7d48f23da44 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -39,6 +39,7 @@ Required properties: * "fsl,b4860-clockgen" * "fsl,ls1012a-clockgen" * "fsl,ls1021a-clockgen" + * "fsl,ls1028a-clockgen" * "fsl,ls1043a-clockgen" * "fsl,ls1046a-clockgen" * "fsl,ls1088a-clockgen" @@ -83,8 +84,8 @@ second cell is the clock index for the specified type. 1 cmux index (n in CLKCnCSR) 2 hwaccel index (n in CLKCGnHWACSR) 3 fman 0 for fm1, 1 for fm2 - 4 platform pll 0=pll, 1=pll/2, 2=pll/3, 3=pll/4 - 4=pll/5, 5=pll/6, 6=pll/7, 7=pll/8 + 4 platform pll n=pll/(n+1). For example, when n=1, + that means output_freq=PLL_freq/2. 5 coreclk must be 0 3. Example diff --git a/Documentation/devicetree/bindings/clock/sifive/fu540-prci.txt b/Documentation/devicetree/bindings/clock/sifive/fu540-prci.txt new file mode 100644 index 000000000000..349808f4fb8c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sifive/fu540-prci.txt @@ -0,0 +1,46 @@ +SiFive FU540 PRCI bindings + +On the FU540 family of SoCs, most system-wide clock and reset integration +is via the PRCI IP block. + +Required properties: +- compatible: Should be "sifive,<chip>-prci". Only one value is + supported: "sifive,fu540-c000-prci" +- reg: Should describe the PRCI's register target physical address region +- clocks: Should point to the hfclk device tree node and the rtcclk + device tree node. The RTC clock here is not a time-of-day clock, + but is instead a high-stability clock source for system timers + and cycle counters. +- #clock-cells: Should be <1> + +The clock consumer should specify the desired clock via the clock ID +macros defined in include/dt-bindings/clock/sifive-fu540-prci.h. +These macros begin with PRCI_CLK_. + +The hfclk and rtcclk nodes are required, and represent physical +crystals or resonators located on the PCB. These nodes should be present +underneath /, rather than /soc. + +Examples: + +/* under /, in PCB-specific DT data */ +hfclk: hfclk { + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <33333333>; + clock-output-names = "hfclk"; +}; +rtcclk: rtcclk { + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <1000000>; + clock-output-names = "rtcclk"; +}; + +/* under /soc, in SoC-specific DT data */ +prci: clock-controller@10000000 { + compatible = "sifive,fu540-c000-prci"; + reg = <0x0 0x10000000 0x0 0x1000>; + clocks = <&hfclk>, <&rtcclk>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt b/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt index b240121d2ac9..cfa04b614d8a 100644 --- a/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt +++ b/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt @@ -11,6 +11,8 @@ Required properties: "st,stm32f42xx-rcc" "st,stm32f469-rcc" "st,stm32f746-rcc" + "st,stm32f769-rcc" + - reg: should be register base and length as documented in the datasheet - #reset-cells: 1, see below @@ -102,6 +104,10 @@ The secondary index is bound with the following magic numbers: 28 CLK_I2C3 29 CLK_I2C4 30 CLK_LPTIMER (LPTimer1 clock) + 31 CLK_PLL_SRC + 32 CLK_DFSDM1 + 33 CLK_ADFSDM1 + 34 CLK_F769_DSI ) Example: diff --git a/Documentation/devicetree/bindings/connector/usb-connector.txt b/Documentation/devicetree/bindings/connector/usb-connector.txt index a9a2f2fc44f2..cef556d4e5ee 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.txt +++ b/Documentation/devicetree/bindings/connector/usb-connector.txt @@ -47,7 +47,7 @@ Required properties for usb-c-connector with power delivery support: Required nodes: - any data bus to the connector should be modeled using the OF graph bindings specified in bindings/graph.txt, unless the bus is between parent node and - the connector. Since single connector can have multpile data buses every bus + the connector. Since single connector can have multiple data buses every bus has assigned OF graph port number as follows: 0: High Speed (HS), present in all connectors, 1: Super Speed (SS), present in SS capable connectors, diff --git a/Documentation/devicetree/bindings/counter/ftm-quaddec.txt b/Documentation/devicetree/bindings/counter/ftm-quaddec.txt new file mode 100644 index 000000000000..4d18cd722074 --- /dev/null +++ b/Documentation/devicetree/bindings/counter/ftm-quaddec.txt @@ -0,0 +1,18 @@ +FlexTimer Quadrature decoder counter + +This driver exposes a simple counter for the quadrature decoder mode. + +Required properties: +- compatible: Must be "fsl,ftm-quaddec". +- reg: Must be set to the memory region of the flextimer. + +Optional property: +- big-endian: Access the device registers in big-endian mode. + +Example: + counter0: counter@29d0000 { + compatible = "fsl,ftm-quaddec"; + reg = <0x0 0x29d0000 0x0 0x10000>; + big-endian; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/iio/counter/stm32-lptimer-cnt.txt b/Documentation/devicetree/bindings/counter/stm32-lptimer-cnt.txt index a04aa5c04103..e90bc47f752a 100644 --- a/Documentation/devicetree/bindings/iio/counter/stm32-lptimer-cnt.txt +++ b/Documentation/devicetree/bindings/counter/stm32-lptimer-cnt.txt @@ -10,8 +10,9 @@ See ../mfd/stm32-lptimer.txt for details about the parent node. Required properties: - compatible: Must be "st,stm32-lptimer-counter". -- pinctrl-names: Set to "default". -- pinctrl-0: List of phandles pointing to pin configuration nodes, +- pinctrl-names: Set to "default". An additional "sleep" state can be + defined to set pins in sleep state. +- pinctrl-n: List of phandles pointing to pin configuration nodes, to set IN1/IN2 pins in mode of operation for Low-Power Timer input on external pin. @@ -21,7 +22,8 @@ Example: ... counter { compatible = "st,stm32-lptimer-counter"; - pinctrl-names = "default"; + pinctrl-names = "default", "sleep"; pinctrl-0 = <&lptim1_in_pins>; + pinctrl-1 = <&lptim1_sleep_in_pins>; }; }; diff --git a/Documentation/devicetree/bindings/counter/stm32-timer-cnt.txt b/Documentation/devicetree/bindings/counter/stm32-timer-cnt.txt new file mode 100644 index 000000000000..c52fcdd4bf6c --- /dev/null +++ b/Documentation/devicetree/bindings/counter/stm32-timer-cnt.txt @@ -0,0 +1,31 @@ +STMicroelectronics STM32 Timer quadrature encoder + +STM32 Timer provides quadrature encoder to detect +angular position and direction of rotary elements, +from IN1 and IN2 input signals. + +Must be a sub-node of an STM32 Timer device tree node. +See ../mfd/stm32-timers.txt for details about the parent node. + +Required properties: +- compatible: Must be "st,stm32-timer-counter". +- pinctrl-names: Set to "default". +- pinctrl-0: List of phandles pointing to pin configuration nodes, + to set CH1/CH2 pins in mode of operation for STM32 + Timer input on external pin. + +Example: + timers@40010000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "st,stm32-timers"; + reg = <0x40010000 0x400>; + clocks = <&rcc 0 160>; + clock-names = "int"; + + counter { + compatible = "st,stm32-timer-counter"; + pinctrl-names = "default"; + pinctrl-0 = <&tim1_in_pins>; + }; + }; diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt index bf4a18047309..3a50a7862cf3 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt @@ -37,6 +37,7 @@ Required properties: - GXL (S905X, S905D) : "amlogic,meson-gxl-dw-hdmi" - GXM (S912) : "amlogic,meson-gxm-dw-hdmi" followed by the common "amlogic,meson-gx-dw-hdmi" + - G12A (S905X2, S905Y2, S905D2) : "amlogic,meson-g12a-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, @@ -66,6 +67,9 @@ corresponding to each HDMI output and input. S905X (GXL) VENC Input TMDS Output S905D (GXL) VENC Input TMDS Output S912 (GXM) VENC Input TMDS Output + S905X2 (G12A) VENC Input TMDS Output + S905Y2 (G12A) VENC Input TMDS Output + S905D2 (G12A) VENC Input TMDS Output Example: diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt index c65fd7a7467c..be40a780501c 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt +++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt @@ -57,18 +57,18 @@ Required properties: - GXL (S905X, S905D) : "amlogic,meson-gxl-vpu" - GXM (S912) : "amlogic,meson-gxm-vpu" followed by the common "amlogic,meson-gx-vpu" + - G12A (S905X2, S905Y2, S905D2) : "amlogic,meson-g12a-vpu" - reg: base address and size of he following memory-mapped regions : - vpu - hhi - - dmc - reg-names: should contain the names of the previous memory regions - interrupts: should contain the VENC Vsync interrupt number +- amlogic,canvas: phandle to canvas provider node as described in the file + ../soc/amlogic/amlogic,canvas.txt Optional properties: - power-domains: Optional phandle to associated power domain as described in the file ../power/power_domain.txt -- amlogic,canvas: phandle to canvas provider node as described in the file - ../soc/amlogic/amlogic,canvas.txt Required nodes: @@ -84,6 +84,9 @@ corresponding to each VPU output. S905X (GXL) CVBS VDAC HDMI-TX S905D (GXL) CVBS VDAC HDMI-TX S912 (GXM) CVBS VDAC HDMI-TX + S905X2 (G12A) CVBS VDAC HDMI-TX + S905Y2 (G12A) CVBS VDAC HDMI-TX + S905D2 (G12A) CVBS VDAC HDMI-TX Example: diff --git a/Documentation/devicetree/bindings/display/amlogic,simple-framebuffer.txt b/Documentation/devicetree/bindings/display/amlogic,simple-framebuffer.txt deleted file mode 100644 index aaa6c24c8e70..000000000000 --- a/Documentation/devicetree/bindings/display/amlogic,simple-framebuffer.txt +++ /dev/null @@ -1,33 +0,0 @@ -Meson specific Simple Framebuffer bindings - -This binding documents meson specific extensions to the simple-framebuffer -bindings. The meson simplefb u-boot code relies on the devicetree containing -pre-populated simplefb nodes. - -These extensions are intended so that u-boot can select the right node based -on which pipeline is being used. As such they are solely intended for -firmware / bootloader use, and the OS should ignore them. - -Required properties: -- compatible: "amlogic,simple-framebuffer", "simple-framebuffer" -- amlogic,pipeline, one of: - "vpu-cvbs" - "vpu-hdmi" - -Example: - -chosen { - #address-cells = <2>; - #size-cells = <2>; - ranges; - - simplefb_hdmi: framebuffer-hdmi { - compatible = "amlogic,simple-framebuffer", - "simple-framebuffer"; - amlogic,pipeline = "vpu-hdmi"; - clocks = <&clkc CLKID_HDMI_PCLK>, - <&clkc CLKID_CLK81>, - <&clkc CLKID_GCLK_VENCI_INT0>; - power-domains = <&pwrc_vpu>; - }; -}; diff --git a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt index 54d7e31525ec..5ff4f64ef8e8 100644 --- a/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt +++ b/Documentation/devicetree/bindings/display/bridge/ti,tfp410.txt @@ -6,15 +6,32 @@ Required properties: Optional properties: - powerdown-gpios: power-down gpio -- reg: I2C address. If and only if present the device node - should be placed into the i2c controller node where the - tfp410 i2c is connected to. +- reg: I2C address. If and only if present the device node should be placed + into the I2C controller node where the TFP410 I2C is connected to. +- ti,deskew: data de-skew in 350ps increments, from -4 to +3, as configured + through th DK[3:1] pins. This property shall be present only if the TFP410 + is not connected through I2C. Required nodes: -- Video port 0 for DPI input [1]. -- Video port 1 for DVI output [1]. -[1]: Documentation/devicetree/bindings/media/video-interfaces.txt +This device has two video ports. Their connections are modeled using the OF +graph bindings specified in [1]. Each port node shall have a single endpoint. + +- Port 0 is the DPI input port. Its endpoint subnode shall contain a + pclk-sample and bus-width property and a remote-endpoint property as specified + in [1]. + - If pclk-sample is not defined, pclk-sample = 0 should be assumed for + backward compatibility. + - If bus-width is not defined then bus-width = 24 should be assumed for + backward compatibility. + bus-width = 24: 24 data lines are connected and single-edge mode + bus-width = 12: 12 data lines are connected and dual-edge mode + +- Port 1 is the DVI output port. Its endpoint subnode shall contain a + remote-endpoint property is specified in [1]. + +[1] Documentation/devicetree/bindings/media/video-interfaces.txt + Example ------- @@ -22,6 +39,7 @@ Example tfp410: encoder@0 { compatible = "ti,tfp410"; powerdown-gpios = <&twl_gpio 2 GPIO_ACTIVE_LOW>; + ti,deskew = <4>; ports { #address-cells = <1>; @@ -31,6 +49,8 @@ tfp410: encoder@0 { reg = <0>; tfp410_in: endpoint@0 { + pclk-sample = <1>; + bus-width = <24>; remote-endpoint = <&dpi_out>; }; }; diff --git a/Documentation/devicetree/bindings/display/msm/gmu.txt b/Documentation/devicetree/bindings/display/msm/gmu.txt index 3439b38e60f2..90af5b0a56a9 100644 --- a/Documentation/devicetree/bindings/display/msm/gmu.txt +++ b/Documentation/devicetree/bindings/display/msm/gmu.txt @@ -24,7 +24,10 @@ Required properties: * "cxo" * "axi" * "mnoc" -- power-domains: should be <&clock_gpucc GPU_CX_GDSC> +- power-domains: should be: + <&clock_gpucc GPU_CX_GDSC> + <&clock_gpucc GPU_GX_GDSC> +- power-domain-names: Matching names for the power domains - iommus: phandle to the adreno iommu - operating-points-v2: phandle to the OPP operating points @@ -51,7 +54,10 @@ Example: <&gcc GCC_GPU_MEMNOC_GFX_CLK>; clock-names = "gmu", "cxo", "axi", "memnoc"; - power-domains = <&gpucc GPU_CX_GDSC>; + power-domains = <&gpucc GPU_CX_GDSC>, + <&gpucc GPU_GX_GDSC>; + power-domain-names = "cx", "gx"; + iommus = <&adreno_smmu 5>; operating-points-v2 = <&gmu_opp_table>; diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index aad1aef682f7..2b8fd26c43b0 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -22,9 +22,14 @@ Required properties: - qcom,adreno-630.2 - iommus: optional phandle to an adreno iommu instance - operating-points-v2: optional phandle to the OPP operating points +- interconnects: optional phandle to an interconnect provider. See + ../interconnect/interconnect.txt for details. - qcom,gmu: For GMU attached devices a phandle to the GMU device that will control the power for the GPU. Applicable targets: - qcom,adreno-630.2 +- zap-shader: For a5xx and a6xx devices this node contains a memory-region that + points to reserved memory to store the zap shader that can be used to help + bring the GPU out of secure mode. Example 3xx/4xx/a5xx: @@ -70,6 +75,12 @@ Example a6xx (with GMU): operating-points-v2 = <&gpu_opp_table>; + interconnects = <&rsc_hlos MASTER_GFX3D &rsc_hlos SLAVE_EBI1>; + qcom,gmu = <&gmu>; + + zap-shader { + memory-region = <&zap_shader_region>; + }; }; }; diff --git a/Documentation/devicetree/bindings/display/panel/feiyang,fy07024di26a30d.txt b/Documentation/devicetree/bindings/display/panel/feiyang,fy07024di26a30d.txt new file mode 100644 index 000000000000..82caa7b65ae8 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/feiyang,fy07024di26a30d.txt @@ -0,0 +1,20 @@ +Feiyang FY07024DI26A30-D 7" MIPI-DSI LCD Panel + +Required properties: +- compatible: must be "feiyang,fy07024di26a30d" +- reg: DSI virtual channel used by that screen +- avdd-supply: analog regulator dc1 switch +- dvdd-supply: 3v3 digital regulator +- reset-gpios: a GPIO phandle for the reset pin + +Optional properties: +- backlight: phandle for the backlight control. + +panel@0 { + compatible = "feiyang,fy07024di26a30d"; + reg = <0>; + avdd-supply = <®_dc1sw>; + dvdd-supply = <®_dldo2>; + reset-gpios = <&pio 3 24 GPIO_ACTIVE_HIGH>; /* LCD-RST: PD24 */ + backlight = <&backlight>; +}; diff --git a/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt b/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt index d0f55161579a..3ab8c7412cf6 100644 --- a/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,p079zca.txt @@ -12,7 +12,7 @@ Optional properties: Example: &mipi_dsi { - panel { + panel@0 { compatible = "innolux,p079zca"; reg = <0>; power-supply = <...>; diff --git a/Documentation/devicetree/bindings/display/panel/innolux,p097pfg.txt b/Documentation/devicetree/bindings/display/panel/innolux,p097pfg.txt index 595d9dfeffd3..d1cab3a8f0fb 100644 --- a/Documentation/devicetree/bindings/display/panel/innolux,p097pfg.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,p097pfg.txt @@ -13,7 +13,7 @@ Optional properties: Example: &mipi_dsi { - panel { + panel@0 { compatible = "innolux,p079zca"; reg = <0>; avdd-supply = <...>; diff --git a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd097d04.txt b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd097d04.txt index 164a5fa236da..cfefff688614 100644 --- a/Documentation/devicetree/bindings/display/panel/kingdisplay,kd097d04.txt +++ b/Documentation/devicetree/bindings/display/panel/kingdisplay,kd097d04.txt @@ -12,7 +12,7 @@ Optional properties: Example: &mipi_dsi { - panel { + panel@0 { compatible = "kingdisplay,kd097d04"; reg = <0>; power-supply = <...>; diff --git a/Documentation/devicetree/bindings/display/panel/lg,acx467akm-7.txt b/Documentation/devicetree/bindings/display/panel/lg,acx467akm-7.txt new file mode 100644 index 000000000000..fc1e1b325e49 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/lg,acx467akm-7.txt @@ -0,0 +1,7 @@ +LG ACX467AKM-7 4.95" 1080Ă—1920 LCD Panel + +Required properties: +- compatible: must be "lg,acx467akm-7" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/display/panel/osddisplays,osd070t1718-19ts.txt b/Documentation/devicetree/bindings/display/panel/osddisplays,osd070t1718-19ts.txt new file mode 100644 index 000000000000..e57883ccdf2f --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/osddisplays,osd070t1718-19ts.txt @@ -0,0 +1,12 @@ +OSD Displays OSD070T1718-19TS 7" WVGA TFT LCD panel + +Required properties: +- compatible: shall be "osddisplays,osd070t1718-19ts" +- power-supply: see simple-panel.txt + +Optional properties: +- backlight: see simple-panel.txt + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. No other simple-panel properties than +the ones specified herein are valid. diff --git a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt new file mode 100644 index 000000000000..1b5763200cf6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.txt @@ -0,0 +1,18 @@ +Rocktech jh057n00900 5.5" 720x1440 TFT LCD panel + +Required properties: +- compatible: should be "rocktech,jh057n00900" +- reg: DSI virtual channel of the peripheral +- reset-gpios: panel reset gpio +- backlight: phandle of the backlight device attached to the panel + +Example: + + &mipi_dsi { + panel@0 { + compatible = "rocktech,jh057n00900"; + reg = <0>; + backlight = <&backlight>; + reset-gpios = <&gpio3 13 GPIO_ACTIVE_LOW>; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/ronbo,rb070d30.yaml b/Documentation/devicetree/bindings/display/panel/ronbo,rb070d30.yaml new file mode 100644 index 000000000000..0e7987f1cdb7 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/ronbo,rb070d30.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR X11) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/ronbo,rb070d30.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ronbo RB070D30 DSI Display Panel + +maintainers: + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + compatible: + const: ronbo,rb070d30 + + reg: + description: MIPI-DSI virtual channel + + power-gpios: + description: GPIO used for the power pin + maxItems: 1 + + reset-gpios: + description: GPIO used for the reset pin + maxItems: 1 + + shlr-gpios: + description: GPIO used for the shlr pin (horizontal flip) + maxItems: 1 + + updn-gpios: + description: GPIO used for the updn pin (vertical flip) + maxItems: 1 + + vcc-lcd-supply: + description: Power regulator + + backlight: + description: Backlight used by the panel + $ref: "/schemas/types.yaml#/definitions/phandle" + +required: + - compatible + - power-gpios + - reg + - reset-gpios + - shlr-gpios + - updn-gpios + - vcc-lcd-supply + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt b/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt index ed34253d9fb1..898e06ecf4ef 100644 --- a/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt +++ b/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt @@ -6,6 +6,7 @@ Required properties: Optional properties: - label: a symbolic name for the panel +- backlight: phandle of the backlight device Required nodes: - Video port for DPI input @@ -21,6 +22,7 @@ lcd-panel: td028ttec1@0 { spi-cpha; label = "lcd"; + backlight = <&backlight>; port { lcd_in: endpoint { remote-endpoint = <&dpi_out>; diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.txt new file mode 100644 index 000000000000..d1ad31bca8d9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip,rk3066-hdmi.txt @@ -0,0 +1,72 @@ +Rockchip specific extensions for rk3066 HDMI +============================================ + +Required properties: +- compatible: + "rockchip,rk3066-hdmi"; +- reg: + Physical base address and length of the controller's registers. +- clocks, clock-names: + Phandle to HDMI controller clock, name should be "hclk". +- interrupts: + HDMI interrupt number. +- power-domains: + Phandle to the RK3066_PD_VIO power domain. +- rockchip,grf: + This soc uses GRF regs to switch the HDMI TX input between vop0 and vop1. +- ports: + Contains one port node with two endpoints, numbered 0 and 1, + connected respectively to vop0 and vop1. + Contains one port node with one endpoint + connected to a hdmi-connector node. +- pinctrl-0, pinctrl-name: + Switch the iomux for the HPD/I2C pins to HDMI function. + +Example: + hdmi: hdmi@10116000 { + compatible = "rockchip,rk3066-hdmi"; + reg = <0x10116000 0x2000>; + interrupts = <GIC_SPI 64 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru HCLK_HDMI>; + clock-names = "hclk"; + power-domains = <&power RK3066_PD_VIO>; + rockchip,grf = <&grf>; + pinctrl-names = "default"; + pinctrl-0 = <&hdmii2c_xfer>, <&hdmi_hpd>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + hdmi_in: port@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + hdmi_in_vop0: endpoint@0 { + reg = <0>; + remote-endpoint = <&vop0_out_hdmi>; + }; + hdmi_in_vop1: endpoint@1 { + reg = <1>; + remote-endpoint = <&vop1_out_hdmi>; + }; + }; + hdmi_out: port@1 { + reg = <1>; + hdmi_out_con: endpoint { + remote-endpoint = <&hdmi_con_in>; + }; + }; + }; + }; + +&pinctrl { + hdmi { + hdmi_hpd: hdmi-hpd { + rockchip,pins = <0 RK_PA0 1 &pcfg_pull_default>; + }; + hdmii2c_xfer: hdmii2c-xfer { + rockchip,pins = <0 RK_PA1 1 &pcfg_pull_none>, + <0 RK_PA2 1 &pcfg_pull_none>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt b/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt deleted file mode 100644 index d693b8dc9a62..000000000000 --- a/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt +++ /dev/null @@ -1,36 +0,0 @@ -Sunxi specific Simple Framebuffer bindings - -This binding documents sunxi specific extensions to the simple-framebuffer -bindings. The sunxi simplefb u-boot code relies on the devicetree containing -pre-populated simplefb nodes. - -These extensions are intended so that u-boot can select the right node based -on which pipeline is being used. As such they are solely intended for -firmware / bootloader use, and the OS should ignore them. - -Required properties: -- compatible: "allwinner,simple-framebuffer" -- allwinner,pipeline, one of: - "de_be0-lcd0" - "de_be1-lcd1" - "de_be0-lcd0-hdmi" - "de_be1-lcd1-hdmi" - "mixer0-lcd0" - "mixer0-lcd0-hdmi" - "mixer1-lcd1-hdmi" - "mixer1-lcd1-tve" - -Example: - -chosen { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - framebuffer@0 { - compatible = "allwinner,simple-framebuffer", "simple-framebuffer"; - allwinner,pipeline = "de_be0-lcd0-hdmi"; - clocks = <&pll5 1>, <&ahb_gates 36>, <&ahb_gates 43>, - <&ahb_gates 44>; - }; -}; diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.txt b/Documentation/devicetree/bindings/display/simple-framebuffer.txt deleted file mode 100644 index 5a9ce511be88..000000000000 --- a/Documentation/devicetree/bindings/display/simple-framebuffer.txt +++ /dev/null @@ -1,91 +0,0 @@ -Simple Framebuffer - -A simple frame-buffer describes a frame-buffer setup by firmware or -the bootloader, with the assumption that the display hardware has already -been set up to scan out from the memory pointed to by the reg property. - -Since simplefb nodes represent runtime information they must be sub-nodes of -the chosen node (*). Simplefb nodes must be named "framebuffer@<address>". - -If the devicetree contains nodes for the display hardware used by a simplefb, -then the simplefb node must contain a property called "display", which -contains a phandle pointing to the primary display hw node, so that the OS -knows which simplefb to disable when handing over control to a driver for the -real hardware. The bindings for the hw nodes must specify which node is -considered the primary node. - -It is advised to add display# aliases to help the OS determine how to number -things. If display# aliases are used, then if the simplefb node contains a -"display" property then the /aliases/display# path must point to the display -hw node the "display" property points to, otherwise it must point directly -to the simplefb node. - -If a simplefb node represents the preferred console for user interaction, -then the chosen node's stdout-path property should point to it, or to the -primary display hw node, as with display# aliases. If display aliases are -used then it should be set to the alias instead. - -It is advised that devicetree files contain pre-filled, disabled framebuffer -nodes, so that the firmware only needs to update the mode information and -enable them. This way if e.g. later on support for more display clocks get -added, the simplefb nodes will already contain this info and the firmware -does not need to be updated. - -If pre-filled framebuffer nodes are used, the firmware may need extra -information to find the right node. In that case an extra platform specific -compatible and platform specific properties should be used and documented, -see e.g. simple-framebuffer-sunxi.txt . - -Required properties: -- compatible: "simple-framebuffer" -- reg: Should contain the location and size of the framebuffer memory. -- width: The width of the framebuffer in pixels. -- height: The height of the framebuffer in pixels. -- stride: The number of bytes in each line of the framebuffer. -- format: The format of the framebuffer surface. Valid values are: - - r5g6b5 (16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b). - - a8b8g8r8 (32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r). - -Optional properties: -- clocks : List of clocks used by the framebuffer. -- *-supply : Any number of regulators used by the framebuffer. These should - be named according to the names in the device's design. - - The above resources are expected to already be configured correctly. - The OS must ensure they are not modified or disabled while the simple - framebuffer remains active. - -- display : phandle pointing to the primary display hardware node - -Example: - -aliases { - display0 = &lcdc0; -} - -chosen { - framebuffer0: framebuffer@1d385000 { - compatible = "simple-framebuffer"; - reg = <0x1d385000 (1600 * 1200 * 2)>; - width = <1600>; - height = <1200>; - stride = <(1600 * 2)>; - format = "r5g6b5"; - clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>; - lcd-supply = <®_dc1sw>; - display = <&lcdc0>; - }; - stdout-path = "display0"; -}; - -soc@1c00000 { - lcdc0: lcdc@1c0c000 { - compatible = "allwinner,sun4i-a10-lcdc"; - ... - }; -}; - - -*) Older devicetree files may have a compatible = "simple-framebuffer" node -in a different place, operating systems must first enumerate any compatible -nodes found under chosen and then check for other compatible nodes. diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml new file mode 100644 index 000000000000..b052d76cf8b6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/simple-framebuffer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Simple Framebuffer Device Tree Bindings + +maintainers: + - Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com> + - Hans de Goede <hdegoede@redhat.com> + +description: |+ + A simple frame-buffer describes a frame-buffer setup by firmware or + the bootloader, with the assumption that the display hardware has + already been set up to scan out from the memory pointed to by the + reg property. + + Since simplefb nodes represent runtime information they must be + sub-nodes of the chosen node (*). Simplefb nodes must be named + framebuffer@<address>. + + If the devicetree contains nodes for the display hardware used by a + simplefb, then the simplefb node must contain a property called + display, which contains a phandle pointing to the primary display + hw node, so that the OS knows which simplefb to disable when handing + over control to a driver for the real hardware. The bindings for the + hw nodes must specify which node is considered the primary node. + + It is advised to add display# aliases to help the OS determine how + to number things. If display# aliases are used, then if the simplefb + node contains a display property then the /aliases/display# path + must point to the display hw node the display property points to, + otherwise it must point directly to the simplefb node. + + If a simplefb node represents the preferred console for user + interaction, then the chosen node stdout-path property should point + to it, or to the primary display hw node, as with display# + aliases. If display aliases are used then it should be set to the + alias instead. + + It is advised that devicetree files contain pre-filled, disabled + framebuffer nodes, so that the firmware only needs to update the + mode information and enable them. This way if e.g. later on support + for more display clocks get added, the simplefb nodes will already + contain this info and the firmware does not need to be updated. + + If pre-filled framebuffer nodes are used, the firmware may need + extra information to find the right node. In that case an extra + platform specific compatible and platform specific properties should + be used and documented. + +properties: + compatible: + items: + - enum: + - allwinner,simple-framebuffer + - amlogic,simple-framebuffer + - const: simple-framebuffer + + reg: + description: Location and size of the framebuffer memory + + clocks: + description: List of clocks used by the framebuffer. + + power-domains: + description: List of power domains used by the framebuffer. + + width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Width of the framebuffer in pixels + + height: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Height of the framebuffer in pixels + + stride: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Number of bytes of a line in the framebuffer + + format: + description: > + Format of the framebuffer: + * `a8b8g8r8` - 32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r + * `r5g6b5` - 16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b + enum: + - a8b8g8r8 + - r5g6b5 + + display: + $ref: /schemas/types.yaml#/definitions/phandle + description: Primary display hardware node + + allwinner,pipeline: + description: Pipeline used by the framebuffer on Allwinner SoCs + enum: + - de_be0-lcd0 + - de_be0-lcd0-hdmi + - de_be0-lcd0-tve0 + - de_be1-lcd0 + - de_be1-lcd1-hdmi + - de_fe0-de_be0-lcd0 + - de_fe0-de_be0-lcd0-hdmi + - de_fe0-de_be0-lcd0-tve0 + - mixer0-lcd0 + - mixer0-lcd0-hdmi + - mixer1-lcd1-hdmi + - mixer1-lcd1-tve + + amlogic,pipeline: + description: Pipeline used by the framebuffer on Amlogic SoCs + enum: + - vpu-cvbs + - vpu-hdmi + +patternProperties: + "^[a-zA-Z0-9-]+-supply$": + $ref: /schemas/types.yaml#/definitions/phandle + description: + Regulators used by the framebuffer. These should be named + according to the names in the device design. + +required: + # The binding requires also reg, width, height, stride and format, + # but usually they will be filled by the bootloader. + - compatible + +additionalProperties: false + +examples: + - | + aliases { + display0 = &lcdc0; + }; + + chosen { + #address-cells = <1>; + #size-cells = <1>; + stdout-path = "display0"; + framebuffer0: framebuffer@1d385000 { + compatible = "simple-framebuffer"; + reg = <0x1d385000 3840000>; + width = <1600>; + height = <1200>; + stride = <3200>; + format = "r5g6b5"; + clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>; + lcd-supply = <®_dc1sw>; + display = <&lcdc0>; + }; + }; + + soc@1c00000 { + lcdc0: lcdc@1c0c000 { + compatible = "allwinner,sun4i-a10-lcdc"; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/ste,mcde.txt b/Documentation/devicetree/bindings/display/ste,mcde.txt new file mode 100644 index 000000000000..4c33c692bd5f --- /dev/null +++ b/Documentation/devicetree/bindings/display/ste,mcde.txt @@ -0,0 +1,104 @@ +ST-Ericsson Multi Channel Display Engine MCDE + +The ST-Ericsson MCDE is a display controller with support for compositing +and displaying several channels memory resident graphics data on DSI or +LCD displays or bridges. It is used in the ST-Ericsson U8500 platform. + +Required properties: + +- compatible: must be: + "ste,mcde" +- reg: register base for the main MCDE control registers, should be + 0x1000 in size +- interrupts: the interrupt line for the MCDE +- epod-supply: a phandle to the EPOD regulator +- vana-supply: a phandle to the analog voltage regulator +- clocks: an array of the MCDE clocks in this strict order: + MCDECLK (main MCDE clock), LCDCLK (LCD clock), PLLDSI + (HDMI clock), DSI0ESCLK (DSI0 energy save clock), + DSI1ESCLK (DSI1 energy save clock), DSI2ESCLK (DSI2 energy + save clock) +- clock-names: must be the following array: + "mcde", "lcd", "hdmi" + to match the required clock inputs above. +- #address-cells: should be <1> (for the DSI hosts that will be children) +- #size-cells: should be <1> (for the DSI hosts that will be children) +- ranges: this should always be stated + +Required subnodes: + +The devicetree must specify subnodes for the DSI host adapters. +These must have the following characteristics: + +- compatible: must be: + "ste,mcde-dsi" +- reg: must specify the register range for the DSI host +- vana-supply: phandle to the VANA voltage regulator +- clocks: phandles to the high speed and low power (energy save) clocks + the high speed clock is not present on the third (dsi2) block, so it + should only have the "lp" clock +- clock-names: "hs" for the high speed clock and "lp" for the low power + (energy save) clock +- #address-cells: should be <1> +- #size-cells: should be <0> + +Display panels and bridges will appear as children on the DSI hosts, and +the displays are connected to the DSI hosts using the common binding +for video transmitter interfaces; see +Documentation/devicetree/bindings/media/video-interfaces.txt + +If a DSI host is unused (not connected) it will have no children defined. + +Example: + +mcde@a0350000 { + compatible = "ste,mcde"; + reg = <0xa0350000 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + epod-supply = <&db8500_b2r2_mcde_reg>; + vana-supply = <&ab8500_ldo_ana_reg>; + clocks = <&prcmu_clk PRCMU_MCDECLK>, /* Main MCDE clock */ + <&prcmu_clk PRCMU_LCDCLK>, /* LCD clock */ + <&prcmu_clk PRCMU_PLLDSI>; /* HDMI clock */ + clock-names = "mcde", "lcd", "hdmi"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + dsi0: dsi@a0351000 { + compatible = "ste,mcde-dsi"; + reg = <0xa0351000 0x1000>; + vana-supply = <&ab8500_ldo_ana_reg>; + clocks = <&prcmu_clk PRCMU_DSI0CLK>, <&prcmu_clk PRCMU_DSI0ESCCLK>; + clock-names = "hs", "lp"; + #address-cells = <1>; + #size-cells = <0>; + + panel { + compatible = "samsung,s6d16d0"; + reg = <0>; + vdd1-supply = <&ab8500_ldo_aux1_reg>; + reset-gpios = <&gpio2 1 GPIO_ACTIVE_LOW>; + }; + + }; + dsi1: dsi@a0352000 { + compatible = "ste,mcde-dsi"; + reg = <0xa0352000 0x1000>; + vana-supply = <&ab8500_ldo_ana_reg>; + clocks = <&prcmu_clk PRCMU_DSI1CLK>, <&prcmu_clk PRCMU_DSI1ESCCLK>; + clock-names = "hs", "lp"; + #address-cells = <1>; + #size-cells = <0>; + }; + dsi2: dsi@a0353000 { + compatible = "ste,mcde-dsi"; + reg = <0xa0353000 0x1000>; + vana-supply = <&ab8500_ldo_ana_reg>; + /* This DSI port only has the Low Power / Energy Save clock */ + clocks = <&prcmu_clk PRCMU_DSI2ESCCLK>; + clock-names = "lp"; + #address-cells = <1>; + #size-cells = <0>; + }; +}; diff --git a/Documentation/devicetree/bindings/dma/adi,axi-dmac.txt b/Documentation/devicetree/bindings/dma/adi,axi-dmac.txt index 47cb1d14b690..b38ee732efa9 100644 --- a/Documentation/devicetree/bindings/dma/adi,axi-dmac.txt +++ b/Documentation/devicetree/bindings/dma/adi,axi-dmac.txt @@ -18,7 +18,6 @@ Required properties for adi,channels sub-node: Required channel sub-node properties: - reg: Which channel this node refers to. - - adi,length-width: Width of the DMA transfer length register. - adi,source-bus-width, adi,destination-bus-width: Width of the source or destination bus in bits. - adi,source-bus-type, @@ -28,7 +27,8 @@ Required channel sub-node properties: 1 (AXI_DMAC_TYPE_AXI_STREAM): Streaming AXI interface 2 (AXI_DMAC_TYPE_AXI_FIFO): FIFO interface -Optional channel properties: +Deprecated optional channel properties: + - adi,length-width: Width of the DMA transfer length register. - adi,cyclic: Must be set if the channel supports hardware cyclic DMA transfers. - adi,2d: Must be set if the channel supports hardware 2D DMA transfers. diff --git a/Documentation/devicetree/bindings/dma/nvidia,tegra210-adma.txt b/Documentation/devicetree/bindings/dma/nvidia,tegra210-adma.txt index 2f35b047f772..245d3063715c 100644 --- a/Documentation/devicetree/bindings/dma/nvidia,tegra210-adma.txt +++ b/Documentation/devicetree/bindings/dma/nvidia,tegra210-adma.txt @@ -4,7 +4,9 @@ The Tegra Audio DMA controller that is used for transferring data between system memory and the Audio Processing Engine (APE). Required properties: -- compatible: Must be "nvidia,tegra210-adma". +- compatible: Should contain one of the following: + - "nvidia,tegra210-adma": for Tegra210 + - "nvidia,tegra186-adma": for Tegra186 and Tegra194 - reg: Should contain DMA registers location and length. This should be a single entry that includes all of the per-channel registers in one contiguous bank. diff --git a/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt b/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt index 5626560a6cfd..8f52206cfd2a 100644 --- a/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt +++ b/Documentation/devicetree/bindings/edac/socfpga-eccmgr.txt @@ -232,37 +232,152 @@ Example: }; }; -Stratix10 SoCFPGA ECC Manager +Stratix10 SoCFPGA ECC Manager (ARM64) The Stratix10 SoC ECC Manager handles the IRQs for each peripheral -in a shared register similar to the Arria10. However, ECC requires -access to registers that can only be read from Secure Monitor with -SMC calls. Therefore the device tree is slightly different. +in a shared register similar to the Arria10. However, Stratix10 ECC +requires access to registers that can only be read from Secure Monitor +with SMC calls. Therefore the device tree is slightly different. Note +that only 1 interrupt is sent in Stratix10 because the double bit errors +are treated as SErrors in ARM64 instead of IRQs in ARM32. Required Properties: - compatible : Should be "altr,socfpga-s10-ecc-manager" -- interrupts : Should be single bit error interrupt, then double bit error - interrupt. +- altr,sysgr-syscon : phandle to Stratix10 System Manager Block + containing the ECC manager registers. +- interrupts : Should be single bit error interrupt. - interrupt-controller : boolean indicator that ECC Manager is an interrupt controller - #interrupt-cells : must be set to 2. +- #address-cells: must be 1 +- #size-cells: must be 1 +- ranges : standard definition, should translate from local addresses Subcomponents: SDRAM ECC Required Properties: - compatible : Should be "altr,sdram-edac-s10" -- interrupts : Should be single bit error interrupt, then double bit error - interrupt, in this order. +- interrupts : Should be single bit error interrupt. + +On-Chip RAM ECC +Required Properties: +- compatible : Should be "altr,socfpga-s10-ocram-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent OCRAM node. +- interrupts : Should be single bit error interrupt. + +Ethernet FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-s10-eth-mac-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent Ethernet node. +- interrupts : Should be single bit error interrupt. + +NAND FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-s10-nand-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent NAND node. +- interrupts : Should be single bit error interrupt. + +DMA FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-s10-dma-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent DMA node. +- interrupts : Should be single bit error interrupt. + +USB FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-s10-usb-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent USB node. +- interrupts : Should be single bit error interrupt. + +SDMMC FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-s10-sdmmc-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent SD/MMC node. +- interrupts : Should be single bit error interrupt for port A + and then single bit error interrupt for port B. Example: eccmgr { compatible = "altr,socfpga-s10-ecc-manager"; - interrupts = <0 15 4>, <0 95 4>; + altr,sysmgr-syscon = <&sysmgr>; + #address-cells = <1>; + #size-cells = <1>; + interrupts = <0 15 4>; interrupt-controller; #interrupt-cells = <2>; + ranges; sdramedac { compatible = "altr,sdram-edac-s10"; - interrupts = <16 4>, <48 4>; + interrupts = <16 IRQ_TYPE_LEVEL_HIGH>; + }; + + ocram-ecc@ff8cc000 { + compatible = "altr,socfpga-s10-ocram-ecc"; + reg = <ff8cc000 0x100>; + altr,ecc-parent = <&ocram>; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH>; + }; + + emac0-rx-ecc@ff8c0000 { + compatible = "altr,socfpga-s10-eth-mac-ecc"; + reg = <0xff8c0000 0x100>; + altr,ecc-parent = <&gmac0>; + interrupts = <4 IRQ_TYPE_LEVEL_HIGH>; + }; + + emac0-tx-ecc@ff8c0400 { + compatible = "altr,socfpga-s10-eth-mac-ecc"; + reg = <0xff8c0400 0x100>; + altr,ecc-parent = <&gmac0>; + interrupts = <5 IRQ_TYPE_LEVEL_HIGH>' + }; + + nand-buf-ecc@ff8c8000 { + compatible = "altr,socfpga-s10-nand-ecc"; + reg = <0xff8c8000 0x100>; + altr,ecc-parent = <&nand>; + interrupts = <11 IRQ_TYPE_LEVEL_HIGH>; + }; + + nand-rd-ecc@ff8c8400 { + compatible = "altr,socfpga-s10-nand-ecc"; + reg = <0xff8c8400 0x100>; + altr,ecc-parent = <&nand>; + interrupts = <13 IRQ_TYPE_LEVEL_HIGH>; + }; + + nand-wr-ecc@ff8c8800 { + compatible = "altr,socfpga-s10-nand-ecc"; + reg = <0xff8c8800 0x100>; + altr,ecc-parent = <&nand>; + interrupts = <12 IRQ_TYPE_LEVEL_HIGH>; + }; + + dma-ecc@ff8c9000 { + compatible = "altr,socfpga-s10-dma-ecc"; + reg = <0xff8c9000 0x100>; + altr,ecc-parent = <&pdma>; + interrupts = <10 IRQ_TYPE_LEVEL_HIGH>; + + usb0-ecc@ff8c4000 { + compatible = "altr,socfpga-s10-usb-ecc"; + reg = <0xff8c4000 0x100>; + altr,ecc-parent = <&usb0>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + }; + + sdmmc-ecc@ff8c8c00 { + compatible = "altr,socfpga-s10-sdmmc-ecc"; + reg = <0xff8c8c00 0x100>; + altr,ecc-parent = <&mmc>; + interrupts = <14 IRQ_TYPE_LEVEL_HIGH>, + <15 IRQ_TYPE_LEVEL_HIGH>; }; }; diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index 0e456bbc1213..22aead844d0f 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -50,6 +50,7 @@ Required properties: "nxp,se97b" - the fallback is "atmel,24c02", "renesas,r1ex24002" - the fallback is "atmel,24c02" + "renesas,r1ex24016" - the fallback is "atmel,24c16" "renesas,r1ex24128" - the fallback is "atmel,24c128" "rohm,br24t01" - the fallback is "atmel,24c01" diff --git a/Documentation/devicetree/bindings/fieldbus/arcx,anybus-controller.txt b/Documentation/devicetree/bindings/fieldbus/arcx,anybus-controller.txt new file mode 100644 index 000000000000..b1f9474f36d5 --- /dev/null +++ b/Documentation/devicetree/bindings/fieldbus/arcx,anybus-controller.txt @@ -0,0 +1,71 @@ +* Arcx Anybus-S controller + +This chip communicates with the SoC over a parallel bus. It is +expected that its Device Tree node is specified as the child of a node +corresponding to the parallel bus used for communication. + +Required properties: +-------------------- + + - compatible : The following chip-specific string: + "arcx,anybus-controller" + + - reg : three areas: + index 0: bus memory area where the cpld registers are located. + index 1: bus memory area of the first host's dual-port ram. + index 2: bus memory area of the second host's dual-port ram. + + - reset-gpios : the GPIO pin connected to the reset line of the controller. + + - interrupts : two interrupts: + index 0: interrupt connected to the first host + index 1: interrupt connected to the second host + Generic interrupt client node bindings are described in + interrupt-controller/interrupts.txt + +Optional: use of subnodes +------------------------- + +The card connected to a host may need additional properties. These can be +specified in subnodes to the controller node. + +The subnodes are identified by the standard 'reg' property. Which information +exactly can be specified depends on the bindings for the function driver +for the subnode. + +Required controller node properties when using subnodes: +- #address-cells: should be one. +- #size-cells: should be zero. + +Required subnode properties: +- reg: Must contain the host index of the card this subnode describes: + <0> for the first host on the controller + <1> for the second host on the controller + Note that only a single card can be plugged into a host, so the host + index uniquely describes the card location. + +Example of usage: +----------------- + +This example places the bridge on top of the i.MX WEIM parallel bus, see: +Documentation/devicetree/bindings/bus/imx-weim.txt + +&weim { + controller@0,0 { + compatible = "arcx,anybus-controller"; + reg = <0 0 0x100>, <0 0x400000 0x800>, <1 0x400000 0x800>; + reset-gpios = <&gpio5 2 GPIO_ACTIVE_HIGH>; + interrupt-parent = <&gpio1>; + interrupts = <1 IRQ_TYPE_LEVEL_LOW>, <5 IRQ_TYPE_LEVEL_LOW>; + /* fsl,weim-cs-timing is a i.MX WEIM bus specific property */ + fsl,weim-cs-timing = <0x024400b1 0x00001010 0x20081100 + 0x00000000 0xa0000240 0x00000000>; + /* optional subnode for a card plugged into the first host */ + #address-cells = <1>; + #size-cells = <0>; + card@0 { + reg = <0>; + /* card specific properties go here */ + }; + }; +}; diff --git a/Documentation/devicetree/bindings/gnss/u-blox.txt b/Documentation/devicetree/bindings/gnss/u-blox.txt index e475659cb85f..7cdefd058fe0 100644 --- a/Documentation/devicetree/bindings/gnss/u-blox.txt +++ b/Documentation/devicetree/bindings/gnss/u-blox.txt @@ -9,6 +9,7 @@ Required properties: - compatible : Must be one of + "u-blox,neo-6m" "u-blox,neo-8" "u-blox,neo-m8" diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index fb144e2b6522..dab537c20def 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -2,6 +2,7 @@ Required properties: - compatible: Has to contain one of the following: + nxp,pca6416 nxp,pca9505 nxp,pca9534 nxp,pca9535 @@ -30,6 +31,7 @@ Required properties: ti,tca6424 ti,tca9539 ti,tca9554 + onnn,cat9554 onnn,pca9654 exar,xra1202 - gpio-controller: if used as gpio expander. diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.txt b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.txt new file mode 100644 index 000000000000..b8be9dbc68b4 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.txt @@ -0,0 +1,92 @@ +ARM Mali Bifrost GPU +==================== + +Required properties: + +- compatible : + * Since Mali Bifrost GPU model/revision is fully discoverable by reading + some determined registers, must contain the following: + + "arm,mali-bifrost" + * which must be preceded by one of the following vendor specifics: + + "amlogic,meson-g12a-mali" + +- reg : Physical base address of the device and length of the register area. + +- interrupts : Contains the three IRQ lines required by Mali Bifrost devices, + in the following defined order. + +- interrupt-names : Contains the names of IRQ resources in this exact defined + order: "job", "mmu", "gpu". + +Optional properties: + +- clocks : Phandle to clock for the Mali Bifrost device. + +- mali-supply : Phandle to regulator for the Mali device. Refer to + Documentation/devicetree/bindings/regulator/regulator.txt for details. + +- operating-points-v2 : Refer to Documentation/devicetree/bindings/opp/opp.txt + for details. + +- resets : Phandle of the GPU reset line. + +Vendor-specific bindings +------------------------ + +The Mali GPU is integrated very differently from one SoC to +another. In order to accommodate those differences, you have the option +to specify one more vendor-specific compatible, among: + +- "amlogic,meson-g12a-mali" + Required properties: + - resets : Should contain phandles of : + + GPU reset line + + GPU APB glue reset line + +Example for a Mali-G31: + +gpu@ffa30000 { + compatible = "amlogic,meson-g12a-mali", "arm,mali-bifrost"; + reg = <0xffe40000 0x10000>; + interrupts = <GIC_SPI 160 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 161 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 162 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "job", "mmu", "gpu"; + clocks = <&clk CLKID_MALI>; + mali-supply = <&vdd_gpu>; + operating-points-v2 = <&gpu_opp_table>; + resets = <&reset RESET_DVALIN_CAPB3>, <&reset RESET_DVALIN>; +}; + +gpu_opp_table: opp_table0 { + compatible = "operating-points-v2"; + + opp@533000000 { + opp-hz = /bits/ 64 <533000000>; + opp-microvolt = <1250000>; + }; + opp@450000000 { + opp-hz = /bits/ 64 <450000000>; + opp-microvolt = <1150000>; + }; + opp@400000000 { + opp-hz = /bits/ 64 <400000000>; + opp-microvolt = <1125000>; + }; + opp@350000000 { + opp-hz = /bits/ 64 <350000000>; + opp-microvolt = <1075000>; + }; + opp@266000000 { + opp-hz = /bits/ 64 <266000000>; + opp-microvolt = <1025000>; + }; + opp@160000000 { + opp-hz = /bits/ 64 <160000000>; + opp-microvolt = <925000>; + }; + opp@100000000 { + opp-hz = /bits/ 64 <100000000>; + opp-microvolt = <912500>; + }; +}; diff --git a/Documentation/devicetree/bindings/gpu/aspeed-gfx.txt b/Documentation/devicetree/bindings/gpu/aspeed-gfx.txt new file mode 100644 index 000000000000..958bdf962339 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/aspeed-gfx.txt @@ -0,0 +1,41 @@ +Device tree configuration for the GFX display device on the ASPEED SoCs + +Required properties: + - compatible + * Must be one of the following: + + aspeed,ast2500-gfx + + aspeed,ast2400-gfx + * In addition, the ASPEED pinctrl bindings require the 'syscon' property to + be present + + - reg: Physical base address and length of the GFX registers + + - interrupts: interrupt number for the GFX device + + - clocks: clock number used to generate the pixel clock + + - resets: reset line that must be released to use the GFX device + + - memory-region: + Phandle to a memory region to allocate from, as defined in + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt + + +Example: + +gfx: display@1e6e6000 { + compatible = "aspeed,ast2500-gfx", "syscon"; + reg = <0x1e6e6000 0x1000>; + reg-io-width = <4>; + clocks = <&syscon ASPEED_CLK_GATE_D1CLK>; + resets = <&syscon ASPEED_RESET_CRT1>; + interrupts = <0x19>; + memory-region = <&gfx_memory>; +}; + +gfx_memory: framebuffer { + size = <0x01000000>; + alignment = <0x01000000>; + compatible = "shared-dma-pool"; + reusable; +}; diff --git a/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.txt b/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.txt index c907aa8dd755..b2df82b44625 100644 --- a/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.txt +++ b/Documentation/devicetree/bindings/gpu/brcm,bcm-v3d.txt @@ -6,15 +6,20 @@ For V3D 2.x, see brcm,bcm-vc4.txt. Required properties: - compatible: Should be "brcm,7268-v3d" or "brcm,7278-v3d" - reg: Physical base addresses and lengths of the register areas -- reg-names: Names for the register areas. The "hub", "bridge", and "core0" +- reg-names: Names for the register areas. The "hub" and "core0" register areas are always required. The "gca" register area - is required if the GCA cache controller is present. + is required if the GCA cache controller is present. The + "bridge" register area is required if an external reset + controller is not present. - interrupts: The interrupt numbers. The first interrupt is for the hub, - while the following interrupts are for the cores. + while the following interrupts are separate interrupt lines + for the cores (if they don't share the hub's interrupt). See bindings/interrupt-controller/interrupts.txt Optional properties: - clocks: The core clock the unit runs on +- resets: The reset line for v3d, if not using a mapping of the bridge + See bindings/reset/reset.txt v3d { compatible = "brcm,7268-v3d"; diff --git a/Documentation/devicetree/bindings/hwmon/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/hwmon/cirrus,lochnagar.txt new file mode 100644 index 000000000000..ffb79ccf51ee --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/cirrus,lochnagar.txt @@ -0,0 +1,26 @@ +Cirrus Logic Lochnagar Audio Development Board + +Lochnagar is an evaluation and development board for Cirrus Logic +Smart CODEC and Amp devices. It allows the connection of most Cirrus +Logic devices on mini-cards, as well as allowing connection of +various application processor systems to provide a full evaluation +platform. Audio system topology, clocking and power can all be +controlled through the Lochnagar, allowing the device under test +to be used in a variety of possible use cases. + +This binding document describes the binding for the hardware monitor +portion of the driver. + +This binding must be part of the Lochnagar MFD binding: + [4] ../mfd/cirrus,lochnagar.txt + +Required properties: + + - compatible : One of the following strings: + "cirrus,lochnagar2-hwmon" + +Example: + +lochnagar-hwmon { + compatible = "cirrus,lochnagar2-hwmon"; +}; diff --git a/Documentation/devicetree/bindings/hwmon/g762.txt b/Documentation/devicetree/bindings/hwmon/g762.txt index 25cc6d8ee575..6d154c4923de 100644 --- a/Documentation/devicetree/bindings/hwmon/g762.txt +++ b/Documentation/devicetree/bindings/hwmon/g762.txt @@ -21,7 +21,7 @@ If an optional property is not set in .dts file, then current value is kept unmodified (e.g. u-boot installed value). Additional information on operational parameters for the device is available -in Documentation/hwmon/g762. A detailed datasheet for the device is available +in Documentation/hwmon/g762.rst. A detailed datasheet for the device is available at http://natisbad.org/NAS/refs/GMT_EDS-762_763-080710-0.2.pdf. Example g762 node: diff --git a/Documentation/devicetree/bindings/hwmon/lm75.txt b/Documentation/devicetree/bindings/hwmon/lm75.txt index 12d8cf7cf592..586b5ed70be7 100644 --- a/Documentation/devicetree/bindings/hwmon/lm75.txt +++ b/Documentation/devicetree/bindings/hwmon/lm75.txt @@ -25,6 +25,7 @@ Required properties: "ti,tmp175", "ti,tmp275", "ti,tmp75", + "ti,tmp75b", "ti,tmp75c", - reg: I2C bus address of the device diff --git a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt b/Documentation/devicetree/bindings/hwmon/pwm-fan.txt index 49ca5d83ed13..6ced829b0e58 100644 --- a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/pwm-fan.txt @@ -7,7 +7,16 @@ Required properties: which correspond to thermal cooling states Optional properties: -- fan-supply : phandle to the regulator that provides power to the fan +- fan-supply : phandle to the regulator that provides power to the fan +- interrupts : This contains a single interrupt specifier which + describes the tachometer output of the fan as an + interrupt source. The output signal must generate a + defined number of interrupts per fan revolution, which + require that it must be self resetting edge interrupts. + See interrupt-controller/interrupts.txt for the format. +- pulses-per-revolution : define the tachometer pulses per fan revolution as + an integer (default is 2 interrupts per revolution). + The value must be greater than zero. Example: fan0: pwm-fan { @@ -38,3 +47,13 @@ Example: }; }; }; + +Example 2: + fan0: pwm-fan { + compatible = "pwm-fan"; + pwms = <&pwm 0 40000 0>; + fan-supply = <®_fan>; + interrupt-parent = <&gpio5>; + interrupts = <1 IRQ_TYPE_EDGE_FALLING>; + pulses-per-revolution = <2>; + }; diff --git a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt index 81f982ccca31..d12cc33cca6c 100644 --- a/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt +++ b/Documentation/devicetree/bindings/i2c/brcm,iproc-i2c.txt @@ -3,15 +3,12 @@ Broadcom iProc I2C controller Required properties: - compatible: - Must be "brcm,iproc-i2c" + Must be "brcm,iproc-i2c" or "brcm,iproc-nic-i2c" - reg: Define the base and range of the I/O address space that contain the iProc I2C controller registers -- interrupts: - Should contain the I2C interrupt - - clock-frequency: This is the I2C bus clock. Need to be either 100000 or 400000 @@ -21,6 +18,18 @@ Required properties: - #size-cells: Always 0 +Optional properties: + +- interrupts: + Should contain the I2C interrupt. For certain revisions of the I2C + controller, I2C interrupt is unwired to the interrupt controller. In such + case, this property should be left unspecified, and driver will fall back + to polling mode + +- brcm,ape-hsls-addr-mask: + Required for "brcm,iproc-nic-i2c". Host view of address mask into the + 'APE' co-processor. Value must be unsigned, 32-bit + Example: i2c0: i2c@18008000 { compatible = "brcm,iproc-i2c"; diff --git a/Documentation/devicetree/bindings/i2c/i2c-designware.txt b/Documentation/devicetree/bindings/i2c/i2c-designware.txt index 3e4bcc2fb6f7..08be4d3846e5 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-designware.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-designware.txt @@ -6,12 +6,21 @@ Required properties : or "mscc,ocelot-i2c" with "snps,designware-i2c" for fallback - reg : Offset and length of the register set for the device - interrupts : <IRQ> where IRQ is the interrupt number. + - clocks : phandles for the clocks, see the description of clock-names below. + The phandle for the "ic_clk" clock is required. The phandle for the "pclk" + clock is optional. If a single clock is specified but no clock-name, it is + the "ic_clk" clock. If both clocks are listed, the "ic_clk" must be first. Recommended properties : - clock-frequency : desired I2C bus clock frequency in Hz. Optional properties : + + - clock-names : Contains the names of the clocks: + "ic_clk", for the core clock used to generate the external I2C clock. + "pclk", the interface clock, required for register access. + - reg : for "mscc,ocelot-i2c", a second register set to configure the SDA hold time, named ICPU_CFG:TWI_DELAY in the datasheet. diff --git a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt index ee4c32454198..68f6d73a8b73 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mt65xx.txt @@ -12,13 +12,16 @@ Required properties: "mediatek,mt7623-i2c", "mediatek,mt6577-i2c": for MediaTek MT7623 "mediatek,mt7629-i2c", "mediatek,mt2712-i2c": for MediaTek MT7629 "mediatek,mt8173-i2c": for MediaTek MT8173 + "mediatek,mt8183-i2c": for MediaTek MT8183 + "mediatek,mt8516-i2c", "mediatek,mt2712-i2c": for MediaTek MT8516 - reg: physical base address of the controller and dma base, length of memory mapped region. - interrupts: interrupt number to the cpu. - clock-div: the fixed value for frequency divider of clock source in i2c module. Each IC may be different. - clocks: clock name from clock manager - - clock-names: Must include "main" and "dma", if enable have-pmic need include + - clock-names: Must include "main" and "dma", "arb" is for multi-master that + one bus has more than two i2c controllers, if enable have-pmic need include "pmic" extra. Optional properties: diff --git a/Documentation/devicetree/bindings/i2c/i2c-riic.txt b/Documentation/devicetree/bindings/i2c/i2c-riic.txt index 0bcc4716c319..e26fe3ad86a9 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-riic.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-riic.txt @@ -1,7 +1,10 @@ Device tree configuration for Renesas RIIC driver Required properties: -- compatible : "renesas,riic-<soctype>". "renesas,riic-rz" as fallback +- compatible : + "renesas,riic-r7s72100" if the device is a part of a R7S72100 SoC. + "renesas,riic-r7s9210" if the device is a part of a R7S9210 SoC. + "renesas,riic-rz" for a generic RZ/A compatible device. - reg : address start and address range size of device - interrupts : 8 interrupts (TEI, RI, TI, SPI, STI, NAKI, ALI, TMOI) - clock-frequency : frequency of bus clock in Hz diff --git a/Documentation/devicetree/bindings/i2c/i2c-stm32.txt b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt index 69240e189b01..f334738f7a35 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-stm32.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt @@ -1,11 +1,11 @@ * I2C controller embedded in STMicroelectronics STM32 I2C platform -Required properties : -- compatible : Must be one of the following +Required properties: +- compatible: Must be one of the following - "st,stm32f4-i2c" - "st,stm32f7-i2c" -- reg : Offset and length of the register set for the device -- interrupts : Must contain the interrupt id for I2C event and then the +- reg: Offset and length of the register set for the device +- interrupts: Must contain the interrupt id for I2C event and then the interrupt id for I2C error. - resets: Must contain the phandle to the reset controller. - clocks: Must contain the input clock of the I2C instance. @@ -14,25 +14,26 @@ Required properties : - #address-cells = <1>; - #size-cells = <0>; -Optional properties : -- clock-frequency : Desired I2C bus clock frequency in Hz. If not specified, +Optional properties: +- clock-frequency: Desired I2C bus clock frequency in Hz. If not specified, the default 100 kHz frequency will be used. For STM32F4 SoC Standard-mode and Fast-mode are supported, possible values are 100000 and 400000. - For STM32F7 SoC, Standard-mode, Fast-mode and Fast-mode Plus are supported, - possible values are 100000, 400000 and 1000000. -- i2c-scl-rising-time-ns : Only for STM32F7, I2C SCL Rising time for the board - (default: 25) -- i2c-scl-falling-time-ns : Only for STM32F7, I2C SCL Falling time for the board - (default: 10) + For STM32F7, STM32H7 and STM32MP1 SoCs, Standard-mode, Fast-mode and Fast-mode + Plus are supported, possible values are 100000, 400000 and 1000000. +- i2c-scl-rising-time-ns: I2C SCL Rising time for the board (default: 25) + For STM32F7, STM32H7 and STM32MP1 only. +- i2c-scl-falling-time-ns: I2C SCL Falling time for the board (default: 10) + For STM32F7, STM32H7 and STM32MP1 only. I2C Timings are derived from these 2 values -- st,syscfg-fmp: Only for STM32F7, use to set Fast Mode Plus bit within SYSCFG - whether Fast Mode Plus speed is selected by slave. - 1st cell : phandle to syscfg - 2nd cell : register offset within SYSCFG - 3rd cell : register bitmask for FMP bit +- st,syscfg-fmp: Use to set Fast Mode Plus bit within SYSCFG when Fast Mode + Plus speed is selected by slave. + 1st cell: phandle to syscfg + 2nd cell: register offset within SYSCFG + 3rd cell: register bitmask for FMP bit + For STM32F7, STM32H7 and STM32MP1 only. -Example : +Example: i2c@40005400 { compatible = "st,stm32f4-i2c"; diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt new file mode 100644 index 000000000000..eb76a02e2a82 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt @@ -0,0 +1,17 @@ +Kionix KXCJK-1013 Accelerometer device tree bindings + +Required properties: + +- compatible: Must be one of: + "kionix,kxcjk1013" + "kionix,kxcj91008" + "kionix,kxtj21009" + "kionix,kxtf9" + - reg: i2c slave address + +Example: + +kxtf9@f { + compatible = "kionix,kxtf9"; + reg = <0x0F>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt index d7b6241ca881..d8652460198e 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt @@ -7,6 +7,7 @@ Required properties for the AD7606: * "adi,ad7606-8" * "adi,ad7606-6" * "adi,ad7606-4" + * "adi,ad7616" - reg: SPI chip select number for the device - spi-max-frequency: Max SPI frequency to use see: Documentation/devicetree/bindings/spi/spi-bus.txt diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7780.txt b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.txt new file mode 100644 index 000000000000..440e52555349 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.txt @@ -0,0 +1,48 @@ +* Analog Devices AD7170/AD7171/AD7780/AD7781 + +Data sheets: + +- AD7170: + * https://www.analog.com/media/en/technical-documentation/data-sheets/AD7170.pdf +- AD7171: + * https://www.analog.com/media/en/technical-documentation/data-sheets/AD7171.pdf +- AD7780: + * https://www.analog.com/media/en/technical-documentation/data-sheets/ad7780.pdf +- AD7781: + * https://www.analog.com/media/en/technical-documentation/data-sheets/AD7781.pdf + +Required properties: + +- compatible: should be one of + * "adi,ad7170" + * "adi,ad7171" + * "adi,ad7780" + * "adi,ad7781" +- reg: spi chip select number for the device +- vref-supply: the regulator supply for the ADC reference voltage + +Optional properties: + +- powerdown-gpios: must be the device tree identifier of the PDRST pin. If + specified, it will be asserted during driver probe. As the + line is active high, it should be marked GPIO_ACTIVE_HIGH. +- adi,gain-gpios: must be the device tree identifier of the GAIN pin. Only for + the ad778x chips. If specified, it will be asserted during + driver probe. As the line is active low, it should be marked + GPIO_ACTIVE_LOW. +- adi,filter-gpios: must be the device tree identifier of the FILTER pin. Only + for the ad778x chips. If specified, it will be asserted + during driver probe. As the line is active low, it should be + marked GPIO_ACTIVE_LOW. + +Example: + +adc@0 { + compatible = "adi,ad7780"; + reg = <0>; + vref-supply = <&vdd_supply> + + powerdown-gpios = <&gpio 12 GPIO_ACTIVE_HIGH>; + adi,gain-gpios = <&gpio 5 GPIO_ACTIVE_LOW>; + adi,filter-gpios = <&gpio 15 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt index 75c775954102..d57e9df25f4f 100644 --- a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt +++ b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt @@ -9,6 +9,7 @@ Required properties: - "amlogic,meson-gxl-saradc" for GXL - "amlogic,meson-gxm-saradc" for GXM - "amlogic,meson-axg-saradc" for AXG + - "amlogic,meson-g12a-saradc" for AXG along with the generic "amlogic,meson-saradc" - reg: the physical base address and length of the registers - interrupts: the interrupt indicating end of sampling diff --git a/Documentation/devicetree/bindings/iio/adc/avia-hx711.txt b/Documentation/devicetree/bindings/iio/adc/avia-hx711.txt deleted file mode 100644 index 7222328a3d0d..000000000000 --- a/Documentation/devicetree/bindings/iio/adc/avia-hx711.txt +++ /dev/null @@ -1,24 +0,0 @@ -* AVIA HX711 ADC chip for weight cells - Bit-banging driver - -Required properties: - - compatible: Should be "avia,hx711" - - sck-gpios: Definition of the GPIO for the clock - - dout-gpios: Definition of the GPIO for data-out - See Documentation/devicetree/bindings/gpio/gpio.txt - - avdd-supply: Definition of the regulator used as analog supply - -Optional properties: - - clock-frequency: Frequency of PD_SCK in Hz - Minimum value allowed is 10 kHz because of maximum - high time of 50 microseconds. - -Example: -weight { - compatible = "avia,hx711"; - sck-gpios = <&gpio3 10 GPIO_ACTIVE_HIGH>; - dout-gpios = <&gpio0 7 GPIO_ACTIVE_HIGH>; - avdd-suppy = <&avdd>; - clock-frequency = <100000>; -}; - diff --git a/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml new file mode 100644 index 000000000000..8a4100ceeaf2 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/avia-hx711.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/iio/adc/avia-hx711.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: AVIA HX711 ADC chip for weight cells + +maintainers: + - Andreas Klinger <ak@it-klinger.de> + +description: | + Bit-banging driver using two GPIOs: + - sck-gpio gives a clock to the sensor with 24 cycles for data retrieval + and up to 3 cycles for selection of the input channel and gain for the + next measurement + - dout-gpio is the sensor data the sensor responds to the clock + + Specifications about the driver can be found at: + http://www.aviaic.com/ENProducts.aspx + +properties: + compatible: + enum: + - avia,hx711 + + sck-gpios: + description: + Definition of the GPIO for the clock (output). In the datasheet it is + named PD_SCK + maxItems: 1 + + dout-gpios: + description: + Definition of the GPIO for the data-out sent by the sensor in + response to the clock (input). + See Documentation/devicetree/bindings/gpio/gpio.txt for information + on how to specify a consumer gpio. + maxItems: 1 + + avdd-supply: + description: + Definition of the regulator used as analog supply + maxItems: 1 + + clock-frequency: + minimum: 20000 + maximum: 2500000 + default: 400000 + +required: + - compatible + - sck-gpios + - dout-gpios + - avdd-supply + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + weight { + compatible = "avia,hx711"; + sck-gpios = <&gpio3 10 GPIO_ACTIVE_HIGH>; + dout-gpios = <&gpio0 7 GPIO_ACTIVE_HIGH>; + avdd-suppy = <&avdd>; + clock-frequency = <100000>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/lpc32xx-adc.txt b/Documentation/devicetree/bindings/iio/adc/lpc32xx-adc.txt index b3629d3a9adf..3a1bc669bd51 100644 --- a/Documentation/devicetree/bindings/iio/adc/lpc32xx-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/lpc32xx-adc.txt @@ -6,6 +6,10 @@ Required properties: region. - interrupts: The ADC interrupt +Optional: + - vref-supply: The regulator supply ADC reference voltage, optional + for legacy reason, but highly encouraging to us in new device tree + Example: adc@40048000 { @@ -13,4 +17,5 @@ Example: reg = <0x40048000 0x1000>; interrupt-parent = <&mic>; interrupts = <39 0>; + vref-supply = <&vcc>; }; diff --git a/Documentation/devicetree/bindings/iio/adc/ti-ads8344.txt b/Documentation/devicetree/bindings/iio/adc/ti-ads8344.txt new file mode 100644 index 000000000000..e47c3759a82b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti-ads8344.txt @@ -0,0 +1,19 @@ +* Texas Instruments ADS8344 A/DC chip + +Required properties: + - compatible: Must be "ti,ads8344" + - reg: SPI chip select number for the device + - vref-supply: phandle to a regulator node that supplies the + reference voltage + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Example: +adc@0 { + compatible = "ti,ads8344"; + reg = <0>; + vref-supply = <&refin_supply>; + spi-max-frequency = <10000000>; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt index 7b5f06f324c8..c52ea2126eaa 100644 --- a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt +++ b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt @@ -1,7 +1,13 @@ * Plantower PMS7003 particulate matter sensor Required properties: -- compatible: must be "plantower,pms7003" +- compatible: must one of: + "plantower,pms1003" + "plantower,pms3003" + "plantower,pms5003" + "plantower,pms6003" + "plantower,pms7003" + "plantower,pmsa003" - vcc-supply: phandle to the regulator that provides power to the sensor Optional properties: diff --git a/Documentation/devicetree/bindings/iio/gyroscope/bmg160.txt b/Documentation/devicetree/bindings/iio/gyroscope/bmg160.txt new file mode 100644 index 000000000000..78e18a1e9c1d --- /dev/null +++ b/Documentation/devicetree/bindings/iio/gyroscope/bmg160.txt @@ -0,0 +1,20 @@ +* Bosch BMG160 triaxial rotation sensor (gyroscope) + +Required properties: + + - compatible : should be "bosch,bmg160" or "bosch,bmi055_gyro" + - reg : the I2C address of the sensor (0x69) + +Optional properties: + + - interrupts : interrupt mapping for GPIO IRQ, it should by configured with + flags IRQ_TYPE_EDGE_RISING + +Example: + +bmg160@69 { + compatible = "bosch,bmg160"; + reg = <0x69>; + interrupt-parent = <&gpio6>; + interrupts = <18 (IRQ_TYPE_EDGE_RISING)>; +}; diff --git a/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.txt b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.txt new file mode 100644 index 000000000000..465e104bbf14 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/gyroscope/nxp,fxas21002c.txt @@ -0,0 +1,31 @@ +* NXP FXAS21002C Gyroscope device tree bindings + +http://www.nxp.com/products/sensors/gyroscopes/3-axis-digital-gyroscope:FXAS21002C + +Required properties: + - compatible : should be "nxp,fxas21002c" + - reg : the I2C address of the sensor or SPI chip select number for the + device. + - vdd-supply: phandle to the regulator that provides power to the sensor. + - vddio-supply: phandle to the regulator that provides power to the bus. + +Optional properties: + - reset-gpios : gpio used to reset the device, see gpio/gpio.txt + - interrupts : device support 2 interrupts, INT1 and INT2, + the interrupts can be triggered on rising or falling edges. + See interrupt-controller/interrupts.txt + - interrupt-names: should contain "INT1" or "INT2", the gyroscope interrupt + line in use. + - drive-open-drain: the interrupt/data ready line will be configured + as open drain, which is useful if several sensors share + the same interrupt line. This is a boolean property. + (This binding is taken from pinctrl/pinctrl-bindings.txt) + +Example: + +gyroscope@20 { + compatible = "nxp,fxas21002c"; + reg = <0x20>; + vdd-supply = <®_peri_3p15v>; + vddio-supply = <®_peri_3p15v>; +}; diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt new file mode 100644 index 000000000000..ed7783f45233 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt @@ -0,0 +1,85 @@ + +Analog Devices ADIS16480 and similar IMUs + +Required properties for the ADIS16480: + +- compatible: Must be one of + * "adi,adis16375" + * "adi,adis16480" + * "adi,adis16485" + * "adi,adis16488" + * "adi,adis16495-1" + * "adi,adis16495-2" + * "adi,adis16495-3" + * "adi,adis16497-1" + * "adi,adis16497-2" + * "adi,adis16497-3" +- reg: SPI chip select number for the device +- spi-max-frequency: Max SPI frequency to use + see: Documentation/devicetree/bindings/spi/spi-bus.txt +- spi-cpha: See Documentation/devicetree/bindings/spi/spi-bus.txt +- spi-cpol: See Documentation/devicetree/bindings/spi/spi-bus.txt +- interrupts: interrupt mapping for IRQ, accepted values are: + * IRQF_TRIGGER_RISING + * IRQF_TRIGGER_FALLING + +Optional properties: + +- interrupt-names: Data ready line selection. Valid values are: + * DIO1 + * DIO2 + * DIO3 + * DIO4 + If this field is left empty, DIO1 is assigned as default data ready + signal. +- reset-gpios: must be the device tree identifier of the RESET pin. As the line + is active low, it should be marked GPIO_ACTIVE_LOW. +- clocks: phandle to the external clock. Should be set according to + "clock-names". + If this field is left empty together with the "clock-names" field, then + the internal clock is used. +- clock-names: The name of the external clock to be used. Valid values are: + * sync: In sync mode, the internal clock is disabled and the frequency + of the external clock signal establishes therate of data + collection and processing. See Fig 14 and 15 in the datasheet. + The clock-frequency must be: + * 3000 to 4500 Hz for adis1649x devices. + * 700 to 2400 Hz for adis1648x devices. + * pps: In Pulse Per Second (PPS) Mode, the rate of data collection and + production is equal to the product of the external clock + frequency and the scale factor in the SYNC_SCALE register, see + Table 154 in the datasheet. + The clock-frequency must be: + * 1 to 128 Hz for adis1649x devices. + * This mode is not supported by adis1648x devices. + If this field is left empty together with the "clocks" field, then the + internal clock is used. +- adi,ext-clk-pin: The DIOx line to be used as an external clock input. + Valid values are: + * DIO1 + * DIO2 + * DIO3 + * DIO4 + Each DIOx pin supports only one function at a time (data ready line + selection or external clock input). When a single pin has two + two assignments, the enable bit for the lower priority function + automatically resets to zero (disabling the lower priority function). + Data ready has highest priority. + If this field is left empty, DIO2 is assigned as default external clock + input pin. + +Example: + + imu@0 { + compatible = "adi,adis16495-1"; + reg = <0>; + spi-max-frequency = <3200000>; + spi-cpol; + spi-cpha; + interrupts = <25 IRQF_TRIGGER_FALLING>; + interrupt-parent = <&gpio>; + interrupt-names = "DIO2"; + clocks = <&adis16495_sync>; + clock-names = "sync"; + adi,ext-clk-pin = "DIO1"; + }; diff --git a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt index 69d53d98d0f0..efec9ece034a 100644 --- a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt +++ b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt @@ -8,6 +8,9 @@ Required properties: "st,lsm6dsm" "st,ism330dlc" "st,lsm6dso" + "st,asm330lhh" + "st,lsm6dsox" + "st,lsm6dsr" - reg: i2c address of the sensor / spi cs line Optional properties: diff --git a/Documentation/devicetree/bindings/iio/light/vcnl4000.txt b/Documentation/devicetree/bindings/iio/light/vcnl4000.txt new file mode 100644 index 000000000000..955af4555c90 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/vcnl4000.txt @@ -0,0 +1,24 @@ +VISHAY VCNL4000 - Ambient Light and proximity sensor + +This driver supports the VCNL4000/10/20/40 and VCNL4200 chips + +Required properties: + + -compatible: must be one of : + vishay,vcnl4000 + vishay,vcnl4010 + vishay,vcnl4020 + vishay,vcnl4040 + vishay,vcnl4200 + + -reg: I2C address of the sensor, should be one from below based on the model: + 0x13 + 0x51 + 0x60 + +Example: + +light-sensor@51 { + compatible = "vishay,vcnl4200"; + reg = <0x51>; +}; diff --git a/Documentation/devicetree/bindings/iio/pressure/bmp085.txt b/Documentation/devicetree/bindings/iio/pressure/bmp085.txt deleted file mode 100644 index 61c72e63c584..000000000000 --- a/Documentation/devicetree/bindings/iio/pressure/bmp085.txt +++ /dev/null @@ -1,27 +0,0 @@ -BMP085/BMP18x/BMP28x digital pressure sensors - -Required properties: -- compatible: must be one of: - "bosch,bmp085" - "bosch,bmp180" - "bosch,bmp280" - "bosch,bme280" - -Optional properties: -- interrupts: interrupt mapping for IRQ -- reset-gpios: a GPIO line handling reset of the sensor: as the line is - active low, it should be marked GPIO_ACTIVE_LOW (see gpio/gpio.txt) -- vddd-supply: digital voltage regulator (see regulator/regulator.txt) -- vdda-supply: analog voltage regulator (see regulator/regulator.txt) - -Example: - -pressure@77 { - compatible = "bosch,bmp085"; - reg = <0x77>; - interrupt-parent = <&gpio0>; - interrupts = <25 IRQ_TYPE_EDGE_RISING>; - reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>; - vddd-supply = <&foo>; - vdda-supply = <&bar>; -}; diff --git a/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml new file mode 100644 index 000000000000..c6721a7e8938 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/pressure/bmp085.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: BMP085/BMP180/BMP280/BME280 pressure iio sensors + +maintainers: + - Andreas Klinger <ak@it-klinger.de> + +description: | + Pressure, temperature and humidity iio sensors with i2c and spi interfaces + + Specifications about the sensor can be found at: + https://www.bosch-sensortec.com/bst/products/all_products/bmp180 + https://www.bosch-sensortec.com/bst/products/all_products/bmp280 + https://www.bosch-sensortec.com/bst/products/all_products/bme280 + +properties: + compatible: + enum: + - bosch,bmp085 + - bosch,bmp180 + - bosch,bmp280 + - bosch,bme280 + + vddd-supply: + description: + digital voltage regulator (see regulator/regulator.txt) + maxItems: 1 + + vdda-supply: + description: + analog voltage regulator (see regulator/regulator.txt) + maxItems: 1 + + reset-gpios: + description: + A GPIO line handling reset of the sensor. As the line is active low, + it should be marked GPIO_ACTIVE_LOW (see gpio/gpio.txt) + maxItems: 1 + + interrupts: + description: + interrupt mapping for IRQ (BMP085 only) + maxItems: 1 + +required: + - compatible + - vddd-supply + - vdda-supply + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + pressure@77 { + compatible = "bosch,bmp085"; + reg = <0x77>; + interrupt-parent = <&gpio0>; + interrupts = <25 IRQ_TYPE_EDGE_RISING>; + reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>; + vddd-supply = <&foo>; + vdda-supply = <&bar>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.txt b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.txt deleted file mode 100644 index d4dc7a227e2e..000000000000 --- a/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.txt +++ /dev/null @@ -1,28 +0,0 @@ -* 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/iio/proximity/devantech-srf04.yaml b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml new file mode 100644 index 000000000000..4e80ea7c1475 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/devantech-srf04.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/proximity/devantech-srf04.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Devantech SRF04 and Maxbotix mb1000 ultrasonic range finder + +maintainers: + - Andreas Klinger <ak@it-klinger.de> + +description: | + Bit-banging driver using two GPIOs: + - trigger-gpio is raised by the driver to start sending out an ultrasonic + burst + - echo-gpio is held high by the sensor after sending ultrasonic burst + until it is received once again + + Specifications about the devices can be found at: + http://www.robot-electronics.co.uk/htm/srf04tech.htm + + http://www.maxbotix.com/documents/LV-MaxSonar-EZ_Datasheet.pdf + +properties: + compatible: + enum: + - devantech,srf04 + - maxbotix,mb1000 + - maxbotix,mb1010 + - maxbotix,mb1020 + - maxbotix,mb1030 + - maxbotix,mb1040 + + trig-gpios: + description: + 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. + See Documentation/devicetree/bindings/gpio/gpio.txt for information + on how to specify a consumer gpio. + maxItems: 1 + + echo-gpios: + description: + 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. + maxItems: 1 + +required: + - compatible + - trig-gpios + - echo-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + proximity { + compatible = "devantech,srf04"; + trig-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; + echo-gpios = <&gpio2 6 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/iio/proximity/maxbotix,mb1232.txt b/Documentation/devicetree/bindings/iio/proximity/maxbotix,mb1232.txt new file mode 100644 index 000000000000..dd1058fbe9c3 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/maxbotix,mb1232.txt @@ -0,0 +1,29 @@ +* MaxBotix I2CXL-MaxSonar ultrasonic distance sensor of type mb1202, + mb1212, mb1222, mb1232, mb1242, mb7040 or mb7137 using the i2c interface + for ranging + +Required properties: + - compatible: "maxbotix,mb1202", + "maxbotix,mb1212", + "maxbotix,mb1222", + "maxbotix,mb1232", + "maxbotix,mb1242", + "maxbotix,mb7040" or + "maxbotix,mb7137" + + - reg: i2c address of the device, see also i2c/i2c.txt + +Optional properties: + - interrupts: Interrupt used to announce the preceding reading + request has finished and that data is available. + If no interrupt is specified the device driver + falls back to wait a fixed amount of time until + data can be retrieved. + +Example: +proximity@70 { + compatible = "maxbotix,mb1232"; + reg = <0x70>; + interrupt-parent = <&gpio2>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; +}; diff --git a/Documentation/devicetree/bindings/iio/st-sensors.txt b/Documentation/devicetree/bindings/iio/st-sensors.txt index 52ee4baec6f0..0ef64a444479 100644 --- a/Documentation/devicetree/bindings/iio/st-sensors.txt +++ b/Documentation/devicetree/bindings/iio/st-sensors.txt @@ -49,6 +49,7 @@ Accelerometers: - st,lis2dw12 - st,lis3dhh - st,lis3de +- st,lis2de12 Gyroscopes: - st,l3g4200d-gyro diff --git a/Documentation/devicetree/bindings/iio/temperature/max31856.txt b/Documentation/devicetree/bindings/iio/temperature/max31856.txt new file mode 100644 index 000000000000..06ab43bb4de8 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/temperature/max31856.txt @@ -0,0 +1,24 @@ +Maxim MAX31856 thermocouple support + +https://datasheets.maximintegrated.com/en/ds/MAX31856.pdf + +Optional property: + - thermocouple-type: Type of thermocouple (THERMOCOUPLE_TYPE_K if + omitted). Supported types are B, E, J, K, N, R, S, T. + +Required properties: + - compatible: must be "maxim,max31856" + - reg: SPI chip select number for the device + - spi-max-frequency: As per datasheet max. supported freq is 5000000 + - spi-cpha: must be defined for max31856 to enable SPI mode 1 + + Refer to spi/spi-bus.txt for generic SPI slave bindings. + + Example: + temp-sensor@0 { + compatible = "maxim,max31856"; + reg = <0>; + spi-max-frequency = <5000000>; + spi-cpha; + thermocouple-type = <THERMOCOUPLE_TYPE_K>; + }; diff --git a/Documentation/devicetree/bindings/iio/temperature/temperature-bindings.txt b/Documentation/devicetree/bindings/iio/temperature/temperature-bindings.txt new file mode 100644 index 000000000000..8f339cab74ae --- /dev/null +++ b/Documentation/devicetree/bindings/iio/temperature/temperature-bindings.txt @@ -0,0 +1,7 @@ +If the temperature sensor device can be configured to use some specific +thermocouple type, you can use the defined types provided in the file +"include/dt-bindings/iio/temperature/thermocouple.h". + +Property: +thermocouple-type: A single cell representing the type of the thermocouple + used by the device. diff --git a/Documentation/devicetree/bindings/input/gpio-vibrator.yaml b/Documentation/devicetree/bindings/input/gpio-vibrator.yaml new file mode 100644 index 000000000000..903475f52dbd --- /dev/null +++ b/Documentation/devicetree/bindings/input/gpio-vibrator.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bindings/input/gpio-vibrator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPIO vibrator + +maintainers: + - Luca Weiss <luca@z3ntu.xyz> + +description: |+ + Registers a GPIO device as vibrator, where the on/off capability is controlled by a GPIO. + +properties: + compatible: + const: gpio-vibrator + + enable-gpios: + maxItems: 1 + + vcc-supply: + description: Regulator that provides power + +required: + - compatible + - enable-gpios + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + vibrator { + compatible = "gpio-vibrator"; + enable-gpios = <&msmgpio 86 GPIO_ACTIVE_HIGH>; + vcc-supply = <&pm8941_l18>; + }; diff --git a/Documentation/devicetree/bindings/input/lpc32xx-key.txt b/Documentation/devicetree/bindings/input/lpc32xx-key.txt index bcf62f856358..2b075a080d30 100644 --- a/Documentation/devicetree/bindings/input/lpc32xx-key.txt +++ b/Documentation/devicetree/bindings/input/lpc32xx-key.txt @@ -8,6 +8,7 @@ Required Properties: - reg: Physical base address of the controller and length of memory mapped region. - interrupts: The interrupt number to the cpu. +- clocks: phandle to clock controller plus clock-specifier pair - nxp,debounce-delay-ms: Debounce delay in ms - nxp,scan-delay-ms: Repeated scan period in ms - linux,keymap: the key-code to be reported when the key is pressed @@ -22,7 +23,9 @@ Example: key@40050000 { compatible = "nxp,lpc3220-key"; reg = <0x40050000 0x1000>; - interrupts = <54 0>; + clocks = <&clk LPC32XX_CLK_KEY>; + interrupt-parent = <&sic1>; + interrupts = <22 IRQ_TYPE_LEVEL_HIGH>; keypad,num-rows = <1>; keypad,num-columns = <1>; nxp,debounce-delay-ms = <3>; diff --git a/Documentation/devicetree/bindings/input/max77650-onkey.txt b/Documentation/devicetree/bindings/input/max77650-onkey.txt new file mode 100644 index 000000000000..477dc74f452a --- /dev/null +++ b/Documentation/devicetree/bindings/input/max77650-onkey.txt @@ -0,0 +1,26 @@ +Onkey driver for MAX77650 PMIC from Maxim Integrated. + +This module is part of the MAX77650 MFD device. For more details +see Documentation/devicetree/bindings/mfd/max77650.txt. + +The onkey controller is represented as a sub-node of the PMIC node on +the device tree. + +Required properties: +-------------------- +- compatible: Must be "maxim,max77650-onkey". + +Optional properties: +- linux,code: The key-code to be reported when the key is pressed. + Defaults to KEY_POWER. +- maxim,onkey-slide: The system's button is a slide switch, not the default + push button. + +Example: +-------- + + onkey { + compatible = "maxim,max77650-onkey"; + linux,code = <KEY_END>; + maxim,onkey-slide; + }; diff --git a/Documentation/devicetree/bindings/input/microchip,qt1050.txt b/Documentation/devicetree/bindings/input/microchip,qt1050.txt new file mode 100644 index 000000000000..80e75f96252b --- /dev/null +++ b/Documentation/devicetree/bindings/input/microchip,qt1050.txt @@ -0,0 +1,78 @@ +Microchip AT42QT1050 Five-channel Touch Sensor IC + +The AT42QT1050 (QT1050) is a QTouchADC sensor device. The device can sense from +one to five keys, dependent on mode. The QT1050 includes all signal processing +functions necessary to provide stable sensing under a wide variety of changing +conditions, and the outputs are fully debounced. + +The touchkey device node should be placed inside an I2C bus node. + +Required properties: +- compatible: Must be "microchip,qt1050" +- reg: The I2C address of the device +- interrupts: The sink for the touchpad's IRQ output, + see ../interrupt-controller/interrupts.txt + +Optional properties: +- wakeup-source: touch keys can be used as a wakeup source + +Each button (key) is represented as a sub-node: + +Each not specified key or key with linux,code set to KEY_RESERVED gets disabled +in HW. + +Subnode properties: +- linux,code: Keycode to emit. +- reg: The key number. Valid values: 0, 1, 2, 3, 4. + +Optional subnode-properties: + +If a optional property is missing or has a invalid value the default value is +taken. + +- microchip,pre-charge-time-ns: + Each touchpad need some time to precharge. The value depends on the mechanical + layout. + Valid value range: 0 - 637500; values must be a multiple of 2500; + default is 0. +- microchip,average-samples: + Number of data samples which are averaged for each read. + Valid values: 1, 4, 16, 64, 256, 1024, 4096, 16384; default is 1. +- microchip,average-scaling: + The scaling factor which is used to scale the average-samples. + Valid values: 1, 2, 4, 8, 16, 32, 64, 128; default is 1. +- microchip,threshold: + Number of counts to register a touch detection. + Valid value range: 0 - 255; default is 20. + +Example: +QT1050 with 3 non continuous keys, key2 and key4 are disabled. + +touchkeys@41 { + compatible = "microchip,qt1050"; + reg = <0x41>; + interrupt-parent = <&gpio0>; + interrupts = <17 IRQ_TYPE_EDGE_FALLING>; + + up@0 { + reg = <0>; + linux,code = <KEY_UP>; + microchip,average-samples = <64>; + microchip,average-scaling = <16>; + microchip,pre-charge-time-ns = <10000>; + }; + + right@1 { + reg = <1>; + linux,code = <KEY_RIGHT>; + microchip,average-samples = <64>; + microchip,average-scaling = <8>; + }; + + down@3 { + reg = <3>; + linux,code = <KEY_DOWN>; + microchip,average-samples = <256>; + microchip,average-scaling = <16>; + }; +}; diff --git a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt index 1458c3179a63..496125c6bfb7 100644 --- a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt +++ b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt @@ -2,12 +2,14 @@ Allwinner sun4i low res adc attached tablet keys ------------------------------------------------ Required properties: - - compatible: "allwinner,sun4i-a10-lradc-keys" + - compatible: should be one of the following string: + "allwinner,sun4i-a10-lradc-keys" + "allwinner,sun8i-a83t-r-lradc" - reg: mmio address range of the chip - interrupts: interrupt to which the chip is connected - vref-supply: powersupply for the lradc reference voltage -Each key is represented as a sub-node of "allwinner,sun4i-a10-lradc-keys": +Each key is represented as a sub-node of the compatible mentioned above: Required subnode-properties: - label: Descriptive name of the key. diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.txt b/Documentation/devicetree/bindings/input/touchscreen/goodix.txt index 8cf0b4d38a7e..fc03ea4cf5ab 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/goodix.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.txt @@ -3,6 +3,7 @@ Device tree bindings for Goodix GT9xx series touchscreen controller Required properties: - compatible : Should be "goodix,gt1151" + or "goodix,gt5663" or "goodix,gt5688" or "goodix,gt911" or "goodix,gt9110" @@ -19,6 +20,8 @@ Optional properties: - irq-gpios : GPIO pin used for IRQ. The driver uses the interrupt gpio pin as output to reset the device. - reset-gpios : GPIO pin used for reset + - AVDD28-supply : Analog power supply regulator on AVDD28 pin + - VDDIO-supply : GPIO power supply regulator on VDDIO pin - touchscreen-inverted-x - touchscreen-inverted-y - touchscreen-size-x diff --git a/Documentation/devicetree/bindings/input/touchscreen/iqs5xx.txt b/Documentation/devicetree/bindings/input/touchscreen/iqs5xx.txt new file mode 100644 index 000000000000..efa0820e2469 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/iqs5xx.txt @@ -0,0 +1,80 @@ +Azoteq IQS550/572/525 Trackpad/Touchscreen Controller + +Required properties: + +- compatible : Must be equal to one of the following: + "azoteq,iqs550" + "azoteq,iqs572" + "azoteq,iqs525" + +- reg : I2C slave address for the device. + +- interrupts : GPIO to which the device's active-high RDY + output is connected (see [0]). + +- reset-gpios : GPIO to which the device's active-low NRST + input is connected (see [1]). + +Optional properties: + +- touchscreen-min-x : See [2]. + +- touchscreen-min-y : See [2]. + +- touchscreen-size-x : See [2]. If this property is omitted, the + maximum x-coordinate is specified by the + device's "X Resolution" register. + +- touchscreen-size-y : See [2]. If this property is omitted, the + maximum y-coordinate is specified by the + device's "Y Resolution" register. + +- touchscreen-max-pressure : See [2]. Pressure is expressed as the sum of + the deltas across all channels impacted by a + touch event. A channel's delta is calculated + as its count value minus a reference, where + the count value is inversely proportional to + the channel's capacitance. + +- touchscreen-fuzz-x : See [2]. + +- touchscreen-fuzz-y : See [2]. + +- touchscreen-fuzz-pressure : See [2]. + +- touchscreen-inverted-x : See [2]. Inversion is applied relative to that + which may already be specified by the device's + FLIP_X and FLIP_Y register fields. + +- touchscreen-inverted-y : See [2]. Inversion is applied relative to that + which may already be specified by the device's + FLIP_X and FLIP_Y register fields. + +- touchscreen-swapped-x-y : See [2]. Swapping is applied relative to that + which may already be specified by the device's + SWITCH_XY_AXIS register field. + +[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +[1]: Documentation/devicetree/bindings/gpio/gpio.txt +[2]: Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt + +Example: + + &i2c1 { + /* ... */ + + touchscreen@74 { + compatible = "azoteq,iqs550"; + reg = <0x74>; + interrupt-parent = <&gpio>; + interrupts = <17 4>; + reset-gpios = <&gpio 27 1>; + + touchscreen-size-x = <640>; + touchscreen-size-y = <480>; + + touchscreen-max-pressure = <16000>; + }; + + /* ... */ + }; diff --git a/Documentation/devicetree/bindings/interconnect/interconnect.txt b/Documentation/devicetree/bindings/interconnect/interconnect.txt index 5a3c575b387a..6f5d23a605b7 100644 --- a/Documentation/devicetree/bindings/interconnect/interconnect.txt +++ b/Documentation/devicetree/bindings/interconnect/interconnect.txt @@ -51,6 +51,10 @@ interconnect-names : List of interconnect path name strings sorted in the same interconnect-names to match interconnect paths with interconnect specifier pairs. + Reserved interconnect names: + * dma-mem: Path from the device to the main memory of + the system + Example: sdhci@7864000 { diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml index 758fbd7128e7..54838d4ea44c 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml @@ -129,6 +129,7 @@ required: patternProperties: "^v2m@[0-9a-f]+$": + type: object description: | * GICv2m extension for MSI/MSI-x support (Optional) diff --git a/Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml new file mode 100644 index 000000000000..4d61fe0a98a4 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/lm3630a-backlight.yaml @@ -0,0 +1,129 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/lm3630a-backlight.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI LM3630A High-Efficiency Dual-String White LED + +maintainers: + - Lee Jones <lee.jones@linaro.org> + - Daniel Thompson <daniel.thompson@linaro.org> + - Jingoo Han <jingoohan1@gmail.com> + +description: | + The LM3630A is a current-mode boost converter which supplies the power and + controls the current in up to two strings of 10 LEDs per string. + https://www.ti.com/product/LM3630A + +properties: + compatible: + const: ti,lm3630a + + reg: + maxItems: 1 + + ti,linear-mapping-mode: + description: | + Enable linear mapping mode. If disabled, then it will use exponential + mapping mode in which the ramp up/down appears to have a more uniform + transition to the human eye. + type: boolean + +required: + - compatible + - reg + +patternProperties: + "^led@[01]$": + type: object + description: | + Properties for a string of connected LEDs. + + properties: + reg: + description: | + The control bank that is used to program the two current sinks. The + LM3630A has two control banks (A and B) and are represented as 0 or 1 + in this property. The two current sinks can be controlled + independently with both banks, or bank A can be configured to control + both sinks with the led-sources property. + maxItems: 1 + minimum: 0 + maximum: 1 + + label: + maxItems: 1 + + led-sources: + allOf: + - minItems: 1 + maxItems: 2 + items: + minimum: 0 + maximum: 1 + + default-brightness: + description: Default brightness level on boot. + minimum: 0 + maximum: 255 + + max-brightness: + description: Maximum brightness that is allowed during runtime. + minimum: 0 + maximum: 255 + + required: + - reg + + additionalProperties: false + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@38 { + compatible = "ti,lm3630a"; + reg = <0x38>; + + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + led-sources = <0 1>; + label = "lcd-backlight"; + default-brightness = <200>; + max-brightness = <255>; + }; + }; + }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@38 { + compatible = "ti,lm3630a"; + reg = <0x38>; + + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + default-brightness = <150>; + ti,linear-mapping-mode; + }; + + led@1 { + reg = <1>; + default-brightness = <225>; + ti,linear-mapping-mode; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/leds-lm3532.txt b/Documentation/devicetree/bindings/leds/leds-lm3532.txt new file mode 100644 index 000000000000..c087f85ddddc --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-lm3532.txt @@ -0,0 +1,101 @@ +* Texas Instruments - lm3532 White LED driver with ambient light sensing +capability. + +The LM3532 provides the 3 high-voltage, low-side current sinks. The device is +programmable over an I2C-compatible interface and has independent +current control for all three channels. The adaptive current regulation +method allows for different LED currents in each current sink thus allowing +for a wide variety of backlight and keypad applications. + +The main features of the LM3532 include dual ambient light sensor inputs +each with 32 internal voltage setting resistors, 8-bit logarithmic and linear +brightness control, dual external PWM brightness control inputs, and up to +1000:1 dimming ratio with programmable fade in and fade out settings. + +Required properties: + - compatible : "ti,lm3532" + - reg : I2C slave address + - #address-cells : 1 + - #size-cells : 0 + +Optional properties: + - enable-gpios : gpio pin to enable (active high)/disable the device. + - ramp-up-us - The Run time ramp rates/step are from one current + set-point to another after the device has reached its + initial target set point from turn-on + - ramp-down-us - The Run time ramp rates/step are from one current + set-point to another after the device has reached its + initial target set point from turn-on + Range for ramp settings: 8us - 65536us + +Optional properties if ALS mode is used: + - ti,als-vmin - Minimum ALS voltage defined in Volts + - ti,als-vmax - Maximum ALS voltage defined in Volts + Per the data sheet the max ALS voltage is 2V and the min is 0V + + - ti,als1-imp-sel - ALS1 impedance resistor selection in Ohms + - ti,als2-imp-sel - ALS2 impedance resistor selection in Ohms + Range for impedance select: 37000 Ohms - 1190 Ohms + Values above 37kohms will be set to the "High Impedance" setting + + - ti,als-avrg-time-us - Determines the length of time the device needs to + average the two ALS inputs. This is only used if + the input mode is LM3532_ALS_INPUT_AVRG. + Range: 17920us - 2293760us + - ti,als-input-mode - Determines how the device uses the attached ALS + devices. + 0x00 - ALS1 and ALS2 input average + 0x01 - ALS1 Input + 0x02 - ALS2 Input + 0x03 - Max of ALS1 and ALS2 + +Required child properties: + - reg : Indicates control bank the LED string is controlled by + - led-sources : see Documentation/devicetree/bindings/leds/common.txt + - ti,led-mode : Defines if the LED strings are manually controlled or + if the LED strings are controlled by the ALS. + 0x00 - LED strings are I2C controlled via full scale + brightness control register + 0x01 - LED strings are ALS controlled + +Optional LED child properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - linux,default-trigger : + see Documentation/devicetree/bindings/leds/common.txt + +Example: +led-controller@38 { + compatible = "ti,lm3532"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x38>; + + enable-gpios = <&gpio6 12 GPIO_ACTIVE_HIGH>; + ramp-up-us = <1024>; + ramp-down-us = <65536>; + + ti,als-vmin = <0>; + ti,als-vmax = <2000>; + ti,als1-imp-sel = <4110>; + ti,als2-imp-sel = <2180>; + ti,als-avrg-time-us = <17920>; + ti,als-input-mode = <0x00>; + + led@0 { + reg = <0>; + led-sources = <2>; + ti,led-mode = <1>; + label = ":backlight"; + linux,default-trigger = "backlight"; + }; + + led@1 { + reg = <1>; + led-sources = <1>; + ti,led-mode = <0>; + label = ":kbd_backlight"; + }; +}; + +For more product information please see the links below: +http://www.ti.com/product/LM3532 diff --git a/Documentation/devicetree/bindings/leds/leds-max77650.txt b/Documentation/devicetree/bindings/leds/leds-max77650.txt new file mode 100644 index 000000000000..3a67115cc1da --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-max77650.txt @@ -0,0 +1,57 @@ +LED driver for MAX77650 PMIC from Maxim Integrated. + +This module is part of the MAX77650 MFD device. For more details +see Documentation/devicetree/bindings/mfd/max77650.txt. + +The LED controller is represented as a sub-node of the PMIC node on +the device tree. + +This device has three current sinks. + +Required properties: +-------------------- +- compatible: Must be "maxim,max77650-led" +- #address-cells: Must be <1>. +- #size-cells: Must be <0>. + +Each LED is represented as a sub-node of the LED-controller node. Up to +three sub-nodes can be defined. + +Required properties of the sub-node: +------------------------------------ + +- reg: Must be <0>, <1> or <2>. + +Optional properties of the sub-node: +------------------------------------ + +- label: See Documentation/devicetree/bindings/leds/common.txt +- linux,default-trigger: See Documentation/devicetree/bindings/leds/common.txt + +For more details, please refer to the generic GPIO DT binding document +<devicetree/bindings/gpio/gpio.txt>. + +Example: +-------- + + leds { + compatible = "maxim,max77650-led"; + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + label = "blue:usr0"; + }; + + led@1 { + reg = <1>; + label = "red:usr1"; + linux,default-trigger = "heartbeat"; + }; + + led@2 { + reg = <2>; + label = "green:usr2"; + }; + }; diff --git a/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.txt b/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.txt new file mode 100644 index 000000000000..282ab81a4ea6 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/marvell,armada-3700-rwtm-mailbox.txt @@ -0,0 +1,16 @@ +* rWTM BIU Mailbox driver for Armada 37xx + +Required properties: +- compatible: must be "marvell,armada-3700-rwtm-mailbox" +- reg: physical base address of the mailbox and length of memory mapped + region +- interrupts: the IRQ line for the mailbox +- #mbox-cells: must be 1 + +Example: + rwtm: mailbox@b0000 { + compatible = "marvell,armada-3700-rwtm-mailbox"; + reg = <0xb0000 0x100>; + interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>; + #mbox-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/media/aspeed-video.txt b/Documentation/devicetree/bindings/media/aspeed-video.txt index 78b464ae2672..ce2894506e1f 100644 --- a/Documentation/devicetree/bindings/media/aspeed-video.txt +++ b/Documentation/devicetree/bindings/media/aspeed-video.txt @@ -14,6 +14,11 @@ Required properties: the VE - interrupts: the interrupt associated with the VE on this platform +Optional properties: + - memory-region: + phandle to a memory region to allocate from, as defined in + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt + Example: video-engine@1e700000 { @@ -23,4 +28,5 @@ video-engine@1e700000 { clock-names = "vclk", "eclk"; resets = <&syscon ASPEED_RESET_VIDEO>; interrupts = <7>; + memory-region = <&video_engine_memory>; }; diff --git a/Documentation/devicetree/bindings/media/cedrus.txt b/Documentation/devicetree/bindings/media/cedrus.txt index bce0705df953..20c82fb0c343 100644 --- a/Documentation/devicetree/bindings/media/cedrus.txt +++ b/Documentation/devicetree/bindings/media/cedrus.txt @@ -13,6 +13,7 @@ Required properties: - "allwinner,sun8i-h3-video-engine" - "allwinner,sun50i-a64-video-engine" - "allwinner,sun50i-h5-video-engine" + - "allwinner,sun50i-h6-video-engine" - reg : register base and length of VE; - clocks : list of clock specifiers, corresponding to entries in the clock-names property; diff --git a/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt new file mode 100644 index 000000000000..7976e6c40a80 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/st,st-mipid02.txt @@ -0,0 +1,82 @@ +STMicroelectronics MIPID02 CSI-2 to PARALLEL bridge + +MIPID02 has two CSI-2 input ports, only one of those ports can be active at a +time. Active port input stream will be de-serialized and its content outputted +through PARALLEL output port. +CSI-2 first input port is a dual lane 800Mbps per lane whereas CSI-2 second +input port is a single lane 800Mbps. Both ports support clock and data lane +polarity swap. First port also supports data lane swap. +PARALLEL output port has a maximum width of 12 bits. +Supported formats are RAW6, RAW7, RAW8, RAW10, RAW12, RGB565, RGB888, RGB444, +YUV420 8-bit, YUV422 8-bit and YUV420 10-bit. + +Required Properties: +- compatible: shall be "st,st-mipid02" +- clocks: reference to the xclk input clock. +- clock-names: shall be "xclk". +- VDDE-supply: sensor digital IO supply. Must be 1.8 volts. +- VDDIN-supply: sensor internal regulator supply. Must be 1.8 volts. + +Optional Properties: +- reset-gpios: reference to the GPIO connected to the xsdn pin, if any. + This is an active low signal to the mipid02. + +Required subnodes: + - ports: A ports node with one port child node per device input and output + port, in accordance with the video interface bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + port nodes are numbered as follows: + + Port Description + ----------------------------- + 0 CSI-2 first input port + 1 CSI-2 second input port + 2 PARALLEL output + +Endpoint node required property for CSI-2 connection is: +- data-lanes: shall be <1> for Port 1. for Port 0 dual-lane operation shall be +<1 2> or <2 1>. For Port 0 single-lane operation shall be <1> or <2>. +Endpoint node optional property for CSI-2 connection is: +- lane-polarities: any lane can be inverted or not. + +Endpoint node required property for PARALLEL connection is: +- bus-width: shall be set to <6>, <7>, <8>, <10> or <12>. +Endpoint node optional properties for PARALLEL connection are: +- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. +LOW being the default. +- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. +LOW being the default. + +Example: + +mipid02: csi2rx@14 { + compatible = "st,st-mipid02"; + reg = <0x14>; + status = "okay"; + clocks = <&clk_ext_camera_12>; + clock-names = "xclk"; + VDDE-supply = <&vdd>; + VDDIN-supply = <&vdd>; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + + ep0: endpoint { + data-lanes = <1 2>; + remote-endpoint = <&mipi_csi2_in>; + }; + }; + port@2 { + reg = <2>; + + ep2: endpoint { + bus-width = <8>; + hsync-active = <0>; + vsync-active = <0>; + remote-endpoint = <¶llel_out>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/meson-ao-cec.txt b/Documentation/devicetree/bindings/media/meson-ao-cec.txt index 8671bdb08080..c67fc41d4aa2 100644 --- a/Documentation/devicetree/bindings/media/meson-ao-cec.txt +++ b/Documentation/devicetree/bindings/media/meson-ao-cec.txt @@ -4,16 +4,23 @@ The Amlogic Meson AO-CEC module is present is Amlogic SoCs and its purpose is to handle communication between HDMI connected devices over the CEC bus. Required properties: - - compatible : value should be following + - compatible : value should be following depending on the SoC : + For GXBB, GXL, GXM and G12A (AO_CEC_A module) : "amlogic,meson-gx-ao-cec" + For G12A (AO_CEC_B module) : + "amlogic,meson-g12a-ao-cec" - reg : Physical base address of the IP registers and length of memory mapped region. - interrupts : AO-CEC interrupt number to the CPU. - clocks : from common clock binding: handle to AO-CEC clock. - - clock-names : from common clock binding: must contain "core", - corresponding to entry in the clocks property. + - clock-names : from common clock binding, must contain : + For GXBB, GXL, GXM and G12A (AO_CEC_A module) : + - "core" + For G12A (AO_CEC_B module) : + - "oscin" + corresponding to entry in the clocks property. - hdmi-phandle: phandle to the HDMI controller Example: diff --git a/Documentation/devicetree/bindings/media/rcar_imr.txt b/Documentation/devicetree/bindings/media/rcar_imr.txt new file mode 100644 index 000000000000..b0614153ed36 --- /dev/null +++ b/Documentation/devicetree/bindings/media/rcar_imr.txt @@ -0,0 +1,31 @@ +Renesas R-Car Image Renderer (Distortion Correction Engine) +----------------------------------------------------------- + +The image renderer, or the distortion correction engine, is a drawing processor +with a simple instruction system capable of referencing video capture data or +data in an external memory as 2D texture data and performing texture mapping +and drawing with respect to any shape that is split into triangular objects. + +Required properties: + +- compatible: "renesas,<soctype>-imr-lx4", "renesas,imr-lx4" as a fallback for + the image renderer light extended 4 (IMR-LX4) found in the R-Car gen3 SoCs, + where the examples with <soctype> are: + - "renesas,r8a7795-imr-lx4" for R-Car H3, + - "renesas,r8a7796-imr-lx4" for R-Car M3-W. +- reg: offset and length of the register block; +- interrupts: single interrupt specifier; +- clocks: single clock phandle/specifier pair; +- power-domains: power domain phandle/specifier pair; +- resets: reset phandle/specifier pair. + +Example: + + imr-lx4@fe860000 { + compatible = "renesas,r8a7795-imr-lx4", "renesas,imr-lx4"; + reg = <0 0xfe860000 0 0x2000>; + interrupts = <GIC_SPI 192 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 823>; + power-domains = <&sysc R8A7795_PD_A3VC>; + resets = <&cpg 823>; + }; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 224a4615b418..aa217b096279 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -13,6 +13,7 @@ on Gen3 and RZ/G2 platforms to a CSI-2 receiver. - "renesas,vin-r8a7743" for the R8A7743 device - "renesas,vin-r8a7744" for the R8A7744 device - "renesas,vin-r8a7745" for the R8A7745 device + - "renesas,vin-r8a774a1" for the R8A774A1 device - "renesas,vin-r8a774c0" for the R8A774C0 device - "renesas,vin-r8a7778" for the R8A7778 device - "renesas,vin-r8a7779" for the R8A7779 device diff --git a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt index d63275e17afd..331409259752 100644 --- a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt +++ b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt @@ -8,6 +8,7 @@ R-Car VIN module, which provides the video capture capabilities. Mandatory properties -------------------- - compatible: Must be one or more of the following + - "renesas,r8a774a1-csi2" for the R8A774A1 device. - "renesas,r8a774c0-csi2" for the R8A774C0 device. - "renesas,r8a7795-csi2" for the R8A7795 device. - "renesas,r8a7796-csi2" for the R8A7796 device. @@ -18,7 +19,8 @@ Mandatory properties - reg: the register base and size for the device registers - interrupts: the interrupt for the device - - clocks: reference to the parent clock + - clocks: A phandle + clock specifier for the module clock + - resets: A phandle + reset specifier for the module reset The device node shall contain two 'port' child nodes according to the bindings defined in Documentation/devicetree/bindings/media/ diff --git a/Documentation/devicetree/bindings/memory-controllers/atmel,ebi.txt b/Documentation/devicetree/bindings/memory-controllers/atmel,ebi.txt index 9bb5f57e2066..94bf7896a688 100644 --- a/Documentation/devicetree/bindings/memory-controllers/atmel,ebi.txt +++ b/Documentation/devicetree/bindings/memory-controllers/atmel,ebi.txt @@ -15,6 +15,7 @@ Required properties: "atmel,at91sam9g45-ebi" "atmel,at91sam9x5-ebi" "atmel,sama5d3-ebi" + "microchip,sam9x60-ebi" - reg: Contains offset/length value for EBI memory mapping. This property might contain several entries if the EBI diff --git a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt index 3f643ef121ff..5f8880cc757e 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt @@ -7,6 +7,7 @@ Required properties: "atmel,sama5d2-hlcdc" "atmel,sama5d3-hlcdc" "atmel,sama5d4-hlcdc" + "microchip,sam9x60-hlcdc" - reg: base address and size of the HLCDC device registers. - clock-names: the name of the 3 clocks requested by the HLCDC device. Should contain "periph_clk", "sys_clk" and "slow_clk". diff --git a/Documentation/devicetree/bindings/mfd/axp20x.txt b/Documentation/devicetree/bindings/mfd/axp20x.txt index 2af4ff95d6bc..4991a6415796 100644 --- a/Documentation/devicetree/bindings/mfd/axp20x.txt +++ b/Documentation/devicetree/bindings/mfd/axp20x.txt @@ -25,6 +25,7 @@ Required properties: * "x-powers,axp223" * "x-powers,axp803" * "x-powers,axp806" + * "x-powers,axp805", "x-powers,axp806" * "x-powers,axp809" * "x-powers,axp813" - reg: The I2C slave address or RSB hardware address for the AXP chip diff --git a/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.txt index 004b0158cf4d..3bf92ad37fa1 100644 --- a/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.txt +++ b/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.txt @@ -19,6 +19,8 @@ And these documents for the required sub-node binding details: [4] Clock: ../clock/cirrus,lochnagar.txt [5] Pinctrl: ../pinctrl/cirrus,lochnagar.txt [6] Regulator: ../regulator/cirrus,lochnagar.txt + [7] Sound: ../sound/cirrus,lochnagar.txt + [8] Hardware Monitor: ../hwmon/cirrus,lochnagar.txt Required properties: @@ -41,6 +43,11 @@ Optional sub-nodes: - Bindings for the regulator components, see [6]. Only available on Lochnagar 2. + - lochnagar-sc : Binding for the sound card components, see [7]. + Only available on Lochnagar 2. + - lochnagar-hwmon : Binding for the hardware monitor components, see [8]. + Only available on Lochnagar 2. + Optional properties: - present-gpios : Host present line, indicating the presence of a @@ -65,4 +72,14 @@ lochnagar: lochnagar@22 { compatible = "cirrus,lochnagar-pinctrl"; ... }; + + lochnagar-sc { + compatible = "cirrus,lochnagar2-soundcard"; + ... + }; + + lochnagar-hwmon { + compatible = "cirrus,lochnagar2-hwmon"; + ... + }; }; diff --git a/Documentation/devicetree/bindings/mfd/max77620.txt b/Documentation/devicetree/bindings/mfd/max77620.txt index 9c16d51cc15b..5a642a51d58e 100644 --- a/Documentation/devicetree/bindings/mfd/max77620.txt +++ b/Documentation/devicetree/bindings/mfd/max77620.txt @@ -4,7 +4,8 @@ Required properties: ------------------- - compatible: Must be one of "maxim,max77620" - "maxim,max20024". + "maxim,max20024" + "maxim,max77663" - reg: I2C device address. Optional properties: @@ -17,6 +18,11 @@ Optional properties: IRQ numbers for different interrupt source of MAX77620 are defined at dt-bindings/mfd/max77620.h. +- system-power-controller: Indicates that this PMIC is controlling the + system power, see [1] for more details. + +[1] Documentation/devicetree/bindings/power/power-controller.txt + Optional subnodes and their properties: ======================================= @@ -105,6 +111,7 @@ Optional properties: Here supported time periods by device in microseconds are as follows: MAX77620 supports 40, 80, 160, 320, 640, 1280, 2560 and 5120 microseconds. MAX20024 supports 20, 40, 80, 160, 320, 640, 1280 and 2540 microseconds. +MAX77663 supports 20, 40, 80, 160, 320, 640, 1280 and 2540 microseconds. -maxim,power-ok-control: configure map power ok bit 1: Enables POK(Power OK) to control nRST_IO and GPIO1 diff --git a/Documentation/devicetree/bindings/mfd/max77650.txt b/Documentation/devicetree/bindings/mfd/max77650.txt new file mode 100644 index 000000000000..b529d8d19335 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/max77650.txt @@ -0,0 +1,46 @@ +MAX77650 ultra low-power PMIC from Maxim Integrated. + +Required properties: +------------------- +- compatible: Must be "maxim,max77650" +- reg: I2C device address. +- interrupts: The interrupt on the parent the controller is + connected to. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Must be <2>. + +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Must be <2>. The first cell is the pin number and + the second cell is used to specify the gpio active + state. + +Optional properties: +-------------------- +gpio-line-names: Single string containing the name of the GPIO line. + +The GPIO-controller module is represented as part of the top-level PMIC +node. The device exposes a single GPIO line. + +For device-tree bindings of other sub-modules (regulator, power supply, +LEDs and onkey) refer to the binding documents under the respective +sub-system directories. + +For more details on GPIO bindings, please refer to the generic GPIO DT +binding document <devicetree/bindings/gpio/gpio.txt>. + +Example: +-------- + + pmic@48 { + compatible = "maxim,max77650"; + reg = <0x48>; + + interrupt-controller; + interrupt-parent = <&gpio2>; + #interrupt-cells = <2>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + + gpio-controller; + #gpio-cells = <2>; + gpio-line-names = "max77650-charger"; + }; diff --git a/Documentation/devicetree/bindings/mfd/stm32-lptimer.txt b/Documentation/devicetree/bindings/mfd/stm32-lptimer.txt index 2a9ff29db9c9..fb54e4dad5b3 100644 --- a/Documentation/devicetree/bindings/mfd/stm32-lptimer.txt +++ b/Documentation/devicetree/bindings/mfd/stm32-lptimer.txt @@ -16,7 +16,7 @@ Required properties: Optional subnodes: - pwm: See ../pwm/pwm-stm32-lp.txt -- counter: See ../iio/timer/stm32-lptimer-cnt.txt +- counter: See ../counter/stm32-lptimer-cnt.txt - trigger: See ../iio/timer/stm32-lptimer-trigger.txt Example: diff --git a/Documentation/devicetree/bindings/mfd/stm32-timers.txt b/Documentation/devicetree/bindings/mfd/stm32-timers.txt index 0e900b52e895..15c3b87f51d9 100644 --- a/Documentation/devicetree/bindings/mfd/stm32-timers.txt +++ b/Documentation/devicetree/bindings/mfd/stm32-timers.txt @@ -28,6 +28,7 @@ Optional parameters: Optional subnodes: - pwm: See ../pwm/pwm-stm32.txt - timer: See ../iio/timer/stm32-timer-trigger.txt +- counter: See ../counter/stm32-timer-cnt.txt Example: timers@40010000 { @@ -48,6 +49,12 @@ Example: compatible = "st,stm32-timer-trigger"; reg = <0>; }; + + counter { + compatible = "st,stm32-timer-counter"; + pinctrl-names = "default"; + pinctrl-0 = <&tim1_in_pins>; + }; }; Example with all dmas: diff --git a/Documentation/devicetree/bindings/mfd/stmfx.txt b/Documentation/devicetree/bindings/mfd/stmfx.txt new file mode 100644 index 000000000000..f0c2f7fcf5c7 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/stmfx.txt @@ -0,0 +1,28 @@ +STMicroelectonics Multi-Function eXpander (STMFX) Core bindings + +ST Multi-Function eXpander (STMFX) is a slave controller using I2C for +communication with the main MCU. Its main features are GPIO expansion, main +MCU IDD measurement (IDD is the amount of current that flows through VDD) and +resistive touchscreen controller. + +Required properties: +- compatible: should be "st,stmfx-0300". +- reg: I2C slave address of the device. +- interrupts: interrupt specifier triggered by MFX_IRQ_OUT signal. + Please refer to ../interrupt-controller/interrupt.txt + +Optional properties: +- drive-open-drain: configure MFX_IRQ_OUT as open drain. +- vdd-supply: phandle of the regulator supplying STMFX. + +Example: + + stmfx: stmfx@42 { + compatible = "st,stmfx-0300"; + reg = <0x42>; + interrupts = <8 IRQ_TYPE_EDGE_RISING>; + interrupt-parent = <&gpioi>; + vdd-supply = <&v3v3>; + }; + +Please refer to ../pinctrl/pinctrl-stmfx.txt for STMFX GPIO expander function bindings. diff --git a/Documentation/devicetree/bindings/mfd/ti-lmu.txt b/Documentation/devicetree/bindings/mfd/ti-lmu.txt index c885cf89b8ce..86ca786d54fc 100644 --- a/Documentation/devicetree/bindings/mfd/ti-lmu.txt +++ b/Documentation/devicetree/bindings/mfd/ti-lmu.txt @@ -4,7 +4,6 @@ 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 @@ -13,7 +12,6 @@ TI LMU driver supports lighting devices below. Required properties: - compatible: Should be one of: - "ti,lm3532" "ti,lm3631" "ti,lm3632" "ti,lm3633" @@ -23,7 +21,6 @@ Required properties: 0x11 for LM3632 0x29 for LM3631 0x36 for LM3633, LM3697 - 0x38 for LM3532 0x63 for LM3695 Optional property: @@ -47,23 +44,6 @@ Optional nodes: [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>; @@ -124,8 +104,8 @@ lm3632@11 { 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 */ + enable-gpios = <&pioC 0 GPIO_ACTIVE_HIGH>, + <&pioC 1 GPIO_ACTIVE_HIGH>; vboost { regulator-name = "lcd_boost"; diff --git a/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt b/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt new file mode 100644 index 000000000000..854bd67ffec6 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/aspeed-p2a-ctrl.txt @@ -0,0 +1,47 @@ +====================================================================== +Device tree bindings for Aspeed AST2400/AST2500 PCI-to-AHB Bridge Control Driver +====================================================================== + +The bridge is available on platforms with the VGA enabled on the Aspeed device. +In this case, the host has access to a 64KiB window into all of the BMC's +memory. The BMC can disable this bridge. If the bridge is enabled, the host +has read access to all the regions of memory, however the host only has read +and write access depending on a register controlled by the BMC. + +Required properties: +=================== + + - compatible: must be one of: + - "aspeed,ast2400-p2a-ctrl" + - "aspeed,ast2500-p2a-ctrl" + +Optional properties: +=================== + +- memory-region: A phandle to a reserved_memory region to be used for the PCI + to AHB mapping + +The p2a-control node should be the child of a syscon node with the required +property: + +- compatible : Should be one of the following: + "aspeed,ast2400-scu", "syscon", "simple-mfd" + "aspeed,g4-scu", "syscon", "simple-mfd" + "aspeed,ast2500-scu", "syscon", "simple-mfd" + "aspeed,g5-scu", "syscon", "simple-mfd" + +Example +=================== + +g4 Example +---------- + +syscon: scu@1e6e2000 { + compatible = "aspeed,ast2400-scu", "syscon", "simple-mfd"; + reg = <0x1e6e2000 0x1a8>; + + p2a: p2a-control { + compatible = "aspeed,ast2400-p2a-ctrl"; + memory-region = <&reserved_memory>; + }; +}; diff --git a/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt index 99c5cf8507e8..edb8cadb9541 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt +++ b/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt @@ -17,6 +17,7 @@ Required properties: "fsl,t4240-esdhc" Possible compatibles for ARM: "fsl,ls1012a-esdhc" + "fsl,ls1028a-esdhc" "fsl,ls1088a-esdhc" "fsl,ls1043a-esdhc" "fsl,ls1046a-esdhc" diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt index 540c65ed9cba..f707b8bee304 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt @@ -17,6 +17,7 @@ Required properties: "fsl,imx6sx-usdhc" "fsl,imx6ull-usdhc" "fsl,imx7d-usdhc" + "fsl,imx7ulp-usdhc" "fsl,imx8qxp-usdhc" Optional properties: diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index cdbcfd3a4ff2..c269dbe384fe 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -64,6 +64,8 @@ Optional properties: whether pwrseq-simple is used. Default to 10ms if no available. - supports-cqe : The presence of this property indicates that the corresponding MMC host controller supports HW command queue feature. +- disable-cqe-dcmd: This property indicates that the MMC controller's command + queue engine (CQE) does not support direct commands (DCMDs). *NOTE* on CD and WP polarity. To use common for all SD/MMC host controllers line polarity properties, we have to fix the meaning of the "normal" and "inverted" diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.txt b/Documentation/devicetree/bindings/mmc/mtk-sd.txt index f5bcda3980cc..8a532f4453f2 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.txt +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.txt @@ -11,10 +11,12 @@ Required properties: "mediatek,mt8135-mmc": for mmc host ip compatible with mt8135 "mediatek,mt8173-mmc": for mmc host ip compatible with mt8173 "mediatek,mt8183-mmc": for mmc host ip compatible with mt8183 + "mediatek,mt8516-mmc": for mmc host ip compatible with mt8516 "mediatek,mt2701-mmc": for mmc host ip compatible with mt2701 "mediatek,mt2712-mmc": for mmc host ip compatible with mt2712 "mediatek,mt7622-mmc": for MT7622 SoC "mediatek,mt7623-mmc", "mediatek,mt2701-mmc": for MT7623 SoC + "mediatek,mt7620-mmc", for MT7621 SoC (and others) - reg: physical base address of the controller and length - interrupts: Should contain MSDC interrupt number diff --git a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt index 2cecdc71d94c..2cf3affa1be7 100644 --- a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt @@ -14,6 +14,7 @@ Required properties: - "nvidia,tegra124-sdhci": for Tegra124 and Tegra132 - "nvidia,tegra210-sdhci": for Tegra210 - "nvidia,tegra186-sdhci": for Tegra186 + - "nvidia,tegra194-sdhci": for Tegra194 - 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/mtd/allwinner,sun4i-a10-nand.yaml b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml new file mode 100644 index 000000000000..fbd4da3684fc --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/allwinner,sun4i-a10-nand.yaml @@ -0,0 +1,97 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/allwinner,sun4i-a10-nand.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Allwinner A10 NAND Controller Device Tree Bindings + +allOf: + - $ref: "nand-controller.yaml" + +maintainers: + - Chen-Yu Tsai <wens@csie.org> + - Maxime Ripard <maxime.ripard@bootlin.com> + +properties: + "#address-cells": true + "#size-cells": true + + compatible: + enum: + - allwinner,sun4i-a10-nand + - allwinner,sun8i-a23-nand-controller + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + items: + - description: Bus Clock + - description: Module Clock + + clock-names: + items: + - const: ahb + - const: mod + + resets: + maxItems: 1 + + reset-names: + const: ahb + + dmas: + maxItems: 1 + + dma-names: + const: rxtx + + pinctrl-names: true + +patternProperties: + "^pinctrl-[0-9]+$": true + + "^nand@[a-f0-9]+$": + properties: + reg: + maxItems: 1 + minimum: 0 + maximum: 7 + + nand-ecc-mode: true + + nand-ecc-algo: + const: bch + + nand-ecc-step-size: + enum: [ 512, 1024 ] + + nand-ecc-strength: + maximum: 80 + + allwinner,rb: + description: + Contains the native Ready/Busy IDs. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + - minItems: 1 + maxItems: 2 + items: + minimum: 0 + maximum: 1 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +additionalProperties: false + +... diff --git a/Documentation/devicetree/bindings/mtd/atmel-nand.txt b/Documentation/devicetree/bindings/mtd/atmel-nand.txt index 9bb66e476672..68b51dc58816 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-nand.txt +++ b/Documentation/devicetree/bindings/mtd/atmel-nand.txt @@ -14,6 +14,7 @@ Required properties: "atmel,at91sam9261-nand-controller" "atmel,at91sam9g45-nand-controller" "atmel,sama5d3-nand-controller" + "microchip,sam9x60-nand-controller" - ranges: empty ranges property to forward EBI ranges definitions. - #address-cells: should be set to 2. - #size-cells: should be set to 1. diff --git a/Documentation/devicetree/bindings/mtd/denali-nand.txt b/Documentation/devicetree/bindings/mtd/denali-nand.txt index f33da8782741..b14b6751c2f3 100644 --- a/Documentation/devicetree/bindings/mtd/denali-nand.txt +++ b/Documentation/devicetree/bindings/mtd/denali-nand.txt @@ -7,34 +7,48 @@ Required properties: "socionext,uniphier-denali-nand-v5b" - for Socionext UniPhier (v5b) - reg : should contain registers location and length for data and reg. - reg-names: Should contain the reg names "nand_data" and "denali_reg" + - #address-cells: should be 1. The cell encodes the chip select connection. + - #size-cells : should be 0. - interrupts : The interrupt number. - clocks: should contain phandle of the controller core clock, the bus interface clock, and the ECC circuit clock. - clock-names: should contain "nand", "nand_x", "ecc" -Optional properties: - - nand-ecc-step-size: see nand.txt for details. If present, the value must be - 512 for "altr,socfpga-denali-nand" - 1024 for "socionext,uniphier-denali-nand-v5a" - 1024 for "socionext,uniphier-denali-nand-v5b" - - nand-ecc-strength: see nand.txt for details. Valid values are: - 8, 15 for "altr,socfpga-denali-nand" - 8, 16, 24 for "socionext,uniphier-denali-nand-v5a" - 8, 16 for "socionext,uniphier-denali-nand-v5b" - - nand-ecc-maximize: see nand.txt for details - -The device tree may optionally contain sub-nodes describing partitions of the +Sub-nodes: + Sub-nodes represent available NAND chips. + + Required properties: + - reg: should contain the bank ID of the controller to which each chip + select is connected. + + Optional properties: + - nand-ecc-step-size: see nand.txt for details. + If present, the value must be + 512 for "altr,socfpga-denali-nand" + 1024 for "socionext,uniphier-denali-nand-v5a" + 1024 for "socionext,uniphier-denali-nand-v5b" + - nand-ecc-strength: see nand.txt for details. Valid values are: + 8, 15 for "altr,socfpga-denali-nand" + 8, 16, 24 for "socionext,uniphier-denali-nand-v5a" + 8, 16 for "socionext,uniphier-denali-nand-v5b" + - nand-ecc-maximize: see nand.txt for details + +The chip nodes may optionally contain sub-nodes describing partitions of the address space. See partition.txt for more detail. Examples: nand: nand@ff900000 { #address-cells = <1>; - #size-cells = <1>; + #size-cells = <0>; compatible = "altr,socfpga-denali-nand"; reg = <0xff900000 0x20>, <0xffb80000 0x1000>; reg-names = "nand_data", "denali_reg"; clocks = <&nand_clk>, <&nand_x_clk>, <&nand_ecc_clk>; clock-names = "nand", "nand_x", "ecc"; interrupts = <0 144 4>; + + nand@0 { + reg = <0>; + } }; diff --git a/Documentation/devicetree/bindings/mtd/ingenic,jz4780-nand.txt b/Documentation/devicetree/bindings/mtd/ingenic,jz4780-nand.txt index 29ea5853ca91..c02259353327 100644 --- a/Documentation/devicetree/bindings/mtd/ingenic,jz4780-nand.txt +++ b/Documentation/devicetree/bindings/mtd/ingenic,jz4780-nand.txt @@ -1,4 +1,4 @@ -* Ingenic JZ4780 NAND/BCH +* Ingenic JZ4780 NAND/ECC This file documents the device tree bindings for NAND flash devices on the JZ4780. NAND devices are connected to the NEMC controller (described in @@ -6,15 +6,18 @@ memory-controllers/ingenic,jz4780-nemc.txt), and thus NAND device nodes must be children of the NEMC node. Required NAND controller device properties: -- compatible: Should be set to "ingenic,jz4780-nand". +- compatible: Should be one of: + * ingenic,jz4740-nand + * ingenic,jz4725b-nand + * ingenic,jz4780-nand - reg: For each bank with a NAND chip attached, should specify a bank number, an offset of 0 and a size of 0x1000000 (i.e. the whole NEMC bank). Optional NAND controller device properties: -- ingenic,bch-controller: To make use of the hardware BCH controller, this - property must contain a phandle for the BCH controller node. The required +- ecc-engine: To make use of the hardware ECC controller, this + property must contain a phandle for the ECC controller node. The required properties for this node are described below. If this is not specified, - software BCH will be used instead. + software ECC will be used instead. Optional children nodes: - Individual NAND chips are children of the NAND controller node. @@ -45,7 +48,7 @@ nemc: nemc@13410000 { #address-cells = <1>; #size-cells = <0>; - ingenic,bch-controller = <&bch>; + ecc-engine = <&bch>; nand@1 { reg = <1>; @@ -67,14 +70,17 @@ nemc: nemc@13410000 { }; }; -The BCH controller is a separate SoC component used for error correction on +The ECC controller is a separate SoC component used for error correction on NAND devices. The following is a description of the device properties for a -BCH controller. - -Required BCH properties: -- compatible: Should be set to "ingenic,jz4780-bch". -- reg: Should specify the BCH controller registers location and length. -- clocks: Clock for the BCH controller. +ECC controller. + +Required ECC properties: +- compatible: Should be one of: + * ingenic,jz4740-ecc + * ingenic,jz4725b-bch + * ingenic,jz4780-bch +- reg: Should specify the ECC controller registers location and length. +- clocks: Clock for the ECC controller. Example: diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt index 7df0dcaccb7d..c69f4f065d23 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt @@ -96,3 +96,19 @@ An example using SRAM: bank-width = <2>; }; +An example using gpio-addrs + + flash@20000000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "cfi-flash", "jedec-flash"; + reg = <0x20000000 0x02000000>; + ranges = <0 0x00000000 0x02000000 + 1 0x02000000 0x02000000>; + bank-width = <2>; + addr-gpios = <&gpio1 2 GPIO_ACTIVE_HIGH>; + partition@0 { + label = "test-part1"; + reg = <0 0x04000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml new file mode 100644 index 000000000000..199ba5ac2a06 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -0,0 +1,143 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/nand-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NAND Chip and NAND Controller Generic Binding + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + - Richard Weinberger <richard@nod.at> + +description: | + The NAND controller should be represented with its own DT node, and + all NAND chips attached to this controller should be defined as + children nodes of the NAND controller. This representation should be + enforced even for simple controllers supporting only one chip. + + The ECC strength and ECC step size properties define the user + desires in terms of correction capability of a controller. Together, + they request the ECC engine to correct {strength} bit errors per + {size} bytes. + + The interpretation of these parameters is implementation-defined, so + not all implementations must support all possible + combinations. However, implementations are encouraged to further + specify the value(s) they support. + +properties: + $nodename: + pattern: "^nand-controller(@.*)?" + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + ranges: true + +patternProperties: + "^nand@[a-f0-9]$": + properties: + reg: + description: + Contains the native Ready/Busy IDs. + + nand-ecc-mode: + allOf: + - $ref: /schemas/types.yaml#/definitions/string + - enum: [ none, soft, hw, hw_syndrome, hw_oob_first, on-die ] + description: + Desired ECC engine, either hardware (most of the time + embedded in the NAND controller) or software correction + (Linux will handle the calculations). soft_bch is deprecated + and should be replaced by soft and nand-ecc-algo. + + nand-ecc-algo: + allOf: + - $ref: /schemas/types.yaml#/definitions/string + - enum: [ hamming, bch, rs ] + description: + Desired ECC algorithm. + + nand-bus-width: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - enum: [ 8, 16 ] + - default: 8 + description: + Bus width to the NAND chip + + nand-on-flash-bbt: + $ref: /schemas/types.yaml#/definitions/flag + description: + With this property, the OS will search the device for a Bad + Block Table (BBT). If not found, it will create one, reserve + a few blocks at the end of the device to store it and update + it as the device ages. Otherwise, the out-of-band area of a + few pages of all the blocks will be scanned at boot time to + find Bad Block Markers (BBM). These markers will help to + build a volatile BBT in RAM. + + nand-ecc-strength: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - minimum: 1 + description: + Maximum number of bits that can be corrected per ECC step. + + nand-ecc-step-size: + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - minimum: 1 + description: + Number of data bytes covered by a single ECC step. + + nand-ecc-maximize: + $ref: /schemas/types.yaml#/definitions/flag + description: + Whether or not the ECC strength should be maximized. The + maximum ECC strength is both controller and chip + dependent. The ECC engine has to select the ECC config + providing the best strength and taking the OOB area size + constraint into account. This is particularly useful when + only the in-band area is used by the upper layers, and you + want to make your NAND as reliable as possible. + + nand-is-boot-medium: + $ref: /schemas/types.yaml#/definitions/flag + description: + Whether or not the NAND chip is a boot medium. Drivers might + use this information to select ECC algorithms supported by + the boot ROM or similar restrictions. + + nand-rb: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + Contains the native Ready/Busy IDs. + + required: + - reg + +required: + - "#address-cells" + - "#size-cells" + +examples: + - | + nand-controller { + #address-cells = <1>; + #size-cells = <0>; + + /* controller specific properties */ + + nand@0 { + reg = <0>; + nand-ecc-mode = "soft"; + nand-ecc-algo = "bch"; + + /* controller specific properties */ + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/nand.txt b/Documentation/devicetree/bindings/mtd/nand.txt deleted file mode 100644 index e949c778e983..000000000000 --- a/Documentation/devicetree/bindings/mtd/nand.txt +++ /dev/null @@ -1,75 +0,0 @@ -* NAND chip and NAND controller generic binding - -NAND controller/NAND chip representation: - -The NAND controller should be represented with its own DT node, and all -NAND chips attached to this controller should be defined as children nodes -of the NAND controller. This representation should be enforced even for -simple controllers supporting only one chip. - -Mandatory NAND controller properties: -- #address-cells: depends on your controller. Should at least be 1 to - encode the CS line id. -- #size-cells: depends on your controller. Put zero unless you need a - mapping between CS lines and dedicated memory regions - -Optional NAND controller properties -- ranges: only needed if you need to define a mapping between CS lines and - memory regions - -Optional NAND chip properties: - -- nand-ecc-mode : String, operation mode of the NAND ecc mode. - Supported values are: "none", "soft", "hw", "hw_syndrome", - "hw_oob_first", "on-die". - Deprecated values: - "soft_bch": use "soft" and nand-ecc-algo instead -- nand-ecc-algo: string, algorithm of NAND ECC. - Valid values are: "hamming", "bch", "rs". -- nand-bus-width : 8 or 16 bus width if not present 8 -- nand-on-flash-bbt: boolean to enable on flash bbt option if not present false - -- nand-ecc-strength: integer representing the number of bits to correct - per ECC step. - -- nand-ecc-step-size: integer representing the number of data bytes - that are covered by a single ECC step. - -- nand-ecc-maximize: boolean used to specify that you want to maximize ECC - strength. The maximum ECC strength is both controller and - chip dependent. The controller side has to select the ECC - config providing the best strength and taking the OOB area - size constraint into account. - This is particularly useful when only the in-band area is - used by the upper layers, and you want to make your NAND - as reliable as possible. -- nand-is-boot-medium: Whether the NAND chip is a boot medium. Drivers might use - this information to select ECC algorithms supported by - the boot ROM or similar restrictions. - -- nand-rb: shall contain the native Ready/Busy ids. - -The ECC strength and ECC step size properties define the correction capability -of a controller. Together, they say a controller can correct "{strength} bit -errors per {size} bytes". - -The interpretation of these parameters is implementation-defined, so not all -implementations must support all possible combinations. However, implementations -are encouraged to further specify the value(s) they support. - -Example: - - nand-controller { - #address-cells = <1>; - #size-cells = <0>; - - /* controller specific properties */ - - nand@0 { - reg = <0>; - nand-ecc-mode = "soft"; - nand-ecc-algo = "bch"; - - /* controller specific properties */ - }; - }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.txt b/Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.txt new file mode 100644 index 000000000000..d5c5616f6db5 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/arm,arm-firmware-suite.txt @@ -0,0 +1,17 @@ +ARM AFS - ARM Firmware Suite Partitions +======================================= + +The ARM Firmware Suite is a flash partitioning system found on the +ARM reference designs: Integrator AP, Integrator CP, Versatile AB, +Versatile PB, the RealView family, Versatile Express and Juno. + +Required properties: +- compatible : (required) must be "arm,arm-firmware-suite" + +Example: + +flash@0 { + partitions { + compatible = "arm,arm-firmware-suite"; + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-cfe-nor-partitions.txt b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-cfe-nor-partitions.txt new file mode 100644 index 000000000000..9f630e95f180 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-cfe-nor-partitions.txt @@ -0,0 +1,24 @@ +Broadcom BCM963XX CFE Loader NOR Flash Partitions +================================================= + +Most Broadcom BCM63XX SoC based devices follow the Broadcom reference layout for +NOR. The first erase block used for the CFE bootloader, the last for an +NVRAM partition, and the remainder in-between for one to two firmware partitions +at fixed offsets. A valid firmware partition is identified by the ImageTag +header found at beginning of the second erase block, containing the rootfs and +kernel offsets and sizes within the firmware partition. + +Required properties: +- compatible : must be "brcm,bcm963xx-cfe-nor-partitions" + +Example: + +flash@1fc00000 { + compatible = "cfi-flash"; + reg = <0x1fc00000 0x400000>; + bank-width = <2>; + + partitions { + compatible = "brcm,bcm963xx-cfe-nor-partitions"; + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-imagetag.txt b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-imagetag.txt new file mode 100644 index 000000000000..f8b7418ed817 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/brcm,bcm963xx-imagetag.txt @@ -0,0 +1,45 @@ +Broadcom BCM963XX ImageTag Partition Container +============================================== + +Some Broadcom BCM63XX SoC based devices contain additional, non discoverable +partitions or non standard bootloader partition sizes. For these a mixed layout +needs to be used with an explicit firmware partition. + +The BCM963XX ImageTag is a simple firmware header describing the offsets and +sizes of the rootfs and kernel parts contained in the firmware. + +Required properties: +- compatible : must be "brcm,bcm963xx-imagetag" + +Example: + +flash@1e000000 { + compatible = "cfi-flash"; + reg = <0x1e000000 0x2000000>; + bank-width = <2>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + cfe@0 { + reg = <0x0 0x10000>; + read-only; + }; + + firmware@10000 { + reg = <0x10000 0x7d0000>; + compatible = "brcm,bcm963xx-imagetag"; + }; + + caldata@7e0000 { + reg = <0x7e0000 0x10000>; + read-only; + }; + + nvram@7f0000 { + reg = <0x7f0000 0x10000>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/sunxi-nand.txt b/Documentation/devicetree/bindings/mtd/sunxi-nand.txt deleted file mode 100644 index dcd5a5d80dc0..000000000000 --- a/Documentation/devicetree/bindings/mtd/sunxi-nand.txt +++ /dev/null @@ -1,48 +0,0 @@ -Allwinner NAND Flash Controller (NFC) - -Required properties: -- compatible : "allwinner,sun4i-a10-nand". -- reg : shall contain registers location and length for data and reg. -- interrupts : shall define the nand controller interrupt. -- #address-cells: shall be set to 1. Encode the nand CS. -- #size-cells : shall be set to 0. -- clocks : shall reference nand controller clocks. -- clock-names : nand controller internal clock names. Shall contain : - * "ahb" : AHB gating clock - * "mod" : nand controller clock - -Optional properties: -- dmas : shall reference DMA channel associated to the NAND controller. -- dma-names : shall be "rxtx". - -Optional children nodes: -Children nodes represent the available nand chips. - -Optional properties: -- reset : phandle + reset specifier pair -- reset-names : must contain "ahb" -- allwinner,rb : shall contain the native Ready/Busy ids. -- nand-ecc-mode : one of the supported ECC modes ("hw", "soft", "soft_bch" or - "none") - -see Documentation/devicetree/bindings/mtd/nand.txt for generic bindings. - - -Examples: -nfc: nand@1c03000 { - compatible = "allwinner,sun4i-a10-nand"; - reg = <0x01c03000 0x1000>; - interrupts = <0 37 1>; - clocks = <&ahb_gates 13>, <&nand_clk>; - clock-names = "ahb", "mod"; - #address-cells = <1>; - #size-cells = <0>; - pinctrl-names = "default"; - pinctrl-0 = <&nand_pins_a &nand_cs0_pins_a &nand_rb0_pins_a>; - - nand@0 { - reg = <0>; - allwinner,rb = <0>; - nand-ecc-mode = "soft_bch"; - }; -}; diff --git a/Documentation/devicetree/bindings/net/altera_tse.txt b/Documentation/devicetree/bindings/net/altera_tse.txt index 0e21df94a53f..0b7d4d3758ea 100644 --- a/Documentation/devicetree/bindings/net/altera_tse.txt +++ b/Documentation/devicetree/bindings/net/altera_tse.txt @@ -46,9 +46,8 @@ Required properties: - reg: phy id used to communicate to phy. - device_type: Must be "ethernet-phy". -Optional properties: -- local-mac-address: See ethernet.txt in the same directory. -- max-frame-size: See ethernet.txt in the same directory. +The MAC address will be determined using the optional properties defined in +ethernet.txt. Example: diff --git a/Documentation/devicetree/bindings/net/amd-xgbe.txt b/Documentation/devicetree/bindings/net/amd-xgbe.txt index 93dcb79a5f16..9c27dfcd1133 100644 --- a/Documentation/devicetree/bindings/net/amd-xgbe.txt +++ b/Documentation/devicetree/bindings/net/amd-xgbe.txt @@ -24,8 +24,6 @@ Required properties: - phy-mode: See ethernet.txt file in the same directory Optional properties: -- mac-address: mac address to be assigned to the device. Can be overridden - by UEFI. - dma-coherent: Present if dma operations are coherent - amd,per-channel-interrupt: Indicates that Rx and Tx complete will generate a unique interrupt for each DMA channel - this requires an additional @@ -34,6 +32,9 @@ Optional properties: 0 - 1GbE and 10GbE (default) 1 - 2.5GbE and 10GbE +The MAC address will be determined using the optional properties defined in +ethernet.txt. + The following optional properties are represented by an array with each value corresponding to a particular speed. The first array value represents the setting for the 1GbE speed, the second value for the 2.5GbE speed and diff --git a/Documentation/devicetree/bindings/net/brcm,amac.txt b/Documentation/devicetree/bindings/net/brcm,amac.txt index 0bfad656a9ff..0120ebe93262 100644 --- a/Documentation/devicetree/bindings/net/brcm,amac.txt +++ b/Documentation/devicetree/bindings/net/brcm,amac.txt @@ -16,8 +16,8 @@ Required properties: registers (required for Northstar2) - interrupts: Interrupt number -Optional properties: -- mac-address: See ethernet.txt file in the same directory +The MAC address will be determined using the optional properties +defined in ethernet.txt. Examples: diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index 3264e1978d25..7c7ac5eb0313 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -49,10 +49,12 @@ Required properties: Optional properties: - dual_emac_res_vlan : Specifies VID to be used to segregate the ports -- mac-address : See ethernet.txt file in the same directory - phy_id : Specifies slave phy id (deprecated, use phy-handle) - phy-handle : See ethernet.txt file in the same directory +The MAC address will be determined using the optional properties +defined in ethernet.txt. + Slave sub-nodes: - fixed-link : See fixed-link.txt file in the same directory diff --git a/Documentation/devicetree/bindings/net/davinci_emac.txt b/Documentation/devicetree/bindings/net/davinci_emac.txt index ca83dcc84fb8..5e3579e72e2d 100644 --- a/Documentation/devicetree/bindings/net/davinci_emac.txt +++ b/Documentation/devicetree/bindings/net/davinci_emac.txt @@ -20,11 +20,12 @@ Required properties: Optional properties: - phy-handle: See ethernet.txt file in the same directory. If absent, davinci_emac driver defaults to 100/FULL. -- nvmem-cells: phandle, reference to an nvmem node for the MAC address -- nvmem-cell-names: string, should be "mac-address" if nvmem is to be used - ti,davinci-rmii-en: 1 byte, 1 means use RMII - ti,davinci-no-bd-ram: boolean, does EMAC have BD RAM? +The MAC address will be determined using the optional properties +defined in ethernet.txt. + Example (enbw_cmc board): eth0: emac@1e20000 { compatible = "ti,davinci-dm6467-emac"; diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index d66a5292b9d3..f66bb7ecdb82 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -1,12 +1,6 @@ Distributed Switch Architecture Device Tree Bindings ---------------------------------------------------- -Two bindings exist, one of which has been deprecated due to -limitations. - -Current Binding ---------------- - Switches are true Linux devices and can be probed by any means. Once probed, they register to the DSA framework, passing a node pointer. This node is expected to fulfil the following binding, and @@ -71,9 +65,8 @@ properties, described in binding documents: Documentation/devicetree/bindings/net/fixed-link.txt for details. -- local-mac-address : See - Documentation/devicetree/bindings/net/ethernet.txt - for details. +The MAC address will be determined using the optional properties +defined in ethernet.txt. Example @@ -262,152 +255,3 @@ linked into one DSA cluster. }; }; }; - -Deprecated Binding ------------------- - -The deprecated binding makes use of a platform device to represent the -switches. The switches themselves are not Linux devices, and make use -of an MDIO bus for management. - -Required properties: -- compatible : Should be "marvell,dsa" -- #address-cells : Must be 2, first cell is the address on the MDIO bus - and second cell is the address in the switch tree. - Second cell is used only when cascading/chaining. -- #size-cells : Must be 0 -- dsa,ethernet : Should be a phandle to a valid Ethernet device node -- dsa,mii-bus : Should be a phandle to a valid MDIO bus device node - -Optional properties: -- interrupts : property with a value describing the switch - interrupt number (not supported by the driver) - -A DSA node can contain multiple switch chips which are therefore child nodes of -the parent DSA node. The maximum number of allowed child nodes is 4 -(DSA_MAX_SWITCHES). -Each of these switch child nodes should have the following required properties: - -- reg : Contains two fields. The first one describes the - address on the MII bus. The second is the switch - number that must be unique in cascaded configurations -- #address-cells : Must be 1 -- #size-cells : Must be 0 - -A switch child node has the following optional property: - -- eeprom-length : Set to the length of an EEPROM connected to the - switch. Must be set if the switch can not detect - the presence and/or size of a connected EEPROM, - otherwise optional. - -A switch may have multiple "port" children nodes - -Each port children node must have the following mandatory properties: -- reg : Describes the port address in the switch -- label : Describes the label associated with this port, special - labels are "cpu" to indicate a CPU port and "dsa" to - indicate an uplink/downlink port. - -Note that a port labelled "dsa" will imply checking for the uplink phandle -described below. - -Optional property: -- link : Should be a list of phandles to another switch's DSA port. - This property is only used when switches are being - chained/cascaded together. This port is used as outgoing port - towards the phandle port, which can be more than one hop away. - -- phy-handle : Phandle to a PHY on an external MDIO bus, not the - switch internal one. See - Documentation/devicetree/bindings/net/ethernet.txt - for details. - -- phy-mode : String representing the connection to the designated - PHY node specified by the 'phy-handle' property. See - Documentation/devicetree/bindings/net/ethernet.txt - for details. - -- mii-bus : Should be a phandle to a valid MDIO bus device node. - This mii-bus will be used in preference to the - global dsa,mii-bus defined above, for this switch. - -Optional subnodes: -- fixed-link : Fixed-link subnode describing a link to a non-MDIO - managed entity. See - Documentation/devicetree/bindings/net/fixed-link.txt - for details. - -Example: - - dsa@0 { - compatible = "marvell,dsa"; - #address-cells = <2>; - #size-cells = <0>; - - interrupts = <10>; - dsa,ethernet = <ðernet0>; - dsa,mii-bus = <&mii_bus0>; - - switch@0 { - #address-cells = <1>; - #size-cells = <0>; - reg = <16 0>; /* MDIO address 16, switch 0 in tree */ - - port@0 { - reg = <0>; - label = "lan1"; - phy-handle = <&phy0>; - }; - - port@1 { - reg = <1>; - label = "lan2"; - }; - - port@5 { - reg = <5>; - label = "cpu"; - }; - - switch0port6: port@6 { - reg = <6>; - label = "dsa"; - link = <&switch1port0 - &switch2port0>; - }; - }; - - switch@1 { - #address-cells = <1>; - #size-cells = <0>; - reg = <17 1>; /* MDIO address 17, switch 1 in tree */ - mii-bus = <&mii_bus1>; - reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; - - switch1port0: port@0 { - reg = <0>; - label = "dsa"; - link = <&switch0port6>; - }; - switch1port1: port@1 { - reg = <1>; - label = "dsa"; - link = <&switch2port1>; - }; - }; - - switch@2 { - #address-cells = <1>; - #size-cells = <0>; - reg = <18 2>; /* MDIO address 18, switch 2 in tree */ - mii-bus = <&mii_bus1>; - - switch2port0: port@0 { - reg = <0>; - label = "dsa"; - link = <&switch1port1 - &switch0port6>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/net/dsa/sja1105.txt b/Documentation/devicetree/bindings/net/dsa/sja1105.txt new file mode 100644 index 000000000000..13fd21074d48 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/sja1105.txt @@ -0,0 +1,156 @@ +NXP SJA1105 switch driver +========================= + +Required properties: + +- compatible: + Must be one of: + - "nxp,sja1105e" + - "nxp,sja1105t" + - "nxp,sja1105p" + - "nxp,sja1105q" + - "nxp,sja1105r" + - "nxp,sja1105s" + + Although the device ID could be detected at runtime, explicit bindings + are required in order to be able to statically check their validity. + For example, SGMII can only be specified on port 4 of R and S devices, + and the non-SGMII devices, while pin-compatible, are not equal in terms + of support for RGMII internal delays (supported on P/Q/R/S, but not on + E/T). + +Optional properties: + +- sja1105,role-mac: +- sja1105,role-phy: + Boolean properties that can be assigned under each port node. By + default (unless otherwise specified) a port is configured as MAC if it + is driving a PHY (phy-handle is present) or as PHY if it is PHY-less + (fixed-link specified, presumably because it is connected to a MAC). + The effect of this property (in either its implicit or explicit form) + is: + - In the case of MII or RMII it specifies whether the SJA1105 port is a + clock source or sink for this interface (not applicable for RGMII + where there is a Tx and an Rx clock). + - In the case of RGMII it affects the behavior regarding internal + delays: + 1. If sja1105,role-mac is specified, and the phy-mode property is one + of "rgmii-id", "rgmii-txid" or "rgmii-rxid", then the entity + designated to apply the delay/clock skew necessary for RGMII + is the PHY. The SJA1105 MAC does not apply any internal delays. + 2. If sja1105,role-phy is specified, and the phy-mode property is one + of the above, the designated entity to apply the internal delays + is the SJA1105 MAC (if hardware-supported). This is only supported + by the second-generation (P/Q/R/S) hardware. On a first-generation + E or T device, it is an error to specify an RGMII phy-mode other + than "rgmii" for a port that is in fixed-link mode. In that case, + the clock skew must either be added by the MAC at the other end of + the fixed-link, or by PCB serpentine traces on the board. + These properties are required, for example, in the case where SJA1105 + ports are at both ends of a MII/RMII PHY-less setup. One end would need + to have sja1105,role-mac, while the other sja1105,role-phy. + +See Documentation/devicetree/bindings/net/dsa/dsa.txt for the list of standard +DSA required and optional properties. + +Other observations +------------------ + +The SJA1105 SPI interface requires a CS-to-CLK time (t2 in UM10944) of at least +one half of t_CLK. At an SPI frequency of 1MHz, this means a minimum +cs_sck_delay of 500ns. Ensuring that this SPI timing requirement is observed +depends on the SPI bus master driver. + +Example +------- + +Ethernet switch connected via SPI to the host, CPU port wired to enet2: + +arch/arm/boot/dts/ls1021a-tsn.dts: + +/* SPI controller of the LS1021 */ +&dspi0 { + sja1105@1 { + reg = <0x1>; + #address-cells = <1>; + #size-cells = <0>; + compatible = "nxp,sja1105t"; + spi-max-frequency = <4000000>; + fsl,spi-cs-sck-delay = <1000>; + fsl,spi-sck-cs-delay = <1000>; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + /* ETH5 written on chassis */ + label = "swp5"; + phy-handle = <&rgmii_phy6>; + phy-mode = "rgmii-id"; + reg = <0>; + /* Implicit "sja1105,role-mac;" */ + }; + port@1 { + /* ETH2 written on chassis */ + label = "swp2"; + phy-handle = <&rgmii_phy3>; + phy-mode = "rgmii-id"; + reg = <1>; + /* Implicit "sja1105,role-mac;" */ + }; + port@2 { + /* ETH3 written on chassis */ + label = "swp3"; + phy-handle = <&rgmii_phy4>; + phy-mode = "rgmii-id"; + reg = <2>; + /* Implicit "sja1105,role-mac;" */ + }; + port@3 { + /* ETH4 written on chassis */ + phy-handle = <&rgmii_phy5>; + label = "swp4"; + phy-mode = "rgmii-id"; + reg = <3>; + /* Implicit "sja1105,role-mac;" */ + }; + port@4 { + /* Internal port connected to eth2 */ + ethernet = <&enet2>; + phy-mode = "rgmii"; + reg = <4>; + /* Implicit "sja1105,role-phy;" */ + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + }; + }; +}; + +/* MDIO controller of the LS1021 */ +&mdio0 { + /* BCM5464 */ + rgmii_phy3: ethernet-phy@3 { + reg = <0x3>; + }; + rgmii_phy4: ethernet-phy@4 { + reg = <0x4>; + }; + rgmii_phy5: ethernet-phy@5 { + reg = <0x5>; + }; + rgmii_phy6: ethernet-phy@6 { + reg = <0x6>; + }; +}; + +/* Ethernet master port of the LS1021 */ +&enet2 { + phy-connection-type = "rgmii"; + status = "ok"; + fixed-link { + speed = <1000>; + full-duplex; + }; +}; diff --git a/Documentation/devicetree/bindings/net/ethernet.txt b/Documentation/devicetree/bindings/net/ethernet.txt index a68621580584..e88c3641d613 100644 --- a/Documentation/devicetree/bindings/net/ethernet.txt +++ b/Documentation/devicetree/bindings/net/ethernet.txt @@ -4,12 +4,14 @@ NOTE: All 'phy*' properties documented below are Ethernet specific. For the generic PHY 'phys' property, see Documentation/devicetree/bindings/phy/phy-bindings.txt. -- local-mac-address: array of 6 bytes, specifies the MAC address that was - assigned to the network device; - mac-address: array of 6 bytes, specifies the MAC address that was last used by the boot program; should be used in cases where the MAC address assigned to the device by the boot program is different from the "local-mac-address" property; +- local-mac-address: array of 6 bytes, specifies the MAC address that was + assigned to the network device; +- nvmem-cells: phandle, reference to an nvmem node for the MAC address +- nvmem-cell-names: string, should be "mac-address" if nvmem is to be used - max-speed: number, specifies maximum speed in Mbit/s supported by the device; - max-frame-size: number, maximum transfer unit (IEEE defined MTU), rather than the maximum frame size (there's contradiction in the Devicetree @@ -36,7 +38,7 @@ Documentation/devicetree/bindings/phy/phy-bindings.txt. * "smii" * "xgmii" * "trgmii" - * "2000base-x", + * "1000base-x", * "2500base-x", * "rxaui" * "xaui" diff --git a/Documentation/devicetree/bindings/net/hisilicon-femac.txt b/Documentation/devicetree/bindings/net/hisilicon-femac.txt index d11af5ecace8..5f96976f3cea 100644 --- a/Documentation/devicetree/bindings/net/hisilicon-femac.txt +++ b/Documentation/devicetree/bindings/net/hisilicon-femac.txt @@ -14,7 +14,6 @@ Required properties: the PHY reset signal(optional). - reset-names: should contain the reset signal name "mac"(required) and "phy"(optional). -- mac-address: see ethernet.txt [1]. - phy-mode: see ethernet.txt [1]. - phy-handle: see ethernet.txt [1]. - hisilicon,phy-reset-delays-us: triplet of delays if PHY reset signal given. @@ -22,6 +21,9 @@ Required properties: The 2nd cell is reset pulse in micro seconds. The 3rd cell is reset post-delay in micro seconds. +The MAC address will be determined using the optional properties +defined in ethernet.txt[1]. + [1] Documentation/devicetree/bindings/net/ethernet.txt Example: diff --git a/Documentation/devicetree/bindings/net/hisilicon-hix5hd2-gmac.txt b/Documentation/devicetree/bindings/net/hisilicon-hix5hd2-gmac.txt index eea73adc678f..cddf46bf6b63 100644 --- a/Documentation/devicetree/bindings/net/hisilicon-hix5hd2-gmac.txt +++ b/Documentation/devicetree/bindings/net/hisilicon-hix5hd2-gmac.txt @@ -18,7 +18,6 @@ Required properties: - #size-cells: must be <0>. - phy-mode: see ethernet.txt [1]. - phy-handle: see ethernet.txt [1]. -- mac-address: see ethernet.txt [1]. - clocks: clock phandle and specifier pair. - clock-names: contain the clock name "mac_core"(required) and "mac_ifc"(optional). - resets: should contain the phandle to the MAC core reset signal(optional), @@ -31,6 +30,9 @@ Required properties: The 2nd cell is reset pulse in micro seconds. The 3rd cell is reset post-delay in micro seconds. +The MAC address will be determined using the properties defined in +ethernet.txt[1]. + - PHY subnode: inherits from phy binding [2] [1] Documentation/devicetree/bindings/net/ethernet.txt diff --git a/Documentation/devicetree/bindings/net/keystone-netcp.txt b/Documentation/devicetree/bindings/net/keystone-netcp.txt index 04ba1dc34fd6..6262c2f293b0 100644 --- a/Documentation/devicetree/bindings/net/keystone-netcp.txt +++ b/Documentation/devicetree/bindings/net/keystone-netcp.txt @@ -135,14 +135,14 @@ Optional properties: are swapped. The netcp driver will swap the two DWORDs back to the proper order when this property is set to 2 when it obtains the mac address from efuse. -- local-mac-address: the driver is designed to use the of_get_mac_address api - only if efuse-mac is 0. When efuse-mac is 0, the MAC - address is obtained from local-mac-address. If this - attribute is not present, then the driver will use a - random MAC address. - "netcp-device label": phandle to the device specification for each of NetCP sub-module attached to this interface. +The MAC address will be determined using the optional properties defined in +ethernet.txt and only if efuse-mac is set to 0. If all of the optional MAC +address properties are not present, then the driver will use a random MAC +address. + Example binding: netcp: netcp@2000000 { diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt index 8b80515729d7..9c5e94482b5f 100644 --- a/Documentation/devicetree/bindings/net/macb.txt +++ b/Documentation/devicetree/bindings/net/macb.txt @@ -26,9 +26,8 @@ Required properties: Optional elements: 'tsu_clk' - clocks: Phandles to input clocks. -Optional properties: -- nvmem-cells: phandle, reference to an nvmem node for the MAC address -- nvmem-cell-names: string, should be "mac-address" if nvmem is to be used +The MAC address will be determined using the optional properties +defined in ethernet.txt. Optional properties for PHY child node: - reset-gpios : Should specify the gpio for phy reset diff --git a/Documentation/devicetree/bindings/net/marvell-pxa168.txt b/Documentation/devicetree/bindings/net/marvell-pxa168.txt index 845a148a346e..5574af3554aa 100644 --- a/Documentation/devicetree/bindings/net/marvell-pxa168.txt +++ b/Documentation/devicetree/bindings/net/marvell-pxa168.txt @@ -11,7 +11,9 @@ Optional properties: - #address-cells: must be 1 when using sub-nodes. - #size-cells: must be 0 when using sub-nodes. - phy-handle: see ethernet.txt file in the same directory. -- local-mac-address: see ethernet.txt file in the same directory. + +The MAC address will be determined using the optional properties +defined in ethernet.txt. Sub-nodes: Each PHY can be represented as a sub-node. This is not mandatory. diff --git a/Documentation/devicetree/bindings/net/mdio-mux-meson-g12a.txt b/Documentation/devicetree/bindings/net/mdio-mux-meson-g12a.txt new file mode 100644 index 000000000000..3a96cbed9294 --- /dev/null +++ b/Documentation/devicetree/bindings/net/mdio-mux-meson-g12a.txt @@ -0,0 +1,48 @@ +Properties for the MDIO bus multiplexer/glue of Amlogic G12a SoC family. + +This is a special case of a MDIO bus multiplexer. It allows to choose between +the internal mdio bus leading to the embedded 10/100 PHY or the external +MDIO bus. + +Required properties in addition to the generic multiplexer properties: +- compatible : amlogic,g12a-mdio-mux +- reg: physical address and length of the multiplexer/glue registers +- clocks: list of clock phandle, one for each entry clock-names. +- clock-names: should contain the following: + * "pclk" : peripheral clock. + * "clkin0" : platform crytal + * "clkin1" : SoC 50MHz MPLL + +Example : + +mdio_mux: mdio-multiplexer@4c000 { + compatible = "amlogic,g12a-mdio-mux"; + reg = <0x0 0x4c000 0x0 0xa4>; + clocks = <&clkc CLKID_ETH_PHY>, + <&xtal>, + <&clkc CLKID_MPLL_5OM>; + clock-names = "pclk", "clkin0", "clkin1"; + mdio-parent-bus = <&mdio0>; + #address-cells = <1>; + #size-cells = <0>; + + ext_mdio: mdio@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + int_mdio: mdio@1 { + reg = <1>; + #address-cells = <1>; + #size-cells = <0>; + + internal_ephy: ethernet-phy@8 { + compatible = "ethernet-phy-id0180.3301", + "ethernet-phy-ieee802.3-c22"; + interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>; + reg = <8>; + max-speed = <100>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/microchip,enc28j60.txt b/Documentation/devicetree/bindings/net/microchip,enc28j60.txt index 24626e082b83..a8275921a896 100644 --- a/Documentation/devicetree/bindings/net/microchip,enc28j60.txt +++ b/Documentation/devicetree/bindings/net/microchip,enc28j60.txt @@ -21,8 +21,9 @@ Optional properties: - spi-max-frequency: Maximum frequency of the SPI bus when accessing the ENC28J60. According to the ENC28J80 datasheet, the chip allows a maximum of 20 MHz, however, board designs may need to limit this value. -- local-mac-address: See ethernet.txt in the same directory. +The MAC address will be determined using the optional properties +defined in ethernet.txt. Example (for NXP i.MX28 with pin control stuff for GPIO irq): diff --git a/Documentation/devicetree/bindings/net/microchip,lan78xx.txt b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt index 76786a0f6d3d..11a679530ae6 100644 --- a/Documentation/devicetree/bindings/net/microchip,lan78xx.txt +++ b/Documentation/devicetree/bindings/net/microchip,lan78xx.txt @@ -7,9 +7,8 @@ The Device Tree properties, if present, override the OTP and EEPROM. Required properties: - compatible: Should be one of "usb424,7800", "usb424,7801" or "usb424,7850". -Optional properties: -- local-mac-address: see ethernet.txt -- mac-address: see ethernet.txt +The MAC address will be determined using the optional properties +defined in ethernet.txt. Optional properties of the embedded PHY: - microchip,led-modes: a 0..4 element vector, with each element configuring diff --git a/Documentation/devicetree/bindings/net/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index 17c1d2bd00f6..9b9e5b1765dd 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -51,6 +51,10 @@ Optional Properties: to ensure the integrated PHY is used. The absence of this property indicates the muxers should be configured so that the external PHY is used. +- resets: The reset-controller phandle and specifier for the PHY reset signal. + +- reset-names: Must be "phy" for the PHY reset signal. + - reset-gpios: The GPIO phandle and specifier for the PHY reset signal. - reset-assert-us: Delay after the reset was asserted in microseconds. @@ -67,6 +71,8 @@ ethernet-phy@0 { interrupts = <35 IRQ_TYPE_EDGE_RISING>; reg = <0>; + resets = <&rst 8>; + reset-names = "phy"; reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>; reset-assert-us = <1000>; reset-deassert-us = <2000>; diff --git a/Documentation/devicetree/bindings/net/qca,qca7000.txt b/Documentation/devicetree/bindings/net/qca,qca7000.txt index e4a8a51086df..21c36e524993 100644 --- a/Documentation/devicetree/bindings/net/qca,qca7000.txt +++ b/Documentation/devicetree/bindings/net/qca,qca7000.txt @@ -23,7 +23,6 @@ Optional properties: Numbers smaller than 1000000 or greater than 16000000 are invalid. Missing the property will set the SPI frequency to 8000000 Hertz. -- local-mac-address : see ./ethernet.txt - qca,legacy-mode : Set the SPI data transfer of the QCA7000 to legacy mode. In this mode the SPI master must toggle the chip select between each data word. In burst mode these gaps aren't @@ -31,6 +30,9 @@ Optional properties: the QCA7000 is setup via GPIO pin strapping. If the property is missing the driver defaults to burst mode. +The MAC address will be determined using the optional properties +defined in ethernet.txt. + SPI Example: /* Freescale i.MX28 SPI master*/ diff --git a/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt b/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt index 824c0e23c544..7ef6118abd3d 100644 --- a/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt +++ b/Documentation/devicetree/bindings/net/qualcomm-bluetooth.txt @@ -11,20 +11,21 @@ Required properties: - compatible: should contain one of the following: * "qcom,qca6174-bt" * "qcom,wcn3990-bt" + * "qcom,wcn3998-bt" Optional properties for compatible string qcom,qca6174-bt: - enable-gpios: gpio specifier used to enable chip - clocks: clock provided to the controller (SUSCLK_32KHZ) -Required properties for compatible string qcom,wcn3990-bt: +Required properties for compatible string qcom,wcn399x-bt: - vddio-supply: VDD_IO supply regulator handle. - vddxo-supply: VDD_XO supply regulator handle. - vddrf-supply: VDD_RF supply regulator handle. - vddch0-supply: VDD_CH0 supply regulator handle. -Optional properties for compatible string qcom,wcn3990-bt: +Optional properties for compatible string qcom,wcn399x-bt: - max-speed: see Documentation/devicetree/bindings/serial/slave-device.txt diff --git a/Documentation/devicetree/bindings/net/samsung-sxgbe.txt b/Documentation/devicetree/bindings/net/samsung-sxgbe.txt index 46e591178911..2cff6d8a585a 100644 --- a/Documentation/devicetree/bindings/net/samsung-sxgbe.txt +++ b/Documentation/devicetree/bindings/net/samsung-sxgbe.txt @@ -21,10 +21,12 @@ Required properties: range. Optional properties: -- mac-address: 6 bytes, mac address - max-frame-size: Maximum Transfer Unit (IEEE defined MTU), rather than the maximum frame size. +The MAC address will be determined using the optional properties +defined in ethernet.txt. + Example: aliases { diff --git a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt index 36f1aef585f0..ad3c6e109ce1 100644 --- a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt +++ b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt @@ -103,8 +103,6 @@ Required properties: Optional properties: - dma-coherent: Present if dma operations are coherent -- mac-address: See ethernet.txt in the same directory -- local-mac-address: See ethernet.txt in the same directory - phy-reset-gpios: Phandle and specifier for any GPIO used to reset the PHY. See ../gpio/gpio.txt. - snps,en-lpi: If present it enables use of the AXI low-power interface @@ -133,6 +131,9 @@ Optional properties: - device_type: Must be "ethernet-phy". - fixed-mode device tree subnode: see fixed-link.txt in the same directory +The MAC address will be determined using the optional properties +defined in ethernet.txt. + Examples: ethernet2@40010000 { clock-names = "phy_ref_clk", "apb_pclk"; diff --git a/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt index fc8f01718690..4e85fc495e87 100644 --- a/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt +++ b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt @@ -31,8 +31,8 @@ Required properties: - socionext,syscon-phy-mode: A phandle to syscon with one argument that configures phy mode. The argument is the ID of MAC instance. -Optional properties: - - local-mac-address: See ethernet.txt in the same directory. +The MAC address will be determined using the optional properties +defined in ethernet.txt. Required subnode: - mdio: A container for child nodes representing phy nodes. diff --git a/Documentation/devicetree/bindings/net/socionext-netsec.txt b/Documentation/devicetree/bindings/net/socionext-netsec.txt index 0cff94fb0433..9d6c9feb12ff 100644 --- a/Documentation/devicetree/bindings/net/socionext-netsec.txt +++ b/Documentation/devicetree/bindings/net/socionext-netsec.txt @@ -26,11 +26,12 @@ Required properties: Optional properties: (See ethernet.txt file in the same directory) - dma-coherent: Boolean property, must only be present if memory accesses performed by the device are cache coherent. -- local-mac-address: See ethernet.txt in the same directory. -- mac-address: See ethernet.txt in the same directory. - max-speed: See ethernet.txt in the same directory. - max-frame-size: See ethernet.txt in the same directory. +The MAC address will be determined using the optional properties +defined in ethernet.txt. + Example: eth0: ethernet@522d0000 { compatible = "socionext,synquacer-netsec"; diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt index 7b9a776230c0..7e675dafc256 100644 --- a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt @@ -13,11 +13,12 @@ properties: Optional properties: -- mac-address: See ethernet.txt in the parent directory -- local-mac-address: See ethernet.txt in the parent directory - ieee80211-freq-limit: See ieee80211.txt - mediatek,mtd-eeprom: Specify a MTD partition + offset containing EEPROM data +The MAC address can as well be set with corresponding optional properties +defined in net/ethernet.txt. + Optional nodes: - led: Properties for a connected LED Optional properties: diff --git a/Documentation/devicetree/bindings/net/wireless/qca,ath9k.txt b/Documentation/devicetree/bindings/net/wireless/qca,ath9k.txt index b7396c8c271c..aaaeeb5f935b 100644 --- a/Documentation/devicetree/bindings/net/wireless/qca,ath9k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qca,ath9k.txt @@ -34,9 +34,9 @@ Optional properties: ath9k wireless chip (in this case the calibration / EEPROM data will be loaded from userspace using the kernel firmware loader). -- mac-address: See ethernet.txt in the parent directory -- local-mac-address: See ethernet.txt in the parent directory +The MAC address will be determined using the optional properties defined in +net/ethernet.txt. In this example, the node is defined as child node of the PCI controller: &pci0 { diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt index 99c4ba6a3f61..cfb18b4ef8f7 100644 --- a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt +++ b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt @@ -8,11 +8,12 @@ Required properties: "allwinner,sun8i-h3-sid" "allwinner,sun50i-a64-sid" "allwinner,sun50i-h5-sid" + "allwinner,sun50i-h6-sid" - reg: Should contain registers location and length = Data cells = -Are child nodes of qfprom, bindings of which as described in +Are child nodes of sunxi-sid, bindings of which as described in bindings/nvmem/nvmem.txt Example for sun4i: diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt index 7a999a135e56..68f7d6fdd140 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -1,7 +1,8 @@ Freescale i.MX6 On-Chip OTP Controller (OCOTP) device tree bindings This binding represents the on-chip eFuse OTP controller found on -i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX, i.MX6UL, i.MX6ULL/ULZ and i.MX6SLL SoCs. +i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX, i.MX6UL, i.MX6ULL/ULZ, i.MX6SLL, +i.MX7D/S, i.MX7ULP and i.MX8MQ SoCs. Required properties: - compatible: should be one of @@ -13,6 +14,7 @@ Required properties: "fsl,imx7d-ocotp" (i.MX7D/S), "fsl,imx6sll-ocotp" (i.MX6SLL), "fsl,imx7ulp-ocotp" (i.MX7ULP), + "fsl,imx8mq-ocotp" (i.MX8MQ), followed by "syscon". - #address-cells : Should be 1 - #size-cells : Should be 1 diff --git a/Documentation/devicetree/bindings/nvmem/st,stm32-romem.txt b/Documentation/devicetree/bindings/nvmem/st,stm32-romem.txt new file mode 100644 index 000000000000..142a51d5a9be --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/st,stm32-romem.txt @@ -0,0 +1,31 @@ +STMicroelectronics STM32 Factory-programmed data device tree bindings + +This represents STM32 Factory-programmed read only non-volatile area: locked +flash, OTP, read-only HW regs... This contains various information such as: +analog calibration data for temperature sensor (e.g. TS_CAL1, TS_CAL2), +internal vref (VREFIN_CAL), unique device ID... + +Required properties: +- compatible: Should be one of: + "st,stm32f4-otp" + "st,stm32mp15-bsec" +- reg: Offset and length of factory-programmed area. +- #address-cells: Should be '<1>'. +- #size-cells: Should be '<1>'. + +Optional Data cells: +- Must be child nodes as described in nvmem.txt. + +Example on stm32f4: + romem: nvmem@1fff7800 { + compatible = "st,stm32f4-otp"; + reg = <0x1fff7800 0x400>; + #address-cells = <1>; + #size-cells = <1>; + + /* Data cells: ts_cal1 at 0x1fff7a2c */ + ts_cal1: calib@22c { + reg = <0x22c 0x2>; + }; + ... + }; diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt index c124f9bc11f3..5561a1c060d0 100644 --- a/Documentation/devicetree/bindings/pci/designware-pcie.txt +++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt @@ -4,8 +4,11 @@ Required properties: - compatible: "snps,dw-pcie" for RC mode; "snps,dw-pcie-ep" for EP mode; -- reg: Should contain the configuration address space. -- reg-names: Must be "config" for the PCIe configuration space. +- reg: For designware cores version < 4.80 contains the configuration + address space. For designware core version >= 4.80, contains + the configuration and ATU address space +- reg-names: Must be "config" for the PCIe configuration space and "atu" for + the ATU address 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 diff --git a/Documentation/devicetree/bindings/pci/pci-keystone.txt b/Documentation/devicetree/bindings/pci/pci-keystone.txt index 2030ee0dc4f9..47202a2938f2 100644 --- a/Documentation/devicetree/bindings/pci/pci-keystone.txt +++ b/Documentation/devicetree/bindings/pci/pci-keystone.txt @@ -11,16 +11,24 @@ described here as well as properties that are not applicable. Required Properties:- -compatibility: "ti,keystone-pcie" -reg: index 1 is the base address and length of DW application registers. - index 2 is the base address and length of PCI device ID register. +compatibility: Should be "ti,keystone-pcie" for RC on Keystone2 SoC + Should be "ti,am654-pcie-rc" for RC on AM654x SoC +reg: Three register ranges as listed in the reg-names property +reg-names: "dbics" for the DesignWare PCIe registers, "app" for the + TI specific application registers, "config" for the + configuration space address pcie_msi_intc : Interrupt controller device node for MSI IRQ chip interrupt-cells: should be set to 1 interrupts: GIC interrupt lines connected to PCI MSI interrupt lines + (required if the compatible is "ti,keystone-pcie") +msi-map: As specified in Documentation/devicetree/bindings/pci/pci-msi.txt + (required if the compatible is "ti,am654-pcie-rc". ti,syscon-pcie-id : phandle to the device control module required to set device id and vendor id. +ti,syscon-pcie-mode : phandle to the device control module required to configure + PCI in either RC mode or EP mode. Example: pcie_msi_intc: msi-interrupt-controller { @@ -61,3 +69,47 @@ Optional properties:- DesignWare DT Properties not applicable for Keystone PCI 1. pcie_bus clock-names not used. Instead, a phandle to phys is used. + +AM654 PCIe Endpoint +=================== + +Required Properties:- + +compatibility: Should be "ti,am654-pcie-ep" for EP on AM654x SoC +reg: Four register ranges as listed in the reg-names property +reg-names: "dbics" for the DesignWare PCIe registers, "app" for the + TI specific application registers, "atu" for the + Address Translation Unit configuration registers and + "addr_space" used to map remote RC address space +num-ib-windows: As specified in + Documentation/devicetree/bindings/pci/designware-pcie.txt +num-ob-windows: As specified in + Documentation/devicetree/bindings/pci/designware-pcie.txt +num-lanes: As specified in + Documentation/devicetree/bindings/pci/designware-pcie.txt +power-domains: As documented by the generic PM domain bindings in + Documentation/devicetree/bindings/power/power_domain.txt. +ti,syscon-pcie-mode: phandle to the device control module required to configure + PCI in either RC mode or EP mode. + +Optional properties:- + +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 lanes as specified in *num-lanes* property. +("phys" and "phy-names" DT bindings are specified in +Documentation/devicetree/bindings/phy/phy-bindings.txt) +interrupts: platform interrupt for error interrupts. + +pcie-ep { + compatible = "ti,am654-pcie-ep"; + reg = <0x5500000 0x1000>, <0x5501000 0x1000>, + <0x10000000 0x8000000>, <0x5506000 0x1000>; + reg-names = "app", "dbics", "addr_space", "atu"; + power-domains = <&k3_pds 120>; + ti,syscon-pcie-mode = <&pcie0_mode>; + num-lanes = <1>; + num-ib-windows = <16>; + num-ob-windows = <16>; + interrupts = <GIC_SPI 340 IRQ_TYPE_EDGE_RISING>; +}; diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt index c77981c5dd18..92c01db610df 100644 --- a/Documentation/devicetree/bindings/pci/pci.txt +++ b/Documentation/devicetree/bindings/pci/pci.txt @@ -24,3 +24,53 @@ driver implementation may support the following properties: unsupported link speed, for instance, trying to do training for unsupported link speed, etc. Must be '4' for gen4, '3' for gen3, '2' for gen2, and '1' for gen1. Any other values are invalid. + +PCI-PCI Bridge properties +------------------------- + +PCIe root ports and switch ports may be described explicitly in the device +tree, as children of the host bridge node. Even though those devices are +discoverable by probing, it might be necessary to describe properties that +aren't provided by standard PCIe capabilities. + +Required properties: + +- reg: + Identifies the PCI-PCI bridge. As defined in the IEEE Std 1275-1994 + document, it is a five-cell address encoded as (phys.hi phys.mid + phys.lo size.hi size.lo). phys.hi should contain the device's BDF as + 0b00000000 bbbbbbbb dddddfff 00000000. The other cells should be zero. + + The bus number is defined by firmware, through the standard bridge + configuration mechanism. If this port is a switch port, then firmware + allocates the bus number and writes it into the Secondary Bus Number + register of the bridge directly above this port. Otherwise, the bus + number of a root port is the first number in the bus-range property, + defaulting to zero. + + If firmware leaves the ARI Forwarding Enable bit set in the bridge + above this port, then phys.hi contains the 8-bit function number as + 0b00000000 bbbbbbbb ffffffff 00000000. Note that the PCIe specification + recommends that firmware only leaves ARI enabled when it knows that the + OS is ARI-aware. + +Optional properties: + +- external-facing: + When present, the port is external-facing. All bridges and endpoints + downstream of this port are external to the machine. The OS can, for + example, use this information to identify devices that cannot be + trusted with relaxed DMA protection, as users could easily attach + malicious devices to this port. + +Example: + +pcie@10000000 { + compatible = "pci-host-ecam-generic"; + ... + pcie@0008 { + /* Root port 00:01.0 is external-facing */ + reg = <0x00000800 0 0 0 0>; + external-facing; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/brcm,stingray-usb-phy.txt b/Documentation/devicetree/bindings/phy/brcm,stingray-usb-phy.txt new file mode 100644 index 000000000000..4ba298966af9 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/brcm,stingray-usb-phy.txt @@ -0,0 +1,32 @@ +Broadcom Stingray USB PHY + +Required properties: + - compatible : should be one of the listed compatibles + - "brcm,sr-usb-combo-phy" is combo PHY has two PHYs, one SS and one HS. + - "brcm,sr-usb-hs-phy" is a single HS PHY. + - reg: offset and length of the PHY blocks registers + - #phy-cells: + - Must be 1 for brcm,sr-usb-combo-phy as it expects one argument to indicate + the PHY number of two PHYs. 0 for HS PHY and 1 for SS PHY. + - Must be 0 for brcm,sr-usb-hs-phy. + +Refer to phy/phy-bindings.txt for the generic PHY binding properties + +Example: + usbphy0: usb-phy@0 { + compatible = "brcm,sr-usb-combo-phy"; + reg = <0x00000000 0x100>; + #phy-cells = <1>; + }; + + usbphy1: usb-phy@10000 { + compatible = "brcm,sr-usb-combo-phy"; + reg = <0x00010000 0x100>, + #phy-cells = <1>; + }; + + usbphy2: usb-phy@20000 { + compatible = "brcm,sr-usb-hs-phy"; + reg = <0x00020000 0x100>, + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt b/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt index a22e853d710c..ed47e5cd067e 100644 --- a/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt @@ -7,6 +7,9 @@ Required properties: - clocks: phandles to the clocks for each clock listed in clock-names - clock-names: must contain "phy" +Optional properties: +- vbus-supply: A phandle to the regulator for USB VBUS. + Example: usb3_phy0: phy@381f0040 { compatible = "fsl,imx8mq-usb-phy"; diff --git a/Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt b/Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt new file mode 100644 index 000000000000..a6ebc3dea159 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt @@ -0,0 +1,22 @@ +* Amlogic G12A USB2 PHY binding + +Required properties: +- compatible: Should be "amlogic,meson-g12a-usb2-phy" +- reg: The base address and length of the registers +- #phys-cells: must be 0 (see phy-bindings.txt in this directory) +- clocks: a phandle to the clock of this PHY +- clock-names: must be "xtal" +- resets: a phandle to the reset line of this PHY +- reset-names: must be "phy" +- phy-supply: see phy-bindings.txt in this directory + +Example: + usb2_phy0: phy@36000 { + compatible = "amlogic,g12a-usb2-phy"; + reg = <0x0 0x36000 0x0 0x2000>; + clocks = <&xtal>; + clock-names = "xtal"; + resets = <&reset RESET_USB_PHY21>; + reset-names = "phy"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt b/Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt new file mode 100644 index 000000000000..7cfc17e2df31 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt @@ -0,0 +1,22 @@ +* Amlogic G12A USB3 + PCIE Combo PHY binding + +Required properties: +- compatible: Should be "amlogic,meson-g12a-usb3-pcie-phy" +- #phys-cells: must be 1. The cell number is used to select the phy mode + as defined in <dt-bindings/phy/phy.h> between PHY_TYPE_USB3 and PHY_TYPE_PCIE +- reg: The base address and length of the registers +- clocks: a phandle to the 100MHz reference clock of this PHY +- clock-names: must be "ref_clk" +- resets: phandle to the reset lines for the PHY control +- reset-names: must be "phy" + +Example: + usb3_pcie_phy: phy@46000 { + compatible = "amlogic,g12a-usb3-pcie-phy"; + reg = <0x0 0x46000 0x0 0x2000>; + clocks = <&clkc CLKID_PCIE_PLL>; + clock-names = "ref_clk"; + resets = <&reset RESET_PCIE_PHY>; + reset-names = "phy"; + #phy-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt index 3742c152c467..daedb15f322e 100644 --- a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt @@ -36,11 +36,20 @@ Required properties: - Tegra124: "nvidia,tegra124-xusb-padctl" - Tegra132: "nvidia,tegra132-xusb-padctl", "nvidia,tegra124-xusb-padctl" - Tegra210: "nvidia,tegra210-xusb-padctl" + - Tegra186: "nvidia,tegra186-xusb-padctl" - reg: Physical base address and length of the controller's registers. - resets: Must contain an entry for each entry in reset-names. - reset-names: Must include the following entries: - "padctl" +For Tegra186: +- avdd-pll-erefeut-supply: UPHY brick and reference clock as well as UTMI PHY + power supply. Must supply 1.8 V. +- avdd-usb-supply: USB I/Os, VBUS, ID, REXT, D+/D- power supply. Must supply + 3.3 V. +- vclamp-usb-supply: Bias rail for USB pad. Must supply 1.8 V. +- vddio-hsic-supply: HSIC PHY power supply. Must supply 1.2 V. + Pad nodes: ========== diff --git a/Documentation/devicetree/bindings/phy/phy-hi3660-usb3.txt b/Documentation/devicetree/bindings/phy/phy-hi3660-usb3.txt new file mode 100644 index 000000000000..e88ba7d92dcb --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-hi3660-usb3.txt @@ -0,0 +1,26 @@ +Hisilicon hi3660 USB PHY +----------------------- + +Required properties: +- compatible: should be "hisilicon,hi3660-usb-phy" +- #phy-cells: must be 0 +- hisilicon,pericrg-syscon: phandle of syscon used to control phy. +- hisilicon,pctrl-syscon: phandle of syscon used to control phy. +- hisilicon,eye-diagram-param: parameter set for phy +Refer to phy/phy-bindings.txt for the generic PHY binding properties + +This is a subnode of usb3_otg_bc register node. + +Example: + usb3_otg_bc: usb3_otg_bc@ff200000 { + compatible = "syscon", "simple-mfd"; + reg = <0x0 0xff200000 0x0 0x1000>; + + usb-phy { + compatible = "hisilicon,hi3660-usb-phy"; + #phy-cells = <0>; + hisilicon,pericrg-syscon = <&crg_ctrl>; + hisilicon,pctrl-syscon = <&pctrl>; + hisilicon,eye-diagram-param = <0x22466e4>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-mtk-ufs.txt b/Documentation/devicetree/bindings/phy/phy-mtk-ufs.txt new file mode 100644 index 000000000000..5789029a1d42 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-mtk-ufs.txt @@ -0,0 +1,38 @@ +MediaTek Universal Flash Storage (UFS) M-PHY binding +-------------------------------------------------------- + +UFS M-PHY nodes are defined to describe on-chip UFS M-PHY hardware macro. +Each UFS M-PHY node should have its own node. + +To bind UFS M-PHY with UFS host controller, the controller node should +contain a phandle reference to UFS M-PHY node. + +Required properties for UFS M-PHY nodes: +- compatible : Compatible list, contains the following controller: + "mediatek,mt8183-ufsphy" for ufs phy + persent on MT81xx chipsets. +- reg : Address and length of the UFS M-PHY register set. +- #phy-cells : This property shall be set to 0. +- clocks : List of phandle and clock specifier pairs. +- clock-names : List of clock input name strings sorted in the same + order as the clocks property. Following clocks are + mandatory. + "unipro": Unipro core control clock. + "mp": M-PHY core control clock. + +Example: + + ufsphy: phy@11fa0000 { + compatible = "mediatek,mt8183-ufsphy"; + reg = <0 0x11fa0000 0 0xc000>; + #phy-cells = <0>; + + clocks = <&infracfg_ao INFRACFG_AO_UNIPRO_SCK_CG>, + <&infracfg_ao INFRACFG_AO_UFS_MP_SAP_BCLK_CG>; + clock-names = "unipro", "mp"; + }; + + ufshci@11270000 { + ... + phys = <&ufsphy>; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt index 5d181fc3cc18..085fbd676cfc 100644 --- a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt +++ b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt @@ -11,6 +11,7 @@ Required properties: "qcom,msm8996-qmp-usb3-phy" for 14nm USB3 phy on msm8996, "qcom,msm8998-qmp-usb3-phy" for USB3 QMP V3 phy on msm8998, "qcom,msm8998-qmp-ufs-phy" for UFS QMP phy on msm8998, + "qcom,msm8998-qmp-pcie-phy" for PCIe QMP phy on msm8998, "qcom,sdm845-qmp-usb3-phy" for USB3 QMP V3 phy on sdm845, "qcom,sdm845-qmp-usb3-uni-phy" for USB3 QMP V3 UNI phy on sdm845, "qcom,sdm845-qmp-ufs-phy" for UFS QMP phy on sdm845. @@ -48,6 +49,8 @@ Required properties: "aux", "cfg_ahb", "ref". For "qcom,msm8998-qmp-ufs-phy" must contain: "ref", "ref_aux". + For "qcom,msm8998-qmp-pcie-phy" must contain: + "aux", "cfg_ahb", "ref". For "qcom,sdm845-qmp-usb3-phy" must contain: "aux", "cfg_ahb", "ref", "com_aux". For "qcom,sdm845-qmp-usb3-uni-phy" must contain: @@ -59,7 +62,8 @@ Required properties: 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. + "cfg" for phy's ahb cfg block reset, + "ufsphy" for the PHY reset in the UFS controller. For "qcom,ipq8074-qmp-pcie-phy" must contain: "phy", "common". @@ -69,12 +73,16 @@ Required properties: "phy", "common". For "qcom,msm8998-qmp-usb3-phy" must contain "phy", "common". - For "qcom,msm8998-qmp-ufs-phy": no resets are listed. + For "qcom,msm8998-qmp-ufs-phy": must contain: + "ufsphy". + For "qcom,msm8998-qmp-pcie-phy" must contain: + "phy", "common". For "qcom,sdm845-qmp-usb3-phy" must contain: "phy", "common". For "qcom,sdm845-qmp-usb3-uni-phy" must contain: "phy", "common". - For "qcom,sdm845-qmp-ufs-phy": no resets are listed. + For "qcom,sdm845-qmp-ufs-phy": must contain: + "ufsphy". - 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. diff --git a/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt b/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt index 4f0879a0ca12..ac96d6481bb8 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt @@ -7,6 +7,7 @@ Required properties: - compatible: "renesas,usb-phy-r8a7743" if the device is a part of R8A7743 SoC. "renesas,usb-phy-r8a7744" if the device is a part of R8A7744 SoC. "renesas,usb-phy-r8a7745" if the device is a part of R8A7745 SoC. + "renesas,usb-phy-r8a77470" if the device is a part of R8A77470 SoC. "renesas,usb-phy-r8a7790" if the device is a part of R8A7790 SoC. "renesas,usb-phy-r8a7791" if the device is a part of R8A7791 SoC. "renesas,usb-phy-r8a7794" if the device is a part of R8A7794 SoC. @@ -30,7 +31,7 @@ channels. These subnodes must contain the following properties: - #phy-cells: see phy-bindings.txt in the same directory, must be <1>. The phandle's argument in the PHY specifier is the USB controller selector for -the USB channel; see the selector meanings below: +the USB channel other than r8a77470 SoC; see the selector meanings below: +-----------+---------------+---------------+ |\ Selector | | | @@ -41,6 +42,16 @@ the USB channel; see the selector meanings below: | 2 | PCI EHCI/OHCI | xHCI | +-----------+---------------+---------------+ +For r8a77470 SoC;see the selector meaning below: + ++-----------+---------------+---------------+ +|\ Selector | | | ++ --------- + 0 | 1 | +| Channel \| | | ++-----------+---------------+---------------+ +| 0 | EHCI/OHCI | HS-USB | ++-----------+---------------+---------------+ + Example (Lager board): usb-phy@e6590100 { @@ -48,15 +59,53 @@ Example (Lager board): reg = <0 0xe6590100 0 0x100>; #address-cells = <1>; #size-cells = <0>; - clocks = <&mstp7_clks R8A7790_CLK_HSUSB>; + clocks = <&cpg CPG_MOD 704>; clock-names = "usbhs"; + power-domains = <&sysc R8A7790_PD_ALWAYS_ON>; + resets = <&cpg 704>; - usb-channel@0 { + usb0: usb-channel@0 { reg = <0>; #phy-cells = <1>; }; - usb-channel@2 { + usb2: usb-channel@2 { reg = <2>; #phy-cells = <1>; }; }; + +Example (iWave RZ/G1C sbc): + + usbphy0: usb-phy0@e6590100 { + compatible = "renesas,usb-phy-r8a77470", + "renesas,rcar-gen2-usb-phy"; + reg = <0 0xe6590100 0 0x100>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&cpg CPG_MOD 704>; + clock-names = "usbhs"; + power-domains = <&sysc R8A77470_PD_ALWAYS_ON>; + resets = <&cpg 704>; + + usb0: usb-channel@0 { + reg = <0>; + #phy-cells = <1>; + }; + }; + + usbphy1: usb-phy@e6598100 { + compatible = "renesas,usb-phy-r8a77470", + "renesas,rcar-gen2-usb-phy"; + reg = <0 0xe6598100 0 0x100>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&cpg CPG_MOD 706>; + clock-names = "usbhs"; + power-domains = <&sysc R8A77470_PD_ALWAYS_ON>; + resets = <&cpg 706>; + + usb1: usb-channel@0 { + reg = <0>; + #phy-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt index ad9c290d8f15..d46188f450bf 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt @@ -1,10 +1,12 @@ * Renesas R-Car generation 3 USB 2.0 PHY This file provides information on what the device node for the R-Car generation -3 and RZ/G2 USB 2.0 PHY contain. +3, RZ/G1C and RZ/G2 USB 2.0 PHY contain. Required properties: -- compatible: "renesas,usb2-phy-r8a774a1" if the device is a part of an R8A774A1 +- compatible: "renesas,usb2-phy-r8a77470" if the device is a part of an R8A77470 + SoC. + "renesas,usb2-phy-r8a774a1" if the device is a part of an R8A774A1 SoC. "renesas,usb2-phy-r8a774c0" if the device is a part of an R8A774C0 SoC. @@ -27,7 +29,13 @@ Required properties: - reg: offset and length of the partial USB 2.0 Host register block. - clocks: clock phandle and specifier pair(s). -- #phy-cells: see phy-bindings.txt in the same directory, must be <0>. +- #phy-cells: see phy-bindings.txt in the same directory, must be <1> (and + using <0> is deprecated). + +The phandle's argument in the PHY specifier is the INT_STATUS bit of controller: +- 1 = USBH_INTA (OHCI) +- 2 = USBH_INTB (EHCI) +- 3 = UCOM_INT (OTG and BC) Optional properties: To use a USB channel where USB 2.0 Host and HSUSB (USB 2.0 Peripheral) are diff --git a/Documentation/devicetree/bindings/phy/rockchip-emmc-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-emmc-phy.txt index e3ea55763b0a..e728786f21e0 100644 --- a/Documentation/devicetree/bindings/phy/rockchip-emmc-phy.txt +++ b/Documentation/devicetree/bindings/phy/rockchip-emmc-phy.txt @@ -7,12 +7,15 @@ Required properties: - reg: PHY register address offset and length in "general register files" -Optional clocks using the clock bindings (see ../clock/clock-bindings.txt), -specified by name: +Optional properties: - clock-names: Should contain "emmcclk". Although this is listed as optional (because most boards can get basic functionality without having access to it), it is strongly suggested. + See ../clock/clock-bindings.txt for details. - clocks: Should have a phandle to the card clock exported by the SDHCI driver. + - drive-impedance-ohm: Specifies the drive impedance in Ohm. + Possible values are 33, 40, 50, 66 and 100. + If not set, the default value of 50 will be applied. Example: @@ -29,6 +32,7 @@ grf: syscon@ff770000 { reg = <0xf780 0x20>; clocks = <&sdhci>; clock-names = "emmcclk"; + drive-impedance-ohm = <50>; #phy-cells = <0>; }; }; diff --git a/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.txt b/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.txt new file mode 100644 index 000000000000..64b286d2d398 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/ti,phy-am654-serdes.txt @@ -0,0 +1,82 @@ +TI AM654 SERDES + +Required properties: + - compatible: Should be "ti,phy-am654-serdes" + - reg : Address and length of the register set for the device. + - #phy-cells: determine the number of cells that should be given in the + phandle while referencing this phy. Should be "2". The 1st cell + corresponds to the phy type (should be one of the types specified in + include/dt-bindings/phy/phy.h) and the 2nd cell should be the serdes + lane function. + If SERDES0 is referenced 2nd cell should be: + 0 - USB3 + 1 - PCIe0 Lane0 + 2 - ICSS2 SGMII Lane0 + If SERDES1 is referenced 2nd cell should be: + 0 - PCIe1 Lane0 + 1 - PCIe0 Lane1 + 2 - ICSS2 SGMII Lane1 + - power-domains: As documented by the generic PM domain bindings in + Documentation/devicetree/bindings/power/power_domain.txt. + - clocks: List of clock-specifiers representing the input to the SERDES. + Should have 3 items representing the left input clock, external + reference clock and right input clock in that order. + - clock-output-names: List of clock names for each of the clock outputs of + SERDES. Should have 3 items for CMU reference clock, + left output clock and right output clock in that order. + - assigned-clocks: As defined in + Documentation/devicetree/bindings/clock/clock-bindings.txt + - assigned-clock-parents: As defined in + Documentation/devicetree/bindings/clock/clock-bindings.txt + - #clock-cells: Should be <1> to choose between the 3 output clocks. + Defined in Documentation/devicetree/bindings/clock/clock-bindings.txt + + The following macros are defined in dt-bindings/phy/phy-am654-serdes.h + for selecting the correct reference clock. This can be used while + specifying the clocks created by SERDES. + => AM654_SERDES_CMU_REFCLK + => AM654_SERDES_LO_REFCLK + => AM654_SERDES_RO_REFCLK + + - mux-controls: Phandle to the multiplexer that is used to select the lane + function. See #phy-cells above to see the multiplex values. + +Example: + +Example for SERDES0 is given below. It has 3 clock inputs; +left input reference clock as indicated by <&k3_clks 153 4>, external +reference clock as indicated by <&k3_clks 153 1> and right input +reference clock as indicated by <&serdes1 AM654_SERDES_LO_REFCLK>. (The +right input of SERDES0 is connected to the left output of SERDES1). + +SERDES0 registers 3 clock outputs as indicated in clock-output-names. The +first refers to the CMU reference clock, second refers to the left output +reference clock and the third refers to the right output reference clock. + +The assigned-clocks and assigned-clock-parents is used here to set the +parent of left input reference clock to MAINHSDIV_CLKOUT4 and parent of +CMU reference clock to left input reference clock. + +serdes0: serdes@900000 { + compatible = "ti,phy-am654-serdes"; + reg = <0x0 0x900000 0x0 0x2000>; + reg-names = "serdes"; + #phy-cells = <2>; + power-domains = <&k3_pds 153>; + clocks = <&k3_clks 153 4>, <&k3_clks 153 1>, + <&serdes1 AM654_SERDES_LO_REFCLK>; + clock-output-names = "serdes0_cmu_refclk", "serdes0_lo_refclk", + "serdes0_ro_refclk"; + assigned-clocks = <&k3_clks 153 4>, <&serdes0 AM654_SERDES_CMU_REFCLK>; + assigned-clock-parents = <&k3_clks 153 8>, <&k3_clks 153 4>; + ti,serdes-clk = <&serdes0_clk>; + mux-controls = <&serdes_mux 0>; + #clock-cells = <1>; +}; + +Example for PCIe consumer node using the SERDES PHY specifier is given below. +&pcie0_rc { + num-lanes = <2>; + phys = <&serdes0 PHY_TYPE_PCIE 1>, <&serdes1 PHY_TYPE_PCIE 1>; + phy-names = "pcie-phy0", "pcie-phy1"; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt new file mode 100644 index 000000000000..ed34bb1ee81c --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/bitmain,bm1880-pinctrl.txt @@ -0,0 +1,98 @@ +Bitmain BM1880 Pin Controller + +This binding describes the pin controller found in the BM1880 SoC. + +Required Properties: + +- compatible: Should be "bitmain,bm1880-pinctrl" +- reg: Offset and length of pinctrl space in SCTRL. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration for BM1880 SoC +includes only pinmux as there is no pinconf support available in SoC. + +Each configuration node can consist of multiple nodes describing the pinmux +options. The name of each subnode is not important; all subnodes should be +enumerated and processed purely based on their content. + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pinmux subnode: + +Required Properties: + +- pins: An array of strings, each string containing the name of a pin. + Valid values for pins are: + + MIO0 - MIO111 + +- groups: An array of strings, each string containing the name of a pin + group. Valid values for groups are: + + nand_grp, spi_grp, emmc_grp, sdio_grp, eth0_grp, pwm0_grp, + pwm1_grp, pwm2_grp, pwm3_grp, pwm4_grp, pwm5_grp, pwm6_grp, + pwm7_grp, pwm8_grp, pwm9_grp, pwm10_grp, pwm11_grp, pwm12_grp, + pwm13_grp, pwm14_grp, pwm15_grp, pwm16_grp, pwm17_grp, + pwm18_grp, pwm19_grp, pwm20_grp, pwm21_grp, pwm22_grp, + pwm23_grp, pwm24_grp, pwm25_grp, pwm26_grp, pwm27_grp, + pwm28_grp, pwm29_grp, pwm30_grp, pwm31_grp, pwm32_grp, + pwm33_grp, pwm34_grp, pwm35_grp, pwm36_grp, i2c0_grp, + i2c1_grp, i2c2_grp, i2c3_grp, i2c4_grp, uart0_grp, uart1_grp, + uart2_grp, uart3_grp, uart4_grp, uart5_grp, uart6_grp, + uart7_grp, uart8_grp, uart9_grp, uart10_grp, uart11_grp, + uart12_grp, uart13_grp, uart14_grp, uart15_grp, gpio0_grp, + gpio1_grp, gpio2_grp, gpio3_grp, gpio4_grp, gpio5_grp, + gpio6_grp, gpio7_grp, gpio8_grp, gpio9_grp, gpio10_grp, + gpio11_grp, gpio12_grp, gpio13_grp, gpio14_grp, gpio15_grp, + gpio16_grp, gpio17_grp, gpio18_grp, gpio19_grp, gpio20_grp, + gpio21_grp, gpio22_grp, gpio23_grp, gpio24_grp, gpio25_grp, + gpio26_grp, gpio27_grp, gpio28_grp, gpio29_grp, gpio30_grp, + gpio31_grp, gpio32_grp, gpio33_grp, gpio34_grp, gpio35_grp, + gpio36_grp, gpio37_grp, gpio38_grp, gpio39_grp, gpio40_grp, + gpio41_grp, gpio42_grp, gpio43_grp, gpio44_grp, gpio45_grp, + gpio46_grp, gpio47_grp, gpio48_grp, gpio49_grp, gpio50_grp, + gpio51_grp, gpio52_grp, gpio53_grp, gpio54_grp, gpio55_grp, + gpio56_grp, gpio57_grp, gpio58_grp, gpio59_grp, gpio60_grp, + gpio61_grp, gpio62_grp, gpio63_grp, gpio64_grp, gpio65_grp, + gpio66_grp, gpio67_grp, eth1_grp, i2s0_grp, i2s0_mclkin_grp, + i2s1_grp, i2s1_mclkin_grp, spi0_grp + +- function: An array of strings, each string containing the name of the + pinmux functions. The following are the list of pinmux + functions available: + + nand, spi, emmc, sdio, eth0, pwm0, pwm1, pwm2, pwm3, pwm4, + pwm5, pwm6, pwm7, pwm8, pwm9, pwm10, pwm11, pwm12, pwm13, + pwm14, pwm15, pwm16, pwm17, pwm18, pwm19, pwm20, pwm21, pwm22, + pwm23, pwm24, pwm25, pwm26, pwm27, pwm28, pwm29, pwm30, pwm31, + pwm32, pwm33, pwm34, pwm35, pwm36, i2c0, i2c1, i2c2, i2c3, + i2c4, uart0, uart1, uart2, uart3, uart4, uart5, uart6, uart7, + uart8, uart9, uart10, uart11, uart12, uart13, uart14, uart15, + gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7, gpio8, + gpio9, gpio10, gpio11, gpio12, gpio13, gpio14, gpio15, gpio16, + gpio17, gpio18, gpio19, gpio20, gpio21, gpio22, gpio23, + gpio24, gpio25, gpio26, gpio27, gpio28, gpio29, gpio30, + gpio31, gpio32, gpio33, gpio34, gpio35, gpio36, gpio37, + gpio38, gpio39, gpio40, gpio41, gpio42, gpio43, gpio44, + gpio45, gpio46, gpio47, gpio48, gpio49, gpio50, gpio51, + gpio52, gpio53, gpio54, gpio55, gpio56, gpio57, gpio58, + gpio59, gpio60, gpio61, gpio62, gpio63, gpio64, gpio65, + gpio66, gpio67, eth1, i2s0, i2s0_mclkin, i2s1, i2s1_mclkin, + spi0 + +Example: + pinctrl: pinctrl@50 { + compatible = "bitmain,bm1880-pinctrl"; + reg = <0x50 0x4B0>; + + pinctrl_uart0_default: uart0-default { + pinmux { + groups = "uart0_grp"; + function = "uart0"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.txt new file mode 100644 index 000000000000..a87447180e83 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/cirrus,lochnagar.txt @@ -0,0 +1,141 @@ +Cirrus Logic Lochnagar Audio Development Board + +Lochnagar is an evaluation and development board for Cirrus Logic +Smart CODEC and Amp devices. It allows the connection of most Cirrus +Logic devices on mini-cards, as well as allowing connection of +various application processor systems to provide a full evaluation +platform. Audio system topology, clocking and power can all be +controlled through the Lochnagar, allowing the device under test +to be used in a variety of possible use cases. + +This binding document describes the binding for the pinctrl portion +of the driver. + +Also see these documents for generic binding information: + [1] GPIO : ../gpio/gpio.txt + [2] Pinctrl: ../pinctrl/pinctrl-bindings.txt + +And these for relevant defines: + [3] include/dt-bindings/pinctrl/lochnagar.h + +This binding must be part of the Lochnagar MFD binding: + [4] ../mfd/cirrus,lochnagar.txt + +Required properties: + + - compatible : One of the following strings: + "cirrus,lochnagar-pinctrl" + + - gpio-controller : Indicates this device is a GPIO controller. + - #gpio-cells : Must be 2. The first cell is the pin number, see + [3] for available pins and the second cell is used to specify + optional parameters, see [1]. + - gpio-ranges : Range of pins managed by the GPIO controller, see + [1]. Both the GPIO and Pinctrl base should be set to zero and the + count to the appropriate of the LOCHNAGARx_PIN_NUM_GPIOS define, + see [3]. + + - pinctrl-names : A pinctrl state named "default" must be defined. + - pinctrl-0 : A phandle to the default pinctrl state. + +Required sub-nodes: + +The pin configurations are defined as a child of the pinctrl states +node, see [2]. Each sub-node can have the following properties: + - groups : A list of groups to select (either this or "pins" must be + specified), available groups: + codec-aif1, codec-aif2, codec-aif3, dsp-aif1, dsp-aif2, psia1, + psia2, gf-aif1, gf-aif2, gf-aif3, gf-aif4, spdif-aif, usb-aif1, + usb-aif2, adat-aif, soundcard-aif + - pins : A list of pin names to select (either this or "groups" must + be specified), available pins: + fpga-gpio1, fpga-gpio2, fpga-gpio3, fpga-gpio4, fpga-gpio5, + fpga-gpio6, codec-gpio1, codec-gpio2, codec-gpio3, codec-gpio4, + codec-gpio5, codec-gpio6, codec-gpio7, codec-gpio8, dsp-gpio1, + dsp-gpio2, dsp-gpio3, dsp-gpio4, dsp-gpio5, dsp-gpio6, gf-gpio2, + gf-gpio3, gf-gpio7, codec-aif1-bclk, codec-aif1-rxdat, + codec-aif1-lrclk, codec-aif1-txdat, codec-aif2-bclk, + codec-aif2-rxdat, codec-aif2-lrclk, codec-aif2-txdat, + codec-aif3-bclk, codec-aif3-rxdat, codec-aif3-lrclk, + codec-aif3-txdat, dsp-aif1-bclk, dsp-aif1-rxdat, dsp-aif1-lrclk, + dsp-aif1-txdat, dsp-aif2-bclk, dsp-aif2-rxdat, + dsp-aif2-lrclk, dsp-aif2-txdat, psia1-bclk, psia1-rxdat, + psia1-lrclk, psia1-txdat, psia2-bclk, psia2-rxdat, psia2-lrclk, + psia2-txdat, gf-aif3-bclk, gf-aif3-rxdat, gf-aif3-lrclk, + gf-aif3-txdat, gf-aif4-bclk, gf-aif4-rxdat, gf-aif4-lrclk, + gf-aif4-txdat, gf-aif1-bclk, gf-aif1-rxdat, gf-aif1-lrclk, + gf-aif1-txdat, gf-aif2-bclk, gf-aif2-rxdat, gf-aif2-lrclk, + gf-aif2-txdat, dsp-uart1-rx, dsp-uart1-tx, dsp-uart2-rx, + dsp-uart2-tx, gf-uart2-rx, gf-uart2-tx, usb-uart-rx, + codec-pdmclk1, codec-pdmdat1, codec-pdmclk2, codec-pdmdat2, + codec-dmicclk1, codec-dmicdat1, codec-dmicclk2, codec-dmicdat2, + codec-dmicclk3, codec-dmicdat3, codec-dmicclk4, codec-dmicdat4, + dsp-dmicclk1, dsp-dmicdat1, dsp-dmicclk2, dsp-dmicdat2, i2c2-scl, + i2c2-sda, i2c3-scl, i2c3-sda, i2c4-scl, i2c4-sda, dsp-standby, + codec-mclk1, codec-mclk2, dsp-clkin, psia1-mclk, psia2-mclk, + gf-gpio1, gf-gpio5, dsp-gpio20, led1, led2 + - function : The mux function to select, available functions: + aif, fpga-gpio1, fpga-gpio2, fpga-gpio3, fpga-gpio4, fpga-gpio5, + fpga-gpio6, codec-gpio1, codec-gpio2, codec-gpio3, codec-gpio4, + codec-gpio5, codec-gpio6, codec-gpio7, codec-gpio8, dsp-gpio1, + dsp-gpio2, dsp-gpio3, dsp-gpio4, dsp-gpio5, dsp-gpio6, gf-gpio2, + gf-gpio3, gf-gpio7, gf-gpio1, gf-gpio5, dsp-gpio20, codec-clkout, + dsp-clkout, pmic-32k, spdif-clkout, clk-12m288, clk-11m2986, + clk-24m576, clk-22m5792, xmos-mclk, gf-clkout1, gf-mclk1, + gf-mclk3, gf-mclk2, gf-clkout2, codec-mclk1, codec-mclk2, + dsp-clkin, psia1-mclk, psia2-mclk, spdif-mclk, codec-irq, + codec-reset, dsp-reset, dsp-irq, dsp-standby, codec-pdmclk1, + codec-pdmdat1, codec-pdmclk2, codec-pdmdat2, codec-dmicclk1, + codec-dmicdat1, codec-dmicclk2, codec-dmicdat2, codec-dmicclk3, + codec-dmicdat3, codec-dmicclk4, codec-dmicdat4, dsp-dmicclk1, + dsp-dmicdat1, dsp-dmicclk2, dsp-dmicdat2, dsp-uart1-rx, + dsp-uart1-tx, dsp-uart2-rx, dsp-uart2-tx, gf-uart2-rx, + gf-uart2-tx, usb-uart-rx, usb-uart-tx, i2c2-scl, i2c2-sda, + i2c3-scl, i2c3-sda, i2c4-scl, i2c4-sda, spdif-aif, psia1, + psia1-bclk, psia1-lrclk, psia1-rxdat, psia1-txdat, psia2, + psia2-bclk, psia2-lrclk, psia2-rxdat, psia2-txdat, codec-aif1, + codec-aif1-bclk, codec-aif1-lrclk, codec-aif1-rxdat, + codec-aif1-txdat, codec-aif2, codec-aif2-bclk, codec-aif2-lrclk, + codec-aif2-rxdat, codec-aif2-txdat, codec-aif3, codec-aif3-bclk, + codec-aif3-lrclk, codec-aif3-rxdat, codec-aif3-txdat, dsp-aif1, + dsp-aif1-bclk, dsp-aif1-lrclk, dsp-aif1-rxdat, dsp-aif1-txdat, + dsp-aif2, dsp-aif2-bclk, dsp-aif2-lrclk, dsp-aif2-rxdat, + dsp-aif2-txdat, gf-aif3, gf-aif3-bclk, gf-aif3-lrclk, + gf-aif3-rxdat, gf-aif3-txdat, gf-aif4, gf-aif4-bclk, + gf-aif4-lrclk, gf-aif4-rxdat, gf-aif4-txdat, gf-aif1, + gf-aif1-bclk, gf-aif1-lrclk, gf-aif1-rxdat, gf-aif1-txdat, + gf-aif2, gf-aif2-bclk, gf-aif2-lrclk, gf-aif2-rxdat, + gf-aif2-txdat, usb-aif1, usb-aif2, adat-aif, soundcard-aif, + + - output-enable : Specifies that an AIF group will be used as a master + interface (either this or input-enable is required if a group is + being muxed to an AIF) + - input-enable : Specifies that an AIF group will be used as a slave + interface (either this or output-enable is required if a group is + being muxed to an AIF) + +Example: + +lochnagar-pinctrl { + compatible = "cirrus,lochnagar-pinctrl"; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&lochnagar 0 0 LOCHNAGAR2_PIN_NUM_GPIOS>; + + pinctrl-names = "default"; + pinctrl-0 = <&pin-settings>; + + pin-settings: pin-settings { + ap-aif { + input-enable; + groups = "gf-aif1"; + function = "codec-aif3"; + }; + codec-aif { + output-enable; + groups = "codec-aif3"; + function = "gf-aif1"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt index 6666277c3acb..8ac1d0851a0f 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt @@ -48,9 +48,9 @@ PAD_CTL_HYS (1 << 3) PAD_CTL_SRE_SLOW (1 << 2) PAD_CTL_SRE_FAST (0 << 2) PAD_CTL_DSE_X1 (0 << 0) -PAD_CTL_DSE_X2 (1 << 0) -PAD_CTL_DSE_X3 (2 << 0) -PAD_CTL_DSE_X4 (3 << 0) +PAD_CTL_DSE_X4 (1 << 0) +PAD_CTL_DSE_X2 (2 << 0) +PAD_CTL_DSE_X6 (3 << 0) Examples: While iomuxc-lpsr is intended to be used by dedicated peripherals to take diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt index e7d6f81c227f..205be98ae078 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt @@ -11,6 +11,7 @@ Required properties: "mediatek,mt8127-pinctrl", compatible with mt8127 pinctrl. "mediatek,mt8135-pinctrl", compatible with mt8135 pinctrl. "mediatek,mt8173-pinctrl", compatible with mt8173 pinctrl. + "mediatek,mt8516-pinctrl", compatible with mt8516 pinctrl. - pins-are-numbered: Specify the subnodes are using numbered pinmux to specify pins. - gpio-controller : Marks the device node as a gpio controller. diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8183.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8183.txt new file mode 100644 index 000000000000..eccbe3f55d3f --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt8183.txt @@ -0,0 +1,132 @@ +* Mediatek MT8183 Pin Controller + +The Mediatek's Pin controller is used to control SoC pins. + +Required properties: +- compatible: value should be one of the following. + "mediatek,mt8183-pinctrl", compatible with mt8183 pinctrl. +- gpio-controller : Marks the device node as a gpio controller. +- #gpio-cells: number of cells in GPIO specifier. Since the generic GPIO + binding is used, the amount of cells must be specified as 2. See the below + mentioned gpio binding representation for description of particular cells. +- gpio-ranges : gpio valid number range. +- reg: physical address base for gpio base registers. There are 10 GPIO + physical address base in mt8183. + +Optional properties: +- reg-names: gpio base register names. There are 10 gpio base register + names in mt8183. They are "iocfg0", "iocfg1", "iocfg2", "iocfg3", "iocfg4", + "iocfg5", "iocfg6", "iocfg7", "iocfg8", "eint". +- interrupt-controller: Marks the device node as an interrupt controller +- #interrupt-cells: Should be two. +- interrupts : The interrupt outputs to sysirq. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices. + +Subnode format +A pinctrl node should contain at least one subnodes representing the +pinctrl groups available on the machine. Each subnode will list the +pins it needs, and how they should be configured, with regard to muxer +configuration, pullups, drive strength, input enable/disable and input schmitt. + + node { + pinmux = <PIN_NUMBER_PINMUX>; + GENERIC_PINCONFIG; + }; + +Required properties: +- pinmux: integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are defined + as macros in boot/dts/<soc>-pinfunc.h directly. + +Optional properties: +- GENERIC_PINCONFIG: is the generic pinconfig options to use, bias-disable, + bias-pull-down, bias-pull-up, input-enable, input-disable, output-low, + output-high, input-schmitt-enable, input-schmitt-disable + and drive-strength are valid. + + Some special pins have extra pull up strength, there are R0 and R1 pull-up + resistors available, but for user, it's only need to set R1R0 as 00, 01, + 10 or 11. So It needs config "mediatek,pull-up-adv" or + "mediatek,pull-down-adv" to support arguments for those special pins. + Valid arguments are from 0 to 3. + + mediatek,tdsel: An integer describing the steps for output level shifter + duty cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 15. + mediatek,rdsel: An integer describing the steps for input level shifter + duty cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 63. + + When config drive-strength, it can support some arguments, such as + MTK_DRIVE_4mA, MTK_DRIVE_6mA, etc. See dt-bindings/pinctrl/mt65xx.h. + It can only support 2/4/6/8/10/12/14/16mA in mt8183. + For I2C pins, there are existing generic driving setup and the specific + driving setup. I2C pins can only support 2/4/6/8/10/12/14/16mA driving + adjustment in generic driving setup. But in specific driving setup, + they can support 0.125/0.25/0.5/1mA adjustment. If we enable specific + driving setup for I2C pins, the existing generic driving setup will be + disabled. For some special features, we need the I2C pins specific + driving setup. The specific driving setup is controlled by E1E0EN. + So we need add extra vendor driving preperty instead of + the generic driving property. + We can add "mediatek,drive-strength-adv = <XXX>;" to describe the specific + driving setup property. "XXX" means the value of E1E0EN. EN is 0 or 1. + It is used to enable or disable the specific driving setup. + E1E0 is used to describe the detail strength specification of the I2C pin. + When E1=0/E0=0, the strength is 0.125mA. + When E1=0/E0=1, the strength is 0.25mA. + When E1=1/E0=0, the strength is 0.5mA. + When E1=1/E0=1, the strength is 1mA. + So the valid arguments of "mediatek,drive-strength-adv" are from 0 to 7. + +Examples: + +#include "mt8183-pinfunc.h" + +... +{ + pio: pinctrl@10005000 { + compatible = "mediatek,mt8183-pinctrl"; + reg = <0 0x10005000 0 0x1000>, + <0 0x11f20000 0 0x1000>, + <0 0x11e80000 0 0x1000>, + <0 0x11e70000 0 0x1000>, + <0 0x11e90000 0 0x1000>, + <0 0x11d30000 0 0x1000>, + <0 0x11d20000 0 0x1000>, + <0 0x11c50000 0 0x1000>, + <0 0x11f30000 0 0x1000>, + <0 0x1000b000 0 0x1000>; + reg-names = "iocfg0", "iocfg1", "iocfg2", + "iocfg3", "iocfg4", "iocfg5", + "iocfg6", "iocfg7", "iocfg8", + "eint"; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pio 0 0 192>; + interrupt-controller; + interrupts = <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>; + #interrupt-cells = <2>; + + i2c0_pins_a: i2c0 { + pins1 { + pinmux = <PINMUX_GPIO48__FUNC_SCL5>, + <PINMUX_GPIO49__FUNC_SDA5>; + mediatek,pull-up-adv = <3>; + mediatek,drive-strength-adv = <7>; + }; + }; + + i2c1_pins_a: i2c1 { + pins { + pinmux = <PINMUX_GPIO50__FUNC_SCL3>, + <PINMUX_GPIO51__FUNC_SDA3>; + mediatek,pull-down-adv = <2>; + mediatek,drive-strength-adv = <4>; + }; + }; + ... + }; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-stmfx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-stmfx.txt new file mode 100644 index 000000000000..c1b4c1819b84 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-stmfx.txt @@ -0,0 +1,116 @@ +STMicroelectronics Multi-Function eXpander (STMFX) GPIO expander bindings + +ST Multi-Function eXpander (STMFX) offers up to 24 GPIOs expansion. +Please refer to ../mfd/stmfx.txt for STMFX Core bindings. + +Required properties: +- compatible: should be "st,stmfx-0300-pinctrl". +- #gpio-cells: should be <2>, the first cell is the GPIO number and the second + cell is the gpio flags in accordance with <dt-bindings/gpio/gpio.h>. +- gpio-controller: marks the device as a GPIO controller. +- #interrupt-cells: should be <2>, the first cell is the GPIO number and the + second cell is the interrupt flags in accordance with + <dt-bindings/interrupt-controller/irq.h>. +- interrupt-controller: marks the device as an interrupt controller. +- gpio-ranges: specifies the mapping between gpio controller and pin + controller pins. Check "Concerning gpio-ranges property" below. +Please refer to ../gpio/gpio.txt. + +Please refer to pinctrl-bindings.txt for pin configuration. + +Required properties for pin configuration sub-nodes: +- pins: list of pins to which the configuration applies. + +Optional properties for pin configuration sub-nodes (pinconf-generic ones): +- bias-disable: disable any bias on the pin. +- bias-pull-up: the pin will be pulled up. +- bias-pull-pin-default: use the pin-default pull state. +- bias-pull-down: the pin will be pulled down. +- drive-open-drain: the pin will be driven with open drain. +- drive-push-pull: the pin will be driven actively high and low. +- output-high: the pin will be configured as an output driving high level. +- output-low: the pin will be configured as an output driving low level. + +Note that STMFX pins[15:0] are called "gpio[15:0]", and STMFX pins[23:16] are +called "agpio[7:0]". Example, to refer to pin 18 of STMFX, use "agpio2". + +Concerning gpio-ranges property: +- if all STMFX pins[24:0] are available (no other STMFX function in use), you + should use gpio-ranges = <&stmfx_pinctrl 0 0 24>; +- if agpio[3:0] are not available (STMFX Touchscreen function in use), you + should use gpio-ranges = <&stmfx_pinctrl 0 0 16>, <&stmfx_pinctrl 20 20 4>; +- if agpio[7:4] are not available (STMFX IDD function in use), you + should use gpio-ranges = <&stmfx_pinctrl 0 0 20>; + + +Example: + + stmfx: stmfx@42 { + ... + + stmfx_pinctrl: stmfx-pin-controller { + compatible = "st,stmfx-0300-pinctrl"; + #gpio-cells = <2>; + #interrupt-cells = <2>; + gpio-controller; + interrupt-controller; + gpio-ranges = <&stmfx_pinctrl 0 0 24>; + + joystick_pins: joystick { + pins = "gpio0", "gpio1", "gpio2", "gpio3", "gpio4"; + drive-push-pull; + bias-pull-up; + }; + }; + }; + +Example of STMFX GPIO consumers: + + joystick { + compatible = "gpio-keys"; + #address-cells = <1>; + #size-cells = <0>; + pinctrl-0 = <&joystick_pins>; + pinctrl-names = "default"; + button-0 { + label = "JoySel"; + linux,code = <KEY_ENTER>; + interrupt-parent = <&stmfx_pinctrl>; + interrupts = <0 IRQ_TYPE_EDGE_RISING>; + }; + button-1 { + label = "JoyDown"; + linux,code = <KEY_DOWN>; + interrupt-parent = <&stmfx_pinctrl>; + interrupts = <1 IRQ_TYPE_EDGE_RISING>; + }; + button-2 { + label = "JoyLeft"; + linux,code = <KEY_LEFT>; + interrupt-parent = <&stmfx_pinctrl>; + interrupts = <2 IRQ_TYPE_EDGE_RISING>; + }; + button-3 { + label = "JoyRight"; + linux,code = <KEY_RIGHT>; + interrupt-parent = <&stmfx_pinctrl>; + interrupts = <3 IRQ_TYPE_EDGE_RISING>; + }; + button-4 { + label = "JoyUp"; + linux,code = <KEY_UP>; + interrupt-parent = <&stmfx_pinctrl>; + interrupts = <4 IRQ_TYPE_EDGE_RISING>; + }; + }; + + leds { + compatible = "gpio-leds"; + orange { + gpios = <&stmfx_pinctrl 17 1>; + }; + + blue { + gpios = <&stmfx_pinctrl 19 1>; + }; + } diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt index c2dbb3e8d840..4e90ddd77784 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,apq8064-pinctrl.txt @@ -42,7 +42,7 @@ information about e.g. the mux function. The following generic properties as defined in pinctrl-bindings.txt are valid to specify in a pin configuration subnode: - pins, function, bias-disable, bias-pull-down, bias-pull,up, drive-strength, + pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength, output-low, output-high. Non-empty subnodes must specify the 'pins' property. diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt index 991be0cd0948..84be0f2c6f3b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt @@ -44,7 +44,7 @@ information about e.g. the mux function. The following generic properties as defined in pinctrl-bindings.txt are valid to specify in a pin configuration subnode: - pins, function, bias-disable, bias-pull-down, bias-pull,up, drive-strength. + pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength. Non-empty subnodes must specify the 'pins' property. Note that not all properties are valid for all pins. diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt index 7ed56a1b70fc..a7aaaa7db83b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8064-pinctrl.txt @@ -42,7 +42,7 @@ information about e.g. the mux function. The following generic properties as defined in pinctrl-bindings.txt are valid to specify in a pin configuration subnode: - pins, function, bias-disable, bias-pull-down, bias-pull,up, drive-strength, + pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength, output-low, output-high. Non-empty subnodes must specify the 'pins' property. diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt index cdc4787e59d2..f095209848c8 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8660-pinctrl.txt @@ -42,7 +42,7 @@ information about e.g. the mux function. The following generic properties as defined in pinctrl-bindings.txt are valid to specify in a pin configuration subnode: - pins, function, bias-disable, bias-pull-down, bias-pull,up, drive-strength, + pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength, output-low, output-high. Non-empty subnodes must specify the 'pins' property. diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt index c22e6c425d0b..004056506679 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8974-pinctrl.txt @@ -41,7 +41,7 @@ information about e.g. the mux function. The following generic properties as defined in pinctrl-bindings.txt are valid to specify in a pin configuration subnode: - pins, function, bias-disable, bias-pull-down, bias-pull,up, drive-strength. + pins, function, bias-disable, bias-pull-down, bias-pull-up, drive-strength. Non-empty subnodes must specify the 'pins' property. Note that not all properties are valid for all pins. diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt index 48df30a36b01..00169255e48c 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -57,6 +57,8 @@ Optional properties: - st,bank-ioport: should correspond to the EXTI IOport selection (EXTI line used to select GPIOs as interrupts). - hwlocks: reference to a phandle of a hardware spinlock provider node. + - st,package: Indicates the SOC package used. + More details in include/dt-bindings/pinctrl/stm32-pinfunc.h Example 1: #include <dt-bindings/pinctrl/stm32f429-pinfunc.h> diff --git a/Documentation/devicetree/bindings/power/supply/max77650-charger.txt b/Documentation/devicetree/bindings/power/supply/max77650-charger.txt new file mode 100644 index 000000000000..e6d0fb6ff94e --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/max77650-charger.txt @@ -0,0 +1,28 @@ +Battery charger driver for MAX77650 PMIC from Maxim Integrated. + +This module is part of the MAX77650 MFD device. For more details +see Documentation/devicetree/bindings/mfd/max77650.txt. + +The charger is represented as a sub-node of the PMIC node on the device tree. + +Required properties: +-------------------- +- compatible: Must be "maxim,max77650-charger" + +Optional properties: +-------------------- +- input-voltage-min-microvolt: Minimum CHGIN regulation voltage. Must be one + of: 4000000, 4100000, 4200000, 4300000, + 4400000, 4500000, 4600000, 4700000. +- input-current-limit-microamp: CHGIN input current limit (in microamps). Must + be one of: 95000, 190000, 285000, 380000, + 475000. + +Example: +-------- + + charger { + compatible = "maxim,max77650-charger"; + input-voltage-min-microvolt = <4200000>; + input-current-limit-microamp = <285000>; + }; diff --git a/Documentation/devicetree/bindings/pps/pps-gpio.txt b/Documentation/devicetree/bindings/pps/pps-gpio.txt index 3683874832ae..9012a2a02e14 100644 --- a/Documentation/devicetree/bindings/pps/pps-gpio.txt +++ b/Documentation/devicetree/bindings/pps/pps-gpio.txt @@ -7,6 +7,10 @@ Required properties: - compatible: should be "pps-gpio" - gpios: one PPS GPIO in the format described by ../gpio/gpio.txt +Additional required properties for the PPS ECHO functionality: +- echo-gpios: one PPS ECHO GPIO in the format described by ../gpio/gpio.txt +- echo-active-ms: duration in ms of the active portion of the echo pulse + Optional properties: - assert-falling-edge: when present, assert is indicated by a falling edge (instead of by a rising edge) @@ -19,5 +23,8 @@ Example: gpios = <&gpio1 26 GPIO_ACTIVE_HIGH>; assert-falling-edge; + echo-gpios = <&gpio1 27 GPIO_ACTIVE_HIGH>; + echo-active-ms = <100>; + compatible = "pps-gpio"; }; diff --git a/Documentation/devicetree/bindings/pwm/imx-tpm-pwm.txt b/Documentation/devicetree/bindings/pwm/imx-tpm-pwm.txt new file mode 100644 index 000000000000..3ba958d764ff --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/imx-tpm-pwm.txt @@ -0,0 +1,22 @@ +Freescale i.MX TPM PWM controller + +Required properties: +- compatible : Should be "fsl,imx7ulp-pwm". +- reg: Physical base address and length of the controller's registers. +- #pwm-cells: Should be 3. See pwm.txt in this directory for a description of the cells format. +- clocks : The clock provided by the SoC to drive the PWM. +- interrupts: The interrupt for the PWM controller. + +Note: The TPM counter and period counter are shared between multiple channels, so all channels +should use same period setting. + +Example: + +tpm4: pwm@40250000 { + compatible = "fsl,imx7ulp-pwm"; + reg = <0x40250000 0x1000>; + assigned-clocks = <&pcc2 IMX7ULP_CLK_LPTPM4>; + assigned-clock-parents = <&scg1 IMX7ULP_CLK_SOSC_BUS_CLK>; + clocks = <&pcc2 IMX7ULP_CLK_LPTPM4>; + #pwm-cells = <3>; +}; diff --git a/Documentation/devicetree/bindings/pwm/pwm-meson.txt b/Documentation/devicetree/bindings/pwm/pwm-meson.txt index 1fa3f7182133..891632354065 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-meson.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-meson.txt @@ -7,6 +7,9 @@ Required properties: or "amlogic,meson-gxbb-ao-pwm" or "amlogic,meson-axg-ee-pwm" or "amlogic,meson-axg-ao-pwm" + or "amlogic,meson-g12a-ee-pwm" + or "amlogic,meson-g12a-ao-pwm-ab" + or "amlogic,meson-g12a-ao-pwm-cd" - #pwm-cells: Should be 3. See pwm.txt in this directory for a description of the cells format. diff --git a/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.txt b/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.txt index 944fe356bb45..31c4577157dd 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-tiehrpwm.txt @@ -4,6 +4,7 @@ Required properties: - compatible: Must be "ti,<soc>-ehrpwm". for am33xx - compatible = "ti,am3352-ehrpwm", "ti,am33xx-ehrpwm"; for am4372 - compatible = "ti,am4372-ehrpwm", "ti-am3352-ehrpwm", "ti,am33xx-ehrpwm"; + for am654 - compatible = "ti,am654-ehrpwm", "ti-am3352-ehrpwm"; for da850 - compatible = "ti,da850-ehrpwm", "ti-am3352-ehrpwm", "ti,am33xx-ehrpwm"; for dra746 - compatible = "ti,dra746-ehrpwm", "ti-am3352-ehrpwm"; - #pwm-cells: should be 3. See pwm.txt in this directory for a description of diff --git a/Documentation/devicetree/bindings/regulator/gpio-regulator.txt b/Documentation/devicetree/bindings/regulator/gpio-regulator.txt index 1f496159e2bb..dd25e73b5d79 100644 --- a/Documentation/devicetree/bindings/regulator/gpio-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/gpio-regulator.txt @@ -4,16 +4,30 @@ Required properties: - compatible : Must be "regulator-gpio". - regulator-name : Defined in regulator.txt as optional, but required here. -- states : Selection of available voltages and GPIO configs. - if there are no states, then use a fixed regulator +- gpios : Array of one or more GPIO pins used to select the + regulator voltage/current listed in "states". +- states : Selection of available voltages/currents provided by + this regulator and matching GPIO configurations to + achieve them. If there are no states in the "states" + array, use a fixed regulator instead. Optional properties: -- enable-gpio : GPIO to use to enable/disable the regulator. -- gpios : GPIO group used to control voltage. -- gpios-states : gpios pin's initial states array. 0: LOW, 1: HIGH. - defualt is LOW if nothing is specified. +- enable-gpios : GPIO used to enable/disable the regulator. + Warning, the GPIO phandle flags are ignored and the + GPIO polarity is controlled solely by the presence + of "enable-active-high" DT property. This is due to + compatibility with old DTs. +- enable-active-high : Polarity of "enable-gpio" GPIO is active HIGH. + Default is active LOW. +- gpios-states : On operating systems, that don't support reading back + gpio values in output mode (most notably linux), this + array provides the state of GPIO pins set when + requesting them from the gpio controller. Systems, + that are capable of preserving state when requesting + the lines, are free to ignore this property. + 0: LOW, 1: HIGH. Default is LOW if nothing else + is specified. - startup-delay-us : Startup time in microseconds. -- enable-active-high : Polarity of GPIO is active high (default is low). - regulator-type : Specifies what is being regulated, must be either "voltage" or "current", defaults to voltage. @@ -30,7 +44,7 @@ Example: regulator-max-microvolt = <2600000>; regulator-boot-on; - enable-gpio = <&gpio0 23 0x4>; + enable-gpios = <&gpio0 23 0x4>; gpios = <&gpio0 24 0x4 &gpio0 25 0x4>; states = <1800000 0x3 diff --git a/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.txt b/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.txt new file mode 100644 index 000000000000..e372dd3f0c8a --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/st,stm32mp1-pwr-reg.txt @@ -0,0 +1,43 @@ +STM32MP1 PWR Regulators +----------------------- + +Available Regulators in STM32MP1 PWR block are: + - reg11 for regulator 1V1 + - reg18 for regulator 1V8 + - usb33 for the swtich USB3V3 + +Required properties: +- compatible: Must be "st,stm32mp1,pwr-reg" +- list of child nodes that specify the regulator reg11, reg18 or usb33 + initialization data for defined regulators. The definition for each of + these nodes is defined using the standard binding for regulators found at + Documentation/devicetree/bindings/regulator/regulator.txt. +- vdd-supply: phandle to the parent supply/regulator node for vdd input +- vdd_3v3_usbfs-supply: phandle to the parent supply/regulator node for usb33 + +Example: + +pwr_regulators: pwr@50001000 { + compatible = "st,stm32mp1,pwr-reg"; + reg = <0x50001000 0x10>; + vdd-supply = <&vdd>; + vdd_3v3_usbfs-supply = <&vdd_usb>; + + reg11: reg11 { + regulator-name = "reg11"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + }; + + reg18: reg18 { + regulator-name = "reg18"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + usb33: usb33 { + regulator-name = "usb33"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; +}; diff --git a/Documentation/devicetree/bindings/rtc/nxp,pcf85063.txt b/Documentation/devicetree/bindings/rtc/nxp,pcf85063.txt index d3e380ad712d..627bb533eff7 100644 --- a/Documentation/devicetree/bindings/rtc/nxp,pcf85063.txt +++ b/Documentation/devicetree/bindings/rtc/nxp,pcf85063.txt @@ -1,7 +1,11 @@ * NXP PCF85063 Real Time Clock Required properties: -- compatible: Should contain "nxp,pcf85063". +- compatible: Should one of contain: + "nxp,pcf85063", + "nxp,pcf85063a", + "nxp,pcf85063tp", + "microcrystal,rv8263" - reg: I2C address for chip. Optional property: diff --git a/Documentation/devicetree/bindings/rtc/rtc-aspeed.txt b/Documentation/devicetree/bindings/rtc/rtc-aspeed.txt new file mode 100644 index 000000000000..2e956b3dc276 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-aspeed.txt @@ -0,0 +1,22 @@ +ASPEED BMC RTC +============== + +Required properties: + - compatible: should be one of the following + * aspeed,ast2400-rtc for the ast2400 + * aspeed,ast2500-rtc for the ast2500 + * aspeed,ast2600-rtc for the ast2600 + + - reg: physical base address of the controller and length of memory mapped + region + + - interrupts: The interrupt number + +Example: + + rtc@1e781000 { + compatible = "aspeed,ast2400-rtc"; + reg = <0x1e781000 0x18>; + interrupts = <22>; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/rtc/rtc.txt b/Documentation/devicetree/bindings/rtc/rtc.txt index f4687c68c08c..a97fc6a9a75e 100644 --- a/Documentation/devicetree/bindings/rtc/rtc.txt +++ b/Documentation/devicetree/bindings/rtc/rtc.txt @@ -69,3 +69,4 @@ ricoh,rv5c386 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC ricoh,rv5c387a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC sii,s35390a 2-wire CMOS real-time clock whwave,sd3078 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +xircom,x1205 Xircom X1205 I2C RTC diff --git a/Documentation/devicetree/bindings/serial/cdns,uart.txt b/Documentation/devicetree/bindings/serial/cdns,uart.txt index 227bb770b027..4efc560f90ab 100644 --- a/Documentation/devicetree/bindings/serial/cdns,uart.txt +++ b/Documentation/devicetree/bindings/serial/cdns,uart.txt @@ -12,6 +12,11 @@ Required properties: See ../clocks/clock-bindings.txt for details. +Optional properties: +- cts-override : Override the CTS modem status signal. This signal will + always be reported as active instead of being obtained from the modem status + register. Define this if your serial port does not use this pin + Example: uart@e0000000 { compatible = "cdns,uart-r1p8"; diff --git a/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt b/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt index e7921a8e276b..c1091a923a89 100644 --- a/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt +++ b/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt @@ -12,6 +12,8 @@ Required properties: - reg: I2C address of the SC16IS7xx device. - interrupts: Should contain the UART interrupt - clocks: Reference to the IC source clock. + OR (when there is no clock provider visible to the platform) +- clock-frequency: The source clock frequency for the IC. Optional properties: - gpio-controller: Marks the device node as a GPIO controller. diff --git a/Documentation/devicetree/bindings/serial/sifive-serial.txt b/Documentation/devicetree/bindings/serial/sifive-serial.txt new file mode 100644 index 000000000000..c86b1e524159 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/sifive-serial.txt @@ -0,0 +1,33 @@ +SiFive asynchronous serial interface (UART) + +Required properties: + +- compatible: should be something similar to + "sifive,<chip>-uart" for the UART as integrated + on a particular chip, and "sifive,uart<version>" for the + general UART IP block programming model. Supported + compatible strings as of the date of this writing are: + "sifive,fu540-c000-uart" for the SiFive UART v0 as + integrated onto the SiFive FU540 chip, or "sifive,uart0" + for the SiFive UART v0 IP block with no chip integration + tweaks (if any) +- reg: address and length of the register space +- interrupts: Should contain the UART interrupt identifier +- clocks: Should contain a clock identifier for the UART's parent clock + + +UART HDL that corresponds to the IP block version numbers can be found +here: + +https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/uart + + +Example: + +uart0: serial@10010000 { + compatible = "sifive,fu540-c000-uart", "sifive,uart0"; + interrupt-parent = <&plic0>; + interrupts = <80>; + reg = <0x0 0x10010000 0x0 0x1000>; + clocks = <&prci PRCI_CLK_TLCLK>; +}; diff --git a/Documentation/devicetree/bindings/serial/sprd-uart.txt b/Documentation/devicetree/bindings/serial/sprd-uart.txt index cab40f0f6f49..9607dc616205 100644 --- a/Documentation/devicetree/bindings/serial/sprd-uart.txt +++ b/Documentation/devicetree/bindings/serial/sprd-uart.txt @@ -7,7 +7,17 @@ Required properties: - reg: offset and length of the register set for the device - interrupts: exactly one interrupt specifier -- clocks: phandles to input clocks. +- clock-names: Should contain following entries: + "enable" for UART module enable clock, + "uart" for UART clock, + "source" for UART source (parent) clock. +- clocks: Should contain a clock specifier for each entry in clock-names. + UART clock and source clock are optional properties, but enable clock + is required. + +Optional properties: +- dma-names: Should contain "rx" for receive and "tx" for transmit channels. +- dmas: A list of dma specifiers, one for each entry in dma-names. Example: uart0: serial@0 { @@ -15,5 +25,8 @@ Example: "sprd,sc9836-uart"; reg = <0x0 0x100>; interrupts = <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&ext_26m>; + dma-names = "rx", "tx"; + dmas = <&ap_dma 19>, <&ap_dma 20>; + clock-names = "enable", "uart", "source"; + clocks = <&clk_ap_apb_gates 9>, <&clk_uart0>, <&ext_26m>; }; diff --git a/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt b/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt index 4248b662deff..229ad1392cdc 100644 --- a/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt +++ b/Documentation/devicetree/bindings/sound/adi,axi-i2s.txt @@ -1,5 +1,8 @@ ADI AXI-I2S controller +The core can be generated with transmit (playback), only receive +(capture) or both directions enabled. + Required properties: - compatible : Must be "adi,axi-i2s-1.00.a" - reg : Must contain I2S core's registers location and length @@ -9,8 +12,8 @@ Required properties: - clock-names : "axi" for the clock to the AXI interface, "ref" for the sample rate reference clock. - dmas: Pairs of phandle and specifier for the DMA channels that are used by - the core. The core expects two dma channels, one for transmit and one for - receive. + the core. The core expects two dma channels if both transmit and receive are + enabled, one channel otherwise. - dma-names : "tx" for the transmit channel, "rx" for the receive channel. For more details on the 'dma', 'dma-names', 'clock' and 'clock-names' properties diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt index 3dfc2515e5c6..4330fc9dca6d 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-fifo.txt @@ -2,7 +2,9 @@ Required properties: - compatible: 'amlogic,axg-toddr' or - 'amlogic,axg-frddr' + 'amlogic,axg-toddr' or + 'amlogic,g12a-frddr' or + 'amlogic,g12a-toddr' - reg: physical base address of the controller and length of memory mapped region. - interrupts: interrupt specifier for the fifo. diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt index 5672d0bc5b16..73f473a9365f 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-pdm.txt @@ -1,7 +1,8 @@ * Amlogic Audio PDM input Required properties: -- compatible: 'amlogic,axg-pdm' +- compatible: 'amlogic,axg-pdm' or + 'amlogic,g12a-pdm' - reg: physical base address of the controller and length of memory mapped region. - clocks: list of clock phandle, one for each entry clock-names. diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt index 2e6cb7d9b202..0b82504fa419 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt @@ -1,7 +1,8 @@ * Amlogic Audio SPDIF Input Required properties: -- compatible: 'amlogic,axg-spdifin' +- compatible: 'amlogic,axg-spdifin' or + 'amlogic,g12a-spdifin' - interrupts: interrupt specifier for the spdif input. - clocks: list of clock phandle, one for each entry clock-names. - clock-names: should contain the following: diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt index 521c38ad89e7..826152730508 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifout.txt @@ -1,7 +1,8 @@ * Amlogic Audio SPDIF Output Required properties: -- compatible: 'amlogic,axg-spdifout' +- compatible: 'amlogic,axg-spdifout' or + 'amlogic,g12a-spdifout' - clocks: list of clock phandle, one for each entry clock-names. - clock-names: should contain the following: * "pclk" : peripheral clock. diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt index 1c1b7490554e..3b94a715a0b9 100644 --- a/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-tdm-formatters.txt @@ -2,7 +2,9 @@ Required properties: - compatible: 'amlogic,axg-tdmin' or - 'amlogic,axg-tdmout' + 'amlogic,axg-tdmout' or + 'amlogic,g12a-tdmin' or + 'amlogic,g12a-tdmout' - reg: physical base address of the controller and length of memory mapped region. - clocks: list of clock phandle, one for each entry clock-names. diff --git a/Documentation/devicetree/bindings/sound/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/sound/cirrus,lochnagar.txt new file mode 100644 index 000000000000..41ae2699f07a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cirrus,lochnagar.txt @@ -0,0 +1,39 @@ +Cirrus Logic Lochnagar Audio Development Board + +Lochnagar is an evaluation and development board for Cirrus Logic +Smart CODEC and Amp devices. It allows the connection of most Cirrus +Logic devices on mini-cards, as well as allowing connection of +various application processor systems to provide a full evaluation +platform. Audio system topology, clocking and power can all be +controlled through the Lochnagar, allowing the device under test +to be used in a variety of possible use cases. + +This binding document describes the binding for the audio portion +of the driver. + +This binding must be part of the Lochnagar MFD binding: + [4] ../mfd/cirrus,lochnagar.txt + +Required properties: + + - compatible : One of the following strings: + "cirrus,lochnagar2-soundcard" + + - #sound-dai-cells : Must be set to 1. + + - clocks : Contains an entry for each entry in clock-names. + - clock-names : Must include the following clocks: + "mclk" Master clock source for the sound card, should normally + be set to LOCHNAGAR_SOUNDCARD_MCLK provided by the Lochnagar + clock driver. + +Example: + +lochnagar-sc { + compatible = "cirrus,lochnagar2-soundcard"; + + #sound-dai-cells = <1>; + + clocks = <&lochnagar_clk LOCHNAGAR_SOUNDCARD_MCLK>; + clock-names = "mclk"; +}; diff --git a/Documentation/devicetree/bindings/sound/cs42l51.txt b/Documentation/devicetree/bindings/sound/cs42l51.txt index 4b5de33ce377..acbd68ddd2cb 100644 --- a/Documentation/devicetree/bindings/sound/cs42l51.txt +++ b/Documentation/devicetree/bindings/sound/cs42l51.txt @@ -1,6 +1,17 @@ CS42L51 audio CODEC +Required properties: + + - compatible : "cirrus,cs42l51" + + - reg : the I2C address of the device for I2C. + Optional properties: + - VL-supply, VD-supply, VA-supply, VAHP-supply: power supplies for the device, + as covered in Documentation/devicetree/bindings/regulator/regulator.txt. + + - reset-gpios : GPIO specification for the reset pin. If specified, it will be + deasserted before starting the communication with the codec. - clocks : a list of phandles + clock-specifiers, one for each entry in clock-names @@ -14,4 +25,9 @@ cs42l51: cs42l51@4a { reg = <0x4a>; clocks = <&mclk_prov>; clock-names = "MCLK"; + VL-supply = <®_audio>; + VD-supply = <®_audio>; + VA-supply = <®_audio>; + VAHP-supply = <®_audio>; + reset-gpios = <&gpiog 9 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/sound/da7219.txt b/Documentation/devicetree/bindings/sound/da7219.txt index e9d0baeb94e2..add1caf26ac2 100644 --- a/Documentation/devicetree/bindings/sound/da7219.txt +++ b/Documentation/devicetree/bindings/sound/da7219.txt @@ -23,8 +23,8 @@ Optional properties: interrupt is to be used to wake system, otherwise "irq" should be used. - wakeup-source: Flag to indicate this device can wake system (suspend/resume). -- #clock-cells : Should be set to '<0>', only one clock source provided; -- clock-output-names : Name given for DAI clocks output; +- #clock-cells : Should be set to '<1>', two clock sources provided; +- clock-output-names : Names given for DAI clock outputs (WCLK & BCLK); - clocks : phandle and clock specifier for codec MCLK. - clock-names : Clock name string for 'clocks' attribute, should be "mclk". @@ -84,8 +84,8 @@ Example: VDDMIC-supply = <®_audio>; VDDIO-supply = <®_audio>; - #clock-cells = <0>; - clock-output-names = "dai-clks"; + #clock-cells = <1>; + clock-output-names = "dai-wclk", "dai-bclk"; clocks = <&clks 201>; clock-names = "mclk"; diff --git a/Documentation/devicetree/bindings/sound/fsl,audmix.txt b/Documentation/devicetree/bindings/sound/fsl,audmix.txt new file mode 100644 index 000000000000..840b7e0d6a63 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/fsl,audmix.txt @@ -0,0 +1,50 @@ +NXP Audio Mixer (AUDMIX). + +The Audio Mixer is a on-chip functional module that allows mixing of two +audio streams into a single audio stream. Audio Mixer has two input serial +audio interfaces. These are driven by two Synchronous Audio interface +modules (SAI). Each input serial interface carries 8 audio channels in its +frame in TDM manner. Mixer mixes audio samples of corresponding channels +from two interfaces into a single sample. Before mixing, audio samples of +two inputs can be attenuated based on configuration. The output of the +Audio Mixer is also a serial audio interface. Like input interfaces it has +the same TDM frame format. This output is used to drive the serial DAC TDM +interface of audio codec and also sent to the external pins along with the +receive path of normal audio SAI module for readback by the CPU. + +The output of Audio Mixer can be selected from any of the three streams + - serial audio input 1 + - serial audio input 2 + - mixed audio + +Mixing operation is independent of audio sample rate but the two audio +input streams must have same audio sample rate with same number of channels +in TDM frame to be eligible for mixing. + +Device driver required properties: +================================= + - compatible : Compatible list, contains "fsl,imx8qm-audmix" + + - reg : Offset and length of the register set for the device. + + - clocks : Must contain an entry for each entry in clock-names. + + - clock-names : Must include the "ipg" for register access. + + - power-domains : Must contain the phandle to AUDMIX power domain node + + - dais : Must contain a list of phandles to AUDMIX connected + DAIs. The current implementation requires two phandles + to SAI interfaces to be provided, the first SAI in the + list being used to route the AUDMIX output. + +Device driver configuration example: +====================================== + audmix: audmix@59840000 { + compatible = "fsl,imx8qm-audmix"; + reg = <0x0 0x59840000 0x0 0x10000>; + clocks = <&clk IMX8QXP_AUD_AUDMIX_IPG>; + clock-names = "ipg"; + power-domains = <&pd_audmix>; + dais = <&sai4>, <&sai5>; + }; diff --git a/Documentation/devicetree/bindings/sound/mchp-i2s-mcc.txt b/Documentation/devicetree/bindings/sound/mchp-i2s-mcc.txt new file mode 100644 index 000000000000..91ec83a6faed --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mchp-i2s-mcc.txt @@ -0,0 +1,43 @@ +* Microchip I2S Multi-Channel Controller + +Required properties: +- compatible: Should be "microchip,sam9x60-i2smcc". +- reg: Should be the physical base address of the controller and the + length of memory mapped region. +- interrupts: Should contain the interrupt for the controller. +- dmas: Should be one per channel name listed in the dma-names property, + as described in atmel-dma.txt and dma.txt files. +- dma-names: Identifier string for each DMA request line in the dmas property. + Two dmas have to be defined, "tx" and "rx". +- clocks: Must contain an entry for each entry in clock-names. + Please refer to clock-bindings.txt. +- clock-names: Should be one of each entry matching the clocks phandles list: + - "pclk" (peripheral clock) Required. + - "gclk" (generated clock) Optional (1). + +Optional properties: +- pinctrl-0: Should specify pin control groups used for this controller. +- princtrl-names: Should contain only one value - "default". + + +(1) : Only the peripheral clock is required. The generated clock is optional + and should be set mostly when Master Mode is required. + +Example: + + i2s@f001c000 { + compatible = "microchip,sam9x60-i2smcc"; + reg = <0xf001c000 0x100>; + interrupts = <34 IRQ_TYPE_LEVEL_HIGH 7>; + dmas = <&dma0 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | + AT91_XDMAC_DT_PERID(36))>, + <&dma0 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | + AT91_XDMAC_DT_PERID(37))>; + dma-names = "tx", "rx"; + clocks = <&i2s_clk>, <&i2s_gclk>; + clock-names = "pclk", "gclk"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2s_default>; + }; diff --git a/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt b/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt new file mode 100644 index 000000000000..92ac86f83822 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt8183-da7219-max98357.txt @@ -0,0 +1,15 @@ +MT8183 with MT6358, DA7219 and MAX98357 CODECS + +Required properties: +- compatible : "mediatek,mt8183_da7219_max98357" +- mediatek,headset-codec: the phandles of da7219 codecs +- mediatek,platform: the phandle of MT8183 ASoC platform + +Example: + + sound { + compatible = "mediatek,mt8183_da7219_max98357"; + mediatek,headset-codec = <&da7219>; + mediatek,platform = <&afe>; + }; + diff --git a/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt new file mode 100644 index 000000000000..d6d5207fa996 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt8183-mt6358-ts3a227-max98357.txt @@ -0,0 +1,15 @@ +MT8183 with MT6358, TS3A227 and MAX98357 CODECS + +Required properties: +- compatible : "mediatek,mt8183_mt6358_ts3a227_max98357" +- mediatek,headset-codec: the phandles of ts3a227 codecs +- mediatek,platform: the phandle of MT8183 ASoC platform + +Example: + + sound { + compatible = "mediatek,mt8183_mt6358_ts3a227_max98357"; + mediatek,headset-codec = <&ts3a227>; + mediatek,platform = <&afe>; + }; + diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index 648d43e1b1e9..5c52182f7dcf 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -266,6 +266,7 @@ Required properties: - "renesas,rcar_sound-r8a7743" (RZ/G1M) - "renesas,rcar_sound-r8a7744" (RZ/G1N) - "renesas,rcar_sound-r8a7745" (RZ/G1E) + - "renesas,rcar_sound-r8a77470" (RZ/G1C) - "renesas,rcar_sound-r8a774a1" (RZ/G2M) - "renesas,rcar_sound-r8a774c0" (RZ/G2E) - "renesas,rcar_sound-r8a7778" (R-Car M1A) @@ -282,7 +283,12 @@ Required properties: - reg : Should contain the register physical address. required register is SRU/ADG/SSI if generation1 - SRU/ADG/SSIU/SSI if generation2 + SRU/ADG/SSIU/SSI/AUDIO-DMAC-periperi if generation2/generation3 + Select extended AUDIO-DMAC-periperi address if SoC has it, + otherwise select normal AUDIO-DMAC-periperi address. +- reg-names : Should contain the register names. + scu/adg/ssi if generation1 + scu/adg/ssiu/ssi/audmapp if generation2/generation3 - rcar_sound,ssi : Should contain SSI feature. The number of SSI subnode should be same as HW. see below for detail. diff --git a/Documentation/devicetree/bindings/sound/rockchip,pdm.txt b/Documentation/devicetree/bindings/sound/rockchip,pdm.txt index 47f164fbd1d7..98572a25122f 100644 --- a/Documentation/devicetree/bindings/sound/rockchip,pdm.txt +++ b/Documentation/devicetree/bindings/sound/rockchip,pdm.txt @@ -3,6 +3,9 @@ Required properties: - compatible: "rockchip,pdm" + - "rockchip,px30-pdm" + - "rockchip,rk1808-pdm" + - "rockchip,rk3308-pdm" - reg: physical base address of the controller and length of memory mapped region. - dmas: DMA specifiers for rx dma. See the DMA client binding, @@ -12,6 +15,8 @@ Required properties: - clock-names: should contain following: - "pdm_hclk": clock for PDM BUS - "pdm_clk" : clock for PDM controller +- resets: a list of phandle + reset-specifer paris, one for each entry in reset-names. +- reset-names: reset names, should include "pdm-m". - pinctrl-names: Must contain a "default" entry. - pinctrl-N: One property must exist for each entry in pinctrl-names. See ../pinctrl/pinctrl-bindings.txt diff --git a/Documentation/devicetree/bindings/sound/rt5651.txt b/Documentation/devicetree/bindings/sound/rt5651.txt index a41199a5cd79..56e736a1cba9 100644 --- a/Documentation/devicetree/bindings/sound/rt5651.txt +++ b/Documentation/devicetree/bindings/sound/rt5651.txt @@ -22,6 +22,11 @@ Optional properties: 2: Use JD1_2 pin for jack-detect 3: Use JD2 pin for jack-detect +- realtek,jack-detect-not-inverted + bool. Normal jack-detect switches give an inverted (active-low) signal, + set this bool in the rare case you've a jack-detect switch which is not + inverted. + - realtek,over-current-threshold-microamp u32, micbias over-current detection threshold in µA, valid values are 600, 1500 and 2000µA. diff --git a/Documentation/devicetree/bindings/sound/simple-amplifier.txt b/Documentation/devicetree/bindings/sound/simple-amplifier.txt index 7182ac4f1e65..b1b097cc9b68 100644 --- a/Documentation/devicetree/bindings/sound/simple-amplifier.txt +++ b/Documentation/devicetree/bindings/sound/simple-amplifier.txt @@ -2,9 +2,9 @@ Simple Amplifier Audio Driver Required properties: - compatible : "dioo,dio2125" or "simple-audio-amplifier" -- enable-gpios : the gpio connected to the enable pin of the simple amplifier Optional properties: +- enable-gpios : the gpio connected to the enable pin of the simple amplifier - VCC-supply : power supply for the device, as covered in Documentation/devicetree/bindings/regulator/regulator.txt diff --git a/Documentation/devicetree/bindings/sound/simple-card.txt b/Documentation/devicetree/bindings/sound/simple-card.txt index 4629c8f8a6b6..79954cd6e37b 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-card.txt @@ -24,6 +24,8 @@ Optional properties: a microphone is attached. - simple-audio-card,aux-devs : List of phandles pointing to auxiliary devices, such as amplifiers, to be added to the sound card. +- simple-audio-card,pin-switches : List of strings containing the widget names for + which pin switches must be created. Optional subnodes: diff --git a/Documentation/devicetree/bindings/sound/sprd-mcdt.txt b/Documentation/devicetree/bindings/sound/sprd-mcdt.txt new file mode 100644 index 000000000000..274ba0acbfd6 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/sprd-mcdt.txt @@ -0,0 +1,19 @@ +Spreadtrum Multi-Channel Data Transfer Binding + +The Multi-channel data transfer controller is used for sound stream +transmission between audio subsystem and other AP/CP subsystem. It +supports 10 DAC channel and 10 ADC channel, and each channel can be +configured with DMA mode or interrupt mode. + +Required properties: +- compatible: Should be "sprd,sc9860-mcdt". +- reg: Should contain registers address and length. +- interrupts: Should contain one interrupt shared by all channel. + +Example: + +mcdt@41490000 { + compatible = "sprd,sc9860-mcdt"; + reg = <0 0x41490000 0 0x170>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/spi/fsl-spi.txt b/Documentation/devicetree/bindings/spi/fsl-spi.txt index 8854004a1d3a..411375eac54d 100644 --- a/Documentation/devicetree/bindings/spi/fsl-spi.txt +++ b/Documentation/devicetree/bindings/spi/fsl-spi.txt @@ -18,6 +18,10 @@ Optional properties: - gpios : specifies the gpio pins to be used for chipselects. The gpios will be referred to as reg = <index> in the SPI child nodes. If unspecified, a single SPI device without a chip select can be used. +- fsl,spisel_boot : for the MPC8306 and MPC8309, specifies that the + SPISEL_BOOT signal is used as chip select for a slave device. Use + reg = <number of gpios> in the corresponding child node, i.e. 0 if + the gpios property is not present. Example: spi@4c0 { diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt b/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt index 9ba7c5a273b4..db8e0d71c5bc 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra114-spi.txt @@ -23,6 +23,18 @@ Required properties: Recommended properties: - spi-max-frequency: Definition as per Documentation/devicetree/bindings/spi/spi-bus.txt +Optional properties: +- nvidia,tx-clk-tap-delay: Delays the clock going out to the external device + with this tap value. This property is used to tune the outgoing data from + Tegra SPI master with respect to outgoing Tegra SPI master clock. + Tap values vary based on the platform design trace lengths from Tegra SPI + to corresponding slave devices. Valid tap values are from 0 thru 63. +- nvidia,rx-clk-tap-delay: Delays the clock coming in from the external device + with this tap value. This property is used to adjust the Tegra SPI master + clock with respect to the data from the SPI slave device. + Tap values vary based on the platform design trace lengths from Tegra SPI + to corresponding slave devices. Valid tap values are from 0 thru 63. + Example: spi@7000d600 { @@ -38,4 +50,12 @@ spi@7000d600 { reset-names = "spi"; dmas = <&apbdma 16>, <&apbdma 16>; dma-names = "rx", "tx"; + <spi-client>@<bus_num> { + ... + ... + nvidia,rx-clk-tap-delay = <0>; + nvidia,tx-clk-tap-delay = <16>; + ... + }; + }; diff --git a/Documentation/devicetree/bindings/spi/sh-msiof.txt b/Documentation/devicetree/bindings/spi/sh-msiof.txt index 37cf69586d10..18e14ee257b2 100644 --- a/Documentation/devicetree/bindings/spi/sh-msiof.txt +++ b/Documentation/devicetree/bindings/spi/sh-msiof.txt @@ -4,6 +4,7 @@ Required properties: - compatible : "renesas,msiof-r8a7743" (RZ/G1M) "renesas,msiof-r8a7744" (RZ/G1N) "renesas,msiof-r8a7745" (RZ/G1E) + "renesas,msiof-r8a77470" (RZ/G1C) "renesas,msiof-r8a774a1" (RZ/G2M) "renesas,msiof-r8a774c0" (RZ/G2E) "renesas,msiof-r8a7790" (R-Car H2) diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.txt b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.txt index 2864bc6b659c..f54c8c36395e 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.txt +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.txt @@ -8,9 +8,16 @@ Required properties: - interrupts : One interrupt, used by the controller. - #address-cells : <1>, as required by generic SPI binding. - #size-cells : <0>, also as required by generic SPI binding. +- clocks : phandles for the clocks, see the description of clock-names below. + The phandle for the "ssi_clk" is required. The phandle for the "pclk" clock + is optional. If a single clock is specified but no clock-name, it is the + "ssi_clk" clock. If both clocks are listed, the "ssi_clk" must be first. Optional properties: -- cs-gpios : Specifies the gpio pis to be used for chipselects. +- clock-names : Contains the names of the clocks: + "ssi_clk", for the core clock used to generate the external SPI clock. + "pclk", the interface clock, required for register access. +- cs-gpios : Specifies the gpio pins to be used for chipselects. - num-cs : The number of chipselects. If omitted, this will default to 4. - reg-io-width : The I/O register width (in bytes) implemented by this device. Supported values are 2 or 4 (the default). @@ -25,6 +32,7 @@ Example: interrupts = <0 154 4>; #address-cells = <1>; #size-cells = <0>; + clocks = <&spi_m_clk>; num-cs = <2>; cs-gpios = <&gpio0 13 0>, <&gpio0 14 0>; diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt index 6cc3c6fe25a3..e71b81a41ac0 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt @@ -7,7 +7,11 @@ Required properties: - reg : address and length of the lpspi master registers - interrupt-parent : core interrupt controller - interrupts : lpspi interrupt -- clocks : lpspi clock specifier +- clocks : lpspi clock specifier. Its number and order need to correspond to the + value in clock-names. +- clock-names : Corresponding to per clock and ipg clock in "clocks" + respectively. In i.MX7ULP, it only has per clk, so use CLK_DUMMY + to fill the "ipg" blank. - spi-slave : spi slave mode support. In slave mode, add this attribute without value. In master mode, remove it. @@ -18,6 +22,8 @@ lpspi2: lpspi@40290000 { reg = <0x40290000 0x10000>; interrupt-parent = <&intc>; interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX7ULP_CLK_LPSPI2>; + clocks = <&clks IMX7ULP_CLK_LPSPI2>, + <&clks IMX7ULP_CLK_DUMMY>; + clock-names = "per", "ipg"; spi-slave; }; diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index 69c356767cf8..c0f6c8ecfa2e 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -10,6 +10,7 @@ Required properties: - mediatek,mt8135-spi: for mt8135 platforms - mediatek,mt8173-spi: for mt8173 platforms - mediatek,mt8183-spi: for mt8183 platforms + - "mediatek,mt8516-spi", "mediatek,mt2712-spi": for mt8516 platforms - #address-cells: should be 1. diff --git a/Documentation/devicetree/bindings/spi/spi-mt7621.txt b/Documentation/devicetree/bindings/spi/spi-mt7621.txt new file mode 100644 index 000000000000..d5baec0fa56e --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-mt7621.txt @@ -0,0 +1,26 @@ +Binding for MTK SPI controller (MT7621 MIPS) + +Required properties: +- compatible: Should be one of the following: + - "ralink,mt7621-spi": for mt7621/mt7628/mt7688 platforms +- #address-cells: should be 1. +- #size-cells: should be 0. +- reg: Address and length of the register set for the device +- resets: phandle to the reset controller asserting this device in + reset + See ../reset/reset.txt for details. + +Optional properties: +- cs-gpios: see spi-bus.txt. + +Example: + +- SoC Specific Portion: +spi0: spi@b00 { + compatible = "ralink,mt7621-spi"; + reg = <0xb00 0x100>; + #address-cells = <1>; + #size-cells = <0>; + resets = <&rstctrl 18>; + reset-names = "spi"; +}; diff --git a/Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt b/Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt new file mode 100644 index 000000000000..16b734ad3102 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-zynq-qspi.txt @@ -0,0 +1,25 @@ +Xilinx Zynq QSPI controller Device Tree Bindings +------------------------------------------------------------------- + +Required properties: +- compatible : Should be "xlnx,zynq-qspi-1.0". +- reg : Physical base address and size of QSPI registers map. +- interrupts : Property with a value describing the interrupt + number. +- clock-names : List of input clock names - "ref_clk", "pclk" + (See clock bindings for details). +- clocks : Clock phandles (see clock bindings for details). + +Optional properties: +- num-cs : Number of chip selects used. + +Example: + qspi: spi@e000d000 { + compatible = "xlnx,zynq-qspi-1.0"; + reg = <0xe000d000 0x1000>; + interrupt-parent = <&intc>; + interrupts = <0 19 4>; + clock-names = "ref_clk", "pclk"; + clocks = <&clkc 10>, <&clkc 43>; + num-cs = <1>; + }; diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml index c4ab59550fc2..b3f0fe96ff0d 100644 --- a/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml +++ b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml @@ -59,6 +59,7 @@ properties: patternProperties: '^frame@[0-9a-z]*$': + type: object description: A timer node has up to 8 frame sub-nodes, each with the following properties. properties: frame-number: diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index d79fb22bde39..747fd3f689dc 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -92,6 +92,8 @@ properties: - fsl,sgtl5000 # G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface - gmt,g751 + # Infineon IR38064 Voltage Regulator + - infineon,ir38064 # Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) - infineon,slb9635tt # Infineon SLB9645 I2C TPM (new protocol, max 400khz) @@ -102,6 +104,8 @@ properties: - isil,isl29028 # Intersil ISL29030 Ambient Light and Proximity Sensor - isil,isl29030 + # Intersil ISL68137 Digital Output Configurable PWM Controller + - isil,isl68137 # 5 Bit Programmable, Pulse-Width Modulator - maxim,ds1050 # Low-Power, 4-/12-Channel, 2-Wire Serial, 12-Bit ADCs diff --git a/Documentation/devicetree/bindings/ufs/cdns,ufshc.txt b/Documentation/devicetree/bindings/ufs/cdns,ufshc.txt index a04a4989ec7f..02347b017abd 100644 --- a/Documentation/devicetree/bindings/ufs/cdns,ufshc.txt +++ b/Documentation/devicetree/bindings/ufs/cdns,ufshc.txt @@ -5,8 +5,9 @@ Each UFS controller instance should have its own node. Please see the ufshcd-pltfrm.txt for a list of all available properties. Required properties: -- compatible : Compatible list, contains the following controller: - "cdns,ufshc" +- compatible : Compatible list, contains one of the following controllers: + "cdns,ufshc" - Generic CDNS HCI, + "cdns,ufshc-m31-16nm" - CDNS UFS HC + M31 16nm PHY complemented with the JEDEC version: "jedec,ufs-2.0" diff --git a/Documentation/devicetree/bindings/ufs/ufs-mediatek.txt b/Documentation/devicetree/bindings/ufs/ufs-mediatek.txt new file mode 100644 index 000000000000..72aab8547308 --- /dev/null +++ b/Documentation/devicetree/bindings/ufs/ufs-mediatek.txt @@ -0,0 +1,43 @@ +* Mediatek Universal Flash Storage (UFS) Host Controller + +UFS nodes are defined to describe on-chip UFS hardware macro. +Each UFS Host Controller should have its own node. + +To bind UFS PHY with UFS host controller, the controller node should +contain a phandle reference to UFS M-PHY node. + +Required properties for UFS nodes: +- compatible : Compatible list, contains the following controller: + "mediatek,mt8183-ufshci" for MediaTek UFS host controller + present on MT81xx chipsets. +- reg : Address and length of the UFS register set. +- phys : phandle to m-phy. +- clocks : List of phandle and clock specifier pairs. +- clock-names : List of clock input name strings sorted in the same + order as the clocks property. "ufs" is mandatory. + "ufs": ufshci core control clock. +- freq-table-hz : Array of <min max> operating frequencies stored in the same + order as the clocks property. If this property is not + defined or a value in the array is "0" then it is assumed + that the frequency is set by the parent clock or a + fixed rate clock source. +- vcc-supply : phandle to VCC supply regulator node. + +Example: + + ufsphy: phy@11fa0000 { + ... + }; + + ufshci@11270000 { + compatible = "mediatek,mt8183-ufshci"; + reg = <0 0x11270000 0 0x2300>; + interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>; + phys = <&ufsphy>; + + clocks = <&infracfg_ao INFRACFG_AO_UFS_CG>; + clock-names = "ufs"; + freq-table-hz = <0 0>; + + vcc-supply = <&mt_pmic_vemc_ldo_reg>; + }; diff --git a/Documentation/devicetree/bindings/ufs/ufs-qcom.txt b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt index 21d9a93db2e9..fd59f93e9556 100644 --- a/Documentation/devicetree/bindings/ufs/ufs-qcom.txt +++ b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt @@ -29,6 +29,7 @@ Optional properties: - vdda-pll-max-microamp : specifies max. load that can be drawn from pll supply - vddp-ref-clk-supply : phandle to UFS device ref_clk pad power supply - vddp-ref-clk-max-microamp : specifies max. load that can be drawn from this supply +- resets : specifies the PHY reset in the UFS controller Example: @@ -51,9 +52,11 @@ Example: <&clock_gcc clk_ufs_phy_ldo>, <&clock_gcc clk_gcc_ufs_tx_cfg_clk>, <&clock_gcc clk_gcc_ufs_rx_cfg_clk>; + resets = <&ufshc 0>; }; - ufshc@fc598000 { + ufshc: ufshc@fc598000 { + #reset-cells = <1>; ... phys = <&ufsphy1>; phy-names = "ufsphy"; diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt index 5111e9130bc3..56bccde9953a 100644 --- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt +++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt @@ -31,7 +31,6 @@ Optional properties: - vcc-max-microamp : specifies max. load that can be drawn from vcc supply - vccq-max-microamp : specifies max. load that can be drawn from vccq supply - vccq2-max-microamp : specifies max. load that can be drawn from vccq2 supply -- <name>-fixed-regulator : boolean property specifying that <name>-supply is a fixed regulator - clocks : List of phandle and clock specifier pairs - clock-names : List of clock input name strings sorted in the same @@ -50,6 +49,8 @@ Optional properties: -lanes-per-direction : number of lanes available per direction - either 1 or 2. Note that it is assume same number of lanes is used both directions at once. If not specified, default is 2 lanes per direction. +- #reset-cells : Must be <1> for Qualcomm UFS controllers that expose + PHY reset from the UFS controller. - resets : reset node register - reset-names : describe reset node register, the "rst" corresponds to reset the whole UFS IP. @@ -63,7 +64,6 @@ Example: interrupts = <0 28 0>; vdd-hba-supply = <&xxx_reg0>; - vdd-hba-fixed-regulator; vcc-supply = <&xxx_reg1>; vcc-supply-1p8; vccq-supply = <&xxx_reg2>; @@ -79,4 +79,5 @@ Example: reset-names = "rst"; phys = <&ufsphy1>; phy-names = "ufsphy"; + #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt b/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt index 9a8b631904fd..b9f04e617eb7 100644 --- a/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt +++ b/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt @@ -40,3 +40,91 @@ Example device nodes: phy-names = "usb2-phy", "usb3-phy"; }; }; + +Amlogic Meson G12A DWC3 USB SoC Controller Glue + +The Amlogic G12A embeds a DWC3 USB IP Core configured for USB2 and USB3 +in host-only mode, and a DWC2 IP Core configured for USB2 peripheral mode +only. + +A glue connects the DWC3 core to USB2 PHYs and optionnaly to an USB3 PHY. + +One of the USB2 PHY can be re-routed in peripheral mode to a DWC2 USB IP. + +The DWC3 Glue controls the PHY routing and power, an interrupt line is +connected to the Glue to serve as OTG ID change detection. + +Required properties: +- compatible: Should be "amlogic,meson-g12a-usb-ctrl" +- clocks: a handle for the "USB" clock +- resets: a handle for the shared "USB" reset line +- reg: The base address and length of the registers +- interrupts: the interrupt specifier for the OTG detection +- phys: handle to used PHYs on the system + - a <0> phandle can be used if a PHY is not used +- phy-names: names of the used PHYs on the system : + - "usb2-phy0" for USB2 PHY0 if USBHOST_A port is used + - "usb2-phy1" for USB2 PHY1 if USBOTG_B port is used + - "usb3-phy0" for USB3 PHY if USB3_0 is used +- dr_mode: should be "host", "peripheral", or "otg" depending on + the usage and configuration of the OTG Capable port. + - "host" and "peripheral" means a fixed Host or Device only connection + - "otg" means the port can be used as both Host or Device and + be switched automatically using the OTG ID pin. + +Optional properties: +- vbus-supply: should be a phandle to the regulator controlling the VBUS + power supply when used in OTG switchable mode + +Required child nodes: + +A child node must exist to represent the core DWC3 IP block. The name of +the node is not important. The content of the node is defined in dwc3.txt. + +A child node must exist to represent the core DWC2 IP block. The name of +the node is not important. The content of the node is defined in dwc2.txt. + +PHY documentation is provided in the following places: +- Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt +- Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt + +Example device nodes: + usb: usb@ffe09000 { + compatible = "amlogic,meson-g12a-usb-ctrl"; + reg = <0x0 0xffe09000 0x0 0xa0>; + interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <2>; + #size-cells = <2>; + ranges; + + clocks = <&clkc CLKID_USB>; + resets = <&reset RESET_USB>; + + dr_mode = "otg"; + + phys = <&usb2_phy0>, <&usb2_phy1>, + <&usb3_pcie_phy PHY_TYPE_USB3>; + phy-names = "usb2-phy0", "usb2-phy1", "usb3-phy0"; + + dwc2: usb@ff400000 { + compatible = "amlogic,meson-g12a-usb", "snps,dwc2"; + reg = <0x0 0xff400000 0x0 0x40000>; + interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clkc CLKID_USB1_DDR_BRIDGE>; + clock-names = "ddr"; + phys = <&usb2_phy1>; + dr_mode = "peripheral"; + g-rx-fifo-size = <192>; + g-np-tx-fifo-size = <128>; + g-tx-fifo-size = <128 128 16 16 16>; + }; + + dwc3: usb@ff500000 { + compatible = "snps,dwc3"; + reg = <0x0 0xff500000 0x0 0x100000>; + interrupts = <GIC_SPI 30 IRQ_TYPE_LEVEL_HIGH>; + dr_mode = "host"; + snps,dis_u2_susphy_quirk; + snps,quirk-frame-length-adjustment; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index 6dc3c4a34483..49eac0dc86b0 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -14,6 +14,7 @@ Required properties: - "amlogic,meson8-usb": The DWC2 USB controller instance in Amlogic Meson8 SoCs; - "amlogic,meson8b-usb": The DWC2 USB controller instance in Amlogic Meson8b SoCs; - "amlogic,meson-gxbb-usb": The DWC2 USB controller instance in Amlogic S905 SoCs; + - "amlogic,meson-g12a-usb": The DWC2 USB controller instance in Amlogic G12A SoCs; - "amcc,dwc-otg": The DWC2 USB controller instance in AMCC Canyonlands 460EX SoCs; - snps,dwc2: A generic DWC2 USB controller with default parameters. - "st,stm32f4x9-fsotg": The DWC2 USB FS/HS controller instance in STM32F4x9 SoCs @@ -31,12 +32,18 @@ Refer to clk/clock-bindings.txt for generic clock consumer properties Optional properties: - phys: phy provider specifier - phy-names: shall be "usb2-phy" +- vbus-supply: reference to the VBUS regulator. Depending on the current mode + this is enabled (in "host" mode") or disabled (in "peripheral" mode). The + regulator is updated if the controller is configured in "otg" mode and the + status changes between "host" and "peripheral". Refer to phy/phy-bindings.txt for generic phy consumer properties - dr_mode: shall be one of "host", "peripheral" and "otg" Refer to usb/generic.txt - g-rx-fifo-size: size of rx fifo size in gadget mode. - g-np-tx-fifo-size: size of non-periodic tx fifo size in gadget mode. - g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) in gadget mode. +- snps,reset-phy-on-wake: If present indicates that we need to reset the PHY when + we detect a wakeup. This is due to a hardware errata. Deprecated properties: - g-use-dma: gadget DMA mode is automatically detected diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml new file mode 100644 index 000000000000..d3b4f6415920 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/generic-ehci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: USB EHCI Controller Device Tree Bindings + +allOf: + - $ref: "usb-hcd.yaml" + +maintainers: + - Greg Kroah-Hartman <gregkh@linuxfoundation.org> + +properties: + compatible: + contains: + const: generic-ehci + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + minItems: 1 + maxItems: 4 + + clocks: + minItems: 1 + maxItems: 4 + description: | + In case the Renesas R-Car Gen3 SoCs: + - if a host only channel: first clock should be host. + - if a USB DRD channel: first clock should be host and second + one should be peripheral + + big-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag for HCDs with big endian descriptors and big + endian registers. + + big-endian-desc: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag for HCDs with big endian descriptors. + + big-endian-regs: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag for HCDs with big endian registers. + + has-transaction-translator: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag if EHCI has a Transaction Translator built into + the root hub. + + needs-reset-on-resume: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag to force EHCI reset after resume. + + phys: true + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + ehci@e0000300 { + compatible = "ibm,usb-ehci-440epx", "generic-ehci"; + interrupt-parent = <&UIC0>; + interrupts = <0x1a 4>; + reg = <0 0xe0000300 90 0 0xe0000390 70>; + big-endian; + }; + + - | + ehci0: usb@1c14000 { + compatible = "allwinner,sun4i-a10-ehci", "generic-ehci"; + reg = <0x01c14000 0x100>; + interrupts = <39>; + clocks = <&ahb_gates 1>; + phys = <&usbphy 1>; + phy-names = "usb"; + }; + +... diff --git a/Documentation/devicetree/bindings/usb/generic-ohci.yaml b/Documentation/devicetree/bindings/usb/generic-ohci.yaml new file mode 100644 index 000000000000..da5a14becbe5 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/generic-ohci.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/generic-ohci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: USB OHCI Controller Device Tree Bindings + +allOf: + - $ref: "usb-hcd.yaml" + +maintainers: + - Greg Kroah-Hartman <gregkh@linuxfoundation.org> + +properties: + compatible: + contains: + const: generic-ohci + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + minItems: 1 + maxItems: 2 + + clocks: + minItems: 1 + maxItems: 3 + description: | + In case the Renesas R-Car Gen3 SoCs: + - if a host only channel: first clock should be host. + - if a USB DRD channel: first clock should be host and second + one should be peripheral + + big-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag for HCDs with big endian descriptors and big + endian registers. + + big-endian-desc: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag for HCDs with big endian descriptors. + + big-endian-regs: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag for HCDs with big endian registers. + + remote-wakeup-connected: + $ref: /schemas/types.yaml#/definitions/flag + description: + Remote wakeup is wired on the platform. + + no-big-frame-no: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set if frame_no lives in bits [15:0] of HCCA + + num-ports: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Overrides the detected port count + + phys: true + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + ohci0: usb@1c14400 { + compatible = "allwinner,sun4i-a10-ohci", "generic-ohci"; + reg = <0x01c14400 0x100>; + interrupts = <64>; + clocks = <&usb_clk 6>, <&ahb_gates 2>; + phys = <&usbphy 1>; + }; + +... diff --git a/Documentation/devicetree/bindings/usb/ingenic,jz4740-musb.txt b/Documentation/devicetree/bindings/usb/ingenic,jz4740-musb.txt index 620355cee63f..16808721f3ff 100644 --- a/Documentation/devicetree/bindings/usb/ingenic,jz4740-musb.txt +++ b/Documentation/devicetree/bindings/usb/ingenic,jz4740-musb.txt @@ -8,9 +8,15 @@ Required properties: - interrupt-names: must be "mc" - clocks: phandle to the "udc" clock - clock-names: must be "udc" +- phys: phandle to the USB PHY Example: +usb_phy: usb-phy@0 { + compatible = "usb-nop-xceiv"; + #phy-cells = <0>; +}; + udc: usb@13040000 { compatible = "ingenic,jz4740-musb"; reg = <0x13040000 0x10000>; @@ -21,4 +27,6 @@ udc: usb@13040000 { clocks = <&cgu JZ4740_CLK_UDC>; clock-names = "udc"; + + phys = <&usb_phy>; }; diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt index 4156c3e181c5..5bfcc0b4d6b9 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt @@ -10,6 +10,7 @@ Required properties: - Tegra124: "nvidia,tegra124-xusb" - Tegra132: "nvidia,tegra132-xusb", "nvidia,tegra124-xusb" - Tegra210: "nvidia,tegra210-xusb" + - Tegra186: "nvidia,tegra186-xusb" - reg: Must contain the base and length of the xHCI host registers, XUSB FPCI registers and XUSB IPFS registers. - reg-names: Must contain the following entries: @@ -59,6 +60,8 @@ For Tegra210: - avdd-pll-uerefe-supply: PLLE reference PLL power supply. Must supply 1.05 V. - dvdd-pex-pll-supply: PCIe/USB3 PLL power supply. Must supply 1.05 V. - hvdd-pex-pll-e-supply: High-voltage PLLE power supply. Must supply 1.8 V. + +For Tegra210 and Tegra186: - power-domains: A list of PM domain specifiers that reference each power-domain used by the xHCI controller. This list must comprise of a specifier for the XUSBA and XUSBC power-domains. See ../power/power_domain.txt and @@ -78,6 +81,7 @@ Optional properties: - Tegra132: usb2-0, usb2-1, usb2-2, hsic-0, hsic-1, usb3-0, usb3-1 - Tegra210: usb2-0, usb2-1, usb2-2, usb2-3, hsic-0, usb3-0, usb3-1, usb3-2, usb3-3 + - Tegra186: usb2-0, usb2-1, usb2-2, hsic-0, usb3-0, usb3-1, usb3-2 Example: -------- diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index d93b6a1504f2..b8acc2a994a8 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -6,6 +6,7 @@ Required properties: - "renesas,usbhs-r8a7743" for r8a7743 (RZ/G1M) compatible device - "renesas,usbhs-r8a7744" for r8a7744 (RZ/G1N) compatible device - "renesas,usbhs-r8a7745" for r8a7745 (RZ/G1E) compatible device + - "renesas,usbhs-r8a77470" for r8a77470 (RZ/G1C) compatible device - "renesas,usbhs-r8a774a1" for r8a774a1 (RZ/G2M) compatible device - "renesas,usbhs-r8a774c0" for r8a774c0 (RZ/G2E) compatible device - "renesas,usbhs-r8a7790" for r8a7790 (R-Car H2) compatible device diff --git a/Documentation/devicetree/bindings/usb/usb-ehci.txt b/Documentation/devicetree/bindings/usb/usb-ehci.txt deleted file mode 100644 index 406252d14c6b..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-ehci.txt +++ /dev/null @@ -1,46 +0,0 @@ -USB EHCI controllers - -Required properties: - - compatible : should be "generic-ehci". - - reg : should contain at least address and length of the standard EHCI - register set for the device. Optional platform-dependent registers - (debug-port or other) can be also specified here, but only after - definition of standard EHCI registers. - - interrupts : one EHCI interrupt should be described here. - -Optional properties: - - big-endian-regs : boolean, set this for hcds with big-endian registers - - big-endian-desc : boolean, set this for hcds with big-endian descriptors - - big-endian : boolean, for hcds with big-endian-regs + big-endian-desc - - needs-reset-on-resume : boolean, set this to force EHCI reset after resume - - has-transaction-translator : boolean, set this if EHCI have a Transaction - Translator built into the root hub. - - clocks : a list of phandle + clock specifier pairs. In case of Renesas - R-Car Gen3 SoCs: - - if a host only channel: first clock should be host. - - if a USB DRD channel: first clock should be host and second one - should be peripheral. - - phys : see usb-hcd.txt in the current directory - - resets : phandle + reset specifier pair - -additionally the properties from usb-hcd.txt (in the current directory) are -supported. - -Example (Sequoia 440EPx): - ehci@e0000300 { - compatible = "ibm,usb-ehci-440epx", "usb-ehci"; - interrupt-parent = <&UIC0>; - interrupts = <1a 4>; - reg = <0 e0000300 90 0 e0000390 70>; - big-endian; - }; - -Example (Allwinner sun4i A10 SoC): - ehci0: usb@1c14000 { - compatible = "allwinner,sun4i-a10-ehci", "generic-ehci"; - reg = <0x01c14000 0x100>; - interrupts = <39>; - clocks = <&ahb_gates 1>; - phys = <&usbphy 1>; - phy-names = "usb"; - }; diff --git a/Documentation/devicetree/bindings/usb/usb-hcd.txt b/Documentation/devicetree/bindings/usb/usb-hcd.txt deleted file mode 100644 index 50529b838c9c..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-hcd.txt +++ /dev/null @@ -1,9 +0,0 @@ -Generic USB HCD (Host Controller Device) Properties - -Optional properties: -- phys: a list of all USB PHYs on this HCD - -Example: - &usb1 { - phys = <&usb2_phy1>, <&usb3_phy1>; - }; diff --git a/Documentation/devicetree/bindings/usb/usb-hcd.yaml b/Documentation/devicetree/bindings/usb/usb-hcd.yaml new file mode 100644 index 000000000000..9c8c56d3a792 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-hcd.yaml @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-hcd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic USB Host Controller Device Tree Bindings + +maintainers: + - Greg Kroah-Hartman <gregkh@linuxfoundation.org> + +properties: + $nodename: + pattern: "^usb(@.*)?" + + phys: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + List of all the USB PHYs on this HCD + +examples: + - | + usb { + phys = <&usb2_phy1>, <&usb3_phy1>; + }; diff --git a/Documentation/devicetree/bindings/usb/usb-ohci.txt b/Documentation/devicetree/bindings/usb/usb-ohci.txt deleted file mode 100644 index aaaa5255c972..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-ohci.txt +++ /dev/null @@ -1,35 +0,0 @@ -USB OHCI controllers - -Required properties: -- compatible : "generic-ohci" -- reg : ohci controller register range (address and length) -- interrupts : ohci controller interrupt - -Optional properties: -- big-endian-regs : boolean, set this for hcds with big-endian registers -- big-endian-desc : boolean, set this for hcds with big-endian descriptors -- big-endian : boolean, for hcds with big-endian-regs + big-endian-desc -- no-big-frame-no : boolean, set if frame_no lives in bits [15:0] of HCCA -- remote-wakeup-connected: remote wakeup is wired on the platform -- num-ports : u32, to override the detected port count -- clocks : a list of phandle + clock specifier pairs. In case of Renesas - R-Car Gen3 SoCs: - - if a host only channel: first clock should be host. - - if a USB DRD channel: first clock should be host and second one - should be peripheral. -- phys : see usb-hcd.txt in the current directory -- resets : a list of phandle + reset specifier pairs - -additionally the properties from usb-hcd.txt (in the current directory) are -supported. - -Example: - - ohci0: usb@1c14400 { - compatible = "allwinner,sun4i-a10-ohci", "generic-ohci"; - reg = <0x01c14400 0x100>; - interrupts = <64>; - clocks = <&usb_clk 6>, <&ahb_gates 2>; - phys = <&usbphy 1>; - phy-names = "usb"; - }; diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index fea8b1545751..97400e8f8605 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -10,6 +10,7 @@ Required properties: - "renesas,xhci-r8a7743" for r8a7743 SoC - "renesas,xhci-r8a7744" for r8a7744 SoC - "renesas,xhci-r8a774a1" for r8a774a1 SoC + - "renesas,xhci-r8a774c0" for r8a774c0 SoC - "renesas,xhci-r8a7790" for r8a7790 SoC - "renesas,xhci-r8a7791" for r8a7791 SoC - "renesas,xhci-r8a7793" for r8a7793 SoC diff --git a/Documentation/devicetree/bindings/usb/usb251xb.txt b/Documentation/devicetree/bindings/usb/usb251xb.txt index 17915f64b8ee..bc7945e9dbfe 100644 --- a/Documentation/devicetree/bindings/usb/usb251xb.txt +++ b/Documentation/devicetree/bindings/usb/usb251xb.txt @@ -64,8 +64,10 @@ Optional properties : - power-on-time-ms : Specifies the time it takes from the time the host initiates the power-on sequence to a port until the port has adequate power. The value is given in ms in a 0 - 510 range (default is 100ms). - - swap-dx-lanes : Specifies the ports which will swap the differential-pair - (D+/D-), default is not-swapped. + - swap-dx-lanes : Specifies the downstream ports which will swap the + differential-pair (D+/D-), default is not-swapped. + - swap-us-lanes : Selects the upstream port differential-pair (D+/D-) + swapping (boolean, default is not-swapped) Examples: usb2512b@2c { diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 8162b0eb4b50..e0e216002efd 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -36,6 +36,7 @@ aptina Aptina Imaging arasan Arasan Chip Systems archermind ArcherMind Technology (Nanjing) Co., Ltd. arctic Arctic Sand +arcx arcx Inc. / Archronix Inc. aries Aries Embedded GmbH arm ARM Ltd. armadeus ARMadeus Systems SARL @@ -54,6 +55,7 @@ avic Shanghai AVIC Optoelectronics Co., Ltd. avnet Avnet, Inc. axentia Axentia Technologies AB axis Axis Communications AB +azoteq Azoteq (Pty) Ltd bananapi BIPAI KEJI LIMITED bhf Beckhoff Automation GmbH & Co. KG bitmain Bitmain Technologies @@ -210,6 +212,7 @@ kiebackpeter Kieback & Peter GmbH kinetic Kinetic Technologies kingdisplay King & Display Technology Co., Ltd. kingnovel Kingnovel Technology Co., Ltd. +kionix Kionix, Inc. koe Kaohsiung Opto-Electronics Inc. kosagi Sutajio Ko-Usagi PTE Ltd. kyo Kyocera Corporation @@ -233,6 +236,7 @@ lsi LSI Corp. (LSI Logic) lwn Liebherr-Werk Nenzing GmbH macnica Macnica Americas marvell Marvell Technology Group Ltd. +maxbotix MaxBotix Inc. maxim Maxim Integrated Products mbvl Mobiveil Inc. mcube mCube @@ -302,6 +306,7 @@ oranth Shenzhen Oranth Technology Co., Ltd. ORCL Oracle Corporation orisetech Orise Technology ortustech Ortus Technology Co., Ltd. +osddisplays OSD Displays ovti OmniVision Technologies oxsemi Oxford Semiconductor, Ltd. panasonic Panasonic Corporation @@ -344,7 +349,9 @@ ricoh Ricoh Co. Ltd. rikomagic Rikomagic Tech Corp. Ltd riscv RISC-V Foundation rockchip Fuzhou Rockchip Electronics Co., Ltd +rocktech ROCKTECH DISPLAYS LIMITED rohm ROHM Semiconductor Co., Ltd +ronbo Ronbo Electronics roofull Shenzhen Roofull Technology Co, Ltd samsung Samsung Semiconductor samtec Samtec/Softing company diff --git a/Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt b/Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt new file mode 100644 index 000000000000..02b87e92ae68 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/fsl-imx-sc-wdt.txt @@ -0,0 +1,24 @@ +* Freescale i.MX System Controller Watchdog + +i.MX system controller watchdog is for i.MX SoCs with system controller inside, +the watchdog is managed by system controller, users can ONLY communicate with +system controller from secure mode for watchdog operations, so Linux i.MX system +controller watchdog driver will call ARM SMC API and trap into ARM-Trusted-Firmware +for watchdog operations, ARM-Trusted-Firmware is running at secure EL3 mode and +it will request system controller to execute the watchdog operation passed from +Linux kernel. + +Required properties: +- compatible: Should be : + "fsl,imx8qxp-sc-wdt" + followed by "fsl,imx-sc-wdt"; + +Optional properties: +- timeout-sec : Contains the watchdog timeout in seconds. + +Examples: + +watchdog { + compatible = "fsl,imx8qxp-sc-wdt", "fsl,imx-sc-wdt"; + timeout-sec = <60>; +}; diff --git a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt index 8682d6a93e5b..fd380eb28df5 100644 --- a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt @@ -9,6 +9,7 @@ Required properties: "mediatek,mt7622-wdt", "mediatek,mt6589-wdt": for MT7622 "mediatek,mt7623-wdt", "mediatek,mt6589-wdt": for MT7623 "mediatek,mt7629-wdt", "mediatek,mt6589-wdt": for MT7629 + "mediatek,mt8516-wdt", "mediatek,mt6589-wdt": for MT8516 - reg : Specifies base physical address and size of the registers. diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.txt new file mode 100644 index 000000000000..27dfd2d8016e --- /dev/null +++ b/Documentation/devicetree/bindings/writing-bindings.txt @@ -0,0 +1,60 @@ +DOs and DON'Ts for designing and writing Devicetree bindings + +This is a list of common review feedback items focused on binding design. With +every rule, there are exceptions and bindings have many gray areas. + +For guidelines related to patches, see +Documentation/devicetree/bindings/submitting-patches.txt + + +Overall design + +- DO attempt to make bindings complete even if a driver doesn't support some + features. For example, if a device has an interrupt, then include the + 'interrupts' property even if the driver is only polled mode. + +- DON'T refer to Linux or "device driver" in bindings. Bindings should be + based on what the hardware has, not what an OS and driver currently support. + +- DO use node names matching the class of the device. Many standard names are + defined in the DT Spec. If there isn't one, consider adding it. + +- DO check that the example matches the documentation especially after making + review changes. + +- DON'T create nodes just for the sake of instantiating drivers. Multi-function + devices only need child nodes when the child nodes have their own DT + resources. A single node can be multiple providers (e.g. clocks and resets). + +- DON'T use 'syscon' alone without a specific compatible string. A 'syscon' + hardware block should have a compatible string unique enough to infer the + register layout of the entire block (at a minimum). + + +Properties + +- DO make 'compatible' properties specific. DON'T use wildcards in compatible + strings. DO use fallback compatibles when devices are the same as or a subset + of prior implementations. DO add new compatibles in case there are new + features or bugs. + +- DO use a vendor prefix on device specific property names. Consider if + properties could be common among devices of the same class. Check other + existing bindings for similar devices. + +- DON'T redefine common properties. Just reference the definition and define + constraints specific to the device. + +- DO use common property unit suffixes for properties with scientific units. + See property-units.txt. + +- DO define properties in terms of constraints. How many entries? What are + possible values? What is the order? + + +Board/SoC .dts Files + +- DO put all MMIO devices under a bus node and not at the top-level. + +- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit + platforms don't need all devices to have 64-bit address and size. diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md index a3652d33a48f..dc032db36262 100644 --- a/Documentation/devicetree/writing-schema.md +++ b/Documentation/devicetree/writing-schema.md @@ -97,7 +97,7 @@ The DT schema project must be installed in order to validate the DT schema binding documents and validate DTS files using the DT schema. The DT schema project can be installed with pip: -`pip3 install git+https://github.com/robherring/yaml-bindings.git@master` +`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master` dtc must also be built with YAML output support enabled. This requires that libyaml and its headers be installed on the host system. diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst index a7f95d7d3a63..603f3ff55d5a 100644 --- a/Documentation/doc-guide/index.rst +++ b/Documentation/doc-guide/index.rst @@ -7,9 +7,9 @@ How to write kernel documentation .. toctree:: :maxdepth: 1 - sphinx.rst - kernel-doc.rst - parse-headers.rst + sphinx + kernel-doc + parse-headers .. only:: subproject and html diff --git a/Documentation/dontdiff b/Documentation/dontdiff index ef25a066d952..5eba889ea84d 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -127,7 +127,7 @@ flask.h fore200e_mkfirm fore200e_pca_fw.c* gconf -gconf.glade.h +gconf-cfg gen-devlist gen_crc32table gen_init_cpio @@ -148,24 +148,22 @@ int32.c int4.c int8.c kallsyms -kconfig keywords.c ksym.c* ksym.h* -kxgettext *lex.c *lex.*.c linux logo_*.c logo_*_clut224.c logo_*_mono.c -lxdialog mach-types mach-types.h machtypes.h map map_hugetlb mconf +mconf-cfg miboot* mk_elfconfig mkboot @@ -176,11 +174,14 @@ mkprep mkregtable mktables mktree +mkutf8data modpost modules.builtin +modules.builtin.modinfo modules.order modversions.h* nconf +nconf-cfg ncscope.* offset.h oui.c* @@ -200,6 +201,7 @@ pnmtologo ppc_defs.h* pss_boot.h qconf +qconf-cfg r100_reg_safe.h r200_reg_safe.h r300_reg_safe.h @@ -254,6 +256,7 @@ vsyscall_32.lds wanxlfw.inc uImage unifdef +utf8data.h wakeup.bin wakeup.elf wakeup.lds diff --git a/Documentation/driver-api/component.rst b/Documentation/driver-api/component.rst index 2da4a8f20607..57e37590733f 100644 --- a/Documentation/driver-api/component.rst +++ b/Documentation/driver-api/component.rst @@ -1,3 +1,5 @@ +.. _component: + ====================================== Component Helper for Aggregate Drivers ====================================== diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst new file mode 100644 index 000000000000..f51db893f595 --- /dev/null +++ b/Documentation/driver-api/generic-counter.rst @@ -0,0 +1,342 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Generic Counter Interface +========================= + +Introduction +============ + +Counter devices are prevalent within a diverse spectrum of industries. +The ubiquitous presence of these devices necessitates a common interface +and standard of interaction and exposure. This driver API attempts to +resolve the issue of duplicate code found among existing counter device +drivers by introducing a generic counter interface for consumption. The +Generic Counter interface enables drivers to support and expose a common +set of components and functionality present in counter devices. + +Theory +====== + +Counter devices can vary greatly in design, but regardless of whether +some devices are quadrature encoder counters or tally counters, all +counter devices consist of a core set of components. This core set of +components, shared by all counter devices, is what forms the essence of +the Generic Counter interface. + +There are three core components to a counter: + +* Count: + Count data for a set of Signals. + +* Signal: + Input data that is evaluated by the counter to determine the count + data. + +* Synapse: + The association of a Signal with a respective Count. + +COUNT +----- +A Count represents the count data for a set of Signals. The Generic +Counter interface provides the following available count data types: + +* COUNT_POSITION: + Unsigned integer value representing position. + +A Count has a count function mode which represents the update behavior +for the count data. The Generic Counter interface provides the following +available count function modes: + +* Increase: + Accumulated count is incremented. + +* Decrease: + Accumulated count is decremented. + +* Pulse-Direction: + Rising edges on signal A updates the respective count. The input level + of signal B determines direction. + +* Quadrature: + A pair of quadrature encoding signals are evaluated to determine + position and direction. The following Quadrature modes are available: + + - x1 A: + If direction is forward, rising edges on quadrature pair signal A + updates the respective count; if the direction is backward, falling + edges on quadrature pair signal A updates the respective count. + Quadrature encoding determines the direction. + + - x1 B: + If direction is forward, rising edges on quadrature pair signal B + updates the respective count; if the direction is backward, falling + edges on quadrature pair signal B updates the respective count. + Quadrature encoding determines the direction. + + - x2 A: + Any state transition on quadrature pair signal A updates the + respective count. Quadrature encoding determines the direction. + + - x2 B: + Any state transition on quadrature pair signal B updates the + respective count. Quadrature encoding determines the direction. + + - x4: + Any state transition on either quadrature pair signals updates the + respective count. Quadrature encoding determines the direction. + +A Count has a set of one or more associated Signals. + +SIGNAL +------ +A Signal represents a counter input data; this is the input data that is +evaluated by the counter to determine the count data; e.g. a quadrature +signal output line of a rotary encoder. Not all counter devices provide +user access to the Signal data. + +The Generic Counter interface provides the following available signal +data types for when the Signal data is available for user access: + +* SIGNAL_LEVEL: + Signal line state level. The following states are possible: + + - SIGNAL_LEVEL_LOW: + Signal line is in a low state. + + - SIGNAL_LEVEL_HIGH: + Signal line is in a high state. + +A Signal may be associated with one or more Counts. + +SYNAPSE +------- +A Synapse represents the association of a Signal with a respective +Count. Signal data affects respective Count data, and the Synapse +represents this relationship. + +The Synapse action mode specifies the Signal data condition which +triggers the respective Count's count function evaluation to update the +count data. The Generic Counter interface provides the following +available action modes: + +* None: + Signal does not trigger the count function. In Pulse-Direction count + function mode, this Signal is evaluated as Direction. + +* Rising Edge: + Low state transitions to high state. + +* Falling Edge: + High state transitions to low state. + +* Both Edges: + Any state transition. + +A counter is defined as a set of input signals associated with count +data that are generated by the evaluation of the state of the associated +input signals as defined by the respective count functions. Within the +context of the Generic Counter interface, a counter consists of Counts +each associated with a set of Signals, whose respective Synapse +instances represent the count function update conditions for the +associated Counts. + +Paradigm +======== + +The most basic counter device may be expressed as a single Count +associated with a single Signal via a single Synapse. Take for example +a counter device which simply accumulates a count of rising edges on a +source input line:: + + Count Synapse Signal + ----- ------- ------ + +---------------------+ + | Data: Count | Rising Edge ________ + | Function: Increase | <------------- / Source \ + | | ____________ + +---------------------+ + +In this example, the Signal is a source input line with a pulsing +voltage, while the Count is a persistent count value which is repeatedly +incremented. The Signal is associated with the respective Count via a +Synapse. The increase function is triggered by the Signal data condition +specified by the Synapse -- in this case a rising edge condition on the +voltage input line. In summary, the counter device existence and +behavior is aptly represented by respective Count, Signal, and Synapse +components: a rising edge condition triggers an increase function on an +accumulating count datum. + +A counter device is not limited to a single Signal; in fact, in theory +many Signals may be associated with even a single Count. For example, a +quadrature encoder counter device can keep track of position based on +the states of two input lines:: + + Count Synapse Signal + ----- ------- ------ + +-------------------------+ + | Data: Position | Both Edges ___ + | Function: Quadrature x4 | <------------ / A \ + | | _______ + | | + | | Both Edges ___ + | | <------------ / B \ + | | _______ + +-------------------------+ + +In this example, two Signals (quadrature encoder lines A and B) are +associated with a single Count: a rising or falling edge on either A or +B triggers the "Quadrature x4" function which determines the direction +of movement and updates the respective position data. The "Quadrature +x4" function is likely implemented in the hardware of the quadrature +encoder counter device; the Count, Signals, and Synapses simply +represent this hardware behavior and functionality. + +Signals associated with the same Count can have differing Synapse action +mode conditions. For example, a quadrature encoder counter device +operating in a non-quadrature Pulse-Direction mode could have one input +line dedicated for movement and a second input line dedicated for +direction:: + + Count Synapse Signal + ----- ------- ------ + +---------------------------+ + | Data: Position | Rising Edge ___ + | Function: Pulse-Direction | <------------- / A \ (Movement) + | | _______ + | | + | | None ___ + | | <------------- / B \ (Direction) + | | _______ + +---------------------------+ + +Only Signal A triggers the "Pulse-Direction" update function, but the +instantaneous state of Signal B is still required in order to know the +direction so that the position data may be properly updated. Ultimately, +both Signals are associated with the same Count via two respective +Synapses, but only one Synapse has an active action mode condition which +triggers the respective count function while the other is left with a +"None" condition action mode to indicate its respective Signal's +availability for state evaluation despite its non-triggering mode. + +Keep in mind that the Signal, Synapse, and Count are abstract +representations which do not need to be closely married to their +respective physical sources. This allows the user of a counter to +divorce themselves from the nuances of physical components (such as +whether an input line is differential or single-ended) and instead focus +on the core idea of what the data and process represent (e.g. position +as interpreted from quadrature encoding data). + +Userspace Interface +=================== + +Several sysfs attributes are generated by the Generic Counter interface, +and reside under the /sys/bus/counter/devices/counterX directory, where +counterX refers to the respective counter device. Please see +Documentation/ABI/testing/sys-bus-counter-generic-sysfs for detailed +information on each Generic Counter interface sysfs attribute. + +Through these sysfs attributes, programs and scripts may interact with +the Generic Counter paradigm Counts, Signals, and Synapses of respective +counter devices. + +Driver API +========== + +Driver authors may utilize the Generic Counter interface in their code +by including the include/linux/counter.h header file. This header file +provides several core data structures, function prototypes, and macros +for defining a counter device. + +.. kernel-doc:: include/linux/counter.h + :internal: + +.. kernel-doc:: drivers/counter/generic-counter.c + :export: + +Implementation +============== + +To support a counter device, a driver must first allocate the available +Counter Signals via counter_signal structures. These Signals should +be stored as an array and set to the signals array member of an +allocated counter_device structure before the Counter is registered to +the system. + +Counter Counts may be allocated via counter_count structures, and +respective Counter Signal associations (Synapses) made via +counter_synapse structures. Associated counter_synapse structures are +stored as an array and set to the the synapses array member of the +respective counter_count structure. These counter_count structures are +set to the counts array member of an allocated counter_device structure +before the Counter is registered to the system. + +Driver callbacks should be provided to the counter_device structure via +a constant counter_ops structure in order to communicate with the +device: to read and write various Signals and Counts, and to set and get +the "action mode" and "function mode" for various Synapses and Counts +respectively. + +A defined counter_device structure may be registered to the system by +passing it to the counter_register function, and unregistered by passing +it to the counter_unregister function. Similarly, the +devm_counter_register and devm_counter_unregister functions may be used +if device memory-managed registration is desired. + +Extension sysfs attributes can be created for auxiliary functionality +and data by passing in defined counter_device_ext, counter_count_ext, +and counter_signal_ext structures. In these cases, the +counter_device_ext structure is used for global configuration of the +respective Counter device, while the counter_count_ext and +counter_signal_ext structures allow for auxiliary exposure and +configuration of a specific Count or Signal respectively. + +Architecture +============ + +When the Generic Counter interface counter module is loaded, the +counter_init function is called which registers a bus_type named +"counter" to the system. Subsequently, when the module is unloaded, the +counter_exit function is called which unregisters the bus_type named +"counter" from the system. + +Counter devices are registered to the system via the counter_register +function, and later removed via the counter_unregister function. The +counter_register function establishes a unique ID for the Counter +device and creates a respective sysfs directory, where X is the +mentioned unique ID: + + /sys/bus/counter/devices/counterX + +Sysfs attributes are created within the counterX directory to expose +functionality, configurations, and data relating to the Counts, Signals, +and Synapses of the Counter device, as well as options and information +for the Counter device itself. + +Each Signal has a directory created to house its relevant sysfs +attributes, where Y is the unique ID of the respective Signal: + + /sys/bus/counter/devices/counterX/signalY + +Similarly, each Count has a directory created to house its relevant +sysfs attributes, where Y is the unique ID of the respective Count: + + /sys/bus/counter/devices/counterX/countY + +For a more detailed breakdown of the available Generic Counter interface +sysfs attributes, please refer to the +Documentation/ABI/testing/sys-bus-counter file. + +The Signals and Counts associated with the Counter device are registered +to the system as well by the counter_register function. The +signal_read/signal_write driver callbacks are associated with their +respective Signal attributes, while the count_read/count_write and +function_get/function_set driver callbacks are associated with their +respective Count attributes; similarly, the same is true for the +action_get/action_set driver callbacks and their respective Synapse +attributes. If a driver callback is left undefined, then the respective +read/write permission is left disabled for the relevant attributes. + +Similarly, extension sysfs attributes are created for the defined +counter_device_ext, counter_count_ext, and counter_signal_ext +structures that are passed in. diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 3043167fc557..1ce7fcd0f989 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -1,10 +1,8 @@ -================================ -GPIO Descriptor Driver Interface -================================ +===================== +GPIO Driver Interface +===================== -This document serves as a guide for GPIO chip drivers writers. Note that it -describes the new descriptor-based interface. For a description of the -deprecated integer-based GPIO interface please refer to gpio-legacy.txt. +This document serves as a guide for writers of GPIO chip drivers. Each GPIO controller driver needs to include the following header, which defines the structures used to define a GPIO driver: @@ -15,32 +13,49 @@ the structures used to define a GPIO driver: Internal Representation of GPIOs ================================ -Inside a GPIO driver, individual GPIOs are identified by their hardware number, -which is a unique number between 0 and n, n being the number of GPIOs managed by -the chip. This number is purely internal: the hardware number of a particular -GPIO descriptor is never made visible outside of the driver. - -On top of this internal number, each GPIO also need to have a global number in -the integer GPIO namespace so that it can be used with the legacy GPIO +A GPIO chip handles one or more GPIO lines. To be considered a GPIO chip, the +lines must conform to the definition: General Purpose Input/Output. If the +line is not general purpose, it is not GPIO and should not be handled by a +GPIO chip. The use case is the indicative: certain lines in a system may be +called GPIO but serve a very particular purpose thus not meeting the criteria +of a general purpose I/O. On the other hand a LED driver line may be used as a +GPIO and should therefore still be handled by a GPIO chip driver. + +Inside a GPIO driver, individual GPIO lines are identified by their hardware +number, sometime also referred to as ``offset``, which is a unique number +between 0 and n-1, n being the number of GPIOs managed by the chip. + +The hardware GPIO number should be something intuitive to the hardware, for +example if a system uses a memory-mapped set of I/O-registers where 32 GPIO +lines are handled by one bit per line in a 32-bit register, it makes sense to +use hardware offsets 0..31 for these, corresponding to bits 0..31 in the +register. + +This number is purely internal: the hardware number of a particular GPIO +line is never made visible outside of the driver. + +On top of this internal number, each GPIO line also needs to have a global +number in the integer GPIO namespace so that it can be used with the legacy GPIO interface. Each chip must thus have a "base" number (which can be automatically -assigned), and for each GPIO the global number will be (base + hardware number). -Although the integer representation is considered deprecated, it still has many -users and thus needs to be maintained. +assigned), and for each GPIO line the global number will be (base + hardware +number). Although the integer representation is considered deprecated, it still +has many users and thus needs to be maintained. -So for example one platform could use numbers 32-159 for GPIOs, with a +So for example one platform could use global numbers 32-159 for GPIOs, with a controller defining 128 GPIOs at a "base" of 32 ; while another platform uses -numbers 0..63 with one set of GPIO controllers, 64-79 with another type of GPIO -controller, and on one particular board 80-95 with an FPGA. The numbers need not -be contiguous; either of those platforms could also use numbers 2000-2063 to -identify GPIOs in a bank of I2C GPIO expanders. +global numbers 0..63 with one set of GPIO controllers, 64-79 with another type +of GPIO controller, and on one particular board 80-95 with an FPGA. The legacy +numbers need not be contiguous; either of those platforms could also use numbers +2000-2063 to identify GPIO lines in a bank of I2C GPIO expanders. Controller Drivers: gpio_chip ============================= In the gpiolib framework each GPIO controller is packaged as a "struct -gpio_chip" (see linux/gpio/driver.h for its complete definition) with members -common to each controller of that type: +gpio_chip" (see <linux/gpio/driver.h> for its complete definition) with members +common to each controller of that type, these should be assigned by the +driver code: - methods to establish GPIO line direction - methods used to access GPIO line values @@ -48,12 +63,12 @@ common to each controller of that type: - method to return the IRQ number associated to a given GPIO line - flag saying whether calls to its methods may sleep - optional line names array to identify lines - - optional debugfs dump method (showing extra state like pullup config) + - optional debugfs dump method (showing extra state information) - optional base number (will be automatically assigned if omitted) - optional label for diagnostics and GPIO chip mapping using platform data The code implementing a gpio_chip should support multiple instances of the -controller, possibly using the driver model. That code will configure each +controller, preferably using the driver model. That code will configure each gpio_chip and issue ``gpiochip_add[_data]()`` or ``devm_gpiochip_add_data()``. Removing a GPIO controller should be rare; use ``[devm_]gpiochip_remove()`` when it is unavoidable. @@ -62,24 +77,28 @@ Often a gpio_chip is part of an instance-specific structure with states not exposed by the GPIO interfaces, such as addressing, power management, and more. Chips such as audio codecs will have complex non-GPIO states. -Any debugfs dump method should normally ignore signals which haven't been -requested as GPIOs. They can use gpiochip_is_requested(), which returns either -NULL or the label associated with that GPIO when it was requested. +Any debugfs dump method should normally ignore lines which haven't been +requested. They can use gpiochip_is_requested(), which returns either +NULL or the label associated with that GPIO line when it was requested. -RT_FULL: the GPIO driver should not use spinlock_t or any sleepable APIs -(like PM runtime) in its gpio_chip implementation (.get/.set and direction -control callbacks) if it is expected to call GPIO APIs from atomic context -on -RT (inside hard IRQ handlers and similar contexts). Normally this should -not be required. +Realtime considerations: the GPIO driver should not use spinlock_t or any +sleepable APIs (like PM runtime) in its gpio_chip implementation (.get/.set +and direction control callbacks) if it is expected to call GPIO APIs from +atomic context on realtime kernels (inside hard IRQ handlers and similar +contexts). Normally this should not be required. GPIO electrical configuration ----------------------------- -GPIOs can be configured for several electrical modes of operation by using the -.set_config() callback. Currently this API supports setting debouncing and -single-ended modes (open drain/open source). These settings are described -below. +GPIO lines can be configured for several electrical modes of operation by using +the .set_config() callback. Currently this API supports setting: + +- Debouncing +- Single-ended modes (open drain/open source) +- Pull up and pull down resistor enablement + +These settings are described below. The .set_config() callback uses the same enumerators and configuration semantics as the generic pin control drivers. This is not a coincidence: it is @@ -94,8 +113,8 @@ description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin numbers on the pin controller so they can properly cross-reference each other. -GPIOs with debounce support ---------------------------- +GPIO lines with debounce support +-------------------------------- Debouncing is a configuration set to a pin indicating that it is connected to a mechanical switch or button, or similar that may bounce. Bouncing means the @@ -111,8 +130,8 @@ a certain number of milliseconds for debouncing, or just "on/off" if that time is not configurable. -GPIOs with open drain/source support ------------------------------------- +GPIO lines with open drain/source support +----------------------------------------- Open drain (CMOS) or open collector (TTL) means the line is not actively driven high: instead you provide the drain/collector as output, so when the transistor @@ -132,13 +151,13 @@ This configuration is normally used as a way to achieve one of two things: - Level-shifting: to reach a logical level higher than that of the silicon where the output resides. -- inverse wire-OR on an I/O line, for example a GPIO line, making it possible +- Inverse wire-OR on an I/O line, for example a GPIO line, making it possible for any driving stage on the line to drive it low even if any other output to the same line is simultaneously driving it high. A special case of this is driving the SCL and SDA lines of an I2C bus, which is by definition a wire-OR bus. -Both usecases require that the line be equipped with a pull-up resistor. This +Both use cases require that the line be equipped with a pull-up resistor. This resistor will make the line tend to high level unless one of the transistors on the rail actively pulls it down. @@ -208,27 +227,91 @@ For open source configuration the same principle is used, just that instead of actively driving the line low, it is set to input. +GPIO lines with pull up/down resistor support +--------------------------------------------- + +A GPIO line can support pull-up/down using the .set_config() callback. This +means that a pull up or pull-down resistor is available on the output of the +GPIO line, and this resistor is software controlled. + +In discrete designs, a pull-up or pull-down resistor is simply soldered on +the circuit board. This is not something we deal or model in software. The +most you will think about these lines is that they will very likely be +configured as open drain or open source (see the section above). + +The .set_config() callback can only turn pull up or down on and off, and will +no have any semantic knowledge about the resistance used. It will only say +switch a bit in a register enabling or disabling pull-up or pull-down. + +If the GPIO line supports shunting in different resistance values for the +pull-up or pull-down resistor, the GPIO chip callback .set_config() will not +suffice. For these complex use cases, a combined GPIO chip and pin controller +need to be implemented, as the pin config interface of a pin controller +supports more versatile control over electrical properties and can handle +different pull-up or pull-down resistance values. + + GPIO drivers providing IRQs ---------------------------- +=========================== + It is custom that GPIO drivers (GPIO chips) are also providing interrupts, most often cascaded off a parent interrupt controller, and in some special cases the GPIO logic is melded with a SoC's primary interrupt controller. -The IRQ portions of the GPIO block are implemented using an irqchip, using +The IRQ portions of the GPIO block are implemented using an irq_chip, using the header <linux/irq.h>. So basically such a driver is utilizing two sub- systems simultaneously: gpio and irq. -RT_FULL: a realtime compliant GPIO driver should not use spinlock_t or any -sleepable APIs (like PM runtime) as part of its irq_chip implementation. +It is legal for any IRQ consumer to request an IRQ from any irqchip even if it +is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and +irq_chip are orthogonal, and offering their services independent of each +other. -* spinlock_t should be replaced with raw_spinlock_t [1]. -* If sleepable APIs have to be used, these can be done from the .irq_bus_lock() +gpiod_to_irq() is just a convenience function to figure out the IRQ for a +certain GPIO line and should not be relied upon to have been called before +the IRQ is used. + +Always prepare the hardware and make it ready for action in respective +callbacks from the GPIO and irq_chip APIs. Do not rely on gpiod_to_irq() having +been called first. + +We can divide GPIO irqchips in two broad categories: + +- CASCADED INTERRUPT CHIPS: this means that the GPIO chip has one common + interrupt output line, which is triggered by any enabled GPIO line on that + chip. The interrupt output line will then be routed to an parent interrupt + controller one level up, in the most simple case the systems primary + interrupt controller. This is modeled by an irqchip that will inspect bits + inside the GPIO controller to figure out which line fired it. The irqchip + part of the driver needs to inspect registers to figure this out and it + will likely also need to acknowledge that it is handling the interrupt + by clearing some bit (sometime implicitly, by just reading a status + register) and it will often need to set up the configuration such as + edge sensitivity (rising or falling edge, or high/low level interrupt for + example). + +- HIERARCHICAL INTERRUPT CHIPS: this means that each GPIO line has a dedicated + irq line to a parent interrupt controller one level up. There is no need + to inquire the GPIO hardware to figure out which line has figured, but it + may still be necessary to acknowledge the interrupt and set up the + configuration such as edge sensitivity. + +Realtime considerations: a realtime compliant GPIO driver should not use +spinlock_t or any sleepable APIs (like PM runtime) as part of its irqchip +implementation. + +- spinlock_t should be replaced with raw_spinlock_t [1]. +- If sleepable APIs have to be used, these can be done from the .irq_bus_lock() and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks on an irqchip. Create the callbacks if needed [2]. -GPIO irqchips usually fall in one of two categories: -* CHAINED GPIO irqchips: these are usually the type that is embedded on +Cascaded GPIO irqchips +---------------------- + +Cascaded GPIO irqchips usually fall in one of three categories: + +- CHAINED CASCADED GPIO IRQCHIPS: these are usually the type that is embedded on an SoC. This means that there is a fast IRQ flow handler for the GPIOs that gets called in a chain from the parent IRQ handler, most typically the system interrupt controller. This means that the GPIO irqchip handler will @@ -245,16 +328,19 @@ GPIO irqchips usually fall in one of two categories: struct gpio_chip, as everything happens directly in the callbacks: no slow bus traffic like I2C can be used. - RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT. - As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used - in chained IRQ handler. - If required (and if it can't be converted to the nested threaded GPIO irqchip) - a chained IRQ handler can be converted to generic irq handler and this way - it will be a threaded IRQ handler on -RT and a hard IRQ handler on non-RT - (for example, see [3]). - Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled, + Realtime considerations: Note that chained IRQ handlers will not be forced + threaded on -RT. As a result, spinlock_t or any sleepable APIs (like PM + runtime) can't be used in a chained IRQ handler. + + If required (and if it can't be converted to the nested threaded GPIO irqchip, + see below) a chained IRQ handler can be converted to generic irq handler and + this way it will become a threaded IRQ handler on -RT and a hard IRQ handler + on non-RT (for example, see [3]). + + The generic_handle_irq() is expected to be called with IRQ disabled, so the IRQ core will complain if it is called from an IRQ handler which is - forced to a thread. The "fake?" raw lock can be used to W/A this problem:: + forced to a thread. The "fake?" raw lock can be used to work around this + problem:: raw_spinlock_t wa_lock; static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank) @@ -263,7 +349,7 @@ GPIO irqchips usually fall in one of two categories: generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit)); raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags); -* GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips", +- GENERIC CHAINED GPIO IRQCHIPS: these are the same as "CHAINED GPIO irqchips", but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is performed by generic IRQ handler which is configured using request_irq(). The GPIO irqchip will then end up calling something like this sequence in @@ -273,16 +359,19 @@ GPIO irqchips usually fall in one of two categories: for each detected GPIO IRQ generic_handle_irq(...); - RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ - core will complain that generic_handle_irq() is called with IRQ enabled and - the same W/A as for "CHAINED GPIO irqchips" can be applied. + Realtime considerations: this kind of handlers will be forced threaded on -RT, + and as result the IRQ core will complain that generic_handle_irq() is called + with IRQ enabled and the same work around as for "CHAINED GPIO irqchips" can + be applied. + +- NESTED THREADED GPIO IRQCHIPS: these are off-chip GPIO expanders and any + other GPIO irqchip residing on the other side of a sleeping bus such as I2C + or SPI. -* NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any - other GPIO irqchip residing on the other side of a sleeping bus. Of course - such drivers that need slow bus traffic to read out IRQ status and similar, - traffic which may in turn incur other IRQs to happen, cannot be handled - in a quick IRQ handler with IRQs disabled. Instead they need to spawn a - thread and then mask the parent IRQ line until the interrupt is handled + Of course such drivers that need slow bus traffic to read out IRQ status and + similar, traffic which may in turn incur other IRQs to happen, cannot be + handled in a quick IRQ handler with IRQs disabled. Instead they need to spawn + a thread and then mask the parent IRQ line until the interrupt is handled by the driver. The hallmark of this driver is to call something like this in its interrupt handler:: @@ -294,36 +383,46 @@ GPIO irqchips usually fall in one of two categories: flag on struct gpio_chip to true, indicating that this chip may sleep when accessing the GPIOs. + These kinds of irqchips are inherently realtime tolerant as they are + already set up to handle sleeping contexts. + + +Infrastructure helpers for GPIO irqchips +---------------------------------------- + To help out in handling the set-up and management of GPIO irqchips and the associated irqdomain and resource allocation callbacks, the gpiolib has some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig symbol: -* gpiochip_irqchip_add(): adds a chained irqchip to a gpiochip. It will pass - the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks - need to embed the gpio_chip in its state container and obtain a pointer - to the container using container_of(). +- gpiochip_irqchip_add(): adds a chained cascaded irqchip to a gpiochip. It + will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the + callbacks need to embed the gpio_chip in its state container and obtain a + pointer to the container using container_of(). (See Documentation/driver-model/design-patterns.txt) -* gpiochip_irqchip_add_nested(): adds a nested irqchip to a gpiochip. +- gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, + as discussed above regarding different types of cascaded irqchips. The + cascaded irq has to be handled by a threaded interrupt handler. Apart from that it works exactly like the chained irqchip. -* gpiochip_set_chained_irqchip(): sets up a chained irq handler for a +- gpiochip_set_chained_irqchip(): sets up a chained cascaded irq handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler - data. (Notice handler data, since the irqchip data is likely used by the - parent irqchip!). + data. Notice that we pass is as the handler data, since the irqchip data is + likely used by the parent irqchip. -* gpiochip_set_nested_irqchip(): sets up a nested irq handler for a +- gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a gpio_chip from a parent IRQ. As the parent IRQ has usually been explicitly requested by the driver, this does very little more than mark all the child IRQs as having the other IRQ as parent. -If there is a need to exclude certain GPIOs from the IRQ domain, you can -set .irq.need_valid_mask of the gpiochip before gpiochip_add_data() is -called. This allocates an .irq.valid_mask with as many bits set as there -are GPIOs in the chip. Drivers can exclude GPIOs by clearing bits from this -mask. The mask must be filled in before gpiochip_irqchip_add() or -gpiochip_irqchip_add_nested() is called. +If there is a need to exclude certain GPIO lines from the IRQ domain handled by +these helpers, we can set .irq.need_valid_mask of the gpiochip before +[devm_]gpiochip_add_data() is called. This allocates an .irq.valid_mask with as +many bits set as there are GPIO lines in the chip, each bit representing line +0..n-1. Drivers can exclude GPIO lines by clearing bits from this mask. The mask +must be filled in before gpiochip_irqchip_add() or gpiochip_irqchip_add_nested() +is called. To use the helpers please keep the following in mind: @@ -333,33 +432,24 @@ To use the helpers please keep the following in mind: - Nominally set all handlers to handle_bad_irq() in the setup call and pass handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is - expected for GPIO driver that irqchip .set_type() callback have to be called - before using/enabling GPIO IRQ. Then set the handler to handle_level_irq() - and/or handle_edge_irq() in the irqchip .set_type() callback depending on - what your controller supports. + expected for GPIO driver that irqchip .set_type() callback will be called + before using/enabling each GPIO IRQ. Then set the handler to + handle_level_irq() and/or handle_edge_irq() in the irqchip .set_type() + callback depending on what your controller supports and what is requested + by the consumer. -It is legal for any IRQ consumer to request an IRQ from any irqchip no matter -if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and -irq_chip are orthogonal, and offering their services independent of each -other. - -gpiod_to_irq() is just a convenience function to figure out the IRQ for a -certain GPIO line and should not be relied upon to have been called before -the IRQ is used. -So always prepare the hardware and make it ready for action in respective -callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having -been called first. +Locking IRQ usage +----------------- -This orthogonality leads to ambiguities that we need to solve: if there is -competition inside the subsystem which side is using the resource (a certain -GPIO line and register for example) it needs to deny certain operations and -keep track of usage inside of the gpiolib subsystem. This is why the API -below exists. +Since GPIO and irq_chip are orthogonal, we can get conflicts between different +use cases. For example a GPIO line used for IRQs should be an input line, +it does not make sense to fire interrupts on an output GPIO. +If there is competition inside the subsystem which side is using the +resource (a certain GPIO line and register for example) it needs to deny +certain operations and keep track of usage inside of the gpiolib subsystem. -Locking IRQ usage ------------------ Input GPIOs can be used as IRQ signals. When this happens, a driver is requested to mark the GPIO as being used as an IRQ:: @@ -380,9 +470,15 @@ assigned. Disabling and enabling IRQs --------------------------- + +In some (fringe) use cases, a driver may be using a GPIO line as input for IRQs, +but occasionally switch that line over to drive output and then back to being +an input with interrupts again. This happens on things like CEC (Consumer +Electronics Control). + When a GPIO is used as an IRQ signal, then gpiolib also needs to know if the IRQ is enabled or disabled. In order to inform gpiolib about this, -a driver should call:: +the irqchip driver should call:: void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset) @@ -398,40 +494,45 @@ irqchip. When using the gpiolib irqchip helpers, these callbacks are automatically assigned. + Real-Time compliance for GPIO IRQ chips --------------------------------------- -Any provider of irqchips needs to be carefully tailored to support Real Time +Any provider of irqchips needs to be carefully tailored to support Real-Time preemption. It is desirable that all irqchips in the GPIO subsystem keep this in mind and do the proper testing to assure they are real time-enabled. -So, pay attention on above " RT_FULL:" notes, please. -The following is a checklist to follow when preparing a driver for real -time-compliance: -- ensure spinlock_t is not used as part irq_chip implementation; -- ensure that sleepable APIs are not used as part irq_chip implementation. +So, pay attention on above realtime considerations in the documentation. + +The following is a checklist to follow when preparing a driver for real-time +compliance: + +- ensure spinlock_t is not used as part irq_chip implementation +- ensure that sleepable APIs are not used as part irq_chip implementation If sleepable APIs have to be used, these can be done from the .irq_bus_lock() - and .irq_bus_unlock() callbacks; + and .irq_bus_unlock() callbacks - Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used - from chained IRQ handler; + from the chained IRQ handler - Generic chained GPIO irqchips: take care about generic_handle_irq() calls and - apply corresponding W/A; -- Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq - handler if possible :) -- regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for - GPIO IRQ chip implementation; -- Test your driver with the appropriate in-kernel real time test cases for both - level and edge IRQs. + apply corresponding work-around +- Chained GPIO irqchips: get rid of the chained IRQ handler and use generic irq + handler if possible +- regmap_mmio: it is possible to disable internal locking in regmap by setting + .disable_locking and handling the locking in the GPIO driver +- Test your driver with the appropriate in-kernel real-time test cases for both + level and edge IRQs + +* [1] http://www.spinics.net/lists/linux-omap/msg120425.html +* [2] https://lkml.org/lkml/2015/9/25/494 +* [3] https://lkml.org/lkml/2015/9/25/495 Requesting self-owned GPIO pins -------------------------------- +=============================== Sometimes it is useful to allow a GPIO chip driver to request its own GPIO -descriptors through the gpiolib API. Using gpio_request() for this purpose -does not help since it pins the module to the kernel forever (it calls -try_module_get()). A GPIO driver can use the following functions instead -to request and free descriptors without being pinned to the kernel forever:: +descriptors through the gpiolib API. A GPIO driver can use the following +functions to request and free descriptors:: struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, u16 hwnum, @@ -446,7 +547,3 @@ gpiochip_free_own_desc(). These functions must be used with care since they do not affect module use count. Do not use the functions to request gpio descriptors not owned by the calling driver. - -* [1] http://www.spinics.net/lists/linux-omap/msg120425.html -* [2] https://lkml.org/lkml/2015/9/25/494 -* [3] https://lkml.org/lkml/2015/9/25/495 diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index aa87075c7846..d26308af6036 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -57,6 +57,7 @@ available subsections can be seen below. soundwire/index fpga/index acpi/index + generic-counter .. only:: subproject and html diff --git a/Documentation/driver-api/pm/cpuidle.rst b/Documentation/driver-api/pm/cpuidle.rst index 5842ab621a58..006cf6db40c6 100644 --- a/Documentation/driver-api/pm/cpuidle.rst +++ b/Documentation/driver-api/pm/cpuidle.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + .. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>` .. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>` .. |struct cpuidle_driver| replace:: :c:type:`struct cpuidle_driver <cpuidle_driver>` @@ -7,9 +10,9 @@ CPU Idle Time Management ======================== -:: +:Copyright: |copy| 2019 Intel Corporation - Copyright (c) 2019 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> CPU Idle Time Management Subsystem diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 090c151aa86b..30835683616a 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + .. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>` .. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>` .. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>` @@ -12,11 +15,12 @@ Device Power Management Basics ============================== -:: +:Copyright: |copy| 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +:Copyright: |copy| 2010 Alan Stern <stern@rowland.harvard.edu> +:Copyright: |copy| 2016 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> - Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. - Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu> - Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> Most of the code in Linux is device drivers, so most of the Linux power management (PM) code is also driver-specific. Most drivers will do very diff --git a/Documentation/driver-api/pm/index.rst b/Documentation/driver-api/pm/index.rst index 56975c6bc789..c2a9ef8d115c 100644 --- a/Documentation/driver-api/pm/index.rst +++ b/Documentation/driver-api/pm/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =============================== CPU and Device Power Management =============================== diff --git a/Documentation/driver-api/pm/notifiers.rst b/Documentation/driver-api/pm/notifiers.rst index 62f860026992..186435c43b77 100644 --- a/Documentation/driver-api/pm/notifiers.rst +++ b/Documentation/driver-api/pm/notifiers.rst @@ -1,10 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + ============================= Suspend/Hibernation Notifiers ============================= -:: +:Copyright: |copy| 2016 Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> - Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> There are some operations that subsystems or drivers may want to carry out before hibernation/suspend or after restore/resume, but they require the system diff --git a/Documentation/driver-api/pm/types.rst b/Documentation/driver-api/pm/types.rst index 3ebdecc54104..73a231caf764 100644 --- a/Documentation/driver-api/pm/types.rst +++ b/Documentation/driver-api/pm/types.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================================== Device Power Management Data Types ================================== diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst index 26a6064503fd..5351bd2f34a8 100644 --- a/Documentation/driver-api/soundwire/stream.rst +++ b/Documentation/driver-api/soundwire/stream.rst @@ -201,7 +201,7 @@ Bus implements below API for allocate a stream which needs to be called once per stream. From ASoC DPCM framework, this stream state maybe linked to .startup() operation. - .. code-block:: c +.. code-block:: c int sdw_alloc_stream(char * stream_name); @@ -228,7 +228,7 @@ the respective Master(s) and Slave(s) associated with stream. These APIs can only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM framework, this stream state is linked to .hw_params() operation. - .. code-block:: c +.. code-block:: c int sdw_stream_add_master(struct sdw_bus * bus, struct sdw_stream_config * stream_config, @@ -274,7 +274,7 @@ Bus implements below API for PREPARE state which needs to be called once per stream. From ASoC DPCM framework, this stream state is linked to .prepare() operation. - .. code-block:: c +.. code-block:: c int sdw_prepare_stream(struct sdw_stream_runtime * stream); @@ -304,7 +304,7 @@ Bus implements below API for ENABLE state which needs to be called once per stream. From ASoC DPCM framework, this stream state is linked to .trigger() start operation. - .. code-block:: c +.. code-block:: c int sdw_enable_stream(struct sdw_stream_runtime * stream); @@ -332,7 +332,7 @@ Bus implements below API for DISABLED state which needs to be called once per stream. From ASoC DPCM framework, this stream state is linked to .trigger() stop operation. - .. code-block:: c +.. code-block:: c int sdw_disable_stream(struct sdw_stream_runtime * stream); @@ -357,7 +357,7 @@ Bus implements below API for DEPREPARED state which needs to be called once per stream. From ASoC DPCM framework, this stream state is linked to .trigger() stop operation. - .. code-block:: c +.. code-block:: c int sdw_deprepare_stream(struct sdw_stream_runtime * stream); @@ -382,7 +382,7 @@ Bus implements below APIs for RELEASE state which needs to be called by all the Master(s) and Slave(s) associated with stream. From ASoC DPCM framework, this stream state is linked to .hw_free() operation. - .. code-block:: c +.. code-block:: c int sdw_stream_remove_master(struct sdw_bus * bus, struct sdw_stream_runtime * stream); @@ -395,7 +395,7 @@ stream assigned as part of ALLOCATED state. In .shutdown() the data structure maintaining stream state are freed up. - .. code-block:: c +.. code-block:: c void sdw_release_stream(struct sdw_stream_runtime * stream); diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index d7d6f01e81ff..99994a461359 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -256,6 +256,9 @@ DMA dmam_pool_create() dmam_pool_destroy() +DRM + devm_drm_dev_init() + GPIO devm_gpiod_get() devm_gpiod_get_index() diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 3e6b8f07d5d0..38c40cfa0578 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -21,7 +21,7 @@ | nds32: | TODO | | nios2: | ok | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | TODO | | s390: | TODO | diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index f4e45bd58fea..e68239b5d2f0 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -21,7 +21,7 @@ | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | ok | | s390: | ok | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index 1d5651ef11f8..f17131b328e5 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -21,7 +21,7 @@ | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | TODO | | s390: | ok | diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index efea228ccd8a..dac435575384 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -52,7 +52,7 @@ prototypes: int (*rename) (struct inode *, struct dentry *, struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); - const char *(*get_link) (struct dentry *, struct inode *, void **); + const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); void (*truncate) (struct inode *); int (*permission) (struct inode *, int, unsigned int); int (*get_acl)(struct inode *, int); @@ -118,6 +118,7 @@ set: exclusive --------------------------- super_operations --------------------------- prototypes: struct inode *(*alloc_inode)(struct super_block *sb); + void (*free_inode)(struct inode *); void (*destroy_inode)(struct inode *); void (*dirty_inode) (struct inode *, int flags); int (*write_inode) (struct inode *, struct writeback_control *wbc); @@ -139,6 +140,7 @@ locking rules: All may block [not true, see below] s_umount alloc_inode: +free_inode: called from RCU callback destroy_inode: dirty_inode: write_inode: diff --git a/Documentation/filesystems/autofs-mount-control.txt b/Documentation/filesystems/autofs-mount-control.txt index 45edad6933cc..acc02fc57993 100644 --- a/Documentation/filesystems/autofs-mount-control.txt +++ b/Documentation/filesystems/autofs-mount-control.txt @@ -354,8 +354,10 @@ this ioctl is called until no further expire candidates are found. The call requires an initialized struct autofs_dev_ioctl with the ioctlfd field set to the descriptor obtained from the open call. In -addition an immediate expire, independent of the mount timeout, can be -requested by setting the how field of struct args_expire to 1. If no +addition an immediate expire that's independent of the mount timeout, +and a forced expire that's independent of whether the mount is busy, +can be requested by setting the how field of struct args_expire to +AUTOFS_EXP_IMMEDIATE or AUTOFS_EXP_FORCED, respectively . If no expire candidates can be found the ioctl returns -1 with errno set to EAGAIN. diff --git a/Documentation/filesystems/autofs.txt b/Documentation/filesystems/autofs.txt index 373ad25852d3..3af38c7fd26d 100644 --- a/Documentation/filesystems/autofs.txt +++ b/Documentation/filesystems/autofs.txt @@ -116,7 +116,7 @@ that purpose there is another flag. **DCACHE_MANAGE_TRANSIT** If a dentry has DCACHE_MANAGE_TRANSIT set then two very different but -related behaviors are invoked, both using the `d_op->d_manage()` +related behaviours are invoked, both using the `d_op->d_manage()` dentry operation. Firstly, before checking to see if any filesystem is mounted on the @@ -193,8 +193,8 @@ VFS remain in RCU-walk mode, but can only tell it to get out of RCU-walk mode by returning `-ECHILD`. So `d_manage()`, when called with `rcu_walk` set, should either return --ECHILD if there is any reason to believe it is unsafe to end the -mounted filesystem, and otherwise should return 0. +-ECHILD if there is any reason to believe it is unsafe to enter the +mounted filesystem, otherwise it should return 0. autofs will return `-ECHILD` if an expiry of the filesystem has been initiated or is being considered, otherwise it returns 0. @@ -210,7 +210,7 @@ mounts that were created by `d_automount()` returning a filesystem to be mounted. As autofs doesn't return such a filesystem but leaves the mounting to the automount daemon, it must involve the automount daemon in unmounting as well. This also means that autofs has more control -of expiry. +over expiry. The VFS also supports "expiry" of mounts using the MNT_EXPIRE flag to the `umount` system call. Unmounting with MNT_EXPIRE will fail unless @@ -225,7 +225,7 @@ unmount any filesystems mounted on the autofs filesystem or remove any symbolic links or empty directories any time it likes. If the unmount or removal is successful the filesystem will be returned to the state it was before the mount or creation, so that any access of the name -will trigger normal auto-mount processing. In particlar, `rmdir` and +will trigger normal auto-mount processing. In particular, `rmdir` and `unlink` do not leave negative entries in the dcache as a normal filesystem would, so an attempt to access a recently-removed object is passed to autofs for handling. @@ -240,11 +240,18 @@ Normally the daemon only wants to remove entries which haven't been used for a while. For this purpose autofs maintains a "`last_used`" time stamp on each directory or symlink. For symlinks it genuinely does record the last time the symlink was "used" or followed to find -out where it points to. For directories the field is a slight -misnomer. It actually records the last time that autofs checked if -the directory or one of its descendents was busy and found that it -was. This is just as useful and doesn't require updating the field so -often. +out where it points to. For directories the field is used slightly +differently. The field is updated at mount time and during expire +checks if it is found to be in use (ie. open file descriptor or +process working directory) and during path walks. The update done +during path walks prevents frequent expire and immediate mount of +frequently accessed automounts. But in the case where a GUI continually +access or an application frequently scans an autofs directory tree +there can be an accumulation of mounts that aren't actually being +used. To cater for this case the "`strictexpire`" autofs mount option +can be used to avoid the "`last_used`" update on path walk thereby +preventing this apparent inability to expire mounts that aren't +really in use. The daemon is able to ask autofs if anything is due to be expired, using an `ioctl` as discussed later. For a *direct* mount, autofs @@ -255,8 +262,12 @@ up. There is an option with indirect mounts to consider each of the leaves that has been mounted on instead of considering the top-level names. -This is intended for compatability with version 4 of autofs and should -be considered as deprecated. +This was originally intended for compatibility with version 4 of autofs +and should be considered as deprecated for Sun Format automount maps. +However, it may be used again for amd format mount maps (which are +generally indirect maps) because the amd automounter allows for the +setting of an expire timeout for individual mounts. But there are +some difficulties in making the needed changes for this. When autofs considers a directory it checks the `last_used` time and compares it with the "timeout" value set when the filesystem was @@ -273,7 +284,7 @@ mounts. If it finds something in the root directory to expire it will return the name of that thing. Once a name has been returned the automount daemon needs to unmount any filesystems mounted below the name normally. As described above, this is unsafe for non-toplevel -mounts in a version-5 autofs. For this reason the current `automountd` +mounts in a version-5 autofs. For this reason the current `automount(8)` does not use this ioctl. The second mechanism uses either the **AUTOFS_DEV_IOCTL_EXPIRE_CMD** or @@ -345,7 +356,7 @@ The `wait_queue_token` is a unique number which can identify a particular request to be acknowledged. When a message is sent over the pipe the affected dentry is marked as either "active" or "expiring" and other accesses to it block until the message is -acknowledged using one of the ioctls below and the relevant +acknowledged using one of the ioctls below with the relevant `wait_queue_token`. Communicating with autofs: root directory ioctls @@ -367,15 +378,14 @@ The available ioctl commands are: This mode is also entered if a write to the pipe fails. - **AUTOFS_IOC_PROTOVER**: This returns the protocol version in use. - **AUTOFS_IOC_PROTOSUBVER**: Returns the protocol sub-version which - is really a version number for the implementation. It is - currently 2. + is really a version number for the implementation. - **AUTOFS_IOC_SETTIMEOUT**: This passes a pointer to an unsigned long. The value is used to set the timeout for expiry, and the current timeout value is stored back through the pointer. - **AUTOFS_IOC_ASKUMOUNT**: Returns, in the pointed-to `int`, 1 if the filesystem could be unmounted. This is only a hint as the situation could change at any instant. This call can be - use to avoid a more expensive full unmount attempt. + used to avoid a more expensive full unmount attempt. - **AUTOFS_IOC_EXPIRE**: as described above, this asks if there is anything suitable to expire. A pointer to a packet: @@ -400,6 +410,11 @@ The available ioctl commands are: **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored and objects are expired if the are not in use. + **AUTOFS_EXP_FORCED** causes the in use status to be ignored + and objects are expired ieven if they are in use. This assumes + that the daemon has requested this because it is capable of + performing the umount. + **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level name to expire. This is only safe when *maxproto* is 4. @@ -415,7 +430,7 @@ which can be used to communicate directly with the autofs filesystem. It requires CAP_SYS_ADMIN for access. The `ioctl`s that can be used on this device are described in a separate -document `autofs-mount-control.txt`, and are summarized briefly here. +document `autofs-mount-control.txt`, and are summarised briefly here. Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure: struct autofs_dev_ioctl { @@ -511,6 +526,21 @@ directories. Catatonic mode can only be left via the **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`. +The "ignore" mount option +------------------------- + +The "ignore" mount option can be used to provide a generic indicator +to applications that the mount entry should be ignored when displaying +mount information. + +In other OSes that provide autofs and that provide a mount list to user +space based on the kernel mount list a no-op mount option ("ignore" is +the one use on the most common OSes) is allowed so that autofs file +system users can optionally use it. + +This is intended to be used by user space programs to exclude autofs +mounts from consideration when reading the mounts list. + autofs, name spaces, and shared mounts -------------------------------------- diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 4f45f71149cb..4a0a9c3f4af6 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -31,10 +31,10 @@ This call, if successful, will make a directory called name underneath the indicated parent directory. If parent is NULL, the directory will be created in the debugfs root. On success, the return value is a struct dentry pointer which can be used to create files in the directory (and to -clean it up at the end). A NULL return value indicates that something went -wrong. If ERR_PTR(-ENODEV) is returned, that is an indication that the -kernel has been built without debugfs support and none of the functions -described below will work. +clean it up at the end). An ERR_PTR(-ERROR) return value indicates that +something went wrong. If ERR_PTR(-ENODEV) is returned, that is an +indication that the kernel has been built without debugfs support and none +of the functions described below will work. The most general way to create a file within a debugfs directory is with: @@ -48,8 +48,9 @@ should hold the file, data will be stored in the i_private field of the resulting inode structure, and fops is a set of file operations which implement the file's behavior. At a minimum, the read() and/or write() operations should be provided; others can be included as needed. Again, -the return value will be a dentry pointer to the created file, NULL for -error, or ERR_PTR(-ENODEV) if debugfs support is missing. +the return value will be a dentry pointer to the created file, +ERR_PTR(-ERROR) on error, or ERR_PTR(-ENODEV) if debugfs support is +missing. Create a file with an initial size, the following function can be used instead: @@ -214,7 +215,8 @@ can be removed with: void debugfs_remove(struct dentry *dentry); -The dentry value can be NULL, in which case nothing will be removed. +The dentry value can be NULL or an error value, in which case nothing will +be removed. Once upon a time, debugfs users were required to remember the dentry pointer for every debugfs file they created so that all files could be diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index cf43bc4dbf31..3bd1148d8bb6 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -638,3 +638,38 @@ in your dentry operations instead. inode to d_splice_alias() will also do the right thing (equivalent of d_add(dentry, NULL); return NULL;), so that kind of special cases also doesn't need a separate treatment. +-- +[strongly recommended] + take the RCU-delayed parts of ->destroy_inode() into a new method - + ->free_inode(). If ->destroy_inode() becomes empty - all the better, + just get rid of it. Synchronous work (e.g. the stuff that can't + be done from an RCU callback, or any WARN_ON() where we want the + stack trace) *might* be movable to ->evict_inode(); however, + that goes only for the things that are not needed to balance something + done by ->alloc_inode(). IOW, if it's cleaning up the stuff that + might have accumulated over the life of in-core inode, ->evict_inode() + might be a fit. + + Rules for inode destruction: + * if ->destroy_inode() is non-NULL, it gets called + * if ->free_inode() is non-NULL, it gets scheduled by call_rcu() + * combination of NULL ->destroy_inode and NULL ->free_inode is + treated as NULL/free_inode_nonrcu, to preserve the compatibility. + + Note that the callback (be it via ->free_inode() or explicit call_rcu() + in ->destroy_inode()) is *NOT* ordered wrt superblock destruction; + as the matter of fact, the superblock and all associated structures + might be already gone. The filesystem driver is guaranteed to be still + there, but that's it. Freeing memory in the callback is fine; doing + more than that is possible, but requires a lot of care and is best + avoided. +-- +[mandatory] + DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the + default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any + business doing so. +-- +[mandatory] + d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are + very suspect (and won't work in modules). Such uses are very likely to + be misspelled d_alloc_anon(). diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 761c6fd24a53..57fc576b1f3e 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -3,8 +3,6 @@ Original author: Richard Gooch <rgooch@atnf.csiro.au> - Last updated on June 24, 2007. - Copyright (C) 1999 Richard Gooch Copyright (C) 2005 Pekka Enberg @@ -465,6 +463,12 @@ otherwise noted. argument. If request can't be handled without leaving RCU mode, have it return ERR_PTR(-ECHILD). + If the filesystem stores the symlink target in ->i_link, the + VFS may use it directly without calling ->get_link(); however, + ->get_link() must still be provided. ->i_link must not be + freed until after an RCU grace period. Writing to ->i_link + post-iget() time requires a 'release' memory barrier. + readlink: this is now just an override for use by readlink(2) for the cases when ->get_link uses nd_jump_link() or object is not in fact a symlink. Normally filesystems should only implement diff --git a/Documentation/gpio/index.rst b/Documentation/gpio/index.rst new file mode 100644 index 000000000000..09a4a553f434 --- /dev/null +++ b/Documentation/gpio/index.rst @@ -0,0 +1,17 @@ +:orphan: + +==== +gpio +==== + +.. toctree:: + :maxdepth: 1 + + sysfs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.rst index 58eeab81f349..ec09ffd983e7 100644 --- a/Documentation/gpio/sysfs.txt +++ b/Documentation/gpio/sysfs.rst @@ -1,10 +1,12 @@ GPIO Sysfs Interface for Userspace ================================== -THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO -Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS -ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL -NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. +.. warning:: + + THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO + Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS + ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL + NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. Refer to the examples in tools/gpio/* for an introduction to the new character device ABI. Also see the userspace header in @@ -51,13 +53,15 @@ The control interfaces are write-only: /sys/class/gpio/ - "export" ... Userspace may ask the kernel to export control of + "export" ... + Userspace may ask the kernel to export control of a GPIO to userspace by writing its number to this file. Example: "echo 19 > export" will create a "gpio19" node for GPIO #19, if that's not requested by kernel code. - "unexport" ... Reverses the effect of exporting to userspace. + "unexport" ... + Reverses the effect of exporting to userspace. Example: "echo 19 > unexport" will remove a "gpio19" node exported using the "export" file. @@ -67,7 +71,8 @@ and have the following read/write attributes: /sys/class/gpio/gpioN/ - "direction" ... reads as either "in" or "out". This value may + "direction" ... + reads as either "in" or "out". This value may normally be written. Writing as "out" defaults to initializing the value as low. To ensure glitch free operation, values "low" and "high" may be written to @@ -78,7 +83,8 @@ and have the following read/write attributes: it was exported by kernel code that didn't explicitly allow userspace to reconfigure this GPIO's direction. - "value" ... reads as either 0 (low) or 1 (high). If the GPIO + "value" ... + reads as either 0 (low) or 1 (high). If the GPIO is configured as an output, this value may be written; any nonzero value is treated as high. @@ -92,14 +98,16 @@ and have the following read/write attributes: file and read the new value or close the file and re-open it to read the value. - "edge" ... reads as either "none", "rising", "falling", or + "edge" ... + reads as either "none", "rising", "falling", or "both". Write these strings to select the signal edge(s) that will make poll(2) on the "value" file return. This file exists only if the pin can be configured as an interrupt generating input pin. - "active_low" ... reads as either 0 (false) or 1 (true). Write + "active_low" ... + reads as either 0 (false) or 1 (true). Write any nonzero value to invert the value attribute both for reading and writing. Existing and subsequent poll(2) support configuration via the edge attribute @@ -112,11 +120,14 @@ read-only attributes: /sys/class/gpio/gpiochipN/ - "base" ... same as N, the first GPIO managed by this chip + "base" ... + same as N, the first GPIO managed by this chip - "label" ... provided for diagnostics (not always unique) + "label" ... + provided for diagnostics (not always unique) - "ngpio" ... how many GPIOs this manages (N to N + ngpio - 1) + "ngpio" ... + how many GPIOs this manages (N to N + ngpio - 1) Board documentation should in most cases cover what GPIOs are used for what purposes. However, those numbers are not always stable; GPIOs on @@ -129,7 +140,7 @@ the correct GPIO number to use for a given signal. Exporting from Kernel code -------------------------- Kernel code can explicitly manage exports of GPIOs which have already been -requested using gpio_request(): +requested using gpio_request():: /* export the GPIO to userspace */ int gpiod_export(struct gpio_desc *desc, bool direction_may_change); diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 3ae23a5454ac..966bd2d9f0cc 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -93,6 +93,11 @@ Device Instance and Driver Handling Driver Load ----------- +Component Helper Usage +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/drm_drv.c + :doc: component helper usage recommendations IRQ Helper Library ~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 17ca7f8bf3d3..14102ae035dc 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -107,6 +107,12 @@ fbdev Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c :export: +format Helper Functions Reference +================================= + +.. kernel-doc:: drivers/gpu/drm/drm_format_helper.c + :export: + Framebuffer CMA Helper Functions Reference ========================================== @@ -369,3 +375,15 @@ Legacy CRTC/Modeset Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c :export: + +SHMEM GEM Helper Reference +========================== + +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_shmem_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c + :export: diff --git a/Documentation/gpu/kms-properties.csv b/Documentation/gpu/kms-properties.csv index bfde04eddd14..07ed22ea3bd6 100644 --- a/Documentation/gpu/kms-properties.csv +++ b/Documentation/gpu/kms-properties.csv @@ -17,7 +17,6 @@ Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,De ,Virtual GPU,“suggested X”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an X offset for a connector ,,“suggested Y”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an Y offset for a connector ,Optional,"""aspect ratio""",ENUM,"{ ""None"", ""4:3"", ""16:9"" }",Connector,TDB -,Optional,"""content type""",ENUM,"{ ""No Data"", ""Graphics"", ""Photo"", ""Cinema"", ""Game"" }",Connector,TBD i915,Generic,"""Broadcast RGB""",ENUM,"{ ""Automatic"", ""Full"", ""Limited 16:235"" }",Connector,"When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255." ,,“audio”,ENUM,"{ ""force-dvi"", ""off"", ""auto"", ""on"" }",Connector,TBD ,SDVO-TV,“mode”,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B"" } etc.",Connector,TBD diff --git a/Documentation/gpu/meson.rst b/Documentation/gpu/meson.rst index 479f6f51a13b..b9e2f9aa3bd8 100644 --- a/Documentation/gpu/meson.rst +++ b/Documentation/gpu/meson.rst @@ -42,12 +42,6 @@ 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 ============ diff --git a/Documentation/gpu/tinydrm.rst b/Documentation/gpu/tinydrm.rst index a913644bfc19..33a41544f659 100644 --- a/Documentation/gpu/tinydrm.rst +++ b/Documentation/gpu/tinydrm.rst @@ -1,34 +1,22 @@ -========================== -drm/tinydrm Driver library -========================== +============================ +drm/tinydrm Tiny DRM drivers +============================ -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c - :doc: overview - -Core functionality -================== +tinydrm is a collection of DRM drivers that are so small they can fit in a +single source file. -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c - :doc: core +Helpers +======= -.. kernel-doc:: include/drm/tinydrm/tinydrm.h +.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h :internal: -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c +.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c :export: .. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-pipe.c :export: -Additional helpers -================== - -.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c - :export: - MIPI DBI Compatible Controllers =============================== diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 159a4aba49e6..1528ad2d598b 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -215,12 +215,12 @@ Might be good to also have some igt testcases for this. Contact: Daniel Vetter, Noralf Tronnes -Put a reservation_object into drm_gem_object +Remove the ->gem_prime_res_obj callback -------------------------------------------- -This would remove the need for the ->gem_prime_res_obj callback. It would also -allow us to implement generic helpers for waiting for a bo, allowing for quite a -bit of refactoring in the various wait ioctl implementations. +The ->gem_prime_res_obj callback can be removed from drivers by using the +reservation_object in the drm_gem_object. It may also be possible to use the +generic drm_gem_reservation_object_wait helper for waiting for a bo. Contact: Daniel Vetter @@ -469,10 +469,6 @@ those drivers as simple as possible, so lots of room for refactoring: one of the ideas for having a shared dsi/dbi helper, abstracting away the transport details more. -- 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 :-) - Contact: Noralf Trønnes, Daniel Vetter AMD DC Display Driver diff --git a/Documentation/hwmon/ab8500 b/Documentation/hwmon/ab8500.rst index cf169c8ef4e3..33f93a9cec04 100644 --- a/Documentation/hwmon/ab8500 +++ b/Documentation/hwmon/ab8500.rst @@ -2,19 +2,23 @@ Kernel driver ab8500 ==================== Supported chips: + * ST-Ericsson AB8500 + Prefix: 'ab8500' + Addresses scanned: - + Datasheet: http://www.stericsson.com/developers/documentation.jsp Authors: - Martin Persson <martin.persson@stericsson.com> - Hongbo Zhang <hongbo.zhang@linaro.org> + - Martin Persson <martin.persson@stericsson.com> + - Hongbo Zhang <hongbo.zhang@linaro.org> Description ----------- -See also Documentation/hwmon/abx500. This is the ST-Ericsson AB8500 specific +See also Documentation/hwmon/abx500.rst. This is the ST-Ericsson AB8500 specific driver. Currently only the AB8500 internal sensor and one external sensor for battery diff --git a/Documentation/hwmon/abituguru b/Documentation/hwmon/abituguru deleted file mode 100644 index 44013d23b3f0..000000000000 --- a/Documentation/hwmon/abituguru +++ /dev/null @@ -1,92 +0,0 @@ -Kernel driver abituguru -======================= - -Supported chips: - * Abit uGuru revision 1 & 2 (Hardware Monitor part only) - Prefix: 'abituguru' - Addresses scanned: ISA 0x0E0 - Datasheet: Not available, this driver is based on reverse engineering. - A "Datasheet" has been written based on the reverse engineering it - should be available in the same dir as this file under the name - abituguru-datasheet. - Note: - The uGuru is a microcontroller with onboard firmware which programs - it to behave as a hwmon IC. There are many different revisions of the - firmware and thus effectivly many different revisions of the uGuru. - Below is an incomplete list with which revisions are used for which - Motherboards: - uGuru 1.00 ~ 1.24 (AI7, KV8-MAX3, AN7) (1) - uGuru 2.0.0.0 ~ 2.0.4.2 (KV8-PRO) - uGuru 2.1.0.0 ~ 2.1.2.8 (AS8, AV8, AA8, AG8, AA8XE, AX8) - uGuru 2.2.0.0 ~ 2.2.0.6 (AA8 Fatal1ty) - uGuru 2.3.0.0 ~ 2.3.0.9 (AN8) - uGuru 3.0.0.0 ~ 3.0.x.x (AW8, AL8, AT8, NI8 SLI, AT8 32X, AN8 32X, - AW9D-MAX) (2) - 1) For revisions 2 and 3 uGuru's the driver can autodetect the - sensortype (Volt or Temp) for bank1 sensors, for revision 1 uGuru's - this does not always work. For these uGuru's the autodetection can - be overridden with the bank1_types module param. For all 3 known - revison 1 motherboards the correct use of this param is: - bank1_types=1,1,0,0,0,0,0,2,0,0,0,0,2,0,0,1 - You may also need to specify the fan_sensors option for these boards - fan_sensors=5 - 2) There is a separate abituguru3 driver for these motherboards, - the abituguru (without the 3 !) driver will not work on these - motherboards (and visa versa)! - -Authors: - Hans de Goede <j.w.r.degoede@hhs.nl>, - (Initial reverse engineering done by Olle Sandberg - <ollebull@gmail.com>) - - -Module Parameters ------------------ - -* force: bool Force detection. Note this parameter only causes the - detection to be skipped, and thus the insmod to - succeed. If the uGuru can't be read the actual hwmon - driver will not load and thus no hwmon device will get - registered. -* bank1_types: int[] Bank1 sensortype autodetection override: - -1 autodetect (default) - 0 volt sensor - 1 temp sensor - 2 not connected -* fan_sensors: int Tell the driver how many fan speed sensors there are - on your motherboard. Default: 0 (autodetect). -* pwms: int Tell the driver how many fan speed controls (fan - pwms) your motherboard has. Default: 0 (autodetect). -* verbose: int How verbose should the driver be? (0-3): - 0 normal output - 1 + verbose error reporting - 2 + sensors type probing info (default) - 3 + retryable error reporting - Default: 2 (the driver is still in the testing phase) - -Notice if you need any of the first three options above please insmod the -driver with verbose set to 3 and mail me <j.w.r.degoede@hhs.nl> the output of: -dmesg | grep abituguru - - -Description ------------ - -This driver supports the hardware monitoring features of the first and -second revision of the Abit uGuru chip found on Abit uGuru featuring -motherboards (most modern Abit motherboards). - -The first and second revision of the uGuru chip in reality is a Winbond -W83L950D in disguise (despite Abit claiming it is "a new microprocessor -designed by the ABIT Engineers"). Unfortunately this doesn't help since the -W83L950D is a generic microcontroller with a custom Abit application running -on it. - -Despite Abit not releasing any information regarding the uGuru, Olle -Sandberg <ollebull@gmail.com> has managed to reverse engineer the sensor part -of the uGuru. Without his work this driver would not have been possible. - -Known Issues ------------- - -The voltage and frequency control parts of the Abit uGuru are not supported. diff --git a/Documentation/hwmon/abituguru-datasheet b/Documentation/hwmon/abituguru-datasheet.rst index 86c0b1251c81..6d5253e2223b 100644 --- a/Documentation/hwmon/abituguru-datasheet +++ b/Documentation/hwmon/abituguru-datasheet.rst @@ -1,3 +1,4 @@ +=============== uGuru datasheet =============== @@ -168,34 +169,35 @@ This bank contains 0 sensors, iow the sensor address is ignored (but must be written) just use 0. Bank 0x20 contains 3 bytes: Byte 0: -This byte holds the alarm flags for sensor 0-7 of Sensor Bank1, with bit 0 -corresponding to sensor 0, 1 to 1, etc. + This byte holds the alarm flags for sensor 0-7 of Sensor Bank1, with bit 0 + corresponding to sensor 0, 1 to 1, etc. Byte 1: -This byte holds the alarm flags for sensor 8-15 of Sensor Bank1, with bit 0 -corresponding to sensor 8, 1 to 9, etc. + This byte holds the alarm flags for sensor 8-15 of Sensor Bank1, with bit 0 + corresponding to sensor 8, 1 to 9, etc. Byte 2: -This byte holds the alarm flags for sensor 0-5 of Sensor Bank2, with bit 0 -corresponding to sensor 0, 1 to 1, etc. + This byte holds the alarm flags for sensor 0-5 of Sensor Bank2, with bit 0 + corresponding to sensor 0, 1 to 1, etc. Bank 0x21 Sensor Bank1 Values / Readings (R) -------------------------------------------- This bank contains 16 sensors, for each sensor it contains 1 byte. So far the following sensors are known to be available on all motherboards: -Sensor 0 CPU temp -Sensor 1 SYS temp -Sensor 3 CPU core volt -Sensor 4 DDR volt -Sensor 10 DDR Vtt volt -Sensor 15 PWM temp + +- Sensor 0 CPU temp +- Sensor 1 SYS temp +- Sensor 3 CPU core volt +- Sensor 4 DDR volt +- Sensor 10 DDR Vtt volt +- Sensor 15 PWM temp Byte 0: -This byte holds the reading from the sensor. Sensors in Bank1 can be both -volt and temp sensors, this is motherboard specific. The uGuru however does -seem to know (be programmed with) what kindoff sensor is attached see Sensor -Bank1 Settings description. + This byte holds the reading from the sensor. Sensors in Bank1 can be both + volt and temp sensors, this is motherboard specific. The uGuru however does + seem to know (be programmed with) what kindoff sensor is attached see Sensor + Bank1 Settings description. Volt sensors use a linear scale, a reading 0 corresponds with 0 volt and a reading of 255 with 3494 mV. The sensors for higher voltages however are @@ -207,96 +209,118 @@ Temp sensors also use a linear scale, a reading of 0 corresponds with 0 degree Celsius and a reading of 255 with a reading of 255 degrees Celsius. -Bank 0x22 Sensor Bank1 Settings (R) -Bank 0x23 Sensor Bank1 Settings (W) ------------------------------------ +Bank 0x22 Sensor Bank1 Settings (R) and Bank 0x23 Sensor Bank1 Settings (W) +--------------------------------------------------------------------------- -This bank contains 16 sensors, for each sensor it contains 3 bytes. Each +Those banks contain 16 sensors, for each sensor it contains 3 bytes. Each set of 3 bytes contains the settings for the sensor with the same sensor address in Bank 0x21 . Byte 0: -Alarm behaviour for the selected sensor. A 1 enables the described behaviour. -Bit 0: Give an alarm if measured temp is over the warning threshold (RW) * -Bit 1: Give an alarm if measured volt is over the max threshold (RW) ** -Bit 2: Give an alarm if measured volt is under the min threshold (RW) ** -Bit 3: Beep if alarm (RW) -Bit 4: 1 if alarm cause measured temp is over the warning threshold (R) -Bit 5: 1 if alarm cause measured volt is over the max threshold (R) -Bit 6: 1 if alarm cause measured volt is under the min threshold (R) -Bit 7: Volt sensor: Shutdown if alarm persist for more than 4 seconds (RW) - Temp sensor: Shutdown if temp is over the shutdown threshold (RW) - -* This bit is only honored/used by the uGuru if a temp sensor is connected -** This bit is only honored/used by the uGuru if a volt sensor is connected -Note with some trickery this can be used to find out what kinda sensor is -detected see the Linux kernel driver for an example with many comments on -how todo this. + Alarm behaviour for the selected sensor. A 1 enables the described + behaviour. + +Bit 0: + Give an alarm if measured temp is over the warning threshold (RW) [1]_ + +Bit 1: + Give an alarm if measured volt is over the max threshold (RW) [2]_ + +Bit 2: + Give an alarm if measured volt is under the min threshold (RW) [2]_ + +Bit 3: + Beep if alarm (RW) + +Bit 4: + 1 if alarm cause measured temp is over the warning threshold (R) + +Bit 5: + 1 if alarm cause measured volt is over the max threshold (R) + +Bit 6: + 1 if alarm cause measured volt is under the min threshold (R) + +Bit 7: + - Volt sensor: Shutdown if alarm persist for more than 4 seconds (RW) + - Temp sensor: Shutdown if temp is over the shutdown threshold (RW) + +.. [1] This bit is only honored/used by the uGuru if a temp sensor is connected + +.. [2] This bit is only honored/used by the uGuru if a volt sensor is connected + Note with some trickery this can be used to find out what kinda sensor + is detected see the Linux kernel driver for an example with many + comments on how todo this. Byte 1: -Temp sensor: warning threshold (scale as bank 0x21) -Volt sensor: min threshold (scale as bank 0x21) + - Temp sensor: warning threshold (scale as bank 0x21) + - Volt sensor: min threshold (scale as bank 0x21) Byte 2: -Temp sensor: shutdown threshold (scale as bank 0x21) -Volt sensor: max threshold (scale as bank 0x21) + - Temp sensor: shutdown threshold (scale as bank 0x21) + - Volt sensor: max threshold (scale as bank 0x21) -Bank 0x24 PWM outputs for FAN's (R) -Bank 0x25 PWM outputs for FAN's (W) ------------------------------------ +Bank 0x24 PWM outputs for FAN's (R) and Bank 0x25 PWM outputs for FAN's (W) +--------------------------------------------------------------------------- -This bank contains 3 "sensors", for each sensor it contains 5 bytes. -Sensor 0 usually controls the CPU fan -Sensor 1 usually controls the NB (or chipset for single chip) fan -Sensor 2 usually controls the System fan +Those banks contain 3 "sensors", for each sensor it contains 5 bytes. + - Sensor 0 usually controls the CPU fan + - Sensor 1 usually controls the NB (or chipset for single chip) fan + - Sensor 2 usually controls the System fan Byte 0: -Flag 0x80 to enable control, Fan runs at 100% when disabled. -low nibble (temp)sensor address at bank 0x21 used for control. + Flag 0x80 to enable control, Fan runs at 100% when disabled. + low nibble (temp)sensor address at bank 0x21 used for control. Byte 1: -0-255 = 0-12v (linear), specify voltage at which fan will rotate when under -low threshold temp (specified in byte 3) + 0-255 = 0-12v (linear), specify voltage at which fan will rotate when under + low threshold temp (specified in byte 3) Byte 2: -0-255 = 0-12v (linear), specify voltage at which fan will rotate when above -high threshold temp (specified in byte 4) + 0-255 = 0-12v (linear), specify voltage at which fan will rotate when above + high threshold temp (specified in byte 4) Byte 3: -Low threshold temp (scale as bank 0x21) + Low threshold temp (scale as bank 0x21) byte 4: -High threshold temp (scale as bank 0x21) + High threshold temp (scale as bank 0x21) Bank 0x26 Sensors Bank2 Values / Readings (R) --------------------------------------------- This bank contains 6 sensors (AFAIK), for each sensor it contains 1 byte. + So far the following sensors are known to be available on all motherboards: -Sensor 0: CPU fan speed -Sensor 1: NB (or chipset for single chip) fan speed -Sensor 2: SYS fan speed + - Sensor 0: CPU fan speed + - Sensor 1: NB (or chipset for single chip) fan speed + - Sensor 2: SYS fan speed Byte 0: -This byte holds the reading from the sensor. 0-255 = 0-15300 (linear) + This byte holds the reading from the sensor. 0-255 = 0-15300 (linear) -Bank 0x27 Sensors Bank2 Settings (R) -Bank 0x28 Sensors Bank2 Settings (W) ------------------------------------- +Bank 0x27 Sensors Bank2 Settings (R) and Bank 0x28 Sensors Bank2 Settings (W) +----------------------------------------------------------------------------- -This bank contains 6 sensors (AFAIK), for each sensor it contains 2 bytes. +Those banks contain 6 sensors (AFAIK), for each sensor it contains 2 bytes. Byte 0: -Alarm behaviour for the selected sensor. A 1 enables the described behaviour. -Bit 0: Give an alarm if measured rpm is under the min threshold (RW) -Bit 3: Beep if alarm (RW) -Bit 7: Shutdown if alarm persist for more than 4 seconds (RW) + Alarm behaviour for the selected sensor. A 1 enables the described behaviour. + +Bit 0: + Give an alarm if measured rpm is under the min threshold (RW) + +Bit 3: + Beep if alarm (RW) + +Bit 7: + Shutdown if alarm persist for more than 4 seconds (RW) Byte 1: -min threshold (scale as bank 0x26) + min threshold (scale as bank 0x26) Warning for the adventurous diff --git a/Documentation/hwmon/abituguru.rst b/Documentation/hwmon/abituguru.rst new file mode 100644 index 000000000000..d8243c827de9 --- /dev/null +++ b/Documentation/hwmon/abituguru.rst @@ -0,0 +1,113 @@ +Kernel driver abituguru +======================= + +Supported chips: + + * Abit uGuru revision 1 & 2 (Hardware Monitor part only) + + Prefix: 'abituguru' + + Addresses scanned: ISA 0x0E0 + + Datasheet: Not available, this driver is based on reverse engineering. + A "Datasheet" has been written based on the reverse engineering it + should be available in the same dir as this file under the name + abituguru-datasheet. + + Note: + The uGuru is a microcontroller with onboard firmware which programs + it to behave as a hwmon IC. There are many different revisions of the + firmware and thus effectivly many different revisions of the uGuru. + Below is an incomplete list with which revisions are used for which + Motherboards: + + - uGuru 1.00 ~ 1.24 (AI7, KV8-MAX3, AN7) [1]_ + - uGuru 2.0.0.0 ~ 2.0.4.2 (KV8-PRO) + - uGuru 2.1.0.0 ~ 2.1.2.8 (AS8, AV8, AA8, AG8, AA8XE, AX8) + - uGuru 2.2.0.0 ~ 2.2.0.6 (AA8 Fatal1ty) + - uGuru 2.3.0.0 ~ 2.3.0.9 (AN8) + - uGuru 3.0.0.0 ~ 3.0.x.x (AW8, AL8, AT8, NI8 SLI, AT8 32X, AN8 32X, + AW9D-MAX) [2]_ + +.. [1] For revisions 2 and 3 uGuru's the driver can autodetect the + sensortype (Volt or Temp) for bank1 sensors, for revision 1 uGuru's + this does not always work. For these uGuru's the autodetection can + be overridden with the bank1_types module param. For all 3 known + revison 1 motherboards the correct use of this param is: + bank1_types=1,1,0,0,0,0,0,2,0,0,0,0,2,0,0,1 + You may also need to specify the fan_sensors option for these boards + fan_sensors=5 + +.. [2] There is a separate abituguru3 driver for these motherboards, + the abituguru (without the 3 !) driver will not work on these + motherboards (and visa versa)! + +Authors: + - Hans de Goede <j.w.r.degoede@hhs.nl>, + - (Initial reverse engineering done by Olle Sandberg + <ollebull@gmail.com>) + + +Module Parameters +----------------- + +* force: bool + Force detection. Note this parameter only causes the + detection to be skipped, and thus the insmod to + succeed. If the uGuru can't be read the actual hwmon + driver will not load and thus no hwmon device will get + registered. +* bank1_types: int[] + Bank1 sensortype autodetection override: + + * -1 autodetect (default) + * 0 volt sensor + * 1 temp sensor + * 2 not connected +* fan_sensors: int + Tell the driver how many fan speed sensors there are + on your motherboard. Default: 0 (autodetect). +* pwms: int + Tell the driver how many fan speed controls (fan + pwms) your motherboard has. Default: 0 (autodetect). +* verbose: int + How verbose should the driver be? (0-3): + + * 0 normal output + * 1 + verbose error reporting + * 2 + sensors type probing info (default) + * 3 + retryable error reporting + + Default: 2 (the driver is still in the testing phase) + +Notice: if you need any of the first three options above please insmod the +driver with verbose set to 3 and mail me <j.w.r.degoede@hhs.nl> the output of: +dmesg | grep abituguru + + +Description +----------- + +This driver supports the hardware monitoring features of the first and +second revision of the Abit uGuru chip found on Abit uGuru featuring +motherboards (most modern Abit motherboards). + +The first and second revision of the uGuru chip in reality is a Winbond +W83L950D in disguise (despite Abit claiming it is "a new microprocessor +designed by the ABIT Engineers"). Unfortunately this doesn't help since the +W83L950D is a generic microcontroller with a custom Abit application running +on it. + +Despite Abit not releasing any information regarding the uGuru, Olle +Sandberg <ollebull@gmail.com> has managed to reverse engineer the sensor part +of the uGuru. Without his work this driver would not have been possible. + +Known Issues +------------ + +The voltage and frequency control parts of the Abit uGuru are not supported. + +.. toctree:: + :maxdepth: 1 + + abituguru-datasheet.rst diff --git a/Documentation/hwmon/abituguru3 b/Documentation/hwmon/abituguru3.rst index a6ccfe4bb6aa..514f11f41e8b 100644 --- a/Documentation/hwmon/abituguru3 +++ b/Documentation/hwmon/abituguru3.rst @@ -3,41 +3,51 @@ Kernel driver abituguru3 Supported chips: * Abit uGuru revision 3 (Hardware Monitor part, reading only) + Prefix: 'abituguru3' + Addresses scanned: ISA 0x0E0 + Datasheet: Not available, this driver is based on reverse engineering. + Note: The uGuru is a microcontroller with onboard firmware which programs it to behave as a hwmon IC. There are many different revisions of the firmware and thus effectivly many different revisions of the uGuru. Below is an incomplete list with which revisions are used for which Motherboards: - uGuru 1.00 ~ 1.24 (AI7, KV8-MAX3, AN7) - uGuru 2.0.0.0 ~ 2.0.4.2 (KV8-PRO) - uGuru 2.1.0.0 ~ 2.1.2.8 (AS8, AV8, AA8, AG8, AA8XE, AX8) - uGuru 2.3.0.0 ~ 2.3.0.9 (AN8) - uGuru 3.0.0.0 ~ 3.0.x.x (AW8, AL8, AT8, NI8 SLI, AT8 32X, AN8 32X, - AW9D-MAX) + + - uGuru 1.00 ~ 1.24 (AI7, KV8-MAX3, AN7) + - uGuru 2.0.0.0 ~ 2.0.4.2 (KV8-PRO) + - uGuru 2.1.0.0 ~ 2.1.2.8 (AS8, AV8, AA8, AG8, AA8XE, AX8) + - uGuru 2.3.0.0 ~ 2.3.0.9 (AN8) + - uGuru 3.0.0.0 ~ 3.0.x.x (AW8, AL8, AT8, NI8 SLI, AT8 32X, AN8 32X, + AW9D-MAX) + The abituguru3 driver is only for revison 3.0.x.x motherboards, this driver will not work on older motherboards. For older motherboards use the abituguru (without the 3 !) driver. Authors: - Hans de Goede <j.w.r.degoede@hhs.nl>, - (Initial reverse engineering done by Louis Kruger) + - Hans de Goede <j.w.r.degoede@hhs.nl>, + - (Initial reverse engineering done by Louis Kruger) Module Parameters ----------------- -* force: bool Force detection. Note this parameter only causes the +* force: bool + Force detection. Note this parameter only causes the detection to be skipped, and thus the insmod to succeed. If the uGuru can't be read the actual hwmon driver will not load and thus no hwmon device will get registered. -* verbose: bool Should the driver be verbose? - 0/off/false normal output - 1/on/true + verbose error reporting (default) +* verbose: bool + Should the driver be verbose? + + * 0/off/false normal output + * 1/on/true + verbose error reporting (default) + Default: 1 (the driver is still in the testing phase) Description @@ -62,4 +72,4 @@ neither is writing any of the sensor settings and writing / reading the fanspeed control registers (FanEQ) If you encounter any problems please mail me <j.w.r.degoede@hhs.nl> and -include the output of: "dmesg | grep abituguru" +include the output of: `dmesg | grep abituguru` diff --git a/Documentation/hwmon/abx500 b/Documentation/hwmon/abx500.rst index 319a058cec7c..3d88b2ce0f00 100644 --- a/Documentation/hwmon/abx500 +++ b/Documentation/hwmon/abx500.rst @@ -2,14 +2,18 @@ Kernel driver abx500 ==================== Supported chips: + * ST-Ericsson ABx500 series + Prefix: 'abx500' + Addresses scanned: - + Datasheet: http://www.stericsson.com/developers/documentation.jsp Authors: - Martin Persson <martin.persson@stericsson.com> - Hongbo Zhang <hongbo.zhang@linaro.org> + Martin Persson <martin.persson@stericsson.com> + Hongbo Zhang <hongbo.zhang@linaro.org> Description ----------- diff --git a/Documentation/hwmon/acpi_power_meter b/Documentation/hwmon/acpi_power_meter.rst index c80399a00c50..4a0941ade0ca 100644 --- a/Documentation/hwmon/acpi_power_meter +++ b/Documentation/hwmon/acpi_power_meter.rst @@ -4,8 +4,11 @@ Kernel driver power_meter This driver talks to ACPI 4.0 power meters. Supported systems: + * Any recent system with ACPI 4.0. + Prefix: 'power_meter' + Datasheet: http://acpi.info/, section 10.4. Author: Darrick J. Wong @@ -18,26 +21,26 @@ the ACPI 4.0 spec (Chapter 10.4). These devices have a simple set of features--a power meter that returns average power use over a configurable interval, an optional capping mechanism, and a couple of trip points. The sysfs interface conforms with the specification outlined in the "Power" section -of Documentation/hwmon/sysfs-interface. +of Documentation/hwmon/sysfs-interface.rst. Special Features ---------------- -The power[1-*]_is_battery knob indicates if the power supply is a battery. -Both power[1-*]_average_{min,max} must be set before the trip points will work. +The `power[1-*]_is_battery` knob indicates if the power supply is a battery. +Both `power[1-*]_average_{min,max}` must be set before the trip points will work. When both of them are set, an ACPI event will be broadcast on the ACPI netlink socket and a poll notification will be sent to the appropriate -power[1-*]_average sysfs file. +`power[1-*]_average` sysfs file. -The power[1-*]_{model_number, serial_number, oem_info} fields display arbitrary -strings that ACPI provides with the meter. The measures/ directory contains -symlinks to the devices that this meter measures. +The `power[1-*]_{model_number, serial_number, oem_info}` fields display +arbitrary strings that ACPI provides with the meter. The measures/ directory +contains symlinks to the devices that this meter measures. Some computers have the ability to enforce a power cap in hardware. If this is -the case, the power[1-*]_cap and related sysfs files will appear. When the +the case, the `power[1-*]_cap` and related sysfs files will appear. When the average power consumption exceeds the cap, an ACPI event will be broadcast on the netlink event socket and a poll notification will be sent to the -appropriate power[1-*]_alarm file to indicate that capping has begun, and the +appropriate `power[1-*]_alarm` file to indicate that capping has begun, and the hardware has taken action to reduce power consumption. Most likely this will result in reduced performance. @@ -46,6 +49,6 @@ all cases the ACPI event will be broadcast on the ACPI netlink event socket as well as sent as a poll notification to a sysfs file. The events are as follows: -power[1-*]_cap will be notified if the firmware changes the power cap. -power[1-*]_interval will be notified if the firmware changes the averaging +`power[1-*]_cap` will be notified if the firmware changes the power cap. +`power[1-*]_interval` will be notified if the firmware changes the averaging interval. diff --git a/Documentation/hwmon/ad7314 b/Documentation/hwmon/ad7314.rst index 1912549c7467..bf389736bcd1 100644 --- a/Documentation/hwmon/ad7314 +++ b/Documentation/hwmon/ad7314.rst @@ -2,14 +2,23 @@ Kernel driver ad7314 ==================== Supported chips: + * Analog Devices AD7314 + Prefix: 'ad7314' + Datasheet: Publicly available at Analog Devices website. + * Analog Devices ADT7301 + Prefix: 'adt7301' + Datasheet: Publicly available at Analog Devices website. + * Analog Devices ADT7302 + Prefix: 'adt7302' + Datasheet: Publicly available at Analog Devices website. Description diff --git a/Documentation/hwmon/adc128d818 b/Documentation/hwmon/adc128d818.rst index 39c95004dabc..6753468932ab 100644 --- a/Documentation/hwmon/adc128d818 +++ b/Documentation/hwmon/adc128d818.rst @@ -2,11 +2,14 @@ Kernel driver adc128d818 ======================== Supported chips: + * Texas Instruments ADC818D818 + Prefix: 'adc818d818' + Addresses scanned: I2C 0x1d, 0x1e, 0x1f, 0x2d, 0x2e, 0x2f - Datasheet: Publicly available at the TI website - http://www.ti.com/ + + Datasheet: Publicly available at the TI website http://www.ti.com/ Author: Guenter Roeck diff --git a/Documentation/hwmon/adm1021 b/Documentation/hwmon/adm1021.rst index 02ad96cf9b2b..6cbb0f75fe00 100644 --- a/Documentation/hwmon/adm1021 +++ b/Documentation/hwmon/adm1021.rst @@ -2,51 +2,91 @@ Kernel driver adm1021 ===================== Supported chips: + * Analog Devices ADM1021 + Prefix: 'adm1021' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the Analog Devices website + * Analog Devices ADM1021A/ADM1023 + Prefix: 'adm1023' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the Analog Devices website + * Genesys Logic GL523SM + Prefix: 'gl523sm' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: + * Maxim MAX1617 + Prefix: 'max1617' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the Maxim website + * Maxim MAX1617A + Prefix: 'max1617a' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the Maxim website + * National Semiconductor LM84 + Prefix: 'lm84' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the National Semiconductor website + * Philips NE1617 + Prefix: 'max1617' (probably detected as a max1617) + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the Philips website + * Philips NE1617A + Prefix: 'max1617' (probably detected as a max1617) + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the Philips website + * TI THMC10 + Prefix: 'thmc10' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the TI website + * Onsemi MC1066 + Prefix: 'mc1066' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the Onsemi website Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com> + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com> Module Parameters ----------------- diff --git a/Documentation/hwmon/adm1025 b/Documentation/hwmon/adm1025.rst index 99f05049c68a..283e65e348a5 100644 --- a/Documentation/hwmon/adm1025 +++ b/Documentation/hwmon/adm1025.rst @@ -2,23 +2,32 @@ Kernel driver adm1025 ===================== Supported chips: + * Analog Devices ADM1025, ADM1025A + Prefix: 'adm1025' + Addresses scanned: I2C 0x2c - 0x2e + Datasheet: Publicly available at the Analog Devices website + * Philips NE1619 + Prefix: 'ne1619' + Addresses scanned: I2C 0x2c - 0x2d + Datasheet: Publicly available at the Philips website The NE1619 presents some differences with the original ADM1025: + * Only two possible addresses (0x2c - 0x2d). * No temperature offset register, but we don't use it anyway. * No INT mode for pin 16. We don't play with it anyway. Authors: - Chen-Yuan Wu <gwu@esoft.com>, - Jean Delvare <jdelvare@suse.de> + - Chen-Yuan Wu <gwu@esoft.com>, + - Jean Delvare <jdelvare@suse.de> Description ----------- diff --git a/Documentation/hwmon/adm1026 b/Documentation/hwmon/adm1026.rst index d8fabe0c23ac..35d63e6498a3 100644 --- a/Documentation/hwmon/adm1026 +++ b/Documentation/hwmon/adm1026.rst @@ -3,28 +3,36 @@ Kernel driver adm1026 Supported chips: * Analog Devices ADM1026 + Prefix: 'adm1026' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: Publicly available at the Analog Devices website - http://www.onsemi.com/PowerSolutions/product.do?id=ADM1026 + + http://www.onsemi.com/PowerSolutions/product.do?id=ADM1026 Authors: - Philip Pokorny <ppokorny@penguincomputing.com> for Penguin Computing - Justin Thiessen <jthiessen@penguincomputing.com> + - Philip Pokorny <ppokorny@penguincomputing.com> for Penguin Computing + - Justin Thiessen <jthiessen@penguincomputing.com> Module Parameters ----------------- * gpio_input: int array (min = 1, max = 17) - List of GPIO pins (0-16) to program as inputs + List of GPIO pins (0-16) to program as inputs + * gpio_output: int array (min = 1, max = 17) - List of GPIO pins (0-16) to program as outputs + List of GPIO pins (0-16) to program as outputs + * gpio_inverted: int array (min = 1, max = 17) - List of GPIO pins (0-16) to program as inverted + List of GPIO pins (0-16) to program as inverted + * gpio_normal: int array (min = 1, max = 17) - List of GPIO pins (0-16) to program as normal/non-inverted + List of GPIO pins (0-16) to program as normal/non-inverted + * gpio_fan: int array (min = 1, max = 8) - List of GPIO pins (0-7) to program as fan tachs + List of GPIO pins (0-7) to program as fan tachs Description diff --git a/Documentation/hwmon/adm1031 b/Documentation/hwmon/adm1031.rst index a143117c99cb..a677c3ab5574 100644 --- a/Documentation/hwmon/adm1031 +++ b/Documentation/hwmon/adm1031.rst @@ -3,20 +3,28 @@ Kernel driver adm1031 Supported chips: * Analog Devices ADM1030 + Prefix: 'adm1030' + Addresses scanned: I2C 0x2c to 0x2e + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/en/prod/0%2C2877%2CADM1030%2C00.html + + http://www.analog.com/en/prod/0%2C2877%2CADM1030%2C00.html * Analog Devices ADM1031 + Prefix: 'adm1031' + Addresses scanned: I2C 0x2c to 0x2e + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/en/prod/0%2C2877%2CADM1031%2C00.html + + http://www.analog.com/en/prod/0%2C2877%2CADM1031%2C00.html Authors: - Alexandre d'Alton <alex@alexdalton.org> - Jean Delvare <jdelvare@suse.de> + - Alexandre d'Alton <alex@alexdalton.org> + - Jean Delvare <jdelvare@suse.de> Description ----------- diff --git a/Documentation/hwmon/adm1275 b/Documentation/hwmon/adm1275.rst index 5e277b0d91ce..9a1913e5b4d9 100644 --- a/Documentation/hwmon/adm1275 +++ b/Documentation/hwmon/adm1275.rst @@ -2,29 +2,53 @@ Kernel driver adm1275 ===================== Supported chips: + * Analog Devices ADM1075 + Prefix: 'adm1075' + Addresses scanned: - + Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1075.pdf + * Analog Devices ADM1272 + Prefix: 'adm1272' + Addresses scanned: - + Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1272.pdf + * Analog Devices ADM1275 + Prefix: 'adm1275' + Addresses scanned: - + Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1275.pdf + * Analog Devices ADM1276 + Prefix: 'adm1276' + Addresses scanned: - + Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1276.pdf + * Analog Devices ADM1278 + Prefix: 'adm1278' + Addresses scanned: - + Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1278.pdf + * Analog Devices ADM1293/ADM1294 + Prefix: 'adm1293', 'adm1294' + Addresses scanned: - + Datasheet: http://www.analog.com/media/en/technical-documentation/data-sheets/ADM1293_1294.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -44,7 +68,7 @@ integrated 12 bit analog-to-digital converter (ADC), accessed using a PMBus interface. The driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus for details on PMBus client drivers. +Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -66,7 +90,7 @@ Platform data support --------------------- The driver supports standard PMBus driver platform data. Please see -Documentation/hwmon/pmbus for details. +Documentation/hwmon/pmbus.rst for details. Sysfs entries @@ -75,6 +99,7 @@ Sysfs entries The following attributes are supported. Limits are read-write, history reset attributes are write-only, all other attributes are read-only. +======================= ======================================================= inX_label "vin1" or "vout1" depending on chip variant and configuration. On ADM1075, ADM1293, and ADM1294, vout1 reports the voltage on the VAUX pin. @@ -120,3 +145,4 @@ temp1_reset_history Write any value to reset history. Temperature attributes are supported on ADM1272 and ADM1278. +======================= ======================================================= diff --git a/Documentation/hwmon/adm9240 b/Documentation/hwmon/adm9240.rst index 9b174fc700cc..91063b0f4c6f 100644 --- a/Documentation/hwmon/adm9240 +++ b/Documentation/hwmon/adm9240.rst @@ -2,30 +2,43 @@ Kernel driver adm9240 ===================== Supported chips: + * Analog Devices ADM9240 + Prefix: 'adm9240' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/UploadedFiles/Data_Sheets/79857778ADM9240_0.pdf + + http://www.analog.com/UploadedFiles/Data_Sheets/79857778ADM9240_0.pdf * Dallas Semiconductor DS1780 + Prefix: 'ds1780' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: Publicly available at the Dallas Semiconductor (Maxim) website - http://pdfserv.maxim-ic.com/en/ds/DS1780.pdf + + http://pdfserv.maxim-ic.com/en/ds/DS1780.pdf * National Semiconductor LM81 + Prefix: 'lm81' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ds.cgi/LM/LM81.pdf + + http://www.national.com/ds.cgi/LM/LM81.pdf Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Michiel Rook <michiel@grendelproject.nl>, - Grant Coady <gcoady.lk@gmail.com> with guidance - from Jean Delvare <jdelvare@suse.de> + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com>, + - Michiel Rook <michiel@grendelproject.nl>, + - Grant Coady <gcoady.lk@gmail.com> with guidance + from Jean Delvare <jdelvare@suse.de> Interface --------- @@ -87,11 +100,13 @@ rpm = (22500 * 60) / (count * divider) Automatic fan clock divider * User sets 0 to fan_min limit + - low speed alarm is disabled - fan clock divider not changed - auto fan clock adjuster enabled for valid fan speed reading * User sets fan_min limit too low + - low speed alarm is enabled - fan clock divider set to max - fan_min set to register value 254 which corresponds @@ -101,18 +116,20 @@ Automatic fan clock divider - auto fan clock adjuster disabled * User sets reasonable fan speed + - low speed alarm is enabled - fan clock divider set to suit fan_min - auto fan clock adjuster enabled: adjusts fan_min * User sets unreasonably high low fan speed limit + - resolution of the low speed limit may be reduced - alarm will be asserted - auto fan clock adjuster enabled: adjusts fan_min - * fan speed may be displayed as zero until the auto fan clock divider - adjuster brings fan speed clock divider back into chip measurement - range, this will occur within a few measurement cycles. + * fan speed may be displayed as zero until the auto fan clock divider + adjuster brings fan speed clock divider back into chip measurement + range, this will occur within a few measurement cycles. Analog Output ------------- @@ -122,16 +139,21 @@ power up or reset. This doesn't do much on the test Intel SE440BX-2. Voltage Monitor +^^^^^^^^^^^^^^^ + Voltage (IN) measurement is internally scaled: + === =========== =========== ========= ========== nr label nominal maximum resolution - mV mV mV + mV mV mV + === =========== =========== ========= ========== 0 +2.5V 2500 3320 13.0 1 Vccp1 2700 3600 14.1 2 +3.3V 3300 4380 17.2 3 +5V 5000 6640 26.0 4 +12V 12000 15940 62.5 5 Vccp2 2700 3600 14.1 + === =========== =========== ========= ========== The reading is an unsigned 8-bit value, nominal voltage measurement is represented by a reading of 192, being 3/4 of the measurement range. @@ -159,8 +181,9 @@ Clear the CI latch by writing value 0 to the sysfs intrusion0_alarm file. Alarm flags reported as 16-bit word + === ============= ========================== bit label comment - --- ------------- -------------------------- + === ============= ========================== 0 +2.5 V_Error high or low limit exceeded 1 VCCP_Error high or low limit exceeded 2 +3.3 V_Error high or low limit exceeded @@ -171,6 +194,7 @@ Alarm flags reported as 16-bit word 8 +12 V_Error high or low limit exceeded 9 VCCP2_Error high or low limit exceeded 12 Chassis_Error CI pin went high + === ============= ========================== Remaining bits are reserved and thus undefined. It is important to note that alarm bits may be cleared on read, user-space may latch alarms and diff --git a/Documentation/hwmon/ads1015 b/Documentation/hwmon/ads1015.rst index 02d2a459385f..e0951c4e57bb 100644 --- a/Documentation/hwmon/ads1015 +++ b/Documentation/hwmon/ads1015.rst @@ -2,17 +2,25 @@ Kernel driver ads1015 ===================== Supported chips: + * Texas Instruments ADS1015 + Prefix: 'ads1015' - Datasheet: Publicly available at the Texas Instruments website : - http://focus.ti.com/lit/ds/symlink/ads1015.pdf + + Datasheet: Publicly available at the Texas Instruments website: + + http://focus.ti.com/lit/ds/symlink/ads1015.pdf + * Texas Instruments ADS1115 + Prefix: 'ads1115' - Datasheet: Publicly available at the Texas Instruments website : - http://focus.ti.com/lit/ds/symlink/ads1115.pdf + + Datasheet: Publicly available at the Texas Instruments website: + + http://focus.ti.com/lit/ds/symlink/ads1115.pdf Authors: - Dirk Eibach, Guntermann & Drunck GmbH <eibach@gdsys.de> + Dirk Eibach, Guntermann & Drunck GmbH <eibach@gdsys.de> Description ----------- @@ -24,14 +32,15 @@ This device is a 12/16-bit A-D converter with 4 inputs. The inputs can be used single ended or in certain differential combinations. The inputs can be made available by 8 sysfs input files in0_input - in7_input: -in0: Voltage over AIN0 and AIN1. -in1: Voltage over AIN0 and AIN3. -in2: Voltage over AIN1 and AIN3. -in3: Voltage over AIN2 and AIN3. -in4: Voltage over AIN0 and GND. -in5: Voltage over AIN1 and GND. -in6: Voltage over AIN2 and GND. -in7: Voltage over AIN3 and GND. + + - in0: Voltage over AIN0 and AIN1. + - in1: Voltage over AIN0 and AIN3. + - in2: Voltage over AIN1 and AIN3. + - in3: Voltage over AIN2 and AIN3. + - in4: Voltage over AIN0 and GND. + - in5: Voltage over AIN1 and GND. + - in6: Voltage over AIN2 and GND. + - in7: Voltage over AIN3 and GND. Which inputs are available can be configured using platform data or devicetree. @@ -42,29 +51,34 @@ Platform Data In linux/platform_data/ads1015.h platform data is defined, channel_data contains configuration data for the used input combinations: + - pga is the programmable gain amplifier (values are full scale) - 0: +/- 6.144 V - 1: +/- 4.096 V - 2: +/- 2.048 V - 3: +/- 1.024 V - 4: +/- 0.512 V - 5: +/- 0.256 V + + - 0: +/- 6.144 V + - 1: +/- 4.096 V + - 2: +/- 2.048 V + - 3: +/- 1.024 V + - 4: +/- 0.512 V + - 5: +/- 0.256 V + - data_rate in samples per second - 0: 128 - 1: 250 - 2: 490 - 3: 920 - 4: 1600 - 5: 2400 - 6: 3300 - -Example: -struct ads1015_platform_data data = { + + - 0: 128 + - 1: 250 + - 2: 490 + - 3: 920 + - 4: 1600 + - 5: 2400 + - 6: 3300 + +Example:: + + struct ads1015_platform_data data = { .channel_data = { [2] = { .enabled = true, .pga = 1, .data_rate = 0 }, [4] = { .enabled = true, .pga = 4, .data_rate = 5 }, } -}; + }; In this case only in2_input (FS +/- 4.096 V, 128 SPS) and in4_input (FS +/- 0.512 V, 2400 SPS) would be created. diff --git a/Documentation/hwmon/ads7828 b/Documentation/hwmon/ads7828.rst index f6e263e0f607..b830b490cfe4 100644 --- a/Documentation/hwmon/ads7828 +++ b/Documentation/hwmon/ads7828.rst @@ -2,20 +2,27 @@ Kernel driver ads7828 ===================== Supported chips: + * Texas Instruments/Burr-Brown ADS7828 + Prefix: 'ads7828' + Datasheet: Publicly available at the Texas Instruments website: - http://focus.ti.com/lit/ds/symlink/ads7828.pdf + + http://focus.ti.com/lit/ds/symlink/ads7828.pdf * Texas Instruments ADS7830 + Prefix: 'ads7830' + Datasheet: Publicly available at the Texas Instruments website: - http://focus.ti.com/lit/ds/symlink/ads7830.pdf + + http://focus.ti.com/lit/ds/symlink/ads7830.pdf Authors: - Steve Hardy <shardy@redhat.com> - Vivien Didelot <vivien.didelot@savoirfairelinux.com> - Guillaume Roguez <guillaume.roguez@savoirfairelinux.com> + - Steve Hardy <shardy@redhat.com> + - Vivien Didelot <vivien.didelot@savoirfairelinux.com> + - Guillaume Roguez <guillaume.roguez@savoirfairelinux.com> Platform data ------------- @@ -24,16 +31,16 @@ The ads7828 driver accepts an optional ads7828_platform_data structure (defined in include/linux/platform_data/ads7828.h). The structure fields are: * diff_input: (bool) Differential operation - set to true for differential mode, false for default single ended mode. + set to true for differential mode, false for default single ended mode. * ext_vref: (bool) External reference - set to true if it operates with an external reference, false for default - internal reference. + set to true if it operates with an external reference, false for default + internal reference. * vref_mv: (unsigned int) Voltage reference - if using an external reference, set this to the reference voltage in mV, - otherwise it will default to the internal value (2500mV). This value will be - bounded with limits accepted by the chip, described in the datasheet. + if using an external reference, set this to the reference voltage in mV, + otherwise it will default to the internal value (2500mV). This value will be + bounded with limits accepted by the chip, described in the datasheet. If no structure is provided, the configuration defaults to single ended operation and internal voltage reference (2.5V). diff --git a/Documentation/hwmon/adt7410 b/Documentation/hwmon/adt7410.rst index 9817941e5f19..24caaa83c8ec 100644 --- a/Documentation/hwmon/adt7410 +++ b/Documentation/hwmon/adt7410.rst @@ -2,26 +2,45 @@ Kernel driver adt7410 ===================== Supported chips: + * Analog Devices ADT7410 + Prefix: 'adt7410' + Addresses scanned: None + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7410.pdf + + http://www.analog.com/static/imported-files/data_sheets/ADT7410.pdf * Analog Devices ADT7420 + Prefix: 'adt7420' + Addresses scanned: None + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7420.pdf + + http://www.analog.com/static/imported-files/data_sheets/ADT7420.pdf + * Analog Devices ADT7310 + Prefix: 'adt7310' + Addresses scanned: None + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7310.pdf + + http://www.analog.com/static/imported-files/data_sheets/ADT7310.pdf + * Analog Devices ADT7320 + Prefix: 'adt7320' + Addresses scanned: None + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/static/imported-files/data_sheets/ADT7320.pdf + + http://www.analog.com/static/imported-files/data_sheets/ADT7320.pdf Author: Hartmut Knaack <knaack.h@gmx.de> @@ -61,13 +80,15 @@ The device is set to 16 bit resolution and comparator mode. sysfs-Interface --------------- -temp#_input - temperature input -temp#_min - temperature minimum setpoint -temp#_max - temperature maximum setpoint -temp#_crit - critical temperature setpoint -temp#_min_hyst - hysteresis for temperature minimum (read-only) -temp#_max_hyst - hysteresis for temperature maximum (read/write) -temp#_crit_hyst - hysteresis for critical temperature (read-only) -temp#_min_alarm - temperature minimum alarm flag -temp#_max_alarm - temperature maximum alarm flag -temp#_crit_alarm - critical temperature alarm flag +======================== ==================================================== +temp#_input temperature input +temp#_min temperature minimum setpoint +temp#_max temperature maximum setpoint +temp#_crit critical temperature setpoint +temp#_min_hyst hysteresis for temperature minimum (read-only) +temp#_max_hyst hysteresis for temperature maximum (read/write) +temp#_crit_hyst hysteresis for critical temperature (read-only) +temp#_min_alarm temperature minimum alarm flag +temp#_max_alarm temperature maximum alarm flag +temp#_crit_alarm critical temperature alarm flag +======================== ==================================================== diff --git a/Documentation/hwmon/adt7411 b/Documentation/hwmon/adt7411.rst index 1632960f9745..57ad16fb216a 100644 --- a/Documentation/hwmon/adt7411 +++ b/Documentation/hwmon/adt7411.rst @@ -2,9 +2,13 @@ Kernel driver adt7411 ===================== Supported chips: + * Analog Devices ADT7411 + Prefix: 'adt7411' + Addresses scanned: 0x48, 0x4a, 0x4b + Datasheet: Publicly available at the Analog Devices website Author: Wolfram Sang (based on adt7470 by Darrick J. Wong) @@ -26,15 +30,19 @@ Check the datasheet for details. sysfs-Interface --------------- -in0_input - vdd voltage input -in[1-8]_input - analog 1-8 input -temp1_input - temperature input +================ ================= +in0_input vdd voltage input +in[1-8]_input analog 1-8 input +temp1_input temperature input +================ ================= Besides standard interfaces, this driver adds (0 = off, 1 = on): - adc_ref_vdd - Use vdd as reference instead of 2.25 V - fast_sampling - Sample at 22.5 kHz instead of 1.4 kHz, but drop filters - no_average - Turn off averaging over 16 samples + ============== ======================================================= + adc_ref_vdd Use vdd as reference instead of 2.25 V + fast_sampling Sample at 22.5 kHz instead of 1.4 kHz, but drop filters + no_average Turn off averaging over 16 samples + ============== ======================================================= Notes ----- diff --git a/Documentation/hwmon/adt7462 b/Documentation/hwmon/adt7462.rst index ec660b328275..139e19696188 100644 --- a/Documentation/hwmon/adt7462 +++ b/Documentation/hwmon/adt7462.rst @@ -1,10 +1,14 @@ Kernel driver adt7462 -====================== +===================== Supported chips: + * Analog Devices ADT7462 + Prefix: 'adt7462' + Addresses scanned: I2C 0x58, 0x5C + Datasheet: Publicly available at the Analog Devices website Author: Darrick J. Wong @@ -57,11 +61,10 @@ Besides standard interfaces driver adds the following: * pwm#_auto_point1_pwm and temp#_auto_point1_temp and * pwm#_auto_point2_pwm and temp#_auto_point2_temp - -point1: Set the pwm speed at a lower temperature bound. -point2: Set the pwm speed at a higher temperature bound. + - point1: Set the pwm speed at a lower temperature bound. + - point2: Set the pwm speed at a higher temperature bound. The ADT7462 will scale the pwm between the lower and higher pwm speed when the temperature is between the two temperature boundaries. PWM values range from 0 (off) to 255 (full speed). Fan speed will be set to maximum when the temperature sensor associated with the PWM control exceeds temp#_max. - diff --git a/Documentation/hwmon/adt7470 b/Documentation/hwmon/adt7470.rst index fe68e18a0c8d..d225f816e992 100644 --- a/Documentation/hwmon/adt7470 +++ b/Documentation/hwmon/adt7470.rst @@ -2,9 +2,13 @@ Kernel driver adt7470 ===================== Supported chips: + * Analog Devices ADT7470 + Prefix: 'adt7470' + Addresses scanned: I2C 0x2C, 0x2E, 0x2F + Datasheet: Publicly available at the Analog Devices website Author: Darrick J. Wong @@ -56,8 +60,8 @@ Besides standard interfaces driver adds the following: * pwm#_auto_point1_pwm and pwm#_auto_point1_temp and * pwm#_auto_point2_pwm and pwm#_auto_point2_temp - -point1: Set the pwm speed at a lower temperature bound. -point2: Set the pwm speed at a higher temperature bound. + - point1: Set the pwm speed at a lower temperature bound. + - point2: Set the pwm speed at a higher temperature bound. The ADT7470 will scale the pwm between the lower and higher pwm speed when the temperature is between the two temperature boundaries. PWM values range diff --git a/Documentation/hwmon/adt7475 b/Documentation/hwmon/adt7475.rst index 01b46b290532..ef3ea1ea9bc1 100644 --- a/Documentation/hwmon/adt7475 +++ b/Documentation/hwmon/adt7475.rst @@ -2,28 +2,44 @@ Kernel driver adt7475 ===================== Supported chips: + * Analog Devices ADT7473 + Prefix: 'adt7473' + Addresses scanned: I2C 0x2C, 0x2D, 0x2E + Datasheet: Publicly available at the On Semiconductors website + * Analog Devices ADT7475 + Prefix: 'adt7475' + Addresses scanned: I2C 0x2E + Datasheet: Publicly available at the On Semiconductors website + * Analog Devices ADT7476 + Prefix: 'adt7476' + Addresses scanned: I2C 0x2C, 0x2D, 0x2E + Datasheet: Publicly available at the On Semiconductors website + * Analog Devices ADT7490 + Prefix: 'adt7490' + Addresses scanned: I2C 0x2C, 0x2D, 0x2E + Datasheet: Publicly available at the On Semiconductors website Authors: - Jordan Crouse - Hans de Goede - Darrick J. Wong (documentation) - Jean Delvare + - Jordan Crouse + - Hans de Goede + - Darrick J. Wong (documentation) + - Jean Delvare Description @@ -82,14 +98,16 @@ ADT7490: Sysfs Mapping ------------- - ADT7490 ADT7476 ADT7475 ADT7473 - ------- ------- ------- ------- +==== =========== =========== ========= ========== +in ADT7490 ADT7476 ADT7475 ADT7473 +==== =========== =========== ========= ========== in0 2.5VIN (22) 2.5VIN (22) - - in1 VCCP (23) VCCP (23) VCCP (14) VCCP (14) in2 VCC (4) VCC (4) VCC (4) VCC (3) in3 5VIN (20) 5VIN (20) in4 12VIN (21) 12VIN (21) in5 VTT (8) +==== =========== =========== ========= ========== Special Features ---------------- @@ -107,8 +125,8 @@ Fan Speed Control The driver exposes two trip points per PWM channel. -point1: Set the PWM speed at the lower temperature bound -point2: Set the PWM speed at the higher temperature bound +- point1: Set the PWM speed at the lower temperature bound +- point2: Set the PWM speed at the higher temperature bound The ADT747x will scale the PWM linearly between the lower and higher PWM speed when the temperature is between the two temperature boundaries. @@ -123,12 +141,12 @@ the PWM control exceeds temp#_max. At Tmin - hysteresis the PWM output can either be off (0% duty cycle) or at the minimum (i.e. auto_point1_pwm). This behaviour can be configured using the -pwm[1-*]_stall_disable sysfs attribute. A value of 0 means the fans will shut +`pwm[1-*]_stall_disable sysfs attribute`. A value of 0 means the fans will shut off. A value of 1 means the fans will run at auto_point1_pwm. The responsiveness of the ADT747x to temperature changes can be configured. This allows smoothing of the fan speed transition. To set the transition time -set the value in ms in the temp[1-*]_smoothing sysfs attribute. +set the value in ms in the `temp[1-*]_smoothing` sysfs attribute. Notes ----- diff --git a/Documentation/hwmon/amc6821 b/Documentation/hwmon/amc6821.rst index ced8359c50f8..5ddb2849da90 100644 --- a/Documentation/hwmon/amc6821 +++ b/Documentation/hwmon/amc6821.rst @@ -2,9 +2,13 @@ Kernel driver amc6821 ===================== Supported chips: + Texas Instruments AMC6821 + Prefix: 'amc6821' + Addresses scanned: 0x18, 0x19, 0x1a, 0x2c, 0x2d, 0x2e, 0x4c, 0x4d, 0x4e + Datasheet: http://focus.ti.com/docs/prod/folders/print/amc6821.html Authors: @@ -21,10 +25,11 @@ The pwm can be controlled either from software or automatically. The driver provides the following sensor accesses in sysfs: +======================= == =============================================== temp1_input ro on-chip temperature temp1_min rw " temp1_max rw " -temp1_crit rw " +temp1_crit rw " temp1_min_alarm ro " temp1_max_alarm ro " temp1_crit_alarm ro " @@ -32,16 +37,16 @@ temp1_crit_alarm ro " temp2_input ro remote temperature temp2_min rw " temp2_max rw " -temp2_crit rw " +temp2_crit rw " temp2_min_alarm ro " temp2_max_alarm ro " temp2_crit_alarm ro " temp2_fault ro " -fan1_input ro tachometer speed +fan1_input ro tachometer speed fan1_min rw " fan1_max rw " -fan1_fault ro " +fan1_fault ro " fan1_div rw Fan divisor can be either 2 or 4. pwm1 rw pwm1 @@ -87,6 +92,7 @@ temp2_auto_point3_temp rw Above this temperature fan runs at maximum values which depend on temp2_auto_point2_temp and pwm1_auto_point2_pwm. Read it out after writing to get actual value. +======================= == =============================================== Module parameters @@ -97,6 +103,6 @@ load the module with: init=0. If your board BIOS doesn't initialize the chip, or you want different settings, you can set the following parameters: -init=1, -pwminv: 0 default pwm output, 1 inverts pwm output. +- init=1, +- pwminv: 0 default pwm output, 1 inverts pwm output. diff --git a/Documentation/hwmon/asb100 b/Documentation/hwmon/asb100.rst index ab7365e139be..c2d5f97085fe 100644 --- a/Documentation/hwmon/asb100 +++ b/Documentation/hwmon/asb100.rst @@ -2,9 +2,13 @@ Kernel driver asb100 ==================== Supported Chips: + * Asus ASB100 and ASB100-A "Bach" + Prefix: 'asb100' + Addresses scanned: I2C 0x2d + Datasheet: none released Author: Mark M. Hoffman <mhoffman@lightlink.com> @@ -41,32 +45,29 @@ processor itself. It is a value in volts. Alarms: (TODO question marks indicate may or may not work) -0x0001 => in0 (?) -0x0002 => in1 (?) -0x0004 => in2 -0x0008 => in3 -0x0010 => temp1 (1) -0x0020 => temp2 -0x0040 => fan1 -0x0080 => fan2 -0x0100 => in4 -0x0200 => in5 (?) (2) -0x0400 => in6 (?) (2) -0x0800 => fan3 -0x1000 => chassis switch -0x2000 => temp3 - -Alarm Notes: - -(1) This alarm will only trigger if the hysteresis value is 127C. -I.e. it behaves the same as w83781d. - -(2) The min and max registers for these values appear to -be read-only or otherwise stuck at 0x00. +- 0x0001 => in0 (?) +- 0x0002 => in1 (?) +- 0x0004 => in2 +- 0x0008 => in3 +- 0x0010 => temp1 [1]_ +- 0x0020 => temp2 +- 0x0040 => fan1 +- 0x0080 => fan2 +- 0x0100 => in4 +- 0x0200 => in5 (?) [2]_ +- 0x0400 => in6 (?) [2]_ +- 0x0800 => fan3 +- 0x1000 => chassis switch +- 0x2000 => temp3 + +.. [1] This alarm will only trigger if the hysteresis value is 127C. + I.e. it behaves the same as w83781d. + +.. [2] The min and max registers for these values appear to + be read-only or otherwise stuck at 0x00. TODO: -* Experiment with fan divisors > 8. -* Experiment with temp. sensor types. -* Are there really 13 voltage inputs? Probably not... -* Cleanups, no doubt... - + * Experiment with fan divisors > 8. + * Experiment with temp. sensor types. + * Are there really 13 voltage inputs? Probably not... + * Cleanups, no doubt... diff --git a/Documentation/hwmon/asc7621 b/Documentation/hwmon/asc7621.rst index 7287be7e1f21..b5a9fad0f172 100644 --- a/Documentation/hwmon/asc7621 +++ b/Documentation/hwmon/asc7621.rst @@ -1,10 +1,15 @@ +===================== Kernel driver asc7621 -================== +===================== Supported chips: + Andigilog aSC7621 and aSC7621a + Prefix: 'asc7621' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.fairview5.com/linux/asc7621/asc7621.pdf Author: @@ -73,8 +78,10 @@ Finally, we have added a tach disable function that turns off the tach measurement system for individual tachs in order to save power. That is in register 75h. --- +-------------------------------------------------------------------------- + aSC7621 Product Description +=========================== The aSC7621 has a two wire digital interface compatible with SMBus 2.0. Using a 10-bit ADC, the aSC7621 measures the temperature of two remote diode @@ -102,6 +109,8 @@ System voltages of VCCP, 2.5V, 3.3V, 5.0V, and 12V motherboard power are monitored efficiently with internal scaling resistors. Features +-------- + - Supports PECI interface and monitors internal and remote thermal diodes - 2-wire, SMBus 2.0 compliant, serial interface - 10-bit ADC @@ -110,7 +119,7 @@ Features - Noise filtering of temperature reading for fan speed control - 0.25C digital temperature sensor resolution - 3 PWM fan speed control outputs for 2-, 3- or 4-wire fans and up to 4 fan - tachometer inputs + tachometer inputs - Enhanced measured temperature to Temperature Zone assignment. - Provides high and low PWM frequency ranges - 3 GPIO pins for custom use @@ -123,17 +132,20 @@ Except where noted below, the sysfs entries created by this driver follow the standards defined in "sysfs-interface". temp1_source + = =============================================== 0 (default) peci_legacy = 0, Remote 1 Temperature - peci_legacy = 1, PECI Processor Temperature 0 + peci_legacy = 1, PECI Processor Temperature 0 1 Remote 1 Temperature 2 Remote 2 Temperature 3 Internal Temperature 4 PECI Processor Temperature 0 5 PECI Processor Temperature 1 6 PECI Processor Temperature 2 - 7 PECI Processor Temperature 3 + 7 PECI Processor Temperature 3 + = =============================================== temp2_source + = =============================================== 0 (default) Internal Temperature 1 Remote 1 Temperature 2 Remote 2 Temperature @@ -142,8 +154,10 @@ temp2_source 5 PECI Processor Temperature 1 6 PECI Processor Temperature 2 7 PECI Processor Temperature 3 + = =============================================== temp3_source + = =============================================== 0 (default) Remote 2 Temperature 1 Remote 1 Temperature 2 Remote 2 Temperature @@ -152,10 +166,12 @@ temp3_source 5 PECI Processor Temperature 1 6 PECI Processor Temperature 2 7 PECI Processor Temperature 3 + = =============================================== temp4_source + = =============================================== 0 (default) peci_legacy = 0, PECI Processor Temperature 0 - peci_legacy = 1, Remote 1 Temperature + peci_legacy = 1, Remote 1 Temperature 1 Remote 1 Temperature 2 Remote 2 Temperature 3 Internal Temperature @@ -163,58 +179,65 @@ temp4_source 5 PECI Processor Temperature 1 6 PECI Processor Temperature 2 7 PECI Processor Temperature 3 + = =============================================== -temp[1-4]_smoothing_enable -temp[1-4]_smoothing_time +temp[1-4]_smoothing_enable / temp[1-4]_smoothing_time Smooths spikes in temp readings caused by noise. Valid values in milliseconds are: - 35000 - 17600 - 11800 - 7000 - 4400 - 3000 - 1600 - 800 + + * 35000 + * 17600 + * 11800 + * 7000 + * 4400 + * 3000 + * 1600 + * 800 temp[1-4]_crit When the corresponding zone temperature reaches this value, ALL pwm outputs will got to 100%. -temp[5-8]_input -temp[5-8]_enable +temp[5-8]_input / temp[5-8]_enable The aSC7621 can also read temperatures provided by the processor via the PECI bus. Usually these are "core" temps and are relative to the point where the automatic thermal control circuit starts throttling. This means that these are usually negative numbers. pwm[1-3]_enable + =============== ======================================================== 0 Fan off. 1 Fan on manual control. 2 Fan on automatic control and will run at the minimum pwm - if the temperature for the zone is below the minimum. - 3 Fan on automatic control but will be off if the temperature - for the zone is below the minimum. - 4-254 Ignored. + if the temperature for the zone is below the minimum. + 3 Fan on automatic control but will be off if the + temperature for the zone is below the minimum. + 4-254 Ignored. 255 Fan on full. + =============== ======================================================== pwm[1-3]_auto_channels Bitmap as described in sysctl-interface with the following exceptions... + Only the following combination of zones (and their corresponding masks) are valid: - 1 - 2 - 3 - 2,3 - 1,2,3 - 4 - 1,2,3,4 - Special values: - 0 Disabled. - 16 Fan on manual control. - 31 Fan on full. + * 1 + * 2 + * 3 + * 2,3 + * 1,2,3 + * 4 + * 1,2,3,4 + + * Special values: + + == ====================== + 0 Disabled. + 16 Fan on manual control. + 31 Fan on full. + == ====================== pwm[1-3]_invert @@ -226,22 +249,22 @@ pwm[1-3]_freq PWM frequency in Hz Valid values in Hz are: - 10 - 15 - 23 - 30 (default) - 38 - 47 - 62 - 94 - 23000 - 24000 - 25000 - 26000 - 27000 - 28000 - 29000 - 30000 + * 10 + * 15 + * 23 + * 30 (default) + * 38 + * 47 + * 62 + * 94 + * 23000 + * 24000 + * 25000 + * 26000 + * 27000 + * 28000 + * 29000 + * 30000 Setting any other value will be ignored. @@ -251,17 +274,17 @@ peci_enable peci_avg Input filter average time. - 0 0 Sec. (no Smoothing) (default) - 1 0.25 Sec. - 2 0.5 Sec. - 3 1.0 Sec. - 4 2.0 Sec. - 5 4.0 Sec. - 6 8.0 Sec. - 7 0.0 Sec. + * 0 0 Sec. (no Smoothing) (default) + * 1 0.25 Sec. + * 2 0.5 Sec. + * 3 1.0 Sec. + * 4 2.0 Sec. + * 5 4.0 Sec. + * 6 8.0 Sec. + * 7 0.0 Sec. peci_legacy - + = ============================================ 0 Standard Mode (default) Remote Diode 1 reading is associated with Temperature Zone 1, PECI is associated with @@ -270,10 +293,12 @@ peci_legacy 1 Legacy Mode PECI is associated with Temperature Zone 1, Remote Diode 1 is associated with Zone 4 + = ============================================ peci_diode Diode filter + = ==================== 0 0.25 Sec. 1 1.1 Sec. 2 2.4 Sec. (default) @@ -282,15 +307,20 @@ peci_diode 5 6.8 Sec. 6 10.2 Sec. 7 16.4 Sec. + = ==================== peci_4domain Four domain enable + = =============================================== 0 1 or 2 Domains for enabled processors (default) 1 3 or 4 Domains for enabled processors + = =============================================== peci_domain Domain + = ================================================== 0 Processor contains a single domain (0) (default) 1 Processor contains two domains (0,1) + = ================================================== diff --git a/Documentation/hwmon/aspeed-pwm-tacho b/Documentation/hwmon/aspeed-pwm-tacho.rst index 7cfb34977460..6dcec845fbc7 100644 --- a/Documentation/hwmon/aspeed-pwm-tacho +++ b/Documentation/hwmon/aspeed-pwm-tacho.rst @@ -15,8 +15,10 @@ 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/coretemp b/Documentation/hwmon/coretemp.rst index fec5a9bf755f..c609329e3bc4 100644 --- a/Documentation/hwmon/coretemp +++ b/Documentation/hwmon/coretemp.rst @@ -3,20 +3,29 @@ Kernel driver coretemp Supported chips: * All Intel Core family + Prefix: 'coretemp' - CPUID: family 0x6, models 0xe (Pentium M DC), 0xf (Core 2 DC 65nm), - 0x16 (Core 2 SC 65nm), 0x17 (Penryn 45nm), - 0x1a (Nehalem), 0x1c (Atom), 0x1e (Lynnfield), - 0x26 (Tunnel Creek Atom), 0x27 (Medfield Atom), - 0x36 (Cedar Trail Atom) - Datasheet: Intel 64 and IA-32 Architectures Software Developer's Manual - Volume 3A: System Programming Guide - http://softwarecommunity.intel.com/Wiki/Mobility/720.htm + + CPUID: family 0x6, models + + - 0xe (Pentium M DC), 0xf (Core 2 DC 65nm), + - 0x16 (Core 2 SC 65nm), 0x17 (Penryn 45nm), + - 0x1a (Nehalem), 0x1c (Atom), 0x1e (Lynnfield), + - 0x26 (Tunnel Creek Atom), 0x27 (Medfield Atom), + - 0x36 (Cedar Trail Atom) + + Datasheet: + + Intel 64 and IA-32 Architectures Software Developer's Manual + Volume 3A: System Programming Guide + + http://softwarecommunity.intel.com/Wiki/Mobility/720.htm Author: Rudolf Marek Description ----------- + This driver permits reading the DTS (Digital Temperature Sensor) embedded inside Intel CPUs. This driver can read both the per-core and per-package temperature using the appropriate sensors. The per-package sensor is new; @@ -35,14 +44,17 @@ may be raised, if the temperature grows enough (more than TjMax) to trigger the Out-Of-Spec bit. Following table summarizes the exported sysfs files: All Sysfs entries are named with their core_id (represented here by 'X'). -tempX_input - Core temperature (in millidegrees Celsius). -tempX_max - All cooling devices should be turned on (on Core2). -tempX_crit - Maximum junction temperature (in millidegrees Celsius). -tempX_crit_alarm - Set when Out-of-spec bit is set, never clears. - Correct CPU operation is no longer guaranteed. -tempX_label - Contains string "Core X", where X is processor - number. For Package temp, this will be "Physical id Y", - where Y is the package number. + +================= ======================================================== +tempX_input Core temperature (in millidegrees Celsius). +tempX_max All cooling devices should be turned on (on Core2). +tempX_crit Maximum junction temperature (in millidegrees Celsius). +tempX_crit_alarm Set when Out-of-spec bit is set, never clears. + Correct CPU operation is no longer guaranteed. +tempX_label Contains string "Core X", where X is processor + number. For Package temp, this will be "Physical id Y", + where Y is the package number. +================= ======================================================== On CPU models which support it, TjMax is read from a model-specific register. On other models, it is set to an arbitrary value based on weak heuristics. @@ -52,6 +64,7 @@ as a module parameter (tjmax). Appendix A. Known TjMax lists (TBD): Some information comes from ark.intel.com +=============== =============================================== ================ Process Processor TjMax(C) 22nm Core i5/i7 Processors @@ -179,3 +192,4 @@ Process Processor TjMax(C) 65nm Celeron Processors T1700/1600 100 560/550/540/530 100 +=============== =============================================== ================ diff --git a/Documentation/hwmon/da9052 b/Documentation/hwmon/da9052.rst index 5bc51346b689..c1c0f1f08904 100644 --- a/Documentation/hwmon/da9052 +++ b/Documentation/hwmon/da9052.rst @@ -1,6 +1,12 @@ +Kernel driver da9052 +==================== + Supported chips: + * Dialog Semiconductors DA9052-BC and DA9053-AA/Bx PMICs + Prefix: 'da9052' + Datasheet: Datasheet is not publicly available. Authors: David Dajun Chen <dchen@diasemi.com> @@ -15,17 +21,20 @@ different inputs. The track and hold circuit ensures stable input voltages at the input of the ADC during the conversion. The ADC is used to measure the following inputs: -Channel 0: VDDOUT - measurement of the system voltage -Channel 1: ICH - internal battery charger current measurement -Channel 2: TBAT - output from the battery NTC -Channel 3: VBAT - measurement of the battery voltage -Channel 4: ADC_IN4 - high impedance input (0 - 2.5V) -Channel 5: ADC_IN5 - high impedance input (0 - 2.5V) -Channel 6: ADC_IN6 - high impedance input (0 - 2.5V) -Channel 7: XY - TSI interface to measure the X and Y voltage of the touch - screen resistive potentiometers -Channel 8: Internal Tjunc. - sense (internal temp. sensor) -Channel 9: VBBAT - measurement of the backup battery voltage + +========= =================================================================== +Channel 0 VDDOUT - measurement of the system voltage +Channel 1 ICH - internal battery charger current measurement +Channel 2 TBAT - output from the battery NTC +Channel 3 VBAT - measurement of the battery voltage +Channel 4 ADC_IN4 - high impedance input (0 - 2.5V) +Channel 5 ADC_IN5 - high impedance input (0 - 2.5V) +Channel 6 ADC_IN6 - high impedance input (0 - 2.5V) +Channel 7 XY - TSI interface to measure the X and Y voltage of the touch + screen resistive potentiometers +Channel 8 Internal Tjunc. - sense (internal temp. sensor) +Channel 9 VBBAT - measurement of the backup battery voltage +========= =================================================================== By using sysfs attributes we can measure the system voltage VDDOUT, the battery charging current ICH, battery temperature TBAT, battery junction temperature @@ -37,12 +46,15 @@ Voltage Monitoring Voltages are sampled by a 10 bit ADC. The battery voltage is calculated as: + Milli volt = ((ADC value * 1000) / 512) + 2500 The backup battery voltage is calculated as: + Milli volt = (ADC value * 2500) / 512; The voltages on ADC channels 4, 5 and 6 are calculated as: + Milli volt = (ADC value * 2500) / 1023 Temperature Monitoring @@ -52,10 +64,15 @@ Temperatures are sampled by a 10 bit ADC. Junction and battery temperatures are monitored by the ADC channels. The junction temperature is calculated: + Degrees celsius = 1.708 * (TJUNC_RES - T_OFFSET) - 108.8 + The junction temperature attribute is supported by the driver. The battery temperature is calculated: - Degree Celsius = 1 / (t1 + 1/298)- 273 + + Degree Celsius = 1 / (t1 + 1/298) - 273 + where t1 = (1/B)* ln(( ADCval * 2.5)/(R25*ITBAT*255)) + Default values of R25, B, ITBAT are 10e3, 3380 and 50e-6 respectively. diff --git a/Documentation/hwmon/da9055 b/Documentation/hwmon/da9055.rst index 855c3f536e00..beae271a3312 100644 --- a/Documentation/hwmon/da9055 +++ b/Documentation/hwmon/da9055.rst @@ -1,6 +1,11 @@ +Kernel driver da9055 +==================== + Supported chips: * Dialog Semiconductors DA9055 PMIC + Prefix: 'da9055' + Datasheet: Datasheet is not publicly available. Authors: David Dajun Chen <dchen@diasemi.com> @@ -15,11 +20,12 @@ different inputs. The track and hold circuit ensures stable input voltages at the input of the ADC during the conversion. The ADC is used to measure the following inputs: -Channel 0: VDDOUT - measurement of the system voltage -Channel 1: ADC_IN1 - high impedance input (0 - 2.5V) -Channel 2: ADC_IN2 - high impedance input (0 - 2.5V) -Channel 3: ADC_IN3 - high impedance input (0 - 2.5V) -Channel 4: Internal Tjunc. - sense (internal temp. sensor) + +- Channel 0: VDDOUT - measurement of the system voltage +- Channel 1: ADC_IN1 - high impedance input (0 - 2.5V) +- Channel 2: ADC_IN2 - high impedance input (0 - 2.5V) +- Channel 3: ADC_IN3 - high impedance input (0 - 2.5V) +- Channel 4: Internal Tjunc. - sense (internal temp. sensor) By using sysfs attributes we can measure the system voltage VDDOUT, chip junction temperature and auxiliary channels voltages. @@ -31,9 +37,11 @@ Voltages are sampled in a AUTO mode it can be manually sampled too and results are stored in a 10 bit ADC. The system voltage is calculated as: + Milli volt = ((ADC value * 1000) / 85) + 2500 The voltages on ADC channels 1, 2 and 3 are calculated as: + Milli volt = (ADC value * 1000) / 102 Temperature Monitoring @@ -43,5 +51,7 @@ Temperatures are sampled by a 10 bit ADC. Junction temperatures are monitored by the ADC channels. The junction temperature is calculated: + Degrees celsius = -0.4084 * (ADC_RES - T_OFFSET) + 307.6332 + The junction temperature attribute is supported by the driver. diff --git a/Documentation/hwmon/dme1737 b/Documentation/hwmon/dme1737.rst index 4d2935145a1c..82fcbc6b2b43 100644 --- a/Documentation/hwmon/dme1737 +++ b/Documentation/hwmon/dme1737.rst @@ -2,21 +2,37 @@ Kernel driver dme1737 ===================== Supported chips: + * SMSC DME1737 and compatibles (like Asus A8000) + Prefix: 'dme1737' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: Provided by SMSC upon request and under NDA + * SMSC SCH3112, SCH3114, SCH3116 + Prefix: 'sch311x' + Addresses scanned: none, address read from Super-I/O config space + Datasheet: Available on the Internet + * SMSC SCH5027 + Prefix: 'sch5027' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: Provided by SMSC upon request and under NDA + * SMSC SCH5127 + Prefix: 'sch5127' + Addresses scanned: none, address read from Super-I/O config space + Datasheet: Provided by SMSC upon request and under NDA Authors: @@ -26,11 +42,14 @@ Authors: Module Parameters ----------------- -* force_start: bool Enables the monitoring of voltage, fan and temp inputs +* force_start: bool + Enables the monitoring of voltage, fan and temp inputs and PWM output control functions. Using this parameter shouldn't be required since the BIOS usually takes care of this. -* probe_all_addr: bool Include non-standard LPC addresses 0x162e and 0x164e + +* probe_all_addr: bool + Include non-standard LPC addresses 0x162e and 0x164e when probing for ISA devices. This is required for the following boards: - VIA EPIA SN18000 @@ -70,7 +89,8 @@ scaling resistors. The values returned by the driver therefore reflect true millivolts and don't need scaling. The voltage inputs are mapped as follows (the last column indicates the input ranges): -DME1737, A8000: +DME1737, A8000:: + in0: +5VTR (+5V standby) 0V - 6.64V in1: Vccp (processor core) 0V - 3V in2: VCC (internal +3.3V) 0V - 4.38V @@ -79,7 +99,8 @@ DME1737, A8000: in5: VTR (+3.3V standby) 0V - 4.38V in6: Vbat (+3.0V) 0V - 4.38V -SCH311x: +SCH311x:: + in0: +2.5V 0V - 3.32V in1: Vccp (processor core) 0V - 2V in2: VCC (internal +3.3V) 0V - 4.38V @@ -88,7 +109,8 @@ SCH311x: in5: VTR (+3.3V standby) 0V - 4.38V in6: Vbat (+3.0V) 0V - 4.38V -SCH5027: +SCH5027:: + in0: +5VTR (+5V standby) 0V - 6.64V in1: Vccp (processor core) 0V - 3V in2: VCC (internal +3.3V) 0V - 4.38V @@ -97,7 +119,8 @@ SCH5027: in5: VTR (+3.3V standby) 0V - 4.38V in6: Vbat (+3.0V) 0V - 4.38V -SCH5127: +SCH5127:: + in0: +2.5 0V - 3.32V in1: Vccp (processor core) 0V - 3V in2: VCC (internal +3.3V) 0V - 4.38V @@ -119,7 +142,7 @@ Celsius. The chip also features offsets for all 3 temperature inputs which - when programmed - get added to the input readings. The chip does all the scaling by itself and the driver therefore reports true temperatures that don't need any user-space adjustments. The temperature inputs are mapped as follows -(the last column indicates the input ranges): +(the last column indicates the input ranges):: temp1: Remote diode 1 (3904 type) temperature -127C - +127C temp2: DME1737 internal temperature -127C - +127C @@ -171,6 +194,7 @@ pwm[1-3]_auto_pwm_min, respectively. The thermal thresholds of the zones are programmed via zone[1-3]_auto_point[1-3]_temp and zone[1-3]_auto_point1_temp_hyst: + =============================== ======================================= pwm[1-3]_auto_point2_pwm full-speed duty-cycle (255, i.e., 100%) pwm[1-3]_auto_point1_pwm low-speed duty-cycle pwm[1-3]_auto_pwm_min min-speed duty-cycle @@ -179,6 +203,7 @@ zone[1-3]_auto_point1_temp_hyst: zone[1-3]_auto_point2_temp full-speed temp zone[1-3]_auto_point1_temp low-speed temp zone[1-3]_auto_point1_temp_hyst min-speed temp + =============================== ======================================= The chip adjusts the output duty-cycle linearly in the range of auto_point1_pwm to auto_point2_pwm if the temperature of the associated zone is between @@ -192,17 +217,21 @@ all PWM outputs are set to 100% duty-cycle. Following is another representation of how the chip sets the output duty-cycle based on the temperature of the associated thermal zone: - Duty-Cycle Duty-Cycle - Temperature Rising Temp Falling Temp - ----------- ----------- ------------ + =============== =============== ================= + Temperature Duty-Cycle Duty-Cycle + Rising Temp Falling Temp + =============== =============== ================= full-speed full-speed full-speed - < linearly adjusted duty-cycle > + - < linearly - + adjusted + duty-cycle > low-speed low-speed low-speed - min-speed low-speed + - min-speed low-speed min-speed min-speed min-speed - min-speed min-speed + - min-speed min-speed + =============== =============== ================= Sysfs Attributes @@ -211,8 +240,9 @@ Sysfs Attributes Following is a list of all sysfs attributes that the driver provides, their permissions and a short description: +=============================== ======= ======================================= Name Perm Description ----- ---- ----------- +=============================== ======= ======================================= cpu0_vid RO CPU core reference voltage in millivolts. vrm RW Voltage regulator module version @@ -242,9 +272,10 @@ temp[1-3]_fault RO Temp input fault. Returns 1 if the chip zone[1-3]_auto_channels_temp RO Temperature zone to temperature input mapping. This attribute is a bitfield and supports the following values: - 1: temp1 - 2: temp2 - 4: temp3 + + - 1: temp1 + - 2: temp2 + - 4: temp3 zone[1-3]_auto_point1_temp_hyst RW Auto PWM temp point1 hysteresis. The output of the corresponding PWM is set to the pwm_auto_min value if the temp @@ -275,9 +306,10 @@ pmw[1-3,5-6] RO/RW Duty-cycle of PWM output. Supported manual mode. pwm[1-3]_enable RW Enable of PWM outputs 1-3. Supported values are: - 0: turned off (output @ 100%) - 1: manual mode - 2: automatic mode + + - 0: turned off (output @ 100%) + - 1: manual mode + - 2: automatic mode pwm[5-6]_enable RO Enable of PWM outputs 5-6. Always returns 1 since these 2 outputs are hard-wired to manual mode. @@ -294,11 +326,12 @@ pmw[1-3]_ramp_rate RW Ramp rate of PWM output. Determines how pwm[1-3]_auto_channels_zone RW PWM output to temperature zone mapping. This attribute is a bitfield and supports the following values: - 1: zone1 - 2: zone2 - 4: zone3 - 6: highest of zone[2-3] - 7: highest of zone[1-3] + + - 1: zone1 + - 2: zone2 + - 4: zone3 + - 6: highest of zone[2-3] + - 7: highest of zone[1-3] pwm[1-3]_auto_pwm_min RW Auto PWM min pwm. Minimum PWM duty- cycle. Supported values are 0 or auto_point1_pwm. @@ -307,12 +340,14 @@ pwm[1-3]_auto_point1_pwm RW Auto PWM pwm point. Auto_point1 is the pwm[1-3]_auto_point2_pwm RO Auto PWM pwm point. Auto_point2 is the full-speed duty-cycle which is hard- wired to 255 (100% duty-cycle). +=============================== ======= ======================================= Chip Differences ---------------- +======================= ======= ======= ======= ======= Feature dme1737 sch311x sch5027 sch5127 -------------------------------------------------------- +======================= ======= ======= ======= ======= temp[1-3]_offset yes yes vid yes zone3 yes yes yes @@ -326,3 +361,4 @@ pwm5 opt opt fan6 opt opt pwm6 opt opt in7 yes +======================= ======= ======= ======= ======= diff --git a/Documentation/hwmon/ds1621 b/Documentation/hwmon/ds1621.rst index fa3407997795..552b37e9dd34 100644 --- a/Documentation/hwmon/ds1621 +++ b/Documentation/hwmon/ds1621.rst @@ -2,42 +2,61 @@ Kernel driver ds1621 ==================== Supported chips: + * Dallas Semiconductor / Maxim Integrated DS1621 + Prefix: 'ds1621' + Addresses scanned: none + Datasheet: Publicly available from www.maximintegrated.com * Dallas Semiconductor DS1625 + Prefix: 'ds1625' + Addresses scanned: none + Datasheet: Publicly available from www.datasheetarchive.com * Maxim Integrated DS1631 + Prefix: 'ds1631' + Addresses scanned: none + Datasheet: Publicly available from www.maximintegrated.com * Maxim Integrated DS1721 + Prefix: 'ds1721' + Addresses scanned: none + Datasheet: Publicly available from www.maximintegrated.com * Maxim Integrated DS1731 + Prefix: 'ds1731' + Addresses scanned: none + Datasheet: Publicly available from www.maximintegrated.com Authors: - Christian W. Zuckschwerdt <zany@triq.net> - valuable contributions by Jan M. Sendler <sendler@sendler.de> - ported to 2.6 by Aurelien Jarno <aurelien@aurel32.net> - with the help of Jean Delvare <jdelvare@suse.de> + - Christian W. Zuckschwerdt <zany@triq.net> + - valuable contributions by Jan M. Sendler <sendler@sendler.de> + - ported to 2.6 by Aurelien Jarno <aurelien@aurel32.net> + with the help of Jean Delvare <jdelvare@suse.de> Module Parameters ------------------ * polarity int - Output's polarity: 0 = active high, 1 = active low + Output's polarity: + + * 0 = active high, + * 1 = active low Description ----------- @@ -87,28 +106,31 @@ are used internally, however, these flags do get set and cleared as the actual temperature crosses the min or max settings (which by default are set to 75 and 80 degrees respectively). -Temperature Conversion: ------------------------ -DS1621 - 750ms (older devices may take up to 1000ms) -DS1625 - 500ms -DS1631 - 93ms..750ms for 9..12 bits resolution, respectively. -DS1721 - 93ms..750ms for 9..12 bits resolution, respectively. -DS1731 - 93ms..750ms for 9..12 bits resolution, respectively. +Temperature Conversion +---------------------- + +- DS1621 - 750ms (older devices may take up to 1000ms) +- DS1625 - 500ms +- DS1631 - 93ms..750ms for 9..12 bits resolution, respectively. +- DS1721 - 93ms..750ms for 9..12 bits resolution, respectively. +- DS1731 - 93ms..750ms for 9..12 bits resolution, respectively. Note: On the DS1621, internal access to non-volatile registers may last for 10ms or less (unverified on the other devices). -Temperature Accuracy: ---------------------- -DS1621: +/- 0.5 degree Celsius (from 0 to +70 degrees) -DS1625: +/- 0.5 degree Celsius (from 0 to +70 degrees) -DS1631: +/- 0.5 degree Celsius (from 0 to +70 degrees) -DS1721: +/- 1.0 degree Celsius (from -10 to +85 degrees) -DS1731: +/- 1.0 degree Celsius (from -10 to +85 degrees) +Temperature Accuracy +-------------------- -Note: -Please refer to the device datasheets for accuracy at other temperatures. +- DS1621: +/- 0.5 degree Celsius (from 0 to +70 degrees) +- DS1625: +/- 0.5 degree Celsius (from 0 to +70 degrees) +- DS1631: +/- 0.5 degree Celsius (from 0 to +70 degrees) +- DS1721: +/- 1.0 degree Celsius (from -10 to +85 degrees) +- DS1731: +/- 1.0 degree Celsius (from -10 to +85 degrees) + +.. Note:: + + Please refer to the device datasheets for accuracy at other temperatures. Temperature Resolution: ----------------------- @@ -117,60 +139,67 @@ support, which is achieved via the R0 and R1 config register bits, where: R0..R1 ------ - 0 0 => 9 bits, 0.5 degrees Celsius - 1 0 => 10 bits, 0.25 degrees Celsius - 0 1 => 11 bits, 0.125 degrees Celsius - 1 1 => 12 bits, 0.0625 degrees Celsius -Note: -At initial device power-on, the default resolution is set to 12-bits. +== == =============================== +R0 R1 +== == =============================== + 0 0 9 bits, 0.5 degrees Celsius + 1 0 10 bits, 0.25 degrees Celsius + 0 1 11 bits, 0.125 degrees Celsius + 1 1 12 bits, 0.0625 degrees Celsius +== == =============================== + +.. Note:: + + At initial device power-on, the default resolution is set to 12-bits. The resolution mode for the DS1631, DS1721, or DS1731 can be changed from userspace, via the device 'update_interval' sysfs attribute. This attribute will normalize the range of input values to the device maximum resolution values defined in the datasheet as follows: +============= ================== =============== Resolution Conversion Time Input Range (C/LSB) (msec) (msec) ------------------------------------------------- +============= ================== =============== 0.5 93.75 0....94 0.25 187.5 95...187 0.125 375 188..375 0.0625 750 376..infinity ------------------------------------------------- +============= ================== =============== The following examples show how the 'update_interval' attribute can be -used to change the conversion time: - -$ cat update_interval -750 -$ cat temp1_input -22062 -$ -$ echo 300 > update_interval -$ cat update_interval -375 -$ cat temp1_input -22125 -$ -$ echo 150 > update_interval -$ cat update_interval -188 -$ cat temp1_input -22250 -$ -$ echo 1 > update_interval -$ cat update_interval -94 -$ cat temp1_input -22000 -$ -$ echo 1000 > update_interval -$ cat update_interval -750 -$ cat temp1_input -22062 -$ +used to change the conversion time:: + + $ cat update_interval + 750 + $ cat temp1_input + 22062 + $ + $ echo 300 > update_interval + $ cat update_interval + 375 + $ cat temp1_input + 22125 + $ + $ echo 150 > update_interval + $ cat update_interval + 188 + $ cat temp1_input + 22250 + $ + $ echo 1 > update_interval + $ cat update_interval + 94 + $ cat temp1_input + 22000 + $ + $ echo 1000 > update_interval + $ cat update_interval + 750 + $ cat temp1_input + 22062 + $ As shown, the ds1621 driver automatically adjusts the 'update_interval' user input, via a step function. Reading back the 'update_interval' value @@ -182,6 +211,7 @@ via the following function: g(x) = 0.5 * [minimum_conversion_time/x] where: - -> 'x' = the output from 'update_interval' - -> 'g(x)' = the resolution in degrees C per LSB. - -> 93.75ms = minimum conversion time + + - 'x' = the output from 'update_interval' + - 'g(x)' = the resolution in degrees C per LSB. + - 93.75ms = minimum conversion time diff --git a/Documentation/hwmon/ds620 b/Documentation/hwmon/ds620.rst index 1fbe3cd916cc..2d686b17b547 100644 --- a/Documentation/hwmon/ds620 +++ b/Documentation/hwmon/ds620.rst @@ -2,15 +2,19 @@ Kernel driver ds620 =================== Supported chips: + * Dallas Semiconductor DS620 + Prefix: 'ds620' + Datasheet: Publicly available at the Dallas Semiconductor website - http://www.dalsemi.com/ + + http://www.dalsemi.com/ Authors: - Roland Stigge <stigge@antcom.de> - based on ds1621.c by - Christian W. Zuckschwerdt <zany@triq.net> + Roland Stigge <stigge@antcom.de> + based on ds1621.c by + Christian W. Zuckschwerdt <zany@triq.net> Description ----------- diff --git a/Documentation/hwmon/emc1403 b/Documentation/hwmon/emc1403.rst index a869b0ef6a9d..3a4913b63ef3 100644 --- a/Documentation/hwmon/emc1403 +++ b/Documentation/hwmon/emc1403.rst @@ -2,28 +2,48 @@ Kernel driver emc1403 ===================== Supported chips: + * SMSC / Microchip EMC1402, EMC1412 + Addresses scanned: I2C 0x18, 0x1c, 0x29, 0x4c, 0x4d, 0x5c + Prefix: 'emc1402' + Datasheets: - http://ww1.microchip.com/downloads/en/DeviceDoc/1412.pdf - http://ww1.microchip.com/downloads/en/DeviceDoc/1402.pdf + + - http://ww1.microchip.com/downloads/en/DeviceDoc/1412.pdf + - http://ww1.microchip.com/downloads/en/DeviceDoc/1402.pdf + * SMSC / Microchip EMC1403, EMC1404, EMC1413, EMC1414 + Addresses scanned: I2C 0x18, 0x29, 0x4c, 0x4d + Prefix: 'emc1403', 'emc1404' + Datasheets: - http://ww1.microchip.com/downloads/en/DeviceDoc/1403_1404.pdf - http://ww1.microchip.com/downloads/en/DeviceDoc/1413_1414.pdf + + - http://ww1.microchip.com/downloads/en/DeviceDoc/1403_1404.pdf + - http://ww1.microchip.com/downloads/en/DeviceDoc/1413_1414.pdf + * SMSC / Microchip EMC1422 + Addresses scanned: I2C 0x4c + Prefix: 'emc1422' + Datasheet: - http://ww1.microchip.com/downloads/en/DeviceDoc/1422.pdf + + - http://ww1.microchip.com/downloads/en/DeviceDoc/1422.pdf + * SMSC / Microchip EMC1423, EMC1424 + Addresses scanned: I2C 0x4c + Prefix: 'emc1423', 'emc1424' + Datasheet: - http://ww1.microchip.com/downloads/en/DeviceDoc/1423_1424.pdf + + - http://ww1.microchip.com/downloads/en/DeviceDoc/1423_1424.pdf Author: Kalhan Trisal <kalhan.trisal@intel.com @@ -46,6 +66,7 @@ difference between the limit and its hysteresis is always the same for all three limits. This implementation detail implies the following: + * When setting a limit, its hysteresis will automatically follow, the difference staying unchanged. For example, if the old critical limit was 80 degrees C, and the hysteresis was 75 degrees C, and you change diff --git a/Documentation/hwmon/emc2103 b/Documentation/hwmon/emc2103.rst index a12b2c127140..6a6ca6d1b34e 100644 --- a/Documentation/hwmon/emc2103 +++ b/Documentation/hwmon/emc2103.rst @@ -2,13 +2,17 @@ Kernel driver emc2103 ====================== Supported chips: + * SMSC EMC2103 + Addresses scanned: I2C 0x2e + Prefix: 'emc2103' + Datasheet: Not public Authors: - Steve Glendinning <steve.glendinning@smsc.com> + Steve Glendinning <steve.glendinning@smsc.com> Description ----------- diff --git a/Documentation/hwmon/emc6w201 b/Documentation/hwmon/emc6w201.rst index 757629b12897..a8e1185b9bb6 100644 --- a/Documentation/hwmon/emc6w201 +++ b/Documentation/hwmon/emc6w201.rst @@ -2,9 +2,13 @@ Kernel driver emc6w201 ====================== Supported chips: + * SMSC EMC6W201 + Prefix: 'emc6w201' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: Not public Author: Jean Delvare <jdelvare@suse.de> @@ -38,5 +42,6 @@ Known Systems With EMC6W201 The EMC6W201 is a rare device, only found on a few systems, made in 2005 and 2006. Known systems with this device: + * Dell Precision 670 workstation * Gigabyte 2CEWH mainboard diff --git a/Documentation/hwmon/f71805f b/Documentation/hwmon/f71805f.rst index 48a356084bc6..1efe5e5d337c 100644 --- a/Documentation/hwmon/f71805f +++ b/Documentation/hwmon/f71805f.rst @@ -2,17 +2,29 @@ Kernel driver f71805f ===================== Supported chips: + * Fintek F71805F/FG + Prefix: 'f71805f' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71806F/FG + Prefix: 'f71872f' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71872F/FG + Prefix: 'f71872f' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website Author: Jean Delvare <jdelvare@suse.de> @@ -64,24 +76,26 @@ you can only set the limits in steps of 32 mV (before scaling). The wirings and resistor values suggested by Fintek are as follow: - pin expected - name use R1 R2 divider raw val. - +======= ======= =========== ==== ======= ============ ============== +in pin expected + name use R1 R2 divider raw val. +======= ======= =========== ==== ======= ============ ============== in0 VCC VCC3.3V int. int. 2.00 1.65 V in1 VIN1 VTT1.2V 10K - 1.00 1.20 V -in2 VIN2 VRAM 100K 100K 2.00 ~1.25 V (1) -in3 VIN3 VCHIPSET 47K 100K 1.47 2.24 V (2) +in2 VIN2 VRAM 100K 100K 2.00 ~1.25 V [1]_ +in3 VIN3 VCHIPSET 47K 100K 1.47 2.24 V [2]_ in4 VIN4 VCC5V 200K 47K 5.25 0.95 V in5 VIN5 +12V 200K 20K 11.00 1.05 V in6 VIN6 VCC1.5V 10K - 1.00 1.50 V -in7 VIN7 VCORE 10K - 1.00 ~1.40 V (1) +in7 VIN7 VCORE 10K - 1.00 ~1.40 V [1]_ in8 VIN8 VSB5V 200K 47K 1.00 0.95 V -in10 VSB VSB3.3V int. int. 2.00 1.65 V (3) -in9 VBAT VBATTERY int. int. 2.00 1.50 V (3) +in10 VSB VSB3.3V int. int. 2.00 1.65 V [3]_ +in9 VBAT VBATTERY int. int. 2.00 1.50 V [3]_ +======= ======= =========== ==== ======= ============ ============== -(1) Depends on your hardware setup. -(2) Obviously not correct, swapping R1 and R2 would make more sense. -(3) F71872F/FG only. +.. [1] Depends on your hardware setup. +.. [2] Obviously not correct, swapping R1 and R2 would make more sense. +.. [3] F71872F/FG only. These values can be used as hints at best, as motherboard manufacturers are free to use a completely different setup. As a matter of fact, the diff --git a/Documentation/hwmon/f71882fg b/Documentation/hwmon/f71882fg.rst index 4c3cb8377d74..5c0b7b0db150 100644 --- a/Documentation/hwmon/f71882fg +++ b/Documentation/hwmon/f71882fg.rst @@ -2,60 +2,114 @@ Kernel driver f71882fg ====================== Supported chips: + * Fintek F71808E + Prefix: 'f71808e' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Not public + * Fintek F71808A + Prefix: 'f71808a' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Not public + * Fintek F71858FG + Prefix: 'f71858fg' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71862FG and F71863FG + Prefix: 'f71862fg' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71869F and F71869E + Prefix: 'f71869' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71869A + Prefix: 'f71869a' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Not public + * Fintek F71882FG and F71883FG + Prefix: 'f71882fg' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71889FG + Prefix: 'f71889fg' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website + * Fintek F71889ED + Prefix: 'f71889ed' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Should become available on the Fintek website soon + * Fintek F71889A + Prefix: 'f71889a' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Should become available on the Fintek website soon + * Fintek F8000 + Prefix: 'f8000' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Not public + * Fintek F81801U + Prefix: 'f71889fg' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Not public - Note: This is the 64-pin variant of the F71889FG, they have the + + Note: + This is the 64-pin variant of the F71889FG, they have the same device ID and are fully compatible as far as hardware monitoring is concerned. + * Fintek F81865F + Prefix: 'f81865f' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Available from the Fintek website Author: Hans de Goede <hdegoede@redhat.com> diff --git a/Documentation/hwmon/fam15h_power b/Documentation/hwmon/fam15h_power.rst index fb594c281c46..fdde632c93a3 100644 --- a/Documentation/hwmon/fam15h_power +++ b/Documentation/hwmon/fam15h_power.rst @@ -2,15 +2,20 @@ Kernel driver fam15h_power ========================== Supported chips: + * AMD Family 15h Processors + * AMD Family 16h Processors Prefix: 'fam15h_power' + Addresses scanned: PCI space + Datasheets: - BIOS and Kernel Developer's Guide (BKDG) For AMD Family 15h Processors - BIOS and Kernel Developer's Guide (BKDG) For AMD Family 16h Processors - AMD64 Architecture Programmer's Manual Volume 2: System Programming + + - BIOS and Kernel Developer's Guide (BKDG) For AMD Family 15h Processors + - BIOS and Kernel Developer's Guide (BKDG) For AMD Family 16h Processors + - AMD64 Architecture Programmer's Manual Volume 2: System Programming Author: Andreas Herrmann <herrmann.der.user@googlemail.com> @@ -31,14 +36,19 @@ For AMD Family 15h and 16h processors the following power values can be calculated using different processor northbridge function registers: -* BasePwrWatts: Specifies in watts the maximum amount of power - consumed by the processor for NB and logic external to the core. -* ProcessorPwrWatts: Specifies in watts the maximum amount of power - the processor can support. -* CurrPwrWatts: Specifies in watts the current amount of power being - consumed by the processor. +* BasePwrWatts: + Specifies in watts the maximum amount of power + consumed by the processor for NB and logic external to the core. + +* ProcessorPwrWatts: + Specifies in watts the maximum amount of power + the processor can support. +* CurrPwrWatts: + Specifies in watts the current amount of power being + consumed by the processor. This driver provides ProcessorPwrWatts and CurrPwrWatts: + * power1_crit (ProcessorPwrWatts) * power1_input (CurrPwrWatts) @@ -53,35 +63,53 @@ calculate the average power consumed by a processor during a measurement interval Tm. The feature of accumulated power mechanism is indicated by CPUID Fn8000_0007_EDX[12]. -* Tsample: compute unit power accumulator sample period -* Tref: the PTSC counter period -* PTSC: performance timestamp counter -* N: the ratio of compute unit power accumulator sample period to the - PTSC period -* Jmax: max compute unit accumulated power which is indicated by - MaxCpuSwPwrAcc MSR C001007b -* Jx/Jy: compute unit accumulated power which is indicated by - CpuSwPwrAcc MSR C001007a -* Tx/Ty: the value of performance timestamp counter which is indicated - by CU_PTSC MSR C0010280 -* PwrCPUave: CPU average power +* Tsample: + compute unit power accumulator sample period + +* Tref: + the PTSC counter period + +* PTSC: + performance timestamp counter + +* N: + the ratio of compute unit power accumulator sample period to the + PTSC period + +* Jmax: + max compute unit accumulated power which is indicated by + MaxCpuSwPwrAcc MSR C001007b + +* Jx/Jy: + compute unit accumulated power which is indicated by + CpuSwPwrAcc MSR C001007a +* Tx/Ty: + the value of performance timestamp counter which is indicated + by CU_PTSC MSR C0010280 + +* PwrCPUave: + CPU average power i. Determine the ratio of Tsample to Tref by executing CPUID Fn8000_0007. + N = value of CPUID Fn8000_0007_ECX[CpuPwrSampleTimeRatio[15:0]]. ii. Read the full range of the cumulative energy value from the new -MSR MaxCpuSwPwrAcc. + MSR MaxCpuSwPwrAcc. + Jmax = value returned. + iii. At time x, SW reads CpuSwPwrAcc MSR and samples the PTSC. - Jx = value read from CpuSwPwrAcc and Tx = value read from -PTSC. + + Jx = value read from CpuSwPwrAcc and Tx = value read from PTSC. iv. At time y, SW reads CpuSwPwrAcc MSR and samples the PTSC. - Jy = value read from CpuSwPwrAcc and Ty = value read from -PTSC. + + Jy = value read from CpuSwPwrAcc and Ty = value read from PTSC. v. Calculate the average power consumption for a compute unit over -time period (y-x). Unit of result is uWatt. + time period (y-x). Unit of result is uWatt:: + if (Jy < Jx) // Rollover has occurred Jdelta = (Jy + Jmax) - Jx else @@ -90,13 +118,14 @@ time period (y-x). Unit of result is uWatt. This driver provides PwrCPUave and interval(default is 10 millisecond and maximum is 1 second): + * power1_average (PwrCPUave) * power1_average_interval (Interval) The power1_average_interval can be updated at /etc/sensors3.conf file as below: -chip "fam15h_power-*" +chip `fam15h_power-*` set power1_average_interval 0.01 Then save it with "sensors -s". diff --git a/Documentation/hwmon/ftsteutates b/Documentation/hwmon/ftsteutates.rst index af54db92391b..58a2483d8d0d 100644 --- a/Documentation/hwmon/ftsteutates +++ b/Documentation/hwmon/ftsteutates.rst @@ -1,9 +1,12 @@ Kernel driver ftsteutates -===================== +========================= Supported chips: + * FTS Teutates + Prefix: 'ftsteutates' + Addresses scanned: I2C 0x73 (7-Bit) Author: Thilo Cestonaro <thilo.cestonaro@ts.fujitsu.com> @@ -11,6 +14,7 @@ Author: Thilo Cestonaro <thilo.cestonaro@ts.fujitsu.com> Description ----------- + The BMC Teutates is the Eleventh generation of Superior System monitoring and thermal management solution. It is builds on the basic functionality of the BMC Theseus and contains several new features and @@ -19,9 +23,11 @@ enhancements. It can monitor up to 4 voltages, 16 temperatures and implemented in this driver. To clear a temperature or fan alarm, execute the following command with the -correct path to the alarm file: +correct path to the alarm file:: + echo 0 >XXXX_alarm Specification of the chip can be found here: -ftp://ftp.ts.fujitsu.com/pub/Mainboard-OEM-Sales/Services/Software&Tools/Linux_SystemMonitoring&Watchdog&GPIO/BMC-Teutates_Specification_V1.21.pdf -ftp://ftp.ts.fujitsu.com/pub/Mainboard-OEM-Sales/Services/Software&Tools/Linux_SystemMonitoring&Watchdog&GPIO/Fujitsu_mainboards-1-Sensors_HowTo-en-US.pdf + +- ftp://ftp.ts.fujitsu.com/pub/Mainboard-OEM-Sales/Services/Software&Tools/Linux_SystemMonitoring&Watchdog&GPIO/BMC-Teutates_Specification_V1.21.pdf +- ftp://ftp.ts.fujitsu.com/pub/Mainboard-OEM-Sales/Services/Software&Tools/Linux_SystemMonitoring&Watchdog&GPIO/Fujitsu_mainboards-1-Sensors_HowTo-en-US.pdf diff --git a/Documentation/hwmon/g760a b/Documentation/hwmon/g760a.rst index cfc894537061..d82952cc8319 100644 --- a/Documentation/hwmon/g760a +++ b/Documentation/hwmon/g760a.rst @@ -2,9 +2,13 @@ Kernel driver g760a =================== Supported chips: + * Global Mixed-mode Technology Inc. G760A + Prefix: 'g760a' + Datasheet: Publicly available at the GMT website + http://www.gmt.com.tw/product/datasheet/EDS-760A.pdf Author: Herbert Valerio Riedel <hvr@gnu.org> diff --git a/Documentation/hwmon/g762 b/Documentation/hwmon/g762.rst index 923db9c5b5bc..0371b3365c48 100644 --- a/Documentation/hwmon/g762 +++ b/Documentation/hwmon/g762.rst @@ -7,7 +7,7 @@ modes - PWM or DC - are supported by the device. For additional information, a detailed datasheet is available at http://natisbad.org/NAS/ref/GMT_EDS-762_763-080710-0.2.pdf. sysfs -bindings are described in Documentation/hwmon/sysfs-interface. +bindings are described in Documentation/hwmon/sysfs-interface.rst. The following entries are available to the user in a subdirectory of /sys/bus/i2c/drivers/g762/ to control the operation of the device. @@ -21,34 +21,43 @@ documented in Documentation/devicetree/bindings/hwmon/g762.txt or using a specific platform_data structure in board initialization file (see include/linux/platform_data/g762.h). - fan1_target: set desired fan speed. This only makes sense in closed-loop - fan speed control (i.e. when pwm1_enable is set to 2). + fan1_target: + set desired fan speed. This only makes sense in closed-loop + fan speed control (i.e. when pwm1_enable is set to 2). - fan1_input: provide current fan rotation value in RPM as reported by - the fan to the device. + fan1_input: + provide current fan rotation value in RPM as reported by + the fan to the device. - fan1_div: fan clock divisor. Supported value are 1, 2, 4 and 8. + fan1_div: + fan clock divisor. Supported value are 1, 2, 4 and 8. - fan1_pulses: number of pulses per fan revolution. Supported values - are 2 and 4. + fan1_pulses: + number of pulses per fan revolution. Supported values + are 2 and 4. - fan1_fault: reports fan failure, i.e. no transition on fan gear pin for - about 0.7s (if the fan is not voluntarily set off). + fan1_fault: + reports fan failure, i.e. no transition on fan gear pin for + about 0.7s (if the fan is not voluntarily set off). - fan1_alarm: in closed-loop control mode, if fan RPM value is 25% out - of the programmed value for over 6 seconds 'fan1_alarm' is - set to 1. + fan1_alarm: + in closed-loop control mode, if fan RPM value is 25% out + of the programmed value for over 6 seconds 'fan1_alarm' is + set to 1. - pwm1_enable: set current fan speed control mode i.e. 1 for manual fan - speed control (open-loop) via pwm1 described below, 2 for - automatic fan speed control (closed-loop) via fan1_target - above. + pwm1_enable: + set current fan speed control mode i.e. 1 for manual fan + speed control (open-loop) via pwm1 described below, 2 for + automatic fan speed control (closed-loop) via fan1_target + above. - pwm1_mode: set or get fan driving mode: 1 for PWM mode, 0 for DC mode. + pwm1_mode: + set or get fan driving mode: 1 for PWM mode, 0 for DC mode. - pwm1: get or set PWM fan control value in open-loop mode. This is an - integer value between 0 and 255. 0 stops the fan, 255 makes - it run at full speed. + pwm1: + get or set PWM fan control value in open-loop mode. This is an + integer value between 0 and 255. 0 stops the fan, 255 makes + it run at full speed. Both in PWM mode ('pwm1_mode' set to 1) and DC mode ('pwm1_mode' set to 0), when current fan speed control mode is open-loop ('pwm1_enable' set to 1), diff --git a/Documentation/hwmon/gl518sm b/Documentation/hwmon/gl518sm.rst index 494bb55b6e72..bf1e0b5e824b 100644 --- a/Documentation/hwmon/gl518sm +++ b/Documentation/hwmon/gl518sm.rst @@ -2,27 +2,34 @@ Kernel driver gl518sm ===================== Supported chips: + * Genesys Logic GL518SM release 0x00 + Prefix: 'gl518sm' + Addresses scanned: I2C 0x2c and 0x2d + * Genesys Logic GL518SM release 0x80 + Prefix: 'gl518sm' + Addresses scanned: I2C 0x2c and 0x2d + Datasheet: http://www.genesyslogic.com/ Authors: - Frodo Looijaard <frodol@dds.nl>, - Kyösti Mälkki <kmalkki@cc.hut.fi> - Hong-Gunn Chew <hglinux@gunnet.org> - Jean Delvare <jdelvare@suse.de> + - Frodo Looijaard <frodol@dds.nl>, + - Kyösti Mälkki <kmalkki@cc.hut.fi> + - Hong-Gunn Chew <hglinux@gunnet.org> + - Jean Delvare <jdelvare@suse.de> Description ----------- -IMPORTANT: +.. important:: -For the revision 0x00 chip, the in0, in1, and in2 values (+5V, +3V, -and +12V) CANNOT be read. This is a limitation of the chip, not the driver. + For the revision 0x00 chip, the in0, in1, and in2 values (+5V, +3V, + and +12V) CANNOT be read. This is a limitation of the chip, not the driver. This driver supports the Genesys Logic GL518SM chip. There are at least two revision of this chip, which we call revision 0x00 and 0x80. Revision diff --git a/Documentation/hwmon/hih6130 b/Documentation/hwmon/hih6130.rst index 73dae918ea7b..649bd4be4fc2 100644 --- a/Documentation/hwmon/hih6130 +++ b/Documentation/hwmon/hih6130.rst @@ -2,11 +2,16 @@ Kernel driver hih6130 ===================== Supported chips: + * Honeywell HIH-6130 / HIH-6131 + Prefix: 'hih6130' + Addresses scanned: none + Datasheet: Publicly available at the Honeywell website - http://sensing.honeywell.com/index.php?ci_id=3106&la_id=1&defId=44872 + + http://sensing.honeywell.com/index.php?ci_id=3106&la_id=1&defId=44872 Author: Iain Paton <ipaton0@gmail.com> @@ -28,8 +33,11 @@ instantiate I2C devices. sysfs-Interface --------------- -temp1_input - temperature input -humidity1_input - humidity input +temp1_input + temperature input + +humidity1_input + humidity input Notes ----- diff --git a/Documentation/hwmon/hwmon-kernel-api.txt b/Documentation/hwmon/hwmon-kernel-api.rst index 8bdefb41be30..c41eb6108103 100644 --- a/Documentation/hwmon/hwmon-kernel-api.txt +++ b/Documentation/hwmon/hwmon-kernel-api.rst @@ -1,5 +1,5 @@ -The Linux Hardware Monitoring kernel API. -========================================= +The Linux Hardware Monitoring kernel API +======================================== Guenter Roeck @@ -12,42 +12,43 @@ drivers that want to use the hardware monitoring framework. This document does not describe what a hardware monitoring (hwmon) Driver or Device is. It also does not describe the API which can be used by user space to communicate with a hardware monitoring device. If you want to know this -then please read the following file: Documentation/hwmon/sysfs-interface. +then please read the following file: Documentation/hwmon/sysfs-interface.rst. For additional guidelines on how to write and improve hwmon drivers, please -also read Documentation/hwmon/submitting-patches. +also read Documentation/hwmon/submitting-patches.rst. The API ------- Each hardware monitoring driver must #include <linux/hwmon.h> and, in most cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following -register/unregister functions: - -struct device * -hwmon_device_register_with_groups(struct device *dev, const char *name, - void *drvdata, - const struct attribute_group **groups); - -struct device * -devm_hwmon_device_register_with_groups(struct device *dev, - const char *name, void *drvdata, - const struct attribute_group **groups); - -struct device * -hwmon_device_register_with_info(struct device *dev, - const char *name, void *drvdata, - const struct hwmon_chip_info *info, - const struct attribute_group **extra_groups); - -struct device * -devm_hwmon_device_register_with_info(struct device *dev, - const char *name, - void *drvdata, - const struct hwmon_chip_info *info, - const struct attribute_group **extra_groups); - -void hwmon_device_unregister(struct device *dev); -void devm_hwmon_device_unregister(struct device *dev); +register/unregister functions:: + + struct device * + hwmon_device_register_with_groups(struct device *dev, const char *name, + void *drvdata, + const struct attribute_group **groups); + + struct device * + devm_hwmon_device_register_with_groups(struct device *dev, + const char *name, void *drvdata, + const struct attribute_group **groups); + + struct device * + hwmon_device_register_with_info(struct device *dev, + const char *name, void *drvdata, + const struct hwmon_chip_info *info, + const struct attribute_group **extra_groups); + + struct device * + devm_hwmon_device_register_with_info(struct device *dev, + const char *name, + void *drvdata, + const struct hwmon_chip_info *info, + const struct attribute_group **extra_groups); + + void hwmon_device_unregister(struct device *dev); + + void devm_hwmon_device_unregister(struct device *dev); hwmon_device_register_with_groups registers a hardware monitoring device. The first parameter of this function is a pointer to the parent device. @@ -100,78 +101,89 @@ Using devm_hwmon_device_register_with_info() hwmon_device_register_with_info() registers a hardware monitoring device. The parameters to this function are -struct device *dev Pointer to parent device -const char *name Device name -void *drvdata Driver private data -const struct hwmon_chip_info *info - Pointer to chip description. -const struct attribute_group **extra_groups - Null-terminated list of additional non-standard - sysfs attribute groups. +=============================================== =============================================== +`struct device *dev` Pointer to parent device +`const char *name` Device name +`void *drvdata` Driver private data +`const struct hwmon_chip_info *info` Pointer to chip description. +`const struct attribute_group **extra_groups` Null-terminated list of additional non-standard + sysfs attribute groups. +=============================================== =============================================== This function returns a pointer to the created hardware monitoring device on success and a negative error code for failure. -The hwmon_chip_info structure looks as follows. +The hwmon_chip_info structure looks as follows:: -struct hwmon_chip_info { - const struct hwmon_ops *ops; - const struct hwmon_channel_info **info; -}; + struct hwmon_chip_info { + const struct hwmon_ops *ops; + const struct hwmon_channel_info **info; + }; It contains the following fields: -* ops: Pointer to device operations. -* info: NULL-terminated list of device channel descriptors. +* ops: + Pointer to device operations. +* info: + NULL-terminated list of device channel descriptors. -The list of hwmon operations is defined as: +The list of hwmon operations is defined as:: -struct hwmon_ops { + struct hwmon_ops { umode_t (*is_visible)(const void *, enum hwmon_sensor_types type, u32 attr, int); int (*read)(struct device *, enum hwmon_sensor_types type, u32 attr, int, long *); int (*write)(struct device *, enum hwmon_sensor_types type, u32 attr, int, long); -}; + }; It defines the following operations. -* is_visible: Pointer to a function to return the file mode for each supported - attribute. This function is mandatory. +* is_visible: + Pointer to a function to return the file mode for each supported + attribute. This function is mandatory. -* read: Pointer to a function for reading a value from the chip. This function - is optional, but must be provided if any readable attributes exist. +* read: + Pointer to a function for reading a value from the chip. This function + is optional, but must be provided if any readable attributes exist. -* write: Pointer to a function for writing a value to the chip. This function is - optional, but must be provided if any writeable attributes exist. +* write: + Pointer to a function for writing a value to the chip. This function is + optional, but must be provided if any writeable attributes exist. Each sensor channel is described with struct hwmon_channel_info, which is -defined as follows. +defined as follows:: -struct hwmon_channel_info { - enum hwmon_sensor_types type; - u32 *config; -}; + struct hwmon_channel_info { + enum hwmon_sensor_types type; + u32 *config; + }; It contains following fields: -* type: The hardware monitoring sensor type. - Supported sensor types are - * hwmon_chip A virtual sensor type, used to describe attributes - * which are not bound to a specific input or output - * hwmon_temp Temperature sensor - * hwmon_in Voltage sensor - * hwmon_curr Current sensor - * hwmon_power Power sensor - * hwmon_energy Energy sensor - * hwmon_humidity Humidity sensor - * hwmon_fan Fan speed sensor - * hwmon_pwm PWM control - -* config: Pointer to a 0-terminated list of configuration values for each - sensor of the given type. Each value is a combination of bit values - describing the attributes supposed by a single sensor. +* type: + The hardware monitoring sensor type. + + Supported sensor types are + + ================== ================================================== + hwmon_chip A virtual sensor type, used to describe attributes + which are not bound to a specific input or output + hwmon_temp Temperature sensor + hwmon_in Voltage sensor + hwmon_curr Current sensor + hwmon_power Power sensor + hwmon_energy Energy sensor + hwmon_humidity Humidity sensor + hwmon_fan Fan speed sensor + hwmon_pwm PWM control + ================== ================================================== + +* config: + Pointer to a 0-terminated list of configuration values for each + sensor of the given type. Each value is a combination of bit values + describing the attributes supposed by a single sensor. As an example, here is the complete description file for a LM75 compatible sensor chip. The chip has a single temperature sensor. The driver wants to @@ -179,48 +191,62 @@ register with the thermal subsystem (HWMON_C_REGISTER_TZ), and it supports the update_interval attribute (HWMON_C_UPDATE_INTERVAL). The chip supports reading the temperature (HWMON_T_INPUT), it has a maximum temperature register (HWMON_T_MAX) as well as a maximum temperature hysteresis register -(HWMON_T_MAX_HYST). - -static const u32 lm75_chip_config[] = { - HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL, - 0 -}; - -static const struct hwmon_channel_info lm75_chip = { - .type = hwmon_chip, - .config = lm75_chip_config, -}; - -static const u32 lm75_temp_config[] = { - HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST, - 0 -}; - -static const struct hwmon_channel_info lm75_temp = { - .type = hwmon_temp, - .config = lm75_temp_config, -}; - -static const struct hwmon_channel_info *lm75_info[] = { - &lm75_chip, - &lm75_temp, - NULL -}; - -static const struct hwmon_ops lm75_hwmon_ops = { - .is_visible = lm75_is_visible, - .read = lm75_read, - .write = lm75_write, -}; - -static const struct hwmon_chip_info lm75_chip_info = { - .ops = &lm75_hwmon_ops, - .info = lm75_info, -}; +(HWMON_T_MAX_HYST):: + + static const u32 lm75_chip_config[] = { + HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL, + 0 + }; + + static const struct hwmon_channel_info lm75_chip = { + .type = hwmon_chip, + .config = lm75_chip_config, + }; + + static const u32 lm75_temp_config[] = { + HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST, + 0 + }; + + static const struct hwmon_channel_info lm75_temp = { + .type = hwmon_temp, + .config = lm75_temp_config, + }; + + static const struct hwmon_channel_info *lm75_info[] = { + &lm75_chip, + &lm75_temp, + NULL + }; + + The HWMON_CHANNEL_INFO() macro can and should be used when possible. + With this macro, the above example can be simplified to + + static const struct hwmon_channel_info *lm75_info[] = { + HWMON_CHANNEL_INFO(chip, + HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL), + HWMON_CHANNEL_INFO(temp, + HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST), + NULL + }; + + The remaining declarations are as follows. + + static const struct hwmon_ops lm75_hwmon_ops = { + .is_visible = lm75_is_visible, + .read = lm75_read, + .write = lm75_write, + }; + + static const struct hwmon_chip_info lm75_chip_info = { + .ops = &lm75_hwmon_ops, + .info = lm75_info, + }; A complete list of bit values indicating individual attribute support is defined in include/linux/hwmon.h. Definition prefixes are as follows. +=============== ================================================= HWMON_C_xxxx Chip attributes, for use with hwmon_chip. HWMON_T_xxxx Temperature attributes, for use with hwmon_temp. HWMON_I_xxxx Voltage attributes, for use with hwmon_in. @@ -231,57 +257,76 @@ HWMON_E_xxxx Energy attributes, for use with hwmon_energy. HWMON_H_xxxx Humidity attributes, for use with hwmon_humidity. HWMON_F_xxxx Fan speed attributes, for use with hwmon_fan. HWMON_PWM_xxxx PWM control attributes, for use with hwmon_pwm. +=============== ================================================= Driver callback functions ------------------------- Each driver provides is_visible, read, and write functions. Parameters -and return values for those functions are as follows. +and return values for those functions are as follows:: -umode_t is_visible_func(const void *data, enum hwmon_sensor_types type, - u32 attr, int channel) + umode_t is_visible_func(const void *data, enum hwmon_sensor_types type, + u32 attr, int channel) Parameters: - data: Pointer to device private data structure. - type: The sensor type. - attr: Attribute identifier associated with a specific attribute. + data: + Pointer to device private data structure. + type: + The sensor type. + attr: + Attribute identifier associated with a specific attribute. For example, the attribute value for HWMON_T_INPUT would be hwmon_temp_input. For complete mappings of bit fields to attribute values please see include/linux/hwmon.h. - channel:The sensor channel number. + channel: + The sensor channel number. Return value: The file mode for this attribute. Typically, this will be 0 (the attribute will not be created), S_IRUGO, or 'S_IRUGO | S_IWUSR'. -int read_func(struct device *dev, enum hwmon_sensor_types type, - u32 attr, int channel, long *val) +:: + + int read_func(struct device *dev, enum hwmon_sensor_types type, + u32 attr, int channel, long *val) Parameters: - dev: Pointer to the hardware monitoring device. - type: The sensor type. - attr: Attribute identifier associated with a specific attribute. + dev: + Pointer to the hardware monitoring device. + type: + The sensor type. + attr: + Attribute identifier associated with a specific attribute. For example, the attribute value for HWMON_T_INPUT would be hwmon_temp_input. For complete mappings please see include/linux/hwmon.h. - channel:The sensor channel number. - val: Pointer to attribute value. + channel: + The sensor channel number. + val: + Pointer to attribute value. Return value: 0 on success, a negative error number otherwise. -int write_func(struct device *dev, enum hwmon_sensor_types type, - u32 attr, int channel, long val) +:: + + int write_func(struct device *dev, enum hwmon_sensor_types type, + u32 attr, int channel, long val) Parameters: - dev: Pointer to the hardware monitoring device. - type: The sensor type. - attr: Attribute identifier associated with a specific attribute. + dev: + Pointer to the hardware monitoring device. + type: + The sensor type. + attr: + Attribute identifier associated with a specific attribute. For example, the attribute value for HWMON_T_INPUT would be hwmon_temp_input. For complete mappings please see include/linux/hwmon.h. - channel:The sensor channel number. - val: The value to write to the chip. + channel: + The sensor channel number. + val: + The value to write to the chip. Return value: 0 on success, a negative error number otherwise. @@ -317,25 +362,25 @@ Standard functions, similar to DEVICE_ATTR_{RW,RO,WO}, have _show and _store appended to the provided function name. SENSOR_DEVICE_ATTR and its variants define a struct sensor_device_attribute -variable. This structure has the following fields. +variable. This structure has the following fields:: -struct sensor_device_attribute { - struct device_attribute dev_attr; - int index; -}; + struct sensor_device_attribute { + struct device_attribute dev_attr; + int index; + }; You can use to_sensor_dev_attr to get the pointer to this structure from the attribute read or write function. Its parameter is the device to which the attribute is attached. SENSOR_DEVICE_ATTR_2 and its variants define a struct sensor_device_attribute_2 -variable, which is defined as follows. +variable, which is defined as follows:: -struct sensor_device_attribute_2 { - struct device_attribute dev_attr; - u8 index; - u8 nr; -}; + struct sensor_device_attribute_2 { + struct device_attribute dev_attr; + u8 index; + u8 nr; + }; Use to_sensor_dev_attr_2 to get the pointer to this structure. Its parameter is the device to which the attribute is attached. diff --git a/Documentation/hwmon/ibm-cffps b/Documentation/hwmon/ibm-cffps.rst index e05ecd8ecfcf..52e74e39463a 100644 --- a/Documentation/hwmon/ibm-cffps +++ b/Documentation/hwmon/ibm-cffps.rst @@ -2,6 +2,7 @@ Kernel driver ibm-cffps ======================= Supported chips: + * IBM Common Form Factor power supply Author: Eddie James <eajames@us.ibm.com> @@ -24,6 +25,7 @@ Sysfs entries The following attributes are supported: +======================= ====================================================== curr1_alarm Output current over-current alarm. curr1_input Measured output current in mA. curr1_label "iout1" @@ -52,3 +54,4 @@ temp2_alarm Secondary rectifier temp over-temperature alarm. temp2_input Measured secondary rectifier temp in millidegrees C. temp3_alarm ORing FET temperature over-temperature alarm. temp3_input Measured ORing FET temperature in millidegrees C. +======================= ====================================================== diff --git a/Documentation/hwmon/ibmaem b/Documentation/hwmon/ibmaem.rst index 1e0d59e000b4..f07a14a1c2f5 100644 --- a/Documentation/hwmon/ibmaem +++ b/Documentation/hwmon/ibmaem.rst @@ -1,15 +1,21 @@ Kernel driver ibmaem -====================== +==================== This driver talks to the IBM Systems Director Active Energy Manager, known henceforth as AEM. Supported systems: + * Any recent IBM System X server with AEM support. + This includes the x3350, x3550, x3650, x3655, x3755, x3850 M2, - x3950 M2, and certain HC10/HS2x/LS2x/QS2x blades. The IPMI host interface + x3950 M2, and certain HC10/HS2x/LS2x/QS2x blades. + + The IPMI host interface driver ("ipmi-si") needs to be loaded for this driver to do anything. + Prefix: 'ibmaem' + Datasheet: Not available Author: Darrick J. Wong diff --git a/Documentation/hwmon/ibmpowernv b/Documentation/hwmon/ibmpowernv.rst index 56468258711f..5d642bc3dec0 100644 --- a/Documentation/hwmon/ibmpowernv +++ b/Documentation/hwmon/ibmpowernv.rst @@ -2,6 +2,7 @@ Kernel Driver IBMPOWERNV ======================== Supported systems: + * Any recent IBM P servers based on POWERNV platform Author: Neelesh Gupta @@ -29,10 +30,11 @@ CONFIG_SENSORS_IBMPOWERNV. It can also be built as module 'ibmpowernv'. Sysfs attributes ---------------- +======================= ======================================================= fanX_input Measured RPM value. fanX_min Threshold RPM for alert generation. -fanX_fault 0: No fail condition - 1: Failing fan +fanX_fault - 0: No fail condition + - 1: Failing fan tempX_input Measured ambient temperature. tempX_max Threshold ambient temperature for alert generation. @@ -42,20 +44,22 @@ tempX_enable Enable/disable all temperature sensors belonging to the sub-group. In POWER9, this attribute corresponds to each OCC. Using this attribute each OCC can be asked to disable/enable all of its temperature sensors. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable inX_input Measured power supply voltage (millivolt) -inX_fault 0: No fail condition. - 1: Failing power supply. +inX_fault - 0: No fail condition. + - 1: Failing power supply. inX_highest Historical maximum voltage inX_lowest Historical minimum voltage inX_enable Enable/disable all voltage sensors belonging to the sub-group. In POWER9, this attribute corresponds to each OCC. Using this attribute each OCC can be asked to disable/enable all of its voltage sensors. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable powerX_input Power consumption (microWatt) powerX_input_highest Historical maximum power @@ -64,8 +68,9 @@ powerX_enable Enable/disable all power sensors belonging to the sub-group. In POWER9, this attribute corresponds to each OCC. Using this attribute each OCC can be asked to disable/enable all of its power sensors. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable currX_input Measured current (milliampere) currX_highest Historical maximum current @@ -74,7 +79,9 @@ currX_enable Enable/disable all current sensors belonging to the sub-group. In POWER9, this attribute corresponds to each OCC. Using this attribute each OCC can be asked to disable/enable all of its current sensors. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable energyX_input Cumulative energy (microJoule) +======================= ======================================================= diff --git a/Documentation/hwmon/ina209 b/Documentation/hwmon/ina209.rst index 672501de4509..64322075a145 100644 --- a/Documentation/hwmon/ina209 +++ b/Documentation/hwmon/ina209.rst @@ -1,16 +1,21 @@ Kernel driver ina209 -===================== +==================== Supported chips: + * Burr-Brown / Texas Instruments INA209 + Prefix: 'ina209' + Addresses scanned: - + Datasheet: - http://www.ti.com/lit/gpn/ina209 + http://www.ti.com/lit/gpn/ina209 -Author: Paul Hays <Paul.Hays@cattail.ca> -Author: Ira W. Snyder <iws@ovro.caltech.edu> -Author: Guenter Roeck <linux@roeck-us.net> +Author: + - Paul Hays <Paul.Hays@cattail.ca> + - Ira W. Snyder <iws@ovro.caltech.edu> + - Guenter Roeck <linux@roeck-us.net> Description @@ -31,7 +36,7 @@ the I2C bus. See the datasheet for details. This tries to expose most monitoring features of the hardware via sysfs. It does not support every feature of this chip. - +======================= ======================================================= in0_input shunt voltage (mV) in0_input_highest shunt voltage historical maximum reading (mV) in0_input_lowest shunt voltage historical minimum reading (mV) @@ -70,6 +75,7 @@ curr1_input current measurement (mA) update_interval data conversion time; affects number of samples used to average results for shunt and bus voltages. +======================= ======================================================= General Remarks --------------- diff --git a/Documentation/hwmon/ina2xx b/Documentation/hwmon/ina2xx.rst index 0f36c021192d..94b9a260c518 100644 --- a/Documentation/hwmon/ina2xx +++ b/Documentation/hwmon/ina2xx.rst @@ -2,35 +2,56 @@ Kernel driver ina2xx ==================== Supported chips: + * Texas Instruments INA219 + + Prefix: 'ina219' Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + + http://www.ti.com/ * Texas Instruments INA220 + Prefix: 'ina220' + Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + + http://www.ti.com/ * Texas Instruments INA226 + Prefix: 'ina226' + Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + + http://www.ti.com/ * Texas Instruments INA230 + Prefix: 'ina230' + Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + + http://www.ti.com/ * Texas Instruments INA231 + Prefix: 'ina231' + Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + + http://www.ti.com/ Author: Lothar Felten <lothar.felten@gmail.com> @@ -57,23 +78,27 @@ refer to the Documentation/devicetree/bindings/hwmon/ina2xx.txt for bindings if the device tree is used. Additionally ina226 supports update_interval attribute as described in -Documentation/hwmon/sysfs-interface. Internally the interval is the sum of +Documentation/hwmon/sysfs-interface.rst. Internally the interval is the sum of bus and shunt voltage conversion times multiplied by the averaging rate. We don't touch the conversion times and only modify the number of averages. The lower limit of the update_interval is 2 ms, the upper limit is 2253 ms. The actual programmed interval may vary from the desired value. General sysfs entries -------------- +--------------------- +======================= =============================== in0_input Shunt voltage(mV) channel in1_input Bus voltage(mV) channel curr1_input Current(mA) measurement channel power1_input Power(uW) measurement channel shunt_resistor Shunt resistance(uOhm) channel +======================= =============================== Sysfs entries for ina226, ina230 and ina231 only -------------- +------------------------------------------------ +======================= ==================================================== update_interval data conversion time; affects number of samples used to average results for shunt and bus voltages. +======================= ==================================================== diff --git a/Documentation/hwmon/ina3221 b/Documentation/hwmon/ina3221.rst index 4b82cbfb551c..f6007ae8f4e2 100644 --- a/Documentation/hwmon/ina3221 +++ b/Documentation/hwmon/ina3221.rst @@ -2,11 +2,16 @@ Kernel driver ina3221 ===================== Supported chips: + * Texas Instruments INA3221 + Prefix: 'ina3221' + Addresses: I2C 0x40 - 0x43 + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/ + + http://www.ti.com/ Author: Andrew F. Davis <afd@ti.com> @@ -21,17 +26,37 @@ and power are calculated host-side from these. Sysfs entries ------------- +======================= ======================================================= in[123]_label Voltage channel labels in[123]_enable Voltage channel enable controls in[123]_input Bus voltage(mV) channels curr[123]_input Current(mA) measurement channels shunt[123]_resistor Shunt resistance(uOhm) channels curr[123]_crit Critical alert current(mA) setting, activates the - corresponding alarm when the respective current - is above this value + corresponding alarm when the respective current + is above this value curr[123]_crit_alarm Critical alert current limit exceeded curr[123]_max Warning alert current(mA) setting, activates the - corresponding alarm when the respective current - average is above this value. + corresponding alarm when the respective current + average is above this value. curr[123]_max_alarm Warning alert current limit exceeded in[456]_input Shunt voltage(uV) for channels 1, 2, and 3 respectively +samples Number of samples using in the averaging mode. + + Supports the list of number of samples: + + 1, 4, 16, 64, 128, 256, 512, 1024 + +update_interval Data conversion time in millisecond, following: + + update_interval = C x S x (BC + SC) + + * C: number of enabled channels + * S: number of samples + * BC: bus-voltage conversion time in millisecond + * SC: shunt-voltage conversion time in millisecond + + Affects both Bus- and Shunt-voltage conversion time. + Note that setting update_interval to 0ms sets both BC + and SC to 140 us (minimum conversion time). +======================= ======================================================= diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst new file mode 100644 index 000000000000..ee090e51653a --- /dev/null +++ b/Documentation/hwmon/index.rst @@ -0,0 +1,182 @@ +========================= +Linux Hardware Monitoring +========================= + +.. toctree:: + :maxdepth: 1 + + hwmon-kernel-api + pmbus-core + submitting-patches + sysfs-interface + userspace-tools + +Hardware Monitoring Kernel Drivers +================================== + +.. toctree:: + :maxdepth: 1 + + ab8500 + abituguru + abituguru3 + abx500 + acpi_power_meter + ad7314 + adc128d818 + adm1021 + adm1025 + adm1026 + adm1031 + adm1275 + adm9240 + ads1015 + ads7828 + adt7410 + adt7411 + adt7462 + adt7470 + adt7475 + amc6821 + asb100 + asc7621 + aspeed-pwm-tacho + coretemp + da9052 + da9055 + dme1737 + ds1621 + ds620 + emc1403 + emc2103 + emc6w201 + f71805f + f71882fg + fam15h_power + ftsteutates + g760a + g762 + gl518sm + hih6130 + ibmaem + ibm-cffps + ibmpowernv + ina209 + ina2xx + ina3221 + ir35221 + ir38064 + isl68137 + it87 + jc42 + k10temp + k8temp + lineage-pem + lm25066 + lm63 + lm70 + lm73 + lm75 + lm77 + lm78 + lm80 + lm83 + lm85 + lm87 + lm90 + lm92 + lm93 + lm95234 + lm95245 + lochnagar + ltc2945 + ltc2978 + ltc2990 + ltc3815 + ltc4151 + ltc4215 + ltc4245 + ltc4260 + ltc4261 + max16064 + max16065 + max1619 + max1668 + max197 + max20751 + max31722 + max31785 + max31790 + max34440 + max6639 + max6642 + max6650 + max6697 + max8688 + mc13783-adc + mcp3021 + menf21bmc + mlxreg-fan + nct6683 + nct6775 + nct7802 + nct7904 + npcm750-pwm-fan + nsa320 + ntc_thermistor + occ + pc87360 + pc87427 + pcf8591 + pmbus + powr1220 + pwm-fan + raspberrypi-hwmon + sch5627 + sch5636 + scpi-hwmon + sht15 + sht21 + sht3x + shtc1 + sis5595 + smm665 + smsc47b397 + smsc47m192 + smsc47m1 + tc654 + tc74 + thmc50 + tmp102 + tmp103 + tmp108 + tmp401 + tmp421 + tps40422 + twl4030-madc-hwmon + ucd9000 + ucd9200 + vexpress + via686a + vt1211 + w83627ehf + w83627hf + w83773g + w83781d + w83791d + w83792d + w83793 + w83795 + w83l785ts + w83l786ng + wm831x + wm8350 + xgene-hwmon + zl6100 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/hwmon/ir35221 b/Documentation/hwmon/ir35221.rst index f7e112752c04..a83922e5ccb5 100644 --- a/Documentation/hwmon/ir35221 +++ b/Documentation/hwmon/ir35221.rst @@ -2,9 +2,12 @@ Kernel driver ir35221 ===================== Supported chips: - * Infinion IR35221 + * Infineon IR35221 + Prefix: 'ir35221' + Addresses scanned: - + Datasheet: Datasheet is not publicly available. Author: Samuel Mendoza-Jonas <sam@mendozajonas.com> @@ -23,15 +26,16 @@ This driver does not probe for PMBus devices. You will have to instantiate devices explicitly. Example: the following commands will load the driver for an IR35221 -at address 0x70 on I2C bus #4: +at address 0x70 on I2C bus #4:: -# modprobe ir35221 -# echo ir35221 0x70 > /sys/bus/i2c/devices/i2c-4/new_device + # modprobe ir35221 + # echo ir35221 0x70 > /sys/bus/i2c/devices/i2c-4/new_device Sysfs attributes ---------------- +======================= ======================================================= curr1_label "iin" curr1_input Measured input current curr1_max Maximum current @@ -85,3 +89,4 @@ temp[1-2]_highest Highest temperature temp[1-2]_lowest Lowest temperature temp[1-2]_max Maximum temperature temp[1-2]_max_alarm Chip temperature high alarm +======================= ======================================================= diff --git a/Documentation/hwmon/ir38064.rst b/Documentation/hwmon/ir38064.rst new file mode 100644 index 000000000000..c455d755a267 --- /dev/null +++ b/Documentation/hwmon/ir38064.rst @@ -0,0 +1,66 @@ +Kernel driver ir38064 +===================== + +Supported chips: + + * Infineon IR38064 + + Prefix: 'ir38064' + Addresses scanned: - + + Datasheet: Publicly available at the Infineon webiste + https://www.infineon.com/dgdl/Infineon-IR38064MTRPBF-DS-v03_07-EN.pdf?fileId=5546d462584d1d4a0158db0d9efb67ca + +Authors: + - Maxim Sloyko <maxims@google.com> + - Patrick Venture <venture@google.com> + +Description +----------- + +IR38064 is a Single-input Voltage, Synchronous Buck Regulator, DC-DC Converter. + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +Sysfs attributes +---------------- + +======================= =========================== +curr1_label "iout1" +curr1_input Measured output current +curr1_crit Critical maximum current +curr1_crit_alarm Current critical high alarm +curr1_max Maximum current +curr1_max_alarm Current high alarm + +in1_label "vin" +in1_input Measured input voltage +in1_crit Critical maximum input voltage +in1_crit_alarm Input voltage critical high alarm +in1_min Minimum input voltage +in1_min_alarm Input voltage low alarm + +in2_label "vout1" +in2_input Measured output voltage +in2_lcrit Critical minimum output voltage +in2_lcrit_alarm Output voltage critical low alarm +in2_crit Critical maximum output voltage +in2_crit_alarm Output voltage critical high alarm +in2_max Maximum output voltage +in2_max_alarm Output voltage high alarm +in2_min Minimum output voltage +in2_min_alarm Output voltage low alarm + +power1_label "pout1" +power1_input Measured output power + +temp1_input Measured temperature +temp1_crit Critical high temperature +temp1_crit_alarm Chip temperature critical high alarm +temp1_max Maximum temperature +temp1_max_alarm Chip temperature high alarm +======================= =========================== diff --git a/Documentation/hwmon/isl68137.rst b/Documentation/hwmon/isl68137.rst new file mode 100644 index 000000000000..a5a7c8545c9e --- /dev/null +++ b/Documentation/hwmon/isl68137.rst @@ -0,0 +1,80 @@ +Kernel driver isl68137 +====================== + +Supported chips: + + * Intersil ISL68137 + + Prefix: 'isl68137' + + Addresses scanned: - + + Datasheet: + + Publicly available at the Intersil website + https://www.intersil.com/content/dam/Intersil/documents/isl6/isl68137.pdf + +Authors: + - Maxim Sloyko <maxims@google.com> + - Robert Lippert <rlippert@google.com> + - Patrick Venture <venture@google.com> + +Description +----------- + +Intersil ISL68137 is a digital output 7-phase configurable PWM +controller with an AVSBus interface. + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +The ISL68137 AVS operation mode must be enabled/disabled at runtime. + +Beyond the normal sysfs pmbus attributes, the driver exposes a control attribute. + +Additional Sysfs attributes +--------------------------- + +======================= ==================================== +avs(0|1)_enable Controls the AVS state of each rail. + +curr1_label "iin" +curr1_input Measured input current +curr1_crit Critical maximum current +curr1_crit_alarm Current critical high alarm + +curr[2-3]_label "iout[1-2]" +curr[2-3]_input Measured output current +curr[2-3]_crit Critical maximum current +curr[2-3]_crit_alarm Current critical high alarm + +in1_label "vin" +in1_input Measured input voltage +in1_lcrit Critical minimum input voltage +in1_lcrit_alarm Input voltage critical low alarm +in1_crit Critical maximum input voltage +in1_crit_alarm Input voltage critical high alarm + +in[2-3]_label "vout[1-2]" +in[2-3]_input Measured output voltage +in[2-3]_lcrit Critical minimum output voltage +in[2-3]_lcrit_alarm Output voltage critical low alarm +in[2-3]_crit Critical maximum output voltage +in[2-3]_crit_alarm Output voltage critical high alarm + +power1_label "pin" +power1_input Measured input power +power1_alarm Input power high alarm + +power[2-3]_label "pout[1-2]" +power[2-3]_input Measured output power + +temp[1-3]_input Measured temperature +temp[1-3]_crit Critical high temperature +temp[1-3]_crit_alarm Chip temperature critical high alarm +temp[1-3]_max Maximum temperature +temp[1-3]_max_alarm Chip temperature high alarm +======================= ==================================== diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87.rst index fff6f6bf55bc..2d83f23bee93 100644 --- a/Documentation/hwmon/it87 +++ b/Documentation/hwmon/it87.rst @@ -2,105 +2,179 @@ Kernel driver it87 ================== Supported chips: + * IT8603E/IT8623E + Prefix: 'it8603' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8620E + Prefix: 'it8620' + Addresses scanned: from Super I/O config space (8 I/O ports) + * IT8628E + Prefix: 'it8628' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8705F + Prefix: 'it87' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Once publicly available at the ITE website, but no longer + * IT8712F + Prefix: 'it8712' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Once publicly available at the ITE website, but no longer + * IT8716F/IT8726F + Prefix: 'it8716' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Once publicly available at the ITE website, but no longer + * IT8718F + Prefix: 'it8718' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Once publicly available at the ITE website, but no longer + * IT8720F + Prefix: 'it8720' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8721F/IT8758E + Prefix: 'it8721' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8728F + Prefix: 'it8728' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8732F + Prefix: 'it8732' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8771E + Prefix: 'it8771' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8772E + Prefix: 'it8772' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8781F + Prefix: 'it8781' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8782F + Prefix: 'it8782' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8783E/F + Prefix: 'it8783' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8786E + Prefix: 'it8786' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * IT8790E + Prefix: 'it8790' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: Not publicly available + * SiS950 [clone of IT8705F] + Prefix: 'it87' + Addresses scanned: from Super I/O config space (8 I/O ports) + Datasheet: No longer be available + Authors: - Christophe Gauthron - Jean Delvare <jdelvare@suse.de> + - Christophe Gauthron + - Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- * update_vbat: int - - 0 if vbat should report power on value, 1 if vbat should be updated after - each read. Default is 0. On some boards the battery voltage is provided - by either the battery or the onboard power supply. Only the first reading - at power on will be the actual battery voltage (which the chip does - automatically). On other boards the battery voltage is always fed to - the chip so can be read at any time. Excessive reading may decrease - battery life but no information is given in the datasheet. + 0 if vbat should report power on value, 1 if vbat should be updated after + each read. Default is 0. On some boards the battery voltage is provided + by either the battery or the onboard power supply. Only the first reading + at power on will be the actual battery voltage (which the chip does + automatically). On other boards the battery voltage is always fed to + the chip so can be read at any time. Excessive reading may decrease + battery life but no information is given in the datasheet. * fix_pwm_polarity int - - Force PWM polarity to active high (DANGEROUS). Some chips are - misconfigured by BIOS - PWM values would be inverted. This option tries - to fix this. Please contact your BIOS manufacturer and ask him for fix. + Force PWM polarity to active high (DANGEROUS). Some chips are + misconfigured by BIOS - PWM values would be inverted. This option tries + to fix this. Please contact your BIOS manufacturer and ask him for fix. Hardware Interfaces diff --git a/Documentation/hwmon/jc42 b/Documentation/hwmon/jc42.rst index b4b671f22453..5b14b49bb6f7 100644 --- a/Documentation/hwmon/jc42 +++ b/Documentation/hwmon/jc42.rst @@ -2,53 +2,100 @@ Kernel driver jc42 ================== Supported chips: + * Analog Devices ADT7408 + Datasheets: + http://www.analog.com/static/imported-files/data_sheets/ADT7408.pdf + * Atmel AT30TS00, AT30TS002A/B, AT30TSE004A + Datasheets: + http://www.atmel.com/Images/doc8585.pdf + http://www.atmel.com/Images/doc8711.pdf + http://www.atmel.com/Images/Atmel-8852-SEEPROM-AT30TSE002A-Datasheet.pdf + http://www.atmel.com/Images/Atmel-8868-DTS-AT30TSE004A-Datasheet.pdf + * IDT TSE2002B3, TSE2002GB2, TSE2004GB2, TS3000B3, TS3000GB0, TS3000GB2, + TS3001GB2 + Datasheets: + Available from IDT web site + * Maxim MAX6604 + Datasheets: + http://datasheets.maxim-ic.com/en/ds/MAX6604.pdf + * Microchip MCP9804, MCP9805, MCP9808, MCP98242, MCP98243, MCP98244, MCP9843 + Datasheets: + http://ww1.microchip.com/downloads/en/DeviceDoc/22203C.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/21977b.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/25095A.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/21996a.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/22153c.pdf + http://ww1.microchip.com/downloads/en/DeviceDoc/22327A.pdf + * NXP Semiconductors SE97, SE97B, SE98, SE98A + Datasheets: + http://www.nxp.com/documents/data_sheet/SE97.pdf + http://www.nxp.com/documents/data_sheet/SE97B.pdf + http://www.nxp.com/documents/data_sheet/SE98.pdf + http://www.nxp.com/documents/data_sheet/SE98A.pdf + * ON Semiconductor CAT34TS02, CAT6095 + Datasheet: + http://www.onsemi.com/pub_link/Collateral/CAT34TS02-D.PDF + http://www.onsemi.com/pub/Collateral/CAT6095-D.PDF + * ST Microelectronics STTS424, STTS424E02, STTS2002, STTS2004, STTS3000 + Datasheets: + http://www.st.com/web/en/resource/technical/document/datasheet/CD00157556.pdf + http://www.st.com/web/en/resource/technical/document/datasheet/CD00157558.pdf + http://www.st.com/web/en/resource/technical/document/datasheet/CD00266638.pdf + http://www.st.com/web/en/resource/technical/document/datasheet/CD00225278.pdf + http://www.st.com/web/en/resource/technical/document/datasheet/DM00076709.pdf + * JEDEC JC 42.4 compliant temperature sensor chips + Datasheet: + http://www.jedec.org/sites/default/files/docs/4_01_04R19.pdf + Common for all chips: + Prefix: 'jc42' + Addresses scanned: I2C 0x18 - 0x1f Author: @@ -67,10 +114,10 @@ The driver auto-detects the chips listed above, but can be manually instantiated to support other JC 42.4 compliant chips. Example: the following will load the driver for a generic JC 42.4 compliant -temperature sensor at address 0x18 on I2C bus #1: +temperature sensor at address 0x18 on I2C bus #1:: -# modprobe jc42 -# echo jc42 0x18 > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe jc42 + # echo jc42 0x18 > /sys/bus/i2c/devices/i2c-1/new_device A JC 42.4 compliant chip supports a single temperature sensor. Minimum, maximum, and critical temperature can be configured. There are alarms for high, low, @@ -90,6 +137,7 @@ cannot be changed. Sysfs entries ------------- +======================= =========================================== temp1_input Temperature (RO) temp1_min Minimum temperature (RO or RW) temp1_max Maximum temperature (RO or RW) @@ -101,3 +149,4 @@ temp1_max_hyst Maximum hysteresis temperature (RO) temp1_min_alarm Temperature low alarm temp1_max_alarm Temperature high alarm temp1_crit_alarm Temperature critical alarm +======================= =========================================== diff --git a/Documentation/hwmon/k10temp b/Documentation/hwmon/k10temp.rst index 254d2f55345a..12a86ba17de9 100644 --- a/Documentation/hwmon/k10temp +++ b/Documentation/hwmon/k10temp.rst @@ -2,42 +2,77 @@ Kernel driver k10temp ===================== Supported chips: + * AMD Family 10h processors: + Socket F: Quad-Core/Six-Core/Embedded Opteron (but see below) + Socket AM2+: Quad-Core Opteron, Phenom (II) X3/X4, Athlon X2 (but see below) + Socket AM3: Quad-Core Opteron, Athlon/Phenom II X2/X3/X4, Sempron II + Socket S1G3: Athlon II, Sempron, Turion II + * AMD Family 11h processors: + Socket S1G2: Athlon (X2), Sempron (X2), Turion X2 (Ultra) + * AMD Family 12h processors: "Llano" (E2/A4/A6/A8-Series) + * AMD Family 14h processors: "Brazos" (C/E/G/Z-Series) + * AMD Family 15h processors: "Bulldozer" (FX-Series), "Trinity", "Kaveri", "Carrizo" + * AMD Family 16h processors: "Kabini", "Mullins" Prefix: 'k10temp' + Addresses scanned: PCI space + Datasheets: + BIOS and Kernel Developer's Guide (BKDG) For AMD Family 10h Processors: + http://support.amd.com/us/Processor_TechDocs/31116.pdf + BIOS and Kernel Developer's Guide (BKDG) for AMD Family 11h Processors: + http://support.amd.com/us/Processor_TechDocs/41256.pdf + BIOS and Kernel Developer's Guide (BKDG) for AMD Family 12h Processors: + http://support.amd.com/us/Processor_TechDocs/41131.pdf + BIOS and Kernel Developer's Guide (BKDG) for AMD Family 14h Models 00h-0Fh Processors: + http://support.amd.com/us/Processor_TechDocs/43170.pdf + Revision Guide for AMD Family 10h Processors: + http://support.amd.com/us/Processor_TechDocs/41322.pdf + Revision Guide for AMD Family 11h Processors: + http://support.amd.com/us/Processor_TechDocs/41788.pdf + Revision Guide for AMD Family 12h Processors: + http://support.amd.com/us/Processor_TechDocs/44739.pdf + Revision Guide for AMD Family 14h Models 00h-0Fh Processors: + http://support.amd.com/us/Processor_TechDocs/47534.pdf + AMD Family 11h Processor Power and Thermal Data Sheet for Notebooks: + http://support.amd.com/us/Processor_TechDocs/43373.pdf + AMD Family 10h Server and Workstation Processor Power and Thermal Data Sheet: + http://support.amd.com/us/Processor_TechDocs/43374.pdf + AMD Family 10h Desktop Processor Power and Thermal Data Sheet: + http://support.amd.com/us/Processor_TechDocs/43375.pdf Author: Clemens Ladisch <clemens@ladisch.de> @@ -60,7 +95,7 @@ are using an AM3 processor on an AM2+ mainboard, you can safely use the There is one temperature measurement value, available as temp1_input in sysfs. It is measured in degrees Celsius with a resolution of 1/8th degree. -Please note that it is defined as a relative value; to quote the AMD manual: +Please note that it is defined as a relative value; to quote the AMD manual:: Tctl is the processor temperature control value, used by the platform to control cooling systems. Tctl is a non-physical temperature on an diff --git a/Documentation/hwmon/k8temp b/Documentation/hwmon/k8temp.rst index 716dc24c7237..72da12aa17e5 100644 --- a/Documentation/hwmon/k8temp +++ b/Documentation/hwmon/k8temp.rst @@ -2,12 +2,17 @@ Kernel driver k8temp ==================== Supported chips: + * AMD Athlon64/FX or Opteron CPUs + Prefix: 'k8temp' + Addresses scanned: PCI space + Datasheet: http://support.amd.com/us/Processor_TechDocs/32559.pdf Author: Rudolf Marek + Contact: Rudolf Marek <r.marek@assembler.cz> Description @@ -27,10 +32,12 @@ implemented sensors. Mapping of /sys files is as follows: -temp1_input - temperature of Core 0 and "place" 0 -temp2_input - temperature of Core 0 and "place" 1 -temp3_input - temperature of Core 1 and "place" 0 -temp4_input - temperature of Core 1 and "place" 1 +============= =================================== +temp1_input temperature of Core 0 and "place" 0 +temp2_input temperature of Core 0 and "place" 1 +temp3_input temperature of Core 1 and "place" 0 +temp4_input temperature of Core 1 and "place" 1 +============= =================================== Temperatures are measured in degrees Celsius and measurement resolution is 1 degree C. It is expected that future CPU will have better resolution. The @@ -48,7 +55,7 @@ computed temperature called TControl, which must be lower than TControlMax. The relationship is following: -temp1_input - TjOffset*2 < TControlMax, + temp1_input - TjOffset*2 < TControlMax, TjOffset is not yet exported by the driver, TControlMax is usually 70 degrees C. The rule of the thumb -> CPU temperature should not cross diff --git a/Documentation/hwmon/lineage-pem b/Documentation/hwmon/lineage-pem.rst index 83b2ddc160c8..10c271dc20e8 100644 --- a/Documentation/hwmon/lineage-pem +++ b/Documentation/hwmon/lineage-pem.rst @@ -2,11 +2,16 @@ Kernel driver lineage-pem ========================= Supported devices: + * Lineage Compact Power Line Power Entry Modules + Prefix: 'lineage-pem' + Addresses scanned: - + Documentation: - http://www.lineagepower.com/oem/pdf/CPLI2C.pdf + + http://www.lineagepower.com/oem/pdf/CPLI2C.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -31,9 +36,10 @@ which can be safely used to identify the chip. You will have to instantiate the devices explicitly. Example: the following will load the driver for a Lineage PEM at address 0x40 -on I2C bus #1: -$ modprobe lineage-pem -$ echo lineage-pem 0x40 > /sys/bus/i2c/devices/i2c-1/new_device +on I2C bus #1:: + + $ modprobe lineage-pem + $ echo lineage-pem 0x40 > /sys/bus/i2c/devices/i2c-1/new_device All Lineage CPL power entry modules have a built-in I2C bus master selector (PCA9541). To ensure device access, this driver should only be used as client @@ -51,6 +57,7 @@ Input voltage, input current, input power, and fan speed measurement is only supported on newer devices. The driver detects if those attributes are supported, and only creates respective sysfs entries if they are. +======================= =============================== in1_input Output voltage (mV) in1_min_alarm Output undervoltage alarm in1_max_alarm Output overvoltage alarm @@ -75,3 +82,4 @@ temp1_crit temp1_alarm temp1_crit_alarm temp1_fault +======================= =============================== diff --git a/Documentation/hwmon/lm25066 b/Documentation/hwmon/lm25066.rst index 51b32aa203a8..da15e3094c8c 100644 --- a/Documentation/hwmon/lm25066 +++ b/Documentation/hwmon/lm25066.rst @@ -2,34 +2,62 @@ Kernel driver lm25066 ===================== Supported chips: + * TI LM25056 + Prefix: 'lm25056' + Addresses scanned: - + Datasheets: + http://www.ti.com/lit/gpn/lm25056 + http://www.ti.com/lit/gpn/lm25056a + * National Semiconductor LM25066 + Prefix: 'lm25066' + Addresses scanned: - + Datasheets: + http://www.national.com/pf/LM/LM25066.html + http://www.national.com/pf/LM/LM25066A.html + * National Semiconductor LM5064 + Prefix: 'lm5064' + Addresses scanned: - + Datasheet: + http://www.national.com/pf/LM/LM5064.html + * National Semiconductor LM5066 + Prefix: 'lm5066' + Addresses scanned: - + Datasheet: + http://www.national.com/pf/LM/LM5066.html + * Texas Instruments LM5066I + Prefix: 'lm5066i' + Addresses scanned: - + Datasheet: + http://www.ti.com/product/LM5066I + Author: Guenter Roeck <linux@roeck-us.net> @@ -41,7 +69,7 @@ LM25066, LM5064, and LM5066/LM5066I Power Management, Monitoring, Control, and Protection ICs. The driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus for details on PMBus client drivers. +Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -64,6 +92,7 @@ Sysfs entries The following attributes are supported. Limits are read-write; all other attributes are read-only. +======================= ======================================================= in1_label "vin" in1_input Measured input voltage. in1_average Average measured input voltage. @@ -105,3 +134,4 @@ temp1_max Maximum temperature. temp1_crit Critical high temperature. temp1_max_alarm Chip temperature high alarm. temp1_crit_alarm Chip temperature critical high alarm. +======================= ======================================================= diff --git a/Documentation/hwmon/lm63 b/Documentation/hwmon/lm63.rst index 4a00461512a6..f478132b0408 100644 --- a/Documentation/hwmon/lm63 +++ b/Documentation/hwmon/lm63.rst @@ -2,26 +2,43 @@ Kernel driver lm63 ================== Supported chips: + * National Semiconductor LM63 + Prefix: 'lm63' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM63.html + + http://www.national.com/pf/LM/LM63.html + * National Semiconductor LM64 + Prefix: 'lm64' + Addresses scanned: I2C 0x18 and 0x4e + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM64.html + + http://www.national.com/pf/LM/LM64.html + * National Semiconductor LM96163 + Prefix: 'lm96163' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM96163.html + + http://www.national.com/pf/LM/LM96163.html + Author: Jean Delvare <jdelvare@suse.de> Thanks go to Tyan and especially Alex Buckingham for setting up a remote access to their S4882 test platform for this driver. + http://www.tyan.com/ Description @@ -32,6 +49,7 @@ and control. The LM63 is basically an LM86 with fan speed monitoring and control capabilities added. It misses some of the LM86 features though: + - No low limit for local temperature. - No critical limit for local temperature. - Critical limit for remote temperature can be changed only once. We diff --git a/Documentation/hwmon/lm70 b/Documentation/hwmon/lm70.rst index c3a1f2ea017d..f259bc1fcd91 100644 --- a/Documentation/hwmon/lm70 +++ b/Documentation/hwmon/lm70.rst @@ -2,19 +2,30 @@ Kernel driver lm70 ================== Supported chips: + * National Semiconductor LM70 + Datasheet: http://www.national.com/pf/LM/LM70.html + * Texas Instruments TMP121/TMP123 + Information: http://focus.ti.com/docs/prod/folders/print/tmp121.html + * Texas Instruments TMP122/TMP124 + Information: http://www.ti.com/product/tmp122 + * National Semiconductor LM71 + Datasheet: http://www.ti.com/product/LM71 + * National Semiconductor LM74 + Datasheet: http://www.ti.com/product/LM74 + Author: - Kaiwan N Billimoria <kaiwan@designergraphix.com> + Kaiwan N Billimoria <kaiwan@designergraphix.com> Description ----------- diff --git a/Documentation/hwmon/lm73 b/Documentation/hwmon/lm73.rst index 8af059dcb642..1d6a46844e85 100644 --- a/Documentation/hwmon/lm73 +++ b/Documentation/hwmon/lm73.rst @@ -2,13 +2,20 @@ Kernel driver lm73 ================== Supported chips: + * Texas Instruments LM73 + Prefix: 'lm73' + Addresses scanned: I2C 0x48, 0x49, 0x4a, 0x4c, 0x4d, and 0x4e + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/lm73 + + http://www.ti.com/product/lm73 + Author: Guillaume Ligneul <guillaume.ligneul@gmail.com> + Documentation: Chris Verges <kg4ysn@gmail.com> @@ -29,17 +36,18 @@ conversion time via the 'update_interval' sysfs attribute for the device. This attribute will normalize ranges of input values to the maximum times defined for the resolution in the datasheet. + ============= ============= ============ Resolution Conv. Time Input Range (C/LSB) (msec) (msec) - -------------------------------------- + ============= ============= ============ 0.25 14 0..14 0.125 28 15..28 0.0625 56 29..56 0.03125 112 57..infinity - -------------------------------------- + ============= ============= ============ The following examples show how the 'update_interval' attribute can be -used to change the conversion time: +used to change the conversion time:: $ echo 0 > update_interval $ cat update_interval diff --git a/Documentation/hwmon/lm75 b/Documentation/hwmon/lm75.rst index 010583608f12..ba8acbd2a6cb 100644 --- a/Documentation/hwmon/lm75 +++ b/Documentation/hwmon/lm75.rst @@ -2,68 +2,132 @@ Kernel driver lm75 ================== Supported chips: + * National Semiconductor LM75 + Prefix: 'lm75' + Addresses scanned: I2C 0x48 - 0x4f + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ + + http://www.national.com/ + * National Semiconductor LM75A + Prefix: 'lm75a' + Addresses scanned: I2C 0x48 - 0x4f + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ + + http://www.national.com/ + * Dallas Semiconductor (now Maxim) DS75, DS1775, DS7505 + Prefixes: 'ds75', 'ds1775', 'ds7505' + Addresses scanned: none + Datasheet: Publicly available at the Maxim website - http://www.maximintegrated.com/ + + http://www.maximintegrated.com/ + * Maxim MAX6625, MAX6626, MAX31725, MAX31726 + Prefixes: 'max6625', 'max6626', 'max31725', 'max31726' + Addresses scanned: none + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/ + + http://www.maxim-ic.com/ + * Microchip (TelCom) TCN75 + Prefix: 'tcn75' + Addresses scanned: none + Datasheet: Publicly available at the Microchip website - http://www.microchip.com/ + + http://www.microchip.com/ + * Microchip MCP9800, MCP9801, MCP9802, MCP9803 + Prefix: 'mcp980x' + Addresses scanned: none + Datasheet: Publicly available at the Microchip website - http://www.microchip.com/ + + http://www.microchip.com/ + * Analog Devices ADT75 + Prefix: 'adt75' + Addresses scanned: none + Datasheet: Publicly available at the Analog Devices website - http://www.analog.com/adt75 + + http://www.analog.com/adt75 + * ST Microelectronics STDS75 + Prefix: 'stds75' + Addresses scanned: none + Datasheet: Publicly available at the ST website - http://www.st.com/internet/analog/product/121769.jsp + + http://www.st.com/internet/analog/product/121769.jsp + * ST Microelectronics STLM75 + Prefix: 'stlm75' + Addresses scanned: none + Datasheet: Publicly available at the ST website + https://www.st.com/resource/en/datasheet/stlm75.pdf - * Texas Instruments TMP100, TMP101, TMP105, TMP112, TMP75, TMP75C, TMP175, TMP275 - Prefixes: 'tmp100', 'tmp101', 'tmp105', 'tmp112', 'tmp175', 'tmp75', 'tmp75c', 'tmp275' + + * Texas Instruments TMP100, TMP101, TMP105, TMP112, TMP75, TMP75B, TMP75C, TMP175, TMP275 + + Prefixes: 'tmp100', 'tmp101', 'tmp105', 'tmp112', 'tmp175', 'tmp75', 'tmp75b', 'tmp75c', 'tmp275' + Addresses scanned: none + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/tmp100 - http://www.ti.com/product/tmp101 - http://www.ti.com/product/tmp105 - http://www.ti.com/product/tmp112 - http://www.ti.com/product/tmp75 - http://www.ti.com/product/tmp75c - http://www.ti.com/product/tmp175 - http://www.ti.com/product/tmp275 + + http://www.ti.com/product/tmp100 + + http://www.ti.com/product/tmp101 + + http://www.ti.com/product/tmp105 + + http://www.ti.com/product/tmp112 + + http://www.ti.com/product/tmp75 + + http://www.ti.com/product/tmp75b + + http://www.ti.com/product/tmp75c + + http://www.ti.com/product/tmp175 + + http://www.ti.com/product/tmp275 + * NXP LM75B + Prefix: 'lm75b' + Addresses scanned: none + Datasheet: Publicly available at the NXP website - http://www.nxp.com/documents/data_sheet/LM75B.pdf + + http://www.nxp.com/documents/data_sheet/LM75B.pdf Author: Frodo Looijaard <frodol@dds.nl> diff --git a/Documentation/hwmon/lm77 b/Documentation/hwmon/lm77.rst index bfc915fe3639..4ed3fe6b999a 100644 --- a/Documentation/hwmon/lm77 +++ b/Documentation/hwmon/lm77.rst @@ -2,11 +2,17 @@ Kernel driver lm77 ================== Supported chips: + * National Semiconductor LM77 + Prefix: 'lm77' + Addresses scanned: I2C 0x48 - 0x4b + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ + + http://www.national.com/ + Author: Andras BALI <drewie@freemail.hu> @@ -25,6 +31,7 @@ register on the chip, which means that the relative difference between the limit and its hysteresis is always the same for all 3 limits. This implementation detail implies the following: + * When setting a limit, its hysteresis will automatically follow, the difference staying unchanged. For example, if the old critical limit was 80 degrees C, and the hysteresis was 75 degrees C, and you change diff --git a/Documentation/hwmon/lm78 b/Documentation/hwmon/lm78.rst index 4dd47731789f..cb7a4832f35e 100644 --- a/Documentation/hwmon/lm78 +++ b/Documentation/hwmon/lm78.rst @@ -2,19 +2,31 @@ Kernel driver lm78 ================== Supported chips: + * National Semiconductor LM78 / LM78-J + Prefix: 'lm78' + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ + + http://www.national.com/ + * National Semiconductor LM79 + Prefix: 'lm79' + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ -Authors: Frodo Looijaard <frodol@dds.nl> - Jean Delvare <jdelvare@suse.de> + http://www.national.com/ + + +Authors: + - Frodo Looijaard <frodol@dds.nl> + - Jean Delvare <jdelvare@suse.de> Description ----------- diff --git a/Documentation/hwmon/lm80 b/Documentation/hwmon/lm80.rst index a60b43efc32b..c53186abd82e 100644 --- a/Documentation/hwmon/lm80 +++ b/Documentation/hwmon/lm80.rst @@ -2,20 +2,31 @@ Kernel driver lm80 ================== Supported chips: + * National Semiconductor LM80 + Prefix: 'lm80' + Addresses scanned: I2C 0x28 - 0x2f + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ + + http://www.national.com/ + * National Semiconductor LM96080 + Prefix: 'lm96080' + Addresses scanned: I2C 0x28 - 0x2f + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/ + + http://www.national.com/ + Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com> + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com> Description ----------- diff --git a/Documentation/hwmon/lm83 b/Documentation/hwmon/lm83.rst index 50be5cb26de9..ecf83819960e 100644 --- a/Documentation/hwmon/lm83 +++ b/Documentation/hwmon/lm83.rst @@ -2,16 +2,24 @@ Kernel driver lm83 ================== Supported chips: + * National Semiconductor LM83 + Prefix: 'lm83' + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM83.html + + http://www.national.com/pf/LM/LM83.html + * National Semiconductor LM82 + Addresses scanned: I2C 0x18 - 0x1a, 0x29 - 0x2b, 0x4c - 0x4e + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM82.html + http://www.national.com/pf/LM/LM82.html Author: Jean Delvare <jdelvare@suse.de> @@ -34,13 +42,17 @@ fact that any of these motherboards do actually have an LM83, please contact us. Note that the LM90 can easily be misdetected as a LM83. Confirmed motherboards: + === ===== SBS P014 SBS PSL09 + === ===== Unconfirmed motherboards: + =========== ========== Gigabyte GA-8IK1100 Iwill MPX2 Soltek SL-75DRV5 + =========== ========== The LM82 is confirmed to have been found on most AMD Geode reference designs and test platforms. diff --git a/Documentation/hwmon/lm85 b/Documentation/hwmon/lm85.rst index 2329c383efe4..faa92f54431c 100644 --- a/Documentation/hwmon/lm85 +++ b/Documentation/hwmon/lm85.rst @@ -2,49 +2,85 @@ Kernel driver lm85 ================== Supported chips: + * National Semiconductor LM85 (B and C versions) + Prefix: 'lm85b' or 'lm85c' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.national.com/pf/LM/LM85.html + * Texas Instruments LM96000 + Prefix: 'lm9600' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.ti.com/lit/ds/symlink/lm96000.pdf + * Analog Devices ADM1027 + Prefix: 'adm1027' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADM1027 + * Analog Devices ADT7463 + Prefix: 'adt7463' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7463 + * Analog Devices ADT7468 + Prefix: 'adt7468' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7468 + * SMSC EMC6D100, SMSC EMC6D101 + Prefix: 'emc6d100' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e - Datasheet: http://www.smsc.com/media/Downloads_Public/discontinued/6d100.pdf + + Datasheet: http://www.smsc.com/media/Downloads_Public/discontinued/6d100.pdf + * SMSC EMC6D102 + Prefix: 'emc6d102' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.smsc.com/main/catalog/emc6d102.html + * SMSC EMC6D103 + Prefix: 'emc6d103' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.smsc.com/main/catalog/emc6d103.html + * SMSC EMC6D103S + Prefix: 'emc6d103s' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.smsc.com/main/catalog/emc6d103s.html Authors: - Philip Pokorny <ppokorny@penguincomputing.com>, - Frodo Looijaard <frodol@dds.nl>, - Richard Barrington <rich_b_nz@clear.net.nz>, - Margit Schubert-While <margitsw@t-online.de>, - Justin Thiessen <jthiessen@penguincomputing.com> + - Philip Pokorny <ppokorny@penguincomputing.com>, + - Frodo Looijaard <frodol@dds.nl>, + - Richard Barrington <rich_b_nz@clear.net.nz>, + - Margit Schubert-While <margitsw@t-online.de>, + - Justin Thiessen <jthiessen@penguincomputing.com> Description ----------- @@ -177,38 +213,50 @@ Each temperature sensor is associated with a Zone. There are three sensors and therefore three zones (# 1, 2 and 3). Each zone has the following temperature configuration points: -* temp#_auto_temp_off - temperature below which fans should be off or spinning very low. -* temp#_auto_temp_min - temperature over which fans start to spin. -* temp#_auto_temp_max - temperature when fans spin at full speed. -* temp#_auto_temp_crit - temperature when all fans will run full speed. +* temp#_auto_temp_off + - temperature below which fans should be off or spinning very low. +* temp#_auto_temp_min + - temperature over which fans start to spin. +* temp#_auto_temp_max + - temperature when fans spin at full speed. +* temp#_auto_temp_crit + - temperature when all fans will run full speed. -* PWM Control +PWM Control +^^^^^^^^^^^ There are three PWM outputs. The LM85 datasheet suggests that the pwm3 output control both fan3 and fan4. Each PWM can be individually configured and assigned to a zone for its control value. Each PWM can be configured individually according to the following options. -* pwm#_auto_pwm_min - this specifies the PWM value for temp#_auto_temp_off - temperature. (PWM value from 0 to 255) +* pwm#_auto_pwm_min + - this specifies the PWM value for temp#_auto_temp_off + temperature. (PWM value from 0 to 255) + +* pwm#_auto_pwm_minctl + - this flags selects for temp#_auto_temp_off temperature + the behaviour of fans. Write 1 to let fans spinning at + pwm#_auto_pwm_min or write 0 to let them off. -* pwm#_auto_pwm_minctl - this flags selects for temp#_auto_temp_off temperature - the behaviour of fans. Write 1 to let fans spinning at - pwm#_auto_pwm_min or write 0 to let them off. +.. note:: -NOTE: It has been reported that there is a bug in the LM85 that causes the flag -to be associated with the zones not the PWMs. This contradicts all the -published documentation. Setting pwm#_min_ctl in this case actually affects all -PWMs controlled by zone '#'. + It has been reported that there is a bug in the LM85 that causes + the flag to be associated with the zones not the PWMs. This + contradicts all the published documentation. Setting pwm#_min_ctl + in this case actually affects all PWMs controlled by zone '#'. -* PWM Controlling Zone selection +PWM Controlling Zone selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* pwm#_auto_channels - controls zone that is associated with PWM +* pwm#_auto_channels + - controls zone that is associated with PWM Configuration choices: - Value Meaning - ------ ------------------------------------------------ +========== ============================================= +Value Meaning +========== ============================================= 1 Controlled by Zone 1 2 Controlled by Zone 2 3 Controlled by Zone 3 @@ -217,6 +265,7 @@ Configuration choices: 0 PWM always 0% (off) -1 PWM always 100% (full on) -2 Manual control (write to 'pwm#' to set) +========== ============================================= The National LM85's have two vendor specific configuration features. Tach. mode and Spinup Control. For more details on these, diff --git a/Documentation/hwmon/lm87 b/Documentation/hwmon/lm87.rst index a2339fd9acb9..72fcb577ef2a 100644 --- a/Documentation/hwmon/lm87 +++ b/Documentation/hwmon/lm87.rst @@ -2,23 +2,32 @@ Kernel driver lm87 ================== Supported chips: + * National Semiconductor LM87 + Prefix: 'lm87' + Addresses scanned: I2C 0x2c - 0x2e + Datasheet: http://www.national.com/pf/LM/LM87.html + * Analog Devices ADM1024 + Prefix: 'adm1024' + Addresses scanned: I2C 0x2c - 0x2e + Datasheet: http://www.analog.com/en/prod/0,2877,ADM1024,00.html + Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark Studebaker <mdsxyz123@yahoo.com>, - Stephen Rousset <stephen.rousset@rocketlogix.com>, - Dan Eaton <dan.eaton@rocketlogix.com>, - Jean Delvare <jdelvare@suse.de>, - Original 2.6 port Jeff Oliver + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com>, + - Mark Studebaker <mdsxyz123@yahoo.com>, + - Stephen Rousset <stephen.rousset@rocketlogix.com>, + - Dan Eaton <dan.eaton@rocketlogix.com>, + - Jean Delvare <jdelvare@suse.de>, + - Original 2.6 port Jeff Oliver Description ----------- diff --git a/Documentation/hwmon/lm90 b/Documentation/hwmon/lm90.rst index 8122675d30f6..953315987c06 100644 --- a/Documentation/hwmon/lm90 +++ b/Documentation/hwmon/lm90.rst @@ -2,132 +2,256 @@ Kernel driver lm90 ================== Supported chips: + * National Semiconductor LM90 + Prefix: 'lm90' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM90.html + + http://www.national.com/pf/LM/LM90.html + * National Semiconductor LM89 + Prefix: 'lm89' (no auto-detection) + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/mpf/LM/LM89.html + + http://www.national.com/mpf/LM/LM89.html + * National Semiconductor LM99 + Prefix: 'lm99' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/pf/LM/LM99.html + + http://www.national.com/pf/LM/LM99.html + * National Semiconductor LM86 + Prefix: 'lm86' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the National Semiconductor website - http://www.national.com/mpf/LM/LM86.html + + http://www.national.com/mpf/LM/LM86.html + * Analog Devices ADM1032 + Prefix: 'adm1032' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=ADM1032 + + http://www.onsemi.com/PowerSolutions/product.do?id=ADM1032 + * Analog Devices ADT7461 + Prefix: 'adt7461' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461 + + http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461 + * Analog Devices ADT7461A + Prefix: 'adt7461a' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A + + http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461A + * ON Semiconductor NCT1008 + Prefix: 'nct1008' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: Publicly available at the ON Semiconductor website - http://www.onsemi.com/PowerSolutions/product.do?id=NCT1008 + + http://www.onsemi.com/PowerSolutions/product.do?id=NCT1008 + * Maxim MAX6646 + Prefix: 'max6646' + Addresses scanned: I2C 0x4d + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + * Maxim MAX6647 + Prefix: 'max6646' + Addresses scanned: I2C 0x4e + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + * Maxim MAX6648 + Prefix: 'max6646' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500 + * Maxim MAX6649 + Prefix: 'max6646' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497 + * Maxim MAX6657 + Prefix: 'max6657' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 + * Maxim MAX6658 + Prefix: 'max6657' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 + * Maxim MAX6659 + Prefix: 'max6659' + Addresses scanned: I2C 0x4c, 0x4d, 0x4e + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 + * Maxim MAX6680 + Prefix: 'max6680' + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, - 0x4c, 0x4d and 0x4e + + 0x4c, 0x4d and 0x4e + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370 + * Maxim MAX6681 + Prefix: 'max6680' + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, - 0x4c, 0x4d and 0x4e + + 0x4c, 0x4d and 0x4e + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370 + * Maxim MAX6692 + Prefix: 'max6646' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500 + + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3500 + * Maxim MAX6695 + Prefix: 'max6695' + Addresses scanned: I2C 0x18 + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/datasheet/index.mvp/id/4199 + + http://www.maxim-ic.com/datasheet/index.mvp/id/4199 + * Maxim MAX6696 + Prefix: 'max6695' + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, - 0x4c, 0x4d and 0x4e + + 0x4c, 0x4d and 0x4e + Datasheet: Publicly available at the Maxim website - http://www.maxim-ic.com/datasheet/index.mvp/id/4199 + + http://www.maxim-ic.com/datasheet/index.mvp/id/4199 + * Winbond/Nuvoton W83L771W/G + Prefix: 'w83l771' + Addresses scanned: I2C 0x4c + Datasheet: No longer available + * Winbond/Nuvoton W83L771AWG/ASG + Prefix: 'w83l771' + Addresses scanned: I2C 0x4c + Datasheet: Not publicly available, can be requested from Nuvoton + * Philips/NXP SA56004X + Prefix: 'sa56004' + Addresses scanned: I2C 0x48 through 0x4F + Datasheet: Publicly available at NXP website - http://ics.nxp.com/products/interface/datasheet/sa56004x.pdf + + http://ics.nxp.com/products/interface/datasheet/sa56004x.pdf + * GMT G781 + Prefix: 'g781' + Addresses scanned: I2C 0x4c, 0x4d + Datasheet: Not publicly available from GMT + * Texas Instruments TMP451 + Prefix: 'tmp451' + Addresses scanned: I2C 0x4c + Datasheet: Publicly available at TI website - http://www.ti.com/litv/pdf/sbos686 + http://www.ti.com/litv/pdf/sbos686 Author: Jean Delvare <jdelvare@suse.de> diff --git a/Documentation/hwmon/lm92 b/Documentation/hwmon/lm92.rst index cfa99a353b8c..c131b923ed36 100644 --- a/Documentation/hwmon/lm92 +++ b/Documentation/hwmon/lm92.rst @@ -2,22 +2,35 @@ Kernel driver lm92 ================== Supported chips: + * National Semiconductor LM92 + Prefix: 'lm92' + Addresses scanned: I2C 0x48 - 0x4b + Datasheet: http://www.national.com/pf/LM/LM92.html + * National Semiconductor LM76 + Prefix: 'lm92' + Addresses scanned: none, force parameter needed + Datasheet: http://www.national.com/pf/LM/LM76.html + * Maxim MAX6633/MAX6634/MAX6635 + Prefix: 'max6635' + Addresses scanned: none, force parameter needed + Datasheet: http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3074 + Authors: - Abraham van der Merwe <abraham@2d3d.co.za> - Jean Delvare <jdelvare@suse.de> + - Abraham van der Merwe <abraham@2d3d.co.za> + - Jean Delvare <jdelvare@suse.de> Description diff --git a/Documentation/hwmon/lm93 b/Documentation/hwmon/lm93.rst index f3b2ad2ceb01..49d199b45b67 100644 --- a/Documentation/hwmon/lm93 +++ b/Documentation/hwmon/lm93.rst @@ -2,20 +2,29 @@ Kernel driver lm93 ================== Supported chips: + * National Semiconductor LM93 + Prefix 'lm93' + Addresses scanned: I2C 0x2c-0x2e + Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf + * National Semiconductor LM94 + Prefix 'lm94' + Addresses scanned: I2C 0x2c-0x2e + Datasheet: http://www.national.com/ds.cgi/LM/LM94.pdf + Authors: - Mark M. Hoffman <mhoffman@lightlink.com> - Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com> - Adapted to 2.6.20 by Carsten Emde <ce@osadl.org> - Modified for mainline integration by Hans J. Koch <hjk@hansjkoch.de> + - Mark M. Hoffman <mhoffman@lightlink.com> + - Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com> + - Adapted to 2.6.20 by Carsten Emde <ce@osadl.org> + - Modified for mainline integration by Hans J. Koch <hjk@hansjkoch.de> Module Parameters ----------------- @@ -67,7 +76,8 @@ LM94 are not supported. User Interface -------------- -#PROCHOT: +#PROCHOT +^^^^^^^^ The LM93 can monitor two #PROCHOT signals. The results are found in the sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max, @@ -86,7 +96,8 @@ prochot2_interval. The values in these files specify the intervals for list will cause the driver to use the next largest interval. The available intervals are (in seconds): -#PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372 +#PROCHOT intervals: + 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372 It is possible to configure the LM93 to logically short the two #PROCHOT signals. I.e. when #P1_PROCHOT is asserted, the LM93 will automatically @@ -105,16 +116,15 @@ contains a value controlling the duty cycle for the PWM signal used when the override function is enabled. This value ranges from 0 to 15, with 0 indicating minimum duty cycle and 15 indicating maximum. -#VRD_HOT: +#VRD_HOT +^^^^^^^^ The LM93 can monitor two #VRD_HOT signals. The results are found in the sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These files are read-only. -Smart Tach Mode: - -(from the datasheet) +Smart Tach Mode (from the datasheet):: If a fan is driven using a low-side drive PWM, the tachometer output of the fan is corrupted. The LM93 includes smart tachometer @@ -127,7 +137,8 @@ the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero will disable the function for that fan. Note that Smart tach mode cannot be enabled if the PWM output frequency is 22500 Hz (see below). -Manual PWM: +Manual PWM +^^^^^^^^^^ The LM93 has a fixed or override mode for the two PWM outputs (although, there are still some conditions that will override even this mode - see section @@ -141,7 +152,8 @@ will cause the driver to use the next largest value. Also note: when manual PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty cycle chosen by the h/w. -PWM Output Frequency: +PWM Output Frequency +^^^^^^^^^^^^^^^^^^^^ The LM93 supports several different frequencies for the PWM output channels. The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The @@ -149,9 +161,11 @@ frequency values are constrained by the hardware. Selecting a value which is not available will cause the driver to use the next largest value. Also note that this parameter has implications for the Smart Tach Mode (see above). -PWM Output Frequencies (in Hz): 12, 36, 48, 60, 72, 84, 96, 22500 (default) +PWM Output Frequencies (in Hz): + 12, 36, 48, 60, 72, 84, 96, 22500 (default) -Automatic PWM: +Automatic PWM +^^^^^^^^^^^^^ The LM93 is capable of complex automatic fan control, with many different points of configuration. To start, each PWM output can be bound to any @@ -163,14 +177,16 @@ The eight control sources are: temp1-temp4 (aka "zones" in the datasheet), in the sysfs files pwm<n>_auto_channels, where a "1" enables the binding, and a "0" disables it. The h/w default is 0x0f (all temperatures bound). - 0x01 - Temp 1 - 0x02 - Temp 2 - 0x04 - Temp 3 - 0x08 - Temp 4 - 0x10 - #PROCHOT 1 - 0x20 - #PROCHOT 2 - 0x40 - #VRDHOT 1 - 0x80 - #VRDHOT 2 + ====== =========== + 0x01 Temp 1 + 0x02 Temp 2 + 0x04 Temp 3 + 0x08 Temp 4 + 0x10 #PROCHOT 1 + 0x20 #PROCHOT 2 + 0x40 #VRDHOT 1 + 0x80 #VRDHOT 2 + ====== =========== The function y = f(x) takes a source temperature x to a PWM output y. This function of the LM93 is derived from a base temperature and a table of 12 @@ -180,7 +196,9 @@ degrees C, with the value of offset <i> for temperature value <n> being contained in the file temp<n>_auto_offset<i>. E.g. if the base temperature is 40C: + ========== ======================= =============== ======= offset # temp<n>_auto_offset<i> range pwm + ========== ======================= =============== ======= 1 0 - 25.00% 2 0 - 28.57% 3 1 40C - 41C 32.14% @@ -193,7 +211,8 @@ is 40C: 10 2 54C - 56C 57.14% 11 2 56C - 58C 71.43% 12 2 58C - 60C 85.71% - > 60C 100.00% + - - > 60C 100.00% + ========== ======================= =============== ======= Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments. @@ -213,7 +232,8 @@ temp<n>_auto_pwm_min. Note, there are only two minimums: one each for temp[12] and temp[34]. Therefore, any change to e.g. temp1_auto_pwm_min will also affect temp2_auto_pwm_min. -PWM Spin-Up Cycle: +PWM Spin-Up Cycle +^^^^^^^^^^^^^^^^^ A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to some value > 0%. The LM93 supports a minimum duty cycle during spin-up. These @@ -225,10 +245,11 @@ the spin-up time in seconds. The available spin-up times are constrained by the hardware. Selecting a value which is not available will cause the driver to use the next largest value. -Spin-up Durations: 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0, - 2.0, 4.0 +Spin-up Durations: + 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0, 2.0, 4.0 -#PROCHOT and #VRDHOT PWM Ramping: +#PROCHOT and #VRDHOT PWM Ramping +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete @@ -237,9 +258,11 @@ one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp. The available ramp times are constrained by the hardware. Selecting a value which is not available will cause the driver to use the next largest value. -Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals +Ramp Times: + 0 (disabled, h/w default) to 0.75 in 0.05 second intervals -Fan Boost: +Fan Boost +^^^^^^^^^ For each temperature channel, there is a boost temperature: if the channel exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%. @@ -249,7 +272,8 @@ limit is reached, the temperature channel must drop below this value before the boost function is disabled. This temperature is also expressed in degrees C in the sysfs files temp<n>_auto_boost_hyst. -GPIO Pins: +GPIO Pins +^^^^^^^^^ The LM93 can monitor the logic level of four dedicated GPIO pins as well as the four tach input pins. GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively. @@ -260,50 +284,29 @@ LSB is GPIO0, and the MSB is GPIO7. LM93 Unique sysfs Files ----------------------- - file description - ------------------------------------------------------------- - - prochot<n> current #PROCHOT % - - prochot<n>_avg moving average #PROCHOT % - - prochot<n>_max limit #PROCHOT % - - prochot_short enable or disable logical #PROCHOT pin short - - prochot<n>_override force #PROCHOT assertion as PWM - - prochot_override_duty_cycle - duty cycle for the PWM signal used when - #PROCHOT is overridden - - prochot<n>_interval #PROCHOT PWM sampling interval - - vrdhot<n> 0 means negated, 1 means asserted - - fan<n>_smart_tach enable or disable smart tach mode - - pwm<n>_auto_channels select control sources for PWM outputs - - pwm<n>_auto_spinup_min minimum duty cycle during spin-up - - pwm<n>_auto_spinup_time duration of spin-up - - pwm_auto_prochot_ramp ramp time per step when #PROCHOT asserted - - pwm_auto_vrdhot_ramp ramp time per step when #VRDHOT asserted - - temp<n>_auto_base temperature channel base - - temp<n>_auto_offset[1-12] - temperature channel offsets - - temp<n>_auto_offset_hyst - temperature channel offset hysteresis - - temp<n>_auto_boost temperature channel boost (PWMs to 100%) limit - - temp<n>_auto_boost_hyst temperature channel boost hysteresis - - gpio input state of 8 GPIO pins; read-only - +=========================== =============================================== +file description +=========================== =============================================== +prochot<n> current #PROCHOT % +prochot<n>_avg moving average #PROCHOT % +prochot<n>_max limit #PROCHOT % +prochot_short enable or disable logical #PROCHOT pin short +prochot<n>_override force #PROCHOT assertion as PWM +prochot_override_duty_cycle duty cycle for the PWM signal used when + #PROCHOT is overridden +prochot<n>_interval #PROCHOT PWM sampling interval +vrdhot<n> 0 means negated, 1 means asserted +fan<n>_smart_tach enable or disable smart tach mode +pwm<n>_auto_channels select control sources for PWM outputs +pwm<n>_auto_spinup_min minimum duty cycle during spin-up +pwm<n>_auto_spinup_time duration of spin-up +pwm_auto_prochot_ramp ramp time per step when #PROCHOT asserted +pwm_auto_vrdhot_ramp ramp time per step when #VRDHOT asserted +temp<n>_auto_base temperature channel base +temp<n>_auto_offset[1-12] temperature channel offsets +temp<n>_auto_offset_hyst temperature channel offset hysteresis +temp<n>_auto_boost temperature channel boost (PWMs to 100%) + limit +temp<n>_auto_boost_hyst temperature channel boost hysteresis +gpio input state of 8 GPIO pins; read-only +=========================== =============================================== diff --git a/Documentation/hwmon/lm95234 b/Documentation/hwmon/lm95234.rst index 32b777ef224c..e4c14bea5efd 100644 --- a/Documentation/hwmon/lm95234 +++ b/Documentation/hwmon/lm95234.rst @@ -2,15 +2,22 @@ Kernel driver lm95234 ===================== Supported chips: + * National Semiconductor / Texas Instruments LM95233 + Addresses scanned: I2C 0x18, 0x2a, 0x2b + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/lm95233 + + http://www.ti.com/product/lm95233 + * National Semiconductor / Texas Instruments LM95234 + Addresses scanned: I2C 0x18, 0x4d, 0x4e + Datasheet: Publicly available at the Texas Instruments website - http://www.ti.com/product/lm95234 + http://www.ti.com/product/lm95234 Author: Guenter Roeck <linux@roeck-us.net> diff --git a/Documentation/hwmon/lm95245 b/Documentation/hwmon/lm95245.rst index d755901f58c4..566d1dc8c5a6 100644 --- a/Documentation/hwmon/lm95245 +++ b/Documentation/hwmon/lm95245.rst @@ -1,16 +1,23 @@ Kernel driver lm95245 -================== +===================== Supported chips: + * TI LM95235 + Addresses scanned: I2C 0x18, 0x29, 0x4c + Datasheet: Publicly available at the TI website - http://www.ti.com/lit/ds/symlink/lm95235.pdf + + http://www.ti.com/lit/ds/symlink/lm95235.pdf + * TI / National Semiconductor LM95245 + Addresses scanned: I2C 0x18, 0x19, 0x29, 0x4c, 0x4d + Datasheet: Publicly available at the TI website - http://www.ti.com/lit/ds/symlink/lm95245.pdf + http://www.ti.com/lit/ds/symlink/lm95245.pdf Author: Alexander Stein <alexander.stein@systec-electronic.com> diff --git a/Documentation/hwmon/lochnagar.rst b/Documentation/hwmon/lochnagar.rst new file mode 100644 index 000000000000..1d609c4d18c3 --- /dev/null +++ b/Documentation/hwmon/lochnagar.rst @@ -0,0 +1,83 @@ +Kernel Driver Lochnagar +======================= + +Supported systems: + * Cirrus Logic : Lochnagar 2 + +Author: Lucas A. Tanure Alves + +Description +----------- + +Lochnagar 2 features built-in Current Monitor circuitry that allows for the +measurement of both voltage and current on up to eight of the supply voltage +rails provided to the minicards. The Current Monitor does not require any +hardware modifications or external circuitry to operate. + +The current and voltage measurements are obtained through the standard register +map interface to the Lochnagar board controller, and can therefore be monitored +by software. + +Sysfs attributes +---------------- + +======================= ======================================================= +temp1_input The Lochnagar board temperature (milliCelsius) +in0_input Measured voltage for DBVDD1 (milliVolts) +in0_label "DBVDD1" +curr1_input Measured current for DBVDD1 (milliAmps) +curr1_label "DBVDD1" +power1_average Measured average power for DBVDD1 (microWatts) +power1_average_interval Power averaging time input valid from 1 to 1708mS +power1_label "DBVDD1" +in1_input Measured voltage for 1V8 DSP (milliVolts) +in1_label "1V8 DSP" +curr2_input Measured current for 1V8 DSP (milliAmps) +curr2_label "1V8 DSP" +power2_average Measured average power for 1V8 DSP (microWatts) +power2_average_interval Power averaging time input valid from 1 to 1708mS +power2_label "1V8 DSP" +in2_input Measured voltage for 1V8 CDC (milliVolts) +in2_label "1V8 CDC" +curr3_input Measured current for 1V8 CDC (milliAmps) +curr3_label "1V8 CDC" +power3_average Measured average power for 1V8 CDC (microWatts) +power3_average_interval Power averaging time input valid from 1 to 1708mS +power3_label "1V8 CDC" +in3_input Measured voltage for VDDCORE DSP (milliVolts) +in3_label "VDDCORE DSP" +curr4_input Measured current for VDDCORE DSP (milliAmps) +curr4_label "VDDCORE DSP" +power4_average Measured average power for VDDCORE DSP (microWatts) +power4_average_interval Power averaging time input valid from 1 to 1708mS +power4_label "VDDCORE DSP" +in4_input Measured voltage for AVDD 1V8 (milliVolts) +in4_label "AVDD 1V8" +curr5_input Measured current for AVDD 1V8 (milliAmps) +curr5_label "AVDD 1V8" +power5_average Measured average power for AVDD 1V8 (microWatts) +power5_average_interval Power averaging time input valid from 1 to 1708mS +power5_label "AVDD 1V8" +curr6_input Measured current for SYSVDD (milliAmps) +curr6_label "SYSVDD" +power6_average Measured average power for SYSVDD (microWatts) +power6_average_interval Power averaging time input valid from 1 to 1708mS +power6_label "SYSVDD" +in6_input Measured voltage for VDDCORE CDC (milliVolts) +in6_label "VDDCORE CDC" +curr7_input Measured current for VDDCORE CDC (milliAmps) +curr7_label "VDDCORE CDC" +power7_average Measured average power for VDDCORE CDC (microWatts) +power7_average_interval Power averaging time input valid from 1 to 1708mS +power7_label "VDDCORE CDC" +in7_input Measured voltage for MICVDD (milliVolts) +in7_label "MICVDD" +curr8_input Measured current for MICVDD (milliAmps) +curr8_label "MICVDD" +power8_average Measured average power for MICVDD (microWatts) +power8_average_interval Power averaging time input valid from 1 to 1708mS +power8_label "MICVDD" +======================= ======================================================= + +Note: + It is not possible to measure voltage on the SYSVDD rail. diff --git a/Documentation/hwmon/ltc2945 b/Documentation/hwmon/ltc2945.rst index f8d0f7f19adb..20c884985367 100644 --- a/Documentation/hwmon/ltc2945 +++ b/Documentation/hwmon/ltc2945.rst @@ -2,11 +2,16 @@ Kernel driver ltc2945 ===================== Supported chips: + * Linear Technology LTC2945 + Prefix: 'ltc2945' + Addresses scanned: - + Datasheet: - http://cds.linear.com/docs/en/datasheet/2945fa.pdf + + http://cds.linear.com/docs/en/datasheet/2945fa.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -26,9 +31,10 @@ which can be safely used to identify the chip. You will have to instantiate the devices explicitly. Example: the following will load the driver for an LTC2945 at address 0x10 -on I2C bus #1: -$ modprobe ltc2945 -$ echo ltc2945 0x10 > /sys/bus/i2c/devices/i2c-1/new_device +on I2C bus #1:: + + $ modprobe ltc2945 + $ echo ltc2945 0x10 > /sys/bus/i2c/devices/i2c-1/new_device Sysfs entries @@ -45,6 +51,7 @@ Current Sense register. The reported value assumes that a 1 mOhm sense resistor is installed. If a different sense resistor is installed, calculate the real current by dividing the reported value by the sense resistor value in mOhm. +======================= ======================================================== in1_input VIN voltage (mV). Voltage is measured either at SENSE+ or VDD pin depending on chip configuration. in1_min Undervoltage threshold @@ -82,3 +89,4 @@ power1_input_highest Historical maximum power use power1_reset_history Write 1 to reset power1 history power1_min_alarm Low power alarm power1_max_alarm High power alarm +======================= ======================================================== diff --git a/Documentation/hwmon/ltc2978 b/Documentation/hwmon/ltc2978.rst index dfb2caa401d9..01a24fd6d5fe 100644 --- a/Documentation/hwmon/ltc2978 +++ b/Documentation/hwmon/ltc2978.rst @@ -2,85 +2,143 @@ Kernel driver ltc2978 ===================== Supported chips: + * Linear Technology LTC2974 + Prefix: 'ltc2974' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc2974 + * Linear Technology LTC2975 + Prefix: 'ltc2975' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc2975 + * Linear Technology LTC2977 + Prefix: 'ltc2977' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc2977 + * Linear Technology LTC2978, LTC2978A + Prefix: 'ltc2978' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc2978 - http://www.linear.com/product/ltc2978a + + http://www.linear.com/product/ltc2978a + * Linear Technology LTC2980 + Prefix: 'ltc2980' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc2980 + * Linear Technology LTC3880 + Prefix: 'ltc3880' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc3880 + * Linear Technology LTC3882 + Prefix: 'ltc3882' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc3882 + * Linear Technology LTC3883 + Prefix: 'ltc3883' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc3883 + * Linear Technology LTC3886 + Prefix: 'ltc3886' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc3886 + * Linear Technology LTC3887 + Prefix: 'ltc3887' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc3887 + * Linear Technology LTM2987 + Prefix: 'ltm2987' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltm2987 + * Linear Technology LTM4675 + Prefix: 'ltm4675' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltm4675 + * Linear Technology LTM4676 + Prefix: 'ltm4676' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltm4676 + * Analog Devices LTM4686 + Prefix: 'ltm4686' + Addresses scanned: - + Datasheet: http://www.analog.com/ltm4686 + Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -LTC2974 and LTC2975 are quad digital power supply managers. -LTC2978 is an octal power supply monitor. -LTC2977 is a pin compatible replacement for LTC2978. -LTC2980 is a 16-channel Power System Manager, consisting of two LTC2977 -in a single die. The chip is instantiated and reported as two separate chips -on two different I2C bus addresses. -LTC3880, LTC3882, LTC3886, and LTC3887 are dual output poly-phase step-down -DC/DC controllers. -LTC3883 is a single phase step-down DC/DC controller. -LTM2987 is a 16-channel Power System Manager with two LTC2977 plus -additional components on a single die. The chip is instantiated and reported -as two separate chips on two different I2C bus addresses. -LTM4675 is a dual 9A or single 18A ÎĽModule regulator -LTM4676 is a dual 13A or single 26A uModule regulator. -LTM4686 is a dual 10A or single 20A uModule regulator. +- LTC2974 and LTC2975 are quad digital power supply managers. +- LTC2978 is an octal power supply monitor. +- LTC2977 is a pin compatible replacement for LTC2978. +- LTC2980 is a 16-channel Power System Manager, consisting of two LTC2977 +- in a single die. The chip is instantiated and reported as two separate chips +- on two different I2C bus addresses. +- LTC3880, LTC3882, LTC3886, and LTC3887 are dual output poly-phase step-down +- DC/DC controllers. +- LTC3883 is a single phase step-down DC/DC controller. +- LTM2987 is a 16-channel Power System Manager with two LTC2977 plus +- additional components on a single die. The chip is instantiated and reported +- as two separate chips on two different I2C bus addresses. +- LTM4675 is a dual 9A or single 18A ÎĽModule regulator +- LTM4676 is a dual 13A or single 26A uModule regulator. +- LTM4686 is a dual 10A or single 20A uModule regulator. Usage Notes @@ -90,127 +148,208 @@ This driver does not probe for PMBus devices. You will have to instantiate devices explicitly. Example: the following commands will load the driver for an LTC2978 at address -0x60 on I2C bus #1: +0x60 on I2C bus #1:: -# modprobe ltc2978 -# echo ltc2978 0x60 > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe ltc2978 + # echo ltc2978 0x60 > /sys/bus/i2c/devices/i2c-1/new_device Sysfs attributes ---------------- +======================= ======================================================== in1_label "vin" + in1_input Measured input voltage. + in1_min Minimum input voltage. + in1_max Maximum input voltage. + LTC2974, LTC2975, LTC2977, LTC2980, LTC2978, and LTM2987 only. + in1_lcrit Critical minimum input voltage. + LTC2974, LTC2975, LTC2977, LTC2980, LTC2978, and LTM2987 only. + in1_crit Critical maximum input voltage. + in1_min_alarm Input voltage low alarm. + in1_max_alarm Input voltage high alarm. + LTC2974, LTC2975, LTC2977, LTC2980, LTC2978, and LTM2987 only. in1_lcrit_alarm Input voltage critical low alarm. + LTC2974, LTC2975, LTC2977, LTC2980, LTC2978, and LTM2987 only. in1_crit_alarm Input voltage critical high alarm. + in1_lowest Lowest input voltage. + LTC2974, LTC2975, LTC2977, LTC2980, LTC2978, and LTM2987 only. in1_highest Highest input voltage. + in1_reset_history Reset input voltage history. in[N]_label "vout[1-8]". - LTC2974, LTC2975: N=2-5 - LTC2977, LTC2980, LTM2987: N=2-9 - LTC2978: N=2-9 - LTC3880, LTC3882, LTC23886 LTC3887, LTM4675, LTM4676: - N=2-3 - LTC3883: N=2 + + - LTC2974, LTC2975: N=2-5 + - LTC2977, LTC2980, LTM2987: N=2-9 + - LTC2978: N=2-9 + - LTC3880, LTC3882, LTC23886 LTC3887, LTM4675, LTM4676: + N=2-3 + - LTC3883: N=2 + in[N]_input Measured output voltage. + in[N]_min Minimum output voltage. + in[N]_max Maximum output voltage. + in[N]_lcrit Critical minimum output voltage. + in[N]_crit Critical maximum output voltage. + in[N]_min_alarm Output voltage low alarm. + in[N]_max_alarm Output voltage high alarm. + in[N]_lcrit_alarm Output voltage critical low alarm. + in[N]_crit_alarm Output voltage critical high alarm. -in[N]_lowest Lowest output voltage. LTC2974, LTC2975, - and LTC2978 only. + +in[N]_lowest Lowest output voltage. + + + LTC2974, LTC2975,and LTC2978 only. + in[N]_highest Highest output voltage. + in[N]_reset_history Reset output voltage history. temp[N]_input Measured temperature. - On LTC2974 and LTC2975, temp[1-4] report external - temperatures, and temp5 reports the chip temperature. - On LTC2977, LTC2980, LTC2978, and LTM2987, only one - temperature measurement is supported and reports - the chip temperature. - On LTC3880, LTC3882, LTC3887, LTM4675, and LTM4676, - temp1 and temp2 report external temperatures, and temp3 - reports the chip temperature. - On LTC3883, temp1 reports an external temperature, - and temp2 reports the chip temperature. -temp[N]_min Mimimum temperature. LTC2974, LCT2977, LTM2980, LTC2978, - and LTM2987 only. + + - On LTC2974 and LTC2975, temp[1-4] report external + temperatures, and temp5 reports the chip temperature. + - On LTC2977, LTC2980, LTC2978, and LTM2987, only one + temperature measurement is supported and reports + the chip temperature. + - On LTC3880, LTC3882, LTC3887, LTM4675, and LTM4676, + temp1 and temp2 report external temperatures, and + temp3 reports the chip temperature. + - On LTC3883, temp1 reports an external temperature, + and temp2 reports the chip temperature. + +temp[N]_min Mimimum temperature. + + LTC2974, LCT2977, LTM2980, LTC2978, and LTM2987 only. + temp[N]_max Maximum temperature. + temp[N]_lcrit Critical low temperature. + temp[N]_crit Critical high temperature. + temp[N]_min_alarm Temperature low alarm. + LTC2974, LTC2975, LTC2977, LTM2980, LTC2978, and LTM2987 only. + temp[N]_max_alarm Temperature high alarm. + + temp[N]_lcrit_alarm Temperature critical low alarm. + temp[N]_crit_alarm Temperature critical high alarm. + temp[N]_lowest Lowest measured temperature. - LTC2974, LTC2975, LTC2977, LTM2980, LTC2978, and - LTM2987 only. - Not supported for chip temperature sensor on LTC2974 and - LTC2975. -temp[N]_highest Highest measured temperature. Not supported for chip - temperature sensor on LTC2974 and LTC2975. -temp[N]_reset_history Reset temperature history. Not supported for chip - temperature sensor on LTC2974 and LTC2975. + + - LTC2974, LTC2975, LTC2977, LTM2980, LTC2978, and + LTM2987 only. + - Not supported for chip temperature sensor on LTC2974 + and LTC2975. + +temp[N]_highest Highest measured temperature. + + Not supported for chip temperature sensor on + LTC2974 and LTC2975. + +temp[N]_reset_history Reset temperature history. + + Not supported for chip temperature sensor on + LTC2974 and LTC2975. power1_label "pin". LTC3883 and LTC3886 only. + power1_input Measured input power. power[N]_label "pout[1-4]". - LTC2974, LTC2975: N=1-4 - LTC2977, LTC2980, LTM2987: Not supported - LTC2978: Not supported - LTC3880, LTC3882, LTC3886, LTC3887, LTM4675, LTM4676: - N=1-2 - LTC3883: N=2 + + - LTC2974, LTC2975: N=1-4 + - LTC2977, LTC2980, LTM2987: Not supported + - LTC2978: Not supported + - LTC3880, LTC3882, LTC3886, LTC3887, LTM4675, LTM4676: + N=1-2 + - LTC3883: N=2 + power[N]_input Measured output power. -curr1_label "iin". LTC3880, LTC3883, LTC3886, LTC3887, LTM4675, +curr1_label "iin". + + LTC3880, LTC3883, LTC3886, LTC3887, LTM4675, and LTM4676 only. + curr1_input Measured input current. + curr1_max Maximum input current. + curr1_max_alarm Input current high alarm. -curr1_highest Highest input current. LTC3883 and LTC3886 only. -curr1_reset_history Reset input current history. LTC3883 and LTC3886 only. + +curr1_highest Highest input current. + + LTC3883 and LTC3886 only. + +curr1_reset_history Reset input current history. + + LTC3883 and LTC3886 only. curr[N]_label "iout[1-4]". - LTC2974, LTC2975: N=1-4 - LTC2977, LTC2980, LTM2987: not supported - LTC2978: not supported - LTC3880, LTC3882, LTC3886, LTC3887, LTM4675, LTM4676: - N=2-3 - LTC3883: N=2 + + - LTC2974, LTC2975: N=1-4 + - LTC2977, LTC2980, LTM2987: not supported + - LTC2978: not supported + - LTC3880, LTC3882, LTC3886, LTC3887, LTM4675, LTM4676: + N=2-3 + - LTC3883: N=2 + curr[N]_input Measured output current. + curr[N]_max Maximum output current. + curr[N]_crit Critical high output current. -curr[N]_lcrit Critical low output current. LTC2974 and LTC2975 only. + +curr[N]_lcrit Critical low output current. + + LTC2974 and LTC2975 only. + curr[N]_max_alarm Output current high alarm. + curr[N]_crit_alarm Output current critical high alarm. + curr[N]_lcrit_alarm Output current critical low alarm. + + LTC2974 and LTC2975 only. + +curr[N]_lowest Lowest output current. + LTC2974 and LTC2975 only. -curr[N]_lowest Lowest output current. LTC2974 and LTC2975 only. + curr[N]_highest Highest output current. + curr[N]_reset_history Reset output current history. +======================= ======================================================== diff --git a/Documentation/hwmon/ltc2990 b/Documentation/hwmon/ltc2990.rst index 3ed68f676c0f..e0a369e679d3 100644 --- a/Documentation/hwmon/ltc2990 +++ b/Documentation/hwmon/ltc2990.rst @@ -1,14 +1,23 @@ Kernel driver ltc2990 ===================== + Supported chips: + * Linear Technology LTC2990 + Prefix: 'ltc2990' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc2990 -Author: Mike Looijmans <mike.looijmans@topic.nl> - Tom Levens <tom.levens@cern.ch> + + +Author: + + - Mike Looijmans <mike.looijmans@topic.nl> + - Tom Levens <tom.levens@cern.ch> Description @@ -31,17 +40,21 @@ devices explicitly. Sysfs attributes ---------------- +============= ================================================== in0_input Voltage at Vcc pin in millivolt (range 2.5V to 5V) -temp1_input Internal chip temperature in millidegrees Celcius +temp1_input Internal chip temperature in millidegrees Celsius +============= ================================================== A subset of the following attributes are visible, depending on the measurement mode of the chip. +============= ========================================================== in[1-4]_input Voltage at V[1-4] pin in millivolt -temp2_input External temperature sensor TR1 in millidegrees Celcius -temp3_input External temperature sensor TR2 in millidegrees Celcius +temp2_input External temperature sensor TR1 in millidegrees Celsius +temp3_input External temperature sensor TR2 in millidegrees Celsius curr1_input Current in mA across V1-V2 assuming a 1mOhm sense resistor curr2_input Current in mA across V3-V4 assuming a 1mOhm sense resistor +============= ========================================================== The "curr*_input" measurements actually report the voltage drop across the input pins in microvolts. This is equivalent to the current through a 1mOhm diff --git a/Documentation/hwmon/ltc3815 b/Documentation/hwmon/ltc3815.rst index eb7db2d13587..fb0135fc1925 100644 --- a/Documentation/hwmon/ltc3815 +++ b/Documentation/hwmon/ltc3815.rst @@ -2,9 +2,13 @@ Kernel driver ltc3815 ===================== Supported chips: + * Linear Technology LTC3815 + Prefix: 'ltc3815' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc3815 Author: Guenter Roeck <linux@roeck-us.net> @@ -23,15 +27,16 @@ This driver does not probe for PMBus devices. You will have to instantiate devices explicitly. Example: the following commands will load the driver for an LTC3815 -at address 0x20 on I2C bus #1: +at address 0x20 on I2C bus #1:: -# modprobe ltc3815 -# echo ltc3815 0x20 > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe ltc3815 + # echo ltc3815 0x20 > /sys/bus/i2c/devices/i2c-1/new_device Sysfs attributes ---------------- +======================= ======================================================= in1_label "vin" in1_input Measured input voltage. in1_alarm Input voltage alarm. @@ -59,3 +64,4 @@ curr2_input Measured output current. curr2_alarm Output current alarm. curr2_highest Highest output current. curr2_reset_history Reset output current history. +======================= ======================================================= diff --git a/Documentation/hwmon/ltc4151 b/Documentation/hwmon/ltc4151.rst index 43c667e6677a..c39229b19624 100644 --- a/Documentation/hwmon/ltc4151 +++ b/Documentation/hwmon/ltc4151.rst @@ -2,11 +2,16 @@ Kernel driver ltc4151 ===================== Supported chips: + * Linear Technology LTC4151 + Prefix: 'ltc4151' + Addresses scanned: - + Datasheet: - http://www.linear.com/docs/Datasheet/4151fc.pdf + + http://www.linear.com/docs/Datasheet/4151fc.pdf Author: Per Dalen <per.dalen@appeartv.com> @@ -25,9 +30,10 @@ which can be safely used to identify the chip. You will have to instantiate the devices explicitly. Example: the following will load the driver for an LTC4151 at address 0x6f -on I2C bus #0: -# modprobe ltc4151 -# echo ltc4151 0x6f > /sys/bus/i2c/devices/i2c-0/new_device +on I2C bus #0:: + + # modprobe ltc4151 + # echo ltc4151 0x6f > /sys/bus/i2c/devices/i2c-0/new_device Sysfs entries @@ -40,8 +46,10 @@ Current reading provided by this driver is reported as obtained from the Current Sense register. The reported value assumes that a 1 mOhm sense resistor is installed. +======================= ================== in1_input VDIN voltage (mV) in2_input ADIN voltage (mV) curr1_input SENSE current (mA) +======================= ================== diff --git a/Documentation/hwmon/ltc4215 b/Documentation/hwmon/ltc4215.rst index c196a1846259..8d5044d99bab 100644 --- a/Documentation/hwmon/ltc4215 +++ b/Documentation/hwmon/ltc4215.rst @@ -2,11 +2,16 @@ Kernel driver ltc4215 ===================== Supported chips: + * Linear Technology LTC4215 + Prefix: 'ltc4215' + Addresses scanned: 0x44 + Datasheet: - http://www.linear.com/pc/downloadDocument.do?navId=H0,C1,C1003,C1006,C1163,P17572,D12697 + + http://www.linear.com/pc/downloadDocument.do?navId=H0,C1,C1003,C1006,C1163,P17572,D12697 Author: Ira W. Snyder <iws@ovro.caltech.edu> @@ -26,9 +31,10 @@ of the possible addresses are unfriendly to probing. You will have to instantiate the devices explicitly. Example: the following will load the driver for an LTC4215 at address 0x44 -on I2C bus #0: -$ modprobe ltc4215 -$ echo ltc4215 0x44 > /sys/bus/i2c/devices/i2c-0/new_device +on I2C bus #0:: + + $ modprobe ltc4215 + $ echo ltc4215 0x44 > /sys/bus/i2c/devices/i2c-0/new_device Sysfs entries @@ -38,6 +44,7 @@ The LTC4215 has built-in limits for overvoltage, undervoltage, and undercurrent warnings. This makes it very likely that the reference circuit will be used. +======================= ========================= in1_input input voltage in2_input output voltage @@ -49,3 +56,4 @@ curr1_max_alarm overcurrent alarm power1_input power usage power1_alarm power bad alarm +======================= ========================= diff --git a/Documentation/hwmon/ltc4245 b/Documentation/hwmon/ltc4245.rst index 4ca7a9da09f9..3dafd08a4e87 100644 --- a/Documentation/hwmon/ltc4245 +++ b/Documentation/hwmon/ltc4245.rst @@ -2,11 +2,16 @@ Kernel driver ltc4245 ===================== Supported chips: + * Linear Technology LTC4245 + Prefix: 'ltc4245' + Addresses scanned: 0x20-0x3f + Datasheet: - http://www.linear.com/pc/downloadDocument.do?navId=H0,C1,C1003,C1006,C1140,P19392,D13517 + + http://www.linear.com/pc/downloadDocument.do?navId=H0,C1,C1003,C1006,C1140,P19392,D13517 Author: Ira W. Snyder <iws@ovro.caltech.edu> @@ -27,9 +32,10 @@ of the possible addresses are unfriendly to probing. You will have to instantiate the devices explicitly. Example: the following will load the driver for an LTC4245 at address 0x23 -on I2C bus #1: -$ modprobe ltc4245 -$ echo ltc4245 0x23 > /sys/bus/i2c/devices/i2c-1/new_device +on I2C bus #1:: + + $ modprobe ltc4245 + $ echo ltc4245 0x23 > /sys/bus/i2c/devices/i2c-1/new_device Sysfs entries @@ -42,6 +48,7 @@ This driver uses the values in the datasheet to change the register values into the values specified in the sysfs-interface document. The current readings rely on the sense resistors listed in Table 2: "Sense Resistor Values". +======================= ======================================================= in1_input 12v input voltage (mV) in2_input 5v input voltage (mV) in3_input 3v input voltage (mV) @@ -80,6 +87,7 @@ power1_input 12v power usage (mW) power2_input 5v power usage (mW) power3_input 3v power usage (mW) power4_input Vee (-12v) power usage (mW) +======================= ======================================================= Note 1 @@ -96,6 +104,7 @@ slowly, -EAGAIN will be returned when you read the sysfs attribute containing the sensor reading. The LTC4245 chip can be configured to sample all GPIO pins with two methods: + 1) platform data -- see include/linux/platform_data/ltc4245.h 2) OF device tree -- add the "ltc4245,use-extra-gpios" property to each chip diff --git a/Documentation/hwmon/ltc4260 b/Documentation/hwmon/ltc4260.rst index c4ff4ad998b2..4c335b6a51d1 100644 --- a/Documentation/hwmon/ltc4260 +++ b/Documentation/hwmon/ltc4260.rst @@ -2,11 +2,16 @@ Kernel driver ltc4260 ===================== Supported chips: + * Linear Technology LTC4260 + Prefix: 'ltc4260' + Addresses scanned: - + Datasheet: - http://cds.linear.com/docs/en/datasheet/4260fc.pdf + + http://cds.linear.com/docs/en/datasheet/4260fc.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -26,9 +31,10 @@ which can be safely used to identify the chip. You will have to instantiate the devices explicitly. Example: the following will load the driver for an LTC4260 at address 0x10 -on I2C bus #1: -$ modprobe ltc4260 -$ echo ltc4260 0x10 > /sys/bus/i2c/devices/i2c-1/new_device +on I2C bus #1:: + + $ modprobe ltc4260 + $ echo ltc4260 0x10 > /sys/bus/i2c/devices/i2c-1/new_device Sysfs entries @@ -45,6 +51,7 @@ Current Sense register. The reported value assumes that a 1 mOhm sense resistor is installed. If a different sense resistor is installed, calculate the real current by dividing the reported value by the sense resistor value in mOhm. +======================= ======================= in1_input SOURCE voltage (mV) in1_min_alarm Undervoltage alarm in1_max_alarm Overvoltage alarm @@ -54,3 +61,4 @@ in2_alarm Power bad alarm curr1_input SENSE current (mA) curr1_alarm SENSE overcurrent alarm +======================= ======================= diff --git a/Documentation/hwmon/ltc4261 b/Documentation/hwmon/ltc4261.rst index 9378a75c6134..c80233f8082e 100644 --- a/Documentation/hwmon/ltc4261 +++ b/Documentation/hwmon/ltc4261.rst @@ -2,11 +2,16 @@ Kernel driver ltc4261 ===================== Supported chips: + * Linear Technology LTC4261 + Prefix: 'ltc4261' + Addresses scanned: - + Datasheet: - http://cds.linear.com/docs/Datasheet/42612fb.pdf + + http://cds.linear.com/docs/Datasheet/42612fb.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -26,9 +31,10 @@ which can be safely used to identify the chip. You will have to instantiate the devices explicitly. Example: the following will load the driver for an LTC4261 at address 0x10 -on I2C bus #1: -$ modprobe ltc4261 -$ echo ltc4261 0x10 > /sys/bus/i2c/devices/i2c-1/new_device +on I2C bus #1:: + + $ modprobe ltc4261 + $ echo ltc4261 0x10 > /sys/bus/i2c/devices/i2c-1/new_device Sysfs entries @@ -51,6 +57,7 @@ the proximity of the ADIN2 pin to the OV pin. ADIN2 is, however, not available on all chip variants. To ensure that the alarm condition is reported to the user, report it with both voltage sensors. +======================= ============================= in1_input ADIN2 voltage (mV) in1_min_alarm ADIN/ADIN2 Undervoltage alarm in1_max_alarm ADIN/ADIN2 Overvoltage alarm @@ -61,3 +68,4 @@ in2_max_alarm ADIN/ADIN2 Overvoltage alarm curr1_input SENSE current (mA) curr1_alarm SENSE overcurrent alarm +======================= ============================= diff --git a/Documentation/hwmon/max16064 b/Documentation/hwmon/max16064.rst index 265370f5cb82..6d5e9538991f 100644 --- a/Documentation/hwmon/max16064 +++ b/Documentation/hwmon/max16064.rst @@ -2,9 +2,13 @@ Kernel driver max16064 ====================== Supported chips: + * Maxim MAX16064 + Prefix: 'max16064' + Addresses scanned: - + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX16064.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -17,7 +21,7 @@ This driver supports hardware monitoring for Maxim MAX16064 Quad Power-Supply Controller with Active-Voltage Output Control and PMBus Interface. The driver is a client driver to the core PMBus driver. -Please see Documentation/hwmon/pmbus for details on PMBus client drivers. +Please see Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -40,16 +44,20 @@ Sysfs entries The following attributes are supported. Limits are read-write; all other attributes are read-only. +======================= ======================================================== in[1-4]_label "vout[1-4]" in[1-4]_input Measured voltage. From READ_VOUT register. in[1-4]_min Minimum Voltage. From VOUT_UV_WARN_LIMIT register. in[1-4]_max Maximum voltage. From VOUT_OV_WARN_LIMIT register. in[1-4]_lcrit Critical minimum Voltage. VOUT_UV_FAULT_LIMIT register. -in[1-4]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT register. +in[1-4]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT + register. in[1-4]_min_alarm Voltage low alarm. From VOLTAGE_UV_WARNING status. in[1-4]_max_alarm Voltage high alarm. From VOLTAGE_OV_WARNING status. -in[1-4]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT status. -in[1-4]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT status. +in[1-4]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT + status. +in[1-4]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT + status. in[1-4]_highest Historical maximum voltage. in[1-4]_reset_history Write any value to reset history. @@ -64,3 +72,4 @@ temp1_crit_alarm Chip temperature critical high alarm. Set by comparing status is set. temp1_highest Historical maximum temperature. temp1_reset_history Write any value to reset history. +======================= ======================================================== diff --git a/Documentation/hwmon/max16065 b/Documentation/hwmon/max16065.rst index 208a29e43010..fa5c852a178c 100644 --- a/Documentation/hwmon/max16065 +++ b/Documentation/hwmon/max16065.rst @@ -1,28 +1,48 @@ Kernel driver max16065 ====================== + Supported chips: + * Maxim MAX16065, MAX16066 + Prefixes: 'max16065', 'max16066' + Addresses scanned: - + Datasheet: + http://datasheets.maxim-ic.com/en/ds/MAX16065-MAX16066.pdf + * Maxim MAX16067 + Prefix: 'max16067' + Addresses scanned: - + Datasheet: + http://datasheets.maxim-ic.com/en/ds/MAX16067.pdf + * Maxim MAX16068 + Prefix: 'max16068' + Addresses scanned: - + Datasheet: + http://datasheets.maxim-ic.com/en/ds/MAX16068.pdf + * Maxim MAX16070/MAX16071 + Prefixes: 'max16070', 'max16071' + Addresses scanned: - + Datasheet: - http://datasheets.maxim-ic.com/en/ds/MAX16070-MAX16071.pdf + http://datasheets.maxim-ic.com/en/ds/MAX16070-MAX16071.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -73,6 +93,7 @@ turn into a brick. Sysfs entries ------------- +======================= ======================================================== in[0-11]_input Input voltage measurements. in12_input Voltage on CSP (Current Sense Positive) pin. @@ -103,3 +124,4 @@ curr1_input Current sense input; only if the chip supports current curr1_alarm Overcurrent alarm; only if the chip supports current sensing and if current sensing is enabled. +======================= ======================================================== diff --git a/Documentation/hwmon/max1619 b/Documentation/hwmon/max1619.rst index 518bae3a80c4..e25956e70f73 100644 --- a/Documentation/hwmon/max1619 +++ b/Documentation/hwmon/max1619.rst @@ -2,15 +2,20 @@ Kernel driver max1619 ===================== Supported chips: + * Maxim MAX1619 + Prefix: 'max1619' + Addresses scanned: I2C 0x18-0x1a, 0x29-0x2b, 0x4c-0x4e + Datasheet: Publicly available at the Maxim website - http://pdfserv.maxim-ic.com/en/ds/MAX1619.pdf + + http://pdfserv.maxim-ic.com/en/ds/MAX1619.pdf Authors: - Oleksij Rempel <bug-track@fisher-privat.net>, - Jean Delvare <jdelvare@suse.de> + - Oleksij Rempel <bug-track@fisher-privat.net>, + - Jean Delvare <jdelvare@suse.de> Description ----------- @@ -26,4 +31,3 @@ Only the external sensor has high and low limits. The max1619 driver will not update its values more frequently than every other second; reading them more often will do no harm, but will return 'old' values. - diff --git a/Documentation/hwmon/max1668 b/Documentation/hwmon/max1668.rst index 8f9d570dbfec..417f17d750e6 100644 --- a/Documentation/hwmon/max1668 +++ b/Documentation/hwmon/max1668.rst @@ -2,12 +2,17 @@ Kernel driver max1668 ===================== Supported chips: + * Maxim MAX1668, MAX1805 and MAX1989 + Prefix: 'max1668' + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, 0x4c, 0x4d, 0x4e + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX1668-MAX1989.pdf Author: + David George <david.george@ska.ac.za> Description @@ -23,8 +28,9 @@ two ICs. The driver is able to distinguish between the devices and creates sysfs entries as follows: -MAX1805, MAX1668 and MAX1989: +- MAX1805, MAX1668 and MAX1989: +=============== == ============================================================ temp1_input ro local (ambient) temperature temp1_max rw local temperature maximum threshold for alarm temp1_max_alarm ro local temperature maximum threshold alarm @@ -40,8 +46,11 @@ temp3_max rw remote temperature 2 maximum threshold for alarm temp3_max_alarm ro remote temperature 2 maximum threshold alarm temp3_min rw remote temperature 2 minimum threshold for alarm temp3_min_alarm ro remote temperature 2 minimum threshold alarm +=============== == ============================================================ + +- MAX1668 and MAX1989 only: -MAX1668 and MAX1989 only: +=============== == ============================================================ temp4_input ro remote temperature 3 temp4_max rw remote temperature 3 maximum threshold for alarm temp4_max_alarm ro remote temperature 3 maximum threshold alarm @@ -52,6 +61,7 @@ temp5_max rw remote temperature 4 maximum threshold for alarm temp5_max_alarm ro remote temperature 4 maximum threshold alarm temp5_min rw remote temperature 4 minimum threshold for alarm temp5_min_alarm ro remote temperature 4 minimum threshold alarm +=============== == ============================================================ Module Parameters ----------------- diff --git a/Documentation/hwmon/max197 b/Documentation/hwmon/max197.rst index 8d89b9009df8..02fe19bc3428 100644 --- a/Documentation/hwmon/max197 +++ b/Documentation/hwmon/max197.rst @@ -1,16 +1,22 @@ -Maxim MAX197 driver -=================== +Kernel driver max197 +==================== Author: + * Vivien Didelot <vivien.didelot@savoirfairelinux.com> Supported chips: + * Maxim MAX197 + Prefix: 'max197' + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX197.pdf * Maxim MAX199 + Prefix: 'max199' + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX199.pdf Description @@ -26,7 +32,7 @@ Platform data ------------- The MAX197 platform data (defined in linux/platform_data/max197.h) should be -filled with a pointer to a conversion function, defined like: +filled with a pointer to a conversion function, defined like:: int convert(u8 ctrl); @@ -36,25 +42,29 @@ or a negative error code otherwise. Control byte format: +======= ========== ============================================ Bit Name Description 7,6 PD1,PD0 Clock and Power-Down modes 5 ACQMOD Internal or External Controlled Acquisition 4 RNG Full-scale voltage magnitude at the input 3 BIP Unipolar or Bipolar conversion mode 2,1,0 A2,A1,A0 Channel +======= ========== ============================================ Sysfs interface --------------- -* in[0-7]_input: The conversion value for the corresponding channel. - RO + ============== ============================================================== + in[0-7]_input The conversion value for the corresponding channel. + RO -* in[0-7]_min: The lower limit (in mV) for the corresponding channel. - For the MAX197, it will be adjusted to -10000, -5000, or 0. - For the MAX199, it will be adjusted to -4000, -2000, or 0. - RW + in[0-7]_min The lower limit (in mV) for the corresponding channel. + For the MAX197, it will be adjusted to -10000, -5000, or 0. + For the MAX199, it will be adjusted to -4000, -2000, or 0. + RW -* in[0-7]_max: The higher limit (in mV) for the corresponding channel. - For the MAX197, it will be adjusted to 0, 5000, or 10000. - For the MAX199, it will be adjusted to 0, 2000, or 4000. - RW + in[0-7]_max The higher limit (in mV) for the corresponding channel. + For the MAX197, it will be adjusted to 0, 5000, or 10000. + For the MAX199, it will be adjusted to 0, 2000, or 4000. + RW + ============== ============================================================== diff --git a/Documentation/hwmon/max20751 b/Documentation/hwmon/max20751.rst index f9fa25ebb521..aa4469be6674 100644 --- a/Documentation/hwmon/max20751 +++ b/Documentation/hwmon/max20751.rst @@ -2,10 +2,15 @@ Kernel driver max20751 ====================== Supported chips: + * maxim MAX20751 + Prefix: 'max20751' + Addresses scanned: - + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX20751.pdf + Application note: http://pdfserv.maximintegrated.com/en/an/AN5941.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -18,7 +23,7 @@ This driver supports MAX20751 Multiphase Master with PMBus Interface and Internal Buck Converter. The driver is a client driver to the core PMBus driver. -Please see Documentation/hwmon/pmbus for details on PMBus client drivers. +Please see Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -40,6 +45,7 @@ Sysfs entries The following attributes are supported. +======================= ======================================================= in1_label "vin1" in1_input Measured voltage. in1_min Minimum input voltage. @@ -75,3 +81,4 @@ temp1_crit_alarm Chip temperature critical high alarm. power1_input Output power. power1_label "pout1" +======================= ======================================================= diff --git a/Documentation/hwmon/max31722 b/Documentation/hwmon/max31722.rst index 090da84538c8..0ab15c00b226 100644 --- a/Documentation/hwmon/max31722 +++ b/Documentation/hwmon/max31722.rst @@ -2,15 +2,25 @@ Kernel driver max31722 ====================== Supported chips: + * Maxim Integrated MAX31722 + Prefix: 'max31722' + ACPI ID: MAX31722 + Addresses scanned: - + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX31722-MAX31723.pdf + * Maxim Integrated MAX31723 + Prefix: 'max31723' + ACPI ID: MAX31723 + Addresses scanned: - + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX31722-MAX31723.pdf Author: Tiberiu Breana <tiberiu.a.breana@intel.com> @@ -31,4 +41,6 @@ Sysfs entries The following attribute is supported: +======================= ======================================================= temp1_input Measured temperature. Read-only. +======================= ======================================================= diff --git a/Documentation/hwmon/max31785 b/Documentation/hwmon/max31785.rst index 270c5f865261..c8c6756d0ee1 100644 --- a/Documentation/hwmon/max31785 +++ b/Documentation/hwmon/max31785.rst @@ -2,9 +2,13 @@ Kernel driver max31785 ====================== Supported chips: + * Maxim MAX31785, MAX31785A + Prefix: 'max31785' or 'max31785a' + Addresses scanned: - + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX31785.pdf Author: Andrew Jeffery <andrew@aj.id.au> @@ -30,6 +34,7 @@ devices explicitly. Sysfs attributes ---------------- +======================= ======================================================= fan[1-4]_alarm Fan alarm. fan[1-4]_fault Fan fault. fan[1-8]_input Fan RPM. On the MAX31785A, inputs 5-8 correspond to the @@ -58,3 +63,4 @@ temp[1-11]_crit_alarm Chip temperature critical high alarm temp[1-11]_input Measured temperature temp[1-11]_max Maximum temperature temp[1-11]_max_alarm Chip temperature high alarm +======================= ======================================================= diff --git a/Documentation/hwmon/max31790 b/Documentation/hwmon/max31790.rst index 855e62430da9..84c62a12ef3a 100644 --- a/Documentation/hwmon/max31790 +++ b/Documentation/hwmon/max31790.rst @@ -2,9 +2,13 @@ Kernel driver max31790 ====================== Supported chips: + * Maxim MAX31790 + Prefix: 'max31790' + Addresses scanned: - + Datasheet: http://pdfserv.maximintegrated.com/en/ds/MAX31790.pdf Author: Il Han <corone.il.han@gmail.com> @@ -30,8 +34,10 @@ also be configured to serve as tachometer inputs. Sysfs entries ------------- +================== === ======================================================= fan[1-12]_input RO fan tachometer speed in RPM fan[1-12]_fault RO fan experienced fault fan[1-6]_target RW desired fan speed in RPM pwm[1-6]_enable RW regulator mode, 0=disabled, 1=manual mode, 2=rpm mode pwm[1-6] RW fan target duty cycle (0-255) +================== === ======================================================= diff --git a/Documentation/hwmon/max34440 b/Documentation/hwmon/max34440.rst index b2de8fa49273..939138e12b02 100644 --- a/Documentation/hwmon/max34440 +++ b/Documentation/hwmon/max34440.rst @@ -2,34 +2,63 @@ Kernel driver max34440 ====================== Supported chips: + * Maxim MAX34440 + Prefixes: 'max34440' + Addresses scanned: - + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34440.pdf + * Maxim MAX34441 + PMBus 5-Channel Power-Supply Manager and Intelligent Fan Controller + Prefixes: 'max34441' + Addresses scanned: - + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34441.pdf + * Maxim MAX34446 + PMBus Power-Supply Data Logger + Prefixes: 'max34446' + Addresses scanned: - + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34446.pdf + * Maxim MAX34451 + PMBus 16-Channel V/I Monitor and 12-Channel Sequencer/Marginer + Prefixes: 'max34451' + Addresses scanned: - + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34451.pdf + * Maxim MAX34460 + PMBus 12-Channel Voltage Monitor & Sequencer + Prefix: 'max34460' + Addresses scanned: - + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34460.pdf + * Maxim MAX34461 + PMBus 16-Channel Voltage Monitor & Sequencer + Prefix: 'max34461' + Addresses scanned: - + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX34461.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -47,7 +76,7 @@ based on GIN pins. The MAX34460 supports 12 voltage channels, and the MAX34461 supports 16 voltage channels. The driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus for details on PMBus client drivers. +Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -77,42 +106,67 @@ Sysfs entries The following attributes are supported. Limits are read-write; all other attributes are read-only. +In +~~ + +======================= ======================================================= in[1-6]_label "vout[1-6]". in[1-6]_input Measured voltage. From READ_VOUT register. in[1-6]_min Minimum Voltage. From VOUT_UV_WARN_LIMIT register. in[1-6]_max Maximum voltage. From VOUT_OV_WARN_LIMIT register. in[1-6]_lcrit Critical minimum Voltage. VOUT_UV_FAULT_LIMIT register. -in[1-6]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT register. +in[1-6]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT + register. in[1-6]_min_alarm Voltage low alarm. From VOLTAGE_UV_WARNING status. in[1-6]_max_alarm Voltage high alarm. From VOLTAGE_OV_WARNING status. -in[1-6]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT status. -in[1-6]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT status. +in[1-6]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT + status. +in[1-6]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT + status. in[1-6]_lowest Historical minimum voltage. in[1-6]_highest Historical maximum voltage. in[1-6]_reset_history Write any value to reset history. +======================= ======================================================= + +.. note:: MAX34446 only supports in[1-4]. - MAX34446 only supports in[1-4]. +Curr +~~~~ +======================= ======================================================== curr[1-6]_label "iout[1-6]". curr[1-6]_input Measured current. From READ_IOUT register. curr[1-6]_max Maximum current. From IOUT_OC_WARN_LIMIT register. -curr[1-6]_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT register. +curr[1-6]_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT + register. curr[1-6]_max_alarm Current high alarm. From IOUT_OC_WARNING status. curr[1-6]_crit_alarm Current critical high alarm. From IOUT_OC_FAULT status. curr[1-4]_average Historical average current (MAX34446/34451 only). curr[1-6]_highest Historical maximum current. curr[1-6]_reset_history Write any value to reset history. +======================= ======================================================== + +.. note:: + + - in6 and curr6 attributes only exist for MAX34440. + - MAX34446 only supports curr[1-4]. - in6 and curr6 attributes only exist for MAX34440. - MAX34446 only supports curr[1-4]. +Power +~~~~~ +======================= ======================================================== power[1,3]_label "pout[1,3]" power[1,3]_input Measured power. power[1,3]_average Historical average power. power[1,3]_highest Historical maximum power. +======================= ======================================================== - Power attributes only exist for MAX34446. +.. note:: Power attributes only exist for MAX34446. +Temp +~~~~ + +======================= ======================================================== temp[1-8]_input Measured temperatures. From READ_TEMPERATURE_1 register. temp1 is the chip's internal temperature. temp2..temp5 are remote I2C temperature sensors. For MAX34441, temp6 @@ -125,11 +179,17 @@ temp[1-8]_crit_alarm Temperature critical high alarm. temp[1-8]_average Historical average temperature (MAX34446 only). temp[1-8]_highest Historical maximum temperature. temp[1-8]_reset_history Write any value to reset history. +======================= ======================================================== + + +.. note:: + - temp7 and temp8 attributes only exist for MAX34440. + - MAX34446 only supports temp[1-3]. + - temp7 and temp8 attributes only exist for MAX34440. - MAX34446 only supports temp[1-3]. +.. note:: -MAX34451 supports attribute groups in[1-16] (or curr[1-16] based on input pins) -and temp[1-5]. -MAX34460 supports attribute groups in[1-12] and temp[1-5]. -MAX34461 supports attribute groups in[1-16] and temp[1-5]. + - MAX34451 supports attribute groups in[1-16] (or curr[1-16] based on + input pins) and temp[1-5]. + - MAX34460 supports attribute groups in[1-12] and temp[1-5]. + - MAX34461 supports attribute groups in[1-16] and temp[1-5]. diff --git a/Documentation/hwmon/max6639 b/Documentation/hwmon/max6639.rst index dc49f8be7167..3da54225f83c 100644 --- a/Documentation/hwmon/max6639 +++ b/Documentation/hwmon/max6639.rst @@ -2,14 +2,18 @@ Kernel driver max6639 ===================== Supported chips: + * Maxim MAX6639 + Prefix: 'max6639' + Addresses scanned: I2C 0x2c, 0x2e, 0x2f + Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6639.pdf Authors: - He Changqing <hechangqing@semptian.com> - Roland Stigge <stigge@antcom.de> + - He Changqing <hechangqing@semptian.com> + - Roland Stigge <stigge@antcom.de> Description ----------- @@ -21,19 +25,20 @@ diode-connected transistors. The following device attributes are implemented via sysfs: +====================== ==== =================================================== Attribute R/W Contents ----------------------------------------------------------------------------- +====================== ==== =================================================== temp1_input R Temperature channel 1 input (0..150 C) temp2_input R Temperature channel 2 input (0..150 C) temp1_fault R Temperature channel 1 diode fault temp2_fault R Temperature channel 2 diode fault temp1_max RW Set THERM temperature for input 1 - (in C, see datasheet) + (in C, see datasheet) temp2_max RW Set THERM temperature for input 2 temp1_crit RW Set ALERT temperature for input 1 temp2_crit RW Set ALERT temperature for input 2 temp1_emergency RW Set OT temperature for input 1 - (in C, see datasheet) + (in C, see datasheet) temp2_emergency RW Set OT temperature for input 2 pwm1 RW Fan 1 target duty cycle (0..255) pwm2 RW Fan 2 target duty cycle (0..255) @@ -47,3 +52,4 @@ temp1_crit_alarm R Alarm on ALERT temperature on channel 1 temp2_crit_alarm R Alarm on ALERT temperature on channel 2 temp1_emergency_alarm R Alarm on OT temperature on channel 1 temp2_emergency_alarm R Alarm on OT temperature on channel 2 +====================== ==== =================================================== diff --git a/Documentation/hwmon/max6642 b/Documentation/hwmon/max6642.rst index afbd3e4942e2..7e5b7d4f9492 100644 --- a/Documentation/hwmon/max6642 +++ b/Documentation/hwmon/max6642.rst @@ -2,14 +2,20 @@ Kernel driver max6642 ===================== Supported chips: + * Maxim MAX6642 + Prefix: 'max6642' + Addresses scanned: I2C 0x48-0x4f + Datasheet: Publicly available at the Maxim website - http://datasheets.maxim-ic.com/en/ds/MAX6642.pdf + + http://datasheets.maxim-ic.com/en/ds/MAX6642.pdf Authors: - Per Dalen <per.dalen@appeartv.com> + + Per Dalen <per.dalen@appeartv.com> Description ----------- diff --git a/Documentation/hwmon/max6650 b/Documentation/hwmon/max6650.rst index dff1d296a48b..253482add082 100644 --- a/Documentation/hwmon/max6650 +++ b/Documentation/hwmon/max6650.rst @@ -2,19 +2,27 @@ Kernel driver max6650 ===================== Supported chips: + * Maxim MAX6650 + Prefix: 'max6650' + Addresses scanned: none + Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6650-MAX6651.pdf + * Maxim MAX6651 + Prefix: 'max6651' + Addresses scanned: none + Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6650-MAX6651.pdf Authors: - Hans J. Koch <hjk@hansjkoch.de> - John Morris <john.morris@spirentcom.com> - Claus Gindhart <claus.gindhart@kontron.com> + - Hans J. Koch <hjk@hansjkoch.de> + - John Morris <john.morris@spirentcom.com> + - Claus Gindhart <claus.gindhart@kontron.com> Description ----------- @@ -28,6 +36,7 @@ The driver is not able to distinguish between the 2 devices. The driver provides the following sensor accesses in sysfs: +=============== ======= ======================================================= fan1_input ro fan tachometer speed in RPM fan2_input ro " fan3_input ro " @@ -40,6 +49,7 @@ pwm1 rw relative speed (0-255), 255=max. speed. fan1_div rw sets the speed range the inputs can handle. Legal values are 1, 2, 4, and 8. Use lower values for faster fans. +=============== ======= ======================================================= Usage notes ----------- @@ -62,4 +72,3 @@ clock: The clock frequency in Hz of the chip the driver should assume [254000] Please have a look at the MAX6650/6651 data sheet and make sure that you fully understand the meaning of these parameters before you attempt to change them. - diff --git a/Documentation/hwmon/max6697 b/Documentation/hwmon/max6697.rst index 6594177ededa..ffc5a7d8d33b 100644 --- a/Documentation/hwmon/max6697 +++ b/Documentation/hwmon/max6697.rst @@ -2,38 +2,69 @@ Kernel driver max6697 ===================== Supported chips: + * Maxim MAX6581 + Prefix: 'max6581' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6581.pdf + * Maxim MAX6602 + Prefix: 'max6602' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6602.pdf + * Maxim MAX6622 + Prefix: 'max6622' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6622.pdf + * Maxim MAX6636 + Prefix: 'max6636' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6636.pdf + * Maxim MAX6689 + Prefix: 'max6689' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6689.pdf + * Maxim MAX6693 + Prefix: 'max6693' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6693.pdf + * Maxim MAX6694 + Prefix: 'max6694' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6694.pdf + * Maxim MAX6697 + Prefix: 'max6697' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6697.pdf + * Maxim MAX6698 + Prefix: 'max6698' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6698.pdf + * Maxim MAX6699 + Prefix: 'max6699' + Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6699.pdf Author: + Guenter Roeck <linux@roeck-us.net> Description @@ -50,9 +81,11 @@ The driver provides the following sysfs attributes. temp1 is the local (chip) temperature, temp[2..n] are remote temperatures. The actually supported per-channel attributes are chip type and channel dependent. +================ == ========================================================== tempX_input RO temperature tempX_max RW temperature maximum threshold tempX_max_alarm RO temperature maximum threshold alarm tempX_crit RW temperature critical threshold tempX_crit_alarm RO temperature critical threshold alarm tempX_fault RO temperature diode fault (remote sensors only) +================ == ========================================================== diff --git a/Documentation/hwmon/max8688 b/Documentation/hwmon/max8688.rst index ca233bec7a8a..009487759c61 100644 --- a/Documentation/hwmon/max8688 +++ b/Documentation/hwmon/max8688.rst @@ -2,9 +2,13 @@ Kernel driver max8688 ===================== Supported chips: + * Maxim MAX8688 + Prefix: 'max8688' + Addresses scanned: - + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX8688.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -17,7 +21,7 @@ This driver supports hardware monitoring for Maxim MAX8688 Digital Power-Supply Controller/Monitor with PMBus Interface. The driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus for details on PMBus client drivers. +Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -40,23 +44,28 @@ Sysfs entries The following attributes are supported. Limits are read-write; all other attributes are read-only. +======================= ======================================================== in1_label "vout1" in1_input Measured voltage. From READ_VOUT register. in1_min Minimum Voltage. From VOUT_UV_WARN_LIMIT register. in1_max Maximum voltage. From VOUT_OV_WARN_LIMIT register. in1_lcrit Critical minimum Voltage. VOUT_UV_FAULT_LIMIT register. -in1_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT register. +in1_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT + register. in1_min_alarm Voltage low alarm. From VOLTAGE_UV_WARNING status. in1_max_alarm Voltage high alarm. From VOLTAGE_OV_WARNING status. -in1_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT status. -in1_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT status. +in1_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT + status. +in1_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT + status. in1_highest Historical maximum voltage. in1_reset_history Write any value to reset history. curr1_label "iout1" curr1_input Measured current. From READ_IOUT register. curr1_max Maximum current. From IOUT_OC_WARN_LIMIT register. -curr1_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT register. +curr1_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT + register. curr1_max_alarm Current high alarm. From IOUT_OC_WARN_LIMIT register. curr1_crit_alarm Current critical high alarm. From IOUT_OC_FAULT status. curr1_highest Historical maximum current. @@ -73,3 +82,4 @@ temp1_crit_alarm Chip temperature critical high alarm. Set by comparing status is set. temp1_highest Historical maximum temperature. temp1_reset_history Write any value to reset history. +======================= ======================================================== diff --git a/Documentation/hwmon/mc13783-adc b/Documentation/hwmon/mc13783-adc.rst index 05ccc9f159f1..cae70350ba2f 100644 --- a/Documentation/hwmon/mc13783-adc +++ b/Documentation/hwmon/mc13783-adc.rst @@ -2,16 +2,25 @@ Kernel driver mc13783-adc ========================= Supported chips: + * Freescale MC13783 + Prefix: 'mc13783' + Datasheet: https://www.nxp.com/docs/en/data-sheet/MC13783.pdf + * Freescale MC13892 + Prefix: 'mc13892' + Datasheet: https://www.nxp.com/docs/en/data-sheet/MC13892.pdf + + Authors: - Sascha Hauer <s.hauer@pengutronix.de> - Luotao Fu <l.fu@pengutronix.de> + + - Sascha Hauer <s.hauer@pengutronix.de> + - Luotao Fu <l.fu@pengutronix.de> Description ----------- @@ -30,9 +39,11 @@ the General Purpose inputs and touchscreen. See the following tables for the meaning of the different channels and their chip internal scaling: -MC13783: +- MC13783: + +======= =============================================== =============== ======= Channel Signal Input Range Scaling -------------------------------------------------------------------------------- +======= =============================================== =============== ======= 0 Battery Voltage (BATT) 2.50 - 4.65V -2.40V 1 Battery Current (BATT - BATTISNS) -50 - 50 mV x20 2 Application Supply (BP) 2.50 - 4.65V -2.40V @@ -52,10 +63,13 @@ Channel Signal Input Range Scaling 13 General Purpose TSX2 / Touchscreen X-plate 2 0 - 2.30V No 14 General Purpose TSY1 / Touchscreen Y-plate 1 0 - 2.30V No 15 General Purpose TSY2 / Touchscreen Y-plate 2 0 - 2.30V No +======= =============================================== =============== ======= + +- MC13892: -MC13892: +======= =============================================== =============== ======= Channel Signal Input Range Scaling -------------------------------------------------------------------------------- +======= =============================================== =============== ======= 0 Battery Voltage (BATT) 0 - 4.8V /2 1 Battery Current (BATT - BATTISNSCC) -60 - 60 mV x20 2 Application Supply (BPSNS) 0 - 4.8V /2 @@ -72,3 +86,4 @@ Channel Signal Input Range Scaling 13 General Purpose TSX2 / Touchscreen X-plate 2 0 - 2.4V No 14 General Purpose TSY1 / Touchscreen Y-plate 1 0 - 2.4V No 15 General Purpose TSY2 / Touchscreen Y-plate 2 0 - 2.4V No +======= =============================================== =============== ======= diff --git a/Documentation/hwmon/mcp3021 b/Documentation/hwmon/mcp3021.rst index 74a6b72adf5f..83f4bda2f269 100644 --- a/Documentation/hwmon/mcp3021 +++ b/Documentation/hwmon/mcp3021.rst @@ -1,17 +1,26 @@ Kernel driver MCP3021 -====================== +===================== Supported chips: + * Microchip Technology MCP3021 + Prefix: 'mcp3021' + Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21805a.pdf + * Microchip Technology MCP3221 + Prefix: 'mcp3221' + Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21732c.pdf + + Authors: - Mingkai Hu - Sven Schuchmann <schuchmann@schleissheimer.de> + + - Mingkai Hu + - Sven Schuchmann <schuchmann@schleissheimer.de> Description ----------- diff --git a/Documentation/hwmon/menf21bmc b/Documentation/hwmon/menf21bmc.rst index 2a273a065c5e..1f0c6b2235ab 100644 --- a/Documentation/hwmon/menf21bmc +++ b/Documentation/hwmon/menf21bmc.rst @@ -2,8 +2,11 @@ Kernel driver menf21bmc_hwmon ============================= Supported chips: + * MEN 14F021P00 + Prefix: 'menf21bmc_hwmon' + Adresses scanned: - Author: Andreas Werner <andreas.werner@men.de> @@ -34,6 +37,7 @@ Sysfs entries The following attributes are supported. All attributes are read only The Limits are read once by the driver. +=============== ========================== in0_input +3.3V input voltage in1_input +5.0V input voltage in2_input +12.0V input voltage @@ -48,3 +52,4 @@ in1_label "MON_5V" in2_label "MON_12V" in3_label "5V_STANDBY" in4_label "VBAT" +=============== ========================== diff --git a/Documentation/hwmon/mlxreg-fan b/Documentation/hwmon/mlxreg-fan.rst index fc531c6978d4..c92b8e885f7e 100644 --- a/Documentation/hwmon/mlxreg-fan +++ b/Documentation/hwmon/mlxreg-fan.rst @@ -2,32 +2,38 @@ Kernel driver mlxreg-fan ======================== Provides FAN control for the next Mellanox systems: -QMB700, equipped with 40x200GbE InfiniBand ports; -MSN3700, equipped with 32x200GbE or 16x400GbE Ethernet ports; -MSN3410, equipped with 6x400GbE plus 48x50GbE Ethernet ports; -MSN3800, equipped with 64x1000GbE Ethernet ports; + +- QMB700, equipped with 40x200GbE InfiniBand ports; +- MSN3700, equipped with 32x200GbE or 16x400GbE Ethernet ports; +- MSN3410, equipped with 6x400GbE plus 48x50GbE Ethernet ports; +- MSN3800, equipped with 64x1000GbE Ethernet ports; + +Author: Vadim Pasternak <vadimp@mellanox.com> + These are the Top of the Rack systems, equipped with Mellanox switch board with Mellanox Quantum or Spectrume-2 devices. FAN controller is implemented by the programmable device logic. The default registers offsets set within the programmable device is as following: -- pwm1 0xe3 -- fan1 (tacho1) 0xe4 -- fan2 (tacho2) 0xe5 -- fan3 (tacho3) 0xe6 -- fan4 (tacho4) 0xe7 -- fan5 (tacho5) 0xe8 -- fan6 (tacho6) 0xe9 -- fan7 (tacho7) 0xea -- fan8 (tacho8) 0xeb -- fan9 (tacho9) 0xec -- fan10 (tacho10) 0xed -- fan11 (tacho11) 0xee -- fan12 (tacho12) 0xef -This setup can be re-programmed with other registers. -Author: Vadim Pasternak <vadimp@mellanox.com> +======================= ==== +pwm1 0xe3 +fan1 (tacho1) 0xe4 +fan2 (tacho2) 0xe5 +fan3 (tacho3) 0xe6 +fan4 (tacho4) 0xe7 +fan5 (tacho5) 0xe8 +fan6 (tacho6) 0xe9 +fan7 (tacho7) 0xea +fan8 (tacho8) 0xeb +fan9 (tacho9) 0xec +fan10 (tacho10) 0xed +fan11 (tacho11) 0xee +fan12 (tacho12) 0xef +======================= ==== + +This setup can be re-programmed with other registers. Description ----------- @@ -48,13 +54,17 @@ thermal's sysfs interfaces. /sys files in hwmon subsystem ----------------------------- -fan[1-12]_fault - RO files for tachometers TACH1-TACH12 fault indication -fan[1-12]_input - RO files for tachometers TACH1-TACH12 input (in RPM) -pwm1 - RW file for fan[1-12] target duty cycle (0..255) +================= == =================================================== +fan[1-12]_fault RO files for tachometers TACH1-TACH12 fault indication +fan[1-12]_input RO files for tachometers TACH1-TACH12 input (in RPM) +pwm1 RW file for fan[1-12] target duty cycle (0..255) +================= == =================================================== /sys files in thermal subsystem ------------------------------- -cur_state - RW file for current cooling state of the cooling device - (0..max_state) -max_state - RO file for maximum cooling state of the cooling device +================= == ==================================================== +cur_state RW file for current cooling state of the cooling device + (0..max_state) +max_state RO file for maximum cooling state of the cooling device +================= == ==================================================== diff --git a/Documentation/hwmon/nct6683 b/Documentation/hwmon/nct6683.rst index c1301d4300cd..efbf7e9703ec 100644 --- a/Documentation/hwmon/nct6683 +++ b/Documentation/hwmon/nct6683.rst @@ -2,13 +2,18 @@ Kernel driver nct6683 ===================== Supported chips: + * Nuvoton NCT6683D + Prefix: 'nct6683' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request Authors: - Guenter Roeck <linux@roeck-us.net> + + Guenter Roeck <linux@roeck-us.net> Description ----------- @@ -50,8 +55,10 @@ Tested Boards and Firmware Versions The driver has been reported to work with the following boards and firmware versions. +=============== =============================================== Board Firmware version ---------------------------------------------------------------- +=============== =============================================== Intel DH87RL NCT6683D EC firmware version 1.0 build 04/03/13 Intel DH87MC NCT6683D EC firmware version 1.0 build 04/03/13 Intel DB85FL NCT6683D EC firmware version 1.0 build 04/03/13 +=============== =============================================== diff --git a/Documentation/hwmon/nct6775 b/Documentation/hwmon/nct6775.rst index bd59834d310f..1d0315c40952 100644 --- a/Documentation/hwmon/nct6775 +++ b/Documentation/hwmon/nct6775.rst @@ -1,52 +1,90 @@ -Note -==== - -This driver supersedes the NCT6775F and NCT6776F support in the W83627EHF -driver. - Kernel driver NCT6775 ===================== +.. note:: + + This driver supersedes the NCT6775F and NCT6776F support in the W83627EHF + driver. + Supported chips: + * Nuvoton NCT6102D/NCT6104D/NCT6106D + Prefix: 'nct6106' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from the Nuvoton web site + * Nuvoton NCT5572D/NCT6771F/NCT6772F/NCT6775F/W83677HG-I + Prefix: 'nct6775' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT5573D/NCT5577D/NCT6776D/NCT6776F + Prefix: 'nct6776' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT5532D/NCT6779D + Prefix: 'nct6779' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6791D + Prefix: 'nct6791' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6792D + Prefix: 'nct6792' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6793D + Prefix: 'nct6793' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6795D + Prefix: 'nct6795' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6796D + Prefix: 'nct6796' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + + Authors: - Guenter Roeck <linux@roeck-us.net> + + Guenter Roeck <linux@roeck-us.net> Description ----------- @@ -96,10 +134,14 @@ The mode works for fan1-fan5. sysfs attributes ---------------- -pwm[1-7] - this file stores PWM duty cycle or DC value (fan speed) in range: +pwm[1-7] + - this file stores PWM duty cycle or DC value (fan speed) in range: + 0 (lowest speed) to 255 (full) -pwm[1-7]_enable - this file controls mode of fan/temperature control: +pwm[1-7]_enable + - this file controls mode of fan/temperature control: + * 0 Fan control disabled (fans set to maximum speed) * 1 Manual mode, write to pwm[0-5] any value 0-255 * 2 "Thermal Cruise" mode @@ -107,15 +149,19 @@ pwm[1-7]_enable - this file controls mode of fan/temperature control: * 4 "Smart Fan III" mode (NCT6775F only) * 5 "Smart Fan IV" mode -pwm[1-7]_mode - controls if output is PWM or DC level - * 0 DC output - * 1 PWM output +pwm[1-7]_mode + - controls if output is PWM or DC level + + * 0 DC output + * 1 PWM output Common fan control attributes ----------------------------- -pwm[1-7]_temp_sel Temperature source. Value is temperature sensor index. +pwm[1-7]_temp_sel + Temperature source. Value is temperature sensor index. For example, select '1' for temp1_input. + pwm[1-7]_weight_temp_sel Secondary temperature source. Value is temperature sensor index. For example, select '1' for temp1_input. @@ -126,13 +172,16 @@ following attributes. pwm[1-7]_weight_duty_step Duty step size. + pwm[1-7]_weight_temp_step Temperature step size. With each step over temp_step_base, the value of weight_duty_step is added to the current pwm value. + pwm[1-7]_weight_temp_step_base Temperature at which secondary temperature control kicks in. + pwm[1-7]_weight_temp_step_tol Temperature step tolerance. @@ -141,24 +190,35 @@ Thermal Cruise mode (2) If the temperature is in the range defined by: -pwm[1-7]_target_temp Target temperature, unit millidegree Celsius +pwm[1-7]_target_temp + Target temperature, unit millidegree Celsius (range 0 - 127000) + pwm[1-7]_temp_tolerance Target temperature tolerance, unit millidegree Celsius -there are no changes to fan speed. Once the temperature leaves the interval, fan +There are no changes to fan speed. Once the temperature leaves the interval, fan speed increases (if temperature is higher that desired) or decreases (if temperature is lower than desired), using the following limits and time intervals. -pwm[1-7]_start fan pwm start value (range 1 - 255), to start fan +pwm[1-7]_start + fan pwm start value (range 1 - 255), to start fan when the temperature is above defined range. -pwm[1-7]_floor lowest fan pwm (range 0 - 255) if temperature is below + +pwm[1-7]_floor + lowest fan pwm (range 0 - 255) if temperature is below the defined range. If set to 0, the fan is expected to stop if the temperature is below the defined range. -pwm[1-7]_step_up_time milliseconds before fan speed is increased -pwm[1-7]_step_down_time milliseconds before fan speed is decreased -pwm[1-7]_stop_time how many milliseconds must elapse to switch + +pwm[1-7]_step_up_time + milliseconds before fan speed is increased + +pwm[1-7]_step_down_time + milliseconds before fan speed is decreased + +pwm[1-7]_stop_time + how many milliseconds must elapse to switch corresponding fan off (when the temperature was below defined range). @@ -167,7 +227,9 @@ Speed Cruise mode (3) This modes tries to keep the fan speed constant. -fan[1-7]_target Target fan speed +fan[1-7]_target + Target fan speed + fan[1-7]_tolerance Target speed tolerance @@ -188,16 +250,22 @@ critical temperature mode, in which the fans should run at full speed. pwm[1-7]_auto_point[1-7]_pwm pwm value to be set if temperature reaches matching temperature range. + pwm[1-7]_auto_point[1-7]_temp Temperature over which the matching pwm is enabled. + pwm[1-7]_temp_tolerance Temperature tolerance, unit millidegree Celsius + pwm[1-7]_crit_temp_tolerance Temperature tolerance for critical temperature, unit millidegree Celsius -pwm[1-7]_step_up_time milliseconds before fan speed is increased -pwm[1-7]_step_down_time milliseconds before fan speed is decreased +pwm[1-7]_step_up_time + milliseconds before fan speed is increased + +pwm[1-7]_step_down_time + milliseconds before fan speed is decreased Usage Notes ----------- diff --git a/Documentation/hwmon/nct7802 b/Documentation/hwmon/nct7802.rst index 5438deb6be02..8b7365a7cb32 100644 --- a/Documentation/hwmon/nct7802 +++ b/Documentation/hwmon/nct7802.rst @@ -2,13 +2,18 @@ Kernel driver nct7802 ===================== Supported chips: + * Nuvoton NCT7802Y + Prefix: 'nct7802' + Addresses scanned: I2C 0x28..0x2f + Datasheet: Available from Nuvoton web site Authors: - Guenter Roeck <linux@roeck-us.net> + + Guenter Roeck <linux@roeck-us.net> Description ----------- @@ -25,7 +30,9 @@ Tested Boards and BIOS Versions The driver has been reported to work with the following boards and BIOS versions. +======================= =============================================== Board BIOS version ---------------------------------------------------------------- +======================= =============================================== Kontron COMe-bSC2 CHR2E934.001.GGO Kontron COMe-bIP2 CCR2E212 +======================= =============================================== diff --git a/Documentation/hwmon/nct7904 b/Documentation/hwmon/nct7904.rst index 57fffe33ebfc..5b2f111582ff 100644 --- a/Documentation/hwmon/nct7904 +++ b/Documentation/hwmon/nct7904.rst @@ -1,11 +1,16 @@ Kernel driver nct7904 -==================== +===================== Supported chip: + * Nuvoton NCT7904D + Prefix: nct7904 + Addresses: I2C 0x2d, 0x2e + Datasheet: Publicly available at Nuvoton website + http://www.nuvoton.com/ Author: Vadim V. Vlasov <vvlasov@dev.rtsoft.ru> @@ -25,6 +30,7 @@ Sysfs entries Currently, the driver supports only the following features: +======================= ======================================================= in[1-20]_input Input voltage measurements (mV) fan[1-12]_input Fan tachometer measurements (rpm) @@ -40,6 +46,7 @@ pwm[1-4]_enable R/W, 1/2 for manual or SmartFan mode previously configured by BIOS (or configuration EEPROM) pwm[1-4] R/O in SmartFan mode, R/W in manual control mode +======================= ======================================================= The driver checks sensor control registers and does not export the sensors that are not enabled. Anyway, a sensor that is enabled may actually be not diff --git a/Documentation/hwmon/npcm750-pwm-fan b/Documentation/hwmon/npcm750-pwm-fan.rst index 6156ef7398e6..c67af08b6773 100644 --- a/Documentation/hwmon/npcm750-pwm-fan +++ b/Documentation/hwmon/npcm750-pwm-fan.rst @@ -2,9 +2,11 @@ Kernel driver npcm750-pwm-fan ============================= Supported chips: + NUVOTON NPCM750/730/715/705 Authors: + <tomer.maimon@nuvoton.com> Description: @@ -15,8 +17,10 @@ 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/nsa320 b/Documentation/hwmon/nsa320.rst index fdbd6947799b..4fe75fd2f937 100644 --- a/Documentation/hwmon/nsa320 +++ b/Documentation/hwmon/nsa320.rst @@ -2,14 +2,23 @@ Kernel driver nsa320_hwmon ========================== Supported chips: + * Holtek HT46R065 microcontroller with onboard firmware that configures + it to act as a hardware monitor. + Prefix: 'nsa320' + Addresses scanned: none + Datasheet: Not available, driver was reverse engineered based upon the + Zyxel kernel source + + Author: + Adam Baker <linux@baker-net.org.uk> Description @@ -31,8 +40,10 @@ tenths of a degree. sysfs-Interface --------------- -temp1_input - temperature input -fan1_input - fan speed +============= ================= +temp1_input temperature input +fan1_input fan speed +============= ================= Notes ----- diff --git a/Documentation/hwmon/ntc_thermistor b/Documentation/hwmon/ntc_thermistor.rst index 8b9ff23edc32..d0e7f91726b9 100644 --- a/Documentation/hwmon/ntc_thermistor +++ b/Documentation/hwmon/ntc_thermistor.rst @@ -1,22 +1,29 @@ Kernel driver ntc_thermistor -================= +============================ Supported thermistors from Murata: + * Murata NTC Thermistors NCP15WB473, NCP18WB473, NCP21WB473, NCP03WB473, NCP15WL333, NCP03WF104, NCP15XH103 + Prefixes: 'ncp15wb473', 'ncp18wb473', 'ncp21wb473', 'ncp03wb473', 'ncp15wl333', 'ncp03wf104', 'ncp15xh103' + Datasheet: Publicly available at Murata Supported thermistors from EPCOS: + * EPCOS NTC Thermistors B57330V2103 + Prefixes: b57330v2103 + Datasheet: Publicly available at EPCOS Other NTC thermistors can be supported simply by adding compensation tables; e.g., NCP15WL333 support is added by the table ncpXXwl333. Authors: + MyungJoo Ham <myungjoo.ham@samsung.com> Description @@ -29,57 +36,60 @@ compensation table to get the temperature input. The NTC driver provides lookup tables with a linear approximation function and four circuit models with an option not to use any of the four models. +Using the following convention:: + + $ resistor + [TH] the thermistor + The four circuit models provided are: - $: resister, [TH]: the thermistor - - 1. connect = NTC_CONNECTED_POSITIVE, pullup_ohm > 0 - - [pullup_uV] - | | - [TH] $ (pullup_ohm) - | | - +----+-----------------------[read_uV] - | - $ (pulldown_ohm) - | - --- (ground) - - 2. connect = NTC_CONNECTED_POSITIVE, pullup_ohm = 0 (not-connected) - - [pullup_uV] - | - [TH] - | - +----------------------------[read_uV] - | - $ (pulldown_ohm) - | - --- (ground) - - 3. connect = NTC_CONNECTED_GROUND, pulldown_ohm > 0 - - [pullup_uV] - | - $ (pullup_ohm) - | - +----+-----------------------[read_uV] - | | - [TH] $ (pulldown_ohm) - | | - -------- (ground) - - 4. connect = NTC_CONNECTED_GROUND, pulldown_ohm = 0 (not-connected) - - [pullup_uV] - | - $ (pullup_ohm) - | - +----------------------------[read_uV] - | - [TH] - | - --- (ground) +1. connect = NTC_CONNECTED_POSITIVE, pullup_ohm > 0:: + + [pullup_uV] + | | + [TH] $ (pullup_ohm) + | | + +----+-----------------------[read_uV] + | + $ (pulldown_ohm) + | + -+- (ground) + +2. connect = NTC_CONNECTED_POSITIVE, pullup_ohm = 0 (not-connected):: + + [pullup_uV] + | + [TH] + | + +----------------------------[read_uV] + | + $ (pulldown_ohm) + | + -+- (ground) + +3. connect = NTC_CONNECTED_GROUND, pulldown_ohm > 0:: + + [pullup_uV] + | + $ (pullup_ohm) + | + +----+-----------------------[read_uV] + | | + [TH] $ (pulldown_ohm) + | | + -+----+- (ground) + +4. connect = NTC_CONNECTED_GROUND, pulldown_ohm = 0 (not-connected):: + + [pullup_uV] + | + $ (pullup_ohm) + | + +----------------------------[read_uV] + | + [TH] + | + -+- (ground) When one of the four circuit models is used, read_uV, pullup_uV, pullup_ohm, pulldown_ohm, and connect should be provided. When none of the four models @@ -88,13 +98,14 @@ provide read_ohm and _not_ provide the others. Sysfs Interface --------------- -name the mandatory global attribute, the thermistor name. -temp1_type always 4 (thermistor) - RO +=============== == ============================================================= +name the mandatory global attribute, the thermistor name. +=============== == ============================================================= +temp1_type RO always 4 (thermistor) -temp1_input measure the temperature and provide the measured value. - (reading this file initiates the reading procedure.) - RO +temp1_input RO measure the temperature and provide the measured value. + (reading this file initiates the reading procedure.) +=============== == ============================================================= Note that each NTC thermistor has only _one_ thermistor; thus, only temp1 exists. diff --git a/Documentation/hwmon/occ b/Documentation/hwmon/occ.rst index e787596e03fe..bf41c162d70e 100644 --- a/Documentation/hwmon/occ +++ b/Documentation/hwmon/occ.rst @@ -2,6 +2,7 @@ Kernel driver occ-hwmon ======================= Supported chips: + * POWER8 * POWER9 @@ -37,53 +38,87 @@ Some entries are only present with certain OCC sensor versions or only on certain OCCs in the system. The version number is not exported to the user but can be inferred. -temp[1-n]_label OCC sensor ID. +temp[1-n]_label + OCC sensor ID. + [with temperature sensor version 1] - temp[1-n]_input Measured temperature of the component in millidegrees + + temp[1-n]_input + Measured temperature of the component in millidegrees Celsius. + [with temperature sensor version >= 2] - temp[1-n]_type The FRU (Field Replaceable Unit) type + + temp[1-n]_type + The FRU (Field Replaceable Unit) type (represented by an integer) for the component that this sensor measures. - temp[1-n]_fault Temperature sensor fault boolean; 1 to indicate + temp[1-n]_fault + Temperature sensor fault boolean; 1 to indicate that a fault is present or 0 to indicate that no fault is present. + [with type == 3 (FRU type is VRM)] - temp[1-n]_alarm VRM temperature alarm boolean; 1 to indicate + + temp[1-n]_alarm + VRM temperature alarm boolean; 1 to indicate alarm, 0 to indicate no alarm + [else] - temp[1-n]_input Measured temperature of the component in - millidegrees Celsius. -freq[1-n]_label OCC sensor ID. -freq[1-n]_input Measured frequency of the component in MHz. + temp[1-n]_input + Measured temperature of the component in + millidegrees Celsius. -power[1-n]_input Latest measured power reading of the component in +freq[1-n]_label + OCC sensor ID. +freq[1-n]_input + Measured frequency of the component in MHz. +power[1-n]_input + Latest measured power reading of the component in microwatts. -power[1-n]_average Average power of the component in microwatts. -power[1-n]_average_interval The amount of time over which the power average +power[1-n]_average + Average power of the component in microwatts. +power[1-n]_average_interval + The amount of time over which the power average was taken in microseconds. + [with power sensor version < 2] - power[1-n]_label OCC sensor ID. + + power[1-n]_label + OCC sensor ID. + [with power sensor version >= 2] - power[1-n]_label OCC sensor ID + function ID + channel in the form + + power[1-n]_label + OCC sensor ID + function ID + channel in the form of a string, delimited by underscores, i.e. "0_15_1". Both the function ID and channel are integers that further identify the power sensor. + [with power sensor version 0xa0] - power[1-n]_label OCC sensor ID + sensor type in the form of a string, + + power[1-n]_label + OCC sensor ID + sensor type in the form of a string, delimited by an underscore, i.e. "0_system". Sensor type will be one of "system", "proc", "vdd" or "vdn". For this sensor version, OCC sensor ID will be the same for all power sensors. + [present only on "master" OCC; represents the whole system power; only one of - this type of power sensor will be present] - power[1-n]_label "system" - power[1-n]_input Latest system output power in microwatts. - power[1-n]_cap Current system power cap in microwatts. - power[1-n]_cap_not_redundant System power cap in microwatts when - there is not redundant power. - power[1-n]_cap_max Maximum power cap that the OCC can enforce in +this type of power sensor will be present] + + power[1-n]_label + "system" + power[1-n]_input + Latest system output power in microwatts. + power[1-n]_cap + Current system power cap in microwatts. + power[1-n]_cap_not_redundant + System power cap in microwatts when + there is not redundant power. + power[1-n]_cap_max + Maximum power cap that the OCC can enforce in microwatts. power[1-n]_cap_min Minimum power cap that the OCC can enforce in microwatts. @@ -94,8 +129,11 @@ power[1-n]_average_interval The amount of time over which the power average ignored, i.e. requesting a power cap of 500900000 microwatts will result in a power cap request of 500 watts. + [with caps sensor version > 1] - power[1-n]_cap_user_source Indicates how the user power cap was + + power[1-n]_cap_user_source + Indicates how the user power cap was set. This is an integer that maps to system or firmware components that can set the user power cap. @@ -104,9 +142,12 @@ The following "extn" sensors are exported as a way for the OCC to provide data that doesn't fit anywhere else. The meaning of these sensors is entirely dependent on their data, and cannot be statically defined. -extn[1-n]_label ASCII ID or OCC sensor ID. -extn[1-n]_flags This is one byte hexadecimal value. Bit 7 indicates the +extn[1-n]_label + ASCII ID or OCC sensor ID. +extn[1-n]_flags + This is one byte hexadecimal value. Bit 7 indicates the type of the label attribute; 1 for sensor ID, 0 for ASCII ID. Other bits are reserved. -extn[1-n]_input 6 bytes of hexadecimal data, with a meaning defined by +extn[1-n]_input + 6 bytes of hexadecimal data, with a meaning defined by the sensor ID. diff --git a/Documentation/hwmon/pc87360 b/Documentation/hwmon/pc87360.rst index d5f5cf16ce59..4bad07bce54b 100644 --- a/Documentation/hwmon/pc87360 +++ b/Documentation/hwmon/pc87360.rst @@ -2,14 +2,19 @@ Kernel driver pc87360 ===================== Supported chips: + * National Semiconductor PC87360, PC87363, PC87364, PC87365 and PC87366 + Prefixes: 'pc87360', 'pc87363', 'pc87364', 'pc87365', 'pc87366' + Addresses scanned: none, address read from Super I/O config space + Datasheets: No longer available Authors: Jean Delvare <jdelvare@suse.de> Thanks to Sandeep Mehta, Tonko de Rooy and Daniel Ceregatti for testing. + Thanks to Rudolf Marek for helping me investigate conversion issues. @@ -17,11 +22,13 @@ Module Parameters ----------------- * init int - Chip initialization level: - 0: None - *1: Forcibly enable internal voltage and temperature channels, except in9 - 2: Forcibly enable all voltage and temperature channels, except in9 - 3: Forcibly enable all voltage and temperature channels, including in9 + Chip initialization level: + + - 0: None + - **1**: Forcibly enable internal voltage and temperature channels, + except in9 + - 2: Forcibly enable all voltage and temperature channels, except in9 + - 3: Forcibly enable all voltage and temperature channels, including in9 Note that this parameter has no effect for the PC87360, PC87363 and PC87364 chips. @@ -43,13 +50,15 @@ hardware monitoring chipsets, not only controlling and monitoring three fans, but also monitoring eleven voltage inputs and two (PC87365) or up to four (PC87366) temperatures. + =========== ======= ======= ======= ======= ===== Chip #vin #fan #pwm #temp devid - + =========== ======= ======= ======= ======= ===== PC87360 - 2 2 - 0xE1 PC87363 - 2 2 - 0xE8 PC87364 - 3 3 - 0xE4 PC87365 11 3 3 2 0xE5 PC87366 11 3 3 3-4 0xE9 + =========== ======= ======= ======= ======= ===== The driver assumes that no more than one chip is present, and one of the standard Super I/O addresses is used (0x2E/0x2F or 0x4E/0x4F) @@ -68,18 +77,23 @@ have to care no more. For reference, here are a few values about clock dividers: - slowest accuracy highest - measurable around 3000 accurate + =========== =============== =============== =========== + slowest accuracy highest + measurable around 3000 accurate divider speed (RPM) RPM (RPM) speed (RPM) - 1 1882 18 6928 - 2 941 37 4898 - 4 470 74 3464 - 8 235 150 2449 + =========== =============== =============== =========== + 1 1882 18 6928 + 2 941 37 4898 + 4 470 74 3464 + 8 235 150 2449 + =========== =============== =============== =========== For the curious, here is how the values above were computed: + * slowest measurable speed: clock/(255*divider) * accuracy around 3000 RPM: 3000^2/clock * highest accurate speed: sqrt(clock*100) + The clock speed for the PC87360 family is 480 kHz. I arbitrarily chose 100 RPM as the lowest acceptable accuracy. diff --git a/Documentation/hwmon/pc87427 b/Documentation/hwmon/pc87427.rst index c313eb66e08a..22d8f62d851f 100644 --- a/Documentation/hwmon/pc87427 +++ b/Documentation/hwmon/pc87427.rst @@ -2,9 +2,13 @@ Kernel driver pc87427 ===================== Supported chips: + * National Semiconductor PC87427 + Prefix: 'pc87427' + Addresses scanned: none, address read from Super I/O config space + Datasheet: No longer available Author: Jean Delvare <jdelvare@suse.de> diff --git a/Documentation/hwmon/pcf8591 b/Documentation/hwmon/pcf8591.rst index 447c0702c0ec..e98bd542a441 100644 --- a/Documentation/hwmon/pcf8591 +++ b/Documentation/hwmon/pcf8591.rst @@ -2,16 +2,21 @@ Kernel driver pcf8591 ===================== Supported chips: + * Philips/NXP PCF8591 + Prefix: 'pcf8591' + Addresses scanned: none + Datasheet: Publicly available at the NXP website - http://www.nxp.com/pip/PCF8591_6.html + + http://www.nxp.com/pip/PCF8591_6.html Authors: - Aurelien Jarno <aurelien@aurel32.net> - valuable contributions by Jan M. Sendler <sendler@sendler.de>, - Jean Delvare <jdelvare@suse.de> + - Aurelien Jarno <aurelien@aurel32.net> + - valuable contributions by Jan M. Sendler <sendler@sendler.de>, + - Jean Delvare <jdelvare@suse.de> Description @@ -22,24 +27,25 @@ analog output) for the I2C bus produced by Philips Semiconductors (now NXP). It is designed to provide a byte I2C interface to up to 4 separate devices. The PCF8591 has 4 analog inputs programmable as single-ended or -differential inputs : +differential inputs: + - mode 0 : four single ended inputs - Pins AIN0 to AIN3 are single ended inputs for channels 0 to 3 + Pins AIN0 to AIN3 are single ended inputs for channels 0 to 3 - mode 1 : three differential inputs - Pins AIN3 is the common negative differential input - Pins AIN0 to AIN2 are positive differential inputs for channels 0 to 2 + Pins AIN3 is the common negative differential input + Pins AIN0 to AIN2 are positive differential inputs for channels 0 to 2 - mode 2 : single ended and differential mixed - Pins AIN0 and AIN1 are single ended inputs for channels 0 and 1 - Pins AIN2 is the positive differential input for channel 3 - Pins AIN3 is the negative differential input for channel 3 + Pins AIN0 and AIN1 are single ended inputs for channels 0 and 1 + Pins AIN2 is the positive differential input for channel 3 + Pins AIN3 is the negative differential input for channel 3 - mode 3 : two differential inputs - Pins AIN0 is the positive differential input for channel 0 - Pins AIN1 is the negative differential input for channel 0 - Pins AIN2 is the positive differential input for channel 1 - Pins AIN3 is the negative differential input for channel 1 + Pins AIN0 is the positive differential input for channel 0 + Pins AIN1 is the negative differential input for channel 0 + Pins AIN2 is the positive differential input for channel 1 + Pins AIN3 is the negative differential input for channel 1 See the datasheet for details. @@ -49,10 +55,11 @@ Module parameters * input_mode int Analog input mode: - 0 = four single ended inputs - 1 = three differential inputs - 2 = single ended and differential mixed - 3 = two differential inputs + + - 0 = four single ended inputs + - 1 = three differential inputs + - 2 = single ended and differential mixed + - 3 = two differential inputs Accessing PCF8591 via /sys interface @@ -67,11 +74,12 @@ for details. Directories are being created for each instantiated PCF8591: /sys/bus/i2c/devices/<0>-<1>/ -where <0> is the bus the chip is connected to (e. g. i2c-0) -and <1> the chip address ([48..4f]) + where <0> is the bus the chip is connected to (e. g. i2c-0) + and <1> the chip address ([48..4f]) Inside these directories, there are such files: -in0_input, in1_input, in2_input, in3_input, out0_enable, out0_output, name + + in0_input, in1_input, in2_input, in3_input, out0_enable, out0_output, name Name contains chip name. diff --git a/Documentation/hwmon/pmbus-core b/Documentation/hwmon/pmbus-core.rst index 8ed10e9ddfb5..92515c446fe3 100644 --- a/Documentation/hwmon/pmbus-core +++ b/Documentation/hwmon/pmbus-core.rst @@ -1,3 +1,4 @@ +================================== PMBus core driver and internal API ================================== @@ -120,24 +121,24 @@ Specifically, it provides the following information. non-standard PMBus commands to standard commands, or to augment standard command return values with device specific information. - API functions - ------------- +API functions +============= - Functions provided by chip driver - --------------------------------- +Functions provided by chip driver +--------------------------------- - All functions return the command return value (read) or zero (write) if - successful. A return value of -ENODATA indicates that there is no manufacturer - specific command, but that a standard PMBus command may exist. Any other - negative return value indicates that the commands does not exist for this - chip, and that no attempt should be made to read or write the standard - command. +All functions return the command return value (read) or zero (write) if +successful. A return value of -ENODATA indicates that there is no manufacturer +specific command, but that a standard PMBus command may exist. Any other +negative return value indicates that the commands does not exist for this +chip, and that no attempt should be made to read or write the standard +command. - As mentioned above, an exception to this rule applies to virtual commands, - which _must_ be handled in driver specific code. See "Virtual PMBus Commands" - above for more details. +As mentioned above, an exception to this rule applies to virtual commands, +which *must* be handled in driver specific code. See "Virtual PMBus Commands" +above for more details. - Command execution in the core PMBus driver code is as follows. +Command execution in the core PMBus driver code is as follows:: if (chip_access_function) { status = chip_access_function(); @@ -148,128 +149,160 @@ Specifically, it provides the following information. return -EINVAL; return generic_access(); - Chip drivers may provide pointers to the following functions in struct - pmbus_driver_info. All functions are optional. +Chip drivers may provide pointers to the following functions in struct +pmbus_driver_info. All functions are optional. + +:: int (*read_byte_data)(struct i2c_client *client, int page, int reg); - Read byte from page <page>, register <reg>. - <page> may be -1, which means "current page". +Read byte from page <page>, register <reg>. +<page> may be -1, which means "current page". + + +:: int (*read_word_data)(struct i2c_client *client, int page, int reg); - Read word from page <page>, register <reg>. +Read word from page <page>, register <reg>. + +:: int (*write_word_data)(struct i2c_client *client, int page, int reg, - u16 word); + u16 word); - Write word to page <page>, register <reg>. +Write word to page <page>, register <reg>. + +:: int (*write_byte)(struct i2c_client *client, int page, u8 value); - Write byte to page <page>, register <reg>. - <page> may be -1, which means "current page". +Write byte to page <page>, register <reg>. +<page> may be -1, which means "current page". + +:: int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info); - Determine supported PMBus functionality. This function is only necessary - if a chip driver supports multiple chips, and the chip functionality is not - pre-determined. It is currently only used by the generic pmbus driver - (pmbus.c). +Determine supported PMBus functionality. This function is only necessary +if a chip driver supports multiple chips, and the chip functionality is not +pre-determined. It is currently only used by the generic pmbus driver +(pmbus.c). + +Functions exported by core driver +--------------------------------- - Functions exported by core driver - --------------------------------- +Chip drivers are expected to use the following functions to read or write +PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C +commands are used, the chip driver code must not directly modify the current +page, since the selected page is cached in the core driver and the core driver +will assume that it is selected. Using pmbus_set_page() to select a new page +is mandatory. - Chip drivers are expected to use the following functions to read or write - PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C - commands are used, the chip driver code must not directly modify the current - page, since the selected page is cached in the core driver and the core driver - will assume that it is selected. Using pmbus_set_page() to select a new page - is mandatory. +:: int pmbus_set_page(struct i2c_client *client, u8 page); - Set PMBus page register to <page> for subsequent commands. +Set PMBus page register to <page> for subsequent commands. + +:: int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 reg); - Read word data from <page>, <reg>. Similar to i2c_smbus_read_word_data(), but - selects page first. +Read word data from <page>, <reg>. Similar to i2c_smbus_read_word_data(), but +selects page first. + +:: int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg, u16 word); - Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but - selects page first. +Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but +selects page first. + +:: int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg); - Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but - selects page first. <page> may be -1, which means "current page". +Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but +selects page first. <page> may be -1, which means "current page". + +:: int pmbus_write_byte(struct i2c_client *client, int page, u8 value); - Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but - selects page first. <page> may be -1, which means "current page". +Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but +selects page first. <page> may be -1, which means "current page". + +:: void pmbus_clear_faults(struct i2c_client *client); - Execute PMBus "Clear Fault" command on all chip pages. - This function calls the device specific write_byte function if defined. - Therefore, it must _not_ be called from that function. +Execute PMBus "Clear Fault" command on all chip pages. +This function calls the device specific write_byte function if defined. +Therefore, it must _not_ be called from that function. + +:: bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg); - Check if byte register exists. Return true if the register exists, false - otherwise. - This function calls the device specific write_byte function if defined to - obtain the chip status. Therefore, it must _not_ be called from that function. +Check if byte register exists. Return true if the register exists, false +otherwise. +This function calls the device specific write_byte function if defined to +obtain the chip status. Therefore, it must _not_ be called from that function. + +:: bool pmbus_check_word_register(struct i2c_client *client, int page, int reg); - Check if word register exists. Return true if the register exists, false - otherwise. - This function calls the device specific write_byte function if defined to - obtain the chip status. Therefore, it must _not_ be called from that function. +Check if word register exists. Return true if the register exists, false +otherwise. +This function calls the device specific write_byte function if defined to +obtain the chip status. Therefore, it must _not_ be called from that function. + +:: int pmbus_do_probe(struct i2c_client *client, const struct i2c_device_id *id, - struct pmbus_driver_info *info); + struct pmbus_driver_info *info); + +Execute probe function. Similar to standard probe function for other drivers, +with the pointer to struct pmbus_driver_info as additional argument. Calls +identify function if supported. Must only be called from device probe +function. - Execute probe function. Similar to standard probe function for other drivers, - with the pointer to struct pmbus_driver_info as additional argument. Calls - identify function if supported. Must only be called from device probe - function. +:: void pmbus_do_remove(struct i2c_client *client); - Execute driver remove function. Similar to standard driver remove function. +Execute driver remove function. Similar to standard driver remove function. + +:: const struct pmbus_driver_info *pmbus_get_driver_info(struct i2c_client *client); - Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe(). +Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe(). PMBus driver platform data ========================== PMBus platform data is defined in include/linux/pmbus.h. Platform data -currently only provides a flag field with a single bit used. +currently only provides a flag field with a single bit used:: -#define PMBUS_SKIP_STATUS_CHECK (1 << 0) + #define PMBUS_SKIP_STATUS_CHECK (1 << 0) -struct pmbus_platform_data { - u32 flags; /* Device specific flags */ -}; + struct pmbus_platform_data { + u32 flags; /* Device specific flags */ + }; Flags ----- PMBUS_SKIP_STATUS_CHECK - -During register detection, skip checking the status register for -communication or command errors. + During register detection, skip checking the status register for + communication or command errors. Some PMBus chips respond with valid data when trying to read an unsupported register. For such chips, checking the status register is mandatory when diff --git a/Documentation/hwmon/pmbus b/Documentation/hwmon/pmbus.rst index dfd9c65996c0..abfb9dd4857d 100644 --- a/Documentation/hwmon/pmbus +++ b/Documentation/hwmon/pmbus.rst @@ -1,42 +1,77 @@ Kernel driver pmbus -==================== +=================== Supported chips: + * Ericsson BMR453, BMR454 + Prefixes: 'bmr453', 'bmr454' + Addresses scanned: - + Datasheet: + http://archive.ericsson.net/service/internet/picov/get?DocNo=28701-EN/LZT146395 + * ON Semiconductor ADP4000, NCP4200, NCP4208 + Prefixes: 'adp4000', 'ncp4200', 'ncp4208' + Addresses scanned: - + Datasheets: + http://www.onsemi.com/pub_link/Collateral/ADP4000-D.PDF + http://www.onsemi.com/pub_link/Collateral/NCP4200-D.PDF + http://www.onsemi.com/pub_link/Collateral/JUNE%202009-%20REV.%200.PDF + * Lineage Power + Prefixes: 'mdt040', 'pdt003', 'pdt006', 'pdt012', 'udt020' + Addresses scanned: - + Datasheets: + http://www.lineagepower.com/oem/pdf/PDT003A0X.pdf + http://www.lineagepower.com/oem/pdf/PDT006A0X.pdf + http://www.lineagepower.com/oem/pdf/PDT012A0X.pdf + http://www.lineagepower.com/oem/pdf/UDT020A0X.pdf + http://www.lineagepower.com/oem/pdf/MDT040A0X.pdf + * Texas Instruments TPS40400, TPS544B20, TPS544B25, TPS544C20, TPS544C25 + Prefixes: 'tps40400', 'tps544b20', 'tps544b25', 'tps544c20', 'tps544c25' + Addresses scanned: - + Datasheets: + http://www.ti.com/lit/gpn/tps40400 + http://www.ti.com/lit/gpn/tps544b20 + http://www.ti.com/lit/gpn/tps544b25 + http://www.ti.com/lit/gpn/tps544c20 + http://www.ti.com/lit/gpn/tps544c25 + * Generic PMBus devices + Prefix: 'pmbus' + Addresses scanned: - + Datasheet: n.a. + Author: Guenter Roeck <linux@roeck-us.net> @@ -62,9 +97,10 @@ supported by all chips), and since there is no well defined address range for PMBus devices. You will have to instantiate the devices explicitly. Example: the following will load the driver for an LTC2978 at address 0x60 -on I2C bus #1: -$ modprobe pmbus -$ echo ltc2978 0x60 > /sys/bus/i2c/devices/i2c-1/new_device +on I2C bus #1:: + + $ modprobe pmbus + $ echo ltc2978 0x60 > /sys/bus/i2c/devices/i2c-1/new_device Platform data support @@ -72,9 +108,9 @@ Platform data support Support for additional PMBus chips can be added by defining chip parameters in a new chip specific driver file. For example, (untested) code to add support for -Emerson DS1200 power modules might look as follows. +Emerson DS1200 power modules might look as follows:: -static struct pmbus_driver_info ds1200_info = { + static struct pmbus_driver_info ds1200_info = { .pages = 1, /* Note: All other sensors are in linear mode */ .direct[PSC_VOLTAGE_OUT] = true, @@ -95,45 +131,45 @@ static struct pmbus_driver_info ds1200_info = { | PMBUS_HAVE_PIN | PMBUS_HAVE_POUT | PMBUS_HAVE_TEMP | PMBUS_HAVE_STATUS_TEMP | PMBUS_HAVE_FAN12 | PMBUS_HAVE_STATUS_FAN12, -}; + }; -static int ds1200_probe(struct i2c_client *client, - const struct i2c_device_id *id) -{ + static int ds1200_probe(struct i2c_client *client, + const struct i2c_device_id *id) + { return pmbus_do_probe(client, id, &ds1200_info); -} + } -static int ds1200_remove(struct i2c_client *client) -{ + static int ds1200_remove(struct i2c_client *client) + { return pmbus_do_remove(client); -} + } -static const struct i2c_device_id ds1200_id[] = { + static const struct i2c_device_id ds1200_id[] = { {"ds1200", 0}, {} -}; + }; -MODULE_DEVICE_TABLE(i2c, ds1200_id); + MODULE_DEVICE_TABLE(i2c, ds1200_id); -/* This is the driver that will be inserted */ -static struct i2c_driver ds1200_driver = { + /* This is the driver that will be inserted */ + static struct i2c_driver ds1200_driver = { .driver = { .name = "ds1200", }, .probe = ds1200_probe, .remove = ds1200_remove, .id_table = ds1200_id, -}; + }; -static int __init ds1200_init(void) -{ + static int __init ds1200_init(void) + { return i2c_add_driver(&ds1200_driver); -} + } -static void __exit ds1200_exit(void) -{ + static void __exit ds1200_exit(void) + { i2c_del_driver(&ds1200_driver); -} + } Sysfs entries @@ -148,6 +184,7 @@ a given sysfs entry. The following attributes are supported. Limits are read-write; all other attributes are read-only. +======================= ======================================================== inX_input Measured voltage. From READ_VIN or READ_VOUT register. inX_min Minimum Voltage. From VIN_UV_WARN_LIMIT or VOUT_UV_WARN_LIMIT register. @@ -214,3 +251,4 @@ tempX_lcrit_alarm Chip temperature critical low alarm. Set by comparing tempX_crit_alarm Chip temperature critical high alarm. Set by comparing READ_TEMPERATURE_X with OT_FAULT_LIMIT if TEMP_OT_FAULT status is set. +======================= ======================================================== diff --git a/Documentation/hwmon/powr1220 b/Documentation/hwmon/powr1220.rst index 21e44f71ae6e..a7fc258da0a8 100644 --- a/Documentation/hwmon/powr1220 +++ b/Documentation/hwmon/powr1220.rst @@ -1,12 +1,17 @@ Kernel driver powr1220 -================== +====================== Supported chips: + * Lattice POWR1220AT8 + Prefix: 'powr1220' + Addresses scanned: none + Datasheet: Publicly available at the Lattice website - http://www.latticesemi.com/ + + http://www.latticesemi.com/ Author: Scott Kanowitz <scott.kanowitz@gmail.com> @@ -26,7 +31,9 @@ value over the low measurement range maximum of 2 V. The input naming convention is as follows: +============== ======== driver name pin name +============== ======== in0 VMON1 in1 VMON2 in2 VMON3 @@ -41,5 +48,6 @@ in10 VMON11 in11 VMON12 in12 VCCA in13 VCCINP +============== ======== The ADC readings are updated on request with a minimum period of 1s. diff --git a/Documentation/hwmon/pwm-fan b/Documentation/hwmon/pwm-fan.rst index 18529d2e3bcf..82fe96742fee 100644 --- a/Documentation/hwmon/pwm-fan +++ b/Documentation/hwmon/pwm-fan.rst @@ -15,3 +15,6 @@ The driver implements a simple interface for driving a fan connected to a PWM output. It uses the generic PWM interface, thus it can be used with a range of SoCs. The driver exposes the fan to the user space through the hwmon's sysfs interface. + +The fan rotation speed returned via the optional 'fan1_input' is extrapolated +from the sampled interrupts from the tachometer signal within 1 second. diff --git a/Documentation/hwmon/raspberrypi-hwmon b/Documentation/hwmon/raspberrypi-hwmon.rst index 3c92e2cb52d6..8038ade36490 100644 --- a/Documentation/hwmon/raspberrypi-hwmon +++ b/Documentation/hwmon/raspberrypi-hwmon.rst @@ -2,6 +2,7 @@ Kernel driver raspberrypi-hwmon =============================== Supported boards: + * Raspberry Pi A+ (via GPIO on SoC) * Raspberry Pi B+ (via GPIO on SoC) * Raspberry Pi 2 B (via GPIO on SoC) @@ -19,4 +20,6 @@ undervoltage conditions. Sysfs entries ------------- +======================= ================== in0_lcrit_alarm Undervoltage alarm +======================= ================== diff --git a/Documentation/hwmon/sch5627 b/Documentation/hwmon/sch5627.rst index 0551d266c51c..187682e99114 100644 --- a/Documentation/hwmon/sch5627 +++ b/Documentation/hwmon/sch5627.rst @@ -2,9 +2,13 @@ Kernel driver sch5627 ===================== Supported chips: + * SMSC SCH5627 + Prefix: 'sch5627' + Addresses scanned: none, address read from Super I/O config space + Datasheet: Application Note available upon request Author: Hans de Goede <hdegoede@redhat.com> diff --git a/Documentation/hwmon/sch5636 b/Documentation/hwmon/sch5636.rst index 7b0a01da0717..4aaee3672f13 100644 --- a/Documentation/hwmon/sch5636 +++ b/Documentation/hwmon/sch5636.rst @@ -2,8 +2,11 @@ Kernel driver sch5636 ===================== Supported chips: + * SMSC SCH5636 + Prefix: 'sch5636' + Addresses scanned: none, address read from Super I/O config space Author: Hans de Goede <hdegoede@redhat.com> diff --git a/Documentation/hwmon/scpi-hwmon b/Documentation/hwmon/scpi-hwmon.rst index 4cfcdf2d5eab..eee7022b44db 100644 --- a/Documentation/hwmon/scpi-hwmon +++ b/Documentation/hwmon/scpi-hwmon.rst @@ -2,8 +2,11 @@ Kernel driver scpi-hwmon ======================== Supported chips: + * Chips based on ARM System Control Processor Interface + Addresses scanned: - + Datasheet: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0922b/index.html Author: Punit Agrawal <punit.agrawal@arm.com> @@ -14,7 +17,7 @@ Description This driver supports hardware monitoring for SoC's based on the ARM System Control Processor (SCP) implementing the System Control Processor Interface (SCPI). The following sensor types are supported -by the SCP - +by the SCP: * temperature * voltage @@ -30,4 +33,4 @@ Usage Notes The driver relies on device tree node to indicate the presence of SCPI support in the kernel. See Documentation/devicetree/bindings/arm/arm,scpi.txt for details of the -devicetree node.
\ No newline at end of file +devicetree node. diff --git a/Documentation/hwmon/sht15 b/Documentation/hwmon/sht15.rst index 5e3207c3b177..485abe037f6c 100644 --- a/Documentation/hwmon/sht15 +++ b/Documentation/hwmon/sht15.rst @@ -2,29 +2,37 @@ Kernel driver sht15 =================== Authors: + * Wouter Horre * Jonathan Cameron * Vivien Didelot <vivien.didelot@savoirfairelinux.com> * Jerome Oufella <jerome.oufella@savoirfairelinux.com> Supported chips: + * Sensirion SHT10 + Prefix: 'sht10' * Sensirion SHT11 + Prefix: 'sht11' * Sensirion SHT15 + Prefix: 'sht15' * Sensirion SHT71 + Prefix: 'sht71' * Sensirion SHT75 + Prefix: 'sht75' Datasheet: Publicly available at the Sensirion website -http://www.sensirion.ch/en/pdf/product_information/Datasheet-humidity-sensor-SHT1x.pdf + + http://www.sensirion.ch/en/pdf/product_information/Datasheet-humidity-sensor-SHT1x.pdf Description ----------- @@ -63,11 +71,13 @@ Platform data Sysfs interface --------------- -* temp1_input: temperature input -* humidity1_input: humidity input -* heater_enable: write 1 in this attribute to enable the on-chip heater, - 0 to disable it. Be careful not to enable the heater - for too long. -* temp1_fault: if 1, this means that the voltage is low (below 2.47V) and - measurement may be invalid. -* humidity1_fault: same as temp1_fault. +================== ========================================================== +temp1_input temperature input +humidity1_input humidity input +heater_enable write 1 in this attribute to enable the on-chip heater, + 0 to disable it. Be careful not to enable the heater + for too long. +temp1_fault if 1, this means that the voltage is low (below 2.47V) and + measurement may be invalid. +humidity1_fault same as temp1_fault. +================== ========================================================== diff --git a/Documentation/hwmon/sht21 b/Documentation/hwmon/sht21.rst index 8b3cdda541c1..f1f5da030108 100644 --- a/Documentation/hwmon/sht21 +++ b/Documentation/hwmon/sht21.rst @@ -2,19 +2,33 @@ Kernel driver sht21 =================== Supported chips: + * Sensirion SHT21 + Prefix: 'sht21' + Addresses scanned: none + Datasheet: Publicly available at the Sensirion website + http://www.sensirion.com/file/datasheet_sht21 + + * Sensirion SHT25 + Prefix: 'sht25' + Addresses scanned: none + Datasheet: Publicly available at the Sensirion website + http://www.sensirion.com/file/datasheet_sht25 + + Author: + Urs Fleisch <urs.fleisch@sensirion.com> Description @@ -33,9 +47,13 @@ in the board setup code. sysfs-Interface --------------- -temp1_input - temperature input -humidity1_input - humidity input -eic - Electronic Identification Code +temp1_input + - temperature input + +humidity1_input + - humidity input +eic + - Electronic Identification Code Notes ----- diff --git a/Documentation/hwmon/sht3x b/Documentation/hwmon/sht3x.rst index d9daa6ab1e8e..978a7117e4b2 100644 --- a/Documentation/hwmon/sht3x +++ b/Documentation/hwmon/sht3x.rst @@ -2,14 +2,19 @@ Kernel driver sht3x =================== Supported chips: + * Sensirion SHT3x-DIS + Prefix: 'sht3x' + Addresses scanned: none + Datasheet: https://www.sensirion.com/file/datasheet_sht3x_digital Author: - David Frey <david.frey@sensirion.com> - Pascal Sachs <pascal.sachs@sensirion.com> + + - David Frey <david.frey@sensirion.com> + - Pascal Sachs <pascal.sachs@sensirion.com> Description ----------- @@ -24,6 +29,7 @@ addresses 0x44 or 0x45, depending on the wiring. See Documentation/i2c/instantiating-devices for methods to instantiate the device. There are two options configurable by means of sht3x_platform_data: + 1. blocking (pull the I2C clock line down while performing the measurement) or non-blocking mode. Blocking mode will guarantee the fastest result but the I2C bus will be busy during that time. By default, non-blocking mode @@ -35,12 +41,15 @@ There are two options configurable by means of sht3x_platform_data: The sht3x sensor supports a single shot mode as well as 5 periodic measure modes, which can be controlled with the update_interval sysfs interface. The allowed update_interval in milliseconds are as follows: - * 0 single shot mode - * 2000 0.5 Hz periodic measurement - * 1000 1 Hz periodic measurement - * 500 2 Hz periodic measurement - * 250 4 Hz periodic measurement - * 100 10 Hz periodic measurement + + ===== ======= ==================== + 0 single shot mode + 2000 0.5 Hz periodic measurement + 1000 1 Hz periodic measurement + 500 2 Hz periodic measurement + 250 4 Hz periodic measurement + 100 10 Hz periodic measurement + ===== ======= ==================== In the periodic measure mode, the sensor automatically triggers a measurement with the configured update interval on the chip. When a temperature or humidity @@ -53,6 +62,7 @@ low. sysfs-Interface --------------- +=================== ============================================================ temp1_input: temperature input humidity1_input: humidity input temp1_max: temperature max value @@ -64,13 +74,15 @@ temp1_min_hyst: temperature hysteresis value for min limit humidity1_min: humidity min value humidity1_min_hyst: humidity hysteresis value for min limit temp1_alarm: alarm flag is set to 1 if the temperature is outside the - configured limits. Alarm only works in periodic measure mode + configured limits. Alarm only works in periodic measure mode humidity1_alarm: alarm flag is set to 1 if the humidity is outside the - configured limits. Alarm only works in periodic measure mode + configured limits. Alarm only works in periodic measure mode heater_enable: heater enable, heating element removes excess humidity from - sensor - 0: turned off - 1: turned on + sensor: + + - 0: turned off + - 1: turned on update_interval: update interval, 0 for single shot, interval in msec - for periodic measurement. If the interval is not supported - by the sensor, the next faster interval is chosen + for periodic measurement. If the interval is not supported + by the sensor, the next faster interval is chosen +=================== ============================================================ diff --git a/Documentation/hwmon/shtc1 b/Documentation/hwmon/shtc1.rst index 6b1e05458f0f..aa116332ba26 100644 --- a/Documentation/hwmon/shtc1 +++ b/Documentation/hwmon/shtc1.rst @@ -2,17 +2,29 @@ Kernel driver shtc1 =================== Supported chips: + * Sensirion SHTC1 + Prefix: 'shtc1' + Addresses scanned: none + Datasheet: http://www.sensirion.com/file/datasheet_shtc1 + + * Sensirion SHTW1 + Prefix: 'shtw1' + Addresses scanned: none + Datasheet: Not publicly available + + Author: + Johannes Winkelmann <johannes.winkelmann@sensirion.com> Description @@ -28,6 +40,7 @@ address 0x70. See Documentation/i2c/instantiating-devices for methods to instantiate the device. There are two options configurable by means of shtc1_platform_data: + 1. blocking (pull the I2C clock line down while performing the measurement) or non-blocking mode. Blocking mode will guarantee the fastest result but the I2C bus will be busy during that time. By default, non-blocking mode @@ -39,5 +52,7 @@ There are two options configurable by means of shtc1_platform_data: sysfs-Interface --------------- -temp1_input - temperature input -humidity1_input - humidity input +temp1_input + - temperature input +humidity1_input + - humidity input diff --git a/Documentation/hwmon/sis5595 b/Documentation/hwmon/sis5595.rst index 4f8877a34f37..16123b3bfff9 100644 --- a/Documentation/hwmon/sis5595 +++ b/Documentation/hwmon/sis5595.rst @@ -2,49 +2,67 @@ Kernel driver sis5595 ===================== Supported chips: + * Silicon Integrated Systems Corp. SiS5595 Southbridge Hardware Monitor + Prefix: 'sis5595' + Addresses scanned: ISA in PCI-space encoded address + Datasheet: Publicly available at the Silicon Integrated Systems Corp. site. + + Authors: - Kyösti Mälkki <kmalkki@cc.hut.fi>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Aurelien Jarno <aurelien@aurel32.net> 2.6 port + + - Kyösti Mälkki <kmalkki@cc.hut.fi>, + - Mark D. Studebaker <mdsxyz123@yahoo.com>, + - Aurelien Jarno <aurelien@aurel32.net> 2.6 port SiS southbridge has a LM78-like chip integrated on the same IC. This driver is a customized copy of lm78.c Supports following revisions: + + =============== =============== ============== Version PCI ID PCI Revision + =============== =============== ============== 1 1039/0008 AF or less 2 1039/0008 B0 or greater + =============== =============== ============== Note: these chips contain a 0008 device which is incompatible with the - 5595. We recognize these by the presence of the listed - "blacklist" PCI ID and refuse to load. + 5595. We recognize these by the presence of the listed + "blacklist" PCI ID and refuse to load. + =================== =============== ================ NOT SUPPORTED PCI ID BLACKLIST PCI ID - 540 0008 0540 - 550 0008 0550 + =================== =============== ================ + 540 0008 0540 + 550 0008 0550 5513 0008 5511 5581 0008 5597 5582 0008 5597 5597 0008 5597 - 630 0008 0630 - 645 0008 0645 - 730 0008 0730 - 735 0008 0735 + 630 0008 0630 + 645 0008 0645 + 730 0008 0730 + 735 0008 0735 + =================== =============== ================ Module Parameters ----------------- + +======================= ===================================================== force_addr=0xaddr Set the I/O base address. Useful for boards that don't set the address in the BIOS. Does not do a PCI force; the device must still be present in lspci. Don't use this unless the driver complains that the base address is not set. + Example: 'modprobe sis5595 force_addr=0x290' +======================= ===================================================== Description @@ -103,4 +121,3 @@ Problems -------- Some chips refuse to be enabled. We don't know why. The driver will recognize this and print a message in dmesg. - diff --git a/Documentation/hwmon/smm665 b/Documentation/hwmon/smm665.rst index a341eeedab75..a0e27f62b57b 100644 --- a/Documentation/hwmon/smm665 +++ b/Documentation/hwmon/smm665.rst @@ -2,31 +2,57 @@ Kernel driver smm665 ==================== Supported chips: + * Summit Microelectronics SMM465 + Prefix: 'smm465' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM465/SMM465DS.pdf + * Summit Microelectronics SMM665, SMM665B + Prefix: 'smm665' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM665/SMM665B_2089_20.pdf + * Summit Microelectronics SMM665C + Prefix: 'smm665c' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM665C/SMM665C_2125.pdf + * Summit Microelectronics SMM764 + Prefix: 'smm764' + Addresses scanned: - + Datasheet: + http://www.summitmicro.com/prod_select/summary/SMM764/SMM764_2098.pdf + * Summit Microelectronics SMM766, SMM766B + Prefix: 'smm766' + Addresses scanned: - + Datasheets: + http://www.summitmicro.com/prod_select/summary/SMM766/SMM766_2086.pdf + http://www.summitmicro.com/prod_select/summary/SMM766B/SMM766B_2122.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -36,9 +62,10 @@ Module Parameters ----------------- * vref: int - Default: 1250 (mV) - Reference voltage on VREF_ADC pin in mV. It should not be necessary to set - this parameter unless a non-default reference voltage is used. + Default: 1250 (mV) + + Reference voltage on VREF_ADC pin in mV. It should not be necessary to set + this parameter unless a non-default reference voltage is used. Description @@ -64,9 +91,10 @@ the devices explicitly. When instantiating the device, you have to specify its configuration register address. Example: the following will load the driver for an SMM665 at address 0x57 -on I2C bus #1: -$ modprobe smm665 -$ echo smm665 0x57 > /sys/bus/i2c/devices/i2c-1/new_device +on I2C bus #1:: + + $ modprobe smm665 + $ echo smm665 0x57 > /sys/bus/i2c/devices/i2c-1/new_device Sysfs entries @@ -84,6 +112,7 @@ max otherwise. For details please see the SMM665 datasheet. For SMM465 and SMM764, values for Channel E and F are reported but undefined. +======================= ======================================================= in1_input 12V input voltage (mV) in2_input 3.3V (VDD) input voltage (mV) in3_input Channel A voltage (mV) @@ -155,3 +184,4 @@ temp1_min Mimimum chip temperature temp1_max Maximum chip temperature temp1_crit Critical chip temperature temp1_crit_alarm Temperature critical alarm +======================= ======================================================= diff --git a/Documentation/hwmon/smsc47b397 b/Documentation/hwmon/smsc47b397.rst index 3a43b6948924..600194cf1804 100644 --- a/Documentation/hwmon/smsc47b397 +++ b/Documentation/hwmon/smsc47b397.rst @@ -2,29 +2,38 @@ Kernel driver smsc47b397 ======================== Supported chips: + * SMSC LPC47B397-NC + * SMSC SCH5307-NS + * SMSC SCH5317 + Prefix: 'smsc47b397' + Addresses scanned: none, address read from Super I/O config space + Datasheet: In this file -Authors: Mark M. Hoffman <mhoffman@lightlink.com> - Utilitek Systems, Inc. +Authors: + + - Mark M. Hoffman <mhoffman@lightlink.com> + - Utilitek Systems, Inc. November 23, 2004 -The following specification describes the SMSC LPC47B397-NC[1] sensor chip +The following specification describes the SMSC LPC47B397-NC [1]_ sensor chip (for which there is no public datasheet available). This document was provided by Craig Kelly (In-Store Broadcast Network) and edited/corrected by Mark M. Hoffman <mhoffman@lightlink.com>. -[1] And SMSC SCH5307-NS and SCH5317, which have different device IDs but are -otherwise compatible. +.. [1] And SMSC SCH5307-NS and SCH5317, which have different device IDs but are + otherwise compatible. -* * * * * +------------------------------------------------------------------------- -Methods for detecting the HP SIO and reading the thermal data on a dc7100. +Methods for detecting the HP SIO and reading the thermal data on a dc7100 +------------------------------------------------------------------------- The thermal information on the dc7100 is contained in the SIO Hardware Monitor (HWM). The information is accessed through an index/data pair. The index/data @@ -35,18 +44,22 @@ and 0x61 (LSB). Currently we are using 0x480 for the HWM Base Address and Reading temperature information. The temperature information is located in the following registers: + +=============== ======= ======================================================= Temp1 0x25 (Currently, this reflects the CPU temp on all systems). Temp2 0x26 Temp3 0x27 Temp4 0x80 +=============== ======= ======================================================= Programming Example -The following is an example of how to read the HWM temperature registers: -MOV DX,480H -MOV AX,25H -OUT DX,AL -MOV DX,481H -IN AL,DX +The following is an example of how to read the HWM temperature registers:: + + MOV DX,480H + MOV AX,25H + OUT DX,AL + MOV DX,481H + IN AL,DX AL contains the data in hex, the temperature in Celsius is the decimal equivalent. @@ -55,25 +68,32 @@ Ex: If AL contains 0x2A, the temperature is 42 degrees C. Reading tach information. The fan speed information is located in the following registers: + +=============== ======= ======= ================================= LSB MSB Tach1 0x28 0x29 (Currently, this reflects the CPU fan speed on all systems). Tach2 0x2A 0x2B Tach3 0x2C 0x2D Tach4 0x2E 0x2F +=============== ======= ======= ================================= -Important!!! -Reading the tach LSB locks the tach MSB. -The LSB Must be read first. +.. Important:: + + Reading the tach LSB locks the tach MSB. + The LSB Must be read first. + +How to convert the tach reading to RPM +-------------------------------------- -How to convert the tach reading to RPM. The tach reading (TCount) is given by: (Tach MSB * 256) + (Tach LSB) The SIO counts the number of 90kHz (11.111us) pulses per revolution. RPM = 60/(TCount * 11.111us) -Example: -Reg 0x28 = 0x9B -Reg 0x29 = 0x08 +Example:: + + Reg 0x28 = 0x9B + Reg 0x29 = 0x08 TCount = 0x89B = 2203 @@ -81,21 +101,28 @@ RPM = 60 / (2203 * 11.11111 E-6) = 2451 RPM Obtaining the SIO version. -CONFIGURATION SEQUENCE +Configuration Sequence +---------------------- + To program the configuration registers, the following sequence must be followed: 1. Enter Configuration Mode 2. Configure the Configuration Registers 3. Exit Configuration Mode. Enter Configuration Mode +^^^^^^^^^^^^^^^^^^^^^^^^ + To place the chip into the Configuration State The config key (0x55) is written to the CONFIG PORT (0x2E). Configuration Mode +^^^^^^^^^^^^^^^^^^ + In configuration mode, the INDEX PORT is located at the CONFIG PORT address and the DATA PORT is at INDEX PORT address + 1. The desired configuration registers are accessed in two steps: + a. Write the index of the Logical Device Number Configuration Register (i.e., 0x07) to the INDEX PORT and then write the number of the desired logical device to the DATA PORT. @@ -104,30 +131,35 @@ b. Write the address of the desired configuration register within the logical device to the INDEX PORT and then write or read the config- uration register through the DATA PORT. -Note: If accessing the Global Configuration Registers, step (a) is not required. +Note: + If accessing the Global Configuration Registers, step (a) is not required. Exit Configuration Mode +^^^^^^^^^^^^^^^^^^^^^^^ + To exit the Configuration State the write 0xAA to the CONFIG PORT (0x2E). The chip returns to the RUN State. (This is important). Programming Example -The following is an example of how to read the SIO Device ID located at 0x20 - -; ENTER CONFIGURATION MODE -MOV DX,02EH -MOV AX,055H -OUT DX,AL -; GLOBAL CONFIGURATION REGISTER -MOV DX,02EH -MOV AL,20H -OUT DX,AL -; READ THE DATA -MOV DX,02FH -IN AL,DX -; EXIT CONFIGURATION MODE -MOV DX,02EH -MOV AX,0AAH -OUT DX,AL +^^^^^^^^^^^^^^^^^^^ + +The following is an example of how to read the SIO Device ID located at 0x20: + + ; ENTER CONFIGURATION MODE + MOV DX,02EH + MOV AX,055H + OUT DX,AL + ; GLOBAL CONFIGURATION REGISTER + MOV DX,02EH + MOV AL,20H + OUT DX,AL + ; READ THE DATA + MOV DX,02FH + IN AL,DX + ; EXIT CONFIGURATION MODE + MOV DX,02EH + MOV AX,0AAH + OUT DX,AL The registers of interest for identifying the SIO on the dc7100 are Device ID (0x20) and Device Rev (0x21). @@ -135,29 +167,31 @@ The registers of interest for identifying the SIO on the dc7100 are Device ID The Device ID will read 0x6F (0x81 for SCH5307-NS, and 0x85 for SCH5317) The Device Rev currently reads 0x01 -Obtaining the HWM Base Address. +Obtaining the HWM Base Address +------------------------------ + The following is an example of how to read the HWM Base Address located in -Logical Device 8. - -; ENTER CONFIGURATION MODE -MOV DX,02EH -MOV AX,055H -OUT DX,AL -; CONFIGURE REGISTER CRE0, -; LOGICAL DEVICE 8 -MOV DX,02EH -MOV AL,07H -OUT DX,AL ;Point to LD# Config Reg -MOV DX,02FH -MOV AL, 08H -OUT DX,AL;Point to Logical Device 8 -; -MOV DX,02EH -MOV AL,60H -OUT DX,AL ; Point to HWM Base Addr MSB -MOV DX,02FH -IN AL,DX ; Get MSB of HWM Base Addr -; EXIT CONFIGURATION MODE -MOV DX,02EH -MOV AX,0AAH -OUT DX,AL +Logical Device 8:: + + ; ENTER CONFIGURATION MODE + MOV DX,02EH + MOV AX,055H + OUT DX,AL + ; CONFIGURE REGISTER CRE0, + ; LOGICAL DEVICE 8 + MOV DX,02EH + MOV AL,07H + OUT DX,AL ;Point to LD# Config Reg + MOV DX,02FH + MOV AL, 08H + OUT DX,AL;Point to Logical Device 8 + ; + MOV DX,02EH + MOV AL,60H + OUT DX,AL ; Point to HWM Base Addr MSB + MOV DX,02FH + IN AL,DX ; Get MSB of HWM Base Addr + ; EXIT CONFIGURATION MODE + MOV DX,02EH + MOV AX,0AAH + OUT DX,AL diff --git a/Documentation/hwmon/smsc47m1 b/Documentation/hwmon/smsc47m1.rst index 10a24b420686..c54eabd5eb57 100644 --- a/Documentation/hwmon/smsc47m1 +++ b/Documentation/hwmon/smsc47m1.rst @@ -2,30 +2,53 @@ Kernel driver smsc47m1 ====================== Supported chips: + * SMSC LPC47B27x, LPC47M112, LPC47M10x, LPC47M13x, LPC47M14x, + LPC47M15x and LPC47M192 + Addresses scanned: none, address read from Super I/O config space + Prefix: 'smsc47m1' + Datasheets: - http://www.smsc.com/media/Downloads_Public/Data_Sheets/47b272.pdf - http://www.smsc.com/media/Downloads_Public/Data_Sheets/47m10x.pdf - http://www.smsc.com/media/Downloads_Public/Data_Sheets/47m112.pdf - http://www.smsc.com/ + + http://www.smsc.com/media/Downloads_Public/Data_Sheets/47b272.pdf + + http://www.smsc.com/media/Downloads_Public/Data_Sheets/47m10x.pdf + + http://www.smsc.com/media/Downloads_Public/Data_Sheets/47m112.pdf + + http://www.smsc.com/ + * SMSC LPC47M292 + Addresses scanned: none, address read from Super I/O config space + Prefix: 'smsc47m2' + Datasheet: Not public + * SMSC LPC47M997 + Addresses scanned: none, address read from Super I/O config space + Prefix: 'smsc47m1' + Datasheet: none + + Authors: - Mark D. Studebaker <mdsxyz123@yahoo.com>, - With assistance from Bruce Allen <ballen@uwm.edu>, and his - fan.c program: http://www.lsc-group.phys.uwm.edu/%7Eballen/driver/ - Gabriele Gorla <gorlik@yahoo.com>, - Jean Delvare <jdelvare@suse.de> + + - Mark D. Studebaker <mdsxyz123@yahoo.com>, + - With assistance from Bruce Allen <ballen@uwm.edu>, and his + fan.c program: + + - http://www.lsc-group.phys.uwm.edu/%7Eballen/driver/ + + - Gabriele Gorla <gorlik@yahoo.com>, + - Jean Delvare <jdelvare@suse.de> Description ----------- @@ -57,7 +80,7 @@ hardware registers are read whenever any data is read (unless it is less than 1.5 seconds since the last update). This means that you can easily miss once-only alarms. +------------------------------------------------------------------ -********************** The lm_sensors project gratefully acknowledges the support of Intel in the development of this driver. diff --git a/Documentation/hwmon/smsc47m192 b/Documentation/hwmon/smsc47m192 deleted file mode 100644 index 6d54ecb7b3f8..000000000000 --- a/Documentation/hwmon/smsc47m192 +++ /dev/null @@ -1,103 +0,0 @@ -Kernel driver smsc47m192 -======================== - -Supported chips: - * SMSC LPC47M192, LPC47M15x, LPC47M292 and LPC47M997 - Prefix: 'smsc47m192' - Addresses scanned: I2C 0x2c - 0x2d - Datasheet: The datasheet for LPC47M192 is publicly available from - http://www.smsc.com/ - The LPC47M15x, LPC47M292 and LPC47M997 are compatible for - hardware monitoring. - -Author: Hartmut Rick <linux@rick.claranet.de> - Special thanks to Jean Delvare for careful checking - of the code and many helpful comments and suggestions. - - -Description ------------ - -This driver implements support for the hardware sensor capabilities -of the SMSC LPC47M192 and compatible Super-I/O chips. - -These chips support 3 temperature channels and 8 voltage inputs -as well as CPU voltage VID input. - -They do also have fan monitoring and control capabilities, but the -these features are accessed via ISA bus and are not supported by this -driver. Use the 'smsc47m1' driver for fan monitoring and control. - -Voltages and temperatures are measured by an 8-bit ADC, the resolution -of the temperatures is 1 bit per degree C. -Voltages are scaled such that the nominal voltage corresponds to -192 counts, i.e. 3/4 of the full range. Thus the available range for -each voltage channel is 0V ... 255/192*(nominal voltage), the resolution -is 1 bit per (nominal voltage)/192. -Both voltage and temperature values are scaled by 1000, the sys files -show voltages in mV and temperatures in units of 0.001 degC. - -The +12V analog voltage input channel (in4_input) is multiplexed with -bit 4 of the encoded CPU voltage. This means that you either get -a +12V voltage measurement or a 5 bit CPU VID, but not both. -The default setting is to use the pin as 12V input, and use only 4 bit VID. -This driver assumes that the information in the configuration register -is correct, i.e. that the BIOS has updated the configuration if -the motherboard has this input wired to VID4. - -The temperature and voltage readings are updated once every 1.5 seconds. -Reading them more often repeats the same values. - - -sysfs interface ---------------- - -in0_input - +2.5V voltage input -in1_input - CPU voltage input (nominal 2.25V) -in2_input - +3.3V voltage input -in3_input - +5V voltage input -in4_input - +12V voltage input (may be missing if used as VID4) -in5_input - Vcc voltage input (nominal 3.3V) - This is the supply voltage of the sensor chip itself. -in6_input - +1.5V voltage input -in7_input - +1.8V voltage input - -in[0-7]_min, -in[0-7]_max - lower and upper alarm thresholds for in[0-7]_input reading - - All voltages are read and written in mV. - -in[0-7]_alarm - alarm flags for voltage inputs - These files read '1' in case of alarm, '0' otherwise. - -temp1_input - chip temperature measured by on-chip diode -temp[2-3]_input - temperature measured by external diodes (one of these would - typically be wired to the diode inside the CPU) - -temp[1-3]_min, -temp[1-3]_max - lower and upper alarm thresholds for temperatures - -temp[1-3]_offset - temperature offset registers - The chip adds the offsets stored in these registers to - the corresponding temperature readings. - Note that temp1 and temp2 offsets share the same register, - they cannot both be different from zero at the same time. - Writing a non-zero number to one of them will reset the other - offset to zero. - - All temperatures and offsets are read and written in - units of 0.001 degC. - -temp[1-3]_alarm - alarm flags for temperature inputs, '1' in case of alarm, - '0' otherwise. -temp[2-3]_input_fault - diode fault flags for temperature inputs 2 and 3. - A fault is detected if the two pins for the corresponding - sensor are open or shorted, or any of the two is shorted - to ground or Vcc. '1' indicates a diode fault. - -cpu0_vid - CPU voltage as received from the CPU - -vrm - CPU VID standard used for decoding CPU voltage - - The *_min, *_max, *_offset and vrm files can be read and - written, all others are read-only. diff --git a/Documentation/hwmon/smsc47m192.rst b/Documentation/hwmon/smsc47m192.rst new file mode 100644 index 000000000000..a2e86ab67918 --- /dev/null +++ b/Documentation/hwmon/smsc47m192.rst @@ -0,0 +1,116 @@ +Kernel driver smsc47m192 +======================== + +Supported chips: + + * SMSC LPC47M192, LPC47M15x, LPC47M292 and LPC47M997 + + Prefix: 'smsc47m192' + + Addresses scanned: I2C 0x2c - 0x2d + + Datasheet: The datasheet for LPC47M192 is publicly available from + + http://www.smsc.com/ + + The LPC47M15x, LPC47M292 and LPC47M997 are compatible for + + hardware monitoring. + + + +Author: + - Hartmut Rick <linux@rick.claranet.de> + + - Special thanks to Jean Delvare for careful checking + of the code and many helpful comments and suggestions. + + +Description +----------- + +This driver implements support for the hardware sensor capabilities +of the SMSC LPC47M192 and compatible Super-I/O chips. + +These chips support 3 temperature channels and 8 voltage inputs +as well as CPU voltage VID input. + +They do also have fan monitoring and control capabilities, but the +these features are accessed via ISA bus and are not supported by this +driver. Use the 'smsc47m1' driver for fan monitoring and control. + +Voltages and temperatures are measured by an 8-bit ADC, the resolution +of the temperatures is 1 bit per degree C. +Voltages are scaled such that the nominal voltage corresponds to +192 counts, i.e. 3/4 of the full range. Thus the available range for +each voltage channel is 0V ... 255/192*(nominal voltage), the resolution +is 1 bit per (nominal voltage)/192. +Both voltage and temperature values are scaled by 1000, the sys files +show voltages in mV and temperatures in units of 0.001 degC. + +The +12V analog voltage input channel (in4_input) is multiplexed with +bit 4 of the encoded CPU voltage. This means that you either get +a +12V voltage measurement or a 5 bit CPU VID, but not both. +The default setting is to use the pin as 12V input, and use only 4 bit VID. +This driver assumes that the information in the configuration register +is correct, i.e. that the BIOS has updated the configuration if +the motherboard has this input wired to VID4. + +The temperature and voltage readings are updated once every 1.5 seconds. +Reading them more often repeats the same values. + + +sysfs interface +--------------- + +===================== ========================================================== +in0_input +2.5V voltage input +in1_input CPU voltage input (nominal 2.25V) +in2_input +3.3V voltage input +in3_input +5V voltage input +in4_input +12V voltage input (may be missing if used as VID4) +in5_input Vcc voltage input (nominal 3.3V) + This is the supply voltage of the sensor chip itself. +in6_input +1.5V voltage input +in7_input +1.8V voltage input + +in[0-7]_min, +in[0-7]_max lower and upper alarm thresholds for in[0-7]_input reading + + All voltages are read and written in mV. + +in[0-7]_alarm alarm flags for voltage inputs + These files read '1' in case of alarm, '0' otherwise. + +temp1_input chip temperature measured by on-chip diode +temp[2-3]_input temperature measured by external diodes (one of these + would typically be wired to the diode inside the CPU) + +temp[1-3]_min, +temp[1-3]_max lower and upper alarm thresholds for temperatures + +temp[1-3]_offset temperature offset registers + The chip adds the offsets stored in these registers to + the corresponding temperature readings. + Note that temp1 and temp2 offsets share the same register, + they cannot both be different from zero at the same time. + Writing a non-zero number to one of them will reset the other + offset to zero. + + All temperatures and offsets are read and written in + units of 0.001 degC. + +temp[1-3]_alarm alarm flags for temperature inputs, '1' in case of alarm, + '0' otherwise. +temp[2-3]_input_fault diode fault flags for temperature inputs 2 and 3. + A fault is detected if the two pins for the corresponding + sensor are open or shorted, or any of the two is shorted + to ground or Vcc. '1' indicates a diode fault. + +cpu0_vid CPU voltage as received from the CPU + +vrm CPU VID standard used for decoding CPU voltage +===================== ========================================================== + +The `*_min`, `*_max`, `*_offset` and `vrm` files can be read and written, +all others are read-only. diff --git a/Documentation/hwmon/submitting-patches b/Documentation/hwmon/submitting-patches.rst index f88221b46153..f9796b9d9db6 100644 --- a/Documentation/hwmon/submitting-patches +++ b/Documentation/hwmon/submitting-patches.rst @@ -1,5 +1,5 @@ - How to Get Your Patch Accepted Into the Hwmon Subsystem - ------------------------------------------------------- +How to Get Your Patch Accepted Into the Hwmon Subsystem +======================================================= This text is a collection of suggestions for people writing patches or drivers for the hwmon subsystem. Following these suggestions will greatly @@ -9,11 +9,12 @@ increase the chances of your change being accepted. 1. General ---------- -* It should be unnecessary to mention, but please read and follow - Documentation/process/submit-checklist.rst - Documentation/process/submitting-drivers.rst - Documentation/process/submitting-patches.rst - Documentation/process/coding-style.rst +* It should be unnecessary to mention, but please read and follow: + + - Documentation/process/submit-checklist.rst + - Documentation/process/submitting-drivers.rst + - Documentation/process/submitting-patches.rst + - Documentation/process/coding-style.rst * Please run your patch through 'checkpatch --strict'. There should be no errors, no warnings, and few if any check messages. If there are any @@ -38,7 +39,7 @@ increase the chances of your change being accepted. 2. Adding functionality to existing drivers ------------------------------------------- -* Make sure the documentation in Documentation/hwmon/<driver_name> is up to +* Make sure the documentation in Documentation/hwmon/<driver_name>.rst is up to date. * Make sure the information in Kconfig is up to date. @@ -60,7 +61,7 @@ increase the chances of your change being accepted. * Consider adding yourself to MAINTAINERS. -* Document the driver in Documentation/hwmon/<driver_name>. +* Document the driver in Documentation/hwmon/<driver_name>.rst. * Add the driver to Kconfig and Makefile in alphabetical order. @@ -133,7 +134,7 @@ increase the chances of your change being accepted. non-standard attributes, or you believe you do, discuss it on the mailing list first. Either case, provide a detailed explanation why you need the non-standard attribute(s). - Standard attributes are specified in Documentation/hwmon/sysfs-interface. + Standard attributes are specified in Documentation/hwmon/sysfs-interface.rst. * When deciding which sysfs attributes to support, look at the chip's capabilities. While we do not expect your driver to support everything the diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface.rst index 2b9e1005d88b..fd590633bb14 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface.rst @@ -1,5 +1,5 @@ Naming and data format standards for sysfs files ------------------------------------------------- +================================================ The libsensors library offers an interface to the raw sensors data through the sysfs interface. Since lm-sensors 3.0.0, libsensors is @@ -32,7 +32,7 @@ this reason, it is still not recommended to bypass the library. Each chip gets its own directory in the sysfs /sys/devices tree. To find all sensor chips, it is easier to follow the device symlinks from -/sys/class/hwmon/hwmon*. +`/sys/class/hwmon/hwmon*`. Up to lm-sensors 3.0.0, libsensors looks for hardware monitoring attributes in the "physical" device directory. Since lm-sensors 3.0.1, attributes found @@ -67,11 +67,13 @@ are interpreted as 0! For more on how written strings are interpreted see the ------------------------------------------------------------------------- -[0-*] denotes any positive number starting from 0 -[1-*] denotes any positive number starting from 1 +======= =========================================== +`[0-*]` denotes any positive number starting from 0 +`[1-*]` denotes any positive number starting from 1 RO read only value WO write only value RW read/write value +======= =========================================== Read/write values may be read-only for some chips, depending on the hardware implementation. @@ -80,57 +82,82 @@ All entries (except name) are optional, and should only be created in a given driver if the chip has the feature. -********************* -* Global attributes * -********************* +***************** +Global attributes +***************** -name The chip name. +`name` + The chip name. This should be a short, lowercase string, not containing whitespace, dashes, or the wildcard character '*'. This attribute represents the chip name. It is the only mandatory attribute. I2C devices get this attribute created automatically. + RO -update_interval The interval at which the chip will update readings. +`update_interval` + The interval at which the chip will update readings. Unit: millisecond + RW + Some devices have a variable update rate or interval. This attribute can be used to change it to the desired value. -************ -* Voltages * -************ +******** +Voltages +******** + +`in[0-*]_min` + Voltage min value. -in[0-*]_min Voltage min value. Unit: millivolt + RW - -in[0-*]_lcrit Voltage critical min value. + +`in[0-*]_lcrit` + Voltage critical min value. + Unit: millivolt + RW + If voltage drops to or below this limit, the system may take drastic action such as power down or reset. At the very least, it should report a fault. -in[0-*]_max Voltage max value. +`in[0-*]_max` + Voltage max value. + Unit: millivolt + RW - -in[0-*]_crit Voltage critical max value. + +`in[0-*]_crit` + Voltage critical max value. + Unit: millivolt + RW + If voltage reaches or exceeds this limit, the system may take drastic action such as power down or reset. At the very least, it should report a fault. -in[0-*]_input Voltage input value. +`in[0-*]_input` + Voltage input value. + Unit: millivolt + RO + Voltage measured on the chip pin. + Actual voltage depends on the scaling resistors on the motherboard, as recommended in the chip datasheet. + This varies by chip and by motherboard. Because of this variation, values are generally NOT scaled by the chip driver, and must be done by the application. @@ -140,166 +167,232 @@ in[0-*]_input Voltage input value. thumb: drivers should report the voltage values at the "pins" of the chip. -in[0-*]_average +`in[0-*]_average` Average voltage + Unit: millivolt + RO -in[0-*]_lowest +`in[0-*]_lowest` Historical minimum voltage + Unit: millivolt + RO -in[0-*]_highest +`in[0-*]_highest` Historical maximum voltage + Unit: millivolt + RO -in[0-*]_reset_history +`in[0-*]_reset_history` Reset inX_lowest and inX_highest + WO -in_reset_history +`in_reset_history` Reset inX_lowest and inX_highest for all sensors + WO -in[0-*]_label Suggested voltage channel label. +`in[0-*]_label` + Suggested voltage channel label. + Text string + Should only be created if the driver has hints about what this voltage channel is being used for, and user-space doesn't. In all other cases, the label is provided by user-space. + RO -in[0-*]_enable +`in[0-*]_enable` Enable or disable the sensors. + When disabled the sensor read will return -ENODATA. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable + RW -cpu[0-*]_vid CPU core reference voltage. +`cpu[0-*]_vid` + CPU core reference voltage. + Unit: millivolt + RO + Not always correct. -vrm Voltage Regulator Module version number. +`vrm` + Voltage Regulator Module version number. + RW (but changing it should no more be necessary) + Originally the VRM standard version multiplied by 10, but now an arbitrary number, as not all standards have a version number. + Affects the way the driver calculates the CPU core reference voltage from the vid pins. Also see the Alarms section for status flags associated with voltages. -******** -* Fans * -******** +**** +Fans +**** + +`fan[1-*]_min` + Fan minimum value -fan[1-*]_min Fan minimum value Unit: revolution/min (RPM) + RW -fan[1-*]_max Fan maximum value +`fan[1-*]_max` + Fan maximum value + Unit: revolution/min (RPM) + Only rarely supported by the hardware. RW -fan[1-*]_input Fan input value. +`fan[1-*]_input` + Fan input value. + Unit: revolution/min (RPM) + RO -fan[1-*]_div Fan divisor. +`fan[1-*]_div` + Fan divisor. + Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128). + RW + Some chips only support values 1, 2, 4 and 8. Note that this is actually an internal clock divisor, which affects the measurable speed range, not the read value. -fan[1-*]_pulses Number of tachometer pulses per fan revolution. +`fan[1-*]_pulses` + Number of tachometer pulses per fan revolution. + Integer value, typically between 1 and 4. + RW + This value is a characteristic of the fan connected to the device's input, so it has to be set in accordance with the fan model. + Should only be created if the chip has a register to configure the number of pulses. In the absence of such a register (and thus attribute) the value assumed by all devices is 2 pulses per fan revolution. -fan[1-*]_target +`fan[1-*]_target` Desired fan speed + Unit: revolution/min (RPM) + RW + Only makes sense if the chip supports closed-loop fan speed control based on the measured fan speed. -fan[1-*]_label Suggested fan channel label. +`fan[1-*]_label` + Suggested fan channel label. + Text string + Should only be created if the driver has hints about what this fan channel is being used for, and user-space doesn't. In all other cases, the label is provided by user-space. + RO -fan[1-*]_enable +`fan[1-*]_enable` Enable or disable the sensors. + When disabled the sensor read will return -ENODATA. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable + RW Also see the Alarms section for status flags associated with fans. -******* -* PWM * -******* +*** +PWM +*** + +`pwm[1-*]` + Pulse width modulation fan control. -pwm[1-*] Pulse width modulation fan control. Integer value in the range 0 to 255 + RW + 255 is max or 100%. -pwm[1-*]_enable +`pwm[1-*]_enable` Fan speed control method: - 0: no fan speed control (i.e. fan at full speed) - 1: manual fan speed control enabled (using pwm[1-*]) - 2+: automatic fan speed control enabled + + - 0: no fan speed control (i.e. fan at full speed) + - 1: manual fan speed control enabled (using `pwm[1-*]`) + - 2+: automatic fan speed control enabled + Check individual chip documentation files for automatic mode details. + RW -pwm[1-*]_mode 0: DC mode (direct current) - 1: PWM mode (pulse-width modulation) +`pwm[1-*]_mode` + - 0: DC mode (direct current) + - 1: PWM mode (pulse-width modulation) + RW -pwm[1-*]_freq Base PWM frequency in Hz. +`pwm[1-*]_freq` + Base PWM frequency in Hz. + Only possibly available when pwmN_mode is PWM, but not always present even then. + RW -pwm[1-*]_auto_channels_temp +`pwm[1-*]_auto_channels_temp` Select which temperature channels affect this PWM output in - auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc... + auto mode. + + Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc... Which values are possible depend on the chip used. + RW -pwm[1-*]_auto_point[1-*]_pwm -pwm[1-*]_auto_point[1-*]_temp -pwm[1-*]_auto_point[1-*]_temp_hyst - Define the PWM vs temperature curve. Number of trip points is - chip-dependent. Use this for chips which associate trip points - to PWM output channels. +`pwm[1-*]_auto_point[1-*]_pwm` / `pwm[1-*]_auto_point[1-*]_temp` / `pwm[1-*]_auto_point[1-*]_temp_hyst` + Define the PWM vs temperature curve. + + Number of trip points is chip-dependent. Use this for chips + which associate trip points to PWM output channels. + RW -temp[1-*]_auto_point[1-*]_pwm -temp[1-*]_auto_point[1-*]_temp -temp[1-*]_auto_point[1-*]_temp_hyst - Define the PWM vs temperature curve. Number of trip points is - chip-dependent. Use this for chips which associate trip points - to temperature channels. +`temp[1-*]_auto_point[1-*]_pwm` / `temp[1-*]_auto_point[1-*]_temp` / `temp[1-*]_auto_point[1-*]_temp_hyst` + Define the PWM vs temperature curve. + + Number of trip points is chip-dependent. Use this for chips + which associate trip points to temperature channels. + RW There is a third case where trip points are associated to both PWM output @@ -312,122 +405,173 @@ The actual result is up to the chip, but in general the highest candidate value (fastest fan speed) wins. -**************** -* Temperatures * -**************** +************ +Temperatures +************ + +`temp[1-*]_type` + Sensor type selection. -temp[1-*]_type Sensor type selection. Integers 1 to 6 + RW - 1: CPU embedded diode - 2: 3904 transistor - 3: thermal diode - 4: thermistor - 5: AMD AMDSI - 6: Intel PECI + + - 1: CPU embedded diode + - 2: 3904 transistor + - 3: thermal diode + - 4: thermistor + - 5: AMD AMDSI + - 6: Intel PECI + Not all types are supported by all chips -temp[1-*]_max Temperature max value. +`temp[1-*]_max` + Temperature max value. + Unit: millidegree Celsius (or millivolt, see below) + RW -temp[1-*]_min Temperature min value. +`temp[1-*]_min` + Temperature min value. + Unit: millidegree Celsius + RW -temp[1-*]_max_hyst +`temp[1-*]_max_hyst` Temperature hysteresis value for max limit. + Unit: millidegree Celsius + Must be reported as an absolute temperature, NOT a delta from the max value. + RW -temp[1-*]_min_hyst +`temp[1-*]_min_hyst` Temperature hysteresis value for min limit. Unit: millidegree Celsius + Must be reported as an absolute temperature, NOT a delta from the min value. + RW -temp[1-*]_input Temperature input value. +`temp[1-*]_input` + Temperature input value. + Unit: millidegree Celsius + RO -temp[1-*]_crit Temperature critical max value, typically greater than +`temp[1-*]_crit` + Temperature critical max value, typically greater than corresponding temp_max values. + Unit: millidegree Celsius + RW -temp[1-*]_crit_hyst +`temp[1-*]_crit_hyst` Temperature hysteresis value for critical limit. + Unit: millidegree Celsius + Must be reported as an absolute temperature, NOT a delta from the critical value. + RW -temp[1-*]_emergency +`temp[1-*]_emergency` Temperature emergency max value, for chips supporting more than two upper temperature limits. Must be equal or greater than corresponding temp_crit values. + Unit: millidegree Celsius + RW -temp[1-*]_emergency_hyst +`temp[1-*]_emergency_hyst` Temperature hysteresis value for emergency limit. + Unit: millidegree Celsius + Must be reported as an absolute temperature, NOT a delta from the emergency value. + RW -temp[1-*]_lcrit Temperature critical min value, typically lower than +`temp[1-*]_lcrit` + Temperature critical min value, typically lower than corresponding temp_min values. + Unit: millidegree Celsius + RW -temp[1-*]_lcrit_hyst +`temp[1-*]_lcrit_hyst` Temperature hysteresis value for critical min limit. + Unit: millidegree Celsius + Must be reported as an absolute temperature, NOT a delta from the critical min value. + RW -temp[1-*]_offset +`temp[1-*]_offset` Temperature offset which is added to the temperature reading by the chip. + Unit: millidegree Celsius + Read/Write value. -temp[1-*]_label Suggested temperature channel label. +`temp[1-*]_label` + Suggested temperature channel label. + Text string + Should only be created if the driver has hints about what this temperature channel is being used for, and user-space doesn't. In all other cases, the label is provided by user-space. + RO -temp[1-*]_lowest +`temp[1-*]_lowest` Historical minimum temperature + Unit: millidegree Celsius + RO -temp[1-*]_highest +`temp[1-*]_highest` Historical maximum temperature + Unit: millidegree Celsius + RO -temp[1-*]_reset_history +`temp[1-*]_reset_history` Reset temp_lowest and temp_highest + WO -temp_reset_history +`temp_reset_history` Reset temp_lowest and temp_highest for all sensors + WO -temp[1-*]_enable +`temp[1-*]_enable` Enable or disable the sensors. + When disabled the sensor read will return -ENODATA. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable + RW Some chips measure temperature using external thermistors and an ADC, and @@ -442,201 +586,300 @@ channels by the driver. Also see the Alarms section for status flags associated with temperatures. -************ -* Currents * -************ +******** +Currents +******** + +`curr[1-*]_max` + Current max value -curr[1-*]_max Current max value Unit: milliampere + RW -curr[1-*]_min Current min value. +`curr[1-*]_min` + Current min value. + Unit: milliampere + RW -curr[1-*]_lcrit Current critical low value +`curr[1-*]_lcrit` + Current critical low value + Unit: milliampere + RW -curr[1-*]_crit Current critical high value. +`curr[1-*]_crit` + Current critical high value. + Unit: milliampere + RW -curr[1-*]_input Current input value +`curr[1-*]_input` + Current input value + Unit: milliampere + RO -curr[1-*]_average +`curr[1-*]_average` Average current use + Unit: milliampere + RO -curr[1-*]_lowest +`curr[1-*]_lowest` Historical minimum current + Unit: milliampere + RO -curr[1-*]_highest +`curr[1-*]_highest` Historical maximum current Unit: milliampere RO -curr[1-*]_reset_history +`curr[1-*]_reset_history` Reset currX_lowest and currX_highest + WO -curr_reset_history +`curr_reset_history` Reset currX_lowest and currX_highest for all sensors + WO -curr[1-*]_enable +`curr[1-*]_enable` Enable or disable the sensors. + When disabled the sensor read will return -ENODATA. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable + RW Also see the Alarms section for status flags associated with currents. -********* -* Power * -********* +***** +Power +***** + +`power[1-*]_average` + Average power use -power[1-*]_average Average power use Unit: microWatt + RO -power[1-*]_average_interval Power use averaging interval. A poll +`power[1-*]_average_interval` + Power use averaging interval. A poll notification is sent to this file if the hardware changes the averaging interval. + Unit: milliseconds + RW -power[1-*]_average_interval_max Maximum power use averaging interval +`power[1-*]_average_interval_max` + Maximum power use averaging interval + Unit: milliseconds + RO -power[1-*]_average_interval_min Minimum power use averaging interval +`power[1-*]_average_interval_min` + Minimum power use averaging interval + Unit: milliseconds + RO -power[1-*]_average_highest Historical average maximum power use +`power[1-*]_average_highest` + Historical average maximum power use + Unit: microWatt + RO -power[1-*]_average_lowest Historical average minimum power use +`power[1-*]_average_lowest` + Historical average minimum power use + Unit: microWatt + RO -power[1-*]_average_max A poll notification is sent to - power[1-*]_average when power use +`power[1-*]_average_max` + A poll notification is sent to + `power[1-*]_average` when power use rises above this value. + Unit: microWatt + RW -power[1-*]_average_min A poll notification is sent to - power[1-*]_average when power use +`power[1-*]_average_min` + A poll notification is sent to + `power[1-*]_average` when power use sinks below this value. + Unit: microWatt + RW -power[1-*]_input Instantaneous power use +`power[1-*]_input` + Instantaneous power use + Unit: microWatt + RO -power[1-*]_input_highest Historical maximum power use +`power[1-*]_input_highest` + Historical maximum power use + Unit: microWatt + RO -power[1-*]_input_lowest Historical minimum power use +`power[1-*]_input_lowest` + Historical minimum power use + Unit: microWatt + RO -power[1-*]_reset_history Reset input_highest, input_lowest, +`power[1-*]_reset_history` + Reset input_highest, input_lowest, average_highest and average_lowest. + WO -power[1-*]_accuracy Accuracy of the power meter. +`power[1-*]_accuracy` + Accuracy of the power meter. + Unit: Percent + RO -power[1-*]_cap If power use rises above this limit, the +`power[1-*]_cap` + If power use rises above this limit, the system should take action to reduce power use. A poll notification is sent to this file if the - cap is changed by the hardware. The *_cap + cap is changed by the hardware. The `*_cap` files only appear if the cap is known to be enforced by hardware. + Unit: microWatt + RW -power[1-*]_cap_hyst Margin of hysteresis built around capping and +`power[1-*]_cap_hyst` + Margin of hysteresis built around capping and notification. + Unit: microWatt + RW -power[1-*]_cap_max Maximum cap that can be set. +`power[1-*]_cap_max` + Maximum cap that can be set. + Unit: microWatt + RO -power[1-*]_cap_min Minimum cap that can be set. +`power[1-*]_cap_min` + Minimum cap that can be set. + Unit: microWatt + RO -power[1-*]_max Maximum power. +`power[1-*]_max` + Maximum power. + Unit: microWatt + RW -power[1-*]_crit Critical maximum power. +`power[1-*]_crit` + Critical maximum power. + If power rises to or above this limit, the system is expected take drastic action to reduce power consumption, such as a system shutdown or a forced powerdown of some devices. + Unit: microWatt + RW -power[1-*]_enable Enable or disable the sensors. +`power[1-*]_enable` + Enable or disable the sensors. + When disabled the sensor read will return -ENODATA. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable + RW Also see the Alarms section for status flags associated with power readings. -********** -* Energy * -********** +****** +Energy +****** + +`energy[1-*]_input` + Cumulative energy use -energy[1-*]_input Cumulative energy use Unit: microJoule + RO -energy[1-*]_enable Enable or disable the sensors. +`energy[1-*]_enable` + Enable or disable the sensors. + When disabled the sensor read will return -ENODATA. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable + RW -************ -* Humidity * -************ +******** +Humidity +******** + +`humidity[1-*]_input` + Humidity -humidity[1-*]_input Humidity Unit: milli-percent (per cent mille, pcm) + RO -humidity[1-*]_enable Enable or disable the sensors +`humidity[1-*]_enable` + Enable or disable the sensors + When disabled the sensor read will return -ENODATA. - 1: Enable - 0: Disable + + - 1: Enable + - 0: Disable + RW -********** -* Alarms * -********** +****** +Alarms +****** Each channel or limit may have an associated alarm file, containing a boolean value. 1 means than an alarm condition exists, 0 means no alarm. @@ -645,67 +888,67 @@ Usually a given chip will either use channel-related alarms, or limit-related alarms, not both. The driver should just reflect the hardware implementation. -in[0-*]_alarm -curr[1-*]_alarm -power[1-*]_alarm -fan[1-*]_alarm -temp[1-*]_alarm - Channel alarm - 0: no alarm - 1: alarm - RO - -OR - -in[0-*]_min_alarm -in[0-*]_max_alarm -in[0-*]_lcrit_alarm -in[0-*]_crit_alarm -curr[1-*]_min_alarm -curr[1-*]_max_alarm -curr[1-*]_lcrit_alarm -curr[1-*]_crit_alarm -power[1-*]_cap_alarm -power[1-*]_max_alarm -power[1-*]_crit_alarm -fan[1-*]_min_alarm -fan[1-*]_max_alarm -temp[1-*]_min_alarm -temp[1-*]_max_alarm -temp[1-*]_lcrit_alarm -temp[1-*]_crit_alarm -temp[1-*]_emergency_alarm - Limit alarm - 0: no alarm - 1: alarm - RO ++-------------------------------+-----------------------+ +| **`in[0-*]_alarm`, | Channel alarm | +| `curr[1-*]_alarm`, | | +| `power[1-*]_alarm`, | - 0: no alarm | +| `fan[1-*]_alarm`, | - 1: alarm | +| `temp[1-*]_alarm`** | | +| | RO | ++-------------------------------+-----------------------+ + +**OR** + ++-------------------------------+-----------------------+ +| **`in[0-*]_min_alarm`, | Limit alarm | +| `in[0-*]_max_alarm`, | | +| `in[0-*]_lcrit_alarm`, | - 0: no alarm | +| `in[0-*]_crit_alarm`, | - 1: alarm | +| `curr[1-*]_min_alarm`, | | +| `curr[1-*]_max_alarm`, | RO | +| `curr[1-*]_lcrit_alarm`, | | +| `curr[1-*]_crit_alarm`, | | +| `power[1-*]_cap_alarm`, | | +| `power[1-*]_max_alarm`, | | +| `power[1-*]_crit_alarm`, | | +| `fan[1-*]_min_alarm`, | | +| `fan[1-*]_max_alarm`, | | +| `temp[1-*]_min_alarm`, | | +| `temp[1-*]_max_alarm`, | | +| `temp[1-*]_lcrit_alarm`, | | +| `temp[1-*]_crit_alarm`, | | +| `temp[1-*]_emergency_alarm`** | | ++-------------------------------+-----------------------+ Each input channel may have an associated fault file. This can be used to notify open diodes, unconnected fans etc. where the hardware supports it. When this boolean has value 1, the measurement for that channel should not be trusted. -fan[1-*]_fault -temp[1-*]_fault +`fan[1-*]_fault` / `temp[1-*]_fault` Input fault condition - 0: no fault occurred - 1: fault condition + + - 0: no fault occurred + - 1: fault condition + RO Some chips also offer the possibility to get beeped when an alarm occurs: -beep_enable Master beep enable - 0: no beeps - 1: beeps +`beep_enable` + Master beep enable + + - 0: no beeps + - 1: beeps + RW -in[0-*]_beep -curr[1-*]_beep -fan[1-*]_beep -temp[1-*]_beep +`in[0-*]_beep`, `curr[1-*]_beep`, `fan[1-*]_beep`, `temp[1-*]_beep`, Channel beep - 0: disable - 1: enable + + - 0: disable + - 1: enable + RW In theory, a chip could provide per-limit beep masking, but no such chip @@ -715,56 +958,90 @@ Old drivers provided a different, non-standard interface to alarms and beeps. These interface files are deprecated, but will be kept around for compatibility reasons: -alarms Alarm bitmask. +`alarms` + Alarm bitmask. + RO + Integer representation of one to four bytes. + A '1' bit means an alarm. + Chips should be programmed for 'comparator' mode so that the alarm will 'come back' after you read the register if it is still valid. + Generally a direct representation of a chip's internal alarm registers; there is no standard for the position of individual bits. For this reason, the use of this interface file for new drivers is discouraged. Use - individual *_alarm and *_fault files instead. + `individual *_alarm` and `*_fault` files instead. Bits are defined in kernel/include/sensors.h. -beep_mask Bitmask for beep. +`beep_mask` + Bitmask for beep. Same format as 'alarms' with the same bit locations, use discouraged for the same reason. Use individual - *_beep files instead. + `*_beep` files instead. RW -*********************** -* Intrusion detection * -*********************** +******************* +Intrusion detection +******************* -intrusion[0-*]_alarm +`intrusion[0-*]_alarm` Chassis intrusion detection - 0: OK - 1: intrusion detected + + - 0: OK + - 1: intrusion detected + RW + Contrary to regular alarm flags which clear themselves automatically when read, this one sticks until cleared by the user. This is done by writing 0 to the file. Writing other values is unsupported. -intrusion[0-*]_beep +`intrusion[0-*]_beep` Chassis intrusion beep + 0: disable 1: enable + RW +**************************** +Average sample configuration +**************************** + +Devices allowing for reading {in,power,curr,temp}_average values may export +attributes for controlling number of samples used to compute average. + ++--------------+---------------------------------------------------------------+ +| samples | Sets number of average samples for all types of measurements. | +| | | +| | RW | ++--------------+---------------------------------------------------------------+ +| in_samples | Sets number of average samples for specific type of | +| power_samples| measurements. | +| curr_samples | | +| temp_samples | Note that on some devices it won't be possible to set all of | +| | them to different values so changing one might also change | +| | some others. | +| | | +| | RW | ++--------------+---------------------------------------------------------------+ sysfs attribute writes interpretation ------------------------------------- hwmon sysfs attributes always contain numbers, so the first thing to do is to convert the input to a number, there are 2 ways todo this depending whether -the number can be negative or not: -unsigned long u = simple_strtoul(buf, NULL, 10); -long s = simple_strtol(buf, NULL, 10); +the number can be negative or not:: + + unsigned long u = simple_strtoul(buf, NULL, 10); + long s = simple_strtol(buf, NULL, 10); With buf being the buffer with the user input being passed by the kernel. Notice that we do not use the second argument of strto[u]l, and thus cannot @@ -789,13 +1066,13 @@ limits using clamp_val(value, min_limit, max_limit). If it is not continuous like for example a tempX_type, then when an invalid value is written, -EINVAL should be returned. -Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees): +Example1, temp1_max, register is a signed 8 bit value (-128 - 127 degrees):: long v = simple_strtol(buf, NULL, 10) / 1000; v = clamp_val(v, -128, 127); /* write v to register */ -Example2, fan divider setting, valid values 2, 4 and 8: +Example2, fan divider setting, valid values 2, 4 and 8:: unsigned long v = simple_strtoul(buf, NULL, 10); diff --git a/Documentation/hwmon/tc654 b/Documentation/hwmon/tc654.rst index 47636a8077b4..ce546ee6dfed 100644 --- a/Documentation/hwmon/tc654 +++ b/Documentation/hwmon/tc654.rst @@ -2,13 +2,16 @@ Kernel driver tc654 =================== Supported chips: + * Microchip TC654 and TC655 + Prefix: 'tc654' - Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/20001734C.pdf + Datasheet: http://ww1.m + icrochip.com/downloads/en/DeviceDoc/20001734C.pdf Authors: - Chris Packham <chris.packham@alliedtelesis.co.nz> - Masahiko Iwamoto <iwamoto@allied-telesis.co.jp> + - Chris Packham <chris.packham@alliedtelesis.co.nz> + - Masahiko Iwamoto <iwamoto@allied-telesis.co.jp> Description ----------- diff --git a/Documentation/hwmon/tc74 b/Documentation/hwmon/tc74.rst index 43027aad5f8e..f1764211c129 100644 --- a/Documentation/hwmon/tc74 +++ b/Documentation/hwmon/tc74.rst @@ -2,8 +2,11 @@ Kernel driver tc74 ==================== Supported chips: + * Microchip TC74 + Prefix: 'tc74' + Datasheet: Publicly available at Microchip website. Description diff --git a/Documentation/hwmon/thmc50 b/Documentation/hwmon/thmc50.rst index 8a7772ade8d0..cfff3885287d 100644 --- a/Documentation/hwmon/thmc50 +++ b/Documentation/hwmon/thmc50.rst @@ -2,30 +2,41 @@ Kernel driver thmc50 ===================== Supported chips: + * Analog Devices ADM1022 + Prefix: 'adm1022' + Addresses scanned: I2C 0x2c - 0x2e + Datasheet: http://www.analog.com/en/prod/0,2877,ADM1022,00.html + * Texas Instruments THMC50 + Prefix: 'thmc50' + Addresses scanned: I2C 0x2c - 0x2e - Datasheet: http://www.ti.com/ + + Datasheet: http://www.ti.com/ + Author: Krzysztof Helt <krzysztof.h1@wp.pl> This driver was derived from the 2.4 kernel thmc50.c source file. Credits: + thmc50.c (2.4 kernel): - Frodo Looijaard <frodol@dds.nl> - Philip Edelbrock <phil@netroedge.com> + + - Frodo Looijaard <frodol@dds.nl> + - Philip Edelbrock <phil@netroedge.com> Module Parameters ----------------- * adm1022_temp3: short array - List of adapter,address pairs to force chips into ADM1022 mode with - second remote temperature. This does not work for original THMC50 chips. + List of adapter,address pairs to force chips into ADM1022 mode with + second remote temperature. This does not work for original THMC50 chips. Description ----------- @@ -59,16 +70,20 @@ Driver Features The driver provides up to three temperatures: -temp1 -- internal -temp2 -- remote -temp3 -- 2nd remote only for ADM1022 +temp1 + - internal +temp2 + - remote +temp3 + - 2nd remote only for ADM1022 -pwm1 -- fan speed (0 = stop, 255 = full) -pwm1_mode -- always 0 (DC mode) +pwm1 + - fan speed (0 = stop, 255 = full) +pwm1_mode + - always 0 (DC mode) The value of 0 for pwm1 also forces FAN_OFF signal from the chip, so it stops fans even if the value 0 into the ANALOG_OUT register does not. The driver was tested on Compaq AP550 with two ADM1022 chips (one works in the temp3 mode), five temperature readings and two fans. - diff --git a/Documentation/hwmon/tmp102 b/Documentation/hwmon/tmp102.rst index 8454a7763122..b1f585531a88 100644 --- a/Documentation/hwmon/tmp102 +++ b/Documentation/hwmon/tmp102.rst @@ -2,12 +2,17 @@ Kernel driver tmp102 ==================== Supported chips: + * Texas Instruments TMP102 + Prefix: 'tmp102' + Addresses scanned: none + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp102.html Author: + Steven King <sfking@fdwdc.com> Description @@ -23,4 +28,4 @@ The TMP102 has a programmable update rate that can select between 8, 4, 1, and 0.5 Hz. (Currently the driver only supports the default of 4 Hz). The driver provides the common sysfs-interface for temperatures (see -Documentation/hwmon/sysfs-interface under Temperatures). +Documentation/hwmon/sysfs-interface.rst under Temperatures). diff --git a/Documentation/hwmon/tmp103 b/Documentation/hwmon/tmp103.rst index ec00a15645ba..15d25806d585 100644 --- a/Documentation/hwmon/tmp103 +++ b/Documentation/hwmon/tmp103.rst @@ -2,12 +2,17 @@ Kernel driver tmp103 ==================== Supported chips: + * Texas Instruments TMP103 + Prefix: 'tmp103' + Addresses scanned: none + Product info and datasheet: http://www.ti.com/product/tmp103 Author: + Heiko Schocher <hs@denx.de> Description @@ -22,7 +27,7 @@ Resolution: 8 Bits Accuracy: ±1°C Typ (–10°C to +100°C) The driver provides the common sysfs-interface for temperatures (see -Documentation/hwmon/sysfs-interface under Temperatures). +Documentation/hwmon/sysfs-interface.rst under Temperatures). Please refer how to instantiate this driver: Documentation/i2c/instantiating-devices diff --git a/Documentation/hwmon/tmp108 b/Documentation/hwmon/tmp108.rst index 25802df23010..5f4266a16cb2 100644 --- a/Documentation/hwmon/tmp108 +++ b/Documentation/hwmon/tmp108.rst @@ -2,12 +2,17 @@ Kernel driver tmp108 ==================== Supported chips: + * Texas Instruments TMP108 + Prefix: 'tmp108' + Addresses scanned: none + Datasheet: http://www.ti.com/product/tmp108 Author: + John Muir <john@jmuir.com> Description @@ -33,4 +38,4 @@ and then the device is shut down automatically. (This driver only supports continuous mode.) The driver provides the common sysfs-interface for temperatures (see -Documentation/hwmon/sysfs-interface under Temperatures). +Documentation/hwmon/sysfs-interface.rst under Temperatures). diff --git a/Documentation/hwmon/tmp401 b/Documentation/hwmon/tmp401.rst index 2d9ca42213cf..6a05a0719bc7 100644 --- a/Documentation/hwmon/tmp401 +++ b/Documentation/hwmon/tmp401.rst @@ -2,33 +2,59 @@ Kernel driver tmp401 ==================== Supported chips: + * Texas Instruments TMP401 + Prefix: 'tmp401' + Addresses scanned: I2C 0x4c + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp401.html + * Texas Instruments TMP411 + Prefix: 'tmp411' + Addresses scanned: I2C 0x4c, 0x4d, 0x4e + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp411.html + * Texas Instruments TMP431 + Prefix: 'tmp431' + Addresses scanned: I2C 0x4c, 0x4d + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp431.html + * Texas Instruments TMP432 + Prefix: 'tmp432' + Addresses scanned: I2C 0x4c, 0x4d + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp432.html + * Texas Instruments TMP435 + Prefix: 'tmp435' + Addresses scanned: I2C 0x48 - 0x4f + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp435.html + * Texas Instruments TMP461 + Prefix: 'tmp461' + Datasheet: http://www.ti.com/product/tmp461 + + Authors: - Hans de Goede <hdegoede@redhat.com> - Andre Prendel <andre.prendel@gmx.de> + + - Hans de Goede <hdegoede@redhat.com> + - Andre Prendel <andre.prendel@gmx.de> Description ----------- @@ -42,7 +68,7 @@ supported by the driver so far, so using the default resolution of 0.5 degree). The driver provides the common sysfs-interface for temperatures (see -Documentation/hwmon/sysfs-interface under Temperatures). +Documentation/hwmon/sysfs-interface.rst under Temperatures). The TMP411 and TMP431 chips are compatible with TMP401. TMP411 provides some additional features. diff --git a/Documentation/hwmon/tmp421 b/Documentation/hwmon/tmp421.rst index 9e6fe5549ca1..1ba926a3605c 100644 --- a/Documentation/hwmon/tmp421 +++ b/Documentation/hwmon/tmp421.rst @@ -2,28 +2,49 @@ Kernel driver tmp421 ==================== Supported chips: + * Texas Instruments TMP421 + Prefix: 'tmp421' + Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html + * Texas Instruments TMP422 + Prefix: 'tmp422' + Addresses scanned: I2C 0x4c, 0x4d, 0x4e and 0x4f + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html + * Texas Instruments TMP423 + Prefix: 'tmp423' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: http://focus.ti.com/docs/prod/folders/print/tmp421.html + * Texas Instruments TMP441 + Prefix: 'tmp441' + Addresses scanned: I2C 0x2a, 0x4c, 0x4d, 0x4e and 0x4f + Datasheet: http://www.ti.com/product/tmp441 + * Texas Instruments TMP442 + Prefix: 'tmp442' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: http://www.ti.com/product/tmp442 Authors: + Andre Prendel <andre.prendel@gmx.de> Description @@ -40,5 +61,6 @@ for both the local and remote channels is 0.0625 degree C. The chips support only temperature measurement. The driver exports the temperature values via the following sysfs files: -temp[1-4]_input -temp[2-4]_fault +**temp[1-4]_input** + +**temp[2-4]_fault** diff --git a/Documentation/hwmon/tps40422 b/Documentation/hwmon/tps40422.rst index 24bb0688d515..b691e30479dd 100644 --- a/Documentation/hwmon/tps40422 +++ b/Documentation/hwmon/tps40422.rst @@ -2,9 +2,13 @@ Kernel driver tps40422 ====================== Supported chips: + * TI TPS40422 + Prefix: 'tps40422' + Addresses scanned: - + Datasheet: http://www.ti.com/lit/gpn/tps40422 Author: Zhu Laiwen <richard.zhu@nsn.com> @@ -17,7 +21,7 @@ This driver supports TI TPS40422 Dual-Output or Two-Phase Synchronous Buck Controller with PMBus The driver is a client driver to the core PMBus driver. -Please see Documentation/hwmon/pmbus for details on PMBus client drivers. +Please see Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -39,6 +43,7 @@ Sysfs entries The following attributes are supported. +======================= ======================================================= in[1-2]_label "vout[1-2]" in[1-2]_input Measured voltage. From READ_VOUT register. in[1-2]_alarm voltage alarm. @@ -46,19 +51,23 @@ in[1-2]_alarm voltage alarm. curr[1-2]_input Measured current. From READ_IOUT register. curr[1-2]_label "iout[1-2]" curr1_max Maximum current. From IOUT_OC_WARN_LIMIT register. -curr1_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT register. +curr1_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT + register. curr1_max_alarm Current high alarm. From IOUT_OC_WARN_LIMIT status. curr1_crit_alarm Current critical high alarm. From IOUT_OC_FAULT status. curr2_alarm Current high alarm. From IOUT_OC_WARNING status. -temp1_input Measured temperature. From READ_TEMPERATURE_2 register on page 0. +temp1_input Measured temperature. From READ_TEMPERATURE_2 register + on page 0. temp1_max Maximum temperature. From OT_WARN_LIMIT register. temp1_crit Critical high temperature. From OT_FAULT_LIMIT register. temp1_max_alarm Chip temperature high alarm. Set by comparing - READ_TEMPERATURE_2 on page 0 with OT_WARN_LIMIT if TEMP_OT_WARNING - status is set. + READ_TEMPERATURE_2 on page 0 with OT_WARN_LIMIT if + TEMP_OT_WARNING status is set. temp1_crit_alarm Chip temperature critical high alarm. Set by comparing - READ_TEMPERATURE_2 on page 0 with OT_FAULT_LIMIT if TEMP_OT_FAULT - status is set. -temp2_input Measured temperature. From READ_TEMPERATURE_2 register on page 1. + READ_TEMPERATURE_2 on page 0 with OT_FAULT_LIMIT if + TEMP_OT_FAULT status is set. +temp2_input Measured temperature. From READ_TEMPERATURE_2 register + on page 1. temp2_alarm Chip temperature alarm on page 1. +======================= ======================================================= diff --git a/Documentation/hwmon/twl4030-madc-hwmon b/Documentation/hwmon/twl4030-madc-hwmon.rst index c3a3a5be10ad..22c885383b11 100644 --- a/Documentation/hwmon/twl4030-madc-hwmon +++ b/Documentation/hwmon/twl4030-madc-hwmon.rst @@ -1,8 +1,10 @@ Kernel driver twl4030-madc -========================= +========================== Supported chips: + * Texas Instruments TWL4030 + Prefix: 'twl4030-madc' @@ -19,8 +21,9 @@ channels which can be used in different modes. See this table for the meaning of the different channels +======= ========================================================== Channel Signal ------------------------------------------- +======= ========================================================== 0 Battery type(BTYPE) 1 BCI: Battery temperature (BTEMP) 2 GP analog input @@ -37,6 +40,7 @@ Channel Signal 13 Reserved 14 Reserved 15 VRUSB Supply/Speaker left/Speaker right polarization level +======= ========================================================== The Sysfs nodes will represent the voltage in the units of mV, diff --git a/Documentation/hwmon/ucd9000 b/Documentation/hwmon/ucd9000.rst index 262e713e60ff..ebc4f2b3bfea 100644 --- a/Documentation/hwmon/ucd9000 +++ b/Documentation/hwmon/ucd9000.rst @@ -2,15 +2,20 @@ Kernel driver ucd9000 ===================== Supported chips: + * TI UCD90120, UCD90124, UCD90160, UCD9090, and UCD90910 + Prefixes: 'ucd90120', 'ucd90124', 'ucd90160', 'ucd9090', 'ucd90910' + Addresses scanned: - + Datasheets: - http://focus.ti.com/lit/ds/symlink/ucd90120.pdf - http://focus.ti.com/lit/ds/symlink/ucd90124.pdf - http://focus.ti.com/lit/ds/symlink/ucd90160.pdf - http://focus.ti.com/lit/ds/symlink/ucd9090.pdf - http://focus.ti.com/lit/ds/symlink/ucd90910.pdf + + - http://focus.ti.com/lit/ds/symlink/ucd90120.pdf + - http://focus.ti.com/lit/ds/symlink/ucd90124.pdf + - http://focus.ti.com/lit/ds/symlink/ucd90160.pdf + - http://focus.ti.com/lit/ds/symlink/ucd9090.pdf + - http://focus.ti.com/lit/ds/symlink/ucd90910.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -52,7 +57,7 @@ system-health monitor. The device integrates a 12-bit ADC for monitoring up to 13 power-supply voltage, current, or temperature inputs. This driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus for details on PMBus client drivers. +Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -67,7 +72,7 @@ Platform data support --------------------- The driver supports standard PMBus driver platform data. Please see -Documentation/hwmon/pmbus for details. +Documentation/hwmon/pmbus.rst for details. Sysfs entries @@ -76,23 +81,28 @@ Sysfs entries The following attributes are supported. Limits are read-write; all other attributes are read-only. +======================= ======================================================== in[1-12]_label "vout[1-12]". in[1-12]_input Measured voltage. From READ_VOUT register. in[1-12]_min Minimum Voltage. From VOUT_UV_WARN_LIMIT register. in[1-12]_max Maximum voltage. From VOUT_OV_WARN_LIMIT register. in[1-12]_lcrit Critical minimum Voltage. VOUT_UV_FAULT_LIMIT register. -in[1-12]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT register. +in[1-12]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT + register. in[1-12]_min_alarm Voltage low alarm. From VOLTAGE_UV_WARNING status. in[1-12]_max_alarm Voltage high alarm. From VOLTAGE_OV_WARNING status. -in[1-12]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT status. -in[1-12]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT status. +in[1-12]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT + status. +in[1-12]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT + status. curr[1-12]_label "iout[1-12]". curr[1-12]_input Measured current. From READ_IOUT register. curr[1-12]_max Maximum current. From IOUT_OC_WARN_LIMIT register. -curr[1-12]_lcrit Critical minimum output current. From IOUT_UC_FAULT_LIMIT +curr[1-12]_lcrit Critical minimum output current. From + IOUT_UC_FAULT_LIMIT register. +curr[1-12]_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT register. -curr[1-12]_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT register. curr[1-12]_max_alarm Current high alarm. From IOUT_OC_WARNING status. curr[1-12]_crit_alarm Current critical high alarm. From IOUT_OC_FAULT status. @@ -116,3 +126,4 @@ fan[1-4]_fault Fan fault. created only for enabled fans. Note that even though UCD90910 supports up to 10 fans, only up to four fans are currently supported. +======================= ======================================================== diff --git a/Documentation/hwmon/ucd9200 b/Documentation/hwmon/ucd9200.rst index 1e8060e631bd..b819dfd75f71 100644 --- a/Documentation/hwmon/ucd9200 +++ b/Documentation/hwmon/ucd9200.rst @@ -2,18 +2,23 @@ Kernel driver ucd9200 ===================== Supported chips: + * TI UCD9220, UCD9222, UCD9224, UCD9240, UCD9244, UCD9246, and UCD9248 + Prefixes: 'ucd9220', 'ucd9222', 'ucd9224', 'ucd9240', 'ucd9244', 'ucd9246', - 'ucd9248' + 'ucd9248' + Addresses scanned: - + Datasheets: - http://focus.ti.com/lit/ds/symlink/ucd9220.pdf - http://focus.ti.com/lit/ds/symlink/ucd9222.pdf - http://focus.ti.com/lit/ds/symlink/ucd9224.pdf - http://focus.ti.com/lit/ds/symlink/ucd9240.pdf - http://focus.ti.com/lit/ds/symlink/ucd9244.pdf - http://focus.ti.com/lit/ds/symlink/ucd9246.pdf - http://focus.ti.com/lit/ds/symlink/ucd9248.pdf + + - http://focus.ti.com/lit/ds/symlink/ucd9220.pdf + - http://focus.ti.com/lit/ds/symlink/ucd9222.pdf + - http://focus.ti.com/lit/ds/symlink/ucd9224.pdf + - http://focus.ti.com/lit/ds/symlink/ucd9240.pdf + - http://focus.ti.com/lit/ds/symlink/ucd9244.pdf + - http://focus.ti.com/lit/ds/symlink/ucd9246.pdf + - http://focus.ti.com/lit/ds/symlink/ucd9248.pdf Author: Guenter Roeck <linux@roeck-us.net> @@ -28,7 +33,7 @@ dedicated circuitry for DC/DC loop management with flash memory and a serial interface to support configuration, monitoring and management. This driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus for details on PMBus client drivers. +Documentation/hwmon/pmbus.rst for details on PMBus client drivers. Usage Notes @@ -43,7 +48,7 @@ Platform data support --------------------- The driver supports standard PMBus driver platform data. Please see -Documentation/hwmon/pmbus for details. +Documentation/hwmon/pmbus.rst for details. Sysfs entries @@ -52,12 +57,14 @@ Sysfs entries The following attributes are supported. Limits are read-write; all other attributes are read-only. +======================= ======================================================== in1_label "vin". in1_input Measured voltage. From READ_VIN register. in1_min Minimum Voltage. From VIN_UV_WARN_LIMIT register. in1_max Maximum voltage. From VIN_OV_WARN_LIMIT register. in1_lcrit Critical minimum Voltage. VIN_UV_FAULT_LIMIT register. -in1_crit Critical maximum voltage. From VIN_OV_FAULT_LIMIT register. +in1_crit Critical maximum voltage. From VIN_OV_FAULT_LIMIT + register. in1_min_alarm Voltage low alarm. From VIN_UV_WARNING status. in1_max_alarm Voltage high alarm. From VIN_OV_WARNING status. in1_lcrit_alarm Voltage critical low alarm. From VIN_UV_FAULT status. @@ -68,11 +75,14 @@ in[2-5]_input Measured voltage. From READ_VOUT register. in[2-5]_min Minimum Voltage. From VOUT_UV_WARN_LIMIT register. in[2-5]_max Maximum voltage. From VOUT_OV_WARN_LIMIT register. in[2-5]_lcrit Critical minimum Voltage. VOUT_UV_FAULT_LIMIT register. -in[2-5]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT register. +in[2-5]_crit Critical maximum voltage. From VOUT_OV_FAULT_LIMIT + register. in[2-5]_min_alarm Voltage low alarm. From VOLTAGE_UV_WARNING status. in[2-5]_max_alarm Voltage high alarm. From VOLTAGE_OV_WARNING status. -in[2-5]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT status. -in[2-5]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT status. +in[2-5]_lcrit_alarm Voltage critical low alarm. From VOLTAGE_UV_FAULT + status. +in[2-5]_crit_alarm Voltage critical high alarm. From VOLTAGE_OV_FAULT + status. curr1_label "iin". curr1_input Measured current. From READ_IIN register. @@ -80,9 +90,10 @@ curr1_input Measured current. From READ_IIN register. curr[2-5]_label "iout[1-4]". curr[2-5]_input Measured current. From READ_IOUT register. curr[2-5]_max Maximum current. From IOUT_OC_WARN_LIMIT register. -curr[2-5]_lcrit Critical minimum output current. From IOUT_UC_FAULT_LIMIT +curr[2-5]_lcrit Critical minimum output current. From + IOUT_UC_FAULT_LIMIT register. +curr[2-5]_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT register. -curr[2-5]_crit Critical maximum current. From IOUT_OC_FAULT_LIMIT register. curr[2-5]_max_alarm Current high alarm. From IOUT_OC_WARNING status. curr[2-5]_crit_alarm Current critical high alarm. From IOUT_OC_FAULT status. @@ -97,7 +108,7 @@ power[2-5]_label "pout[1-4]" rails. See chip datasheets for details. temp[1-5]_input Measured temperatures. From READ_TEMPERATURE_1 and - READ_TEMPERATURE_2 registers. + READ_TEMPERATURE_2 registers. temp1 is the chip internal temperature. temp[2-5] are rail temperatures. temp[2-5] attributes are only created for enabled rails. See chip datasheets for @@ -110,3 +121,4 @@ temp[1-5]_crit_alarm Temperature critical high alarm. fan1_input Fan RPM. ucd9240 only. fan1_alarm Fan alarm. ucd9240 only. fan1_fault Fan fault. ucd9240 only. +======================= ======================================================== diff --git a/Documentation/hwmon/userspace-tools b/Documentation/hwmon/userspace-tools.rst index 9865aeedc58f..bf3797c8e734 100644 --- a/Documentation/hwmon/userspace-tools +++ b/Documentation/hwmon/userspace-tools.rst @@ -1,3 +1,6 @@ +Userspace tools +=============== + Introduction ------------ diff --git a/Documentation/hwmon/vexpress b/Documentation/hwmon/vexpress.rst index 557d6d5ad90d..8c861c8151ac 100644 --- a/Documentation/hwmon/vexpress +++ b/Documentation/hwmon/vexpress.rst @@ -2,14 +2,21 @@ Kernel driver vexpress ====================== Supported systems: + * ARM Ltd. Versatile Express platform + Prefix: 'vexpress' + Datasheets: + * "Hardware Description" sections of the Technical Reference Manuals - for the Versatile Express boards: - http://infocenter.arm.com/help/topic/com.arm.doc.subset.boards.express/index.html + for the Versatile Express boards: + + - http://infocenter.arm.com/help/topic/com.arm.doc.subset.boards.express/index.html + * Section "4.4.14. System Configuration registers" of the V2M-P1 TRM: - http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0447-/index.html + + - http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0447-/index.html Author: Pawel Moll diff --git a/Documentation/hwmon/via686a b/Documentation/hwmon/via686a.rst index e5f90ab5c48d..a343c35df740 100644 --- a/Documentation/hwmon/via686a +++ b/Documentation/hwmon/via686a.rst @@ -2,29 +2,35 @@ Kernel driver via686a ===================== Supported chips: + * Via VT82C686A, VT82C686B Southbridge Integrated Hardware Monitor + Prefix: 'via686a' + Addresses scanned: ISA in PCI-space encoded address + Datasheet: On request through web form (http://www.via.com.tw/en/resources/download-center/) Authors: - Kyösti Mälkki <kmalkki@cc.hut.fi>, - Mark D. Studebaker <mdsxyz123@yahoo.com> - Bob Dougherty <bobd@stanford.edu> - (Some conversion-factor data were contributed by - Jonathan Teh Soon Yew <j.teh@iname.com> - and Alex van Kaam <darkside@chello.nl>.) + - Kyösti Mälkki <kmalkki@cc.hut.fi>, + - Mark D. Studebaker <mdsxyz123@yahoo.com> + - Bob Dougherty <bobd@stanford.edu> + - (Some conversion-factor data were contributed by + - Jonathan Teh Soon Yew <j.teh@iname.com> + - and Alex van Kaam <darkside@chello.nl>.) Module Parameters ----------------- +======================= ======================================================= force_addr=0xaddr Set the I/O base address. Useful for boards that - don't set the address in the BIOS. Look for a BIOS - upgrade before resorting to this. Does not do a - PCI force; the via686a must still be present in lspci. - Don't use this unless the driver complains that the - base address is not set. - Example: 'modprobe via686a force_addr=0x6000' + don't set the address in the BIOS. Look for a BIOS + upgrade before resorting to this. Does not do a + PCI force; the via686a must still be present in lspci. + Don't use this unless the driver complains that the + base address is not set. + Example: 'modprobe via686a force_addr=0x6000' +======================= ======================================================= Description ----------- diff --git a/Documentation/hwmon/vt1211 b/Documentation/hwmon/vt1211.rst index 77fa633b97a8..ddbcde7dd642 100644 --- a/Documentation/hwmon/vt1211 +++ b/Documentation/hwmon/vt1211.rst @@ -2,9 +2,13 @@ Kernel driver vt1211 ==================== Supported chips: + * VIA VT1211 + Prefix: 'vt1211' + Addresses scanned: none, address read from Super-I/O config space + Datasheet: Provided by VIA upon request and under NDA Authors: Juerg Haefliger <juergh@gmail.com> @@ -19,14 +23,17 @@ technical support. Module Parameters ----------------- -* uch_config: int Override the BIOS default universal channel (UCH) + +* uch_config: int + Override the BIOS default universal channel (UCH) configuration for channels 1-5. Legal values are in the range of 0-31. Bit 0 maps to UCH1, bit 1 maps to UCH2 and so on. Setting a bit to 1 enables the thermal input of that particular UCH and setting a bit to 0 enables the voltage input. -* int_mode: int Override the BIOS default temperature interrupt mode. +* int_mode: int + Override the BIOS default temperature interrupt mode. The only possible value is 0 which forces interrupt mode 0. In this mode, any pending interrupt is cleared when the status register is read but is regenerated as @@ -55,8 +62,9 @@ connected to the PWM outputs of the VT1211 :-(). The following table shows the relationship between the vt1211 inputs and the sysfs nodes. +=============== ============== =========== ================================ Sensor Voltage Mode Temp Mode Default Use (from the datasheet) ------- ------------ --------- -------------------------------- +=============== ============== =========== ================================ Reading 1 temp1 Intel thermal diode Reading 3 temp2 Internal thermal diode UCH1/Reading2 in0 temp3 NTC type thermistor @@ -65,6 +73,7 @@ UCH3 in2 temp5 VccP (processor core) UCH4 in3 temp6 +5V UCH5 in4 temp7 +12V +3.3V in5 Internal VCC (+3.3V) +=============== ============== =========== ================================ Voltage Monitoring @@ -82,19 +91,22 @@ follows. And this is of course totally dependent on the actual board implementation :-) You will have to find documentation for your own motherboard and edit sensors.conf accordingly. - Expected +============= ====== ====== ========= ============ + Expected Voltage R1 R2 Divider Raw Value ------------------------------------------------ +============= ====== ====== ========= ============ +2.5V 2K 10K 1.2 2083 mV -VccP --- --- 1.0 1400 mV (1) +VccP --- --- 1.0 1400 mV [1]_ +5V 14K 10K 2.4 2083 mV +12V 47K 10K 5.7 2105 mV -+3.3V (int) 2K 3.4K 1.588 3300 mV (2) ++3.3V (int) 2K 3.4K 1.588 3300 mV [2]_ +3.3V (ext) 6.8K 10K 1.68 1964 mV +============= ====== ====== ========= ============ + +.. [1] Depending on the CPU (1.4V is for a VIA C3 Nehemiah). -(1) Depending on the CPU (1.4V is for a VIA C3 Nehemiah). -(2) R1 and R2 for 3.3V (int) are internal to the VT1211 chip and the driver - performs the scaling and returns the properly scaled voltage value. +.. [2] R1 and R2 for 3.3V (int) are internal to the VT1211 chip and the driver + performs the scaling and returns the properly scaled voltage value. Each measured voltage has an associated low and high limit which triggers an alarm when crossed. @@ -124,35 +136,37 @@ compute temp1 (@-Offset)/Gain, (@*Gain)+Offset According to the VIA VT1211 BIOS porting guide, the following gain and offset values should be used: +=============== ======== =========== Diode Type Offset Gain ----------- ------ ---- +=============== ======== =========== Intel CPU 88.638 0.9528 - 65.000 0.9686 *) + 65.000 0.9686 [3]_ VIA C3 Ezra 83.869 0.9528 VIA C3 Ezra-T 73.869 0.9528 +=============== ======== =========== -*) This is the formula from the lm_sensors 2.10.0 sensors.conf file. I don't -know where it comes from or how it was derived, it's just listed here for -completeness. +.. [3] This is the formula from the lm_sensors 2.10.0 sensors.conf file. I don't + know where it comes from or how it was derived, it's just listed here for + completeness. Temp3-temp7 support NTC thermistors. For these channels, the driver returns the voltages as seen at the individual pins of UCH1-UCH5. The voltage at the pin (Vpin) is formed by a voltage divider made of the thermistor (Rth) and a -scaling resistor (Rs): +scaling resistor (Rs):: -Vpin = 2200 * Rth / (Rs + Rth) (2200 is the ADC max limit of 2200 mV) + Vpin = 2200 * Rth / (Rs + Rth) (2200 is the ADC max limit of 2200 mV) The equation for the thermistor is as follows (google it if you want to know -more about it): +more about it):: -Rth = Ro * exp(B * (1 / T - 1 / To)) (To is 298.15K (25C) and Ro is the - nominal resistance at 25C) + Rth = Ro * exp(B * (1 / T - 1 / To)) (To is 298.15K (25C) and Ro is the + nominal resistance at 25C) Mingling the above two equations and assuming Rs = Ro and B = 3435 yields the -following formula for sensors.conf: +following formula for sensors.conf:: -compute tempx 1 / (1 / 298.15 - (` (2200 / @ - 1)) / 3435) - 273.15, - 2200 / (1 + (^ (3435 / 298.15 - 3435 / (273.15 + @)))) + compute tempx 1 / (1 / 298.15 - (` (2200 / @ - 1)) / 3435) - 273.15, + 2200 / (1 + (^ (3435 / 298.15 - 3435 / (273.15 + @)))) Fan Speed Control @@ -176,31 +190,37 @@ registers in the VT1211 and programming one set is sufficient (actually only the first set pwm1_auto_point[1-4]_temp is writable, the second set is read-only). +========================== ========================================= PWM Auto Point PWM Output Duty-Cycle ------------------------------------------------- +========================== ========================================= pwm[1-2]_auto_point4_pwm full speed duty-cycle (hard-wired to 255) pwm[1-2]_auto_point3_pwm high speed duty-cycle pwm[1-2]_auto_point2_pwm low speed duty-cycle pwm[1-2]_auto_point1_pwm off duty-cycle (hard-wired to 0) +========================== ========================================= +========================== ================= Temp Auto Point Thermal Threshold ---------------------------------------------- +========================== ================= pwm[1-2]_auto_point4_temp full speed temp pwm[1-2]_auto_point3_temp high speed temp pwm[1-2]_auto_point2_temp low speed temp pwm[1-2]_auto_point1_temp off temp +========================== ================= Long story short, the controller implements the following algorithm to set the PWM output duty-cycle based on the input temperature: -Thermal Threshold Output Duty-Cycle - (Rising Temp) (Falling Temp) ----------------------------------------------------------- - full speed duty-cycle full speed duty-cycle +=================== ======================= ======================== +Thermal Threshold Output Duty-Cycle Output Duty-Cycle + (Rising Temp) (Falling Temp) +=================== ======================= ======================== +- full speed duty-cycle full speed duty-cycle full speed temp - high speed duty-cycle full speed duty-cycle +- high speed duty-cycle full speed duty-cycle high speed temp - low speed duty-cycle high speed duty-cycle +- low speed duty-cycle high speed duty-cycle low speed temp - off duty-cycle low speed duty-cycle +- off duty-cycle low speed duty-cycle off temp +=================== ======================= ======================== diff --git a/Documentation/hwmon/w83627ehf b/Documentation/hwmon/w83627ehf.rst index 735c42a85ead..74d19ef11e1f 100644 --- a/Documentation/hwmon/w83627ehf +++ b/Documentation/hwmon/w83627ehf.rst @@ -2,45 +2,79 @@ Kernel driver w83627ehf ======================= Supported chips: + * Winbond W83627EHF/EHG (ISA access ONLY) + Prefix: 'w83627ehf' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: not available + * Winbond W83627DHG + Prefix: 'w83627dhg' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: not available + * Winbond W83627DHG-P + Prefix: 'w83627dhg' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: not available + * Winbond W83627UHG + Prefix: 'w83627uhg' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: available from www.nuvoton.com + * Winbond W83667HG + Prefix: 'w83667hg' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: not available + * Winbond W83667HG-B + Prefix: 'w83667hg' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6775F/W83667HG-I + Prefix: 'nct6775' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + * Nuvoton NCT6776F + Prefix: 'nct6776' + Addresses scanned: ISA address retrieved from Super I/O registers + Datasheet: Available from Nuvoton upon request + Authors: - Jean Delvare <jdelvare@suse.de> - Yuan Mu (Winbond) - Rudolf Marek <r.marek@assembler.cz> - David Hubbard <david.c.hubbard@gmail.com> - Gong Jun <JGong@nuvoton.com> + + - Jean Delvare <jdelvare@suse.de> + - Yuan Mu (Winbond) + - Rudolf Marek <r.marek@assembler.cz> + - David Hubbard <david.c.hubbard@gmail.com> + - Gong Jun <JGong@nuvoton.com> Description ----------- @@ -85,25 +119,30 @@ predefined temperature range. If the temperature goes out of range, fan is driven slower/faster to reach the predefined range again. The mode works for fan1-fan4. Mapping of temperatures to pwm outputs is as -follows: +follows:: -temp1 -> pwm1 -temp2 -> pwm2 -temp3 -> pwm3 (not on 627UHG) -prog -> pwm4 (not on 667HG and 667HG-B; the programmable setting is not - supported by the driver) + temp1 -> pwm1 + temp2 -> pwm2 + temp3 -> pwm3 (not on 627UHG) + prog -> pwm4 (not on 667HG and 667HG-B; the programmable setting is not + supported by the driver) /sys files ---------- -name - this is a standard hwmon device entry, it contains the name of - the device (see the prefix in the list of supported devices at - the top of this file) +name + this is a standard hwmon device entry, it contains the name of + the device (see the prefix in the list of supported devices at + the top of this file) + +pwm[1-4] + this file stores PWM duty cycle or DC value (fan speed) in range: -pwm[1-4] - this file stores PWM duty cycle or DC value (fan speed) in range: 0 (stop) to 255 (full) -pwm[1-4]_enable - this file controls mode of fan/temperature control: +pwm[1-4]_enable + this file controls mode of fan/temperature control: + * 1 Manual mode, write to pwm file any value 0-255 (full speed) * 2 "Thermal Cruise" mode * 3 "Fan Speed Cruise" mode @@ -121,33 +160,43 @@ pwm[1-4]_enable - this file controls mode of fan/temperature control: returned when reading pwm attributes is unrelated to SmartFan IV operation. -pwm[1-4]_mode - controls if output is PWM or DC level - * 0 DC output (0 - 12v) - * 1 PWM output +pwm[1-4]_mode + controls if output is PWM or DC level + + * 0 DC output (0 - 12v) + * 1 PWM output Thermal Cruise mode ------------------- If the temperature is in the range defined by: -pwm[1-4]_target - set target temperature, unit millidegree Celsius - (range 0 - 127000) -pwm[1-4]_tolerance - tolerance, unit millidegree Celsius (range 0 - 15000) +pwm[1-4]_target + set target temperature, unit millidegree Celsius + (range 0 - 127000) +pwm[1-4]_tolerance + tolerance, unit millidegree Celsius (range 0 - 15000) there are no changes to fan speed. Once the temperature leaves the interval, fan speed increases (temp is higher) or decreases if lower than desired. There are defined steps and times, but not exported by the driver yet. -pwm[1-4]_min_output - minimum fan speed (range 1 - 255), when the temperature - is below defined range. -pwm[1-4]_stop_time - how many milliseconds [ms] must elapse to switch - corresponding fan off. (when the temperature was below - defined range). -pwm[1-4]_start_output-minimum fan speed (range 1 - 255) when spinning up -pwm[1-4]_step_output- rate of fan speed change (1 - 255) -pwm[1-4]_stop_output- minimum fan speed (range 1 - 255) when spinning down -pwm[1-4]_max_output - maximum fan speed (range 1 - 255), when the temperature - is above defined range. +pwm[1-4]_min_output + minimum fan speed (range 1 - 255), when the temperature + is below defined range. +pwm[1-4]_stop_time + how many milliseconds [ms] must elapse to switch + corresponding fan off. (when the temperature was below + defined range). +pwm[1-4]_start_output + minimum fan speed (range 1 - 255) when spinning up +pwm[1-4]_step_output + rate of fan speed change (1 - 255) +pwm[1-4]_stop_output + minimum fan speed (range 1 - 255) when spinning down +pwm[1-4]_max_output + maximum fan speed (range 1 - 255), when the temperature + is above defined range. Note: last six functions are influenced by other control bits, not yet exported by the driver, so a change might not have any effect. @@ -161,26 +210,35 @@ different power-on default values, but BIOS should already be loading appropriate defaults. Note that bank selection must be performed as is currently done in the driver for all register addresses. -0x49: only on DHG, selects temperature source for AUX fan, CPU fan0 -0x4a: not completely documented for the EHF and the DHG documentation assigns - different behavior to bits 7 and 6, including extending the temperature - input selection to SmartFan I, not just SmartFan III. Testing on the EHF - will reveal whether they are compatible or not. - -0x58: Chip ID: 0xa1=EHF 0xc1=DHG -0x5e: only on DHG, has bits to enable "current mode" temperature detection and - critical temperature protection -0x45b: only on EHF, bit 3, vin4 alarm (EHF supports 10 inputs, only 9 on DHG) -0x552: only on EHF, vin4 -0x558: only on EHF, vin4 high limit -0x559: only on EHF, vin4 low limit -0x6b: only on DHG, SYS fan critical temperature -0x6c: only on DHG, CPU fan0 critical temperature -0x6d: only on DHG, AUX fan critical temperature -0x6e: only on DHG, CPU fan1 critical temperature - -0x50-0x55 and 0x650-0x657 are marked "Test Register" for the EHF, but "Reserved - Register" for the DHG +========================= ===================================================== +Register(s) Meaning +========================= ===================================================== +0x49 only on DHG, selects temperature source for AUX fan, + CPU fan0 +0x4a not completely documented for the EHF and the DHG + documentation assigns different behavior to bits 7 + and 6, including extending the temperature input + selection to SmartFan I, not just SmartFan III. + Testing on the EHF will reveal whether they are + compatible or not. +0x58 Chip ID: 0xa1=EHF 0xc1=DHG +0x5e only on DHG, has bits to enable "current mode" + temperature detection and critical temperature + protection +0x45b only on EHF, bit 3, vin4 alarm (EHF supports 10 + inputs, only 9 on DHG) +0x552 only on EHF, vin4 +0x558 only on EHF, vin4 high limit +0x559 only on EHF, vin4 low limit +0x6b only on DHG, SYS fan critical temperature +0x6c only on DHG, CPU fan0 critical temperature +0x6d only on DHG, AUX fan critical temperature +0x6e only on DHG, CPU fan1 critical temperature +0x50-0x55 and 0x650-0x657 marked as: + + - "Test Register" for the EHF + - "Reserved Register" for the DHG +========================= ===================================================== The DHG also supports PECI, where the DHG queries Intel CPU temperatures, and the ICH8 southbridge gets that data via PECI from the DHG, so that the diff --git a/Documentation/hwmon/w83627hf b/Documentation/hwmon/w83627hf.rst index 8432e1118173..d1406c28dee7 100644 --- a/Documentation/hwmon/w83627hf +++ b/Documentation/hwmon/w83627hf.rst @@ -20,10 +20,10 @@ Supported chips: Datasheet: Provided by Winbond on request(http://www.winbond.com/hq/enu) Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark Studebaker <mdsxyz123@yahoo.com>, - Bernhard C. Schrenk <clemy@clemy.org> + Frodo Looijaard <frodol@dds.nl>, + Philip Edelbrock <phil@netroedge.com>, + Mark Studebaker <mdsxyz123@yahoo.com>, + Bernhard C. Schrenk <clemy@clemy.org> Module Parameters ----------------- @@ -52,8 +52,8 @@ If you really want i2c accesses for these Super I/O chips, use the w83781d driver. However this is not the preferred method now that this ISA driver has been developed. -The w83627_HF_ uses pins 110-106 as VID0-VID4. The w83627_THF_ uses the -same pins as GPIO[0:4]. Technically, the w83627_THF_ does not support a +The `w83627_HF_` uses pins 110-106 as VID0-VID4. The `w83627_THF_` uses the +same pins as GPIO[0:4]. Technically, the `w83627_THF_` does not support a VID reading. However the two chips have the identical 128 pin package. So, it is possible or even likely for a w83627thf to have the VID signals routed to these pins despite their not being labeled for that purpose. Therefore, @@ -75,19 +75,23 @@ module parameter is gone for technical reasons. If you need this feature, you can obtain the same result by using the isaset tool (part of lm-sensors) before loading the driver: -# Enter the Super I/O config space -isaset -y -f 0x2e 0x87 -isaset -y -f 0x2e 0x87 +# Enter the Super I/O config space:: -# Select the hwmon logical device -isaset -y 0x2e 0x2f 0x07 0x0b + isaset -y -f 0x2e 0x87 + isaset -y -f 0x2e 0x87 -# Set the base I/O address (to 0x290 in this example) -isaset -y 0x2e 0x2f 0x60 0x02 -isaset -y 0x2e 0x2f 0x61 0x90 +# Select the hwmon logical device:: -# Exit the Super-I/O config space -isaset -y -f 0x2e 0xaa + isaset -y 0x2e 0x2f 0x07 0x0b + +# Set the base I/O address (to 0x290 in this example):: + + isaset -y 0x2e 0x2f 0x60 0x02 + isaset -y 0x2e 0x2f 0x61 0x90 + +# Exit the Super-I/O config space:: + + isaset -y -f 0x2e 0xaa The above sequence assumes a Super-I/O config space at 0x2e/0x2f, but 0x4e/0x4f is also possible. @@ -97,18 +101,23 @@ Voltage pin mapping Here is a summary of the voltage pin mapping for the W83627THF. This can be useful to convert data provided by board manufacturers into -working libsensors configuration statements. - - W83627THF | - Pin | Name | Register | Sysfs attribute ------------------------------------------------------ - 100 | CPUVCORE | 20h | in0 - 99 | VIN0 | 21h | in1 - 98 | VIN1 | 22h | in2 - 97 | VIN2 | 24h | in4 - 114 | AVCC | 23h | in3 - 61 | 5VSB | 50h (bank 5) | in7 - 74 | VBAT | 51h (bank 5) | in8 +working libsensors configuration statements: + + +- W83627THF + + + ======== =============== =============== =============== + Pin Name Register Sysfs attribute + ======== =============== =============== =============== + 100 CPUVCORE 20h in0 + 99 VIN0 21h in1 + 98 VIN1 22h in2 + 97 VIN2 24h in4 + 114 AVCC 23h in3 + 61 5VSB 50h (bank 5) in7 + 74 VBAT 51h (bank 5) in8 + ======== =============== =============== =============== For other supported devices, you'll have to take the hard path and look up the information in the datasheet yourself (and then add it diff --git a/Documentation/hwmon/w83773g b/Documentation/hwmon/w83773g.rst index 4cc6c0b8257f..cabaed391414 100644 --- a/Documentation/hwmon/w83773g +++ b/Documentation/hwmon/w83773g.rst @@ -1,13 +1,18 @@ Kernel driver w83773g -==================== +===================== Supported chips: + * Nuvoton W83773G + Prefix: 'w83773g' + Addresses scanned: I2C 0x4c and 0x4d + Datasheet: https://www.nuvoton.com/resource-files/W83773G_SG_DatasheetV1_2.pdf Authors: + Lei YU <mine260309@gmail.com> Description @@ -27,7 +32,4 @@ Resolution for both the local and remote channels is 0.125 degree C. The chip supports only temperature measurement. The driver exports the temperature values via the following sysfs files: -temp[1-3]_input -temp[2-3]_fault -temp[2-3]_offset -update_interval +**temp[1-3]_input, temp[2-3]_fault, temp[2-3]_offset, update_interval** diff --git a/Documentation/hwmon/w83781d b/Documentation/hwmon/w83781d.rst index 129b0a3b555b..f36d33dfb704 100644 --- a/Documentation/hwmon/w83781d +++ b/Documentation/hwmon/w83781d.rst @@ -2,44 +2,64 @@ Kernel driver w83781d ===================== Supported chips: + * Winbond W83781D + Prefix: 'w83781d' + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) + Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/w83781d.pdf + * Winbond W83782D + Prefix: 'w83782d' + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) + Datasheet: http://www.winbond.com + * Winbond W83783S + Prefix: 'w83783s' + Addresses scanned: I2C 0x2d + Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/w83783s.pdf + * Asus AS99127F + Prefix: 'as99127f' + Addresses scanned: I2C 0x28 - 0x2f + Datasheet: Unavailable from Asus + + Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark Studebaker <mdsxyz123@yahoo.com> + + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com>, + - Mark Studebaker <mdsxyz123@yahoo.com> Module parameters ----------------- * init int - (default 1) - Use 'init=0' to bypass initializing the chip. - Try this if your computer crashes when you load the module. + (default 1) + + Use 'init=0' to bypass initializing the chip. + Try this if your computer crashes when you load the module. * reset int - (default 0) - The driver used to reset the chip on load, but does no more. Use - 'reset=1' to restore the old behavior. Report if you need to do this. + (default 0) + The driver used to reset the chip on load, but does no more. Use + 'reset=1' to restore the old behavior. Report if you need to do this. force_subclients=bus,caddr,saddr,saddr This is used to force the i2c addresses for subclients of - a certain chip. Typical usage is `force_subclients=0,0x2d,0x4a,0x4b' + a certain chip. Typical usage is `force_subclients=0,0x2d,0x4a,0x4b` to force the subclients of chip 0x2d on bus 0 to i2c addresses 0x4a and 0x4b. This parameter is useful for certain Tyan boards. @@ -54,12 +74,19 @@ There is quite some difference between these chips, but they are similar enough that it was sensible to put them together in one driver. The Asus chips are similar to an I2C-only W83782D. -Chip #vin #fanin #pwm #temp wchipid vendid i2c ISA -as99127f 7 3 0 3 0x31 0x12c3 yes no -as99127f rev.2 (type_name = as99127f) 0x31 0x5ca3 yes no -w83781d 7 3 0 3 0x10-1 0x5ca3 yes yes -w83782d 9 3 2-4 3 0x30 0x5ca3 yes yes -w83783s 5-6 3 2 1-2 0x40 0x5ca3 yes no ++----------+---------+--------+-------+-------+---------+--------+------+-----+ +| Chip | #vin | #fanin | #pwm | #temp | wchipid | vendid | i2c | ISA | ++----------+---------+--------+-------+-------+---------+--------+------+-----+ +| as99127f | 7 | 3 | 0 | 3 | 0x31 | 0x12c3 | yes | no | ++----------+---------+--------+-------+-------+---------+--------+------+-----+ +| as99127f rev.2 (type_name = as99127f) | 0x31 | 0x5ca3 | yes | no | ++----------+---------+--------+-------+-------+---------+--------+------+-----+ +| w83781d | 7 | 3 | 0 | 3 | 0x10-1 | 0x5ca3 | yes | yes | ++----------+---------+--------+-------+-------+---------+--------+------+-----+ +| w83782d | 9 | 3 | 2-4 | 3 | 0x30 | 0x5ca3 | yes | yes | ++----------+---------+--------+-------+-------+---------+--------+------+-----+ +| w83783s | 5-6 | 3 | 2 | 1-2 | 0x40 | 0x5ca3 | yes | no | ++----------+---------+--------+-------+-------+---------+--------+------+-----+ Detection of these chips can sometimes be foiled because they can be in an internal state that allows no clean access. If you know the address @@ -124,22 +151,24 @@ or only the beeping for some alarms. Individual alarm and beep bits: -0x000001: in0 -0x000002: in1 -0x000004: in2 -0x000008: in3 -0x000010: temp1 -0x000020: temp2 (+temp3 on W83781D) -0x000040: fan1 -0x000080: fan2 -0x000100: in4 -0x000200: in5 -0x000400: in6 -0x000800: fan3 -0x001000: chassis -0x002000: temp3 (W83782D only) -0x010000: in7 (W83782D only) -0x020000: in8 (W83782D only) +======== ========================== +0x000001 in0 +0x000002 in1 +0x000004 in2 +0x000008 in3 +0x000010 temp1 +0x000020 temp2 (+temp3 on W83781D) +0x000040 fan1 +0x000080 fan2 +0x000100 in4 +0x000200 in5 +0x000400 in6 +0x000800 fan3 +0x001000 chassis +0x002000 temp3 (W83782D only) +0x010000 in7 (W83782D only) +0x020000 in8 (W83782D only) +======== ========================== If an alarm triggers, it will remain triggered until the hardware register is read at least once. This means that the cause for the alarm may @@ -179,68 +208,74 @@ Please do not send mail to the author or the sensors group asking for a datasheet or ideas on how to convince Asus. We can't help. -NOTES: +NOTES ----- 783s has no in1 so that in[2-6] are compatible with the 781d/782d. 783s pin is programmable for -5V or temp1; defaults to -5V, - no control in driver so temp1 doesn't work. + no control in driver so temp1 doesn't work. 782d and 783s datasheets differ on which is pwm1 and which is pwm2. - We chose to follow 782d. + We chose to follow 782d. 782d and 783s pin is programmable for fan3 input or pwm2 output; - defaults to fan3 input. - If pwm2 is enabled (with echo 255 1 > pwm2), then - fan3 will report 0. + defaults to fan3 input. + If pwm2 is enabled (with echo 255 1 > pwm2), then + fan3 will report 0. 782d has pwm1-2 for ISA, pwm1-4 for i2c. (pwm3-4 share pins with - the ISA pins) + the ISA pins) -Data sheet updates: +Data sheet updates ------------------ - PWM clock registers: - - 000: master / 512 - 001: master / 1024 - 010: master / 2048 - 011: master / 4096 - 100: master / 8192 + * 000: master / 512 + * 001: master / 1024 + * 010: master / 2048 + * 011: master / 4096 + * 100: master / 8192 Answers from Winbond tech support --------------------------------- -> -> 1) In the W83781D data sheet section 7.2 last paragraph, it talks about -> reprogramming the R-T table if the Beta of the thermistor is not -> 3435K. The R-T table is described briefly in section 8.20. -> What formulas do I use to program a new R-T table for a given Beta? -> - We are sorry that the calculation for R-T table value is -confidential. If you have another Beta value of thermistor, we can help -to calculate the R-T table for you. But you should give us real R-T -Table which can be gotten by thermistor vendor. Therefore we will calculate -them and obtain 32-byte data, and you can fill the 32-byte data to the -register in Bank0.CR51 of W83781D. +:: + + > + > 1) In the W83781D data sheet section 7.2 last paragraph, it talks about + > reprogramming the R-T table if the Beta of the thermistor is not + > 3435K. The R-T table is described briefly in section 8.20. + > What formulas do I use to program a new R-T table for a given Beta? + > + + We are sorry that the calculation for R-T table value is + confidential. If you have another Beta value of thermistor, we can help + to calculate the R-T table for you. But you should give us real R-T + Table which can be gotten by thermistor vendor. Therefore we will calculate + them and obtain 32-byte data, and you can fill the 32-byte data to the + register in Bank0.CR51 of W83781D. -> 2) In the W83782D data sheet, it mentions that pins 38, 39, and 40 are -> programmable to be either thermistor or Pentium II diode inputs. -> How do I program them for diode inputs? I can't find any register -> to program these to be diode inputs. - --> You may program Bank0 CR[5Dh] and CR[59h] registers. - CR[5Dh] bit 1(VTIN1) bit 2(VTIN2) bit 3(VTIN3) + > 2) In the W83782D data sheet, it mentions that pins 38, 39, and 40 are + > programmable to be either thermistor or Pentium II diode inputs. + > How do I program them for diode inputs? I can't find any register + > to program these to be diode inputs. - thermistor 0 0 0 - diode 1 1 1 + You may program Bank0 CR[5Dh] and CR[59h] registers. + =============================== =============== ============== ============ + CR[5Dh] bit 1(VTIN1) bit 2(VTIN2) bit 3(VTIN3) -(error) CR[59h] bit 4(VTIN1) bit 2(VTIN2) bit 3(VTIN3) -(right) CR[59h] bit 4(VTIN1) bit 5(VTIN2) bit 6(VTIN3) + thermistor 0 0 0 + diode 1 1 1 - PII thermal diode 1 1 1 - 2N3904 diode 0 0 0 + + (error) CR[59h] bit 4(VTIN1) bit 2(VTIN2) bit 3(VTIN3) + (right) CR[59h] bit 4(VTIN1) bit 5(VTIN2) bit 6(VTIN3) + + PII thermal diode 1 1 1 + 2N3904 diode 0 0 0 + =============================== =============== ============== ============ Asus Clones @@ -251,18 +286,21 @@ Here are some very useful information that were given to us by Alex Van Kaam about how to detect these chips, and how to read their values. He also gives advice for another Asus chipset, the Mozart-2 (which we don't support yet). Thanks Alex! + I reworded some parts and added personal comments. -# Detection: +Detection +^^^^^^^^^ AS99127F rev.1, AS99127F rev.2 and ASB100: - I2C address range: 0x29 - 0x2F -- If register 0x58 holds 0x31 then we have an Asus (either ASB100 or - AS99127F) +- If register 0x58 holds 0x31 then we have an Asus (either ASB100 or AS99127F) - Which one depends on register 0x4F (manufacturer ID): - 0x06 or 0x94: ASB100 - 0x12 or 0xC3: AS99127F rev.1 - 0x5C or 0xA3: AS99127F rev.2 + + - 0x06 or 0x94: ASB100 + - 0x12 or 0xC3: AS99127F rev.1 + - 0x5C or 0xA3: AS99127F rev.2 + Note that 0x5CA3 is Winbond's ID (WEC), which let us think Asus get their AS99127F rev.2 direct from Winbond. The other codes mean ATT and DVC, respectively. ATT could stand for Asustek something (although it would be @@ -273,88 +311,103 @@ Mozart-2: - I2C address: 0x77 - If register 0x58 holds 0x56 or 0x10 then we have a Mozart-2 - Of the Mozart there are 3 types: - 0x58=0x56, 0x4E=0x94, 0x4F=0x36: Asus ASM58 Mozart-2 - 0x58=0x56, 0x4E=0x94, 0x4F=0x06: Asus AS2K129R Mozart-2 - 0x58=0x10, 0x4E=0x5C, 0x4F=0xA3: Asus ??? Mozart-2 + + - 0x58=0x56, 0x4E=0x94, 0x4F=0x36: Asus ASM58 Mozart-2 + - 0x58=0x56, 0x4E=0x94, 0x4F=0x06: Asus AS2K129R Mozart-2 + - 0x58=0x10, 0x4E=0x5C, 0x4F=0xA3: Asus ??? Mozart-2 + You can handle all 3 the exact same way :) -# Temperature sensors: +Temperature sensors +^^^^^^^^^^^^^^^^^^^ ASB100: -- sensor 1: register 0x27 -- sensor 2 & 3 are the 2 LM75's on the SMBus -- sensor 4: register 0x17 -Remark: I noticed that on Intel boards sensor 2 is used for the CPU + - sensor 1: register 0x27 + - sensor 2 & 3 are the 2 LM75's on the SMBus + - sensor 4: register 0x17 + +Remark: + + I noticed that on Intel boards sensor 2 is used for the CPU and 4 is ignored/stuck, on AMD boards sensor 4 is the CPU and sensor 2 is either ignored or a socket temperature. AS99127F (rev.1 and 2 alike): -- sensor 1: register 0x27 -- sensor 2 & 3 are the 2 LM75's on the SMBus -Remark: Register 0x5b is suspected to be temperature type selector. Bit 1 + - sensor 1: register 0x27 + - sensor 2 & 3 are the 2 LM75's on the SMBus + +Remark: + + Register 0x5b is suspected to be temperature type selector. Bit 1 would control temp1, bit 3 temp2 and bit 5 temp3. Mozart-2: -- sensor 1: register 0x27 -- sensor 2: register 0x13 + - sensor 1: register 0x27 + - sensor 2: register 0x13 -# Fan sensors: +Fan sensors +^^^^^^^^^^^ ASB100, AS99127F (rev.1 and 2 alike): -- 3 fans, identical to the W83781D + - 3 fans, identical to the W83781D Mozart-2: -- 2 fans only, 1350000/RPM/div -- fan 1: register 0x28, divisor on register 0xA1 (bits 4-5) -- fan 2: register 0x29, divisor on register 0xA1 (bits 6-7) + - 2 fans only, 1350000/RPM/div + - fan 1: register 0x28, divisor on register 0xA1 (bits 4-5) + - fan 2: register 0x29, divisor on register 0xA1 (bits 6-7) -# Voltages: +Voltages +^^^^^^^^ This is where there is a difference between AS99127F rev.1 and 2. -Remark: The difference is similar to the difference between + +Remark: + + The difference is similar to the difference between W83781D and W83782D. ASB100: -in0=r(0x20)*0.016 -in1=r(0x21)*0.016 -in2=r(0x22)*0.016 -in3=r(0x23)*0.016*1.68 -in4=r(0x24)*0.016*3.8 -in5=r(0x25)*(-0.016)*3.97 -in6=r(0x26)*(-0.016)*1.666 + - in0=r(0x20)*0.016 + - in1=r(0x21)*0.016 + - in2=r(0x22)*0.016 + - in3=r(0x23)*0.016*1.68 + - in4=r(0x24)*0.016*3.8 + - in5=r(0x25)*(-0.016)*3.97 + - in6=r(0x26)*(-0.016)*1.666 AS99127F rev.1: -in0=r(0x20)*0.016 -in1=r(0x21)*0.016 -in2=r(0x22)*0.016 -in3=r(0x23)*0.016*1.68 -in4=r(0x24)*0.016*3.8 -in5=r(0x25)*(-0.016)*3.97 -in6=r(0x26)*(-0.016)*1.503 + - in0=r(0x20)*0.016 + - in1=r(0x21)*0.016 + - in2=r(0x22)*0.016 + - in3=r(0x23)*0.016*1.68 + - in4=r(0x24)*0.016*3.8 + - in5=r(0x25)*(-0.016)*3.97 + - in6=r(0x26)*(-0.016)*1.503 AS99127F rev.2: -in0=r(0x20)*0.016 -in1=r(0x21)*0.016 -in2=r(0x22)*0.016 -in3=r(0x23)*0.016*1.68 -in4=r(0x24)*0.016*3.8 -in5=(r(0x25)*0.016-3.6)*5.14+3.6 -in6=(r(0x26)*0.016-3.6)*3.14+3.6 + - in0=r(0x20)*0.016 + - in1=r(0x21)*0.016 + - in2=r(0x22)*0.016 + - in3=r(0x23)*0.016*1.68 + - in4=r(0x24)*0.016*3.8 + - in5=(r(0x25)*0.016-3.6)*5.14+3.6 + - in6=(r(0x26)*0.016-3.6)*3.14+3.6 Mozart-2: -in0=r(0x20)*0.016 -in1=255 -in2=r(0x22)*0.016 -in3=r(0x23)*0.016*1.68 -in4=r(0x24)*0.016*4 -in5=255 -in6=255 + - in0=r(0x20)*0.016 + - in1=255 + - in2=r(0x22)*0.016 + - in3=r(0x23)*0.016*1.68 + - in4=r(0x24)*0.016*4 + - in5=255 + - in6=255 -# PWM +PWM +^^^ * Additional info about PWM on the AS99127F (may apply to other Asus -chips as well) by Jean Delvare as of 2004-04-09: + chips as well) by Jean Delvare as of 2004-04-09: AS99127F revision 2 seems to have two PWM registers at 0x59 and 0x5A, and a temperature sensor type selector at 0x5B (which basically means @@ -401,15 +454,20 @@ AS99127F chips at all. I've been fiddling around with the (in)famous 0x59 register and found out the following values do work as a form of coarse pwm: -0x80 - seems to turn fans off after some time(1-2 minutes)... might be -some form of auto-fan-control based on temp? hmm (Qfan? this mobo is an -old ASUS, it isn't marketed as Qfan. Maybe some beta pre-attempt at Qfan -that was dropped at the BIOS) -0x81 - off -0x82 - slightly "on-ner" than off, but my fans do not get to move. I can -hear the high-pitched PWM sound that motors give off at too-low-pwm. -0x83 - now they do move. Estimate about 70% speed or so. -0x84-0x8f - full on +0x80 + - seems to turn fans off after some time(1-2 minutes)... might be + some form of auto-fan-control based on temp? hmm (Qfan? this mobo is an + old ASUS, it isn't marketed as Qfan. Maybe some beta pre-attempt at Qfan + that was dropped at the BIOS) +0x81 + - off +0x82 + - slightly "on-ner" than off, but my fans do not get to move. I can + hear the high-pitched PWM sound that motors give off at too-low-pwm. +0x83 + - now they do move. Estimate about 70% speed or so. +0x84-0x8f + - full on Changing the high nibble doesn't seem to do much except the high bit (0x80) must be set for PWM to work, else the current pwm doesn't seem to @@ -435,6 +493,7 @@ looks like PWM is filtered on this motherboard. Here are some of measurements: +==== ========= 0x80 20 mV 0x81 20 mV 0x82 232 mV @@ -451,3 +510,4 @@ Here are some of measurements: 0x8d 12.4 V 0x8e 12.4 V 0x8f 12.4 V +==== ========= diff --git a/Documentation/hwmon/w83791d b/Documentation/hwmon/w83791d.rst index f4021a285460..3adaed39b157 100644 --- a/Documentation/hwmon/w83791d +++ b/Documentation/hwmon/w83791d.rst @@ -2,9 +2,13 @@ Kernel driver w83791d ===================== Supported chips: + * Winbond W83791D + Prefix: 'w83791d' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/W83791D_W83791Gb.pdf Author: Charles Spirakis <bezaur@gmail.com> @@ -12,39 +16,46 @@ Author: Charles Spirakis <bezaur@gmail.com> This driver was derived from the w83781d.c and w83792d.c source files. Credits: + w83781d.c: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - and Mark Studebaker <mdsxyz123@yahoo.com> + + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com>, + - Mark Studebaker <mdsxyz123@yahoo.com> + w83792d.c: - Shane Huang (Winbond), - Rudolf Marek <r.marek@assembler.cz> + + - Shane Huang (Winbond), + - Rudolf Marek <r.marek@assembler.cz> Additional contributors: - Sven Anders <anders@anduras.de> - Marc Hulsman <m.hulsman@tudelft.nl> + + - Sven Anders <anders@anduras.de> + - Marc Hulsman <m.hulsman@tudelft.nl> Module Parameters ----------------- * init boolean - (default 0) - Use 'init=1' to have the driver do extra software initializations. - The default behavior is to do the minimum initialization possible - and depend on the BIOS to properly setup the chip. If you know you - have a w83791d and you're having problems, try init=1 before trying - reset=1. + (default 0) + + Use 'init=1' to have the driver do extra software initializations. + The default behavior is to do the minimum initialization possible + and depend on the BIOS to properly setup the chip. If you know you + have a w83791d and you're having problems, try init=1 before trying + reset=1. * reset boolean - (default 0) - Use 'reset=1' to reset the chip (via index 0x40, bit 7). The default - behavior is no chip reset to preserve BIOS settings. + (default 0) + + Use 'reset=1' to reset the chip (via index 0x40, bit 7). The default + behavior is no chip reset to preserve BIOS settings. * force_subclients=bus,caddr,saddr,saddr - This is used to force the i2c addresses for subclients of - a certain chip. Example usage is `force_subclients=0,0x2f,0x4a,0x4b' - to force the subclients of chip 0x2f on bus 0 to i2c addresses - 0x4a and 0x4b. + This is used to force the i2c addresses for subclients of + a certain chip. Example usage is `force_subclients=0,0x2f,0x4a,0x4b` + to force the subclients of chip 0x2f on bus 0 to i2c addresses + 0x4a and 0x4b. Description @@ -91,11 +102,11 @@ This file is used for both legacy and new code. The sysfs interface to the beep bitmask has migrated from the original legacy method of a single sysfs beep_mask file to a newer method using multiple -*_beep files as described in .../Documentation/hwmon/sysfs-interface. +`*_beep` files as described in `Documentation/hwmon/sysfs-interface.rst`. A similar change has occurred for the bitmap corresponding to the alarms. The original legacy method used a single sysfs alarms file containing a bitmap -of triggered alarms. The newer method uses multiple sysfs *_alarm files +of triggered alarms. The newer method uses multiple sysfs `*_alarm` files (again following the pattern described in sysfs-interface). Since both methods read and write the underlying hardware, they can be used @@ -116,46 +127,54 @@ User mode code requesting values more often will receive cached values. The sysfs-interface is documented in the 'sysfs-interface' file. Only chip-specific options are documented here. -pwm[1-3]_enable - this file controls mode of fan/temperature control for +======================= ======================================================= +pwm[1-3]_enable this file controls mode of fan/temperature control for fan 1-3. Fan/PWM 4-5 only support manual mode. - * 1 Manual mode - * 2 Thermal Cruise mode - * 3 Fan Speed Cruise mode (no further support) -temp[1-3]_target - defines the target temperature for Thermal Cruise mode. + * 1 Manual mode + * 2 Thermal Cruise mode + * 3 Fan Speed Cruise mode (no further support) + +temp[1-3]_target defines the target temperature for Thermal Cruise mode. Unit: millidegree Celsius RW -temp[1-3]_tolerance - temperature tolerance for Thermal Cruise mode. +temp[1-3]_tolerance temperature tolerance for Thermal Cruise mode. Specifies an interval around the target temperature in which the fan speed is not changed. Unit: millidegree Celsius RW +======================= ======================================================= Alarms bitmap vs. beep_mask bitmask ------------------------------------- +----------------------------------- + For legacy code using the alarms and beep_mask files: -in0 (VCORE) : alarms: 0x000001 beep_mask: 0x000001 -in1 (VINR0) : alarms: 0x000002 beep_mask: 0x002000 <== mismatch -in2 (+3.3VIN): alarms: 0x000004 beep_mask: 0x000004 -in3 (5VDD) : alarms: 0x000008 beep_mask: 0x000008 -in4 (+12VIN) : alarms: 0x000100 beep_mask: 0x000100 -in5 (-12VIN) : alarms: 0x000200 beep_mask: 0x000200 -in6 (-5VIN) : alarms: 0x000400 beep_mask: 0x000400 -in7 (VSB) : alarms: 0x080000 beep_mask: 0x010000 <== mismatch -in8 (VBAT) : alarms: 0x100000 beep_mask: 0x020000 <== mismatch -in9 (VINR1) : alarms: 0x004000 beep_mask: 0x004000 -temp1 : alarms: 0x000010 beep_mask: 0x000010 -temp2 : alarms: 0x000020 beep_mask: 0x000020 -temp3 : alarms: 0x002000 beep_mask: 0x000002 <== mismatch -fan1 : alarms: 0x000040 beep_mask: 0x000040 -fan2 : alarms: 0x000080 beep_mask: 0x000080 -fan3 : alarms: 0x000800 beep_mask: 0x000800 -fan4 : alarms: 0x200000 beep_mask: 0x200000 -fan5 : alarms: 0x400000 beep_mask: 0x400000 -tart1 : alarms: 0x010000 beep_mask: 0x040000 <== mismatch -tart2 : alarms: 0x020000 beep_mask: 0x080000 <== mismatch -tart3 : alarms: 0x040000 beep_mask: 0x100000 <== mismatch -case_open : alarms: 0x001000 beep_mask: 0x001000 -global_enable: alarms: -------- beep_mask: 0x800000 (modified via beep_enable) +============= ======== ========= ========================== +Signal Alarms beep_mask Obs +============= ======== ========= ========================== +in0 (VCORE) 0x000001 0x000001 +in1 (VINR0) 0x000002 0x002000 <== mismatch +in2 (+3.3VIN) 0x000004 0x000004 +in3 (5VDD) 0x000008 0x000008 +in4 (+12VIN) 0x000100 0x000100 +in5 (-12VIN) 0x000200 0x000200 +in6 (-5VIN) 0x000400 0x000400 +in7 (VSB) 0x080000 0x010000 <== mismatch +in8 (VBAT) 0x100000 0x020000 <== mismatch +in9 (VINR1) 0x004000 0x004000 +temp1 0x000010 0x000010 +temp2 0x000020 0x000020 +temp3 0x002000 0x000002 <== mismatch +fan1 0x000040 0x000040 +fan2 0x000080 0x000080 +fan3 0x000800 0x000800 +fan4 0x200000 0x200000 +fan5 0x400000 0x400000 +tart1 0x010000 0x040000 <== mismatch +tart2 0x020000 0x080000 <== mismatch +tart3 0x040000 0x100000 <== mismatch +case_open 0x001000 0x001000 +global_enable - 0x800000 (modified via beep_enable) +============= ======== ========= ========================== diff --git a/Documentation/hwmon/w83792d b/Documentation/hwmon/w83792d.rst index f2ffc402ea45..92c4bfe4968c 100644 --- a/Documentation/hwmon/w83792d +++ b/Documentation/hwmon/w83792d.rst @@ -2,9 +2,13 @@ Kernel driver w83792d ===================== Supported chips: + * Winbond W83792D + Prefix: 'w83792d' + Addresses scanned: I2C 0x2c - 0x2f + Datasheet: http://www.winbond.com.tw Author: Shane Huang (Winbond) @@ -15,15 +19,16 @@ Module Parameters ----------------- * init int - (default 1) - Use 'init=0' to bypass initializing the chip. - Try this if your computer crashes when you load the module. + (default 1) + + Use 'init=0' to bypass initializing the chip. + Try this if your computer crashes when you load the module. * force_subclients=bus,caddr,saddr,saddr - This is used to force the i2c addresses for subclients of - a certain chip. Example usage is `force_subclients=0,0x2f,0x4a,0x4b' - to force the subclients of chip 0x2f on bus 0 to i2c addresses - 0x4a and 0x4b. + This is used to force the i2c addresses for subclients of + a certain chip. Example usage is `force_subclients=0,0x2f,0x4a,0x4b` + to force the subclients of chip 0x2f on bus 0 to i2c addresses + 0x4a and 0x4b. Description @@ -67,31 +72,34 @@ or maximum limit. Alarms are provided as output from "realtime status register". Following bits are defined: -bit - alarm on: -0 - in0 -1 - in1 -2 - temp1 -3 - temp2 -4 - temp3 -5 - fan1 -6 - fan2 -7 - fan3 -8 - in2 -9 - in3 -10 - in4 -11 - in5 -12 - in6 -13 - VID change -14 - chassis -15 - fan7 -16 - tart1 -17 - tart2 -18 - tart3 -19 - in7 -20 - in8 -21 - fan4 -22 - fan5 -23 - fan6 +==== ========== +bit alarm on +==== ========== +0 in0 +1 in1 +2 temp1 +3 temp2 +4 temp3 +5 fan1 +6 fan2 +7 fan3 +8 in2 +9 in3 +10 in4 +11 in5 +12 in6 +13 VID change +14 chassis +15 fan7 +16 tart1 +17 tart2 +18 tart3 +19 in7 +20 in8 +21 fan4 +22 fan5 +23 fan6 +==== ========== Tart will be asserted while target temperature cannot be achieved after 3 minutes of full speed rotation of corresponding fan. @@ -114,7 +122,7 @@ Known problems: by CR[0x49h]. - The function of vid and vrm has not been finished, because I'm NOT very familiar with them. Adding support is welcome. - - The function of chassis open detection needs more tests. + - The function of chassis open detection needs more tests. - If you have ASUS server board and chip was not found: Then you will need to upgrade to latest (or beta) BIOS. If it does not help please contact us. @@ -165,17 +173,27 @@ for each fan. /sys files ---------- -pwm[1-7] - this file stores PWM duty cycle or DC value (fan speed) in range: - 0 (stop) to 255 (full) -pwm[1-3]_enable - this file controls mode of fan/temperature control: - * 0 Disabled - * 1 Manual mode - * 2 Smart Fan II - * 3 Thermal Cruise -pwm[1-7]_mode - Select PWM or DC mode - * 0 DC - * 1 PWM -thermal_cruise[1-3] - Selects the desired temperature for cruise (degC) -tolerance[1-3] - Value in degrees of Celsius (degC) for +- T -sf2_point[1-4]_fan[1-3] - four temperature points for each fan for Smart Fan II -sf2_level[1-3]_fan[1-3] - three PWM/DC levels for each fan for Smart Fan II +pwm[1-7] + - this file stores PWM duty cycle or DC value (fan speed) in range: + + 0 (stop) to 255 (full) +pwm[1-3]_enable + - this file controls mode of fan/temperature control: + + * 0 Disabled + * 1 Manual mode + * 2 Smart Fan II + * 3 Thermal Cruise +pwm[1-7]_mode + - Select PWM or DC mode + + * 0 DC + * 1 PWM +thermal_cruise[1-3] + - Selects the desired temperature for cruise (degC) +tolerance[1-3] + - Value in degrees of Celsius (degC) for +- T +sf2_point[1-4]_fan[1-3] + - four temperature points for each fan for Smart Fan II +sf2_level[1-3]_fan[1-3] + - three PWM/DC levels for each fan for Smart Fan II diff --git a/Documentation/hwmon/w83793 b/Documentation/hwmon/w83793 deleted file mode 100644 index 6cc5f639b721..000000000000 --- a/Documentation/hwmon/w83793 +++ /dev/null @@ -1,106 +0,0 @@ -Kernel driver w83793 -==================== - -Supported chips: - * Winbond W83793G/W83793R - Prefix: 'w83793' - Addresses scanned: I2C 0x2c - 0x2f - Datasheet: Still not published - -Authors: - Yuan Mu (Winbond Electronics) - Rudolf Marek <r.marek@assembler.cz> - - -Module parameters ------------------ - -* reset int - (default 0) - This parameter is not recommended, it will lose motherboard specific - settings. Use 'reset=1' to reset the chip when loading this module. - -* force_subclients=bus,caddr,saddr1,saddr2 - This is used to force the i2c addresses for subclients of - a certain chip. Typical usage is `force_subclients=0,0x2f,0x4a,0x4b' - to force the subclients of chip 0x2f on bus 0 to i2c addresses - 0x4a and 0x4b. - - -Description ------------ - -This driver implements support for Winbond W83793G/W83793R chips. - -* Exported features - This driver exports 10 voltage sensors, up to 12 fan tachometer inputs, - 6 remote temperatures, up to 8 sets of PWM fan controls, SmartFan - (automatic fan speed control) on all temperature/PWM combinations, 2 - sets of 6-pin CPU VID input. - -* Sensor resolutions - If your motherboard maker used the reference design, the resolution of - voltage0-2 is 2mV, resolution of voltage3/4/5 is 16mV, 8mV for voltage6, - 24mV for voltage7/8. Temp1-4 have a 0.25 degree Celsius resolution, - temp5-6 have a 1 degree Celsiis resolution. - -* Temperature sensor types - Temp1-4 have 2 possible types. It can be read from (and written to) - temp[1-4]_type. - - If the value is 3, it starts monitoring using a remote termal diode - (default). - - If the value is 6, it starts monitoring using the temperature sensor - in Intel CPU and get result by PECI. - Temp5-6 can be connected to external thermistors (value of - temp[5-6]_type is 4). - -* Alarm mechanism - For voltage sensors, an alarm triggers if the measured value is below - the low voltage limit or over the high voltage limit. - For temperature sensors, an alarm triggers if the measured value goes - above the high temperature limit, and wears off only after the measured - value drops below the hysteresis value. - For fan sensors, an alarm triggers if the measured value is below the - low speed limit. - -* SmartFan/PWM control - If you want to set a pwm fan to manual mode, you just need to make sure it - is not controlled by any temp channel, for example, you want to set fan1 - to manual mode, you need to check the value of temp[1-6]_fan_map, make - sure bit 0 is cleared in the 6 values. And then set the pwm1 value to - control the fan. - - Each temperature channel can control all the 8 PWM outputs (by setting the - corresponding bit in tempX_fan_map), you can set the temperature channel - mode using temp[1-6]_pwm_enable, 2 is Thermal Cruise mode and 3 - is the SmartFanII mode. Temperature channels will try to speed up or - slow down all controlled fans, this means one fan can receive different - PWM value requests from different temperature channels, but the chip - will always pick the safest (max) PWM value for each fan. - - In Thermal Cruise mode, the chip attempts to keep the temperature at a - predefined value, within a tolerance margin. So if tempX_input > - thermal_cruiseX + toleranceX, the chip will increase the PWM value, - if tempX_input < thermal_cruiseX - toleranceX, the chip will decrease - the PWM value. If the temperature is within the tolerance range, the PWM - value is left unchanged. - - SmartFanII works differently, you have to define up to 7 PWM, temperature - trip points, defining a PWM/temperature curve which the chip will follow. - While not fundamentally different from the Thermal Cruise mode, the - implementation is quite different, giving you a finer-grained control. - -* Chassis - If the case open alarm triggers, it will stay in this state unless cleared - by writing 0 to the sysfs file "intrusion0_alarm". - -* VID and VRM - The VRM version is detected automatically, don't modify the it unless you - *do* know the cpu VRM version and it's not properly detected. - - -Notes ------ - - Only Fan1-5 and PWM1-3 are guaranteed to always exist, other fan inputs and - PWM outputs may or may not exist depending on the chip pin configuration. diff --git a/Documentation/hwmon/w83793.rst b/Documentation/hwmon/w83793.rst new file mode 100644 index 000000000000..83bb40c48645 --- /dev/null +++ b/Documentation/hwmon/w83793.rst @@ -0,0 +1,113 @@ +Kernel driver w83793 +==================== + +Supported chips: + + * Winbond W83793G/W83793R + + Prefix: 'w83793' + + Addresses scanned: I2C 0x2c - 0x2f + + Datasheet: Still not published + +Authors: + - Yuan Mu (Winbond Electronics) + - Rudolf Marek <r.marek@assembler.cz> + + +Module parameters +----------------- + +* reset int + (default 0) + + This parameter is not recommended, it will lose motherboard specific + settings. Use 'reset=1' to reset the chip when loading this module. + +* force_subclients=bus,caddr,saddr1,saddr2 + This is used to force the i2c addresses for subclients of + a certain chip. Typical usage is `force_subclients=0,0x2f,0x4a,0x4b` + to force the subclients of chip 0x2f on bus 0 to i2c addresses + 0x4a and 0x4b. + + +Description +----------- + +This driver implements support for Winbond W83793G/W83793R chips. + +* Exported features + This driver exports 10 voltage sensors, up to 12 fan tachometer inputs, + 6 remote temperatures, up to 8 sets of PWM fan controls, SmartFan + (automatic fan speed control) on all temperature/PWM combinations, 2 + sets of 6-pin CPU VID input. + +* Sensor resolutions + If your motherboard maker used the reference design, the resolution of + voltage0-2 is 2mV, resolution of voltage3/4/5 is 16mV, 8mV for voltage6, + 24mV for voltage7/8. Temp1-4 have a 0.25 degree Celsius resolution, + temp5-6 have a 1 degree Celsiis resolution. + +* Temperature sensor types + Temp1-4 have 2 possible types. It can be read from (and written to) + temp[1-4]_type. + + - If the value is 3, it starts monitoring using a remote termal diode + (default). + - If the value is 6, it starts monitoring using the temperature sensor + in Intel CPU and get result by PECI. + + Temp5-6 can be connected to external thermistors (value of + temp[5-6]_type is 4). + +* Alarm mechanism + For voltage sensors, an alarm triggers if the measured value is below + the low voltage limit or over the high voltage limit. + For temperature sensors, an alarm triggers if the measured value goes + above the high temperature limit, and wears off only after the measured + value drops below the hysteresis value. + For fan sensors, an alarm triggers if the measured value is below the + low speed limit. + +* SmartFan/PWM control + If you want to set a pwm fan to manual mode, you just need to make sure it + is not controlled by any temp channel, for example, you want to set fan1 + to manual mode, you need to check the value of temp[1-6]_fan_map, make + sure bit 0 is cleared in the 6 values. And then set the pwm1 value to + control the fan. + + Each temperature channel can control all the 8 PWM outputs (by setting the + corresponding bit in tempX_fan_map), you can set the temperature channel + mode using temp[1-6]_pwm_enable, 2 is Thermal Cruise mode and 3 + is the SmartFanII mode. Temperature channels will try to speed up or + slow down all controlled fans, this means one fan can receive different + PWM value requests from different temperature channels, but the chip + will always pick the safest (max) PWM value for each fan. + + In Thermal Cruise mode, the chip attempts to keep the temperature at a + predefined value, within a tolerance margin. So if tempX_input > + thermal_cruiseX + toleranceX, the chip will increase the PWM value, + if tempX_input < thermal_cruiseX - toleranceX, the chip will decrease + the PWM value. If the temperature is within the tolerance range, the PWM + value is left unchanged. + + SmartFanII works differently, you have to define up to 7 PWM, temperature + trip points, defining a PWM/temperature curve which the chip will follow. + While not fundamentally different from the Thermal Cruise mode, the + implementation is quite different, giving you a finer-grained control. + +* Chassis + If the case open alarm triggers, it will stay in this state unless cleared + by writing 0 to the sysfs file "intrusion0_alarm". + +* VID and VRM + The VRM version is detected automatically, don't modify the it unless you + *do* know the cpu VRM version and it's not properly detected. + + +Notes +----- + + Only Fan1-5 and PWM1-3 are guaranteed to always exist, other fan inputs and + PWM outputs may or may not exist depending on the chip pin configuration. diff --git a/Documentation/hwmon/w83795 b/Documentation/hwmon/w83795 deleted file mode 100644 index d3e678216b9a..000000000000 --- a/Documentation/hwmon/w83795 +++ /dev/null @@ -1,127 +0,0 @@ -Kernel driver w83795 -==================== - -Supported chips: - * Winbond/Nuvoton W83795G - Prefix: 'w83795g' - Addresses scanned: I2C 0x2c - 0x2f - Datasheet: Available for download on nuvoton.com - * Winbond/Nuvoton W83795ADG - Prefix: 'w83795adg' - Addresses scanned: I2C 0x2c - 0x2f - Datasheet: Available for download on nuvoton.com - -Authors: - Wei Song (Nuvoton) - Jean Delvare <jdelvare@suse.de> - - -Pin mapping ------------ - -Here is a summary of the pin mapping for the W83795G and W83795ADG. -This can be useful to convert data provided by board manufacturers -into working libsensors configuration statements. - - W83795G | - Pin | Name | Register | Sysfs attribute ------------------------------------------------------------------- - 13 | VSEN1 (VCORE1) | 10h | in0 - 14 | VSEN2 (VCORE2) | 11h | in1 - 15 | VSEN3 (VCORE3) | 12h | in2 - 16 | VSEN4 | 13h | in3 - 17 | VSEN5 | 14h | in4 - 18 | VSEN6 | 15h | in5 - 19 | VSEN7 | 16h | in6 - 20 | VSEN8 | 17h | in7 - 21 | VSEN9 | 18h | in8 - 22 | VSEN10 | 19h | in9 - 23 | VSEN11 | 1Ah | in10 - 28 | VTT | 1Bh | in11 - 24 | 3VDD | 1Ch | in12 - 25 | 3VSB | 1Dh | in13 - 26 | VBAT | 1Eh | in14 - 3 | VSEN12/TR5 | 1Fh | in15/temp5 - 4 | VSEN13/TR5 | 20h | in16/temp6 - 5/ 6 | VDSEN14/TR1/TD1 | 21h | in17/temp1 - 7/ 8 | VDSEN15/TR2/TD2 | 22h | in18/temp2 - 9/ 10 | VDSEN16/TR3/TD3 | 23h | in19/temp3 - 11/ 12 | VDSEN17/TR4/TD4 | 24h | in20/temp4 - 40 | FANIN1 | 2Eh | fan1 - 42 | FANIN2 | 2Fh | fan2 - 44 | FANIN3 | 30h | fan3 - 46 | FANIN4 | 31h | fan4 - 48 | FANIN5 | 32h | fan5 - 50 | FANIN6 | 33h | fan6 - 52 | FANIN7 | 34h | fan7 - 54 | FANIN8 | 35h | fan8 - 57 | FANIN9 | 36h | fan9 - 58 | FANIN10 | 37h | fan10 - 59 | FANIN11 | 38h | fan11 - 60 | FANIN12 | 39h | fan12 - 31 | FANIN13 | 3Ah | fan13 - 35 | FANIN14 | 3Bh | fan14 - 41 | FANCTL1 | 10h (bank 2) | pwm1 - 43 | FANCTL2 | 11h (bank 2) | pwm2 - 45 | FANCTL3 | 12h (bank 2) | pwm3 - 47 | FANCTL4 | 13h (bank 2) | pwm4 - 49 | FANCTL5 | 14h (bank 2) | pwm5 - 51 | FANCTL6 | 15h (bank 2) | pwm6 - 53 | FANCTL7 | 16h (bank 2) | pwm7 - 55 | FANCTL8 | 17h (bank 2) | pwm8 - 29/ 30 | PECI/TSI (DTS1) | 26h | temp7 - 29/ 30 | PECI/TSI (DTS2) | 27h | temp8 - 29/ 30 | PECI/TSI (DTS3) | 28h | temp9 - 29/ 30 | PECI/TSI (DTS4) | 29h | temp10 - 29/ 30 | PECI/TSI (DTS5) | 2Ah | temp11 - 29/ 30 | PECI/TSI (DTS6) | 2Bh | temp12 - 29/ 30 | PECI/TSI (DTS7) | 2Ch | temp13 - 29/ 30 | PECI/TSI (DTS8) | 2Dh | temp14 - 27 | CASEOPEN# | 46h | intrusion0 - - W83795ADG | - Pin | Name | Register | Sysfs attribute ------------------------------------------------------------------- - 10 | VSEN1 (VCORE1) | 10h | in0 - 11 | VSEN2 (VCORE2) | 11h | in1 - 12 | VSEN3 (VCORE3) | 12h | in2 - 13 | VSEN4 | 13h | in3 - 14 | VSEN5 | 14h | in4 - 15 | VSEN6 | 15h | in5 - 16 | VSEN7 | 16h | in6 - 17 | VSEN8 | 17h | in7 - 22 | VTT | 1Bh | in11 - 18 | 3VDD | 1Ch | in12 - 19 | 3VSB | 1Dh | in13 - 20 | VBAT | 1Eh | in14 - 48 | VSEN12/TR5 | 1Fh | in15/temp5 - 1 | VSEN13/TR5 | 20h | in16/temp6 - 2/ 3 | VDSEN14/TR1/TD1 | 21h | in17/temp1 - 4/ 5 | VDSEN15/TR2/TD2 | 22h | in18/temp2 - 6/ 7 | VDSEN16/TR3/TD3 | 23h | in19/temp3 - 8/ 9 | VDSEN17/TR4/TD4 | 24h | in20/temp4 - 32 | FANIN1 | 2Eh | fan1 - 34 | FANIN2 | 2Fh | fan2 - 36 | FANIN3 | 30h | fan3 - 37 | FANIN4 | 31h | fan4 - 38 | FANIN5 | 32h | fan5 - 39 | FANIN6 | 33h | fan6 - 40 | FANIN7 | 34h | fan7 - 41 | FANIN8 | 35h | fan8 - 43 | FANIN9 | 36h | fan9 - 44 | FANIN10 | 37h | fan10 - 45 | FANIN11 | 38h | fan11 - 46 | FANIN12 | 39h | fan12 - 24 | FANIN13 | 3Ah | fan13 - 28 | FANIN14 | 3Bh | fan14 - 33 | FANCTL1 | 10h (bank 2) | pwm1 - 35 | FANCTL2 | 11h (bank 2) | pwm2 - 23 | PECI (DTS1) | 26h | temp7 - 23 | PECI (DTS2) | 27h | temp8 - 23 | PECI (DTS3) | 28h | temp9 - 23 | PECI (DTS4) | 29h | temp10 - 23 | PECI (DTS5) | 2Ah | temp11 - 23 | PECI (DTS6) | 2Bh | temp12 - 23 | PECI (DTS7) | 2Ch | temp13 - 23 | PECI (DTS8) | 2Dh | temp14 - 21 | CASEOPEN# | 46h | intrusion0 diff --git a/Documentation/hwmon/w83795.rst b/Documentation/hwmon/w83795.rst new file mode 100644 index 000000000000..d0615e2fabb9 --- /dev/null +++ b/Documentation/hwmon/w83795.rst @@ -0,0 +1,142 @@ +Kernel driver w83795 +==================== + +Supported chips: + + * Winbond/Nuvoton W83795G + + Prefix: 'w83795g' + + Addresses scanned: I2C 0x2c - 0x2f + + Datasheet: Available for download on nuvoton.com + + * Winbond/Nuvoton W83795ADG + + Prefix: 'w83795adg' + + Addresses scanned: I2C 0x2c - 0x2f + + Datasheet: Available for download on nuvoton.com + +Authors: + - Wei Song (Nuvoton) + - Jean Delvare <jdelvare@suse.de> + + +Pin mapping +----------- + +Here is a summary of the pin mapping for the W83795G and W83795ADG. +This can be useful to convert data provided by board manufacturers +into working libsensors configuration statements. + + +- W83795G + +========= ======================= =============== ================ +Pin Name Register Sysfs attribute +========= ======================= =============== ================ + 13 VSEN1 (VCORE1) 10h in0 + 14 VSEN2 (VCORE2) 11h in1 + 15 VSEN3 (VCORE3) 12h in2 + 16 VSEN4 13h in3 + 17 VSEN5 14h in4 + 18 VSEN6 15h in5 + 19 VSEN7 16h in6 + 20 VSEN8 17h in7 + 21 VSEN9 18h in8 + 22 VSEN10 19h in9 + 23 VSEN11 1Ah in10 + 28 VTT 1Bh in11 + 24 3VDD 1Ch in12 + 25 3VSB 1Dh in13 + 26 VBAT 1Eh in14 + 3 VSEN12/TR5 1Fh in15/temp5 + 4 VSEN13/TR5 20h in16/temp6 + 5/ 6 VDSEN14/TR1/TD1 21h in17/temp1 + 7/ 8 VDSEN15/TR2/TD2 22h in18/temp2 + 9/ 10 VDSEN16/TR3/TD3 23h in19/temp3 + 11/ 12 VDSEN17/TR4/TD4 24h in20/temp4 + 40 FANIN1 2Eh fan1 + 42 FANIN2 2Fh fan2 + 44 FANIN3 30h fan3 + 46 FANIN4 31h fan4 + 48 FANIN5 32h fan5 + 50 FANIN6 33h fan6 + 52 FANIN7 34h fan7 + 54 FANIN8 35h fan8 + 57 FANIN9 36h fan9 + 58 FANIN10 37h fan10 + 59 FANIN11 38h fan11 + 60 FANIN12 39h fan12 + 31 FANIN13 3Ah fan13 + 35 FANIN14 3Bh fan14 + 41 FANCTL1 10h (bank 2) pwm1 + 43 FANCTL2 11h (bank 2) pwm2 + 45 FANCTL3 12h (bank 2) pwm3 + 47 FANCTL4 13h (bank 2) pwm4 + 49 FANCTL5 14h (bank 2) pwm5 + 51 FANCTL6 15h (bank 2) pwm6 + 53 FANCTL7 16h (bank 2) pwm7 + 55 FANCTL8 17h (bank 2) pwm8 + 29/ 30 PECI/TSI (DTS1) 26h temp7 + 29/ 30 PECI/TSI (DTS2) 27h temp8 + 29/ 30 PECI/TSI (DTS3) 28h temp9 + 29/ 30 PECI/TSI (DTS4) 29h temp10 + 29/ 30 PECI/TSI (DTS5) 2Ah temp11 + 29/ 30 PECI/TSI (DTS6) 2Bh temp12 + 29/ 30 PECI/TSI (DTS7) 2Ch temp13 + 29/ 30 PECI/TSI (DTS8) 2Dh temp14 + 27 CASEOPEN# 46h intrusion0 +========= ======================= =============== ================ + +- W83795ADG + +========= ======================= =============== ================ +Pin Name Register Sysfs attribute +========= ======================= =============== ================ + 10 VSEN1 (VCORE1) 10h in0 + 11 VSEN2 (VCORE2) 11h in1 + 12 VSEN3 (VCORE3) 12h in2 + 13 VSEN4 13h in3 + 14 VSEN5 14h in4 + 15 VSEN6 15h in5 + 16 VSEN7 16h in6 + 17 VSEN8 17h in7 + 22 VTT 1Bh in11 + 18 3VDD 1Ch in12 + 19 3VSB 1Dh in13 + 20 VBAT 1Eh in14 + 48 VSEN12/TR5 1Fh in15/temp5 + 1 VSEN13/TR5 20h in16/temp6 + 2/ 3 VDSEN14/TR1/TD1 21h in17/temp1 + 4/ 5 VDSEN15/TR2/TD2 22h in18/temp2 + 6/ 7 VDSEN16/TR3/TD3 23h in19/temp3 + 8/ 9 VDSEN17/TR4/TD4 24h in20/temp4 + 32 FANIN1 2Eh fan1 + 34 FANIN2 2Fh fan2 + 36 FANIN3 30h fan3 + 37 FANIN4 31h fan4 + 38 FANIN5 32h fan5 + 39 FANIN6 33h fan6 + 40 FANIN7 34h fan7 + 41 FANIN8 35h fan8 + 43 FANIN9 36h fan9 + 44 FANIN10 37h fan10 + 45 FANIN11 38h fan11 + 46 FANIN12 39h fan12 + 24 FANIN13 3Ah fan13 + 28 FANIN14 3Bh fan14 + 33 FANCTL1 10h (bank 2) pwm1 + 35 FANCTL2 11h (bank 2) pwm2 + 23 PECI (DTS1) 26h temp7 + 23 PECI (DTS2) 27h temp8 + 23 PECI (DTS3) 28h temp9 + 23 PECI (DTS4) 29h temp10 + 23 PECI (DTS5) 2Ah temp11 + 23 PECI (DTS6) 2Bh temp12 + 23 PECI (DTS7) 2Ch temp13 + 23 PECI (DTS8) 2Dh temp14 + 21 CASEOPEN# 46h intrusion0 +========= ======================= =============== ================ diff --git a/Documentation/hwmon/w83l785ts b/Documentation/hwmon/w83l785ts.rst index c8978478871f..7fa5418fed11 100644 --- a/Documentation/hwmon/w83l785ts +++ b/Documentation/hwmon/w83l785ts.rst @@ -2,14 +2,19 @@ Kernel driver w83l785ts ======================= Supported chips: + * Winbond W83L785TS-S + Prefix: 'w83l785ts' + Addresses scanned: I2C 0x2e + Datasheet: Publicly available at the Winbond USA website - http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/W83L785TS-S.pdf + + http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/W83L785TS-S.pdf Authors: - Jean Delvare <jdelvare@suse.de> + Jean Delvare <jdelvare@suse.de> Description ----------- diff --git a/Documentation/hwmon/w83l786ng b/Documentation/hwmon/w83l786ng.rst index d8f55d7fff10..2b7776190de3 100644 --- a/Documentation/hwmon/w83l786ng +++ b/Documentation/hwmon/w83l786ng.rst @@ -1,10 +1,14 @@ Kernel driver w83l786ng -===================== +======================= Supported chips: + * Winbond W83L786NG/W83L786NR + Prefix: 'w83l786ng' + Addresses scanned: I2C 0x2e - 0x2f + Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/W83L786NRNG09.pdf Author: Kevin Lo <kevlo@kevlo.org> @@ -14,9 +18,10 @@ Module Parameters ----------------- * reset boolean - (default 0) - Use 'reset=1' to reset the chip (via index 0x40, bit 7). The default - behavior is no chip reset to preserve BIOS settings + (default 0) + + Use 'reset=1' to reset the chip (via index 0x40, bit 7). The default + behavior is no chip reset to preserve BIOS settings Description @@ -41,14 +46,21 @@ or maximum limit. /sys files ---------- -pwm[1-2] - this file stores PWM duty cycle or DC value (fan speed) in range: - 0 (stop) to 255 (full) -pwm[1-2]_enable - this file controls mode of fan/temperature control: - * 0 Manual Mode - * 1 Thermal Cruise - * 2 Smart Fan II - * 4 FAN_SET -pwm[1-2]_mode - Select PWM of DC mode - * 0 DC - * 1 PWM -tolerance[1-2] - Value in degrees of Celsius (degC) for +- T +pwm[1-2] + - this file stores PWM duty cycle or DC value (fan speed) in range: + + 0 (stop) to 255 (full) +pwm[1-2]_enable + - this file controls mode of fan/temperature control: + + * 0 Manual Mode + * 1 Thermal Cruise + * 2 Smart Fan II + * 4 FAN_SET +pwm[1-2]_mode + - Select PWM of DC mode + + * 0 DC + * 1 PWM +tolerance[1-2] + - Value in degrees of Celsius (degC) for +- T diff --git a/Documentation/hwmon/wm831x b/Documentation/hwmon/wm831x.rst index 11446757c8c8..c56fb35a2fb3 100644 --- a/Documentation/hwmon/wm831x +++ b/Documentation/hwmon/wm831x.rst @@ -3,11 +3,14 @@ Kernel driver wm831x-hwmon Supported chips: * Wolfson Microelectronics WM831x PMICs + Prefix: 'wm831x' + Datasheet: - http://www.wolfsonmicro.com/products/WM8310 - http://www.wolfsonmicro.com/products/WM8311 - http://www.wolfsonmicro.com/products/WM8312 + + - http://www.wolfsonmicro.com/products/WM8310 + - http://www.wolfsonmicro.com/products/WM8311 + - http://www.wolfsonmicro.com/products/WM8312 Authors: Mark Brown <broonie@opensource.wolfsonmicro.com> diff --git a/Documentation/hwmon/wm8350 b/Documentation/hwmon/wm8350.rst index 98f923bd2e92..cec044ca5900 100644 --- a/Documentation/hwmon/wm8350 +++ b/Documentation/hwmon/wm8350.rst @@ -2,12 +2,16 @@ Kernel driver wm8350-hwmon ========================== Supported chips: + * Wolfson Microelectronics WM835x PMICs + Prefix: 'wm8350' + Datasheet: - http://www.wolfsonmicro.com/products/WM8350 - http://www.wolfsonmicro.com/products/WM8351 - http://www.wolfsonmicro.com/products/WM8352 + + - http://www.wolfsonmicro.com/products/WM8350 + - http://www.wolfsonmicro.com/products/WM8351 + - http://www.wolfsonmicro.com/products/WM8352 Authors: Mark Brown <broonie@opensource.wolfsonmicro.com> diff --git a/Documentation/hwmon/xgene-hwmon b/Documentation/hwmon/xgene-hwmon.rst index 6ec50ed7cc8f..439b30b881b6 100644 --- a/Documentation/hwmon/xgene-hwmon +++ b/Documentation/hwmon/xgene-hwmon.rst @@ -1,7 +1,8 @@ Kernel driver xgene-hwmon -======================== +========================= Supported chips: + * APM X-Gene SoC Description @@ -15,16 +16,21 @@ For ACPI, it is the PCC mailbox. The following sensors are supported * Temperature - - SoC on-die temperature in milli-degree C - - Alarm when high/over temperature occurs + - SoC on-die temperature in milli-degree C + - Alarm when high/over temperature occurs + * Power - - CPU power in uW - - IO power in uW + - CPU power in uW + - IO power in uW sysfs-Interface --------------- -temp0_input - SoC on-die temperature (milli-degree C) -temp0_critical_alarm - An 1 would indicates on-die temperature exceeded threshold -power0_input - CPU power in (uW) -power1_input - IO power in (uW) +temp0_input + - SoC on-die temperature (milli-degree C) +temp0_critical_alarm + - An 1 would indicates on-die temperature exceeded threshold +power0_input + - CPU power in (uW) +power1_input + - IO power in (uW) diff --git a/Documentation/hwmon/zl6100 b/Documentation/hwmon/zl6100.rst index 477a94b131ae..41513bb7fe51 100644 --- a/Documentation/hwmon/zl6100 +++ b/Documentation/hwmon/zl6100.rst @@ -2,57 +2,106 @@ Kernel driver zl6100 ==================== Supported chips: + * Intersil / Zilker Labs ZL2004 + Prefix: 'zl2004' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6847.pdf + * Intersil / Zilker Labs ZL2005 + Prefix: 'zl2005' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6848.pdf + * Intersil / Zilker Labs ZL2006 + Prefix: 'zl2006' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6850.pdf + * Intersil / Zilker Labs ZL2008 + Prefix: 'zl2008' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6859.pdf + * Intersil / Zilker Labs ZL2105 + Prefix: 'zl2105' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6851.pdf + * Intersil / Zilker Labs ZL2106 + Prefix: 'zl2106' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6852.pdf + * Intersil / Zilker Labs ZL6100 + Prefix: 'zl6100' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6876.pdf + * Intersil / Zilker Labs ZL6105 + Prefix: 'zl6105' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn6906.pdf + * Intersil / Zilker Labs ZL9101M + Prefix: 'zl9101' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn7669.pdf + * Intersil / Zilker Labs ZL9117M + Prefix: 'zl9117' + Addresses scanned: - + Datasheet: http://www.intersil.com/data/fn/fn7914.pdf + * Ericsson BMR450, BMR451 + Prefix: 'bmr450', 'bmr451' + Addresses scanned: - + Datasheet: + http://archive.ericsson.net/service/internet/picov/get?DocNo=28701-EN/LZT146401 + * Ericsson BMR462, BMR463, BMR464 + Prefixes: 'bmr462', 'bmr463', 'bmr464' + Addresses scanned: - + Datasheet: -http://archive.ericsson.net/service/internet/picov/get?DocNo=28701-EN/LZT146256 + http://archive.ericsson.net/service/internet/picov/get?DocNo=28701-EN/LZT146256 Author: Guenter Roeck <linux@roeck-us.net> @@ -64,7 +113,7 @@ This driver supports hardware monitoring for Intersil / Zilker Labs ZL6100 and compatible digital DC-DC controllers. The driver is a client driver to the core PMBus driver. Please see -Documentation/hwmon/pmbus and Documentation.hwmon/pmbus-core for details +Documentation/hwmon/pmbus.rst and Documentation.hwmon/pmbus-core for details on PMBus client drivers. @@ -75,13 +124,15 @@ This driver does not auto-detect devices. You will have to instantiate the devices explicitly. Please see Documentation/i2c/instantiating-devices for details. -WARNING: Do not access chip registers using the i2cdump command, and do not use -any of the i2ctools commands on a command register used to save and restore -configuration data (0x11, 0x12, 0x15, 0x16, and 0xf4). The chips supported by -this driver interpret any access to those command registers (including read -commands) as request to execute the command in question. Unless write accesses -to those registers are protected, this may result in power loss, board resets, -and/or Flash corruption. Worst case, your board may turn into a brick. +.. warning:: + + Do not access chip registers using the i2cdump command, and do not use + any of the i2ctools commands on a command register used to save and restore + configuration data (0x11, 0x12, 0x15, 0x16, and 0xf4). The chips supported by + this driver interpret any access to those command registers (including read + commands) as request to execute the command in question. Unless write accesses + to those registers are protected, this may result in power loss, board resets, + and/or Flash corruption. Worst case, your board may turn into a brick. Platform data support @@ -110,6 +161,7 @@ Sysfs entries The following attributes are supported. Limits are read-write; all other attributes are read-only. +======================= ======================================================== in1_label "vin" in1_input Measured input voltage. in1_min Minimum input voltage. @@ -158,3 +210,4 @@ temp[12]_min_alarm Chip temperature low alarm. temp[12]_max_alarm Chip temperature high alarm. temp[12]_lcrit_alarm Chip temperature critical low alarm. temp[12]_crit_alarm Chip temperature critical high alarm. +======================= ======================================================== diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2 new file mode 100644 index 000000000000..6571487171f4 --- /dev/null +++ b/Documentation/i2c/busses/i2c-amd-mp2 @@ -0,0 +1,23 @@ +Kernel driver i2c-amd-mp2 + +Supported adapters: + * AMD MP2 PCIe interface + +Datasheet: not publicly available. + +Authors: + Shyam Sundar S K <Shyam-sundar.S-k@amd.com> + Nehal Shah <nehal-bakulchandra.shah@amd.com> + Elie Morisse <syniurge@gmail.com> + +Description +----------- + +The MP2 is an ARM processor programmed as an I2C controller and communicating +with the x86 host through PCI. + +If you see something like this: + +03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 + +in your 'lspci -v', then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4 index aa959fd22450..2703bc3acad0 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4 @@ -15,6 +15,8 @@ Supported adapters: http://support.amd.com/us/Embedded_TechDocs/44413.pdf * AMD Hudson-2, ML, CZ Datasheet: Not publicly available + * Hygon CZ + Datasheet: Not publicly available * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge Datasheet: Publicly available at the SMSC website http://www.smsc.com diff --git a/Documentation/index.rst b/Documentation/index.rst index fdfa85c56a50..a7566ef62411 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -93,6 +93,7 @@ needed). media/index networking/index input/index + hwmon/index gpu/index security/index sound/index @@ -111,7 +112,9 @@ implementation. .. toctree:: :maxdepth: 2 + x86/index sh/index + x86/index Filesystem Documentation ------------------------ diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt index 8a3830b39c7d..9c230ea71963 100644 --- a/Documentation/kbuild/kbuild.txt +++ b/Documentation/kbuild/kbuild.txt @@ -11,6 +11,11 @@ modules.builtin This file lists all modules that are built into the kernel. This is used by modprobe to not fail when trying to load something builtin. +modules.builtin.modinfo +-------------------------------------------------- +This file contains modinfo from all modules that are built into the kernel. +Unlike modinfo of a separate module, all fields are prefixed with module name. + Environment variables diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index ee60e519438a..8baab8832c5b 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -321,6 +321,7 @@ architectures: - ppc - mips - s390 +- parisc Configuring Kprobes =================== diff --git a/Documentation/livepatch/callbacks.txt b/Documentation/livepatch/callbacks.rst index 182e31d4abce..470944aa8658 100644 --- a/Documentation/livepatch/callbacks.txt +++ b/Documentation/livepatch/callbacks.rst @@ -4,7 +4,7 @@ Livepatch (un)patch-callbacks provide a mechanism for livepatch modules to execute callback functions when a kernel object is (un)patched. They -can be considered a "power feature" that extends livepatching abilities +can be considered a **power feature** that **extends livepatching abilities** to include: - Safe updates to global data @@ -17,6 +17,9 @@ In most cases, (un)patch callbacks will need to be used in conjunction with memory barriers and kernel synchronization primitives, like mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues. +1. Motivation +============= + Callbacks differ from existing kernel facilities: - Module init/exit code doesn't run when disabling and re-enabling a @@ -28,21 +31,31 @@ Callbacks are part of the klp_object structure and their implementation is specific to that klp_object. Other livepatch objects may or may not be patched, irrespective of the target klp_object's current state. +2. Callback types +================= + Callbacks can be registered for the following livepatch actions: - * Pre-patch - before a klp_object is patched + * Pre-patch + - before a klp_object is patched - * Post-patch - after a klp_object has been patched and is active + * Post-patch + - after a klp_object has been patched and is active across all tasks - * Pre-unpatch - before a klp_object is unpatched (ie, patched code is + * Pre-unpatch + - before a klp_object is unpatched (ie, patched code is active), used to clean up post-patch callback resources - * Post-unpatch - after a klp_object has been patched, all code has + * Post-unpatch + - after a klp_object has been patched, all code has been restored and no tasks are running patched code, used to cleanup pre-patch callback resources +3. How it works +=============== + Each callback is optional, omitting one does not preclude specifying any other. However, the livepatching core executes the handlers in symmetry: pre-patch callbacks have a post-unpatch counterpart and @@ -86,11 +99,14 @@ If the object did successfully patch, but the patch transition never started for some reason (e.g., if another object failed to patch), only the post-unpatch callback will be called. +4. Use cases +============ -Example Use-cases -================= +Sample livepatch modules demonstrating the callback API can be found in +samples/livepatch/ directory. These samples were modified for use in +kselftests and can be found in the lib/livepatch directory. -Update global data +Global data update ------------------ A pre-patch callback can be useful to update a global variable. For @@ -103,24 +119,15 @@ patch the data *after* patching is complete with a post-patch callback, so that tcp_send_challenge_ack() could first be changed to read sysctl_tcp_challenge_ack_limit with READ_ONCE. - -Support __init and probe function patches +__init and probe function patches support ----------------------------------------- Although __init and probe functions are not directly livepatch-able, it may be possible to implement similar updates via pre/post-patch callbacks. -48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that +The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that virtnet_probe() initialized its driver's net_device features. A pre/post-patch callback could iterate over all such devices, making a similar change to their hw_features value. (Client functions of the value may need to be updated accordingly.) - - -Other Examples -============== - -Sample livepatch modules demonstrating the callback API can be found in -samples/livepatch/ directory. These samples were modified for use in -kselftests and can be found in the lib/livepatch directory. diff --git a/Documentation/livepatch/cumulative-patches.txt b/Documentation/livepatch/cumulative-patches.rst index 0012808e8d44..1931f318976a 100644 --- a/Documentation/livepatch/cumulative-patches.txt +++ b/Documentation/livepatch/cumulative-patches.rst @@ -18,7 +18,7 @@ Usage ----- The atomic replace can be enabled by setting "replace" flag in struct klp_patch, -for example: +for example:: static struct klp_patch patch = { .mod = THIS_MODULE, @@ -49,19 +49,19 @@ Features The atomic replace allows: - + Atomically revert some functions in a previous patch while + - Atomically revert some functions in a previous patch while upgrading other functions. - + Remove eventual performance impact caused by core redirection + - Remove eventual performance impact caused by core redirection for functions that are no longer patched. - + Decrease user confusion about dependencies between livepatches. + - Decrease user confusion about dependencies between livepatches. Limitations: ------------ - + Once the operation finishes, there is no straightforward way + - Once the operation finishes, there is no straightforward way to reverse it and restore the replaced patches atomically. A good practice is to set .replace flag in any released livepatch. @@ -74,7 +74,7 @@ Limitations: only when the transition was not forced. - + Only the (un)patching callbacks from the _new_ cumulative livepatch are + - Only the (un)patching callbacks from the _new_ cumulative livepatch are executed. Any callbacks from the replaced patches are ignored. In other words, the cumulative patch is responsible for doing any actions @@ -93,7 +93,7 @@ Limitations: enabled patches were called. - + There is no special handling of shadow variables. Livepatch authors + - There is no special handling of shadow variables. Livepatch authors must create their own rules how to pass them from one cumulative patch to the other. Especially that they should not blindly remove them in module_exit() functions. diff --git a/Documentation/livepatch/index.rst b/Documentation/livepatch/index.rst new file mode 100644 index 000000000000..edd291d51847 --- /dev/null +++ b/Documentation/livepatch/index.rst @@ -0,0 +1,21 @@ +:orphan: + +=================== +Kernel Livepatching +=================== + +.. toctree:: + :maxdepth: 1 + + livepatch + callbacks + cumulative-patches + module-elf-format + shadow-vars + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.rst index 4627b41ff02e..c2c598c4ead8 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.rst @@ -4,22 +4,22 @@ Livepatch This document outlines basic information about kernel livepatching. -Table of Contents: - -1. Motivation -2. Kprobes, Ftrace, Livepatching -3. Consistency model -4. Livepatch module - 4.1. New functions - 4.2. Metadata -5. Livepatch life-cycle - 5.1. Loading - 5.2. Enabling - 5.3. Replacing - 5.4. Disabling - 5.5. Removing -6. Sysfs -7. Limitations +.. Table of Contents: + + 1. Motivation + 2. Kprobes, Ftrace, Livepatching + 3. Consistency model + 4. Livepatch module + 4.1. New functions + 4.2. Metadata + 5. Livepatch life-cycle + 5.1. Loading + 5.2. Enabling + 5.3. Replacing + 5.4. Disabling + 5.5. Removing + 6. Sysfs + 7. Limitations 1. Motivation @@ -40,14 +40,14 @@ There are multiple mechanisms in the Linux kernel that are directly related to redirection of code execution; namely: kernel probes, function tracing, and livepatching: - + The kernel probes are the most generic. The code can be redirected by + - The kernel probes are the most generic. The code can be redirected by putting a breakpoint instruction instead of any instruction. - + The function tracer calls the code from a predefined location that is + - The function tracer calls the code from a predefined location that is close to the function entry point. This location is generated by the compiler using the '-pg' gcc option. - + Livepatching typically needs to redirect the code at the very beginning + - Livepatching typically needs to redirect the code at the very beginning of the function entry before the function parameters or the stack are in any way modified. @@ -249,7 +249,7 @@ The patch contains only functions that are really modified. But they might want to access functions or data from the original source file that may only be locally accessible. This can be solved by a special relocation section in the generated livepatch module, see -Documentation/livepatch/module-elf-format.txt for more details. +Documentation/livepatch/module-elf-format.rst for more details. 4.2. Metadata @@ -258,7 +258,7 @@ Documentation/livepatch/module-elf-format.txt for more details. The patch is described by several structures that split the information into three levels: - + struct klp_func is defined for each patched function. It describes + - struct klp_func is defined for each patched function. It describes the relation between the original and the new implementation of a particular function. @@ -275,7 +275,7 @@ 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. - + struct klp_object defines an array of patched functions (struct + - 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. @@ -285,7 +285,7 @@ into three levels: only when they are available. - + struct klp_patch defines an array of patched objects (struct + - struct klp_patch defines an array of patched objects (struct klp_object). This structure handles all patched functions consistently and eventually, @@ -337,14 +337,16 @@ operation fails. Second, livepatch enters into a transition state where tasks are converging to the patched state. 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[*]. This stage is indicated by a value of '1' +ftrace handler is registered\ [#]_. This stage is indicated by a value of '1' in /sys/kernel/livepatch/<name>/transition. For more information about this process, see the "Consistency model" section. Finally, once all tasks have been patched, the 'transition' value changes to '0'. -[*] Note that functions might be patched multiple times. The ftrace handler +.. [#] + + Note that functions might be patched multiple times. The ftrace handler is registered only once for a given function. Further patches just add an entry to the list (see field `func_stack`) of the struct klp_ops. The right implementation is selected by the ftrace handler, see @@ -368,7 +370,7 @@ the ftrace handler is unregistered and the struct klp_ops is freed when the related function is not modified by the new patch and func_stack list becomes empty. -See Documentation/livepatch/cumulative-patches.txt for more details. +See Documentation/livepatch/cumulative-patches.rst for more details. 5.4. Disabling @@ -421,7 +423,7 @@ See Documentation/ABI/testing/sysfs-kernel-livepatch for more details. The current Livepatch implementation has several limitations: - + Only functions that can be traced could be patched. + - Only functions that can be traced could be patched. Livepatch is based on the dynamic ftrace. In particular, functions implementing ftrace or the livepatch ftrace handler could not be @@ -431,7 +433,7 @@ The current Livepatch implementation has several limitations: - + Livepatch works reliably only when the dynamic ftrace is located at + - Livepatch works reliably only when the dynamic ftrace is located at the very beginning of the function. The function need to be redirected before the stack or the function @@ -445,7 +447,7 @@ The current Livepatch implementation has several limitations: this is handled on the ftrace level. - + Kretprobes using the ftrace framework conflict with the patched + - Kretprobes using the ftrace framework conflict with the patched functions. Both kretprobes and livepatches use a ftrace handler that modifies @@ -453,7 +455,7 @@ The current Livepatch implementation has several limitations: is rejected when the handler is already in use by the other. - + Kprobes in the original function are ignored when the code is + - Kprobes in the original function are ignored when the code is redirected to the new implementation. There is a work in progress to add warnings about this situation. diff --git a/Documentation/livepatch/module-elf-format.txt b/Documentation/livepatch/module-elf-format.rst index f21a5289a09c..2a591e6f8e6c 100644 --- a/Documentation/livepatch/module-elf-format.txt +++ b/Documentation/livepatch/module-elf-format.rst @@ -4,33 +4,21 @@ Livepatch module Elf format This document outlines the Elf format requirements that livepatch modules must follow. ------------------ -Table of Contents ------------------ -0. Background and motivation -1. Livepatch modinfo field -2. Livepatch relocation sections - 2.1 What are livepatch relocation sections? - 2.2 Livepatch relocation section format - 2.2.1 Required flags - 2.2.2 Required name format - 2.2.3 Example livepatch relocation section names - 2.2.4 Example `readelf --sections` output - 2.2.5 Example `readelf --relocs` output -3. Livepatch symbols - 3.1 What are livepatch symbols? - 3.2 A livepatch module's symbol table - 3.3 Livepatch symbol format - 3.3.1 Required flags - 3.3.2 Required name format - 3.3.3 Example livepatch symbol names - 3.3.4 Example `readelf --symbols` output -4. Architecture-specific sections -5. Symbol table and Elf section access - ----------------------------- -0. Background and motivation ----------------------------- + +.. Table of Contents + + 1. Background and motivation + 2. Livepatch modinfo field + 3. Livepatch relocation sections + 3.1 Livepatch relocation section format + 4. Livepatch symbols + 4.1 A livepatch module's symbol table + 4.2 Livepatch symbol format + 5. Architecture-specific sections + 6. Symbol table and Elf section access + +1. Background and motivation +============================ Formerly, livepatch required separate architecture-specific code to write relocations. However, arch-specific code to write relocations already @@ -52,8 +40,8 @@ relocation sections and symbols, which are described in this document. The Elf constants used to mark livepatch symbols and relocation sections were selected from OS-specific ranges according to the definitions from glibc. -0.1 Why does livepatch need to write its own relocations? ---------------------------------------------------------- +Why does livepatch need to write its own relocations? +----------------------------------------------------- A typical livepatch module contains patched versions of functions that can reference non-exported global symbols and non-included local symbols. Relocations referencing these types of symbols cannot be left in as-is @@ -72,13 +60,8 @@ relas reference are special livepatch symbols (see section 2 and 3). The arch-specific livepatch relocation code is replaced by a call to apply_relocate_add(). -================================ -PATCH MODULE FORMAT REQUIREMENTS -================================ - --------------------------- -1. Livepatch modinfo field --------------------------- +2. Livepatch modinfo field +========================== Livepatch modules are required to have the "livepatch" modinfo attribute. See the sample livepatch module in samples/livepatch/ for how this is done. @@ -87,22 +70,23 @@ Livepatch modules can be identified by users by using the 'modinfo' command and looking for the presence of the "livepatch" field. This field is also used by the kernel module loader to identify livepatch modules. -Example modinfo output: ------------------------ -% modinfo livepatch-meminfo.ko -filename: livepatch-meminfo.ko -livepatch: Y -license: GPL -depends: -vermagic: 4.3.0+ SMP mod_unload - --------------------------------- -2. Livepatch relocation sections --------------------------------- - -------------------------------------------- -2.1 What are livepatch relocation sections? -------------------------------------------- +Example: +-------- + +**Modinfo output:** + +:: + + % modinfo livepatch-meminfo.ko + filename: livepatch-meminfo.ko + livepatch: Y + license: GPL + depends: + vermagic: 4.3.0+ SMP mod_unload + +3. Livepatch relocation sections +================================ + A livepatch module manages its own Elf relocation sections to apply relocations to modules as well as to the kernel (vmlinux) at the appropriate time. For example, if a patch module patches a driver that is @@ -127,12 +111,9 @@ Every symbol referenced by a rela in a livepatch relocation section is a livepatch symbol. These must be resolved before livepatch can call apply_relocate_add(). See Section 3 for more information. ---------------------------------------- -2.2 Livepatch relocation section format ---------------------------------------- +3.1 Livepatch relocation section format +======================================= -2.2.1 Required flags --------------------- Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCH section flag. See include/uapi/linux/elf.h for the definition. The module loader recognizes this flag and will avoid applying those relocation sections @@ -140,28 +121,39 @@ at patch module load time. These sections must also be marked with SHF_ALLOC, so that the module loader doesn't discard them on module load (i.e. they will be copied into memory along with the other SHF_ALLOC sections). -2.2.2 Required name format --------------------------- -The name of a livepatch relocation section must conform to the following format: +The name of a livepatch relocation section must conform to the following +format:: -.klp.rela.objname.section_name -^ ^^ ^ ^ ^ -|________||_____| |__________| - [A] [B] [C] + .klp.rela.objname.section_name + ^ ^^ ^ ^ ^ + |________||_____| |__________| + [A] [B] [C] -[A] The relocation section name is prefixed with the string ".klp.rela." -[B] The name of the object (i.e. "vmlinux" or name of module) to - which the relocation section belongs follows immediately after the prefix. -[C] The actual name of the section to which this relocation section applies. +[A] + The relocation section name is prefixed with the string ".klp.rela." -2.2.3 Example livepatch relocation section names: -------------------------------------------------- -.klp.rela.ext4.text.ext4_attr_store -.klp.rela.vmlinux.text.cmdline_proc_show +[B] + The name of the object (i.e. "vmlinux" or name of module) to + which the relocation section belongs follows immediately after the prefix. + +[C] + The actual name of the section to which this relocation section applies. + +Examples: +--------- + +**Livepatch relocation section names:** + +:: + + .klp.rela.ext4.text.ext4_attr_store + .klp.rela.vmlinux.text.cmdline_proc_show + +**`readelf --sections` output for a patch +module that patches vmlinux and modules 9p, btrfs, ext4:** + +:: -2.2.4 Example `readelf --sections` output for a patch -module that patches vmlinux and modules 9p, btrfs, ext4: --------------------------------------------------------- Section Headers: [Nr] Name Type Address Off Size ES Flg Lk Inf Al [ snip ] @@ -175,31 +167,33 @@ module that patches vmlinux and modules 9p, btrfs, ext4: [ snip ] ^ ^ | | [*] [*] -[*] Livepatch relocation sections are SHT_RELA sections but with a few special -characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will -not be discarded when the module is loaded into memory, as well as with the -SHF_RELA_LIVEPATCH flag ("o" - for OS-specific). - -2.2.5 Example `readelf --relocs` output for a patch module: ------------------------------------------------------------ -Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: - Offset Info Type Symbol's Value Symbol's Name + Addend -000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 -0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0 -0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4 -000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4 -[ snip ] ^ - | - [*] -[*] Every symbol referenced by a relocation is a livepatch symbol. - --------------------- -3. Livepatch symbols --------------------- - -------------------------------- -3.1 What are livepatch symbols? -------------------------------- + +[*] + Livepatch relocation sections are SHT_RELA sections but with a few special + characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will + not be discarded when the module is loaded into memory, as well as with the + SHF_RELA_LIVEPATCH flag ("o" - for OS-specific). + +**`readelf --relocs` output for a patch module:** + +:: + + Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: + Offset Info Type Symbol's Value Symbol's Name + Addend + 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 + 0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0 + 0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4 + 000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4 + [ snip ] ^ + | + [*] + +[*] + Every symbol referenced by a relocation is a livepatch symbol. + +4. Livepatch symbols +==================== + Livepatch symbols are symbols referred to by livepatch relocation sections. These are symbols accessed from new versions of functions for patched objects, whose addresses cannot be resolved by the module loader (because @@ -219,9 +213,8 @@ loader can identify and ignore them. Livepatch modules keep these symbols in their symbol tables, and the symbol table is made accessible through module->symtab. -------------------------------------- -3.2 A livepatch module's symbol table -------------------------------------- +4.1 A livepatch module's symbol table +===================================== Normally, a stripped down copy of a module's symbol table (containing only "core" symbols) is made available through module->symtab (See layout_symtab() in kernel/module.c). For livepatch modules, the symbol table copied into memory @@ -231,71 +224,82 @@ relocation section refer to their respective symbols with their symbol indices, and the original symbol indices (and thus the symtab ordering) must be preserved in order for apply_relocate_add() to find the right symbol. -For example, take this particular rela from a livepatch module: -Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: - Offset Info Type Symbol's Value Symbol's Name + Addend -000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 - -This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded -in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the -symbol index 94. -And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol: -[ snip ] -94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0 -[ snip ] - ---------------------------- -3.3 Livepatch symbol format ---------------------------- - -3.3.1 Required flags --------------------- +For example, take this particular rela from a livepatch module::: + + Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries: + Offset Info Type Symbol's Value Symbol's Name + Addend + 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4 + + This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded + in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the + symbol index 94. + And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol: + [ snip ] + 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0 + [ snip ] + +4.2 Livepatch symbol format +=========================== + Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so that the module loader can identify them and not attempt to resolve them. See include/uapi/linux/elf.h for the actual definitions. -3.3.2 Required name format --------------------------- -Livepatch symbol names must conform to the following format: - -.klp.sym.objname.symbol_name,sympos -^ ^^ ^ ^ ^ ^ -|_______||_____| |_________| | - [A] [B] [C] [D] - -[A] The symbol name is prefixed with the string ".klp.sym." -[B] The name of the object (i.e. "vmlinux" or name of module) to - which the symbol belongs follows immediately after the prefix. -[C] The actual name of the symbol. -[D] The position of the symbol in the object (as according to kallsyms) - This is used to differentiate duplicate symbols within the same - object. The symbol position is expressed numerically (0, 1, 2...). - The symbol position of a unique symbol is 0. - -3.3.3 Example livepatch symbol names: -------------------------------------- -.klp.sym.vmlinux.snprintf,0 -.klp.sym.vmlinux.printk,0 -.klp.sym.btrfs.btrfs_ktype,0 - -3.3.4 Example `readelf --symbols` output for a patch module: ------------------------------------------------------------- -Symbol table '.symtab' contains 127 entries: - Num: Value Size Type Bind Vis Ndx Name - [ snip ] - 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0 - 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0 - 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0 - 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0 - [ snip ] ^ - | - [*] -[*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20). - "OS" means OS-specific. - ---------------------------------- -4. Architecture-specific sections ---------------------------------- +Livepatch symbol names must conform to the following format:: + + .klp.sym.objname.symbol_name,sympos + ^ ^^ ^ ^ ^ ^ + |_______||_____| |_________| | + [A] [B] [C] [D] + +[A] + The symbol name is prefixed with the string ".klp.sym." + +[B] + The name of the object (i.e. "vmlinux" or name of module) to + which the symbol belongs follows immediately after the prefix. + +[C] + The actual name of the symbol. + +[D] + The position of the symbol in the object (as according to kallsyms) + This is used to differentiate duplicate symbols within the same + object. The symbol position is expressed numerically (0, 1, 2...). + The symbol position of a unique symbol is 0. + +Examples: +--------- + +**Livepatch symbol names:** + +:: + + .klp.sym.vmlinux.snprintf,0 + .klp.sym.vmlinux.printk,0 + .klp.sym.btrfs.btrfs_ktype,0 + +**`readelf --symbols` output for a patch module:** + +:: + + Symbol table '.symtab' contains 127 entries: + Num: Value Size Type Bind Vis Ndx Name + [ snip ] + 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0 + 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0 + 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0 + 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0 + [ snip ] ^ + | + [*] + +[*] + Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20). + "OS" means OS-specific. + +5. Architecture-specific sections +================================= Architectures may override arch_klp_init_object_loaded() to perform additional arch-specific tasks when a target module loads, such as applying arch-specific sections. On x86 for example, we must apply per-object @@ -304,20 +308,19 @@ These sections must be prefixed with ".klp.arch.$objname." so that they can be easily identified when iterating through a patch module's Elf sections (See arch/x86/kernel/livepatch.c for a complete example). --------------------------------------- -5. Symbol table and Elf section access --------------------------------------- +6. Symbol table and Elf section access +====================================== A livepatch module's symbol table is accessible through module->symtab. Since apply_relocate_add() requires access to a module's section headers, symbol table, and relocation section indices, Elf information is preserved for livepatch modules and is made accessible by the module loader through module->klp_info, which is a klp_modinfo struct. When a livepatch module loads, -this struct is filled in by the module loader. Its fields are documented below: - -struct klp_modinfo { - Elf_Ehdr hdr; /* Elf header */ - Elf_Shdr *sechdrs; /* Section header table */ - char *secstrings; /* String table for the section headers */ - unsigned int symndx; /* The symbol table section index */ -}; +this struct is filled in by the module loader. Its fields are documented below:: + + struct klp_modinfo { + Elf_Ehdr hdr; /* Elf header */ + Elf_Shdr *sechdrs; /* Section header table */ + char *secstrings; /* String table for the section headers */ + unsigned int symndx; /* The symbol table section index */ + }; diff --git a/Documentation/livepatch/shadow-vars.txt b/Documentation/livepatch/shadow-vars.rst index ecc09a7be5dd..c05715aeafa4 100644 --- a/Documentation/livepatch/shadow-vars.txt +++ b/Documentation/livepatch/shadow-vars.rst @@ -27,10 +27,13 @@ A hashtable references all shadow variables. These references are stored and retrieved through a <obj, id> pair. * The klp_shadow variable data structure encapsulates both tracking -meta-data and shadow-data: + meta-data and shadow-data: + - meta-data + - obj - pointer to parent object - id - data identifier + - data[] - storage for shadow data It is important to note that the klp_shadow_alloc() and @@ -47,31 +50,43 @@ to do actions that can be done only once when a new variable is allocated. * klp_shadow_alloc() - allocate and add a new shadow variable - search hashtable for <obj, id> pair + - if exists + - WARN and return NULL + - if <obj, id> doesn't already exist + - allocate a new shadow variable - initialize the variable using a custom constructor and data when provided - add <obj, id> to the global hashtable * klp_shadow_get_or_alloc() - get existing or alloc a new shadow variable - search hashtable for <obj, id> pair + - if exists + - return existing shadow variable + - if <obj, id> doesn't already exist + - allocate a new shadow variable - initialize the variable using a custom constructor and data when provided - add <obj, id> pair to the global hashtable * klp_shadow_free() - detach and free a <obj, id> shadow variable - find and remove a <obj, id> reference from global hashtable + - if found + - call destructor function if defined - free shadow variable * klp_shadow_free_all() - detach and free all <*, id> shadow variables - find and remove any <*, id> references from global hashtable + - if found + - call destructor function if defined - free shadow variable @@ -102,12 +117,12 @@ parent "goes live" (ie, any shadow variable get-API requests are made for this <obj, id> pair.) For commit 1d147bfa6429, when a parent sta_info structure is allocated, -allocate a shadow copy of the ps_lock pointer, then initialize it: +allocate a shadow copy of the ps_lock pointer, then initialize it:: -#define PS_LOCK 1 -struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata, - const u8 *addr, gfp_t gfp) -{ + #define PS_LOCK 1 + struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata, + const u8 *addr, gfp_t gfp) + { struct sta_info *sta; spinlock_t *ps_lock; @@ -123,10 +138,10 @@ struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata, ... When requiring a ps_lock, query the shadow variable API to retrieve one -for a specific struct sta_info: +for a specific struct sta_info::: -void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) -{ + void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) + { spinlock_t *ps_lock; /* sync with ieee80211_tx_h_unicast_ps_buf */ @@ -136,10 +151,10 @@ void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) ... When the parent sta_info structure is freed, first free the shadow -variable: +variable:: -void sta_info_free(struct ieee80211_local *local, struct sta_info *sta) -{ + void sta_info_free(struct ieee80211_local *local, struct sta_info *sta) + { klp_shadow_free(sta, PS_LOCK, NULL); kfree(sta); ... @@ -155,19 +170,19 @@ these cases, the klp_shadow_get_or_alloc() call can be used to attach shadow variables to parents already in-flight. For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is -inside ieee80211_sta_ps_deliver_wakeup(): +inside ieee80211_sta_ps_deliver_wakeup():: -int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data) -{ + int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data) + { spinlock_t *lock = shadow_data; spin_lock_init(lock); return 0; -} + } -#define PS_LOCK 1 -void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) -{ + #define PS_LOCK 1 + void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta) + { spinlock_t *ps_lock; /* sync with ieee80211_tx_h_unicast_ps_buf */ @@ -200,10 +215,12 @@ suggests how to handle the parent object. ============= * https://github.com/dynup/kpatch -The livepatch implementation is based on the kpatch version of shadow -variables. + + The livepatch implementation is based on the kpatch version of shadow + variables. * http://files.mkgnu.net/files/dynamos/doc/papers/dynamos_eurosys_07.pdf -Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity -Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented -a datatype update technique called "shadow data structures". + + Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity + Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented + a datatype update technique called "shadow data structures". diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst index 0a222fc1d7ca..0301c25ff887 100644 --- a/Documentation/media/index.rst +++ b/Documentation/media/index.rst @@ -18,7 +18,7 @@ Linux Media Subsystem Documentation v4l-drivers/index cec-drivers/index -.. only:: subproject +.. only:: html and subproject Indices ======= diff --git a/Documentation/media/kapi/mc-core.rst b/Documentation/media/kapi/mc-core.rst index f930725e0d6b..05bba0b61748 100644 --- a/Documentation/media/kapi/mc-core.rst +++ b/Documentation/media/kapi/mc-core.rst @@ -259,6 +259,45 @@ Subsystems should facilitate link validation by providing subsystem specific helper functions to provide easy access for commonly needed information, and in the end provide a way to use driver-specific callbacks. +Media Controller Device Allocator API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the media device belongs to more than one driver, the shared media +device is allocated with the shared struct device as the key for look ups. + +The shared media device should stay in registered state until the last +driver unregisters it. In addition, the media device should be released when +all the references are released. Each driver gets a reference to the media +device during probe, when it allocates the media device. If media device is +already allocated, the allocate API bumps up the refcount and returns the +existing media device. The driver puts the reference back in its disconnect +routine when it calls :c:func:`media_device_delete()`. + +The media device is unregistered and cleaned up from the kref put handler to +ensure that the media device stays in registered state until the last driver +unregisters the media device. + +**Driver Usage** + +Drivers should use the appropriate media-core routines to manage the shared +media device life-time handling the two states: +1. allocate -> register -> delete +2. get reference to already registered device -> delete + +call :c:func:`media_device_delete()` routine to make sure the shared media +device delete is handled correctly. + +**driver probe:** +Call :c:func:`media_device_usb_allocate()` to allocate or get a reference +Call :c:func:`media_device_register()`, if media devnode isn't registered + +**driver disconnect:** +Call :c:func:`media_device_delete()` to free the media_device. Freeing is +handled by the kref put handler. + +API Definitions +^^^^^^^^^^^^^^^ + .. kernel-doc:: include/media/media-device.h .. kernel-doc:: include/media/media-devnode.h @@ -266,3 +305,5 @@ in the end provide a way to use driver-specific callbacks. .. kernel-doc:: include/media/media-entity.h .. kernel-doc:: include/media/media-request.h + +.. kernel-doc:: include/media/media-dev-allocator.h diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index 7a8b8ff4f076..ac768d769113 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -63,6 +63,7 @@ ignore symbol RC_PROTO_IMON ignore symbol RC_PROTO_RCMM12 ignore symbol RC_PROTO_RCMM24 ignore symbol RC_PROTO_RCMM32 +ignore symbol RC_PROTO_XBOX_DVD # Undocumented macros diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst index 1ad631e549fe..a74c82d95609 100644 --- a/Documentation/media/uapi/mediactl/request-api.rst +++ b/Documentation/media/uapi/mediactl/request-api.rst @@ -93,7 +93,7 @@ A queued request cannot be modified anymore. .. caution:: For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for output buffers, not for capture buffers. Attempting to add a capture buffer - to a request will result in an ``EACCES`` error. + to a request will result in an ``EBADR`` error. If the request contains configurations for multiple entities, individual drivers may synchronize so the requested pipeline's topology is applied before the diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index 81ffdcb89057..1cbd9cde57f3 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -165,7 +165,7 @@ of appropriately sized buffers for each use case). struct v4l2_buffer ================== -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.3cm}|p{10.5cm}| +.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| .. cssclass:: longtable @@ -326,7 +326,7 @@ struct v4l2_buffer Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls other than :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. - If the device does not support requests, then ``EACCES`` will be returned. + If the device does not support requests, then ``EBADR`` will be returned. If requests are supported but an invalid request file descriptor is given, then ``EINVAL`` will be returned. @@ -420,7 +420,7 @@ enum v4l2_buf_type .. cssclass:: longtable -.. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| .. flat-table:: :header-rows: 0 @@ -482,7 +482,11 @@ enum v4l2_buf_type Buffer Flags ============ -.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| .. cssclass:: longtable @@ -681,6 +685,9 @@ Buffer Flags exposure of the frame has begun. This is only valid for the ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. +.. raw:: latex + + \normalsize .. c:type:: v4l2_memory @@ -688,7 +695,7 @@ Buffer Flags enum v4l2_memory ================ -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| .. flat-table:: :header-rows: 0 @@ -724,7 +731,7 @@ The :c:type:`v4l2_buffer_timecode` structure is designed to hold a struct v4l2_timecode -------------------- -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| .. flat-table:: :header-rows: 0 @@ -761,7 +768,7 @@ struct v4l2_timecode Timecode Types -------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/colorspaces-defs.rst b/Documentation/media/uapi/v4l/colorspaces-defs.rst index c4e8fc620379..e122bbe3d799 100644 --- a/Documentation/media/uapi/v4l/colorspaces-defs.rst +++ b/Documentation/media/uapi/v4l/colorspaces-defs.rst @@ -39,7 +39,7 @@ whole range, 0-255, dividing the angular value by 1.41. The enum colorspaces except for BT.2020 which uses limited range R'G'B' quantization. -.. tabularcolumns:: |p{6.0cm}|p{11.5cm}| +.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| .. c:type:: v4l2_colorspace @@ -112,7 +112,7 @@ whole range, 0-255, dividing the angular value by 1.41. The enum .. c:type:: v4l2_ycbcr_encoding -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| .. flat-table:: V4L2 Y'CbCr Encodings :header-rows: 1 diff --git a/Documentation/media/uapi/v4l/colorspaces.rst b/Documentation/media/uapi/v4l/colorspaces.rst index c5a560f0c13d..4f6c82fa057f 100644 --- a/Documentation/media/uapi/v4l/colorspaces.rst +++ b/Documentation/media/uapi/v4l/colorspaces.rst @@ -56,9 +56,9 @@ The Y value in the CIE XYZ colorspace corresponds to luminance. Often the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace: -x = X / (X + Y + Z) + x = X / (X + Y + Z) -y = Y / (X + Y + Z) + y = Y / (X + Y + Z) The x and y values are the chromaticity coordinates and can be used to define a color without the luminance component Y. It is very confusing diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst index d6a707f0b24f..e06b03ca2ab2 100644 --- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst @@ -106,7 +106,7 @@ VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. -.. tabularcolumns:: |p{2.4cm}|p{4.4cm}|p{10.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.7cm}| .. c:type:: v4l2_vbi_format @@ -190,7 +190,7 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does applications must set it to zero. -.. tabularcolumns:: |p{4.0cm}|p{1.5cm}|p{12.0cm}| +.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}| .. _vbifmt-flags: diff --git a/Documentation/media/uapi/v4l/dev-rds.rst b/Documentation/media/uapi/v4l/dev-rds.rst index 624d6f95b842..64a724ef58f5 100644 --- a/Documentation/media/uapi/v4l/dev-rds.rst +++ b/Documentation/media/uapi/v4l/dev-rds.rst @@ -146,7 +146,7 @@ RDS datastructures .. _v4l2-rds-block-codes: -.. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{1.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| .. flat-table:: Block defines :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst index 0aa6cb8a272b..e86346f66017 100644 --- a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst @@ -118,7 +118,7 @@ struct v4l2_sliced_vbi_format \scriptsize \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{.75cm}|p{3.3cm}|p{3.4cm}|p{3.4cm}|p{3.4cm}| +.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.4cm}|p{4.4cm}|p{4.4cm}| .. cssclass:: longtable @@ -223,7 +223,7 @@ Sliced VBI services .. raw:: latex - \footnotesize + \scriptsize .. tabularcolumns:: |p{4.1cm}|p{1.1cm}|p{2.4cm}|p{2.0cm}|p{7.3cm}| @@ -541,7 +541,7 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 ------------------------------------------------- -.. tabularcolumns:: |p{4.9cm}|p{2.4cm}|p{10.2cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| .. flat-table:: :header-rows: 0 @@ -561,12 +561,12 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 :: - linemask[0] b0: line 6 first field - linemask[0] b17: line 23 first field - linemask[0] b18: line 6 second field - linemask[0] b31: line 19 second field - linemask[1] b0: line 20 second field - linemask[1] b3: line 23 second field + linemask[0] b0: line 6 first field + linemask[0] b17: line 23 first field + linemask[0] b18: line 6 second field + linemask[0] b31: line 19 second field + linemask[1] b0: line 20 second field + linemask[1] b3: line 23 second field linemask[1] b4-b31: unused and set to 0 * - struct :c:type:`v4l2_mpeg_vbi_itv0_line` @@ -590,7 +590,7 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 struct v4l2_mpeg_vbi_ITV0 ------------------------- -.. tabularcolumns:: |p{4.9cm}|p{4.4cm}|p{8.2cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| .. flat-table:: :header-rows: 0 @@ -635,7 +635,7 @@ struct v4l2_mpeg_vbi_itv0_line Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field ------------------------------------------------------------ -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| .. flat-table:: :header-rows: 1 diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst index 2c2768c7343b..029bb2d9928a 100644 --- a/Documentation/media/uapi/v4l/dev-subdev.rst +++ b/Documentation/media/uapi/v4l/dev-subdev.rst @@ -211,7 +211,7 @@ list entity names and pad numbers). .. raw:: latex - \tiny + \scriptsize .. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}| @@ -223,40 +223,80 @@ list entity names and pad numbers). :widths: 5 5 5 5 5 5 5 * - - - Sensor/0 format - - Frontend/0 format - - Frontend/1 format - - Scaler/0 format - - Scaler/0 compose selection rectangle - - Scaler/1 format + - Sensor/0 + + format + - Frontend/0 + + format + - Frontend/1 + + format + - Scaler/0 + + format + - Scaler/0 + + compose selection rectangle + - Scaler/1 + + format * - Initial state - - 2048x1536/SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 - (default) - (default) - (default) - (default) - (default) * - Configure frontend sink format - - 2048x1536/SGRBG8_1X8 - - *2048x1536/SGRBG8_1X8* - - *2046x1534/SGRBG8_1X8* + - 2048x1536 + + SGRBG8_1X8 + - *2048x1536* + + *SGRBG8_1X8* + - *2046x1534* + + *SGRBG8_1X8* - (default) - (default) - (default) * - Configure scaler sink format - - 2048x1536/SGRBG8_1X8 - - 2048x1536/SGRBG8_1X8 - - 2046x1534/SGRBG8_1X8 - - *2046x1534/SGRBG8_1X8* + - 2048x1536 + + SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 + - 2046x1534 + + SGRBG8_1X8 + - *2046x1534* + + *SGRBG8_1X8* - *0,0/2046x1534* - - *2046x1534/SGRBG8_1X8* + - *2046x1534* + + *SGRBG8_1X8* * - Configure scaler sink compose selection - - 2048x1536/SGRBG8_1X8 - - 2048x1536/SGRBG8_1X8 - - 2046x1534/SGRBG8_1X8 - - 2046x1534/SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 + - 2048x1536 + + SGRBG8_1X8 + - 2046x1534 + + SGRBG8_1X8 + - 2046x1534 + + SGRBG8_1X8 - *0,0/1280x960* - - *1280x960/SGRBG8_1X8* + - *1280x960* + + *SGRBG8_1X8* .. raw:: latex diff --git a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst index d3a553cd86c9..51c1d5c9eb00 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst @@ -88,7 +88,7 @@ enum v4l2_exposure_metering - Determines how the camera measures the amount of light available for the frame exposure. Possible values are: -.. tabularcolumns:: |p{8.5cm}|p{9.0cm}| +.. tabularcolumns:: |p{8.7cm}|p{8.8cm}| .. flat-table:: :header-rows: 0 @@ -180,7 +180,7 @@ enum v4l2_exposure_metering - control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS`` control value. -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| .. flat-table:: :header-rows: 0 @@ -206,7 +206,7 @@ enum v4l2_exposure_metering - enum v4l2_auto_focus_range - Determines auto focus distance range for which lens may be adjusted. -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -281,7 +281,7 @@ enum v4l2_auto_n_preset_white_balance - representation. The following white balance presets are listed in order of increasing color temperature. -.. tabularcolumns:: |p{7.0 cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.2 cm}|p{10.3cm}| .. flat-table:: :header-rows: 0 @@ -387,7 +387,11 @@ enum v4l2_scene_mode - to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related controls are accessible. The following scene programs are defined: -.. tabularcolumns:: |p{6.0cm}|p{11.5cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.9cm}|p{11.5cm}| .. flat-table:: :header-rows: 0 @@ -459,6 +463,9 @@ enum v4l2_scene_mode - may be switched to close-up mode and this setting may also involve some lens-distortion correction. +.. raw:: latex + + \normalsize ``V4L2_CID_3A_LOCK (bitmask)`` diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst index c97fb7923be5..4a8446203085 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -105,7 +105,7 @@ enum v4l2_mpeg_stream_vbi_fmt - -.. tabularcolumns:: |p{6 cm}|p{11.5cm}| +.. tabularcolumns:: |p{6.6 cm}|p{10.9cm}| .. flat-table:: :header-rows: 0 @@ -477,7 +477,7 @@ enum v4l2_mpeg_audio_dec_playback - -.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| +.. tabularcolumns:: |p{9.8cm}|p{7.7cm}| .. flat-table:: :header-rows: 0 @@ -888,7 +888,7 @@ enum v4l2_mpeg_video_multi_slice_mode - -.. tabularcolumns:: |p{8.7cm}|p{8.8cm}| +.. tabularcolumns:: |p{9.6cm}|p{7.9cm}| .. flat-table:: :header-rows: 0 @@ -923,9 +923,11 @@ enum v4l2_mpeg_video_multi_slice_mode - enum v4l2_mpeg_video_h264_loop_filter_mode - Loop filter mode for H264 encoder. Possible values are: +.. raw:: latex + \small -.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| +.. tabularcolumns:: |p{13.6cm}|p{3.9cm}| .. flat-table:: :header-rows: 0 @@ -938,6 +940,9 @@ enum v4l2_mpeg_video_h264_loop_filter_mode - * - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY`` - Loop filter is disabled at the slice boundary. +.. raw:: latex + + \normalsize ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)`` @@ -964,6 +969,8 @@ enum v4l2_mpeg_video_h264_entropy_mode - encoder. Possible values are: +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| + .. flat-table:: :header-rows: 0 @@ -1048,6 +1055,30 @@ enum v4l2_mpeg_video_h264_entropy_mode - Quantization parameter for an B frame for H264. Valid range: from 0 to 51. +``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the H264 I frame to limit I frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the H264 I frame to limit I frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_MIN_QP (integer)`` + Minimum quantization parameter for the H264 P frame to limit P frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MIN_QP is also set, the quantization parameter + should be chosen to meet both requirements. + +``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_MAX_QP (integer)`` + Maximum quantization parameter for the H264 P frame to limit P frame + quality to a range. Valid range: from 0 to 51. If + V4L2_CID_MPEG_VIDEO_H264_MAX_QP is also set, the quantization parameter + should be chosen to meet both requirements. + ``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)`` Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31. @@ -1129,7 +1160,9 @@ enum v4l2_mpeg_video_header_mode - it returned together with the first frame. Applicable to encoders. Possible values are: +.. raw:: latex + \small .. tabularcolumns:: |p{10.3cm}|p{7.2cm}| @@ -1143,6 +1176,9 @@ enum v4l2_mpeg_video_header_mode - - The stream header is returned together with the first encoded frame. +.. raw:: latex + + \normalsize ``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)`` @@ -1181,6 +1217,10 @@ enum v4l2_mpeg_video_h264_sei_fp_arrangement_type - Frame packing arrangement type for H264 SEI. Applicable to the H264 encoder. Possible values are: +.. raw:: latex + + \small + .. tabularcolumns:: |p{12cm}|p{5.5cm}| .. flat-table:: @@ -1200,6 +1240,10 @@ enum v4l2_mpeg_video_h264_sei_fp_arrangement_type - * - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL`` - One view per frame. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)`` @@ -1217,6 +1261,10 @@ enum v4l2_mpeg_video_h264_fmo_map_type - patterns of macroblocks. Applicable to the H264 encoder. Possible values are: +.. raw:: latex + + \small + .. tabularcolumns:: |p{12.5cm}|p{5.0cm}| .. flat-table:: @@ -1240,6 +1288,10 @@ enum v4l2_mpeg_video_h264_fmo_map_type - * - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT`` - User defined map type. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)`` @@ -1361,6 +1413,8 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. cssclass:: longtable +.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| + .. flat-table:: struct v4l2_ctrl_mpeg2_slice_params :header-rows: 0 :stub-columns: 0 @@ -1402,6 +1456,8 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. cssclass:: longtable +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + .. flat-table:: struct v4l2_mpeg2_sequence :header-rows: 0 :stub-columns: 0 @@ -1433,6 +1489,8 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. cssclass:: longtable +.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| + .. flat-table:: struct v4l2_mpeg2_picture :header-rows: 0 :stub-columns: 0 @@ -1492,6 +1550,12 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. cssclass:: longtable +.. tabularcolumns:: |p{1.2cm}|p{8.0cm}|p{7.4cm}| + +.. raw:: latex + + \small + .. flat-table:: struct v4l2_ctrl_mpeg2_quantization :header-rows: 0 :stub-columns: 0 @@ -1537,6 +1601,19 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - non-intra-coded frames, in zigzag scanning order. Only relevant for non-4:2:0 YUV formats. +``V4L2_CID_FWHT_I_FRAME_QP (integer)`` + Quantization parameter for an I frame for FWHT. Valid range: from 1 + to 31. + +``V4L2_CID_FWHT_P_FRAME_QP (integer)`` + Quantization parameter for a P frame for FWHT. Valid range: from 1 + to 31. + +.. raw:: latex + + \normalsize + + MFC 5.1 MPEG Controls ===================== @@ -1644,7 +1721,11 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - are: -.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| +.. tabularcolumns:: |p{9.2cm}|p{8.3cm}| + +.. raw:: latex + + \small .. flat-table:: :header-rows: 0 @@ -1659,7 +1740,9 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - - Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control. +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)`` Enable rate-control with fixed target bit. If this setting is @@ -1682,7 +1765,7 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - Force a frame type for the next queued buffer. Applicable to encoders. Possible values are: - +.. tabularcolumns:: |p{9.5cm}|p{8.0cm}| .. flat-table:: :header-rows: 0 @@ -1696,6 +1779,125 @@ enum v4l2_mpeg_mfc51_video_force_frame_type - - Force a non-coded frame. +.. _v4l2-mpeg-fwht: + +``V4L2_CID_MPEG_VIDEO_FWHT_PARAMS (struct)`` + Specifies the fwht parameters (as extracted from the bitstream) for the + associated FWHT data. This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for FWHT. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_fwht_params + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| + +.. flat-table:: struct v4l2_ctrl_fwht_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``backward_ref_ts`` + - Timestamp of the V4L2 capture buffer to use as backward reference, used + with P-coded frames. The timestamp refers to the + ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the + :c:func:`v4l2_timeval_to_ns()` function to convert the struct + :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64. + * - __u32 + - ``version`` + - The version of the codec + * - __u32 + - ``width`` + - The width of the frame + * - __u32 + - ``height`` + - The height of the frame + * - __u32 + - ``flags`` + - The flags of the frame, see :ref:`fwht-flags`. + * - __u32 + - ``colorspace`` + - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`. + * - __u32 + - ``xfer_func`` + - The transfer function, from enum :c:type:`v4l2_xfer_func`. + * - __u32 + - ``ycbcr_enc`` + - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. + * - __u32 + - ``quantization`` + - The quantization range, from enum :c:type:`v4l2_quantization`. + + + +.. _fwht-flags: + +FWHT Flags +============ + +.. cssclass:: longtable + +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``FWHT_FL_IS_INTERLACED`` + - 0x00000001 + - Set if this is an interlaced format + * - ``FWHT_FL_IS_BOTTOM_FIRST`` + - 0x00000002 + - Set if this is a bottom-first (NTSC) interlaced format + * - ``FWHT_FL_IS_ALTERNATE`` + - 0x00000004 + - Set if each 'frame' contains just one field + * - ``FWHT_FL_IS_BOTTOM_FIELD`` + - 0x00000008 + - If FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the + bottom field, else it is the top field. + * - ``FWHT_FL_LUMA_IS_UNCOMPRESSED`` + - 0x00000010 + - Set if the luma plane is uncompressed + * - ``FWHT_FL_CB_IS_UNCOMPRESSED`` + - 0x00000020 + - Set if the cb plane is uncompressed + * - ``FWHT_FL_CR_IS_UNCOMPRESSED`` + - 0x00000040 + - Set if the cr plane is uncompressed + * - ``FWHT_FL_CHROMA_FULL_HEIGHT`` + - 0x00000080 + - Set if the chroma plane has the same height as the luma plane, + else the chroma plane is half the height of the luma plane + * - ``FWHT_FL_CHROMA_FULL_WIDTH`` + - 0x00000100 + - Set if the chroma plane has the same width as the luma plane, + else the chroma plane is half the width of the luma plane + * - ``FWHT_FL_ALPHA_IS_UNCOMPRESSED`` + - 0x00000200 + - Set if the alpha plane is uncompressed + * - ``FWHT_FL_I_FRAME`` + - 0x00000400 + - Set if this is an I-frame + * - ``FWHT_FL_COMPONENTS_NUM_MSK`` + - 0x00070000 + - A 4-values flag - the number of components - 1 + * - ``FWHT_FL_PIXENC_YUV`` + - 0x00080000 + - Set if the pixel encoding is YUV + * - ``FWHT_FL_PIXENC_RGB`` + - 0x00100000 + - Set if the pixel encoding is RGB + * - ``FWHT_FL_PIXENC_HSV`` + - 0x00180000 + - Set if the pixel encoding is HSV CX2341x MPEG Controls @@ -1745,9 +1947,11 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - Select the algorithm to use for the Luma Spatial Filter (default ``1D_HOR``). Possible values: +.. tabularcolumns:: |p{14.5cm}|p{3.0cm}| +.. raw:: latex -.. tabularcolumns:: |p{14.5cm}|p{3.0cm}| + \small .. flat-table:: :header-rows: 0 @@ -1764,6 +1968,10 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE`` - Two-dimensional symmetrical non-separable +.. raw:: latex + + \normalsize + .. _chroma-spatial-filter-type: @@ -1776,6 +1984,7 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - ``1D_HOR``). Possible values are: +.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| .. flat-table:: :header-rows: 0 @@ -1918,6 +2127,10 @@ enum v4l2_vp8_num_ref_frames - .. tabularcolumns:: |p{7.9cm}|p{9.6cm}| +.. raw:: latex + + \small + .. flat-table:: :header-rows: 0 :stub-columns: 0 @@ -1932,6 +2145,10 @@ enum v4l2_vp8_num_ref_frames - - The last encoded frame, the golden frame and the altref frame will be searched. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)`` @@ -1961,7 +2178,7 @@ enum v4l2_vp8_golden_frame_sel - .. raw:: latex - \footnotesize + \scriptsize .. tabularcolumns:: |p{9.0cm}|p{8.0cm}| @@ -2283,7 +2500,7 @@ enum v4l2_mpeg_video_hevc_loop_filter_mode - \footnotesize -.. tabularcolumns:: |p{10.7cm}|p{6.3cm}| +.. tabularcolumns:: |p{12.1cm}|p{5.4cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/ext-ctrls-detect.rst b/Documentation/media/uapi/v4l/ext-ctrls-detect.rst index 8a45ce642829..80981d0cff42 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-detect.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-detect.rst @@ -30,7 +30,7 @@ Detect Control IDs ``V4L2_CID_DETECT_MD_MODE (menu)`` Sets the motion detection mode. -.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/ext-ctrls-dv.rst b/Documentation/media/uapi/v4l/ext-ctrls-dv.rst index 57edf211875c..5c70ac98f710 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-dv.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-dv.rst @@ -106,7 +106,7 @@ enum v4l2_dv_it_content_type - or an analog source. The enum v4l2_dv_it_content_type defines the possible content types: -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.3cm}|p{10.4cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/ext-ctrls-flash.rst b/Documentation/media/uapi/v4l/ext-ctrls-flash.rst index 5f30791c35b5..eff056b17167 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-flash.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-flash.rst @@ -87,7 +87,7 @@ Flash Control IDs ``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` Defines the source of the flash LED strobe. -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| .. flat-table:: :header-rows: 0 @@ -146,7 +146,7 @@ Flash Control IDs an effect is chip dependent. Reading the faults resets the control and returns the chip to a usable state if possible. -.. tabularcolumns:: |p{8.0cm}|p{9.5cm}| +.. tabularcolumns:: |p{8.4cm}|p{9.1cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst b/Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst index cf9cd8a9f9b4..60ce3f949319 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst @@ -37,7 +37,7 @@ JPEG Control IDs how Cb and Cr components are downsampled after converting an input image from RGB to Y'CbCr color space. -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index 8415268d439c..3fb473e3b8e2 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -64,7 +64,9 @@ enum v4l2_field .. c:type:: v4l2_field -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{11.1cm}| + +.. cssclass:: longtable .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst index 2675bef3eefe..6c961cfb74da 100644 --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst @@ -125,3 +125,9 @@ Compressed Formats - Video elementary stream using a codec based on the Fast Walsh Hadamard Transform. This codec is implemented by the vicodec ('Virtual Codec') driver. See the codec-fwht.h header for more details. + * .. _V4L2-PIX-FMT-FWHT-STATELESS: + + - ``V4L2_PIX_FMT_FWHT_STATELESS`` + - 'SFWH' + - Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation. + See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`. diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst index 862e1f327150..87e8fd7d5d02 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst @@ -36,13 +36,16 @@ per frame, therefore their headers cannot be larger than 255 bytes. Below are proprietary Microsoft style metadata types, used by D4xx cameras, where all fields are in little endian order: +.. tabularcolumns:: |p{5.0cm}|p{12.5cm}| + + .. flat-table:: D4xx metadata - :widths: 1 4 + :widths: 1 2 :header-rows: 1 :stub-columns: 0 - * - Field - - Description + * - **Field** + - **Description** * - :cspan:`1` *Depth Control* * - __u32 ID - 0x80000000 diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst index 2ebccdcca95d..d1a341af9c48 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst @@ -41,6 +41,10 @@ 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: +.. raw:: latex + + \small + :: Area 0 Area 1 Area 2 Area 3 Area 4 Area 5 @@ -53,6 +57,11 @@ Areas which can be configured to cover overlapping Hue values: 5U 0L 0U 1L 1U 2L 2U 3L 3U 4L 4U 5L 5U 0L <0..............................Hue Value............................255> + +.. raw:: latex + + \normalsize + When two consecutive areas don't overlap (n+1L is equal to nU) the boundary value is considered as part of the lower area. diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst index 38b1895a509f..dfc4a8367b3d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst @@ -31,7 +31,7 @@ The values are packed in 24 or 32 bit formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.0cm}|p{0.54cm}|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}| +.. tabularcolumns:: |p{2.6cm}|p{0.8cm}|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}| .. _packed-hsv-formats: diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst index 6b3781c04dd5..738bb14c0ee2 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst @@ -27,7 +27,7 @@ next to each other in memory. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.3cm}|p{1.6cm}|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}| +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|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}| .. _rgb-formats: @@ -139,6 +139,144 @@ next to each other in memory. - r\ :sub:`1` - r\ :sub:`0` - + * .. _V4L2-PIX-FMT-RGBA444: + + - ``V4L2_PIX_FMT_RGBA444`` + - 'RA12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-RGBX444: + + - ``V4L2_PIX_FMT_RGBX444`` + - 'RX12' + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + - + - + - + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-ABGR444: + + - ``V4L2_PIX_FMT_ABGR444`` + - 'AB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-XBGR444: + + - ``V4L2_PIX_FMT_XBGR444`` + - 'XB12' + + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - + - + - + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRA444: + + - ``V4L2_PIX_FMT_BGRA444`` + - 'BA12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - + * .. _V4L2-PIX-FMT-BGRX444: + + - ``V4L2_PIX_FMT_BGRX444`` + - 'BX12' + + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + - + - + - + + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - * .. _V4L2-PIX-FMT-ARGB555: - ``V4L2_PIX_FMT_ARGB555`` @@ -185,6 +323,144 @@ next to each other in memory. - g\ :sub:`4` - g\ :sub:`3` - + * .. _V4L2-PIX-FMT-RGBA555: + + - ``V4L2_PIX_FMT_RGBA555`` + - 'RA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - a + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-RGBX555: + + - ``V4L2_PIX_FMT_RGBX555`` + - 'RX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - + + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-ABGR555: + + - ``V4L2_PIX_FMT_ABGR555`` + - 'AB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - a + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-XBGR555: + + - ``V4L2_PIX_FMT_XBGR555`` + - 'XB15' + + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + + - + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - + * .. _V4L2-PIX-FMT-BGRA555: + + - ``V4L2_PIX_FMT_BGRA555`` + - 'BA15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - a + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - + * .. _V4L2-PIX-FMT-BGRX555: + + - ``V4L2_PIX_FMT_BGRX555`` + - 'BX15' + + - g\ :sub:`1` + - g\ :sub:`0` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - + + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - * .. _V4L2-PIX-FMT-RGB565: - ``V4L2_PIX_FMT_RGB565`` @@ -461,6 +737,166 @@ next to each other in memory. - - - + * .. _V4L2-PIX-FMT-BGRA32: + + - ``V4L2_PIX_FMT_BGRA32`` + - 'RA24' + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-BGRX32: + + - ``V4L2_PIX_FMT_BGRX32`` + - 'RX24' + + - + - + - + - + - + - + - + - + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _V4L2-PIX-FMT-RGBA32: + + - ``V4L2_PIX_FMT_RGBA32`` + - 'AB24' + + - 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:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - a\ :sub:`7` + - a\ :sub:`6` + - a\ :sub:`5` + - a\ :sub:`4` + - a\ :sub:`3` + - a\ :sub:`2` + - a\ :sub:`1` + - a\ :sub:`0` + * .. _V4L2-PIX-FMT-RGBX32: + + - ``V4L2_PIX_FMT_RGBX32`` + - 'XB24' + + - 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:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + + - + - + - + - + - + - + - + - * .. _V4L2-PIX-FMT-ARGB32: - ``V4L2_PIX_FMT_ARGB32`` @@ -656,7 +1092,7 @@ either the corresponding ARGB or XRGB format, depending on the driver. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.2cm}|p{0.60cm}|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}| +.. tabularcolumns:: |p{2.6cm}|p{0.70cm}|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}| .. _rgb-formats-deprecated: diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst index 7fcee1c11ac4..41b60fae703a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst @@ -28,7 +28,7 @@ component of each pixel in one 16 or 32 bit word. .. _packed-yuv-formats: -.. tabularcolumns:: |p{2.0cm}|p{0.67cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}|p{0.29cm}| +.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}| .. flat-table:: Packed YUV Image Formats :header-rows: 2 @@ -44,6 +44,7 @@ component of each pixel in one 16 or 32 bit word. - :cspan:`7` Byte 2 - :cspan:`7` Byte 3 + * - - - 7 @@ -81,6 +82,7 @@ component of each pixel in one 16 or 32 bit word. - 2 - 1 - 0 + * .. _V4L2-PIX-FMT-YUV444: - ``V4L2_PIX_FMT_YUV444`` @@ -103,7 +105,9 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`2` - Y'\ :sub:`1` - Y'\ :sub:`0` - - + + - :cspan:`15` + * .. _V4L2-PIX-FMT-YUV555: - ``V4L2_PIX_FMT_YUV555`` @@ -126,7 +130,8 @@ component of each pixel in one 16 or 32 bit word. - Y'\ :sub:`0` - Cb\ :sub:`4` - Cb\ :sub:`3` - - + + - :cspan:`15` * .. _V4L2-PIX-FMT-YUV565: - ``V4L2_PIX_FMT_YUV565`` @@ -149,7 +154,9 @@ component of each pixel in one 16 or 32 bit word. - Cb\ :sub:`5` - Cb\ :sub:`4` - Cb\ :sub:`3` - - + + - :cspan:`15` + * .. _V4L2-PIX-FMT-YUV32: - ``V4L2_PIX_FMT_YUV32`` @@ -190,7 +197,7 @@ component of each pixel in one 16 or 32 bit word. - Cr\ :sub:`2` - Cr\ :sub:`1` - Cr\ :sub:`0` - - + * .. _V4L2-PIX-FMT-AYUV32: - ``V4L2_PIX_FMT_AYUV32`` @@ -231,7 +238,7 @@ component of each pixel in one 16 or 32 bit word. - Cr\ :sub:`2` - Cr\ :sub:`1` - Cr\ :sub:`0` - - + * .. _V4L2-PIX-FMT-XYUV32: - ``V4L2_PIX_FMT_XYUV32`` @@ -272,7 +279,7 @@ component of each pixel in one 16 or 32 bit word. - Cr\ :sub:`2` - Cr\ :sub:`1` - Cr\ :sub:`0` - - + * .. _V4L2-PIX-FMT-VUYA32: - ``V4L2_PIX_FMT_VUYA32`` @@ -313,7 +320,7 @@ component of each pixel in one 16 or 32 bit word. - a\ :sub:`2` - a\ :sub:`1` - a\ :sub:`0` - - + * .. _V4L2-PIX-FMT-VUYX32: - ``V4L2_PIX_FMT_VUYX32`` diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst index cdb70ac26126..fd32660a3766 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst @@ -40,7 +40,7 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{5.4cm}| +.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst index 01413be12916..960851275f23 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst @@ -18,6 +18,7 @@ V4L2_PIX_FMT_SRGGB12P ('pRAA'), V4L2_PIX_FMT_SGRBG12P ('pgAA'), V4L2_PIX_FMT_SGB 12-bit packed Bayer formats +--------------------------- Description @@ -37,7 +38,7 @@ Below is an example of a small V4L2_PIX_FMT_SBGGR12P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{2.7cm}|p{1.0cm}|p{1.0cm}|p{2.7cm}| +.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}| .. flat-table:: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst index b583531c2853..1a988d7e7ff8 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst @@ -41,17 +41,21 @@ of one of these formats: **Byte Order.** Each cell is one byte. +.. raw:: latex + \footnotesize + +.. tabularcolumns:: |p{1.8cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.1cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 2 1 1 1 1 1 1 1 + :widths: 2 1 1 1 1 3 3 3 - .. row 1 - - start + 0: + - start + 0 - B\ :sub:`00high` @@ -62,17 +66,20 @@ Each cell is one byte. - G\ :sub:`03high` - G\ :sub:`01low bits 1--0`\ (bits 7--6) + B\ :sub:`00low bits 5--0`\ (bits 5--0) - R\ :sub:`02low bits 3--0`\ (bits 7--4) + G\ :sub:`01low bits 5--2`\ (bits 3--0) - G\ :sub:`03low bits 5--0`\ (bits 7--2) + R\ :sub:`02low bits 5--4`\ (bits 1--0) - .. row 2 - - start + 7: + - start + 7 - G\ :sub:`00high` @@ -83,12 +90,15 @@ Each cell is one byte. - R\ :sub:`03high` - R\ :sub:`01low bits 1--0`\ (bits 7--6) + G\ :sub:`00low bits 5--0`\ (bits 5--0) - G\ :sub:`02low bits 3--0`\ (bits 7--4) + R\ :sub:`01low bits 5--2`\ (bits 3--0) - R\ :sub:`03low bits 5--0`\ (bits 7--2) + G\ :sub:`02low bits 5--4`\ (bits 1--0) - .. row 3 @@ -104,12 +114,15 @@ Each cell is one byte. - G\ :sub:`23high` - G\ :sub:`21low bits 1--0`\ (bits 7--6) + B\ :sub:`20low bits 5--0`\ (bits 5--0) - R\ :sub:`22low bits 3--0`\ (bits 7--4) + G\ :sub:`21low bits 5--2`\ (bits 3--0) - G\ :sub:`23low bits 5--0`\ (bits 7--2) + R\ :sub:`22low bits 5--4`\ (bits 1--0) - .. row 4 @@ -132,3 +145,8 @@ Each cell is one byte. - R\ :sub:`33low bits 5--0`\ (bits 7--2) G\ :sub:`32low bits 5--4`\ (bits 1--0) + +.. raw:: latex + + \normalsize + diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst index 7f82dad9013a..5688c816e334 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst @@ -19,6 +19,7 @@ array of struct :c:type:`v4l2_plane_pix_format` structures, describing all planes of that format. + .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| .. c:type:: v4l2_plane_pix_format @@ -41,6 +42,10 @@ describing all planes of that format. applications. +.. raw:: latex + + \small + .. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}| .. c:type:: v4l2_pix_format_mplane @@ -82,9 +87,7 @@ describing all planes of that format. * - __u8 - ``flags`` - Flags set by the application or driver, see :ref:`format-flags`. - * - union { - - (anonymous) - - + * - :cspan:`2` union { (anonymous) * - __u8 - ``ycbcr_enc`` - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`. @@ -97,9 +100,7 @@ describing all planes of that format. This information supplements the ``colorspace`` and must be set by the driver for capture streams and by the application for output streams, see :ref:`colorspaces`. - * - } - - - - + * - :cspan:`2` } * - __u8 - ``quantization`` - Quantization range, from enum :c:type:`v4l2_quantization`. @@ -116,3 +117,7 @@ describing all planes of that format. - ``reserved[7]`` - Reserved for future extensions. Should be zeroed by drivers and applications. + +.. raw:: latex + + \normalsize diff --git a/Documentation/media/uapi/v4l/pixfmt-y10p.rst b/Documentation/media/uapi/v4l/pixfmt-y10p.rst index 7893642faee3..39cd789dcb59 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y10p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y10p.rst @@ -27,6 +27,12 @@ in the same order. **Bit-packed representation.** +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}||p{1.2cm}||p{1.2cm}||p{1.2cm}|p{3.2cm}|p{3.2cm}| + .. flat-table:: :header-rows: 0 :stub-columns: 0 @@ -38,3 +44,7 @@ in the same order. - Y'\ :sub:`03[9:2]` - Y'\ :sub:`03[1:0]`\ (bits 7--6) Y'\ :sub:`02[1:0]`\ (bits 5--4) Y'\ :sub:`01[1:0]`\ (bits 3--2) Y'\ :sub:`00[1:0]`\ (bits 1--0) + +.. raw:: latex + + \normalsize diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index f5440d55d510..ab1a48a5ae80 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -980,6 +980,113 @@ The following tables list existing packed RGB formats. - r\ :sub:`2` - r\ :sub:`1` - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-BGR888-3X8: + + - MEDIA_BUS_FMT_BGR888_3X8 + - 0x101b + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + * - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` * .. _MEDIA-BUS-FMT-GBR888-1X24: - MEDIA_BUS_FMT_GBR888_1X24 @@ -7414,7 +7521,7 @@ The following table lists existing HSV/HSL formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{3.0cm}|p{0.60cm}|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}| +.. tabularcolumns:: |p{3.9cm}|p{0.73cm}|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-hsv: @@ -7524,7 +7631,7 @@ The following table lists existing JPEG compressed formats. .. _v4l2-mbus-pixelcode-jpeg: -.. tabularcolumns:: |p{5.4cm}|p{1.4cm}|p{10.7cm}| +.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{10.1cm}| .. flat-table:: JPEG Formats :header-rows: 1 @@ -7557,7 +7664,7 @@ formats. .. _v4l2-mbus-pixelcode-vendor-specific: -.. tabularcolumns:: |p{6.8cm}|p{1.4cm}|p{9.3cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| .. flat-table:: Vendor and device specific formats :header-rows: 1 diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst index c138d149faea..dbf7b445a27b 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -111,7 +111,7 @@ in use. Setting it means that the buffer will not be passed to the driver until the request itself is queued. Also, the driver will apply any settings associated with the request for this buffer. This field will be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. -If the device does not support requests, then ``EACCES`` will be returned. +If the device does not support requests, then ``EBADR`` will be returned. If requests are supported but an invalid request file descriptor is given, then ``EINVAL`` will be returned. @@ -125,7 +125,7 @@ then ``EINVAL`` will be returned. For :ref:`memory-to-memory devices <mem2mem>` you can specify the ``request_fd`` only for output buffers, not for capture buffers. Attempting - to specify this for a capture buffer will result in an ``EACCES`` error. + to specify this for a capture buffer will result in an ``EBADR`` error. Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing @@ -185,9 +185,11 @@ EPIPE codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already dequeued and no new buffers are expected to become available. -EACCES +EBADR The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not - support requests for the given buffer type. + support requests for the given buffer type, or + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires + that the buffer is part of a request. EBUSY The first buffer was queued via a request, but the application now tries diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index dfd4b205937c..33a055907258 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -65,5 +65,4 @@ For more details see the file COPYING in the source distribution of Linux. soc-camera uvcvideo vivid - zoran zr364xx diff --git a/Documentation/media/v4l-drivers/zoran.rst b/Documentation/media/v4l-drivers/zoran.rst deleted file mode 100644 index d2724a863d1d..000000000000 --- a/Documentation/media/v4l-drivers/zoran.rst +++ /dev/null @@ -1,583 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The Zoran driver -================ - -unified zoran driver (zr360x7, zoran, buz, dc10(+), dc30(+), lml33) - -website: http://mjpeg.sourceforge.net/driver-zoran/ - - -Frequently Asked Questions --------------------------- - -What cards are supported ------------------------- - -Iomega Buz, Linux Media Labs LML33/LML33R10, Pinnacle/Miro -DC10/DC10+/DC30/DC30+ and related boards (available under various names). - -Iomega Buz -~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7111 TV decoder -* Philips saa7185 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, saa7111, saa7185, zr36060, zr36067 - -Inputs/outputs: Composite and S-video - -Norms: PAL, SECAM (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 7 - -AverMedia 6 Eyes AVS6EYES -~~~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Samsung ks0127 TV decoder -* Conexant bt866 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, ks0127, bt866, zr36060, zr36067 - -Inputs/outputs: - Six physical inputs. 1-6 are composite, - 1-2, 3-4, 5-6 doubles as S-video, - 1-3 triples as component. - One composite output. - -Norms: PAL, SECAM (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 8 - -.. note:: - - Not autodetected, card=8 is necessary. - -Linux Media Labs LML33 -~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Brooktree bt819 TV decoder -* Brooktree bt856 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, bt819, bt856, zr36060, zr36067 - -Inputs/outputs: Composite and S-video - -Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 5 - -Linux Media Labs LML33R10 -~~~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7114 TV decoder -* Analog Devices adv7170 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, saa7114, adv7170, zr36060, zr36067 - -Inputs/outputs: Composite and S-video - -Norms: PAL (720x576 @ 25 fps), NTSC (720x480 @ 29.97 fps) - -Card number: 6 - -Pinnacle/Miro DC10(new) -~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36057 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7110a TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, saa7110, adv7175, zr36060, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 1 - -Pinnacle/Miro DC10+ -~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36060 MJPEG codec -* Philips saa7110a TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, sa7110, adv7175, zr36060, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 2 - -Pinnacle/Miro DC10(old) -~~~~~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36057 PCI controller -* Zoran zr36050 MJPEG codec -* Zoran zr36016 Video Front End or Fuji md0211 Video Front End (clone?) -* Micronas vpx3220a TV decoder -* mse3000 TV encoder or Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, vpx3220, mse3000/adv7175, zr36050, zr36016, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 0 - -Pinnacle/Miro DC30 -~~~~~~~~~~~~~~~~~~ - -* Zoran zr36057 PCI controller -* Zoran zr36050 MJPEG codec -* Zoran zr36016 Video Front End -* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36016, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 3 - -Pinnacle/Miro DC30+ -~~~~~~~~~~~~~~~~~~~ - -* Zoran zr36067 PCI controller -* Zoran zr36050 MJPEG codec -* Zoran zr36016 Video Front End -* Micronas vpx3225d/vpx3220a/vpx3216b TV decoder -* Analog Devices adv7176 TV encoder - -Drivers to use: videodev, i2c-core, i2c-algo-bit, -videocodec, vpx3220/vpx3224, adv7175, zr36050, zr36015, zr36067 - -Inputs/outputs: Composite, S-video and Internal - -Norms: PAL, SECAM (768x576 @ 25 fps), NTSC (640x480 @ 29.97 fps) - -Card number: 4 - -.. note:: - - #) No module for the mse3000 is available yet - #) No module for the vpx3224 is available yet - -1.1 What the TV decoder can do an what not ------------------------------------------- - -The best know TV standards are NTSC/PAL/SECAM. but for decoding a frame that -information is not enough. There are several formats of the TV standards. -And not every TV decoder is able to handle every format. Also the every -combination is supported by the driver. There are currently 11 different -tv broadcast formats all aver the world. - -The CCIR defines parameters needed for broadcasting the signal. -The CCIR has defined different standards: A,B,D,E,F,G,D,H,I,K,K1,L,M,N,... -The CCIR says not much about the colorsystem used !!! -And talking about a colorsystem says not to much about how it is broadcast. - -The CCIR standards A,E,F are not used any more. - -When you speak about NTSC, you usually mean the standard: CCIR - M using -the NTSC colorsystem which is used in the USA, Japan, Mexico, Canada -and a few others. - -When you talk about PAL, you usually mean: CCIR - B/G using the PAL -colorsystem which is used in many Countries. - -When you talk about SECAM, you mean: CCIR - L using the SECAM Colorsystem -which is used in France, and a few others. - -There the other version of SECAM, CCIR - D/K is used in Bulgaria, China, -Slovakai, Hungary, Korea (Rep.), Poland, Rumania and a others. - -The CCIR - H uses the PAL colorsystem (sometimes SECAM) and is used in -Egypt, Libya, Sri Lanka, Syrain Arab. Rep. - -The CCIR - I uses the PAL colorsystem, and is used in Great Britain, Hong Kong, -Ireland, Nigeria, South Africa. - -The CCIR - N uses the PAL colorsystem and PAL frame size but the NTSC framerate, -and is used in Argentinia, Uruguay, an a few others - -We do not talk about how the audio is broadcast ! - -A rather good sites about the TV standards are: -http://www.sony.jp/support/ -http://info.electronicwerkstatt.de/bereiche/fernsehtechnik/frequenzen_und_normen/Fernsehnormen/ -and http://www.cabl.com/restaurant/channel.html - -Other weird things around: NTSC 4.43 is a modificated NTSC, which is mainly -used in PAL VCR's that are able to play back NTSC. PAL 60 seems to be the same -as NTSC 4.43 . The Datasheets also talk about NTSC 44, It seems as if it would -be the same as NTSC 4.43. -NTSC Combs seems to be a decoder mode where the decoder uses a comb filter -to split coma and luma instead of a Delay line. - -But I did not defiantly find out what NTSC Comb is. - -Philips saa7111 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1997, is used in the BUZ and -- can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC N, NTSC 4.43 and SECAM - -Philips saa7110a TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1995, is used in the Pinnacle/Miro DC10(new), DC10+ and -- can handle: PAL B/G, NTSC M and SECAM - -Philips saa7114 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 2000, is used in the LML33R10 and -- can handle: PAL B/G/D/H/I/N, PAL N, PAL M, NTSC M, NTSC 4.43 and SECAM - -Brooktree bt819 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, and is used in the LML33 and -- can handle: PAL B/D/G/H/I, NTSC M - -Micronas vpx3220a TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, is used in the DC30 and DC30+ and -- can handle: PAL B/G/H/I, PAL N, PAL M, NTSC M, NTSC 44, PAL 60, SECAM,NTSC Comb - -Samsung ks0127 TV decoder -~~~~~~~~~~~~~~~~~~~~~~~~~ - -- is used in the AVS6EYES card and -- can handle: NTSC-M/N/44, PAL-M/N/B/G/H/I/D/K/L and SECAM - - -What the TV encoder can do an what not --------------------------------------- - -The TV encoder are doing the "same" as the decoder, but in the oder direction. -You feed them digital data and the generate a Composite or SVHS signal. -For information about the colorsystems and TV norm take a look in the -TV decoder section. - -Philips saa7185 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, is used in the BUZ -- can generate: PAL B/G, NTSC M - -Brooktree bt856 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1994, is used in the LML33 -- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL-N (Argentina) - -Analog Devices adv7170 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 2000, is used in the LML300R10 -- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M, PAL 60 - -Analog Devices adv7175 TV Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1996, is used in the DC10, DC10+, DC10 old, DC30, DC30+ -- can generate: PAL B/D/G/H/I/N, PAL M, NTSC M - -ITT mse3000 TV encoder -~~~~~~~~~~~~~~~~~~~~~~ - -- was introduced in 1991, is used in the DC10 old -- can generate: PAL , NTSC , SECAM - -Conexant bt866 TV encoder -~~~~~~~~~~~~~~~~~~~~~~~~~ - -- is used in AVS6EYES, and -- can generate: NTSC/PAL, PALÂM, PALÂN - -The adv717x, should be able to produce PAL N. But you find nothing PAL N -specific in the registers. Seem that you have to reuse a other standard -to generate PAL N, maybe it would work if you use the PAL M settings. - -How do I get this damn thing to work ------------------------------------- - -Load zr36067.o. If it can't autodetect your card, use the card=X insmod -option with X being the card number as given in the previous section. -To have more than one card, use card=X1[,X2[,X3,[X4[..]]]] - -To automate this, add the following to your /etc/modprobe.d/zoran.conf: - -options zr36067 card=X1[,X2[,X3[,X4[..]]]] -alias char-major-81-0 zr36067 - -One thing to keep in mind is that this doesn't load zr36067.o itself yet. It -just automates loading. If you start using xawtv, the device won't load on -some systems, since you're trying to load modules as a user, which is not -allowed ("permission denied"). A quick workaround is to add 'Load "v4l"' to -XF86Config-4 when you use X by default, or to run 'v4l-conf -c <device>' in -one of your startup scripts (normally rc.local) if you don't use X. Both -make sure that the modules are loaded on startup, under the root account. - -What mainboard should I use (or why doesn't my card work) ---------------------------------------------------------- - - -<insert lousy disclaimer here>. In short: good=SiS/Intel, bad=VIA. - -Experience tells us that people with a Buz, on average, have more problems -than users with a DC10+/LML33. Also, it tells us that people owning a VIA- -based mainboard (ktXXX, MVP3) have more problems than users with a mainboard -based on a different chipset. Here's some notes from Andrew Stevens: - -Here's my experience of using LML33 and Buz on various motherboards: - -- VIA MVP3 - - Forget it. Pointless. Doesn't work. -- Intel 430FX (Pentium 200) - - LML33 perfect, Buz tolerable (3 or 4 frames dropped per movie) -- Intel 440BX (early stepping) - - LML33 tolerable. Buz starting to get annoying (6-10 frames/hour) -- Intel 440BX (late stepping) - - Buz tolerable, LML3 almost perfect (occasional single frame drops) -- SiS735 - - LML33 perfect, Buz tolerable. -- VIA KT133(*) - - LML33 starting to get annoying, Buz poor enough that I have up. - -- Both 440BX boards were dual CPU versions. - -Bernhard Praschinger later added: - -- AMD 751 - - Buz perfect-tolerable -- AMD 760 - - Buz perfect-tolerable - -In general, people on the user mailinglist won't give you much of a chance -if you have a VIA-based motherboard. They may be cheap, but sometimes, you'd -rather want to spend some more money on better boards. In general, VIA -mainboard's IDE/PCI performance will also suck badly compared to others. -You'll noticed the DC10+/DC30+ aren't mentioned anywhere in the overview. -Basically, you can assume that if the Buz works, the LML33 will work too. If -the LML33 works, the DC10+/DC30+ will work too. They're most tolerant to -different mainboard chipsets from all of the supported cards. - -If you experience timeouts during capture, buy a better mainboard or lower -the quality/buffersize during capture (see 'Concerning buffer sizes, quality, -output size etc.'). If it hangs, there's little we can do as of now. Check -your IRQs and make sure the card has its own interrupts. - -Programming interface ---------------------- - -This driver conforms to video4linux2. Support for V4L1 and for the custom -zoran ioctls has been removed in kernel 2.6.38. - -For programming example, please, look at lavrec.c and lavplay.c code in -the MJPEG-tools (http://mjpeg.sf.net/). - -Additional notes for software developers: - - The driver returns maxwidth and maxheight parameters according to - the current TV standard (norm). Therefore, the software which - communicates with the driver and "asks" for these parameters should - first set the correct norm. Well, it seems logically correct: TV - standard is "more constant" for current country than geometry - settings of a variety of TV capture cards which may work in ITU or - square pixel format. - -Applications ------------- - -Applications known to work with this driver: - -TV viewing: - -* xawtv -* kwintv -* probably any TV application that supports video4linux or video4linux2. - -MJPEG capture/playback: - -* mjpegtools/lavtools (or Linux Video Studio) -* gstreamer -* mplayer - -General raw capture: - -* xawtv -* gstreamer -* probably any application that supports video4linux or video4linux2 - -Video editing: - -* Cinelerra -* MainActor -* mjpegtools (or Linux Video Studio) - - -Concerning buffer sizes, quality, output size etc. --------------------------------------------------- - - -The zr36060 can do 1:2 JPEG compression. This is really the theoretical -maximum that the chipset can reach. The driver can, however, limit compression -to a maximum (size) of 1:4. The reason for this is that some cards (e.g. Buz) -can't handle 1:2 compression without stopping capture after only a few minutes. -With 1:4, it'll mostly work. If you have a Buz, use 'low_bitrate=1' to go into -1:4 max. compression mode. - -100% JPEG quality is thus 1:2 compression in practice. So for a full PAL frame -(size 720x576). The JPEG fields are stored in YUY2 format, so the size of the -fields are 720x288x16/2 bits/field (2 fields/frame) = 207360 bytes/field x 2 = -414720 bytes/frame (add some more bytes for headers and DHT (huffman)/DQT -(quantization) tables, and you'll get to something like 512kB per frame for -1:2 compression. For 1:4 compression, you'd have frames of half this size. - -Some additional explanation by Martin Samuelsson, which also explains the -importance of buffer sizes: --- -> Hmm, I do not think it is really that way. With the current (downloaded -> at 18:00 Monday) driver I get that output sizes for 10 sec: -> -q 50 -b 128 : 24.283.332 Bytes -> -q 50 -b 256 : 48.442.368 -> -q 25 -b 128 : 24.655.992 -> -q 25 -b 256 : 25.859.820 - -I woke up, and can't go to sleep again. I'll kill some time explaining why -this doesn't look strange to me. - -Let's do some math using a width of 704 pixels. I'm not sure whether the Buz -actually use that number or not, but that's not too important right now. - -704x288 pixels, one field, is 202752 pixels. Divided by 64 pixels per block; -3168 blocks per field. Each pixel consist of two bytes; 128 bytes per block; -1024 bits per block. 100% in the new driver mean 1:2 compression; the maximum -output becomes 512 bits per block. Actually 510, but 512 is simpler to use -for calculations. - -Let's say that we specify d1q50. We thus want 256 bits per block; times 3168 -becomes 811008 bits; 101376 bytes per field. We're talking raw bits and bytes -here, so we don't need to do any fancy corrections for bits-per-pixel or such -things. 101376 bytes per field. - -d1 video contains two fields per frame. Those sum up to 202752 bytes per -frame, and one of those frames goes into each buffer. - -But wait a second! -b128 gives 128kB buffers! It's not possible to cram -202752 bytes of JPEG data into 128kB! - -This is what the driver notice and automatically compensate for in your -examples. Let's do some math using this information: - -128kB is 131072 bytes. In this buffer, we want to store two fields, which -leaves 65536 bytes for each field. Using 3168 blocks per field, we get -20.68686868... available bytes per block; 165 bits. We can't allow the -request for 256 bits per block when there's only 165 bits available! The -q50 -option is silently overridden, and the -b128 option takes precedence, leaving -us with the equivalence of -q32. - -This gives us a data rate of 165 bits per block, which, times 3168, sums up -to 65340 bytes per field, out of the allowed 65536. The current driver has -another level of rate limiting; it won't accept -q values that fill more than -6/8 of the specified buffers. (I'm not sure why. "Playing it safe" seem to be -a safe bet. Personally, I think I would have lowered requested-bits-per-block -by one, or something like that.) We can't use 165 bits per block, but have to -lower it again, to 6/8 of the available buffer space: We end up with 124 bits -per block, the equivalence of -q24. With 128kB buffers, you can't use greater -than -q24 at -d1. (And PAL, and 704 pixels width...) - -The third example is limited to -q24 through the same process. The second -example, using very similar calculations, is limited to -q48. The only -example that actually grab at the specified -q value is the last one, which -is clearly visible, looking at the file size. --- - -Conclusion: the quality of the resulting movie depends on buffer size, quality, -whether or not you use 'low_bitrate=1' as insmod option for the zr36060.c -module to do 1:4 instead of 1:2 compression, etc. - -If you experience timeouts, lowering the quality/buffersize or using -'low_bitrate=1 as insmod option for zr36060.o might actually help, as is -proven by the Buz. - -It hangs/crashes/fails/whatevers! Help! ---------------------------------------- - -Make sure that the card has its own interrupts (see /proc/interrupts), check -the output of dmesg at high verbosity (load zr36067.o with debug=2, -load all other modules with debug=1). Check that your mainboard is favorable -(see question 2) and if not, test the card in another computer. Also see the -notes given in question 3 and try lowering quality/buffersize/capturesize -if recording fails after a period of time. - -If all this doesn't help, give a clear description of the problem including -detailed hardware information (memory+brand, mainboard+chipset+brand, which -MJPEG card, processor, other PCI cards that might be of interest), give the -system PnP information (/proc/interrupts, /proc/dma, /proc/devices), and give -the kernel version, driver version, glibc version, gcc version and any other -information that might possibly be of interest. Also provide the dmesg output -at high verbosity. See 'Contacting' on how to contact the developers. - -Maintainers/Contacting ----------------------- - -The driver is currently maintained by Laurent Pinchart and Ronald Bultje -(<laurent.pinchart@skynet.be> and <rbultje@ronald.bitfreak.net>). For bug -reports or questions, please contact the mailinglist instead of the developers -individually. For user questions (i.e. bug reports or how-to questions), send -an email to <mjpeg-users@lists.sf.net>, for developers (i.e. if you want to -help programming), send an email to <mjpeg-developer@lists.sf.net>. See -http://www.sf.net/projects/mjpeg/ for subscription information. - -For bug reports, be sure to include all the information as described in -the section 'It hangs/crashes/fails/whatevers! Help!'. Please make sure -you're using the latest version (http://mjpeg.sf.net/driver-zoran/). - -Previous maintainers/developers of this driver include Serguei Miridonov -<mirsev@cicese.mx>, Wolfgang Scherr <scherr@net4you.net>, Dave Perks -<dperks@ibm.net> and Rainer Johanni <Rainer@Johanni.de>. - -Driver's License ----------------- - - This driver is distributed under the terms of the General Public License. - - 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. - -See http://www.gnu.org/ for more information. diff --git a/Documentation/networking/batman-adv.rst b/Documentation/networking/batman-adv.rst index 245fb6c0ab6f..18020943ba25 100644 --- a/Documentation/networking/batman-adv.rst +++ b/Documentation/networking/batman-adv.rst @@ -27,24 +27,8 @@ Load the batman-adv module into your kernel:: $ insmod batman-adv.ko The module is now waiting for activation. You must add some interfaces on which -batman can operate. After loading the module batman advanced will scan your -systems interfaces to search for compatible interfaces. Once found, it will -create subfolders in the ``/sys`` directories of each supported interface, -e.g.:: - - $ ls /sys/class/net/eth0/batman_adv/ - elp_interval iface_status mesh_iface throughput_override - -If an interface does not have the ``batman_adv`` subfolder, it probably is not -supported. Not supported interfaces are: loopback, non-ethernet and batman's -own interfaces. - -Note: After the module was loaded it will continuously watch for new -interfaces to verify the compatibility. There is no need to reload the module -if you plug your USB wifi adapter into your machine after batman advanced was -initially loaded. - -The batman-adv soft-interface can be created using the iproute2 tool ``ip``:: +batman-adv can operate. The batman-adv soft-interface can be created using the +iproute2 tool ``ip``:: $ ip link add name bat0 type batadv @@ -52,57 +36,46 @@ To activate a given interface simply attach it to the ``bat0`` interface:: $ ip link set dev eth0 master bat0 -Repeat this step for all interfaces you wish to add. Now batman starts +Repeat this step for all interfaces you wish to add. Now batman-adv starts using/broadcasting on this/these interface(s). -By reading the "iface_status" file you can check its status:: - - $ cat /sys/class/net/eth0/batman_adv/iface_status - active - To deactivate an interface you have to detach it from the "bat0" interface:: $ ip link set dev eth0 nomaster +The same can also be done using the batctl interface subcommand:: -All mesh wide settings can be found in batman's own interface folder:: + batctl -m bat0 interface create + batctl -m bat0 interface add -M eth0 - $ ls /sys/class/net/bat0/mesh/ - aggregated_ogms fragmentation isolation_mark routing_algo - ap_isolation gw_bandwidth log_level vlan0 - bonding gw_mode multicast_mode - bridge_loop_avoidance gw_sel_class network_coding - distributed_arp_table hop_penalty orig_interval +To detach eth0 and destroy bat0:: -There is a special folder for debugging information:: + batctl -m bat0 interface del -M eth0 + batctl -m bat0 interface destroy - $ ls /sys/kernel/debug/batman_adv/bat0/ - bla_backbone_table log neighbors transtable_local - bla_claim_table mcast_flags originators - dat_cache nc socket - gateways nc_nodes transtable_global +There are additional settings for each batadv mesh interface, vlan and hardif +which can be modified using batctl. Detailed information about this can be found +in its manual. -Some of the files contain all sort of status information regarding the mesh -network. For example, you can view the table of originators (mesh -participants) with:: +For instance, you can check the current originator interval (value +in milliseconds which determines how often batman-adv sends its broadcast +packets):: - $ cat /sys/kernel/debug/batman_adv/bat0/originators - -Other files allow to change batman's behaviour to better fit your requirements. -For instance, you can check the current originator interval (value in -milliseconds which determines how often batman sends its broadcast packets):: - - $ cat /sys/class/net/bat0/mesh/orig_interval + $ batctl -M bat0 orig_interval 1000 and also change its value:: - $ echo 3000 > /sys/class/net/bat0/mesh/orig_interval + $ batctl -M bat0 orig_interval 3000 In very mobile scenarios, you might want to adjust the originator interval to a lower value. This will make the mesh more responsive to topology changes, but will also increase the overhead. +Information about the current state can be accessed via the batadv generic +netlink family. batctl provides human readable version via its debug tables +subcommands. + Usage ===== @@ -147,43 +120,16 @@ batman-adv module. When building batman-adv as part of kernel, use "make menuconfig" and enable the option ``B.A.T.M.A.N. debugging`` (``CONFIG_BATMAN_ADV_DEBUG=y``). -Those additional debug messages can be accessed using a special file in -debugfs:: +Those additional debug messages can be accessed using the perf infrastructure:: - $ cat /sys/kernel/debug/batman_adv/bat0/log + $ trace-cmd stream -e batadv:batadv_dbg The additional debug output is by default disabled. It can be enabled during -run time. Following log_levels are defined: - -.. flat-table:: - - * - 0 - - All debug output disabled - * - 1 - - Enable messages related to routing / flooding / broadcasting - * - 2 - - Enable messages related to route added / changed / deleted - * - 4 - - Enable messages related to translation table operations - * - 8 - - Enable messages related to bridge loop avoidance - * - 16 - - Enable messages related to DAT, ARP snooping and parsing - * - 32 - - Enable messages related to network coding - * - 64 - - Enable messages related to multicast - * - 128 - - Enable messages related to throughput meter - * - 255 - - Enable all messages - -The debug output can be changed at runtime using the file -``/sys/class/net/bat0/mesh/log_level``. e.g.:: - - $ echo 6 > /sys/class/net/bat0/mesh/log_level - -will enable debug messages for when routes change. +run time:: + + $ batctl -m bat0 loglevel routes tt + +will enable debug messages for when routes and translation table entries change. Counters for different types of packets entering and leaving the batman-adv module are available through ethtool:: diff --git a/Documentation/networking/devlink-info-versions.rst b/Documentation/networking/devlink-info-versions.rst index c79ad8593383..4316342b7746 100644 --- a/Documentation/networking/devlink-info-versions.rst +++ b/Documentation/networking/devlink-info-versions.rst @@ -41,3 +41,8 @@ fw.ncsi Version of the software responsible for supporting/handling the Network Controller Sideband Interface. + +fw.psid +======= + +Unique identifier of the firmware parameter set. diff --git a/Documentation/networking/dsa/bcm_sf2.txt b/Documentation/networking/dsa/bcm_sf2.rst index eba3a2431e91..dee234039e1e 100644 --- a/Documentation/networking/dsa/bcm_sf2.txt +++ b/Documentation/networking/dsa/bcm_sf2.rst @@ -1,3 +1,4 @@ +============================================= Broadcom Starfighter 2 Ethernet switch driver ============================================= @@ -25,27 +26,27 @@ are connected at a lower speed. The switch hardware block is typically interfaced using MMIO accesses and contains a bunch of sub-blocks/registers: -* SWITCH_CORE: common switch registers -* SWITCH_REG: external interfaces switch register -* SWITCH_MDIO: external MDIO bus controller (there is another one in SWITCH_CORE, +- ``SWITCH_CORE``: common switch registers +- ``SWITCH_REG``: external interfaces switch register +- ``SWITCH_MDIO``: external MDIO bus controller (there is another one in SWITCH_CORE, which is used for indirect PHY accesses) -* SWITCH_INDIR_RW: 64-bits wide register helper block -* SWITCH_INTRL2_0/1: Level-2 interrupt controllers -* SWITCH_ACB: Admission control block -* SWITCH_FCB: Fail-over control block +- ``SWITCH_INDIR_RW``: 64-bits wide register helper block +- ``SWITCH_INTRL2_0/1``: Level-2 interrupt controllers +- ``SWITCH_ACB``: Admission control block +- ``SWITCH_FCB``: Fail-over control block Implementation details ====================== -The driver is located in drivers/net/dsa/bcm_sf2.c and is implemented as a DSA -driver; see Documentation/networking/dsa/dsa.txt for details on the subsystem +The driver is located in ``drivers/net/dsa/bcm_sf2.c`` and is implemented as a DSA +driver; see ``Documentation/networking/dsa/dsa.rst`` for details on the subsystem and what it provides. The SF2 switch is configured to enable a Broadcom specific 4-bytes switch tag which gets inserted by the switch for every packet forwarded to the CPU interface, conversely, the CPU network interface should insert a similar tag for packets entering the CPU port. The tag format is described in -net/dsa/tag_brcm.c. +``net/dsa/tag_brcm.c``. Overall, the SF2 driver is a fairly regular DSA driver; there are a few specifics covered below. @@ -54,7 +55,7 @@ Device Tree probing ------------------- The DSA platform device driver is probed using a specific compatible string -provided in net/dsa/dsa.c. The reason for that is because the DSA subsystem gets +provided in ``net/dsa/dsa.c``. The reason for that is because the DSA subsystem gets registered as a platform device driver currently. DSA will provide the needed device_node pointers which are then accessible by the switch driver setup function to setup resources such as register ranges and interrupts. This @@ -70,7 +71,7 @@ Broadcom switches connected to a SF2 require the use of the DSA slave MDIO bus in order to properly configure them. By default, the SF2 pseudo-PHY address, and an external switch pseudo-PHY address will both be snooping for incoming MDIO transactions, since they are at the same address (30), resulting in some kind of -"double" programming. Using DSA, and setting ds->phys_mii_mask accordingly, we +"double" programming. Using DSA, and setting ``ds->phys_mii_mask`` accordingly, we selectively divert reads and writes towards external Broadcom switches pseudo-PHY addresses. Newer revisions of the SF2 hardware have introduced a configurable pseudo-PHY address which circumvents the initial design limitation. @@ -86,7 +87,7 @@ firmware gets reloaded. The SF2 driver relies on such events to properly set its MoCA interface carrier state and properly report this to the networking stack. The MoCA interfaces are supported using the PHY library's fixed PHY/emulated PHY -device and the switch driver registers a fixed_link_update callback for such +device and the switch driver registers a ``fixed_link_update`` callback for such PHYs which reflects the link state obtained from the interrupt handler. diff --git a/Documentation/networking/dsa/dsa.txt b/Documentation/networking/dsa/dsa.rst index 43ef767bc440..ca87068b9ab9 100644 --- a/Documentation/networking/dsa/dsa.txt +++ b/Documentation/networking/dsa/dsa.rst @@ -1,10 +1,8 @@ -Distributed Switch Architecture -=============================== - -Introduction +============ +Architecture ============ -This document describes the Distributed Switch Architecture (DSA) subsystem +This document describes the **Distributed Switch Architecture (DSA)** subsystem design principles, limitations, interactions with other subsystems, and how to develop drivers for this subsystem as well as a TODO for developers interested in joining the effort. @@ -70,11 +68,11 @@ Switch tagging protocols DSA currently supports 5 different tagging protocols, and a tag-less mode as well. The different protocols are implemented in: -net/dsa/tag_trailer.c: Marvell's 4 trailer tag mode (legacy) -net/dsa/tag_dsa.c: Marvell's original DSA tag -net/dsa/tag_edsa.c: Marvell's enhanced DSA tag -net/dsa/tag_brcm.c: Broadcom's 4 bytes tag -net/dsa/tag_qca.c: Qualcomm's 2 bytes tag +- ``net/dsa/tag_trailer.c``: Marvell's 4 trailer tag mode (legacy) +- ``net/dsa/tag_dsa.c``: Marvell's original DSA tag +- ``net/dsa/tag_edsa.c``: Marvell's enhanced DSA tag +- ``net/dsa/tag_brcm.c``: Broadcom's 4 bytes tag +- ``net/dsa/tag_qca.c``: Qualcomm's 2 bytes tag The exact format of the tag protocol is vendor specific, but in general, they all contain something which: @@ -89,7 +87,7 @@ Master network devices are regular, unmodified Linux network device drivers for the CPU/management Ethernet interface. Such a driver might occasionally need to know whether DSA is enabled (e.g.: to enable/disable specific offload features), but the DSA subsystem has been proven to work with industry standard drivers: -e1000e, mv643xx_eth etc. without having to introduce modifications to these +``e1000e,`` ``mv643xx_eth`` etc. without having to introduce modifications to these drivers. Such network devices are also often referred to as conduit network devices since they act as a pipe between the host processor and the hardware Ethernet switch. @@ -100,40 +98,42 @@ Networking stack hooks When a master netdev is used with DSA, a small hook is placed in in the networking stack is in order to have the DSA subsystem process the Ethernet switch specific tagging protocol. DSA accomplishes this by registering a -specific (and fake) Ethernet type (later becoming skb->protocol) with the -networking stack, this is also known as a ptype or packet_type. A typical +specific (and fake) Ethernet type (later becoming ``skb->protocol``) with the +networking stack, this is also known as a ``ptype`` or ``packet_type``. A typical Ethernet Frame receive sequence looks like this: Master network device (e.g.: e1000e): -Receive interrupt fires: -- receive function is invoked -- basic packet processing is done: getting length, status etc. -- packet is prepared to be processed by the Ethernet layer by calling - eth_type_trans +1. Receive interrupt fires: + + - receive function is invoked + - basic packet processing is done: getting length, status etc. + - packet is prepared to be processed by the Ethernet layer by calling + ``eth_type_trans`` + +2. net/ethernet/eth.c:: + + eth_type_trans(skb, dev) + if (dev->dsa_ptr != NULL) + -> skb->protocol = ETH_P_XDSA -net/ethernet/eth.c: +3. drivers/net/ethernet/\*:: -eth_type_trans(skb, dev) - if (dev->dsa_ptr != NULL) - -> skb->protocol = ETH_P_XDSA + netif_receive_skb(skb) + -> iterate over registered packet_type + -> invoke handler for ETH_P_XDSA, calls dsa_switch_rcv() -drivers/net/ethernet/*: +4. net/dsa/dsa.c:: -netif_receive_skb(skb) - -> iterate over registered packet_type - -> invoke handler for ETH_P_XDSA, calls dsa_switch_rcv() + -> dsa_switch_rcv() + -> invoke switch tag specific protocol handler in 'net/dsa/tag_*.c' -net/dsa/dsa.c: - -> dsa_switch_rcv() - -> invoke switch tag specific protocol handler in - net/dsa/tag_*.c +5. net/dsa/tag_*.c: -net/dsa/tag_*.c: - -> inspect and strip switch tag protocol to determine originating port - -> locate per-port network device - -> invoke eth_type_trans() with the DSA slave network device - -> invoked netif_receive_skb() + - inspect and strip switch tag protocol to determine originating port + - locate per-port network device + - invoke ``eth_type_trans()`` with the DSA slave network device + - invoked ``netif_receive_skb()`` Past this point, the DSA slave network devices get delivered regular Ethernet frames that can be processed by the networking stack. @@ -162,7 +162,7 @@ invoke a specific transmit routine which takes care of adding the relevant switch tag in the Ethernet frames. These frames are then queued for transmission using the master network device -ndo_start_xmit() function, since they contain the appropriate switch tag, the +``ndo_start_xmit()`` function, since they contain the appropriate switch tag, the Ethernet switch will be able to process these incoming frames from the management interface and delivers these frames to the physical switch port. @@ -170,23 +170,25 @@ Graphical representation ------------------------ Summarized, this is basically how DSA looks like from a network device -perspective: - - - |--------------------------- - | CPU network device (eth0)| - ---------------------------- - | <tag added by switch | - | | - | | - | tag added by CPU> | - |--------------------------------------------| - | Switch driver | - |--------------------------------------------| - || || || - |-------| |-------| |-------| - | sw0p0 | | sw0p1 | | sw0p2 | - |-------| |-------| |-------| +perspective:: + + + |--------------------------- + | CPU network device (eth0)| + ---------------------------- + | <tag added by switch | + | | + | | + | tag added by CPU> | + |--------------------------------------------| + | Switch driver | + |--------------------------------------------| + || || || + |-------| |-------| |-------| + | sw0p0 | | sw0p1 | | sw0p2 | + |-------| |-------| |-------| + + Slave MDIO bus -------------- @@ -207,31 +209,32 @@ PHYs, external PHYs, or even external switches. Data structures --------------- -DSA data structures are defined in include/net/dsa.h as well as -net/dsa/dsa_priv.h. +DSA data structures are defined in ``include/net/dsa.h`` as well as +``net/dsa/dsa_priv.h``: -dsa_chip_data: platform data configuration for a given switch device, this -structure describes a switch device's parent device, its address, as well as -various properties of its ports: names/labels, and finally a routing table -indication (when cascading switches) +- ``dsa_chip_data``: platform data configuration for a given switch device, + this structure describes a switch device's parent device, its address, as + well as various properties of its ports: names/labels, and finally a routing + table indication (when cascading switches) -dsa_platform_data: platform device configuration data which can reference a -collection of dsa_chip_data structure if multiples switches are cascaded, the -master network device this switch tree is attached to needs to be referenced +- ``dsa_platform_data``: platform device configuration data which can reference + a collection of dsa_chip_data structure if multiples switches are cascaded, + the master network device this switch tree is attached to needs to be + referenced -dsa_switch_tree: structure assigned to the master network device under -"dsa_ptr", this structure references a dsa_platform_data structure as well as -the tagging protocol supported by the switch tree, and which receive/transmit -function hooks should be invoked, information about the directly attached switch -is also provided: CPU port. Finally, a collection of dsa_switch are referenced -to address individual switches in the tree. +- ``dsa_switch_tree``: structure assigned to the master network device under + ``dsa_ptr``, this structure references a dsa_platform_data structure as well as + the tagging protocol supported by the switch tree, and which receive/transmit + function hooks should be invoked, information about the directly attached + switch is also provided: CPU port. Finally, a collection of dsa_switch are + referenced to address individual switches in the tree. -dsa_switch: structure describing a switch device in the tree, referencing a -dsa_switch_tree as a backpointer, slave network devices, master network device, -and a reference to the backing dsa_switch_ops +- ``dsa_switch``: structure describing a switch device in the tree, referencing + a ``dsa_switch_tree`` as a backpointer, slave network devices, master network + device, and a reference to the backing``dsa_switch_ops`` -dsa_switch_ops: structure referencing function pointers, see below for a full -description. +- ``dsa_switch_ops``: structure referencing function pointers, see below for a + full description. Design limitations ================== @@ -240,7 +243,7 @@ Limits on the number of devices and ports ----------------------------------------- DSA currently limits the number of maximum switches within a tree to 4 -(DSA_MAX_SWITCHES), and the number of ports per switch to 12 (DSA_MAX_PORTS). +(``DSA_MAX_SWITCHES``), and the number of ports per switch to 12 (``DSA_MAX_PORTS``). These limits could be extended to support larger configurations would this need arise. @@ -279,15 +282,15 @@ Interactions with other subsystems DSA currently leverages the following subsystems: -- MDIO/PHY library: drivers/net/phy/phy.c, mdio_bus.c -- Switchdev: net/switchdev/* +- MDIO/PHY library: ``drivers/net/phy/phy.c``, ``mdio_bus.c`` +- Switchdev:``net/switchdev/*`` - Device Tree for various of_* functions MDIO/PHY library ---------------- Slave network devices exposed by DSA may or may not be interfacing with PHY -devices (struct phy_device as defined in include/linux/phy.h), but the DSA +devices (``struct phy_device`` as defined in ``include/linux/phy.h)``, but the DSA subsystem deals with all possible combinations: - internal PHY devices, built into the Ethernet switch hardware @@ -296,16 +299,16 @@ subsystem deals with all possible combinations: - special, non-autonegotiated or non MDIO-managed PHY devices: SFPs, MoCA; a.k.a fixed PHYs -The PHY configuration is done by the dsa_slave_phy_setup() function and the +The PHY configuration is done by the ``dsa_slave_phy_setup()`` function and the logic basically looks like this: - if Device Tree is used, the PHY device is looked up using the standard "phy-handle" property, if found, this PHY device is created and registered - using of_phy_connect() + using ``of_phy_connect()`` - if Device Tree is used, and the PHY device is "fixed", that is, conforms to the definition of a non-MDIO managed PHY as defined in - Documentation/devicetree/bindings/net/fixed-link.txt, the PHY is registered + ``Documentation/devicetree/bindings/net/fixed-link.txt``, the PHY is registered and connected transparently using the special fixed MDIO bus driver - finally, if the PHY is built into the switch, as is very common with @@ -331,8 +334,8 @@ Device Tree ----------- DSA features a standardized binding which is documented in -Documentation/devicetree/bindings/net/dsa/dsa.txt. PHY/MDIO library helper -functions such as of_get_phy_mode(), of_phy_connect() are also used to query +``Documentation/devicetree/bindings/net/dsa/dsa.txt``. PHY/MDIO library helper +functions such as ``of_get_phy_mode()``, ``of_phy_connect()`` are also used to query per-port PHY specific details: interface connection, MDIO bus location etc.. Driver development @@ -341,8 +344,8 @@ Driver development DSA switch drivers need to implement a dsa_switch_ops structure which will contain the various members described below. -register_switch_driver() registers this dsa_switch_ops in its internal list -of drivers to probe for. unregister_switch_driver() does the exact opposite. +``register_switch_driver()`` registers this dsa_switch_ops in its internal list +of drivers to probe for. ``unregister_switch_driver()`` does the exact opposite. Unless requested differently by setting the priv_size member accordingly, DSA does not allocate any driver private context space. @@ -350,17 +353,17 @@ does not allocate any driver private context space. Switch configuration -------------------- -- tag_protocol: this is to indicate what kind of tagging protocol is supported, - should be a valid value from the dsa_tag_protocol enum +- ``tag_protocol``: this is to indicate what kind of tagging protocol is supported, + should be a valid value from the ``dsa_tag_protocol`` enum -- probe: probe routine which will be invoked by the DSA platform device upon +- ``probe``: probe routine which will be invoked by the DSA platform device upon registration to test for the presence/absence of a switch device. For MDIO devices, it is recommended to issue a read towards internal registers using the switch pseudo-PHY and return whether this is a supported device. For other buses, return a non-NULL string -- setup: setup function for the switch, this function is responsible for setting - up the dsa_switch_ops private structure with all it needs: register maps, +- ``setup``: setup function for the switch, this function is responsible for setting + up the ``dsa_switch_ops`` private structure with all it needs: register maps, interrupts, mutexes, locks etc.. This function is also expected to properly configure the switch to separate all network interfaces from each other, that is, they should be isolated by the switch hardware itself, typically by creating @@ -375,27 +378,27 @@ Switch configuration PHY devices and link management ------------------------------- -- get_phy_flags: Some switches are interfaced to various kinds of Ethernet PHYs, +- ``get_phy_flags``: Some switches are interfaced to various kinds of Ethernet PHYs, if the PHY library PHY driver needs to know about information it cannot obtain on its own (e.g.: coming from switch memory mapped registers), this function should return a 32-bits bitmask of "flags", that is private between the switch - driver and the Ethernet PHY driver in drivers/net/phy/*. + driver and the Ethernet PHY driver in ``drivers/net/phy/\*``. -- phy_read: Function invoked by the DSA slave MDIO bus when attempting to read +- ``phy_read``: Function invoked by the DSA slave MDIO bus when attempting to read the switch port MDIO registers. If unavailable, return 0xffff for each read. For builtin switch Ethernet PHYs, this function should allow reading the link status, auto-negotiation results, link partner pages etc.. -- phy_write: Function invoked by the DSA slave MDIO bus when attempting to write +- ``phy_write``: Function invoked by the DSA slave MDIO bus when attempting to write to the switch port MDIO registers. If unavailable return a negative error code. -- adjust_link: Function invoked by the PHY library when a slave network device +- ``adjust_link``: Function invoked by the PHY library when a slave network device is attached to a PHY device. This function is responsible for appropriately configuring the switch port link parameters: speed, duplex, pause based on - what the phy_device is providing. + what the ``phy_device`` is providing. -- fixed_link_update: Function invoked by the PHY library, and specifically by +- ``fixed_link_update``: Function invoked by the PHY library, and specifically by the fixed PHY driver asking the switch driver for link parameters that could not be auto-negotiated, or obtained by reading the PHY registers through MDIO. This is particularly useful for specific kinds of hardware such as QSGMII, @@ -405,87 +408,87 @@ PHY devices and link management Ethtool operations ------------------ -- get_strings: ethtool function used to query the driver's strings, will +- ``get_strings``: ethtool function used to query the driver's strings, will typically return statistics strings, private flags strings etc. -- get_ethtool_stats: ethtool function used to query per-port statistics and +- ``get_ethtool_stats``: ethtool function used to query per-port statistics and return their values. DSA overlays slave network devices general statistics: RX/TX counters from the network device, with switch driver specific statistics per port -- get_sset_count: ethtool function used to query the number of statistics items +- ``get_sset_count``: ethtool function used to query the number of statistics items -- get_wol: ethtool function used to obtain Wake-on-LAN settings per-port, this +- ``get_wol``: ethtool function used to obtain Wake-on-LAN settings per-port, this function may, for certain implementations also query the master network device Wake-on-LAN settings if this interface needs to participate in Wake-on-LAN -- set_wol: ethtool function used to configure Wake-on-LAN settings per-port, +- ``set_wol``: ethtool function used to configure Wake-on-LAN settings per-port, direct counterpart to set_wol with similar restrictions -- set_eee: ethtool function which is used to configure a switch port EEE (Green +- ``set_eee``: ethtool function which is used to configure a switch port EEE (Green Ethernet) settings, can optionally invoke the PHY library to enable EEE at the PHY level if relevant. This function should enable EEE at the switch port MAC controller and data-processing logic -- get_eee: ethtool function which is used to query a switch port EEE settings, +- ``get_eee``: ethtool function which is used to query a switch port EEE settings, this function should return the EEE state of the switch port MAC controller and data-processing logic as well as query the PHY for its currently configured EEE settings -- get_eeprom_len: ethtool function returning for a given switch the EEPROM +- ``get_eeprom_len``: ethtool function returning for a given switch the EEPROM length/size in bytes -- get_eeprom: ethtool function returning for a given switch the EEPROM contents +- ``get_eeprom``: ethtool function returning for a given switch the EEPROM contents -- set_eeprom: ethtool function writing specified data to a given switch EEPROM +- ``set_eeprom``: ethtool function writing specified data to a given switch EEPROM -- get_regs_len: ethtool function returning the register length for a given +- ``get_regs_len``: ethtool function returning the register length for a given switch -- get_regs: ethtool function returning the Ethernet switch internal register +- ``get_regs``: ethtool function returning the Ethernet switch internal register contents. This function might require user-land code in ethtool to pretty-print register values and registers Power management ---------------- -- suspend: function invoked by the DSA platform device when the system goes to +- ``suspend``: function invoked by the DSA platform device when the system goes to suspend, should quiesce all Ethernet switch activities, but keep ports participating in Wake-on-LAN active as well as additional wake-up logic if supported -- resume: function invoked by the DSA platform device when the system resumes, +- ``resume``: function invoked by the DSA platform device when the system resumes, should resume all Ethernet switch activities and re-configure the switch to be in a fully active state -- port_enable: function invoked by the DSA slave network device ndo_open +- ``port_enable``: function invoked by the DSA slave network device ndo_open function when a port is administratively brought up, this function should be fully enabling a given switch port. DSA takes care of marking the port with - BR_STATE_BLOCKING if the port is a bridge member, or BR_STATE_FORWARDING if it + ``BR_STATE_BLOCKING`` if the port is a bridge member, or ``BR_STATE_FORWARDING`` if it was not, and propagating these changes down to the hardware -- port_disable: function invoked by the DSA slave network device ndo_close +- ``port_disable``: function invoked by the DSA slave network device ndo_close function when a port is administratively brought down, this function should be fully disabling a given switch port. DSA takes care of marking the port with - BR_STATE_DISABLED and propagating changes to the hardware if this port is + ``BR_STATE_DISABLED`` and propagating changes to the hardware if this port is disabled while being a bridge member Bridge layer ------------ -- port_bridge_join: bridge layer function invoked when a given switch port is +- ``port_bridge_join``: bridge layer function invoked when a given switch port is added to a bridge, this function should be doing the necessary at the switch level to permit the joining port from being added to the relevant logical domain for it to ingress/egress traffic with other members of the bridge. -- port_bridge_leave: bridge layer function invoked when a given switch port is +- ``port_bridge_leave``: bridge layer function invoked when a given switch port is removed from a bridge, this function should be doing the necessary at the switch level to deny the leaving port from ingress/egress traffic from the remaining bridge members. When the port leaves the bridge, it should be aged out at the switch hardware for the switch to (re) learn MAC addresses behind this port. -- port_stp_state_set: bridge layer function invoked when a given switch port STP +- ``port_stp_state_set``: bridge layer function invoked when a given switch port STP state is computed by the bridge layer and should be propagated to switch hardware to forward/block/learn traffic. The switch driver is responsible for computing a STP state change based on current and asked parameters and perform @@ -494,7 +497,7 @@ Bridge layer Bridge VLAN filtering --------------------- -- port_vlan_filtering: bridge layer function invoked when the bridge gets +- ``port_vlan_filtering``: bridge layer function invoked when the bridge gets configured for turning on or off VLAN filtering. If nothing specific needs to be done at the hardware level, this callback does not need to be implemented. When VLAN filtering is turned on, the hardware must be programmed with @@ -504,61 +507,61 @@ Bridge VLAN filtering accept any 802.1Q frames irrespective of their VLAN ID, and untagged frames are allowed. -- port_vlan_prepare: bridge layer function invoked when the bridge prepares the +- ``port_vlan_prepare``: bridge layer function invoked when the bridge prepares the configuration of a VLAN on the given port. If the operation is not supported - by the hardware, this function should return -EOPNOTSUPP to inform the bridge + by the hardware, this function should return ``-EOPNOTSUPP`` to inform the bridge code to fallback to a software implementation. No hardware setup must be done in this function. See port_vlan_add for this and details. -- port_vlan_add: bridge layer function invoked when a VLAN is configured +- ``port_vlan_add``: bridge layer function invoked when a VLAN is configured (tagged or untagged) for the given switch port -- port_vlan_del: bridge layer function invoked when a VLAN is removed from the +- ``port_vlan_del``: bridge layer function invoked when a VLAN is removed from the given switch port -- port_vlan_dump: bridge layer function invoked with a switchdev callback +- ``port_vlan_dump``: bridge layer function invoked with a switchdev callback function that the driver has to call for each VLAN the given port is a member of. A switchdev object is used to carry the VID and bridge flags. -- port_fdb_add: bridge layer function invoked when the bridge wants to install a +- ``port_fdb_add``: bridge layer function invoked when the bridge wants to install a Forwarding Database entry, the switch hardware should be programmed with the specified address in the specified VLAN Id in the forwarding database associated with this VLAN ID. If the operation is not supported, this - function should return -EOPNOTSUPP to inform the bridge code to fallback to + function should return ``-EOPNOTSUPP`` to inform the bridge code to fallback to a software implementation. -Note: VLAN ID 0 corresponds to the port private database, which, in the context -of DSA, would be the its port-based VLAN, used by the associated bridge device. +.. note:: VLAN ID 0 corresponds to the port private database, which, in the context + of DSA, would be the its port-based VLAN, used by the associated bridge device. -- port_fdb_del: bridge layer function invoked when the bridge wants to remove a +- ``port_fdb_del``: bridge layer function invoked when the bridge wants to remove a Forwarding Database entry, the switch hardware should be programmed to delete the specified MAC address from the specified VLAN ID if it was mapped into this port forwarding database -- port_fdb_dump: bridge layer function invoked with a switchdev callback +- ``port_fdb_dump``: bridge layer function invoked with a switchdev callback function that the driver has to call for each MAC address known to be behind the given port. A switchdev object is used to carry the VID and FDB info. -- port_mdb_prepare: bridge layer function invoked when the bridge prepares the +- ``port_mdb_prepare``: bridge layer function invoked when the bridge prepares the installation of a multicast database entry. If the operation is not supported, - this function should return -EOPNOTSUPP to inform the bridge code to fallback + this function should return ``-EOPNOTSUPP`` to inform the bridge code to fallback to a software implementation. No hardware setup must be done in this function. - See port_fdb_add for this and details. + See ``port_fdb_add`` for this and details. -- port_mdb_add: bridge layer function invoked when the bridge wants to install +- ``port_mdb_add``: bridge layer function invoked when the bridge wants to install a multicast database entry, the switch hardware should be programmed with the specified address in the specified VLAN ID in the forwarding database associated with this VLAN ID. -Note: VLAN ID 0 corresponds to the port private database, which, in the context -of DSA, would be the its port-based VLAN, used by the associated bridge device. +.. note:: VLAN ID 0 corresponds to the port private database, which, in the context + of DSA, would be the its port-based VLAN, used by the associated bridge device. -- port_mdb_del: bridge layer function invoked when the bridge wants to remove a +- ``port_mdb_del``: bridge layer function invoked when the bridge wants to remove a multicast database entry, the switch hardware should be programmed to delete the specified MAC address from the specified VLAN ID if it was mapped into this port forwarding database. -- port_mdb_dump: bridge layer function invoked with a switchdev callback +- ``port_mdb_dump``: bridge layer function invoked with a switchdev callback function that the driver has to call for each MAC address known to be behind the given port. A switchdev object is used to carry the VID and MDB info. @@ -577,7 +580,7 @@ two subsystems and get the best of both worlds. Other hanging fruits -------------------- -- making the number of ports fully dynamic and not dependent on DSA_MAX_PORTS +- making the number of ports fully dynamic and not dependent on ``DSA_MAX_PORTS`` - allowing more than one CPU/management interface: http://comments.gmane.org/gmane.linux.network/365657 - porting more drivers from other vendors: diff --git a/Documentation/networking/dsa/index.rst b/Documentation/networking/dsa/index.rst new file mode 100644 index 000000000000..0e5b7a9be406 --- /dev/null +++ b/Documentation/networking/dsa/index.rst @@ -0,0 +1,11 @@ +=============================== +Distributed Switch Architecture +=============================== + +.. toctree:: + :maxdepth: 1 + + dsa + bcm_sf2 + lan9303 + sja1105 diff --git a/Documentation/networking/dsa/lan9303.txt b/Documentation/networking/dsa/lan9303.rst index 144b02b95207..e3c820db28ad 100644 --- a/Documentation/networking/dsa/lan9303.txt +++ b/Documentation/networking/dsa/lan9303.rst @@ -1,3 +1,4 @@ +============================== LAN9303 Ethernet switch driver ============================== @@ -9,10 +10,9 @@ host master network interface (e.g. fixed link). Driver details ============== -The driver is implemented as a DSA driver, see -Documentation/networking/dsa/dsa.txt. +The driver is implemented as a DSA driver, see ``Documentation/networking/dsa/dsa.rst``. -See Documentation/devicetree/bindings/net/dsa/lan9303.txt for device tree +See ``Documentation/devicetree/bindings/net/dsa/lan9303.txt`` for device tree binding. The LAN9303 can be managed both via MDIO and I2C, both supported by this driver. diff --git a/Documentation/networking/dsa/sja1105.rst b/Documentation/networking/dsa/sja1105.rst new file mode 100644 index 000000000000..ea7bac438cfd --- /dev/null +++ b/Documentation/networking/dsa/sja1105.rst @@ -0,0 +1,220 @@ +========================= +NXP SJA1105 switch driver +========================= + +Overview +======== + +The NXP SJA1105 is a family of 6 devices: + +- SJA1105E: First generation, no TTEthernet +- SJA1105T: First generation, TTEthernet +- SJA1105P: Second generation, no TTEthernet, no SGMII +- SJA1105Q: Second generation, TTEthernet, no SGMII +- SJA1105R: Second generation, no TTEthernet, SGMII +- SJA1105S: Second generation, TTEthernet, SGMII + +These are SPI-managed automotive switches, with all ports being gigabit +capable, and supporting MII/RMII/RGMII and optionally SGMII on one port. + +Being automotive parts, their configuration interface is geared towards +set-and-forget use, with minimal dynamic interaction at runtime. They +require a static configuration to be composed by software and packed +with CRC and table headers, and sent over SPI. + +The static configuration is composed of several configuration tables. Each +table takes a number of entries. Some configuration tables can be (partially) +reconfigured at runtime, some not. Some tables are mandatory, some not: + +============================= ================== ============================= +Table Mandatory Reconfigurable +============================= ================== ============================= +Schedule no no +Schedule entry points if Scheduling no +VL Lookup no no +VL Policing if VL Lookup no +VL Forwarding if VL Lookup no +L2 Lookup no no +L2 Policing yes no +VLAN Lookup yes yes +L2 Forwarding yes partially (fully on P/Q/R/S) +MAC Config yes partially (fully on P/Q/R/S) +Schedule Params if Scheduling no +Schedule Entry Points Params if Scheduling no +VL Forwarding Params if VL Forwarding no +L2 Lookup Params no partially (fully on P/Q/R/S) +L2 Forwarding Params yes no +Clock Sync Params no no +AVB Params no no +General Params yes partially +Retagging no yes +xMII Params yes no +SGMII no yes +============================= ================== ============================= + + +Also the configuration is write-only (software cannot read it back from the +switch except for very few exceptions). + +The driver creates a static configuration at probe time, and keeps it at +all times in memory, as a shadow for the hardware state. When required to +change a hardware setting, the static configuration is also updated. +If that changed setting can be transmitted to the switch through the dynamic +reconfiguration interface, it is; otherwise the switch is reset and +reprogrammed with the updated static configuration. + +Traffic support +=============== + +The switches do not support switch tagging in hardware. But they do support +customizing the TPID by which VLAN traffic is identified as such. The switch +driver is leveraging ``CONFIG_NET_DSA_TAG_8021Q`` by requesting that special +VLANs (with a custom TPID of ``ETH_P_EDSA`` instead of ``ETH_P_8021Q``) are +installed on its ports when not in ``vlan_filtering`` mode. This does not +interfere with the reception and transmission of real 802.1Q-tagged traffic, +because the switch does no longer parse those packets as VLAN after the TPID +change. +The TPID is restored when ``vlan_filtering`` is requested by the user through +the bridge layer, and general IP termination becomes no longer possible through +the switch netdevices in this mode. + +The switches have two programmable filters for link-local destination MACs. +These are used to trap BPDUs and PTP traffic to the master netdevice, and are +further used to support STP and 1588 ordinary clock/boundary clock +functionality. + +The following traffic modes are supported over the switch netdevices: + ++--------------------+------------+------------------+------------------+ +| | Standalone | Bridged with | Bridged with | +| | ports | vlan_filtering 0 | vlan_filtering 1 | ++====================+============+==================+==================+ +| Regular traffic | Yes | Yes | No (use master) | ++--------------------+------------+------------------+------------------+ +| Management traffic | Yes | Yes | Yes | +| (BPDU, PTP) | | | | ++--------------------+------------+------------------+------------------+ + +Switching features +================== + +The driver supports the configuration of L2 forwarding rules in hardware for +port bridging. The forwarding, broadcast and flooding domain between ports can +be restricted through two methods: either at the L2 forwarding level (isolate +one bridge's ports from another's) or at the VLAN port membership level +(isolate ports within the same bridge). The final forwarding decision taken by +the hardware is a logical AND of these two sets of rules. + +The hardware tags all traffic internally with a port-based VLAN (pvid), or it +decodes the VLAN information from the 802.1Q tag. Advanced VLAN classification +is not possible. Once attributed a VLAN tag, frames are checked against the +port's membership rules and dropped at ingress if they don't match any VLAN. +This behavior is available when switch ports are enslaved to a bridge with +``vlan_filtering 1``. + +Normally the hardware is not configurable with respect to VLAN awareness, but +by changing what TPID the switch searches 802.1Q tags for, the semantics of a +bridge with ``vlan_filtering 0`` can be kept (accept all traffic, tagged or +untagged), and therefore this mode is also supported. + +Segregating the switch ports in multiple bridges is supported (e.g. 2 + 2), but +all bridges should have the same level of VLAN awareness (either both have +``vlan_filtering`` 0, or both 1). Also an inevitable limitation of the fact +that VLAN awareness is global at the switch level is that once a bridge with +``vlan_filtering`` enslaves at least one switch port, the other un-bridged +ports are no longer available for standalone traffic termination. + +Topology and loop detection through STP is supported. + +L2 FDB manipulation (add/delete/dump) is currently possible for the first +generation devices. Aging time of FDB entries, as well as enabling fully static +management (no address learning and no flooding of unknown traffic) is not yet +configurable in the driver. + +A special comment about bridging with other netdevices (illustrated with an +example): + +A board has eth0, eth1, swp0@eth1, swp1@eth1, swp2@eth1, swp3@eth1. +The switch ports (swp0-3) are under br0. +It is desired that eth0 is turned into another switched port that communicates +with swp0-3. + +If br0 has vlan_filtering 0, then eth0 can simply be added to br0 with the +intended results. +If br0 has vlan_filtering 1, then a new br1 interface needs to be created that +enslaves eth0 and eth1 (the DSA master of the switch ports). This is because in +this mode, the switch ports beneath br0 are not capable of regular traffic, and +are only used as a conduit for switchdev operations. + +Device Tree bindings and board design +===================================== + +This section references ``Documentation/devicetree/bindings/net/dsa/sja1105.txt`` +and aims to showcase some potential switch caveats. + +RMII PHY role and out-of-band signaling +--------------------------------------- + +In the RMII spec, the 50 MHz clock signals are either driven by the MAC or by +an external oscillator (but not by the PHY). +But the spec is rather loose and devices go outside it in several ways. +Some PHYs go against the spec and may provide an output pin where they source +the 50 MHz clock themselves, in an attempt to be helpful. +On the other hand, the SJA1105 is only binary configurable - when in the RMII +MAC role it will also attempt to drive the clock signal. To prevent this from +happening it must be put in RMII PHY role. +But doing so has some unintended consequences. +In the RMII spec, the PHY can transmit extra out-of-band signals via RXD[1:0]. +These are practically some extra code words (/J/ and /K/) sent prior to the +preamble of each frame. The MAC does not have this out-of-band signaling +mechanism defined by the RMII spec. +So when the SJA1105 port is put in PHY role to avoid having 2 drivers on the +clock signal, inevitably an RMII PHY-to-PHY connection is created. The SJA1105 +emulates a PHY interface fully and generates the /J/ and /K/ symbols prior to +frame preambles, which the real PHY is not expected to understand. So the PHY +simply encodes the extra symbols received from the SJA1105-as-PHY onto the +100Base-Tx wire. +On the other side of the wire, some link partners might discard these extra +symbols, while others might choke on them and discard the entire Ethernet +frames that follow along. This looks like packet loss with some link partners +but not with others. +The take-away is that in RMII mode, the SJA1105 must be let to drive the +reference clock if connected to a PHY. + +RGMII fixed-link and internal delays +------------------------------------ + +As mentioned in the bindings document, the second generation of devices has +tunable delay lines as part of the MAC, which can be used to establish the +correct RGMII timing budget. +When powered up, these can shift the Rx and Tx clocks with a phase difference +between 73.8 and 101.7 degrees. +The catch is that the delay lines need to lock onto a clock signal with a +stable frequency. This means that there must be at least 2 microseconds of +silence between the clock at the old vs at the new frequency. Otherwise the +lock is lost and the delay lines must be reset (powered down and back up). +In RGMII the clock frequency changes with link speed (125 MHz at 1000 Mbps, 25 +MHz at 100 Mbps and 2.5 MHz at 10 Mbps), and link speed might change during the +AN process. +In the situation where the switch port is connected through an RGMII fixed-link +to a link partner whose link state life cycle is outside the control of Linux +(such as a different SoC), then the delay lines would remain unlocked (and +inactive) until there is manual intervention (ifdown/ifup on the switch port). +The take-away is that in RGMII mode, the switch's internal delays are only +reliable if the link partner never changes link speeds, or if it does, it does +so in a way that is coordinated with the switch port (practically, both ends of +the fixed-link are under control of the same Linux system). +As to why would a fixed-link interface ever change link speeds: there are +Ethernet controllers out there which come out of reset in 100 Mbps mode, and +their driver inevitably needs to change the speed and clock frequency if it's +required to work at gigabit. + +MDIO bus and PHY management +--------------------------- + +The SJA1105 does not have an MDIO bus and does not perform in-band AN either. +Therefore there is no link state notification coming from the switch device. +A board would need to hook up the PHYs connected to the switch to any other +MDIO bus available to Linux within the system (e.g. to the DSA master's MDIO +bus). Link state management then works by the driver manually keeping in sync +(over SPI commands) the MAC link speed with the settings negotiated by the PHY. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 984e68f9e026..f390fe3cfdfb 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -9,7 +9,6 @@ Contents: netdev-FAQ af_xdp batman-adv - bpf_flow_dissector can can_ucan_protocol device_drivers/freescale/dpaa2/index @@ -25,6 +24,7 @@ Contents: device_drivers/intel/i40e device_drivers/intel/iavf device_drivers/intel/ice + dsa/index devlink-info-versions ieee802154 kapi diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index c4ac35234f05..725b8bea58a7 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -81,6 +81,11 @@ fib_multipath_hash_policy - INTEGER 0 - Layer 3 1 - Layer 4 +fib_sync_mem - UNSIGNED INTEGER + Amount of dirty memory from fib entries that can be backlogged before + synchronize_rcu is forced. + Default: 512kB Minimum: 64kB Maximum: 64MB + ip_forward_update_priority - INTEGER Whether to update SKB priority from "TOS" field in IPv4 header after it is forwarded. The new SKB priority is mapped from TOS field value @@ -1910,16 +1915,41 @@ enhanced_dad - BOOLEAN icmp/*: ratelimit - INTEGER - Limit the maximal rates for sending ICMPv6 packets. + Limit the maximal rates for sending ICMPv6 messages. 0 to disable any limiting, otherwise the minimal space between responses in milliseconds. Default: 1000 +ratemask - list of comma separated ranges + For ICMPv6 message types matching the ranges in the ratemask, limit + the sending of the message according to ratelimit parameter. + + The format used for both input and output is a comma separated + list of ranges (e.g. "0-127,129" for ICMPv6 message type 0 to 127 and + 129). Writing to the file will clear all previous ranges of ICMPv6 + message types and update the current list with the input. + + Refer to: https://www.iana.org/assignments/icmpv6-parameters/icmpv6-parameters.xhtml + for numerical values of ICMPv6 message types, e.g. echo request is 128 + and echo reply is 129. + + Default: 0-1,3-127 (rate limit ICMPv6 errors except Packet Too Big) + echo_ignore_all - BOOLEAN If set non-zero, then the kernel will ignore all ICMP ECHO requests sent to it over the IPv6 protocol. Default: 0 +echo_ignore_multicast - BOOLEAN + If set non-zero, then the kernel will ignore all ICMP ECHO + requests sent to it over the IPv6 protocol via multicast. + Default: 0 + +echo_ignore_anycast - BOOLEAN + If set non-zero, then the kernel will ignore all ICMP ECHO + requests sent to it over the IPv6 protocol destined to anycast address. + Default: 0 + xfrm6_gc_thresh - INTEGER (Obsolete since linux-4.14) The threshold at which we will start garbage collecting for IPv6 diff --git a/Documentation/ntb.txt b/Documentation/ntb.txt index a043854d28df..074a423c853c 100644 --- a/Documentation/ntb.txt +++ b/Documentation/ntb.txt @@ -41,9 +41,10 @@ mainly used to perform the proper memory window initialization. Typically there are two types of memory window interfaces supported by the NTB API: inbound translation configured on the local ntb port and outbound translation configured by the peer, on the peer ntb port. The first type is -depicted on the next figure +depicted on the next figure:: + + Inbound translation: -Inbound translation: Memory: Local NTB Port: Peer NTB Port: Peer MMIO: ____________ | dma-mapped |-ntb_mw_set_trans(addr) | @@ -58,9 +59,10 @@ maps corresponding outbound memory window so to have access to the shared memory region. The second type of interface, that implies the shared windows being -initialized by a peer device, is depicted on the figure: +initialized by a peer device, is depicted on the figure:: + + Outbound translation: -Outbound translation: Memory: Local NTB Port: Peer NTB Port: Peer MMIO: ____________ ______________ | dma-mapped | | | MW base addr |<== memory-mapped IO @@ -75,11 +77,13 @@ outbound memory window so to have access to the shared memory region. As one can see the described scenarios can be combined in one portable algorithm. + Local device: 1) Allocate memory for a shared window 2) Initialize memory window by translated address of the allocated region (it may fail if local memory window initialization is unsupported) 3) Send the translated address and memory window index to a peer device + Peer device: 1) Initialize memory window with retrieved address of the allocated by another device memory region (it may fail if peer memory window @@ -88,6 +92,7 @@ algorithm. In accordance with this scenario, the NTB Memory Window API can be used as follows: + Local device: 1) ntb_mw_count(pidx) - retrieve number of memory ranges, which can be allocated for memory windows between local device and peer device @@ -103,6 +108,7 @@ follows: 5) Send translated base address (usually together with memory window number) to the peer device using, for instance, scratchpad or message registers. + Peer device: 1) ntb_peer_mw_set_trans(pidx, midx) - try to set received from other device (related to pidx) translated address for specified memory diff --git a/Documentation/packing.txt b/Documentation/packing.txt new file mode 100644 index 000000000000..f830c98645f1 --- /dev/null +++ b/Documentation/packing.txt @@ -0,0 +1,149 @@ +================================================ +Generic bitfield packing and unpacking functions +================================================ + +Problem statement +----------------- + +When working with hardware, one has to choose between several approaches of +interfacing with it. +One can memory-map a pointer to a carefully crafted struct over the hardware +device's memory region, and access its fields as struct members (potentially +declared as bitfields). But writing code this way would make it less portable, +due to potential endianness mismatches between the CPU and the hardware device. +Additionally, one has to pay close attention when translating register +definitions from the hardware documentation into bit field indices for the +structs. Also, some hardware (typically networking equipment) tends to group +its register fields in ways that violate any reasonable word boundaries +(sometimes even 64 bit ones). This creates the inconvenience of having to +define "high" and "low" portions of register fields within the struct. +A more robust alternative to struct field definitions would be to extract the +required fields by shifting the appropriate number of bits. But this would +still not protect from endianness mismatches, except if all memory accesses +were performed byte-by-byte. Also the code can easily get cluttered, and the +high-level idea might get lost among the many bit shifts required. +Many drivers take the bit-shifting approach and then attempt to reduce the +clutter with tailored macros, but more often than not these macros take +shortcuts that still prevent the code from being truly portable. + +The solution +------------ + +This API deals with 2 basic operations: + - Packing a CPU-usable number into a memory buffer (with hardware + constraints/quirks) + - Unpacking a memory buffer (which has hardware constraints/quirks) + into a CPU-usable number. + +The API offers an abstraction over said hardware constraints and quirks, +over CPU endianness and therefore between possible mismatches between +the two. + +The basic unit of these API functions is the u64. From the CPU's +perspective, bit 63 always means bit offset 7 of byte 7, albeit only +logically. The question is: where do we lay this bit out in memory? + +The following examples cover the memory layout of a packed u64 field. +The byte offsets in the packed buffer are always implicitly 0, 1, ... 7. +What the examples show is where the logical bytes and bits sit. + +1. Normally (no quirks), we would do it like this: + +63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 +7 6 5 4 +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 +3 2 1 0 + +That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the +LSByte (0) of the u64 sits at memory offset 7. +This corresponds to what most folks would regard to as "big endian", where +bit i corresponds to the number 2^i. This is also referred to in the code +comments as "logical" notation. + + +2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this: + +56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 +7 6 5 4 +24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 +3 2 1 0 + +That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but +inverts bit offsets inside a byte. + + +3. If QUIRK_LITTLE_ENDIAN is set, we do it like this: + +39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 +4 5 6 7 +7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 +0 1 2 3 + +Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every +byte from each 4-byte word is placed at its mirrored position compared to +the boundary of that word. + +4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it + like this: + +32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 +4 5 6 7 +0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 +0 1 2 3 + + +5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this: + +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 +3 2 1 0 +63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 +7 6 5 4 + +In this case the 8 byte memory region is interpreted as follows: first +4 bytes correspond to the least significant 4-byte word, next 4 bytes to +the more significant 4-byte word. + + +6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like + this: + +24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 +3 2 1 0 +56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 +7 6 5 4 + + +7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like + this: + +7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 +0 1 2 3 +39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 +4 5 6 7 + + +8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT + are set, it looks like this: + +0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 +0 1 2 3 +32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 +4 5 6 7 + + +We always think of our offsets as if there were no quirk, and we translate +them afterwards, before accessing the memory region. + +Intended use +------------ + +Drivers that opt to use this API first need to identify which of the above 3 +quirk combinations (for a total of 8) match what the hardware documentation +describes. Then they should wrap the packing() function, creating a new +xxx_packing() that calls it using the proper QUIRK_* one-hot bits set. + +The packing() function returns an int-encoded error code, which protects the +programmer against incorrect API use. The errors are not expected to occur +durring runtime, therefore it is reasonable for xxx_packing() to return void +and simply swallow those errors. Optionally it can dump stack or print the +error description. diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/DAWR-POWER9.txt index 2feaa6619658..ecdbb076438c 100644 --- a/Documentation/powerpc/DAWR-POWER9.txt +++ b/Documentation/powerpc/DAWR-POWER9.txt @@ -1,10 +1,10 @@ DAWR issues on POWER9 ============================ -On POWER9 the DAWR can cause a checkstop if it points to cache -inhibited (CI) memory. Currently Linux has no way to disinguish CI -memory when configuring the DAWR, so (for now) the DAWR is disabled by -this commit: +On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop +if it points to cache inhibited (CI) memory. Currently Linux has no way to +disinguish CI memory when configuring the DAWR, so (for now) the DAWR is +disabled by this commit: commit 9654153158d3e0684a1bdb76dbababdb7111d5a0 Author: Michael Neuling <mikey@neuling.org> @@ -56,3 +56,35 @@ POWER9. Loads and stores to the watchpoint locations will not be trapped in GDB. The watchpoint is remembered, so if the guest is migrated back to the POWER8 host, it will start working again. +Force enabling the DAWR +============================= +Kernels (since ~v5.2) have an option to force enable the DAWR via: + + echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous + +This enables the DAWR even on POWER9. + +This is a dangerous setting, USE AT YOUR OWN RISK. + +Some users may not care about a bad user crashing their box +(ie. single user/desktop systems) and really want the DAWR. This +allows them to force enable DAWR. + +This flag can also be used to disable DAWR access. Once this is +cleared, all DAWR access should be cleared immediately and your +machine once again safe from crashing. + +Userspace may get confused by toggling this. If DAWR is force +enabled/disabled between getting the number of breakpoints (via +PTRACE_GETHWDBGINFO) and setting the breakpoint, userspace will get an +inconsistent view of what's available. Similarly for guests. + +For the DAWR to be enabled in a KVM guest, the DAWR needs to be force +enabled in the host AND the guest. For this reason, this won't work on +POWERVM as it doesn't allow the HCALL to work. Writes of 'Y' to the +dawr_enable_dangerous file will fail if the hypervisor doesn't support +writing the DAWR. + +To double check the DAWR is working, run this kernel selftest: + tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c +Any errors/failures/skips mean something is wrong. diff --git a/Documentation/preempt-locking.txt b/Documentation/preempt-locking.txt index 509f5a422d57..dce336134e54 100644 --- a/Documentation/preempt-locking.txt +++ b/Documentation/preempt-locking.txt @@ -52,7 +52,6 @@ preemption must be disabled around such regions. Note, some FPU functions are already explicitly preempt safe. For example, kernel_fpu_begin and kernel_fpu_end will disable and enable preemption. -However, fpu__restore() must be called with preemption disabled. RULE #3: Lock acquire and release must be performed by same task diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 4213e580f273..855a70b80269 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -216,10 +216,12 @@ The tags in common use are: which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` Code without a proper signoff cannot be merged into the mainline. - - Co-developed-by: states that the patch was also created by another developer - along with the original author. This is useful at times when multiple - people work on a single patch. Note, this person also needs to have a - Signed-off-by: line in the patch as well. + - Co-developed-by: states that the patch was co-created by several developers; + it is a used to give attribution to co-authors (in addition to the author + attributed by the From: tag) when multiple people work on a single patch. + Every Co-developed-by: must be immediately followed by a Signed-off-by: of + the associated co-author. Details and examples can be found in + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. - Acked-by: indicates an agreement by another developer (often a maintainer of the relevant code) that the patch is appropriate for diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 8ea913e99fa1..fa864a51e6ea 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -843,7 +843,8 @@ used. The kernel provides the following general purpose memory allocators: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and vzalloc(). Please refer to the API documentation for further information -about them. +about them. :ref:`Documentation/core-api/memory-allocation.rst +<memory_allocation>` The preferred form for passing a size of a struct is the following: @@ -874,6 +875,9 @@ The preferred form for allocating a zeroed array is the following: Both forms check for overflow on the allocation size n * sizeof(...), and return NULL if that occurred. +These generic allocation functions all emit a stack dump on failure when used +without __GFP_NOWARN so there is no use in emitting an additional failure +message when NULL is returned. 15) The inline disease ---------------------- diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 0ef5a63c06ba..49e0f64a3427 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _deprecated: + ===================================================================== Deprecated Interfaces, Language Features, Attributes, and Conventions ===================================================================== diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index ad2b6c852b95..6ab75c11d2c3 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -62,7 +62,7 @@ Legal Issues The Linux kernel source code is released under the GPL. Please see the file COPYING in the main directory of the source tree. The Linux kernel licensing rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are -descibed in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`. +described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`. If you have further questions about the license, please contact a lawyer, and do not ask on the Linux kernel mailing list. The people on the mailing lists are not lawyers, and you should not rely on their statements on legal matters. diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index ab12dddc773e..7a45a8e36ea7 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -95,18 +95,6 @@ On-line docs [...]. This paper examines some common problems for submitting larger changes and some strategies to avoid problems. - * Title: **Overview of the Virtual File System** - - :Author: Richard Gooch. - :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt - :Date: 2007 - :Keywords: VFS, File System, mounting filesystems, opening files, - dentries, dcache. - :Description: Brief introduction to the Linux Virtual File System. - What is it, how it works, operations taken when opening a file or - mounting a file system and description of important data - structures explaining the purpose of each of their entries. - * Title: **Linux Device Drivers, Third Edition** :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst index 6b09033a8e9e..2ef44ada3f11 100644 --- a/Documentation/process/license-rules.rst +++ b/Documentation/process/license-rules.rst @@ -234,13 +234,13 @@ kernel, can be broken down into: | -2. Not recommended licenses: +2. Deprecated licenses: These licenses should only be used for existing code or for importing code from a different project. These licenses are available from the directory:: - LICENSES/other/ + LICENSES/deprecated/ in the kernel source tree. @@ -250,14 +250,14 @@ kernel, can be broken down into: Examples:: - LICENSES/other/ISC + LICENSES/deprecated/ISC Contains the Internet Systems Consortium license text and the required metatags:: - LICENSES/other/ZLib + LICENSES/deprecated/GPL-1.0 - Contains the ZLIB license text and the required metatags. + Contains the GPL version 1 license text and the required metatags. Metatags: @@ -281,7 +281,56 @@ kernel, can be broken down into: | -3. _`Exceptions`: +3. Dual Licensing Only + + These licenses should only be used to dual license code with another + license in addition to a preferred license. These licenses are available + from the directory:: + + LICENSES/dual/ + + in the kernel source tree. + + The files in this directory contain the full license text and + `Metatags`_. The file names are identical to the SPDX license + identifier which shall be used for the license in source files. + + Examples:: + + LICENSES/dual/MPL-1.1 + + Contains the Mozilla Public License version 1.1 license text and the + required metatags:: + + LICENSES/dual/Apache-2.0 + + Contains the Apache License version 2.0 license text and the required + metatags. + + Metatags: + + The metatag requirements for 'other' licenses are identical to the + requirements of the `Preferred licenses`_. + + File format example:: + + Valid-License-Identifier: MPL-1.1 + SPDX-URL: https://spdx.org/licenses/MPL-1.1.html + Usage-Guide: + Do NOT use. The MPL-1.1 is not GPL2 compatible. It may only be used for + dual-licensed files where the other license is GPL2 compatible. + If you end up using this it MUST be used together with a GPL2 compatible + license using "OR". + To use the Mozilla Public License version 1.1 put the following SPDX + tag/value pair into a comment according to the placement guidelines in + the licensing rules documentation: + SPDX-License-Identifier: MPL-1.1 + License-Text: + Full license text + +| + +4. _`Exceptions`: Some licenses can be amended with exceptions which grant certain rights which the original license does not. These exceptions are available diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index aff9b1a4d77b..4bab7464ff8c 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -943,7 +943,7 @@ have on your keyring:: Next, open the `PGP pathfinder`_. In the "From" field, paste the key fingerprint of Linus Torvalds from the output above. In the "To" field, -paste they key-id you found via ``gpg --search`` of the unknown key, and +paste the key-id you found via ``gpg --search`` of the unknown key, and check the results: - `Finding paths to Linus`_ diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 367353c54949..c88867b173d9 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -72,47 +72,44 @@ and elsewhere regarding submitting Linux kernel patches. 13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and ``CONFIG_PREEMPT.`` -14) If the patch affects IO/Disk, etc: has been tested with and without - ``CONFIG_LBDAF.`` +16) All codepaths have been exercised with all lockdep features enabled. -15) All codepaths have been exercised with all lockdep features enabled. +17) All new ``/proc`` entries are documented under ``Documentation/`` -16) All new ``/proc`` entries are documented under ``Documentation/`` - -17) All new kernel boot parameters are documented in +18) All new kernel boot parameters are documented in ``Documentation/admin-guide/kernel-parameters.rst``. -18) All new module parameters are documented with ``MODULE_PARM_DESC()`` +19) All new module parameters are documented with ``MODULE_PARM_DESC()`` -19) All new userspace interfaces are documented in ``Documentation/ABI/``. +20) All new userspace interfaces are documented in ``Documentation/ABI/``. See ``Documentation/ABI/README`` for more information. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. -20) Check that it all passes ``make headers_check``. +21) Check that it all passes ``make headers_check``. -21) Has been checked with injection of at least slab and page-allocation +22) Has been checked with injection of at least slab and page-allocation failures. See ``Documentation/fault-injection/``. If the new code is substantial, addition of subsystem-specific fault injection might be appropriate. -22) Newly-added code has been compiled with ``gcc -W`` (use +23) Newly-added code has been compiled with ``gcc -W`` (use ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good for finding bugs like "warning: comparison between signed and unsigned". -23) Tested after it has been merged into the -mm patchset to make sure +24) Tested after it has been merged into the -mm patchset to make sure that it still works with all of the other queued patches and various changes in the VM, VFS, and other subsystems. -24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a +25) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a comment in the source code that explains the logic of what they are doing and why. -25) If any ioctl's are added by the patch, then also update +26) If any ioctl's are added by the patch, then also update ``Documentation/ioctl/ioctl-number.txt``. -26) If your modified source code depends on or uses any of the kernel +27) If your modified source code depends on or uses any of the kernel APIs or features that are related to the following ``Kconfig`` symbols, then test multiple builds with the related ``Kconfig`` symbols disabled and/or ``=m`` (if that option is available) [not all of these at the diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index be7d1829c3af..9c4299293c72 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -60,8 +60,8 @@ not in any lower subdirectory. To create a patch for a single file, it is often sufficient to do:: - SRCTREE= linux - MYFILE= drivers/net/mydriver.c + SRCTREE=linux + MYFILE=drivers/net/mydriver.c cd $SRCTREE cp $MYFILE $MYFILE.orig @@ -73,7 +73,7 @@ To create a patch for multiple files, you should unpack a "vanilla", or unmodified kernel source tree, and generate a ``diff`` against your own source tree. For example:: - MYSRC= /devel/linux + MYSRC=/devel/linux tar xvfz linux-3.19.tar.gz mv linux-3.19 linux-3.19-vanilla @@ -545,10 +545,40 @@ person it names - but it should indicate that this person was copied on the patch. This tag documents that potentially interested parties have been included in the discussion. -A Co-developed-by: states that the patch was also created by another developer -along with the original author. This is useful at times when multiple people -work on a single patch. Note, this person also needs to have a Signed-off-by: -line in the patch as well. +Co-developed-by: states that the patch was co-created by multiple developers; +it is a used to give attribution to co-authors (in addition to the author +attributed by the From: tag) when several people work on a single patch. Since +Co-developed-by: denotes authorship, every Co-developed-by: must be immediately +followed by a Signed-off-by: of the associated co-author. Standard sign-off +procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the +chronological history of the patch insofar as possible, regardless of whether +the author is attributed via From: or Co-developed-by:. Notably, the last +Signed-off-by: must always be that of the developer submitting the patch. + +Note, the From: tag is optional when the From: author is also the person (and +email) listed in the From: line of the email header. + +Example of a patch submitted by the From: author:: + + <changelog> + + Co-developed-by: First Co-Author <first@coauthor.example.org> + Signed-off-by: First Co-Author <first@coauthor.example.org> + Co-developed-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + +Example of a patch submitted by a Co-developed-by: author:: + + From: From Author <from@author.example.org> + + <changelog> + + Co-developed-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> + Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: @@ -696,7 +726,7 @@ A couple of example Subjects:: The ``from`` line must be the very first line in the message body, and has the form: - From: Original Author <author@example.com> + From: Patch Author <author@example.com> The ``from`` line specifies who will be credited as the author of the patch in the permanent changelog. If the ``from`` line is missing, diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index a129acf38537..688c95b11919 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -136,5 +136,5 @@ a high functionality RTC is integrated into the SOC. That system might read the system clock from the discrete RTC, but use the integrated one for all other tasks, because of its greater functionality. -Check out tools/testing/selftests/timers/rtctest.c for an example usage of the +Check out tools/testing/selftests/rtc/rtctest.c for an example usage of the ioctl interface. diff --git a/Documentation/serial/README.cycladesZ b/Documentation/serial/cyclades_z.rst index 024a69443cc2..532ff67e2f1c 100644 --- a/Documentation/serial/README.cycladesZ +++ b/Documentation/serial/cyclades_z.rst @@ -1,8 +1,11 @@ +================ +Cyclades-Z notes +================ The Cyclades-Z must have firmware loaded onto the card before it will operate. This operation should be performed during system startup, The firmware, loader program and the latest device driver code are available from Cyclades at - ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/ + ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/ diff --git a/Documentation/serial/driver b/Documentation/serial/driver.rst index 86e47c19a924..4537119bf624 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver.rst @@ -1,6 +1,6 @@ - - Low Level Serial API - -------------------- +==================== +Low Level Serial API +==================== This document is meant as a brief overview of some aspects of the new serial @@ -44,7 +44,7 @@ are described in the uart_ops listing below.) There are two locks. A per-port spinlock, and an overall semaphore. From the core driver perspective, the port->lock locks the following -data: +data:: port->mctrl port->icount @@ -75,41 +75,51 @@ hardware. return TIOCSER_TEMT. Locking: none. + Interrupts: caller dependent. + This call must not sleep set_mctrl(port, mctrl) This function sets the modem control lines for port described by 'port' to the state described by mctrl. The relevant bits of mctrl are: + - TIOCM_RTS RTS signal. - TIOCM_DTR DTR signal. - TIOCM_OUT1 OUT1 signal. - TIOCM_OUT2 OUT2 signal. - TIOCM_LOOP Set the port into loopback mode. + If the appropriate bit is set, the signal should be driven active. If the bit is clear, the signal should be driven inactive. Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep get_mctrl(port) Returns the current state of modem control inputs. The state of the outputs should not be returned, since the core keeps track of their state. The state information should include: + - TIOCM_CAR state of DCD signal - TIOCM_CTS state of CTS signal - TIOCM_DSR state of DSR signal - TIOCM_RI state of RI signal + The bit is set if the signal is currently driven active. If the port does not support CTS, DCD or DSR, the driver should indicate that the signal is permanently active. If RI is not available, the signal should not be indicated as active. Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep stop_tx(port) @@ -121,14 +131,18 @@ hardware. possible. Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep start_tx(port) Start transmitting characters. Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep throttle(port) @@ -138,16 +152,17 @@ hardware. This will be called only if hardware assisted flow control is enabled. Locking: serialized with .unthrottle() and termios modification by the - tty layer. + tty layer. unthrottle(port) Notify the serial driver that characters can now be sent to the serial port without fear of overrunning the input buffers of the line disciplines. + This will be called only if hardware assisted flow control is enabled. Locking: serialized with .throttle() and termios modification by the - tty layer. + tty layer. send_xchar(port,ch) Transmit a high priority character, even if the port is stopped. @@ -159,6 +174,7 @@ hardware. Do not transmit if ch == '\0' (__DISABLED_CHAR). Locking: none. + Interrupts: caller dependent. stop_rx(port) @@ -166,7 +182,9 @@ hardware. being closed. Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep enable_ms(port) @@ -177,7 +195,9 @@ hardware. called. Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep break_ctl(port,ctl) @@ -196,6 +216,7 @@ hardware. This method will only be called when the port is initially opened. Locking: port_sem taken. + Interrupts: globally disabled. shutdown(port) @@ -210,6 +231,7 @@ hardware. this port. Locking: port_sem taken. + Interrupts: caller dependent. flush_buffer(port) @@ -220,7 +242,9 @@ hardware. buffer is cleared. Locking: port->lock taken. + Interrupts: locally disabled. + This call must not sleep set_termios(port,termios,oldtermios) @@ -228,29 +252,46 @@ hardware. bits. Update read_status_mask and ignore_status_mask to indicate the types of events we are interested in receiving. Relevant termios->c_cflag bits are: - CSIZE - word size - CSTOPB - 2 stop bits - PARENB - parity enable - PARODD - odd parity (when PARENB is in force) - CREAD - enable reception of characters (if not set, + + CSIZE + - word size + CSTOPB + - 2 stop bits + PARENB + - parity enable + PARODD + - odd parity (when PARENB is in force) + CREAD + - enable reception of characters (if not set, still receive characters from the port, but throw them away. - CRTSCTS - if set, enable CTS status change reporting - CLOCAL - if not set, enable modem status change + CRTSCTS + - if set, enable CTS status change reporting + CLOCAL + - if not set, enable modem status change reporting. + Relevant termios->c_iflag bits are: - INPCK - enable frame and parity error events to be + + INPCK + - enable frame and parity error events to be passed to the TTY layer. - BRKINT - PARMRK - both of these enable break events to be + BRKINT / PARMRK + - both of these enable break events to be passed to the TTY layer. - IGNPAR - ignore parity and framing errors - IGNBRK - ignore break errors, If IGNPAR is also + IGNPAR + - ignore parity and framing errors + IGNBRK + - ignore break errors, If IGNPAR is also set, ignore overrun errors as well. + The interaction of the iflag bits is as follows (parity error given as an example): + + =============== ======= ====== ============================= Parity error INPCK IGNPAR + =============== ======= ====== ============================= n/a 0 n/a character received, marked as TTY_NORMAL None 1 n/a character received, marked as @@ -258,16 +299,19 @@ hardware. Yes 1 0 character received, marked as TTY_PARITY Yes 1 1 character discarded + =============== ======= ====== ============================= Other flags may be used (eg, xon/xoff characters) if your hardware supports hardware "soft" flow control. Locking: caller holds tty_port->mutex + Interrupts: caller dependent. + This call must not sleep set_ldisc(port,termios) - Notifier for discipline change. See Documentation/serial/tty.txt. + Notifier for discipline change. See Documentation/serial/tty.rst. Locking: caller holds tty_port->mutex @@ -283,6 +327,7 @@ hardware. will occur even if CONFIG_PM is not set. Locking: none. + Interrupts: caller dependent. type(port) @@ -291,6 +336,7 @@ hardware. substituted. Locking: none. + Interrupts: caller dependent. release_port(port) @@ -298,6 +344,7 @@ hardware. the port. Locking: none. + Interrupts: caller dependent. request_port(port) @@ -306,6 +353,7 @@ hardware. returns, and it should return -EBUSY on failure. Locking: none. + Interrupts: caller dependent. config_port(port,type) @@ -321,6 +369,7 @@ hardware. internally hard wired (eg, system on a chip implementations). Locking: none. + Interrupts: caller dependent. verify_port(port,serinfo) @@ -328,6 +377,7 @@ hardware. suitable for this port type. Locking: none. + Interrupts: caller dependent. ioctl(port,cmd,arg) @@ -335,6 +385,7 @@ hardware. using the standard numbering system found in <asm/ioctl.h> Locking: none. + Interrupts: caller dependent. poll_init(port) @@ -343,6 +394,7 @@ hardware. this should not request interrupts. Locking: tty_mutex and tty_port->mutex taken. + Interrupts: n/a. poll_put_char(port,ch) @@ -350,7 +402,9 @@ hardware. port. It can and should block until there is space in the TX FIFO. Locking: none. + Interrupts: caller dependent. + This call must not sleep poll_get_char(port) @@ -359,7 +413,9 @@ hardware. the function should return NO_POLL_CHAR immediately. Locking: none. + Interrupts: caller dependent. + This call must not sleep Other functions @@ -370,6 +426,7 @@ uart_update_timeout(port,cflag,baud) number of bits, parity, stop bits and baud rate. Locking: caller is expected to take port->lock + Interrupts: n/a uart_get_baud_rate(port,termios,old,min,max) @@ -385,6 +442,7 @@ uart_get_baud_rate(port,termios,old,min,max) Note: min..max must always allow 9600 baud to be selected. Locking: caller dependent. + Interrupts: n/a uart_get_divisor(port,baud) @@ -395,6 +453,7 @@ uart_get_divisor(port,baud) custom divisor instead. Locking: caller dependent. + Interrupts: n/a uart_match_port(port1,port2) @@ -402,6 +461,7 @@ uart_match_port(port1,port2) uart_port structures describe the same port. Locking: n/a + Interrupts: n/a uart_write_wakeup(port) @@ -409,6 +469,7 @@ uart_write_wakeup(port) characters in the transmit buffer have dropped below a threshold. Locking: port->lock should be held. + Interrupts: n/a uart_register_driver(drv) @@ -419,6 +480,7 @@ uart_register_driver(drv) registered using uart_add_one_port after this call has succeeded. Locking: none + Interrupts: enabled uart_unregister_driver() @@ -427,15 +489,16 @@ uart_unregister_driver() uart_remove_one_port() if it registered them with uart_add_one_port(). Locking: none + Interrupts: enabled -uart_suspend_port() +**uart_suspend_port()** -uart_resume_port() +**uart_resume_port()** -uart_add_one_port() +**uart_add_one_port()** -uart_remove_one_port() +**uart_remove_one_port()** Other notes ----------- @@ -444,7 +507,7 @@ It is intended some day to drop the 'unused' entries from uart_port, and allow low level drivers to register their own individual uart_port's with the core. This will allow drivers to use uart_port as a pointer to a structure containing both the uart_port entry with their own extensions, -thus: +thus:: struct my_port { struct uart_port port; @@ -459,14 +522,14 @@ Some helpers are provided in order to set/get modem control lines via GPIO. mctrl_gpio_init(port, idx): This will get the {cts,rts,...}-gpios from device tree if they are present and request them, set direction etc, and return an - allocated structure. devm_* functions are used, so there's no need + allocated structure. `devm_*` functions are used, so there's no need to call mctrl_gpio_free(). As this sets up the irq handling make sure to not handle changes to the gpio input lines in your driver, too. mctrl_gpio_free(dev, gpios): This will free the requested gpios in mctrl_gpio_init(). - As devm_* functions are used, there's generally no need to call + As `devm_*` functions are used, there's generally no need to call this function. mctrl_gpio_to_gpiod(gpios, gidx) diff --git a/Documentation/serial/index.rst b/Documentation/serial/index.rst new file mode 100644 index 000000000000..d0ba22ea23bf --- /dev/null +++ b/Documentation/serial/index.rst @@ -0,0 +1,32 @@ +:orphan: + +========================== +Support for Serial devices +========================== + +.. toctree:: + :maxdepth: 1 + + + driver + tty + +Serial drivers +============== + +.. toctree:: + :maxdepth: 1 + + cyclades_z + moxa-smartio + n_gsm + rocket + serial-iso7816 + serial-rs485 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/serial/moxa-smartio b/Documentation/serial/moxa-smartio deleted file mode 100644 index 5d2a33be0bd8..000000000000 --- a/Documentation/serial/moxa-smartio +++ /dev/null @@ -1,523 +0,0 @@ -============================================================================= - MOXA Smartio/Industio Family Device Driver Installation Guide - for Linux Kernel 2.4.x, 2.6.x - Copyright (C) 2008, Moxa Inc. -============================================================================= -Date: 01/21/2008 - -Content - -1. Introduction -2. System Requirement -3. Installation - 3.1 Hardware installation - 3.2 Driver files - 3.3 Device naming convention - 3.4 Module driver configuration - 3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x. - 3.6 Custom configuration - 3.7 Verify driver installation -4. Utilities -5. Setserial -6. Troubleshooting - ------------------------------------------------------------------------------ -1. Introduction - - The Smartio/Industio/UPCI family Linux driver supports following multiport - boards. - - - 2 ports multiport board - CP-102U, CP-102UL, CP-102UF - CP-132U-I, CP-132UL, - CP-132, CP-132I, CP132S, CP-132IS, - CI-132, CI-132I, CI-132IS, - (C102H, C102HI, C102HIS, C102P, CP-102, CP-102S) - - - 4 ports multiport board - CP-104EL, - CP-104UL, CP-104JU, - CP-134U, CP-134U-I, - C104H/PCI, C104HS/PCI, - CP-114, CP-114I, CP-114S, CP-114IS, CP-114UL, - C104H, C104HS, - CI-104J, CI-104JS, - CI-134, CI-134I, CI-134IS, - (C114HI, CT-114I, C104P) - POS-104UL, - CB-114, - CB-134I - - - 8 ports multiport board - CP-118EL, CP-168EL, - CP-118U, CP-168U, - C168H/PCI, - C168H, C168HS, - (C168P), - CB-108 - - This driver and installation procedure have been developed upon Linux Kernel - 2.4.x and 2.6.x. This driver supports Intel x86 hardware platform. In order - to maintain compatibility, this version has also been properly tested with - RedHat, Mandrake, Fedora and S.u.S.E Linux. However, if compatibility problem - occurs, please contact Moxa at support@moxa.com.tw. - - In addition to device driver, useful utilities are also provided in this - version. They are - - msdiag Diagnostic program for displaying installed Moxa - Smartio/Industio boards. - - msmon Monitor program to observe data count and line status signals. - - msterm A simple terminal program which is useful in testing serial - ports. - - io-irq.exe Configuration program to setup ISA boards. Please note that - this program can only be executed under DOS. - - All the drivers and utilities are published in form of source code under - GNU General Public License in this version. Please refer to GNU General - Public License announcement in each source code file for more detail. - - In Moxa's Web sites, you may always find latest driver at http://www.moxa.com/. - - This version of driver can be installed as Loadable Module (Module driver) - or built-in into kernel (Static driver). You may refer to following - installation procedure for suitable one. Before you install the driver, - please refer to hardware installation procedure in the User's Manual. - - We assume the user should be familiar with following documents. - - Serial-HOWTO - - Kernel-HOWTO - ------------------------------------------------------------------------------ -2. System Requirement - - Hardware platform: Intel x86 machine - - Kernel version: 2.4.x or 2.6.x - - gcc version 2.72 or later - - Maximum 4 boards can be installed in combination - ------------------------------------------------------------------------------ -3. Installation - - 3.1 Hardware installation - 3.2 Driver files - 3.3 Device naming convention - 3.4 Module driver configuration - 3.5 Static driver configuration for Linux kernel 2.4.x, 2.6.x. - 3.6 Custom configuration - 3.7 Verify driver installation - - - 3.1 Hardware installation - - There are two types of buses, ISA and PCI, for Smartio/Industio - family multiport board. - - ISA board - --------- - You'll have to configure CAP address, I/O address, Interrupt Vector - as well as IRQ before installing this driver. Please refer to hardware - installation procedure in User's Manual before proceed any further. - Please make sure the JP1 is open after the ISA board is set properly. - - PCI/UPCI board - -------------- - You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict - with other ISA devices. Please refer to hardware installation - procedure in User's Manual in advance. - - PCI IRQ Sharing - ----------- - Each port within the same multiport board shares the same IRQ. Up to - 4 Moxa Smartio/Industio PCI Family multiport boards can be installed - together on one system and they can share the same IRQ. - - - 3.2 Driver files - - The driver file may be obtained from ftp, CD-ROM or floppy disk. The - first step, anyway, is to copy driver file "mxser.tgz" into specified - directory. e.g. /moxa. The execute commands as below. - - # cd / - # mkdir moxa - # cd /moxa - # tar xvf /dev/fd0 - - or - - # cd / - # mkdir moxa - # cd /moxa - # cp /mnt/cdrom/<driver directory>/mxser.tgz . - # tar xvfz mxser.tgz - - - 3.3 Device naming convention - - You may find all the driver and utilities files in /moxa/mxser. - Following installation procedure depends on the model you'd like to - run the driver. If you prefer module driver, please refer to 3.4. - If static driver is required, please refer to 3.5. - - Dialin and callout port - ----------------------- - This driver remains traditional serial device properties. There are - two special file name for each serial port. One is dial-in port - which is named "ttyMxx". For callout port, the naming convention - is "cumxx". - - Device naming when more than 2 boards installed - ----------------------------------------------- - Naming convention for each Smartio/Industio multiport board is - pre-defined as below. - - Board Num. Dial-in Port Callout port - 1st board ttyM0 - ttyM7 cum0 - cum7 - 2nd board ttyM8 - ttyM15 cum8 - cum15 - 3rd board ttyM16 - ttyM23 cum16 - cum23 - 4th board ttyM24 - ttym31 cum24 - cum31 - - - !!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - Under Kernel 2.6 the cum Device is Obsolete. So use ttyM* - device instead. - !!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - Board sequence - -------------- - This driver will activate ISA boards according to the parameter set - in the driver. After all specified ISA board activated, PCI board - will be installed in the system automatically driven. - Therefore the board number is sorted by the CAP address of ISA boards. - For PCI boards, their sequence will be after ISA boards and C168H/PCI - has higher priority than C104H/PCI boards. - - 3.4 Module driver configuration - Module driver is easiest way to install. If you prefer static driver - installation, please skip this paragraph. - - - ------------- Prepare to use the MOXA driver-------------------- - 3.4.1 Create tty device with correct major number - Before using MOXA driver, your system must have the tty devices - which are created with driver's major number. We offer one shell - script "msmknod" to simplify the procedure. - This step is only needed to be executed once. But you still - need to do this procedure when: - a. You change the driver's major number. Please refer the "3.7" - section. - b. Your total installed MOXA boards number is changed. Maybe you - add/delete one MOXA board. - c. You want to change the tty name. This needs to modify the - shell script "msmknod" - - The procedure is: - # cd /moxa/mxser/driver - # ./msmknod - - This shell script will require the major number for dial-in - device and callout device to create tty device. You also need - to specify the total installed MOXA board number. Default major - numbers for dial-in device and callout device are 30, 35. If - you need to change to other number, please refer section "3.7" - for more detailed procedure. - Msmknod will delete any special files occupying the same device - naming. - - 3.4.2 Build the MOXA driver and utilities - Before using the MOXA driver and utilities, you need compile the - all the source code. This step is only need to be executed once. - But you still re-compile the source code if you modify the source - code. For example, if you change the driver's major number (see - "3.7" section), then you need to do this step again. - - Find "Makefile" in /moxa/mxser, then run - - # make clean; make install - - !!!!!!!!!! NOTE !!!!!!!!!!!!!!!!! - For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1: - # make clean; make installsp1 - - For Red Hat Enterprise Linux AS4/ES4/WS4: - # make clean; make installsp2 - !!!!!!!!!! NOTE !!!!!!!!!!!!!!!!! - - The driver files "mxser.o" and utilities will be properly compiled - and copied to system directories respectively. - - ------------- Load MOXA driver-------------------- - 3.4.3 Load the MOXA driver - - # modprobe mxser <argument> - - will activate the module driver. You may run "lsmod" to check - if "mxser" is activated. If the MOXA board is ISA board, the - <argument> is needed. Please refer to section "3.4.5" for more - information. - - - ------------- Load MOXA driver on boot -------------------- - 3.4.4 For the above description, you may manually execute - "modprobe mxser" to activate this driver and run - "rmmod mxser" to remove it. - However, it's better to have a boot time configuration to - eliminate manual operation. Boot time configuration can be - achieved by rc file. We offer one "rc.mxser" file to simplify - the procedure under "moxa/mxser/driver". - - But if you use ISA board, please modify the "modprobe ..." command - to add the argument (see "3.4.5" section). After modifying the - rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser" - manually to make sure the modification is ok. If any error - encountered, please try to modify again. If the modification is - completed, follow the below step. - - Run following command for setting rc files. - - # cd /moxa/mxser/driver - # cp ./rc.mxser /etc/rc.d - # cd /etc/rc.d - - Check "rc.serial" is existed or not. If "rc.serial" doesn't exist, - create it by vi, run "chmod 755 rc.serial" to change the permission. - Add "/etc/rc.d/rc.mxser" in last line, - - Reboot and check if moxa.o activated by "lsmod" command. - - 3.4.5. If you'd like to drive Smartio/Industio ISA boards in the system, - you'll have to add parameter to specify CAP address of given - board while activating "mxser.o". The format for parameters are - as follows. - - modprobe mxser ioaddr=0x???,0x???,0x???,0x??? - | | | | - | | | +- 4th ISA board - | | +------ 3rd ISA board - | +------------ 2nd ISA board - +------------------- 1st ISA board - - 3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x - - Note: To use static driver, you must install the linux kernel - source package. - - 3.5.1 Backup the built-in driver in the kernel. - # cd /usr/src/linux/drivers/char - # mv mxser.c mxser.c.old - - For Red Hat 7.x user, you need to create link: - # cd /usr/src - # ln -s linux-2.4 linux - - 3.5.2 Create link - # cd /usr/src/linux/drivers/char - # ln -s /moxa/mxser/driver/mxser.c mxser.c - - 3.5.3 Add CAP address list for ISA boards. For PCI boards user, - please skip this step. - - In module mode, the CAP address for ISA board is given by - parameter. In static driver configuration, you'll have to - assign it within driver's source code. If you will not - install any ISA boards, you may skip to next portion. - The instructions to modify driver source code are as - below. - a. # cd /moxa/mxser/driver - # vi mxser.c - b. Find the array mxserBoardCAP[] as below. - - static int mxserBoardCAP[] - = {0x00, 0x00, 0x00, 0x00}; - - c. Change the address within this array using vi. For - example, to driver 2 ISA boards with CAP address - 0x280 and 0x180 as 1st and 2nd board. Just to change - the source code as follows. - - static int mxserBoardCAP[] - = {0x280, 0x180, 0x00, 0x00}; - - 3.5.4 Setup kernel configuration - - Configure the kernel: - - # cd /usr/src/linux - # make menuconfig - - You will go into a menu-driven system. Please select [Character - devices][Non-standard serial port support], enable the [Moxa - SmartIO support] driver with "[*]" for built-in (not "[M]"), then - select [Exit] to exit this program. - - 3.5.5 Rebuild kernel - The following are for Linux kernel rebuilding, for your - reference only. - For appropriate details, please refer to the Linux document. - - a. cd /usr/src/linux - b. make clean /* take a few minutes */ - c. make dep /* take a few minutes */ - d. make bzImage /* take probably 10-20 minutes */ - e. make install /* copy boot image to correct position */ - f. Please make sure the boot kernel (vmlinuz) is in the - correct position. - g. If you use 'lilo' utility, you should check /etc/lilo.conf - 'image' item specified the path which is the 'vmlinuz' path, - or you will load wrong (or old) boot kernel image (vmlinuz). - After checking /etc/lilo.conf, please run "lilo". - - Note that if the result of "make bzImage" is ERROR, then you have to - go back to Linux configuration Setup. Type "make menuconfig" in - directory /usr/src/linux. - - - 3.5.6 Make tty device and special file - # cd /moxa/mxser/driver - # ./msmknod - - 3.5.7 Make utility - # cd /moxa/mxser/utility - # make clean; make install - - 3.5.8 Reboot - - - - 3.6 Custom configuration - Although this driver already provides you default configuration, you - still can change the device name and major number. The instruction to - change these parameters are shown as below. - - Change Device name - ------------------ - If you'd like to use other device names instead of default naming - convention, all you have to do is to modify the internal code - within the shell script "msmknod". First, you have to open "msmknod" - by vi. Locate each line contains "ttyM" and "cum" and change them - to the device name you desired. "msmknod" creates the device names - you need next time executed. - - Change Major number - ------------------- - If major number 30 and 35 had been occupied, you may have to select - 2 free major numbers for this driver. There are 3 steps to change - major numbers. - - 3.6.1 Find free major numbers - In /proc/devices, you may find all the major numbers occupied - in the system. Please select 2 major numbers that are available. - e.g. 40, 45. - 3.6.2 Create special files - Run /moxa/mxser/driver/msmknod to create special files with - specified major numbers. - 3.6.3 Modify driver with new major number - Run vi to open /moxa/mxser/driver/mxser.c. Locate the line - contains "MXSERMAJOR". Change the content as below. - #define MXSERMAJOR 40 - #define MXSERCUMAJOR 45 - 3.6.4 Run "make clean; make install" in /moxa/mxser/driver. - - 3.7 Verify driver installation - You may refer to /var/log/messages to check the latest status - log reported by this driver whenever it's activated. - ------------------------------------------------------------------------------ -4. Utilities - There are 3 utilities contained in this driver. They are msdiag, msmon and - msterm. These 3 utilities are released in form of source code. They should - be compiled into executable file and copied into /usr/bin. - - Before using these utilities, please load driver (refer 3.4 & 3.5) and - make sure you had run the "msmknod" utility. - - msdiag - Diagnostic - -------------------- - This utility provides the function to display what Moxa Smartio/Industio - board found by driver in the system. - - msmon - Port Monitoring - ----------------------- - This utility gives the user a quick view about all the MOXA ports' - activities. One can easily learn each port's total received/transmitted - (Rx/Tx) character count since the time when the monitoring is started. - Rx/Tx throughputs per second are also reported in interval basis (e.g. - the last 5 seconds) and in average basis (since the time the monitoring - is started). You can reset all ports' count by <HOME> key. <+> <-> - (plus/minus) keys to change the displaying time interval. Press <ENTER> - on the port, that cursor stay, to view the port's communication - parameters, signal status, and input/output queue. - - msterm - Terminal Emulation - --------------------------- - This utility provides data sending and receiving ability of all tty ports, - especially for MOXA ports. It is quite useful for testing simple - application, for example, sending AT command to a modem connected to the - port or used as a terminal for login purpose. Note that this is only a - dumb terminal emulation without handling full screen operation. - ------------------------------------------------------------------------------ -5. Setserial - - Supported Setserial parameters are listed as below. - - uart set UART type(16450-->disable FIFO, 16550A-->enable FIFO) - close_delay set the amount of time(in 1/100 of a second) that DTR - should be kept low while being closed. - closing_wait set the amount of time(in 1/100 of a second) that the - serial port should wait for data to be drained while - being closed, before the receiver is disable. - spd_hi Use 57.6kb when the application requests 38.4kb. - spd_vhi Use 115.2kb when the application requests 38.4kb. - spd_shi Use 230.4kb when the application requests 38.4kb. - spd_warp Use 460.8kb when the application requests 38.4kb. - spd_normal Use 38.4kb when the application requests 38.4kb. - spd_cust Use the custom divisor to set the speed when the - application requests 38.4kb. - divisor This option set the custom division. - baud_base This option set the base baud rate. - ------------------------------------------------------------------------------ -6. Troubleshooting - - The boot time error messages and solutions are stated as clearly as - possible. If all the possible solutions fail, please contact our technical - support team to get more help. - - - Error msg: More than 4 Moxa Smartio/Industio family boards found. Fifth board - and after are ignored. - Solution: - To avoid this problem, please unplug fifth and after board, because Moxa - driver supports up to 4 boards. - - Error msg: Request_irq fail, IRQ(?) may be conflict with another device. - Solution: - Other PCI or ISA devices occupy the assigned IRQ. If you are not sure - which device causes the situation, please check /proc/interrupts to find - free IRQ and simply change another free IRQ for Moxa board. - - Error msg: Board #: C1xx Series(CAP=xxx) interrupt number invalid. - Solution: - Each port within the same multiport board shares the same IRQ. Please set - one IRQ (IRQ doesn't equal to zero) for one Moxa board. - - Error msg: No interrupt vector be set for Moxa ISA board(CAP=xxx). - Solution: - Moxa ISA board needs an interrupt vector.Please refer to user's manual - "Hardware Installation" chapter to set interrupt vector. - - Error msg: Couldn't install MOXA Smartio/Industio family driver! - Solution: - Load Moxa driver fail, the major number may conflict with other devices. - Please refer to previous section 3.7 to change a free major number for - Moxa driver. - - Error msg: Couldn't install MOXA Smartio/Industio family callout driver! - Solution: - Load Moxa callout driver fail, the callout device major number may - conflict with other devices. Please refer to previous section 3.7 to - change a free callout device major number for Moxa driver. - - ------------------------------------------------------------------------------ - diff --git a/Documentation/serial/moxa-smartio.rst b/Documentation/serial/moxa-smartio.rst new file mode 100644 index 000000000000..156100f17c3f --- /dev/null +++ b/Documentation/serial/moxa-smartio.rst @@ -0,0 +1,615 @@ +============================================================= +MOXA Smartio/Industio Family Device Driver Installation Guide +============================================================= + +.. note:: + + This file is outdated. It needs some care in order to make it + updated to Kernel 5.0 and upper + +Copyright (C) 2008, Moxa Inc. + +Date: 01/21/2008 + +.. Content + + 1. Introduction + 2. System Requirement + 3. Installation + 3.1 Hardware installation + 3.2 Driver files + 3.3 Device naming convention + 3.4 Module driver configuration + 3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x. + 3.6 Custom configuration + 3.7 Verify driver installation + 4. Utilities + 5. Setserial + 6. Troubleshooting + +1. Introduction +^^^^^^^^^^^^^^^ + + The Smartio/Industio/UPCI family Linux driver supports following multiport + boards. + + - 2 ports multiport board + CP-102U, CP-102UL, CP-102UF + CP-132U-I, CP-132UL, + CP-132, CP-132I, CP132S, CP-132IS, + CI-132, CI-132I, CI-132IS, + (C102H, C102HI, C102HIS, C102P, CP-102, CP-102S) + + - 4 ports multiport board + CP-104EL, + CP-104UL, CP-104JU, + CP-134U, CP-134U-I, + C104H/PCI, C104HS/PCI, + CP-114, CP-114I, CP-114S, CP-114IS, CP-114UL, + C104H, C104HS, + CI-104J, CI-104JS, + CI-134, CI-134I, CI-134IS, + (C114HI, CT-114I, C104P), + POS-104UL, + CB-114, + CB-134I + + - 8 ports multiport board + CP-118EL, CP-168EL, + CP-118U, CP-168U, + C168H/PCI, + C168H, C168HS, + (C168P), + CB-108 + + This driver and installation procedure have been developed upon Linux Kernel + 2.4.x and 2.6.x. This driver supports Intel x86 hardware platform. In order + to maintain compatibility, this version has also been properly tested with + RedHat, Mandrake, Fedora and S.u.S.E Linux. However, if compatibility problem + occurs, please contact Moxa at support@moxa.com.tw. + + In addition to device driver, useful utilities are also provided in this + version. They are: + + - msdiag + Diagnostic program for displaying installed Moxa + Smartio/Industio boards. + - msmon + Monitor program to observe data count and line status signals. + - msterm A simple terminal program which is useful in testing serial + ports. + - io-irq.exe + Configuration program to setup ISA boards. Please note that + this program can only be executed under DOS. + + All the drivers and utilities are published in form of source code under + GNU General Public License in this version. Please refer to GNU General + Public License announcement in each source code file for more detail. + + In Moxa's Web sites, you may always find latest driver at http://www.moxa.com/. + + This version of driver can be installed as Loadable Module (Module driver) + or built-in into kernel (Static driver). You may refer to following + installation procedure for suitable one. Before you install the driver, + please refer to hardware installation procedure in the User's Manual. + + We assume the user should be familiar with following documents. + + - Serial-HOWTO + - Kernel-HOWTO + +2. System Requirement +^^^^^^^^^^^^^^^^^^^^^ + + - Hardware platform: Intel x86 machine + - Kernel version: 2.4.x or 2.6.x + - gcc version 2.72 or later + - Maximum 4 boards can be installed in combination + +3. Installation +^^^^^^^^^^^^^^^ + +3.1 Hardware installation +========================= + + There are two types of buses, ISA and PCI, for Smartio/Industio + family multiport board. + +ISA board +--------- + + You'll have to configure CAP address, I/O address, Interrupt Vector + as well as IRQ before installing this driver. Please refer to hardware + installation procedure in User's Manual before proceed any further. + Please make sure the JP1 is open after the ISA board is set properly. + +PCI/UPCI board +-------------- + + You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict + with other ISA devices. Please refer to hardware installation + procedure in User's Manual in advance. + +PCI IRQ Sharing +--------------- + + Each port within the same multiport board shares the same IRQ. Up to + 4 Moxa Smartio/Industio PCI Family multiport boards can be installed + together on one system and they can share the same IRQ. + + +3.2 Driver files +================ + + The driver file may be obtained from ftp, CD-ROM or floppy disk. The + first step, anyway, is to copy driver file "mxser.tgz" into specified + directory. e.g. /moxa. The execute commands as below:: + + # cd / + # mkdir moxa + # cd /moxa + # tar xvf /dev/fd0 + +or:: + + # cd / + # mkdir moxa + # cd /moxa + # cp /mnt/cdrom/<driver directory>/mxser.tgz . + # tar xvfz mxser.tgz + + +3.3 Device naming convention +============================ + + You may find all the driver and utilities files in /moxa/mxser. + Following installation procedure depends on the model you'd like to + run the driver. If you prefer module driver, please refer to 3.4. + If static driver is required, please refer to 3.5. + +Dialin and callout port +----------------------- + + This driver remains traditional serial device properties. There are + two special file name for each serial port. One is dial-in port + which is named "ttyMxx". For callout port, the naming convention + is "cumxx". + +Device naming when more than 2 boards installed +----------------------------------------------- + + Naming convention for each Smartio/Industio multiport board is + pre-defined as below. + + ============ =============== ============== + Board Num. Dial-in Port Callout port + 1st board ttyM0 - ttyM7 cum0 - cum7 + 2nd board ttyM8 - ttyM15 cum8 - cum15 + 3rd board ttyM16 - ttyM23 cum16 - cum23 + 4th board ttyM24 - ttym31 cum24 - cum31 + ============ =============== ============== + +.. note:: + + Under Kernel 2.6 and upper, the cum Device is Obsolete. So use ttyM* + device instead. + +Board sequence +-------------- + + This driver will activate ISA boards according to the parameter set + in the driver. After all specified ISA board activated, PCI board + will be installed in the system automatically driven. + Therefore the board number is sorted by the CAP address of ISA boards. + For PCI boards, their sequence will be after ISA boards and C168H/PCI + has higher priority than C104H/PCI boards. + +3.4 Module driver configuration +=============================== + + Module driver is easiest way to install. If you prefer static driver + installation, please skip this paragraph. + + + ------------- Prepare to use the MOXA driver -------------------- + +3.4.1 Create tty device with correct major number +------------------------------------------------- + + Before using MOXA driver, your system must have the tty devices + which are created with driver's major number. We offer one shell + script "msmknod" to simplify the procedure. + This step is only needed to be executed once. But you still + need to do this procedure when: + + a. You change the driver's major number. Please refer the "3.7" + section. + b. Your total installed MOXA boards number is changed. Maybe you + add/delete one MOXA board. + c. You want to change the tty name. This needs to modify the + shell script "msmknod" + + The procedure is:: + + # cd /moxa/mxser/driver + # ./msmknod + + This shell script will require the major number for dial-in + device and callout device to create tty device. You also need + to specify the total installed MOXA board number. Default major + numbers for dial-in device and callout device are 30, 35. If + you need to change to other number, please refer section "3.7" + for more detailed procedure. + Msmknod will delete any special files occupying the same device + naming. + +3.4.2 Build the MOXA driver and utilities +----------------------------------------- + + Before using the MOXA driver and utilities, you need compile the + all the source code. This step is only need to be executed once. + But you still re-compile the source code if you modify the source + code. For example, if you change the driver's major number (see + "3.7" section), then you need to do this step again. + + Find "Makefile" in /moxa/mxser, then run + + # make clean; make install + + ..note:: + + For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1: + # make clean; make installsp1 + + For Red Hat Enterprise Linux AS4/ES4/WS4: + # make clean; make installsp2 + + The driver files "mxser.o" and utilities will be properly compiled + and copied to system directories respectively. + +------------- Load MOXA driver-------------------- + +3.4.3 Load the MOXA driver +-------------------------- + + :: + + # modprobe mxser <argument> + + will activate the module driver. You may run "lsmod" to check + if "mxser" is activated. If the MOXA board is ISA board, the + <argument> is needed. Please refer to section "3.4.5" for more + information. + +------------- Load MOXA driver on boot -------------------- + +3.4.4 Load the mxser driver +--------------------------- + + + For the above description, you may manually execute + "modprobe mxser" to activate this driver and run + "rmmod mxser" to remove it. + + However, it's better to have a boot time configuration to + eliminate manual operation. Boot time configuration can be + achieved by rc file. We offer one "rc.mxser" file to simplify + the procedure under "moxa/mxser/driver". + + But if you use ISA board, please modify the "modprobe ..." command + to add the argument (see "3.4.5" section). After modifying the + rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser" + manually to make sure the modification is ok. If any error + encountered, please try to modify again. If the modification is + completed, follow the below step. + + Run following command for setting rc files:: + + # cd /moxa/mxser/driver + # cp ./rc.mxser /etc/rc.d + # cd /etc/rc.d + + Check "rc.serial" is existed or not. If "rc.serial" doesn't exist, + create it by vi, run "chmod 755 rc.serial" to change the permission. + + Add "/etc/rc.d/rc.mxser" in last line. + + Reboot and check if moxa.o activated by "lsmod" command. + +3.4.5. specify CAP address +-------------------------- + + If you'd like to drive Smartio/Industio ISA boards in the system, + you'll have to add parameter to specify CAP address of given + board while activating "mxser.o". The format for parameters are + as follows.:: + + modprobe mxser ioaddr=0x???,0x???,0x???,0x??? + | | | | + | | | +- 4th ISA board + | | +------ 3rd ISA board + | +------------ 2nd ISA board + +-------------------1st ISA board + +3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x +================================================================ + + Note: + To use static driver, you must install the linux kernel + source package. + +3.5.1 Backup the built-in driver in the kernel +---------------------------------------------- + + :: + + # cd /usr/src/linux/drivers/char + # mv mxser.c mxser.c.old + + For Red Hat 7.x user, you need to create link: + # cd /usr/src + # ln -s linux-2.4 linux + +3.5.2 Create link +----------------- + :: + + # cd /usr/src/linux/drivers/char + # ln -s /moxa/mxser/driver/mxser.c mxser.c + +3.5.3 Add CAP address list for ISA boards. +------------------------------------------ + + For PCI boards user, please skip this step. + + In module mode, the CAP address for ISA board is given by + parameter. In static driver configuration, you'll have to + assign it within driver's source code. If you will not + install any ISA boards, you may skip to next portion. + The instructions to modify driver source code are as + below. + + a. run:: + + # cd /moxa/mxser/driver + # vi mxser.c + + b. Find the array mxserBoardCAP[] as below:: + + static int mxserBoardCAP[] = {0x00, 0x00, 0x00, 0x00}; + + c. Change the address within this array using vi. For + example, to driver 2 ISA boards with CAP address + 0x280 and 0x180 as 1st and 2nd board. Just to change + the source code as follows:: + + static int mxserBoardCAP[] = {0x280, 0x180, 0x00, 0x00}; + +3.5.4 Setup kernel configuration +-------------------------------- + + Configure the kernel:: + + # cd /usr/src/linux + # make menuconfig + + You will go into a menu-driven system. Please select [Character + devices][Non-standard serial port support], enable the [Moxa + SmartIO support] driver with "[*]" for built-in (not "[M]"), then + select [Exit] to exit this program. + +3.5.5 Rebuild kernel +-------------------- + + The following are for Linux kernel rebuilding, for your + reference only. + + For appropriate details, please refer to the Linux document: + + a. Run the following commands:: + + cd /usr/src/linux + make clean # take a few minutes + make dep # take a few minutes + make bzImage # take probably 10-20 minutes + make install # copy boot image to correct position + + f. Please make sure the boot kernel (vmlinuz) is in the + correct position. + g. If you use 'lilo' utility, you should check /etc/lilo.conf + 'image' item specified the path which is the 'vmlinuz' path, + or you will load wrong (or old) boot kernel image (vmlinuz). + After checking /etc/lilo.conf, please run "lilo". + + Note that if the result of "make bzImage" is ERROR, then you have to + go back to Linux configuration Setup. Type "make menuconfig" in + directory /usr/src/linux. + + +3.5.6 Make tty device and special file +-------------------------------------- + + :: + # cd /moxa/mxser/driver + # ./msmknod + +3.5.7 Make utility +------------------ + + :: + + # cd /moxa/mxser/utility + # make clean; make install + +3.5.8 Reboot +------------ + + + +3.6 Custom configuration +======================== + + Although this driver already provides you default configuration, you + still can change the device name and major number. The instruction to + change these parameters are shown as below. + +a. Change Device name + + If you'd like to use other device names instead of default naming + convention, all you have to do is to modify the internal code + within the shell script "msmknod". First, you have to open "msmknod" + by vi. Locate each line contains "ttyM" and "cum" and change them + to the device name you desired. "msmknod" creates the device names + you need next time executed. + +b. Change Major number + + If major number 30 and 35 had been occupied, you may have to select + 2 free major numbers for this driver. There are 3 steps to change + major numbers. + +3.6.1 Find free major numbers +----------------------------- + + In /proc/devices, you may find all the major numbers occupied + in the system. Please select 2 major numbers that are available. + e.g. 40, 45. + +3.6.2 Create special files +-------------------------- + + Run /moxa/mxser/driver/msmknod to create special files with + specified major numbers. + +3.6.3 Modify driver with new major number +----------------------------------------- + + Run vi to open /moxa/mxser/driver/mxser.c. Locate the line + contains "MXSERMAJOR". Change the content as below:: + + #define MXSERMAJOR 40 + #define MXSERCUMAJOR 45 + + 3.6.4 Run "make clean; make install" in /moxa/mxser/driver. + +3.7 Verify driver installation +============================== + + You may refer to /var/log/messages to check the latest status + log reported by this driver whenever it's activated. + +4. Utilities +^^^^^^^^^^^^ + + There are 3 utilities contained in this driver. They are msdiag, msmon and + msterm. These 3 utilities are released in form of source code. They should + be compiled into executable file and copied into /usr/bin. + + Before using these utilities, please load driver (refer 3.4 & 3.5) and + make sure you had run the "msmknod" utility. + +msdiag - Diagnostic +=================== + + This utility provides the function to display what Moxa Smartio/Industio + board found by driver in the system. + +msmon - Port Monitoring +======================= + + This utility gives the user a quick view about all the MOXA ports' + activities. One can easily learn each port's total received/transmitted + (Rx/Tx) character count since the time when the monitoring is started. + + Rx/Tx throughputs per second are also reported in interval basis (e.g. + the last 5 seconds) and in average basis (since the time the monitoring + is started). You can reset all ports' count by <HOME> key. <+> <-> + (plus/minus) keys to change the displaying time interval. Press <ENTER> + on the port, that cursor stay, to view the port's communication + parameters, signal status, and input/output queue. + +msterm - Terminal Emulation +=========================== + + This utility provides data sending and receiving ability of all tty ports, + especially for MOXA ports. It is quite useful for testing simple + application, for example, sending AT command to a modem connected to the + port or used as a terminal for login purpose. Note that this is only a + dumb terminal emulation without handling full screen operation. + +5. Setserial +^^^^^^^^^^^^ + + Supported Setserial parameters are listed as below. + + ============== ========================================================= + uart set UART type(16450-->disable FIFO, 16550A-->enable FIFO) + close_delay set the amount of time(in 1/100 of a second) that DTR + should be kept low while being closed. + closing_wait set the amount of time(in 1/100 of a second) that the + serial port should wait for data to be drained while + being closed, before the receiver is disable. + spd_hi Use 57.6kb when the application requests 38.4kb. + spd_vhi Use 115.2kb when the application requests 38.4kb. + spd_shi Use 230.4kb when the application requests 38.4kb. + spd_warp Use 460.8kb when the application requests 38.4kb. + spd_normal Use 38.4kb when the application requests 38.4kb. + spd_cust Use the custom divisor to set the speed when the + application requests 38.4kb. + divisor This option set the custom division. + baud_base This option set the base baud rate. + ============== ========================================================= + +6. Troubleshooting +^^^^^^^^^^^^^^^^^^ + + The boot time error messages and solutions are stated as clearly as + possible. If all the possible solutions fail, please contact our technical + support team to get more help. + + + Error msg: + More than 4 Moxa Smartio/Industio family boards found. Fifth board + and after are ignored. + + Solution: + To avoid this problem, please unplug fifth and after board, because Moxa + driver supports up to 4 boards. + + Error msg: + Request_irq fail, IRQ(?) may be conflict with another device. + + Solution: + Other PCI or ISA devices occupy the assigned IRQ. If you are not sure + which device causes the situation, please check /proc/interrupts to find + free IRQ and simply change another free IRQ for Moxa board. + + Error msg: + Board #: C1xx Series(CAP=xxx) interrupt number invalid. + + Solution: + Each port within the same multiport board shares the same IRQ. Please set + one IRQ (IRQ doesn't equal to zero) for one Moxa board. + + Error msg: + No interrupt vector be set for Moxa ISA board(CAP=xxx). + + Solution: + Moxa ISA board needs an interrupt vector.Please refer to user's manual + "Hardware Installation" chapter to set interrupt vector. + + Error msg: + Couldn't install MOXA Smartio/Industio family driver! + + Solution: + Load Moxa driver fail, the major number may conflict with other devices. + Please refer to previous section 3.7 to change a free major number for + Moxa driver. + + Error msg: + Couldn't install MOXA Smartio/Industio family callout driver! + + Solution: + Load Moxa callout driver fail, the callout device major number may + conflict with other devices. Please refer to previous section 3.7 to + change a free callout device major number for Moxa driver. diff --git a/Documentation/serial/n_gsm.rst b/Documentation/serial/n_gsm.rst new file mode 100644 index 000000000000..f3ad9fd26408 --- /dev/null +++ b/Documentation/serial/n_gsm.rst @@ -0,0 +1,103 @@ +============================== +GSM 0710 tty multiplexor HOWTO +============================== + +This line discipline implements the GSM 07.10 multiplexing protocol +detailed in the following 3GPP document: + + http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip + +This document give some hints on how to use this driver with GPRS and 3G +modems connected to a physical serial port. + +How to use it +------------- +1. initialize the modem in 0710 mux mode (usually AT+CMUX= command) through + its serial port. Depending on the modem used, you can pass more or less + parameters to this command, +2. switch the serial line to using the n_gsm line discipline by using + TIOCSETD ioctl, +3. configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl, + +Major parts of the initialization program : +(a good starting point is util-linux-ng/sys-utils/ldattach.c):: + + #include <linux/gsmmux.h> + #define N_GSM0710 21 /* GSM 0710 Mux */ + #define DEFAULT_SPEED B115200 + #define SERIAL_PORT /dev/ttyS0 + + int ldisc = N_GSM0710; + struct gsm_config c; + struct termios configuration; + + /* open the serial port connected to the modem */ + fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); + + /* configure the serial port : speed, flow control ... */ + + /* send the AT commands to switch the modem to CMUX mode + and check that it's successful (should return OK) */ + write(fd, "AT+CMUX=0\r", 10); + + /* experience showed that some modems need some time before + being able to answer to the first MUX packet so a delay + may be needed here in some case */ + sleep(3); + + /* use n_gsm line discipline */ + ioctl(fd, TIOCSETD, &ldisc); + + /* get n_gsm configuration */ + ioctl(fd, GSMIOC_GETCONF, &c); + /* we are initiator and need encoding 0 (basic) */ + c.initiator = 1; + c.encapsulation = 0; + /* our modem defaults to a maximum size of 127 bytes */ + c.mru = 127; + c.mtu = 127; + /* set the new configuration */ + ioctl(fd, GSMIOC_SETCONF, &c); + + /* and wait for ever to keep the line discipline enabled */ + daemon(0,0); + pause(); + +4. create the devices corresponding to the "virtual" serial ports (take care, + each modem has its configuration and some DLC have dedicated functions, + for example GPS), starting with minor 1 (DLC0 is reserved for the management + of the mux):: + + MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}` + for i in `seq 1 4`; do + mknod /dev/ttygsm$i c $MAJOR $i + done + +5. use these devices as plain serial ports. + + for example, it's possible: + + - and to use gnokii to send / receive SMS on ttygsm1 + - to use ppp to establish a datalink on ttygsm2 + +6. first close all virtual ports before closing the physical port. + + Note that after closing the physical port the modem is still in multiplexing + mode. This may prevent a successful re-opening of the port later. To avoid + this situation either reset the modem if your hardware allows that or send + a disconnect command frame manually before initializing the multiplexing mode + for the second time. The byte sequence for the disconnect command frame is:: + + 0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9. + +Additional Documentation +------------------------ +More practical details on the protocol and how it's supported by industrial +modems can be found in the following documents : + +- http://www.telit.com/module/infopool/download.php?id=616 +- http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf +- http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx +- http://wm.sim.com/sim/News/photo/2010721161442.pdf + +11-03-08 - Eric BĂ©nard - <eric@eukrea.com> diff --git a/Documentation/serial/n_gsm.txt b/Documentation/serial/n_gsm.txt deleted file mode 100644 index 875361bb7cb4..000000000000 --- a/Documentation/serial/n_gsm.txt +++ /dev/null @@ -1,96 +0,0 @@ -n_gsm.c GSM 0710 tty multiplexor HOWTO -=================================================== - -This line discipline implements the GSM 07.10 multiplexing protocol -detailed in the following 3GPP document : -http://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip - -This document give some hints on how to use this driver with GPRS and 3G -modems connected to a physical serial port. - -How to use it -------------- -1- initialize the modem in 0710 mux mode (usually AT+CMUX= command) through -its serial port. Depending on the modem used, you can pass more or less -parameters to this command, -2- switch the serial line to using the n_gsm line discipline by using -TIOCSETD ioctl, -3- configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl, - -Major parts of the initialization program : -(a good starting point is util-linux-ng/sys-utils/ldattach.c) -#include <linux/gsmmux.h> -#define N_GSM0710 21 /* GSM 0710 Mux */ -#define DEFAULT_SPEED B115200 -#define SERIAL_PORT /dev/ttyS0 - - int ldisc = N_GSM0710; - struct gsm_config c; - struct termios configuration; - - /* open the serial port connected to the modem */ - fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); - - /* configure the serial port : speed, flow control ... */ - - /* send the AT commands to switch the modem to CMUX mode - and check that it's successful (should return OK) */ - write(fd, "AT+CMUX=0\r", 10); - - /* experience showed that some modems need some time before - being able to answer to the first MUX packet so a delay - may be needed here in some case */ - sleep(3); - - /* use n_gsm line discipline */ - ioctl(fd, TIOCSETD, &ldisc); - - /* get n_gsm configuration */ - ioctl(fd, GSMIOC_GETCONF, &c); - /* we are initiator and need encoding 0 (basic) */ - c.initiator = 1; - c.encapsulation = 0; - /* our modem defaults to a maximum size of 127 bytes */ - c.mru = 127; - c.mtu = 127; - /* set the new configuration */ - ioctl(fd, GSMIOC_SETCONF, &c); - - /* and wait for ever to keep the line discipline enabled */ - daemon(0,0); - pause(); - -4- create the devices corresponding to the "virtual" serial ports (take care, -each modem has its configuration and some DLC have dedicated functions, -for example GPS), starting with minor 1 (DLC0 is reserved for the management -of the mux) - -MAJOR=`cat /proc/devices |grep gsmtty | awk '{print $1}` -for i in `seq 1 4`; do - mknod /dev/ttygsm$i c $MAJOR $i -done - -5- use these devices as plain serial ports. -for example, it's possible : -- and to use gnokii to send / receive SMS on ttygsm1 -- to use ppp to establish a datalink on ttygsm2 - -6- first close all virtual ports before closing the physical port. - -Note that after closing the physical port the modem is still in multiplexing -mode. This may prevent a successful re-opening of the port later. To avoid -this situation either reset the modem if your hardware allows that or send -a disconnect command frame manually before initializing the multiplexing mode -for the second time. The byte sequence for the disconnect command frame is: -0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9. - -Additional Documentation ------------------------- -More practical details on the protocol and how it's supported by industrial -modems can be found in the following documents : -http://www.telit.com/module/infopool/download.php?id=616 -http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf -http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx -http://wm.sim.com/sim/News/photo/2010721161442.pdf - -11-03-08 - Eric BĂ©nard - <eric@eukrea.com> diff --git a/Documentation/serial/rocket.txt b/Documentation/serial/rocket.rst index 60b039891057..23761eae4282 100644 --- a/Documentation/serial/rocket.txt +++ b/Documentation/serial/rocket.rst @@ -1,20 +1,22 @@ -Comtrol(tm) RocketPort(R)/RocketModem(TM) Series -Device Driver for the Linux Operating System +================================================ +Comtrol(tm) RocketPort(R)/RocketModem(TM) Series +================================================ -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- +Device Driver for the Linux Operating System +============================================ -PRODUCT OVERVIEW +Product overview ---------------- This driver provides a loadable kernel driver for the Comtrol RocketPort -and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32 +and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32 high-speed serial ports or modems. This driver supports up to a combination of four RocketPort or RocketModems boards in one machine simultaneously. This file assumes that you are using the RocketPort driver which is -integrated into the kernel sources. +integrated into the kernel sources. -The driver can also be installed as an external module using the usual -"make;make install" routine. This external module driver, obtainable +The driver can also be installed as an external module using the usual +"make;make install" routine. This external module driver, obtainable from the Comtrol website listed below, is useful for updating the driver or installing it into kernels which do not have the driver configured into them. Installations instructions for the external module @@ -29,57 +31,59 @@ information on how to set the DIP switches. You pass the I/O port to the driver using the following module parameters: -board1 : I/O port for the first ISA board -board2 : I/O port for the second ISA board -board3 : I/O port for the third ISA board -board4 : I/O port for the fourth ISA board +board1: + I/O port for the first ISA board +board2: + I/O port for the second ISA board +board3: + I/O port for the third ISA board +board4: + I/O port for the fourth ISA board There is a set of utilities and scripts provided with the external driver -( downloadable from http://www.comtrol.com ) that ease the configuration and +(downloadable from http://www.comtrol.com) that ease the configuration and setup of the ISA cards. The RocketModem II PCI boards require firmware to be loaded into the card before it will function. The driver has only been tested as a module for this board. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -INSTALLATION PROCEDURES +Installation Procedures ----------------------- -RocketPort/RocketModem PCI cards require no driver configuration, they are +RocketPort/RocketModem PCI cards require no driver configuration, they are automatically detected and configured. -The RocketPort driver can be installed as a module (recommended) or built +The RocketPort driver can be installed as a module (recommended) or built into the kernel. This is selected, as for other drivers, through the `make config` -command from the root of the Linux source tree during the kernel build process. +command from the root of the Linux source tree during the kernel build process. The RocketPort/RocketModem serial ports installed by this driver are assigned -device major number 46, and will be named /dev/ttyRx, where x is the port number +device major number 46, and will be named /dev/ttyRx, where x is the port number starting at zero (ex. /dev/ttyR0, /devttyR1, ...). If you have multiple cards installed in the system, the mapping of port names to serial ports is displayed in the system log at /var/log/messages. If installed as a module, the module must be loaded. This can be done manually by entering "modprobe rocket". To have the module loaded automatically -upon system boot, edit a /etc/modprobe.d/*.conf file and add the line +upon system boot, edit a `/etc/modprobe.d/*.conf` file and add the line "alias char-major-46 rocket". In order to use the ports, their device names (nodes) must be created with mknod. -This is only required once, the system will retain the names once created. To -create the RocketPort/RocketModem device names, use the command -"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero. For example: +This is only required once, the system will retain the names once created. To +create the RocketPort/RocketModem device names, use the command +"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero. ->mknod /dev/ttyR0 c 46 0 ->mknod /dev/ttyR1 c 46 1 ->mknod /dev/ttyR2 c 46 2 +For example:: -The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) -for you: + > mknod /dev/ttyR0 c 46 0 + > mknod /dev/ttyR1 c 46 1 + > mknod /dev/ttyR2 c 46 2 ->/dev/MAKEDEV ttyR +The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) +for you:: -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- + >/dev/MAKEDEV ttyR ISA Rocketport Boards --------------------- @@ -89,7 +93,7 @@ card before installing and using it. This is done by setting a set of DIP switches on the Rocketport board. -SETTING THE I/O ADDRESS +Setting the I/O address ----------------------- Before installing RocketPort(R) or RocketPort RA boards, you must find @@ -130,40 +134,36 @@ the first 4 bytes of that range are used by the first board. You would need to set the second, third, or fourth board to one of the next available blocks such as 0x180. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -RocketPort and RocketPort RA SW1 Settings: - - +-------------------------------+ - | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | - +-------+-------+---------------+ - | Unused| Card | I/O Port Block| - +-------------------------------+ - -DIP Switches DIP Switches -7 8 6 5 -=================== =================== -On On UNUSED, MUST BE ON. On On First Card <==== Default - On Off Second Card - Off On Third Card - Off Off Fourth Card - -DIP Switches I/O Address Range -4 3 2 1 Used by the First Card -===================================== -On Off On Off 100-143 -On Off Off On 140-183 -On Off Off Off 180-1C3 <==== Default -Off On On Off 200-243 -Off On Off On 240-283 -Off On Off Off 280-2C3 -Off Off On Off 300-343 -Off Off Off On 340-383 -Off Off Off Off 380-3C3 - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - -REPORTING BUGS +RocketPort and RocketPort RA SW1 Settings:: + + +-------------------------------+ + | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | + +-------+-------+---------------+ + | Unused| Card | I/O Port Block| + +-------------------------------+ + + DIP Switches DIP Switches + 7 8 6 5 + =================== =================== + On On UNUSED, MUST BE ON. On On First Card <==== Default + On Off Second Card + Off On Third Card + Off Off Fourth Card + + DIP Switches I/O Address Range + 4 3 2 1 Used by the First Card + ===================================== + On Off On Off 100-143 + On Off Off On 140-183 + On Off Off Off 180-1C3 <==== Default + Off On On Off 200-243 + Off On Off On 240-283 + Off On Off Off 280-2C3 + Off Off On Off 300-343 + Off Off Off On 340-383 + Off Off Off Off 380-3C3 + +Reporting Bugs -------------- For technical support, please provide the following @@ -171,19 +171,15 @@ information: Driver version, kernel release, distribution of kernel, and type of board you are using. Error messages and log printouts port configuration details are especially helpful. -USA - Phone: (612) 494-4100 - FAX: (612) 494-4199 - email: support@comtrol.com +USA: + :Phone: (612) 494-4100 + :FAX: (612) 494-4199 + :email: support@comtrol.com -Comtrol Europe - Phone: +44 (0) 1 869 323-220 - FAX: +44 (0) 1 869 323-211 - email: support@comtrol.co.uk +Comtrol Europe: + :Phone: +44 (0) 1 869 323-220 + :FAX: +44 (0) 1 869 323-211 + :email: support@comtrol.co.uk Web: http://www.comtrol.com FTP: ftp.comtrol.com - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- - - diff --git a/Documentation/serial/serial-iso7816.txt b/Documentation/serial/serial-iso7816.rst index 3193d24a2b0f..d990143de0c6 100644 --- a/Documentation/serial/serial-iso7816.txt +++ b/Documentation/serial/serial-iso7816.rst @@ -1,11 +1,15 @@ - ISO7816 SERIAL COMMUNICATIONS +============================= +ISO7816 Serial Communications +============================= -1. INTRODUCTION +1. Introduction +=============== ISO/IEC7816 is a series of standards specifying integrated circuit cards (ICC) also known as smart cards. -2. HARDWARE-RELATED CONSIDERATIONS +2. Hardware-related considerations +================================== Some CPUs/UARTs (e.g., Microchip AT91) contain a built-in mode capable of handling communication with a smart card. @@ -15,7 +19,8 @@ available at user-level to allow switching from one mode to the other, and vice versa. -3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL +3. Data Structures Already Available in the Kernel +================================================== The Linux kernel provides the serial_iso7816 structure (see [1]) to handle ISO7816 communications. This data structure is used to set and configure @@ -27,10 +32,11 @@ to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config callback receives a pointer to struct serial_iso7816. -4. USAGE FROM USER-LEVEL +4. Usage from user-level +======================== From user-level, ISO7816 configuration can be get/set using the previous - ioctls. For instance, to set ISO7816 you can use the following code: + ioctls. For instance, to set ISO7816 you can use the following code:: #include <linux/serial.h> @@ -78,6 +84,7 @@ /* Error handling. See errno. */ } -5. REFERENCES +5. References +============= [1] include/uapi/linux/serial.h diff --git a/Documentation/serial/serial-rs485.txt b/Documentation/serial/serial-rs485.rst index ce0c1a9b8aab..6bc824f948f9 100644 --- a/Documentation/serial/serial-rs485.txt +++ b/Documentation/serial/serial-rs485.rst @@ -1,6 +1,9 @@ - RS485 SERIAL COMMUNICATIONS +=========================== +RS485 Serial Communications +=========================== -1. INTRODUCTION +1. Introduction +=============== EIA-485, also known as TIA/EIA-485 or RS-485, is a standard defining the electrical characteristics of drivers and receivers for use in balanced @@ -9,7 +12,8 @@ because it can be used effectively over long distances and in electrically noisy environments. -2. HARDWARE-RELATED CONSIDERATIONS +2. Hardware-related Considerations +================================== Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in half-duplex mode capable of automatically controlling line direction by @@ -22,7 +26,8 @@ available at user-level to allow switching from one mode to the other, and vice versa. -3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL +3. Data Structures Already Available in the Kernel +================================================== The Linux kernel provides the serial_rs485 structure (see [1]) to handle RS485 communications. This data structure is used to set and configure RS485 @@ -38,10 +43,11 @@ to TIOCSRS485 and TIOCGRS485 ioctls (see below). The rs485_config callback receives a pointer to struct serial_rs485. -4. USAGE FROM USER-LEVEL +4. Usage from user-level +======================== From user-level, RS485 configuration can be get/set using the previous - ioctls. For instance, to set RS485 you can use the following code: + ioctls. For instance, to set RS485 you can use the following code:: #include <linux/serial.h> @@ -89,7 +95,9 @@ /* Error handling. See errno. */ } -5. REFERENCES +5. References +============= [1] include/uapi/linux/serial.h + [2] Documentation/devicetree/bindings/serial/rs485.txt diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.rst index b48780977a68..dd972caacf3e 100644 --- a/Documentation/serial/tty.txt +++ b/Documentation/serial/tty.rst @@ -1,5 +1,6 @@ - - The Lockronomicon +================= +The Lockronomicon +================= Your guide to the ancient and twisted locking policies of the tty layer and the warped logic behind them. Beware all ye who read on. @@ -9,12 +10,12 @@ Line Discipline --------------- Line disciplines are registered with tty_register_ldisc() passing the -discipline number and the ldisc structure. At the point of registration the +discipline number and the ldisc structure. At the point of registration the discipline must be ready to use and it is possible it will get used before the call returns success. If the call returns an error then it won't get called. Do not re-use ldisc numbers as they are part of the userspace ABI and writing over an existing ldisc will cause demons to eat your computer. -After the return the ldisc data has been copied so you may free your own +After the return the ldisc data has been copied so you may free your own copy of the structure. You must not re-register over the top of the line discipline even with the same data or your computer again will be eaten by demons. @@ -26,7 +27,7 @@ code manages the module counts this should not usually be a concern. Heed this warning: the reference count field of the registered copies of the tty_ldisc structure in the ldisc table counts the number of lines using this -discipline. The reference count of the tty_ldisc structure within a tty +discipline. The reference count of the tty_ldisc structure within a tty counts the number of active users of the ldisc at this instant. In effect it counts the number of threads of execution within an ldisc method (plus those about to enter and exit although this detail matters not). @@ -34,9 +35,11 @@ about to enter and exit although this detail matters not). Line Discipline Methods ----------------------- -TTY side interfaces: +TTY side interfaces +^^^^^^^^^^^^^^^^^^^ -open() - Called when the line discipline is attached to +======================= ======================================================= +open() Called when the line discipline is attached to the terminal. No other call into the line discipline for this tty will occur until it completes successfully. Should initialize any @@ -47,66 +50,69 @@ open() - Called when the line discipline is attached to Returning an error will prevent the ldisc from being attached. Can sleep. -close() - This is called on a terminal when the line +close() This is called on a terminal when the line discipline is being unplugged. At the point of execution no further users will enter the ldisc code for this tty. Can sleep. -hangup() - Called when the tty line is hung up. +hangup() Called when the tty line is hung up. The line discipline should cease I/O to the tty. No further calls into the ldisc code will occur. The return value is ignored. Can sleep. -read() - (optional) A process requests reading data from +read() (optional) A process requests reading data from the line. Multiple read calls may occur in parallel and the ldisc must deal with serialization issues. If not defined, the process will receive an EIO error. May sleep. -write() - (optional) A process requests writing data to the +write() (optional) A process requests writing data to the line. Multiple write calls are serialized by the tty layer for the ldisc. If not defined, the process will receive an EIO error. May sleep. -flush_buffer() - (optional) May be called at any point between +flush_buffer() (optional) May be called at any point between open and close, and instructs the line discipline to empty its input buffer. -set_termios() - (optional) Called on termios structure changes. +set_termios() (optional) Called on termios structure changes. The caller passes the old termios data and the current data is in the tty. Called under the termios semaphore so allowed to sleep. Serialized against itself only. -poll() - (optional) Check the status for the poll/select +poll() (optional) Check the status for the poll/select calls. Multiple poll calls may occur in parallel. May sleep. -ioctl() - (optional) Called when an ioctl is handed to the +ioctl() (optional) Called when an ioctl is handed to the tty layer that might be for the ldisc. Multiple ioctl calls may occur in parallel. May sleep. -compat_ioctl() - (optional) Called when a 32 bit ioctl is handed +compat_ioctl() (optional) Called when a 32 bit ioctl is handed to the tty layer that might be for the ldisc. Multiple ioctl calls may occur in parallel. May sleep. +======================= ======================================================= -Driver Side Interfaces: +Driver Side Interfaces +^^^^^^^^^^^^^^^^^^^^^^ -receive_buf() - (optional) Called by the low-level driver to hand +======================= ======================================================= +receive_buf() (optional) Called by the low-level driver to hand a buffer of received bytes to the ldisc for processing. The number of bytes is guaranteed not to exceed the current value of tty->receive_room. All bytes must be processed. -receive_buf2() - (optional) Called by the low-level driver to hand +receive_buf2() (optional) Called by the low-level driver to hand a buffer of received bytes to the ldisc for processing. Returns the number of bytes processed. If both receive_buf() and receive_buf2() are defined, receive_buf2() should be preferred. -write_wakeup() - May be called at any point between open and close. +write_wakeup() May be called at any point between open and close. The TTY_DO_WRITE_WAKEUP flag indicates if a call is needed but always races versus calls. Thus the ldisc must be careful about setting order and to @@ -117,17 +123,20 @@ write_wakeup() - May be called at any point between open and close. is permitted to call the driver write method from this function. In such a situation defer it. -dcd_change() - Report to the tty line the current DCD pin status +dcd_change() Report to the tty line the current DCD pin status changes and the relative timestamp. The timestamp cannot be NULL. +======================= ======================================================= Driver Access +^^^^^^^^^^^^^ Line discipline methods can call the following methods of the underlying hardware driver through the function pointers within the tty->driver structure: +======================= ======================================================= write() Write a block of characters to the tty device. Returns the number of characters accepted. The character buffer passed to this method is already @@ -189,13 +198,16 @@ wait_until_sent() Waits until the device has written out all of the characters in its transmitter FIFO. send_xchar() Send a high-priority XON/XOFF character to the device. +======================= ======================================================= Flags +^^^^^ Line discipline methods have access to tty->flags field containing the following interesting flags: +======================= ======================================================= TTY_THROTTLED Driver input is throttled. The ldisc should call tty->driver->unthrottle() in order to resume reception when it is ready to process more data. @@ -212,102 +224,105 @@ TTY_OTHER_CLOSED Device is a pty and the other side has closed. TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into smaller chunks. +======================= ======================================================= Locking +^^^^^^^ Callers to the line discipline functions from the tty layer are required to take line discipline locks. The same is true of calls from the driver side but not yet enforced. -Three calls are now provided +Three calls are now provided:: ldisc = tty_ldisc_ref(tty); takes a handle to the line discipline in the tty and returns it. If no ldisc is currently attached or the ldisc is being closed and re-opened at this point then NULL is returned. While this handle is held the ldisc will not -change or go away. +change or go away:: tty_ldisc_deref(ldisc) Returns the ldisc reference and allows the ldisc to be closed. Returning the reference takes away your right to call the ldisc functions until you take -a new reference. +a new reference:: ldisc = tty_ldisc_ref_wait(tty); Performs the same function as tty_ldisc_ref except that it will wait for an -ldisc change to complete and then return a reference to the new ldisc. +ldisc change to complete and then return a reference to the new ldisc. While these functions are slightly slower than the old code they should have minimal impact as most receive logic uses the flip buffers and they only need to take a reference when they push bits up through the driver. -A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc +A caution: The ldisc->open(), ldisc->close() and driver->set_ldisc functions are called with the ldisc unavailable. Thus tty_ldisc_ref will fail in this situation if used within these functions. Ldisc and driver -code calling its own functions must be careful in this case. +code calling its own functions must be careful in this case. Driver Interface ---------------- -open() - Called when a device is opened. May sleep +======================= ======================================================= +open() Called when a device is opened. May sleep -close() - Called when a device is closed. At the point of - return from this call the driver must make no +close() Called when a device is closed. At the point of + return from this call the driver must make no further ldisc calls of any kind. May sleep -write() - Called to write bytes to the device. May not - sleep. May occur in parallel in special cases. +write() Called to write bytes to the device. May not + sleep. May occur in parallel in special cases. Because this includes panic paths drivers generally shouldn't try and do clever locking here. -put_char() - Stuff a single character onto the queue. The +put_char() Stuff a single character onto the queue. The driver is guaranteed following up calls to flush_chars. -flush_chars() - Ask the kernel to write put_char queue +flush_chars() Ask the kernel to write put_char queue -write_room() - Return the number of characters that can be stuffed +write_room() Return the number of characters that can be stuffed into the port buffers without overflow (or less). The ldisc is responsible for being intelligent - about multi-threading of write_room/write calls + about multi-threading of write_room/write calls -ioctl() - Called when an ioctl may be for the driver +ioctl() Called when an ioctl may be for the driver -set_termios() - Called on termios change, serialized against +set_termios() Called on termios change, serialized against itself by a semaphore. May sleep. -set_ldisc() - Notifier for discipline change. At the point this +set_ldisc() Notifier for discipline change. At the point this is done the discipline is not yet usable. Can now sleep (I think) -throttle() - Called by the ldisc to ask the driver to do flow +throttle() Called by the ldisc to ask the driver to do flow control. Serialization including with unthrottle is the job of the ldisc layer. -unthrottle() - Called by the ldisc to ask the driver to stop flow +unthrottle() Called by the ldisc to ask the driver to stop flow control. -stop() - Ldisc notifier to the driver to stop output. As with +stop() Ldisc notifier to the driver to stop output. As with throttle the serializations with start() are down to the ldisc layer. -start() - Ldisc notifier to the driver to start output. +start() Ldisc notifier to the driver to start output. -hangup() - Ask the tty driver to cause a hangup initiated +hangup() Ask the tty driver to cause a hangup initiated from the host side. [Can sleep ??] -break_ctl() - Send RS232 break. Can sleep. Can get called in +break_ctl() Send RS232 break. Can sleep. Can get called in parallel, driver must serialize (for now), and with write calls. -wait_until_sent() - Wait for characters to exit the hardware queue +wait_until_sent() Wait for characters to exit the hardware queue of the driver. Can sleep -send_xchar() - Send XON/XOFF and if possible jump the queue with +send_xchar() Send XON/XOFF and if possible jump the queue with it in order to get fast flow control responses. Cannot sleep ?? - +======================= ======================================================= diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 6b154dbb02cc..132f5eb9b530 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -324,7 +324,7 @@ to details explained in the following section. strcpy(card->driver, "My Chip"); strcpy(card->shortname, "My Own Chip 123"); sprintf(card->longname, "%s at 0x%lx irq %i", - card->shortname, chip->ioport, chip->irq); + card->shortname, chip->port, chip->irq); /* (5) */ .... /* implemented later */ @@ -437,7 +437,7 @@ Since each component can be properly freed, the single strcpy(card->driver, "My Chip"); strcpy(card->shortname, "My Own Chip 123"); sprintf(card->longname, "%s at 0x%lx irq %i", - card->shortname, chip->ioport, chip->irq); + card->shortname, chip->port, chip->irq); The driver field holds the minimal ID string of the chip. This is used by alsa-lib's configurator, so keep it simple but unique. Even the diff --git a/Documentation/sparc/adi.txt b/Documentation/sparc/adi.rst index e1aed155fb89..857ad30f9569 100644 --- a/Documentation/sparc/adi.txt +++ b/Documentation/sparc/adi.rst @@ -1,3 +1,4 @@ +================================ Application Data Integrity (ADI) ================================ @@ -44,12 +45,15 @@ provided by the hypervisor to the kernel. Kernel returns the value of ADI block size to userspace using auxiliary vector along with other ADI info. Following auxiliary vectors are provided by the kernel: + ============ =========================================== AT_ADI_BLKSZ ADI block size. This is the granularity and alignment, in bytes, of ADI versioning. AT_ADI_NBITS Number of ADI version bits in the VA + ============ =========================================== -IMPORTANT NOTES: +IMPORTANT NOTES +=============== - Version tag values of 0x0 and 0xf are reserved. These values match any tag in virtual address and never generate a mismatch exception. @@ -86,11 +90,12 @@ IMPORTANT NOTES: ADI related traps ------------------ +================= With ADI enabled, following new traps may occur: Disrupting memory corruption +---------------------------- When a store accesses a memory localtion that has TTE.mcd=1, the task is running with ADI enabled (PSTATE.mcde=1), and the ADI @@ -100,7 +105,7 @@ Disrupting memory corruption first. Hypervisor creates a sun4v error report and sends a resumable error (TT=0x7e) trap to the kernel. The kernel sends a SIGSEGV to the task that resulted in this trap with the following - info: + info:: siginfo.si_signo = SIGSEGV; siginfo.errno = 0; @@ -110,6 +115,7 @@ Disrupting memory corruption Precise memory corruption +------------------------- When a store accesses a memory location that has TTE.mcd=1, the task is running with ADI enabled (PSTATE.mcde=1), and the ADI @@ -118,7 +124,7 @@ Precise memory corruption MCD precise exception is enabled (MCDPERR=1), a precise exception is sent to the kernel with TT=0x1a. The kernel sends a SIGSEGV to the task that resulted in this trap with the following - info: + info:: siginfo.si_signo = SIGSEGV; siginfo.errno = 0; @@ -126,17 +132,19 @@ Precise memory corruption siginfo.si_addr = addr; /* address that caused trap */ siginfo.si_trapno = 0; - NOTE: ADI tag mismatch on a load always results in precise trap. + NOTE: + ADI tag mismatch on a load always results in precise trap. MCD disabled +------------ When a task has not enabled ADI and attempts to set ADI version on a memory address, processor sends an MCD disabled trap. This trap is handled by hypervisor first and the hypervisor vectors this trap through to the kernel as Data Access Exception trap with fault type set to 0xa (invalid ASI). When this occurs, the kernel - sends the task SIGSEGV signal with following info: + sends the task SIGSEGV signal with following info:: siginfo.si_signo = SIGSEGV; siginfo.errno = 0; @@ -149,35 +157,35 @@ Sample program to use ADI ------------------------- Following sample program is meant to illustrate how to use the ADI -functionality. - -#include <unistd.h> -#include <stdio.h> -#include <stdlib.h> -#include <elf.h> -#include <sys/ipc.h> -#include <sys/shm.h> -#include <sys/mman.h> -#include <asm/asi.h> - -#ifndef AT_ADI_BLKSZ -#define AT_ADI_BLKSZ 48 -#endif -#ifndef AT_ADI_NBITS -#define AT_ADI_NBITS 49 -#endif - -#ifndef PROT_ADI -#define PROT_ADI 0x10 -#endif - -#define BUFFER_SIZE 32*1024*1024UL - -main(int argc, char* argv[], char* envp[]) -{ - unsigned long i, mcde, adi_blksz, adi_nbits; - char *shmaddr, *tmp_addr, *end, *veraddr, *clraddr; - int shmid, version; +functionality:: + + #include <unistd.h> + #include <stdio.h> + #include <stdlib.h> + #include <elf.h> + #include <sys/ipc.h> + #include <sys/shm.h> + #include <sys/mman.h> + #include <asm/asi.h> + + #ifndef AT_ADI_BLKSZ + #define AT_ADI_BLKSZ 48 + #endif + #ifndef AT_ADI_NBITS + #define AT_ADI_NBITS 49 + #endif + + #ifndef PROT_ADI + #define PROT_ADI 0x10 + #endif + + #define BUFFER_SIZE 32*1024*1024UL + + main(int argc, char* argv[], char* envp[]) + { + unsigned long i, mcde, adi_blksz, adi_nbits; + char *shmaddr, *tmp_addr, *end, *veraddr, *clraddr; + int shmid, version; Elf64_auxv_t *auxv; adi_blksz = 0; @@ -202,77 +210,77 @@ main(int argc, char* argv[], char* envp[]) printf("\tBlock size = %ld\n", adi_blksz); printf("\tNumber of bits = %ld\n", adi_nbits); - if ((shmid = shmget(2, BUFFER_SIZE, - IPC_CREAT | SHM_R | SHM_W)) < 0) { - perror("shmget failed"); - exit(1); - } + if ((shmid = shmget(2, BUFFER_SIZE, + IPC_CREAT | SHM_R | SHM_W)) < 0) { + perror("shmget failed"); + exit(1); + } - shmaddr = shmat(shmid, NULL, 0); - if (shmaddr == (char *)-1) { - perror("shm attach failed"); - shmctl(shmid, IPC_RMID, NULL); - exit(1); - } + shmaddr = shmat(shmid, NULL, 0); + if (shmaddr == (char *)-1) { + perror("shm attach failed"); + shmctl(shmid, IPC_RMID, NULL); + exit(1); + } if (mprotect(shmaddr, BUFFER_SIZE, PROT_READ|PROT_WRITE|PROT_ADI)) { perror("mprotect failed"); goto err_out; } - /* Set the ADI version tag on the shm segment - */ - version = 10; - tmp_addr = shmaddr; - end = shmaddr + BUFFER_SIZE; - while (tmp_addr < end) { - asm volatile( - "stxa %1, [%0]0x90\n\t" - : - : "r" (tmp_addr), "r" (version)); - tmp_addr += adi_blksz; - } + /* Set the ADI version tag on the shm segment + */ + version = 10; + tmp_addr = shmaddr; + end = shmaddr + BUFFER_SIZE; + while (tmp_addr < end) { + asm volatile( + "stxa %1, [%0]0x90\n\t" + : + : "r" (tmp_addr), "r" (version)); + tmp_addr += adi_blksz; + } asm volatile("membar #Sync\n\t"); - /* Create a versioned address from the normal address by placing + /* Create a versioned address from the normal address by placing * version tag in the upper adi_nbits bits - */ - tmp_addr = (void *) ((unsigned long)shmaddr << adi_nbits); - tmp_addr = (void *) ((unsigned long)tmp_addr >> adi_nbits); - veraddr = (void *) (((unsigned long)version << (64-adi_nbits)) - | (unsigned long)tmp_addr); - - printf("Starting the writes:\n"); - for (i = 0; i < BUFFER_SIZE; i++) { - veraddr[i] = (char)(i); - if (!(i % (1024 * 1024))) - printf("."); - } - printf("\n"); - - printf("Verifying data..."); + */ + tmp_addr = (void *) ((unsigned long)shmaddr << adi_nbits); + tmp_addr = (void *) ((unsigned long)tmp_addr >> adi_nbits); + veraddr = (void *) (((unsigned long)version << (64-adi_nbits)) + | (unsigned long)tmp_addr); + + printf("Starting the writes:\n"); + for (i = 0; i < BUFFER_SIZE; i++) { + veraddr[i] = (char)(i); + if (!(i % (1024 * 1024))) + printf("."); + } + printf("\n"); + + printf("Verifying data..."); fflush(stdout); - for (i = 0; i < BUFFER_SIZE; i++) - if (veraddr[i] != (char)i) - printf("\nIndex %lu mismatched\n", i); - printf("Done.\n"); + for (i = 0; i < BUFFER_SIZE; i++) + if (veraddr[i] != (char)i) + printf("\nIndex %lu mismatched\n", i); + printf("Done.\n"); - /* Disable ADI and clean up - */ + /* Disable ADI and clean up + */ if (mprotect(shmaddr, BUFFER_SIZE, PROT_READ|PROT_WRITE)) { perror("mprotect failed"); goto err_out; } - if (shmdt((const void *)shmaddr) != 0) - perror("Detach failure"); - shmctl(shmid, IPC_RMID, NULL); + if (shmdt((const void *)shmaddr) != 0) + perror("Detach failure"); + shmctl(shmid, IPC_RMID, NULL); - exit(0); + exit(0); -err_out: - if (shmdt((const void *)shmaddr) != 0) - perror("Detach failure"); - shmctl(shmid, IPC_RMID, NULL); - exit(1); -} + err_out: + if (shmdt((const void *)shmaddr) != 0) + perror("Detach failure"); + shmctl(shmid, IPC_RMID, NULL); + exit(1); + } diff --git a/Documentation/sparc/console.txt b/Documentation/sparc/console.rst index 5aa735a44e02..73132db83ece 100644 --- a/Documentation/sparc/console.txt +++ b/Documentation/sparc/console.rst @@ -1,5 +1,5 @@ -Steps for sending 'break' on sunhv console: -=========================================== +Steps for sending 'break' on sunhv console +========================================== On Baremetal: 1. press Esc + 'B' diff --git a/Documentation/sparc/index.rst b/Documentation/sparc/index.rst new file mode 100644 index 000000000000..91f7d6643dd5 --- /dev/null +++ b/Documentation/sparc/index.rst @@ -0,0 +1,13 @@ +:orphan: + +================== +Sparc Architecture +================== + +.. toctree:: + :maxdepth: 1 + + console + adi + + oradax/oracle-dax diff --git a/Documentation/sparc/oradax/oracle-dax.txt b/Documentation/sparc/oradax/oracle-dax.rst index 9d53ac93286f..d1e14d572918 100644 --- a/Documentation/sparc/oradax/oracle-dax.txt +++ b/Documentation/sparc/oradax/oracle-dax.rst @@ -1,5 +1,6 @@ +======================================= Oracle Data Analytics Accelerator (DAX) ---------------------------------------- +======================================= DAX is a coprocessor which resides on the SPARC M7 (DAX1) and M8 (DAX2) processor chips, and has direct access to the CPU's L3 caches @@ -17,6 +18,7 @@ code sufficient to write user or kernel applications that use DAX functionality. The user library is open source and available at: + https://oss.oracle.com/git/gitweb.cgi?p=libdax.git The Hypervisor interface to the coprocessor is described in detail in @@ -26,7 +28,7 @@ Specification" version 3.0.20+15, dated 2017-09-25. High Level Overview -------------------- +=================== A coprocessor request is described by a Command Control Block (CCB). The CCB contains an opcode and various parameters. The opcode @@ -52,7 +54,7 @@ thread. Addressing Memory ------------------ +================= The kernel does not have access to physical memory in the Sun4v architecture, as there is an additional level of memory virtualization @@ -77,7 +79,7 @@ the request. The Driver API --------------- +============== An application makes requests to the driver via the write() system call, and gets results (if any) via read(). The completion areas are @@ -108,6 +110,7 @@ equal to the number of bytes given in the call. Otherwise -1 is returned and errno is set. CCB_DEQUEUE +----------- Tells the driver to clean up resources associated with past requests. Since no interrupt is generated upon the completion of a @@ -116,12 +119,14 @@ further status information is returned, so the user should not subsequently call read(). CCB_KILL +-------- Kills a CCB during execution. The CCB is guaranteed to not continue executing once this call returns successfully. On success, read() must be called to retrieve the result of the action. CCB_INFO +-------- Retrieves information about a currently executing CCB. Note that some Hypervisors might return 'notfound' when the CCB is in 'inprogress' @@ -130,6 +135,7 @@ CCB_KILL must be invoked on that CCB. Upon success, read() must be called to retrieve the details of the action. Submission of an array of CCBs for execution +--------------------------------------------- A write() whose length is a multiple of the CCB size is treated as a submit operation. The file offset is treated as the index of the @@ -146,6 +152,7 @@ status will reflect the error caused by the first CCB that was not accepted, and status_data will provide additional data in some cases. MMAP +---- The mmap() function provides access to the completion area allocated in the driver. Note that the completion area is not writeable by the @@ -153,7 +160,7 @@ user process, and the mmap call must not specify PROT_WRITE. Completion of a Request ------------------------ +======================= The first byte in each completion area is the command status which is updated by the coprocessor hardware. Software may take advantage of @@ -172,7 +179,7 @@ and resumption of execution may be just a few nanoseconds. Application Life Cycle of a DAX Submission ------------------------------------------- +========================================== - open dax device - call mmap() to get the completion area address @@ -187,7 +194,7 @@ Application Life Cycle of a DAX Submission Memory Constraints ------------------- +================== The DAX hardware operates only on physical addresses. Therefore, it is not aware of virtual memory mappings and the discontiguities that may @@ -226,7 +233,7 @@ CCB Structure ------------- A CCB is an array of 8 64-bit words. Several of these words provide command opcodes, parameters, flags, etc., and the rest are addresses -for the completion area, output buffer, and various inputs: +for the completion area, output buffer, and various inputs:: struct ccb { u64 control; @@ -252,7 +259,7 @@ The first word (control) is examined by the driver for the following: Example Code ------------- +============ The DAX is accessible to both user and kernel code. The kernel code can make hypercalls directly while the user code must use wrappers @@ -265,7 +272,7 @@ arch/sparc/include/uapi/asm/oradax.h must be included. First, the proper device must be opened. For M7 it will be /dev/oradax1 and for M8 it will be /dev/oradax2. The simplest -procedure is to attempt to open both, as only one will succeed: +procedure is to attempt to open both, as only one will succeed:: fd = open("/dev/oradax1", O_RDWR); if (fd < 0) @@ -273,7 +280,7 @@ procedure is to attempt to open both, as only one will succeed: if (fd < 0) /* No DAX found */ -Next, the completion area must be mapped: +Next, the completion area must be mapped:: completion_area = mmap(NULL, DAX_MMAP_LEN, PROT_READ, MAP_SHARED, fd, 0); @@ -295,7 +302,7 @@ is the input bitmap inverted. For details of all the parameters and bits used in this CCB, please refer to section 36.2.1.3 of the DAX Hypervisor API document, which -describes the Scan command in detail. +describes the Scan command in detail:: ccb->control = /* Table 36.1, CCB Header Format */ (2L << 48) /* command = Scan Value */ @@ -326,7 +333,7 @@ describes the Scan command in detail. The CCB submission is a write() or pwrite() system call to the driver. If the call fails, then a read() must be used to retrieve the -status: +status:: if (pwrite(fd, ccb, 64, 0) != 64) { struct ccb_exec_result status; @@ -337,7 +344,7 @@ status: After a successful submission of the CCB, the completion area may be polled to determine when the DAX is finished. Detailed information on the contents of the completion area can be found in section 36.2.2 of -the DAX HV API document. +the DAX HV API document:: while (1) { /* Monitored Load */ @@ -355,7 +362,7 @@ the DAX HV API document. A completion area status of 1 indicates successful completion of the CCB and validity of the output bitmap, which may be used immediately. All other non-zero values indicate error conditions which are -described in section 36.2.2. +described in section 36.2.2:: if (completion_area[0] != 1) { /* section 36.2.2, 1 = command ran and succeeded */ /* completion_area[0] contains the completion status */ @@ -364,7 +371,7 @@ described in section 36.2.2. After the completion area has been processed, the driver must be notified that it can release any resources associated with the -request. This is done via the dequeue operation: +request. This is done via the dequeue operation:: struct dax_command cmd; cmd.command = CCB_DEQUEUE; @@ -375,13 +382,14 @@ request. This is done via the dequeue operation: Finally, normal program cleanup should be done, i.e., unmapping completion area, closing the dax device, freeing memory etc. -[Kernel example] +Kernel example +-------------- The only difference in using the DAX in kernel code is the treatment of the completion area. Unlike user applications which mmap the completion area allocated by the driver, kernel code must allocate its own memory to use for the completion area, and this address and its -type must be given in the CCB: +type must be given in the CCB:: ccb->control |= /* Table 36.1, CCB Header Format */ (3L << 32); /* completion area address type = primary virtual */ @@ -389,9 +397,11 @@ type must be given in the CCB: ccb->completion = (unsigned long) completion_area; /* Completion area address */ The dax submit hypercall is made directly. The flags used in the -ccb_submit call are documented in the DAX HV API in section 36.3.1. +ccb_submit call are documented in the DAX HV API in section 36.3.1/ -#include <asm/hypervisor.h> +:: + + #include <asm/hypervisor.h> hv_rv = sun4v_ccb_submit((unsigned long)ccb, 64, HV_CCB_QUERY_CMD | @@ -405,7 +415,7 @@ ccb_submit call are documented in the DAX HV API in section 36.3.1. } After the submission, the completion area polling code is identical to -that in user land: +that in user land:: while (1) { /* Monitored Load */ @@ -427,3 +437,9 @@ that in user land: The output bitmap is ready for consumption immediately after the completion status indicates success. + +Excer[t from UltraSPARC Virtual Machine Specification +===================================================== + + .. include:: dax-hv-api.txt + :literal: diff --git a/Documentation/speculation.txt b/Documentation/speculation.txt index e9e6cbae2841..50d7ea857cff 100644 --- a/Documentation/speculation.txt +++ b/Documentation/speculation.txt @@ -17,7 +17,7 @@ observed to extract secret information. For example, in the presence of branch prediction, it is possible for bounds checks to be ignored by code which is speculatively executed. Consider the -following code: +following code:: int load_array(int *array, unsigned int index) { @@ -27,7 +27,7 @@ following code: return array[index]; } -Which, on arm64, may be compiled to an assembly sequence such as: +Which, on arm64, may be compiled to an assembly sequence such as:: CMP <index>, #MAX_ARRAY_ELEMS B.LT less @@ -44,7 +44,7 @@ microarchitectural state which can be subsequently measured. More complex sequences involving multiple dependent memory accesses may result in sensitive information being leaked. Consider the following -code, building on the prior example: +code, building on the prior example:: int load_dependent_arrays(int *arr1, int *arr2, int index) { @@ -77,7 +77,7 @@ A call to array_index_nospec(index, size) returns a sanitized index value that is bounded to [0, size) even under cpu speculation conditions. -This can be used to protect the earlier load_array() example: +This can be used to protect the earlier load_array() example:: int load_array(int *array, unsigned int index) { diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary index 1721c1b570c3..1a63194b74d7 100644 --- a/Documentation/spi/spi-summary +++ b/Documentation/spi/spi-summary @@ -572,6 +572,12 @@ SPI MASTER METHODS 0: transfer is finished 1: transfer is still in progress + master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, + u8 hold_clk_cycles, u8 inactive_clk_cycles) + This method allows SPI client drivers to request SPI master controller + for configuring device specific CS setup, hold and inactive timing + requirements. + DEPRECATED METHODS master->transfer(struct spi_device *spi, struct spi_message *message) diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index aa058aa7bf28..f0c86fbb3b48 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -196,7 +196,7 @@ CAP_LAST_CAP from the kernel. core_pattern: core_pattern is used to specify a core dumpfile pattern name. -. max length 128 characters; default value is "core" +. max length 127 characters; default value is "core" . core_pattern is used as a pattern template for the output filename; certain string patterns (beginning with '%') are substituted with their actual values. diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 3f13d8599337..749322060f10 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -61,6 +61,7 @@ Currently, these files are in /proc/sys/vm: - stat_refresh - numa_stat - swappiness +- unprivileged_userfaultfd - user_reserve_kbytes - vfs_cache_pressure - watermark_boost_factor @@ -818,6 +819,17 @@ The default value is 60. ============================================================== +unprivileged_userfaultfd + +This flag controls whether unprivileged users can use the userfaultfd +system calls. Set this to 1 to allow unprivileged users to use the +userfaultfd system calls, or set this to 0 to restrict userfaultfd to only +privileged users (with SYS_CAP_PTRACE capability). + +The default value is 1. + +============================================================== + - user_reserve_kbytes When overcommit_memory is set to 2, "never overcommit" mode, reserve diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt index 911399730c1c..c3fa500df92c 100644 --- a/Documentation/thermal/sysfs-api.txt +++ b/Documentation/thermal/sysfs-api.txt @@ -316,7 +316,7 @@ ACPI thermal zones. |---temp[1-*]_input: The current temperature of thermal zone [1-*] |---temp[1-*]_critical: The critical trip point of thermal zone [1-*] -Please read Documentation/hwmon/sysfs-interface for additional information. +Please read Documentation/hwmon/sysfs-interface.rst for additional information. *************************** * Thermal zone attributes * diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index 7c5e6d6ab5d1..c3b9bd2fd512 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -1404,6 +1404,7 @@ trace has provided some very helpful debugging information. If we prefer function graph output instead of function, we can set display-graph option:: + with echo 1 > options/display-graph # tracer: irqsoff diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index 0ea59d45aef1..ddbaffa530f9 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -1915,7 +1915,10 @@ The following commonly-used handler.action pairs are available: The 'matching.event' specification is simply the fully qualified event name of the event that matches the target event for the - onmatch() functionality, in the form 'system.event_name'. + onmatch() functionality, in the form 'system.event_name'. Histogram + keys of both events are compared to find if events match. In case + multiple histogram keys are used, they all must match in the specified + order. Finally, the number and type of variables/fields in the 'param list' must match the number and types of the fields in the @@ -1978,9 +1981,9 @@ The following commonly-used handler.action pairs are available: /sys/kernel/debug/tracing/events/sched/sched_waking/trigger Then, when the corresponding thread is actually scheduled onto the - CPU by a sched_switch event, calculate the latency and use that - along with another variable and an event field to generate a - wakeup_latency synthetic event:: + CPU by a sched_switch event (saved_pid matches next_pid), calculate + the latency and use that along with another variable and an event field + to generate a wakeup_latency synthetic event:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:\ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,\ @@ -2133,33 +2136,33 @@ The following commonly-used handler.action pairs are available: the end the event that triggered the snapshot (in this case you can verify the timestamps between the sched_waking and sched_switch events, which should match the time displayed in the - global maximum): - - # cat /sys/kernel/debug/tracing/snapshot - - <...>-2103 [005] d..3 309.873125: sched_switch: prev_comm=cyclictest prev_pid=2103 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120 - <idle>-0 [005] d.h3 309.873611: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005 - <idle>-0 [005] dNh4 309.873613: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005 - <idle>-0 [005] d..3 309.873616: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19 - <...>-2102 [005] d..3 309.873625: sched_switch: prev_comm=cyclictest prev_pid=2102 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120 - <idle>-0 [005] d.h3 309.874624: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005 - <idle>-0 [005] dNh4 309.874626: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005 - <idle>-0 [005] dNh3 309.874628: sched_waking: comm=cyclictest pid=2103 prio=19 target_cpu=005 - <idle>-0 [005] dNh4 309.874630: sched_wakeup: comm=cyclictest pid=2103 prio=19 target_cpu=005 - <idle>-0 [005] d..3 309.874633: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19 - <idle>-0 [004] d.h3 309.874757: sched_waking: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004 - <idle>-0 [004] dNh4 309.874762: sched_wakeup: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004 - <idle>-0 [004] d..3 309.874766: sched_switch: prev_comm=swapper/4 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=gnome-terminal- next_pid=1699 next_prio=120 - gnome-terminal--1699 [004] d.h2 309.874941: sched_stat_runtime: comm=gnome-terminal- pid=1699 runtime=180706 [ns] vruntime=1126870572 [ns] - <idle>-0 [003] d.s4 309.874956: sched_waking: comm=rcu_sched pid=9 prio=120 target_cpu=007 - <idle>-0 [003] d.s5 309.874960: sched_wake_idle_without_ipi: cpu=7 - <idle>-0 [003] d.s5 309.874961: sched_wakeup: comm=rcu_sched pid=9 prio=120 target_cpu=007 - <idle>-0 [007] d..3 309.874963: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=rcu_sched next_pid=9 next_prio=120 - rcu_sched-9 [007] d..3 309.874973: sched_stat_runtime: comm=rcu_sched pid=9 runtime=13646 [ns] vruntime=22531430286 [ns] - rcu_sched-9 [007] d..3 309.874978: sched_switch: prev_comm=rcu_sched prev_pid=9 prev_prio=120 prev_state=R+ ==> next_comm=swapper/7 next_pid=0 next_prio=120 - <...>-2102 [005] d..4 309.874994: sched_migrate_task: comm=cyclictest pid=2103 prio=19 orig_cpu=5 dest_cpu=1 - <...>-2102 [005] d..4 309.875185: sched_wake_idle_without_ipi: cpu=1 - <idle>-0 [001] d..3 309.875200: sched_switch: prev_comm=swapper/1 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2103 next_prio=19 + global maximum):: + + # cat /sys/kernel/debug/tracing/snapshot + + <...>-2103 [005] d..3 309.873125: sched_switch: prev_comm=cyclictest prev_pid=2103 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120 + <idle>-0 [005] d.h3 309.873611: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005 + <idle>-0 [005] dNh4 309.873613: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005 + <idle>-0 [005] d..3 309.873616: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19 + <...>-2102 [005] d..3 309.873625: sched_switch: prev_comm=cyclictest prev_pid=2102 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120 + <idle>-0 [005] d.h3 309.874624: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005 + <idle>-0 [005] dNh4 309.874626: sched_wakeup: comm=cyclictest pid=2102 prio=19 target_cpu=005 + <idle>-0 [005] dNh3 309.874628: sched_waking: comm=cyclictest pid=2103 prio=19 target_cpu=005 + <idle>-0 [005] dNh4 309.874630: sched_wakeup: comm=cyclictest pid=2103 prio=19 target_cpu=005 + <idle>-0 [005] d..3 309.874633: sched_switch: prev_comm=swapper/5 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2102 next_prio=19 + <idle>-0 [004] d.h3 309.874757: sched_waking: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004 + <idle>-0 [004] dNh4 309.874762: sched_wakeup: comm=gnome-terminal- pid=1699 prio=120 target_cpu=004 + <idle>-0 [004] d..3 309.874766: sched_switch: prev_comm=swapper/4 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=gnome-terminal- next_pid=1699 next_prio=120 + gnome-terminal--1699 [004] d.h2 309.874941: sched_stat_runtime: comm=gnome-terminal- pid=1699 runtime=180706 [ns] vruntime=1126870572 [ns] + <idle>-0 [003] d.s4 309.874956: sched_waking: comm=rcu_sched pid=9 prio=120 target_cpu=007 + <idle>-0 [003] d.s5 309.874960: sched_wake_idle_without_ipi: cpu=7 + <idle>-0 [003] d.s5 309.874961: sched_wakeup: comm=rcu_sched pid=9 prio=120 target_cpu=007 + <idle>-0 [007] d..3 309.874963: sched_switch: prev_comm=swapper/7 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=rcu_sched next_pid=9 next_prio=120 + rcu_sched-9 [007] d..3 309.874973: sched_stat_runtime: comm=rcu_sched pid=9 runtime=13646 [ns] vruntime=22531430286 [ns] + rcu_sched-9 [007] d..3 309.874978: sched_switch: prev_comm=rcu_sched prev_pid=9 prev_prio=120 prev_state=R+ ==> next_comm=swapper/7 next_pid=0 next_prio=120 + <...>-2102 [005] d..4 309.874994: sched_migrate_task: comm=cyclictest pid=2103 prio=19 orig_cpu=5 dest_cpu=1 + <...>-2102 [005] d..4 309.875185: sched_wake_idle_without_ipi: cpu=1 + <idle>-0 [001] d..3 309.875200: sched_switch: prev_comm=swapper/1 prev_pid=0 prev_prio=120 prev_state=S ==> next_comm=cyclictest next_pid=2103 next_prio=19 - onchange(var).save(field,.. .) @@ -2213,9 +2216,10 @@ The following commonly-used handler.action pairs are available: following the rest of the fields. If a snaphot was taken, there is also a message indicating that, - along with the value and event that triggered the snapshot: + along with the value and event that triggered the snapshot:: + + # cat /sys/kernel/debug/tracing/events/tcp/tcp_probe/hist - # cat /sys/kernel/debug/tracing/events/tcp/tcp_probe/hist { dport: 1521 } hitcount: 8 changed: 10 snd_wnd: 35456 srtt: 154262 rcv_wnd: 42112 @@ -2228,14 +2232,15 @@ The following commonly-used handler.action pairs are available: { dport: 443 } hitcount: 211 changed: 10 snd_wnd: 26960 srtt: 17379 rcv_wnd: 28800 - Snapshot taken (see tracing/snapshot). Details: + Snapshot taken (see tracing/snapshot). Details:: + triggering value { onchange($cwnd) }: 10 triggered by event with key: { dport: 80 } - Totals: - Hits: 414 - Entries: 4 - Dropped: 0 + Totals: + Hits: 414 + Entries: 4 + Dropped: 0 In the above case, the event that triggered the snapshot has the key with dport == 80. If you look at the bucket that has 80 as @@ -2245,18 +2250,18 @@ The following commonly-used handler.action pairs are available: the global snapshot). And finally, looking at the snapshot data should show at or near - the end the event that triggered the snapshot: - - # cat /sys/kernel/debug/tracing/snapshot - - gnome-shell-1261 [006] dN.3 49.823113: sched_stat_runtime: comm=gnome-shell pid=1261 runtime=49347 [ns] vruntime=1835730389 [ns] - kworker/u16:4-773 [003] d..3 49.823114: sched_switch: prev_comm=kworker/u16:4 prev_pid=773 prev_prio=120 prev_state=R+ ==> next_comm=kworker/3:2 next_pid=135 next_prio=120 - gnome-shell-1261 [006] d..3 49.823114: sched_switch: prev_comm=gnome-shell prev_pid=1261 prev_prio=120 prev_state=R+ ==> next_comm=kworker/6:2 next_pid=387 next_prio=120 - kworker/3:2-135 [003] d..3 49.823118: sched_stat_runtime: comm=kworker/3:2 pid=135 runtime=5339 [ns] vruntime=17815800388 [ns] - kworker/6:2-387 [006] d..3 49.823120: sched_stat_runtime: comm=kworker/6:2 pid=387 runtime=9594 [ns] vruntime=14589605367 [ns] - kworker/6:2-387 [006] d..3 49.823122: sched_switch: prev_comm=kworker/6:2 prev_pid=387 prev_prio=120 prev_state=R+ ==> next_comm=gnome-shell next_pid=1261 next_prio=120 - kworker/3:2-135 [003] d..3 49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120 - <idle>-0 [004] ..s7 49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312 + the end the event that triggered the snapshot:: + + # cat /sys/kernel/debug/tracing/snapshot + + gnome-shell-1261 [006] dN.3 49.823113: sched_stat_runtime: comm=gnome-shell pid=1261 runtime=49347 [ns] vruntime=1835730389 [ns] + kworker/u16:4-773 [003] d..3 49.823114: sched_switch: prev_comm=kworker/u16:4 prev_pid=773 prev_prio=120 prev_state=R+ ==> next_comm=kworker/3:2 next_pid=135 next_prio=120 + gnome-shell-1261 [006] d..3 49.823114: sched_switch: prev_comm=gnome-shell prev_pid=1261 prev_prio=120 prev_state=R+ ==> next_comm=kworker/6:2 next_pid=387 next_prio=120 + kworker/3:2-135 [003] d..3 49.823118: sched_stat_runtime: comm=kworker/3:2 pid=135 runtime=5339 [ns] vruntime=17815800388 [ns] + kworker/6:2-387 [006] d..3 49.823120: sched_stat_runtime: comm=kworker/6:2 pid=387 runtime=9594 [ns] vruntime=14589605367 [ns] + kworker/6:2-387 [006] d..3 49.823122: sched_switch: prev_comm=kworker/6:2 prev_pid=387 prev_prio=120 prev_state=R+ ==> next_comm=gnome-shell next_pid=1261 next_prio=120 + kworker/3:2-135 [003] d..3 49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120 + <idle>-0 [004] ..s7 49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312 3. User space creating a trigger -------------------------------- diff --git a/Documentation/trace/intel_th.rst b/Documentation/trace/intel_th.rst index 19e2d633f3c7..baa12eb09ef4 100644 --- a/Documentation/trace/intel_th.rst +++ b/Documentation/trace/intel_th.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ======================= Intel(R) Trace Hub (TH) ======================= diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index 66bfd8396877..995da15b16ca 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -113,7 +113,7 @@ my $regex_kswapd_wake_default = 'nid=([0-9]*) order=([0-9]*)'; my $regex_kswapd_sleep_default = 'nid=([0-9]*)'; my $regex_wakeup_kswapd_default = 'nid=([0-9]*) zid=([0-9]*) order=([0-9]*) gfp_flags=([A-Z_|]*)'; my $regex_lru_isolate_default = 'isolate_mode=([0-9]*) classzone_idx=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_skipped=([0-9]*) nr_taken=([0-9]*) lru=([a-z_]*)'; -my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) nr_dirty=([0-9]*) nr_writeback=([0-9]*) nr_congested=([0-9]*) nr_immediate=([0-9]*) nr_activate=([0-9]*) nr_ref_keep=([0-9]*) nr_unmap_fail=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; +my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) nr_dirty=([0-9]*) nr_writeback=([0-9]*) nr_congested=([0-9]*) nr_immediate=([0-9]*) nr_activate_anon=([0-9]*) nr_activate_file=([0-9]*) nr_ref_keep=([0-9]*) nr_unmap_fail=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_scanned=([0-9]*) nr_rotated=([0-9]*) priority=([0-9]*)'; my $regex_writepage_default = 'page=([0-9a-f]*) pfn=([0-9]*) flags=([A-Z_|]*)'; @@ -212,7 +212,8 @@ $regex_lru_shrink_inactive = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_inactive", $regex_lru_shrink_inactive_default, "nid", "nr_scanned", "nr_reclaimed", "nr_dirty", "nr_writeback", - "nr_congested", "nr_immediate", "nr_activate", "nr_ref_keep", + "nr_congested", "nr_immediate", "nr_activate_anon", + "nr_activate_file", "nr_ref_keep", "nr_unmap_fail", "priority", "flags"); $regex_lru_shrink_active = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_active", @@ -407,7 +408,7 @@ EVENT_PROCESS: } my $nr_reclaimed = $3; - my $flags = $12; + my $flags = $13; my $file = 0; if ($flags =~ /RECLAIM_WB_FILE/) { $file = 1; diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst index 7f77c52d33aa..e446e5ed00a6 100644 --- a/Documentation/translations/index.rst +++ b/Documentation/translations/index.rst @@ -11,3 +11,43 @@ Translations it_IT/index ko_KR/index ja_JP/index + + +.. _translations_disclaimer: + +Disclaimer +---------- + +Translation's purpose is to ease reading and understanding in languages other +than English. Its aim is to help people who do not understand English or have +doubts about its interpretation. Additionally, some people prefer to read +documentation in their native language, but please bear in mind that the +*only* official documentation is the English one: :ref:`linux_doc`. + +It is very unlikely that an update to :ref:`linux_doc` will be propagated +immediately to all translations. Translations' maintainers - and +contributors - follow the evolution of the official documentation and they +maintain translations aligned as much as they can. For this reason there is +no guarantee that a translation is up to date. If what you read in a +translation does not sound right compared to what you read in the code, please +inform the translation maintainer and - if you can - check also the English +documentation. + +A translation is not a fork of the official documentation, therefore +translations' users should not find information that differs from the official +English documentation. Any content addition, removal or update, must be +applied to the English documents first. Afterwards and when possible, the +same change should be applied to translations. Translations' maintainers +accept only contributions that are merely translation related (e.g. new +translations, updates, fixes). + +Translations try to be as accurate as possible but it is not possible to map +one language directly to all other languages. Each language has its own +grammar and culture, so the translation of an English statement may need to be +adapted to fit a different language. For this reason, when viewing +translations, you may find slight differences that carry the same message but +in a different form. + +If you need to communicate with the Linux community but you do not feel +comfortable writing in English, you can ask the translation's maintainers +for help. diff --git a/Documentation/translations/it_IT/core-api/memory-allocation.rst b/Documentation/translations/it_IT/core-api/memory-allocation.rst new file mode 100644 index 000000000000..11d5148f8d6b --- /dev/null +++ b/Documentation/translations/it_IT/core-api/memory-allocation.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/core-api/memory-allocation.rst <memory_allocation>` + +.. _it_memory_allocation: + +================================ +Guida all'allocazione di memoria +================================ + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/disclaimer-ita.rst b/Documentation/translations/it_IT/disclaimer-ita.rst index d68e52de6a5d..bfe8a384baed 100644 --- a/Documentation/translations/it_IT/disclaimer-ita.rst +++ b/Documentation/translations/it_IT/disclaimer-ita.rst @@ -1,13 +1,6 @@ :orphan: -.. note:: - This document is maintained by Federico Vaga <federico.vaga@vaga.pv.it>. - 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. - Following people helped to translate or review: - Alessia Mantegazza <amantegazza@vaga.pv.it> - .. warning:: - The purpose of this file is to be easier to read and understand for Italian - 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. + In caso di dubbi sulla correttezza del contenuto di questa traduzione, + l'unico riferimento valido è la documentazione ufficiale in inglese. + Per maggiori informazioni consultate le :ref:`avvertenze <it_disclaimer>`. diff --git a/Documentation/translations/it_IT/doc-guide/index.rst b/Documentation/translations/it_IT/doc-guide/index.rst index 7a6562b547ee..9fffff626711 100644 --- a/Documentation/translations/it_IT/doc-guide/index.rst +++ b/Documentation/translations/it_IT/doc-guide/index.rst @@ -12,9 +12,9 @@ Come scrivere la documentazione del kernel .. toctree:: :maxdepth: 1 - sphinx.rst - kernel-doc.rst - parse-headers.rst + sphinx + kernel-doc + parse-headers .. only:: subproject and html diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index ea9b2916b3e4..409eaac03e9f 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -4,26 +4,49 @@ Traduzione italiana =================== -L'obiettivo di questa traduzione è di rendere piĂą facile la lettura e -la comprensione per chi preferisce leggere in lingua italiana. -Tenete presente che la documentazione di riferimento rimane comunque -quella in lingua inglese: :ref:`linux_doc` - -Questa traduzione cerca di essere il piĂą fedele possibile all'originale ma -è ovvio che alcune frasi vadano trasformate: non aspettatevi una traduzione -letterale. Quando possibile, si eviteranno gli inglesismi ed al loro posto -verranno utilizzate le corrispettive parole italiane. +:manutentore: Federico Vaga <federico.vaga@vaga.pv.it> -Se notate che la traduzione non è piĂą aggiornata potete contattare -direttamente il manutentore della traduzione italiana. +.. _it_disclaimer: -Se notate che la documentazione contiene errori o dimenticanze, allora -verificate la documentazione di riferimento in lingua inglese. Se il problema -è presente anche nella documentazione di riferimento, contattate il suo -manutentore. Se avete problemi a scrivere in inglese, potete comunque -riportare il problema al manutentore della traduzione italiana. +Avvertenze +========== -Manutentore della traduzione italiana: Federico Vaga <federico.vaga@vaga.pv.it> +L'obiettivo di questa traduzione è di rendere piĂą facile la lettura e +la comprensione per chi non capisce l'inglese o ha dubbi sulla sua +interpretazione, oppure semplicemente per chi preferisce leggere in lingua +italiana. Tuttavia, tenete ben presente che l'*unica* documentazione +ufficiale è quella in lingua inglese: :ref:`linux_doc` + +La propagazione simultanea a tutte le traduzioni di una modifica in +:ref:`linux_doc` è altamente improbabile. I manutentori delle traduzioni - +e i contributori - seguono l'evolversi della documentazione ufficiale e +cercano di mantenere le rispettive traduzioni allineate nel limite del +possibile. Per questo motivo non c'è garanzia che una traduzione sia +aggiornata all'ultima modifica. Se quello che leggete in una traduzione +non corrisponde a quello che leggete nel codice, informate il manutentore +della traduzione e - se potete - verificate anche la documentazione in +inglese. + +Una traduzione non è un *fork* della documentazione ufficiale, perciò gli +utenti non vi troveranno alcuna informazione diversa rispetto alla versione +ufficiale. Ogni aggiunta, rimozione o modifica dei contenuti deve essere +fatta prima nei documenti in inglese. In seguito, e quando è possibile, la +stessa modifica dovrebbe essere applicata anche alle traduzioni. I manutentori +delle traduzioni accettano contributi che interessano prettamente l'attivitĂ +di traduzione (per esempio, nuove traduzioni, aggiornamenti, correzioni). + +Le traduzioni cercano di essere il piĂą possibile accurate ma non è possibile +mappare direttamente una lingua in un'altra. Ogni lingua ha la sua grammatica +e una sua cultura alle spalle, quindi la traduzione di una frase in inglese +potrebbe essere modificata per adattarla all'italiano. Per questo motivo, +quando leggete questa traduzione, potreste trovare alcune differenze di forma +ma che trasmettono comunque il messaggio originale. Nonostante la grande +diffusione di inglesismi nella lingua parlata, quando possibile, questi +verranno sostituiti dalle corrispettive parole italiane + +Se avete bisogno d'aiuto per comunicare con la comunitĂ Linux ma non vi sentite +a vostro agio nello scrivere in inglese, potete chiedere aiuto al manutentore +della traduzione. La documentazione del kernel Linux ================================== @@ -47,9 +70,7 @@ I seguenti documenti descrivono la licenza usata nei sorgenti del kernel Linux (GPLv2), come licenziare i singoli file; inoltre troverete i riferimenti al testo integrale della licenza. -.. warning:: - - TODO ancora da tradurre +* :ref:`it_kernel_licensing` Documentazione per gli utenti ----------------------------- @@ -90,10 +111,6 @@ vostre modifiche molto piĂą semplice doc-guide/index kernel-hacking/index -.. warning:: - - TODO ancora da tradurre - Documentazione della API del kernel ----------------------------------- diff --git a/Documentation/translations/it_IT/networking/netdev-FAQ.rst b/Documentation/translations/it_IT/networking/netdev-FAQ.rst new file mode 100644 index 000000000000..8489ead7cff1 --- /dev/null +++ b/Documentation/translations/it_IT/networking/netdev-FAQ.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + +.. _it_netdev-FAQ: + +========== +netdev FAQ +========== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst index b979266aa884..1476d51eb5e5 100644 --- a/Documentation/translations/it_IT/process/5.Posting.rst +++ b/Documentation/translations/it_IT/process/5.Posting.rst @@ -233,10 +233,12 @@ Le etichette in uso piĂą comuni sono: :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. Codice che non presenta una firma appropriata non potrĂ essere integrato. - - Co-developed-by: indica che la patch è stata sviluppata anche da un altro - sviluppatore assieme all'autore originale. Questo è utile quando piĂą - persone lavorano sulla stessa patch. Da notare che questa persona deve - avere anche una riga "Signed-off-by:" nella patch. + - Co-developed-by: indica che la patch è stata cosviluppata da diversi + sviluppatori; viene usato per assegnare piĂą autori (in aggiunta a quello + associato all'etichetta From:) quando piĂą persone lavorano ad una patch. + Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by: + del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili + in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore del codice in oggetto) all'integrazione della patch nel kernel. diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index 2fd0e7f79d55..5ef534c95e69 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -859,7 +859,8 @@ racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...). Il kernel fornisce i seguenti assegnatori ad uso generico: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc(). -Per maggiori informazioni, consultate la documentazione dell'API. +Per maggiori informazioni, consultate la documentazione dell'API: +:ref:`Documentation/translations/it_IT/core-api/memory-allocation.rst <it_memory_allocation>` Il modo preferito per passare la dimensione di una struttura è il seguente: @@ -890,6 +891,11 @@ Il modo preferito per assegnare un vettore a zero è il seguente: Entrambe verificano la condizione di overflow per la dimensione d'assegnamento n * sizeof(...), se accade ritorneranno NULL. +Questi allocatori generici producono uno *stack dump* in caso di fallimento +a meno che non venga esplicitamente specificato __GFP_NOWARN. Quindi, nella +maggior parte dei casi, è inutile stampare messaggi aggiuntivi quando uno di +questi allocatori ritornano un puntatore NULL. + 15) Il morbo inline ------------------- diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst new file mode 100644 index 000000000000..776f26732a94 --- /dev/null +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -0,0 +1,129 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/deprecated.rst <deprecated>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_deprecated: + +============================================================================== +Interfacce deprecate, caratteristiche del linguaggio, attributi, e convenzioni +============================================================================== + +In un mondo perfetto, sarebbe possibile prendere tutti gli usi di +un'interfaccia deprecata e convertirli in quella nuova, e così sarebbe +possibile rimuovere la vecchia interfaccia in un singolo ciclo di sviluppo. +Tuttavia, per via delle dimensioni del kernel, la gerarchia dei manutentori e +le tempistiche, non è sempre possibile fare questo tipo di conversione tutta +in una volta. Questo significa che nuove istanze di una vecchia interfaccia +potrebbero aggiungersi al kernel proprio quando si sta cercando di rimuoverle, +aumentando così il carico di lavoro. Al fine di istruire gli sviluppatori su +cosa è considerato deprecato (e perchĂ©), è stata create la seguente lista a cui +fare riferimento quando qualcuno propone modifiche che usano cose deprecate. + +__deprecated +------------ +Nonostante questo attributo marchi visibilmente un interfaccia come deprecata, +`non produce piĂą alcun avviso durante la compilazione +<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ +perchĂ© uno degli obiettivi del kernel è quello di compilare senza avvisi; +inoltre, nessuno stava agendo per rimuovere queste interfacce. Nonostante l'uso +di `__deprecated` in un file d'intestazione sia opportuno per segnare una +interfaccia come 'vecchia', questa non è una soluzione completa. L'interfaccia +deve essere rimossa dal kernel, o aggiunta a questo documento per scoraggiarne +l'uso. + +Calcoli codificati negli argomenti di un allocatore +---------------------------------------------------- +Il calcolo dinamico delle dimensioni (specialmente le moltiplicazioni) non +dovrebbero essere fatto negli argomenti di funzioni di allocazione di memoria +(o simili) per via del rischio di overflow. Questo può portare a valori piĂą +piccoli di quelli che il chiamante si aspettava. L'uso di questo modo di +allocare può portare ad un overflow della memoria di heap e altri +malfunzionamenti. (Si fa eccezione per valori numerici per i quali il +compilatore può generare avvisi circa un potenziale overflow. Tuttavia usare +i valori numerici come suggerito di seguito è innocuo). + +Per esempio, non usate ``count * size`` come argomento:: + + foo = kmalloc(count * size, GFP_KERNEL); + +Al suo posto, si dovrebbe usare l'allocatore a due argomenti:: + + foo = kmalloc_array(count, size, GFP_KERNEL); + +Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate +le funzioni del tipo *saturate-on-overflow*:: + + bar = vmalloc(array_size(count, size)); + +Un altro tipico caso da evitare è quello di calcolare la dimensione di una +struttura seguita da un vettore di altre strutture, come nel seguente caso:: + + header = kzalloc(sizeof(*header) + count * sizeof(*header->item), + GFP_KERNEL); + +Invece, usate la seguente funzione:: + + header = kzalloc(struct_size(header, item, count), GFP_KERNEL); + +Per maggiori dettagli fate riferimento a :c:func:`array_size`, +:c:func:`array3_size`, e :c:func:`struct_size`, così come la famiglia di +funzioni :c:func:`check_add_overflow` e :c:func:`check_mul_overflow`. + +simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() +---------------------------------------------------------------------- +Le funzioni :c:func:`simple_strtol`, :c:func:`simple_strtoll`, +:c:func:`simple_strtoul`, e :c:func:`simple_strtoull` ignorano volutamente +i possibili overflow, e questo può portare il chiamante a generare risultati +inaspettati. Le rispettive funzioni :c:func:`kstrtol`, :c:func:`kstrtoll`, +:c:func:`kstrtoul`, e :c:func:`kstrtoull` sono da considerarsi le corrette +sostitute; tuttavia va notato che queste richiedono che la stringa sia +terminata con il carattere NUL o quello di nuova riga. + +strcpy() +-------- +La funzione :c:func:`strcpy` non fa controlli agli estremi del buffer +di destinazione. Questo può portare ad un overflow oltre i limiti del +buffer e generare svariati tipi di malfunzionamenti. Nonostante l'opzione +`CONFIG_FORTIFY_SOURCE=y` e svariate opzioni del compilatore aiutano +a ridurne il rischio, non c'è alcuna buona ragione per continuare ad usare +questa funzione. La versione sicura da usare è :c:func:`strscpy`. + +strncpy() su stringe terminate con NUL +-------------------------------------- +L'utilizzo di :c:func:`strncpy` non fornisce alcuna garanzia sul fatto che +il buffer di destinazione verrĂ terminato con il carattere NUL. Questo +potrebbe portare a diversi overflow di lettura o altri malfunzionamenti +causati, appunto, dalla mancanza del terminatore. Questa estende la +terminazione nel buffer di destinazione quando la stringa d'origine è piĂą +corta; questo potrebbe portare ad una penalizzazione delle prestazioni per +chi usa solo stringe terminate. La versione sicura da usare è +:c:func:`strscpy`. (chi usa :c:func:`strscpy` e necessita di estendere la +terminazione con NUL deve aggiungere una chiamata a :c:func:`memset`) + +Se il chiamate no usa stringhe terminate con NUL, allore :c:func:`strncpy()` +può continuare ad essere usata, ma i buffer di destinazione devono essere +marchiati con l'attributo `__nonstring <https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ +per evitare avvisi durante la compilazione. + +strlcpy() +--------- +La funzione :c:func:`strlcpy`, per prima cosa, legge interamente il buffer di +origine, magari leggendo piĂą di quanto verrĂ effettivamente copiato. Questo +è inefficiente e può portare a overflow di lettura quando la stringa non è +terminata con NUL. La versione sicura da usare è :c:func:`strscpy`. + +Vettori a dimensione variabile (VLA) +------------------------------------ + +Usare VLA sullo stack produce codice molto peggiore rispetto a quando si usano +vettori a dimensione fissa. Questi `problemi di prestazioni <https://git.kernel.org/linus/02361bc77888>`_, +tutt'altro che banali, sono giĂ un motivo valido per eliminare i VLA; in +aggiunta sono anche un problema per la sicurezza. La crescita dinamica di un +vettore nello stack potrebbe eccedere la memoria rimanente in tale segmento. +Questo può portare a dei malfunzionamenti, potrebbe sovrascrivere +dati importanti alla fine dello stack (quando il kernel è compilato senza +`CONFIG_THREAD_INFO_IN_TASK=y`), o sovrascrivere un pezzo di memoria adiacente +allo stack (quando il kernel è compilato senza `CONFIG_VMAP_STACK=y`). diff --git a/Documentation/translations/it_IT/process/kernel-enforcement-statement.rst b/Documentation/translations/it_IT/process/kernel-enforcement-statement.rst index 4ddf5a35b270..1f62da622e26 100644 --- a/Documentation/translations/it_IT/process/kernel-enforcement-statement.rst +++ b/Documentation/translations/it_IT/process/kernel-enforcement-statement.rst @@ -1,13 +1,175 @@ .. include:: ../disclaimer-ita.rst :Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` - +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> .. _it_process_statement_kernel: Applicazione della licenza sul kernel Linux =========================================== -.. warning:: +Come sviluppatori del kernel Linux, abbiamo un certo interessa su come il +nostro software viene usato e su come la sua licenza viene fatta rispettare. +Il rispetto reciproco degli obblighi di condivisione della GPL-2.0 è +fondamentale per la sostenibilitĂ di lungo periodo del nostro software e +della nostra comunitĂ . + +BenchĂ© ognuno abbia il diritto a far rispettare il diritto d'autore per i +propri contributi alla nostra comunitĂ , condividiamo l'interesse a far si che +ogni azione individuale nel far rispettare i propri diritti sia condotta in +modo da portare beneficio alla comunitĂ e che non abbia, involontariamente, +impatti negativi sulla salute e la crescita del nostro ecosistema software. +Al fine di scoraggiare l'esecuzione di azioni inutili, concordiamo che è nel +migliore interesse della nostra comunitĂ di sviluppo di impegnarci nel +rispettare i seguenti obblighi nei confronti degli utenti del kernel Linux +per conto nostro e di qualsiasi successore ai nostri interessi sul diritto +d'autore: + + Malgrado le clausole di risoluzione della licenza GPL-2.0, abbiamo + concordato che è nel migliore interesse della nostra comunitĂ di sviluppo + adottare le seguenti disposizioni della GPL-3.0 come permessi aggiuntivi + alla nostra licenza nei confronti di qualsiasi affermazione non difensiva + di diritti sulla licenza. + + In ogni caso, se cessano tutte le violazioni di questa Licenza, allora + la tua licenza da parte di un dato detentore del copyright viene + ripristinata (a) in via cautelativa, a meno che e fino a quando il + detentore del copyright non cessa esplicitamente e definitivamente + la tua licenza, e (b) in via permanente se il detentore del copyright + non ti notifica in alcun modo la violazione entro 60 giorni dalla + cessazione della licenza. + + Inoltre, la tua licenza da parte di un dato detentore del copyright + viene ripristinata in maniera permanente se il detentore del copyright + ti notifica la violazione in maniera adeguata, se questa è la prima + volta che ricevi una notifica di violazione di questa Licenza (per + qualunque Programma) dallo stesso detentore di copyright, e se rimedi + alla violazione entro 30 giorni dalla data di ricezione della notifica + di violazione. + +Fornendo queste garanzie, abbiamo l'intenzione di incoraggiare l'uso del +software. Vogliamo che le aziende e le persone usino, modifichino e +distribuiscano a questo software. Vogliamo lavorare con gli utenti in modo +aperto e trasparente per eliminare ogni incertezza circa le nostre aspettative +sul rispetto o l'ottemperanza alla licenza che possa limitare l'uso del nostro +software. Vediamo l'azione legale come ultima spiaggia, da avviare solo quando +gli altri sforzi della comunitĂ hanno fallito nel risolvere il problema. + +Per finire, una volta che un problema di non rispetto della licenza viene +risolto, speriamo che gli utenti si sentano i benvenuti ad aggregarsi a noi +nello sviluppo di questo progetto. Lavorando assieme, saremo piĂą forti. + +Ad eccezione deve specificato, parliamo per noi stessi, e non per una qualsiasi +azienda per la quale lavoriamo oggi, o per cui abbiamo lavorato in passato, o +lavoreremo in futuro. + - TODO ancora da tradurre + - Laura Abbott + - Bjorn Andersson (Linaro) + - Andrea Arcangeli + - Neil Armstrong + - Jens Axboe + - Pablo Neira Ayuso + - Khalid Aziz + - Ralf Baechle + - Felipe Balbi + - Arnd Bergmann + - Ard Biesheuvel + - Tim Bird + - Paolo Bonzini + - Christian Borntraeger + - Mark Brown (Linaro) + - Paul Burton + - Javier Martinez Canillas + - Rob Clark + - Kees Cook (Google) + - Jonathan Corbet + - Dennis Dalessandro + - Vivien Didelot (Savoir-faire Linux) + - Hans de Goede + - Mel Gorman (SUSE) + - Sven Eckelmann + - Alex Elder (Linaro) + - Fabio Estevam + - Larry Finger + - Bhumika Goyal + - Andy Gross + - Juergen Gross + - Shawn Guo + - Ulf Hansson + - Stephen Hemminger (Microsoft) + - Tejun Heo + - Rob Herring + - Masami Hiramatsu + - Michal Hocko + - Simon Horman + - Johan Hovold (Hovold Consulting AB) + - Christophe JAILLET + - Olof Johansson + - Lee Jones (Linaro) + - Heiner Kallweit + - Srinivas Kandagatla + - Jan Kara + - Shuah Khan (Samsung) + - David Kershner + - Jaegeuk Kim + - Namhyung Kim + - Colin Ian King + - Jeff Kirsher + - Greg Kroah-Hartman (Linux Foundation) + - Christian König + - Vinod Koul + - Krzysztof Kozlowski + - Viresh Kumar + - Aneesh Kumar K.V + - Julia Lawall + - Doug Ledford + - Chuck Lever (Oracle) + - Daniel Lezcano + - Shaohua Li + - Xin Long + - Tony Luck + - Catalin Marinas (Arm Ltd) + - Mike Marshall + - Chris Mason + - Paul E. McKenney + - Arnaldo Carvalho de Melo + - David S. Miller + - Ingo Molnar + - Kuninori Morimoto + - Trond Myklebust + - Martin K. Petersen (Oracle) + - Borislav Petkov + - Jiri Pirko + - Josh Poimboeuf + - Sebastian Reichel (Collabora) + - Guenter Roeck + - Joerg Roedel + - Leon Romanovsky + - Steven Rostedt (VMware) + - Frank Rowand + - Ivan Safonov + - Anna Schumaker + - Jes Sorensen + - K.Y. Srinivasan + - David Sterba (SUSE) + - Heiko Stuebner + - Jiri Kosina (SUSE) + - Willy Tarreau + - Dmitry Torokhov + - Linus Torvalds + - Thierry Reding + - Rik van Riel + - Luis R. Rodriguez + - Geert Uytterhoeven (Glider bvba) + - Eduardo Valentin (Amazon.com) + - Daniel Vetter + - Linus Walleij + - Richard Weinberger + - Dan Williams + - Rafael J. Wysocki + - Arvind Yadav + - Masahiro Yamada + - Wei Yongjun + - Lv Zheng + - Marc Zyngier (Arm Ltd) diff --git a/Documentation/translations/it_IT/process/license-rules.rst b/Documentation/translations/it_IT/process/license-rules.rst new file mode 100644 index 000000000000..f058e06996dc --- /dev/null +++ b/Documentation/translations/it_IT/process/license-rules.rst @@ -0,0 +1,500 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/license-rules.rst <kernel_licensing>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_kernel_licensing: + +Regole per licenziare il kernel Linux +===================================== + +Il kernel Linux viene rilasciato sotto i termini definiti dalla seconda +versione della licenza *GNU General Public License* (GPL-2.0), di cui una +copia è disponibile nel file LICENSES/preferred/GPL-2.0; a questo si +aggiunge eccezione per le chiamate di sistema come descritto in +LICENSES/exceptions/Linux-syscall-note; tutto ciò è descritto nel file COPYING. + +Questo documento fornisce una descrizione su come ogni singolo file sorgente +debba essere licenziato per far si che sia chiaro e non ambiguo. Questo non +sostituisce la licenza del kernel. + +La licenza descritta nel file COPYING si applica ai sorgenti del kernel nella +loro interezza, quindi i singoli file sorgenti possono avere diverse licenze ma +devono essere compatibili con la GPL-2.0:: + + GPL-1.0+ : GNU General Public License v1.0 o successiva + GPL-2.0+ : GNU General Public License v2.0 o successiva + LGPL-2.0 : GNU Library General Public License v2 + LGPL-2.0+ : GNU Library General Public License v2 o successiva + LGPL-2.1 : GNU Lesser General Public License v2.1 + LGPL-2.1+ : GNU Lesser General Public License v2.1 o successiva + +A parte questo, i singolo file possono essere forniti con una doppia licenza, +per esempio con una delle varianti compatibili della GPL e alternativamente con +una licenza permissiva come BSD, MIT eccetera. + +I file d'intestazione per l'API verso lo spazio utente (UAPI) descrivono +le interfacce usate dai programmi, e per questo sono un caso speciale. +Secondo le note nel file COPYING, le chiamate di sistema sono un chiaro +confine oltre il quale non si estendono i requisiti della GPL per quei +programmi che le usano per comunicare con il kernel. Dato che i file +d'intestazione UAPI devono poter essere inclusi nei sorgenti di un +qualsiasi programma eseguibile sul kernel Linux, questi meritano +un'eccezione documentata da una clausola speciale. + +Il modo piĂą comune per indicare la licenza dei file sorgenti è quello di +aggiungere il corrispondente blocco di testo come commento in testa a detto +file. Per via della formattazione, dei refusi, eccetera, questi blocchi di +testo sono difficili da identificare dagli strumenti usati per verificare il +rispetto delle licenze. + +Un'alternativa ai blocchi di testo è data dall'uso degli identificatori +*Software Package Data Exchange* (SPDX) in ogni file sorgente. Gli +identificatori di licenza SPDX sono analizzabili dalle macchine e sono precisi +simboli stenografici che identificano la licenza sotto la quale viene +licenziato il file che lo include. Gli identificatori di licenza SPDX sono +gestiti del gruppo di lavoro SPDX presso la Linux Foundation e sono stati +concordati fra i soci nell'industria, gli sviluppatori di strumenti, e i +rispettivi gruppi legali. Per maggiori informazioni, consultate +https://spdx.org/ + +Il kernel Linux richiede un preciso identificatore SPDX in tutti i file +sorgenti. Gli identificatori validi verranno spiegati nella sezione +`Identificatori di licenza`_ e sono stati copiati dalla lista ufficiale di +licenze SPDX assieme al rispettivo testo come mostrato in +https://spdx.org/licenses/. + +Sintassi degli identificatori di licenza +---------------------------------------- + +1. Posizionamento: + + L'identificativo di licenza SPDX dev'essere posizionato come prima riga + possibile di un file che possa contenere commenti. Per la maggior parte + dei file questa è la prima riga, fanno eccezione gli script che richiedono + come prima riga '#!PATH_TO_INTERPRETER'. Per questi script l'identificativo + SPDX finisce nella seconda riga. + +| + +2. Stile: + + L'identificativo di licenza SPDX viene aggiunto sotto forma di commento. + Lo stile del commento dipende dal tipo di file:: + + sorgenti C: // SPDX-License-Identifier: <SPDX License Expression> + intestazioni C: /* SPDX-License-Identifier: <SPDX License Expression> */ + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ + scripts: # SPDX-License-Identifier: <SPDX License Expression> + .rst: .. SPDX-License-Identifier: <SPDX License Expression> + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> + + Se un particolare programma non dovesse riuscire a gestire lo stile + principale per i commenti, allora dev'essere usato il meccanismo accettato + dal programma. Questo è il motivo per cui si ha "/\* \*/" nei file + d'intestazione C. Notammo che 'ld' falliva nell'analizzare i commenti del + C++ nei file .lds che venivano prodotti. Oggi questo è stato corretto, + ma ci sono in giro ancora vecchi programmi che non sono in grado di + gestire lo stile dei commenti del C++. + +| + +3. Sintassi: + + Una <espressione di licenza SPDX> può essere scritta usando l'identificatore + SPDX della licenza come indicato nella lista di licenze SPDX, oppure la + combinazione di due identificatori SPDX separati da "WITH" per i casi + eccezionali. Quando si usano piĂą licenze l'espressione viene formata da + sottoespressioni separate dalle parole chiave "AND", "OR" e racchiuse fra + parentesi tonde "(", ")". + + Gli identificativi di licenza per licenze come la [L]GPL che si avvalgono + dell'opzione 'o successive' si formano aggiungendo alla fine il simbolo "+" + per indicare l'opzione 'o successive'.:: + + // SPDX-License-Identifier: GPL-2.0+ + // SPDX-License-Identifier: LGPL-2.1+ + + WITH dovrebbe essere usato quando sono necessarie delle modifiche alla + licenza. Per esempio, la UAPI del kernel linux usa l'espressione:: + + // SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note + // SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note + + Altri esempi di usi di WITH all'interno del kernel sono:: + + // SPDX-License-Identifier: GPL-2.0 WITH mif-exception + // SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0 + + Le eccezioni si possono usare solo in combinazione con identificatori di + licenza. Gli identificatori di licenza riconosciuti sono elencati nei + corrispondenti file d'eccezione. Per maggiori dettagli consultate + `Eccezioni`_ nel capitolo `Identificatori di licenza`_ + + La parola chiave OR dovrebbe essere usata solo quando si usa una doppia + licenza e solo una dev'essere scelta. Per esempio, alcuni file dtsi sono + disponibili con doppia licenza:: + + // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause + + Esempi dal kernel di espressioni per file licenziati con doppia licenza + sono:: + + // SPDX-License-Identifier: GPL-2.0 OR MIT + // SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause + // SPDX-License-Identifier: GPL-2.0 OR Apache-2.0 + // SPDX-License-Identifier: GPL-2.0 OR MPL-1.1 + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT + // SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL + + La parola chiave AND dovrebbe essere usata quando i termini di piĂą licenze + si applicano ad un file. Per esempio, quando il codice viene preso da + un altro progetto il quale da i permessi per aggiungerlo nel kernel ma + richiede che i termini originali della licenza rimangano intatti:: + + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT + + Di seguito, un altro esempio dove entrambe i termini di licenza devono + essere rispettati:: + + // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+ + +Identificatori di licenza +------------------------- + +Le licenze attualmente in uso, così come le licenze aggiunte al kernel, possono +essere categorizzate in: + +1. _`Licenze raccomandate`: + + Ovunque possibile le licenze qui indicate dovrebbero essere usate perchĂ© + pienamente compatibili e molto usate. Queste licenze sono disponibile nei + sorgenti del kernel, nella cartella:: + + LICENSES/preferred/ + + I file in questa cartella contengono il testo completo della licenza e i + `Metatag`_. Il nome di questi file è lo stesso usato come identificatore + di licenza SPDX e che deve essere usato nei file sorgenti. + + Esempi:: + + LICENSES/preferred/GPL-2.0 + + Contiene il testo della seconda versione della licenza GPL e i metatag + necessari:: + + LICENSES/preferred/MIT + + Contiene il testo della licenza MIT e i metatag necessari. + + _`Metatag`: + + I seguenti metatag devono essere presenti in un file di licenza: + + - Valid-License-Identifier: + + Una o piĂą righe che dichiarano quali identificatori di licenza sono validi + all'interno del progetto per far riferimento alla licenza in questione. + Solitamente, questo è un unico identificatore valido, ma per esempio le + licenze che permettono l'opzione 'o successive' hanno due identificatori + validi. + + - SPDX-URL: + + L'URL della pagina SPDX che contiene informazioni aggiuntive riguardanti + la licenza. + + - Usage-Guidance: + + Testo in formato libero per dare suggerimenti agli utenti. Il testo deve + includere degli esempi su come usare gli identificatori di licenza SPDX + in un file sorgente in conformitĂ con le linea guida in + `Sintassi degli identificatori di licenza`_. + + - License-Text: + + Tutto il testo che compare dopo questa etichetta viene trattato + come se fosse parte del testo originale della licenza. + + Esempi:: + + Valid-License-Identifier: GPL-2.0 + Valid-License-Identifier: GPL-2.0+ + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html + Usage-Guide: + To use this license in source code, put one of the following SPDX + tag/value pairs into a comment according to the placement + guidelines in the licensing rules documentation. + For 'GNU General Public License (GPL) version 2 only' use: + SPDX-License-Identifier: GPL-2.0 + For 'GNU General Public License (GPL) version 2 or any later version' use: + SPDX-License-Identifier: GPL-2.0+ + License-Text: + Full license text + + :: + + SPDX-License-Identifier: MIT + SPDX-URL: https://spdx.org/licenses/MIT.html + Usage-Guide: + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: MIT + License-Text: + Full license text + +| + +2. Licenze deprecate: + + Questo tipo di licenze dovrebbero essere usate solo per codice giĂ esistente + o quando si prende codice da altri progetti. Le licenze sono disponibili + nei sorgenti del kernel nella cartella:: + + LICENSES/deprecated/ + + I file in questa cartella contengono il testo completo della licenza e i + `Metatag`_. Il nome di questi file è lo stesso usato come identificatore + di licenza SPDX e che deve essere usato nei file sorgenti. + + Esempi:: + + LICENSES/deprecated/ISC + + Contiene il testo della licenza Internet System Consortium e i suoi + metatag:: + + LICENSES/deprecated/GPL-1.0 + + Contiene il testo della versione 1 della licenza GPL e i suoi metatag. + + Metatag: + + I metatag necessari per le 'altre' ('other') licenze sono gli stessi + di usati per le `Licenze raccomandate`_. + + Esempio del formato del file:: + + Valid-License-Identifier: ISC + SPDX-URL: https://spdx.org/licenses/ISC.html + Usage-Guide: + Usage of this license in the kernel for new code is discouraged + and it should solely be used for importing code from an already + existing project. + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: ISC + License-Text: + Full license text + +| + +3. Solo per doppie licenze + + Queste licenze dovrebbero essere usate solamente per codice licenziato in + combinazione con un'altra licenza che solitamente è quella preferita. + Queste licenze sono disponibili nei sorgenti del kernel nella cartella:: + + LICENSES/dual + + I file in questa cartella contengono il testo completo della rispettiva + licenza e i suoi `Metatags`_. I nomi dei file sono identici agli + identificatori di licenza SPDX che dovrebbero essere usati nei file + sorgenti. + + Esempi:: + + LICENSES/dual/MPL-1.1 + + Questo file contiene il testo della versione 1.1 della licenza *Mozilla + Pulic License* e i metatag necessari:: + + LICENSES/dual/Apache-2.0 + + Questo file contiene il testo della versione 2.0 della licenza Apache e i + metatag necessari. + + Metatag: + + I requisiti per le 'altre' ('*other*') licenze sono identici a quelli per le + `Licenze raccomandate`_. + + Esempio del formato del file:: + + Valid-License-Identifier: MPL-1.1 + SPDX-URL: https://spdx.org/licenses/MPL-1.1.html + Usage-Guide: + Do NOT use. The MPL-1.1 is not GPL2 compatible. It may only be used for + dual-licensed files where the other license is GPL2 compatible. + If you end up using this it MUST be used together with a GPL2 compatible + license using "OR". + To use the Mozilla Public License version 1.1 put the following SPDX + tag/value pair into a comment according to the placement guidelines in + the licensing rules documentation: + SPDX-License-Identifier: MPL-1.1 + License-Text: + Full license text + +| + +4. _`Eccezioni`: + + Alcune licenze possono essere corrette con delle eccezioni che forniscono + diritti aggiuntivi. Queste eccezioni sono disponibili nei sorgenti del + kernel nella cartella:: + + LICENSES/exceptions/ + + I file in questa cartella contengono il testo completo dell'eccezione e i + `Metatag per le eccezioni`_. + + Esempi:: + + LICENSES/exceptions/Linux-syscall-note + + Contiene la descrizione dell'eccezione per le chiamate di sistema Linux + così come documentato nel file COPYING del kernel Linux; questo viene usato + per i file d'intestazione per la UAPI. Per esempio + /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/:: + + LICENSES/exceptions/GCC-exception-2.0 + + Contiene la 'eccezione di linking' che permette di collegare qualsiasi + binario, indipendentemente dalla sua licenza, con un compilato il cui file + sorgente è marchiato con questa eccezione. Questo è necessario per creare + eseguibili dai sorgenti che non sono compatibili con la GPL. + + _`Metatag per le eccezioni`: + + Un file contenente un'eccezione deve avere i seguenti metatag: + + - SPDX-Exception-Identifier: + + Un identificatore d'eccezione che possa essere usato in combinazione con + un identificatore di licenza SPDX. + + - SPDX-URL: + + L'URL della pagina SPDX che contiene informazioni aggiuntive riguardanti + l'eccezione. + + - SPDX-Licenses: + + Una lista di licenze SPDX separate da virgola, che possono essere usate + con l'eccezione. + + - Usage-Guidance: + + Testo in formato libero per dare suggerimenti agli utenti. Il testo deve + includere degli esempi su come usare gli identificatori di licenza SPDX + in un file sorgente in conformitĂ con le linea guida in + `Sintassi degli identificatori di licenza`_. + + - Exception-Text: + + Tutto il testo che compare dopo questa etichetta viene trattato + come se fosse parte del testo originale della licenza. + + Esempi:: + + SPDX-Exception-Identifier: Linux-syscall-note + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ + Usage-Guidance: + This exception is used together with one of the above SPDX-Licenses + to mark user-space API (uapi) header files so they can be included + into non GPL compliant user-space application code. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note + Exception-Text: + Full exception text + + :: + + SPDX-Exception-Identifier: GCC-exception-2.0 + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html + SPDX-Licenses: GPL-2.0, GPL-2.0+ + Usage-Guidance: + The "GCC Runtime Library exception 2.0" is used together with one + of the above SPDX-Licenses for code imported from the GCC runtime + library. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0 + Exception-Text: + Full exception text + +Per ogni identificatore di licenza SPDX e per le eccezioni dev'esserci un file +nella sotto-cartella LICENSES. Questo è necessario per permettere agli +strumenti di effettuare verifiche (come checkpatch.pl), per avere le licenze +disponibili per la lettura e per estrarre i diritti dai sorgenti, così come +raccomandato da diverse organizzazioni FOSS, per esempio l'`iniziativa FSFE +REUSE <https://reuse.software/>`_. + +_`MODULE_LICENSE` +----------------- + + I moduli del kernel necessitano di un'etichetta MODULE_LICENSE(). Questa + etichetta non sostituisce le informazioni sulla licenza del codice sorgente + (SPDX-License-Identifier) nĂ© fornisce informazioni che esprimono o + determinano l'esatta licenza sotto la quale viene rilasciato. + + Il solo scopo di questa etichetta è quello di fornire sufficienti + informazioni al caricatore di moduli del kernel, o agli strumenti in spazio + utente, per capire se il modulo è libero o proprietario. + + Le stringe di licenza valide per MODULE_LICENSE() sono: + + ============================= ============================================= + "GPL" Il modulo è licenziato con la GPL versione 2. + Questo non fa distinzione fra GPL'2.0-only o + GPL-2.0-or-later. L'esatta licenza può essere + determinata solo leggendo i corrispondenti + file sorgenti. + + "GPL v2" Stesso significato di "GPL". Esiste per + motivi storici. + + "GPL and additional rights" Questa è una variante che esiste per motivi + storici che indica che i sorgenti di un + modulo sono rilasciati sotto una variante + della licenza GPL v2 e quella MIT. Per favore + non utilizzatela per codice nuovo. + + "Dual MIT/GPL" Questo è il modo corretto per esprimere il + il fatto che il modulo è rilasciato con + doppia licenza a scelta fra: una variante + della GPL v2 o la licenza MIT. + + "Dual BSD/GPL" Questo modulo è rilasciato con doppia licenza + a scelta fra: una variante della GPL v2 o la + licenza BSD. La variante esatta della licenza + BSD può essere determinata solo attraverso i + corrispondenti file sorgenti. + + "Dual MPL/GPL" Questo modulo è rilasciato con doppia licenza + a scelta fra: una variante della GPL v2 o la + Mozilla Public License (MPL). La variante + esatta della licenza MPL può essere + determinata solo attraverso i corrispondenti + file sorgenti. + + "Proprietary" Questo modulo è rilasciato con licenza + proprietaria. Questa stringa è solo per i + moduli proprietari di terze parti e non può + essere usata per quelli che risiedono nei + sorgenti del kernel. I moduli etichettati in + questo modo stanno contaminando il kernel e + gli viene assegnato un flag 'P'; quando + vengono caricati, il caricatore di moduli del + kernel si rifiuterĂ di collegare questi + moduli ai simboli che sono stati esportati + con EXPORT_SYMBOL_GPL(). + + ============================= ============================================= diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index 24a133f0a51d..276db0e37f43 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -1,13 +1,946 @@ .. include:: ../disclaimer-ita.rst :Original: :ref:`Documentation/process/maintainer-pgp-guide.rst <pgpguide>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> .. _it_pgpguide: +========================================= +La guida a PGP per manutentori del kernel +========================================= + +:Author: Konstantin Ryabitsev <konstantin@linuxfoundation.org> + +Questo documento è destinato agli sviluppatori del kernel Linux, in particolar +modo ai manutentori. Contiene degli approfondimenti riguardo informazioni che +sono state affrontate in maniera piĂą generale nella sezione +"`Protecting Code Integrity`_" pubblicata dalla Linux Foundation. +Per approfondire alcuni argomenti trattati in questo documento è consigliato +leggere il documento sopraindicato + +.. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md + +Il ruolo di PGP nello sviluppo del kernel Linux +=============================================== + +PGP aiuta ad assicurare l'integritĂ del codice prodotto dalla comunitĂ +di sviluppo del kernel e, in secondo luogo, stabilisce canali di comunicazione +affidabili tra sviluppatori attraverso lo scambio di email firmate con PGP. + +Il codice sorgente del kernel Linux è disponibile principalmente in due +formati: + +- repositori distribuiti di sorgenti (git) +- rilasci periodici di istantanee (archivi tar) + +Sia i repositori git che gli archivi tar portano le firme PGP degli +sviluppatori che hanno creato i rilasci ufficiali del kernel. Queste firme +offrono una garanzia crittografica che le versioni scaricabili rese disponibili +via kernel.org, o altri portali, siano identiche a quelle che gli sviluppatori +hanno sul loro posto di lavoro. A tal scopo: + +- i repositori git forniscono firme PGP per ogni tag +- gli archivi tar hanno firme separate per ogni archivio + +.. _it_devs_not_infra: + +Fidatevi degli sviluppatori e non dell'infrastruttura +----------------------------------------------------- + +Fin dal 2011, quando i sistemi di kernel.org furono compromessi, il principio +generale del progetto Kernel Archives è stato quello di assumere che qualsiasi +parte dell'infrastruttura possa essere compromessa in ogni momento. Per questa +ragione, gli amministratori hanno intrapreso deliberatemene dei passi per +enfatizzare che la fiducia debba risiedere sempre negli sviluppatori e mai nel +codice che gestisce l'infrastruttura, indipendentemente da quali che siano le +pratiche di sicurezza messe in atto. + +Il principio sopra indicato è la ragione per la quale è necessaria questa +guida. Vogliamo essere sicuri che il riporre la fiducia negli sviluppatori +non sia fatto semplicemente per incolpare qualcun'altro per future falle di +sicurezza. L'obiettivo è quello di fornire una serie di linee guida che gli +sviluppatori possano seguire per creare un ambiente di lavoro sicuro e +salvaguardare le chiavi PGP usate nello stabilire l'integritĂ del kernel Linux +stesso. + +.. _it_pgp_tools: + +Strumenti PGP +============= + +Usare GnuPG v2 +-------------- + +La vostra distribuzione potrebbe avere giĂ installato GnuPG, dovete solo +verificare che stia utilizzando la versione 2.x e non la serie 1.4 -- +molte distribuzioni forniscono entrambe, di base il comando ''gpg'' +invoca GnuPG v.1. Per controllate usate:: + + $ gpg --version | head -n1 + +Se visualizzate ``gpg (GnuPG) 1.4.x``, allora state usando GnuPG v.1. +Provate il comando ``gpg2`` (se non lo avete, potreste aver bisogno +di installare il pacchetto gnupg2):: + + $ gpg2 --version | head -n1 + +Se visualizzate ``gpg (GnuPG) 2.x.x``, allora siete pronti a partire. +Questa guida assume che abbiate la versione 2.2.(o successiva) di GnuPG. +Se state usando la versione 2.0, alcuni dei comandi indicati qui non +funzioneranno, in questo caso considerate un aggiornamento all'ultima versione, +la 2.2. Versioni di gnupg-2.1.11 e successive dovrebbero essere compatibili +per gli obiettivi di questa guida. + +Se avete entrambi i comandi: ``gpg`` e ``gpg2``, assicuratevi di utilizzare +sempre la versione V2, e non quella vecchia. Per evitare errori potreste creare +un alias:: + + $ alias gpg=gpg2 + +Potete mettere questa opzione nel vostro ``.bashrc`` in modo da essere sicuri. + +Configurare le opzioni di gpg-agent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +L'agente GnuPG è uno strumento di aiuto che partirĂ automaticamente ogni volta +che userete il comando ``gpg`` e funzionerĂ in background con l'obiettivo di +individuare la passphrase. Ci sono due opzioni che dovreste conoscere +per personalizzare la scadenza della passphrase nella cache: + +- ``default-cache-ttl`` (secondi): Se usate ancora la stessa chiave prima + che il time-to-live termini, il conto alla rovescia si resetterĂ per un + altro periodo. Di base è di 600 (10 minuti). + +- ``max-cache-ttl`` (secondi): indipendentemente da quanto sia recente l'ultimo + uso della chiave da quando avete inserito la passphrase, se il massimo + time-to-live è scaduto, dovrete reinserire nuovamente la passphrase. + Di base è di 30 minuti. + +Se ritenete entrambe questi valori di base troppo corti (o troppo lunghi), +potete creare il vostro file ``~/.gnupg/gpg-agent.conf`` ed impostare i vostri +valori:: + + # set to 30 minutes for regular ttl, and 2 hours for max ttl + default-cache-ttl 1800 + max-cache-ttl 7200 + +.. note:: + + Non è piĂą necessario far partire l'agente gpg manualmente all'inizio della + vostra sessione. Dovreste controllare i file rc per rimuovere tutto ciò che + riguarda vecchie le versioni di GnuPG, poichĂ© potrebbero non svolgere piĂą + bene il loro compito. + +Impostare un *refresh* con cronjob +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Potreste aver bisogno di rinfrescare regolarmente il vostro portachiavi in +modo aggiornare le chiavi pubbliche di altre persone, lavoro che è svolto +al meglio con un cronjob giornaliero:: + + @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1 + +Controllate il percorso assoluto del vostro comando ``gpg`` o ``gpg2`` e usate +il comando ``gpg2`` se per voi ``gpg`` corrisponde alla versione GnuPG v.1. + +.. _it_master_key: + +Proteggere la vostra chiave PGP primaria ======================================== -Guida a PGP per i manutentori del kernel -======================================== + +Questa guida parte dal presupposto che abbiate giĂ una chiave PGP che usate +per lo sviluppo del kernel Linux. Se non ne avete ancora una, date uno sguardo +al documento "`Protecting Code Integrity`_" che abbiamo menzionato prima. + +Dovreste inoltre creare una nuova chiave se quella attuale è inferiore a 2048 +bit (RSA). + +Chiave principale o sottochiavi +------------------------------- + +Le sottochiavi sono chiavi PGP totalmente indipendenti, e sono collegate alla +chiave principale attraverso firme certificate. Ă quindi importante +comprendere i seguenti punti: + +1. Non ci sono differenze tecniche tra la chiave principale e la sottochiave. +2. In fesa di creazione, assegniamo limitazioni funzionali ad ogni chiave + assegnando capacitĂ specifiche. +3. Una chiave PGP può avere 4 capacitĂ : + + - **[S]** può essere usata per firmare + - **[E]** può essere usata per criptare + - **[A]** può essere usata per autenticare + - **[C]** può essere usata per certificare altre chiavi + +4. Una singola chiave può avere piĂą capacitĂ +5. Una sottochiave è completamente indipendente dalla chiave principale. + Un messaggio criptato con la sottochiave non può essere decrittato con + quella principale. Se perdete la vostra sottochiave privata, non può + essere rigenerata in nessun modo da quella principale. + +La chiave con capacitĂ **[C]** (certify) è identificata come la chiave +principale perchĂ© è l'unica che può essere usata per indicare la relazione +con altre chiavi. Solo la chiave **[C]** può essere usata per: + +- Aggiungere o revocare altre chiavi (sottochiavi) che hanno capacitĂ S/E/A +- Aggiungere, modificare o eliminare le identitĂ (unids) associate alla chiave +- Aggiungere o modificare la data di termine di sĂ© stessa o di ogni sottochiave +- Firmare le chiavi di altre persone a scopo di creare una rete di fiducia + +Di base, alla creazione di nuove chiavi, GnuPG genera quanto segue: + +- Una chiave madre che porta sia la capacitĂ di certificazione che quella + di firma (**[SC]**) +- Una sottochiave separata con capacitĂ di criptaggio (**[E]**) + +Se avete usato i parametri di base per generare la vostra chiave, quello +sarĂ il risultato. Potete verificarlo utilizzando ``gpg --list-secret-keys``, +per esempio:: + + sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] + +Qualsiasi chiave che abbia la capacitĂ **[C]** è la vostra chiave madre, +indipendentemente da quali altre capacitĂ potreste averle assegnato. + +La lunga riga sotto la voce ``sec`` è la vostra impronta digitale -- +negli esempi che seguono, quando vedere ``[fpr]`` ci si riferisce a questa +stringa di 40 caratteri. + +Assicuratevi che la vostra passphrase sia forte +----------------------------------------------- + +GnuPG utilizza le passphrases per criptare la vostra chiave privata prima +di salvarla sul disco. In questo modo, anche se il contenuto della vostra +cartella ``.gnupg`` venisse letto o trafugato nella sia interezza, gli +attaccanti non potrebbero comunque utilizzare le vostre chiavi private senza +aver prima ottenuto la passphrase per decriptarle. + +Ă assolutamente essenziale che le vostre chiavi private siano protette da +una passphrase forte. Per impostarla o cambiarla, usate:: + + $ gpg --change-passphrase [fpr] + +Create una sottochiave di firma separata +---------------------------------------- + +Il nostro obiettivo è di proteggere la chiave primaria spostandola su un +dispositivo sconnesso dalla rete, dunque se avete solo una chiave combinata +**[SC]** allora dovreste creare una sottochiave di firma separata:: + + $ gpg --quick-add-key [fpr] ed25519 sign + +Ricordate di informare il keyserver del vostro cambiamento, cosicchĂ© altri +possano ricevere la vostra nuova sottochiave:: + + $ gpg --send-key [fpr] + +.. note:: Supporto ECC in GnuPG + GnuPG 2.1 e successivi supportano pienamente *Elliptic Curve Cryptography*, + con la possibilitĂ di combinare sottochiavi ECC con le tradizionali chiavi + primarie RSA. Il principale vantaggio della crittografia ECC è che è molto + piĂą veloce da calcolare e crea firme piĂą piccole se confrontate byte per + byte con le chiavi RSA a piĂą di 2048 bit. A meno che non pensiate di + utilizzare un dispositivo smartcard che non supporta le operazioni ECC, vi + raccomandiamo ti creare sottochiavi di firma ECC per il vostro lavoro col + kernel. + + Se per qualche ragione preferite rimanere con sottochiavi RSA, nel comando + precedente, sostituite "ed25519" con "rsa2048". + +Copia di riserva della chiave primaria per gestire il recupero da disastro +-------------------------------------------------------------------------- + +Maggiori sono le firme di altri sviluppatori che vengono applicate alla vostra, +maggiori saranno i motivi per avere una copia di riserva che non sia digitale, +al fine di effettuare un recupero da disastro. + +Il modo migliore per creare una copia fisica della vostra chiave privata è +l'uso del programma ``paperkey``. Consultate ``man paperkey`` per maggiori +dettagli sul formato dell'output ed i suoi punti di forza rispetto ad altre +soluzioni. Paperkey dovrebbe essere giĂ pacchettizzato per la maggior parte +delle distribuzioni. + +Eseguite il seguente comando per creare una copia fisica di riserva della +vostra chiave privata:: + + $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt + +Stampate il file (o fate un pipe direttamente verso lpr), poi prendete +una penna e scrivete la passphare sul margine del foglio. **Questo è +caldamente consigliato** perchĂ© la copia cartacea è comunque criptata con +la passphrase, e se mai doveste cambiarla non vi ricorderete qual'era al +momento della creazione di quella copia -- *garantito*. + +Mettete la copia cartacea e la passphrase scritta a mano in una busta e +mettetela in un posto sicuro e ben protetto, preferibilmente fuori casa, +magari in una cassetta di sicurezza in banca. + +.. note:: + + Probabilmente la vostra stampante non è piĂą quello stupido dispositivo + connesso alla porta parallela, ma dato che il suo output è comunque + criptato con la passphrase, eseguire la stampa in un sistema "cloud" + moderno dovrebbe essere comunque relativamente sicuro. Un'opzione potrebbe + essere quella di cambiare la passphrase della vostra chiave primaria + subito dopo aver finito con paperkey. + +Copia di riserva di tutta la cartella GnuPG +------------------------------------------- .. warning:: - TODO ancora da tradurre + **!!!Non saltate questo passo!!!** + +Quando avete bisogno di recuperare le vostre chiavi PGP è importante avere +una copia di riserva pronta all'uso. Questo sta su un diverso piano di +prontezza rispetto al recupero da disastro che abbiamo risolto con +``paperkey``. Vi affiderete a queste copie esterne quando dovreste usare la +vostra chiave Certify -- ovvero quando fate modifiche alle vostre chiavi o +firmate le chiavi di altre persone ad una conferenza o ad un gruppo d'incontro. + +Incominciate con una piccola chiavetta di memoria USB (preferibilmente due) +che userete per le copie di riserva. Dovrete criptarle usando LUKS -- fate +riferimento alla documentazione della vostra distribuzione per capire come +fare. + +Per la passphrase di criptazione, potete usare la stessa della vostra chiave +primaria. + +Una volta che il processo di criptazione è finito, reinserite il disco USB ed +assicurativi che venga montato correttamente. Copiate interamente la cartella +``.gnugp`` nel disco criptato:: + + $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup + +Ora dovreste verificare che tutto continui a funzionare:: + + $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] + +Se non vedete errori, allora dovreste avere fatto tutto con successo. +Smontate il disco USB, etichettatelo per bene di modo da evitare di +distruggerne il contenuto non appena vi serve una chiavetta USB a caso, ed +infine mettetelo in un posto sicuro -- ma non troppo lontano, perchĂ© vi servirĂ +di tanto in tanto per modificare le identitĂ , aggiungere o revocare +sottochiavi, o firmare le chiavi di altre persone. + +Togliete la chiave primaria dalla vostra home +--------------------------------------------- + +I file che si trovano nella vostra cartella home non sono poi così ben protetti +come potreste pensare. Potrebbero essere letti o trafugati in diversi modi: + +- accidentalmente quando fate una rapida copia della cartella home per + configurare una nuova postazione +- da un amministratore di sistema negligente o malintenzionato +- attraverso copie di riserva insicure +- attraverso malware installato in alcune applicazioni (browser, lettori PDF, + eccetera) +- attraverso coercizione quando attraversate confini internazionali + +Proteggere la vostra chiave con una buona passphare aiuta notevolmente a +ridurre i rischi elencati qui sopra, ma le passphrase possono essere scoperte +attraverso i keylogger, il shoulder-surfing, o altri modi. Per questi motivi, +nella configurazione si raccomanda di rimuove la chiave primaria dalla vostra +cartella home e la si archivia su un dispositivo disconnesso. + +.. warning:: + + Per favore, fate riferimento alla sezione precedente e assicuratevi + di aver fatto una copia di riserva totale della cartella GnuPG. Quello + che stiamo per fare renderĂ la vostra chiave inutile se non avete delle + copie di riserva utilizzabili! + +Per prima cosa, identificate il keygrip della vostra chiave primaria:: + + $ gpg --with-keygrip --list-key [fpr] + +L'output assomiglierĂ a questo:: + + pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + Keygrip = 1111000000000000000000000000000000000000 + uid [ultimate] Alice Dev <adev@kernel.org> + sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] + Keygrip = 2222000000000000000000000000000000000000 + sub ed25519 2018-01-24 [S] + Keygrip = 3333000000000000000000000000000000000000 + +Trovate la voce keygrid che si trova sotto alla riga ``pub`` (appena sotto +all'impronta digitale della chiave primaria). Questo corrisponderĂ direttamente +ad un file nella cartella ``~/.gnupg``:: + + $ cd ~/.gnupg/private-keys-v1.d + $ ls + 1111000000000000000000000000000000000000.key + 2222000000000000000000000000000000000000.key + 3333000000000000000000000000000000000000.key + +Quello che dovrete fare è rimuovere il file .key che corrisponde al keygrip +della chiave primaria:: + + $ cd ~/.gnupg/private-keys-v1.d + $ rm 1111000000000000000000000000000000000000.key + +Ora, se eseguite il comando ``--list-secret-keys``, vedrete che la chiave +primaria non compare piĂą (il simbolo ``#`` indica che non è disponibile):: + + $ gpg --list-secret-keys + sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] + ssb ed25519 2018-01-24 [S] + +Dovreste rimuovere anche i file ``secring.gpg`` che si trovano nella cartella +``~/.gnupg``, in quanto rimasugli delle versioni precedenti di GnuPG. + +Se non avete la cartella "private-keys-v1.d" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Se non avete la cartella ``~/.gnupg/private-keys-v1.d``, allora le vostre +chiavi segrete sono ancora salvate nel vecchio file ``secring.gpg`` usato +da GnuPG v1. Effettuare una qualsiasi modifica alla vostra chiave, come +cambiare la passphare o aggiungere una sottochiave, dovrebbe convertire +automaticamente il vecchio formato ``secring.gpg``nel nuovo +``private-keys-v1.d``. + +Una volta che l'avete fatto, assicuratevi di rimuovere il file ``secring.gpg``, +che continua a contenere la vostra chiave privata. + +.. _it_smartcards: + +Spostare le sottochiavi in un apposito dispositivo criptato +=========================================================== + +Nonostante la chiave primaria sia ora al riparo da occhi e mani indiscrete, +le sottochiavi si trovano ancora nella vostra cartella home. Chiunque riesca +a mettere le sue mani su quelle chiavi riuscirĂ a decriptare le vostre +comunicazioni o a falsificare le vostre firme (se conoscono la passphrase). +Inoltre, ogni volta che viene fatta un'operazione con GnuPG, le chiavi vengono +caricate nella memoria di sistema e potrebbero essere rubate con l'uso di +malware sofisticati (pensate a Meltdown e a Spectre). + +Il miglior modo per proteggere le proprie chiave è di spostarle su un +dispositivo specializzato in grado di effettuare operazioni smartcard. + +I benefici di una smartcard +--------------------------- + +Una smartcard contiene un chip crittografico che è capace di immagazzinare +le chiavi private ed effettuare operazioni crittografiche direttamente sulla +carta stessa. Dato che la chiave non lascia mai la smartcard, il sistema +operativo usato sul computer non sarĂ in grado di accedere alle chiavi. +Questo è molto diverso dai dischi USB criptati che abbiamo usato allo scopo di +avere una copia di riserva sicura -- quando il dispositivo USB è connesso e +montato, il sistema operativo potrĂ accedere al contenuto delle chiavi private. + +L'uso di un disco USB criptato non può sostituire le funzioni di un dispositivo +capace di operazioni di tipo smartcard. + +Dispositivi smartcard disponibili +--------------------------------- + +A meno che tutti i vostri computer dispongano di lettori smartcard, il modo +piĂą semplice è equipaggiarsi di un dispositivo USB specializzato che +implementi le funzionalitĂ delle smartcard. Sul mercato ci sono diverse +soluzioni disponibili: + +- `Nitrokey Start`_: è Open hardware e Free Software, è basata sul progetto + `GnuK`_ della FSIJ. Ha il supporto per chiavi ECC, ma meno funzionalitĂ di + sicurezza (come la resistenza alla manomissione o alcuni attacchi ad un + canale laterale). +- `Nitrokey Pro`_: è simile alla Nitrokey Start, ma è piĂą resistente alla + manomissione e offre piĂą funzionalitĂ di sicurezza, ma l'ECC. +- `Yubikey 4`_: l'hardware e il software sono proprietari, ma è piĂą economica + della Nitrokey Pro ed è venduta anche con porta USB-C il che è utile con i + computer portatili piĂą recenti. In aggiunta, offre altre funzionalitĂ di + sicurezza come FIDO, U2F, ma non l'ECC + +`Su LWN c'è una buona recensione`_ dei modelli elencati qui sopra e altri. +Se volete usare chiavi ECC, la vostra migliore scelta sul mercato è la +Nitrokey Start. + +.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 +.. _`Nitrokey Pro`: https://shop.nitrokey.com/shop/product/nitrokey-pro-3 +.. _`Yubikey 4`: https://www.yubico.com/product/yubikey-4-series/ +.. _Gnuk: http://www.fsij.org/doc-gnuk/ +.. _`Su LWN c'è una buona recensione`: https://lwn.net/Articles/736231/ + +Configurare il vostro dispositivo smartcard +------------------------------------------- + +Il vostro dispositivo smartcard dovrebbe iniziare a funzionare non appena +lo collegate ad un qualsiasi computer Linux moderno. Potete verificarlo +eseguendo:: + + $ gpg --card-status + +Se vedete tutti i dettagli della smartcard, allora ci siamo. Sfortunatamente, +affrontare tutti i possibili motivi per cui le cose potrebbero non funzionare +non è lo scopo di questa guida. Se avete problemi nel far funzionare la carta +con GnuPG, cercate aiuto attraverso i soliti canali di supporto. + +Per configurare la vostra smartcard, dato che non c'è una via facile dalla +riga di comando, dovrete usate il menu di GnuPG:: + + $ gpg --card-edit + [...omitted...] + gpg/card> admin + Admin commands are allowed + gpg/card> passwd + +Dovreste impostare il PIN dell'utente (1), quello dell'amministratore (3) e il +codice di reset (4). Assicuratevi di annotare e salvare questi codici in un +posto sicuro -- specialmente il PIN dell'amministratore e il codice di reset +(che vi permetterĂ di azzerare completamente la smartcard). Il PIN +dell'amministratore viene usato così raramente che è inevitabile dimenticarselo +se non lo si annota. + +Tornando al nostro menu, potete impostare anche altri valori (come il nome, +il sesso, informazioni d'accesso, eccetera), ma non sono necessari e aggiunge +altre informazioni sulla carta che potrebbero trapelare in caso di smarrimento. + +.. note:: + + A dispetto del nome "PIN", nĂ© il PIN utente nĂ© quello dell'amministratore + devono essere esclusivamente numerici. + +Spostare le sottochiavi sulla smartcard +--------------------------------------- + +Uscite dal menu (usando "q") e salverete tutte le modifiche. Poi, spostiamo +tutte le sottochiavi sulla smartcard. Per la maggior parte delle operazioni +vi serviranno sia la passphrase della chiave PGP che il PIN +dell'amministratore:: + + $ gpg --edit-key [fpr] + + Secret subkeys are available. + + pub rsa2048/AAAABBBBCCCCDDDD + created: 2018-01-23 expires: 2020-01-23 usage: SC + trust: ultimate validity: ultimate + ssb rsa2048/1111222233334444 + created: 2018-01-23 expires: never usage: E + ssb ed25519/5555666677778888 + created: 2017-12-07 expires: never usage: S + [ultimate] (1). Alice Dev <adev@kernel.org> + + gpg> + +Usando ``--edit-key`` si tornerĂ alla modalitĂ menu e noterete che +la lista delle chiavi è leggermente diversa. Da questo momento in poi, +tutti i comandi saranno eseguiti nella modalitĂ menu, come indicato +da ``gpg>``. + +Per prima cosa, selezioniamo la chiave che verrĂ messa sulla carta -- +potete farlo digitando ``key 1`` (è la prima della lista, la sottochiave +**[E]**):: + + gpg> key 1 + +Nel'output dovreste vedere ``ssb*`` associato alla chiave **[E]**. Il simbolo +``*`` indica che la chiave è stata "selezionata". Funziona come un +interruttore, ovvero se scrivete nuovamente ``key 1``, il simbolo ``*`` sparirĂ +e la chiave non sarĂ piĂą selezionata. + +Ora, spostiamo la chiave sulla smartcard:: + + gpg> keytocard + Please select where to store the key: + (2) Encryption key + Your selection? 2 + +Dato che è la nostra chiave **[E]**, ha senso metterla nella sezione criptata. +Quando confermerete la selezione, vi verrĂ chiesta la passphrase della vostra +chiave PGP, e poi il PIN dell'amministratore. Se il comando ritorna senza +errori, allora la vostra chiave è stata spostata con successo. + +**Importante**: digitate nuovamente ``key 1`` per deselezionare la prima chiave +e selezionate la seconda chiave **[S]** con ``key 2``:: + + gpg> key 1 + gpg> key 2 + gpg> keytocard + Please select where to store the key: + (1) Signature key + (3) Authentication key + Your selection? 1 + +Potete usare la chiave **[S]** sia per firmare che per autenticare, ma vogliamo +che sia nella sezione di firma, quindi scegliete (1). Ancora una volta, se il +comando ritorna senza errori, allora l'operazione è avvenuta con successo:: + + gpg> q + Save changes? (y/N) y + +Salvando le modifiche cancellerete dalla vostra cartella home tutte le chiavi +che avete spostato sulla carta (ma questo non è un problema, perchĂ© abbiamo +fatto delle copie di sicurezza nel caso in cui dovessimo configurare una +nuova smartcard). + +Verificare che le chiavi siano state spostate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ora, se doveste usare l'opzione ``--list-secret-keys``, vedrete una +sottile differenza nell'output:: + + $ gpg --list-secret-keys + sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] + ssb> ed25519 2018-01-24 [S] + +Il simbolo ``>`` in ``ssb>`` indica che la sottochiave è disponibile solo +nella smartcard. Se tornate nella vostra cartella delle chiavi segrete e +guardate al suo contenuto, noterete che i file ``.key`` sono stati sostituiti +con degli stub:: + + $ cd ~/.gnupg/private-keys-v1.d + $ strings *.key | grep 'private-key' + +Per indicare che i file sono solo degli stub e che in realtĂ il contenuto è +sulla smartcard, l'output dovrebbe mostrarvi ``shadowed-private-key``. + +Verificare che la smartcard funzioni +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Per verificare che la smartcard funzioni come dovuto, potete creare +una firma:: + + $ echo "Hello world" | gpg --clearsign > /tmp/test.asc + $ gpg --verify /tmp/test.asc + +Col primo comando dovrebbe chiedervi il PIN della smartcard, e poi dovrebbe +mostrare "Good signature" dopo l'esecuzione di ``gpg --verify``. + +Complimenti, siete riusciti a rendere estremamente difficile il furto della +vostra identitĂ digitale di sviluppatore. + +Altre operazioni possibili con GnuPG +------------------------------------ + +Segue un breve accenno ad alcune delle operazioni piĂą comuni che dovrete +fare con le vostre chiavi PGP. + +Montare il disco con la chiave primaria +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vi servirĂ la vostra chiave principale per tutte le operazioni che seguiranno, +per cui per prima cosa dovrete accedere ai vostri backup e dire a GnuPG di +usarli:: + + $ export GNUPGHOME=/media/disk/foo/gnupg-backup + $ gpg --list-secret-keys + +Dovete assicurarvi di vedere ``sec`` e non ``sec#`` nell'output del programma +(il simbolo ``#`` significa che la chiave non è disponibile e che state ancora +utilizzando la vostra solita cartella di lavoro). + +Estendere la data di scadenza di una chiave +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La chiave principale ha una data di scadenza di 2 anni dal momento della sua +creazione. Questo per motivi di sicurezza e per rendere obsolete le chiavi +che, eventualmente, dovessero sparire dai keyserver. + +Per estendere di un anno, dalla data odierna, la scadenza di una vostra chiave, +eseguite:: + + $ gpg --quick-set-expire [fpr] 1y + +Se per voi è piĂą facile da memorizzare, potete anche utilizzare una data +specifica (per esempio, il vostro compleanno o capodanno):: + + $ gpg --quick-set-expire [fpr] 2020-07-01 + +Ricordatevi di inviare l'aggiornamento ai keyserver:: + + $ gpg --send-key [fpr] + +Aggiornare la vostra cartella di lavoro dopo ogni modifica +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dopo aver fatto delle modifiche alle vostre chiavi usando uno spazio a parte, +dovreste importarle nella vostra cartella di lavoro abituale:: + + $ gpg --export | gpg --homedir ~/.gnupg --import + $ unset GNUPGHOME + + +Usare PGP con Git +================= + +Una delle caratteristiche fondanti di Git è la sua natura decentralizzata -- +una volta che il repositorio è stato clonato sul vostro sistema, avete la +storia completa del progetto, inclusi i suoi tag, i commit ed i rami. Tuttavia, +con i centinaia di repositori clonati che ci sono in giro, come si fa a +verificare che la loro copia di linux.git non è stata manomessa da qualcuno? + +Oppure, cosa succede se viene scoperta una backdoor nel codice e la riga +"Autore" dice che sei stato tu, mentre tu sei abbastanza sicuro di +`non averci niente a che fare`_? + +Per risolvere entrambi i problemi, Git ha introdotto l'integrazione con PGP. +I tag firmati dimostrano che il repositorio è integro assicurando che il suo +contenuto è lo stesso che si trova sulle macchine degli sviluppatori che hanno +creato il tag; mentre i commit firmati rendono praticamente impossibile +ad un malintenzionato di impersonarvi senza avere accesso alle vostre chiavi +PGP. + +.. _`non averci niente a che fare`: https://github.com/jayphelps/git-blame-someone-else + +Configurare git per usare la vostra chiave PGP +---------------------------------------------- + +Se avete solo una chiave segreta nel vostro portachiavi, allora non avete nulla +da fare in piĂą dato che sarĂ la vostra chiave di base. Tuttavia, se doveste +avere piĂą chiavi segrete, potete dire a git quale dovrebbe usare (``[fpg]`` +è la vostra impronta digitale):: + + $ git config --global user.signingKey [fpr] + +**IMPORTANTE**: se avete una comando dedicato per ``gpg2``, allora dovreste +dire a git di usare sempre quello piuttosto che il vecchio comando ``gpg``:: + + $ git config --global gpg.program gpg2 + +Come firmare i tag +------------------ + +Per creare un tag firmato, passate l'opzione ``-s`` al comando tag:: + + $ git tag -s [tagname] + +La nostra raccomandazione è quella di firmare sempre i tag git, perchĂ© +questo permette agli altri sviluppatori di verificare che il repositorio +git dal quale stanno prendendo il codice non è stato alterato intenzionalmente. + +Come verificare i tag firmati +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Per verificare un tag firmato, potete usare il comando ``verify-tag``:: + + $ git verify-tag [tagname] + +Se state prendendo un tag da un fork del repositorio del progetto, git +dovrebbe verificare automaticamente la firma di quello che state prendendo +e vi mostrerĂ il risultato durante l'operazione di merge:: + + $ git pull [url] tags/sometag + +Il merge conterrĂ qualcosa di simile:: + + Merge tag 'sometag' of [url] + + [Tag message] + + # gpg: Signature made [...] + # gpg: Good signature from [...] + +Se state verificando il tag di qualcun altro, allora dovrete importare +la loro chiave PGP. Fate riferimento alla sezione ":ref:`it_verify_identities`" +che troverete piĂą avanti. + +Configurare git per firmare sempre i tag con annotazione +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Se state creando un tag con annotazione è molto probabile che vogliate +firmarlo. Per imporre a git di firmare sempre un tag con annotazione, +dovete impostare la seguente opzione globale:: + + $ git config --global tag.forceSignAnnotated true + +Come usare commit firmati +------------------------- + +Creare dei commit firmati è facile, ma è molto piĂą difficile utilizzarli +nello sviluppo del kernel linux per via del fatto che ci si affida alle +liste di discussione e questo modo di procedere non mantiene le firme PGP +nei commit. In aggiunta, quando si usa *rebase* nel proprio repositorio +locale per allinearsi al kernel anche le proprie firme PGP verranno scartate. +Per questo motivo, la maggior parte degli sviluppatori del kernel non si +preoccupano troppo di firmare i propri commit ed ignoreranno quelli firmati +che si trovano in altri repositori usati per il proprio lavoro. + +Tuttavia, se avete il vostro repositorio di lavoro disponibile al pubblico +su un qualche servizio di hosting git (kernel.org, infradead.org, ozlabs.org, +o altri), allora la raccomandazione è di firmare tutti i vostri commit +anche se gli sviluppatori non ne beneficeranno direttamente. + +Vi raccomandiamo di farlo per i seguenti motivi: + +1. Se dovesse mai esserci la necessitĂ di fare delle analisi forensi o + tracciare la provenienza di un codice, anche sorgenti mantenuti + esternamente che hanno firme PGP sui commit avranno un certo valore a + questo scopo. +2. Se dovesse mai capitarvi di clonare il vostro repositorio locale (per + esempio dopo un danneggiamento del disco), la firma vi permetterĂ di + verificare l'integritĂ del repositorio prima di riprendere il lavoro. +3. Se qualcuno volesse usare *cherry-pick* sui vostri commit, allora la firma + permetterĂ di verificare l'integritĂ dei commit prima di applicarli. + +Creare commit firmati +~~~~~~~~~~~~~~~~~~~~~ + +Per creare un commit firmato, dovete solamente aggiungere l'opzione ``-S`` +al comando ``git commit`` (si usa la lettera maiuscola per evitare +conflitti con un'altra opzione):: + + $ git commit -S + +Configurare git per firmare sempre i commit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Potete dire a git di firmare sempre i commit:: + + git config --global commit.gpgSign true + +.. note:: + + Assicuratevi di aver configurato ``gpg-agent`` prima di abilitare + questa opzione. + +.. _it_verify_identities: + +Come verificare l'identitĂ degli sviluppatori del kernel +======================================================== + +Firmare i tag e i commit è facile, ma come si fa a verificare che la chiave +usata per firmare qualcosa appartenga davvero allo sviluppatore e non ad un +impostore? + +Configurare l'auto-key-retrieval usando WKD e DANE +-------------------------------------------------- + +Se non siete ancora in possesso di una vasta collezione di chiavi pubbliche +di altri sviluppatori, allora potreste iniziare il vostro portachiavi +affidandovi ai servizi di auto-scoperta e auto-recupero. GnuPG può affidarsi +ad altre tecnologie di delega della fiducia, come DNSSEC e TLS, per sostenervi +nel caso in cui iniziare una propria rete di fiducia da zero sia troppo +scoraggiante. + +Aggiungete il seguente testo al vostro file ``~/.gnupg/gpg.conf``:: + + auto-key-locate wkd,dane,local + auto-key-retrieve + +La *DNS-Based Authentication of Named Entities* ("DANE") è un metodo +per la pubblicazione di chiavi pubbliche su DNS e per renderle sicure usando +zone firmate con DNSSEC. Il *Web Key Directory* ("WKD") è un metodo +alternativo che usa https a scopo di ricerca. Quando si usano DANE o WKD +per la ricerca di chiavi pubbliche, GnuPG validerĂ i certificati DNSSEC o TLS +prima di aggiungere al vostro portachiavi locale le eventuali chiavi trovate. + +Kernel.org pubblica la WKD per tutti gli sviluppatori che hanno un account +kernel.org. Una volta che avete applicato le modifiche al file ``gpg.conf``, +potrete auto-recuperare le chiavi di Linus Torvalds e Greg Kroah-Hartman +(se non le avete giĂ ):: + + $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org + +Se avete un account kernel.org, al fine di rendere piĂą utile l'uso di WKD +da parte di altri sviluppatori del kernel, dovreste `aggiungere alla vostra +chiave lo UID di kernel.org`_. + +.. _`aggiungere alla vostra chiave lo UID di kernel.org`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key + +Web of Trust (WOT) o Trust on First Use (TOFU) +---------------------------------------------- + +PGP incorpora un meccanismo di delega della fiducia conosciuto come +"Web of Trust". Di base, questo è un tentativo di sostituire la necessitĂ +di un'autoritĂ certificativa centralizzata tipica del mondo HTTPS/TLS. +Invece di avere svariati produttori software che decidono chi dovrebbero +essere le entitĂ di certificazione di cui dovreste fidarvi, PGP lascia +la responsabilitĂ ad ogni singolo utente. + +Sfortunatamente, solo poche persone capiscono come funziona la rete di fiducia. +Nonostante sia un importante aspetto della specifica OpenPGP, recentemente +le versioni di GnuPG (2.2 e successive) hanno implementato un meccanisco +alternativo chiamato "Trust on First Use" (TOFU). Potete pensare a TOFU come +"ad un approccio all fidicia simile ad SSH". In SSH, la prima volta che vi +connettete ad un sistema remoto, l'impronta digitale della chiave viene +registrata e ricordata. Se la chiave dovesse cambiare in futuro, il programma +SSH vi avviserĂ e si rifiuterĂ di connettersi, obbligandovi a prendere una +decisione circa la fiducia che riponete nella nuova chiave. In modo simile, +la prima volta che importate la chiave PGP di qualcuno, si assume sia valida. +Se ad un certo punto GnuPG trova un'altra chiave con la stessa identitĂ , +entrambe, la vecchia e la nuova, verranno segnate come invalide e dovrete +verificare manualmente quale tenere. + +Vi raccomandiamo di usare il meccanisco TOFU+PGP (che è la nuova configurazione +di base di GnuPG v2). Per farlo, aggiungete (o modificate) l'impostazione +``trust-model`` in ``~/.gnupg/gpg.conf``:: + + trust-model tofu+pgp + +Come usare i keyserver in sicurezza +----------------------------------- +Se ottenete l'errore "No public key" quando cercate di validate il tag di +qualcuno, allora dovreste cercare quella chiave usando un keyserver. Ă +importante tenere bene a mente che non c'è alcuna garanzia che la chiave +che avete recuperato da un keyserver PGP appartenga davvero alla persona +reale -- è progettato così. Dovreste usare il Web of Trust per assicurarvi +che la chiave sia valida. + +Come mantenere il Web of Trust va oltre gli scopi di questo documento, +semplicemente perchĂ© farlo come si deve richiede sia sforzi che perseveranza +che tendono ad andare oltre al livello di interesse della maggior parte degli +esseri umani. Qui di seguito alcuni rapidi suggerimenti per aiutarvi a ridurre +il rischio di importare chiavi maligne. + +Primo, diciamo che avete provato ad eseguire ``git verify-tag`` ma restituisce +un errore dicendo che la chiave non è stata trovata:: + + $ git verify-tag sunxi-fixes-for-4.15-2 + gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST + gpg: using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430 + gpg: issuer "wens@...org" + gpg: Can't check signature: No public key + +Cerchiamo nel keyserver per maggiori informazioni sull'impronta digitale +della chiave (l'impronta digitale, probabilmente, appartiene ad una +sottochiave, dunque non possiamo usarla direttamente senza trovare prima +l'ID della chiave primaria associata ad essa):: + + $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430 + gpg: data source: hkp://keys.gnupg.net + (1) Chen-Yu Tsai <wens@...org> + 4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15 + Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430". Enter number(s), N)ext, or Q)uit > q + +Localizzate l'ID della chiave primaria, nel nostro esempio +``C94035C21B4F2AEB``. Ora visualizzate le chiavi di Linus Torvalds +che avete nel vostro portachiavi:: + + $ gpg --list-key torvalds@kernel.org + pub rsa2048 2011-09-20 [SC] + ABAF11C65A2970B130ABE3C479BE3E4300411886 + uid [ unknown] Linus Torvalds <torvalds@kernel.org> + sub rsa2048 2011-09-20 [E] + +Poi, aprite il `PGP pathfinder`_. Nel campo "From", incollate l'impronta +digitale della chiave di Linus Torvalds che si vede nell'output qui sopra. +Nel campo "to", incollate il key-id della chiave sconosciuta che avete +trovato con ``gpg --search``, e poi verificare il risultato: + +- `Finding paths to Linus`_ + +Se trovate un paio di percorsi affidabili è un buon segno circa la validitĂ +della chiave. Ora, potete aggiungerla al vostro portachiavi dal keyserver:: + + $ gpg --recv-key C94035C21B4F2AEB + +Questa procedura non è perfetta, e ovviamente state riponendo la vostra +fiducia nell'amministratore del servizio *PGP Pathfinder* sperando che non +sia malintenzionato (infatti, questo va contro :ref:`it_devs_not_infra`). +Tuttavia, se mantenete con cura la vostra rete di fiducia sarĂ un deciso +miglioramento rispetto alla cieca fiducia nei keyserver. + +.. _`PGP pathfinder`: https://pgp.cs.uu.nl/ +.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index 6fa5ce9c3572..48e88e5ad2c5 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -1,12 +1,202 @@ .. include:: ../disclaimer-ita.rst :Original: :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> .. _it_stable_kernel_rules: Tutto quello che volevate sapere sui rilasci -stable di Linux ============================================================== -.. warning:: +Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti +"-stable": - TODO ancora da tradurre + - Ovviamente dev'essere corretta e verificata. + - Non dev'essere piĂą grande di 100 righe, incluso il contesto. + - Deve correggere una cosa sola. + - Deve correggere un baco vero che sta disturbando gli utenti (non cose del + tipo "Questo potrebbe essere un problema ..."). + - Deve correggere un problema di compilazione (ma non per cose giĂ segnate + con CONFIG_BROKEN), un kernel oops, un blocco, una corruzione di dati, + un vero problema di sicurezza, o problemi del tipo "oh, questo non va bene". + In pratica, qualcosa di critico. + - Problemi importanti riportati dagli utenti di una distribuzione potrebbero + essere considerati se correggono importanti problemi di prestazioni o di + interattivitĂ . Dato che questi problemi non sono così ovvi e la loro + correzione ha un'alta probabilitĂ d'introdurre una regressione, dovrebbero + essere sottomessi solo dal manutentore della distribuzione includendo un + link, se esiste, ad un rapporto su bugzilla, e informazioni aggiuntive + sull'impatto che ha sugli utenti. + - Non deve correggere problemi relativi a una "teorica sezione critica", + a meno che non venga fornita anche una spiegazione su come questa si + possa verificare. + - Non deve includere alcuna correzione "banale" (correzioni grammaticali, + pulizia dagli spazi bianchi, eccetera). + - Deve rispettare le regole scritte in + :ref:`Documentation/translation/it_IT/process/submitting-patches.rst <it_submittingpatches>` + - Questa patch o una equivalente deve esistere giĂ nei sorgenti principali di + Linux + + +Procedura per sottomettere patch per i sorgenti -stable +------------------------------------------------------- + + - Se la patch contiene modifiche a dei file nelle cartelle net/ o drivers/net, + allora seguite le linee guida descritte in + :ref:`Documentation/translation/it_IT/networking/netdev-FAQ.rst <it_netdev-FAQ>`; + ma solo dopo aver verificato al seguente indirizzo che la patch non sia + giĂ in coda: + https://patchwork.ozlabs.org/bundle/davem/stable/?series=&submitter=&state=*&q=&archive= + - Una patch di sicurezza non dovrebbero essere gestite (solamente) dal processo + di revisione -stable, ma dovrebbe seguire le procedure descritte in + :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`. + + +Per tutte le altre sottomissioni, scegliere una delle seguenti procedure +------------------------------------------------------------------------ + +.. _it_option_1: + +Opzione 1 +********* + +Per far sì che una patch venga automaticamente inclusa nei sorgenti stabili, +aggiungete l'etichetta + +.. code-block:: none + + Cc: stable@vger.kernel.org + +nell'area dedicata alla firme. Una volta che la patch è stata inclusa, verrĂ +applicata anche sui sorgenti stabili senza che l'autore o il manutentore +del sottosistema debba fare qualcosa. + +.. _it_option_2: + +Opzione 2 +********* + +Dopo che la patch è stata inclusa nei sorgenti Linux, inviate una mail a +stable@vger.kernel.org includendo: il titolo della patch, l'identificativo +del commit, il perchĂ© pensate che debba essere applicata, e in quale versione +del kernel la vorreste vedere. + +.. _it_option_3: + +Opzione 3 +********* + +Inviata la patch, dopo aver verificato che rispetta le regole descritte in +precedenza, a stable@vger.kernel.org. Dovete annotare nel changelog +l'identificativo del commit nei sorgenti principali, così come la versione +del kernel nel quale vorreste vedere la patch. + +L':ref:`it_option_1` è fortemente raccomandata; è il modo piĂą facile e usato. +L':ref:`it_option_2` e l':ref:`it_option_3` sono piĂą utili quando, al momento +dell'inclusione dei sorgenti principali, si ritiene che non debbano essere +incluse anche in quelli stabili (per esempio, perchĂ© si crede che si dovrebbero +fare piĂą verifiche per eventuali regressioni). L':ref:`it_option_3` è +particolarmente utile se la patch ha bisogno di qualche modifica per essere +applicata ad un kernel piĂą vecchio (per esempio, perchĂ© nel frattempo l'API è +cambiata). + +Notate che per l':ref:`it_option_3`, se la patch è diversa da quella nei +sorgenti principali (per esempio perchĂ© è stato necessario un lavoro di +adattamento) allora dev'essere ben documentata e giustificata nella descrizione +della patch. + +L'identificativo del commit nei sorgenti principali dev'essere indicato sopra +al messaggio della patch, così: + +.. code-block:: none + + commit <sha1> upstream. + +In aggiunta, alcune patch inviate attraverso l':ref:`it_option_1` potrebbero +dipendere da altre che devo essere incluse. Questa situazione può essere +indicata nel seguente modo nell'area dedicata alle firme: + +.. code-block:: none + + Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle + Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle + Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic + Cc: <stable@vger.kernel.org> # 3.3.x + Signed-off-by: Ingo Molnar <mingo@elte.hu> + +La sequenza di etichette ha il seguente significato: + +.. code-block:: none + + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick <this commit> + +Inoltre, alcune patch potrebbero avere dei requisiti circa la versione del +kernel. Questo può essere indicato usando il seguente formato nell'area +dedicata alle firme: + +.. code-block:: none + + Cc: <stable@vger.kernel.org> # 3.3.x + +L'etichetta ha il seguente significato: + +.. code-block:: none + + git cherry-pick <this commit> + +per ogni sorgente "-stable" che inizia con la versione indicata. + +Dopo la sottomissione: + + - Il mittente riceverĂ un ACK quando la patch è stata accettata e messa in + coda, oppure un NAK se la patch è stata rigettata. A seconda degli impegni + degli sviluppatori, questa risposta potrebbe richiedere alcuni giorni. + - Se accettata, la patch verrĂ aggiunta alla coda -stable per essere + revisionata dal altri sviluppatori e dal principale manutentore del + sottosistema. + + +Ciclo di una revisione +---------------------- + + - Quando i manutentori -stable decidono di fare un ciclo di revisione, le + patch vengono mandate al comitato per la revisione, ai manutentori soggetti + alle modifiche delle patch (a meno che il mittente non sia anche il + manutentore di quell'area del kernel) e in CC: alla lista di discussione + linux-kernel. + - La commissione per la revisione ha 48 ore per dare il proprio ACK o NACK + alle patch. + - Se una patch viene rigettata da un membro della commissione, o un membro + della lista linux-kernel obietta la bontĂ della patch, sollevando problemi + che i manutentori ed i membri non avevano compreso, allora la patch verrĂ + rimossa dalla coda. + - Alla fine del ciclo di revisione tutte le patch che hanno ricevuto l'ACK + verranno aggiunte per il prossimo rilascio -stable, e successivamente + questo nuovo rilascio verrĂ fatto. + - Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente + dalla squadra per la sicurezza del kernel, e non passerĂ per il normale + ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli + su questa procedura. + +Sorgenti +-------- + + - La coda delle patch, sia quelle giĂ applicate che in fase di revisione, + possono essere trovate al seguente indirizzo: + + https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git + + - Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere + trovato in rami distinti per versione al seguente indirizzo: + + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git + + +Comitato per la revisione +------------------------- + + - Questo comitato è fatto di sviluppatori del kernel che si sono offerti + volontari per questo lavoro, e pochi altri che non sono proprio volontari. diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 2ab9c1401aa1..7d7ea92c5c5a 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -67,8 +67,8 @@ sulla radice dei sorgenti del kernel, e non sulle sue sottocartelle. Per creare una patch per un singolo file, spesso è sufficiente fare:: - SRCTREE= linux - MYFILE= drivers/net/mydriver.c + SRCTREE=linux + MYFILE=drivers/net/mydriver.c cd $SRCTREE cp $MYFILE $MYFILE.orig @@ -80,7 +80,7 @@ Per creare una patch per molteplici file, dovreste spacchettare i sorgenti "vergini", o comunque non modificati, e fare un ``diff`` coi vostri. Per esempio:: - MYSRC= /devel/linux + MYSRC=/devel/linux tar xvfz linux-3.19.tar.gz mv linux-3.19 linux-3.19-vanilla @@ -567,11 +567,42 @@ alcunchĂ© - ma dovrebbe indicare che la persona ha ricevuto una copia della patch. Questa etichetta documenta che terzi potenzialmente interessati sono stati inclusi nella discussione. -L'etichetta Co-developed-by: indica che la patch è stata scritta dall'autore in -collaborazione con un altro sviluppatore. Qualche volta questo è utile quando -piĂą persone lavorano sulla stessa patch. Notate, questa persona deve avere -nella patch anche una riga Signed-off-by:. +Co-developed-by: indica che la patch è stata cosviluppata da diversi +sviluppatori; viene usato per assegnare piĂą autori (in aggiunta a quello +associato all'etichetta From:) quando piĂą persone lavorano ad una patch. Dato +che Co-developed-by: implica la paternitĂ della patch, ogni Co-developed-by: +dev'essere seguito immediatamente dal Signed-off-by: del corrispondente +coautore. Qui si applica la procedura di base per sign-off, in pratica +l'ordine delle etichette Signed-off-by: dovrebbe riflettere il piĂą possibile +l'ordine cronologico della storia della patch, indipendentemente dal fatto che +la paternitĂ venga assegnata via From: o Co-developed-by:. Da notare che +l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch. +Notate anche che l'etichetta From: è opzionale quando l'autore in From: è +anche la persona (e indirizzo email) indicato nel From: dell'intestazione +dell'email. + +Esempio di una patch sottomessa dall'autore in From::: + + <changelog> + + Co-developed-by: First Co-Author <first@coauthor.example.org> + Signed-off-by: First Co-Author <first@coauthor.example.org> + Co-developed-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + +Esempio di una patch sottomessa dall'autore Co-developed-by::: + + From: From Author <from@author.example.org> + + <changelog> + + Co-developed-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> + Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> 13) Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes: ----------------------------------------------------------------------------- @@ -719,7 +750,7 @@ Un paio di esempi di oggetti:: La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel formato: - From: Original Author <author@example.com> + From: Patch Author <author@example.com> La riga ``from`` indica chi verrĂ accreditato nel changelog permanente come l'autore della patch. Se la riga ``from`` è mancante, allora per determinare diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist index 60c7c35ac517..b42220d3d46c 100644 --- a/Documentation/translations/ja_JP/SubmitChecklist +++ b/Documentation/translations/ja_JP/SubmitChecklist @@ -74,38 +74,34 @@ Linux ă‚«ăĽăŤă«ă‘ăă投稿者ĺ‘ă‘ăェăă‚ŻăŞă‚ąă 13: CONFIG_SMP, CONFIG_PREEMPT を有効ă«ă—ăźĺ ´ĺă¨ç„ˇĺŠąă«ă—ăźĺ ´ĺă®ä¸ˇć–ąă§ ă“ă«ă‰ă—ăźä¸Šă€ĺ‹•ä˝śç˘şčŞŤă‚’čˇŚăŁă¦ăŹă ă•ă„。 -14: ă‚‚ă—ă‘ăăăŚă‡ă‚Łă‚ąă‚Żă®I/O性č˝ăŞă©ă«ĺ˝±éźżă‚’与ăă‚‹ă‚ă†ă§ă‚ă‚Śă°ă€ - 'CONFIG_LBDAF'ă‚Şă—ă‚·ă§ăłă‚’有効ă«ă—ăźĺ ´ĺă¨ç„ˇĺŠąă«ă—ăźĺ ´ĺă®ä¸ˇć–ąă§ - ă†ă‚ąăを実施ă—ă¦ăżă¦ăŹă ă•ă„。 +14: lockdepă®ć©źč˝ă‚’ĺ…¨ă¦ćś‰ĺŠąă«ă—ăźä¸Šă§ă€ĺ…¨ă¦ă®ă‚łăĽă‰ă‘スを評価ă—ă¦ăŹă ă•ă„。 -15: lockdepă®ć©źč˝ă‚’ĺ…¨ă¦ćś‰ĺŠąă«ă—ăźä¸Šă§ă€ĺ…¨ă¦ă®ă‚łăĽă‰ă‘スを評価ă—ă¦ăŹă ă•ă„。 - -16: /proc ă«ć–°ă—ă„エăłăăŞă‚’čż˝ĺŠ ă—ăźĺ ´ĺă«ăŻă€Documentation/ 配下㫠+15: /proc ă«ć–°ă—ă„エăłăăŞă‚’čż˝ĺŠ ă—ăźĺ ´ĺă«ăŻă€Documentation/ 配下㫠必ăšă‰ă‚ăĄăˇăłăă‚’čż˝ĺŠ ă—ă¦ăŹă ă•ă„。 -17: ć–°ă—ă„ă–ăĽăă‘ă©ăˇăĽă‚żă‚’čż˝ĺŠ ă—ăźĺ ´ĺă«ăŻă€ +16: ć–°ă—ă„ă–ăĽăă‘ă©ăˇăĽă‚żă‚’čż˝ĺŠ ă—ăźĺ ´ĺă«ăŻă€ ĺż…ăšDocumentation/admin-guide/kernel-parameters.rst ă«čެćŽă‚’čż˝ĺŠ ă—ă¦ăŹă ă•ă„。 -18: ć–°ă—ăŹmoduleă«ă‘ă©ăˇăĽă‚żă‚’čż˝ĺŠ ă—ăźĺ ´ĺă«ăŻă€MODULE_PARM_DESC()ă‚’ +17: ć–°ă—ăŹmoduleă«ă‘ă©ăˇăĽă‚żă‚’čż˝ĺŠ ă—ăźĺ ´ĺă«ăŻă€MODULE_PARM_DESC()ă‚’ ĺ©ç”¨ă—ă¦ĺż…ăšăťă®čެćŽă‚’č¨čż°ă—ă¦ăŹă ă•ă„。 -19: ć–°ă—ă„userspaceイăłă‚żă•ă‚§ăĽă‚ąă‚’作ćă—ăźĺ ´ĺă«ăŻă€Documentation/ABI/ ă« +18: ć–°ă—ă„userspaceイăłă‚żă•ă‚§ăĽă‚ąă‚’作ćă—ăźĺ ´ĺă«ăŻă€Documentation/ABI/ ă« Documentation/ABI/README を参č€ă«ă—ă¦ĺż…ăšă‰ă‚ăĄăˇăłăă‚’čż˝ĺŠ ă—ă¦ăŹă ă•ă„。 -20: 'make headers_check'を実行ă—ă¦ĺ…¨ăŹĺ•ŹéˇŚăŚăŞă„ă“ă¨ă‚’確認ă—ă¦ăŹă ă•ă„。 +19: 'make headers_check'を実行ă—ă¦ĺ…¨ăŹĺ•ŹéˇŚăŚăŞă„ă“ă¨ă‚’確認ă—ă¦ăŹă ă•ă„。 -21: ĺ°‘ăŞăŹă¨ă‚‚slabアăケăĽă‚·ă§ăłă¨pageアăケăĽă‚·ă§ăłă«ĺ¤±ć•—ă—ăźĺ ´ĺă® +20: ĺ°‘ăŞăŹă¨ă‚‚slabアăケăĽă‚·ă§ăłă¨pageアăケăĽă‚·ă§ăłă«ĺ¤±ć•—ă—ăźĺ ´ĺ㮠挙動ă«ă¤ă„ă¦ă€fault-injectionă‚’ĺ©ç”¨ă—ă¦ç˘şčŞŤă—ă¦ăŹă ă•ă„。 Documentation/fault-injection/ を参照ă—ă¦ăŹă ă•ă„。 čż˝ĺŠ ă—ăźă‚łăĽă‰ăŚă‹ăŞă‚Šă®é‡Źă§ă‚ăŁăźăŞă‚‰ă°ă€ă‚µă–ă‚·ă‚ąă†ă 特有㮠fault-injectionă‚’čż˝ĺŠ ă—ăźă»ă†ăŚč‰Żă„ă‹ă‚‚ă—ă‚Śăľă›ă‚“。 -22: ć–°ăźă«čż˝ĺŠ ă—ăźă‚łăĽă‰ăŻă€`gcc -W'ă§ă‚łăłă‘イă«ă—ă¦ăŹă ă•ă„。 +21: ć–°ăźă«čż˝ĺŠ ă—ăźă‚łăĽă‰ăŻă€`gcc -W'ă§ă‚łăłă‘イă«ă—ă¦ăŹă ă•ă„。 ă“ă®ă‚Şă—ă‚·ă§ăłăŻĺ¤§é‡Źă®ä¸Ťč¦ăŞăˇăă‚»ăĽă‚¸ă‚’出力ă—ăľă™ăŚă€ "warning: comparison between signed and unsigned" ă®ă‚ă†ăŞăˇăă‚»ăĽă‚¸ăŻă€ ăグを見ă¤ă‘ă‚‹ă®ă«ĺ˝ąă«ç«‹ăˇăľă™ă€‚ -23: 投稿ă—ăźă‘ăă㌠-mm ă‘ăăă‚»ăăă«ăžăĽă‚¸ă•ă‚ŚăźĺľŚă€ĺ…¨ă¦ă®ć—˘ĺă®ă‘ăăă‚„ +22: 投稿ă—ăźă‘ăă㌠-mm ă‘ăăă‚»ăăă«ăžăĽă‚¸ă•ă‚ŚăźĺľŚă€ĺ…¨ă¦ă®ć—˘ĺă®ă‘ăăă‚„ VM, VFS ăŠă‚ăłăťă®ä»–ă®ă‚µă–ă‚·ă‚ąă†ă ă«é–˘ă™ă‚‹ć§ă€…ăŞĺ¤‰ć›´ă¨ă€çŹľć™‚ç‚ąă§ă‚‚ĺ…±ĺ ă§ăŤă‚‹ă“ă¨ă‚’確認ă™ă‚‹ă†ă‚ąăを行ăŁă¦ăŹă ă•ă„。 diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index 02139656463e..ad979c3c06a6 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -58,8 +58,8 @@ Linux ă‚«ăĽăŤă«ă«ĺŻľă™ă‚‹ĺ…¨ă¦ă®ĺ¤‰ć›´ăŻ diff(1) ă‚łăžăłă‰ă«ă‚ă‚‹ă 1個ă®ă•ă‚ˇă‚¤ă«ă«ă¤ă„ă¦ă®ă‘ăăを作ćă™ă‚‹ăźă‚ă«ăŻă€ă»ă¨ă‚“ă©ă®ĺ ´ĺ〠以下ă®ä˝śćĄă‚’行ăă°ĺŤĺ†ă§ă™ă€‚ - SRCTREE= linux-2.6 - MYFILE= drivers/net/mydriver.c + SRCTREE=linux-2.6 + MYFILE=drivers/net/mydriver.c cd $SRCTREE cp $MYFILE $MYFILE.orig @@ -71,7 +71,7 @@ Linux ă‚«ăĽăŤă«ă«ĺŻľă™ă‚‹ĺ…¨ă¦ă®ĺ¤‰ć›´ăŻ diff(1) ă‚łăžăłă‰ă«ă‚ă‚‹ă ăŞă‚Źăˇĺ¤‰ć›´ă‚’ĺŠ ăă¦ăŞă„ Linux ă‚«ăĽăŤă«ă‚’展開ă—ă€č‡Şĺ†ă® Linux ă‚«ăĽăŤă« ă‚˝ăĽă‚ąă¨ă®ĺ·®ĺ†ă‚’生ćă—ăŞă„ă¨ă„ă‘ăľă›ă‚“。例ăă°ă€ - MYSRC= /devel/linux-2.6 + MYSRC=/devel/linux-2.6 tar xvfz linux-2.6.12.tar.gz mv linux-2.6.12 linux-2.6.12-vanilla diff --git a/Documentation/translations/zh_CN/SubmittingPatches b/Documentation/translations/zh_CN/SubmittingPatches deleted file mode 100644 index e9098da8f1a4..000000000000 --- a/Documentation/translations/zh_CN/SubmittingPatches +++ /dev/null @@ -1,412 +0,0 @@ -Chinese translated version of Documentation/process/submitting-patches.rst - -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. - -Chinese maintainer: TripleX Chung <triplex@zh-kernel.org> ---------------------------------------------------------------------- -Documentation/process/submitting-patches.rst çš„ä¸ć–‡çż»čŻ‘ - -如果ćłčŻ„论ć–更新本文的内容，请直接č”çł»ĺŽźć–‡ćˇŁçš„ç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡ -交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 -译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 - -ä¸ć–‡ç‰ç»´ćŠ¤č€…： 钟宇 TripleX Chung <triplex@zh-kernel.org> -ä¸ć–‡ç‰çż»čŻ‘者： 钟宇 TripleX Chung <triplex@zh-kernel.org> -ä¸ć–‡ç‰ć ˇčŻ‘者： ćťŽéł Li Yang <leo@zh-kernel.org> - çŽ‹čŞ Wang Cong <xiyou.wangcong@gmail.com> - -以下为ćŁć–‡ ---------------------------------------------------------------------- - - ĺ¦‚ä˝•č®©ä˝ çš„ć”ąĺŠ¨čż›ĺ…Ąĺ†…ć ¸ - ć–者 - 获得亲ç±çš„ Linus Torvalds çš„ĺ…łćł¨ĺ’Śĺ¤„ç† ----------------------------------- - -对于ćłč¦ĺ°†ć”ąĺŠ¨ćŹäş¤ĺ° Linux ĺ†…ć ¸çš„ä¸Şäşşć–者公司来说，如果不熟悉“规矩”， -ćŹäş¤çš„ćµç¨‹äĽšč®©äşşç•Źć§ă€‚本文档收集了一系ĺ—建议，这些建议可以大大的ćŹé«ä˝ -的改动被接受的机会。 -é…读 Documentation/process/submit-checklist.rst 来获得在ćŹäş¤ä»Łç 前需č¦ćŁ€ćźĄçš„éˇąç›®çš„ĺ— -čˇ¨ă€‚ĺ¦‚ćžśä˝ ĺś¨ćŹäş¤ä¸€ä¸Şé©±ĺŠ¨ç¨‹ĺşŹďĽŚé‚ŁäąĺŚć—¶é…读一下 -Documentation/process/submitting-drivers.rst 。 - - --------------------------- -第一节 - ĺ›ĺ»şĺą¶ĺŹ‘é€ä˝ 的改动 --------------------------- - -1) "diff -up" ------------ - -使用 "diff -up" ć–者 "diff -uprN" 来ĺ›ĺ»şčˇĄä¸ă€‚ - -ć‰€ćś‰ĺ†…ć ¸çš„ć”ąĺŠ¨ďĽŚé˝ćŻä»ĄčˇĄä¸çš„形式ĺ‘现的，补ä¸ç”± diff(1) 生ć。ĺ›ĺ»şčˇĄä¸çš„ -时候，č¦çˇ®č®¤ĺ®ćŻä»Ą "unified diff" ć ĽĺĽŹĺ›ĺ»şçš„ďĽŚčż™ç§Ťć ĽĺĽŹç”± diff(1) çš„ '-u' -参数生ć。而且，请使用 '-p' ĺŹ‚ć•°ďĽŚé‚Łć ·äĽšćľç¤şćŻŹä¸Şć”ąĺŠ¨ć‰€ĺś¨çš„C函数，使得 -产生的补ä¸ĺ®ąć“读得多。补ä¸ĺş”čŻĄĺźşäşŽĺ†…ć ¸ćşä»Łç ć ‘çš„ć ąç›®ĺ˝•ďĽŚč€Śä¸ŤćŻé‡Śčľąçš„ä»» -何ĺ目录。 -为一个单独的文件ĺ›ĺ»şčˇĄä¸ďĽŚä¸€č¬ćťĄčŻ´čż™ć ·ĺšĺ°±ĺ¤źäş†ďĽš - - SRCTREE= linux-2.6 - MYFILE= drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -为多个文件ĺ›ĺ»şčˇĄä¸ďĽŚä˝ ĺŹŻä»Ąč§ŁĺĽ€ä¸€ä¸Şć˛ˇćś‰äż®ć”ąčż‡çš„ĺ†…ć ¸ćşä»Łç ć ‘ďĽŚç„¶ĺŽĺ’Śä˝ 自 -己的代ç ć ‘äą‹é—´ĺš diff 。例如： - - MYSRC= /devel/linux-2.6 - - tar xvfz linux-2.6.12.tar.gz - mv linux-2.6.12 linux-2.6.12-vanilla - diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ - linux-2.6.12-vanilla $MYSRC > /tmp/patch - -"dontdiff" ćŻĺ†…ć ¸ĺś¨çĽ–čŻ‘çš„ć—¶ĺ€™äş§ç”źçš„ć–‡ä»¶çš„ĺ—表，ĺ—表ä¸çš„文件在 diff(1) -产生的补ä¸é‡ŚäĽšč˘«č·łčż‡ă€‚"dontdiff" 文件被包ĺ«ĺś¨2.6.12ĺ’Śäą‹ĺŽç‰ćś¬çš„ĺ†…ć ¸ćşä»Ł -ç ć ‘ä¸ă€‚ĺŻąäşŽć›´ć—©çš„ĺ†…ć ¸ç‰ćś¬ďĽŚä˝ 可以从 -<http://www.xenotime.net/linux/doc/dontdiff> 获取ĺ®ă€‚ -çˇ®ĺ®šä˝ çš„čˇĄä¸é‡Ść˛ˇćś‰ĺŚ…ĺ«ä»»ä˝•ä¸Ťĺ±žäşŽčż™ć¬ˇčˇĄä¸ćŹäş¤çš„额外文件。记得在用diff(1) -生ć补ä¸äą‹ĺŽďĽŚĺ®ˇé…一次补ä¸ďĽŚä»Ąçˇ®äżťĺ‡†çˇ®ă€‚ -ĺ¦‚ćžśä˝ çš„ć”ąĺŠ¨ĺľć•Łäą±ďĽŚä˝ ĺş”čŻĄç ”ç©¶ä¸€ä¸‹ĺ¦‚ä˝•ĺ°†čˇĄä¸ĺ†ĺ‰˛ć独立的é¨ĺ†ďĽŚĺ°†ć”ąĺŠ¨ĺ† -割ć一系ĺ—ĺ乎逻辑的ćĄéŞ¤ă€‚čż™ć ·ć›´ĺ®ąć“č®©ĺ…¶ä»–ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ĺ®ˇć ¸ďĽŚĺ¦‚ćžśä˝ ćłä˝ çš„ -补ä¸č˘«ćŽĄĺŹ—，这ćŻĺľé‡Ťč¦çš„。下面这些脚本č˝ĺ¤źĺ¸®ĺŠ©ä˝ ĺščż™ä»¶äş‹ć…： -Quilt: -http://savannah.nongnu.org/projects/quilt - -2)ćŹŹčż°ä˝ çš„ć”ąĺŠ¨ă€‚ -ćŹŹčż°ä˝ çš„ć”ąĺŠ¨ĺŚ…ĺ«çš„技术细节。 - -č¦ĺ¤šĺ…·ä˝“就写多具体。最糟糕的描述可č˝ćŻĺŹä¸‹éť˘čż™äş›čŻĺŹĄďĽšâ€ść›´ć–°äş†ćźé©±ĺŠ¨ç¨‹ -序”，“修ćŁäş†ćźé©±ĺŠ¨ç¨‹ĺşŹçš„bug”，ć–者“这个补ä¸ĺŚ…ĺ«äş†ćźĺ系统的修改，请 -使用。” - -ĺ¦‚ćžśä˝ çš„ćŹŹčż°ĺĽ€ĺ§‹ĺŹé•żďĽŚčż™čˇ¨ç¤şä˝ 也许需č¦ć‹†ĺ†ä˝ 的补ä¸äş†ďĽŚčŻ·çś‹ç¬¬3小节， -继ç»ă€‚ - -3)拆ĺ†ä˝ 的改动 - -将改动拆ĺ†ďĽŚé€»čľ‘类似的放ĺ°ĺŚä¸€ä¸ŞčˇĄä¸ć–‡ä»¶é‡Śă€‚ - -äľ‹ĺ¦‚ďĽŚĺ¦‚ćžśä˝ çš„ć”ąĺŠ¨é‡ŚĺŚć—¶ćś‰bugäż®ćŁĺ’Ść€§č˝äĽĺŚ–，那äąćŠŠčż™äş›ć”ąĺŠ¨ć‹†ĺ†ĺ°ä¸¤ä¸Şć– -者更多的补ä¸ć–‡ä»¶ä¸ă€‚ĺ¦‚ćžśä˝ çš„ć”ąĺŠ¨ĺŚ…ĺ«ĺŻąAPI的修改，并且修改了驱动程序来适 -应这些新的API，那äąćŠŠčż™äş›äż®ć”ąĺ†ć两个补ä¸ă€‚ - -ĺŹ¦ä¸€ć–ąéť˘ďĽŚĺ¦‚ćžśä˝ ĺ°†ä¸€ä¸ŞĺŤ•ç‹¬çš„ć”ąĺŠ¨ĺšć多个补ä¸ć–‡ä»¶ďĽŚé‚Łäąĺ°†ĺ®ä»¬ĺ并ć一个 -单独的补ä¸ć–‡ä»¶ă€‚čż™ć ·ä¸€ä¸Şé€»čľ‘ä¸ŠĺŤ•ç‹¬çš„ć”ąĺŠ¨ĺŹŞč˘«ĺŚ…ĺ«ĺś¨ä¸€ä¸ŞčˇĄä¸ć–‡ä»¶é‡Śă€‚ - -如果有一个补ä¸äľťčµ–另外一个补ä¸ćťĄĺ®Śćĺ®çš„改动，那没问é˘ă€‚ç®€ĺŤ•çš„ĺś¨ä˝ çš„čˇĄ -ä¸ćŹŹčż°é‡ŚćŚ‡ĺ‡şâ€śčż™ä¸ŞčˇĄä¸äľťčµ–ćźčˇĄä¸â€ťĺ°±ĺĄ˝äş†ă€‚ - -ĺ¦‚ćžśä˝ ä¸Ťč˝ĺ°†čˇĄä¸ćµ“缩ć更少的文件，那äąćŻŹć¬ˇĺ¤§çş¦ĺŹ‘é€ĺ‡ş15个，然ĺŽç‰ĺľ…审查 -ĺ’Ść•´ĺ。 - -4)选择 e-mail 的收件人 - -çś‹ä¸€éŤ MAINTAINERS 文件和ćşä»Łç ďĽŚçś‹çś‹ä˝ ć‰€çš„ć”ąĺŠ¨ć‰€ĺś¨çš„ĺ†…ć ¸ĺ系统有没有指 -定的维护者。如果有，给他们发e-mail。 - -如果没有找ĺ°ç»´ćŠ¤č€…，ć–者维护者没有反é¦ďĽŚĺ°†ä˝ 的补ä¸ĺŹ‘é€ĺ°ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä¸»é‚® -件ĺ—表 linux-kernel@vger.kernel.org。大é¨ĺ†çš„ĺ†…ć ¸ĺĽ€ĺŹ‘č€…é˝č·źč¸Şčż™ä¸Şé‚®ä»¶ĺ— -čˇ¨ďĽŚĺŹŻä»ĄčŻ„ä»·ä˝ çš„ć”ąĺŠ¨ă€‚ - -每次不č¦ĺŹ‘é€č¶…过15个补ä¸ĺ° vger 邮件ĺ—表ďĽďĽďĽ - -Linus Torvalds ćŻĺ†łĺ®šć”ąĺŠ¨č˝ĺ¦čż›ĺ…Ą Linux ĺ†…ć ¸çš„ćś€ç»čŁĺ†łč€…。他的 e-mail -ĺś°ĺť€ćŻ <torvalds@linux-foundation.org> 。他收ĺ°çš„ e-mail ĺľĺ¤šďĽŚć‰€ä»Ąä¸€č¬ -的说，最好ĺ«ç»™ä»–发 e-mail。 - -那些修ćŁbug，“ćľč€Ść“č§â€ťçš„修改ć–者ćŻç±»äĽĽçš„只需č¦ĺľĺ°‘讨论的补ä¸ĺŹŻä»Ąç›´ćŽĄ -发é€ć–者CCç»™Linus。那些需č¦č®¨č®şć–者没有ĺľć¸…楚的好处的补ä¸ďĽŚä¸€č¬ĺ…发é€ĺ° -linux-kernel邮件ĺ—表。只有当补ä¸č˘«č®¨č®şĺľ—差不多了，才ćŹäş¤ç»™Linus。 - -5)选择CC( e-mail 抄é€)ĺ—表 - -é™¤éťžä˝ ćś‰ç†ç”±ä¸Ťčż™ć ·ĺšďĽŚĺ¦ĺ™CC linux-kernel@vger.kernel.org。 - -除了 Linus äą‹ĺ¤–ďĽŚĺ…¶ä»–ĺ†…ć ¸ĺĽ€ĺŹ‘č€…äąźéś€č¦ćł¨ć„Źĺ°ä˝ çš„ć”ąĺŠ¨ďĽŚčż™ć ·ä»–ä»¬ć‰Ťč˝čŻ„č®şä˝ -的改动并ćŹäľ›ä»Łç 审查和建议。linux-kernel ćŻ Linux ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä¸»é‚®ä»¶ĺ—表 -。其ĺ®çš„邮件ĺ—表为特定的ĺ系统ćŹäľ›ćśŤĺŠˇďĽŚćŻ”如 USB，framebuffer 设备，虚 -拟文件系统，SCSI ĺ系统，ç‰ç‰ă€‚查看 MAINTAINERS ć–‡ä»¶ćťĄčŽ·ĺľ—ĺ’Śä˝ çš„ć”ąĺŠ¨ćś‰ -关的邮件ĺ—表。 - -Majordomo lists of VGER.KERNEL.ORG at: - <http://vger.kernel.org/vger-lists.html> - -如果改动影响了用ć·ç©şé—´ĺ’Śĺ†…ć ¸äą‹é—´çš„ćŽĄĺŹŁďĽŚčŻ·ç»™ MAN-PAGES 的维护者ďĽĺ—在 -MAINTAINERS 文件里的）发é€ä¸€ä¸Şć‰‹ĺ†ŚéˇµďĽman-pages）补ä¸ďĽŚć–者至少通知一下改 -ĺŹďĽŚč®©ä¸€äş›äżˇćŻćś‰é€”径进入手册页。 - -即使在第四ćĄçš„时候，维护者没有作出回应，也č¦çˇ®č®¤ĺś¨äż®ć”ąä»–们的代ç 的时候 -，一直将维护者拷贝ĺ°CCĺ—表ä¸ă€‚ - -对于小的补ä¸ďĽŚä˝ 也许会CCĺ° Adrian Bunk 管ç†çš„ćśé›†ç碎补ä¸çš„邮件ĺ—表 -(Trivial Patch Monkey)trivial@kernel.org，那里专门收集ç碎的补ä¸ă€‚ä¸‹éť˘čż™ć · -的补ä¸äĽšč˘«çś‹ä˝śâ€śç碎的”补ä¸ďĽš - 文档的拼写修ćŁă€‚ - äż®ćŁäĽšĺ˝±ĺ“Ťĺ° grep(1) 的拼写。 - č¦ĺ‘ŠäżˇćŻäż®ćŁ(频çąçš„ć‰“ĺŤ°ć— ç”¨çš„č¦ĺ‘ŠćŻä¸ŤĺĄ˝çš„。) - 编译错误修ćŁďĽä»Łç 逻辑的确ćŻĺŻąçš„，只ćŻçĽ–译有问é˘ă€‚） - čżčˇŚć—¶äż®ćŁďĽĺŹŞč¦çśźçš„äż®ćŁäş†é”™čŻŻă€‚） - 移除使用了被废ĺĽçš„函数/宏的代ç (例如 check_region。) - č”系方式和文档修ćŁă€‚ - 用可移植的代ç 替换不可移植的代ç ďĽĺŤłä˝żĺś¨ä˝“系结构相关的代ç ä¸ďĽŚć—˘ç„¶ćś‰ - 人拷贝，只č¦ĺ®ćŻç碎的） - 任何文件的作者/维护者对该文件的改动ďĽäľ‹ĺ¦‚ patch monkey ĺś¨é‡ŤäĽ ć¨ˇĺĽŹä¸‹ďĽ‰ - -EMAIL: trivial@kernel.org - -(译注，关于“ç碎补ä¸â€ťçš„一些说ćŽďĽšĺ› 为原文的这一é¨ĺ†ĺ†™ĺľ—比čľç®€ĺŤ•ďĽŚć‰€ä»Ąä¸Ťĺľ—不 -违例写一下译注。"trivial"这个英文单词的本意ćŻâ€śç碎的，不重č¦çš„。”但ćŻĺś¨čż™é‡Ś -有稍微有一些ĺŹĺŚ–，例如对一些ćŽćľçš„NULL指é’çš„äż®ćŁďĽŚĺ±žäşŽčżčˇŚć—¶äż®ćŁďĽŚäĽšč˘«ĺ˝’ç±» -ĺ°ç碎补ä¸é‡Śă€‚虽然NULL指é’çš„äż®ćŁĺľé‡Ťč¦ďĽŚä˝†ćŻčż™ć ·çš„äż®ćŁĺľ€ĺľ€ĺľĺ°Źč€Śä¸”ĺľĺ®ąć“ĺľ—ĺ° -检验，所以也被归入ç碎补ä¸ă€‚ç碎补ä¸ć›´ç˛ľçˇ®çš„ĺ˝’ç±»ĺş”čŻĄćŻ -“simple, localized & easy to verify”，也就ćŻčŻ´ç®€ĺŤ•çš„，局é¨çš„ĺ’Ść“于检验的。 -trivial@kernel.org邮件ĺ—表的目的ćŻé’ĺŻąčż™ć ·çš„čˇĄä¸ďĽŚä¸şćŹäş¤č€…ćŹäľ›ä¸€ä¸Şä¸ĺżďĽŚćťĄ -降低ćŹäş¤çš„门槛。) - -6)没有 MIME 编ç ，没有链接，没有压缩，没有附件，只有纯文本。 - -Linus ĺ’Śĺ…¶ä»–çš„ĺ†…ć ¸ĺĽ€ĺŹ‘č€…éś€č¦é…čŻ»ĺ’ŚčŻ„č®şä˝ ćŹäş¤çš„ć”ąĺŠ¨ă€‚ĺŻąäşŽĺ†…ć ¸ĺĽ€ĺŹ‘č€…ćťĄčŻ´ -ďĽŚĺŹŻä»Ąâ€śĺĽ•ç”¨â€ťä˝ çš„ć”ąĺŠ¨ĺľé‡Ťč¦ďĽŚä˝żç”¨ä¸€č¬çš„ e-mail ĺ·Ąĺ…·ďĽŚä»–ä»¬ĺ°±ĺŹŻä»Ąĺś¨ä˝ çš„ -代ç çš„ä»»ä˝•ä˝Ťç˝®ć·»ĺŠ čŻ„č®şă€‚ - -ĺ› ä¸şčż™ä¸ŞĺŽźĺ› ďĽŚć‰€ćś‰çš„ćŹäş¤çš„补ä¸é˝ćŻ e-mail ä¸â€śĺ†…嵌”的。 -č¦ĺ‘ŠďĽšĺ¦‚ćžśä˝ ä˝żç”¨ĺ‰Şĺ‡-ç˛č´´ä˝ 的补ä¸ďĽŚĺ°Źĺżä˝ 的编辑器的自动换行功č˝ç ´ĺťŹä˝ çš„ -补ä¸ă€‚ - -不č¦ĺ°†čˇĄä¸ä˝śä¸ş MIME 编ç 的附件，不管ćŻĺ¦ĺŽ‹çĽ©ă€‚ĺľĺ¤šćµčˇŚçš„ e-mail 软件不 -ćŻä»»ä˝•ć—¶ĺ€™é˝ĺ°† MIME 编ç 的附件当作纯文本发é€çš„，这会使得ĺ«äşşć— ćł•ĺś¨ä˝ çš„ -代ç ä¸ĺŠ 评论。另外，MIME 编ç 的附件会让 Linus 多花一点时间来处ç†ďĽŚčż™ĺ°± -é™Ťä˝Žäş†ä˝ çš„ć”ąĺŠ¨č˘«ćŽĄĺŹ—çš„ĺŹŻč˝ć€§ă€‚ - -č¦ĺ‘ŠďĽšä¸€äş›é‚®ä»¶č˝Żä»¶ďĽŚćŻ”如 Mozilla äĽšĺ°†ä˝ çš„äżˇćŻä»Ąĺ¦‚ä¸‹ć ĽĺĽŹĺŹ‘é€ďĽš ----- 邮件头 ---- -Content-Type: text/plain; charset=us-ascii; format=flowed ----- 邮件头 ---- -é—®é˘ĺś¨äşŽ “format=flowed” 会让接收端的ćźäş›é‚®ä»¶č˝Żä»¶ĺ°†é‚®ä»¶ä¸çš„ĺ¶čˇ¨ç¬¦ć›żćŤ˘ -ćç©şć Ľä»ĄĺŹŠĺšä¸€äş›ç±»äĽĽçš„ć›żćŤ˘ă€‚čż™ć ·ďĽŚä˝ ĺŹ‘é€çš„时候看起来没问é˘çš„补ä¸ĺ°±č˘«ç ´ -坏了。 - -č¦äż®ćŁčż™ä¸Şé—®é˘ďĽŚĺŹŞéś€č¦ĺ°†ä˝ çš„ mozilla çš„ defaults/pref/mailnews.js 文件 -里的 -pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= -修改ć -pref("mailnews.display.disable_format_flowed_support", true); -就可以了。 - -7) e-mail 的大小 - -ç»™ Linus 发é€čˇĄä¸çš„时候，永远按照第6小节说的ĺšă€‚ - -大的改动对邮件ĺ—表不ĺ适，对ćźäş›ç»´ćŠ¤č€…也不ĺé€‚ă€‚ĺ¦‚ćžśä˝ çš„čˇĄä¸ďĽŚĺś¨ä¸ŤĺŽ‹çĽ© -çš„ć…况下，超过了40kB，那äąä˝ 最好将补ä¸ć”ľĺś¨ä¸€ä¸Şč˝é€ščż‡ internet 访问的服 -务器上，然ĺŽç”¨ćŚ‡ĺ‘ä˝ çš„čˇĄä¸çš„ URL 替代。 - -8) ćŚ‡ĺ‡şä˝ çš„ĺ†…ć ¸ç‰ćś¬ - -ĺś¨ć ‡é˘ĺ’Śĺś¨čˇĄä¸çš„描述ä¸ďĽŚćŚ‡ĺ‡şčˇĄä¸ĺŻąĺş”çš„ĺ†…ć ¸çš„ç‰ćś¬ďĽŚćŻĺľé‡Ťč¦çš„。 - -如果补ä¸ä¸Ťč˝ĺą˛ĺ‡€çš„在最新ç‰ćś¬çš„ĺ†…ć ¸ä¸Šć‰“ä¸ŠďĽŚLinus ćŻä¸ŤäĽšćŽĄĺŹ—ĺ®çš„。 - -9) 不č¦ć°”é¦ďĽŚç»§ç»ćŹäş¤ă€‚ - -ĺ˝“ä˝ ćŹäş¤äş†ć”ąĺŠ¨ä»ĄĺŽďĽŚč€ĺżĺś°ç‰ĺľ…。如果 Linus ĺ–ść¬˘ä˝ çš„ć”ąĺŠ¨ĺą¶ä¸”ĺŚć„Źĺ®ďĽŚé‚Łäą -ĺ®ĺ°†ĺś¨ä¸‹ä¸€ä¸Şĺ†…ć ¸ĺŹ‘ĺ¸ç‰ćś¬ä¸ĺ‡şçŽ°ă€‚ - -ç„¶č€ŚďĽŚĺ¦‚ćžśä˝ çš„ć”ąĺŠ¨ć˛ˇćś‰ĺ‡şçŽ°ĺś¨ä¸‹ä¸€ä¸Şç‰ćś¬çš„ĺ†…ć ¸ä¸ďĽŚĺŹŻč˝ćś‰č‹Ąĺą˛ĺŽźĺ› 。减少那 -äş›ĺŽźĺ› ďĽŚäż®ćŁé”™čŻŻďĽŚé‡Ťć–°ćŹäş¤ć›´ć–°ĺŽçš„改动，ćŻä˝ 自己的工作。 - -Linus不给出任何评论就“丢ĺĽâ€ťä˝ 的补ä¸ćŻĺ¸¸č§çš„äş‹ć…。在系统ä¸čż™ć ·çš„äş‹ć…ĺľ -ĺąłĺ¸¸ă€‚ĺ¦‚ćžśä»–ć˛ˇćś‰ćŽĄĺŹ—ä˝ çš„čˇĄä¸ďĽŚäąźč®¸ćŻç”±äşŽä»Ąä¸‹ĺŽźĺ› ： -* ä˝ çš„čˇĄä¸ä¸Ťč˝ĺś¨ćś€ć–°ç‰ćś¬çš„ĺ†…ć ¸ä¸Šĺą˛ĺ‡€çš„ć‰“ä¸Šă€‚ -* ä˝ çš„čˇĄä¸ĺś¨ linux-kernel 邮件ĺ—表ä¸ć˛ˇćś‰ĺľ—ĺ°ĺ……ĺ†çš„讨论。 -* éŁŽć Ľé—®é˘ďĽĺŹ‚照第2小节） -* é‚®ä»¶ć ĽĺĽŹé—®é˘ďĽé‡ŤčŻ»ćś¬čŠ‚） -* ä˝ çš„ć”ąĺŠ¨ćś‰ćŠ€ćśŻé—®é˘ă€‚ -* 他收ĺ°äş†ćĺ¨çš„ e-mailďĽŚč€Śä˝ çš„ĺś¨ć··äą±ä¸ä¸˘ĺ¤±äş†ă€‚ -* ä˝ č®©äşşä¸şéšľă€‚ - -有疑问的时候，在 linux-kernel 邮件ĺ—表上请求评论。 - -10) ĺś¨ć ‡é˘ä¸ŠĺŠ 上 PATCH çš„ĺ—ć · - -Linus ĺ’Ś linux-kernel 邮件ĺ—表的 e-mail ćµé‡Źé˝ĺľé«ďĽŚä¸€ä¸Şé€šĺ¸¸çš„约定ćŻć ‡ -é˘čˇŚä»Ą [PATCH] ĺĽ€ĺ¤´ă€‚čż™ć ·ĺŹŻä»Ąč®© Linus ĺ’Śĺ…¶ä»–ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘可以从 e-mail -的讨论ä¸ĺľč˝»ć“的将补ä¸ĺ†čľ¨ĺ‡şćťĄă€‚ - -11ďĽ‰ä¸şä˝ çš„ĺ·Ąä˝śçľĺŤ - -ä¸şäş†ĺŠ ĺĽşĺŻąč°ĺšäş†ä˝•äş‹çš„追踪，尤其ćŻĺŻąé‚Łäş›é€Źčż‡ĺĄ˝ĺ‡ 层的维护者的补ä¸ďĽŚć‘们 -建议在发é€ĺ‡şĺŽ»çš„补ä¸ä¸ŠĺŠ 一个 “sign-off” 的过程。 - -"sign-off" ćŻĺś¨čˇĄä¸çš„注释的最ĺŽçš„简单的一行文ĺ—，认čŻä˝ 编写了ĺ®ć–者其他 -人有ćťĺŠ›ĺ°†ĺ®ä˝śä¸şĺĽ€ć”ľćşä»Łç 的补ä¸äĽ 递。规ĺ™ĺľç®€ĺŤ•ďĽšĺ¦‚ćžśä˝ č˝č®¤čŻĺ¦‚ä¸‹äżˇćŻ -： - 开发者来ćşčŻäą¦ 1.1 - 对于本项目的贡献，ć‘认čŻĺ¦‚下信ćŻďĽš - ďĽa）这些贡献ćŻĺ®Śĺ…¨ć–者é¨ĺ†çš„ç”±ć‘ĺ›ĺ»şďĽŚć‘有ćťĺ©ä»Ąć–‡ä»¶ä¸ćŚ‡ĺ‡ş - 的开放ćşä»Łç 许可čŻćŹäş¤ĺ®ďĽ›ć–者 - ďĽb）这些贡献基于以前的工作，据ć‘所知，这些以前的工作受ć°ĺ˝“的开放 - ćşä»Łç 许可čŻäżťćŠ¤ďĽŚč€Śä¸”ďĽŚć ąćŤ®č®¸ĺŹŻčŻďĽŚć‘有ćťćŹäş¤äż®ć”ąĺŽçš„贡献， - ć— č®şćŻĺ®Śĺ…¨čżćŻé¨ĺ†ç”±ć‘ĺ›é€ ，这些贡献é˝ä˝żç”¨ĺŚä¸€ä¸ŞĺĽ€ć”ľćşä»Łç č®¸ĺŹŻčŻ - ďĽé™¤éťžć‘被ĺ…许用其ĺ®çš„许可čŻďĽ‰ďĽŚćŁĺ¦‚文件ä¸ćŚ‡ĺ‡şçš„；ć–者 - ďĽc）这些贡献由认čŻďĽa），ďĽb）ć–者ďĽc）的人直接ćŹäľ›ç»™ć‘，而 - 且ć‘没有修改ĺ®ă€‚ - ďĽd）ć‘ç†č§Łĺą¶ĺŚć„Źčż™ä¸Şéˇąç›®ĺ’Śč´ˇçŚ®ćŻĺ…¬ĺĽ€çš„，贡献的记录ďĽĺŚ…ć‹¬ć‘ - 一起ćŹäş¤çš„个人记录，包括 sign-off ）被永久维护并且可以和这个项目 - ć–者开放ćşä»Łç 的许可čŻĺŚćĄĺś°ĺ†ŤĺŹ‘行。 - é‚ŁäąĺŠ ĺ…Ąčż™ć ·ä¸€čˇŚďĽš - Signed-off-by: Random J Developer <random@developer.example.org> - -ä˝żç”¨ä˝ çš„çśźĺŤďĽćŠ±ć‰ďĽŚä¸Ťč˝ä˝żç”¨ĺ‡ĺŤć–者匿ĺŤă€‚） - -有人在最ĺŽĺŠ ä¸Šć ‡çľă€‚现在这些东西会被忽略，但ćŻä˝ ĺŹŻä»Ąčż™ć ·ĺšďĽŚćťĄć ‡č®°ĺ…¬ĺŹ¸ -内é¨çš„过程，ć–者只ćŻćŚ‡ĺ‡şĺ…łäşŽ sign-off 的一些特殊细节。 - -12ďĽ‰ć ‡ĺ‡†čˇĄä¸ć ĽĺĽŹ - -ć ‡ĺ‡†çš„čˇĄä¸ďĽŚć ‡é˘čˇŚćŻďĽš - Subject: [PATCH 001/123] ĺ系统:一句话概述 - -ć ‡ĺ‡†čˇĄä¸çš„信体ĺ在如下é¨ĺ†ďĽš - - - 一个 "from" 行指出补ä¸ä˝śč€…。 - - - 一个空行 - - - 说ćŽçš„主体，这些说ćŽć–‡ĺ—会被拷贝ĺ°ćŹŹčż°čŻĄčˇĄä¸çš„永久改动记录里。 - - - 一个由"---"ćž„ćçš„ć ‡č®°čˇŚ - - - 不ĺ适放ĺ°ć”ąĺŠ¨č®°ĺ˝•é‡Śçš„额外的注解。 - - - 补ä¸ćś¬čş«ďĽdiff 输出） - -ć ‡é˘čˇŚçš„ć ĽĺĽŹďĽŚä˝żĺľ—ĺŻąć ‡é˘čˇŚćŚ‰ĺ—ćŻŤĺşŹćŽ’ĺşŹéťžĺ¸¸çš„ĺ®ąć“ - ĺľĺ¤š e-mail 客ć·ç«Żé˝ -ĺŹŻä»Ąć”ŻćŚ - ĺ› ä¸şĺşŹĺ—号ćŻç”¨é›¶ĺˇ«ĺ……的，所以按数ĺ—排序和按ĺ—母排序ćŻä¸€ć ·çš„。 - -e-mail ć ‡é˘ä¸çš„“ĺçł»ç»źâ€ťć ‡čŻ†ĺ“Şä¸Şĺ†…ć ¸ĺ系统将被打补ä¸ă€‚ - -e-mail ć ‡é˘ä¸çš„“一句话概述”扼č¦çš„描述 e-mail ä¸çš„补ä¸ă€‚“一句话概述” -不应该ćŻä¸€ä¸Şć–‡ä»¶ĺŤă€‚对于一个补ä¸çł»ĺ—ďĽâ€śčˇĄä¸çł»ĺ—”指一系ĺ—的多个相关补 -ä¸ďĽ‰ďĽŚä¸Ťč¦ĺŻąćŻŹä¸ŞčˇĄä¸é˝ä˝żç”¨ĺŚć ·çš„“一句话概述”。 - -记住 e-mail 的“一句话概述”会ć为该补ä¸çš„ĺ…¨ĺ±€ĺ”Żä¸€ć ‡čŻ†ă€‚ĺ®äĽšč”“ĺ»¶ĺ° git -的改动记录里。然ĺŽâ€śä¸€ĺŹĄčŻťć¦‚述”会被用在开发者的讨论里，用来指代这个补 -ä¸ă€‚用ć·ĺ°†ĺ¸Śćś›é€ščż‡ google 来ćśç´˘"一句话概述"来找ĺ°é‚Łäş›č®¨č®şčż™ä¸ŞčˇĄä¸çš„ć–‡ -ç« ă€‚ - -ä¸€äş›ć ‡é˘çš„äľ‹ĺ： - - Subject: [patch 2/5] ext2: improve scalability of bitmap searching - Subject: [PATCHv2 001/207] x86: fix eflags tracking - -"from" 行ćŻäżˇä˝“é‡Śçš„ćś€ä¸Šéť˘ä¸€čˇŚďĽŚĺ…·ćś‰ĺ¦‚ä¸‹ć ĽĺĽŹďĽš - From: Original Author <author@example.com> - -"from" 行指ćŽĺś¨ć°¸äą…改动日志里，č°äĽšč˘«çˇ®č®¤ä¸şä˝śč€…。如果没有 "from" 行，那 -äąé‚®ä»¶ĺ¤´é‡Śçš„ "From: " 行会被用来决定改动日志ä¸çš„作者。 - -说ćŽçš„主é˘ĺ°†äĽšč˘«ćŹäş¤ĺ°ć°¸äą…çš„ćşä»Łç ć”ąĺŠ¨ć—Ąĺż—é‡ŚďĽŚĺ› ć¤ĺŻąé‚Łäş›ć—©ĺ·˛ç»Źä¸Ťč®°ĺľ—ĺ’Ś -这个补ä¸ç›¸ĺ…łçš„讨论细节的有č˝ĺŠ›çš„读者来说，ćŻćś‰ć„Źäą‰çš„。 - -"---" ć ‡č®°čˇŚĺŻąäşŽčˇĄä¸ĺ¤„ç†ĺ·Ąĺ…·č¦ć‰ľĺ°ĺ“Şé‡ŚćŻć”ąĺŠ¨ć—Ąĺż—信ćŻçš„结束，ćŻä¸ŤĺŹŻçĽşĺ°‘ -的。 - -对于 "---" ć ‡č®°äą‹ĺŽçš„额外注解，一个好的用途就ćŻç”¨ćťĄĺ†™ diffstatďĽŚç”¨ćťĄćľ -示修改了什äąć–‡ä»¶ĺ’ŚćŻŹä¸Şć–‡ä»¶é˝ĺ˘žĺŠ ĺ’Śĺ 除了多少行。diffstat 对于比čľĺ¤§çš„补 -ä¸ç‰ąĺ«ćś‰ç”¨ă€‚其余那些只ćŻĺ’Ść—¶ĺ»ć–者开发者相关的注解，不ĺ适放ĺ°ć°¸äą…的改 -动日志里的，也应该放这里。 -使用 diffstat的选项 "-p 1 -w 70" čż™ć ·ć–‡ä»¶ĺŤĺ°±äĽšä»Žĺ†…ć ¸ćşä»Łç ć ‘çš„ç›®ĺ˝•ĺĽ€ĺ§‹ -ďĽŚä¸ŤäĽšĺŤ ç”¨ĺ¤Şĺ®˝çš„ç©şé—´ďĽĺľĺ®ąć“适ĺ80ĺ—的宽度，也许会有一些缩进。） - -在ĺŽéť˘çš„参č€čµ„ć–™ä¸č˝çś‹ĺ°é€‚当的补ä¸ć ĽĺĽŹçš„更多细节。 - -------------------------------- -第二节 ćŹç¤şďĽŚĺ»şč®®ĺ’ŚčŻ€çŞŤ -------------------------------- - -本节包ĺ«ĺľĺ¤šĺ’ŚćŹäş¤ĺ°ĺ†…ć ¸çš„ä»Łç 有关的通常的"规ĺ™"。事ć…永远有例外...ä˝†ćŻ -ä˝ ĺż…éˇ»çśźçš„ćś‰ĺĄ˝çš„ç†ç”±čż™ć ·ĺšă€‚ä˝ ĺŹŻä»ĄćŠŠćś¬čŠ‚ĺŹ«ĺšLinus的计算机科ĺ¦ĺ…Ąé—¨čŻľă€‚ - -1) 读 Document/process/coding-style.rst - -Nuff čŻ´čż‡ďĽŚĺ¦‚ćžśä˝ çš„ä»Łç 和这个ĺŹç¦»ĺ¤Şĺ¤šďĽŚé‚Łäąĺ®ćś‰ĺŹŻč˝äĽšč˘«ć‹’绝，没有更多的 -审查，没有更多的评价。 - -2) #ifdef ćŻä¸‘陋的 -混杂了 ifdef 的代ç 难以é…读和维护。ĺ«čż™ć ·ĺšă€‚ä˝śä¸şć›żä»ŁďĽŚĺ°†ä˝ çš„ ifdef 放 -在头文件里，有条件地定义 "static inline" 函数，ć–者宏，在代ç 里用这些东 -西。让编译器把那些"空操作"äĽĺŚ–掉。 - -一个简单的例ĺ，不好的代ç ： - - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - #ifdef CONFIG_NET_FUNKINESS - init_funky_net(dev); - #endif - -清ç†ĺŽçš„äľ‹ĺ: - -(头文件里) - #ifndef CONFIG_NET_FUNKINESS - static inline void init_funky_net (struct net_device *d) {} - #endif - -(代ç 文件里) - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - init_funky_net(dev); - -3) 'static inline' 比宏好 - -Static inline 函数相比宏来说，ćŻĺĄ˝ĺľ—多的选择。Static inline 函数ćŹäľ›äş† -类型安全，没有长度é™ĺ¶ďĽŚć˛ˇćś‰ć ĽĺĽŹé™ĺ¶ďĽŚĺś¨ gcc ä¸‹ĺĽ€é”€ĺ’Śĺ®Źä¸€ć ·ĺ°Źă€‚ - -宏只在 static inline 函数不ćŻćś€äĽçš„时候[在 fast paths 里有ĺľĺ°‘的独立的 -ćˇäľ‹]，ć–者不可č˝ç”¨ static inline 函数的时候[例如ĺ—符串ĺ†é…Ť]。 -应该用 'static inline' č€Śä¸ŤćŻ 'static __inline__', 'extern inline' ĺ’Ś -'extern __inline__' 。 - -4) 不č¦čż‡ĺş¦č®ľč®ˇ - -不č¦čŻ•ĺ›ľé˘„计模糊的未来事ć…，这些事ć…也许有用也许没有用："让事ć…尽可č˝çš„ -简单，而不ćŻć›´ç®€ĺŤ•"。 - ----------------- -第三节 参č€ć–‡çŚ® ----------------- - -Andrew Morton, "The perfect patch" (tpp). - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> - -Jeff Garzik, "Linux kernel patch submission format". - <http://linux.yyz.us/patch-format.html> - -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". - <http://www.kroah.com/log/2005/03/31/> - <http://www.kroah.com/log/2005/07/08/> - <http://www.kroah.com/log/2005/10/19/> - <http://www.kroah.com/log/2006/01/11/> - -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! - <https://lkml.org/lkml/2005/7/11/336> - -Kernel Documentation/process/coding-style.rst: - <http://sosdg.org/~coywolf/lxr/source/Documentation/process/coding-style.rst> - -Linus Torvalds's mail on the canonical patch format: - <http://lkml.org/lkml/2005/4/7/183> --- diff --git a/Documentation/translations/zh_CN/disclaimer-zh_CN.rst b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst new file mode 100644 index 000000000000..dcf803ede85a --- /dev/null +++ b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst @@ -0,0 +1,9 @@ +:orphan: + +.. warning:: + ć¤ć–‡ä»¶çš„目的ćŻä¸şč®©ä¸ć–‡čŻ»č€…更容ć“é…读和ç†č§ŁďĽŚč€Śä¸ŤćŻä˝śä¸şä¸€ä¸Şĺ†ć”Żă€‚ ĺ› ć¤ďĽŚ + 如果您对ć¤ć–‡ä»¶ćś‰ä»»ä˝•ć„Źč§ć–更新，请ĺ…尝试更新原始英文文件。 + +.. note:: + 如果您发现本文档与原始文件有任何不ĺŚć–者有翻译问é˘ďĽŚčŻ·č”系该文件的译者， + ć–者请求时奎亮的帮助：<alex.shi@linux.alibaba.com>。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 75956d669962..d3165535ec9e 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -3,10 +3,19 @@ \renewcommand\thesection* \renewcommand\thesubsection* -Chinese translations -==================== +ä¸ć–‡çż»čŻ‘ +======== + +这些手册包ĺ«ćś‰ĺ…łĺ¦‚ä˝•ĺĽ€ĺŹ‘ĺ†…ć ¸çš„ć•´ä˝“äżˇćŻă€‚ĺ†…ć ¸ç¤ľĺŚşéťžĺ¸¸ĺşžĺ¤§ďĽŚä¸€ĺą´ä¸‹ćťĄćś‰ć•°ĺŤĺŤĺĽ€ĺŹ‘ +äşşĺ‘ĺšĺ‡şč´ˇçŚ®ă€‚ ä¸Žä»»ä˝•ĺ¤§ĺž‹ç¤ľĺŚşä¸€ć ·ďĽŚçźĄé“如何完ć任务将使得更改ĺ并的过程ĺŹĺľ—ć›´ +ĺŠ ĺ®ąć“。 .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + + process/index + +ç›®ĺ˝•ĺ’Śčˇ¨ć Ľ +---------- - coding-style +* :ref:`genindex` diff --git a/Documentation/translations/zh_CN/magic-number.txt b/Documentation/translations/zh_CN/magic-number.txt deleted file mode 100644 index 7159cec04090..000000000000 --- a/Documentation/translations/zh_CN/magic-number.txt +++ /dev/null @@ -1,153 +0,0 @@ -Chinese translated version of Documentation/process/magic-number.rst - -If you have any comment or update to the content, please post to LKML directly. -However, if you have problem communicating in English you can also ask the -Chinese maintainer for help. Contact the Chinese maintainer, if this -translation is outdated or there is problem with translation. - -Chinese maintainer: Jia Wei Wei <harryxiyou@gmail.com> ---------------------------------------------------------------------- -Documentation/process/magic-number.rstçš„ä¸ć–‡çż»čŻ‘ - -如果ćłčŻ„论ć–更新本文的内容，请直接发信ĺ°LKMLă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡äş¤ćµćś‰ĺ›°éšľçš„话，也可 -以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 - -ä¸ć–‡ç‰ç»´ćŠ¤č€…： č´ľĺ¨ĺ¨ Jia Wei Wei <harryxiyou@gmail.com> -ä¸ć–‡ç‰çż»čŻ‘者： č´ľĺ¨ĺ¨ Jia Wei Wei <harryxiyou@gmail.com> -ä¸ć–‡ç‰ć ˇčŻ‘者： č´ľĺ¨ĺ¨ Jia Wei Wei <harryxiyou@gmail.com> - -以下为ćŁć–‡ ---------------------------------------------------------------------- -这个文件ćŻćś‰ĺ…łĺ˝“前使用的é”ćśŻĺ€Ľćł¨ĺ†Śčˇ¨ă€‚ĺ˝“ä˝ ç»™ä¸€ä¸Şç»“ćž„ć·»ĺŠ äş†ä¸€ä¸Şé”ćśŻĺ€ĽďĽŚä˝ äąźĺş”čŻĄćŠŠčż™ä¸Şé”ćśŻĺ€Ľć·»ĺŠ ĺ°čż™ä¸Şć–‡ä»¶ďĽŚĺ› 为ć‘们最好把用于ĺ„种结构的é”术值统一起来。 - -使用é”ćśŻĺ€ĽćťĄäżťćŠ¤ĺ†…ć ¸ć•°ćŤ®ç»“ćž„ćŻä¸€ä¸Şéťžĺ¸¸ĺĄ˝çš„主意。这就ĺ…č®¸ä˝ ĺś¨čżčˇŚćśźćŁ€ćźĄ(a)一个结构ćŻĺ¦ĺ·˛ç»Źč˘«ć”»ĺ‡»ďĽŚć–者(b)ä˝ ĺ·˛ç»Źç»™ä¸€ä¸Şäľ‹čˇŚç¨‹ĺşŹé€ščż‡äş†ä¸€ä¸Şé”™čŻŻçš„ç»“ćž„ă€‚ĺŽä¸€ç§Ťć…况特ĺ«ĺś°ćś‰ç”¨---特ĺ«ćŻĺ˝“ä˝ é€ščż‡ä¸€ä¸Şç©şćŚ‡é’指ĺ‘结构体的时候。ttyćşç ，例如，经常通过特定驱动使用这种方法并且反复地排ĺ—特定方面的结构。 - -使用é”术值的方法ćŻĺś¨ç»“构的开始处声ćŽçš„，如下： - -struct tty_ldisc { - int magic; - ... -}; - -ĺ˝“ä˝ ä»ĄĺŽç»™ĺ†…ć ¸ć·»ĺŠ ĺ˘žĺĽşĺŠźč˝çš„时候，请éµĺ®čż™ćťˇč§„ĺ™ďĽčż™ć ·ĺ°±äĽščŠ‚çść•°ä¸Ťć¸…çš„č°čŻ•ć—¶é—´ďĽŚç‰ąĺ«ćŻä¸€äş›ĺŹ¤ć€Şçš„ć…况，例如，数组超出čŚĺ›´ĺą¶ä¸”重新写了超出é¨ĺ†ă€‚éµĺ®čż™ä¸Şč§„ĺ™ďĽŚâ€Şčż™äş›ć…况可以被快速地，安全地éżĺ…Ťă€‚ - - Theodore Ts'o - 31 Mar 94 - -给当前的Linux 2.1.55ć·»ĺŠ é”术表。 - - Michael Chastain - <mailto:mec@shout.net> - 22 Sep 1997 - -现在应该最新的Linux 2.1.112.ĺ› ä¸şĺś¨ç‰ąć€§ĺ†»ç»“ćśźé—´ďĽŚä¸Ťč˝ĺś¨2.2.x前改ĺŹä»»ä˝•ä¸śčĄżă€‚这些条目被数域所排序。 - - Krzysztof G.Baranowski - <mailto: kgb@knm.org.pl> - 29 Jul 1998 - -ć›´ć–°é”术表ĺ°Linux 2.5.45。ĺšĺĄ˝č¶Ščż‡ç‰ąć€§ĺ†»ç»“，但ćŻćś‰ĺŹŻč˝čżäĽšćś‰ä¸€äş›ć–°çš„é”术值在2.6.x之前融入ĺ°ĺ†…ć ¸ä¸ă€‚ - - Petr Baudis - <pasky@ucw.cz> - 03 Nov 2002 - -ć›´ć–°é”术表ĺ°Linux 2.5.74。 - - Fabian Frederick - <ffrederick@users.sourceforge.net> - 09 Jul 2003 - -é”ćśŻĺŤ ĺś°ĺť€ 结构 所在文件 -=========================================================================== -PG_MAGIC 'P' pg_{read,write}_hdr include/linux/pg.h -CMAGIC 0x0111 user include/linux/a.out.h -MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h -HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c -APM_BIOS_MAGIC 0x4101 apm_user arch/x86/kernel/apm_32.c -CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h -DB_MAGIC 0x4442 fc_info drivers/net/iph5526_novram.c -DL_MAGIC 0x444d fc_info drivers/net/iph5526_novram.c -FASYNC_MAGIC 0x4601 fasync_struct include/linux/fs.h -FF_MAGIC 0x4646 fc_info drivers/net/iph5526_novram.c -ISICOM_MAGIC 0x4d54 isi_port include/linux/isicom.h -PTY_MAGIC 0x5001 drivers/char/pty.c -PPP_MAGIC 0x5002 ppp include/linux/if_pppvar.h -SERIAL_MAGIC 0x5301 async_struct include/linux/serial.h -SSTATE_MAGIC 0x5302 serial_state include/linux/serial.h -SLIP_MAGIC 0x5302 slip drivers/net/slip.h -STRIP_MAGIC 0x5303 strip drivers/net/strip.c -X25_ASY_MAGIC 0x5303 x25_asy drivers/net/x25_asy.h -SIXPACK_MAGIC 0x5304 sixpack drivers/net/hamradio/6pack.h -AX25_MAGIC 0x5316 ax_disp drivers/net/mkiss.h -TTY_MAGIC 0x5401 tty_struct include/linux/tty.h -MGSL_MAGIC 0x5401 mgsl_info drivers/char/synclink.c -TTY_DRIVER_MAGIC 0x5402 tty_driver include/linux/tty_driver.h -MGSLPC_MAGIC 0x5402 mgslpc_info drivers/char/pcmcia/synclink_cs.c -TTY_LDISC_MAGIC 0x5403 tty_ldisc include/linux/tty_ldisc.h -USB_SERIAL_MAGIC 0x6702 usb_serial drivers/usb/serial/usb-serial.h -FULL_DUPLEX_MAGIC 0x6969 drivers/net/ethernet/dec/tulip/de2104x.c -USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth drivers/usb/class/bluetty.c -RFCOMM_TTY_MAGIC 0x6d02 net/bluetooth/rfcomm/tty.c -USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port drivers/usb/serial/usb-serial.h -CG_MAGIC 0x00090255 ufs_cylinder_group include/linux/ufs_fs.h -RPORT_MAGIC 0x00525001 r_port drivers/char/rocket_int.h -LSEMAGIC 0x05091998 lse drivers/fc4/fc.c -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str drivers/scsi/gdth_ioctl.h -RIEBL_MAGIC 0x09051990 drivers/net/atarilance.c -NBD_REQUEST_MAGIC 0x12560953 nbd_request include/linux/nbd.h -RED_MAGIC2 0x170fc2a5 (any) mm/slab.c -BAYCOM_MAGIC 0x19730510 baycom_state drivers/net/baycom_epp.c -ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data - drivers/isdn/isdn_x25iface.h -ECP_MAGIC 0x21504345 cdkecpsig include/linux/cdk.h -LSOMAGIC 0x27091997 lso drivers/fc4/fc.c -LSMAGIC 0x2a3b4d2a ls drivers/fc4/fc.c -WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} include/linux/wanpipe.h -CS_CARD_MAGIC 0x43525553 cs_card sound/oss/cs46xx.c -LABELCL_MAGIC 0x4857434c labelcl_info_s include/asm/ia64/sn/labelcl.h -ISDN_ASYNC_MAGIC 0x49344C01 modem_info include/linux/isdn.h -CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info drivers/s390/net/ctctty.c -ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s drivers/isdn/i4l/isdn_net_lib.h -SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg arch/*/amiga/config.c -CS_STATE_MAGIC 0x4c4f4749 cs_state sound/oss/cs46xx.c -SLAB_C_MAGIC 0x4f17a36d kmem_cache mm/slab.c -COW_MAGIC 0x4f4f4f4d cow_header_v1 arch/um/drivers/ubd_user.c -I810_CARD_MAGIC 0x5072696E i810_card sound/oss/i810_audio.c -TRIDENT_CARD_MAGIC 0x5072696E trident_card sound/oss/trident.c -ROUTER_MAGIC 0x524d4157 wan_device [in wanrouter.h pre 3.9] -SAVEKMSG_MAGIC1 0x53415645 savekmsg arch/*/amiga/config.c -GDA_MAGIC 0x58464552 gda arch/mips/include/asm/sn/gda.h -RED_MAGIC1 0x5a2cf071 (any) mm/slab.c -EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev drivers/atm/lanai.c -HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state include/linux/hdlcdrv.h -PCXX_MAGIC 0x5c6df104 channel drivers/char/pcxx.h -KV_MAGIC 0x5f4b565f kernel_vars_s arch/mips/include/asm/sn/klkernvars.h -I810_STATE_MAGIC 0x63657373 i810_state sound/oss/i810_audio.c -TRIDENT_STATE_MAGIC 0x63657373 trient_state sound/oss/trident.c -M3_CARD_MAGIC 0x646e6f50 m3_card sound/oss/maestro3.c -FW_HEADER_MAGIC 0x65726F66 fw_header drivers/atm/fore200e.h -SLOT_MAGIC 0x67267321 slot drivers/hotplug/cpqphp.h -SLOT_MAGIC 0x67267322 slot drivers/hotplug/acpiphp.h -LO_MAGIC 0x68797548 nbd_device include/linux/nbd.h -OPROFILE_MAGIC 0x6f70726f super_block drivers/oprofile/oprofilefs.h -M3_STATE_MAGIC 0x734d724d m3_state sound/oss/maestro3.c -VMALLOC_MAGIC 0x87654320 snd_alloc_track sound/core/memory.c -KMALLOC_MAGIC 0x87654321 snd_alloc_track sound/core/memory.c -PWC_MAGIC 0x89DC10AB pwc_device drivers/usb/media/pwc.h -NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h -ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h -CODA_MAGIC 0xC0DAC0DA coda_file_info include/linux/coda_fs_i.h -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h -YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c -CCB_MAGIC 0xf2691ad2 ccb drivers/scsi/ncr53c8xx.c -QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry drivers/scsi/arm/queue.c -QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry drivers/scsi/arm/queue.c -HTB_CMAGIC 0xFEFAFEF1 htb_class net/sched/sch_htb.c -NMI_MAGIC 0x48414d4d455201 nmi_s arch/mips/include/asm/sn/nmi.h - -请注意，在声音记忆管ç†ä¸ä»Ťç„¶ćś‰ä¸€äş›ç‰ąć®Šçš„为每个驱动定义的é”术值。查看include/sound/sndmagic.h来获取他们完整的ĺ—表信ćŻă€‚ĺľĺ¤šOSS声音驱动拥有自己从声卡PCI ID构建的é”术值-他们也没有被ĺ—在这里。 - -IrDAĺ系统也使用了大量的自己的é”术值，查看include/net/irda/irda.h来获取他们完整的信ćŻă€‚ - -HFSćŻĺŹ¦ĺ¤–一个比čľĺ¤§çš„使用é”术值的文件系统-ä˝ ĺŹŻä»Ąĺś¨fs/hfs/hfs.hä¸ć‰ľĺ°ä»–们。 diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt index a893f04dfd5d..93fa061cf9e4 100644 --- a/Documentation/translations/zh_CN/oops-tracing.txt +++ b/Documentation/translations/zh_CN/oops-tracing.txt @@ -16,7 +16,7 @@ Documentation/admin-guide/bug-hunting.rst çš„ä¸ć–‡çż»čŻ‘ ä¸ć–‡ç‰ç»´ćŠ¤č€…： 杨瑞 Dave Young <hidave.darkstar@gmail.com> ä¸ć–‡ç‰çż»čŻ‘者： 杨瑞 Dave Young <hidave.darkstar@gmail.com> -ä¸ć–‡ç‰ć ˇčŻ‘者： ćťŽéł Li Yang <leo@zh-kernel.org> +ä¸ć–‡ç‰ć ˇčŻ‘者： ćťŽéł Li Yang <leoyang.li@nxp.com> çŽ‹čŞ Wang Cong <xiyou.wangcong@gmail.com> 以下为ćŁć–‡ diff --git a/Documentation/translations/zh_CN/process/1.Intro.rst b/Documentation/translations/zh_CN/process/1.Intro.rst new file mode 100644 index 000000000000..10a15f3dc282 --- /dev/null +++ b/Documentation/translations/zh_CN/process/1.Intro.rst @@ -0,0 +1,186 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/1.Intro.rst <development_process_intro>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_process_intro: + +介绍 +==== + +执行ć‘č¦ +-------- + +本节的其余é¨ĺ†ć¶µç›–äş†ĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹çš„čŚĺ›´ďĽŚä»ĄĺŹŠĺĽ€ĺŹ‘äşşĺ‘及其雇主在这方面可č˝é‡ +ĺ°çš„ĺ„种挫ćŠă€‚ĺ†…ć ¸ä»Łç 应该ĺ并ĺ°ćŁĺĽŹçš„ďĽâ€śä¸»çşżâ€ťďĽ‰ĺ†…ć ¸ä¸ćś‰ĺľĺ¤šĺŽźĺ› ，包括对用 +ć·çš„自动可用性ă€ĺ¤šç§Ťĺ˝˘ĺĽŹçš„社区支ćŚä»ĄĺŹŠĺ˝±ĺ“Ťĺ†…ć ¸ĺĽ€ĺŹ‘ć–ąĺ‘çš„č˝ĺŠ›ă€‚ćŹäľ›ç»™Linux +ĺ†…ć ¸çš„ä»Łç 必须在与GPL兼容的许可čŻä¸‹ĺŹŻç”¨ă€‚ + +:ref:`cn_development_process` 介绍了开发过程ă€ĺ†…ć ¸ĺŹ‘ĺ¸ĺ‘¨ćśźĺ’Śĺ并窗口的机ĺ¶ă€‚ +涵盖了补ä¸ĺĽ€ĺŹ‘ă€ĺ®ˇćźĄĺ’Śĺ并周期ä¸çš„ĺ„个é¶ć®µă€‚有一些关于工具和邮件ĺ—表的讨论。 +éĽ“ĺŠ±ĺ¸Śćś›ĺĽ€ĺ§‹ĺ†…ć ¸ĺĽ€ĺŹ‘çš„ĺĽ€ĺŹ‘äşşĺ‘作为ĺťĺ§‹ç»äą 跟踪并修复bug。 + + +:ref:`cn_development_early_stage` 包括早期项目规ĺ’，重点ćŻĺ°˝ĺż«č®©ĺĽ€ĺŹ‘社区参与 + +:ref:`cn_development_coding` ćŻĺ…łäşŽçĽ–ç 过程的；讨论了其他开发人ĺ‘é‡ĺ°çš„ĺ‡ ä¸Ş +é™·é±ă€‚对补ä¸çš„一些č¦ć±‚ĺ·˛ç»Źć¶µç›–ďĽŚĺą¶ä¸”ä»‹ç»Ťäş†ä¸€äş›ĺ·Ąĺ…·ďĽŚčż™äş›ĺ·Ąĺ…·ćś‰ĺŠ©äşŽçˇ®äżťĺ†…ć ¸ +补ä¸ćŻćŁçˇ®çš„。 + +:ref:`cn_development_posting` 讨论发ĺ¸čˇĄä¸ä»Ąäľ›čŻ„审的过程。为了让开发社区 +认真对待，补ä¸ĺż…须ćŁçˇ®ć ĽĺĽŹĺŚ–和描述，并且必须发é€ĺ°ćŁçˇ®çš„地方。éµĺľŞćś¬čŠ‚ä¸çš„ +建议有助于确保为您的工作ćŹäľ›ćś€ĺĄ˝çš„接纳。 + +:ref:`cn_development_followthrough` 介绍了发ĺ¸čˇĄä¸äą‹ĺŽĺŹ‘生的事ć…；该工作 +在这一点上čżčżśčżść˛ˇćś‰ĺ®Ść。与审é…者一起工作ćŻĺĽ€ĺŹ‘过程ä¸çš„一个重č¦é¨ĺ†ďĽ›ćś¬čŠ‚ +ćŹäľ›äş†ä¸€äş›ĺ…łäşŽĺ¦‚何在这个重č¦é¶ć®µéżĺ…Ťé—®é˘çš„ćŹç¤şă€‚当补ä¸č˘«ĺ并ĺ°ä¸»çşżä¸ć—¶ďĽŚ +开发人ĺ‘č¦ćł¨ć„Źä¸Ťč¦ĺ‡ĺ®šä»»ĺŠˇĺ·˛ç»Źĺ®Ść。 + +:ref:`cn_development_advancedtopics` 介绍了两个“é«çş§â€ťä¸»é˘ďĽš +使用Git管ç†čˇĄä¸ĺ’ŚćźĄçś‹ĺ…¶ä»–人发ĺ¸çš„补ä¸ă€‚ + +:ref:`cn_development_conclusion` ć€»ç»“äş†ćś‰ĺ…łĺ†…ć ¸ĺĽ€ĺŹ‘çš„ć›´ĺ¤šäżˇćŻďĽŚé™„带有带有 +指ĺ‘资ćşçš„链接. + +这个文件ćŻĺ…łäşŽä»€äąçš„ +-------------------- + +Linuxĺ†…ć ¸ćś‰č¶…čż‡800万行代ç ，每个ç‰ćś¬çš„贡献者超过1000人，ćŻçŽ°ĺ最大ă€ćś€ć´»č· +的免费软件项目之一。从1991ĺą´ĺĽ€ĺ§‹ďĽŚčż™ä¸Şĺ†…ć ¸ĺ·˛ç»ŹĺŹ‘ĺ±•ć为一个最好的操作系统 +组件，čżčˇŚĺś¨č˘–珍数ĺ—éźłäąć’放器ă€ĺŹ°ĺĽŹPCă€çŽ°ĺ最大的超级计算机以及所有类型的 +系统上。ĺ®ćŻä¸€ç§Ťé€‚ç”¨äşŽĺ‡ äąŽä»»ä˝•ć…况的ĺĄĺŁ®ă€é«ć•ĺ’ŚĺŹŻć‰©ĺ±•çš„解决方ćˇă€‚ + +随着Linux的发展，希望参与其开发的开发人ĺ‘ďĽĺ’Śĺ…¬ĺŹ¸ďĽ‰çš„ć•°é‡Źäąźĺś¨ĺ˘žĺŠ ă€‚çˇ¬ä»¶äľ›ĺş”ĺ•† +希望确保Linuxč˝ĺ¤źĺľĺĄ˝ĺś°ć”ŻćŚä»–们的产ĺ“，使这些产ĺ“对Linux用ć·ĺ…·ćś‰ĺ¸ĺĽ•ĺŠ›ă€‚嵌入 +式系统供应商使用Linux作为集ć产ĺ“的组件，希望Linuxč˝ĺ¤źĺ°˝ĺŹŻč˝ĺś°čśä»»ć‰‹ĺ¤´çš„任务。 +ĺ†é”€ĺ•†ĺ’Śĺ…¶ä»–基于Linux的软件供应商对Linuxĺ†…ć ¸çš„ĺŠźč˝ă€ć€§č˝ĺ’ŚĺŹŻéť 性有着ćŽçˇ®çš„ +兴趣。最ç»ç”¨ć·äąźĺ¸¸ĺ¸¸ĺ¸Śćś›äż®ć”ąLinux，使之更好地满足他们的需求。 + +Linux最引人注目的特性之一ćŻčż™äş›ĺĽ€ĺŹ‘äşşĺ‘可以访问ĺ®ďĽ›ä»»ä˝•ĺ…·ĺ¤‡ĺż…č¦ćŠ€č˝çš„äşşé˝ĺŹŻä»Ą +改进Linux并影响其开发方ĺ‘。专有产ĺ“不č˝ćŹäľ›čż™ç§ŤĺĽ€ć”ľć€§ďĽŚčż™ćŻč‡Şç”±č˝Żä»¶çš„一个特点。 +但ćŻďĽŚĺ¦‚果有什äąä¸ŤĺŚçš„čŻťďĽŚĺ†…ć ¸ćŻ”ĺ¤§ĺ¤šć•°ĺ…¶ä»–č‡Şç”±č˝Żä»¶éˇąç›®ć›´ĺĽ€ć”ľă€‚ä¸€ä¸Şĺ…¸ĺž‹çš„ä¸‰ä¸Şćś +ĺ†…ć ¸ĺĽ€ĺŹ‘ĺ‘¨ćśźĺŹŻä»Ąć¶‰ĺŹŠ1000多个开发人ĺ‘，他们为100多个不ĺŚçš„公司 +ďĽć–č€…ć ąćś¬ć˛ˇćś‰ĺ…¬ĺŹ¸ďĽ‰ĺ·Ąä˝śă€‚ + +ä¸Žĺ†…ć ¸ĺĽ€ĺŹ‘ç¤ľĺŚşĺ作并不ćŻç‰ąĺ«ĺ›°éšľă€‚但ćŻďĽŚĺ°˝ç®ˇĺ¦‚ć¤ďĽŚč®¸ĺ¤šć˝śĺś¨çš„č´ˇçŚ®č€…ĺś¨ĺ°ťčŻ•ĺš +ĺ†…ć ¸ĺ·Ąä˝ść—¶é‡ĺ°äş†ĺ›°éšľă€‚ĺ†…ć ¸ç¤ľĺŚşĺ·˛ç»ŹĺŹ‘ĺ±•äş†č‡Şĺ·±ç‹¬ç‰ąçš„ć“Ťä˝ść–ąĺĽŹďĽŚä˝żĺ…¶č˝ĺ¤źĺś¨ćŻŹĺ¤© +é˝č¦ć›´ć”ąć•°ĺŤčˇŚä»Łç 的环ĺ˘ä¸éˇşĺ©čżčˇŚďĽĺą¶ç”źćé«č´¨é‡Źçš„产ĺ“ďĽ‰ă€‚ĺ› ć¤ďĽŚLinuxĺ†…ć ¸ĺĽ€ĺŹ‘ +过程与专有的开发方法有ĺľĺ¤§çš„不ĺŚäąźĺ°±ä¸Ťč¶łä¸şĺĄ‡äş†ă€‚ + +对于新开发人ĺ‘ćťĄčŻ´ďĽŚĺ†…ć ¸çš„ĺĽ€ĺŹ‘čż‡ç¨‹ĺŹŻč˝äĽšč®©äşşć„źĺ°ĺĄ‡ć€Şĺ’Śćć§ďĽŚä˝†čż™ä¸ŞčŚĺŽćś‰ĺ……ĺ†çš„ +ç†ç”±ĺ’Śĺťšĺ®žçš„ç»ŹéŞŚă€‚ä¸€ä¸Şä¸Ťäş†č§Łĺ†…ć ¸ç¤ľĺŚşçš„ć–ąĺĽŹçš„ĺĽ€ĺŹ‘äşşĺ‘ďĽć–者更糟的ćŻďĽŚä»–们试图 +抛ĺĽć–规éżĺ†…ć ¸ç¤ľĺŚşçš„ć–ąĺĽŹďĽ‰äĽšćś‰ä¸€ä¸Şä»¤äşşć˛®ä¸§çš„ä˝“éŞŚă€‚ĺĽ€ĺŹ‘ç¤ľĺŚş, 在帮助那些试图ĺ¦äą +çš„äşşçš„ĺŚć—¶ďĽŚć˛ˇćś‰ć—¶é—´ĺ¸®ĺŠ©é‚Łäş›ä¸Ťć„żć„Źĺ€ľĺ¬ć–不关ĺżĺĽ€ĺŹ‘过程的人。 + +希望é…读本文的人č˝ĺ¤źéżĺ…Ťčż™ç§Ťä»¤äşşć˛®ä¸§çš„经历。这里有ĺľĺ¤šćťć–™ďĽŚä˝†é…读时所ĺšçš„ +努力会在çźć—¶é—´ĺ†…ĺľ—ĺ°ĺ›žćŠĄă€‚开发社区总ćŻéś€č¦č˝č®©ĺ†…ć ¸ĺŹć›´ĺĄ˝çš„开发人ĺ‘；下面的 +文本应该帮助您ć–为您工作的人ĺ‘ĺŠ ĺ…Ąć‘们的社区。 + +致谢 +---- + +本文件由Jonathan Corbet撰写，corbet@lwn.net。以下人ĺ‘的建议使之更为完善： +Johannes Berg, James Berry, Alex Chiang, Roland Dreier, Randy Dunlap, +Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, Amanda McPherson, +Andrew Morton, Andrew Price, Tsugikazu Shibata, ĺ’Ś Jochen VoĂź. + +这项工作得ĺ°äş†Linux基金会的支ćŚďĽŚç‰ąĺ«ć„źč°˘Amanda McPherson，他看ĺ°äş†čż™éˇąĺ·Ąä˝ś +的价值并把ĺ®ĺŹć现实。 + +代ç 进入主线的重č¦ć€§ +-------------------- + +有些公司和开发人ĺ‘ĺ¶ĺ°”会ćłďĽŚä¸şä»€äąä»–们č¦č´ąĺżĺ¦äą ĺ¦‚ä˝•ä¸Žĺ†…ć ¸ç¤ľĺŚşĺ作，并将代ç +ć”ľĺ…Ąä¸»çşżĺ†…ć ¸ďĽâ€śä¸»çşżâ€ťćŻç”±Linus Torvaldsç»´ćŠ¤çš„ĺ†…ć ¸ďĽŚLinux发行商将其用作基础）。 +在çźćśźĺ†…，贡献代ç 看起来ĺŹćŻä¸€ç§ŤĺŹŻä»Ąéżĺ…Ťçš„开销；仅仅将代ç ĺ†ĺĽ€ĺą¶ç›´ćŽĄć”ŻćŚç”¨ć· +似乎更容ć“。事实上，保ćŚä»Łç 独立ďĽâ€ść ‘外”）ćŻĺś¨ç»ŹćµŽä¸ŠćŻé”™čŻŻçš„。 + +作为说ćŽć ‘外代ç ć本的一种方法，下面ćŻĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹çš„ä¸€äş›ç›¸ĺ…łć–ąéť˘ďĽ›ćś¬ć–‡ç¨ŤĺŽĺ°† +更详细地讨论其ä¸çš„大é¨ĺ†ĺ†…容。č€č™‘： + +- 所有Linux用ć·é˝ĺŹŻä»Ąä˝żç”¨ĺ并ĺ°ä¸»çşżĺ†…ć ¸ä¸çš„代ç 。ĺ®ĺ°†č‡ŞĺŠ¨ĺ‡şçŽ°ĺś¨ć‰€ćś‰ĺŻç”¨ĺ®çš„ + 发行ç‰ä¸Šă€‚不需č¦é©±ĺŠ¨ç¨‹ĺşŹçŁç›ă€ä¸‹č˝˝ďĽŚäąźä¸Ťéś€č¦ä¸şĺ¤šä¸ŞĺŹ‘行ç‰çš„多个ç‰ćś¬ćŹäľ›ć”ŻćŚďĽ› + 对于开发人ĺ‘和用ć·ćťĄčŻ´ďĽŚčż™ä¸€ĺ‡é˝ćŻĺŹŻčˇŚçš„。并入主线解决了大量的ĺ†ĺ¸ĺ’Ść”ŻćŚé—®é˘ + +- ĺ˝“ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘努力维护一个稳定的用ć·ç©şé—´ćŽĄĺŹŁć—¶ďĽŚĺ†…é¨ĺ†…ć ¸API处于不ć–ĺŹĺŚ–äą‹ä¸. + 缺乏一个稳定的内é¨ćŽĄĺŹŁćŻä¸€ä¸Şć·±ć€ťç†źč™‘的设计决ç–；ĺ®ĺ…许在任何时候进行基本的改 + 进，并产生更é«č´¨é‡Źçš„代ç 。但该ç–略的一个结果ćŻďĽŚĺ¦‚ćžśč¦ä˝żç”¨ć–°çš„ĺ†…ć ¸ďĽŚä»»ä˝•ć ‘ĺ¤– + 代ç é˝éś€č¦ćŚç»çš„ç»´ćŠ¤ă€‚ç»´ćŠ¤ć ‘ĺ¤–ä»Łç 需č¦ĺ¤§é‡Źçš„工作才č˝ä˝żä»Łç äżťćŚĺ·Ąä˝śçŠ¶ć€ă€‚ + + 相反，位于主线ä¸çš„代ç 不需č¦čż™ć ·ĺšďĽŚĺ› 为一个简单的规ĺ™č¦ć±‚进行API更改的任何 + 开发人ĺ‘äąźĺż…éˇ»äż®ĺ¤Ťç”±äşŽčŻĄć›´ć”ąč€Śç ´ĺťŹçš„ä»»ä˝•ä»Łç ă€‚ĺ› ć¤ďĽŚĺ并ĺ°ä¸»çşżä¸çš„代ç 大大 + 降低了维护ć本。 + +- 除ć¤äą‹ĺ¤–ďĽŚĺ†…ć ¸ä¸çš„代ç 通常会被其他开发人ĺ‘改进。令人ćŠč®¶çš„结果可č˝ćťĄč‡ŞćŽćť + 您的用ć·ç¤ľĺŚşĺ’Śĺ®˘ć·ć”ąčż›ć‚¨çš„产ĺ“。 + +- ĺ†…ć ¸ä»Łç 在ĺ并ĺ°ä¸»çşżäą‹ĺ‰Ťĺ’Śäą‹ĺŽé˝č¦ç»Źčż‡ĺ®ˇćźĄă€‚不管原始开发人ĺ‘的技č˝ćś‰ĺ¤šĺĽşďĽŚ + 这个审查过程总ćŻč˝ć‰ľĺ°ć”ąčż›ä»Łç 的方法。审查经常发现严重的错误和安全问é˘ă€‚ + 这对于在ĺ°é—环ĺ˘ä¸ĺĽ€ĺŹ‘的代ç 尤其如ć¤ďĽ›čż™ç§Ťä»Łç 从外é¨ĺĽ€ĺŹ‘äşşĺ‘的审查ä¸čŽ·ç›Š + ĺŚŞćµ…ă€‚ć ‘ĺ¤–ä»Łç ćŻä˝Žč´¨é‡Źä»Łç 。 + +- 参与开发过程ćŻć‚¨ĺ˝±ĺ“Ťĺ†…ć ¸ĺĽ€ĺŹ‘ć–ąĺ‘的方式。ć—观者的抱怨会被ĺ¬ĺ°ďĽŚä˝†ćŻć´»č·çš„ + 开发人ĺ‘有更强的声音——并且č˝ĺ¤źĺ®žçŽ°ä˝żĺ†…ć ¸ć›´ĺĄ˝ĺś°ć»ˇč¶łĺ…¶éś€ć±‚çš„ć›´ć”ąă€‚ + +- 当单独维护代ç 时，总ćŻĺ在第三方为类似功č˝ćŹäľ›ä¸ŤĺŚĺ®žçŽ°çš„可č˝ć€§ă€‚如果发生 + 这种ć…况，ĺ并代ç ĺ°†ĺŹĺľ—ć›´ĺŠ ĺ›°éšľâ€”â€”ç”šč‡łĺ°äş†ä¸ŤĺŹŻč˝çš„ĺś°ćĄă€‚然ĺŽďĽŚć‚¨ĺ°†éť˘ä¸´ä»Ąä¸‹ + 令人不快的选择：ďĽ1ďĽ‰ć— é™ćśźĺś°ç»´ćŠ¤ć ‘ĺ¤–çš„éťžć ‡ĺ‡†ç‰ąć€§ďĽŚć–ďĽ2）放ĺĽä»Łç ĺą¶ĺ°†ç”¨ć· + čżç§»ĺ°ć ‘内ç‰ćś¬ă€‚ + +- 代ç 的贡献ćŻä˝żć•´ä¸Şčż‡ç¨‹ĺ·Ąä˝śçš„ć ąćś¬ă€‚é€ščż‡č´ˇçŚ®ä»Łç ，您可以ĺ‘ĺ†…ć ¸ć·»ĺŠ ć–°ĺŠźč˝ďĽŚĺą¶ + ćŹäľ›ĺ…¶ä»–ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘使用的功č˝ĺ’Śç¤şäľ‹ă€‚如果您已经为Linux开发了代ç ďĽć–者 + ćŁĺś¨č€č™‘čż™ć ·ĺšďĽ‰ďĽŚé‚Łäąć‚¨ćľç„¶ĺŻąčż™ä¸ŞĺąłĺŹ°çš„ćŚç»ć功感兴趣；贡献代ç ćŻçˇ®äżťć功 + 的最好方法之一。 + +上述所有ç†ç”±é˝é€‚ç”¨äşŽä»»ä˝•ć ‘ĺ¤–ĺ†…ć ¸ä»Łç ，包括以专有的ă€ä»…二进ĺ¶ĺ˝˘ĺĽŹĺ†ĺŹ‘的代ç 。 +然而，在č€č™‘任何类型的纯二进ĺ¶ĺ†…ć ¸ä»Łç ĺ†ĺ¸äą‹ĺ‰ŤďĽŚčżéś€č¦č€č™‘ĺ…¶ä»–ĺ› ç´ ă€‚čż™äş›ĺŚ…ć‹¬ďĽš + +- ĺ›´ç»•ä¸“ćś‰ĺ†…ć ¸ć¨ˇĺť—ĺ†ĺŹ‘çš„ćł•ĺľ‹é—®é˘ĺ……其量ćŻć¨ˇçłŠçš„ďĽ›ç›¸ĺ˝“ĺ¤šçš„ĺ†…ć ¸ç‰ćťć‰€ćś‰č€…认为， + 大多数仅é™äşŚčż›ĺ¶çš„模块ćŻĺ†…ć ¸çš„ć´ľç”źäş§ĺ“ďĽŚĺ› ć¤ďĽŚĺ®ä»¬çš„ĺ†ĺŹ‘违反了GNU通用公共 + 许可čŻďĽä¸‹éť˘ĺ°†čŻ¦ç»†ä»‹ç»ŤďĽ‰ă€‚您的作者不ćŻĺľ‹ĺ¸ďĽŚćś¬ć–‡ćˇŁä¸çš„任何内容é˝ä¸ŤĺŹŻč˝č˘« + 视为法律建议。ĺ°é—ćşä»Łç 模块的真实法律地位只č˝ç”±ćł•é™˘ĺ†łĺ®šă€‚ä˝†ä¸Ťç®ˇć€Žć ·ďĽŚĺ›°ć‰° + 这些模块的不确定性仍然ĺ在。 + +- 二进ĺ¶ć¨ˇĺť—ĺ¤§ĺ¤§ĺ˘žĺŠ äş†č°čŻ•ĺ†…ć ¸é—®é˘çš„éšľĺş¦ďĽŚä»Ąč‡łäşŽĺ¤§ĺ¤šć•°ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘甚至é˝ä¸ŤäĽš + ĺ°ťčŻ•ă€‚ĺ› ć¤ďĽŚĺŹŞĺ†ĺŹ‘二进ĺ¶ć¨ˇĺť—将使您的用ć·ć›´éšľä»Žç¤ľĺŚşčŽ·ĺľ—支ćŚă€‚ + +- 对于只支ćŚäşŚčż›ĺ¶çš„模块的发行者来说，支ćŚäąźć›´ĺŠ ĺ›°éšľďĽŚä»–ä»¬ĺż…éˇ»ä¸şä»–ä»¬ĺ¸Śćś›ć”ŻćŚ + 的每个发行ç‰ĺ’ŚćŻŹä¸Şĺ†…ć ¸ç‰ćś¬ćŹäľ›ä¸€ä¸Şç‰ćś¬çš„模块。为了ćŹäľ›ç›¸ĺ˝“全面的覆盖čŚĺ›´ďĽŚ + 可č˝éś€č¦ä¸€ä¸Şć¨ˇĺť—çš„ĺ‡ ĺŤä¸Şćž„ĺ»şďĽŚĺą¶ä¸”ćŻŹć¬ˇĺŤ‡çş§ĺ†…ć ¸ć—¶ďĽŚć‚¨çš„ç”¨ć·é˝ĺż…须单独升级 + 您的模块。 + +- 上面ćŹĺ°çš„关于代ç 评审的所有问é˘é˝ć›´ĺŠ ĺ在于ĺ°é—ćşä»Łç 。由于该代ç ć ąćś¬ä¸ŤĺŹŻ + ç”¨ďĽŚĺ› ć¤ç¤ľĺŚşć— ćł•ĺŻąĺ…¶čż›čˇŚĺ®ˇćźĄďĽŚćŻ«ć— ç–‘é—®ďĽŚĺ®ĺ°†ĺ在严重问é˘ă€‚ + +尤其ćŻĺµŚĺ…ĄĺĽŹçł»ç»źçš„ĺ¶é€ 商，可č˝äĽšĺ€ľĺ‘于忽视本节ä¸ć‰€čŻ´çš„大é¨ĺ†ĺ†…ĺ®ąďĽŚĺ› ä¸şä»–ä»¬ +相信自己ćŁĺś¨ĺ•†ç”¨ä¸€ç§Ťä˝żç”¨ĺ†»ç»“ĺ†…ć ¸ç‰ćś¬çš„独立产ĺ“，在发ĺ¸ĺŽä¸Ťéś€č¦ĺ†Ťčż›čˇŚĺĽ€ĺŹ‘。 +这个论点忽略了广泛的代ç 审查的价值以及ĺ…许用ć·ĺ‘产ĺ“ć·»ĺŠ ĺŠźč˝çš„价值。但这些 +产ĺ“也有有é™çš„商业寿命，之ĺŽĺż…须发ĺ¸ć–°ç‰ćś¬çš„产ĺ“。在这一点上，代ç 在主线上 +并得ĺ°č‰ŻĺĄ˝ç»´ćŠ¤çš„供应商将č˝ĺ¤źć›´ĺĄ˝ĺś°ĺŤ 位，以使新产ĺ“快速上市。 + +许可 +---- + +代ç ćŻć ąćŤ®ä¸€äş›č®¸ĺŹŻčŻćŹäľ›ç»™Linuxĺ†…ć ¸çš„ďĽŚä˝†ćŻć‰€ćś‰ä»Łç é˝ĺż…须与GNU通用公共许可 +čŻďĽGPLV2）的ç‰ćś¬2兼容，该ç‰ćś¬ćŻč¦†ç›–ć•´ä¸Şĺ†…ć ¸ĺ†ĺŹ‘的许可čŻă€‚在实践ä¸ďĽŚčż™ć„Źĺ‘ł +着所有代ç 贡献é˝ç”±GPLv2ďĽĺŹŻé€‰ĺś°ďĽŚčŻč¨€ĺ…许在更é«ç‰ćś¬çš„GPL下ĺ†ĺŹ‘）ć–3ĺ句BSD +许可ďĽNew BSD License, 译者注）覆盖。任何不包ĺ«ĺś¨ĺ…Ľĺ®ąč®¸ĺŹŻčŻä¸çš„贡献é˝ä¸ŤäĽš +被接受ĺ°ĺ†…ć ¸ä¸ă€‚ + +č´ˇçŚ®ç»™ĺ†…ć ¸çš„ä»Łç 不需č¦ďĽć–请求）ç‰ćťĺ†é…Ťă€‚ĺ并ĺ°ä¸»çşżĺ†…ć ¸ä¸çš„所有代ç é˝äżťç•™ +其原始所有ćťďĽ›ĺ› ć¤ďĽŚĺ†…ć ¸çŽ°ĺś¨ć‹Ąćś‰ć•°ĺŤä¸Şć‰€ćś‰č€…。 + +这种所有ćťç»“构的一个暗示ćŻďĽŚä»»ä˝•ć”ąĺŹĺ†…ć ¸č®¸ĺŹŻçš„ĺ°ťčŻ•é˝ćł¨ĺ®šäĽšĺ¤±č´Ąă€‚ĺľĺ°‘有实际 +的场景可以获得所有ç‰ćťć‰€ćś‰č€…çš„ĺŚć„ŹďĽć–č€…ä»Žĺ†…ć ¸ä¸ĺ 除他们的代ç ďĽ‰ă€‚ĺ› ć¤ďĽŚç‰ą +ĺ«ćŻďĽŚĺś¨ĺŹŻé˘„č§çš„将来，不可č˝čżç§»ĺ°GPLçš„ç‰ćś¬3。 + +ć‰€ćś‰č´ˇçŚ®ç»™ĺ†…ć ¸çš„ä»Łç é˝ĺż…须ćŻĺćł•çš„ĺ…Ťč´ąč˝Żä»¶ă€‚ĺ› ć¤ďĽŚä¸ŤćŽĄĺŹ—匿ĺŤďĽć–匿ĺŤďĽ‰č´ˇçŚ® +者的代ç 。所有贡献者é˝éś€č¦ĺś¨ä»–们的代ç 上“sign off”，声ćŽä»Łç 可以在GPL下与内 +ć ¸ä¸€čµ·ĺ†ĺŹ‘ă€‚ć— ćł•ćŹäľ›ćśŞč˘«ĺ…¶ć‰€ćś‰č€…许可为免费软件的代ç ，ć–可č˝ä¸şĺ†…ć ¸é€ ćç‰ćť +相关问é˘çš„代ç ďĽäľ‹ĺ¦‚，由缺乏适当保护的反ĺ‘工程工作派生的代ç ）不č˝č˘«ćŽĄĺŹ—。 + +有关ç‰ćťç›¸ĺ…łé—®é˘çš„é—®é˘ĺś¨Linux开发邮件ĺ—表ä¸ĺľĺ¸¸č§ă€‚čż™ć ·çš„é—®é˘é€šĺ¸¸äĽšĺľ—ĺ°ä¸Ťĺ°‘ +ç”ćˇďĽŚä˝†č¦č®°ä˝ŹďĽŚĺ›žç”这些问é˘çš„人不ćŻĺľ‹ĺ¸ďĽŚä¸Ťč˝ćŹäľ›ćł•ĺľ‹ĺ’¨čŻ˘ă€‚如果您有关于 +Linuxćşä»Łç çš„ćł•ĺľ‹é—®é˘ďĽŚé‚Łäąä¸Žäş†č§ŁčŻĄé˘†ĺźźçš„ĺľ‹ĺ¸äş¤ćµćŻć— ćł•ć›żä»Łçš„ă€‚äľťéť ä»ŽćŠ€ćśŻ +邮件ĺ—表ä¸čŽ·ĺľ—çš„ç”ćˇćŻä¸€ä»¶ĺ†’险的事ć…。 + diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst new file mode 100644 index 000000000000..ceb733bb0294 --- /dev/null +++ b/Documentation/translations/zh_CN/process/2.Process.rst @@ -0,0 +1,360 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/2.Process.rst <development_process>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_process: + +开发ćµç¨‹ĺ¦‚何工作 +================ + +90年代早期的Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ćŻä¸€ä»¶ç›¸ĺ˝“ćťľć•Łçš„äş‹ć…，涉及的用ć·ĺ’ŚĺĽ€ĺŹ‘äşşĺ‘ç›¸ĺŻąčľ +少。由于拥有数以百万计的用ć·çľ¤ďĽŚĺą¶ä¸”在一年的时间里有大约2000ĺŤĺĽ€ĺŹ‘äşşĺ‘参与 +čż›ćťĄďĽŚĺ†…ć ¸ĺ› ć¤ĺż…须发展许多ćµç¨‹ćťĄäżťćŚĺĽ€ĺŹ‘的顺ĺ©čż›čˇŚă€‚č¦ć为ćµç¨‹çš„有ć•ç»„ć +é¨ĺ†ďĽŚéś€č¦ĺŻąćµç¨‹çš„工作方式有一个扎实的ç†č§Łă€‚ + +ć€»č§ +---- + +ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘使用一个松散的基于时间的发ĺ¸čż‡ç¨‹ďĽŚćŻŹä¸¤ĺ°ä¸‰ä¸ŞćśĺŹ‘ĺ¸ä¸€ć¬ˇć–°çš„ä¸»č¦ +ĺ†…ć ¸ç‰ćś¬ă€‚最近的发ĺ¸ĺŽ†ĺŹ˛č®°ĺ˝•ĺ¦‚下： + + ====== ================= + 4.11 ĺ››ćś 30, 2017 + 4.12 ä¸ćś 2, 2017 + 4.13 äąťćś 3, 2017 + 4.14 ĺŤä¸€ćś 12, 2017 + 4.15 ä¸€ćś 28, 2018 + 4.16 ĺ››ćś 1, 2018 + ====== ================= + +每4.xç‰ćś¬é˝ćŻä¸€ä¸Şä¸»č¦çš„ĺ†…ć ¸ç‰ćś¬ďĽŚĺ…·ćś‰ć–°ç‰ąć€§ă€ĺ†…é¨API更改ç‰ç‰ă€‚一个典型的4.x +ç‰ćś¬ĺŚ…ĺ«ĺ¤§çş¦13000个ĺŹć›´é›†ďĽŚĺŹć›´äş†ĺ‡ ĺŤä¸‡čˇŚä»Łç ă€‚ĺ› ć¤ďĽŚ4.xćŻLinuxĺ†…ć ¸ĺĽ€ĺŹ‘çš„ĺ‰Ť +ć˛żďĽ›ĺ†…ć ¸ä˝żç”¨ć»šĺŠ¨ĺĽ€ĺŹ‘ć¨ˇĺž‹ďĽŚä¸Ťć–集ć重大ĺŹĺŚ–。 + +对于每个ç‰ćś¬çš„补ä¸ĺ并，éµĺľŞä¸€ä¸Şç›¸ĺŻąç®€ĺŤ•çš„规ĺ™ă€‚在每个开发周期的开始，“ĺ并 +窗口”被打开。当时，被认为足够稳定ďĽĺą¶ä¸”被开发社区接受）的代ç 被ĺ并ĺ°ä¸»çşżĺ†… +ć ¸ä¸ă€‚在这段时间内，新开发周期的大é¨ĺ†ĺŹć›´ďĽä»ĄĺŹŠć‰€ćś‰ä¸»č¦ĺŹć›´ďĽ‰ĺ°†ä»ĄćŽĄčż‘每天 +1000次ĺŹć›´ďĽâ€śčˇĄä¸â€ťć–“ĺŹć›´é›†â€ťďĽ‰çš„速度ĺ并。 + +ďĽéˇşäľżčŻ´ä¸€ĺŹĄďĽŚĺ€Ľĺľ—注意的ćŻďĽŚĺ并窗口期间集ć的更改并不ćŻĺ‡ç©şäş§ç”źçš„；ĺ®ä»¬ćŻ +ćŹĺ‰Ťć”¶é›†ă€ćµ‹čŻ•ĺ’Śĺ†çş§çš„。稍ĺŽĺ°†čŻ¦ç»†ćŹŹčż°čŻĄčż‡ç¨‹çš„工作方式）。 + +ĺ并窗口ćŚç»ĺ¤§çş¦ä¸¤ĺ‘¨ă€‚在这段时间结束时，LinusTorvalds将声ćŽçŞ—ĺŹŁĺ·˛ĺ…łé—，并 +释放第一个“rcâ€ťĺ†…ć ¸ă€‚äľ‹ĺ¦‚ďĽŚĺŻąäşŽç›®ć ‡ä¸ş4.14çš„ĺ†…ć ¸ďĽŚĺś¨ĺ并窗口结束时发生的释放 +将被称为4.14-rc1。RC1ç‰ćś¬ćŻä¸€ä¸ŞäżˇĺŹ·ďĽŚčˇ¨ç¤şĺ并新特性的时间已经过去，稳定下一 +ä¸Şĺ†…ć ¸çš„ć—¶é—´ĺ·˛ç»ŹĺĽ€ĺ§‹ă€‚ + +在接下来的6ĺ°10周内，只有修复问é˘çš„补ä¸ć‰Ťĺş”该ćŹäş¤ç»™ä¸»çşżă€‚有时会ĺ…许更大的 +更改，但这种ć…况ĺľĺ°‘发生；试图在ĺ并窗口外ĺ并新功č˝çš„开发人ĺ‘往往会受ĺ°ä¸Ť +友好的接待。一č¬ćťĄčŻ´ďĽŚĺ¦‚果您错过了给定特性的ĺ并窗口，最好的ĺšćł•ćŻç‰ĺľ…下一 +个开发周期。ďĽĺŻąäşŽä»Ąĺ‰Ťä¸Ťć”ŻćŚçš„硬件，ĺ¶ĺ°”会对驱动程序进行例外；如果ĺ®ä»¬ä¸Ť +改ĺŹĺ·˛ćś‰ä»Łç ，ĺ™ä¸ŤäĽšĺŻĽč‡´ĺ›žĺ˝’ďĽŚĺą¶ä¸”ĺş”čŻĄĺŹŻä»ĄéšŹć—¶ĺ®‰ĺ…¨ĺś°ć·»ĺŠ ďĽ‰ă€‚ + +随着修复程序进入主线，补ä¸é€źĺş¦ĺ°†éšŹçť€ć—¶é—´çš„推移而ĺŹć…˘ă€‚Linus大约每周发ĺ¸ä¸€ć¬ˇ +ć–°çš„-rcĺ†…ć ¸ďĽ›ä¸€ä¸ŞćŁĺ¸¸çš„çł»ĺ—将在-rc6ĺ’Ś-rc9äą‹é—´ďĽŚĺ†…ć ¸č˘«č®¤ä¸şč¶łĺ¤źç¨łĺ®šĺą¶ćś€ç»ĺŹ‘ĺ¸ă€‚ +然ĺŽďĽŚć•´ä¸Şčż‡ç¨‹ĺŹé‡Ťć–°ĺĽ€ĺ§‹äş†ă€‚ + +例如，这里ćŻ4.16的开发周期进行ć…况ďĽ2018年的所有日期）: + + ============== ============================== + ä¸€ćś 28 4.15 稳定ç‰ĺŹ‘ĺ¸ + äşŚćś 11 4.16-rc1, ĺĺą¶çŞ—ĺŹŁĺ…łé— + äşŚćś 18 4.16-rc2 + äşŚćś 25 4.16-rc3 + ä¸‰ćś 4 4.16-rc4 + ä¸‰ćś 11 4.16-rc5 + ä¸‰ćś 18 4.16-rc6 + ä¸‰ćś 25 4.16-rc7 + ĺ››ćś 1 4.16 稳定ç‰ĺŹ‘ĺ¸ + ============== ============================== + +开发人ĺ‘如何决定何时结束开发周期并ĺ›ĺ»şç¨łĺ®šçš„ç‰ćś¬ďĽźä˝żç”¨çš„最重č¦çš„ćŚ‡ć ‡ćŻä»Ąĺ‰Ť +ç‰ćś¬çš„回归ĺ—表。不欢迎出现任何错误，但ćŻé‚Łäş›ç ´ĺťŹäş†ä»Ąĺ‰Ťč˝ĺ·Ąä˝śçš„系统的错误被 +认为ćŻç‰ąĺ«ä¸Ąé‡Ťçš„ă€‚ĺ› ć¤ďĽŚĺŻĽč‡´ĺ›žĺ˝’的补ä¸ćŻä¸ŤĺŹ—欢迎的，ĺľĺŹŻč˝ĺś¨ç¨łĺ®šćśźĺ†…ĺ 除。 + +开发人ĺ‘çš„ç›®ć ‡ćŻĺś¨ç¨łĺ®šĺŹ‘ĺ¸äą‹ĺ‰Ťäż®ĺ¤Ťć‰€ćś‰ĺ·˛çźĄçš„回归。在现实世界ä¸ďĽŚčż™ç§Ťĺ®ŚçľŽćŻ +ĺľéšľĺ®žçŽ°çš„；在这种规模的项目ä¸ďĽŚĺŹé‡Źĺ¤Şĺ¤šäş†ă€‚有一点，延迟最ç»ç‰ćś¬ĺŹŞäĽšä˝żé—®é˘ +ĺŹĺľ—更糟；ç‰ĺľ…下一个ĺĺą¶çŞ—ĺŹŁçš„ä¸€ĺ †ć›´ć”ąĺ°†ĺŹĺ¤§ďĽŚä»Žč€Śĺś¨ä¸‹ć¬ˇĺ›ĺ»şć›´ĺ¤šçš„回归错误。 +ĺ› ć¤ďĽŚĺ¤§ĺ¤šć•°4.xĺ†…ć ¸é˝ćś‰ä¸€äş›ĺ·˛çźĄçš„回归错误，不过，希望没有一个ćŻä¸Ąé‡Ťçš„。 + +一旦一个稳定的ç‰ćś¬ĺŹ‘ĺ¸ďĽŚĺ®ćŁĺś¨čż›čˇŚçš„维护工作就被移交给“稳定团éźâ€ťďĽŚç›®ĺ‰Ťç”± +Greg Kroah-Hartman组ć。稳定团éźĺ°†ä˝żç”¨4.x.y编号方ćˇä¸Ťĺ®šćśźçš„发ĺ¸ç¨łĺ®šç‰ćś¬çš„ć›´ +新。č¦ĺŠ ĺ…Ąć›´ć–°ç‰ćś¬ďĽŚčˇĄä¸ç¨‹ĺşŹĺż…须ďĽ1）修复一个重č¦çš„bug，ďĽ2）已经ĺĺą¶ĺ° +下一个开发主线ä¸ă€‚ĺ†…ć ¸é€šĺ¸¸äĽšĺś¨č¶…čż‡ĺ…¶ĺťĺ§‹ç‰ćś¬çš„一个以上的开发周期内接收稳定 +的更新。例如，4.13ĺ†…ć ¸çš„ĺŽ†ĺŹ˛ĺ¦‚ä¸‹ + + ============== =============================== + äąťćś 3 4.13 稳定ç‰ĺŹ‘ĺ¸ + äąťćś 13 4.13.1 + äąťćś 20 4.13.2 + äąťćś 27 4.13.3 + ĺŤćś 5 4.13.4 + ĺŤćś 12 4.13.5 + ... ... + ĺŤä¸€ćś 24 4.13.16 + ============== =============================== + +4.13.16ćŻ4.13ç‰ćś¬çš„最ç»ç¨łĺ®šć›´ć–°ă€‚ + +ćś‰äş›ĺ†…ć ¸č˘«ćŚ‡ĺ®šä¸şâ€śé•żćśźâ€ťĺ†…ć ¸ďĽ›ĺ®ä»¬ĺ°†ĺľ—ĺ°ć›´é•żć—¶é—´çš„支ćŚă€‚在本文ä¸ďĽŚĺ˝“前的长期 +ĺ†…ć ¸ĺŹŠĺ…¶ç»´ćŠ¤č€…ćŻďĽš + + ====== ====================== ============================== + 3.16 Ben Hutchings (é•żćśźç¨łĺ®šĺ†…ć ¸) + 4.1 Sasha Levin + 4.4 Greg Kroah-Hartman (é•żćśźç¨łĺ®šĺ†…ć ¸) + 4.9 Greg Kroah-Hartman + 4.14 Greg Kroah-Hartman + ====== ====================== ============================== + +为长期支ćŚé€‰ć‹©ĺ†…ć ¸çşŻç˛ąćŻç»´ćŠ¤äşşĺ‘有必č¦ĺ’Ść—¶é—´ćťĄç»´ćŠ¤čŻĄç‰ćś¬çš„é—®é˘ă€‚目前čżć˛ˇćś‰ +为即将发ĺ¸çš„任何特定ç‰ćś¬ćŹäľ›é•żćśźć”ŻćŚçš„已知计ĺ’。 + +补ä¸çš„生命周期 +-------------- + +补ä¸ä¸ŤäĽšç›´ćŽĄä»ŽĺĽ€ĺŹ‘äşşĺ‘çš„é”®ç›čż›ĺ…Ąä¸»çşżĺ†…ć ¸ă€‚ç›¸ĺŹŤďĽŚćś‰ä¸€ä¸Şç¨Ťĺľ®ĺ¤Ťćť‚ďĽĺ¦‚果有些非 +ćŁĺĽŹďĽ‰çš„过程，旨在确保对每个补ä¸čż›čˇŚč´¨é‡Źĺ®ˇćźĄďĽŚĺą¶çˇ®äżťćŻŹä¸ŞčˇĄä¸ĺ®žçŽ°äş†ä¸€ä¸Şĺś¨ä¸»çşż +ä¸éś€č¦çš„更改。对于小的修复，这个过程可č˝äĽšĺľĺż«ĺŹ‘生，ć–者，在大的和有争议的 +ĺŹć›´çš„ć…况下，会ćŚç»ć•°ĺą´ă€‚许多开发人ĺ‘的挫ćŠćťĄč‡ŞäşŽĺŻąčż™ä¸Şčż‡ç¨‹çĽşäąŹç†č§Łć–者 +试图绕过ĺ®ă€‚ + +为了减少这种挫ćŠć„źďĽŚćś¬ć–‡ĺ°†ćŹŹčż°čˇĄä¸ĺ¦‚ä˝•čż›ĺ…Ąĺ†…ć ¸ă€‚ä¸‹éť˘ćŻä¸€ä¸Şä»‹ç»ŤďĽŚĺ®ä»Ąćźç§Ť +ç†ćłĺŚ–的方式描述了这个过程。更详细的过程将在ĺŽéť˘çš„ç« čŠ‚ä¸ä»‹ç»Ťă€‚ + +补ä¸ç¨‹ĺşŹç»ŹĺŽ†çš„é¶ć®µé€šĺ¸¸ćŻďĽš + +- 设计。这就ćŻčˇĄä¸çš„çśźćŁéś€ć±‚——以及满足这些需求的方式——的所在。设计工作通常 + ćŻĺś¨ä¸Ťć¶‰ĺŹŠç¤ľĺŚşçš„ć…况下完ć的，但ćŻĺ¦‚果可č˝çš„话，最好ćŻĺś¨ĺ…¬ĺĽ€çš„ć…况下完ć + čż™éˇąĺ·Ąä˝śďĽ›čż™ć ·ĺŹŻä»ĄčŠ‚çśĺľĺ¤šç¨ŤĺŽĺ†Ťé‡Ťć–°č®ľč®ˇçš„时间。 + +- 早期评审。补ä¸č˘«ĺŹ‘ĺ¸ĺ°ç›¸ĺ…łçš„邮件ĺ—表ä¸ďĽŚĺ—表ä¸çš„开发人ĺ‘会回复他们可č˝ćś‰ + 的任何评论。如果一ĺ‡éˇşĺ©çš„话，这个过程应该会发现补ä¸çš„任何主č¦é—®é˘ă€‚ + +- 更广泛的评审。当补ä¸ćŽĄčż‘准备好纳入主线时，ĺ®ĺş”该被相关的ĺçł»ç»źç»´ćŠ¤äşşĺ‘ + 接受——尽管这种接受并不č˝äżťčŻčˇĄä¸äĽšä¸€ç›´ĺ»¶äĽ¸ĺ°ä¸»çşżă€‚补ä¸ĺ°†ĺ‡şçŽ°ĺś¨ç»´ćŠ¤äşşĺ‘çš„ + ĺçł»ç»źć ‘ä¸ďĽŚĺą¶čż›ĺ…Ą -next ć ‘ďĽĺ¦‚下所述）。当ćµç¨‹ĺ·Ąä˝ść—¶ďĽŚć¤ćĄéŞ¤ĺ°†ĺŻĽč‡´ĺŻąčˇĄä¸ + 进行更广泛的审查，并发现由于将ć¤čˇĄä¸ä¸Žĺ…¶ä»–人所ĺšçš„工作集ć而导致的任何 + é—®é˘ă€‚ + +- 请注意，大多数维护人ĺ‘äąźćś‰ć—Ąĺ¸¸ĺ·Ąä˝śďĽŚĺ› ć¤ĺ并补ä¸ĺŹŻč˝ä¸ŤćŻä»–们的最é«äĽĺ…级。 + 如果您的补ä¸ç¨‹ĺşŹĺľ—ĺ°äş†ĺ…łäşŽć‰€éś€ć›´ć”ąçš„反é¦ďĽŚé‚Łäąć‚¨ĺş”该进行这些更改，ć–者为 + ä¸Ťĺş”čŻĄčż›čˇŚčż™äş›ć›´ć”ąçš„ĺŽźĺ› čľ©ćŠ¤ă€‚ĺ¦‚ćžść‚¨çš„čˇĄä¸ć˛ˇćś‰čŻ„审意č§ďĽŚä˝†ć˛ˇćś‰č˘«ĺ…¶ç›¸ĺş”çš„ + ĺ系统ć–驱动程序维护者接受，那äąć‚¨ĺş”该坚ćŚä¸Ťć‡ĺś°ĺ°†čˇĄä¸ć›´ć–°ĺ°ĺ˝“ĺ‰Ťĺ†…ć ¸ďĽŚä˝ż + 其干净地应用，并不ć–地将其发é€ä»Ąäľ›ĺ®ˇćźĄĺ’Śĺ并。 + +- ĺ并ĺ°ä¸»çşżă€‚最ç»ďĽŚä¸€ä¸Şć功的补ä¸ĺ°†č˘«ĺ并ĺ°ç”±LinusTorvalds管ç†çš„主线ĺ储库 + ä¸ă€‚ć¤ć—¶ĺŹŻč˝äĽšĺ‡şçŽ°ć›´ĺ¤šçš„评论和/ć–é—®é˘ďĽ›ĺĽ€ĺŹ‘äşşĺ‘应对这些问é˘ĺą¶č§Łĺ†łĺ‡şçŽ°çš„ + 任何问é˘ĺľé‡Ťč¦ă€‚ + +- 稳定ç‰ĺŹ‘ĺ¸ă€‚可č˝ĺŹ—补ä¸ĺ˝±ĺ“Ťçš„用ć·ć•°é‡ŹçŽ°ĺś¨ĺľĺ¤§ďĽŚĺ› ć¤ĺŹŻč˝ĺ†Ťć¬ˇĺ‡şçŽ°ć–°çš„é—®é˘ă€‚ + +- 长期维护。虽然开发人ĺ‘在ĺ并代ç ĺŽĺŹŻč˝äĽšĺżč®°ä»Łç ，但这种行为往往会给开发 + 社区留下不良印象。ĺ并代ç ć¶é™¤äş†ä¸€äş›ç»´ćŠ¤č´źć‹…ďĽŚĺ› ä¸şĺ…¶ä»–ä»Łç 将修复由API + 更改引起的问é˘ă€‚但ćŻďĽŚĺ¦‚果代ç č¦é•żćśźäżťćŚćś‰ç”¨ďĽŚĺŽźĺ§‹ĺĽ€ĺŹ‘äşşĺ‘应该继ç»ä¸ş + 代ç 负责。 + +ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ďĽć–他们的雇主）犯的最大错误之一ćŻčŻ•ĺ›ľĺ°†ćµç¨‹ç®€ĺŚ–为一个 +“ĺ并ĺ°ä¸»çşżâ€ťćĄéŞ¤ă€‚čż™ç§Ťć–ąćł•ć€»ćŻäĽšč®©ć‰€ćś‰ç›¸ĺ…łäşşĺ‘ć„źĺ°ć˛®ä¸§ă€‚ + +补ä¸ĺ¦‚ä˝•čż›ĺ…Ąĺ†…ć ¸ +---------------- + +只有一个人可以将补ä¸ĺ并ĺ°ä¸»çşżĺ†…ć ¸ĺ储库ä¸ďĽšLinusTorvalds。但ćŻďĽŚĺś¨čż›ĺ…Ą +2.6.38ĺ†…ć ¸çš„9500多个补ä¸ä¸ďĽŚĺŹŞćś‰112个ďĽĺ¤§çş¦1.3%）ćŻç”±Linus自己直接选择的。 +ĺ†…ć ¸éˇąç›®ĺ·˛ç»ŹĺŹ‘ĺ±•ĺ°ä¸€ä¸Şč§„模，没有一个开发人ĺ‘可以在没有支ćŚçš„ć…况下检查和 +选择每个补ä¸ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘处ç†čż™ç§Ťĺ˘žé•żçš„方式ćŻé€ščż‡ä˝żç”¨ĺ›´ç»•äżˇä»»é“ľćž„建的 +助ç†çł»ç»źă€‚ + +ĺ†…ć ¸ä»Łç 库在逻辑上被ĺ†č§Łä¸şä¸€ç»„ĺ系统：网络ă€ç‰ąĺ®šçš„体系结构支ćŚă€ĺ†…ĺ管ç†ă€ +视频设备ç‰ă€‚大多数ĺ系统é˝ćś‰ä¸€ä¸ŞćŚ‡ĺ®šçš„维护人ĺ‘，开发人ĺ‘对该ĺ系统ä¸çš„代ç +负有全é¨č´Łä»»ă€‚这些ĺ系统维护者ďĽćťľć•Łĺś°ďĽ‰ćŻä»–们所管ç†çš„ĺ†…ć ¸é¨ĺ†çš„ĺ®ćŠ¤č€…； +他们ďĽé€šĺ¸¸ďĽ‰äĽšćŽĄĺŹ—一个补ä¸ä»ĄĺŚ…ĺ«ĺ°ä¸»çşżĺ†…ć ¸ä¸ă€‚ + +ĺ系统维护人ĺ‘每个人é˝ä˝żç”¨gitćşä»Łç 管ç†ĺ·Ąĺ…·ç®ˇç†č‡Şĺ·±ç‰ćś¬çš„ĺ†…ć ¸ćşä»Łç ć ‘ă€‚Git +ç‰ĺ·Ąĺ…·ďĽä»ĄĺŹŠQuiltć–Mercurialç‰ç›¸ĺ…łĺ·Ąĺ…·ďĽ‰ĺ…许维护人ĺ‘跟踪补ä¸ĺ—表，包括作者 +信ćŻĺ’Śĺ…¶ä»–ĺ…数据。在任何给定的时间，维护人ĺ‘é˝ĺŹŻä»Ąçˇ®ĺ®šä»–ć–她的ĺ储库ä¸çš„ĺ“Ş +些补ä¸ĺś¨ä¸»çşżä¸ć‰ľä¸Ťĺ°ă€‚ + +当ĺ并窗口打开时，顶级维护人ĺ‘ĺ°†č¦ć±‚Linus从其ĺ储库ä¸â€ść‹‰ĺ‡şâ€ťä»–们为ĺ并选择 +的补ä¸ă€‚如果LinusĺŚć„ŹďĽŚčˇĄä¸ćµĺ°†ćµĺ‘ä»–çš„ĺ储库，ćä¸şä¸»çşżĺ†…ć ¸çš„ä¸€é¨ĺ†ă€‚ +Linus对拉操作ä¸ćŽĄć”¶ĺ°çš„特定补ä¸çš„关注程度ĺ„不相ĺŚă€‚ĺľćŽćľďĽŚćś‰ć—¶ä»–çś‹čµ·ćťĄĺľ +关注。但ćŻďĽŚä˝śä¸şä¸€č¬č§„ĺ™ďĽŚLinus相信ĺ系统维护人ĺ‘不会ĺ‘上游发é€ĺťŹčˇĄä¸ă€‚ + +ĺ系统维护人ĺ‘反过来也可以从其他维护人ĺ‘那里获取补ä¸ă€‚äľ‹ĺ¦‚ďĽŚç˝‘ç»ść ‘ćŻç”±é¦–ĺ… +在专用于网络设备驱动程序ă€ć— 线网络ç‰çš„ć ‘ä¸ç§Żç´Żçš„补ä¸ćž„建的。ć¤ĺ储链可以 +任意长，但ĺľĺ°‘超过两个ć–三个链接。由于链ä¸çš„每个维护者é˝äżˇä»»é‚Łäş›ç®ˇç†čľä˝Ž +级ĺ«ć ‘的维护者，所以这个过程称为“信任链”。 + +ćľç„¶ďĽŚĺś¨čż™ć ·çš„系统ä¸ďĽŚčŽ·ĺŹ–ĺ†…ć ¸čˇĄä¸ĺŹ–决于找ĺ°ćŁçˇ®çš„维护者。直接ĺ‘LinusĺŹ‘é€ +补ä¸é€šĺ¸¸ä¸ŤćŻćŁçˇ®çš„方法。 + +Next ć ‘ +------- + +ĺçł»ç»źć ‘é“ľĺĽ•ĺŻĽčˇĄä¸ćµĺ°ĺ†…ć ¸ďĽŚä˝†ĺ®äąźćŹĺ‡şäş†ä¸€ä¸Şćś‰č¶Łçš„é—®é˘ďĽšĺ¦‚果有人ćłćźĄçś‹ä¸ş +下一个ĺ并窗口准备的所有补ä¸ć€ŽäąĺŠžďĽźĺĽ€ĺŹ‘äşşĺ‘将感兴趣的ćŻďĽŚčżćś‰ä»€äąĺ…¶ä»–çš„ +更改有待解决，以查看ćŻĺ¦ĺ在需č¦ć‹…ĺżçš„冲çŞďĽ›äľ‹ĺ¦‚ďĽŚć›´ć”ąć ¸ĺżĺ†…ć ¸ĺ‡˝ć•°ĺŽźĺž‹çš„ +修补程序将与使用该函数旧形式的任何其他修补程序冲çŞă€‚审查人ĺ‘和测试人ĺ‘希望 +在所有这些ĺŹć›´ĺ°čľľä¸»çşżĺ†…ć ¸äą‹ĺ‰ŤďĽŚč˝ĺ¤źč®żé—®ĺ®ä»¬çš„集ć形式ä¸çš„ĺŹć›´ă€‚您可以从所有 +有趣的ĺçł»ç»źć ‘ä¸ćŹĺŹ–更改，但这将ćŻä¸€éˇąĺ¤§ĺž‹ä¸”容ć“出错的工作。 + +ç”ćˇä»Ą-nextć ‘çš„ĺ˝˘ĺĽŹĺ‡şçŽ°ďĽŚĺś¨čż™é‡Śĺçł»ç»źć ‘č˘«ć”¶é›†ä»Ąäľ›ćµ‹čŻ•ĺ’Śĺ®ˇćźĄă€‚Andrew Morton +ç»´ćŠ¤çš„čż™äş›ć—§ć ‘č˘«ç§°ä¸şâ€ś-mm”ďĽç”¨äşŽĺ†…ĺ管ç†ďĽŚčż™ĺ°±ćŻĺ®çš„ĺŻĺŠ¨ĺŤĺ—）。-mm ć ‘é›†ć了 +一长串ĺçł»ç»źć ‘ä¸çš„补ä¸ďĽ›ĺ®čżĺŚ…ĺ«ä¸€äş›ć—¨ĺś¨ĺ¸®ĺŠ©č°čŻ•çš„补ä¸ă€‚ + +除ć¤äą‹ĺ¤–，-mm čżĺŚ…ĺ«ĺ¤§é‡Źç”±Andrew直接选择的补ä¸ă€‚这些补ä¸ĺŹŻč˝ĺ·˛ç»ŹĺŹ‘ĺ¸ĺś¨é‚®ä»¶ +ĺ—表上，ć–者ĺ®ä»¬ĺŹŻč˝ĺş”ç”¨äşŽĺ†…ć ¸ä¸ć˛ˇćś‰ćŚ‡ĺ®šĺçł»ç»źć ‘çš„é¨ĺ†ă€‚结果，-mm 作为一种 +最ĺŽć‰‹ć®µçš„ĺçł»ç»źć ‘čżčˇŚďĽ›ĺ¦‚果没有其他ćŽćľçš„路径可以让补ä¸čż›ĺ…Ąä¸»çşżďĽŚé‚Łäąĺ®ĺľ +可č˝ä»Ą-mm 结束。累积在-mm ä¸çš„ĺ„种补ä¸ćś€ç»ĺ°†č˘«č˝¬ĺŹ‘ĺ°é€‚当的ĺçł»ç»źć ‘ďĽŚć–者直接 +发é€ĺ°Linus。在典型的开发周期ä¸ďĽŚĺ¤§çş¦5-10%的补ä¸é€ščż‡-mm 进入主线。 + +当前-mm 补ä¸ĺŹŻĺś¨â€śmmotm”ďĽ-mm of the moment）目录ä¸ć‰ľĺ°ďĽŚĺś°ĺť€ďĽš + + http://www.ozlabs.org/~akpm/mmotm/ + +然而，使用mmotmć ‘ĺŹŻč˝ćŻä¸€ç§Ťä»¤äşşć˛®ä¸§çš„体验；ĺ®ç”šč‡łĺŹŻč˝ć— 法编译。 + +下一个周期补ä¸ĺ并的主č¦ć ‘ćŻlinux-next，由Stephen Rothwell ç»´ćŠ¤ă€‚ć ąćŤ®č®ľč®ˇ +linux-next ćŻä¸‹ä¸€ä¸Şĺ并窗口关é—ĺŽä¸»çşżçš„快照。linux-nextć ‘ĺś¨Linux-kernel ĺ’Ś +Linux-next 邮件ĺ—表ä¸ĺŹ‘ĺ¸ďĽŚĺŹŻä»Žä»Ąä¸‹ä˝Ťç˝®ä¸‹č˝˝ďĽš + + http://www.kernel.org/pub/linux/kernel/next/ + +Linux-next 已经ćä¸şĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹ä¸ä¸ŤĺŹŻć–缺的一é¨ĺ†ďĽ›ĺś¨ä¸€ä¸Şç»™ĺ®šçš„ĺ并窗口ä¸ĺ并 +的所有补ä¸é˝ĺş”该在ĺ并窗口打开之前的一段时间内找ĺ°čż›ĺ…ĄLinux-next 的方法。 + +Staging ć ‘ +---------- + +ĺ†…ć ¸ćşä»Łç ć ‘ĺŚ…ĺ«drivers/staging/directory，其ä¸ćś‰č®¸ĺ¤šé©±ĺŠ¨ç¨‹ĺşŹć–文件系统的 +ĺ目录ćŁĺś¨č˘«ć·»ĺŠ ĺ°ĺ†…ć ¸ć ‘ä¸ă€‚ĺ®ä»¬ç„¶éś€č¦ć›´ĺ¤šçš„工作的时候可以保留在 +driver/staging目录ä¸ďĽ›ä¸€ć—¦ĺ®Ść，就可以将ĺ®ä»¬ç§»ĺ°ĺ†…ć ¸ä¸ă€‚čż™ćŻä¸€ç§Ťč·źč¸Şä¸Ťç¬¦ĺ +Linuxĺ†…ć ¸çĽ–ç ć–č´¨é‡Źć ‡ĺ‡†çš„é©±ĺŠ¨ç¨‹ĺşŹçš„ć–ąćł•ďĽŚä˝†äşşä»¬ĺŹŻč˝ĺ¸Śćś›ä˝żç”¨ĺ®ä»¬ĺą¶č·źč¸ŞĺĽ€ĺŹ‘。 + +Greg Kroah Hartman 目前负责维护staging ć ‘ă€‚ä»Ťéś€č¦ĺ·Ąä˝śçš„驱动程序将发é€ç»™ä»–， +每个驱动程序在drivers/staging/ä¸é˝ćś‰č‡Şĺ·±çš„ĺ目录。除了驱动程序ćşć–‡ä»¶äą‹ĺ¤–， +目录ä¸čżĺş”该有一个TODO文件。todo文件ĺ—出了驱动程序需č¦ćŽĄĺŹ—的挂起的工作， +以及驱动程序的任何补ä¸é˝ĺş”该抄é€çš„äşşĺ‘ĺ—表。当前的规ĺ™č¦ć±‚，staging的驱动 +程序必须至少ćŁçˇ®çĽ–译。 + +Staging ćŻä¸€ç§Ťç›¸ĺŻąĺ®ąć“的方法，可以让新的驱动程序进入主线，幸čżçš„ćŻďĽŚä»–们会 +引起其他开发人ĺ‘的注意，并迅速改进。然而，进入staging并不ćŻć•…事的结尾； +stagingä¸ć˛ˇćś‰çś‹ĺ°ĺ¸¸č§„进展的代ç 最ç»ĺ°†č˘«ĺ 除。经销商也倾ĺ‘于相对不愿意使用 +stagingé©±ĺŠ¨ç¨‹ĺşŹă€‚ĺ› ć¤ďĽŚĺś¨ć为一ĺŤĺ适的主线驱动的路上，staging ĺ……ĺ…¶é‡ŹĺŹŞćŻ +一个ĺśç•™ă€‚ + +ĺ·Ąĺ…· +---- + +ä»Žä¸Šéť˘çš„ć–‡ćś¬ĺŹŻä»Ąçś‹ĺ‡şďĽŚĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹ĺś¨ĺľĺ¤§ç¨‹ĺş¦ä¸Šäľťčµ–于在不ĺŚć–ąĺ‘上čšé›†čˇĄä¸çš„ +č˝ĺŠ›ă€‚ĺ¦‚ćžść˛ˇćś‰é€‚ĺ˝“ĺĽşĺ¤§çš„ĺ·Ąĺ…·ďĽŚć•´ä¸Şçł»ç»źĺ°†ć— ćł•ĺś¨ä»»ä˝•ĺś°ć–ąćŁĺ¸¸ĺ·Ąä˝śă€‚关于如何使用 +这些工具的教程远远超出了本文档的čŚĺ›´ďĽŚä˝†ćŻčżćŻćś‰ä¸€äş›ćŚ‡ĺŤ—的空间。 + +ĺ°ç›®ĺ‰Ťä¸şć˘ďĽŚĺ†…ć ¸ç¤ľĺŚşä˝żç”¨çš„ä¸»č¦ćşä»Łç 管ç†çł»ç»źćŻgit。GitćŻĺś¨č‡Şç”±č˝Żä»¶ç¤ľĺŚşä¸ĺĽ€ĺŹ‘ +的许多ĺ†ĺ¸ĺĽŹç‰ćś¬ćŽ§ĺ¶çł»ç»źäą‹ä¸€ă€‚ĺ®éťžĺ¸¸é€‚ĺĺ†…ć ¸ĺĽ€ĺŹ‘ďĽŚĺ› ä¸şĺ®ĺś¨ĺ¤„ç†ĺ¤§ĺž‹ĺ储库和 +大量补ä¸ć—¶ć€§č˝éťžĺ¸¸ĺĄ˝ă€‚ĺ®čżćś‰ä¸€ä¸Şéšľä»Ąĺ¦äą 和使用的ĺŤĺŁ°ďĽŚĺ°˝ç®ˇéšŹçť€ć—¶é—´çš„ćŽ¨ç§»ĺ® +ĺŹĺľ—ć›´ĺĄ˝äş†ă€‚ĺŻąäşŽĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘来说，对Gitçš„ćźç§Ťç†źć‚‰ĺ‡ 乎ćŻä¸€ç§Ťč¦ć±‚；即使他们不 +ĺ°†ĺ®ç”¨äşŽč‡Şĺ·±çš„工作，他们也需č¦Git来跟上其他开发人ĺ‘ďĽä»ĄĺŹŠä¸»çşżďĽ‰ćŁĺś¨ĺšçš„äş‹ć…。 + +çŽ°ĺś¨ĺ‡ äąŽć‰€ćś‰çš„Linux发行ç‰é˝ć‰“包了Git。主页位于： + + http://git-scm.com/ + +那个页面有指ĺ‘文档和教程的指é’。 + +在不使用gitçš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ä¸ďĽŚćś€ćµčˇŚçš„é€‰ć‹©ĺ‡ äąŽč‚Żĺ®šćŻmercurial： + + http://www.seleric.com/mercurial/ + +Mercurial与Git共享许多特性，但ĺ®ćŹäľ›äş†ä¸€ä¸Şç•Śéť˘ďĽŚč®¸ĺ¤šäşşč§‰ĺľ—ĺ®ć›´ć“于使用。 + +另一个值得了解的工具ćŻquilt: + + http://savannah.nongnu.org/projects/quilt + +Quilt ćŻä¸€ä¸ŞčˇĄä¸ç®ˇç†çł»ç»źďĽŚč€Śä¸ŤćŻćşä»Łç 管ç†çł»ç»źă€‚ĺ®ä¸ŤäĽšéšŹçť€ć—¶é—´çš„推移跟踪历史； +相反，ĺ®éť˘ĺ‘ć ąćŤ®ä¸Ťć–发展的代ç 库跟踪一组特定的更改。一些主č¦çš„ĺçł»ç»źç»´ćŠ¤äşşĺ‘ +使用Quilt来管ç†ć‰“ç®—ĺ‘上游移动的补ä¸ă€‚对于ćźäş›ć ‘的管ç†ďĽäľ‹ĺ¦‚-mm），quilt ćŻ +最好的工具。 + +邮件ĺ—表 +-------- + +大量的Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ĺ·Ąä˝śćŻé€ščż‡é‚®ä»¶ĺ—表完ć的。如果不在ćźä¸Şĺś°ć–ąĺŠ 入至少一个ĺ—表， +ĺ°±ĺľéšľć为社区ä¸ä¸€ä¸ŞĺŠźč˝ĺ®Śĺ¤‡çš„ćĺ‘。但ćŻďĽŚLinux邮件ĺ—表对开发人ĺ‘来说也ćŻä¸€ä¸Ş +潜在的危险，他们可č˝äĽšč˘«ä¸€ĺ †ç”µĺ邮件淹没，违反Linuxĺ—表上使用的约定，ć–者 +两者兼而有之。 + +ĺ¤§ĺ¤šć•°ĺ†…ć ¸é‚®ä»¶ĺ—表é˝ĺś¨vger.kernel.org上čżčˇŚďĽ›ä¸»ĺ—表位于： + + http://vger.kernel.org/vger-lists.html + +不过，也有一些ĺ—表ć‰ç®ˇĺś¨ĺ«ĺ¤„；其ä¸ä¸€äş›ĺ—表位于lists.redhat.com。 + +ĺ˝“ç„¶ďĽŚĺ†…ć ¸ĺĽ€ĺŹ‘çš„ć ¸ĺżé‚®ä»¶ĺ—表ćŻlinux-kernel。这个ĺŤĺŤ•ćŻä¸€ä¸Şä»¤äşşç”źç•Źçš„地方； +每天的信ćŻé‡ŹĺŹŻä»Ąčľľĺ°500条，噪音ĺľé«ďĽŚč°čŻťćŠ€ćśŻć€§ĺľĺĽşďĽŚĺŹ‚与者并不总ćŻčˇ¨çŽ°ĺ‡ş +é«ĺş¦çš„礼貌。但ćŻďĽŚć˛ˇćś‰ĺ…¶ä»–ĺś°ć–ąĺŹŻä»Ąč®©ĺ†…ć ¸ĺĽ€ĺŹ‘ç¤ľĺŚşä˝śä¸şä¸€ä¸Şć•´ä˝“čšé›†ĺś¨ä¸€čµ·ďĽ› +éżĺ…Ťä˝żç”¨ć¤ĺ—表的开发人ĺ‘将错过重č¦äżˇćŻă€‚ + +有一些ćŹç¤şĺŹŻä»Ąĺ¸®ĺŠ©ĺś¨linux-kernel生ĺ： + +- 将邮件转移ĺ°ĺŤ•ç‹¬çš„文件夹，而不ćŻä¸»é‚®ç®±ă€‚ć‘们必须č˝ĺ¤źćŚç»ĺś°ĺż˝ç•Ąć´Şćµă€‚ + +- 不č¦čŻ•ĺ›ľč·źč¸ŞćŻŹä¸€ć¬ˇč°čŻť-其他人é˝ä¸ŤäĽšă€‚重č¦çš„ćŻč¦ĺŻąć„źĺ…´č¶Łçš„主é˘ďĽĺ°˝ç®ˇčŻ· + 注意，长时间的对话可以在不更改电ĺ邮件主é˘čˇŚçš„ć…况下ĺŹç¦»ĺŽźĺ§‹ä¸»é˘ďĽ‰ĺ’ŚĺŹ‚与 + 的人进行ç›é€‰ă€‚ + +- 不č¦ćŚ‘事。如果有人试图激起愤怒的反应，忽略他们。 + +- 当响应Linuxĺ†…ć ¸ç”µĺ邮件ďĽć–其他ĺ—表上的电ĺ邮件）时，请为所有相关人ĺ‘äżťç•™ + cc:header。如果没有强有力的ç†ç”±ďĽĺ¦‚ćŽçˇ®çš„请求），ĺ™ä¸Ťĺş”ĺ é™¤ć”¶ä»¶äşşă€‚ä¸€ĺ®šč¦ + çˇ®äżťä˝ č¦ĺ›žĺ¤Ťçš„人在cc:listä¸ă€‚这个ćŻäľ‹äąźä˝żä˝ 不必在回复邮件时ćŽçˇ®č¦ć±‚被抄é€ă€‚ + +- 在ćŹĺ‡şé—®é˘äą‹ĺ‰ŤďĽŚćśç´˘ĺ—表档ćˇďĽĺ’Ść•´ä¸Şç˝‘络）。有些开发人ĺ‘可č˝äĽšĺŻąé‚Łäş›ćľç„¶ + 没有完ć家ĺşä˝śä¸šçš„äşşć„źĺ°ä¸Ťč€ç¦ă€‚ + +- éżĺ…Ťč´´éˇ¶ĺ¸–ďĽćŠŠä˝ çš„ç”ćˇć”ľĺś¨ä˝ č¦ĺ›žĺ¤Ťçš„引文上面的ĺšćł•ďĽ‰ă€‚čż™äĽšč®©ä˝ çš„ĺ›žç”ć›´éšľ + ç†č§ŁďĽŚĺŤ°č±ˇäąźĺľĺ·®ă€‚ + +- 询问ćŁçˇ®çš„邮件ĺ—表。linux-kernel 可č˝ćŻé€šç”¨çš„讨论点，但ĺ®ä¸ŤćŻä»Žć‰€ćś‰ĺ系统 + ä¸ĺŻ»ć‰ľĺĽ€ĺŹ‘äşşĺ‘的最佳场所。 + +最ĺŽä¸€ç‚ąâ€”—找ĺ°ćŁçˇ®çš„邮件ĺ—表——ćŻĺĽ€ĺŹ‘äşşĺ‘出错的常č§ĺś°ć–ąă€‚在Linuxĺ†…ć ¸ä¸ŠćŹĺ‡şä¸Ž +网络相关的问é˘çš„äşşĺ‡ äąŽč‚Żĺ®šäĽšć”¶ĺ°ä¸€ä¸Şç¤Ľč˛Śçš„建议，转而在netdevĺ—表上ćŹĺ‡şďĽŚ +ĺ› ä¸şčż™ćŻĺ¤§ĺ¤šć•°ç˝‘络开发人ĺ‘经常出现的ĺ—表。čżćś‰ĺ…¶ä»–ĺ—表可用于scsi〠+video4linuxă€ideă€filesystemç‰ĺ系统。查找邮件ĺ—表的最佳位置ćŻä¸Žĺ†…ć ¸ćşä»Łç +一起打包的MAINTAINERS文件。 + +ĺĽ€ĺ§‹ĺ†…ć ¸ĺĽ€ĺŹ‘ +------------ + +ĺ…łäşŽĺ¦‚ä˝•ĺĽ€ĺ§‹ĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹çš„é—®é˘ĺľĺ¸¸č§â€”—来自个人和公司。ĺŚć ·ĺ¸¸č§çš„ćŻé”™čŻŻďĽŚčż™ +使得关系的开始比必须的更困难。 + +公司通常希望č请知ĺŤçš„开发人ĺ‘来ĺŻĺŠ¨ĺĽ€ĺŹ‘团éźă€‚实际上，这ćŻä¸€ç§Ťćś‰ć•çš„技术。 +但ĺ®äąźĺľ€ĺľ€ćŻć‚č´µçš„ďĽŚč€Śä¸”ć˛ˇćś‰ĺ˘žé•żç»ŹéŞŚä¸°ĺŻŚçš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘储备。č€č™‘ĺ°ć—¶é—´çš„ +投入，可以让内é¨ĺĽ€ĺŹ‘äşşĺ‘ĺŠ ĺż«Linuxĺ†…ć ¸çš„ĺĽ€ĺŹ‘é€źĺş¦ă€‚čŠ±čż™ä¸Şć—¶é—´ĺŹŻä»Ąč®©é›‡ä¸»ć‹Ąćś‰ +ä¸€ć‰ąäş†č§Łĺ†…ć ¸ĺ’Śĺ…¬ĺŹ¸çš„ĺĽ€ĺŹ‘äşşĺ‘，他们也可以帮助培č®ĺ…¶ä»–人。从ä¸ćśźćťĄçś‹ďĽŚčż™ĺľ€ĺľ€ +ćŻć›´ćś‰ĺ©ĺŹŻĺ›ľçš„方法。 + +可以ç†č§Łçš„ćŻďĽŚĺŤ•ä¸ŞĺĽ€ĺŹ‘äşşĺ‘往往对起ćĄć„źĺ°čŚ«ç„¶ă€‚从一个大型项目开始可č˝äĽšĺľ +ĺ“人；人们往往ćłĺ…用一些čľĺ°Źçš„东西来测试水域。这ćŻä¸€äş›ĺĽ€ĺŹ‘äşşĺ‘开始ĺ›ĺ»şäż®čˇĄ +拼写错误ć–轻微编ç éŁŽć Ľé—®é˘çš„补ä¸çš„地方。不幸的ćŻďĽŚčż™ć ·çš„补ä¸äĽšäş§ç”źä¸€ĺ®šç¨‹ĺş¦ +的噪音，这会ĺ†ć•Łć•´ä¸ŞĺĽ€ĺŹ‘ç¤ľĺŚşçš„ćł¨ć„ŹĺŠ›ďĽŚĺ› ć¤ďĽŚč¶ŠćťĄč¶Šĺ¤šçš„人看不起ĺ®ä»¬ă€‚ĺ¸Śćś›ĺ‘ +社区介绍自己的新开发人ĺ‘ĺ°†ć— ćł•é€ščż‡čż™äş›ć–ąĺĽŹčŽ·ĺľ—ä»–ä»¬ćłč¦çš„那种接待。 + +Andrew Morton ä¸şćś‰ćŠ±č´źçš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ćŹäľ›äş†čż™ä¸Şĺ»şč®® + +:: + + ć‰€ćś‰ĺ†…ć ¸ĺťĺ¦č€…çš„No.1项目肯定ćŻâ€śçˇ®äżťĺ†…ć ¸ĺś¨ć‰€ćś‰çš„ćśşĺ™¨ä¸ŠďĽŚä˝ ĺŹŻä»Ąč§¦ć‘¸ + ĺ°çš„，始ç»čżčˇŚč‰ŻĺĄ˝" é€šĺ¸¸čż™ć ·ĺšçš„ć–ąćł•ćŻä¸Žĺ…¶ä»–人一起解决问é˘ďĽčż™ + 可č˝éś€č¦ĺťšćŚďĽďĽ‰ä˝†čż™ĺľĺĄ˝â€”—这ćŻĺ†…ć ¸ĺĽ€ĺŹ‘çš„ä¸€é¨ĺ† + +(http://lwn.net/articles/283982/) + +在没有ćŽćľé—®é˘éś€č¦č§Łĺ†łçš„ć…况下，建议开发人ĺ‘查看当前的回归和开放式错误ĺ—表. +解决需č¦äż®ĺ¤Ťçš„é—®é˘ć˛ˇćś‰ä»»ä˝•çĽşç‚ąďĽ›é€ščż‡č§Łĺ†łčż™äş›é—®é˘ďĽŚĺĽ€ĺŹ‘äşşĺ‘将获得处ç†čż‡ç¨‹çš„ +经验，ĺŚć—¶ä¸ŽĺĽ€ĺŹ‘社区的其他人建立尊重。 diff --git a/Documentation/translations/zh_CN/process/3.Early-stage.rst b/Documentation/translations/zh_CN/process/3.Early-stage.rst new file mode 100644 index 000000000000..b8676aec6005 --- /dev/null +++ b/Documentation/translations/zh_CN/process/3.Early-stage.rst @@ -0,0 +1,161 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/3.Early-stage.rst <development_early_stage>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_early_stage: + +ć—©ćśźč§„ĺ’ +======== + +当č€č™‘一个Linuxĺ†…ć ¸ĺĽ€ĺŹ‘éˇąç›®ć—¶ďĽŚĺľĺŹŻč˝äĽšç›´ćŽĄč·łčż›ĺŽ»ĺĽ€ĺ§‹çĽ–ç ă€‚ç„¶č€ŚďĽŚä¸Žä»»ä˝•é‡Ťč¦ +çš„éˇąç›®ä¸€ć ·ďĽŚć功的许多基础最好ćŻĺś¨ç¬¬ä¸€čˇŚä»Łç 编写之前就ĺšĺĄ˝äş†ă€‚在早期计ĺ’ĺ’Ś +沟通ä¸čŠ±č´ąä¸€äş›ć—¶é—´ĺŹŻä»ĄčŠ‚çść›´ĺ¤šçš„时间。 + +čŻ¦čż°é—®é˘ +-------- + +ä¸Žä»»ä˝•ĺ·Ąç¨‹éˇąç›®ä¸€ć ·ďĽŚćĺŠźçš„ĺ†…ć ¸ĺ˘žĺĽşä»Žč¦č§Łĺ†łçš„é—®é˘çš„清晰描述开始。在ćźäş›ć…况 +下，这个ćĄéޤĺľĺ®ąć“：例如，当ćźä¸Şç‰ąĺ®šçˇ¬ä»¶éś€č¦é©±ĺŠ¨ç¨‹ĺşŹć—¶ă€‚不过，在其他方面， +将实际问é˘ä¸Žĺ»şč®®çš„解决方ćˇć··ć·†ćŻĺľćś‰čŻ±ć‘力的，这可č˝äĽšĺŻĽč‡´ĺ›°éšľă€‚ + +举个例ĺďĽšĺ‡ ĺą´ĺ‰ŤďĽŚä˝żç”¨Linux音频的开发人ĺ‘寻求一种方法来čżčˇŚĺş”ç”¨ç¨‹ĺşŹďĽŚč€Śä¸Ťĺ› +系统延迟过大而导致退出ć–其他工件。他们得ĺ°çš„解决方ćˇćŻä¸€ä¸Şĺ†…ć ¸ć¨ˇĺť—ďĽŚć—¨ĺś¨čżž +接ĺ°Linux安全模块ďĽLSM）框架ä¸ďĽ›čż™ä¸Şć¨ˇĺť—可以配置为ĺ…许特定的应用程序访问 +实时č°ĺş¦ç¨‹ĺşŹă€‚这个模块被实现并发é€ĺ°Linuxĺ†…ć ¸é‚®ä»¶ĺ—表，在那里ĺ®ç«‹ĺŤłé‡ĺ°é—®é˘ă€‚ + +对于音频开发人ĺ‘来说，这个安全模块足以解决他们当前的问é˘ă€‚但ćŻďĽŚĺŻąäşŽć›´ĺążćł›çš„ +ĺ†…ć ¸ç¤ľĺŚşćťĄčŻ´ďĽŚčż™č˘«č§†ä¸şĺŻąLSM框架的滥用ďĽLSM框架并不打算ćŽäşä»–们原本不具备的 +进程特ćťďĽ‰ďĽŚĺą¶ĺŻąçł»ç»źç¨łĺ®šć€§é€ ć风险。他们首选的解决方ćˇĺŚ…括çźćśźçš„通过rlimit +ćśşĺ¶čż›čˇŚĺ®žć—¶č°ĺş¦č®żé—®ďĽŚä»ĄĺŹŠé•żćśźçš„减少延迟的工作。 + +然而，音频社区看不ĺ°ä»–们实施的特定解决方ćˇçš„过去；他们不愿意接受替代方ćˇă€‚ +ç”±ć¤äş§ç”źçš„ĺ†ć§ä˝żčż™äş›ĺĽ€ĺŹ‘äşşĺ‘ĺŻąć•´ä¸Şĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹ć„źĺ°ĺ¤±ćś›ďĽ›ĺ…¶ä¸ä¸€ä¸ŞĺĽ€ĺŹ‘äşşĺ‘返回 +ĺ°éźłé˘‘ĺ—表并发ĺ¸äş†ä»Ąä¸‹ĺ†…容： + + 有ĺľĺ¤šéťžĺ¸¸ĺĄ˝çš„Linuxĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘，但他们往往会被一群傲慢的傻瓜所压倒。 + 试图ĺ‘čż™äş›äşşäĽ čľľç”¨ć·éś€ć±‚ćŻćµŞč´ąć—¶é—´ă€‚他们太“čŞćŽâ€ťäş†ďĽŚć ąćś¬ĺ¬ä¸Ťĺ°ĺ°‘ć•°äşş + 的话。 + +ďĽhttp://lwn.net/articles/131776/） + +实际ć…况不ĺŚďĽ›ä¸Žç‰ąĺ®šć¨ˇĺť—ç›¸ćŻ”ďĽŚĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ć›´ĺ…łĺżçł»ç»źç¨łĺ®šć€§ă€é•żćśźç»´ćŠ¤ä»ĄĺŹŠć‰ľĺ° +ćŁçˇ®çš„é—®é˘č§Łĺ†łć–ąćˇă€‚这个故事的寓意ćŻćŠŠé‡Ťç‚ąć”ľĺś¨é—®é˘ä¸Šâ€”—而不ćŻĺ…·ä˝“çš„č§Łĺ†łć–ąćˇ +上——并在投入ĺ›ĺ»şä»Łç 之前与开发社区讨论这个问é˘ă€‚ + +ĺ› ć¤ďĽŚĺś¨č€č™‘ä¸€ä¸Şĺ†…ć ¸ĺĽ€ĺŹ‘éˇąç›®ć—¶ďĽŚć‘们应该得ĺ°ä¸€ç»„简çźé—®é˘çš„ç”ćˇďĽš + + - 究竟需č¦č§Łĺ†łçš„é—®é˘ćŻä»€äąďĽź + + - 受ć¤é—®é˘ĺ˝±ĺ“Ťçš„用ć·ćŻč°ďĽźč§Łĺ†łć–ąćˇĺş”该解决哪些用例？ + + - ĺ†…ć ¸çŽ°ĺś¨ä¸şä˝•ć˛ˇč˝č§Łĺ†łčż™ä¸Şé—®é˘ďĽź + +ĺŹŞćś‰čż™ć ·ďĽŚć‰Ťč˝ĺĽ€ĺ§‹č€č™‘可č˝çš„解决方ćˇă€‚ + + +早期讨论 +-------- + +在计ĺ’ĺ†…ć ¸ĺĽ€ĺŹ‘éˇąç›®ć—¶ďĽŚĺś¨ĺĽ€ĺ§‹ĺ®žć–˝äą‹ĺ‰Ťä¸Žç¤ľĺŚşčż›čˇŚč®¨č®şćŻĺľćś‰ć„Źäą‰çš„。早期沟通可以 +通过多种方式节çść—¶é—´ĺ’Śéş»ç¦ďĽš + + - ĺľĺŹŻč˝é—®é˘ćŻç”±ĺ†…ć ¸ä»Ąć‚¨ä¸Ťç†č§Łçš„方式解决的。Linuxĺ†…ć ¸ĺľĺ¤§ďĽŚĺ…·ćś‰č®¸ĺ¤šä¸ŤćŽćľ + 的特性和功č˝ă€‚并不ćŻć‰€ćś‰çš„ĺ†…ć ¸ĺŠźč˝é˝ĺŹäşşä»¬ć‰€ĺ¸Śćś›çš„é‚Łć ·ćś‰ć–‡ćˇŁč®°ĺ˝•ďĽŚč€Śä¸”ĺľ + 容ć“é—ćĽŹä¸€äş›ä¸śčĄżă€‚ä˝ çš„ä˝śč€…ĺŹ‘ĺ‡şäş†ä¸€ä¸Şĺ®Ść•´çš„é©±ĺŠ¨ç¨‹ĺşŹďĽŚĺ¤Ťĺ¶äş†ä¸€ä¸Şć–°ä˝śč€…不 + 知é“的现有驱动程序。重新设计现有轮ĺ的代ç 不仅浪费，而且不会被接受ĺ°ä¸»çşż + ĺ†…ć ¸ä¸ă€‚ + + - 建议的解决方ćˇä¸ĺŹŻč˝ćś‰ä¸€äş›ĺ…ç´ ä¸Ťé€‚ç”¨äşŽä¸»çşżĺ并。在编写代ç äą‹ĺ‰ŤďĽŚćś€ĺĄ˝ĺ… + äş†č§Łčż™ć ·çš„é—®é˘ă€‚ + + - 其他开发人ĺ‘完全有可č˝č€č™‘过这个问é˘ďĽ›ä»–们可č˝ćś‰ć›´ĺĄ˝çš„解决方ćˇçš„ćłćł•ďĽŚĺą¶ä¸” + 可č˝ć„żć„Źĺ¸®ĺŠ©ĺ›ĺ»şčż™ä¸Şč§Łĺ†łć–ąćˇă€‚ + +ĺś¨ĺ†…ć ¸ĺĽ€ĺŹ‘ç¤ľĺŚşçš„ĺ¤šĺą´ç»ŹéŞŚç»™äş†ć‘们一个ćŽçˇ®çš„ć•™č®ďĽšé—é—¨č®ľč®ˇĺ’ŚĺĽ€ĺŹ‘çš„ĺ†…ć ¸ä»Łç ć€»ćŻ +有一些问é˘ďĽŚčż™äş›é—®é˘ĺŹŞćś‰ĺś¨ä»Łç 发ĺ¸ĺ°ç¤ľĺŚşä¸ć—¶ć‰ŤäĽšč˘«ĺŹ‘现。有时这些问é˘ĺľä¸Ąé‡ŤďĽŚ +需č¦ć•°ćść–数年的努力才č˝ä˝żä»Łç čľľĺ°ĺ†…ć ¸ç¤ľĺŚşçš„ć ‡ĺ‡†ă€‚ä¸€äş›äľ‹ĺ包括： + + - 设计并实现了单处ç†ĺ™¨çł»ç»źçš„DeviceScape网络ć 。只有使其适ĺ于多处ç†ĺ™¨çł»ç»źďĽŚ + 才č˝ĺ°†ĺ…¶ĺ并ĺ°ä¸»çşżä¸ă€‚在代ç ä¸ć”ąčŁ…é”ç‰ç‰ćŻä¸€éˇąĺ›°éšľçš„ä»»ĺŠˇďĽ›ĺ› ć¤ďĽŚčż™ć®µä»Łç + ďĽçŽ°ĺś¨ç§°ä¸şmac80211）的ĺ并被推迟了一年多。 + + - Reiser4文件系统包ĺ«č®¸ĺ¤šĺŠźč˝ďĽŚć ¸ĺżĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘认为这些功č˝ĺş”该在虚拟文件 + 系统层ä¸ĺ®žçŽ°ă€‚ĺ®čżĺŚ…括一些特性，这些特性在不将系统暴露于用ć·ĺĽ•čµ·çš„ć»é”çš„ + ć…况下ćŻä¸Ťĺ®ąć“实现的。这些问é˘çš„最新发现——以及对其ä¸ä¸€äş›é—®é˘çš„拒绝——已经 + 导致Reiser4čżśç¦»äş†ä¸»çşżĺ†…ć ¸ă€‚ + + - Apparmorĺ®‰ĺ…¨ć¨ˇĺť—ä»Ąč˘«č®¤ä¸şä¸Ťĺ®‰ĺ…¨ĺ’Śä¸ŤĺŹŻéť çš„ć–ąĺĽŹä˝żç”¨ĺ†…é¨č™šć‹źć–‡ä»¶çł»ç»źć•°ćŤ®ç»“构。 + 这种担ĺżďĽĺŚ…括其他）使Apparmor多年不在主线上。 + +在每一种ć…ĺ†µä¸‹ďĽŚé€ščż‡ä¸Žĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘的早期讨论，可以éżĺ…Ťĺ¤§é‡Źçš„痛苦和额外的工作。 + +找č°äş¤ćµ +-------- + +当开发人ĺ‘决定公开他们的计ĺ’时，下一个问é˘ćŻďĽšć‘们从哪里开始？ç”ćˇćŻć‰ľĺ°ćŁçˇ® +的邮件ĺ—表和ćŁçˇ®çš„维护者。对于邮件ĺ—表，最好的方法ćŻĺś¨ç»´ćŠ¤č€…(MAINTAINERS)文件 +ä¸ćźĄć‰ľč¦ĺŹ‘ĺ¸çš„相关位置。如果有一个ĺ适的ĺ系统ĺ—表，那äąĺŹ‘ĺ¸ĺ®é€šĺ¸¸ćŻ”在Linux +ĺ†…ć ¸ä¸ŠĺŹ‘ĺ¸ć›´ĺŹŻĺŹ–；您更有可č˝ćŽĄč§¦ĺ°ĺś¨ç›¸ĺ…łĺ系统ä¸ĺ…·ćś‰ä¸“业知识的开发人ĺ‘，并且 +环ĺ˘ĺŹŻč˝ĺ…·ć”ŻćŚć€§ă€‚ + +找ĺ°ç»´ćŠ¤äşşĺ‘可č˝äĽšćś‰ç‚ąĺ›°éšľă€‚ĺŚć ·ďĽŚç»´ćŠ¤č€…文件ćŻĺĽ€ĺ§‹çš„地方。但ćŻďĽŚčŻĄć–‡ä»¶ĺľ€ĺľ€ä¸Ťć€» +ćŻćś€ć–°çš„，并且并非所有ĺ系统é˝ĺś¨é‚Łé‡Śčˇ¨ç¤şă€‚实际上，维护者文件ä¸ĺ—出的人ĺ‘ĺŹŻč˝ +不ćŻĺ˝“前实际担任该角色的人ĺ‘ă€‚ĺ› ć¤ďĽŚĺ˝“对č”çł»č°ćś‰ç–‘问时，一个有用的技巧ćŻä˝żç”¨ +gitďĽĺ°¤ĺ…¶ćŻâ€śgit-log”）查看感兴趣的ĺ系统ä¸ĺ˝“前活动的用ć·ă€‚çś‹çś‹č°ĺś¨ĺ†™čˇĄä¸ďĽŚ +如果有人的话，č°äĽšĺś¨čż™äş›čˇĄä¸ä¸ŠĺŠ 上用线çľĺŤçš„。这些人将ćŻĺ¸®ĺŠ©ć–°ĺĽ€ĺŹ‘项目的最佳 +人选。 + +找ĺ°ĺ适的维护者的任务有时ćŻéťžĺ¸¸ĺ…·ćś‰ćŚ‘ćć€§çš„ďĽŚä»Ąč‡łäşŽĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ć·»ĺŠ äş†ä¸€ä¸Ş +脚本来简化过程： + +:: + + .../scripts/get_maintainer.pl + +当给定“-f”选项时，ć¤č„šćś¬ĺ°†čż”回给定文件ć–ç›®ĺ˝•çš„ĺ˝“ĺ‰Ťç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśĺś¨ĺ‘˝ä»¤čˇŚä¸ŠäĽ é€’ +了一个补ä¸ďĽŚĺ®ĺ°†ĺ—出可č˝ćŽĄć”¶čˇĄä¸ĺ‰Żćś¬çš„维护人ĺ‘。有许多选项可以č°čŠ‚ +get_maintainer.plćśç´˘ç»´ćŠ¤č€…çš„éšľć“程度；请小ĺżä˝żç”¨ć›´ĺ…·ć”»ĺ‡»ć€§çš„é€‰éˇąďĽŚĺ› ä¸şćś€ç» +可č˝äĽšĺŚ…括对您ćŁĺś¨äż®ć”ąçš„代ç 没有真ćŁĺ…´č¶Łçš„开发人ĺ‘。 + +如果所有其他方法é˝ĺ¤±č´Ąäş†ďĽŚé‚Łäąä¸ŽAndrew Morton交č°ĺŹŻä»Ąć为一种有ć•çš„方法来跟踪 +特定代ç 段的维护人ĺ‘。 + +何时邮寄？ +---------- + +如果可č˝çš„话，在早期é¶ć®µĺŹ‘ĺ¸ä˝ 的计ĺ’只会有帮助。描述ćŁĺś¨č§Łĺ†łçš„é—®é˘ä»ĄĺŹŠĺ·˛ç»Ź +ĺ¶ĺ®šçš„关于如何实施的任何计ĺ’。您可以ćŹäľ›çš„任何信ćŻé˝ĺŹŻä»Ąĺ¸®ĺŠ©ĺĽ€ĺŹ‘社区为项目 +ćŹäľ›ćś‰ç”¨çš„输入。 + +在这个é¶ć®µĺŹŻč˝ĺŹ‘生的一件令人沮丧的事ć…不ćŻć•ŚĺŻąçš„反应，而ćŻĺľĺ°‘ć–ć ąćś¬ć˛ˇćś‰ +反应。可悲的事实ćŻďĽšďĽ1ďĽ‰ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘往往ĺľĺż™ďĽ›ďĽ2）不缺少有宏伟计ĺ’ĺ’Śĺľĺ°‘ +代ç ďĽç”šč‡łä»Łç 前景）支ćŚä»–们的人；ďĽ3）没有人有义务审查ć–评论ĺ«äşşĺŹ‘表的 +ćłćł•ă€‚除ć¤äą‹ĺ¤–，é«çş§č®ľč®ˇĺ¸¸ĺ¸¸éšč—Źä¸€äş›é—®é˘ďĽŚčż™äş›é—®é˘ĺŹŞćś‰ĺś¨ćś‰äşşçśźćŁĺ°ťčŻ•ĺ®žçŽ° +čż™äş›č®ľč®ˇć—¶ć‰ŤäĽšč˘«ĺŹ‘çŽ°ďĽ›ĺ› ć¤ďĽŚĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ĺ®ć„żçś‹ĺ°ä»Łç 。 + +如果发表评论的请求在评论的方式上没有什äąć•ćžśďĽŚä¸Ťč¦ĺ‡č®ľčż™ć„Źĺ‘łçť€ĺŻąéˇąç›®ć˛ˇćś‰ +兴趣。不幸的ćŻďĽŚä˝ 也不č˝ĺ‡č®ľä˝ çš„ćłćł•ć˛ˇćś‰é—®é˘ă€‚在这种ć…况下，最好的ĺšćł•ćŻ +继ç»čż›čˇŚďĽŚćŠŠä˝ 的进展随时通知社区。 + +获得ĺ®ć–ąč®¤ĺŹŻ +----------------------- + +如果您的工作ćŻĺś¨ĺ…¬ĺŹ¸çŽŻĺ˘ä¸ĺ®Ść的，就ĺŹĺ¤§ĺ¤šć•°Linuxĺ†…ć ¸ĺ·Ąä˝śä¸€ć ·ďĽŚćľç„¶ďĽŚĺś¨ć‚¨ĺ°† +公司的计ĺ’ć–代ç 发ĺ¸ĺ°ĺ…¬ĺ…±é‚®ä»¶ĺ—表之前，必须获得适当ćŽćťçš„经ç†çš„č®¸ĺŹŻă€‚ĺŹ‘ĺ¸ +不确定ćŻĺ¦ĺ…Ľĺ®ąGPL的代ç 可č˝ćŻćś‰ç‰ąĺ«é—®é˘çš„；公司的管ç†ĺ±‚ĺ’Śćł•ĺľ‹äşşĺ‘越早č˝ĺ¤źĺ°± +发ĺ¸ĺ†…ć ¸ĺĽ€ĺŹ‘éˇąç›®čľľć一致，对参与的每个人é˝č¶ŠĺĄ˝ă€‚ + +一些读者可č˝äĽšč®¤ä¸şä»–ä»¬çš„ć ¸ĺżĺ·Ąä˝śćŻä¸şäş†ć”ŻćŚčżć˛ˇćś‰ćŁĺĽŹć‰żč®¤ĺ在的产ĺ“。将雇主 +的计ĺ’ĺ…¬ĺ¸ĺś¨ĺ…¬ĺ…±é‚®ä»¶ĺ—表上可č˝ä¸ŤćŻä¸€ä¸ŞĺŹŻčˇŚçš„选择。在这种ć…况下，有必č¦č€č™‘ +保密ćŻĺ¦çśźçš„ćŻĺż…č¦çš„；通常不需č¦ćŠŠĺĽ€ĺŹ‘计ĺ’关在门内。 + +äąźĺ°±ćŻčŻ´ďĽŚćś‰äş›ć…况下，一家公司在开发过程的早期就不č˝ĺ法地披露其计ĺ’。拥有 +ç»ŹéŞŚä¸°ĺŻŚçš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘的公司可以选择以开环的方式进行，前ćŹćŻä»–们以ĺŽč˝ĺ¤źéżĺ…Ť +严重的集ćé—®é˘ă€‚对于没有这种内é¨ä¸“业知识的公司，最好的选择往往ćŻččŻ·ĺ¤–é¨ +ĺĽ€ĺŹ‘ĺ•†ć ąćŤ®äżťĺŻ†ĺŤŹč®®ĺ®ˇćźĄč®ˇĺ’。Linux基金会čżčˇŚäş†ä¸€ä¸ŞNDA程序，旨在帮助解决这种 +ć…况； + + http://www.linuxfoundation.org/en/NDA_program + +这种审查通常足以éżĺ…Ťä»ĄĺŽĺ‡şçŽ°ä¸Ąé‡Ťé—®é˘ďĽŚč€Ść— 需公开披露项目。 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst new file mode 100644 index 000000000000..5301e9d55255 --- /dev/null +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -0,0 +1,290 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/4.Coding.rst <development_coding>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_coding: + +使代ç ćŁçˇ® +====================== + +虽然对于一个坚实的ă€éť˘ĺ‘社区的设计过程有ĺľĺ¤ščŻťč¦čŻ´ďĽŚä˝†ćŻä»»ä˝•ĺ†…ć ¸ĺĽ€ĺŹ‘éˇąç›®çš„ +čŻćŽé˝ĺś¨ç”źć的代ç ä¸ă€‚ĺ®ćŻĺ°†ç”±ĺ…¶ä»–开发人ĺ‘检查并ĺ并ďĽć–不ĺ并）ĺ°ä¸»çşżć ‘ä¸ +的代ç 。所以这段代ç 的质量决定了项目的最ç»ć功。 + +本节将检查编ç 过程。ć‘ä»¬ĺ°†ä»Žĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ĺ‡şé”™çš„ĺ‡ ç§Ťć–ąĺĽŹĺĽ€ĺ§‹ă€‚ç„¶ĺŽé‡Ťç‚ąĺ°†č˝¬ç§» +ĺ°ćŁçˇ®çš„äş‹ć…和可以帮助这个任务的工具上。 + +é™·é± +---- + +编ç éŁŽć Ľ +******** + +ĺ†…ć ¸é•żćśźä»ĄćťĄé˝ćś‰ä¸€ç§Ťć ‡ĺ‡†çš„编ç éŁŽć ĽďĽŚĺ¦‚ +:ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` +ä¸ć‰€čż°ă€‚在大é¨ĺ†ć—¶é—´é‡ŚďĽŚčŻĄć–‡ä»¶ä¸ćŹŹčż°çš„政ç–被认为至多ćŻĺ»şč®®ć€§çš„ă€‚ĺ› ć¤ďĽŚĺ†…ć ¸ +ä¸ĺ在大量不符ĺ编ç éŁŽć Ľĺ‡†ĺ™çš„代ç 。代ç çš„ĺĺś¨äĽšç»™ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘带来两个独立 +的危害。 + +首ĺ…，č¦ç›¸äżˇĺ†…ć ¸çĽ–ç ć ‡ĺ‡†ĺą¶ä¸Ťé‡Ťč¦ďĽŚäąźä¸ŤĺĽşĺ¶ć‰§čˇŚă€‚äş‹ĺ®žä¸ŠďĽŚĺ¦‚ćžść˛ˇćś‰ćŚ‰ç…§ć ‡ĺ‡†ĺŻąä»Ł +ç 进行编ç ，那äąĺ‘ĺ†…ć ¸ć·»ĺŠ ć–°ä»Łç ćŻéťžĺ¸¸ĺ›°éšľçš„；许多开发人ĺ‘甚至会在审查代ç äą‹ +前č¦ć±‚对代ç čż›čˇŚé‡Ťć–°ć ĽĺĽŹĺŚ–ă€‚ä¸€ä¸Şä¸Žĺ†…ć ¸ä¸€ć ·ĺ¤§çš„ä»Łç 库需č¦ä¸€äş›ç»źä¸€çš„代ç ，以使 +开发人ĺ‘č˝ĺ¤źĺż«é€źç†č§Łĺ…¶ä¸çš„任何é¨ĺ†ă€‚所以已经没有空间来ĺć”ľĺĄ‡ć€Şçš„ć ĽĺĽŹĺŚ–ä»Łç 了。 + +ĺ¶ĺ°”ďĽŚĺ†…ć ¸çš„çĽ–ç éŁŽć ĽäĽšä¸Žé›‡ä¸»çš„ĺĽşĺ¶éŁŽć ĽĺŹ‘生冲çŞă€‚在这种ć…ĺ†µä¸‹ďĽŚĺ†…ć ¸çš„éŁŽć Ľĺż…éˇ» +在代ç ĺ并之前获čśă€‚将代ç ć”ľĺ…Ąĺ†…ć ¸ć„Źĺ‘łçť€ä»Ąĺ¤šç§Ťć–ąĺĽŹć”ľĺĽä¸€ĺ®šç¨‹ĺş¦çš„控ĺ¶ćťâ€”—包括 +控ĺ¶ä»Łç çš„ć ĽĺĽŹĺŚ–ć–ąĺĽŹă€‚ + +另一个陷é±ćŻĺ‡ĺ®šĺ·˛ç»Źĺś¨ĺ†…ć ¸ä¸çš„代ç čż«ĺ‡éś€č¦çĽ–ç ć ·ĺĽŹçš„äż®ĺ¤Ťă€‚ĺĽ€ĺŹ‘äşşĺ‘可č˝äĽšĺĽ€ĺ§‹ +生ćé‡Ťć–°ć ĽĺĽŹĺŚ–čˇĄä¸ďĽŚä˝śä¸şç†źć‚‰čż‡ç¨‹çš„一种方式，ć–者作为将其ĺŤç§°ĺ†™ĺ…Ąĺ†…ć ¸ĺŹć›´ć—Ąĺż— +的一种方式，ć–者两者兼而有之。但ćŻçşŻçĽ–ç éŁŽć Ľçš„äż®ĺ¤Ťč˘«ĺĽ€ĺŹ‘ç¤ľĺŚşč§†ä¸şĺ™ŞéźłďĽ›ĺ®ä»¬ĺľ€ +往受ĺ°ĺ†·é‡ă€‚ĺ› ć¤ďĽŚćś€ĺĄ˝éżĺ…Ťä˝żç”¨čż™ç§Ťç±»ĺž‹çš„补ä¸ă€‚ç”±äşŽĺ…¶ä»–ĺŽźĺ› ďĽŚĺś¨ĺ¤„ç†ä¸€ć®µä»Łç çš„ +ĺŚć—¶äż®ĺ¤Ťĺ®çš„ć ·ĺĽŹćŻĺľč‡Şç„¶çš„，但ćŻçĽ–ç ć ·ĺĽŹçš„ć›´ć”ąä¸Ťĺş”čŻĄä»…ä¸şäş†ć›´ć”ąč€Śčż›čˇŚă€‚ + +编ç éŁŽć Ľçš„ć–‡ćˇŁäąźä¸Ťĺş”čŻĄč˘«č§†ä¸şç»ťĺŻąçš„ćł•ĺľ‹ďĽŚčż™ćŻć°¸čżśä¸ŤäĽšč˘«čżťĺŹŤçš„。如果有一个ĺľĺĄ˝ +çš„ç†ç”±ĺŹŤĺŻąčż™ç§Ťć ·ĺĽŹďĽäľ‹ĺ¦‚，如果拆ĺ†ä¸şé€‚ĺ80ĺ—é™ĺ¶çš„行，那äąĺ®çš„可读性就会大大 +降低），那äąĺ°±čż™ć ·ĺšă€‚ + +请注意，您čżĺŹŻä»Ąä˝żç”¨ ``clang-format`` 工具来帮助您处ç†čż™äş›č§„ĺ™ďĽŚč‡ŞĺŠ¨é‡Ťć–°ć ĽĺĽŹ +化é¨ĺ†ä»Łç ，并查看完整的文件，以发现编ç ć ·ĺĽŹé”™čŻŻă€ć‹Ľĺ†™é”™čŻŻĺ’ŚĺŹŻč˝çš„改进。ĺ®čż +可以方便地进行排序，包括对é˝ĺŹé‡Ź/宏ă€ĺ›žćµć–‡ćś¬ĺ’Śĺ…¶ä»–类似任务。有关详细信ćŻďĽŚčŻ· +参é…文件 :ref:`Documentation/process/clang-format.rst <clangformat>` + +抽象层 +****** + +计算机科ĺ¦ć•™ćŽć•™ĺ¦ç”źä»Ąçµć´»ć€§ĺ’ŚäżˇćŻéšč—Źçš„ĺŤäą‰ĺążćł›ä˝żç”¨ćŠ˝č±ˇĺ±‚ă€‚ĺ˝“ç„¶ďĽŚĺ†…ć ¸ĺążćł› +地使用了抽象；任何涉及数百万行代ç 的项目é˝ä¸Ťč˝ĺšĺ°čż™ä¸€ç‚ąĺą¶ĺ活下来。但经验 +表ćŽďĽŚčż‡ĺş¦ć–过早的抽象可č˝ĺ’Śčż‡ć—©çš„äĽĺŚ–ä¸€ć ·ćś‰ĺ®łă€‚ćŠ˝č±ˇĺş”ç”¨äşŽć‰€éś€çš„çş§ĺ«ďĽŚ +不č¦čż‡ĺş¦ă€‚ + +在一个简单的级ĺ«ä¸ŠďĽŚč€č™‘一个函数的参数，该参数总ćŻç”±ć‰€ćś‰č°ç”¨ć–ąä˝śä¸şé›¶äĽ 递。 +ć‘们可以保留这个论点: 以é˛ćś‰äşşćś€ç»éś€č¦ä˝żç”¨ĺ®ćŹäľ›çš„额外çµć´»ć€§ă€‚不过，ĺ°é‚Łć—¶ďĽŚ +实现这个额外参数的代ç ĺľćś‰ĺŹŻč˝ä»Ąćźç§Ťä»ŽćśŞč˘«ćł¨ć„Źĺ°çš„ĺľ®ĺ¦™ć–ąĺĽŹč˘«ç ´ĺťŹâ€”â€”ĺ› ä¸şĺ®ä»Ž +未被使用过。ć–者，当需č¦é˘ťĺ¤–çš„çµć´»ć€§ć—¶ďĽŚĺ®ä¸ŤäĽšä»Ąç¬¦ĺ程序ĺ‘早期期望的方式来 +čż™ć ·ĺšă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘通常会ćŹäş¤čˇĄä¸ćťĄĺ 除未使用的参数；一č¬ćťĄčŻ´ďĽŚé¦–ĺ…不应该 +ć·»ĺŠ čż™äş›ĺŹ‚ć•°ă€‚ + +éšč—Źçˇ¬ä»¶č®żé—®çš„抽象层——通常ĺ…许大量的驱动程序在多个操作系统ä¸ä˝żç”¨â€”—尤其不受 +ć¬˘čżŽă€‚čż™ć ·çš„ĺ±‚ä˝żä»Łç ĺŹĺľ—模糊，可č˝äĽšé€ ć性č˝ćŤźĺ¤±ďĽ›ĺ®ä»¬ä¸Ťĺ±žäşŽLinuxĺ†…ć ¸ă€‚ + +ĺŹ¦ä¸€ć–ąéť˘ďĽŚĺ¦‚ćžść‚¨ĺŹ‘çŽ°č‡Şĺ·±ä»ŽĺŹ¦ä¸€ä¸Şĺ†…ć ¸ĺ系统复ĺ¶äş†ĺ¤§é‡Źçš„代ç ，那äąçŽ°ĺś¨ćŻć—¶ĺ€™ +问一下，事实上，将这些代ç ä¸çš„一些ćŹĺŹ–ĺ°ĺŤ•ç‹¬çš„ĺş“ä¸ďĽŚć–者在更é«çš„层次上实现 +这些功č˝ćŻĺ¦ćś‰ć„Źäą‰ă€‚ĺś¨ć•´ä¸Şĺ†…ć ¸ä¸ĺ¤Ťĺ¶ç›¸ĺŚçš„代ç 没有价值。 + +#ifdef ĺ’Śé˘„ĺ¤„ç† +*************** + +C预处ç†ĺ™¨äĽĽäąŽç»™ä¸€äş›C程序ĺ‘带来了强大的诱ć‘，他们认为ĺ®ćŻä¸€ç§Ťćś‰ć•ĺś°ĺ°†ĺ¤§é‡Źçµ +活性编ç ĺ°ćşć–‡ä»¶ä¸çš„方法。但ćŻé˘„处ç†ĺ™¨ä¸ŤćŻC，大量使用ĺ®äĽšĺŻĽč‡´ä»Łç 对其他人来 +说更难读取，对编译器来说更难检查ćŁçˇ®ć€§ă€‚大量的预处ç†ĺ™¨ĺ‡ 乎总ćŻä»Łç 需č¦ä¸€äş› +清ç†ĺ·Ąä˝śçš„ć ‡ĺż—ă€‚ + +使用ifdef的条件编译实际上ćŻä¸€ä¸ŞĺĽşĺ¤§çš„功č˝ďĽŚĺ®ĺś¨ĺ†…ć ¸ä¸ä˝żç”¨ă€‚但ćŻĺľĺ°‘有人希望 +çś‹ĺ°ä»Łç 被大量地撒上ifdef块。作为一č¬č§„ĺ™ďĽŚifdef的使用应尽可č˝é™ĺ¶ĺś¨ĺ¤´ć–‡ä»¶ +ä¸ă€‚有条件编译的代ç 可以é™ĺ¶ĺ‡˝ć•°ďĽŚĺ¦‚果代ç 不ĺ在，这些函数就会ĺŹćç©şçš„ă€‚ç„¶ĺŽ +编译器将悄悄地äĽĺŚ–对空函数的č°ç”¨ă€‚结果ćŻä»Łç ć›´ĺŠ ć¸…ć™°ďĽŚć›´ĺ®ąć“ç†č§Łă€‚ + +C预处ç†ĺ™¨ĺ®Źĺ在许多危险，包括可č˝ĺŻąĺ…·ćś‰ĺ‰Żä˝śç”¨ä¸”没有类型安全性的表达式进行多 +重评估。如果您试图定义宏，请č€č™‘ĺ›ĺ»şä¸€ä¸Şĺ†…č”函数。结果相ĺŚçš„代ç ，但ćŻĺ†…č” +函数更容ć“读取，不会多次计算其参数，并且ĺ…许编译器对参数和返回值执行类型检查。 + +内č”函数 +******** + +不过，内č”函数本身也ĺ在风险。程序ĺ‘可以倾ĺżäşŽéżĺ…Ťĺ‡˝ć•°č°ç”¨ĺ’Śç”¨ĺ†…č”ĺ‡˝ć•°ĺˇ«ĺ……ćş +文件所固有的ć•çŽ‡ă€‚然而，这些功č˝ĺ®žé™…上会降低性č˝ă€‚ĺ› ä¸şĺ®ä»¬çš„代ç 在每个č°ç”¨ç«™ +ç‚ąé˝č˘«ĺ¤Ťĺ¶ďĽŚć‰€ä»Ąĺ®ä»¬ćś€ç»äĽšĺ˘žĺŠ çĽ–čŻ‘ĺ†…ć ¸çš„ĺ¤§ĺ°Źă€‚ĺŹŤčż‡ćťĄďĽŚčż™äĽšĺŻąĺ¤„ç†ĺ™¨çš„内ĺ缓ĺ +é€ ć压力，从而大大降低执行速度。通常，内č”函数应该非常小，而且相对čľĺ°‘。毕竟， +函数č°ç”¨çš„ć本并不é«ďĽ›ĺ¤§é‡Źĺ†…č”函数的ĺ›ĺ»şćŻčż‡ć—©äĽĺŚ–的典型例ĺ。 + +一č¬ćťĄčŻ´ďĽŚĺ†…ć ¸ç¨‹ĺşŹĺ‘会忽略缓ĺć•ćžśďĽŚčż™äĽšĺ¸¦ćťĄĺŤ±é™©ă€‚在开始的数据结构课程ä¸ďĽŚç»Ź +典的时间/ç©şé—´ćťčˇˇé€šĺ¸¸ä¸Ťé€‚用于当代硬件。空间就ćŻć—¶é—´ďĽŚĺ› 为一个大的程序比一个 +更紧凑的程序čżčˇŚĺľ—慢。 + +最近的编译器在决定一个给定函数ćŻĺ¦ĺş”该被内č”方面扮演着越来越积ćžçš„角色。 +ĺ› ć¤ďĽŚâ€śinline”关键ĺ—的自由放置可č˝ä¸Ťä»…ä»…ćŻčż‡ĺş¦çš„，ĺ®äąźĺŹŻč˝ćŻć— 关的。 + +é” +** + +2006ĺą´5ćśďĽŚâ€śdeviceescapeâ€ťç˝‘ç»śĺ †ć 在GPL下发ĺ¸ďĽŚĺą¶č˘«çşłĺ…Ąä¸»çşżĺ†…ć ¸ă€‚čż™ćŻä¸€ä¸ŞĺŹ— +欢迎的ć¶ćŻďĽ›ĺŻąLinuxä¸ć— 线网络的支ćŚĺ……其量被认为ćŻä¸Ťĺć Ľçš„ďĽŚč€Śdeviceescape +ĺ †ć ćŹäľ›äş†äż®ĺ¤Ťčż™ç§Ťć…况的承诺。然而，直ĺ°2007ĺą´6ćśďĽ2.6.22），这段代ç 才真 +ćŁčż›ĺ…Ąä¸»çşżă€‚发生了什äąďĽź + +这段代ç ćľç¤şäş†č®¸ĺ¤šé—é—¨é€ č˝¦çš„čżąč±ˇă€‚ä˝†ä¸€ä¸Şç‰ąĺ«ĺ¤§çš„é—®é˘ćŻďĽŚĺ®ĺą¶ä¸ŤćŻč®ľč®ˇç”¨äşŽĺ¤š +处ç†ĺ™¨çł»ç»źă€‚在ĺĺą¶čż™ä¸Şç˝‘ç»śĺ †ć ďĽçŽ°ĺś¨ç§°ä¸şmac80211）之前，需č¦ĺŻąĺ…¶čż›čˇŚä¸€ä¸Şé” +ć–ąćˇçš„ć”ąé€ ă€‚ + +曾经，Linuxĺ†…ć ¸ä»Łç 可以在不č€č™‘多处ç†ĺ™¨çł»ç»źć‰€ĺ¸¦ćťĄçš„并发性问é˘çš„ć…况下进行 +开发。然而，现在，这个文件ćŻĺ†™ĺś¨ĺŹŚć ¸ç¬”记本电脑上的。即使在单处ç†ĺ™¨çł»ç»źä¸ŠďĽŚ +为ćŹé«ĺ“Ťĺş”č˝ĺŠ›ć‰€ĺšçš„工作也会ćŹé«ĺ†…ć ¸ĺ†…çš„ĺą¶ĺŹ‘ć€§ć°´ĺąłă€‚çĽ–ĺ†™ĺ†…ć ¸ä»Łç 而不č€č™‘é” +çš„ć—Ąĺ已经过去ĺľé•żäş†ă€‚ + +可以由多个线程并发访问的任何资ćşďĽć•°ćŤ®ç»“ćž„ă€çˇ¬ä»¶ĺŻ„ĺ器ç‰ďĽ‰ĺż…须由é”保护。新 +的代ç 应该记住这一č¦ć±‚；事ĺŽć”ąčŁ…é”ćŻä¸€éˇąç›¸ĺ˝“ĺ›°éšľçš„ä»»ĺŠˇă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘应该花 +时间充ĺ†äş†č§ŁĺŹŻç”¨çš„é”原čŻďĽŚä»Ąäľżä¸şä˝śä¸šé€‰ć‹©ćŁçˇ®çš„工具。ćľç¤şĺŻąĺą¶ĺŹ‘性缺乏关注的 +代ç 进入主线将ĺľĺ›°éšľă€‚ + +回归 +**** + +最ĺŽä¸€ä¸Şĺ€Ľĺľ—一ćŹçš„危险ćŻďĽšĺ®ĺŹŻč˝äĽšĺĽ•čµ·ć”ąĺŹďĽčż™ĺŹŻč˝äĽšĺ¸¦ćťĄĺľĺ¤§çš„改进），从而 +导致现有用ć·çš„ćźäş›ä¸śčĄżä¸ć–。这种ĺŹĺŚ–被称为“回归”，回归已经ćä¸şä¸»çşżĺ†…ć ¸ćś€ä¸Ť +受欢迎的。除少数例外ć…况外，如果回归不č˝ĺŹŠć—¶äż®ćŁďĽŚäĽšĺŻĽč‡´ĺ›žĺ˝’çš„ĺŹĺŚ–将被取ć¶ă€‚ +最好首ĺ…éżĺ…Ťĺ›žĺ˝’。 + +人们常常争论，如果回归让更多人可以工作，远超过产生问é˘ďĽŚé‚Łäąĺ›žĺ˝’ćŻĺç†çš„。 +如果ĺ®ç ´ĺťŹçš„一个系统却为ĺŤä¸Şçł»ç»źĺ¸¦ćťĄć–°çš„功č˝ďĽŚä¸şä»€äąä¸Ťčż›čˇŚć›´ć”ąĺ‘˘ďĽź2007ĺą´7ćśďĽŚ +Linus对这个问é˘ç»™ĺ‡şäş†ćś€ä˝łç”ćˇ: + +:: + 所以ć‘们不会通过引入新问é˘ćťĄäż®ĺ¤Ťé”™čŻŻă€‚é‚Łć ·çš„č°Žč¨€ĺľç–Żç‹‚ďĽŚć˛ˇćś‰äşşçźĄé“ + ä˝ ćŻĺ¦çśźçš„有进展。ćŻĺ‰Ťčż›ä¸¤ćĄďĽŚĺŽé€€ä¸€ćĄďĽŚčżćŻĺ‘前一ćĄďĽŚĺ‘ĺŽä¸¤ćĄďĽź + +ďĽhttp://lwn.net/articles/243460/） + +一种特ĺ«ä¸ŤĺŹ—欢迎的回归类型ćŻç”¨ć·ç©şé—´ABI的任何ĺŹĺŚ–。一旦接口被导出ĺ°ç”¨ć·ç©şé—´ďĽŚ +ĺ°±ĺż…éˇ»ć— é™ćśźĺś°ć”ŻćŚĺ®ă€‚这一事实使得用ć·ç©şé—´ćŽĄĺŹŁçš„ĺ›ĺ»şç‰ąĺ«ĺ…·ćś‰ćŚ‘ćć€§ďĽšĺ› ä¸şĺ®ä»¬ +不č˝ä»Ąä¸Ťĺ…Ľĺ®ąçš„方式进行更改，所以必须第一次ćŁçˇ®ĺś°čż›čˇŚć›´ć”ąă€‚ĺ› ć¤ďĽŚç”¨ć·ç©şé—´ç•Śéť˘ +总ćŻéś€č¦ĺ¤§é‡Źçš„思č€ă€ć¸…晰的文档和广泛的审查。 + + +代ç 检查工具 +------------ + +č‡łĺ°‘ç›®ĺ‰ŤďĽŚçĽ–ĺ†™ć— é”™čŻŻä»Łç 仍然ćŻć‘们ä¸ĺľĺ°‘äşşč˝čľľĺ°çš„ç†ćłçŠ¶ć€ă€‚不过，ć‘ä»¬ĺ¸Śćś›ĺš +çš„ćŻďĽŚĺś¨ä»Łç čż›ĺ…Ąä¸»çşżĺ†…ć ¸äą‹ĺ‰ŤďĽŚĺ°˝ĺŹŻč˝ĺ¤šĺś°ćŤ•čŽ·ĺą¶äż®ĺ¤Ťčż™äş›é”™čŻŻă€‚为ć¤ďĽŚĺ†…ć ¸ĺĽ€ĺŹ‘äşş +ĺ‘已经组装了一系ĺ—令人印象深ĺ»çš„工具，可以自动捕获ĺ„种ĺ„ć ·çš„ć¨ˇçłŠé—®é˘ă€‚计算机 +发现的任何问é˘é˝ćŻä¸€ä¸Şä»ĄĺŽä¸ŤäĽšĺ›°ć‰°ç”¨ć·çš„é—®é˘ďĽŚĺ› ć¤ďĽŚĺŹŞč¦ćś‰ĺŹŻč˝ďĽŚĺ°±ĺş”该使用 +自动化工具。 + +第一ćĄĺŹŞćŻćł¨ć„ŹçĽ–译器产生的č¦ĺ‘Šă€‚当代ç‰ćś¬çš„GCC可以检测ďĽĺą¶č¦ĺ‘ŠďĽ‰ĺ¤§é‡Źć˝śĺś¨é”™čŻŻă€‚ +通常，这些č¦ĺ‘Šé˝ćŚ‡ĺ‘çśźćŁçš„é—®é˘ă€‚ćŹäş¤ä»Ąäľ›ĺ®ˇé…的代ç 通常不会产生任何编译器č¦ĺ‘Šă€‚ +在ć¶é™¤č¦ĺ‘Šć—¶ďĽŚćł¨ć„Źäş†č§ŁçśźćŁçš„ĺŽźĺ› ďĽŚĺą¶ĺ°˝é‡Źéżĺ…Ťâ€śäż®ĺ¤Ťâ€ťďĽŚä˝żč¦ĺ‘Šć¶ĺ¤±č€Śä¸Ťč§Łĺ†łĺ…¶ĺŽźĺ› 。 + +请注意，并非所有编译器č¦ĺ‘Šé˝é»č®¤ĺŻç”¨ă€‚使用“make EXTRA_CFLAGS=-Wâ€ťćž„ĺ»şĺ†…ć ¸ä»Ą +获得完整集ĺ。 + +ĺ†…ć ¸ćŹäľ›äş†ĺ‡ 个配置选项，可以打开č°čŻ•ĺŠźč˝ďĽ›ĺ¤§ĺ¤šć•°é…Ťç˝®é€‰éˇąä˝ŤäşŽâ€śkernel hacking” +ĺ菜单ä¸ă€‚对于任何用于开发ć–ćµ‹čŻ•ç›®çš„çš„ĺ†…ć ¸ďĽŚé˝ĺş”该ĺŻç”¨ĺ…¶ä¸ĺ‡ 个选项。特ĺ«ćŻďĽŚ +您应该打开： + + - ĺŻç”¨ ENABLE_MUST_CHECK and FRAME_WARN 以获得一组额外的č¦ĺ‘ŠďĽŚä»Ąč§Łĺ†łä˝żç”¨ä¸Ť + 推čŤä˝żç”¨çš„接口ć–忽略函数的重č¦čż”回值ç‰é—®é˘ă€‚这些č¦ĺ‘Šç”źć的输出可č˝ćŻĺ†—é•ż + 的，但您不必担ĺżćťĄč‡Şĺ†…ć ¸ĺ…¶ä»–é¨ĺ†çš„č¦ĺ‘Šă€‚ + + - DEBUG_OBJECTS ĺ°†ć·»ĺŠ ä»Łç ďĽŚä»Ąč·źč¸Şĺ†…ć ¸ĺ›ĺ»şçš„ĺ„种对象的生ĺ期，并在出现问é˘ć—¶ + 发出č¦ĺ‘Šă€‚如果č¦ć·»ĺŠ ĺ›ĺ»şďĽĺ’ŚĺŻĽĺ‡şďĽ‰č‡Şĺ·±çš„复杂对象的ĺ系统，请č€č™‘ć·»ĺŠ ĺŻąĺŻąč±ˇ + č°čŻ•ĺźşçˇ€ç»“构的支ćŚă€‚ + + - DEBUG_SLAB 可以发现ĺ„种内ĺĺ†é…Ťĺ’Śä˝żç”¨é”™čŻŻďĽ›ĺ®ĺş”čŻĄç”¨äşŽĺ¤§ĺ¤šć•°ĺĽ€ĺŹ‘ĺ†…ć ¸ă€‚ + + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP and DEBUG_MUTEXES 会发现许多常č§çš„ + é”定错误. + +čżćś‰ĺľĺ¤šĺ…¶ä»–č°čŻ•é€‰éˇąďĽŚĺ…¶ä¸ä¸€äş›ĺ°†ĺś¨ä¸‹éť˘č®¨č®şă€‚ĺ…¶ä¸ä¸€äş›ĺ…·ćś‰ćľč‘—的性č˝ĺ˝±ĺ“ŤďĽŚä¸Ťĺş” +一直使用。但ćŻďĽŚĺś¨ĺ¦äą 可用选项上花费的一些时间可č˝äĽšĺś¨çźćśźĺ†…ĺľ—ĺ°ĺ¤šć¬ˇĺ›žćŠĄă€‚ + +ĺ…¶ä¸ä¸€ä¸Şčľé‡Ťçš„č°čŻ•ĺ·Ąĺ…·ćŻé”定检查器ć–“lockdep”。该工具将跟踪系统ä¸ćŻŹä¸Şé” +ďĽspinlockć–mutex）的获取和释放ă€čŽ·ĺŹ–é”的相对顺序ă€ĺ˝“前ä¸ć–环ĺ˘ç‰ç‰ă€‚然ĺŽďĽŚ +ĺ®ĺŹŻä»Ąçˇ®äżťć€»ćŻä»Ąç›¸ĺŚçš„顺序获取é”，相ĺŚçš„ä¸ć–ĺ‡č®ľé€‚用于所有ć…况，ç‰ç‰ă€‚换句话 +说，lockdep可以找ĺ°č®¸ĺ¤šĺśşć™ŻďĽŚĺś¨čż™äş›ĺśşć™Żä¸ďĽŚçł»ç»źĺľĺ°‘会ć»é”。在é¨ç˝˛çš„系统ä¸ďĽŚ +这种问é˘ĺŹŻč˝äĽšĺľç—›č‹¦ďĽĺŻąäşŽĺĽ€ĺŹ‘äşşĺ‘和用ć·č€Śč¨€ďĽ‰ďĽ›LockDepĺ…许ćŹĺ‰Ťä»Ąč‡ŞĺŠ¨ć–ąĺĽŹ +发现问é˘ă€‚具有任何类型的非普通é”定的代ç 在ćŹäş¤ĺŚ…ĺ«ĺ‰Ťĺş”在ĺŻç”¨lockdepçš„ć…况 +下čżčˇŚă€‚ + +ä˝śä¸şä¸€ä¸Şĺ‹¤ĺĄ‹çš„ĺ†…ć ¸ç¨‹ĺşŹĺ‘ďĽŚćŻ«ć— ç–‘é—®ďĽŚć‚¨ĺ°†ćŁ€ćźĄä»»ä˝•ĺŹŻč˝ĺ¤±č´Ąçš„操作ďĽĺ¦‚内ĺĺ†é…ŤďĽ‰ +的返回状ć€ă€‚然而，事实上，最ç»çš„ć•…éšść˘ĺ¤Ťč·Żĺľ„可č˝ĺ®Śĺ…¨ć˛ˇćś‰ç»Źčż‡ćµ‹čŻ•ă€‚未测试的 +代ç ĺľ€ĺľ€äĽšč˘«ç ´ĺťŹďĽ›ĺ¦‚ćžść‰€ćś‰čż™äş›é”™čŻŻĺ¤„ç†č·Żĺľ„é˝č˘«ć‰§čˇŚäş†ĺ‡ 次，那äąć‚¨ĺŹŻč˝ĺŻąä»Łç +更有信ĺżă€‚ + +ĺ†…ć ¸ćŹäľ›äş†ä¸€ä¸ŞĺŹŻä»Ąĺšĺ°čż™ä¸€ç‚ąçš„错误注入框架，特ĺ«ćŻĺś¨ć¶‰ĺŹŠĺ†…ĺĺ†é…Ťçš„ć…况下。 +ĺŻç”¨ć•…障注入ĺŽďĽŚĺ†…ĺĺ†é…Ťçš„可配置百ĺ†ćŻ”将失败；这些失败可以é™ĺ¶ĺś¨ç‰ąĺ®šçš„代ç +čŚĺ›´ĺ†…。在ĺŻç”¨äş†ć•…障注入的ć…况下čżčˇŚďĽŚç¨‹ĺşŹĺ‘可以看ĺ°ĺ˝“ć…况ć¶ĺŚ–时代ç 如何响 +应。有关如何使用ć¤ĺ·Ąĺ…·çš„详细信ćŻďĽŚčŻ·ĺŹ‚é… +Documentation/fault-injection/fault-injection.txt。 + +使用“sparse”静ć€ĺ†ćžĺ·Ąĺ…·ĺŹŻä»ĄĺŹ‘现其他类型的错误。对于sparse，可以č¦ĺ‘Šç¨‹ĺşŹĺ‘ +用ć·ç©şé—´ĺ’Śĺ†…ć ¸ç©şé—´ĺś°ĺť€äą‹é—´çš„ć··ć·†ă€big endianĺ’Śsmall endian数量的混ĺă€ĺś¨éś€ +č¦ä¸€ç»„ä˝Ťć ‡ĺż—çš„ĺś°ć–ąäĽ é€’ć•´ć•°ĺ€Ľç‰ç‰ă€‚sparse必须单独安装(如果您的ĺ†ĺŹ‘服务器没 +有将其打包，可以在 https://sparse.wiki.kernel.org/index.php/Main_page)找ĺ°, +然ĺŽĺŹŻä»Ąé€ščż‡ĺś¨make命令ä¸ć·»ĺŠ “C=1”在代ç 上čżčˇŚĺ®ă€‚ + +“Coccinelle”工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` +č˝ĺ¤źĺŹ‘现ĺ„种潜在的编ç é—®é˘ďĽ›ĺ®čżĺŹŻä»Ąä¸şčż™äş›é—®é˘ćŹĺ‡şäż®ĺ¤Ťć–ąćˇă€‚在 +scripts/coccinelleç›®ĺ˝•ä¸‹ĺ·˛ç»Źć‰“ĺŚ…äş†ç›¸ĺ˝“ĺ¤šçš„ĺ†…ć ¸â€śčŻäą‰čˇĄä¸â€ťďĽ›čżčˇŚ +“make coccicheck”将čżčˇŚčż™äş›čŻäą‰čˇĄä¸ĺą¶ćŠĄĺ‘ŠĺŹ‘现的任何问é˘ă€‚有关详细信ćŻďĽŚčŻ·ĺŹ‚é… +:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>` + + +其他类型的可移植性错误最好通过为其他体系结构编译代ç 来发现。如果没有S/390系统 +ć–Blackfin开发板，您仍然可以执行编译ćĄéŞ¤ă€‚ĺŹŻä»Ąĺś¨ä»Ąä¸‹ä˝Ťç˝®ć‰ľĺ°ä¸€ç»„用于x86系统的 +大型交叉编译器： + + http://www.kernel.org/pub/tools/crosstool/ + +花一些时间安装和使用这些编译器将有助于éżĺ…Ťä»ĄĺŽçš„尴尬。 + +文档 +---- + +ć–‡ćˇŁé€šĺ¸¸ćŻ”ĺ†…ć ¸ĺĽ€ĺŹ‘č§„ĺ™ć›´ä¸şäľ‹ĺ¤–。即便如ć¤ďĽŚč¶łĺ¤źçš„文档将有助于简化将新代ç ĺ并 +ĺ°ĺ†…ć ¸ä¸çš„过程，使其他开发人ĺ‘的生活更轻松，并对您的用ć·ćś‰ć‰€ĺ¸®ĺŠ©ă€‚在许多ć…况 +ä¸‹ďĽŚć–‡ä»¶çš„ć·»ĺŠ ĺ·˛ĺźşćś¬ä¸Šć为强ĺ¶ć€§çš„。 + +任何补ä¸çš„第一个文档ćŻĺ…¶ĺ…łč”çš„ĺŹć›´ć—Ąĺż—。日志条目应该描述ćŁĺś¨č§Łĺ†łçš„é—®é˘ă€č§Łĺ†ł +ć–ąćˇçš„形式ă€ĺ¤„ç†čˇĄä¸çš„äşşĺ‘ă€ĺŻąć€§č˝çš„任何相关影响，以及ç†č§ŁčˇĄä¸ĺŹŻč˝éś€č¦çš„任何 +其他内容。确保changelog说ćŽäş†ä¸şä»€äąčˇĄä¸ĺ€Ľĺľ—应用；大量开发人ĺ‘未č˝ćŹäľ›čż™äş›äżˇćŻă€‚ + +ä»»ä˝•ć·»ĺŠ ć–°ç”¨ć·ç©şé—´ç•Śéť˘çš„代ç ďĽĺŚ…括新的sysfsć–/proc文件）é˝ĺş”该包ĺ«čŻĄç•Śéť˘çš„ +文档，该文档使用ć·ç©şé—´ĺĽ€ĺŹ‘äşşĺ‘č˝ĺ¤źçźĄé“他们在使用什äąă€‚čŻ·ĺŹ‚é… +Documentation/abi/readmeďĽŚäş†č§Łĺ¦‚ä˝•ć ĽĺĽŹĺŚ–ć¤ć–‡ćˇŁä»ĄĺŹŠéś€č¦ćŹäľ›ĺ“Şäş›äżˇćŻă€‚ + +文件 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` +ćŹŹčż°äş†ĺ†…ć ¸çš„ć‰€ćś‰ĺĽ•ĺŻĽć—¶é—´ĺŹ‚ć•°ă€‚ä»»ä˝•ć·»ĺŠ ć–°ĺŹ‚ć•°çš„čˇĄä¸é˝ĺş”该ĺ‘čŻĄć–‡ä»¶ć·»ĺŠ é€‚ĺ˝“çš„ +条目。 + +任何新的配置选项é˝ĺż…须附有帮助文本，帮助文本清楚地解释了这些选项以及用ć·ĺŹŻč˝ +希望何时选择ĺ®ä»¬ă€‚ + +许多ĺ系统的内é¨API信ćŻé€ščż‡ä¸“é—¨ć ĽĺĽŹĺŚ–çš„ćł¨é‡Ščż›čˇŚč®°ĺ˝•ďĽ›čż™äş›ćł¨é‡ŠĺŹŻä»Ąé€ščż‡ +“kernel-doc”脚本以多种方式ćŹĺŹ–ĺ’Ść ĽĺĽŹĺŚ–ă€‚ĺ¦‚ćžść‚¨ĺś¨ĺ…·ćś‰kerneldoc注释的ĺçł»ç»źä¸ +工作，ĺ™ĺş”该维护ĺ®ä»¬ďĽŚĺą¶ć ąćŤ®éś€č¦ä¸şĺ¤–é¨ĺŹŻç”¨çš„功č˝ć·»ĺŠ ĺ®ä»¬ă€‚即使在没有如ć¤č®°ĺ˝• +的领域ä¸ďĽŚä¸şĺ°†ćťĄć·»ĺŠ kerneldoc注释也没有坏处；实际上，这对于ĺšĺĽ€ĺ§‹ĺĽ€ĺŹ‘ĺ†…ć ¸çš„äşş +来说ćŻä¸€ä¸Şćś‰ç”¨çš„ć´»ĺŠ¨ă€‚čż™äş›ćł¨é‡Šçš„ć ĽĺĽŹä»ĄĺŹŠĺ¦‚ä˝•ĺ›ĺ»şkerneldoc模板的一些信ćŻĺŹŻä»Ąĺś¨ +:ref:`Documentation/doc-guide/ <doc_guide>` 上找ĺ°ă€‚ + +任何é…čŻ»ĺ¤§é‡ŹçŽ°ćś‰ĺ†…ć ¸ä»Łç çš„äşşé˝äĽšćł¨ć„Źĺ°ďĽŚćł¨é‡Šçš„缺失往往ćŻćś€ĺ€Ľĺľ—注意的。再一次， +对新代ç 的期望比过去更é«ďĽ›ĺ并未注释的代ç ĺ°†ć›´ĺŠ ĺ›°éšľă€‚čż™ĺ°±ćŻčŻ´ďĽŚäşşä»¬ĺ‡ 乎不希望 +用čŻč¨€ćł¨é‡Šä»Łç 。代ç 本身应该ćŻĺŹŻčŻ»çš„，注释解释了更微妙的方面。 + +ćźäş›äş‹ć…应该总ćŻč˘«ćł¨é‡Šă€‚使用内ĺ屏障时，应附上一行文ĺ—，解释为什äąéś€č¦č®ľç˝®ĺ†…ĺ +屏障。数据结构的é”定规ĺ™é€šĺ¸¸éś€č¦ĺś¨ćźä¸Şĺś°ć–ąč§Łé‡Šă€‚一č¬ćťĄčŻ´ďĽŚä¸»č¦ć•°ćŤ®ç»“构需č¦ĺ…¨éť˘ +的文档。应该指出单独代ç 位之间不ćŽćľçš„依赖性。任何可č˝čŻ±ä˝żä»Łç 看门人进行错误的 +“清ç†â€ťçš„äş‹ć…é˝éś€č¦ä¸€ä¸Şćł¨é‡ŠćťĄčŻ´ćŽä¸şä»€äąč¦čż™ć ·ĺšă€‚ç‰ç‰ă€‚ + + +内é¨API更改 +----------- + +ĺ†…ć ¸ćŹäľ›ç»™ç”¨ć·ç©şé—´çš„二进ĺ¶ćŽĄĺŹŁä¸Ťč˝č˘«ç ´ĺťŹďĽŚé™¤éťžĺś¨ćś€ä¸Ąé‡Ťçš„ć…ĺ†µä¸‹ă€‚ç›¸ĺŹŤďĽŚĺ†…ć ¸çš„ +内é¨çĽ–程接口ćŻé«ĺş¦ćµĺŠ¨çš„，当需č¦ć—¶ĺŹŻä»Ąć›´ć”ąă€‚ĺ¦‚ćžśä˝ ĺŹ‘çŽ°č‡Şĺ·±ä¸Ťĺľ—ä¸Ťĺ¤„ç†ä¸€ä¸Şĺ†…ć ¸ +API，ć–č€…ä»…ä»…ĺ› ä¸şĺ®ä¸Ťć»ˇč¶łä˝ 的需求而不使用特定的功č˝ďĽŚčż™ĺŹŻč˝ćŻAPI需č¦ć”ąĺŹçš„一 +ä¸Şć ‡ĺż—ă€‚ä˝śä¸şĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘，您有ćťčż›čˇŚć¤ç±»ć›´ć”ąă€‚ + +当然, 可以进行API更改，但ĺ®ä»¬ĺż…须ćŻĺç†çš„ă€‚ĺ› ć¤ďĽŚä»»ä˝•čż›čˇŚĺ†…é¨API更改的补ä¸é˝ +应该附带一个关于更改内容和必č¦ĺŽźĺ› 的描述。这种ĺŹĺŚ–也应该ĺ†č§Łć一个单独的补ä¸ďĽŚ +而不ćŻĺź‹ĺś¨ä¸€ä¸Şć›´ĺ¤§çš„补ä¸ä¸ă€‚ + +另一个č¦ç‚ąćŻďĽŚć›´ć”ąĺ†…é¨API的开发人ĺ‘通常č¦č´źč´Łäż®ĺ¤Ťĺ†…ć ¸ć ‘ä¸č˘«ć›´ć”ąç ´ĺťŹçš„任何代ç 。 +对于一个广泛使用的函数，这个čŚč´ŁĺŹŻä»ĄĺŻĽč‡´ć百上ĺŤçš„ĺŹĺŚ–，其ä¸č®¸ĺ¤šĺŹĺŚ–可č˝ä¸Žĺ…¶ä»– +开发人ĺ‘ćŁĺś¨ĺšçš„工作相冲çŞă€‚不用说，这可č˝ćŻä¸€éˇąĺ¤§ĺ·Ąä˝śďĽŚć‰€ä»Ąćś€ĺĄ˝çˇ®äżťç†ç”±ćŻ +ĺŹŻéť çš„ă€‚čŻ·ćł¨ć„ŹďĽŚcoccinelle工具可以帮助进行广泛的API更改。 + +在进行不兼容的API更改时，应尽可č˝çˇ®äżťçĽ–译器捕获未更新的代ç 。这将帮助您确保找 +ĺ°čŻĄćŽĄĺŹŁçš„ć ‘ĺ†…ç”¨ĺ¤„ă€‚ĺ®čżĺ°†č¦ĺ‘ŠĺĽ€ĺŹ‘äşşĺ‘ć ‘ĺ¤–ä»Łç ĺ在他们需č¦ĺ“Ťĺş”的更改。支ćŚć ‘外 +代ç 不ćŻĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘需č¦ć‹…ĺżçš„äş‹ć…，但ćŻć‘ä»¬äąźä¸Ťĺż…ä˝żć ‘ĺ¤–ĺĽ€ĺŹ‘äşşĺ‘çš„ç”źć´»ćś‰ä¸Ťĺż…č¦ +的困难。 diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst new file mode 100644 index 000000000000..41aba21ff050 --- /dev/null +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -0,0 +1,240 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_posting: + +发é€čˇĄä¸ +======== + +迟早，当您的工作准备好ćŹäş¤ç»™ç¤ľĺŚşčż›čˇŚĺ®ˇćźĄďĽŚĺą¶ćś€ç»ĺŚ…ĺ«ĺ°ä¸»çşżĺ†…ć ¸ä¸ć—¶ă€‚不出所料， +ĺ†…ć ¸ĺĽ€ĺŹ‘ç¤ľĺŚşĺ·˛ç»ŹĺŹ‘ĺ±•ĺ‡şä¸€ĺĄ—ç”¨äşŽĺŹ‘ĺ¸čˇĄä¸çš„约定和过程；éµĺľŞčż™äş›çş¦ĺ®šĺ’Śčż‡ç¨‹ĺ°†ä˝ż +参与其ä¸çš„ćŻŹä¸Şäşşçš„ç”źć´»ć›´ĺŠ č˝»ćťľă€‚ćś¬ć–‡ä»¶ĺ°†čŻ•ĺ›ľĺç†čŻ¦ç»†ĺś°ć¶µç›–čż™äş›ćśźćś›ďĽ›ć›´ĺ¤šäżˇćŻ +也可在以下文件ä¸ć‰ľĺ° +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`, +:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +ĺ’Ś :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`. + +何时邮寄 +-------- + +在补ä¸ĺ®Śĺ…¨â€śĺ‡†ĺ¤‡ĺĄ˝â€ťäą‹ĺ‰ŤďĽŚćś‰ä¸€ä¸Şä¸Ťć–的诱ć‘来éżĺ…ŤĺŹ‘ĺ¸čˇĄä¸ă€‚对于简单的补ä¸ďĽŚ +这不ćŻé—®é˘ă€‚但ćŻďĽŚĺ¦‚ćžśćŁĺś¨ĺ®Ść的工作ĺľĺ¤Ťćť‚，那äąĺś¨ĺ·Ąä˝śĺ®Ść之前从社区获得 +反é¦ĺ°±ĺŹŻä»ĄčŽ·ĺľ—ĺľĺ¤šĺĄ˝ĺ¤„ă€‚ĺ› ć¤ďĽŚć‚¨ĺş”该č€č™‘发ĺ¸ćŁĺś¨čż›čˇŚçš„工作，甚至使Gitć ‘ +可用，以便感兴趣的开发人ĺ‘可以随时赶上您的工作。 + +当发ĺ¸čżć˛ˇćś‰ĺ‡†ĺ¤‡ĺĄ˝ĺŚ…ĺ«çš„代ç 时，最好在发ĺ¸ćś¬čş«ä¸čż™ć ·čŻ´ă€‚čżĺş”ćŹĺŹŠä»»ä˝•ćś‰ĺľ…完ć +的主č¦ĺ·Ąä˝śĺ’Śä»»ä˝•ĺ·˛çźĄé—®é˘ă€‚ĺľĺ°‘有人会看ĺ°é‚Łäş›č˘«č®¤ä¸şćŻĺŤŠç”źä¸Ťç†źçš„补ä¸ďĽŚä˝†ćŻé‚Łäş› +人会ćłĺ°ä»–ä»¬ĺŹŻä»Ąĺ¸®ĺŠ©ä˝ ćŠŠĺ·Ąä˝śćŽ¨ĺ‘ćŁçˇ®çš„ć–ąĺ‘。 + +ĺ›ĺ»şčˇĄä¸äą‹ĺ‰Ť +------------ + +在č€č™‘将补ä¸ĺŹ‘é€ĺ°ĺĽ€ĺŹ‘社区之前，有许多事ć…应该ĺšă€‚这些包括： + + - 尽可č˝ĺś°ćµ‹čŻ•ä»Łç 。ĺ©ç”¨ĺ†…ć ¸çš„č°čŻ•ĺ·Ąĺ…·ďĽŚçˇ®äżťĺ†…ć ¸ä˝żç”¨ć‰€ćś‰ĺç†çš„配置选项组ĺ + 进行构建，使用跨编译器为不ĺŚçš„体系结构进行构建ç‰ă€‚ + + - 确保您的代ç 符ĺĺ†…ć ¸çĽ–ç éŁŽć ĽćŚ‡ĺŤ—ă€‚ + + - 您的更改ćŻĺ¦ĺ…·ćś‰ć€§č˝ĺ˝±ĺ“ŤďĽźĺ¦‚ćžśćŻčż™ć ·ďĽŚć‚¨ĺş”该čżčˇŚĺźşĺ‡†ćµ‹čŻ•ćťĄćľç¤şć‚¨çš„ĺŹć›´çš„ + 影响ďĽć–好处）；结果的ć‘č¦ĺş”该包ĺ«ĺś¨čˇĄä¸ä¸ă€‚ + + - 确保您有ćťĺŹ‘ĺ¸ä»Łç 。如果这项工作ćŻä¸şé›‡ä¸»ĺ®Ść的，雇主对这项工作具有所有ćťďĽŚ + 并且必须ĺŚć„Źć ąćŤ®GPL对其进行放行。 + +一č¬ćťĄčŻ´ďĽŚĺś¨ĺŹ‘ĺ¸ä»Łç 之前进行一些额外的思č€ďĽŚĺ‡ 乎总ćŻč˝ĺś¨çźć—¶é—´ĺ†…ĺľ—ĺ°ĺ›žćŠĄă€‚ + +补ä¸ĺ‡†ĺ¤‡ +-------- + +准备发ĺ¸čˇĄä¸ĺŹŻč˝ćŻä¸€ä¸ŞćŠäşşçš„工作量，但再次尝试节çść—¶é—´ĺś¨čż™é‡Śé€šĺ¸¸ćŻä¸ŤćŽć™şçš„， +即使在çźćśźĺ†…。 + +必须é’ĺŻąĺ†…ć ¸çš„ç‰ąĺ®šç‰ćś¬ĺ‡†ĺ¤‡čˇĄä¸ă€‚作为一č¬č§„ĺ™ďĽŚčˇĄä¸ç¨‹ĺşŹĺş”该基于Linusçš„Gitć ‘ä¸ +的当前主线。当以主线为基础时，从一个众所周知的发ĺ¸ç‚ąĺĽ€ĺ§‹â€”—一个稳定的ć–RCçš„ +发ĺ¸â€”—而不ćŻĺś¨ä¸€ä¸Şä¸»çşżĺ†ć”Żä»»ć„Źç‚ąă€‚ + +但ćŻďĽŚĺŹŻč˝éś€č¦é’对-mmă€linux-nextć–ĺçł»ç»źć ‘ç”źćç‰ćś¬ďĽŚä»ĄäľżäşŽć›´ĺążćł›çš„测试和审查。 +ć ąćŤ®čˇĄä¸çš„区域以及其他地方的ć…况，é’ĺŻąčż™äş›ĺ…¶ä»–ć ‘ĺ»şç«‹čˇĄä¸ĺŹŻč˝éś€č¦ĺ¤§é‡Źçš„工作来 +解决冲çŞĺ’Śĺ¤„ç†API更改。 + +ĺŹŞćś‰ćś€ç®€ĺŤ•çš„ć›´ć”ąć‰Ťĺş”ć ĽĺĽŹĺŚ–ä¸şĺŤ•ä¸ŞčˇĄä¸ďĽ›ĺ…¶ä»–所有更改é˝ĺş”作为一系ĺ—逻辑更改进行。 +ĺ†ĺ‰˛čˇĄä¸ćŻä¸€é—¨č‰şćśŻďĽ›ä¸€äş›ĺĽ€ĺŹ‘äşşĺ‘花了ĺľé•żć—¶é—´ćťĄĺĽ„清楚如何按照社区期望的方式来 +ĺšă€‚然而，有一些经验法ĺ™ĺŹŻä»Ąĺ¤§ĺ¤§ĺ¸®ĺŠ©ďĽš + + - 您发ĺ¸çš„补ä¸ç¨‹ĺşŹçł»ĺ—ĺ‡ äąŽč‚Żĺ®šä¸ŤäĽšćŻĺ·Ąä˝śçł»ç»źä¸çš„一系ĺ—更改。相反，您所ĺšçš„ + 更改需č¦ĺś¨ćś€ç»ĺ˝˘ĺĽŹä¸ĺŠ 以č€č™‘，然ĺŽä»Ąćś‰ć„Źäą‰çš„方式进行拆ĺ†ă€‚开发人ĺ‘对离散的〠+ 自包ĺ«çš„更改感兴趣，而不ćŻć‚¨čŽ·ĺŹ–这些更改的路径。 + + - 每个逻辑上独立的ĺŹć›´é˝ĺş”čŻĄć ĽĺĽŹĺŚ–ä¸şĺŤ•ç‹¬çš„čˇĄä¸ă€‚这些更改可以ćŻĺ°Źçš„ďĽâ€śĺ‘ć¤ + ç»“ćž„ć·»ĺŠ ĺ—段”）ć–大的ďĽäľ‹ĺ¦‚ďĽŚć·»ĺŠ ä¸€ä¸Şé‡Ťč¦çš„新驱动程序），但ĺ®ä»¬ĺś¨ć¦‚念上 + 应该ćŻĺ°Źçš„，并且可以接受一行描述。每个补ä¸é˝ĺş”该ĺšä¸€ä¸Şç‰ąĺ®šçš„更改，可以单独 + 检查并验čŻĺ®ć‰€ĺšçš„äş‹ć…。 + + - 作为重申上述准ĺ™çš„一种方法：不č¦ĺś¨ĺŚä¸€čˇĄä¸ä¸ć··ĺ不ĺŚç±»ĺž‹çš„更改。如果一个 + 补ä¸äż®ĺ¤Ťäş†ä¸€ä¸Şĺ…łé”®çš„安全漏洞，重新排ĺ—äş†ä¸€äş›ç»“ćž„ďĽŚĺą¶é‡Ťć–°ć ĽĺĽŹĺŚ–äş†ä»Łç ďĽŚé‚Łäą + ĺľćś‰ĺŹŻč˝ĺ®äĽšč˘«ĺż˝ç•ĄďĽŚč€Śé‡Ťč¦çš„修复将丢失。 + + - 每个补ä¸é˝ĺş”čŻĄäş§ç”źä¸€ä¸Şĺ†…ć ¸ďĽŚĺ®ĺŹŻä»ĄćŁçˇ®ĺś°ćž„建和čżčˇŚďĽ›ĺ¦‚果补ä¸çł»ĺ—在ä¸é—´č˘« + ä¸ć–，那äąç»“果应该仍然ćŻä¸€ä¸Şĺ·Ąä˝śçš„ĺ†…ć ¸ă€‚čˇĄä¸çł»ĺ—çš„é¨ĺ†ĺş”用ćŻä˝żç”¨ + “git bisct”工具查找回归的一个常č§ĺśşć™ŻďĽ›ĺ¦‚果结果ćŻä¸€ä¸ŞćŤźĺťŹçš„ĺ†…ć ¸ďĽŚé‚ŁäąĺŻąäşŽ + 那些从事追踪问é˘çš„é«ĺ°šĺ·Ąä˝śçš„开发人ĺ‘和用ć·ćťĄčŻ´ďĽŚĺ°†ä˝żä»–ä»¬çš„ç”źć´»ć›´ĺŠ č‰°éšľă€‚ + + - 不过，不č¦čż‡ĺ†ă€‚一位开发人ĺ‘曾经将一组编辑内容作为500个单独的补ä¸ĺŹ‘ĺ¸ĺ°ä¸€ä¸Ş + 文件ä¸ďĽŚčż™ĺą¶ć˛ˇćś‰ä˝żä»–ćä¸şĺ†…ć ¸é‚®ä»¶ĺ—表ä¸ćś€ĺŹ—欢迎的人。一个补ä¸ĺŹŻä»Ąç›¸ĺ˝“大， + 只č¦ĺ®ä»Ťç„¶ĺŚ…ĺ«ä¸€ä¸ŞĺŤ•ä¸€çš„逻辑ĺŹć›´ă€‚ + + - 用一系ĺ—补ä¸ć·»ĺŠ 一个全新的基础设施ćŻĺľćś‰čŻ±ć‘力的，但ćŻĺś¨çł»ĺ—ä¸çš„最ĺŽä¸€ä¸Ş + 补ä¸ĺŻç”¨ć•´ä¸ŞčˇĄä¸äą‹ĺ‰ŤďĽŚčŻĄĺźşçˇ€č®ľć–˝ćŻä¸Ťä˝żç”¨çš„。如果可č˝çš„话，应该éżĺ…Ťčż™ç§Ť + 诱ć‘；如果这个系ĺ—ĺ˘žĺŠ äş†ĺ›žĺ˝’ďĽŚé‚ŁäąäşŚĺ†ćł•ĺ°†ćŚ‡ĺ‡şćś€ĺŽä¸€ä¸ŞčˇĄä¸ćŻĺŻĽč‡´é—®é˘çš„ + 补ä¸ďĽŚĺŤłä˝żçśźćŁçš„bug在其他地方。只č¦ćś‰ĺŹŻč˝ďĽŚć·»ĺŠ 新代ç 的补ä¸ç¨‹ĺşŹĺş”该立即 + 激活该代ç 。 + +ĺ›ĺ»şĺ®ŚçľŽčˇĄä¸çł»ĺ—的工作可č˝ćŻä¸€ä¸Şä»¤äşşć˛®ä¸§çš„过程，在完ć“真ćŁçš„工作”之ĺŽéś€č¦čŠ±č´ą +大量的时间和思č€ă€‚但ćŻďĽŚĺ¦‚ćžśĺšĺľ—好，这ćŻä¸€ć®µĺľĺĄ˝çš„时间。 + +补ä¸ć ĽĺĽŹĺ’Ść›´ć”ąć—Ąĺż— +------------------ + +ć‰€ä»ĄçŽ°ĺś¨ä˝ ćś‰äş†ä¸€çł»ĺ—完美的补ä¸ĺŹŻä»ĄĺŹ‘ĺ¸ďĽŚä˝†ćŻčż™éˇąĺ·Ąä˝śčżć˛ˇćś‰ĺ®Ść。每个补ä¸é˝ +需č¦č˘«ć ĽĺĽŹĺŚ–ć一条ć¶ćŻďĽŚĺ®ĺŹŻä»Ąĺż«é€źč€Ść¸…ć™°ĺś°ĺ°†ĺ…¶ç›®çš„äĽ čľľç»™ä¸–ç•Śĺ…¶ä»–ĺś°ć–ąă€‚ä¸şć¤ďĽŚ +每个补ä¸ĺ°†ç”±ä»Ąä¸‹é¨ĺ†ç»„ć： + + - ĺ‘˝ĺŤčˇĄä¸ä˝śč€…的可选“fromâ€ťčˇŚă€‚ĺŹŞćś‰ĺ˝“ä˝ é€ščż‡ç”µĺé‚®ä»¶äĽ é€’ĺ«äşşçš„补ä¸ć—¶ďĽŚčż™ä¸€čˇŚ + 才ćŻĺż…č¦çš„，但ćŻĺ¦‚ćžśćś‰ç–‘é—®ďĽŚć·»ĺŠ ĺ®ä¸ŤäĽšćś‰ä»»ä˝•äĽ¤ĺ®łă€‚ + + - 一行描述补ä¸çš„作用。对于没有其他上下文的读者来说，ć¤ć¶ćŻĺş”čŻĄč¶łĺ¤źäş†č§ŁčˇĄä¸ + çš„čŚĺ›´ďĽ›čż™ćŻĺ°†ĺś¨â€śçźć ĽĺĽŹâ€ťĺŹć›´ć—Ąĺż—ä¸ćľç¤şçš„行。ć¤ć¶ćŻé€šĺ¸¸é¦–ĺ…用相关的ĺ系统 + ĺŤç§°ć ĽĺĽŹĺŚ–，然ĺŽćŻčˇĄä¸çš„目的。例如： + + :: + + gpio: fix build on CONFIG_GPIO_SYSFS=n + + - 一个空白行，ĺŽéť˘ćŻčˇĄä¸ĺ†…容的详细描述。这个描述可以ćŻĺż…需的；ĺ®ĺş”该说ćŽčˇĄä¸ + 的作用以及为什äąĺ®ĺş”čŻĄĺş”ç”¨äşŽĺ†…ć ¸ă€‚ + + - 一个ć–ĺ¤šä¸Şć ‡č®°čˇŚďĽŚč‡łĺ°‘ćś‰ä¸€ä¸Şç”±čˇĄä¸ä˝śč€…的：signed-off-by çľĺŤă€‚çľĺŤĺ°†ĺś¨ä¸‹éť˘ + 更详细地描述。 + +上面的项目一起构ć补ä¸çš„ĺŹć›´ć—Ąĺż—。写一篇好的ĺŹć›´ć—Ąĺż—ćŻä¸€é—¨č‡łĺ…łé‡Ťč¦ä˝†ĺ¸¸ĺ¸¸č˘« +忽视的艺术；值得花一点时间来讨论这个问é˘ă€‚ĺ˝“ä˝ ĺ†™ä¸€ä¸ŞĺŹć›´ć—Ąĺż—ć—¶ďĽŚä˝ ĺş”čŻĄč®°ä˝Ź +有ĺľĺ¤šä¸ŤĺŚçš„äşşäĽščŻ»ä˝ çš„čŻťă€‚ĺ…¶ä¸ĺŚ…括ĺ系统维护人ĺ‘和审查人ĺ‘，他们需č¦ĺ†łĺ®šćŻĺ¦ +应该包括补ä¸ďĽŚĺ†é”€ĺ•†ĺ’Śĺ…¶ä»–维护人ĺ‘试图决定ćŻĺ¦ĺş”该将补ä¸ĺŹŤĺ‘移植ĺ°ĺ…¶ä»–ĺ†…ć ¸ďĽŚ +bugćśĺŻ»äşşĺ‘ćłçźĄé“补ä¸ćŻĺ¦č´źč´Łä»–们ćŁĺś¨čż˝ćźĄçš„é—®é˘ďĽŚćłçźĄé“ĺ†…ć ¸ĺ¦‚ä˝•ĺŹĺŚ–的用ć·ă€‚ +ç‰ç‰ă€‚一个好的ĺŹć›´ć—Ąĺż—以最直接和最简ć´çš„方式ĺ‘ć‰€ćś‰čż™äş›äşşäĽ čľľć‰€éś€çš„äżˇćŻă€‚ + +为ć¤ďĽŚć€»ç»“行应该描述ĺŹć›´çš„影响和动机，以及在一行约束条件下可č˝ĺŹ‘生的ĺŹĺŚ–。 +然ĺŽďĽŚčŻ¦ç»†çš„描述可以详述这些主é˘ďĽŚĺą¶ćŹäľ›ä»»ä˝•éś€č¦çš„é™„ĺŠ äżˇćŻă€‚如果补ä¸äż®ĺ¤Ťäş† +一个bug，请引用引入该bugçš„commitďĽĺ¦‚果可č˝ďĽŚčŻ·ĺś¨ĺĽ•ç”¨commitsć—¶ĺŚć—¶ćŹäľ›commit id +ĺ’Ść ‡é˘ďĽ‰ă€‚如果ćźä¸Şé—®é˘ä¸Žç‰ąĺ®šçš„ć—Ąĺż—ć–编译器输出相关č”，请包ĺ«čŻĄčľ“出以帮助其他 +äşşćśç´˘ĺŚä¸€é—®é˘çš„解决方ćˇă€‚如果更改ćŻä¸şäş†ć”ŻćŚä»ĄĺŽčˇĄä¸ä¸çš„其他更改，那äąĺ°±čż™äą +说。如果更改了内é¨API，请详细说ćŽčż™äş›ć›´ć”ąä»ĄĺŹŠĺ…¶ä»–开发人ĺ‘ĺş”čŻĄĺ¦‚ä˝•ĺ“Ťĺş”ă€‚ä¸€č¬ +ćťĄčŻ´ďĽŚä˝ č¶Šč˝ćŠŠč‡Şĺ·±ć”ľĺś¨ćŻŹä¸Şé…čŻ»ä˝ çš„changelog的人的位置上，changelogďĽĺ’Śĺ†…ć ¸ +作为一个整体）就越好。 + +不用说，ĺŹć›´ć—Ąĺż—应该ćŻĺ°†ĺŹć›´ćŹäş¤ĺ°äż®č®˘ćŽ§ĺ¶çł»ç»źć—¶ä˝żç”¨çš„文本。接下来ćŻďĽš + + - 补ä¸ćś¬čş«ďĽŚé‡‡ç”¨ç»źä¸€çš„ďĽâ€ś-u”）补ä¸ć ĽĺĽŹă€‚将“-p”选项用于diff将使函数ĺŤä¸Žć›´ć”ą + 相关č”，从而使结果补ä¸ć›´ĺ®ąć“被其他人读取。 + +您应该éżĺ…Ťĺś¨čˇĄä¸ä¸ĺŚ…括对不相关文件ďĽäľ‹ĺ¦‚，由构建过程生ć的文件ć–编辑器 +备份文件）的更改。文档目录ä¸çš„文件“dontdiff”在这方面有帮助；使用“-X”选项将 +ĺ…¶äĽ é€’ç»™diff。 + +上面ćŹĺ°çš„ć ‡çľç”¨äşŽćŹŹčż°ĺ„种开发人ĺ‘如何与这个补ä¸çš„开发相关č”。 +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` +文档ä¸ĺŻąĺ®ä»¬čż›čˇŚäş†čŻ¦ç»†ćŹŹčż°ďĽ›ä¸‹éť˘ćŻä¸€ä¸Şç®€çźçš„ć€»ç»“ă€‚ćŻŹä¸€čˇŚçš„ć ĽĺĽŹĺ¦‚ä¸‹ďĽš + +:: + + tag: Full Name <email address> optional-other-stuff + +ĺ¸¸ç”¨çš„ć ‡çľćś‰ďĽš + + - Signed-off-by: čż™ćŻä¸€ä¸ŞĺĽ€ĺŹ‘äşşĺ‘çš„čŻćŽďĽŚä»–ć–她有ćťćŹäş¤čˇĄä¸ä»ĄĺŚ…ĺ«ĺ°ĺ†…ć ¸ä¸ă€‚ + čż™ćŻĺĽ€ĺŹ‘来ćşč®¤čŻĺŤŹč®®ďĽŚĺ…¶ĺ…¨ć–‡ĺŹŻĺś¨ + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` + ä¸ć‰ľĺ°ďĽŚĺ¦‚果没有适当的çľĺ—，ĺ™ä¸Ťč˝ĺ并ĺ°ä¸»çşżä¸ă€‚ + + - Co-developed-by: 声ćŽčˇĄä¸ćŻç”±ĺ¤šä¸ŞĺĽ€ĺŹ‘äşşĺ‘ĺ…±ĺŚĺ›ĺ»şçš„ďĽ›ĺ˝“ĺ‡ ä¸Şäşşĺś¨ä¸€ä¸ŞčˇĄä¸ä¸Š + 工作时，ĺ®ç”¨äşŽĺ°†ĺ±žć€§čµ‹äşĺ…±ĺŚä˝śč€…ďĽé™¤äş† From: 所赋äşçš„ä˝śč€…äą‹ĺ¤–ďĽ‰ă€‚ĺ› ä¸ş + Co-developed-by: 表示作者身份，所以每个共ĺŚĺĽ€ĺŹ‘äşş, 必须紧跟在相关ĺ作作者 + çš„çľĺŤäą‹ĺŽă€‚具体内容和示例可以在以下文件ä¸ć‰ľĺ° + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` + + - Acked-by: 表示另一个开发人ĺ‘ďĽé€šĺ¸¸ćŻç›¸ĺ…łä»Łç 的维护人ĺ‘）ĺŚć„ŹčˇĄä¸é€‚ĺĺŚ…ĺ« + ĺś¨ĺ†…ć ¸ä¸ă€‚ + + - Tested-by: 声ćŽćŚ‡ĺ®šçš„人已经测试了补ä¸ĺą¶ĺŹ‘现ĺ®ĺŹŻä»Ąĺ·Ąä˝śă€‚ + + - Reviewed-by: 指定的开发人ĺ‘已经审查了补ä¸çš„ćŁçˇ®ć€§ďĽ›ćś‰ĺ…łčŻ¦ç»†äżˇćŻďĽŚčŻ·ĺŹ‚é… + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` + + - Reported-by: 指定报告ć¤čˇĄä¸äż®ĺ¤Ťçš„é—®é˘çš„用ć·ďĽ›ć¤ć ‡č®°ç”¨äşŽćŹäľ›ć„źč°˘ă€‚ + + - Cc：指定的人收ĺ°äş†čˇĄä¸çš„副本，并有机会对ć¤ĺŹ‘表评论。 + +在补ä¸ä¸ć·»ĺŠ ć ‡çľć—¶č¦ĺ°ŹĺżďĽšĺŹŞćś‰cc:才适ĺ在没有指定人ĺ‘ćŽçˇ®č®¸ĺŹŻçš„ć…ĺ†µä¸‹ć·»ĺŠ ă€‚ + +发é€čˇĄä¸ +-------- + +在邮寄补ä¸äą‹ĺ‰ŤďĽŚć‚¨čżéś€č¦ćł¨ć„Źä»Ąä¸‹ĺ‡ 点： + + - 您确定您的邮件发é€ç¨‹ĺşŹä¸ŤäĽšćŤźĺťŹčˇĄä¸ĺ—？有免费的空白更改ć–由邮件客ć·ç«Ż + 执行的行包装的补ä¸ä¸ŤäĽšĺś¨ĺŹ¦ä¸€ç«Żĺ¤ŤĺŽźďĽŚĺą¶ä¸”通常不会进行任何详细检查。如果有 + 任何疑问，把补ä¸ĺŻ„ç»™ä˝ č‡Şĺ·±ďĽŚč®©ä˝ č‡Şĺ·±ç›¸äżˇĺ®ćŻĺ®ŚĺĄ˝ć— 损的。 + + :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` + ćŹäľ›äş†ä¸€äş›ćś‰ç”¨çš„ćŹç¤şďĽŚĺŹŻä»Ąč®©ç‰ąĺ®šçš„邮件客ć·ćśşĺ·Ąä˝śä»ĄĺŹ‘é€čˇĄä¸ă€‚ + + - ä˝ çˇ®ĺ®šä˝ çš„čˇĄä¸ć˛ˇćś‰ć„šč ˘çš„错误ĺ—？您应该始ç»é€ščż‡scripts/checkpatch.plčżčˇŚ + 补ä¸ç¨‹ĺşŹďĽŚĺą¶č§Łĺ†łĺ®ćŹĺ‡şçš„投诉。请记住，checkpatch.pl虽然ćŻĺ¤§é‡Źć€ťč€ĺ†…ć ¸ + 补ä¸ĺş”该ćŻä»€äąć ·ĺ的体现，但ĺ®ĺą¶ä¸ŤćŻ”您čŞćŽă€‚如果修复checkpatch.pl投诉会 + 使代ç ĺŹĺľ—更糟，请不č¦čż™ć ·ĺšă€‚ + +补ä¸ĺş”始ç»ä»ĄçşŻć–‡ćś¬ĺ˝˘ĺĽŹĺŹ‘é€ă€‚请不č¦ĺ°†ĺ®ä»¬ä˝śä¸şé™„件发é€ďĽ›čż™ä˝żĺľ—审é…者在ç”复ä¸ć›´éšľ +引用补ä¸çš„é¨ĺ†ă€‚相反，只需将补ä¸ç›´ćŽĄć”ľĺ°ć‚¨çš„ć¶ćŻä¸ă€‚ + +邮寄补ä¸ć—¶ďĽŚé‡Ťč¦çš„ćŻĺ°†ĺ‰Żćś¬ĺŹ‘é€ç»™ä»»ä˝•ĺŹŻč˝ć„źĺ…´č¶Łçš„人。与其他一些项目不ĺŚďĽŚĺ†…ć ¸ +鼓励人们错误地发é€čż‡ĺ¤šçš„副本；不č¦ĺ‡ĺ®šç›¸ĺ…łäşşĺ‘会看ĺ°ć‚¨ĺś¨é‚®ä»¶ĺ—表ä¸çš„发ĺ¸ă€‚ +尤其ćŻďĽŚĺ‰Żćś¬ĺş”发é€č‡łďĽš + + - 受影响ĺ系统的维护人ĺ‘。如前所述，维护人ĺ‘文件ćŻćźĄć‰ľčż™äş›äşşĺ‘的第一个地方。 + + - 其他在ĺŚä¸€é˘†ĺźźĺ·Ąä˝śçš„开发人ĺ‘，尤其ćŻé‚Łäş›çŽ°ĺś¨ĺŹŻč˝ĺś¨é‚Łé‡Śĺ·Ąä˝śçš„开发人ĺ‘。使用 + git查看čżćś‰č°äż®ć”ąäş†ć‚¨ćŁĺś¨ĺ¤„ç†çš„文件，这ĺľćś‰ĺ¸®ĺŠ©ă€‚ + + - 如果您对错误报告ć–功č˝čŻ·ć±‚ĺšĺ‡şĺ“Ťĺş”，也可以抄é€ĺŽźĺ§‹ĺŹ‘é€äşşă€‚ + + - 将副本发é€ĺ°ç›¸ĺ…łé‚®ä»¶ĺ—表，ć–者，如果没有其他应用，ĺ™ĺŹ‘é€ĺ°Linuxĺ†…ć ¸ĺ—表。 + + - 如果您ćŁĺś¨äż®ĺ¤Ťä¸€ä¸Şbug，请č€č™‘该修复ćŻĺ¦ĺş”进入下一个稳定更新。如果ćŻčż™ć ·ďĽŚ + stable@vger.kernel.org 应该得ĺ°čˇĄä¸çš„副本。另外，在补ä¸ćś¬čş«çš„ć ‡çľä¸ć·»ĺŠ + 一个“cc:stable@vger.kernel.org”；这将使稳定团éźĺś¨äż®ĺ¤Ťčż›ĺ…Ąä¸»çşżć—¶ć”¶ĺ°é€šçźĄă€‚ + +当为一个补ä¸é€‰ć‹©ćŽĄć”¶č€…时，最好知é“ä˝ č®¤ä¸şč°ćś€ç»äĽšćŽĄĺŹ—这个补ä¸ĺą¶ĺ°†ĺ…¶ĺ并。虽然 +可以将补ä¸ç›´ćŽĄĺŹ‘é€ç»™LinusTorvalds并让他ĺ并，但通常ć…ĺ†µä¸‹ä¸ŤäĽščż™ć ·ĺšă€‚Linus +ĺľĺż™ďĽŚĺą¶ä¸”有ĺ系统维护人ĺ‘č´źč´Łç›‘č§†ĺ†…ć ¸çš„ç‰ąĺ®šé¨ĺ†ă€‚通常您会希望维护人ĺ‘ĺ并您 +的补ä¸ă€‚如果没有ćŽćľçš„维护人ĺ‘，Andrew Morton通常ćŻćś€ĺŽçš„补ä¸ç›®ć ‡ă€‚ + +补ä¸éś€č¦ĺĄ˝çš„主é˘čˇŚă€‚补ä¸ç¨‹ĺşŹčˇŚçš„规čŚć ĽĺĽŹĺ¦‚下： + +:: + + [PATCH nn/mm] subsys: one-line description of the patch + +ĺ…¶ä¸â€śnn”ćŻčˇĄä¸çš„序号，“mm”ćŻçł»ĺ—ä¸čˇĄä¸çš„总数，“subsys”ćŻĺŹ—影响ĺ系统的ĺŤç§°ă€‚ +ćľç„¶ďĽŚä¸€ä¸ŞĺŤ•ç‹¬çš„补ä¸ĺŹŻä»Ąçśç•Ąnn/mm。 + +如果您有一系ĺ—重č¦çš„补ä¸ďĽŚé‚Łäąé€šĺ¸¸ĺ°†ä»‹ç»Ťć€§ćŹŹčż°ä˝śä¸şé›¶é¨ĺ†ĺŹ‘é€ă€‚不过，这种约定 +并没有得ĺ°ć™®éŤéµĺľŞďĽ›ĺ¦‚果您使用ĺ®ďĽŚčŻ·č®°ä˝Źç®€ä»‹ä¸çš„信ćŻä¸ŤäĽšä˝żĺ®čż›ĺ…Ąĺ†…ć ¸ĺŹć›´ć—Ąĺż—。 +ĺ› ć¤ďĽŚčŻ·çˇ®äżťčˇĄä¸ćś¬čş«ĺ…·ćś‰ĺ®Ść•´çš„ĺŹć›´ć—Ąĺż—信ćŻă€‚ + +一č¬ćťĄčŻ´ďĽŚĺ¤šé¨ĺ†čˇĄä¸çš„第二é¨ĺ†ĺ’ŚĺŽç»é¨ĺ†ĺş”作为对第一é¨ĺ†çš„回复发é€ďĽŚä»Ąäľżĺ®ä»¬ +在接收端é˝čżžćŽĄĺś¨ä¸€čµ·ă€‚ĺŹgitĺ’Ścoiltčż™ć ·çš„ĺ·Ąĺ…·ćś‰ĺ‘˝ä»¤ďĽŚĺŹŻä»Ąé€ščż‡é€‚ĺ˝“çš„çşżç¨‹ĺŹ‘é€ +一组补ä¸ă€‚但ćŻďĽŚĺ¦‚果您有一个长系ĺ—，并且ćŁĺś¨ä˝żç”¨git，请远离–chain reply-to +选项，以éżĺ…Ťĺ›ĺ»şĺĽ‚常深的嵌套。 diff --git a/Documentation/translations/zh_CN/process/6.Followthrough.rst b/Documentation/translations/zh_CN/process/6.Followthrough.rst new file mode 100644 index 000000000000..f509e077e1cb --- /dev/null +++ b/Documentation/translations/zh_CN/process/6.Followthrough.rst @@ -0,0 +1,145 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/6.Followthrough.rst <development_followthrough>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_followthrough: + +č·źčż› +==== + +在这一点上，您已经éµĺľŞäş†ĺ°ç›®ĺ‰Ťä¸şć˘ç»™ĺ‡şçš„指导方é’ďĽŚĺą¶ä¸”ďĽŚéšŹçť€ć‚¨č‡Şĺ·±çš„ĺ·Ąç¨‹ćŠ€č˝ +çš„ĺ˘žĺŠ ďĽŚĺ·˛ç»ŹĺŹ‘ĺ¸äş†ä¸€çł»ĺ—完美的补ä¸ă€‚即使ćŻç»ŹéŞŚä¸°ĺŻŚçš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘äąźč˝çŠŻçš„最大 +错误之一ćŻďĽŚč®¤ä¸şä»–们的工作现在已经完ć了。事实上，发ĺ¸čˇĄä¸ć„Źĺ‘łçť€čż›ĺ…Ąćµç¨‹çš„下 +一个é¶ć®µďĽŚĺŹŻč˝čżéś€č¦ĺšĺľĺ¤šĺ·Ąä˝śă€‚ + +一个补ä¸ĺś¨ç¬¬ä¸€ć¬ˇĺŹ‘ĺ¸ć—¶ĺ°±éťžĺ¸¸ĺ‡şč‰˛ďĽŚć˛ˇćś‰ć”ąčż›çš„余地,čż™ćŻĺľç˝•č§çš„ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘ćµç¨‹ +认识ĺ°čż™ä¸€äş‹ĺ®žďĽŚĺ› ć¤ďĽŚĺ®éťžĺ¸¸ćł¨é‡ŤĺŻąĺ·˛ĺŹ‘ĺ¸ä»Łç 的改进。作为代ç 的作者，您应该与 +ĺ†…ć ¸ç¤ľĺŚşĺ作，以确保您的代ç 符ĺĺ†…ć ¸çš„č´¨é‡Źć ‡ĺ‡†ă€‚ĺ¦‚ćžśä¸ŤĺŹ‚ä¸Žčż™ä¸Şčż‡ç¨‹ďĽŚĺľĺŹŻč˝äĽš +é»ć˘ĺ°†čˇĄä¸ĺŚ…ĺ«ĺ°ä¸»çşżä¸ă€‚ + +与审é…者ĺ作 +------------ + +任何意义上的补ä¸é˝äĽšĺŻĽč‡´ĺ…¶ä»–开发人ĺ‘在审查代ç 时发表大量评论。对于许多开发 +äşşĺ‘来说，与审查人ĺ‘ĺ作可č˝ćŻĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹ä¸ćś€ä»¤äşşç”źç•Źçš„é¨ĺ†ă€‚但ćŻďĽŚĺ¦‚ćžśä˝ +记住一些事ć…，生活会ĺŹĺľ—容ć“得多： + + - ĺ¦‚ćžśä˝ ĺ·˛ç»ŹĺľĺĄ˝ĺś°č§Łé‡Šäş†ä˝ 的补ä¸ďĽŚčŻ„论人ĺ‘会ç†č§Łĺ®çš„价值，以及为什äąä˝ 会 + č´ąĺ°˝ĺżć€ťĺŽ»ĺ†™ĺ®ă€‚但ćŻčż™ä¸Şĺą¶ä¸Ťč˝é»ć˘ä»–们ćŹĺ‡şä¸€ä¸Şĺźşćś¬çš„é—®é˘ďĽšäş”ĺą´ć–ĺŤĺą´ĺŽ + 用这个代ç ç»´ćŠ¤ä¸€ä¸Şĺ†…ć ¸äĽšćŻä»€äąć„źč§‰ďĽźä˝ 可č˝č˘«č¦ć±‚ĺšĺ‡şçš„许多改ĺŹâ€”—从编ç éŁŽć Ľ + çš„č°ć•´ĺ°ĺ¤§é‡Źçš„重写——é˝ćťĄč‡ŞäşŽĺŻąLinuxçš„ç†č§ŁďĽŚĺŤłä»ŽçŽ°ĺś¨čµ·ĺŤĺą´ĺŽďĽŚLinux仍将在 + 开发ä¸ă€‚ + + - 代ç 审查ćŻä¸€éˇąč‰°č‹¦çš„工作，这ćŻä¸€éˇąç›¸ĺŻąĺ力不讨好的工作；人们记得č°çĽ–写了 + ĺ†…ć ¸ä»Łç ，但对于那些审查ĺ®çš„äşşćťĄčŻ´ďĽŚĺ‡ äąŽć˛ˇćś‰ä»€äąćŚäą…çš„ĺŤĺŁ°ă€‚ĺ› ć¤ďĽŚčŻ„论 + äşşĺ‘可č˝äĽšĺŹĺľ—ćš´čşďĽŚĺ°¤ĺ…¶ćŻĺ˝“他们看ĺ°ĺŚć ·çš„错误被一éŤĺŹä¸€éŤĺś°çŠŻä¸‹ć—¶ă€‚如果 + ä˝ ĺľ—ĺ°äş†ä¸€ä¸Şçś‹čµ·ćťĄć„¤ć€’ă€äľ®čľ±ć–ĺ®Śĺ…¨ĺ†’çŠŻä˝ çš„čŻ„č®şďĽŚćŠµĺ¶ä»ĄĺŚć ·ć–ąĺĽŹĺ›žĺş”的冲动。 + 代ç 审查ćŻĺ…łäşŽä»Łç 的，而不ćŻĺ…łäşŽäşşçš„，代ç 审查人ĺ‘不会亲自攻击您。 + + - ĺŚć ·ďĽŚä»Łç 审查人ĺ‘也不ćłä»Ąç‰şç‰˛ä˝ 雇主的ĺ©ç›Šä¸şä»Łä»·ćťĄĺ®ŁäĽ 他们雇主的议程。 + ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘通常希望今ĺŽĺ‡ ĺą´č˝ĺś¨ĺ†…ć ¸ä¸Šĺ·Ąä˝śďĽŚä˝†ä»–ä»¬ćŽç™˝ä»–们的雇主可č˝äĽšć”ą + ĺŹă€‚ä»–ä»¬çśźçš„ďĽŚĺ‡ äąŽćŻ«ć— äľ‹ĺ¤–ĺś°ďĽŚč‡´ĺŠ›äşŽĺ›é€ 他们所č˝ĺšĺ°çš„ćś€ĺĄ˝çš„ĺ†…ć ¸ďĽ›ä»–ä»¬ĺą¶ + ć˛ˇćś‰čŻ•ĺ›ľç»™é›‡ä¸»çš„ç«žäş‰ĺŻąć‰‹é€ ć不适。 + +ć‰€ćś‰čż™äş›ĺ˝’ć ąç»“ĺş•é˝ćŻďĽŚĺ˝“审é…者ĺ‘您发é€čŻ„论时，您需č¦ćł¨ć„Źä»–们ćŁĺś¨čż›čˇŚçš„技术 +观察。不č¦č®©ä»–们的表达方式ć–ä˝ č‡Şĺ·±çš„éŞ„ĺ‚˛é»ć˘čż™ç§Ťäş‹ć…çš„ĺŹ‘ç”źă€‚ĺ˝“ä˝ ĺś¨ä¸€ä¸ŞčˇĄä¸ +上得ĺ°čŻ„论时，花点时间去ç†č§ŁčŻ„论人ćłčŻ´ä»€äąă€‚如果可č˝çš„话，请修复审é…者č¦ć±‚ +您修复的内容。然ĺŽĺ›žĺ¤Ťĺ®ˇç¨żäşşďĽšč°˘č°˘ä»–ä»¬ďĽŚĺą¶ćŹŹčż°ä˝ ĺ°†ĺ¦‚ä˝•ĺ›žç”他们的问é˘ă€‚ + +请注意，您不必ĺŚć„Źĺ®ˇé…者建议的每个更改。如果您认为审é…者误解了您的代ç ，请 +解释ĺ°ĺş•ĺŹ‘生了什äąă€‚如果您对建议的更改有技术上的异议，请描述ĺ®ĺą¶čŻćŽć‚¨ĺŻąčŻĄ +é—®é˘çš„解决方ćˇćŻćŁçˇ®çš„ă€‚ĺ¦‚ćžśä˝ çš„č§Łé‡Šćś‰é“ç†ďĽŚĺ®ˇç¨żäşşäĽšćŽĄĺŹ—çš„ă€‚ä¸Ťčż‡ďĽŚĺ¦‚ćžśä˝ çš„ +解释不č˝čŻćŽćŻćś‰čŻ´ćśŤĺŠ›çš„，尤其ćŻĺ˝“其他人开始ĺŚć„Źĺ®ˇç¨żäşşçš„观点时，请花些时间 +重新č€č™‘ä¸€ä¸‹ă€‚ä˝ ĺľĺ®ąć“对自己解决问é˘çš„方法视而不č§ďĽŚä»Ąč‡łäşŽä˝ 没有意识ĺ°ćźä¸Ş +é—®é˘ć ąćś¬ćŻé”™čŻŻçš„，ć–č€…ä˝ ç”šč‡łć˛ˇćś‰č§Łĺ†łćŁçˇ®çš„é—®é˘ă€‚ + +Andrew Morton建议，每一条不会导致代ç 更改的评论é˝ĺş”该导致额外的代ç 注释； +这可以帮助未来的评论人ĺ‘éżĺ…Ťĺ‡şçŽ°ç¬¬ä¸€ć¬ˇĺ‡şçŽ°çš„é—®é˘ă€‚ + +一个致命的错误ćŻĺż˝č§†čŻ„论，希望ĺ®ä»¬äĽšć¶ĺ¤±ă€‚他们不会走的。如果您在没有对之前 +收ĺ°çš„注释ĺšĺ‡şĺ“Ťĺş”çš„ć…况下重新发ĺ¸ä»Łç ，那äąĺľĺŹŻč˝äĽšĺŹ‘现补ä¸ćŻ«ć— 用处。 + +说ĺ°é‡Ťć–°ĺŹ‘ĺ¸ä»Łç ：请记住，审é…者不会记住您上次发ĺ¸çš„代ç çš„ć‰€ćś‰ç»†čŠ‚ă€‚ĺ› ć¤ďĽŚ +ćŹé†’审查人ĺ‘以前ćŹĺ‡şçš„é—®é˘ä»ĄĺŹŠć‚¨ĺ¦‚何处ç†čż™äş›é—®é˘ć€»ćŻä¸€ä¸ŞĺĄ˝ä¸»ć„ŹďĽ›čˇĄä¸ĺŹć›´ +ć—Ąĺż—ćŻćŹäľ›ć¤ç±»äżˇćŻçš„好地方。审é…者不必ćśç´˘ĺ—表档ćˇćťĄç†źć‚‰ä¸Šć¬ˇć‰€čŻ´çš„内容； +如果您帮助他们开始čżčˇŚďĽŚĺ˝“他们重新访问您的代ç 时，他们的ĺżć…会更好。 + +ĺ¦‚ćžśä˝ ĺ·˛ç»ŹčŻ•çť€ĺšćŁçˇ®çš„äş‹ć…，但事ć…仍然没有进展呢？大多数技术上的ĺ†ć§é˝ĺŹŻä»Ą +通过讨论来解决，但有时人们只需č¦ĺšĺ‡şĺ†łĺ®šă€‚ĺ¦‚ćžśä˝ çśźçš„č®¤ä¸şčż™ä¸Şĺ†łĺ®šĺŻąä˝ ä¸Ťĺ©ďĽŚ +ä˝ ĺŹŻä»ĄčŻ•çť€ĺ‘ć›´é«çš„ćťĺŠ›ä¸ŠčŻ‰ă€‚ĺś¨čż™çŻ‡ć–‡ç« ä¸ďĽŚć›´é«çš„ćťĺŠ›ĺ€ľĺ‘于Andrew Morton。 +Andrewĺś¨ĺ†…ć ¸ĺĽ€ĺŹ‘ç¤ľĺŚşä¸ĺŹ—iĺľĺ¤§çš„尊重；他经常为似乎被绝望地é»ĺˇžäş‹ć…清障。 +尽管如ć¤ďĽŚĺŻąAndrewçš„ĺ‘Ľĺ不应轻而ć“举，也不应在所有其他替代方ćˇé˝č˘«ćŽ˘ç´˘äą‹ĺ‰Ť +使用。当然，记住，他也可č˝ä¸ŤĺŚć„Źä˝ çš„ć„Źč§ă€‚ + +ćŽĄä¸‹ćťĄäĽšĺŹ‘ç”źä»€äą +---------------- + +如果一个补ä¸č˘«č®¤ä¸şćŻć·»ĺŠ ĺ°ĺ†…ć ¸ä¸çš„一件好事，并且一旦大多数审查问é˘ĺľ—ĺ°č§Łĺ†łďĽŚ +下一ćĄé€šĺ¸¸ćŻčż›ĺ…Ąĺ系统维护人ĺ‘çš„ć ‘ä¸ă€‚ĺ·Ąä˝ść–ąĺĽŹĺ› ĺ系统而异；每个维护人ĺ‘é˝ +有自己的工作方式。特ĺ«ćŻďĽŚĺŹŻč˝ćś‰ä¸Ťć˘ä¸€ćŁµć ‘â€”â€”ä¸€ćŁµć ‘ďĽŚäąźč®¸ďĽŚä¸“é—¨ç”¨äşŽč®ˇĺ’下一 +个ĺ并窗口的补ä¸ďĽŚĺŹ¦ä¸€ćŁµć ‘用于长期工作。 + +对于应用于没有ćŽćľĺçł»ç»źć ‘ďĽäľ‹ĺ¦‚内ĺ管ç†äż®čˇĄç¨‹ĺşŹďĽ‰çš„区域的修补程序，é»č®¤ć ‘ +通常以-mm结尾。影响多个ĺ系统的补ä¸äąźĺŹŻä»Ąćś€ç»é€ščż‡-mmć ‘ă€‚ + +包ĺ«ĺś¨ĺçł»ç»źć ‘ä¸ĺŹŻä»ĄćŹé«čˇĄä¸çš„可č§ć€§ă€‚çŽ°ĺś¨ďĽŚä˝żç”¨čŻĄć ‘çš„ĺ…¶ä»–ĺĽ€ĺŹ‘äşşĺ‘ĺ°†é»č®¤čŽ· +得补ä¸ă€‚ĺçł»ç»źć ‘é€šĺ¸¸äąźä¸şLinuxćŹäľ›ć”ŻćŚďĽŚä˝żĺ…¶ĺ†…容对整个开发社区可č§ă€‚在这一点 +上，您ĺľĺŹŻč˝äĽšä»Žä¸€ç»„新的审é…者那里得ĺ°ć›´ĺ¤šçš„评论；这些评论需č¦ĺŹä¸Šä¸€č˝®é‚Łć · +ĺľ—ĺ°ĺ›žç”。 + +在这一点上也会发生什äąďĽŚčż™ĺŹ–ĺ†łäşŽä˝ çš„čˇĄä¸çš„性质，ćŻä¸Žĺ…¶ä»–äşşćŁĺś¨ĺšçš„工作发生 +冲çŞă€‚在最坏的ć…况下，严重的补ä¸ĺ†˛çŞĺŹŻč˝äĽšĺŻĽč‡´ä¸€äş›ĺ·Ąä˝śč˘«ćç˝®ďĽŚä»Ąäľżĺ‰©ä˝™çš„čˇĄä¸ +可以ć形并ĺ并。另一些时候，冲çŞč§Łĺ†łĺ°†ć¶‰ĺŹŠĺ°ä¸Žĺ…¶ä»–开发人ĺ‘ĺ作，可č˝čżäĽš +ĺś¨ć ‘äą‹é—´ç§»ĺŠ¨ä¸€äş›čˇĄä¸ďĽŚä»Ąçˇ®äżťć‰€ćś‰çš„应用é˝ćŻĺą˛ĺ‡€çš„。这项工作可č˝ćŻä¸€ä»¶ç—›č‹¦çš„ +äş‹ć…，但č¦č®ˇç®—您的福祉：在Linuxä¸‹ä¸€ćŁµć ‘ĺ‡şçŽ°äą‹ĺ‰ŤďĽŚčż™äş›ĺ†˛çŞé€šĺ¸¸ĺŹŞĺś¨ĺ并窗口 +ä¸ĺ‡şçŽ°ďĽŚĺż…须迅速解决。现在可以在ĺ并窗口打开之前，在空闲时解决这些问é˘ă€‚ + +有朝一日，如果一ĺ‡éˇşĺ©ďĽŚć‚¨ĺ°†ç™»ĺ˝•ĺą¶çś‹ĺ°ć‚¨çš„补ä¸ĺ·˛ç»Źĺ并ĺ°ä¸»çşżĺ†…ć ¸ä¸ă€‚çĄťč´şä˝ ďĽ +然而，一旦庆祝活动完ćďĽĺą¶ä¸”ć‚¨ĺ·˛ç»Źĺ°†č‡Şĺ·±ć·»ĺŠ ĺ°ç»´ćŠ¤äşşĺ‘文件ä¸ďĽ‰ďĽŚĺ°±ĺ€Ľĺľ—记住 +一个重č¦çš„小事实：工作仍然没有完ć。并入主线带来了自身的挑ć。 + +首ĺ…，补ä¸çš„可č§ć€§ĺ†Ťć¬ˇćŹé«ă€‚可č˝äĽšćś‰ć–°ä¸€č˝®çš„开发者评论，他们以前不知é“čż™ +个补ä¸ă€‚忽略ĺ®ä»¬ĺŹŻč˝ĺľćś‰čŻ±ć‘ĺŠ›ďĽŚĺ› ä¸şć‚¨çš„ä»Łç 不再ĺ在任何被ĺ并的问é˘ă€‚但ćŻďĽŚ +č¦ćŠµĺ¶čż™ç§ŤčŻ±ć‘，您仍然需č¦ĺŻąćś‰é—®é˘ć–建议的开发人ĺ‘作出响应。 + +不过，更重č¦çš„ćŻďĽšĺ°†ä»Łç 包ĺ«ĺś¨ä¸»çşżä¸äĽšĺ°†ä»Łç 交给更大的一组测试人ĺ‘。即使您 +为尚未ćŹäľ›çš„硬件ćŹäľ›äş†é©±ĺŠ¨ç¨‹ĺşŹďĽŚć‚¨äąźäĽšćŠč®¶äşŽćś‰ĺ¤šĺ°‘人会将您的代ç 构建ĺ°ĺ†…ć ¸ +ä¸ă€‚当然，如果有测试人ĺ‘，也会有错误报告。 + +最糟糕的错误报告ćŻĺ›žĺ˝’ă€‚ĺ¦‚ćžśä˝ çš„čˇĄä¸ĺŻĽč‡´ĺ›žĺ˝’ďĽŚä˝ äĽšĺŹ‘çŽ°ĺľĺ¤šä¸Ťč’服的眼睛盯着 +ä˝ ďĽ›ĺ›žĺ˝’éś€č¦ĺ°˝ĺż«äż®ĺ¤Ťă€‚如果您不愿意ć–ć— ćł•äż®ĺ¤Ťĺ›žĺ˝’ďĽĺ…¶ä»–äşşé˝ä¸ŤäĽšä¸şć‚¨äż®ĺ¤ŤďĽ‰ďĽŚ +é‚Łäąĺś¨ç¨łĺ®šćśźĺ†…，您的补ä¸ĺ‡ 乎肯定会被移除。除了ĺ¦ĺ®šć‚¨ä¸şä˝żčˇĄä¸čż›ĺ…Ąä¸»çşżć‰€ĺšçš„ +所有工作之外，如果由于未č˝äż®ĺ¤Ťĺ›žĺ˝’而取ć¶čˇĄä¸ďĽŚĺľĺŹŻč˝äĽšä˝żĺ°†ćťĄçš„工作更难ĺ并。 + +在处ç†ĺ®Śä»»ä˝•ĺ›žĺ˝’äą‹ĺŽďĽŚĺŹŻč˝čżćś‰ĺ…¶ä»–普通的bug需č¦ĺ¤„ç†ă€‚稳定期ćŻäż®ĺ¤Ťčż™äş›é”™čŻŻĺą¶ +确保代ç ĺś¨ä¸»çşżĺ†…ć ¸ç‰ćś¬ä¸çš„首次发ĺ¸ĺ°˝ĺŹŻč˝ĺŹŻéť 的最好机会。所以，请回ç”错误 +报告，并尽可č˝č§Łĺ†łé—®é˘ă€‚这就ćŻç¨łĺ®šćśźçš„目的；一旦解决了旧补ä¸çš„任何问é˘ďĽŚĺ°± +可以开始ĺ›ĺ»şé…·çš„新补ä¸ă€‚ + +ĺ«ĺżäş†ďĽŚčżćś‰ĺ…¶ä»–里程碑也可č˝äĽšĺ›ĺ»şbug报告：下一个主线稳定ç‰ćś¬ďĽŚĺ˝“č‘—ĺŤçš„发行 +商选择包ĺ«čˇĄä¸çš„ĺ†…ć ¸ç‰ćś¬ć—¶ďĽŚç‰ç‰ă€‚继ç»ĺ“Ťĺş”这些报告ćŻć‚¨ĺ·Ąä˝śçš„基本骄傲。但ćŻďĽŚ +如果这不ćŻč¶łĺ¤źçš„动机，那äąäąźĺ€Ľĺľ—č€č™‘çš„ćŻďĽŚĺĽ€ĺŹ‘社区会记住那些在ĺ并ĺŽĺŻąä»Łç +失去兴趣的开发人ĺ‘ă€‚ä¸‹ä¸€ć¬ˇä˝ ĺŹ‘ĺ¸čˇĄä¸ć—¶ďĽŚä»–ä»¬äĽšä»Ąä˝ ä»ĄĺŽä¸ŤäĽšĺś¨čş«čľąç»´ćŠ¤ĺ®ä¸şĺ‡ +设来评估ĺ®ă€‚ + +其他可č˝ĺŹ‘ç”źçš„äş‹ć… +------------------ + +ćś‰ä¸€ĺ¤©ďĽŚä˝ ĺŹŻä»Ąć‰“ĺĽ€ä˝ çš„é‚®ä»¶ĺ®˘ć·ç«ŻďĽŚçś‹ĺ°ćś‰äşşç»™ä˝ 寄了一个代ç 补ä¸ă€‚ćŻ•ç«źďĽŚčż™ćŻ +让您的代ç 公开ĺ在的好处之一。如果您ĺŚć„Źčż™ä¸ŞčˇĄä¸ďĽŚć‚¨ĺŹŻä»Ąĺ°†ĺ®č˝¬ĺŹ‘ç»™ĺ系统 +维护人ĺ‘ďĽçˇ®äżťĺŚ…ĺ«ä¸€ä¸ŞćŁçˇ®çš„From:čˇŚďĽŚčż™ć ·ĺ±žć€§ćŻćŁçˇ®çš„ďĽŚĺą¶ć·»ĺŠ ä¸€ä¸Şć‚¨č‡Şĺ·± +çš„çľĺ‡†ďĽ‰ďĽŚć–者回复一个Acked-by，让原始发é€č€…ĺ‘上发é€ĺ®ă€‚ + +如果您不ĺŚć„ŹčˇĄä¸ďĽŚčŻ·ĺŹ‘é€ä¸€ä¸Şç¤Ľč˛Śçš„ĺ›žĺ¤ŤďĽŚč§Łé‡ŠĺŽźĺ› ă€‚ĺ¦‚ćžśĺŹŻč˝çš„čŻťďĽŚĺ‘ŠčŻ‰ä˝śč€…éś€č¦ +ĺšĺ“Şäş›ć›´ć”ąć‰Ťč˝č®©ć‚¨ćŽĄĺŹ—补ä¸ă€‚对于代ç 的编写者和维护者所反对的ĺ并补ä¸ďĽŚĺ在着 +一定的é»ĺŠ›ďĽŚä˝†ä»…ć¤č€Śĺ·˛ă€‚ĺ¦‚ćžśä˝ č˘«č®¤ä¸şä¸Ťĺż…č¦çš„é»ç˘Ťäş†ĺĄ˝çš„工作，那äąčż™äş›čˇĄä¸ćś€ +ç»äĽšç»Źčż‡ä˝ 身边并进入主线。在Linuxĺ†…ć ¸ä¸ďĽŚć˛ˇćś‰äşşĺŻąä»»ä˝•ä»Łç 拥有绝对的ĺ¦ĺ†łćťă€‚ +除了Linus。 + +在非常罕č§çš„ć…况下，您可č˝äĽšçś‹ĺ°ĺ®Śĺ…¨ä¸ŤĺŚçš„东西：另一个开发人ĺ‘发ĺ¸äş†é’对您 +çš„é—®é˘çš„不ĺŚč§Łĺ†łć–ąćˇă€‚在这一点上，两个补ä¸ä¸çš„一个可č˝ä¸ŤäĽšĺ并，“ć‘的在这里 +ćŻç¬¬ä¸€ä¸Şâ€ťä¸Ťč˘«č®¤ä¸şćŻä¸€ä¸Şä»¤äşşäżˇćśŤçš„技术论据。如果有人的补ä¸ĺŹ–ä»Łäş†ä˝ çš„čˇĄä¸č€Śčż› +入了主线，那äąĺŹŞćś‰ä¸€ç§Ťć–ąćł•ĺŹŻä»Ąĺ›žĺş”ä˝ ďĽšé«ĺ…´ä˝ çš„é—®é˘ĺľ—ĺ°č§Łĺ†łďĽŚç»§ç»ä˝ 的工作。 +以这种方式把一个人的工作推ĺ°ä¸€čľąĺŹŻč˝äĽšäĽ¤ĺ®łĺ’Ść°”é¦ďĽŚä˝†ćŻĺś¨ä»–们ĺżč®°äş†č°çš„čˇĄä¸ +çśźćŁč˘«ĺ并ĺľäą…äą‹ĺŽďĽŚç¤ľĺŚşäĽšč®°ä˝Źä˝ 的反应。 diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst new file mode 100644 index 000000000000..956815edbd18 --- /dev/null +++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst @@ -0,0 +1,124 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_advancedtopics: + +é«çş§ä¸»é˘ +======== + +现在，希望您č˝ĺ¤źćŽŚćŹˇĺĽ€ĺŹ‘ćµç¨‹çš„工作方式。然而，čżćś‰ć›´ĺ¤šçš„东西č¦ĺ¦ďĽćś¬čŠ‚将介绍 +一些主é˘ďĽŚčż™äş›ä¸»é˘ĺŻąĺ¸Śćś›ć为Linuxĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹ĺ¸¸č§„é¨ĺ†çš„开发人ĺ‘有帮助。 + +使用Git管ç†čˇĄä¸ +--------------- + +ĺ†…ć ¸ä˝żç”¨ĺ†ĺ¸ĺĽŹç‰ćś¬ćŽ§ĺ¶ĺ§‹äşŽ2002ĺą´ĺťďĽŚĺ˝“ć—¶Linus首次开始使用专有的Bitkeeper应用 +程序。虽然bitkeeperĺ在争议，但ĺ®ć‰€ä˝“现的软件ç‰ćś¬ç®ˇç†ć–ąćł•ĺŤ´č‚Żĺ®šä¸ŤćŻă€‚ĺ†ĺ¸ĺĽŹ +ç‰ćś¬ćŽ§ĺ¶ĺŹŻä»Ąç«‹ĺŤłĺŠ é€źĺ†…ć ¸ĺĽ€ĺŹ‘éˇąç›®ă€‚ĺś¨ĺ˝“ĺ‰Ťçš„ć—¶ä»ŁďĽŚćś‰ĺ‡ ç§Ťĺ…Ťč´ąçš„ćŻ”ç‰ąäżťćŚĺ™¨ć›żä»Łĺ“。 +ć— č®şĺĄ˝ĺťŹďĽŚĺ†…ć ¸éˇąç›®é˝ĺ°†Git作为其选择的工具。 + +使用Git管ç†čˇĄä¸ĺŹŻä»Ąä˝żĺĽ€ĺŹ‘äşşĺ‘çš„ç”źć´»ć›´ĺŠ č˝»ćťľďĽŚĺ°¤ĺ…¶ćŻéšŹçť€čˇĄä¸ć•°é‡Źçš„ĺ˘žĺŠ ă€‚Git +也有其粗糙的边çĽĺ’Śä¸€ĺ®šçš„危险，ĺ®ćŻä¸€ä¸Şĺą´č˝»ĺ’ŚĺĽşĺ¤§çš„工具，仍然在其开发人ĺ‘完善 +ä¸ă€‚本文档不会试图教会读者如何使用git；这会ćŻä¸Şĺ·¨é•żçš„文档。相反，这里的重点 +ĺ°†ćŻGit如何特ĺ«é€‚ĺĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹ă€‚ćłč¦ĺŠ ĺż«Git的开发人ĺ‘ĺŹŻä»Ąĺś¨ä»Ąä¸‹ç˝‘ç«™ä¸Šć‰ľĺ° +更多信ćŻďĽš + + http://git-scm.com/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +在尝试使用ĺ®ä˝żčˇĄä¸ĺŹŻäľ›ĺ…¶ä»–人使用之前，第一č¦ĺŠˇćŻé…读上述站点，对Git的工作 +方式有一个扎实的了解。使用Git的开发人ĺ‘应该č˝ĺ¤źčŽ·ĺľ—主线ĺ储库的副本，探索 +修订历史，ćŹäş¤ĺŻąć ‘的更改，使用ĺ†ć”Żç‰ă€‚了解Git用于重写历史的工具ďĽĺ¦‚Rebase） +äąźĺľćś‰ç”¨ă€‚Git有自己的术čŻĺ’Ść¦‚念；Git的新用ć·ĺş”该了解refsă€čżśç¨‹ĺ†ć”Żă€ç´˘ĺĽ•ă€ +ĺż«čż›ĺ并ă€ćŽ¨ć‹‰ă€ĺ†ç¦»ĺ¤´ç‰ă€‚一开始可č˝ćś‰ç‚ąĺ“人，但这些概念不难通过一点ĺ¦äą 来 +ç†č§Łă€‚ + +使用git生ć通过电ĺ邮件ćŹäş¤çš„补ä¸ćŻćŹé«é€źĺş¦çš„一个ĺľĺĄ˝çš„ç»äą 。 + +当您准备好开始安装Gitć ‘äľ›ĺ…¶ä»–äşşćźĄçś‹ć—¶ďĽŚć‚¨ĺ˝“ç„¶éś€č¦ä¸€ä¸ŞĺŹŻä»Ąä»Žä¸ćŹĺŹ–的服务器。 +如果您有一个可以访问Internet的系统，那äąä˝żç”¨gitĺ®ćŠ¤čż›ç¨‹č®ľç˝®čż™ć ·çš„服务器相 +对简单。ĺ¦ĺ™ďĽŚĺ…Ťč´ąçš„公共ć‰ç®ˇç˝‘ç«™ďĽäľ‹ĺ¦‚github）开始出现在网络上。ć熟的开发 +äşşĺ‘可以在kernel.org上获得一个ĺ¸ć·ďĽŚä˝†čż™äş›ĺ¸ć·ĺą¶ä¸Ťĺ®ąć“找ĺ°ďĽ›ćś‰ĺ…łć›´ĺ¤šäżˇćŻďĽŚ +čŻ·ĺŹ‚é… http://kernel.org/faq/ + +ćŁĺ¸¸çš„Git工作ćµç¨‹ć¶‰ĺŹŠĺ°č®¸ĺ¤šĺ†ć”Żçš„使用。每一条开发线é˝ĺŹŻä»Ąĺ†ä¸şĺŤ•ç‹¬çš„â€śä¸»é˘ +ĺ†ć”Żâ€ťďĽŚĺą¶ç‹¬ç«‹ç»´ćŠ¤ă€‚Gitçš„ĺ†ć”Żćśşćž„ĺľäľżĺ®śďĽŚć˛ˇćś‰ç†ç”±ä¸Ťĺ…Ťč´ąä˝żç”¨ĺ®ä»¬ă€‚而且，在 +任何ć…况下，您é˝ä¸Ťĺş”该在任何您打算让其他人从ä¸ĺŹ—益的ĺ†ć”Żä¸čż›čˇŚĺĽ€ĺŹ‘。应该 +ĺ°Źĺżĺś°ĺ›ĺ»şĺ…¬ĺĽ€ĺŹŻç”¨çš„ĺ†ć”ŻďĽ›ĺ˝“ĺ®ä»¬ĺ¤„于完整的形式并准备好čżčˇŚć—¶(而不ćŻäą‹ĺ‰ŤďĽ‰ďĽŚ +ĺ并开发ĺ†ć”Żçš„补ä¸ă€‚ + +GitćŹäľ›äş†ä¸€äş›ĺĽşĺ¤§çš„工具，可以让您重写开发历史。一个不方便的补ä¸ďĽćŻ”如说， +ä¸€ä¸Şć‰“ç ´äşŚĺ†ćł•çš„补ä¸ďĽŚć–者有其他一些ćŽćľçš„缺陷）可以在适当的位置修复，ć–者 +完全从历史ä¸ć¶ĺ¤±ă€‚一个补ä¸çł»ĺ—可以被重写，就好ĺŹĺ®ćŻĺś¨ä»Šĺ¤©çš„主线之上写的 +ä¸€ć ·ďĽŚĺŤłä˝żä˝ ĺ·˛ç»ŹčŠ±äş†ĺ‡ ä¸Şćśçš„时间在写ĺ®ă€‚可以透ćŽĺś°ĺ°†ć›´ć”ąä»Žä¸€ä¸Şĺ†ć”Żč˝¬ç§»ĺ°ĺŹ¦ +一个ĺ†ć”Żă€‚ç‰ç‰ă€‚ćŽć™şĺś°ä˝żç”¨git修改历史的č˝ĺŠ›ĺŹŻä»Ąĺ¸®ĺŠ©ĺ›ĺ»şé—®é˘ć›´ĺ°‘的干净补ä¸é›†ă€‚ + +然而，过度使用这种č˝ĺŠ›ĺŹŻč˝äĽšĺŻĽč‡´ĺ…¶ä»–é—®é˘ďĽŚč€Śä¸Ťä»…ä»…ćŻĺŻąĺ›ĺ»şĺ®ŚçľŽéˇąç›®ĺŽ†ĺŹ˛çš„ +简单痴迷。重写历史将重写该历史ä¸ĺŚ…ĺ«çš„更改，将经过测试ďĽĺ¸Śćś›ďĽ‰çš„ĺ†…ć ¸ć ‘ĺŹ +ä¸şćśŞç»Źćµ‹čŻ•çš„ĺ†…ć ¸ć ‘ă€‚ä˝†ćŻďĽŚé™¤ć¤äą‹ĺ¤–，如果开发人ĺ‘没有对项目历史的共享视图， +ä»–ä»¬ĺ°±ć— ćł•č˝»ćťľĺś°ĺŤŹä˝śďĽ›ĺ¦‚ćžść‚¨é‡Ťĺ†™äş†ĺ…¶ä»–ĺĽ€ĺŹ‘äşşĺ‘拉入他们ĺ储库的历史，您将 +使这些开发人ĺ‘çš„ç”źć´»ć›´ĺŠ ĺ›°éšľă€‚ĺ› ć¤ďĽŚčż™é‡Śćś‰ä¸€ä¸Şç®€ĺŤ•çš„经验法ĺ™ďĽšč˘«ĺŻĽĺ‡şĺ°ĺ…¶ä»– +人的历史在ć¤ĺŽé€šĺ¸¸č˘«č®¤ä¸şćŻä¸ŤĺŹŻĺŹçš„。 + +ĺ› ć¤ďĽŚä¸€ć—¦ĺ°†ä¸€ç»„更改推é€ĺ°ĺ…¬ĺĽ€ĺŹŻç”¨çš„服务器上，就不应该重写这些更改。如果您 +尝试强ĺ¶čż›čˇŚä¸ŤäĽšĺŻĽč‡´ĺż«čż›ĺ并ďĽĺŤłä¸Ťĺ…±äş«ĺŚä¸€ĺŽ†ĺŹ˛č®°ĺ˝•çš„更改）的更改，Git将尝 +试强ĺ¶ć‰§čˇŚć¤č§„ĺ™ă€‚可以重写ć¤ćŁ€ćźĄďĽŚćś‰ć—¶ĺŹŻč˝éś€č¦é‡Ťĺ†™ĺŻĽĺ‡şçš„ć ‘ă€‚ĺś¨ć ‘äą‹é—´ç§»ĺŠ¨ĺŹ +更集以éżĺ…ŤLinux-nextä¸çš„冲çŞĺ°±ćŻä¸€ä¸Şäľ‹ĺ。但这种行为应该ćŻç˝•č§çš„。这就ćŻä¸ş +什äąĺĽ€ĺŹ‘应该在ç§ćś‰ĺ†ć”Żä¸čż›čˇŚďĽĺż…č¦ć—¶ĺŹŻä»Ąé‡Ťĺ†™ďĽ‰ĺą¶ä¸”只有在公共ĺ†ć”Żĺ¤„于ĺç†çš„ +é«çş§çŠ¶ć€ć—¶ć‰Ťč˝¬ç§»ĺ°ĺ…¬ĺ…±ĺ†ć”Żä¸çš„ĺŽźĺ› äą‹ä¸€ă€‚ + +当主线ďĽć–其他一组ĺŹć›´ć‰€ĺźşäşŽçš„ć ‘ďĽ‰ĺ‰Ťčż›ć—¶ďĽŚĺľĺ®ąć“ä¸ŽčŻĄć ‘ĺ并以保ćŚé˘†ĺ…地位。 +对于一个ç§ćś‰çš„ĺ†ć”ŻďĽŚrebasing 可č˝ćŻä¸€ä¸Şĺľĺ®ąć“č·źä¸ŠĺŹ¦ä¸€ćŁµć ‘çš„ć–ąćł•ďĽŚä˝†ćŻä¸€ć—¦ +ä¸€ćŁµć ‘č˘«ĺŻĽĺ‡şĺ°ĺ…¨ä¸–界，rebasing就不ćŻä¸€ä¸Şé€‰éˇąă€‚一旦发生这种ć…况，就必须进行 +完全ĺ并ďĽmerge）。ĺ并有时ćŻĺľćś‰ć„Źäą‰çš„，但ćŻčż‡äşŽé˘‘çąçš„ĺ并会不必č¦ĺś°ć‰°äą± +历史。在这种ć…况下，建议的技术ćŻä¸Ťç»Źĺ¸¸ĺ并，通常只在特定的发ĺ¸ç‚ąďĽĺ¦‚主线-rc +发ĺ¸ďĽ‰ĺ并。如果您对特定的更改感ĺ°ç´§ĺĽ ，ĺ™ĺŹŻä»Ąĺ§‹ç»ĺś¨ç§ćś‰ĺ†ć”Żä¸ć‰§čˇŚćµ‹čŻ•ĺ并。 +在这种ć…况下，git rerere ĺ·Ąĺ…·ĺľćś‰ç”¨ďĽ›ĺ®č®°ä˝Źĺ并冲çŞćŻĺ¦‚ä˝•č§Łĺ†łçš„ďĽŚčż™ć ·ć‚¨ĺ°± +不必重复相ĺŚçš„工作。 + +关于Gitčż™ć ·çš„ĺ·Ąĺ…·çš„ä¸€ä¸Şćś€ĺ¤§çš„ĺŹŤĺ¤ŤćŠ±ć€¨ćŻďĽščˇĄä¸ä»Žä¸€ä¸Şĺ储库ĺ°ĺŹ¦ä¸€ä¸Şĺ储库的 +大量移动使得ĺľĺ®ąć“陷入错误建议的ĺŹć›´ä¸ďĽŚčż™äş›ĺŹć›´éżĺĽ€ĺ®ˇćźĄé›·čľľčż›ĺ…Ąä¸»çşżă€‚当内 +ć ¸ĺĽ€ĺŹ‘äşşĺ‘çś‹ĺ°čż™ç§Ťć…况发生时，他们往往会感ĺ°ä¸Ťé«ĺ…´ďĽ›ĺś¨Gitć ‘ä¸Šć”ľç˝®ćśŞćźĄçś‹ć– +主é˘ĺ¤–的补ä¸ĺŹŻč˝äĽšĺ˝±ĺ“Ťć‚¨ĺ°†ćťĄčŽ·ĺŹ–ć ‘çš„č˝ĺŠ›ă€‚引用Linus: + +:: + + ä˝ ĺŹŻä»Ąç»™ć‘发补ä¸ďĽŚä˝†č¦ć‘ä»Žä˝ ĺ“Şé‡ŚĺŹ–ä¸€ä¸ŞGit补ä¸ďĽŚć‘需č¦çźĄé“ä˝ çźĄé“ + ä˝ ĺś¨ĺšä»€äąďĽŚć‘需č¦č˝ĺ¤źç›¸äżˇäş‹ć…而不去检查每个个人改ĺŹă€‚ + +ďĽhttp://lwn.net/articles/224135/）。 + +为了éżĺ…Ťčż™ç§Ťć…况，请确保给定ĺ†ć”Żä¸çš„所有补ä¸é˝ä¸Žç›¸ĺ…łä¸»é˘ç´§ĺŻ†ç›¸ĺ…łďĽ›â€śé©±ĺŠ¨ç¨‹ĺşŹ +修复”ĺ†ć”Żä¸Ťĺş”ć›´ć”ąć ¸ĺżĺ†…ĺ管ç†ä»Łç 。而且，最重č¦çš„ćŻďĽŚä¸Ťč¦ä˝żç”¨Gitć ‘ćťĄç»•čż‡ +ĺ®ˇćźĄčż‡ç¨‹ă€‚ä¸Ťć—¶çš„ĺ°†ć ‘çš„ć‘č¦ĺŹ‘ĺ¸ĺ°ç›¸ĺ…łçš„ĺ—表ä¸ďĽŚĺ˝“时间ĺ适时，请求 +Linux-next ä¸ĺŚ…ĺ«čŻĄć ‘。 + +如果其他人开始发é€čˇĄä¸ä»ĄĺŚ…ĺ«ĺ°ć‚¨çš„ć ‘ä¸ďĽŚä¸Ťč¦ĺżč®°ćźĄçś‹ĺ®ä»¬ă€‚čżč¦çˇ®äżťć‚¨ç»´ćŠ¤ćŁçˇ® +的作者信ćŻďĽ› ``git am`` 工具在这方面ĺšĺľ—最好，但ćŻĺ¦‚ćžśĺ®é€ščż‡ç¬¬ä¸‰ć–ąč˝¬ĺŹ‘给您， +您可č˝éś€č¦ĺś¨čˇĄä¸ä¸ć·»ĺŠ “From：”行。 + +请求pull操作时，请务必ćŹäľ›ć‰€ćś‰ç›¸ĺ…łäżˇćŻďĽšć ‘的位置ă€č¦ć‹‰çš„ĺ†ć”Żä»ĄĺŹŠć‹‰ć“Ťä˝śĺ°†ĺŻĽč‡´ +的更改。在这方面，git request pull 命令非常有用；ĺ®ĺ°†ćŚ‰ç…§ĺ…¶ä»–开发人ĺ‘的预期 +ć ĽĺĽŹĺŚ–čŻ·ć±‚ďĽŚĺą¶ćŁ€ćźĄä»Ąçˇ®äżťć‚¨č®°ä˝Źäş†ĺ°†čż™äş›ć›´ć”ąćŽ¨é€ĺ°ĺ…¬ĺ…±ćśŤĺŠˇĺ™¨ă€‚ + +ĺ®ˇćźĄčˇĄä¸ +-------- + +一些读者当然会反对将本节与“é«çş§ä¸»é˘â€ťć”ľĺś¨ä¸€čµ·ďĽŚĺ› 为即使ćŻĺšĺĽ€ĺ§‹çš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ +也应该检查补ä¸ă€‚当然，ĺ¦äą ĺ¦‚ä˝•ĺś¨ĺ†…ć ¸çŽŻĺ˘ä¸çĽ–程没有比查看其他人发ĺ¸çš„代ç 更好 +的方法了。ć¤ĺ¤–，审é…者永远供不应求；通过查看代ç ，您可以对整个ćµç¨‹ĺšĺ‡şé‡Ťĺ¤§č´ˇçŚ®ă€‚ + +审查代ç 可č˝ćŻä¸€ä¸Şä»¤äşşç”źç•Źçš„前景，特ĺ«ćŻĺŻąäşŽä¸€ä¸Şć–°çš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘来说，他们 +可č˝äĽšĺŻąĺ…¬ĺĽ€čŻ˘é—®ä»Łç ć„źĺ°ç´§ĺĽ ，而这些代ç ćŻç”±é‚Łäş›ćś‰ć›´ĺ¤šç»ŹéŞŚçš„äşşĺŹ‘ĺ¸çš„。不过， +即使ćŻćś€ćś‰ç»ŹéŞŚçš„ĺĽ€ĺŹ‘äşşĺ‘编写的代ç 也可以得ĺ°ć”ąčż›ă€‚也许对评审ĺ‘ďĽć‰€ćś‰čŻ„审ĺ‘） +最好的建议ćŻďĽšćŠŠčŻ„审评论当ćé—®é˘č€Śä¸ŤćŻć‰ąčŻ„。询问“在这条路径ä¸ĺ¦‚何释放é”？” +总ćŻćŻ”说“这里的é”ćŻé”™čŻŻçš„”更好。 + +不ĺŚçš„开发人ĺ‘将从不ĺŚçš„角度审查代ç 。一些主č¦ĺ…łćł¨çš„ćŻçĽ–ç ć ·ĺĽŹä»ĄĺŹŠä»Łç čˇŚćŻ +ĺ¦ćś‰ĺ°ľéšŹç©şć Ľă€‚其他人将主č¦ĺ…łćł¨čˇĄä¸ä˝śä¸şä¸€ä¸Şć•´ä˝“实现的ĺŹć›´ćŻĺ¦ĺŻąĺ†…ć ¸ćś‰ĺĄ˝ĺ¤„ă€‚ +然而，其他人会检查ćŻĺ¦ĺ在é”定问é˘ă€ĺ †ć 使用过度ă€ĺŹŻč˝çš„安全问é˘ă€ĺś¨ĺ…¶ä»– +地方发现的代ç 重复ă€č¶łĺ¤źçš„文档ă€ĺŻąć€§č˝çš„不ĺ©ĺ˝±ĺ“Ťă€ç”¨ć·ç©şé—´ABI更改ç‰ă€‚所有 +类型的检查，如果ĺ®ä»¬ĺŻĽč‡´ć›´ĺĄ˝çš„代ç čż›ĺ…Ąĺ†…ć ¸ďĽŚé˝ćŻĺŹ—欢迎和值得的。 diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst new file mode 100644 index 000000000000..2bbd76161e10 --- /dev/null +++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst @@ -0,0 +1,64 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_conclusion: + +ć›´ĺ¤šäżˇćŻ +======== + +关于Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ĺ’Śç›¸ĺ…łä¸»é˘çš„信ćŻćťĄćşĺľĺ¤šă€‚首ĺ…ćŻĺś¨ĺ†…ć ¸ćşä»Łç ĺ†ĺŹ‘ä¸ć‰ľĺ°çš„ +文档目录。顶级 :ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` +文件ćŻä¸€ä¸Şé‡Ťč¦çš„čµ·ç‚ą +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` +ĺ’Ś :ref:`process/submitting-drivers.rst <submittingdrivers>` +äąźćŻć‰€ćś‰ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘é˝ĺş”该é…读的内容。许多内é¨ĺ†…ć ¸APIé˝ćŻä˝żç”¨kerneldocćśşĺ¶ +记录的；“make htmldocs”ć–“make pdfdocs”可用于以HTMLć–PDFć ĽĺĽŹç”źćčż™äş›ć–‡ćˇŁďĽ +尽管ćźäş›ĺŹ‘行ç‰ćŹäľ›çš„texç‰ćś¬äĽšé‡ĺ°ĺ†…é¨é™ĺ¶ďĽŚć— ćł•ćŁçˇ®ĺ¤„ç†ć–‡ćˇŁďĽ‰ă€‚ + +不ĺŚçš„网站在ĺ„ä¸Şç»†čŠ‚ĺ±‚ć¬ˇä¸Šč®¨č®şĺ†…ć ¸ĺĽ€ĺŹ‘ă€‚ć‚¨çš„ä˝śč€…ćłč°¦č™šĺś°ĺ»şč®®ç”¨ http://lwn.net/ +作为来ćşďĽ›ćś‰ĺ…łč®¸ĺ¤šç‰ąĺ®šĺ†…ć ¸ä¸»é˘çš„信ćŻĺŹŻä»Ąé€ščż‡ä»Ąä¸‹ç˝‘址的lwnĺ†…ć ¸ç´˘ĺĽ•ć‰ľĺ°ďĽš + + http://lwn.net/kernel/index/ + +除ć¤äą‹ĺ¤–ďĽŚĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘的一个宝贵资ćşćŻďĽš + + http://kernelnewbies.org/ + +当然，ć‘们不应该ĺżč®° http://kernel.org/ čż™ćŻĺ†…ć ¸ĺŹ‘ĺ¸äżˇćŻçš„最ç»ä˝Ťç˝®ă€‚ + +ĺ…łäşŽĺ†…ć ¸ĺĽ€ĺŹ‘ćś‰ĺľĺ¤šäą¦ďĽš + + Linux设备驱动程序，第三ç‰ďĽJonathan Corbetă€Alessandro Rubiniĺ’ŚGreg Kroah Hartman）。 + 在线：http://lwn.net/kernel/ldd3/ + + Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ďĽRobert Love）。 + + 了解Linuxĺ†…ć ¸ďĽDaniel Bovetĺ’ŚMarco Cesati）。 + +然而，所有这些书é˝ćś‰ä¸€ä¸Şĺ…±ĺŚçš„缺点：当ĺ®ä»¬ä¸Šćž¶ć—¶ďĽŚĺ®ä»¬ĺľ€ĺľ€ćś‰äş›čż‡ć—¶ďĽŚč€Śä¸”ĺ®ä»¬ +已经上架一段时间了。不过，在那里čżĺŹŻä»Ąć‰ľĺ°ç›¸ĺ˝“多的好信ćŻă€‚ + +有关git的文档，请访问： + + http://www.kernel.org/pub/software/scm/git/docs/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +结论 +==== + +祝贺所有通过这篇冗长的文件的人。希望ĺ®č˝ĺ¤źĺ¸®ĺŠ©ć‚¨ç†č§ŁLinuxĺ†…ć ¸ćŻĺ¦‚何开发的， +以及您如何参与这个过程。 + +最ĺŽďĽŚé‡Ťč¦çš„ćŻĺŹ‚与。任何开ćşč˝Żä»¶éˇąç›®é˝ä¸Ťč¶…过其贡献者投入其ä¸çš„总和。Linuxĺ†…ć ¸ +çš„ĺŹ‘ĺ±•é€źĺş¦ĺ’Śä»Ąĺ‰Ťä¸€ć ·ĺż«ďĽŚĺ› ä¸şĺ®ĺľ—ĺ°äş†ĺ¤§é‡ŹĺĽ€ĺŹ‘äşşĺ‘的帮助，他们é˝ĺś¨ĺŠŞĺŠ›ä˝żĺ®ĺŹĺľ— +ć›´ĺĄ˝ă€‚ĺ†…ć ¸ćŻä¸€ä¸Şä¸»č¦çš„äľ‹ĺ，说ćŽĺ˝“ćĺŤä¸Šä¸‡çš„人为了一个共ĺŚçš„ç›®ć ‡ä¸€čµ·ĺ·Ąä˝ść—¶ďĽŚ +可以ĺšäş›ä»€äąă€‚ + +ä¸Ťčż‡ďĽŚĺ†…ć ¸ć€»ćŻĺŹŻä»Ąä»Žć›´ĺ¤§çš„开发人ĺ‘基础ä¸čŽ·ç›Šă€‚总有更多的工作č¦ĺšă€‚但ćŻďĽŚĺŚć · +重č¦çš„ćŻďĽŚLinux生ć€çł»ç»źä¸çš„ĺ¤§ĺ¤šć•°ĺ…¶ä»–ĺŹ‚ä¸Žč€…ĺŹŻä»Ąé€ščż‡ä¸şĺ†…ć ¸ĺšĺ‡şč´ˇçŚ®č€ŚĺŹ—益。使 +代ç 进入主线ćŻćŹé«ä»Łç 质量ă€é™Ťä˝Žç»´ćŠ¤ĺ’Śĺ†ĺŹ‘ć本ă€ćŹé«ĺŻąĺ†…ć ¸ĺĽ€ĺŹ‘ć–ąĺ‘的影响程度 +ç‰çš„关键。这ćŻä¸€ç§Ťäşşäşşé˝čµ˘çš„ĺ±€éť˘ă€‚č¸˘ĺĽ€ä˝ çš„çĽ–čľ‘ďĽŚćťĄĺŠ ĺ…Ąć‘们ĺ§ďĽŚä˝ 会非常受 +欢迎的。 diff --git a/Documentation/translations/zh_CN/process/code-of-conduct-interpretation.rst b/Documentation/translations/zh_CN/process/code-of-conduct-interpretation.rst new file mode 100644 index 000000000000..c323ce76e0cb --- /dev/null +++ b/Documentation/translations/zh_CN/process/code-of-conduct-interpretation.rst @@ -0,0 +1,108 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/code-of-conduct-interpretation.rst <code_of_conduct_interpretation>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_code_of_conduct_interpretation: + +Linuxĺ†…ć ¸č´ˇçŚ®č€…ĺĄ‘çş¦čˇŚä¸şĺ‡†ĺ™č§Łé‡Š +=============================== + +:ref:`cn_code_of_conduct` 准ĺ™ćŻä¸€ä¸Şé€šç”¨ć–‡ćˇŁďĽŚć—¨ĺś¨ä¸şĺ‡ 乎所有开ćşç¤ľĺŚşćŹäľ›ä¸€ĺĄ—规ĺ™ă€‚ +每个开ćşç¤ľĺŚşé˝ćŻç‹¬ä¸€ć— 二的，Linuxĺ†…ć ¸äąźä¸Ťäľ‹ĺ¤–ă€‚ĺ› ć¤ďĽŚćś¬ć–‡ćŹŹčż°äş†Linuxĺ†…ć ¸ç¤ľĺŚşä¸ +如何解释ĺ®ă€‚ć‘们也不希望这种解释随着时间的推移ćŻéť™ć€çš„ďĽŚĺą¶ĺ°†ć ąćŤ®éś€č¦čż›čˇŚč°ć•´ă€‚ + +ä¸ŽĺĽ€ĺŹ‘č˝Żä»¶çš„â€śäĽ ç»źâ€ťć–ąćł•ç›¸ćŻ”ďĽŚLinuxĺ†…ć ¸ĺĽ€ĺŹ‘ĺ·Ąä˝śćŻä¸€ä¸Şéťžĺ¸¸ä¸ŞäşşĺŚ–çš„čż‡ç¨‹ă€‚ä˝ çš„č´ˇçŚ® +ĺ’ŚčŚĺŽçš„ćłćł•ĺ°†č˘«ä»”细审查，往往导致批ĺ¤ĺ’Ść‰ąčŻ„ă€‚ĺ®ˇćźĄĺ°†ĺ‡ äąŽć€»ćŻéś€č¦ć”ąčż›ďĽŚćťć–™ć‰Ť +č˝ĺŚ…ć‹¬ĺś¨ĺ†…ć ¸ä¸ă€‚č¦çźĄé“čż™ćŻĺ› 为所有相关人ĺ‘é˝ĺ¸Śćś›çś‹ĺ°Linux整体ć功的最佳解决方 +ćˇă€‚这个开发过程已经被čŻćŽĺŹŻä»Ąĺ›ĺ»şćś‰ĺŹ˛ä»ĄćťĄćś€ĺĄĺŁ®çš„ć“Ťä˝śçł»ç»źĺ†…ć ¸ďĽŚć‘们不ćłĺšä»»ä˝• +äş‹ć…来导致ćŹäş¤č´¨é‡Źĺ’Śćś€ç»ç»“果的下降。 + +维护者 +------ + +行为准ĺ™ĺ¤šć¬ˇä˝żç”¨â€śç»´ćŠ¤č€…â€ťä¸€čŻŤă€‚ĺś¨ĺ†…ć ¸ç¤ľĺŚşä¸ďĽŚâ€śç»´ćŠ¤č€…”ćŻč´źč´Łĺ系统ă€é©±ĺŠ¨ç¨‹ĺşŹć– +ć–‡ä»¶çš„ä»»ä˝•äşşďĽŚĺą¶ĺś¨ĺ†…ć ¸ćşä»Łç ć ‘çš„ç»´ćŠ¤č€…ć–‡ä»¶ä¸ĺ—出。 + +č´Łä»» +---- + +《行为准ĺ™ă€‹ćŹĺ°äş†ç»´ćŠ¤äşşĺ‘çš„ćťĺ©ĺ’Śč´Łä»»ďĽŚčż™éś€č¦čż›ä¸€ćĄćľ„清。 + +首ĺ…，最重č¦çš„ćŻďĽŚćś‰ä¸€ä¸Şĺç†çš„ćśźćś›ćŻç”±ç»´ćŠ¤äşşĺ‘通过实例来领导。 + +äąźĺ°±ćŻčŻ´ďĽŚć‘们的社区ćŻĺążé”的，对维护者没有新的č¦ć±‚，他们单方面处ç†ĺ…¶ä»–人在 +他们活č·çš„社区的行为。这一责任由ć‘们所有人承担，最ç»ă€ŠčˇŚä¸şĺ‡†ĺ™ă€‹č®°ĺ˝•äş†ćś€ç»çš„ +上诉路径，以é˛ćś‰ĺ…łčˇŚä¸şé—®é˘çš„é—®é˘ć‚¬č€ŚćśŞĺ†łă€‚ + +维护人ĺ‘应该愿意在出现问é˘ć—¶ćŹäľ›ĺ¸®ĺŠ©ďĽŚĺą¶ĺś¨éś€č¦ć—¶ä¸Žç¤ľĺŚşä¸çš„其他人ĺ作。如果您 +不确定如何处ç†ĺ‡şçŽ°çš„ć…况，请不č¦ĺ®łć€•č”系技术咨询委ĺ‘会ďĽTAB）ć–其他维护人ĺ‘。 +除非您愿意，ĺ¦ĺ™ä¸ŤäĽšĺ°†ĺ…¶č§†ä¸şčżťč§„报告。如果您不确定ćŻĺ¦čŻĄč”çł»TAB ć–任何其他维 +护人ĺ‘，请č”çł»ć‘们的冲çŞč°č§Łäşş Mishi Choudhary <mishi@linux.com>。 + +最ĺŽďĽŚâ€śĺ–„待对方”才ćŻćŻŹä¸Şäşşçš„最ç»ç›®ć ‡ă€‚ć‘们知é“每个人é˝ćŻäşşďĽŚćś‰ć—¶ć‘们é˝äĽšĺ¤±č´ĄďĽŚ +但ć‘们所有人的首č¦ç›®ć ‡ĺş”该ćŻĺŠŞĺŠ›ĺŹ‹ĺĄ˝ĺś°č§Łĺ†łé—®é˘ă€‚执行行为准ĺ™ĺ°†ćŻćś€ĺŽçš„选择。 + +ć‘ä»¬çš„ç›®ć ‡ćŻĺ›ĺ»şä¸€ä¸ŞĺĽşĺ¤§çš„ă€ćŠ€ćśŻĺ…进的操作系统，以及所涉及的技术复杂性，这自 +然需č¦ä¸“业知识和决ç–。 + +ć‰€éś€çš„ä¸“ä¸šçźĄčŻ†ĺ› č´ˇçŚ®é˘†ĺźźč€ŚĺĽ‚ă€‚ĺ®ä¸»č¦ç”±ä¸Šä¸‹ć–‡ĺ’ŚćŠ€ćśŻĺ¤Ťćť‚性决定，其次由贡献者和 +维护者的期望决定。 + +专家的期望和决ç–é˝č¦ç»Źčż‡č®¨č®şďĽŚä˝†ĺś¨ćś€ĺŽďĽŚä¸şäş†ĺŹ–得进展，必须č˝ĺ¤źĺšĺ‡şĺ†łç–。这一 +特ćťćŽŚćŹˇĺś¨ç»´ćŠ¤äşşĺ‘和项目领导的手ä¸ďĽŚé˘„计将善意使用。 + +ĺ› ć¤ďĽŚč®ľĺ®šä¸“业知识期望ă€ä˝śĺ‡şĺ†łĺ®šĺ’Ść‹’绝不适当的贡献不被视为违反行为准ĺ™ă€‚ + +虽然维护人ĺ‘一č¬é˝ć¬˘čżŽć–°ćťĄč€…，但他们帮助ďĽć–°ďĽ‰č´ˇçŚ®č€…克服障碍的č˝ĺŠ›ćś‰é™ďĽŚĺ› ć¤ +他们必须确定äĽĺ…事项。这也不应被视为违反了行为准ĺ™ă€‚ĺ†…ć ¸ç¤ľĺŚşć„ŹčŻ†ĺ°čż™ä¸€ç‚ąďĽŚĺą¶ +以ĺ„种形式ćŹäľ›ĺ…Ąé—¨çş§čŠ‚目，如 kernelnewbies.org 。 + +čŚĺ›´ +---- + +Linuxĺ†…ć ¸ç¤ľĺŚşä¸»č¦ĺś¨ä¸€ç»„公共电ĺ邮件ĺ—表上进行交互，这些ĺ—表ĺ†ĺ¸ĺś¨ç”±ĺ¤šä¸Şä¸ŤĺŚ +公司ć–个人控ĺ¶çš„多个不ĺŚćśŤĺŠˇĺ™¨ä¸Šă€‚所有这些ĺ—表é˝ĺś¨ĺ†…ć ¸ćşä»Łç ć ‘ä¸çš„ +MAINTAINERS 文件ä¸ĺ®šäą‰ă€‚发é€ĺ°čż™äş›é‚®ä»¶ĺ—表的任何电ĺ邮件é˝č˘«č§†ä¸şĺŚ…ĺ«ĺś¨čˇŚä¸ş +准ĺ™ä¸ă€‚ + +使用 kernel.org bugzilla和其他ĺ系统bugzilla ć–bug跟踪工具的开发人ĺ‘应该éµĺľŞ +行为准ĺ™çš„指导原ĺ™ă€‚Linuxĺ†…ć ¸ç¤ľĺŚşć˛ˇćś‰â€śĺ®ć–ąâ€ťéˇąç›®ç”µĺ邮件地址ć–“ĺ®ć–ąâ€ťç¤ľäş¤ĺŞ’ä˝“ +地址。使用kernel.org电ĺ邮件ĺ¸ć·ć‰§čˇŚçš„任何活动必须éµĺľŞä¸şkernel.org发ĺ¸çš„行为 +准ĺ™ďĽŚĺ°±ĺŹä»»ä˝•ä˝żç”¨ĺ…¬ĺŹ¸ç”µĺ邮件ĺ¸ć·çš„个人必须éµĺľŞčŻĄĺ…¬ĺŹ¸çš„特定规ĺ™ä¸€ć ·ă€‚ + +行为准ĺ™ĺą¶ä¸Ťç¦ć˘ĺś¨é‚®ä»¶ĺ—表ć¶ćŻă€ĺ†…ć ¸ć›´ć”ąć—Ąĺż—ć¶ćŻć–代ç 注释ä¸ç»§ç»ĺŚ…ĺ«ĺŤç§°ă€ +电ĺ邮件地址和相关注释。 + +其他论坛ä¸çš„互动包括在适用于上述论坛的任何规ĺ™ä¸ďĽŚé€šĺ¸¸ä¸ŤĺŚ…括在行为准ĺ™ä¸ă€‚ +除了在ćžç«Żć…况下可č€č™‘的例外ć…况。 + +ćŹäş¤ç»™ĺ†…ć ¸çš„č´ˇçŚ®ĺş”čŻĄä˝żç”¨é€‚ĺ˝“çš„čŻč¨€ă€‚在行为准ĺ™äą‹ĺ‰Ťĺ·˛ç»Źĺ在的内容现在不会被 +视为违反。然而，不适当的čŻč¨€ĺŹŻä»Ąč˘«č§†ä¸şä¸€ä¸Şbug；如果任何相关方ćŹäş¤čˇĄä¸ďĽŚ +čż™ć ·çš„bug将被更快地修复。当前属于用ć·/ĺ†…ć ¸API的一é¨ĺ†çš„表达式，ć–者反ć ĺ·˛ +发ĺ¸ć ‡ĺ‡†ć–规čŚä¸ä˝żç”¨çš„术čŻçš„表达式，不被视为bug。 + +执行 +---- + +行为准ĺ™ä¸ĺ—出的地址属于行为准ĺ™ĺ§”ĺ‘会。https://kernel.org/code-of-conduct.html +ĺ—出了在任何给定时间接收这些电ĺ邮件的确ĺ‡ćĺ‘。ćĺ‘不č˝č®żé—®ĺś¨ĺŠ 入委ĺ‘会之前 +ć–离开委ĺ‘会之ĺŽć‰€ĺšçš„报告。 + +最ĺťçš„行为准ĺ™ĺ§”ĺ‘会由TAB的志愿者以及作为ä¸ç«‹ç¬¬ä¸‰ć–ąçš„专业č°č§Łäşşç»„ć。委ĺ‘会 +的首č¦ä»»ĺŠˇćŻĺ»şç«‹ć–‡ä»¶ĺŚ–çš„ćµç¨‹ďĽŚĺą¶ĺ°†ĺ…¶ĺ…¬ĺĽ€ă€‚ + +如果报告人不希望将整个委ĺ‘会纳入投诉ć–ĺ…łĺ‡ďĽŚĺŹŻç›´ćŽĄč”系委ĺ‘会的任何ćĺ‘，包括 +č°č§Łäşşă€‚ + +行为准ĺ™ĺ§”ĺ‘äĽšć ąćŤ®ćµç¨‹ĺ®ˇćźĄćˇäľ‹ďĽč§ä¸Šć–‡ďĽ‰ďĽŚĺą¶ć ąćŤ®éś€č¦ĺ’Śé€‚当与TAB协商，例如请求 +ĺ’ŚćŽĄć”¶ćś‰ĺ…łĺ†…ć ¸ç¤ľĺŚşçš„äżˇćŻă€‚ + +委ĺ‘会ĺšĺ‡şçš„任何决定é˝ĺ°†ćŹäş¤ĺ°čˇ¨ä¸ďĽŚä»Ąäľżĺś¨ĺż…č¦ć—¶ä¸Žç›¸ĺ…łç»´ćŠ¤äşşĺ‘一起执行。行为 +准ĺ™ĺ§”ĺ‘会的决定可以通过三ĺ†äą‹äşŚçš„投票推翻。 + +每ĺŁĺş¦ďĽŚčˇŚä¸şĺ‡†ĺ™ĺ§”ĺ‘äĽšĺ’Ść ‡çľĺ°†ćŹäľ›ä¸€ä»˝ćŠĄĺ‘ŠďĽŚć¦‚述行为准ĺ™ĺ§”ĺ‘会收ĺ°çš„匿ĺŤćŠĄĺ‘Š +及其状ć€ďĽŚä»ĄĺŹŠä»»ä˝•ĺ¦ĺ†łĺ†łĺ®šçš„细节，包括完整和可识ĺ«çš„投票细节。 + +ć‘们希望在ĺŻĺŠ¨ćśźäą‹ĺŽä¸şčˇŚä¸şĺ‡†ĺ™ĺ§”ĺ‘会人ĺ‘配备建立一个不ĺŚçš„ćµç¨‹ă€‚发生ć¤ć…况时， +将使用该信ćŻć›´ć–°ć¤ć–‡ćˇŁă€‚ diff --git a/Documentation/translations/zh_CN/process/code-of-conduct.rst b/Documentation/translations/zh_CN/process/code-of-conduct.rst new file mode 100644 index 000000000000..99024df058e9 --- /dev/null +++ b/Documentation/translations/zh_CN/process/code-of-conduct.rst @@ -0,0 +1,72 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_code_of_conduct: + +č´ˇçŚ®č€…ĺĄ‘çş¦čˇŚä¸şĺ‡†ĺ™ +++++++++++++++++++ + +ć‘们的誓言 +========== + +为了čĄé€ 一个开放ă€ĺŹ‹ĺĄ˝çš„环ĺ˘ďĽŚć‘们作为贡献者和维护人承诺，让ć‘们的社区和参 +ä¸Žč€…ďĽŚć‹Ąćś‰ä¸€ä¸Şć— éŞšć‰°çš„ä˝“éŞŚďĽŚć— č®şĺą´éľ„ă€ä˝“ĺž‹ă€ć®‹ç–ľă€ç§Ťć—Źă€ć€§ĺ«ç‰ąĺľă€ć€§ĺ«č®¤ĺŚ +和表达ă€ç»ŹéŞŚć°´ĺąłă€ć•™č‚˛ç¨‹ĺş¦ă€ç¤ľäĽšçŠ¶ĺ†µďĽŚç»ŹćµŽĺś°ä˝Ťă€ĺ›˝ç±Ťă€ä¸Şäşşĺ¤–貌ă€ç§Ťć—Źă€ĺ®—ć•™ +ć–性身份和取ĺ‘。 + +ć‘ä»¬çš„ć ‡ĺ‡† +========== + +有助于ĺ›é€ 积ćžçŽŻĺ˘çš„行为包括： + +* 使用欢迎和包容的čŻč¨€ +* 尊重不ĺŚçš„观点和经验 +* äĽé›…地接受建设性的批评 +* 关注什äąĺŻąç¤ľĺŚşćś€ćś‰ĺ© +* 对其他社区ćĺ‘表示ĺŚć… + +参与者的不可接受行为包括： + +* 使用性意味的čŻč¨€ć–意象以及不受欢迎的性注意ć–者更过ĺ†çš„行为 +* 煽动ă€äľ®čľ±/贬损评论以及个人ć–政治攻击 +* 公开ć–ç§ä¸‹éŞšć‰° +* 未经ćŽçˇ®č®¸ĺŹŻďĽŚĺŹ‘ĺ¸ä»–äşşçš„ç§äşşäżˇćŻďĽŚĺ¦‚物ç†ć–电ĺ地址。 +* 在专业场ĺ被ĺç†č®¤ä¸şä¸Ťé€‚当的其他行为 + +ć‘们的责任 +========== + +维护人ĺ‘č´źč´Łćľ„ć¸…ĺŹŻćŽĄĺŹ—čˇŚä¸şçš„ć ‡ĺ‡†ďĽŚĺą¶ĺş”é’对任何不可接受行为采取适当和公平的 +çş ćŁćŽŞć–˝ă€‚ + +维护人ĺ‘有ćťĺ’Śč´Łä»»ĺ 除ă€çĽ–čľ‘ć–拒绝与本行为准ĺ™ä¸Ťä¸€č‡´çš„评论ă€ć‰żčŻşă€ä»Łç 〠+wiki编辑ă€é—®é˘ĺ’Śĺ…¶ä»–贡献，ć–ćš‚ć—¶ć–永久ç¦ć˘ä»»ä˝•č´ˇçŚ®č€…从事他们认为不适当〠+ĺ¨čă€ĺ†’犯ć–有害的其他行为。 + +čŚĺ›´ +==== + +当个人代表项目ć–其社区时，本行为准ĺ™ć—˘é€‚用于项目空间，也适用于公共空间。 +代表一个项目ć–社区的例ĺ包括使用一个ćŁĺĽŹçš„项目电ĺ邮件地址，通过一个ćŁĺĽŹ +的社交媒体ĺ¸ć·ĺŹ‘ĺ¸ďĽŚć–者在在线ć–离线事件ä¸ć‹…任指定的代表。项目维护人ĺ‘可以 +进一ćĄĺ®šäą‰ĺ’Śćľ„清项目的表示。 + +执行 +==== + +如有滥用ă€éŞšć‰°ć–其他不可接受的行为，可č”系行为准ĺ™ĺ§”ĺ‘会<conduct@kernel.org>。 +所有投诉é˝ĺ°†ćŽĄĺŹ—审查和č°ćźĄďĽŚĺą¶ĺ°†ĺľ—ĺ°ĺż…č¦ĺ’Śé€‚当的ç”复。行为准ĺ™ĺ§”ĺ‘会有义务 +对事件报告人保密。具体执行政ç–的进一ćĄç»†čŠ‚可单独公ĺ¸ă€‚ + +归属 +==== + +本行为准ĺ™ć”ąçĽ–自《贡献者契约》，ç‰ćś¬1.4，可从 +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 获取。 + +解释 +==== + +有关Linuxĺ†…ć ¸ç¤ľĺŚşĺ¦‚ä˝•č§Łé‡Šć¤ć–‡ćˇŁďĽŚčŻ·ĺŹ‚é… :ref:`cn_code_of_conduct_interpretation` diff --git a/Documentation/translations/zh_CN/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 3cb09803e084..5479c591c2f7 100644 --- a/Documentation/translations/zh_CN/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -1,19 +1,10 @@ -Chinese translated version of Documentation/process/coding-style.rst +.. include:: ../disclaimer-zh_CN.rst -If you have any comment or update to the content, please post to LKML directly. -However, if you have problem communicating in English you can also ask the -Chinese maintainer for help. Contact the Chinese maintainer, if this -translation is outdated or there is problem with translation. +:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` -Chinese maintainer: Zhang Le <r0bertz@gentoo.org> +.. _cn_codingstyle: ---------------------------------------------------------------------- - -Documentation/process/coding-style.rst çš„ä¸ć–‡çż»čŻ‘ - -如果ćłčŻ„论ć–更新本文的内容，请直接发信ĺ°LKMLă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡äş¤ćµćś‰ĺ›°éšľçš„话， -也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ -维护者:: +译者:: ä¸ć–‡ç‰ç»´ćŠ¤č€…： ĺĽ äą Zhang Le <r0bertz@gentoo.org> ä¸ć–‡ç‰çż»čŻ‘者： ĺĽ äą Zhang Le <r0bertz@gentoo.org> @@ -23,10 +14,6 @@ Documentation/process/coding-style.rst çš„ä¸ć–‡çż»čŻ‘ Li Zefan <lizf@cn.fujitsu.com> Wang Chen <wangchen@cn.fujitsu.com> -以下为ćŁć–‡ - ---------------------------------------------------------------------- - Linux ĺ†…ć ¸ä»Łç éŁŽć Ľ ========================= diff --git a/Documentation/translations/zh_CN/process/development-process.rst b/Documentation/translations/zh_CN/process/development-process.rst new file mode 100644 index 000000000000..30cffe66c075 --- /dev/null +++ b/Documentation/translations/zh_CN/process/development-process.rst @@ -0,0 +1,26 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/development-process.rst <development_process_main>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_development_process_main: + +ĺ†…ć ¸ĺĽ€ĺŹ‘čż‡ç¨‹ćŚ‡ĺŤ— +================ + +内容: + +.. toctree:: + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process + 3.Early-stage + 4.Coding + 5.Posting + 6.Followthrough + 7.AdvancedTopics + 8.Conclusion + +本文档的目的ćŻĺ¸®ĺŠ©ĺĽ€ĺŹ‘äşşĺ‘ďĽĺŹŠĺ…¶ç»Źç†ďĽ‰ä»Ąćś€ĺ°Źçš„挫ćŠć„źä¸ŽĺĽ€ĺŹ‘社区ĺ作。ĺ®čŻ•ĺ›ľč®°ĺ˝•čż™ä¸Şç¤ľĺŚşĺ¦‚何以一种不熟悉Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ďĽć–者实际上ćŻč‡Şç”±č˝Żä»¶ĺĽ€ĺŹ‘）的人可以访问的方式工作。虽然这里有一些技术资料，但这ćŻä¸€ä¸Şéť˘ĺ‘过程的讨论，不需č¦ć·±ĺ…Ąäş†č§Łĺ†…ć ¸çĽ–ç¨‹ĺ°±ĺŹŻä»Ąç†č§Łă€‚ diff --git a/Documentation/translations/zh_CN/email-clients.txt b/Documentation/translations/zh_CN/process/email-clients.rst index ec31d97e8d0e..102023651118 100644 --- a/Documentation/translations/zh_CN/email-clients.txt +++ b/Documentation/translations/zh_CN/process/email-clients.rst @@ -1,33 +1,34 @@ -Chinese translated version of Documentation/process/email-clients.rst +.. _cn_email_clients: -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. +.. include:: ../disclaimer-zh_CN.rst -Chinese maintainer: Harry Wei <harryxiyou@gmail.com> ---------------------------------------------------------------------- -Documentation/process/email-clients.rst çš„ä¸ć–‡çż»čŻ‘ +:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` -如果ćłčŻ„论ć–更新本文的内容，请直接č”çł»ĺŽźć–‡ćˇŁçš„ç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡ -交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 -译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 +译者:: -ä¸ć–‡ç‰ç»´ćŠ¤č€…： č´ľĺ¨ĺ¨ Harry Wei <harryxiyou@gmail.com> -ä¸ć–‡ç‰çż»čŻ‘者： č´ľĺ¨ĺ¨ Harry Wei <harryxiyou@gmail.com> -ä¸ć–‡ç‰ć ˇčŻ‘者： Yinglin Luan <synmyth@gmail.com> - Xiaochen Wang <wangxiaochen0@gmail.com> - yaxinsn <yaxinsn@163.com> - -以下为ćŁć–‡ ---------------------------------------------------------------------- + ä¸ć–‡ç‰ç»´ćŠ¤č€…： č´ľĺ¨ĺ¨ Harry Wei <harryxiyou@gmail.com> + ä¸ć–‡ç‰çż»čŻ‘者： č´ľĺ¨ĺ¨ Harry Wei <harryxiyou@gmail.com> + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + ä¸ć–‡ç‰ć ˇčŻ‘者： Yinglin Luan <synmyth@gmail.com> + Xiaochen Wang <wangxiaochen0@gmail.com> + yaxinsn <yaxinsn@163.com> Linux邮件客ć·ç«Żé…Ťç˝®äżˇćŻ -====================================================================== +======================= + +Git +--- + +现在大多数开发人ĺ‘使用 ``git send-email`` 而不ćŻĺ¸¸č§„的电ĺ邮件客ć·ç«Żă€‚这方面 +的手册非常好。在接收端，维护人ĺ‘使用 ``git am`` ĺŠ č˝˝čˇĄä¸ă€‚ + +ĺ¦‚ćžśä˝ ćŻ ``git`` 新手，那äąćŠŠä˝ 的第一个补ä¸ĺŹ‘é€ç»™ä˝ 自己。将其保ĺ为包ĺ«ć‰€ćś‰ +ć ‡é˘çš„原始文本。čżčˇŚ ``git am raw_email.txt`` ，然ĺŽä˝żç”¨ ``git log`` 查看更 +改日志。如果工作ćŁĺ¸¸ďĽŚĺ†Ťĺ°†čˇĄä¸ĺŹ‘é€ĺ°ç›¸ĺş”的邮件ĺ—表。 + 普通配置 ----------------------------------------------------------------------- +-------- Linuxĺ†…ć ¸čˇĄä¸ćŻé€ščż‡é‚®ä»¶č˘«ćŹäş¤çš„，最好把补ä¸ä˝śä¸şé‚®ä»¶ä˝“的内嵌文本。有些维护者 接收附件，但ćŻé™„ä»¶çš„ĺ†…ĺ®ąć ĽĺĽŹĺş”čŻĄćŻ"text/plain"。然而，附件一č¬ćŻä¸Ťčµžć的， ĺ› ä¸şčż™äĽšä˝żčˇĄä¸çš„引用é¨ĺ†ĺś¨čŻ„论过程ä¸ĺŹçš„ĺľĺ›°éšľă€‚ @@ -56,7 +57,7 @@ Linuxĺ†…ć ¸čˇĄä¸ćŻé€ščż‡é‚®ä»¶č˘«ćŹäş¤çš„，最好把补ä¸ä˝śä¸şé‚®ä»¶ä˝“çš„ 一些邮件客ć·ç«ŻćŹç¤ş ----------------------------------------------------------------------- +------------------ 这里给出一些详细的MUAé…Ťç˝®ćŹç¤şďĽŚĺŹŻä»Ąç”¨äşŽç»™Linuxĺ†…ć ¸ĺŹ‘é€čˇĄä¸ă€‚čż™äş›ĺą¶ä¸Ťć„Źĺ‘łćŻ ć‰€ćś‰çš„č˝Żä»¶ĺŚ…é…Ťç˝®ć€»ç»“ă€‚ @@ -64,8 +65,8 @@ Linuxĺ†…ć ¸čˇĄä¸ćŻé€ščż‡é‚®ä»¶č˘«ćŹäş¤çš„，最好把补ä¸ä˝śä¸şé‚®ä»¶ä˝“çš„ TUI = 以文本为基础的用ć·ćŽĄĺŹŁ GUI = 图形界面用ć·ćŽĄĺŹŁ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Alpine (TUI) +~~~~~~~~~~~~ 配置选项： 在"Sending Preferences"é¨ĺ†ďĽš @@ -76,8 +77,8 @@ Alpine (TUI) ĺ˝“ĺ†™é‚®ä»¶ć—¶ďĽŚĺ…‰ć ‡ĺş”čŻĄć”ľĺś¨čˇĄä¸äĽšĺ‡şçŽ°çš„地方，然ĺŽćŚ‰ä¸‹CTRL-R组ĺ键，使指定的 补ä¸ć–‡ä»¶ĺµŚĺ…Ąĺ°é‚®ä»¶ä¸ă€‚ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Evolution (GUI) +~~~~~~~~~~~~~~~ 一些开发者ć功的使用ĺ®ĺŹ‘é€čˇĄä¸ @@ -89,8 +90,8 @@ Evolution (GUI) ä˝ čżĺŹŻä»Ą"diff -Nru old.c new.c | xclip"，选择Preformat，然ĺŽä˝żç”¨ä¸é—´é”®čż›čˇŚç˛ĺ¸–。 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Kmail (GUI) +~~~~~~~~~~~ 一些开发者ć功的使用ĺ®ĺŹ‘é€čˇĄä¸ă€‚ @@ -118,13 +119,13 @@ display"ďĽŚčż™ć ·ĺ†…ĺµŚé™„ä»¶ć›´ĺ®ąć“让读者看ĺ°ă€‚ 并且希望这将会被处ç†ă€‚邮件ćŻä»ĄĺŹŞé’对ćźä¸Şç”¨ć·ĺŹŻčŻ»ĺ†™çš„ćťé™č˘«äżťĺçš„ďĽŚć‰€ä»Ąĺ¦‚ćžśä˝ ćłćŠŠé‚®ä»¶ĺ¤Ťĺ¶ĺ°ĺ…¶ä»–地方， ä˝ ä¸Ťĺľ—ä¸ŤćŠŠä»–ä»¬çš„ćťé™ć”ąä¸şç»„ć–者整体可读。 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Lotus Notes (GUI) +~~~~~~~~~~~~~~~~~ 不č¦ä˝żç”¨ĺ®ă€‚ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Mutt (TUI) +~~~~~~~~~~ ĺľĺ¤šLinux开发人ĺ‘使用mutt客ć·ç«ŻďĽŚć‰€ä»ĄčŻćŽĺ®č‚Żĺ®šĺ·Ąä˝śçš„非常漂亮。 @@ -142,12 +143,49 @@ Muttä¸Ťč‡Şĺ¸¦çĽ–čľ‘ĺ™¨ďĽŚć‰€ä»Ąä¸Ťç®ˇä˝ ä˝żç”¨ä»€äąçĽ–辑器é˝ä¸Ťĺş”该带有č 如果ćłč¦ćŠŠčˇĄä¸ä˝śä¸şĺ†…嵌文本。 (a)ttach工作的ĺľĺĄ˝ďĽŚä¸Ťĺ¸¦ćś‰"set paste"。 +ä˝ ĺŹŻä»Ąé€ščż‡ ``git format-patch`` 生ć补ä¸ďĽŚç„¶ĺŽç”¨ Mutt发é€ĺ®ä»¬:: + + $ mutt -H 0001-some-bug-fix.patch + 配置选项： ĺ®ĺş”该以é»č®¤č®ľç˝®çš„形式工作。 然而，把"send_charset"设置为"us-ascii::utf-8"äąźćŻä¸€ä¸Şä¸Ťé”™çš„主意。 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Mutt ćŻé«ĺş¦ĺŹŻé…Ťç˝®çš„。 这里ćŻä¸Şä˝żç”¨mutt通过 Gmail 发é€çš„补ä¸çš„最小配置:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'yourusername@gmail.com' + set imap_pass = 'yourpassword' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Require encrypted connection + + # ================ Composition ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # See the headers when editing + set charset = UTF-8 # value of $LANG; also fallback for send_charset + # Sender, email address, and sign-off line must match + unset use_domain # because joe@localhost is just embarrassing + set realname = "YOUR NAME" + set from = "username@gmail.com" + set use_from = yes + +Mutt文档ĺ«ćś‰ć›´ĺ¤šäżˇćŻ: + + http://dev.mutt.org/trac/wiki/UseCases/Gmail + + http://dev.mutt.org/doc/manual.html + Pine (TUI) +~~~~~~~~~~ Pinečż‡ĺŽ»ćś‰ä¸€äş›ç©şć Ľĺ 减问é˘ďĽŚä˝†ćŻčż™äş›çŽ°ĺś¨ĺş”该é˝č˘«äż®ĺ¤Ťäş†ă€‚ @@ -158,8 +196,8 @@ Pinečż‡ĺŽ»ćś‰ä¸€äş›ç©şć Ľĺ 减问é˘ďĽŚä˝†ćŻčż™äş›çŽ°ĺś¨ĺş”该é˝č˘«äż®ĺ¤Ťäş†ă - "no-strip-whitespace-before-send"选项也ćŻéś€č¦çš„。 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sylpheed (GUI) +~~~~~~~~~~~~~~ - 内嵌文本可以ĺľĺĄ˝çš„工作ďĽć–者使用附件）。 - ĺ…许使用外é¨çš„编辑器。 @@ -168,8 +206,8 @@ Sylpheed (GUI) - 在组ć窗口ä¸ćś‰ä¸€ä¸Şĺľćś‰ç”¨çš„ruler bar。 - 给地址本ä¸ć·»ĺŠ 地址就不会ćŁçˇ®çš„了解ćľç¤şĺŤă€‚ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Thunderbird (GUI) +~~~~~~~~~~~~~~~~~ é»č®¤ć…况下，thunderbirdĺľĺ®ąć“损坏文本，但ćŻčżćś‰ä¸€äş›ć–ąćł•ĺŹŻä»ĄĺĽşĺ¶ĺ®ĺŹĺľ—更好。 @@ -191,13 +229,13 @@ Thunderbird (GUI) $EDITOR来读取ć–者ĺ并补ä¸ĺ°ć–‡ćś¬ä¸ă€‚č¦ĺ®žçŽ°ĺ®ďĽŚĺŹŻä»Ąä¸‹č˝˝ĺą¶ä¸”安装这个扩展，然ĺŽć·»ĺŠ 一个使用ĺ®çš„ 按键View->Toolbars->Customize...最ĺŽĺ˝“ä˝ äą¦ĺ†™äżˇćŻçš„时候仅仅点击ĺ®ĺ°±ĺŹŻä»Ąäş†ă€‚ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TkRat (GUI) +~~~~~~~~~~~ 可以使用ĺ®ă€‚使用"Insert file..."ć–者外é¨çš„编辑器。 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Gmail (Web GUI) +~~~~~~~~~~~~~~~ 不č¦ä˝żç”¨ĺ®ĺŹ‘é€čˇĄä¸ă€‚ diff --git a/Documentation/translations/zh_CN/HOWTO b/Documentation/translations/zh_CN/process/howto.rst index 7a00a8a4eb15..5b671178b17b 100644 --- a/Documentation/translations/zh_CN/HOWTO +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -1,32 +1,22 @@ -Chinese translated version of Documentation/process/howto.rst +.. _cn_process_howto: -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. +.. include:: ../disclaimer-zh_CN.rst -Maintainer: Greg Kroah-Hartman <greg@kroah.com> -Chinese maintainer: Li Yang <leoli@freescale.com> ---------------------------------------------------------------------- -Documentation/process/howto.rst çš„ä¸ć–‡çż»čŻ‘ +:Original: :ref:`Documentation/process/howto.rst <process_howto>` -如果ćłčŻ„论ć–更新本文的内容，请直接č”çł»ĺŽźć–‡ćˇŁçš„ç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡ -交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 -译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 +译者:: -英文ç‰ç»´ćŠ¤č€…： Greg Kroah-Hartman <greg@kroah.com> -ä¸ć–‡ç‰ç»´ćŠ¤č€…： ćťŽéł Li Yang <leoli@freescale.com> -ä¸ć–‡ç‰çż»čŻ‘者： ćťŽéł Li Yang <leoli@freescale.com> -ä¸ć–‡ç‰ć ˇčŻ‘者： 钟宇 TripleX Chung <xxx.phy@gmail.com> - é™ç¦ Maggie Chen <chenqi@beyondsoft.com> - çŽ‹čŞ Wang Cong <xiyou.wangcong@gmail.com> - -以下为ćŁć–‡ ---------------------------------------------------------------------- + 英文ç‰ç»´ćŠ¤č€…： Greg Kroah-Hartman <greg@kroah.com> + ä¸ć–‡ç‰ç»´ćŠ¤č€…： ćťŽéł Li Yang <leoyang.li@nxp.com> + ä¸ć–‡ç‰çż»čŻ‘者： ćťŽéł Li Yang <leoyang.li@nxp.com> + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + ä¸ć–‡ç‰ć ˇčŻ‘者: + 钟宇 TripleX Chung <xxx.phy@gmail.com> + é™ç¦ Maggie Chen <chenqi@beyondsoft.com> + çŽ‹čŞ Wang Cong <xiyou.wangcong@gmail.com> 如何参与Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ ---------------------- +===================== čż™ćŻä¸€çŻ‡ĺ°†ĺ¦‚何参与Linuxĺ†…ć ¸ĺĽ€ĺŹ‘çš„ç›¸ĺ…łé—®é˘ä¸€ç˝‘打尽的ç»ćžç§ç¬ă€‚ĺ®ĺ°†ćŚ‡ĺŻĽä˝ ć为一ĺŤLinuxĺ†…ć ¸ĺĽ€ĺŹ‘č€…ďĽŚĺą¶ä¸”ĺ¦äĽšĺ¦‚何ĺŚLinuxĺ†…ć ¸ĺĽ€ĺŹ‘ç¤ľĺŚşĺ作。ĺ®ĺ°˝ĺŹŻč˝ä¸Ť @@ -47,6 +37,7 @@ Linuxĺ†…ć ¸ĺ¤§é¨ĺ†ćŻç”±CčŻč¨€ĺ†™ć的，一些体系结构相关的代ç ç” ĺŹ‚ä¸Žĺ†…ć ¸ĺĽ€ĺŹ‘ďĽŚä˝ ĺż…éˇ»ç˛ľé€šCčŻč¨€ă€‚é™¤éťžä˝ ćłä¸şćźä¸Şćž¶ćž„开发底层代ç ，ĺ¦ĺ™ä˝ 并 不需č¦äş†č§ŁďĽä»»ä˝•ä˝“系结构的）汇编čŻč¨€ă€‚下面ĺ—举的书籍虽然不č˝ć›żä»Łć‰Žĺ®žçš„C čŻč¨€ć•™č‚˛ĺ’Śĺ¤šĺą´çš„开发经验，但如果需č¦çš„话，ĺšä¸şĺŹ‚č€čżćŻä¸Ťé”™çš„： + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] 《C程序设计čŻč¨€ďĽç¬¬2ç‰Â·ć–°ç‰ďĽ‰ă€‹ďĽĺľĺ®ťć–‡ 李志 译）[机械工业出ç‰ç¤ľ] - "Practical C Programming" by Steve Oualline [O'Reilly] @@ -71,9 +62,11 @@ Linuxĺ†…ć ¸ä˝żç”¨GNU Cĺ’ŚGNU工具链开发。虽然ĺ®éµĺľŞISO C89ć ‡ĺ‡†ďĽŚä˝† -------- Linuxĺ†…ć ¸ćşä»Łç é˝ćŻĺś¨GPLďĽé€šç”¨ĺ…¬ĺ…±č®¸ĺŹŻčŻďĽ‰çš„保护下发ĺ¸çš„。č¦äş†č§Łčż™ç§Ťč®¸ĺŹŻ -的细节请查看ćşä»Łç 主目录下的COPYINGć–‡ä»¶ă€‚ĺ¦‚ćžśä˝ ĺŻąĺ®čżćś‰ć›´ć·±ĺ…Ąé—®é˘čŻ·č”çł» -ĺľ‹ĺ¸ďĽŚč€Śä¸Ťč¦ĺś¨Linuxĺ†…ć ¸é‚®ä»¶ç»„ä¸ŠćŹé—®ă€‚ĺ› ä¸şé‚®ä»¶ç»„é‡Śçš„äşşĺą¶ä¸ŤćŻĺľ‹ĺ¸ďĽŚä¸Ťč¦ćśź -望他们的话有法律ć•ĺŠ›ă€‚ +的细节请查看ćşä»Łç 主目录下的COPYING文件。Linuxĺ†…ć ¸č®¸ĺŹŻĺ‡†ĺ™ĺ’Śĺ¦‚何使用 +`SPDX <https://spdx.org/>` ć ‡ĺż—ç¬¦čŻ´ćŽĺś¨čż™ä¸Şć–‡ä»¶ä¸ +:ref:`Documentation/translations/zh_CN/process/license-rules.rst <cn_kernel_licensing>` +ĺ¦‚ćžśä˝ ĺŻąĺ®čżćś‰ć›´ć·±ĺ…Ąé—®é˘čŻ·č”系律ĺ¸ďĽŚč€Śä¸Ťč¦ĺś¨Linuxĺ†…ć ¸é‚®ä»¶ç»„ä¸ŠćŹé—®ă€‚ĺ› ä¸ş +邮件组里的人并不ćŻĺľ‹ĺ¸ďĽŚä¸Ťč¦ćśźćś›ä»–们的话有法律ć•ĺŠ›ă€‚ 对于GPL的常č§é—®é˘ĺ’Śč§Łç”，请访问以下链接： http://www.gnu.org/licenses/gpl-faq.html @@ -89,65 +82,75 @@ Linuxĺ†…ć ¸ä»Łç ä¸ĺŚ…ĺ«ćś‰ĺ¤§é‡Źçš„文档。这些文档对于ĺ¦äą 如何与 的维护者解释这些ĺŹĺŚ–。 以下ćŻĺ†…ć ¸ä»Łç ä¸éś€č¦é…读的文档： - README + :ref:`Documentation/admin-guide/README.rst <readme>` 文件简č¦ä»‹ç»Ťäş†Linuxĺ†…ć ¸çš„čŚć™ŻďĽŚĺą¶ä¸”ćŹŹčż°äş†ĺ¦‚ä˝•é…Ťç˝®ĺ’ŚçĽ–čŻ‘ĺ†…ć ¸ă€‚ĺ†…ć ¸çš„ 新用ć·ĺş”该从这里开始。 - Documentation/process/changes.rst + + :ref:`Documentation/process/changes.rst <changes>` ć–‡ä»¶ç»™ĺ‡şäş†ç”¨ćťĄçĽ–čŻ‘ĺ’Śä˝żç”¨ĺ†…ć ¸ć‰€éś€č¦çš„最小软件包ĺ—表。 - Documentation/process/coding-style.rst + :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` 描述Linuxĺ†…ć ¸çš„ä»Łç éŁŽć Ľĺ’Śç†ç”±ă€‚所有新代ç 需č¦éµĺ®čż™çŻ‡ć–‡ćˇŁä¸ĺ®šäą‰çš„规 čŚă€‚大多数维护者只会接收符ĺ规定的补ä¸ďĽŚĺľĺ¤šäşşäąźĺŹŞäĽšĺ¸®ĺż™ćŁ€ćźĄç¬¦ĺéŁŽć Ľ 的代ç 。 - Documentation/process/submitting-patches.rst - Documentation/process/submitting-drivers.rst + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` + :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + 这两份文档ćŽçˇ®ćŹŹčż°ĺ¦‚何ĺ›ĺ»şĺ’ŚĺŹ‘é€čˇĄä¸ďĽŚĺ…¶ä¸ĺŚ…括ďĽä˝†ä¸Ťä»…é™äşŽ)： - 邮件内容 - é‚®ä»¶ć ĽĺĽŹ - 选择收件人 + éµĺ®čż™äş›č§„定并不č˝äżťčŻćŹäş¤ć功ďĽĺ› 为所有补ä¸éś€č¦é€ščż‡ä¸Ąć Ľçš„ĺ†…ĺ®ąĺ’ŚéŁŽć Ľ 审查），但ćŻĺż˝č§†ä»–ä»¬ĺ‡ äąŽĺ°±ć„Źĺ‘łçť€ĺ¤±č´Ąă€‚ 其他关于如何ćŁçˇ®ĺś°ç”źć补ä¸çš„äĽç§€ć–‡ćˇŁĺŚ…括： "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html - Documentation/process/stable-api-nonsense.rst + :ref:`Documentation/translations/zh_CN/process/stable-api-nonsense.rst <cn_stable_api_nonsense>` 论čŻĺ†…ć ¸ä¸şä»€äąç‰ąć„Źä¸ŤĺŚ…ć‹¬ç¨łĺ®šçš„ĺ†…ć ¸ĺ†…é¨API，也就ćŻčŻ´ä¸ŤĺŚ…括ĺŹčż™ć ·çš„特 性： + - ĺ系统ä¸é—´ĺ±‚ďĽä¸şäş†ĺ…Ľĺ®ąć€§ďĽźďĽ‰ - 在不ĺŚć“Ťä˝śçł»ç»źé—´ć“于移植的驱动程序 - 减缓ďĽç”šč‡łé»ć˘ďĽ‰ĺ†…ć ¸ä»Łç 的快速ĺŹĺŚ– + 这篇文档对于ç†č§ŁLinux的开发哲ĺ¦č‡łĺ…łé‡Ťč¦ă€‚对于将开发平台从其他操作系 统转移ĺ°Linux的人来说也ĺľé‡Ťč¦ă€‚ - Documentation/admin-guide/security-bugs.rst + :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` ĺ¦‚ćžśä˝ č®¤ä¸şč‡Şĺ·±ĺŹ‘çŽ°äş†Linuxĺ†…ć ¸çš„ĺ®‰ĺ…¨ć€§é—®é˘ďĽŚčŻ·ć ąćŤ®čż™çŻ‡ć–‡ćˇŁä¸çš„ćĄéŞ¤ćťĄ ćŹé†’ĺ…¶ä»–ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ĺą¶ĺ¸®ĺŠ©č§Łĺ†łčż™ä¸Şé—®é˘ă€‚ - Documentation/process/management-style.rst + :ref:`Documentation/translations/zh_CN/process/management-style.rst <cn_managementstyle>` + ćŹŹčż°ĺ†…ć ¸ç»´ćŠ¤č€…çš„ĺ·Ąä˝ść–ąćł•ĺŹŠĺ…¶ĺ…±ćś‰ç‰ąç‚ąă€‚čż™ĺŻąäşŽĺšĺšćŽĄč§¦ĺ†…ć ¸ĺĽ€ĺŹ‘ďĽć–者对 ĺ®ć„źĺ°ĺĄ˝ĺĄ‡ďĽ‰çš„人来说ĺľé‡Ťč¦ďĽŚĺ› 为ĺ®č§Łé‡Šäş†ĺľĺ¤šĺŻąäşŽĺ†…ć ¸ç»´ćŠ¤č€…ç‹¬ç‰ąčˇŚä¸şçš„ ć™®éŤčŻŻč§Łä¸Žčż·ć‘。 - Documentation/process/stable-kernel-rules.rst + :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` 解释了稳定ç‰ĺ†…ć ¸ĺŹ‘ĺ¸çš„规ĺ™ďĽŚä»ĄĺŹŠĺ¦‚何将改动放入这些ç‰ćś¬çš„ćĄéŞ¤ă€‚ - 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/目录下。在内 ć ¸ćşç 的主目录ä¸ä˝żç”¨ä»Ąä¸‹ä¸ŤĺŚĺ‘˝ä»¤ĺ°†äĽšĺ†ĺ«ç”źćPDFă€Postscriptă€HTML和手册 -页ç‰ä¸ŤĺŚć ĽĺĽŹçš„文档： +页ç‰ä¸ŤĺŚć ĽĺĽŹçš„文档:: + make pdfdocs make htmldocs @@ -155,7 +158,9 @@ Linuxĺ†…ć ¸ä»Łç ä¸ĺŚ…ĺ«ćś‰ĺ¤§é‡Źçš„文档。这些文档对于ĺ¦äą 如何与 如何ćä¸şĺ†…ć ¸ĺĽ€ĺŹ‘č€… ------------------ ĺ¦‚ćžśä˝ ĺŻąLinuxĺ†…ć ¸ĺĽ€ĺŹ‘ä¸€ć— ć‰€çźĄďĽŚä˝ ĺş”čŻĄč®żé—®â€śLinuxĺ†…ć ¸ć–°ć‰‹â€ťč®ˇĺ’： + http://kernelnewbies.org + ĺ®ć‹Ąćś‰ä¸€ä¸ŞĺŹŻä»Ąé—®ĺ„ç§Ťćś€ĺźşćś¬çš„ĺ†…ć ¸ĺĽ€ĺŹ‘é—®é˘çš„邮件ĺ—表ďĽĺś¨ćŹé—®äą‹ĺ‰Ťä¸€ĺ®šč¦č®°ĺľ— 查找已往的邮件，确认ćŻĺ¦ćś‰äşşĺ·˛ç»Źĺ›žç”过相ĺŚçš„é—®é˘ďĽ‰ă€‚ĺ®čżć‹Ąćś‰ä¸€ä¸ŞĺŹŻä»ĄčŽ·ĺľ— 实时反é¦çš„IRCčŠĺ¤©é˘‘é“，以及大量对于ĺ¦äą Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ç›¸ĺ˝“ćś‰ĺ¸®ĺŠ©çš„ć–‡ćˇŁă€‚ @@ -166,23 +171,21 @@ Linuxĺ†…ć ¸ä»Łç ä¸ĺŚ…ĺ«ćś‰ĺ¤§é‡Źçš„文档。这些文档对于ĺ¦äą 如何与 ĺ¦‚ćžśä˝ ćłĺŠ ĺ…Ąĺ†…ć ¸ĺĽ€ĺŹ‘ç¤ľĺŚşĺą¶ĺŤŹĺŠ©ĺ®Ść一些任务，却找不ĺ°ä»Žĺ“Şé‡ŚĺĽ€ĺ§‹ďĽŚĺŹŻä»Ąč®żé—® “Linuxĺ†…ć ¸ćżç®ˇĺ‘”计ĺ’： + http://kernelnewbies.org/KernelJanitors + čż™ćŻćžä˝łçš„起点。ĺ®ćŹäľ›ä¸€ä¸Şç›¸ĺŻąç®€ĺŤ•çš„任务ĺ—表，ĺ—ĺ‡şĺ†…ć ¸ä»Łç ä¸éś€č¦č˘«é‡Ťć–° ć•´ç†ć–者改ćŁçš„地方。通过和负责这个计ĺ’的开发者们一ĺŚĺ·Ąä˝śďĽŚä˝ 会ĺ¦ĺ°ĺ°†čˇĄä¸ 集ćčż›ĺ†…ć ¸çš„ĺźşćś¬ĺŽźç†ă€‚如果čżć˛ˇćś‰ĺ†łĺ®šä¸‹ä¸€ćĄč¦ĺšä»€äąçš„čŻťďĽŚä˝ čżĺŹŻč˝äĽšĺľ—ĺ°ć–ą ĺ‘性的指点。 -ĺ¦‚ćžśä˝ ĺ·˛ç»Źćś‰ä¸€äş›çŽ°ć的代ç ćłč¦ć”ľĺ°ĺ†…ć ¸ä¸ďĽŚä˝†ćŻéś€č¦ä¸€äş›ĺ¸®ĺŠ©ćťĄä˝żĺ®ä»¬ć‹Ąćś‰ćŁ -çˇ®çš„ć ĽĺĽŹă€‚čŻ·č®żé—®â€śĺ†…ć ¸ĺŻĽĺ¸â€ťč®ˇĺ’。这个计ĺ’ĺ°±ćŻç”¨ćťĄĺ¸®ĺŠ©ä˝ 完ćčż™ä¸Şç›®ć ‡çš„ă€‚ĺ® -ćŻä¸€ä¸Şé‚®ä»¶ĺ—表，地址如下： - http://selenic.com/mailman/listinfo/kernel-mentors - 在真ćŁĺŠ¨ć‰‹äż®ć”ąĺ†…ć ¸ä»Łç 之前，ç†č§Łč¦äż®ć”ąçš„代ç 如何čżä˝śćŻĺż…需的。č¦čľľĺ°čż™ä¸Ş 目的，没什äąĺŠžćł•ćŻ”直接读代ç 更有ć•äş†ďĽĺ¤§ĺ¤šć•°čŠ±ć‹›é˝äĽšćś‰ç›¸ĺş”的注释），而且 一些特ĺ¶çš„ĺ·Ąĺ…·čżĺŹŻä»ĄćŹäľ›ĺ¸®ĺŠ©ă€‚例如，“Linux代ç 交叉引用”项目就ćŻä¸€ä¸Şĺ€Ľĺľ— 特ĺ«ćŽ¨čŤçš„帮助工具，ĺ®ĺ°†ćşä»Łç ćľç¤şĺś¨ćś‰çĽ–目和索引的网页上。其ä¸ä¸€ä¸Şć›´ć–°ĺŹŠ ć—¶çš„ĺ†…ć ¸ćşç 库，可以通过以下地址访问： - http://sosdg.org/~coywolf/lxr/ + + https://elixir.bootlin.com/ 开发ćµç¨‹ @@ -190,22 +193,23 @@ Linuxĺ†…ć ¸ä»Łç ä¸ĺŚ…ĺ«ćś‰ĺ¤§é‡Źçš„文档。这些文档对于ĺ¦äą 如何与 目前Linuxĺ†…ć ¸ĺĽ€ĺŹ‘ćµç¨‹ĺŚ…ć‹¬ĺ‡ ä¸Şâ€śä¸»ĺ†…ć ¸ĺ†ć”Żâ€ťĺ’Śĺľĺ¤šĺçł»ç»źç›¸ĺ…łçš„ĺ†…ć ¸ĺ†ć”Żă€‚čż™ äş›ĺ†ć”ŻĺŚ…括： - - 2.6.xä¸»ĺ†…ć ¸ćşç ć ‘ - - 2.6.x.y -stableĺ†…ć ¸ćşç ć ‘ - - 2.6.x -mmĺ†…ć ¸čˇĄä¸é›† - - ĺçł»ç»źç›¸ĺ…łçš„ĺ†…ć ¸ćşç ć ‘ĺ’ŚčˇĄä¸é›† + - Linus çš„ĺ†…ć ¸ćşç ć ‘ + - 多个主č¦ç‰ćś¬çš„稳定ç‰ĺ†…ć ¸ć ‘ + - ĺçł»ç»źç›¸ĺ…łçš„ĺ†…ć ¸ć ‘ + - linux-next 集ććµ‹čŻ•ć ‘ + + +ä¸»çşżć ‘ +------ +ä¸»çşżć ‘ćŻç”±Linus Torvalds ç»´ćŠ¤çš„ă€‚ä˝ ĺŹŻä»Ąĺś¨https://kernel.org 网站ć–者代ç +ĺş“ä¸ä¸‹ć‰ľĺ°ĺ®ă€‚ĺ®çš„开发éµĺľŞä»Ąä¸‹ćĄéŞ¤ďĽš -2.6.xĺ†…ć ¸ä¸»ćşç ć ‘ ------------------ -2.6.xĺ†…ć ¸ćŻç”±Linus TorvaldsďĽLinuxçš„ĺ›é€ č€…ďĽ‰äş˛č‡Şç»´ćŠ¤çš„ă€‚ä˝ ĺŹŻä»Ąĺś¨ -kernel.org网站的pub/linux/kernel/v2.6/目录下找ĺ°ĺ®ă€‚ĺ®çš„开发éµĺľŞä»Ąä¸‹ćĄ -骤： - 每当一个新ç‰ćś¬çš„ĺ†…ć ¸č˘«ĺŹ‘ĺ¸ďĽŚä¸şćśźä¸¤ĺ‘¨çš„集ć窗口将被打开。在这段时间里 维护者可以ĺ‘LinusćŹäş¤ĺ¤§ć®µçš„修改，通常这些修改已经被放ĺ°-mmĺ†…ć ¸ä¸ĺ‡ 个 ćźćśźäş†ă€‚ćŹäş¤ĺ¤§é‡Źäż®ć”ąçš„首选方式ćŻä˝żç”¨gitĺ·Ąĺ…·ďĽĺ†…ć ¸çš„ä»Łç ç‰ćś¬ç®ˇç†ĺ·Ąĺ…· - ，更多的信ćŻĺŹŻä»Ąĺś¨http://git-scm.com/获取），不过使用普通补ä¸äąźćŻĺŹŻä»Ą - 的。 + ，更多的信ćŻĺŹŻä»Ąĺś¨ http://git-scm.com/ 获取），不过使用普通补ä¸äąźćŻ + 可以的。 - 两个ćźćśźä»ĄĺŽ-rc1ç‰ćś¬ĺ†…ć ¸ĺŹ‘ĺ¸ă€‚äą‹ĺŽĺŹŞćś‰ä¸ŤĺŚ…ĺ«ĺŹŻč˝ĺ˝±ĺ“Ťć•´ä¸Şĺ†…ć ¸ç¨łĺ®šć€§çš„ 新功č˝çš„补ä¸ć‰ŤĺŹŻč˝č˘«ćŽĄĺŹ—。请注意一个全新的驱动程序ďĽć–者文件系统）有 可č˝ĺś¨-rc1ĺŽč˘«ćŽĄĺŹ—ćŻĺ› ä¸şčż™ć ·çš„äż®ć”ąĺ®Śĺ…¨ç‹¬ç«‹ďĽŚä¸ŤäĽšĺ˝±ĺ“Ťĺ…¶ä»–çš„ä»Łç ，所以 @@ -220,106 +224,61 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找ĺ°ĺ®ă€‚ĺ®çš„开发éµĺľŞ “没有人知é“ć–°ĺ†…ć ¸ä˝•ć—¶äĽšč˘«ĺŹ‘ĺ¸ďĽŚĺ› 为发ĺ¸ćŻć ąćŤ®ĺ·˛çźĄbugçš„ć…况来决定 的，而不ćŻć ąćŤ®ä¸€ä¸Şäş‹ĺ…ĺ¶ĺ®šĺĄ˝çš„时间表。” +ĺçł»ç»źç‰ąĺ®šć ‘ +------------ -2.6.x.y -stableďĽç¨łĺ®šç‰ďĽ‰ĺ†…ć ¸ćşç ć ‘ ------------------------------------ -ç”±4个数ĺ—组ćçš„ĺ†…ć ¸ç‰ćś¬ĺŹ·čŻ´ćŽć¤ĺ†…ć ¸ćŻ-stableç‰ćś¬ă€‚ĺ®ä»¬ĺŚ…ĺ«ĺźşäşŽ2.6.xç‰ćś¬ -ĺ†…ć ¸çš„ç›¸ĺŻąčľĺ°Źä¸”至关重č¦çš„修补，这些修补é’对安全性问é˘ć–č€…ä¸Ąé‡Ťçš„ĺ†…ć ¸é€€ćĄă€‚ - -这种ç‰ćś¬çš„ĺ†…ć ¸é€‚ç”¨äşŽé‚Łäş›ćśźćś›čŽ·ĺľ—ćś€ć–°çš„ç¨łĺ®šç‰ĺ†…ć ¸ĺą¶ä¸”ä¸ŤćłĺŹ‚与测试开发ç‰ć– -者实验ç‰çš„用ć·ă€‚ - -如果没有2.6.x.yç‰ćś¬ĺ†…ć ¸ĺ在，那äąćś€ć–°çš„2.6.xç‰ćś¬ĺ†…ć ¸ĺ°±ç›¸ĺ˝“äşŽćŻĺ˝“前的稳定 -ç‰ĺ†…ć ¸ă€‚ - -2.6.x.yç‰ćś¬ç”±â€śç¨łĺ®šç‰â€ťĺ°Źç»„ďĽé‚®ä»¶ĺś°ĺť€<stable@vger.kernel.org>）维护，一č¬éš”周发 -ĺ¸ć–°ç‰ćś¬ă€‚ - -ĺ†…ć ¸ćşç ä¸çš„Documentation/process/stable-kernel-rules.rst文件具体描述了可被稳定 -ç‰ĺ†…ć ¸ćŽĄĺŹ—çš„äż®ć”ąç±»ĺž‹ä»ĄĺŹŠĺŹ‘ĺ¸çš„ćµç¨‹ă€‚ +ĺ„ç§Ťĺ†…ć ¸ĺçł»ç»źçš„ç»´ćŠ¤č€…â€”â€”ä»ĄĺŹŠč®¸ĺ¤šĺ†…ć ¸ĺ系统开发人ĺ‘——在ćşä»Łç ĺş“ä¸ĺ…¬ĺĽ€äş†ä»–们 +当前的开发状ć€ă€‚čż™ć ·ďĽŚĺ…¶ä»–äşşĺ°±ĺŹŻä»Ąçś‹ĺ°ĺ†…ć ¸çš„ä¸ŤĺŚĺŚşĺźźĺŹ‘生了什äąă€‚在开发速度 +ĺľĺż«çš„领域，可č˝äĽšč¦ć±‚开发人ĺ‘ĺ°†ćŹäş¤çš„ĺ†…ĺ®ąĺ»şç«‹ĺś¨čż™ć ·çš„ĺçł»ç»źĺ†…ć ¸ć ‘ä¸ŠďĽŚčż™ć · +ĺ°±éżĺ…Ťäş†ćŹäş¤ä¸Žĺ…¶ä»–已经进行的工作之间的冲çŞă€‚ +这些ĺ储库ä¸çš„大多数é˝ćŻGitć ‘ďĽŚä˝†ćŻäąźćś‰ĺ…¶ä»–çš„scm在使用，ć–者补ä¸éźĺ—č˘«ĺŹ‘ĺ¸ +为Quiltçł»ĺ—。这些ĺ系统ĺ储库的地址ĺ—在MAINTAINERS文件ä¸ă€‚ĺ…¶ä¸č®¸ĺ¤šĺŹŻä»Ąĺś¨ +https://git.kernel.org/上浏č§ă€‚ -2.6.x -mm补ä¸é›† ---------------- -čż™ćŻç”±Andrew Mortonç»´ćŠ¤çš„čŻ•éŞŚć€§ĺ†…ć ¸čˇĄä¸é›†ă€‚Andrew将所有ĺçł»ç»źçš„ĺ†…ć ¸ćşç -和补ä¸ć‹Ľĺ‡‘ĺ°ä¸€čµ·ďĽŚĺą¶ä¸”ĺŠ ĺ…Ąäş†ĺ¤§é‡Źä»Žlinux-kernel邮件ĺ—表ä¸é‡‡é›†çš„补ä¸ă€‚这个 -ćşç ć ‘ćŻć–°ĺŠźč˝ĺ’ŚčˇĄä¸çš„试炼场。当补ä¸ĺś¨-mm补ä¸é›†é‡ŚčŻćŽäş†ĺ…¶ä»·ĺ€Ľä»ĄĺŽAndrew -ć–者相应ĺ系统的维护者会将补ä¸ĺŹ‘ç»™Linus以便集ćčż›ä¸»ĺ†…ć ¸ćşç ć ‘ă€‚ +在将一个建议的补ä¸ćŹäş¤ĺ°čż™ć ·çš„ĺçł»ç»źć ‘äą‹ĺ‰ŤďĽŚéś€č¦ĺŻąĺ®čż›čˇŚĺ®ˇćźĄďĽŚĺ®ˇćźĄä¸»č¦ĺŹ‘生 +在邮件ĺ—表上ďĽčŻ·ĺŹ‚č§ä¸‹éť˘ç›¸ĺş”çš„é¨ĺ†ďĽ‰ă€‚ĺŻąäşŽĺ‡ ä¸Şĺ†…ć ¸ĺ系统，这个审查过程ćŻé€š +过工具补ä¸č·źč¸Şçš„。PatchworkćŹäľ›äş†ä¸€ä¸ŞWeb界面，ćľç¤şčˇĄä¸ĺŹ‘ĺ¸ă€ĺŻąčˇĄä¸çš„任何评 +论ć–修订，维护人ĺ‘可以将补ä¸ć ‡č®°ä¸şćŁĺś¨ĺ®ˇćźĄă€ćŽĄĺŹ—ć–拒绝。大多数补ä¸ç˝‘ç«™é˝ĺ— +在 https://patchwork.kernel.org/ -在将所有新补ä¸ĺŹ‘ç»™Linus以集ćĺ°ä¸»ĺ†…ć ¸ćşç ć ‘äą‹ĺ‰ŤďĽŚć‘们非常鼓励ĺ…把这些补 -ä¸ć”ľĺś¨-mmç‰ĺ†…ć ¸ćşç ć ‘ä¸čż›čˇŚćµ‹čŻ•ă€‚ - -čż™äş›ĺ†…ć ¸ç‰ćś¬ä¸Ťé€‚ĺ在需č¦ç¨łĺ®ščżčˇŚçš„系统上čżčˇŚďĽŚĺ› 为čżčˇŚĺ®ä»¬ćŻ”čżčˇŚä»»ä˝•ĺ…¶ä»– -ĺ†…ć ¸ĺ†ć”Żé˝ć›´ĺ…·ćś‰éŁŽé™©ă€‚ - -ĺ¦‚ćžśä˝ ćłä¸şĺ†…ć ¸ĺĽ€ĺŹ‘čż›ç¨‹ćŹäľ›ĺ¸®ĺŠ©ďĽŚčŻ·ĺ°ťčŻ•ĺą¶ä˝żç”¨čż™äş›ĺ†…ć ¸ç‰ćś¬ďĽŚĺą¶ĺś¨ -linux-kernel邮件ĺ—表ä¸ćŹäľ›ĺŹŤé¦ďĽŚĺ‘ŠčŻ‰ĺ¤§ĺ®¶ä˝ é‡ĺ°äş†é—®é˘čżćŻä¸€ĺ‡ćŁĺ¸¸ă€‚ - -通常-mmç‰čˇĄä¸é›†ä¸Ťĺ…‰ĺŚ…括这些额外的试验性补ä¸ďĽŚčżĺŚ…括发ĺ¸ć—¶-gitç‰ä¸»ćşç ć ‘ -ä¸çš„改动。 - --mmç‰ĺ†…ć ¸ć˛ˇćś‰ĺ›şĺ®šçš„ĺŹ‘ĺ¸ĺ‘¨ćśźďĽŚä˝†ćŻé€šĺ¸¸ĺś¨ćŻŹä¸¤ä¸Ş-rcç‰ĺ†…ć ¸ĺŹ‘ĺ¸äą‹é—´é˝äĽšćś‰č‹Ąĺą˛ -个-mmç‰ĺ†…ć ¸ĺŹ‘ĺ¸ďĽä¸€č¬ćŻ1至3个）。 - - -ĺçł»ç»źç›¸ĺ…łĺ†…ć ¸ćşç ć ‘ĺ’ŚčˇĄä¸é›† ----------------------------- -相当一é¨ĺ†ĺ†…ć ¸ĺ系统开发者会公开他们自己的开发ćşç ć ‘ďĽŚä»Ąäľżĺ…¶ä»–äşşč˝äş†č§Łĺ†… -ć ¸çš„ä¸ŤĺŚé˘†ĺźźćŁĺś¨ĺŹ‘生的事ć…。如上所述，这些ćşç ć ‘äĽšč˘«é›†ćĺ°-mmç‰ćś¬ĺ†…ć ¸ä¸ă€‚ - -下面ćŻç›®ĺ‰ŤĺŹŻç”¨çš„ä¸€äş›ĺ†…ć ¸ćşç ć ‘çš„ĺ—表： - 通过git管ç†çš„ćşç ć ‘ďĽš - - Kbuild开发ćşç ć ‘ďĽŚ Sam Ravnborg <sam@ravnborg.org> - git.kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git - - - ACPI开发ćşç ć ‘, Len Brown <len.brown@intel.com> - git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git - - - 块设备开发ćşç ć ‘, Jens Axboe <axboe@suse.de> - git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git - - - DRM开发ćşç ć ‘, Dave Airlie <airlied@linux.ie> - git.kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git - - - ia64开发ćşç ć ‘, Tony Luck <tony.luck@intel.com> - git.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git +Linux-next 集ććµ‹čŻ•ć ‘ +--------------------- - - ieee1394开发ćşç ć ‘, Jody McIntyre <scjody@modernduck.com> - git.kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git +在将ĺçł»ç»źć ‘çš„ć›´ć–°ĺ并ĺ°ä¸»çşżć ‘之前，需č¦ĺŻąĺ®ä»¬čż›čˇŚé›†ć测试。为ć¤ďĽŚĺ在一个 +特殊的测试ĺ储库，其ä¸ĺ‡ 乎每天é˝äĽšćŹĺŹ–所有ĺçł»ç»źć ‘ďĽš - - infiniband开发ćşç ć ‘, Roland Dreier <rolandd@cisco.com> - git.kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git + https://git.kernel.org/？p=linux/kernel/git/next/linux-next.git - - libata开发ćşç ć ‘, Jeff Garzik <jgarzik@pobox.com> - git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git +通过这种方式，Linux-next 对下一个ĺ并é¶ć®µĺ°†čż›ĺ…Ąä¸»çşżĺ†…ć ¸çš„ĺ†…ĺ®ąç»™ĺ‡şäş†ä¸€ä¸Şć¦‚č¦ +展望。非常欢冒险的测试者čżčˇŚćµ‹čŻ•Linux-next。 - - 网络驱动程序开发ćşç ć ‘, Jeff Garzik <jgarzik@pobox.com> - git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git +多个主č¦ç‰ćś¬çš„稳定ç‰ĺ†…ć ¸ć ‘ +----------------------------------- +ç”±3个数ĺ—组ćçš„ĺ†…ć ¸ç‰ćś¬ĺŹ·čŻ´ćŽć¤ĺ†…ć ¸ćŻ-stableç‰ćś¬ă€‚ĺ®ä»¬ĺŚ…ĺ«ĺ†…ć ¸çš„ç›¸ĺŻąčľĺ°Źä¸” +至关重č¦çš„修补，这些修补é’对安全性问é˘ć–č€…ä¸Ąé‡Ťçš„ĺ†…ć ¸é€€ćĄă€‚ - - pcmcia开发ćşç ć ‘, Dominik Brodowski <linux@dominikbrodowski.net> - git.kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git +这种ç‰ćś¬çš„ĺ†…ć ¸é€‚ç”¨äşŽé‚Łäş›ćśźćś›čŽ·ĺľ—ćś€ć–°çš„ç¨łĺ®šç‰ĺ†…ć ¸ĺą¶ä¸”ä¸ŤćłĺŹ‚与测试开发ç‰ć– +者实验ç‰çš„用ć·ă€‚ - - SCSI开发ćşç ć ‘, James Bottomley <James.Bottomley@SteelEye.com> - git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git +稳定ç‰ĺ†…ć ¸ć ‘ç‰ćś¬ç”±â€śç¨łĺ®šç‰â€ťĺ°Źç»„ďĽé‚®ä»¶ĺś°ĺť€<stable@vger.kernel.org>ďĽ‰ç»´ćŠ¤ďĽŚä¸€č¬ +隔周发ĺ¸ć–°ç‰ćś¬ă€‚ - 使用quilt管ç†çš„补ä¸é›†ďĽš - - USB, PCI, é©±ĺŠ¨ç¨‹ĺşŹć ¸ĺżĺ’ŚI2C, Greg Kroah-Hartman <gregkh@linuxfoundation.org> - kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/ - - x86-64, é¨ĺ†i386, Andi Kleen <ak@suse.de> - ftp.firstfloor.org:/pub/ak/x86_64/quilt/ +ĺ†…ć ¸ćşç ä¸çš„ :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +文件具体描述了可被稳定ç‰ĺ†…ć ¸ćŽĄĺŹ—çš„äż®ć”ąç±»ĺž‹ä»ĄĺŹŠĺŹ‘ĺ¸çš„ćµç¨‹ă€‚ - ĺ…¶ä»–ĺ†…ć ¸ćşç ć ‘ĺŹŻä»Ąĺś¨http://git.kernel.orgçš„ĺ—表ä¸ĺ’ŚMAINTAINERS文件里 - 找ĺ°ă€‚ 报告bug ------- bugzilla.kernel.orgćŻLinuxĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ç”¨ćťĄč·źč¸Şĺ†…ć ¸Bug的网站。ć‘们鼓励用 ć·ĺś¨čż™ä¸Şĺ·Ąĺ…·ä¸ćŠĄĺ‘Šć‰ľĺ°çš„所有bugă€‚ĺ¦‚ä˝•ä˝żç”¨ĺ†…ć ¸bugzilla的细节请访问： + http://test.kernel.org/bugzilla/faq.html -ĺ†…ć ¸ćşç 主目录ä¸çš„admin-guide/reporting-bugs.rst文件里有一个ĺľĺĄ˝çš„模板。ĺ®ćŚ‡ĺŻĽç”¨ć·ĺ¦‚何报 -告可č˝çš„ĺ†…ć ¸bug以及需č¦ćŹäľ›ĺ“Şäş›äżˇćŻćťĄĺ¸®ĺŠ©ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ć‰ľĺ°é—®é˘çš„ć ąćşă€‚ +ĺ†…ć ¸ćşç 主目录ä¸çš„:ref:`admin-guide/reporting-bugs.rst <reportingbugs>` +文件里有一个ĺľĺĄ˝çš„模板。ĺ®ćŚ‡ĺŻĽç”¨ć·ĺ¦‚何报告可č˝çš„ĺ†…ć ¸bug以及需č¦ćŹäľ›ĺ“Şäş›äżˇćŻ +ćťĄĺ¸®ĺŠ©ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ć‰ľĺ°é—®é˘çš„ć ąćşă€‚ ĺ©ç”¨bug报告 @@ -330,12 +289,7 @@ bugzilla.kernel.orgćŻLinuxĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ç”¨ćťĄč·źč¸Şĺ†…ć ¸Bug的网站。ć 者感受ĺ°ä˝ çš„ĺ在。修改bugćŻčµ˘ĺľ—ĺ…¶ä»–ĺĽ€ĺŹ‘č€…čµžčŞ‰çš„ćś€ĺĄ˝ĺŠžćł•ďĽŚĺ› ä¸şĺą¶ä¸ŤćŻĺľĺ¤š äşşé˝ĺ–ść¬˘ćµŞč´ąć—¶é—´ĺŽ»äż®ć”ąĺ«äşşćŠĄĺ‘Šçš„bug。 -č¦ĺ°ťčŻ•äż®ć”ąĺ·˛çźĄçš„bug，请访问http://bugzilla.kernel.orgç˝‘ĺť€ă€‚ĺ¦‚ćžśä˝ ćłčŽ·ĺľ— -最新bug的通知，可以订é…bugme-new邮件ĺ—表ďĽĺŹŞćś‰ć–°çš„bug报告会被寄ĺ°čż™é‡ŚďĽ‰ -ć–者订é…bugme-janitor邮件ĺ—表ďĽć‰€ćś‰bugzillaçš„ĺŹĺŠ¨é˝äĽšč˘«ĺŻ„ĺ°čż™é‡ŚďĽ‰ă€‚ - - https://lists.linux-foundation.org/mailman/listinfo/bugme-new - https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors +č¦ĺ°ťčŻ•äż®ć”ąĺ·˛çźĄçš„bug，请访问 http://bugzilla.kernel.org 网址。 邮件ĺ—表 @@ -343,10 +297,14 @@ bugzilla.kernel.orgćŻLinuxĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ç”¨ćťĄč·źč¸Şĺ†…ć ¸Bug的网站。ć ćŁĺ¦‚ä¸Šéť˘çš„ć–‡ćˇŁć‰€ćŹŹčż°ďĽŚĺ¤§ĺ¤šć•°çš„éŞ¨ĺą˛ĺ†…ć ¸ĺĽ€ĺŹ‘č€…é˝ĺŠ 入了Linux Kernelé‚®ä»¶ĺ— čˇ¨ă€‚ĺ¦‚ä˝•č®˘é…和退订ĺ—表的细节可以在这里找ĺ°ďĽš + http://vger.kernel.org/vger-lists.html#linux-kernel + 网上ĺľĺ¤šĺś°ć–ąé˝ćś‰čż™ä¸Şé‚®ä»¶ĺ—表的ĺ档(archive)。可以使用ćśç´˘ĺĽ•ć“ŽćťĄć‰ľĺ°čż™äş› ĺ档。比如： + http://dir.gmane.org/gmane.linux.kernel + 在发信之前，ć‘们强çĺ»şč®®ä˝ ĺ…在ĺ档ä¸ćśç´˘ä˝ ćłč¦č®¨č®şçš„é—®é˘ă€‚ĺľĺ¤šĺ·˛ç»Źč˘«čŻ¦ç»† 讨论过的问é˘ĺŹŞĺś¨é‚®ä»¶ĺ—表的ĺ档ä¸ĺŹŻä»Ąć‰ľĺ°ă€‚ @@ -354,10 +312,12 @@ bugzilla.kernel.orgćŻLinuxĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ç”¨ćťĄč·źč¸Şĺ†…ć ¸Bug的网站。ć MAINTAINERS文件ä¸ĺŹŻä»Ąć‰ľĺ°ä¸ŤĺŚčŻťé˘ĺŻąĺş”的邮件ĺ—表。 ĺľĺ¤šé‚®ä»¶ĺ—表架设在kernel.org服务器上。这些ĺ—表的信ćŻĺŹŻä»Ąĺś¨čż™é‡Ść‰ľĺ°ďĽš + http://vger.kernel.org/vger-lists.html 在使用这些邮件ĺ—表时，请记住保ćŚč‰ŻĺĄ˝çš„čˇŚä¸şäą ćŻă€‚下面的链接ćŹäľ›äş†ä¸Žčż™äş›ĺ— 表ďĽć–任何其ĺ®é‚®ä»¶ĺ—表）交ćµçš„一些简单规ĺ™ďĽŚč™˝ç„¶ĺ†…容有点滥竽充数。 + http://www.albion.com/netiquette/ 当有ĺľĺ¤šäşşĺ›žĺ¤Ťä˝ 的邮件时，邮件的抄é€ĺ—表会ĺŹĺľ—ĺľé•żă€‚请不č¦ĺ°†ä»»ä˝•äşşä»ŽćŠ„é€ @@ -369,11 +329,12 @@ MAINTAINERS文件ä¸ĺŹŻä»Ąć‰ľĺ°ä¸ŤĺŚčŻťé˘ĺŻąĺş”的邮件ĺ—表。 čż™ĺ‡ čˇŚă€‚ĺ°†ä˝ çš„čŻ„č®şĺŠ ĺś¨č˘«ĺĽ•ç”¨çš„ć®µč˝äą‹é—´č€Śä¸Ťč¦ć”ľĺś¨é‚®ä»¶çš„顶é¨ă€‚ ĺ¦‚ćžśä˝ ĺś¨é‚®ä»¶ä¸é™„带补ä¸ďĽŚčŻ·çˇ®č®¤ĺ®ä»¬ćŻĺŹŻä»Ąç›´ćŽĄé…读的纯文本ďĽĺ¦‚ -Documentation/process/submitting-patches.rst文档ä¸ć‰€čż°ďĽ‰ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ä¸Ťĺ¸Śćś›é‡ĺ°é™„件 -ć–者被压缩了的补ä¸ă€‚ĺŹŞćś‰čż™ć ·ć‰Ťč˝äżťčŻä»–ä»¬ĺŹŻä»Ąç›´ćŽĄčŻ„č®şä˝ çš„ćŻŹčˇŚä»Łç 。请确保 -ä˝ ä˝żç”¨çš„é‚®ä»¶ĺŹ‘é€ç¨‹ĺşŹä¸ŤäĽšäż®ć”ąç©şć Ľĺ’Śĺ¶čˇ¨ç¬¦ă€‚一个é˛čŚć€§çš„测试方法ćŻĺ…将邮件 -发é€ç»™č‡Şĺ·±ďĽŚç„¶ĺŽč‡Şĺ·±ĺ°ťčŻ•ćŻĺ¦ĺŹŻä»Ąéˇşĺ©ĺś°ć‰“上收ĺ°çš„补ä¸ă€‚如果测试不ć功，请 -č°ć•´ć–č€…ć›´ćŤ˘ä˝ çš„é‚®ä»¶ĺŹ‘é€ç¨‹ĺşŹç›´ĺ°ĺ®ćŁçˇ®ĺ·Ąä˝śä¸şć˘ă€‚ +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` +文档ä¸ć‰€čż°ďĽ‰ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ä»¬ä¸Ťĺ¸Śćś›é‡ĺ°é™„件ć–者被压缩了的补ä¸ă€‚ĺŹŞćś‰čż™ć ·ć‰Ťč˝ +äżťčŻä»–ä»¬ĺŹŻä»Ąç›´ćŽĄčŻ„č®şä˝ çš„ćŻŹčˇŚä»Łç ă€‚čŻ·çˇ®äżťä˝ ä˝żç”¨çš„é‚®ä»¶ĺŹ‘é€ç¨‹ĺşŹä¸ŤäĽšäż®ć”ąç©şć Ľ +ĺ’Śĺ¶čˇ¨ç¬¦ă€‚一个é˛čŚć€§çš„测试方法ćŻĺ…将邮件发é€ç»™č‡Şĺ·±ďĽŚç„¶ĺŽč‡Şĺ·±ĺ°ťčŻ•ćŻĺ¦ĺŹŻä»Ą +顺ĺ©ĺś°ć‰“上收ĺ°çš„补ä¸ă€‚如果测试不ć功，请č°ć•´ć–č€…ć›´ćŤ˘ä˝ çš„é‚®ä»¶ĺŹ‘é€ç¨‹ĺşŹç›´ĺ° +ĺ®ćŁçˇ®ĺ·Ąä˝śä¸şć˘ă€‚ 总而言之，请尊重其他的邮件ĺ—表订é…者。 @@ -383,6 +344,7 @@ Documentation/process/submitting-patches.rst文档ä¸ć‰€čż°ďĽ‰ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘č€… ĺ†…ć ¸ç¤ľĺŚşçš„ç›®ć ‡ĺ°±ćŻćŹäľ›ĺ°˝ĺ–„ĺ°˝çľŽçš„ĺ†…ć ¸ă€‚ć‰€ä»Ąĺ˝“ä˝ ćŹäş¤čˇĄä¸ćśźćś›č˘«ćŽĄĺŹ—čż›ĺ†…ć ¸çš„ 时候，ĺ®çš„技术价值以及其他方面é˝ĺ°†č˘«čŻ„审。那äąä˝ 可č˝äĽšĺľ—ĺ°ä»€äąĺ‘˘ďĽź + - 批评 - 评论 - č¦ć±‚修改 @@ -395,6 +357,7 @@ Documentation/process/submitting-patches.rst文档ä¸ć‰€čż°ďĽ‰ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘č€… 没在茫茫信海ä¸ă€‚ ä˝ ä¸Ťĺş”čŻĄĺšçš„äş‹ć…： + - 期望自己的补ä¸ä¸ŤĺŹ—任何质疑就直接被接受 - 翻脸 - 忽略ĺ«äşşçš„评论 @@ -414,7 +377,8 @@ Documentation/process/submitting-patches.rst文档ä¸ć‰€čż°ďĽ‰ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘č€… ĺ†…ć ¸ç¤ľĺŚşçš„ĺ·Ąä˝ść¨ˇĺĽŹĺŚĺ¤§ĺ¤šć•°äĽ 统公司开发éźäĽŤçš„工作模式并不相ĺŚă€‚下面这些例 ĺďĽŚĺŹŻä»Ąĺ¸®ĺŠ©ä˝ éżĺ…Ťćźäş›ĺŹŻč˝ĺŹ‘生问é˘ďĽš - ç”¨čż™äş›čŻťä»‹ç»Ťä˝ çš„äż®ć”ąćŹćˇäĽšćś‰ĺĄ˝ĺ¤„： +ç”¨čż™äş›čŻťä»‹ç»Ťä˝ çš„äż®ć”ąćŹćˇäĽšćś‰ĺĄ˝ĺ¤„： + - ĺ®ĺŚć—¶č§Łĺ†łäş†ĺ¤šä¸Şé—®é˘ - ĺ®ĺ 除了2000行代ç - čż™ćŻčˇĄä¸ďĽŚĺ®ĺ·˛ç»Źč§Łé‡Šäş†ć‘ćłč¦čŻ´ćŽçš„ @@ -422,7 +386,8 @@ Documentation/process/submitting-patches.rst文档ä¸ć‰€čż°ďĽ‰ă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘č€… - čż™ćŻä¸€çł»ĺ—小补ä¸ç”¨ćťĄâ€¦â€¦ - 这个修改ćŹé«äş†ć™®é€šćśşĺ™¨çš„性č˝â€¦â€¦ - 应该éżĺ…Ťĺ¦‚下的说法： +应该éżĺ…Ťĺ¦‚下的说法： + - ć‘们在AIX/ptx/Solarisĺ°±ćŻčż™äąĺšçš„，所以这äąĺšč‚Żĺ®šćŻĺĄ˝çš„…… - ć‘ĺščż™čˇŚĺ·˛ç»Ź20年了，所以…… - 为了ć‘们公司赚钱č€č™‘必须这äąĺš @@ -495,6 +460,7 @@ Linuxĺ†…ć ¸ç¤ľĺŚşĺą¶ä¸Ťĺ–ść¬˘ä¸€ä¸‹ćŽĄć”¶ĺ¤§ć®µçš„ä»Łç 。修改需č¦č˘«ć°ĺ˝“ ĺ˝“ä˝ ĺŹ‘é€čˇĄä¸çš„时候，需č¦ç‰ąĺ«ç•™ć„Źé‚®ä»¶ćŁć–‡çš„ĺ†…ĺ®ąă€‚ĺ› ä¸şčż™é‡Śçš„äżˇćŻĺ°†äĽšĺšä¸şčˇĄ ä¸çš„修改记录(ChangeLog)，会被一直保留以备大家查é…。ĺ®éś€č¦ĺ®Śĺ…¨ĺś°ćŹŹčż°čˇĄä¸ďĽŚ 包括： + - 为什äąéś€č¦čż™ä¸Şäż®ć”ą - 补ä¸çš„总体设计 - 实现细节 @@ -510,7 +476,8 @@ Linuxĺ†…ć ¸ç¤ľĺŚşĺą¶ä¸Ťĺ–ść¬˘ä¸€ä¸‹ćŽĄć”¶ĺ¤§ć®µçš„ä»Łç 。修改需č¦č˘«ć°ĺ˝“ ĺľĺ¤šäşşĺ·˛ç»Źĺšĺ°äş†ďĽŚč€Śä»–们é˝ć›ľç»Źĺ’ŚçŽ°ĺś¨çš„ä˝ ç«™ĺś¨ĺŚć ·çš„起点上。 ---------------- +ć„źč°˘ +---- ć„źč°˘Paolo Ciarrocchiĺ…许“开发ćµç¨‹â€ťé¨ĺ†ĺźşäşŽä»–ć‰€ĺ†™çš„ć–‡ç« (http://www.kerneltravel.net/newbie/2.6-development_process)，感谢Randy Dunlapĺ’ŚGerrit Huizenga完善了应该说和不该说的ĺ—表。感谢Pat Mochel, Hanna diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst new file mode 100644 index 000000000000..be1e764a80d2 --- /dev/null +++ b/Documentation/translations/zh_CN/process/index.rst @@ -0,0 +1,60 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/index.rst <process_index>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_process_index: + +与Linux ĺ†…ć ¸ç¤ľĺŚşä¸€čµ·ĺ·Ąä˝ś +======================== + +é‚Łäąä˝ ćłć为Linuxĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘？ ć¬˘čżŽďĽ ä¸Ťä˝†ä»ŽćŠ€ćśŻć„Źäą‰ä¸Šč®˛ćś‰ĺľĺ¤šĺ…łäşŽĺ†…ć ¸çš„çźĄčŻ† +需č¦ĺ¦ďĽŚč€Śä¸”了解ć‘们社区的工作方式也ĺľé‡Ťč¦ă€‚ é…čŻ»čż™äş›ć–‡ç« ĺŹŻä»Ąč®©ć‚¨ä»Ąć›´č˝»ćťľĺś°, +éş»ç¦ćś€ĺ°‘的方式将更改ĺ并ĺ°ĺ†…ć ¸ă€‚ + +以下ćŻćŻŹä˝ŤĺĽ€ĺŹ‘äşşĺ‘ĺş”é…读的基本指南。 + +.. toctree:: + :maxdepth: 1 + + howto + code-of-conduct + code-of-conduct-interpretation + submitting-patches + programming-language + coding-style + development-process + email-clients + license-rules + +ĺ…¶ĺ®ĺ¤§ĺ¤šć•°ĺĽ€ĺŹ‘äşşĺ‘感兴趣的社区指南： + + +.. toctree:: + :maxdepth: 1 + + submitting-drivers + submit-checklist + stable-api-nonsense + stable-kernel-rules + management-style + +这些ćŻä¸€äş›ć€»ä˝“技术指南，由于缺乏更好的地方，现在已经放在这里 + +.. toctree:: + :maxdepth: 1 + + magic-number + volatile-considered-harmful + +.. only:: subproject and html + + 目录 + ==== + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/process/license-rules.rst b/Documentation/translations/zh_CN/process/license-rules.rst new file mode 100644 index 000000000000..30c272b2a292 --- /dev/null +++ b/Documentation/translations/zh_CN/process/license-rules.rst @@ -0,0 +1,370 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/license-rules.rst <kernel_licensing>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_kernel_licensing: + +Linuxĺ†…ć ¸č®¸ĺŹŻč§„ĺ™ +================= + +Linuxĺ†…ć ¸ć ąćŤ®LICENSES/preferred/GPL-2.0ä¸ćŹäľ›çš„GNU通用公共许可čŻç‰ćś¬2 +ďĽGPL-2.0）的条款ćŹäľ›ďĽŚĺą¶ĺś¨LICENSES/exceptions/Linux-syscall-noteä¸ćľĺĽŹ +描述了例外的系统č°ç”¨ďĽŚĺ¦‚COPYING文件ä¸ć‰€čż°ă€‚ + +ć¤ć–‡ćˇŁć–‡ä»¶ćŹäľ›äş†ĺ¦‚何对每个ćşć–‡ä»¶čż›čˇŚćł¨é‡Šä»Ąä˝żĺ…¶č®¸ĺŹŻčŻć¸…ć™°ćŽçˇ®çš„说ćŽă€‚ +ĺ®ä¸ŤäĽšĺŹ–ä»Łĺ†…ć ¸çš„č®¸ĺŹŻčŻă€‚ + +ĺ†…ć ¸ćşä»Łç 作为一个整体适用于COPYING文件ä¸ćŹŹčż°çš„许可čŻďĽŚä˝†ćŻĺŤ•ä¸Şćşć–‡ä»¶ĺŹŻä»Ą +具有不ĺŚçš„与GPL-20兼容的许可čŻ:: + + GPL-1.0+ : GNU通用公共许可čŻv1.0ć–ć›´é«ç‰ćś¬ + GPL-2.0+ : GNU通用公共许可čŻv2.0ć–ć›´é«ç‰ćś¬ + LGPL-2.0 : ä»…é™GNU库通用公共许可čŻv2 + LGPL-2.0+: GNU 库通用公共许可čŻv2ć–ć›´é«ç‰ćś¬ + LGPL-2.1 : ä»…é™GNU宽通用公共许可čŻv2.1 + LGPL-2.1+: GNU宽通用公共许可čŻv2.1ć–ć›´é«ç‰ćś¬ + +除ć¤äą‹ĺ¤–，个人文件可以在双重许可下ćŹäľ›ďĽŚäľ‹ĺ¦‚一个兼容的GPLĺŹä˝“，ć–者BSD， +MITç‰č®¸ĺŹŻă€‚ + +用ć·ç©şé—´APIďĽUAPI）头文件描述了用ć·ç©şé—´ç¨‹ĺşŹä¸Žĺ†…ć ¸çš„ćŽĄĺŹŁďĽŚčż™ćŻä¸€ç§Ťç‰ąć®Šć…况。 +ć ąćŤ®ĺ†…ć ¸COPYING文件ä¸çš„注释，syscall接口ćŻä¸€ä¸ŞćŽçˇ®çš„边界，ĺ®ä¸ŤäĽšĺ°†GPLč¦ć±‚ +扩展ĺ°ä»»ä˝•ä˝żç”¨ĺ®ä¸Žĺ†…ć ¸é€šäżˇçš„č˝Żä»¶ă€‚ç”±äşŽUAPI头文件必须包ĺ«ĺś¨ĺ›ĺ»şĺś¨Linuxĺ†…ć ¸ +上čżčˇŚçš„可执行文件的任何ćşć–‡ä»¶ä¸ďĽŚĺ› ć¤ć¤äľ‹ĺ¤–必须记录在特ĺ«çš„许可čŻčˇ¨čż°ä¸ă€‚ + +表达ćşć–‡ä»¶č®¸ĺŹŻčŻçš„常用方法ćŻĺ°†ĺŚąé…Ťçš„ć ·ćťżć–‡ćś¬ć·»ĺŠ ĺ°ć–‡ä»¶çš„顶é¨ćł¨é‡Šä¸ă€‚由于 +ć ĽĺĽŹďĽŚć‹Ľĺ†™é”™čŻŻç‰ďĽŚčż™äş›â€ść ·ćťżâ€ťĺľéšľé€ščż‡é‚Łäş›ĺś¨ä¸Šä¸‹ć–‡ä¸ä˝żç”¨çš„验čŻč®¸ĺŹŻčŻĺ规性 +的工具。 + +ć ·ćťżć–‡ćś¬çš„ć›żä»Łć–ąćł•ćŻĺś¨ćŻŹä¸Şćşć–‡ä»¶ä¸ä˝żç”¨č˝Żä»¶ĺŚ…数据交换ďĽSPDX）许可čŻć ‡čŻ†ç¬¦ă€‚ +SPDX许可čŻć ‡čŻ†ç¬¦ćŻćśşĺ™¨ĺŹŻč§Łćžçš„，并且ćŻç”¨äşŽćŹäľ›ć–‡ä»¶ĺ†…容的许可čŻçš„精确缩写。 +SPDX许可čŻć ‡čŻ†ç¬¦ç”±Linux 基金会的SPDX 工作组管ç†ďĽŚĺą¶ĺľ—ĺ°äş†ć•´ä¸ŞčˇŚä¸šďĽŚĺ·Ąĺ…· +供应商和法律团éźçš„ĺ作伙伴的一致ĺŚć„Źă€‚有关详细信ćŻďĽŚčŻ·ĺŹ‚é… +https://spdx.org/ + +Linuxĺ†…ć ¸éś€č¦ć‰€ćś‰ćşć–‡ä»¶ä¸çš„精确SPDXć ‡čŻ†ç¬¦ă€‚ĺ†…ć ¸ä¸ä˝żç”¨çš„有ć•ć ‡čŻ†ç¬¦ĺś¨ +`č®¸ĺŹŻć ‡čŻ†ç¬¦`_ 一节ä¸čż›čˇŚäş†č§Łé‡ŠďĽŚĺą¶ä¸”已可以在 +https://spdx.org/licenses/ 上的ĺ®ć–ąSPDX许可čŻĺ—表ä¸ćŁ€ç´˘ďĽŚĺą¶é™„ĺ¸¦č®¸ĺŹŻčŻ +文本。 + +č®¸ĺŹŻć ‡čŻ†ç¬¦čŻćł• +-------------- + +1.安置: + +Â Â Â ĺ†…ć ¸ć–‡ä»¶ä¸çš„SPDX许可čŻć ‡čŻ†ç¬¦ĺş”ć·»ĺŠ ĺ°ĺŹŻĺŚ…ĺ«ćł¨é‡Šçš„文件ä¸çš„第一行。对于大多 + 数文件，这ćŻç¬¬ä¸€čˇŚďĽŚé™¤äş†é‚Łäş›ĺś¨ç¬¬ä¸€čˇŚä¸éś€č¦'#!PATH_TO_INTERPRETER'的脚本。 + 对于这些脚本，SPDXć ‡čŻ†ç¬¦čż›ĺ…Ąç¬¬äşŚčˇŚă€‚ + +| + +2. éŁŽć Ľ: + + SPDX许可čŻć ‡čŻ†ç¬¦ä»Ąćł¨é‡Šçš„ĺ˝˘ĺĽŹć·»ĺŠ ă€‚ćł¨é‡Šć ·ĺĽŹĺŹ–ĺ†łäşŽć–‡ä»¶ç±»ĺž‹:: + + C source: // SPDX-License-Identifier: <SPDX License Expression> + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ + scripts: # SPDX-License-Identifier: <SPDX License Expression> + .rst: .. SPDX-License-Identifier: <SPDX License Expression> + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> + + ĺ¦‚ćžśç‰ąĺ®šĺ·Ąĺ…·ć— ćł•ĺ¤„ç†ć ‡ĺ‡†ćł¨é‡Šć ·ĺĽŹďĽŚĺ™ĺş”使用工具接受的相应注释机ĺ¶ă€‚čż™ćŻĺś¨ + C 头文件ä¸ä˝żç”¨â€ś/\*\*/â€ťć ·ĺĽŹćł¨é‡Šçš„ĺŽźĺ› ă€‚čż‡ĺŽ»ĺś¨ä˝żç”¨ç”źćçš„.lds文件ä¸č§‚ĺŻźĺ° + ćž„ĺ»şč˘«ç ´ĺťŹďĽŚĺ…¶ä¸'ld'ć— ćł•č§ŁćžC++注释。现在已经解决了这个问é˘ďĽŚä˝†ä»Ťç„¶ćś‰čľ + ć—§çš„ć±‡çĽ–ç¨‹ĺşŹĺ·Ąĺ…·ć— ćł•ĺ¤„ç†C++ć ·ĺĽŹçš„ćł¨é‡Šă€‚ + +| + +3. 句法: + + <SPDX许可čŻčˇ¨čľľĺĽŹ>ćŻSPDX许可čŻĺ—表ä¸çš„SPDXçźć ĽĺĽŹč®¸ĺŹŻčŻć ‡čŻ†ç¬¦ďĽŚć–者在许可 + čŻäľ‹ĺ¤–适用时由“WITH”ĺ†éš”的两个SPDXçźć ĽĺĽŹč®¸ĺŹŻčŻć ‡čŻ†ç¬¦çš„组ĺ。当应用多个许 + 可čŻć—¶ďĽŚčˇ¨čľľĺĽŹç”±ĺ†éš”ĺ表达式的关键ĺ—“AND”，“OR”组ć，并由“ďĽâ€ťďĽŚâ€śďĽ‰â€ťĺŚ…围。 + + 带有“ć–ć›´é«â€ťé€‰éˇąçš„[L]GPLç‰č®¸ĺŹŻčŻçš„许可čŻć ‡čŻ†ç¬¦é€ščż‡ä˝żç”¨â€ś+”来表示“ć–ć›´é«â€ť + 选项来构建。:: + + // SPDX-License-Identifier: GPL-2.0+ + // SPDX-License-Identifier: LGPL-2.1+ + + 当需č¦äż®ćŁçš„许可čŻć—¶ďĽŚĺş”使用WITH。 例如，linuxĺ†…ć ¸UAPI文件使用表达式:: + + // SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note + // SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note + + ĺ…¶ĺ®ĺś¨ĺ†…ć ¸ä¸ä˝żç”¨WITH例外的事例如下:: + + // SPDX-License-Identifier: GPL-2.0 WITH mif-exception + // SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0 + + 例外只č˝ä¸Žç‰ąĺ®šçš„许可čŻć ‡čŻ†ç¬¦ä¸€čµ·ä˝żç”¨ă€‚有ć•çš„许可čŻć ‡čŻ†ç¬¦ĺ—在异常文本文件 + çš„ć ‡č®°ä¸ă€‚有关详细信ćŻďĽŚčŻ·ĺŹ‚é… `č®¸ĺŹŻć ‡čŻ†ç¬¦`_ ä¸€ç« ä¸çš„ `例外`_ 。 + + 如果文件ćŻĺŹŚé‡Ťč®¸ĺŹŻä¸”只选择一个许可čŻďĽŚĺ™ĺş”使用OR。例如，一些dtsi文件在双 + 许可下可用:: + + // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause + + ĺ†…ć ¸ä¸ĺŹŚč®¸ĺŹŻć–‡ä»¶ä¸č®¸ĺŹŻčˇ¨čľľĺĽŹçš„示例:: + + // SPDX-License-Identifier: GPL-2.0 OR MIT + // SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause + // SPDX-License-Identifier: GPL-2.0 OR Apache-2.0 + // SPDX-License-Identifier: GPL-2.0 OR MPL-1.1 + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT + // SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL + + 如果文件具有多个许可čŻďĽŚĺ…¶ćťˇć¬ľĺ…¨é¨é€‚用于使用该文件，ĺ™ĺş”使用AND。例如， + 如果代ç ćŻä»ŽĺŹ¦ä¸€ä¸Şéˇąç›®ç»§ć‰żçš„，并且已经ćŽäşäş†ĺ°†ĺ…¶ć”ľĺ…Ąĺ†…ć ¸çš„ćťé™ďĽŚä˝†ĺŽźĺ§‹ + 许可条款需č¦äżťćŚćś‰ć•:: + + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT + + 另一个需č¦éµĺ®ä¸¤ĺĄ—许可条款的例ĺćŻ:: + + // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+ + +č®¸ĺŹŻć ‡čŻ†ç¬¦ +---------- + +当前使用的许可čŻä»ĄĺŹŠć·»ĺŠ ĺ°ĺ†…ć ¸çš„ä»Łç 许可čŻĺŹŻä»Ąĺ†č§Łä¸şďĽš + +1. _`äĽĺ…许可`: + + 应尽可č˝ä˝żç”¨čż™äş›č®¸ĺŹŻčŻďĽŚĺ› 为ĺ®ä»¬ĺ·˛çźĄĺ®Śĺ…¨ĺ…Ľĺ®ąĺą¶ĺążćł›ä˝żç”¨ă€‚这些许可čŻĺś¨ĺ†…ć ¸ + 目录:: + + LICENSES/preferred/ + + ć¤ç›®ĺ˝•ä¸çš„文件包ĺ«ĺ®Ść•´çš„许可čŻć–‡ćś¬ĺ’Ś `ĺ…ć ‡č®°`_ 。文件ĺŤä¸ŽSPDX许可čŻć ‡čŻ† + 符相ĺŚďĽŚĺŽč€…应用于ćşć–‡ä»¶ä¸çš„许可čŻă€‚ + + 例如:: + + LICENSES/preferred/GPL-2.0 + + 包ĺ«GPLv2许可čŻć–‡ćś¬ĺ’Ść‰€éś€çš„ĺ…ć ‡çľ:: + + LICENSES/preferred/MIT + + 包ĺ«MIT许可čŻć–‡ćś¬ĺ’Ść‰€éś€çš„ĺ…ć ‡č®° + + _`ĺ…ć ‡č®°`: + + 许可čŻć–‡ä»¶ä¸ĺż…须包ĺ«ä»Ąä¸‹ĺ…ć ‡č®°ďĽš + + - Valid-License-Identifier: + +   一行ć–多行, 声ćŽé‚Łäş›č®¸ĺŹŻć ‡čŻ†ç¬¦ĺś¨éˇąç›®ĺ†…有ć•, 以引用ć¤ç‰ąĺ®šč®¸ĺŹŻçš„文本。通 + 常这ćŻä¸€ä¸Şćś‰ć•çš„ć ‡čŻ†ç¬¦ďĽŚä˝†ćŻäľ‹ĺ¦‚对于带有'ć–ć›´é«'选项的许可čŻďĽŚä¸¤ä¸Şć ‡čŻ† + 符é˝ćś‰ć•ă€‚ + + - SPDX-URL: + + SPDX页面的URL，其ä¸ĺŚ…ĺ«ä¸Žč®¸ĺŹŻčŻç›¸ĺ…łçš„其他信ćŻ. + + - Usage-Guidance: + + ä˝żç”¨ĺ»şč®®çš„č‡Şç”±ć ĽĺĽŹć–‡ćś¬ă€‚čŻĄć–‡ćś¬ĺż…éˇ»ĺŚ…ĺ«SPDX许可čŻć ‡čŻ†ç¬¦çš„ćŁçˇ®ç¤şäľ‹ďĽŚĺ› 为 + ĺ®ä»¬ĺş”ć ąćŤ® `č®¸ĺŹŻć ‡čŻ†ç¬¦čŻćł•`_ 指南放入ćşć–‡ä»¶ä¸ă€‚ + + - License-Text: + + ć¤ć ‡č®°äą‹ĺŽçš„所有文本é˝č˘«č§†ä¸şĺŽźĺ§‹č®¸ĺŹŻć–‡ćś¬ + + ć–‡ä»¶ć ĽĺĽŹç¤şäľ‹:: + + Valid-License-Identifier: GPL-2.0 + Valid-License-Identifier: GPL-2.0+ + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html + Usage-Guide: + To use this license in source code, put one of the following SPDX + tag/value pairs into a comment according to the placement + guidelines in the licensing rules documentation. + For 'GNU General Public License (GPL) version 2 only' use: + SPDX-License-Identifier: GPL-2.0 + For 'GNU General Public License (GPL) version 2 or any later version' use: + SPDX-License-Identifier: GPL-2.0+ + License-Text: + Full license text + + :: + + SPDX-License-Identifier: MIT + SPDX-URL: https://spdx.org/licenses/MIT.html + Usage-Guide: + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: MIT + License-Text: + Full license text + +| + +2. 不推čŤçš„许可čŻ: + + 这些许可čŻĺŹŞĺş”用于现有代ç ć–从其他项目导入代ç 。这些许可čŻĺś¨ĺ†…ć ¸ç›®ĺ˝•:: + + LICENSES/other/ + + ć¤ç›®ĺ˝•ä¸çš„文件包ĺ«ĺ®Ść•´çš„许可čŻć–‡ćś¬ĺ’Ś `ĺ…ć ‡č®°`_ 。文件ĺŤä¸ŽSPDX许可čŻć ‡čŻ† + 符相ĺŚďĽŚĺŽč€…应用于ćşć–‡ä»¶ä¸çš„许可čŻă€‚ + + 例如:: + + LICENSES/other/ISC + + 包ĺ«ĺ›˝é™…系统č”ĺ许可文本和所需的ĺ…ć ‡çľ:: + + LICENSES/other/ZLib + + 包ĺ«ZLIB许可文本和所需的ĺ…ć ‡çľ. + + ĺ…ć ‡çľ: + + “其他”许可čŻçš„ĺ…ć ‡çľč¦ć±‚与 `äĽĺ…许可`_ çš„č¦ć±‚相ĺŚă€‚ + + ć–‡ä»¶ć ĽĺĽŹç¤şäľ‹:: + + Valid-License-Identifier: ISC + SPDX-URL: https://spdx.org/licenses/ISC.html + Usage-Guide: + Usage of this license in the kernel for new code is discouraged + and it should solely be used for importing code from an already + existing project. + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: ISC + License-Text: + Full license text + +| + +3. _`例外`: + + ćźäş›č®¸ĺŹŻčŻĺŹŻä»Ąäż®ć”ąďĽŚĺą¶ĺ…许原始许可čŻä¸Ťĺ…·ćś‰çš„ćźäş›äľ‹ĺ¤–ćťĺ©ă€‚这些例外在 + ĺ†…ć ¸ç›®ĺ˝•:: + + LICENSES/exceptions/ + + ć¤ç›®ĺ˝•ä¸çš„文件包ĺ«ĺ®Ść•´çš„例外文本和所需的 `例外ĺ…ć ‡č®°`_ 。 + + 例如:: + + LICENSES/exceptions/Linux-syscall-note + + 包ĺ«Linuxĺ†…ć ¸çš„COPYING文件ä¸č®°ĺ˝•çš„Linux系统č°ç”¨äľ‹ĺ¤–，该文件用于UAPI + 头文件。例如:: + + LICENSES/exceptions/GCC-exception-2.0 + + 包ĺ«GCC'链接例外'，ĺ®ĺ…许独立于其许可čŻçš„任何二进ĺ¶ć–‡ä»¶ä¸Žć ‡č®°ćś‰ć¤äľ‹ĺ¤–çš„ + 文件的编译ç‰ćś¬é“ľćŽĄă€‚čż™ćŻä»ŽGPL不兼容ćşä»Łç ĺ›ĺ»şĺŹŻčżčˇŚçš„可执行文件所必需的。 + + _`例外ĺ…ć ‡č®°`: + + 以下ĺ…ć ‡č®°ĺż…éˇ»ĺś¨äľ‹ĺ¤–ć–‡ä»¶ä¸ĺŹŻç”¨ďĽš + + - SPDX-Exception-Identifier: + +   一个可与SPDX许可čŻć ‡čŻ†ç¬¦ä¸€čµ·ä˝żç”¨çš„äľ‹ĺ¤–ć ‡čŻ†ç¬¦ă€‚ + + - SPDX-URL: + + SPDX页面的URL，其ä¸ĺŚ…ĺ«ä¸Žäľ‹ĺ¤–相关的其他信ćŻă€‚ + + - SPDX-Licenses: + +   以逗号ĺ†éš”的例外可用的SPDX许可čŻć ‡čŻ†ç¬¦ĺ—表。 + + - Usage-Guidance: + + ä˝żç”¨ĺ»şč®®çš„č‡Şç”±ć ĽĺĽŹć–‡ćś¬ă€‚ĺż…éˇ»ĺś¨ć–‡ćś¬ĺŽéť˘ĺŠ 上SPDX许可čŻć ‡čŻ†ç¬¦çš„ćŁçˇ®ç¤şäľ‹ďĽŚ + ĺ› ä¸şĺ®ä»¬ĺş”ć ąćŤ® `č®¸ĺŹŻć ‡čŻ†ç¬¦čŻćł•`_ 指南放入ćşć–‡ä»¶ä¸ă€‚ + + - Exception-Text: + + ć¤ć ‡č®°äą‹ĺŽçš„所有文本é˝č˘«č§†ä¸şĺŽźĺ§‹ĺĽ‚常文本 + + ć–‡ä»¶ć ĽĺĽŹç¤şäľ‹:: + + SPDX-Exception-Identifier: Linux-syscall-note + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ + Usage-Guidance: + This exception is used together with one of the above SPDX-Licenses + to mark user-space API (uapi) header files so they can be included + into non GPL compliant user-space application code. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note + Exception-Text: + Full exception text + + :: + + SPDX-Exception-Identifier: GCC-exception-2.0 + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html + SPDX-Licenses: GPL-2.0, GPL-2.0+ + Usage-Guidance: + The "GCC Runtime Library exception 2.0" is used together with one + of the above SPDX-Licenses for code imported from the GCC runtime + library. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0 + Exception-Text: + Full exception text + + +所有SPDX许可čŻć ‡čŻ†ç¬¦ĺ’Śäľ‹ĺ¤–é˝ĺż…须在LICENSESĺ目录ä¸ĺ…·ćś‰ç›¸ĺş”的文件。这ćŻĺ…许 +工具验čŻďĽäľ‹ĺ¦‚checkpatch.pl）以及准备好从ćşčŻ»ĺŹ–ĺ’ŚćŹĺŹ–许可čŻć‰€ĺż…需的, čż™ćŻ +ĺ„种FOSS组织推čŤçš„，例如 `FSFE REUSE initiative <https://reuse.software/>`_. + +_`模块许可` +----------------- + + ĺŹŻĺŠ č˝˝ĺ†…ć ¸ć¨ˇĺť—čżéś€č¦MODULE_LICENSEďĽďĽ‰ć ‡č®°ă€‚ć¤ć ‡č®°ć—˘ä¸Ťć›żä»ŁćŁçˇ®çš„ćşä»Łç + 许可čŻäżˇćŻďĽSPDX-License-Identifier），也不以任何方式表示ć–确定ćŹäľ›ć¨ˇĺť— + ćşä»Łç 的确ĺ‡č®¸ĺŹŻčŻă€‚ + + ć¤ć ‡č®°çš„唯一目的ćŻćŹäľ›č¶łĺ¤źçš„信ćŻďĽŚčŻĄć¨ˇĺť—ćŻĺ¦ćŻč‡Şç”±č˝Żä»¶ć–者ćŻĺ†…ć ¸ć¨ˇĺť—ĺŠ + 载器和用ć·ç©şé—´ĺ·Ąĺ…·çš„专有模块。 + + MODULE_LICENSEďĽďĽ‰çš„有ć•č®¸ĺŹŻčŻĺ—符串ćŻ: + + ============================= ============================================= + "GPL" 模块ćŻć ąćŤ®GPLç‰ćś¬2许可的。这并不表示仅é™äşŽ + GPL-2.0ć–GPL-2.0ć–ć›´é«ç‰ćś¬äą‹é—´çš„任何区ĺ«ă€‚ + 最ćŁçˇ®č®¸ĺŹŻčŻäżˇćŻĺŹŞč˝é€ščż‡ç›¸ĺş”ćşć–‡ä»¶ä¸çš„č®¸ĺŹŻčŻ + 信ćŻćťĄçˇ®ĺ®š + + "GPL v2" ĺ’Ś"GPL"相ĺŚďĽŚĺ®çš„ĺ在ćŻĺ› ä¸şĺŽ†ĺŹ˛ĺŽźĺ› ă€‚ + + "GPL and additional rights" 表示模块ćşĺś¨GPL v2ĺŹä˝“ĺ’ŚMIT许可下双重许可的 + 历史ĺŹä˝“。请不č¦ĺś¨ć–°ä»Łç ä¸ä˝żç”¨ă€‚ + + "Dual MIT/GPL" 表达该模块在GPL v2ĺŹä˝“ć–MIT许可čŻé€‰ć‹©ä¸‹ĺŹŚé‡Ť + 许可的ćŁçˇ®ć–ąĺĽŹă€‚ + + "Dual BSD/GPL" čŻĄć¨ˇĺť—ć ąćŤ®GPL v2ĺŹä˝“ć–BSD许可čŻé€‰ć‹©čż›čˇŚĺŹŚé‡Ť + 许可。 BSD许可čŻçš„确ĺ‡ĺŹä˝“只č˝é€ščż‡ç›¸ĺş”ćşć–‡ä»¶ + ä¸çš„许可čŻäżˇćŻćťĄçˇ®ĺ®šă€‚ + + "Dual MPL/GPL" čŻĄć¨ˇĺť—ć ąćŤ®GPL v2ĺŹä˝“ć–Mozilla Public License + ďĽMPL）选项进行双重许可。 MPL许可čŻçš„确ĺ‡ĺŹä˝“ + 只č˝é€ščż‡ç›¸ĺş”çš„ćşć–‡ä»¶ä¸çš„许可čŻäżˇćŻćťĄçˇ®ĺ®šă€‚ + + "Proprietary" 该模块属于专有许可。ć¤ĺ—符串仅用于专有的第三 + 方模块，不č˝ç”¨äşŽĺś¨ĺ†…ć ¸ć ‘ä¸ĺ…·ćś‰ćşä»Łç 的模块。 + ä»Ąčż™ç§Ťć–ąĺĽŹć ‡č®°çš„ć¨ˇĺť—ĺś¨ĺŠ č˝˝ć—¶äĽšä˝żç”¨'P'ć ‡č®°ć±ˇ + ćź“ĺ†…ć ¸ďĽŚĺą¶ä¸”ĺ†…ć ¸ć¨ˇĺť—ĺŠ č˝˝ĺ™¨ć‹’ç»ťĺ°†čż™äş›ć¨ˇĺť—é“ľćŽĄ + ĺ°ä˝żç”¨EXPORT_SYMBOL_GPLďĽďĽ‰ĺŻĽĺ‡şçš„符号。 + ============================= ============================================= + diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst new file mode 100644 index 000000000000..15c592518194 --- /dev/null +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -0,0 +1,151 @@ +.. _cn_magicnumbers: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` + +如果ćłčŻ„论ć–更新本文的内容，请直接发信ĺ°LKMLă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡äş¤ćµćś‰ĺ›°éšľçš„话，也可 +以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…:: + + ä¸ć–‡ç‰ç»´ćŠ¤č€…： č´ľĺ¨ĺ¨ Jia Wei Wei <harryxiyou@gmail.com> + ä¸ć–‡ç‰çż»čŻ‘者： č´ľĺ¨ĺ¨ Jia Wei Wei <harryxiyou@gmail.com> + ä¸ć–‡ç‰ć ˇčŻ‘者： č´ľĺ¨ĺ¨ Jia Wei Wei <harryxiyou@gmail.com> + +Linux é”术数 +============ + +这个文件ćŻćś‰ĺ…łĺ˝“前使用的é”ćśŻĺ€Ľćł¨ĺ†Śčˇ¨ă€‚ĺ˝“ä˝ ç»™ä¸€ä¸Şç»“ćž„ć·»ĺŠ äş†ä¸€ä¸Şé”ćśŻĺ€ĽďĽŚä˝ äąźĺş”čŻĄćŠŠčż™ä¸Şé”ćśŻĺ€Ľć·»ĺŠ ĺ°čż™ä¸Şć–‡ä»¶ďĽŚĺ› 为ć‘们最好把用于ĺ„种结构的é”术值统一起来。 + +使用é”ćśŻĺ€ĽćťĄäżťćŠ¤ĺ†…ć ¸ć•°ćŤ®ç»“ćž„ćŻä¸€ä¸Şéťžĺ¸¸ĺĄ˝çš„主意。这就ĺ…č®¸ä˝ ĺś¨čżčˇŚćśźćŁ€ćźĄ(a)一个结构ćŻĺ¦ĺ·˛ç»Źč˘«ć”»ĺ‡»ďĽŚć–者(b)ä˝ ĺ·˛ç»Źç»™ä¸€ä¸Şäľ‹čˇŚç¨‹ĺşŹé€ščż‡äş†ä¸€ä¸Şé”™čŻŻçš„ç»“ćž„ă€‚ĺŽä¸€ç§Ťć…况特ĺ«ĺś°ćś‰ç”¨---特ĺ«ćŻĺ˝“ä˝ é€ščż‡ä¸€ä¸Şç©şćŚ‡é’指ĺ‘结构体的时候。ttyćşç ，例如，经常通过特定驱动使用这种方法并且反复地排ĺ—特定方面的结构。 + +使用é”术值的方法ćŻĺś¨ç»“构的开始处声ćŽçš„，如下:: + + struct tty_ldisc { + int magic; + ... + }; + +ĺ˝“ä˝ ä»ĄĺŽç»™ĺ†…ć ¸ć·»ĺŠ ĺ˘žĺĽşĺŠźč˝çš„时候，请éµĺ®čż™ćťˇč§„ĺ™ďĽčż™ć ·ĺ°±äĽščŠ‚çść•°ä¸Ťć¸…çš„č°čŻ•ć—¶é—´ďĽŚç‰ąĺ«ćŻä¸€äş›ĺŹ¤ć€Şçš„ć…况，例如，数组超出čŚĺ›´ĺą¶ä¸”重新写了超出é¨ĺ†ă€‚éµĺ®čż™ä¸Şč§„ĺ™ďĽŚâ€Şčż™äş›ć…况可以被快速地，安全地éżĺ…Ťă€‚ + + Theodore Ts'o + 31 Mar 94 + +给当前的Linux 2.1.55ć·»ĺŠ é”术表。 + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + +现在应该最新的Linux 2.1.112.ĺ› ä¸şĺś¨ç‰ąć€§ĺ†»ç»“ćśźé—´ďĽŚä¸Ťč˝ĺś¨2.2.x前改ĺŹä»»ä˝•ä¸śčĄżă€‚这些条目被数域所排序。 + + Krzysztof G.Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + +ć›´ć–°é”术表ĺ°Linux 2.5.45。ĺšĺĄ˝č¶Ščż‡ç‰ąć€§ĺ†»ç»“，但ćŻćś‰ĺŹŻč˝čżäĽšćś‰ä¸€äş›ć–°çš„é”术值在2.6.x之前融入ĺ°ĺ†…ć ¸ä¸ă€‚ + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + +ć›´ć–°é”术表ĺ°Linux 2.5.74。 + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + +===================== ================ ======================== ========================================== +é”ćśŻć•°ĺŤ ć•°ĺ— ç»“ćž„ 文件 +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +CMAGIC 0x0111 user ``include/linux/a.out.h`` +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` +HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` +DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` +DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` +ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` +PTY_MAGIC 0x5001 ``drivers/char/pty.c`` +PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` +SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` +SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` +X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` +SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` +AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` +TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` +MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` +TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` +USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` +FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` +RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` +CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` +RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` +LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` +RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` +NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` +RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` +ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` +LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` +LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` +CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` +LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` +ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` +CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` +SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` +COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` +I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` +TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` +ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` +GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` +RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` +TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` +M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` +FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` +SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` +SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` +LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` +OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` +M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` +VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` +KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` +PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` +NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` +ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== + + +请注意，在声音记忆管ç†ä¸ä»Ťç„¶ćś‰ä¸€äş›ç‰ąć®Šçš„为每个驱动定义的é”术值。查看include/sound/sndmagic.h来获取他们完整的ĺ—表信ćŻă€‚ĺľĺ¤šOSS声音驱动拥有自己从声卡PCI ID构建的é”术值-他们也没有被ĺ—在这里。 + +IrDAĺ系统也使用了大量的自己的é”术值，查看include/net/irda/irda.h来获取他们完整的信ćŻă€‚ + +HFSćŻĺŹ¦ĺ¤–一个比čľĺ¤§çš„使用é”术值的文件系统-ä˝ ĺŹŻä»Ąĺś¨fs/hfs/hfs.hä¸ć‰ľĺ°ä»–们。 diff --git a/Documentation/translations/zh_CN/process/management-style.rst b/Documentation/translations/zh_CN/process/management-style.rst new file mode 100644 index 000000000000..a181fa56d19e --- /dev/null +++ b/Documentation/translations/zh_CN/process/management-style.rst @@ -0,0 +1,207 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/management-style.rst <managementstyle>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_managementstyle: + +Linuxĺ†…ć ¸ç®ˇç†éŁŽć Ľ +================= + +čż™ćŻä¸€ä¸Şç®€çźçš„文档，描述了Linuxĺ†…ć ¸é¦–é€‰çš„ďĽć–čˇçĽ–的，取决于您问č°ďĽ‰ç®ˇç†éŁŽć Ľă€‚ +ĺ®çš„目的ćŻĺś¨ćźç§Ťç¨‹ĺş¦ä¸ŠĺŹ‚ç…§ :ref:`process/coding-style.rst <codingstyle>` +主č¦ćŻä¸şäş†éżĺ…ŤĺŹŤĺ¤Ťĺ›žç” [#cnf1]_ 相ĺŚďĽć–类似）的问é˘ă€‚ + +管ç†éŁŽć ĽćŻéťžĺ¸¸ä¸ŞäşşĺŚ–的，比简单的编ç éŁŽć Ľč§„ĺ™ć›´éšľä»Ąé‡ŹĺŚ–ďĽŚĺ› ć¤ćś¬ć–‡ćˇŁĺŹŻč˝ä¸Žĺ®ž +é™…ć…况有关，也可č˝ä¸Žĺ®žé™…ć…ĺ†µć— ĺ…łă€‚čµ·ĺťĺ®ćŻä¸€ä¸ŞçŽ©ç¬‘，但这并不意味着ĺ®ĺŹŻč˝ä¸Ť +ćŻçśźçš„ă€‚ä˝ ĺľ—č‡Şĺ·±ĺ†łĺ®šă€‚ + +顺便说一句，在č°ĺ°â€ść ¸ĺżç®ˇç†č€…”时，主č¦ćŻćŠ€ćśŻč´źč´ŁäşşďĽŚč€Śä¸ŤćŻĺś¨ĺ…¬ĺŹ¸ĺ†…é¨čż›čˇŚäĽ +统管ç†çš„äşşă€‚ĺ¦‚ćžśä˝ çľç˝˛äş†é‡‡č´č®˘ĺŤ•ć–č€…ĺŻąä˝ çš„ĺ›˘éźçš„é˘„ç®—ćś‰ä»»ä˝•äş†č§ŁďĽŚä˝ ĺ‡ äąŽč‚Żĺ®š +不ćŻä¸€ä¸Şć ¸ĺżç®ˇç†č€…。这些建议可č˝é€‚用于您，也可č˝ä¸Ťé€‚用于您。 + +首ĺ…，ć‘ĺ»şč®®ä˝ č´äą°â€śé«ć•äşşçš„ä¸ä¸Şäą ćŻâ€ťďĽŚč€Śä¸ŤćŻé…读ĺ®ă€‚ç§äş†ĺ®ďĽŚčż™ćŻä¸€ä¸ŞäĽźĺ¤§çš„ +象ĺľć€§ĺ§żć€ă€‚ + +.. [#cnf1] 本文件并不ćŻé€ščż‡ĺ›žç”é—®é˘ďĽŚč€ŚćŻé€ščż‡č®©ćŹé—®č€…痛苦地ćŽç™˝ďĽŚć‘ä»¬ä¸ŤçźĄé“ + ç”ćˇćŻä»€äąă€‚ + +ä¸Ťç®ˇć€Žć ·ďĽŚčż™é‡ŚćŻďĽš + +.. _decisions: + +1ďĽ‰ĺ†łç– +------- + +每个人é˝č®¤ä¸şç®ˇç†č€…ĺšĺ†łĺ®šďĽŚč€Śä¸”决ç–ĺľé‡Ťč¦ă€‚决定越大越痛苦，管ç†č€…就必须越é«çş§ă€‚ +čż™ĺľćŽćľďĽŚä˝†äş‹ĺ®žĺą¶éťžĺ¦‚ć¤ă€‚ + +游ćŹçš„ĺŤĺ—ćŻ **éżĺ…Ť** ĺšĺ‡şĺ†łĺ®šă€‚尤其ćŻďĽŚĺ¦‚ćžśćś‰äşşĺ‘ŠčŻ‰ä˝ â€śé€‰ć‹©ďĽa）ć–ďĽb）， +ć‘们真的需č¦ä˝ 来ĺšĺ†łĺ®šâ€ťďĽŚä˝ ĺ°±ćŻé™·ĺ…Ąéş»ç¦çš„管ç†č€…ă€‚ä˝ ç®ˇç†çš„äşşćŻ”ä˝ ć›´äş†č§Łç»†čŠ‚ďĽŚ +ć‰€ä»Ąĺ¦‚ćžśä»–ä»¬ćťĄć‰ľä˝ ĺšćŠ€ćśŻĺ†łç–ďĽŚä˝ ĺ®Śč›‹äş†ă€‚ä˝ ćľç„¶ć˛ˇćś‰č˝ĺŠ›ä¸şä»–们ĺščż™ä¸Şĺ†łĺ®šă€‚ + +ďĽćŽ¨č®şďĽšĺ¦‚ćžśä˝ ç®ˇç†çš„äşşä¸ŤćŻ”ä˝ ć›´äş†č§Łç»†čŠ‚ďĽŚä˝ äąźäĽšč˘«ćžç ¸ďĽŚĺ°˝ç®ˇĺŽźĺ› 完全不ĺŚă€‚ +äąźĺ°±ćŻčŻ´ďĽŚä˝ 的工作ćŻé”™çš„，他们应该管ç†ä˝ 的才智） + +所以游ćŹçš„ĺŤĺ—ćŻ **éżĺ…Ť** ĺšĺ‡şĺ†łĺ®šďĽŚč‡łĺ°‘ćŻé‚Łäş›ĺ¤§č€Śç—›č‹¦çš„决定。ĺšä¸€äş›ĺ°Źçš„ +和非结果性的决定ćŻĺľĺĄ˝çš„，并且使您看起来好ĺŹçźĄé“自己在ĺšä»€äąďĽŚć‰€ä»Ąĺ†…ć ¸ç®ˇç†č€… +需č¦ĺšçš„ćŻĺ°†é‚Łäş›ĺ¤§çš„和痛苦的决定ĺŹć那些没有人真ćŁĺ…łĺżçš„ĺ°Źäş‹ć…。 + +这有助于认识ĺ°ä¸€ä¸Şĺ¤§çš„决定和一个小的决定之间的关键区ĺ«ćŻä˝ ćŻĺ¦ĺŹŻä»Ąĺś¨äş‹ĺŽäż®ćŁ +ä˝ çš„ĺ†łĺ®šă€‚ä»»ä˝•ĺ†łĺ®šé˝ĺŹŻä»Ąé€ščż‡ĺ§‹ç»çˇ®äżťĺ¦‚ćžśä˝ é”™äş†ďĽč€Śä¸”ä˝ ä¸€ĺ®šäĽšé”™ďĽ‰ďĽŚä˝ ä»ĄĺŽć€»ćŻ +可以通过回溯来弥补损失。çŞç„¶é—´ďĽŚä˝ ĺ°±č¦ĺšä¸¤ä¸Şć— ĺ…łç´§č¦çš„决定，一个ćŻé”™čŻŻçš„，另 +一个ćŻćŁçˇ®çš„。 + +人们甚至会认为这ćŻçśźćŁçš„领导č˝ĺŠ›ďĽĺ’łďĽŚčˇčŻ´ďĽŚĺ’łďĽ‰ă€‚ + +ĺ› ć¤ďĽŚéżĺ…Ťé‡Ťĺ¤§ĺ†łç–的关键在于éżĺ…Ťĺšé‚Łäş›ć— 法挽回的事ć…。不č¦č˘«ĺĽ•ĺŻĽĺ°ä¸€ä¸Şä˝ ć— ćł• +é€ç¦»çš„角č˝ă€‚čµ°ćŠ•ć— č·Żçš„č€éĽ 可č˝ĺľĺŤ±é™©â€”â€”čµ°ćŠ•ć— č·Żçš„ç®ˇç†č€…真可怜。 + +事实čŻćŽďĽŚç”±äşŽć˛ˇćś‰äşşäĽšć„šč ˘ĺ°č®©ĺ†…ć ¸ç®ˇç†č€…承担巨大的财政责任，所以通常ĺľĺ®ąć“ +ĺ›žćşŻă€‚ć—˘ç„¶ä˝ ä¸ŤĺŹŻč˝ćµŞč´ąćŽ‰ä˝ ć— ćł•ĺżčżçš„ĺ·¨é˘ťčµ„é‡‘ďĽŚä˝ ĺ”Żä¸€ĺŹŻä»Ąĺ›žćşŻçš„ĺ°±ćŻćŠ€ćśŻĺ†łç–， +而回溯ĺľĺ®ąć“：只č¦ĺ‘ŠčŻ‰ĺ¤§ĺ®¶ä˝ ćŻä¸Şä¸Ťç§°čŚçš„傻瓜，说对不起，然ĺŽć’¤é”€ä˝ ĺŽ»ĺą´č®©ĺ« +人所ĺšçš„ćŻ«ć— ä»·ĺ€Ľçš„ĺ·Ąä˝śă€‚çŞç„¶é—´ďĽŚä˝ 一年前ĺšçš„决定不在ćŻä¸€ä¸Şé‡Ťĺ¤§çš„ĺ†łĺ®šďĽŚĺ› ä¸ş +ĺ®ĺľĺ®ąć“被推翻。 + +事实čŻćŽďĽŚćś‰äş›äşşĺŻąćŽĄĺŹ—čż™ç§Ťć–ąćł•ćś‰ĺ›°éšľďĽŚĺŽźĺ› ćś‰ä¸¤ä¸ŞďĽš + + - ć‰żč®¤ä˝ ćŻä¸Şç™˝ç—´ćŻ”看起来更难。ć‘们é˝ĺ–ść¬˘äżťćŚĺ˝˘č±ˇďĽŚĺś¨ĺ…¬ĺ…±ĺśşĺčŻ´ä˝ é”™äş†ćś‰ć—¶ + 确实ĺľéšľă€‚ + - ĺ¦‚ćžśćś‰äşşĺ‘ŠčŻ‰ä˝ ďĽŚä˝ ĺŽ»ĺą´ć‰€ĺšçš„工作ç»ç©¶ćŻä¸Ťĺ€Ľĺľ—的，那äąĺŻąé‚Łäş›ĺŹŻć€śçš„低级工 + 程ĺ¸ćťĄčŻ´äąźćŻĺľĺ›°éšľçš„，虽然实际的 **工作** ĺľĺ®ąć“ĺ é™¤ďĽŚä˝†ä˝ ĺŹŻč˝ĺ·˛ç»Źä¸ŤĺŹŻ + 挽回地失去了工程ĺ¸çš„信任。记住：“不可撤销”ćŻć‘们一开始就试图éżĺ…Ťçš„， + č€Śä˝ çš„ĺ†łĺ®šç»ç©¶ćŻä¸€ä¸Şé‡Ťĺ¤§çš„决定。 + +令人欣慰的ćŻďĽŚčż™ä¸¤ä¸ŞĺŽźĺ› é˝ĺŹŻä»Ąé€ščż‡é˘„ĺ…ć‰żč®¤ä˝ ć˛ˇćś‰ä»»ä˝•çşżç´˘ďĽŚćŹĺ‰Ťĺ‘ŠčŻ‰äşşä»¬ä˝ çš„ +决定完全ćŻĺťćĄçš„，而且可č˝ćŻé”™čŻŻçš„äş‹ć…来有ć•ĺś°çĽ“č§Łă€‚ä˝ ĺş”čŻĄĺ§‹ç»äżťç•™ć”ąĺŹä¸»ć„Ź +çš„ćťĺ©ďĽŚĺą¶č®©äşşä»¬ **意识** ĺ°čż™ä¸€ç‚ąă€‚ĺ˝“ä˝ **čżć˛ˇćś‰** ĺščż‡çśźćŁć„šč ˘çš„äş‹ć…çš„ć—¶ +候，承认自己ćŻć„šč ˘çš„č¦ĺ®ąć“得多。 + +然ĺŽďĽŚĺ˝“ĺ®çśźçš„被čŻćŽćŻć„šč ˘çš„ć—¶ĺ€™ďĽŚäşşä»¬ĺ°±č˝¬ĺŠ¨ä»–ä»¬çš„çśĽçŹ čŻ´â€śĺ“Žĺ‘€ďĽŚä¸‹ć¬ˇä¸Ťč¦äş†â€ťă€‚ + +这种对不称čŚçš„ĺ…发ĺ¶äşşçš„承认，也可č˝ä˝żçśźćŁĺščż™éˇąĺ·Ąä˝śçš„人也会三思ćŻĺ¦ĺ€Ľĺľ—ĺšă€‚ +毕竟，如果他们不确定这ćŻĺ¦ćŻä¸€ä¸ŞĺĄ˝ä¸»ć„ŹďĽŚä˝ 肯定不应该通过ĺ‘他们保čŻä»–ä»¬ć‰€ĺš +的工作将会进入ďĽĺ†…ć ¸ďĽ‰éĽ“ĺŠ±ä»–ä»¬ă€‚ĺś¨ä»–ä»¬ĺĽ€ĺ§‹ä¸€éˇąĺ·¨ĺ¤§çš„ĺŠŞĺŠ›äą‹ĺ‰ŤďĽŚč‡łĺ°‘č®©ä»–ä»¬ä¸‰ +思而ĺŽčˇŚă€‚ + +č®°ä˝ŹďĽšä»–ä»¬ćś€ĺĄ˝ćŻ”ä˝ ć›´äş†č§Łç»†čŠ‚ďĽŚč€Śä¸”ä»–ä»¬é€šĺ¸¸č®¤ä¸şä»–ä»¬ĺŻąćŻŹä»¶äş‹é˝ćś‰ç”ćˇă€‚作为一 +个管ç†č€…ďĽŚä˝ č˝ĺšçš„最好的事ć…不ćŻçŚčľ“自信，而ćŻĺŻąä»–们所ĺšçš„äş‹ć…进行ĺĄĺş·çš„批 +ĺ¤ć€§ć€ťč€ă€‚ + +顺便说一句，另一种éżĺ…Ťĺšĺ‡şĺ†łĺ®šçš„ć–ąćł•ćŻçś‹čµ·ćťĄĺľĺŹŻć€śçš„抱怨 “ć‘们不č˝ä¸¤č€…ĺ…Ľ +ĺľ—ĺ—？” 相信ć‘，ĺ®ćŻćś‰ć•çš„。如果不清楚哪种方法更好，他们最ç»äĽšĺĽ„清楚的。 +最ç»çš„ç”ćˇĺŹŻč˝ćŻä¸¤ä¸Şĺ›˘éźé˝äĽšĺ› 为这种ć…况而感ĺ°ć˛®ä¸§ďĽŚä»Ąč‡łäşŽä»–们放ĺĽäş†ă€‚ + +čż™ĺ¬čµ·ćťĄĺŹćŻä¸€ä¸Şĺ¤±č´ĄďĽŚä˝†čż™é€šĺ¸¸ćŻä¸€ä¸Şčżąč±ˇďĽŚčˇ¨ćŽä¸¤ä¸Şéˇąç›®é˝ćś‰é—®é˘ďĽŚč€ŚĺŹ‚ä¸Žĺ…¶ä¸ +的人不č˝ĺšĺ†łĺ®šçš„ĺŽźĺ› ćŻä»–们é˝ćŻé”™čŻŻçš„ă€‚ä˝ ćś€ç»äĽšé—»ĺ°çŽ«ç‘°çš„ĺ‘łé“ďĽŚä˝ éżĺ…Ťäş†ĺŹ¦ä¸€ +ä¸Şä˝ ćś¬ĺŹŻä»Ąćžç ¸çš„决定。 + +2）人 +----- + +大多数人é˝ćŻç™˝ç—´ďĽŚĺšä¸€ĺŤç®ˇç†č€…ć„Źĺ‘łçť€ä˝ ĺż…éˇ»ĺ¤„ç†ĺĄ˝čż™ä»¶äş‹ďĽŚäąźč®¸ć›´é‡Ťč¦çš„ćŻ, +**他们** 必须处ç†ĺĄ˝ä˝ 。 + +事实čŻćŽďĽŚč™˝ç„¶ĺľĺ®ąć“çş ćŁćŠ€ćśŻé”™čŻŻďĽŚä˝†ä¸Ťĺ®ąć“çş ćŁäşşć Ľéšśç˘Ťă€‚ä˝ ĺŹŞč˝ĺ’Śä»–们的和 +ä˝ çš„ďĽäşşć Ľéšśç˘ŤďĽ‰ĺ…±ĺ¤„。 + +但ćŻďĽŚä¸şäş†ĺšĺĄ˝ä˝śä¸şĺ†…ć ¸ç®ˇç†č€…的准备，最好记住不č¦ç§ćŽ‰ä»»ä˝•ćˇĄć˘ďĽŚä¸Ťč¦č˝°ç‚¸ä»»ä˝• +ć— čľśçš„ćť‘ć°‘ďĽŚäąźä¸Ťč¦ç–Źčżśĺ¤Şĺ¤šçš„ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘。事实čŻćŽďĽŚç–ŹčżśäşşćŻç›¸ĺ˝“容ć“的，而 +亲近一个疏远的人ćŻĺľéšľçš„ă€‚ĺ› ć¤ďĽŚâ€śç–Źčżśâ€ťç«‹ĺŤłĺ±žäşŽâ€śä¸ŤĺŹŻé€†â€ťçš„čŚç•´ďĽŚĺą¶ć ąćŤ® +:ref:`decisions` ć为绝不可以ĺšçš„äş‹ć…。 + +čż™é‡ŚĺŹŞćś‰ĺ‡ ä¸Şç®€ĺŤ•çš„č§„ĺ™ďĽš + + (1) 不č¦ĺŹ«äşşç¬¨č›‹ďĽč‡łĺ°‘不č¦ĺś¨ĺ…¬ĺ…±ĺśşĺ） + (2) ĺ¦äą 如何在ĺżč®°č§„ĺ™(1)ć—¶é“ć‰ + +é—®é˘ĺś¨äşŽ #1 ĺľĺ®ąć“去ĺšďĽŚĺ› ä¸şä˝ ĺŹŻä»Ąç”¨ć•°ç™ľä¸‡ç§Ťä¸ŤĺŚçš„ć–ąĺĽŹčŻ´â€śä˝ ćŻä¸€ä¸Şç¬¨č›‹â€ť [#cnf2]_ +有时甚至没有意识ĺ°ďĽŚč€Śä¸”ĺ‡ äąŽć€»ćŻĺ¸¦çť€ä¸€ç§Ťç™˝çĺŚ–çš„äżˇĺżµďĽŚč®¤ä¸şä˝ ćŻĺŻąçš„。 + +ä˝ č¶Šçˇ®äżˇč‡Şĺ·±ćŻĺŻąçš„ďĽč®©ć‘们面对现实ĺ§ďĽŚä˝ ĺŹŻä»ĄćŠŠĺ‡ äąŽć‰€ćś‰äşşé˝ç§°ä¸şĺťŹäşşďĽŚč€Śä¸”ä˝ +经常ćŻĺŻąçš„），事ĺŽé“ć‰ĺ°±č¶Šéšľă€‚ + +č¦č§Łĺ†łć¤é—®é˘ďĽŚć‚¨ĺ®žé™…上只有两个选项： + + - 非常擅长é“ć‰ + - 把“ç±â€ťĺť‡ĺŚ€ĺś°ć•ŁĺĽ€ďĽŚć˛ˇćś‰äşşäĽšçśźćŁć„źč§‰ĺ°č‡Şĺ·±č˘«ä¸Ťĺ…¬ĺąłĺś°çž„准了。让ĺ®ćś‰č¶łĺ¤źçš„ + ĺ›é€ 性，他们甚至可č˝äĽšč§‰ĺľ—好笑。 + +选择永远保ćŚç¤Ľč˛ŚćŻä¸Ťĺ在的。没有人会相信一个如ć¤ćŽćľĺś°éšč—Źäş†ä»–ä»¬çśźĺ®žć€§ć Ľçš„äşşă€‚ + +.. [#cnf2] 保罗·西蒙演唱了“离开ç±äşşçš„50ç§Ťć–ąćł•â€ťďĽŚĺ› ä¸şĺť¦çŽ‡ĺś°čŻ´ďĽŚâ€śĺ‘ŠčŻ‰ĺĽ€ĺŹ‘č€… + 他们ćŻD*CKHEAD" çš„100万种方法é˝ć— 法确认。但ć‘确信他已经这äąćłäş†ă€‚ + +3）人2 - 好人 +------------- + +虽然大多数人é˝ćŻç™˝ç—´ďĽŚä˝†ä¸Ťĺą¸çš„ćŻďĽŚćŤ®ć¤ćŽ¨č®şä˝ äąźćŻç™˝ç—´ďĽŚĺ°˝ç®ˇć‘们é˝č‡Şć‘感觉良 +好，ć‘们比普通人更好ďĽč®©ć‘们面对现实ĺ§ďĽŚć˛ˇćś‰äşşç›¸äżˇä»–们ćŻć™®é€šäşşć–低于普通人）， +ć‘们也应该承认ć‘们不ćŻćś€é”‹ĺ©çš„ĺ€ďĽŚč€Śä¸”äĽšćś‰ĺ…¶ä»–äşşćŻ”ä˝ ć›´ä¸ŤĺŹç™˝ç—´ă€‚ + +有些人对čŞćŽäşşĺŹŤĺş”不好。其他人ĺ©ç”¨ĺ®ä»¬ă€‚ + +ä˝śä¸şĺ†…ć ¸ç»´ćŠ¤äşşĺ‘，确保您在第二组ä¸ă€‚ćŽĄĺŹ—ä»–ä»¬ďĽŚĺ› ä¸şä»–ä»¬äĽšč®©ä˝ çš„ĺ·Ąä˝ść›´ĺ®ąć“。 +特ĺ«ćŻďĽŚä»–们č˝ĺ¤źä¸şä˝ ĺšĺ†łĺ®šďĽŚčż™ĺ°±ćŻć¸¸ćŹçš„ĺ…¨é¨ĺ†…容。 + +ć‰€ä»Ąĺ˝“ä˝ ĺŹ‘çŽ°ä¸€ä¸ŞćŻ”ä˝ čŞćŽçš„人时，就顺其自然ĺ§ă€‚ä˝ çš„ç®ˇç†čŚč´Łĺś¨ĺľĺ¤§ç¨‹ĺş¦ä¸ŠĺŹć +了“ĺ¬čµ·ćťĄĺŹćŻä¸ŞĺĄ˝ä¸»ć„Źâ€”—去尝试ĺ§â€ťďĽŚć–者“ĺ¬čµ·ćťĄä¸Ťé”™ďĽŚä˝†ćŻXXXĺ‘˘ďĽźâ€ťâ€śă€‚ç¬¬äşŚä¸Şç‰ +本尤其ćŻä¸€ä¸ŞĺľĺĄ˝çš„方法，č¦äąĺ¦äą 一些关于“XXX”的新东西，č¦äąé€ščż‡ćŚ‡ĺ‡şä¸€äş›čŞćŽ +人没有ćłĺ°çš„东西来ćľĺľ—更具管ç†ć€§ă€‚ć— č®şĺ“Şç§Ťć…ĺ†µďĽŚä˝ é˝äĽščµ˘ă€‚ + +č¦ćł¨ć„Źçš„一件事ćŻč®¤čŻ†ĺ°ä¸€ä¸Şé˘†ĺźźçš„äĽźĺ¤§ä¸Ťä¸€ĺ®šäĽšč˝¬ĺŚ–ä¸şĺ…¶ä»–é˘†ĺźźă€‚ć‰€ä»Ąä˝ ĺŹŻč˝äĽšĺ‘ +特定的方ĺ‘ĺşćż€äşşä»¬ďĽŚä˝†č®©ć‘们面对现实ĺ§ďĽŚä»–们可č˝ć“…长他们所ĺšçš„äş‹ć…，而且对 +其他事ć…é˝ĺľĺ·®ĺŠ˛ă€‚好ć¶ćŻćŻďĽŚäşşä»¬ĺľ€ĺľ€äĽšč‡Şç„¶č€Śç„¶ĺś°é‡Ťć‹ľä»–们擅长的东西，所以当 +ä˝ ĺ‘ćźä¸Şć–ąĺ‘ĺşćż€ä»–ä»¬ć—¶ďĽŚä˝ ĺą¶ä¸ŤćŻĺś¨ĺšä¸ŤĺŹŻé€†č˝¬çš„äş‹ć…，只ćŻä¸Ťč¦ç”¨ĺŠ›ćŽ¨ă€‚ + +4）责备 +------- + +äş‹ć…会出问é˘çš„ďĽŚäşşä»¬ĺ¸Śćś›ĺŽ»č´Łĺ¤‡äşşă€‚č´´ć ‡çľďĽŚä˝ ĺ°±ćŻĺŹ—责备的人。 + +事实上，接受责备并不难，尤其ćŻĺ˝“人们意识ĺ°čż™ä¸Ť **ĺ…¨ćŻ** ä˝ çš„čż‡é”™ć—¶ă€‚čż™č®©ć‘ +们找ĺ°äş†ć‰żć‹…责任的最佳方式：为ĺ«äşşć‰żć‹…čż™ä»¶äş‹ă€‚ä˝ äĽšć„źč§‰ĺľĺĄ˝ďĽŚä»–们会感觉ĺľĺĄ˝ďĽŚ +没有受ĺ°ćŚ‡č´Ł. é‚Łč°ďĽŚĺ¤±ĺŽ»äş†ä»–们的全é¨36GB色ć…ć”¶č—Źçš„äşşďĽŚĺ› ä¸şä˝ çš„ć— č˝ĺ°†ĺ‹‰ĺĽşć‰ż +č®¤ďĽŚä˝ č‡łĺ°‘ć˛ˇćś‰čŻ•ĺ›ľé€éżč´Łä»»ă€‚ + +然ĺŽč®©çśźćŁćžç ¸äş†çš„开发人ĺ‘ďĽĺ¦‚ćžśä˝ č˝ć‰ľĺ°ä»–们）ç§ä¸‹çźĄé“他们ćžç ¸äş†ă€‚不仅ćŻä¸ş +了将来可以éżĺ…ŤďĽŚč€Śä¸”为了让他们知é“ä»–ä»¬ć¬ ä˝ ä¸€ä¸Şäşşć…。而且，也许更重č¦çš„ćŻďĽŚ +他们也可č˝ćŻč˝ĺ¤źč§Łĺ†łé—®é˘çš„äşşă€‚ĺ› ä¸şďĽŚč®©ć‘们面对现实ĺ§ďĽŚč‚Żĺ®šä¸ŤćŻä˝ 。 + +承担责任也ćŻä˝ 首ĺ…ć为管ç†č€…çš„ĺŽźĺ› ă€‚čż™ćŻč®©äşşä»¬äżˇä»»ä˝ ďĽŚč®©ä˝ čŽ·ĺľ—ć˝śĺś¨çš„čŤŁč€€çš„ +一é¨ĺ†ďĽŚĺ› ä¸şä˝ ĺ°±ćŻé‚Łä¸ŞäĽščŻ´â€ść‘ćžç ¸äş†â€ťçš„äşşă€‚ĺ¦‚ćžśä˝ ĺ·˛ç»ŹéµĺľŞäş†ä»Ąĺ‰Ťçš„规ĺ™ďĽŚä˝ 现 +在已经ĺľć“…长说了。 + +5）应éżĺ…Ťçš„äş‹ć… +--------------- + +有一件事人们甚至比被称为“笨蛋”更讨厌，那就ćŻĺś¨ä¸€ä¸ŞçĄžĺśŁçš„声音ä¸č˘«ç§°ä¸şâ€śç¬¨č›‹â€ťă€‚ +ç¬¬ä¸€ä¸Şä˝ ĺŹŻä»Ąé“ć‰ďĽŚç¬¬äşŚä¸Şä˝ 不会真ćŁĺľ—ĺ°ćśşäĽšă€‚ĺŤłä˝żä˝ ĺšĺľ—ĺľĺĄ˝ďĽŚä»–们也可č˝ä¸Ťĺ†Ť +倾ĺ¬ă€‚ + +ć‘们é˝č®¤ä¸şč‡Şĺ·±ćŻ”ĺ«äşşĺĽşďĽŚčż™ć„Źĺ‘łçť€ĺ˝“ĺ«äşşčŁ…腔作势时，这会让ć‘们ĺľćĽç«ă€‚ä˝ äąźč®¸ +在é“ĺľ·ĺ’Ść™şĺŠ›ä¸ŠćŻ”ä˝ ĺ‘¨ĺ›´çš„ćŻŹä¸Şäşşé˝äĽč¶ŠďĽŚä˝†ä¸Ťč¦čŻ•ĺ›ľĺ¤ŞćŽćľďĽŚé™¤éťžä˝ 真的打算激怒 +ćźäşş [#cnf3]_ + +ĺŚć ·ďĽŚä¸Ťč¦ĺŻąäş‹ć…太客气ć–太微妙。礼貌ĺľĺ®ąć“č˝ĺľ—č˝čŠ±ćµć°´ďĽŚćŠŠé—®é˘éšč—Źčµ·ćťĄďĽŚ +ćŁĺ¦‚他们所说，“在互č”网上，没人č˝ĺ¬ĺ°ä˝ çš„ĺ«č“„。”用一个钝器把这一点锤进去， +ĺ› ä¸şä˝ ä¸Ťč˝çśźçš„äľťéť ĺ«äşşćťĄčŽ·ĺľ—ä˝ çš„č§‚ç‚ąă€‚ + +一些幽é»ĺŹŻä»Ąĺ¸®ĺŠ©çĽ“和直率和é“德化。过度ĺ°čŤ’谬的地ćĄďĽŚĺŹŻä»ĄçŚčľ“一个观点，而不 +会让接受者感ĺ°ç—›č‹¦ďĽŚä»–们只ćŻč®¤ä¸şä˝ ćŻć„šč ˘çš„ă€‚ĺ› ć¤ďĽŚĺ®ĺŹŻä»Ąĺ¸®ĺŠ©ć‘们摆脱对批评 +的个人ĺżç†éšśç˘Ťă€‚ + +.. [#cnf3] ćŹç¤şďĽšä¸Žä˝ 的工作没有直接关系的网络新闻组ćŻć¶é™¤ä˝ 对他人不满的好 + 方法。ĺ¶ĺ°”写些侮辱性的帖ĺďĽŚć‰“ä¸Şĺ–·ĺšŹďĽŚč®©ä˝ çš„ć…绪得ĺ°ĺ‡€ĺŚ–。ĺ«ćŠŠç‰˘éŞšĺ¸¦ĺ›žĺ®¶ + +6）为什äąćŻć‘？ +--------------- + +ć—˘ç„¶ä˝ çš„ä¸»č¦č´Łä»»äĽĽäąŽćŻä¸şĺ«äşşçš„错误承担责任，并且让ĺ«äşşç—›č‹¦ĺś°ćŽç™˝ä˝ ćŻä¸Ťç§°čŚ +的，那äąćľč€Ść“č§çš„é—®é˘äą‹ä¸€ĺ°±ĺŹć了为什äąé¦–ĺ…č¦čż™ć ·ĺšă€‚ + +首ĺ…ďĽŚč™˝ç„¶ä˝ ĺŹŻč˝äĽšć–可č˝ä¸ŤäĽšĺ¬ĺ°ĺŤĺ‡ ĺ˛ĺĄłĺ©ďĽć–ç”·ĺ©ďĽŚč®©ć‘们不č¦ĺś¨čż™é‡ŚčŻ„ĺ¤ć– +性ĺ«ć§č§†ďĽ‰ć•˛ä˝ çš„ć›´čˇŁĺ®¤é—¨ďĽŚä˝ äĽšĺľ—ĺ°ä¸€ä¸Şĺ·¨ĺ¤§çš„个人ć就感为“负责”。ĺ«ä»‹ć„Źä˝ çśź +的在领导ĺ«äşşďĽŚä˝ č¦č·źä¸Šĺ«äşşďĽŚĺ°˝ĺŹŻč˝ĺż«ĺś°čż˝čµ¶ä»–们。每个人é˝äĽšč®¤ä¸şä˝ ćŻč´źč´Łäşşă€‚ + +ĺ¦‚ćžśä˝ ĺŹŻä»Ąĺšĺ°čż™ä¸ŞďĽŚ čż™ćŻä¸ŞäĽźĺ¤§çš„ĺ·Ąä˝śďĽ diff --git a/Documentation/translations/zh_CN/process/programming-language.rst b/Documentation/translations/zh_CN/process/programming-language.rst new file mode 100644 index 000000000000..51fd4ef48ea1 --- /dev/null +++ b/Documentation/translations/zh_CN/process/programming-language.rst @@ -0,0 +1,41 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/programming-language.rst <programming_language>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_programming_language: + +程序设计čŻč¨€ +============ + +ĺ†…ć ¸ćŻç”¨CčŻč¨€ [c-language]_ çĽ–ĺ†™çš„ă€‚ć›´ĺ‡†çˇ®ĺś°čŻ´ďĽŚĺ†…ć ¸é€šĺ¸¸ćŻç”¨ ``gcc`` [gcc]_ +在 ``-std=gnu89`` [gcc-c-dialect-options]_ 下编译的：ISO C90çš„ GNU ć–ąč¨€ďĽ +包括一些C99特性） + +这种方言包ĺ«ĺŻąčŻč¨€ [gnu-extensions]_ 的许多扩展，当然，ĺ®ä»¬č®¸ĺ¤šé˝ĺś¨ĺ†…ć ¸ä¸ä˝żç”¨ă€‚ + +对于一些体系结构，有一些使用 ``clang`` [clang]_ ĺ’Ś ``icc`` [icc]_ çĽ–čŻ‘ĺ†…ć ¸ +的支ćŚďĽŚĺ°˝ç®ˇĺś¨çĽ–写ć¤ć–‡ćˇŁć—¶čżć˛ˇćś‰ĺ®Ść，仍需č¦ç¬¬ä¸‰ć–ąčˇĄä¸ă€‚ + +属性 +---- + +ĺś¨ć•´ä¸Şĺ†…ć ¸ä¸ä˝żç”¨çš„一个常č§ć‰©ĺ±•ćŻĺ±žć€§ďĽattributes） [gcc-attribute-syntax]_ +属性ĺ…许将实现定义的čŻäą‰ĺĽ•ĺ…ĄčŻč¨€ĺ®žä˝“ďĽĺ¦‚ĺŹé‡Źă€ĺ‡˝ć•°ć–ç±»ĺž‹ďĽ‰ďĽŚč€Ść— éś€ĺŻąčŻč¨€čż›čˇŚ +重大的čŻćł•ć›´ć”ąďĽäľ‹ĺ¦‚ć·»ĺŠ ć–°ĺ…łé”®ĺ—） [n2049]_ + +在ćźäş›ć…况下，属性ćŻĺŹŻé€‰çš„ďĽĺŤłä¸Ťć”ŻćŚčż™äş›ĺ±žć€§çš„编译器仍然应该生ććŁçˇ®çš„代ç ， +即使其速度čľć…˘ć–执行的编译时检查/诊ć–次数不够） + +ĺ†…ć ¸ĺ®šäą‰äş†äĽŞĺ…łé”®ĺ—ďĽäľ‹ĺ¦‚， ``pure`` ），而不ćŻç›´ćŽĄä˝żç”¨GNU属性čŻćł•ďĽäľ‹ĺ¦‚, +``__attribute__((__pure__))`` ），以检测可以使用哪些关键ĺ—ĺ’Ś/ć–缩çźä»Łç , 具体 +čŻ·ĺŹ‚é… ``include/linux/compiler_attributes.h`` + +.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards +.. [gcc] https://gcc.gnu.org +.. [clang] https://clang.llvm.org +.. [icc] https://software.intel.com/en-us/c-compilers +.. [gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html +.. [gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html +.. [gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html +.. [n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf diff --git a/Documentation/translations/zh_CN/stable_api_nonsense.txt b/Documentation/translations/zh_CN/process/stable-api-nonsense.rst index a2b27fab382c..b4ddb6e88d9d 100644 --- a/Documentation/translations/zh_CN/stable_api_nonsense.txt +++ b/Documentation/translations/zh_CN/process/stable-api-nonsense.rst @@ -1,26 +1,18 @@ -Chinese translated version of Documentation/process/stable-api-nonsense.rst +.. _cn_stable_api_nonsense: -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have problem -communicating in English you can also ask the Chinese maintainer for help. -Contact the Chinese maintainer, if this translation is outdated or there -is problem with translation. +.. include:: ../disclaimer-zh_CN.rst -Maintainer: Greg Kroah-Hartman <greg@kroah.com> -Chinese maintainer: TripleX Chung <zhongyu@18mail.cn> ---------------------------------------------------------------------- -Documentation/process/stable-api-nonsense.rst çš„ä¸ć–‡çż»čŻ‘ +:Original: :ref:`Documentation/process/stable-api-nonsense.rst + <stable_api_nonsense>` -如果ćłčŻ„论ć–更新本文的内容，请直接č”çł»ĺŽźć–‡ćˇŁçš„ç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡ -交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 -译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 +译者:: -英文ç‰ç»´ćŠ¤č€…： Greg Kroah-Hartman <greg@kroah.com> -ä¸ć–‡ç‰ç»´ćŠ¤č€…： 钟宇 TripleX Chung <zhongyu@18mail.cn> -ä¸ć–‡ç‰çż»čŻ‘者： 钟宇 TripleX Chung <zhongyu@18mail.cn> -ä¸ć–‡ç‰ć ˇčŻ‘者： ćťŽéł Li Yang <leoli@freescale.com> -以下为ćŁć–‡ ---------------------------------------------------------------------- + ä¸ć–‡ç‰ç»´ćŠ¤č€…： 钟宇 TripleX Chung <xxx.phy@gmail.com> + ä¸ć–‡ç‰çż»čŻ‘者： 钟宇 TripleX Chung <xxx.phy@gmail.com> + ä¸ć–‡ç‰ć ˇčŻ‘者： ćťŽéł Li Yang <leoyang.li@nxp.com> + +Linux ĺ†…ć ¸é©±ĺŠ¨ćŽĄĺŹŁ +================== 写作本文档的目的，ćŻä¸şäş†č§Łé‡Šä¸şä»€äąLinux既没有二进ĺ¶ĺ†…ć ¸ćŽĄĺŹŁďĽŚäąźć˛ˇćś‰ç¨łĺ®š çš„ĺ†…ć ¸ćŽĄĺŹŁă€‚čż™é‡Ść‰€čŻ´çš„ĺ†…ć ¸ćŽĄĺŹŁďĽŚćŻćŚ‡ĺ†…ć ¸é‡Śçš„ćŽĄĺŹŁďĽŚč€Śä¸ŤćŻĺ†…ć ¸ĺ’Śç”¨ć·ç©şé—´ @@ -59,18 +51,22 @@ Linuxč˝ć为强壮，稳定，ć熟的操作系统，这也ćŻä˝ 最开始选 -------------- ĺ‡ĺ¦‚ć‘ä»¬ćś‰ä¸€ä¸Şç¨łĺ®šçš„ĺ†…ć ¸ćşä»Łç 接口，那äąč‡Şç„¶č€Śç„¶çš„，ć‘们就拥有了稳定的 二进ĺ¶ćŽĄĺŹŁďĽŚćŻčż™ć ·çš„ĺ—？错。让ć‘们看看关于Linuxĺ†…ć ¸çš„ĺ‡ ç‚ąäş‹ĺ®žďĽš + - 取决于所用的C编译器的ç‰ćś¬ďĽŚä¸ŤĺŚçš„ĺ†…ć ¸ć•°ćŤ®ç»“ćž„é‡Śçš„ç»“ćž„ä˝“çš„ĺŻąé˝ć–ą -式会有差ĺ«ďĽŚä»Łç ä¸ä¸ŤĺŚĺ‡˝ć•°çš„čˇ¨çŽ°ĺ˝˘ĺĽŹäąźä¸Ťä¸€ć ·ďĽĺ‡˝ć•°ćŻä¸ŤćŻč˘«inline编译取 -决于编译器行为）。不ĺŚçš„函数的表现形式并不重č¦ďĽŚä˝†ćŻć•°ćŤ®ç»“构内é¨çš„ĺŻąé˝ -方式ĺľĺ…łé”®ă€‚ + 式会有差ĺ«ďĽŚä»Łç ä¸ä¸ŤĺŚĺ‡˝ć•°çš„čˇ¨çŽ°ĺ˝˘ĺĽŹäąźä¸Ťä¸€ć ·ďĽĺ‡˝ć•°ćŻä¸ŤćŻč˘«inline + 编译取决于编译器行为）。不ĺŚçš„函数的表现形式并不重č¦ďĽŚä˝†ćŻć•°ćŤ® + 结构内é¨çš„对é˝ć–ąĺĽŹĺľĺ…łé”®ă€‚ + - ĺŹ–ĺ†łäşŽĺ†…ć ¸çš„é…Ťç˝®é€‰éˇąďĽŚä¸ŤĺŚçš„é€‰éˇąäĽšč®©ĺ†…ć ¸çš„ĺľĺ¤šä¸śčĄżĺŹ‘生改ĺŹďĽš + - ĺŚä¸€ä¸Şç»“构体可č˝ĺŚ…ĺ«ä¸ŤĺŚçš„ćĺ‘ĺŹé‡Ź - 有的函数可č˝ć ąćś¬ä¸ŤäĽšč˘«ĺ®žçŽ°ďĽćŻ”如编译的时候没有选择SMPć”ŻćŚ -，一些é”函数就会被定义ć空函数）。 + 一些é”函数就会被定义ć空函数）。 - ĺ†…ć ¸ä˝żç”¨çš„ĺ†…ĺ会以不ĺŚçš„方式对é˝ďĽŚčż™ĺŹ–决于不ĺŚçš„ĺ†…ć ¸é…Ťç˝®é€‰ -项。 + 项。 + - Linux可以在ĺľĺ¤šçš„不ĺŚä˝“系结构的处ç†ĺ™¨ä¸ŠčżčˇŚă€‚在ćźä¸Şä˝“系结构上编 -译好的二进ĺ¶é©±ĺŠ¨ç¨‹ĺşŹďĽŚä¸ŤĺŹŻč˝ĺś¨ĺŹ¦ĺ¤–一个体系结构上ćŁçˇ®çš„čżčˇŚă€‚ + 译好的二进ĺ¶é©±ĺŠ¨ç¨‹ĺşŹďĽŚä¸ŤĺŹŻč˝ĺś¨ĺŹ¦ĺ¤–一个体系结构上ćŁçˇ®çš„čżčˇŚă€‚ ĺŻąäşŽä¸€ä¸Şç‰ąĺ®šçš„ĺ†…ć ¸ďĽŚć»ˇč¶łčż™äş›ćťˇä»¶ĺą¶ä¸ŤéšľďĽŚä˝żç”¨ĺŚä¸€ä¸ŞC编译器和ĺŚć ·çš„ĺ†…ć ¸é…Ť 置选项来编译驱动程序模块就可以了。这对于给一个特定Linux发ĺ¸çš„特定ç‰ćś¬ćŹ @@ -90,7 +86,7 @@ Linuxč˝ć为强壮，稳定，ć熟的操作系统，这也ćŻä˝ 最开始选 ĺ¦‚ćžśćś‰äşşä¸Ťĺ°†ä»–çš„ĺ†…ć ¸é©±ĺŠ¨ç¨‹ĺşŹďĽŚć”ľĺ…Ąĺ…¬ç‰ĺ†…ć ¸çš„ćşä»Łç ć ‘ďĽŚč€ŚĺŹćłč®©é©±ĺŠ¨ç¨‹ĺşŹ 一直保ćŚĺś¨ćś€ć–°çš„ĺ†…ć ¸ä¸ĺŹŻç”¨ďĽŚé‚Łäąčż™ä¸ŞčŻťé˘ĺ°†äĽšĺŹĺľ—没完没了。 - ĺ†…ć ¸ĺĽ€ĺŹ‘ćŻćŚç»č€Śä¸”快节奏的，从来é˝ä¸ŤäĽšć…˘ä¸‹ćťĄă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ĺś¨ĺ˝“ĺ‰ŤćŽĄĺŹŁä¸ +ĺ†…ć ¸ĺĽ€ĺŹ‘ćŻćŚç»č€Śä¸”快节奏的，从来é˝ä¸ŤäĽšć…˘ä¸‹ćťĄă€‚ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘ĺś¨ĺ˝“ĺ‰ŤćŽĄĺŹŁä¸ ć‰ľĺ°bug，ć–者找ĺ°ć›´ĺĄ˝çš„实现方式。一旦发现这些，他们就ĺľĺż«äĽšĺŽ»äż®ć”ąĺ˝“前的 接口。修改接口意味着，函数ĺŤĺŹŻč˝äĽšć”ąĺŹďĽŚç»“构体可č˝č˘«ć‰©ĺ……ć–者ĺ 减，函数 的参数也可č˝ĺŹ‘生改ĺŹă€‚ä¸€ć—¦ćŽĄĺŹŁč˘«äż®ć”ąďĽŚĺ†…ć ¸ä¸ä˝żç”¨čż™äş›ćŽĄĺŹŁçš„地方需č¦ĺŚć—¶ @@ -98,21 +94,22 @@ Linuxč˝ć为强壮，稳定，ć熟的操作系统，这也ćŻä˝ 最开始选 举一个例ĺďĽŚĺ†…ć ¸çš„USB驱动程序接口在USBĺ系统的整个生命周期ä¸ďĽŚč‡łĺ°‘经历 了三次重写。这些重写解决以下问é˘ďĽš + - 把数据ćµä»ŽĺŚćĄć¨ˇĺĽŹć”ąćéťžĺŚćĄć¨ˇĺĽŹďĽŚčż™ä¸Şć”ąĺŠ¨ĺ‡Źĺ°‘了一些驱动程序的 -复杂度，ćŹé«äş†ć‰€ćś‰USB驱动程序的ĺžĺçŽ‡ďĽŚčż™ć ·ĺ‡ äąŽć‰€ćś‰çš„USB设备é˝č˝ä»Ąćś€ĺ¤§ -速率工作了。 + 复杂度，ćŹé«äş†ć‰€ćś‰USB驱动程序的ĺžĺçŽ‡ďĽŚčż™ć ·ĺ‡ äąŽć‰€ćś‰çš„USBč®ľĺ¤‡é˝ + č˝ä»Ąćś€ĺ¤§é€źçŽ‡ĺ·Ąä˝śäş†ă€‚ - 修改了USBć ¸ĺżä»Łç ä¸ä¸şUSB驱动ĺ†é…Ťć•°ćŤ®ĺŚ…内ĺçš„ć–ąĺĽŹďĽŚć‰€ćś‰çš„é©±ĺŠ¨é˝ -需č¦ćŹäľ›ć›´ĺ¤šçš„参数给USBć ¸ĺżďĽŚä»Ąäż®ćŁäş†ĺľĺ¤šĺ·˛ç»Źč˘«č®°ĺ˝•ĺś¨ćˇçš„ć»é”。 + 需č¦ćŹäľ›ć›´ĺ¤šçš„参数给USBć ¸ĺżďĽŚä»Ąäż®ćŁäş†ĺľĺ¤šĺ·˛ç»Źč˘«č®°ĺ˝•ĺś¨ćˇçš„ć»é”。 这和一些ĺ°é—ćşä»Łç 的操作系统形ć鲜ćŽçš„对比，在那些操作系统上，不得不额 外的维护旧的USB接口。这导致了一个可č˝ć€§ďĽŚć–°çš„开发者依然会不小ĺżä˝żç”¨ć—§çš„ 接口，以不ć°ĺ˝“的方式编写代ç ，进而影响ĺ°ć“Ťä˝śçł»ç»źçš„稳定性。 - 在上面的例ĺä¸ďĽŚć‰€ćś‰çš„开发者é˝ĺŚć„Źčż™äş›é‡Ťč¦çš„ć”ąĺŠ¨ďĽŚĺś¨čż™ć ·çš„ć…况下修改代 +在上面的例ĺä¸ďĽŚć‰€ćś‰çš„开发者é˝ĺŚć„Źčż™äş›é‡Ťč¦çš„ć”ąĺŠ¨ďĽŚĺś¨čż™ć ·çš„ć…况下修改代 ä»·ĺľä˝Žă€‚如果LinuxäżťćŚä¸€ä¸Şç¨łĺ®šçš„ĺ†…ć ¸ćşä»Łç 接口，那äąĺ°±ĺľ—ĺ›ĺ»şä¸€ä¸Şć–°çš„接口 ；旧的，有问é˘çš„接口必须一直维护，给Linux USB开发者带来额外的工作。既然 所有的Linux USB驱动的作者é˝ćŻĺ©ç”¨č‡Şĺ·±çš„时间工作，那äąč¦ć±‚他们去ĺšćŻ«ć— ć„Ź 义的免费额外工作，ćŻä¸ŤĺŹŻč˝çš„。 - 安全问é˘ĺŻąLinux来说ĺŤĺ†é‡Ťč¦ă€‚一个安全问é˘č˘«ĺŹ‘现，就会在çźć—¶é—´ĺ†…ĺľ—ĺ°äż® +安全问é˘ĺŻąLinux来说ĺŤĺ†é‡Ťč¦ă€‚一个安全问é˘č˘«ĺŹ‘现，就会在çźć—¶é—´ĺ†…ĺľ—ĺ°äż® ćŁă€‚在ĺľĺ¤šć…况下，这将导致Linuxĺ†…ć ¸ä¸çš„ä¸€äş›ćŽĄĺŹŁč˘«é‡Ťĺ†™ďĽŚä»Ąä»Žć ąćś¬ä¸Šéżĺ…Ťĺ®‰ 全问é˘ă€‚一旦接口被重写，所有使用这些接口的驱动程序，必须ĺŚć—¶ĺľ—ĺ°äż®ćŁďĽŚ 以确定安全问é˘ĺ·˛ç»Źĺľ—ĺ°äż®ĺ¤Ťĺą¶ä¸”不可č˝ĺś¨ćśŞćťĄčżćś‰ĺŚć ·çš„安全问é˘ă€‚ĺ¦‚ćžśĺ†…ć ¸ @@ -124,7 +121,7 @@ Linuxč˝ć为强壮，稳定，ć熟的操作系统，这也ćŻä˝ 最开始选 č¦ĺšä»€äą -------- +-------- ĺ¦‚ćžśä˝ ĺ†™äş†ä¸€ä¸ŞLinuxĺ†…ć ¸é©±ĺŠ¨ďĽŚä˝†ćŻĺ®čżä¸Ťĺś¨Linuxćşä»Łç ć ‘é‡ŚďĽŚä˝śä¸şä¸€ä¸ŞĺĽ€ĺŹ‘ č€…ďĽŚä˝ ĺş”čŻĄć€ŽäąĺšďĽźä¸şćŻŹä¸ŞĺŹ‘ĺ¸çš„每个ç‰ćś¬ćŹäľ›ä¸€ä¸ŞäşŚčż›ĺ¶é©±ĺŠ¨ďĽŚé‚Łç®€ç›´ćŻä¸€ä¸Ş @@ -137,20 +134,21 @@ Linuxč˝ć为强壮，稳定，ć熟的操作系统，这也ćŻä˝ 最开始选 ĺšä»€äąäş‹ć…。 把驱动放ĺ°ĺ†…ć ¸ćşä»Łç ć ‘é‡ŚäĽšćś‰ĺľĺ¤šçš„好处： + - 驱动的质量会ćŹĺŤ‡ďĽŚč€Śç»´ćŠ¤ć本ďĽĺŻąĺŽźĺ§‹ä˝śč€…来说）会下降。 - ĺ…¶ä»–äşşäĽšç»™é©±ĺŠ¨ć·»ĺŠ ć–°ç‰ąć€§ă€‚ - 其他人会找ĺ°é©±ĺŠ¨ä¸çš„bug并修复。 - 其他人会在驱动ä¸ć‰ľĺ°ć€§č˝äĽĺŚ–的机会。 - 当外é¨çš„接口的改ĺŹéś€č¦äż®ć”ąé©±ĺŠ¨ç¨‹ĺşŹçš„时候，其他人会修改驱动程序 -。 - 不需č¦č”系任何发行商，这个驱动会自动的随着所有的Linux发ĺ¸ä¸€čµ·ĺŹ‘ -ĺ¸ă€‚ + ĺ¸ă€‚ ĺ’Śĺ«çš„操作系统相比，Linux为更多不ĺŚçš„设备ćŹäľ›çŽ°ć的驱动，而且č˝ĺś¨ć›´ĺ¤šä¸Ť ĺŚä˝“系结构的处ç†ĺ™¨ä¸Šć”ŻćŚčż™äş›č®ľĺ¤‡ă€‚这个经过č€éŞŚçš„ĺĽ€ĺŹ‘ć¨ˇĺĽŹďĽŚĺż…ç„¶ćŻé”™ä¸Ťäş† çš„ :) -------------- +ć„źč°˘ +---- ć„źč°˘ Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, Robert Love, and Nishanth Aravamudan 对于本文档早期ç‰ćś¬çš„评审和建议。 diff --git a/Documentation/translations/zh_CN/stable_kernel_rules.txt b/Documentation/translations/zh_CN/process/stable-kernel-rules.rst index db4ba5a0c39a..fba361f2ddfd 100644 --- a/Documentation/translations/zh_CN/stable_kernel_rules.txt +++ b/Documentation/translations/zh_CN/process/stable-kernel-rules.rst @@ -1,31 +1,26 @@ -Chinese translated version of Documentation/process/stable-kernel-rules.rst +.. _cn_stable_kernel_rules: -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. +.. include:: ../disclaimer-zh_CN.rst -Chinese maintainer: TripleX Chung <triplex@zh-kernel.org> ---------------------------------------------------------------------- -Documentation/process/stable-kernel-rules.rst çš„ä¸ć–‡çż»čŻ‘ +:Original: :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` 如果ćłčŻ„论ć–更新本文的内容，请直接č”çł»ĺŽźć–‡ćˇŁçš„ç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡ 交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 -译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 +译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…:: + ä¸ć–‡ç‰ç»´ćŠ¤č€…： 钟宇 TripleX Chung <xxx.phy@gmail.com> + ä¸ć–‡ç‰çż»čŻ‘者： 钟宇 TripleX Chung <xxx.phy@gmail.com> + ä¸ć–‡ç‰ć ˇčŻ‘者： + - ćťŽéł Li Yang <leoyang.li@nxp.com> + - Kangkai Yin <e12051@motorola.com> -ä¸ć–‡ç‰ç»´ćŠ¤č€…： 钟宇 TripleX Chung <triplex@zh-kernel.org> -ä¸ć–‡ç‰çż»čŻ‘者： 钟宇 TripleX Chung <triplex@zh-kernel.org> -ä¸ć–‡ç‰ć ˇčŻ‘者： ćťŽéł Li Yang <leo@zh-kernel.org> - Kangkai Yin <e12051@motorola.com> - -以下为ćŁć–‡ ---------------------------------------------------------------------- +ć‰€ćś‰ä˝ ćłçźĄé“çš„äş‹ć… - 关于linux稳定ç‰ĺŹ‘ĺ¸ +======================================== 关于Linux 2.6稳定ç‰ĺŹ‘ĺ¸ďĽŚć‰€ćś‰ä˝ ćłçźĄé“çš„äş‹ć…。 关于哪些类型的补ä¸ĺŹŻä»Ąč˘«ćŽĄć”¶čż›ĺ…Ąç¨łĺ®šç‰ä»Łç ć ‘ďĽŚĺ“Şäş›ä¸ŤĺŹŻä»Ąçš„č§„ĺ™ďĽš +---------------------------------------------------------------- - 必须ćŻćľč€Ść“č§çš„ćŁçˇ®ďĽŚĺą¶ä¸”经过测试的。 - čżžĺŚä¸Šä¸‹ć–‡ďĽŚä¸Ťč˝ĺ¤§äşŽ100行。 @@ -38,9 +33,10 @@ Documentation/process/stable-kernel-rules.rst çš„ä¸ć–‡çż»čŻ‘ - 没有“ç†č®şä¸Šçš„竞争条件”，除非č˝ç»™ĺ‡şç«žäş‰ćťˇä»¶ĺ¦‚何被ĺ©ç”¨çš„解释。 - 不č˝ĺ在任何的“ç碎的”修ćŁďĽć‹Ľĺ†™äż®ćŁďĽŚĺŽ»ćŽ‰ĺ¤šä˝™ç©şć Ľäą‹ç±»çš„）。 - 必须被相关ĺ系统的维护者接受。 - - 必须éµĺľŞDocumentation/process/submitting-patches.rst里的规ĺ™ă€‚ + - 必须éµĺľŞDocumentation/translations/zh_CN/process/submitting-patches.rst里的规ĺ™ă€‚ ĺ‘稳定ç‰ä»Łç ć ‘ćŹäş¤čˇĄä¸çš„过程： +------------------------------ - 在确认了补ä¸ç¬¦ĺ以上的规ĺ™ĺŽďĽŚĺ°†čˇĄä¸ĺŹ‘é€ĺ°stable@vger.kernel.org。 - 如果补ä¸č˘«ćŽĄĺŹ—ĺ°éźĺ—里，发é€č€…会收ĺ°ä¸€ä¸ŞACK回复，如果没有被接受，收 @@ -49,6 +45,7 @@ Documentation/process/stable-kernel-rules.rst çš„ä¸ć–‡çż»čŻ‘ - 安全方面的补ä¸ä¸Ťč¦ĺŹ‘ĺ°čż™ä¸Şĺ—表，应该发é€ĺ°security@kernel.org。 审查周期： +---------- - 当稳定ç‰çš„维护者决定开始一个审查周期，补ä¸ĺ°†č˘«ĺŹ‘é€ĺ°ĺ®ˇćźĄĺ§”ĺ‘会，以 及被补ä¸ĺ˝±ĺ“Ťçš„领域的维护者ďĽé™¤éťžćŹäş¤č€…ĺ°±ćŻčŻĄé˘†ĺźźçš„ç»´ćŠ¤č€…ďĽ‰ĺą¶ä¸”ćŠ„é€ @@ -63,4 +60,5 @@ Documentation/process/stable-kernel-rules.rst çš„ä¸ć–‡çż»čŻ‘ 通常的审查周期。请č”çł»ĺ†…ć ¸ĺ®‰ĺ…¨ĺ°Źç»„ä»ĄčŽ·ĺľ—ĺ…łäşŽčż™ä¸Şčż‡ç¨‹çš„ć›´ĺ¤šç»†čŠ‚ă€‚ 审查委ĺ‘会： +------------ - ç”±ä¸€äş›č‡Şć„żć‰żć‹…čż™éˇąä»»ĺŠˇçš„ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ďĽŚĺ’Śĺ‡ ä¸Şéťžĺż—ć„żçš„ç»„ć。 diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst new file mode 100644 index 000000000000..89061aa8fdbe --- /dev/null +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -0,0 +1,107 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +.. _cn_submitchecklist: + +Linuxĺ†…ć ¸čˇĄä¸ćŹäş¤ć¸…单 +~~~~~~~~~~~~~~~~~~~~~ + +如果开发人ĺ‘希望看ĺ°ä»–ä»¬çš„ĺ†…ć ¸čˇĄä¸ćŹäş¤ć›´ĺż«ĺś°č˘«ćŽĄĺŹ—，那äąä»–们应该ĺšä¸€äş›ĺźşćś¬ +çš„äş‹ć…。 + +这些é˝ćŻĺś¨ +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` +和其他有关ćŹäş¤Linuxĺ†…ć ¸čˇĄä¸çš„文档ä¸ćŹäľ›çš„。 + +1) 如果使用工具，ĺ™ĺŚ…括定义/声ćŽčŻĄĺ·Ąĺ…·çš„文件。不č¦äľťčµ–于其他头文件拉入您使用 + 的头文件。 + +2) 干净的编译： + + a) 使用适用ć–修改的 ``CONFIG`` 选项 ``=y``ă€``=m`` ĺ’Ś ``=n`` 。没有GCC + č¦ĺ‘Š/错误，没有链接器č¦ĺ‘Š/错误。 + + b) 通过allnoconfigă€allmodconfig + + c) 使用 ``O=builddir`` 时可以ć功编译 + +3) 通过使用本地交叉编译工具ć–其他一些构建场在多个CPU体系结构上构建。 + +4) PPC64ćŻä¸€ç§ŤĺľĺĄ˝çš„äş¤ĺŹ‰çĽ–čŻ‘ćŁ€ćźĄä˝“çł»ç»“ćž„ďĽŚĺ› ä¸şĺ®ĺ€ľĺ‘于对64ä˝Ťçš„ć•°ä˝żç”¨ć— ç¬¦ĺŹ· + 长整型。 + +5) 如下所述 :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>`. + 检查您的补ä¸ćŻĺ¦ä¸şĺ¸¸č§„ć ·ĺĽŹă€‚ĺś¨ćŹäş¤ďĽ ``scripts/check patch.pl`` ）之前， + 使用补ä¸ć ·ĺĽŹćŁ€ćźĄĺ™¨ćŁ€ćźĄćŻĺ¦ćś‰č˝»ĺľ®çš„冲çŞă€‚您应该č˝ĺ¤źĺ¤„ç†ć‚¨çš„补ä¸ä¸ĺ在的所有 + 违规行为。 + +6) 任何新的ć–修改过的 ``CONFIG`` 选项é˝ä¸ŤäĽšĺĽ„脏配置菜单，并é»č®¤ä¸şĺ…łé—，除非 + ĺ®ä»¬ç¬¦ĺ ``Documentation/kbuild/kconfig-language.txt`` ä¸č®°ĺ˝•çš„异常条件, + 菜单属性：é»č®¤ĺ€Ľ. + +7) 所有新的 ``kconfig`` 选项é˝ćś‰ĺ¸®ĺŠ©ć–‡ćś¬ă€‚ + +8) 已仔细审查了相关的 ``Kconfig`` 组ĺ。这ĺľéšľç”¨ćµ‹čŻ•ćťĄçş ćŁâ€”—脑力在这里ćŻćś‰ + 回报的。 + +9) 用 sparse 检查干净。 + +10) 使用 ``make checkstack`` ĺ’Ś ``make namespacecheck`` 并修复他们发现的任何 + é—®é˘ă€‚ + + .. note:: + + ``checkstack`` 并没有ćŽçˇ®ćŚ‡ĺ‡şé—®é˘ďĽŚä˝†ćŻä»»ä˝•ä¸€ä¸Şĺś¨ĺ †ć 上使用超过512 + ĺ—节的函数é˝ĺŹŻä»Ąčż›čˇŚć›´ć”ąă€‚ + +11) 包括 :ref:`kernel-doc <kernel_doc>` ĺ†…ć ¸ć–‡ćˇŁä»Ąč®°ĺ˝•ĺ…¨ĺ±€ĺ†…ć ¸API。ďĽéť™ć€ĺ‡˝ć•° + 不需č¦ďĽŚä˝†äąźĺŹŻä»Ąă€‚）使用 ``make htmldocs`` ć– ``make pdfdocs`` 检查 + :ref:`kernel-doc <kernel_doc>` 并修复任何问é˘ă€‚ + +12) 通过以下选项ĺŚć—¶ĺŻç”¨çš„测试 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` + +13) 已经过构建和čżčˇŚć—¶ćµ‹čŻ•ďĽŚĺŚ…括有ć–没有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + +14) 如果补ä¸ç¨‹ĺşŹĺ˝±ĺ“ŤIO/çŁç›ç‰ďĽšä˝żç”¨ć–不使用 ``CONFIG_LBDAF`` 进行测试。 + +15) 所有代ç č·Żĺľ„é˝ĺ·˛ĺś¨ĺŻç”¨ć‰€ćś‰lockdep功č˝çš„ć…况下čżčˇŚă€‚ + +16) 所有新的/proc条目é˝č®°ĺ˝•ĺś¨ ``Documentation/`` + +17) ć‰€ćś‰ć–°çš„ĺ†…ć ¸ĺĽ•ĺŻĽĺŹ‚ć•°é˝č®°ĺ˝•ĺś¨ + Documentation/admin-guide/kernel-parameters.rst ä¸ă€‚ + +18) 所有新的模块参数é˝č®°ĺ˝•ĺś¨ ``MODULE_PARM_DESC()`` + +19) 所有新的用ć·ç©şé—´ćŽĄĺŹŁé˝č®°ĺ˝•ĺś¨ ``Documentation/ABI/`` ä¸ă€‚有关详细信ćŻďĽŚ + čŻ·ĺŹ‚é… ``Documentation/ABI/README`` 。更改用ć·ç©şé—´ćŽĄĺŹŁçš„补ä¸ĺş”čŻĄćŠ„é€ + linux-api@vger.kernel.org。 + +20) 检查ćŻĺ¦ĺ…¨é¨é€ščż‡ ``make headers_check`` 。 + +21) 已通过至少注入slabĺ’Śpageĺ†é…Ťĺ¤±č´Ąčż›čˇŚćŁ€ćźĄă€‚čŻ·ĺŹ‚é… ``Documentation/fault-injection/`` + 如果新代ç ćŻĺ®žč´¨ć€§çš„，那äąć·»ĺŠ ĺ系统特定的故障注入可č˝ćŻĺ适的。 + +22) ć–°ć·»ĺŠ çš„ä»Łç 已经用 ``gcc -W`` 编译ďĽä˝żç”¨ ``make EXTRA-CFLAGS=-W`` ）。这 + 将产生大量噪声，但对于查找诸如“č¦ĺ‘ŠďĽšćś‰ç¬¦ĺŹ·ĺ’Ść— 符号之间的比čľâ€ťäą‹ç±»çš„错误 + ĺľćś‰ç”¨ă€‚ + +23) 在ĺ®č˘«ĺ并ĺ°-mm补ä¸é›†ä¸äą‹ĺŽčż›čˇŚćµ‹čŻ•ďĽŚä»Ąçˇ®äżťĺ®ä»Ťç„¶ä¸Žć‰€ćś‰ĺ…¶ä»–排éźçš„补ä¸ä»Ą + 及VMă€VFS和其他ĺ系统ä¸çš„ĺ„种更改一起工作。 + +24) 所有内ĺ屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` é˝éś€č¦ćşä»Łç ä¸çš„注 + 释来解释ĺ®ä»¬ćŁĺś¨ć‰§čˇŚçš„ć“Ťä˝śĺŹŠĺ…¶ĺŽźĺ› çš„é€»čľ‘ă€‚ + +25) 如果补ä¸ć·»ĺŠ 了任何ioctl，那äąäąźč¦ć›´ć–° ``Documentation/ioctl/ioctl-number.txt`` + +26) 如果修改ĺŽçš„ćşä»Łç äľťčµ–ć–使用与以下 ``Kconfig`` ç¬¦ĺŹ·ç›¸ĺ…łçš„ä»»ä˝•ĺ†…ć ¸APIć– + 功č˝ďĽŚĺ™ĺś¨ç¦ç”¨ç›¸ĺ…ł ``Kconfig`` 符号和/ć– ``=m`` ďĽĺ¦‚果该选项可用）的ć…况 + 下测试以下多个构建[并非所有这些é˝ĺŚć—¶ĺ在，只ćŻĺ®ä»¬çš„ĺ„种/随机组ĺ]： + + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (但ćŻĺŽč€…伴随 ``CONFIG_NET=y``). diff --git a/Documentation/translations/zh_CN/SubmittingDrivers b/Documentation/translations/zh_CN/process/submitting-drivers.rst index 15e73562f710..72c6cd935821 100644 --- a/Documentation/translations/zh_CN/SubmittingDrivers +++ b/Documentation/translations/zh_CN/process/submitting-drivers.rst @@ -1,36 +1,28 @@ -Chinese translated version of Documentation/process/submitting-drivers.rst +.. _cn_submittingdrivers: -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. +.. include:: ../disclaimer-zh_CN.rst -Chinese maintainer: Li Yang <leo@zh-kernel.org> ---------------------------------------------------------------------- -Documentation/process/submitting-drivers.rst çš„ä¸ć–‡çż»čŻ‘ +:Original: :ref:`Documentation/process/submitting-drivers.rst + <submittingdrivers>` 如果ćłčŻ„论ć–更新本文的内容，请直接č”çł»ĺŽźć–‡ćˇŁçš„ç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡ 交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 -译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 +译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…:: -ä¸ć–‡ç‰ç»´ćŠ¤č€…： ćťŽéł Li Yang <leo@zh-kernel.org> -ä¸ć–‡ç‰çż»čŻ‘者： ćťŽéł Li Yang <leo@zh-kernel.org> -ä¸ć–‡ç‰ć ˇčŻ‘者： é™ç¦ Maggie Chen <chenqi@beyondsoft.com> - çŽ‹čŞ Wang Cong <xiyou.wangcong@gmail.com> - ĺĽ ĺ·Ť Zhang Wei <Wei.Zhang@freescale.com> - -以下为ćŁć–‡ ---------------------------------------------------------------------- + ä¸ć–‡ç‰ç»´ćŠ¤č€…： ćťŽéł Li Yang <leoyang.li@nxp.com> + ä¸ć–‡ç‰çż»čŻ‘者： ćťŽéł Li Yang <leoyang.li@nxp.com> + ä¸ć–‡ç‰ć ˇčŻ‘者： é™ç¦ Maggie Chen <chenqi@beyondsoft.com> + çŽ‹čŞ Wang Cong <xiyou.wangcong@gmail.com> + ĺĽ ĺ·Ť Zhang Wei <wezhang@outlook.com> ĺ¦‚ä˝•ĺ‘ Linux ĺ†…ć ¸ćŹäş¤é©±ĺŠ¨ç¨‹ĺşŹ ------------------------------ +============================= 这篇文档将会解释如何ĺ‘不ĺŚçš„ĺ†…ć ¸ćşç ć ‘ćŹäş¤č®ľĺ¤‡é©±ĺŠ¨ç¨‹ĺşŹă€‚čŻ·ćł¨ć„ŹďĽŚĺ¦‚ćžśä˝ ć„ź 兴趣的ćŻćľĺŤˇé©±ĺŠ¨ç¨‹ĺşŹďĽŚä˝ 也许应该访问 XFree86 项目(http://www.xfree86.org/) ĺ’ŚďĽŹć– X.org 项目 (http://x.org)。 -ĺŹ¦čŻ·ĺŹ‚é… Documentation/process/submitting-patches.rst 文档。 +ĺŹ¦čŻ·ĺŹ‚é… Documentation/Documentation/translations/zh_CN/process/submitting-patches.rst 文档。 ĺ†é…Ťč®ľĺ¤‡ĺŹ· @@ -145,9 +137,13 @@ Linux 设备驱动程序，第三ç‰ďĽćŽ˘č®¨ 2.6.10 ç‰ĺ†…ć ¸ďĽ‰ďĽš LWN.net: ćŻŹĺ‘¨ĺ†…ć ¸ĺĽ€ĺŹ‘ć´»ĺŠ¨ć‘č¦ - http://lwn.net/ + 2.6 ç‰ä¸ API çš„ĺŹć›´ďĽš + http://lwn.net/Articles/2.6-kernel-api/ + 将旧ç‰ĺ†…ć ¸çš„é©±ĺŠ¨ç¨‹ĺşŹç§»ć¤Ťĺ° 2.6 ç‰ďĽš + http://lwn.net/Articles/driver-porting/ ĺ†…ć ¸ć–°ć‰‹(KernelNewbies): diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst new file mode 100644 index 000000000000..437c23b367bb --- /dev/null +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -0,0 +1,682 @@ +.. _cn_submittingpatches: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + +译者:: + + ä¸ć–‡ç‰ç»´ćŠ¤č€…： 钟宇 TripleX Chung <xxx.phy@gmail.com> + ä¸ć–‡ç‰çż»čŻ‘者： 钟宇 TripleX Chung <xxx.phy@gmail.com> + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + ä¸ć–‡ç‰ć ˇčŻ‘者： ćťŽéł Li Yang <leoyang.li@nxp.com> + çŽ‹čŞ Wang Cong <xiyou.wangcong@gmail.com> + + +ĺ¦‚ä˝•č®©ä˝ çš„ć”ąĺŠ¨čż›ĺ…Ąĺ†…ć ¸ +====================== + +对于ćłč¦ĺ°†ć”ąĺŠ¨ćŹäş¤ĺ° Linux ĺ†…ć ¸çš„ä¸Şäşşć–者公司来说，如果不熟悉“规矩”， +ćŹäş¤çš„ćµç¨‹äĽšč®©äşşç•Źć§ă€‚本文档收集了一系ĺ—建议，这些建议可以大大的ćŹé«ä˝ +的改动被接受的机会. + +以下文档ĺ«ćś‰ĺ¤§é‡Źç®€ć´çš„建议， 具体请č§ďĽš +:ref:`Documentation/process <development_process_main>` +ĺŚć ·ďĽŚ:ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>` +给出在ćŹäş¤ä»Łç 前需č¦ćŁ€ćźĄçš„项目的ĺ—čˇ¨ă€‚ĺ¦‚ćžśä˝ ĺś¨ćŹäş¤ä¸€ä¸Şé©±ĺŠ¨ç¨‹ĺşŹďĽŚé‚Łäą +ĺŚć—¶é…读一下: +:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + +ĺ…¶ä¸č®¸ĺ¤šćĄéŞ¤ćŹŹčż°äş†Gitç‰ćś¬ćŽ§ĺ¶çł»ç»źçš„é»č®¤čˇŚä¸şďĽ›ĺ¦‚果您使用Git来准备补ä¸ďĽŚ +您将发现ĺ®ä¸şć‚¨ĺ®Ść的大é¨ĺ†ćśşć˘°ĺ·Ąä˝śďĽŚĺ°˝ç®ˇć‚¨ä»Ťç„¶éś€č¦ĺ‡†ĺ¤‡ĺ’Śč®°ĺ˝•ä¸€ç»„ĺç†çš„ +补ä¸ă€‚一č¬ćťĄčŻ´ďĽŚä˝żç”¨gitĺ°†ä˝żć‚¨ä˝śä¸şĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘的生活更轻松。 + + +0) 获取当前ćşç ć ‘ +----------------- + +ĺ¦‚ćžść‚¨ć˛ˇćś‰ä¸€ä¸ŞĺŹŻä»Ąä˝żç”¨ĺ˝“ĺ‰Ťĺ†…ć ¸ćşä»Łç çš„ĺ储库，请使用gitčŽ·ĺŹ–ä¸€ä¸Şă€‚ć‚¨ĺ°†č¦ +从主线ĺ储库开始，ĺ®ĺŹŻä»Ąé€ščż‡ä»Ąä¸‹ć–ąĺĽŹčŽ·ĺŹ–:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +但ćŻďĽŚčŻ·ćł¨ć„ŹďĽŚć‚¨ĺŹŻč˝ä¸Ťĺ¸Śćś›ç›´ćŽĄé’ĺŻąä¸»çşżć ‘čż›čˇŚĺĽ€ĺŹ‘ă€‚ĺ¤§ĺ¤šć•°ĺ系统维护人ĺ‘čż +čˇŚč‡Şĺ·±çš„ć ‘ďĽŚĺą¶ĺ¸Śćś›çś‹ĺ°é’ĺŻąčż™äş›ć ‘ĺ‡†ĺ¤‡çš„čˇĄä¸ă€‚请参č§MAINTAINERS文件ä¸ĺçł» +统的 **T:** éˇąä»ĄćźĄć‰ľčŻĄć ‘ďĽŚć–č€…ç®€ĺŤ•ĺś°čŻ˘é—®ç»´ćŠ¤č€…čŻĄć ‘ćŻĺ¦ćśŞĺś¨ĺ…¶ä¸ĺ—出。 + +仍然可以通过tarballsä¸‹č˝˝ĺ†…ć ¸ç‰ćś¬ďĽĺ¦‚下一节所述），但这ćŻčż›čˇŚĺ†…ć ¸ĺĽ€ĺŹ‘çš„ +一种困难的方式。 + +1) "diff -up" +------------- + +使用 "diff -up" ć–者 "diff -uprN" 来ĺ›ĺ»şčˇĄä¸ă€‚ + +ć‰€ćś‰ĺ†…ć ¸çš„ć”ąĺŠ¨ďĽŚé˝ćŻä»ĄčˇĄä¸çš„形式ĺ‘现的，补ä¸ç”± diff(1) 生ć。ĺ›ĺ»şčˇĄä¸çš„ +时候，č¦çˇ®č®¤ĺ®ćŻä»Ą "unified diff" ć ĽĺĽŹĺ›ĺ»şçš„ďĽŚčż™ç§Ťć ĽĺĽŹç”± diff(1) çš„ '-u' +参数生ć。而且，请使用 '-p' ĺŹ‚ć•°ďĽŚé‚Łć ·äĽšćľç¤şćŻŹä¸Şć”ąĺŠ¨ć‰€ĺś¨çš„C函数，使得 +产生的补ä¸ĺ®ąć“读得多。补ä¸ĺş”čŻĄĺźşäşŽĺ†…ć ¸ćşä»Łç ć ‘çš„ć ąç›®ĺ˝•ďĽŚč€Śä¸ŤćŻé‡Śčľąçš„ä»» +何ĺ目录。 + +为一个单独的文件ĺ›ĺ»şčˇĄä¸ďĽŚä¸€č¬ćťĄčŻ´čż™ć ·ĺšĺ°±ĺ¤źäş†:: + + SRCTREE=linux + MYFILE=drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +为多个文件ĺ›ĺ»şčˇĄä¸ďĽŚä˝ ĺŹŻä»Ąč§ŁĺĽ€ä¸€ä¸Şć˛ˇćś‰äż®ć”ąčż‡çš„ĺ†…ć ¸ćşä»Łç ć ‘ďĽŚç„¶ĺŽĺ’Śä˝ 自 +己的代ç ć ‘äą‹é—´ĺš diff 。例如:: + + MYSRC=/devel/linux + + tar xvfz linux-3.19.tar.gz + mv linux-3.19 linux-3.19-vanilla + diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ + linux-3.19-vanilla $MYSRC > /tmp/patch + +"dontdiff" ćŻĺ†…ć ¸ĺś¨çĽ–čŻ‘çš„ć—¶ĺ€™äş§ç”źçš„ć–‡ä»¶çš„ĺ—表，ĺ—表ä¸çš„文件在 diff(1) +产生的补ä¸é‡ŚäĽšč˘«č·łčż‡ă€‚ + +çˇ®ĺ®šä˝ çš„čˇĄä¸é‡Ść˛ˇćś‰ĺŚ…ĺ«ä»»ä˝•ä¸Ťĺ±žäşŽčż™ć¬ˇčˇĄä¸ćŹäş¤çš„额外文件。记得在用diff(1) +生ć补ä¸äą‹ĺŽďĽŚĺ®ˇé…一次补ä¸ďĽŚä»Ąçˇ®äżťĺ‡†çˇ®ă€‚ + +ĺ¦‚ćžśä˝ çš„ć”ąĺŠ¨ĺľć•Łäą±ďĽŚä˝ ĺş”čŻĄç ”ç©¶ä¸€ä¸‹ĺ¦‚ä˝•ĺ°†čˇĄä¸ĺ†ĺ‰˛ć独立的é¨ĺ†ďĽŚĺ°†ć”ąĺŠ¨ĺ† +割ć一系ĺ—ĺ乎逻辑的ćĄéŞ¤ă€‚čż™ć ·ć›´ĺ®ąć“č®©ĺ…¶ä»–ĺ†…ć ¸ĺĽ€ĺŹ‘č€…ĺ®ˇć ¸ďĽŚĺ¦‚ćžśä˝ ćłä˝ çš„ +补ä¸č˘«ćŽĄĺŹ—，这ćŻĺľé‡Ťč¦çš„。请参é…： +:ref:`cn_split_changes` + +ĺ¦‚ćžśä˝ ç”¨ ``git`` , ``git rebase -i`` ĺŹŻä»Ąĺ¸®ĺŠ©ä˝ čż™ä¸€ç‚ąă€‚ĺ¦‚ćžśä˝ ä¸Ťç”¨ ``git``, +``quilt`` <http://savannah.nongnu.org/projects/quilt> 另外一个ćµčˇŚçš„选择。 + +.. _cn_describe_changes: + +2) ćŹŹčż°ä˝ çš„ć”ąĺŠ¨ +--------------- + +ćŹŹčż°ä˝ çš„é—®é˘ă€‚ć— č®şć‚¨çš„čˇĄä¸ćŻä¸€čˇŚé”™čŻŻäż®ĺ¤ŤčżćŻ5000行新功č˝ďĽŚé˝ĺż…须有一个潜在 +çš„é—®é˘ćż€ĺŠ±ć‚¨ĺ®Ść这项工作。让审稿人相信有一个问é˘ĺ€Ľĺľ—解决，让他们读完第一段 +ćŻćś‰ć„Źäą‰çš„。 + +描述用ć·ĺŹŻč§çš„影响。直接崩ćşĺ’Śé”定ćŻç›¸ĺ˝“有说服力的，但并不ćŻć‰€ćś‰çš„错误é˝é‚Łäą +ćŽç›®ĺĽ č†ă€‚即使在代ç 审查期间发现了这个问é˘ďĽŚäąźč¦ćŹŹčż°ä¸€ä¸‹ć‚¨č®¤ä¸şĺ®ĺŹŻč˝ĺŻąç”¨ć·äş§ +生的影响。请记住，大多数Linux安装čżčˇŚçš„ĺ†…ć ¸ćťĄč‡ŞäşŚçş§ç¨łĺ®šć ‘ć–特定于供应商/äş§ĺ“ +çš„ć ‘ďĽŚĺŹŞä»Žä¸Šć¸¸ç˛ľé€‰ç‰ąĺ®šçš„čˇĄä¸ďĽŚĺ› ć¤čŻ·ĺŚ…ĺ«ä»»ä˝•ĺŹŻä»Ąĺ¸®ĺŠ©ć‚¨ĺ°†ć›´ć”ąĺ®šä˝Ťĺ°ä¸‹ć¸¸çš„内容： +触发的场景ă€DMESGçš„ć‘录ă€ĺ´©ćşćŹŹčż°ă€ć€§č˝ĺ›žĺ˝’ă€ĺ»¶čżźĺ°–ĺł°ă€é”定ç‰ă€‚ + +量化äĽĺŚ–ĺ’Śćťčˇˇă€‚如果您声称在性č˝ă€ĺ†…ĺć¶č€—ă€ĺ †ć ĺŤ ç”¨ç©şé—´ć–二进ĺ¶ĺ¤§ĺ°Źć–ąéť˘ćś‰ć‰€ +改进，请包括支ćŚĺ®ä»¬çš„ć•°ĺ—。但也č¦ćŹŹčż°ä¸ŤćŽćľçš„ć本。äĽĺŚ–通常不ćŻĺ…Ťč´ąçš„ďĽŚč€ŚćŻ +在CPUă€ĺ†…ĺ和可读性之间进行ćťčˇˇďĽ›ć–者，探索性的工作，在不ĺŚçš„工作负载之间进 +行ćťčˇˇă€‚请描述äĽĺŚ–的预期缺点，以便审é…者可以ćťčˇˇć本和收益。 + +一旦问é˘ĺ»şç«‹čµ·ćťĄďĽŚĺ°±č¦čŻ¦ç»†ĺś°ćŹŹčż°ä¸€ä¸‹ć‚¨ĺ®žé™…在ĺšä»€äąă€‚对于审é…者来说，用简单的 +英čŻćŹŹčż°ä»Łç çš„ĺŹĺŚ–ćŻĺľé‡Ťč¦çš„，以验čŻä»Łç 的行为ćŻĺ¦ç¬¦ĺ您的意愿。 + +如果您将补ä¸ćŹŹčż°ĺ†™ĺś¨ä¸€ä¸Şčˇ¨ĺŤ•ä¸ďĽŚčż™ä¸Şčˇ¨ĺŤ•ĺŹŻä»Ąĺľĺ®ąć“地作为“ćŹäş¤ć—Ąĺż—”放入Linux +çš„ćşä»Łç 管ç†çł»ç»źgitä¸ďĽŚé‚Łäąç»´ćŠ¤äşşĺ‘ĺ°†éťžĺ¸¸ć„źč°˘ć‚¨ă€‚č§ :ref:`cn_explicit_in_reply_to`. + +每个补ä¸ĺŹŞč§Łĺ†łä¸€ä¸Şé—®é˘ă€‚ĺ¦‚ćžśä˝ çš„ćŹŹčż°ĺĽ€ĺ§‹ĺŹé•żďĽŚčż™ĺ°±čˇ¨ćŽä˝ 可č˝éś€č¦ć‹†ĺ†ä˝ 的补ä¸ă€‚ +čŻ·č§ :ref:`cn_split_changes` + +ćŹäş¤ć–重新ćŹäş¤äż®čˇĄç¨‹ĺşŹć–修补程序系ĺ—时，请包括完整的修补程序说ćŽĺ’Śç†ç”±ă€‚ä¸Ťč¦ +只说这ćŻčˇĄä¸ďĽçł»ĺ—ďĽ‰çš„ç¬¬ĺ‡ ç‰ă€‚不č¦ćśźćś›ĺ系统维护人ĺ‘引用更早的补ä¸ç‰ćś¬ć–引用 +URL来查找补ä¸ćŹŹčż°ĺą¶ĺ°†ĺ…¶ć”ľĺ…ĄčˇĄä¸ä¸ă€‚äąźĺ°±ćŻčŻ´ďĽŚčˇĄä¸ďĽçł»ĺ—）及其描述应该ćŻç‹¬ç«‹çš„。 +这对维护人ĺ‘和审查人ĺ‘é˝ćś‰ĺĄ˝ĺ¤„。一些评审者可č˝ç”šč‡łć˛ˇćś‰ć”¶ĺ°čˇĄä¸çš„ć—©ćśźç‰ćś¬ă€‚ + +ćŹŹčż°ä˝ ĺś¨ĺ‘˝ä»¤čŻć°”ä¸çš„ĺŹĺŚ–，例如“make xyzzy do frotz”而不ćŻâ€ś[这个补ä¸]make +xyzzy do frotz”ć–“[ć‘]changed xyzzy to do frotz”，就好ĺŹä˝ 在命令代ç ĺş“ć”ąĺŹ +ĺ®çš„čˇŚä¸şä¸€ć ·ă€‚ + +如果修补程序修复了一个记录的bug条目，请按编号和URL引用该bug条目。如果补ä¸ćťĄ +自邮件ĺ—表讨论，请给出邮件ĺ—表ĺ档的URL；使用带有 ``Message-ID`` çš„ +https://lkml.kernel.org/ 重定ĺ‘，以确保链接不会过时。 + +但ćŻďĽŚĺś¨ć˛ˇćś‰ĺ¤–é¨čµ„ćşçš„ć…ĺ†µä¸‹ďĽŚĺ°˝é‡Źč®©ä˝ çš„č§Łé‡ŠĺŹŻç†č§Łă€‚除了ćŹäľ›é‚®ä»¶ĺ—表ĺćˇŁć– +bugçš„URL之外，čżč¦ć€»ç»“需č¦ćŹäş¤čˇĄä¸çš„相关讨论č¦ç‚ąă€‚ + +如果您ćłč¦ĺĽ•ç”¨ä¸€ä¸Şç‰ąĺ®šçš„ćŹäş¤ďĽŚä¸Ťč¦ĺŹŞĺĽ•ç”¨ćŹäş¤çš„ SHA-1 ID。čżčŻ·ĺŚ…括ćŹäş¤çš„一行 +ć‘č¦ďĽŚä»ĄäľżäşŽĺ®ˇé…者了解ĺ®ćŻĺ…łäşŽä»€äąçš„。例如:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +您čżĺş”该确保至少使用前12位 SHA-1 ID. ĺ†…ć ¸ĺ储库包ĺ«*许多*对象，使与čľçźçš„ID +发生冲çŞçš„可č˝ć€§ĺľĺ¤§ă€‚记住，即使现在不会与您的ĺ…个ĺ—符ID发生冲çŞďĽŚčż™ç§Ťć…况 +可č˝äş”ĺą´ĺŽć”ąĺŹă€‚ + +如果修补程序修复了特定ćŹäş¤ä¸çš„错误，例如，使用 ``git bisct`` ，请使用带有前 +12个ĺ—符SHA-1 ID çš„"Fixes:"ć ‡č®°ĺ’ŚĺŤ•čˇŚć‘č¦ă€‚为了简化不č¦ĺ°†ć ‡č®°ć‹†ĺ†ä¸şĺ¤šä¸ŞďĽŚ +行ă€ć ‡č®°ä¸ŤĺŹ—ĺ†ćžč„šćś¬â€ś75ĺ—换行”规ĺ™çš„é™ĺ¶ă€‚例如:: + + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +ä¸‹ĺ— ``git config`` č®ľç˝®ĺŹŻä»Ąć·»ĺŠ č®© ``git log``, ``git show`` 漂亮的ćľç¤şć ĽĺĽŹ:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +.. _cn_split_changes: + +3) 拆ĺ†ä˝ 的改动 +--------------- + +将每个逻辑更改ĺ†éš”ć一个单独的补ä¸ă€‚ + +äľ‹ĺ¦‚ďĽŚĺ¦‚ćžśä˝ çš„ć”ąĺŠ¨é‡ŚĺŚć—¶ćś‰bugäż®ćŁĺ’Ść€§č˝äĽĺŚ–，那äąćŠŠčż™äş›ć”ąĺŠ¨ć‹†ĺ†ĺ°ä¸¤ä¸Şć– +者更多的补ä¸ć–‡ä»¶ä¸ă€‚ĺ¦‚ćžśä˝ çš„ć”ąĺŠ¨ĺŚ…ĺ«ĺŻąAPI的修改，并且修改了驱动程序来适 +应这些新的API，那äąćŠŠčż™äş›äż®ć”ąĺ†ć两个补ä¸ă€‚ + +ĺŹ¦ä¸€ć–ąéť˘ďĽŚĺ¦‚ćžśä˝ ĺ°†ä¸€ä¸ŞĺŤ•ç‹¬çš„ć”ąĺŠ¨ĺšć多个补ä¸ć–‡ä»¶ďĽŚé‚Łäąĺ°†ĺ®ä»¬ĺ并ć一个 +单独的补ä¸ć–‡ä»¶ă€‚čż™ć ·ä¸€ä¸Şé€»čľ‘ä¸ŠĺŤ•ç‹¬çš„ć”ąĺŠ¨ĺŹŞč˘«ĺŚ…ĺ«ĺś¨ä¸€ä¸ŞčˇĄä¸ć–‡ä»¶é‡Śă€‚ + +如果有一个补ä¸äľťčµ–另外一个补ä¸ćťĄĺ®Śćĺ®çš„改动，那没问é˘ă€‚ç®€ĺŤ•çš„ĺś¨ä˝ çš„čˇĄ +ä¸ćŹŹčż°é‡ŚćŚ‡ĺ‡şâ€śčż™ä¸ŞčˇĄä¸äľťčµ–ćźčˇĄä¸â€ťĺ°±ĺĄ˝äş†ă€‚ + +在将您的更改ĺ’ĺ†ä¸şä¸€çł»ĺ—补ä¸ć—¶ďĽŚč¦ç‰ąĺ«ćł¨ć„Źçˇ®äżťĺ†…ć ¸ĺś¨çł»ĺ—ä¸çš„每个补ä¸äą‹ĺŽ +é˝č˝ćŁĺ¸¸ćž„建和čżčˇŚă€‚使用 ``git bisect`` 来追踪问é˘çš„开发者可č˝äĽšĺś¨ä»»ä˝•ć—¶ +候ĺ†ĺ‰˛ä˝ 的补ä¸çł»ĺ—ďĽ›ĺ¦‚ćžśä˝ ĺś¨ä¸é—´ĺĽ•ĺ…Ąé”™čŻŻďĽŚä»–ä»¬ä¸ŤäĽšć„źč°˘ä˝ ă€‚ + +ĺ¦‚ćžśä˝ ä¸Ťč˝ĺ°†čˇĄä¸ćµ“缩ć更少的文件，那äąćŻŹć¬ˇĺ¤§çş¦ĺŹ‘é€ĺ‡ş15个，然ĺŽç‰ĺľ…审查 +和集ć。 + +4) ćŁ€ćźĄä˝ çš„ć›´ć”ąéŁŽć Ľ +------------------- + +检查您的补ä¸ćŻĺ¦ĺĺś¨ĺźşćś¬ć ·ĺĽŹĺ†˛çŞďĽŚčŻ¦ç»†äżˇćŻĺŹŻĺś¨ +:ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` +ä¸ć‰ľĺ°ă€‚ĺ¦‚ćžśä¸Ťčż™ć ·ĺšďĽŚĺŹŞäĽšćµŞč´ąĺ®ˇç¨żäşşçš„ć—¶é—´ďĽŚĺą¶ä¸”äĽšĺŻĽč‡´ä˝ çš„čˇĄä¸č˘«ć‹’绝，甚至 +可č˝ć˛ˇćś‰č˘«é…读。 + +一个重č¦çš„例外ćŻĺś¨ĺ°†ä»Łç 从一个文件移动ĺ°ĺŹ¦ä¸€ä¸Şć–‡ä»¶ć—¶â€”—在这种ć…况下，您不应 +该在移动代ç çš„ĺŚä¸€ä¸ŞčˇĄä¸ä¸äż®ć”ąç§»ĺŠ¨çš„代ç 。这清楚地描述了移动代ç 和您的更改 +的行为。这大大有助于审查实际差异，并ĺ…许工具更好地跟踪代ç 本身的历史。 + +在ćŹäş¤äą‹ĺ‰ŤďĽŚä˝żç”¨čˇĄä¸ć ·ĺĽŹćŁ€ćźĄç¨‹ĺşŹćŁ€ćźĄčˇĄä¸ďĽscripts/check patch.pl）。不过， +čŻ·ćł¨ć„ŹďĽŚć ·ĺĽŹćŁ€ćźĄç¨‹ĺşŹĺş”čŻĄč˘«č§†ä¸şä¸€ä¸ŞćŚ‡ĺŤ—ďĽŚč€Śä¸ŤćŻä˝śä¸şäşşç±»ĺ¤ć–的替代ĺ“。如果您 +的代ç 看起来更好，但有违规行为，那äąćś€ĺĄ˝ä¸Ťč¦ä˝żç”¨ĺ®ă€‚ + +检查者报告三个级ĺ«ďĽš + + - ERROR：ĺľĺŹŻč˝ĺ‡şé”™çš„äş‹ć… + - WARNING：需č¦ä»”细审查的事项 + - CHECK：需č¦ć€ťč€çš„äş‹ć… + +您应该č˝ĺ¤źĺ¤ć–您的补ä¸ä¸ĺ在的所有违规行为。 + +5) 选择补ä¸ć”¶ä»¶äşş +----------------- + +您应该总ćŻĺś¨ä»»ä˝•čˇĄä¸ä¸Šĺ¤Ťĺ¶ç›¸ĺş”çš„ĺ系统维护人ĺ‘，以获得他们维护的代ç ；查看 +维护人ĺ‘文件和ćşä»Łç 修订历史记录，以了解这些维护人ĺ‘ćŻč°ă€‚脚本 +scripts/get_Maintainer.pl在这个ćĄéޤä¸éťžĺ¸¸ćś‰ç”¨ă€‚如果您找不ĺ°ćŁĺś¨ĺ·Ąä˝śçš„ĺ系统 +的维护人ĺ‘，那äąAndrew MortonďĽakpm@linux-foundation.org）将充当最ĺŽçš„维护 +äşşĺ‘。 + +您通常čżĺş”该选择至少一个邮件ĺ—表来接收补ä¸é›†çš„。linux-kernel@vger.kernel.org +作为最ĺŽä¸€ä¸Şč§Łĺ†łĺŠžćł•çš„ĺ—表，但ćŻčż™ä¸Şĺ—表上的体积已经引起了许多开发人ĺ‘的拒绝。 +在MAINTAINERS文件ä¸ćźĄć‰ľĺ系统特定的ĺ—表；您的补ä¸ĺŹŻč˝äĽšĺś¨é‚Łé‡Śĺľ—ĺ°ć›´ĺ¤šçš„关注。 +不过，请不č¦ĺŹ‘é€ĺžĺśľé‚®ä»¶ĺ°ć— ĺ…łçš„ĺ—表。 + +č®¸ĺ¤šä¸Žĺ†…ć ¸ç›¸ĺ…łçš„ĺ—表ć‰ç®ˇĺś¨vger.kernel.org上；您可以在 +http://vger.kernel.org/vger-lists.html 上找ĺ°ĺ®ä»¬çš„ĺ—čˇ¨ă€‚ä¸Ťčż‡ďĽŚäąźćś‰ä¸Žĺ†…ć ¸ç›¸ĺ…ł +çš„ĺ—表ć‰ç®ˇĺś¨ĺ…¶ä»–地方。 + +不č¦ä¸€ć¬ˇĺŹ‘é€č¶…过15个补ä¸ĺ°vger邮件ĺ—表ďĽďĽďĽďĽ + +Linus Torvalds ćŻĺ†łĺ®šć”ąĺŠ¨č˝ĺ¦čż›ĺ…Ą Linux ĺ†…ć ¸çš„ćś€ç»čŁĺ†łč€…。他的 e-mail +ĺś°ĺť€ćŻ <torvalds@linux-foundation.org> 。他收ĺ°çš„ e-mail ĺľĺ¤šďĽŚć‰€ä»Ąä¸€č¬ +的说，最好ĺ«ç»™ä»–发 e-mail。 + +如果您有修复可ĺ©ç”¨ĺ®‰ĺ…¨ćĽŹć´žçš„补ä¸ďĽŚčŻ·ĺ°†čŻĄčˇĄä¸ĺŹ‘é€ĺ° security@kernel.org。对于 +严重的bug，可以č€č™‘çźćśźćš‚ĺśä»Ąĺ…许ĺ†é”€ĺ•†ĺ‘用ć·ĺŹ‘ĺ¸čˇĄä¸ďĽ›ĺś¨čż™ç§Ťć…况下，ćľç„¶ä¸Ťĺş” +将补ä¸ĺŹ‘é€ĺ°ä»»ä˝•ĺ…¬ĺ…±ĺ—表。 + +修复已发ĺ¸ĺ†…ć ¸ä¸ä¸Ąé‡Ťé”™čŻŻçš„补ä¸ç¨‹ĺşŹĺş”该指ĺ‘稳定ç‰ç»´ćŠ¤äşşĺ‘，方法ćŻć”ľčż™ć ·çš„一行:: + + Cc: stable@vger.kernel.org + +进入补ä¸çš„çľĺ‡†ĺŚşďĽćł¨ć„ŹďĽŚä¸ŤćŻç”µĺ邮件收件人）。除了这个文件之外，您čżĺş”该é…读 +:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + +但ćŻďĽŚčŻ·ćł¨ć„ŹďĽŚä¸€äş›ĺ系统维护人ĺ‘希望得出他们自己的结论，即哪些补ä¸ĺş”čŻĄč˘«ć”ľĺ° +ç¨łĺ®šçš„ć ‘ä¸Šă€‚ĺ°¤ĺ…¶ćŻç˝‘络维护人ĺ‘，不希望看ĺ°ĺŤ•ä¸ŞĺĽ€ĺŹ‘äşşĺ‘在补ä¸ä¸ć·»ĺŠ ĺŹä¸Šéť˘čż™ć · +的行。 + +如果更改影响ĺ°ç”¨ć·ĺ’Śĺ†…ć ¸ćŽĄĺŹŁďĽŚčŻ·ĺ‘手册页维护人ĺ‘ďĽĺ¦‚维护人ĺ‘文件ä¸ć‰€ĺ—ďĽ‰ĺŹ‘é€ +手册页补ä¸ďĽŚć–至少发é€ć›´ć”ąé€šçźĄďĽŚä»Ąäľżä¸€äş›äżˇćŻčż›ĺ…Ąć‰‹ĺ†Śéˇµă€‚čżĺş”将用ć·ç©şé—´API +更改复ĺ¶ĺ° linux-api@vger.kernel.org。 + +对于小的补ä¸ďĽŚä˝ 也许会CCĺ°ćśé›†ç碎补ä¸çš„邮件ĺ—表(Trivial Patch Monkey) +trivial@kernel.org，那里专门收集ç碎的补ä¸ă€‚ä¸‹éť˘čż™ć ·çš„čˇĄä¸äĽšč˘«çś‹ä˝śâ€śç碎的” +补ä¸ďĽš + + - 文档的拼写修ćŁă€‚ + - äż®ćŁäĽšĺ˝±ĺ“Ťĺ° grep(1) 的拼写。 + - č¦ĺ‘ŠäżˇćŻäż®ćŁ(频çąçš„ć‰“ĺŤ°ć— ç”¨çš„č¦ĺ‘ŠćŻä¸ŤĺĄ˝çš„。) + - 编译错误修ćŁďĽä»Łç 逻辑的确ćŻĺŻąçš„，只ćŻçĽ–译有问é˘ă€‚） + - čżčˇŚć—¶äż®ćŁďĽĺŹŞč¦çśźçš„äż®ćŁäş†é”™čŻŻă€‚） + - 移除使用了被废ĺĽçš„函数/宏的代ç (例如 check_region。) + - č”系方式和文档修ćŁă€‚ + - 用可移植的代ç 替换不可移植的代ç ďĽĺŤłä˝żĺś¨ä˝“系结构相关的代ç ä¸ďĽŚć—˘ç„¶ćś‰ + - 人拷贝，只č¦ĺ®ćŻç碎的） + - 任何文件的作者/维护者对该文件的改动ďĽäľ‹ĺ¦‚ patch monkey ĺś¨é‡ŤäĽ ć¨ˇĺĽŹä¸‹ďĽ‰ + +(译注，关于“ç碎补ä¸â€ťçš„一些说ćŽďĽšĺ› 为原文的这一é¨ĺ†ĺ†™ĺľ—比čľç®€ĺŤ•ďĽŚć‰€ä»Ąä¸Ťĺľ—不 +违例写一下译注。"trivial"这个英文单词的本意ćŻâ€śç碎的，不重č¦çš„。”但ćŻĺś¨čż™é‡Ś +有稍微有一些ĺŹĺŚ–，例如对一些ćŽćľçš„NULL指é’çš„äż®ćŁďĽŚĺ±žäşŽčżčˇŚć—¶äż®ćŁďĽŚäĽšč˘«ĺ˝’ç±» +ĺ°ç碎补ä¸é‡Śă€‚虽然NULL指é’çš„äż®ćŁĺľé‡Ťč¦ďĽŚä˝†ćŻčż™ć ·çš„äż®ćŁĺľ€ĺľ€ĺľĺ°Źč€Śä¸”ĺľĺ®ąć“ĺľ—ĺ° +检验，所以也被归入ç碎补ä¸ă€‚ç碎补ä¸ć›´ç˛ľçˇ®çš„ĺ˝’ç±»ĺş”čŻĄćŻ +“simple, localized & easy to verify”，也就ćŻčŻ´ç®€ĺŤ•çš„，局é¨çš„ĺ’Ść“于检验的。 +trivial@kernel.org邮件ĺ—表的目的ćŻé’ĺŻąčż™ć ·çš„čˇĄä¸ďĽŚä¸şćŹäş¤č€…ćŹäľ›ä¸€ä¸Şä¸ĺżďĽŚćťĄ +降低ćŹäş¤çš„门槛。) + +6) 没有 MIME 编ç ，没有链接，没有压缩，没有附件，只有纯文本 +----------------------------------------------------------- + +Linus ĺ’Śĺ…¶ä»–çš„ĺ†…ć ¸ĺĽ€ĺŹ‘č€…éś€č¦é…čŻ»ĺ’ŚčŻ„č®şä˝ ćŹäş¤çš„ć”ąĺŠ¨ă€‚ĺŻąäşŽĺ†…ć ¸ĺĽ€ĺŹ‘č€…ćťĄčŻ´ +ďĽŚĺŹŻä»Ąâ€śĺĽ•ç”¨â€ťä˝ çš„ć”ąĺŠ¨ĺľé‡Ťč¦ďĽŚä˝żç”¨ä¸€č¬çš„ e-mail ĺ·Ąĺ…·ďĽŚä»–ä»¬ĺ°±ĺŹŻä»Ąĺś¨ä˝ çš„ +代ç çš„ä»»ä˝•ä˝Ťç˝®ć·»ĺŠ čŻ„č®şă€‚ + +ĺ› ä¸şčż™ä¸ŞĺŽźĺ› ďĽŚć‰€ćś‰çš„ćŹäş¤çš„补ä¸é˝ćŻ e-mail ä¸â€śĺ†…嵌”的。 + +.. warning:: + ĺ¦‚ćžśä˝ ä˝żç”¨ĺ‰Şĺ‡-ç˛č´´ä˝ 的补ä¸ďĽŚĺ°Źĺżä˝ 的编辑器的自动换行功č˝ç ´ĺťŹä˝ çš„čˇĄä¸ + +不č¦ĺ°†čˇĄä¸ä˝śä¸ş MIME 编ç 的附件，不管ćŻĺ¦ĺŽ‹çĽ©ă€‚ĺľĺ¤šćµčˇŚçš„ e-mail 软件不 +ćŻä»»ä˝•ć—¶ĺ€™é˝ĺ°† MIME 编ç 的附件当作纯文本发é€çš„，这会使得ĺ«äşşć— ćł•ĺś¨ä˝ çš„ +代ç ä¸ĺŠ 评论。另外，MIME 编ç 的附件会让 Linus 多花一点时间来处ç†ďĽŚčż™ĺ°± +é™Ťä˝Žäş†ä˝ çš„ć”ąĺŠ¨č˘«ćŽĄĺŹ—çš„ĺŹŻč˝ć€§ă€‚ + +äľ‹ĺ¤–ďĽšĺ¦‚ćžśä˝ çš„é‚®é€’ĺ‘弄坏了补ä¸ďĽŚé‚Łäąćś‰äşşĺŹŻč˝äĽšč¦ć±‚ä˝ ä˝żç”¨mime重新发é€čˇĄä¸ + +čŻ·ĺŹ‚é… :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` +以获取有关配置电ĺ邮件客ć·ç«Żä»Ąä˝żĺ…¶ä¸ŤĺŹ—影响地发é€äż®čˇĄç¨‹ĺşŹçš„ćŹç¤şă€‚ + +7) e-mail 的大小 +---------------- + +大的改动对邮件ĺ—表不ĺ适，对ćźäş›ç»´ćŠ¤č€…也不ĺé€‚ă€‚ĺ¦‚ćžśä˝ çš„čˇĄä¸ďĽŚĺś¨ä¸ŤĺŽ‹çĽ© +çš„ć…况下，超过了300kB，那äąä˝ 最好将补ä¸ć”ľĺś¨ä¸€ä¸Şč˝é€ščż‡ internet 访问的服 +务器上，然ĺŽç”¨ćŚ‡ĺ‘ä˝ çš„čˇĄä¸çš„ URL 替代。但ćŻčŻ·ćł¨ć„ŹďĽŚĺ¦‚果您的补ä¸č¶…过了 +300kb，那äąĺ®ĺ‡ 乎肯定需č¦č˘«ç ´ĺťŹă€‚ + +8ďĽ‰ĺ›žĺ¤ŤčŻ„ĺ®ˇć„Źč§ +--------------- + +ä˝ çš„čˇĄä¸ĺ‡ 乎肯定会得ĺ°čŻ„审者对补ä¸ć”ąčż›ć–ąćł•çš„评论。您必须对这些评论作出 +回应；让补ä¸č˘«ĺż˝ç•Ąçš„一个好办法就ćŻĺż˝ç•Ąĺ®ˇé…者的意č§ă€‚不会导致代ç 更改的 +ć„Źč§ć–é—®é˘ĺ‡ 乎肯定会带来注释ć–ĺŹć›´ć—Ąĺż—的改ĺŹďĽŚä»Ąäľżä¸‹ä¸€ä¸ŞčŻ„审者更好地了解 +ćŁĺś¨ĺŹ‘生的事ć…。 + +一定č¦ĺ‘ŠčŻ‰ĺ®ˇç¨żäşşä˝ 在ĺšä»€äąć”ąĺŹďĽŚĺą¶ć„źč°˘ä»–们的时间。代ç 审查ćŻä¸€ä¸Şç´Żäşşä¸” +耗时的过程，审查人ĺ‘有时会ĺŹĺľ—ćš´čşă€‚即使在这种ć…况下，也č¦ç¤Ľč˛Śĺś°ĺ›žĺş”并 +解决他们指出的问é˘ă€‚ + +9）不č¦ćł„ć°”ć–不č€ç¦ +------------------- + +ćŹäş¤ć›´ć”ąĺŽďĽŚčŻ·č€ĺżç‰ĺľ…。审é…者ćŻĺż™ç˘Śçš„人，可č˝ć— 法立即访问您的修补程序。 + +ć›ľĺ‡ ä˝•ć—¶ďĽŚčˇĄä¸ć›ľĺś¨ć˛ˇćś‰čŻ„论的ć…况下ć¶ĺ¤±ĺś¨ç©şç™˝ä¸ďĽŚä˝†ĺĽ€ĺŹ‘čż‡ç¨‹ćŻ”çŽ°ĺś¨ć›´ĺŠ éˇşĺ©ă€‚ +您应该在一周左右的时间内收ĺ°čŻ„论；如果没有收ĺ°čŻ„论，请确保您已将补ä¸ĺŹ‘é€ +ĺ°ćŁçˇ®çš„位置。在重新ćŹäş¤ć–č”系审é…者之前至少ç‰ĺľ…一周-在诸如ĺ并窗口之类的 +çąĺż™ć—¶é—´ĺŹŻč˝ć›´é•żă€‚ + +10）主é˘ä¸ĺŚ…ĺ« PATCH +-------------------- + +由于ĺ°linusĺ’Ślinuxĺ†…ć ¸çš„ç”µĺ邮件ćµé‡Źĺľé«ďĽŚé€šĺ¸¸äĽšĺś¨ä¸»é˘čˇŚĺ‰Ťéť˘ĺŠ 上[PATCH] +前缀. 这使Linusĺ’Śĺ…¶ä»–ĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘更容ć“将补ä¸ä¸Žĺ…¶ä»–电ĺ邮件讨论区ĺ†ĺĽ€ă€‚ + +11）çľç˝˛ä˝ 的作ĺ“-ĺĽ€ĺŹ‘č€…ĺŽźĺ§‹č®¤čŻ +------------------------------- + +ä¸şäş†ĺŠ ĺĽşĺŻąč°ĺšäş†ä˝•äş‹çš„追踪，尤其ćŻĺŻąé‚Łäş›é€Źčż‡ĺĄ˝ĺ‡ 层的维护者的补ä¸ďĽŚć‘们 +建议在发é€ĺ‡şĺŽ»çš„补ä¸ä¸ŠĺŠ 一个 “sign-off” 的过程。 + +"sign-off" ćŻĺś¨čˇĄä¸çš„注释的最ĺŽçš„简单的一行文ĺ—，认čŻä˝ 编写了ĺ®ć–者其他 +人有ćťĺŠ›ĺ°†ĺ®ä˝śä¸şĺĽ€ć”ľćşä»Łç 的补ä¸äĽ 递。规ĺ™ĺľç®€ĺŤ•ďĽšĺ¦‚ćžśä˝ č˝č®¤čŻĺ¦‚下信ćŻ: + +开发者来ćşčŻäą¦ 1.1 +^^^^^^^^^^^^^^^^^^ + +对于本项目的贡献，ć‘认čŻĺ¦‚下信ćŻďĽš + + ďĽa）这些贡献ćŻĺ®Śĺ…¨ć–者é¨ĺ†çš„ç”±ć‘ĺ›ĺ»şďĽŚć‘有ćťĺ©ä»Ąć–‡ä»¶ä¸ćŚ‡ĺ‡ş + 的开放ćşä»Łç 许可čŻćŹäş¤ĺ®ďĽ›ć–者 + ďĽb）这些贡献基于以前的工作，据ć‘所知，这些以前的工作受ć°ĺ˝“的开放 + ćşä»Łç 许可čŻäżťćŠ¤ďĽŚč€Śä¸”ďĽŚć ąćŤ®č®¸ĺŹŻčŻďĽŚć‘有ćťćŹäş¤äż®ć”ąĺŽçš„贡献， + ć— č®şćŻĺ®Śĺ…¨čżćŻé¨ĺ†ç”±ć‘ĺ›é€ ，这些贡献é˝ä˝żç”¨ĺŚä¸€ä¸ŞĺĽ€ć”ľćşä»Łç č®¸ĺŹŻčŻ + ďĽé™¤éťžć‘被ĺ…许用其ĺ®çš„许可čŻďĽ‰ďĽŚćŁĺ¦‚文件ä¸ćŚ‡ĺ‡şçš„；ć–者 + ďĽc）这些贡献由认čŻďĽa），ďĽb）ć–者ďĽc）的人直接ćŹäľ›ç»™ć‘，而 + 且ć‘没有修改ĺ®ă€‚ + ďĽd）ć‘ç†č§Łĺą¶ĺŚć„Źčż™ä¸Şéˇąç›®ĺ’Śč´ˇçŚ®ćŻĺ…¬ĺĽ€çš„，贡献的记录ďĽĺŚ…ć‹¬ć‘ + 一起ćŹäş¤çš„个人记录，包括 sign-off ）被永久维护并且可以和这个项目 + ć–者开放ćşä»Łç 的许可čŻĺŚćĄĺś°ĺ†ŤĺŹ‘行。 + +é‚ŁäąĺŠ ĺ…Ąčż™ć ·ä¸€čˇŚ:: + + Signed-off-by: Random J Developer <random@developer.example.org> + +ä˝żç”¨ä˝ çš„çśźĺŤďĽćŠ±ć‰ďĽŚä¸Ťč˝ä˝żç”¨ĺ‡ĺŤć–者匿ĺŤă€‚） + +有人在最ĺŽĺŠ ä¸Šć ‡çľă€‚现在这些东西会被忽略，但ćŻä˝ ĺŹŻä»Ąčż™ć ·ĺšďĽŚćťĄć ‡č®°ĺ…¬ĺŹ¸ +内é¨çš„过程，ć–者只ćŻćŚ‡ĺ‡şĺ…łäşŽ sign-off 的一些特殊细节。 + +如果您ćŻĺ系统ć–ĺ†ć”Żç»´ćŠ¤äşşĺ‘，有时需č¦ç¨Ťĺľ®äż®ć”ąć”¶ĺ°çš„补ä¸ďĽŚä»Ąäľżĺ并ĺ®ä»¬ďĽŚ +ĺ› ä¸şć ‘ĺ’ŚćŹäş¤č€…ä¸çš„代ç 不完全相ĺŚă€‚ĺ¦‚ćžśä˝ ä¸Ąć Ľéµĺ®č§„ĺ™ďĽcďĽ‰ďĽŚä˝ ĺş”čŻĄč¦ć±‚ćŹäş¤č€… +重新发ĺ¸ďĽŚä˝†čż™ĺ®Śĺ…¨ćŻĺś¨ćµŞč´ąć—¶é—´ĺ’Śç˛ľĺŠ›ă€‚规ĺ™ďĽb）ĺ…许您č°ć•´ä»Łç ，但ćŻć›´ć”ąä¸€ä¸Ş +ćŹäş¤č€…的代ç 并让他认可您的错误ćŻéťžĺ¸¸ä¸Ťç¤Ľč˛Śçš„。č¦č§Łĺ†łć¤é—®é˘ďĽŚĺ»şč®®ĺś¨ćś€ĺŽä¸€ä¸Ş +ç”±çľĺŤčˇŚĺ’Ść‚¨çš„čˇŚäą‹é—´ć·»ĺŠ ä¸€čˇŚďĽŚćŚ‡ç¤şć›´ć”ąçš„ć€§č´¨ă€‚č™˝ç„¶čż™ĺą¶ä¸ŤćŻĺĽşĺ¶ć€§çš„，但似乎 +ĺś¨ćŹŹčż°ĺ‰ŤĺŠ ä¸Šć‚¨çš„é‚®ä»¶ĺ’Ś/ć–姓ĺŤďĽĺ…¨é¨ç”¨ć–ąć‹¬ĺŹ·ć‹¬čµ·ćťĄďĽ‰ďĽŚčż™č¶łä»Ąč®©äşşćł¨ć„Źĺ°ć‚¨ĺŻąćś€ +ĺŽä¸€ĺ†é’źçš„更改负有责任。例如:: + + Signed-off-by: Random J Developer <random@developer.example.org> + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> + +如果您维护一个稳定的ĺ†ć”Żćśşćž„，ĺŚć—¶ĺ¸Śćś›ĺŻąä˝śč€…进行致谢ă€č·źč¸Şć›´ć”ąă€ĺ并修复并 +保护ćŹäş¤č€…不受投诉，那äąčż™ç§Ťĺšćł•ĺ°¤ĺ…¶ćś‰ç”¨ă€‚请注意，在任何ć…况下é˝ä¸Ťč˝ć›´ć”ąä˝śč€… +çš„IDďĽFrom ĺ¤´ďĽ‰ďĽŚĺ› ä¸şĺ®ćŻĺ‡şçŽ°ĺś¨ć›´ć”ąć—Ąĺż—ä¸çš„ć ‡čŻ†ă€‚ + +对回ĺďĽback-porters）的特ĺ«čŻ´ćŽďĽšĺś¨ćŹäş¤ć¶ćŻçš„顶é¨ďĽä¸»é˘čˇŚäą‹ĺŽďĽ‰ćŹ’ĺ…Ąä¸€ä¸ŞčˇĄä¸ +çš„čµ·ćşćŚ‡ç¤şäĽĽäąŽćŻä¸€ç§Ťĺ¸¸č§ä¸”有用的实践，以便于跟踪。例如，下面ćŻć‘们在3.x稳定 +ç‰ćś¬ä¸çś‹ĺ°çš„内容:: + + Date: Tue Oct 7 07:26:38 2014 -0400 + + libata: Un-break ATA blacklist + + commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. + +čżćś‰ďĽŚ 这里ćŻä¸€ä¸Şć—§ç‰ĺ†…ć ¸ä¸çš„一个回ĺ补ä¸:: + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +12）何时使用Acked-by:，CC:，和Co-Developed by: +---------------------------------------------- + +Singed-off-by: ć ‡č®°čˇ¨ç¤şçľĺŤč€…参与了补ä¸çš„开发，ć–者他/她在补ä¸çš„äĽ é€’č·Żĺľ„ä¸ă€‚ + +如果一个人没有直接参与补ä¸çš„准备ć–处ç†ďĽŚä˝†ĺ¸Śćś›čˇ¨ç¤şĺą¶č®°ĺ˝•ä»–们对补ä¸çš„批准， +é‚Łäąä»–们可以č¦ć±‚在补ä¸çš„ĺŹć›´ć—Ąĺż—ä¸ć·»ĺŠ 一个 Acked-by: + +Acked-by：通常由受影响代ç 的维护者使用，当该维护者既没有贡献也没有转发补ä¸ć—¶ă€‚ + +Acked-by: 不ĺŹçľĺ—äşşé‚Łć ·ćŁĺĽŹă€‚čż™ćŻä¸€ä¸Şč®°ĺ˝•ďĽŚçˇ®č®¤äşşč‡łĺ°‘审查了补ä¸ďĽŚĺą¶čˇ¨ç¤şćŽĄĺŹ—。 +ĺ› ć¤ďĽŚčˇĄä¸ĺ并有时会手动将Acker的“Yep，looks good to me”转换为 Acked-By：ďĽä˝† +请注意，通常最好č¦ć±‚一个ćŽçˇ®çš„Ack）。 + +Acked-by：不一定表示对整个补ä¸çš„确认。例如，如果一个补ä¸ĺ˝±ĺ“Ťĺ¤šä¸Şĺ系统，并且 +有一个：来自一个ĺ系统维护者，那äąčż™é€šĺ¸¸čˇ¨ç¤şĺŹŞçˇ®č®¤ĺ˝±ĺ“Ťç»´ćŠ¤č€…代ç çš„é¨ĺ†ă€‚这里 +应该仔细ĺ¤ć–。如有疑问，应参č€é‚®ä»¶ĺ—表档ćˇä¸çš„原始讨论。 + +如果ćźäşşćś‰ćśşäĽšĺŻąčˇĄä¸čż›čˇŚčŻ„论，但没有ćŹäľ›ć¤ç±»čŻ„论，您可以选择在补ä¸ä¸ć·»ĺŠ ``Cc:`` +čż™ćŻĺ”Żä¸€ä¸€ä¸Şć ‡çľďĽŚĺ®ĺŹŻä»Ąĺś¨ć˛ˇćś‰č˘«ĺ®ĺ‘˝ĺŤçš„äşşćľĺĽŹć“Ťä˝śçš„ć…ĺ†µä¸‹ć·»ĺŠ ďĽŚä˝†ĺ®ĺş”čŻĄčˇ¨ćŽ +这个人ćŻĺś¨čˇĄä¸ä¸ŠćŠ„é€çš„。讨论ä¸ĺŚ…ĺ«äş†ć˝śĺś¨ĺ©ç›Šç›¸ĺ…łć–ąă€‚ + +Co-developed-by: 声ćŽčˇĄä¸ćŻç”±ĺ¤šä¸ŞĺĽ€ĺŹ‘äşşĺ‘ĺ…±ĺŚĺ›ĺ»şçš„ďĽ›ĺ˝“ĺ‡ ä¸Şäşşĺś¨ä¸€ä¸ŞčˇĄä¸ä¸Šĺ·Ą +作时，ĺ®ç”¨äşŽĺ°†ĺ±žć€§čµ‹äşĺ…±ĺŚä˝śč€…ďĽé™¤äş† From: 所赋äşçš„ä˝śč€…äą‹ĺ¤–ďĽ‰ă€‚ĺ› ä¸ş +Co-developed-by: 表示作者身份，所以每个共ĺŚĺĽ€ĺŹ‘人：必须紧跟在相关ĺ作作者的 +çľĺŤäą‹ĺŽă€‚ć ‡ĺ‡†çš„çľć ¸ç¨‹ĺşŹč¦ć±‚ďĽšć ‡č®°çš„çľć ¸éˇşĺşŹĺş”尽可č˝ĺŹŤć 补ä¸çš„时间历史，而不 +管作者ćŻé€ščż‡ From ：čżćŻç”± Co-developed-by: ĺ…±ĺŚĺĽ€ĺŹ‘的。值得注意的ćŻďĽŚćś€ĺŽä¸€ +个çľĺ—人：必须始ç»ćŻćŹäş¤čˇĄä¸çš„开发人ĺ‘。 + +注意，当作者也ćŻç”µĺé‚®ä»¶ć ‡é˘â€śĺŹ‘件人：”行ä¸ĺ—出的人时，“From: ” ć ‡č®°ćŻĺŹŻé€‰çš„。 + +作者ćŹäş¤çš„补ä¸ç¨‹ĺşŹç¤şäľ‹:: + + <changelog> + + Co-developed-by: First Co-Author <first@coauthor.example.org> + Signed-off-by: First Co-Author <first@coauthor.example.org> + Co-developed-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + +ĺ作开发者ćŹäş¤çš„补ä¸ç¤şäľ‹:: + + From: From Author <from@author.example.org> + + <changelog> + + Co-developed-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> + Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> + + +13）使用报告人：ă€ćµ‹čŻ•äşşďĽšă€ĺ®ˇć ¸äşşďĽšă€ĺ»şč®®äşşďĽšă€äż®ĺ¤ŤäşşďĽš +-------------------------------------------------------- + +Reported-by: 给那些发现错误并报告错误的人致谢，ĺ®ĺ¸Śćś›ćż€ĺŠ±ä»–们在将来再次帮助 +ć‘们。请注意，如果bugćŻä»Ąç§ćś‰ć–ąĺĽŹćŠĄĺ‘Šçš„，那äąĺś¨ä˝żç”¨Reported-być ‡č®°äą‹ĺ‰ŤďĽŚčŻ· +ĺ…请求ćťé™ă€‚ + +Tested-by: ć ‡č®°čˇ¨ç¤şčˇĄä¸ĺ·˛ç”±ćŚ‡ĺ®šçš„äşşďĽĺś¨ćźäş›çŽŻĺ˘ä¸ďĽ‰ćĺŠźćµ‹čŻ•ă€‚čż™ä¸Şć ‡çľé€šçźĄ +维护人ĺ‘已经执行了一些测试，为将来的补ä¸ćŹäľ›äş†ä¸€ç§Ťĺ®šä˝Ťćµ‹čŻ•äşşĺ‘的方法，并确 +保测试人ĺ‘的信誉。 + +Reviewed-byďĽšç›¸ĺŹŤďĽŚć ąćŤ®ĺ®ˇćźĄäşşçš„ĺŁ°ćŽďĽŚčˇ¨ćŽčŻĄčˇĄä¸ĺ·˛č˘«ĺ®ˇćźĄĺą¶č˘«č®¤ä¸şćŻĺŹŻćŽĄĺŹ—的： + + +ĺ®ˇćźĄäşşçš„ç›‘çťŁĺŁ°ćŽ +^^^^^^^^^^^^^^^^ + +通过ćŹäľ›ć‘çš„ Reviewed-by，ć‘声ćŽďĽš + + (a) ć‘已经对这个补ä¸čż›čˇŚäş†ä¸€ć¬ˇćŠ€ćśŻĺ®ˇćźĄďĽŚä»ĄčŻ„估ĺ®ćŻĺ¦é€‚ĺ被包ĺ«ĺ° + ä¸»çşżĺ†…ć ¸ä¸ă€‚ + + (b) 与补ä¸ç›¸ĺ…łçš„任何问é˘ă€éˇľč™‘ć–é—®é˘é˝ĺ·˛ĺŹŤé¦ç»™ćŹäş¤č€…。ć‘对ćŹäş¤č€…对 + ć‘的评论的回应感ĺ°ć»ˇć„Źă€‚ + + (c) 虽然这一ćŹäş¤ĺŹŻč˝äĽšć”ąčż›ä¸€äş›ä¸śčĄżďĽŚä˝†ć‘相信，ć¤ć—¶ďĽŚďĽ1ďĽ‰ĺŻąĺ†…ć ¸ + 进行了有价值的修改，ďĽ2）没有包ĺ«äş‰č®şä¸ć¶‰ĺŹŠçš„已知问é˘ă€‚ + + (d) 虽然ć‘已经审查了补ä¸ĺą¶č®¤ä¸şĺ®ćŻĺĄĺ…¨çš„，但ć‘不会ďĽé™¤éťžĺŹ¦ćś‰ćŽçˇ® + 说ćŽďĽ‰ä˝śĺ‡şä»»ä˝•äżťčŻć–äżťčŻĺ®ĺ°†ĺś¨ä»»ä˝•ç»™ĺ®šć…况下实现其规定的目的 + ć–ćŁĺ¸¸čżčˇŚă€‚ + +Reviewed-by ćŻä¸€ç§Ťč§‚点声ćŽďĽŚĺŤłčˇĄä¸ćŻĺŻąĺ†…ć ¸çš„é€‚ĺ˝“äż®ć”ąďĽŚć˛ˇćś‰ä»»ä˝•é—留的严重技术 +é—®é˘ă€‚任何感兴趣的审é…者ďĽĺ®Ść工作的人）é˝ĺŹŻä»Ąä¸şä¸€ä¸ŞčˇĄä¸ćŹäľ›ä¸€ä¸Ş Review-by +ć ‡çľă€‚ć¤ć ‡çľç”¨äşŽĺ‘审é…者ćŹäľ›č‡´č°˘ďĽŚĺą¶é€šçźĄç»´ćŠ¤č€…已在修补程序上完ć的审é…程度。 +Reviewed-by: 当由已知了解主é˘ĺŚşĺźźĺą¶ć‰§čˇŚĺ˝»ĺş•ćŁ€ćźĄçš„审é…者ćŹäľ›ć—¶ďĽŚé€šĺ¸¸äĽšĺ˘žĺŠ +补ä¸čż›ĺ…Ąĺ†…ć ¸çš„ĺŹŻč˝ć€§ă€‚ + +Suggested-by: 表示补ä¸çš„ćłćł•ćŻç”±ćŚ‡ĺ®šçš„äşşćŹĺ‡şçš„，并确保将ć¤ćłćł•ĺ˝’功于指定的 +äşşă€‚čŻ·ćł¨ć„ŹďĽŚćśŞç»Źč®¸ĺŹŻďĽŚä¸Ťĺľ—ć·»ĺŠ ć¤ć ‡çľďĽŚç‰ąĺ«ćŻĺ¦‚果该ćłćł•ćśŞĺś¨ĺ…¬ĺ…±č®şĺť›ä¸ŠĺŹ‘ĺ¸ă€‚ +这就ćŻčŻ´ďĽŚĺ¦‚ćžść‘们勤快地致谢ć‘们的ĺ›ć„Źč€…，他们ĺľćś‰ĺ¸Śćś›ĺś¨ćśŞćťĄĺľ—ĺ°éĽ“čžďĽŚĺ†Ťć¬ˇ +帮助ć‘们。 + +Fixes: 指示补ä¸ĺś¨ä»Ąĺ‰Ťçš„ćŹäş¤ä¸äż®ĺ¤Ťäş†ä¸€ä¸Şé—®é˘ă€‚ĺ®ĺŹŻä»Ąĺľĺ®ąć“地确定错误的来ćşďĽŚ +čż™ćś‰ĺŠ©äşŽćŁ€ćźĄé”™čŻŻäż®ĺ¤Ťă€‚čż™ä¸Şć ‡č®°čżĺ¸®ĺŠ©ç¨łĺ®šĺ†…ć ¸ĺ›˘éźçˇ®ĺ®šĺş”čŻĄćŽĄć”¶äż®ĺ¤Ťçš„ç¨łĺ®šĺ†…ć ¸ +ç‰ćś¬ă€‚čż™ćŻćŚ‡ç¤şčˇĄä¸äż®ĺ¤Ťçš„é”™čŻŻçš„é¦–é€‰ć–ąćł•ă€‚čŻ·ĺŹ‚é… :ref:`cn_describe_changes` +描述您的更改以了解更多详细信ćŻă€‚ + +.. _cn_the_canonical_patch_format: + +12ďĽ‰ć ‡ĺ‡†čˇĄä¸ć ĽĺĽŹ +---------------- + +ćś¬čŠ‚ćŹŹčż°ĺ¦‚ä˝•ć ĽĺĽŹĺŚ–čˇĄä¸ćś¬čş«ă€‚请注意，如果您的补ä¸ĺ储在 ``Git`` ĺ储库ä¸ďĽŚĺ™ +可以使用 ``git format-patch`` 进行ćŁçˇ®çš„补ä¸ć ĽĺĽŹč®ľç˝®ă€‚但ćŻďĽŚčż™äş›ĺ·Ąĺ…·ć— ćł•ĺ›ĺ»ş +ĺż…č¦çš„ć–‡ćś¬ďĽŚĺ› ć¤čŻ·ĺŠˇĺż…é…读下面的说ćŽă€‚ + +ć ‡ĺ‡†çš„čˇĄä¸ďĽŚć ‡é˘čˇŚćŻ:: + + Subject: [PATCH 001/123] ĺ系统:一句话概述 + +ć ‡ĺ‡†čˇĄä¸çš„信体ĺ在如下é¨ĺ†ďĽš + + - 一个 "from" 行指出补ä¸ä˝śč€…。ĺŽč·źç©şčˇŚďĽä»…当发é€äż®čˇĄç¨‹ĺşŹçš„人不ćŻä˝śč€…时才需č¦ďĽ‰ă€‚ + + - 解释的ćŁć–‡ďĽŚčˇŚä»Ą75ĺ—包装，这将被复ĺ¶ĺ°ć°¸äą…ĺŹć›´ć—Ąĺż—来描述这个补ä¸ă€‚ + + - 一个空行 + + - 上面描述的“Signed-off-by” 行，也将出现在更改日志ä¸ă€‚ + + - ĺŹŞĺŚ…ĺ« ``---`` çš„ć ‡č®°çşżă€‚ + + - 任何其他不适ĺ放在ĺŹć›´ć—Ąĺż—的注释。 + + - 实际补ä¸ďĽ ``diff`` 输出）。 + +ć ‡é˘čˇŚçš„ć ĽĺĽŹďĽŚä˝żĺľ—ĺŻąć ‡é˘čˇŚćŚ‰ĺ—ćŻŤĺşŹćŽ’ĺşŹéťžĺ¸¸çš„ĺ®ąć“ - ĺľĺ¤š e-mail 客ć·ç«Żé˝ +ĺŹŻä»Ąć”ŻćŚ - ĺ› ä¸şĺşŹĺ—号ćŻç”¨é›¶ĺˇ«ĺ……的，所以按数ĺ—排序和按ĺ—母排序ćŻä¸€ć ·çš„。 + +e-mail ć ‡é˘ä¸çš„“ĺçł»ç»źâ€ťć ‡čŻ†ĺ“Şä¸Şĺ†…ć ¸ĺ系统将被打补ä¸ă€‚ + +e-mail ć ‡é˘ä¸çš„“一句话概述”扼č¦çš„描述 e-mail ä¸çš„补ä¸ă€‚“一句话概述” +不应该ćŻä¸€ä¸Şć–‡ä»¶ĺŤă€‚对于一个补ä¸çł»ĺ—ďĽâ€śčˇĄä¸çł»ĺ—”指一系ĺ—的多个相关补 +ä¸ďĽ‰ďĽŚä¸Ťč¦ĺŻąćŻŹä¸ŞčˇĄä¸é˝ä˝żç”¨ĺŚć ·çš„“一句话概述”。 + +记住 e-mail 的“一句话概述”会ć为该补ä¸çš„ĺ…¨ĺ±€ĺ”Żä¸€ć ‡čŻ†ă€‚ĺ®äĽšč”“ĺ»¶ĺ° git +的改动记录里。然ĺŽâ€śä¸€ĺŹĄčŻťć¦‚述”会被用在开发者的讨论里，用来指代这个补 +ä¸ă€‚用ć·ĺ°†ĺ¸Śćś›é€ščż‡ google 来ćśç´˘"一句话概述"来找ĺ°é‚Łäş›č®¨č®şčż™ä¸ŞčˇĄä¸çš„ć–‡ +ç« ă€‚ĺ˝“äşşä»¬ĺś¨ä¸¤ä¸‰ä¸ŞćśĺŽä˝żç”¨čŻ¸ĺ¦‚ ``gitk`` ć– ``git log --oneline`` äą‹ç±» +的工具查看数ĺŤä¸ŞčˇĄä¸ć—¶ďĽŚäąźäĽšĺľĺż«çś‹ĺ°ĺ®ă€‚ + +ĺ‡şäşŽčż™äş›ĺŽźĺ› ďĽŚć¦‚čż°ĺż…éˇ»ä¸Ťč¶…čż‡70-75个ĺ—符，并且必须描述补ä¸çš„更改以及为 +什äąéś€č¦čˇĄä¸ă€‚ć—˘č¦ç®€ć´ĺŹč¦ćŹŹčż°ć€§ĺľćś‰ćŚ‘ćć€§ďĽŚä˝†ĺ†™ĺľ—ĺĄ˝çš„ć¦‚čż°ĺş”čŻĄčż™ć ·ĺšă€‚ + +概述的前缀可以用方括号括起来：“Subject: [PATCH <tag>...] <概述>â€ťă€‚ć ‡č®° +不被视为概述的一é¨ĺ†ďĽŚč€ŚćŻćŹŹčż°ĺş”该如何处ç†čˇĄä¸ă€‚如果补ä¸çš„多个ç‰ćś¬ĺ·˛ĺŹ‘ +é€ĺ‡şćťĄä»Ąĺ“Ťĺş”评审ďĽĺŤłâ€śv1，v2，v3”）ć–“rfc”，以指示评审请求，那äąé€šç”¨ć ‡č®° +可č˝ĺŚ…括ç‰ćś¬ćŹŹčż°ç¬¦ă€‚如果一个补ä¸çł»ĺ—ä¸ćś‰ĺ››ä¸ŞčˇĄä¸ďĽŚé‚Łäąĺ„个补ä¸ĺŹŻä»Ąčż™ć · +编号：1/4ă€2/4ă€3/4ă€4/4。这可以确保开发人ĺ‘了解补ä¸ĺş”用的顺序，并且他们 +已经查看ć–应用了补ä¸çł»ĺ—ä¸çš„所有补ä¸ă€‚ + +ä¸€äş›ć ‡é˘çš„äľ‹ĺ:: + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +"From" 行ćŻäżˇä˝“é‡Śçš„ćś€ä¸Šéť˘ä¸€čˇŚďĽŚĺ…·ćś‰ĺ¦‚ä¸‹ć ĽĺĽŹďĽš + From: Patch Author <author@example.com> + +"From" 行指ćŽĺś¨ć°¸äą…改动日志里，č°äĽšč˘«çˇ®č®¤ä¸şä˝śč€…。如果没有 "From" 行，那 +äąé‚®ä»¶ĺ¤´é‡Śçš„ "From: " 行会被用来决定改动日志ä¸çš„作者。 + +说ćŽçš„主é˘ĺ°†äĽšč˘«ćŹäş¤ĺ°ć°¸äą…çš„ćşä»Łç ć”ąĺŠ¨ć—Ąĺż—é‡ŚďĽŚĺ› ć¤ĺŻąé‚Łäş›ć—©ĺ·˛ç»Źä¸Ťč®°ĺľ—ĺ’Ś +这个补ä¸ç›¸ĺ…łçš„讨论细节的有č˝ĺŠ›çš„读者来说，ćŻćś‰ć„Źäą‰çš„。包括补ä¸ç¨‹ĺşŹĺ®šä˝Ť +错误的ďĽĺ†…ć ¸ć—Ąĺż—ć¶ćŻă€OOPSć¶ćŻç‰ďĽ‰ç—‡çŠ¶ďĽŚĺŻąäşŽćśç´˘ćŹäş¤ć—Ąĺż—以寻找适用补ä¸çš„äşş +尤其有用。如果一个补ä¸äż®ĺ¤Ťäş†ä¸€ä¸ŞçĽ–译失败，那äąĺŹŻč˝ä¸Ťéś€č¦ĺŚ…ĺ«ć‰€ćś‰çĽ–译失败； +只č¦č¶łĺ¤źč®©ćśç´˘čˇĄä¸çš„äşşč˝ĺ¤źć‰ľĺ°ĺ®ĺ°±čˇŚäş†ă€‚ä¸Žć¦‚čż°ä¸€ć ·ďĽŚć—˘č¦ç®€ć´ĺŹč¦ćŹŹčż°ć€§ă€‚ + +"---" ć ‡č®°čˇŚĺŻąäşŽčˇĄä¸ĺ¤„ç†ĺ·Ąĺ…·č¦ć‰ľĺ°ĺ“Şé‡ŚćŻć”ąĺŠ¨ć—Ąĺż—信ćŻçš„结束，ćŻä¸ŤĺŹŻçĽşĺ°‘ +的。 + +对于 "---" ć ‡č®°äą‹ĺŽçš„额外注解，一个好的用途就ćŻç”¨ćťĄĺ†™ diffstatďĽŚç”¨ćťĄćľ +示修改了什äąć–‡ä»¶ĺ’ŚćŻŹä¸Şć–‡ä»¶é˝ĺ˘žĺŠ ĺ’Śĺ 除了多少行。diffstat 对于比čľĺ¤§çš„补 +ä¸ç‰ąĺ«ćś‰ç”¨ă€‚其余那些只ćŻĺ’Ść—¶ĺ»ć–者开发者相关的注解，不ĺ适放ĺ°ć°¸äą…的改 +动日志里的，也应该放这里。 +使用 diffstat的选项 "-p 1 -w 70" čż™ć ·ć–‡ä»¶ĺŤĺ°±äĽšä»Žĺ†…ć ¸ćşä»Łç ć ‘çš„ç›®ĺ˝•ĺĽ€ĺ§‹ +ďĽŚä¸ŤäĽšĺŤ ç”¨ĺ¤Şĺ®˝çš„ç©şé—´ďĽĺľĺ®ąć“适ĺ80ĺ—的宽度，也许会有一些缩进。） + +在ĺŽéť˘çš„参č€čµ„ć–™ä¸č˝çś‹ĺ°é€‚当的补ä¸ć ĽĺĽŹçš„更多细节。 + +.. _cn_explicit_in_reply_to: + +15) ćŽçˇ®ĺ›žĺ¤Ťé‚®ä»¶ĺ¤´(In-Reply-To) +------------------------------- + +ć‰‹ĺŠ¨ć·»ĺŠ ĺ›žĺ¤ŤčˇĄä¸çš„çš„ć ‡é˘ĺ¤´(In-Reply_To:) ćŻćś‰ĺ¸®ĺŠ©çš„ďĽäľ‹ĺ¦‚，使用 ``git send-email`` ） +将补ä¸ä¸Žä»Ąĺ‰Ťçš„相关讨论关č”起来，例如，将bug修复程序链接ĺ°ç”µĺ邮件和bug报告。 +但ćŻďĽŚĺŻąäşŽĺ¤ščˇĄä¸çł»ĺ—，最好éżĺ…Ťĺś¨ĺ›žĺ¤Ťć—¶ä˝żç”¨é“ľćŽĄĺ°čŻĄçł»ĺ—çš„ć—§ç‰ćś¬ă€‚čż™ć ·ďĽŚ +补ä¸çš„多个ç‰ćś¬ĺ°±ä¸ŤäĽšć为电ĺ邮件客ć·ç«Żä¸ć— 法管ç†çš„引用序ĺ—。如果链接有用， +可以使用 https://lkml.kernel.org/ 重定ĺ‘器ďĽäľ‹ĺ¦‚，在ĺ°éť˘ç”µĺ邮件文本ä¸ďĽ‰ +链接ĺ°čˇĄä¸çł»ĺ—çš„ć—©ćśźç‰ćś¬ă€‚ + +16) 发é€git pull请求 +-------------------- + +如果您有一系ĺ—补ä¸ďĽŚé‚Łäąč®©ç»´ćŠ¤äşşĺ‘通过git pull操作将ĺ®ä»¬ç›´ćŽĄć‹‰ĺ…Ąĺ系统ĺ储 +库可č˝ćŻćś€ć–ąäľżçš„。但ćŻďĽŚčŻ·ćł¨ć„ŹďĽŚä»ŽĺĽ€ĺŹ‘äşşĺ‘那里获取补ä¸ćŻ”从邮件ĺ—表ä¸čŽ·ĺŹ–补 +ä¸éś€č¦ć›´é«çš„äżˇä»»ĺş¦ă€‚ĺ› ć¤ďĽŚč®¸ĺ¤šĺ系统维护人ĺ‘不愿意接受请求，特ĺ«ćŻćťĄč‡Şć–°çš„ +未知开发人ĺ‘的请求。如果有疑问，您可以在ĺ°éť˘é‚®ä»¶ä¸ä˝żç”¨pull 请求作为补ä¸çł»ĺ— +ćŁĺ¸¸ĺŹ‘ĺ¸çš„一个选项，让维护人ĺ‘可以选择使用其ä¸äą‹ä¸€ă€‚ + +pull 请求的主é˘čˇŚä¸ĺş”该有[Git Pull]。请求本身应该在一行ä¸ĺŚ…ĺ«ĺ储库ĺŤç§°ĺ’Ś +感兴趣的ĺ†ć”ŻďĽ›ĺ®ĺş”该看起来ĺŹ:: + + Please pull from + + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus + + to get these changes: + + +pull 请求čżĺş”该包ĺ«ä¸€ćťˇć•´ä˝“ć¶ćŻďĽŚčŻ´ćŽčŻ·ć±‚ä¸ĺ°†ĺŚ…ĺ«ä»€äąďĽŚä¸€ä¸ŞčˇĄä¸ćś¬čş«çš„ ``Git shortlog`` +以及一个ćľç¤şčˇĄä¸çł»ĺ—整体ć•ćžśçš„ ``diffstat`` 。当然，将所有这些信ćŻć”¶é›†ĺś¨ä¸€čµ· +的最简单方法ćŻč®© ``git`` 使用 ``git request-pull`` 命令为您完ć这些工作。 + +一些维护人ĺ‘ďĽĺŚ…括Linus）希望看ĺ°ćťĄč‡Şĺ·˛çľĺŤćŹäş¤çš„čŻ·ć±‚ďĽ›čż™ĺ˘žĺŠ äş†ä»–ä»¬ĺŻąä˝ çš„ +请求信ĺżă€‚特ĺ«ćŻďĽŚĺś¨ć˛ˇćś‰çľĺŤć ‡çľçš„ć…况下，Linus ä¸ŤäĽšä»ŽĺŹ Github čż™ć ·çš„ĺ…¬ĺ…± +ć‰ç®ˇç«™ç‚ąć‹‰čŻ·ć±‚。 + +ĺ›ĺ»şć¤ç±»çľĺŤçš„第一ćĄćŻç”źć一个 GNRPG 密钥，并由一个ć–ĺ¤šä¸Şć ¸ĺżĺ†…ć ¸ĺĽ€ĺŹ‘äşşĺ‘对 +其进行çľĺŤă€‚这一ćĄĺŻąć–°ĺĽ€ĺŹ‘äşşĺ‘来说可č˝ĺľĺ›°éšľďĽŚä˝†ć˛ˇćś‰ĺŠžćł•ç»•čż‡ĺ®ă€‚ĺŹ‚ĺŠ äĽšč®®ćŻ +找ĺ°ĺŹŻä»Ąçľç˝˛ć‚¨çš„密钥的开发人ĺ‘的好方法。 + +一旦您在Git ä¸ĺ‡†ĺ¤‡äş†ä¸€ä¸Şć‚¨ĺ¸Śćś›ćś‰äşşć‹‰çš„补ä¸çł»ĺ—，就用 ``git tag -s`` ĺ›ĺ»şä¸€ +个çľĺŤć ‡č®°ă€‚这将ĺ›ĺ»şä¸€ä¸Şć–°ć ‡č®°ďĽŚć ‡čŻ†čŻĄçł»ĺ—ä¸çš„最ĺŽä¸€ć¬ˇćŹäş¤ďĽŚĺą¶ĺŚ…ĺ«ç”¨ć‚¨çš„ç§ +é’Ąĺ›ĺ»şçš„çľĺŤă€‚您čżĺŹŻä»Ąĺ°†changelogć ·ĺĽŹçš„ć¶ćŻć·»ĺŠ ĺ°ć ‡č®°ä¸ďĽ›čż™ćŻä¸€ä¸ŞćŹŹčż°ć‹‰čŻ·ć±‚ +整体ć•ćžśçš„ç†ćłä˝Ťç˝®ă€‚ + +如果维护人ĺ‘ĺ°†č¦ä»Žä¸ćŹĺŹ–çš„ć ‘ä¸ŤćŻć‚¨ćŁĺś¨ä˝żç”¨çš„ĺ储库，请不č¦ĺżč®°ĺ°†ĺ·˛çľĺŤçš„ć ‡č®° +ćľĺĽŹćŽ¨é€ĺ°ĺ…¬ĺ…±ć ‘。 + +生ć拉请求时，请使用已çľĺŤçš„ć ‡č®°ä˝śä¸şç›®ć ‡ă€‚čż™ć ·çš„ĺ‘˝ä»¤ĺŹŻä»Ąĺ®žçŽ°:: + + git request-pull master git://my.public.tree/linux.git my-signed-tag + +参č€ć–‡çŚ® +-------- + +Andrew Morton, "The perfect patch" (tpp). + <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/linux/maintainer.html> + + <http://www.kroah.com/log/linux/maintainer-02.html> + + <http://www.kroah.com/log/linux/maintainer-03.html> + + <http://www.kroah.com/log/linux/maintainer-04.html> + + <http://www.kroah.com/log/linux/maintainer-05.html> + + <http://www.kroah.com/log/linux/maintainer-06.html> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + <https://lkml.org/lkml/2005/7/11/336> + +Kernel Documentation/process/coding-style.rst: + :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` + +Linus Torvalds's mail on the canonical patch format: + <http://lkml.org/lkml/2005/4/7/183> + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + + http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/zh_CN/volatile-considered-harmful.txt b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst index 475125967197..48b32ce58ef1 100644 --- a/Documentation/translations/zh_CN/volatile-considered-harmful.txt +++ b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst @@ -1,30 +1,23 @@ -Chinese translated version of Documentation/process/volatile-considered-harmful.rst +.. _cn_volatile_considered_harmful: -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. +.. include:: ../disclaimer-zh_CN.rst -Maintainer: Jonathan Corbet <corbet@lwn.net> -Chinese maintainer: Bryan Wu <bryan.wu@analog.com> ---------------------------------------------------------------------- -Documentation/process/volatile-considered-harmful.rst çš„ä¸ć–‡çż»čŻ‘ +:Original: :ref:`Documentation/process/volatile-considered-harmful.rst + <volatile_considered_harmful>` 如果ćłčŻ„论ć–更新本文的内容，请直接č”çł»ĺŽźć–‡ćˇŁçš„ç»´ćŠ¤č€…ă€‚ĺ¦‚ćžśä˝ ä˝żç”¨č‹±ć–‡ 交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 -译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 +译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…:: -英文ç‰ç»´ćŠ¤č€…： Jonathan Corbet <corbet@lwn.net> -ä¸ć–‡ç‰ç»´ćŠ¤č€…： 伍鹏 Bryan Wu <bryan.wu@analog.com> -ä¸ć–‡ç‰çż»čŻ‘者： 伍鹏 Bryan Wu <bryan.wu@analog.com> -ä¸ć–‡ç‰ć ˇčŻ‘者： ĺĽ ć±‰čľ‰ Eugene Teo <eugeneteo@kernel.sg> - 杨瑞 Dave Young <hidave.darkstar@gmail.com> -以下为ćŁć–‡ ---------------------------------------------------------------------- + 英文ç‰ç»´ćŠ¤č€…： Jonathan Corbet <corbet@lwn.net> + ä¸ć–‡ç‰ç»´ćŠ¤č€…： 伍鹏 Bryan Wu <bryan.wu@analog.com> + ä¸ć–‡ç‰çż»čŻ‘者： 伍鹏 Bryan Wu <bryan.wu@analog.com> + ä¸ć–‡ç‰ć ˇčŻ‘者： ĺĽ ć±‰čľ‰ Eugene Teo <eugeneteo@kernel.sg> + 杨瑞 Dave Young <hidave.darkstar@gmail.com> + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> 为什äąä¸Ťĺş”该使用“volatile”类型 ------------------------------- +============================== C程序ĺ‘通常认为volatile表示ćźä¸ŞĺŹé‡ŹĺŹŻä»Ąĺś¨ĺ˝“前执行的线程之外被改ĺŹďĽ›ĺ› ć¤ďĽŚĺś¨ĺ†…ć ¸ ä¸ç”¨ĺ°ĺ…±äş«ć•°ćŤ®ç»“构时，常常会有C程序ĺ‘喜欢使用volatile这类ĺŹé‡Źă€‚换句话说，他们经 @@ -41,7 +34,7 @@ C程序ĺ‘通常认为volatile表示ćźä¸ŞĺŹé‡ŹĺŹŻä»Ąĺś¨ĺ˝“ĺ‰Ťć‰§čˇŚçš„çşżç¨‹äą ĺż…č¦ĺ†Ťä˝żç”¨volatile。如果仍然必须使用volatile，那äąĺ‡ 乎可以肯定在代ç çš„ćźĺ¤„有一 个bug。在ćŁçˇ®č®ľč®ˇçš„ĺ†…ć ¸ä»Łç ä¸ďĽŚvolatileč˝ĺ¸¦ćťĄçš„ä»…ä»…ćŻä˝żäş‹ć…ĺŹć…˘ă€‚ -思č€ä¸€ä¸‹čż™ć®µĺ…¸ĺž‹çš„ĺ†…ć ¸ä»Łç ： +思č€ä¸€ä¸‹čż™ć®µĺ…¸ĺž‹çš„ĺ†…ć ¸ä»Łç :: spin_lock(&the_lock); do_something_on(&shared_data); @@ -66,7 +59,7 @@ volatileçš„ĺ储类型最ĺťćŻä¸şé‚Łäş›ĺ†…ĺć ĺ°„çš„I/O寄ĺ器而定义。 ćŻĺż…需的。 另一种引起用ć·ĺŹŻč˝ä˝żç”¨volatileçš„ć…况ćŻĺ˝“处ç†ĺ™¨ćŁĺż™çť€ç‰ĺľ…一个ĺŹé‡Źçš„值。ćŁçˇ®ć‰§čˇŚä¸€ -个忙ç‰ĺľ…çš„ć–ąćł•ćŻďĽš +个忙ç‰ĺľ…çš„ć–ąćł•ćŻ:: while (my_variable != what_i_want) cpu_relax(); diff --git a/Documentation/translations/zh_CN/sparse.txt b/Documentation/translations/zh_CN/sparse.txt index 2f728962a8e2..47fc4a06ebe8 100644 --- a/Documentation/translations/zh_CN/sparse.txt +++ b/Documentation/translations/zh_CN/sparse.txt @@ -6,7 +6,7 @@ communicating in English you can also ask the Chinese maintainer for help. Contact the Chinese maintainer if this translation is outdated or if there is a problem with the translation. -Chinese maintainer: Li Yang <leo@zh-kernel.org> +Chinese maintainer: Li Yang <leoyang.li@nxp.com> --------------------------------------------------------------------- Documentation/dev-tools/sparse.rst çš„ä¸ć–‡çż»čŻ‘ @@ -14,8 +14,8 @@ Documentation/dev-tools/sparse.rst çš„ä¸ć–‡çż»čŻ‘ 交ćµćś‰ĺ›°éšľçš„话，也可以ĺ‘ä¸ć–‡ç‰ç»´ćŠ¤č€…求助。如果本翻译更新不及时ć–者翻 译ĺ在问é˘ďĽŚčŻ·č”çł»ä¸ć–‡ç‰ç»´ćŠ¤č€…。 -ä¸ć–‡ç‰ç»´ćŠ¤č€…： ćťŽéł Li Yang <leo@zh-kernel.org> -ä¸ć–‡ç‰çż»čŻ‘者： ćťŽéł Li Yang <leo@zh-kernel.org> +ä¸ć–‡ç‰ç»´ćŠ¤č€…： ćťŽéł Li Yang <leoyang.li@nxp.com> +ä¸ć–‡ç‰çż»čŻ‘者： ćťŽéł Li Yang <leoyang.li@nxp.com> 以下为ćŁć–‡ diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.txt index 51b4ff031586..1ee82419d8aa 100644 --- a/Documentation/unaligned-memory-access.txt +++ b/Documentation/unaligned-memory-access.txt @@ -1,5 +1,5 @@ ========================= -UNALIGNED MEMORY ACCESSES +Unaligned Memory Accesses ========================= :Author: Daniel Drake <dsd@gentoo.org>, diff --git a/Documentation/usb/WUSB-Design-overview.txt b/Documentation/usb/WUSB-Design-overview.txt index fdb47637720e..dc5e21609bb5 100644 --- a/Documentation/usb/WUSB-Design-overview.txt +++ b/Documentation/usb/WUSB-Design-overview.txt @@ -1,7 +1,9 @@ - +================================ Linux UWB + Wireless USB + WiNET +================================ + + Copyright (C) 2005-2006 Intel Corporation - (C) 2005-2006 Intel Corporation Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> This program is free software; you can redistribute it and/or @@ -29,6 +31,7 @@ drivers for the USB based UWB radio controllers defined in the Wireless USB 1.0 specification (including Wireless USB host controller and an Intel WiNET controller). +.. Contents 1. Introduction 1. HWA: Host Wire adapters, your Wireless USB dongle @@ -51,7 +54,8 @@ and an Intel WiNET controller). 4. Glossary - Introduction +Introduction +============ UWB is a wide-band communication protocol that is to serve also as the low-level protocol for others (much like TCP sits on IP). Currently @@ -93,7 +97,8 @@ The different logical parts of this driver are: do the actual WUSB. - HWA: Host Wire adapters, your Wireless USB dongle +HWA: Host Wire adapters, your Wireless USB dongle +------------------------------------------------- WUSB also defines a device called a Host Wire Adaptor (HWA), which in mere terms is a USB dongle that enables your PC to have UWB and Wireless @@ -125,7 +130,8 @@ The HWA itself is broken in two or three main interfaces: their type and kick into gear. - DWA: Device Wired Adaptor, a Wireless USB hub for wired devices +DWA: Device Wired Adaptor, a Wireless USB hub for wired devices +--------------------------------------------------------------- These are the complement to HWAs. They are a USB host for connecting wired devices, but it is connected to your PC connected via Wireless @@ -137,7 +143,8 @@ code with the HWA-RC driver; there is a bunch of factorization work that has been done to support that in upcoming releases. - WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter +WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter +------------------------------------------------------------------- This is your usual PCI device that implements WHCI. Similar in concept to EHCI, it allows your wireless USB devices (including DWAs) to connect @@ -148,7 +155,8 @@ There is still no driver support for this, but will be in upcoming releases. - The UWB stack +The UWB stack +============= The main mission of the UWB stack is to keep a tally of which devices are in radio proximity to allow drivers to connect to them. As well, it @@ -156,7 +164,8 @@ provides an API for controlling the local radio controllers (RCs from now on), such as to start/stop beaconing, scan, allocate bandwidth, etc. - Devices and hosts: the basic structure +Devices and hosts: the basic structure +-------------------------------------- The main building block here is the UWB device (struct uwb_dev). For each device that pops up in radio presence (ie: the UWB host receives a @@ -187,7 +196,8 @@ the USB connected HWA. Eventually, drivers/whci-rc.c will do the same for the PCI connected WHCI controller. - Host Controller life cycle +Host Controller life cycle +-------------------------- So let's say we connect a dongle to the system: it is detected and firmware uploaded if needed [for Intel's i1480 @@ -209,7 +219,8 @@ When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/ takes time of tearing everything down safely (or not...). - On the air: beacons and enumerating the radio neighborhood +On the air: beacons and enumerating the radio neighborhood +---------------------------------------------------------- So assuming we have devices and we have agreed for a channel to connect on (let's say 9), we put the new RC to beacon: @@ -235,12 +246,14 @@ are received in some time, the device is considered gone and wiped out the beacon cache of dead devices]. - Device lists +Device lists +------------ All UWB devices are kept in the list of the struct bus_type uwb_bus_type. - Bandwidth allocation +Bandwidth allocation +-------------------- The UWB stack maintains a local copy of DRP availability through processing of incoming *DRP Availability Change* notifications. This @@ -260,7 +273,8 @@ completion. [Note: The bandwidth reservation work is in progress and subject to change.] - Wireless USB Host Controller drivers +Wireless USB Host Controller drivers +==================================== *WARNING* This section needs a lot of work! @@ -296,7 +310,8 @@ starts sending MMCs. Now it all depends on external stimuli. -*New device connection* +New device connection +--------------------- A new device pops up, it scans the radio looking for MMCs that give out the existence of Wireless USB channels. Once one (or more) are found, @@ -322,7 +337,8 @@ has seen the port status changes, as we have been toggling them. It will start enumerating and doing transfers through usb_hcd->urb_enqueue() to read descriptors and move our data. -*Device life cycle and keep alives* +Device life cycle and keep alives +--------------------------------- Every time there is a successful transfer to/from a device, we update a per-device activity timestamp. If not, every now and then we check and @@ -340,7 +356,8 @@ device list looking for whom needs refreshing. If the device wants to disconnect, it will either die (ugly) or send a /DN_Disconnect/ that will prompt a disconnection from the system. -*Sending and receiving data* +Sending and receiving data +-------------------------- Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is /aimed/ at an endpoint in a WUSB device. This is the same for HWAs and @@ -394,7 +411,8 @@ finalize the transfer. For IN xfers, we only issue URBs for the segments we want to read and then wait for the xfer result data. -*URB mapping into xfers* +URB mapping into xfers +^^^^^^^^^^^^^^^^^^^^^^ This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an rpipe to the endpoint where we have to transmit, create a transfer @@ -407,7 +425,8 @@ and not yet done and when all that is done, the xfer callback will be called--this will call the URB callback. - Glossary +Glossary +======== *DWA* -- Device Wire Adapter @@ -436,4 +455,3 @@ the host. Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by InakyPerezGonzalez) - diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt index 903abca10517..e8bda98e9b51 100644 --- a/Documentation/usb/acm.txt +++ b/Documentation/usb/acm.txt @@ -1,127 +1,131 @@ - Linux ACM driver v0.16 - (c) 1999 Vojtech Pavlik <vojtech@suse.cz> - Sponsored by SuSE ----------------------------------------------------------------------------- +====================== +Linux ACM driver v0.16 +====================== + +Copyright (c) 1999 Vojtech Pavlik <vojtech@suse.cz> + +Sponsored by SuSE 0. Disclaimer ~~~~~~~~~~~~~ - This program is free software; you can redistribute it and/or modify it +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 +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 +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@suse.cz>, or by paper mail: Vojtech Pavlik, +Should you need to contact me, the author, you can do so either by e-mail - +mail your message to <vojtech@suse.cz>, or by paper mail: Vojtech Pavlik, Ucitelska 1576, Prague 8, 182 00 Czech Republic - For your convenience, the GNU General Public License version 2 is included +For your convenience, the GNU General Public License version 2 is included in the package: See the file COPYING. 1. Usage ~~~~~~~~ - The drivers/usb/class/cdc-acm.c drivers works with USB modems and USB ISDN terminal +The drivers/usb/class/cdc-acm.c drivers works with USB modems and USB ISDN terminal adapters that conform to the Universal Serial Bus Communication Device Class Abstract Control Model (USB CDC ACM) specification. - Many modems do, here is a list of those I know of: +Many modems do, here is a list of those I know of: - 3Com OfficeConnect 56k - 3Com Voice FaxModem Pro - 3Com Sportster - MultiTech MultiModem 56k - Zoom 2986L FaxModem - Compaq 56k FaxModem - ELSA Microlink 56k + - 3Com OfficeConnect 56k + - 3Com Voice FaxModem Pro + - 3Com Sportster + - MultiTech MultiModem 56k + - Zoom 2986L FaxModem + - Compaq 56k FaxModem + - ELSA Microlink 56k - I know of one ISDN TA that does work with the acm driver: +I know of one ISDN TA that does work with the acm driver: - 3Com USR ISDN Pro TA + - 3Com USR ISDN Pro TA - Some cell phones also connect via USB. I know the following phones work: +Some cell phones also connect via USB. I know the following phones work: - SonyEricsson K800i + - SonyEricsson K800i - Unfortunately many modems and most ISDN TAs use proprietary interfaces and +Unfortunately many modems and most ISDN TAs use proprietary interfaces and thus won't work with this drivers. Check for ACM compliance before buying. - To use the modems you need these modules loaded: +To use the modems you need these modules loaded:: usbcore.ko uhci-hcd.ko ohci-hcd.ko or ehci-hcd.ko cdc-acm.ko - After that, the modem[s] should be accessible. You should be able to use +After that, the modem[s] should be accessible. You should be able to use minicom, ppp and mgetty with them. 2. Verifying that it works ~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 -B: Alloc= 0/900 us ( 0%), #Int= 0, #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=6800 -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=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 -D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 -P: Vendor=04c1 ProdID=008f Rev= 2.07 -S: Manufacturer=3Com Inc. -S: Product=3Com U.S. Robotics Pro ISDN TA -S: SerialNumber=UFT53A49BVT7 -C: #Ifs= 1 Cfg#= 1 Atr=60 MxPwr= 0mA -I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm -E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms -E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms -E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms -C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr= 0mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm -E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms -I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm -E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms -E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + +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 + B: Alloc= 0/900 us ( 0%), #Int= 0, #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=6800 + 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=01 Lev=01 Prnt=01 Port=01 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 + D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 + P: Vendor=04c1 ProdID=008f Rev= 2.07 + S: Manufacturer=3Com Inc. + S: Product=3Com U.S. Robotics Pro ISDN TA + S: SerialNumber=UFT53A49BVT7 + C: #Ifs= 1 Cfg#= 1 Atr=60 MxPwr= 0mA + I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=acm + E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms + C:* #Ifs= 2 Cfg#= 2 Atr=60 MxPwr= 0mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm + E: Ad=81(I) Atr=03(Int.) MxPS= 16 Ivl=128ms + I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm + E: Ad=85(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms + E: Ad=04(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms The presence of these three lines (and the Cls= 'comm' and 'data' classes) is important, it means it's an ACM device. The Driver=acm means the acm driver is used for the device. If you see only Cls=ff(vend.) then you're out -of luck, you have a device with vendor specific-interface. - -D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 -I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm -I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm - -In the system log you should see: - -usb.c: USB new device connect, assigned device number 2 -usb.c: kmalloc IF c7691fa0, numif 1 -usb.c: kmalloc IF c7b5f3e0, numif 2 -usb.c: skipped 4 class/vendor specific interface descriptors -usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3 -usb.c: USB device number 2 default language ID 0x409 -Manufacturer: 3Com Inc. -Product: 3Com U.S. Robotics Pro ISDN TA -SerialNumber: UFT53A49BVT7 -acm.c: probing config 1 -acm.c: probing config 2 -ttyACM0: USB ACM device -acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0 -acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7 -usb.c: acm driver claimed interface c7b5f3e0 -usb.c: acm driver claimed interface c7b5f3f8 -usb.c: acm driver claimed interface c7691fa0 +of luck, you have a device with vendor specific-interface:: + + D: Ver= 1.00 Cls=02(comm.) Sub=00 Prot=00 MxPS= 8 #Cfgs= 2 + I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm + I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm + +In the system log you should see:: + + usb.c: USB new device connect, assigned device number 2 + usb.c: kmalloc IF c7691fa0, numif 1 + usb.c: kmalloc IF c7b5f3e0, numif 2 + usb.c: skipped 4 class/vendor specific interface descriptors + usb.c: new device strings: Mfr=1, Product=2, SerialNumber=3 + usb.c: USB device number 2 default language ID 0x409 + Manufacturer: 3Com Inc. + Product: 3Com U.S. Robotics Pro ISDN TA + SerialNumber: UFT53A49BVT7 + acm.c: probing config 1 + acm.c: probing config 2 + ttyACM0: USB ACM device + acm.c: acm_control_msg: rq: 0x22 val: 0x0 len: 0x0 result: 0 + acm.c: acm_control_msg: rq: 0x20 val: 0x0 len: 0x7 result: 7 + usb.c: acm driver claimed interface c7b5f3e0 + usb.c: acm driver claimed interface c7b5f3f8 + usb.c: acm driver claimed interface c7691fa0 If all this seems to be OK, fire up minicom and set it to talk to the ttyACM device and try typing 'at'. If it responds with 'OK', then everything is diff --git a/Documentation/usb/authorization.txt b/Documentation/usb/authorization.txt index 9dd1dc7b1009..9e53909d04c2 100644 --- a/Documentation/usb/authorization.txt +++ b/Documentation/usb/authorization.txt @@ -1,7 +1,8 @@ - +============================================================== Authorizing (or not) your USB devices to connect to the system +============================================================== -(C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation +Copyright (C) 2007 Inaky Perez-Gonzalez <inaky@linux.intel.com> Intel Corporation This feature allows you to control if a USB device can be used (or not) in a system. This feature will allow you to implement a lock-down @@ -12,24 +13,25 @@ its interfaces are immediately made available to the users. With this modification, only if root authorizes the device to be configured will then it be possible to use it. -Usage: +Usage +===== -Authorize a device to connect: +Authorize a device to connect:: -$ echo 1 > /sys/bus/usb/devices/DEVICE/authorized + $ echo 1 > /sys/bus/usb/devices/DEVICE/authorized -Deauthorize a device: +De-authorize a device:: -$ echo 0 > /sys/bus/usb/devices/DEVICE/authorized + $ echo 0 > /sys/bus/usb/devices/DEVICE/authorized Set new devices connected to hostX to be deauthorized by default (ie: -lock down): +lock down):: -$ echo 0 > /sys/bus/usb/devices/usbX/authorized_default + $ echo 0 > /sys/bus/usb/devices/usbX/authorized_default -Remove the lock down: +Remove the lock down:: -$ echo 1 > /sys/bus/usb/devices/usbX/authorized_default + $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default By default, Wired USB devices are authorized by default to connect. Wireless USB hosts deauthorize by default all new connected @@ -40,21 +42,21 @@ USB ports. Example system lockdown (lame) ------------------------ +------------------------------ Imagine you want to implement a lockdown so only devices of type XYZ can be connected (for example, it is a kiosk machine with a visible -USB port): +USB port):: -boot up -rc.local -> + boot up + rc.local -> - for host in /sys/bus/usb/devices/usb* - do - echo 0 > $host/authorized_default - done + for host in /sys/bus/usb/devices/usb* + do + echo 0 > $host/authorized_default + done -Hookup an script to udev, for new USB devices +Hookup an script to udev, for new USB devices:: if device_is_my_type $DEV then @@ -67,10 +69,10 @@ checking if the class, type and protocol match something is the worse security verification you can make (or the best, for someone willing to break it). If you need something secure, use crypto and Certificate Authentication or stuff like that. Something simple for an storage key -could be: +could be:: -function device_is_my_type() -{ + function device_is_my_type() + { echo 1 > authorized # temporarily authorize it # FIXME: make sure none can mount it mount DEVICENODE /mntpoint @@ -83,7 +85,7 @@ function device_is_my_type() else echo 0 > authorized fi -} + } Of course, this is lame, you'd want to do a real certificate @@ -95,30 +97,35 @@ welcome. Interface authorization ----------------------- + There is a similar approach to allow or deny specific USB interfaces. That allows to block only a subset of an USB device. -Authorize an interface: -$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized +Authorize an interface:: -Deauthorize an interface: -$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized + $ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized + +Deauthorize an interface:: + + $ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized The default value for new interfaces on a particular USB bus can be changed, too. -Allow interfaces per default: -$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default +Allow interfaces per default:: + + $ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default + +Deny interfaces per default:: -Deny interfaces per default: -$ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default + $ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default Per default the interface_authorized_default bit is 1. So all interfaces would authorized per default. Note: -If a deauthorized interface will be authorized so the driver probing must -be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe + If a deauthorized interface will be authorized so the driver probing must + be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe For drivers that need multiple interfaces all needed interfaces should be authorized first. After that the drivers should be probed. diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt index d1eedc01b00a..68473abe2823 100644 --- a/Documentation/usb/chipidea.txt +++ b/Documentation/usb/chipidea.txt @@ -1,22 +1,37 @@ +============================================== +ChipIdea Highspeed Dual Role Controller Driver +============================================== + 1. How to test OTG FSM(HNP and SRP) ----------------------------------- + To show how to demo OTG HNP and SRP functions via sys input files with 2 Freescale i.MX6Q sabre SD boards. 1.1 How to enable OTG FSM ---------------------------------------- +------------------------- + 1.1.1 Select CONFIG_USB_OTG_FSM in menuconfig, rebuild kernel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Image and modules. If you want to check some internal variables for otg fsm, mount debugfs, there are 2 files -which can show otg fsm variables and some controller registers value: -cat /sys/kernel/debug/ci_hdrc.0/otg -cat /sys/kernel/debug/ci_hdrc.0/registers +which can show otg fsm variables and some controller registers value:: + + cat /sys/kernel/debug/ci_hdrc.0/otg + cat /sys/kernel/debug/ci_hdrc.0/registers + 1.1.2 Add below entries in your dts file for your controller node +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + otg-rev = <0x0200>; adp-disable; 1.2 Test operations ------------------- + 1) Power up 2 Freescale i.MX6Q sabre SD boards with gadget class driver loaded (e.g. g_mass_storage). @@ -26,19 +41,24 @@ cat /sys/kernel/debug/ci_hdrc.0/registers The A-device(with micro A plug inserted) should enumerate B-device. 3) Role switch - On B-device: - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + On B-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req B-device should take host role and enumerate A-device. 4) A-device switch back to host. - On B-device: - echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + On B-device:: + + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req or, by introducing HNP polling, B-Host can know when A-peripheral wish to be host role, so this role switch also can be trigged in A-peripheral - side by answering the polling from B-Host, this can be done on A-device: - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req + side by answering the polling from B-Host, this can be done on A-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req A-device should switch back to host and enumerate B-device. @@ -49,23 +69,31 @@ cat /sys/kernel/debug/ci_hdrc.0/registers A-device should NOT enumerate B-device. if A-device wants to use bus: - On A-device: - echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req + + On A-device:: + + echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req if B-device wants to use bus: - On B-device: - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + On B-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req 7) A-device power down the bus. - On A-device: - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop + + On A-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop A-device should disconnect with B-device and power down the bus. 8) B-device does data pulse for SRP. - On B-device: - echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + + On B-device:: + + echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req A-device should resume usb bus and enumerate B-device. @@ -75,22 +103,31 @@ cat /sys/kernel/debug/ci_hdrc.0/registers July 27, 2012 Revision 2.0 version 1.1a" 2. How to enable USB as system wakeup source ------------------------------------ +-------------------------------------------- Below is the example for how to enable USB as system wakeup source at imx6 platform. -2.1 Enable core's wakeup -echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup -2.2 Enable glue layer's wakeup -echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup -2.3 Enable PHY's wakeup (optional) -echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup -2.4 Enable roothub's wakeup -echo enabled > /sys/bus/usb/devices/usb1/power/wakeup -2.5 Enable related device's wakeup -echo enabled > /sys/bus/usb/devices/1-1/power/wakeup +2.1 Enable core's wakeup:: + + echo enabled > /sys/bus/platform/devices/ci_hdrc.0/power/wakeup + +2.2 Enable glue layer's wakeup:: + + echo enabled > /sys/bus/platform/devices/2184000.usb/power/wakeup + +2.3 Enable PHY's wakeup (optional):: + + echo enabled > /sys/bus/platform/devices/20c9000.usbphy/power/wakeup + +2.4 Enable roothub's wakeup:: + + echo enabled > /sys/bus/usb/devices/usb1/power/wakeup + +2.5 Enable related device's wakeup:: + + echo enabled > /sys/bus/usb/devices/1-1/power/wakeup If the system has only one usb port, and you want usb wakeup at this port, you -can use below script to enable usb wakeup. -for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; +can use below script to enable usb wakeup:: + for i in $(find /sys -name wakeup | grep usb);do echo enabled > $i;done; diff --git a/Documentation/usb/dwc3.txt b/Documentation/usb/dwc3.txt index 1d02c01d1c7c..f94a7ba16573 100644 --- a/Documentation/usb/dwc3.txt +++ b/Documentation/usb/dwc3.txt @@ -1,6 +1,11 @@ +=========== +DWC3 driver +=========== + + +TODO +~~~~ - TODO -~~~~~~ Please pick something while reading :) - Convert interrupt handler to per-ep-thread-irq @@ -9,6 +14,7 @@ Please pick something while reading :) until the command completes which is bad. Implementation idea: + - dwc core implements a demultiplexing irq chip for interrupts per endpoint. The interrupt numbers are allocated during probe and belong to the device. If MSI provides per-endpoint interrupt this dummy @@ -19,6 +25,7 @@ Please pick something while reading :) - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout() until the command completes. - the interrupt handler is split into the following pieces: + - primary handler of the device goes through every event and calls generic_handle_irq() for event it. On return from generic_handle_irq() in acknowledges the event @@ -40,6 +47,7 @@ Please pick something while reading :) for command completion. Latency: + There should be no increase in latency since the interrupt-thread has a high priority and will be run before an average task in user land (except the user changed priorities). diff --git a/Documentation/usb/ehci.txt b/Documentation/usb/ehci.txt index 160bd6c3ab7b..31f650e7c1b4 100644 --- a/Documentation/usb/ehci.txt +++ b/Documentation/usb/ehci.txt @@ -1,3 +1,7 @@ +=========== +EHCI driver +=========== + 27-Dec-2002 The EHCI driver is used to talk to high speed USB 2.0 devices using @@ -40,7 +44,8 @@ APIs exposed to USB device drivers. <dbrownell@users.sourceforge.net> -FUNCTIONALITY +Functionality +============= This driver is regularly tested on x86 hardware, and has also been used on PPC hardware so big/little endianness issues should be gone. @@ -48,6 +53,7 @@ It's believed to do all the right PCI magic so that I/O works even on systems with interesting DMA mapping issues. Transfer Types +-------------- At this writing the driver should comfortably handle all control, bulk, and interrupt transfers, including requests to USB 1.1 devices through @@ -63,6 +69,7 @@ since EHCI represents these with a different data structure. So for now, most USB audio and video devices can't be connected to high speed buses. Driver Behavior +--------------- Transfers of all types can be queued. This means that control transfers from a driver on one interface (or through usbfs) won't interfere with @@ -83,14 +90,15 @@ limits on the number of periodic transactions that can be scheduled, and prevent use of polling intervals of less than one frame. -USE BY +Use by +====== Assuming you have an EHCI controller (on a PCI card or motherboard) -and have compiled this driver as a module, load this like: +and have compiled this driver as a module, load this like:: # modprobe ehci-hcd -and remove it by: +and remove it by:: # rmmod ehci-hcd @@ -112,13 +120,16 @@ If you're using this driver on a 2.5 kernel, and you've enabled USB debugging support, you'll see three files in the "sysfs" directory for any EHCI controller: - "async" dumps the asynchronous schedule, used for control + "async" + dumps the asynchronous schedule, used for control and bulk transfers. Shows each active qh and the qtds pending, usually one qtd per urb. (Look at it with usb-storage doing disk I/O; watch the request queues!) - "periodic" dumps the periodic schedule, used for interrupt + "periodic" + dumps the periodic schedule, used for interrupt and isochronous transfers. Doesn't show qtds. - "registers" show controller register state, and + "registers" + show controller register state, and The contents of those files can help identify driver problems. @@ -136,7 +147,8 @@ transaction translators are in use; some drivers have been seen to behave badly when they see different faults than OHCI or UHCI report. -PERFORMANCE +Performance +=========== USB 2.0 throughput is gated by two main factors: how fast the host controller can process requests, and how fast devices can respond to @@ -156,6 +168,7 @@ hardware and device driver software allow it. Periodic transfer modes approach the quoted 480 MBit/sec transfer rate. Hardware Performance +-------------------- At this writing, individual USB 2.0 devices tend to max out at around 20 MByte/sec transfer rates. This is of course subject to change; @@ -183,6 +196,7 @@ you issue a control or bulk request you can often expect to learn that it completed in less than 250 usec (depending on transfer size). Software Performance +-------------------- To get even 20 MByte/sec transfer rates, Linux-USB device drivers will need to keep the EHCI queue full. That means issuing large requests, @@ -206,9 +220,11 @@ mapping (which might apply an IOMMU) and IRQ reduction, all of which will help make high speed transfers run as fast as they can. -TBD: Interrupt and ISO transfer performance issues. Those periodic -transfers are fully scheduled, so the main issue is likely to be how -to trigger "high bandwidth" modes. +TBD: + Interrupt and ISO transfer performance issues. Those periodic + transfers are fully scheduled, so the main issue is likely to be how + to trigger "high bandwidth" modes. -TBD: More than standard 80% periodic bandwidth allocation is possible -through sysfs uframe_periodic_max parameter. Describe that. +TBD: + More than standard 80% periodic bandwidth allocation is possible + through sysfs uframe_periodic_max parameter. Describe that. diff --git a/Documentation/usb/functionfs.txt b/Documentation/usb/functionfs.txt index eaaaea019fc7..7fdc6d840ac5 100644 --- a/Documentation/usb/functionfs.txt +++ b/Documentation/usb/functionfs.txt @@ -1,4 +1,6 @@ -*How FunctionFS works* +==================== +How FunctionFS works +==================== From kernel point of view it is just a composite function with some unique behaviour. It may be added to an USB configuration only after @@ -38,13 +40,13 @@ when mounting. One can imagine a gadget that has an Ethernet, MTP and HID interfaces where the last two are implemented via FunctionFS. On user space -level it would look like this: +level it would look like this:: -$ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid -$ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp -$ ( cd /dev/ffs-mtp && mtp-daemon ) & -$ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid -$ ( cd /dev/ffs-hid && hid-daemon ) & + $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid + $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp + $ ( cd /dev/ffs-mtp && mtp-daemon ) & + $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid + $ ( cd /dev/ffs-hid && hid-daemon ) & On kernel level the gadget checks ffs_data->dev_name to identify whether it's FunctionFS designed for MTP ("mtp") or HID ("hid"). @@ -64,4 +66,3 @@ have been written to their ep0's. Conversely, the gadget is unregistered after the first USB function closes its endpoints. - diff --git a/Documentation/usb/gadget-testing.txt b/Documentation/usb/gadget-testing.txt index 5908a21fddb6..7d7f2340af42 100644 --- a/Documentation/usb/gadget-testing.txt +++ b/Documentation/usb/gadget-testing.txt @@ -1,26 +1,32 @@ +============== +Gadget Testing +============== + This file summarizes information on basic testing of USB functions provided by gadgets. -1. ACM function -2. ECM function -3. ECM subset function -4. EEM function -5. FFS function -6. HID function -7. LOOPBACK function -8. MASS STORAGE function -9. MIDI function -10. NCM function -11. OBEX function -12. PHONET function -13. RNDIS function -14. SERIAL function -15. SOURCESINK function -16. UAC1 function (legacy implementation) -17. UAC2 function -18. UVC function -19. PRINTER function -20. UAC1 function (new API) +.. contents + + 1. ACM function + 2. ECM function + 3. ECM subset function + 4. EEM function + 5. FFS function + 6. HID function + 7. LOOPBACK function + 8. MASS STORAGE function + 9. MIDI function + 10. NCM function + 11. OBEX function + 12. PHONET function + 13. RNDIS function + 14. SERIAL function + 15. SOURCESINK function + 16. UAC1 function (legacy implementation) + 17. UAC2 function + 18. UVC function + 19. PRINTER function + 20. UAC1 function (new API) 1. ACM function @@ -44,13 +50,23 @@ There can be at most 4 ACM/generic serial/OBEX ports in the system. Testing the ACM function ------------------------ -On the host: cat > /dev/ttyACM<X> -On the device : cat /dev/ttyGS<Y> +On the host:: + + cat > /dev/ttyACM<X> + +On the device:: + + cat /dev/ttyGS<Y> then the other way round -On the device: cat > /dev/ttyGS<Y> -On the host: cat /dev/ttyACM<X> +On the device:: + + cat > /dev/ttyGS<Y> + +On the host:: + + cat /dev/ttyACM<X> 2. ECM function =============== @@ -63,13 +79,15 @@ Function-specific configfs interface The function name to use when creating the function directory is "ecm". The ECM function provides these attributes in its function directory: - ifname - network device interface name associated with this + =============== ================================================== + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + qmult queue length multiplier for high and super speed + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link + =============== ================================================== and after creating the functions/ecm.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. @@ -82,8 +100,13 @@ Testing the ECM function Configure IP addresses of the device and the host. Then: -On the device: ping <host's IP> -On the host: ping <device's IP> +On the device:: + + ping <host's IP> + +On the host:: + + ping <device's IP> 3. ECM subset function ====================== @@ -96,13 +119,15 @@ Function-specific configfs interface The function name to use when creating the function directory is "geth". The ECM subset function provides these attributes in its function directory: - ifname - network device interface name associated with this + =============== ================================================== + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + qmult queue length multiplier for high and super speed + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link + =============== ================================================== and after creating the functions/ecm.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. @@ -115,8 +140,13 @@ Testing the ECM subset function Configure IP addresses of the device and the host. Then: -On the device: ping <host's IP> -On the host: ping <device's IP> +On the device:: + + ping <host's IP> + +On the host:: + + ping <device's IP> 4. EEM function =============== @@ -129,13 +159,15 @@ Function-specific configfs interface The function name to use when creating the function directory is "eem". The EEM function provides these attributes in its function directory: - ifname - network device interface name associated with this + =============== ================================================== + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + qmult queue length multiplier for high and super speed + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link + =============== ================================================== and after creating the functions/eem.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. @@ -148,8 +180,13 @@ Testing the EEM function Configure IP addresses of the device and the host. Then: -On the device: ping <host's IP> -On the host: ping <device's IP> +On the device:: + + ping <host's IP> + +On the host:: + + ping <device's IP> 5. FFS function =============== @@ -172,6 +209,7 @@ Testing the FFS function ------------------------ On the device: start the function's userspace daemon, enable the gadget + On the host: use the USB function provided by the device 6. HID function @@ -185,39 +223,43 @@ Function-specific configfs interface The function name to use when creating the function directory is "hid". The HID function provides these attributes in its function directory: - protocol - HID protocol to use - report_desc - data to be used in HID reports, except data + =============== =========================================== + protocol HID protocol to use + report_desc data to be used in HID reports, except data passed with /dev/hidg<X> - report_length - HID report length - subclass - HID subclass to use + report_length HID report length + subclass HID subclass to use + =============== =========================================== For a keyboard the protocol and the subclass are 1, the report_length is 8, -while the report_desc is: +while the report_desc is:: -$ hd my_report_desc -00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| -00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| -00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| -00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| -0000003f + $ hd my_report_desc + 00000000 05 01 09 06 a1 01 05 07 19 e0 29 e7 15 00 25 01 |..........)...%.| + 00000010 75 01 95 08 81 02 95 01 75 08 81 03 95 05 75 01 |u.......u.....u.| + 00000020 05 08 19 01 29 05 91 02 95 01 75 03 91 03 95 06 |....).....u.....| + 00000030 75 08 15 00 25 65 05 07 19 00 29 65 81 00 c0 |u...%e....)e...| + 0000003f -Such a sequence of bytes can be stored to the attribute with echo: +Such a sequence of bytes can be stored to the attribute with echo:: -$ echo -ne \\x05\\x01\\x09\\x06\\xa1..... + $ echo -ne \\x05\\x01\\x09\\x06\\xa1..... Testing the HID function ------------------------ Device: + - create the gadget - connect the gadget to a host, preferably not the one used -to control the gadget + to control the gadget - run a program which writes to /dev/hidg<N>, e.g. -a userspace program found in Documentation/usb/gadget_hid.txt: + a userspace program found in Documentation/usb/gadget_hid.txt:: -$ ./hid_gadget_test /dev/hidg0 keyboard + $ ./hid_gadget_test /dev/hidg0 keyboard Host: + - observe the keystrokes from the gadget 7. LOOPBACK function @@ -231,13 +273,16 @@ Function-specific configfs interface The function name to use when creating the function directory is "Loopback". The LOOPBACK function provides these attributes in its function directory: - qlen - depth of loopback queue - bulk_buflen - buffer length + =============== ======================= + qlen depth of loopback queue + bulk_buflen buffer length + =============== ======================= Testing the LOOPBACK function ----------------------------- device: run the gadget + host: test-usb (tools/usb/testusb.c) 8. MASS STORAGE function @@ -252,18 +297,20 @@ The function name to use when creating the function directory is "mass_storage". The MASS STORAGE function provides these attributes in its directory: files: - stall - Set to permit function to halt bulk endpoints. + =============== ============================================== + stall Set to permit function to halt bulk endpoints. Disabled on some USB devices known not to work correctly. You should set it to true. - num_buffers - Number of pipeline buffers. Valid numbers + num_buffers Number of pipeline buffers. Valid numbers are 2..4. Available only if CONFIG_USB_GADGET_DEBUG_FILES is set. + =============== ============================================== and a default lun.0 directory corresponding to SCSI LUN #0. -A new lun can be added with mkdir: +A new lun can be added with mkdir:: -$ mkdir functions/mass_storage.0/partition.5 + $ mkdir functions/mass_storage.0/partition.5 Lun numbering does not have to be continuous, except for lun #0 which is created by default. A maximum of 8 luns can be specified and they all must be @@ -273,18 +320,20 @@ although it is not mandatory. In each lun directory there are the following attribute files: - file - The path to the backing file for the LUN. + =============== ============================================== + file The path to the backing file for the LUN. Required if LUN is not marked as removable. - ro - Flag specifying access to the LUN shall be + ro Flag specifying access to the LUN shall be read-only. This is implied if CD-ROM emulation is enabled as well as when it was impossible to open "filename" in R/W mode. - removable - Flag specifying that LUN shall be indicated as + removable Flag specifying that LUN shall be indicated as being removable. - cdrom - Flag specifying that LUN shall be reported as + cdrom Flag specifying that LUN shall be reported as being a CD-ROM. - nofua - Flag specifying that FUA flag + nofua Flag specifying that FUA flag in SCSI WRITE(10,12) + =============== ============================================== Testing the MASS STORAGE function --------------------------------- @@ -304,12 +353,14 @@ Function-specific configfs interface The function name to use when creating the function directory is "midi". The MIDI function provides these attributes in its function directory: - buflen - MIDI buffer length - id - ID string for the USB MIDI adapter - in_ports - number of MIDI input ports - index - index value for the USB MIDI adapter - out_ports - number of MIDI output ports - qlen - USB read request queue length + =============== ==================================== + buflen MIDI buffer length + id ID string for the USB MIDI adapter + in_ports number of MIDI input ports + index index value for the USB MIDI adapter + out_ports number of MIDI output ports + qlen USB read request queue length + =============== ==================================== Testing the MIDI function ------------------------- @@ -317,60 +368,63 @@ Testing the MIDI function There are two cases: playing a mid from the gadget to the host and playing a mid from the host to the gadget. -1) Playing a mid from the gadget to the host -host) +1) Playing a mid from the gadget to the host: + +host:: -$ arecordmidi -l - Port Client name Port name - 14:0 Midi Through Midi Through Port-0 - 24:0 MIDI Gadget MIDI Gadget MIDI 1 -$ arecordmidi -p 24:0 from_gadget.mid + $ arecordmidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 + $ arecordmidi -p 24:0 from_gadget.mid -gadget) +gadget:: -$ aplaymidi -l - Port Client name Port name - 20:0 f_midi f_midi + $ aplaymidi -l + Port Client name Port name + 20:0 f_midi f_midi -$ aplaymidi -p 20:0 to_host.mid + $ aplaymidi -p 20:0 to_host.mid 2) Playing a mid from the host to the gadget -gadget) -$ arecordmidi -l - Port Client name Port name - 20:0 f_midi f_midi +gadget:: + + $ arecordmidi -l + Port Client name Port name + 20:0 f_midi f_midi -$ arecordmidi -p 20:0 from_host.mid + $ arecordmidi -p 20:0 from_host.mid -host) +host:: -$ aplaymidi -l - Port Client name Port name - 14:0 Midi Through Midi Through Port-0 - 24:0 MIDI Gadget MIDI Gadget MIDI 1 + $ aplaymidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 -$ aplaymidi -p24:0 to_gadget.mid + $ aplaymidi -p24:0 to_gadget.mid The from_gadget.mid should sound identical to the to_host.mid. + The from_host.id should sound identical to the to_gadget.mid. -MIDI files can be played to speakers/headphones with e.g. timidity installed +MIDI files can be played to speakers/headphones with e.g. timidity installed:: -$ aplaymidi -l - Port Client name Port name - 14:0 Midi Through Midi Through Port-0 - 24:0 MIDI Gadget MIDI Gadget MIDI 1 -128:0 TiMidity TiMidity port 0 -128:1 TiMidity TiMidity port 1 -128:2 TiMidity TiMidity port 2 -128:3 TiMidity TiMidity port 3 + $ aplaymidi -l + Port Client name Port name + 14:0 Midi Through Midi Through Port-0 + 24:0 MIDI Gadget MIDI Gadget MIDI 1 + 128:0 TiMidity TiMidity port 0 + 128:1 TiMidity TiMidity port 1 + 128:2 TiMidity TiMidity port 2 + 128:3 TiMidity TiMidity port 3 -$ aplaymidi -p 128:0 file.mid + $ aplaymidi -p 128:0 file.mid -MIDI ports can be logically connected using the aconnect utility, e.g.: +MIDI ports can be logically connected using the aconnect utility, e.g.:: -$ aconnect 24:0 128:0 # try it on the host + $ aconnect 24:0 128:0 # try it on the host After the gadget's MIDI port is connected to timidity's MIDI port, whatever is played at the gadget side with aplaymidi -l is audible @@ -387,13 +441,15 @@ Function-specific configfs interface The function name to use when creating the function directory is "ncm". The NCM function provides these attributes in its function directory: - ifname - network device interface name associated with this + =============== ================================================== + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + qmult queue length multiplier for high and super speed + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link + =============== ================================================== and after creating the functions/ncm.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. @@ -406,8 +462,13 @@ Testing the NCM function Configure IP addresses of the device and the host. Then: -On the device: ping <host's IP> -On the host: ping <device's IP> +On the device:: + + ping <host's IP> + +On the host:: + + ping <device's IP> 11. OBEX function ================= @@ -429,13 +490,18 @@ There can be at most 4 ACM/generic serial/OBEX ports in the system. Testing the OBEX function ------------------------- -On device: seriald -f /dev/ttyGS<Y> -s 1024 -On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ - -t<out endpoint addr> -r<in endpoint addr> +On device:: + + seriald -f /dev/ttyGS<Y> -s 1024 + +On host:: + + serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ + -t<out endpoint addr> -r<in endpoint addr> where seriald and serialc are Felipe's utilities found here: -https://github.com/felipebalbi/usb-tools.git master + https://github.com/felipebalbi/usb-tools.git master 12. PHONET function =================== @@ -448,8 +514,10 @@ Function-specific configfs interface The function name to use when creating the function directory is "phonet". The PHONET function provides just one attribute in its function directory: - ifname - network device interface name associated with this + =============== ================================================== + ifname network device interface name associated with this function instance + =============== ================================================== Testing the PHONET function --------------------------- @@ -464,41 +532,41 @@ These tools are required: git://git.gitorious.org/meego-cellular/phonet-utils.git -On the host: +On the host:: -$ ./phonet -a 0x10 -i usbpn0 -$ ./pnroute add 0x6c usbpn0 -$./pnroute add 0x10 usbpn0 -$ ifconfig usbpn0 up + $ ./phonet -a 0x10 -i usbpn0 + $ ./pnroute add 0x6c usbpn0 + $./pnroute add 0x10 usbpn0 + $ ifconfig usbpn0 up -On the device: +On the device:: -$ ./phonet -a 0x6c -i upnlink0 -$ ./pnroute add 0x10 upnlink0 -$ ifconfig upnlink0 up + $ ./phonet -a 0x6c -i upnlink0 + $ ./pnroute add 0x10 upnlink0 + $ ifconfig upnlink0 up -Then a test program can be used: +Then a test program can be used:: -http://www.spinics.net/lists/linux-usb/msg85690.html + http://www.spinics.net/lists/linux-usb/msg85690.html -On the device: +On the device:: -$ ./pnxmit -a 0x6c -r + $ ./pnxmit -a 0x6c -r -On the host: +On the host:: -$ ./pnxmit -a 0x10 -s 0x6c + $ ./pnxmit -a 0x10 -s 0x6c As a result some data should be sent from host to device. Then the other way round: -On the host: +On the host:: -$ ./pnxmit -a 0x10 -r + $ ./pnxmit -a 0x10 -r -On the device: +On the device:: -$ ./pnxmit -a 0x6c -s 0x10 + $ ./pnxmit -a 0x6c -s 0x10 13. RNDIS function ================== @@ -511,13 +579,15 @@ Function-specific configfs interface The function name to use when creating the function directory is "rndis". The RNDIS function provides these attributes in its function directory: - ifname - network device interface name associated with this + =============== ================================================== + ifname network device interface name associated with this function instance - qmult - queue length multiplier for high and super speed - host_addr - MAC address of host's end of this + qmult queue length multiplier for high and super speed + host_addr MAC address of host's end of this Ethernet over USB link - dev_addr - MAC address of device's end of this + dev_addr MAC address of device's end of this Ethernet over USB link + =============== ================================================== and after creating the functions/rndis.<instance name> they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. @@ -530,8 +600,13 @@ Testing the RNDIS function Configure IP addresses of the device and the host. Then: -On the device: ping <host's IP> -On the host: ping <device's IP> +On the device:: + + ping <host's IP> + +On the host:: + + ping <device's IP> 14. SERIAL function =================== @@ -553,15 +628,28 @@ There can be at most 4 ACM/generic serial/OBEX ports in the system. Testing the SERIAL function --------------------------- -On host: insmod usbserial - echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id -On host: cat > /dev/ttyUSB<X> -On target: cat /dev/ttyGS<Y> +On host:: + + insmod usbserial + echo VID PID >/sys/bus/usb-serial/drivers/generic/new_id + +On host:: + + cat > /dev/ttyUSB<X> + +On target:: + + cat /dev/ttyGS<Y> then the other way round -On target: cat > /dev/ttyGS<Y> -On host: cat /dev/ttyUSB<X> +On target:: + + cat > /dev/ttyGS<Y> + +On host:: + + cat /dev/ttyUSB<X> 15. SOURCESINK function ======================= @@ -574,24 +662,27 @@ Function-specific configfs interface The function name to use when creating the function directory is "SourceSink". The SOURCESINK function provides these attributes in its function directory: - pattern - 0 (all zeros), 1 (mod63), 2 (none) - isoc_interval - 1..16 - isoc_maxpacket - 0 - 1023 (fs), 0 - 1024 (hs/ss) - isoc_mult - 0..2 (hs/ss only) - isoc_maxburst - 0..15 (ss only) - bulk_buflen - buffer length - bulk_qlen - depth of queue for bulk - iso_qlen - depth of queue for iso + =============== ================================== + pattern 0 (all zeros), 1 (mod63), 2 (none) + isoc_interval 1..16 + isoc_maxpacket 0 - 1023 (fs), 0 - 1024 (hs/ss) + isoc_mult 0..2 (hs/ss only) + isoc_maxburst 0..15 (ss only) + bulk_buflen buffer length + bulk_qlen depth of queue for bulk + iso_qlen depth of queue for iso + =============== ================================== Testing the SOURCESINK function ------------------------------- device: run the gadget + host: test-usb (tools/usb/testusb.c) 16. UAC1 function (legacy implementation) -================= +========================================= The function is provided by usb_f_uac1_legacy.ko module. @@ -602,12 +693,14 @@ The function name to use when creating the function directory is "uac1_legacy". The uac1 function provides these attributes in its function directory: - audio_buf_size - audio buffer size - fn_cap - capture pcm device file name - fn_cntl - control device file name - fn_play - playback pcm device file name - req_buf_size - ISO OUT endpoint request buffer size - req_count - ISO OUT endpoint request count + =============== ==================================== + audio_buf_size audio buffer size + fn_cap capture pcm device file name + fn_cntl control device file name + fn_play playback pcm device file name + req_buf_size ISO OUT endpoint request buffer size + req_count ISO OUT endpoint request count + =============== ==================================== The attributes have sane default values. @@ -615,7 +708,10 @@ Testing the UAC1 function ------------------------- device: run the gadget -host: aplay -l # should list our USB Audio Gadget + +host:: + + aplay -l # should list our USB Audio Gadget 17. UAC2 function ================= @@ -628,14 +724,16 @@ Function-specific configfs interface The function name to use when creating the function directory is "uac2". The uac2 function provides these attributes in its function directory: - c_chmask - capture channel mask - c_srate - capture sampling rate - c_ssize - capture sample size (bytes) - p_chmask - playback channel mask - p_srate - playback sampling rate - p_ssize - playback sample size (bytes) - req_number - the number of pre-allocated request for both capture - and playback + =============== ==================================================== + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + req_number the number of pre-allocated request for both capture + and playback + =============== ==================================================== The attributes have sane default values. @@ -648,14 +746,14 @@ host: aplay -l # should list our USB Audio Gadget This function does not require real hardware support, it just sends a stream of audio data to/from the host. In order to actually hear something at the device side, a command similar -to this must be used at the device side: +to this must be used at the device side:: -$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & + $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & -e.g.: +e.g.:: -$ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ -aplay -D default:CARD=OdroidU3 + $ arecord -f dat -t wav -D hw:CARD=UAC2Gadget,DEV=0 | \ + aplay -D default:CARD=OdroidU3 18. UVC function ================ @@ -668,66 +766,73 @@ Function-specific configfs interface The function name to use when creating the function directory is "uvc". The uvc function provides these attributes in its function directory: - streaming_interval - interval for polling endpoint for data transfers - streaming_maxburst - bMaxBurst for super speed companion descriptor - streaming_maxpacket - maximum packet size this endpoint is capable of - sending or receiving when this configuration is - selected + =================== ================================================ + streaming_interval interval for polling endpoint for data transfers + streaming_maxburst bMaxBurst for super speed companion descriptor + streaming_maxpacket maximum packet size this endpoint is capable of + sending or receiving when this configuration is + selected + =================== ================================================ There are also "control" and "streaming" subdirectories, each of which contain a number of their subdirectories. There are some sane defaults provided, but the user must provide the following: - control header - create in control/header, link from control/class/fs - and/or control/class/ss - streaming header - create in streaming/header, link from - streaming/class/fs and/or streaming/class/hs and/or - streaming/class/ss - format description - create in streaming/mjpeg and/or - streaming/uncompressed - frame description - create in streaming/mjpeg/<format> and/or in - streaming/uncompressed/<format> + ================== ==================================================== + control header create in control/header, link from control/class/fs + and/or control/class/ss + streaming header create in streaming/header, link from + streaming/class/fs and/or streaming/class/hs and/or + streaming/class/ss + format description create in streaming/mjpeg and/or + streaming/uncompressed + frame description create in streaming/mjpeg/<format> and/or in + streaming/uncompressed/<format> + ================== ==================================================== Each frame description contains frame interval specification, and each such specification consists of a number of lines with an inverval value -in each line. The rules stated above are best illustrated with an example: - -# mkdir functions/uvc.usb0/control/header/h -# cd functions/uvc.usb0/control/ -# ln -s header/h class/fs -# ln -s header/h class/ss -# mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p -# cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval -666666 -1000000 -5000000 -EOF -# cd $GADGET_CONFIGFS_ROOT -# mkdir functions/uvc.usb0/streaming/header/h -# cd functions/uvc.usb0/streaming/header/h -# ln -s ../../uncompressed/u -# cd ../../class/fs -# ln -s ../../header/h -# cd ../../class/hs -# ln -s ../../header/h -# cd ../../class/ss -# ln -s ../../header/h +in each line. The rules stated above are best illustrated with an example:: + + # mkdir functions/uvc.usb0/control/header/h + # cd functions/uvc.usb0/control/ + # ln -s header/h class/fs + # ln -s header/h class/ss + # mkdir -p functions/uvc.usb0/streaming/uncompressed/u/360p + # cat <<EOF > functions/uvc.usb0/streaming/uncompressed/u/360p/dwFrameInterval + 666666 + 1000000 + 5000000 + EOF + # cd $GADGET_CONFIGFS_ROOT + # mkdir functions/uvc.usb0/streaming/header/h + # cd functions/uvc.usb0/streaming/header/h + # ln -s ../../uncompressed/u + # cd ../../class/fs + # ln -s ../../header/h + # cd ../../class/hs + # ln -s ../../header/h + # cd ../../class/ss + # ln -s ../../header/h Testing the UVC function ------------------------ -device: run the gadget, modprobe vivid +device: run the gadget, modprobe vivid:: -# uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> + # uvc-gadget -u /dev/video<uvc video node #> -v /dev/video<vivid video node #> where uvc-gadget is this program: -http://git.ideasonboard.org/uvc-gadget.git + http://git.ideasonboard.org/uvc-gadget.git with these patches: -http://www.spinics.net/lists/linux-usb/msg99220.html -host: luvcview -f yuv + http://www.spinics.net/lists/linux-usb/msg99220.html + +host:: + + luvcview -f yuv 19. PRINTER function ==================== @@ -740,16 +845,19 @@ Function-specific configfs interface The function name to use when creating the function directory is "printer". The printer function provides these attributes in its function directory: - pnp_string - Data to be passed to the host in pnp string - q_len - Number of requests per endpoint + ========== =========================================== + pnp_string Data to be passed to the host in pnp string + q_len Number of requests per endpoint + ========== =========================================== Testing the PRINTER function ---------------------------- The most basic testing: -device: run the gadget -# ls -l /devices/virtual/usb_printer_gadget/ +device: run the gadget:: + + # ls -l /devices/virtual/usb_printer_gadget/ should show g_printer<number>. @@ -761,23 +869,28 @@ If udev is active, then e.g. /dev/usb/lp0 should appear. host->device transmission: -device: -# cat /dev/g_printer<number> -host: -# cat > /dev/usb/lp0 +device:: -device->host transmission: + # cat /dev/g_printer<number> -# cat > /dev/g_printer<number> -host: -# cat /dev/usb/lp0 +host:: + + # cat > /dev/usb/lp0 + +device->host transmission:: + + # cat > /dev/g_printer<number> + +host:: + + # cat /dev/usb/lp0 More advanced testing can be done with the prn_example described in Documentation/usb/gadget_printer.txt. 20. UAC1 function (virtual ALSA card, using u_audio API) -================= +======================================================== The function is provided by usb_f_uac1.ko module. It will create a virtual ALSA card and the audio streams are simply @@ -789,14 +902,16 @@ Function-specific configfs interface The function name to use when creating the function directory is "uac1". The uac1 function provides these attributes in its function directory: - c_chmask - capture channel mask - c_srate - capture sampling rate - c_ssize - capture sample size (bytes) - p_chmask - playback channel mask - p_srate - playback sampling rate - p_ssize - playback sample size (bytes) - req_number - the number of pre-allocated request for both capture - and playback + ========== ==================================================== + c_chmask capture channel mask + c_srate capture sampling rate + c_ssize capture sample size (bytes) + p_chmask playback channel mask + p_srate playback sampling rate + p_ssize playback sample size (bytes) + req_number the number of pre-allocated request for both capture + and playback + ========== ==================================================== The attributes have sane default values. @@ -809,11 +924,11 @@ host: aplay -l # should list our USB Audio Gadget This function does not require real hardware support, it just sends a stream of audio data to/from the host. In order to actually hear something at the device side, a command similar -to this must be used at the device side: +to this must be used at the device side:: -$ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & + $ arecord -f dat -t wav -D hw:2,0 | aplay -D hw:0,0 & -e.g.: +e.g.:: -$ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ -aplay -D default:CARD=OdroidU3 + $ arecord -f dat -t wav -D hw:CARD=UAC1Gadget,DEV=0 | \ + aplay -D default:CARD=OdroidU3 diff --git a/Documentation/usb/gadget_configfs.txt b/Documentation/usb/gadget_configfs.txt index b8cb38a98c19..54fb08baae22 100644 --- a/Documentation/usb/gadget_configfs.txt +++ b/Documentation/usb/gadget_configfs.txt @@ -1,11 +1,9 @@ +============================================ +Linux USB gadget configured through configfs +============================================ - - - Linux USB gadget configured through configfs - - - 25th April 2013 +25th April 2013 @@ -26,7 +24,7 @@ Linux provides a number of functions for gadgets to use. Creating a gadget means deciding what configurations there will be and which functions each configuration will provide. -Configfs (please see Documentation/filesystems/configfs/*) lends itself nicely +Configfs (please see `Documentation/filesystems/configfs/*`) lends itself nicely for the purpose of telling the kernel about the above mentioned decision. This document is about how to do it. @@ -51,44 +49,46 @@ Usage made available through configfs can be seen here: http://www.spinics.net/lists/linux-usb/msg76388.html) -$ modprobe libcomposite -$ mount none $CONFIGFS_HOME -t configfs +:: + + $ modprobe libcomposite + $ mount none $CONFIGFS_HOME -t configfs where CONFIGFS_HOME is the mount point for configfs 1. Creating the gadgets ----------------------- -For each gadget to be created its corresponding directory must be created: +For each gadget to be created its corresponding directory must be created:: -$ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> + $ mkdir $CONFIGFS_HOME/usb_gadget/<gadget name> -e.g.: +e.g.:: -$ mkdir $CONFIGFS_HOME/usb_gadget/g1 + $ mkdir $CONFIGFS_HOME/usb_gadget/g1 -... -... -... + ... + ... + ... -$ cd $CONFIGFS_HOME/usb_gadget/g1 + $ cd $CONFIGFS_HOME/usb_gadget/g1 -Each gadget needs to have its vendor id <VID> and product id <PID> specified: +Each gadget needs to have its vendor id <VID> and product id <PID> specified:: -$ echo <VID> > idVendor -$ echo <PID> > idProduct + $ echo <VID> > idVendor + $ echo <PID> > idProduct A gadget also needs its serial number, manufacturer and product strings. In order to have a place to store them, a strings subdirectory must be created -for each language, e.g.: +for each language, e.g.:: -$ mkdir strings/0x409 + $ mkdir strings/0x409 -Then the strings can be specified: +Then the strings can be specified:: -$ echo <serial number> > strings/0x409/serialnumber -$ echo <manufacturer> > strings/0x409/manufacturer -$ echo <product> > strings/0x409/product + $ echo <serial number> > strings/0x409/serialnumber + $ echo <manufacturer> > strings/0x409/manufacturer + $ echo <product> > strings/0x409/product 2. Creating the configurations ------------------------------ @@ -99,43 +99,43 @@ directories must be created: $ mkdir configs/<name>.<number> where <name> can be any string which is legal in a filesystem and the -<number> is the configuration's number, e.g.: +<number> is the configuration's number, e.g.:: -$ mkdir configs/c.1 + $ mkdir configs/c.1 -... -... -... + ... + ... + ... Each configuration also needs its strings, so a subdirectory must be created -for each language, e.g.: +for each language, e.g.:: -$ mkdir configs/c.1/strings/0x409 + $ mkdir configs/c.1/strings/0x409 -Then the configuration string can be specified: +Then the configuration string can be specified:: -$ echo <configuration> > configs/c.1/strings/0x409/configuration + $ echo <configuration> > configs/c.1/strings/0x409/configuration -Some attributes can also be set for a configuration, e.g.: +Some attributes can also be set for a configuration, e.g.:: -$ echo 120 > configs/c.1/MaxPower + $ echo 120 > configs/c.1/MaxPower 3. Creating the functions ------------------------- The gadget will provide some functions, for each function its corresponding -directory must be created: +directory must be created:: -$ mkdir functions/<name>.<instance name> + $ mkdir functions/<name>.<instance name> where <name> corresponds to one of allowed function names and instance name -is an arbitrary string allowed in a filesystem, e.g.: +is an arbitrary string allowed in a filesystem, e.g.:: -$ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() + $ mkdir functions/ncm.usb0 # usb_f_ncm.ko gets loaded with request_module() -... -... -... + ... + ... + ... Each function provides its specific set of attributes, with either read-only or read-write access. Where applicable they need to be written to as @@ -149,17 +149,17 @@ At this moment a number of gadgets is created, each of which has a number of configurations specified and a number of functions available. What remains is specifying which function is available in which configuration (the same function can be used in multiple configurations). This is achieved with -creating symbolic links: +creating symbolic links:: -$ ln -s functions/<name>.<instance name> configs/<name>.<number> + $ ln -s functions/<name>.<instance name> configs/<name>.<number> -e.g.: +e.g.:: -$ ln -s functions/ncm.usb0 configs/c.1 + $ ln -s functions/ncm.usb0 configs/c.1 -... -... -... + ... + ... + ... 5. Enabling the gadget ---------------------- @@ -167,123 +167,127 @@ $ ln -s functions/ncm.usb0 configs/c.1 All the above steps serve the purpose of composing the gadget of configurations and functions. -An example directory structure might look like this: - -. -./strings -./strings/0x409 -./strings/0x409/serialnumber -./strings/0x409/product -./strings/0x409/manufacturer -./configs -./configs/c.1 -./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 -./configs/c.1/strings -./configs/c.1/strings/0x409 -./configs/c.1/strings/0x409/configuration -./configs/c.1/bmAttributes -./configs/c.1/MaxPower -./functions -./functions/ncm.usb0 -./functions/ncm.usb0/ifname -./functions/ncm.usb0/qmult -./functions/ncm.usb0/host_addr -./functions/ncm.usb0/dev_addr -./UDC -./bcdUSB -./bcdDevice -./idProduct -./idVendor -./bMaxPacketSize0 -./bDeviceProtocol -./bDeviceSubClass -./bDeviceClass +An example directory structure might look like this:: + + . + ./strings + ./strings/0x409 + ./strings/0x409/serialnumber + ./strings/0x409/product + ./strings/0x409/manufacturer + ./configs + ./configs/c.1 + ./configs/c.1/ncm.usb0 -> ../../../../usb_gadget/g1/functions/ncm.usb0 + ./configs/c.1/strings + ./configs/c.1/strings/0x409 + ./configs/c.1/strings/0x409/configuration + ./configs/c.1/bmAttributes + ./configs/c.1/MaxPower + ./functions + ./functions/ncm.usb0 + ./functions/ncm.usb0/ifname + ./functions/ncm.usb0/qmult + ./functions/ncm.usb0/host_addr + ./functions/ncm.usb0/dev_addr + ./UDC + ./bcdUSB + ./bcdDevice + ./idProduct + ./idVendor + ./bMaxPacketSize0 + ./bDeviceProtocol + ./bDeviceSubClass + ./bDeviceClass Such a gadget must be finally enabled so that the USB host can enumerate it. -In order to enable the gadget it must be bound to a UDC (USB Device Controller). -$ echo <udc name> > UDC +In order to enable the gadget it must be bound to a UDC (USB Device +Controller):: + + $ echo <udc name> > UDC where <udc name> is one of those found in /sys/class/udc/* -e.g.: +e.g.:: -$ echo s3c-hsotg > UDC + $ echo s3c-hsotg > UDC 6. Disabling the gadget ----------------------- -$ echo "" > UDC +:: + + $ echo "" > UDC 7. Cleaning up -------------- -Remove functions from configurations: +Remove functions from configurations:: -$ rm configs/<config name>.<number>/<function> + $ rm configs/<config name>.<number>/<function> where <config name>.<number> specify the configuration and <function> is -a symlink to a function being removed from the configuration, e.g.: +a symlink to a function being removed from the configuration, e.g.:: -$ rm configs/c.1/ncm.usb0 + $ rm configs/c.1/ncm.usb0 -... -... -... + ... + ... + ... -Remove strings directories in configurations +Remove strings directories in configurations: -$ rmdir configs/<config name>.<number>/strings/<lang> + $ rmdir configs/<config name>.<number>/strings/<lang> -e.g.: +e.g.:: -$ rmdir configs/c.1/strings/0x409 + $ rmdir configs/c.1/strings/0x409 -... -... -... + ... + ... + ... -and remove the configurations +and remove the configurations:: -$ rmdir configs/<config name>.<number> + $ rmdir configs/<config name>.<number> -e.g.: +e.g.:: -rmdir configs/c.1 + rmdir configs/c.1 -... -... -... + ... + ... + ... -Remove functions (function modules are not unloaded, though) +Remove functions (function modules are not unloaded, though): -$ rmdir functions/<name>.<instance name> + $ rmdir functions/<name>.<instance name> -e.g.: +e.g.:: -$ rmdir functions/ncm.usb0 + $ rmdir functions/ncm.usb0 -... -... -... + ... + ... + ... -Remove strings directories in the gadget +Remove strings directories in the gadget:: -$ rmdir strings/<lang> + $ rmdir strings/<lang> -e.g.: +e.g.:: -$ rmdir strings/0x409 + $ rmdir strings/0x409 -and finally remove the gadget: +and finally remove the gadget:: -$ cd .. -$ rmdir <gadget name> + $ cd .. + $ rmdir <gadget name> -e.g.: +e.g.:: -$ rmdir g1 + $ rmdir g1 @@ -305,16 +309,16 @@ configured elements. However, they are embedded in usage-specific larger structures. In the picture below there is a "cs" which contains a config_item and an "sa" which contains a configfs_attribute. -The filesystem view would be like this: +The filesystem view would be like this:: -./ -./cs (directory) - | - +--sa (file) - | - . - . - . + ./ + ./cs (directory) + | + +--sa (file) + | + . + . + . Whenever a user reads/writes the "sa" file, a function is called which accepts a struct config_item and a struct configfs_attribute. @@ -326,29 +330,31 @@ buffer), while the "store" is for modifying the file's contents (copy data from the buffer to the cs), but it is up to the implementer of the two functions to decide what they actually do. -typedef struct configured_structure cs; -typedef struct specific_attribute sa; - - sa - +----------------------------------+ - cs | (*show)(cs *, buffer); | -+-----------------+ | (*store)(cs *, buffer, length); | -| | | | -| +-------------+ | | +------------------+ | -| | struct |-|----|------>|struct | | -| | config_item | | | |configfs_attribute| | -| +-------------+ | | +------------------+ | -| | +----------------------------------+ -| data to be set | . -| | . -+-----------------+ . +:: + + typedef struct configured_structure cs; + typedef struct specific_attribute sa; + + sa + +----------------------------------+ + cs | (*show)(cs *, buffer); | + +-----------------+ | (*store)(cs *, buffer, length); | + | | | | + | +-------------+ | | +------------------+ | + | | struct |-|----|------>|struct | | + | | config_item | | | |configfs_attribute| | + | +-------------+ | | +------------------+ | + | | +----------------------------------+ + | data to be set | . + | | . + +-----------------+ . The file names are decided by the config item/group designer, while the directories in general can be named at will. A group can have a number of its default sub-groups created automatically. For more information on configfs please see -Documentation/filesystems/configfs/*. +`Documentation/filesystems/configfs/*`. The concepts described above translate to USB gadgets like this: diff --git a/Documentation/usb/gadget_hid.txt b/Documentation/usb/gadget_hid.txt index 7a0fb8e16e27..098d563040cc 100644 --- a/Documentation/usb/gadget_hid.txt +++ b/Documentation/usb/gadget_hid.txt @@ -1,28 +1,31 @@ - - Linux USB HID gadget driver +=========================== +Linux USB HID gadget driver +=========================== Introduction +============ - The HID Gadget driver provides emulation of USB Human Interface - Devices (HID). The basic HID handling is done in the kernel, - and HID reports can be sent/received through I/O on the - /dev/hidgX character devices. +The HID Gadget driver provides emulation of USB Human Interface +Devices (HID). The basic HID handling is done in the kernel, +and HID reports can be sent/received through I/O on the +/dev/hidgX character devices. - For more details about HID, see the developer page on - http://www.usb.org/developers/hidpage/ +For more details about HID, see the developer page on +http://www.usb.org/developers/hidpage/ Configuration +============= - g_hid is a platform driver, so to use it you need to add - struct platform_device(s) to your platform code defining the - HID function descriptors you want to use - E.G. something - like: +g_hid is a platform driver, so to use it you need to add +struct platform_device(s) to your platform code defining the +HID function descriptors you want to use - E.G. something +like:: -#include <linux/platform_device.h> -#include <linux/usb/g_hid.h> + #include <linux/platform_device.h> + #include <linux/usb/g_hid.h> -/* hid descriptor for a keyboard */ -static struct hidg_func_descriptor my_hid_data = { + /* hid descriptor for a keyboard */ + static struct hidg_func_descriptor my_hid_data = { .subclass = 0, /* No subclass */ .protocol = 1, /* Keyboard */ .report_length = 8, @@ -61,85 +64,87 @@ static struct hidg_func_descriptor my_hid_data = { 0x81, 0x00, /* INPUT (Data,Ary,Abs) */ 0xc0 /* END_COLLECTION */ } -}; + }; -static struct platform_device my_hid = { + static struct platform_device my_hid = { .name = "hidg", .id = 0, .num_resources = 0, .resource = 0, .dev.platform_data = &my_hid_data, -}; + }; - You can add as many HID functions as you want, only limited by - the amount of interrupt endpoints your gadget driver supports. +You can add as many HID functions as you want, only limited by +the amount of interrupt endpoints your gadget driver supports. Configuration with configfs +=========================== - Instead of adding fake platform devices and drivers in order to pass - some data to the kernel, if HID is a part of a gadget composed with - configfs the hidg_func_descriptor.report_desc is passed to the kernel - by writing the appropriate stream of bytes to a configfs attribute. +Instead of adding fake platform devices and drivers in order to pass +some data to the kernel, if HID is a part of a gadget composed with +configfs the hidg_func_descriptor.report_desc is passed to the kernel +by writing the appropriate stream of bytes to a configfs attribute. Send and receive HID reports +============================ - HID reports can be sent/received using read/write on the - /dev/hidgX character devices. See below for an example program - to do this. +HID reports can be sent/received using read/write on the +/dev/hidgX character devices. See below for an example program +to do this. - hid_gadget_test is a small interactive program to test the HID - gadget driver. To use, point it at a hidg device and set the - device type (keyboard / mouse / joystick) - E.G.: +hid_gadget_test is a small interactive program to test the HID +gadget driver. To use, point it at a hidg device and set the +device type (keyboard / mouse / joystick) - E.G.:: - # hid_gadget_test /dev/hidg0 keyboard + # hid_gadget_test /dev/hidg0 keyboard - You are now in the prompt of hid_gadget_test. You can type any - combination of options and values. Available options and - values are listed at program start. In keyboard mode you can - send up to six values. +You are now in the prompt of hid_gadget_test. You can type any +combination of options and values. Available options and +values are listed at program start. In keyboard mode you can +send up to six values. - For example type: g i s t r --left-shift +For example type: g i s t r --left-shift - Hit return and the corresponding report will be sent by the - HID gadget. +Hit return and the corresponding report will be sent by the +HID gadget. - Another interesting example is the caps lock test. Type - --caps-lock and hit return. A report is then sent by the - gadget and you should receive the host answer, corresponding - to the caps lock LED status. +Another interesting example is the caps lock test. Type +--caps-lock and hit return. A report is then sent by the +gadget and you should receive the host answer, corresponding +to the caps lock LED status:: - --caps-lock - recv report:2 + --caps-lock + recv report:2 - With this command: +With this command:: - # hid_gadget_test /dev/hidg1 mouse + # hid_gadget_test /dev/hidg1 mouse - You can test the mouse emulation. Values are two signed numbers. +You can test the mouse emulation. Values are two signed numbers. -Sample code +Sample code:: -/* hid_gadget_test */ + /* hid_gadget_test */ -#include <pthread.h> -#include <string.h> -#include <stdio.h> -#include <ctype.h> -#include <fcntl.h> -#include <errno.h> -#include <stdio.h> -#include <stdlib.h> -#include <unistd.h> + #include <pthread.h> + #include <string.h> + #include <stdio.h> + #include <ctype.h> + #include <fcntl.h> + #include <errno.h> + #include <stdio.h> + #include <stdlib.h> + #include <unistd.h> -#define BUF_LEN 512 + #define BUF_LEN 512 -struct options { + struct options { const char *opt; unsigned char val; -}; + }; -static struct options kmod[] = { + static struct options kmod[] = { {.opt = "--left-ctrl", .val = 0x01}, {.opt = "--right-ctrl", .val = 0x10}, {.opt = "--left-shift", .val = 0x02}, @@ -149,9 +154,9 @@ static struct options kmod[] = { {.opt = "--left-meta", .val = 0x08}, {.opt = "--right-meta", .val = 0x80}, {.opt = NULL} -}; + }; -static struct options kval[] = { + static struct options kval[] = { {.opt = "--return", .val = 0x28}, {.opt = "--esc", .val = 0x29}, {.opt = "--bckspc", .val = 0x2a}, @@ -183,10 +188,10 @@ static struct options kval[] = { {.opt = "--up", .val = 0x52}, {.opt = "--num-lock", .val = 0x53}, {.opt = NULL} -}; + }; -int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) -{ + int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) + { char *tok = strtok(buf, " "); int key = 0; int i = 0; @@ -229,17 +234,17 @@ int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold) fprintf(stderr, "unknown option: %s\n", tok); } return 8; -} + } -static struct options mmod[] = { + static struct options mmod[] = { {.opt = "--b1", .val = 0x01}, {.opt = "--b2", .val = 0x02}, {.opt = "--b3", .val = 0x04}, {.opt = NULL} -}; + }; -int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) -{ + int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) + { char *tok = strtok(buf, " "); int mvt = 0; int i = 0; @@ -274,9 +279,9 @@ int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold) fprintf(stderr, "unknown option: %s\n", tok); } return 3; -} + } -static struct options jmod[] = { + static struct options jmod[] = { {.opt = "--b1", .val = 0x10}, {.opt = "--b2", .val = 0x20}, {.opt = "--b3", .val = 0x40}, @@ -287,10 +292,10 @@ static struct options jmod[] = { {.opt = "--hat4", .val = 0x03}, {.opt = "--hatneutral", .val = 0x04}, {.opt = NULL} -}; + }; -int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) -{ + int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) + { char *tok = strtok(buf, " "); int mvt = 0; int i = 0; @@ -326,10 +331,10 @@ int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold) fprintf(stderr, "unknown option: %s\n", tok); } return 4; -} + } -void print_options(char c) -{ + void print_options(char c) + { int i = 0; if (c == 'k') { @@ -358,10 +363,10 @@ void print_options(char c) " three signed numbers\n" "--quit to close\n"); } -} + } -int main(int argc, const char *argv[]) -{ + int main(int argc, const char *argv[]) + { const char *filename = NULL; int fd = 0; char buf[BUF_LEN]; @@ -449,4 +454,4 @@ int main(int argc, const char *argv[]) close(fd); return 0; -} + } diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt index b3146dd7aa43..9806b55af301 100644 --- a/Documentation/usb/gadget_multi.txt +++ b/Documentation/usb/gadget_multi.txt @@ -1,6 +1,9 @@ - -*- org -*- +============================== +Multifunction Composite Gadget +============================== -* Overview +Overview +======== The Multifunction Composite Gadget (or g_multi) is a composite gadget that makes extensive use of the composite framework to provide @@ -17,13 +20,15 @@ have two configurations -- one with RNDIS and another with CDC ECM[3]. Please note that if you use non-standard configuration (that is enable CDC ECM) you may need to change vendor and/or product ID. -* Host drivers +Host drivers +============ To make use of the gadget one needs to make it work on host side -- without that there's no hope of achieving anything with the gadget. As one might expect, things one need to do very from system to system. -** Linux host drivers +Linux host drivers +------------------ Since the gadget uses standard composite framework and appears as such to Linux host it does not need any additional drivers on Linux host @@ -34,11 +39,13 @@ This is also true for two configuration set-up with RNDIS configuration being the first one. Linux host will use the second configuration with CDC ECM which should work better under Linux. -** Windows host drivers +Windows host drivers +-------------------- For the gadget to work under Windows two conditions have to be met: -*** Detecting as composite gadget +Detecting as composite gadget +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ First of all, Windows need to detect the gadget as an USB composite gadget which on its own have some conditions[4]. If they are met, @@ -53,7 +60,8 @@ The only thing to worry is that the gadget has to have a single configuration so a dual RNDIS and CDC ECM gadget won't work unless you create a proper INF -- and of course, if you do submit it! -*** Installing drivers for each function +Installing drivers for each function +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The other, trickier thing is making Windows install drivers for each individual function. @@ -63,7 +71,8 @@ implementing USB Mass Storage class and selects appropriate driver. Things are harder with RDNIS and CDC ACM. -**** RNDIS +RNDIS +..... To make Windows select RNDIS drivers for the first function in the gadget, one needs to use the [[file:linux.inf]] file provided with this @@ -75,11 +84,13 @@ RNDIS was not the first interface. You do not need to worry abut it unless you are trying to develop your own gadget in which case watch out for this bug. -**** CDC ACM +CDC ACM +....... Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. -**** Customising the gadget +Customising the gadget +...................... If you intend to hack the g_multi gadget be advised that rearranging functions will obviously change interface numbers for each of the @@ -97,14 +108,16 @@ things don't work as intended before realising Windows have cached some drivers information (changing USB port may sometimes help plus you might try using USBDeview[8] to remove the phantom device). -**** INF testing +INF testing +........... Provided INF files have been tested on Windows XP SP3, Windows Vista and Windows 7, all 32-bit versions. It should work on 64-bit versions as well. It most likely won't work on Windows prior to Windows XP SP2. -** Other systems +Other systems +------------- At this moment, drivers for any other systems have not been tested. Knowing how MacOS is based on BSD and BSD is an Open Source it is @@ -115,7 +128,8 @@ For more exotic systems I have even less to say... Any testing and drivers *are* *welcome*! -* Authors +Authors +======= This document has been written by Michal Nazarewicz ([[mailto:mina86@mina86.com]]). INF files have been hacked with @@ -124,7 +138,8 @@ Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS template[9], Microchip's CDC ACM INF file and David Brownell's ([[mailto:dbrownell@users.sourceforge.net]]) original INF files. -* Footnotes +Footnotes +========= [1] Remote Network Driver Interface Specification, [[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. diff --git a/Documentation/usb/gadget_printer.txt b/Documentation/usb/gadget_printer.txt index ad995bf0db41..5e5516c69075 100644 --- a/Documentation/usb/gadget_printer.txt +++ b/Documentation/usb/gadget_printer.txt @@ -1,12 +1,14 @@ +=============================== +Linux USB Printer Gadget Driver +=============================== - Linux USB Printer Gadget Driver - 06/04/2007 +06/04/2007 - Copyright (C) 2007 Craig W. Nadler <craig@nadler.us> +Copyright (C) 2007 Craig W. Nadler <craig@nadler.us> -GENERAL +General ======= This driver may be used if you are writing printer firmware using Linux as @@ -29,52 +31,60 @@ user space firmware can read or write this status byte using a device file -HOWTO USE THIS DRIVER +Howto Use This Driver ===================== To load the USB device controller driver and the printer gadget driver. The -following example uses the Netchip 2280 USB device controller driver: +following example uses the Netchip 2280 USB device controller driver:: -modprobe net2280 -modprobe g_printer + modprobe net2280 + modprobe g_printer The follow command line parameter can be used when loading the printer gadget (ex: modprobe g_printer idVendor=0x0525 idProduct=0xa4a8 ): -idVendor - This is the Vendor ID used in the device descriptor. The default is +idVendor + This is the Vendor ID used in the device descriptor. The default is the Netchip vendor id 0x0525. YOU MUST CHANGE TO YOUR OWN VENDOR ID BEFORE RELEASING A PRODUCT. If you plan to release a product and don't already have a Vendor ID please see www.usb.org for details on how to get one. -idProduct - This is the Product ID used in the device descriptor. The default +idProduct + This is the Product ID used in the device descriptor. The default is 0xa4a8, you should change this to an ID that's not used by any of your other USB products if you have any. It would be a good idea to start numbering your products starting with say 0x0001. -bcdDevice - This is the version number of your product. It would be a good idea +bcdDevice + This is the version number of your product. It would be a good idea to put your firmware version here. -iManufacturer - A string containing the name of the Vendor. +iManufacturer + A string containing the name of the Vendor. -iProduct - A string containing the Product Name. +iProduct + A string containing the Product Name. -iSerialNum - A string containing the Serial Number. This should be changed for +iSerialNum + A string containing the Serial Number. This should be changed for each unit of your product. -iPNPstring - The PNP ID string used for this printer. You will want to set +iPNPstring + The PNP ID string used for this printer. You will want to set either on the command line or hard code the PNP ID string used for your printer product. -qlen - The number of 8k buffers to use per endpoint. The default is 10, you +qlen + The number of 8k buffers to use per endpoint. The default is 10, you should tune this for your product. You may also want to tune the size of each buffer for your product. -USING THE EXAMPLE CODE +Using The Example Code ====================== This example code talks to stdout, instead of a print engine. @@ -82,22 +92,23 @@ This example code talks to stdout, instead of a print engine. To compile the test code below: 1) save it to a file called prn_example.c -2) compile the code with the follow command: +2) compile the code with the follow command:: + gcc prn_example.c -o prn_example -To read printer data from the host to stdout: +To read printer data from the host to stdout:: # prn_example -read_data -To write printer data from a file (data_file) to the host: +To write printer data from a file (data_file) to the host:: # cat data_file | prn_example -write_data -To get the current printer status for the gadget driver: +To get the current printer status for the gadget driver::: # prn_example -get_status @@ -107,60 +118,62 @@ To get the current printer status for the gadget driver: Printer OK -To set printer to Selected/On-line: +To set printer to Selected/On-line:: # prn_example -selected -To set printer to Not Selected/Off-line: +To set printer to Not Selected/Off-line:: # prn_example -not_selected -To set paper status to paper out: +To set paper status to paper out:: # prn_example -paper_out -To set paper status to paper loaded: +To set paper status to paper loaded:: # prn_example -paper_loaded -To set error status to printer OK: +To set error status to printer OK:: # prn_example -no_error -To set error status to ERROR: +To set error status to ERROR:: # prn_example -error -EXAMPLE CODE +Example Code ============ +:: + -#include <stdio.h> -#include <stdlib.h> -#include <fcntl.h> -#include <linux/poll.h> -#include <sys/ioctl.h> -#include <linux/usb/g_printer.h> + #include <stdio.h> + #include <stdlib.h> + #include <fcntl.h> + #include <linux/poll.h> + #include <sys/ioctl.h> + #include <linux/usb/g_printer.h> -#define PRINTER_FILE "/dev/g_printer" -#define BUF_SIZE 512 + #define PRINTER_FILE "/dev/g_printer" + #define BUF_SIZE 512 -/* - * 'usage()' - Show program usage. - */ + /* + * 'usage()' - Show program usage. + */ -static void -usage(const char *option) /* I - Option string or NULL */ -{ + static void + usage(const char *option) /* I - Option string or NULL */ + { if (option) { fprintf(stderr,"prn_example: Unknown option \"%s\"!\n", option); @@ -186,12 +199,12 @@ usage(const char *option) /* I - Option string or NULL */ fputs("\n\n", stderr); exit(1); -} + } -static int -read_printer_data() -{ + static int + read_printer_data() + { struct pollfd fd[1]; /* Open device file for printer gadget. */ @@ -236,12 +249,12 @@ read_printer_data() close(fd[0].fd); return 0; -} + } -static int -write_printer_data() -{ + static int + write_printer_data() + { struct pollfd fd[1]; /* Open device file for printer gadget. */ @@ -295,12 +308,12 @@ write_printer_data() close(fd[0].fd); return 0; -} + } -static int -read_NB_printer_data() -{ + static int + read_NB_printer_data() + { int fd; static char buf[BUF_SIZE]; int bytes_read; @@ -329,12 +342,12 @@ read_NB_printer_data() close(fd); return 0; -} + } -static int -get_printer_status() -{ + static int + get_printer_status() + { int retval; int fd; @@ -357,12 +370,12 @@ get_printer_status() close(fd); return(retval); -} + } -static int -set_printer_status(unsigned char buf, int clear_printer_status_bit) -{ + static int + set_printer_status(unsigned char buf, int clear_printer_status_bit) + { int retval; int fd; @@ -397,12 +410,12 @@ set_printer_status(unsigned char buf, int clear_printer_status_bit) close(fd); return 0; -} + } -static int -display_printer_status() -{ + static int + display_printer_status() + { char printer_status; printer_status = get_printer_status(); @@ -429,12 +442,12 @@ display_printer_status() } return(0); -} + } -int -main(int argc, char *argv[]) -{ + int + main(int argc, char *argv[]) + { int i; /* Looping var */ int retval = 0; @@ -507,4 +520,4 @@ main(int argc, char *argv[]) } exit(retval); -} + } diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index d1def3186782..dce8bc1fb1f2 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -1,7 +1,10 @@ +=============================== +Linux Gadget Serial Driver v2.0 +=============================== - Linux Gadget Serial Driver v2.0 - 11/20/2004 - (updated 8-May-2008 for v2.3) +11/20/2004 + +(updated 8-May-2008 for v2.3) License and Disclaimer @@ -56,7 +59,7 @@ hardware; for example, a PDA, an embedded Linux system, or a PC with a USB development card. The gadget serial driver talks over USB to either a CDC ACM driver -or a generic USB serial driver running on a host PC. +or a generic USB serial driver running on a host PC:: Host -------------------------------------- @@ -112,11 +115,11 @@ configuring the kernel. Then rebuild and install the kernel or modules. Then you must load the gadget serial driver. To load it as an -ACM device (recommended for interoperability), do this: +ACM device (recommended for interoperability), do this:: modprobe g_serial -To load it as a vendor specific bulk in/out device, do this: +To load it as a vendor specific bulk in/out device, do this:: modprobe g_serial use_acm=0 @@ -127,7 +130,7 @@ desired. Your system should use mdev (from busybox) or udev to make the device nodes. After this gadget driver has been set up you should -then see a /dev/ttyGS0 node: +then see a /dev/ttyGS0 node:: # ls -l /dev/ttyGS0 | cat crw-rw---- 1 root root 253, 0 May 8 14:10 /dev/ttyGS0 @@ -187,24 +190,24 @@ support". 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 +the gadget serial device. For example, the command:: cat /sys/kernel/debug/usb/devices -should show something like this: - -T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0 -D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 -P: Vendor=0525 ProdID=a4a7 Rev= 2.01 -S: Manufacturer=Linux 2.6.8.1 with net2280 -S: Product=Gadget Serial -S: SerialNumber=0 -C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA -I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm -E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms -I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm -E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms -E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms +should show something like this::: + + T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 5 Spd=480 MxCh= 0 + D: Ver= 2.00 Cls=02(comm.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 + P: Vendor=0525 ProdID=a4a7 Rev= 2.01 + S: Manufacturer=Linux 2.6.8.1 with net2280 + S: Product=Gadget Serial + S: SerialNumber=0 + C:* #Ifs= 2 Cfg#= 2 Atr=c0 MxPwr= 2mA + I: If#= 0 Alt= 0 #EPs= 1 Cls=02(comm.) Sub=02 Prot=01 Driver=acm + E: Ad=83(I) Atr=03(Int.) MxPS= 8 Ivl=32ms + I: If#= 1 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=acm + E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms + E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms If the host side Linux system is configured properly, the ACM driver should be loaded automatically. The command "lsmod" should show the @@ -219,29 +222,29 @@ Serial Converter support", and for the "USB Generic Serial Driver". 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 +the gadget serial device. For example, the command:: cat /sys/kernel/debug/usb/devices -should show something like this: +should show something like this::: -T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0 -D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 -P: Vendor=0525 ProdID=a4a6 Rev= 2.01 -S: Manufacturer=Linux 2.6.8.1 with net2280 -S: Product=Gadget Serial -S: SerialNumber=0 -C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA -I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial -E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms -E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms + T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 6 Spd=480 MxCh= 0 + D: Ver= 2.00 Cls=ff(vend.) Sub=00 Prot=00 MxPS=64 #Cfgs= 1 + P: Vendor=0525 ProdID=a4a6 Rev= 2.01 + S: Manufacturer=Linux 2.6.8.1 with net2280 + S: Product=Gadget Serial + S: SerialNumber=0 + C:* #Ifs= 1 Cfg#= 1 Atr=c0 MxPwr= 2mA + I: If#= 0 Alt= 0 #EPs= 2 Cls=0a(data ) Sub=00 Prot=00 Driver=serial + E: Ad=81(I) Atr=02(Bulk) MxPS= 512 Ivl=0ms + E: Ad=02(O) Atr=02(Bulk) MxPS= 512 Ivl=0ms You must load the usbserial driver and explicitly set its parameters -to configure it to recognize the gadget serial device, like this: +to configure it to recognize the gadget serial device, like this:: echo 0x0525 0xA4A6 >/sys/bus/usb-serial/drivers/generic/new_id -The legacy way is to use module parameters: +The legacy way is to use module parameters:: modprobe usbserial vendor=0x0525 product=0xA4A6 diff --git a/Documentation/usb/iuu_phoenix.txt b/Documentation/usb/iuu_phoenix.txt index e5f048067da4..b76268728450 100644 --- a/Documentation/usb/iuu_phoenix.txt +++ b/Documentation/usb/iuu_phoenix.txt @@ -1,5 +1,6 @@ +============================= Infinity Usb Unlimited Readme ------------------------------ +============================= Hi all, @@ -19,7 +20,8 @@ have his own device file(/dev/ttyUSB0,/dev/ttyUSB1,...) -How to tune the reader speed ? +How to tune the reader speed? +============================= A few parameters can be used at load time To use parameters, just unload the module if it is @@ -27,26 +29,33 @@ How to tune the reader speed ? In case of prebuilt module, use the command insmod iuu_phoenix param=value. - Example: + Example:: - modprobe iuu_phoenix clockmode=3 + modprobe iuu_phoenix clockmode=3 The parameters are: - parm: clockmode:1=3Mhz579,2=3Mhz680,3=6Mhz (int) - parm: boost:overclock boost percent 100 to 500 (int) - parm: cdmode:Card detect mode 0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int) - parm: xmas:xmas color enabled or not (bool) - parm: debug:Debug enabled or not (bool) +clockmode: + 1=3Mhz579,2=3Mhz680,3=6Mhz (int) +boost: + overclock boost percent 100 to 500 (int) +cdmode: + Card detect mode + 0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int) +xmas: + xmas color enabled or not (bool) +debug: + Debug enabled or not (bool) - clockmode will provide 3 different base settings commonly adopted by different software: - 1. 3Mhz579 + + 1. 3Mhz579 2. 3Mhz680 3. 6Mhz - boost provide a way to overclock the reader ( my favorite :-) ) - For example to have best performance than a simple clockmode=3, try this: + For example to have best performance than a simple clockmode=3, try this:: modprobe boost=195 @@ -66,7 +75,8 @@ How to tune the reader speed ? - debug will produce a lot of debugging messages... - Last notes: +Last notes +========== Don't worry about the serial settings, the serial emulation is an abstraction, so use any speed or parity setting will diff --git a/Documentation/usb/mass-storage.txt b/Documentation/usb/mass-storage.txt index e89803a5a960..d181b47c3cb6 100644 --- a/Documentation/usb/mass-storage.txt +++ b/Documentation/usb/mass-storage.txt @@ -1,4 +1,9 @@ -* Overview +========================= +Mass Storage Gadget (MSG) +========================= + +Overview +======== Mass Storage Gadget (or MSG) acts as a USB Mass Storage device, appearing to the host as a disk or a CD-ROM drive. It supports @@ -24,7 +29,8 @@ (which is no longer included in Linux). It will talk only briefly about how to use MSF within composite gadgets. -* Module parameters +Module parameters +================= The mass storage gadget accepts the following mass storage specific module parameters: @@ -146,7 +152,8 @@ - iProduct -- USB Product string (string) - iSerialNumber -- SerialNumber string (sting) -* sysfs entries +sysfs entries +============= For each logical unit, the gadget creates a directory in the sysfs hierarchy. Inside of it the following three files are created: @@ -177,7 +184,8 @@ Other then those, as usual, the values of module parameters can be read from /sys/module/g_mass_storage/parameters/* files. -* Other gadgets using mass storage function +Other gadgets using mass storage function +========================================= The Mass Storage Gadget uses the Mass Storage Function to handle mass storage protocol. As a composite function, MSF may be used by @@ -193,7 +201,8 @@ may take a look at mass_storage.c, acm_ms.c and multi.c (sorted by complexity). -* Relation to file storage gadget +Relation to file storage gadget +=============================== The Mass Storage Function and thus the Mass Storage Gadget has been based on the File Storage Gadget. The difference between the two is diff --git a/Documentation/usb/misc_usbsevseg.txt b/Documentation/usb/misc_usbsevseg.txt index 0f6be4f9930b..6274aee083ed 100644 --- a/Documentation/usb/misc_usbsevseg.txt +++ b/Documentation/usb/misc_usbsevseg.txt @@ -1,4 +1,7 @@ +============================= USB 7-Segment Numeric Display +============================= + Manufactured by Delcom Engineering Device Information @@ -13,9 +16,13 @@ Device Modes ------------ By default, the driver assumes the display is only 6 characters The mode for 6 characters is: + MSB 0x06; LSB 0x3f + For the 8 character display: + MSB 0x08; LSB 0xff + The device can accept "text" either in raw, hex, or ascii textmode. raw controls each segment manually, hex expects a value between 0-15 per character, @@ -42,5 +49,3 @@ Device Operation To set multiple decimals points sum up each power. For example, to set the 0th and 3rd decimal place echo 1001 > /sys/bus/usb/.../decimals - - diff --git a/Documentation/usb/mtouchusb.txt b/Documentation/usb/mtouchusb.txt index a91adb26ea7b..d1111b74bf75 100644 --- a/Documentation/usb/mtouchusb.txt +++ b/Documentation/usb/mtouchusb.txt @@ -1,19 +1,27 @@ -CHANGES +================ +mtouchusb driver +================ + +Changes +======= - 0.3 - Created based off of scanner & INSTALL from the original touchscreen driver on freecode (http://freecode.com/projects/3mtouchscreendriver) - Amended for linux-2.4.18, then 2.4.19 - 0.5 - Complete rewrite using Linux Input in 2.6.3 - Unfortunately no calibration support at this time + Unfortunately no calibration support at this time - 1.4 - Multiple changes to support the EXII 5000UC and house cleaning - Changed reset from standard USB dev reset to vendor reset - Changed data sent to host from compensated to raw coordinates - Eliminated vendor/product module params - Performed multiple successful tests with an EXII-5010UC + Changed reset from standard USB dev reset to vendor reset + Changed data sent to host from compensated to raw coordinates + Eliminated vendor/product module params + Performed multiple successful tests with an EXII-5010UC + +Supported Hardware +================== -SUPPORTED HARDWARE: +:: All controllers have the Vendor: 0x0596 & Product: 0x0001 @@ -29,9 +37,10 @@ SUPPORTED HARDWARE: USB Capacitive - Black Case EXII-5030UC USB Capacitive - No Case EXII-5050UC -DRIVER NOTES: +Driver Notes +============ -Installation is simple, you only need to add Linux Input, Linux USB, and the +Installation is simple, you only need to add Linux Input, Linux USB, and the driver to the kernel. The driver can also be optionally built as a module. This driver appears to be one of possible 2 Linux USB Input Touchscreen @@ -49,24 +58,27 @@ The controller screen resolution is now 0 to 16384 for both X and Y reporting the raw touch data. This is the same for the old and new capacitive USB controllers. -Perhaps at some point an abstract function will be placed into evdev so -generic functions like calibrations, resets, and vendor information can be +Perhaps at some point an abstract function will be placed into evdev so +generic functions like calibrations, resets, and vendor information can be requested from the userspace (And the drivers would handle the vendor specific tasks). -TODO: +TODO +==== Implement a control urb again to handle requests to and from the device such as calibration, etc once/if it becomes available. -DISCLAIMER: +Disclaimer +========== -I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support +I am not a MicroTouch/3M employee, nor have I ever been. 3M does not support this driver! If you want touch drivers only supported within X, please go to: http://www.3m.com/3MTouchSystems/ -THANKS: +Thanks +====== A huge thank you to 3M Touch Systems for the EXII-5010UC controllers for testing! diff --git a/Documentation/usb/ohci.txt b/Documentation/usb/ohci.txt index 99320d9fa523..bb3c49719e6b 100644 --- a/Documentation/usb/ohci.txt +++ b/Documentation/usb/ohci.txt @@ -1,3 +1,7 @@ +==== +OHCI +==== + 23-Aug-2002 The "ohci-hcd" driver is a USB Host Controller Driver (HCD) that is derived @@ -29,4 +33,3 @@ work on while the OS is getting around to the relevant IRQ processing. - David Brownell <dbrownell@users.sourceforge.net> - diff --git a/Documentation/usb/rio.txt b/Documentation/usb/rio.txt index aee715af7db7..ca9adcf56355 100644 --- a/Documentation/usb/rio.txt +++ b/Documentation/usb/rio.txt @@ -1,72 +1,80 @@ +============ +Diamonds Rio +============ + Copyright (C) 1999, 2000 Bruce Tenison + Portions Copyright (C) 1999, 2000 David Nelson + Thanks to David Nelson for guidance and the usage of the scanner.txt and scanner.c files to model our driver and this informative file. Mar. 2, 2000 -CHANGES +Changes +======= - Initial Revision -OVERVIEW +Overview +======== This README will address issues regarding how to configure the kernel -to access a RIO 500 mp3 player. +to access a RIO 500 mp3 player. Before I explain how to use this to access the Rio500 please be warned: -W A R N I N G: --------------- +.. warning:: -Please note that this software is still under development. The authors -are in no way responsible for any damage that may occur, no matter how -inconsequential. + Please note that this software is still under development. The authors + are in no way responsible for any damage that may occur, no matter how + inconsequential. It seems that the Rio has a problem when sending .mp3 with low batteries. I suggest when the batteries are low and you want to transfer stuff that you replace it with a fresh one. In my case, what happened is I lost two 16kb blocks (they are no longer usable to store information to it). But I don't -know if that's normal or not; it could simply be a problem with the flash +know if that's normal or not; it could simply be a problem with the flash memory. -In an extreme case, I left my Rio playing overnight and the batteries wore -down to nothing and appear to have corrupted the flash memory. My RIO -needed to be replaced as a result. Diamond tech support is aware of the -problem. Do NOT allow your batteries to wear down to nothing before -changing them. It appears RIO 500 firmware does not handle low battery -power well at all. +In an extreme case, I left my Rio playing overnight and the batteries wore +down to nothing and appear to have corrupted the flash memory. My RIO +needed to be replaced as a result. Diamond tech support is aware of the +problem. Do NOT allow your batteries to wear down to nothing before +changing them. It appears RIO 500 firmware does not handle low battery +power well at all. -On systems with OHCI controllers, the kernel OHCI code appears to have -power on problems with some chipsets. If you are having problems -connecting to your RIO 500, try turning it on first and then plugging it -into the USB cable. +On systems with OHCI controllers, the kernel OHCI code appears to have +power on problems with some chipsets. If you are having problems +connecting to your RIO 500, try turning it on first and then plugging it +into the USB cable. -Contact information: --------------------- +Contact Information +------------------- The main page for the project is hosted at sourceforge.net in the following URL: <http://rio500.sourceforge.net>. You can also go to the project's sourceforge home page at: <http://sourceforge.net/projects/rio500/>. There is also a mailing list: rio500-users@lists.sourceforge.net -Authors: +Authors ------- -Most of the code was written by Cesar Miquel <miquel@df.uba.ar>. Keith +Most of the code was written by Cesar Miquel <miquel@df.uba.ar>. Keith Clayton <kclayton@jps.net> is incharge of the PPC port and making sure things work there. Bruce Tenison <btenison@dibbs.net> is adding support for .fon files and also does testing. The program will mostly sure be re-written and Pete Ikusz along with the rest will re-design it. I would -also like to thank Tri Nguyen <tmn_3022000@hotmail.com> who provided use +also like to thank Tri Nguyen <tmn_3022000@hotmail.com> who provided use with some important information regarding the communication with the Rio. -ADDITIONAL INFORMATION and Userspace tools +Additional Information and userspace tools -http://rio500.sourceforge.net/ + http://rio500.sourceforge.net/ -REQUIREMENTS +Requirements +============ A host with a USB port. Ideally, either a UHCI (Intel) or OHCI (Compaq and others) hardware port should work. @@ -80,11 +88,11 @@ A Linux kernel with RIO 500 support enabled. 'lspci' which is only needed to determine the type of USB hardware available in your machine. -CONFIGURATION +Configuration Using `lspci -v`, determine the type of USB hardware available. - If you see something like: + If you see something like:: USB Controller: ...... Flags: ..... @@ -92,7 +100,7 @@ Using `lspci -v`, determine the type of USB hardware available. Then you have a UHCI based controller. - If you see something like: + If you see something like:: USB Controller: ..... Flags: .... @@ -107,8 +115,9 @@ hardware (determined from the steps above), 'USB Diamond Rio500 support', and (you may need to execute `depmod -a` to update the module dependencies). -Add a device for the USB rio500: - `mknod /dev/usb/rio500 c 180 64` +Add a device for the USB rio500:: + + mknod /dev/usb/rio500 c 180 64 Set appropriate permissions for /dev/usb/rio500 (don't forget about group and world permissions). Both read and write permissions are @@ -116,12 +125,14 @@ required for proper operation. Load the appropriate modules (if compiled as modules): - OHCI: + OHCI:: + modprobe usbcore modprobe usb-ohci modprobe rio500 - UHCI: + UHCI:: + modprobe usbcore modprobe usb-uhci (or uhci) modprobe rio500 @@ -129,10 +140,10 @@ Load the appropriate modules (if compiled as modules): That's it. The Rio500 Utils at: http://rio500.sourceforge.net should be able to access the rio500. -BUGS +Bugs +==== If you encounter any problems feel free to drop me an email. Bruce Tenison btenison@dibbs.net - diff --git a/Documentation/usb/usb-help.txt b/Documentation/usb/usb-help.txt index 4273ca2b86ba..dc23ecd4d802 100644 --- a/Documentation/usb/usb-help.txt +++ b/Documentation/usb/usb-help.txt @@ -1,16 +1,17 @@ -usb-help.txt +============== +USB references +============== + 2008-Mar-7 For USB help other than the readme files that are located in -Documentation/usb/*, see the following: +`Documentation/usb/*`, see the following: -Linux-USB project: http://www.linux-usb.org - mirrors at http://usb.in.tum.de/linux-usb/ - and http://it.linux-usb.org -Linux USB Guide: http://linux-usb.sourceforge.net -Linux-USB device overview (working devices and drivers): - http://www.qbik.ch/usb/devices/ +- Linux-USB project: http://www.linux-usb.org + mirrors at http://usb.in.tum.de/linux-usb/ + and http://it.linux-usb.org +- Linux USB Guide: http://linux-usb.sourceforge.net +- Linux-USB device overview (working devices and drivers): + http://www.qbik.ch/usb/devices/ The Linux-USB mailing list is at linux-usb@vger.kernel.org - -### diff --git a/Documentation/usb/usb-serial.txt b/Documentation/usb/usb-serial.txt index ab100d6ee436..8fa7dbd3da9a 100644 --- a/Documentation/usb/usb-serial.txt +++ b/Documentation/usb/usb-serial.txt @@ -1,4 +1,9 @@ -INTRODUCTION +========== +USB serial +========== + +Introduction +============ The USB serial driver currently supports a number of different USB to serial converter products, as well as some devices that use a serial @@ -8,13 +13,15 @@ INTRODUCTION the different devices. -CONFIGURATION +Configuration +============= Currently the driver can handle up to 256 different serial interfaces at - one time. + one time. The major number that the driver uses is 188 so to use the driver, - create the following nodes: + create the following nodes:: + mknod /dev/ttyUSB0 c 188 0 mknod /dev/ttyUSB1 c 188 1 mknod /dev/ttyUSB2 c 188 2 @@ -28,12 +35,14 @@ CONFIGURATION When the device is connected and recognized by the driver, the driver will print to the system log, which node(s) the device has been bound to. - -SPECIFIC DEVICES SUPPORTED + +Specific Devices Supported +========================== ConnectTech WhiteHEAT 4 port converter +-------------------------------------- ConnectTech has been very forthcoming with information about their device, including providing a unit to test with. @@ -46,6 +55,7 @@ ConnectTech WhiteHEAT 4 port converter HandSpring Visor, Palm USB, and CliĂ© USB driver +----------------------------------------------- This driver works with all HandSpring USB, Palm USB, and Sony CliĂ© USB devices. @@ -62,7 +72,7 @@ HandSpring Visor, Palm USB, and CliĂ© USB driver This goes against the current documentation for pilot-xfer and other packages, but is the only way that it will work due to the hardware in the device. - + When the device is connected, try talking to it on the second port (this is usually /dev/ttyUSB1 if you do not have any other usb-serial devices in the system.) The system log should tell you which port is @@ -78,10 +88,10 @@ HandSpring Visor, Palm USB, and CliĂ© USB driver try resetting the device, first a hot reset, and then a cold reset if necessary. Some devices need this before they can talk to the USB port properly. - + Devices that are not compiled into the kernel can be specified with module parameters. e.g. modprobe visor vendor=0x54c product=0x66 - + There is a webpage and mailing lists for this portion of the driver at: http://sourceforge.net/projects/usbvisor/ @@ -90,6 +100,7 @@ HandSpring Visor, Palm USB, and CliĂ© USB driver PocketPC PDA Driver +------------------- This driver can be used to connect to Compaq iPAQ, HP Jornada, Casio EM500 and other PDAs running Windows CE 3.0 or PocketPC 2002 using a USB @@ -135,12 +146,13 @@ PocketPC PDA Driver be used to flash the ROM, as well as the microP code.. so much for needing Toshiba's $350 serial cable for flashing!! :D NOTE: This has NOT been tested. Use at your own risk. - + For any questions or problems with the driver, please contact Ganesh Varadarajan <ganesh@veritas.com> Keyspan PDA Serial Adapter +-------------------------- Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly sold in Macintosh catalogs, comes in a translucent white/green dongle). @@ -148,32 +160,37 @@ Keyspan PDA Serial Adapter This driver also works for the Xircom/Entrega single port serial adapter. Current status: + Things that work: - basic input/output (tested with 'cu') - blocking write when serial line can't keep up - changing baud rates (up to 115200) - getting/setting modem control pins (TIOCM{GET,SET,BIS,BIC}) - sending break (although duration looks suspect) + - basic input/output (tested with 'cu') + - blocking write when serial line can't keep up + - changing baud rates (up to 115200) + - getting/setting modem control pins (TIOCM{GET,SET,BIS,BIC}) + - sending break (although duration looks suspect) + Things that don't: - device strings (as logged by kernel) have trailing binary garbage - device ID isn't right, might collide with other Keyspan products - changing baud rates ought to flush tx/rx to avoid mangled half characters + - device strings (as logged by kernel) have trailing binary garbage + - device ID isn't right, might collide with other Keyspan products + - changing baud rates ought to flush tx/rx to avoid mangled half characters + Big Things on the todo list: - parity, 7 vs 8 bits per char, 1 or 2 stop bits - HW flow control - not all of the standard USB descriptors are handled: Get_Status, Set_Feature - O_NONBLOCK, select() + - parity, 7 vs 8 bits per char, 1 or 2 stop bits + - HW flow control + - not all of the standard USB descriptors are handled: + Get_Status, Set_Feature, O_NONBLOCK, select() For any questions or problems with this driver, please contact Brian - Warner at warner@lothar.com + Warner at warner@lothar.com Keyspan USA-series Serial Adapters +---------------------------------- - Single, Dual and Quad port adapters - driver uses Keyspan supplied + Single, Dual and Quad port adapters - driver uses Keyspan supplied firmware and is being developed with their support. - + Current status: + The USA-18X, USA-28X, USA-19, USA-19W and USA-49W are supported and have been pretty thoroughly tested at various baud rates with 8-N-1 character settings. Other character lengths and parity setups are @@ -182,32 +199,37 @@ Keyspan USA-series Serial Adapters The USA-28 isn't yet supported though doing so should be pretty straightforward. Contact the maintainer if you require this functionality. - + More information is available at: + http://www.carnationsoftware.com/carnation/Keyspan.html - + For any questions or problems with this driver, please contact Hugh Blemings at hugh@misc.nu FTDI Single Port Serial Driver +------------------------------ This is a single port DB-25 serial adapter. Devices supported include: - -TripNav TN-200 USB GPS - -Navis Engineering Bureau CH-4711 USB GPS + + - TripNav TN-200 USB GPS + - Navis Engineering Bureau CH-4711 USB GPS For any questions or problems with this driver, please contact Bill Ryder. ZyXEL omni.net lcd plus ISDN TA +------------------------------- This is an ISDN TA. Please report both successes and troubles to azummo@towertech.it Cypress M8 CY4601 Family Serial Driver +-------------------------------------- This driver was in most part developed by Neil "koyama" Whelchel. It has been improved since that previous form to support dynamic serial @@ -215,18 +237,19 @@ Cypress M8 CY4601 Family Serial Driver part stable and has been tested on an smp machine. (dual p2) Chipsets supported under CY4601 family: - + CY7C63723, CY7C63742, CY7C63743, CY7C64013 Devices supported: - -DeLorme's USB Earthmate GPS (SiRF Star II lp arch) - -Cypress HID->COM RS232 adapter - - Note: Cypress Semiconductor claims no affiliation with the + - DeLorme's USB Earthmate GPS (SiRF Star II lp arch) + - Cypress HID->COM RS232 adapter + + Note: + Cypress Semiconductor claims no affiliation with the hid->com device. - Most devices using chipsets under the CY4601 family should + Most devices using chipsets under the CY4601 family should work with the driver. As long as they stay true to the CY4601 usbserial specification. @@ -236,8 +259,9 @@ Cypress M8 CY4601 Family Serial Driver upon start init to this setting. usbserial core provides the rest of the termios settings, along with some custom termios so that the output is in proper format and parsable. - - The device can be put into sirf mode by issuing NMEA command: + + The device can be put into sirf mode by issuing NMEA command:: + $PSRF100,<protocol>,<baud>,<databits>,<stopbits>,<parity>*CHECKSUM $PSRF100,0,9600,8,1,0*0C @@ -259,11 +283,14 @@ Cypress M8 CY4601 Family Serial Driver If you have any questions, problems, patches, feature requests, etc. you can contact me here via email: + dignome@gmail.com + (your problems/patches can alternately be submitted to usb-devel) Digi AccelePort Driver +---------------------- This driver supports the Digi AccelePort USB 2 and 4 devices, 2 port (plus a parallel port) and 4 port USB serial converters. The driver @@ -285,42 +312,49 @@ Digi AccelePort Driver Belkin USB Serial Adapter F5U103 +-------------------------------- Single port DB-9/PS-2 serial adapter from Belkin with firmware by eTEK Labs. The Peracom single port serial adapter also works with this driver, as well as the GoHubs adapter. Current status: + The following have been tested and work: - Baud rate 300-230400 - Data bits 5-8 - Stop bits 1-2 - Parity N,E,O,M,S - Handshake None, Software (XON/XOFF), Hardware (CTSRTS,CTSDTR)* - Break Set and clear - Line control Input/Output query and control ** - - * Hardware input flow control is only enabled for firmware + + - Baud rate 300-230400 + - Data bits 5-8 + - Stop bits 1-2 + - Parity N,E,O,M,S + - Handshake None, Software (XON/XOFF), Hardware (CTSRTS,CTSDTR) [1]_ + - Break Set and clear + - Line control Input/Output query and control [2]_ + + .. [1] + Hardware input flow control is only enabled for firmware levels above 2.06. Read source code comments describing Belkin firmware errata. Hardware output flow control is working for all firmware versions. - ** Queries of inputs (CTS,DSR,CD,RI) show the last + + .. [2] + Queries of inputs (CTS,DSR,CD,RI) show the last reported state. Queries of outputs (DTR,RTS) show the last requested state and may not reflect current state as set by automatic hardware flow control. TO DO List: - -- Add true modem control line query capability. Currently tracks the - states reported by the interrupt and the states requested. - -- Add error reporting back to application for UART error conditions. - -- Add support for flush ioctls. - -- Add everything else that is missing :) + - Add true modem control line query capability. Currently tracks the + states reported by the interrupt and the states requested. + - Add error reporting back to application for UART error conditions. + - Add support for flush ioctls. + - Add everything else that is missing :) For any questions or problems with this driver, please contact William Greathouse at wgreathouse@smva.com Empeg empeg-car Mark I/II Driver +-------------------------------- This is an experimental driver to provide connectivity support for the client synchronization tools for an Empeg empeg-car mp3 player. @@ -335,6 +369,7 @@ Empeg empeg-car Mark I/II Driver MCT USB Single Port Serial Adapter U232 +--------------------------------------- This driver is for the MCT USB-RS232 Converter (25 pin, Model No. U232-P25) from Magic Control Technology Corp. (there is also a 9 pin @@ -355,35 +390,39 @@ MCT USB Single Port Serial Adapter U232 Inside Out Networks Edgeport Driver +----------------------------------- This driver supports all devices made by Inside Out Networks, specifically the following models: - Edgeport/4 - Rapidport/4 - Edgeport/4t - Edgeport/2 - Edgeport/4i - Edgeport/2i - Edgeport/421 - Edgeport/21 - Edgeport/8 - Edgeport/8 Dual - Edgeport/2D8 - Edgeport/4D8 - Edgeport/8i - Edgeport/2 DIN - Edgeport/4 DIN - Edgeport/16 Dual + + - Edgeport/4 + - Rapidport/4 + - Edgeport/4t + - Edgeport/2 + - Edgeport/4i + - Edgeport/2i + - Edgeport/421 + - Edgeport/21 + - Edgeport/8 + - Edgeport/8 Dual + - Edgeport/2D8 + - Edgeport/4D8 + - Edgeport/8i + - Edgeport/2 DIN + - Edgeport/4 DIN + - Edgeport/16 Dual For any questions or problems with this driver, please contact Greg Kroah-Hartman at greg@kroah.com REINER SCT cyberJack pinpad/e-com USB chipcard reader - +----------------------------------------------------- + Interface to ISO 7816 compatible contactbased chipcards, e.g. GSM SIMs. - + Current status: + This is the kernel part of the driver for this USB card reader. There is also a user part for a CT-API driver available. A site for downloading is TBA. For now, you can request it from the @@ -394,6 +433,7 @@ REINER SCT cyberJack pinpad/e-com USB chipcard reader Prolific PL2303 Driver +---------------------- This driver supports any device that has the PL2303 chip from Prolific in it. This includes a number of single port USB to serial converters, @@ -403,11 +443,13 @@ Prolific PL2303 Driver For any questions or problems with this driver, please contact Greg Kroah-Hartman at greg@kroah.com - + KL5KUSB105 chipset / PalmConnect USB single-port adapter - +-------------------------------------------------------- + Current status: + The driver was put together by looking at the usb bus transactions done by Palm's driver under Windows, so a lot of functionality is still missing. Notably, serial ioctls are sometimes faked or not yet @@ -417,21 +459,25 @@ Current status: are supported, but handshaking (software or hardware) is not, which is why it is wise to cut down on the rate used is wise for large transfers until this is settled. - + See http://www.uuhaus.de/linux/palmconnect.html for up-to-date information on this driver. Winchiphead CH341 Driver +------------------------ This driver is for the Winchiphead CH341 USB-RS232 Converter. This chip also implements an IEEE 1284 parallel port, I2C and SPI, but that is not supported by the driver. The protocol was analyzed from the behaviour of the Windows driver, no datasheet is available at present. + The manufacturer's website: http://www.winchiphead.com/. + For any questions or problems with this driver, please contact frank@kingswood-consulting.co.uk. Moschip MCS7720, MCS7715 driver +------------------------------- These chips are present in devices sold by various manufacturers, such as Syba and Cables Unlimited. There may be others. The 7720 provides two serial @@ -449,20 +495,24 @@ Moschip MCS7720, MCS7715 driver don't have one of these devices, so I can't say for sure. Generic Serial driver +--------------------- If your device is not one of the above listed devices, compatible with the above models, you can try out the "generic" interface. This interface does not provide any type of control messages sent to the device, and does not support any kind of device flow control. All that is required of your device is that it has at least one bulk in endpoint, - or one bulk out endpoint. + or one bulk out endpoint. + + To enable the generic driver to recognize your device, provide:: - To enable the generic driver to recognize your device, provide echo <vid> <pid> >/sys/bus/usb-serial/drivers/generic/new_id + where the <vid> and <pid> is replaced with the hex representation of your device's vendor id and product id. If the driver is compiled as a module you can also provide one id when - loading the module + loading the module:: + insmod usbserial vendor=0x#### product=0x#### This driver has been successfully used to connect to the NetChip USB @@ -473,7 +523,8 @@ Generic Serial driver Kroah-Hartman at greg@kroah.com -CONTACT: +Contact +======= If anyone has any problems using these drivers, with any of the above specified products, please contact the specific driver's author listed diff --git a/Documentation/usb/usbip_protocol.txt b/Documentation/usb/usbip_protocol.txt index c7a0f4c7e7f1..988c832166cd 100644 --- a/Documentation/usb/usbip_protocol.txt +++ b/Documentation/usb/usbip_protocol.txt @@ -1,3 +1,7 @@ +=============== +USB/IP protocol +=============== + PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! 28 Jun 2011 @@ -12,6 +16,8 @@ in one or more pieces at the low level transport layer). The server sends back the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the TCP/IP connection is closed. +:: + virtual host controller usb host "client" "server" (imports USB devices) (exports USB devices) @@ -32,6 +38,8 @@ send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. +:: + virtual host controller usb host "client" "server" (imports USB devices) (exports USB devices) @@ -88,270 +96,316 @@ The fields are in network (big endian) byte order meaning that the most signific byte (MSB) is stored at the lowest address. -OP_REQ_DEVLIST: Retrieve the list of exported USB devices. +OP_REQ_DEVLIST: + Retrieve the list of exported USB devices. - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 ------------+--------+------------+--------------------------------------------------- - 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB - | | | devices. ------------+--------+------------+--------------------------------------------------- - 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB | +| | | | devices. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 | ++-----------+--------+------------+---------------------------------------------------+ -OP_REP_DEVLIST: Reply with the list of exported USB devices. +OP_REP_DEVLIST: + Reply with the list of exported USB devices. - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0. ------------+--------+------------+--------------------------------------------------- - 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. ------------+--------+------------+--------------------------------------------------- - 4 | 4 | 0x00000000 | Status: 0 for OK ------------+--------+------------+--------------------------------------------------- - 8 | 4 | n | Number of exported devices: 0 means no exported - | | | devices. ------------+--------+------------+--------------------------------------------------- - 0x0C | | | From now on the exported n devices are described, - | | | if any. If no devices are exported the message - | | | ends with the previous "number of exported - | | | devices" field. ------------+--------+------------+--------------------------------------------------- - | 256 | | path: Path of the device on the host exporting the - | | | USB device, string closed with zero byte, e.g. - | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" - | | | The unused bytes shall be filled with zero - | | | bytes. ------------+--------+------------+--------------------------------------------------- - 0x10C | 32 | | busid: Bus ID of the exported device, string - | | | closed with zero byte, e.g. "3-2". The unused - | | | bytes shall be filled with zero bytes. ------------+--------+------------+--------------------------------------------------- - 0x12C | 4 | | busnum ------------+--------+------------+--------------------------------------------------- - 0x130 | 4 | | devnum ------------+--------+------------+--------------------------------------------------- - 0x134 | 4 | | speed ------------+--------+------------+--------------------------------------------------- - 0x138 | 2 | | idVendor ------------+--------+------------+--------------------------------------------------- - 0x13A | 2 | | idProduct ------------+--------+------------+--------------------------------------------------- - 0x13C | 2 | | bcdDevice ------------+--------+------------+--------------------------------------------------- - 0x13E | 1 | | bDeviceClass ------------+--------+------------+--------------------------------------------------- - 0x13F | 1 | | bDeviceSubClass ------------+--------+------------+--------------------------------------------------- - 0x140 | 1 | | bDeviceProtocol ------------+--------+------------+--------------------------------------------------- - 0x141 | 1 | | bConfigurationValue ------------+--------+------------+--------------------------------------------------- - 0x142 | 1 | | bNumConfigurations ------------+--------+------------+--------------------------------------------------- - 0x143 | 1 | | bNumInterfaces ------------+--------+------------+--------------------------------------------------- - 0x144 | | m_0 | From now on each interface is described, all - | | | together bNumInterfaces times, with the - | | | the following 4 fields: ------------+--------+------------+--------------------------------------------------- - | 1 | | bInterfaceClass ------------+--------+------------+--------------------------------------------------- - 0x145 | 1 | | bInterfaceSubClass ------------+--------+------------+--------------------------------------------------- - 0x146 | 1 | | bInterfaceProtocol ------------+--------+------------+--------------------------------------------------- - 0x147 | 1 | | padding byte for alignment, shall be set to zero ------------+--------+------------+--------------------------------------------------- - 0xC + | | | The second exported USB device starts at i=1 - i*0x138 + | | | with the busid field. - m_(i-1)*4 | | | ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.| ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: 0 for OK | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | n | Number of exported devices: 0 means no exported | +| | | | devices. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x0C | | | From now on the exported n devices are described, | +| | | | if any. If no devices are exported the message | +| | | | ends with the previous "number of exported | +| | | | devices" field. | ++-----------+--------+------------+---------------------------------------------------+ +| | 256 | | path: Path of the device on the host exporting the| +| | | | USB device, string closed with zero byte, e.g. | +| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" | +| | | | The unused bytes shall be filled with zero | +| | | | bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10C | 32 | | busid: Bus ID of the exported device, string | +| | | | closed with zero byte, e.g. "3-2". The unused | +| | | | bytes shall be filled with zero bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x12C | 4 | | busnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x130 | 4 | | devnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x134 | 4 | | speed | ++-----------+--------+------------+---------------------------------------------------+ +| 0x138 | 2 | | idVendor | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13A | 2 | | idProduct | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13C | 2 | | bcdDevice | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13E | 1 | | bDeviceClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13F | 1 | | bDeviceSubClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x140 | 1 | | bDeviceProtocol | ++-----------+--------+------------+---------------------------------------------------+ +| 0x141 | 1 | | bConfigurationValue | ++-----------+--------+------------+---------------------------------------------------+ +| 0x142 | 1 | | bNumConfigurations | ++-----------+--------+------------+---------------------------------------------------+ +| 0x143 | 1 | | bNumInterfaces | ++-----------+--------+------------+---------------------------------------------------+ +| 0x144 | | m_0 | From now on each interface is described, all | +| | | | together bNumInterfaces times, with the | +| | | | the following 4 fields: | ++-----------+--------+------------+---------------------------------------------------+ +| | 1 | | bInterfaceClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x145 | 1 | | bInterfaceSubClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x146 | 1 | | bInterfaceProtocol | ++-----------+--------+------------+---------------------------------------------------+ +| 0x147 | 1 | | padding byte for alignment, shall be set to zero | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC + | | | The second exported USB device starts at i=1 | +| i*0x138 + | | | with the busid field. | +| m_(i-1)*4 | | | | ++-----------+--------+------------+---------------------------------------------------+ -OP_REQ_IMPORT: Request to import (attach) a remote USB device. +OP_REQ_IMPORT: + Request to import (attach) a remote USB device. - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 ------------+--------+------------+--------------------------------------------------- - 2 | 2 | 0x8003 | Command code: import a remote USB device. ------------+--------+------------+--------------------------------------------------- - 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 ------------+--------+------------+--------------------------------------------------- - 8 | 32 | | busid: the busid of the exported device on the - | | | remote host. The possible values are taken - | | | from the message field OP_REP_DEVLIST.busid. - | | | A string closed with zero, the unused bytes - | | | shall be filled with zeros. ------------+--------+------------+--------------------------------------------------- ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x8003 | Command code: import a remote USB device. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 32 | | busid: the busid of the exported device on the | +| | | | remote host. The possible values are taken | +| | | | from the message field OP_REP_DEVLIST.busid. | +| | | | A string closed with zero, the unused bytes | +| | | | shall be filled with zeros. | ++-----------+--------+------------+---------------------------------------------------+ -OP_REP_IMPORT: Reply to import (attach) a remote USB device. +OP_REP_IMPORT: + Reply to import (attach) a remote USB device. - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 ------------+--------+------------+--------------------------------------------------- - 2 | 2 | 0x0003 | Reply code: Reply to import. ------------+--------+------------+--------------------------------------------------- - 4 | 4 | 0x00000000 | Status: 0 for OK - | | | 1 for error ------------+--------+------------+--------------------------------------------------- - 8 | | | From now on comes the details of the imported - | | | device, if the previous status field was OK (0), - | | | otherwise the reply ends with the status field. ------------+--------+------------+--------------------------------------------------- - | 256 | | path: Path of the device on the host exporting the - | | | USB device, string closed with zero byte, e.g. - | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" - | | | The unused bytes shall be filled with zero - | | | bytes. ------------+--------+------------+--------------------------------------------------- - 0x108 | 32 | | busid: Bus ID of the exported device, string - | | | closed with zero byte, e.g. "3-2". The unused - | | | bytes shall be filled with zero bytes. ------------+--------+------------+--------------------------------------------------- - 0x128 | 4 | | busnum ------------+--------+------------+--------------------------------------------------- - 0x12C | 4 | | devnum ------------+--------+------------+--------------------------------------------------- - 0x130 | 4 | | speed ------------+--------+------------+--------------------------------------------------- - 0x134 | 2 | | idVendor ------------+--------+------------+--------------------------------------------------- - 0x136 | 2 | | idProduct ------------+--------+------------+--------------------------------------------------- - 0x138 | 2 | | bcdDevice ------------+--------+------------+--------------------------------------------------- - 0x139 | 1 | | bDeviceClass ------------+--------+------------+--------------------------------------------------- - 0x13A | 1 | | bDeviceSubClass ------------+--------+------------+--------------------------------------------------- - 0x13B | 1 | | bDeviceProtocol ------------+--------+------------+--------------------------------------------------- - 0x13C | 1 | | bConfigurationValue ------------+--------+------------+--------------------------------------------------- - 0x13D | 1 | | bNumConfigurations ------------+--------+------------+--------------------------------------------------- - 0x13E | 1 | | bNumInterfaces ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | ++-----------+--------+------------+---------------------------------------------------+ +| 2 | 2 | 0x0003 | Reply code: Reply to import. | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | 0x00000000 | Status: | +| | | | | +| | | | - 0 for OK | +| | | | - 1 for error | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | | | From now on comes the details of the imported | +| | | | device, if the previous status field was OK (0), | +| | | | otherwise the reply ends with the status field. | ++-----------+--------+------------+---------------------------------------------------+ +| | 256 | | path: Path of the device on the host exporting the| +| | | | USB device, string closed with zero byte, e.g. | +| | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" | +| | | | The unused bytes shall be filled with zero | +| | | | bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x108 | 32 | | busid: Bus ID of the exported device, string | +| | | | closed with zero byte, e.g. "3-2". The unused | +| | | | bytes shall be filled with zero bytes. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x128 | 4 | | busnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x12C | 4 | | devnum | ++-----------+--------+------------+---------------------------------------------------+ +| 0x130 | 4 | | speed | ++-----------+--------+------------+---------------------------------------------------+ +| 0x134 | 2 | | idVendor | ++-----------+--------+------------+---------------------------------------------------+ +| 0x136 | 2 | | idProduct | ++-----------+--------+------------+---------------------------------------------------+ +| 0x138 | 2 | | bcdDevice | ++-----------+--------+------------+---------------------------------------------------+ +| 0x139 | 1 | | bDeviceClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13A | 1 | | bDeviceSubClass | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13B | 1 | | bDeviceProtocol | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13C | 1 | | bConfigurationValue | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13D | 1 | | bNumConfigurations | ++-----------+--------+------------+---------------------------------------------------+ +| 0x13E | 1 | | bNumInterfaces | ++-----------+--------+------------+---------------------------------------------------+ -USBIP_CMD_SUBMIT: Submit an URB +USBIP_CMD_SUBMIT: + Submit an URB - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 4 | 0x00000001 | command: Submit an URB ------------+--------+------------+--------------------------------------------------- - 4 | 4 | | seqnum: the sequence number of the URB to submit ------------+--------+------------+--------------------------------------------------- - 8 | 4 | | devid ------------+--------+------------+--------------------------------------------------- - 0xC | 4 | | direction: 0: USBIP_DIR_OUT - | | | 1: USBIP_DIR_IN ------------+--------+------------+--------------------------------------------------- - 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 ------------+--------+------------+--------------------------------------------------- - 0x14 | 4 | | transfer_flags: possible values depend on the - | | | URB transfer type, see below ------------+--------+------------+--------------------------------------------------- - 0x18 | 4 | | transfer_buffer_length ------------+--------+------------+--------------------------------------------------- - 0x1C | 4 | | start_frame: specify the selected frame to - | | | transmit an ISO frame, ignored if URB_ISO_ASAP - | | | is specified at transfer_flags ------------+--------+------------+--------------------------------------------------- - 0x20 | 4 | | number_of_packets: number of ISO packets ------------+--------+------------+--------------------------------------------------- - 0x24 | 4 | | interval: maximum time for the request on the - | | | server-side host controller ------------+--------+------------+--------------------------------------------------- - 0x28 | 8 | | setup: data bytes for USB setup, filled with - | | | zeros if not used ------------+--------+------------+--------------------------------------------------- - 0x30 | | | URB data. For ISO transfers the padding between - | | | each ISO packets is not transmitted. ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000001 | command: Submit an URB | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: the sequence number of the URB to submit | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | transfer_flags: possible values depend on the | +| | | | URB transfer type, see below | ++-----------+--------+------------+---------------------------------------------------+ +| 0x18 | 4 | | transfer_buffer_length | ++-----------+--------+------------+---------------------------------------------------+ +| 0x1C | 4 | | start_frame: specify the selected frame to | +| | | | transmit an ISO frame, ignored if URB_ISO_ASAP | +| | | | is specified at transfer_flags | ++-----------+--------+------------+---------------------------------------------------+ +| 0x20 | 4 | | number_of_packets: number of ISO packets | ++-----------+--------+------------+---------------------------------------------------+ +| 0x24 | 4 | | interval: maximum time for the request on the | +| | | | server-side host controller | ++-----------+--------+------------+---------------------------------------------------+ +| 0x28 | 8 | | setup: data bytes for USB setup, filled with | +| | | | zeros if not used | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | | | URB data. For ISO transfers the padding between | +| | | | each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ - Allowed transfer_flags | value | control | interrupt | bulk | isochronous - -------------------------+------------+---------+-----------+----------+------------- - URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no - URB_ISO_ASAP | 0x00000002 | no | no | no | yes - URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes - URB_ZERO_PACKET | 0x00000040 | no | no | only out | no - URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes - URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes - URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes + +-------------------------+------------+---------+-----------+----------+-------------+ + | Allowed transfer_flags | value | control | interrupt | bulk | isochronous | + +=========================+============+=========+===========+==========+=============+ + | URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_ISO_ASAP | 0x00000002 | no | no | no | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_ZERO_PACKET | 0x00000040 | no | no | only out | no | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ + | URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes | + +-------------------------+------------+---------+-----------+----------+-------------+ -USBIP_RET_SUBMIT: Reply for submitting an URB +USBIP_RET_SUBMIT: + Reply for submitting an URB - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 4 | 0x00000003 | command ------------+--------+------------+--------------------------------------------------- - 4 | 4 | | seqnum: URB sequence number ------------+--------+------------+--------------------------------------------------- - 8 | 4 | | devid ------------+--------+------------+--------------------------------------------------- - 0xC | 4 | | direction: 0: USBIP_DIR_OUT - | | | 1: USBIP_DIR_IN ------------+--------+------------+--------------------------------------------------- - 0x10 | 4 | | ep: endpoint number ------------+--------+------------+--------------------------------------------------- - 0x14 | 4 | | status: zero for successful URB transaction, - | | | otherwise some kind of error happened. ------------+--------+------------+--------------------------------------------------- - 0x18 | 4 | n | actual_length: number of URB data bytes ------------+--------+------------+--------------------------------------------------- - 0x1C | 4 | | start_frame: for an ISO frame the actually - | | | selected frame for transmit. ------------+--------+------------+--------------------------------------------------- - 0x20 | 4 | | number_of_packets ------------+--------+------------+--------------------------------------------------- - 0x24 | 4 | | error_count ------------+--------+------------+--------------------------------------------------- - 0x28 | 8 | | setup: data bytes for USB setup, filled with - | | | zeros if not used ------------+--------+------------+--------------------------------------------------- - 0x30 | n | | URB data bytes. For ISO transfers the padding - | | | between each ISO packets is not transmitted. ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000003 | command | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: URB sequence number | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | status: zero for successful URB transaction, | +| | | | otherwise some kind of error happened. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x18 | 4 | n | actual_length: number of URB data bytes | ++-----------+--------+------------+---------------------------------------------------+ +| 0x1C | 4 | | start_frame: for an ISO frame the actually | +| | | | selected frame for transmit. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x20 | 4 | | number_of_packets | ++-----------+--------+------------+---------------------------------------------------+ +| 0x24 | 4 | | error_count | ++-----------+--------+------------+---------------------------------------------------+ +| 0x28 | 8 | | setup: data bytes for USB setup, filled with | +| | | | zeros if not used | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | n | | URB data bytes. For ISO transfers the padding | +| | | | between each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ -USBIP_CMD_UNLINK: Unlink an URB +USBIP_CMD_UNLINK: + Unlink an URB - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 4 | 0x00000002 | command: URB unlink command ------------+--------+------------+--------------------------------------------------- - 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so? ------------+--------+------------+--------------------------------------------------- - 8 | 4 | | devid ------------+--------+------------+--------------------------------------------------- - 0xC | 4 | | direction: 0: USBIP_DIR_OUT - | | | 1: USBIP_DIR_IN ------------+--------+------------+--------------------------------------------------- - 0x10 | 4 | | ep: endpoint number: zero ------------+--------+------------+--------------------------------------------------- - 0x14 | 4 | | seqnum: the URB sequence number given previously - | | | at USBIP_CMD_SUBMIT.seqnum field ------------+--------+------------+--------------------------------------------------- - 0x30 | n | | URB data bytes. For ISO transfers the padding - | | | between each ISO packets is not transmitted. ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000002 | command: URB unlink command | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: URB sequence number to unlink: | +| | | | | +| | | | FIXME: | +| | | | is this so? | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number: zero | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | seqnum: the URB sequence number given previously | +| | | | at USBIP_CMD_SUBMIT.seqnum field | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | n | | URB data bytes. For ISO transfers the padding | +| | | | between each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ -USBIP_RET_UNLINK: Reply for URB unlink +USBIP_RET_UNLINK: + Reply for URB unlink - Offset | Length | Value | Description ------------+--------+------------+--------------------------------------------------- - 0 | 4 | 0x00000004 | command: reply for the URB unlink command ------------+--------+------------+--------------------------------------------------- - 4 | 4 | | seqnum: the unlinked URB sequence number ------------+--------+------------+--------------------------------------------------- - 8 | 4 | | devid ------------+--------+------------+--------------------------------------------------- - 0xC | 4 | | direction: 0: USBIP_DIR_OUT - | | | 1: USBIP_DIR_IN ------------+--------+------------+--------------------------------------------------- - 0x10 | 4 | | ep: endpoint number ------------+--------+------------+--------------------------------------------------- - 0x14 | 4 | | status: This is the value contained in the - | | | urb->status in the URB completition handler. - | | | FIXME: a better explanation needed. ------------+--------+------------+--------------------------------------------------- - 0x30 | n | | URB data bytes. For ISO transfers the padding - | | | between each ISO packets is not transmitted. ++-----------+--------+------------+---------------------------------------------------+ +| Offset | Length | Value | Description | ++===========+========+============+===================================================+ +| 0 | 4 | 0x00000004 | command: reply for the URB unlink command | ++-----------+--------+------------+---------------------------------------------------+ +| 4 | 4 | | seqnum: the unlinked URB sequence number | ++-----------+--------+------------+---------------------------------------------------+ +| 8 | 4 | | devid | ++-----------+--------+------------+---------------------------------------------------+ +| 0xC | 4 | | direction: | +| | | | | +| | | | - 0: USBIP_DIR_OUT | +| | | | - 1: USBIP_DIR_IN | ++-----------+--------+------------+---------------------------------------------------+ +| 0x10 | 4 | | ep: endpoint number | ++-----------+--------+------------+---------------------------------------------------+ +| 0x14 | 4 | | status: This is the value contained in the | +| | | | urb->status in the URB completition handler. | +| | | | | +| | | | FIXME: | +| | | | a better explanation needed. | ++-----------+--------+------------+---------------------------------------------------+ +| 0x30 | n | | URB data bytes. For ISO transfers the padding | +| | | | between each ISO packets is not transmitted. | ++-----------+--------+------------+---------------------------------------------------+ diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 28425f736756..b0bd51080799 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -1,4 +1,9 @@ -* Introduction +====== +usbmon +====== + +Introduction +============ The name "usbmon" in lowercase refers to a facility in kernel which is used to collect traces of I/O on the USB bus. This function is analogous @@ -16,7 +21,8 @@ Two APIs are currently implemented: "text" and "binary". The binary API is available through a character device in /dev namespace and is an ABI. The text API is deprecated since 2.6.35, but available for convenience. -* How to use usbmon to collect raw text traces +How to use usbmon to collect raw text traces +============================================ Unlike the packet socket, usbmon has an interface which provides traces in a text format. This is used for two purposes. First, it serves as a @@ -26,38 +32,41 @@ are finalized. Second, humans can read it in case tools are not available. To collect a raw text trace, execute following steps. 1. Prepare +---------- Mount debugfs (it has to be enabled in your kernel configuration), and load the usbmon module (if built as module). The second step is skipped -if usbmon is built into the kernel. +if usbmon is built into the kernel:: -# mount -t debugfs none_debugs /sys/kernel/debug -# modprobe usbmon -# + # mount -t debugfs none_debugs /sys/kernel/debug + # modprobe usbmon + # -Verify that bus sockets are present. +Verify that bus sockets are present: -# ls /sys/kernel/debug/usb/usbmon -0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u -# + # ls /sys/kernel/debug/usb/usbmon + 0s 0u 1s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u + # Now you can choose to either use the socket '0u' (to capture packets on all buses), and skip to step #3, or find the bus used by your device with step #2. This allows to filter away annoying devices that talk continuously. 2. Find which bus connects to the desired device +------------------------------------------------ Run "cat /sys/kernel/debug/usb/devices", and find the T-line which corresponds to the device. Usually you do it by looking for the vendor string. If you have many similar devices, unplug one and compare the two /sys/kernel/debug/usb/devices outputs. The T-line will have a bus number. -Example: -T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 -D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 -P: Vendor=0557 ProdID=2004 Rev= 1.00 -S: Manufacturer=ATEN -S: Product=UC100KM V2.00 +Example:: + + T: Bus=03 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 0 + D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 + P: Vendor=0557 ProdID=2004 Rev= 1.00 + S: Manufacturer=ATEN + S: Product=UC100KM V2.00 "Bus=03" means it's bus 3. Alternatively, you can look at the output from "lsusb" and get the bus number from the appropriate line. Example: @@ -65,23 +74,28 @@ S: Product=UC100KM V2.00 Bus 003 Device 002: ID 0557:2004 ATEN UC100KM V2.00 3. Start 'cat' +-------------- + +:: -# cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out + # cat /sys/kernel/debug/usb/usbmon/3u > /tmp/1.mon.out -to listen on a single bus, otherwise, to listen on all buses, type: +to listen on a single bus, otherwise, to listen on all buses, type:: -# cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out + # cat /sys/kernel/debug/usb/usbmon/0u > /tmp/1.mon.out This process will read until it is killed. Naturally, the output can be redirected to a desirable location. This is preferred, because it is going to be quite long. 4. Perform the desired operation on the USB bus +----------------------------------------------- This is where you do something that creates the traffic: plug in a flash key, copy files, control a webcam, etc. 5. Kill cat +----------- Usually it's done with a keyboard interrupt (Control-C). @@ -89,7 +103,8 @@ At this point the output file (/tmp/1.mon.out in this example) can be saved, sent by e-mail, or inspected with a text editor. In the last case make sure that the file size is not excessive for your favourite editor. -* Raw text data format +Raw text data format +==================== Two formats are supported currently: the original, or '1t' format, and the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u' @@ -122,10 +137,14 @@ Here is the list of words, from left to right: - "Address" word (formerly a "pipe"). It consists of four fields, separated by colons: URB type and direction, Bus number, Device address, Endpoint number. Type and direction are encoded with two bytes in the following manner: + + == == ============================= Ci Co Control input and output Zi Zo Isochronous input and output Ii Io Interrupt input and output Bi Bo Bulk input and output + == == ============================= + Bus number, Device address, and Endpoint are decimal numbers, but they may have leading zeros, for the sake of human readers. @@ -178,24 +197,25 @@ Here is the list of words, from left to right: Examples: -An input control transfer to get a port status. +An input control transfer to get a port status:: -d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < -d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 + d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 < + d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000 An output bulk transfer to send a SCSI command 0x28 (READ_10) in a 31-byte -Bulk wrapper to a storage device at address 5: +Bulk wrapper to a storage device at address 5:: -dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 -dd65f0e8 4128379808 C Bo:1:005:2 0 31 > + dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 ad000000 00800000 80010a28 20000000 20000040 00000000 000000 + dd65f0e8 4128379808 C Bo:1:005:2 0 31 > -* Raw binary format and API +Raw binary format and API +========================= The overall architecture of the API is about the same as the one above, only the events are delivered in binary format. Each event is sent in -the following structure (its name is made up, so that we can refer to it): +the following structure (its name is made up, so that we can refer to it):: -struct usbmon_packet { + struct usbmon_packet { u64 id; /* 0: URB ID - from submission to callback */ unsigned char type; /* 8: Same as text; extensible. */ unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ @@ -220,7 +240,7 @@ struct usbmon_packet { int start_frame; /* 52: For ISO */ unsigned int xfer_flags; /* 56: copy of URB's transfer_flags */ unsigned int ndesc; /* 60: Actual number of ISO descriptors */ -}; /* 64 total length */ + }; /* 64 total length */ These events can be received from a character device by reading with read(2), with an ioctl(2), or by accessing the buffer with mmap. However, read(2) @@ -244,12 +264,12 @@ no events are available. MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) -The argument is a pointer to the following structure: +The argument is a pointer to the following structure:: -struct mon_bin_stats { + struct mon_bin_stats { u32 queued; u32 dropped; -}; + }; The member "queued" refers to the number of events currently queued in the buffer (and not to the number of events processed since the last reset). @@ -273,13 +293,13 @@ This call returns the current size of the buffer in bytes. These calls wait for events to arrive if none were in the kernel buffer, then return the first event. The argument is a pointer to the following -structure: +structure:: -struct mon_get_arg { + struct mon_get_arg { struct usbmon_packet *hdr; void *data; size_t alloc; /* Length of data (can be zero) */ -}; + }; Before the call, hdr, data, and alloc should be filled. Upon return, the area pointed by hdr contains the next event structure, and the data buffer contains @@ -290,13 +310,13 @@ The MON_IOCX_GET copies 48 bytes to hdr area, MON_IOCX_GETX copies 64 bytes. MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) This ioctl is primarily used when the application accesses the buffer -with mmap(2). Its argument is a pointer to the following structure: +with mmap(2). Its argument is a pointer to the following structure:: -struct mon_mfetch_arg { + struct mon_mfetch_arg { uint32_t *offvec; /* Vector of events fetched */ uint32_t nfetch; /* Number of events to fetch (out: fetched) */ uint32_t nflush; /* Number of events to flush */ -}; + }; The ioctl operates in 3 stages. @@ -329,7 +349,7 @@ be polled with select(2) and poll(2). But lseek(2) does not work. The basic idea is simple: To prepare, map the buffer by getting the current size, then using mmap(2). -Then, execute a loop similar to the one written in pseudo-code below: +Then, execute a loop similar to the one written in pseudo-code below:: struct mon_mfetch_arg fetch; struct usbmon_packet *hdr; diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index b1b846d8a094..bd9165241b6c 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -123,9 +123,9 @@ In precedence order, they are: to userland as the errno without executing the system call. ``SECCOMP_RET_USER_NOTIF``: - Results in a ``struct seccomp_notif`` message sent on the userspace - notification fd, if it is attached, or ``-ENOSYS`` if it is not. See below - on discussion of how to handle user notifications. + Results in a ``struct seccomp_notif`` message sent on the userspace + notification fd, if it is attached, or ``-ENOSYS`` if it is not. See + below on discussion of how to handle user notifications. ``SECCOMP_RET_TRACE``: When returned, this value will cause the kernel to attempt to @@ -133,7 +133,7 @@ In precedence order, they are: call. If there is no tracer present, ``-ENOSYS`` is returned to userland and the system call is not executed. - A tracer will be notified if it requests ``PTRACE_O_TRACESECCOM``P + A tracer will be notified if it requests ``PTRACE_O_TRACESECCOMP`` using ``ptrace(PTRACE_SETOPTIONS)``. The tracer will be notified of a ``PTRACE_EVENT_SECCOMP`` and the ``SECCOMP_RET_DATA`` portion of the BPF program return value will be available to the tracer diff --git a/Documentation/video-output.txt b/Documentation/video-output.txt index e517011be4f9..56d6fa2e2368 100644 --- a/Documentation/video-output.txt +++ b/Documentation/video-output.txt @@ -1,34 +1,34 @@ +Video Output Switcher Control +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Video Output Switcher Control - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 2006 luming.yu@intel.com +2006 luming.yu@intel.com The output sysfs class driver provides an abstract video output layer that can be used to hook platform specific methods to enable/disable video output device through common sysfs interface. For example, on my IBM ThinkPad T42 laptop, The ACPI video driver registered its output devices and read/write -method for 'state' with output sysfs class. The user interface under sysfs is: +method for 'state' with output sysfs class. The user interface under sysfs is:: -linux:/sys/class/video_output # tree . -. -|-- CRT0 -| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 -| |-- state -| |-- subsystem -> ../../../class/video_output -| `-- uevent -|-- DVI0 -| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 -| |-- state -| |-- subsystem -> ../../../class/video_output -| `-- uevent -|-- LCD0 -| |-- device -> ../../../devices/pci0000:00/0000:00:01.0 -| |-- state -| |-- subsystem -> ../../../class/video_output -| `-- uevent -`-- TV0 - |-- device -> ../../../devices/pci0000:00/0000:00:01.0 - |-- state - |-- subsystem -> ../../../class/video_output - `-- uevent + linux:/sys/class/video_output # tree . + . + |-- CRT0 + | |-- device -> ../../../devices/pci0000:00/0000:00:01.0 + | |-- state + | |-- subsystem -> ../../../class/video_output + | `-- uevent + |-- DVI0 + | |-- device -> ../../../devices/pci0000:00/0000:00:01.0 + | |-- state + | |-- subsystem -> ../../../class/video_output + | `-- uevent + |-- LCD0 + | |-- device -> ../../../devices/pci0000:00/0000:00:01.0 + | |-- state + | |-- subsystem -> ../../../class/video_output + | `-- uevent + `-- TV0 + |-- device -> ../../../devices/pci0000:00/0000:00:01.0 + |-- state + |-- subsystem -> ../../../class/video_output + `-- uevent diff --git a/Documentation/vm/hmm.rst b/Documentation/vm/hmm.rst index 44205f0b671f..ec1efa32af3c 100644 --- a/Documentation/vm/hmm.rst +++ b/Documentation/vm/hmm.rst @@ -189,20 +189,10 @@ the driver callback returns. When the device driver wants to populate a range of virtual addresses, it can use either:: - int hmm_vma_get_pfns(struct vm_area_struct *vma, - struct hmm_range *range, - unsigned long start, - unsigned long end, - hmm_pfn_t *pfns); - int hmm_vma_fault(struct vm_area_struct *vma, - struct hmm_range *range, - unsigned long start, - unsigned long end, - hmm_pfn_t *pfns, - bool write, - bool block); - -The first one (hmm_vma_get_pfns()) will only fetch present CPU page table + long hmm_range_snapshot(struct hmm_range *range); + long hmm_range_fault(struct hmm_range *range, bool block); + +The first one (hmm_range_snapshot()) will only fetch present CPU page table entries and will not trigger a page fault on missing or non-present entries. The second one does trigger a page fault on missing or read-only entry if the write parameter is true. Page faults use the generic mm page fault code path @@ -220,25 +210,56 @@ respect in order to keep things properly synchronized. The usage pattern is:: { struct hmm_range range; ... + + range.start = ...; + range.end = ...; + range.pfns = ...; + range.flags = ...; + range.values = ...; + range.pfn_shift = ...; + hmm_range_register(&range); + + /* + * Just wait for range to be valid, safe to ignore return value as we + * will use the return value of hmm_range_snapshot() below under the + * mmap_sem to ascertain the validity of the range. + */ + hmm_range_wait_until_valid(&range, TIMEOUT_IN_MSEC); + again: - ret = hmm_vma_get_pfns(vma, &range, start, end, pfns); - if (ret) + down_read(&mm->mmap_sem); + ret = hmm_range_snapshot(&range); + if (ret) { + up_read(&mm->mmap_sem); + if (ret == -EAGAIN) { + /* + * No need to check hmm_range_wait_until_valid() return value + * on retry we will get proper error with hmm_range_snapshot() + */ + hmm_range_wait_until_valid(&range, TIMEOUT_IN_MSEC); + goto again; + } + hmm_mirror_unregister(&range); return ret; + } take_lock(driver->update); - if (!hmm_vma_range_done(vma, &range)) { + if (!range.valid) { release_lock(driver->update); + up_read(&mm->mmap_sem); goto again; } // Use pfns array content to update device page table + hmm_mirror_unregister(&range); release_lock(driver->update); + up_read(&mm->mmap_sem); return 0; } The driver->update lock is the same lock that the driver takes inside its -update() callback. That lock must be held before hmm_vma_range_done() to avoid -any race with a concurrent CPU page table update. +update() callback. That lock must be held before checking the range.valid +field to avoid any race with a concurrent CPU page table update. HMM implements all this on top of the mmu_notifier API because we wanted a simpler API and also to be able to perform optimizations latter on like doing @@ -255,6 +276,41 @@ report commands as executed is serialized (there is no point in doing this concurrently). +Leverage default_flags and pfn_flags_mask +========================================= + +The hmm_range struct has 2 fields default_flags and pfn_flags_mask that allows +to set fault or snapshot policy for a whole range instead of having to set them +for each entries in the range. + +For instance if the device flags for device entries are: + VALID (1 << 63) + WRITE (1 << 62) + +Now let say that device driver wants to fault with at least read a range then +it does set: + range->default_flags = (1 << 63) + range->pfn_flags_mask = 0; + +and calls hmm_range_fault() as described above. This will fill fault all page +in the range with at least read permission. + +Now let say driver wants to do the same except for one page in the range for +which its want to have write. Now driver set: + range->default_flags = (1 << 63); + range->pfn_flags_mask = (1 << 62); + range->pfns[index_of_write] = (1 << 62); + +With this HMM will fault in all page with at least read (ie valid) and for the +address == range->start + (index_of_write << PAGE_SHIFT) it will fault with +write permission ie if the CPU pte does not have write permission set then HMM +will call handle_mm_fault(). + +Note that HMM will populate the pfns array with write permission for any entry +that have write permission within the CPU pte no matter what are the values set +in default_flags or pfn_flags_mask. + + Represent and manage device memory from core kernel point of view ================================================================= diff --git a/Documentation/vm/hugetlbfs_reserv.rst b/Documentation/vm/hugetlbfs_reserv.rst index 9d200762114f..f143954e0d05 100644 --- a/Documentation/vm/hugetlbfs_reserv.rst +++ b/Documentation/vm/hugetlbfs_reserv.rst @@ -85,10 +85,10 @@ 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 +semantics of the reservation map is significantly different for the two types of mappings. Location differences are: -- For private mappings, the reservation map hangs off the the VMA structure. +- For private mappings, the reservation map hangs off 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, @@ -109,15 +109,15 @@ These operations result in a call to the routine hugetlb_reserve_pages():: struct vm_area_struct *vma, vm_flags_t vm_flags) -The first thing hugetlb_reserve_pages() does is check for the NORESERVE +The first thing hugetlb_reserve_pages() does is check if the NORESERVE flag was specified in either the shmget() or mmap() call. If NORESERVE -was specified, then this routine returns immediately as no reservation +was specified, then this routine returns immediately as no reservations 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 +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 @@ -138,7 +138,8 @@ 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 +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 :ref:`Reservation Map Modifications <resv_map_modifications>` for details on how this is accomplished. @@ -165,7 +166,7 @@ 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 +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. @@ -239,7 +240,7 @@ 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 +map. For shared mappings where 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. diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst index b58cc3bfe777..e8d943b21cf9 100644 --- a/Documentation/vm/index.rst +++ b/Documentation/vm/index.rst @@ -37,6 +37,7 @@ descriptions of data structures and algorithms. hwpoison hugetlbfs_reserv ksm + memory-model mmu_notifier numa overcommit-accounting diff --git a/Documentation/vm/memory-model.rst b/Documentation/vm/memory-model.rst new file mode 100644 index 000000000000..382f72ace1fc --- /dev/null +++ b/Documentation/vm/memory-model.rst @@ -0,0 +1,183 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _physical_memory_model: + +===================== +Physical Memory Model +===================== + +Physical memory in a system may be addressed in different ways. The +simplest case is when the physical memory starts at address 0 and +spans a contiguous range up to the maximal address. It could be, +however, that this range contains small holes that are not accessible +for the CPU. Then there could be several contiguous ranges at +completely distinct addresses. And, don't forget about NUMA, where +different memory banks are attached to different CPUs. + +Linux abstracts this diversity using one of the three memory models: +FLATMEM, DISCONTIGMEM and SPARSEMEM. Each architecture defines what +memory models it supports, what the default memory model is and +whether it is possible to manually override that default. + +.. note:: + At time of this writing, DISCONTIGMEM is considered deprecated, + although it is still in use by several architectures. + +All the memory models track the status of physical page frames using +:c:type:`struct page` arranged in one or more arrays. + +Regardless of the selected memory model, there exists one-to-one +mapping between the physical page frame number (PFN) and the +corresponding `struct page`. + +Each memory model defines :c:func:`pfn_to_page` and :c:func:`page_to_pfn` +helpers that allow the conversion from PFN to `struct page` and vice +versa. + +FLATMEM +======= + +The simplest memory model is FLATMEM. This model is suitable for +non-NUMA systems with contiguous, or mostly contiguous, physical +memory. + +In the FLATMEM memory model, there is a global `mem_map` array that +maps the entire physical memory. For most architectures, the holes +have entries in the `mem_map` array. The `struct page` objects +corresponding to the holes are never fully initialized. + +To allocate the `mem_map` array, architecture specific setup code +should call :c:func:`free_area_init_node` function or its convenience +wrapper :c:func:`free_area_init`. Yet, the mappings array is not +usable until the call to :c:func:`memblock_free_all` that hands all +the memory to the page allocator. + +If an architecture enables `CONFIG_ARCH_HAS_HOLES_MEMORYMODEL` option, +it may free parts of the `mem_map` array that do not cover the +actual physical pages. In such case, the architecture specific +:c:func:`pfn_valid` implementation should take the holes in the +`mem_map` into account. + +With FLATMEM, the conversion between a PFN and the `struct page` is +straightforward: `PFN - ARCH_PFN_OFFSET` is an index to the +`mem_map` array. + +The `ARCH_PFN_OFFSET` defines the first page frame number for +systems with physical memory starting at address different from 0. + +DISCONTIGMEM +============ + +The DISCONTIGMEM model treats the physical memory as a collection of +`nodes` similarly to how Linux NUMA support does. For each node Linux +constructs an independent memory management subsystem represented by +`struct pglist_data` (or `pg_data_t` for short). Among other +things, `pg_data_t` holds the `node_mem_map` array that maps +physical pages belonging to that node. The `node_start_pfn` field of +`pg_data_t` is the number of the first page frame belonging to that +node. + +The architecture setup code should call :c:func:`free_area_init_node` for +each node in the system to initialize the `pg_data_t` object and its +`node_mem_map`. + +Every `node_mem_map` behaves exactly as FLATMEM's `mem_map` - +every physical page frame in a node has a `struct page` entry in the +`node_mem_map` array. When DISCONTIGMEM is enabled, a portion of the +`flags` field of the `struct page` encodes the node number of the +node hosting that page. + +The conversion between a PFN and the `struct page` in the +DISCONTIGMEM model became slightly more complex as it has to determine +which node hosts the physical page and which `pg_data_t` object +holds the `struct page`. + +Architectures that support DISCONTIGMEM provide :c:func:`pfn_to_nid` +to convert PFN to the node number. The opposite conversion helper +:c:func:`page_to_nid` is generic as it uses the node number encoded in +page->flags. + +Once the node number is known, the PFN can be used to index +appropriate `node_mem_map` array to access the `struct page` and +the offset of the `struct page` from the `node_mem_map` plus +`node_start_pfn` is the PFN of that page. + +SPARSEMEM +========= + +SPARSEMEM is the most versatile memory model available in Linux and it +is the only memory model that supports several advanced features such +as hot-plug and hot-remove of the physical memory, alternative memory +maps for non-volatile memory devices and deferred initialization of +the memory map for larger systems. + +The SPARSEMEM model presents the physical memory as a collection of +sections. A section is represented with :c:type:`struct mem_section` +that contains `section_mem_map` that is, logically, a pointer to an +array of struct pages. However, it is stored with some other magic +that aids the sections management. The section size and maximal number +of section is specified using `SECTION_SIZE_BITS` and +`MAX_PHYSMEM_BITS` constants defined by each architecture that +supports SPARSEMEM. While `MAX_PHYSMEM_BITS` is an actual width of a +physical address that an architecture supports, the +`SECTION_SIZE_BITS` is an arbitrary value. + +The maximal number of sections is denoted `NR_MEM_SECTIONS` and +defined as + +.. math:: + + NR\_MEM\_SECTIONS = 2 ^ {(MAX\_PHYSMEM\_BITS - SECTION\_SIZE\_BITS)} + +The `mem_section` objects are arranged in a two-dimensional array +called `mem_sections`. The size and placement of this array depend +on `CONFIG_SPARSEMEM_EXTREME` and the maximal possible number of +sections: + +* When `CONFIG_SPARSEMEM_EXTREME` is disabled, the `mem_sections` + array is static and has `NR_MEM_SECTIONS` rows. Each row holds a + single `mem_section` object. +* When `CONFIG_SPARSEMEM_EXTREME` is enabled, the `mem_sections` + array is dynamically allocated. Each row contains PAGE_SIZE worth of + `mem_section` objects and the number of rows is calculated to fit + all the memory sections. + +The architecture setup code should call :c:func:`memory_present` for +each active memory range or use :c:func:`memblocks_present` or +:c:func:`sparse_memory_present_with_active_regions` wrappers to +initialize the memory sections. Next, the actual memory maps should be +set up using :c:func:`sparse_init`. + +With SPARSEMEM there are two possible ways to convert a PFN to the +corresponding `struct page` - a "classic sparse" and "sparse +vmemmap". The selection is made at build time and it is determined by +the value of `CONFIG_SPARSEMEM_VMEMMAP`. + +The classic sparse encodes the section number of a page in page->flags +and uses high bits of a PFN to access the section that maps that page +frame. Inside a section, the PFN is the index to the array of pages. + +The sparse vmemmap uses a virtually mapped memory map to optimize +pfn_to_page and page_to_pfn operations. There is a global `struct +page *vmemmap` pointer that points to a virtually contiguous array of +`struct page` objects. A PFN is an index to that array and the the +offset of the `struct page` from `vmemmap` is the PFN of that +page. + +To use vmemmap, an architecture has to reserve a range of virtual +addresses that will map the physical pages containing the memory +map and make sure that `vmemmap` points to that range. In addition, +the architecture should implement :c:func:`vmemmap_populate` method +that will allocate the physical memory and create page tables for the +virtual memory map. If an architecture does not have any special +requirements for the vmemmap mappings, it can use default +:c:func:`vmemmap_populate_basepages` provided by the generic memory +management. + +The virtually mapped memory map allows storing `struct page` objects +for persistent memory devices in pre-allocated storage on those +devices. This storage is represented with :c:type:`struct vmem_altmap` +that is eventually passed to vmemmap_populate() through a long chain +of function calls. The vmemmap_populate() implementation may use the +`vmem_altmap` along with :c:func:`altmap_alloc_block_buf` helper to +allocate memory map on the persistent memory device. diff --git a/Documentation/vm/numa.rst b/Documentation/vm/numa.rst index 185d8a568168..5cae13e9a08b 100644 --- a/Documentation/vm/numa.rst +++ b/Documentation/vm/numa.rst @@ -109,8 +109,8 @@ System administrators and application designers can restrict a task's migration to improve NUMA locality using various CPU affinity command line interfaces, such as taskset(1) and numactl(1), and program interfaces such as sched_setaffinity(2). Further, one can modify the kernel's default local -allocation behavior using Linux NUMA memory policy. -[see Documentation/admin-guide/mm/numa_memory_policy.rst.] +allocation behavior using Linux NUMA memory policy. [see +:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`]. System administrators can restrict the CPUs and nodes' memories that a non- privileged user can specify in the scheduling or NUMA commands and functions diff --git a/Documentation/vm/transhuge.rst b/Documentation/vm/transhuge.rst index a8cf6809e36e..37c57ca32629 100644 --- a/Documentation/vm/transhuge.rst +++ b/Documentation/vm/transhuge.rst @@ -4,8 +4,9 @@ Transparent Hugepage Support ============================ -This document describes design principles Transparent Hugepage (THP) -Support and its interaction with other parts of the memory management. +This document describes design principles for Transparent Hugepage (THP) +support and its interaction with other parts of the memory management +system. Design principles ================= @@ -37,31 +38,25 @@ get_user_pages and follow_page get_user_pages and follow_page if run on a hugepage, will return the head or tail pages as usual (exactly as they would do on -hugetlbfs). Most gup users will only care about the actual physical +hugetlbfs). Most GUP users will only care about the actual physical address of the page and its temporary pinning to release after the I/O is complete, so they won't ever notice the fact the page is huge. But if any driver is going to mangle over the page structure of the tail page (like for checking page->mapping or other bits that are relevant for the head page and not the tail page), it should be updated to jump -to check head page instead. Taking reference on any head/tail page would -prevent page from being split by anyone. +to check head page instead. Taking a reference on any head/tail page would +prevent the page from being split by anyone. .. note:: these aren't new constraints to the GUP API, and they match the - same constrains that applies to hugetlbfs too, so any driver capable + same constraints that apply to hugetlbfs too, so any driver capable of handling GUP on hugetlbfs will also work fine on transparent hugepage backed mappings. In case you can't handle compound pages if they're returned by -follow_page, the FOLL_SPLIT bit can be specified as parameter to +follow_page, the FOLL_SPLIT bit can be specified as a parameter to follow_page, so that it will split the hugepages before returning -them. Migration for example passes FOLL_SPLIT as parameter to -follow_page because it's not hugepage aware and in fact it can't work -at all on hugetlbfs (but it instead works fine on transparent -hugepages thanks to FOLL_SPLIT). migration simply can't deal with -hugepages being returned (as it's not only checking the pfn of the -page and pinning it during the copy but it pretends to migrate the -memory in regular page sizes and with regular pte/pmd mappings). +them. Graceful fallback ================= @@ -72,11 +67,11 @@ pmd_offset. It's trivial to make the code transparent hugepage aware by just grepping for "pmd_offset" and adding split_huge_pmd where missing after pmd_offset returns the pmd. Thanks to the graceful fallback design, with a one liner change, you can avoid to write -hundred if not thousand of lines of complex code to make your code +hundreds if not thousands of lines of complex code to make your code hugepage aware. If you're not walking pagetables but you run into a physical hugepage -but you can't handle it natively in your code, you can split it by +that you can't handle natively in your code, you can split it by calling split_huge_page(page). This is what the Linux VM does before it tries to swapout the hugepage for example. split_huge_page() can fail if the page is pinned and you must handle this correctly. @@ -103,18 +98,18 @@ split_huge_page() or split_huge_pmd() has a cost. To make pagetable walks huge pmd aware, all you need to do is to call pmd_trans_huge() on the pmd returned by pmd_offset. You must hold the -mmap_sem in read (or write) mode to be sure an huge pmd cannot be +mmap_sem in read (or write) mode to be sure a huge pmd cannot be created from under you by khugepaged (khugepaged collapse_huge_page takes the mmap_sem in write mode in addition to the anon_vma lock). If pmd_trans_huge returns false, you just fallback in the old code paths. If instead pmd_trans_huge returns true, you have to take the page table lock (pmd_lock()) and re-run pmd_trans_huge. Taking the -page table lock will prevent the huge pmd to be converted into a +page table lock will prevent the huge pmd being converted into a regular pmd from under you (split_huge_pmd can run in parallel to the pagetable walk). If the second pmd_trans_huge returns false, you should just drop the page table lock and fallback to the old code as -before. Otherwise you can proceed to process the huge pmd and the -hugepage natively. Once finished you can drop the page table lock. +before. Otherwise, you can proceed to process the huge pmd and the +hugepage natively. Once finished, you can drop the page table lock. Refcounts and transparent huge pages ==================================== @@ -122,61 +117,61 @@ Refcounts and transparent huge pages Refcounting on THP is mostly consistent with refcounting on other compound pages: - - get_page()/put_page() and GUP operate in head page's ->_refcount. + - get_page()/put_page() and GUP operate on head page's ->_refcount. - ->_refcount in tail pages is always zero: get_page_unless_zero() never - succeed on tail pages. + succeeds on tail pages. - map/unmap of the pages with PTE entry increment/decrement ->_mapcount on relevant sub-page of the compound page. - - map/unmap of the whole compound page accounted in compound_mapcount + - map/unmap of the whole compound page is accounted for in compound_mapcount (stored in first tail page). For file huge pages, we also increment ->_mapcount of all sub-pages in order to have race-free detection of last unmap of subpages. PageDoubleMap() indicates that the page is *possibly* mapped with PTEs. -For anonymous pages PageDoubleMap() also indicates ->_mapcount in all +For anonymous pages, PageDoubleMap() also indicates ->_mapcount in all subpages is offset up by one. This additional reference is required to get race-free detection of unmap of subpages when we have them mapped with both PMDs and PTEs. -This is optimization required to lower overhead of per-subpage mapcount -tracking. The alternative is alter ->_mapcount in all subpages on each +This optimization is required to lower the overhead of per-subpage mapcount +tracking. The alternative is to alter ->_mapcount in all subpages on each map/unmap of the whole compound page. -For anonymous pages, we set PG_double_map when a PMD of the page got split -for the first time, but still have PMD mapping. The additional references -go away with last compound_mapcount. +For anonymous pages, we set PG_double_map when a PMD of the page is split +for the first time, but still have a PMD mapping. The additional references +go away with the last compound_mapcount. -File pages get PG_double_map set on first map of the page with PTE and -goes away when the page gets evicted from page cache. +File pages get PG_double_map set on the first map of the page with PTE and +goes away when the page gets evicted from the page cache. split_huge_page internally has to distribute the refcounts in the head page to the tail pages before clearing all PG_head/tail bits from the page structures. It can be done easily for refcounts taken by page table -entries. But we don't have enough information on how to distribute any +entries, but we don't have enough information on how to distribute any additional pins (i.e. from get_user_pages). split_huge_page() fails any -requests to split pinned huge page: it expects page count to be equal to -sum of mapcount of all sub-pages plus one (split_huge_page caller must -have reference for head page). +requests to split pinned huge pages: it expects page count to be equal to +the sum of mapcount of all sub-pages plus one (split_huge_page caller must +have a reference to the head page). split_huge_page uses migration entries to stabilize page->_refcount and -page->_mapcount of anonymous pages. File pages just got unmapped. +page->_mapcount of anonymous pages. File pages just get unmapped. -We safe against physical memory scanners too: the only legitimate way -scanner can get reference to a page is get_page_unless_zero(). +We are safe against physical memory scanners too: the only legitimate way +a scanner can get a 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 know 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 -clear where reference should go after split: it will stay on head page. +clear where references should go after split: it will stay on the head page. -Note that split_huge_pmd() doesn't have any limitation on refcounting: +Note that split_huge_pmd() doesn't have any limitations on refcounting: pmd can be split at any point and never fails. Partial unmap and deferred_split_huge_page() @@ -188,10 +183,10 @@ in page_remove_rmap() and queue the THP for splitting if memory pressure comes. Splitting will free up unused subpages. Splitting the page right away is not an option due to locking context in -the place where we can detect partial unmap. It's also might be +the place where we can detect partial unmap. It also might be 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 function deferred_split_huge_page() is used to queue a page for splitting. The splitting itself will happen when we get memory pressure via shrinker interface. diff --git a/Documentation/x86/amd-memory-encryption.txt b/Documentation/x86/amd-memory-encryption.rst index afc41f544dab..c48d452d0718 100644 --- a/Documentation/x86/amd-memory-encryption.txt +++ b/Documentation/x86/amd-memory-encryption.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +AMD Memory Encryption +===================== + Secure Memory Encryption (SME) and Secure Encrypted Virtualization (SEV) are features found on AMD processors. @@ -34,7 +40,7 @@ is operating in 64-bit or 32-bit PAE mode, in all other modes the SEV hardware forces the memory encryption bit to 1. Support for SME and SEV can be determined through the CPUID instruction. The -CPUID function 0x8000001f reports information related to SME: +CPUID function 0x8000001f reports information related to SME:: 0x8000001f[eax]: Bit[0] indicates support for SME @@ -48,14 +54,14 @@ CPUID function 0x8000001f reports information related to SME: addresses) If support for SME is present, MSR 0xc00100010 (MSR_K8_SYSCFG) can be used to -determine if SME is enabled and/or to enable memory encryption: +determine if SME is enabled and/or to enable memory encryption:: 0xc0010010: Bit[23] 0 = memory encryption features are disabled 1 = memory encryption features are enabled If SEV is supported, MSR 0xc0010131 (MSR_AMD64_SEV) can be used to determine if -SEV is active: +SEV is active:: 0xc0010131: Bit[0] 0 = memory encryption is not active @@ -68,6 +74,7 @@ requirements for the system. If this bit is not set upon Linux startup then Linux itself will not set it and memory encryption will not be possible. The state of SME in the Linux kernel can be documented as follows: + - Supported: The CPU supports SME (determined through CPUID instruction). diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.rst index f4c2a97bfdbd..08a2f100c0e6 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.rst @@ -1,5 +1,8 @@ - THE LINUX/x86 BOOT PROTOCOL - --------------------------- +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +The Linux/x86 Boot Protocol +=========================== On the x86 platform, the Linux kernel uses a rather complicated boot convention. This has evolved partially due to historical aspects, as @@ -10,84 +13,91 @@ real-mode DOS as a mainstream operating system. Currently, the following versions of the Linux/x86 boot protocol exist. -Old kernels: zImage/Image support only. Some very early kernels +============= ============================================================ +Old kernels zImage/Image support only. Some very early kernels may not even support a command line. -Protocol 2.00: (Kernel 1.3.73) Added bzImage and initrd support, as +Protocol 2.00 (Kernel 1.3.73) Added bzImage and initrd support, as well as a formalized way to communicate between the boot loader and the kernel. setup.S made relocatable, although the traditional setup area still assumed writable. -Protocol 2.01: (Kernel 1.3.76) Added a heap overrun warning. +Protocol 2.01 (Kernel 1.3.76) Added a heap overrun warning. -Protocol 2.02: (Kernel 2.4.0-test3-pre3) New command line protocol. +Protocol 2.02 (Kernel 2.4.0-test3-pre3) New command line protocol. Lower the conventional memory ceiling. No overwrite of the traditional setup area, thus making booting safe for systems which use the EBDA from SMM or 32-bit BIOS entry points. zImage deprecated but still supported. -Protocol 2.03: (Kernel 2.4.18-pre1) Explicitly makes the highest possible +Protocol 2.03 (Kernel 2.4.18-pre1) Explicitly makes the highest possible initrd address available to the bootloader. -Protocol 2.04: (Kernel 2.6.14) Extend the syssize field to four bytes. +Protocol 2.04 (Kernel 2.6.14) Extend the syssize field to four bytes. -Protocol 2.05: (Kernel 2.6.20) Make protected mode kernel relocatable. +Protocol 2.05 (Kernel 2.6.20) Make protected mode kernel relocatable. Introduce relocatable_kernel and kernel_alignment fields. -Protocol 2.06: (Kernel 2.6.22) Added a field that contains the size of +Protocol 2.06 (Kernel 2.6.22) Added a field that contains the size of the boot command line. -Protocol 2.07: (Kernel 2.6.24) Added paravirtualised boot protocol. +Protocol 2.07 (Kernel 2.6.24) Added paravirtualised boot protocol. Introduced hardware_subarch and hardware_subarch_data and KEEP_SEGMENTS flag in load_flags. -Protocol 2.08: (Kernel 2.6.26) Added crc32 checksum and ELF format +Protocol 2.08 (Kernel 2.6.26) Added crc32 checksum and ELF format payload. Introduced payload_offset and payload_length fields to aid in locating the payload. -Protocol 2.09: (Kernel 2.6.26) Added a field of 64-bit physical +Protocol 2.09 (Kernel 2.6.26) Added a field of 64-bit physical pointer to single linked list of struct setup_data. -Protocol 2.10: (Kernel 2.6.31) Added a protocol for relaxed alignment +Protocol 2.10 (Kernel 2.6.31) Added a protocol for relaxed alignment beyond the kernel_alignment added, new init_size and pref_address fields. Added extended boot loader IDs. -Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover +Protocol 2.11 (Kernel 3.6) Added a field for offset of EFI handover protocol entry point. -Protocol 2.12: (Kernel 3.8) Added the xloadflags field and extension fields +Protocol 2.12 (Kernel 3.8) Added the xloadflags field and extension fields to struct boot_params for loading bzImage and ramdisk above 4G in 64bit. -**** MEMORY LAYOUT +Protocol 2.13 (Kernel 3.14) Support 32- and 64-bit flags being set in + xloadflags to support booting a 64-bit kernel from 32-bit + EFI +============= ============================================================ -The traditional memory map for the kernel loader, used for Image or -zImage kernels, typically looks like: - - | | -0A0000 +------------------------+ - | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. -09A000 +------------------------+ - | Command line | - | Stack/heap | For use by the kernel real-mode code. -098000 +------------------------+ - | Kernel setup | The kernel real-mode code. -090200 +------------------------+ - | Kernel boot sector | The kernel legacy boot sector. -090000 +------------------------+ - | Protected-mode kernel | The bulk of the kernel image. -010000 +------------------------+ - | Boot loader | <- Boot sector entry point 0000:7C00 -001000 +------------------------+ - | Reserved for MBR/BIOS | -000800 +------------------------+ - | Typically used by MBR | -000600 +------------------------+ - | BIOS use only | -000000 +------------------------+ +Memory Layout +============= + +The traditional memory map for the kernel loader, used for Image or +zImage kernels, typically looks like:: + + | | + 0A0000 +------------------------+ + | Reserved for BIOS | Do not use. Reserved for BIOS EBDA. + 09A000 +------------------------+ + | Command line | + | Stack/heap | For use by the kernel real-mode code. + 098000 +------------------------+ + | Kernel setup | The kernel real-mode code. + 090200 +------------------------+ + | Kernel boot sector | The kernel legacy boot sector. + 090000 +------------------------+ + | Protected-mode kernel | The bulk of the kernel image. + 010000 +------------------------+ + | Boot loader | <- Boot sector entry point 0000:7C00 + 001000 +------------------------+ + | Reserved for MBR/BIOS | + 000800 +------------------------+ + | Typically used by MBR | + 000600 +------------------------+ + | BIOS use only | + 000000 +------------------------+ When using bzImage, the protected-mode kernel was relocated to 0x100000 ("high memory"), and the kernel real-mode block (boot sector, @@ -112,36 +122,36 @@ zImage or old bzImage kernels, which need data written into the above the 0x9A000 point; too many BIOSes will break above that point. For a modern bzImage kernel with boot protocol version >= 2.02, a -memory layout like the following is suggested: - - ~ ~ - | Protected-mode kernel | -100000 +------------------------+ - | I/O memory hole | -0A0000 +------------------------+ - | Reserved for BIOS | Leave as much as possible unused - ~ ~ - | Command line | (Can also be below the X+10000 mark) -X+10000 +------------------------+ - | Stack/heap | For use by the kernel real-mode code. -X+08000 +------------------------+ - | Kernel setup | The kernel real-mode code. - | Kernel boot sector | The kernel legacy boot sector. -X +------------------------+ - | Boot loader | <- Boot sector entry point 0000:7C00 -001000 +------------------------+ - | Reserved for MBR/BIOS | -000800 +------------------------+ - | Typically used by MBR | -000600 +------------------------+ - | BIOS use only | -000000 +------------------------+ - -... where the address X is as low as the design of the boot loader -permits. - - -**** THE REAL-MODE KERNEL HEADER +memory layout like the following is suggested:: + + ~ ~ + | Protected-mode kernel | + 100000 +------------------------+ + | I/O memory hole | + 0A0000 +------------------------+ + | Reserved for BIOS | Leave as much as possible unused + ~ ~ + | Command line | (Can also be below the X+10000 mark) + X+10000 +------------------------+ + | Stack/heap | For use by the kernel real-mode code. + X+08000 +------------------------+ + | Kernel setup | The kernel real-mode code. + | Kernel boot sector | The kernel legacy boot sector. + X +------------------------+ + | Boot loader | <- Boot sector entry point 0000:7C00 + 001000 +------------------------+ + | Reserved for MBR/BIOS | + 000800 +------------------------+ + | Typically used by MBR | + 000600 +------------------------+ + | BIOS use only | + 000000 +------------------------+ + + ... where the address X is as low as the design of the boot loader permits. + + +The Real-Mode Kernel Header +=========================== In the following text, and anywhere in the kernel boot sequence, "a sector" refers to 512 bytes. It is independent of the actual sector @@ -155,61 +165,63 @@ sectors (1K) and then examine the bootup sector size. The header looks like: -Offset Proto Name Meaning -/Size - -01F1/1 ALL(1 setup_sects The size of the setup in sectors -01F2/2 ALL root_flags If set, the root is mounted readonly -01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras -01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only -01FA/2 ALL vid_mode Video mode control -01FC/2 ALL root_dev Default root device number -01FE/2 ALL boot_flag 0xAA55 magic number -0200/2 2.00+ jump Jump instruction -0202/4 2.00+ header Magic signature "HdrS" -0206/2 2.00+ version Boot protocol version supported -0208/4 2.00+ realmode_swtch Boot loader hook (see below) -020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete) -020E/2 2.00+ kernel_version Pointer to kernel version string -0210/1 2.00+ type_of_loader Boot loader identifier -0211/1 2.00+ loadflags Boot protocol option flags -0212/2 2.00+ setup_move_size Move to high memory size (used with hooks) -0214/4 2.00+ code32_start Boot loader hook (see below) -0218/4 2.00+ ramdisk_image initrd load address (set by boot loader) -021C/4 2.00+ ramdisk_size initrd size (set by boot loader) -0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only -0224/2 2.01+ heap_end_ptr Free memory after setup end -0226/1 2.02+(3 ext_loader_ver Extended boot loader version -0227/1 2.02+(3 ext_loader_type Extended boot loader ID -0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line -022C/4 2.03+ initrd_addr_max Highest legal initrd address -0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel -0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not -0235/1 2.10+ min_alignment Minimum alignment, as a power of two -0236/2 2.12+ xloadflags Boot protocol option flags -0238/4 2.06+ cmdline_size Maximum size of the kernel command line -023C/4 2.07+ hardware_subarch Hardware subarchitecture -0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data -0248/4 2.08+ payload_offset Offset of kernel payload -024C/4 2.08+ payload_length Length of kernel payload -0250/8 2.09+ setup_data 64-bit physical pointer to linked list - of struct setup_data -0258/8 2.10+ pref_address Preferred loading address -0260/4 2.10+ init_size Linear memory required during initialization -0264/4 2.11+ handover_offset Offset of handover entry point - -(1) For backwards compatibility, if the setup_sects field contains 0, the - real value is 4. - -(2) For boot protocol prior to 2.04, the upper two bytes of the syssize - field are unusable, which means the size of a bzImage kernel - cannot be determined. - -(3) Ignored, but safe to set, for boot protocols 2.02-2.09. +=========== ======== ===================== ============================================ +Offset/Size Proto Name Meaning +=========== ======== ===================== ============================================ +01F1/1 ALL(1) setup_sects The size of the setup in sectors +01F2/2 ALL root_flags If set, the root is mounted readonly +01F4/4 2.04+(2) syssize The size of the 32-bit code in 16-byte paras +01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only +01FA/2 ALL vid_mode Video mode control +01FC/2 ALL root_dev Default root device number +01FE/2 ALL boot_flag 0xAA55 magic number +0200/2 2.00+ jump Jump instruction +0202/4 2.00+ header Magic signature "HdrS" +0206/2 2.00+ version Boot protocol version supported +0208/4 2.00+ realmode_swtch Boot loader hook (see below) +020C/2 2.00+ start_sys_seg The load-low segment (0x1000) (obsolete) +020E/2 2.00+ kernel_version Pointer to kernel version string +0210/1 2.00+ type_of_loader Boot loader identifier +0211/1 2.00+ loadflags Boot protocol option flags +0212/2 2.00+ setup_move_size Move to high memory size (used with hooks) +0214/4 2.00+ code32_start Boot loader hook (see below) +0218/4 2.00+ ramdisk_image initrd load address (set by boot loader) +021C/4 2.00+ ramdisk_size initrd size (set by boot loader) +0220/4 2.00+ bootsect_kludge DO NOT USE - for bootsect.S use only +0224/2 2.01+ heap_end_ptr Free memory after setup end +0226/1 2.02+(3) ext_loader_ver Extended boot loader version +0227/1 2.02+(3) ext_loader_type Extended boot loader ID +0228/4 2.02+ cmd_line_ptr 32-bit pointer to the kernel command line +022C/4 2.03+ initrd_addr_max Highest legal initrd address +0230/4 2.05+ kernel_alignment Physical addr alignment required for kernel +0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not +0235/1 2.10+ min_alignment Minimum alignment, as a power of two +0236/2 2.12+ xloadflags Boot protocol option flags +0238/4 2.06+ cmdline_size Maximum size of the kernel command line +023C/4 2.07+ hardware_subarch Hardware subarchitecture +0240/8 2.07+ hardware_subarch_data Subarchitecture-specific data +0248/4 2.08+ payload_offset Offset of kernel payload +024C/4 2.08+ payload_length Length of kernel payload +0250/8 2.09+ setup_data 64-bit physical pointer to linked list + of struct setup_data +0258/8 2.10+ pref_address Preferred loading address +0260/4 2.10+ init_size Linear memory required during initialization +0264/4 2.11+ handover_offset Offset of handover entry point +=========== ======== ===================== ============================================ + +.. note:: + (1) For backwards compatibility, if the setup_sects field contains 0, the + real value is 4. + + (2) For boot protocol prior to 2.04, the upper two bytes of the syssize + field are unusable, which means the size of a bzImage kernel + cannot be determined. + + (3) Ignored, but safe to set, for boot protocols 2.02-2.09. If the "HdrS" (0x53726448) magic number is not found at offset 0x202, the boot protocol version is "old". Loading an old kernel, the -following parameters should be assumed: +following parameters should be assumed:: Image type = zImage initrd not supported @@ -221,7 +233,8 @@ setting fields in the header, you must make sure only to set fields supported by the protocol version in use. -**** DETAILS OF HEADER FIELDS +Details of Harder Fileds +======================== For each field, some are information from the kernel to the bootloader ("read"), some are expected to be filled out by the bootloader @@ -235,106 +248,132 @@ boot loaders can ignore those fields. The byte order of all fields is littleendian (this is x86, after all.) +============ =========== Field name: setup_sects Type: read Offset/size: 0x1f1/1 Protocol: ALL +============ =========== The size of the setup code in 512-byte sectors. If this field is 0, the real value is 4. The real-mode code consists of the boot sector (always one 512-byte sector) plus the setup code. -Field name: root_flags -Type: modify (optional) -Offset/size: 0x1f2/2 -Protocol: ALL +============ ================= +Field name: root_flags +Type: modify (optional) +Offset/size: 0x1f2/2 +Protocol: ALL +============ ================= If this field is nonzero, the root defaults to readonly. The use of this field is deprecated; use the "ro" or "rw" options on the command line instead. +============ =============================================== Field name: syssize Type: read Offset/size: 0x1f4/4 (protocol 2.04+) 0x1f4/2 (protocol ALL) Protocol: 2.04+ +============ =============================================== The size of the protected-mode code in units of 16-byte paragraphs. For protocol versions older than 2.04 this field is only two bytes wide, and therefore cannot be trusted for the size of a kernel if the LOAD_HIGH flag is set. +============ =============== Field name: ram_size Type: kernel internal Offset/size: 0x1f8/2 Protocol: ALL +============ =============== This field is obsolete. +============ =================== Field name: vid_mode Type: modify (obligatory) Offset/size: 0x1fa/2 +============ =================== Please see the section on SPECIAL COMMAND LINE OPTIONS. +============ ================= Field name: root_dev Type: modify (optional) Offset/size: 0x1fc/2 Protocol: ALL +============ ================= The default root device device number. The use of this field is deprecated, use the "root=" option on the command line instead. +============ ========= Field name: boot_flag Type: read Offset/size: 0x1fe/2 Protocol: ALL +============ ========= Contains 0xAA55. This is the closest thing old Linux kernels have to a magic number. +============ ======= Field name: jump Type: read Offset/size: 0x200/2 Protocol: 2.00+ +============ ======= Contains an x86 jump instruction, 0xEB followed by a signed offset relative to byte 0x202. This can be used to determine the size of the header. +============ ======= Field name: header Type: read Offset/size: 0x202/4 Protocol: 2.00+ +============ ======= Contains the magic number "HdrS" (0x53726448). +============ ======= Field name: version Type: read Offset/size: 0x206/2 Protocol: 2.00+ +============ ======= Contains the boot protocol version, in (major << 8)+minor format, e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version 10.17. +============ ================= Field name: realmode_swtch Type: modify (optional) Offset/size: 0x208/4 Protocol: 2.00+ +============ ================= Boot loader hook (see ADVANCED BOOT LOADER HOOKS below.) +============ ============= Field name: start_sys_seg Type: read Offset/size: 0x20c/2 Protocol: 2.00+ +============ ============= The load low segment (0x1000). Obsolete. +============ ============== Field name: kernel_version Type: read Offset/size: 0x20e/2 Protocol: 2.00+ +============ ============== If set to a nonzero value, contains a pointer to a NUL-terminated human-readable kernel version number string, less 0x200. This can @@ -344,17 +383,19 @@ Protocol: 2.00+ For example, if this value is set to 0x1c00, the kernel version number string can be found at offset 0x1e00 in the kernel file. This is a valid value if and only if the "setup_sects" field - contains the value 15 or higher, as: + contains the value 15 or higher, as:: 0x1c00 < 15*0x200 (= 0x1e00) but 0x1c00 >= 14*0x200 (= 0x1c00) - 0x1c00 >> 9 = 14, so the minimum value for setup_secs is 15. + 0x1c00 >> 9 = 14, So the minimum value for setup_secs is 15. +============ ================== Field name: type_of_loader Type: write (obligatory) Offset/size: 0x210/1 Protocol: 2.00+ +============ ================== If your boot loader has an assigned id (see table below), enter 0xTV here, where T is an identifier for the boot loader and V is @@ -365,17 +406,20 @@ Protocol: 2.00+ Similarly, the ext_loader_ver field can be used to provide more than four bits for the bootloader version. - For example, for T = 0x15, V = 0x234, write: + For example, for T = 0x15, V = 0x234, write:: - type_of_loader <- 0xE4 - ext_loader_type <- 0x05 - ext_loader_ver <- 0x23 + type_of_loader <- 0xE4 + ext_loader_type <- 0x05 + ext_loader_ver <- 0x23 Assigned boot loader ids (hexadecimal): - 0 LILO (0x00 reserved for pre-2.00 bootloader) + == ======================================= + 0 LILO + (0x00 reserved for pre-2.00 bootloader) 1 Loadlin - 2 bootsect-loader (0x20, all other values reserved) + 2 bootsect-loader + (0x20, all other values reserved) 3 Syslinux 4 Etherboot/gPXE/iPXE 5 ELILO @@ -386,55 +430,70 @@ Protocol: 2.00+ B Qemu C Arcturus Networks uCbootloader D kexec-tools - E Extended (see ext_loader_type) - F Special (0xFF = undefined) - 10 Reserved - 11 Minimal Linux Bootloader <http://sebastian-plotz.blogspot.de> - 12 OVMF UEFI virtualization stack + E Extended (see ext_loader_type) + F Special (0xFF = undefined) + 10 Reserved + 11 Minimal Linux Bootloader + <http://sebastian-plotz.blogspot.de> + 12 OVMF UEFI virtualization stack + == ======================================= - Please contact <hpa@zytor.com> if you need a bootloader ID - value assigned. + Please contact <hpa@zytor.com> if you need a bootloader ID value assigned. +============ =================== Field name: loadflags Type: modify (obligatory) Offset/size: 0x211/1 Protocol: 2.00+ +============ =================== This field is a bitmask. Bit 0 (read): LOADED_HIGH + - If 0, the protected-mode code is loaded at 0x10000. - If 1, the protected-mode code is loaded at 0x100000. Bit 1 (kernel internal): KASLR_FLAG + - Used internally by the compressed kernel to communicate KASLR status to kernel proper. - If 1, KASLR enabled. - If 0, KASLR disabled. + + - If 1, KASLR enabled. + - If 0, KASLR disabled. Bit 5 (write): QUIET_FLAG + - If 0, print early messages. - If 1, suppress early messages. + This requests to the kernel (decompressor and early kernel) to not write early messages that require accessing the display hardware directly. Bit 6 (write): KEEP_SEGMENTS + Protocol: 2.07+ + - If 0, reload the segment registers in the 32bit entry point. - If 1, do not reload the segment registers in the 32bit entry point. + Assume that %cs %ds %ss %es are all set to flat segments with a base of 0 (or the equivalent for their environment). Bit 7 (write): CAN_USE_HEAP + Set this bit to 1 to indicate that the value entered in the heap_end_ptr is valid. If this field is clear, some setup code functionality will be disabled. + +============ =================== Field name: setup_move_size Type: modify (obligatory) Offset/size: 0x212/2 Protocol: 2.00-2.01 +============ =================== When using protocol 2.00 or 2.01, if the real mode kernel is not loaded at 0x90000, it gets moved there later in the loading @@ -443,14 +502,16 @@ Protocol: 2.00-2.01 itself. The unit is bytes starting with the beginning of the boot sector. - + This field is can be ignored when the protocol is 2.02 or higher, or if the real-mode code is loaded at 0x90000. +============ ======================== Field name: code32_start Type: modify (optional, reloc) Offset/size: 0x214/4 Protocol: 2.00+ +============ ======================== The address to jump to in protected mode. This defaults to the load address of the kernel, and can be used by the boot loader to @@ -458,47 +519,57 @@ Protocol: 2.00+ This field can be modified for two purposes: - 1. as a boot loader hook (see ADVANCED BOOT LOADER HOOKS below.) + 1. as a boot loader hook (see Advanced Boot Loader Hooks below.) - 2. if a bootloader which does not install a hook loads a - relocatable kernel at a nonstandard address it will have to modify - this field to point to the load address. + 2. if a bootloader which does not install a hook loads a + relocatable kernel at a nonstandard address it will have to modify + this field to point to the load address. +============ ================== Field name: ramdisk_image Type: write (obligatory) Offset/size: 0x218/4 Protocol: 2.00+ +============ ================== The 32-bit linear address of the initial ramdisk or ramfs. Leave at zero if there is no initial ramdisk/ramfs. +============ ================== Field name: ramdisk_size Type: write (obligatory) Offset/size: 0x21c/4 Protocol: 2.00+ +============ ================== Size of the initial ramdisk or ramfs. Leave at zero if there is no initial ramdisk/ramfs. +============ =============== Field name: bootsect_kludge Type: kernel internal Offset/size: 0x220/4 Protocol: 2.00+ +============ =============== This field is obsolete. +============ ================== Field name: heap_end_ptr Type: write (obligatory) Offset/size: 0x224/2 Protocol: 2.01+ +============ ================== Set this field to the offset (from the beginning of the real-mode code) of the end of the setup stack/heap, minus 0x0200. +============ ================ Field name: ext_loader_ver Type: write (optional) Offset/size: 0x226/1 Protocol: 2.02+ +============ ================ This field is used as an extension of the version number in the type_of_loader field. The total version number is considered to be @@ -510,10 +581,12 @@ Protocol: 2.02+ Kernels prior to 2.6.31 did not recognize this field, but it is safe to write for protocol version 2.02 or higher. +============ ===================================================== Field name: ext_loader_type Type: write (obligatory if (type_of_loader & 0xf0) == 0xe0) Offset/size: 0x227/1 Protocol: 2.02+ +============ ===================================================== This field is used as an extension of the type number in type_of_loader field. If the type in type_of_loader is 0xE, then @@ -524,10 +597,12 @@ Protocol: 2.02+ Kernels prior to 2.6.31 did not recognize this field, but it is safe to write for protocol version 2.02 or higher. +============ ================== Field name: cmd_line_ptr Type: write (obligatory) Offset/size: 0x228/4 Protocol: 2.02+ +============ ================== Set this field to the linear address of the kernel command line. The kernel command line can be located anywhere between the end of @@ -540,10 +615,12 @@ Protocol: 2.02+ zero, the kernel will assume that your boot loader does not support the 2.02+ protocol. +============ =============== Field name: initrd_addr_max Type: read Offset/size: 0x22c/4 Protocol: 2.03+ +============ =============== The maximum address that may be occupied by the initial ramdisk/ramfs contents. For boot protocols 2.02 or earlier, this @@ -552,10 +629,12 @@ Protocol: 2.03+ your ramdisk is exactly 131072 bytes long and this field is 0x37FFFFFF, you can start your ramdisk at 0x37FE0000.) +============ ============================ Field name: kernel_alignment Type: read/modify (reloc) Offset/size: 0x230/4 Protocol: 2.05+ (read), 2.10+ (modify) +============ ============================ Alignment unit required by the kernel (if relocatable_kernel is true.) A relocatable kernel that is loaded at an alignment @@ -567,25 +646,29 @@ Protocol: 2.05+ (read), 2.10+ (modify) loader to modify this field to permit a lesser alignment. See the min_alignment and pref_address field below. +============ ================== Field name: relocatable_kernel Type: read (reloc) Offset/size: 0x234/1 Protocol: 2.05+ +============ ================== If this field is nonzero, the protected-mode part of the kernel can be loaded at any address that satisfies the kernel_alignment field. After loading, the boot loader must set the code32_start field to point to the loaded code, or to a boot loader hook. +============ ============= Field name: min_alignment Type: read (reloc) Offset/size: 0x235/1 Protocol: 2.10+ +============ ============= This field, if nonzero, indicates as a power of two the minimum alignment required, as opposed to preferred, by the kernel to boot. If a boot loader makes use of this field, it should update the - kernel_alignment field with the alignment unit desired; typically: + kernel_alignment field with the alignment unit desired; typically:: kernel_alignment = 1 << min_alignment @@ -593,44 +676,56 @@ Protocol: 2.10+ misaligned kernel. Therefore, a loader should typically try each power-of-two alignment from kernel_alignment down to this alignment. -Field name: xloadflags -Type: read -Offset/size: 0x236/2 -Protocol: 2.12+ +============ ========== +Field name: xloadflags +Type: read +Offset/size: 0x236/2 +Protocol: 2.12+ +============ ========== This field is a bitmask. Bit 0 (read): XLF_KERNEL_64 + - If 1, this kernel has the legacy 64-bit entry point at 0x200. Bit 1 (read): XLF_CAN_BE_LOADED_ABOVE_4G + - If 1, kernel/boot_params/cmdline/ramdisk can be above 4G. Bit 2 (read): XLF_EFI_HANDOVER_32 + - If 1, the kernel supports the 32-bit EFI handoff entry point given at handover_offset. Bit 3 (read): XLF_EFI_HANDOVER_64 + - If 1, the kernel supports the 64-bit EFI handoff entry point given at handover_offset + 0x200. Bit 4 (read): XLF_EFI_KEXEC + - If 1, the kernel supports kexec EFI boot with EFI runtime support. + +============ ============ Field name: cmdline_size Type: read Offset/size: 0x238/4 Protocol: 2.06+ +============ ============ The maximum size of the command line without the terminating zero. This means that the command line can contain at most cmdline_size characters. With protocol version 2.05 and earlier, the maximum size was 255. +============ ==================================== Field name: hardware_subarch Type: write (optional, defaults to x86/PC) Offset/size: 0x23c/4 Protocol: 2.07+ +============ ==================================== In a paravirtualized environment the hardware low level architectural pieces such as interrupt handling, page table handling, and @@ -639,25 +734,31 @@ Protocol: 2.07+ This field allows the bootloader to inform the kernel we are in one one of those environments. + ========== ============================== 0x00000000 The default x86/PC environment 0x00000001 lguest 0x00000002 Xen 0x00000003 Moorestown MID 0x00000004 CE4100 TV Platform + ========== ============================== +============ ========================= Field name: hardware_subarch_data Type: write (subarch-dependent) Offset/size: 0x240/8 Protocol: 2.07+ +============ ========================= A pointer to data that is specific to hardware subarch This field is currently unused for the default x86/PC environment, do not modify. +============ ============== Field name: payload_offset Type: read Offset/size: 0x248/4 Protocol: 2.08+ +============ ============== If non-zero then this field contains the offset from the beginning of the protected-mode code to the payload. @@ -670,29 +771,33 @@ Protocol: 2.08+ 02 21). The uncompressed payload is currently always ELF (magic number 7F 45 4C 46). +============ ============== Field name: payload_length Type: read Offset/size: 0x24c/4 Protocol: 2.08+ +============ ============== The length of the payload. +============ =============== Field name: setup_data Type: write (special) Offset/size: 0x250/8 Protocol: 2.09+ +============ =============== The 64-bit physical pointer to NULL terminated single linked list of struct setup_data. This is used to define a more extensible boot parameters passing mechanism. The definition of struct setup_data is - as follow: + as follow:: - struct setup_data { - u64 next; - u32 type; - u32 len; - u8 data[0]; - }; + struct setup_data { + u64 next; + u32 type; + u32 len; + u8 data[0]; + }; Where, the next is a 64-bit physical pointer to the next node of linked list, the next field of the last node is 0; the type is used @@ -704,10 +809,12 @@ Protocol: 2.09+ sure to consider the case where the linked list already contains entries. +============ ============ Field name: pref_address Type: read (reloc) Offset/size: 0x258/8 Protocol: 2.10+ +============ ============ This field, if nonzero, represents a preferred load address for the kernel. A relocating bootloader should attempt to load at this @@ -716,9 +823,11 @@ Protocol: 2.10+ A non-relocatable kernel will unconditionally move itself and to run at this address. +============ ======= Field name: init_size Type: read Offset/size: 0x260/4 +============ ======= This field indicates the amount of linear contiguous memory starting at the kernel runtime start address that the kernel needs before it @@ -727,16 +836,18 @@ Offset/size: 0x260/4 be used by a relocating boot loader to help select a safe load address for the kernel. - The kernel runtime start address is determined by the following algorithm: + The kernel runtime start address is determined by the following algorithm:: - if (relocatable_kernel) + if (relocatable_kernel) runtime_start = align_up(load_address, kernel_alignment) - else + else runtime_start = pref_address +============ =============== Field name: handover_offset Type: read Offset/size: 0x264/4 +============ =============== This field is the offset from the beginning of the kernel image to the EFI handover protocol entry point. Boot loaders using the EFI @@ -745,7 +856,8 @@ Offset/size: 0x264/4 See EFI HANDOVER PROTOCOL below for more details. -**** THE IMAGE CHECKSUM +The Image Checksum +================== From boot protocol version 2.08 onwards the CRC-32 is calculated over the entire file using the characteristic polynomial 0x04C11DB7 and an @@ -754,7 +866,8 @@ file; therefore the CRC of the file up to the limit specified in the syssize field of the header is always 0. -**** THE KERNEL COMMAND LINE +The Kernel Command Line +======================= The kernel command line has become an important way for the boot loader to communicate with the kernel. Some of its options are also @@ -774,19 +887,20 @@ heap and 0xA0000. If the protocol version is *not* 2.02 or higher, the kernel command line is entered using the following protocol: - At offset 0x0020 (word), "cmd_line_magic", enter the magic - number 0xA33F. + - At offset 0x0020 (word), "cmd_line_magic", enter the magic + number 0xA33F. + + - At offset 0x0022 (word), "cmd_line_offset", enter the offset + of the kernel command line (relative to the start of the + real-mode kernel). - At offset 0x0022 (word), "cmd_line_offset", enter the offset - of the kernel command line (relative to the start of the - real-mode kernel). - - The kernel command line *must* be within the memory region - covered by setup_move_size, so you may need to adjust this - field. + - The kernel command line *must* be within the memory region + covered by setup_move_size, so you may need to adjust this + field. -**** MEMORY LAYOUT OF THE REAL-MODE CODE +Memory Layout of The Real-Mode Code +=================================== The real-mode code requires a stack/heap to be set up, as well as memory allocated for the kernel command line. This needs to be done @@ -802,10 +916,11 @@ segment has to be used: - When loading a zImage kernel ((loadflags & 0x01) == 0). - When loading a 2.01 or earlier boot protocol kernel. - -> For the 2.00 and 2.01 boot protocols, the real-mode code - can be loaded at another address, but it is internally - relocated to 0x90000. For the "old" protocol, the - real-mode code must be loaded at 0x90000. +.. note:: + For the 2.00 and 2.01 boot protocols, the real-mode code + can be loaded at another address, but it is internally + relocated to 0x90000. For the "old" protocol, the + real-mode code must be loaded at 0x90000. When loading at 0x90000, avoid using memory above 0x9a000. @@ -818,24 +933,29 @@ The kernel command line should not be located below the real-mode code, nor should it be located in high memory. -**** SAMPLE BOOT CONFIGURATION +Sample Boot Configuartion +========================= As a sample configuration, assume the following layout of the real -mode segment: +mode segment. When loading below 0x90000, use the entire segment: + ============= =================== 0x0000-0x7fff Real mode kernel 0x8000-0xdfff Stack and heap 0xe000-0xffff Kernel command line + ============= =================== When loading at 0x90000 OR the protocol version is 2.01 or earlier: + ============= =================== 0x0000-0x7fff Real mode kernel 0x8000-0x97ff Stack and heap 0x9800-0x9fff Kernel command line + ============= =================== -Such a boot loader should enter the following fields in the header: +Such a boot loader should enter the following fields in the header:: unsigned long base_ptr; /* base address for real-mode segment */ @@ -894,7 +1014,8 @@ Such a boot loader should enter the following fields in the header: } -**** LOADING THE REST OF THE KERNEL +Loading The Rest of The Kernel +============================== The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512 in the kernel file (again, if setup_sects == 0 the real value is 4.) @@ -902,7 +1023,7 @@ It should be loaded at address 0x10000 for Image/zImage kernels and 0x100000 for bzImage kernels. The kernel is a bzImage kernel if the protocol >= 2.00 and the 0x01 -bit (LOAD_HIGH) in the loadflags field is set: +bit (LOAD_HIGH) in the loadflags field is set:: is_bzImage = (protocol >= 0x0200) && (loadflags & 0x01); load_address = is_bzImage ? 0x100000 : 0x10000; @@ -912,8 +1033,8 @@ the entire 0x10000-0x90000 range of memory. This means it is pretty much a requirement for these kernels to load the real-mode part at 0x90000. bzImage kernels allow much more flexibility. - -**** SPECIAL COMMAND LINE OPTIONS +Special Command Line Options +============================ If the command line provided by the boot loader is entered by the user, the user may expect the following command line options to work. @@ -962,7 +1083,8 @@ or configuration-specified command line. Otherwise, "init=/bin/sh" gets confused by the "auto" option. -**** RUNNING THE KERNEL +Running the Kernel +================== The kernel is started by jumping to the kernel entry point, which is located at *segment* offset 0x20 from the start of the real mode @@ -976,7 +1098,7 @@ interrupts should be disabled. Furthermore, to guard against bugs in the kernel, it is recommended that the boot loader sets fs = gs = ds = es = ss. -In our example from above, we would do: +In our example from above, we would do:: /* Note: in the case of the "old" kernel protocol, base_ptr must be == 0x90000 at this point; see the previous sample code */ @@ -999,7 +1121,8 @@ switched off, especially if the loaded kernel has the floppy driver as a demand-loaded module! -**** ADVANCED BOOT LOADER HOOKS +Advanced Boot Loader Hooks +========================== If the boot loader runs in a particularly hostile environment (such as LOADLIN, which runs under DOS) it may be impossible to follow the @@ -1028,7 +1151,8 @@ IMPORTANT: All the hooks are required to preserve %esp, %ebp, %esi and (relocated, if appropriate.) -**** 32-bit BOOT PROTOCOL +32-bit Boot Protocol +==================== For machine with some new BIOS other than legacy BIOS, such as EFI, LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel @@ -1041,7 +1165,7 @@ traditionally known as "zero page"). The memory for struct boot_params should be allocated and initialized to all zero. Then the setup header from offset 0x01f1 of kernel image on should be loaded into struct boot_params and examined. The end of setup header can be calculated as -follow: +follow:: 0x0202 + byte value at offset 0x0201 @@ -1065,7 +1189,8 @@ must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %esi must hold the base address of the struct boot_params; %ebp, %edi and %ebx must be zero. -**** 64-bit BOOT PROTOCOL +64-bit Boot Protocol +==================== For machine with 64bit cpus and 64bit kernel, we could use 64bit bootloader and we need a 64-bit boot protocol. @@ -1076,7 +1201,7 @@ traditionally known as "zero page"). The memory for struct boot_params could be allocated anywhere (even above 4G) and initialized to all zero. Then, the setup header at offset 0x01f1 of kernel image on should be loaded into struct boot_params and examined. The end of setup header -can be calculated as follows: +can be calculated as follows:: 0x0202 + byte value at offset 0x0201 @@ -1103,7 +1228,8 @@ must have read/write permission; CS must be __BOOT_CS and DS, ES, SS must be __BOOT_DS; interrupt must be disabled; %rsi must hold the base address of the struct boot_params. -**** EFI HANDOVER PROTOCOL +EFI Handover Protocol +===================== This protocol allows boot loaders to defer initialisation to the EFI boot stub. The boot loader is required to load the kernel/initrd(s) @@ -1111,7 +1237,7 @@ from the boot media and jump to the EFI handover protocol entry point which is hdr->handover_offset bytes from the beginning of startup_{32,64}. -The function prototype for the handover entry point looks like this, +The function prototype for the handover entry point looks like this:: efi_main(void *handle, efi_system_table_t *table, struct boot_params *bp) @@ -1120,11 +1246,11 @@ firmware, 'table' is the EFI system table - these are the first two arguments of the "handoff state" as described in section 2.3 of the UEFI specification. 'bp' is the boot loader-allocated boot params. -The boot loader *must* fill out the following fields in bp, +The boot loader *must* fill out the following fields in bp:: - o hdr.code32_start - o hdr.cmd_line_ptr - o hdr.ramdisk_image (if applicable) - o hdr.ramdisk_size (if applicable) + - hdr.code32_start + - hdr.cmd_line_ptr + - hdr.ramdisk_image (if applicable) + - hdr.ramdisk_size (if applicable) All other fields should be zero. diff --git a/Documentation/x86/conf.py b/Documentation/x86/conf.py new file mode 100644 index 000000000000..33c5c3142e20 --- /dev/null +++ b/Documentation/x86/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = "X86 architecture specific documentation" + +tags.add("subproject") + +latex_documents = [ + ('index', 'x86.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/x86/earlyprintk.txt b/Documentation/x86/earlyprintk.rst index 46933e06c972..11307378acf0 100644 --- a/Documentation/x86/earlyprintk.txt +++ b/Documentation/x86/earlyprintk.rst @@ -1,52 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +Early Printk +============ Mini-HOWTO for using the earlyprintk=dbgp boot option with a USB2 Debug port key and a debug cable, on x86 systems. You need two computers, the 'USB debug key' special gadget and -and two USB cables, connected like this: +and two USB cables, connected like this:: [host/target] <-------> [USB debug key] <-------> [client/console] -1. There are a number of specific hardware requirements: - - a.) Host/target system needs to have USB debug port capability. - - You can check this capability by looking at a 'Debug port' bit in - the lspci -vvv output: - - # lspci -vvv - ... - 00:1d.7 USB Controller: Intel Corporation 82801H (ICH8 Family) USB2 EHCI Controller #1 (rev 03) (prog-if 20 [EHCI]) - Subsystem: Lenovo ThinkPad T61 - Control: I/O- Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR+ FastB2B- DisINTx- - Status: Cap+ 66MHz- UDF- FastB2B+ ParErr- DEVSEL=medium >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx- - Latency: 0 - Interrupt: pin D routed to IRQ 19 - Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K] - Capabilities: [50] Power Management version 2 - Flags: PMEClk- DSI- D1- D2- AuxCurrent=375mA PME(D0+,D1-,D2-,D3hot+,D3cold+) - Status: D0 PME-Enable- DSel=0 DScale=0 PME+ - Capabilities: [58] Debug port: BAR=1 offset=00a0 +Hardware requirements +===================== + + a) Host/target system needs to have USB debug port capability. + + You can check this capability by looking at a 'Debug port' bit in + the lspci -vvv output:: + + # lspci -vvv + ... + 00:1d.7 USB Controller: Intel Corporation 82801H (ICH8 Family) USB2 EHCI Controller #1 (rev 03) (prog-if 20 [EHCI]) + Subsystem: Lenovo ThinkPad T61 + Control: I/O- Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR+ FastB2B- DisINTx- + Status: Cap+ 66MHz- UDF- FastB2B+ ParErr- DEVSEL=medium >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx- + Latency: 0 + Interrupt: pin D routed to IRQ 19 + Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K] + Capabilities: [50] Power Management version 2 + Flags: PMEClk- DSI- D1- D2- AuxCurrent=375mA PME(D0+,D1-,D2-,D3hot+,D3cold+) + Status: D0 PME-Enable- DSel=0 DScale=0 PME+ + Capabilities: [58] Debug port: BAR=1 offset=00a0 ^^^^^^^^^^^ <==================== [ HERE ] - Kernel driver in use: ehci_hcd - Kernel modules: ehci-hcd - ... + Kernel driver in use: ehci_hcd + Kernel modules: ehci-hcd + ... -( If your system does not list a debug port capability then you probably - won't be able to use the USB debug key. ) + .. note:: + If your system does not list a debug port capability then you probably + won't be able to use the USB debug key. - b.) You also need a NetChip USB debug cable/key: + b) You also need a NetChip USB debug cable/key: http://www.plxtech.com/products/NET2000/NET20DC/default.asp This is a small blue plastic connector with two USB connections; it draws power from its USB connections. - c.) You need a second client/console system with a high speed USB 2.0 - port. + c) You need a second client/console system with a high speed USB 2.0 port. - d.) The NetChip device must be plugged directly into the physical - debug port on the "host/target" system. You cannot use a USB hub in + d) The NetChip device must be plugged directly into the physical + debug port on the "host/target" system. You cannot use a USB hub in between the physical debug port and the "host/target" system. The EHCI debug controller is bound to a specific physical USB @@ -65,29 +71,31 @@ and two USB cables, connected like this: to the hardware vendor, because there is no reason not to wire this port into one of the physically accessible ports. - e.) It is also important to note, that many versions of the NetChip + e) It is also important to note, that many versions of the NetChip device require the "client/console" system to be plugged into the right hand side of the device (with the product logo facing up and readable left to right). The reason being is that the 5 volt power supply is taken from only one side of the device and it must be the side that does not get rebooted. -2. Software requirements: +Software requirements +===================== - a.) On the host/target system: + a) On the host/target system: - You need to enable the following kernel config option: + You need to enable the following kernel config option:: CONFIG_EARLY_PRINTK_DBGP=y And you need to add the boot command line: "earlyprintk=dbgp". - (If you are using Grub, append it to the 'kernel' line in - /etc/grub.conf. If you are using Grub2 on a BIOS firmware system, - append it to the 'linux' line in /boot/grub2/grub.cfg. If you are - using Grub2 on an EFI firmware system, append it to the 'linux' - or 'linuxefi' line in /boot/grub2/grub.cfg or - /boot/efi/EFI/<distro>/grub.cfg.) + .. note:: + If you are using Grub, append it to the 'kernel' line in + /etc/grub.conf. If you are using Grub2 on a BIOS firmware system, + append it to the 'linux' line in /boot/grub2/grub.cfg. If you are + using Grub2 on an EFI firmware system, append it to the 'linux' + or 'linuxefi' line in /boot/grub2/grub.cfg or + /boot/efi/EFI/<distro>/grub.cfg. On systems with more than one EHCI debug controller you must specify the correct EHCI debug controller number. The ordering @@ -96,14 +104,15 @@ and two USB cables, connected like this: controller. To use the second EHCI debug controller, you would use the command line: "earlyprintk=dbgp1" - NOTE: normally earlyprintk console gets turned off once the - regular console is alive - use "earlyprintk=dbgp,keep" to keep - this channel open beyond early bootup. This can be useful for - debugging crashes under Xorg, etc. + .. note:: + normally earlyprintk console gets turned off once the + regular console is alive - use "earlyprintk=dbgp,keep" to keep + this channel open beyond early bootup. This can be useful for + debugging crashes under Xorg, etc. - b.) On the client/console system: + b) On the client/console system: - You should enable the following kernel config option: + You should enable the following kernel config option:: CONFIG_USB_SERIAL_DEBUG=y @@ -115,27 +124,28 @@ and two USB cables, connected like this: it up to use /dev/ttyUSB0 - or use a raw 'cat /dev/ttyUSBx' to see the raw output. - c.) On Nvidia Southbridge based systems: the kernel will try to probe + c) On Nvidia Southbridge based systems: the kernel will try to probe and find out which port has a debug device connected. -3. Testing that it works fine: +Testing +======= - You can test the output by using earlyprintk=dbgp,keep and provoking - kernel messages on the host/target system. You can provoke a harmless - kernel message by for example doing: +You can test the output by using earlyprintk=dbgp,keep and provoking +kernel messages on the host/target system. You can provoke a harmless +kernel message by for example doing:: echo h > /proc/sysrq-trigger - On the host/target system you should see this help line in "dmesg" output: +On the host/target system you should see this help line in "dmesg" output:: SysRq : HELP : loglevel(0-9) reBoot Crashdump terminate-all-tasks(E) memory-full-oom-kill(F) kill-all-tasks(I) saK show-backtrace-all-active-cpus(L) show-memory-usage(M) nice-all-RT-tasks(N) powerOff show-registers(P) show-all-timers(Q) unRaw Sync show-task-states(T) Unmount show-blocked-tasks(W) dump-ftrace-buffer(Z) - On the client/console system do: +On the client/console system do:: cat /dev/ttyUSB0 - And you should see the help line above displayed shortly after you've - provoked it on the host system. +And you should see the help line above displayed shortly after you've +provoked it on the host system. If it does not work then please ask about it on the linux-kernel@vger.kernel.org mailing list or contact the x86 maintainers. diff --git a/Documentation/x86/entry_64.txt b/Documentation/x86/entry_64.rst index c1df8eba9dfd..a48b3f6ebbe8 100644 --- a/Documentation/x86/entry_64.txt +++ b/Documentation/x86/entry_64.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +Kernel Entries +============== + This file documents some of the kernel entries in arch/x86/entry/entry_64.S. A lot of this explanation is adapted from an email from Ingo Molnar: @@ -59,7 +65,7 @@ Now, there's a secondary complication: there's a cheap way to test which mode the CPU is in and an expensive way. The cheap way is to pick this info off the entry frame on the kernel -stack, from the CS of the ptregs area of the kernel stack: +stack, from the CS of the ptregs area of the kernel stack:: xorl %ebx,%ebx testl $3,CS+8(%rsp) @@ -67,7 +73,7 @@ stack, from the CS of the ptregs area of the kernel stack: SWAPGS The expensive (paranoid) way is to read back the MSR_GS_BASE value -(which is what SWAPGS modifies): +(which is what SWAPGS modifies):: movl $1,%ebx movl $MSR_GS_BASE,%ecx @@ -76,7 +82,7 @@ The expensive (paranoid) way is to read back the MSR_GS_BASE value js 1f /* negative -> in kernel */ SWAPGS xorl %ebx,%ebx -1: ret + 1: ret If we are at an interrupt or user-trap/gate-alike boundary then we can use the faster check: the stack will be a reliable indicator of diff --git a/Documentation/x86/exception-tables.txt b/Documentation/x86/exception-tables.rst index e396bcd8d830..24596c8210b5 100644 --- a/Documentation/x86/exception-tables.txt +++ b/Documentation/x86/exception-tables.rst @@ -1,5 +1,10 @@ - Kernel level exception handling in Linux - Commentary by Joerg Pommnitz <joerg@raleigh.ibm.com> +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +Kernel level exception handling +=============================== + +Commentary by Joerg Pommnitz <joerg@raleigh.ibm.com> When a process runs in kernel mode, it often has to access user mode memory whose address has been passed by an untrusted program. @@ -25,9 +30,9 @@ How does this work? Whenever the kernel tries to access an address that is currently not accessible, the CPU generates a page fault exception and calls the -page fault handler +page fault handler:: -void do_page_fault(struct pt_regs *regs, unsigned long error_code) + void do_page_fault(struct pt_regs *regs, unsigned long error_code) in arch/x86/mm/fault.c. The parameters on the stack are set up by the low level assembly glue in arch/x86/kernel/entry_32.S. The parameter @@ -57,73 +62,74 @@ as an example. The definition is somewhat hard to follow, so let's peek at the code generated by the preprocessor and the compiler. I selected the get_user call in drivers/char/sysrq.c for a detailed examination. -The original code in sysrq.c line 587: +The original code in sysrq.c line 587:: + get_user(c, buf); -The preprocessor output (edited to become somewhat readable): - -( - { - long __gu_err = - 14 , __gu_val = 0; - const __typeof__(*( ( buf ) )) *__gu_addr = ((buf)); - if (((((0 + current_set[0])->tss.segment) == 0x18 ) || - (((sizeof(*(buf))) <= 0xC0000000UL) && - ((unsigned long)(__gu_addr ) <= 0xC0000000UL - (sizeof(*(buf))))))) - do { - __gu_err = 0; - switch ((sizeof(*(buf)))) { - case 1: - __asm__ __volatile__( - "1: mov" "b" " %2,%" "b" "1\n" - "2:\n" - ".section .fixup,\"ax\"\n" - "3: movl %3,%0\n" - " xor" "b" " %" "b" "1,%" "b" "1\n" - " jmp 2b\n" - ".section __ex_table,\"a\"\n" - " .align 4\n" - " .long 1b,3b\n" - ".text" : "=r"(__gu_err), "=q" (__gu_val): "m"((*(struct __large_struct *) - ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )) ; - break; - case 2: - __asm__ __volatile__( - "1: mov" "w" " %2,%" "w" "1\n" - "2:\n" - ".section .fixup,\"ax\"\n" - "3: movl %3,%0\n" - " xor" "w" " %" "w" "1,%" "w" "1\n" - " jmp 2b\n" - ".section __ex_table,\"a\"\n" - " .align 4\n" - " .long 1b,3b\n" - ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) - ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )); - break; - case 4: - __asm__ __volatile__( - "1: mov" "l" " %2,%" "" "1\n" - "2:\n" - ".section .fixup,\"ax\"\n" - "3: movl %3,%0\n" - " xor" "l" " %" "" "1,%" "" "1\n" - " jmp 2b\n" - ".section __ex_table,\"a\"\n" - " .align 4\n" " .long 1b,3b\n" - ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) - ( __gu_addr )) ), "i"(- 14 ), "0"(__gu_err)); - break; - default: - (__gu_val) = __get_user_bad(); - } - } while (0) ; - ((c)) = (__typeof__(*((buf))))__gu_val; - __gu_err; - } -); +The preprocessor output (edited to become somewhat readable):: + + ( + { + long __gu_err = - 14 , __gu_val = 0; + const __typeof__(*( ( buf ) )) *__gu_addr = ((buf)); + if (((((0 + current_set[0])->tss.segment) == 0x18 ) || + (((sizeof(*(buf))) <= 0xC0000000UL) && + ((unsigned long)(__gu_addr ) <= 0xC0000000UL - (sizeof(*(buf))))))) + do { + __gu_err = 0; + switch ((sizeof(*(buf)))) { + case 1: + __asm__ __volatile__( + "1: mov" "b" " %2,%" "b" "1\n" + "2:\n" + ".section .fixup,\"ax\"\n" + "3: movl %3,%0\n" + " xor" "b" " %" "b" "1,%" "b" "1\n" + " jmp 2b\n" + ".section __ex_table,\"a\"\n" + " .align 4\n" + " .long 1b,3b\n" + ".text" : "=r"(__gu_err), "=q" (__gu_val): "m"((*(struct __large_struct *) + ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )) ; + break; + case 2: + __asm__ __volatile__( + "1: mov" "w" " %2,%" "w" "1\n" + "2:\n" + ".section .fixup,\"ax\"\n" + "3: movl %3,%0\n" + " xor" "w" " %" "w" "1,%" "w" "1\n" + " jmp 2b\n" + ".section __ex_table,\"a\"\n" + " .align 4\n" + " .long 1b,3b\n" + ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) + ( __gu_addr )) ), "i"(- 14 ), "0"( __gu_err )); + break; + case 4: + __asm__ __volatile__( + "1: mov" "l" " %2,%" "" "1\n" + "2:\n" + ".section .fixup,\"ax\"\n" + "3: movl %3,%0\n" + " xor" "l" " %" "" "1,%" "" "1\n" + " jmp 2b\n" + ".section __ex_table,\"a\"\n" + " .align 4\n" " .long 1b,3b\n" + ".text" : "=r"(__gu_err), "=r" (__gu_val) : "m"((*(struct __large_struct *) + ( __gu_addr )) ), "i"(- 14 ), "0"(__gu_err)); + break; + default: + (__gu_val) = __get_user_bad(); + } + } while (0) ; + ((c)) = (__typeof__(*((buf))))__gu_val; + __gu_err; + } + ); WOW! Black GCC/assembly magic. This is impossible to follow, so let's -see what code gcc generates: +see what code gcc generates:: > xorl %edx,%edx > movl current_set,%eax @@ -154,7 +160,7 @@ understand. Can we? The actual user access is quite obvious. Thanks to the unified address space we can just access the address in user memory. But what does the .section stuff do????? -To understand this we have to look at the final kernel: +To understand this we have to look at the final kernel:: > objdump --section-headers vmlinux > @@ -181,7 +187,7 @@ To understand this we have to look at the final kernel: There are obviously 2 non standard ELF sections in the generated object file. But first we want to find out what happened to our code in the -final kernel executable: +final kernel executable:: > objdump --disassemble --section=.text vmlinux > @@ -199,7 +205,7 @@ final kernel executable: The whole user memory access is reduced to 10 x86 machine instructions. The instructions bracketed in the .section directives are no longer in the normal execution path. They are located in a different section -of the executable file: +of the executable file:: > objdump --disassemble --section=.fixup vmlinux > @@ -207,14 +213,15 @@ of the executable file: > c0199ffa <.fixup+10ba> xorb %dl,%dl > c0199ffc <.fixup+10bc> jmp c017e7a7 <do_con_write+e3> -And finally: +And finally:: + > objdump --full-contents --section=__ex_table vmlinux > > c01aa7c4 93c017c0 e09f19c0 97c017c0 99c017c0 ................ > c01aa7d4 f6c217c0 e99f19c0 a5e717c0 f59f19c0 ................ > c01aa7e4 080a18c0 01a019c0 0a0a18c0 04a019c0 ................ -or in human readable byte order: +or in human readable byte order:: > c01aa7c4 c017c093 c0199fe0 c017c097 c017c099 ................ > c01aa7d4 c017c2f6 c0199fe9 c017e7a5 c0199ff5 ................ @@ -222,18 +229,22 @@ or in human readable byte order: this is the interesting part! > c01aa7e4 c0180a08 c019a001 c0180a0a c019a004 ................ -What happened? The assembly directives +What happened? The assembly directives:: -.section .fixup,"ax" -.section __ex_table,"a" + .section .fixup,"ax" + .section __ex_table,"a" told the assembler to move the following code to the specified -sections in the ELF object file. So the instructions -3: movl $-14,%eax - xorb %dl,%dl - jmp 2b -ended up in the .fixup section of the object file and the addresses +sections in the ELF object file. So the instructions:: + + 3: movl $-14,%eax + xorb %dl,%dl + jmp 2b + +ended up in the .fixup section of the object file and the addresses:: + .long 1b,3b + ended up in the __ex_table section of the object file. 1b and 3b are local labels. The local label 1b (1b stands for next label 1 backward) is the address of the instruction that might fault, i.e. @@ -246,35 +257,39 @@ the fault, in our case the actual value is c0199ff5: the original assembly code: > 3: movl $-14,%eax and linked in vmlinux : > c0199ff5 <.fixup+10b5> movl $0xfffffff2,%eax -The assembly code +The assembly code:: + > .section __ex_table,"a" > .align 4 > .long 1b,3b -becomes the value pair +becomes the value pair:: + > c01aa7d4 c017c2f6 c0199fe9 c017e7a5 c0199ff5 ................ ^this is ^this is 1b 3b + c017e7a5,c0199ff5 in the exception table of the kernel. So, what actually happens if a fault from kernel mode with no suitable vma occurs? -1.) access to invalid address: - > c017e7a5 <do_con_write+e1> movb (%ebx),%dl -2.) MMU generates exception -3.) CPU calls do_page_fault -4.) do page fault calls search_exception_table (regs->eip == c017e7a5); -5.) search_exception_table looks up the address c017e7a5 in the - exception table (i.e. the contents of the ELF section __ex_table) - and returns the address of the associated fault handle code c0199ff5. -6.) do_page_fault modifies its own return address to point to the fault - handle code and returns. -7.) execution continues in the fault handling code. -8.) 8a) EAX becomes -EFAULT (== -14) - 8b) DL becomes zero (the value we "read" from user space) - 8c) execution continues at local label 2 (address of the - instruction immediately after the faulting user access). +#. access to invalid address:: + + > c017e7a5 <do_con_write+e1> movb (%ebx),%dl +#. MMU generates exception +#. CPU calls do_page_fault +#. do page fault calls search_exception_table (regs->eip == c017e7a5); +#. search_exception_table looks up the address c017e7a5 in the + exception table (i.e. the contents of the ELF section __ex_table) + and returns the address of the associated fault handle code c0199ff5. +#. do_page_fault modifies its own return address to point to the fault + handle code and returns. +#. execution continues in the fault handling code. +#. a) EAX becomes -EFAULT (== -14) + b) DL becomes zero (the value we "read" from user space) + c) execution continues at local label 2 (address of the + instruction immediately after the faulting user access). The steps 8a to 8c in a certain way emulate the faulting instruction. @@ -295,14 +310,15 @@ Things changed when 64-bit support was added to x86 Linux. Rather than double the size of the exception table by expanding the two entries from 32-bits to 64 bits, a clever trick was used to store addresses as relative offsets from the table itself. The assembly code changed -from: - .long 1b,3b -to: - .long (from) - . - .long (to) - . +from:: + + .long 1b,3b + to: + .long (from) - . + .long (to) - . and the C-code that uses these values converts back to absolute addresses -like this: +like this:: ex_insn_addr(const struct exception_table_entry *x) { @@ -313,15 +329,18 @@ In v4.6 the exception table entry was expanded with a new field "handler". This is also 32-bits wide and contains a third relative function pointer which points to one of: -1) int ex_handler_default(const struct exception_table_entry *fixup) - This is legacy case that just jumps to the fixup code -2) int ex_handler_fault(const struct exception_table_entry *fixup) - This case provides the fault number of the trap that occurred at - entry->insn. It is used to distinguish page faults from machine - check. -3) int ex_handler_ext(const struct exception_table_entry *fixup) - This case is used for uaccess_err ... we need to set a flag - in the task structure. Before the handler functions existed this - case was handled by adding a large offset to the fixup to tag - it as special. +1) ``int ex_handler_default(const struct exception_table_entry *fixup)`` + This is legacy case that just jumps to the fixup code + +2) ``int ex_handler_fault(const struct exception_table_entry *fixup)`` + This case provides the fault number of the trap that occurred at + entry->insn. It is used to distinguish page faults from machine + check. + +3) ``int ex_handler_ext(const struct exception_table_entry *fixup)`` + This case is used for uaccess_err ... we need to set a flag + in the task structure. Before the handler functions existed this + case was handled by adding a large offset to the fixup to tag + it as special. + More functions can easily be added. diff --git a/Documentation/x86/i386/IO-APIC.txt b/Documentation/x86/i386/IO-APIC.rst index 15f5baf7e1b6..ce4d8df15e7c 100644 --- a/Documentation/x86/i386/IO-APIC.txt +++ b/Documentation/x86/i386/IO-APIC.rst @@ -1,3 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +IO-APIC +======= + +:Author: Ingo Molnar <mingo@kernel.org> + Most (all) Intel-MP compliant SMP boards have the so-called 'IO-APIC', which is an enhanced interrupt controller. It enables us to route hardware interrupts to multiple CPUs, or to CPU groups. Without an @@ -13,9 +21,8 @@ usually worked around by the kernel. If your MP-compliant SMP board does not boot Linux, then consult the linux-smp mailing list archives first. If your box boots fine with enabled IO-APIC IRQs, then your -/proc/interrupts will look like this one: +/proc/interrupts will look like this one:: - ----------------------------> hell:~> cat /proc/interrupts CPU0 0: 1360293 IO-APIC-edge timer @@ -28,7 +35,6 @@ If your box boots fine with enabled IO-APIC IRQs, then your NMI: 0 ERR: 0 hell:~> - <---------------------------- Some interrupts are still listed as 'XT PIC', but this is not a problem; none of those IRQ sources is performance-critical. @@ -37,14 +43,14 @@ none of those IRQ sources is performance-critical. In the unlikely case that your board does not create a working mp-table, you can use the pirq= boot parameter to 'hand-construct' IRQ entries. This is non-trivial though and cannot be automated. One sample /etc/lilo.conf -entry: +entry:: append="pirq=15,11,10" The actual numbers depend on your system, on your PCI cards and on their PCI slot position. Usually PCI slots are 'daisy chained' before they are connected to the PCI chipset IRQ routing facility (the incoming PIRQ1-4 -lines): +lines):: ,-. ,-. ,-. ,-. ,-. PIRQ4 ----| |-. ,-| |-. ,-| |-. ,-| |--------| | @@ -56,7 +62,7 @@ lines): PIRQ1 ----| |- `----| |- `----| |- `----| |--------| | `-' `-' `-' `-' `-' -Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD: +Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD:: ,-. INTD--| | @@ -78,19 +84,19 @@ to have non shared interrupts). Slot5 should be used for videocards, they do not use interrupts normally, thus they are not daisy chained either. so if you have your SCSI card (IRQ11) in Slot1, Tulip card (IRQ9) in -Slot2, then you'll have to specify this pirq= line: +Slot2, then you'll have to specify this pirq= line:: append="pirq=11,9" the following script tries to figure out such a default pirq= line from -your PCI configuration: +your PCI configuration:: echo -n pirq=; echo `scanpci | grep T_L | cut -c56-` | sed 's/ /,/g' note that this script won't work if you have skipped a few slots or if your board does not do default daisy-chaining. (or the IO-APIC has the PIRQ pins connected in some strange way). E.g. if in the above case you have your SCSI -card (IRQ11) in Slot3, and have Slot1 empty: +card (IRQ11) in Slot3, and have Slot1 empty:: append="pirq=0,9,11" @@ -105,7 +111,7 @@ won't function properly (e.g. if it's inserted as a module). If you have 2 PCI buses, then you can use up to 8 pirq values, although such boards tend to have a good configuration. -Be prepared that it might happen that you need some strange pirq line: +Be prepared that it might happen that you need some strange pirq line:: append="pirq=0,0,0,0,0,0,9,11" @@ -115,5 +121,3 @@ Good luck and mail to linux-smp@vger.kernel.org or linux-kernel@vger.kernel.org if you have any problems that are not covered by this document. --- mingo - diff --git a/Documentation/x86/i386/index.rst b/Documentation/x86/i386/index.rst new file mode 100644 index 000000000000..8747cf5bbd49 --- /dev/null +++ b/Documentation/x86/i386/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +i386 Support +============ + +.. toctree:: + :maxdepth: 2 + + IO-APIC diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst new file mode 100644 index 000000000000..ae36fc5fc649 --- /dev/null +++ b/Documentation/x86/index.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +x86-specific Documentation +========================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + boot + topology + exception-tables + kernel-stacks + entry_64 + earlyprintk + orc-unwinder + zero-page + tlb + mtrr + pat + protection-keys + intel_mpx + amd-memory-encryption + pti + mds + microcode + resctrl_ui + usb-legacy-support + i386/index + x86_64/index diff --git a/Documentation/x86/intel_mpx.txt b/Documentation/x86/intel_mpx.rst index 85d0549ad846..387a640941a6 100644 --- a/Documentation/x86/intel_mpx.txt +++ b/Documentation/x86/intel_mpx.rst @@ -1,5 +1,11 @@ -1. Intel(R) MPX Overview -======================== +.. SPDX-License-Identifier: GPL-2.0 + +=========================================== +Intel(R) Memory Protection Extensions (MPX) +=========================================== + +Intel(R) MPX Overview +===================== Intel(R) Memory Protection Extensions (Intel(R) MPX) is a new capability introduced into Intel Architecture. Intel MPX provides hardware features @@ -7,7 +13,7 @@ that can be used in conjunction with compiler changes to check memory references, for those references whose compile-time normal intentions are usurped at runtime due to buffer overflow or underflow. -You can tell if your CPU supports MPX by looking in /proc/cpuinfo: +You can tell if your CPU supports MPX by looking in /proc/cpuinfo:: cat /proc/cpuinfo | grep ' mpx ' @@ -21,8 +27,8 @@ can be downloaded from http://software.intel.com/en-us/articles/intel-software-development-emulator -2. How to get the advantage of MPX -================================== +How to get the advantage of MPX +=============================== For MPX to work, changes are required in the kernel, binutils and compiler. No source changes are required for applications, just a recompile. @@ -84,14 +90,15 @@ Kernel MPX Code: is unmapped. -3. How does MPX kernel code work -================================ +How does MPX kernel code work +============================= Handling #BR faults caused by MPX --------------------------------- When MPX is enabled, there are 2 new situations that can generate #BR faults. + * new bounds tables (BT) need to be allocated to save bounds. * bounds violation caused by MPX instructions. @@ -124,37 +131,37 @@ the kernel. It can theoretically be done completely from userspace. Here are a few ways this could be done. We don't think any of them are practical in the real-world, but here they are. -Q: Can virtual space simply be reserved for the bounds tables so that we - never have to allocate them? -A: MPX-enabled application will possibly create a lot of bounds tables in - process address space to save bounds information. These tables can take - up huge swaths of memory (as much as 80% of the memory on the system) - even if we clean them up aggressively. In the worst-case scenario, the - tables can be 4x the size of the data structure being tracked. IOW, a - 1-page structure can require 4 bounds-table pages. An X-GB virtual - area needs 4*X GB of virtual space, plus 2GB for the bounds directory. - If we were to preallocate them for the 128TB of user virtual address - space, we would need to reserve 512TB+2GB, which is larger than the - entire virtual address space today. This means they can not be reserved - ahead of time. Also, a single process's pre-populated bounds directory - consumes 2GB of virtual *AND* physical memory. IOW, it's completely - infeasible to prepopulate bounds directories. - -Q: Can we preallocate bounds table space at the same time memory is - allocated which might contain pointers that might eventually need - bounds tables? -A: This would work if we could hook the site of each and every memory - allocation syscall. This can be done for small, constrained applications. - But, it isn't practical at a larger scale since a given app has no - way of controlling how all the parts of the app might allocate memory - (think libraries). The kernel is really the only place to intercept - these calls. - -Q: Could a bounds fault be handed to userspace and the tables allocated - there in a signal handler instead of in the kernel? -A: mmap() is not on the list of safe async handler functions and even - if mmap() would work it still requires locking or nasty tricks to - keep track of the allocation state there. +:Q: Can virtual space simply be reserved for the bounds tables so that we + never have to allocate them? +:A: MPX-enabled application will possibly create a lot of bounds tables in + process address space to save bounds information. These tables can take + up huge swaths of memory (as much as 80% of the memory on the system) + even if we clean them up aggressively. In the worst-case scenario, the + tables can be 4x the size of the data structure being tracked. IOW, a + 1-page structure can require 4 bounds-table pages. An X-GB virtual + area needs 4*X GB of virtual space, plus 2GB for the bounds directory. + If we were to preallocate them for the 128TB of user virtual address + space, we would need to reserve 512TB+2GB, which is larger than the + entire virtual address space today. This means they can not be reserved + ahead of time. Also, a single process's pre-populated bounds directory + consumes 2GB of virtual *AND* physical memory. IOW, it's completely + infeasible to prepopulate bounds directories. + +:Q: Can we preallocate bounds table space at the same time memory is + allocated which might contain pointers that might eventually need + bounds tables? +:A: This would work if we could hook the site of each and every memory + allocation syscall. This can be done for small, constrained applications. + But, it isn't practical at a larger scale since a given app has no + way of controlling how all the parts of the app might allocate memory + (think libraries). The kernel is really the only place to intercept + these calls. + +:Q: Could a bounds fault be handed to userspace and the tables allocated + there in a signal handler instead of in the kernel? +:A: mmap() is not on the list of safe async handler functions and even + if mmap() would work it still requires locking or nasty tricks to + keep track of the allocation state there. Having ruled out all of the userspace-only approaches for managing bounds tables that we could think of, we create them on demand in @@ -167,20 +174,20 @@ If a #BR is generated due to a bounds violation caused by MPX. We need to decode MPX instructions to get violation address and set this address into extended struct siginfo. -The _sigfault field of struct siginfo is extended as follow: - -87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */ -88 struct { -89 void __user *_addr; /* faulting insn/memory ref. */ -90 #ifdef __ARCH_SI_TRAPNO -91 int _trapno; /* TRAP # which caused the signal */ -92 #endif -93 short _addr_lsb; /* LSB of the reported address */ -94 struct { -95 void __user *_lower; -96 void __user *_upper; -97 } _addr_bnd; -98 } _sigfault; +The _sigfault field of struct siginfo is extended as follow:: + + 87 /* SIGILL, SIGFPE, SIGSEGV, SIGBUS */ + 88 struct { + 89 void __user *_addr; /* faulting insn/memory ref. */ + 90 #ifdef __ARCH_SI_TRAPNO + 91 int _trapno; /* TRAP # which caused the signal */ + 92 #endif + 93 short _addr_lsb; /* LSB of the reported address */ + 94 struct { + 95 void __user *_lower; + 96 void __user *_upper; + 97 } _addr_bnd; + 98 } _sigfault; The '_addr' field refers to violation address, and new '_addr_and' field refers to the upper/lower bounds when a #BR is caused. @@ -209,9 +216,10 @@ Adding new prctl commands Two new prctl commands are added to enable and disable MPX bounds tables management in kernel. +:: -155 #define PR_MPX_ENABLE_MANAGEMENT 43 -156 #define PR_MPX_DISABLE_MANAGEMENT 44 + 155 #define PR_MPX_ENABLE_MANAGEMENT 43 + 156 #define PR_MPX_DISABLE_MANAGEMENT 44 Runtime library in userspace is responsible for allocation of bounds directory. So kernel have to use XSAVE instruction to get the base @@ -223,8 +231,8 @@ into struct mm_struct to be used in future during PR_MPX_ENABLE_MANAGEMENT command execution. -4. Special rules -================ +Special rules +============= 1) If userspace is requesting help from the kernel to do the management of bounds tables, it may not create or modify entries in the bounds directory. diff --git a/Documentation/x86/kernel-stacks b/Documentation/x86/kernel-stacks.rst index d1bfb0b95ee0..6b0bcf027ff1 100644 --- a/Documentation/x86/kernel-stacks +++ b/Documentation/x86/kernel-stacks.rst @@ -1,5 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +Kernel Stacks +============= + Kernel stacks on x86-64 bit ---------------------------- +=========================== Most of the text from Keith Owens, hacked by AK @@ -57,7 +63,7 @@ IST events with the same code to be nested. However in most cases, the stack size allocated to an IST assumes no nesting for the same code. If that assumption is ever broken then the stacks will become corrupt. -The currently assigned IST stacks are :- +The currently assigned IST stacks are: * ESTACK_DF. EXCEPTION_STKSZ (PAGE_SIZE). @@ -103,7 +109,7 @@ For more details see the Intel IA32 or AMD AMD64 architecture manuals. Printing backtraces on x86 --------------------------- +========================== The question about the '?' preceding function names in an x86 stacktrace keeps popping up, here's an indepth explanation. It helps if the reader @@ -113,7 +119,7 @@ arch/x86/kernel/dumpstack.c. Adapted from Ingo's mail, Message-ID: <20150521101614.GA10889@gmail.com>: We always scan the full kernel stack for return addresses stored on -the kernel stack(s) [*], from stack top to stack bottom, and print out +the kernel stack(s) [1]_, from stack top to stack bottom, and print out anything that 'looks like' a kernel text address. If it fits into the frame pointer chain, we print it without a question @@ -141,6 +147,6 @@ that look like kernel text addresses, so if debug information is wrong, we still print out the real call chain as well - just with more question marks than ideal. -[*] For things like IRQ and IST stacks, we also scan those stacks, in - the right order, and try to cross from one stack into another - reconstructing the call chain. This works most of the time. +.. [1] For things like IRQ and IST stacks, we also scan those stacks, in + the right order, and try to cross from one stack into another + reconstructing the call chain. This works most of the time. diff --git a/Documentation/x86/mds.rst b/Documentation/x86/mds.rst new file mode 100644 index 000000000000..534e9baa4e1d --- /dev/null +++ b/Documentation/x86/mds.rst @@ -0,0 +1,225 @@ +Microarchitectural Data Sampling (MDS) mitigation +================================================= + +.. _mds: + +Overview +-------- + +Microarchitectural Data Sampling (MDS) is a family of side channel attacks +on internal buffers in Intel CPUs. The variants are: + + - Microarchitectural Store Buffer Data Sampling (MSBDS) (CVE-2018-12126) + - Microarchitectural Fill Buffer Data Sampling (MFBDS) (CVE-2018-12130) + - Microarchitectural Load Port Data Sampling (MLPDS) (CVE-2018-12127) + - Microarchitectural Data Sampling Uncacheable Memory (MDSUM) (CVE-2019-11091) + +MSBDS leaks Store Buffer Entries which can be speculatively forwarded to a +dependent load (store-to-load forwarding) as an optimization. The forward +can also happen to a faulting or assisting load operation for a different +memory address, which can be exploited under certain conditions. Store +buffers are partitioned between Hyper-Threads so cross thread forwarding is +not possible. But if a thread enters or exits a sleep state the store +buffer is repartitioned which can expose data from one thread to the other. + +MFBDS leaks Fill Buffer Entries. Fill buffers are used internally to manage +L1 miss situations and to hold data which is returned or sent in response +to a memory or I/O operation. Fill buffers can forward data to a load +operation and also write data to the cache. When the fill buffer is +deallocated it can retain the stale data of the preceding operations which +can then be forwarded to a faulting or assisting load operation, which can +be exploited under certain conditions. Fill buffers are shared between +Hyper-Threads so cross thread leakage is possible. + +MLPDS leaks Load Port Data. Load ports are used to perform load operations +from memory or I/O. The received data is then forwarded to the register +file or a subsequent operation. In some implementations the Load Port can +contain stale data from a previous operation which can be forwarded to +faulting or assisting loads under certain conditions, which again can be +exploited eventually. Load ports are shared between Hyper-Threads so cross +thread leakage is possible. + +MDSUM is a special case of MSBDS, MFBDS and MLPDS. An uncacheable load from +memory that takes a fault or assist can leave data in a microarchitectural +structure that may later be observed using one of the same methods used by +MSBDS, MFBDS or MLPDS. + +Exposure assumptions +-------------------- + +It is assumed that attack code resides in user space or in a guest with one +exception. The rationale behind this assumption is that the code construct +needed for exploiting MDS requires: + + - to control the load to trigger a fault or assist + + - to have a disclosure gadget which exposes the speculatively accessed + data for consumption through a side channel. + + - to control the pointer through which the disclosure gadget exposes the + data + +The existence of such a construct in the kernel cannot be excluded with +100% certainty, but the complexity involved makes it extremly unlikely. + +There is one exception, which is untrusted BPF. The functionality of +untrusted BPF is limited, but it needs to be thoroughly investigated +whether it can be used to create such a construct. + + +Mitigation strategy +------------------- + +All variants have the same mitigation strategy at least for the single CPU +thread case (SMT off): Force the CPU to clear the affected buffers. + +This is achieved by using the otherwise unused and obsolete VERW +instruction in combination with a microcode update. The microcode clears +the affected CPU buffers when the VERW instruction is executed. + +For virtualization there are two ways to achieve CPU buffer +clearing. Either the modified VERW instruction or via the L1D Flush +command. The latter is issued when L1TF mitigation is enabled so the extra +VERW can be avoided. If the CPU is not affected by L1TF then VERW needs to +be issued. + +If the VERW instruction with the supplied segment selector argument is +executed on a CPU without the microcode update there is no side effect +other than a small number of pointlessly wasted CPU cycles. + +This does not protect against cross Hyper-Thread attacks except for MSBDS +which is only exploitable cross Hyper-thread when one of the Hyper-Threads +enters a C-state. + +The kernel provides a function to invoke the buffer clearing: + + mds_clear_cpu_buffers() + +The mitigation is invoked on kernel/userspace, hypervisor/guest and C-state +(idle) transitions. + +As a special quirk to address virtualization scenarios where the host has +the microcode updated, but the hypervisor does not (yet) expose the +MD_CLEAR CPUID bit to guests, the kernel issues the VERW instruction in the +hope that it might actually clear the buffers. The state is reflected +accordingly. + +According to current knowledge additional mitigations inside the kernel +itself are not required because the necessary gadgets to expose the leaked +data cannot be controlled in a way which allows exploitation from malicious +user space or VM guests. + +Kernel internal mitigation modes +-------------------------------- + + ======= ============================================================ + off Mitigation is disabled. Either the CPU is not affected or + mds=off is supplied on the kernel command line + + full Mitigation is enabled. CPU is affected and MD_CLEAR is + advertised in CPUID. + + vmwerv Mitigation is enabled. CPU is affected and MD_CLEAR is not + advertised in CPUID. That is mainly for virtualization + scenarios where the host has the updated microcode but the + hypervisor does not expose MD_CLEAR in CPUID. It's a best + effort approach without guarantee. + ======= ============================================================ + +If the CPU is affected and mds=off is not supplied on the kernel command +line then the kernel selects the appropriate mitigation mode depending on +the availability of the MD_CLEAR CPUID bit. + +Mitigation points +----------------- + +1. Return to user space +^^^^^^^^^^^^^^^^^^^^^^^ + + When transitioning from kernel to user space the CPU buffers are flushed + on affected CPUs when the mitigation is not disabled on the kernel + command line. The migitation is enabled through the static key + mds_user_clear. + + The mitigation is invoked in prepare_exit_to_usermode() which covers + most of the kernel to user space transitions. There are a few exceptions + which are not invoking prepare_exit_to_usermode() on return to user + space. These exceptions use the paranoid exit code. + + - Non Maskable Interrupt (NMI): + + Access to sensible data like keys, credentials in the NMI context is + mostly theoretical: The CPU can do prefetching or execute a + misspeculated code path and thereby fetching data which might end up + leaking through a buffer. + + But for mounting other attacks the kernel stack address of the task is + already valuable information. So in full mitigation mode, the NMI is + mitigated on the return from do_nmi() to provide almost complete + coverage. + + - Double fault (#DF): + + A double fault is usually fatal, but the ESPFIX workaround, which can + be triggered from user space through modify_ldt(2) is a recoverable + double fault. #DF uses the paranoid exit path, so explicit mitigation + in the double fault handler is required. + + - Machine Check Exception (#MC): + + Another corner case is a #MC which hits between the CPU buffer clear + invocation and the actual return to user. As this still is in kernel + space it takes the paranoid exit path which does not clear the CPU + buffers. So the #MC handler repopulates the buffers to some + extent. Machine checks are not reliably controllable and the window is + extremly small so mitigation would just tick a checkbox that this + theoretical corner case is covered. To keep the amount of special + cases small, ignore #MC. + + - Debug Exception (#DB): + + This takes the paranoid exit path only when the INT1 breakpoint is in + kernel space. #DB on a user space address takes the regular exit path, + so no extra mitigation required. + + +2. C-State transition +^^^^^^^^^^^^^^^^^^^^^ + + When a CPU goes idle and enters a C-State the CPU buffers need to be + cleared on affected CPUs when SMT is active. This addresses the + repartitioning of the store buffer when one of the Hyper-Threads enters + a C-State. + + When SMT is inactive, i.e. either the CPU does not support it or all + sibling threads are offline CPU buffer clearing is not required. + + The idle clearing is enabled on CPUs which are only affected by MSBDS + and not by any other MDS variant. The other MDS variants cannot be + protected against cross Hyper-Thread attacks because the Fill Buffer and + the Load Ports are shared. So on CPUs affected by other variants, the + idle clearing would be a window dressing exercise and is therefore not + activated. + + The invocation is controlled by the static key mds_idle_clear which is + switched depending on the chosen mitigation mode and the SMT state of + the system. + + The buffer clear is only invoked before entering the C-State to prevent + that stale data from the idling CPU from spilling to the Hyper-Thread + sibling after the store buffer got repartitioned and all entries are + available to the non idle sibling. + + When coming out of idle the store buffer is partitioned again so each + sibling has half of it available. The back from idle CPU could be then + speculatively exposed to contents of the sibling. The buffers are + flushed either on exit to user space or on VMENTER so malicious code + in user space or the guest cannot speculatively access them. + + The mitigation is hooked into all variants of halt()/mwait(), but does + not cover the legacy ACPI IO-Port mechanism because the ACPI idle driver + has been superseded by the intel_idle driver around 2010 and is + preferred on all affected CPUs which are expected to gain the MD_CLEAR + functionality in microcode. Aside of that the IO-Port mechanism is a + legacy interface which is only used on older systems which are either + not affected or do not receive microcode updates anymore. diff --git a/Documentation/x86/microcode.txt b/Documentation/x86/microcode.rst index 79fdb4a8148a..a320d37982ed 100644 --- a/Documentation/x86/microcode.txt +++ b/Documentation/x86/microcode.rst @@ -1,7 +1,11 @@ - The Linux Microcode Loader +.. SPDX-License-Identifier: GPL-2.0 -Authors: Fenghua Yu <fenghua.yu@intel.com> - Borislav Petkov <bp@suse.de> +========================== +The Linux Microcode Loader +========================== + +:Authors: - Fenghua Yu <fenghua.yu@intel.com> + - Borislav Petkov <bp@suse.de> The kernel has a x86 microcode loading facility which is supposed to provide microcode loading methods in the OS. Potential use cases are @@ -10,8 +14,8 @@ and updating the microcode on long-running systems without rebooting. The loader supports three loading methods: -1. Early load microcode -======================= +Early load microcode +==================== The kernel can update microcode very early during boot. Loading microcode early can fix CPU issues before they are observed during @@ -26,8 +30,10 @@ loader parses the combined initrd image during boot. The microcode files in cpio name space are: -on Intel: kernel/x86/microcode/GenuineIntel.bin -on AMD : kernel/x86/microcode/AuthenticAMD.bin +on Intel: + kernel/x86/microcode/GenuineIntel.bin +on AMD : + kernel/x86/microcode/AuthenticAMD.bin During BSP (BootStrapping Processor) boot (pre-SMP), the kernel scans the microcode file in the initrd. If microcode matching the @@ -42,8 +48,8 @@ Here's a crude example how to prepare an initrd with microcode (this is normally done automatically by the distribution, when recreating the initrd, so you don't really have to do it yourself. It is documented here for future reference only). +:: ---- #!/bin/bash if [ -z "$1" ]; then @@ -76,15 +82,15 @@ here for future reference only). cat ucode.cpio $INITRD.orig > $INITRD rm -rf $TMPDIR ---- + The system needs to have the microcode packages installed into /lib/firmware or you need to fixup the paths above if yours are somewhere else and/or you've downloaded them directly from the processor vendor's site. -2. Late loading -=============== +Late loading +============ There are two legacy user space interfaces to load microcode, either through /dev/cpu/microcode or through /sys/devices/system/cpu/microcode/reload file @@ -94,9 +100,9 @@ The /dev/cpu/microcode method is deprecated because it needs a special userspace tool for that. The easier method is simply installing the microcode packages your distro -supplies and running: +supplies and running:: -# echo 1 > /sys/devices/system/cpu/microcode/reload + # echo 1 > /sys/devices/system/cpu/microcode/reload as root. @@ -104,29 +110,29 @@ The loading mechanism looks for microcode blobs in /lib/firmware/{intel-ucode,amd-ucode}. The default distro installation packages already put them there. -3. Builtin microcode -==================== +Builtin microcode +================= The loader supports also loading of a builtin microcode supplied through the regular builtin firmware method CONFIG_EXTRA_FIRMWARE. Only 64-bit is currently supported. -Here's an example: +Here's an example:: -CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin" -CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware" + CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin" + CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware" -This basically means, you have the following tree structure locally: +This basically means, you have the following tree structure locally:: -/lib/firmware/ -|-- amd-ucode -... -| |-- microcode_amd_fam15h.bin -... -|-- intel-ucode -... -| |-- 06-3a-09 -... + /lib/firmware/ + |-- amd-ucode + ... + | |-- microcode_amd_fam15h.bin + ... + |-- intel-ucode + ... + | |-- 06-3a-09 + ... so that the build system can find those files and integrate them into the final kernel image. The early loader finds them and applies them. diff --git a/Documentation/x86/mtrr.rst b/Documentation/x86/mtrr.rst new file mode 100644 index 000000000000..c5b695d75349 --- /dev/null +++ b/Documentation/x86/mtrr.rst @@ -0,0 +1,354 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================= +MTRR (Memory Type Range Register) control +========================================= + +:Authors: - Richard Gooch <rgooch@atnf.csiro.au> - 3 Jun 1999 + - Luis R. Rodriguez <mcgrof@do-not-panic.com> - April 9, 2015 + + +Phasing out MTRR use +==================== + +MTRR use is replaced on modern x86 hardware with PAT. Direct MTRR use by +drivers on Linux is now completely phased out, device drivers should use +arch_phys_wc_add() in combination with ioremap_wc() to make MTRR effective on +non-PAT systems while a no-op but equally effective on PAT enabled systems. + +Even if Linux does not use MTRRs directly, some x86 platform firmware may still +set up MTRRs early before booting the OS. They do this as some platform +firmware may still have implemented access to MTRRs which would be controlled +and handled by the platform firmware directly. An example of platform use of +MTRRs is through the use of SMI handlers, one case could be for fan control, +the platform code would need uncachable access to some of its fan control +registers. Such platform access does not need any Operating System MTRR code in +place other than mtrr_type_lookup() to ensure any OS specific mapping requests +are aligned with platform MTRR setup. If MTRRs are only set up by the platform +firmware code though and the OS does not make any specific MTRR mapping +requests mtrr_type_lookup() should always return MTRR_TYPE_INVALID. + +For details refer to :doc:`pat`. + +.. tip:: + On Intel P6 family processors (Pentium Pro, Pentium II and later) + the Memory Type Range Registers (MTRRs) may be used to control + processor access to memory ranges. This is most useful when you have + a video (VGA) card on a PCI or AGP bus. Enabling write-combining + allows bus write transfers to be combined into a larger transfer + before bursting over the PCI/AGP bus. This can increase performance + of image write operations 2.5 times or more. + + The Cyrix 6x86, 6x86MX and M II processors have Address Range + Registers (ARRs) which provide a similar functionality to MTRRs. For + these, the ARRs are used to emulate the MTRRs. + + The AMD K6-2 (stepping 8 and above) and K6-3 processors have two + MTRRs. These are supported. The AMD Athlon family provide 8 Intel + style MTRRs. + + The Centaur C6 (WinChip) has 8 MCRs, allowing write-combining. These + are supported. + + The VIA Cyrix III and VIA C3 CPUs offer 8 Intel style MTRRs. + + The CONFIG_MTRR option creates a /proc/mtrr file which may be used + to manipulate your MTRRs. Typically the X server should use + this. This should have a reasonably generic interface so that + similar control registers on other processors can be easily + supported. + +There are two interfaces to /proc/mtrr: one is an ASCII interface +which allows you to read and write. The other is an ioctl() +interface. The ASCII interface is meant for administration. The +ioctl() interface is meant for C programs (i.e. the X server). The +interfaces are described below, with sample commands and C code. + + +Reading MTRRs from the shell +============================ +:: + + % cat /proc/mtrr + reg00: base=0x00000000 ( 0MB), size= 128MB: write-back, count=1 + reg01: base=0x08000000 ( 128MB), size= 64MB: write-back, count=1 + +Creating MTRRs from the C-shell:: + + # echo "base=0xf8000000 size=0x400000 type=write-combining" >! /proc/mtrr + +or if you use bash:: + + # echo "base=0xf8000000 size=0x400000 type=write-combining" >| /proc/mtrr + +And the result thereof:: + + % cat /proc/mtrr + reg00: base=0x00000000 ( 0MB), size= 128MB: write-back, count=1 + reg01: base=0x08000000 ( 128MB), size= 64MB: write-back, count=1 + reg02: base=0xf8000000 (3968MB), size= 4MB: write-combining, count=1 + +This is for video RAM at base address 0xf8000000 and size 4 megabytes. To +find out your base address, you need to look at the output of your X +server, which tells you where the linear framebuffer address is. A +typical line that you may get is:: + + (--) S3: PCI: 968 rev 0, Linear FB @ 0xf8000000 + +Note that you should only use the value from the X server, as it may +move the framebuffer base address, so the only value you can trust is +that reported by the X server. + +To find out the size of your framebuffer (what, you don't actually +know?), the following line will tell you:: + + (--) S3: videoram: 4096k + +That's 4 megabytes, which is 0x400000 bytes (in hexadecimal). +A patch is being written for XFree86 which will make this automatic: +in other words the X server will manipulate /proc/mtrr using the +ioctl() interface, so users won't have to do anything. If you use a +commercial X server, lobby your vendor to add support for MTRRs. + + +Creating overlapping MTRRs +========================== +:: + + %echo "base=0xfb000000 size=0x1000000 type=write-combining" >/proc/mtrr + %echo "base=0xfb000000 size=0x1000 type=uncachable" >/proc/mtrr + +And the results:: + + % cat /proc/mtrr + reg00: base=0x00000000 ( 0MB), size= 64MB: write-back, count=1 + reg01: base=0xfb000000 (4016MB), size= 16MB: write-combining, count=1 + reg02: base=0xfb000000 (4016MB), size= 4kB: uncachable, count=1 + +Some cards (especially Voodoo Graphics boards) need this 4 kB area +excluded from the beginning of the region because it is used for +registers. + +NOTE: You can only create type=uncachable region, if the first +region that you created is type=write-combining. + + +Removing MTRRs from the C-shel +============================== +:: + + % echo "disable=2" >! /proc/mtrr + +or using bash:: + + % echo "disable=2" >| /proc/mtrr + + +Reading MTRRs from a C program using ioctl()'s +============================================== +:: + + /* mtrr-show.c + + Source file for mtrr-show (example program to show MTRRs using ioctl()'s) + + Copyright (C) 1997-1998 Richard Gooch + + 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., 675 Mass Ave, Cambridge, MA 02139, USA. + + Richard Gooch may be reached by email at rgooch@atnf.csiro.au + The postal address is: + Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia. + */ + + /* + This program will use an ioctl() on /proc/mtrr to show the current MTRR + settings. This is an alternative to reading /proc/mtrr. + + + Written by Richard Gooch 17-DEC-1997 + + Last updated by Richard Gooch 2-MAY-1998 + + + */ + #include <stdio.h> + #include <stdlib.h> + #include <string.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <sys/ioctl.h> + #include <errno.h> + #include <asm/mtrr.h> + + #define TRUE 1 + #define FALSE 0 + #define ERRSTRING strerror (errno) + + static char *mtrr_strings[MTRR_NUM_TYPES] = + { + "uncachable", /* 0 */ + "write-combining", /* 1 */ + "?", /* 2 */ + "?", /* 3 */ + "write-through", /* 4 */ + "write-protect", /* 5 */ + "write-back", /* 6 */ + }; + + int main () + { + int fd; + struct mtrr_gentry gentry; + + if ( ( fd = open ("/proc/mtrr", O_RDONLY, 0) ) == -1 ) + { + if (errno == ENOENT) + { + fputs ("/proc/mtrr not found: not supported or you don't have a PPro?\n", + stderr); + exit (1); + } + fprintf (stderr, "Error opening /proc/mtrr\t%s\n", ERRSTRING); + exit (2); + } + for (gentry.regnum = 0; ioctl (fd, MTRRIOC_GET_ENTRY, &gentry) == 0; + ++gentry.regnum) + { + if (gentry.size < 1) + { + fprintf (stderr, "Register: %u disabled\n", gentry.regnum); + continue; + } + fprintf (stderr, "Register: %u base: 0x%lx size: 0x%lx type: %s\n", + gentry.regnum, gentry.base, gentry.size, + mtrr_strings[gentry.type]); + } + if (errno == EINVAL) exit (0); + fprintf (stderr, "Error doing ioctl(2) on /dev/mtrr\t%s\n", ERRSTRING); + exit (3); + } /* End Function main */ + + +Creating MTRRs from a C programme using ioctl()'s +================================================= +:: + + /* mtrr-add.c + + Source file for mtrr-add (example programme to add an MTRRs using ioctl()) + + Copyright (C) 1997-1998 Richard Gooch + + 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., 675 Mass Ave, Cambridge, MA 02139, USA. + + Richard Gooch may be reached by email at rgooch@atnf.csiro.au + The postal address is: + Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia. + */ + + /* + This programme will use an ioctl() on /proc/mtrr to add an entry. The first + available mtrr is used. This is an alternative to writing /proc/mtrr. + + + Written by Richard Gooch 17-DEC-1997 + + Last updated by Richard Gooch 2-MAY-1998 + + + */ + #include <stdio.h> + #include <string.h> + #include <stdlib.h> + #include <unistd.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <sys/ioctl.h> + #include <errno.h> + #include <asm/mtrr.h> + + #define TRUE 1 + #define FALSE 0 + #define ERRSTRING strerror (errno) + + static char *mtrr_strings[MTRR_NUM_TYPES] = + { + "uncachable", /* 0 */ + "write-combining", /* 1 */ + "?", /* 2 */ + "?", /* 3 */ + "write-through", /* 4 */ + "write-protect", /* 5 */ + "write-back", /* 6 */ + }; + + int main (int argc, char **argv) + { + int fd; + struct mtrr_sentry sentry; + + if (argc != 4) + { + fprintf (stderr, "Usage:\tmtrr-add base size type\n"); + exit (1); + } + sentry.base = strtoul (argv[1], NULL, 0); + sentry.size = strtoul (argv[2], NULL, 0); + for (sentry.type = 0; sentry.type < MTRR_NUM_TYPES; ++sentry.type) + { + if (strcmp (argv[3], mtrr_strings[sentry.type]) == 0) break; + } + if (sentry.type >= MTRR_NUM_TYPES) + { + fprintf (stderr, "Illegal type: \"%s\"\n", argv[3]); + exit (2); + } + if ( ( fd = open ("/proc/mtrr", O_WRONLY, 0) ) == -1 ) + { + if (errno == ENOENT) + { + fputs ("/proc/mtrr not found: not supported or you don't have a PPro?\n", + stderr); + exit (3); + } + fprintf (stderr, "Error opening /proc/mtrr\t%s\n", ERRSTRING); + exit (4); + } + if (ioctl (fd, MTRRIOC_ADD_ENTRY, &sentry) == -1) + { + fprintf (stderr, "Error doing ioctl(2) on /dev/mtrr\t%s\n", ERRSTRING); + exit (5); + } + fprintf (stderr, "Sleeping for 5 seconds so you can see the new entry\n"); + sleep (5); + close (fd); + fputs ("I've just closed /proc/mtrr so now the new entry should be gone\n", + stderr); + } /* End Function main */ diff --git a/Documentation/x86/mtrr.txt b/Documentation/x86/mtrr.txt deleted file mode 100644 index dc3e703913ac..000000000000 --- a/Documentation/x86/mtrr.txt +++ /dev/null @@ -1,329 +0,0 @@ -MTRR (Memory Type Range Register) control - -Richard Gooch <rgooch@atnf.csiro.au> - 3 Jun 1999 -Luis R. Rodriguez <mcgrof@do-not-panic.com> - April 9, 2015 - -=============================================================================== -Phasing out MTRR use - -MTRR use is replaced on modern x86 hardware with PAT. Direct MTRR use by -drivers on Linux is now completely phased out, device drivers should use -arch_phys_wc_add() in combination with ioremap_wc() to make MTRR effective on -non-PAT systems while a no-op but equally effective on PAT enabled systems. - -Even if Linux does not use MTRRs directly, some x86 platform firmware may still -set up MTRRs early before booting the OS. They do this as some platform -firmware may still have implemented access to MTRRs which would be controlled -and handled by the platform firmware directly. An example of platform use of -MTRRs is through the use of SMI handlers, one case could be for fan control, -the platform code would need uncachable access to some of its fan control -registers. Such platform access does not need any Operating System MTRR code in -place other than mtrr_type_lookup() to ensure any OS specific mapping requests -are aligned with platform MTRR setup. If MTRRs are only set up by the platform -firmware code though and the OS does not make any specific MTRR mapping -requests mtrr_type_lookup() should always return MTRR_TYPE_INVALID. - -For details refer to Documentation/x86/pat.txt. - -=============================================================================== - - On Intel P6 family processors (Pentium Pro, Pentium II and later) - the Memory Type Range Registers (MTRRs) may be used to control - processor access to memory ranges. This is most useful when you have - a video (VGA) card on a PCI or AGP bus. Enabling write-combining - allows bus write transfers to be combined into a larger transfer - before bursting over the PCI/AGP bus. This can increase performance - of image write operations 2.5 times or more. - - The Cyrix 6x86, 6x86MX and M II processors have Address Range - Registers (ARRs) which provide a similar functionality to MTRRs. For - these, the ARRs are used to emulate the MTRRs. - - The AMD K6-2 (stepping 8 and above) and K6-3 processors have two - MTRRs. These are supported. The AMD Athlon family provide 8 Intel - style MTRRs. - - The Centaur C6 (WinChip) has 8 MCRs, allowing write-combining. These - are supported. - - The VIA Cyrix III and VIA C3 CPUs offer 8 Intel style MTRRs. - - The CONFIG_MTRR option creates a /proc/mtrr file which may be used - to manipulate your MTRRs. Typically the X server should use - this. This should have a reasonably generic interface so that - similar control registers on other processors can be easily - supported. - - -There are two interfaces to /proc/mtrr: one is an ASCII interface -which allows you to read and write. The other is an ioctl() -interface. The ASCII interface is meant for administration. The -ioctl() interface is meant for C programs (i.e. the X server). The -interfaces are described below, with sample commands and C code. - -=============================================================================== -Reading MTRRs from the shell: - -% cat /proc/mtrr -reg00: base=0x00000000 ( 0MB), size= 128MB: write-back, count=1 -reg01: base=0x08000000 ( 128MB), size= 64MB: write-back, count=1 -=============================================================================== -Creating MTRRs from the C-shell: -# echo "base=0xf8000000 size=0x400000 type=write-combining" >! /proc/mtrr -or if you use bash: -# echo "base=0xf8000000 size=0x400000 type=write-combining" >| /proc/mtrr - -And the result thereof: -% cat /proc/mtrr -reg00: base=0x00000000 ( 0MB), size= 128MB: write-back, count=1 -reg01: base=0x08000000 ( 128MB), size= 64MB: write-back, count=1 -reg02: base=0xf8000000 (3968MB), size= 4MB: write-combining, count=1 - -This is for video RAM at base address 0xf8000000 and size 4 megabytes. To -find out your base address, you need to look at the output of your X -server, which tells you where the linear framebuffer address is. A -typical line that you may get is: - -(--) S3: PCI: 968 rev 0, Linear FB @ 0xf8000000 - -Note that you should only use the value from the X server, as it may -move the framebuffer base address, so the only value you can trust is -that reported by the X server. - -To find out the size of your framebuffer (what, you don't actually -know?), the following line will tell you: - -(--) S3: videoram: 4096k - -That's 4 megabytes, which is 0x400000 bytes (in hexadecimal). -A patch is being written for XFree86 which will make this automatic: -in other words the X server will manipulate /proc/mtrr using the -ioctl() interface, so users won't have to do anything. If you use a -commercial X server, lobby your vendor to add support for MTRRs. -=============================================================================== -Creating overlapping MTRRs: - -%echo "base=0xfb000000 size=0x1000000 type=write-combining" >/proc/mtrr -%echo "base=0xfb000000 size=0x1000 type=uncachable" >/proc/mtrr - -And the results: cat /proc/mtrr -reg00: base=0x00000000 ( 0MB), size= 64MB: write-back, count=1 -reg01: base=0xfb000000 (4016MB), size= 16MB: write-combining, count=1 -reg02: base=0xfb000000 (4016MB), size= 4kB: uncachable, count=1 - -Some cards (especially Voodoo Graphics boards) need this 4 kB area -excluded from the beginning of the region because it is used for -registers. - -NOTE: You can only create type=uncachable region, if the first -region that you created is type=write-combining. -=============================================================================== -Removing MTRRs from the C-shell: -% echo "disable=2" >! /proc/mtrr -or using bash: -% echo "disable=2" >| /proc/mtrr -=============================================================================== -Reading MTRRs from a C program using ioctl()'s: - -/* mtrr-show.c - - Source file for mtrr-show (example program to show MTRRs using ioctl()'s) - - Copyright (C) 1997-1998 Richard Gooch - - 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., 675 Mass Ave, Cambridge, MA 02139, USA. - - Richard Gooch may be reached by email at rgooch@atnf.csiro.au - The postal address is: - Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia. -*/ - -/* - This program will use an ioctl() on /proc/mtrr to show the current MTRR - settings. This is an alternative to reading /proc/mtrr. - - - Written by Richard Gooch 17-DEC-1997 - - Last updated by Richard Gooch 2-MAY-1998 - - -*/ -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <fcntl.h> -#include <sys/ioctl.h> -#include <errno.h> -#include <asm/mtrr.h> - -#define TRUE 1 -#define FALSE 0 -#define ERRSTRING strerror (errno) - -static char *mtrr_strings[MTRR_NUM_TYPES] = -{ - "uncachable", /* 0 */ - "write-combining", /* 1 */ - "?", /* 2 */ - "?", /* 3 */ - "write-through", /* 4 */ - "write-protect", /* 5 */ - "write-back", /* 6 */ -}; - -int main () -{ - int fd; - struct mtrr_gentry gentry; - - if ( ( fd = open ("/proc/mtrr", O_RDONLY, 0) ) == -1 ) - { - if (errno == ENOENT) - { - fputs ("/proc/mtrr not found: not supported or you don't have a PPro?\n", - stderr); - exit (1); - } - fprintf (stderr, "Error opening /proc/mtrr\t%s\n", ERRSTRING); - exit (2); - } - for (gentry.regnum = 0; ioctl (fd, MTRRIOC_GET_ENTRY, &gentry) == 0; - ++gentry.regnum) - { - if (gentry.size < 1) - { - fprintf (stderr, "Register: %u disabled\n", gentry.regnum); - continue; - } - fprintf (stderr, "Register: %u base: 0x%lx size: 0x%lx type: %s\n", - gentry.regnum, gentry.base, gentry.size, - mtrr_strings[gentry.type]); - } - if (errno == EINVAL) exit (0); - fprintf (stderr, "Error doing ioctl(2) on /dev/mtrr\t%s\n", ERRSTRING); - exit (3); -} /* End Function main */ -=============================================================================== -Creating MTRRs from a C programme using ioctl()'s: - -/* mtrr-add.c - - Source file for mtrr-add (example programme to add an MTRRs using ioctl()) - - Copyright (C) 1997-1998 Richard Gooch - - 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., 675 Mass Ave, Cambridge, MA 02139, USA. - - Richard Gooch may be reached by email at rgooch@atnf.csiro.au - The postal address is: - Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia. -*/ - -/* - This programme will use an ioctl() on /proc/mtrr to add an entry. The first - available mtrr is used. This is an alternative to writing /proc/mtrr. - - - Written by Richard Gooch 17-DEC-1997 - - Last updated by Richard Gooch 2-MAY-1998 - - -*/ -#include <stdio.h> -#include <string.h> -#include <stdlib.h> -#include <unistd.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <fcntl.h> -#include <sys/ioctl.h> -#include <errno.h> -#include <asm/mtrr.h> - -#define TRUE 1 -#define FALSE 0 -#define ERRSTRING strerror (errno) - -static char *mtrr_strings[MTRR_NUM_TYPES] = -{ - "uncachable", /* 0 */ - "write-combining", /* 1 */ - "?", /* 2 */ - "?", /* 3 */ - "write-through", /* 4 */ - "write-protect", /* 5 */ - "write-back", /* 6 */ -}; - -int main (int argc, char **argv) -{ - int fd; - struct mtrr_sentry sentry; - - if (argc != 4) - { - fprintf (stderr, "Usage:\tmtrr-add base size type\n"); - exit (1); - } - sentry.base = strtoul (argv[1], NULL, 0); - sentry.size = strtoul (argv[2], NULL, 0); - for (sentry.type = 0; sentry.type < MTRR_NUM_TYPES; ++sentry.type) - { - if (strcmp (argv[3], mtrr_strings[sentry.type]) == 0) break; - } - if (sentry.type >= MTRR_NUM_TYPES) - { - fprintf (stderr, "Illegal type: \"%s\"\n", argv[3]); - exit (2); - } - if ( ( fd = open ("/proc/mtrr", O_WRONLY, 0) ) == -1 ) - { - if (errno == ENOENT) - { - fputs ("/proc/mtrr not found: not supported or you don't have a PPro?\n", - stderr); - exit (3); - } - fprintf (stderr, "Error opening /proc/mtrr\t%s\n", ERRSTRING); - exit (4); - } - if (ioctl (fd, MTRRIOC_ADD_ENTRY, &sentry) == -1) - { - fprintf (stderr, "Error doing ioctl(2) on /dev/mtrr\t%s\n", ERRSTRING); - exit (5); - } - fprintf (stderr, "Sleeping for 5 seconds so you can see the new entry\n"); - sleep (5); - close (fd); - fputs ("I've just closed /proc/mtrr so now the new entry should be gone\n", - stderr); -} /* End Function main */ -=============================================================================== diff --git a/Documentation/x86/orc-unwinder.txt b/Documentation/x86/orc-unwinder.rst index cd4b29be29af..d811576c1f3e 100644 --- a/Documentation/x86/orc-unwinder.txt +++ b/Documentation/x86/orc-unwinder.rst @@ -1,8 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ ORC unwinder ============ Overview --------- +======== The kernel CONFIG_UNWINDER_ORC option enables the ORC unwinder, which is similar in concept to a DWARF unwinder. The difference is that the @@ -23,12 +26,12 @@ correlate instruction addresses with their stack states at run time. ORC vs frame pointers ---------------------- +===================== With frame pointers enabled, GCC adds instrumentation code to every function in the kernel. The kernel's .text size increases by about 3.2%, resulting in a broad kernel-wide slowdown. Measurements by Mel -Gorman [1] have shown a slowdown of 5-10% for some workloads. +Gorman [1]_ have shown a slowdown of 5-10% for some workloads. In contrast, the ORC unwinder has no effect on text size or runtime performance, because the debuginfo is out of band. So if you disable @@ -55,7 +58,7 @@ depending on the kernel config. ORC vs DWARF ------------- +============ ORC debuginfo's advantage over DWARF itself is that it's much simpler. It gets rid of the complex DWARF CFI state machine and also gets rid of @@ -65,7 +68,7 @@ mission critical oops code. The simpler debuginfo format also enables the unwinder to be much faster than DWARF, which is important for perf and lockdep. In a basic -performance test by Jiri Slaby [2], the ORC unwinder was about 20x +performance test by Jiri Slaby [2]_, the ORC unwinder was about 20x faster than an out-of-tree DWARF unwinder. (Note: That measurement was taken before some performance tweaks were added, which doubled performance, so the speedup over DWARF may be closer to 40x.) @@ -85,7 +88,7 @@ still be able to control the format, e.g. no complex state machines. ORC unwind table generation ---------------------------- +=========================== The ORC data is generated by objtool. With the existing compile-time stack metadata validation feature, objtool already follows all code @@ -133,7 +136,7 @@ objtool follows GCC code quite well. Unwinder implementation details -------------------------------- +=============================== Objtool generates the ORC data by integrating with the compile-time stack metadata validation feature, which is described in detail in @@ -154,7 +157,7 @@ subset of the table needs to be searched. Etymology ---------- +========= Orcs, fearsome creatures of medieval folklore, are the Dwarves' natural enemies. Similarly, the ORC unwinder was created in opposition to the @@ -162,7 +165,7 @@ complexity and slowness of DWARF. "Although Orcs rarely consider multiple solutions to a problem, they do excel at getting things done because they are creatures of action, not -thought." [3] Similarly, unlike the esoteric DWARF unwinder, the +thought." [3]_ Similarly, unlike the esoteric DWARF unwinder, the veracious ORC unwinder wastes no time or siloconic effort decoding variable-length zero-extended unsigned-integer byte-coded state-machine-based debug information entries. @@ -174,6 +177,6 @@ brutal, unyielding efficiency. ORC stands for Oops Rewind Capability. -[1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de -[2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz -[3] http://dustin.wikidot.com/half-orcs-and-orcs +.. [1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de +.. [2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz +.. [3] http://dustin.wikidot.com/half-orcs-and-orcs diff --git a/Documentation/x86/pat.rst b/Documentation/x86/pat.rst new file mode 100644 index 000000000000..9a298fd97d74 --- /dev/null +++ b/Documentation/x86/pat.rst @@ -0,0 +1,242 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +PAT (Page Attribute Table) +========================== + +x86 Page Attribute Table (PAT) allows for setting the memory attribute at the +page level granularity. PAT is complementary to the MTRR settings which allows +for setting of memory types over physical address ranges. However, PAT is +more flexible than MTRR due to its capability to set attributes at page level +and also due to the fact that there are no hardware limitations on number of +such attribute settings allowed. Added flexibility comes with guidelines for +not having memory type aliasing for the same physical memory with multiple +virtual addresses. + +PAT allows for different types of memory attributes. The most commonly used +ones that will be supported at this time are: + +=== ============== +WB Write-back +UC Uncached +WC Write-combined +WT Write-through +UC- Uncached Minus +=== ============== + + +PAT APIs +======== + +There are many different APIs in the kernel that allows setting of memory +attributes at the page level. In order to avoid aliasing, these interfaces +should be used thoughtfully. Below is a table of interfaces available, +their intended usage and their memory attribute relationships. Internally, +these APIs use a reserve_memtype()/free_memtype() interface on the physical +address range to avoid any aliasing. + ++------------------------+----------+--------------+------------------+ +| API | RAM | ACPI,... | Reserved/Holes | ++------------------------+----------+--------------+------------------+ +| ioremap | -- | UC- | UC- | ++------------------------+----------+--------------+------------------+ +| ioremap_cache | -- | WB | WB | ++------------------------+----------+--------------+------------------+ +| ioremap_uc | -- | UC | UC | ++------------------------+----------+--------------+------------------+ +| ioremap_nocache | -- | UC- | UC- | ++------------------------+----------+--------------+------------------+ +| ioremap_wc | -- | -- | WC | ++------------------------+----------+--------------+------------------+ +| ioremap_wt | -- | -- | WT | ++------------------------+----------+--------------+------------------+ +| set_memory_uc, | UC- | -- | -- | +| set_memory_wb | | | | ++------------------------+----------+--------------+------------------+ +| set_memory_wc, | WC | -- | -- | +| set_memory_wb | | | | ++------------------------+----------+--------------+------------------+ +| set_memory_wt, | WT | -- | -- | +| set_memory_wb | | | | ++------------------------+----------+--------------+------------------+ +| pci sysfs resource | -- | -- | UC- | ++------------------------+----------+--------------+------------------+ +| pci sysfs resource_wc | -- | -- | WC | +| is IORESOURCE_PREFETCH | | | | ++------------------------+----------+--------------+------------------+ +| pci proc | -- | -- | UC- | +| !PCIIOC_WRITE_COMBINE | | | | ++------------------------+----------+--------------+------------------+ +| pci proc | -- | -- | WC | +| PCIIOC_WRITE_COMBINE | | | | ++------------------------+----------+--------------+------------------+ +| /dev/mem | -- | WB/WC/UC- | WB/WC/UC- | +| read-write | | | | ++------------------------+----------+--------------+------------------+ +| /dev/mem | -- | UC- | UC- | +| mmap SYNC flag | | | | ++------------------------+----------+--------------+------------------+ +| /dev/mem | -- | WB/WC/UC- | WB/WC/UC- | +| mmap !SYNC flag | | | | +| and | |(from existing| (from existing | +| any alias to this area | |alias) | alias) | ++------------------------+----------+--------------+------------------+ +| /dev/mem | -- | WB | WB | +| mmap !SYNC flag | | | | +| no alias to this area | | | | +| and | | | | +| MTRR says WB | | | | ++------------------------+----------+--------------+------------------+ +| /dev/mem | -- | -- | UC- | +| mmap !SYNC flag | | | | +| no alias to this area | | | | +| and | | | | +| MTRR says !WB | | | | ++------------------------+----------+--------------+------------------+ + + +Advanced APIs for drivers +========================= + +A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range, +vmf_insert_pfn. + +Drivers wanting to export some pages to userspace do it by using mmap +interface and a combination of: + + 1) pgprot_noncached() + 2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn() + +With PAT support, a new API pgprot_writecombine is being added. So, drivers can +continue to use the above sequence, with either pgprot_noncached() or +pgprot_writecombine() in step 1, followed by step 2. + +In addition, step 2 internally tracks the region as UC or WC in memtype +list in order to ensure no conflicting mapping. + +Note that this set of APIs only works with IO (non RAM) regions. If driver +wants to export a RAM region, it has to do set_memory_uc() or set_memory_wc() +as step 0 above and also track the usage of those pages and use set_memory_wb() +before the page is freed to free pool. + +MTRR effects on PAT / non-PAT systems +===================================== + +The following table provides the effects of using write-combining MTRRs when +using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally +mtrr_add() usage will be phased out in favor of arch_phys_wc_add() which will +be a no-op on PAT enabled systems. The region over which a arch_phys_wc_add() +is made, should already have been ioremapped with WC attributes or PAT entries, +this can be done by using ioremap_wc() / set_memory_wc(). Devices which +combine areas of IO memory desired to remain uncacheable with areas where +write-combining is desirable should consider use of ioremap_uc() followed by +set_memory_wc() to white-list effective write-combined areas. Such use is +nevertheless discouraged as the effective memory type is considered +implementation defined, yet this strategy can be used as last resort on devices +with size-constrained regions where otherwise MTRR write-combining would +otherwise not be effective. +:: + + ==== ======= === ========================= ===================== + MTRR Non-PAT PAT Linux ioremap value Effective memory type + ==== ======= === ========================= ===================== + PAT Non-PAT | PAT + |PCD | + ||PWT | + ||| | + WC 000 WB _PAGE_CACHE_MODE_WB WC | WC + WC 001 WC _PAGE_CACHE_MODE_WC WC* | WC + WC 010 UC- _PAGE_CACHE_MODE_UC_MINUS WC* | UC + WC 011 UC _PAGE_CACHE_MODE_UC UC | UC + ==== ======= === ========================= ===================== + + (*) denotes implementation defined and is discouraged + +.. note:: -- in the above table mean "Not suggested usage for the API". Some + of the --'s are strictly enforced by the kernel. Some others are not really + enforced today, but may be enforced in future. + +For ioremap and pci access through /sys or /proc - The actual type returned +can be more restrictive, in case of any existing aliasing for that address. +For example: If there is an existing uncached mapping, a new ioremap_wc can +return uncached mapping in place of write-combine requested. + +set_memory_[uc|wc|wt] and set_memory_wb should be used in pairs, where driver +will first make a region uc, wc or wt and switch it back to wb after use. + +Over time writes to /proc/mtrr will be deprecated in favor of using PAT based +interfaces. Users writing to /proc/mtrr are suggested to use above interfaces. + +Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] access +types. + +Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges. + + +PAT debugging +============= + +With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by:: + + # mount -t debugfs debugfs /sys/kernel/debug + # cat /sys/kernel/debug/x86/pat_memtype_list + PAT memtype list: + uncached-minus @ 0x7fadf000-0x7fae0000 + uncached-minus @ 0x7fb19000-0x7fb1a000 + uncached-minus @ 0x7fb1a000-0x7fb1b000 + uncached-minus @ 0x7fb1b000-0x7fb1c000 + uncached-minus @ 0x7fb1c000-0x7fb1d000 + uncached-minus @ 0x7fb1d000-0x7fb1e000 + uncached-minus @ 0x7fb1e000-0x7fb25000 + uncached-minus @ 0x7fb25000-0x7fb26000 + uncached-minus @ 0x7fb26000-0x7fb27000 + uncached-minus @ 0x7fb27000-0x7fb28000 + uncached-minus @ 0x7fb28000-0x7fb2e000 + uncached-minus @ 0x7fb2e000-0x7fb2f000 + uncached-minus @ 0x7fb2f000-0x7fb30000 + uncached-minus @ 0x7fb31000-0x7fb32000 + uncached-minus @ 0x80000000-0x90000000 + +This list shows physical address ranges and various PAT settings used to +access those physical address ranges. + +Another, more verbose way of getting PAT related debug messages is with +"debugpat" boot parameter. With this parameter, various debug messages are +printed to dmesg log. + +PAT Initialization +================== + +The following table describes how PAT is initialized under various +configurations. The PAT MSR must be updated by Linux in order to support WC +and WT attributes. Otherwise, the PAT MSR has the value programmed in it +by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests. + + ==== ===== ========================== ========= ======= + MTRR PAT Call Sequence PAT State PAT MSR + ==== ===== ========================== ========= ======= + E E MTRR -> PAT init Enabled OS + E D MTRR -> PAT init Disabled - + D E MTRR -> PAT disable Disabled BIOS + D D MTRR -> PAT disable Disabled - + - np/E PAT -> PAT disable Disabled BIOS + - np/D PAT -> PAT disable Disabled - + E !P/E MTRR -> PAT init Disabled BIOS + D !P/E MTRR -> PAT disable Disabled BIOS + !M !P/E MTRR stub -> PAT disable Disabled BIOS + ==== ===== ========================== ========= ======= + + Legend + + ========= ======================================= + E Feature enabled in CPU + D Feature disabled/unsupported in CPU + np "nopat" boot option specified + !P CONFIG_X86_PAT option unset + !M CONFIG_MTRR option unset + Enabled PAT state set to enabled + Disabled PAT state set to disabled + OS PAT initializes PAT MSR with OS setting + BIOS PAT keeps PAT MSR with BIOS setting + ========= ======================================= + diff --git a/Documentation/x86/pat.txt b/Documentation/x86/pat.txt deleted file mode 100644 index 481d8d8536ac..000000000000 --- a/Documentation/x86/pat.txt +++ /dev/null @@ -1,230 +0,0 @@ - -PAT (Page Attribute Table) - -x86 Page Attribute Table (PAT) allows for setting the memory attribute at the -page level granularity. PAT is complementary to the MTRR settings which allows -for setting of memory types over physical address ranges. However, PAT is -more flexible than MTRR due to its capability to set attributes at page level -and also due to the fact that there are no hardware limitations on number of -such attribute settings allowed. Added flexibility comes with guidelines for -not having memory type aliasing for the same physical memory with multiple -virtual addresses. - -PAT allows for different types of memory attributes. The most commonly used -ones that will be supported at this time are Write-back, Uncached, -Write-combined, Write-through and Uncached Minus. - - -PAT APIs --------- - -There are many different APIs in the kernel that allows setting of memory -attributes at the page level. In order to avoid aliasing, these interfaces -should be used thoughtfully. Below is a table of interfaces available, -their intended usage and their memory attribute relationships. Internally, -these APIs use a reserve_memtype()/free_memtype() interface on the physical -address range to avoid any aliasing. - - -------------------------------------------------------------------- -API | RAM | ACPI,... | Reserved/Holes | ------------------------|----------|------------|------------------| - | | | | -ioremap | -- | UC- | UC- | - | | | | -ioremap_cache | -- | WB | WB | - | | | | -ioremap_uc | -- | UC | UC | - | | | | -ioremap_nocache | -- | UC- | UC- | - | | | | -ioremap_wc | -- | -- | WC | - | | | | -ioremap_wt | -- | -- | WT | - | | | | -set_memory_uc | UC- | -- | -- | - set_memory_wb | | | | - | | | | -set_memory_wc | WC | -- | -- | - set_memory_wb | | | | - | | | | -set_memory_wt | WT | -- | -- | - set_memory_wb | | | | - | | | | -pci sysfs resource | -- | -- | UC- | - | | | | -pci sysfs resource_wc | -- | -- | WC | - is IORESOURCE_PREFETCH| | | | - | | | | -pci proc | -- | -- | UC- | - !PCIIOC_WRITE_COMBINE | | | | - | | | | -pci proc | -- | -- | WC | - PCIIOC_WRITE_COMBINE | | | | - | | | | -/dev/mem | -- | WB/WC/UC- | WB/WC/UC- | - read-write | | | | - | | | | -/dev/mem | -- | UC- | UC- | - mmap SYNC flag | | | | - | | | | -/dev/mem | -- | WB/WC/UC- | WB/WC/UC- | - mmap !SYNC flag | |(from exist-| (from exist- | - and | | ing alias)| ing alias) | - any alias to this area| | | | - | | | | -/dev/mem | -- | WB | WB | - mmap !SYNC flag | | | | - no alias to this area | | | | - and | | | | - MTRR says WB | | | | - | | | | -/dev/mem | -- | -- | UC- | - mmap !SYNC flag | | | | - no alias to this area | | | | - and | | | | - MTRR says !WB | | | | - | | | | -------------------------------------------------------------------- - -Advanced APIs for drivers -------------------------- -A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range, -vmf_insert_pfn - -Drivers wanting to export some pages to userspace do it by using mmap -interface and a combination of -1) pgprot_noncached() -2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn() - -With PAT support, a new API pgprot_writecombine is being added. So, drivers can -continue to use the above sequence, with either pgprot_noncached() or -pgprot_writecombine() in step 1, followed by step 2. - -In addition, step 2 internally tracks the region as UC or WC in memtype -list in order to ensure no conflicting mapping. - -Note that this set of APIs only works with IO (non RAM) regions. If driver -wants to export a RAM region, it has to do set_memory_uc() or set_memory_wc() -as step 0 above and also track the usage of those pages and use set_memory_wb() -before the page is freed to free pool. - -MTRR effects on PAT / non-PAT systems -------------------------------------- - -The following table provides the effects of using write-combining MTRRs when -using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally -mtrr_add() usage will be phased out in favor of arch_phys_wc_add() which will -be a no-op on PAT enabled systems. The region over which a arch_phys_wc_add() -is made, should already have been ioremapped with WC attributes or PAT entries, -this can be done by using ioremap_wc() / set_memory_wc(). Devices which -combine areas of IO memory desired to remain uncacheable with areas where -write-combining is desirable should consider use of ioremap_uc() followed by -set_memory_wc() to white-list effective write-combined areas. Such use is -nevertheless discouraged as the effective memory type is considered -implementation defined, yet this strategy can be used as last resort on devices -with size-constrained regions where otherwise MTRR write-combining would -otherwise not be effective. - ----------------------------------------------------------------------- -MTRR Non-PAT PAT Linux ioremap value Effective memory type ----------------------------------------------------------------------- - Non-PAT | PAT - PAT - |PCD - ||PWT - ||| -WC 000 WB _PAGE_CACHE_MODE_WB WC | WC -WC 001 WC _PAGE_CACHE_MODE_WC WC* | WC -WC 010 UC- _PAGE_CACHE_MODE_UC_MINUS WC* | UC -WC 011 UC _PAGE_CACHE_MODE_UC UC | UC ----------------------------------------------------------------------- - -(*) denotes implementation defined and is discouraged - -Notes: - --- in the above table mean "Not suggested usage for the API". Some of the --'s -are strictly enforced by the kernel. Some others are not really enforced -today, but may be enforced in future. - -For ioremap and pci access through /sys or /proc - The actual type returned -can be more restrictive, in case of any existing aliasing for that address. -For example: If there is an existing uncached mapping, a new ioremap_wc can -return uncached mapping in place of write-combine requested. - -set_memory_[uc|wc|wt] and set_memory_wb should be used in pairs, where driver -will first make a region uc, wc or wt and switch it back to wb after use. - -Over time writes to /proc/mtrr will be deprecated in favor of using PAT based -interfaces. Users writing to /proc/mtrr are suggested to use above interfaces. - -Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] access -types. - -Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges. - - -PAT debugging -------------- - -With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by - -# mount -t debugfs debugfs /sys/kernel/debug -# cat /sys/kernel/debug/x86/pat_memtype_list -PAT memtype list: -uncached-minus @ 0x7fadf000-0x7fae0000 -uncached-minus @ 0x7fb19000-0x7fb1a000 -uncached-minus @ 0x7fb1a000-0x7fb1b000 -uncached-minus @ 0x7fb1b000-0x7fb1c000 -uncached-minus @ 0x7fb1c000-0x7fb1d000 -uncached-minus @ 0x7fb1d000-0x7fb1e000 -uncached-minus @ 0x7fb1e000-0x7fb25000 -uncached-minus @ 0x7fb25000-0x7fb26000 -uncached-minus @ 0x7fb26000-0x7fb27000 -uncached-minus @ 0x7fb27000-0x7fb28000 -uncached-minus @ 0x7fb28000-0x7fb2e000 -uncached-minus @ 0x7fb2e000-0x7fb2f000 -uncached-minus @ 0x7fb2f000-0x7fb30000 -uncached-minus @ 0x7fb31000-0x7fb32000 -uncached-minus @ 0x80000000-0x90000000 - -This list shows physical address ranges and various PAT settings used to -access those physical address ranges. - -Another, more verbose way of getting PAT related debug messages is with -"debugpat" boot parameter. With this parameter, various debug messages are -printed to dmesg log. - -PAT Initialization ------------------- - -The following table describes how PAT is initialized under various -configurations. The PAT MSR must be updated by Linux in order to support WC -and WT attributes. Otherwise, the PAT MSR has the value programmed in it -by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests. - - MTRR PAT Call Sequence PAT State PAT MSR - ========================================================= - E E MTRR -> PAT init Enabled OS - E D MTRR -> PAT init Disabled - - D E MTRR -> PAT disable Disabled BIOS - D D MTRR -> PAT disable Disabled - - - np/E PAT -> PAT disable Disabled BIOS - - np/D PAT -> PAT disable Disabled - - E !P/E MTRR -> PAT init Disabled BIOS - D !P/E MTRR -> PAT disable Disabled BIOS - !M !P/E MTRR stub -> PAT disable Disabled BIOS - - Legend - ------------------------------------------------ - E Feature enabled in CPU - D Feature disabled/unsupported in CPU - np "nopat" boot option specified - !P CONFIG_X86_PAT option unset - !M CONFIG_MTRR option unset - Enabled PAT state set to enabled - Disabled PAT state set to disabled - OS PAT initializes PAT MSR with OS setting - BIOS PAT keeps PAT MSR with BIOS setting - diff --git a/Documentation/x86/protection-keys.txt b/Documentation/x86/protection-keys.rst index ecb0d2dadfb7..49d9833af871 100644 --- a/Documentation/x86/protection-keys.txt +++ b/Documentation/x86/protection-keys.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +Memory Protection Keys +====================== + Memory Protection Keys for Userspace (PKU aka PKEYs) is a feature which is found on Intel's Skylake "Scalable Processor" Server CPUs. It will be avalable in future non-server parts. @@ -23,9 +29,10 @@ even though there is theoretically space in the PAE PTEs. These permissions are enforced on data access only and have no effect on instruction fetches. -=========================== Syscalls =========================== +Syscalls +======== -There are 3 system calls which directly interact with pkeys: +There are 3 system calls which directly interact with pkeys:: int pkey_alloc(unsigned long flags, unsigned long init_access_rights) int pkey_free(int pkey); @@ -37,6 +44,7 @@ pkey_alloc(). An application calls the WRPKRU instruction directly in order to change access permissions to memory covered with a key. In this example WRPKRU is wrapped by a C function called pkey_set(). +:: int real_prot = PROT_READ|PROT_WRITE; pkey = pkey_alloc(0, PKEY_DISABLE_WRITE); @@ -45,43 +53,44 @@ called pkey_set(). ... application runs here Now, if the application needs to update the data at 'ptr', it can -gain access, do the update, then remove its write access: +gain access, do the update, then remove its write access:: pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE *ptr = foo; // assign something pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again Now when it frees the memory, it will also free the pkey since it -is no longer in use: +is no longer in use:: munmap(ptr, PAGE_SIZE); pkey_free(pkey); -(Note: pkey_set() is a wrapper for the RDPKRU and WRPKRU instructions. - An example implementation can be found in - tools/testing/selftests/x86/protection_keys.c) +.. note:: pkey_set() is a wrapper for the RDPKRU and WRPKRU instructions. + An example implementation can be found in + tools/testing/selftests/x86/protection_keys.c. -=========================== Behavior =========================== +Behavior +======== The kernel attempts to make protection keys consistent with the -behavior of a plain mprotect(). For instance if you do this: +behavior of a plain mprotect(). For instance if you do this:: mprotect(ptr, size, PROT_NONE); something(ptr); -you can expect the same effects with protection keys when doing this: +you can expect the same effects with protection keys when doing this:: pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ); pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey); something(ptr); That should be true whether something() is a direct access to 'ptr' -like: +like:: *ptr = foo; or when the kernel does the access on the application's behalf like -with a read(): +with a read():: read(fd, ptr, 1); diff --git a/Documentation/x86/pti.txt b/Documentation/x86/pti.rst index 5cd58439ad2d..4b858a9bad8d 100644 --- a/Documentation/x86/pti.txt +++ b/Documentation/x86/pti.rst @@ -1,9 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +Page Table Isolation (PTI) +========================== + Overview ======== -Page Table Isolation (pti, previously known as KAISER[1]) is a +Page Table Isolation (pti, previously known as KAISER [1]_) is a countermeasure against attacks on the shared user/kernel address -space such as the "Meltdown" approach[2]. +space such as the "Meltdown" approach [2]_. To mitigate this class of attacks, we create an independent set of page tables for use only when running userspace applications. When @@ -60,6 +66,7 @@ Protection against side-channel attacks is important. But, this protection comes at a cost: 1. Increased Memory Use + a. Each process now needs an order-1 PGD instead of order-0. (Consumes an additional 4k per process). b. The 'cpu_entry_area' structure must be 2MB in size and 2MB @@ -68,6 +75,7 @@ this protection comes at a cost: is decompressed, but no space in the kernel image itself. 2. Runtime Cost + a. CR3 manipulation to switch between the page table copies must be done at interrupt, syscall, and exception entry and exit (it can be skipped when the kernel is interrupted, @@ -142,6 +150,7 @@ ideally doing all of these in parallel: interrupted, including nested NMIs. Using "-c" boosts the rate of NMIs, and using two -c with separate counters encourages nested NMIs and less deterministic behavior. + :: while true; do perf record -c 10000 -e instructions,cycles -a sleep 10; done @@ -182,5 +191,5 @@ that are worth noting here. tended to be TLB invalidation issues. Usually invalidating the wrong PCID, or otherwise missing an invalidation. -1. https://gruss.cc/files/kaiser.pdf -2. https://meltdownattack.com/meltdown.pdf +.. [1] https://gruss.cc/files/kaiser.pdf +.. [2] https://meltdownattack.com/meltdown.pdf diff --git a/Documentation/x86/resctrl_ui.txt b/Documentation/x86/resctrl_ui.rst index c1f95b59e14d..225cfd4daaee 100644 --- a/Documentation/x86/resctrl_ui.txt +++ b/Documentation/x86/resctrl_ui.rst @@ -1,33 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=========================================== User Interface for Resource Control feature +=========================================== -Intel refers to this feature as Intel Resource Director Technology(Intel(R) RDT). -AMD refers to this feature as AMD Platform Quality of Service(AMD QoS). +:Copyright: |copy| 2016 Intel Corporation +:Authors: - Fenghua Yu <fenghua.yu@intel.com> + - Tony Luck <tony.luck@intel.com> + - Vikas Shivappa <vikas.shivappa@intel.com> -Copyright (C) 2016 Intel Corporation -Fenghua Yu <fenghua.yu@intel.com> -Tony Luck <tony.luck@intel.com> -Vikas Shivappa <vikas.shivappa@intel.com> +Intel refers to this feature as Intel Resource Director Technology(Intel(R) RDT). +AMD refers to this feature as AMD Platform Quality of Service(AMD QoS). This feature is enabled by the CONFIG_X86_CPU_RESCTRL and the x86 /proc/cpuinfo flag bits: -RDT (Resource Director Technology) Allocation - "rdt_a" -CAT (Cache Allocation Technology) - "cat_l3", "cat_l2" -CDP (Code and Data Prioritization ) - "cdp_l3", "cdp_l2" -CQM (Cache QoS Monitoring) - "cqm_llc", "cqm_occup_llc" -MBM (Memory Bandwidth Monitoring) - "cqm_mbm_total", "cqm_mbm_local" -MBA (Memory Bandwidth Allocation) - "mba" -To use the feature mount the file system: +============================================= ================================ +RDT (Resource Director Technology) Allocation "rdt_a" +CAT (Cache Allocation Technology) "cat_l3", "cat_l2" +CDP (Code and Data Prioritization) "cdp_l3", "cdp_l2" +CQM (Cache QoS Monitoring) "cqm_llc", "cqm_occup_llc" +MBM (Memory Bandwidth Monitoring) "cqm_mbm_total", "cqm_mbm_local" +MBA (Memory Bandwidth Allocation) "mba" +============================================= ================================ + +To use the feature mount the file system:: # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl mount options are: -"cdp": Enable code/data prioritization in L3 cache allocations. -"cdpl2": Enable code/data prioritization in L2 cache allocations. -"mba_MBps": Enable the MBA Software Controller(mba_sc) to specify MBA - bandwidth in MBps +"cdp": + Enable code/data prioritization in L3 cache allocations. +"cdpl2": + Enable code/data prioritization in L2 cache allocations. +"mba_MBps": + Enable the MBA Software Controller(mba_sc) to specify MBA + bandwidth in MBps L2 and L3 CDP are controlled seperately. @@ -44,7 +55,7 @@ For more details on the behavior of the interface during monitoring and allocation, see the "Resource alloc and monitor groups" section. Info directory --------------- +============== The 'info' directory contains information about the enabled resources. Each resource has its own subdirectory. The subdirectory @@ -56,77 +67,93 @@ allocation: Cache resource(L3/L2) subdirectory contains the following files related to allocation: -"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%. - -"min_cbm_bits": The minimum number of consecutive bits which - must be set when writing a mask. - -"shareable_bits": Bitmask of shareable resource with other executing - entities (e.g. I/O). User can use this when - setting up exclusive cache partitions. Note that - some platforms support devices that have their - own settings for cache use which can over-ride - these bits. -"bit_usage": Annotated capacity bitmasks showing how all - instances of the resource are used. The legend is: - "0" - Corresponding region is unused. When the system's +"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%. +"min_cbm_bits": + The minimum number of consecutive bits which + must be set when writing a mask. + +"shareable_bits": + Bitmask of shareable resource with other executing + entities (e.g. I/O). User can use this when + setting up exclusive cache partitions. Note that + some platforms support devices that have their + own settings for cache use which can over-ride + these bits. +"bit_usage": + Annotated capacity bitmasks showing how all + instances of the resource are used. The legend is: + + "0": + Corresponding region is unused. When the system's resources have been allocated and a "0" is found in "bit_usage" it is a sign that resources are wasted. - "H" - Corresponding region is used by hardware only + + "H": + Corresponding region is used by hardware only but available for software use. If a resource has bits set in "shareable_bits" but not all of these bits appear in the resource groups' schematas then the bits appearing in "shareable_bits" but no resource group will be marked as "H". - "X" - Corresponding region is available for sharing and + "X": + Corresponding region is available for sharing and used by hardware and software. These are the bits that appear in "shareable_bits" as well as a resource group's allocation. - "S" - Corresponding region is used by software + "S": + Corresponding region is used by software and available for sharing. - "E" - Corresponding region is used exclusively by + "E": + Corresponding region is used exclusively by one resource group. No sharing allowed. - "P" - Corresponding region is pseudo-locked. No + "P": + Corresponding region is pseudo-locked. No sharing allowed. Memory bandwitdh(MB) subdirectory contains the following files with respect to allocation: -"min_bandwidth": The minimum memory bandwidth percentage which - user can request. +"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. +"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. +"delay_linear": + Indicates if the delay scale is linear or + non-linear. This field is purely informational + only. If RDT monitoring is available there will be an "L3_MON" directory with the following files: -"num_rmids": The number of RMIDs available. This is the - upper bound for how many "CTRL_MON" + "MON" - groups can be created. +"num_rmids": + The number of RMIDs available. This is the + upper bound for how many "CTRL_MON" + "MON" + groups can be created. -"mon_features": Lists the monitoring events if - monitoring is enabled for the resource. +"mon_features": + Lists the monitoring events if + monitoring is enabled for the resource. "max_threshold_occupancy": - Read/write file provides the largest value (in - bytes) at which a previously used LLC_occupancy - counter can be considered for re-use. + Read/write file provides the largest value (in + bytes) at which a previously used LLC_occupancy + counter can be considered for re-use. Finally, in the top level of the "info" directory there is a file named "last_cmd_status". This is reset with every "command" issued @@ -134,6 +161,7 @@ via the file system (making new directories or writing to any of the control files). If the command was successful, it will read as "ok". If the command failed, it will provide more information that can be conveyed in the error returns from file operations. E.g. +:: # echo L3:0=f7 > schemata bash: echo: write error: Invalid argument @@ -141,7 +169,7 @@ conveyed in the error returns from file operations. E.g. mask f7 has non-consecutive 1-bits Resource alloc and monitor groups ---------------------------------- +================================= Resource groups are represented as directories in the resctrl file system. The default group is the root directory which, immediately @@ -226,6 +254,7 @@ When monitoring is enabled all MON groups will also contain: Resource allocation rules ------------------------- + When a task is running the following rules define which resources are available to it: @@ -252,7 +281,7 @@ Resource monitoring rules Notes on cache occupancy monitoring and control ------------------------------------------------ +=============================================== When moving a task from one group to another you should remember that this only affects *new* cache allocations by the task. E.g. you may have a task in a monitor group showing 3 MB of cache occupancy. If you move @@ -321,7 +350,7 @@ of the capacity of the cache. You could partition the cache into four equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. Memory bandwidth Allocation and monitoring ------------------------------------------- +========================================== For Memory bandwidth resource, by default the user controls the resource by indicating the percentage of total memory bandwidth. @@ -369,7 +398,7 @@ In order to mitigate this and make the interface more user friendly, resctrl added support for specifying the bandwidth in MBps as well. The kernel underneath would use a software feedback mechanism or a "Software Controller(mba_sc)" which reads the actual bandwidth using MBM counters -and adjust the memowy bandwidth percentages to ensure +and adjust the memowy bandwidth percentages to ensure:: "actual bandwidth < user specified bandwidth". @@ -380,14 +409,14 @@ sections. L3 schemata file details (code and data prioritization disabled) ---------------------------------------------------------------- -With CDP disabled the L3 schemata format is: +With CDP disabled the L3 schemata format is:: L3:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... L3 schemata file details (CDP enabled via mount option to resctrl) ------------------------------------------------------------------ When CDP is enabled L3 control is split into two separate resources -so you can specify independent masks for code and data like this: +so you can specify independent masks for code and data like this:: L3data:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... L3code:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... @@ -395,7 +424,7 @@ so you can specify independent masks for code and data like this: L2 schemata file details ------------------------ L2 cache does not support code and data prioritization, so the -schemata format is always: +schemata format is always:: L2:<cache_id0>=<cbm>;<cache_id1>=<cbm>;... @@ -403,6 +432,7 @@ Memory bandwidth Allocation (default mode) ------------------------------------------ Memory b/w domain is L3 cache. +:: MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;... @@ -410,6 +440,7 @@ Memory bandwidth Allocation specified in MBps --------------------------------------------- Memory bandwidth domain is L3 cache. +:: MB:<cache_id0>=bw_MBps0;<cache_id1>=bw_MBps1;... @@ -418,17 +449,18 @@ 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 + # 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 Cache Pseudo-Locking --------------------- +==================== CAT enables a user to specify the amount of cache space that an application can fill. Cache pseudo-locking builds on the fact that a CPU can still read and write data pre-allocated outside its current @@ -442,6 +474,7 @@ a region of memory with reduced average read latency. The creation of a cache pseudo-locked region is triggered by a request from the user to do so that is accompanied by a schemata of the region to be pseudo-locked. The cache pseudo-locked region is created as follows: + - Create a CAT allocation CLOSNEW with a CBM matching the schemata from the user of the cache region that will contain the pseudo-locked memory. This region must not overlap with any current CAT allocation/CLOS @@ -480,6 +513,7 @@ initial mmap() handling, there is no enforcement afterwards and the application self needs to ensure it remains affine to the correct cores. Pseudo-locking is accomplished in two stages: + 1) During the first stage the system administrator allocates a portion of cache that should be dedicated to pseudo-locking. At this time an equivalent portion of memory is allocated, loaded into allocated @@ -506,7 +540,7 @@ by user space in order to obtain access to the pseudo-locked memory region. An example of cache pseudo-locked region creation and usage can be found below. Cache Pseudo-Locking Debugging Interface ---------------------------------------- +---------------------------------------- The pseudo-locking debugging interface is enabled by default (if CONFIG_DEBUG_FS is enabled) and can be found in /sys/kernel/debug/resctrl. @@ -514,6 +548,7 @@ There is no explicit way for the kernel to test if a provided memory location is present in the cache. The pseudo-locking debugging interface uses the tracing infrastructure to provide two ways to measure cache residency of the pseudo-locked region: + 1) Memory access latency using the pseudo_lock_mem_latency tracepoint. Data from these measurements are best visualized using a hist trigger (see example below). In this test the pseudo-locked region is traversed at @@ -529,87 +564,97 @@ it in debugfs as /sys/kernel/debug/resctrl/<newdir>. A single write-only file, pseudo_lock_measure, is present in this directory. The measurement of the pseudo-locked region depends on the number written to this debugfs file: -1 - writing "1" to the pseudo_lock_measure file will trigger the latency + +1: + writing "1" to the pseudo_lock_measure file will trigger the latency measurement captured in the pseudo_lock_mem_latency tracepoint. See example below. -2 - writing "2" to the pseudo_lock_measure file will trigger the L2 cache +2: + writing "2" to the pseudo_lock_measure file will trigger the L2 cache residency (cache hits and misses) measurement captured in the pseudo_lock_l2 tracepoint. See example below. -3 - writing "3" to the pseudo_lock_measure file will trigger the L3 cache +3: + writing "3" to the pseudo_lock_measure file will trigger the L3 cache residency (cache hits and misses) measurement captured in the pseudo_lock_l3 tracepoint. All measurements are recorded with the tracing infrastructure. This requires the relevant tracepoints to be enabled before the measurement is triggered. -Example of latency debugging interface: +Example of latency debugging interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In this example a pseudo-locked region named "newlock" was created. Here is how we can measure the latency in cycles of reading from this region and visualize this data with a histogram that is available if CONFIG_HIST_TRIGGERS -is set: -# :> /sys/kernel/debug/tracing/trace -# echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger -# echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable -# echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure -# echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable -# cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist - -# event histogram -# -# trigger info: hist:keys=latency:vals=hitcount:sort=hitcount:size=2048 [active] -# - -{ latency: 456 } hitcount: 1 -{ latency: 50 } hitcount: 83 -{ latency: 36 } hitcount: 96 -{ latency: 44 } hitcount: 174 -{ latency: 48 } hitcount: 195 -{ latency: 46 } hitcount: 262 -{ latency: 42 } hitcount: 693 -{ latency: 40 } hitcount: 3204 -{ latency: 38 } hitcount: 3484 - -Totals: - Hits: 8192 - Entries: 9 - Dropped: 0 - -Example of cache hits/misses debugging: +is set:: + + # :> /sys/kernel/debug/tracing/trace + # echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger + # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable + # echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure + # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable + # cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist + + # event histogram + # + # trigger info: hist:keys=latency:vals=hitcount:sort=hitcount:size=2048 [active] + # + + { latency: 456 } hitcount: 1 + { latency: 50 } hitcount: 83 + { latency: 36 } hitcount: 96 + { latency: 44 } hitcount: 174 + { latency: 48 } hitcount: 195 + { latency: 46 } hitcount: 262 + { latency: 42 } hitcount: 693 + { latency: 40 } hitcount: 3204 + { latency: 38 } hitcount: 3484 + + Totals: + Hits: 8192 + Entries: 9 + Dropped: 0 + +Example of cache hits/misses debugging +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In this example a pseudo-locked region named "newlock" was created on the L2 cache of a platform. Here is how we can obtain details of the cache hits and misses using the platform's precision counters. +:: -# :> /sys/kernel/debug/tracing/trace -# echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable -# echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure -# echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable -# cat /sys/kernel/debug/tracing/trace + # :> /sys/kernel/debug/tracing/trace + # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable + # echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure + # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable + # cat /sys/kernel/debug/tracing/trace -# tracer: nop -# -# _-----=> irqs-off -# / _----=> need-resched -# | / _---=> hardirq/softirq -# || / _--=> preempt-depth -# ||| / delay -# TASK-PID CPU# |||| TIMESTAMP FUNCTION -# | | | |||| | | - pseudo_lock_mea-1672 [002] .... 3132.860500: pseudo_lock_l2: hits=4097 miss=0 + # tracer: nop + # + # _-----=> irqs-off + # / _----=> need-resched + # | / _---=> hardirq/softirq + # || / _--=> preempt-depth + # ||| / delay + # TASK-PID CPU# |||| TIMESTAMP FUNCTION + # | | | |||| | | + pseudo_lock_mea-1672 [002] .... 3132.860500: pseudo_lock_l2: hits=4097 miss=0 -Examples for RDT allocation usage: +Examples for RDT allocation usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1) Example 1 -Example 1 ---------- On a two socket machine (one L3 cache per socket) with just four bits for cache bit masks, minimum b/w of 10% with a memory bandwidth -granularity of 10% +granularity of 10%. +:: -# mount -t resctrl resctrl /sys/fs/resctrl -# cd /sys/fs/resctrl -# mkdir p0 p1 -# 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 + # mount -t resctrl resctrl /sys/fs/resctrl + # cd /sys/fs/resctrl + # mkdir p0 p1 + # 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"). @@ -628,100 +673,106 @@ the b/w accordingly. If the MBA is specified in MB(megabytes) then user can enter the max b/w in MB rather than the percentage values. +:: -# echo "L3:0=3;1=c\nMB:0=1024;1=500" > /sys/fs/resctrl/p0/schemata -# echo "L3:0=3;1=3\nMB:0=1024;1=500" > /sys/fs/resctrl/p1/schemata + # echo "L3:0=3;1=c\nMB:0=1024;1=500" > /sys/fs/resctrl/p0/schemata + # echo "L3:0=3;1=3\nMB:0=1024;1=500" > /sys/fs/resctrl/p1/schemata In the above example the tasks in "p1" and "p0" on socket 0 would use a max b/w of 1024MB where as on socket 1 they would use 500MB. -Example 2 ---------- +2) Example 2 + Again two sockets, but this time with a more realistic 20-bit mask. Two real time tasks pid=1234 running on processor 0 and pid=5678 running on processor 1 on socket 0 on a 2-socket and dual core machine. To avoid noisy neighbors, each of the two real-time tasks exclusively occupies one quarter of L3 cache on socket 0. +:: -# mount -t resctrl resctrl /sys/fs/resctrl -# cd /sys/fs/resctrl + # mount -t resctrl resctrl /sys/fs/resctrl + # 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 and 50% of memory b/w cannot be used by -ordinary tasks: +ordinary tasks:: -# echo "L3:0=3ff;1=fffff\nMB:0=50;1=100" > 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. +:: -# mkdir p0 -# echo "L3:0=f8000;1=fffff" > p0/schemata + # mkdir p0 + # echo "L3:0=f8000;1=fffff" > p0/schemata Finally we move our first real time task into this resource group. We also use taskset(1) to ensure the task always runs on a dedicated CPU on socket 0. Most uses of resource groups will also constrain which processors tasks run on. +:: -# echo 1234 > p0/tasks -# taskset -cp 1 1234 + # echo 1234 > p0/tasks + # taskset -cp 1 1234 -Ditto for the second real time task (with the remaining 25% of cache): +Ditto for the second real time task (with the remaining 25% of cache):: -# mkdir p1 -# echo "L3:0=7c00;1=fffff" > p1/schemata -# echo 5678 > p1/tasks -# taskset -cp 2 5678 + # mkdir p1 + # echo "L3:0=7c00;1=fffff" > p1/schemata + # 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. +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 + # 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 + # echo -e "L3:0=f8000;1=fffff\nMB:0=20;1=100" > p0/schemata -Example 3 ---------- +3) Example 3 A single socket system which has real-time tasks running on core 4-7 and non real-time workload assigned to core 0-3. The real-time tasks share text and data, so a per task association is not required and due to interaction with the kernel it's desired that the kernel on these cores shares L3 with the tasks. +:: -# mount -t resctrl resctrl /sys/fs/resctrl -# cd /sys/fs/resctrl + # mount -t resctrl resctrl /sys/fs/resctrl + # 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, and 50% of memory bandwidth on socket 0 -cannot be used by ordinary tasks: +cannot be used by ordinary tasks:: -# echo "L3:0=3ff\nMB:0=50" > 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 and 50% of memory bandwidth on socket 0. +:: -# mkdir p0 -# echo "L3:0=ffc00\nMB:0=50" > p0/schemata + # mkdir p0 + # 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. 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 F0 > p0/cpus + # echo F0 > p0/cpus -Example 4 ---------- +4) Example 4 The resource groups in previous examples were all in the default "shareable" mode allowing sharing of their cache allocations. If one resource group @@ -732,157 +783,168 @@ In this example a new exclusive resource group will be created on a L2 CAT system with two L2 cache instances that can be configured with an 8-bit capacity bitmask. The new exclusive resource group will be configured to use 25% of each cache instance. +:: -# mount -t resctrl resctrl /sys/fs/resctrl/ -# cd /sys/fs/resctrl + # mount -t resctrl resctrl /sys/fs/resctrl/ + # cd /sys/fs/resctrl First, we observe that the default group is configured to allocate to all L2 -cache: +cache:: -# cat schemata -L2:0=ff;1=ff + # cat schemata + L2:0=ff;1=ff We could attempt to create the new resource group at this point, but it will -fail because of the overlap with the schemata of the default group: -# mkdir p0 -# echo 'L2:0=0x3;1=0x3' > p0/schemata -# cat p0/mode -shareable -# echo exclusive > p0/mode --sh: echo: write error: Invalid argument -# cat info/last_cmd_status -schemata overlaps +fail because of the overlap with the schemata of the default group:: + + # mkdir p0 + # echo 'L2:0=0x3;1=0x3' > p0/schemata + # cat p0/mode + shareable + # echo exclusive > p0/mode + -sh: echo: write error: Invalid argument + # cat info/last_cmd_status + schemata overlaps To ensure that there is no overlap with another resource group the default resource group's schemata has to change, making it possible for the new resource group to become exclusive. -# echo 'L2:0=0xfc;1=0xfc' > schemata -# echo exclusive > p0/mode -# grep . p0/* -p0/cpus:0 -p0/mode:exclusive -p0/schemata:L2:0=03;1=03 -p0/size:L2:0=262144;1=262144 +:: + + # echo 'L2:0=0xfc;1=0xfc' > schemata + # echo exclusive > p0/mode + # grep . p0/* + p0/cpus:0 + p0/mode:exclusive + p0/schemata:L2:0=03;1=03 + p0/size:L2:0=262144;1=262144 A new resource group will on creation not overlap with an exclusive resource -group: -# mkdir p1 -# grep . p1/* -p1/cpus:0 -p1/mode:shareable -p1/schemata:L2:0=fc;1=fc -p1/size:L2:0=786432;1=786432 - -The bit_usage will reflect how the cache is used: -# cat info/L2/bit_usage -0=SSSSSSEE;1=SSSSSSEE - -A resource group cannot be forced to overlap with an exclusive resource group: -# echo 'L2:0=0x1;1=0x1' > p1/schemata --sh: echo: write error: Invalid argument -# cat info/last_cmd_status -overlaps with exclusive group +group:: + + # mkdir p1 + # grep . p1/* + p1/cpus:0 + p1/mode:shareable + p1/schemata:L2:0=fc;1=fc + p1/size:L2:0=786432;1=786432 + +The bit_usage will reflect how the cache is used:: + + # cat info/L2/bit_usage + 0=SSSSSSEE;1=SSSSSSEE + +A resource group cannot be forced to overlap with an exclusive resource group:: + + # echo 'L2:0=0x1;1=0x1' > p1/schemata + -sh: echo: write error: Invalid argument + # cat info/last_cmd_status + overlaps with exclusive group Example of Cache Pseudo-Locking -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Lock portion of L2 cache from cache id 1 using CBM 0x3. Pseudo-locked region is exposed at /dev/pseudo_lock/newlock that can be provided to application for argument to mmap(). +:: -# mount -t resctrl resctrl /sys/fs/resctrl/ -# cd /sys/fs/resctrl + # mount -t resctrl resctrl /sys/fs/resctrl/ + # cd /sys/fs/resctrl Ensure that there are bits available that can be pseudo-locked, since only unused bits can be pseudo-locked the bits to be pseudo-locked needs to be -removed from the default resource group's schemata: -# cat info/L2/bit_usage -0=SSSSSSSS;1=SSSSSSSS -# echo 'L2:1=0xfc' > schemata -# cat info/L2/bit_usage -0=SSSSSSSS;1=SSSSSS00 +removed from the default resource group's schemata:: + + # cat info/L2/bit_usage + 0=SSSSSSSS;1=SSSSSSSS + # echo 'L2:1=0xfc' > schemata + # cat info/L2/bit_usage + 0=SSSSSSSS;1=SSSSSS00 Create a new resource group that will be associated with the pseudo-locked region, indicate that it will be used for a pseudo-locked region, and -configure the requested pseudo-locked region capacity bitmask: +configure the requested pseudo-locked region capacity bitmask:: -# mkdir newlock -# echo pseudo-locksetup > newlock/mode -# echo 'L2:1=0x3' > newlock/schemata + # mkdir newlock + # echo pseudo-locksetup > newlock/mode + # echo 'L2:1=0x3' > newlock/schemata On success the resource group's mode will change to pseudo-locked, the bit_usage will reflect the pseudo-locked region, and the character device -exposing the pseudo-locked region will exist: - -# cat newlock/mode -pseudo-locked -# cat info/L2/bit_usage -0=SSSSSSSS;1=SSSSSSPP -# ls -l /dev/pseudo_lock/newlock -crw------- 1 root root 243, 0 Apr 3 05:01 /dev/pseudo_lock/newlock - -/* - * Example code to access one page of pseudo-locked cache region - * from user space. - */ -#define _GNU_SOURCE -#include <fcntl.h> -#include <sched.h> -#include <stdio.h> -#include <stdlib.h> -#include <unistd.h> -#include <sys/mman.h> - -/* - * It is required that the application runs with affinity to only - * cores associated with the pseudo-locked region. Here the cpu - * is hardcoded for convenience of example. - */ -static int cpuid = 2; - -int main(int argc, char *argv[]) -{ - cpu_set_t cpuset; - long page_size; - void *mapping; - int dev_fd; - int ret; - - page_size = sysconf(_SC_PAGESIZE); - - CPU_ZERO(&cpuset); - CPU_SET(cpuid, &cpuset); - ret = sched_setaffinity(0, sizeof(cpuset), &cpuset); - if (ret < 0) { - perror("sched_setaffinity"); - exit(EXIT_FAILURE); - } - - dev_fd = open("/dev/pseudo_lock/newlock", O_RDWR); - if (dev_fd < 0) { - perror("open"); - exit(EXIT_FAILURE); - } - - mapping = mmap(0, page_size, PROT_READ | PROT_WRITE, MAP_SHARED, - dev_fd, 0); - if (mapping == MAP_FAILED) { - perror("mmap"); - close(dev_fd); - exit(EXIT_FAILURE); - } - - /* Application interacts with pseudo-locked memory @mapping */ - - ret = munmap(mapping, page_size); - if (ret < 0) { - perror("munmap"); - close(dev_fd); - exit(EXIT_FAILURE); - } - - close(dev_fd); - exit(EXIT_SUCCESS); -} +exposing the pseudo-locked region will exist:: + + # cat newlock/mode + pseudo-locked + # cat info/L2/bit_usage + 0=SSSSSSSS;1=SSSSSSPP + # ls -l /dev/pseudo_lock/newlock + crw------- 1 root root 243, 0 Apr 3 05:01 /dev/pseudo_lock/newlock + +:: + + /* + * Example code to access one page of pseudo-locked cache region + * from user space. + */ + #define _GNU_SOURCE + #include <fcntl.h> + #include <sched.h> + #include <stdio.h> + #include <stdlib.h> + #include <unistd.h> + #include <sys/mman.h> + + /* + * It is required that the application runs with affinity to only + * cores associated with the pseudo-locked region. Here the cpu + * is hardcoded for convenience of example. + */ + static int cpuid = 2; + + int main(int argc, char *argv[]) + { + cpu_set_t cpuset; + long page_size; + void *mapping; + int dev_fd; + int ret; + + page_size = sysconf(_SC_PAGESIZE); + + CPU_ZERO(&cpuset); + CPU_SET(cpuid, &cpuset); + ret = sched_setaffinity(0, sizeof(cpuset), &cpuset); + if (ret < 0) { + perror("sched_setaffinity"); + exit(EXIT_FAILURE); + } + + dev_fd = open("/dev/pseudo_lock/newlock", O_RDWR); + if (dev_fd < 0) { + perror("open"); + exit(EXIT_FAILURE); + } + + mapping = mmap(0, page_size, PROT_READ | PROT_WRITE, MAP_SHARED, + dev_fd, 0); + if (mapping == MAP_FAILED) { + perror("mmap"); + close(dev_fd); + exit(EXIT_FAILURE); + } + + /* Application interacts with pseudo-locked memory @mapping */ + + ret = munmap(mapping, page_size); + if (ret < 0) { + perror("munmap"); + close(dev_fd); + exit(EXIT_FAILURE); + } + + close(dev_fd); + exit(EXIT_SUCCESS); + } Locking between applications ---------------------------- @@ -921,86 +983,86 @@ Read lock: B) If success read the directory structure. C) funlock -Example with bash: - -# Atomically read directory structure -$ flock -s /sys/fs/resctrl/ find /sys/fs/resctrl - -# Read directory contents and create new subdirectory - -$ cat create-dir.sh -find /sys/fs/resctrl/ > output.txt -mask = function-of(output.txt) -mkdir /sys/fs/resctrl/newres/ -echo mask > /sys/fs/resctrl/newres/schemata - -$ flock /sys/fs/resctrl/ ./create-dir.sh - -Example with C: - -/* - * Example code do take advisory locks - * before accessing resctrl filesystem - */ -#include <sys/file.h> -#include <stdlib.h> - -void resctrl_take_shared_lock(int fd) -{ - int ret; - - /* take shared lock on resctrl filesystem */ - ret = flock(fd, LOCK_SH); - if (ret) { - perror("flock"); - exit(-1); - } -} - -void resctrl_take_exclusive_lock(int fd) -{ - int ret; - - /* release lock on resctrl filesystem */ - ret = flock(fd, LOCK_EX); - if (ret) { - perror("flock"); - exit(-1); - } -} - -void resctrl_release_lock(int fd) -{ - int ret; - - /* take shared lock on resctrl filesystem */ - ret = flock(fd, LOCK_UN); - if (ret) { - perror("flock"); - exit(-1); - } -} - -void main(void) -{ - int fd, ret; - - fd = open("/sys/fs/resctrl", O_DIRECTORY); - if (fd == -1) { - perror("open"); - exit(-1); - } - resctrl_take_shared_lock(fd); - /* code to read directory contents */ - resctrl_release_lock(fd); - - resctrl_take_exclusive_lock(fd); - /* code to read and write directory contents */ - resctrl_release_lock(fd); -} - -Examples for RDT Monitoring along with allocation usage: - +Example with bash:: + + # Atomically read directory structure + $ flock -s /sys/fs/resctrl/ find /sys/fs/resctrl + + # Read directory contents and create new subdirectory + + $ cat create-dir.sh + find /sys/fs/resctrl/ > output.txt + mask = function-of(output.txt) + mkdir /sys/fs/resctrl/newres/ + echo mask > /sys/fs/resctrl/newres/schemata + + $ flock /sys/fs/resctrl/ ./create-dir.sh + +Example with C:: + + /* + * Example code do take advisory locks + * before accessing resctrl filesystem + */ + #include <sys/file.h> + #include <stdlib.h> + + void resctrl_take_shared_lock(int fd) + { + int ret; + + /* take shared lock on resctrl filesystem */ + ret = flock(fd, LOCK_SH); + if (ret) { + perror("flock"); + exit(-1); + } + } + + void resctrl_take_exclusive_lock(int fd) + { + int ret; + + /* release lock on resctrl filesystem */ + ret = flock(fd, LOCK_EX); + if (ret) { + perror("flock"); + exit(-1); + } + } + + void resctrl_release_lock(int fd) + { + int ret; + + /* take shared lock on resctrl filesystem */ + ret = flock(fd, LOCK_UN); + if (ret) { + perror("flock"); + exit(-1); + } + } + + void main(void) + { + int fd, ret; + + fd = open("/sys/fs/resctrl", O_DIRECTORY); + if (fd == -1) { + perror("open"); + exit(-1); + } + resctrl_take_shared_lock(fd); + /* code to read directory contents */ + resctrl_release_lock(fd); + + resctrl_take_exclusive_lock(fd); + /* code to read and write directory contents */ + resctrl_release_lock(fd); + } + +Examples for RDT Monitoring along with allocation usage +======================================================= Reading monitored data ---------------------- Reading an event file (for ex: mon_data/mon_L3_00/llc_occupancy) would @@ -1009,17 +1071,17 @@ group or CTRL_MON group. Example 1 (Monitor CTRL_MON group and subset of tasks in CTRL_MON group) ---------- +------------------------------------------------------------------------ On a two socket machine (one L3 cache per socket) with just four bits -for cache bit masks +for cache bit masks:: -# 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 5678 > p1/tasks -# echo 5679 > p1/tasks + # 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 5678 > p1/tasks + # echo 5679 > p1/tasks 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"). @@ -1029,47 +1091,51 @@ Tasks that are under the control of group "p0" may only allocate from the Tasks in group "p1" use the "lower" 50% of cache on both sockets. Create monitor groups and assign a subset of tasks to each monitor group. +:: -# cd /sys/fs/resctrl/p1/mon_groups -# mkdir m11 m12 -# echo 5678 > m11/tasks -# echo 5679 > m12/tasks + # cd /sys/fs/resctrl/p1/mon_groups + # mkdir m11 m12 + # echo 5678 > m11/tasks + # echo 5679 > m12/tasks fetch data (data shown in bytes) +:: -# cat m11/mon_data/mon_L3_00/llc_occupancy -16234000 -# cat m11/mon_data/mon_L3_01/llc_occupancy -14789000 -# cat m12/mon_data/mon_L3_00/llc_occupancy -16789000 + # cat m11/mon_data/mon_L3_00/llc_occupancy + 16234000 + # cat m11/mon_data/mon_L3_01/llc_occupancy + 14789000 + # cat m12/mon_data/mon_L3_00/llc_occupancy + 16789000 The parent ctrl_mon group shows the aggregated data. +:: -# cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy -31234000 + # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy + 31234000 Example 2 (Monitor a task from its creation) ---------- -On a two socket machine (one L3 cache per socket) +-------------------------------------------- +On a two socket machine (one L3 cache per socket):: -# mount -t resctrl resctrl /sys/fs/resctrl -# cd /sys/fs/resctrl -# mkdir p0 p1 + # mount -t resctrl resctrl /sys/fs/resctrl + # cd /sys/fs/resctrl + # mkdir p0 p1 An RMID is allocated to the group once its created and hence the <cmd> below is monitored from its creation. +:: -# echo $$ > /sys/fs/resctrl/p1/tasks -# <cmd> + # echo $$ > /sys/fs/resctrl/p1/tasks + # <cmd> -Fetch the data +Fetch the data:: -# cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy -31789000 + # cat /sys/fs/resctrl/p1/mon_data/mon_l3_00/llc_occupancy + 31789000 Example 3 (Monitor without CAT support or before creating CAT groups) ---------- +--------------------------------------------------------------------- Assume a system like HSW has only CQM and no CAT support. In this case the resctrl will still mount but cannot create CTRL_MON directories. @@ -1078,27 +1144,29 @@ able to monitor all tasks including kernel threads. This can also be used to profile jobs cache size footprint before being able to allocate them to different allocation groups. +:: -# mount -t resctrl resctrl /sys/fs/resctrl -# cd /sys/fs/resctrl -# mkdir mon_groups/m01 -# mkdir mon_groups/m02 + # mount -t resctrl resctrl /sys/fs/resctrl + # cd /sys/fs/resctrl + # mkdir mon_groups/m01 + # mkdir mon_groups/m02 -# echo 3478 > /sys/fs/resctrl/mon_groups/m01/tasks -# echo 2467 > /sys/fs/resctrl/mon_groups/m02/tasks + # echo 3478 > /sys/fs/resctrl/mon_groups/m01/tasks + # echo 2467 > /sys/fs/resctrl/mon_groups/m02/tasks Monitor the groups separately and also get per domain data. From the below its apparent that the tasks are mostly doing work on domain(socket) 0. +:: -# cat /sys/fs/resctrl/mon_groups/m01/mon_L3_00/llc_occupancy -31234000 -# cat /sys/fs/resctrl/mon_groups/m01/mon_L3_01/llc_occupancy -34555 -# cat /sys/fs/resctrl/mon_groups/m02/mon_L3_00/llc_occupancy -31234000 -# cat /sys/fs/resctrl/mon_groups/m02/mon_L3_01/llc_occupancy -32789 + # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_00/llc_occupancy + 31234000 + # cat /sys/fs/resctrl/mon_groups/m01/mon_L3_01/llc_occupancy + 34555 + # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_00/llc_occupancy + 31234000 + # cat /sys/fs/resctrl/mon_groups/m02/mon_L3_01/llc_occupancy + 32789 Example 4 (Monitor real time tasks) @@ -1107,15 +1175,17 @@ Example 4 (Monitor real time tasks) A single socket system which has real time tasks running on cores 4-7 and non real time tasks on other cpus. We want to monitor the cache occupancy of the real time threads on these cores. +:: + + # mount -t resctrl resctrl /sys/fs/resctrl + # cd /sys/fs/resctrl + # mkdir p1 -# mount -t resctrl resctrl /sys/fs/resctrl -# cd /sys/fs/resctrl -# mkdir p1 +Move the cpus 4-7 over to p1:: -Move the cpus 4-7 over to p1 -# echo f0 > p1/cpus + # echo f0 > p1/cpus -View the llc occupancy snapshot +View the llc occupancy snapshot:: -# cat /sys/fs/resctrl/p1/mon_data/mon_L3_00/llc_occupancy -11234000 + # cat /sys/fs/resctrl/p1/mon_data/mon_L3_00/llc_occupancy + 11234000 diff --git a/Documentation/x86/tlb.txt b/Documentation/x86/tlb.rst index 6a0607b99ed8..82ec58ae63a8 100644 --- a/Documentation/x86/tlb.txt +++ b/Documentation/x86/tlb.rst @@ -1,5 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +The TLB +======= + When the kernel unmaps or modified the attributes of a range of memory, it has two choices: + 1. Flush the entire TLB with a two-instruction sequence. This is a quick operation, but it causes collateral damage: TLB entries from areas other than the one we are trying to flush will be @@ -10,6 +17,7 @@ memory, it has two choices: damage to other TLB entries. Which method to do depends on a few things: + 1. The size of the flush being performed. A flush of the entire address space is obviously better performed by flushing the entire TLB than doing 2^48/PAGE_SIZE individual flushes. @@ -33,7 +41,7 @@ well. There is essentially no "right" point to choose. You may be doing too many individual invalidations if you see the invlpg instruction (or instructions _near_ it) show up high in profiles. If you believe that individual invalidations being -called too often, you can lower the tunable: +called too often, you can lower the tunable:: /sys/kernel/debug/x86/tlb_single_page_flush_ceiling @@ -43,7 +51,7 @@ Setting it to 1 is a very conservative setting and it should never need to be 0 under normal circumstances. Despite the fact that a single individual flush on x86 is -guaranteed to flush a full 2MB [1], hugetlbfs always uses the full +guaranteed to flush a full 2MB [1]_, hugetlbfs always uses the full flushes. THP is treated exactly the same as normal memory. You might see invlpg inside of flush_tlb_mm_range() show up in @@ -54,15 +62,15 @@ Essentially, you are balancing the cycles you spend doing invlpg with the cycles that you spend refilling the TLB later. You can measure how expensive TLB refills are by using -performance counters and 'perf stat', like this: +performance counters and 'perf stat', like this:: -perf stat -e - cpu/event=0x8,umask=0x84,name=dtlb_load_misses_walk_duration/, - cpu/event=0x8,umask=0x82,name=dtlb_load_misses_walk_completed/, - cpu/event=0x49,umask=0x4,name=dtlb_store_misses_walk_duration/, - cpu/event=0x49,umask=0x2,name=dtlb_store_misses_walk_completed/, - cpu/event=0x85,umask=0x4,name=itlb_misses_walk_duration/, - cpu/event=0x85,umask=0x2,name=itlb_misses_walk_completed/ + perf stat -e + cpu/event=0x8,umask=0x84,name=dtlb_load_misses_walk_duration/, + cpu/event=0x8,umask=0x82,name=dtlb_load_misses_walk_completed/, + cpu/event=0x49,umask=0x4,name=dtlb_store_misses_walk_duration/, + cpu/event=0x49,umask=0x2,name=dtlb_store_misses_walk_completed/, + cpu/event=0x85,umask=0x4,name=itlb_misses_walk_duration/, + cpu/event=0x85,umask=0x2,name=itlb_misses_walk_completed/ That works on an IvyBridge-era CPU (i5-3320M). Different CPUs may have differently-named counters, but they should at least @@ -70,6 +78,6 @@ be there in some form. You can use pmu-tools 'ocperf list' (https://github.com/andikleen/pmu-tools) to find the right counters for a given CPU. -1. A footnote in Intel's SDM "4.10.4.2 Recommended Invalidation" +.. [1] A footnote in Intel's SDM "4.10.4.2 Recommended Invalidation" says: "One execution of INVLPG is sufficient even for a page with size greater than 4 KBytes." diff --git a/Documentation/x86/topology.txt b/Documentation/x86/topology.rst index 06b3cdbc4048..6e28dbe818ab 100644 --- a/Documentation/x86/topology.txt +++ b/Documentation/x86/topology.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ x86 Topology ============ @@ -33,14 +36,14 @@ The topology of a system is described in the units of: - cores - threads -* Package: - - Packages contain a number of cores plus shared resources, e.g. DRAM - controller, shared caches etc. +Package +======= +Packages contain a number of cores plus shared resources, e.g. DRAM +controller, shared caches etc. - AMD nomenclature for package is 'Node'. +AMD nomenclature for package is 'Node'. - Package-related topology information in the kernel: +Package-related topology information in the kernel: - cpuinfo_x86.x86_max_cores: @@ -66,40 +69,41 @@ The topology of a system is described in the units of: - cpu_llc_id: A per-CPU variable containing: - - On Intel, the first APIC ID of the list of CPUs sharing the Last Level - Cache - - On AMD, the Node ID or Core Complex ID containing the Last Level - Cache. In general, it is a number identifying an LLC uniquely on the - system. + - On Intel, the first APIC ID of the list of CPUs sharing the Last Level + Cache -* Cores: + - On AMD, the Node ID or Core Complex ID containing the Last Level + Cache. In general, it is a number identifying an LLC uniquely on the + system. - A core consists of 1 or more threads. It does not matter whether the threads - are SMT- or CMT-type threads. +Cores +===== +A core consists of 1 or more threads. It does not matter whether the threads +are SMT- or CMT-type threads. - AMDs nomenclature for a CMT core is "Compute Unit". The kernel always uses - "core". +AMDs nomenclature for a CMT core is "Compute Unit". The kernel always uses +"core". - Core-related topology information in the kernel: +Core-related topology information in the kernel: - smp_num_siblings: The number of threads in a core. The number of threads in a package can be - calculated by: + calculated by:: threads_per_package = cpuinfo_x86.x86_max_cores * smp_num_siblings -* Threads: +Threads +======= +A thread is a single scheduling unit. It's the equivalent to a logical Linux +CPU. - A thread is a single scheduling unit. It's the equivalent to a logical Linux - CPU. +AMDs nomenclature for CMT threads is "Compute Unit Core". The kernel always +uses "thread". - AMDs nomenclature for CMT threads is "Compute Unit Core". The kernel always - uses "thread". - - Thread-related topology information in the kernel: +Thread-related topology information in the kernel: - topology_core_cpumask(): @@ -113,15 +117,15 @@ The topology of a system is described in the units of: The cpumask contains all online threads in the core to which a thread belongs. - - topology_logical_package_id(): + - topology_logical_package_id(): The logical package ID to which a thread belongs. - - topology_physical_package_id(): + - topology_physical_package_id(): The physical package ID to which a thread belongs. - - topology_core_id(); + - topology_core_id(); The ID of the core to which a thread belongs. It is also printed in /proc/cpuinfo "core_id." @@ -129,41 +133,41 @@ The topology of a system is described in the units of: System topology examples +======================== -Note: - -The alternative Linux CPU enumeration depends on how the BIOS enumerates the -threads. Many BIOSes enumerate all threads 0 first and then all threads 1. -That has the "advantage" that the logical Linux CPU numbers of threads 0 stay -the same whether threads are enabled or not. That's merely an implementation -detail and has no practical impact. +.. note:: + The alternative Linux CPU enumeration depends on how the BIOS enumerates the + threads. Many BIOSes enumerate all threads 0 first and then all threads 1. + That has the "advantage" that the logical Linux CPU numbers of threads 0 stay + the same whether threads are enabled or not. That's merely an implementation + detail and has no practical impact. -1) Single Package, Single Core +1) Single Package, Single Core:: [package 0] -> [core 0] -> [thread 0] -> Linux CPU 0 2) Single Package, Dual Core - a) One thread per core + a) One thread per core:: [package 0] -> [core 0] -> [thread 0] -> Linux CPU 0 -> [core 1] -> [thread 0] -> Linux CPU 1 - b) Two threads per core + b) Two threads per core:: [package 0] -> [core 0] -> [thread 0] -> Linux CPU 0 -> [thread 1] -> Linux CPU 1 -> [core 1] -> [thread 0] -> Linux CPU 2 -> [thread 1] -> Linux CPU 3 - Alternative enumeration: + Alternative enumeration:: [package 0] -> [core 0] -> [thread 0] -> Linux CPU 0 -> [thread 1] -> Linux CPU 2 -> [core 1] -> [thread 0] -> Linux CPU 1 -> [thread 1] -> Linux CPU 3 - AMD nomenclature for CMT systems: + AMD nomenclature for CMT systems:: [node 0] -> [Compute Unit 0] -> [Compute Unit Core 0] -> Linux CPU 0 -> [Compute Unit Core 1] -> Linux CPU 1 @@ -172,7 +176,7 @@ detail and has no practical impact. 4) Dual Package, Dual Core - a) One thread per core + a) One thread per core:: [package 0] -> [core 0] -> [thread 0] -> Linux CPU 0 -> [core 1] -> [thread 0] -> Linux CPU 1 @@ -180,7 +184,7 @@ detail and has no practical impact. [package 1] -> [core 0] -> [thread 0] -> Linux CPU 2 -> [core 1] -> [thread 0] -> Linux CPU 3 - b) Two threads per core + b) Two threads per core:: [package 0] -> [core 0] -> [thread 0] -> Linux CPU 0 -> [thread 1] -> Linux CPU 1 @@ -192,7 +196,7 @@ detail and has no practical impact. -> [core 1] -> [thread 0] -> Linux CPU 6 -> [thread 1] -> Linux CPU 7 - Alternative enumeration: + Alternative enumeration:: [package 0] -> [core 0] -> [thread 0] -> Linux CPU 0 -> [thread 1] -> Linux CPU 4 @@ -204,7 +208,7 @@ detail and has no practical impact. -> [core 1] -> [thread 0] -> Linux CPU 3 -> [thread 1] -> Linux CPU 7 - AMD nomenclature for CMT systems: + AMD nomenclature for CMT systems:: [node 0] -> [Compute Unit 0] -> [Compute Unit Core 0] -> Linux CPU 0 -> [Compute Unit Core 1] -> Linux CPU 1 diff --git a/Documentation/x86/usb-legacy-support.txt b/Documentation/x86/usb-legacy-support.rst index 1894cdfc69d9..e01c08b7c981 100644 --- a/Documentation/x86/usb-legacy-support.txt +++ b/Documentation/x86/usb-legacy-support.rst @@ -1,7 +1,11 @@ + +.. SPDX-License-Identifier: GPL-2.0 + +================== USB Legacy support -~~~~~~~~~~~~~~~~~~ +================== -Vojtech Pavlik <vojtech@suse.cz>, January 2004 +:Author: Vojtech Pavlik <vojtech@suse.cz>, January 2004 Also known as "USB Keyboard" or "USB Mouse support" in the BIOS Setup is a @@ -27,18 +31,20 @@ It has several drawbacks, though: Solutions: -Problem 1) can be solved by loading the USB drivers prior to loading the -PS/2 mouse driver. Since the PS/2 mouse driver is in 2.6 compiled into -the kernel unconditionally, this means the USB drivers need to be -compiled-in, too. - -Problem 2) can currently only be solved by either disabling HIGHMEM64G -in the kernel config or USB Legacy support in the BIOS. A BIOS update -could help, but so far no such update exists. - -Problem 3) is usually fixed by a BIOS update. Check the board -manufacturers web site. If an update is not available, disable USB -Legacy support in the BIOS. If this alone doesn't help, try also adding -idle=poll on the kernel command line. The BIOS may be entering the SMM -on the HLT instruction as well. - +Problem 1) + can be solved by loading the USB drivers prior to loading the + PS/2 mouse driver. Since the PS/2 mouse driver is in 2.6 compiled into + the kernel unconditionally, this means the USB drivers need to be + compiled-in, too. + +Problem 2) + can currently only be solved by either disabling HIGHMEM64G + in the kernel config or USB Legacy support in the BIOS. A BIOS update + could help, but so far no such update exists. + +Problem 3) + is usually fixed by a BIOS update. Check the board + manufacturers web site. If an update is not available, disable USB + Legacy support in the BIOS. If this alone doesn't help, try also adding + idle=poll on the kernel command line. The BIOS may be entering the SMM + on the HLT instruction as well. diff --git a/Documentation/x86/x86_64/5level-paging.txt b/Documentation/x86/x86_64/5level-paging.rst index 2432a5ef86d9..ab88a4514163 100644 --- a/Documentation/x86/x86_64/5level-paging.txt +++ b/Documentation/x86/x86_64/5level-paging.rst @@ -1,5 +1,11 @@ -== Overview == +.. SPDX-License-Identifier: GPL-2.0 +============== +5-level paging +============== + +Overview +======== Original x86-64 was limited by 4-level paing to 256 TiB of virtual address space and 64 TiB of physical address space. We are already bumping into this limit: some vendors offers servers with 64 TiB of memory today. @@ -16,16 +22,17 @@ QEMU 2.9 and later support 5-level paging. Virtual memory layout for 5-level paging is described in Documentation/x86/x86_64/mm.txt -== Enabling 5-level paging == +Enabling 5-level paging +======================= CONFIG_X86_5LEVEL=y enables the feature. Kernel with CONFIG_X86_5LEVEL=y still able to boot on 4-level hardware. In this case additional page table level -- p4d -- will be folded at runtime. -== User-space and large virtual address space == - +User-space and large virtual address space +========================================== On x86, 5-level paging enables 56-bit userspace virtual address space. Not all user space is ready to handle wide addresses. It's known that at least some JIT compilers use higher bits in pointers to encode their @@ -58,4 +65,3 @@ One important case we need to handle here is interaction with MPX. MPX (without MAWA extension) cannot handle addresses above 47-bit, so we need to make sure that MPX cannot be enabled we already have VMA above the boundary and forbid creating such VMAs once MPX is enabled. - diff --git a/Documentation/x86/x86_64/boot-options.rst b/Documentation/x86/x86_64/boot-options.rst new file mode 100644 index 000000000000..2f69836b8445 --- /dev/null +++ b/Documentation/x86/x86_64/boot-options.rst @@ -0,0 +1,335 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +AMD64 Specific Boot Options +=========================== + +There are many others (usually documented in driver documentation), but +only the AMD64 specific ones are listed here. + +Machine check +============= +Please see Documentation/x86/x86_64/machinecheck for sysfs runtime tunables. + + mce=off + Disable machine check + mce=no_cmci + Disable CMCI(Corrected Machine Check Interrupt) that + Intel processor supports. Usually this disablement is + not recommended, but it might be handy if your hardware + is misbehaving. + Note that you'll get more problems without CMCI than with + due to the shared banks, i.e. you might get duplicated + error logs. + mce=dont_log_ce + Don't make logs for corrected errors. All events reported + as corrected are silently cleared by OS. + This option will be useful if you have no interest in any + of corrected errors. + mce=ignore_ce + Disable features for corrected errors, e.g. polling timer + and CMCI. All events reported as corrected are not cleared + by OS and remained in its error banks. + Usually this disablement is not recommended, however if + there is an agent checking/clearing corrected errors + (e.g. BIOS or hardware monitoring applications), conflicting + with OS's error handling, and you cannot deactivate the agent, + then this option will be a help. + mce=no_lmce + Do not opt-in to Local MCE delivery. Use legacy method + to broadcast MCEs. + mce=bootlog + Enable logging of machine checks left over from booting. + Disabled by default on AMD Fam10h and older because some BIOS + leave bogus ones. + If your BIOS doesn't do that it's a good idea to enable though + to make sure you log even machine check events that result + in a reboot. On Intel systems it is enabled by default. + mce=nobootlog + Disable boot machine check logging. + mce=tolerancelevel[,monarchtimeout] (number,number) + tolerance levels: + 0: always panic on uncorrected errors, log corrected errors + 1: panic or SIGBUS on uncorrected errors, log corrected errors + 2: SIGBUS or log uncorrected errors, log corrected errors + 3: never panic or SIGBUS, log all errors (for testing only) + Default is 1 + Can be also set using sysfs which is preferable. + monarchtimeout: + Sets the time in us to wait for other CPUs on machine checks. 0 + to disable. + mce=bios_cmci_threshold + Don't overwrite the bios-set CMCI threshold. This boot option + prevents Linux from overwriting the CMCI threshold set by the + bios. Without this option, Linux always sets the CMCI + threshold to 1. Enabling this may make memory predictive failure + analysis less effective if the bios sets thresholds for memory + errors since we will not see details for all errors. + mce=recovery + Force-enable recoverable machine check code paths + + nomce (for compatibility with i386) + same as mce=off + + Everything else is in sysfs now. + +APICs +===== + + apic + Use IO-APIC. Default + + noapic + Don't use the IO-APIC. + + disableapic + Don't use the local APIC + + nolapic + Don't use the local APIC (alias for i386 compatibility) + + pirq=... + See Documentation/x86/i386/IO-APIC.txt + + noapictimer + Don't set up the APIC timer + + no_timer_check + Don't check the IO-APIC timer. This can work around + problems with incorrect timer initialization on some boards. + + apicpmtimer + Do APIC timer calibration using the pmtimer. Implies + apicmaintimer. Useful when your PIT timer is totally broken. + +Timing +====== + + notsc + Deprecated, use tsc=unstable instead. + + nohpet + Don't use the HPET timer. + +Idle loop +========= + + idle=poll + Don't do power saving in the idle loop using HLT, but poll for rescheduling + event. This will make the CPUs eat a lot more power, but may be useful + to get slightly better performance in multiprocessor benchmarks. It also + makes some profiling using performance counters more accurate. + Please note that on systems with MONITOR/MWAIT support (like Intel EM64T + CPUs) this option has no performance advantage over the normal idle loop. + It may also interact badly with hyperthreading. + +Rebooting +========= + + reboot=b[ios] | t[riple] | k[bd] | a[cpi] | e[fi] [, [w]arm | [c]old] + bios + Use the CPU reboot vector for warm reset + warm + Don't set the cold reboot flag + cold + Set the cold reboot flag + triple + Force a triple fault (init) + kbd + Use the keyboard controller. cold reset (default) + acpi + Use the ACPI RESET_REG in the FADT. If ACPI is not configured or + the ACPI reset does not work, the reboot path attempts the reset + using the keyboard controller. + efi + Use efi reset_system runtime service. If EFI is not configured or + the EFI reset does not work, the reboot path attempts the reset using + the keyboard controller. + + Using warm reset will be much faster especially on big memory + systems because the BIOS will not go through the memory check. + Disadvantage is that not all hardware will be completely reinitialized + on reboot so there may be boot problems on some systems. + + reboot=force + Don't stop other CPUs on reboot. This can make reboot more reliable + in some cases. + +Non Executable Mappings +======================= + + noexec=on|off + on + Enable(default) + off + Disable + +NUMA +==== + + numa=off + Only set up a single NUMA node spanning all memory. + + numa=noacpi + Don't parse the SRAT table for NUMA setup + + numa=fake=<size>[MG] + If given as a memory unit, fills all system RAM with nodes of + size interleaved over physical nodes. + + numa=fake=<N> + If given as an integer, fills all system RAM with N fake nodes + interleaved over physical nodes. + + numa=fake=<N>U + If given as an integer followed by 'U', it will divide each + physical node into N emulated nodes. + +ACPI +==== + + acpi=off + Don't enable ACPI + acpi=ht + Use ACPI boot table parsing, but don't enable ACPI interpreter + acpi=force + Force ACPI on (currently not needed) + acpi=strict + Disable out of spec ACPI workarounds. + acpi_sci={edge,level,high,low} + Set up ACPI SCI interrupt. + acpi=noirq + Don't route interrupts + acpi=nocmcff + Disable firmware first mode for corrected errors. This + disables parsing the HEST CMC error source to check if + firmware has set the FF flag. This may result in + duplicate corrected error reports. + +PCI +=== + + pci=off + Don't use PCI + pci=conf1 + Use conf1 access. + pci=conf2 + Use conf2 access. + pci=rom + Assign ROMs. + pci=assign-busses + Assign busses + pci=irqmask=MASK + Set PCI interrupt mask to MASK + pci=lastbus=NUMBER + Scan up to NUMBER busses, no matter what the mptable says. + pci=noacpi + Don't use ACPI to set up PCI interrupt routing. + +IOMMU (input/output memory management unit) +=========================================== +Multiple x86-64 PCI-DMA mapping implementations exist, for example: + + 1. <lib/dma-direct.c>: use no hardware/software IOMMU at all + (e.g. because you have < 3 GB memory). + Kernel boot message: "PCI-DMA: Disabling IOMMU" + + 2. <arch/x86/kernel/amd_gart_64.c>: AMD GART based hardware IOMMU. + Kernel boot message: "PCI-DMA: using GART IOMMU" + + 3. <arch/x86_64/kernel/pci-swiotlb.c> : Software IOMMU implementation. Used + e.g. if there is no hardware IOMMU in the system and it is need because + you have >3GB memory or told the kernel to us it (iommu=soft)) + Kernel boot message: "PCI-DMA: Using software bounce buffering + for IO (SWIOTLB)" + + 4. <arch/x86_64/pci-calgary.c> : IBM Calgary hardware IOMMU. Used in IBM + pSeries and xSeries servers. This hardware IOMMU supports DMA address + mapping with memory protection, etc. + Kernel boot message: "PCI-DMA: Using Calgary IOMMU" + +:: + + iommu=[<size>][,noagp][,off][,force][,noforce] + [,memaper[=<order>]][,merge][,fullflush][,nomerge] + [,noaperture][,calgary] + +General iommu options: + + off + Don't initialize and use any kind of IOMMU. + noforce + Don't force hardware IOMMU usage when it is not needed. (default). + force + Force the use of the hardware IOMMU even when it is + not actually needed (e.g. because < 3 GB memory). + soft + Use software bounce buffering (SWIOTLB) (default for + Intel machines). This can be used to prevent the usage + of an available hardware IOMMU. + +iommu options only relevant to the AMD GART hardware IOMMU: + + <size> + Set the size of the remapping area in bytes. + allowed + Overwrite iommu off workarounds for specific chipsets. + fullflush + Flush IOMMU on each allocation (default). + nofullflush + Don't use IOMMU fullflush. + memaper[=<order>] + Allocate an own aperture over RAM with size 32MB<<order. + (default: order=1, i.e. 64MB) + merge + Do scatter-gather (SG) merging. Implies "force" (experimental). + nomerge + Don't do scatter-gather (SG) merging. + noaperture + Ask the IOMMU not to touch the aperture for AGP. + noagp + Don't initialize the AGP driver and use full aperture. + panic + Always panic when IOMMU overflows. + calgary + Use the Calgary IOMMU if it is available + +iommu options only relevant to the software bounce buffering (SWIOTLB) IOMMU +implementation: + + swiotlb=<pages>[,force] + <pages> + Prereserve that many 128K pages for the software IO bounce buffering. + force + Force all IO through the software TLB. + +Settings for the IBM Calgary hardware IOMMU currently found in IBM +pSeries and xSeries machines + + calgary=[64k,128k,256k,512k,1M,2M,4M,8M] + Set the size of each PCI slot's translation table when using the + Calgary IOMMU. This is the size of the translation table itself + in main memory. The smallest table, 64k, covers an IO space of + 32MB; the largest, 8MB table, can cover an IO space of 4GB. + Normally the kernel will make the right choice by itself. + calgary=[translate_empty_slots] + Enable translation even on slots that have no devices attached to + them, in case a device will be hotplugged in the future. + calgary=[disable=<PCI bus number>] + Disable translation on a given PHB. For + example, the built-in graphics adapter resides on the first bridge + (PCI bus number 0); if translation (isolation) is enabled on this + bridge, X servers that access the hardware directly from user + space might stop working. Use this option if you have devices that + are accessed from userspace directly on some PCI host bridge. + panic + Always panic when IOMMU overflows + + +Miscellaneous +============= + + nogbpages + Do not use GB pages for kernel direct mappings. + gbpages + Use GB pages for kernel direct mappings. diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt deleted file mode 100644 index abc53886655e..000000000000 --- a/Documentation/x86/x86_64/boot-options.txt +++ /dev/null @@ -1,278 +0,0 @@ -AMD64 specific boot options - -There are many others (usually documented in driver documentation), but -only the AMD64 specific ones are listed here. - -Machine check - - Please see Documentation/x86/x86_64/machinecheck for sysfs runtime tunables. - - mce=off - Disable machine check - mce=no_cmci - Disable CMCI(Corrected Machine Check Interrupt) that - Intel processor supports. Usually this disablement is - not recommended, but it might be handy if your hardware - is misbehaving. - Note that you'll get more problems without CMCI than with - due to the shared banks, i.e. you might get duplicated - error logs. - mce=dont_log_ce - Don't make logs for corrected errors. All events reported - as corrected are silently cleared by OS. - This option will be useful if you have no interest in any - of corrected errors. - mce=ignore_ce - Disable features for corrected errors, e.g. polling timer - and CMCI. All events reported as corrected are not cleared - by OS and remained in its error banks. - Usually this disablement is not recommended, however if - there is an agent checking/clearing corrected errors - (e.g. BIOS or hardware monitoring applications), conflicting - with OS's error handling, and you cannot deactivate the agent, - then this option will be a help. - mce=no_lmce - Do not opt-in to Local MCE delivery. Use legacy method - to broadcast MCEs. - mce=bootlog - Enable logging of machine checks left over from booting. - Disabled by default on AMD Fam10h and older because some BIOS - leave bogus ones. - If your BIOS doesn't do that it's a good idea to enable though - to make sure you log even machine check events that result - in a reboot. On Intel systems it is enabled by default. - mce=nobootlog - Disable boot machine check logging. - mce=tolerancelevel[,monarchtimeout] (number,number) - tolerance levels: - 0: always panic on uncorrected errors, log corrected errors - 1: panic or SIGBUS on uncorrected errors, log corrected errors - 2: SIGBUS or log uncorrected errors, log corrected errors - 3: never panic or SIGBUS, log all errors (for testing only) - Default is 1 - Can be also set using sysfs which is preferable. - monarchtimeout: - Sets the time in us to wait for other CPUs on machine checks. 0 - to disable. - mce=bios_cmci_threshold - Don't overwrite the bios-set CMCI threshold. This boot option - prevents Linux from overwriting the CMCI threshold set by the - bios. Without this option, Linux always sets the CMCI - threshold to 1. Enabling this may make memory predictive failure - analysis less effective if the bios sets thresholds for memory - errors since we will not see details for all errors. - mce=recovery - Force-enable recoverable machine check code paths - - nomce (for compatibility with i386): same as mce=off - - Everything else is in sysfs now. - -APICs - - apic Use IO-APIC. Default - - noapic Don't use the IO-APIC. - - disableapic Don't use the local APIC - - nolapic Don't use the local APIC (alias for i386 compatibility) - - pirq=... See Documentation/x86/i386/IO-APIC.txt - - noapictimer Don't set up the APIC timer - - no_timer_check Don't check the IO-APIC timer. This can work around - problems with incorrect timer initialization on some boards. - apicpmtimer - Do APIC timer calibration using the pmtimer. Implies - apicmaintimer. Useful when your PIT timer is totally - broken. - -Timing - - notsc - Deprecated, use tsc=unstable instead. - - nohpet - Don't use the HPET timer. - -Idle loop - - idle=poll - Don't do power saving in the idle loop using HLT, but poll for rescheduling - event. This will make the CPUs eat a lot more power, but may be useful - to get slightly better performance in multiprocessor benchmarks. It also - makes some profiling using performance counters more accurate. - Please note that on systems with MONITOR/MWAIT support (like Intel EM64T - CPUs) this option has no performance advantage over the normal idle loop. - It may also interact badly with hyperthreading. - -Rebooting - - reboot=b[ios] | t[riple] | k[bd] | a[cpi] | e[fi] [, [w]arm | [c]old] - bios Use the CPU reboot vector for warm reset - warm Don't set the cold reboot flag - cold Set the cold reboot flag - triple Force a triple fault (init) - kbd Use the keyboard controller. cold reset (default) - acpi Use the ACPI RESET_REG in the FADT. If ACPI is not configured or the - ACPI reset does not work, the reboot path attempts the reset using - the keyboard controller. - efi Use efi reset_system runtime service. If EFI is not configured or the - EFI reset does not work, the reboot path attempts the reset using - the keyboard controller. - - Using warm reset will be much faster especially on big memory - systems because the BIOS will not go through the memory check. - Disadvantage is that not all hardware will be completely reinitialized - on reboot so there may be boot problems on some systems. - - reboot=force - - Don't stop other CPUs on reboot. This can make reboot more reliable - in some cases. - -Non Executable Mappings - - noexec=on|off - - on Enable(default) - off Disable - -NUMA - - numa=off Only set up a single NUMA node spanning all memory. - - numa=noacpi Don't parse the SRAT table for NUMA setup - - numa=fake=<size>[MG] - If given as a memory unit, fills all system RAM with nodes of - size interleaved over physical nodes. - - numa=fake=<N> - If given as an integer, fills all system RAM with N fake nodes - interleaved over physical nodes. - - numa=fake=<N>U - If given as an integer followed by 'U', it will divide each - physical node into N emulated nodes. - -ACPI - - acpi=off Don't enable ACPI - acpi=ht Use ACPI boot table parsing, but don't enable ACPI - interpreter - acpi=force Force ACPI on (currently not needed) - - acpi=strict Disable out of spec ACPI workarounds. - - acpi_sci={edge,level,high,low} Set up ACPI SCI interrupt. - - acpi=noirq Don't route interrupts - - acpi=nocmcff Disable firmware first mode for corrected errors. This - disables parsing the HEST CMC error source to check if - firmware has set the FF flag. This may result in - duplicate corrected error reports. - -PCI - - pci=off Don't use PCI - pci=conf1 Use conf1 access. - pci=conf2 Use conf2 access. - pci=rom Assign ROMs. - pci=assign-busses Assign busses - pci=irqmask=MASK Set PCI interrupt mask to MASK - pci=lastbus=NUMBER Scan up to NUMBER busses, no matter what the mptable says. - pci=noacpi Don't use ACPI to set up PCI interrupt routing. - -IOMMU (input/output memory management unit) - - Multiple x86-64 PCI-DMA mapping implementations exist, for example: - - 1. <lib/dma-direct.c>: use no hardware/software IOMMU at all - (e.g. because you have < 3 GB memory). - Kernel boot message: "PCI-DMA: Disabling IOMMU" - - 2. <arch/x86/kernel/amd_gart_64.c>: AMD GART based hardware IOMMU. - Kernel boot message: "PCI-DMA: using GART IOMMU" - - 3. <arch/x86_64/kernel/pci-swiotlb.c> : Software IOMMU implementation. Used - e.g. if there is no hardware IOMMU in the system and it is need because - you have >3GB memory or told the kernel to us it (iommu=soft)) - Kernel boot message: "PCI-DMA: Using software bounce buffering - for IO (SWIOTLB)" - - 4. <arch/x86_64/pci-calgary.c> : IBM Calgary hardware IOMMU. Used in IBM - pSeries and xSeries servers. This hardware IOMMU supports DMA address - mapping with memory protection, etc. - Kernel boot message: "PCI-DMA: Using Calgary IOMMU" - - iommu=[<size>][,noagp][,off][,force][,noforce] - [,memaper[=<order>]][,merge][,fullflush][,nomerge] - [,noaperture][,calgary] - - General iommu options: - off Don't initialize and use any kind of IOMMU. - noforce Don't force hardware IOMMU usage when it is not needed. - (default). - force Force the use of the hardware IOMMU even when it is - not actually needed (e.g. because < 3 GB memory). - soft Use software bounce buffering (SWIOTLB) (default for - Intel machines). This can be used to prevent the usage - of an available hardware IOMMU. - - iommu options only relevant to the AMD GART hardware IOMMU: - <size> Set the size of the remapping area in bytes. - allowed Overwrite iommu off workarounds for specific chipsets. - fullflush Flush IOMMU on each allocation (default). - nofullflush Don't use IOMMU fullflush. - memaper[=<order>] Allocate an own aperture over RAM with size 32MB<<order. - (default: order=1, i.e. 64MB) - merge Do scatter-gather (SG) merging. Implies "force" - (experimental). - nomerge Don't do scatter-gather (SG) merging. - noaperture Ask the IOMMU not to touch the aperture for AGP. - noagp Don't initialize the AGP driver and use full aperture. - panic Always panic when IOMMU overflows. - calgary Use the Calgary IOMMU if it is available - - iommu options only relevant to the software bounce buffering (SWIOTLB) IOMMU - implementation: - swiotlb=<pages>[,force] - <pages> Prereserve that many 128K pages for the software IO - bounce buffering. - force Force all IO through the software TLB. - - Settings for the IBM Calgary hardware IOMMU currently found in IBM - pSeries and xSeries machines: - - calgary=[64k,128k,256k,512k,1M,2M,4M,8M] - calgary=[translate_empty_slots] - calgary=[disable=<PCI bus number>] - panic Always panic when IOMMU overflows - - 64k,...,8M - Set the size of each PCI slot's translation table - when using the Calgary IOMMU. This is the size of the translation - table itself in main memory. The smallest table, 64k, covers an IO - space of 32MB; the largest, 8MB table, can cover an IO space of - 4GB. Normally the kernel will make the right choice by itself. - - translate_empty_slots - Enable translation even on slots that have - no devices attached to them, in case a device will be hotplugged - in the future. - - disable=<PCI bus number> - Disable translation on a given PHB. For - example, the built-in graphics adapter resides on the first bridge - (PCI bus number 0); if translation (isolation) is enabled on this - bridge, X servers that access the hardware directly from user - space might stop working. Use this option if you have devices that - are accessed from userspace directly on some PCI host bridge. - -Miscellaneous - - nogbpages - Do not use GB pages for kernel direct mappings. - gbpages - Use GB pages for kernel direct mappings. diff --git a/Documentation/x86/x86_64/cpu-hotplug-spec b/Documentation/x86/x86_64/cpu-hotplug-spec.rst index 3c23e0587db3..8d1c91f0c880 100644 --- a/Documentation/x86/x86_64/cpu-hotplug-spec +++ b/Documentation/x86/x86_64/cpu-hotplug-spec.rst @@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================================== Firmware support for CPU hotplug under Linux/x86-64 ---------------------------------------------------- +=================================================== Linux/x86-64 supports CPU hotplug now. For various reasons Linux wants to know in advance of boot time the maximum number of CPUs that could be plugged diff --git a/Documentation/x86/x86_64/fake-numa-for-cpusets b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst index 4b09f18831f8..74fbb78b3c67 100644 --- a/Documentation/x86/x86_64/fake-numa-for-cpusets +++ b/Documentation/x86/x86_64/fake-numa-for-cpusets.rst @@ -1,5 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Fake NUMA For CPUSets +===================== + +:Author: David Rientjes <rientjes@cs.washington.edu> + Using numa=fake and CPUSets for Resource Management -Written by David Rientjes <rientjes@cs.washington.edu> This document describes how the numa=fake x86_64 command-line option can be used in conjunction with cpusets for coarse memory management. Using this feature, @@ -20,7 +27,7 @@ you become more familiar with using this combination for resource control, you'll determine a better setup to minimize the number of nodes you have to deal with. -A machine may be split as follows with "numa=fake=4*512," as reported by dmesg: +A machine may be split as follows with "numa=fake=4*512," as reported by dmesg:: Faking node 0 at 0000000000000000-0000000020000000 (512MB) Faking node 1 at 0000000020000000-0000000040000000 (512MB) @@ -34,7 +41,7 @@ A machine may be split as follows with "numa=fake=4*512," as reported by dmesg: Now following the instructions for mounting the cpusets filesystem from Documentation/cgroup-v1/cpusets.txt, you can assign fake nodes (i.e. contiguous memory -address spaces) to individual cpusets: +address spaces) to individual cpusets:: [root@xroads /]# mkdir exampleset [root@xroads /]# mount -t cpuset none exampleset @@ -47,7 +54,7 @@ Now this cpuset, 'ddset', will only allowed access to fake nodes 0 and 1 for memory allocations (1G). You can now assign tasks to these cpusets to limit the memory resources -available to them according to the fake nodes assigned as mems: +available to them according to the fake nodes assigned as mems:: [root@xroads /exampleset/ddset]# echo $$ > tasks [root@xroads /exampleset/ddset]# dd if=/dev/zero of=tmp bs=1024 count=1G @@ -57,9 +64,13 @@ Notice the difference between the system memory usage as reported by /proc/meminfo between the restricted cpuset case above and the unrestricted case (i.e. running the same 'dd' command without assigning it to a fake NUMA cpuset): - Unrestricted Restricted - MemTotal: 3091900 kB 3091900 kB - MemFree: 42113 kB 1513236 kB + + ======== ============ ========== + Name Unrestricted Restricted + ======== ============ ========== + MemTotal 3091900 kB 3091900 kB + MemFree 42113 kB 1513236 kB + ======== ============ ========== This allows for coarse memory management for the tasks you assign to particular cpusets. Since cpusets can form a hierarchy, you can create some pretty diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/x86/x86_64/index.rst new file mode 100644 index 000000000000..d6eaaa5a35fc --- /dev/null +++ b/Documentation/x86/x86_64/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +x86_64 Support +============== + +.. toctree:: + :maxdepth: 2 + + boot-options + uefi + mm + 5level-paging + fake-numa-for-cpusets + cpu-hotplug-spec + machinecheck diff --git a/Documentation/x86/x86_64/machinecheck b/Documentation/x86/x86_64/machinecheck.rst index d0648a74fceb..e189168406fa 100644 --- a/Documentation/x86/x86_64/machinecheck +++ b/Documentation/x86/x86_64/machinecheck.rst @@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 -Configurable sysfs parameters for the x86-64 machine check code. +=============================================================== +Configurable sysfs parameters for the x86-64 machine check code +=============================================================== Machine checks report internal hardware error conditions detected by the CPU. Uncorrected errors typically cause a machine check @@ -16,14 +19,13 @@ log then mcelog should run to collect and decode machine check entries from /dev/mcelog. Normally mcelog should be run regularly from a cronjob. Each CPU has a directory in /sys/devices/system/machinecheck/machinecheckN -(N = CPU number) +(N = CPU number). The directory contains some configurable entries: -Entries: - bankNctl -(N bank number) + (N bank number) + 64bit Hex bitmask enabling/disabling specific subevents for bank N When a bit in the bitmask is zero then the respective subevent will not be reported. diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst new file mode 100644 index 000000000000..267fc4808945 --- /dev/null +++ b/Documentation/x86/x86_64/mm.rst @@ -0,0 +1,161 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +Memory Managment +================ + +Complete virtual memory map with 4-level page tables +==================================================== + +.. note:: + + - Negative addresses such as "-23 TB" are absolute addresses in bytes, counted down + from the top of the 64-bit address space. It's easier to understand the layout + when seen both in absolute addresses and in distance-from-top notation. + + For example 0xffffe90000000000 == -23 TB, it's 23 TB lower than the top of the + 64-bit address space (ffffffffffffffff). + + Note that as we get closer to the top of the address space, the notation changes + from TB to GB and then MB/KB. + + - "16M TB" might look weird at first sight, but it's an easier to visualize size + notation than "16 EB", which few will recognize at first sight as 16 exabytes. + It also shows it nicely how incredibly large 64-bit address space is. + +:: + + ======================================================================================================================== + Start addr | Offset | End addr | Size | VM area description + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 00007fffffffffff | 128 TB | user-space virtual memory, different per mm + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0000800000000000 | +128 TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical + | | | | virtual memory addresses up to the -128 TB + | | | | starting offset of kernel mappings. + __________________|____________|__________________|_________|___________________________________________________________ + | + | Kernel-space virtual memory, shared between all processes: + ____________________________________________________________|___________________________________________________________ + | | | | + ffff800000000000 | -128 TB | ffff87ffffffffff | 8 TB | ... guard hole, also reserved for hypervisor + ffff880000000000 | -120 TB | ffff887fffffffff | 0.5 TB | LDT remap for PTI + ffff888000000000 | -119.5 TB | ffffc87fffffffff | 64 TB | direct mapping of all physical memory (page_offset_base) + ffffc88000000000 | -55.5 TB | ffffc8ffffffffff | 0.5 TB | ... unused hole + ffffc90000000000 | -55 TB | ffffe8ffffffffff | 32 TB | vmalloc/ioremap space (vmalloc_base) + ffffe90000000000 | -23 TB | ffffe9ffffffffff | 1 TB | ... unused hole + ffffea0000000000 | -22 TB | ffffeaffffffffff | 1 TB | virtual memory map (vmemmap_base) + ffffeb0000000000 | -21 TB | ffffebffffffffff | 1 TB | ... unused hole + ffffec0000000000 | -20 TB | fffffbffffffffff | 16 TB | KASAN shadow memory + __________________|____________|__________________|_________|____________________________________________________________ + | + | Identical layout to the 56-bit one from here on: + ____________________________________________________________|____________________________________________________________ + | | | | + fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole + | | | | vaddr_end for KASLR + fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping + fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole + ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks + ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole + ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole + ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0 + ffffffff80000000 |-2048 MB | | | + ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space + ffffffffff000000 | -16 MB | | | + FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset + ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI + ffffffffffe00000 | -2 MB | ffffffffffffffff | 2 MB | ... unused hole + __________________|____________|__________________|_________|___________________________________________________________ + + +Complete virtual memory map with 5-level page tables +==================================================== + +.. note:: + + - With 56-bit addresses, user-space memory gets expanded by a factor of 512x, + from 0.125 PB to 64 PB. All kernel mappings shift down to the -64 PB starting + offset and many of the regions expand to support the much larger physical + memory supported. + +:: + + ======================================================================================================================== + Start addr | Offset | End addr | Size | VM area description + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 00ffffffffffffff | 64 PB | user-space virtual memory, different per mm + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0100000000000000 | +64 PB | feffffffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical + | | | | virtual memory addresses up to the -64 PB + | | | | starting offset of kernel mappings. + __________________|____________|__________________|_________|___________________________________________________________ + | + | Kernel-space virtual memory, shared between all processes: + ____________________________________________________________|___________________________________________________________ + | | | | + ff00000000000000 | -64 PB | ff0fffffffffffff | 4 PB | ... guard hole, also reserved for hypervisor + ff10000000000000 | -60 PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI + ff11000000000000 | -59.75 PB | ff90ffffffffffff | 32 PB | direct mapping of all physical memory (page_offset_base) + ff91000000000000 | -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole + ffa0000000000000 | -24 PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base) + ffd2000000000000 | -11.5 PB | ffd3ffffffffffff | 0.5 PB | ... unused hole + ffd4000000000000 | -11 PB | ffd5ffffffffffff | 0.5 PB | virtual memory map (vmemmap_base) + ffd6000000000000 | -10.5 PB | ffdeffffffffffff | 2.25 PB | ... unused hole + ffdf000000000000 | -8.25 PB | fffffbffffffffff | ~8 PB | KASAN shadow memory + __________________|____________|__________________|_________|____________________________________________________________ + | + | Identical layout to the 47-bit one from here on: + ____________________________________________________________|____________________________________________________________ + | | | | + fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole + | | | | vaddr_end for KASLR + fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping + fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole + ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks + ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole + ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole + ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0 + ffffffff80000000 |-2048 MB | | | + ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space + ffffffffff000000 | -16 MB | | | + FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset + ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI + ffffffffffe00000 | -2 MB | 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 sign extended. +This causes hole between user space and kernel addresses if you interpret them +as unsigned. + +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/PML5 pages of +the processes using the page fault handler, with init_top_pgt as +reference. + +We map EFI runtime services in the 'efi_pgd' PGD in a 64Gb large virtual +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. + +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. + +Be very careful vs. KASLR when changing anything here. The KASLR address +range must not overlap with anything except the KASAN shadow area, which is +correct as KASAN disables KASLR. + +For both 4- and 5-level layouts, the STACKLEAK_POISON value in the last 2MB +hole: ffffffffffff4111 diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt deleted file mode 100644 index 6cbe652d7a49..000000000000 --- a/Documentation/x86/x86_64/mm.txt +++ /dev/null @@ -1,153 +0,0 @@ -==================================================== -Complete virtual memory map with 4-level page tables -==================================================== - -Notes: - - - Negative addresses such as "-23 TB" are absolute addresses in bytes, counted down - from the top of the 64-bit address space. It's easier to understand the layout - when seen both in absolute addresses and in distance-from-top notation. - - For example 0xffffe90000000000 == -23 TB, it's 23 TB lower than the top of the - 64-bit address space (ffffffffffffffff). - - Note that as we get closer to the top of the address space, the notation changes - from TB to GB and then MB/KB. - - - "16M TB" might look weird at first sight, but it's an easier to visualize size - notation than "16 EB", which few will recognize at first sight as 16 exabytes. - It also shows it nicely how incredibly large 64-bit address space is. - -======================================================================================================================== - Start addr | Offset | End addr | Size | VM area description -======================================================================================================================== - | | | | - 0000000000000000 | 0 | 00007fffffffffff | 128 TB | user-space virtual memory, different per mm -__________________|____________|__________________|_________|___________________________________________________________ - | | | | - 0000800000000000 | +128 TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical - | | | | virtual memory addresses up to the -128 TB - | | | | starting offset of kernel mappings. -__________________|____________|__________________|_________|___________________________________________________________ - | - | Kernel-space virtual memory, shared between all processes: -____________________________________________________________|___________________________________________________________ - | | | | - ffff800000000000 | -128 TB | ffff87ffffffffff | 8 TB | ... guard hole, also reserved for hypervisor - ffff880000000000 | -120 TB | ffff887fffffffff | 0.5 TB | LDT remap for PTI - ffff888000000000 | -119.5 TB | ffffc87fffffffff | 64 TB | direct mapping of all physical memory (page_offset_base) - ffffc88000000000 | -55.5 TB | ffffc8ffffffffff | 0.5 TB | ... unused hole - ffffc90000000000 | -55 TB | ffffe8ffffffffff | 32 TB | vmalloc/ioremap space (vmalloc_base) - ffffe90000000000 | -23 TB | ffffe9ffffffffff | 1 TB | ... unused hole - ffffea0000000000 | -22 TB | ffffeaffffffffff | 1 TB | virtual memory map (vmemmap_base) - ffffeb0000000000 | -21 TB | ffffebffffffffff | 1 TB | ... unused hole - ffffec0000000000 | -20 TB | fffffbffffffffff | 16 TB | KASAN shadow memory -__________________|____________|__________________|_________|____________________________________________________________ - | - | Identical layout to the 56-bit one from here on: -____________________________________________________________|____________________________________________________________ - | | | | - fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole - | | | | vaddr_end for KASLR - fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping - fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole - ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks - ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole - ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space - ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole - ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0 - ffffffff80000000 |-2048 MB | | | - ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space - ffffffffff000000 | -16 MB | | | - FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset - ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI - ffffffffffe00000 | -2 MB | ffffffffffffffff | 2 MB | ... unused hole -__________________|____________|__________________|_________|___________________________________________________________ - - -==================================================== -Complete virtual memory map with 5-level page tables -==================================================== - -Notes: - - - With 56-bit addresses, user-space memory gets expanded by a factor of 512x, - from 0.125 PB to 64 PB. All kernel mappings shift down to the -64 PB starting - offset and many of the regions expand to support the much larger physical - memory supported. - -======================================================================================================================== - Start addr | Offset | End addr | Size | VM area description -======================================================================================================================== - | | | | - 0000000000000000 | 0 | 00ffffffffffffff | 64 PB | user-space virtual memory, different per mm -__________________|____________|__________________|_________|___________________________________________________________ - | | | | - 0100000000000000 | +64 PB | feffffffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical - | | | | virtual memory addresses up to the -64 PB - | | | | starting offset of kernel mappings. -__________________|____________|__________________|_________|___________________________________________________________ - | - | Kernel-space virtual memory, shared between all processes: -____________________________________________________________|___________________________________________________________ - | | | | - ff00000000000000 | -64 PB | ff0fffffffffffff | 4 PB | ... guard hole, also reserved for hypervisor - ff10000000000000 | -60 PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI - ff11000000000000 | -59.75 PB | ff90ffffffffffff | 32 PB | direct mapping of all physical memory (page_offset_base) - ff91000000000000 | -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole - ffa0000000000000 | -24 PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base) - ffd2000000000000 | -11.5 PB | ffd3ffffffffffff | 0.5 PB | ... unused hole - ffd4000000000000 | -11 PB | ffd5ffffffffffff | 0.5 PB | virtual memory map (vmemmap_base) - ffd6000000000000 | -10.5 PB | ffdeffffffffffff | 2.25 PB | ... unused hole - ffdf000000000000 | -8.25 PB | fffffbffffffffff | ~8 PB | KASAN shadow memory -__________________|____________|__________________|_________|____________________________________________________________ - | - | Identical layout to the 47-bit one from here on: -____________________________________________________________|____________________________________________________________ - | | | | - fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole - | | | | vaddr_end for KASLR - fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping - fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole - ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks - ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole - ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space - ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole - ffffffff80000000 | -2 GB | ffffffff9fffffff | 512 MB | kernel text mapping, mapped to physical address 0 - ffffffff80000000 |-2048 MB | | | - ffffffffa0000000 |-1536 MB | fffffffffeffffff | 1520 MB | module mapping space - ffffffffff000000 | -16 MB | | | - FIXADDR_START | ~-11 MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset - ffffffffff600000 | -10 MB | ffffffffff600fff | 4 kB | legacy vsyscall ABI - ffffffffffe00000 | -2 MB | 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 sign extended. -This causes hole between user space and kernel addresses if you interpret them -as unsigned. - -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/PML5 pages of -the processes using the page fault handler, with init_top_pgt as -reference. - -We map EFI runtime services in the 'efi_pgd' PGD in a 64Gb large virtual -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. - -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. - -Be very careful vs. KASLR when changing anything here. The KASLR address -range must not overlap with anything except the KASAN shadow area, which is -correct as KASAN disables KASLR. - -For both 4- and 5-level layouts, the STACKLEAK_POISON value in the last 2MB -hole: ffffffffffff4111 diff --git a/Documentation/x86/x86_64/uefi.txt b/Documentation/x86/x86_64/uefi.rst index a5e2b4fdb170..88c3ba32546f 100644 --- a/Documentation/x86/x86_64/uefi.txt +++ b/Documentation/x86/x86_64/uefi.rst @@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== General note on [U]EFI x86_64 support -------------------------------------- +===================================== The nomenclature EFI and UEFI are used interchangeably in this document. @@ -14,29 +17,42 @@ with EFI firmware and specifications are listed below. 3. x86_64 platform with EFI/UEFI firmware. -Mechanics: +Mechanics --------- -- Build the kernel with the following configuration. + +- Build the kernel with the following configuration:: + CONFIG_FB_EFI=y CONFIG_FRAMEBUFFER_CONSOLE=y + If EFI runtime services are expected, the following configuration should - be selected. + be selected:: + CONFIG_EFI=y CONFIG_EFI_VARS=y or m # optional + - Create a VFAT partition on the disk - Copy the following to the VFAT partition: + elilo bootloader with x86_64 support, elilo configuration file, kernel image built in first step and corresponding initrd. Instructions on building elilo and its dependencies can be found in the elilo sourceforge project. + - Boot to EFI shell and invoke elilo choosing the kernel image built in first step. - If some or all EFI runtime services don't work, you can try following kernel command line parameters to turn off some or all EFI runtime services. - noefi turn off all EFI runtime services - reboot_type=k turn off EFI reboot runtime service + + noefi + turn off all EFI runtime services + reboot_type=k + turn off EFI reboot runtime service + - If the EFI memory map has additional entries not in the E820 map, you can include those entries in the kernels memory map of available physical RAM by using the following kernel command line parameter. - add_efi_memmap include EFI memory map of available physical RAM + + add_efi_memmap + include EFI memory map of available physical RAM diff --git a/Documentation/x86/zero-page.rst b/Documentation/x86/zero-page.rst new file mode 100644 index 000000000000..f088f5881666 --- /dev/null +++ b/Documentation/x86/zero-page.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========= +Zero Page +========= +The additional fields in struct boot_params as a part of 32-bit boot +protocol of kernel. These should be filled by bootloader or 16-bit +real-mode setup code of the kernel. References/settings to it mainly +are in:: + + arch/x86/include/uapi/asm/bootparam.h + +=========== ===== ======================= ================================================= +Offset/Size Proto Name Meaning + +000/040 ALL screen_info Text mode or frame buffer information + (struct screen_info) +040/014 ALL apm_bios_info APM BIOS information (struct apm_bios_info) +058/008 ALL tboot_addr Physical address of tboot shared page +060/010 ALL ist_info Intel SpeedStep (IST) BIOS support information + (struct ist_info) +080/010 ALL hd0_info hd0 disk parameter, OBSOLETE!! +090/010 ALL hd1_info hd1 disk parameter, OBSOLETE!! +0A0/010 ALL sys_desc_table System description table (struct sys_desc_table), + OBSOLETE!! +0B0/010 ALL olpc_ofw_header OLPC's OpenFirmware CIF and friends +0C0/004 ALL ext_ramdisk_image ramdisk_image high 32bits +0C4/004 ALL ext_ramdisk_size ramdisk_size high 32bits +0C8/004 ALL ext_cmd_line_ptr cmd_line_ptr high 32bits +140/080 ALL edid_info Video mode setup (struct edid_info) +1C0/020 ALL efi_info EFI 32 information (struct efi_info) +1E0/004 ALL alt_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_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) +1EB/001 ALL kbd_status Numlock is enabled +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_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/x86/zero-page.txt b/Documentation/x86/zero-page.txt deleted file mode 100644 index 68aed077f7b6..000000000000 --- a/Documentation/x86/zero-page.txt +++ /dev/null @@ -1,40 +0,0 @@ -The additional fields in struct boot_params as a part of 32-bit boot -protocol of kernel. These should be filled by bootloader or 16-bit -real-mode setup code of the kernel. References/settings to it mainly -are in: - - arch/x86/include/uapi/asm/bootparam.h - - -Offset Proto Name Meaning -/Size - -000/040 ALL screen_info Text mode or frame buffer information - (struct screen_info) -040/014 ALL apm_bios_info APM BIOS information (struct apm_bios_info) -058/008 ALL tboot_addr Physical address of tboot shared page -060/010 ALL ist_info Intel SpeedStep (IST) BIOS support information - (struct ist_info) -080/010 ALL hd0_info hd0 disk parameter, OBSOLETE!! -090/010 ALL hd1_info hd1 disk parameter, OBSOLETE!! -0A0/010 ALL sys_desc_table System description table (struct sys_desc_table), - OBSOLETE!! -0B0/010 ALL olpc_ofw_header OLPC's OpenFirmware CIF and friends -0C0/004 ALL ext_ramdisk_image ramdisk_image high 32bits -0C4/004 ALL ext_ramdisk_size ramdisk_size high 32bits -0C8/004 ALL ext_cmd_line_ptr cmd_line_ptr high 32bits -140/080 ALL edid_info Video mode setup (struct edid_info) -1C0/020 ALL efi_info EFI 32 information (struct efi_info) -1E0/004 ALL alt_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_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) -1EB/001 ALL kbd_status Numlock is enabled -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_table E820 memory map table - (array of struct e820_entry) -D00/1EC ALL eddbuf EDD data (array of struct edd_info) |
