diff options
Diffstat (limited to 'Documentation')
512 files changed, 21769 insertions, 6206 deletions
diff --git a/Documentation/ABI/stable/procfs-audit_loginuid b/Documentation/ABI/stable/procfs-audit_loginuid new file mode 100644 index 000000000000..cda405178391 --- /dev/null +++ b/Documentation/ABI/stable/procfs-audit_loginuid @@ -0,0 +1,27 @@ +What: Audit Login UID +Date: 2005-02-01 +KernelVersion: 2.6.11-rc2 1e2d1492e178 ("[PATCH] audit: handle loginuid through proc") +Contact: linux-audit@redhat.com +Users: audit and login applications +Description: + The /proc/$pid/loginuid pseudofile is written to set and + read to get the audit login UID of process $pid as a + decimal unsigned int (%u, u32). If it is unset, + permissions are not needed to set it. The accessor must + have CAP_AUDIT_CONTROL in the initial user namespace to + write it if it has been set. It cannot be written again + if AUDIT_FEATURE_LOGINUID_IMMUTABLE is enabled. It + cannot be unset if AUDIT_FEATURE_ONLY_UNSET_LOGINUID is + enabled. + +What: Audit Login Session ID +Date: 2008-03-13 +KernelVersion: 2.6.25-rc7 1e0bd7550ea9 ("[PATCH] export sessionid alongside the loginuid in procfs") +Contact: linux-audit@redhat.com +Users: audit and login applications +Description: + The /proc/$pid/sessionid pseudofile is read to get the + audit login session ID of process $pid as a decimal + unsigned int (%u, u32). It is set automatically, + serially assigned with each new login. + diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs index d447a611c41b..c78fc9282876 100644 --- a/Documentation/ABI/testing/debugfs-driver-habanalabs +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -82,6 +82,24 @@ Description: Allows the root user to read or write 64 bit data directly If the IOMMU is disabled, it also allows the root user to read or write from the host a device VA of a host mapped memory +What: /sys/kernel/debug/habanalabs/hl<n>/data_dma +Date: Apr 2021 +KernelVersion: 5.13 +Contact: ogabbay@kernel.org +Description: Allows the root user to read from the device's internal + memory (DRAM/SRAM) through a DMA engine. + This property is a binary blob that contains the result of the + DMA transfer. + This custom interface is needed (instead of using the generic + Linux user-space PCI mapping) because the amount of internal + memory is huge (>32GB) and reading it via the PCI bar will take + a very long time. + This interface doesn't support concurrency in the same device. + In GAUDI and GOYA, this action can cause undefined behavior + in case the it is done while the device is executing user + workloads. + Only supported on GAUDI at this stage. + What: /sys/kernel/debug/habanalabs/hl<n>/device Date: Jan 2019 KernelVersion: 5.1 @@ -90,6 +108,24 @@ Description: Enables the root user to set the device to specific state. Valid values are "disable", "enable", "suspend", "resume". User can read this property to see the valid values +What: /sys/kernel/debug/habanalabs/hl<n>/dma_size +Date: Apr 2021 +KernelVersion: 5.13 +Contact: ogabbay@kernel.org +Description: Specify the size of the DMA transaction when using DMA to read + from the device's internal memory. The value can not be larger + than 128MB. Writing to this value initiates the DMA transfer. + When the write is finished, the user can read the "data_dma" + blob + +What: /sys/kernel/debug/habanalabs/hl<n>/dump_security_violations +Date: Jan 2021 +KernelVersion: 5.12 +Contact: ogabbay@kernel.org +Description: Dumps all security violations to dmesg. This will also ack + all security violations meanings those violations will not be + dumped next time user calls this API + What: /sys/kernel/debug/habanalabs/hl<n>/engines Date: Jul 2019 KernelVersion: 5.3 @@ -154,6 +190,16 @@ Description: Displays the hop values and physical address for a given ASID e.g. to display info about VA 0x1000 for ASID 1 you need to do: echo "1 0x1000" > /sys/kernel/debug/habanalabs/hl0/mmu +What: /sys/kernel/debug/habanalabs/hl<n>/mmu_error +Date: Mar 2021 +KernelVersion: 5.12 +Contact: fkassabri@habana.ai +Description: Check and display page fault or access violation mmu errors for + all MMUs specified in mmu_cap_mask. + e.g. to display error info for MMU hw cap bit 9, you need to do: + echo "0x200" > /sys/kernel/debug/habanalabs/hl0/mmu_error + cat /sys/kernel/debug/habanalabs/hl0/mmu_error + What: /sys/kernel/debug/habanalabs/hl<n>/set_power_state Date: Jan 2019 KernelVersion: 5.1 @@ -161,6 +207,13 @@ Contact: ogabbay@kernel.org Description: Sets the PCI power state. Valid values are "1" for D0 and "2" for D3Hot +What: /sys/kernel/debug/habanalabs/hl<n>/stop_on_err +Date: Mar 2020 +KernelVersion: 5.6 +Contact: ogabbay@kernel.org +Description: Sets the stop-on_error option for the device engines. Value of + "0" is for disable, otherwise enable. + What: /sys/kernel/debug/habanalabs/hl<n>/userptr Date: Jan 2019 KernelVersion: 5.1 @@ -174,19 +227,4 @@ Date: Jan 2019 KernelVersion: 5.1 Contact: ogabbay@kernel.org Description: Displays a list with information about all the active virtual - address mappings per ASID - -What: /sys/kernel/debug/habanalabs/hl<n>/stop_on_err -Date: Mar 2020 -KernelVersion: 5.6 -Contact: ogabbay@kernel.org -Description: Sets the stop-on_error option for the device engines. Value of - "0" is for disable, otherwise enable. - -What: /sys/kernel/debug/habanalabs/hl<n>/dump_security_violations -Date: Jan 2021 -KernelVersion: 5.12 -Contact: ogabbay@kernel.org -Description: Dumps all security violations to dmesg. This will also ack - all security violations meanings those violations will not be - dumped next time user calls this API + address mappings per ASID and all user mappings of HW blocks diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet index 6eee10c3d5a1..637d8587d03d 100644 --- a/Documentation/ABI/testing/debugfs-moxtet +++ b/Documentation/ABI/testing/debugfs-moxtet @@ -1,7 +1,7 @@ What: /sys/kernel/debug/moxtet/input Date: March 2019 KernelVersion: 5.3 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) Read input from the shift registers, in hexadecimal. Returns N+1 bytes, where N is the number of Moxtet connected modules. The first byte is from the CPU board itself. @@ -19,7 +19,7 @@ Description: (Read) Read input from the shift registers, in hexadecimal. What: /sys/kernel/debug/moxtet/output Date: March 2019 KernelVersion: 5.3 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (RW) Read last written value to the shift registers, in hexadecimal, or write values to the shift registers, also in hexadecimal. diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm index 326df1b74707..813987d5de4e 100644 --- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm +++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm @@ -1,7 +1,7 @@ What: /sys/kernel/debug/turris-mox-rwtm/do_sign Date: Jun 2020 KernelVersion: 5.8 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: ======= =========================================================== diff --git a/Documentation/ABI/testing/sysfs-block-rnbd b/Documentation/ABI/testing/sysfs-block-rnbd index 14a6fe9422b3..80b420b5d6b8 100644 --- a/Documentation/ABI/testing/sysfs-block-rnbd +++ b/Documentation/ABI/testing/sysfs-block-rnbd @@ -44,3 +44,21 @@ Date: Feb 2020 KernelVersion: 5.7 Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> Description: Contains the device access mode: ro, rw or migration. + +What: /sys/block/rnbd<N>/rnbd/resize +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Write the number of sectors to change the size of the disk. + +What: /sys/block/rnbd<N>/rnbd/remap_device +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Remap the disconnected device if the session is not destroyed yet. + +What: /sys/block/rnbd<N>/rnbd/nr_poll_queues +Date: Feb 2020 +KernelVersion: 5.7 +Contact: Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com> +Description: Contains the number of poll-mode queues diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index d957f5da5c04..267973541e72 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -33,6 +33,52 @@ Description: Description of the physical chip / device for device X. Typically a part number. +What: /sys/bus/iio/devices/iio:deviceX/label +KernelVersion: 5.8 +Contact: linux-iio@vger.kernel.org +Description: + Optional symbolic label for a device. + This is useful for userspace to be able to better identify an + individual device. + + The contents of the label are free-form, but there are some + standardized uses: + + For proximity sensors which give the proximity (of a person) to + a certain wlan or wwan antenna the following standardized labels + are used: + + * "proximity-wifi" + * "proximity-lte" + * "proximity-wifi-lte" + * "proximity-wifi-left" + * "proximity-wifi-right" + + These are used to indicate to userspace that these proximity + sensors may be used to tune transmit power to ensure that + Specific Absorption Rate (SAR) limits are honored. + The "-left" and "-right" labels are for devices with multiple + antennas. + + In some laptops/tablets the standardized proximity sensor labels + instead indicate proximity to a specific part of the device: + + * "proximity-palmrest" indicates proximity to the keyboard's palmrest + * "proximity-palmrest-left" indicates proximity to the left part of the palmrest + * "proximity-palmrest-right" indicates proximity to the right part of the palmrest + * "proximity-lap" indicates the device is being used on someone's lap + + Note "proximity-lap" is special in that its value may be + calculated by firmware from other sensor readings, rather then + being a raw sensor reading. + + For accelerometers used in 2-in-1s with 360° (yoga-style) hinges, + which have an accelerometer in both their base and their display, + the following standardized labels are used: + + * "accel-base" + * "accel-display" + What: /sys/bus/iio/devices/iio:deviceX/current_timestamp_clock KernelVersion: 4.5 Contact: linux-iio@vger.kernel.org @@ -325,6 +371,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_offset What: /sys/bus/iio/devices/iio:deviceX/in_magn_offset What: /sys/bus/iio/devices/iio:deviceX/in_rot_offset What: /sys/bus/iio/devices/iio:deviceX/in_angl_offset +What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceX_offset KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -656,6 +703,8 @@ What: /sys/.../iio:deviceX/events/in_voltageY_thresh_falling_en What: /sys/.../iio:deviceX/events/in_voltageY_thresh_either_en What: /sys/.../iio:deviceX/events/in_tempY_thresh_rising_en What: /sys/.../iio:deviceX/events/in_tempY_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_capacitanceY_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_capacitanceY_thresh_falling_en KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -733,6 +782,32 @@ Description: a given event type is enabled a future point (and not those for whatever event was previously enabled). +What: /sys/.../events/in_capacitanceY_adaptive_thresh_rising_en +What: /sys/.../events/in_capacitanceY_adaptive_thresh_falling_en +KernelVersion: 5.13 +Contact: linux-iio@vger.kernel.org +Descrption: + Adaptive thresholds are similar to normal fixed thresholds + but the value is expressed as an offset from a value which + provides a low frequency approximation of the channel itself. + Thus these detect if a rapid change occurs in the specified + direction which crosses tracking value + offset. + Tracking value calculation is devices specific. + +What: /sys/.../in_capacitanceY_adaptive_thresh_rising_timeout +What: /sys/.../in_capacitanceY_adaptive_thresh_falling_timeout +KernelVersion: 5.11 +Contact: linux-iio@vger.kernel.org +Descrption: + When adaptive thresholds are used, the tracking signal + may adjust too slowly to step changes in the raw signal. + *_timeout (in seconds) specifies a time for which the + difference between the slow tracking signal and the raw + signal is allowed to remain out-of-range before a reset + event occurs in which the tracking signal is made equal + to the raw signal, allowing slow tracking to resume and the + adaptive threshold event detection to function as expected. + What: /sys/.../events/in_accel_thresh_rising_value What: /sys/.../events/in_accel_thresh_falling_value What: /sys/.../events/in_accel_x_raw_thresh_rising_value @@ -773,6 +848,10 @@ What: /sys/.../events/in_proximity0_thresh_falling_value What: /sys/.../events/in_proximity0_thresh_rising_value What: /sys/.../events/in_illuminance_thresh_rising_value What: /sys/.../events/in_illuminance_thresh_falling_value +What: /sys/.../events/in_capacitanceY_thresh_rising_value +What: /sys/.../events/in_capacitanceY_thresh_falling_value +What: /sys/.../events/in_capacitanceY_thresh_adaptive_rising_value +What: /sys/.../events/in_capacitanceY_thresh_falling_rising_value KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -1118,12 +1197,16 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/buffer/length KernelVersion: 2.6.35 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/length +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Number of scans contained by the buffer. What: /sys/bus/iio/devices/iio:deviceX/buffer/enable KernelVersion: 2.6.35 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/enable +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Actually start the buffer capture up. Will start trigger @@ -1131,11 +1214,16 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/scan_elements KernelVersion: 2.6.37 +What: /sys/bus/iio/devices/iio:deviceX/bufferY +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Directory containing interfaces for elements that will be captured for a single triggered sample set in the buffer. + Since kernel 5.11 the scan_elements attributes are merged into + the bufferY directory, to be configurable per buffer. + What: /sys/.../iio:deviceX/scan_elements/in_accel_x_en What: /sys/.../iio:deviceX/scan_elements/in_accel_y_en What: /sys/.../iio:deviceX/scan_elements/in_accel_z_en @@ -1164,6 +1252,34 @@ What: /sys/.../iio:deviceX/scan_elements/in_pressure_en What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_en What: /sys/.../iio:deviceX/scan_elements/in_proximity_en KernelVersion: 2.6.37 +What: /sys/.../iio:deviceX/bufferY/in_accel_x_en +What: /sys/.../iio:deviceX/bufferY/in_accel_y_en +What: /sys/.../iio:deviceX/bufferY/in_accel_z_en +What: /sys/.../iio:deviceX/bufferY/in_anglvel_x_en +What: /sys/.../iio:deviceX/bufferY/in_anglvel_y_en +What: /sys/.../iio:deviceX/bufferY/in_anglvel_z_en +What: /sys/.../iio:deviceX/bufferY/in_magn_x_en +What: /sys/.../iio:deviceX/bufferY/in_magn_y_en +What: /sys/.../iio:deviceX/bufferY/in_magn_z_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_tilt_comp_en +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_tilt_comp_en +What: /sys/.../iio:deviceX/bufferY/in_timestamp_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY-voltageZ_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_i_en +What: /sys/.../iio:deviceX/bufferY/in_voltageY_q_en +What: /sys/.../iio:deviceX/bufferY/in_voltage_i_en +What: /sys/.../iio:deviceX/bufferY/in_voltage_q_en +What: /sys/.../iio:deviceX/bufferY/in_incli_x_en +What: /sys/.../iio:deviceX/bufferY/in_incli_y_en +What: /sys/.../iio:deviceX/bufferY/in_pressureY_en +What: /sys/.../iio:deviceX/bufferY/in_pressure_en +What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_en +What: /sys/.../iio:deviceX/bufferY/in_proximity_en +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Scan element control for triggered data capture. @@ -1185,6 +1301,23 @@ What: /sys/.../iio:deviceX/scan_elements/in_pressure_type What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_type What: /sys/.../iio:deviceX/scan_elements/in_proximity_type KernelVersion: 2.6.37 +What: /sys/.../iio:deviceX/bufferY/in_accel_type +What: /sys/.../iio:deviceX/bufferY/in_anglvel_type +What: /sys/.../iio:deviceX/bufferY/in_magn_type +What: /sys/.../iio:deviceX/bufferY/in_incli_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_type +What: /sys/.../iio:deviceX/bufferY/in_voltage_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_i_type +What: /sys/.../iio:deviceX/bufferY/in_voltageY_q_type +What: /sys/.../iio:deviceX/bufferY/in_voltage_i_type +What: /sys/.../iio:deviceX/bufferY/in_voltage_q_type +What: /sys/.../iio:deviceX/bufferY/in_timestamp_type +What: /sys/.../iio:deviceX/bufferY/in_pressureY_type +What: /sys/.../iio:deviceX/bufferY/in_pressure_type +What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_type +What: /sys/.../iio:deviceX/bufferY/in_proximity_type +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: Description of the scan element data storage within the buffer @@ -1241,6 +1374,33 @@ What: /sys/.../iio:deviceX/scan_elements/in_pressure_index What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_index What: /sys/.../iio:deviceX/scan_elements/in_proximity_index KernelVersion: 2.6.37 +What: /sys/.../iio:deviceX/bufferY/in_voltageY_index +What: /sys/.../iio:deviceX/bufferY/in_voltageY_supply_index +What: /sys/.../iio:deviceX/bufferY/in_voltageY_i_index +What: /sys/.../iio:deviceX/bufferY/in_voltageY_q_index +What: /sys/.../iio:deviceX/bufferY/in_voltage_i_index +What: /sys/.../iio:deviceX/bufferY/in_voltage_q_index +What: /sys/.../iio:deviceX/bufferY/in_accel_x_index +What: /sys/.../iio:deviceX/bufferY/in_accel_y_index +What: /sys/.../iio:deviceX/bufferY/in_accel_z_index +What: /sys/.../iio:deviceX/bufferY/in_anglvel_x_index +What: /sys/.../iio:deviceX/bufferY/in_anglvel_y_index +What: /sys/.../iio:deviceX/bufferY/in_anglvel_z_index +What: /sys/.../iio:deviceX/bufferY/in_magn_x_index +What: /sys/.../iio:deviceX/bufferY/in_magn_y_index +What: /sys/.../iio:deviceX/bufferY/in_magn_z_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_magnetic_tilt_comp_index +What: /sys/.../iio:deviceX/bufferY/in_rot_from_north_true_tilt_comp_index +What: /sys/.../iio:deviceX/bufferY/in_incli_x_index +What: /sys/.../iio:deviceX/bufferY/in_incli_y_index +What: /sys/.../iio:deviceX/bufferY/in_timestamp_index +What: /sys/.../iio:deviceX/bufferY/in_pressureY_index +What: /sys/.../iio:deviceX/bufferY/in_pressure_index +What: /sys/.../iio:deviceX/bufferY/in_rot_quaternion_index +What: /sys/.../iio:deviceX/bufferY/in_proximity_index +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: A single positive integer specifying the position of this @@ -1455,6 +1615,8 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/buffer/watermark KernelVersion: 4.2 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/watermark +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: A single positive integer specifying the maximum number of scan @@ -1473,6 +1635,8 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/buffer/data_available KernelVersion: 4.16 +What: /sys/bus/iio/devices/iio:deviceX/bufferY/data_available +KernelVersion: 5.11 Contact: linux-iio@vger.kernel.org Description: A read-only value indicating the bytes of data available in the @@ -1823,3 +1987,12 @@ Description: hinge, keyboard, screen. It means the three channels each correspond respectively to hinge angle, keyboard angle, and screen angle. + +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_hysteresis_relative +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_hysteresis_relative +KernelVersion: 5.12 +Contact: linux-iio@vger.kernel.org +Description: + Specify the percent for light sensor relative to the channel + absolute value that a data field should change before an event + is generated. Units are a percentage of the prior reading. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 b/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 deleted file mode 100644 index bac3d0d48b7b..000000000000 --- a/Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8 +++ /dev/null @@ -1,133 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/in_count_count_mode_available -What: /sys/bus/iio/devices/iio:deviceX/in_count_noise_error_available -What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available -What: /sys/bus/iio/devices/iio:deviceX/in_index_index_polarity_available -What: /sys/bus/iio/devices/iio:deviceX/in_index_synchronous_mode_available -KernelVersion: 4.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. - -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. - - 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 preset value, while the lower limit is set to 0. The - counter freezes at count = preset when counting up, and - at count = 0 when counting down. At either of these - limits, the counting is resumed only when the count - direction is reversed. - - Non-recycle: - Counter is disabled whenever a 24-bit count 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 write to raw. - - Modulo-N: - A count boundary is set between 0 and the preset value. - The counter is reset to 0 at count = preset when - counting up, while the counter is set to the preset - value at count = 0 when counting down; the counter does - not freeze at the bundary points, but counts - continuously throughout. - -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. - -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. - -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 - scale attribute selects the encoder phase division (scale of 1 - selects full-cycle, scale of 0.5 selects half-cycle, scale of - 0.25 selects quarter-cycle) processed by the channel Y counter. - - Non-quadrature: - The filter and decoder circuit are bypassed. Encoder A - input serves as the count input and B as the UP/DOWN - direction control input, with B = 1 selecting UP Count - mode and B = 0 selecting Down Count mode. - - Quadrature: - Encoder A and B inputs are digitally filtered and - decoded for UP/DN clock. - -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. - -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. - -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. - - Non-synchronous: - A logic low level is the active level at this index - input. The index function (as enabled via - set_to_preset_on_index) 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 - set_to_preset_on_index) is performed synchronously with - the quadrature clock on the active level of the index - input. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 index 40df5c9fef99..9dae94aa880b 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 +++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 @@ -1,11 +1,3 @@ -What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity -Date: January 2017 -KernelVersion: 4.11 -Contact: linux-iio@vger.kernel.org -Description: - Show or set the gain boost of the amp, from 0-31 range. - default 31 - What: /sys/bus/iio/devices/iio:deviceX/sensor_max_range Date: January 2017 KernelVersion: 4.11 diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 b/Documentation/ABI/testing/sysfs-bus-iio-humidity index 5b78af5f341d..cb0d7e75d297 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 +++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity @@ -6,4 +6,5 @@ Description: Controls the heater device within the humidity sensor to get rid of excess condensation. - Valid control values are 0 = OFF, and 1 = ON. + In some devices, this is just a switch in which case 0 = OFF, + and 1 = ON. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x deleted file mode 100644 index b72bb62552cf..000000000000 --- a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x +++ /dev/null @@ -1,9 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw -What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available -KernelVersion: 4.3 -Contact: linux-iio@vger.kernel.org -Description: - Controls the heater device within the humidity sensor to get - rid of excess condensation. - - Valid control values are 0 = OFF, and 1 = ON. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 deleted file mode 100644 index 73498ff666bd..000000000000 --- a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 +++ /dev/null @@ -1,62 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/in_count0_preset -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Reading returns the current preset value. Writing sets the - preset value. Encoder counts continuously from 0 to preset - value, depending on direction (up/down). - -What: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Reading returns the list possible quadrature modes. - -What: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Configure the device counter quadrature modes: - - - non-quadrature: - Encoder IN1 input servers as the count input (up - direction). - - - quadrature: - Encoder IN1 and IN2 inputs are mixed to get direction - and count. - -What: /sys/bus/iio/devices/iio:deviceX/in_count_polarity_available -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Reading returns the list possible active edges. - -What: /sys/bus/iio/devices/iio:deviceX/in_count0_polarity -KernelVersion: 4.13 -Contact: fabrice.gasnier@st.com -Description: - Configure the device encoder/counter active edge: - - - rising-edge - - falling-edge - - both-edges - - In non-quadrature mode, device counts up on active edge. - - In quadrature mode, encoder counting scenarios are as follows: - - +---------+----------+--------------------+--------------------+ - | Active | Level on | IN1 signal | IN2 signal | - | edge | opposite +----------+---------+----------+---------+ - | | signal | Rising | Falling | Rising | Falling | - +---------+----------+----------+---------+----------+---------+ - | Rising | High -> | Down | - | Up | - | - | edge | Low -> | Up | - | Down | - | - +---------+----------+----------+---------+----------+---------+ - | Falling | High -> | - | Up | - | Down | - | edge | Low -> | - | Down | - | Up | - +---------+----------+----------+---------+----------+---------+ - | Both | High -> | Down | Up | Up | Down | - | edges | Low -> | Up | Down | Down | Up | - +---------+----------+----------+---------+----------+---------+ diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity b/Documentation/ABI/testing/sysfs-bus-iio-proximity index 2172f3bb9c64..3aac6dab8775 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity @@ -8,3 +8,17 @@ Description: considered close to the device. If the value read from the sensor is above or equal to the value in this file an object should typically be considered near. + +What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity +Date: March 2014 +KernelVersion: 3.15 +Contact: linux-iio@vger.kernel.org +Description: + Proximity sensors sometimes have a controllable amplifier + on the signal from which time of flight measurements are + taken. + The appropriate values to take is dependent on both the + sensor and it's operating environment: + * as3935 (0-31 range) + 18 = indoors (default) + 14 = outdoors diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 index c59d95346341..1e5c40775a6c 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 @@ -6,15 +6,6 @@ Description: Get the current distance in meters of storm (1km steps) 1000-40000 = distance in meters -What: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity -Date: March 2014 -KernelVersion: 3.15 -Contact: Matt Ranostay <matt.ranostay@konsulko.com> -Description: - Show or set the gain boost of the amp, from 0-31 range. - 18 = indoors (default) - 14 = outdoors - What /sys/bus/iio/devices/iio:deviceX/noise_level_tripped Date: May 2017 KernelVersion: 4.13 diff --git a/Documentation/ABI/testing/sysfs-bus-moxtet-devices b/Documentation/ABI/testing/sysfs-bus-moxtet-devices index 4a6d61b44f3f..32dccc00d57d 100644 --- a/Documentation/ABI/testing/sysfs-bus-moxtet-devices +++ b/Documentation/ABI/testing/sysfs-bus-moxtet-devices @@ -1,17 +1,17 @@ What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_description Date: March 2019 KernelVersion: 5.3 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) Moxtet module description. Format: string What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_id Date: March 2019 KernelVersion: 5.3 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) Moxtet module ID. Format: %x What: /sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_name Date: March 2019 KernelVersion: 5.3 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) Moxtet module name. Format: string diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 25c9c39770c6..1241b6d11a52 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -195,10 +195,13 @@ What: /sys/bus/pci/devices/.../index Date: July 2010 Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com Description: - Reading this attribute will provide the firmware - given instance (SMBIOS type 41 device type instance) of the - PCI device. The attribute will be created only if the firmware - has given an instance number to the PCI device. + Reading this attribute will provide the firmware given instance + number of the PCI device. Depending on the platform this can + be for example the SMBIOS type 41 device type instance or the + user-defined ID (UID) on s390. The attribute will be created + only if the firmware has given an instance number to the PCI + device and that number is guaranteed to uniquely identify the + device in the system. Users: Userspace applications interested in knowing the firmware assigned device type instance of the PCI diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic b/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic index 1936f7324155..4ec03cd36357 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-pvpanic @@ -1,4 +1,5 @@ -What: /sys/devices/pci0000:00/*/QEMU0001:00/capability +What: /sys/devices/pci0000:00/*/QEMU0001:00/capability for MMIO + /sys/bus/pci/drivers/pvpanic-pci/0000:00:0*.0/capability for PCI Date: Jan 2021 Contact: zhenwei pi <pizhenwei@bytedance.com> Description: @@ -12,6 +13,7 @@ Description: https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/specs/pvpanic.txt What: /sys/devices/pci0000:00/*/QEMU0001:00/events + /sys/bus/pci/drivers/pvpanic-pci/0000:00:0*.0/events for PCI Date: Jan 2021 Contact: zhenwei pi <pizhenwei@bytedance.com> Description: diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index d7f09d011b6d..c41c68f64693 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -1,31 +1,3 @@ -What: /sys/bus/thunderbolt/devices/<xdomain>/rx_speed -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the XDomain RX speed per lane. - All RX lanes run at the same speed. - -What: /sys/bus/thunderbolt/devices/<xdomain>/rx_lanes -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the number of RX lanes the XDomain - is using simultaneously through its upstream port. - -What: /sys/bus/thunderbolt/devices/<xdomain>/tx_speed -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports the XDomain TX speed per lane. - All TX lanes run at the same speed. - -What: /sys/bus/thunderbolt/devices/<xdomain>/tx_lanes -Date: Feb 2021 -KernelVersion: 5.11 -Contact: Isaac Hazan <isaac.hazan@intel.com> -Description: This attribute reports number of TX lanes the XDomain - is using simultaneously through its upstream port. - What: /sys/bus/thunderbolt/devices/.../domainX/boot_acl Date: Jun 2018 KernelVersion: 4.17 @@ -162,6 +134,13 @@ Contact: thunderbolt-software@lists.01.org Description: This attribute contains name of this device extracted from the device DROM. +What: /sys/bus/thunderbolt/devices/.../maxhopid +Date: Jul 2021 +KernelVersion: 5.13 +Contact: Mika Westerberg <mika.westerberg@linux.intel.com> +Description: Only set for XDomains. The maximum HopID the other host + supports as its input HopID. + What: /sys/bus/thunderbolt/devices/.../rx_speed Date: Jan 2020 KernelVersion: 5.5 diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq index 386bc230a33d..5e6b74f30406 100644 --- a/Documentation/ABI/testing/sysfs-class-devfreq +++ b/Documentation/ABI/testing/sysfs-class-devfreq @@ -97,10 +97,7 @@ Description: object. The values are represented in ms. If the value is less than 1 jiffy, it is considered to be 0, which means no polling. This value is meaningless if the governor is - not polling; thus. If the governor is not using - devfreq-provided central polling - (/sys/class/devfreq/.../central_polling is 0), this value - may be useless. + not polling. A list of governors that support the node: - simple_ondmenad diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia index 795a5de12fc1..c4d46970c1cf 100644 --- a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia +++ b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia @@ -1,7 +1,7 @@ What: /sys/class/leds/<led>/device/brightness Date: July 2020 KernelVersion: 5.9 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (RW) On the front panel of the Turris Omnia router there is also a button which can be used to control the intensity of all the LEDs at once, so that if they are too bright, user can dim them. diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client index 2aa05b3e348e..0b5997ab3365 100644 --- a/Documentation/ABI/testing/sysfs-class-rnbd-client +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client @@ -85,6 +85,19 @@ Description: Expected format is the following:: By default "rw" is used. + nr_poll_queues + specifies the number of poll-mode queues. If the IO has HIPRI flag, + the block-layer will send the IO via the poll-mode queue. + For fast network and device the polling is faster than interrupt-base + IO handling because it saves time for context switching, switching to + another process, handling the interrupt and switching back to the + issuing process. + + Set -1 if you want to set it as the number of CPUs + By default rnbd client creates only irq-mode queues. + + NOTICE: MUST make a unique session for a device using the poll-mode queues. + Exit Codes: If the device is already mapped it will fail with EEXIST. If the input diff --git a/Documentation/ABI/testing/sysfs-driver-xdata b/Documentation/ABI/testing/sysfs-driver-xdata new file mode 100644 index 000000000000..f574e8e6dca2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-xdata @@ -0,0 +1,49 @@ +What: /sys/class/misc/drivers/dw-xdata-pcie.<device>/write +Date: April 2021 +KernelVersion: 5.13 +Contact: Gustavo Pimentel <gustavo.pimentel@synopsys.com> +Description: Allows the user to enable the PCIe traffic generator which + will create write TLPs frames - from the Root Complex to the + Endpoint direction or to disable the PCIe traffic generator + in all directions. + + Write y/1/on to enable, n/0/off to disable + + Usage e.g. + echo 1 > /sys/class/misc/dw-xdata-pcie.<device>/write + or + echo 0 > /sys/class/misc/dw-xdata-pcie.<device>/write + + The user can read the current PCIe link throughput generated + through this generator in MB/s. + + Usage e.g. + cat /sys/class/misc/dw-xdata-pcie.<device>/write + 204 + + The file is read and write. + +What: /sys/class/misc/dw-xdata-pcie.<device>/read +Date: April 2021 +KernelVersion: 5.13 +Contact: Gustavo Pimentel <gustavo.pimentel@synopsys.com> +Description: Allows the user to enable the PCIe traffic generator which + will create read TLPs frames - from the Endpoint to the Root + Complex direction or to disable the PCIe traffic generator + in all directions. + + Write y/1/on to enable, n/0/off to disable + + Usage e.g. + echo 1 > /sys/class/misc/dw-xdata-pcie.<device>/read + or + echo 0 > /sys/class/misc/dw-xdata-pcie.<device>/read + + The user can read the current PCIe link throughput generated + through this generator in MB/s. + + Usage e.g. + cat /sys/class/misc/dw-xdata-pcie.<device>/read + 199 + + The file is read and write. diff --git a/Documentation/ABI/testing/sysfs-firmware-sgi_uv b/Documentation/ABI/testing/sysfs-firmware-sgi_uv index 637c668cbe45..12ed843e1d3e 100644 --- a/Documentation/ABI/testing/sysfs-firmware-sgi_uv +++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv @@ -39,8 +39,8 @@ Description: The uv_type entry contains the hub revision number. This value can be used to identify the UV system version:: - "0.*" = Hubless UV ('*' is subtype) + "0.*" = Hubless UV ('*' is subtype) "3.0" = UV2 "5.0" = UV3 "7.0" = UV4 diff --git a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm index b8631f5a29c4..ea5e5b489bc7 100644 --- a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm +++ b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm @@ -1,21 +1,21 @@ What: /sys/firmware/turris-mox-rwtm/board_version Date: August 2019 KernelVersion: 5.4 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) Board version burned into eFuses of this Turris Mox board. Format: %i What: /sys/firmware/turris-mox-rwtm/mac_address* Date: August 2019 KernelVersion: 5.4 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) MAC addresses burned into eFuses of this Turris Mox board. Format: %pM What: /sys/firmware/turris-mox-rwtm/pubkey Date: August 2019 KernelVersion: 5.4 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) ECDSA public key (in pubkey hex compressed form) computed as pair to the ECDSA private key burned into eFuses of this Turris Mox Board. @@ -24,7 +24,7 @@ Description: (Read) ECDSA public key (in pubkey hex compressed form) computed What: /sys/firmware/turris-mox-rwtm/ram_size Date: August 2019 KernelVersion: 5.4 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) RAM size in MiB of this Turris Mox board as was detected during manufacturing and burned into eFuses. Can be 512 or 1024. Format: %i @@ -32,6 +32,6 @@ Description: (Read) RAM size in MiB of this Turris Mox board as was detected What: /sys/firmware/turris-mox-rwtm/serial_number Date: August 2019 KernelVersion: 5.4 -Contact: Marek Behún <marek.behun@nic.cz> +Contact: Marek Behún <kabel@kernel.org> Description: (Read) Serial number burned into eFuses of this Turris Mox device. Format: %016X diff --git a/Documentation/ABI/testing/sysfs-fs-xfs b/Documentation/ABI/testing/sysfs-fs-xfs index ea0cc8c42093..f704925f6fe9 100644 --- a/Documentation/ABI/testing/sysfs-fs-xfs +++ b/Documentation/ABI/testing/sysfs-fs-xfs @@ -33,7 +33,7 @@ Contact: xfs@oss.sgi.com Description: The current state of the log write grant head. It represents the total log reservation of all currently - oustanding transactions, including regrants due to + outstanding transactions, including regrants due to rolling transactions. The grant head is exported in "cycle:bytes" format. Users: xfstests diff --git a/Documentation/ABI/testing/sysfs-platform-intel-pmc b/Documentation/ABI/testing/sysfs-platform-intel-pmc new file mode 100644 index 000000000000..ef199af75ab0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-intel-pmc @@ -0,0 +1,20 @@ +What: /sys/devices/platform/<platform>/etr3 +Date: Apr 2021 +KernelVersion: 5.13 +Contact: "Tomas Winkler" <tomas.winkler@intel.com> +Description: + The file exposes "Extended Test Mode Register 3" global + reset bits. The bits are used during an Intel platform + manufacturing process to indicate that consequent reset + of the platform is a "global reset". This type of reset + is required in order for manufacturing configurations + to take effect. + + Display global reset setting bits for PMC. + * bit 31 - global reset is locked + * bit 20 - global reset is set + Writing bit 20 value to the etr3 will induce + a platform "global reset" upon consequent platform reset, + in case the register is not locked. + The "global reset bit" should be locked on a production + system and the file is in read-only mode. diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt index 3b0876c77355..588d97366a46 100644 --- a/Documentation/RCU/RTFP.txt +++ b/Documentation/RCU/RTFP.txt @@ -847,7 +847,7 @@ Symposium on Distributed Computing} 'It's entirely possible that the current user could be replaced by RCU and/or seqlocks, and we could get rid of brlocks entirely.' . - Steve Hemminger responds by replacing them with RCU. + Stephen Hemminger responds by replacing them with RCU. } } diff --git a/Documentation/admin-guide/LSM/LoadPin.rst b/Documentation/admin-guide/LSM/LoadPin.rst index 716ad9b23c9a..dd3ca68b5df1 100644 --- a/Documentation/admin-guide/LSM/LoadPin.rst +++ b/Documentation/admin-guide/LSM/LoadPin.rst @@ -11,8 +11,8 @@ restrictions without needing to sign the files individually. The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and can be controlled at boot-time with the kernel command line option -"``loadpin.enabled``". By default, it is enabled, but can be disabled at -boot ("``loadpin.enabled=0``"). +"``loadpin.enforce``". By default, it is enabled, but can be disabled at +boot ("``loadpin.enforce=0``"). LoadPin starts pinning when it sees the first file loaded. If the block device backing the filesystem is not read-only, a sysctl is @@ -28,4 +28,4 @@ different mechanisms such as ``CONFIG_MODULE_SIG`` and ``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while still use LoadPin to protect the integrity of other files kernel loads. The full list of valid file types can be found in ``kernel_read_file_str`` -defined in ``include/linux/fs.h``. +defined in ``include/linux/kernel_read_file.h``. diff --git a/Documentation/admin-guide/cgroup-v1/index.rst b/Documentation/admin-guide/cgroup-v1/index.rst index 226f64473e8e..99fbc8a64ba9 100644 --- a/Documentation/admin-guide/cgroup-v1/index.rst +++ b/Documentation/admin-guide/cgroup-v1/index.rst @@ -17,6 +17,7 @@ Control Groups version 1 hugetlb memcg_test memory + misc net_cls net_prio pids diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index 0936412e044e..41191b5fb69d 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -360,8 +360,8 @@ U != 0, K = unlimited: U != 0, K < U: Kernel memory is a subset of the user memory. This setup is useful in - deployments where the total amount of memory per-cgroup is overcommited. - Overcommiting kernel memory limits is definitely not recommended, since the + deployments where the total amount of memory per-cgroup is overcommitted. + Overcommitting kernel memory limits is definitely not recommended, since the box can still run out of non-reclaimable memory. In this case, the admin could set up K so that the sum of all groups is never greater than the total memory, and freely set U at the cost of his @@ -851,6 +851,9 @@ At reading, current status of OOM is shown. (if 1, oom-killer is disabled) - under_oom 0 or 1 (if 1, the memory cgroup is under OOM, tasks may be stopped.) + - oom_kill integer counter + The number of processes belonging to this cgroup killed by any + kind of OOM killer. 11. Memory Pressure =================== diff --git a/Documentation/admin-guide/cgroup-v1/misc.rst b/Documentation/admin-guide/cgroup-v1/misc.rst new file mode 100644 index 000000000000..661614c24df3 --- /dev/null +++ b/Documentation/admin-guide/cgroup-v1/misc.rst @@ -0,0 +1,4 @@ +=============== +Misc controller +=============== +Please refer "Misc" documentation in Documentation/admin-guide/cgroup-v2.rst diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 64c62b979f2f..b1e81aa8598a 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -65,8 +65,11 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgrou 5-7-1. RDMA Interface Files 5-8. HugeTLB 5.8-1. HugeTLB Interface Files - 5-8. Misc - 5-8-1. perf_event + 5-9. Misc + 5.9-1 Miscellaneous cgroup Interface Files + 5.9-2 Migration and Ownership + 5-10. Others + 5-10-1. perf_event 5-N. Non-normative information 5-N-1. CPU controller root cgroup process behaviour 5-N-2. IO controller root cgroup process behaviour @@ -2171,6 +2174,72 @@ HugeTLB Interface Files Misc ---- +The Miscellaneous cgroup provides the resource limiting and tracking +mechanism for the scalar resources which cannot be abstracted like the other +cgroup resources. Controller is enabled by the CONFIG_CGROUP_MISC config +option. + +A resource can be added to the controller via enum misc_res_type{} in the +include/linux/misc_cgroup.h file and the corresponding name via misc_res_name[] +in the kernel/cgroup/misc.c file. Provider of the resource must set its +capacity prior to using the resource by calling misc_cg_set_capacity(). + +Once a capacity is set then the resource usage can be updated using charge and +uncharge APIs. All of the APIs to interact with misc controller are in +include/linux/misc_cgroup.h. + +Misc Interface Files +~~~~~~~~~~~~~~~~~~~~ + +Miscellaneous controller provides 3 interface files. If two misc resources (res_a and res_b) are registered then: + + misc.capacity + A read-only flat-keyed file shown only in the root cgroup. It shows + miscellaneous scalar resources available on the platform along with + their quantities:: + + $ cat misc.capacity + res_a 50 + res_b 10 + + misc.current + A read-only flat-keyed file shown in the non-root cgroups. It shows + the current usage of the resources in the cgroup and its children.:: + + $ cat misc.current + res_a 3 + res_b 0 + + misc.max + A read-write flat-keyed file shown in the non root cgroups. Allowed + maximum usage of the resources in the cgroup and its children.:: + + $ cat misc.max + res_a max + res_b 4 + + Limit can be set by:: + + # echo res_a 1 > misc.max + + Limit can be set to max by:: + + # echo res_a max > misc.max + + Limits can be set higher than the capacity value in the misc.capacity + file. + +Migration and Ownership +~~~~~~~~~~~~~~~~~~~~~~~ + +A miscellaneous scalar resource is charged to the cgroup in which it is used +first, and stays charged to that cgroup until that resource is freed. Migrating +a process to a different cgroup does not move the charge to the destination +cgroup where the process has moved. + +Others +------ + perf_event ~~~~~~~~~~ diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst index 13783dc68ab7..f170d8820258 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -714,6 +714,7 @@ DebugData Displays information about active CIFS sessions and version. Stats Lists summary resource usage information as well as per share statistics. +open_files List all the open file handles on all active SMB sessions. ======================= ======================================================= Configuration pseudo-files: @@ -794,6 +795,8 @@ LinuxExtensionsEnabled If set to one then the client will attempt to support and want to map the uid and gid fields to values supplied at mount (rather than the actual values, then set this to zero. (default 1) +dfscache List the content of the DFS cache. + If set to 0, the client will clear the cache. ======================= ======================================================= These experimental features and tracing can be enabled by changing flags in diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index 63fd4e6a014b..ef41f77cb979 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -289,7 +289,7 @@ 152 = /dev/kpoll Kernel Poll Driver 153 = /dev/mergemem Memory merge device 154 = /dev/pmu Macintosh PowerBook power manager - 155 = /dev/isictl MultiTech ISICom serial control + 155 = 156 = /dev/lcd Front panel LCD display 157 = /dev/ac Applicom Intl Profibus card 158 = /dev/nwbutton Netwinder external button @@ -477,11 +477,6 @@ 18 block Sanyo CD-ROM 0 = /dev/sjcd Sanyo CD-ROM - 19 char Cyclades serial card - 0 = /dev/ttyC0 First Cyclades port - ... - 31 = /dev/ttyC31 32nd Cyclades port - 19 block "Double" compressed disk 0 = /dev/double0 First compressed disk ... @@ -493,11 +488,6 @@ See the Double documentation for the meaning of the mirror devices. - 20 char Cyclades serial card - alternate devices - 0 = /dev/cub0 Callout device for ttyC0 - ... - 31 = /dev/cub31 Callout device for ttyC31 - 20 block Hitachi CD-ROM (under development) 0 = /dev/hitcd Hitachi CD-ROM diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 6c04aea8f4cd..b119b8277b3e 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -347,7 +347,7 @@ Examples <debugfs>/dynamic_debug/control // enable messages in files of which the paths include string "usb" - nullarbor:~ # echo -n '*usb* +p' > <debugfs>/dynamic_debug/control + nullarbor:~ # echo -n 'file *usb* +p' > <debugfs>/dynamic_debug/control // enable all messages nullarbor:~ # echo -n '+p' > <debugfs>/dynamic_debug/control diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 423116c4e787..dc00afcabb95 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -35,7 +35,6 @@ problems and bugs in particular. :maxdepth: 1 reporting-issues - Reporting bugs (obsolete) <reporting-bugs> security-bugs bug-hunting bug-bisect diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 1132796a8d96..3996b54158bf 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -68,6 +68,13 @@ For example one can add to the command line following parameter: where the final item represents CPUs 100,101,125,126,150,151,... +The value "N" can be used to represent the numerically last CPU on the system, +i.e "foo_cpus=16-N" would be equivalent to "16-31" on a 32 core system. + +Keep in mind that "N" is dynamic, so if system changes cause the bitmap width +to change, such as less cores in the CPU list, then N and any ranges using N +will also change. Use the same on a small 4 core system, and "16-N" becomes +"16-3" and now the same boot input will be flagged as invalid (start > end). This document may not be entirely up to date and comprehensive. The command @@ -140,6 +147,7 @@ parameter is applicable:: PPT Parallel port support is enabled. PS2 Appropriate PS/2 support is enabled. RAM RAM disk support is enabled. + RISCV RISCV architecture is enabled. RDT Intel Resource Director Technology. S390 S390 architecture is enabled. SCSI Appropriate SCSI support is enabled. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index fcd0fc8fd977..5c949c12ed07 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -50,7 +50,7 @@ CONFIG_ACPI_DEBUG must be enabled to produce any ACPI debug output. Bits in debug_layer correspond to a _COMPONENT in an ACPI source file, e.g., - #define _COMPONENT ACPI_PCI_COMPONENT + #define _COMPONENT ACPI_EVENTS Bits in debug_level correspond to a level in ACPI_DEBUG_PRINT statements, e.g., ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... @@ -60,8 +60,6 @@ Enable processor driver info messages: acpi.debug_layer=0x20000000 - Enable PCI/PCI interrupt routing info messages: - acpi.debug_layer=0x400000 Enable AML "Debug" output, i.e., stores to the Debug object while interpreting AML: acpi.debug_layer=0xffffffff acpi.debug_level=0x2 @@ -784,6 +782,16 @@ cs89x0_media= [HW,NET] Format: { rj45 | aui | bnc } + csdlock_debug= [KNL] Enable debug add-ons of cross-CPU function call + handling. When switched on, additional debug data is + printed to the console in case a hanging CPU is + detected, and that CPU is pinged again in order to try + to resolve the hang situation. + 0: disable csdlock debugging (default) + 1: enable basic csdlock debugging (minor impact) + ext: enable extended csdlock debugging (more impact, + but more data) + dasd= [HW,NET] See header of drivers/s390/block/dasd_devmap.c. @@ -2279,8 +2287,7 @@ state is kept private from the host. Not valid if the kernel is running in EL2. - Defaults to VHE/nVHE based on hardware support and - the value of CONFIG_ARM64_VHE. + Defaults to VHE/nVHE based on hardware support. kvm-arm.vgic_v3_group0_trap= [KVM,ARM] Trap guest accesses to GICv3 group-0 @@ -3472,7 +3479,8 @@ nr_uarts= [SERIAL] maximum number of UARTs to be registered. - numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. + numa_balancing= [KNL,ARM64,PPC,RISCV,S390,X86] Enable or disable automatic + NUMA balancing. Allowed values are enable and disable numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. @@ -4151,6 +4159,17 @@ fully seed the kernel's CRNG. Default is controlled by CONFIG_RANDOM_TRUST_CPU. + randomize_kstack_offset= + [KNL] Enable or disable kernel stack offset + randomization, which provides roughly 5 bits of + entropy, frustrating memory corruption attacks + that depend on stack address determinism or + cross-syscall address exposures. This is only + available on architectures that have defined + CONFIG_HAVE_ARCH_RANDOMIZE_KSTACK_OFFSET. + Format: <bool> (1/Y/y=enable, 0/N/n=disable) + Default is CONFIG_RANDOMIZE_KSTACK_OFFSET_DEFAULT. + ras=option[,option,...] [KNL] RAS-specific options cec_disable [X86] @@ -4158,9 +4177,7 @@ see CONFIG_RAS_CEC help text. rcu_nocbs= [KNL] - The argument is a cpu list, as described above, - except that the string "all" can be used to - specify every CPU on the system. + The argument is a cpu list, as described above. In kernels built with CONFIG_RCU_NOCB_CPU=y, set the specified list of CPUs to be no-callback CPUs. @@ -4349,6 +4366,18 @@ rcuscale.kfree_rcu_test= [KNL] Set to measure performance of kfree_rcu() flooding. + rcuscale.kfree_rcu_test_double= [KNL] + Test the double-argument variant of kfree_rcu(). + If this parameter has the same value as + rcuscale.kfree_rcu_test_single, both the single- + and double-argument variants are tested. + + rcuscale.kfree_rcu_test_single= [KNL] + Test the single-argument variant of kfree_rcu(). + If this parameter has the same value as + rcuscale.kfree_rcu_test_double, both the single- + and double-argument variants are tested. + rcuscale.kfree_nthreads= [KNL] The number of threads running loops of kfree_rcu(). @@ -4815,7 +4844,7 @@ sbni= [NET] Granch SBNI12 leased line adapter - sched_debug [KNL] Enables verbose scheduler debug messages. + sched_verbose [KNL] Enables verbose scheduler debug messages. schedstats= [KNL,X86] Enable or disable scheduled statistics. Allowed values are enable and disable. This feature @@ -5190,27 +5219,37 @@ spia_peddr= split_lock_detect= - [X86] Enable split lock detection + [X86] Enable split lock detection or bus lock detection When enabled (and if hardware support is present), atomic instructions that access data across cache line - boundaries will result in an alignment check exception. + boundaries will result in an alignment check exception + for split lock detection or a debug exception for + bus lock detection. off - not enabled - warn - the kernel will emit rate limited warnings + warn - the kernel will emit rate-limited warnings about applications triggering the #AC - exception. This mode is the default on CPUs - that supports split lock detection. + exception or the #DB exception. This mode is + the default on CPUs that support split lock + detection or bus lock detection. Default + behavior is by #AC if both features are + enabled in hardware. fatal - the kernel will send SIGBUS to applications - that trigger the #AC exception. + that trigger the #AC exception or the #DB + exception. Default behavior is by #AC if + both features are enabled in hardware. If an #AC exception is hit in the kernel or in firmware (i.e. not while executing in user mode) the kernel will oops in either "warn" or "fatal" mode. + #DB exception for bus lock is triggered only when + CPL > 0. + srbds= [X86,INTEL] Control the Special Register Buffer Data Sampling (SRBDS) mitigation. @@ -5552,6 +5591,18 @@ See Documentation/admin-guide/mm/transhuge.rst for more details. + trusted.source= [KEYS] + Format: <string> + This parameter identifies the trust source as a backend + for trusted keys implementation. Supported trust + sources: + - "tpm" + - "tee" + If not specified then it defaults to iterating through + the trust source list starting with TPM and assigns the + first trust source as a backend which is initialized + successfully during iteration. + tsc= Disable clocksource stability checks for TSC. Format: <string> [x86] reliable: mark tsc clocksource as reliable, this diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 531f689311f2..5e51ee5b0358 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -332,23 +332,3 @@ To reduce its OS jitter, do at least one of the following: kthreads from being created in the first place. However, please note that this will not eliminate OS jitter, but will instead shift it to RCU_SOFTIRQ. - -Name: - watchdog/%u - -Purpose: - Detect software lockups on each CPU. - -To reduce its OS jitter, do at least one of the following: - -1. Build with CONFIG_LOCKUP_DETECTOR=n, which will prevent these - kthreads from being created in the first place. -2. Boot with "nosoftlockup=0", which will also prevent these kthreads - from being created. Other related watchdog and softlockup boot - parameters may be found in Documentation/admin-guide/kernel-parameters.rst - and Documentation/watchdog/watchdog-parameters.rst. -3. Echo a zero to /proc/sys/kernel/watchdog to disable the - watchdog timer. -4. Echo a large number of /proc/sys/kernel/watchdog_thresh in - order to reduce the frequency of OS jitter due to the watchdog - timer down to a level that is acceptable for your workload. diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 91fd6846ce17..6721a80a2d4f 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -52,6 +52,7 @@ detailed description): - LCD Shadow (PrivacyGuard) enable and disable - Lap mode sensor - Setting keyboard language + - WWAN Antenna type A compatibility table by model and feature is maintained on the web site, http://ibm-acpi.sf.net/. I appreciate any success or failure @@ -1490,6 +1491,25 @@ fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan), nl(Dutch), nn(Norway), pl(Polish), pt(portugese), sl(Slovenian), sv(Sweden), tr(Turkey) +WWAN Antenna type +----------------- + +sysfs: wwan_antenna_type + +On some newer Thinkpads we need to set SAR value based on the antenna +type. This interface will be used by userspace to get the antenna type +and set the corresponding SAR value, as is required for FCC certification. + +The available commands are:: + + cat /sys/devices/platform/thinkpad_acpi/wwan_antenna_type + +Currently 2 antenna types are supported as mentioned below: +- type a +- type b + +The property is read-only. If the platform doesn't have support the sysfs +class is not created. Adaptive keyboard ----------------- diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst index c2f826409bf0..166697325947 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -151,7 +151,7 @@ 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/ + # tree /sys/devices/system/node/node0/memory_side_cache/ /sys/devices/system/node/node0/memory_side_cache/ |-- index1 | |-- indexing diff --git a/Documentation/admin-guide/perf/hisi-pmu.rst b/Documentation/admin-guide/perf/hisi-pmu.rst index 404a5c3d9d00..546979360513 100644 --- a/Documentation/admin-guide/perf/hisi-pmu.rst +++ b/Documentation/admin-guide/perf/hisi-pmu.rst @@ -53,6 +53,60 @@ Example usage of perf:: $# perf stat -a -e hisi_sccl3_l3c0/rd_hit_cpipe/ sleep 5 $# perf stat -a -e hisi_sccl3_l3c0/config=0x02/ sleep 5 +For HiSilicon uncore PMU v2 whose identifier is 0x30, the topology is the same +as PMU v1, but some new functions are added to the hardware. + +(a) L3C PMU supports filtering by core/thread within the cluster which can be +specified as a bitmap:: + + $# perf stat -a -e hisi_sccl3_l3c0/config=0x02,tt_core=0x3/ sleep 5 + +This will only count the operations from core/thread 0 and 1 in this cluster. + +(b) Tracetag allow the user to chose to count only read, write or atomic +operations via the tt_req parameeter in perf. The default value counts all +operations. tt_req is 3bits, 3'b100 represents read operations, 3'b101 +represents write operations, 3'b110 represents atomic store operations and +3'b111 represents atomic non-store operations, other values are reserved:: + + $# perf stat -a -e hisi_sccl3_l3c0/config=0x02,tt_req=0x4/ sleep 5 + +This will only count the read operations in this cluster. + +(c) Datasrc allows the user to check where the data comes from. It is 5 bits. +Some important codes are as follows: +5'b00001: comes from L3C in this die; +5'b01000: comes from L3C in the cross-die; +5'b01001: comes from L3C which is in another socket; +5'b01110: comes from the local DDR; +5'b01111: comes from the cross-die DDR; +5'b10000: comes from cross-socket DDR; +etc, it is mainly helpful to find that the data source is nearest from the CPU +cores. If datasrc_cfg is used in the multi-chips, the datasrc_skt shall be +configured in perf command:: + + $# perf stat -a -e hisi_sccl3_l3c0/config=0xb9,datasrc_cfg=0xE/, + hisi_sccl3_l3c0/config=0xb9,datasrc_cfg=0xF/ sleep 5 + +(d)Some HiSilicon SoCs encapsulate multiple CPU and IO dies. Each CPU die +contains several Compute Clusters (CCLs). The I/O dies are called Super I/O +clusters (SICL) containing multiple I/O clusters (ICLs). Each CCL/ICL in the +SoC has a unique ID. Each ID is 11bits, include a 6-bit SCCL-ID and 5-bit +CCL/ICL-ID. For I/O die, the ICL-ID is followed by: +5'b00000: I/O_MGMT_ICL; +5'b00001: Network_ICL; +5'b00011: HAC_ICL; +5'b10000: PCIe_ICL; + +Users could configure IDs to count data come from specific CCL/ICL, by setting +srcid_cmd & srcid_msk, and data desitined for specific CCL/ICL by setting +tgtid_cmd & tgtid_msk. A set bit in srcid_msk/tgtid_msk means the PMU will not +check the bit when matching against the srcid_cmd/tgtid_cmd. + +If all of these options are disabled, it can works by the default value that +doesn't distinguish the filter condition and ID information and will return +the total counter values in the PMU counters. + The current driver does not support sampling. So "perf record" is unsupported. Also attach to a task is unsupported as the events are all uncore. diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst index b0a1ae7df13b..8f107d8c9261 100644 --- a/Documentation/admin-guide/ramoops.rst +++ b/Documentation/admin-guide/ramoops.rst @@ -3,7 +3,7 @@ Ramoops oops/panic logger Sergiu Iordache <sergiu@chromium.org> -Updated: 17 November 2011 +Updated: 10 Feb 2021 Introduction ------------ @@ -30,6 +30,8 @@ mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use depends on atomic operations. At least on ARM, pgprot_noncached causes the memory to be mapped strongly ordered, and atomic operations on strongly ordered memory are implementation defined, and won't work on many ARMs such as omaps. +Setting ``mem_type=2`` attempts to treat the memory region as normal memory, +which enables full cache on it. This can improve the performance. The memory area is divided into ``record_size`` chunks (also rounded down to power of two) and each kmesg dump writes a ``record_size`` chunk of diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst deleted file mode 100644 index 409fa91d7495..000000000000 --- a/Documentation/admin-guide/reporting-bugs.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. _reportingbugs: - -.. note:: - - This document is obsolete, and will be replaced by - 'Documentation/admin-guide/reporting-issues.rst' in the near future. - -Reporting bugs -++++++++++++++ - -Background -========== - -The upstream Linux kernel maintainers only fix bugs for specific kernel -versions. Those versions include the current "release candidate" (or -rc) -kernel, any "stable" kernel versions, and any "long term" kernels. - -Please see https://www.kernel.org/ for a list of supported kernels. Any -kernel marked with [EOL] is "end of life" and will not have any fixes -backported to it. - -If you've found a bug on a kernel version that isn't listed on kernel.org, -contact your Linux distribution or embedded vendor for support. -Alternatively, you can attempt to run one of the supported stable or -rc -kernels, and see if you can reproduce the bug on that. It's preferable -to reproduce the bug on the latest -rc kernel. - - -How to report Linux kernel bugs -=============================== - - -Identify the problematic subsystem ----------------------------------- - -Identifying which part of the Linux kernel might be causing your issue -increases your chances of getting your bug fixed. Simply posting to the -generic linux-kernel mailing list (LKML) may cause your bug report to be -lost in the noise of a mailing list that gets 1000+ emails a day. - -Instead, try to figure out which kernel subsystem is causing the issue, -and email that subsystem's maintainer and mailing list. If the subsystem -maintainer doesn't answer, then expand your scope to mailing lists like -LKML. - - -Identify who to notify ----------------------- - -Once you know the subsystem that is causing the issue, you should send a -bug report. Some maintainers prefer bugs to be reported via bugzilla -(https://bugzilla.kernel.org), while others prefer that bugs be reported -via the subsystem mailing list. - -To find out where to send an emailed bug report, find your subsystem or -device driver in the MAINTAINERS file. Search in the file for relevant -entries, and send your bug report to the person(s) listed in the "M:" -lines, making sure to Cc the mailing list(s) in the "L:" lines. When the -maintainer replies to you, make sure to 'Reply-all' in order to keep the -public mailing list(s) in the email thread. - -If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script:: - - perl scripts/get_maintainer.pl -f <filename> - -If it is a security bug, please copy the Security Contact listed in the -MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more information. - -If you can't figure out which subsystem caused the issue, you should file -a bug in kernel.org bugzilla and send email to -linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more -information on the linux-kernel mailing list see -http://vger.kernel.org/lkml/). - - -Tips for reporting bugs ------------------------ - -If you haven't reported a bug before, please read: - - https://www.chiark.greenend.org.uk/~sgtatham/bugs.html - - http://www.catb.org/esr/faqs/smart-questions.html - -It's REALLY important to report bugs that seem unrelated as separate email -threads or separate bugzilla entries. If you report several unrelated -bugs at once, it's difficult for maintainers to tease apart the relevant -data. - - -Gather information ------------------- - -The most important information in a bug report is how to reproduce the -bug. This includes system information, and (most importantly) -step-by-step instructions for how a user can trigger the bug. - -If the failure includes an "OOPS:", take a picture of the screen, capture -a netconsole trace, or type the message from your screen into the bug -report. Please read "Documentation/admin-guide/bug-hunting.rst" before posting your -bug report. This explains what you should do with the "Oops" information -to make it useful to the recipient. - -This is a suggested format for a bug report sent via email or bugzilla. -Having a standardized bug report form makes it easier for you not to -overlook things, and easier for the developers to find the pieces of -information they're really interested in. If some information is not -relevant to your bug, feel free to exclude it. - -First run the ver_linux script included as scripts/ver_linux, which -reports the version of some important subsystems. Run this script with -the command ``awk -f scripts/ver_linux``. - -Use that information to fill in all fields of the bug report form, and -post it to the mailing list with a subject of "PROBLEM: <one line -summary from [1.]>" for easy identification by the developers:: - - [1.] One line summary of the problem: - [2.] Full description of the problem/report: - [3.] Keywords (i.e., modules, networking, kernel): - [4.] Kernel information - [4.1.] Kernel version (from /proc/version): - [4.2.] Kernel .config file: - [5.] Most recent kernel version which did not have the bug: - [6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/admin-guide/bug-hunting.rst) - [7.] A small shell script or example program which triggers the - problem (if possible) - [8.] Environment - [8.1.] Software (add the output of the ver_linux script here) - [8.2.] Processor information (from /proc/cpuinfo): - [8.3.] Module information (from /proc/modules): - [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) - [8.5.] PCI information ('lspci -vvv' as root) - [8.6.] SCSI information (from /proc/scsi/scsi) - [8.7.] Other information that might be relevant to the problem - (please look in /proc and include all information that you - think to be relevant): - [X.] Other notes, patches, fixes, workarounds: - - -Follow up -========= - -Expectations for bug reporters ------------------------------- - -Linux kernel maintainers expect bug reporters to be able to follow up on -bug reports. That may include running new tests, applying patches, -recompiling your kernel, and/or re-triggering your bug. The most -frustrating thing for maintainers is for someone to report a bug, and then -never follow up on a request to try out a fix. - -That said, it's still useful for a kernel maintainer to know a bug exists -on a supported kernel, even if you can't follow up with retests. Follow -up reports, such as replying to the email thread with "I tried the latest -kernel and I can't reproduce my bug anymore" are also helpful, because -maintainers have to assume silence means things are still broken. - -Expectations for kernel maintainers ------------------------------------ - -Linux kernel maintainers are busy, overworked human beings. Some times -they may not be able to address your bug in a day, a week, or two weeks. -If they don't answer your email, they may be on vacation, or at a Linux -conference. Check the conference schedule at https://LWN.net for more info: - - https://lwn.net/Calendar/ - -In general, kernel maintainers take 1 to 5 business days to respond to -bugs. The majority of kernel maintainers are employed to work on the -kernel, and they may not work on the weekends. Maintainers are scattered -around the world, and they may not work in your time zone. Unless you -have a high priority bug, please wait at least a week after the first bug -report before sending the maintainer a reminder email. - -The exceptions to this rule are regressions, kernel crashes, security holes, -or userspace breakage caused by new kernel behavior. Those bugs should be -addressed by the maintainers ASAP. If you suspect a maintainer is not -responding to these types of bugs in a timely manner (especially during a -merge window), escalate the bug to LKML and Linus Torvalds. - -Thank you! - -[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ] diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index 07879d01fe68..48b4d0ef2b09 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -9,25 +9,6 @@ (for example by the kernel's build system) might contain content taken from files which use a more restrictive license. -.. important:: - - This document is being prepared to replace - 'Documentation/admin-guide/reporting-bugs.rst'. The main work is done and - you are already free to follow its instructions when reporting issues to the - Linux kernel developers. But keep in mind, below text still needs a few - finishing touches and review. It was merged to the Linux kernel sources at - this stage to make this process easier and increase the text's visibility. - - Any improvements for the text or other feedback is thus very much welcome. - Please send it to 'Thorsten Leemhuis <linux@leemhuis.info>' and 'Jonathan - Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing list (LKML) - <linux-kernel@vger.kernel.org>' and the 'Linux Kernel Documentation List - <linux-doc@vger.kernel.org>' in CC. - - Areas in the text that still need work or discussion contain a hint like this - which point out the remaining issues; all of them start with the word "FIXME" - to make them easy to find. - Reporting issues ++++++++++++++++ @@ -36,46 +17,43 @@ Reporting issues The short guide (aka TL;DR) =========================== -If you're facing multiple issues with the Linux kernel at once, report each -separately to its developers. Try your best guess which kernel part might be -causing the issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its -developers expect to be told about issues. Note, it's rarely -`bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in almost all cases -the report needs to be sent by email! - -Check the destination thoroughly for existing reports; also search the LKML -archives and the web. Join existing discussion if you find matches. If you -don't find any, install `the latest Linux mainline kernel -<https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or using -add-on kernel modules. Also ensure the kernel is running in a healthy -environment and is not already tainted before the issue occurs. - -If you can reproduce your issue with the mainline kernel, send a report to the -destination you determined earlier. Make sure it includes all relevant -information, which in case of a regression should mention the change that's -causing it which can often can be found with a bisection. Also ensure the -report reaches all people that need to know about it, for example the security -team, the stable maintainers or the developers of the patch that causes a -regression. Once the report is out, answer any questions that might be raised -and help where you can. That includes keeping the ball rolling: every time a -new rc1 mainline kernel is released, check if the issue is still happening -there and attach a status update to your initial report. - -If you can not reproduce the issue with the mainline kernel, consider sticking -with it; if you'd like to use an older version line and want to see it fixed -there, first make sure it's still supported. Install its latest release as -vanilla kernel. If you cannot reproduce the issue there, try to find the commit -that fixed it in mainline or any discussion preceding it: those will often -mention if backporting is planed or considered too complex. If backporting was -not discussed, ask if it's in the cards. In case you don't find any commits or -a preceding discussion, see the Linux-stable mailing list archives for existing -reports, as it might be a regression specific to the version line. If it is, -report it like you would report a problem in mainline (including the -bisection). - -If you reached this point without a solution, ask for advice one the -subsystem's mailing list. - +Are you facing a regression with vanilla kernels from the same stable or +longterm series? One still supported? Then search the `LKML +<https://lore.kernel.org/lkml/>`_ and the `Linux stable mailing list +<https://lore.kernel.org/stable/>`_ archives for matching reports to join. If +you don't find any, install `the latest release from that series +<https://kernel.org/>`_. If it still shows the issue, report it to the stable +mailing list (stable@vger.kernel.org) and CC the regressions list +(regressions@lists.linux.dev). + +In all other cases try your best guess which kernel part might be causing the +issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its developers +expect to be told about problems, which most of the time will be by email with a +mailing list in CC. Check the destination's archives for matching reports; +search the `LKML <https://lore.kernel.org/lkml/>`_ and the web, too. If you +don't find any to join, install `the latest mainline kernel +<https://kernel.org/>`_. If the issue is present there, send a report. + +The issue was fixed there, but you would like to see it resolved in a still +supported stable or longterm series as well? Then install its latest release. +If it shows the problem, search for the change that fixed it in mainline and +check if backporting is in the works or was discarded; if it's neither, ask +those who handled the change for it. + +**General remarks**: When installing and testing a kernel as outlined above, +ensure it's vanilla (IOW: not patched and not using add-on modules). Also make +sure it's built and running in a healthy environment and not already tainted +before the issue occurs. + +If you are facing multiple issues with the Linux kernel at once, report each +separately. While writing your report, include all information relevant to the +issue, like the kernel and the distro used. In case of a regression, CC the +regressions mailing list (regressions@lists.linux.dev) to your report; also try +to include the commit-id of the change causing it, which a bisection can find. + +Once the report is out, answer any questions that come up and help where you +can. That includes keeping the ball rolling by occasionally retesting with newer +releases and sending a status update afterwards. Step-by-step guide how to report issues to the kernel maintainers ================================================================= @@ -94,28 +72,23 @@ early if an issue that looks like a Linux kernel problem is actually caused by something else. These steps thus help to ensure the time you invest in this process won't feel wasted in the end: - * Stop reading this document and report the problem to your vendor instead, - unless you are running the latest mainline kernel already or are willing to - install it. This kernel must not be modified or enhanced in any way, and - thus be considered 'vanilla'. + * Are you facing an issue with a Linux kernel a hardware or software vendor + provided? Then in almost all cases you are better off to stop reading this + document and reporting the issue to your vendor instead, unless you are + willing to install the latest Linux version yourself. Be aware the latter + will often be needed anyway to hunt down and fix issues. + + * Perform a rough search for existing reports with your favorite internet + search engine; additionally, check the archives of the `Linux Kernel Mailing + List (LKML) <https://lore.kernel.org/lkml/>`_. If you find matching reports, + join the discussion instead of sending a new one. * See if the issue you are dealing with qualifies as regression, security issue, or a really severe problem: those are 'issues of high priority' that need special handling in some steps that are about to follow. - * Check if your kernel was 'tainted' when the issue occurred, as the event - that made the kernel set this flag might be causing the issue you face. - - * Locate the driver or kernel subsystem that seems to be causing the issue. - Find out how and where its developers expect reports. Note: most of the - time this won't be bugzilla.kernel.org, as issues typically need to be sent - by mail to a maintainer and a public mailing list. - - * Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. Also check if you find - something with your favorite internet search engine or in the Linux Kernel - Mailing List (LKML) archives. If you find anything, join the discussion - instead of sending a new report. + * Make sure it's not the kernel's surroundings that are causing the issue + you face. * Create a fresh backup and put system repair and restore tools at hand. @@ -123,8 +96,8 @@ process won't feel wasted in the end: kernel modules on-the-fly, which solutions like DKMS might be doing locally without your knowledge. - * Make sure it's not the kernel's surroundings that are causing the issue - you face. + * Check if your kernel was 'tainted' when the issue occurred, as the event + that made the kernel set this flag might be causing the issue you face. * Write down coarsely how to reproduce the issue. If you deal with multiple issues at once, create separate notes for each of them and make sure they @@ -132,20 +105,35 @@ process won't feel wasted in the end: needs to get reported to the kernel developers separately, unless they are strongly entangled. + * If you are facing a regression within a stable or longterm version line + (say something broke when updating from 5.10.4 to 5.10.5), scroll down to + 'Dealing with regressions within a stable and longterm kernel line'. + + * Locate the driver or kernel subsystem that seems to be causing the issue. + Find out how and where its developers expect reports. Note: most of the + time this won't be bugzilla.kernel.org, as issues typically need to be sent + by mail to a maintainer and a public mailing list. + + * Search the archives of the bug tracker or mailing list in question + thoroughly for reports that might match your issue. If you find anything, + join the discussion instead of sending a new report. + After these preparations you'll now enter the main part: - * Install the latest Linux mainline kernel: that's where all issues get - fixed first, because it's the version line the kernel developers mainly - care about. Testing and reporting with the latest Linux stable kernel can - be an acceptable alternative in some situations, for example during the - merge window; but during that period you might want to suspend your efforts - till its end anyway. + * Unless you are already running the latest 'mainline' Linux kernel, better + go and install it for the reporting process. Testing and reporting with + the latest 'stable' Linux can be an acceptable alternative in some + situations; during the merge window that actually might be even the best + approach, but in that development phase it can be an even better idea to + suspend your efforts for a few days anyway. Whatever version you choose, + ideally use a 'vanilla' build. Ignoring these advices will dramatically + increase the risk your report will be rejected or ignored. * Ensure the kernel you just installed does not 'taint' itself when running. * Reproduce the issue with the kernel you just installed. If it doesn't show - up there, head over to the instructions for issues only happening with + up there, scroll down to the instructions for issues only happening with stable and longterm kernels. * Optimize your notes: try to find and write the most straightforward way to @@ -154,8 +142,8 @@ After these preparations you'll now enter the main part: that hear about it for the first time. And if you learned something in this process, consider searching again for existing reports about the issue. - * If the failure includes a stack dump, like an Oops does, consider decoding - it to find the offending line of code. + * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider + decoding the kernel log to find the line of code that triggered the error. * If your problem is a regression, try to narrow down when the issue was introduced as much as possible. @@ -184,28 +172,54 @@ After these preparations you'll now enter the main part: help yourself, if you don't get any help or if it's unsatisfying. +Reporting regressions within a stable and longterm kernel line +-------------------------------------------------------------- + +This subsection is for you, if you followed above process and got sent here at +the point about regression within a stable or longterm kernel version line. You +face one of those if something breaks when updating from 5.10.4 to 5.10.5 (a +switch from 5.9.15 to 5.10.5 does not qualify). The developers want to fix such +regressions as quickly as possible, hence there is a streamlined process to +report them: + + * Check if the kernel developers still maintain the Linux kernel version + line you care about: go to the `front page of kernel.org + <https://kernel.org/>`_ and make sure it mentions + the latest release of the particular version line without an '[EOL]' tag. + + * Check the archives of the `Linux stable mailing list + <https://lore.kernel.org/stable/>`_ for existing reports. + + * Install the latest release from the particular version line as a vanilla + kernel. Ensure this kernel is not tainted and still shows the problem, as + the issue might have already been fixed there. If you first noticed the + problem with a vendor kernel, check a vanilla build of the last version + known to work performs fine as well. + + * Send a short problem report to the Linux stable mailing list + (stable@vger.kernel.org) and CC the Linux regressions mailing list + (regressions@lists.linux.dev). Roughly describe the issue and ideally + explain how to reproduce it. Mention the first version that shows the + problem and the last version that's working fine. Then wait for further + instructions. + +The reference section below explains each of these steps in more detail. + + Reporting issues only occurring in older kernel version lines ------------------------------------------------------------- -This section is for you, if you tried the latest mainline kernel as outlined +This subsection is for you, if you tried the latest mainline kernel as outlined above, but failed to reproduce your issue there; at the same time you want to -see the issue fixed in older version lines or a vendor kernel that's regularly -rebased on new stable or longterm releases. If that case follow these steps: +see the issue fixed in a still supported stable or longterm series or vendor +kernels regularly rebased on those. If that the case, follow these steps: * Prepare yourself for the possibility that going through the next few steps might not get the issue solved in older releases: the fix might be too big or risky to get backported there. - * Check if the kernel developers still maintain the Linux kernel version - line you care about: go to the front page of kernel.org and make sure it - mentions the latest release of the particular version line without an - '[EOL]' tag. - - * Check the archives of the Linux stable mailing list for existing reports. - - * Install the latest release from the particular version line as a vanilla - kernel. Ensure this kernel is not tainted and still shows the problem, as - the issue might have already been fixed there. + * Perform the first three steps in the section "Dealing with regressions + within a stable and longterm kernel line" above. * Search the Linux kernel version control system for the change that fixed the issue in mainline, as its commit message might tell you if the fix is @@ -215,22 +229,13 @@ rebased on new stable or longterm releases. If that case follow these steps: deemed unsuitable for backporting. If backporting was not considered at all, join the newest discussion, asking if it's in the cards. - * Check if you're dealing with a regression that was never present in - mainline by installing the first release of the version line you care - about. If the issue doesn't show up with it, you basically need to report - the issue with this version like you would report a problem with mainline - (see above). This ideally includes a bisection followed by a search for - existing reports on the net; with the help of the subject and the two - relevant commit-ids. If that doesn't turn up anything, write the report; CC - or forward the report to the stable maintainers, the stable mailing list, - and those who authored the change. Include the shortened commit-id if you - found the change that causes it. - * One of the former steps should lead to a solution. If that doesn't work out, ask the maintainers for the subsystem that seems to be causing the issue for advice; CC the mailing list for the particular subsystem as well as the stable mailing list. +The reference section below explains each of these steps in more detail. + Reference section: Reporting issues to the kernel maintainers ============================================================= @@ -276,54 +281,103 @@ issues to the Linux kernel developers. Make sure you're using the upstream Linux kernel ------------------------------------------------ - *Stop reading this document and report the problem to your vendor instead, - unless you are running the latest mainline kernel already or are willing to - install it. This kernel must not be modified or enhanced in any way, and - thus be considered 'vanilla'.* + *Are you facing an issue with a Linux kernel a hardware or software vendor + provided? Then in almost all cases you are better off to stop reading this + document and reporting the issue to your vendor instead, unless you are + willing to install the latest Linux version yourself. Be aware the latter + will often be needed anyway to hunt down and fix issues.* Like most programmers, Linux kernel developers don't like to spend time dealing -with reports for issues that don't even happen with the source code they -maintain: it's just a waste everybody's time, yours included. That's why you -later will have to test your issue with the latest 'vanilla' kernel: a kernel -that was build using the Linux sources taken straight from `kernel.org -<https://kernel.org/>`_ and not modified or enhanced in any way. - -Almost all kernels used in devices (Computers, Laptops, Smartphones, Routers, -…) and most kernels shipped by Linux distributors are ancient from the point of -kernel development and heavily modified. They thus do not qualify for reporting -an issue to the Linux kernel developers: the issue you face with such a kernel -might be fixed already or caused by the changes or additions, even if they look -small or totally unrelated. That's why issues with such kernels need to be -reported to the vendor that distributed it. Its developers should look into the +with reports for issues that don't even happen with their current code. It's +just a waste everybody's time, especially yours. Unfortunately such situations +easily happen when it comes to the kernel and often leads to frustration on both +sides. That's because almost all Linux-based kernels pre-installed on devices +(Computers, Laptops, Smartphones, Routers, …) and most shipped by Linux +distributors are quite distant from the official Linux kernel as distributed by +kernel.org: these kernels from these vendors are often ancient from the point of +Linux development or heavily modified, often both. + +Most of these vendor kernels are quite unsuitable for reporting issues to the +Linux kernel developers: an issue you face with one of them might have been +fixed by the Linux kernel developers months or years ago already; additionally, +the modifications and enhancements by the vendor might be causing the issue you +face, even if they look small or totally unrelated. That's why you should report +issues with these kernels to the vendor. Its developers should look into the report and, in case it turns out to be an upstream issue, fix it directly -upstream or report it there. In practice that sometimes does not work out. If -that the case, you might want to circumvent the vendor by installing the latest -mainline kernel yourself and reporting the issue as outlined in this document; -just make sure to use really fresh kernel (see below). - - -.. note:: - - FIXME: Should we accept reports for issues with kernel images that are pretty - close to vanilla? But when are they close enough and how to put that line in - words? Maybe something like this? +upstream or forward the report there. In practice that often does not work out +or might not what you want. You thus might want to consider circumventing the +vendor by installing the very latest Linux kernel core yourself. If that's an +option for you move ahead in this process, as a later step in this guide will +explain how to do that once it rules out other potential causes for your issue. + +Note, the previous paragraph is starting with the word 'most', as sometimes +developers in fact are willing to handle reports about issues occurring with +vendor kernels. If they do in the end highly depends on the developers and the +issue in question. Your chances are quite good if the distributor applied only +small modifications to a kernel based on a recent Linux version; that for +example often holds true for the mainline kernels shipped by Debian GNU/Linux +Sid or Fedora Rawhide. Some developers will also accept reports about issues +with kernels from distributions shipping the latest stable kernel, as long as +its only slightly modified; that for example is often the case for Arch Linux, +regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you better +want to use a mainline Linux and avoid using a stable kernel for this +process, as outlined in the section 'Install a fresh kernel for testing' in more +detail. + +Obviously you are free to ignore all this advice and report problems with an old +or heavily modified vendor kernel to the upstream Linux developers. But note, +those often get rejected or ignored, so consider yourself warned. But it's still +better than not reporting the issue at all: sometimes such reports directly or +indirectly will help to get the issue fixed over time. + + +Search for existing reports, first run +-------------------------------------- + + *Perform a rough search for existing reports with your favorite internet + search engine; additionally, check the archives of the Linux Kernel Mailing + List (LKML). If you find matching reports, join the discussion instead of + sending a new one.* + +Reporting an issue that someone else already brought forward is often a waste of +time for everyone involved, especially you as the reporter. So it's in your own +interest to thoroughly check if somebody reported the issue already. At this +step of the process it's okay to just perform a rough search: a later step will +tell you to perform a more detailed search once you know where your issue needs +to be reported to. Nevertheless, do not hurry with this step of the reporting +process, it can save you time and trouble. + +Simply search the internet with your favorite search engine first. Afterwards, +search the `Linux Kernel Mailing List (LKML) archives +<https://lore.kernel.org/lkml/>`_. - *Note: Some Linux kernel developers accept reports from vendor kernels that - are known to be close to upstream. That for example is often the case for - the kernels that Debian GNU/Linux Sid or Fedora Rawhide ship, which are - normally following mainline closely and carry only a few patches. So a - report with one of these might be accepted by the developers that need to - handle it. But if they do, depends heavily on the individual developers and - the issue at hand. That's why installing a mainline vanilla kernel is the - safe bet.* +If you get flooded with results consider telling your search engine to limit +search timeframe to the past month or year. And wherever you search, make sure +to use good search terms; vary them a few times, too. While doing so try to +look at the issue from the perspective of someone else: that will help you to +come up with other words to use as search terms. Also make sure not to use too +many search terms at once. Remember to search with and without information like +the name of the kernel driver or the name of the affected hardware component. +But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') +often is not much helpful, as it is too specific. Instead try search terms like +the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip +('Navi' or 'Navi10') with and without its manufacturer ('AMD'). - *Arch Linux, other Fedora releases, and openSUSE Tumbleweed often use quite - recent stable kernels that are pretty close to upstream, too. Some - developers accept bugs from them as well. But note that you normally should - avoid stable kernels for reporting issues and use a mainline kernel instead - (see below).* +In case you find an existing report about your issue, join the discussion, as +you might be able to provide valuable additional information. That can be +important even when a fix is prepared or in its final stages already, as +developers might look for people that can provide additional information or +test a proposed fix. Jump to the section 'Duties after the report went out' for +details on how to get properly involved. - Are there any other major Linux distributions that should be mentioned here? +Note, searching `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ might also +be a good idea, as that might provide valuable insights or turn up matching +reports. If you find the latter, just keep in mind: most subsystems expect +reports in different places, as described below in the section "Check where you +need to report your issue". The developers that should take care of the issue +thus might not even be aware of the bugzilla ticket. Hence, check the ticket if +the issue already got reported as outlined in this document and if not consider +doing so. Issue of high priority? @@ -365,6 +419,75 @@ fatal error where the kernel stop itself) with a 'Oops' (a recoverable error), as the kernel remains running after the latter. +Ensure a healthy environment +---------------------------- + + *Make sure it's not the kernel's surroundings that are causing the issue + you face.* + +Problems that look a lot like a kernel issue are sometimes caused by build or +runtime environment. It's hard to rule out that problem completely, but you +should minimize it: + + * Use proven tools when building your kernel, as bugs in the compiler or the + binutils can cause the resulting kernel to misbehave. + + * Ensure your computer components run within their design specifications; + that's especially important for the main processor, the main memory, and the + motherboard. Therefore, stop undervolting or overclocking when facing a + potential kernel issue. + + * Try to make sure it's not faulty hardware that is causing your issue. Bad + main memory for example can result in a multitude of issues that will + manifest itself in problems looking like kernel issues. + + * If you're dealing with a filesystem issue, you might want to check the file + system in question with ``fsck``, as it might be damaged in a way that leads + to unexpected kernel behavior. + + * When dealing with a regression, make sure it's not something else that + changed in parallel to updating the kernel. The problem for example might be + caused by other software that was updated at the same time. It can also + happen that a hardware component coincidentally just broke when you rebooted + into a new kernel for the first time. Updating the systems BIOS or changing + something in the BIOS Setup can also lead to problems that on look a lot + like a kernel regression. + + +Prepare for emergencies +----------------------- + + *Create a fresh backup and put system repair and restore tools at hand.* + +Reminder, you are dealing with computers, which sometimes do unexpected things, +especially if you fiddle with crucial parts like the kernel of its operating +system. That's what you are about to do in this process. Thus, make sure to +create a fresh backup; also ensure you have all tools at hand to repair or +reinstall the operating system as well as everything you need to restore the +backup. + + +Make sure your kernel doesn't get enhanced +------------------------------------------ + + *Ensure your system does not enhance its kernels by building additional + kernel modules on-the-fly, which solutions like DKMS might be doing locally + without your knowledge.* + +The risk your issue report gets ignored or rejected dramatically increases if +your kernel gets enhanced in any way. That's why you should remove or disable +mechanisms like akmods and DKMS: those build add-on kernel modules +automatically, for example when you install a new Linux kernel or boot it for +the first time. Also remove any modules they might have installed. Then reboot +before proceeding. + +Note, you might not be aware that your system is using one of these solutions: +they often get set up silently when you install Nvidia's proprietary graphics +driver, VirtualBox, or other software that requires a some support from a +module not part of the Linux kernel. That why your might need to uninstall the +packages with such software to get rid of any 3rd party kernel module. + + Check 'taint' flag ------------------ @@ -433,9 +556,52 @@ three things: the name of the module in question). -Locate kernel area that causes the issue +Document how to reproduce issue +------------------------------- + + *Write down coarsely how to reproduce the issue. If you deal with multiple + issues at once, create separate notes for each of them and make sure they + work independently on a freshly booted system. That's needed, as each issue + needs to get reported to the kernel developers separately, unless they are + strongly entangled.* + +If you deal with multiple issues at once, you'll have to report each of them +separately, as they might be handled by different developers. Describing +various issues in one report also makes it quite difficult for others to tear +it apart. Hence, only combine issues in one report if they are very strongly +entangled. + +Additionally, during the reporting process you will have to test if the issue +happens with other kernel versions. Therefore, it will make your work easier if +you know exactly how to reproduce an issue quickly on a freshly booted system. + +Note: it's often fruitless to report issues that only happened once, as they +might be caused by a bit flip due to cosmic radiation. That's why you should +try to rule that out by reproducing the issue before going further. Feel free +to ignore this advice if you are experienced enough to tell a one-time error +due to faulty hardware apart from a kernel issue that rarely happens and thus +is hard to reproduce. + + +Regression in stable or longterm kernel? ---------------------------------------- + *If you are facing a regression within a stable or longterm version line + (say something broke when updating from 5.10.4 to 5.10.5), scroll down to + 'Dealing with regressions within a stable and longterm kernel line'.* + +Regression within a stable and longterm kernel version line are something the +Linux developers want to fix badly, as such issues are even more unwanted than +regression in the main development branch, as they can quickly affect a lot of +people. The developers thus want to learn about such issues as quickly as +possible, hence there is a streamlined process to report them. Note, +regressions with newer kernel version line (say something broke when switching +from 5.9.15 to 5.10.5) do not qualify. + + +Check where you need to report your issue +----------------------------------------- + *Locate the driver or kernel subsystem that seems to be causing the issue. Find out how and where its developers expect reports. Note: most of the time this won't be bugzilla.kernel.org, as issues typically need to be sent @@ -526,26 +692,6 @@ example above does not have such a line. That is the case for most sections, as Linux kernel development is completely driven by mail. Very few subsystems use a bug tracker, and only some of those rely on bugzilla.kernel.org. - -.. note:: - - FIXME: The old text took a totally different approach to bugzilla.kernel.org, - as it mentions it as the place to file issue for people that don't known how - to contact the appropriate people. The new one mentions it rarely; and when - it does like here, it warns users that it's often the wrong place to go. - - This approach was chosen as the main author of this document noticed quite a - few users (or even a lot?) get no reply to the bugs they file in bugzilla. - That's kind of expected, as quite a few (many? most?) of the maintainers - don't even get notified when reports for their subsystem get filed there. And - not getting a single reply to report is something that is just annoying for - users and might make them angry. Improving bugzilla.k.o would be an option, - but on the kernel and maintainers summit 2017 it was agreed on to first go - this route (sorry it took so long): it's easier to achieve and less - controversial, as putting additional burden on already overworked maintainers - is unlikely to get well received. - - In this and many other cases you thus have to look for lines starting with 'Mail:' instead. Those mention the name and the email addresses for the maintainers of the particular code. Also look for a line starting with 'Mailing @@ -558,21 +704,6 @@ and might leave some work for other developers on the subsystem specific list; and LKML is important to have one place where all issue reports can be found. -.. note:: - - FIXME: Above section tells users to always CC LKML. These days it's a kind of - "catch-all" list anyway, which nearly nobody seems to follow closely. So it - seems appropriate to go "all in" and make people send their reports here, - too, as everything (reports, fixes, ...) then can be found in one place (at - least for all reports sent by mail and all subsystems that CC LKML). - - Related: Should we create mailing list like 'linux-issues@vger.kernel.org' - and tell users above to always CC it when reporting issues? Then there would - be one central place reporters could search for existing reports (at least - for issues reported by mail) without getting regular LKML traffic mixed into - the results. - - Finding the maintainers with the help of a script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -611,205 +742,87 @@ modified during tree-wide cleanups by developers that do not care about the particular driver at all. -Search for existing reports ---------------------------- +Search for existing reports, second run +--------------------------------------- *Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. Also check if you find - something with your favorite internet search engine or in the Linux Kernel - Mailing List (LKML) archives. If you find anything, join the discussion - instead of sending a new report.* - -Reporting an issue that someone else already brought forward is often a waste -of time for everyone involved, especially you as the reporter. So it's in your -own interest to thoroughly check if somebody reported the issue already. Thus -do not hurry with this step of the reporting process. Spending 30 to 60 minutes -or even more time can save you and others quite a lot of time and trouble. - -The best place to search is the bug tracker or the mailing list where your -report needs to be filed. You'll find quite a few of those lists on -`lore.kernel.org <https://lore.kernel.org/>`_, but some are hosted in -different places. That for example is the case for the ath10k WiFi driver used -as example in the previous step. But you'll often find the archives for these -lists easily on the net. Searching for 'archive ath10k@lists.infradead.org' for -example will quickly lead you to the `Info page for the ath10k mailing list -<https://lists.infradead.org/mailman/listinfo/ath10k>`_, which at the top links -to its `list archives <https://lists.infradead.org/pipermail/ath10k/>`_. - -Sadly this and quite a few other lists miss a way to search the archives. In -those cases use a regular internet search engine and add something like + thoroughly for reports that might match your issue. If you find anything, + join the discussion instead of sending a new report.* + +As mentioned earlier already: reporting an issue that someone else already +brought forward is often a waste of time for everyone involved, especially you +as the reporter. That's why you should search for existing report again, now +that you know where they need to be reported to. If it's mailing list, you will +often find its archives on `lore.kernel.org <https://lore.kernel.org/>`_. + +But some list are hosted in different places. That for example is the case for +the ath10k WiFi driver used as example in the previous step. But you'll often +find the archives for these lists easily on the net. Searching for 'archive +ath10k@lists.infradead.org' for example will lead you to the `Info page for the +ath10k mailing list <https://lists.infradead.org/mailman/listinfo/ath10k>`_, +which at the top links to its +`list archives <https://lists.infradead.org/pipermail/ath10k/>`_. Sadly this and +quite a few other lists miss a way to search the archives. In those cases use a +regular internet search engine and add something like 'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits the results to the archives at that URL. -Additionally, search the internet and the `Linux Kernel Mailing List (LKML) -archives <https://lore.kernel.org/lkml/>`_, as maybe the real culprit might be -in some other subsystem. Searching in `bugzilla.kernel.org -<https://bugzilla.kernel.org/>`_ might also be a good idea, but if you find -anything there keep in mind: most subsystems expect reports in different -places, hence those you find there might have not even reached the people -responsible for the subsystem in question. Nevertheless, the data there might -provide valuable insights. - -If you get flooded with results consider telling your search engine to limit -search timeframe to the past month or year. And wherever you search, make sure -to use good search terms; vary them a few times, too. While doing so try to -look at the issue from the perspective of someone else: that will help you to -come up with other words to use as search terms. Also make sure not to use too -many search terms at once. Remember to search with and without information like -the name of the kernel driver or the name of the affected hardware component. -But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') -often is not much helpful, as it is too specific. Instead try search terms like -the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip -('Navi' or 'Navi10') with and without its manufacturer ('AMD'). - -In case you find an existing report about your issue, join the discussion, as -you might be able to provide valuable additional information. That can be -important even when a fix is prepared or in its final stages already, as -developers might look for people that can provide additional information or -test a proposed fix. Jump to the section 'Duties after the report went out' for -details on how to get properly involved. - - -Prepare for emergencies ------------------------ - - *Create a fresh backup and put system repair and restore tools at hand.* - -Reminder, you are dealing with computers, which sometimes do unexpected things, -especially if you fiddle with crucial parts like the kernel of its operating -system. That's what you are about to do in this process. Thus, make sure to -create a fresh backup; also ensure you have all tools at hand to repair or -reinstall the operating system as well as everything you need to restore the -backup. - - -Make sure your kernel doesn't get enhanced ------------------------------------------- - - *Ensure your system does not enhance its kernels by building additional - kernel modules on-the-fly, which solutions like DKMS might be doing locally - without your knowledge.* - -Your kernel must be 'vanilla' when reporting an issue, but stops being pure as -soon as it loads a kernel module not built from the sources used to compile the -kernel image itself. That's why you need to ensure your Linux kernel stays -vanilla by removing or disabling mechanisms like akmods and DKMS: those might -build additional kernel modules automatically, for example when your boot into -a newly installed Linux kernel the first time. Reboot after removing them and -any modules they installed. - -Note, you might not be aware that your system is using one of these solutions: -they often get set up silently when you install Nvidia's proprietary graphics -driver, VirtualBox, or other software that requires a some support from a -module not part of the Linux kernel. That why your might need to uninstall the -packages with such software to get rid of any 3rd party kernel module. - - -Ensure a healthy environment ----------------------------- - - *Make sure it's not the kernel's surroundings that are causing the issue - you face.* - -Problems that look a lot like a kernel issue are sometimes caused by build or -runtime environment. It's hard to rule out that problem completely, but you -should minimize it: - - * Use proven tools when building your kernel, as bugs in the compiler or the - binutils can cause the resulting kernel to misbehave. - - * Ensure your computer components run within their design specifications; - that's especially important for the main processor, the main memory, and the - motherboard. Therefore, stop undervolting or overclocking when facing a - potential kernel issue. - - * Try to make sure it's not faulty hardware that is causing your issue. Bad - main memory for example can result in a multitude of issues that will - manifest itself in problems looking like kernel issues. - - * If you're dealing with a filesystem issue, you might want to check the file - system in question with ``fsck``, as it might be damaged in a way that leads - to unexpected kernel behavior. - - * When dealing with a regression, make sure it's not something else that - changed in parallel to updating the kernel. The problem for example might be - caused by other software that was updated at the same time. It can also - happen that a hardware component coincidentally just broke when you rebooted - into a new kernel for the first time. Updating the systems BIOS or changing - something in the BIOS Setup can also lead to problems that on look a lot - like a kernel regression. - +It's also wise to check the internet, LKML and maybe bugzilla.kernel.org again +at this point. -Document how to reproduce issue -------------------------------- +For details how to search and what to do if you find matching reports see +"Search for existing reports, first run" above. - *Write down coarsely how to reproduce the issue. If you deal with multiple - issues at once, create separate notes for each of them and make sure they - work independently on a freshly booted system. That's needed, as each issue - needs to get reported to the kernel developers separately, unless they are - strongly entangled.* - -If you deal with multiple issues at once, you'll have to report each of them -separately, as they might be handled by different developers. Describing -various issues in one report also makes it quite difficult for others to tear -it apart. Hence, only combine issues in one report if they are very strongly -entangled. - -Additionally, during the reporting process you will have to test if the issue -happens with other kernel versions. Therefore, it will make your work easier if -you know exactly how to reproduce an issue quickly on a freshly booted system. - -Note: it's often fruitless to report issues that only happened once, as they -might be caused by a bit flip due to cosmic radiation. That's why you should -try to rule that out by reproducing the issue before going further. Feel free -to ignore this advice if you are experienced enough to tell a one-time error -due to faulty hardware apart from a kernel issue that rarely happens and thus -is hard to reproduce. +Do not hurry with this step of the reporting process: spending 30 to 60 minutes +or even more time can save you and others quite a lot of time and trouble. Install a fresh kernel for testing ---------------------------------- - *Install the latest Linux mainline kernel: that's where all issues get - fixed first, because it's the version line the kernel developers mainly - care about. Testing and reporting with the latest Linux stable kernel can - be an acceptable alternative in some situations, for example during the - merge window; but during that period you might want to suspend your efforts - till its end anyway.* - -Reporting an issue to the Linux kernel developers they fixed weeks or months -ago is annoying for them and wasting their and your time. That's why it's in -everybody's interest to check if the issue occurs with the latest codebase -before reporting it. - -In the scope of the Linux kernel the term 'latest' means: a kernel version -recently created from the main line of development, as this 'mainline' tree is -where developers first apply fixes; only after that are they are allowed to get -backported to older, still supported version lines called 'stable' and -'longterm' kernels. That's why you should check a recent mainline kernel, even -if you deal with an issue you only want to see fixed in an older version line. -Another reason: some fixes are only applied to mainline or recent version -lines, as it's too hard or risky to backport them to older versions. If that -the case, reporting the issue again is unlikely to change anything. - -Longterm kernels (sometimes called "LTS kernels") are therefore unsuitable for -testing; they simply are too distant from current development. Even the latest -Linux 'stable' kernel is a significant bit behind and thus better avoided. At -least most of the time, as sometimes a stable kernel can the best choice; but -in those situations you might want to wait a few days anyway: - -Choosing between mainline, stable and waiting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Head over to `kernel.org <https://kernel.org/>`_ to decide which version to -use. Ignore the big yellow button that says 'Latest release' and look a little -lower for a table. At its top you'll see a line starting with 'mainline', which -most of the time will point to a pre-release with a version number like -'5.8-rc2'. If that's the case, you'll want to use this mainline kernel for -testing. Do not let that 'rc' scare you, these 'development kernels' are pretty -reliable — and you made a backup, as you were instructed above, didn't you? - -In about two out of every nine to ten weeks, 'mainline' might point you to a + *Unless you are already running the latest 'mainline' Linux kernel, better + go and install it for the reporting process. Testing and reporting with + the latest 'stable' Linux can be an acceptable alternative in some + situations; during the merge window that actually might be even the best + approach, but in that development phase it can be an even better idea to + suspend your efforts for a few days anyway. Whatever version you choose, + ideally use a 'vanilla' built. Ignoring these advices will dramatically + increase the risk your report will be rejected or ignored.* + +As mentioned in the detailed explanation for the first step already: Like most +programmers, Linux kernel developers don't like to spend time dealing with +reports for issues that don't even happen with the current code. It's just a +waste everybody's time, especially yours. That's why it's in everybody's +interest that you confirm the issue still exists with the latest upstream code +before reporting it. You are free to ignore this advice, but as outlined +earlier: doing so dramatically increases the risk that your issue report might +get rejected or simply ignored. + +In the scope of the kernel "latest upstream" normally means: + + * Install a mainline kernel; the latest stable kernel can be an option, but + most of the time is better avoided. Longterm kernels (sometimes called 'LTS + kernels') are unsuitable at this point of the process. The next subsection + explains all of this in more detail. + + * The over next subsection describes way to obtain and install such a kernel. + It also outlines that using a pre-compiled kernel are fine, but better are + vanilla, which means: it was built using Linux sources taken straight `from + kernel.org <https://kernel.org/>`_ and not modified or enhanced in any way. + +Choosing the right version for testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Head over to `kernel.org <https://kernel.org/>`_ to find out which version you +want to use for testing. Ignore the big yellow button that says 'Latest release' +and look a little lower at the table. At its top you'll see a line starting with +mainline, which most of the time will point to a pre-release with a version +number like '5.8-rc2'. If that's the case, you'll want to use this mainline +kernel for testing, as that where all fixes have to be applied first. Do not let +that 'rc' scare you, these 'development kernels' are pretty reliable — and you +made a backup, as you were instructed above, didn't you? + +In about two out of every nine to ten weeks, mainline might point you to a proper release with a version number like '5.7'. If that happens, consider suspending the reporting process until the first pre-release of the next version (5.8-rc1) shows up on kernel.org. That's because the Linux development @@ -830,45 +843,79 @@ case mainline for some reason does currently not work for you. An in general: using it for reproducing the issue is also better than not reporting it issue at all. +Better avoid using the latest stable kernel outside merge windows, as all fixes +must be applied to mainline first. That's why checking the latest mainline +kernel is so important: any issue you want to see fixed in older version lines +needs to be fixed in mainline first before it can get backported, which can +take a few days or weeks. Another reason: the fix you hope for might be too +hard or risky for backporting; reporting the issue again hence is unlikely to +change anything. + +These aspects are also why longterm kernels (sometimes called "LTS kernels") +are unsuitable for this part of the reporting process: they are to distant from +the current code. Hence go and test mainline first and follow the process +further: if the issue doesn't occur with mainline it will guide you how to get +it fixed in older version lines, if that's in the cards for the fix in question. + How to obtain a fresh Linux kernel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use pre-built or self-compiled kernel for testing; if you choose the -latter approach, you can either obtain the source code using git or download it -as tar archive. - -Using a pre-compiled kernel for testing is often the quickest, easiest, and -safest way – especially is you are unfamiliar with the Linux kernel. But it -needs to be a vanilla kernel, which can be hard to come buy. You are in luck if -you are using a popular Linux distribution: for quite a few of them you'll find -repositories on the net that contain packages with the latest mainline or -stable kernels in vanilla fashion. It's totally okay to use these, just make -sure from the repository's documentation they are really vanilla. And ensure -the packages contain the latest versions as offered on kernel.org; they are -likely unsuitable if the package is older than a week, as new mainline and -stable kernels typically get released at least once a week. And be aware that -you might need to get build your own kernel later anyway when it comes to -helping test fixes, as described later in this document. - -Developers and experienced Linux users familiar with git are often best served -by obtaining the latest Linux kernel sources straight from the `official -development repository on kernel.org +**Using a pre-compiled kernel**: This is often the quickest, easiest, and safest +way for testing — especially is you are unfamiliar with the Linux kernel. The +problem: most of those shipped by distributors or add-on repositories are build +from modified Linux sources. They are thus not vanilla and therefore often +unsuitable for testing and issue reporting: the changes might cause the issue +you face or influence it somehow. + +But you are in luck if you are using a popular Linux distribution: for quite a +few of them you'll find repositories on the net that contain packages with the +latest mainline or stable Linux built as vanilla kernel. It's totally okay to +use these, just make sure from the repository's description they are vanilla or +at least close to it. Additionally ensure the packages contain the latest +versions as offered on kernel.org. The packages are likely unsuitable if they +are older than a week, as new mainline and stable kernels typically get released +at least once a week. + +Please note that you might need to build your own kernel manually later: that's +sometimes needed for debugging or testing fixes, as described later in this +document. Also be aware that pre-compiled kernels might lack debug symbols that +are needed to decode messages the kernel prints when a panic, Oops, warning, or +BUG occurs; if you plan to decode those, you might be better off compiling a +kernel yourself (see the end of this subsection and the section titled 'Decode +failure messages' for details). + +**Using git**: Developers and experienced Linux users familiar with git are +often best served by obtaining the latest Linux kernel sources straight from the +`official development repository on kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_. Those are likely a bit ahead of the latest mainline pre-release. Don't worry about it: they are as reliable as a proper pre-release, unless the kernel's development cycle is currently in the middle of a merge window. But even then they are quite reliable. -People unfamiliar with git are often best served by downloading the sources as -tarball from `kernel.org <https://kernel.org/>`_. +**Conventional**: People unfamiliar with git are often best served by +downloading the sources as tarball from `kernel.org <https://kernel.org/>`_. -How to actually build a kernel isnot described here, as many websites explain +How to actually build a kernel is not described here, as many websites explain the necessary steps already. If you are new to it, consider following one of those how-to's that suggest to use ``make localmodconfig``, as that tries to pick up the configuration of your current kernel and then tries to adjust it somewhat for your system. That does not make the resulting kernel any better, but quicker to compile. +Note: If you are dealing with a panic, Oops, warning, or BUG from the kernel, +please try to enable CONFIG_KALLSYMS when configuring your kernel. +Additionally, enable CONFIG_DEBUG_KERNEL and CONFIG_DEBUG_INFO, too; the +latter is the relevant one of those two, but can only be reached if you enable +the former. Be aware CONFIG_DEBUG_INFO increases the storage space required to +build a kernel by quite a bit. But that's worth it, as these options will allow +you later to pinpoint the exact line of code that triggers your issue. The +section 'Decode failure messages' below explains this in more detail. + +But keep in mind: Always keep a record of the issue encountered in case it is +hard to reproduce. Sending an undecoded report is better than not reporting +the issue at all. + Check 'taint' flag ------------------ @@ -888,7 +935,7 @@ Reproduce issue with the fresh kernel ------------------------------------- *Reproduce the issue with the kernel you just installed. If it doesn't show - up there, head over to the instructions for issues only happening with + up there, scroll down to the instructions for issues only happening with stable and longterm kernels.* Check if the issue occurs with the fresh Linux kernel version you just @@ -923,31 +970,55 @@ instead you can join. Decode failure messages ----------------------- -.. note:: + *If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider + decoding the kernel log to find the line of code that triggered the error.* - FIXME: The text in this section is a placeholder for now and quite similar to - the old text found in 'Documentation/admin-guide/reporting-bugs.rst' - currently. It and the document it references are known to be outdated and - thus need to be revisited. Thus consider this note a request for help: if you - are familiar with this topic, please write a few lines that would fit here. - Alternatively, simply outline the current situation roughly to the main - authors of this document (see intro), as they might be able to write - something then. +When the kernel detects an internal problem, it will log some information about +the executed code. This makes it possible to pinpoint the exact line in the +source code that triggered the issue and shows how it was called. But that only +works if you enabled CONFIG_DEBUG_INFO and CONFIG_KALLSYMS when configuring +your kernel. If you did so, consider to decode the information from the +kernel's log. That will make it a lot easier to understand what lead to the +'panic', 'Oops', 'warning', or 'BUG', which increases the chances that someone +can provide a fix. - This section in the end should answer questions like "when is this actually - needed", "what .config options to ideally set earlier to make this step easy - or unnecessary?" (likely CONFIG_UNWINDER_ORC when it's available, otherwise - CONFIG_UNWINDER_FRAME_POINTER; but is there anything else needed?). +Decoding can be done with a script you find in the Linux source tree. If you +are running a kernel you compiled yourself earlier, call it like this:: -.. + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + +If you are running a packaged vanilla kernel, you will likely have to install +the corresponding packages with debug symbols. Then call the script (which you +might need to get from the Linux sources if your distro does not package it) +like this:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +The script will work on log lines like the following, which show the address of +the code the kernel was executing when the error occurred:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +Once decoded, these lines will look like this:: - *If the failure includes a stack dump, like an Oops does, consider decoding - it to find the offending line of code.* + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module -When the kernel detects an error, it will print a stack dump that allows to -identify the exact line of code where the issue happens. But that information -sometimes needs to get decoded to be readable, which is explained in -admin-guide/bug-hunting.rst. +In this case the executed code was built from the file +'~/linux-5.10.5/test-module/test-module.c' and the error occurred by the +instructions found in line '16'. + +The script will similarly decode the addresses mentioned in the section +starting with 'Call trace', which show the path to the function where the +problem occurred. Additionally, the script will show the assembler output for +the code section the kernel was executing. + +Note, if you can't get this to work, simply skip this step and mention the +reason for it in the report. If you're lucky, it might not be needed. And if it +is, someone might help you to get things going. Also be aware this is just one +of several ways to decode kernel stack traces. Sometimes different steps will +be required to retrieve the relevant details. Don't worry about that, if that's +needed in your case, developers will tell you what to do. Special care for regressions @@ -1000,8 +1071,7 @@ In the whole process keep in mind: an issue only qualifies as regression if the older and the newer kernel got built with a similar configuration. The best way to archive this: copy the configuration file (``.config``) from the old working kernel freshly to each newer kernel version you try. Afterwards run ``make -oldnoconfig`` to adjust it for the needs of the new version without enabling -any new feature, as those are allowed to cause regressions. +olddefconfig`` to adjust it for the needs of the new version. Write and send the report @@ -1166,17 +1236,26 @@ Special handling for high priority issues Reports for high priority issues need special handling. -**Severe bugs**: make sure the subject or ticket title as well as the first +**Severe issues**: make sure the subject or ticket title as well as the first paragraph makes the severeness obvious. -**Regressions**: If the issue is a regression add [REGRESSION] to the mail's -subject or the title in the bug-tracker. If you did not perform a bisection -mention at least the latest mainline version you tested that worked fine (say -5.7) and the oldest where the issue occurs (say 5.8). If you did a successful -bisection mention the commit id and subject of the change that causes the -regression. Also make sure to add the author of that change to your report; if -you need to file your bug in a bug-tracker forward the report to him in a -private mail and mention where your filed it. +**Regressions**: make the report's subject start with '[REGRESSION]'. + +In case you performed a successful bisection, use the title of the change that +introduced the regression as the second part of your subject. Make the report +also mention the commit id of the culprit. In case of an unsuccessful bisection, +make your report mention the latest tested version that's working fine (say 5.7) +and the oldest where the issue occurs (say 5.8-rc1). + +When sending the report by mail, CC the Linux regressions mailing list +(regressions@lists.linux.dev). In case the report needs to be filed to some web +tracker, proceed to do so; once filed, forward the report by mail to the +regressions list. Make sure to inline the forwarded report, hence do not attach +it. Also add a short note at the top where you mention the URL to the ticket. + +When mailing or forwarding the report, in case of a successful bisection add the +author of the culprit to the recipients; also CC everyone in the signed-off-by +chain, which you find at the end of its commit message. **Security issues**: for these issues your will have to evaluate if a short-term risk to other users would arise if details were publicly disclosed. @@ -1255,7 +1334,7 @@ you never have heard of yet; or you might be asked to apply a patch to the Linux kernel sources to test if it helps. In some cases it will be fine sending a reply asking for instructions how to do that. But before going that route try to find the answer own your own by searching the internet; alternatively -consider asking in other places for advice. For example ask a fried or post +consider asking in other places for advice. For example ask a friend or post about it to a chatroom or forum you normally hang out. **Be patient**: If you are really lucky you might get a reply to your report @@ -1390,32 +1469,11 @@ easier. And with a bit of luck there might be someone in the team that knows a bit about programming and might be able to write a fix. -Details about reporting issues only occurring in older kernel version lines ---------------------------------------------------------------------------- +Reference for "Reporting regressions within a stable and longterm kernel line" +------------------------------------------------------------------------------ -This subsection provides details for steps you need to take if you could not -reproduce your issue with a mainline kernel, but want to see it fixed in older -version lines (aka stable and longterm kernels). - -Some fixes are too complex -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Prepare yourself for the possibility that going through the next few steps - might not get the issue solved in older releases: the fix might be too big - or risky to get backported there.* - -Even small and seemingly obvious code-changes sometimes introduce new and -totally unexpected problems. The maintainers of the stable and longterm kernels -are very aware of that and thus only apply changes to these kernels that are -within rules outlined in 'Documentation/process/stable-kernel-rules.rst'. - -Complex or risky changes for example do not qualify and thus only get applied -to mainline. Other fixes are easy to get backported to the newest stable and -longterm kernels, but too risky to integrate into older ones. So be aware the -fix you are hoping for might be one of those that won't be backported to the -version line your care about. In that case you'll have no other choice then to -live with the issue or switch to a newer Linux version, unless you want to -patch the fix into your kernels yourself. +This subsection provides details for the steps you need to perform if you face +a regression within a stable and longterm kernel line. Make sure the particular version line still gets support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1431,7 +1489,7 @@ chosen and gets supported for at least two years (often six). That's why you need to check if the kernel developers still support the version line you care for. -Note, if kernel.org lists two 'stable' version lines on the front page, you +Note, if kernel.org lists two stable version lines on the front page, you should consider switching to the newer one and forget about the older one: support for it is likely to be abandoned soon. Then it will get a "end-of-life" (EOL) stamp. Version lines that reached that point still get mentioned on the @@ -1454,12 +1512,103 @@ Reproduce issue with the newest release *Install the latest release from the particular version line as a vanilla kernel. Ensure this kernel is not tainted and still shows the problem, as - the issue might have already been fixed there.* + the issue might have already been fixed there. If you first noticed the + problem with a vendor kernel, check a vanilla build of the last version + known to work performs fine as well.* Before investing any more time in this process you want to check if the issue was already fixed in the latest release of version line you're interested in. This kernel needs to be vanilla and shouldn't be tainted before the issue -happens, as detailed outlined already above in the process of testing mainline. +happens, as detailed outlined already above in the section "Install a fresh +kernel for testing". + +Did you first notice the regression with a vendor kernel? Then changes the +vendor applied might be interfering. You need to rule that out by performing +a recheck. Say something broke when you updated from 5.10.4-vendor.42 to +5.10.5-vendor.43. Then after testing the latest 5.10 release as outlined in +the previous paragraph check if a vanilla build of Linux 5.10.4 works fine as +well. If things are broken there, the issue does not qualify as upstream +regression and you need switch back to the main step-by-step guide to report +the issue. + +Report the regression +~~~~~~~~~~~~~~~~~~~~~ + + *Send a short problem report to the Linux stable mailing list + (stable@vger.kernel.org) and CC the Linux regressions mailing list + (regressions@lists.linux.dev). Roughly describe the issue and ideally + explain how to reproduce it. Mention the first version that shows the + problem and the last version that's working fine. Then wait for further + instructions.* + +When reporting a regression that happens within a stable or longterm kernel +line (say when updating from 5.10.4 to 5.10.5) a brief report is enough for +the start to get the issue reported quickly. Hence a rough description is all +it takes. + +But note, it helps developers a great deal if you can specify the exact version +that introduced the problem. Hence if possible within a reasonable time frame, +try to find that version using vanilla kernels. Lets assume something broke when +your distributor released a update from Linux kernel 5.10.5 to 5.10.8. Then as +instructed above go and check the latest kernel from that version line, say +5.10.9. If it shows the problem, try a vanilla 5.10.5 to ensure that no patches +the distributor applied interfere. If the issue doesn't manifest itself there, +try 5.10.7 and then (depending on the outcome) 5.10.8 or 5.10.6 to find the +first version where things broke. Mention it in the report and state that 5.10.9 +is still broken. + +What the previous paragraph outlines is basically a rough manual 'bisection'. +Once your report is out your might get asked to do a proper one, as it allows to +pinpoint the exact change that causes the issue (which then can easily get +reverted to fix the issue quickly). Hence consider to do a proper bisection +right away if time permits. See the section 'Special care for regressions' and +the document 'Documentation/admin-guide/bug-bisect.rst' for details how to +perform one. + + +Reference for "Reporting issues only occurring in older kernel version lines" +----------------------------------------------------------------------------- + +This section provides details for the steps you need to take if you could not +reproduce your issue with a mainline kernel, but want to see it fixed in older +version lines (aka stable and longterm kernels). + +Some fixes are too complex +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *Prepare yourself for the possibility that going through the next few steps + might not get the issue solved in older releases: the fix might be too big + or risky to get backported there.* + +Even small and seemingly obvious code-changes sometimes introduce new and +totally unexpected problems. The maintainers of the stable and longterm kernels +are very aware of that and thus only apply changes to these kernels that are +within rules outlined in 'Documentation/process/stable-kernel-rules.rst'. + +Complex or risky changes for example do not qualify and thus only get applied +to mainline. Other fixes are easy to get backported to the newest stable and +longterm kernels, but too risky to integrate into older ones. So be aware the +fix you are hoping for might be one of those that won't be backported to the +version line your care about. In that case you'll have no other choice then to +live with the issue or switch to a newer Linux version, unless you want to +patch the fix into your kernels yourself. + +Common preparations +~~~~~~~~~~~~~~~~~~~ + + *Perform the first three steps in the section "Reporting issues only + occurring in older kernel version lines" above.* + +You need to carry out a few steps already described in another section of this +guide. Those steps will let you: + + * Check if the kernel developers still maintain the Linux kernel version line + you care about. + + * Search the Linux stable mailing list for exiting reports. + + * Check with the latest release. + Check code history and search for existing discussions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1513,41 +1662,6 @@ discussions abound it. join the discussion: mention the version where you face the issue and that you would like to see it fixed, if suitable. -Check if it's a regression specific to stable or longterm kernels -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Check if you're dealing with a regression that was never present in - mainline by installing the first release of the version line you care - about. If the issue doesn't show up with it, you basically need to report - the issue with this version like you would report a problem with mainline - (see above). This ideally includes a bisection followed by a search for - existing reports on the net; with the help of the subject and the two - relevant commit-ids. If that doesn't turn up anything, write the report; CC - or forward the report to the stable maintainers, the stable mailing list, - and those who authored the change. Include the shortened commit-id if you - found the change that causes it.* - -Sometimes you won't find anything in the previous step: the issue you face -might have never occurred in mainline, as it is caused by some change that is -incomplete or not correctly applied. To check this, install the first release -from version line you care about, e.g., if you care about 5.4.x, install 5.4. - -If the issue doesn't show itself there, it's a regression specific to the -particular version line. In that case you need to report it like an issue -happening in mainline, like the last few steps in the main section in the above -outline. - -One of them suggests doing a bisection, which you are strongly advised to do in -this case. After finding the culprit, search the net for existing reports -again: not only search for the exact subject and the commit-id (proper and -shortened to twelve characters) of the change, but also for the commit-id -(proper and shortened) mentioned as 'Upstream commit' in the commit message. - -Write the report; just keep a few specialties in mind: CC or forward the report -to the stable maintainers, the stable mailing list, which the :ref:`MAINTAINERS -<maintainers>` file mentions in the section "STABLE BRANCH". If you performed a -successful bisection, CC the author of the change and include its subject and -the shortened commit-id. Ask for advice ~~~~~~~~~~~~~~ @@ -1560,8 +1674,7 @@ Ask for advice If the previous three steps didn't get you closer to a solution there is only one option left: ask for advice. Do that in a mail you sent to the maintainers for the subsystem where the issue seems to have its roots; CC the mailing list -for the subsystem as well as the stable mailing list the :ref:`MAINTAINERS -<maintainers>` file mention in the section "STABLE BRANCH". +for the subsystem as well as the stable mailing list (stable@vger.kernel.org). Why some issues won't get any reaction or remain unfixed after being reported @@ -1629,3 +1742,13 @@ issues to the Linux kernel developers: the length and complexity of this document and the implications between the lines illustrate that. But that's how it is for now. The main author of this text hopes documenting the state of the art will lay some groundwork to improve the situation over time. + + +.. + This text is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If you + spot a typo or small mistake, feel free to let him know directly and he'll + fix it. You are free to do the same in a mostly informal way if you want + to contribute changes to the text, but for copyright reasons please CC + linux-doc@vger.kernel.org and "sign-off" your contribution as + Documentation/process/submitting-patches.rst outlines in the section "Sign + your work - the Developer's Certificate of Origin". diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 67dfa4c29093..60ce5f5ebab6 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -90,8 +90,8 @@ Command Function ``b`` Will immediately reboot the system without syncing or unmounting your disks. -``c`` Will perform a system crash by a NULL pointer dereference. - A crashdump will be taken if configured. +``c`` Will perform a system crash and a crashdump will be taken + if configured. ``d`` Shows all locks that are held. diff --git a/Documentation/arch.rst b/Documentation/arch.rst new file mode 100644 index 000000000000..f10bd32a5972 --- /dev/null +++ b/Documentation/arch.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +CPU Architectures +================= + +These books provide programming details about architecture-specific +implementation. + +.. toctree:: + :maxdepth: 2 + + arm/index + arm64/index + ia64/index + m68k/index + mips/index + nios2/index + openrisc/index + parisc/index + powerpc/index + riscv/index + s390/index + sh/index + sparc/index + x86/index + xtensa/index diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst index b4bea32472b6..d4f34ae9e6f4 100644 --- a/Documentation/arm/index.rst +++ b/Documentation/arm/index.rst @@ -52,6 +52,7 @@ SoC-specific documents stm32/stm32f746-overview stm32/overview stm32/stm32h743-overview + stm32/stm32h750-overview stm32/stm32f769-overview stm32/stm32f429-overview stm32/stm32mp157-overview diff --git a/Documentation/arm/marvell.rst b/Documentation/arm/marvell.rst index 94cd73383594..c50be711ec72 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arm/marvell.rst @@ -18,12 +18,12 @@ Orion family - 88F5181L - 88F5182 - - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf - - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf - - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf + - Datasheet: https://web.archive.org/web/20210124231420/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-datasheet.pdf + - Programmer's User Guide: https://web.archive.org/web/20210124231536/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-opensource-manual.pdf + - User Manual: https://web.archive.org/web/20210124231631/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-usermanual.pdf - 88F5281 - - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf + - Datasheet: https://web.archive.org/web/20131028144728/http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf - 88F6183 Core: Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible @@ -38,33 +38,33 @@ Kirkwood family Flavors: - 88F6282 a.k.a Armada 300 - - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - Product Brief : https://web.archive.org/web/20111027032509/http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6283 a.k.a Armada 310 - - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - Product Brief : https://web.archive.org/web/20111027032509/http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6190 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20130730072715/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20121021182835/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6192 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20131113121446/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20121021182835/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6182 - 88F6180 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120616201621/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20130730091654/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6281 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120131133709/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20120620073511/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf Homepage: - http://www.marvell.com/embedded-processors/kirkwood/ + https://web.archive.org/web/20160513194943/http://www.marvell.com/embedded-processors/kirkwood/ Core: Feroceon 88fr131 ARMv5 compatible Linux kernel mach directory: @@ -78,14 +78,15 @@ Discovery family Flavors: - MV78100 - - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120616194711/http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20141005120451/http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20111110081125/http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf - MV78200 - - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20140801121623/http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20141005120458/http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20111110081125/http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - MV76100 Not supported by the Linux kernel. @@ -106,9 +107,9 @@ EBU Armada family - 88F6707 - 88F6W11 - - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf - - Hardware Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf + - Product Brief: https://web.archive.org/web/20121115063038/http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf + - Hardware Spec: https://web.archive.org/web/20140617183747/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf + - Functional Spec: https://web.archive.org/web/20140617183701/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf Core: Sheeva ARMv7 compatible PJ4B @@ -116,7 +117,7 @@ EBU Armada family Armada 375 Flavors: - 88F6720 - - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf + - Product Brief: https://web.archive.org/web/20131216023516/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf Core: ARM Cortex-A9 @@ -126,8 +127,8 @@ EBU Armada family - 88F6820 Armada 385 - 88F6828 Armada 388 - - Product infos: http://www.marvell.com/embedded-processors/armada-38x/ - - Functional Spec: http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-38x-functional-specifications-2015-11.pdf + - Product infos: https://web.archive.org/web/20181006144616/http://www.marvell.com/embedded-processors/armada-38x/ + - Functional Spec: https://web.archive.org/web/20200420191927/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-38x-functional-specifications-2015-11.pdf Core: ARM Cortex-A9 @@ -136,7 +137,7 @@ EBU Armada family - 88F6920 Armada 390 - 88F6928 Armada 398 - - Product infos: http://www.marvell.com/embedded-processors/armada-39x/ + - Product infos: https://web.archive.org/web/20181020222559/http://www.marvell.com/embedded-processors/armada-39x/ Core: ARM Cortex-A9 @@ -150,16 +151,16 @@ EBU Armada family not to be confused with the non-SMP 78xx0 SoCs Product Brief: - http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf + https://web.archive.org/web/20121021173528/http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf Functional Spec: - http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf + https://web.archive.org/web/20180829171131/http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf - Hardware Specs: - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF + - https://web.archive.org/web/20141127013651/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF + - https://web.archive.org/web/20141222000224/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF + - https://web.archive.org/web/20141222000230/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF Core: Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP @@ -180,13 +181,13 @@ EBU Armada family ARMv8 ARM Cortex A53 (ARMv8) Homepage: - http://www.marvell.com/embedded-processors/armada-3700/ + https://web.archive.org/web/20181103003602/http://www.marvell.com/embedded-processors/armada-3700/ Product Brief: - http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-product-brief-2016-01.pdf + https://web.archive.org/web/20210121194810/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-product-brief-2016-01.pdf Hardware Spec: - http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-hardware-specifications-2019-09.pdf + https://web.archive.org/web/20210202162011/http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-hardware-specifications-2019-09.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-37* @@ -198,11 +199,11 @@ EBU Armada family ARMv8 Core: ARM Cortex A72 Homepage: - http://www.marvell.com/embedded-processors/armada-70xx/ + https://web.archive.org/web/20181020222606/http://www.marvell.com/embedded-processors/armada-70xx/ Product Brief: - - http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf - - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf + - https://web.archive.org/web/20161010105541/http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf + - https://web.archive.org/web/20160928154533/http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-70* @@ -214,11 +215,11 @@ EBU Armada family ARMv8 ARM Cortex A72 Homepage: - http://www.marvell.com/embedded-processors/armada-80xx/ + https://web.archive.org/web/20181022004830/http://www.marvell.com/embedded-processors/armada-80xx/ Product Brief: - - http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf - - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf + - https://web.archive.org/web/20210124233728/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-8020-product-brief-2017-12.pdf + - https://web.archive.org/web/20161010105532/http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-80* @@ -233,10 +234,10 @@ Avanta family - 88F6560 Homepage: - http://www.marvell.com/broadband/ + https://web.archive.org/web/20181005145041/http://www.marvell.com/broadband/ Product Brief: - http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf + https://web.archive.org/web/20180829171057/http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf No public datasheet available. @@ -255,7 +256,7 @@ Storage family - 88RC1580 Product infos: - http://www.marvell.com/storage/armada-sp/ + https://web.archive.org/web/20191129073953/http://www.marvell.com/storage/armada-sp/ Core: Sheeva ARMv7 comatible Quad-core PJ4C @@ -269,16 +270,16 @@ Dove family (application processor) - 88AP510 a.k.a Armada 510 Product Brief: - http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf + https://web.archive.org/web/20111102020643/http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf Hardware Spec: - http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf + https://web.archive.org/web/20160428160231/http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf Functional Spec: - http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf + https://web.archive.org/web/20120130172443/http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf Homepage: - http://www.marvell.com/application-processors/armada-500/ + https://web.archive.org/web/20160822232651/http://www.marvell.com/application-processors/armada-500/ Core: ARMv7 compatible @@ -295,22 +296,22 @@ PXA 2xx/3xx/93x/95x family - Application processor only - Core: ARMv5 XScale1 core - PXA270, PXA271, PXA272 - - Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf - - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf - - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf - - Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf - - Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf + - Product Brief : https://web.archive.org/web/20150927135510/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf + - Design guide : https://web.archive.org/web/20120111181937/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf + - Developers manual : https://web.archive.org/web/20150927164805/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf + - Specification : https://web.archive.org/web/20140211221535/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf + - Specification update : https://web.archive.org/web/20120111104906/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf - Application processor only - Core: ARMv5 XScale2 core - PXA300, PXA310, PXA320 - - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf - - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf - - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf - - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf - - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip - - Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf - - Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip - - Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf + - PXA 300 Product Brief : https://web.archive.org/web/20120111121203/http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf + - PXA 310 Product Brief : https://web.archive.org/web/20120111104515/http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf + - PXA 320 Product Brief : https://web.archive.org/web/20121021182826/http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf + - Design guide : https://web.archive.org/web/20130727144625/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf + - Developers manual : https://web.archive.org/web/20130727144605/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip + - Specifications : https://web.archive.org/web/20130727144559/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf + - Specification Update : https://web.archive.org/web/20150927183411/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip + - Reference Manual : https://web.archive.org/web/20120111103844/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf - Application processor only - Core: ARMv5 XScale3 core - PXA930, PXA935 @@ -341,26 +342,26 @@ MMP/MMP2/MMP3 family (communication processor) Flavors: - PXA168, a.k.a Armada 168 - - Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp - - Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf - - Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf - - Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf - - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf - - Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf - - App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf + - Homepage : https://web.archive.org/web/20110926014256/http://www.marvell.com/application-processors/armada-100/armada-168.jsp + - Product brief : https://web.archive.org/web/20111102030100/http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf + - Hardware manual : https://web.archive.org/web/20160428165359/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf + - Software manual : https://web.archive.org/web/20160428154454/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf + - Specification update : https://web.archive.org/web/20150927160338/http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf + - Boot ROM manual : https://web.archive.org/web/20130727205559/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf + - App node package : https://web.archive.org/web/20141005090706/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf - Application processor only - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - PXA910/PXA920 - - Homepage : http://www.marvell.com/communication-processors/pxa910/ - - Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf + - Homepage : https://web.archive.org/web/20150928121236/http://www.marvell.com/communication-processors/pxa910/ + - Product Brief : https://archive.org/download/marvell-pxa910-pb/Marvell_PXA910_Platform-001_PB.pdf - Application processor with Communication processor - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - - PXA688, a.k.a. MMP2, a.k.a Armada 610 - - Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf + - PXA688, a.k.a. MMP2, a.k.a Armada 610 (OLPC XO-1.75) + - Product Brief : https://web.archive.org/web/20111102023255/http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf - Application processor only - Core: ARMv7 compatible Sheeva PJ4 88sv581x core - - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream) - - Product Brief : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf + - PXA2128, a.k.a. MMP3, a.k.a Armada 620 (OLPC XO-4) + - Product Brief : https://web.archive.org/web/20120824055155/http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf - Application processor only - Core: Dual-core ARMv7 compatible Sheeva PJ4C core - PXA960/PXA968/PXA978 (Linux support not upstream) diff --git a/Documentation/arm/stm32/stm32h750-overview.rst b/Documentation/arm/stm32/stm32h750-overview.rst new file mode 100644 index 000000000000..0e51235c9547 --- /dev/null +++ b/Documentation/arm/stm32/stm32h750-overview.rst @@ -0,0 +1,34 @@ +================== +STM32H750 Overview +================== + +Introduction +------------ + +The STM32H750 is a Cortex-M7 MCU aimed at various applications. +It features: + +- Cortex-M7 core running up to @480MHz +- 128K internal flash, 1MBytes internal RAM +- FMC controller to connect SDRAM, NOR and NAND memories +- Dual mode QSPI +- SD/MMC/SDIO support +- Ethernet controller +- USB OTFG FS & HS controllers +- I2C, SPI, CAN busses support +- Several 16 & 32 bits general purpose timers +- Serial Audio interface +- LCD controller +- HDMI-CEC +- SPDIFRX +- DFSDM + +Resources +--------- + +Datasheet and reference manual are publicly available on ST website (STM32H750_). + +.. _STM32H750: https://www.st.com/en/microcontrollers-microprocessors/stm32h750-value-line.html + +:Authors: Dillon Min <dillon.minfei@gmail.com> + diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst index f732f957421f..9b0b5e458a1e 100644 --- a/Documentation/arm/uefi.rst +++ b/Documentation/arm/uefi.rst @@ -64,4 +64,11 @@ linux,uefi-mmap-desc-size 32-bit Size in bytes of each entry in the UEFI memory map. linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format. + +linux,initrd-start 64-bit Physical start address of an initrd + +linux,initrd-end 64-bit Physical end address of an initrd + +kaslr-seed 64-bit Entropy used to randomize the kernel image + base address location. ========================== ====== =========================================== diff --git a/Documentation/arm64/acpi_object_usage.rst b/Documentation/arm64/acpi_object_usage.rst index 377e9d224db0..0609da73970b 100644 --- a/Documentation/arm64/acpi_object_usage.rst +++ b/Documentation/arm64/acpi_object_usage.rst @@ -17,12 +17,12 @@ For ACPI on arm64, tables also fall into the following categories: - Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT - - Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT, - MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO, - TCPA, TPM2, UEFI, XENV + - Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IBFT, + IORT, MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, + STAO, TCPA, TPM2, UEFI, XENV - - Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT, - MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT + - Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IVRS, LPIT, MSDM, OEMx, + PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT ====== ======================================================================== Table Usage for ARMv8 Linux diff --git a/Documentation/arm64/booting.rst b/Documentation/arm64/booting.rst index 7552dbc1cc54..4fcc00add117 100644 --- a/Documentation/arm64/booting.rst +++ b/Documentation/arm64/booting.rst @@ -202,9 +202,10 @@ Before jumping into the kernel, the following conditions must be met: - System registers - All writable architected system registers at the exception level where - the kernel image will be entered must be initialised by software at a - higher exception level to prevent execution in an UNKNOWN state. + All writable architected system registers at or below the exception + level where the kernel image will be entered must be initialised by + software at a higher exception level to prevent execution in an UNKNOWN + state. - SCR_EL3.FIQ must have the same value across all CPUs the kernel is executing on. @@ -270,6 +271,12 @@ Before jumping into the kernel, the following conditions must be met: having 0b1 set for the corresponding bit for each of the auxiliary counters present. + For CPUs with the Fine Grained Traps (FEAT_FGT) extension present: + + - If EL3 is present and the kernel is entered at EL2: + + - SCR_EL3.FGTEn (bit 27) must be initialised to 0b1. + The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must enter the kernel in the same exception level. diff --git a/Documentation/arm64/pointer-authentication.rst b/Documentation/arm64/pointer-authentication.rst index 30b2ab06526b..f127666ea3a8 100644 --- a/Documentation/arm64/pointer-authentication.rst +++ b/Documentation/arm64/pointer-authentication.rst @@ -107,3 +107,37 @@ filter out the Pointer Authentication system key registers from KVM_GET/SET_REG_* ioctls and mask those features from cpufeature ID register. Any attempt to use the Pointer Authentication instructions will result in an UNDEFINED exception being injected into the guest. + + +Enabling and disabling keys +--------------------------- + +The prctl PR_PAC_SET_ENABLED_KEYS allows the user program to control which +PAC keys are enabled in a particular task. It takes two arguments, the +first being a bitmask of PR_PAC_APIAKEY, PR_PAC_APIBKEY, PR_PAC_APDAKEY +and PR_PAC_APDBKEY specifying which keys shall be affected by this prctl, +and the second being a bitmask of the same bits specifying whether the key +should be enabled or disabled. For example:: + + prctl(PR_PAC_SET_ENABLED_KEYS, + PR_PAC_APIAKEY | PR_PAC_APIBKEY | PR_PAC_APDAKEY | PR_PAC_APDBKEY, + PR_PAC_APIBKEY, 0, 0); + +disables all keys except the IB key. + +The main reason why this is useful is to enable a userspace ABI that uses PAC +instructions to sign and authenticate function pointers and other pointers +exposed outside of the function, while still allowing binaries conforming to +the ABI to interoperate with legacy binaries that do not sign or authenticate +pointers. + +The idea is that a dynamic loader or early startup code would issue this +prctl very early after establishing that a process may load legacy binaries, +but before executing any PAC instructions. + +For compatibility with previous kernel versions, processes start up with IA, +IB, DA and DB enabled, and are reset to this state on exec(). Processes created +via fork() and clone() inherit the key enabled state from the calling process. + +It is recommended to avoid disabling the IA key, as this has higher performance +overhead than disabling any of the other keys. diff --git a/Documentation/arm64/silicon-errata.rst b/Documentation/arm64/silicon-errata.rst index 719510247292..d410a47ffa57 100644 --- a/Documentation/arm64/silicon-errata.rst +++ b/Documentation/arm64/silicon-errata.rst @@ -130,6 +130,9 @@ stable kernels. | Marvell | ARM-MMU-500 | #582743 | N/A | +----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ +| NVIDIA | Carmel Core | N/A | NVIDIA_CARMEL_CNP_ERRATUM | ++----------------+-----------------+-----------------+-----------------------------+ ++----------------+-----------------+-----------------+-----------------------------+ | Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 | +----------------+-----------------+-----------------+-----------------------------+ +----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/arm64/tagged-address-abi.rst b/Documentation/arm64/tagged-address-abi.rst index 4a9d9c794ee5..cbc4d4500241 100644 --- a/Documentation/arm64/tagged-address-abi.rst +++ b/Documentation/arm64/tagged-address-abi.rst @@ -40,7 +40,7 @@ space obtained in one of the following ways: during creation and with the same restrictions as for ``mmap()`` above (e.g. data, bss, stack). -The AArch64 Tagged Address ABI has two stages of relaxation depending +The AArch64 Tagged Address ABI has two stages of relaxation depending on how the user addresses are used by the kernel: 1. User addresses not accessed by the kernel but used for address space diff --git a/Documentation/conf.py b/Documentation/conf.py index fd65168c10f8..879e86dbea66 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -331,27 +331,34 @@ htmlhelp_basename = 'TheLinuxKerneldoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -'papersize': 'a4paper', + # The paper size ('letterpaper' or 'a4paper'). + 'papersize': 'a4paper', -# The font size ('10pt', '11pt' or '12pt'). -'pointsize': '11pt', + # The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '11pt', -# Latex figure (float) alignment -#'figure_align': 'htbp', + # Latex figure (float) alignment + #'figure_align': 'htbp', -# Don't mangle with UTF-8 chars -'inputenc': '', -'utf8extra': '', + # Don't mangle with UTF-8 chars + 'inputenc': '', + 'utf8extra': '', -# Additional stuff for the LaTeX preamble. + # Set document margins + 'sphinxsetup': ''' + hmargin=0.5in, vmargin=1in, + parsedliteralwraps=true, + verbatimhintsturnover=false, + ''', + + # Additional stuff for the LaTeX preamble. 'preamble': ''' - % Use some font with UTF-8 support with XeLaTeX + % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} \\setsansfont{DejaVu Sans} \\setromanfont{DejaVu Serif} \\setmonofont{DejaVu Sans Mono} - ''' + ''', } # At least one book (translations) may have Asian characters diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 160e710d992f..f063a384c7c8 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -79,7 +79,19 @@ Pointers printed without a specifier extension (i.e unadorned %p) are hashed to prevent leaking information about the kernel memory layout. This has the added benefit of providing a unique identifier. On 64-bit machines the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it -gathers enough entropy. If you *really* want the address see %px below. +gathers enough entropy. + +When possible, use specialised modifiers such as %pS or %pB (described below) +to avoid the need of providing an unhashed address that has to be interpreted +post-hoc. If not possible, and the aim of printing the address is to provide +more information for debugging, use %p and boot the kernel with the +``no_hash_pointers`` parameter during debugging, which will print all %p +addresses unmodified. If you *really* always want the unmodified address, see +%px below. + +If (and only if) you are printing addresses as a content of a virtual file in +e.g. procfs or sysfs (using e.g. seq_printf(), not printk()) read by a +userspace process, use the %pK modifier described below instead of %p or %px. Error Pointers -------------- @@ -139,6 +151,11 @@ For printing kernel pointers which should be hidden from unprivileged users. The behaviour of %pK depends on the kptr_restrict sysctl - see Documentation/admin-guide/sysctl/kernel.rst for more details. +This modifier is *only* intended when producing content of a file read by +userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the +section about %p above for discussion about how to manage hashing pointers +in printk(). + Unmodified Addresses -------------------- @@ -153,6 +170,13 @@ equivalent to %lx (or %lu). %px is preferred because it is more uniquely grep'able. If in the future we need to modify the way the kernel handles printing pointers we will be better equipped to find the call sites. +Before using %px, consider if using %p is sufficient together with enabling the +``no_hash_pointers`` kernel parameter during debugging sessions (see the %p +description above). One valid scenario for %px might be printing information +immediately before a panic, which prevents any sensitive information to be +exploited anyway, and with %px there would be no need to reproduce the panic +with no_hash_pointers. + Pointer Differences ------------------- @@ -540,7 +564,7 @@ Flags bitfields such as page flags, gfp_flags :: - %pGp referenced|uptodate|lru|active|private + %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff %pGg GFP_USER|GFP_DMA32|GFP_NOWARN %pGv read|exec|mayread|maywrite|mayexec|denywrite @@ -567,6 +591,24 @@ For printing netdev_features_t. Passed by reference. +V4L2 and DRM FourCC code (pixel format) +--------------------------------------- + +:: + + %p4cc + +Print a FourCC code used by V4L2 or DRM, including format endianness and +its numerical value as hexadecimal. + +Passed by reference. + +Examples:: + + %p4cc BG12 little-endian (0x32314742) + %p4cc Y10 little-endian (0x20303159) + %p4cc NV12 big-endian (0xb231564e) + Thanks ====== diff --git a/Documentation/core-api/rbtree.rst b/Documentation/core-api/rbtree.rst index 6b88837fbf82..ed1a9fbc779e 100644 --- a/Documentation/core-api/rbtree.rst +++ b/Documentation/core-api/rbtree.rst @@ -201,7 +201,7 @@ search trees, such as for traversals or users relying on a the particular order for their own logic. To this end, users can use 'struct rb_root_cached' to optimize O(logN) rb_first() calls to a simple pointer fetch avoiding potentially expensive tree iterations. This is done at negligible runtime -overhead for maintanence; albeit larger memory footprint. +overhead for maintenance; albeit larger memory footprint. Similar to the rb_root structure, cached rbtrees are initialized to be empty via:: diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst new file mode 100644 index 000000000000..51fed1bd72ec --- /dev/null +++ b/Documentation/dev-tools/checkpatch.rst @@ -0,0 +1,755 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========== +Checkpatch +========== + +Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial +style violations in patches and optionally corrects them. Checkpatch can +also be run on file contexts and without the kernel tree. + +Checkpatch is not always right. Your judgement takes precedence over checkpatch +messages. If your code looks better with the violations, then its probably +best left alone. + + +Options +======= + +This section will describe the options checkpatch can be run with. + +Usage:: + + ./scripts/checkpatch.pl [OPTION]... [FILE]... + +Available options: + + - -q, --quiet + + Enable quiet mode. + + - -v, --verbose + Enable verbose mode. Additional verbose test descriptions are output + so as to provide information on why that particular message is shown. + + - --no-tree + + Run checkpatch without the kernel tree. + + - --no-signoff + + Disable the 'Signed-off-by' line check. The sign-off is a simple line at + the end of the explanation for the patch, which certifies that you wrote it + or otherwise have the right to pass it on as an open-source patch. + + Example:: + + Signed-off-by: Random J Developer <random@developer.example.org> + + Setting this flag effectively stops a message for a missing signed-off-by + line in a patch context. + + - --patch + + Treat FILE as a patch. This is the default option and need not be + explicitly specified. + + - --emacs + + Set output to emacs compile window format. This allows emacs users to jump + from the error in the compile window directly to the offending line in the + patch. + + - --terse + + Output only one line per report. + + - --showfile + + Show the diffed file position instead of the input file position. + + - -g, --git + + Treat FILE as a single commit or a git revision range. + + Single commit with: + + - <rev> + - <rev>^ + - <rev>~n + + Multiple commits with: + + - <rev1>..<rev2> + - <rev1>...<rev2> + - <rev>-<count> + + - -f, --file + + Treat FILE as a regular source file. This option must be used when running + checkpatch on source files in the kernel. + + - --subjective, --strict + + Enable stricter tests in checkpatch. By default the tests emitted as CHECK + do not activate by default. Use this flag to activate the CHECK tests. + + - --list-types + + Every message emitted by checkpatch has an associated TYPE. Add this flag + to display all the types in checkpatch. + + Note that when this flag is active, checkpatch does not read the input FILE, + and no message is emitted. Only a list of types in checkpatch is output. + + - --types TYPE(,TYPE2...) + + Only display messages with the given types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES + + - --ignore TYPE(,TYPE2...) + + Checkpatch will not emit messages for the specified types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES + + - --show-types + + By default checkpatch doesn't display the type associated with the messages. + Set this flag to show the message type in the output. + + - --max-line-length=n + + Set the max line length (default 100). If a line exceeds the specified + length, a LONG_LINE message is emitted. + + + The message level is different for patch and file contexts. For patches, + a WARNING is emitted. While a milder CHECK is emitted for files. So for + file contexts, the --strict flag must also be enabled. + + - --min-conf-desc-length=n + + Set the Kconfig entry minimum description length, if shorter, warn. + + - --tab-size=n + + Set the number of spaces for tab (default 8). + + - --root=PATH + + PATH to the kernel tree root. + + This option must be specified when invoking checkpatch from outside + the kernel root. + + - --no-summary + + Suppress the per file summary. + + - --mailback + + Only produce a report in case of Warnings or Errors. Milder Checks are + excluded from this. + + - --summary-file + + Include the filename in summary. + + - --debug KEY=[0|1] + + Turn on/off debugging of KEY, where KEY is one of 'values', 'possible', + 'type', and 'attr' (default is all off). + + - --fix + + This is an EXPERIMENTAL feature. If correctable errors exists, a file + <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the + automatically fixable errors corrected. + + - --fix-inplace + + EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes. + + DO NOT USE this flag unless you are absolutely sure and you have a backup + in place. + + - --ignore-perl-version + + Override checking of perl version. Runtime errors maybe encountered after + enabling this flag if the perl version does not meet the minimum specified. + + - --codespell + + Use the codespell dictionary for checking spelling errors. + + - --codespellfile + + Use the specified codespell file. + Default is '/usr/share/codespell/dictionary.txt'. + + - --typedefsfile + + Read additional types from this file. + + - --color[=WHEN] + + Use colors 'always', 'never', or only when output is a terminal ('auto'). + Default is 'auto'. + + - --kconfig-prefix=WORD + + Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`). + + - -h, --help, --version + + Display the help text. + +Message Levels +============== + +Messages in checkpatch are divided into three levels. The levels of messages +in checkpatch denote the severity of the error. They are: + + - ERROR + + This is the most strict level. Messages of type ERROR must be taken + seriously as they denote things that are very likely to be wrong. + + - WARNING + + This is the next stricter level. Messages of type WARNING requires a + more careful review. But it is milder than an ERROR. + + - CHECK + + This is the mildest level. These are things which may require some thought. + +Type Descriptions +================= + +This section contains a description of all the message types in checkpatch. + +.. Types in this section are also parsed by checkpatch. +.. The types are grouped into subsections based on use. + + +Allocation style +---------------- + + **ALLOC_ARRAY_ARGS** + The first argument for kcalloc or kmalloc_array should be the + number of elements. sizeof() as the first argument is generally + wrong. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + **ALLOC_SIZEOF_STRUCT** + The allocation style is bad. In general for family of + allocation functions using sizeof() to get memory size, + constructs like:: + + p = alloc(sizeof(struct foo), ...) + + should be:: + + p = alloc(sizeof(*p), ...) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory + + **ALLOC_WITH_MULTIPLY** + Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a + sizeof multiply. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + +API usage +--------- + + **ARCH_DEFINES** + Architecture specific defines should be avoided wherever + possible. + + **ARCH_INCLUDE_LINUX** + Whenever asm/file.h is included and linux/file.h exists, a + conversion can be made when linux/file.h includes asm/file.h. + However this is not always the case (See signal.h). + This message type is emitted only for includes from arch/. + + **AVOID_BUG** + BUG() or BUG_ON() should be avoided totally. + Use WARN() and WARN_ON() instead, and handle the "impossible" + error condition as gracefully as possible. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on + + **CONSIDER_KSTRTO** + The simple_strtol(), simple_strtoll(), simple_strtoul(), and + simple_strtoull() functions explicitly ignore overflows, which + may lead to unexpected results in callers. The respective kstrtol(), + kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the + correct replacements. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull + + **LOCKDEP** + The lockdep_no_validate class was added as a temporary measure to + prevent warnings on conversion of device->sem to device->mutex. + It should not be used for any other purpose. + See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/ + + **MALFORMED_INCLUDE** + The #include statement has a malformed path. This has happened + because the author has included a double slash "//" in the pathname + accidentally. + + **USE_LOCKDEP** + lockdep_assert_held() annotations should be preferred over + assertions based on spin_is_locked() + See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations + + **UAPI_INCLUDE** + No #include statements in include/uapi should use a uapi/ path. + + +Comment style +------------- + + **BLOCK_COMMENT_STYLE** + The comment style is incorrect. The preferred style for multi- + line comments is:: + + /* + * This is the preferred style + * for multi line comments. + */ + + The networking comment style is a bit different, with the first line + not empty like the former:: + + /* This is the preferred comment style + * for files in net/ and drivers/net/ + */ + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + **C99_COMMENTS** + C99 style single line comments (//) should not be used. + Prefer the block comment style instead. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + +Commit message +-------------- + + **BAD_SIGN_OFF** + The signed-off-by line does not fall in line with the standards + specified by the community. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1 + + **BAD_STABLE_ADDRESS_STYLE** + The email format for stable is incorrect. + Some valid options for stable address are:: + + 1. stable@vger.kernel.org + 2. stable@kernel.org + + For adding version info, the following comment style should be used:: + + stable@vger.kernel.org # version info + + **COMMIT_COMMENT_SYMBOL** + Commit log lines starting with a '#' are ignored by git as + comments. To solve this problem addition of a single space + infront of the log line is enough. + + **COMMIT_MESSAGE** + The patch is missing a commit description. A brief + description of the changes made by the patch should be added. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + **MISSING_SIGN_OFF** + The patch is missing a Signed-off-by line. A signed-off-by + line should be added according to Developer's certificate of + Origin. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **NO_AUTHOR_SIGN_OFF** + The author of the patch has not signed off the patch. It is + required that a simple sign off line should be present at the + end of explanation of the patch to denote that the author has + written it or otherwise has the rights to pass it on as an open + source patch. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **DIFF_IN_COMMIT_MSG** + Avoid having diff content in commit message. + This causes problems when one tries to apply a file containing both + the changelog and the diff because patch(1) tries to apply the diff + which it found in the changelog. + See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/ + + **GERRIT_CHANGE_ID** + To be picked up by gerrit, the footer of the commit message might + have a Change-Id like:: + + Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b + Signed-off-by: A. U. Thor <author@example.com> + + The Change-Id line must be removed before submitting. + + **GIT_COMMIT_ID** + The proper way to reference a commit id is: + commit <12+ chars of sha1> ("<title line>") + + An example may be:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + +Comparison style +---------------- + + **ASSIGN_IN_IF** + Do not use assignments in if condition. + Example:: + + if ((foo = bar(...)) < BAZ) { + + should be written as:: + + foo = bar(...); + if (foo < BAZ) { + + **BOOL_COMPARISON** + Comparisons of A to true and false are better written + as A and !A. + See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/ + + **COMPARISON_TO_NULL** + Comparisons to NULL in the form (foo == NULL) or (foo != NULL) + are better written as (!foo) and (foo). + + **CONSTANT_COMPARISON** + Comparisons with a constant or upper case identifier on the left + side of the test should be avoided. + + +Macros, Attributes and Symbols +------------------------------ + + **ARRAY_SIZE** + The ARRAY_SIZE(foo) macro should be preferred over + sizeof(foo)/sizeof(foo[0]) for finding number of elements in an + array. + + The macro is defined in include/linux/kernel.h:: + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + + **AVOID_EXTERNS** + Function prototypes don't need to be declared extern in .h + files. It's assumed by the compiler and is unnecessary. + + **AVOID_L_PREFIX** + Local symbol names that are prefixed with `.L` should be avoided, + as this has special meaning for the assembler; a symbol entry will + not be emitted into the symbol table. This can prevent `objtool` + from generating correct unwind info. + + Symbols with STB_LOCAL binding may still be used, and `.L` prefixed + local symbol names are still generally usable within a function, + but `.L` prefixed local symbol names should not be used to denote + the beginning or end of code regions via + `SYM_CODE_START_LOCAL`/`SYM_CODE_END` + + **BIT_MACRO** + Defines like: 1 << <digit> could be BIT(digit). + The BIT() macro is defined in include/linux/bitops.h:: + + #define BIT(nr) (1UL << (nr)) + + **CONST_READ_MOSTLY** + When a variable is tagged with the __read_mostly annotation, it is a + signal to the compiler that accesses to the variable will be mostly + reads and rarely(but NOT never) a write. + + const __read_mostly does not make any sense as const data is already + read-only. The __read_mostly annotation thus should be removed. + + **DATE_TIME** + It is generally desirable that building the same source code with + the same set of tools is reproducible, i.e. the output is always + exactly the same. + + The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, + and enables warnings if they are used as they can lead to + non-deterministic builds. + See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps + + **DEFINE_ARCH_HAS** + The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong. + + For big conceptual features use Kconfig symbols instead. And for + smaller things where we have compatibility fallback functions but + want architectures able to override them with optimized ones, we + should either use weak functions (appropriate for some cases), or + the symbol that protects them should be the same symbol we use. + See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/ + + **INIT_ATTRIBUTE** + Const init definitions should use __initconst instead of + __initdata. + + Similarly init definitions without const require a separate + use of const. + + **INLINE_LOCATION** + The inline keyword should sit between storage class and type. + + For example, the following segment:: + + inline static int example_function(void) + { + ... + } + + should be:: + + static inline int example_function(void) + { + ... + } + + **MULTISTATEMENT_MACRO_USE_DO_WHILE** + Macros with multiple statements should be enclosed in a + do - while block. Same should also be the case for macros + starting with `if` to avoid logic defects:: + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl + + **WEAK_DECLARATION** + Using weak declarations like __attribute__((weak)) or __weak + can have unintended link defects. Avoid using them. + + +Functions and Variables +----------------------- + + **CAMELCASE** + Avoid CamelCase Identifiers. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming + + **FUNCTION_WITHOUT_ARGS** + Function declarations without arguments like:: + + int foo() + + should be:: + + int foo(void) + + **GLOBAL_INITIALISERS** + Global variables should not be initialized explicitly to + 0 (or NULL, false, etc.). Your compiler (or rather your + loader, which is responsible for zeroing out the relevant + sections) automatically does it for you. + + **INITIALISED_STATIC** + Static variables should not be initialized explicitly to zero. + Your compiler (or rather your loader) automatically does + it for you. + + **RETURN_PARENTHESES** + return is not a function and as such doesn't need parentheses:: + + return (bar); + + can simply be:: + + return bar; + + +Spacing and Brackets +-------------------- + + **ASSIGNMENT_CONTINUATIONS** + Assignment operators should not be written at the start of a + line but should follow the operand at the previous line. + + **BRACES** + The placement of braces is stylistically incorrect. + The preferred way is to put the opening brace last on the line, + and put the closing brace first:: + + if (x is true) { + we do y + } + + This applies for all non-functional blocks. + However, there is one special case, namely functions: they have the + opening brace at the beginning of the next line, thus:: + + int function(int x) + { + body of function + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **BRACKET_SPACE** + Whitespace before opening bracket '[' is prohibited. + There are some exceptions: + + 1. With a type on the left:: + + ;int [] a; + + 2. At the beginning of a line for slice initialisers:: + + [0...10] = 5, + + 3. Inside a curly brace:: + + = { [0...10] = 5 } + + **CODE_INDENT** + Code indent should use tabs instead of spaces. + Outside of comments, documentation and Kconfig, + spaces are never used for indentation. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **CONCATENATED_STRING** + Concatenated elements should have a space in between. + Example:: + + printk(KERN_INFO"bar"); + + should be:: + + printk(KERN_INFO "bar"); + + **ELSE_AFTER_BRACE** + `else {` should follow the closing block `}` on the same line. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **LINE_SPACING** + Vertical space is wasted given the limited number of lines an + editor window can display when multiple blank lines are used. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **OPEN_BRACE** + The opening brace should be following the function definitions on the + next line. For any non-functional block it should be on the same line + as the last construct. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **POINTER_LOCATION** + When using pointer data or a function that returns a pointer type, + the preferred use of * is adjacent to the data name or function name + and not adjacent to the type name. + Examples:: + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SPACING** + Whitespace style used in the kernel sources is described in kernel docs. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SWITCH_CASE_INDENT_LEVEL** + switch should be at the same indent as case. + Example:: + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **TRAILING_WHITESPACE** + Trailing whitespace should always be removed. + Some editors highlight the trailing whitespace and cause visual + distractions when editing files. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **WHILE_AFTER_BRACE** + while should follow the closing bracket on the same line:: + + do { + ... + } while(something); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + +Others +------ + + **CONFIG_DESCRIPTION** + Kconfig symbols should have a help text which fully describes + it. + + **CORRUPTED_PATCH** + The patch seems to be corrupted or lines are wrapped. + Please regenerate the patch file before sending it to the maintainer. + + **DOS_LINE_ENDINGS** + For DOS-formatted patches, there are extra ^M symbols at the end of + the line. These should be removed. + + **EXECUTE_PERMISSIONS** + There is no reason for source files to be executable. The executable + bit can be removed safely. + + **NON_OCTAL_PERMISSIONS** + Permission bits should use 4 digit octal permissions (like 0700 or 0444). + Avoid using any other base like decimal. + + **NOT_UNIFIED_DIFF** + The patch file does not appear to be in unified-diff format. Please + regenerate the patch file before sending it to the maintainer. + + **PRINTF_0XDECIMAL** + Prefixing 0x with decimal output is defective and should be corrected. + + **TRAILING_STATEMENTS** + Trailing statements (for example after any conditional) should be + on the next line. + Like:: + + if (x == y) break; + + should be:: + + if (x == y) + break; diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst index 9e989baae154..5fce2b06f229 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -124,6 +124,8 @@ box for setups where kernels are built and run on the same machine. In cases where the kernel runs on a separate machine, special preparations must be made, depending on where the gcov tool is used: +.. _gcov-test: + a) gcov is run on the TEST machine The gcov tool version on the test machine must be compatible with the @@ -143,6 +145,8 @@ a) gcov is run on the TEST machine machine. If any of the path components is symbolic link, the actual directory needs to be used instead (due to make's CURDIR handling). +.. _gcov-build: + b) gcov is run on the BUILD machine The following files need to be copied after each test case from test @@ -211,7 +215,7 @@ Appendix A: gather_on_build.sh ------------------------------ Sample script to gather coverage meta files on the build machine -(see 6a): +(see :ref:`Separated build and test machines a. <gcov-test>`): .. code-block:: sh @@ -244,7 +248,7 @@ Appendix B: gather_on_test.sh ----------------------------- Sample script to gather coverage data files on the test machine -(see 6b): +(see :ref:`Separated build and test machines b. <gcov-build>`): .. code-block:: sh diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 1b1cf4f5c9d9..010a2af1e7d9 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -7,6 +7,9 @@ be used to work on the kernel. For now, the documents have been pulled together without any significant effort to integrate them into a coherent whole; patches welcome! +A brief overview of testing-specific tools can be found in +Documentation/dev-tools/testing-overview.rst + .. class:: toc-title Table of contents @@ -14,6 +17,8 @@ whole; patches welcome! .. toctree:: :maxdepth: 2 + testing-overview + checkpatch coccinelle sparse kcov diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index ddf4239a5890..6f6ab3ed7b79 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -161,6 +161,15 @@ particular KASAN features. - ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``). +- ``kasan.mode=sync`` or ``=async`` controls whether KASAN is configured in + synchronous or asynchronous mode of execution (default: ``sync``). + Synchronous mode: a bad access is detected immediately when a tag + check fault occurs. + Asynchronous mode: a bad access detection is delayed. When a tag check + fault occurs, the information is stored in hardware (in the TFSR_EL1 + register for arm64). The kernel periodically checks the hardware and + only reports tag faults during these checks. + - ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack traces collection (default: ``on``). diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index be7a0b0e1f28..d85ce238ace7 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2019, Google LLC. + The Kernel Concurrency Sanitizer (KCSAN) ======================================== diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index a901def730d9..dcefee707ccd 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -239,8 +239,8 @@ 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`` +- ``tools/testing/selftests/kselftest_module.h`` +- ``tools/testing/selftests/kselftest/module.sh`` How to use ---------- diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst index a6ca0af14098..8d8c238f7f79 100644 --- a/Documentation/dev-tools/kunit/tips.rst +++ b/Documentation/dev-tools/kunit/tips.rst @@ -78,8 +78,82 @@ Similarly to the above, it can be useful to add test-specific logic. void test_only_hook(void) { } #endif -TODO(dlatypov@google.com): add an example of using ``current->kunit_test`` in -such a hook when it's not only updated for ``CONFIG_KASAN=y``. +This test-only code can be made more useful by accessing the current kunit +test, see below. + +Accessing the current test +-------------------------- + +In some cases, you need to call test-only code from outside the test file, e.g. +like in the example above or if you're providing a fake implementation of an +ops struct. +There is a ``kunit_test`` field in ``task_struct``, so you can access it via +``current->kunit_test``. + +Here's a slightly in-depth example of how one could implement "mocking": + +.. code-block:: c + + #include <linux/sched.h> /* for current */ + + struct test_data { + int foo_result; + int want_foo_called_with; + }; + + static int fake_foo(int arg) + { + struct kunit *test = current->kunit_test; + struct test_data *test_data = test->priv; + + KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); + return test_data->foo_result; + } + + static void example_simple_test(struct kunit *test) + { + /* Assume priv is allocated in the suite's .init */ + struct test_data *test_data = test->priv; + + test_data->foo_result = 42; + test_data->want_foo_called_with = 1; + + /* In a real test, we'd probably pass a pointer to fake_foo somewhere + * like an ops struct, etc. instead of calling it directly. */ + KUNIT_EXPECT_EQ(test, fake_foo(1), 42); + } + + +Note: here we're able to get away with using ``test->priv``, but if you wanted +something more flexible you could use a named ``kunit_resource``, see :doc:`api/test`. + +Failing the current test +------------------------ + +But sometimes, you might just want to fail the current test. In that case, we +have ``kunit_fail_current_test(fmt, args...)`` which is defined in ``<kunit/test-bug.h>`` and +doesn't require pulling in ``<kunit/test.h>``. + +E.g. say we had an option to enable some extra debug checks on some data structure: + +.. code-block:: c + + #include <kunit/test-bug.h> + + #ifdef CONFIG_EXTRA_DEBUG_CHECKS + static void validate_my_data(struct data *data) + { + if (is_valid(data)) + return; + + kunit_fail_current_test("data %p is invalid", data); + + /* Normal, non-KUnit, error reporting code here. */ + } + #else + static void my_debug_function(void) { } + #endif + Customizing error messages -------------------------- diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst new file mode 100644 index 000000000000..b5b46709969c --- /dev/null +++ b/Documentation/dev-tools/testing-overview.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Kernel Testing Guide +==================== + + +There are a number of different tools for testing the Linux kernel, so knowing +when to use each of them can be a challenge. This document provides a rough +overview of their differences, and how they fit together. + + +Writing and Running Tests +========================= + +The bulk of kernel tests are written using either the kselftest or KUnit +frameworks. These both provide infrastructure to help make running tests and +groups of tests easier, as well as providing helpers to aid in writing new +tests. + +If you're looking to verify the behaviour of the Kernel — particularly specific +parts of the kernel — then you'll want to use KUnit or kselftest. + + +The Difference Between KUnit and kselftest +------------------------------------------ + +KUnit (Documentation/dev-tools/kunit/index.rst) is an entirely in-kernel system +for "white box" testing: because test code is part of the kernel, it can access +internal structures and functions which aren't exposed to userspace. + +KUnit tests therefore are best written against small, self-contained parts +of the kernel, which can be tested in isolation. This aligns well with the +concept of 'unit' testing. + +For example, a KUnit test might test an individual kernel function (or even a +single codepath through a function, such as an error handling case), rather +than a feature as a whole. + +This also makes KUnit tests very fast to build and run, allowing them to be +run frequently as part of the development process. + +There is a KUnit test style guide which may give further pointers in +Documentation/dev-tools/kunit/style.rst + + +kselftest (Documentation/dev-tools/kselftest.rst), on the other hand, is +largely implemented in userspace, and tests are normal userspace scripts or +programs. + +This makes it easier to write more complicated tests, or tests which need to +manipulate the overall system state more (e.g., spawning processes, etc.). +However, it's not possible to call kernel functions directly from kselftest. +This means that only kernel functionality which is exposed to userspace somehow +(e.g. by a syscall, device, filesystem, etc.) can be tested with kselftest. To +work around this, some tests include a companion kernel module which exposes +more information or functionality. If a test runs mostly or entirely within the +kernel, however, KUnit may be the more appropriate tool. + +kselftest is therefore suited well to tests of whole features, as these will +expose an interface to userspace, which can be tested, but not implementation +details. This aligns well with 'system' or 'end-to-end' testing. + +For example, all new system calls should be accompanied by kselftest tests. + +Code Coverage Tools +=================== + +The Linux Kernel supports two different code coverage measurement tools. These +can be used to verify that a test is executing particular functions or lines +of code. This is useful for determining how much of the kernel is being tested, +and for finding corner-cases which are not covered by the appropriate test. + +:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel +to get global or per-module coverage. Unlike KCOV, it does not record per-task +coverage. Coverage data can be read from debugfs, and interpreted using the +usual gcov tooling. + +:doc:`kcov` is a feature which can be built in to the kernel to allow +capturing coverage on a per-task level. It's therefore useful for fuzzing and +other situations where information about code executed during, for example, a +single syscall is useful. + + +Dynamic Analysis Tools +====================== + +The kernel also supports a number of dynamic analysis tools, which attempt to +detect classes of issues when they occur in a running kernel. These typically +each look for a different class of bugs, such as invalid memory accesses, +concurrency issues such as data races, or other undefined behaviour like +integer overflows. + +Some of these tools are listed below: + +* kmemleak detects possible memory leaks. See + Documentation/dev-tools/kmemleak.rst +* KASAN detects invalid memory accesses such as out-of-bounds and + use-after-free errors. See Documentation/dev-tools/kasan.rst +* UBSAN detects behaviour that is undefined by the C standard, like integer + overflows. See Documentation/dev-tools/ubsan.rst +* KCSAN detects data races. See Documentation/dev-tools/kcsan.rst +* KFENCE is a low-overhead detector of memory issues, which is much faster than + KASAN and can be used in production. See Documentation/dev-tools/kfence.rst +* lockdep is a locking correctness validator. See + Documentation/locking/lockdep-design.rst +* There are several other pieces of debug instrumentation in the kernel, many + of which can be found in lib/Kconfig.debug + +These tools tend to test the kernel as a whole, and do not "pass" like +kselftest or KUnit tests. They can be combined with KUnit or kselftest by +running tests on a kernel with these tools enabled: you can then be sure +that none of these errors are occurring during the test. + +Some of these tools integrate with KUnit or kselftest and will +automatically fail tests if an issue is detected. + diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 5f6769bf45bd..97fb96266344 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -109,6 +109,7 @@ properties: - libretech,aml-s905d-pc - phicomm,n1 - smartlabs,sml5442tw + - videostrong,gxl-kii-pro - const: amlogic,s905d - const: amlogic,meson-gxl @@ -120,8 +121,10 @@ properties: - khadas,vim2 - kingnovel,r-box-pro - libretech,aml-s912-pc + - minix,neo-u9h - nexbox,a1 - tronsmart,vega-s96 + - videostrong,gxm-kiii-pro - wetek,core2 - const: amlogic,s912 - const: amlogic,meson-gxm diff --git a/Documentation/devicetree/bindings/arm/apple.yaml b/Documentation/devicetree/bindings/arm/apple.yaml new file mode 100644 index 000000000000..1e772c85206c --- /dev/null +++ b/Documentation/devicetree/bindings/arm/apple.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/apple.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple ARM Machine Device Tree Bindings + +maintainers: + - Hector Martin <marcan@marcan.st> + +description: | + ARM platforms using SoCs designed by Apple Inc., branded "Apple Silicon". + + This currently includes devices based on the "M1" SoC, starting with the + three Mac models released in late 2020: + + - Mac mini (M1, 2020) + - MacBook Pro (13-inch, M1, 2020) + - MacBook Air (M1, 2020) + + The compatible property should follow this format: + + compatible = "apple,<targettype>", "apple,<socid>", "apple,arm-platform"; + + <targettype> represents the board/device and comes from the `target-type` + property of the root node of the Apple Device Tree, lowercased. It can be + queried on macOS using the following command: + + $ ioreg -d2 -l | grep target-type + + <socid> is the lowercased SoC ID. Apple uses at least *five* different + names for their SoCs: + + - Marketing name ("M1") + - Internal name ("H13G") + - Codename ("Tonga") + - SoC ID ("T8103") + - Package/IC part number ("APL1102") + + Devicetrees should use the lowercased SoC ID, to avoid confusion if + multiple SoCs share the same marketing name. This can be obtained from + the `compatible` property of the arm-io node of the Apple Device Tree, + which can be queried as follows on macOS: + + $ ioreg -n arm-io | grep compatible + +properties: + $nodename: + const: "/" + compatible: + oneOf: + - description: Apple M1 SoC based platforms + items: + - enum: + - apple,j274 # Mac mini (M1, 2020) + - apple,j293 # MacBook Pro (13-inch, M1, 2020) + - apple,j313 # MacBook Air (M1, 2020) + - const: apple,t8103 + - const: apple,arm-platform + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml index e55731f43c84..2cd4e4a32278 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4908.yaml @@ -21,6 +21,7 @@ properties: items: - enum: - netgear,r8000p + - tplink,archer-c2300-v1 - const: brcm,bcm4906 - const: brcm,bcm4908 diff --git a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml index a2c63c8b1d10..e3664eab0f6a 100644 --- a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml @@ -64,6 +64,21 @@ properties: - compatible - "#reset-cells" + pwm: + type: object + + properties: + compatible: + const: raspberrypi,firmware-poe-pwm + + "#pwm-cells": + # See pwm.yaml in this directory for a description of the cells format. + const: 2 + + required: + - compatible + - "#pwm-cells" + additionalProperties: false required: @@ -87,5 +102,10 @@ examples: compatible = "raspberrypi,firmware-reset"; #reset-cells = <1>; }; + + pwm: pwm { + compatible = "raspberrypi,firmware-poe-pwm"; + #pwm-cells = <2>; + }; }; ... diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 26b886b20b27..c299423dc7cb 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -85,6 +85,8 @@ properties: compatible: enum: + - apple,icestorm + - apple,firestorm - arm,arm710t - arm,arm720t - arm,arm740t diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 297c87f45db8..e3c50f231d71 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -617,6 +617,7 @@ properties: - kam,imx7d-flex-concentrator # Kamstrup OMNIA Flex Concentrator - kam,imx7d-flex-concentrator-mfg # Kamstrup OMNIA Flex Concentrator in manufacturing mode - novtech,imx7d-meerkat96 # i.MX7 Meerkat96 Board + - remarkable,imx7d-remarkable2 # i.MX7D ReMarkable 2 E-Ink Tablet - technexion,imx7d-pico-dwarf # TechNexion i.MX7D Pico-Dwarf - technexion,imx7d-pico-hobbit # TechNexion i.MX7D Pico-Hobbit - technexion,imx7d-pico-nymph # TechNexion i.MX7D Pico-Nymph @@ -688,6 +689,14 @@ properties: - variscite,var-som-mx8mm # i.MX8MM Variscite VAR-SOM-MX8MM module - const: fsl,imx8mm + - description: Engicam i.Core MX8M Mini SoM based boards + items: + - enum: + - engicam,icore-mx8mm-ctouch2 # i.MX8MM Engicam i.Core MX8M Mini C.TOUCH 2.0 + - engicam,icore-mx8mm-edimm2.2 # i.MX8MM Engicam i.Core MX8M Mini EDIMM2.2 Starter Kit + - const: engicam,icore-mx8mm # i.MX8MM Engicam i.Core MX8M Mini SoM + - const: fsl,imx8mm + - description: Kontron BL i.MX8MM (N801X S) Board items: - const: kontron,imx8mm-n801x-s @@ -733,6 +742,7 @@ properties: - einfochips,imx8mq-thor96 # i.MX8MQ Thor96 Board - fsl,imx8mq-evk # i.MX8MQ EVK Board - google,imx8mq-phanbell # Google Coral Edge TPU + - kontron,pitx-imx8m # Kontron pITX-imx8m Board - purism,librem5-devkit # Purism Librem5 devkit - solidrun,hummingboard-pulse # SolidRun Hummingboard Pulse - technexion,pico-pi-imx8m # TechNexion PICO-PI-8M evk @@ -755,6 +765,12 @@ properties: - const: zii,imx8mq-ultra - const: fsl,imx8mq + - description: i.MX8QM based Boards + items: + - enum: + - fsl,imx8qm-mek # i.MX8QM MEK Board + - const: fsl,imx8qm + - description: i.MX8QXP based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 93b3bdf6eaeb..aff57a8c8c30 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -118,6 +118,10 @@ properties: - enum: - mediatek,mt8183-evb - const: mediatek,mt8183 + - items: + - enum: + - mediatek,mt8195-evb + - const: mediatek,mt8195 - description: Google Krane (Lenovo IdeaPad Duet, 10e,...) items: - enum: @@ -125,6 +129,38 @@ properties: - google,krane-sku176 - const: google,krane - const: mediatek,mt8183 + - description: Google Damu (ASUS Chromebook Flip CM3) + items: + - const: google,damu + - const: mediatek,mt8183 + - description: Google Juniper (Acer Chromebook Spin 311) + items: + - const: google,juniper-sku16 + - const: google,juniper + - const: mediatek,mt8183 + - description: Google Kakadu (ASUS Chromebook Detachable CM3) + items: + - const: google,kakadu-rev3 + - const: google,kakadu-rev2 + - const: google,kakadu + - const: mediatek,mt8183 + - description: Google Kodama (Lenovo 10e Chromebook Tablet) + items: + - enum: + - google,kodama-sku16 + - google,kodama-sku272 + - google,kodama-sku288 + - google,kodama-sku32 + - const: google,kodama + - const: mediatek,mt8183 + - items: + - enum: + - mediatek,mt8183-pumpkin + - const: mediatek,mt8183 + - items: + - enum: + - mediatek,mt8516-pumpkin + - const: mediatek,mt8516 additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt index d8c9108c3b4a..78c50733985c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt @@ -13,6 +13,7 @@ Required Properties: - "mediatek,mt6779-mmsys", "syscon" - "mediatek,mt6797-mmsys", "syscon" - "mediatek,mt7623-mmsys", "mediatek,mt2701-mmsys", "syscon" + - "mediatek,mt8167-mmsys", "syscon" - "mediatek,mt8173-mmsys", "syscon" - "mediatek,mt8183-mmsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml index c299dc907f6c..62fcbd883392 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.yaml @@ -22,6 +22,7 @@ properties: compatible: enum: - qcom,sc7180-llcc + - qcom,sc7280-llcc - qcom,sdm845-llcc - qcom,sm8150-llcc - qcom,sm8250-llcc diff --git a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml index 61d08c473eb8..a316eef1b728 100644 --- a/Documentation/devicetree/bindings/arm/mstar/mstar.yaml +++ b/Documentation/devicetree/bindings/arm/mstar/mstar.yaml @@ -24,6 +24,7 @@ properties: items: - enum: - honestar,ssd201htv2 # Honestar SSD201_HT_V2 devkit + - m5stack,unitv2 # M5Stack UnitV2 - const: mstar,infinity2m - description: infinity3 boards diff --git a/Documentation/devicetree/bindings/arm/npcm/npcm.txt b/Documentation/devicetree/bindings/arm/npcm/npcm.txt deleted file mode 100644 index 2d87d9ecea85..000000000000 --- a/Documentation/devicetree/bindings/arm/npcm/npcm.txt +++ /dev/null @@ -1,6 +0,0 @@ -NPCM Platforms Device Tree Bindings ------------------------------------ -NPCM750 SoC -Required root node properties: - - compatible = "nuvoton,npcm750"; - diff --git a/Documentation/devicetree/bindings/arm/npcm/npcm.yaml b/Documentation/devicetree/bindings/arm/npcm/npcm.yaml new file mode 100644 index 000000000000..95e51378089c --- /dev/null +++ b/Documentation/devicetree/bindings/arm/npcm/npcm.yaml @@ -0,0 +1,29 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/npcm/npcm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NPCM Platforms Device Tree Bindings + +maintainers: + - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: WPCM450 based boards + items: + - enum: + - supermicro,x9sci-ln4f-bmc # Supermicro X9SCI-LN4F server's BMC + - const: nuvoton,wpcm450 + + - description: NPCM750 based boards + items: + - enum: + - nuvoton,npcm750-evb # NPCM750 evaluation board + - const: nuvoton,npcm750 + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 174134f920e1..9b27e991bddc 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -37,6 +37,7 @@ description: | msm8994 msm8996 sc7180 + sc7280 sdm630 sdm660 sdm845 @@ -137,6 +138,16 @@ properties: - const: qcom,msm8916 - items: + - enum: + - sony,karin_windy + - sony,karin-row + - sony,satsuki-row + - sony,sumire-row + - sony,suzuran-row + - qcom,msm8994 + - const: qcom,apq8094 + + - items: - const: qcom,msm8996-mtp - items: @@ -166,16 +177,24 @@ properties: - items: - enum: + - qcom,sc7280-idp + - const: qcom,sc7280 + + - items: + - enum: - xiaomi,lavender - const: qcom,sdm660 - items: - enum: - qcom,sdx55-mtp + - qcom,sdx55-telit-fn980-tlb + - qcom,sdx55-t55 - const: qcom,sdx55 - items: - enum: + - qcom,ipq6018-cp01 - qcom,ipq6018-cp01-c1 - const: qcom,ipq6018 @@ -187,6 +206,7 @@ properties: - items: - enum: + - qcom,sm8350-hdk - qcom,sm8350-mtp - const: qcom,sm8350 diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index c3036f95c7bc..4a6f772c1043 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -134,6 +134,7 @@ properties: - friendlyarm,nanopi-m4 - friendlyarm,nanopi-m4b - friendlyarm,nanopi-neo4 + - friendlyarm,nanopi-r4s - const: rockchip,rk3399 - description: GeekBuying GeekBox diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index e7525a3395e5..9a77ab74be99 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -53,6 +53,10 @@ properties: - const: st,stm32h743 - items: - enum: + - st,stm32h750i-art-pi + - const: st,stm32h750 + - items: + - enum: - shiratech,stm32mp157a-iot-box # IoT Box - shiratech,stm32mp157a-stinger96 # Stinger96 - st,stm32mp157c-ed1 @@ -64,6 +68,23 @@ properties: - const: st,stm32mp157c-ev1 - const: st,stm32mp157c-ed1 - const: st,stm32mp157 + + - description: Engicam i.Core STM32MP1 SoM based Boards + items: + - enum: + - engicam,icore-stm32mp1-ctouch2 # STM32MP1 Engicam i.Core STM32MP1 C.TOUCH 2.0 + - engicam,icore-stm32mp1-edimm2.2 # STM32MP1 Engicam i.Core STM32MP1 EDIMM2.2 Starter Kit + - const: engicam,icore-stm32mp1 # STM32MP1 Engicam i.Core STM32MP1 SoM + - const: st,stm32mp157 + + - description: Engicam MicroGEA STM32MP1 SoM based Boards + items: + - enum: + - engicam,microgea-stm32mp1-microdev2.0 + - engicam,microgea-stm32mp1-microdev2.0-of7 + - const: engicam,microgea-stm32mp1 + - const: st,stm32mp157 + - description: Octavo OSD32MP15x System-in-Package based boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 08607c7ec1bf..ac750025a2eb 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -802,6 +802,11 @@ properties: - const: tbs-biometrics,a711 - const: allwinner,sun8i-a83t + - description: Topwise A721 Tablet + items: + - const: topwise,a721 + - const: allwinner,sun4i-a10 + - description: Utoo P66 items: - const: utoo,p66 diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index c6e1c1e63e43..c5aa362e4026 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -23,6 +23,8 @@ properties: items: - enum: - ti,am654-evm + - siemens,iot2050-basic + - siemens,iot2050-advanced - const: ti,am654 - description: K3 J721E SoC @@ -33,6 +35,13 @@ properties: items: - const: ti,j7200 + - description: K3 AM642 SoC + items: + - enum: + - ti,am642-evm + - ti,am642-sk + - const: ti,am642 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml index 940486ef1051..0f6fe365ebf3 100644 --- a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml +++ b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.yaml @@ -107,8 +107,8 @@ examples: interrupts = <GIC_SPI 232 IRQ_TYPE_LEVEL_HIGH>; reg = <0x5b010000 0x10000>; clocks = <&sdhc0_lpcg IMX_LPCG_CLK_4>, - <&sdhc0_lpcg IMX_LPCG_CLK_0>, - <&sdhc0_lpcg IMX_LPCG_CLK_5>; - clock-names = "ipg", "per", "ahb"; + <&sdhc0_lpcg IMX_LPCG_CLK_5>, + <&sdhc0_lpcg IMX_LPCG_CLK_0>; + clock-names = "ipg", "ahb", "per"; power-domains = <&pd IMX_SC_R_SDHC_0>; }; diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml index b6daedd62516..32509b98142e 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml @@ -197,6 +197,16 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32 enum: [1, 2, 3] + slow-charger-loop: + description: Allows PMIC charger loops which are slow(i.e. cannot meet the 15ms deadline) to + still comply to pSnkStby i.e Maximum power that can be consumed by sink while in Sink Standby + state as defined in 7.4.2 Sink Electrical Parameters of USB Power Delivery Specification + Revision 3.0, Version 1.2. When the property is set, the port requests pSnkStby(2.5W - + 5V@500mA) upon entering SNK_DISCOVERY(instead of 3A or the 1.5A, Rp current advertised, during + SNK_DISCOVERY) and the actual currrent limit after reception of PS_Ready for PD link or during + SNK_READY for non-pd link. + type: boolean + required: - compatible diff --git a/Documentation/devicetree/bindings/counter/interrupt-counter.yaml b/Documentation/devicetree/bindings/counter/interrupt-counter.yaml new file mode 100644 index 000000000000..fd075d104631 --- /dev/null +++ b/Documentation/devicetree/bindings/counter/interrupt-counter.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/counter/interrupt-counter.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Interrupt counter + +maintainers: + - Oleksij Rempel <o.rempel@pengutronix.de> + +description: | + A generic interrupt counter to measure interrupt frequency. It was developed + and used for agricultural devices to measure rotation speed of wheels or + other tools. Since the direction of rotation is not important, only one + signal line is needed. + Interrupts or gpios are required. If both are defined, the interrupt will + take precedence for counting interrupts. + +properties: + compatible: + const: interrupt-counter + + interrupts: + maxItems: 1 + + gpios: + maxItems: 1 + +required: + - compatible + +anyOf: + - required: [ interrupts-extended ] + - required: [ interrupts ] + - required: [ gpios ] + +additionalProperties: false + +examples: + - | + + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/gpio/gpio.h> + + counter-0 { + compatible = "interrupt-counter"; + interrupts-extended = <&gpio 0 IRQ_TYPE_EDGE_RISING>; + }; + + counter-1 { + compatible = "interrupt-counter"; + gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + }; + + counter-2 { + compatible = "interrupt-counter"; + interrupts-extended = <&gpio 2 IRQ_TYPE_EDGE_RISING>; + gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + }; + +... diff --git a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml index 1d48ac712b23..a410d2cedde6 100644 --- a/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml +++ b/Documentation/devicetree/bindings/crypto/ti,sa2ul.yaml @@ -14,6 +14,7 @@ properties: enum: - ti,j721e-sa2ul - ti,am654-sa2ul + - ti,am64-sa2ul reg: maxItems: 1 @@ -45,6 +46,18 @@ properties: description: Address translation for the possible RNG child node for SA2UL + clocks: + items: + - description: Clock used by PKA + - description: Main Input Clock + - description: Clock used by rng + + clock-names: + items: + - const: pka_in_clk + - const: x1_clk + - const: x2_clk + patternProperties: "^rng@[a-f0-9]+$": type: object @@ -57,7 +70,16 @@ required: - power-domains - dmas - dma-names - - dma-coherent + +if: + properties: + compatible: + enum: + - ti,j721e-sa2ul + - ti,am654-sa2ul +then: + required: + - dma-coherent additionalProperties: false diff --git a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt index a10d1f6d85c6..ac189dd82b08 100644 --- a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt +++ b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt @@ -12,6 +12,8 @@ Required properties: for details. - center-supply: DMC supply node. - status: Marks the node enabled/disabled. +- rockchip,pmu: Phandle to the syscon managing the "PMU general register + files". Optional properties: - interrupts: The CPU interrupt number. The interrupt specifier @@ -77,24 +79,23 @@ Following properties relate to DDR timing: - rockchip,ddr3_drv : When the DRAM type is DDR3, this parameter defines the DRAM side driver strength in ohms. Default - value is DDR3_DS_40ohm. + value is 40. - rockchip,ddr3_odt : When the DRAM type is DDR3, this parameter defines the DRAM side ODT strength in ohms. Default value - is DDR3_ODT_120ohm. + is 120. - rockchip,phy_ddr3_ca_drv : When the DRAM type is DDR3, this parameter defines the phy side CA line (incluing command line, address line and clock line) driver strength. - Default value is PHY_DRV_ODT_40. + Default value is 40. - rockchip,phy_ddr3_dq_drv : When the DRAM type is DDR3, this parameter defines the PHY side DQ line (including DQS/DQ/DM line) - driver strength. Default value is PHY_DRV_ODT_40. + driver strength. Default value is 40. - rockchip,phy_ddr3_odt : When the DRAM type is DDR3, this parameter defines - the PHY side ODT strength. Default value is - PHY_DRV_ODT_240. + the PHY side ODT strength. Default value is 240. - rockchip,lpddr3_odt_dis_freq : When the DRAM type is LPDDR3, this parameter defines then ODT disable frequency in MHz (Mega Hz). @@ -104,25 +105,23 @@ Following properties relate to DDR timing: - rockchip,lpddr3_drv : When the DRAM type is LPDDR3, this parameter defines the DRAM side driver strength in ohms. Default - value is LP3_DS_34ohm. + value is 34. - rockchip,lpddr3_odt : When the DRAM type is LPDDR3, this parameter defines the DRAM side ODT strength in ohms. Default value - is LP3_ODT_240ohm. + is 240. - rockchip,phy_lpddr3_ca_drv : When the DRAM type is LPDDR3, this parameter defines the PHY side CA line (including command line, address line and clock line) driver strength. - Default value is PHY_DRV_ODT_40. + Default value is 40. - rockchip,phy_lpddr3_dq_drv : When the DRAM type is LPDDR3, this parameter defines the PHY side DQ line (including DQS/DQ/DM line) - driver strength. Default value is - PHY_DRV_ODT_40. + driver strength. Default value is 40. - rockchip,phy_lpddr3_odt : When dram type is LPDDR3, this parameter define - the phy side odt strength, default value is - PHY_DRV_ODT_240. + the phy side odt strength, default value is 240. - rockchip,lpddr4_odt_dis_freq : When the DRAM type is LPDDR4, this parameter defines the ODT disable frequency in @@ -132,32 +131,30 @@ Following properties relate to DDR timing: - rockchip,lpddr4_drv : When the DRAM type is LPDDR4, this parameter defines the DRAM side driver strength in ohms. Default - value is LP4_PDDS_60ohm. + value is 60. - rockchip,lpddr4_dq_odt : When the DRAM type is LPDDR4, this parameter defines the DRAM side ODT on DQS/DQ line strength in ohms. - Default value is LP4_DQ_ODT_40ohm. + Default value is 40. - rockchip,lpddr4_ca_odt : When the DRAM type is LPDDR4, this parameter defines the DRAM side ODT on CA line strength in ohms. - Default value is LP4_CA_ODT_40ohm. + Default value is 40. - rockchip,phy_lpddr4_ca_drv : When the DRAM type is LPDDR4, this parameter defines the PHY side CA line (including command address - line) driver strength. Default value is - PHY_DRV_ODT_40. + line) driver strength. Default value is 40. - rockchip,phy_lpddr4_ck_cs_drv : When the DRAM type is LPDDR4, this parameter defines the PHY side clock line and CS line driver - strength. Default value is PHY_DRV_ODT_80. + strength. Default value is 80. - rockchip,phy_lpddr4_dq_drv : When the DRAM type is LPDDR4, this parameter defines the PHY side DQ line (including DQS/DQ/DM line) - driver strength. Default value is PHY_DRV_ODT_80. + driver strength. Default value is 80. - rockchip,phy_lpddr4_odt : When the DRAM type is LPDDR4, this parameter defines - the PHY side ODT strength. Default value is - PHY_DRV_ODT_60. + the PHY side ODT strength. Default value is 60. Example: dmc_opp_table: dmc_opp_table { @@ -193,23 +190,23 @@ Example: rockchip,phy_dll_dis_freq = <125>; rockchip,auto_pd_dis_freq = <666>; rockchip,ddr3_odt_dis_freq = <333>; - rockchip,ddr3_drv = <DDR3_DS_40ohm>; - rockchip,ddr3_odt = <DDR3_ODT_120ohm>; - rockchip,phy_ddr3_ca_drv = <PHY_DRV_ODT_40>; - rockchip,phy_ddr3_dq_drv = <PHY_DRV_ODT_40>; - rockchip,phy_ddr3_odt = <PHY_DRV_ODT_240>; + rockchip,ddr3_drv = <40>; + rockchip,ddr3_odt = <120>; + rockchip,phy_ddr3_ca_drv = <40>; + rockchip,phy_ddr3_dq_drv = <40>; + rockchip,phy_ddr3_odt = <240>; rockchip,lpddr3_odt_dis_freq = <333>; - rockchip,lpddr3_drv = <LP3_DS_34ohm>; - rockchip,lpddr3_odt = <LP3_ODT_240ohm>; - rockchip,phy_lpddr3_ca_drv = <PHY_DRV_ODT_40>; - rockchip,phy_lpddr3_dq_drv = <PHY_DRV_ODT_40>; - rockchip,phy_lpddr3_odt = <PHY_DRV_ODT_240>; + rockchip,lpddr3_drv = <34>; + rockchip,lpddr3_odt = <240>; + rockchip,phy_lpddr3_ca_drv = <40>; + rockchip,phy_lpddr3_dq_drv = <40>; + rockchip,phy_lpddr3_odt = <240>; rockchip,lpddr4_odt_dis_freq = <333>; - rockchip,lpddr4_drv = <LP4_PDDS_60ohm>; - rockchip,lpddr4_dq_odt = <LP4_DQ_ODT_40ohm>; - rockchip,lpddr4_ca_odt = <LP4_CA_ODT_40ohm>; - rockchip,phy_lpddr4_ca_drv = <PHY_DRV_ODT_40>; - rockchip,phy_lpddr4_ck_cs_drv = <PHY_DRV_ODT_80>; - rockchip,phy_lpddr4_dq_drv = <PHY_DRV_ODT_80>; - rockchip,phy_lpddr4_odt = <PHY_DRV_ODT_60>; + rockchip,lpddr4_drv = <60>; + rockchip,lpddr4_dq_odt = <40>; + rockchip,lpddr4_ca_odt = <40>; + rockchip,phy_lpddr4_ca_drv = <40>; + rockchip,phy_lpddr4_ck_cs_drv = <80>; + rockchip,phy_lpddr4_dq_drv = <80>; + rockchip,phy_lpddr4_odt = <60>; }; diff --git a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml index b3e9992525c2..907fb47cc84a 100644 --- a/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/allwinner,sun8i-a83t-dw-hdmi.yaml @@ -12,8 +12,8 @@ description: | and CEC. These DT bindings follow the Synopsys DWC HDMI TX bindings defined - in Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with - the following device-specific properties. + in bridge/synopsys,dw-hdmi.yaml with the following device-specific + properties. maintainers: - Chen-Yu Tsai <wens@csie.org> diff --git a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml index a1d5a32660e0..57324a5f0271 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/brcm,bcm2711-hdmi.yaml @@ -109,7 +109,7 @@ required: - resets - ddc -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml index c789784efe30..ab48ab2f4240 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml +++ b/Documentation/devicetree/bindings/display/bridge/analogix,anx7625.yaml @@ -34,6 +34,15 @@ properties: description: used for reset chip control, RESET_N pin B7. maxItems: 1 + vdd10-supply: + description: Regulator that provides the supply 1.0V power. + + vdd18-supply: + description: Regulator that provides the supply 1.8V power. + + vdd33-supply: + description: Regulator that provides the supply 3.3V power. + ports: $ref: /schemas/graph.yaml#/properties/ports @@ -55,6 +64,9 @@ properties: required: - compatible - reg + - vdd10-supply + - vdd18-supply + - vdd33-supply - ports additionalProperties: false @@ -72,6 +84,9 @@ examples: reg = <0x58>; enable-gpios = <&pio 45 GPIO_ACTIVE_HIGH>; reset-gpios = <&pio 73 GPIO_ACTIVE_HIGH>; + vdd10-supply = <&pp1000_mipibrdg>; + vdd18-supply = <&pp1800_mipibrdg>; + vdd33-supply = <&pp3300_mipibrdg>; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml b/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml new file mode 100644 index 000000000000..62c3bd4cb28d --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/chipone,icn6211.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/chipone,icn6211.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Chipone ICN6211 MIPI-DSI to RGB Converter bridge + +maintainers: + - Jagan Teki <jagan@amarulasolutions.com> + +description: | + ICN6211 is MIPI-DSI to RGB Converter bridge from chipone. + + It has a flexible configuration of MIPI DSI signal input and + produce RGB565, RGB666, RGB888 output format. + +properties: + compatible: + enum: + - chipone,icn6211 + + reg: + maxItems: 1 + description: virtual channel number of a DSI peripheral + + enable-gpios: + description: Bridge EN pin, chip is reset when EN is low. + + vdd1-supply: + description: A 1.8V/2.5V/3.3V supply that power the MIPI RX. + + vdd2-supply: + description: A 1.8V/2.5V/3.3V supply that power the PLL. + + vdd3-supply: + description: A 1.8V/2.5V/3.3V supply that power the RGB output. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for MIPI DSI input + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: + Video port for MIPI DPI output (panel or connector). + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - enable-gpios + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + dsi { + #address-cells = <1>; + #size-cells = <0>; + + bridge@0 { + compatible = "chipone,icn6211"; + reg = <0>; + enable-gpios = <&r_pio 0 5 GPIO_ACTIVE_HIGH>; /* LCD-RST: PL5 */ + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + bridge_in_dsi: endpoint { + remote-endpoint = <&dsi_out_bridge>; + }; + }; + + port@1 { + reg = <1>; + + bridge_out_panel: endpoint { + remote-endpoint = <&panel_out_bridge>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt b/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt deleted file mode 100644 index 33bf981fbe33..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt +++ /dev/null @@ -1,33 +0,0 @@ -Synopsys DesignWare HDMI TX Encoder -=================================== - -This document defines device tree properties for the Synopsys DesignWare HDMI -TX Encoder (DWC HDMI TX). It doesn't constitue a device tree binding -specification by itself but is meant to be referenced by platform-specific -device tree bindings. - -When referenced from platform device tree bindings the properties defined in -this document are defined as follows. The platform device tree bindings are -responsible for defining whether each property is required or optional. - -- reg: Memory mapped base address and length of the DWC HDMI TX registers. - -- reg-io-width: Width of the registers specified by the reg property. The - value is expressed in bytes and must be equal to 1 or 4 if specified. The - register width defaults to 1 if the property is not present. - -- interrupts: Reference to the DWC HDMI TX interrupt. - -- clocks: References to all the clocks specified in the clock-names property - as specified in Documentation/devicetree/bindings/clock/clock-bindings.txt. - -- clock-names: The DWC HDMI TX uses the following clocks. - - - "iahb" is the bus clock for either AHB and APB (mandatory). - - "isfr" is the internal register configuration clock (mandatory). - - "cec" is the HDMI CEC controller main clock (optional). - -- ports: The connectivity of the DWC HDMI TX with the rest of the system is - expressed in using ports as specified in the device graph bindings defined - in Documentation/devicetree/bindings/graph.txt. The numbering of the ports - is platform-specific. diff --git a/Documentation/devicetree/bindings/display/bridge/lontium,lt8912b.yaml b/Documentation/devicetree/bindings/display/bridge/lontium,lt8912b.yaml new file mode 100644 index 000000000000..735d0233a7d6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/lontium,lt8912b.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/lontium,lt8912b.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Lontium LT8912B MIPI to HDMI Bridge + +maintainers: + - Adrien Grassein <adrien.grassein@gmail.com> + +description: | + The LT8912B is a bridge device which convert DSI to HDMI + +properties: + compatible: + enum: + - lontium,lt8912b + + reg: + maxItems: 1 + + reset-gpios: + maxItems: 1 + description: GPIO connected to active high RESET pin. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Primary MIPI port for MIPI input + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + data-lanes: true + + required: + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: | + HDMI port, should be connected to a node compatible with the + hdmi-connector binding. + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - reset-gpios + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + i2c4 { + #address-cells = <1>; + #size-cells = <0>; + + hdmi-bridge@48 { + compatible = "lontium,lt8912b"; + reg = <0x48>; + reset-gpios = <&max7323 0 GPIO_ACTIVE_LOW>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + hdmi_out_in: endpoint { + data-lanes = <0 1 2 3>; + remote-endpoint = <&mipi_dsi_out>; + }; + }; + + port@1 { + reg = <1>; + + endpoint { + remote-endpoint = <&hdmi_in>; + }; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt deleted file mode 100644 index 3f6072651182..000000000000 --- a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.txt +++ /dev/null @@ -1,88 +0,0 @@ -Renesas Gen3 DWC HDMI TX Encoder -================================ - -The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with a companion PHY IP. - -These DT bindings follow the Synopsys DWC HDMI TX bindings defined in -Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the -following device-specific properties. - - -Required properties: - -- compatible : Shall contain one or more of - - "renesas,r8a774a1-hdmi" for R8A774A1 (RZ/G2M) compatible HDMI TX - - "renesas,r8a774b1-hdmi" for R8A774B1 (RZ/G2N) compatible HDMI TX - - "renesas,r8a774e1-hdmi" for R8A774E1 (RZ/G2H) compatible HDMI TX - - "renesas,r8a7795-hdmi" for R8A7795 (R-Car H3) compatible HDMI TX - - "renesas,r8a7796-hdmi" for R8A7796 (R-Car M3-W) compatible HDMI TX - - "renesas,r8a77961-hdmi" for R8A77961 (R-Car M3-W+) compatible HDMI TX - - "renesas,r8a77965-hdmi" for R8A77965 (R-Car M3-N) compatible HDMI TX - - "renesas,rcar-gen3-hdmi" for the generic R-Car Gen3 and RZ/G2 compatible - HDMI TX - - When compatible with generic versions, nodes must list the SoC-specific - version corresponding to the platform first, followed by the - family-specific version. - -- reg: See dw_hdmi.txt. -- interrupts: HDMI interrupt number -- clocks: See dw_hdmi.txt. -- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. -- ports: See dw_hdmi.txt. The DWC HDMI shall have one port numbered 0 - corresponding to the video input of the controller and one port numbered 1 - corresponding to its HDMI output, and one port numbered 2 corresponding to - sound input of the controller. Each port shall have a single endpoint. - -Optional properties: - -- power-domains: Shall reference the power domain that contains the DWC HDMI, - if any. - - -Example: - - hdmi0: hdmi@fead0000 { - compatible = "renesas,r8a7795-hdmi", "renesas,rcar-gen3-hdmi"; - reg = <0 0xfead0000 0 0x10000>; - interrupts = <0 389 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_CORE R8A7795_CLK_S0D4>, <&cpg CPG_MOD 729>; - clock-names = "iahb", "isfr"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - dw_hdmi0_in: endpoint { - remote-endpoint = <&du_out_hdmi0>; - }; - }; - port@1 { - reg = <1>; - rcar_dw_hdmi0_out: endpoint { - remote-endpoint = <&hdmi0_con>; - }; - }; - port@2 { - reg = <2>; - rcar_dw_hdmi0_sound_in: endpoint { - remote-endpoint = <&hdmi_sound_out>; - }; - }; - }; - }; - - hdmi0-out { - compatible = "hdmi-connector"; - label = "HDMI0 OUT"; - type = "a"; - - port { - hdmi0_con: endpoint { - remote-endpoint = <&rcar_dw_hdmi0_out>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml new file mode 100644 index 000000000000..0c9785c8db51 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/renesas,dw-hdmi.yaml @@ -0,0 +1,125 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/renesas,dw-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car DWC HDMI TX Encoder + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP + with a companion PHY IP. + +allOf: + - $ref: synopsys,dw-hdmi.yaml# + +properties: + compatible: + items: + - enum: + - renesas,r8a774a1-hdmi # for RZ/G2M compatible HDMI TX + - renesas,r8a774b1-hdmi # for RZ/G2N compatible HDMI TX + - renesas,r8a774e1-hdmi # for RZ/G2H compatible HDMI TX + - renesas,r8a7795-hdmi # for R-Car H3 compatible HDMI TX + - renesas,r8a7796-hdmi # for R-Car M3-W compatible HDMI TX + - renesas,r8a77961-hdmi # for R-Car M3-W+ compatible HDMI TX + - renesas,r8a77965-hdmi # for R-Car M3-N compatible HDMI TX + - const: renesas,rcar-gen3-hdmi + + reg-io-width: + const: 1 + + clocks: + maxItems: 2 + + clock-names: + maxItems: 2 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Parallel RGB input port + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: HDMI output port + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: Sound input port + + required: + - port@0 + - port@1 + - port@2 + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - ports + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + hdmi@fead0000 { + compatible = "renesas,r8a7795-hdmi", "renesas,rcar-gen3-hdmi"; + reg = <0xfead0000 0x10000>; + interrupts = <0 389 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_CORE R8A7795_CLK_S0D4>, <&cpg CPG_MOD 729>; + clock-names = "iahb", "isfr"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + dw_hdmi0_in: endpoint { + remote-endpoint = <&du_out_hdmi0>; + }; + }; + port@1 { + reg = <1>; + rcar_dw_hdmi0_out: endpoint { + remote-endpoint = <&hdmi0_con>; + }; + }; + port@2 { + reg = <2>; + rcar_dw_hdmi0_sound_in: endpoint { + remote-endpoint = <&hdmi_sound_out>; + }; + }; + }; + }; + + hdmi0-out { + compatible = "hdmi-connector"; + label = "HDMI0 OUT"; + type = "a"; + + port { + hdmi0_con: endpoint { + remote-endpoint = <&rcar_dw_hdmi0_out>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml new file mode 100644 index 000000000000..9be44a682e67 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/synopsys,dw-hdmi.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/synopsys,dw-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common Properties for Synopsys DesignWare HDMI TX Controller + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + This document defines device tree properties for the Synopsys DesignWare HDMI + TX controller (DWC HDMI TX) IP core. It doesn't constitute a full device tree + binding specification by itself but is meant to be referenced by device tree + bindings for the platform-specific integrations of the DWC HDMI TX. + + When referenced from platform device tree bindings the properties defined in + this document are defined as follows. The platform device tree bindings are + responsible for defining whether each property is required or optional. + +properties: + reg: + maxItems: 1 + + reg-io-width: + description: + Width (in bytes) of the registers specified by the reg property. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - enum: [1, 4] + default: 1 + + clocks: + minItems: 2 + maxItems: 5 + items: + - description: The bus clock for either AHB and APB + - description: The internal register configuration clock + additionalItems: true + + clock-names: + minItems: 2 + maxItems: 5 + items: + - const: iahb + - const: isfr + additionalItems: true + + interrupts: + maxItems: 1 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/display/fsl,lcdif.yaml b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml new file mode 100644 index 000000000000..a4c3064c778c --- /dev/null +++ b/Documentation/devicetree/bindings/display/fsl,lcdif.yaml @@ -0,0 +1,110 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/fsl,lcdif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale/NXP i.MX LCD Interface (LCDIF) + +maintainers: + - Marek Vasut <marex@denx.de> + - Stefan Agner <stefan@agner.ch> + +description: | + (e)LCDIF display controller found in the Freescale/NXP i.MX SoCs. + +properties: + compatible: + oneOf: + - enum: + - fsl,imx23-lcdif + - fsl,imx28-lcdif + - fsl,imx6sx-lcdif + - items: + - enum: + - fsl,imx6sl-lcdif + - fsl,imx6sll-lcdif + - fsl,imx6ul-lcdif + - fsl,imx7d-lcdif + - fsl,imx8mm-lcdif + - fsl,imx8mq-lcdif + - const: fsl,imx6sx-lcdif + + reg: + maxItems: 1 + + clocks: + items: + - description: Pixel clock + - description: Bus clock + - description: Display AXI clock + minItems: 1 + + clock-names: + items: + - const: pix + - const: axi + - const: disp_axi + minItems: 1 + + interrupts: + maxItems: 1 + + port: + $ref: /schemas/graph.yaml#/properties/port + description: The LCDIF output port + +required: + - compatible + - reg + - clocks + - interrupts + - port + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + const: fsl,imx6sx-lcdif + then: + properties: + clocks: + minItems: 2 + maxItems: 3 + clock-names: + minItems: 2 + maxItems: 3 + required: + - clock-names + else: + properties: + clocks: + maxItems: 1 + clock-names: + maxItems: 1 + +examples: + - | + #include <dt-bindings/clock/imx6sx-clock.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + display-controller@2220000 { + compatible = "fsl,imx6sx-lcdif"; + reg = <0x02220000 0x4000>; + interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX6SX_CLK_LCDIF1_PIX>, + <&clks IMX6SX_CLK_LCDIF_APB>, + <&clks IMX6SX_CLK_DISPLAY_AXI>; + clock-names = "pix", "axi", "disp_axi"; + + port { + endpoint { + remote-endpoint = <&panel_in>; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml b/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml new file mode 100644 index 000000000000..af7fe9c4d196 --- /dev/null +++ b/Documentation/devicetree/bindings/display/imx/fsl,imx6-hdmi.yaml @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/imx/fsl,imx6-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX6 DWC HDMI TX Encoder + +maintainers: + - Philipp Zabel <p.zabel@pengutronix.de> + +description: | + The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP + with a companion PHY IP. + +allOf: + - $ref: ../bridge/synopsys,dw-hdmi.yaml# + +properties: + compatible: + enum: + - fsl,imx6dl-hdmi + - fsl,imx6q-hdmi + + reg-io-width: + const: 1 + + clocks: + maxItems: 2 + + clock-names: + maxItems: 2 + + ddc-i2c-bus: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The HDMI DDC bus can be connected to either a system I2C master or the + functionally-reduced I2C master contained in the DWC HDMI. When connected + to a system I2C master this property contains a phandle to that I2C + master controller. + + gpr: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the iomuxc-gpr region containing the HDMI multiplexer control + register. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + description: | + This device has four video ports, corresponding to the four inputs of the + HDMI multiplexer. Each port shall have a single endpoint. + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: First input of the HDMI multiplexer + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: Second input of the HDMI multiplexer + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: Third input of the HDMI multiplexer + + port@3: + $ref: /schemas/graph.yaml#/properties/port + description: Fourth input of the HDMI multiplexer + + anyOf: + - required: + - port@0 + - required: + - port@1 + - required: + - port@2 + - required: + - port@3 + +required: + - compatible + - reg + - clocks + - clock-names + - gpr + - interrupts + - ports + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/imx6qdl-clock.h> + + hdmi: hdmi@120000 { + reg = <0x00120000 0x9000>; + interrupts = <0 115 0x04>; + gpr = <&gpr>; + clocks = <&clks IMX6QDL_CLK_HDMI_IAHB>, + <&clks IMX6QDL_CLK_HDMI_ISFR>; + clock-names = "iahb", "isfr"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + hdmi_mux_0: endpoint { + remote-endpoint = <&ipu1_di0_hdmi>; + }; + }; + + port@1 { + reg = <1>; + + hdmi_mux_1: endpoint { + remote-endpoint = <&ipu1_di1_hdmi>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/imx/hdmi.txt b/Documentation/devicetree/bindings/display/imx/hdmi.txt deleted file mode 100644 index 6d021e71c9cf..000000000000 --- a/Documentation/devicetree/bindings/display/imx/hdmi.txt +++ /dev/null @@ -1,65 +0,0 @@ -Freescale i.MX6 DWC HDMI TX Encoder -=================================== - -The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with a companion PHY IP. - -These DT bindings follow the Synopsys DWC HDMI TX bindings defined in -Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the -following device-specific properties. - - -Required properties: - -- compatible : Shall be one of "fsl,imx6q-hdmi" or "fsl,imx6dl-hdmi". -- reg: See dw_hdmi.txt. -- interrupts: HDMI interrupt number -- clocks: See dw_hdmi.txt. -- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. -- ports: See dw_hdmi.txt. The DWC HDMI shall have between one and four ports, - numbered 0 to 3, corresponding to the four inputs of the HDMI multiplexer. - Each port shall have a single endpoint. -- gpr : Shall contain a phandle to the iomuxc-gpr region containing the HDMI - multiplexer control register. - -Optional properties - -- ddc-i2c-bus: The HDMI DDC bus can be connected to either a system I2C master - or the functionally-reduced I2C master contained in the DWC HDMI. When - connected to a system I2C master this property contains a phandle to that - I2C master controller. - - -Example: - - gpr: iomuxc-gpr@20e0000 { - /* ... */ - }; - - hdmi: hdmi@120000 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "fsl,imx6q-hdmi"; - reg = <0x00120000 0x9000>; - interrupts = <0 115 0x04>; - gpr = <&gpr>; - clocks = <&clks 123>, <&clks 124>; - clock-names = "iahb", "isfr"; - ddc-i2c-bus = <&i2c2>; - - port@0 { - reg = <0>; - - hdmi_mux_0: endpoint { - remote-endpoint = <&ipu1_di0_hdmi>; - }; - }; - - port@1 { - reg = <1>; - - hdmi_mux_1: endpoint { - remote-endpoint = <&ipu1_di1_hdmi>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt index 93b160df3eec..fbb59c9ddda6 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt @@ -64,7 +64,7 @@ Required properties (DMA function blocks): - larb: Should contain a phandle pointing to the local arbiter device as defined in Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml - iommus: Should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. Optional properties (RDMA function blocks): diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml index 6cdb734c91a9..dd2896a40ff0 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,dpi.yaml @@ -22,6 +22,7 @@ properties: - mediatek,mt7623-dpi - mediatek,mt8173-dpi - mediatek,mt8183-dpi + - mediatek,mt8192-dpi reg: maxItems: 1 @@ -50,15 +51,10 @@ properties: - const: sleep port: - type: object + $ref: /schemas/graph.yaml#/properties/port description: - Output port node with endpoint definitions as described in - Documentation/devicetree/bindings/graph.txt. This port should be connected - to the input port of an attached HDMI or LVDS encoder chip. - - properties: - endpoint: - type: object + Output port node. This port should be connected to the input port of an + attached HDMI or LVDS encoder chip. required: - compatible diff --git a/Documentation/devicetree/bindings/display/mxsfb.txt b/Documentation/devicetree/bindings/display/mxsfb.txt deleted file mode 100644 index c985871c46b3..000000000000 --- a/Documentation/devicetree/bindings/display/mxsfb.txt +++ /dev/null @@ -1,87 +0,0 @@ -* Freescale MXS LCD Interface (LCDIF) - -New bindings: -============= -Required properties: -- compatible: Should be "fsl,imx23-lcdif" for i.MX23. - Should be "fsl,imx28-lcdif" for i.MX28. - Should be "fsl,imx6sx-lcdif" for i.MX6SX. - Should be "fsl,imx8mq-lcdif" for i.MX8MQ. -- reg: Address and length of the register set for LCDIF -- interrupts: Should contain LCDIF interrupt -- clocks: A list of phandle + clock-specifier pairs, one for each - entry in 'clock-names'. -- clock-names: A list of clock names. For MXSFB it should contain: - - "pix" for the LCDIF block clock - - (MX6SX-only) "axi", "disp_axi" for the bus interface clock - -Required sub-nodes: - - port: The connection to an encoder chip. - -Example: - - lcdif1: display-controller@2220000 { - compatible = "fsl,imx6sx-lcdif", "fsl,imx28-lcdif"; - reg = <0x02220000 0x4000>; - interrupts = <GIC_SPI 5 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks IMX6SX_CLK_LCDIF1_PIX>, - <&clks IMX6SX_CLK_LCDIF_APB>, - <&clks IMX6SX_CLK_DISPLAY_AXI>; - clock-names = "pix", "axi", "disp_axi"; - - port { - parallel_out: endpoint { - remote-endpoint = <&panel_in_parallel>; - }; - }; - }; - -Deprecated bindings: -==================== -Required properties: -- compatible: Should be "fsl,imx23-lcdif" for i.MX23. - Should be "fsl,imx28-lcdif" for i.MX28. -- reg: Address and length of the register set for LCDIF -- interrupts: Should contain LCDIF interrupts -- display: phandle to display node (see below for details) - -* display node - -Required properties: -- bits-per-pixel: <16> for RGB565, <32> for RGB888/666. -- bus-width: number of data lines. Could be <8>, <16>, <18> or <24>. - -Required sub-node: -- display-timings: Refer to binding doc display-timing.txt for details. - -Examples: - -lcdif@80030000 { - compatible = "fsl,imx28-lcdif"; - reg = <0x80030000 2000>; - interrupts = <38 86>; - - display: display { - bits-per-pixel = <32>; - bus-width = <24>; - - display-timings { - native-mode = <&timing0>; - timing0: timing0 { - clock-frequency = <33500000>; - hactive = <800>; - vactive = <480>; - hfront-porch = <164>; - hback-porch = <89>; - hsync-len = <10>; - vback-porch = <23>; - vfront-porch = <10>; - vsync-len = <10>; - hsync-active = <0>; - vsync-active = <0>; - de-active = <1>; - pixelclk-active = <0>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 62b0d54d87b7..b3797ba2698b 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -161,6 +161,8 @@ properties: # Innolux Corporation 12.1" G121X1-L03 XGA (1024x768) TFT LCD panel - innolux,g121x1-l03 # Innolux Corporation 11.6" WXGA (1366x768) TFT LCD panel + - innolux,n116bca-ea1 + # Innolux Corporation 11.6" WXGA (1366x768) TFT LCD panel - innolux,n116bge # InnoLux 13.3" FHD (1920x1080) eDP TFT LCD panel - innolux,n125hce-gn1 diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt deleted file mode 100644 index 7d65c24fcda8..000000000000 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ /dev/null @@ -1,145 +0,0 @@ -* Renesas R-Car Display Unit (DU) - -Required Properties: - - - compatible: must be one of the following. - - "renesas,du-r8a7742" for R8A7742 (RZ/G1H) compatible DU - - "renesas,du-r8a7743" for R8A7743 (RZ/G1M) compatible DU - - "renesas,du-r8a7744" for R8A7744 (RZ/G1N) compatible DU - - "renesas,du-r8a7745" for R8A7745 (RZ/G1E) compatible DU - - "renesas,du-r8a77470" for R8A77470 (RZ/G1C) compatible DU - - "renesas,du-r8a774a1" for R8A774A1 (RZ/G2M) compatible DU - - "renesas,du-r8a774b1" for R8A774B1 (RZ/G2N) compatible DU - - "renesas,du-r8a774c0" for R8A774C0 (RZ/G2E) compatible DU - - "renesas,du-r8a774e1" for R8A774E1 (RZ/G2H) compatible DU - - "renesas,du-r8a7779" for R8A7779 (R-Car H1) compatible DU - - "renesas,du-r8a7790" for R8A7790 (R-Car H2) compatible DU - - "renesas,du-r8a7791" for R8A7791 (R-Car M2-W) compatible DU - - "renesas,du-r8a7792" for R8A7792 (R-Car V2H) compatible DU - - "renesas,du-r8a7793" for R8A7793 (R-Car M2-N) compatible DU - - "renesas,du-r8a7794" for R8A7794 (R-Car E2) compatible DU - - "renesas,du-r8a7795" for R8A7795 (R-Car H3) compatible DU - - "renesas,du-r8a7796" for R8A7796 (R-Car M3-W) compatible DU - - "renesas,du-r8a77961" for R8A77961 (R-Car M3-W+) compatible DU - - "renesas,du-r8a77965" for R8A77965 (R-Car M3-N) compatible DU - - "renesas,du-r8a77970" for R8A77970 (R-Car V3M) compatible DU - - "renesas,du-r8a77980" for R8A77980 (R-Car V3H) compatible DU - - "renesas,du-r8a77990" for R8A77990 (R-Car E3) compatible DU - - "renesas,du-r8a77995" for R8A77995 (R-Car D3) compatible DU - - - reg: the memory-mapped I/O registers base address and length - - - interrupts: Interrupt specifiers for the DU interrupts. - - - clocks: A list of phandles + clock-specifier pairs, one for each entry in - the clock-names property. - - clock-names: Name of the clocks. This property is model-dependent. - - R8A7779 uses a single functional clock. The clock doesn't need to be - named. - - All other DU instances use one functional clock per channel The - functional clocks must be named "du.x" with "x" being the channel - numerical index. - - In addition to the functional clocks, all DU versions also support - externally supplied pixel clocks. Those clocks are optional. When - supplied they must be named "dclkin.x" with "x" being the input clock - numerical index. - - - renesas,cmms: A list of phandles to the CMM instances present in the SoC, - one for each available DU channel. The property shall not be specified for - SoCs that do not provide any CMM (such as V3M and V3H). - - - renesas,vsps: A list of phandle and channel index tuples to the VSPs that - handle the memory interfaces for the DU channels. The phandle identifies the - VSP instance that serves the DU channel, and the channel index identifies - the LIF instance in that VSP. - -Optional properties: - - resets: A list of phandle + reset-specifier pairs, one for each entry in - the reset-names property. - - reset-names: Names of the resets. This property is model-dependent. - - All but R8A7779 use one reset for a group of one or more successive - channels. The resets must be named "du.x" with "x" being the numerical - index of the lowest channel in the group. - -Required nodes: - -The connections to the DU output video ports are modeled using the OF graph -bindings specified in Documentation/devicetree/bindings/graph.txt. - -The following table lists for each supported model the port number -corresponding to each DU output. - - Port0 Port1 Port2 Port3 ------------------------------------------------------------------------------ - R8A7742 (RZ/G1H) DPAD 0 LVDS 0 LVDS 1 - - R8A7743 (RZ/G1M) DPAD 0 LVDS 0 - - - R8A7744 (RZ/G1N) DPAD 0 LVDS 0 - - - R8A7745 (RZ/G1E) DPAD 0 DPAD 1 - - - R8A77470 (RZ/G1C) DPAD 0 DPAD 1 LVDS 0 - - R8A774A1 (RZ/G2M) DPAD 0 HDMI 0 LVDS 0 - - R8A774B1 (RZ/G2N) DPAD 0 HDMI 0 LVDS 0 - - R8A774C0 (RZ/G2E) DPAD 0 LVDS 0 LVDS 1 - - R8A774E1 (RZ/G2H) DPAD 0 HDMI 0 LVDS 0 - - R8A7779 (R-Car H1) DPAD 0 DPAD 1 - - - R8A7790 (R-Car H2) DPAD 0 LVDS 0 LVDS 1 - - R8A7791 (R-Car M2-W) DPAD 0 LVDS 0 - - - R8A7792 (R-Car V2H) DPAD 0 DPAD 1 - - - R8A7793 (R-Car M2-N) DPAD 0 LVDS 0 - - - R8A7794 (R-Car E2) DPAD 0 DPAD 1 - - - R8A7795 (R-Car H3) DPAD 0 HDMI 0 HDMI 1 LVDS 0 - R8A7796 (R-Car M3-W) DPAD 0 HDMI 0 LVDS 0 - - R8A77961 (R-Car M3-W+) DPAD 0 HDMI 0 LVDS 0 - - R8A77965 (R-Car M3-N) DPAD 0 HDMI 0 LVDS 0 - - R8A77970 (R-Car V3M) DPAD 0 LVDS 0 - - - R8A77980 (R-Car V3H) DPAD 0 LVDS 0 - - - R8A77990 (R-Car E3) DPAD 0 LVDS 0 LVDS 1 - - R8A77995 (R-Car D3) DPAD 0 LVDS 0 LVDS 1 - - - -Example: R8A7795 (R-Car H3) ES2.0 DU - - du: display@feb00000 { - compatible = "renesas,du-r8a7795"; - reg = <0 0xfeb00000 0 0x80000>; - interrupts = <GIC_SPI 256 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 268 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 269 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 270 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 724>, - <&cpg CPG_MOD 723>, - <&cpg CPG_MOD 722>, - <&cpg CPG_MOD 721>; - clock-names = "du.0", "du.1", "du.2", "du.3"; - resets = <&cpg 724>, <&cpg 722>; - reset-names = "du.0", "du.2"; - renesas,cmms = <&cmm0>, <&cmm1>, <&cmm2>, <&cmm3>; - renesas,vsps = <&vspd0 0>, <&vspd1 0>, <&vspd2 0>, <&vspd0 1>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - du_out_rgb: endpoint { - }; - }; - port@1 { - reg = <1>; - du_out_hdmi0: endpoint { - remote-endpoint = <&dw_hdmi0_in>; - }; - }; - port@2 { - reg = <2>; - du_out_hdmi1: endpoint { - remote-endpoint = <&dw_hdmi1_in>; - }; - }; - port@3 { - reg = <3>; - du_out_lvds0: endpoint { - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/display/renesas,du.yaml b/Documentation/devicetree/bindings/display/renesas,du.yaml new file mode 100644 index 000000000000..552a99ce4f12 --- /dev/null +++ b/Documentation/devicetree/bindings/display/renesas,du.yaml @@ -0,0 +1,831 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/renesas,du.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Display Unit (DU) + +maintainers: + - Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> + +description: | + These DT bindings describe the Display Unit embedded in the Renesas R-Car + Gen1, R-Car Gen2, R-Car Gen3, RZ/G1 and RZ/G2 SoCs. + +properties: + compatible: + enum: + - renesas,du-r8a7742 # for RZ/G1H compatible DU + - renesas,du-r8a7743 # for RZ/G1M compatible DU + - renesas,du-r8a7744 # for RZ/G1N compatible DU + - renesas,du-r8a7745 # for RZ/G1E compatible DU + - renesas,du-r8a77470 # for RZ/G1C compatible DU + - renesas,du-r8a774a1 # for RZ/G2M compatible DU + - renesas,du-r8a774b1 # for RZ/G2N compatible DU + - renesas,du-r8a774c0 # for RZ/G2E compatible DU + - renesas,du-r8a774e1 # for RZ/G2H compatible DU + - renesas,du-r8a7779 # for R-Car H1 compatible DU + - renesas,du-r8a7790 # for R-Car H2 compatible DU + - renesas,du-r8a7791 # for R-Car M2-W compatible DU + - renesas,du-r8a7792 # for R-Car V2H compatible DU + - renesas,du-r8a7793 # for R-Car M2-N compatible DU + - renesas,du-r8a7794 # for R-Car E2 compatible DU + - renesas,du-r8a7795 # for R-Car H3 compatible DU + - renesas,du-r8a7796 # for R-Car M3-W compatible DU + - renesas,du-r8a77961 # for R-Car M3-W+ compatible DU + - renesas,du-r8a77965 # for R-Car M3-N compatible DU + - renesas,du-r8a77970 # for R-Car V3M compatible DU + - renesas,du-r8a77980 # for R-Car V3H compatible DU + - renesas,du-r8a77990 # for R-Car E3 compatible DU + - renesas,du-r8a77995 # for R-Car D3 compatible DU + + reg: + maxItems: 1 + + # See compatible-specific constraints below. + clocks: true + clock-names: true + interrupts: + description: Interrupt specifiers, one per DU channel + resets: true + reset-names: true + + ports: + $ref: /schemas/graph.yaml#/properties/port + description: | + The connections to the DU output video ports are modeled using the OF + graph bindings specified in Documentation/devicetree/bindings/graph.txt. + The number of ports and their assignment are model-dependent. Each port + shall have a single endpoint. + + patternProperties: + "^port@[0-3]$": + $ref: /schemas/graph.yaml#/properties/port + unevaluatedProperties: false + + required: + - port@0 + - port@1 + + unevaluatedProperties: false + + renesas,cmms: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + description: + A list of phandles to the CMM instances present in the SoC, one for each + available DU channel. + + renesas,vsps: + $ref: "/schemas/types.yaml#/definitions/phandle-array" + description: + A list of phandle and channel index tuples to the VSPs that handle the + memory interfaces for the DU channels. The phandle identifies the VSP + instance that serves the DU channel, and the channel index identifies + the LIF instance in that VSP. + +required: + - compatible + - reg + - clocks + - interrupts + - resets + - ports + +allOf: + - if: + properties: + compatible: + contains: + const: renesas,du-r8a7779 + then: + properties: + clocks: + minItems: 1 + maxItems: 3 + items: + - description: Functional clock + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 1 + maxItems: 3 + items: + - const: du.0 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + # port@2 is TCON, not supported yet + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - interrupts + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7743 + - renesas,du-r8a7744 + - renesas,du-r8a7791 + - renesas,du-r8a7793 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + # port@2 is TCON, not supported yet + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7745 + - renesas,du-r8a7792 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7794 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + # port@2 is TCON, not supported yet + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a77470 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: DPAD 1 + port@2: + description: LVDS 0 + # port@3 is DVENC, not supported yet + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7742 + - renesas,du-r8a7790 + then: + properties: + clocks: + minItems: 3 + maxItems: 6 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU2 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN2 input clock + + clock-names: + minItems: 3 + maxItems: 6 + items: + - const: du.0 + - const: du.1 + - const: du.2 + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + + interrupts: + maxItems: 3 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + port@2: + description: LVDS 1 + # port@3 is TCON, not supported yet + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + required: + - clock-names + - interrupts + - resets + - reset-names + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a7795 + then: + properties: + clocks: + minItems: 4 + maxItems: 8 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU2 + - description: Functional clock for DU4 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN2 input clock + - description: DU_DOTCLKIN3 input clock + + clock-names: + minItems: 4 + maxItems: 8 + items: + - const: du.0 + - const: du.1 + - const: du.2 + - const: du.3 + - pattern: '^dclkin\.[0123]$' + - pattern: '^dclkin\.[0123]$' + - pattern: '^dclkin\.[0123]$' + - pattern: '^dclkin\.[0123]$' + + interrupts: + maxItems: 4 + + resets: + maxItems: 2 + + reset-names: + items: + - const: du.0 + - const: du.2 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: HDMI 0 + port@2: + description: HDMI 1 + port@3: + description: LVDS 0 + + required: + - port@0 + - port@1 + - port@2 + - port@3 + + renesas,cmms: + minItems: 4 + + renesas,vsps: + minItems: 4 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a774a1 + - renesas,du-r8a7796 + - renesas,du-r8a77961 + then: + properties: + clocks: + minItems: 3 + maxItems: 6 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU2 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN2 input clock + + clock-names: + minItems: 3 + maxItems: 6 + items: + - const: du.0 + - const: du.1 + - const: du.2 + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + - pattern: '^dclkin\.[012]$' + + interrupts: + maxItems: 3 + + resets: + maxItems: 2 + + reset-names: + items: + - const: du.0 + - const: du.2 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: HDMI 0 + port@2: + description: LVDS 0 + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + renesas,cmms: + minItems: 3 + + renesas,vsps: + minItems: 3 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a774b1 + - renesas,du-r8a774e1 + - renesas,du-r8a77965 + then: + properties: + clocks: + minItems: 3 + maxItems: 6 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: Functional clock for DU3 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + - description: DU_DOTCLKIN3 input clock + + clock-names: + minItems: 3 + maxItems: 6 + items: + - const: du.0 + - const: du.1 + - const: du.3 + - pattern: '^dclkin\.[013]$' + - pattern: '^dclkin\.[013]$' + - pattern: '^dclkin\.[013]$' + + interrupts: + maxItems: 3 + + resets: + maxItems: 2 + + reset-names: + items: + - const: du.0 + - const: du.3 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: HDMI 0 + port@2: + description: LVDS 0 + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + renesas,cmms: + minItems: 3 + + renesas,vsps: + minItems: 3 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a77970 + - renesas,du-r8a77980 + then: + properties: + clocks: + minItems: 1 + maxItems: 2 + items: + - description: Functional clock for DU0 + - description: DU_DOTCLKIN0 input clock + + clock-names: + minItems: 1 + maxItems: 2 + items: + - const: du.0 + - const: dclkin.0 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + port@2: false + port@3: false + + required: + - port@0 + - port@1 + + renesas,vsps: + minItems: 1 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + + - if: + properties: + compatible: + contains: + enum: + - renesas,du-r8a774c0 + - renesas,du-r8a77990 + - renesas,du-r8a77995 + then: + properties: + clocks: + minItems: 2 + maxItems: 4 + items: + - description: Functional clock for DU0 + - description: Functional clock for DU1 + - description: DU_DOTCLKIN0 input clock + - description: DU_DOTCLKIN1 input clock + + clock-names: + minItems: 2 + maxItems: 4 + items: + - const: du.0 + - const: du.1 + - pattern: '^dclkin\.[01]$' + - pattern: '^dclkin\.[01]$' + + interrupts: + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + items: + - const: du.0 + + ports: + properties: + port@0: + description: DPAD 0 + port@1: + description: LVDS 0 + port@2: + description: LVDS 1 + # port@3 is TCON, not supported yet + port@3: false + + required: + - port@0 + - port@1 + - port@2 + + renesas,cmms: + minItems: 2 + + renesas,vsps: + minItems: 2 + + required: + - clock-names + - interrupts + - resets + - reset-names + - renesas,vsps + +additionalProperties: false + +examples: + # R-Car H3 ES2.0 DU + - | + #include <dt-bindings/clock/renesas-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + display@feb00000 { + compatible = "renesas,du-r8a7795"; + reg = <0xfeb00000 0x80000>; + interrupts = <GIC_SPI 256 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 268 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 269 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 270 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 724>, + <&cpg CPG_MOD 723>, + <&cpg CPG_MOD 722>, + <&cpg CPG_MOD 721>; + clock-names = "du.0", "du.1", "du.2", "du.3"; + resets = <&cpg 724>, <&cpg 722>; + reset-names = "du.0", "du.2"; + + renesas,cmms = <&cmm0>, <&cmm1>, <&cmm2>, <&cmm3>; + renesas,vsps = <&vspd0 0>, <&vspd1 0>, <&vspd2 0>, <&vspd0 1>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + endpoint { + remote-endpoint = <&adv7123_in>; + }; + }; + port@1 { + reg = <1>; + endpoint { + remote-endpoint = <&dw_hdmi0_in>; + }; + }; + port@2 { + reg = <2>; + endpoint { + remote-endpoint = <&dw_hdmi1_in>; + }; + }; + port@3 { + reg = <3>; + endpoint { + remote-endpoint = <&lvds0_in>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt deleted file mode 100644 index 3d32ce137e7f..000000000000 --- a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt +++ /dev/null @@ -1,74 +0,0 @@ -Rockchip DWC HDMI TX Encoder -============================ - -The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with a companion PHY IP. - -These DT bindings follow the Synopsys DWC HDMI TX bindings defined in -Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the -following device-specific properties. - - -Required properties: - -- compatible: should be one of the following: - "rockchip,rk3228-dw-hdmi" - "rockchip,rk3288-dw-hdmi" - "rockchip,rk3328-dw-hdmi" - "rockchip,rk3399-dw-hdmi" -- reg: See dw_hdmi.txt. -- reg-io-width: See dw_hdmi.txt. Shall be 4. -- interrupts: HDMI interrupt number -- clocks: See dw_hdmi.txt. -- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. -- ports: See dw_hdmi.txt. The DWC HDMI shall have a single port numbered 0 - corresponding to the video input of the controller. The port shall have two - endpoints, numbered 0 and 1, connected respectively to the vopb and vopl. -- rockchip,grf: Shall reference the GRF to mux vopl/vopb. - -Optional properties - -- ddc-i2c-bus: The HDMI DDC bus can be connected to either a system I2C master - or the functionally-reduced I2C master contained in the DWC HDMI. When - connected to a system I2C master this property contains a phandle to that - I2C master controller. -- clock-names: See dw_hdmi.txt. The "cec" clock is optional. -- clock-names: May contain "cec" as defined in dw_hdmi.txt. -- clock-names: May contain "grf", power for grf io. -- clock-names: May contain "vpll", external clock for some hdmi phy. -- phys: from general PHY binding: the phandle for the PHY device. -- phy-names: Should be "hdmi" if phys references an external phy. - -Optional pinctrl entry: -- If you have both a "unwedge" and "default" pinctrl entry, dw_hdmi - will switch to the unwedge pinctrl state for 10ms if it ever gets an - i2c timeout. It's intended that this unwedge pinctrl entry will - cause the SDA line to be driven low to work around a hardware - errata. - -Example: - -hdmi: hdmi@ff980000 { - compatible = "rockchip,rk3288-dw-hdmi"; - reg = <0xff980000 0x20000>; - reg-io-width = <4>; - ddc-i2c-bus = <&i2c5>; - rockchip,grf = <&grf>; - interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cru PCLK_HDMI_CTRL>, <&cru SCLK_HDMI_HDCP>; - clock-names = "iahb", "isfr"; - ports { - hdmi_in: port { - #address-cells = <1>; - #size-cells = <0>; - hdmi_in_vopb: endpoint@0 { - reg = <0>; - remote-endpoint = <&vopb_out_hdmi>; - }; - hdmi_in_vopl: endpoint@1 { - reg = <1>; - remote-endpoint = <&vopl_out_hdmi>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml new file mode 100644 index 000000000000..75cd9c686e98 --- /dev/null +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml @@ -0,0 +1,156 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/rockchip/rockchip,dw-hdmi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip DWC HDMI TX Encoder + +maintainers: + - Mark Yao <markyao0591@gmail.com> + +description: | + The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP + with a companion PHY IP. + +allOf: + - $ref: ../bridge/synopsys,dw-hdmi.yaml# + +properties: + compatible: + enum: + - rockchip,rk3228-dw-hdmi + - rockchip,rk3288-dw-hdmi + - rockchip,rk3328-dw-hdmi + - rockchip,rk3399-dw-hdmi + + reg-io-width: + const: 4 + + clocks: + minItems: 2 + maxItems: 5 + items: + - {} + - {} + # The next three clocks are all optional, but shall be specified in this + # order when present. + - description: The HDMI CEC controller main clock + - description: Power for GRF IO + - description: External clock for some HDMI PHY + + clock-names: + minItems: 2 + maxItems: 5 + items: + - {} + - {} + - enum: + - cec + - grf + - vpll + - enum: + - grf + - vpll + - const: vpll + + ddc-i2c-bus: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The HDMI DDC bus can be connected to either a system I2C master or the + functionally-reduced I2C master contained in the DWC HDMI. When connected + to a system I2C master this property contains a phandle to that I2C + master controller. + + phys: + maxItems: 1 + description: The HDMI PHY + + phy-names: + const: hdmi + + pinctrl-names: + description: + The unwedge pinctrl entry shall drive the DDC SDA line low. This is + intended to work around a hardware errata that can cause the DDC I2C + bus to be wedged. + items: + - const: default + - const: unwedge + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: Input of the DWC HDMI TX + + properties: + endpoint@0: + $ref: /schemas/graph.yaml#/properties/endpoint + description: Connection to the VOPB + + endpoint@1: + $ref: /schemas/graph.yaml#/properties/endpoint + description: Connection to the VOPL + + required: + - endpoint@0 + - endpoint@1 + + required: + - port + + rockchip,grf: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the GRF to mux vopl/vopb. + +required: + - compatible + - reg + - reg-io-width + - clocks + - clock-names + - interrupts + - ports + - rockchip,grf + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/rk3288-cru.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + hdmi: hdmi@ff980000 { + compatible = "rockchip,rk3288-dw-hdmi"; + reg = <0xff980000 0x20000>; + reg-io-width = <4>; + ddc-i2c-bus = <&i2c5>; + rockchip,grf = <&grf>; + interrupts = <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru PCLK_HDMI_CTRL>, <&cru SCLK_HDMI_HDCP>; + clock-names = "iahb", "isfr"; + + ports { + port { + #address-cells = <1>; + #size-cells = <0>; + + hdmi_in_vopb: endpoint@0 { + reg = <0>; + remote-endpoint = <&vopb_out_hdmi>; + }; + hdmi_in_vopl: endpoint@1 { + reg = <1>; + remote-endpoint = <&vopl_out_hdmi>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml index eaf8c54fcf50..c2499a7906f5 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer.yaml +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.yaml @@ -54,6 +54,7 @@ properties: compatible: items: - enum: + - apple,simple-framebuffer - allwinner,simple-framebuffer - amlogic,simple-framebuffer - const: simple-framebuffer @@ -84,9 +85,13 @@ properties: 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 + * `x2r10g10b10` - 32-bit pixels, d[29:20]=r, d[19:10]=g, d[9:0]=b + * `x8r8g8b8` - 32-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b enum: - a8b8g8r8 - r5g6b5 + - x2r10g10b10 + - x8r8g8b8 display: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt deleted file mode 100644 index 35383adb10f1..000000000000 --- a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt +++ /dev/null @@ -1,41 +0,0 @@ -Qualcomm's PM8941 USB ID Extcon device - -Some Qualcomm PMICs have a "misc" module that can be used to detect when -the USB ID pin has been pulled low or high. - -PROPERTIES - -- compatible: - Usage: required - Value type: <string> - Definition: Should contain "qcom,pm8941-misc"; - -- reg: - Usage: required - Value type: <u32> - Definition: Should contain the offset to the misc address space - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: Should contain the usb id interrupt - -- interrupt-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the string "usb_id" for the usb id interrupt - -Example: - - pmic { - usb_id: misc@900 { - compatible = "qcom,pm8941-misc"; - reg = <0x900>; - interrupts = <0x0 0x9 0 IRQ_TYPE_EDGE_BOTH>; - interrupt-names = "usb_id"; - }; - } - - usb-controller { - extcon = <&usb_id>; - }; diff --git a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml new file mode 100644 index 000000000000..6a9c96f0352a --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/extcon/qcom,pm8941-misc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. PM8941 USB ID Extcon device + +maintainers: + - Guru Das Srinagesh <gurus@codeaurora.org> + +description: | + Some Qualcomm PMICs have a "misc" module that can be used to detect when + the USB ID pin has been pulled low or high. + +properties: + compatible: + items: + - const: qcom,pm8941-misc + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + maxItems: 2 + + interrupt-names: + minItems: 1 + items: + - const: usb_id + - const: usb_vbus + +required: + - compatible + - reg + - interrupts + - interrupt-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + pmic { + #address-cells = <1>; + #size-cells = <0>; + interrupt-controller; + #interrupt-cells = <4>; + + usb_id: misc@900 { + compatible = "qcom,pm8941-misc"; + reg = <0x900>; + interrupts = <0x0 0x9 0 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "usb_id"; + }; + }; + + usb-controller { + extcon = <&usb_id>; + }; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index a884955f861e..e747d73687cb 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -20,7 +20,9 @@ Required properties: * "qcom,scm-msm8996" * "qcom,scm-msm8998" * "qcom,scm-sc7180" + * "qcom,scm-sc7280" * "qcom,scm-sdm845" + * "qcom,scm-sdx55" * "qcom,scm-sm8150" * "qcom,scm-sm8250" * "qcom,scm-sm8350" diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt index e811cf825019..d787d57491a1 100644 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -245,36 +245,31 @@ Base tree contains: Overlay contains: -/dts-v1/ /plugin/; -/ { - fragment@0 { - target = <&fpga_region0>; - #address-cells = <1>; - #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "soc_system.rbf"; - fpga-bridges = <&fpga_bridge1>; - ranges = <0x20000 0xff200000 0x100000>, - <0x0 0xc0000000 0x20000000>; - - gpio@10040 { - compatible = "altr,pio-1.0"; - reg = <0x10040 0x20>; - altr,ngpio = <4>; - #gpio-cells = <2>; - clocks = <2>; - gpio-controller; - }; - - onchip-memory { - device_type = "memory"; - compatible = "altr,onchipmem-15.1"; - reg = <0x0 0x10000>; - }; - }; +/dts-v1/; +/plugin/; + +&fpga_region0 { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "soc_system.rbf"; + fpga-bridges = <&fpga_bridge1>; + ranges = <0x20000 0xff200000 0x100000>, + <0x0 0xc0000000 0x20000000>; + + gpio@10040 { + compatible = "altr,pio-1.0"; + reg = <0x10040 0x20>; + altr,ngpio = <4>; + #gpio-cells = <2>; + clocks = <2>; + gpio-controller; + }; + + onchip-memory { + device_type = "memory"; + compatible = "altr,onchipmem-15.1"; + reg = <0x0 0x10000>; }; }; @@ -371,25 +366,22 @@ Live Device Tree contains: }; DT Overlay contains: -/dts-v1/ /plugin/; -/ { -fragment@0 { - target = <&fpga_region0>; + +/dts-v1/; +/plugin/; + +&fpga_region0 { #address-cells = <1>; #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - firmware-name = "zynq-gpio.bin"; + firmware-name = "zynq-gpio.bin"; - gpio1: gpio@40000000 { - compatible = "xlnx,xps-gpio-1.00.a"; - reg = <0x40000000 0x10000>; - gpio-controller; - #gpio-cells = <0x2>; - xlnx,gpio-width= <0x6>; - }; + gpio1: gpio@40000000 { + compatible = "xlnx,xps-gpio-1.00.a"; + reg = <0x40000000 0x10000>; + gpio-controller; + #gpio-cells = <0x2>; + xlnx,gpio-width= <0x6>; }; }; @@ -402,41 +394,37 @@ This example programs the FPGA to have two regions that can later be partially configured. Each region has its own bridge in the FPGA fabric. DT Overlay contains: -/dts-v1/ /plugin/; -/ { - fragment@0 { - target = <&fpga_region0>; - #address-cells = <1>; - #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "base.rbf"; - - fpga-bridge@4400 { - compatible = "altr,freeze-bridge-controller"; - reg = <0x4400 0x10>; - - fpga_region1: fpga-region1 { - compatible = "fpga-region"; - #address-cells = <0x1>; - #size-cells = <0x1>; - ranges; - }; - }; - - fpga-bridge@4420 { - compatible = "altr,freeze-bridge-controller"; - reg = <0x4420 0x10>; - - fpga_region2: fpga-region2 { - compatible = "fpga-region"; - #address-cells = <0x1>; - #size-cells = <0x1>; - ranges; - }; - }; + +/dts-v1/; +/plugin/; + +&fpga_region0 { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "base.rbf"; + + fpga-bridge@4400 { + compatible = "altr,freeze-bridge-controller"; + reg = <0x4400 0x10>; + + fpga_region1: fpga-region1 { + compatible = "fpga-region"; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + }; + + fpga-bridge@4420 { + compatible = "altr,freeze-bridge-controller"; + reg = <0x4420 0x10>; + + fpga_region2: fpga-region2 { + compatible = "fpga-region"; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; }; }; }; @@ -451,28 +439,23 @@ differences are that the FPGA is partially reconfigured due to the "partial-fpga-config" boolean and the only bridge that is controlled during programming is the FPGA based bridge of fpga_region1. -/dts-v1/ /plugin/; -/ { - fragment@0 { - target = <&fpga_region1>; - #address-cells = <1>; - #size-cells = <1>; - __overlay__ { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "soc_image2.rbf"; - partial-fpga-config; - - gpio@10040 { - compatible = "altr,pio-1.0"; - reg = <0x10040 0x20>; - clocks = <0x2>; - altr,ngpio = <0x4>; - #gpio-cells = <0x2>; - gpio-controller; - }; - }; +/dts-v1/; +/plugin/; + +&fpga_region1 { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "soc_image2.rbf"; + partial-fpga-config; + + gpio@10040 { + compatible = "altr,pio-1.0"; + reg = <0x10040 0x20>; + clocks = <0x2>; + altr,ngpio = <0x4>; + #gpio-cells = <0x2>; + gpio-controller; }; }; diff --git a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt index 4284d293fa61..0acdfa6d62a4 100644 --- a/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt +++ b/Documentation/devicetree/bindings/fpga/xilinx-pr-decoupler.txt @@ -7,13 +7,24 @@ changes from passing through the bridge. The controller can also couple / enable the bridges which allows traffic to pass through the bridge normally. +Xilinx LogiCORE Dynamic Function eXchange(DFX) AXI shutdown manager +Softcore is compatible with the Xilinx LogiCORE pr-decoupler. + +The Dynamic Function eXchange AXI shutdown manager prevents AXI traffic +from passing through the bridge. The controller safely handles AXI4MM +and AXI4-Lite interfaces on a Reconfigurable Partition when it is +undergoing dynamic reconfiguration, preventing the system deadlock +that can occur if AXI transactions are interrupted by DFX + The Driver supports only MMIO handling. A PR region can have multiple PR Decouplers which can be handled independently or chained via decouple/ decouple_status signals. Required properties: - compatible : Should contain "xlnx,pr-decoupler-1.00" followed by - "xlnx,pr-decoupler" + "xlnx,pr-decoupler" or + "xlnx,dfx-axi-shutdown-manager-1.00" followed by + "xlnx,dfx-axi-shutdown-manager" - regs : base address and size for decoupler module - clocks : input clock to IP - clock-names : should contain "aclk" @@ -22,6 +33,7 @@ See Documentation/devicetree/bindings/fpga/fpga-region.txt and Documentation/devicetree/bindings/fpga/fpga-bridge.txt for generic bindings. Example: +Partial Reconfig Decoupler: fpga-bridge@100000450 { compatible = "xlnx,pr-decoupler-1.00", "xlnx-pr-decoupler"; @@ -30,3 +42,13 @@ Example: clock-names = "aclk"; bridge-enable = <0>; }; + +Dynamic Function eXchange AXI shutdown manager: + fpga-bridge@100000450 { + compatible = "xlnx,dfx-axi-shutdown-manager-1.00", + "xlnx,dfx-axi-shutdown-manager"; + regs = <0x10000045 0x10>; + clocks = <&clkc 15>; + clock-names = "aclk"; + bridge-enable = <0>; + }; diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml index 184492162e7e..894ba217ab32 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml +++ b/Documentation/devicetree/bindings/gpu/arm,mali-bifrost.yaml @@ -69,6 +69,8 @@ properties: where voltage is in V, frequency is in MHz. + dma-coherent: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt index 37f18d684f6a..4c5c3712970e 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt +++ b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt @@ -32,7 +32,7 @@ Optional node properties: - "#thermal-sensor-cells" Used to expose itself to thermal fw. Read more about iio bindings at - Documentation/devicetree/bindings/iio/iio-bindings.txt + https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/ Example: ncp15wb473@0 { diff --git a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml index ff99344788ab..fd040284561f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Bindings for GPIO bitbanged I2C maintainers: - - Wolfram Sang <wolfram@the-dreams.de> + - Wolfram Sang <wsa@kernel.org> allOf: - $ref: /schemas/i2c/i2c-controller.yaml# diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml index f23966b0d6c6..3592d49235e0 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-imx.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Freescale Inter IC (I2C) and High Speed Inter IC (HS-I2C) for i.MX maintainers: - - Wolfram Sang <wolfram@the-dreams.de> + - Oleksij Rempel <o.rempel@pengutronix.de> allOf: - $ref: /schemas/i2c/i2c-controller.yaml# diff --git a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt index 1cf6182f888c..3716589d6999 100644 --- a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt +++ b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt @@ -10,19 +10,19 @@ Required properties: - reg: I3C master registers Mandatory properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - #address-cells: shall be set to 1 - #size-cells: shall be set to 0 Optional properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - i2c-scl-hz - i3c-scl-hz I3C device connected on the bus follow the generic description (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details). +Documentation/devicetree/bindings/i3c/i3c.yaml for more details). Example: diff --git a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt index 5020eb71eb8d..07f35f36085d 100644 --- a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt +++ b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt @@ -9,19 +9,19 @@ Required properties: - reg: Offset and length of I3C master registers Mandatory properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - #address-cells: shall be set to 3 - #size-cells: shall be set to 0 Optional properties defined by the generic binding (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details): +Documentation/devicetree/bindings/i3c/i3c.yaml for more details): - i2c-scl-hz - i3c-scl-hz I3C device connected on the bus follow the generic description (see -Documentation/devicetree/bindings/i3c/i3c.txt for more details). +Documentation/devicetree/bindings/i3c/i3c.yaml for more details). Example: diff --git a/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml b/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml new file mode 100644 index 000000000000..911a1ae9c83f --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/bosch,bmi088.yaml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/accel/bosch,bmi088.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bosch BMI088 IMU accelerometer part + +maintainers: + - Mike Looijmans <mike.looijmans@topic.nl> + +description: | + Acceleration part of the IMU sensor with an SPI interface + Specifications about the sensor can be found at: + https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmi088-ds001.pdf + +properties: + compatible: + enum: + - bosch,bmi088-accel + + reg: + maxItems: 1 + + spi-max-frequency: true + + vdd-supply: true + + vddio-supply: true + + interrupts: + minItems: 1 + maxItems: 2 + description: | + Type should be either IRQ_TYPE_LEVEL_HIGH or IRQ_TYPE_LEVEL_LOW. + Two configurable interrupt lines exist. + + interrupt-names: + description: Specify which interrupt line is in use. + items: + enum: + - INT1 + - INT2 + minItems: 1 + maxItems: 2 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + bmi088-accel@1 { + compatible = "bosch,bmi088-accel"; + reg = <1>; + spi-max-frequency = <10000000>; + interrupt-parent = <&gpio6>; + interrupts = <19 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "INT2"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml index 9f414dbdae86..433a3fb55a2e 100644 --- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml @@ -14,8 +14,9 @@ description: > Industrial I/O subsystem bindings for ADC controller found in Ingenic JZ47xx SoCs. - ADC clients must use the format described in iio-bindings.txt, giving - a phandle and IIO specifier pair ("io-channels") to the ADC controller. + ADC clients must use the format described in + https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/iio-consumer.yaml, + giving a phandle and IIO specifier pair ("io-channels") to the ADC controller. properties: compatible: diff --git a/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml b/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml index 5b21a9fba5dd..b939f9652e3a 100644 --- a/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/mediatek,mt2701-auxadc.yaml @@ -34,6 +34,7 @@ properties: - items: - enum: - mediatek,mt8183-auxadc + - mediatek,mt8195-auxadc - mediatek,mt8516-auxadc - const: mediatek,mt8173-auxadc diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml new file mode 100644 index 000000000000..e0670e3fbb72 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads131e08.yaml @@ -0,0 +1,181 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,ads131e08.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments ADS131E0x 4-, 6- and 8-Channel ADCs + +maintainers: + - Tomislav Denis <tomislav.denis@avl.com> + +description: | + The ADS131E0x are a family of multichannel, simultaneous sampling, + 24-bit, delta-sigma, analog-to-digital converters (ADCs) with a + built-in programmable gain amplifier (PGA), internal reference + and an onboard oscillator. + The communication with ADC chip is via the SPI bus (mode 1). + + https://www.ti.com/lit/ds/symlink/ads131e08.pdf + +properties: + compatible: + enum: + - ti,ads131e04 + - ti,ads131e06 + - ti,ads131e08 + + reg: + maxItems: 1 + + spi-max-frequency: true + + spi-cpha: true + + clocks: + description: | + Device tree identifier to the clock source (2.048 MHz). + Note: clock source is selected using CLKSEL pin. + maxItems: 1 + + clock-names: + items: + - const: adc-clk + + interrupts: + description: | + IRQ line for the ADC data ready. + maxItems: 1 + + vref-supply: + description: | + Optional external voltage reference. If not supplied, internal voltage + reference is used. + + ti,vref-internal: + description: | + Select the internal voltage reference value. + 0: 2.4V + 1: 4.0V + If this field is left empty, 2.4V is selected. + Note: internal voltage reference is used only if vref-supply is not supplied. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +required: + - compatible + - reg + - spi-cpha + - clocks + - clock-names + - interrupts + +patternProperties: + "^channel@([0-7])$": + $ref: "adc.yaml" + type: object + description: | + Represents the external channels which are connected to the ADC. + + properties: + reg: + description: | + The channel number. + Up to 4 channels, numbered from 0 to 3 for ti,ads131e04. + Up to 6 channels, numbered from 0 to 5 for ti,ads131e06. + Up to 8 channels, numbered from 0 to 7 for ti,ads131e08. + items: + minimum: 0 + maximum: 7 + + ti,gain: + description: | + The PGA gain value for the channel. + If this field is left empty, PGA gain 1 is used. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8, 12] + default: 1 + + ti,mux: + description: | + Channel input selection(muliplexer). + 0: Normal input. + 1: Input shorted to (VREFP + VREFN) / 2 (for offset or noise measurements). + 3: MVDD (for supply measurement) + 4: Temperature sensor + If this field is left empty, normal input is selected. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 3, 4] + default: 0 + + required: + - reg + + additionalProperties: false + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "ti,ads131e08"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpha; + clocks = <&clk2048k>; + clock-names = "adc-clk"; + interrupt-parent = <&gpio5>; + interrupts = <28 IRQ_TYPE_EDGE_FALLING>; + vref-supply = <&adc_vref>; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + }; + + channel@1 { + reg = <1>; + }; + + channel@2 { + reg = <2>; + ti,gain = <2>; + }; + + channel@3 { + reg = <3>; + }; + + channel@4 { + reg = <4>; + }; + + channel@5 { + reg = <5>; + }; + + channel@6 { + reg = <6>; + }; + + channel@7 { + reg = <7>; + ti,mux = <4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml new file mode 100644 index 000000000000..2155d3f5666c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/cdc/adi,ad7150.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/cdc/adi,ad7150.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog device AD7150 and similar capacitance to digital convertors. + +maintainers: + - Jonathan Cameron <jic23@kernel.org> + +properties: + compatible: + enum: + - adi,ad7150 + - adi,ad7151 + - adi,ad7156 + + reg: + maxItems: 1 + + vdd-supply: true + + interrupts: true + +allOf: + - if: + properties: + compatible: + contains: + enum: + - adi,ad7150 + - adi,ad7156 + then: + properties: + interrupts: + minItems: 2 + maxItems: 2 + - if: + properties: + compatible: + contains: + const: adi,ad7151 + then: + properties: + interrupts: + minItems: 1 + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + cdc@48 { + compatible = "adi,ad7150"; + reg = <0x48>; + interrupts = <25 2>, <26 2>; + interrupt-parent = <&gpio>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml index 79fba1508e89..a7574210175a 100644 --- a/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16475.yaml @@ -71,15 +71,6 @@ properties: minimum: 0 maximum: 3 - adi,scaled-output-hz: - description: - This property must be present if the clock mode is scaled-sync through - clock-names property. In this mode, the input clock can have a range - of 1Hz to 128HZ which must be scaled to originate an allowable sample - rate. This property specifies that rate. - minimum: 1900 - maximum: 2100 - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml new file mode 100644 index 000000000000..099b4be927d4 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/google,cros-ec-mkbp-proximity.yaml @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/iio/proximity/google,cros-ec-mkbp-proximity.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ChromeOS EC MKBP Proximity Sensor + +maintainers: + - Stephen Boyd <swboyd@chromium.org> + - Benson Leung <bleung@chromium.org> + - Enric Balletbo i Serra <enric.balletbo@collabora.com> + +description: | + Google's ChromeOS EC sometimes has the ability to detect user proximity. + This is implemented on the EC as near/far logic and exposed to the OS + via an MKBP switch bit. + +properties: + compatible: + const: google,cros-ec-mkbp-proximity + + label: + description: Name for proximity sensor + +required: + - compatible + +additionalProperties: false + +examples: + - | + proximity { + compatible = "google,cros-ec-mkbp-proximity"; + label = "proximity-wifi-lte"; + }; diff --git a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml index db291a9390b7..7e98f47987dc 100644 --- a/Documentation/devicetree/bindings/iio/st,st-sensors.yaml +++ b/Documentation/devicetree/bindings/iio/st,st-sensors.yaml @@ -66,6 +66,7 @@ properties: - st,lis3mdl-magn - st,lis2mdl - st,lsm9ds1-magn + - st,iis2mdc # Pressure sensors - st,lps001wp-press - st,lps25h-press diff --git a/Documentation/devicetree/bindings/input/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml index 054406bbd22b..721878d5b7af 100644 --- a/Documentation/devicetree/bindings/input/adc-joystick.yaml +++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml @@ -24,7 +24,9 @@ properties: description: > List of phandle and IIO specifier pairs. Each pair defines one ADC channel to which a joystick axis is connected. - See Documentation/devicetree/bindings/iio/iio-bindings.txt for details. + See + https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/iio-consumer.yaml + for details. '#address-cells': const: 1 diff --git a/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.txt b/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.txt index 51456c0e9a27..af5223bb5bdd 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/resistive-adc-touch.txt @@ -5,7 +5,10 @@ Required properties: - compatible: must be "resistive-adc-touch" The device must be connected to an ADC device that provides channels for position measurement and optional pressure. -Refer to ../iio/iio-bindings.txt for details +Refer to +https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/iio-consumer.yaml +for details + - iio-channels: must have at least two channels connected to an ADC device. These should correspond to the channels exposed by the ADC device and should have the right index as the ADC device registers them. These channels diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml index 799e73cdb90b..cb6498108b78 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml @@ -71,6 +71,16 @@ properties: - qcom,sm8250-mmss-noc - qcom,sm8250-npu-noc - qcom,sm8250-system-noc + - qcom,sm8350-aggre1-noc + - qcom,sm8350-aggre2-noc + - qcom,sm8350-config-noc + - qcom,sm8350-dc-noc + - qcom,sm8350-gem-noc + - qcom,sm8350-lpass-ag-noc + - qcom,sm8350-mc-virt + - qcom,sm8350-mmss-noc + - qcom,sm8350-compute-noc + - qcom,sm8350-system-noc '#interconnect-cells': enum: [ 1, 2 ] diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml new file mode 100644 index 000000000000..29de7807df54 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml @@ -0,0 +1,147 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sdm660.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SDM660 Network-On-Chip interconnect + +maintainers: + - AngeloGioacchino Del Regno <kholk11@gmail.com> + +description: | + The Qualcomm SDM660 interconnect providers support adjusting the + bandwidth requirements between the various NoC fabrics. + +properties: + reg: + maxItems: 1 + + compatible: + enum: + - qcom,sdm660-a2noc + - qcom,sdm660-bimc + - qcom,sdm660-cnoc + - qcom,sdm660-gnoc + - qcom,sdm660-mnoc + - qcom,sdm660-snoc + + '#interconnect-cells': + const: 1 + + clocks: + minItems: 1 + maxItems: 3 + + clock-names: + minItems: 1 + maxItems: 3 + +required: + - compatible + - reg + - '#interconnect-cells' + - clock-names + - clocks + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,sdm660-mnoc + then: + properties: + clocks: + items: + - description: Bus Clock. + - description: Bus A Clock. + - description: CPU-NoC High-performance Bus Clock. + clock-names: + items: + - const: bus + - const: bus_a + - const: iface + + - if: + properties: + compatible: + contains: + enum: + - qcom,sdm660-a2noc + - qcom,sdm660-bimc + - qcom,sdm660-cnoc + - qcom,sdm660-gnoc + - qcom,sdm660-snoc + then: + properties: + clocks: + items: + - description: Bus Clock. + - description: Bus A Clock. + clock-names: + items: + - const: bus + - const: bus_a + +examples: + - | + #include <dt-bindings/clock/qcom,rpmcc.h> + #include <dt-bindings/clock/qcom,mmcc-sdm660.h> + + bimc: interconnect@1008000 { + compatible = "qcom,sdm660-bimc"; + reg = <0x01008000 0x78000>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_BIMC_CLK>, + <&rpmcc RPM_SMD_BIMC_A_CLK>; + }; + + cnoc: interconnect@1500000 { + compatible = "qcom,sdm660-cnoc"; + reg = <0x01500000 0x10000>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_CNOC_CLK>, + <&rpmcc RPM_SMD_CNOC_A_CLK>; + }; + + snoc: interconnect@1626000 { + compatible = "qcom,sdm660-snoc"; + reg = <0x01626000 0x7090>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_SNOC_CLK>, + <&rpmcc RPM_SMD_SNOC_A_CLK>; + }; + + a2noc: interconnect@1704000 { + compatible = "qcom,sdm660-a2noc"; + reg = <0x01704000 0xc100>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&rpmcc RPM_SMD_AGGR2_NOC_CLK>, + <&rpmcc RPM_SMD_AGGR2_NOC_A_CLK>; + }; + + mnoc: interconnect@1745000 { + compatible = "qcom,sdm660-mnoc"; + reg = <0x01745000 0xa010>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a", "iface"; + clocks = <&rpmcc RPM_SMD_MMSSNOC_AXI_CLK>, + <&rpmcc RPM_SMD_MMSSNOC_AXI_CLK_A>, + <&mmcc AHB_CLK_SRC>; + }; + + gnoc: interconnect@17900000 { + compatible = "qcom,sdm660-gnoc"; + reg = <0x17900000 0xe000>; + #interconnect-cells = <1>; + clock-names = "bus", "bus_a"; + clocks = <&xo_board>, <&xo_board>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml new file mode 100644 index 000000000000..cf6c091a07b1 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/apple,aic.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/apple,aic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Apple Interrupt Controller + +maintainers: + - Hector Martin <marcan@marcan.st> + +description: | + The Apple Interrupt Controller is a simple interrupt controller present on + Apple ARM SoC platforms, including various iPhone and iPad devices and the + "Apple Silicon" Macs. + + It provides the following features: + + - Level-triggered hardware IRQs wired to SoC blocks + - Single mask bit per IRQ + - Per-IRQ affinity setting + - Automatic masking on event delivery (auto-ack) + - Software triggering (ORed with hw line) + - 2 per-CPU IPIs (meant as "self" and "other", but they are interchangeable + if not symmetric) + - Automatic prioritization (single event/ack register per CPU, lower IRQs = + higher priority) + - Automatic masking on ack + - Default "this CPU" register view and explicit per-CPU views + + This device also represents the FIQ interrupt sources on platforms using AIC, + which do not go through a discrete interrupt controller. + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + compatible: + items: + - const: apple,t8103-aic + - const: apple,aic + + interrupt-controller: true + + '#interrupt-cells': + const: 3 + description: | + The 1st cell contains the interrupt type: + - 0: Hardware IRQ + - 1: FIQ + + The 2nd cell contains the interrupt number. + - HW IRQs: interrupt number + - FIQs: + - 0: physical HV timer + - 1: virtual HV timer + - 2: physical guest timer + - 3: virtual guest timer + + The 3rd cell contains the interrupt flags. This is normally + IRQ_TYPE_LEVEL_HIGH (4). + + reg: + description: | + Specifies base physical address and size of the AIC registers. + maxItems: 1 + +required: + - compatible + - '#interrupt-cells' + - interrupt-controller + - reg + +additionalProperties: false + +examples: + - | + soc { + #address-cells = <2>; + #size-cells = <2>; + + aic: interrupt-controller@23b100000 { + compatible = "apple,t8103-aic", "apple,aic"; + #interrupt-cells = <3>; + interrupt-controller; + reg = <0x2 0x3b100000 0x0 0x8000>; + }; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml b/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml new file mode 100644 index 000000000000..df5d8d1ead70 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/idt,32434-pic.yaml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/idt,32434-pic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: IDT 79RC32434 Interrupt Controller Device Tree Bindings + +maintainers: + - Thomas Bogendoerfer <tsbogend@alpha.franken.de> + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + +properties: + "#interrupt-cells": + const: 1 + + compatible: + const: idt,32434-pic + + reg: + maxItems: 1 + + interrupt-controller: true + +required: + - "#interrupt-cells" + - compatible + - reg + - interrupt-controller + +additionalProperties: false + +examples: + - | + idtpic3: interrupt-controller@3800c { + compatible = "idt,32434-pic"; + reg = <0x3800c 0x0c>; + + interrupt-controller; + #interrupt-cells = <1>; + + interrupt-parent = <&cpuintc>; + interrupts = <3>; + }; + +... diff --git a/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml b/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml index 0a046be8d1cd..0358a7739c8e 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/ingenic,intc.yaml @@ -23,6 +23,7 @@ properties: - enum: - ingenic,jz4775-intc - ingenic,jz4770-intc + - ingenic,jz4760b-intc - const: ingenic,jz4760-intc - items: - const: ingenic,x1000-intc diff --git a/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml b/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml new file mode 100644 index 000000000000..9ce6804bdb99 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/nuvoton,wpcm450-aic.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/nuvoton,wpcm450-aic.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton WPCM450 Advanced Interrupt Controller bindings + +maintainers: + - Jonathan Neuschäfer <j.neuschaefer@gmx.net> + +properties: + '#interrupt-cells': + const: 2 + + compatible: + const: nuvoton,wpcm450-aic + + interrupt-controller: true + + reg: + maxItems: 1 + +additionalProperties: false + +required: + - '#interrupt-cells' + - compatible + - reg + - interrupt-controller + +examples: + - | + aic: interrupt-controller@b8002000 { + compatible = "nuvoton,wpcm450-aic"; + reg = <0xb8002000 0x1000>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt index e9afb48182c7..98d89e53013d 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.txt @@ -19,6 +19,7 @@ Properties: Value type: <string> Definition: Should contain "qcom,<soc>-pdc" and "qcom,pdc" - "qcom,sc7180-pdc": For SC7180 + - "qcom,sc7280-pdc": For SC7280 - "qcom,sdm845-pdc": For SDM845 - "qcom,sdm8250-pdc": For SM8250 - "qcom,sdm8350-pdc": For SM8350 diff --git a/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml index fe7fa25877fd..c7ed2871da06 100644 --- a/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml +++ b/Documentation/devicetree/bindings/leds/cznic,turris-omnia-leds.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: CZ.NIC's Turris Omnia LEDs driver maintainers: - - Marek Behún <marek.behun@nic.cz> + - Marek Behún <kabel@kernel.org> description: This module adds support for the RGB LEDs found on the front panel of the diff --git a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml index 15cef82cd356..1a3dff277e2b 100644 --- a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml +++ b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml @@ -34,12 +34,15 @@ properties: - fsl,imx8mm-mu - fsl,imx8mn-mu - fsl,imx8mp-mu + - fsl,imx8qm-mu - fsl,imx8qxp-mu - const: fsl,imx6sx-mu - description: To communicate with i.MX8 SCU with fast IPC items: - const: fsl,imx8-mu-scu - - const: fsl,imx8qxp-mu + - enum: + - fsl,imx8qm-mu + - fsl,imx8qxp-mu - const: fsl,imx6sx-mu reg: diff --git a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml index 5fa19d4aeaf3..6d8395d6bca0 100644 --- a/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml +++ b/Documentation/devicetree/bindings/media/allwinner,sun4i-a10-ir.yaml @@ -20,16 +20,12 @@ properties: - const: allwinner,sun5i-a13-ir - const: allwinner,sun6i-a31-ir - items: - - const: allwinner,sun8i-a83t-ir - - const: allwinner,sun6i-a31-ir - - items: - - const: allwinner,sun8i-r40-ir - - const: allwinner,sun6i-a31-ir - - items: - - const: allwinner,sun50i-a64-ir - - const: allwinner,sun6i-a31-ir - - items: - - const: allwinner,sun50i-h6-ir + - enum: + - allwinner,sun8i-a83t-ir + - allwinner,sun8i-r40-ir + - allwinner,sun50i-a64-ir + - allwinner,sun50i-h6-ir + - allwinner,sun50i-h616-ir - const: allwinner,sun6i-a31-ir reg: diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt index cf60c5acc0e4..39c1028b2dfb 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt @@ -19,7 +19,7 @@ Required properties: Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml for details. - iommus: should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. Example: diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt index acfb50375b8a..5e53c6ab52d0 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.txt @@ -17,7 +17,7 @@ Required properties: Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml for details. - iommus: should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. Example: diff --git a/Documentation/devicetree/bindings/media/mediatek-mdp.txt b/Documentation/devicetree/bindings/media/mediatek-mdp.txt index f4798d04e925..caa24943da33 100644 --- a/Documentation/devicetree/bindings/media/mediatek-mdp.txt +++ b/Documentation/devicetree/bindings/media/mediatek-mdp.txt @@ -25,7 +25,7 @@ Required properties (DMA function blocks, child node): "mediatek,mt8173-mdp-wdma" "mediatek,mt8173-mdp-wrot" - iommus: should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. - mediatek,larb: must contain the local arbiters in the current Socs, see Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.yaml diff --git a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt index 8217424fd4bd..06db6837cefd 100644 --- a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt +++ b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt @@ -4,7 +4,9 @@ Mediatek Video Codec is the video codec hw present in Mediatek SoCs which supports high resolution encoding and decoding functionalities. Required properties: -- compatible : "mediatek,mt8173-vcodec-enc" for MT8173 encoder +- compatible : must be one of the following string: + "mediatek,mt8173-vcodec-enc-vp8" for mt8173 vp8 encoder. + "mediatek,mt8173-vcodec-enc" for mt8173 avc encoder. "mediatek,mt8183-vcodec-enc" for MT8183 encoder. "mediatek,mt8173-vcodec-dec" for MT8173 decoder. - reg : Physical base address of the video codec registers and length of @@ -13,12 +15,12 @@ Required properties: - mediatek,larb : must contain the local arbiters in the current Socs. - clocks : list of clock specifiers, corresponding to entries in the clock-names property. -- clock-names: encoder must contain "venc_sel_src", "venc_sel",, - "venc_lt_sel_src", "venc_lt_sel", decoder must contain "vcodecpll", - "univpll_d2", "clk_cci400_sel", "vdec_sel", "vdecpll", "vencpll", - "venc_lt_sel", "vdec_bus_clk_src". +- clock-names: avc encoder must contain "venc_sel", vp8 encoder must + contain "venc_lt_sel", decoder must contain "vcodecpll", "univpll_d2", + "clk_cci400_sel", "vdec_sel", "vdecpll", "vencpll", "venc_lt_sel", + "vdec_bus_clk_src". - iommus : should point to the respective IOMMU block with master port as - argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. One of the two following nodes: - mediatek,vpu : the node of the video processor unit, if using VPU. @@ -80,14 +82,10 @@ vcodec_dec: vcodec@16000000 { assigned-clock-rates = <0>, <0>, <0>, <1482000000>, <800000000>; }; - vcodec_enc: vcodec@18002000 { +vcodec_enc_avc: vcodec@18002000 { compatible = "mediatek,mt8173-vcodec-enc"; - reg = <0 0x18002000 0 0x1000>, /*VENC_SYS*/ - <0 0x19002000 0 0x1000>; /*VENC_LT_SYS*/ - interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>, - <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>; - mediatek,larb = <&larb3>, - <&larb5>; + reg = <0 0x18002000 0 0x1000>; + interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>; iommus = <&iommu M4U_PORT_VENC_RCPU>, <&iommu M4U_PORT_VENC_REC>, <&iommu M4U_PORT_VENC_BSDMA>, @@ -98,8 +96,20 @@ vcodec_dec: vcodec@16000000 { <&iommu M4U_PORT_VENC_REF_LUMA>, <&iommu M4U_PORT_VENC_REF_CHROMA>, <&iommu M4U_PORT_VENC_NBM_RDMA>, - <&iommu M4U_PORT_VENC_NBM_WDMA>, - <&iommu M4U_PORT_VENC_RCPU_SET2>, + <&iommu M4U_PORT_VENC_NBM_WDMA>; + mediatek,larb = <&larb3>; + mediatek,vpu = <&vpu>; + clocks = <&topckgen CLK_TOP_VENC_SEL>; + clock-names = "venc_sel"; + assigned-clocks = <&topckgen CLK_TOP_VENC_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL>; + }; + +vcodec_enc_vp8: vcodec@19002000 { + compatible = "mediatek,mt8173-vcodec-enc-vp8"; + reg = <0 0x19002000 0 0x1000>; /* VENC_LT_SYS */ + interrupts = <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>; + iommus = <&iommu M4U_PORT_VENC_RCPU_SET2>, <&iommu M4U_PORT_VENC_REC_FRM_SET2>, <&iommu M4U_PORT_VENC_BSDMA_SET2>, <&iommu M4U_PORT_VENC_SV_COMA_SET2>, @@ -108,17 +118,10 @@ vcodec_dec: vcodec@16000000 { <&iommu M4U_PORT_VENC_CUR_CHROMA_SET2>, <&iommu M4U_PORT_VENC_REF_LUMA_SET2>, <&iommu M4U_PORT_VENC_REC_CHROMA_SET2>; + mediatek,larb = <&larb5>; mediatek,vpu = <&vpu>; - clocks = <&topckgen CLK_TOP_VENCPLL_D2>, - <&topckgen CLK_TOP_VENC_SEL>, - <&topckgen CLK_TOP_UNIVPLL1_D2>, - <&topckgen CLK_TOP_VENC_LT_SEL>; - clock-names = "venc_sel_src", - "venc_sel", - "venc_lt_sel_src", - "venc_lt_sel"; - assigned-clocks = <&topckgen CLK_TOP_VENC_SEL>, - <&topckgen CLK_TOP_VENC_LT_SEL>; - assigned-clock-parents = <&topckgen CLK_TOP_VENCPLL_D2>, - <&topckgen CLK_TOP_UNIVPLL1_D2>; + clocks = <&topckgen CLK_TOP_VENC_LT_SEL>; + clock-names = "venc_lt_sel"; + assigned-clocks = <&topckgen CLK_TOP_VENC_LT_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_VCODECPLL_370P5>; }; diff --git a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml index be47a7b62ca9..d8ed480482b9 100644 --- a/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml +++ b/Documentation/devicetree/bindings/media/nxp,imx7-mipi-csi2.yaml @@ -4,14 +4,19 @@ $id: http://devicetree.org/schemas/media/nxp,imx7-mipi-csi2.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: NXP i.MX7 Mipi CSI2 +title: NXP i.MX7 MIPI CSI-2 receiver maintainers: - Rui Miguel Silva <rmfrfs@gmail.com> -description: | - This is the device node for the MIPI CSI-2 receiver core in i.MX7 soc. It is - compatible with previous version of samsung d-phy. +description: |- + The NXP i.MX7 SoC family includes a MIPI CSI-2 receiver IP core, documented + as "CSIS V3.3". The IP core seems to originate from Samsung, and may be + compatible with some of the Exynos4 ad S5P SoCs. + + While the CSI-2 receiver is separate from the MIPI D-PHY IP core, the PHY is + completely wrapped by the CSIS and doesn't expose a control interface of its + own. This binding thus covers both IP cores. properties: compatible: @@ -24,8 +29,10 @@ properties: maxItems: 1 clocks: - minItems: 3 - maxItems: 3 + items: + - description: The peripheral clock (a.k.a. APB clock) + - description: The external clock (optionally used as the pixel clock) + - description: The MIPI D-PHY clock clock-names: items: @@ -37,26 +44,16 @@ properties: maxItems: 1 phy-supply: - description: - Phandle to a regulator that provides power to the PHY. This - regulator will be managed during the PHY power on/off sequence. + description: The MIPI D-PHY digital power supply resets: - maxItems: 1 - - reset-names: - const: mrst + items: + - description: MIPI D-PHY slave reset clock-frequency: - description: - The IP main (system bus) clock frequency in Hertz + description: The desired external clock ("wrap") frequency, in Hz default: 166000000 - fsl,csis-hs-settle: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Differential receiver (HS-RX) settle time - ports: $ref: /schemas/graph.yaml#/properties/ports @@ -98,7 +95,6 @@ required: - power-domains - phy-supply - resets - - reset-names - ports additionalProperties: false @@ -111,43 +107,41 @@ examples: #include <dt-bindings/reset/imx7-reset.h> mipi_csi: mipi-csi@30750000 { - compatible = "fsl,imx7-mipi-csi2"; - reg = <0x30750000 0x10000>; - interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; - - clocks = <&clks IMX7D_IPG_ROOT_CLK>, - <&clks IMX7D_MIPI_CSI_ROOT_CLK>, - <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; - clock-names = "pclk", "wrap", "phy"; - clock-frequency = <166000000>; - - power-domains = <&pgc_mipi_phy>; - phy-supply = <®_1p0d>; - resets = <&src IMX7_RESET_MIPI_PHY_MRST>; - reset-names = "mrst"; - fsl,csis-hs-settle = <3>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - - mipi_from_sensor: endpoint { - remote-endpoint = <&ov2680_to_mipi>; - data-lanes = <1>; - }; - }; - - port@1 { - reg = <1>; - - mipi_vc0_to_csi_mux: endpoint { - remote-endpoint = <&csi_mux_from_mipi_vc0>; - }; - }; + compatible = "fsl,imx7-mipi-csi2"; + reg = <0x30750000 0x10000>; + interrupts = <GIC_SPI 25 IRQ_TYPE_LEVEL_HIGH>; + + clocks = <&clks IMX7D_IPG_ROOT_CLK>, + <&clks IMX7D_MIPI_CSI_ROOT_CLK>, + <&clks IMX7D_MIPI_DPHY_ROOT_CLK>; + clock-names = "pclk", "wrap", "phy"; + clock-frequency = <166000000>; + + power-domains = <&pgc_mipi_phy>; + phy-supply = <®_1p0d>; + resets = <&src IMX7_RESET_MIPI_PHY_MRST>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + mipi_from_sensor: endpoint { + remote-endpoint = <&ov2680_to_mipi>; + data-lanes = <1>; + }; + }; + + port@1 { + reg = <1>; + + mipi_vc0_to_csi_mux: endpoint { + remote-endpoint = <&csi_mux_from_mipi_vc0>; + }; }; + }; }; ... diff --git a/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml new file mode 100644 index 000000000000..5d13cbb5251b --- /dev/null +++ b/Documentation/devicetree/bindings/media/nxp,imx8-jpeg.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nxp,imx8-jpeg.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: i.MX8QXP/QM JPEG decoder/encoder Device Tree Bindings + +maintainers: + - Mirela Rabulea <mirela.rabulea@nxp.com> + +description: |- + The JPEG decoder/encoder present in iMX8QXP and iMX8QM SoCs is an + ISO/IEC 10918-1 JPEG standard compliant decoder/encoder, for Baseline + and Extended Sequential DCT modes. + +properties: + compatible: + items: + - enum: + # JPEG decoder + - nxp,imx8qxp-jpgdec + # JPEG encoder + - nxp,imx8qxp-jpgenc + + reg: + maxItems: 1 + + interrupts: + description: | + There are 4 slots available in the IP, which the driver may use + If a certain slot is used, it should have an associated interrupt + The interrupt with index i is assumed to be for slot i + minItems: 1 # At least one slot is needed by the driver + maxItems: 4 # The IP has 4 slots available for use + + power-domains: + description: + List of phandle and PM domain specifier as documented in + Documentation/devicetree/bindings/power/power_domain.txt + minItems: 2 # Wrapper and 1 slot + maxItems: 5 # Wrapper and 4 slots + +required: + - compatible + - reg + - interrupts + - power-domains + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/firmware/imx/rsrc.h> + + jpegdec: jpegdec@58400000 { + compatible = "nxp,imx8qxp-jpgdec"; + reg = <0x58400000 0x00050000 >; + interrupts = <GIC_SPI 309 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 310 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 311 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 312 IRQ_TYPE_LEVEL_HIGH>; + power-domains = <&pd IMX_SC_R_MJPEG_DEC_MP>, + <&pd IMX_SC_R_MJPEG_DEC_S0>, + <&pd IMX_SC_R_MJPEG_DEC_S1>, + <&pd IMX_SC_R_MJPEG_DEC_S2>, + <&pd IMX_SC_R_MJPEG_DEC_S3>; + }; + + jpegenc: jpegenc@58450000 { + compatible = "nxp,imx8qxp-jpgenc"; + reg = <0x58450000 0x00050000 >; + interrupts = <GIC_SPI 305 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 306 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 307 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 308 IRQ_TYPE_LEVEL_HIGH>; + power-domains = <&pd IMX_SC_R_MJPEG_ENC_MP>, + <&pd IMX_SC_R_MJPEG_ENC_S0>, + <&pd IMX_SC_R_MJPEG_ENC_S1>, + <&pd IMX_SC_R_MJPEG_ENC_S2>, + <&pd IMX_SC_R_MJPEG_ENC_S3>; + }; +... diff --git a/Documentation/devicetree/bindings/media/qcom,camss.txt b/Documentation/devicetree/bindings/media/qcom,camss.txt deleted file mode 100644 index 498234629e21..000000000000 --- a/Documentation/devicetree/bindings/media/qcom,camss.txt +++ /dev/null @@ -1,236 +0,0 @@ -Qualcomm Camera Subsystem - -* Properties - -- compatible: - Usage: required - Value type: <stringlist> - Definition: Should contain one of: - - "qcom,msm8916-camss" - - "qcom,msm8996-camss" - - "qcom,sdm660-camss" -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: Register ranges as listed in the reg-names property. -- reg-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the following entries: - - "csiphy0" - - "csiphy0_clk_mux" - - "csiphy1" - - "csiphy1_clk_mux" - - "csiphy2" (8996 only) - - "csiphy2_clk_mux" (8996 only) - - "csid0" - - "csid1" - - "csid2" (8996 only) - - "csid3" (8996 only) - - "ispif" - - "csi_clk_mux" - - "vfe0" - - "vfe1" (8996 only) -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: Interrupts as listed in the interrupt-names property. -- interrupt-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the following entries: - - "csiphy0" - - "csiphy1" - - "csiphy2" (8996 only) - - "csid0" - - "csid1" - - "csid2" (8996 only) - - "csid3" (8996 only) - - "ispif" - - "vfe0" - - "vfe1" (8996 only) -- power-domains: - Usage: required - Value type: <prop-encoded-array> - Definition: A phandle and power domain specifier pairs to the - power domain which is responsible for collapsing - and restoring power to the peripheral. -- clocks: - Usage: required - Value type: <prop-encoded-array> - Definition: A list of phandle and clock specifier pairs as listed - in clock-names property. -- clock-names: - Usage: required - Value type: <stringlist> - Definition: Should contain the following entries: - - "top_ahb" - - "throttle_axi" (660 only) - - "ispif_ahb" - - "csiphy0_timer" - - "csiphy1_timer" - - "csiphy2_timer" (8996 only) - - "csiphy_ahb2crif" (660 only) - - "csi0_ahb" - - "csi0" - - "csi0_phy" - - "csi0_pix" - - "csi0_rdi" - - "cphy_csid0" (660 only) - - "csi1_ahb" - - "csi1" - - "csi1_phy" - - "csi1_pix" - - "csi1_rdi" - - "cphy_csid1" (660 only) - - "csi2_ahb" (8996 only) - - "csi2" (8996 only) - - "csi2_phy" (8996 only) - - "csi2_pix" (8996 only) - - "csi2_rdi" (8996 only) - - "cphy_csid2" (660 only) - - "csi3_ahb" (8996 only) - - "csi3" (8996 only) - - "csi3_phy" (8996 only) - - "csi3_pix" (8996 only) - - "csi3_rdi" (8996 only) - - "cphy_csid3" (660 only) - - "ahb" - - "vfe0" - - "csi_vfe0" - - "vfe0_ahb", (8996 only) - - "vfe0_stream", (8996 only) - - "vfe1", (8996 only) - - "csi_vfe1", (8996 only) - - "vfe1_ahb", (8996 only) - - "vfe1_stream", (8996 only) - - "vfe_ahb" - - "vfe_axi" -- vdda-supply: - Usage: required - Value type: <phandle> - Definition: A phandle to voltage supply for CSI2. -- iommus: - Usage: required - Value type: <prop-encoded-array> - Definition: A list of phandle and IOMMU specifier pairs. - -* Nodes - -- ports: - Usage: required - Definition: As described in video-interfaces.txt in same directory. - Properties: - - reg: - Usage: required - Value type: <u32> - Definition: Selects CSI2 PHY interface - PHY0, PHY1 - or PHY2 (8996 only) - Endpoint node properties: - - clock-lanes: - Usage: required - Value type: <u32> - Definition: The physical clock lane index. On 8916 - the value must always be <1> as the physical - clock lane is lane 1. On 8996 the value must - always be <7> as the hardware supports D-PHY - and C-PHY, indexes are in a common set and - D-PHY physical clock lane is labeled as 7. - - data-lanes: - Usage: required - Value type: <prop-encoded-array> - Definition: An array of physical data lanes indexes. - Position of an entry determines the logical - lane number, while the value of an entry - indicates physical lane index. Lane swapping - is supported. Physical lane indexes for - 8916: 0, 2, 3, 4; for 8996: 0, 1, 2, 3. - -* An Example - - camss: camss@1b00000 { - compatible = "qcom,msm8916-camss"; - reg = <0x1b0ac00 0x200>, - <0x1b00030 0x4>, - <0x1b0b000 0x200>, - <0x1b00038 0x4>, - <0x1b08000 0x100>, - <0x1b08400 0x100>, - <0x1b0a000 0x500>, - <0x1b00020 0x10>, - <0x1b10000 0x1000>; - reg-names = "csiphy0", - "csiphy0_clk_mux", - "csiphy1", - "csiphy1_clk_mux", - "csid0", - "csid1", - "ispif", - "csi_clk_mux", - "vfe0"; - interrupts = <GIC_SPI 78 0>, - <GIC_SPI 79 0>, - <GIC_SPI 51 0>, - <GIC_SPI 52 0>, - <GIC_SPI 55 0>, - <GIC_SPI 57 0>; - interrupt-names = "csiphy0", - "csiphy1", - "csid0", - "csid1", - "ispif", - "vfe0"; - power-domains = <&gcc VFE_GDSC>; - clocks = <&gcc GCC_CAMSS_TOP_AHB_CLK>, - <&gcc GCC_CAMSS_ISPIF_AHB_CLK>, - <&gcc GCC_CAMSS_CSI0PHYTIMER_CLK>, - <&gcc GCC_CAMSS_CSI1PHYTIMER_CLK>, - <&gcc GCC_CAMSS_CSI0_AHB_CLK>, - <&gcc GCC_CAMSS_CSI0_CLK>, - <&gcc GCC_CAMSS_CSI0PHY_CLK>, - <&gcc GCC_CAMSS_CSI0PIX_CLK>, - <&gcc GCC_CAMSS_CSI0RDI_CLK>, - <&gcc GCC_CAMSS_CSI1_AHB_CLK>, - <&gcc GCC_CAMSS_CSI1_CLK>, - <&gcc GCC_CAMSS_CSI1PHY_CLK>, - <&gcc GCC_CAMSS_CSI1PIX_CLK>, - <&gcc GCC_CAMSS_CSI1RDI_CLK>, - <&gcc GCC_CAMSS_AHB_CLK>, - <&gcc GCC_CAMSS_VFE0_CLK>, - <&gcc GCC_CAMSS_CSI_VFE0_CLK>, - <&gcc GCC_CAMSS_VFE_AHB_CLK>, - <&gcc GCC_CAMSS_VFE_AXI_CLK>; - clock-names = "top_ahb", - "ispif_ahb", - "csiphy0_timer", - "csiphy1_timer", - "csi0_ahb", - "csi0", - "csi0_phy", - "csi0_pix", - "csi0_rdi", - "csi1_ahb", - "csi1", - "csi1_phy", - "csi1_pix", - "csi1_rdi", - "ahb", - "vfe0", - "csi_vfe0", - "vfe_ahb", - "vfe_axi"; - vdda-supply = <&pm8916_l2>; - iommus = <&apps_iommu 3>; - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - csiphy0_ep: endpoint { - clock-lanes = <1>; - data-lanes = <0 2>; - remote-endpoint = <&ov5645_ep>; - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml new file mode 100644 index 000000000000..304908072d72 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,msm8916-camss.yaml @@ -0,0 +1,256 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,msm8916-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + - Todor Tomov <todor.too@gmail.com> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,msm8916-camss + + clocks: + minItems: 19 + maxItems: 19 + + clock-names: + items: + - const: top_ahb + - const: ispif_ahb + - const: csiphy0_timer + - const: csiphy1_timer + - const: csi0_ahb + - const: csi0 + - const: csi0_phy + - const: csi0_pix + - const: csi0_rdi + - const: csi1_ahb + - const: csi1 + - const: csi1_phy + - const: csi1_pix + - const: csi1_rdi + - const: ahb + - const: vfe0 + - const: csi_vfe0 + - const: vfe_ahb + - const: vfe_axi + + interrupts: + minItems: 6 + maxItems: 6 + + interrupt-names: + items: + - const: csiphy0 + - const: csiphy1 + - const: csid0 + - const: csid1 + - const: ispif + - const: vfe0 + + iommus: + maxItems: 1 + + power-domains: + items: + - description: VFE GDSC - Video Front End, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 1 + + data-lanes: + description: + An array of physical data lanes indexes. + Position of an entry determines the logical + lane number, while the value of an entry + indicates physical lane index. Lane swapping + is supported. Physical lane indexes; + 0, 2, 3, 4. + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 9 + maxItems: 9 + + reg-names: + items: + - const: csiphy0 + - const: csiphy0_clk_mux + - const: csiphy1 + - const: csiphy1_clk_mux + - const: csid0 + - const: csid1 + - const: ispif + - const: csi_clk_mux + - const: vfe0 + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-msm8916.h> + + camss: camss@1b00000 { + compatible = "qcom,msm8916-camss"; + + clocks = <&gcc GCC_CAMSS_TOP_AHB_CLK>, + <&gcc GCC_CAMSS_ISPIF_AHB_CLK>, + <&gcc GCC_CAMSS_CSI0PHYTIMER_CLK>, + <&gcc GCC_CAMSS_CSI1PHYTIMER_CLK>, + <&gcc GCC_CAMSS_CSI0_AHB_CLK>, + <&gcc GCC_CAMSS_CSI0_CLK>, + <&gcc GCC_CAMSS_CSI0PHY_CLK>, + <&gcc GCC_CAMSS_CSI0PIX_CLK>, + <&gcc GCC_CAMSS_CSI0RDI_CLK>, + <&gcc GCC_CAMSS_CSI1_AHB_CLK>, + <&gcc GCC_CAMSS_CSI1_CLK>, + <&gcc GCC_CAMSS_CSI1PHY_CLK>, + <&gcc GCC_CAMSS_CSI1PIX_CLK>, + <&gcc GCC_CAMSS_CSI1RDI_CLK>, + <&gcc GCC_CAMSS_AHB_CLK>, + <&gcc GCC_CAMSS_VFE0_CLK>, + <&gcc GCC_CAMSS_CSI_VFE0_CLK>, + <&gcc GCC_CAMSS_VFE_AHB_CLK>, + <&gcc GCC_CAMSS_VFE_AXI_CLK>; + + clock-names = "top_ahb", + "ispif_ahb", + "csiphy0_timer", + "csiphy1_timer", + "csi0_ahb", + "csi0", + "csi0_phy", + "csi0_pix", + "csi0_rdi", + "csi1_ahb", + "csi1", + "csi1_phy", + "csi1_pix", + "csi1_rdi", + "ahb", + "vfe0", + "csi_vfe0", + "vfe_ahb", + "vfe_axi"; + + interrupts = <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 51 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 52 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 55 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 57 IRQ_TYPE_EDGE_RISING>; + + interrupt-names = "csiphy0", + "csiphy1", + "csid0", + "csid1", + "ispif", + "vfe0"; + + iommus = <&apps_iommu 3>; + + power-domains = <&gcc VFE_GDSC>; + + reg = <0x01b0ac00 0x200>, + <0x01b00030 0x4>, + <0x01b0b000 0x200>, + <0x01b00038 0x4>, + <0x01b08000 0x100>, + <0x01b08400 0x100>, + <0x01b0a000 0x500>, + <0x01b00020 0x10>, + <0x01b10000 0x1000>; + + reg-names = "csiphy0", + "csiphy0_clk_mux", + "csiphy1", + "csiphy1_clk_mux", + "csid0", + "csid1", + "ispif", + "csi_clk_mux", + "vfe0"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + + }; diff --git a/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml b/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml new file mode 100644 index 000000000000..38be41e932f0 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,msm8996-camss.yaml @@ -0,0 +1,387 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,msm8996-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + - Todor Tomov <todor.too@gmail.com> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,msm8996-camss + + clocks: + minItems: 36 + maxItems: 36 + + clock-names: + items: + - const: top_ahb + - const: ispif_ahb + - const: csiphy0_timer + - const: csiphy1_timer + - const: csiphy2_timer + - const: csi0_ahb + - const: csi0 + - const: csi0_phy + - const: csi0_pix + - const: csi0_rdi + - const: csi1_ahb + - const: csi1 + - const: csi1_phy + - const: csi1_pix + - const: csi1_rdi + - const: csi2_ahb + - const: csi2 + - const: csi2_phy + - const: csi2_pix + - const: csi2_rdi + - const: csi3_ahb + - const: csi3 + - const: csi3_phy + - const: csi3_pix + - const: csi3_rdi + - const: ahb + - const: vfe0 + - const: csi_vfe0 + - const: vfe0_ahb + - const: vfe0_stream + - const: vfe1 + - const: csi_vfe1 + - const: vfe1_ahb + - const: vfe1_stream + - const: vfe_ahb + - const: vfe_axi + + interrupts: + minItems: 10 + maxItems: 10 + + interrupt-names: + items: + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: ispif + - const: vfe0 + - const: vfe1 + + iommus: + maxItems: 4 + + power-domains: + items: + - description: VFE0 GDSC - Video Front End, Global Distributed Switch Controller. + - description: VFE1 GDSC - Video Front End, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + description: + An array of physical data lanes indexes. + Position of an entry determines the logical + lane number, while the value of an entry + indicates physical lane index. Lane swapping + is supported. Physical lane indexes are; + 0, 1, 2, 3 + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@3: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 14 + maxItems: 14 + + reg-names: + items: + - const: csiphy0 + - const: csiphy0_clk_mux + - const: csiphy1 + - const: csiphy1_clk_mux + - const: csiphy2 + - const: csiphy2_clk_mux + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: ispif + - const: csi_clk_mux + - const: vfe0 + - const: vfe1 + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-msm8996.h> + #include <dt-bindings/clock/qcom,mmcc-msm8996.h> + + camss: camss@a00000 { + compatible = "qcom,msm8996-camss"; + + clocks = <&mmcc CAMSS_TOP_AHB_CLK>, + <&mmcc CAMSS_ISPIF_AHB_CLK>, + <&mmcc CAMSS_CSI0PHYTIMER_CLK>, + <&mmcc CAMSS_CSI1PHYTIMER_CLK>, + <&mmcc CAMSS_CSI2PHYTIMER_CLK>, + <&mmcc CAMSS_CSI0_AHB_CLK>, + <&mmcc CAMSS_CSI0_CLK>, + <&mmcc CAMSS_CSI0PHY_CLK>, + <&mmcc CAMSS_CSI0PIX_CLK>, + <&mmcc CAMSS_CSI0RDI_CLK>, + <&mmcc CAMSS_CSI1_AHB_CLK>, + <&mmcc CAMSS_CSI1_CLK>, + <&mmcc CAMSS_CSI1PHY_CLK>, + <&mmcc CAMSS_CSI1PIX_CLK>, + <&mmcc CAMSS_CSI1RDI_CLK>, + <&mmcc CAMSS_CSI2_AHB_CLK>, + <&mmcc CAMSS_CSI2_CLK>, + <&mmcc CAMSS_CSI2PHY_CLK>, + <&mmcc CAMSS_CSI2PIX_CLK>, + <&mmcc CAMSS_CSI2RDI_CLK>, + <&mmcc CAMSS_CSI3_AHB_CLK>, + <&mmcc CAMSS_CSI3_CLK>, + <&mmcc CAMSS_CSI3PHY_CLK>, + <&mmcc CAMSS_CSI3PIX_CLK>, + <&mmcc CAMSS_CSI3RDI_CLK>, + <&mmcc CAMSS_AHB_CLK>, + <&mmcc CAMSS_VFE0_CLK>, + <&mmcc CAMSS_CSI_VFE0_CLK>, + <&mmcc CAMSS_VFE0_AHB_CLK>, + <&mmcc CAMSS_VFE0_STREAM_CLK>, + <&mmcc CAMSS_VFE1_CLK>, + <&mmcc CAMSS_CSI_VFE1_CLK>, + <&mmcc CAMSS_VFE1_AHB_CLK>, + <&mmcc CAMSS_VFE1_STREAM_CLK>, + <&mmcc CAMSS_VFE_AHB_CLK>, + <&mmcc CAMSS_VFE_AXI_CLK>; + + clock-names = "top_ahb", + "ispif_ahb", + "csiphy0_timer", + "csiphy1_timer", + "csiphy2_timer", + "csi0_ahb", + "csi0", + "csi0_phy", + "csi0_pix", + "csi0_rdi", + "csi1_ahb", + "csi1", + "csi1_phy", + "csi1_pix", + "csi1_rdi", + "csi2_ahb", + "csi2", + "csi2_phy", + "csi2_pix", + "csi2_rdi", + "csi3_ahb", + "csi3", + "csi3_phy", + "csi3_pix", + "csi3_rdi", + "ahb", + "vfe0", + "csi_vfe0", + "vfe0_ahb", + "vfe0_stream", + "vfe1", + "csi_vfe1", + "vfe1_ahb", + "vfe1_stream", + "vfe_ahb", + "vfe_axi"; + + interrupts = <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 80 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 296 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 297 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 298 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 299 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 309 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 314 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 315 IRQ_TYPE_EDGE_RISING>; + + interrupt-names = "csiphy0", + "csiphy1", + "csiphy2", + "csid0", + "csid1", + "csid2", + "csid3", + "ispif", + "vfe0", + "vfe1"; + + iommus = <&vfe_smmu 0>, + <&vfe_smmu 1>, + <&vfe_smmu 2>, + <&vfe_smmu 3>; + + power-domains = <&mmcc VFE0_GDSC>, + <&mmcc VFE1_GDSC>; + + reg = <0x00a34000 0x1000>, + <0x00a00030 0x4>, + <0x00a35000 0x1000>, + <0x00a00038 0x4>, + <0x00a36000 0x1000>, + <0x00a00040 0x4>, + <0x00a30000 0x100>, + <0x00a30400 0x100>, + <0x00a30800 0x100>, + <0x00a30c00 0x100>, + <0x00a31000 0x500>, + <0x00a00020 0x10>, + <0x00a10000 0x1000>, + <0x00a14000 0x1000>; + + reg-names = "csiphy0", + "csiphy0_clk_mux", + "csiphy1", + "csiphy1_clk_mux", + "csiphy2", + "csiphy2_clk_mux", + "csid0", + "csid1", + "csid2", + "csid3", + "ispif", + "csi_clk_mux", + "vfe0", + "vfe1"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml new file mode 100644 index 000000000000..841a1aafdd13 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,sdm660-camss.yaml @@ -0,0 +1,398 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,sdm660-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + - AngeloGioacchino Del Regno <angelogioacchino.delregno@somainline.org> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,sdm660-camss + + clocks: + minItems: 42 + maxItems: 42 + + clock-names: + items: + - const: ahb + - const: cphy_csid0 + - const: cphy_csid1 + - const: cphy_csid2 + - const: cphy_csid3 + - const: csi0_ahb + - const: csi0 + - const: csi0_phy + - const: csi0_pix + - const: csi0_rdi + - const: csi1_ahb + - const: csi1 + - const: csi1_phy + - const: csi1_pix + - const: csi1_rdi + - const: csi2_ahb + - const: csi2 + - const: csi2_phy + - const: csi2_pix + - const: csi2_rdi + - const: csi3_ahb + - const: csi3 + - const: csi3_phy + - const: csi3_pix + - const: csi3_rdi + - const: csiphy0_timer + - const: csiphy1_timer + - const: csiphy2_timer + - const: csiphy_ahb2crif + - const: csi_vfe0 + - const: csi_vfe1 + - const: ispif_ahb + - const: throttle_axi + - const: top_ahb + - const: vfe0_ahb + - const: vfe0 + - const: vfe0_stream + - const: vfe1_ahb + - const: vfe1 + - const: vfe1_stream + - const: vfe_ahb + - const: vfe_axi + + interrupts: + minItems: 10 + maxItems: 10 + + interrupt-names: + items: + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: ispif + - const: vfe0 + - const: vfe1 + + iommus: + maxItems: 4 + + power-domains: + items: + - description: VFE0 GDSC - Video Front End, Global Distributed Switch Controller. + - description: VFE1 GDSC - Video Front End, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@3: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 14 + maxItems: 14 + + reg-names: + items: + - const: csi_clk_mux + - const: csid0 + - const: csid1 + - const: csid2 + - const: csid3 + - const: csiphy0 + - const: csiphy0_clk_mux + - const: csiphy1 + - const: csiphy1_clk_mux + - const: csiphy2 + - const: csiphy2_clk_mux + - const: ispif + - const: vfe0 + - const: vfe1 + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,gcc-sdm660.h> + #include <dt-bindings/clock/qcom,mmcc-sdm660.h> + + camss: camss@ca00000 { + compatible = "qcom,sdm660-camss"; + + clocks = <&mmcc CAMSS_AHB_CLK>, + <&mmcc CAMSS_CPHY_CSID0_CLK>, + <&mmcc CAMSS_CPHY_CSID1_CLK>, + <&mmcc CAMSS_CPHY_CSID2_CLK>, + <&mmcc CAMSS_CPHY_CSID3_CLK>, + <&mmcc CAMSS_CSI0_AHB_CLK>, + <&mmcc CAMSS_CSI0_CLK>, + <&mmcc CAMSS_CPHY_CSID0_CLK>, + <&mmcc CAMSS_CSI0PIX_CLK>, + <&mmcc CAMSS_CSI0RDI_CLK>, + <&mmcc CAMSS_CSI1_AHB_CLK>, + <&mmcc CAMSS_CSI1_CLK>, + <&mmcc CAMSS_CPHY_CSID1_CLK>, + <&mmcc CAMSS_CSI1PIX_CLK>, + <&mmcc CAMSS_CSI1RDI_CLK>, + <&mmcc CAMSS_CSI2_AHB_CLK>, + <&mmcc CAMSS_CSI2_CLK>, + <&mmcc CAMSS_CPHY_CSID2_CLK>, + <&mmcc CAMSS_CSI2PIX_CLK>, + <&mmcc CAMSS_CSI2RDI_CLK>, + <&mmcc CAMSS_CSI3_AHB_CLK>, + <&mmcc CAMSS_CSI3_CLK>, + <&mmcc CAMSS_CPHY_CSID3_CLK>, + <&mmcc CAMSS_CSI3PIX_CLK>, + <&mmcc CAMSS_CSI3RDI_CLK>, + <&mmcc CAMSS_CSI0PHYTIMER_CLK>, + <&mmcc CAMSS_CSI1PHYTIMER_CLK>, + <&mmcc CAMSS_CSI2PHYTIMER_CLK>, + <&mmcc CSIPHY_AHB2CRIF_CLK>, + <&mmcc CAMSS_CSI_VFE0_CLK>, + <&mmcc CAMSS_CSI_VFE1_CLK>, + <&mmcc CAMSS_ISPIF_AHB_CLK>, + <&mmcc THROTTLE_CAMSS_AXI_CLK>, + <&mmcc CAMSS_TOP_AHB_CLK>, + <&mmcc CAMSS_VFE0_AHB_CLK>, + <&mmcc CAMSS_VFE0_CLK>, + <&mmcc CAMSS_VFE0_STREAM_CLK>, + <&mmcc CAMSS_VFE1_AHB_CLK>, + <&mmcc CAMSS_VFE1_CLK>, + <&mmcc CAMSS_VFE1_STREAM_CLK>, + <&mmcc CAMSS_VFE_VBIF_AHB_CLK>, + <&mmcc CAMSS_VFE_VBIF_AXI_CLK>; + + clock-names = "ahb", + "cphy_csid0", + "cphy_csid1", + "cphy_csid2", + "cphy_csid3", + "csi0_ahb", + "csi0", + "csi0_phy", + "csi0_pix", + "csi0_rdi", + "csi1_ahb", + "csi1", + "csi1_phy", + "csi1_pix", + "csi1_rdi", + "csi2_ahb", + "csi2", + "csi2_phy", + "csi2_pix", + "csi2_rdi", + "csi3_ahb", + "csi3", + "csi3_phy", + "csi3_pix", + "csi3_rdi", + "csiphy0_timer", + "csiphy1_timer", + "csiphy2_timer", + "csiphy_ahb2crif", + "csi_vfe0", + "csi_vfe1", + "ispif_ahb", + "throttle_axi", + "top_ahb", + "vfe0_ahb", + "vfe0", + "vfe0_stream", + "vfe1_ahb", + "vfe1", + "vfe1_stream", + "vfe_ahb", + "vfe_axi"; + + interrupts = <GIC_SPI 296 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 297 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 298 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 299 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 78 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 80 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 309 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 314 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 315 IRQ_TYPE_EDGE_RISING>; + + interrupt-names = "csid0", + "csid1", + "csid2", + "csid3", + "csiphy0", + "csiphy1", + "csiphy2", + "ispif", + "vfe0", + "vfe1"; + + iommus = <&mmss_smmu 0xc00>, + <&mmss_smmu 0xc01>, + <&mmss_smmu 0xc02>, + <&mmss_smmu 0xc03>; + + power-domains = <&mmcc CAMSS_VFE0_GDSC>, + <&mmcc CAMSS_VFE1_GDSC>; + + reg = <0x0ca00020 0x10>, + <0x0ca30000 0x100>, + <0x0ca30400 0x100>, + <0x0ca30800 0x100>, + <0x0ca30c00 0x100>, + <0x0c824000 0x1000>, + <0x0ca00120 0x4>, + <0x0c825000 0x1000>, + <0x0ca00124 0x4>, + <0x0c826000 0x1000>, + <0x0ca00128 0x4>, + <0x0ca31000 0x500>, + <0x0ca10000 0x1000>, + <0x0ca14000 0x1000>; + + reg-names = "csi_clk_mux", + "csid0", + "csid1", + "csid2", + "csid3", + "csiphy0", + "csiphy0_clk_mux", + "csiphy1", + "csiphy1_clk_mux", + "csiphy2", + "csiphy2_clk_mux", + "ispif", + "vfe0", + "vfe1"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml b/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml new file mode 100644 index 000000000000..9ca5dfa7f226 --- /dev/null +++ b/Documentation/devicetree/bindings/media/qcom,sdm845-camss.yaml @@ -0,0 +1,371 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/media/qcom,sdm845-camss.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Qualcomm CAMSS ISP + +maintainers: + - Robert Foss <robert.foss@linaro.org> + +description: | + The CAMSS IP is a CSI decoder and ISP present on Qualcomm platforms + +properties: + compatible: + const: qcom,sdm845-camss + + clocks: + minItems: 36 + maxItems: 36 + + clock-names: + items: + - const: camnoc_axi + - const: cpas_ahb + - const: cphy_rx_src + - const: csi0 + - const: csi0_src + - const: csi1 + - const: csi1_src + - const: csi2 + - const: csi2_src + - const: csiphy0 + - const: csiphy0_timer + - const: csiphy0_timer_src + - const: csiphy1 + - const: csiphy1_timer + - const: csiphy1_timer_src + - const: csiphy2 + - const: csiphy2_timer + - const: csiphy2_timer_src + - const: csiphy3 + - const: csiphy3_timer + - const: csiphy3_timer_src + - const: gcc_camera_ahb + - const: gcc_camera_axi + - const: slow_ahb_src + - const: soc_ahb + - const: vfe0_axi + - const: vfe0 + - const: vfe0_cphy_rx + - const: vfe0_src + - const: vfe1_axi + - const: vfe1 + - const: vfe1_cphy_rx + - const: vfe1_src + - const: vfe_lite + - const: vfe_lite_cphy_rx + - const: vfe_lite_src + + interrupts: + minItems: 10 + maxItems: 10 + + interrupt-names: + items: + - const: csid0 + - const: csid1 + - const: csid2 + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: csiphy3 + - const: vfe0 + - const: vfe1 + - const: vfe_lite + + iommus: + maxItems: 4 + + power-domains: + items: + - description: IFE0 GDSC - Image Front End, Global Distributed Switch Controller. + - description: IFE1 GDSC - Image Front End, Global Distributed Switch Controller. + - description: Titan GDSC - Titan ISP Block, Global Distributed Switch Controller. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + description: + CSI input ports. + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + items: + - const: 7 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@2: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + port@3: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: + Input port for receiving CSI data. + + properties: + endpoint: + $ref: video-interfaces.yaml# + unevaluatedProperties: false + + properties: + clock-lanes: + maxItems: 1 + + data-lanes: + minItems: 1 + maxItems: 4 + + required: + - clock-lanes + - data-lanes + + reg: + minItems: 10 + maxItems: 10 + + reg-names: + items: + - const: csid0 + - const: csid1 + - const: csid2 + - const: csiphy0 + - const: csiphy1 + - const: csiphy2 + - const: csiphy3 + - const: vfe0 + - const: vfe1 + - const: vfe_lite + + vdda-supply: + description: + Definition of the regulator used as analog power supply. + +required: + - clock-names + - clocks + - compatible + - interrupt-names + - interrupts + - iommus + - power-domains + - reg + - reg-names + - vdda-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/qcom,camcc-sdm845.h> + #include <dt-bindings/clock/qcom,gcc-sdm845.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + camss: camss@a00000 { + compatible = "qcom,sdm845-camss"; + + clocks = <&clock_camcc CAM_CC_CAMNOC_AXI_CLK>, + <&clock_camcc CAM_CC_CPAS_AHB_CLK>, + <&clock_camcc CAM_CC_CPHY_RX_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_0_CSID_CLK>, + <&clock_camcc CAM_CC_IFE_0_CSID_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_1_CSID_CLK>, + <&clock_camcc CAM_CC_IFE_1_CSID_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_LITE_CSID_CLK>, + <&clock_camcc CAM_CC_IFE_LITE_CSID_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY0_CLK>, + <&clock_camcc CAM_CC_CSI0PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI0PHYTIMER_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY1_CLK>, + <&clock_camcc CAM_CC_CSI1PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI1PHYTIMER_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY2_CLK>, + <&clock_camcc CAM_CC_CSI2PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI2PHYTIMER_CLK_SRC>, + <&clock_camcc CAM_CC_CSIPHY3_CLK>, + <&clock_camcc CAM_CC_CSI3PHYTIMER_CLK>, + <&clock_camcc CAM_CC_CSI3PHYTIMER_CLK_SRC>, + <&gcc GCC_CAMERA_AHB_CLK>, + <&gcc GCC_CAMERA_AXI_CLK>, + <&clock_camcc CAM_CC_SLOW_AHB_CLK_SRC>, + <&clock_camcc CAM_CC_SOC_AHB_CLK>, + <&clock_camcc CAM_CC_IFE_0_AXI_CLK>, + <&clock_camcc CAM_CC_IFE_0_CLK>, + <&clock_camcc CAM_CC_IFE_0_CPHY_RX_CLK>, + <&clock_camcc CAM_CC_IFE_0_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_1_AXI_CLK>, + <&clock_camcc CAM_CC_IFE_1_CLK>, + <&clock_camcc CAM_CC_IFE_1_CPHY_RX_CLK>, + <&clock_camcc CAM_CC_IFE_1_CLK_SRC>, + <&clock_camcc CAM_CC_IFE_LITE_CLK>, + <&clock_camcc CAM_CC_IFE_LITE_CPHY_RX_CLK>, + <&clock_camcc CAM_CC_IFE_LITE_CLK_SRC>; + + clock-names = "camnoc_axi", + "cpas_ahb", + "cphy_rx_src", + "csi0", + "csi0_src", + "csi1", + "csi1_src", + "csi2", + "csi2_src", + "csiphy0", + "csiphy0_timer", + "csiphy0_timer_src", + "csiphy1", + "csiphy1_timer", + "csiphy1_timer_src", + "csiphy2", + "csiphy2_timer", + "csiphy2_timer_src", + "csiphy3", + "csiphy3_timer", + "csiphy3_timer_src", + "gcc_camera_ahb", + "gcc_camera_axi", + "slow_ahb_src", + "soc_ahb", + "vfe0_axi", + "vfe0", + "vfe0_cphy_rx", + "vfe0_src", + "vfe1_axi", + "vfe1", + "vfe1_cphy_rx", + "vfe1_src", + "vfe_lite", + "vfe_lite_cphy_rx", + "vfe_lite_src"; + + interrupts = <GIC_SPI 464 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 466 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 468 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 477 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 478 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 479 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 448 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 465 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 467 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 469 IRQ_TYPE_LEVEL_HIGH>; + + interrupt-names = "csid0", + "csid1", + "csid2", + "csiphy0", + "csiphy1", + "csiphy2", + "csiphy3", + "vfe0", + "vfe1", + "vfe_lite"; + + iommus = <&apps_smmu 0x0808 0x0>, + <&apps_smmu 0x0810 0x8>, + <&apps_smmu 0x0c08 0x0>, + <&apps_smmu 0x0c10 0x8>; + + power-domains = <&clock_camcc IFE_0_GDSC>, + <&clock_camcc IFE_1_GDSC>, + <&clock_camcc TITAN_TOP_GDSC>; + + reg = <0 0xacb3000 0 0x1000>, + <0 0xacba000 0 0x1000>, + <0 0xacc8000 0 0x1000>, + <0 0xac65000 0 0x1000>, + <0 0xac66000 0 0x1000>, + <0 0xac67000 0 0x1000>, + <0 0xac68000 0 0x1000>, + <0 0xacaf000 0 0x4000>, + <0 0xacb6000 0 0x4000>, + <0 0xacc4000 0 0x4000>; + + reg-names = "csid0", + "csid1", + "csid2", + "csiphy0", + "csiphy1", + "csiphy2", + "csiphy3", + "vfe0", + "vfe1", + "vfe_lite"; + + vdda-supply = <®_2v8>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/rc.yaml b/Documentation/devicetree/bindings/media/rc.yaml index 946441b4e1a5..af9e7e59e5a1 100644 --- a/Documentation/devicetree/bindings/media/rc.yaml +++ b/Documentation/devicetree/bindings/media/rc.yaml @@ -90,9 +90,12 @@ properties: - rc-leadtek-y04g0051 - rc-lme2510 - rc-manli + - rc-mecool-kii-pro + - rc-mecool-kiii-pro - rc-medion-x10 - rc-medion-x10-digitainer - rc-medion-x10-or2x + - rc-minix-neo - rc-msi-digivox-ii - rc-msi-digivox-iii - rc-msi-tvanywhere @@ -145,11 +148,13 @@ properties: - rc-videomate-s350 - rc-videomate-tv-pvr - rc-videostrong-kii-pro + - rc-vega-s9x - rc-wetek-hub - rc-wetek-play2 - rc-winfast - rc-winfast-usbii-deluxe - rc-x96max + - rc-xbox-360 - rc-xbox-dvd - rc-zx-irdec diff --git a/Documentation/devicetree/bindings/media/renesas,drif.txt b/Documentation/devicetree/bindings/media/renesas,drif.txt deleted file mode 100644 index 0d8974aa8b38..000000000000 --- a/Documentation/devicetree/bindings/media/renesas,drif.txt +++ /dev/null @@ -1,177 +0,0 @@ -Renesas R-Car Gen3 Digital Radio Interface controller (DRIF) ------------------------------------------------------------- - -R-Car Gen3 DRIF is a SPI like receive only slave device. A general -representation of DRIF interfacing with a master device is shown below. - -+---------------------+ +---------------------+ -| |-----SCK------->|CLK | -| Master |-----SS-------->|SYNC DRIFn (slave) | -| |-----SD0------->|D0 | -| |-----SD1------->|D1 | -+---------------------+ +---------------------+ - -As per datasheet, each DRIF channel (drifn) is made up of two internal -channels (drifn0 & drifn1). These two internal channels share the common -CLK & SYNC. Each internal channel has its own dedicated resources like -irq, dma channels, address space & clock. This internal split is not -visible to the external master device. - -The device tree model represents each internal channel as a separate node. -The internal channels sharing the CLK & SYNC are tied together by their -phandles using a property called "renesas,bonding". For the rest of -the documentation, unless explicitly stated, the word channel implies an -internal channel. - -When both internal channels are enabled they need to be managed together -as one (i.e.) they cannot operate alone as independent devices. Out of the -two, one of them needs to act as a primary device that accepts common -properties of both the internal channels. This channel is identified by a -property called "renesas,primary-bond". - -To summarize, - - When both the internal channels that are bonded together are enabled, - the zeroth channel is selected as primary-bond. This channels accepts - properties common to all the members of the bond. - - When only one of the bonded channels need to be enabled, the property - "renesas,bonding" or "renesas,primary-bond" will have no effect. That - enabled channel can act alone as any other independent device. - -Required properties of an internal channel: -------------------------------------------- -- compatible: "renesas,r8a7795-drif" if DRIF controller is a part of R8A7795 SoC. - "renesas,r8a7796-drif" if DRIF controller is a part of R8A7796 SoC. - "renesas,rcar-gen3-drif" for a generic R-Car Gen3 compatible device. - - When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first - followed by the generic version. - -- reg: offset and length of that channel. -- interrupts: associated with that channel. -- clocks: phandle and clock specifier of that channel. -- clock-names: clock input name string: "fck". -- dmas: phandles to the DMA channels. -- dma-names: names of the DMA channel: "rx". -- renesas,bonding: phandle to the other channel. - -Optional properties of an internal channel: -------------------------------------------- -- power-domains: phandle to the respective power domain. - -Required properties of an internal channel when: - - It is the only enabled channel of the bond (or) - - If it acts as primary among enabled bonds --------------------------------------------------------- -- pinctrl-0: pin control group to be used for this channel. -- pinctrl-names: must be "default". -- renesas,primary-bond: empty property indicating the channel acts as primary - among the bonded channels. -- port: child port node corresponding to the data input, in accordance with - the video interface bindings defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. The port - node must contain at least one endpoint. - -Optional endpoint property: ---------------------------- -- sync-active: Indicates sync signal polarity, 0/1 for low/high respectively. - This property maps to SYNCAC bit in the hardware manual. The - default is 1 (active high). - -Example: --------- - -(1) Both internal channels enabled: ------------------------------------ - -When interfacing with a third party tuner device with two data pins as shown -below. - -+---------------------+ +---------------------+ -| |-----SCK------->|CLK | -| Master |-----SS-------->|SYNC DRIFn (slave) | -| |-----SD0------->|D0 | -| |-----SD1------->|D1 | -+---------------------+ +---------------------+ - - drif00: rif@e6f40000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f40000 0 0x64>; - interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 515>; - clock-names = "fck"; - dmas = <&dmac1 0x20>, <&dmac2 0x20>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif01>; - renesas,primary-bond; - pinctrl-0 = <&drif0_pins>; - pinctrl-names = "default"; - port { - drif0_ep: endpoint { - remote-endpoint = <&tuner_ep>; - }; - }; - }; - - drif01: rif@e6f50000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f50000 0 0x64>; - interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 514>; - clock-names = "fck"; - dmas = <&dmac1 0x22>, <&dmac2 0x22>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif00>; - }; - - -(2) Internal channel 1 alone is enabled: ----------------------------------------- - -When interfacing with a third party tuner device with one data pin as shown -below. - -+---------------------+ +---------------------+ -| |-----SCK------->|CLK | -| Master |-----SS-------->|SYNC DRIFn (slave) | -| | |D0 (unused) | -| |-----SD-------->|D1 | -+---------------------+ +---------------------+ - - drif00: rif@e6f40000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f40000 0 0x64>; - interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 515>; - clock-names = "fck"; - dmas = <&dmac1 0x20>, <&dmac2 0x20>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif01>; - }; - - drif01: rif@e6f50000 { - compatible = "renesas,r8a7795-drif", - "renesas,rcar-gen3-drif"; - reg = <0 0xe6f50000 0 0x64>; - interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&cpg CPG_MOD 514>; - clock-names = "fck"; - dmas = <&dmac1 0x22>, <&dmac2 0x22>; - dma-names = "rx", "rx"; - power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; - renesas,bonding = <&drif00>; - pinctrl-0 = <&drif0_pins>; - pinctrl-names = "default"; - port { - drif0_ep: endpoint { - remote-endpoint = <&tuner_ep>; - sync-active = <0>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/media/renesas,drif.yaml b/Documentation/devicetree/bindings/media/renesas,drif.yaml new file mode 100644 index 000000000000..f1bdaeab4053 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,drif.yaml @@ -0,0 +1,279 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/renesas,drif.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen3 Digital Radio Interface Controller (DRIF) + +maintainers: + - Ramesh Shanmugasundaram <rashanmu@gmail.com> + - Fabrizio Castro <fabrizio.castro.jz@renesas.com> + +description: | + R-Car Gen3 DRIF is a SPI like receive only slave device. A general + representation of DRIF interfacing with a master device is shown below. + + +---------------------+ +---------------------+ + | |-----SCK------->|CLK | + | Master |-----SS-------->|SYNC DRIFn (slave) | + | |-----SD0------->|D0 | + | |-----SD1------->|D1 | + +---------------------+ +---------------------+ + + As per datasheet, each DRIF channel (drifn) is made up of two internal + channels (drifn0 & drifn1). These two internal channels share the common + CLK & SYNC. Each internal channel has its own dedicated resources like + irq, dma channels, address space & clock. This internal split is not + visible to the external master device. + + The device tree model represents each internal channel as a separate node. + The internal channels sharing the CLK & SYNC are tied together by their + phandles using a property called "renesas,bonding". For the rest of + the documentation, unless explicitly stated, the word channel implies an + internal channel. + + When both internal channels are enabled they need to be managed together + as one (i.e.) they cannot operate alone as independent devices. Out of the + two, one of them needs to act as a primary device that accepts common + properties of both the internal channels. This channel is identified by a + property called "renesas,primary-bond". + + To summarize, + * When both the internal channels that are bonded together are enabled, + the zeroth channel is selected as primary-bond. This channels accepts + properties common to all the members of the bond. + * When only one of the bonded channels need to be enabled, the property + "renesas,bonding" or "renesas,primary-bond" will have no effect. That + enabled channel can act alone as any other independent device. + +properties: + compatible: + items: + - enum: + - renesas,r8a7795-drif # R-Car H3 + - renesas,r8a7796-drif # R-Car M3-W + - renesas,r8a77965-drif # R-Car M3-N + - renesas,r8a77990-drif # R-Car E3 + - const: renesas,rcar-gen3-drif # Generic R-Car Gen3 compatible device + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + maxItems: 1 + items: + - const: fck + + resets: + maxItems: 1 + + dmas: + minItems: 1 + maxItems: 2 + + dma-names: + minItems: 1 + maxItems: 2 + items: + - const: rx + - const: rx + + renesas,bonding: + $ref: /schemas/types.yaml#/definitions/phandle + description: + The phandle to the other internal channel of DRIF + + power-domains: + maxItems: 1 + + renesas,primary-bond: + type: boolean + description: + Indicates that the channel acts as primary among the bonded channels. + + port: + type: object + description: + Child port node corresponding to the data input, in accordance with the + video interface bindings defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. + The port node must contain at least one endpoint. + + properties: + endpoint: + type: object + + properties: + remote-endpoint: + description: + A phandle to the remote tuner endpoint subnode in remote node + port. + + sync-active: + enum: [0, 1] + description: + Indicates sync signal polarity, 0/1 for low/high respectively. + This property maps to SYNCAC bit in the hardware manual. The + default is 1 (active high). + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - resets + - dmas + - dma-names + - renesas,bonding + - power-domains + +allOf: + - if: + required: + - renesas,primary-bond + then: + required: + - pinctrl-0 + - pinctrl-names + - port + + - if: + required: + - port + then: + required: + - pinctrl-0 + - pinctrl-names + else: + properties: + pinctrl-0: false + pinctrl-names: false + +additionalProperties: false + +examples: + # Example with both internal channels enabled. + # + # When interfacing with a third party tuner device with two data pins as shown + # below. + # + # +---------------------+ +---------------------+ + # | |-----SCK------->|CLK | + # | Master |-----SS-------->|SYNC DRIFn (slave) | + # | |-----SD0------->|D0 | + # | |-----SD1------->|D1 | + # +---------------------+ +---------------------+ + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + drif00: rif@e6f40000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f40000 0 0x64>; + interrupts = <GIC_SPI 12 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 515>; + clock-names = "fck"; + dmas = <&dmac1 0x20>, <&dmac2 0x20>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif01>; + resets = <&cpg 515>; + renesas,primary-bond; + pinctrl-0 = <&drif0_pins>; + pinctrl-names = "default"; + port { + drif0_ep: endpoint { + remote-endpoint = <&tuner_ep>; + }; + }; + }; + + drif01: rif@e6f50000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f50000 0 0x64>; + interrupts = <GIC_SPI 13 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 514>; + clock-names = "fck"; + dmas = <&dmac1 0x22>, <&dmac2 0x22>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + renesas,bonding = <&drif00>; + resets = <&cpg 514>; + }; + }; + + # Example with internal channel 1 alone enabled. + # + # When interfacing with a third party tuner device with one data pin as shown + # below. + # + # +---------------------+ +---------------------+ + # | |-----SCK------->|CLK | + # | Master |-----SS-------->|SYNC DRIFn (slave) | + # | | |D0 (unused) | + # | |-----SD-------->|D1 | + # +---------------------+ +---------------------+ + - | + #include <dt-bindings/clock/r8a7795-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a7795-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + drif10: rif@e6f60000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f60000 0 0x64>; + interrupts = <GIC_SPI 14 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 513>; + clock-names = "fck"; + dmas = <&dmac1 0x24>, <&dmac2 0x24>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 513>; + renesas,bonding = <&drif11>; + status = "disabled"; + }; + + drif11: rif@e6f70000 { + compatible = "renesas,r8a7795-drif", + "renesas,rcar-gen3-drif"; + reg = <0 0xe6f70000 0 0x64>; + interrupts = <GIC_SPI 15 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 512>; + clock-names = "fck"; + dmas = <&dmac1 0x26>, <&dmac2 0x26>; + dma-names = "rx", "rx"; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + resets = <&cpg 512>; + renesas,bonding = <&drif10>; + pinctrl-0 = <&drif1_pins>; + pinctrl-names = "default"; + port { + drif1_ep: endpoint { + remote-endpoint = <&tuner_ep1>; + sync-active = <0>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/zx-irdec.txt b/Documentation/devicetree/bindings/media/zx-irdec.txt deleted file mode 100644 index 295b9fab593e..000000000000 --- a/Documentation/devicetree/bindings/media/zx-irdec.txt +++ /dev/null @@ -1,14 +0,0 @@ -IR Decoder (IRDEC) on ZTE ZX family SoCs - -Required properties: - - compatible: Should be "zte,zx296718-irdec". - - reg: Physical base address and length of IRDEC registers. - - interrupts: Interrupt number of IRDEC. - -Exmaples: - - irdec: ir-decoder@111000 { - compatible = "zte,zx296718-irdec"; - reg = <0x111000 0x1000>; - interrupts = <GIC_SPI 111 IRQ_TYPE_LEVEL_HIGH>; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml index 09bde65e1955..9163c3f12a85 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra124-emc.yaml @@ -37,9 +37,10 @@ properties: description: phandle of the memory controller node - core-supply: + power-domains: + maxItems: 1 description: - Phandle of voltage regulator of the SoC "core" power domain. + Phandle of the SoC "core" power domain. operating-points-v2: description: @@ -370,7 +371,7 @@ examples: nvidia,memory-controller = <&mc>; operating-points-v2 = <&dvfs_opp_table>; - core-supply = <&vdd_core>; + power-domains = <&domain>; #interconnect-cells = <0>; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt index cc443fcf4bec..d2250498c36d 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt @@ -23,7 +23,7 @@ For each opp entry in 'operating-points-v2' table: matches, the OPP gets enabled. Optional properties: -- core-supply: Phandle of voltage regulator of the SoC "core" power domain. +- power-domains: Phandle of the SoC "core" power domain. Child device nodes describe the memory settings for different configurations and clock rates. @@ -48,7 +48,7 @@ Example: interrupts = <0 78 0x04>; clocks = <&tegra_car TEGRA20_CLK_EMC>; nvidia,memory-controller = <&mc>; - core-supply = <&core_vdd_reg>; + power-domains = <&domain>; operating-points-v2 = <&opp_table>; } diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.txt deleted file mode 100644 index 739b7c6f2e26..000000000000 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.txt +++ /dev/null @@ -1,40 +0,0 @@ -NVIDIA Tegra20 MC(Memory Controller) - -Required properties: -- compatible : "nvidia,tegra20-mc-gart" -- reg : Should contain 2 register ranges: physical base address and length of - the controller's registers and the GART aperture respectively. -- clocks: Must contain an entry for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. -- clock-names: Must include the following entries: - - mc: the module's clock input -- interrupts : Should contain MC General interrupt. -- #reset-cells : Should be 1. This cell represents memory client module ID. - The assignments may be found in header file <dt-bindings/memory/tegra20-mc.h> - or in the TRM documentation. -- #iommu-cells: Should be 0. This cell represents the number of cells in an - IOMMU specifier needed to encode an address. GART supports only a single - address space that is shared by all devices, therefore no additional - information needed for the address encoding. -- #interconnect-cells : Should be 1. This cell represents memory client. - The assignments may be found in header file <dt-bindings/memory/tegra20-mc.h>. - -Example: - mc: memory-controller@7000f000 { - compatible = "nvidia,tegra20-mc-gart"; - reg = <0x7000f000 0x400 /* controller registers */ - 0x58000000 0x02000000>; /* GART aperture */ - clocks = <&tegra_car TEGRA20_CLK_MC>; - clock-names = "mc"; - interrupts = <GIC_SPI 77 0x04>; - #reset-cells = <1>; - #iommu-cells = <0>; - #interconnect-cells = <1>; - }; - - video-codec@6001a000 { - compatible = "nvidia,tegra20-vde"; - ... - resets = <&mc TEGRA20_MC_RESET_VDE>; - iommus = <&mc>; - }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.yaml new file mode 100644 index 000000000000..55caf6905399 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-mc.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/nvidia,tegra20-mc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra20 SoC Memory Controller + +maintainers: + - Dmitry Osipenko <digetx@gmail.com> + - Jon Hunter <jonathanh@nvidia.com> + - Thierry Reding <thierry.reding@gmail.com> + +description: | + The Tegra20 Memory Controller merges request streams from various client + interfaces into request stream(s) for the various memory target devices, + and returns response data to the various clients. The Memory Controller + has a configurable arbitration algorithm to allow the user to fine-tune + performance among the various clients. + + Tegra20 Memory Controller includes the GART (Graphics Address Relocation + Table) which allows Memory Controller to provide a linear view of a + fragmented memory pages. + +properties: + compatible: + const: nvidia,tegra20-mc-gart + + reg: + items: + - description: controller registers + - description: GART registers + + clocks: + maxItems: 1 + + clock-names: + items: + - const: mc + + interrupts: + maxItems: 1 + + "#reset-cells": + const: 1 + + "#iommu-cells": + const: 0 + + "#interconnect-cells": + const: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + - "#reset-cells" + - "#iommu-cells" + - "#interconnect-cells" + +additionalProperties: false + +examples: + - | + memory-controller@7000f000 { + compatible = "nvidia,tegra20-mc-gart"; + reg = <0x7000f000 0x400>, /* Controller registers */ + <0x58000000 0x02000000>; /* GART aperture */ + clocks = <&clock_controller 32>; + clock-names = "mc"; + + interrupts = <0 77 4>; + + #iommu-cells = <0>; + #reset-cells = <1>; + #interconnect-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml index 0a2e2c0d0fdd..fb6af14cb49c 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-emc.yaml @@ -39,9 +39,10 @@ properties: description: Phandle of the Memory Controller node. - core-supply: + power-domains: + maxItems: 1 description: - Phandle of voltage regulator of the SoC "core" power domain. + Phandle of the SoC "core" power domain. operating-points-v2: description: @@ -241,7 +242,7 @@ examples: nvidia,memory-controller = <&mc>; operating-points-v2 = <&dvfs_opp_table>; - core-supply = <&vdd_core>; + power-domains = <&domain>; #interconnect-cells = <0>; diff --git a/Documentation/devicetree/bindings/mfd/ab8500.txt b/Documentation/devicetree/bindings/mfd/ab8500.txt index d2a6e835c257..937b3e5505e0 100644 --- a/Documentation/devicetree/bindings/mfd/ab8500.txt +++ b/Documentation/devicetree/bindings/mfd/ab8500.txt @@ -72,7 +72,9 @@ Required child device properties: pwm|regulator|rtc|sysctrl|usb]"; A few child devices require ADC channels from the GPADC node. Those follow the - standard bindings from iio/iio-bindings.txt and iio/adc/adc.txt + standard bindings from + https://github.com/devicetree-org/dt-schema/blob/master/schemas/iio/iio-consumer.yaml + and Documentation/devicetree/bindings/iio/adc/adc.yaml abx500-temp : io-channels "aux1" and "aux2" for measuring external temperatures. diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt index d0a38ba8b9ce..936aa108eab4 100644 --- a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt +++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt @@ -9,13 +9,7 @@ primary use case of the Aspeed LPC controller is as a slave on the bus conditions it can also take the role of bus master. The LPC controller is represented as a multi-function device to account for the -mix of functionality it provides. The principle split is between the register -layout at the start of the I/O space which is, to quote the Aspeed datasheet, -"basically compatible with the [LPC registers from the] popular BMC controller -H8S/2168[1]", and everything else, where everything else is an eclectic -collection of functions with a esoteric register layout. "Everything else", -here labeled the "host" portion of the controller, includes, but is not limited -to: +mix of functionality, which includes, but is not limited to: * An IPMI Block Transfer[2] Controller @@ -44,80 +38,36 @@ Required properties =================== - compatible: One of: - "aspeed,ast2400-lpc", "simple-mfd" - "aspeed,ast2500-lpc", "simple-mfd" - "aspeed,ast2600-lpc", "simple-mfd" + "aspeed,ast2400-lpc-v2", "simple-mfd", "syscon" + "aspeed,ast2500-lpc-v2", "simple-mfd", "syscon" + "aspeed,ast2600-lpc-v2", "simple-mfd", "syscon" - reg: contains the physical address and length values of the Aspeed LPC memory region. - #address-cells: <1> - #size-cells: <1> -- ranges: Maps 0 to the physical address and length of the LPC memory - region - -Required LPC Child nodes -======================== - -BMC Node --------- - -- compatible: One of: - "aspeed,ast2400-lpc-bmc" - "aspeed,ast2500-lpc-bmc" - "aspeed,ast2600-lpc-bmc" - -- reg: contains the physical address and length values of the - H8S/2168-compatible LPC controller memory region - -Host Node ---------- - -- compatible: One of: - "aspeed,ast2400-lpc-host", "simple-mfd", "syscon" - "aspeed,ast2500-lpc-host", "simple-mfd", "syscon" - "aspeed,ast2600-lpc-host", "simple-mfd", "syscon" - -- reg: contains the address and length values of the host-related - register space for the Aspeed LPC controller - -- #address-cells: <1> -- #size-cells: <1> -- ranges: Maps 0 to the address and length of the host-related LPC memory +- ranges: Maps 0 to the physical address and length of the LPC memory region Example: lpc: lpc@1e789000 { - compatible = "aspeed,ast2500-lpc", "simple-mfd"; + compatible = "aspeed,ast2500-lpc-v2", "simple-mfd", "syscon"; reg = <0x1e789000 0x1000>; #address-cells = <1>; #size-cells = <1>; ranges = <0x0 0x1e789000 0x1000>; - lpc_bmc: lpc-bmc@0 { - compatible = "aspeed,ast2500-lpc-bmc"; + lpc_snoop: lpc-snoop@0 { + compatible = "aspeed,ast2600-lpc-snoop"; reg = <0x0 0x80>; - }; - - lpc_host: lpc-host@80 { - compatible = "aspeed,ast2500-lpc-host", "simple-mfd", "syscon"; - reg = <0x80 0x1e0>; - reg-io-width = <4>; - - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x80 0x1e0>; + interrupts = <GIC_SPI 144 IRQ_TYPE_LEVEL_HIGH>; + snoop-ports = <0x80>; }; }; -BMC Node Children -================== - - -Host Node Children -================== LPC Host Interface Controller ------------------- @@ -149,14 +99,12 @@ Optional properties: Example: -lpc-host@80 { - lpc_ctrl: lpc-ctrl@0 { - compatible = "aspeed,ast2500-lpc-ctrl"; - reg = <0x0 0x80>; - clocks = <&syscon ASPEED_CLK_GATE_LCLK>; - memory-region = <&flash_memory>; - flash = <&spi>; - }; +lpc_ctrl: lpc-ctrl@80 { + compatible = "aspeed,ast2500-lpc-ctrl"; + reg = <0x80 0x80>; + clocks = <&syscon ASPEED_CLK_GATE_LCLK>; + memory-region = <&flash_memory>; + flash = <&spi>; }; LPC Host Controller @@ -179,9 +127,9 @@ Required properties: Example: -lhc: lhc@20 { +lhc: lhc@a0 { compatible = "aspeed,ast2500-lhc"; - reg = <0x20 0x24 0x48 0x8>; + reg = <0xa0 0x24 0xc8 0x8>; }; LPC reset control @@ -192,16 +140,18 @@ state of the LPC bus. Some systems may chose to modify this configuration. Required properties: - - compatible: "aspeed,ast2600-lpc-reset" or - "aspeed,ast2500-lpc-reset" - "aspeed,ast2400-lpc-reset" + - compatible: One of: + "aspeed,ast2600-lpc-reset"; + "aspeed,ast2500-lpc-reset"; + "aspeed,ast2400-lpc-reset"; + - reg: offset and length of the IP in the LHC memory region - #reset-controller indicates the number of reset cells expected Example: -lpc_reset: reset-controller@18 { +lpc_reset: reset-controller@98 { compatible = "aspeed,ast2500-lpc-reset"; - reg = <0x18 0x4>; + reg = <0x98 0x4>; #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index 76bf16ee27ec..4dfa70a013ae 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -94,6 +94,9 @@ properties: keyboard-controller: $ref: "/schemas/input/google,cros-ec-keyb.yaml#" + proximity: + $ref: "/schemas/iio/proximity/google,cros-ec-mkbp-proximity.yaml#" + codecs: type: object additionalProperties: false @@ -180,6 +183,10 @@ examples: interrupts = <99 0>; interrupt-parent = <&gpio7>; spi-max-frequency = <5000000>; + + proximity { + compatible = "google,cros-ec-mkbp-proximity"; + }; }; }; diff --git a/Documentation/devicetree/bindings/mfd/motorola-cpcap.txt b/Documentation/devicetree/bindings/mfd/motorola-cpcap.txt index 5ddcc8f4febc..b52e7a33f0f9 100644 --- a/Documentation/devicetree/bindings/mfd/motorola-cpcap.txt +++ b/Documentation/devicetree/bindings/mfd/motorola-cpcap.txt @@ -16,14 +16,14 @@ Optional subnodes: The sub-functions of CPCAP get their own node with their own compatible values, which are described in the following files: -- ../power/supply/cpcap-battery.txt -- ../power/supply/cpcap-charger.txt -- ../regulator/cpcap-regulator.txt -- ../phy/phy-cpcap-usb.txt -- ../input/cpcap-pwrbutton.txt -- ../rtc/cpcap-rtc.txt -- ../leds/leds-cpcap.txt -- ../iio/adc/cpcap-adc.txt +- Documentation/devicetree/bindings/power/supply/cpcap-battery.txt +- Documentation/devicetree/bindings/power/supply/cpcap-charger.txt +- Documentation/devicetree/bindings/regulator/cpcap-regulator.txt +- Documentation/devicetree/bindings/phy/phy-cpcap-usb.txt +- Documentation/devicetree/bindings/input/cpcap-pwrbutton.txt +- Documentation/devicetree/bindings/rtc/cpcap-rtc.txt +- Documentation/devicetree/bindings/leds/leds-cpcap.txt +- Documentation/devicetree/bindings/iio/adc/motorola,cpcap-adc.yaml The only exception is the audio codec. Instead of a compatible value its node must be named "audio-codec". diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index d0e422f4b3e0..678b39952502 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -143,6 +143,13 @@ patternProperties: Ready/Busy pins. Active state refers to the NAND ready state and should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted. + secure-regions: + $ref: /schemas/types.yaml#/definitions/uint64-matrix + description: + Regions in the NAND chip which are protected using a secure element + like Trustzone. This property contains the start address and size of + the secure regions present. + required: - reg diff --git a/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml new file mode 100644 index 000000000000..99249cdfbfb3 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/linksys,ns-partitions.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/linksys,ns-partitions.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Linksys Northstar partitioning + +description: | + Linksys devices based on Broadcom Northstar architecture often use two + firmware partitions. One is used for regular booting, the other is treated as + fallback. + + This binding allows defining all fixed partitions and marking those containing + firmware. System can use that information e.g. for booting or flashing + purposes. + +maintainers: + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +properties: + compatible: + const: linksys,ns-partitions + + "#address-cells": + enum: [ 1, 2 ] + + "#size-cells": + enum: [ 1, 2 ] + +patternProperties: + "^partition@[0-9a-f]+$": + $ref: "partition.yaml#" + properties: + compatible: + items: + - const: linksys,ns-firmware + - const: brcm,trx + unevaluatedProperties: false + +required: + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + partitions { + compatible = "linksys,ns-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "boot"; + reg = <0x0 0x100000>; + read-only; + }; + + partition@100000 { + label = "nvram"; + reg = <0x100000 0x100000>; + }; + + partition@200000 { + compatible = "linksys,ns-firmware", "brcm,trx"; + reg = <0x200000 0xf00000>; + }; + + partition@1100000 { + compatible = "linksys,ns-firmware", "brcm,trx"; + reg = <0x1100000 0xf00000>; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml new file mode 100644 index 000000000000..5cdd2efa9132 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/partitions/nvmem-cells.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nvmem cells + +description: | + Any partition containing the compatible "nvmem-cells" will register as a + nvmem provider. + Each direct subnodes represents a nvmem cell following the nvmem binding. + Nvmem binding to declare nvmem-cells can be found in: + Documentation/devicetree/bindings/nvmem/nvmem.yaml + +maintainers: + - Ansuel Smith <ansuelsmth@gmail.com> + +allOf: + - $ref: /schemas/nvmem/nvmem.yaml# + +properties: + compatible: + const: nvmem-cells + +required: + - compatible + +additionalProperties: true + +examples: + - | + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + /* ... */ + + }; + art: art@1200000 { + compatible = "nvmem-cells"; + reg = <0x1200000 0x0140000>; + label = "art"; + read-only; + #address-cells = <1>; + #size-cells = <1>; + + macaddr_gmac1: macaddr_gmac1@0 { + reg = <0x0 0x6>; + }; + + macaddr_gmac2: macaddr_gmac2@6 { + reg = <0x6 0x6>; + }; + + pre_cal_24g: pre_cal_24g@1000 { + reg = <0x1000 0x2f20>; + }; + + pre_cal_5g: pre_cal_5g@5000{ + reg = <0x5000 0x2f20>; + }; + }; + - | + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "bootloader"; + reg = <0x000000 0x100000>; + read-only; + }; + + firmware@100000 { + compatible = "brcm,trx"; + label = "firmware"; + reg = <0x100000 0xe00000>; + }; + + calibration@f00000 { + compatible = "nvmem-cells"; + label = "calibration"; + reg = <0xf00000 0x100000>; + ranges = <0 0xf00000 0x100000>; + #address-cells = <1>; + #size-cells = <1>; + + wifi0@0 { + reg = <0x000000 0x080000>; + }; + + wifi1@80000 { + reg = <0x080000 0x080000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml new file mode 100644 index 000000000000..84ad7ff30121 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/qcom,nandc.yaml @@ -0,0 +1,196 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/qcom,nandc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm NAND controller + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +properties: + compatible: + enum: + - qcom,ipq806x-nand + - qcom,ipq4019-nand + - qcom,ipq6018-nand + - qcom,ipq8074-nand + - qcom,sdx55-nand + + reg: + maxItems: 1 + + clocks: + items: + - description: Core Clock + - description: Always ON Clock + + clock-names: + items: + - const: core + - const: aon + + "#address-cells": true + "#size-cells": true + +patternProperties: + "^nand@[a-f0-9]$": + type: object + properties: + nand-bus-width: + const: 8 + + nand-ecc-strength: + enum: [1, 4, 8] + + nand-ecc-step-size: + enum: + - 512 + +allOf: + - $ref: "nand-controller.yaml#" + + - if: + properties: + compatible: + contains: + const: qcom,ipq806x-nand + then: + properties: + dmas: + items: + - description: rxtx DMA channel + + dma-names: + items: + - const: rxtx + + qcom,cmd-crci: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Must contain the ADM command type CRCI block instance number + specified for the NAND controller on the given platform + + qcom,data-crci: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Must contain the ADM data type CRCI block instance number + specified for the NAND controller on the given platform + + - if: + properties: + compatible: + contains: + enum: + - qcom,ipq4019-nand + - qcom,ipq6018-nand + - qcom,ipq8074-nand + - qcom,sdx55-nand + + then: + properties: + dmas: + items: + - description: tx DMA channel + - description: rx DMA channel + - description: cmd DMA channel + + dma-names: + items: + - const: tx + - const: rx + - const: cmd + +required: + - compatible + - reg + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-ipq806x.h> + nand-controller@1ac00000 { + compatible = "qcom,ipq806x-nand"; + reg = <0x1ac00000 0x800>; + + clocks = <&gcc EBI2_CLK>, + <&gcc EBI2_AON_CLK>; + clock-names = "core", "aon"; + + dmas = <&adm_dma 3>; + dma-names = "rxtx"; + qcom,cmd-crci = <15>; + qcom,data-crci = <3>; + + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + + nand-ecc-strength = <4>; + nand-bus-width = <8>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "boot-nand"; + reg = <0 0x58a0000>; + }; + + partition@58a0000 { + label = "fs-nand"; + reg = <0x58a0000 0x4000000>; + }; + }; + }; + }; + + #include <dt-bindings/clock/qcom,gcc-ipq4019.h> + nand-controller@79b0000 { + compatible = "qcom,ipq4019-nand"; + reg = <0x79b0000 0x1000>; + + clocks = <&gcc GCC_QPIC_CLK>, + <&gcc GCC_QPIC_AHB_CLK>; + clock-names = "core", "aon"; + + dmas = <&qpicbam 0>, + <&qpicbam 1>, + <&qpicbam 2>; + dma-names = "tx", "rx", "cmd"; + + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-ecc-strength = <4>; + nand-bus-width = <8>; + + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; + + partition@0 { + label = "boot-nand"; + reg = <0 0x58a0000>; + }; + + partition@58a0000 { + label = "fs-nand"; + reg = <0x58a0000 0x4000000>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/mtd/qcom_nandc.txt b/Documentation/devicetree/bindings/mtd/qcom_nandc.txt deleted file mode 100644 index 5647913d8837..000000000000 --- a/Documentation/devicetree/bindings/mtd/qcom_nandc.txt +++ /dev/null @@ -1,142 +0,0 @@ -* Qualcomm NAND controller - -Required properties: -- compatible: must be one of the following: - * "qcom,ipq806x-nand" - for EBI2 NAND controller being used in IPQ806x - SoC and it uses ADM DMA - * "qcom,ipq4019-nand" - for QPIC NAND controller v1.4.0 being used in - IPQ4019 SoC and it uses BAM DMA - * "qcom,ipq6018-nand" - for QPIC NAND controller v1.5.0 being used in - IPQ6018 SoC and it uses BAM DMA - * "qcom,ipq8074-nand" - for QPIC NAND controller v1.5.0 being used in - IPQ8074 SoC and it uses BAM DMA - * "qcom,sdx55-nand" - for QPIC NAND controller v2.0.0 being used in - SDX55 SoC and it uses BAM DMA - -- reg: MMIO address range -- clocks: must contain core clock and always on clock -- clock-names: must contain "core" for the core clock and "aon" for the - always on clock - -EBI2 specific properties: -- dmas: DMA specifier, consisting of a phandle to the ADM DMA - controller node and the channel number to be used for - NAND. Refer to dma.txt and qcom_adm.txt for more details -- dma-names: must be "rxtx" -- qcom,cmd-crci: must contain the ADM command type CRCI block instance - number specified for the NAND controller on the given - platform -- qcom,data-crci: must contain the ADM data type CRCI block instance - number specified for the NAND controller on the given - platform - -QPIC specific properties: -- dmas: DMA specifier, consisting of a phandle to the BAM DMA - and the channel number to be used for NAND. Refer to - dma.txt, qcom_bam_dma.txt for more details -- dma-names: must contain all 3 channel names : "tx", "rx", "cmd" -- #address-cells: <1> - subnodes give the chip-select number -- #size-cells: <0> - -* NAND chip-select - -Each controller may contain one or more subnodes to represent enabled -chip-selects which (may) contain NAND flash chips. Their properties are as -follows. - -Required properties: -- reg: a single integer representing the chip-select - number (e.g., 0, 1, 2, etc.) -- #address-cells: see partition.txt -- #size-cells: see partition.txt - -Optional properties: -- nand-bus-width: see nand-controller.yaml -- nand-ecc-strength: see nand-controller.yaml. If not specified, then ECC strength will - be used according to chip requirement and available - OOB size. - -Each nandcs device node may optionally contain a 'partitions' sub-node, which -further contains sub-nodes describing the flash partition mapping. See -partition.txt for more detail. - -Example: - -nand-controller@1ac00000 { - compatible = "qcom,ipq806x-nand"; - reg = <0x1ac00000 0x800>; - - clocks = <&gcc EBI2_CLK>, - <&gcc EBI2_AON_CLK>; - clock-names = "core", "aon"; - - dmas = <&adm_dma 3>; - dma-names = "rxtx"; - qcom,cmd-crci = <15>; - qcom,data-crci = <3>; - - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - - nand-ecc-strength = <4>; - nand-bus-width = <8>; - - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - partition@0 { - label = "boot-nand"; - reg = <0 0x58a0000>; - }; - - partition@58a0000 { - label = "fs-nand"; - reg = <0x58a0000 0x4000000>; - }; - }; - }; -}; - -nand-controller@79b0000 { - compatible = "qcom,ipq4019-nand"; - reg = <0x79b0000 0x1000>; - - clocks = <&gcc GCC_QPIC_CLK>, - <&gcc GCC_QPIC_AHB_CLK>; - clock-names = "core", "aon"; - - dmas = <&qpicbam 0>, - <&qpicbam 1>, - <&qpicbam 2>; - dma-names = "tx", "rx", "cmd"; - - #address-cells = <1>; - #size-cells = <0>; - - nand@0 { - reg = <0>; - nand-ecc-strength = <4>; - nand-bus-width = <8>; - - partitions { - compatible = "fixed-partitions"; - #address-cells = <1>; - #size-cells = <1>; - - partition@0 { - label = "boot-nand"; - reg = <0 0x58a0000>; - }; - - partition@58a0000 { - label = "fs-nand"; - reg = <0x58a0000 0x4000000>; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml b/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml index 79c38ea14237..13c26f23a820 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml +++ b/Documentation/devicetree/bindings/net/brcm,bcm4908-enet.yaml @@ -32,7 +32,7 @@ required: - interrupts - interrupt-names -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml index 4b7d1e5d003c..e8f04687a3e0 100644 --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -49,7 +49,7 @@ properties: description: Reference to an nvmem node for the MAC address - nvmem-cells-names: + nvmem-cell-names: const: mac-address phy-connection-type: diff --git a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt index b921731cd970..df9e844dd6bc 100644 --- a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt +++ b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt @@ -65,6 +65,71 @@ KSZ9031: step is 60ps. The default value is the neutral setting, so setting rxc-skew-ps=<0> actually results in -900 picoseconds adjustment. + The KSZ9031 hardware supports a range of skew values from negative to + positive, where the specific range is property dependent. All values + specified in the devicetree are offset by the minimum value so they + can be represented as positive integers in the devicetree since it's + difficult to represent a negative number in the devictree. + + The following 5-bit values table apply to rxc-skew-ps and txc-skew-ps. + + Pad Skew Value Delay (ps) Devicetree Value + ------------------------------------------------------ + 0_0000 -900ps 0 + 0_0001 -840ps 60 + 0_0010 -780ps 120 + 0_0011 -720ps 180 + 0_0100 -660ps 240 + 0_0101 -600ps 300 + 0_0110 -540ps 360 + 0_0111 -480ps 420 + 0_1000 -420ps 480 + 0_1001 -360ps 540 + 0_1010 -300ps 600 + 0_1011 -240ps 660 + 0_1100 -180ps 720 + 0_1101 -120ps 780 + 0_1110 -60ps 840 + 0_1111 0ps 900 + 1_0000 60ps 960 + 1_0001 120ps 1020 + 1_0010 180ps 1080 + 1_0011 240ps 1140 + 1_0100 300ps 1200 + 1_0101 360ps 1260 + 1_0110 420ps 1320 + 1_0111 480ps 1380 + 1_1000 540ps 1440 + 1_1001 600ps 1500 + 1_1010 660ps 1560 + 1_1011 720ps 1620 + 1_1100 780ps 1680 + 1_1101 840ps 1740 + 1_1110 900ps 1800 + 1_1111 960ps 1860 + + The following 4-bit values table apply to the txdX-skew-ps, rxdX-skew-ps + data pads, and the rxdv-skew-ps, txen-skew-ps control pads. + + Pad Skew Value Delay (ps) Devicetree Value + ------------------------------------------------------ + 0000 -420ps 0 + 0001 -360ps 60 + 0010 -300ps 120 + 0011 -240ps 180 + 0100 -180ps 240 + 0101 -120ps 300 + 0110 -60ps 360 + 0111 0ps 420 + 1000 60ps 480 + 1001 120ps 540 + 1010 180ps 600 + 1011 240ps 660 + 1100 300ps 720 + 1101 360ps 780 + 1110 420ps 840 + 1111 480ps 900 + Optional properties: Maximum value of 1860, default value 900: @@ -120,11 +185,21 @@ KSZ9131: Examples: + /* Attach to an Ethernet device with autodetected PHY */ + &enet { + rxc-skew-ps = <1800>; + rxdv-skew-ps = <0>; + txc-skew-ps = <1800>; + txen-skew-ps = <0>; + status = "okay"; + }; + + /* Attach to an explicitly-specified PHY */ mdio { phy0: ethernet-phy@0 { - rxc-skew-ps = <3000>; + rxc-skew-ps = <1800>; rxdv-skew-ps = <0>; - txc-skew-ps = <3000>; + txc-skew-ps = <1800>; txen-skew-ps = <0>; reg = <0>; }; @@ -133,3 +208,20 @@ Examples: phy = <&phy0>; phy-mode = "rgmii-id"; }; + +References + + Micrel ksz9021rl/rn Data Sheet, Revision 1.2. Dated 2/13/2014. + http://www.micrel.com/_PDF/Ethernet/datasheets/ksz9021rl-rn_ds.pdf + + Micrel ksz9031rnx Data Sheet, Revision 2.1. Dated 11/20/2014. + http://www.micrel.com/_PDF/Ethernet/datasheets/KSZ9031RNX.pdf + +Notes: + + Note that a previous version of the Micrel ksz9021rl/rn Data Sheet + was missing extended register 106 (transmit data pad skews), and + incorrectly specified the ps per step as 200ps/step instead of + 120ps/step. The latest update to this document reflects the latest + revision of the Micrel specification even though usage in the kernel + still reflects that incorrect document. diff --git a/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml b/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml new file mode 100644 index 000000000000..58ff6b0bdb1a --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/brcm,nvram.yaml @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/brcm,nvram.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom's NVRAM + +description: | + Broadcom's NVRAM is a structure containing device specific environment + variables. It is used for storing device configuration, booting parameters + and calibration data. + + NVRAM can be accessed on Broadcom BCM47xx MIPS and Northstar ARM Cortex-A9 + devices usiong I/O mapped memory. + +maintainers: + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +allOf: + - $ref: "nvmem.yaml#" + +properties: + compatible: + const: brcm,nvram + +unevaluatedProperties: false + +examples: + - | + nvram@1eff0000 { + compatible = "brcm,nvram"; + reg = <0x1eff0000 0x10000>; + }; diff --git a/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt index ef93c3b95424..d479ad977e24 100644 --- a/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt @@ -7,7 +7,9 @@ Required properties: "mediatek,mt7622-efuse", "mediatek,efuse": for MT7622 "mediatek,mt7623-efuse", "mediatek,efuse": for MT7623 "mediatek,mt8173-efuse" or "mediatek,efuse": for MT8173 + "mediatek,mt8192-efuse", "mediatek,efuse": for MT8192 "mediatek,mt8516-efuse", "mediatek,efuse": for MT8516 + "mediatek,mt8192-efuse", "mediatek,efuse": for MT8192 - reg: Should contain registers location and length = Data cells = diff --git a/Documentation/devicetree/bindings/nvmem/nvmem.yaml b/Documentation/devicetree/bindings/nvmem/nvmem.yaml index 7481a9e48f19..b8dc3d2b6e92 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem.yaml @@ -20,9 +20,6 @@ description: | storage device. properties: - $nodename: - pattern: "^(eeprom|efuse|nvram)(@.*|-[0-9a-f])*$" - "#address-cells": const: 1 diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml index 992777c90a0b..861b205016b1 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -24,6 +24,7 @@ properties: - qcom,msm8998-qfprom - qcom,qcs404-qfprom - qcom,sc7180-qfprom + - qcom,sc7280-qfprom - qcom,sdm845-qfprom - const: qcom,qfprom diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.txt b/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.txt deleted file mode 100644 index a7aee9ea8926..000000000000 --- a/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.txt +++ /dev/null @@ -1,21 +0,0 @@ -Driver for Broadcom Northstar USB 2.0 PHY - -Required properties: -- compatible: brcm,ns-usb2-phy -- reg: iomem address range of DMU (Device Management Unit) -- reg-names: "dmu", the only needed & supported reg right now -- clocks: USB PHY reference clock -- clock-names: "phy-ref-clk", the only needed & supported clock right now - -To initialize USB 2.0 PHY driver needs to setup PLL correctly. To do this it -requires passing phandle to the USB PHY reference clock. - -Example: - usb2-phy { - compatible = "brcm,ns-usb2-phy"; - reg = <0x1800c000 0x1000>; - reg-names = "dmu"; - #phy-cells = <0>; - clocks = <&genpll BCM_NSP_GENPLL_USB_PHY_REF_CLK>; - clock-names = "phy-ref-clk"; - }; diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.yaml b/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.yaml new file mode 100644 index 000000000000..05b4dcd80019 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/bcm-ns-usb2-phy.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/bcm-ns-usb2-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Northstar USB 2.0 PHY + +description: > + To initialize USB 2.0 PHY driver needs to setup PLL correctly. + To do this it requires passing phandle to the USB PHY reference clock. + +maintainers: + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +properties: + compatible: + const: brcm,ns-usb2-phy + + reg: + items: + - description: iomem address range of DMU (Device Management Unit) + + reg-names: + items: + - const: dmu + + clocks: + items: + - description: USB PHY reference clock + + clock-names: + items: + - const: phy-ref-clk + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - "#phy-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/bcm-nsp.h> + phy@1800c000 { + compatible = "brcm,ns-usb2-phy"; + reg = <0x1800c000 0x1000>; + reg-names = "dmu"; + clocks = <&genpll BCM_NSP_GENPLL_USB_PHY_REF_CLK>; + clock-names = "phy-ref-clk"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt deleted file mode 100644 index 32f057260351..000000000000 --- a/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt +++ /dev/null @@ -1,34 +0,0 @@ -Driver for Broadcom Northstar USB 3.0 PHY - -Required properties: - -- compatible: one of: "brcm,ns-ax-usb3-phy", "brcm,ns-bx-usb3-phy". -- reg: address of MDIO bus device -- usb3-dmp-syscon: phandle to syscon with DMP (Device Management Plugin) - registers -- #phy-cells: must be 0 - -Initialization of USB 3.0 PHY depends on Northstar version. There are currently -three known series: Ax, Bx and Cx. -Known A0: BCM4707 rev 0 -Known B0: BCM4707 rev 4, BCM53573 rev 2 -Known B1: BCM4707 rev 6 -Known C0: BCM47094 rev 0 - -Example: - mdio: mdio@0 { - reg = <0x0>; - #size-cells = <1>; - #address-cells = <0>; - - usb3-phy@10 { - compatible = "brcm,ns-ax-usb3-phy"; - reg = <0x10>; - usb3-dmp-syscon = <&usb3_dmp>; - #phy-cells = <0>; - }; - }; - - usb3_dmp: syscon@18105000 { - reg = <0x18105000 0x1000>; - }; diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.yaml b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.yaml new file mode 100644 index 000000000000..7fd419db45d0 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/bcm-ns-usb3-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom Northstar USB 3.0 PHY + +description: | + Initialization of USB 3.0 PHY depends on Northstar version. There are currently + three known series: Ax, Bx and Cx. + Known A0: BCM4707 rev 0 + Known B0: BCM4707 rev 4, BCM53573 rev 2 + Known B1: BCM4707 rev 6 + Known C0: BCM47094 rev 0 + +maintainers: + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +properties: + compatible: + enum: + - brcm,ns-ax-usb3-phy + - brcm,ns-bx-usb3-phy + + reg: + description: address of MDIO bus device + maxItems: 1 + + usb3-dmp-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the DMP (Device Management Plugin) syscon + + "#phy-cells": + const: 0 + +required: + - compatible + - reg + - usb3-dmp-syscon + - "#phy-cells" + +additionalProperties: false + +examples: + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + + usb3-phy@10 { + compatible = "brcm,ns-ax-usb3-phy"; + reg = <0x10>; + usb3-dmp-syscon = <&usb3_dmp>; + #phy-cells = <0>; + }; + }; + + usb3_dmp: syscon@18105000 { + reg = <0x18105000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml b/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml index 0497368d1fca..5f9e91bfb5ff 100644 --- a/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml +++ b/Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.yaml @@ -42,6 +42,9 @@ properties: - const: usb_mdio - const: bdc_ec + power-domains: + maxItems: 1 + clocks: minItems: 1 maxItems: 2 diff --git a/Documentation/devicetree/bindings/phy/marvell,armada-3700-utmi-phy.yaml b/Documentation/devicetree/bindings/phy/marvell,armada-3700-utmi-phy.yaml new file mode 100644 index 000000000000..2437c3683326 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/marvell,armada-3700-utmi-phy.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/marvell,armada-3700-utmi-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Marvell Armada UTMI/UTMI+ PHY + +maintainers: + - Miquel Raynal <miquel.raynal@bootlin.com> + +description: + On Armada 3700, there are two USB controllers, one is compatible with + the USB2 and USB3 specifications and supports OTG. The other one is USB2 + compliant and only supports host mode. Both of these controllers come with + a slightly different UTMI PHY. + +properties: + compatible: + enum: + - marvell,a3700-utmi-host-phy + - marvell,a3700-utmi-otg-phy + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + + marvell,usb-misc-reg: + description: + Phandle on the "USB miscellaneous registers" shared region + covering registers related to both the host controller and + the PHY. + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - reg + - "#phy-cells" + - marvell,usb-misc-reg + +additionalProperties: false + +examples: + - | + usb2_utmi_host_phy: phy@5f000 { + compatible = "marvell,armada-3700-utmi-host-phy"; + reg = <0x5f000 0x800>; + marvell,usb-misc-reg = <&usb2_syscon>; + #phy-cells = <0>; + }; + + usb2_syscon: system-controller@5f800 { + compatible = "marvell,armada-3700-usb2-host-misc", "syscon"; + reg = <0x5f800 0x800>; + }; diff --git a/Documentation/devicetree/bindings/phy/marvell,armada-cp110-utmi-phy.yaml b/Documentation/devicetree/bindings/phy/marvell,armada-cp110-utmi-phy.yaml new file mode 100644 index 000000000000..30f3b5f32a95 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/marvell,armada-cp110-utmi-phy.yaml @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + +%YAML 1.2 +--- +$id: "http://devicetree.org/schemas/phy/marvell,armada-cp110-utmi-phy.yaml#" +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: Marvell Armada CP110/CP115 UTMI PHY + +maintainers: + - Konstantin Porotchkin <kostap@marvell.com> + +description: + On Armada 7k/8k and CN913x, there are two host and one device USB controllers. + Each of two exiting UTMI PHYs could be connected to either USB host or USB device + controller. + The USB device controller can only be connected to a single UTMI PHY port + 0.H----- USB HOST0 + UTMI PHY0 --------/ + 0.D-----0 + \------ USB DEVICE + 1.D-----1 + UTMI PHY1 --------\ + 1.H----- USB HOST1 + +properties: + compatible: + const: marvell,cp110-utmi-phy + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + marvell,system-controller: + description: + Phandle to the system controller node + $ref: /schemas/types.yaml#/definitions/phandle + +#Required child nodes: + +patternProperties: + "^usb-phy@[0|1]$": + type: object + description: + Each UTMI PHY port must be represented as a sub-node. + + properties: + reg: + description: phy port index. + maxItems: 1 + + "#phy-cells": + const: 0 + + required: + - reg + - "#phy-cells" + + additionalProperties: false + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - marvell,system-controller + +additionalProperties: false + +examples: + - | + cp0_utmi: utmi@580000 { + compatible = "marvell,cp110-utmi-phy"; + reg = <0x580000 0x2000>; + marvell,system-controller = <&cp0_syscon0>; + #address-cells = <1>; + #size-cells = <0>; + + cp0_utmi0: usb-phy@0 { + reg = <0>; + #phy-cells = <0>; + }; + + cp0_utmi1: usb-phy@1 { + reg = <1>; + #phy-cells = <0>; + }; + }; + + cp0_usb3_0 { + usb-phy = <&cp0_usb3_0_phy0>; + phys = <&cp0_utmi0>; + phy-names = "utmi"; + /* UTMI0 is connected to USB host controller (default mode) */ + dr_mode = "host"; + }; + + cp0_usb3_1 { + usb-phy = <&cp0_usb3_0_phy1>; + phys = <&cp0_utmi1>; + phy-names = "utmi"; + /* UTMI1 is connected to USB device controller */ + dr_mode = "peripheral"; + }; diff --git a/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml index 71d4acea1f66..6e4d795f9b02 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml @@ -19,11 +19,14 @@ properties: pattern: "^dsi-phy@[0-9a-f]+$" compatible: - enum: - - mediatek,mt2701-mipi-tx - - mediatek,mt7623-mipi-tx - - mediatek,mt8173-mipi-tx - - mediatek,mt8183-mipi-tx + oneOf: + - items: + - enum: + - mediatek,mt7623-mipi-tx + - const: mediatek,mt2701-mipi-tx + - const: mediatek,mt2701-mipi-tx + - const: mediatek,mt8173-mipi-tx + - const: mediatek,mt8183-mipi-tx reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml index 4752517a1446..0d94950b84ca 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,hdmi-phy.yaml @@ -21,10 +21,13 @@ properties: pattern: "^hdmi-phy@[0-9a-f]+$" compatible: - enum: - - mediatek,mt2701-hdmi-phy - - mediatek,mt7623-hdmi-phy - - mediatek,mt8173-hdmi-phy + oneOf: + - items: + - enum: + - mediatek,mt7623-hdmi-phy + - const: mediatek,mt2701-hdmi-phy + - const: mediatek,mt2701-hdmi-phy + - const: mediatek,mt8173-hdmi-phy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml index 602e6ff45785..b8a7651a3d9a 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,tphy.yaml @@ -79,6 +79,7 @@ properties: - mediatek,mt2712-tphy - mediatek,mt7629-tphy - mediatek,mt8183-tphy + - mediatek,mt8195-tphy - const: mediatek,generic-tphy-v2 - const: mediatek,mt2701-u3phy deprecated: true @@ -117,7 +118,7 @@ properties: # Required child node: patternProperties: - "^usb-phy@[0-9a-f]+$": + "^(usb|pcie|sata)-phy@[0-9a-f]+$": type: object description: A sub-node is required for each port the controller provides. diff --git a/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml index 3a9be82e7f13..74cc32c1d2e8 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,ufs-phy.yaml @@ -22,7 +22,12 @@ properties: pattern: "^ufs-phy@[0-9a-f]+$" compatible: - const: mediatek,mt8183-ufsphy + oneOf: + - items: + - enum: + - mediatek,mt8195-ufsphy + - const: mediatek,mt8183-ufsphy + - const: mediatek,mt8183-ufsphy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/microchip,sparx5-serdes.yaml b/Documentation/devicetree/bindings/phy/microchip,sparx5-serdes.yaml new file mode 100644 index 000000000000..bdbdb3bbddbe --- /dev/null +++ b/Documentation/devicetree/bindings/phy/microchip,sparx5-serdes.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/microchip,sparx5-serdes.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip Sparx5 Serdes controller + +maintainers: + - Steen Hegelund <steen.hegelund@microchip.com> + +description: | + The Sparx5 SERDES interfaces share the same basic functionality, but + support different operating modes and line rates. + + The following list lists the SERDES features: + + * RX Adaptive Decision Feedback Equalizer (DFE) + * Programmable continuous time linear equalizer (CTLE) + * Rx variable gain control + * Rx built-in fault detector (loss-of-lock/loss-of-signal) + * Adjustable tx de-emphasis (FFE) + * Tx output amplitude control + * Supports rx eye monitor + * Multiple loopback modes + * Prbs generator and checker + * Polarity inversion control + + SERDES6G: + + The SERDES6G is a high-speed SERDES interface, which can operate at + the following data rates: + + * 100 Mbps (100BASE-FX) + * 1.25 Gbps (SGMII/1000BASE-X/1000BASE-KX) + * 3.125 Gbps (2.5GBASE-X/2.5GBASE-KX) + * 5.15625 Gbps (5GBASE-KR/5G-USXGMII) + + SERDES10G + + The SERDES10G is a high-speed SERDES interface, which can operate at + the following data rates: + + * 100 Mbps (100BASE-FX) + * 1.25 Gbps (SGMII/1000BASE-X/1000BASE-KX) + * 3.125 Gbps (2.5GBASE-X/2.5GBASE-KX) + * 5 Gbps (QSGMII/USGMII) + * 5.15625 Gbps (5GBASE-KR/5G-USXGMII) + * 10 Gbps (10G-USGMII) + * 10.3125 Gbps (10GBASE-R/10GBASE-KR/USXGMII) + + SERDES25G + + The SERDES25G is a high-speed SERDES interface, which can operate at + the following data rates: + + * 1.25 Gbps (SGMII/1000BASE-X/1000BASE-KX) + * 3.125 Gbps (2.5GBASE-X/2.5GBASE-KX) + * 5 Gbps (QSGMII/USGMII) + * 5.15625 Gbps (5GBASE-KR/5G-USXGMII) + * 10 Gbps (10G-USGMII) + * 10.3125 Gbps (10GBASE-R/10GBASE-KR/USXGMII) + * 25.78125 Gbps (25GBASE-KR/25GBASE-CR/25GBASE-SR/25GBASE-LR/25GBASE-ER) + +properties: + $nodename: + pattern: "^serdes@[0-9a-f]+$" + + compatible: + const: microchip,sparx5-serdes + + reg: + minItems: 1 + + '#phy-cells': + const: 1 + description: | + - The main serdes input port + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - '#phy-cells' + - clocks + +additionalProperties: false + +examples: + - | + serdes: serdes@10808000 { + compatible = "microchip,sparx5-serdes"; + #phy-cells = <1>; + clocks = <&sys_clk>; + reg = <0x10808000 0x5d0000>; + }; + +... diff --git a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt index 38c5fa21f435..b62397d2bb0c 100644 --- a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt @@ -54,6 +54,7 @@ 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. +- nvidia,pmc: phandle and specifier referring to the Tegra210 PMC node. For Tegra186: - avdd-pll-erefeut-supply: UPHY brick and reference clock as well as UTMI PHY diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml index d210843863df..84383e2e0b34 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml +++ b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.yaml @@ -26,6 +26,9 @@ properties: '#size-cells': const: 0 + '#clock-cells': + const: 1 + resets: minItems: 1 maxItems: 2 @@ -49,12 +52,24 @@ properties: const: serdes clocks: - maxItems: 2 + minItems: 2 + maxItems: 4 clock-names: + minItems: 2 items: - const: cmn_refclk_dig_div - const: cmn_refclk1_dig_div + - const: pll0_refclk + - const: pll1_refclk + + assigned-clocks: + minItems: 1 + maxItems: 2 + + assigned-clock-parents: + minItems: 1 + maxItems: 2 cdns,autoconf: type: boolean diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml index e266ade53d87..01dcd14e7b2a 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml +++ b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml @@ -28,13 +28,27 @@ properties: '#size-cells': const: 0 + '#clock-cells': + const: 1 + clocks: - maxItems: 1 + minItems: 1 + maxItems: 2 description: - PHY reference clock. Must contain an entry in clock-names. + PHY reference clock for 1 item. Must contain an entry in clock-names. + Optional Parent to enable output reference clock. clock-names: - const: refclk + minItems: 1 + items: + - const: refclk + - const: phy_en_refclk + + assigned-clocks: + maxItems: 3 + + assigned-clock-parents: + maxItems: 3 reg: minItems: 1 @@ -170,7 +184,7 @@ examples: }; - | #include <dt-bindings/phy/phy.h> - #include <dt-bindings/phy/phy-cadence-torrent.h> + #include <dt-bindings/phy/phy-cadence.h> bus { #address-cells = <2>; diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt b/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt deleted file mode 100644 index aa99ceec73b0..000000000000 --- a/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt +++ /dev/null @@ -1,38 +0,0 @@ -MVEBU A3700 UTMI PHY --------------------- - -USB2 UTMI+ PHY controllers can be found on the following Marvell MVEBU SoCs: -* Armada 3700 - -On Armada 3700, there are two USB controllers, one is compatible with the USB2 -and USB3 specifications and supports OTG. The other one is USB2 compliant and -only supports host mode. Both of these controllers come with a slightly -different UTMI PHY. - -Required Properties: - -- compatible: Should be one of: - * "marvell,a3700-utmi-host-phy" for the PHY connected to - the USB2 host-only controller. - * "marvell,a3700-utmi-otg-phy" for the PHY connected to - the USB3 and USB2 OTG capable controller. -- reg: PHY IP register range. -- marvell,usb-misc-reg: handle on the "USB miscellaneous registers" shared - region covering registers related to both the host - controller and the PHY. -- #phy-cells: Standard property (Documentation: phy-bindings.txt) Should be 0. - - -Example: - - usb2_utmi_host_phy: phy@5f000 { - compatible = "marvell,armada-3700-utmi-host-phy"; - reg = <0x5f000 0x800>; - marvell,usb-misc-reg = <&usb2_syscon>; - #phy-cells = <0>; - }; - - usb2_syscon: system-controller@5f800 { - compatible = "marvell,armada-3700-usb2-host-misc", "syscon"; - reg = <0x5f800 0x800>; - }; diff --git a/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml index 46df6786727a..018cc1246ee1 100644 --- a/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml +++ b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml @@ -51,6 +51,10 @@ properties: vdda1v8-supply: description: regulator providing 1V8 power supply to the PLL block + '#clock-cells': + description: number of clock cells for ck_usbo_48m consumer + const: 0 + #Required child nodes: patternProperties: @@ -120,6 +124,7 @@ examples: vdda1v8-supply = <®18>; #address-cells = <1>; #size-cells = <0>; + #clock-cells = <0>; usbphyc_port0: usb-phy@0 { reg = <0>; diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml index 626447fee092..7808ec8bc712 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-phy.yaml @@ -25,11 +25,13 @@ properties: - qcom,msm8998-qmp-pcie-phy - qcom,msm8998-qmp-ufs-phy - qcom,msm8998-qmp-usb3-phy + - qcom,sc7180-qmp-usb3-phy - qcom,sc8180x-qmp-ufs-phy - qcom,sc8180x-qmp-usb3-phy - qcom,sdm845-qhp-pcie-phy - qcom,sdm845-qmp-pcie-phy - qcom,sdm845-qmp-ufs-phy + - qcom,sdm845-qmp-usb3-phy - qcom,sdm845-qmp-usb3-uni-phy - qcom,sm8150-qmp-ufs-phy - qcom,sm8150-qmp-usb3-phy diff --git a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml index 33974ad10afe..217aa6c91893 100644 --- a/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,qmp-usb3-dp-phy.yaml @@ -14,9 +14,8 @@ properties: compatible: enum: - qcom,sc7180-qmp-usb3-dp-phy - - qcom,sc7180-qmp-usb3-phy - qcom,sdm845-qmp-usb3-dp-phy - - qcom,sdm845-qmp-usb3-phy + - qcom,sm8250-qmp-usb3-dp-phy reg: items: - description: Address and length of PHY's USB serdes block. diff --git a/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml b/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml index ee77c6458326..20203a8a9e41 100644 --- a/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,usb-snps-femto-v2.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - qcom,usb-snps-hs-7nm-phy + - qcom,sc7280-usb-hs-phy - qcom,sm8150-usb-hs-phy - qcom,sm8250-usb-hs-phy - qcom,sm8350-usb-hs-phy diff --git a/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml index bbbd85501ada..57e1d013a502 100644 --- a/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml +++ b/Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml @@ -15,6 +15,7 @@ properties: enum: - ti,j721e-wiz-16g - ti,j721e-wiz-10g + - ti,am64-wiz-10g power-domains: maxItems: 1 @@ -42,6 +43,9 @@ properties: "#reset-cells": const: 1 + "#clock-cells": + const: 1 + ranges: true assigned-clocks: diff --git a/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml b/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml index 40b08d83c80b..f8e7ddbd2705 100644 --- a/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml +++ b/Documentation/devicetree/bindings/power/brcm,bcm-pmb.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - brcm,bcm4908-pmb + - brcm,bcm63138-pmb reg: description: register space of one or more buses diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index 1ea21acbbd55..ff21bfef8204 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -25,10 +25,12 @@ properties: - qcom,qcs404-rpmpd - qcom,sdm660-rpmpd - qcom,sc7180-rpmhpd + - qcom,sc7280-rpmhpd - qcom,sdm845-rpmhpd - qcom,sdx55-rpmhpd - qcom,sm8150-rpmhpd - qcom,sm8250-rpmhpd + - qcom,sm8350-rpmhpd '#power-domain-cells': const: 1 diff --git a/Documentation/devicetree/bindings/regulator/fan53555.txt b/Documentation/devicetree/bindings/regulator/fan53555.txt index e7fc045281d1..013f096ac0aa 100644 --- a/Documentation/devicetree/bindings/regulator/fan53555.txt +++ b/Documentation/devicetree/bindings/regulator/fan53555.txt @@ -1,8 +1,8 @@ Binding for Fairchild FAN53555 regulators Required properties: - - compatible: one of "fcs,fan53555", "fcs,fan53526", "silergy,syr827" or - "silergy,syr828" + - compatible: one of "fcs,fan53555", "fcs,fan53526", "silergy,syr827", + "silergy,syr828" or "tcs,tcs4525". - reg: I2C address Optional properties: diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt deleted file mode 100644 index ce1e04354006..000000000000 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.txt +++ /dev/null @@ -1,180 +0,0 @@ -Qualcomm Technologies, Inc. RPMh Regulators - -rpmh-regulator devices support PMIC regulator management via the Voltage -Regulator Manager (VRM) and Oscillator Buffer (XOB) RPMh accelerators. The APPS -processor communicates with these hardware blocks via a Resource State -Coordinator (RSC) using command packets. The VRM allows changing three -parameters for a given regulator: enable state, output voltage, and operating -mode. The XOB allows changing only a single parameter for a given regulator: -its enable state. Despite its name, the XOB is capable of controlling the -enable state of any PMIC peripheral. It is used for clock buffers, low-voltage -switches, and LDO/SMPS regulators which have a fixed voltage and mode. - -======================= -Required Node Structure -======================= - -RPMh regulators must be described in two levels of device nodes. The first -level describes the PMIC containing the regulators and must reside within an -RPMh device node. The second level describes each regulator within the PMIC -which is to be used on the board. Each of these regulators maps to a single -RPMh resource. - -The names used for regulator nodes must match those supported by a given PMIC. -Supported regulator node names: - PM8005: smps1 - smps4 - PM8009: smps1 - smps2, ldo1 - ldo7 - PM8150: smps1 - smps10, ldo1 - ldo18 - PM8150L: smps1 - smps8, ldo1 - ldo11, bob, flash, rgb - PM8350: smps1 - smps12, ldo1 - ldo10, - PM8350C: smps1 - smps10, ldo1 - ldo13, bob - PM8998: smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 - PMI8998: bob - PM6150: smps1 - smps5, ldo1 - ldo19 - PM6150L: smps1 - smps8, ldo1 - ldo11, bob - PMX55: smps1 - smps7, ldo1 - ldo16 - -======================== -First Level Nodes - PMIC -======================== - -- compatible - Usage: required - Value type: <string> - Definition: Must be one of below: - "qcom,pm8005-rpmh-regulators" - "qcom,pm8009-rpmh-regulators" - "qcom,pm8009-1-rpmh-regulators" - "qcom,pm8150-rpmh-regulators" - "qcom,pm8150l-rpmh-regulators" - "qcom,pm8350-rpmh-regulators" - "qcom,pm8350c-rpmh-regulators" - "qcom,pm8998-rpmh-regulators" - "qcom,pmc8180-rpmh-regulators" - "qcom,pmc8180c-rpmh-regulators" - "qcom,pmi8998-rpmh-regulators" - "qcom,pm6150-rpmh-regulators" - "qcom,pm6150l-rpmh-regulators" - "qcom,pmx55-rpmh-regulators" - -- qcom,pmic-id - Usage: required - Value type: <string> - Definition: RPMh resource name suffix used for the regulators found on - this PMIC. Typical values: "a", "b", "c", "d", "e", "f". - -- vdd-s1-supply -- vdd-s2-supply -- vdd-s3-supply -- vdd-s4-supply - Usage: optional (PM8998 and PM8005 only) - Value type: <phandle> - Definition: phandle of the parent supply regulator of one or more of the - regulators for this PMIC. - -- vdd-s5-supply -- vdd-s6-supply -- vdd-s7-supply -- vdd-s8-supply -- vdd-s9-supply -- vdd-s10-supply -- vdd-s11-supply -- vdd-s12-supply -- vdd-s13-supply -- vdd-l1-l27-supply -- vdd-l2-l8-l17-supply -- vdd-l3-l11-supply -- vdd-l4-l5-supply -- vdd-l6-supply -- vdd-l7-l12-l14-l15-supply -- vdd-l9-supply -- vdd-l10-l23-l25-supply -- vdd-l13-l19-l21-supply -- vdd-l16-l28-supply -- vdd-l18-l22-supply -- vdd-l20-l24-supply -- vdd-l26-supply -- vin-lvs-1-2-supply - Usage: optional (PM8998 only) - Value type: <phandle> - Definition: phandle of the parent supply regulator of one or more of the - regulators for this PMIC. - -- vdd-bob-supply - Usage: optional (PMI8998 only) - Value type: <phandle> - Definition: BOB regulator parent supply phandle - -=============================== -Second Level Nodes - Regulators -=============================== - -- qcom,always-wait-for-ack - Usage: optional - Value type: <empty> - Definition: Boolean flag which indicates that the application processor - must wait for an ACK or a NACK from RPMh for every request - sent for this regulator including those which are for a - strictly lower power state. - -Other properties defined in Documentation/devicetree/bindings/regulator/regulator.txt -may also be used. regulator-initial-mode and regulator-allowed-modes may be -specified for VRM regulators using mode values from -include/dt-bindings/regulator/qcom,rpmh-regulator.h. regulator-allow-bypass -may be specified for BOB type regulators managed via VRM. -regulator-allow-set-load may be specified for LDO type regulators managed via -VRM. - -======== -Examples -======== - -#include <dt-bindings/regulator/qcom,rpmh-regulator.h> - -&apps_rsc { - pm8998-rpmh-regulators { - compatible = "qcom,pm8998-rpmh-regulators"; - qcom,pmic-id = "a"; - - vdd-l7-l12-l14-l15-supply = <&pm8998_s5>; - - smps2 { - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - }; - - pm8998_s5: smps5 { - regulator-min-microvolt = <1904000>; - regulator-max-microvolt = <2040000>; - }; - - ldo7 { - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-initial-mode = <RPMH_REGULATOR_MODE_HPM>; - regulator-allowed-modes = - <RPMH_REGULATOR_MODE_LPM - RPMH_REGULATOR_MODE_HPM>; - regulator-allow-set-load; - }; - - lvs1 { - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - }; - }; - - pmi8998-rpmh-regulators { - compatible = "qcom,pmi8998-rpmh-regulators"; - qcom,pmic-id = "b"; - - bob { - regulator-min-microvolt = <3312000>; - regulator-max-microvolt = <3600000>; - regulator-allowed-modes = - <RPMH_REGULATOR_MODE_AUTO - RPMH_REGULATOR_MODE_HPM>; - regulator-initial-mode = <RPMH_REGULATOR_MODE_AUTO>; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml new file mode 100644 index 000000000000..e561a5b941e4 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -0,0 +1,162 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/qcom,rpmh-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. RPMh Regulators + +maintainers: + - David Collins <collinsd@codeaurora.org> + +description: | + rpmh-regulator devices support PMIC regulator management via the Voltage + Regulator Manager (VRM) and Oscillator Buffer (XOB) RPMh accelerators. + The APPS processor communicates with these hardware blocks via a + Resource State Coordinator (RSC) using command packets. The VRM allows + changing three parameters for a given regulator, enable state, output + voltage, and operating mode. The XOB allows changing only a single + parameter for a given regulator, its enable state. Despite its name, + the XOB is capable of controlling the enable state of any PMIC peripheral. + It is used for clock buffers, low-voltage switches, and LDO/SMPS regulators + which have a fixed voltage and mode. + + ======================= + Required Node Structure + ======================= + + RPMh regulators must be described in two levels of device nodes. The first + level describes the PMIC containing the regulators and must reside within an + RPMh device node. The second level describes each regulator within the PMIC + which is to be used on the board. Each of these regulators maps to a single + RPMh resource. + + The names used for regulator nodes must match those supported by a given + PMIC. Supported regulator node names are + For PM8005, smps1 - smps4 + For PM8009, smps1 - smps2, ldo1 - ldo7 + For PM8150, smps1 - smps10, ldo1 - ldo18 + For PM8150L, smps1 - smps8, ldo1 - ldo11, bob, flash, rgb + For PM8350, smps1 - smps12, ldo1 - ldo10 + For PM8350C, smps1 - smps10, ldo1 - ldo13, bob + For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 + For PMI8998, bob + For PM6150, smps1 - smps5, ldo1 - ldo19 + For PM6150L, smps1 - smps8, ldo1 - ldo11, bob + For PMX55, smps1 - smps7, ldo1 - ldo16 + For PM7325, smps1 - smps8, ldo1 - ldo19 + For PMR735A, smps1 - smps3, ldo1 - ldo7 + +properties: + compatible: + enum: + - qcom,pm8005-rpmh-regulators + - qcom,pm8009-rpmh-regulators + - qcom,pm8009-1-rpmh-regulators + - qcom,pm8150-rpmh-regulators + - qcom,pm8150l-rpmh-regulators + - qcom,pm8350-rpmh-regulators + - qcom,pm8350c-rpmh-regulators + - qcom,pm8998-rpmh-regulators + - qcom,pmi8998-rpmh-regulators + - qcom,pm6150-rpmh-regulators + - qcom,pm6150l-rpmh-regulators + - qcom,pmx55-rpmh-regulators + - qcom,pm7325-rpmh-regulators + - qcom,pmr735a-rpmh-regulators + + qcom,pmic-id: + description: | + RPMh resource name suffix used for the regulators found + on this PMIC. + $ref: /schemas/types.yaml#/definitions/string + enum: [a, b, c, d, e, f] + + qcom,always-wait-for-ack: + description: | + Boolean flag which indicates that the application processor + must wait for an ACK or a NACK from RPMh for every request + sent for this regulator including those which are for a + strictly lower power state. + $ref: /schemas/types.yaml#/definitions/flag + + vdd-flash-supply: + description: Input supply phandle of flash. + + vdd-rgb-supply: + description: Input supply phandle of rgb. + + vin-lvs-1-2-supply: + description: Input supply phandle of one or more regulators. + + vdd-bob-supply: + description: BOB regulator parent supply phandle. + + bob: + type: object + $ref: "regulator.yaml#" + description: BOB regulator node. + +patternProperties: + "^vdd-s([0-9]+)-supply$": + description: Input supply phandle(s) of one or more regulators. + + "^vdd-(l[0-9]+[-]){1,5}supply$": + description: Input supply phandle(s) of one or more regulators. + + "^(smps|ldo|lvs)[0-9]+$": + type: object + $ref: "regulator.yaml#" + description: smps/ldo regulator nodes(s). + +additionalProperties: false + +required: + - compatible + - qcom,pmic-id + +examples: + - | + #include <dt-bindings/regulator/qcom,rpmh-regulator.h> + + pm8998-rpmh-regulators { + compatible = "qcom,pm8998-rpmh-regulators"; + qcom,pmic-id = "a"; + + vdd-l7-l12-l14-l15-supply = <&pm8998_s5>; + + smps2 { + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + }; + + ldo7 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-initial-mode = <RPMH_REGULATOR_MODE_HPM>; + regulator-allowed-modes = + <RPMH_REGULATOR_MODE_LPM + RPMH_REGULATOR_MODE_HPM>; + regulator-allow-set-load; + }; + + lvs1 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + }; + + pmi8998-rpmh-regulators { + compatible = "qcom,pmi8998-rpmh-regulators"; + qcom,pmic-id = "b"; + + bob { + regulator-min-microvolt = <3312000>; + regulator-max-microvolt = <3600000>; + regulator-allowed-modes = + <RPMH_REGULATOR_MODE_AUTO + RPMH_REGULATOR_MODE_HPM>; + regulator-initial-mode = <RPMH_REGULATOR_MODE_AUTO>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/reserved-memory/ramoops.txt b/Documentation/devicetree/bindings/reserved-memory/ramoops.txt index b7886fea368c..b571ef6dab0f 100644 --- a/Documentation/devicetree/bindings/reserved-memory/ramoops.txt +++ b/Documentation/devicetree/bindings/reserved-memory/ramoops.txt @@ -42,8 +42,14 @@ Optional properties: - pmsg-size: size in bytes of log buffer reserved for userspace messages (defaults to 0: disabled) -- unbuffered: if present, use unbuffered mappings to map the reserved region - (defaults to buffered mappings) +- mem-type: if present, sets the type of mapping is to be used to map the + reserved region. mem-type: 0 = write-combined (default), 1 = unbuffered, + 2 = cached. + +- unbuffered: deprecated, use mem_type instead. If present, and mem_type is + not specified, it is equivalent to mem_type = 1 and uses unbuffered mappings + to map the reserved region (defaults to buffered mappings mem_type = 0). If + both are specified -- "mem_type" overrides "unbuffered". - max-reason: if present, sets maximum type of kmsg dump reasons to store (defaults to 2: log Oopses and Panics). This can be set to INT_MAX to diff --git a/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml b/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml index c147900f9041..6da674666d45 100644 --- a/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml +++ b/Documentation/devicetree/bindings/rng/brcm,bcm2835.yaml @@ -28,6 +28,12 @@ properties: clock-names: const: ipsec + resets: + maxItems: 1 + + reset-names: + const: ipsec + interrupts: maxItems: 1 @@ -35,6 +41,18 @@ required: - compatible - reg +if: + properties: + compatible: + enum: + - brcm,bcm6368-rng +then: + required: + - clocks + - clock-names + - resets + - reset-names + additionalProperties: false examples: @@ -58,4 +76,7 @@ examples: clocks = <&periph_clk 18>; clock-names = "ipsec"; + + resets = <&periph_rst 4>; + reset-names = "ipsec"; }; diff --git a/Documentation/devicetree/bindings/serial/8250.yaml b/Documentation/devicetree/bindings/serial/8250.yaml index f54cae9ff7b2..f0506a917793 100644 --- a/Documentation/devicetree/bindings/serial/8250.yaml +++ b/Documentation/devicetree/bindings/serial/8250.yaml @@ -12,8 +12,13 @@ maintainers: allOf: - $ref: /schemas/serial.yaml# - if: - required: - - aspeed,sirq-polarity-sense + anyOf: + - required: + - aspeed,lpc-io-reg + - required: + - aspeed,lpc-interrupts + - required: + - aspeed,sirq-polarity-sense then: properties: compatible: @@ -55,6 +60,7 @@ properties: - const: aspeed,ast2500-vuart - const: intel,xscale-uart - const: mrvl,pxa-uart + - const: nuvoton,wpcm450-uart - const: nuvoton,npcm750-uart - const: nvidia,tegra20-uart - const: nxp,lpc3220-uart @@ -165,7 +171,6 @@ properties: property. tx-threshold: - $ref: /schemas/types.yaml#/definitions/uint32 description: | Specify the TX FIFO low water indication for parts with programmable TX FIFO thresholds. @@ -188,6 +193,21 @@ properties: offset and bit number to identify how the SIRQ polarity should be configured. One possible data source is the LPC/eSPI mode bit. Only applicable to aspeed,ast2500-vuart. + deprecated: true + + aspeed,lpc-io-reg: + $ref: '/schemas/types.yaml#/definitions/uint32' + description: | + The VUART LPC address. Only applicable to aspeed,ast2500-vuart. + + aspeed,lpc-interrupts: + $ref: "/schemas/types.yaml#/definitions/uint32-array" + minItems: 2 + maxItems: 2 + description: | + A 2-cell property describing the VUART SIRQ number and SIRQ + polarity (IRQ_TYPE_LEVEL_LOW or IRQ_TYPE_LEVEL_HIGH). Only + applicable to aspeed,ast2500-vuart. required: - reg @@ -220,6 +240,7 @@ examples: }; - | #include <dt-bindings/clock/aspeed-clock.h> + #include <dt-bindings/interrupt-controller/irq.h> serial@1e787000 { compatible = "aspeed,ast2500-vuart"; reg = <0x1e787000 0x40>; @@ -227,7 +248,8 @@ examples: interrupts = <8>; clocks = <&syscon ASPEED_CLK_APB>; no-loopback-test; - aspeed,sirq-polarity-sense = <&syscon 0x70 25>; + aspeed,lpc-io-reg = <0x3f8>; + aspeed,lpc-interrupts = <4 IRQ_TYPE_LEVEL_LOW>; }; ... diff --git a/Documentation/devicetree/bindings/serial/brcm,bcm7271-uart.yaml b/Documentation/devicetree/bindings/serial/brcm,bcm7271-uart.yaml new file mode 100644 index 000000000000..46c62745f901 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/brcm,bcm7271-uart.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/brcm,bcm7271-uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom 8250 based serial port devicetree bindings + +maintainers: + - Al Cooper <alcooperx@gmail.com> + +allOf: + - $ref: /schemas/serial.yaml# + +description: |+ + The Broadcom UART is based on the basic 8250 UART but with + enhancements for more accurate high speed baud rates and support + for DMA. + +properties: + compatible: + items: + - enum: + - brcm,bcm7271-uart + - brcm,bcm7278-uart + + reg: + minItems: 1 + maxItems: 5 + + reg-names: + description: The UART register block and optionally the DMA register blocks. + oneOf: + - items: + - const: uart + - items: + - const: uart + - const: dma_arb + - const: dma_rx + - const: dma_tx + - const: dma_intr2 + + clocks: + minItems: 1 + + clock-names: + const: sw_baud + + interrupts: + minItems: 1 + maxItems: 2 + + interrupt-names: + description: The UART interrupt and optionally the DMA interrupt. + minItems: 1 + items: + - const: uart + - const: dma + +required: + - compatible + - reg + - reg-names + - clocks + - clock-names + - interrupts + - interrupt-names + +unevaluatedProperties: false + +examples: + - | + serial@840d000 { + compatible = "brcm,bcm7271-uart"; + reg = <0x840d000 0x20>; + reg-names = "uart"; + interrupts = <0x0 0x62 0x4>; + interrupt-names = "uart"; + clocks = <&scmi_clk 190>; + clock-names = "sw_baud"; + }; + + serial@840e000 { + compatible = "brcm,bcm7271-uart"; + reg = <0x840e000 0x20>, + <0x840e080 0x8>, + <0x840e100 0xa8>, + <0x840e200 0x4c>, + <0x840e300 0x30>; + reg-names = "uart", "dma_arb", "dma_rx", "dma_tx", "dma_intr2"; + interrupts = <0x0 0x62 0x4>, <0x0 0x75 0x4>; + interrupt-names = "uart", "dma"; + clocks = <&scmi_clk 190>; + clock-names = "sw_baud"; + }; diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt index 647b5aee86f3..64c4fb59acd1 100644 --- a/Documentation/devicetree/bindings/serial/mtk-uart.txt +++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt @@ -20,6 +20,7 @@ Required properties: * "mediatek,mt8173-uart" for MT8173 compatible UARTS * "mediatek,mt8183-uart", "mediatek,mt6577-uart" for MT8183 compatible UARTS * "mediatek,mt8192-uart", "mediatek,mt6577-uart" for MT8192 compatible UARTS + * "mediatek,mt8195-uart", "mediatek,mt6577-uart" for MT8195 compatible UARTS * "mediatek,mt8516-uart" for MT8516 compatible UARTS * "mediatek,mt6577-uart" for MT6577 and all of the above diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml index 21ee627b2ced..97ec8a093bf3 100644 --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/serial/samsung_uart.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Samsung S3C, S5P and Exynos SoC UART Controller +title: Samsung S3C, S5P, Exynos, and S5L (Apple SoC) SoC UART Controller maintainers: - Krzysztof Kozlowski <krzk@kernel.org> @@ -19,6 +19,7 @@ properties: compatible: items: - enum: + - apple,s5l-uart - samsung,s3c2410-uart - samsung,s3c2412-uart - samsung,s3c2440-uart @@ -51,6 +52,16 @@ properties: - pattern: '^clk_uart_baud[0-3]$' - pattern: '^clk_uart_baud[0-3]$' + dmas: + items: + - description: DMA controller phandle and request line for RX + - description: DMA controller phandle and request line for TX + + dma-names: + items: + - const: rx + - const: tx + interrupts: description: RX interrupt and optionally TX interrupt. minItems: 1 @@ -68,9 +79,11 @@ required: - interrupts - reg -additionalProperties: false +unevaluatedProperties: false allOf: + - $ref: /schemas/serial.yaml# + - if: properties: compatible: @@ -96,6 +109,7 @@ allOf: compatible: contains: enum: + - apple,s5l-uart - samsung,exynos4210-uart then: properties: diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml index 65e75d040521..f368d58e8086 100644 --- a/Documentation/devicetree/bindings/serial/serial.yaml +++ b/Documentation/devicetree/bindings/serial/serial.yaml @@ -75,6 +75,16 @@ properties: type: boolean description: CTS and RTS pins are swapped. + rx-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + RX FIFO threshold configuration (in bytes). + + tx-threshold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + TX FIFO threshold configuration (in bytes). + if: required: - uart-has-rtscts diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml index 8631678283f9..71a6426bc558 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml +++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml @@ -9,9 +9,6 @@ maintainers: title: STMicroelectronics STM32 USART bindings -allOf: - - $ref: rs485.yaml - properties: compatible: enum: @@ -40,6 +37,8 @@ properties: uart-has-rtscts: true + rx-tx-swap: true + dmas: minItems: 1 maxItems: 2 @@ -66,13 +65,46 @@ properties: linux,rs485-enabled-at-boot-time: true rs485-rx-during-tx: true -if: - required: - - st,hw-flow-ctrl -then: - properties: - cts-gpios: false - rts-gpios: false + rx-threshold: + description: + If value is set to 1, RX FIFO threshold is disabled. + enum: [1, 2, 4, 8, 12, 14, 16] + default: 8 + + tx-threshold: + description: + If value is set to 1, TX FIFO threshold is disabled. + enum: [1, 2, 4, 8, 12, 14, 16] + default: 8 + +allOf: + - $ref: rs485.yaml# + - $ref: serial.yaml# + - if: + required: + - st,hw-flow-ctrl + then: + properties: + cts-gpios: false + rts-gpios: false + - if: + properties: + compatible: + const: st,stm32-uart + then: + properties: + rx-tx-swap: false + - if: + properties: + compatible: + contains: + enum: + - st,stm32-uart + - st,stm32f7-uart + then: + properties: + rx-threshold: false + tx-threshold: false required: - compatible @@ -80,19 +112,22 @@ required: - interrupts - clocks -additionalProperties: false +additionalProperties: + type: object examples: - | #include <dt-bindings/clock/stm32mp1-clks.h> usart1: serial@40011000 { - compatible = "st,stm32-uart"; + compatible = "st,stm32h7-uart"; reg = <0x40011000 0x400>; interrupts = <37>; clocks = <&rcc 0 164>; dmas = <&dma2 2 4 0x414 0x0>, <&dma2 7 4 0x414 0x0>; dma-names = "rx", "tx"; + rx-threshold = <4>; + tx-threshold = <4>; rs485-rts-active-low; }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt index ecac2bbeae45..8051c17e640e 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt @@ -22,6 +22,7 @@ Required properties in pwrap device node. "mediatek,mt6765-pwrap" for MT6765 SoCs "mediatek,mt6779-pwrap" for MT6779 SoCs "mediatek,mt6797-pwrap" for MT6797 SoCs + "mediatek,mt6873-pwrap" for MT6873/8192 SoCs "mediatek,mt7622-pwrap" for MT7622 SoCs "mediatek,mt8135-pwrap" for MT8135 SoCs "mediatek,mt8173-pwrap" for MT8173 SoCs diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt index 19c059e44681..783dc81b0f26 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,aoss-qmp.txt @@ -17,6 +17,7 @@ power-domains. Value type: <string> Definition: must be one of: "qcom,sc7180-aoss-qmp" + "qcom,sc7280-aoss-qmp" "qcom,sdm845-aoss-qmp" "qcom,sm8150-aoss-qmp" "qcom,sm8250-aoss-qmp" diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt index 042a2e4159bd..1382b64e1381 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.txt @@ -24,6 +24,13 @@ block and a BT, WiFi and FM radio block, all using SMD as command channels. "qcom,riva", "qcom,pronto" +- firmware-name: + Usage: optional + Value type: <string> + Definition: specifies the relative firmware image path for the WLAN NV + blob. Defaults to "wlan/prima/WCNSS_qcom_wlan_nv.bin" if + not specified. + = SUBNODES The subnodes of the wcnss node are optional and describe the individual blocks in the WCNSS. diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.yaml b/Documentation/devicetree/bindings/sound/fsl,spdif.yaml index 50449b6d1048..4454aca34d56 100644 --- a/Documentation/devicetree/bindings/sound/fsl,spdif.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,spdif.yaml @@ -21,6 +21,10 @@ properties: - fsl,vf610-spdif - fsl,imx6sx-spdif - fsl,imx8qm-spdif + - fsl,imx8qxp-spdif + - fsl,imx8mq-spdif + - fsl,imx8mm-spdif + - fsl,imx8mn-spdif reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt b/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt index b104be131235..b93a2b3e029d 100644 --- a/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt +++ b/Documentation/devicetree/bindings/soundwire/qcom,sdw.txt @@ -54,6 +54,8 @@ board specific bus parameters. Value type: <prop-encoded-array> Definition: should specify payload transport window offset1 of each data port. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-offset2: @@ -61,6 +63,8 @@ board specific bus parameters. Value type: <prop-encoded-array> Definition: should specify payload transport window offset2 of each data port. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-sinterval-low: @@ -69,12 +73,16 @@ board specific bus parameters. Definition: should be sample interval low of each data port. Out ports followed by In ports. Used for Sample Interval calculation. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-word-length: Usage: optional Value type: <prop-encoded-array> Definition: should be size of payload channel sample. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-block-pack-mode: @@ -84,6 +92,8 @@ board specific bus parameters. 0 to indicate Blocks are per Channel 1 to indicate Blocks are per Port. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-block-group-count: @@ -92,6 +102,8 @@ board specific bus parameters. Definition: should be in range 1 to 4 to indicate how many sample intervals are combined into a payload. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-lane-control: @@ -100,6 +112,8 @@ board specific bus parameters. Definition: should be in range 0 to 7 to identify which data lane the data port uses. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-hstart: @@ -109,6 +123,8 @@ board specific bus parameters. SoundWire Frame, i.e. left edge of the Transport sub-frame for each port. Values between 0 and 15 are valid. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,ports-hstop: @@ -118,6 +134,8 @@ board specific bus parameters. SoundWire Frame, i.e. the right edge of the Transport sub-frame for each port. Values between 0 and 15 are valid. Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. - qcom,dports-type: @@ -128,6 +146,8 @@ board specific bus parameters. 1 for simple ports 2 for full port Out ports followed by In ports. + Value of 0xFF indicates that this option is not implemented + or applicable for the respective data port. More info in MIPI Alliance SoundWire 1.0 Specifications. Note: diff --git a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt deleted file mode 100644 index d99a9cf3336b..000000000000 --- a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt +++ /dev/null @@ -1,245 +0,0 @@ -Broadcom SPI controller - -The Broadcom SPI controller is a SPI master found on various SOCs, including -BRCMSTB (BCM7XXX), Cygnus, NSP and NS2. The Broadcom Master SPI hw IP consits -of : - MSPI : SPI master controller can read and write to a SPI slave device - BSPI : Broadcom SPI in combination with the MSPI hw IP provides acceleration - for flash reads and be configured to do single, double, quad lane - io with 3-byte and 4-byte addressing support. - - Supported Broadcom SoCs have one instance of MSPI+BSPI controller IP. - MSPI master can be used wihout BSPI. BRCMSTB SoCs have an additional instance - of a MSPI master without the BSPI to use with non flash slave devices that - use SPI protocol. - -Required properties: - -- #address-cells: - Must be <1>, as required by generic SPI binding. - -- #size-cells: - Must be <0>, also as required by generic SPI binding. - -- compatible: - Must be one of : - "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi" : MSPI+BSPI on BRCMSTB SoCs - "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7425-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7429-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7435-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7445-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7216-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-bcm7278-qspi", "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI - BRCMSTB SoCs - "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi" : MSPI+BSPI on Cygnus, NSP - "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi" : NS2 SoCs - -- reg: - Define the bases and ranges of the associated I/O address spaces. - The required range is MSPI controller registers. - -- reg-names: - First name does not matter, but must be reserved for the MSPI controller - register range as mentioned in 'reg' above, and will typically contain - - "bspi_regs": BSPI register range, not required with compatible - "spi-brcmstb-mspi" - - "mspi_regs": MSPI register range is required for compatible strings - - "intr_regs", "intr_status_reg" : Interrupt and status register for - NSP, NS2, Cygnus SoC - -- interrupts - The interrupts used by the MSPI and/or BSPI controller. - -- interrupt-names: - Names of interrupts associated with MSPI - - "mspi_halted" : - - "mspi_done": Indicates that the requested SPI operation is complete. - - "spi_lr_fullness_reached" : Linear read BSPI pipe full - - "spi_lr_session_aborted" : Linear read BSPI pipe aborted - - "spi_lr_impatient" : Linear read BSPI requested when pipe empty - - "spi_lr_session_done" : Linear read BSPI session done - -- clocks: - A phandle to the reference clock for this block. - -Optional properties: - - -- native-endian - Defined when using BE SoC and device uses BE register read/write - -Recommended optional m25p80 properties: -- spi-rx-bus-width: Definition as per - Documentation/devicetree/bindings/spi/spi-bus.txt - -Examples: - -BRCMSTB SoC Example: - - SPI Master (MSPI+BSPI) for SPI-NOR access: - - spi@f03e3400 { - #address-cells = <0x1>; - #size-cells = <0x0>; - compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi"; - reg = <0xf03e0920 0x4 0xf03e3400 0x188 0xf03e3200 0x50>; - reg-names = "cs_reg", "mspi", "bspi"; - interrupts = <0x6 0x5 0x4 0x3 0x2 0x1 0x0>; - interrupt-parent = <0x1c>; - interrupt-names = "mspi_halted", - "mspi_done", - "spi_lr_overread", - "spi_lr_session_done", - "spi_lr_impatient", - "spi_lr_session_aborted", - "spi_lr_fullness_reached"; - - clocks = <&hif_spi>; - clock-names = "sw_spi"; - - m25p80@0 { - #size-cells = <0x2>; - #address-cells = <0x2>; - compatible = "m25p80"; - reg = <0x0>; - spi-max-frequency = <0x2625a00>; - spi-cpol; - spi-cpha; - m25p,fast-read; - - flash0.bolt@0 { - reg = <0x0 0x0 0x0 0x100000>; - }; - - flash0.macadr@100000 { - reg = <0x0 0x100000 0x0 0x10000>; - }; - - flash0.nvram@110000 { - reg = <0x0 0x110000 0x0 0x10000>; - }; - - flash0.kernel@120000 { - reg = <0x0 0x120000 0x0 0x400000>; - }; - - flash0.devtree@520000 { - reg = <0x0 0x520000 0x0 0x10000>; - }; - - flash0.splash@530000 { - reg = <0x0 0x530000 0x0 0x80000>; - }; - - flash0@0 { - reg = <0x0 0x0 0x0 0x4000000>; - }; - }; - }; - - - MSPI master for any SPI device : - - spi@f0416000 { - #address-cells = <1>; - #size-cells = <0>; - clocks = <&upg_fixed>; - compatible = "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi"; - reg = <0xf0416000 0x180>; - reg-names = "mspi"; - interrupts = <0x14>; - interrupt-parent = <&irq0_aon_intc>; - interrupt-names = "mspi_done"; - }; - -iProc SoC Example: - - qspi: spi@18027200 { - compatible = "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi"; - reg = <0x18027200 0x184>, - <0x18027000 0x124>, - <0x1811c408 0x004>, - <0x180273a0 0x01c>; - reg-names = "mspi_regs", "bspi_regs", "intr_regs", "intr_status_reg"; - interrupts = <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 75 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>, - <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = - "spi_lr_fullness_reached", - "spi_lr_session_aborted", - "spi_lr_impatient", - "spi_lr_session_done", - "mspi_done", - "mspi_halted"; - clocks = <&iprocmed>; - clock-names = "iprocmed"; - num-cs = <2>; - #address-cells = <1>; - #size-cells = <0>; - }; - - - NS2 SoC Example: - - qspi: spi@66470200 { - compatible = "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi"; - reg = <0x66470200 0x184>, - <0x66470000 0x124>, - <0x67017408 0x004>, - <0x664703a0 0x01c>; - reg-names = "mspi", "bspi", "intr_regs", - "intr_status_reg"; - interrupts = <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>; - interrupt-names = "spi_l1_intr"; - clocks = <&iprocmed>; - clock-names = "iprocmed"; - num-cs = <2>; - #address-cells = <1>; - #size-cells = <0>; - }; - - - m25p80 node for NSP, NS2 - - &qspi { - flash: m25p80@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "m25p80"; - reg = <0x0>; - spi-max-frequency = <12500000>; - m25p,fast-read; - spi-cpol; - spi-cpha; - - partition@0 { - label = "boot"; - reg = <0x00000000 0x000a0000>; - }; - - partition@a0000 { - label = "env"; - reg = <0x000a0000 0x00060000>; - }; - - partition@100000 { - label = "system"; - reg = <0x00100000 0x00600000>; - }; - - partition@700000 { - label = "rootfs"; - reg = <0x00700000 0x01900000>; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml new file mode 100644 index 000000000000..6ee19d49fd3c --- /dev/null +++ b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.yaml @@ -0,0 +1,198 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/brcm,spi-bcm-qspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Broadcom SPI controller + +maintainers: + - Kamal Dasu <kdasu.kdev@gmail.com> + - RafaÅ‚ MiÅ‚ecki <rafal@milecki.pl> + +description: | + The Broadcom SPI controller is a SPI master found on various SOCs, including + BRCMSTB (BCM7XXX), Cygnus, NSP and NS2. The Broadcom Master SPI hw IP consits + of: + MSPI : SPI master controller can read and write to a SPI slave device + BSPI : Broadcom SPI in combination with the MSPI hw IP provides acceleration + for flash reads and be configured to do single, double, quad lane + io with 3-byte and 4-byte addressing support. + + Supported Broadcom SoCs have one instance of MSPI+BSPI controller IP. + MSPI master can be used wihout BSPI. BRCMSTB SoCs have an additional instance + of a MSPI master without the BSPI to use with non flash slave devices that + use SPI protocol. + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + oneOf: + - description: Second Instance of MSPI BRCMSTB SoCs + items: + - enum: + - brcm,spi-bcm7425-qspi + - brcm,spi-bcm7429-qspi + - brcm,spi-bcm7435-qspi + - brcm,spi-bcm7445-qspi + - brcm,spi-bcm7216-qspi + - brcm,spi-bcm7278-qspi + - const: brcm,spi-bcm-qspi + - const: brcm,spi-brcmstb-mspi + - description: Second Instance of MSPI BRCMSTB SoCs + items: + - enum: + - brcm,spi-brcmstb-qspi + - brcm,spi-brcmstb-mspi + - brcm,spi-nsp-qspi + - brcm,spi-ns2-qspi + - const: brcm,spi-bcm-qspi + + reg: + minItems: 1 + maxItems: 5 + + reg-names: + minItems: 1 + maxItems: 5 + items: + - const: mspi + - const: bspi + - enum: [ intr_regs, intr_status_reg, cs_reg ] + - enum: [ intr_regs, intr_status_reg, cs_reg ] + - enum: [ intr_regs, intr_status_reg, cs_reg ] + + interrupts: + minItems: 1 + maxItems: 7 + + interrupt-names: + oneOf: + - minItems: 1 + maxItems: 7 + items: + - const: mspi_done + - const: mspi_halted + - const: spi_lr_fullness_reached + - const: spi_lr_session_aborted + - const: spi_lr_impatient + - const: spi_lr_session_done + - const: spi_lr_overread + - const: spi_l1_intr + + clocks: + maxItems: 1 + description: reference clock for this block + + native-endian: + $ref: /schemas/types.yaml#/definitions/flag + description: Defined when using BE SoC and device uses BE register read/write + +unevaluatedProperties: false + +required: + - reg + - reg-names + - interrupts + - interrupt-names + +examples: + - | # BRCMSTB SoC: SPI Master (MSPI+BSPI) for SPI-NOR access + spi@f03e3400 { + compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-bcm-qspi"; + reg = <0xf03e3400 0x188>, <0xf03e3200 0x50>, <0xf03e0920 0x4>; + reg-names = "mspi", "bspi", "cs_reg"; + interrupts = <0x5>, <0x6>, <0x1>, <0x2>, <0x3>, <0x4>, <0x0>; + interrupt-parent = <&gic>; + interrupt-names = "mspi_done", + "mspi_halted", + "spi_lr_fullness_reached", + "spi_lr_session_aborted", + "spi_lr_impatient", + "spi_lr_session_done", + "spi_lr_overread"; + clocks = <&hif_spi>; + #address-cells = <0x1>; + #size-cells = <0x0>; + + flash@0 { + #size-cells = <0x2>; + #address-cells = <0x2>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <0x2625a00>; + spi-cpol; + spi-cpha; + }; + }; + - | # BRCMSTB SoC: MSPI master for any SPI device + spi@f0416000 { + clocks = <&upg_fixed>; + compatible = "brcm,spi-brcmstb-mspi", "brcm,spi-bcm-qspi"; + reg = <0xf0416000 0x180>; + reg-names = "mspi"; + interrupts = <0x14>; + interrupt-parent = <&irq0_aon_intc>; + interrupt-names = "mspi_done"; + #address-cells = <1>; + #size-cells = <0>; + }; + - | # iProc SoC + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@18027200 { + compatible = "brcm,spi-nsp-qspi", "brcm,spi-bcm-qspi"; + reg = <0x18027200 0x184>, + <0x18027000 0x124>, + <0x1811c408 0x004>, + <0x180273a0 0x01c>; + reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; + interrupts = <GIC_SPI 77 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 72 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 75 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 76 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "mspi_done", + "mspi_halted", + "spi_lr_fullness_reached", + "spi_lr_session_aborted", + "spi_lr_impatient", + "spi_lr_session_done"; + clocks = <&iprocmed>; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; + }; + - | # NS2 SoC + #include <dt-bindings/interrupt-controller/irq.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + + spi@66470200 { + compatible = "brcm,spi-ns2-qspi", "brcm,spi-bcm-qspi"; + reg = <0x66470200 0x184>, + <0x66470000 0x124>, + <0x67017408 0x004>, + <0x664703a0 0x01c>; + reg-names = "mspi", "bspi", "intr_regs", "intr_status_reg"; + interrupts = <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "spi_l1_intr"; + clocks = <&iprocmed>; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <12500000>; + spi-cpol; + spi-cpha; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/cadence-quadspi.txt b/Documentation/devicetree/bindings/spi/cadence-quadspi.txt deleted file mode 100644 index 8ace832a2d80..000000000000 --- a/Documentation/devicetree/bindings/spi/cadence-quadspi.txt +++ /dev/null @@ -1,68 +0,0 @@ -* Cadence Quad SPI controller - -Required properties: -- compatible : should be one of the following: - Generic default - "cdns,qspi-nor". - For TI 66AK2G SoC - "ti,k2g-qspi", "cdns,qspi-nor". - For TI AM654 SoC - "ti,am654-ospi", "cdns,qspi-nor". - For Intel LGM SoC - "intel,lgm-qspi", "cdns,qspi-nor". -- reg : Contains two entries, each of which is a tuple consisting of a - physical address and length. The first entry is the address and - length of the controller register set. The second entry is the - address and length of the QSPI Controller data area. -- interrupts : Unit interrupt specifier for the controller interrupt. -- clocks : phandle to the Quad SPI clock. -- cdns,fifo-depth : Size of the data FIFO in words. -- cdns,fifo-width : Bus width of the data FIFO in bytes. -- cdns,trigger-address : 32-bit indirect AHB trigger address. - -Optional properties: -- cdns,is-decoded-cs : Flag to indicate whether decoder is used or not. -- cdns,rclk-en : Flag to indicate that QSPI return clock is used to latch - the read data rather than the QSPI clock. Make sure that QSPI return - clock is populated on the board before using this property. - -Optional subnodes: -Subnodes of the Cadence Quad SPI controller are spi slave nodes with additional -custom properties: -- cdns,read-delay : Delay for read capture logic, in clock cycles -- cdns,tshsl-ns : Delay in nanoseconds for the length that the master - mode chip select outputs are de-asserted between - transactions. -- cdns,tsd2d-ns : Delay in nanoseconds between one chip select being - de-activated and the activation of another. -- cdns,tchsh-ns : Delay in nanoseconds between last bit of current - transaction and deasserting the device chip select - (qspi_n_ss_out). -- cdns,tslch-ns : Delay in nanoseconds between setting qspi_n_ss_out low - and first bit transfer. -- resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. -- reset-names : Must include either "qspi" and/or "qspi-ocp". - -Example: - - qspi: spi@ff705000 { - compatible = "cdns,qspi-nor"; - #address-cells = <1>; - #size-cells = <0>; - reg = <0xff705000 0x1000>, - <0xffa00000 0x1000>; - interrupts = <0 151 4>; - clocks = <&qspi_clk>; - cdns,is-decoded-cs; - cdns,fifo-depth = <128>; - cdns,fifo-width = <4>; - cdns,trigger-address = <0x00000000>; - resets = <&rst QSPI_RESET>, <&rst QSPI_OCP_RESET>; - reset-names = "qspi", "qspi-ocp"; - - flash0: n25q00@0 { - ... - cdns,read-delay = <4>; - cdns,tshsl-ns = <50>; - cdns,tsd2d-ns = <50>; - cdns,tchsh-ns = <4>; - cdns,tslch-ns = <4>; - }; - }; diff --git a/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml new file mode 100644 index 000000000000..0e7087cc8bf9 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/cdns,qspi-nor.yaml @@ -0,0 +1,143 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/cdns,qspi-nor.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cadence Quad SPI controller + +maintainers: + - Pratyush Yadav <p.yadav@ti.com> + +allOf: + - $ref: spi-controller.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - ti,k2g-qspi + - ti,am654-ospi + - intel,lgm-qspi + - const: cdns,qspi-nor + - const: cdns,qspi-nor + + reg: + items: + - description: the controller register set + - description: the controller data area + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + cdns,fifo-depth: + description: + Size of the data FIFO in words. + $ref: "/schemas/types.yaml#/definitions/uint32" + enum: [ 128, 256 ] + default: 128 + + cdns,fifo-width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Bus width of the data FIFO in bytes. + default: 4 + + cdns,trigger-address: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + 32-bit indirect AHB trigger address. + + cdns,is-decoded-cs: + type: boolean + description: + Flag to indicate whether decoder is used to select different chip select + for different memory regions. + + cdns,rclk-en: + type: boolean + description: + Flag to indicate that QSPI return clock is used to latch the read + data rather than the QSPI clock. Make sure that QSPI return clock + is populated on the board before using this property. + + resets: + maxItems: 2 + + reset-names: + minItems: 1 + maxItems: 2 + items: + enum: [ qspi, qspi-ocp ] + +# subnode's properties +patternProperties: + "@[0-9a-f]+$": + type: object + description: + Flash device uses the below defined properties in the subnode. + + properties: + cdns,read-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Delay for read capture logic, in clock cycles. + + cdns,tshsl-ns: + description: + Delay in nanoseconds for the length that the master mode chip select + outputs are de-asserted between transactions. + + cdns,tsd2d-ns: + description: + Delay in nanoseconds between one chip select being de-activated + and the activation of another. + + cdns,tchsh-ns: + description: + Delay in nanoseconds between last bit of current transaction and + deasserting the device chip select (qspi_n_ss_out). + + cdns,tslch-ns: + description: + Delay in nanoseconds between setting qspi_n_ss_out low and + first bit transfer. + +required: + - compatible + - reg + - interrupts + - clocks + - cdns,fifo-depth + - cdns,fifo-width + - cdns,trigger-address + - '#address-cells' + - '#size-cells' + +unevaluatedProperties: false + +examples: + - | + qspi: spi@ff705000 { + compatible = "cdns,qspi-nor"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xff705000 0x1000>, + <0xffa00000 0x1000>; + interrupts = <0 151 4>; + clocks = <&qspi_clk>; + cdns,fifo-depth = <128>; + cdns,fifo-width = <4>; + cdns,trigger-address = <0x00000000>; + resets = <&rst 0x1>, <&rst 0x2>; + reset-names = "qspi", "qspi-ocp"; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0x0>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml b/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml new file mode 100644 index 000000000000..e58644558412 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/fsl,spi-fsl-qspi.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/fsl,spi-fsl-qspi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Quad Serial Peripheral Interface (QuadSPI) + +maintainers: + - Han Xu <han.xu@nxp.com> + +allOf: + - $ref: "spi-controller.yaml#" + +properties: + compatible: + oneOf: + - enum: + - fsl,vf610-qspi + - fsl,imx6sx-qspi + - fsl,imx7d-qspi + - fsl,imx6ul-qspi + - fsl,ls1021a-qspi + - fsl,ls2080a-qspi + - items: + - enum: + - fsl,ls1043a-qspi + - const: fsl,ls1021a-qspi + - items: + - enum: + - fsl,imx8mq-qspi + - const: fsl,imx7d-qspi + + reg: + items: + - description: registers + - description: memory mapping + + reg-names: + items: + - const: QuadSPI + - const: QuadSPI-memory + + interrupts: + maxItems: 1 + + clocks: + items: + - description: SoC SPI qspi_en clock + - description: SoC SPI qspi clock + + clock-names: + items: + - const: qspi_en + - const: qspi + +required: + - compatible + - reg + - reg-names + - interrupts + - clocks + - clock-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/fsl,qoriq-clockgen.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + spi@1550000 { + compatible = "fsl,ls1021a-qspi"; + reg = <0x0 0x1550000 0x0 0x100000>, + <0x0 0x40000000 0x0 0x10000000>; + reg-names = "QuadSPI", "QuadSPI-memory"; + interrupts = <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&clockgen QORIQ_CLK_PLATFORM_PLL QORIQ_CLK_PLL_DIV(2)>, + <&clockgen QORIQ_CLK_PLATFORM_PLL QORIQ_CLK_PLL_DIV(2)>; + clock-names = "qspi_en", "qspi"; + + flash@0 { + compatible = "jedec,spi-nor"; + spi-max-frequency = <50000000>; + reg = <0>; + spi-rx-bus-width = <4>; + spi-tx-bus-width = <4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml index 55c239446a5b..7393f30535df 100644 --- a/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml +++ b/Documentation/devicetree/bindings/spi/mediatek,spi-mtk-nor.yaml @@ -31,6 +31,7 @@ properties: - mediatek,mt7623-nor - mediatek,mt7629-nor - mediatek,mt8192-nor + - mediatek,mt8195-nor - enum: - mediatek,mt8173-nor - items: diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt deleted file mode 100644 index 69dc5d57b1ef..000000000000 --- a/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt +++ /dev/null @@ -1,66 +0,0 @@ -* Freescale Quad Serial Peripheral Interface(QuadSPI) - -Required properties: - - compatible : Should be "fsl,vf610-qspi", "fsl,imx6sx-qspi", - "fsl,imx7d-qspi", "fsl,imx6ul-qspi", - "fsl,ls1021a-qspi", "fsl,ls2080a-qspi" - or - "fsl,ls1043a-qspi" followed by "fsl,ls1021a-qspi" - - reg : the first contains the register location and length, - the second contains the memory mapping address and length - - reg-names: Should contain the reg names "QuadSPI" and "QuadSPI-memory" - - interrupts : Should contain the interrupt for the device - - clocks : The clocks needed by the QuadSPI controller - - clock-names : Should contain the name of the clocks: "qspi_en" and "qspi". - -Required SPI slave node properties: - - reg: There are two buses (A and B) with two chip selects each. - This encodes to which bus and CS the flash is connected: - <0>: Bus A, CS 0 - <1>: Bus A, CS 1 - <2>: Bus B, CS 0 - <3>: Bus B, CS 1 - -Example: - -qspi0: quadspi@40044000 { - compatible = "fsl,vf610-qspi"; - reg = <0x40044000 0x1000>, <0x20000000 0x10000000>; - reg-names = "QuadSPI", "QuadSPI-memory"; - interrupts = <0 24 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks VF610_CLK_QSPI0_EN>, - <&clks VF610_CLK_QSPI0>; - clock-names = "qspi_en", "qspi"; - - flash0: s25fl128s@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "spansion,s25fl128s", "jedec,spi-nor"; - spi-max-frequency = <50000000>; - reg = <0>; - }; -}; - -Example showing the usage of two SPI NOR devices on bus A: - -&qspi2 { - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_qspi2>; - status = "okay"; - - flash0: n25q256a@0 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "micron,n25q256a", "jedec,spi-nor"; - spi-max-frequency = <29000000>; - reg = <0>; - }; - - flash1: n25q256a@1 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "micron,n25q256a", "jedec,spi-nor"; - spi-max-frequency = <29000000>; - reg = <1>; - }; -}; diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index 9e43721fa7d6..4d0e4c15c4ea 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -12,7 +12,9 @@ Required properties: - mediatek,mt8173-spi: for mt8173 platforms - mediatek,mt8183-spi: for mt8183 platforms - "mediatek,mt8192-spi", "mediatek,mt6765-spi": for mt8192 platforms + - "mediatek,mt8195-spi", "mediatek,mt6765-spi": for mt8195 platforms - "mediatek,mt8516-spi", "mediatek,mt2712-spi": for mt8516 platforms + - "mediatek,mt6779-spi", "mediatek,mt6765-spi": for mt6779 platforms - #address-cells: should be 1. diff --git a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt index 7ac60d9fe357..8f34a7c7d8b8 100644 --- a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt @@ -4,6 +4,8 @@ Required properties: - compatible : Should be "nxp,lx2160a-fspi" "nxp,imx8qxp-fspi" "nxp,imx8mm-fspi" + "nxp,imx8mp-fspi" + "nxp,imx8dxl-fspi" - reg : First contains the register location and length, Second contains the memory mapping address and length diff --git a/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt b/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt index c37e5a179b21..9192724540fd 100644 --- a/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-slave-mt27xx.txt @@ -3,6 +3,7 @@ Binding for MTK SPI Slave controller Required properties: - compatible: should be one of the following. - mediatek,mt2712-spi-slave: for mt2712 platforms + - mediatek,mt8195-spi-slave: for mt8195 platforms - reg: Address and length of the register set for the device. - interrupts: Should contain spi interrupt. - clocks: phandles to input clocks. diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst index 68129ff09967..1d11c25249ff 100644 --- a/Documentation/devicetree/bindings/submitting-patches.rst +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -75,8 +75,8 @@ II. For kernel maintainers binding, and it hasn't received an Acked-by from the devicetree maintainers after a few weeks, go ahead and take it. - Subsystem bindings (anything affecting more than a single device) - then getting a devicetree maintainer to review it is required. + For subsystem bindings (anything affecting more than a single device), + getting a devicetree maintainer to review it is required. 3) For a series going though multiple trees, the binding patch should be kept with the driver using the binding. diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml b/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml index 2c75105c1398..7f5e3af58255 100644 --- a/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml +++ b/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml @@ -34,11 +34,30 @@ properties: - arm,armv8-timer interrupts: + minItems: 1 + maxItems: 5 items: - description: secure timer irq - description: non-secure timer irq - description: virtual timer irq - description: hypervisor timer irq + - description: hypervisor virtual timer irq + + interrupt-names: + oneOf: + - minItems: 2 + items: + - const: phys + - const: virt + - const: hyp-phys + - const: hyp-virt + - minItems: 3 + items: + - const: sec-phys + - const: phys + - const: virt + - const: hyp-phys + - const: hyp-virt clock-frequency: description: The frequency of the main counter, in Hz. Should be present diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml index 024bcad75101..8165df4599cf 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.yaml @@ -20,6 +20,8 @@ select: enum: - ingenic,jz4740-tcu - ingenic,jz4725b-tcu + - ingenic,jz4760-tcu + - ingenic,jz4760b-tcu - ingenic,jz4770-tcu - ingenic,jz4780-tcu - ingenic,x1000-tcu @@ -52,12 +54,15 @@ properties: - enum: - ingenic,jz4740-tcu - ingenic,jz4725b-tcu - - ingenic,jz4770-tcu + - ingenic,jz4760-tcu - ingenic,x1000-tcu - const: simple-mfd - items: - - const: ingenic,jz4780-tcu - - const: ingenic,jz4770-tcu + - enum: + - ingenic,jz4780-tcu + - ingenic,jz4770-tcu + - ingenic,jz4760b-tcu + - const: ingenic,jz4760-tcu - const: simple-mfd reg: @@ -118,6 +123,8 @@ patternProperties: - items: - enum: - ingenic,jz4770-watchdog + - ingenic,jz4760b-watchdog + - ingenic,jz4760-watchdog - ingenic,jz4725b-watchdog - const: ingenic,jz4740-watchdog @@ -147,6 +154,8 @@ patternProperties: - ingenic,jz4725b-pwm - items: - enum: + - ingenic,jz4760-pwm + - ingenic,jz4760b-pwm - ingenic,jz4770-pwm - ingenic,jz4780-pwm - const: ingenic,jz4740-pwm @@ -183,10 +192,15 @@ patternProperties: oneOf: - enum: - ingenic,jz4725b-ost - - ingenic,jz4770-ost + - ingenic,jz4760b-ost - items: - - const: ingenic,jz4780-ost - - const: ingenic,jz4770-ost + - const: ingenic,jz4760-ost + - const: ingenic,jz4725b-ost + - items: + - enum: + - ingenic,jz4780-ost + - ingenic,jz4770-ost + - const: ingenic,jz4760b-ost reg: maxItems: 1 @@ -226,7 +240,7 @@ examples: #include <dt-bindings/clock/jz4770-cgu.h> #include <dt-bindings/clock/ingenic,tcu.h> tcu: timer@10002000 { - compatible = "ingenic,jz4770-tcu", "simple-mfd"; + compatible = "ingenic,jz4770-tcu", "ingenic,jz4760-tcu", "simple-mfd"; reg = <0x10002000 0x1000>; #address-cells = <1>; #size-cells = <1>; @@ -272,7 +286,7 @@ examples: }; ost: timer@e0 { - compatible = "ingenic,jz4770-ost"; + compatible = "ingenic,jz4770-ost", "ingenic,jz4760b-ost"; reg = <0xe0 0x20>; clocks = <&tcu TCU_CLK_OST>; diff --git a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt index 690a9c0966ac..e5c57d6e0186 100644 --- a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt +++ b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt @@ -23,6 +23,7 @@ Required properties: For those SoCs that use SYST * "mediatek,mt8183-timer" for MT8183 compatible timers (SYST) * "mediatek,mt8192-timer" for MT8192 compatible timers (SYST) + * "mediatek,mt8195-timer" for MT8195 compatible timers (SYST) * "mediatek,mt7629-timer" for MT7629 compatible timers (SYST) * "mediatek,mt6765-timer" for MT6765 and all above compatible timers (SYST) diff --git a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt index 97258f1a1505..ac3a5e887455 100644 --- a/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt +++ b/Documentation/devicetree/bindings/timer/nuvoton,npcm7xx-timer.txt @@ -4,7 +4,8 @@ Nuvoton NPCM7xx have three timer modules, each timer module provides five 24-bit timer counters. Required properties: -- compatible : "nuvoton,npcm750-timer" for Poleg NPCM750. +- compatible : "nuvoton,npcm750-timer" for Poleg NPCM750, or + "nuvoton,wpcm450-timer" for Hermon WPCM450. - reg : Offset and length of the register set for the device. - interrupts : Contain the timer interrupt of timer 0. - clocks : phandle of timer reference clock (usually a 25 MHz clock). diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml index 428db3a21bb9..53dd6d9f518f 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.yaml @@ -74,11 +74,13 @@ properties: - renesas,r8a774e1-cmt0 # 32-bit CMT0 on RZ/G2H - renesas,r8a7795-cmt0 # 32-bit CMT0 on R-Car H3 - renesas,r8a7796-cmt0 # 32-bit CMT0 on R-Car M3-W + - renesas,r8a77961-cmt0 # 32-bit CMT0 on R-Car M3-W+ - renesas,r8a77965-cmt0 # 32-bit CMT0 on R-Car M3-N - renesas,r8a77970-cmt0 # 32-bit CMT0 on R-Car V3M - renesas,r8a77980-cmt0 # 32-bit CMT0 on R-Car V3H - renesas,r8a77990-cmt0 # 32-bit CMT0 on R-Car E3 - renesas,r8a77995-cmt0 # 32-bit CMT0 on R-Car D3 + - renesas,r8a779a0-cmt0 # 32-bit CMT0 on R-Car V3U - const: renesas,rcar-gen3-cmt0 # 32-bit CMT0 on R-Car Gen3 and RZ/G2 - items: @@ -89,11 +91,13 @@ properties: - renesas,r8a774e1-cmt1 # 48-bit CMT on RZ/G2H - renesas,r8a7795-cmt1 # 48-bit CMT on R-Car H3 - renesas,r8a7796-cmt1 # 48-bit CMT on R-Car M3-W + - renesas,r8a77961-cmt1 # 48-bit CMT on R-Car M3-W+ - renesas,r8a77965-cmt1 # 48-bit CMT on R-Car M3-N - renesas,r8a77970-cmt1 # 48-bit CMT on R-Car V3M - renesas,r8a77980-cmt1 # 48-bit CMT on R-Car V3H - renesas,r8a77990-cmt1 # 48-bit CMT on R-Car E3 - renesas,r8a77995-cmt1 # 48-bit CMT on R-Car D3 + - renesas,r8a779a0-cmt1 # 48-bit CMT on R-Car V3U - const: renesas,rcar-gen3-cmt1 # 48-bit CMT on R-Car Gen3 and RZ/G2 reg: diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml index c54188731a1b..f0f0f121c355 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml @@ -28,8 +28,14 @@ properties: - renesas,tmu-r8a774e1 # RZ/G2H - renesas,tmu-r8a7778 # R-Car M1A - renesas,tmu-r8a7779 # R-Car H1 + - renesas,tmu-r8a7795 # R-Car H3 + - renesas,tmu-r8a7796 # R-Car M3-W + - renesas,tmu-r8a77961 # R-Car M3-W+ + - renesas,tmu-r8a77965 # R-Car M3-N - renesas,tmu-r8a77970 # R-Car V3M - renesas,tmu-r8a77980 # R-Car V3H + - renesas,tmu-r8a77990 # R-Car E3 + - renesas,tmu-r8a77995 # R-Car D3 - const: renesas,tmu reg: diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index a327130d1faa..08e417e2236c 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -50,6 +50,8 @@ properties: - atmel,atsha204a # i2c h/w elliptic curve crypto module - atmel,atecc508a + # BPA-RS600: Power Supply + - blutek,bpa-rs600 # Bosch Sensortec pressure, temperature, humididty and VOC sensor - bosch,bme680 # CM32181: Ambient Light Sensor @@ -102,6 +104,8 @@ properties: - mps,mp2975 # G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface - gmt,g751 + # Infineon IR36021 digital POL buck controller + - infineon,ir36021 # Infineon IR38064 Voltage Regulator - infineon,ir38064 # Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) @@ -288,6 +292,8 @@ properties: - ti,tmp103 # Digital Temperature Sensor - ti,tmp275 + # TI Dual channel DCAP+ multiphase controller TPS53676 with AVSBus + - ti,tps53676 # TI Dual channel DCAP+ multiphase controller TPS53679 - ti,tps53679 # TI Dual channel DCAP+ multiphase controller TPS53688 diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt index a668f43bedf5..04813a46e5d0 100644 --- a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt +++ b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt @@ -1,32 +1,56 @@ Xilinx SuperSpeed DWC3 USB SoC controller Required properties: -- compatible: Should contain "xlnx,zynqmp-dwc3" +- compatible: May contain "xlnx,zynqmp-dwc3" or "xlnx,versal-dwc3" +- reg: Base address and length of the register control block - clocks: A list of phandles for the clocks listed in clock-names - clock-names: Should contain the following: "bus_clk" Master/Core clock, have to be >= 125 MHz for SS operation and >= 60MHz for HS operation "ref_clk" Clock source to core during PHY power down +- resets: A list of phandles for resets listed in reset-names +- reset-names: + "usb_crst" USB core reset + "usb_hibrst" USB hibernation reset + "usb_apbrst" USB APB reset Required child node: A child node must exist to represent the core DWC3 IP block. The name of the node is not important. The content of the node is defined in dwc3.txt. +Optional properties for snps,dwc3: +- dma-coherent: Enable this flag if CCI is enabled in design. Adding this + flag configures Global SoC bus Configuration Register and + Xilinx USB 3.0 IP - USB coherency register to enable CCI. +- interrupt-names: Should contain the following: + "dwc_usb3" USB gadget mode interrupts + "otg" USB OTG mode interrupts + "hiber" USB hibernation interrupts + Example device node: usb@0 { #address-cells = <0x2>; #size-cells = <0x1>; compatible = "xlnx,zynqmp-dwc3"; + reg = <0x0 0xff9d0000 0x0 0x100>; clock-names = "bus_clk", "ref_clk"; clocks = <&clk125>, <&clk125>; + resets = <&zynqmp_reset ZYNQMP_RESET_USB1_CORERESET>, + <&zynqmp_reset ZYNQMP_RESET_USB1_HIBERRESET>, + <&zynqmp_reset ZYNQMP_RESET_USB1_APB>; + reset-names = "usb_crst", "usb_hibrst", "usb_apbrst"; ranges; dwc3@fe200000 { compatible = "snps,dwc3"; reg = <0x0 0xfe200000 0x40000>; - interrupts = <0x0 0x41 0x4>; + interrupt-names = "dwc_usb3", "otg", "hiber"; + interrupts = <0 65 4>, <0 69 4>, <0 75 4>; + phys = <&psgtr 2 PHY_TYPE_USB3 0 2>; + phy-names = "usb3-phy"; dr_mode = "host"; + dma-coherent; }; }; diff --git a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml index cb4c6f6d3a33..974032b1fda0 100644 --- a/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/fsl,imx8mp-dwc3.yaml @@ -52,11 +52,8 @@ properties: # Required child node: patternProperties: - "^dwc3@[0-9a-f]+$": - type: object - description: - A child node must exist to represent the core DWC3 IP block - The content of the node is defined in dwc3.txt. + "^usb@[0-9a-f]+$": + $ref: snps,dwc3.yaml# required: - compatible @@ -87,7 +84,7 @@ examples: dma-ranges = <0x40000000 0x40000000 0xc0000000>; ranges; - dwc3@38100000 { + usb@38100000 { compatible = "snps,dwc3"; reg = <0x38100000 0x10000>; clocks = <&clk IMX8MP_CLK_HSIO_AXI>, diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index cf83f2d9afac..8089dc956ba3 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -122,6 +122,12 @@ properties: description: Set this flag to force EHCI reset after resume. + spurious-oc: + $ref: /schemas/types.yaml#/definitions/flag + description: + Set this flag to indicate that the hardware sometimes turns on + the OC bit when an over-current isn't actually present. + companion: $ref: /schemas/types.yaml#/definitions/phandle description: diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml index 14f40efb3b22..240882b12565 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.yaml @@ -30,6 +30,7 @@ properties: - mediatek,mt7629-xhci - mediatek,mt8173-xhci - mediatek,mt8183-xhci + - mediatek,mt8192-xhci - const: mediatek,mtk-xhci reg: @@ -45,7 +46,18 @@ properties: - const: ippc # optional, only needed for case 1. interrupts: - maxItems: 1 + description: + use "interrupts-extended" when the interrupts are connected to the + separate interrupt controllers + minItems: 1 + items: + - description: xHCI host controller interrupt + - description: optional, wakeup interrupt used to support runtime PM + + interrupt-names: + items: + - const: host + - const: wakeup power-domains: description: A phandle to USB power domain node to control USB's MTCMOS @@ -99,9 +111,9 @@ properties: vbus-supply: description: Regulator of USB VBUS5v - usb3-lpm-capable: - description: supports USB3.0 LPM - type: boolean + usb3-lpm-capable: true + + usb2-lpm-disable: true imod-interval-ns: description: @@ -127,10 +139,13 @@ properties: - description: The second cell represents the register base address of the glue layer in syscon - - description: + - description: | The third cell represents the hardware version of the glue layer, - 1 is used by mt8173 etc, 2 is used by mt2712 etc - enum: [1, 2] + 1 - used by mt8173 etc, revision 1 without following IPM rule; + 2 - used by mt2712 etc, revision 2 following IPM rule; + 101 - used by mt8183, specific 1.01; + 102 - used by mt8192, specific 1.02; + enum: [1, 2, 101, 102] mediatek,u3p-dis-msk: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml index f5c04b9d2de9..dbc7876e0a0b 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -24,6 +24,7 @@ properties: - mediatek,mt2712-mtu3 - mediatek,mt8173-mtu3 - mediatek,mt8183-mtu3 + - mediatek,mt8192-mtu3 - const: mediatek,mtu3 reg: @@ -126,7 +127,7 @@ properties: Any connector to the data bus of this controller should be modelled using the OF graph bindings specified, if the "usb-role-switch" property is used. See graph.txt - type: object + $ref: /schemas/graph.yaml#/properties/port enable-manual-drd: $ref: /schemas/types.yaml#/definitions/flag @@ -152,10 +153,13 @@ properties: - description: The second cell represents the register base address of the glue layer in syscon - - description: + - description: | The third cell represents the hardware version of the glue layer, - 1 is used by mt8173 etc, 2 is used by mt2712 etc - enum: [1, 2] + 1 - used by mt8173 etc, revision 1 without following IPM rule; + 2 - used by mt2712 etc, revision 2 with following IPM rule; + 101 - used by mt8183, specific 1.01; + 102 - used by mt8192, specific 1.02; + enum: [1, 2, 101, 102] mediatek,u3p-dis-msk: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index c3cbd1fa9944..413299b5fe2b 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -16,6 +16,7 @@ properties: - qcom,msm8996-dwc3 - qcom,msm8998-dwc3 - qcom,sc7180-dwc3 + - qcom,sc7280-dwc3 - qcom,sdm845-dwc3 - qcom,sdx55-dwc3 - qcom,sm8150-dwc3 diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml index 2247da77eac1..41416fbd92aa 100644 --- a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -87,13 +87,19 @@ properties: minItems: 1 snps,usb2-lpm-disable: - description: Indicate if we don't want to enable USB2 HW LPM + description: Indicate if we don't want to enable USB2 HW LPM for host + mode. type: boolean snps,usb3_lpm_capable: description: Determines if platform is USB3 LPM capable type: boolean + snps,usb2-gadget-lpm-disable: + description: Indicate if we don't want to enable USB2 HW LPM for gadget + mode. + type: boolean + snps,dis-start-transfer-quirk: description: When set, disable isoc START TRANSFER command failure SW work-around diff --git a/Documentation/devicetree/bindings/usb/usb-device.yaml b/Documentation/devicetree/bindings/usb/usb-device.yaml index d4c99809ee9a..b77960a7a37b 100644 --- a/Documentation/devicetree/bindings/usb/usb-device.yaml +++ b/Documentation/devicetree/bindings/usb/usb-device.yaml @@ -82,9 +82,9 @@ required: additionalProperties: true examples: - #hub connected to port 1 - #device connected to port 2 - #device connected to port 3 + # hub connected to port 1 + # device connected to port 2 + # device connected to port 3 # interface 0 of configuration 1 # interface 0 of configuration 2 - | diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt deleted file mode 100644 index 4dc6a8ee3071..000000000000 --- a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.txt +++ /dev/null @@ -1,43 +0,0 @@ -USB NOP PHY - -Required properties: -- compatible: should be usb-nop-xceiv -- #phy-cells: Must be 0 - -Optional properties: -- clocks: phandle to the PHY clock. Use as per Documentation/devicetree - /bindings/clock/clock-bindings.txt - This property is required if clock-frequency is specified. - -- clock-names: Should be "main_clk" - -- clock-frequency: the clock frequency (in Hz) that the PHY clock must - be configured to. - -- vcc-supply: phandle to the regulator that provides power to the PHY. - -- reset-gpios: Should specify the GPIO for reset. - -- vbus-detect-gpio: should specify the GPIO detecting a VBus insertion - (see Documentation/devicetree/bindings/gpio/gpio.txt) -- vbus-regulator : should specifiy the regulator supplying current drawn from - the VBus line (see Documentation/devicetree/bindings/regulator/regulator.txt). - -Example: - - hsusb1_phy { - compatible = "usb-nop-xceiv"; - clock-frequency = <19200000>; - clocks = <&osc 0>; - clock-names = "main_clk"; - vcc-supply = <&hsusb1_vcc_regulator>; - reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; - vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; - vbus-regulator = <&vbus_regulator>; - #phy-cells = <0>; - }; - -hsusb1_phy is a NOP USB PHY device that gets its clock from an oscillator -and expects that clock to be configured to 19.2MHz by the NOP PHY driver. -hsusb1_vcc_regulator provides power to the PHY and GPIO 7 controls RESET. -GPIO 13 detects VBus insertion, and accordingly notifies the vbus-regulator. diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml new file mode 100644 index 000000000000..2824c17285ee --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-nop-xceiv.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: USB NOP PHY + +maintainers: + - Rob Herring <robh@kernel.org> + +properties: + compatible: + const: usb-nop-xceiv + + clocks: + maxItems: 1 + + clock-names: + const: main_clk + + clock-frequency: true + + '#phy-cells': + const: 0 + + vcc-supply: + description: phandle to the regulator that provides power to the PHY. + + reset-gpios: + maxItems: 1 + + vbus-detect-gpio: + description: Should specify the GPIO detecting a VBus insertion + maxItems: 1 + + vbus-regulator: + description: Should specifiy the regulator supplying current drawn from + the VBus line. + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - '#phy-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + hsusb1_phy { + compatible = "usb-nop-xceiv"; + clock-frequency = <19200000>; + clocks = <&osc 0>; + clock-names = "main_clk"; + vcc-supply = <&hsusb1_vcc_regulator>; + reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; + vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; + vbus-regulator = <&vbus_regulator>; + #phy-cells = <0>; + }; + +... diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index f6064d84a424..c88b1cfb52cb 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -103,6 +103,8 @@ patternProperties: description: Anvo-Systems Dresden GmbH "^apm,.*": description: Applied Micro Circuits Corporation (APM) + "^apple,.*": + description: Apple Inc. "^aptina,.*": description: Aptina Imaging "^arasan,.*": @@ -169,6 +171,8 @@ patternProperties: description: Beckhoff Automation GmbH & Co. KG "^bitmain,.*": description: Bitmain Technologies + "^blutek,.*": + description: BluTek Power "^boe,.*": description: BOE Technology Group Co., Ltd. "^bosch,.*": @@ -651,6 +655,8 @@ patternProperties: description: Liebherr-Werk Nenzing GmbH "^lxa,.*": description: Linux Automation GmbH + "^m5stack,.*": + description: M5Stack "^macnica,.*": description: Macnica Americas "^mantix,.*": @@ -932,6 +938,8 @@ patternProperties: description: Unisoc Communications, Inc. "^realtek,.*": description: Realtek Semiconductor Corp. + "^remarkable,.*": + description: reMarkable AS "^renesas,.*": description: Renesas Electronics Corporation "^rex,.*": @@ -1024,6 +1032,8 @@ patternProperties: description: Silex Insight "^siliconmitus,.*": description: Silicon Mitus, Inc. + "^siemens,.*": + description: Siemens AG "^simtek,.*": description: Cypress Semiconductor Corporation (Simtek Corporation) "^sinlinx,.*": @@ -1085,6 +1095,8 @@ patternProperties: description: Shenzhen Sunchip Technology Co., Ltd "^SUNW,.*": description: Sun Microsystems, Inc + "^supermicro,.*": + description: Super Micro Computer, Inc. "^silvaco,.*": description: Silvaco, Inc. "^swir,.*": @@ -1101,6 +1113,8 @@ patternProperties: description: Trusted Computing Group "^tcl,.*": description: Toby Churchill Ltd. + "^tcs,.*": + description: Shenzhen City Tang Cheng Technology Co., Ltd. "^tdo,.*": description: Shangai Top Display Optoelectronics Co., Ltd "^technexion,.*": diff --git a/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt index 6d593003c933..9059f54dc023 100644 --- a/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/nuvoton,npcm-wdt.txt @@ -5,7 +5,8 @@ The watchdog supports a pre-timeout interrupt that fires 10ms before the expiry. Required properties: -- compatible : "nuvoton,npcm750-wdt" for NPCM750 (Poleg). +- compatible : "nuvoton,npcm750-wdt" for NPCM750 (Poleg), or + "nuvoton,wpcm450-wdt" for WPCM450 (Hermon). - reg : Offset and length of the register set for the device. - interrupts : Contain the timer interrupt with flags for falling edge. diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 764963876d08..e9f04b1815d1 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -146,6 +146,362 @@ There are also equivalents to memcpy. The ins() and outs() functions copy bytes, words or longs to the given port. +__iomem pointer tokens +====================== + +The data type for an MMIO address is an ``__iomem`` qualified pointer, such as +``void __iomem *reg``. On most architectures it is a regular pointer that +points to a virtual memory address and can be offset or dereferenced, but in +portable code, it must only be passed from and to functions that explicitly +operated on an ``__iomem`` token, in particular the ioremap() and +readl()/writel() functions. The 'sparse' semantic code checker can be used to +verify that this is done correctly. + +While on most architectures, ioremap() creates a page table entry for an +uncached virtual address pointing to the physical MMIO address, some +architectures require special instructions for MMIO, and the ``__iomem`` pointer +just encodes the physical address or an offsettable cookie that is interpreted +by readl()/writel(). + +Differences between I/O access functions +======================================== + +readq(), readl(), readw(), readb(), writeq(), writel(), writew(), writeb() + + These are the most generic accessors, providing serialization against other + MMIO accesses and DMA accesses as well as fixed endianness for accessing + little-endian PCI devices and on-chip peripherals. Portable device drivers + should generally use these for any access to ``__iomem`` pointers. + + Note that posted writes are not strictly ordered against a spinlock, see + Documentation/driver-api/io_ordering.rst. + +readq_relaxed(), readl_relaxed(), readw_relaxed(), readb_relaxed(), +writeq_relaxed(), writel_relaxed(), writew_relaxed(), writeb_relaxed() + + On architectures that require an expensive barrier for serializing against + DMA, these "relaxed" versions of the MMIO accessors only serialize against + each other, but contain a less expensive barrier operation. A device driver + might use these in a particularly performance sensitive fast path, with a + comment that explains why the usage in a specific location is safe without + the extra barriers. + + See memory-barriers.txt for a more detailed discussion on the precise ordering + guarantees of the non-relaxed and relaxed versions. + +ioread64(), ioread32(), ioread16(), ioread8(), +iowrite64(), iowrite32(), iowrite16(), iowrite8() + + These are an alternative to the normal readl()/writel() functions, with almost + identical behavior, but they can also operate on ``__iomem`` tokens returned + for mapping PCI I/O space with pci_iomap() or ioport_map(). On architectures + that require special instructions for I/O port access, this adds a small + overhead for an indirect function call implemented in lib/iomap.c, while on + other architectures, these are simply aliases. + +ioread64be(), ioread32be(), ioread16be() +iowrite64be(), iowrite32be(), iowrite16be() + + These behave in the same way as the ioread32()/iowrite32() family, but with + reversed byte order, for accessing devices with big-endian MMIO registers. + Device drivers that can operate on either big-endian or little-endian + registers may have to implement a custom wrapper function that picks one or + the other depending on which device was found. + + Note: On some architectures, the normal readl()/writel() functions + traditionally assume that devices are the same endianness as the CPU, while + using a hardware byte-reverse on the PCI bus when running a big-endian kernel. + Drivers that use readl()/writel() this way are generally not portable, but + tend to be limited to a particular SoC. + +hi_lo_readq(), lo_hi_readq(), hi_lo_readq_relaxed(), lo_hi_readq_relaxed(), +ioread64_lo_hi(), ioread64_hi_lo(), ioread64be_lo_hi(), ioread64be_hi_lo(), +hi_lo_writeq(), lo_hi_writeq(), hi_lo_writeq_relaxed(), lo_hi_writeq_relaxed(), +iowrite64_lo_hi(), iowrite64_hi_lo(), iowrite64be_lo_hi(), iowrite64be_hi_lo() + + Some device drivers have 64-bit registers that cannot be accessed atomically + on 32-bit architectures but allow two consecutive 32-bit accesses instead. + Since it depends on the particular device which of the two halves has to be + accessed first, a helper is provided for each combination of 64-bit accessors + with either low/high or high/low word ordering. A device driver must include + either <linux/io-64-nonatomic-lo-hi.h> or <linux/io-64-nonatomic-hi-lo.h> to + get the function definitions along with helpers that redirect the normal + readq()/writeq() to them on architectures that do not provide 64-bit access + natively. + +__raw_readq(), __raw_readl(), __raw_readw(), __raw_readb(), +__raw_writeq(), __raw_writel(), __raw_writew(), __raw_writeb() + + These are low-level MMIO accessors without barriers or byteorder changes and + architecture specific behavior. Accesses are usually atomic in the sense that + a four-byte __raw_readl() does not get split into individual byte loads, but + multiple consecutive accesses can be combined on the bus. In portable code, it + is only safe to use these to access memory behind a device bus but not MMIO + registers, as there are no ordering guarantees with regard to other MMIO + accesses or even spinlocks. The byte order is generally the same as for normal + memory, so unlike the other functions, these can be used to copy data between + kernel memory and device memory. + +inl(), inw(), inb(), outl(), outw(), outb() + + PCI I/O port resources traditionally require separate helpers as they are + implemented using special instructions on the x86 architecture. On most other + architectures, these are mapped to readl()/writel() style accessors + internally, usually pointing to a fixed area in virtual memory. Instead of an + ``__iomem`` pointer, the address is a 32-bit integer token to identify a port + number. PCI requires I/O port access to be non-posted, meaning that an outb() + must complete before the following code executes, while a normal writeb() may + still be in progress. On architectures that correctly implement this, I/O port + access is therefore ordered against spinlocks. Many non-x86 PCI host bridge + implementations and CPU architectures however fail to implement non-posted I/O + space on PCI, so they can end up being posted on such hardware. + + In some architectures, the I/O port number space has a 1:1 mapping to + ``__iomem`` pointers, but this is not recommended and device drivers should + not rely on that for portability. Similarly, an I/O port number as described + in a PCI base address register may not correspond to the port number as seen + by a device driver. Portable drivers need to read the port number for the + resource provided by the kernel. + + There are no direct 64-bit I/O port accessors, but pci_iomap() in combination + with ioread64/iowrite64 can be used instead. + +inl_p(), inw_p(), inb_p(), outl_p(), outw_p(), outb_p() + + On ISA devices that require specific timing, the _p versions of the I/O + accessors add a small delay. On architectures that do not have ISA buses, + these are aliases to the normal inb/outb helpers. + +readsq, readsl, readsw, readsb +writesq, writesl, writesw, writesb +ioread64_rep, ioread32_rep, ioread16_rep, ioread8_rep +iowrite64_rep, iowrite32_rep, iowrite16_rep, iowrite8_rep +insl, insw, insb, outsl, outsw, outsb + + These are helpers that access the same address multiple times, usually to copy + data between kernel memory byte stream and a FIFO buffer. Unlike the normal + MMIO accessors, these do not perform a byteswap on big-endian kernels, so the + first byte in the FIFO register corresponds to the first byte in the memory + buffer regardless of the architecture. + +Device memory mapping modes +=========================== + +Some architectures support multiple modes for mapping device memory. +ioremap_*() variants provide a common abstraction around these +architecture-specific modes, with a shared set of semantics. + +ioremap() is the most common mapping type, and is applicable to typical device +memory (e.g. I/O registers). Other modes can offer weaker or stronger +guarantees, if supported by the architecture. From most to least common, they +are as follows: + +ioremap() +--------- + +The default mode, suitable for most memory-mapped devices, e.g. control +registers. Memory mapped using ioremap() has the following characteristics: + +* Uncached - CPU-side caches are bypassed, and all reads and writes are handled + directly by the device +* No speculative operations - the CPU may not issue a read or write to this + memory, unless the instruction that does so has been reached in committed + program flow. +* No reordering - The CPU may not reorder accesses to this memory mapping with + respect to each other. On some architectures, this relies on barriers in + readl_relaxed()/writel_relaxed(). +* No repetition - The CPU may not issue multiple reads or writes for a single + program instruction. +* No write-combining - Each I/O operation results in one discrete read or write + being issued to the device, and multiple writes are not combined into larger + writes. This may or may not be enforced when using __raw I/O accessors or + pointer dereferences. +* Non-executable - The CPU is not allowed to speculate instruction execution + from this memory (it probably goes without saying, but you're also not + allowed to jump into device memory). + +On many platforms and buses (e.g. PCI), writes issued through ioremap() +mappings are posted, which means that the CPU does not wait for the write to +actually reach the target device before retiring the write instruction. + +On many platforms, I/O accesses must be aligned with respect to the access +size; failure to do so will result in an exception or unpredictable results. + +ioremap_wc() +------------ + +Maps I/O memory as normal memory with write combining. Unlike ioremap(), + +* The CPU may speculatively issue reads from the device that the program + didn't actually execute, and may choose to basically read whatever it wants. +* The CPU may reorder operations as long as the result is consistent from the + program's point of view. +* The CPU may write to the same location multiple times, even when the program + issued a single write. +* The CPU may combine several writes into a single larger write. + +This mode is typically used for video framebuffers, where it can increase +performance of writes. It can also be used for other blocks of memory in +devices (e.g. buffers or shared memory), but care must be taken as accesses are +not guaranteed to be ordered with respect to normal ioremap() MMIO register +accesses without explicit barriers. + +On a PCI bus, it is usually safe to use ioremap_wc() on MMIO areas marked as +``IORESOURCE_PREFETCH``, but it may not be used on those without the flag. +For on-chip devices, there is no corresponding flag, but a driver can use +ioremap_wc() on a device that is known to be safe. + +ioremap_wt() +------------ + +Maps I/O memory as normal memory with write-through caching. Like ioremap_wc(), +but also, + +* The CPU may cache writes issued to and reads from the device, and serve reads + from that cache. + +This mode is sometimes used for video framebuffers, where drivers still expect +writes to reach the device in a timely manner (and not be stuck in the CPU +cache), but reads may be served from the cache for efficiency. However, it is +rarely useful these days, as framebuffer drivers usually perform writes only, +for which ioremap_wc() is more efficient (as it doesn't needlessly trash the +cache). Most drivers should not use this. + +ioremap_np() +------------ + +Like ioremap(), but explicitly requests non-posted write semantics. On some +architectures and buses, ioremap() mappings have posted write semantics, which +means that writes can appear to "complete" from the point of view of the +CPU before the written data actually arrives at the target device. Writes are +still ordered with respect to other writes and reads from the same device, but +due to the posted write semantics, this is not the case with respect to other +devices. ioremap_np() explicitly requests non-posted semantics, which means +that the write instruction will not appear to complete until the device has +received (and to some platform-specific extent acknowledged) the written data. + +This mapping mode primarily exists to cater for platforms with bus fabrics that +require this particular mapping mode to work correctly. These platforms set the +``IORESOURCE_MEM_NONPOSTED`` flag for a resource that requires ioremap_np() +semantics and portable drivers should use an abstraction that automatically +selects it where appropriate (see the `Higher-level ioremap abstractions`_ +section below). + +The bare ioremap_np() is only available on some architectures; on others, it +always returns NULL. Drivers should not normally use it, unless they are +platform-specific or they derive benefit from non-posted writes where +supported, and can fall back to ioremap() otherwise. The normal approach to +ensure posted write completion is to do a dummy read after a write as +explained in `Accessing the device`_, which works with ioremap() on all +platforms. + +ioremap_np() should never be used for PCI drivers. PCI memory space writes are +always posted, even on architectures that otherwise implement ioremap_np(). +Using ioremap_np() for PCI BARs will at best result in posted write semantics, +and at worst result in complete breakage. + +Note that non-posted write semantics are orthogonal to CPU-side ordering +guarantees. A CPU may still choose to issue other reads or writes before a +non-posted write instruction retires. See the previous section on MMIO access +functions for details on the CPU side of things. + +ioremap_uc() +------------ + +ioremap_uc() behaves like ioremap() except that on the x86 architecture without +'PAT' mode, it marks memory as uncached even when the MTRR has designated +it as cacheable, see Documentation/x86/pat.rst. + +Portable drivers should avoid the use of ioremap_uc(). + +ioremap_cache() +--------------- + +ioremap_cache() effectively maps I/O memory as normal RAM. CPU write-back +caches can be used, and the CPU is free to treat the device as if it were a +block of RAM. This should never be used for device memory which has side +effects of any kind, or which does not return the data previously written on +read. + +It should also not be used for actual RAM, as the returned pointer is an +``__iomem`` token. memremap() can be used for mapping normal RAM that is outside +of the linear kernel memory area to a regular pointer. + +Portable drivers should avoid the use of ioremap_cache(). + +Architecture example +-------------------- + +Here is how the above modes map to memory attribute settings on the ARM64 +architecture: + ++------------------------+--------------------------------------------+ +| API | Memory region type and cacheability | ++------------------------+--------------------------------------------+ +| ioremap_np() | Device-nGnRnE | ++------------------------+--------------------------------------------+ +| ioremap() | Device-nGnRE | ++------------------------+--------------------------------------------+ +| ioremap_uc() | (not implemented) | ++------------------------+--------------------------------------------+ +| ioremap_wc() | Normal-Non Cacheable | ++------------------------+--------------------------------------------+ +| ioremap_wt() | (not implemented; fallback to ioremap) | ++------------------------+--------------------------------------------+ +| ioremap_cache() | Normal-Write-Back Cacheable | ++------------------------+--------------------------------------------+ + +Higher-level ioremap abstractions +================================= + +Instead of using the above raw ioremap() modes, drivers are encouraged to use +higher-level APIs. These APIs may implement platform-specific logic to +automatically choose an appropriate ioremap mode on any given bus, allowing for +a platform-agnostic driver to work on those platforms without any special +cases. At the time of this writing, the following ioremap() wrappers have such +logic: + +devm_ioremap_resource() + + Can automatically select ioremap_np() over ioremap() according to platform + requirements, if the ``IORESOURCE_MEM_NONPOSTED`` flag is set on the struct + resource. Uses devres to automatically unmap the resource when the driver + probe() function fails or a device in unbound from its driver. + + Documented in Documentation/driver-api/driver-model/devres.rst. + +of_address_to_resource() + + Automatically sets the ``IORESOURCE_MEM_NONPOSTED`` flag for platforms that + require non-posted writes for certain buses (see the nonposted-mmio and + posted-mmio device tree properties). + +of_iomap() + + Maps the resource described in a ``reg`` property in the device tree, doing + all required translations. Automatically selects ioremap_np() according to + platform requirements, as above. + +pci_ioremap_bar(), pci_ioremap_wc_bar() + + Maps the resource described in a PCI base address without having to extract + the physical address first. + +pci_iomap(), pci_iomap_wc() + + Like pci_ioremap_bar()/pci_ioremap_bar(), but also works on I/O space when + used together with ioread32()/iowrite32() and similar accessors + +pcim_iomap() + + Like pci_iomap(), but uses devres to automatically unmap the resource when + the driver probe() function fails or a device in unbound from its driver + + Documented in Documentation/driver-api/driver-model/devres.rst. + +Not using these wrappers may make drivers unusable on certain platforms with +stricter rules for mapping I/O memory. + Public Functions Provided ========================= diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index a2133d69872c..7f37ec30d9fd 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -257,3 +257,79 @@ fences in the kernel. This means: userspace is allowed to use userspace fencing or long running compute workloads. This also means no implicit fencing for shared buffers in these cases. + +Recoverable Hardware Page Faults Implications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Modern hardware supports recoverable page faults, which has a lot of +implications for DMA fences. + +First, a pending page fault obviously holds up the work that's running on the +accelerator and a memory allocation is usually required to resolve the fault. +But memory allocations are not allowed to gate completion of DMA fences, which +means any workload using recoverable page faults cannot use DMA fences for +synchronization. Synchronization fences controlled by userspace must be used +instead. + +On GPUs this poses a problem, because current desktop compositor protocols on +Linux rely on DMA fences, which means without an entirely new userspace stack +built on top of userspace fences, they cannot benefit from recoverable page +faults. Specifically this means implicit synchronization will not be possible. +The exception is when page faults are only used as migration hints and never to +on-demand fill a memory request. For now this means recoverable page +faults on GPUs are limited to pure compute workloads. + +Furthermore GPUs usually have shared resources between the 3D rendering and +compute side, like compute units or command submission engines. If both a 3D +job with a DMA fence and a compute workload using recoverable page faults are +pending they could deadlock: + +- The 3D workload might need to wait for the compute job to finish and release + hardware resources first. + +- The compute workload might be stuck in a page fault, because the memory + allocation is waiting for the DMA fence of the 3D workload to complete. + +There are a few options to prevent this problem, one of which drivers need to +ensure: + +- Compute workloads can always be preempted, even when a page fault is pending + and not yet repaired. Not all hardware supports this. + +- DMA fence workloads and workloads which need page fault handling have + independent hardware resources to guarantee forward progress. This could be + achieved through e.g. through dedicated engines and minimal compute unit + reservations for DMA fence workloads. + +- The reservation approach could be further refined by only reserving the + hardware resources for DMA fence workloads when they are in-flight. This must + cover the time from when the DMA fence is visible to other threads up to + moment when fence is completed through dma_fence_signal(). + +- As a last resort, if the hardware provides no useful reservation mechanics, + all workloads must be flushed from the GPU when switching between jobs + requiring DMA fences or jobs requiring page fault handling: This means all DMA + fences must complete before a compute job with page fault handling can be + inserted into the scheduler queue. And vice versa, before a DMA fence can be + made visible anywhere in the system, all compute workloads must be preempted + to guarantee all pending GPU page faults are flushed. + +- Only a fairly theoretical option would be to untangle these dependencies when + allocating memory to repair hardware page faults, either through separate + memory blocks or runtime tracking of the full dependency graph of all DMA + fences. This results very wide impact on the kernel, since resolving the page + on the CPU side can itself involve a page fault. It is much more feasible and + robust to limit the impact of handling hardware page faults to the specific + driver. + +Note that workloads that run on independent hardware like copy engines or other +GPUs do not have any impact. This allows us to keep using DMA fences internally +in the kernel even for resolving hardware page faults, e.g. by using copy +engines to clear or copy memory needed to resolve the page fault. + +In some ways this page fault problem is a special case of the `Infinite DMA +Fences` discussions: Infinite fences from compute workloads are allowed to +depend on DMA fences, but not the other way around. And not even the page fault +problem is new, because some other CPU thread in userspace might +hit a page fault which holds up a userspace fence - supporting page faults on +GPUs doesn't anything fundamentally new. diff --git a/Documentation/driver-api/driver-model/class.rst b/Documentation/driver-api/driver-model/class.rst deleted file mode 100644 index fff55b80e86a..000000000000 --- a/Documentation/driver-api/driver-model/class.rst +++ /dev/null @@ -1,149 +0,0 @@ -============== -Device Classes -============== - -Introduction -~~~~~~~~~~~~ -A device class describes a type of device, like an audio or network -device. The following device classes have been identified: - -<Insert List of Device Classes Here> - - -Each device class defines a set of semantics and a programming interface -that devices of that class adhere to. Device drivers are the -implementation of that programming interface for a particular device on -a particular bus. - -Device classes are agnostic with respect to what bus a device resides -on. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The device class structure looks like:: - - - typedef int (*devclass_add)(struct device *); - typedef void (*devclass_remove)(struct device *); - -See the kerneldoc for the struct class. - -A typical device class definition would look like:: - - struct device_class input_devclass = { - .name = "input", - .add_device = input_add_device, - .remove_device = input_remove_device, - }; - -Each device class structure should be exported in a header file so it -can be used by drivers, extensions and interfaces. - -Device classes are registered and unregistered with the core using:: - - int devclass_register(struct device_class * cls); - void devclass_unregister(struct device_class * cls); - - -Devices -~~~~~~~ -As devices are bound to drivers, they are added to the device class -that the driver belongs to. Before the driver model core, this would -typically happen during the driver's probe() callback, once the device -has been initialized. It now happens after the probe() callback -finishes from the core. - -The device is enumerated in the class. Each time a device is added to -the class, the class's devnum field is incremented and assigned to the -device. The field is never decremented, so if the device is removed -from the class and re-added, it will receive a different enumerated -value. - -The class is allowed to create a class-specific structure for the -device and store it in the device's class_data pointer. - -There is no list of devices in the device class. Each driver has a -list of devices that it supports. The device class has a list of -drivers of that particular class. To access all of the devices in the -class, iterate over the device lists of each driver in the class. - - -Device Drivers -~~~~~~~~~~~~~~ -Device drivers are added to device classes when they are registered -with the core. A driver specifies the class it belongs to by setting -the struct device_driver::devclass field. - - -sysfs directory structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is a top-level sysfs directory named 'class'. - -Each class gets a directory in the class directory, along with two -default subdirectories:: - - class/ - `-- input - |-- devices - `-- drivers - - -Drivers registered with the class get a symlink in the drivers/ directory -that points to the driver's directory (under its bus directory):: - - class/ - `-- input - |-- devices - `-- drivers - `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ - - -Each device gets a symlink in the devices/ directory that points to the -device's directory in the physical hierarchy:: - - class/ - `-- input - |-- devices - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ - -:: - - struct devclass_attribute { - struct attribute attr; - ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); - ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); - }; - -Class drivers can export attributes using the DEVCLASS_ATTR macro that works -similarly to the DEVICE_ATTR macro for devices. For example, a definition -like this:: - - static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); - -is equivalent to declaring:: - - static devclass_attribute devclass_attr_debug; - -The bus driver can add and remove the attribute from the class's -sysfs directory using:: - - int devclass_create_file(struct device_class *, struct devclass_attribute *); - void devclass_remove_file(struct device_class *, struct devclass_attribute *); - -In the example above, the file will be named 'debug' in placed in the -class's directory in sysfs. - - -Interfaces -~~~~~~~~~~ -There may exist multiple mechanisms for accessing the same device of a -particular class type. Device interfaces describe these mechanisms. - -When a device is added to a device class, the core attempts to add it -to every interface that is registered with the device class. diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst index b9b022371e85..0833be568b06 100644 --- a/Documentation/driver-api/driver-model/device.rst +++ b/Documentation/driver-api/driver-model/device.rst @@ -63,8 +63,14 @@ Attributes are declared using a macro called DEVICE_ATTR:: Example::: - static DEVICE_ATTR(type, 0444, show_type, NULL); - static DEVICE_ATTR(power, 0644, show_power, store_power); + static DEVICE_ATTR(type, 0444, type_show, NULL); + static DEVICE_ATTR(power, 0644, power_show, power_store); + +Helper macros are available for common values of mode, so the above examples +can be simplified to::: + + static DEVICE_ATTR_RO(type); + static DEVICE_ATTR_RW(power); This declares two structures of type struct device_attribute with respective names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be @@ -76,19 +82,24 @@ organized as follows into a group:: NULL, }; - static struct attribute_group dev_attr_group = { + static struct attribute_group dev_group = { .attrs = dev_attrs, }; - static const struct attribute_group *dev_attr_groups[] = { - &dev_attr_group, + static const struct attribute_group *dev_groups[] = { + &dev_group, NULL, }; +A helper macro is available for the common case of a single group, so the +above two structures can be declared using::: + + ATTRIBUTE_GROUPS(dev); + This array of groups can then be associated with a device by setting the group pointer in struct device before device_register() is invoked:: - dev->groups = dev_attr_groups; + dev->groups = dev_groups; device_register(dev); The device_register() function will use the 'groups' pointer to create the diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index cd8b6e657b94..e0814d214048 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -285,7 +285,8 @@ I2C IIO devm_iio_device_alloc() devm_iio_device_register() - devm_iio_kfifo_allocate() + devm_iio_dmaengine_buffer_setup() + devm_iio_kfifo_buffer_setup() devm_iio_triggered_buffer_setup() devm_iio_trigger_alloc() devm_iio_trigger_register() @@ -309,6 +310,7 @@ IOMAP devm_ioremap() devm_ioremap_uc() devm_ioremap_wc() + devm_ioremap_np() devm_ioremap_resource() : checks resource, requests memory region, ioremaps devm_ioremap_resource_wc() devm_platform_ioremap_resource() : calls devm_ioremap_resource() for platform device diff --git a/Documentation/driver-api/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst index 755016422269..4831bdd92e5c 100644 --- a/Documentation/driver-api/driver-model/index.rst +++ b/Documentation/driver-api/driver-model/index.rst @@ -7,7 +7,6 @@ Driver Model binding bus - class design-patterns device devres diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst index 94dd7185e76e..2e924fb5b3d5 100644 --- a/Documentation/driver-api/gpio/intro.rst +++ b/Documentation/driver-api/gpio/intro.rst @@ -27,7 +27,7 @@ What is a GPIO? =============== A "General Purpose Input/Output" (GPIO) is a flexible software-controlled -digital signal. They are provided from many kinds of chip, and are familiar +digital signal. They are provided from many kinds of chips, and are familiar to Linux developers working with embedded and custom hardware. Each GPIO represents a bit connected to a particular pin, or "ball" on Ball Grid Array (BGA) packages. Board schematics show which external hardware connects to diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst index 3ddebddc02ca..e83026aebe97 100644 --- a/Documentation/driver-api/iio/buffers.rst +++ b/Documentation/driver-api/iio/buffers.rst @@ -28,24 +28,26 @@ IIO buffer setup The meta information associated with a channel reading placed in a buffer is called a scan element. The important bits configuring scan elements are exposed to userspace applications via the -:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains +:file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains attributes of the following form: * :file:`enable`, used for enabling a channel. If and only if its attribute is non *zero*, then a triggered capture will contain data samples for this channel. +* :file:`index`, the scan_index of the channel. * :file:`type`, description of the scan element data storage within the buffer and hence the form in which it is read from user space. - Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] . + Format is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift] . + * *be* or *le*, specifies big or little endian. * *s* or *u*, specifies if signed (2's complement) or unsigned. * *bits*, is the number of valid data bits. * *storagebits*, is the number of bits (after padding) that it occupies in the - buffer. - * *shift*, if specified, is the shift that needs to be applied prior to - masking out unused bits. + buffer. * *repeat*, specifies the number of bits/storagebits repetitions. When the - repeat element is 0 or 1, then the repeat value is omitted. + repeat element is 0 or 1, then the repeat value is omitted. + * *shift*, if specified, is the shift that needs to be applied prior to + masking out unused bits. For example, a driver for a 3-axis accelerometer with 12 bit resolution where data is stored in two 8-bits registers as follows:: @@ -122,4 +124,3 @@ More details .. kernel-doc:: include/linux/iio/buffer.h .. kernel-doc:: drivers/iio/industrialio-buffer.c :export: - diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 3fc378b3b269..7160336aa475 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -144,8 +144,7 @@ of the device. This is because the power state of the device is only changed after the power state transition has taken place. The ``s_ctrl`` callback can be used to obtain device's power state after the power state transition: -.. c:function:: - int pm_runtime_get_if_in_use(struct device *dev); +.. c:function:: int pm_runtime_get_if_in_use(struct device *dev); The function returns a non-zero value if it succeeded getting the power count or runtime PM was disabled, in either of which cases the driver may proceed to diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index c140692454b1..2ad71dfa8828 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -28,6 +28,8 @@ Please see: :maxdepth: 5 :numbered: + maintainer-entry-profile + v4l2-core dtv-core rc-core diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst new file mode 100644 index 000000000000..eb1cdfd280ba --- /dev/null +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst @@ -0,0 +1,206 @@ +Media Subsystem Profile +======================= + +Overview +-------- + +The media subsystem covers support for a variety of devices: stream +capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC +and media pipeline control. + +It covers, mainly, the contents of those directories: + + - drivers/media + - drivers/staging/media + - Documentation/admin-guide/media + - Documentation/driver-api/media + - Documentation/userspace-api/media + - Documentation/devicetree/bindings/media/\ [1]_ + - include/media + +.. [1] Device tree bindings are maintained by the + OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers + (see the MAINTAINERS file). So, changes there must be reviewed + by them before being merged via the media subsystem's development + tree. + +Both media userspace and Kernel APIs are documented and the documentation +must be kept in sync with the API changes. It means that all patches that +add new features to the subsystem must also bring changes to the +corresponding API files. + +Due to the size and wide scope of the media subsystem, media's +maintainership model is to have sub-maintainers that have a broad +knowledge of a specific aspect of the subsystem. It is the sub-maintainers' +task to review the patches, providing feedback to users if the patches are +following the subsystem rules and are properly using the media kernel and +userspace APIs. + +Patches for the media subsystem must be sent to the media mailing list +at linux-media@vger.kernel.org as plain text only e-mail. Emails with +HTML will be automatically rejected by the mail server. It could be wise +to also copy the sub-maintainer(s). + +Media's workflow is heavily based on Patchwork, meaning that, once a patch +is submitted, the e-mail will first be accepted by the mailing list +server, and, after a while, it should appear at: + + - https://patchwork.linuxtv.org/project/linux-media/list/ + +If it doesn't automatically appear there after a few minutes, then +probably something went wrong on your submission. Please check if the +email is in plain text\ [2]_ only and if your emailer is not mangling +whitespaces before complaining or submitting them again. + +You can check if the mailing list server accepted your patch, by looking at: + + - https://lore.kernel.org/linux-media/ + +.. [2] If your email contains HTML, the mailing list server will simply + drop it, without any further notice. + + +Media maintainers ++++++++++++++++++ + +At the media subsystem, we have a group of senior developers that +are responsible for doing the code reviews at the drivers (also known as +sub-maintainers), and another senior developer responsible for the +subsystem as a whole. For core changes, whenever possible, multiple +media maintainers do the review. + +The media maintainers that work on specific areas of the subsystem are: + +- Digital TV and remote controllers: + Sean Young <sean@mess.org> + +- HDMI CEC: + Hans Verkuil <hverkuil@xs4all.nl> + +- Media controller drivers: + Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: + Sakari Ailus <sakari.ailus@linux.intel.com> + +- V4L2 drivers and core V4L2 frameworks: + Hans Verkuil <hverkuil@xs4all.nl> + +The subsystem maintainer is: + Mauro Carvalho Chehab <mchehab@kernel.org> + +Media maintainers may delegate a patch to other media maintainers as needed. +On such case, checkpatch's ``delegate`` field indicates who's currently +responsible for reviewing a patch. + +Submit Checklist Addendum +------------------------- + +Patches that change the Open Firmware/Device Tree bindings must be +reviewed by the Device Tree maintainers. So, DT maintainers should be +Cc:ed when those are submitted via devicetree@vger.kernel.org mailing +list. + +There is a set of compliance tools at https://git.linuxtv.org/v4l-utils.git/ +that should be used in order to check if the drivers are properly +implementing the media APIs: + +==================== ======================================================= +Type Tool +==================== ======================================================= +V4L2 drivers\ [3]_ ``v4l2-compliance`` +V4L2 virtual drivers ``contrib/test/test-media`` +CEC drivers ``cec-compliance`` +==================== ======================================================= + +.. [3] The ``v4l2-compliance`` also covers the media controller usage inside + V4L2 drivers. + +Other compilance tools are under development to check other parts of the +subsystem. + +Those tests need to pass before the patches go upstream. + +Also, please notice that we build the Kernel with:: + + make CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 CHECK=check_script + +Where the check script is:: + + #!/bin/bash + /devel/smatch/smatch -p=kernel $@ >&2 + /devel/sparse/sparse $@ >&2 + +Be sure to not introduce new warnings on your patches without a +very good reason. + +Style Cleanup Patches ++++++++++++++++++++++ + +Style cleanups are welcome when they come together with other changes +at the files where the style changes will affect. + +We may accept pure standalone style cleanups, but they should ideally +be one patch for the whole subsystem (if the cleanup is low volume), +or at least be grouped per directory. So, for example, if you're doing a +big cleanup change set at drivers under drivers/media, please send a single +patch for all drivers under drivers/media/pci, another one for +drivers/media/usb and so on. + +Coding Style Addendum ++++++++++++++++++++++ + +Media development uses ``checkpatch.pl`` on strict mode to verify the code +style, e.g.:: + + $ ./scripts/checkpatch.pl --strict --max-line-length=80 + +In principle, patches should follow the coding style rules, but exceptions +are allowed if there are good reasons. On such case, maintainers and reviewers +may question about the rationale for not addressing the ``checkpatch.pl``. + +Please notice that the goal here is to improve code readability. On +a few cases, ``checkpatch.pl`` may actually point to something that would +look worse. So, you should use good sense. + +Note that addressing one ``checkpatch.pl`` issue (of any kind) alone may lead +to having longer lines than 80 characters per line. While this is not +strictly prohibited, efforts should be made towards staying within 80 +characters per line. This could include using re-factoring code that leads +to less indentation, shorter variable or function names and last but not +least, simply wrapping the lines. + +In particular, we accept lines with more than 80 columns: + + - on strings, as they shouldn't be broken due to line length limits; + - when a function or variable name need to have a big identifier name, + which keeps hard to honor the 80 columns limit; + - on arithmetic expressions, when breaking lines makes them harder to + read; + - when they avoid a line to end with an open parenthesis or an open + bracket. + +Key Cycle Dates +--------------- + +New submissions can be sent at any time, but if they intend to hit the +next merge window they should be sent before -rc5, and ideally stabilized +in the linux-media branch by -rc6. + +Review Cadence +-------------- + +Provided that your patch is at https://patchwork.linuxtv.org, it should +be sooner or later handled, so you don't need to re-submit a patch. + +Except for bug fixes, we don't usually add new patches to the development +tree between -rc6 and the next -rc1. + +Please notice that the media subsystem is a high traffic one, so it +could take a while for us to be able to review your patches. Feel free +to ping if you don't get a feedback in a couple of weeks or to ask +other developers to publicly add Reviewed-by and, more importantly, +``Tested-by:`` tags. + +Please note that we expect a detailed description for ``Tested-by:``, +identifying what boards were used at the test and what it was tested. diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 8b53da2f9c74..7736da077fb8 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -208,7 +208,7 @@ the needs of the driver. :c:func:`v4l2_async_notifier_add_i2c_subdev` are for bridge and ISP drivers for registering their async sub-devices with the notifier. -:c:func:`v4l2_async_register_subdev_sensor_common` is a helper function for +:c:func:`v4l2_async_register_subdev_sensor` is a helper function for sensor drivers registering their own async sub-device, but it also registers a notifier and further registers async sub-devices for lens and flash devices found in firmware. The notifier for the sub-device is unregistered with the @@ -252,7 +252,7 @@ contain several subdevs that use an I2C bus, but also a subdev that is controlled through GPIO pins. This distinction is only relevant when setting up the device, but once the subdev is registered it is completely transparent. -Once te subdev has been registered you can call an ops function either +Once the subdev has been registered you can call an ops function either directly: .. code-block:: c diff --git a/Documentation/driver-api/serial/cyclades_z.rst b/Documentation/driver-api/serial/cyclades_z.rst deleted file mode 100644 index 532ff67e2f1c..000000000000 --- a/Documentation/driver-api/serial/cyclades_z.rst +++ /dev/null @@ -1,11 +0,0 @@ -================ -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/ diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst index 33ad10d05b26..21351b8c95a4 100644 --- a/Documentation/driver-api/serial/index.rst +++ b/Documentation/driver-api/serial/index.rst @@ -17,7 +17,6 @@ Serial drivers .. toctree:: :maxdepth: 1 - cyclades_z moxa-smartio n_gsm rocket diff --git a/Documentation/driver-api/serial/rocket.rst b/Documentation/driver-api/serial/rocket.rst deleted file mode 100644 index 23761eae4282..000000000000 --- a/Documentation/driver-api/serial/rocket.rst +++ /dev/null @@ -1,185 +0,0 @@ -================================================ -Comtrol(tm) RocketPort(R)/RocketModem(TM) Series -================================================ - -Device Driver for the Linux Operating System -============================================ - -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 -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. - -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 -are in the included README and HW_INSTALL files. - -RocketPort ISA and RocketModem II PCI boards currently are only supported by -this driver in module form. - -The RocketPort ISA board requires I/O ports to be configured by the DIP -switches on the board. See the section "ISA Rocketport Boards" below for -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 - -There is a set of utilities and scripts provided with the external driver -(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 ------------------------ - -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 -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. - -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 -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 -"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:: - - > mknod /dev/ttyR0 c 46 0 - > mknod /dev/ttyR1 c 46 1 - > mknod /dev/ttyR2 c 46 2 - -The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) -for you:: - - >/dev/MAKEDEV ttyR - -ISA Rocketport Boards ---------------------- - -You must assign and configure the I/O addresses used by the ISA Rocketport -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 ------------------------ - -Before installing RocketPort(R) or RocketPort RA boards, you must find -a range of I/O addresses for it to use. The first RocketPort card -requires a 68-byte contiguous block of I/O addresses, starting at one -of the following: 0x100h, 0x140h, 0x180h, 0x200h, 0x240h, 0x280h, -0x300h, 0x340h, 0x380h. This I/O address must be reflected in the DIP -switches of *all* of the Rocketport cards. - -The second, third, and fourth RocketPort cards require a 64-byte -contiguous block of I/O addresses, starting at one of the following -I/O addresses: 0x100h, 0x140h, 0x180h, 0x1C0h, 0x200h, 0x240h, 0x280h, -0x2C0h, 0x300h, 0x340h, 0x380h, 0x3C0h. The I/O address used by the -second, third, and fourth Rocketport cards (if present) are set via -software control. The DIP switch settings for the I/O address must be -set to the value of the first Rocketport cards. - -In order to distinguish each of the card from the others, each card -must have a unique board ID set on the dip switches. The first -Rocketport board must be set with the DIP switches corresponding to -the first board, the second board must be set with the DIP switches -corresponding to the second board, etc. IMPORTANT: The board ID is -the only place where the DIP switch settings should differ between the -various Rocketport boards in a system. - -The I/O address range used by any of the RocketPort cards must not -conflict with any other cards in the system, including other -RocketPort cards. Below, you will find a list of commonly used I/O -address ranges which may be in use by other devices in your system. -On a Linux system, "cat /proc/ioports" will also be helpful in -identifying what I/O addresses are being used by devices on your -system. - -Remember, the FIRST RocketPort uses 68 I/O addresses. So, if you set it -for 0x100, it will occupy 0x100 to 0x143. This would mean that you -CAN NOT set the second, third or fourth board for address 0x140 since -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 --------------- - -For technical support, please provide the following -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 - -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/driver-api/surface_aggregator/client.rst b/Documentation/driver-api/surface_aggregator/client.rst index 26d13085a117..e519d374c378 100644 --- a/Documentation/driver-api/surface_aggregator/client.rst +++ b/Documentation/driver-api/surface_aggregator/client.rst @@ -248,7 +248,7 @@ This example defines a function .. code-block:: c - int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg); + static int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg); executing the specified request, with the controller passed in when calling said function. In this example, the argument is provided via the ``arg`` @@ -296,7 +296,7 @@ This invocation of the macro defines a function .. code-block:: c - int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret); + static int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret); executing the specified request, using the device IDs and controller given in the client device. The full list of such macros for client devices is: diff --git a/Documentation/driver-api/surface_aggregator/clients/dtx.rst b/Documentation/driver-api/surface_aggregator/clients/dtx.rst new file mode 100644 index 000000000000..e7e7c20007f0 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/clients/dtx.rst @@ -0,0 +1,718 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |__u16| replace:: :c:type:`__u16 <__u16>` +.. |sdtx_event| replace:: :c:type:`struct sdtx_event <sdtx_event>` +.. |sdtx_event_code| replace:: :c:type:`enum sdtx_event_code <sdtx_event_code>` +.. |sdtx_base_info| replace:: :c:type:`struct sdtx_base_info <sdtx_base_info>` +.. |sdtx_device_mode| replace:: :c:type:`struct sdtx_device_mode <sdtx_device_mode>` + +====================================================== +User-Space DTX (Clipboard Detachment System) Interface +====================================================== + +The ``surface_dtx`` driver is responsible for proper clipboard detachment +and re-attachment handling. To this end, it provides the ``/dev/surface/dtx`` +device file, through which it can interface with a user-space daemon. This +daemon is then ultimately responsible for determining and taking necessary +actions, such as unmounting devices attached to the base, +unloading/reloading the graphics-driver, user-notifications, etc. + +There are two basic communication principles used in this driver: Commands +(in other parts of the documentation also referred to as requests) and +events. Commands are sent to the EC and may have a different implications in +different contexts. Events are sent by the EC upon some internal state +change. Commands are always driver-initiated, whereas events are always +initiated by the EC. + +.. contents:: + +Nomenclature +============ + +* **Clipboard:** + The detachable upper part of the Surface Book, housing the screen and CPU. + +* **Base:** + The lower part of the Surface Book from which the clipboard can be + detached, optionally (model dependent) housing the discrete GPU (dGPU). + +* **Latch:** + The mechanism keeping the clipboard attached to the base in normal + operation and allowing it to be detached when requested. + +* **Silently ignored commands:** + The command is accepted by the EC as a valid command and acknowledged + (following the standard communication protocol), but the EC does not act + upon it, i.e. ignores it.e upper part of the + + +Detachment Process +================== + +Warning: This part of the documentation is based on reverse engineering and +testing and thus may contain errors or be incomplete. + +Latch States +------------ + +The latch mechanism has two major states: *open* and *closed*. In the +*closed* state (default), the clipboard is secured to the base, whereas in +the *open* state, the clipboard can be removed by a user. + +The latch can additionally be locked and, correspondingly, unlocked, which +can influence the detachment procedure. Specifically, this locking mechanism +is intended to prevent the dGPU, positioned in the base of the device, from +being hot-unplugged while in use. More details can be found in the +documentation for the detachment procedure below. By default, the latch is +unlocked. + +Detachment Procedure +-------------------- + +Note that the detachment process is governed fully by the EC. The +``surface_dtx`` driver only relays events from the EC to user-space and +commands from user-space to the EC, i.e. it does not influence this process. + +The detachment process is started with the user pressing the *detach* button +on the base of the device or executing the ``SDTX_IOCTL_LATCH_REQUEST`` IOCTL. +Following that: + +1. The EC turns on the indicator led on the detach-button, sends a + *detach-request* event (``SDTX_EVENT_REQUEST``), and awaits further + instructions/commands. In case the latch is unlocked, the led will flash + green. If the latch has been locked, the led will be solid red + +2. The event is, via the ``surface_dtx`` driver, relayed to user-space, where + an appropriate user-space daemon can handle it and send instructions back + to the EC via IOCTLs provided by this driver. + +3. The EC waits for instructions from user-space and acts according to them. + If the EC does not receive any instructions in a given period, it will + time out and continue as follows: + + - If the latch is unlocked, the EC will open the latch and the clipboard + can be detached from the base. This is the exact behavior as without + this driver or any user-space daemon. See the ``SDTX_IOCTL_LATCH_CONFIRM`` + description below for more details on the follow-up behavior of the EC. + + - If the latch is locked, the EC will *not* open the latch, meaning the + clipboard cannot be detached from the base. Furthermore, the EC sends + an cancel event (``SDTX_EVENT_CANCEL``) detailing this with the cancel + reason ``SDTX_DETACH_TIMEDOUT`` (see :ref:`events` for details). + +Valid responses by a user-space daemon to a detachment request event are: + +- Execute ``SDTX_IOCTL_LATCH_REQUEST``. This will immediately abort the + detachment process. Furthermore, the EC will send a detach-request event, + similar to the user pressing the detach-button to cancel said process (see + below). + +- Execute ``SDTX_IOCTL_LATCH_CONFIRM``. This will cause the EC to open the + latch, after which the user can separate clipboard and base. + + As this changes the latch state, a *latch-status* event + (``SDTX_EVENT_LATCH_STATUS``) will be sent once the latch has been opened + successfully. If the EC fails to open the latch, e.g. due to hardware + error or low battery, a latch-cancel event (``SDTX_EVENT_CANCEL``) will be + sent with the cancel reason indicating the specific failure. + + If the latch is currently locked, the latch will automatically be + unlocked before it is opened. + +- Execute ``SDTX_IOCTL_LATCH_HEARTBEAT``. This will reset the internal timeout. + No other actions will be performed, i.e. the detachment process will neither + be completed nor canceled, and the EC will still be waiting for further + responses. + +- Execute ``SDTX_IOCTL_LATCH_CANCEL``. This will abort the detachment process, + similar to ``SDTX_IOCTL_LATCH_REQUEST``, described above, or the button + press, described below. A *generic request* event (``SDTX_EVENT_REQUEST``) + is send in response to this. In contrast to those, however, this command + does not trigger a new detachment process if none is currently in + progress. + +- Do nothing. The detachment process eventually times out as described in + point 3. + +See :ref:`ioctls` for more details on these responses. + +It is important to note that, if the user presses the detach button at any +point when a detachment operation is in progress (i.e. after the EC has sent +the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it +received the corresponding response concluding the process), the detachment +process is canceled on the EC-level and an identical event is being sent. +Thus a *detach-request* event, by itself, does not signal the start of the +detachment process. + +The detachment process may further be canceled by the EC due to hardware +failures or a low clipboard battery. This is done via a cancel event +(``SDTX_EVENT_CANCEL``) with the corresponding cancel reason. + + +User-Space Interface Documentation +================================== + +Error Codes and Status Values +----------------------------- + +Error and status codes are divided into different categories, which can be +used to determine if the status code is an error, and, if it is, the +severity and type of that error. The current categories are: + +.. flat-table:: Overview of Status/Error Categories. + :widths: 2 1 3 + :header-rows: 1 + + * - Name + - Value + - Short Description + + * - ``STATUS`` + - ``0x0000`` + - Non-error status codes. + + * - ``RUNTIME_ERROR`` + - ``0x1000`` + - Non-critical runtime errors. + + * - ``HARDWARE_ERROR`` + - ``0x2000`` + - Critical hardware failures. + + * - ``UNKNOWN`` + - ``0xF000`` + - Unknown error codes. + +Other categories are reserved for future use. The ``SDTX_CATEGORY()`` macro +can be used to determine the category of any status value. The +``SDTX_SUCCESS()`` macro can be used to check if the status value is a +success value (``SDTX_CATEGORY_STATUS``) or if it indicates a failure. + +Unknown status or error codes sent by the EC are assigned to the ``UNKNOWN`` +category by the driver and may be implemented via their own code in the +future. + +Currently used error codes are: + +.. flat-table:: Overview of Error Codes. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Category + - Value + - Short Description + + * - ``SDTX_DETACH_NOT_FEASIBLE`` + - ``RUNTIME`` + - ``0x1001`` + - Detachment not feasible due to low clipboard battery. + + * - ``SDTX_DETACH_TIMEDOUT`` + - ``RUNTIME`` + - ``0x1002`` + - Detachment process timed out while the latch was locked. + + * - ``SDTX_ERR_FAILED_TO_OPEN`` + - ``HARDWARE`` + - ``0x2001`` + - Failed to open latch. + + * - ``SDTX_ERR_FAILED_TO_REMAIN_OPEN`` + - ``HARDWARE`` + - ``0x2002`` + - Failed to keep latch open. + + * - ``SDTX_ERR_FAILED_TO_CLOSE`` + - ``HARDWARE`` + - ``0x2003`` + - Failed to close latch. + +Other error codes are reserved for future use. Non-error status codes may +overlap and are generally only unique within their use-case: + +.. flat-table:: Latch Status Codes. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Category + - Value + - Short Description + + * - ``SDTX_LATCH_CLOSED`` + - ``STATUS`` + - ``0x0000`` + - Latch is closed/has been closed. + + * - ``SDTX_LATCH_OPENED`` + - ``STATUS`` + - ``0x0001`` + - Latch is open/has been opened. + +.. flat-table:: Base State Codes. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Category + - Value + - Short Description + + * - ``SDTX_BASE_DETACHED`` + - ``STATUS`` + - ``0x0000`` + - Base has been detached/is not present. + + * - ``SDTX_BASE_ATTACHED`` + - ``STATUS`` + - ``0x0001`` + - Base has been attached/is present. + +Again, other codes are reserved for future use. + +.. _events: + +Events +------ + +Events can be received by reading from the device file. They are disabled by +default and have to be enabled by executing ``SDTX_IOCTL_EVENTS_ENABLE`` +first. All events follow the layout prescribed by |sdtx_event|. Specific +event types can be identified by their event code, described in +|sdtx_event_code|. Note that other event codes are reserved for future use, +thus an event parser must be able to handle any unknown/unsupported event +types gracefully, by relying on the payload length given in the event header. + +Currently provided event types are: + +.. flat-table:: Overview of DTX events. + :widths: 2 1 1 3 + :header-rows: 1 + + * - Name + - Code + - Payload + - Short Description + + * - ``SDTX_EVENT_REQUEST`` + - ``1`` + - ``0`` bytes + - Detachment process initiated/aborted. + + * - ``SDTX_EVENT_CANCEL`` + - ``2`` + - ``2`` bytes + - EC canceled detachment process. + + * - ``SDTX_EVENT_BASE_CONNECTION`` + - ``3`` + - ``4`` bytes + - Base connection state changed. + + * - ``SDTX_EVENT_LATCH_STATUS`` + - ``4`` + - ``2`` bytes + - Latch status changed. + + * - ``SDTX_EVENT_DEVICE_MODE`` + - ``5`` + - ``2`` bytes + - Device mode changed. + +Individual events in more detail: + +``SDTX_EVENT_REQUEST`` +^^^^^^^^^^^^^^^^^^^^^^ + +Sent when a detachment process is started or, if in progress, aborted by the +user, either via a detach button press or a detach request +(``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space. + +Does not have any payload. + +``SDTX_EVENT_CANCEL`` +^^^^^^^^^^^^^^^^^^^^^ + +Sent when a detachment process is canceled by the EC due to unfulfilled +preconditions (e.g. clipboard battery too low to detach) or hardware +failure. The reason for cancellation is given in the event payload detailed +below and can be one of + +* ``SDTX_DETACH_TIMEDOUT``: Detachment timed out while the latch was locked. + The latch has neither been opened nor unlocked. + +* ``SDTX_DETACH_NOT_FEASIBLE``: Detachment not feasible due to low clipboard + battery. + +* ``SDTX_ERR_FAILED_TO_OPEN``: Could not open the latch (hardware failure). + +* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``: Could not keep the latch open (hardware + failure). + +* ``SDTX_ERR_FAILED_TO_CLOSE``: Could not close the latch (hardware failure). + +Other error codes in this context are reserved for future use. + +These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern +between critical hardware errors (``SDTX_CATEGORY_HARDWARE_ERROR``) or +runtime errors (``SDTX_CATEGORY_RUNTIME_ERROR``), the latter of which may +happen during normal operation if certain preconditions for detachment are +not given. + +.. flat-table:: Detachment Cancel Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``reason`` + - |__u16| + - Reason for cancellation. + +``SDTX_EVENT_BASE_CONNECTION`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent when the base connection state has changed, i.e. when the base has been +attached, detached, or detachment has become infeasible due to low clipboard +battery. The new state and, if a base is connected, ID of the base is +provided as payload of type |sdtx_base_info| with its layout presented +below: + +.. flat-table:: Base-Connection-Change Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``state`` + - |__u16| + - Base connection state. + + * - ``base_id`` + - |__u16| + - Type of base connected (zero if none). + +Possible values for ``state`` are: + +* ``SDTX_BASE_DETACHED``, +* ``SDTX_BASE_ATTACHED``, and +* ``SDTX_DETACH_NOT_FEASIBLE``. + +Other values are reserved for future use. + +``SDTX_EVENT_LATCH_STATUS`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent when the latch status has changed, i.e. when the latch has been opened, +closed, or an error occurred. The current status is provided as payload: + +.. flat-table:: Latch-Status-Change Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``status`` + - |__u16| + - Latch status. + +Possible values for ``status`` are: + +* ``SDTX_LATCH_CLOSED``, +* ``SDTX_LATCH_OPENED``, +* ``SDTX_ERR_FAILED_TO_OPEN``, +* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and +* ``SDTX_ERR_FAILED_TO_CLOSE``. + +Other values are reserved for future use. + +``SDTX_EVENT_DEVICE_MODE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sent when the device mode has changed. The new device mode is provided as +payload: + +.. flat-table:: Device-Mode-Change Event Payload + :widths: 1 1 4 + :header-rows: 1 + + * - Field + - Type + - Description + + * - ``mode`` + - |__u16| + - Device operation mode. + +Possible values for ``mode`` are: + +* ``SDTX_DEVICE_MODE_TABLET``, +* ``SDTX_DEVICE_MODE_LAPTOP``, and +* ``SDTX_DEVICE_MODE_STUDIO``. + +Other values are reserved for future use. + +.. _ioctls: + +IOCTLs +------ + +The following IOCTLs are provided: + +.. flat-table:: Overview of DTX IOCTLs + :widths: 1 1 1 1 4 + :header-rows: 1 + + * - Type + - Number + - Direction + - Name + - Description + + * - ``0xA5`` + - ``0x21`` + - ``-`` + - ``EVENTS_ENABLE`` + - Enable events for the current file descriptor. + + * - ``0xA5`` + - ``0x22`` + - ``-`` + - ``EVENTS_DISABLE`` + - Disable events for the current file descriptor. + + * - ``0xA5`` + - ``0x23`` + - ``-`` + - ``LATCH_LOCK`` + - Lock the latch. + + * - ``0xA5`` + - ``0x24`` + - ``-`` + - ``LATCH_UNLOCK`` + - Unlock the latch. + + * - ``0xA5`` + - ``0x25`` + - ``-`` + - ``LATCH_REQUEST`` + - Request clipboard detachment. + + * - ``0xA5`` + - ``0x26`` + - ``-`` + - ``LATCH_CONFIRM`` + - Confirm clipboard detachment request. + + * - ``0xA5`` + - ``0x27`` + - ``-`` + - ``LATCH_HEARTBEAT`` + - Send heartbeat signal to EC. + + * - ``0xA5`` + - ``0x28`` + - ``-`` + - ``LATCH_CANCEL`` + - Cancel detachment process. + + * - ``0xA5`` + - ``0x29`` + - ``R`` + - ``GET_BASE_INFO`` + - Get current base/connection information. + + * - ``0xA5`` + - ``0x2A`` + - ``R`` + - ``GET_DEVICE_MODE`` + - Get current device operation mode. + + * - ``0xA5`` + - ``0x2B`` + - ``R`` + - ``GET_LATCH_STATUS`` + - Get current device latch status. + +``SDTX_IOCTL_EVENTS_ENABLE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x22)``. + +Enable events for the current file descriptor. Events can be obtained by +reading from the device, if enabled. Events are disabled by default. + +``SDTX_IOCTL_EVENTS_DISABLE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x22)``. + +Disable events for the current file descriptor. Events can be obtained by +reading from the device, if enabled. Events are disabled by default. + +``SDTX_IOCTL_LATCH_LOCK`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x23)``. + +Locks the latch, causing the detachment procedure to abort without opening +the latch on timeout. The latch is unlocked by default. This command will be +silently ignored if the latch is already locked. + +``SDTX_IOCTL_LATCH_UNLOCK`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x24)``. + +Unlocks the latch, causing the detachment procedure to open the latch on +timeout. The latch is unlocked by default. This command will not open the +latch when sent during an ongoing detachment process. It will be silently +ignored if the latch is already unlocked. + +``SDTX_IOCTL_LATCH_REQUEST`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x25)``. + +Generic latch request. Behavior depends on the context: If no +detachment-process is active, detachment is requested. Otherwise the +currently active detachment-process will be aborted. + +If a detachment process is canceled by this operation, a generic detachment +request event (``SDTX_EVENT_REQUEST``) will be sent. + +This essentially behaves the same as a detachment button press. + +``SDTX_IOCTL_LATCH_CONFIRM`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x26)``. + +Acknowledges and confirms a latch request. If sent during an ongoing +detachment process, this command causes the latch to be opened immediately. +The latch will also be opened if it has been locked. In this case, the latch +lock is reset to the unlocked state. + +This command will be silently ignored if there is currently no detachment +procedure in progress. + +``SDTX_IOCTL_LATCH_HEARTBEAT`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x27)``. + +Sends a heartbeat, essentially resetting the detachment timeout. This +command can be used to keep the detachment process alive while work required +for the detachment to succeed is still in progress. + +This command will be silently ignored if there is currently no detachment +procedure in progress. + +``SDTX_IOCTL_LATCH_CANCEL`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IO(0xA5, 0x28)``. + +Cancels detachment in progress (if any). If a detachment process is canceled +by this operation, a generic detachment request event +(``SDTX_EVENT_REQUEST``) will be sent. + +This command will be silently ignored if there is currently no detachment +procedure in progress. + +``SDTX_IOCTL_GET_BASE_INFO`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IOR(0xA5, 0x29, struct sdtx_base_info)``. + +Get the current base connection state (i.e. attached/detached) and the type +of the base connected to the clipboard. This is command essentially provides +a way to query the information provided by the base connection change event +(``SDTX_EVENT_BASE_CONNECTION``). + +Possible values for ``struct sdtx_base_info.state`` are: + +* ``SDTX_BASE_DETACHED``, +* ``SDTX_BASE_ATTACHED``, and +* ``SDTX_DETACH_NOT_FEASIBLE``. + +Other values are reserved for future use. + +``SDTX_IOCTL_GET_DEVICE_MODE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IOR(0xA5, 0x2A, __u16)``. + +Returns the device operation mode, indicating if and how the base is +attached to the clipboard. This is command essentially provides a way to +query the information provided by the device mode change event +(``SDTX_EVENT_DEVICE_MODE``). + +Returned values are: + +* ``SDTX_DEVICE_MODE_LAPTOP`` +* ``SDTX_DEVICE_MODE_TABLET`` +* ``SDTX_DEVICE_MODE_STUDIO`` + +See |sdtx_device_mode| for details. Other values are reserved for future +use. + + +``SDTX_IOCTL_GET_LATCH_STATUS`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Defined as ``_IOR(0xA5, 0x2B, __u16)``. + +Get the current latch status or (presumably) the last error encountered when +trying to open/close the latch. This is command essentially provides a way +to query the information provided by the latch status change event +(``SDTX_EVENT_LATCH_STATUS``). + +Returned values are: + +* ``SDTX_LATCH_CLOSED``, +* ``SDTX_LATCH_OPENED``, +* ``SDTX_ERR_FAILED_TO_OPEN``, +* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and +* ``SDTX_ERR_FAILED_TO_CLOSE``. + +Other values are reserved for future use. + +A Note on Base IDs +------------------ + +Base types/IDs provided via ``SDTX_EVENT_BASE_CONNECTION`` or +``SDTX_IOCTL_GET_BASE_INFO`` are directly forwarded from the EC in the lower +byte of the combined |__u16| value, with the driver storing the EC type from +which this ID comes in the high byte (without this, base IDs over different +types of ECs may be overlapping). + +The ``SDTX_DEVICE_TYPE()`` macro can be used to determine the EC device +type. This can be one of + +* ``SDTX_DEVICE_TYPE_HID``, for Surface Aggregator Module over HID, and + +* ``SDTX_DEVICE_TYPE_SSH``, for Surface Aggregator Module over Surface Serial + Hub. + +Note that currently only the ``SSH`` type EC is supported, however ``HID`` +type is reserved for future use. + +Structures and Enums +-------------------- + +.. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h + +API Users +========= + +A user-space daemon utilizing this API can be found at +https://github.com/linux-surface/surface-dtx-daemon. diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst index 3ccabce23271..98ea9946b8a2 100644 --- a/Documentation/driver-api/surface_aggregator/clients/index.rst +++ b/Documentation/driver-api/surface_aggregator/clients/index.rst @@ -11,6 +11,7 @@ This is the documentation for client drivers themselves. Refer to :maxdepth: 1 cdev + dtx san .. only:: subproject and html diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 078e981e2b16..543e70434da2 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -109,15 +109,16 @@ well as to make sure they aren't relying on some HCD-specific behavior. USB-Standard Types ================== -In ``<linux/usb/ch9.h>`` you will find the USB data types defined in -chapter 9 of the USB specification. These data types are used throughout -USB, and in APIs including this host side API, gadget APIs, usb character -devices and debugfs interfaces. +In ``drivers/usb/common/common.c`` and ``drivers/usb/common/debug.c`` you +will find the USB data types defined in chapter 9 of the USB specification. +These data types are used throughout USB, and in APIs including this host +side API, gadget APIs, usb character devices and debugfs interfaces. -.. kernel-doc:: include/linux/usb/ch9.h - :internal: +.. kernel-doc:: drivers/usb/common/common.c + :export: -.. _usb_header: +.. kernel-doc:: drivers/usb/common/debug.c + :export: Host-Side Data Types and Macros =============================== diff --git a/Documentation/driver-api/xilinx/eemi.rst b/Documentation/driver-api/xilinx/eemi.rst index 9dcbc6f18d75..c1bc47b9000d 100644 --- a/Documentation/driver-api/xilinx/eemi.rst +++ b/Documentation/driver-api/xilinx/eemi.rst @@ -16,35 +16,8 @@ components running across different processing clusters on a chip or device to communicate with a power management controller (PMC) on a device to issue or respond to power management requests. -EEMI ops is a structure containing all eemi APIs supported by Zynq MPSoC. -The zynqmp-firmware driver maintain all EEMI APIs in zynqmp_eemi_ops -structure. Any driver who want to communicate with PMC using EEMI APIs -can call zynqmp_pm_get_eemi_ops(). - -Example of EEMI ops:: - - /* zynqmp-firmware driver maintain all EEMI APIs */ - struct zynqmp_eemi_ops { - int (*get_api_version)(u32 *version); - int (*query_data)(struct zynqmp_pm_query_data qdata, u32 *out); - }; - - static const struct zynqmp_eemi_ops eemi_ops = { - .get_api_version = zynqmp_pm_get_api_version, - .query_data = zynqmp_pm_query_data, - }; - -Example of EEMI ops usage:: - - static const struct zynqmp_eemi_ops *eemi_ops; - u32 ret_payload[PAYLOAD_ARG_CNT]; - int ret; - - eemi_ops = zynqmp_pm_get_eemi_ops(); - if (IS_ERR(eemi_ops)) - return PTR_ERR(eemi_ops); - - ret = eemi_ops->query_data(qdata, ret_payload); +Any driver who wants to communicate with PMC using EEMI APIs use the +functions provided for each function. IOCTL ------ diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 57f66de2f7e1..212f7003cfba 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -207,9 +207,9 @@ Documentation/driver-api/console.rst. To summarize: Echo a value to the bind file that represents the framebuffer console driver. So assuming vtcon1 represents fbcon, then:: - echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to + echo 1 > /sys/class/vtconsole/vtcon1/bind - attach framebuffer console to console layer - echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from + echo 0 > /sys/class/vtconsole/vtcon1/bind - detach framebuffer console from console layer If fbcon is detached from the console layer, your boot console driver (which is diff --git a/Documentation/features/arch-support.txt b/Documentation/features/arch-support.txt index d22a1095e661..118ae031840b 100644 --- a/Documentation/features/arch-support.txt +++ b/Documentation/features/arch-support.txt @@ -8,4 +8,5 @@ The meaning of entries in the tables is: | ok | # feature supported by the architecture |TODO| # feature not yet supported by the architecture | .. | # feature cannot be supported by the hardware + | N/A| # feature doesn't apply to the architecture diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 48a5ca548399..e1c3a4c4d107 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | + | arm64: | N/A | | csky: | TODO | | h8300: | .. | | hexagon: | TODO | diff --git a/Documentation/filesystems/api-summary.rst b/Documentation/filesystems/api-summary.rst index a94f17d9b836..7e5c04c98619 100644 --- a/Documentation/filesystems/api-summary.rst +++ b/Documentation/filesystems/api-summary.rst @@ -101,6 +101,9 @@ Other Functions .. kernel-doc:: fs/xattr.c :export: +.. kernel-doc:: fs/namespace.c + :export: + The proc filesystem =================== @@ -122,6 +125,12 @@ Events based on file descriptors .. kernel-doc:: fs/eventfd.c :export: +eventpoll (epoll) interfaces +============================ + +.. kernel-doc:: fs/eventpoll.c + :internal: + The Filesystem for Exporting Kernel Objects =========================================== diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 1f76b1cb3348..d4853cb919d2 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -53,6 +53,7 @@ filesystem implementations. journalling fscrypt fsverity + netfs_library Filesystems =========== diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index b7dcc86c92a4..1e894480115b 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -80,13 +80,16 @@ prototypes:: struct file *, unsigned open_flag, umode_t create_mode); int (*tmpfile) (struct inode *, struct dentry *, umode_t); + int (*fileattr_set)(struct user_namespace *mnt_userns, + struct dentry *dentry, struct fileattr *fa); + int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); locking rules: all may block -============ ============================================= +============= ============================================= ops i_rwsem(inode) -============ ============================================= +============= ============================================= lookup: shared create: exclusive link: exclusive (both) @@ -107,7 +110,9 @@ fiemap: no update_time: no atomic_open: shared (exclusive if O_CREAT is set in open flags) tmpfile: no -============ ============================================= +fileattr_get: no or exclusive +fileattr_set: exclusive +============= ============================================= Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem @@ -469,7 +474,6 @@ prototypes:: int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *); void (*unlock_native_capacity) (struct gendisk *); - int (*revalidate_disk) (struct gendisk *); int (*getgeo)(struct block_device *, struct hd_geometry *); void (*swap_slot_free_notify) (struct block_device *, unsigned long); @@ -484,7 +488,6 @@ ioctl: no compat_ioctl: no direct_access: no unlock_native_capacity: no -revalidate_disk: no getgeo: no swap_slot_free_notify: no (see below) ======================= =================== diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst new file mode 100644 index 000000000000..57a641847818 --- /dev/null +++ b/Documentation/filesystems/netfs_library.rst @@ -0,0 +1,526 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +NETWORK FILESYSTEM HELPER LIBRARY +================================= + +.. Contents: + + - Overview. + - Buffered read helpers. + - Read helper functions. + - Read helper structures. + - Read helper operations. + - Read helper procedure. + - Read helper cache API. + + +Overview +======== + +The network filesystem helper library is a set of functions designed to aid a +network filesystem in implementing VM/VFS operations. For the moment, that +just includes turning various VM buffered read operations into requests to read +from the server. The helper library, however, can also interpose other +services, such as local caching or local data encryption. + +Note that the library module doesn't link against local caching directly, so +access must be provided by the netfs. + + +Buffered Read Helpers +===================== + +The library provides a set of read helpers that handle the ->readpage(), +->readahead() and much of the ->write_begin() VM operations and translate them +into a common call framework. + +The following services are provided: + + * Handles transparent huge pages (THPs). + + * Insulates the netfs from VM interface changes. + + * Allows the netfs to arbitrarily split reads up into pieces, even ones that + don't match page sizes or page alignments and that may cross pages. + + * Allows the netfs to expand a readahead request in both directions to meet + its needs. + + * Allows the netfs to partially fulfil a read, which will then be resubmitted. + + * Handles local caching, allowing cached data and server-read data to be + interleaved for a single request. + + * Handles clearing of bufferage that aren't on the server. + + * Handle retrying of reads that failed, switching reads from the cache to the + server as necessary. + + * In the future, this is a place that other services can be performed, such as + local encryption of data to be stored remotely or in the cache. + +From the network filesystem, the helpers require a table of operations. This +includes a mandatory method to issue a read operation along with a number of +optional methods. + + +Read Helper Functions +--------------------- + +Three read helpers are provided:: + + * void netfs_readahead(struct readahead_control *ractl, + const struct netfs_read_request_ops *ops, + void *netfs_priv);`` + * int netfs_readpage(struct file *file, + struct page *page, + const struct netfs_read_request_ops *ops, + void *netfs_priv); + * int netfs_write_begin(struct file *file, + struct address_space *mapping, + loff_t pos, + unsigned int len, + unsigned int flags, + struct page **_page, + void **_fsdata, + const struct netfs_read_request_ops *ops, + void *netfs_priv); + +Each corresponds to a VM operation, with the addition of a couple of parameters +for the use of the read helpers: + + * ``ops`` + + A table of operations through which the helpers can talk to the filesystem. + + * ``netfs_priv`` + + Filesystem private data (can be NULL). + +Both of these values will be stored into the read request structure. + +For ->readahead() and ->readpage(), the network filesystem should just jump +into the corresponding read helper; whereas for ->write_begin(), it may be a +little more complicated as the network filesystem might want to flush +conflicting writes or track dirty data and needs to put the acquired page if an +error occurs after calling the helper. + +The helpers manage the read request, calling back into the network filesystem +through the suppplied table of operations. Waits will be performed as +necessary before returning for helpers that are meant to be synchronous. + +If an error occurs and netfs_priv is non-NULL, ops->cleanup() will be called to +deal with it. If some parts of the request are in progress when an error +occurs, the request will get partially completed if sufficient data is read. + +Additionally, there is:: + + * void netfs_subreq_terminated(struct netfs_read_subrequest *subreq, + ssize_t transferred_or_error, + bool was_async); + +which should be called to complete a read subrequest. This is given the number +of bytes transferred or a negative error code, plus a flag indicating whether +the operation was asynchronous (ie. whether the follow-on processing can be +done in the current context, given this may involve sleeping). + + +Read Helper Structures +---------------------- + +The read helpers make use of a couple of structures to maintain the state of +the read. The first is a structure that manages a read request as a whole:: + + struct netfs_read_request { + struct inode *inode; + struct address_space *mapping; + struct netfs_cache_resources cache_resources; + void *netfs_priv; + loff_t start; + size_t len; + loff_t i_size; + const struct netfs_read_request_ops *netfs_ops; + unsigned int debug_id; + ... + }; + +The above fields are the ones the netfs can use. They are: + + * ``inode`` + * ``mapping`` + + The inode and the address space of the file being read from. The mapping + may or may not point to inode->i_data. + + * ``cache_resources`` + + Resources for the local cache to use, if present. + + * ``netfs_priv`` + + The network filesystem's private data. The value for this can be passed in + to the helper functions or set during the request. The ->cleanup() op will + be called if this is non-NULL at the end. + + * ``start`` + * ``len`` + + The file position of the start of the read request and the length. These + may be altered by the ->expand_readahead() op. + + * ``i_size`` + + The size of the file at the start of the request. + + * ``netfs_ops`` + + A pointer to the operation table. The value for this is passed into the + helper functions. + + * ``debug_id`` + + A number allocated to this operation that can be displayed in trace lines + for reference. + + +The second structure is used to manage individual slices of the overall read +request:: + + struct netfs_read_subrequest { + struct netfs_read_request *rreq; + loff_t start; + size_t len; + size_t transferred; + unsigned long flags; + unsigned short debug_index; + ... + }; + +Each subrequest is expected to access a single source, though the helpers will +handle falling back from one source type to another. The members are: + + * ``rreq`` + + A pointer to the read request. + + * ``start`` + * ``len`` + + The file position of the start of this slice of the read request and the + length. + + * ``transferred`` + + The amount of data transferred so far of the length of this slice. The + network filesystem or cache should start the operation this far into the + slice. If a short read occurs, the helpers will call again, having updated + this to reflect the amount read so far. + + * ``flags`` + + Flags pertaining to the read. There are two of interest to the filesystem + or cache: + + * ``NETFS_SREQ_CLEAR_TAIL`` + + This can be set to indicate that the remainder of the slice, from + transferred to len, should be cleared. + + * ``NETFS_SREQ_SEEK_DATA_READ`` + + This is a hint to the cache that it might want to try skipping ahead to + the next data (ie. using SEEK_DATA). + + * ``debug_index`` + + A number allocated to this slice that can be displayed in trace lines for + reference. + + +Read Helper Operations +---------------------- + +The network filesystem must provide the read helpers with a table of operations +through which it can issue requests and negotiate:: + + struct netfs_read_request_ops { + void (*init_rreq)(struct netfs_read_request *rreq, struct file *file); + bool (*is_cache_enabled)(struct inode *inode); + int (*begin_cache_operation)(struct netfs_read_request *rreq); + void (*expand_readahead)(struct netfs_read_request *rreq); + bool (*clamp_length)(struct netfs_read_subrequest *subreq); + void (*issue_op)(struct netfs_read_subrequest *subreq); + bool (*is_still_valid)(struct netfs_read_request *rreq); + int (*check_write_begin)(struct file *file, loff_t pos, unsigned len, + struct page *page, void **_fsdata); + void (*done)(struct netfs_read_request *rreq); + void (*cleanup)(struct address_space *mapping, void *netfs_priv); + }; + +The operations are as follows: + + * ``init_rreq()`` + + [Optional] This is called to initialise the request structure. It is given + the file for reference and can modify the ->netfs_priv value. + + * ``is_cache_enabled()`` + + [Required] This is called by netfs_write_begin() to ask if the file is being + cached. It should return true if it is being cached and false otherwise. + + * ``begin_cache_operation()`` + + [Optional] This is called to ask the network filesystem to call into the + cache (if present) to initialise the caching state for this read. The netfs + library module cannot access the cache directly, so the cache should call + something like fscache_begin_read_operation() to do this. + + The cache gets to store its state in ->cache_resources and must set a table + of operations of its own there (though of a different type). + + This should return 0 on success and an error code otherwise. If an error is + reported, the operation may proceed anyway, just without local caching (only + out of memory and interruption errors cause failure here). + + * ``expand_readahead()`` + + [Optional] This is called to allow the filesystem to expand the size of a + readahead read request. The filesystem gets to expand the request in both + directions, though it's not permitted to reduce it as the numbers may + represent an allocation already made. If local caching is enabled, it gets + to expand the request first. + + Expansion is communicated by changing ->start and ->len in the request + structure. Note that if any change is made, ->len must be increased by at + least as much as ->start is reduced. + + * ``clamp_length()`` + + [Optional] This is called to allow the filesystem to reduce the size of a + subrequest. The filesystem can use this, for example, to chop up a request + that has to be split across multiple servers or to put multiple reads in + flight. + + This should return 0 on success and an error code on error. + + * ``issue_op()`` + + [Required] The helpers use this to dispatch a subrequest to the server for + reading. In the subrequest, ->start, ->len and ->transferred indicate what + data should be read from the server. + + There is no return value; the netfs_subreq_terminated() function should be + called to indicate whether or not the operation succeeded and how much data + it transferred. The filesystem also should not deal with setting pages + uptodate, unlocking them or dropping their refs - the helpers need to deal + with this as they have to coordinate with copying to the local cache. + + Note that the helpers have the pages locked, but not pinned. It is possible + to use the ITER_XARRAY iov iterator to refer to the range of the inode that + is being operated upon without the need to allocate large bvec tables. + + * ``is_still_valid()`` + + [Optional] This is called to find out if the data just read from the local + cache is still valid. It should return true if it is still valid and false + if not. If it's not still valid, it will be reread from the server. + + * ``check_write_begin()`` + + [Optional] This is called from the netfs_write_begin() helper once it has + allocated/grabbed the page to be modified to allow the filesystem to flush + conflicting state before allowing it to be modified. + + It should return 0 if everything is now fine, -EAGAIN if the page should be + regrabbed and any other error code to abort the operation. + + * ``done`` + + [Optional] This is called after the pages in the request have all been + unlocked (and marked uptodate if applicable). + + * ``cleanup`` + + [Optional] This is called as the request is being deallocated so that the + filesystem can clean up ->netfs_priv. + + + +Read Helper Procedure +--------------------- + +The read helpers work by the following general procedure: + + * Set up the request. + + * For readahead, allow the local cache and then the network filesystem to + propose expansions to the read request. This is then proposed to the VM. + If the VM cannot fully perform the expansion, a partially expanded read will + be performed, though this may not get written to the cache in its entirety. + + * Loop around slicing chunks off of the request to form subrequests: + + * If a local cache is present, it gets to do the slicing, otherwise the + helpers just try to generate maximal slices. + + * The network filesystem gets to clamp the size of each slice if it is to be + the source. This allows rsize and chunking to be implemented. + + * The helpers issue a read from the cache or a read from the server or just + clears the slice as appropriate. + + * The next slice begins at the end of the last one. + + * As slices finish being read, they terminate. + + * When all the subrequests have terminated, the subrequests are assessed and + any that are short or have failed are reissued: + + * Failed cache requests are issued against the server instead. + + * Failed server requests just fail. + + * Short reads against either source will be reissued against that source + provided they have transferred some more data: + + * The cache may need to skip holes that it can't do DIO from. + + * If NETFS_SREQ_CLEAR_TAIL was set, a short read will be cleared to the + end of the slice instead of reissuing. + + * Once the data is read, the pages that have been fully read/cleared: + + * Will be marked uptodate. + + * If a cache is present, will be marked with PG_fscache. + + * Unlocked + + * Any pages that need writing to the cache will then have DIO writes issued. + + * Synchronous operations will wait for reading to be complete. + + * Writes to the cache will proceed asynchronously and the pages will have the + PG_fscache mark removed when that completes. + + * The request structures will be cleaned up when everything has completed. + + +Read Helper Cache API +--------------------- + +When implementing a local cache to be used by the read helpers, two things are +required: some way for the network filesystem to initialise the caching for a +read request and a table of operations for the helpers to call. + +The network filesystem's ->begin_cache_operation() method is called to set up a +cache and this must call into the cache to do the work. If using fscache, for +example, the cache would call:: + + int fscache_begin_read_operation(struct netfs_read_request *rreq, + struct fscache_cookie *cookie); + +passing in the request pointer and the cookie corresponding to the file. + +The netfs_read_request object contains a place for the cache to hang its +state:: + + struct netfs_cache_resources { + const struct netfs_cache_ops *ops; + void *cache_priv; + void *cache_priv2; + }; + +This contains an operations table pointer and two private pointers. The +operation table looks like the following:: + + struct netfs_cache_ops { + void (*end_operation)(struct netfs_cache_resources *cres); + + void (*expand_readahead)(struct netfs_cache_resources *cres, + loff_t *_start, size_t *_len, loff_t i_size); + + enum netfs_read_source (*prepare_read)(struct netfs_read_subrequest *subreq, + loff_t i_size); + + int (*read)(struct netfs_cache_resources *cres, + loff_t start_pos, + struct iov_iter *iter, + bool seek_data, + netfs_io_terminated_t term_func, + void *term_func_priv); + + int (*write)(struct netfs_cache_resources *cres, + loff_t start_pos, + struct iov_iter *iter, + netfs_io_terminated_t term_func, + void *term_func_priv); + }; + +With a termination handler function pointer:: + + typedef void (*netfs_io_terminated_t)(void *priv, + ssize_t transferred_or_error, + bool was_async); + +The methods defined in the table are: + + * ``end_operation()`` + + [Required] Called to clean up the resources at the end of the read request. + + * ``expand_readahead()`` + + [Optional] Called at the beginning of a netfs_readahead() operation to allow + the cache to expand a request in either direction. This allows the cache to + size the request appropriately for the cache granularity. + + The function is passed poiners to the start and length in its parameters, + plus the size of the file for reference, and adjusts the start and length + appropriately. It should return one of: + + * ``NETFS_FILL_WITH_ZEROES`` + * ``NETFS_DOWNLOAD_FROM_SERVER`` + * ``NETFS_READ_FROM_CACHE`` + * ``NETFS_INVALID_READ`` + + to indicate whether the slice should just be cleared or whether it should be + downloaded from the server or read from the cache - or whether slicing + should be given up at the current point. + + * ``prepare_read()`` + + [Required] Called to configure the next slice of a request. ->start and + ->len in the subrequest indicate where and how big the next slice can be; + the cache gets to reduce the length to match its granularity requirements. + + * ``read()`` + + [Required] Called to read from the cache. The start file offset is given + along with an iterator to read to, which gives the length also. It can be + given a hint requesting that it seek forward from that start position for + data. + + Also provided is a pointer to a termination handler function and private + data to pass to that function. The termination function should be called + with the number of bytes transferred or an error code, plus a flag + indicating whether the termination is definitely happening in the caller's + context. + + * ``write()`` + + [Required] Called to write to the cache. The start file offset is given + along with an iterator to write from, which gives the length also. + + Also provided is a pointer to a termination handler function and private + data to pass to that function. The termination function should be called + with the number of bytes transferred or an error code, plus a flag + indicating whether the termination is definitely happening in the caller's + context. + +Note that these methods are passed a pointer to the cache resource structure, +not the read request structure as they could be used in other situations where +there isn't a read request structure as well, such as writing dirty data to the +cache. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 48fbfc336ebf..81bfe3c800cc 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -540,7 +540,9 @@ encoded manner. The codes are the following: ac area is accountable nr swap space is not reserved for the area ht area uses huge tlb pages + sf synchronous page fault ar architecture specific flag + wf wipe on fork dd do not include area into core dump sd soft dirty flag mm mixed map area @@ -549,6 +551,8 @@ encoded manner. The codes are the following: mg mergable advise flag bt arm64 BTI guarded page mt arm64 MTE allocation tags are enabled + um userfaultfd missing tracking + uw userfaultfd wr-protect tracking == ======================================= Note that there is no guarantee that every flag and associated mnemonic will diff --git a/Documentation/filesystems/vfat.rst b/Documentation/filesystems/vfat.rst index e85d74e91295..760a4d83fdf9 100644 --- a/Documentation/filesystems/vfat.rst +++ b/Documentation/filesystems/vfat.rst @@ -189,7 +189,7 @@ VFAT MOUNT OPTIONS **discard** If set, issues discard/TRIM commands to the block device when blocks are freed. This is useful for SSD devices - and sparse/thinly-provisoned LUNs. + and sparse/thinly-provisioned LUNs. **nfs=stale_rw|nostale_ro** Enable this only if you want to export the FAT filesystem diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 2049bbf5e388..14c31eced416 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -441,6 +441,9 @@ As of kernel 2.6.22, the following members are defined: unsigned open_flag, umode_t create_mode); int (*tmpfile) (struct user_namespace *, struct inode *, struct dentry *, umode_t); int (*set_acl)(struct user_namespace *, struct inode *, struct posix_acl *, int); + int (*fileattr_set)(struct user_namespace *mnt_userns, + struct dentry *dentry, struct fileattr *fa); + int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); }; Again, all methods are called without any locks being held, unless @@ -588,6 +591,18 @@ otherwise noted. atomically creating, opening and unlinking a file in given directory. +``fileattr_get`` + called on ioctl(FS_IOC_GETFLAGS) and ioctl(FS_IOC_FSGETXATTR) to + retrieve miscellaneous file flags and attributes. Also called + before the relevant SET operation to check what is being changed + (in this case with i_rwsem locked exclusive). If unset, then + fall back to f_op->ioctl(). + +``fileattr_set`` + called on ioctl(FS_IOC_SETFLAGS) and ioctl(FS_IOC_FSSETXATTR) to + change miscellaneous file flags and attributes. Callers hold + i_rwsem exclusive. If unset, then fall back to f_op->ioctl(). + The Address Space Object ======================== diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst index 03cd4e25fc45..0639c9de07f9 100644 --- a/Documentation/firmware-guide/acpi/debug.rst +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -1,18 +1,17 @@ .. SPDX-License-Identifier: GPL-2.0 -================= -ACPI Debug Output -================= +==================== +ACPI CA Debug Output +==================== -The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug -output. This document describes how to use this facility. +The ACPI CA can generate debug output. This document describes how to use this +facility. Compile-time configuration ========================== -ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config -option is turned off, the debug messages are not even built into the -kernel. +The ACPI CA debug output is globally enabled by CONFIG_ACPI_DEBUG. If this +config option is not set, the debug messages are not even built into the kernel. Boot- and run-time configuration ================================ @@ -27,16 +26,16 @@ debug_layer (component) ======================= The "debug_layer" is a mask that selects components of interest, e.g., a -specific driver or part of the ACPI interpreter. To build the debug_layer -bitmask, look for the "#define _COMPONENT" in an ACPI source file. +specific part of the ACPI interpreter. To build the debug_layer bitmask, look +for the "#define _COMPONENT" in an ACPI source file. You can set the debug_layer mask at boot-time using the acpi.debug_layer command line argument, and you can change it after boot by writing values to /sys/module/acpi/parameters/debug_layer. -The possible components are defined in include/acpi/acoutput.h and -include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer -shows the supported mask values, currently these:: +The possible components are defined in include/acpi/acoutput.h. + +Reading /sys/module/acpi/parameters/debug_layer shows the supported mask values:: ACPI_UTILITIES 0x00000001 ACPI_HARDWARE 0x00000002 @@ -52,13 +51,6 @@ shows the supported mask values, currently these:: ACPI_CA_DISASSEMBLER 0x00000800 ACPI_COMPILER 0x00001000 ACPI_TOOLS 0x00002000 - ACPI_SBS_COMPONENT 0x00100000 - ACPI_FAN_COMPONENT 0x00200000 - ACPI_PCI_COMPONENT 0x00400000 - ACPI_CONTAINER_COMPONENT 0x01000000 - ACPI_SYSTEM_COMPONENT 0x02000000 - ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 - ACPI_PROCESSOR_COMPONENT 0x20000000 debug_level =========== @@ -127,10 +119,6 @@ AML) during boot:: acpi.debug_layer=0xffffffff acpi.debug_level=0x2 -Enable PCI and PCI interrupt routing debug messages:: - - acpi.debug_layer=0x400000 acpi.debug_level=0x4 - Enable all ACPI hardware-related messages:: acpi.debug_layer=0x2 acpi.debug_level=0xffffffff diff --git a/Documentation/fpga/dfl.rst b/Documentation/fpga/dfl.rst index c41ac76ffaae..f3a1223f2517 100644 --- a/Documentation/fpga/dfl.rst +++ b/Documentation/fpga/dfl.rst @@ -7,6 +7,7 @@ Authors: - Enno Luebbers <enno.luebbers@intel.com> - Xiao Guangrong <guangrong.xiao@linux.intel.com> - Wu Hao <hao.wu@intel.com> +- Xu Yilun <yilun.xu@intel.com> The Device Feature List (DFL) FPGA framework (and drivers according to this framework) hides the very details of low layer hardwares and provides @@ -530,6 +531,31 @@ Being able to specify more than one DFL per BAR has been considered, but it was determined the use case did not provide value. Specifying a single DFL per BAR simplifies the implementation and allows for extra error checking. + +Userspace driver support for DFL devices +======================================== +The purpose of an FPGA is to be reprogrammed with newly developed hardware +components. New hardware can instantiate a new private feature in the DFL, and +then present a DFL device in the system. In some cases users may need a +userspace driver for the DFL device: + +* Users may need to run some diagnostic test for their hardware. +* Users may prototype the kernel driver in user space. +* Some hardware is designed for specific purposes and does not fit into one of + the standard kernel subsystems. + +This requires direct access to MMIO space and interrupt handling from +userspace. The uio_dfl module exposes the UIO device interfaces for this +purpose. + +Currently the uio_dfl driver only supports the Ether Group sub feature, which +has no irq in hardware. So the interrupt handling is not added in this driver. + +UIO_DFL should be selected to enable the uio_dfl module driver. To support a +new DFL feature via UIO direct access, its feature id should be added to the +driver's id_table. + + Open discussion =============== FME driver exports one ioctl (DFL_FPGA_FME_PORT_PR) for partial reconfiguration diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index b89ddd06dabb..389892f36185 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -80,6 +80,18 @@ Atomic State Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c :export: +GEM Atomic Helper Reference +--------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c + :doc: overview + +.. kernel-doc:: include/drm/drm_gem_atomic_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_gem_atomic_helper.c + :export: + Simple KMS Helper Reference =========================== diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index c9a51e3bfb5a..ec4bc72438e4 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -16,6 +16,7 @@ Linux GPU Driver Developer's Guide vga-switcheroo vgaarbiter todo + rfc/index .. only:: subproject and html diff --git a/Documentation/gpu/rfc/index.rst b/Documentation/gpu/rfc/index.rst new file mode 100644 index 000000000000..a8621f7dab8b --- /dev/null +++ b/Documentation/gpu/rfc/index.rst @@ -0,0 +1,17 @@ +=============== +GPU RFC Section +=============== + +For complex work, especially new uapi, it is often good to nail the high level +design issues before getting lost in the code details. This section is meant to +host such documentation: + +* Each RFC should be a section in this file, explaining the goal and main design + considerations. Especially for uapi make sure you Cc: all relevant project + mailing lists and involved people outside of dri-devel. + +* For uapi structures add a file to this directory with and then pull the + kerneldoc in like with real uapi headers. + +* Once the code has landed move all the documentation to the right places in + the main core, helper or driver sections. diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 40ccac61137e..7ff9fac10d8b 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -459,52 +459,6 @@ Contact: Emil Velikov, respective driver maintainers Level: Intermediate -Plumb drm_atomic_state all over -------------------------------- - -Currently various atomic functions take just a single or a handful of -object states (eg. plane state). While that single object state can -suffice for some simple cases, we often have to dig out additional -object states for dealing with various dependencies between the individual -objects or the hardware they represent. The process of digging out the -additional states is rather non-intuitive and error prone. - -To fix that most functions should rather take the overall -drm_atomic_state as one of their parameters. The other parameters -would generally be the object(s) we mainly want to interact with. - -For example, instead of - -.. code-block:: c - - int (*atomic_check)(struct drm_plane *plane, struct drm_plane_state *state); - -we would have something like - -.. code-block:: c - - int (*atomic_check)(struct drm_plane *plane, struct drm_atomic_state *state); - -The implementation can then trivially gain access to any required object -state(s) via drm_atomic_get_plane_state(), drm_atomic_get_new_plane_state(), -drm_atomic_get_old_plane_state(), and their equivalents for -other object types. - -Additionally many drivers currently access the object->state pointer -directly in their commit functions. That is not going to work if we -eg. want to allow deeper commit pipelines as those pointers could -then point to the states corresponding to a future commit instead of -the current commit we're trying to process. Also non-blocking commits -execute locklessly so there are serious concerns with dereferencing -the object->state pointers without holding the locks that protect them. -Use of drm_atomic_get_new_plane_state(), drm_atomic_get_old_plane_state(), -etc. avoids these problems as well since they relate to a specific -commit via the passed in drm_atomic_state. - -Contact: Ville Syrjälä, Daniel Vetter - -Level: Intermediate - Use struct dma_buf_map throughout codebase ------------------------------------------ @@ -596,23 +550,48 @@ Contact: Daniel Vetter Level: Intermediate -KMS cleanups ------------- +Object lifetime fixes +--------------------- + +There's two related issues here -Some of these date from the very introduction of KMS in 2008 ... +- Cleanup up the various ->destroy callbacks, which often are all the same + simple code. -- Make ->funcs and ->helper_private vtables optional. There's a bunch of empty - function tables in drivers, but before we can remove them we need to make sure - that all the users in helpers and drivers do correctly check for a NULL - vtable. +- Lots of drivers erroneously allocate DRM modeset objects using devm_kzalloc, + which results in use-after free issues on driver unload. This can be serious + trouble even for drivers for hardware integrated on the SoC due to + EPROBE_DEFERRED backoff. -- Cleanup up the various ->destroy callbacks. A lot of them just wrapt the - drm_*_cleanup implementations and can be removed. Some tack a kfree() at the - end, for which we could add drm_*_cleanup_kfree(). And then there's the (for - historical reasons) misnamed drm_primary_helper_destroy() function. +Both these problems can be solved by switching over to drmm_kzalloc(), and the +various convenience wrappers provided, e.g. drmm_crtc_alloc_with_planes(), +drmm_universal_plane_alloc(), ... and so on. + +Contact: Daniel Vetter Level: Intermediate +Remove automatic page mapping from dma-buf importing +---------------------------------------------------- + +When importing dma-bufs, the dma-buf and PRIME frameworks automatically map +imported pages into the importer's DMA area. drm_gem_prime_fd_to_handle() and +drm_gem_prime_handle_to_fd() require that importers call dma_buf_attach() +even if they never do actual device DMA, but only CPU access through +dma_buf_vmap(). This is a problem for USB devices, which do not support DMA +operations. + +To fix the issue, automatic page mappings should be removed from the +buffer-sharing code. Fixing this is a bit more involved, since the import/export +cache is also tied to &drm_gem_object.import_attach. Meanwhile we paper over +this problem for USB devices by fishing out the USB host controller device, as +long as that supports DMA. Otherwise importing can still needlessly fail. + +Contact: Thomas Zimmermann <tzimmermann@suse.de>, Daniel Vetter + +Level: Advanced + + Better Testing ============== @@ -645,8 +624,6 @@ See the documentation of :ref:`VKMS <vkms>` for more details. This is an ideal internship task, since it only requires a virtual machine and can be sized to fit the available time. -Contact: Daniel Vetter - Level: See details Backlight Refactoring @@ -700,7 +677,7 @@ Outside DRM Convert fbdev drivers to DRM ---------------------------- -There are plenty of fbdev drivers for older hardware. Some hwardware has +There are plenty of fbdev drivers for older hardware. Some hardware has become obsolete, but some still provides good(-enough) framebuffers. The drivers that are still useful should be converted to DRM and afterwards removed from fbdev. diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst index f6ce44ff611d..7a851252267a 100644 --- a/Documentation/hid/intel-ish-hid.rst +++ b/Documentation/hid/intel-ish-hid.rst @@ -345,7 +345,7 @@ Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space. To debug ISH, event tracing mechanism is used. To enable debug logs:: echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable - cat sys/kernel/debug/tracing/trace + cat /sys/kernel/debug/tracing/trace 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 ----------------------------------------------------- diff --git a/Documentation/hwmon/amd_energy.rst b/Documentation/hwmon/amd_energy.rst deleted file mode 100644 index 9d58cd5ee3da..000000000000 --- a/Documentation/hwmon/amd_energy.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Kernel driver amd_energy -========================== - -Supported chips: - -* AMD Family 17h Processors: Model 30h - -* AMD Family 19h Processors: Model 01h - - Prefix: 'amd_energy' - - Addresses used: RAPL MSRs - - Datasheets: - - - Processor Programming Reference (PPR) for AMD Family 17h Model 01h, Revision B1 Processors - - https://developer.amd.com/wp-content/resources/55570-B1_PUB.zip - - - Preliminary Processor Programming Reference (PPR) for AMD Family 17h Model 31h, Revision B0 Processors - - https://developer.amd.com/wp-content/resources/56176_ppr_Family_17h_Model_71h_B0_pub_Rev_3.06.zip - -Author: Naveen Krishna Chatradhi <nchatrad@amd.com> - -Description ------------ - -The Energy driver exposes the energy counters that are -reported via the Running Average Power Limit (RAPL) -Model-specific Registers (MSRs) via the hardware monitor -(HWMON) sysfs interface. - -1. Power, Energy and Time Units - MSR_RAPL_POWER_UNIT/ C001_0299: - shared with all cores in the socket - -2. Energy consumed by each Core - MSR_CORE_ENERGY_STATUS/ C001_029A: - 32-bitRO, Accumulator, core-level power reporting - -3. Energy consumed by Socket - MSR_PACKAGE_ENERGY_STATUS/ C001_029B: - 32-bitRO, Accumulator, socket-level power reporting, - shared with all cores in socket - -These registers are updated every 1ms and cleared on -reset of the system. - -Note: If SMT is enabled, Linux enumerates all threads as cpus. -Since, the energy status registers are accessed at core level, -reading those registers from the sibling threads would result -in duplicate values. Hence, energy counter entries are not -populated for the siblings. - -Energy Caluclation ------------------- - -Energy information (in Joules) is based on the multiplier, -1/2^ESU; where ESU is an unsigned integer read from -MSR_RAPL_POWER_UNIT register. Default value is 10000b, -indicating energy status unit is 15.3 micro-Joules increment. - -Reported values are scaled as per the formula - -scaled value = ((1/2^ESU) * (Raw value) * 1000000UL) in uJoules - -Users calculate power for a given domain by calculating - dEnergy/dTime for that domain. - -Energy accumulation --------------------------- - -Current, Socket energy status register is 32bit, assuming a 240W -2P system, the register would wrap around in - - 2^32*15.3 e-6/240 * 2 = 547.60833024 secs to wrap(~9 mins) - -The Core energy register may wrap around after several days. - -To improve the wrap around time, a kernel thread is implemented -to accumulate the socket energy counters and one core energy counter -per run to a respective 64-bit counter. The kernel thread starts -running during probe, wakes up every 100secs and stops running -when driver is removed. - -Frequency of the accumulator thread is set during the probe -based on the chosen energy unit resolution. For example -A. fine grain (1.625 micro J) -B. course grain (0.125 milli J) - -A socket and core energy read would return the current register -value added to the respective energy accumulator. - -Sysfs attributes ----------------- - -=============== ======== ===================================== -Attribute Label Description -=============== ======== ===================================== - -* For index N between [1] and [nr_cpus] - -=============== ======== ====================================== -energy[N]_input EcoreX Core Energy X = [0] to [nr_cpus - 1] - Measured input core energy -=============== ======== ====================================== - -* For N between [nr_cpus] and [nr_cpus + nr_socks] - -=============== ======== ====================================== -energy[N]_input EsocketX Socket Energy X = [0] to [nr_socks -1] - Measured input socket energy -=============== ======== ====================================== - -Note: To address CVE-2020-12912, the visibility of the energy[N]_input -attributes is restricted to owner and groups only. diff --git a/Documentation/hwmon/bpa-rs600.rst b/Documentation/hwmon/bpa-rs600.rst new file mode 100644 index 000000000000..28313995d4ae --- /dev/null +++ b/Documentation/hwmon/bpa-rs600.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver bpa-rs600 +======================= + +Supported chips: + + * BPA-RS600-120 + + Datasheet: Publicly available at the BluTek website + http://blutekpower.com/wp-content/uploads/2019/01/BPA-RS600-120-07-19-2018.pdf + +Authors: + - Chris Packham <chris.packham@alliedtelesis.co.nz> + +Description +----------- + +The BPA-RS600 is a compact 600W removable power supply module. + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +Sysfs attributes +---------------- + +======================= ============================================ +curr1_label "iin" +curr1_input Measured input current +curr1_max Maximum input current +curr1_max_alarm Input current high alarm + +curr2_label "iout1" +curr2_input Measured output current +curr2_max Maximum output current +curr2_max_alarm Output current high alarm + +fan1_input Measured fan speed +fan1_alarm Fan warning +fan1_fault Fan fault + +in1_label "vin" +in1_input Measured input voltage +in1_max Maximum input voltage +in1_max_alarm Input voltage high alarm +in1_min Minimum input voltage +in1_min_alarm Input voltage low alarm + +in2_label "vout1" +in2_input Measured output voltage +in2_max Maximum output voltage +in2_max_alarm Output voltage high alarm +in2_min Maximum output voltage +in2_min_alarm Output voltage low alarm + +power1_label "pin" +power1_input Measured input power +power1_alarm Input power alarm +power1_max Maximum input power + +power2_label "pout1" +power2_input Measured output power +power2_max Maximum output power +power2_max_alarm Output power high alarm + +temp1_input Measured temperature around input connector +temp1_alarm Temperature alarm + +temp2_input Measured temperature around output connector +temp2_alarm Temperature alarm +======================= ============================================ diff --git a/Documentation/hwmon/corsair-psu.rst b/Documentation/hwmon/corsair-psu.rst index 396b95c9a76a..e8378e7a1d8c 100644 --- a/Documentation/hwmon/corsair-psu.rst +++ b/Documentation/hwmon/corsair-psu.rst @@ -47,19 +47,30 @@ Sysfs entries ======================= ======================================================== curr1_input Total current usage curr2_input Current on the 12v psu rail +curr2_crit Current max critical value on the 12v psu rail curr3_input Current on the 5v psu rail +curr3_crit Current max critical value on the 5v psu rail curr4_input Current on the 3.3v psu rail +curr4_crit Current max critical value on the 3.3v psu rail fan1_input RPM of psu fan in0_input Voltage of the psu ac input in1_input Voltage of the 12v psu rail +in1_crit Voltage max critical value on the 12v psu rail +in1_lcrit Voltage min critical value on the 12v psu rail in2_input Voltage of the 5v psu rail -in3_input Voltage of the 3.3 psu rail +in2_crit Voltage max critical value on the 5v psu rail +in2_lcrit Voltage min critical value on the 5v psu rail +in3_input Voltage of the 3.3v psu rail +in3_crit Voltage max critical value on the 3.3v psu rail +in3_lcrit Voltage min critical value on the 3.3v psu rail power1_input Total power usage power2_input Power usage of the 12v psu rail power3_input Power usage of the 5v psu rail power4_input Power usage of the 3.3v psu rail temp1_input Temperature of the psu vrm component +temp1_crit Temperature max cirtical value of the psu vrm component temp2_input Temperature of the psu case +temp2_crit Temperature max critical value of psu case ======================= ======================================================== Usage Notes diff --git a/Documentation/hwmon/fsp-3y.rst b/Documentation/hwmon/fsp-3y.rst new file mode 100644 index 000000000000..5693d83a2035 --- /dev/null +++ b/Documentation/hwmon/fsp-3y.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver fsp3y +====================== +Supported devices: + * 3Y POWER YH-5151E + * 3Y POWER YM-2151E + +Author: Václav Kubernát <kubernat@cesnet.cz> + +Description +----------- +This driver implements limited support for two 3Y POWER devices. + +Sysfs entries +------------- + * in1_input input voltage + * in2_input 12V output voltage + * in3_input 5V output voltage + * curr1_input input current + * curr2_input 12V output current + * curr3_input 5V output current + * fan1_input fan rpm + * temp1_input temperature 1 + * temp2_input temperature 2 + * temp3_input temperature 3 + * power1_input input power + * power2_input output power diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 8d5a2df1ecb6..9ed60fa84cbe 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -39,12 +39,12 @@ Hardware Monitoring Kernel Drivers adt7475 aht10 amc6821 - amd_energy asb100 asc7621 aspeed-pwm-tacho bcm54140 bel-pfe + bpa-rs600 bt1-pvt coretemp corsair-cpro @@ -62,6 +62,7 @@ Hardware Monitoring Kernel Drivers f71805f f71882fg fam15h_power + fsp-3y ftsteutates g760a g762 @@ -77,6 +78,7 @@ Hardware Monitoring Kernel Drivers intel-m10-bmc-hwmon ir35221 ir38064 + ir36021 isl68137 it87 jc42 @@ -112,6 +114,7 @@ Hardware Monitoring Kernel Drivers ltc4260 ltc4261 max127 + max15301 max16064 max16065 max1619 @@ -142,6 +145,7 @@ Hardware Monitoring Kernel Drivers npcm750-pwm-fan nsa320 ntc_thermistor + nzxt-kraken2 occ pc87360 pc87427 @@ -168,6 +172,7 @@ Hardware Monitoring Kernel Drivers smsc47m192 smsc47m1 sparx5-temp + stpddc60 tc654 tc74 thmc50 diff --git a/Documentation/hwmon/ir36021.rst b/Documentation/hwmon/ir36021.rst new file mode 100644 index 000000000000..ca3436b04e20 --- /dev/null +++ b/Documentation/hwmon/ir36021.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver ir36021 +===================== + +Supported chips: + + * Infineon IR36021 + + Prefix: ir36021 + Addresses scanned: - + + Datasheet: Publicly available at the Infineon website + https://www.infineon.com/dgdl/ir36021.pdf?fileId=5546d462533600a4015355d0aa2d1775 + +Authors: + - Chris Packham <chris.packham@alliedtelesis.co.nz> + +Description +----------- + +The IR36021 is a dualâ€loop digital multiâ€phase buck controller designed for +point of load applications. + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +Sysfs attributes +---------------- + +======================= =========================== +curr1_label "iin" +curr1_input Measured input current +curr1_alarm Input fault alarm + +curr2_label "iout1" +curr2_input Measured output current +curr2_alarm Output over-current alarm + +in1_label "vin" +in1_input Measured input voltage +in1_alarm Input under-voltage alarm + +in2_label "vout1" +in2_input Measured output voltage +in2_alarm Output over-voltage alarm + +power1_label "pin" +power1_input Measured input power +power1_alarm Input under-voltage alarm + +power2_label "pout1" +power2_input Measured output power + +temp1_input Measured temperature +temp1_alarm Temperature alarm + +temp2_input Measured other loop temperature +temp2_alarm Temperature alarm +======================= =========================== diff --git a/Documentation/hwmon/max15301.rst b/Documentation/hwmon/max15301.rst new file mode 100644 index 000000000000..e3dc22fe1c6d --- /dev/null +++ b/Documentation/hwmon/max15301.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver max15301 +====================== + +Supported chips: + + * Maxim MAX15301 + + Prefix: 'max15301', 'bmr461' + + Addresses scanned: - + + Datasheet: https://datasheets.maximintegrated.com/en/ds/MAX15301.pdf + +Author: Erik Rosen <erik.rosen@metormote.com> + + +Description +----------- + +This driver supports hardware monitoring for Maxim MAX15301 controller chip and +compatible modules. + +The driver is a client driver to the core PMBus driver. Please see +Documentation/hwmon/pmbus.rst and Documentation.hwmon/pmbus-core for details +on PMBus client drivers. + + +Usage Notes +----------- + +This driver does not auto-detect devices. You will have to instantiate the +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for +details. + + +Platform data support +--------------------- + +The driver supports standard PMBus driver platform data. + + +Module parameters +----------------- + +delay +----- + +The controller requires a minimum interval between I2C bus accesses. +The default interval is set to 100 us. For manual override, the driver +provides a writeable module parameter, 'delay', which can be used to +set the interval to a value between 0 and 65,535 microseconds. + + +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_lcrit Critical minimum input voltage. +in1_crit Critical maximum input voltage. +in1_lcrit_alarm Input voltage critical low alarm. +in1_crit_alarm Input voltage critical high alarm. + +in2_label "vout1" +in2_input Measured output voltage. +in2_lcrit Critical minimum output Voltage. +in2_crit Critical maximum output voltage. +in2_lcrit_alarm Critical output voltage critical low alarm. +in2_crit_alarm Critical output voltage critical high alarm. + +curr1_label "iout1" +curr1_input Measured output current. +curr1_crit Critical maximum output current. +curr1_crit_alarm Output current critical high alarm. + +temp1_input Measured maximum temperature of all phases. +temp1_max Maximum temperature limit. +temp1_max_alarm High temperature alarm. +temp1_crit Critical maximum temperature limit. +temp1_crit_alarm Critical maximum temperature alarm. +======================= ======================================================== diff --git a/Documentation/hwmon/nzxt-kraken2.rst b/Documentation/hwmon/nzxt-kraken2.rst new file mode 100644 index 000000000000..94025de65a81 --- /dev/null +++ b/Documentation/hwmon/nzxt-kraken2.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver nzxt-kraken2 +========================== + +Supported devices: + +* NZXT Kraken X42 +* NZXT Kraken X52 +* NZXT Kraken X62 +* NZXT Kraken X72 + +Author: Jonas Malaco + +Description +----------- + +This driver enables hardware monitoring support for NZXT Kraken X42/X52/X62/X72 +all-in-one CPU liquid coolers. Three sensors are available: fan speed, pump +speed and coolant temperature. + +Fan and pump control, while supported by the firmware, are not currently +exposed. The addressable RGB LEDs, present in the integrated CPU water block +and pump head, are not supported either. But both features can be found in +existing user-space tools (e.g. `liquidctl`_). + +.. _liquidctl: https://github.com/liquidctl/liquidctl + +Usage Notes +----------- + +As these are USB HIDs, the driver can be loaded automatically by the kernel and +supports hot swapping. + +Sysfs entries +------------- + +======================= ======================================================== +fan1_input Fan speed (in rpm) +fan2_input Pump speed (in rpm) +temp1_input Coolant temperature (in millidegrees Celsius) +======================= ======================================================== diff --git a/Documentation/hwmon/stpddc60.rst b/Documentation/hwmon/stpddc60.rst new file mode 100644 index 000000000000..7f7ce7f7871b --- /dev/null +++ b/Documentation/hwmon/stpddc60.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver stpddc60 +====================== + +Supported chips: + + * ST STPDDC60 + + Prefix: 'stpddc60', 'bmr481' + + Addresses scanned: - + + Datasheet: https://flexpowermodules.com/documents/fpm-techspec-bmr481 + +Author: Erik Rosen <erik.rosen@metormote.com> + + +Description +----------- + +This driver supports hardware monitoring for ST STPDDC60 controller chip and +compatible modules. + +The driver is a client driver to the core PMBus driver. Please see +Documentation/hwmon/pmbus.rst and Documentation.hwmon/pmbus-core for details +on PMBus client drivers. + + +Usage Notes +----------- + +This driver does not auto-detect devices. You will have to instantiate the +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for +details. + +The vout under- and over-voltage limits are set in relation to the commanded +output voltage as a positive or negative offset in the interval 50mV to 400mV +in 50mV steps. This means that the absolute values of the limits will change +when the commanded output voltage changes. Also, care should be taken when +writing to those limits since in the worst case the commanded output voltage +could change at the same time as the limit is written to, wich will lead to +unpredictable results. + + +Platform data support +--------------------- + +The driver supports standard PMBus driver platform data. + + +Sysfs entries +------------- + +The following attributes are supported. Vin, iout, pout and temp limits +are read-write; all other attributes are read-only. + +======================= ======================================================== +in1_label "vin" +in1_input Measured input voltage. +in1_lcrit Critical minimum input voltage. +in1_crit Critical maximum input voltage. +in1_lcrit_alarm Input voltage critical low alarm. +in1_crit_alarm Input voltage critical high alarm. + +in2_label "vout1" +in2_input Measured output voltage. +in2_lcrit Critical minimum output voltage. +in2_crit Critical maximum output voltage. +in2_lcrit_alarm Critical output voltage critical low alarm. +in2_crit_alarm Critical output voltage critical high alarm. + +curr1_label "iout1" +curr1_input Measured output current. +curr1_max Maximum output current. +curr1_max_alarm Output current high alarm. +curr1_crit Critical maximum output current. +curr1_crit_alarm Output current critical high alarm. + +power1_label "pout1" +power1_input Measured output power. +power1_crit Critical maximum output power. +power1_crit_alarm Output power critical high alarm. + +temp1_input Measured maximum temperature of all phases. +temp1_max Maximum temperature limit. +temp1_max_alarm High temperature alarm. +temp1_crit Critical maximum temperature limit. +temp1_crit_alarm Critical maximum temperature alarm. +======================= ======================================================== diff --git a/Documentation/hwmon/sysfs-interface.rst b/Documentation/hwmon/sysfs-interface.rst index 678c9c60b5a3..13c5acb72d63 100644 --- a/Documentation/hwmon/sysfs-interface.rst +++ b/Documentation/hwmon/sysfs-interface.rst @@ -65,6 +65,14 @@ the desired value must be written, note that strings which are not a number are interpreted as 0! For more on how written strings are interpreted see the "sysfs attribute writes interpretation" section at the end of this file. +Attribute access +---------------- + +Hardware monitoring sysfs attributes are displayed by unrestricted userspace +applications. For this reason, all standard ABI attributes shall be world +readable. Writeable standard ABI attributes shall be writeable only for +privileged users. + ------------------------------------------------------------------------- ======= =========================================== diff --git a/Documentation/hwmon/tps53679.rst b/Documentation/hwmon/tps53679.rst index c7c589e49789..3b9561648c24 100644 --- a/Documentation/hwmon/tps53679.rst +++ b/Documentation/hwmon/tps53679.rst @@ -19,6 +19,14 @@ Supported chips: Datasheet: https://www.ti.com/lit/gpn/TPS53667 + * Texas Instruments TPS53676 + + Prefix: 'tps53676' + + Addresses scanned: - + + Datasheet: https://www.ti.com/lit/gpn/TPS53676 + * Texas Instruments TPS53679 Prefix: 'tps53679' @@ -136,7 +144,7 @@ power1_input Measured input power. power[N]_label "pout[1-2]". - TPS53647, TPS53667: N=2 - - TPS53679, TPS53681, TPS53588: N=2,3 + - TPS53676, TPS53679, TPS53681, TPS53588: N=2,3 power[N]_input Measured output power. @@ -156,10 +164,11 @@ curr[N]_label "iout[1-2]" or "iout1.[0-5]". The first digit is the output channel, the second digit is the phase within the channel. Per-phase - telemetry supported on TPS53681 only. + telemetry supported on TPS53676 and TPS53681 only. - TPS53647, TPS53667: N=2 - TPS53679, TPS53588: N=2,3 + - TPS53676: N=2-8 - TPS53681: N=2-9 curr[N]_input Measured output current. diff --git a/Documentation/iio/iio_configfs.rst b/Documentation/iio/iio_configfs.rst index 3a5d76f9e2b9..b276397af797 100644 --- a/Documentation/iio/iio_configfs.rst +++ b/Documentation/iio/iio_configfs.rst @@ -71,7 +71,7 @@ kernel module following the interface in include/linux/iio/sw_trigger.h:: .ops = &iio_trig_sample_ops, }; -module_iio_sw_trigger_driver(iio_trig_sample); + module_iio_sw_trigger_driver(iio_trig_sample); Each trigger type has its own directory under /config/iio/triggers. Loading iio-trig-sample module will create 'trig-sample' trigger type directory @@ -99,3 +99,4 @@ Each trigger can have one or more attributes specific to the trigger type. "hrtimer" trigger type doesn't have any configurable attribute from /config dir. It does introduce the sampling_frequency attribute to trigger directory. +That attribute sets the polling frequency in Hz, with mHz precision. diff --git a/Documentation/index.rst b/Documentation/index.rst index 31f2adc8542d..54ce34fd6fbd 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -149,27 +149,11 @@ Architecture-agnostic documentation Architecture-specific documentation ----------------------------------- -These books provide programming details about architecture-specific -implementation. - .. toctree:: :maxdepth: 2 - arm/index - arm64/index - ia64/index - m68k/index - mips/index - nios2/index - openrisc/index - parisc/index - powerpc/index - riscv/index - s390/index - sh/index - sparc/index - x86/index - xtensa/index + arch + Other documentation ------------------- diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst index 3118fc1c1e26..b24ae7d292cc 100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@ -246,9 +246,9 @@ A few EV_ABS codes have special meanings: A device should set the resolution of the axis to indicate whether the pressure is in measurable units. If the resolution is zero, the - pressure data is in arbitrary units. If the resolution is nonzero, the + pressure data is in arbitrary units. If the resolution is non-zero, the pressure data is in units/gram. For example, a value of 10 with a - resolution of 1 represents 10 gram, a value of 10 with a resolution on + resolution of 1 represents 10 gram, a value of 10 with a resolution of 1000 represents 10 microgram. EV_SW @@ -344,7 +344,7 @@ INPUT_PROP_BUTTONPAD For touchpads where the button is placed beneath the surface, such that pressing down on the pad causes a button click, this property should be -set. Common in clickpad notebooks and macbooks from 2009 and onwards. +set. Common in Clickpad notebooks and Macbooks from 2009 and onwards. Originally, the buttonpad property was coded into the bcm5974 driver version field under the name integrated button. For backwards @@ -356,7 +356,7 @@ INPUT_PROP_SEMI_MT Some touchpads, most common between 2008 and 2011, can detect the presence of multiple contacts without resolving the individual positions; only the number of contacts and a rectangular shape is known. For such -touchpads, the semi-mt property should be set. +touchpads, the SEMI_MT property should be set. Depending on the device, the rectangle may enclose all touches, like a bounding box, or just some of them, for instance the two most recent @@ -394,7 +394,7 @@ Guidelines ========== The guidelines below ensure proper single-touch and multi-finger functionality. -For multi-touch functionality, see the multi-touch-protocol.txt document for +For multi-touch functionality, see the multi-touch-protocol.rst document for more information. Mice diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst index 0c02e87ee86d..5a1da42c33b3 100644 --- a/Documentation/input/ff.rst +++ b/Documentation/input/ff.rst @@ -16,8 +16,8 @@ goal is not to support these devices as if they were simple input-only devices (as it is already the case), but to really enable the rendering of force effects. This document only describes the force feedback part of the Linux input -interface. Please read joystick.txt and input.txt before reading further this -document. +interface. Please read joydev/joystick.rst and input.rst before reading further +this document. Instructions to the user ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -36,7 +36,7 @@ should keep a hand on your device, in order to avoid it to break down if something goes wrong. If you have a serial iforce device, you need to start inputattach. See -joystick.txt for details. +joydev/joystick.rst for details. Does it work ? -------------- diff --git a/Documentation/input/gameport-programming.rst b/Documentation/input/gameport-programming.rst index c96911df1c54..7d7063ad0f9f 100644 --- a/Documentation/input/gameport-programming.rst +++ b/Documentation/input/gameport-programming.rst @@ -21,7 +21,7 @@ choose which one to program the hardware to, starting from the more exotic addresses is preferred, because the likelihood of clashing with the standard 0x201 address is smaller. -Eg. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then +E.g. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then 0x218 would be the address of first choice. If your hardware supports a gameport address that is not mapped to ISA io @@ -78,7 +78,7 @@ the gameport. To register a cooked gameport:: for (i = 0; i < 4; i++) axes[i] = my_mmio[i]; - buttons[i] = my_mmio[4]; + buttons[0] = my_mmio[4]; } int my_open(struct gameport *gameport, int mode) @@ -117,25 +117,28 @@ Simple:: The gameport structure ~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - This section is outdated. There are several fields here that don't - match what's there at include/linux/gameport.h. - :: struct gameport { - void *private; + void *port_data; A private pointer for free use in the gameport driver. (Not the joystick driver!) :: - int number; + char name[32]; + +Driver's name as set by driver calling gameport_set_name(). Informational +purpose only. + +:: + + char phys[32]; -Number assigned to the gameport when registered. Informational purpose only. +gameport's physical name/description as set by driver calling gameport_set_phys(). +Informational purpose only. :: @@ -210,8 +213,16 @@ gameport. :: - struct gameport_dev *dev; - struct gameport *next; + struct timer_list poll_timer; + unsigned int poll_interval; /* in msecs */ + spinlock_t timer_lock; + unsigned int poll_cnt; + void (*poll_handler)(struct gameport *); + struct gameport *parent, *child; + struct gameport_driver *drv; + struct mutex drv_mutex; /* protects serio->drv so attributes can pin driver */ + struct device dev; + struct list_head node; For internal use by the gameport layer. diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst index 5938145b0e35..2638dce69764 100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@ -120,7 +120,7 @@ Then there is the:: call to tell those who receive the events that we've sent a complete report. This doesn't seem important in the one button case, but is quite important -for for example mouse movement, where you don't want the X and Y values +for example for mouse movement, where you don't want the X and Y values to be interpreted separately, because that'd result in a different movement. dev->open() and dev->close() @@ -128,7 +128,7 @@ dev->open() and dev->close() In case the driver has to repeatedly poll the device, because it doesn't have an interrupt coming from it and the polling is too expensive to be done -all the time, or if the device uses a valuable resource (eg. interrupt), it +all the time, or if the device uses a valuable resource (e.g. interrupt), it can use the open and close callback to know when it can stop polling or release the interrupt and when it must resume polling or grab the interrupt again. To do that, we would add this to our example driver:: @@ -161,7 +161,7 @@ makes sure that dev->open() is called only when the first user connects to the device and that dev->close() is called when the very last user disconnects. Calls to both callbacks are serialized. -The open() callback should return a 0 in case of success or any nonzero value +The open() callback should return a 0 in case of success or any non-zero value in case of failure. The close() callback (which is void) must always succeed. Inhibiting input devices @@ -182,8 +182,8 @@ providing events to the input core. Calling the device's close() method on inhibit (if there are users) allows the driver to save power. Either by directly powering down the device or by -releasing the runtime-pm reference it got in open() when the driver is using -runtime-pm. +releasing the runtime-PM reference it got in open() when the driver is using +runtime-PM. Inhibiting and uninhibiting are orthogonal to opening and closing the device by input handlers. Userspace might want to inhibit a device in anticipation before @@ -219,8 +219,8 @@ It's reported to the input system via:: input_report_key(struct input_dev *dev, int code, int value) See uapi/linux/input-event-codes.h for the allowable values of code (from 0 to -KEY_MAX). Value is interpreted as a truth value, ie any nonzero value means key -pressed, zero value means key released. The input code generates events only +KEY_MAX). Value is interpreted as a truth value, i.e. any non-zero value means +key pressed, zero value means key released. The input code generates events only in case the value is different from before. In addition to EV_KEY, there are two more basic event types: EV_REL and @@ -231,12 +231,12 @@ because it doesn't have any absolute coordinate system to work in. Absolute events are namely for joysticks and digitizers - devices that do work in an absolute coordinate systems. -Having the device report EV_REL buttons is as simple as with EV_KEY, simply +Having the device report EV_REL buttons is as simple as with EV_KEY; simply set the corresponding bits and call the:: input_report_rel(struct input_dev *dev, int code, int value) -function. Events are generated only for nonzero value. +function. Events are generated only for non-zero values. However EV_ABS requires a little special care. Before calling input_register_device, you have to fill additional fields in the input_dev @@ -280,7 +280,7 @@ device driver. It's a string like 'Generic button device' containing a user friendly name of the device. The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID -of the device. The bus IDs are defined in input.h. The vendor and device ids +of the device. The bus IDs are defined in input.h. The vendor and device IDs are defined in pci_ids.h, usb_ids.h and similar include files. These fields should be set by the input device driver before registering it. diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst index 0eb61e67a7b7..2c67fa904adc 100644 --- a/Documentation/input/input.rst +++ b/Documentation/input/input.rst @@ -9,7 +9,7 @@ Introduction Architecture ============ -Input subsystem a collection of drivers that is designed to support +Input subsystem is a collection of drivers that is designed to support all input devices under Linux. Most of the drivers reside in drivers/input, although quite a few live in drivers/hid and drivers/platform. @@ -50,7 +50,7 @@ will be available as a character device on major 13, minor 63:: crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice -This device usually created automatically by the system. The commands +This device is usually created automatically by the system. The commands to create it by hand are:: cd /dev @@ -180,7 +180,7 @@ whole suite. It handles all HID devices, and because there is a very wide variety of them, and because the USB HID specification isn't simple, it needs to be this big. -Currently, it handles USB mice, joysticks, gamepads, steering wheels +Currently, it handles USB mice, joysticks, gamepads, steering wheels, keyboards, trackballs and digitizers. However, USB uses HID also for monitor controls, speaker controls, UPSs, @@ -268,7 +268,7 @@ events on a read. Their layout is:: }; ``time`` is the timestamp, it returns the time at which the event happened. -Type is for example EV_REL for relative moment, EV_KEY for a keypress or +Type is for example EV_REL for relative movement, EV_KEY for a keypress or release. More types are defined in include/uapi/linux/input-event-codes.h. ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 21c1e6a22888..1085cbee4ee7 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -261,7 +261,7 @@ ABS_MT_PRESSURE signal intensity distribution. If the resolution is zero, the pressure data is in arbitrary units. - If the resolution is nonzero, the pressure data is in units/gram. See + If the resolution is non-zero, the pressure data is in units/gram. See :ref:`input-event-codes` for details. ABS_MT_DISTANCE @@ -279,14 +279,14 @@ ABS_MT_ORIENTATION max should be returned; when aligned with the X axis in the negative direction, the range -max should be returned. - Touch ellipsis are symmetrical by default. For devices capable of true 360 + Touch ellipses are symmetrical by default. For devices capable of true 360 degree orientation, the reported orientation must exceed the range max to indicate more than a quarter of a revolution. For an upside-down finger, range max * 2 should be returned. Orientation can be omitted if the touch area is circular, or if the information is not available in the kernel driver. Partial orientation - support is possible if the device can distinguish between the two axis, but + support is possible if the device can distinguish between the two axes, but not (uniquely) any values in between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] [#f4]_. @@ -356,7 +356,7 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that the device can distinguish between a finger along the Y axis (0) and a finger along the X axis (1). -For win8 devices with both T and C coordinates, the position mapping is:: +For Win8 devices with both T and C coordinates, the position mapping is:: ABS_MT_POSITION_X := T_X ABS_MT_POSITION_Y := T_Y diff --git a/Documentation/input/notifier.rst b/Documentation/input/notifier.rst index 161350cb865e..824379399e61 100644 --- a/Documentation/input/notifier.rst +++ b/Documentation/input/notifier.rst @@ -4,11 +4,12 @@ Keyboard notifier One can use register_keyboard_notifier to get called back on keyboard events (see kbd_keycode() function for details). The passed structure is -keyboard_notifier_param: +keyboard_notifier_param (see <linux/keyboard.h>): - 'vc' always provide the VC for which the keyboard event applies; - 'down' is 1 for a key press event, 0 for a key release; - 'shift' is the current modifier state, mask bit indexes are KG_*; +- 'ledstate' is the current LED state; - 'value' depends on the type of event. - KBD_KEYCODE events are always sent before other events, value is the keycode. diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst index 10c62e62a0a6..30fe80e325a5 100644 --- a/Documentation/input/uinput.rst +++ b/Documentation/input/uinput.rst @@ -179,7 +179,7 @@ uinput old interface -------------------- Before uinput version 5, there wasn't a dedicated ioctl to set up a virtual -device. Programs supportinf older versions of uinput interface need to fill +device. Programs supporting older versions of uinput interface need to fill a uinput_user_dev structure and write it to the uinput file descriptor to configure the new uinput device. New code should not use the old interface but interact with uinput via ioctl calls, or use libevdev. diff --git a/Documentation/leds/leds-lm3556.rst b/Documentation/leds/leds-lm3556.rst index 1ef17d7d800e..32e3983473ba 100644 --- a/Documentation/leds/leds-lm3556.rst +++ b/Documentation/leds/leds-lm3556.rst @@ -23,7 +23,7 @@ from 93.75 mA to 1500 mA.The Flash currents are adjusted via the CURRENT CONTROL REGISTER(0x09).Flash mode is activated by the ENABLE REGISTER(0x0A), or by pulling the STROBE pin HIGH. -LM3556 Flash can be controlled through sys/class/leds/flash/brightness file +LM3556 Flash can be controlled through /sys/class/leds/flash/brightness file * if STROBE pin is enabled, below example control brightness only, and ON / OFF will be controlled by STROBE pin. @@ -32,17 +32,17 @@ Flash Example: OFF:: - #echo 0 > sys/class/leds/flash/brightness + #echo 0 > /sys/class/leds/flash/brightness 93.75 mA:: - #echo 1 > sys/class/leds/flash/brightness + #echo 1 > /sys/class/leds/flash/brightness ... 1500 mA:: - #echo 16 > sys/class/leds/flash/brightness + #echo 16 > /sys/class/leds/flash/brightness Torch Mode ^^^^^^^^^^ @@ -51,7 +51,7 @@ In Torch Mode, the current source(LED) is programmed via the CURRENT CONTROL REGISTER(0x09).Torch Mode is activated by the ENABLE REGISTER(0x0A) or by the hardware TORCH input. -LM3556 torch can be controlled through sys/class/leds/torch/brightness file. +LM3556 torch can be controlled through /sys/class/leds/torch/brightness file. * if TORCH pin is enabled, below example control brightness only, and ON / OFF will be controlled by TORCH pin. @@ -59,22 +59,22 @@ Torch Example: OFF:: - #echo 0 > sys/class/leds/torch/brightness + #echo 0 > /sys/class/leds/torch/brightness 46.88 mA:: - #echo 1 > sys/class/leds/torch/brightness + #echo 1 > /sys/class/leds/torch/brightness ... 375 mA:: - #echo 8 > sys/class/leds/torch/brightness + #echo 8 > /sys/class/leds/torch/brightness Indicator Mode ^^^^^^^^^^^^^^ -Indicator pattern can be set through sys/class/leds/indicator/pattern file, +Indicator pattern can be set through /sys/class/leds/indicator/pattern file, and 4 patterns are pre-defined in indicator_pattern array. According to N-lank, Pulse time and N Period values, different pattern wiill @@ -87,13 +87,13 @@ Indicator pattern example: pattern 0:: - #echo 0 > sys/class/leds/indicator/pattern + #echo 0 > /sys/class/leds/indicator/pattern ... pattern 3:: - #echo 3 > sys/class/leds/indicator/pattern + #echo 3 > /sys/class/leds/indicator/pattern Indicator brightness can be controlled through sys/class/leds/indicator/brightness file. @@ -102,17 +102,17 @@ Example: OFF:: - #echo 0 > sys/class/leds/indicator/brightness + #echo 0 > /sys/class/leds/indicator/brightness 5.86 mA:: - #echo 1 > sys/class/leds/indicator/brightness + #echo 1 > /sys/class/leds/indicator/brightness ... 46.875mA:: - #echo 8 > sys/class/leds/indicator/brightness + #echo 8 > /sys/class/leds/indicator/brightness Notes ----- diff --git a/Documentation/livepatch/shadow-vars.rst b/Documentation/livepatch/shadow-vars.rst index c05715aeafa4..6a7d43a8787d 100644 --- a/Documentation/livepatch/shadow-vars.rst +++ b/Documentation/livepatch/shadow-vars.rst @@ -165,8 +165,8 @@ In-flight parent objects Sometimes it may not be convenient or possible to allocate shadow variables alongside their parent objects. Or a livepatch fix may -require shadow varibles to only a subset of parent object instances. In -these cases, the klp_shadow_get_or_alloc() call can be used to attach +require shadow variables for only a subset of parent object instances. +In 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 diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index b7a627d6c97d..5d5cc3acdf85 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -102,3 +102,4 @@ to do something different in the near future. ../doc-guide/maintainer-profile ../nvdimm/maintainer-entry-profile ../riscv/patch-acceptance + ../driver-api/media/maintainer-entry-profile diff --git a/Documentation/misc-devices/dw-xdata-pcie.rst b/Documentation/misc-devices/dw-xdata-pcie.rst new file mode 100644 index 000000000000..781c6794a506 --- /dev/null +++ b/Documentation/misc-devices/dw-xdata-pcie.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================================================================== +Driver for Synopsys DesignWare PCIe traffic generator (also known as xData) +=========================================================================== + +Supported chips: +Synopsys DesignWare PCIe prototype solution + +Datasheet: +Not freely available + +Author: +Gustavo Pimentel <gustavo.pimentel@synopsys.com> + +Description +----------- + +This driver should be used as a host-side (Root Complex) driver and Synopsys +DesignWare prototype that includes this IP. + +The dw-xdata-pcie driver can be used to enable/disable PCIe traffic +generator in either direction (mutual exclusion) besides allowing the +PCIe link performance analysis. + +The interaction with this driver is done through the module parameter and +can be changed in runtime. The driver outputs the requested command state +information to ``/var/log/kern.log`` or dmesg. + +Example +------- + +Write TLPs traffic generation - Root Complex to Endpoint direction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generate traffic:: + + # echo 1 > /sys/class/misc/dw-xdata-pcie.0/write + +Get link throughput in MB/s:: + + # cat /sys/class/misc/dw-xdata-pcie.0/write + 204 + +Stop traffic in any direction:: + + # echo 0 > /sys/class/misc/dw-xdata-pcie.0/write + +Read TLPs traffic generation - Endpoint to Root Complex direction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generate traffic:: + + # echo 1 > /sys/class/misc/dw-xdata-pcie.0/read + +Get link throughput in MB/s:: + + # cat /sys/class/misc/dw-xdata-pcie.0/read + 199 + +Stop traffic in any direction:: + + # echo 0 > /sys/class/misc/dw-xdata-pcie.0/read + diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index 64420b3314fe..30ac58f81901 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -19,6 +19,7 @@ fit into other categories. bh1770glc eeprom c2port + dw-xdata-pcie ibmvmc ics932s401 isl29003 diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index 5f690f0ad0e4..62f2aab8eaec 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -1988,7 +1988,7 @@ netif_carrier. If use_carrier is 0, then the MII monitor will first query the device's (via ioctl) MII registers and check the link state. If that request fails (not just that it returns carrier down), then the MII -monitor will make an ethtool ETHOOL_GLINK request to attempt to obtain +monitor will make an ethtool ETHTOOL_GLINK request to attempt to obtain the same information. If both methods fail (i.e., the driver either does not support or had some error in processing both the MII register and ethtool requests), then the MII monitor will assume the link is diff --git a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst index 3561a8a29fd2..f8c6469f2bd2 100644 --- a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst +++ b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst @@ -267,7 +267,7 @@ DATA PATH Tx -- -end_start_xmit() is called by the stack. This function does the following: +ena_start_xmit() is called by the stack. This function does the following: - Maps data buffers (skb->data and frags). - Populates ena_buf for the push buffer (if the driver and device are diff --git a/Documentation/networking/devlink/devlink-dpipe.rst b/Documentation/networking/devlink/devlink-dpipe.rst index 468fe1001b74..af37f250df43 100644 --- a/Documentation/networking/devlink/devlink-dpipe.rst +++ b/Documentation/networking/devlink/devlink-dpipe.rst @@ -52,7 +52,7 @@ purposes as a standard complementary tool. The system's view from ``devlink-dpipe`` should change according to the changes done by the standard configuration tools. -For example, it’s quiet common to implement Access Control Lists (ACL) +For example, it’s quite common to implement Access Control Lists (ACL) using Ternary Content Addressable Memory (TCAM). The TCAM memory can be divided into TCAM regions. Complex TC filters can have multiple rules with different priorities and different lookup keys. On the other hand hardware diff --git a/Documentation/networking/devlink/devlink-port.rst b/Documentation/networking/devlink/devlink-port.rst index e99b41599465..ab790e7980b8 100644 --- a/Documentation/networking/devlink/devlink-port.rst +++ b/Documentation/networking/devlink/devlink-port.rst @@ -151,7 +151,7 @@ representor netdevice. ------------- A subfunction devlink port is created but it is not active yet. That means the entities are created on devlink side, the e-switch port representor is created, -but the subfunction device itself it not created. A user might use e-switch port +but the subfunction device itself is not created. A user might use e-switch port representor to do settings, putting it into bridge, adding TC rules, etc. A user might as well configure the hardware address (such as MAC address) of the subfunction while subfunction is inactive. @@ -173,7 +173,7 @@ Terms and Definitions * - Term - Definitions * - ``PCI device`` - - A physical PCI device having one or more PCI bus consists of one or + - A physical PCI device having one or more PCI buses consists of one or more PCI controllers. * - ``PCI controller`` - A controller consists of potentially multiple physical functions, diff --git a/Documentation/networking/ethtool-netlink.rst b/Documentation/networking/ethtool-netlink.rst index 05073482db05..dc03ff884541 100644 --- a/Documentation/networking/ethtool-netlink.rst +++ b/Documentation/networking/ethtool-netlink.rst @@ -976,9 +976,9 @@ constraints on coalescing parameters and their values. PAUSE_GET -============ +========= -Gets channel counts like ``ETHTOOL_GPAUSE`` ioctl request. +Gets pause frame settings like ``ETHTOOL_GPAUSEPARAM`` ioctl request. Request contents: @@ -1007,7 +1007,7 @@ the statistics in the following structure: Each member has a corresponding attribute defined. PAUSE_SET -============ +========= Sets pause parameters like ``ETHTOOL_GPAUSEPARAM`` ioctl request. @@ -1024,7 +1024,7 @@ Request contents: EEE_GET ======= -Gets channel counts like ``ETHTOOL_GEEE`` ioctl request. +Gets Energy Efficient Ethernet settings like ``ETHTOOL_GEEE`` ioctl request. Request contents: @@ -1054,7 +1054,7 @@ first 32 are provided by the ``ethtool_ops`` callback. EEE_SET ======= -Sets pause parameters like ``ETHTOOL_GEEEPARAM`` ioctl request. +Sets Energy Efficient Ethernet parameters like ``ETHTOOL_SEEE`` ioctl request. Request contents: diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index c7952ac5bd2f..3feb5e565b1a 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -1849,21 +1849,6 @@ ip6frag_low_thresh - INTEGER ip6frag_time - INTEGER Time in seconds to keep an IPv6 fragment in memory. -IPv6 Segment Routing: - -seg6_flowlabel - INTEGER - Controls the behaviour of computing the flowlabel of outer - IPv6 header in case of SR T.encaps - - == ======================================================= - -1 set flowlabel to zero. - 0 copy flowlabel from Inner packet in case of Inner IPv6 - (Set flowlabel to 0 in case IPv4/L2) - 1 Compute the flowlabel using seg6_make_flowlabel() - == ======================================================= - - Default is 0. - ``conf/default/*``: Change the interface-specific default settings. diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst index a64c01b52b4c..91b2cf712801 100644 --- a/Documentation/networking/netdev-FAQ.rst +++ b/Documentation/networking/netdev-FAQ.rst @@ -142,73 +142,13 @@ Please send incremental versions on top of what has been merged in order to fix the patches the way they would look like if your latest patch series was to be merged. -How can I tell what patches are queued up for backporting to the various stable releases? ------------------------------------------------------------------------------------------ -Normally Greg Kroah-Hartman collects stable commits himself, but for -networking, Dave collects up patches he deems critical for the -networking subsystem, and then hands them off to Greg. - -There is a patchworks queue that you can see here: - - https://patchwork.kernel.org/bundle/netdev/stable/?state=* - -It contains the patches which Dave has selected, but not yet handed off -to Greg. If Greg already has the patch, then it will be here: - - https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git - -A quick way to find whether the patch is in this stable-queue is to -simply clone the repo, and then git grep the mainline commit ID, e.g. -:: - - stable-queue$ git grep -l 284041ef21fdf2e - releases/3.0.84/ipv6-fix-possible-crashes-in-ip6_cork_release.patch - releases/3.4.51/ipv6-fix-possible-crashes-in-ip6_cork_release.patch - releases/3.9.8/ipv6-fix-possible-crashes-in-ip6_cork_release.patch - stable/stable-queue$ - -I see a network patch and I think it should be backported to stable. Should I request it via stable@vger.kernel.org like the references in the kernel's Documentation/process/stable-kernel-rules.rst file say? ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -No, not for networking. Check the stable queues as per above first -to see if it is already queued. If not, then send a mail to netdev, -listing the upstream commit ID and why you think it should be a stable -candidate. - -Before you jump to go do the above, do note that the normal stable rules -in :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` -still apply. So you need to explicitly indicate why it is a critical -fix and exactly what users are impacted. In addition, you need to -convince yourself that you *really* think it has been overlooked, -vs. having been considered and rejected. - -Generally speaking, the longer it has had a chance to "soak" in -mainline, the better the odds that it is an OK candidate for stable. So -scrambling to request a commit be added the day after it appears should -be avoided. - -I have created a network patch and I think it should be backported to stable. Should I add a Cc: stable@vger.kernel.org like the references in the kernel's Documentation/ directory say? ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ -No. See above answer. In short, if you think it really belongs in -stable, then ensure you write a decent commit log that describes who -gets impacted by the bug fix and how it manifests itself, and when the -bug was introduced. If you do that properly, then the commit will get -handled appropriately and most likely get put in the patchworks stable -queue if it really warrants it. - -If you think there is some valid information relating to it being in -stable that does *not* belong in the commit log, then use the three dash -marker line as described in -:ref:`Documentation/process/submitting-patches.rst <the_canonical_patch_format>` -to temporarily embed that information into the patch that you send. - -Are all networking bug fixes backported to all stable releases? +Are there special rules regarding stable submissions on netdev? --------------------------------------------------------------- -Due to capacity, Dave could only take care of the backports for the -last two stable releases. For earlier stable releases, each stable -branch maintainer is supposed to take care of them. If you find any -patch is missing from an earlier stable branch, please notify -stable@vger.kernel.org with either a commit ID or a formal patch -backported, and CC Dave and other relevant networking developers. +While it used to be the case that netdev submissions were not supposed +to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer +the case today. Please follow the standard stable rules in +:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`, +and make sure you include appropriate Fixes tags! Is the comment style convention different for the networking content? --------------------------------------------------------------------- diff --git a/Documentation/networking/seg6-sysctl.rst b/Documentation/networking/seg6-sysctl.rst index ec73e1445030..07c20e470baf 100644 --- a/Documentation/networking/seg6-sysctl.rst +++ b/Documentation/networking/seg6-sysctl.rst @@ -24,3 +24,16 @@ seg6_require_hmac - INTEGER * 1 - Drop SR packets without HMAC, validate SR packets with HMAC Default is 0. + +seg6_flowlabel - INTEGER + Controls the behaviour of computing the flowlabel of outer + IPv6 header in case of SR T.encaps + + == ======================================================= + -1 set flowlabel to zero. + 0 copy flowlabel from Inner packet in case of Inner IPv6 + (Set flowlabel to 0 in case IPv4/L2) + 1 Compute the flowlabel using seg6_make_flowlabel() + == ======================================================= + + Default is 0. diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index da1073acda96..01391dfd37d9 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -50,7 +50,7 @@ Callbacks to implement The NIC driver offering ipsec offload will need to implement these callbacks to make the offload available to the network stack's -XFRM subsytem. Additionally, the feature bits NETIF_F_HW_ESP and +XFRM subsystem. Additionally, the feature bits NETIF_F_HW_ESP and NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload. diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst index d9c777b18f7a..18ae21bf7f92 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -339,6 +339,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: checked additionally, and -EACCES means that 'power.disable_depth' is different from 0 + `int pm_runtime_resume_and_get(struct device *dev);` + - run pm_runtime_resume(dev) and if successful, increment the device's + usage counter; return the result of pm_runtime_resume + `int pm_request_idle(struct device *dev);` - submit a request to execute the subsystem-level idle callback for the device (the request is represented by a work item in pm_wq); returns 0 on diff --git a/Documentation/powerpc/booting.rst b/Documentation/powerpc/booting.rst index 2d0ec2ff2b57..11aa440f98cc 100644 --- a/Documentation/powerpc/booting.rst +++ b/Documentation/powerpc/booting.rst @@ -94,7 +94,7 @@ should: a) add your platform support as a _boolean_ option in arch/powerpc/Kconfig, following the example of PPC_PSERIES, - PPC_PMAC and PPC_MAPLE. The later is probably a good + PPC_PMAC and PPC_MAPLE. The latter is probably a good example of a board support to start from. b) create your main platform file as diff --git a/Documentation/powerpc/dawr-power9.rst b/Documentation/powerpc/dawr-power9.rst index c96ab6befd9c..e55ac6a24b97 100644 --- a/Documentation/powerpc/dawr-power9.rst +++ b/Documentation/powerpc/dawr-power9.rst @@ -4,7 +4,7 @@ DAWR issues on POWER9 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 +distinguish CI memory when configuring the DAWR, so (for now) the DAWR is disabled by this commit:: commit 9654153158d3e0684a1bdb76dbababdb7111d5a0 diff --git a/Documentation/powerpc/eeh-pci-error-recovery.rst b/Documentation/powerpc/eeh-pci-error-recovery.rst index 438a87ebc095..d6643a91bdf8 100644 --- a/Documentation/powerpc/eeh-pci-error-recovery.rst +++ b/Documentation/powerpc/eeh-pci-error-recovery.rst @@ -73,7 +73,7 @@ return all-ff's (0xff, 0xffff, 0xffffffff for 8/16/32-bit reads). This value was chosen because it is the same value you would get if the device was physically unplugged from the slot. This includes access to PCI memory, I/O space, and PCI config -space. Interrupts; however, will continued to be delivered. +space. Interrupts; however, will continue to be delivered. Detection and recovery are performed with the aid of ppc64 firmware. The programming interfaces in the Linux kernel diff --git a/Documentation/powerpc/elfnote.rst b/Documentation/powerpc/elfnote.rst index 06602248621c..3ec8d61e9a33 100644 --- a/Documentation/powerpc/elfnote.rst +++ b/Documentation/powerpc/elfnote.rst @@ -8,7 +8,7 @@ capabilities and information which can be used by a bootloader or userland. Types and Descriptors --------------------- -The types to be used with the "PowerPC" namesapce are defined in [#f1]_. +The types to be used with the "PowerPC" namespace are defined in [#f1]_. 1) PPC_ELFNOTE_CAPABILITIES diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/powerpc/firmware-assisted-dump.rst index 20ea8cdee0aa..e363fc48529a 100644 --- a/Documentation/powerpc/firmware-assisted-dump.rst +++ b/Documentation/powerpc/firmware-assisted-dump.rst @@ -171,7 +171,7 @@ that were present in CMA region:: (meta area) | | | - Metadata: This area holds a metadata struture whose + Metadata: This area holds a metadata structure whose address is registered with f/w and retrieved in the second kernel after crash, on platforms that support tags (OPAL). Having such structure with info needed @@ -207,7 +207,7 @@ Currently the dump will be copied from /proc/vmcore to a new file upon user intervention. The dump data available through /proc/vmcore will be in ELF format. Hence the existing kdump infrastructure (kdump scripts) to save the dump works fine with minor modifications. KDump scripts on -major Distro releases have already been modified to work seemlessly (no +major Distro releases have already been modified to work seamlessly (no user intervention in saving the dump) when FADump is used, instead of KDump, as dump mechanism. diff --git a/Documentation/powerpc/kaslr-booke32.rst b/Documentation/powerpc/kaslr-booke32.rst index 8b259fdfdf03..5681c1d1b65b 100644 --- a/Documentation/powerpc/kaslr-booke32.rst +++ b/Documentation/powerpc/kaslr-booke32.rst @@ -38,5 +38,5 @@ bit of the entropy to decide the index of the 64M zone. Then we chose a kernstart_virt_addr -To enable KASLR, set CONFIG_RANDOMIZE_BASE = y. If KASLR is enable and you +To enable KASLR, set CONFIG_RANDOMIZE_BASE = y. If KASLR is enabled and you want to disable it at runtime, add "nokaslr" to the kernel cmdline. diff --git a/Documentation/powerpc/mpc52xx.rst b/Documentation/powerpc/mpc52xx.rst index 30260707c3fe..5243b1763fad 100644 --- a/Documentation/powerpc/mpc52xx.rst +++ b/Documentation/powerpc/mpc52xx.rst @@ -34,7 +34,7 @@ To compile/use : Some remarks: - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100 - is not supported, and I'm not sure anyone is interesting in working on it + is not supported, and I'm not sure anyone is interested in working on it so. I didn't took 5xxx because there's apparently a lot of 5xxx that have nothing to do with the MPC5200. I also included the 'MPC' for the same reason. diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/powerpc/papr_hcalls.rst index 48fcf1255a33..3d553e8a2937 100644 --- a/Documentation/powerpc/papr_hcalls.rst +++ b/Documentation/powerpc/papr_hcalls.rst @@ -40,7 +40,7 @@ and any in-arguments for the hcall are provided in registers *r4-r12*. If values have to be passed through a memory buffer, the data stored in that buffer should be in Big-endian byte order. -Once control is returns back to the guest after hypervisor has serviced the +Once control returns back to the guest after hypervisor has serviced the 'HVCS' instruction the return value of the hcall is available in *r3* and any out values are returned in registers *r4-r12*. Again like in case of in-arguments, any out values stored in a memory buffer will be in Big-endian byte order. @@ -147,7 +147,7 @@ corresponding opcode values please look into the arch specific header [4]_: | Out: *numBytesRead* | Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_Hardware* -Given a DRC Index of an NVDIMM, read N-bytes from the the metadata area +Given a DRC Index of an NVDIMM, read N-bytes from the metadata area associated with it, at a specified offset and copy it to provided buffer. The metadata area stores configuration information such as label information, bad-blocks etc. The metadata area is located out-of-band of NVDIMM storage diff --git a/Documentation/powerpc/transactional_memory.rst b/Documentation/powerpc/transactional_memory.rst index b5b09bf00966..040a20675fd1 100644 --- a/Documentation/powerpc/transactional_memory.rst +++ b/Documentation/powerpc/transactional_memory.rst @@ -189,7 +189,7 @@ kernel aborted a transaction: ====================== ================================ These can be checked by the user program's abort handler as TEXASR[0:7]. If -bit 7 is set, it indicates that the error is consider persistent. For example +bit 7 is set, it indicates that the error is considered persistent. For example a TM_CAUSE_ALIGNMENT will be persistent while a TM_CAUSE_RESCHED will not. GDB @@ -271,4 +271,4 @@ with these lines: hrfid and mtmsrd have the same quirk. -The Linux kernel uses this quirk in it's early exception handling. +The Linux kernel uses this quirk in its early exception handling. diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index fa5a62f4150c..f5ba36e96461 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/process/magic-number.rst @@ -73,12 +73,10 @@ CMAGIC 0x0111 user ``include/linux/ 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`` SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` @@ -90,14 +88,12 @@ TTY_MAGIC 0x5401 tty_struct ``include/linux/ 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`` RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 3973556250e1..003c865e9c21 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -35,12 +35,6 @@ Rules on what kind of patches are accepted, and which ones are not, into the Procedure for submitting patches to the -stable tree ---------------------------------------------------- - - If the patch covers files in net/ or drivers/net please follow netdev stable - submission guidelines as described in - :ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>` - after first checking the stable networking queue at - https://patchwork.kernel.org/bundle/netdev/stable/?state=* - to ensure the requested patch is not already queued up. - Security patches should not be handled (solely) by the -stable review process but should follow the procedures in :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 8c991c863628..c66a19201deb 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -250,11 +250,6 @@ should also read :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` in addition to this file. -Note, however, that some subsystem maintainers want to come to their own -conclusions on which patches should go to the stable trees. The networking -maintainer, in particular, would rather not see individual developers -adding lines like the above to their patches. - If changes affect userland-kernel interfaces, please send the MAN-PAGES maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at least a notification of the change, so that some information makes its way @@ -346,6 +341,16 @@ that you have sent your patches to the right place. Wait for a minimum of one week before resubmitting or pinging reviewers - possibly longer during busy times like merge windows. +It's also ok to resend the patch or the patch series after a couple of +weeks with the word "RESEND" added to the subject line:: + + [PATCH Vx RESEND] sub/sys: Condensed patch summary + +Don't add "RESEND" when you are submitting a modified version of your +patch or patch series - "RESEND" only applies to resubmission of a +patch or patch series which have not been modified in any way from the +previous submission. + Include PATCH in the subject ----------------------------- @@ -630,16 +635,19 @@ not considered part of the summary phrase, but describe how the patch should be treated. Common tags might include a version descriptor if the multiple versions of the patch have been sent out in response to comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for -comments. If there are four patches in a patch series the individual -patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures -that developers understand the order in which the patches should be -applied and that they have reviewed or applied all of the patches in -the patch series. +comments. -A couple of example Subjects:: +If there are four patches in a patch series the individual patches may +be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers +understand the order in which the patches should be applied and that +they have reviewed or applied all of the patches in the patch series. + +Here are some good example Subjects:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary The ``from`` line must be the very first line in the message body, and has the form: @@ -652,34 +660,54 @@ then the ``From:`` line from the email header will be used to determine the patch author in the changelog. The explanation body will be committed to the permanent source -changelog, so should make sense to a competent reader who has long -since forgotten the immediate details of the discussion that might -have led to this patch. Including symptoms of the failure which the -patch addresses (kernel log messages, oops messages, etc.) is -especially useful for people who might be searching the commit logs -looking for the applicable patch. If a patch fixes a compile failure, -it may not be necessary to include _all_ of the compile failures; just -enough that it is likely that someone searching for the patch can find -it. As in the ``summary phrase``, it is important to be both succinct as -well as descriptive. - -The ``---`` marker line serves the essential purpose of marking for patch -handling tools where the changelog message ends. - -One good use for the additional comments after the ``---`` marker is for -a ``diffstat``, to show what files have changed, and the number of -inserted and deleted lines per file. A ``diffstat`` is especially useful -on bigger patches. Other comments relevant only to the moment or the -maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be ``patch changelogs`` -which describe what has changed between the v1 and v2 version of the -patch. - -If you are going to include a ``diffstat`` after the ``---`` marker, please -use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from -the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). (``git`` -generates appropriate diffstats by default.) +changelog, so should make sense to a competent reader who has long since +forgotten the immediate details of the discussion that might have led to +this patch. Including symptoms of the failure which the patch addresses +(kernel log messages, oops messages, etc.) are especially useful for +people who might be searching the commit logs looking for the applicable +patch. The text should be written in such detail so that when read +weeks, months or even years later, it can give the reader the needed +details to grasp the reasoning for **why** the patch was created. + +If a patch fixes a compile failure, it may not be necessary to include +_all_ of the compile failures; just enough that it is likely that +someone searching for the patch can find it. As in the ``summary +phrase``, it is important to be both succinct as well as descriptive. + +The ``---`` marker line serves the essential purpose of marking for +patch handling tools where the changelog message ends. + +One good use for the additional comments after the ``---`` marker is +for a ``diffstat``, to show what files have changed, and the number of +inserted and deleted lines per file. A ``diffstat`` is especially useful +on bigger patches. If you are going to include a ``diffstat`` after the +``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that +filenames are listed from the top of the kernel source tree and don't +use too much horizontal space (easily fit in 80 columns, maybe with some +indentation). (``git`` generates appropriate diffstats by default.) + +Other comments relevant only to the moment or the maintainer, not +suitable for the permanent changelog, should also go here. A good +example of such comments might be ``patch changelogs`` which describe +what has changed between the v1 and v2 version of the patch. + +Please put this information **after** the ``---`` line which separates +the changelog from the rest of the patch. The version information is +not part of the changelog which gets committed to the git tree. It is +additional information for the reviewers. If it's placed above the +commit tags, it needs manual interaction to remove it. If it is below +the separator line, it gets automatically stripped off when applying the +patch:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + path/to/file | 5+++-- + ... See more details on the proper patch format in the following references. diff --git a/Documentation/s390/pci.rst b/Documentation/s390/pci.rst index 492850bff316..8157f0cddbc2 100644 --- a/Documentation/s390/pci.rst +++ b/Documentation/s390/pci.rst @@ -50,7 +50,8 @@ Entries specific to zPCI functions and entries that hold zPCI information. * /sys/bus/pci/slots/XXXXXXXX The slot entries are set up using the function identifier (FID) of the - PCI function. + PCI function. The format depicted as XXXXXXXX above is 8 hexadecimal digits + with 0 padding and lower case hexadecimal digitis. - /sys/bus/pci/slots/XXXXXXXX/power @@ -88,8 +89,15 @@ Entries specific to zPCI functions and entries that hold zPCI information. is attached to. - uid - The unique identifier (UID) is defined when configuring an LPAR and is - unique in the LPAR. + The user identifier (UID) may be defined as part of the machine + configuration or the z/VM or KVM guest configuration. If the accompanying + uid_is_unique attribute is 1 the platform guarantees that the UID is unique + within that instance and no devices with the same UID can be attached + during the lifetime of the system. + + - uid_is_unique + Indicates whether the user identifier (UID) is guaranteed to be and remain + unique within this Linux instance. - pfip/segmentX The segments determine the isolation of a function. diff --git a/Documentation/scheduler/sched-domains.rst b/Documentation/scheduler/sched-domains.rst index 8582fa5e9170..14ea2f21d20e 100644 --- a/Documentation/scheduler/sched-domains.rst +++ b/Documentation/scheduler/sched-domains.rst @@ -74,8 +74,8 @@ for a given topology level by creating a sched_domain_topology_level array and calling set_sched_topology() with this array as the parameter. The sched-domains debugging infrastructure can be enabled by enabling -CONFIG_SCHED_DEBUG and adding 'sched_debug' to your cmdline. If you forgot to -tweak your cmdline, you can also flip the /sys/kernel/debug/sched_debug -knob. This enables an error checking parse of the sched domains which should -catch most possible errors (described above). It also prints out the domain -structure in a visual format. +CONFIG_SCHED_DEBUG and adding 'sched_debug_verbose' to your cmdline. If you +forgot to tweak your cmdline, you can also flip the +/sys/kernel/debug/sched/verbose knob. This enables an error checking parse of +the sched domains which should catch most possible errors (described above). It +also prints out the domain structure in a visual format. diff --git a/Documentation/scsi/BusLogic.rst b/Documentation/scsi/BusLogic.rst index b60169812358..d7d4d56981ca 100644 --- a/Documentation/scsi/BusLogic.rst +++ b/Documentation/scsi/BusLogic.rst @@ -251,8 +251,6 @@ BT-445C VLB Fast SCSI-2 BT-747C EISA Fast SCSI-2 BT-757C EISA Wide Fast SCSI-2 BT-757CD EISA Wide Differential Fast SCSI-2 -BT-545C ISA Fast SCSI-2 -BT-540CF ISA Fast SCSI-2 ======== ==== ============================== MultiMaster "S" Series Host Adapters: @@ -263,17 +261,13 @@ BT-747S EISA Fast SCSI-2 BT-747D EISA Differential Fast SCSI-2 BT-757S EISA Wide Fast SCSI-2 BT-757D EISA Wide Differential Fast SCSI-2 -BT-545S ISA Fast SCSI-2 -BT-542D ISA Differential Fast SCSI-2 BT-742A EISA SCSI-2 (742A revision H) -BT-542B ISA SCSI-2 (542B revision H) ======= ==== ============================== MultiMaster "A" Series Host Adapters: ======= ==== ============================== BT-742A EISA SCSI-2 (742A revisions A - G) -BT-542B ISA SCSI-2 (542B revisions A - G) ======= ==== ============================== AMI FastDisk Host Adapters that are true BusLogic MultiMaster clones are also @@ -400,26 +394,11 @@ selected host adapter. The BusLogic Driver Probing Options comprise the following: -IO:<integer> - - The "IO:" option specifies an ISA I/O Address to be probed for a non-PCI - MultiMaster Host Adapter. If neither "IO:" nor "NoProbeISA" options are - specified, then the standard list of BusLogic MultiMaster ISA I/O Addresses - will be probed (0x330, 0x334, 0x230, 0x234, 0x130, and 0x134). Multiple - "IO:" options may be specified to precisely determine the I/O Addresses to - be probed, but the probe order will always follow the standard list. - NoProbe The "NoProbe" option disables all probing and therefore no BusLogic Host Adapters will be detected. -NoProbeISA - - The "NoProbeISA" option disables probing of the standard BusLogic ISA I/O - Addresses and therefore only PCI MultiMaster and FlashPoint Host Adapters - will be detected. - NoProbePCI The "NoProbePCI" options disables the interrogation of PCI Configuration @@ -464,10 +443,7 @@ QueueDepth:<integer> Depth for devices that do not support Tagged Queuing. If no Queue Depth option is provided, the Queue Depth will be determined automatically based on the Host Adapter's Total Queue Depth and the number, type, speed, and - capabilities of the detected Target Devices. For Host Adapters that - require ISA Bounce Buffers, the Queue Depth is automatically set by default - to BusLogic_TaggedQueueDepthBB or BusLogic_UntaggedQueueDepthBB to avoid - excessive preallocation of DMA Bounce Buffer memory. Target Devices that + capabilities of the detected Target Devices. Target Devices that do not support Tagged Queuing always have their Queue Depth set to BusLogic_UntaggedQueueDepth or BusLogic_UntaggedQueueDepthBB, unless a lower Queue Depth option is provided. A Queue Depth of 1 automatically diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index d2052fdbedd2..cbb329956897 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -220,7 +220,7 @@ Older Version : 2.20.4.5 (scsi module), 2.20.2.5 (cmm module) 4. Use the pre defined DMA mask constants from dma-mapping.h Use the DMA_{64,32}BIT_MASK constants from dma-mapping.h when calling - pci_set_dma_mask() or pci_set_consistend_dma_mask(). See + pci_set_dma_mask() or pci_set_consistent_dma_mask(). See http://marc.theaimsgroup.com/?t=108001993000001&r=1&w=2 for more details. Signed-off-by: Tobias Klauser <tklauser@nuerscht.ch> diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 5bc17d012b25..096ffe9cae0e 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -1095,10 +1095,6 @@ of interest: - maximum number of commands that can be queued on devices controlled by the host. Overridden by LLD calls to scsi_change_queue_depth(). - unchecked_isa_dma - - 1=>only use bottom 16 MB of ram (ISA DMA addressing - restriction), 0=>can use full 32 bit (or better) DMA - address space no_async_abort - 1=>Asynchronous aborts are not supported - 0=>Timed-out commands will be aborted asynchronously diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 1da879a68640..80d5a5af62a1 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -6,30 +6,127 @@ Trusted and Encrypted Keys are two new key types added to the existing kernel key ring service. Both of these new types are variable length symmetric keys, and in both cases all keys are created in the kernel, and user space sees, stores, and loads only encrypted blobs. Trusted Keys require the availability -of a Trusted Platform Module (TPM) chip for greater security, while Encrypted -Keys can be used on any system. All user level blobs, are displayed and loaded -in hex ascii for convenience, and are integrity verified. +of a Trust Source for greater security, while Encrypted Keys can be used on any +system. All user level blobs, are displayed and loaded in hex ASCII for +convenience, and are integrity verified. -Trusted Keys use a TPM both to generate and to seal the keys. Keys are sealed -under a 2048 bit RSA key in the TPM, and optionally sealed to specified PCR -(integrity measurement) values, and only unsealed by the TPM, if PCRs and blob -integrity verifications match. A loaded Trusted Key can be updated with new -(future) PCR values, so keys are easily migrated to new pcr values, such as -when the kernel and initramfs are updated. The same key can have many saved -blobs under different PCR values, so multiple boots are easily supported. -TPM 1.2 -------- +Trust Source +============ -By default, trusted keys are sealed under the SRK, which has the default -authorization value (20 zeros). This can be set at takeownership time with the -trouser's utility: "tpm_takeownership -u -z". +A trust source provides the source of security for Trusted Keys. This +section lists currently supported trust sources, along with their security +considerations. Whether or not a trust source is sufficiently safe depends +on the strength and correctness of its implementation, as well as the threat +environment for a specific use case. Since the kernel doesn't know what the +environment is, and there is no metric of trust, it is dependent on the +consumer of the Trusted Keys to determine if the trust source is sufficiently +safe. -TPM 2.0 -------- + * Root of trust for storage -The user must first create a storage key and make it persistent, so the key is -available after reboot. This can be done using the following commands. + (1) TPM (Trusted Platform Module: hardware device) + + Rooted to Storage Root Key (SRK) which never leaves the TPM that + provides crypto operation to establish root of trust for storage. + + (2) TEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone) + + Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip + fuses and is accessible to TEE only. + + * Execution isolation + + (1) TPM + + Fixed set of operations running in isolated execution environment. + + (2) TEE + + Customizable set of operations running in isolated execution + environment verified via Secure/Trusted boot process. + + * Optional binding to platform integrity state + + (1) TPM + + Keys can be optionally sealed to specified PCR (integrity measurement) + values, and only unsealed by the TPM, if PCRs and blob integrity + verifications match. A loaded Trusted Key can be updated with new + (future) PCR values, so keys are easily migrated to new PCR values, + such as when the kernel and initramfs are updated. The same key can + have many saved blobs under different PCR values, so multiple boots are + easily supported. + + (2) TEE + + Relies on Secure/Trusted boot process for platform integrity. It can + be extended with TEE based measured boot process. + + * Interfaces and APIs + + (1) TPM + + TPMs have well-documented, standardized interfaces and APIs. + + (2) TEE + + TEEs have well-documented, standardized client interface and APIs. For + more details refer to ``Documentation/staging/tee.rst``. + + + * Threat model + + The strength and appropriateness of a particular TPM or TEE for a given + purpose must be assessed when using them to protect security-relevant data. + + +Key Generation +============== + +Trusted Keys +------------ + +New keys are created from random numbers generated in the trust source. They +are encrypted/decrypted using a child key in the storage key hierarchy. +Encryption and decryption of the child key must be protected by a strong +access control policy within the trust source. + + * TPM (hardware device) based RNG + + Strength of random numbers may vary from one device manufacturer to + another. + + * TEE (OP-TEE based on Arm TrustZone) based RNG + + RNG is customizable as per platform needs. It can either be direct output + from platform specific hardware RNG or a software based Fortuna CSPRNG + which can be seeded via multiple entropy sources. + +Encrypted Keys +-------------- + +Encrypted keys do not depend on a trust source, and are faster, as they use AES +for encryption/decryption. New keys are created from kernel-generated random +numbers, and are encrypted/decrypted using a specified ‘master’ key. The +‘master’ key can either be a trusted-key or user-key type. The main disadvantage +of encrypted keys is that if they are not rooted in a trusted key, they are only +as secure as the user key encrypting them. The master user key should therefore +be loaded in as secure a way as possible, preferably early in boot. + + +Usage +===== + +Trusted Keys usage: TPM +----------------------- + +TPM 1.2: By default, trusted keys are sealed under the SRK, which has the +default authorization value (20 bytes of 0s). This can be set at takeownership +time with the TrouSerS utility: "tpm_takeownership -u -z". + +TPM 2.0: The user must first create a storage key and make it persistent, so the +key is available after reboot. This can be done using the following commands. With the IBM TSS 2 stack:: @@ -78,14 +175,21 @@ TPM_STORED_DATA format. The key length for new keys are always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding. -Encrypted keys do not depend on a TPM, and are faster, as they use AES for -encryption/decryption. New keys are created from kernel generated random -numbers, and are encrypted/decrypted using a specified 'master' key. The -'master' key can either be a trusted-key or user-key type. The main -disadvantage of encrypted keys is that if they are not rooted in a trusted key, -they are only as secure as the user key encrypting them. The master user key -should therefore be loaded in as secure a way as possible, preferably early in -boot. +Trusted Keys usage: TEE +----------------------- + +Usage:: + + keyctl add trusted name "new keylen" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + +"keyctl print" returns an ASCII hex copy of the sealed key, which is in format +specific to TEE device implementation. The key length for new keys is always +in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). + +Encrypted Keys usage +-------------------- The decrypted portion of encrypted keys can contain either a simple symmetric key or a more complex structure. The format of the more complex structure is @@ -103,8 +207,8 @@ Where:: format:= 'default | ecryptfs | enc32' key-type:= 'trusted' | 'user' - -Examples of trusted and encrypted key usage: +Examples of trusted and encrypted key usage +------------------------------------------- Create and save a trusted key named "kmk" of length 32 bytes. @@ -150,7 +254,7 @@ Load a trusted key from the saved blob:: f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b e4a8aea2b607ec96931e6f4d4fe563ba -Reseal a trusted key under new pcr values:: +Reseal (TPM specific) a trusted key under new PCR values:: $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`" $ keyctl print 268728824 @@ -164,11 +268,12 @@ Reseal a trusted key under new pcr values:: 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8 + The initial consumer of trusted keys is EVM, which at boot time needs a high -quality symmetric key for HMAC protection of file metadata. The use of a +quality symmetric key for HMAC protection of file metadata. The use of a trusted key provides strong guarantees that the EVM key has not been -compromised by a user level problem, and when sealed to specific boot PCR -values, protects against boot and offline attacks. Create and save an +compromised by a user level problem, and when sealed to a platform integrity +state, protects against boot and offline attacks. Create and save an encrypted key "evm" using the above trusted key "kmk": option 1: omitting 'format':: @@ -207,3 +312,61 @@ about the usage can be found in the file Another new format 'enc32' has been defined in order to support encrypted keys with payload size of 32 bytes. This will initially be used for nvdimm security but may expand to other usages that require 32 bytes payload. + + +TPM 2.0 ASN.1 Key Format +------------------------ + +The TPM 2.0 ASN.1 key format is designed to be easily recognisable, +even in binary form (fixing a problem we had with the TPM 1.2 ASN.1 +format) and to be extensible for additions like importable keys and +policy:: + + TPMKey ::= SEQUENCE { + type OBJECT IDENTIFIER + emptyAuth [0] EXPLICIT BOOLEAN OPTIONAL + parent INTEGER + pubkey OCTET STRING + privkey OCTET STRING + } + +type is what distinguishes the key even in binary form since the OID +is provided by the TCG to be unique and thus forms a recognizable +binary pattern at offset 3 in the key. The OIDs currently made +available are:: + + 2.23.133.10.1.3 TPM Loadable key. This is an asymmetric key (Usually + RSA2048 or Elliptic Curve) which can be imported by a + TPM2_Load() operation. + + 2.23.133.10.1.4 TPM Importable Key. This is an asymmetric key (Usually + RSA2048 or Elliptic Curve) which can be imported by a + TPM2_Import() operation. + + 2.23.133.10.1.5 TPM Sealed Data. This is a set of data (up to 128 + bytes) which is sealed by the TPM. It usually + represents a symmetric key and must be unsealed before + use. + +The trusted key code only uses the TPM Sealed Data OID. + +emptyAuth is true if the key has well known authorization "". If it +is false or not present, the key requires an explicit authorization +phrase. This is used by most user space consumers to decide whether +to prompt for a password. + +parent represents the parent key handle, either in the 0x81 MSO space, +like 0x81000001 for the RSA primary storage key. Userspace programmes +also support specifying the primary handle in the 0x40 MSO space. If +this happens the Elliptic Curve variant of the primary key using the +TCG defined template will be generated on the fly into a volatile +object and used as the parent. The current kernel code only supports +the 0x81 MSO form. + +pubkey is the binary representation of TPM2B_PRIVATE excluding the +initial TPM2B header, which can be reconstructed from the ASN.1 octet +string length. + +privkey is the binary representation of TPM2B_PUBLIC excluding the +initial TPM2B header which can be reconstructed from the ASN.1 octed +string length. diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py index a3eea0bbe6ba..16bea0632555 100755 --- a/Documentation/sphinx/rstFlatTable.py +++ b/Documentation/sphinx/rstFlatTable.py @@ -22,7 +22,7 @@ u""" * *auto span* rightmost cell of a table row over the missing cells on the right side of that table-row. With Option ``:fill-cells:`` this behavior - can changed from *auto span* to *auto fill*, which automaticly inserts + can be changed from *auto span* to *auto fill*, which automatically inserts (empty) cells instead of spanning the last cell. Options: @@ -161,7 +161,7 @@ class ListTableBuilder(object): for colwidth in colwidths: colspec = nodes.colspec(colwidth=colwidth) # FIXME: It seems, that the stub method only works well in the - # absence of rowspan (observed by the html buidler, the docutils-xml + # absence of rowspan (observed by the html builder, the docutils-xml # build seems OK). This is not extraordinary, because there exists # no table directive (except *this* flat-table) which allows to # define coexistent of rowspan and stubs (there was no use-case diff --git a/Documentation/spi/butterfly.rst b/Documentation/spi/butterfly.rst index e614a589547c..56088fb090c7 100644 --- a/Documentation/spi/butterfly.rst +++ b/Documentation/spi/butterfly.rst @@ -11,7 +11,7 @@ develop firmware for this, and flash it using this adapter cable. You can make this adapter from an old printer cable and solder things directly to the Butterfly. Or (if you have the parts and skills) you -can come up with something fancier, providing ciruit protection to the +can come up with something fancier, providing circuit protection to the Butterfly and the printer port, or with a better power supply than two signal pins from the printer port. Or for that matter, you can use similar cables to talk to many AVR boards, even a breadboard. diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst index f1daffe10d78..d4239025461d 100644 --- a/Documentation/spi/spi-summary.rst +++ b/Documentation/spi/spi-summary.rst @@ -411,8 +411,11 @@ any more such messages. duplex (one pointer is NULL) transfers; + optionally defining short delays after transfers ... using - the spi_transfer.delay_usecs setting (this delay can be the - only protocol effect, if the buffer length is zero); + the spi_transfer.delay.value setting (this delay can be the + only protocol effect, if the buffer length is zero) ... + when specifying this delay the default spi_transfer.delay.unit + is microseconds, however this can be adjusted to clock cycles + or nanoseconds if needed; + whether the chipselect becomes inactive after a transfer and any delay ... by using the spi_transfer.cs_change flag; diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 090d2949d345..0046d75d9a70 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -330,17 +330,17 @@ la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti* - head col 3 - head col 4 - * - column 1 + * - row 1 - field 1.1 - field 1.2 with autospan - * - column 2 + * - row 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - - column 3 + - row 3 Che verrà rappresentata nel seguente modo: @@ -352,37 +352,46 @@ Che verrà rappresentata nel seguente modo: - head col 3 - head col 4 - * - column 1 + * - row 1 - field 1.1 - field 1.2 with autospan - * - column 2 + * - row 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - - column 3 + - row 3 Riferimenti incrociati ---------------------- -Per fare dei riferimenti incrociati da una pagina ad un'altra -specificando il percorso a partire dalla cartella *Documentation*. -Per esempio, se volete aggiungere un riferimento a questa pagina -(l'estensione .rst è opzionale):: +Aggiungere un riferimento incrociato da una pagina della +documentazione ad un'altra può essere fatto scrivendo il percorso al +file corrispondende, non serve alcuna sintassi speciale. Si possono +usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con +"documentation/". Per esempio, potete fare riferimento a questo +documento in uno dei seguenti modi (da notare che l'estensione +``.rst`` è necessaria):: - See Documentation/translations/it_IT/doc-guide/sphinx.rst. + Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre + Guardate pshinx.rst, che si trova nella stessa cartella. + Leggete ../sphinx.rst, che si trova nella cartella precedente. -Se preferite usare un percorso relative allora vi serve la direttiva -Sphinx ``doc``. Per esempio, se volete aggiungere un riferimento a -questa pagina dalla stessa cartella:: +Se volete che il collegamento abbia un testo diverso rispetto al +titolo del documento, allora dovrete usare la direttiva Sphinx +``doc``. Per esempio:: - See :doc:`sphinx`. + Vedere :doc:`il mio testo per il collegamento <sphinx>`. -Per maggiori informazioni su come aggiungere riferimenti incrociati a -commenti kernel-doc di funzioni o tipi, leggete -Documentation/translations/it_IT/doc-guide/sphinx.rst. +Nella maggioranza dei casi si consiglia il primo metodo perché è più +pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:`` +che non da alcun valore, sentitevi liberi di convertirlo in un +percorso al documento. + +Per informazioni riguardo ai riferimenti incrociati ai commenti +kernel-doc per funzioni o tipi, consultate .. _it_sphinx_kfigure: @@ -391,7 +400,7 @@ Figure ed immagini Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure`` e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in -formato SVG:: +formato SVG (:ref:`it_svg_image_example`):: .. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: una semplice immagine SVG diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 3d30b69f1ec1..f6beb385b4ac 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -369,7 +369,7 @@ all'inizio dell'avvio del sistema è attraverso la procedura Prima di inventare la vostra cache per gli oggetti più usati, considerate l'uso di una cache slab disponibile in ``include/linux/slab.h``. -:c:func:`current()` +:c:macro:`current` ------------------- Definita in ``include/asm/current.h`` diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index bf1acd6204ef..1e7c84def369 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -127,11 +127,11 @@ il vostro processo si auto-sospenderà ; verrà riattivato quando il mutex verrà rilasciato. Questo significa che il processore potrà occuparsi d'altro mentre il vostro processo è in attesa. Esistono molti casi in cui non potete permettervi di sospendere un processo (vedere -:ref:`Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? <it_sleeping-things>`) +`Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni?`_) e quindi dovrete utilizzare gli spinlock. Nessuno di questi *lock* è ricorsivo: vedere -:ref:`Stallo: semplice ed avanzato <it_deadlock>` +`Stallo: semplice ed avanzato`_ I *lock* e i kernel per sistemi monoprocessore ---------------------------------------------- @@ -190,7 +190,7 @@ perfetto questa funzione si chiamerebbe 'spin_lock_softirq()'). Da notare che in questo caso potete utilizzare anche spin_lock_irq() o spin_lock_irqsave(), queste fermano anche le interruzioni hardware: -vedere :ref:`Contesto di interruzione hardware <it_hardirq-context>`. +vedere `Contesto di interruzione hardware`_. Questo funziona alla perfezione anche sui sistemi monoprocessore: gli spinlock svaniscono e questa macro diventa semplicemente local_bh_disable() @@ -241,7 +241,7 @@ Lo stesso softirq Lo stesso softirq può essere eseguito su un diverso processore: allo scopo di migliorare le prestazioni potete utilizzare dati riservati ad ogni -processore (vedere :ref:`Dati per processore <it_per-cpu>`). Se siete arrivati +processore (vedere `Dati per processore`_). Se siete arrivati fino a questo punto nell'uso dei softirq, probabilmente tenete alla scalabilità delle prestazioni abbastanza da giustificarne la complessità aggiuntiva. @@ -896,8 +896,6 @@ leggendo solamente il codice. E come dice Alan Cox: “Lock data, not codeâ€. Problemi comuni =============== -.. _`it_deadlock`: - Stallo: semplice ed avanzato ---------------------------- @@ -1282,7 +1280,6 @@ Il beneficio qui sta nel fatto che il contatore di riferimenti no viene scritto: l'oggetto non viene alterato in alcun modo e quindi diventa molto più veloce su sistemi molti-processore grazie alla loro memoria cache. -.. _`it_per-cpu`: Dati per processore ------------------- @@ -1333,7 +1330,6 @@ Naturalmente, questo è più lento della semplice chiamata spin_lock_irq(), quindi ha senso solo se questo genere di accesso è estremamente raro. -.. _`it_sleeping-things`: Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? ========================================================================= diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst index 8012fe9497ae..54fd255b77d0 100644 --- a/Documentation/translations/it_IT/process/4.Coding.rst +++ b/Documentation/translations/it_IT/process/4.Coding.rst @@ -264,11 +264,10 @@ La maggior parte di queste opzioni possono essere attivate per qualsiasi kernel utilizzato per lo sviluppo o a scopo di test. In particolare dovreste attivare: - - ENABLE_MUST_CHECK e FRAME_WARN per ottenere degli - avvertimenti dedicati a problemi come l'uso di interfacce deprecate o - l'ignorare un importante valore di ritorno di una funzione. Il risultato - generato da questi avvertimenti può risultare verboso, ma non bisogna - preoccuparsi per gli avvertimenti provenienti da altre parti del kernel. + - FRAME_WARN per ottenere degli avvertimenti su stack frame più + grandi di un dato valore. Il risultato generato da questi + avvertimenti può risultare verboso, ma non bisogna preoccuparsi per + gli avvertimenti provenienti da altre parti del kernel. - DEBUG_OBJECTS aggiungerà un codice per tracciare il ciclo di vita di diversi oggetti creati dal kernel e avvisa quando qualcosa viene eseguito diff --git a/Documentation/translations/it_IT/process/adding-syscalls.rst b/Documentation/translations/it_IT/process/adding-syscalls.rst index c478b6e8c292..df8c652d004b 100644 --- a/Documentation/translations/it_IT/process/adding-syscalls.rst +++ b/Documentation/translations/it_IT/process/adding-syscalls.rst @@ -562,7 +562,7 @@ kernel. Se la nuova funzionalità è utile all'interno del kernel, per esempio dev'essere condivisa fra una vecchia e una nuova chiamata di sistema o dev'essere utilizzata da una chiamata di sistema e la sua variante compatibile, allora dev'essere implementata come una funzione di supporto -(*helper function*) (per esempio ``kern_xyzzy()``). Questa funzione potrà +(*helper function*) (per esempio ``ksys_xyzzy()``). Questa funzione potrà essere chiamata dallo *stub* (``sys_xyzzy()``), dalla variante compatibile (``compat_sys_xyzzy()``), e/o da altri parti del kernel. diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index c86c4543f249..95f2e7c985e2 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -75,9 +75,26 @@ stessa riga: if (condition) do_this; do_something_everytime; -né mettete più assegnamenti sulla stessa riga. Lo stile del kernel +Non usate le virgole per evitare le parentesi: + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +Invece, usate sempre le parentesi per racchiudere più istruzioni. + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + +Non mettete nemmeno più assegnamenti sulla stessa riga. Lo stile del kernel è ultrasemplice. Evitate espressioni intricate. + Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è volutamente errato. @@ -320,8 +337,7 @@ qualcosa di simile, **non** dovreste chiamarla ``cntusr()``. Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione ungherese) è stupido - il compilatore conosce comunque il tipo e -può verificarli, e inoltre confonde i programmatori. Non c'è da -sorprendersi che MicroSoft faccia programmi bacati. +può verificarli, e inoltre confonde i programmatori. Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``. diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 1db5a1082389..9554368a2ae2 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -357,17 +357,10 @@ benvenuti. Riportare Bug ------------- -https://bugzilla.kernel.org è dove gli sviluppatori del kernel Linux tracciano -i bachi del kernel. Gli utenti sono incoraggiati nel riportare tutti i bachi -che trovano utilizzando questo strumento. -Per maggiori dettagli su come usare il bugzilla del kernel, guardare: - - https://bugzilla.kernel.org/page.cgi?id=faq.html - -Il file admin-guide/reporting-bugs.rst nella cartella principale del kernel -fornisce un buon modello sul come segnalare un baco nel kernel, e spiega quali -informazioni sono necessarie agli sviluppatori per poter aiutare il -rintracciamento del problema. +Il file 'Documentation/admin-guide/reporting-issues.rst' nella +cartella principale del kernel spiega come segnalare un baco nel +kernel, e fornisce dettagli su quali informazioni sono necessarie agli +sviluppatori del kernel per poter studiare il problema. Gestire i rapporti sui bug -------------------------- @@ -380,8 +373,14 @@ al corrente della vostra presenza. Riparare bachi è una delle migliori vie per acquisire meriti tra gli altri sviluppatori, perchè non a molte persone piace perdere tempo a sistemare i bachi di altri. -Per lavorare sui rapporti di bachi già riportati, andate su -https://bugzilla.kernel.org. +Per lavorare sui bachi già segnalati, per prima cosa cercate il +sottosistema che vi interessa. Poi, verificate nel file MAINTAINERS +dove vengono collezionati solitamente i bachi per quel sottosistema; +spesso sarà una lista di discussione, raramente un bugtracker. Cercate +bachi nell'archivio e aiutate dove credete di poterlo fare. Potete +anche consultare https://bugzilla.kernel.org; però, solo una manciata di +sottosistemi lo usano attivamente, ciò nonostante i bachi che +coinvolgono l'intero kernel sono sempre riportati lì. Liste di discussione -------------------- diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst index 1af30f4228f2..f452fafb1e84 100644 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -79,12 +79,10 @@ CMAGIC 0x0111 user ``include/linux/ 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`` SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` @@ -96,16 +94,13 @@ TTY_MAGIC 0x5401 tty_struct ``include/linux/ 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`` @@ -148,7 +143,6 @@ PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/me 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`` diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst index 614fc17d9086..2fc09cc1f0be 100644 --- a/Documentation/translations/it_IT/process/submit-checklist.rst +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -28,6 +28,10 @@ sottomissione delle patch, in particolare c) quando si usa ``O=builddir`` + d) Qualsiasi modifica in Documentation/ deve compilare con successo senza + avvisi o errori. Usare ``make htmldocs`` o ``make pdfdocs`` per verificare + e correggere i problemi + 3) Compilare per diverse architetture di processore usando strumenti per la cross-compilazione o altri. @@ -54,8 +58,7 @@ sottomissione delle patch, in particolare 9) Verificare con sparse. -10) Usare ``make checkstack`` e ``make namespacecheck`` e correggere tutti i - problemi rilevati. +10) Usare ``make checkstack`` e correggere tutti i problemi rilevati. .. note:: @@ -95,31 +98,29 @@ sottomissione delle patch, in particolare informazioni. Le patch che modificano le interfacce utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. -20) Verifica che il kernel passi con successo ``make headers_check`` - -21) La patch è stata verificata con l'iniezione di fallimenti in slab e +20) La patch è stata verificata con l'iniezione di fallimenti in slab e nell'allocazione di pagine. Vedere ``Documentation/fault-injection/``. Se il nuovo codice è corposo, potrebbe essere opportuno aggiungere l'iniezione di fallimenti specifici per il sottosistema. -22) Il nuovo codice è stato compilato con ``gcc -W`` (usate +21) Il nuovo codice è stato compilato con ``gcc -W`` (usate ``make KCFLAGS=-W``). Questo genererà molti avvisi, ma è ottimo per scovare bachi come "warning: comparison between signed and unsigned". -23) La patch è stata verificata dopo essere stata inclusa nella serie di patch +22) La patch è stata verificata dopo essere stata inclusa nella serie di patch -mm; questo al fine di assicurarsi che continui a funzionare assieme a tutte le altre patch in coda e i vari cambiamenti nei sottosistemi VM, VFS e altri. -24) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``, +23) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``, ``rmb()``, ``wmb()``} devono essere accompagnate da un commento nei sorgenti che ne spieghi la logica: cosa fanno e perché. -25) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate +24) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate ``Documentation/userspace-api/ioctl/ioctl-number.rst``. -26) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o +25) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o funzionalità del kernel che è associata a uno dei seguenti simboli ``Kconfig``, allora verificate che il kernel compili con diverse configurazioni dove i simboli sono disabilitati e/o ``=m`` (se c'è la diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index ae00352346ed..ded95048b9a8 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -433,6 +433,14 @@ Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno ignorate, ma potete farlo per meglio identificare procedure aziendali interne o per aggiungere dettagli circa la firma. +In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da +parte di tutte quelle persone che si sono occupate della gestione e +del trasporto della patch. Queste però non sono state coinvolte nello +sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso +**reale** che una patch a intrapreso dallo sviluppatore, fino al +manutentore, per poi giungere a Linus. + + Quando utilizzare Acked-by:, Cc:, e Co-developed-by: ---------------------------------------------------- @@ -574,6 +582,10 @@ kernel stabili al fine di capire quale kernel deve ricevere la correzione. Questo è il modo suggerito per indicare che un baco è stato corretto nella patch. Per maggiori dettagli leggete :ref:`it_describe_changes` +Da notare che aggiungere un tag "Fixes:" non esime dalle regole +previste per i kernel stabili, e nemmeno dalla necessità di aggiungere +in copia conoscenza stable@vger.kernel.org su tutte le patch per +suddetti kernel. Il formato canonico delle patch ------------------------------- @@ -642,16 +654,20 @@ Le etichette non verranno considerate come parte della frase riassuntiva, ma indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni ci sono quelle di versione che vengono usate quando una patch è stata inviata più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si -attendono dei commenti (*Request For Comments*). Se ci sono quattro patch -nella serie, queste dovrebbero essere enumerate così: 1/4, 2/4, 3/4, 4/4. -Questo assicura che gli sviluppatori capiranno l'ordine in cui le patch -dovrebbero essere applicate, e per tracciare quelle che hanno revisionate o -che hanno applicato. +attendono dei commenti (*Request For Comments*). + +Se ci sono quattro patch nella serie, queste dovrebbero essere +enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli +sviluppatori capiranno l'ordine in cui le patch dovrebbero essere +applicate, e per tracciare quelle che hanno revisionate o che hanno +applicato. Un paio di esempi di oggetti:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel formato: @@ -668,30 +684,76 @@ deve aver senso per un lettore esperto che è ha dimenticato i dettagli della discussione che hanno portato alla patch. L'inclusione di informazioni sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops, eccetera) è particolarmente utile per le persone che potrebbero cercare fra -i messaggi di log per la patch che li tratta. Se la patch corregge un errore -di compilazione, non sarà necessario includere proprio _tutto_ quello che -è uscito dal compilatore; aggiungete solo quello che è necessario per far si -che la vostra patch venga trovata. Come nella ``summary phrase``, è importante -essere sia brevi che descrittivi. +i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto +con abbastanza dettagli da far capire al lettore **perché** quella +patch fu creata, e questo a distanza di settimane, mesi, o addirittura +anni. + +Se la patch corregge un errore di compilazione, non sarà necessario +includere proprio _tutto_ quello che è uscito dal compilatore; +aggiungete solo quello che è necessario per far si che la vostra patch +venga trovata. Come nella ``summary phrase``, è importante essere sia +brevi che descrittivi. La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce il messaggio di changelog. Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi. -Un ``diffstat`` è particolarmente utile per le patch grandi. Altri commenti -che sono importanti solo per i manutentori, quindi inadatti al changelog -permanente, dovrebbero essere messi qui. Un buon esempio per questo tipo -di commenti potrebbe essere quello di descrivere le differenze fra le versioni +Un ``diffstat`` è particolarmente utile per le patch grandi. Se +includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` +cosicché i nomi dei file elencati non occupino troppo spazio +(facilmente rientreranno negli 80 caratteri, magari con qualche +indentazione). (``git`` genera di base dei diffstat adatti). + +I commenti che sono importanti solo per i manutentori, quindi +inadatti al changelog permanente, dovrebbero essere messi qui. Un +buon esempio per questo tipo di commenti potrebbe essere il cosiddetto +``patch changelogs`` che descrivere le differenze fra le versioni della patch. -Se includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` -cosicché i nomi dei file elencati non occupino troppo spazio (facilmente -rientreranno negli 80 caratteri, magari con qualche indentazione). -(``git`` genera di base dei diffstat adatti). +Queste informazioni devono andare **dopo** la linea ``---`` che separa +il *changelog* dal resto della patch. Le informazioni riguardanti la +versione di una patch non sono parte del *chagelog* che viene incluso +in git. Queste sono informazioni utili solo ai revisori. Se venissero +messe sopra la riga, qualcuno dovrà fare del lavoro manuale per +rimuoverle; cosa che invece viene fatta automaticamente quando vengono +messe correttamente oltre la riga.:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + path/to/file | 5+++-- + ... Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito. +Aggiungere i *backtrace* nei messaggi di commit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +I *backtrace* aiutano a documentare la sequenza di chiamate a funzione +che portano ad un problema. Tuttavia, non tutti i *backtrace* sono +davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche +e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante +informazioni che distraggono dal vero problema (per esempio, i +marcatori temporali, la lista dei moduli, la lista dei registri, lo +stato dello stack). + +Quindi, per rendere utile un *backtrace* dovreste eliminare le +informazioni inutili, cosicché ci si possa focalizzare sul +problema. Ecco un esempio di un *backtrace* essenziale:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + .. _it_explicit_in_reply_to: Usare esplicitamente In-Reply-To nell'intestazione diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist index b42220d3d46c..4429447b0965 100644 --- a/Documentation/translations/ja_JP/SubmitChecklist +++ b/Documentation/translations/ja_JP/SubmitChecklist @@ -88,20 +88,18 @@ Linux カーãƒãƒ«ãƒ‘ッãƒæŠ•ç¨¿è€…å‘ã‘ãƒã‚§ãƒƒã‚¯ãƒªã‚¹ãƒˆ 18: æ–°ã—ã„userspaceインタフェースを作æˆã—ãŸå ´åˆã«ã¯ã€Documentation/ABI/ ã« Documentation/ABI/README ã‚’å‚考ã«ã—ã¦å¿…ãšãƒ‰ã‚ãƒ¥ãƒ¡ãƒ³ãƒˆã‚’è¿½åŠ ã—ã¦ãã ã•ã„。 -19: 'make headers_check'を実行ã—ã¦å…¨ãå•é¡ŒãŒãªã„ã“ã¨ã‚’確èªã—ã¦ãã ã•ã„。 - -20: å°‘ãªãã¨ã‚‚slabã‚¢ãƒã‚±ãƒ¼ã‚·ãƒ§ãƒ³ã¨pageã‚¢ãƒã‚±ãƒ¼ã‚·ãƒ§ãƒ³ã«å¤±æ•—ã—ãŸå ´åˆã® +19: å°‘ãªãã¨ã‚‚slabã‚¢ãƒã‚±ãƒ¼ã‚·ãƒ§ãƒ³ã¨pageã‚¢ãƒã‚±ãƒ¼ã‚·ãƒ§ãƒ³ã«å¤±æ•—ã—ãŸå ´åˆã® 挙動ã«ã¤ã„ã¦ã€fault-injectionを利用ã—ã¦ç¢ºèªã—ã¦ãã ã•ã„。 Documentation/fault-injection/ ã‚’å‚ç…§ã—ã¦ãã ã•ã„。 è¿½åŠ ã—ãŸã‚³ãƒ¼ãƒ‰ãŒã‹ãªã‚Šã®é‡ã§ã‚ã£ãŸãªã‚‰ã°ã€ã‚µãƒ–システム特有㮠fault-injectionã‚’è¿½åŠ ã—ãŸã»ã†ãŒè‰¯ã„ã‹ã‚‚ã—ã‚Œã¾ã›ã‚“。 -21: æ–°ãŸã«è¿½åŠ ã—ãŸã‚³ãƒ¼ãƒ‰ã¯ã€`gcc -W'ã§ã‚³ãƒ³ãƒ‘イルã—ã¦ãã ã•ã„。 +20: æ–°ãŸã«è¿½åŠ ã—ãŸã‚³ãƒ¼ãƒ‰ã¯ã€`gcc -W'ã§ã‚³ãƒ³ãƒ‘イルã—ã¦ãã ã•ã„。 ã“ã®ã‚ªãƒ—ションã¯å¤§é‡ã®ä¸è¦ãªãƒ¡ãƒƒã‚»ãƒ¼ã‚¸ã‚’出力ã—ã¾ã™ãŒã€ "warning: comparison between signed and unsigned" ã®ã‚ˆã†ãªãƒ¡ãƒƒã‚»ãƒ¼ã‚¸ã¯ã€ ãƒã‚°ã‚’見ã¤ã‘ã‚‹ã®ã«å½¹ã«ç«‹ã¡ã¾ã™ã€‚ -22: 投稿ã—ãŸãƒ‘ッãƒãŒ -mm パッãƒã‚»ãƒƒãƒˆã«ãƒžãƒ¼ã‚¸ã•ã‚ŒãŸå¾Œã€å…¨ã¦ã®æ—¢å˜ã®ãƒ‘ッãƒã‚„ +21: 投稿ã—ãŸãƒ‘ッãƒãŒ -mm パッãƒã‚»ãƒƒãƒˆã«ãƒžãƒ¼ã‚¸ã•ã‚ŒãŸå¾Œã€å…¨ã¦ã®æ—¢å˜ã®ãƒ‘ッãƒã‚„ VM, VFS ãŠã‚ˆã³ãã®ä»–ã®ã‚µãƒ–システムã«é–¢ã™ã‚‹æ§˜ã€…ãªå¤‰æ›´ã¨ã€ç¾æ™‚点ã§ã‚‚å…±å˜ ã§ãã‚‹ã“ã¨ã‚’確èªã™ã‚‹ãƒ†ã‚¹ãƒˆã‚’è¡Œã£ã¦ãã ã•ã„。 diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index 787f1e85f8a0..a2bdd564c907 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -339,14 +339,8 @@ Andrew Mortonì˜ ê¸€ì´ ìžˆë‹¤. 버그 ë³´ê³ --------- -https://bugzilla.kernel.org 는 리눅스 ì»¤ë„ ê°œë°œìžë“¤ì´ 커ë„ì˜ ë²„ê·¸ë¥¼ 추ì 하는 -ê³³ì´ë‹¤. 사용ìžë“¤ì€ 발견한 ëª¨ë“ ë²„ê·¸ë“¤ì„ ë³´ê³ í•˜ê¸° 위하여 ì´ íˆ´ì„ ì‚¬ìš©í• ê²ƒì„ -권장한다. kernel bugzilla를 사용하는 ìžì„¸í•œ ë°©ë²•ì€ ë‹¤ìŒì„ 참조하ë¼. - - https://bugzilla.kernel.org/page.cgi?id=faq.html - ë©”ì¸ ì»¤ë„ ì†ŒìŠ¤ ë””ë ‰í† ë¦¬ì— ìžˆëŠ” 'Documentation/admin-guide/reporting-issues.rst' -파ì¼ì€ ì»¤ë„ ë²„ê·¸ë¼ê³ ìƒê°ë˜ëŠ” ê²ƒì„ ë³´ê³ í•˜ëŠ” ë°©ë²•ì— ê´€í•œ ì¢‹ì€ í…œí”Œë¦¿ì´ë©° ë¬¸ì œë¥¼ +파ì¼ì€ ì»¤ë„ ë²„ê·¸ë¼ê³ ìƒê°ë˜ëŠ” ê²ƒì„ ì–´ë–»ê²Œ ë³´ê³ í•˜ë©´ ë˜ëŠ”지, ê·¸ë¦¬ê³ ë¬¸ì œë¥¼ 추ì 하기 위해서 ì»¤ë„ ê°œë°œìžë“¤ì´ 필요로 하는 ì •ë³´ê°€ 무엇들ì¸ì§€ë¥¼ ìƒì„¸ížˆ ì„¤ëª…í•˜ê³ ìžˆë‹¤. @@ -362,8 +356,14 @@ https://bugzilla.kernel.org 는 리눅스 ì»¤ë„ ê°œë°œìžë“¤ì´ 커ë„ì˜ ë²„ê· ì 수를 ì–»ì„ ìˆ˜ 있는 가장 ì¢‹ì€ ë°©ë²•ì¤‘ì˜ í•˜ë‚˜ì´ë‹¤. 왜ëƒí•˜ë©´ ë§Žì€ ì‚¬ëžŒë“¤ì€ ë‹¤ë¥¸ ì‚¬ëžŒë“¤ì˜ ë²„ê·¸ë“¤ì„ ìˆ˜ì •í•˜ê¸° 위하여 ì‹œê°„ì„ ë‚비하지 않기 때문ì´ë‹¤. -ì´ë¯¸ ë³´ê³ ëœ ë²„ê·¸ 리í¬íŠ¸ë“¤ì„ ê°€ì§€ê³ ìž‘ì—…í•˜ê¸° 위해서 https://bugzilla.kernel.org -를 참조하ë¼. +ì´ë¯¸ ë³´ê³ ëœ ë²„ê·¸ 리í¬íŠ¸ë“¤ì„ ê°€ì§€ê³ ìž‘ì—…í•˜ê¸° 위해서는 ì—¬ëŸ¬ë¶„ì´ ê´€ì‹¬ìžˆëŠ” +ì„œë¸Œì‹œìŠ¤í…œì„ ì°¾ì•„ë¼. 해당 ì„œë¸Œì‹œìŠ¤í…œì˜ ë²„ê·¸ë“¤ì´ ì–´ë””ë¡œ 리í¬íŠ¸ ë˜ëŠ”지 +MAINTAINERS 파ì¼ì„ ì²´í¬í•˜ë¼; 그건 대부분 ë©”ì¼ë§ 리스트ì´ê³ , ê°€ë”ì€ ë²„ê·¸ 추ì +시스템ì´ë‹¤. ê·¸ ìž¥ì†Œì— ìžˆëŠ” 최근 버그 리í¬íŠ¸ 기ë¡ë“¤ì„ ê²€ìƒ‰í•˜ê³ ì—¬ëŸ¬ë¶„ì´ ë³´ê¸°ì— +ì 합하다 ì‹¶ì€ ê²ƒì„ ë„와ë¼. ì—¬ëŸ¬ë¶„ì€ ë²„ê·¸ 리í¬íŠ¸ë¥¼ 위해 +https://bugzilla.kernel.org 를 ì²´í¬í•˜ê³ ìž í• ìˆ˜ë„ ìžˆë‹¤; ì†Œìˆ˜ì˜ ì»¤ë„ +ì„œë¸Œì‹œìŠ¤í…œë“¤ë§Œì´ ë²„ê·¸ ì‹ ê³ ì™€ 추ì ì„ ìœ„í•´ 해당 ì‹œìŠ¤í…œì„ ì‹¤ì œë¡œ ì‚¬ìš©í•˜ê³ ìžˆì§€ë§Œ, +ì „ì²´ 커ë„ì˜ ë²„ê·¸ë“¤ì´ ê·¸ê³³ì— ì •ë¦¬ëœë‹¤. ë©”ì¼ë§ 리스트들 diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst new file mode 100644 index 000000000000..669a022f6817 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -0,0 +1,347 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/README.rst + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +Linuxå†…æ ¸5.x版本 <http://kernel.org/> +========================================= + +以下是Linux版本5çš„å‘行注记。仔细阅读它们， +å®ƒä»¬ä¼šå‘Šè¯‰ä½ è¿™äº›éƒ½æ˜¯ä»€ä¹ˆï¼Œè§£é‡Šå¦‚ä½•å®‰è£…å†…æ ¸ï¼Œä»¥åŠé‡åˆ°é—®é¢˜æ—¶è¯¥å¦‚何åšã€‚ + +什么是Linux？ +--------------- + + Linux是Unixæ“作系统的克隆版本，由Linus Torvalds在一个æ¾æ•£çš„网络黑客 + （Hackerï¼Œæ— è´¬ä¹‰ï¼‰å›¢é˜Ÿçš„å¸®åŠ©ä¸‹ä»Žå¤´å¼€å§‹ç¼–å†™ã€‚å®ƒæ—¨åœ¨å®žçŽ°å…¼å®¹POSIXå’Œ + å•ä¸€UNIX规范。 + + 它具有在现代æˆç†Ÿçš„Unixä¸åº”当具有的所有功能，包括真æ£çš„多任务处ç†ã€è™šæ‹Ÿå†…å˜ã€ + 共享库ã€æŒ‰éœ€åŠ è½½ã€å…±äº«çš„写时拷è´ï¼ˆCOW）å¯æ‰§è¡Œæ–‡ä»¶ã€æ°å½“的内å˜ç®¡ç†ä»¥åŠåŒ…括 + IPv4å’ŒIPv6在内的å¤åˆç½‘ç»œæ ˆã€‚ + + Linux在GNU通用公共许å¯è¯ï¼Œç‰ˆæœ¬2（GNU GPLv2）下分å‘，详è§éšé™„çš„COPYING文件。 + +å®ƒèƒ½åœ¨ä»€ä¹ˆæ ·çš„ç¡¬ä»¶ä¸Šè¿è¡Œï¼Ÿ +----------------------------- + + 虽然Linux最åˆæ˜¯ä¸º32ä½çš„x86 PC机（386或更高版本）开å‘的，但今天它也能è¿è¡Œåœ¨ + （至少）Compaq Alpha AXPã€Sun SPARC与UltraSPARCã€Motorola 68000ã€PowerPC〠+ PowerPC64ã€ARMã€Hitachi SuperHã€Cellã€IBM S/390ã€MIPSã€HP PA-RISCã€Intel + IA-64ã€DEC VAXã€AMD x86-64 Xtensaå’ŒARC架构上。 + + Linux很容易移æ¤åˆ°å¤§å¤šæ•°é€šç”¨çš„32ä½æˆ–64ä½ä½“系架构，åªè¦å®ƒä»¬æœ‰ä¸€ä¸ªåˆ†é¡µå†…å˜ç®¡ç† + å•å…ƒï¼ˆPMMU）和一个移æ¤çš„GNU C编译器（gccï¼›GNU Compiler Collection，GCC的一 + 部分）。Linux也被移æ¤åˆ°è®¸å¤šæ²¡æœ‰PMMU的体系架构ä¸ï¼Œå°½ç®¡åŠŸèƒ½æ˜¾ç„¶å—到了一定的 + é™åˆ¶ã€‚ + Linux也被移æ¤åˆ°äº†å…¶è‡ªå·±ä¸Šã€‚现在å¯ä»¥å°†å†…æ ¸ä½œä¸ºç”¨æˆ·ç©ºé—´åº”ç”¨ç¨‹åºè¿è¡Œâ€”—这被 + 称为用户模å¼Linux（UML）。 + +文档 +----- +å› ç‰¹ç½‘ä¸Šå’Œä¹¦ç±ä¸Šéƒ½æœ‰å¤§é‡çš„电å文档，既有Linux专属文档，也有与一般UNIX问题相关 +的文档。我建议在任何Linux FTP站点上查找LDP（Linux文档项目）书ç±çš„文档å目录。 +本自述文件并ä¸æ˜¯å…³äºŽç³»ç»Ÿçš„文档：有更好的å¯ç”¨èµ„æºã€‚ + + - å› ç‰¹ç½‘ä¸Šå’Œä¹¦ç±ä¸Šéƒ½æœ‰å¤§é‡çš„（电å）文档，既有Linux专属文档，也有与普通 + UNIX问题相关的文档。我建议在任何有LDP（Linux文档项目）书ç±çš„Linux FTP + 站点上查找文档å目录。本自述文件并ä¸æ˜¯å…³äºŽç³»ç»Ÿçš„文档：有更好的å¯ç”¨èµ„æºã€‚ + + - 文档/å目录ä¸æœ‰å„ç§è‡ªè¿°æ–‡ä»¶ï¼šä¾‹å¦‚，这些文件通常包å«ä¸€äº›ç‰¹å®šé©±åŠ¨ç¨‹åºçš„ + å†…æ ¸å®‰è£…è¯´æ˜Žã€‚è¯·é˜…è¯» + :ref:`Documentation/process/changes.rst <changes>` 文件，它包å«äº†å‡çº§å†…æ ¸ + å¯èƒ½ä¼šå¯¼è‡´çš„问题的相关信æ¯ã€‚ + +å®‰è£…å†…æ ¸æºä»£ç +--------------- + + - 如果您è¦å®‰è£…完整的æºä»£ç ï¼Œè¯·æŠŠå†…æ ¸tar档案包放在您有æƒé™çš„目录ä¸ï¼ˆä¾‹å¦‚您 + 的主目录）并将其解包:: + + xz -cd linux-5.x.tar.xz | tar xvf - + + 将“Xâ€æ›¿æ¢æˆæœ€æ–°å†…æ ¸çš„ç‰ˆæœ¬å·ã€‚ + + ã€ä¸è¦ã€‘使用 /usr/src/linux 目录ï¼è¿™é‡Œæœ‰ä¸€ç»„åº“å¤´æ–‡ä»¶ä½¿ç”¨çš„å†…æ ¸å¤´æ–‡ä»¶ + （通常是ä¸å®Œæ•´çš„）。它们应该与库匹é…，而ä¸æ˜¯è¢«å†…æ ¸çš„å˜åŒ–æžå¾—一团糟。 + + - 您还å¯ä»¥é€šè¿‡æ‰“è¡¥ä¸åœ¨5.x版本之间å‡çº§ã€‚è¡¥ä¸ä»¥xzæ ¼å¼åˆ†å‘。è¦é€šè¿‡æ‰“è¡¥ä¸è¿›è¡Œ + 安装，请获å–所有较新的补ä¸æ–‡ä»¶ï¼Œè¿›å…¥å†…æ ¸æºä»£ç （linux-5.x）的目录并 + 执行:: + + xz -cd ../patch-5.x.xz | patch -p1 + + 请ã€æŒ‰é¡ºåºã€‘替æ¢æ‰€æœ‰å¤§äºŽå½“å‰æºä»£ç æ ‘ç‰ˆæœ¬çš„â€œxâ€ï¼Œè¿™æ ·å°±å¯ä»¥äº†ã€‚您å¯èƒ½æƒ³è¦ + åˆ é™¤å¤‡ä»½æ–‡ä»¶ï¼ˆæ–‡ä»¶å类似xxx~ 或 xxx.orig)，并确ä¿æ²¡æœ‰å¤±è´¥çš„è¡¥ä¸ï¼ˆæ–‡ä»¶å + 类似xxx# 或 xxx.rej）。如果有，ä¸æ˜¯ä½ 就是我犯了错误。 + + 与5.xå†…æ ¸çš„è¡¥ä¸ä¸åŒï¼Œ5.x.yå†…æ ¸ï¼ˆä¹Ÿç§°ä¸ºç¨³å®šç‰ˆå†…æ ¸ï¼‰çš„è¡¥ä¸ä¸æ˜¯å¢žé‡çš„，而是 + 直接应用于基本的5.xå†…æ ¸ã€‚ä¾‹å¦‚ï¼Œå¦‚æžœæ‚¨çš„åŸºæœ¬å†…æ ¸æ˜¯5.0，并且希望应用5.0.3 + è¡¥ä¸ï¼Œåˆ™ä¸åº”先应用5.0.1å’Œ5.0.2çš„è¡¥ä¸ã€‚类似地，如果您è¿è¡Œçš„是5.0.2å†…æ ¸ï¼Œ + 并且希望跳转到5.0.3，那么在应用5.0.3è¡¥ä¸ä¹‹å‰ï¼Œå¿…须首先撤销5.0.2è¡¥ä¸ + （å³patch -R）。更多关于这方é¢çš„内容，请阅读 + :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 + + 或者，脚本 patch-kernel å¯ä»¥ç”¨æ¥è‡ªåŠ¨åŒ–这个过程。它能确定当å‰å†…æ ¸ç‰ˆæœ¬å¹¶ + 应用找到的所有补ä¸:: + + linux/scripts/patch-kernel linux + + 上é¢å‘½ä»¤ä¸çš„第一个å‚æ•°æ˜¯å†…æ ¸æºä»£ç çš„ä½ç½®ã€‚è¡¥ä¸æ˜¯åœ¨å½“å‰ç›®å½•åº”用的，但是 + å¯ä»¥å°†å¦ä¸€ä¸ªç›®å½•æŒ‡å®šä¸ºç¬¬äºŒä¸ªå‚数。 + + - ç¡®ä¿æ²¡æœ‰è¿‡æ—¶çš„ .o 文件和ä¾èµ–项:: + + cd linux + make mrproper + + 现在您应该已ç»æ£ç¡®å®‰è£…了æºä»£ç 。 + +软件è¦æ±‚ +--------- + + 编译和è¿è¡Œ5.xå†…æ ¸éœ€è¦å„ç§è½¯ä»¶åŒ…的最新版本。请å‚考 + :ref:`Documentation/process/changes.rst <changes>` + æ¥äº†è§£æœ€ä½Žç‰ˆæœ¬è¦æ±‚以åŠå¦‚何å‡çº§è½¯ä»¶åŒ…。请注æ„，使用过旧版本的这些包å¯èƒ½ä¼š + å¯¼è‡´å¾ˆéš¾è¿½è¸ªçš„é—´æŽ¥é”™è¯¯ï¼Œå› æ¤ä¸è¦ä»¥ä¸ºåœ¨ç”Ÿæˆæˆ–æ“作过程ä¸å‡ºçŽ°æ˜Žæ˜¾é—®é¢˜æ—¶å¯ä»¥ + åªæ›´æ–°åŒ…。 + +ä¸ºå†…æ ¸å»ºç«‹ç›®å½• +--------------- + + ç¼–è¯‘å†…æ ¸æ—¶ï¼Œé»˜è®¤æƒ…å†µä¸‹æ‰€æœ‰è¾“å‡ºæ–‡ä»¶éƒ½å°†ä¸Žå†…æ ¸æºä»£ç 放在一起。使用 + ``make O=output/dir`` 选项å¯ä»¥ä¸ºè¾“出文件（包括 .config）指定备用ä½ç½®ã€‚ + 例如:: + + kernel source code: /usr/src/linux-5.x + build directory: /home/name/build/kernel + + è¦é…ç½®å’Œæž„å»ºå†…æ ¸ï¼Œè¯·ä½¿ç”¨:: + + cd /usr/src/linux-5.x + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + 请注æ„：如果使用了 ``O=output/dir`` 选项，那么它必须用于make的所有调用。 + +é…ç½®å†…æ ¸ +--------- + + å³ä½¿åªå‡çº§ä¸€ä¸ªå°ç‰ˆæœ¬ï¼Œä¹Ÿä¸è¦è·³è¿‡æ¤æ¥éª¤ã€‚æ¯ä¸ªç‰ˆæœ¬ä¸éƒ½ä¼šæ·»åŠ æ–°çš„é…置选项， + 如果é…ç½®æ–‡ä»¶æ²¡æœ‰æŒ‰é¢„å®šè®¾ç½®ï¼Œå°±ä¼šå‡ºçŽ°å¥‡æ€ªçš„é—®é¢˜ã€‚å¦‚æžœæ‚¨æƒ³ä»¥æœ€å°‘çš„å·¥ä½œé‡ + 将现有é…ç½®å‡çº§åˆ°æ–°ç‰ˆæœ¬ï¼Œè¯·ä½¿ç”¨ ``makeoldconfig`` ，它åªä¼šè¯¢é—®æ‚¨æ–°é…ç½® + 选项的ç”案。 + + - 其他é…置命令包括:: + + "make config" 纯文本界é¢ã€‚ + + "make menuconfig" 基于文本的彩色èœå•ã€é€‰é¡¹åˆ—表和对è¯æ¡†ã€‚ + + "make nconfig" 增强的基于文本的彩色èœå•ã€‚ + + "make xconfig" 基于Qtçš„é…置工具。 + + "make gconfig" 基于GTK+çš„é…置工具。 + + "make oldconfig" 基于现有的 ./.config 文件选择所有选项，并询问 + æ–°é…置选项。 + + "make olddefconfig" + 类似上一个，但ä¸è¯¢é—®ç›´æŽ¥å°†æ–°é€‰é¡¹è®¾ç½®ä¸ºé»˜è®¤å€¼ã€‚ + + "make defconfig" æ ¹æ®ä½“系架构，使用arch/$arch/defconfig或 + arch/$arch/configs/${PLATFORM}_defconfigä¸çš„ + 默认选项值创建./.config文件。 + + "make ${PLATFORM}_defconfig" + 使用arch/$arch/configs/${PLATFORM}_defconfigä¸ + 的默认选项值创建一个./.config文件。 + 用“makehelpâ€æ¥èŽ·å–您体系架构ä¸æ‰€æœ‰å¯ç”¨å¹³å°çš„列表。 + + "make allyesconfig" + 通过尽å¯èƒ½å°†é€‰é¡¹å€¼è®¾ç½®ä¸ºâ€œyâ€ï¼Œåˆ›å»ºä¸€ä¸ª + ./.config文件。 + + "make allmodconfig" + 通过尽å¯èƒ½å°†é€‰é¡¹å€¼è®¾ç½®ä¸ºâ€œmâ€ï¼Œåˆ›å»ºä¸€ä¸ª + ./.config文件。 + + "make allnoconfig" 通过尽å¯èƒ½å°†é€‰é¡¹å€¼è®¾ç½®ä¸ºâ€œnâ€ï¼Œåˆ›å»ºä¸€ä¸ª + ./.config文件。 + + "make randconfig" 通过éšæœºè®¾ç½®é€‰é¡¹å€¼æ¥åˆ›å»º./.config文件。 + + "make localmodconfig" 基于当å‰é…ç½®å’ŒåŠ è½½çš„æ¨¡å—（lsmod）创建é…置。ç¦ç”¨ + å·²åŠ è½½çš„æ¨¡å—ä¸éœ€è¦çš„任何模å—选项。 + + è¦ä¸ºå¦ä¸€å°è®¡ç®—机创建localmodconfig，请将该计算机 + çš„lsmodå˜å‚¨åˆ°ä¸€ä¸ªæ–‡ä»¶ä¸ï¼Œå¹¶å°†å…¶ä½œä¸ºlsmodå‚æ•°ä¼ å…¥ã€‚ + + æ¤å¤–，通过在å‚æ•°LMC_KEEPä¸æŒ‡å®šæ¨¡å—的路径，å¯ä»¥å°† + 模å—ä¿ç•™åœ¨æŸäº›æ–‡ä»¶å¤¹æˆ–kconfig文件ä¸ã€‚ + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod \ + LMC_KEEP="drivers/usb:drivers/gpu:fs" \ + localmodconfig + + 上述方法在交å‰ç¼–译时也适用。 + + "make localyesconfig" 与localmodconfig类似，åªæ˜¯å®ƒä¼šå°†æ‰€æœ‰æ¨¡å—é€‰é¡¹è½¬æ¢ + 为内置（=yï¼‰ã€‚ä½ å¯ä»¥åŒæ—¶é€šè¿‡LMC_KEEPä¿ç•™æ¨¡å—。 + + "make kvmconfig" 为kvmå®¢ä½“å†…æ ¸æ”¯æŒå¯ç”¨å…¶ä»–选项。 + + "make xenconfig" 为xen dom0å®¢ä½“å†…æ ¸æ”¯æŒå¯ç”¨å…¶ä»–选项。 + + "make tinyconfig" é…置尽å¯èƒ½å°çš„å†…æ ¸ã€‚ + + 更多关于使用Linuxå†…æ ¸é…置工具的信æ¯ï¼Œè§æ–‡æ¡£ + Documentation/kbuild/kconfig.rst。 + + - ``make config`` 注æ„事项: + + - 包å«ä¸å¿…è¦çš„驱动程åºä¼šä½¿å†…æ ¸å˜å¤§ï¼Œå¹¶ä¸”在æŸäº›æƒ…况下会导致问题： + 探测ä¸å˜åœ¨çš„控制器å¡å¯èƒ½ä¼šæ··æ·†å…¶ä»–控制器。 + + - 如果å˜åœ¨å处ç†å™¨ï¼Œåˆ™ç¼–译了数å¦ä»¿çœŸçš„å†…æ ¸ä»å°†ä½¿ç”¨å处ç†å™¨ï¼šåœ¨ + è¿™ç§æƒ…况下，数å¦ä»¿çœŸæ°¸è¿œä¸ä¼šè¢«ä½¿ç”¨ã€‚å†…æ ¸ä¼šç¨å¾®å¤§ä¸€ç‚¹ï¼Œä½†ä¸ç®¡ + 是å¦æœ‰æ•°å¦å处ç†å™¨ï¼Œéƒ½å¯ä»¥åœ¨ä¸åŒçš„机器上工作。 + + - “kernel hackingâ€é…ç½®ç»†èŠ‚é€šå¸¸ä¼šå¯¼è‡´æ›´å¤§æˆ–æ›´æ…¢çš„å†…æ ¸ï¼ˆæˆ–ä¸¤è€… + 兼而有之），甚至å¯ä»¥é€šè¿‡é…置一些例程æ¥ä¸»åŠ¨å°è¯•ç ´åå代ç 以å‘现 + å†…æ ¸é—®é¢˜ï¼Œä»Žè€Œé™ä½Žå†…æ ¸çš„ç¨³å®šæ€§ï¼ˆkmalloc()ï¼‰ã€‚å› æ¤ï¼Œæ‚¨å¯èƒ½åº”该 + ç”¨äºŽç ”ç©¶â€œå¼€å‘â€ã€â€œå®žéªŒâ€æˆ–“调试â€ç‰¹æ€§ç›¸å…³é—®é¢˜ã€‚ + +ç¼–è¯‘å†…æ ¸ +--------- + + - ç¡®ä¿æ‚¨è‡³å°‘有gcc 4.9å¯ç”¨ã€‚ + 有关更多信æ¯ï¼Œè¯·å‚阅 :ref:`Documentation/process/changes.rst <changes>` 。 + + 请注æ„，您ä»ç„¶å¯ä»¥ä½¿ç”¨æ¤å†…æ ¸è¿è¡Œa.out用户程åºã€‚ + + - 执行 ``make`` æ¥åˆ›å»ºåŽ‹ç¼©å†…æ ¸æ˜ åƒã€‚如果您安装了lilo以适é…å†…æ ¸makefile， + 那么也å¯ä»¥è¿›è¡Œ ``makeinstall`` ，但是您å¯èƒ½éœ€è¦å…ˆæ£€æŸ¥ç‰¹å®šçš„lilo设置。 + + 实际安装必须以root身份执行，但任何æ£å¸¸æž„建都ä¸éœ€è¦ã€‚ + æ— é¡»å¾’ç„¶ä½¿ç”¨root身份。 + + - å¦‚æžœæ‚¨å°†å†…æ ¸çš„ä»»ä½•éƒ¨åˆ†é…置为模å—，那么还必须执行 ``make modules_install`` 。 + + - è¯¦ç»†çš„å†…æ ¸ç¼–è¯‘/生æˆè¾“出： + + é€šå¸¸ï¼Œå†…æ ¸æž„å»ºç³»ç»Ÿåœ¨ç›¸å½“å®‰é™çš„模å¼ä¸‹è¿è¡Œï¼ˆä½†ä¸æ˜¯å®Œå…¨å®‰é™ï¼‰ã€‚但是有时您或 + å…¶ä»–å†…æ ¸å¼€å‘人员需è¦çœ‹åˆ°ç¼–译ã€é“¾æŽ¥æˆ–其他命令的执行过程。为æ¤ï¼Œå¯ä½¿ç”¨ + “verbose（详细）â€æž„建模å¼ã€‚ + å‘ ``make`` å‘½ä»¤ä¼ é€’ ``V=1`` æ¥å®žçŽ°ï¼Œä¾‹å¦‚:: + + make V=1 all + + å¦‚éœ€æž„å»ºç³»ç»Ÿä¹Ÿç»™å‡ºå†…ä¸ªç›®æ ‡é‡å»ºçš„æ„¿æ„，请使用 ``V=2`` 。默认为 ``V=0`` 。 + + - å‡†å¤‡ä¸€ä¸ªå¤‡ä»½å†…æ ¸ä»¥é˜²å‡ºé”™ã€‚å¯¹äºŽå¼€å‘版本尤其如æ¤ï¼Œå› 为æ¯ä¸ªæ–°ç‰ˆæœ¬éƒ½åŒ…å« + 尚未调试的新代ç 。也è¦ç¡®ä¿ä¿ç•™ä¸Žè¯¥å†…æ ¸å¯¹åº”çš„æ¨¡å—的备份。如果è¦å®‰è£… + ä¸Žå·¥ä½œå†…æ ¸ç‰ˆæœ¬å·ç›¸åŒçš„æ–°å†…æ ¸ï¼Œè¯·åœ¨è¿›è¡Œ ``make modules_install`` 安装 + 之å‰å¤‡ä»½modules目录。 + + 或者，在编译之å‰ï¼Œä½¿ç”¨å†…æ ¸é…置选项“LOCALVERSIONâ€å‘å¸¸è§„å†…æ ¸ç‰ˆæœ¬é™„åŠ + 一个唯一的åŽç¼€ã€‚LOCALVERSIONå¯ä»¥åœ¨â€œGeneral Setupâ€èœå•ä¸è®¾ç½®ã€‚ + + - ä¸ºäº†å¼•å¯¼æ–°å†…æ ¸ï¼Œæ‚¨éœ€è¦å°†å†…æ ¸æ˜ åƒï¼ˆä¾‹å¦‚编译åŽçš„ + .../linux/arch/x86/boot/bzImage）å¤åˆ¶åˆ°å¸¸è§„å¯å¼•å¯¼å†…æ ¸çš„ä½ç½®ã€‚ + + - ä¸å†æ”¯æŒåœ¨æ²¡æœ‰LILOç‰å¯åŠ¨è£…载程åºå¸®åŠ©çš„æƒ…å†µä¸‹ç›´æŽ¥ä»Žè½¯ç›˜å¼•å¯¼å†…æ ¸ã€‚ + + 如果从硬盘引导Linux，很å¯èƒ½ä½¿ç”¨LILO，它使用/etc/lilo.confæ–‡ä»¶ä¸ + æŒ‡å®šçš„å†…æ ¸æ˜ åƒæ–‡ä»¶ã€‚å†…æ ¸æ˜ åƒæ–‡ä»¶é€šå¸¸æ˜¯/vmlinuzã€/boot/vmlinuz〠+ /bzImage或/boot/bzImageã€‚ä½¿ç”¨æ–°å†…æ ¸å‰ï¼Œè¯·ä¿å˜æ—§æ˜ åƒçš„副本，并å¤åˆ¶ + æ–°æ˜ åƒè¦†ç›–æ—§æ˜ åƒã€‚然åŽæ‚¨ã€å¿…é¡»é‡æ–°è¿è¡ŒLILO】æ¥æ›´æ–°åŠ è½½æ˜ å°„ï¼å¦åˆ™ï¼Œ + å°†æ— æ³•å¯åŠ¨æ–°çš„å†…æ ¸æ˜ åƒã€‚ + + é‡æ–°å®‰è£…LILO通常需è¦è¿è¡Œ/sbin/LILO。您å¯èƒ½å¸Œæœ›ç¼–辑/etc/lilo.conf + æ–‡ä»¶ä¸ºæ—§å†…æ ¸æ˜ åƒæŒ‡å®šä¸€ä¸ªæ¡ç›®ï¼ˆä¾‹å¦‚/vmlinux.old)防æ¢æ–°çš„ä¸èƒ½æ£å¸¸ + 工作。有关更多信æ¯ï¼Œè¯·å‚阅LILO文档。 + + é‡æ–°å®‰è£…LILO之åŽï¼Œæ‚¨åº”该就已ç»å‡†å¤‡å¥½äº†ã€‚å…³é—系统，é‡æ–°å¯åŠ¨ï¼Œå°½æƒ… + 享å—å§ï¼ + + 如果需è¦æ›´æ”¹å†…æ ¸æ˜ åƒä¸çš„é»˜è®¤æ ¹è®¾å¤‡ã€è§†é¢‘模å¼ç‰ï¼Œè¯·åœ¨é€‚当的地方使用 + å¯åŠ¨è£…载程åºçš„å¼•å¯¼é€‰é¡¹ã€‚æ— éœ€é‡æ–°ç¼–è¯‘å†…æ ¸å³å¯æ›´æ”¹è¿™äº›å‚数。 + + - ä½¿ç”¨æ–°å†…æ ¸é‡æ–°å¯åŠ¨å¹¶äº«å—它å§ã€‚ + +è‹¥é‡åˆ°é—®é¢˜ +----------- + + - 如果您å‘现了一些å¯èƒ½ç”±äºŽå†…æ ¸ç¼ºé™·æ‰€å¯¼è‡´çš„é—®é¢˜ï¼Œè¯·æ£€æŸ¥MAINTAINERS（维护者） + 文件看看是å¦æœ‰äººä¸Žä»¤æ‚¨é‡åˆ°éº»çƒ¦çš„å†…æ ¸éƒ¨åˆ†ç›¸å…³ã€‚å¦‚æžœæ— äººåœ¨æ¤åˆ—出，那么第二 + 个最好的方案就是把它们å‘给我（torvalds@linux-foundation.org），也å¯èƒ½å‘é€ + 到任何其他相关的邮件列表或新闻组。 + + - 在所有的缺陷报告ä¸ï¼Œã€è¯·ã€‘å‘Šè¯‰æˆ‘ä»¬æ‚¨åœ¨è¯´ä»€ä¹ˆå†…æ ¸ï¼Œå¦‚ä½•å¤çŽ°é—®é¢˜ï¼Œä»¥åŠæ‚¨çš„ + 设置是什么的（使用您的常识）。如果问题是新的，请告诉我；如果问题是旧的， + 请å°è¯•å‘Šè¯‰æˆ‘您什么时候首次注æ„到它。 + + - 如果缺陷导致如下消æ¯:: + + unable to handle kernel paging request at address C0000010 + Oops: 0002 + EIP: 0010:XXXXXXXX + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx + ds: xxxx es: xxxx fs: xxxx gs: xxxx + Pid: xx, process nr: xx + xx xx xx xx xx xx xx xx xx xx + + æˆ–è€…ç±»ä¼¼çš„å†…æ ¸è°ƒè¯•ä¿¡æ¯æ˜¾ç¤ºåœ¨å±å¹•ä¸Šæˆ–在系统日志里，请ã€å¦‚实】å¤åˆ¶å®ƒã€‚ + å¯èƒ½å¯¹ä½ æ¥è¯´è½¬å‚¨ï¼ˆdump）看起æ¥ä¸å¯ç†è§£ï¼Œä½†å®ƒç¡®å®žåŒ…å«å¯èƒ½æœ‰åŠ©äºŽè°ƒè¯•é—®é¢˜çš„ + ä¿¡æ¯ã€‚转储上方的文本也很é‡è¦ï¼šå®ƒè¯´æ˜Žäº†å†…æ ¸è½¬å‚¨ä»£ç çš„åŽŸå› ï¼ˆåœ¨ä¸Šé¢çš„示例ä¸ï¼Œ + æ˜¯ç”±äºŽå†…æ ¸æŒ‡é’ˆé”™è¯¯ï¼‰ã€‚æ›´å¤šå…³äºŽå¦‚ä½•ç†è§£è½¬å‚¨çš„ä¿¡æ¯ï¼Œè¯·å‚è§ + Documentation/admin-guide/bug-hunting.rst。 + + - 如果使用 CONFIG_KALLSYMS ç¼–è¯‘å†…æ ¸ï¼Œåˆ™å¯ä»¥æŒ‰åŽŸæ ·å‘é€è½¬å‚¨ï¼Œå¦åˆ™å¿…须使用 + ``ksymoops`` 程åºæ¥ç†è§£è½¬å‚¨ï¼ˆä½†é€šå¸¸é¦–选使用CONFIG_KALLSYMS编译）。 + æ¤å®žç”¨ç¨‹åºå¯ä»Ž + https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下载。 + 或者，您å¯ä»¥æ‰‹åŠ¨æ‰§è¡Œè½¬å‚¨æŸ¥æ‰¾ï¼š + + - 在调试åƒä¸Šé¢è¿™æ ·çš„转储时，如果您å¯ä»¥æŸ¥æ‰¾EIP值的å«ä¹‰ï¼Œè¿™å°†éžå¸¸æœ‰å¸®åŠ©ã€‚ + åå…进制值本身对我或其他任何人都没有太大帮助：它会å–å†³äºŽç‰¹å®šçš„å†…æ ¸è®¾ç½®ã€‚ + 您应该åšçš„是从EIP行获å–åå…进制值（忽略 ``0010:`` ），然åŽåœ¨å†…æ ¸åå—列表 + ä¸æŸ¥æ‰¾å®ƒï¼Œä»¥æŸ¥çœ‹å“ªä¸ªå†…æ ¸å‡½æ•°åŒ…å«æœ‰é—®é¢˜çš„地å€ã€‚ + + è¦æ‰¾åˆ°å†…æ ¸å‡½æ•°å，您需è¦æ‰¾åˆ°ä¸Žæ˜¾ç¤ºç—‡çŠ¶çš„å†…æ ¸ç›¸å…³è”的系统二进制文件。就是 + 文件“linux/vmlinuxâ€ã€‚è¦æå–åå—åˆ—è¡¨å¹¶å°†å…¶ä¸Žå†…æ ¸å´©æºƒä¸çš„EIP进行匹é…， + 请执行:: + + nm vmlinux | sort | less + + 这将为您æ供一个按å‡åºæŽ’åºçš„å†…æ ¸åœ°å€åˆ—表，从ä¸å¾ˆå®¹æ˜“找到包å«æœ‰é—®é¢˜çš„åœ°å€ + 的函数。请注æ„ï¼Œå†…æ ¸è°ƒè¯•æ¶ˆæ¯æ供的地å€ä¸ä¸€å®šä¸Žå‡½æ•°åœ°å€å®Œå…¨åŒ¹é…（事实上， + 这是ä¸å¯èƒ½çš„ï¼‰ï¼Œå› æ¤æ‚¨ä¸èƒ½åªâ€œgrepâ€åˆ—表：ä¸è¿‡åˆ—表将为您æä¾›æ¯ä¸ªå†…æ ¸å‡½æ•° + çš„èµ·ç‚¹ï¼Œå› æ¤é€šè¿‡æŸ¥æ‰¾èµ·å§‹åœ°å€ä½ŽäºŽä½ æ£åœ¨æœç´¢çš„地å€ï¼Œä½†åŽä¸€ä¸ªå‡½æ•°çš„高于的 + å‡½æ•°ï¼Œä½ ä¼šæ‰¾åˆ°æ‚¨æƒ³è¦çš„。实际上，在您的问题报告ä¸åŠ 入一些“上下文â€å¯èƒ½æ˜¯ + 一个好主æ„ï¼Œç»™å‡ºç›¸å…³çš„ä¸Šä¸‹å‡ è¡Œã€‚ + + 如果您由于æŸäº›åŽŸå› æ— æ³•å®Œæˆä¸Šè¿°æ“ä½œï¼ˆå¦‚æ‚¨ä½¿ç”¨é¢„ç¼–è¯‘çš„å†…æ ¸æ˜ åƒæˆ–ç±»ä¼¼çš„æ˜ åƒï¼‰ï¼Œ + 请尽å¯èƒ½å¤šåœ°å‘Šè¯‰æˆ‘您的相关设置信æ¯ï¼Œè¿™ä¼šæœ‰æ‰€å¸®åŠ©ã€‚有关详细信æ¯è¯·é˜…读 + ‘Documentation/admin-guide/reporting-issues.rst’。 + + - 或者，您å¯ä»¥åœ¨æ£åœ¨è¿è¡Œçš„å†…æ ¸ä¸Šä½¿ç”¨gdb（åªè¯»çš„ï¼›å³ä¸èƒ½æ›´æ”¹å€¼æˆ–设置æ–点）。 + 为æ¤ï¼Œè¯·é¦–先使用-gç¼–è¯‘å†…æ ¸ï¼›é€‚å½“åœ°ç¼–è¾‘arch/x86/Makefile，然åŽæ‰§è¡Œ ``make + clean`` 。您还需è¦å¯ç”¨CONFIG_PROC_FS（通过 ``make config`` ）。 + + ä½¿ç”¨æ–°å†…æ ¸é‡æ–°å¯åŠ¨åŽï¼Œæ‰§è¡Œ ``gdb vmlinux /proc/kcore`` 。现在å¯ä»¥ä½¿ç”¨æ‰€æœ‰ + 普通的gdb命令。查找系统崩溃点的命令是 ``l *0xXXXXXXXX`` （将xxx替æ¢ä¸ºEIP + 值）。 + + 用gdbæ— æ³•è°ƒè¯•ä¸€ä¸ªå½“å‰æœªè¿è¡Œçš„å†…æ ¸æ˜¯ç”±äºŽgdbï¼ˆé”™è¯¯åœ°ï¼‰å¿½ç•¥äº†ç¼–è¯‘å†…æ ¸çš„èµ·å§‹ + å移é‡ã€‚ diff --git a/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst new file mode 100644 index 000000000000..662eb5b46e84 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst @@ -0,0 +1,81 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-bisect` + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +二分（bisect）缺陷 ++++++++++++++++++++ + +（英文版）最åŽæ›´æ–°ï¼š2016å¹´10月28æ—¥ + +引言 +===== + +始终å°è¯•ç”±æ¥è‡ªkernel.orgçš„æºä»£ç æž„å»ºçš„æœ€æ–°å†…æ ¸ã€‚å¦‚æžœæ‚¨æ²¡æœ‰ä¿¡å¿ƒè¿™æ ·åšï¼Œè¯·å°† +错误报告给您的å‘行版供应商，而ä¸æ˜¯å†…æ ¸å¼€å‘人员。 + +找到缺陷（bug）并ä¸æ€»æ˜¯é‚£ä¹ˆå®¹æ˜“，ä¸è¿‡ä»ç„¶å¾—åŽ»æ‰¾ã€‚å¦‚æžœä½ æ‰¾ä¸åˆ°å®ƒï¼Œä¸è¦æ”¾å¼ƒã€‚ +å°½å¯èƒ½å¤šçš„å‘相关维护人员报告您å‘现的信æ¯ã€‚请å‚阅MAINTAINERS文件以了解您所 +关注的å系统的维护人员。 + +在æ交错误报告之å‰ï¼Œè¯·é˜…读“Documentation/admin-guide/reporting-issues.rstâ€ã€‚ + +设备未出现（Devices not appearing） +==================================== + +这通常是由udev/systemdå¼•èµ·çš„ã€‚åœ¨å°†å…¶å½’å’ŽäºŽå†…æ ¸ä¹‹å‰å…ˆæ£€æŸ¥ä¸€ä¸‹ã€‚ + +æŸ¥æ‰¾å¯¼è‡´ç¼ºé™·çš„è¡¥ä¸ +=================== + +使用 ``git`` æ供的工具å¯ä»¥å¾ˆå®¹æ˜“地找到缺陷，åªè¦ç¼ºé™·æ˜¯å¯å¤çŽ°çš„。 + +æ“作æ¥éª¤ï¼š + +- 从gitæºä»£ç æž„å»ºå†…æ ¸ +- 以æ¤å¼€å§‹äºŒåˆ† [#f1]_:: + + $ git bisect start + +- æ ‡è®°æŸåçš„å˜æ›´é›†:: + + $ git bisect bad [commit] + +- æ ‡è®°æ£å¸¸å·¥ä½œçš„å˜æ›´é›†:: + + $ git bisect good [commit] + +- é‡æ–°æž„å»ºå†…æ ¸å¹¶æµ‹è¯• +- 使用以下任一与git bisect进行交互:: + + $ git bisect good + + 或:: + + $ git bisect bad + + è¿™å–决于您测试的å˜æ›´é›†ä¸Šæ˜¯å¦æœ‰ç¼ºé™· +- 在一些交互之åŽï¼Œgit bisect将给出å¯èƒ½å¯¼è‡´ç¼ºé™·çš„å˜æ›´é›†ã€‚ + +- 例如，如果您知é“当å‰ç‰ˆæœ¬æœ‰é—®é¢˜ï¼Œè€Œ4.8版本是æ£å¸¸çš„，则å¯ä»¥æ‰§è¡Œä»¥ä¸‹æ“作:: + + $ git bisect start + $ git bisect bad # Current version is bad + $ git bisect good v4.8 + + +.. [#f1] 您å¯ä»¥ï¼ˆå¯é€‰åœ°ï¼‰åœ¨å¼€å§‹git bisect的时候æä¾›good或badå‚æ•° + ``git bisect start [BAD] [GOOD]`` + +如需进一æ¥å‚考，请阅读： + +- ``git-bisect`` 的手册页 +- `Fighting regressions with git bisect（用git bisect解决回归） + <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_ +- `Fully automated bisecting with "git bisect run"（使用git bisect run + æ¥å…¨è‡ªåŠ¨äºŒåˆ†ï¼‰ <https://lwn.net/Articles/317154>`_ +- `Using Git bisect to figure out when brokenness was introduced + （使用Git二分æ¥æ‰¾å‡ºä½•æ—¶å¼•å…¥äº†é”™è¯¯ï¼‰ <http://webchick.net/node/99>`_ diff --git a/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst new file mode 100644 index 000000000000..decb9b26d2f1 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst @@ -0,0 +1,340 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-hunting` + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +追踪缺陷 +========= + +å†…æ ¸é”™è¯¯æŠ¥å‘Šé€šå¸¸é™„å¸¦å¦‚ä¸‹å †æ ˆè½¬å‚¨:: + + ------------[ cut here ]------------ + WARNING: CPU: 1 PID: 28102 at kernel/module.c:1108 module_put+0x57/0x70 + Modules linked in: dvb_usb_gp8psk(-) dvb_usb dvb_core nvidia_drm(PO) nvidia_modeset(PO) snd_hda_codec_hdmi snd_hda_intel snd_hda_codec snd_hwdep snd_hda_core snd_pcm snd_timer snd soundcore nvidia(PO) [last unloaded: rc_core] + CPU: 1 PID: 28102 Comm: rmmod Tainted: P WC O 4.8.4-build.1 #1 + Hardware name: MSI MS-7309/MS-7309, BIOS V1.12 02/23/2009 + 00000000 c12ba080 00000000 00000000 c103ed6a c1616014 00000001 00006dc6 + c1615862 00000454 c109e8a7 c109e8a7 00000009 ffffffff 00000000 f13f6a10 + f5f5a600 c103ee33 00000009 00000000 00000000 c109e8a7 f80ca4d0 c109f617 + Call Trace: + [<c12ba080>] ? dump_stack+0x44/0x64 + [<c103ed6a>] ? __warn+0xfa/0x120 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c103ee33>] ? warn_slowpath_null+0x23/0x30 + [<c109e8a7>] ? module_put+0x57/0x70 + [<f80ca4d0>] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk] + [<c109f617>] ? symbol_put_addr+0x27/0x50 + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + [<f80bb3bf>] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb] + [<c13d03bc>] ? usb_disable_endpoint+0x7c/0xb0 + [<f80bb48a>] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb] + [<c13d2882>] ? usb_unbind_interface+0x62/0x250 + [<c136b514>] ? __pm_runtime_idle+0x44/0x70 + [<c13620d8>] ? __device_release_driver+0x78/0x120 + [<c1362907>] ? driver_detach+0x87/0x90 + [<c1361c48>] ? bus_remove_driver+0x38/0x90 + [<c13d1c18>] ? usb_deregister+0x58/0xb0 + [<c109fbb0>] ? SyS_delete_module+0x130/0x1f0 + [<c1055654>] ? task_work_run+0x64/0x80 + [<c1000fa5>] ? exit_to_usermode_loop+0x85/0x90 + [<c10013f0>] ? do_fast_syscall_32+0x80/0x130 + [<c1549f43>] ? sysenter_past_esp+0x40/0x6a + ---[ end trace 6ebc60ef3981792f ]--- + +è¿™æ ·çš„å †æ ˆè·Ÿè¸ªæ供了足够的信æ¯æ¥è¯†åˆ«å†…æ ¸æºä»£ç ä¸å‘ç”Ÿé”™è¯¯çš„é‚£ä¸€è¡Œã€‚æ ¹æ®é—®é¢˜çš„ +严é‡æ€§ï¼Œå®ƒè¿˜å¯èƒ½åŒ…å« **“Oopsâ€** 一è¯ï¼Œæ¯”如:: + + BUG: unable to handle kernel NULL pointer dereference at (null) + IP: [<c06969d4>] iret_exc+0x7d0/0xa59 + *pdpt = 000000002258a001 *pde = 0000000000000000 + Oops: 0002 [#1] PREEMPT SMP + ... + +尽管有 **Oops** æˆ–å…¶ä»–ç±»åž‹çš„å †æ ˆè·Ÿè¸ªï¼Œä½†é€šå¸¸éœ€è¦æ‰¾åˆ°å‡ºé—®é¢˜çš„è¡Œæ¥è¯†åˆ«å’Œå¤„ç†ç¼º +é™·ã€‚åœ¨æœ¬ç« ä¸ï¼Œæˆ‘们将å‚考“Oopsâ€æ¥äº†è§£éœ€è¦åˆ†æžçš„å„ç§å †æ ˆè·Ÿè¸ªã€‚ + +å¦‚æžœå†…æ ¸æ˜¯ç”¨ ``CONFIG_DEBUG_INFO`` 编译的，那么å¯ä»¥ä½¿ç”¨æ–‡ä»¶ï¼š +`scripts/decode_stacktrace.sh` 。 + +é“¾æŽ¥çš„æ¨¡å— +----------- + +å—到污染或æ£åœ¨åŠ è½½/å¸è½½çš„模å—用“（…）â€æ ‡è®°ï¼Œæ±¡æŸ“æ ‡å¿—åœ¨ +`Documentation/admin-guide/tainted-kernels.rst` 文件ä¸è¿›è¡Œäº†æ述，“æ£åœ¨è¢«åŠ +è½½â€ç”¨â€œ+â€æ ‡æ³¨ï¼Œâ€œæ£åœ¨è¢«å¸è½½â€ç”¨â€œ-â€æ ‡æ³¨ã€‚ + + +Oops消æ¯åœ¨å“ªï¼Ÿ +--------------- + +通常，Oops文本由klogdä»Žå†…æ ¸ç¼“å†²åŒºè¯»å–，然åŽäº¤ç»™ ``syslogd`` ，åŽè€…将其写入 +syslog文件，通常是 ``/var/log/messages`` （å–决于 ``/etc/syslog.conf`` ）。 +在使用systemd的系统上，它也å¯ä»¥ç”± ``journald`` 守护进程å˜å‚¨ï¼Œå¹¶é€šè¿‡è¿è¡Œ +``journalctl`` 命令进行访问。 + +有时 ``klogd`` 会挂掉，这ç§æƒ…况下您å¯ä»¥è¿è¡Œ ``dmesg > file`` ä»Žå†…æ ¸ç¼“å†²åŒº +读å–æ•°æ®å¹¶ä¿å˜å®ƒã€‚或者您å¯ä»¥ ``cat /proc/kmsg > file`` ，但是您必须适时 +ä¸æ–以åœæ¢ä¼ è¾“ï¼Œå› ä¸º ``kmsg`` æ˜¯ä¸€ä¸ªâ€œæ°¸æ— æ¢å¢ƒçš„文件â€ã€‚ + +如果机器严é‡å´©æºƒï¼Œæ— 法输入命令或ç£ç›˜ä¸å¯ç”¨ï¼Œé‚£è¿˜æœ‰ä¸‰ä¸ªé€‰é¡¹ï¼š + +(1) 手动å¤åˆ¶å±å¹•ä¸Šçš„文本，并在机器é‡æ–°å¯åŠ¨åŽè¾“入。很难å—，但这是çªç„¶å´©æºƒä¸‹ + å”¯ä¸€çš„é€‰æ‹©ã€‚æˆ–è€…ä½ å¯ä»¥ç”¨æ•°ç 相机æ‹ä¸‹å±å¹•â€”—虽然ä¸é‚£ä¹ˆå¥½ï¼Œä½†æ€»æ¯”什么都没 + 有好。如果消æ¯æ»šåŠ¨è¶…出控制å°é¡¶éƒ¨ï¼Œä½¿ç”¨æ›´é«˜åˆ†è¾¨çŽ‡ï¼ˆä¾‹å¦‚ ``vga=791`` ） + 引导å¯åŠ¨å°†å…许您阅读更多文本。（è¦å‘Šï¼šè¿™éœ€è¦ ``vesafb`` ï¼Œå› æ¤å¯¹â€œæ—©æœŸâ€ + çš„Oppses没有帮助） + +(2) 从串å£ç»ˆç«¯å¯åŠ¨ï¼ˆå‚è§ + :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` ）， + 在å¦ä¸€å°æœºå™¨ä¸Šè¿è¡Œè°ƒåˆ¶è§£è°ƒå™¨ç„¶åŽç”¨ä½ 喜欢的通信程åºæ•èŽ·è¾“出。 + Minicomè¿è¡Œè‰¯å¥½ã€‚ + +(3) 使用Kdump（å‚阅 Documentation/admin-guide/kdump/kdump.rst ），使用 + Documentation/admin-guide/kdump/gdbmacros.txt ä¸çš„dmesg gdbmacroä»Žæ—§å†…å˜ + ä¸æå–å†…æ ¸çŽ¯å½¢ç¼“å†²åŒºã€‚ + +找到缺陷ä½ç½® +------------- + +å¦‚æžœä½ èƒ½æŒ‡å‡ºç¼ºé™·åœ¨å†…æ ¸æºä»£ç ä¸çš„ä½ç½®ï¼Œåˆ™æŠ¥å‘Šç¼ºé™·çš„效果会éžå¸¸å¥½ã€‚这有两ç§æ–¹æ³•ã€‚ +通常æ¥è¯´ä½¿ç”¨ ``gdb`` 会比较容易，ä¸è¿‡å†…æ ¸éœ€è¦ç”¨è°ƒè¯•ä¿¡æ¯æ¥é¢„编译。 + +gdb +^^^^ + +GNU 调试器（GNU debugger， ``gdb`` ）是从 ``vmlinux`` 文件ä¸æ‰¾å‡ºOOPS的确切 +文件和行å·çš„最佳方法。 + +在使用 ``CONFIG_DEBUG_INFO`` ç¼–è¯‘çš„å†…æ ¸ä¸Šä½¿ç”¨gdb效果最好。å¯é€šè¿‡è¿è¡Œä»¥ä¸‹å‘½ä»¤ +进行设置:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + +在用 ``CONFIG_DEBUG_INFO`` ç¼–è¯‘çš„å†…æ ¸ä¸Šï¼Œä½ å¯ä»¥ç›´æŽ¥ä»ŽOOPSå¤åˆ¶EIP值:: + + EIP: 0060:[<c021e50e>] Not tainted VLI + +并使用GDBæ¥å°†å…¶ç¿»è¯‘æˆå¯è¯»å½¢å¼:: + + $ gdb vmlinux + (gdb) l *0xc021e50e + +如果没有å¯ç”¨ ``CONFIG_DEBUG_INFO`` ，则使用OOPS的函数å移:: + + EIP is at vt_ioctl+0xda8/0x1482 + +并在å¯ç”¨ ``CONFIG_DEBUG_INFO`` 的情况下é‡æ–°ç¼–è¯‘å†…æ ¸:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + $ make vmlinux + $ gdb vmlinux + (gdb) l *vt_ioctl+0xda8 + 0x1888 is in vt_ioctl (drivers/tty/vt/vt_ioctl.c:293). + 288 { + 289 struct vc_data *vc = NULL; + 290 int ret = 0; + 291 + 292 console_lock(); + 293 if (VT_BUSY(vc_num)) + 294 ret = -EBUSY; + 295 else if (vc_num) + 296 vc = vc_deallocate(vc_num); + 297 console_unlock(); + +或者若您想è¦æ›´è¯¦ç»†çš„显示:: + + (gdb) p vt_ioctl + $1 = {int (struct tty_struct *, unsigned int, unsigned long)} 0xae0 <vt_ioctl> + (gdb) l *0xae0+0xda8 + +您也å¯ä»¥ä½¿ç”¨å¯¹è±¡æ–‡ä»¶ä½œä¸ºæ›¿ä»£:: + + $ make drivers/tty/ + $ gdb drivers/tty/vt/vt_ioctl.o + (gdb) l *vt_ioctl+0xda8 + +å¦‚æžœä½ æœ‰è°ƒç”¨è·Ÿè¸ªï¼Œç±»ä¼¼:: + + Call Trace: + [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5 + [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e + [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee + ... + +这表明问题å¯èƒ½åœ¨ :jbd: 模å—ä¸ã€‚您å¯ä»¥åœ¨gdbä¸åŠ 载该模å—并列出相关代ç :: + + $ gdb fs/jbd/jbd.ko + (gdb) l *log_wait_commit+0xa3 + +.. note:: + + 您还å¯ä»¥å¯¹å †æ ˆè·Ÿè¸ªå¤„的任何函数调用执行相åŒçš„æ“作，例如:: + + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + + 上述调用å‘生的ä½ç½®å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹å¼çœ‹åˆ°:: + + $ gdb drivers/media/usb/dvb-usb/dvb-usb.o + (gdb) l *dvb_usb_adapter_frontend_exit+0x3a + +objdump +^^^^^^^^ + +è¦è°ƒè¯•å†…æ ¸ï¼Œè¯·ä½¿ç”¨objdump并从崩溃输出ä¸æŸ¥æ‰¾åå…进制å移，以找到有效的代ç /汇 +编行。如果没有调试符å·ï¼Œæ‚¨å°†çœ‹åˆ°æ‰€ç¤ºä¾‹ç¨‹çš„汇编程åºä»£ç ï¼Œä½†æ˜¯å¦‚æžœå†…æ ¸æœ‰è°ƒè¯• +符å·ï¼ŒC代ç 也将å¯è§ï¼ˆè°ƒè¯•ç¬¦å·å¯ä»¥åœ¨å†…æ ¸é…ç½®èœå•çš„hacking项ä¸å¯ç”¨ï¼‰ã€‚例如:: + + $ objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. note:: + + 您需è¦å¤„äºŽå†…æ ¸æ ‘çš„é¡¶å±‚ä»¥ä¾¿æ¤èŽ·å¾—您的C文件。 + +å¦‚æžœæ‚¨æ— æ³•è®¿é—®æºä»£ç ，ä»ç„¶å¯ä»¥ä½¿ç”¨ä»¥ä¸‹æ–¹æ³•è°ƒè¯•ä¸€äº›å´©æºƒè½¬å‚¨ï¼ˆå¦‚Dave Millerçš„ +示例崩溃转储输出所示）:: + + EIP is at +0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + +`scripts/decodecode` 文件å¯ä»¥ç”¨æ¥è‡ªåŠ¨å®Œæˆå¤§éƒ¨åˆ†å·¥ä½œï¼Œè¿™å–决于æ£åœ¨è°ƒè¯•çš„CPU +体系结构。 + +报告缺陷 +--------- + +ä¸€æ—¦ä½ é€šè¿‡å®šä½ç¼ºé™·æ‰¾åˆ°äº†å…¶å‘ç”Ÿçš„åœ°æ–¹ï¼Œä½ å¯ä»¥å°è¯•è‡ªå·±ä¿®å¤å®ƒæˆ–者å‘上游报告它。 + +为了å‘上游报告，您应该找出用于开å‘å—å½±å“代ç 的邮件列表。这å¯ä»¥ä½¿ç”¨ ``get_maintainer.pl`` 。 + + +例如，您在gspcaçš„sonixj.c文件ä¸å‘现一个缺陷，则å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹æ³•æ‰¾åˆ°å®ƒçš„维护者:: + + $ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c + Hans Verkuil <hverkuil@xs4all.nl> (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%) + Mauro Carvalho Chehab <mchehab@kernel.org> (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%) + Tejun Heo <tj@kernel.org> (commit_signer:1/1=100%) + Bhaktipriya Shridhar <bhaktipriya96@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:4/4=100%,removed_lines:9/9=100%) + linux-media@vger.kernel.org (open list:GSPCA USB WEBCAM DRIVER) + linux-kernel@vger.kernel.org (open list) + +请注æ„它将指出： + +- 最åŽæŽ¥è§¦æºä»£ç çš„å¼€å‘人员（如果这是在gitæ ‘ä¸å®Œæˆçš„）。在上é¢çš„例åä¸æ˜¯Tejun + å’ŒBhaktipriya（在这个特定的案例ä¸ï¼Œæ²¡æœ‰äººçœŸæ£å‚与这个文件的开å‘）； +- 驱动维护人员（Hans Verkuil）； +- å系统维护人员（Mauro Carvalho Chehab）； +- 驱动程åºå’Œ/或å系统邮件列表（linux-media@vger.kernel.org）； +- Linuxå†…æ ¸é‚®ä»¶åˆ—è¡¨ï¼ˆlinux-kernel@vger.kernel.org）。 + +通常，修å¤ç¼ºé™·çš„最快方法是将它报告给用于开å‘相关代ç 的邮件列表（linux-media +ML），抄é€é©±åŠ¨ç¨‹åºç»´æŠ¤è€…（Hans）。 + +å¦‚æžœä½ å®Œå…¨ä¸çŸ¥é“该把报告寄给è°ï¼Œä¸” ``get_maintainer.pl`` 也没有æ供任何有用 +çš„ä¿¡æ¯ï¼Œè¯·å‘é€åˆ°linux-kernel@vger.kernel.org。 + +感谢您的帮助，这使Linuxå°½å¯èƒ½ç¨³å®š:-) + +ä¿®å¤ç¼ºé™· +--------- + +å¦‚æžœä½ æ‡‚å¾—ç¼–ç¨‹ï¼Œä½ ä¸ä»…å¯ä»¥é€šè¿‡æŠ¥å‘Šé”™è¯¯æ¥å¸®åŠ©æˆ‘们，还å¯ä»¥æ供一个解决方案。 +毕竟，开æºå°±æ˜¯åˆ†äº«ä½ çš„å·¥ä½œï¼Œä½ ä¸æƒ³å› ä¸ºä½ çš„å¤©æ‰è€Œè¢«è®¤å¯å—？ + +å¦‚æžœä½ å†³å®šè¿™æ ·åšï¼Œè¯·åœ¨åˆ¶å®šè§£å†³æ–¹æ¡ˆåŽå°†å…¶æ交到上游。 + +请务必阅读 +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` ， +以帮助您的代ç 被接å—。 + + +--------------------------------------------------------------------------- + +用 ``klogd`` 进行Oops跟踪的注æ„事项 +------------------------------------ + +为了帮助Linuså’Œå…¶ä»–å†…æ ¸å¼€å‘人员， ``klogd`` 对ä¿æŠ¤æ•…障的处ç†æ供了大é‡æ”¯æŒã€‚ +为了完整支æŒåœ°å€è§£æžï¼Œè‡³å°‘应该使用 ``sysklogd`` 包的1.3-pl3版本。 + +当å‘生ä¿æŠ¤æ•…障时， ``klogd`` å®ˆæŠ¤è¿›ç¨‹ä¼šè‡ªåŠ¨å°†å†…æ ¸æ—¥å¿—æ¶ˆæ¯ä¸çš„é‡è¦åœ°å€è½¬æ¢ä¸º +它们的ç‰æ•ˆç¬¦å·ã€‚然åŽé€šè¿‡ ``klogd`` 使用的任何报告机制æ¥è½¬å‘è¿™ä¸ªå·²ç¿»è¯‘çš„å†…æ ¸ +消æ¯ã€‚ä¿æŠ¤é”™è¯¯æ¶ˆæ¯å¯ä»¥ç›´æŽ¥ä»Žæ¶ˆæ¯æ–‡ä»¶ä¸å‰ªåˆ‡å‡ºæ¥å¹¶è½¬å‘ç»™å†…æ ¸å¼€å‘人员。 + +``klogd`` 执行两ç§ç±»åž‹çš„地å€è§£æžï¼Œé™æ€ç¿»è¯‘和动æ€ç¿»è¯‘。é™æ€ç¿»è¯‘使用System.map +文件。为了进行é™æ€è½¬æ¢ï¼Œ ``klogd`` 守护进程必须能够在守护进程åˆå§‹åŒ–时找到系 +ç»Ÿæ˜ å°„æ–‡ä»¶ã€‚æœ‰å…³ ``klogd`` 如何æœç´¢æ˜ 射文件的信æ¯ï¼Œè¯·å‚è§klogd手册页。 + +å½“ä½¿ç”¨å†…æ ¸å¯åŠ 载模å—时，动æ€åœ°å€è½¬æ¢éžå¸¸é‡è¦ã€‚ç”±äºŽå†…æ ¸æ¨¡å—的内å˜æ˜¯ä»Žå†…æ ¸çš„ +动æ€å†…å˜æ± ä¸åˆ†é…çš„ï¼Œå› æ¤æ— 论是模å—的开头还是模å—ä¸çš„函数和符å·éƒ½æ²¡æœ‰å›ºå®šçš„ +ä½ç½®ã€‚ + +å†…æ ¸æ”¯æŒç³»ç»Ÿè°ƒç”¨ï¼Œå…许程åºç¡®å®šåŠ 载哪些模å—åŠå…¶åœ¨å†…å˜ä¸çš„ä½ç½®ã€‚klogd守护进程 +使用这些系统调用构建了一个符å·è¡¨ï¼Œå¯ç”¨äºŽè°ƒè¯•å¯åŠ è½½å†…æ ¸æ¨¡å—ä¸å‘生的ä¿æŠ¤é”™è¯¯ã€‚ + +klogd至少会æ供产生ä¿æŠ¤æ•…障的模å—çš„å称。如果å¯åŠ 载模å—çš„å¼€å‘äººå‘˜é€‰æ‹©ä»Žæ¨¡å— +导出符å·ä¿¡æ¯ï¼Œåˆ™å¯èƒ½ä¼šæœ‰å…¶ä»–å¯ç”¨çš„符å·ä¿¡æ¯ã€‚ + +ç”±äºŽå†…æ ¸æ¨¡å—环境å¯ä»¥æ˜¯åŠ¨æ€çš„ï¼Œå› æ¤å½“模å—环境å‘生å˜åŒ–时，必须有一ç§é€šçŸ¥ +``klogd`` 守护进程的机制。有一些å¯ç”¨çš„命令行选项å…许klogdå‘当å‰æ£åœ¨æ‰§è¡Œçš„守 +护进程å‘出信å·ç¤ºæ„应该刷新符å·ä¿¡æ¯ã€‚有关更多信æ¯ï¼Œè¯·å‚阅 ``klogd`` 手册页。 + +sysklogdå‘行版附带了一个补ä¸ï¼Œå®ƒä¿®æ”¹äº† ``modules-2.0.0`` åŒ…ï¼Œä»¥ä¾¿åœ¨åŠ è½½æˆ– +å¸è½½æ¨¡å—时自动å‘klogdå‘é€ä¿¡å·ã€‚应用æ¤è¡¥ä¸åŸºæœ¬ä¸Šå¯æ— ç¼æ”¯æŒè°ƒè¯•å†…æ ¸å¯åŠ è½½æ¨¡å— +å‘生的ä¿æŠ¤æ•…障。 + +以下是 ``klogd`` 处ç†çš„å¯åŠ 载模å—ä¸çš„ä¿æŠ¤æ•…障示例:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 48bbd3ebad48..be835ec8e632 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -13,9 +13,13 @@ Linux å†…æ ¸ç”¨æˆ·å’Œç®¡ç†å‘˜æŒ‡å— 这个åˆå§‹éƒ¨åˆ†åŒ…å«æ€»ä½“ä¿¡æ¯ï¼ŒåŒ…括æè¿°å†…æ ¸çš„README， å…³äºŽå†…æ ¸å‚数的文档ç‰ã€‚ -Todolist: +.. toctree:: + :maxdepth: 1 README + +Todolist: + kernel-parameters devices sysctl/index @@ -28,16 +32,21 @@ Todolist: 下é¢çš„一组文档，针对的是试图跟踪问题和bug的用户。 -Todolist: +.. toctree:: + :maxdepth: 1 - reporting-bugs + reporting-issues security-bugs bug-hunting bug-bisect tainted-kernels + init + +Todolist: + + reporting-bugs ramoops dynamic-debug-howto - init kdump/index perf/index @@ -56,6 +65,7 @@ Todolist: clearing-warn-once cpu-load + unicode Todolist: @@ -111,7 +121,6 @@ Todolist: sysrq thunderbolt ufs - unicode vga-softcursor video-output xfs diff --git a/Documentation/translations/zh_CN/admin-guide/init.rst b/Documentation/translations/zh_CN/admin-guide/init.rst new file mode 100644 index 000000000000..fbaf6d97f86c --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/init.rst @@ -0,0 +1,54 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/init` + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +解释“No working init found.â€å¯åŠ¨æŒ‚èµ·æ¶ˆæ¯ +========================================= + +:作者: + + Andreas Mohr <andi at lisas period de> + + Cristian Souza <cristianmsbr at gmail period com> + +本文档æä¾›äº†åŠ è½½åˆå§‹åŒ–二进制（init binaryï¼‰å¤±è´¥çš„ä¸€äº›é«˜å±‚çº§åŽŸå› ï¼ˆå¤§è‡´æŒ‰æ‰§è¡Œ +顺åºåˆ—出）。 + +1) **æ— æ³•æŒ‚è½½æ ¹æ–‡ä»¶ç³»ç»ŸUnable to mount root FS** ：请设置“debugâ€å†…æ ¸å‚数（在 + å¼•å¯¼åŠ è½½ç¨‹åºbootloaderé…置文件或CONFIG_CMDLINE）以获å–æ›´è¯¦ç»†çš„å†…æ ¸æ¶ˆæ¯ã€‚ + +2) **åˆå§‹åŒ–二进制ä¸å˜åœ¨äºŽæ ¹æ–‡ä»¶ç³»ç»Ÿä¸Šinit binary doesn't exist on rootfs** ： + ç¡®ä¿æ‚¨çš„æ ¹æ–‡ä»¶ç³»ç»Ÿç±»åž‹æ£ç¡®ï¼ˆå¹¶ä¸” ``root=`` å†…æ ¸å‚数指å‘æ£ç¡®çš„分区）；拥有 + 所需的驱动程åºï¼Œä¾‹å¦‚SCSI或USBç‰å˜å‚¨ç¡¬ä»¶ï¼›æ–‡ä»¶ç³»ç»Ÿï¼ˆext3ã€jffs2ç‰ï¼‰æ˜¯å†…建的 + （或者作为模å—ç”±initrdé¢„åŠ è½½ï¼‰ã€‚ + +3) **控制å°è®¾å¤‡æŸåBroken console device** ： ``console= setup`` ä¸å¯èƒ½å˜åœ¨ + å†²çª --> åˆå§‹æŽ§åˆ¶å°ä¸å¯ç”¨ï¼ˆinitial console unavailable）。例如，由于串行 + IRQ问题（如缺少基于ä¸æ–çš„é…置）导致的æŸäº›ä¸²è¡ŒæŽ§åˆ¶å°ä¸å¯é 。å°è¯•ä½¿ç”¨ä¸åŒçš„ + ``console= device`` æˆ–åƒ ``netconsole=`` 。 + +4) **二进制å˜åœ¨ä½†ä¾èµ–项ä¸å¯ç”¨Binary exists but dependencies not available** ： + 例如åˆå§‹åŒ–二进制的必需库ä¾èµ–é¡¹ï¼Œåƒ ``/lib/ld-linux.so.2`` 丢失或æŸå。使用 + ``readelf -d <INIT>|grep NEEDED`` 找出需è¦å“ªäº›åº“。 + +5) **æ— æ³•åŠ è½½äºŒè¿›åˆ¶Binary cannot be loaded** ：请确ä¿äºŒè¿›åˆ¶çš„体系结构与您的 + 硬件匹é…。例如i386ä¸åŒ¹é…x86_64，或者å°è¯•åœ¨ARMç¡¬ä»¶ä¸ŠåŠ è½½x86。如果您å°è¯•åœ¨ + æ¤å¤„åŠ è½½éžäºŒè¿›åˆ¶æ–‡ä»¶ï¼ˆshell脚本？），您应该确ä¿è„šæœ¬åœ¨å…¶å·¥ä½œå¤´ï¼ˆshebang + header）行 ``#!/...`` ä¸æŒ‡å®šèƒ½æ£å¸¸å·¥ä½œçš„解释器（包括其库ä¾èµ–é¡¹ï¼‰ã€‚åœ¨å¤„ç† + 脚本之å‰ï¼Œæœ€å¥½å…ˆæµ‹è¯•ä¸€ä¸ªç®€å•çš„éžè„šæœ¬äºŒè¿›åˆ¶æ–‡ä»¶ï¼Œæ¯”如 ``/bin/sh`` ，并确认 + 它能æˆåŠŸæ‰§è¡Œã€‚è¦äº†è§£æ›´å¤šä¿¡æ¯ï¼Œè¯·å°†ä»£ç æ·»åŠ åˆ° ``init/main.c`` 以显示 + kernel_execve()的返回值。 + +当您å‘çŽ°æ–°çš„å¤±è´¥åŽŸå› æ—¶ï¼Œè¯·æ‰©å±•æœ¬è§£é‡Šï¼ˆæ¯•ç«ŸåŠ è½½åˆå§‹åŒ–二进制是一个 **关键** 且 +艰难的过渡æ¥éª¤ï¼Œéœ€è¦å°½å¯èƒ½æ— 痛地进行），然åŽå‘LKMLæ交一个补ä¸ã€‚ + +待办事项： + +- 通过一个å¯ä»¥å˜å‚¨ ``kernel_execve()`` 结果值的结构体数组实现å„ç§ + ``run_init_process()`` 调用，并在失败时通过è¿ä»£ **所有** 结果æ¥è®°å½•ä¸€åˆ‡ + （éžå¸¸é‡è¦çš„å¯ç”¨æ€§ä¿®å¤ï¼‰ã€‚ +- 试ç€ä½¿å®žçŽ°æœ¬èº«åœ¨ä¸€èˆ¬æƒ…况下更有帮助，例如在å—å½±å“的地方æä¾›é¢å¤–的错误消æ¯ã€‚ diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst new file mode 100644 index 000000000000..6b4988da2c5a --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst @@ -0,0 +1,1335 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. + If you want to distribute this text under CC-BY-4.0 only, please use 'The + Linux kernel developers' for author attribution and link this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/reporting-issues.rst + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + + +报告问题 ++++++++++ + + +简明指å—ï¼ˆäº¦å³ å¤ªé•¿ä¸çœ‹ï¼‰ +========================== + +您é¢ä¸´çš„是å¦ä¸ºåŒç³»åˆ—稳定版或长期支æŒå†…æ ¸çš„æ™®é€šå†…æ ¸çš„å›žå½’ï¼Ÿæ˜¯å¦ä»ç„¶å—支æŒï¼Ÿ +请æœç´¢ `LKMLå†…æ ¸é‚®ä»¶åˆ—è¡¨ <https://lore.kernel.org/lkml/>`_ å’Œ +`Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ å˜æ¡£ä¸åŒ¹é…的报告并 +åŠ å…¥è®¨è®ºã€‚å¦‚æžœæ‰¾ä¸åˆ°åŒ¹é…的报告，请安装该系列的最新版本。如果它ä»ç„¶å‡ºçŽ°é—®é¢˜ï¼Œ +报告给稳定版邮件列表（stable@vger.kernel.org）。 + +在所有其他情况下，请尽å¯èƒ½çŒœæµ‹æ˜¯å“ªä¸ªå†…æ ¸éƒ¨åˆ†å¯¼è‡´äº†é—®é¢˜ã€‚æŸ¥çœ‹MAINTAINERS文件， +了解开å‘人员希望如何得知问题，大多数情况下，报告问题都是通过电åé‚®ä»¶å’ŒæŠ„é€ +相关邮件列表进行的。检查报告目的地的å˜æ¡£ä¸æ˜¯å¦å·²æœ‰åŒ¹é…的报告；也请æœç´¢ +`LKML <https://lore.kernel.org/lkml/>`_ 和网络。如果找ä¸åˆ°å¯åŠ 入的讨论，请 +安装 `æœ€æ–°çš„ä¸»çº¿å†…æ ¸ <https://kernel.org/>`_ 。如果ä»å˜åœ¨é—®é¢˜ï¼Œè¯·å‘é€æŠ¥å‘Šã€‚ + +问题已ç»è§£å†³äº†ï¼Œä½†æ˜¯æ‚¨å¸Œæœ›çœ‹åˆ°å®ƒåœ¨ä¸€ä¸ªä»ç„¶æ”¯æŒçš„稳定版或长期支æŒç³»åˆ—ä¸å¾—到 +解决？请安装其最新版本。如果它出现了问题，那么在主线ä¸æœç´¢ä¿®å¤å®ƒçš„更改，并 +检查是å¦æ£åœ¨å›žä¼ （backporting）或者已放弃；如果两者都没有，那么å¯è¯¢é—®å¤„ç† +更改的人员。 + +**通用æ醒** ï¼šå½“å®‰è£…å’Œæµ‹è¯•ä¸Šè¿°å†…æ ¸æ—¶ï¼Œè¯·ç¡®ä¿å®ƒæ˜¯æ™®é€šçš„（å³ï¼šæ²¡æœ‰è¡¥ä¸ï¼Œä¹Ÿæ²¡ +æœ‰ä½¿ç”¨é™„åŠ æ¨¡å—）。还è¦ç¡®ä¿å®ƒæ˜¯åœ¨ä¸€ä¸ªæ£å¸¸çš„环境ä¸æž„建和è¿è¡Œï¼Œå¹¶ä¸”在问题å‘生 +之å‰æ²¡æœ‰è¢«æ±¡æŸ“（tainted）。 + +在编写报告时，è¦æ¶µç›–与问题相关的所有信æ¯ï¼Œå¦‚ä½¿ç”¨çš„å†…æ ¸å’Œå‘行版。在碰è§å›žå½’时， +å°è¯•ç»™å‡ºå¼•å…¥å®ƒçš„更改的æ交ID，二分å¯ä»¥æ‰¾åˆ°å®ƒã€‚如果您åŒæ—¶é¢ä¸´Linuxå†…æ ¸çš„å¤šä¸ª +问题，请分别报告æ¯ä¸ªé—®é¢˜ã€‚ + +一旦报告å‘出，请回ç”任何出现的问题，并尽å¯èƒ½åœ°æ供帮助。这包括通过ä¸æ—¶é‡æ–° +测试新版本并å‘é€çŠ¶æ€æ›´æ–°æ¥æŽ¨åŠ¨è¿›å±•ã€‚ + + +如何å‘å†…æ ¸ç»´æŠ¤äººå‘˜æŠ¥å‘Šé—®é¢˜çš„é€æ¥æŒ‡å— +===================================== + +上é¢çš„简明指å—概述了如何å‘Linuxå†…æ ¸å¼€å‘人员报告问题。对于已ç»ç†Ÿæ‚‰å‘自由和开 +æºè½¯ä»¶ï¼ˆFLOSS）项目报告问题的人æ¥è¯´ï¼Œè¿™å¯èƒ½æ˜¯ä»–们所需è¦çš„全部内容。对于其他 +人，本部分更为详细，并一æ¥ä¸€æ¥åœ°æ述。为了便于阅读，它ä»ç„¶å°½é‡ç®€æ´ï¼Œå¹¶çœç•¥ +了许多细节；这些在é€æ¥æŒ‡å—åŽçš„å‚è€ƒç« èŠ‚ä¸è¿›è¡Œäº†æè¿°ï¼Œè¯¥ç« èŠ‚æ›´è¯¦ç»†åœ°è§£é‡Šäº†æ¯ +个æ¥éª¤ã€‚ + +注æ„：本节涉åŠçš„æ–¹é¢æ¯”简明指å—多，顺åºä¹Ÿç¨æœ‰ä¸åŒã€‚这符åˆä½ 的利益，以确ä¿æ‚¨ +尽早æ„识到看起æ¥åƒLinuxå†…æ ¸æ¯›ç—…çš„é—®é¢˜å¯èƒ½å®žé™…ä¸Šæ˜¯ç”±å…¶ä»–åŽŸå› å¼•èµ·çš„ã€‚è¿™äº›æ¥éª¤ +å¯ä»¥ç¡®ä¿ä½ 最终ä¸ä¼šè§‰å¾—在这一过程ä¸æŠ•å…¥çš„时间是浪费： + + * 您是å¦é¢ä¸´ç¡¬ä»¶æˆ–软件供应商æ供的Linuxå†…æ ¸çš„é—®é¢˜ï¼Ÿé‚£ä¹ˆåŸºæœ¬ä¸Šæ‚¨æœ€å¥½åœæ¢é˜…读 + 本文档，转而å‘您的供应商报告问题，除éžæ‚¨æ„¿æ„自己安装最新的Linux版本。寻找 + 和解决问题往往需è¦åŽè€…。 + + * 使用您喜爱的网络æœç´¢å¼•æ“Žå¯¹çŽ°æœ‰æŠ¥å‘Šè¿›è¡Œç²—ç•¥æœç´¢ï¼›æ¤å¤–，请检查 + `Linuxå†…æ ¸é‚®ä»¶åˆ—è¡¨ï¼ˆLKML） <https://lore.kernel.org/lkml/>`_ çš„å˜æ¡£ã€‚如果 + 找到匹é…çš„æŠ¥å‘Šï¼Œè¯·åŠ å…¥è®¨è®ºè€Œä¸æ˜¯å‘é€æ–°æŠ¥å‘Šã€‚ + + * çœ‹çœ‹ä½ æ£åœ¨å¤„ç†çš„问题是å¦ä¸ºå›žå½’问题ã€å®‰å…¨é—®é¢˜æˆ–éžå¸¸ä¸¥é‡çš„问题：这些都是需 + è¦åœ¨æŽ¥ä¸‹æ¥çš„一些æ¥éª¤ä¸ç‰¹åˆ«å¤„ç†çš„“高优先级问题â€ã€‚ + + * ç¡®ä¿ä¸æ˜¯å†…æ ¸çŽ¯å¢ƒå¯¼è‡´äº†æ‚¨é¢ä¸´çš„问题。 + + * 创建一个新的备份，并将系统修å¤å’Œæ¢å¤å·¥å…·æ”¾åœ¨æ‰‹è¾¹ã€‚ + + * ç¡®ä¿æ‚¨çš„系统ä¸ä¼šé€šè¿‡åŠ¨æ€æž„建é¢å¤–çš„å†…æ ¸æ¨¡å—æ¥å¢žå¼ºå…¶å†…æ ¸ï¼ŒåƒDKMSè¿™æ ·çš„è§£å†³ + 方案å¯èƒ½åœ¨æ‚¨ä¸çŸ¥æƒ…çš„æƒ…å†µä¸‹å°±åœ¨æœ¬åœ°è¿›è¡Œäº†è¿™æ ·çš„å·¥ä½œã€‚ + + * 当问题å‘ç”Ÿæ—¶ï¼Œæ£€æŸ¥æ‚¨çš„å†…æ ¸æ˜¯å¦è¢«â€œæ±¡æŸ“â€ï¼Œå› ä¸ºä½¿å†…æ ¸è®¾ç½®è¿™ä¸ªæ ‡å¿—çš„äº‹ä»¶å¯èƒ½ + 会导致您é¢ä¸´çš„问题。 + + * 粗略地写下如何é‡çŽ°è¿™ä¸ªé—®é¢˜ã€‚如果您åŒæ—¶å¤„ç†å¤šä¸ªé—®é¢˜ï¼Œè¯·ä¸ºæ¯ä¸ªé—®é¢˜å•ç‹¬å†™æ³¨ + 释，并确ä¿å®ƒä»¬åœ¨æ–°å¯åŠ¨çš„系统上独立出现。这是必è¦çš„ï¼Œå› ä¸ºæ¯ä¸ªé—®é¢˜éƒ½éœ€è¦åˆ† + åˆ«æŠ¥å‘Šç»™å†…æ ¸å¼€å‘人员，除éžå®ƒä»¬ä¸¥é‡çº ç¼ åœ¨ä¸€èµ·ã€‚ + + * 如果您æ£é¢ä¸´ç¨³å®šç‰ˆæˆ–长期支æŒç‰ˆæœ¬çº¿çš„回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看åŽæ–‡â€œæŠ¥å‘Šç¨³å®šç‰ˆå’Œé•¿æœŸæ”¯æŒå†…æ ¸çº¿çš„å›žå½’â€å°èŠ‚。 + + * 定ä½å¯èƒ½å¼•èµ·é—®é¢˜çš„驱动程åºæˆ–å†…æ ¸å系统。找出其开å‘人员期望的报告的方å¼å’Œ + ä½ç½®ã€‚注æ„：大多数情况下ä¸ä¼šæ˜¯ bugzilla.kernel.orgï¼Œå› ä¸ºé—®é¢˜é€šå¸¸éœ€è¦é€š + 过邮件å‘é€ç»™ç»´æŠ¤äººå‘˜å’Œå…¬å…±é‚®ä»¶åˆ—表。 + + * 在缺陷追踪器或问题相关邮件列表的å˜æ¡£ä¸å½»åº•æœç´¢å¯èƒ½ä¸Žæ‚¨çš„问题匹é…的报告。 + å¦‚æžœä½ å‘çŽ°äº†ä¸€äº›ç›¸å…³è®¨è®ºï¼Œè¯·åŠ å…¥è®¨è®ºè€Œä¸æ˜¯å‘é€æ–°çš„报告。 + +在完æˆè¿™äº›å‡†å¤‡ä¹‹åŽï¼Œä½ 将进入主è¦éƒ¨åˆ†ï¼š + + * 除éžæ‚¨å·²ç»åœ¨è¿è¡Œæœ€æ–°çš„“主线â€Linuxå†…æ ¸ï¼Œå¦åˆ™æœ€å¥½åœ¨æŠ¥å‘Šæµç¨‹å‰å®‰è£…它。在æŸäº› + 情况下，使用最新的“稳定版â€Linux进行测试和报告也是å¯ä»¥æŽ¥å—的替代方案；在 + åˆå¹¶çª—å£æœŸé—´ï¼Œè¿™å®žé™…上å¯èƒ½æ˜¯æœ€å¥½çš„方法，但在开å‘阶段最好还是暂åœå‡ å¤©ã€‚æ— è®º + ä½ é€‰æ‹©ä»€ä¹ˆç‰ˆæœ¬ï¼Œæœ€å¥½ä½¿ç”¨â€œæ™®é€šâ€æž„å»ºã€‚å¿½ç•¥è¿™äº›å»ºè®®ä¼šå¤§å¤§å¢žåŠ æ‚¨çš„æŠ¥å‘Šè¢«æ‹’ç» + 或忽略的风险。 + + * ç¡®ä¿æ‚¨åˆšåˆšå®‰è£…çš„å†…æ ¸åœ¨è¿è¡Œæ—¶ä¸ä¼šâ€œæ±¡æŸ“â€è‡ªå·±ã€‚ + + * åœ¨æ‚¨åˆšåˆšå®‰è£…çš„å†…æ ¸ä¸å¤çŽ°è¿™ä¸ªé—®é¢˜ã€‚如果它没有出现，请查看下方åªå‘生在 + 稳定版和长期支æŒå†…æ ¸çš„é—®é¢˜çš„è¯´æ˜Žã€‚ + + * ä¼˜åŒ–ä½ çš„ç¬”è®°ï¼šè¯•ç€æ‰¾åˆ°å¹¶å†™å‡ºæœ€ç›´æŽ¥çš„å¤çŽ°é—®é¢˜çš„方法。确ä¿æœ€ç»ˆç»“果包å«æ‰€æœ‰ + é‡è¦çš„细节，åŒæ—¶è®©ç¬¬ä¸€æ¬¡å¬è¯´çš„人容易阅读和ç†è§£ã€‚如果您在æ¤è¿‡ç¨‹ä¸å¦åˆ°äº†ä¸€ + 些东西，请考虑å†æ¬¡æœç´¢å…³äºŽè¯¥é—®é¢˜çš„现有报告。 + + * 如果失败涉åŠâ€œpanicâ€ã€â€œOopsâ€ã€â€œwarningâ€æˆ–“BUGâ€ï¼Œè¯·è€ƒè™‘解ç å†…æ ¸æ—¥å¿—ä»¥æŸ¥æ‰¾è§¦ + å‘错误的代ç 行。 + + * 如果您的问题是回归问题，请尽å¯èƒ½ç¼©å°å¼•å…¥é—®é¢˜æ—¶çš„范围。 + + * 通过详细æ述问题æ¥å¼€å§‹ç¼–写报告。记得包括以下æ¡ç›®ï¼šæ‚¨ä¸ºå¤çŽ°è€Œå®‰è£…的最新内 + æ ¸ç‰ˆæœ¬ã€ä½¿ç”¨çš„Linuxå‘行版以åŠå…³äºŽå¦‚何å¤çŽ°è¯¥é—®é¢˜çš„说明。如果å¯èƒ½ï¼Œå°†å†…æ ¸ + 构建é…置（.config）和 ``dmesg`` 的输出放在网上的æŸä¸ªåœ°æ–¹ï¼Œå¹¶é“¾æŽ¥åˆ°å®ƒã€‚包 + å«æˆ–ä¸Šä¼ æ‰€æœ‰å…¶ä»–å¯èƒ½ç›¸å…³çš„ä¿¡æ¯ï¼Œå¦‚Oops的输出/截图或æ¥è‡ª ``lspci`` 的输出 + ã€‚ä¸€æ—¦ä½ å†™å®Œäº†è¿™ä¸ªä¸»è¦éƒ¨åˆ†ï¼Œè¯·åœ¨ä¸Šæ–¹æ’入一个æ£å¸¸é•¿åº¦çš„段è½å¿«é€Ÿæ¦‚述问题和 + å½±å“。å†åœ¨æ¤ä¹‹ä¸Šæ·»åŠ 一个简å•æ述问题的å¥å，以得到人们的阅读。现在给出一 + 个更çŸçš„æè¿°æ€§æ ‡é¢˜æˆ–ä¸»é¢˜ã€‚ç„¶åŽå°±å¯ä»¥åƒMAINTAINERSæ–‡ä»¶å‘Šè¯‰ä½ çš„é‚£æ ·å‘é€æˆ– + æ交报告了，除éžä½ 在处ç†ä¸€ä¸ªâ€œé«˜ä¼˜å…ˆçº§é—®é¢˜â€ï¼šå®ƒä»¬éœ€è¦æŒ‰ç…§ä¸‹é¢â€œé«˜ä¼˜å…ˆçº§é—® + 题的特殊处ç†â€æ‰€è¿°ç‰¹åˆ«å…³ç…§ã€‚ + + * ç‰å¾…别人的å应，继ç»æŽ¨è¿›äº‹æƒ…ï¼Œç›´åˆ°ä½ èƒ½å¤ŸæŽ¥å—è¿™æ ·æˆ–é‚£æ ·çš„ç»“æžœã€‚å› æ¤ï¼Œè¯·å…¬ + 开和åŠæ—¶åœ°å›žåº”任何询问。测试æ出的修å¤ã€‚积æžåœ°æµ‹è¯•ï¼šè‡³å°‘é‡æ–°æµ‹è¯•æ¯ä¸ªæ–°ä¸» + 线版本的首个候选版本（RCï¼‰ï¼Œå¹¶æŠ¥å‘Šä½ çš„ç»“æžœã€‚å¦‚æžœå‡ºçŽ°æ‹–å»¶ï¼Œå°±å‹å¥½åœ°æ醒一 + ä¸‹ã€‚å¦‚æžœä½ æ²¡æœ‰å¾—åˆ°ä»»ä½•å¸®åŠ©æˆ–è€…æœªèƒ½æ»¡æ„，请试ç€è‡ªå·±å¸®åŠ©è‡ªå·±ã€‚ + + +报告稳定版和长期支æŒå†…æ ¸çº¿çš„å›žå½’ +---------------------------------- + +如果您å‘现了稳定版或长期支æŒå†…æ ¸ç‰ˆæœ¬çº¿ä¸çš„回归问题并按上述æµç¨‹è·³åˆ°è¿™é‡Œï¼Œé‚£ä¹ˆ +请阅读本å°èŠ‚。å³ä¾‹å¦‚您在从5.10.4更新到5.10.5时出现了问题（从5.9.15到5.10.5则 +ä¸æ˜¯ï¼‰ã€‚å¼€å‘人员希望尽快修å¤æ¤ç±»å›žå½’ï¼Œå› æ¤æœ‰ä¸€ä¸ªç®€åŒ–æµç¨‹æ¥æŠ¥å‘Šå®ƒä»¬ï¼š + + * æ£€æŸ¥å†…æ ¸å¼€å‘人员是å¦ä»ç„¶ç»´æŠ¤ä½ 关心的Linuxå†…æ ¸ç‰ˆæœ¬çº¿ï¼šåŽ» `kernel.org 的首页 + <https://kernel.org/>`_ ，确ä¿æ¤ç‰¹å®šç‰ˆæœ¬çº¿çš„最新版没有“[EOL]â€æ ‡è®°ã€‚ + + * 检查 `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ ä¸çš„现有报告。 + + * ä»Žç‰¹å®šçš„ç‰ˆæœ¬çº¿å®‰è£…æœ€æ–°ç‰ˆæœ¬ä½œä¸ºçº¯å‡€å†…æ ¸ã€‚ç¡®ä¿è¿™ä¸ªå†…æ ¸æ²¡æœ‰è¢«æ±¡æŸ“ï¼Œå¹¶ä¸”ä»ç„¶ + å˜åœ¨é—®é¢˜ï¼Œå› 为问题å¯èƒ½å·²ç»åœ¨é‚£é‡Œè¢«ä¿®å¤äº†ã€‚如果您第一次å‘çŽ°ä¾›åº”å•†å†…æ ¸çš„é—®é¢˜ï¼Œ + 请检查已知最新版本的普通构建是å¦å¯ä»¥æ£å¸¸è¿è¡Œã€‚ + + * å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸçš„问题报告(stable@vger.kernel.org)。大致 + æ述问题，并解释如何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ£å¸¸çš„版本。 + 然åŽç‰å¾…进一æ¥çš„指示。 + +下é¢çš„å‚è€ƒç« èŠ‚éƒ¨åˆ†è¯¦ç»†è§£é‡Šäº†è¿™äº›æ¥éª¤ä¸çš„æ¯ä¸€æ¥ã€‚ + + +报告åªå‘ç”Ÿåœ¨è¾ƒæ—§å†…æ ¸ç‰ˆæœ¬çº¿çš„é—®é¢˜ +---------------------------------- + +若您å°è¯•äº†ä¸Šè¿°çš„æœ€æ–°ä¸»çº¿å†…æ ¸ï¼Œä½†æœªèƒ½åœ¨é‚£é‡Œå¤çŽ°é—®é¢˜ï¼Œé‚£ä¹ˆæœ¬å°èŠ‚适用于您；以下 +æµç¨‹æœ‰åŠ©äºŽä½¿é—®é¢˜åœ¨ä»ç„¶æ”¯æŒçš„稳定版或长期支æŒç‰ˆæœ¬çº¿ï¼Œæˆ–者定期基于最新稳定版或 +长期支æŒå†…æ ¸çš„ä¾›åº”å•†å†…æ ¸ä¸å¾—到修å¤ã€‚如果是这ç§æƒ…况，请执行以下æ¥éª¤ï¼š + + * 请åšå¥½å‡†å¤‡ï¼ŒæŽ¥ä¸‹æ¥çš„å‡ ä¸ªæ¥éª¤å¯èƒ½æ— 法在旧版本ä¸è§£å†³é—®é¢˜ï¼šä¿®å¤å¯èƒ½å¤ªå¤§æˆ–太 + å†’é™©ï¼Œæ— æ³•ç§»æ¤åˆ°é‚£é‡Œã€‚ + + * 执行å‰èŠ‚“报告稳定版和长期支æŒå†…æ ¸çº¿çš„å›žå½’â€ä¸çš„å‰ä¸‰ä¸ªæ¥éª¤ã€‚ + + * 在Linuxå†…æ ¸ç‰ˆæœ¬æŽ§åˆ¶ç³»ç»Ÿä¸æœç´¢ä¿®å¤ä¸»çº¿é—®é¢˜çš„æ›´æ”¹ï¼Œå› ä¸ºå®ƒçš„æ交消æ¯å¯èƒ½ä¼š + å‘Šè¯‰ä½ ä¿®å¤æ˜¯å¦å·²ç»è®¡åˆ’好了支æŒã€‚å¦‚æžœä½ æ²¡æœ‰æ‰¾åˆ°ï¼Œæœç´¢é€‚当的邮件列表，寻找 + 讨论æ¤ç±»é—®é¢˜æˆ–åŒè¡Œè¯„è®®å¯èƒ½ä¿®å¤çš„帖å；然åŽæ£€æŸ¥è®¨è®ºæ˜¯å¦è®¤ä¸ºä¿®å¤ä¸é€‚åˆæ”¯æŒã€‚ + 如果支æŒæ ¹æœ¬ä¸è¢«è€ƒè™‘ï¼ŒåŠ å…¥æœ€æ–°çš„è®¨è®ºï¼Œè¯¢é—®æ˜¯å¦æœ‰å¯èƒ½ã€‚ + + * å‰é¢çš„æ¥éª¤ä¹‹ä¸€åº”该会给出一个解决方案。如果ä»æœªèƒ½æˆåŠŸï¼Œè¯·å‘å¯èƒ½å¼•èµ·é—®é¢˜çš„ + å系统的维护人员询问建议；抄é€ç‰¹å®šå系统的邮件列表以åŠç¨³å®šç‰ˆé‚®ä»¶åˆ—表 + +下é¢çš„å‚è€ƒç« èŠ‚éƒ¨åˆ†è¯¦ç»†è§£é‡Šäº†è¿™äº›æ¥éª¤ä¸çš„æ¯ä¸€æ¥ã€‚ + + +å‚è€ƒç« èŠ‚ï¼šå‘å†…æ ¸ç»´æŠ¤è€…æŠ¥å‘Šé—®é¢˜ +=============================== + +上é¢çš„详细指å—简è¦åœ°åˆ—出了所有主è¦æ¥éª¤ï¼Œè¿™å¯¹å¤§å¤šæ•°äººæ¥è¯´åº”该足够了。但有时， +å³ä½¿æ˜¯æœ‰ç»éªŒçš„用户也å¯èƒ½æƒ³çŸ¥é“如何实际执行这些æ¥éª¤ä¹‹ä¸€ã€‚这就是本节的目的， +å› ä¸ºå®ƒå°†æ供关于上述æ¯ä¸ªæ¥éª¤çš„更多细节。请将æ¤ä½œä¸ºå‚考文档：å¯ä»¥ä»Žå¤´åˆ°å°¾ +阅读它。但它主è¦æ˜¯ä¸ºäº†æµè§ˆå’ŒæŸ¥æ‰¾å¦‚何实际执行这些æ¥éª¤çš„详细信æ¯ã€‚ + +在深入挖掘细节之å‰ï¼Œæˆ‘æƒ³å…ˆç»™ä½ ä¸€äº›ä¸€èˆ¬æ€§å»ºè®®ï¼š + + * Linuxå†…æ ¸å¼€å‘人员很清楚这个过程很å¤æ‚，比其他的FLOSS项目è¦æ±‚更多。我们很 + 希望让它更简å•ã€‚但这需è¦åœ¨ä¸åŒçš„地方以åŠä¸€äº›åŸºç¡€è®¾æ–½ä¸Šä»˜è¯¸åŠªåŠ›ï¼Œè¿™äº›åŸºç¡€ + 设施需è¦æŒç»çš„维护；尚未有人站出æ¥åšè¿™äº›å·¥ä½œï¼Œæ‰€ä»¥ç›®å‰æƒ…å†µå°±æ˜¯è¿™æ ·ã€‚ + + * 与æŸäº›ä¾›åº”商ç¾è®¢çš„ä¿è¯æˆ–支æŒåˆåŒå¹¶ä¸èƒ½ä½¿æ‚¨æœ‰æƒè¦æ±‚上游Linuxå†…æ ¸ç¤¾åŒºçš„å¼€ + å‘人员进行修å¤ï¼šè¿™æ ·çš„åˆåŒå®Œå…¨åœ¨Linuxå†…æ ¸ã€å…¶å¼€å‘社区和本文档的范围之外。 + 这就是为什么在这ç§æƒ…å†µä¸‹ï¼Œä½ ä¸èƒ½è¦æ±‚任何契约ä¿è¯ï¼Œå³ä½¿å¼€å‘人员处ç†çš„é—® + é¢˜å¯¹ä¾›åº”å•†æœ‰æ•ˆã€‚å¦‚æžœæ‚¨æƒ³ä¸»å¼ æ‚¨çš„æƒåˆ©ï¼Œä½¿ç”¨ä¾›åº”商的支æŒæ¸ é“ä»£æ›¿ã€‚å½“è¿™æ ·åš + çš„æ—¶å€™ï¼Œä½ å¯èƒ½æƒ³æå‡ºä½ å¸Œæœ›çœ‹åˆ°è¿™ä¸ªé—®é¢˜åœ¨ä¸Šæ¸¸Linuxå†…æ ¸ä¸ä¿®å¤ï¼›å¯ä»¥è¿™æ˜¯ç¡® + ä¿æœ€ç»ˆä¿®å¤å°†è¢«çº³å…¥æ‰€æœ‰Linuxå‘行版的唯一方法æ¥é¼“励他们。 + + * 如果您从未å‘FLOSS项目报告过任何问题，那么您应该考虑阅读 `如何有效地报告 + 缺陷 <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_ ， `如何 + 以明智的方å¼æé—® <http://www.catb.org/esr/faqs/smart-questions.html>`_ ， + å’Œ `如何æ出好问题 <https://jvns.ca/blog/good-questions/>`_ 。 + +解决这些问题之åŽï¼Œå¯ä»¥åœ¨ä¸‹é¢æ‰¾åˆ°å¦‚何æ£ç¡®åœ°å‘Linuxå†…æ ¸æŠ¥å‘Šé—®é¢˜çš„è¯¦ç»†ä¿¡æ¯ã€‚ + + +ç¡®ä¿æ‚¨ä½¿ç”¨çš„是上游Linuxå†…æ ¸ +---------------------------- + + *您是å¦é¢ä¸´ç¡¬ä»¶æˆ–软件供应商æ供的Linuxå†…æ ¸çš„é—®é¢˜ï¼Ÿé‚£ä¹ˆåŸºæœ¬ä¸Šæ‚¨æœ€å¥½åœæ¢é˜… + 读本文档，转而å‘您的供应商报告问题，除éžæ‚¨æ„¿æ„自己安装最新的Linux版本。 + 寻找和解决问题往往需è¦åŽè€…。* + +与大多数程åºå‘˜ä¸€æ ·ï¼ŒLinuxå†…æ ¸å¼€å‘人员ä¸å–œæ¬¢èŠ±æ—¶é—´å¤„ç†ä»–们维护的æºä»£ç ä¸æ ¹æœ¬ +ä¸ä¼šå‘生的问题的报告。这åªä¼šæµªè´¹æ¯ä¸ªäººçš„æ—¶é—´ï¼Œå°¤å…¶æ˜¯ä½ çš„æ—¶é—´ã€‚ä¸å¹¸çš„是，当 +涉åŠåˆ°å†…æ ¸æ—¶ï¼Œè¿™æ ·çš„æƒ…å†µå¾ˆå®¹æ˜“å‘生，并且常常导致åŒæ–¹æ°”é¦ã€‚è¿™æ˜¯å› ä¸ºå‡ ä¹Žæ‰€æœ‰é¢„ +装在设备（å°å¼æœºã€ç¬”记本电脑ã€æ™ºèƒ½æ‰‹æœºã€è·¯ç”±å™¨ç‰ï¼‰ä¸Šçš„Linuxå†…æ ¸ï¼Œä»¥åŠå¤§å¤šæ•° +ç”±Linuxå‘行商æä¾›çš„å†…æ ¸ï¼Œéƒ½ä¸Žç”±kernel.orgå‘行的官方Linuxå†…æ ¸ç›¸è·ç”šè¿œï¼šä»ŽLinux +å¼€å‘的角度æ¥çœ‹ï¼Œè¿™äº›ä¾›åº”商æä¾›çš„å†…æ ¸é€šå¸¸æ˜¯å¤è€çš„或者ç»è¿‡äº†å¤§é‡ä¿®æ”¹ï¼Œé€šå¸¸ä¸¤ç‚¹ +兼具。 + +å¤§å¤šæ•°ä¾›åº”å•†å†…æ ¸éƒ½ä¸é€‚åˆç”¨æ¥å‘Linuxå†…æ ¸å¼€å‘人员报告问题：您在其ä¸é‡åˆ°çš„问题 +å¯èƒ½å·²ç»ç”±Linuxå†…æ ¸å¼€å‘人员在数月或数年å‰ä¿®å¤ï¼›æ¤å¤–，供应商的修改和增强å¯èƒ½ +会导致您é¢ä¸´çš„问题，å³ä½¿å®ƒä»¬çœ‹èµ·æ¥å¾ˆå°æˆ–者完全ä¸ç›¸å…³ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆæ‚¨åº”è¯¥å‘ +ä¾›åº”å•†æŠ¥å‘Šè¿™äº›å†…æ ¸çš„é—®é¢˜ã€‚å®ƒçš„å¼€å‘者应该查看报告，如果它是一个上游问题，直接 +于上游修å¤æˆ–将报告转å‘到那里。在实践ä¸ï¼Œè¿™æœ‰æ—¶è¡Œä¸é€šã€‚å› æ¤ï¼Œæ‚¨å¯èƒ½éœ€è¦è€ƒè™‘ +通过自己安装最新的Linuxå†…æ ¸å†…æ ¸æ¥ç»•è¿‡ä¾›åº”商。如果如果您选择æ¤æ–¹æ³•ï¼Œé‚£ä¹ˆæœ¬æŒ‡ +å—åŽé¢çš„æ¥éª¤å°†è§£é‡Šå¦‚何在排除了其他å¯èƒ½å¯¼è‡´æ‚¨çš„é—®é¢˜çš„åŽŸå› åŽæ‰§è¡Œæ¤æ“作。 + +注æ„å‰æ®µä½¿ç”¨çš„è¯è¯æ˜¯â€œå¤§å¤šæ•°â€ï¼Œå› 为有时候开å‘人员实际上愿æ„处ç†ä¾›åº”å•†å†…æ ¸å‡ºçŽ° +的问题报告。他们是å¦è¿™ä¹ˆåšå¾ˆå¤§ç¨‹åº¦ä¸Šå–决于开å‘人员和相关问题。如果å‘è¡Œç‰ˆåª +æ ¹æ®æœ€è¿‘çš„Linuxç‰ˆæœ¬å¯¹å†…æ ¸è¿›è¡Œäº†è¾ƒå°ä¿®æ”¹ï¼Œé‚£ä¹ˆæœºä¼šå°±æ¯”较大；例如对于Debian +GNU/Linux Sid或Fedora Rawhide所æä¾›çš„ä¸»çº¿å†…æ ¸ã€‚ä¸€äº›å¼€å‘人员还将接å—基于最新 +ç¨³å®šå†…æ ¸çš„å‘è¡Œç‰ˆå†…æ ¸é—®é¢˜æŠ¥å‘Šï¼Œåªè¦å®ƒæ”¹åŠ¨ä¸å¤§ï¼›ä¾‹å¦‚Arch Linuxã€å¸¸è§„Fedora版本 +å’ŒopenSUSE Turboweed。但是请记ä½ï¼Œæ‚¨æœ€å¥½ä½¿ç”¨ä¸»çº¿Linux，并é¿å…在æ¤æµç¨‹ä¸ä½¿ç”¨ +ç¨³å®šç‰ˆå†…æ ¸ï¼Œå¦‚â€œå®‰è£…ä¸€ä¸ªæ–°çš„å†…æ ¸è¿›è¡Œæµ‹è¯•â€ä¸€èŠ‚ä¸æ‰€è¯¦è¿°ã€‚ + +当然，您å¯ä»¥å¿½ç•¥æ‰€æœ‰è¿™äº›å»ºè®®ï¼Œå¹¶å‘上游Linuxå¼€å‘人员报告旧的或ç»è¿‡å¤§é‡ä¿®æ”¹çš„ +ä¾›åº”å•†å†…æ ¸çš„é—®é¢˜ã€‚ä½†æ˜¯æ³¨æ„ï¼Œè¿™æ ·çš„æŠ¥å‘Šç»å¸¸è¢«æ‹’ç»æˆ–忽视，所以自行å°å¿ƒè€ƒè™‘一下。 +ä¸è¿‡è¿™è¿˜æ˜¯æ¯”æ ¹æœ¬ä¸æŠ¥å‘Šé—®é¢˜è¦å¥½ï¼šæœ‰æ—¶å€™è¿™æ ·çš„报告会直接或间接地帮助解决之åŽçš„ +问题。 + + +æœç´¢çŽ°æœ‰æŠ¥å‘Šï¼ˆç¬¬ä¸€éƒ¨åˆ†ï¼‰ +------------------------- + + *使用您喜爱的网络æœç´¢å¼•æ“Žå¯¹çŽ°æœ‰æŠ¥å‘Šè¿›è¡Œç²—ç•¥æœç´¢ï¼›æ¤å¤–，请检查Linuxå†…æ ¸ + 邮件列表（LKML）的å˜æ¡£ã€‚如果找到匹é…çš„æŠ¥å‘Šï¼Œè¯·åŠ å…¥è®¨è®ºè€Œä¸æ˜¯å‘é€æ–°æŠ¥å‘Šã€‚* + +报告一个别人已ç»æ出的问题，对æ¯ä¸ªäººæ¥è¯´éƒ½æ˜¯æµªè´¹æ—¶é—´ï¼Œå°¤å…¶æ˜¯ä½œä¸ºæŠ¥å‘Šäººçš„ä½ ã€‚ +所以彻底检查是å¦æœ‰äººå·²ç»æŠ¥å‘Šäº†è¿™ä¸ªé—®é¢˜ï¼Œè¿™å¯¹ä½ 自己是有利的。在æµç¨‹ä¸çš„这一æ¥ï¼Œ +å¯ä»¥åªæ‰§è¡Œä¸€ä¸ªç²—略的æœç´¢ï¼šä¸€æ—¦æ‚¨çŸ¥é“您的问题需è¦æŠ¥å‘Šåˆ°å“ªé‡Œï¼Œç¨åŽçš„æ¥éª¤å°†å‘Šè¯‰ +您如何详细æœç´¢ã€‚尽管如æ¤ï¼Œä¸è¦ä»“促完æˆè¿™ä¸€æ¥ï¼Œå®ƒå¯ä»¥èŠ‚çœæ‚¨çš„时间和å‡å°‘麻烦。 + +åªéœ€å…ˆç”¨ä½ 最喜欢的æœç´¢å¼•æ“Žåœ¨äº’è”网上æœç´¢ã€‚然åŽå†æœç´¢Linuxå†…æ ¸é‚®ä»¶åˆ—è¡¨ï¼ˆLKML） +å˜æ¡£ã€‚ + +如果æœç´¢ç»“果实在太多，å¯ä»¥è€ƒè™‘è®©ä½ çš„æœç´¢å¼•æ“Žå°†æœç´¢æ—¶é—´èŒƒå›´é™åˆ¶åœ¨è¿‡åŽ»çš„一个 +æœˆæˆ–ä¸€å¹´ã€‚è€Œä¸”æ— è®ºä½ åœ¨å“ªé‡Œæœç´¢ï¼Œä¸€å®šè¦ç”¨æ°å½“çš„æœç´¢å…³é”®è¯ï¼›ä¹Ÿè¦å˜åŒ–å‡ æ¬¡å…³é”® +è¯ã€‚åŒæ—¶ï¼Œè¯•ç€ä»Žåˆ«äººçš„è§’åº¦çœ‹é—®é¢˜ï¼šè¿™å°†å¸®åŠ©ä½ æƒ³å‡ºå…¶ä»–çš„å…³é”®è¯ã€‚å¦å¤–ï¼Œä¸€å®šä¸ +è¦åŒæ—¶ä½¿ç”¨è¿‡å¤šçš„关键è¯ã€‚è®°ä½æœç´¢æ—¶è¦åŒæ—¶å°è¯•åŒ…å«å’Œä¸åŒ…å«å†…æ ¸é©±åŠ¨ç¨‹åºçš„å称 +或å—å½±å“的硬件组件的å称ç‰ä¿¡æ¯ã€‚但其确切的å“牌å称（比如说“åŽç¡•çº¢é” Radeon +RX 5700 XT Gaming OCâ€ï¼‰å¾€å¾€å¸®åŠ©ä¸å¤§ï¼Œå› 为它太具体了。相å，å°è¯•æœç´¢æœ¯è¯ï¼Œå¦‚ +åž‹å·ï¼ˆRadeon 5700 或 Radeon 5000ï¼‰å’Œæ ¸å¿ƒä»£å·ï¼ˆâ€œNaviâ€æˆ–“Navi10â€ï¼‰ï¼Œä»¥åŠåŒ…å« +å’Œä¸åŒ…å«å…¶åˆ¶é€ 商（“AMDâ€ï¼‰ã€‚ + +å¦‚æžœä½ å‘çŽ°äº†å…³äºŽä½ çš„é—®é¢˜çš„çŽ°æœ‰æŠ¥å‘Šï¼Œè¯·åŠ å…¥è®¨è®ºï¼Œå› ä¸ºä½ å¯èƒ½ä¼šæä¾›æœ‰ä»·å€¼çš„é¢ +外信æ¯ã€‚这一点很é‡è¦ï¼Œå³ä½¿æ˜¯åœ¨ä¿®å¤ç¨‹åºå·²ç»å‡†å¤‡å¥½æˆ–处于最åŽé˜¶æ®µï¼Œå› 为开å‘人 +员å¯èƒ½ä¼šå¯»æ‰¾èƒ½å¤Ÿæä¾›é¢å¤–ä¿¡æ¯æˆ–测试建议修å¤ç¨‹åºçš„人。跳到“å‘布报告åŽçš„责任†+一节，了解有关如何æ£ç¡®å‚与的细节。 + +注æ„，æœç´¢ `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 网站å¯èƒ½ +也是一个好主æ„ï¼Œå› ä¸ºè¿™å¯èƒ½ä¼šæ供有价值的è§è§£æˆ–找到匹é…的报告。如果您å‘现åŽè€…， +请记ä½ï¼šå¤§å¤šæ•°å系统都希望在ä¸åŒçš„ä½ç½®æŠ¥å‘Šï¼Œå¦‚下é¢â€œä½ 需è¦å°†é—®é¢˜æŠ¥å‘Šåˆ°ä½•å¤„†+一节ä¸æ‰€è¿°ã€‚å› æ¤æœ¬åº”处ç†è¿™ä¸ªé—®é¢˜çš„å¼€å‘人员甚至å¯èƒ½ä¸çŸ¥é“bugzillaçš„å·¥å•ã€‚所以 +请检查工å•ä¸çš„问题是å¦å·²ç»æŒ‰ç…§æœ¬æ–‡æ¡£æ‰€è¿°å¾—åˆ°æŠ¥å‘Šï¼Œå¦‚æžœæ²¡æœ‰ï¼Œè¯·è€ƒè™‘è¿™æ ·åšã€‚ + +高优先级的问题？ +----------------- + + *çœ‹çœ‹ä½ æ£åœ¨å¤„ç†çš„问题是å¦æ˜¯å›žå½’问题ã€å®‰å…¨é—®é¢˜æˆ–éžå¸¸ä¸¥é‡çš„问题：这些都是 + 需è¦åœ¨æŽ¥ä¸‹æ¥çš„一些æ¥éª¤ä¸ç‰¹åˆ«å¤„ç†çš„“高优先级问题â€ã€‚* + +Linus Torvalds和主è¦çš„Linuxå†…æ ¸å¼€å‘äººå‘˜å¸Œæœ›çœ‹åˆ°ä¸€äº›é—®é¢˜å°½å¿«å¾—åˆ°è§£å†³ï¼Œå› æ¤åœ¨ +报告过程ä¸æœ‰ä¸€äº›â€œé«˜ä¼˜å…ˆçº§é—®é¢˜â€çš„处ç†ç•¥æœ‰ä¸åŒã€‚有三ç§æƒ…况符åˆæ¡ä»¶:回归ã€å®‰å…¨ +问题和éžå¸¸ä¸¥é‡çš„问题。 + +如果在旧版本的Linuxå†…æ ¸ä¸å·¥ä½œçš„东西ä¸èƒ½åœ¨æ–°ç‰ˆæœ¬çš„Linuxå†…æ ¸ä¸å·¥ä½œï¼Œæˆ–者æŸç§ +程度上在新版本的Linuxå†…æ ¸ä¸å·¥ä½œå¾—æ›´å·®ï¼Œé‚£ä¹ˆä½ å°±éœ€è¦å¤„ç†â€œå›žå½’â€ã€‚å› æ¤ï¼Œå½“一个 +在Linux 5.7ä¸è¡¨çŽ°è‰¯å¥½çš„WiFi驱动程åºåœ¨5.8ä¸è¡¨çŽ°ä¸ä½³æˆ–æ ¹æœ¬ä¸èƒ½å·¥ä½œæ—¶ï¼Œè¿™æ˜¯ä¸€ +ç§å›žå½’。如果应用程åºåœ¨æ–°çš„å†…æ ¸ä¸å‡ºçŽ°ä¸ç¨³å®šçš„现象，这也是一ç§å›žå½’，这å¯èƒ½æ˜¯ +ç”±äºŽå†…æ ¸å’Œç”¨æˆ·ç©ºé—´ä¹‹é—´çš„æŽ¥å£ï¼ˆå¦‚procfså’Œsysfs）å‘生ä¸å…¼å®¹çš„æ›´æ”¹é€ æˆçš„。显著 +的性能é™ä½Žæˆ–åŠŸè€—å¢žåŠ ä¹Ÿå¯ä»¥ç§°ä¸ºå›žå½’。但是请记ä½:æ–°å†…æ ¸éœ€è¦ä½¿ç”¨ä¸Žæ—§å†…æ ¸ç›¸ä¼¼çš„ +é…ç½®æ¥æž„建（å‚è§ä¸‹é¢å¦‚ä½•å®žçŽ°è¿™ä¸€ç‚¹ï¼‰ã€‚è¿™æ˜¯å› ä¸ºå†…æ ¸å¼€å‘人员在实现新特性时有 +æ—¶æ— æ³•é¿å…ä¸å…¼å®¹æ€§ï¼›ä½†æ˜¯ä¸ºäº†é¿å…回归，这些特性必须在构建é…置期间显å¼åœ°å¯ç”¨ã€‚ + +什么是安全问题留给您自己判æ–。在继ç»ä¹‹å‰ï¼Œè¯·è€ƒè™‘阅读 +“Documentation/translations/zh_CN/admin-guide/security-bugs.rstâ€ï¼Œ +å› ä¸ºå®ƒæ供了如何最æ°å½“地处ç†å®‰å…¨é—®é¢˜çš„é¢å¤–细节。 + +当å‘ç”Ÿäº†å®Œå…¨æ— æ³•æŽ¥å—的糟糕事情时，æ¤é—®é¢˜å°±æ˜¯ä¸€ä¸ªâ€œéžå¸¸ä¸¥é‡çš„问题â€ã€‚例如， +Linuxå†…æ ¸ç ´å了它处ç†çš„æ•°æ®æˆ–æŸå了它è¿è¡Œçš„ç¡¬ä»¶ã€‚å½“å†…æ ¸çªç„¶æ˜¾ç¤ºé”™è¯¯æ¶ˆæ¯ +（“kernel panicâ€ï¼‰å¹¶åœæ¢å·¥ä½œï¼Œæˆ–è€…æ ¹æœ¬æ²¡æœ‰ä»»ä½•åœæ¢ä¿¡æ¯æ—¶ï¼Œæ‚¨ä¹Ÿåœ¨å¤„ç†ä¸€ä¸ªä¸¥é‡ +的问题。注æ„：ä¸è¦æ··æ·†â€œpanicâ€ï¼ˆå†…æ ¸åœæ¢è‡ªèº«çš„致命错误）和“Oopsâ€ï¼ˆå¯æ¢å¤é”™è¯¯ï¼‰ï¼Œ +å› ä¸ºæ˜¾ç¤ºåŽè€…之åŽå†…æ ¸ä»ç„¶åœ¨è¿è¡Œã€‚ + + +ç¡®ä¿çŽ¯å¢ƒå¥åº· +-------------- + + *ç¡®ä¿ä¸æ˜¯å†…æ ¸æ‰€å¤„çŽ¯å¢ƒå¯¼è‡´äº†ä½ æ‰€é¢ä¸´çš„问题。* + +看起æ¥å¾ˆåƒå†…æ ¸é—®é¢˜çš„é—®é¢˜æœ‰æ—¶æ˜¯ç”±æž„å»ºæˆ–è¿è¡Œæ—¶çŽ¯å¢ƒå¼•èµ·çš„。很难完全排除这ç§é—® +é¢˜ï¼Œä½†ä½ åº”è¯¥å°½é‡å‡å°‘è¿™ç§é—®é¢˜ï¼š + + * æž„å»ºå†…æ ¸æ—¶ï¼Œè¯·ä½¿ç”¨ç»è¿‡éªŒè¯çš„å·¥å…·ï¼Œå› ä¸ºç¼–è¯‘å™¨æˆ–äºŒè¿›åˆ¶æ–‡ä»¶ä¸çš„错误å¯èƒ½ä¼šå¯¼ + è‡´å†…æ ¸å‡ºçŽ°é”™è¯¯è¡Œä¸ºã€‚ + + * ç¡®ä¿æ‚¨çš„计算机组件在其设计规范内è¿è¡Œï¼›è¿™å¯¹å¤„ç†å™¨ã€å†…å˜å’Œä¸»æ¿å°¤ä¸ºé‡è¦ã€‚å› + æ¤ï¼Œå½“é¢ä¸´æ½œåœ¨çš„å†…æ ¸é—®é¢˜æ—¶ï¼Œåœæ¢ä½Žç”µåŽ‹æˆ–超频。 + + * å°½é‡ç¡®ä¿ä¸æ˜¯ç¡¬ä»¶æ•…éšœå¯¼è‡´äº†ä½ çš„é—®é¢˜ã€‚ä¾‹å¦‚ï¼Œå†…å˜æŸå会导致大é‡çš„问题，这些 + 问题会表现为看起æ¥åƒå†…æ ¸é—®é¢˜ã€‚ + + * å¦‚æžœä½ æ£åœ¨å¤„ç†ä¸€ä¸ªæ–‡ä»¶ç³»ç»Ÿé—®é¢˜ï¼Œä½ å¯èƒ½éœ€è¦ç”¨ ``fsck`` 检查一下文件系统， + å› ä¸ºå®ƒå¯èƒ½ä¼šä»¥æŸç§æ–¹å¼è¢«æŸåï¼Œä»Žè€Œå¯¼è‡´æ— æ³•é¢„æœŸçš„å†…æ ¸è¡Œä¸ºã€‚ + + * 在处ç†å›žå½’问题时，è¦ç¡®ä¿æ²¡æœ‰åœ¨æ›´æ–°å†…æ ¸çš„åŒæ—¶å‘生了其他å˜åŒ–。例如，这个问 + 题å¯èƒ½æ˜¯ç”±åŒæ—¶æ›´æ–°çš„其他软件引起的。也有å¯èƒ½æ˜¯åœ¨ä½ 第一次é‡å¯è¿›å…¥æ–°å†…æ ¸æ—¶ï¼Œ + æŸä¸ªç¡¬ä»¶å·§åˆåœ°å了。更新系统 BIOS æˆ–æ”¹å˜ BIOS 设置ä¸çš„æŸäº›å†…容也会导致 + 一些看起æ¥å¾ˆåƒå†…æ ¸å›žå½’çš„é—®é¢˜ã€‚ + + +为紧急情况åšå¥½å‡†å¤‡ +------------------- + + *创建一个全新的备份，并将系统修å¤å’Œè¿˜åŽŸå·¥å…·æ”¾åœ¨æ‰‹è¾¹* + +我得æ醒您，您æ£åœ¨å’Œè®¡ç®—机打交é“，计算机有时会出现æ„想ä¸åˆ°çš„事情，尤其是当 +您折腾其æ“ä½œç³»ç»Ÿçš„å†…æ ¸ç‰å…³é”®éƒ¨ä»¶æ—¶ã€‚è€Œè¿™å°±æ˜¯ä½ åœ¨è¿™ä¸ªè¿‡ç¨‹ä¸è¦åšçš„äº‹æƒ…ã€‚å› æ¤ï¼Œ +一定è¦åˆ›å»ºä¸€ä¸ªå…¨æ–°çš„备份；还è¦ç¡®ä¿ä½ 手头有修å¤æˆ–é‡è£…æ“作系统的所有工具， +以åŠæ¢å¤å¤‡ä»½æ‰€éœ€çš„一切。 + + +ç¡®ä¿ä½ çš„å†…æ ¸ä¸ä¼šè¢«å¢žå¼º +------------------------ + + *ç¡®ä¿æ‚¨çš„系统ä¸ä¼šé€šè¿‡åŠ¨æ€æž„建é¢å¤–çš„å†…æ ¸æ¨¡å—æ¥å¢žå¼ºå…¶å†…æ ¸ï¼ŒåƒDKMSè¿™æ ·çš„è§£ + 决方案å¯èƒ½åœ¨æ‚¨ä¸çŸ¥æƒ…çš„æƒ…å†µä¸‹å°±åœ¨æœ¬åœ°è¿›è¡Œäº†è¿™æ ·çš„å·¥ä½œã€‚* + +å¦‚æžœå†…æ ¸ä»¥ä»»ä½•æ–¹å¼å¾—到增强，那么问题报告被忽略或拒ç»çš„é£Žé™©å°±ä¼šæ€¥å‰§å¢žåŠ ã€‚è¿™å°± +æ˜¯ä¸ºä»€ä¹ˆæ‚¨åº”è¯¥åˆ é™¤æˆ–ç¦ç”¨åƒakmodså’ŒDKMSè¿™æ ·çš„æœºåˆ¶ï¼šè¿™äº›æœºåˆ¶ä¼šè‡ªåŠ¨æž„å»ºé¢å¤–å†…æ ¸ +模å—，例如当您安装新的Linuxå†…æ ¸æˆ–ç¬¬ä¸€æ¬¡å¼•å¯¼å®ƒæ—¶ã€‚ä¹Ÿè¦è®°å¾—åŒæ—¶åˆ 除他们å¯èƒ½å®‰è£… +的任何模å—。然åŽé‡æ–°å¯åŠ¨å†ç»§ç»ã€‚ + +注æ„ï¼Œä½ å¯èƒ½ä¸çŸ¥é“ä½ çš„ç³»ç»Ÿæ£åœ¨ä½¿ç”¨è¿™äº›è§£å†³æ–¹æ¡ˆä¹‹ä¸€ï¼šå½“ä½ å®‰è£… Nvidia 专有图 +形驱动程åºã€VirtualBox æˆ–å…¶ä»–éœ€è¦ Linux å†…æ ¸ä»¥å¤–çš„æ¨¡å—支æŒçš„软件时，它们通 +常会é™é»˜è®¾ç½®ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ å¯èƒ½éœ€è¦å¸è½½è¿™äº›è½¯ä»¶çš„软件包，以摆脱任何第三方 +å†…æ ¸æ¨¡å—。 + + +检查“污染â€æ ‡å¿— +---------------- + + *当问题å‘ç”Ÿæ—¶ï¼Œæ£€æŸ¥æ‚¨çš„å†…æ ¸æ˜¯å¦è¢«â€œæ±¡æŸ“â€ï¼Œå› ä¸ºä½¿å†…æ ¸è®¾ç½®è¿™ä¸ªæ ‡å¿—çš„äº‹ä»¶å¯ + 能会导致您é¢ä¸´çš„问题。* + +当æŸäº›å¯èƒ½ä¼šå¯¼è‡´çœ‹èµ·æ¥å®Œå…¨ä¸ç›¸å…³çš„åŽç»é”™è¯¯çš„事情å‘ç”Ÿæ—¶ï¼Œå†…æ ¸ä¼šç”¨â€œæ±¡æŸ“ +（taint）â€æ ‡å¿—æ ‡è®°è‡ªå·±ã€‚å¦‚æžœæ‚¨çš„å†…æ ¸å—到污染，那么您é¢ä¸´çš„å¯èƒ½æ˜¯è¿™æ ·çš„错误。 +å› æ¤åœ¨æŠ•å…¥æ›´å¤šæ—¶é—´åˆ°è¿™ä¸ªè¿‡ç¨‹ä¸ä¹‹å‰ï¼Œå°½æ—©æŽ’除æ¤æƒ…况å¯èƒ½å¯¹ä½ 有好处。这是这个 +æ¥éª¤å‡ºçŽ°åœ¨è¿™é‡Œçš„å”¯ä¸€åŽŸå› ï¼Œå› ä¸ºè¿™ä¸ªè¿‡ç¨‹ç¨åŽä¼šå‘Šè¯‰æ‚¨å®‰è£…æœ€æ–°çš„ä¸»çº¿å†…æ ¸ï¼›ç„¶åŽ +您将需è¦å†æ¬¡æ£€æŸ¥æ±¡æŸ“æ ‡å¿—ï¼Œå› ä¸ºå½“å®ƒå‡ºé—®é¢˜çš„æ—¶å€™å†…æ ¸æŠ¥å‘Šä¼šå…³æ³¨å®ƒã€‚ + +在æ£åœ¨è¿è¡Œçš„ç³»ç»Ÿä¸Šæ£€æŸ¥å†…æ ¸æ˜¯å¦æ±¡æŸ“éžå¸¸å®¹æ˜“：如果 ``cat /proc/sys/kernel/tainted`` +返回“0â€ï¼Œé‚£ä¹ˆå†…æ ¸æ²¡æœ‰è¢«æ±¡æŸ“ï¼Œä¸€åˆ‡æ£å¸¸ã€‚在æŸäº›æƒ…å†µä¸‹æ— æ³•æ£€æŸ¥è¯¥æ–‡ä»¶ï¼›è¿™å°±æ˜¯ +ä¸ºä»€ä¹ˆå½“å†…æ ¸æŠ¥å‘Šå†…éƒ¨é—®é¢˜ï¼ˆâ€œkernel bugâ€ï¼‰ã€å¯æ¢å¤é”™è¯¯ï¼ˆâ€œkernel Oopsâ€ï¼‰æˆ–åœæ¢ +æ“作å‰ä¸å¯æ¢å¤çš„错误（“kernel panicâ€ï¼‰æ—¶ï¼Œå®ƒä¹Ÿä¼šæ到污染状æ€ã€‚当其ä¸ä¸€ä¸ªé”™ +误å‘生时，查看打å°çš„错误消æ¯çš„顶部，æœç´¢ä»¥â€œCPU:â€å¼€å¤´çš„行。如果å‘现问题时内 +æ ¸æœªè¢«æ±¡æŸ“ï¼Œé‚£ä¹ˆå®ƒåº”è¯¥ä»¥â€œNot infectedâ€ç»“æŸï¼›å¦‚æžœä½ çœ‹åˆ°â€œTainted:â€ä¸”åŽè·Ÿä¸€äº› +ç©ºæ ¼å’Œå—æ¯ï¼Œé‚£å°±è¢«æ±¡æŸ“了。 + +å¦‚æžœä½ çš„å†…æ ¸è¢«æ±¡æŸ“äº†ï¼Œè¯·é˜…è¯»â€œDocumentation/translations/zh_CN/admin-guide/tainted-kernels.rst†+ä»¥æ‰¾å‡ºåŽŸå› ã€‚è®¾æ³•æ¶ˆé™¤æ±¡æŸ“å› ç´ ã€‚é€šå¸¸æ˜¯ç”±ä»¥ä¸‹ä¸‰ç§å› ç´ ä¹‹ä¸€å¼•èµ·çš„ï¼š + + 1. å‘生了一个å¯æ¢å¤çš„错误（“kernel Oopsâ€ï¼‰ï¼Œå†…æ ¸æ±¡æŸ“äº†è‡ªå·±ï¼Œå› ä¸ºå†…æ ¸çŸ¥é“在 + æ¤ä¹‹åŽå®ƒå¯èƒ½ä¼šå‡ºçŽ°å¥‡æ€ªçš„行为错乱。在这ç§æƒ…å†µä¸‹ï¼Œæ£€æŸ¥æ‚¨çš„å†…æ ¸æˆ–ç³»ç»Ÿæ—¥å¿—ï¼Œ + 并寻找以下列文å—开头的部分:: + + Oops: 0000 [#1] SMP + + 如方括å·ä¸çš„“#1â€æ‰€ç¤ºï¼Œè¿™æ˜¯è‡ªå¯åŠ¨ä»¥æ¥çš„第一次Oops。æ¯ä¸ªOopså’Œæ¤åŽå‘生的 + 任何其他问题都å¯èƒ½æ˜¯é¦–个Oopsçš„åŽç»é—®é¢˜ï¼Œå³ä½¿è¿™ä¸¤ä¸ªé—®é¢˜çœ‹èµ·æ¥å®Œå…¨ä¸ç›¸å…³ã€‚ + 通过消除首个Oopsçš„åŽŸå› å¹¶åœ¨ä¹‹åŽå¤çŽ°è¯¥é—®é¢˜ï¼Œå¯ä»¥æŽ’除这ç§æƒ…况。有时仅仅 + é‡æ–°å¯åŠ¨å°±è¶³å¤Ÿäº†ï¼Œæœ‰æ—¶æ›´æ”¹é…ç½®åŽé‡æ–°å¯åŠ¨å¯ä»¥æ¶ˆé™¤Oops。但是在这个æµç¨‹ä¸ + ä¸è¦èŠ±è´¹å¤ªå¤šæ—¶é—´åœ¨è¿™ä¸€ç‚¹ä¸Šï¼Œå› 为引起Oopsçš„åŽŸå› å¯èƒ½å·²ç»åœ¨æ‚¨ç¨åŽå°†æŒ‰æµç¨‹ + 安装的新Linuxå†…æ ¸ç‰ˆæœ¬ä¸ä¿®å¤äº†ã€‚ + + 2. æ‚¨çš„ç³»ç»Ÿä½¿ç”¨çš„è½¯ä»¶å®‰è£…äº†è‡ªå·±çš„å†…æ ¸æ¨¡å—，例如Nvidia的专有图形驱动程åºæˆ– + VirtualBoxã€‚å½“å†…æ ¸ä»Žå¤–éƒ¨æºï¼ˆå³ä½¿å®ƒä»¬æ˜¯å¼€æºçš„ï¼‰åŠ è½½æ¤ç±»æ¨¡å—时，它会污染 + 自己：它们有时会在ä¸ç›¸å…³çš„å†…æ ¸åŒºåŸŸå¯¼è‡´é”™è¯¯ï¼Œä»Žè€Œå¯èƒ½å¯¼è‡´æ‚¨é¢ä¸´çš„问题。 + å› æ¤ï¼Œå½“您想è¦å‘Linuxå†…æ ¸å¼€å‘人员报告问题时，您必须阻æ¢è¿™äº›æ¨¡å—åŠ è½½ã€‚ + 大多数情况下最简å•çš„方法是：临时å¸è½½è¿™äº›è½¯ä»¶ï¼ŒåŒ…括它们å¯èƒ½å·²ç»å®‰è£…çš„ä»» + 何模å—。之åŽé‡æ–°å¯åŠ¨ã€‚ + + 3. å½“å†…æ ¸åŠ è½½é©»ç•™åœ¨Linuxå†…æ ¸æºä»£ç stagingæ ‘ä¸çš„模å—时，它也会污染自身。这 + 是一个特殊的区域，代ç （主è¦æ˜¯é©±åŠ¨ç¨‹åºï¼‰è¿˜æ²¡æœ‰è¾¾åˆ°æ£å¸¸Linuxå†…æ ¸çš„è´¨é‡ + æ ‡å‡†ã€‚å½“æ‚¨æŠ¥å‘Šæ¤ç§æ¨¡å—çš„é—®é¢˜æ—¶ï¼Œå†…æ ¸å—到污染显然是没有问题的；åªéœ€ç¡®ä¿ + 问题模å—æ˜¯é€ æˆæ±¡æŸ“çš„å”¯ä¸€åŽŸå› ã€‚å¦‚æžœé—®é¢˜å‘生在一个ä¸ç›¸å…³çš„区域，é‡æ–°å¯åŠ¨ + 并通过指定 ``foo.blacklist=1`` ä½œä¸ºå†…æ ¸å‚数临时阻æ¢è¯¥æ¨¡å—è¢«åŠ è½½ï¼ˆç”¨æœ‰ + 问题的模å—å替æ¢â€œfooâ€ï¼‰ã€‚ + + +记录如何é‡çŽ°é—®é¢˜ +------------------ + + *粗略地写下如何é‡çŽ°è¿™ä¸ªé—®é¢˜ã€‚如果您åŒæ—¶å¤„ç†å¤šä¸ªé—®é¢˜ï¼Œè¯·ä¸ºæ¯ä¸ªé—®é¢˜å•ç‹¬å†™ + 注释，并确ä¿å®ƒä»¬åœ¨æ–°å¯åŠ¨çš„系统上独立出现。这是必è¦çš„ï¼Œå› ä¸ºæ¯ä¸ªé—®é¢˜éƒ½éœ€ + è¦åˆ†åˆ«æŠ¥å‘Šç»™å†…æ ¸å¼€å‘人员，除éžå®ƒä»¬ä¸¥é‡çº ç¼ åœ¨ä¸€èµ·ã€‚* + +å¦‚æžœä½ åŒæ—¶å¤„ç†å¤šä¸ªé—®é¢˜ï¼Œå¿…须分别报告æ¯ä¸ªé—®é¢˜ï¼Œå› 为它们å¯èƒ½ç”±ä¸åŒçš„å¼€å‘人员 +处ç†ã€‚在一份报告ä¸æ述多ç§é—®é¢˜ï¼Œä¹Ÿä¼šè®©å…¶ä»–äººéš¾ä»¥å°†å…¶åˆ†å¼€ã€‚å› æ¤åªæœ‰åœ¨é—®é¢˜ä¸¥ +é‡çº ç¼ çš„æƒ…å†µä¸‹ï¼Œæ‰èƒ½å°†é—®é¢˜åˆå¹¶åœ¨ä¸€ä»½æŠ¥å‘Šä¸ã€‚ + +æ¤å¤–，在报告过程ä¸ï¼Œä½ 必须测试该问题是å¦å‘ç”Ÿåœ¨å…¶ä»–å†…æ ¸ç‰ˆæœ¬ä¸Šã€‚å› æ¤ï¼Œå¦‚果您 +知é“如何在一个新å¯åŠ¨çš„系统上快速é‡çŽ°é—®é¢˜ï¼Œå°†ä½¿æ‚¨çš„å·¥ä½œæ›´åŠ è½»æ¾ã€‚ + +注æ„：报告åªå‘ç”Ÿè¿‡ä¸€æ¬¡çš„é—®é¢˜å¾€å¾€æ˜¯æ²¡æœ‰ç»“æžœçš„ï¼Œå› ä¸ºå®ƒä»¬å¯èƒ½æ˜¯ç”±äºŽå®‡å®™è¾å°„导 +致的ä½ç¿»è½¬ã€‚æ‰€ä»¥ä½ åº”è¯¥å°è¯•é€šè¿‡é‡çŽ°é—®é¢˜æ¥æŽ’除这ç§æƒ…况，然åŽå†ç»§ç»ã€‚å¦‚æžœä½ æœ‰ +足够的ç»éªŒæ¥åŒºåˆ†ç”±äºŽç¡¬ä»¶æ•…障引起的一次性错误和难以é‡çŽ°çš„罕è§å†…æ ¸é—®é¢˜ï¼Œå¯ä»¥ +忽略这个建议。 + + +稳定版或长期支æŒå†…æ ¸çš„å›žå½’ï¼Ÿ +----------------------------- + + *如果您æ£é¢ä¸´ç¨³å®šç‰ˆæˆ–长期支æŒç‰ˆæœ¬çº¿çš„回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看åŽæ–‡â€œæŠ¥å‘Šç¨³å®šç‰ˆå’Œé•¿æœŸæ”¯æŒå†…æ ¸çº¿çš„å›žå½’â€å°èŠ‚。* + +稳定版和长期支æŒå†…æ ¸ç‰ˆæœ¬çº¿ä¸çš„回归是Linuxå¼€å‘人员éžå¸¸å¸Œæœ›è§£å†³çš„é—®é¢˜ï¼Œè¿™æ ·çš„ +问题甚至比主线开å‘分支ä¸çš„回归更ä¸åº”å‡ºçŽ°ï¼Œå› ä¸ºå®ƒä»¬ä¼šå¾ˆå¿«å½±å“到很多人。开å‘人员 +希望尽快了解æ¤ç±»é—®é¢˜ï¼Œå› æ¤æœ‰ä¸€ä¸ªç®€åŒ–æµç¨‹æ¥æŠ¥å‘Šè¿™äº›é—®é¢˜ã€‚注æ„ï¼Œä½¿ç”¨æ›´æ–°å†…æ ¸ç‰ˆ +本线的回归（比如从5.9.15切æ¢åˆ°5.10.5时出现故障）ä¸ç¬¦åˆæ¡ä»¶ã€‚ + + +ä½ éœ€è¦å°†é—®é¢˜æŠ¥å‘Šåˆ°ä½•å¤„ +------------------------ + + *定ä½å¯èƒ½å¼•èµ·é—®é¢˜çš„驱动程åºæˆ–å†…æ ¸å系统。找出其开å‘äººå‘˜æœŸæœ›çš„æŠ¥å‘Šçš„æ–¹å¼ + å’Œä½ç½®ã€‚注æ„：大多数情况下ä¸ä¼šæ˜¯bugzilla.kernel.orgï¼Œå› ä¸ºé—®é¢˜é€šå¸¸éœ€è¦é€š + 过邮件å‘é€ç»™ç»´æŠ¤äººå‘˜å’Œå…¬å…±é‚®ä»¶åˆ—表。* + +将报告å‘é€ç»™åˆé€‚的人是至关é‡è¦çš„ï¼Œå› ä¸ºLinuxå†…æ ¸æ˜¯ä¸€ä¸ªå¤§é¡¹ç›®ï¼Œå¤§å¤šæ•°å¼€å‘人员 +åªç†Ÿæ‚‰å…¶ä¸çš„一å°éƒ¨åˆ†ã€‚例如，相当多的程åºå‘˜åªå…³å¿ƒä¸€ä¸ªé©±åŠ¨ç¨‹åºï¼Œæ¯”如一个WiFi +芯片驱动程åºï¼›å®ƒçš„å¼€å‘人员å¯èƒ½å¯¹ç–远的或ä¸ç›¸å…³çš„“å系统â€ï¼ˆå¦‚TCPå †æ ˆã€ +PCIe/PCIå系统ã€å†…å˜ç®¡ç†æˆ–文件系统）的内部知识了解很少或完全ä¸äº†è§£ã€‚ + +问题在于：Linuxå†…æ ¸ç¼ºå°‘ä¸€ä¸ªï¼Œå¯ä»¥ç®€å•åœ°å°†é—®é¢˜å½’档并让需è¦äº†è§£å®ƒçš„å¼€å‘人员了 +解它的，ä¸å¿ƒåŒ–ç¼ºé™·è·Ÿè¸ªå™¨ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ å¿…é¡»æ‰¾åˆ°æ£ç¡®çš„途径æ¥è‡ªå·±æŠ¥å‘Šé—®é¢˜ã€‚ +您å¯ä»¥åœ¨è„šæœ¬çš„帮助下åšåˆ°è¿™ä¸€ç‚¹ï¼ˆè§ä¸‹æ–‡ï¼‰ï¼Œä½†å®ƒä¸»è¦é’ˆå¯¹çš„æ˜¯å†…æ ¸å¼€å‘人员和专 +家。对于其他人æ¥è¯´ï¼ŒMAINTAINERS（维护人员）文件是更好的选择。 + +如何阅读MAINTAINERS维护者文件 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +为了说明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，让我们å‡è®¾æ‚¨çš„笔记 +本电脑ä¸çš„WiFiåœ¨æ›´æ–°å†…æ ¸åŽçªç„¶å‡ºçŽ°äº†é”™è¯¯è¡Œä¸ºã€‚è¿™ç§æƒ…况下å¯èƒ½æ˜¯WiFi驱动的问 +题。显然，它也å¯èƒ½ç”±äºŽé©±åŠ¨åŸºäºŽçš„æŸäº›ä»£ç ，但除éžä½ æ€€ç–‘æœ‰è¿™æ ·çš„ä¸œè¥¿ä¼šé™„ç€åœ¨ +驱动程åºä¸Šã€‚如果真的是其他的问题，驱动程åºçš„å¼€å‘人员会让åˆé€‚的人å‚与进æ¥ã€‚ + +é—憾的是，没有通用且简å•çš„办法æ¥æ£€æŸ¥å“ªä¸ªä»£ç 驱动了特定硬件组件。 + +在WiFié©±åŠ¨å‡ºçŽ°é—®é¢˜çš„æƒ…å†µä¸‹ï¼Œä½ å¯èƒ½æƒ³æŸ¥çœ‹ ``lspci -k`` çš„è¾“å‡ºï¼Œå› ä¸ºå®ƒåˆ—å‡ºäº† +PCI/PCIeæ€»çº¿ä¸Šçš„è®¾å¤‡å’Œé©±åŠ¨å®ƒçš„å†…æ ¸æ¨¡å—:: + + [user@something ~]$ lspci -k + [...] + 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32) + Subsystem: Bigfoot Networks, Inc. Device 1535 + Kernel driver in use: ath10k_pci + Kernel modules: ath10k_pci + [...] + +ä½†å¦‚æžœä½ çš„WiFi芯片通过USB或其他内部总线连接，这ç§æ–¹æ³•å°±è¡Œä¸é€šäº†ã€‚在这ç§æƒ…况 +下，您å¯èƒ½éœ€è¦æ£€æŸ¥æ‚¨çš„WiFi管ç†å™¨æˆ– ``ip link`` çš„è¾“å‡ºã€‚å¯»æ‰¾æœ‰é—®é¢˜çš„ç½‘ç»œæŽ¥å£ +çš„å称，它å¯èƒ½ç±»ä¼¼äºŽâ€œwlp58s0â€ã€‚æ¤å称å¯ä»¥ç”¨æ¥æ‰¾åˆ°é©±åŠ¨å®ƒçš„模å—:: + + [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module + ath10k_pci + +如果这些技巧ä¸èƒ½è¿›ä¸€æ¥å¸®åŠ©æ‚¨ï¼Œè¯·å°è¯•åœ¨ç½‘上æœç´¢å¦‚何缩å°ç›¸å…³é©±åŠ¨ç¨‹åºæˆ–å系统 +çš„èŒƒå›´ã€‚å¦‚æžœä½ ä¸ç¡®å®šæ˜¯å“ªä¸€ä¸ªï¼šè¯•ç€çŒœä¸€ä¸‹ï¼Œå³ä½¿ä½ 猜得ä¸å¥½ï¼Œä¹Ÿä¼šæœ‰äººä¼šå¸®åŠ©ä½ +的。 + +一旦您知é“了相应的驱动程åºæˆ–å系统，您就希望在MAINTAINERS文件ä¸æœç´¢å®ƒã€‚如果 +是“ath10k_pciâ€ï¼Œæ‚¨ä¸ä¼šæ‰¾åˆ°ä»»ä½•ä¸œè¥¿ï¼Œå› 为åç§°å¤ªå…·ä½“äº†ã€‚æœ‰æ—¶ä½ éœ€è¦åœ¨ç½‘上寻找 +帮助；但在æ¤ä¹‹å‰ï¼Œè¯·å°è¯•ä½¿ç”¨ä¸€ä¸ªç¨çŸæˆ–修改过的å称æ¥æœç´¢MAINTAINERSæ–‡ä»¶ï¼Œå› +ä¸ºè¿™æ ·ä½ å¯èƒ½ä¼šå‘çŽ°ç±»ä¼¼è¿™æ ·çš„ä¸œè¥¿:: + + QUALCOMM ATHEROS ATH10K WIRELESS DRIVER + Mail: A. Some Human <shuman@example.com> + Mailing list: ath10k@lists.infradead.org + Status: Supported + Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k + SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git + Files: drivers/net/wireless/ath/ath10k/ + +注æ„：如果您阅读在Linuxæºä»£ç æ ‘çš„æ ¹ç›®å½•ä¸æ‰¾åˆ°çš„原始维护者文件，则行æ述将是 +缩写。例如，“Mail:（邮件）â€å°†æ˜¯â€œM:â€ï¼Œâ€œMailing list:（邮件列表）â€å°†æ˜¯â€œLâ€ï¼Œ +“Status:（状æ€ï¼‰â€å°†æ˜¯â€œS:â€ã€‚æ¤æ–‡ä»¶é¡¶éƒ¨æœ‰ä¸€æ®µè§£é‡Šäº†è¿™äº›å’Œå…¶ä»–缩写。 + +首先查看“Statusâ€çŠ¶æ€è¡Œã€‚ç†æƒ³æƒ…况下，它应该得到“Supported（支æŒï¼‰â€æˆ– +“Maintained（维护）â€ã€‚如果状æ€ä¸ºâ€œObsolete（过时的）â€ï¼Œé‚£ä¹ˆä½ 在使用一些过时的 +方法，需è¦è½¬æ¢åˆ°æ–°çš„解决方案上。有时候，åªæœ‰åœ¨æ„Ÿåˆ°æœ‰åŠ¨åŠ›æ—¶ï¼Œæ‰ä¼šæœ‰äººä¸ºä»£ç +æ供“Odd Fixesâ€ã€‚如果碰è§â€œOrphanâ€ï¼Œä½ 就完全ä¸èµ°è¿äº†ï¼Œå› 为å†ä¹Ÿæ²¡æœ‰äººå…³å¿ƒä»£ç +了，åªå‰©ä¸‹è¿™äº›é€‰é¡¹:准备好与问题共å˜ï¼Œè‡ªå·±ä¿®å¤å®ƒï¼Œæˆ–者找一个愿æ„ä¿®å¤å®ƒçš„程åºå‘˜ã€‚ + +检查状æ€åŽï¼Œå¯»æ‰¾ä»¥â€œbug:â€å¼€å¤´çš„ä¸€è¡Œï¼šå®ƒå°†å‘Šè¯‰ä½ åœ¨å“ªé‡Œå¯ä»¥æ‰¾åˆ°å系统特定的缺 +陷跟踪器æ¥æäº¤ä½ çš„é—®é¢˜ã€‚ä¸Šé¢çš„例å没有æ¤è¡Œã€‚å¤§å¤šæ•°éƒ¨åˆ†éƒ½æ˜¯è¿™æ ·ï¼Œå› ä¸º Linux +å†…æ ¸çš„å¼€å‘完全是由邮件驱动的。很少有å系统使用缺陷跟踪器，且其ä¸åªæœ‰ä¸€éƒ¨åˆ† +ä¾èµ–于 bugzilla.kernel.org。 + +在这ç§ä»¥åŠå…¶ä»–å¾ˆå¤šæƒ…å†µä¸‹ï¼Œä½ å¿…é¡»å¯»æ‰¾ä»¥â€œMail:â€å¼€å¤´çš„行。这些行æ到了特定代ç +的维护者的åå—和电å邮件地å€ã€‚也å¯ä»¥æŸ¥æ‰¾ä»¥â€œMailing list:â€å¼€å¤´çš„è¡Œï¼Œå®ƒå‘Šè¯‰ä½ +å¼€å‘代ç çš„å…¬å…±é‚®ä»¶åˆ—è¡¨ã€‚ä½ çš„æŠ¥å‘Šä¹‹åŽéœ€è¦é€šè¿‡é‚®ä»¶å‘到这些地å€ã€‚å¦å¤–，对于所有 +通过电å邮件å‘é€çš„问题报告，一定è¦æŠ„é€ Linux Kernel Mailing List（LKML） +<linux-kernel@vger.kernel.org>。在以åŽé€šè¿‡é‚®ä»¶å‘é€é—®é¢˜æŠ¥å‘Šæ—¶ï¼Œä¸è¦é—æ¼ä»»ä½• +一个邮件列表!维护者都是大忙人，å¯èƒ½ä¼šæŠŠä¸€äº›å·¥ä½œç•™ç»™å系统特定列表上的其他开 +å‘者；而 LKML 很é‡è¦ï¼Œå› 为需è¦ä¸€ä¸ªå¯ä»¥æ‰¾åˆ°æ‰€æœ‰é—®é¢˜æŠ¥å‘Šçš„地方。 + + +借助脚本找到维护者 +~~~~~~~~~~~~~~~~~~~~ + +对于手头有Linuxæºç 的人æ¥è¯´ï¼Œæœ‰ç¬¬äºŒä¸ªå¯ä»¥æ‰¾åˆ°åˆé€‚的报告地点的选择：脚本 +“scripts/get_maintainer.plâ€ï¼Œå®ƒå°è¯•æ‰¾åˆ°æ‰€æœ‰è¦è”系的人。它会查询MAINTAINERS +文件，并需è¦ç”¨ç›¸å…³æºä»£ç 的路径æ¥è°ƒç”¨ã€‚对于编译æˆæ¨¡å—的驱动程åºï¼Œç»å¸¸å¯ä»¥ç”¨ +è¿™æ ·çš„å‘½ä»¤æ‰¾åˆ°:: + + $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' + drivers/net/wireless/ath/ath10k/ath10k_pci.ko + +将其ä¸çš„éƒ¨åˆ†å†…å®¹ä¼ é€’ç»™è„šæœ¬:: + + $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k* + Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS) + ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS)) + netdev@vger.kernel.org (open list:NETWORKING DRIVERS) + linux-kernel@vger.kernel.org (open list) + +ä¸è¦æŠŠä½ 的报告å‘给所有的人。å‘é€ç»™ç»´æŠ¤è€…，脚本称之为“supporter:â€ï¼›å¦å¤–æŠ„é€ +代ç æœ€ç›¸å…³çš„é‚®ä»¶åˆ—è¡¨ï¼Œä»¥åŠ Linux å†…æ ¸é‚®ä»¶åˆ—è¡¨ï¼ˆLKML）。在æ¤ä¾‹ä¸ï¼Œä½ 需è¦å°†æŠ¥ +å‘Šå‘é€ç»™ “Some Human <shuman@example.com>â€ ï¼Œå¹¶æŠ„é€ +“ath10k@lists.infradead.orgâ€å’Œâ€œlinux-kernel@vger.kernel.orgâ€ã€‚ + +注æ„ï¼šå¦‚æžœä½ ç”¨ git 克隆了 Linux æºä»£ç ï¼Œä½ å¯èƒ½éœ€è¦ç”¨--git å†æ¬¡è°ƒç”¨ +get_maintainer.pl。脚本会查看æ交历å²ï¼Œä»¥æ‰¾åˆ°æœ€è¿‘哪些人å‚与了相关代ç 的编写， +å› ä¸ºä»–ä»¬å¯èƒ½ä¼šæ供帮助。但è¦å°å¿ƒä½¿ç”¨è¿™äº›ç»“æžœï¼Œå› ä¸ºå®ƒå¾ˆå®¹æ˜“è®©ä½ è¯¯å…¥æ§é€”。 +例如，这ç§æƒ…况常常会å‘生在很少被修改的地方（比如è€æ—§çš„或未维护的驱动程åºï¼‰ï¼š +æœ‰æ—¶è¿™æ ·çš„ä»£ç ä¼šåœ¨æ ‘çº§æ¸…ç†æœŸé—´è¢«æ ¹æœ¬ä¸å…³å¿ƒæ¤é©±åŠ¨ç¨‹åºçš„å¼€å‘者修改。 + + +æœç´¢çŽ°æœ‰æŠ¥å‘Šï¼ˆç¬¬äºŒéƒ¨åˆ†ï¼‰ +-------------------------- + + *在缺陷追踪器或问题相关邮件列表的å˜æ¡£ä¸å½»åº•æœç´¢å¯èƒ½ä¸Žæ‚¨çš„问题匹é…的报告。 + 如果找到匹é…çš„æŠ¥å‘Šï¼Œè¯·åŠ å…¥è®¨è®ºè€Œä¸æ˜¯å‘é€æ–°æŠ¥å‘Šã€‚* + +如å‰æ‰€è¿°ï¼šæŠ¥å‘Šä¸€ä¸ªåˆ«äººå·²ç»æ出的问题，对æ¯ä¸ªäººæ¥è¯´éƒ½æ˜¯æµªè´¹æ—¶é—´ï¼Œå°¤å…¶æ˜¯ä½œä¸ºæŠ¥å‘Š +äººçš„ä½ ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ åº”è¯¥å†æ¬¡æœç´¢çŽ°æœ‰çš„æŠ¥å‘Šã€‚çŽ°åœ¨ä½ å·²ç»çŸ¥é“问题需è¦æŠ¥å‘Šåˆ°å“ªé‡Œã€‚ +如果是邮件列表，那么一般在 `lore.kernel.org <https://lore.kernel.org/>`_ å¯ä»¥ +找到相应å˜æ¡£ã€‚ + +但有些列表è¿è¡Œåœ¨å…¶ä»–地方。例如å‰é¢æ¥éª¤ä¸å½“例åçš„ath10k WiFi驱动程åºå°±æ˜¯è¿™ç§ +æƒ…å†µã€‚ä½†æ˜¯ä½ é€šå¸¸å¯ä»¥åœ¨ç½‘上很容易地找到这些列表的档案。例如æœç´¢â€œarchive +ath10k@lists.infradead.orgâ€ï¼Œå°†å¼•å¯¼æ‚¨åˆ°ath10k邮件列表的信æ¯é¡µï¼Œè¯¥é¡µé¢é¡¶éƒ¨é“¾æŽ¥ +到其 `列表å˜æ¡£ <https://lists.infradead.org/pipermail/ath10k/>`_ 。é—憾的是， +这个列表和其他一些列表缺ä¹æœç´¢å…¶å˜æ¡£çš„功能。在这ç§æƒ…况下å¯ä»¥ä½¿ç”¨å¸¸è§„的互è”网 +æœç´¢å¼•æ“Žï¼Œå¹¶æ·»åŠ 类似“site:lists.infadead.org/pipermail/ath10k/â€è¿™ +æ ·çš„æœç´¢æ¡ä»¶ï¼Œè¿™ä¼šæŠŠç»“æžœé™åˆ¶åœ¨è¯¥é“¾æŽ¥ä¸çš„档案。 + +也请进一æ¥æœç´¢ç½‘络ã€LKMLå’Œbugzilla.kernel.org网站。 + +有关如何æœç´¢ä»¥åŠåœ¨æ‰¾åˆ°åŒ¹é…报告时如何æ“作的详细信æ¯ï¼Œè¯·å‚阅上é¢çš„“æœç´¢çŽ°æœ‰æŠ¥å‘Š +（第一部分）â€ã€‚ + +ä¸è¦æ€¥ç€å®ŒæˆæŠ¥å‘Šè¿‡ç¨‹çš„这一æ¥ï¼šèŠ±30到60分钟甚至更多的时间å¯ä»¥ä¸ºä½ å’Œå…¶ä»–äººèŠ‚çœ / +å‡å°‘相当多的时间和麻烦。 + + +å®‰è£…ä¸€ä¸ªæ–°çš„å†…æ ¸è¿›è¡Œæµ‹è¯• +-------------------------- + + *除éžæ‚¨å·²ç»åœ¨è¿è¡Œæœ€æ–°çš„“主线â€Linuxå†…æ ¸ï¼Œå¦åˆ™æœ€å¥½åœ¨æŠ¥å‘Šæµç¨‹å‰å®‰è£…它。在 + æŸäº›æƒ…况下，使用最新的“稳定版â€Linux进行测试和报告也是å¯ä»¥æŽ¥å—的替代方案； + 在åˆå¹¶çª—å£æœŸé—´ï¼Œè¿™å®žé™…上å¯èƒ½æ˜¯æœ€å¥½çš„方法，但在开å‘阶段最好还是暂åœå‡ 天。 + æ— è®ºä½ é€‰æ‹©ä»€ä¹ˆç‰ˆæœ¬ï¼Œæœ€å¥½ä½¿ç”¨â€œæ™®é€šâ€æž„å»ºã€‚å¿½ç•¥è¿™äº›å»ºè®®ä¼šå¤§å¤§å¢žåŠ æ‚¨çš„æŠ¥å‘Š + 被拒ç»æˆ–忽略的风险。* + +æ£å¦‚第一æ¥çš„详细解释ä¸æ‰€æ到的：与大多数程åºå‘˜ä¸€æ ·ï¼Œä¸Žå¤§å¤šæ•°ç¨‹åºå‘˜ä¸€æ ·ï¼ŒLinux +å†…æ ¸å¼€å‘人员ä¸å–œæ¬¢èŠ±æ—¶é—´å¤„ç†ä»–们维护的æºä»£ç ä¸æ ¹æœ¬ä¸ä¼šå‘ç”Ÿçš„é—®é¢˜çš„æŠ¥å‘Šã€‚è¿™åª +会浪费æ¯ä¸ªäººçš„æ—¶é—´ï¼Œå°¤å…¶æ˜¯ä½ çš„æ—¶é—´ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆåœ¨æŠ¥å‘Šé—®é¢˜ä¹‹å‰ï¼Œæ‚¨å¿…须先确认 +问题ä»ç„¶å˜åœ¨äºŽæœ€æ–°çš„上游代ç ä¸ï¼Œè¿™ç¬¦åˆæ¯ä¸ªäººçš„利益。您å¯ä»¥å¿½ç•¥æ¤å»ºè®®ï¼Œä½†å¦‚å‰ +æ‰€è¿°ï¼šè¿™æ ·åšä¼šæžå¤§åœ°å¢žåŠ 问题报告被拒ç»æˆ–被忽略的风险。 + +å†…æ ¸â€œæœ€æ–°ä¸Šæ¸¸â€çš„范围通常指： + + * å®‰è£…ä¸€ä¸ªä¸»çº¿å†…æ ¸ï¼›æœ€æ–°çš„ç¨³å®šç‰ˆå†…æ ¸ä¹Ÿå¯ä»¥æ˜¯ä¸€ä¸ªé€‰æ‹©ï¼Œä½†å¤§å¤šæ•°æ—¶å€™éƒ½æœ€å¥½é¿å…。 + 长期支æŒå†…æ ¸ï¼ˆæœ‰æ—¶ç§°ä¸ºâ€œLTSå†…æ ¸â€ï¼‰ä¸é€‚åˆæ¤æµç¨‹ã€‚下一å°èŠ‚将更详细地解释所有 + 这些。 + + * 下一å°èŠ‚æ述获å–å’Œå®‰è£…è¿™æ ·ä¸€ä¸ªå†…æ ¸çš„æ–¹æ³•ã€‚å®ƒè¿˜æŒ‡å‡ºäº†ä½¿ç”¨é¢„ç¼–è¯‘å†…æ ¸æ˜¯å¯ä»¥çš„， + ä½†æ™®é€šçš„å†…æ ¸æ›´å¥½ï¼Œè¿™æ„味ç€ï¼šå®ƒæ˜¯ç›´æŽ¥ä½¿ç”¨ä»Ž `kernel.org <https://kernel.org/>`_ + 获得的Linuxæºä»£ç 构建并且没有任何方å¼ä¿®æ”¹æˆ–增强。 + + +选择适åˆæµ‹è¯•çš„版本 +~~~~~~~~~~~~~~~~~~~~ + +å‰å¾€ `kernel.org <https://kernel.org/>`_ æ¥å†³å®šä½¿ç”¨å“ªä¸ªç‰ˆæœ¬ã€‚å¿½ç•¥é‚£ä¸ªå†™ç€ +“Latest release最新版本â€çš„å·¨å¤§é»„è‰²æŒ‰é’®ï¼Œå¾€ä¸‹çœ‹æœ‰ä¸€ä¸ªè¡¨æ ¼ã€‚åœ¨è¡¨æ ¼çš„é¡¶éƒ¨ï¼Œä½ ä¼š +看到一行以“mainlineâ€å¼€å¤´çš„å—æ ·ï¼Œå¤§å¤šæ•°æƒ…å†µä¸‹å®ƒä¼šæŒ‡å‘一个版本å·ç±»ä¼¼â€œ5.8-rc2†+的预å‘å¸ƒç‰ˆæœ¬ã€‚å¦‚æžœæ˜¯è¿™æ ·çš„è¯ï¼Œä½ 将需è¦ä½¿ç”¨è¿™ä¸ªä¸»çº¿å†…æ ¸è¿›è¡Œæµ‹è¯•ã€‚ä¸è¦è®©â€œrc†+å“åˆ°ä½ ï¼Œè¿™äº›â€œå¼€å‘ç‰ˆå†…æ ¸â€å®žé™…上éžå¸¸å¯é â€”â€”è€Œä¸”ä½ å·²ç»æŒ‰ç…§ä¸Šé¢çš„指示åšäº†å¤‡ä»½ï¼Œ +ä¸æ˜¯å—？ + +大概æ¯ä¹åˆ°å周，“mainlineâ€å¯èƒ½ä¼šç»™ä½ 指出一个版本å·ç±»ä¼¼â€œ5.7â€çš„æ£å¼ç‰ˆæœ¬ã€‚如果 +碰è§è¿™ç§æƒ…况，请考虑暂åœæŠ¥å‘Šè¿‡ç¨‹ï¼Œç›´åˆ°ä¸‹ä¸€ä¸ªç‰ˆæœ¬çš„第一个预å‘布（5.8-rc1）出 +现在 `kernel.org <https://kernel.org/>`_ ä¸Šã€‚è¿™æ˜¯å› ä¸º Linux çš„å¼€å‘周期æ£åœ¨ +两周的“åˆå¹¶çª—å£â€å†…。大部分的改动和所有干扰性的改动都会在这段时间内被åˆå¹¶åˆ° +下一个版本ä¸ã€‚在æ¤æœŸé—´ä½¿ç”¨ä¸»çº¿æ˜¯æ¯”较å±é™©çš„ã€‚å†…æ ¸å¼€å‘者通常也很忙，å¯èƒ½æ²¡æœ‰ +多余的时间æ¥å¤„ç†é—®é¢˜æŠ¥å‘Šã€‚这也是很有å¯èƒ½åœ¨åˆå¹¶çª—å£ä¸åº”用了许多修改æ¥ä¿®å¤ä½ +所é¢ä¸´çš„é—®é¢˜ï¼›è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ å¾ˆå¿«å°±å¾—ç”¨ä¸€ä¸ªæ–°çš„å†…æ ¸ç‰ˆæœ¬é‡æ–°æµ‹è¯•ï¼Œå°±åƒä¸‹é¢â€œå‘ +布报告åŽçš„责任â€ä¸€èŠ‚ä¸æ‰€è¿°çš„é‚£æ ·ã€‚ + +这就是为什么è¦ç‰åˆ°åˆå¹¶çª—å£ç»“æŸåŽæ‰åŽ»åšã€‚ä½†æ˜¯å¦‚æžœä½ å¤„ç†çš„是一些ä¸åº”该ç‰å¾…çš„ +ä¸œè¥¿ï¼Œåˆ™æ— éœ€è¿™æ ·åšã€‚在这ç§æƒ…况下，å¯ä»¥è€ƒè™‘通过 git 获å–æœ€æ–°çš„ä¸»çº¿å†…æ ¸ï¼ˆè§ä¸‹ +文），或者使用 kernel.org 上æ供的最新稳定版本。如果 mainline å› ä¸ºæŸäº›åŽŸå› +ä¸æ— 法æ£å¸¸å·¥ä½œï¼Œé‚£ä¹ˆä½¿ç”¨å®ƒä¹Ÿæ˜¯å¯ä»¥æŽ¥å—的。总的æ¥è¯´ï¼šç”¨å®ƒæ¥é‡çŽ°é—®é¢˜ä¹Ÿæ¯”完全 +ä¸æŠ¥å‘Šé—®é¢˜è¦å¥½ã€‚ + +最好é¿å…在åˆå¹¶çª—å£å¤–ä½¿ç”¨æœ€æ–°çš„ç¨³å®šç‰ˆå†…æ ¸ï¼Œå› ä¸ºæ‰€æœ‰ä¿®å¤éƒ½å¿…须首先应用于主线。 +è¿™å°±æ˜¯ä¸ºä»€ä¹ˆæ£€æŸ¥æœ€æ–°çš„ä¸»çº¿å†…æ ¸æ˜¯å¦‚æ¤é‡è¦ï¼šä½ 希望看到在旧版本线修å¤çš„任何问题 +需è¦å…ˆåœ¨ä¸»çº¿ä¿®å¤ï¼Œç„¶åŽæ‰èƒ½å¾—åˆ°å›žä¼ ï¼Œè¿™å¯èƒ½éœ€è¦å‡ å¤©æˆ–å‡ å‘¨ã€‚å¦ä¸€ä¸ªåŽŸå› 是：您 +希望的修å¤å¯¹äºŽå›žä¼ æ¥è¯´å¯èƒ½å¤ªéš¾æˆ–å¤ªå†’é™©ï¼›å› æ¤å†æ¬¡æŠ¥å‘Šé—®é¢˜ä¸å¤ªå¯èƒ½æ”¹å˜ä»»ä½•äº‹æƒ…。 + +这些方é¢ä¹Ÿéƒ¨åˆ†è¡¨æ˜Žäº†ä¸ºä»€ä¹ˆé•¿æœŸæ”¯æŒå†…æ ¸ï¼ˆæœ‰æ—¶ç§°ä¸ºâ€œLTSå†…æ ¸â€ï¼‰ä¸é€‚åˆæŠ¥å‘Šæµç¨‹ï¼š +它们与当å‰ä»£ç çš„è·ç¦»å¤ªè¿œã€‚å› æ¤ï¼Œå…ˆåŽ»æµ‹è¯•ä¸»çº¿ï¼Œç„¶åŽå†æŒ‰æµç¨‹èµ°ï¼šå¦‚果主线没有 +出现问题，æµç¨‹å°†æŒ‡å¯¼æ‚¨å¦‚何在旧版本线ä¸ä¿®å¤å®ƒã€‚ + +如何获得新的 Linux å†…æ ¸ +~~~~~~~~~~~~~~~~~~~~~~~~~ + +ä½ å¯ä»¥ä½¿ç”¨é¢„ç¼–è¯‘æˆ–è‡ªç¼–è¯‘çš„å†…æ ¸è¿›è¡Œæµ‹è¯•ï¼›å¦‚æžœä½ é€‰æ‹©åŽè€…，å¯ä»¥ä½¿ç”¨ git 获å–æº +代ç ，或者下载其 tar å˜æ¡£åŒ…。 + +**ä½¿ç”¨é¢„ç¼–è¯‘çš„å†…æ ¸** ：这往往是最快速ã€æœ€ç®€å•ã€æœ€å®‰å…¨çš„æ–¹æ³•â€”â€”å°¤å…¶æ˜¯åœ¨ä½ ä¸ç†Ÿ +悉 Linux å†…æ ¸çš„æƒ…å†µä¸‹ã€‚é—®é¢˜æ˜¯ï¼šå‘è¡Œå•†æˆ–é™„åŠ å˜å‚¨åº“æ供的大多数版本都是从修改 +过的Linuxæºä»£ç æž„å»ºçš„ã€‚å› æ¤å®ƒä»¬ä¸æ˜¯æ™®é€šçš„，通常ä¸é€‚åˆäºŽæµ‹è¯•å’Œé—®é¢˜æŠ¥å‘Šï¼šè¿™äº› +更改å¯èƒ½ä¼šå¯¼è‡´æ‚¨é¢ä¸´çš„问题或以æŸç§æ–¹å¼å½±å“问题。 + +但是如果您使用的是æµè¡Œçš„Linuxå‘行版，那么您就很幸è¿äº†ï¼šå¯¹äºŽå¤§éƒ¨åˆ†çš„å‘行版， +您å¯ä»¥åœ¨ç½‘上找到包å«æœ€æ–°ä¸»çº¿æˆ–稳定版本Linuxå†…æ ¸åŒ…çš„å˜å‚¨åº“ã€‚ä½¿ç”¨è¿™äº›æ˜¯å®Œå…¨å¯ +以的，åªè¦ä»Žå˜å‚¨åº“çš„æè¿°ä¸ç¡®è®¤å®ƒä»¬æ˜¯æ™®é€šçš„或者至少接近普通。æ¤å¤–，请确ä¿è½¯ä»¶ +包包å«kernel.org上æä¾›çš„æœ€æ–°ç‰ˆæœ¬å†…æ ¸ã€‚å¦‚æžœè¿™äº›è½¯ä»¶åŒ…çš„æ—¶é—´è¶…è¿‡ä¸€å‘¨ï¼Œé‚£ä¹ˆå®ƒä»¬ +å¯èƒ½å°±ä¸åˆé€‚äº†ï¼Œå› ä¸ºæ–°çš„ä¸»çº¿å’Œç¨³å®šç‰ˆå†…æ ¸é€šå¸¸è‡³å°‘æ¯å‘¨å‘布一次。 + +请注æ„，您以åŽå¯èƒ½éœ€è¦æ‰‹åŠ¨æž„å»ºè‡ªå·±çš„å†…æ ¸ï¼šæœ‰æ—¶è¿™æ˜¯è°ƒè¯•æˆ–æµ‹è¯•ä¿®å¤ç¨‹åºæ‰€å¿…需的， +如åŽæ–‡æ‰€è¿°ã€‚还è¦æ³¨æ„ï¼Œé¢„ç¼–è¯‘çš„å†…æ ¸å¯èƒ½ç¼ºå°‘在出现panicã€Oopsã€warning或BUGæ—¶ +解ç å†…æ ¸æ‰“å°çš„消æ¯æ‰€éœ€çš„调试符å·ï¼›å¦‚果您计划解ç 这些消æ¯ï¼Œæœ€å¥½è‡ªå·±ç¼–è¯‘å†…æ ¸ +（有关详细信æ¯ï¼Œè¯·å‚阅本å°èŠ‚结尾和“解ç 失败信æ¯â€å°èŠ‚）。 + +**使用git** ：熟悉 git çš„å¼€å‘者和有ç»éªŒçš„ Linux 用户通常最好直接从 +`kernel.org 上的官方开å‘仓库 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ +ä¸èŽ·å–最新的 Linux å†…æ ¸æºä»£ç 。这些很å¯èƒ½æ¯”最新的主线预å‘å¸ƒç‰ˆæœ¬æ›´æ–°ä¸€äº›ã€‚ä¸ +用担心：它们和æ£å¼çš„预å‘å¸ƒç‰ˆæœ¬ä¸€æ ·å¯é ，除éžå†…æ ¸çš„å¼€å‘周期目å‰æ£å¤„于åˆå¹¶çª— +å£ä¸ã€‚ä¸è¿‡å³ä¾¿å¦‚æ¤ï¼Œå®ƒä»¬ä¹Ÿæ˜¯ç›¸å½“å¯é 的。 + +**常规方法** ：ä¸ç†Ÿæ‚‰ git 的人通常最好从 `kernel.org <https://kernel.org/>`_ +下载æºç çš„tar å˜æ¡£åŒ…。 + +å¦‚ä½•å®žé™…æž„å»ºä¸€ä¸ªå†…æ ¸å¹¶ä¸åœ¨è¿™é‡Œæè¿°ï¼Œå› ä¸ºè®¸å¤šç½‘ç«™å·²ç»è§£é‡Šäº†å¿…è¦çš„æ¥éª¤ã€‚如果 +ä½ æ˜¯æ–°æ‰‹ï¼Œå¯ä»¥è€ƒè™‘按照那些建议使用 ``make localmodconfig`` æ¥åšï¼Œå®ƒå°†å°è¯•èŽ· +å–ä½ å½“å‰å†…æ ¸çš„é…置，然åŽæ ¹æ®ä½ çš„ç³»ç»Ÿè¿›è¡Œä¸€äº›è°ƒæ•´ã€‚è¿™æ ·åšå¹¶ä¸èƒ½ä½¿ç¼–译出æ¥çš„ +å†…æ ¸æ›´å¥½ï¼Œä½†å¯ä»¥æ›´å¿«åœ°ç¼–译。 + +注æ„：如果您æ£åœ¨å¤„ç†æ¥è‡ªå†…æ ¸çš„panncã€Oopsã€warning或BUG，请在é…ç½®å†…æ ¸æ—¶å°è¯• +å¯ç”¨ CONFIG_KALLSYMS 选项。æ¤å¤–，还å¯ä»¥å¯ç”¨ CONFIG_DEBUG_KERNEL å’Œ +CONFIG_DEBUG_INFOï¼›åŽè€…是相关选项，但åªæœ‰å¯ç”¨å‰è€…æ‰èƒ½å¼€å¯ã€‚请注æ„， +CONFIG_DEBUG_INFO 会需è¦æ›´å¤šå‚¨å˜ç©ºé—´æ¥æž„å»ºå†…æ ¸ã€‚ä½†è¿™æ˜¯å€¼å¾—çš„ï¼Œå› ä¸ºè¿™äº›é€‰é¡¹å°† +å…许您ç¨åŽç²¾ç¡®å®šä½è§¦å‘问题的确切代ç 行。下é¢çš„“解ç 失败信æ¯â€ä¸€èŠ‚对æ¤è¿›è¡Œäº†æ›´ +详细的解释。 + +但请记ä½ï¼šå§‹ç»ˆè®°å½•é‡åˆ°çš„问题，以防难以é‡çŽ°ã€‚å‘é€æœªè§£ç 的报告总比ä¸æŠ¥å‘Šè¦å¥½ã€‚ + + +检查“污染â€æ ‡å¿— +---------------- + + *ç¡®ä¿æ‚¨åˆšåˆšå®‰è£…çš„å†…æ ¸åœ¨è¿è¡Œæ—¶ä¸ä¼šâ€œæ±¡æŸ“â€è‡ªå·±ã€‚* + +æ£å¦‚上é¢å·²ç»è¯¦ç»†ä»‹ç»è¿‡çš„：当å‘生一些å¯èƒ½ä¼šå¯¼è‡´ä¸€äº›çœ‹èµ·æ¥å®Œå…¨ä¸ç›¸å…³çš„åŽç»é”™ +è¯¯çš„äº‹æƒ…æ—¶ï¼Œå†…æ ¸ä¼šè®¾ç½®ä¸€ä¸ªâ€œæ±¡æŸ“â€æ ‡å¿—ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ éœ€è¦æ£€æŸ¥ä½ 刚刚安装的内 +æ ¸æ˜¯å¦æœ‰è®¾ç½®æ¤æ ‡å¿—。如果有的è¯ï¼Œå‡ ä¹Žåœ¨ä»»ä½•æƒ…å†µä¸‹ä½ éƒ½éœ€è¦åœ¨æŠ¥å‘Šé—®é¢˜ä¹‹å‰å…ˆæ¶ˆ +除它。详细的æ“作方法请看上é¢çš„ç« èŠ‚ã€‚ + + +ç”¨æ–°å†…æ ¸é‡çŽ°é—®é¢˜ +------------------ + + *åœ¨æ‚¨åˆšåˆšå®‰è£…çš„å†…æ ¸ä¸å¤çŽ°è¿™ä¸ªé—®é¢˜ã€‚如果它没有出现，请查看下方åªå‘生在 + 稳定版和长期支æŒå†…æ ¸çš„é—®é¢˜çš„è¯´æ˜Žã€‚* + +检查这个问题是å¦å‘ç”Ÿåœ¨ä½ åˆšåˆšå®‰è£…çš„æ–° Linux å†…æ ¸ç‰ˆæœ¬ä¸Šã€‚å¦‚æžœæ–°å†…æ ¸å·²ç»ä¿®å¤äº†ï¼Œ +å¯ä»¥è€ƒè™‘使用æ¤ç‰ˆæœ¬çº¿ï¼Œæ”¾å¼ƒæŠ¥å‘Šé—®é¢˜ã€‚但是请记ä½ï¼Œåªè¦å®ƒæ²¡æœ‰åœ¨ `kernel.org +<https://kernel.org/>`_ 的稳定版和长期版（以åŠç”±è¿™äº›ç‰ˆæœ¬è¡ç”Ÿå‡ºæ¥çš„åŽ‚å•†å†…æ ¸ï¼‰ +ä¸å¾—到修å¤ï¼Œå…¶ä»–用户å¯èƒ½ä»ç„¶ä¼šå—åˆ°å®ƒçš„å›°æ‰°ã€‚å¦‚æžœä½ å–œæ¬¢ä½¿ç”¨å…¶ä¸çš„一个，或 +者åªæ˜¯æƒ³å¸®åŠ©å®ƒä»¬çš„用户，请å‰å¾€ä¸‹é¢çš„“报告åªå‘ç”Ÿåœ¨è¾ƒæ—§å†…æ ¸ç‰ˆæœ¬çº¿çš„é—®é¢˜â€ä¸€èŠ‚。 + + +优化å¤çŽ°é—®é¢˜çš„æè¿° +-------------------- + + *ä¼˜åŒ–ä½ çš„ç¬”è®°ï¼šè¯•ç€æ‰¾åˆ°å¹¶å†™å‡ºæœ€ç›´æŽ¥çš„å¤çŽ°é—®é¢˜çš„方法。确ä¿æœ€ç»ˆç»“果包å«æ‰€ + 有é‡è¦çš„细节，åŒæ—¶è®©ç¬¬ä¸€æ¬¡å¬è¯´çš„人容易阅读和ç†è§£ã€‚如果您在æ¤è¿‡ç¨‹ä¸å¦åˆ° + 了一些东西，请考虑å†æ¬¡æœç´¢å…³äºŽè¯¥é—®é¢˜çš„现有报告。* + +过于å¤æ‚的报告会让别人很难ç†è§£ã€‚å› æ¤è¯·å°½é‡æ‰¾åˆ°ä¸€ä¸ªå¯ä»¥ç›´æŽ¥æè¿°ã€æ˜“äºŽä»¥ä¹¦é¢ +å½¢å¼ç†è§£çš„å†çŽ°æ–¹æ³•ã€‚包å«æ‰€æœ‰é‡è¦çš„细节，但åŒæ—¶ä¹Ÿè¦å°½é‡ä¿æŒç®€çŸã€‚ + +在这在å‰é¢çš„æ¥éª¤ä¸ï¼Œä½ 很å¯èƒ½å·²ç»äº†è§£äº†ä¸€äº›å…³äºŽä½ 所é¢ä¸´çš„问题的点。利用这些 +知识，å†æ¬¡æœç´¢å¯ä»¥è½¬è€ŒåŠ 入的现有报告。 + + +解ç å¤±è´¥ä¿¡æ¯ +------------- + + *如果失败涉åŠâ€œpanicâ€ã€â€œOopsâ€ã€â€œwarningâ€æˆ–“BUGâ€ï¼Œè¯·è€ƒè™‘解ç å†…æ ¸æ—¥å¿—ä»¥æŸ¥æ‰¾ + 触å‘错误的代ç 行。* + +å½“å†…æ ¸æ£€æµ‹åˆ°å†…éƒ¨é—®é¢˜æ—¶ï¼Œå®ƒä¼šè®°å½•ä¸€äº›æœ‰å…³å·²æ‰§è¡Œä»£ç çš„ä¿¡æ¯ã€‚这使得在æºä»£ç ä¸ç²¾ +确定ä½è§¦å‘问题的行并显示如何调用它æˆä¸ºå¯èƒ½ã€‚但åªæœ‰åœ¨é…ç½®å†…æ ¸æ—¶å¯ç”¨äº† +CONFIG_DEBUG_INFO å’Œ CONFIG_KALLSYMS选项时，这ç§æ–¹æ³•æ‰èµ·æ•ˆã€‚如果已å¯ç”¨æ¤é€‰é¡¹ï¼Œ +请考虑解ç å†…æ ¸æ—¥å¿—ä¸çš„ä¿¡æ¯ã€‚这将使我们更容易ç†è§£æ˜¯ä»€ä¹ˆå¯¼è‡´äº†â€œpanicâ€ã€â€œOopsâ€ã€ +“warningâ€æˆ–“BUGâ€ï¼Œä»Žè€Œå¢žåŠ 了有人æ供修å¤çš„å‡ çŽ‡ã€‚ + +解ç å¯ä»¥é€šè¿‡Linuxæºä»£ç æ ‘ä¸çš„脚本æ¥å®Œæˆã€‚如果您è¿è¡Œçš„å†…æ ¸æ˜¯ä¹‹å‰è‡ªå·±ç¼–译的， +è¿™æ ·è¿™æ ·è°ƒç”¨å®ƒ:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +如果您è¿è¡Œçš„æ˜¯æ‰“åŒ…å¥½çš„æ™®é€šå†…æ ¸ï¼Œåˆ™å¯èƒ½éœ€è¦å®‰è£…带有调试符å·çš„相应包。然åŽæŒ‰ä»¥ä¸‹ +æ–¹å¼è°ƒç”¨è„šæœ¬ï¼ˆå¦‚æžœå‘行版未打包，则å¯èƒ½éœ€è¦ä»ŽLinuxæºä»£ç 获å–）:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +脚本将解ç å¦‚ä¸‹çš„æ—¥å¿—è¡Œï¼Œè¿™äº›æ—¥å¿—è¡Œæ˜¾ç¤ºå†…æ ¸åœ¨å‘生错误时æ£åœ¨æ‰§è¡Œçš„代ç 的地å€:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +解ç 之åŽï¼Œè¿™äº›è¡Œå°†å˜æˆè¿™æ ·:: + + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module + +在本例ä¸ï¼Œæ‰§è¡Œçš„代ç 是从文件“~/linux-5.10.5/test-module/test-module.câ€æž„建的， +错误出现在第16行的指令ä¸ã€‚ + +该脚本也会如æ¤è§£ç 以“Call traceâ€å¼€å¤´çš„部分ä¸æ到的地å€ï¼Œè¯¥éƒ¨åˆ†æ˜¾ç¤ºå‡ºçŽ°é—®é¢˜çš„ +函数的路径。æ¤å¤–ï¼Œè„šæœ¬è¿˜ä¼šæ˜¾ç¤ºå†…æ ¸æ£åœ¨æ‰§è¡Œçš„代ç 部分的汇编输出。 + +注æ„ï¼Œå¦‚æžœä½ æ²¡æ³•åšåˆ°è¿™ä¸€ç‚¹ï¼Œåªéœ€è·³è¿‡è¿™ä¸€æ¥ï¼Œå¹¶åœ¨æŠ¥å‘Šä¸è¯´æ˜ŽåŽŸå› ã€‚å¦‚æžœä½ å¹¸è¿çš„ +è¯ï¼Œå¯èƒ½æ— 需解ç 。如果需è¦çš„è¯ï¼Œä¹Ÿè®¸æœ‰äººä¼šå¸®ä½ åšè¿™ä»¶äº‹æƒ…。还è¦æ³¨æ„，这åªæ˜¯è§£ +ç å†…æ ¸å †æ ˆè·Ÿè¸ªçš„å‡ ç§æ–¹æ³•ä¹‹ä¸€ã€‚有时需è¦é‡‡å–ä¸åŒçš„æ¥éª¤æ¥æ£€ç´¢ç›¸å…³çš„详细信æ¯ã€‚ +别担心，如果您碰到的情况需è¦è¿™æ ·åšï¼Œå¼€å‘人员会告诉您该怎么åšã€‚ + + +对回归的特别关照 +----------------- + + *如果您的问题是回归问题，请尽å¯èƒ½ç¼©å°å¼•å…¥é—®é¢˜æ—¶çš„范围。* + +Linux 首å¸å¼€å‘者 Linus Torvalds 认为 Linux å†…æ ¸æ°¸è¿œä¸åº”æ¶åŒ–，这就是为什么他 +认为回归是ä¸å¯æŽ¥å—的，并希望看到它们被迅速修å¤ã€‚这就是为什么引入了回归的改 +åŠ¨å¯¼è‡´çš„é—®é¢˜è‹¥æ— æ³•é€šè¿‡å…¶ä»–æ–¹å¼å¿«é€Ÿè§£å†³ï¼Œé€šå¸¸ä¼šè¢«è¿…é€Ÿæ’¤é”€ã€‚å› æ¤ï¼ŒæŠ¥å‘Šå›žå½’有 +点åƒâ€œçŽ‹ç‚¸â€ï¼Œä¼šè¿…速得到修å¤ã€‚但è¦åšåˆ°è¿™ä¸€ç‚¹ï¼Œéœ€è¦çŸ¥é“导致回归的å˜åŒ–。通常情 +况下，è¦ç”±æŠ¥å‘Šè€…æ¥è¿½æŸ¥ç½ªéç¥¸é¦–ï¼Œå› ä¸ºç»´æŠ¤è€…å¾€å¾€æ²¡æœ‰æ—¶é—´æˆ–æ‰‹å¤´è®¾ç½®ä¸ä¾¿æ¥è‡ªè¡Œ +é‡çŽ°å®ƒã€‚ + +有一个å«åšâ€œäºŒåˆ†â€çš„过程å¯ä»¥æ¥å¯»æ‰¾å˜åŒ–，这在 +“Documentation/translations/zh_CN/admin-guide/bug-bisect.rstâ€æ–‡æ¡£ä¸è¿›è¡Œäº†è¯¦ç»† +çš„æ述，这个过程通常需è¦ä½ 构建å到二åä¸ªå†…æ ¸é•œåƒï¼Œæ¯æ¬¡éƒ½å°è¯•åœ¨æž„å»ºä¸‹ä¸€ä¸ªé•œåƒ +之å‰é‡çŽ°é—®é¢˜ã€‚是的，这需è¦èŠ±è´¹ä¸€äº›æ—¶é—´ï¼Œä½†ä¸ç”¨æ‹…心，它比大多数人想象的è¦å¿«å¾—多。 +多äºäº†â€œbinary search二进制æœç´¢â€ï¼Œè¿™å°†å¼•å¯¼ä½ 在æºä»£ç 管ç†ç³»ç»Ÿä¸æ‰¾åˆ°å¯¼è‡´å›žå½’çš„æ交。 +ä¸€æ—¦ä½ æ‰¾åˆ°å®ƒï¼Œå°±åœ¨ç½‘ä¸Šæœç´¢å…¶ä¸»é¢˜ã€æ交ID和缩çŸçš„æ交ID（æ交IDçš„å‰12个å—符）。 +如果有的è¯ï¼Œè¿™å°†å¼•å¯¼æ‚¨æ‰¾åˆ°å…³äºŽå®ƒçš„现有报告。 + +需è¦æ³¨æ„的是，二分法需è¦ä¸€ç‚¹çªé—¨ï¼Œä¸æ˜¯æ¯ä¸ªäººéƒ½æ‡‚得诀çªï¼Œä¹Ÿéœ€è¦ç›¸å½“多的努力， +ä¸æ˜¯æ¯ä¸ªäººéƒ½æ„¿æ„投入。尽管如æ¤ï¼Œè¿˜æ˜¯å¼ºçƒˆå»ºè®®è‡ªå·±è¿›è¡Œä¸€æ¬¡äºŒåˆ†ã€‚å¦‚æžœä½ çœŸçš„ +ä¸èƒ½æˆ–者ä¸æƒ³èµ°è¿™æ¡è·¯ï¼Œè‡³å°‘è¦æ‰¾å‡ºæ˜¯å“ªä¸ªä¸»çº¿å†…æ ¸å¼•å…¥çš„å›žå½’ã€‚æ¯”å¦‚è¯´ä»Ž 5.5.15 +切æ¢åˆ° 5.8.4 的时候出现了一些问题，那么至少å¯ä»¥å°è¯•ä¸€ä¸‹ç›¸è¿‘的所有的主线版本 +（5.6ã€5.7 å’Œ 5.8）æ¥æ£€æŸ¥å®ƒæ˜¯ä»€ä¹ˆæ—¶å€™å‡ºçŽ°çš„。除éžä½ æƒ³åœ¨ä¸€ä¸ªç¨³å®šç‰ˆæˆ–é•¿æœŸæ”¯æŒ +å†…æ ¸ä¸æ‰¾åˆ°ä¸€ä¸ªå›žå½’，å¦åˆ™è¦é¿å…测试那些编å·æœ‰ä¸‰æ®µçš„版本（5.6.12ã€5.7.8ï¼‰ï¼Œå› +为那会使结果难以解释，å¯èƒ½ä¼šè®©ä½ 的测试å˜å¾—æ— ç”¨ã€‚ä¸€æ—¦ä½ æ‰¾åˆ°äº†å¼•å…¥å›žå½’çš„ä¸»è¦ +版本，就å¯ä»¥æ”¾å¿ƒåœ°ç»§ç»æŠ¥å‘Šäº†ã€‚但请记ä½ï¼šåœ¨ä¸çŸ¥é“罪é祸首的情况下，开å‘人员 +是å¦èƒ½å¤Ÿæ供帮助å–决于手头的问题。有时他们å¯èƒ½ä¼šä»ŽæŠ¥å‘Šä¸ç¡®è®¤æ˜¯ä»€ä¹ˆå‡ºçŽ°äº†é—® +题，并能修å¤å®ƒï¼›æœ‰æ—¶ä»–们å¯èƒ½æ— 法æ供帮助，除éžä½ 进行二分。 + +当处ç†å›žå½’问题时，请确ä¿ä½ 所é¢ä¸´çš„é—®é¢˜çœŸçš„æ˜¯ç”±å†…æ ¸å¼•èµ·çš„ï¼Œè€Œä¸æ˜¯ç”±å…¶ä»–东西 +引起的，如上文所述。 + +在整个过程ä¸ï¼Œè¯·è®°ä½ï¼šåªæœ‰å½“æ—§å†…æ ¸å’Œæ–°å†…æ ¸çš„é…置相似时，问题æ‰ç®—回归。最好 +的方法是：把é…置文件（``.config``ï¼‰ä»Žæ—§çš„å·¥ä½œå†…æ ¸ç›´æŽ¥å¤åˆ¶åˆ°ä½ å°è¯•çš„æ¯ä¸ªæ–°å†… +æ ¸ç‰ˆæœ¬ã€‚ä¹‹åŽè¿è¡Œ ``make oldnoconfig`` æ¥è°ƒæ•´å®ƒä»¥é€‚应新版本的需è¦ï¼Œè€Œä¸å¯ç”¨ +ä»»ä½•æ–°çš„åŠŸèƒ½ï¼Œå› ä¸ºé‚£äº›åŠŸèƒ½ä¹Ÿå¯èƒ½å¯¼è‡´å›žå½’。 + + +撰写并å‘é€æŠ¥å‘Š +--------------- + + *通过详细æ述问题æ¥å¼€å§‹ç¼–写报告。记得包括以下æ¡ç›®ï¼šæ‚¨ä¸ºå¤çŽ°è€Œå®‰è£…的最新 + å†…æ ¸ç‰ˆæœ¬ã€ä½¿ç”¨çš„Linuxå‘行版以åŠå…³äºŽå¦‚何å¤çŽ°è¯¥é—®é¢˜çš„说明。如果å¯èƒ½ï¼Œå°†å†… + æ ¸æž„å»ºé…置（.config）和 ``dmesg`` 的输出放在网上的æŸä¸ªåœ°æ–¹ï¼Œå¹¶é“¾æŽ¥åˆ°å®ƒã€‚ + 包å«æˆ–ä¸Šä¼ æ‰€æœ‰å…¶ä»–å¯èƒ½ç›¸å…³çš„ä¿¡æ¯ï¼Œå¦‚Oops的输出/截图或æ¥è‡ª ``lspci`` + çš„è¾“å‡ºã€‚ä¸€æ—¦ä½ å†™å®Œäº†è¿™ä¸ªä¸»è¦éƒ¨åˆ†ï¼Œè¯·åœ¨ä¸Šæ–¹æ’入一个æ£å¸¸é•¿åº¦çš„段è½å¿«é€Ÿæ¦‚ + 述问题和影å“。å†åœ¨æ¤ä¹‹ä¸Šæ·»åŠ 一个简å•æ述问题的å¥å，以得到人们的阅读。 + 现在给出一个更çŸçš„æè¿°æ€§æ ‡é¢˜æˆ–ä¸»é¢˜ã€‚ç„¶åŽå°±å¯ä»¥åƒMAINTAINERSæ–‡ä»¶å‘Šè¯‰ä½ çš„ + é‚£æ ·å‘é€æˆ–æ交报告了，除éžä½ 在处ç†ä¸€ä¸ªâ€œé«˜ä¼˜å…ˆçº§é—®é¢˜â€ï¼šå®ƒä»¬éœ€è¦æŒ‰ç…§ä¸‹é¢ + “高优先级问题的特殊处ç†â€æ‰€è¿°ç‰¹åˆ«å…³ç…§ã€‚* + +çŽ°åœ¨ä½ å·²ç»å‡†å¤‡å¥½äº†ä¸€åˆ‡ï¼Œæ˜¯æ—¶å€™å†™ä½ 的报告了。上文å‰è¨€ä¸é“¾æŽ¥çš„三篇文档对如何 +写报告åšäº†éƒ¨åˆ†è§£é‡Šã€‚这就是为什么本文将åªæåˆ°ä¸€äº›åŸºæœ¬çš„å†…å®¹ä»¥åŠ Linux å†…æ ¸ç‰¹ +有的东西。 + +有一点是符åˆè¿™ä¸¤ç±»çš„ï¼šä½ çš„æŠ¥å‘Šä¸æœ€å…³é”®çš„éƒ¨åˆ†æ˜¯æ ‡é¢˜/主题ã€ç¬¬ä¸€å¥è¯å’Œç¬¬ä¸€æ®µã€‚ +å¼€å‘者ç»å¸¸ä¼šæ”¶åˆ°è®¸å¤šé‚®ä»¶ã€‚å› æ¤ï¼Œä»–们往往åªæ˜¯èŠ±å‡ 秒钟的时间æµè§ˆä¸€ä¸‹é‚®ä»¶ï¼Œç„¶ +åŽå†å†³å®šç»§ç»ä¸‹ä¸€å°æˆ–ä»”ç»†æŸ¥çœ‹ã€‚å› æ¤ï¼Œä½ æŠ¥å‘Šçš„å¼€å¤´è¶Šå¥½ï¼Œæœ‰äººç ”ç©¶å¹¶å¸®åŠ©ä½ çš„æœº +ä¼šå°±è¶Šå¤§ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ åº”è¯¥æš‚æ—¶å¿½ç•¥ä»–ä»¬ï¼Œå…ˆå†™å‡ºè¯¦ç»†çš„æŠ¥å‘Šã€‚;-) + +æ¯ä»½æŠ¥å‘Šéƒ½åº”æåŠçš„事项 +~~~~~~~~~~~~~~~~~~~~~~~~ + +详细æè¿°ä½ çš„é—®é¢˜æ˜¯å¦‚ä½•å‘ç”Ÿåœ¨ä½ å®‰è£…çš„æ–°çº¯å‡€å†…æ ¸ä¸Šçš„ã€‚è¯•ç€åŒ…å«ä½ 之å‰å†™çš„和优 +化过的分æ¥è¯´æ˜Žï¼Œæ¦‚è¿°ä½ å’Œå…¶ä»–äººå¦‚ä½•é‡çŽ°è¿™ä¸ªé—®é¢˜ï¼›åœ¨æžå°‘æ•°æ— æ³•é‡çŽ°çš„情况下， +å°½é‡æè¿°ä½ åšäº†ä»€ä¹ˆæ¥è§¦å‘它。 + +还应包括其他人为了解该问题åŠå…¶çŽ¯å¢ƒè€Œå¯èƒ½éœ€è¦çš„所有相关信æ¯ã€‚实际需è¦çš„东西 +在很大程度上å–å†³äºŽå…·ä½“é—®é¢˜ï¼Œä½†æœ‰äº›äº‹é¡¹ä½ æ€»æ˜¯åº”è¯¥åŒ…æ‹¬åœ¨å†…ï¼š + + * ``cat /proc/version`` 的输出，其ä¸åŒ…å« Linux å†…æ ¸ç‰ˆæœ¬å·å’Œæž„建时的编译器。 + + * 机器æ£åœ¨è¿è¡Œçš„ Linux å‘行版（ ``hostnamectl | grep “Operating System“`` ） + + * CPU å’Œæ“作系统的架构（ ``uname -mi`` ） + + * 如果您æ£åœ¨å¤„ç†å›žå½’，并进行了二分，请æåŠå¯¼è‡´å›žå½’çš„å˜æ›´çš„主题和æ交ID。 + +è®¸å¤šæƒ…å†µä¸‹ï¼Œè®©è¯»ä½ æŠ¥å‘Šçš„äººå¤šäº†è§£ä¸¤ä»¶äº‹ä¹Ÿæ˜¯æ˜Žæ™ºä¹‹ä¸¾ï¼š + + * 用于构建 Linux å†…æ ¸çš„é…置（“.configâ€æ–‡ä»¶ï¼‰ + + * å†…æ ¸çš„ä¿¡æ¯ï¼Œä½ 从 ``dmesg`` 得到的信æ¯å†™åˆ°ä¸€ä¸ªæ–‡ä»¶é‡Œã€‚ç¡®ä¿å®ƒä»¥åƒâ€œLinux + version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version + 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020â€è¿™æ ·çš„行开始，如果没有，那么第 + 一次å¯åŠ¨é˜¶æ®µçš„é‡è¦ä¿¡æ¯å·²ç»è¢«ä¸¢å¼ƒäº†ã€‚在这ç§æƒ…况下，å¯ä»¥è€ƒè™‘使用 + ``journalctl -b 0 -k`` ï¼›æˆ–è€…ä½ ä¹Ÿå¯ä»¥é‡å¯ï¼Œé‡çŽ°è¿™ä¸ªé—®é¢˜ï¼Œç„¶åŽè°ƒç”¨ + ``dmesg`` 。 + +è¿™ä¸¤ä¸ªæ–‡ä»¶å¾ˆå¤§ï¼Œæ‰€ä»¥ç›´æŽ¥æŠŠå®ƒä»¬æ”¾åˆ°ä½ çš„æŠ¥å‘Šä¸æ˜¯ä¸ªå主æ„ã€‚å¦‚æžœä½ æ˜¯åœ¨ç¼ºé™·è·Ÿè¸ª +器ä¸æäº¤é—®é¢˜ï¼Œé‚£ä¹ˆå°†å®ƒä»¬é™„åŠ åˆ°å·¥å•ä¸ã€‚å¦‚æžœä½ é€šè¿‡é‚®ä»¶æŠ¥å‘Šé—®é¢˜ï¼Œä¸è¦ç”¨é™„件附 +ä¸Šå®ƒä»¬ï¼Œå› ä¸ºé‚£ä¼šä½¿é‚®ä»¶å˜å¾—太大，å¯ä»¥æŒ‰ä¸‹åˆ—之一åšï¼š + + * å°†æ–‡ä»¶ä¸Šä¼ åˆ°æŸä¸ªå…¬å¼€çš„åœ°æ–¹ï¼ˆä½ çš„ç½‘ç«™ï¼Œå…¬å…±æ–‡ä»¶ç²˜è´´æœåŠ¡ï¼Œåœ¨ + `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上创建的工å•â€¦â€¦ï¼‰ï¼Œ + å¹¶åœ¨ä½ çš„æŠ¥å‘Šä¸æ”¾ä¸Šé“¾æŽ¥ã€‚ç†æƒ³æƒ…况下请使用å…许这些文件ä¿å˜å¾ˆå¤šå¹´çš„åœ°æ–¹ï¼Œå› + 为它们å¯èƒ½åœ¨å¾ˆå¤šå¹´åŽå¯¹åˆ«äººæœ‰ç”¨ï¼›ä¾‹å¦‚ 5 年或 10 å¹´åŽï¼Œä¸€ä¸ªå¼€å‘者æ£åœ¨ä¿®æ”¹ + 一些代ç ，而这些代ç æ£æ˜¯ä¸ºäº†ä¿®å¤ä½ 的问题。 + + * 把文件放在一边，然åŽè¯´æ˜Žä½ 会在他人回å¤æ—¶å†å•ç‹¬å‘é€ã€‚åªè¦è®°å¾—报告å‘出去åŽï¼Œ + 真æ£åšåˆ°è¿™ä¸€ç‚¹å°±å¯ä»¥äº†ã€‚;-) + +æ供这些东西å¯èƒ½æ˜¯æ˜Žæ™ºçš„ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +æ ¹æ®é—®é¢˜çš„ä¸åŒï¼Œä½ å¯èƒ½éœ€è¦æ供更多的背景数æ®ã€‚这里有一些关于æ供什么比较好 +的建议： + + * å¦‚æžœä½ å¤„ç†çš„æ˜¯å†…æ ¸çš„â€œwarningâ€ã€â€œOOPSâ€æˆ–“panicâ€ï¼Œè¯·åŒ…å«å®ƒã€‚å¦‚æžœä½ ä¸èƒ½å¤åˆ¶ + 粘贴它，试ç€ç”¨netconsole网络终端远程跟踪或者至少æ‹ä¸€å¼ å±å¹•çš„照片。 + + * 如果问题å¯èƒ½ä¸Žä½ çš„ç”µè„‘ç¡¬ä»¶æœ‰å…³ï¼Œè¯·è¯´æ˜Žä½ ä½¿ç”¨çš„æ˜¯ä»€ä¹ˆç³»ç»Ÿã€‚ä¾‹å¦‚ï¼Œå¦‚æžœä½ çš„ + 显å¡æœ‰é—®é¢˜ï¼Œè¯·æåŠå®ƒçš„åˆ¶é€ å•†ï¼Œæ˜¾å¡çš„åž‹å·ï¼Œä»¥åŠä½¿ç”¨çš„芯片。如果是笔记本电 + 脑，请æåŠå®ƒçš„åž‹å·å称，但尽é‡ç¡®ä¿æ„义明确。例如“戴尔 XPS 13â€å°±ä¸å¾ˆæ˜Žç¡®ï¼Œ + å› ä¸ºå®ƒå¯èƒ½æ˜¯ 2012 年的那款，那款除了看起æ¥å’ŒçŽ°åœ¨é”€å”®çš„没有什么ä¸åŒä¹‹å¤–， + 两者没有任何共åŒä¹‹å¤„ã€‚å› æ¤ï¼Œåœ¨è¿™ç§æƒ…况下，è¦åŠ 上准确的型å·ï¼Œä¾‹å¦‚ 2019 + 年内推出的 XPS 13 åž‹å·ä¸ºâ€œ9380â€æˆ–“7390â€ã€‚åƒâ€œè”想 Thinkpad T590â€è¿™æ ·çš„åå— + 也有些å«ç³Šä¸æ¸…：这款笔记本有带独立显å¡å’Œä¸å¸¦çš„ååž‹å·ï¼Œæ‰€ä»¥è¦å°½é‡æ‰¾åˆ°å‡†ç¡® + çš„åž‹å·å称或注明主è¦éƒ¨ä»¶ã€‚ + + * 说明æ£åœ¨ä½¿ç”¨çš„ç›¸å…³è½¯ä»¶ã€‚å¦‚æžœä½ åœ¨åŠ è½½æ¨¡å—æ—¶é‡åˆ°äº†é—®é¢˜ï¼Œä½ è¦è¯´æ˜Žæ£åœ¨ä½¿ç”¨çš„ + kmodã€systemd å’Œ udev 的版本。如果其ä¸ä¸€ä¸ª DRM é©±åŠ¨å‡ºçŽ°é—®é¢˜ï¼Œä½ è¦è¯´æ˜Ž + libdrm å’Œ Mesa 的版本；还è¦è¯´æ˜Žä½ çš„ Wayland åˆæˆå™¨æˆ– X-Server åŠå…¶é©±åŠ¨ã€‚ + å¦‚æžœä½ æœ‰æ–‡ä»¶ç³»ç»Ÿé—®é¢˜ï¼Œè¯·æ³¨æ˜Žç›¸åº”çš„æ–‡ä»¶ç³»ç»Ÿå®žç”¨ç¨‹åºçš„版本（e2fsprogs, + btrfs-progs, xfsprogs……）。 + + * ä»Žå†…æ ¸ä¸æ”¶é›†å¯èƒ½æœ‰ç”¨çš„é¢å¤–ä¿¡æ¯ã€‚例如， ``lspci -nn`` 的输出å¯ä»¥å¸®åŠ©åˆ«äºº + è¯†åˆ«ä½ ä½¿ç”¨çš„ç¡¬ä»¶ã€‚å¦‚æžœä½ çš„ç¡¬ä»¶æœ‰é—®é¢˜ï¼Œä½ ç”šè‡³å¯ä»¥ç»™å‡º ``sudo lspci -vvv`` + çš„ç»“æžœï¼Œå› ä¸ºå®ƒæ供了组件是如何é…置的信æ¯ã€‚对于一些问题，å¯èƒ½æœ€å¥½åŒ…å« + ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ， + ``/proc/modules`` 或 ``/proc/scsi/scsi`` ç‰æ–‡ä»¶çš„内容。一些å系统还æ + 供了收集相关信æ¯çš„工具。 ``alsa-info.sh`` `å°±æ˜¯è¿™æ ·ä¸€ä¸ªå·¥å…·ï¼Œå®ƒæ˜¯éŸ³é¢‘/声 + 音å系统开å‘者æ供的 <https://www.alsa-project.org/wiki/AlsaInfo>`_ 。 + +这些例ååº”è¯¥ä¼šç»™ä½ ä¸€äº›çŸ¥è¯†ç‚¹ï¼Œè®©ä½ çŸ¥é“附上什么数æ®å¯èƒ½æ˜¯æ˜Žæ™ºçš„ï¼Œä½†ä½ è‡ªå·±ä¹Ÿ +è¦æƒ³ä¸€æƒ³ï¼Œå“ªäº›æ•°æ®å¯¹åˆ«äººä¼šæœ‰å¸®åŠ©ã€‚ä¸è¦å¤ªæ‹…å¿ƒå¿˜è®°ä¸€äº›ä¸œè¥¿ï¼Œå› ä¸ºå¼€å‘äººå‘˜ä¼šè¦ +求æ供他们需è¦çš„é¢å¤–细节。但从一开始就把所有é‡è¦çš„东西都æ供出æ¥ï¼Œä¼šå¢žåŠ 别 +人仔细查看的机会。 + + +é‡è¦éƒ¨åˆ†ï¼šæŠ¥å‘Šçš„开头 +~~~~~~~~~~~~~~~~~~~~~~ + +çŽ°åœ¨ä½ å·²ç»å‡†å¤‡å¥½äº†æŠ¥å‘Šçš„详细部分，让我们进入最é‡è¦çš„éƒ¨åˆ†ï¼šå¼€å¤´å‡ å¥ã€‚现在到 +报告的最å‰é¢ï¼Œåœ¨ä½ 刚æ‰å†™çš„部分之å‰åŠ 上类似“The detailed description:â€ï¼ˆè¯¦ç»† +æè¿°ï¼‰è¿™æ ·çš„å†…å®¹ï¼Œå¹¶åœ¨æœ€å‰é¢æ’入两个新行。现在写一个æ£å¸¸é•¿åº¦çš„段è½ï¼Œå¤§è‡´æ¦‚ +述这个问题。去掉所有枯燥的细节，把é‡ç‚¹æ”¾åœ¨è¯»è€…需è¦çŸ¥é“的关键部分，以让人了 +è§£è¿™æ˜¯æ€Žä¹ˆå›žäº‹ï¼›å¦‚æžœä½ è®¤ä¸ºè¿™ä¸ªç¼ºé™·å½±å“了很多用户，就æ一下这点æ¥å¸å¼•å¤§å®¶å…³ +注。 + +åšå¥½è¿™ä¸€ç‚¹åŽï¼Œåœ¨é¡¶éƒ¨å†æ’入两行，写一å¥è¯çš„摘è¦ï¼Œå¿«é€Ÿè§£é‡ŠæŠ¥å‘Šçš„内容。之åŽä½ +è¦æ›´åŠ 抽象，为报告写一个更çŸçš„主题/æ ‡é¢˜ã€‚ + +çŽ°åœ¨ä½ å·²ç»å†™å¥½äº†è¿™éƒ¨åˆ†ï¼Œè¯·èŠ±ç‚¹æ—¶é—´æ¥ä¼˜åŒ–å®ƒï¼Œå› ä¸ºå®ƒæ˜¯ä½ çš„æŠ¥å‘Šä¸æœ€é‡è¦çš„部分： +很多人会先读这部分，然åŽæ‰ä¼šå†³å®šæ˜¯å¦å€¼å¾—花时间阅读其他部分。 + +çŽ°åœ¨å°±åƒ :ref:`MAINTAINERS <maintainers>` ç»´æŠ¤è€…æ–‡ä»¶å‘Šè¯‰ä½ çš„é‚£æ ·å‘é€æˆ–æ交 +报告，除éžå®ƒæ˜¯å‰é¢æ¦‚述的那些“高优先级问题â€ä¹‹ä¸€ï¼šåœ¨è¿™ç§æƒ…况下，请先阅读下一 +å°èŠ‚，然åŽå†å‘é€æŠ¥å‘Šã€‚ + +é«˜ä¼˜å…ˆçº§é—®é¢˜çš„ç‰¹æ®Šå¤„ç† +~~~~~~~~~~~~~~~~~~~~~~~~ + +高优先级问题的报告需è¦ç‰¹æ®Šå¤„ç†ã€‚ + +**éžå¸¸ä¸¥é‡çš„缺陷** ：确ä¿åœ¨ä¸»é¢˜æˆ–å·¥å•æ ‡é¢˜ä»¥åŠç¬¬ä¸€æ®µä¸æ˜Žæ˜¾æ ‡å‡º severeness +（éžå¸¸ä¸¥é‡çš„）。 + +**回归** ï¼šå¦‚æžœé—®é¢˜æ˜¯ä¸€ä¸ªå›žå½’ï¼Œè¯·åœ¨é‚®ä»¶çš„ä¸»é¢˜æˆ–ç¼ºé™·è·Ÿè¸ªå™¨çš„æ ‡é¢˜ä¸æ·»åŠ +[REGRESSION]。如果您没有进行二分，请至少注明您测试的最新主线版本（比如 5.7） +和出现问题的最新版本（比如 5.8）。如果您æˆåŠŸåœ°è¿›è¡Œäº†äºŒåˆ†ï¼Œè¯·æ³¨æ˜Žå¯¼è‡´å›žå½’ +çš„æ交IDå’Œä¸»é¢˜ã€‚ä¹Ÿè¯·æ·»åŠ è¯¥å˜æ›´çš„ä½œè€…åˆ°ä½ çš„æŠ¥å‘Šä¸ï¼›å¦‚果您需è¦å°†æ‚¨çš„缺陷æ交 +到缺陷跟踪器ä¸ï¼Œè¯·å°†æŠ¥å‘Šä»¥ç§äººé‚®ä»¶çš„å½¢å¼è½¬å‘给他，并注明报告æ交地点。 + +**安全问题** ：对于这ç§é—®é¢˜ï¼Œä½ 将必须评估：如果细节被公开披露，是å¦ä¼šå¯¹å…¶ä»– +用户产生çŸæœŸé£Žé™©ã€‚如果ä¸ä¼šï¼Œåªéœ€æŒ‰ç…§æ‰€è¿°ç»§ç»æŠ¥å‘Šé—®é¢˜ã€‚如果有æ¤é£Žé™©ï¼Œä½ éœ€è¦ +ç¨å¾®è°ƒæ•´ä¸€ä¸‹æŠ¥å‘Šæµç¨‹ã€‚ + + * 如果 MAINTAINERS 文件指示您通过邮件报告问题，请ä¸è¦æŠ„é€ä»»ä½•å…¬å…±é‚®ä»¶åˆ—表。 + + * å¦‚æžœä½ åº”è¯¥åœ¨ç¼ºé™·è·Ÿè¸ªå™¨ä¸æ交问题，请确ä¿å°†å·¥å•æ ‡è®°ä¸ºâ€œç§æœ‰â€æˆ–“安全问题â€ã€‚ + 如果缺陷跟踪器没有æä¾›ä¿æŒæŠ¥å‘Šç§å¯†æ€§çš„æ–¹æ³•ï¼Œé‚£å°±åˆ«æƒ³äº†ï¼ŒæŠŠä½ çš„æŠ¥å‘Šä»¥ç§äºº + 邮件的形å¼å‘é€ç»™ç»´æŠ¤è€…å§ã€‚ + +在这两ç§æƒ…况下，都一定è¦å°†æŠ¥å‘Šå‘到 MAINTAINERS 文件ä¸â€œå®‰å…¨è”络â€éƒ¨åˆ†åˆ—出的 +地å€ã€‚ç†æƒ³çš„情况是在å‘é€æŠ¥å‘Šçš„时候直接抄é€ä»–们。如果您在缺陷跟踪器ä¸æ交了 +报告，请将报告的文本转å‘到这些地å€ï¼›ä½†è¯·åœ¨æŠ¥å‘Šçš„é¡¶éƒ¨åŠ ä¸Šæ³¨é‡Šï¼Œè¡¨æ˜Žæ‚¨æ交了 +报告，并附上工å•é“¾æŽ¥ã€‚ + +更多信æ¯è¯·å‚è§â€œDocumentation/translations/zh_CN/admin-guide/security-bugs.rstâ€ã€‚ + + +å‘布报告åŽçš„责任 +------------------ + + *ç‰å¾…别人的å应，继ç»æŽ¨è¿›äº‹æƒ…ï¼Œç›´åˆ°ä½ èƒ½å¤ŸæŽ¥å—è¿™æ ·æˆ–é‚£æ ·çš„ç»“æžœã€‚å› æ¤ï¼Œè¯· + 公开和åŠæ—¶åœ°å›žåº”任何询问。测试æ出的修å¤ã€‚积æžåœ°æµ‹è¯•ï¼šè‡³å°‘é‡æ–°æµ‹è¯•æ¯ä¸ª + 新主线版本的首个候选版本（RCï¼‰ï¼Œå¹¶æŠ¥å‘Šä½ çš„ç»“æžœã€‚å¦‚æžœå‡ºçŽ°æ‹–å»¶ï¼Œå°±å‹å¥½åœ° + æé†’ä¸€ä¸‹ã€‚å¦‚æžœä½ æ²¡æœ‰å¾—åˆ°ä»»ä½•å¸®åŠ©æˆ–è€…æœªèƒ½æ»¡æ„，请试ç€è‡ªå·±å¸®åŠ©è‡ªå·±ã€‚* + +å¦‚æžœä½ çš„æŠ¥å‘Šéžå¸¸ä¼˜ç§€ï¼Œè€Œä¸”ä½ çœŸçš„å¾ˆå¹¸è¿ï¼Œé‚£ä¹ˆæŸä¸ªå¼€å‘者å¯èƒ½ä¼šç«‹å³å‘现导致问 +é¢˜çš„åŽŸå› ï¼›ç„¶åŽä»–们å¯èƒ½ä¼šå†™ä¸€ä¸ªè¡¥ä¸æ¥ä¿®å¤ã€æµ‹è¯•å®ƒï¼Œå¹¶ç›´æŽ¥å‘é€ç»™ä¸»çº¿é›†æˆï¼ŒåŒ +æ—¶æ ‡è®°å®ƒä»¥ä¾¿ä»¥åŽå›žæº¯åˆ°éœ€è¦å®ƒçš„稳定版和长期支æŒå†…æ ¸ã€‚é‚£ä¹ˆä½ éœ€è¦åšçš„å°±æ˜¯å›žå¤ +一å¥â€œThank you very muchâ€ï¼ˆéžå¸¸æ„Ÿè°¢ï¼‰ï¼Œç„¶åŽåœ¨å‘布åŽæ¢ä¸Šä¿®å¤å¥½çš„版本。 + +但这ç§ç†æƒ³çŠ¶å†µå¾ˆå°‘å‘ç”Ÿã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ æŠŠæŠ¥å‘Šæ‹¿å‡ºæ¥ä¹‹åŽå·¥ä½œæ‰å¼€å§‹ã€‚ä½ è¦åšçš„ +事情è¦è§†æƒ…况而定，但通常会是下é¢åˆ—å‡ºçš„äº‹æƒ…ã€‚ä½†åœ¨æ·±å…¥ç ”ç©¶ç»†èŠ‚ä¹‹å‰ï¼Œè¿™é‡Œæœ‰å‡ +件é‡è¦çš„äº‹æƒ…ï¼Œä½ éœ€è¦è®°ä½è¿™éƒ¨åˆ†çš„过程。 + + +关于进一æ¥äº’动的一般建议 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**总是公开回å¤** ï¼šå½“ä½ åœ¨ç¼ºé™·è·Ÿè¸ªå™¨ä¸æ交问题时，一定è¦åœ¨é‚£é‡Œå›žå¤ï¼Œä¸è¦ç§ä¸‹ +è”系任何开å‘者。对于邮件报告，在回å¤æ‚¨æ”¶åˆ°çš„任何邮件时，总是使用“全部回å¤â€ +åŠŸèƒ½ã€‚è¿™åŒ…æ‹¬å¸¦æœ‰ä»»ä½•ä½ å¯èƒ½æƒ³è¦æ·»åŠ åˆ°ä½ çš„æŠ¥å‘Šä¸çš„é¢å¤–æ•°æ®çš„邮件：进入邮件应 +用程åºâ€œå·²å‘é€â€æ–‡ä»¶å¤¹ï¼Œå¹¶åœ¨é‚®ä»¶ä¸Šä½¿ç”¨â€œå…¨éƒ¨å›žå¤â€æ¥å›žå¤æŠ¥å‘Šã€‚è¿™ç§æ–¹æ³•å¯ä»¥ç¡®ä¿ +公共邮件列表和其他所有å‚与者都能åŠæ—¶äº†è§£æƒ…况；它还能ä¿æŒé‚®ä»¶çº¿ç¨‹çš„完整性， +这对于邮件列表将所有相关邮件归为一类是éžå¸¸é‡è¦çš„。 + +åªæœ‰ä¸¤ç§æƒ…况ä¸é€‚åˆåœ¨ç¼ºé™·è·Ÿè¸ªå™¨æˆ–“全部回å¤â€ä¸å‘表评论： + + * æœ‰äººè®©ä½ ç§ä¸‹å‘东西。 + + * ä½ è¢«å‘ŠçŸ¥è¦å‘é€ä¸€äº›ä¸œè¥¿ï¼Œä½†æ³¨æ„到其ä¸åŒ…å«éœ€è¦ä¿å¯†çš„æ•æ„Ÿä¿¡æ¯ã€‚在这ç§æƒ…况下， + å¯ä»¥ç§ä¸‹å‘é€ç»™è¦æ±‚å‘é€çš„å¼€å‘者。但è¦åœ¨å·¥å•æˆ–邮件ä¸æ³¨æ˜Žä½ 是这么åšçš„，这 + æ ·å…¶ä»–äººå°±çŸ¥é“ä½ å°Šé‡äº†è¿™ä¸ªè¦æ±‚。 + +**在请求解释或帮助之å‰å…ˆç ”究一下** ：在这部分过程ä¸ï¼Œæœ‰äººå¯èƒ½ä¼šå‘Šè¯‰ä½ 用尚未 +掌æ¡çš„技能åšä¸€äº›äº‹æƒ…ã€‚ä¾‹å¦‚ä½ å¯èƒ½ä¼šè¢«è¦æ±‚ä½¿ç”¨ä¸€äº›ä½ ä»Žæœªå¬è¯´è¿‡çš„测试工具；或 +è€…ä½ å¯èƒ½ä¼šè¢«è¦æ±‚在 Linux å†…æ ¸æºä»£ç 上应用一个补ä¸æ¥æµ‹è¯•å®ƒæ˜¯å¦æœ‰å¸®åŠ©ã€‚在æŸäº› +情况下，å‘个回å¤è¯¢é—®å¦‚何åšå°±å¯ä»¥äº†ã€‚但在走这æ¡è·¯ä¹‹å‰ï¼Œå°½é‡é€šè¿‡åœ¨äº’è”ç½‘ä¸Šæœ +索自行找到ç”案；或者考虑在其他地方询问建议。比如询问朋å‹ï¼Œæˆ–è€…åˆ°ä½ å¹³æ—¶å¸¸åŽ» +çš„èŠå¤©å®¤æˆ–论å›å‘帖咨询。 + +**è¦æœ‰è€å¿ƒ** ï¼šå¦‚æžœä½ çœŸçš„å¾ˆå¹¸è¿ï¼Œä½ å¯èƒ½ä¼šåœ¨å‡ 个å°æ—¶å†…æ”¶åˆ°å¯¹ä½ çš„æŠ¥å‘Šçš„ç”å¤ã€‚ +ä½†å¤§å¤šæ•°æƒ…å†µä¸‹ä¼šèŠ±è´¹æ›´å¤šçš„æ—¶é—´ï¼Œå› ä¸ºç»´æŠ¤è€…åˆ†æ•£åœ¨å…¨çƒå„åœ°ï¼Œå› æ¤å¯èƒ½åœ¨ä¸åŒçš„ +时区——在那里他们已ç»äº«å—ç€è¿œç¦»é”®ç›˜çš„夜晚。 + +一般æ¥è¯´ï¼Œå†…æ ¸å¼€å‘者需è¦ä¸€åˆ°äº”个工作日æ¥å›žå¤æŠ¥å‘Šã€‚æœ‰æ—¶ä¼šèŠ±è´¹æ›´é•¿çš„æ—¶é—´ï¼Œå› +为他们å¯èƒ½æ£å¿™äºŽåˆå¹¶çª—å£ã€å…¶ä»–工作ã€å‚åŠ å¼€å‘者会议，或者åªæ˜¯åœ¨äº«å—一个漫长 +çš„æš‘å‡ã€‚ + +“高优先级的问题â€ï¼ˆè§ä¸Šé¢çš„解释）例外：维护者应该尽快解决这些问题；这就是为 +ä»€ä¹ˆä½ åº”è¯¥æœ€å¤šç‰å¾…一个星期（如果是紧急的事情，则åªéœ€ä¸¤å¤©ï¼‰ï¼Œç„¶åŽå†å‘é€å‹å¥½ +çš„æ醒。 + +有时维护者å¯èƒ½æ²¡æœ‰åŠæ—¶å›žå¤ï¼›æœ‰æ—¶å€™å¯èƒ½ä¼šå‡ºçŽ°åˆ†æ§ï¼Œä¾‹å¦‚一个问题是å¦ç¬¦åˆå›žå½’ +çš„æ¡ä»¶ã€‚在这ç§æƒ…况下，在邮件列表上æå‡ºä½ çš„é¡¾è™‘ï¼Œå¹¶è¯·æ±‚å…¶ä»–äººå…¬å¼€æˆ–ç§ä¸‹å›žå¤ +如何继ç»æŽ¨è¿›ã€‚如果失败了，å¯èƒ½åº”该让更高级别的维护者介入。如果是 WiFi 驱动， +é‚£å°±æ˜¯æ— çº¿ç»´æŠ¤è€…ï¼›å¦‚æžœæ²¡æœ‰æ›´é«˜çº§åˆ«çš„ç»´æŠ¤è€…ï¼Œæˆ–è€…å…¶ä»–ä¸€åˆ‡åŠªåŠ›éƒ½å¤±è´¥äº†ï¼Œé‚£ +è¿™å¯èƒ½æ˜¯ä¸€ç§ç½•è§çš„ã€å¯ä»¥è®© Linus Torvalds å‚与进æ¥çš„情况。 + +**主动测试** ：æ¯å½“ä¸€ä¸ªæ–°çš„ä¸»çº¿å†…æ ¸ç‰ˆæœ¬çš„ç¬¬ä¸€ä¸ªé¢„å‘布版本（rc1）å‘布的时候， +去检查一下这个问题是å¦å¾—到了解决，或者是å¦æœ‰ä»€ä¹ˆé‡è¦çš„å˜åŒ–。在工å•ä¸æˆ–在 +回å¤æŠ¥å‘Šçš„邮件ä¸æåŠç»“果（确ä¿æ‰€æœ‰å‚与讨论的人都被抄é€ï¼‰ã€‚è¿™å°†è¡¨æ˜Žä½ çš„æ‰¿è¯º +å’Œä½ æ„¿æ„帮忙。如果问题æŒç»å˜åœ¨ï¼Œå®ƒä¹Ÿä¼šæ醒开å‘者确ä¿ä»–们ä¸ä¼šå¿˜è®°å®ƒã€‚其他一 +些ä¸å®šæœŸçš„é‡æ–°æµ‹è¯•ï¼ˆä¾‹å¦‚用rc3ã€rc5 和最终版本）也是一个好主æ„，但åªæœ‰åœ¨ç›¸å…³ +的东西å‘生å˜åŒ–æˆ–è€…ä½ æ£åœ¨å†™ä»€ä¹ˆä¸œè¥¿çš„时候æ‰æŠ¥å‘Šä½ 的结果。 + +这些些常规的事情就ä¸è¯´äº†ï¼Œæˆ‘们æ¥è°ˆè°ˆæŠ¥å‘ŠåŽå¦‚何帮助解决问题的细节。 + +查询和测试请求 +~~~~~~~~~~~~~~~ + +å¦‚æžœä½ çš„æŠ¥å‘Šå¾—åˆ°äº†å›žå¤åˆ™éœ€å±¥è¡Œä»¥ä¸‹è´£ä»»ï¼š + +**æ£€æŸ¥ä¸Žä½ æ‰“äº¤é“的人** ：大多数情况下，会是维护者或特定代ç 区域的开å‘人员对 +ä½ çš„æŠ¥å‘Šåšå‡ºå›žåº”。但由于问题通常是公开报告的，所以回å¤çš„å¯èƒ½æ˜¯ä»»ä½•äººâ€”—包括 +那些想è¦å¸®å¿™çš„人，但最åŽå¯èƒ½ä¼šç”¨ä»–ä»¬çš„é—®é¢˜æˆ–è¯·æ±‚å¼•å¯¼ä½ å®Œå…¨å离轨é“。这很少 +å‘生，但这是快速上网æœæœçœ‹ä½ æ£åœ¨ä¸Žè°äº’åŠ¨æ˜¯æ˜Žæ™ºä¹‹ä¸¾çš„è®¸å¤šåŽŸå› ä¹‹ä¸€ã€‚é€šè¿‡è¿™æ · +åšï¼Œä½ 也å¯ä»¥çŸ¥é“ä½ çš„æŠ¥å‘Šæ˜¯å¦è¢«æ£ç¡®çš„人å¬åˆ°ï¼Œå› 为如果讨论没有导致满æ„的问题 +解决方案而淡出，之åŽå¯èƒ½éœ€è¦æ醒维护者（è§ä¸‹æ–‡ï¼‰ã€‚ + +**查询数æ®** ï¼šé€šå¸¸ä½ ä¼šè¢«è¦æ±‚测试一些东西或æ供更多细节。尽快æ供所è¦æ±‚çš„ä¿¡ +æ¯ï¼Œå› ä¸ºä½ å·²ç»å¾—到了å¯èƒ½ä¼šå¸®åŠ©ä½ 的人的注æ„ï¼Œä½ ç‰å¾…的时间越长就有越å¯èƒ½å¤±åŽ» +å…³æ³¨ï¼›å¦‚æžœä½ ä¸åœ¨æ•°ä¸ªå·¥ä½œæ—¥å†…æ供信æ¯ï¼Œç”šè‡³å¯èƒ½å‡ºçŽ°è¿™ç§ç»“果。 + +**测试请求** ï¼šå½“ä½ è¢«è¦æ±‚测试一个诊æ–è¡¥ä¸æˆ–å¯èƒ½çš„ä¿®å¤æ—¶ï¼Œä¹Ÿè¦å°½é‡åŠæ—¶æµ‹è¯•ã€‚ +但è¦åšå¾—æ°å½“，一定ä¸è¦æ€¥äºŽæ±‚æˆï¼šæ··æ·†äº‹æƒ…很容易å‘生，这会给所有人带æ¥è®¸å¤šå›° +惑。例如一个常è§çš„错误是以为应用了一个带修å¤çš„建议补ä¸ï¼Œä½†äº‹å®žä¸Šå¹¶æ²¡æœ‰ã€‚å³ +使是有ç»éªŒçš„测试人员也会å¶å°”å‘ç”Ÿè¿™æ ·çš„äº‹æƒ…ï¼Œä½†å½“æœ‰ä¿®å¤çš„å†…æ ¸å’Œæ²¡æœ‰ä¿®å¤çš„内 +æ ¸è¡¨çŽ°å¾—ä¸€æ ·æ—¶ï¼Œä»–ä»¬å¤§å¤šæ—¶å€™ä¼šæ³¨æ„到。 + +当没有任何实质性进展时该怎么办 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +有些报告ä¸ä¼šå¾—到负有相关责任的 Linux å†…æ ¸å¼€å‘者的任何å应；或者围绕这个问题 +的讨论有所å‘展，但æ¸æ¸æ·¡å‡ºï¼Œæ²¡æœ‰ä»»ä½•å®žè´¨å†…容产出。 + +在这ç§æƒ…况下，è¦ç‰ä¸¤ä¸ªæ˜ŸæœŸï¼ˆæœ€å¥½æ˜¯ä¸‰ä¸ªæ˜ŸæœŸï¼‰åŽå†å‘出å‹å¥½çš„æé†’ï¼šä¹Ÿè®¸å½“ä½ çš„ +报告到达时，维护者刚刚离开键盘一段时间，或者有更é‡è¦çš„事情è¦å¤„ç†ã€‚在写æ醒 +信的时候，è¦å–„æ„地问一下，是å¦è¿˜éœ€è¦ä½ 这边æ供什么æ¥è®©äº‹æƒ…推进下去。如果报 +告是通过邮件å‘出æ¥çš„，那就在邮件的第一行回å¤ä½ çš„åˆå§‹é‚®ä»¶ï¼ˆè§ä¸Šæ–‡ï¼‰ï¼Œå…¶ä¸åŒ… +æ‹¬ä¸‹æ–¹çš„åŽŸå§‹æŠ¥å‘Šçš„å®Œæ•´å¼•ç”¨ï¼šè¿™æ˜¯å°‘æ•°å‡ ç§æƒ…å†µä¸‹ï¼Œè¿™æ ·çš„â€œTOFUâ€ï¼ˆText Over, +Fullquote Underæ–‡å—在上，完整引用在下）是æ£ç¡®çš„åšæ³•ï¼Œå› ä¸ºè¿™æ ·æ‰€æœ‰çš„æ”¶ä»¶äººéƒ½ +会以适当的顺åºç«‹å³è®©ç»†èŠ‚到手头上æ¥ã€‚ + +在æ醒之åŽï¼Œå†ç‰ä¸‰å‘¨çš„回å¤ã€‚å¦‚æžœä½ ä»ç„¶æ²¡æœ‰å¾—到适当的åé¦ˆï¼Œä½ é¦–å…ˆåº”è¯¥é‡æ–°è€ƒ +è™‘ä½ çš„æ–¹æ³•ã€‚ä½ æ˜¯å¦å¯èƒ½å°è¯•æŽ¥è§¦äº†é”™è¯¯çš„人？是ä¸æ˜¯æŠ¥å‘Šä¹Ÿè®¸ä»¤äººå感或者太混乱， +ä»¥è‡³äºŽäººä»¬å†³å®šå®Œå…¨è¿œç¦»å®ƒï¼ŸæŽ’é™¤è¿™äº›å› ç´ çš„æœ€å¥½æ–¹æ³•æ˜¯ï¼šæŠŠæŠ¥å‘Šç»™ä¸€ä¸¤ä¸ªç†Ÿæ‚‰ +FLOSS 问题报告的人看，询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚他们关于如何继ç»æŽ¨è¿›çš„建议。 +è¿™å¯èƒ½æ„味ç€ï¼šå‡†å¤‡ä¸€ä»½æ›´å¥½çš„æŠ¥å‘Šï¼Œè®©è¿™äº›äººåœ¨ä½ å‘出去之å‰å¯¹å®ƒè¿›è¡Œå®¡æŸ¥ã€‚è¿™æ · +的方法完全å¯ä»¥ï¼›åªéœ€è¯´æ˜Žè¿™æ˜¯å…³äºŽè¿™ä¸ªé—®é¢˜çš„第二份改进的报告，并附上第一份报 +告的链接。 + +如果报告是æ°å½“çš„ï¼Œä½ å¯ä»¥å‘é€ç¬¬äºŒå°æ醒信；在其ä¸è¯¢é—®ä¸ºä»€ä¹ˆæŠ¥å‘Šæ²¡æœ‰å¾—到任何 +回å¤ã€‚第二å°æ醒邮件的好时机是在新 Linux å†…æ ¸ç‰ˆæœ¬çš„é¦–ä¸ªé¢„å‘布版本（'rc1'） +å‘布åŽä¸ä¹…ï¼Œå› ä¸ºæ— è®ºå¦‚ä½•ä½ éƒ½åº”è¯¥åœ¨é‚£ä¸ªæ—¶å€™é‡æ–°æµ‹è¯•å¹¶æ供状æ€æ›´æ–°ï¼ˆè§ä¸Šæ–‡ï¼‰ã€‚ + +如果第二次æ醒的结果åˆåœ¨ä¸€å‘¨å†…没有任何å应，å¯ä»¥å°è¯•è”系上级维护者询问æ„è§ï¼š +å³ä½¿å†å¿™çš„维护者在这时候也至少应该å‘过æŸç§ç¡®è®¤ã€‚ + +è®°ä½è¦åšå¥½å¤±æœ›çš„准备：ç†æƒ³çŠ¶å†µä¸‹ç»´æŠ¤è€…最好对æ¯ä¸€ä¸ªé—®é¢˜æŠ¥å‘Šåšå‡ºå›žåº”，但他们 +åªæœ‰ä¹‰åŠ¡è§£å†³ä¹‹å‰åˆ—出的“高优先级问题â€ã€‚æ‰€ä»¥ï¼Œå¦‚æžœä½ å¾—åˆ°çš„å›žå¤æ˜¯â€œè°¢è°¢ä½ 的报告， +我目å‰æœ‰æ›´é‡è¦çš„问题è¦å¤„ç†ï¼Œåœ¨å¯é¢„è§çš„未æ¥æ²¡æœ‰æ—¶é—´åŽ»ç ”究这个问题â€ï¼Œé‚£è¯·ä¸ +è¦å¤ªæ²®ä¸§ã€‚ + +也有å¯èƒ½åœ¨ç¼ºé™·è·Ÿè¸ªå™¨æˆ–列表ä¸è¿›è¡Œäº†ä¸€äº›è®¨è®ºä¹‹åŽï¼Œä»€ä¹ˆéƒ½æ²¡æœ‰å‘生，æé†’ä¹Ÿæ— åŠ© +于激励大家进行修å¤ã€‚è¿™ç§æƒ…况å¯èƒ½æ˜¯æ¯ç性的，但在 Linux å†…æ ¸å¼€å‘ä¸ç¡®å®žä¼šå‘生。 +这些和其他得ä¸åˆ°å¸®åŠ©çš„åŽŸå› åœ¨æœ¬æ–‡ç»“å°¾å¤„çš„â€œä¸ºä»€ä¹ˆæœ‰äº›é—®é¢˜åœ¨è¢«æŠ¥å‘ŠåŽæ²¡æœ‰å¾—到 +任何回应或者ä»ç„¶æ²¡æœ‰ä¿®å¤â€ä¸è¿›è¡Œäº†è§£é‡Šã€‚ + +å¦‚æžœä½ æ²¡æœ‰å¾—åˆ°ä»»ä½•å¸®åŠ©æˆ–é—®é¢˜æœ€ç»ˆæ²¡æœ‰å¾—åˆ°è§£å†³ï¼Œä¸è¦æ²®ä¸§ï¼šLinux å†…æ ¸æ˜¯ FLOSS， +å› æ¤ä½ ä»ç„¶å¯ä»¥è‡ªå·±å¸®åŠ©è‡ªå·±ã€‚ä¾‹å¦‚ï¼Œä½ å¯ä»¥è¯•ç€æ‰¾åˆ°å…¶ä»–å—å½±å“的人，和他们一 +èµ·åˆä½œæ¥è§£å†³è¿™ä¸ªé—®é¢˜ã€‚è¿™æ ·çš„å›¢é˜Ÿå¯ä»¥ä¸€èµ·å‡†å¤‡ä¸€ä»½æ–°çš„报告，æ到团队有多少人， +ä¸ºä»€ä¹ˆä½ ä»¬è®¤ä¸ºè¿™æ˜¯åº”è¯¥å¾—åˆ°è§£å†³çš„äº‹æƒ…ã€‚ä¹Ÿè®¸ä½ ä»¬è¿˜å¯ä»¥ä¸€èµ·ç¼©å°ç¡®åˆ‡åŽŸå› 或引 +入回归的å˜åŒ–，这往往会使修å¤æ›´å®¹æ˜“。而且如果è¿æ°”好的è¯ï¼Œå›¢é˜Ÿä¸å¯èƒ½ä¼šæœ‰æ‡‚点 +编程的人，也许能写出一个修å¤æ–¹æ¡ˆã€‚ + + + +“报告稳定版和长期支æŒå†…æ ¸çº¿çš„å›žå½’â€çš„å‚考 +------------------------------------------ + +本å°èŠ‚æ供了在稳定版和长期支æŒå†…æ ¸çº¿ä¸é¢å¯¹å›žå½’时需è¦æ‰§è¡Œçš„æ¥éª¤çš„详细信æ¯ã€‚ + +ç¡®ä¿ç‰¹å®šç‰ˆæœ¬çº¿ä»ç„¶å—æ”¯æŒ +~~~~~~~~~~~~~~~~~~~~~~~~~ + + *æ£€æŸ¥å†…æ ¸å¼€å‘人员是å¦ä»ç„¶ç»´æŠ¤ä½ 关心的Linuxå†…æ ¸ç‰ˆæœ¬çº¿ï¼šåŽ» kernel.org çš„ + 首页，确ä¿æ¤ç‰¹å®šç‰ˆæœ¬çº¿çš„最新版没有“[EOL]â€æ ‡è®°ã€‚* + +å¤§å¤šæ•°å†…æ ¸ç‰ˆæœ¬çº¿åªæ”¯æŒä¸‰ä¸ªæœˆå·¦å³ï¼Œå› 为延长维护时间会带æ¥ç›¸å½“å¤šçš„å·¥ä½œã€‚å› æ¤ï¼Œ +æ¯å¹´åªä¼šé€‰æ‹©ä¸€ä¸ªç‰ˆæœ¬æ¥æ”¯æŒè‡³å°‘两年（通常是å…å¹´ï¼‰ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ éœ€è¦æ£€æŸ¥ +å†…æ ¸å¼€å‘者是å¦è¿˜æ”¯æŒä½ 关心的版本线。 + +注æ„，如果 `kernel.org <https://kernel.org/>`_ 在首页上列出了两个“稳定â€ç‰ˆæœ¬ï¼Œ +ä½ åº”è¯¥è€ƒè™‘åˆ‡æ¢åˆ°è¾ƒæ–°çš„版本，而忘掉较旧的版本：对它的支æŒå¯èƒ½å¾ˆå¿«å°±ä¼šç»“æŸã€‚ +然åŽï¼Œå®ƒå°†è¢«æ ‡è®°ä¸ºâ€œç”Ÿå‘½å‘¨æœŸç»“æŸâ€ï¼ˆEOL）。达到这个程度的版本线ä»ç„¶ä¼šåœ¨ +`kernel.org <https://kernel.org/>`_ 首页上被显示一两周，但ä¸é€‚åˆç”¨äºŽæµ‹è¯•å’Œ +报告。 + +æœç´¢ç¨³å®šç‰ˆé‚®ä»¶åˆ—表 +~~~~~~~~~~~~~~~~~~~ + + *检查Linux稳定版邮件列表ä¸çš„现有报告。* + +ä¹Ÿè®¸ä½ æ‰€é¢ä¸´çš„问题已ç»è¢«å‘现，并且已ç»æˆ–å³å°†è¢«ä¿®å¤ã€‚å› æ¤ï¼Œè¯·åœ¨ `Linux 稳定 +版邮件列表的档案 <https://lore.kernel.org/stable/>`_ ä¸æœç´¢ç±»ä¼¼é—®é¢˜çš„报告。 +å¦‚æžœä½ æ‰¾åˆ°ä»»ä½•åŒ¹é…的问题，å¯ä»¥è€ƒè™‘åŠ å…¥è®¨è®ºï¼Œé™¤éžä¿®å¤å·¥ä½œå·²ç»å®Œæˆå¹¶è®¡åˆ’很快 +得到应用。 + +用最新版本å¤çŽ°é—®é¢˜ +~~~~~~~~~~~~~~~~~~~ + + *ä»Žç‰¹å®šçš„ç‰ˆæœ¬çº¿å®‰è£…æœ€æ–°ç‰ˆæœ¬ä½œä¸ºçº¯å‡€å†…æ ¸ã€‚ç¡®ä¿è¿™ä¸ªå†…æ ¸æ²¡æœ‰è¢«æ±¡æŸ“ï¼Œå¹¶ä¸”ä» + 然å˜åœ¨é—®é¢˜ï¼Œå› 为问题å¯èƒ½å·²ç»åœ¨é‚£é‡Œè¢«ä¿®å¤äº†ã€‚* + +在投入更多时间到这个过程ä¸ä¹‹å‰ï¼Œä½ è¦æ£€æŸ¥è¿™ä¸ªé—®é¢˜æ˜¯å¦åœ¨ä½ 关注的版本线的最新 +版本ä¸å·²ç»å¾—到了修å¤ã€‚è¿™ä¸ªå†…æ ¸éœ€è¦æ˜¯çº¯å‡€çš„，在问题å‘生之å‰ä¸åº”è¯¥è¢«æ±¡æŸ“ï¼Œæ£ +如上é¢å·²ç»åœ¨æµ‹è¯•ä¸»çº¿çš„过程ä¸è¯¦ç»†ä»‹ç»è¿‡çš„ä¸€æ ·ã€‚ + +您是å¦æ˜¯ç¬¬ä¸€æ¬¡æ³¨æ„åˆ°ä¾›åº”å•†å†…æ ¸çš„å›žå½’ï¼Ÿä¾›åº”å•†çš„æ›´æ”¹å¯èƒ½ä¼šå‘生å˜åŒ–ã€‚ä½ éœ€è¦é‡æ–° +检查排除æ¥è¿™ä¸ªé—®é¢˜ã€‚当您从5.10.4-vendor.42更新到5.10.5-vendor.43时，记录æŸå +çš„ä¿¡æ¯ã€‚然åŽåœ¨æµ‹è¯•äº†å‰ä¸€æ®µä¸æ‰€è¿°çš„最新5.10版本之åŽï¼Œæ£€æŸ¥Linux 5.10.4的普通版本 +是å¦ä¹Ÿå¯ä»¥æ£å¸¸å·¥ä½œã€‚如果问题在那里出现，那就ä¸ç¬¦åˆä¸Šæ¸¸å›žå½’çš„æ¡ä»¶ï¼Œæ‚¨éœ€è¦åˆ‡æ¢ +回主é€æ¥æŒ‡å—æ¥æŠ¥å‘Šé—®é¢˜ã€‚ + +报告回归 +~~~~~~~~~~ + + *å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸçš„问题报告(stable@vger.kernel.org)。 + 大致æ述问题，并解释如何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ£å¸¸ + 的版本。然åŽç‰å¾…进一æ¥çš„指示。* + +当报告在稳定版或长期支æŒå†…æ ¸çº¿å†…å‘生的回归（例如在从5.10.4更新到5.10.5时）， +一份简çŸçš„æŠ¥å‘Šè¶³ä»¥å¿«é€ŸæŠ¥å‘Šé—®é¢˜ã€‚å› æ¤åªéœ€è¦ç²—略的æ述。 + +但是请注æ„，如果您能够指明引入问题的确切版本，这将对开å‘äººå‘˜æœ‰å¾ˆå¤§å¸®åŠ©ã€‚å› æ¤ +如果有时间的è¯ï¼Œè¯·å°è¯•ä½¿ç”¨æ™®é€šå†…æ ¸æ‰¾åˆ°è¯¥ç‰ˆæœ¬ã€‚è®©æˆ‘ä»¬å‡è®¾å‘行版å‘布Linuxå†…æ ¸ +5.10.5到5.10.8çš„æ›´æ–°æ—¶å‘生了故障。那么按照上é¢çš„指示，去检查该版本线ä¸çš„最新 +å†…æ ¸ï¼Œæ¯”å¦‚5.10.9。如果问题出现，请å°è¯•æ™®é€š5.10.5，以确ä¿ä¾›åº”商应用的补ä¸ä¸ä¼š +干扰。如果问题没有出现，那么å°è¯•5.10.7，然åŽç›´åˆ°5.10.8或5.10.6（å–决于结果） +找到第一个引入问题的版本。在报告ä¸å†™æ˜Žè¿™ä¸€ç‚¹ï¼Œå¹¶æŒ‡å‡º5.10.9ä»ç„¶å˜åœ¨æ•…障。 + +å‰ä¸€æ®µåŸºæœ¬ç²—略地概述了“二分â€æ–¹æ³•ã€‚一旦报告出æ¥ï¼Œæ‚¨å¯èƒ½ä¼šè¢«è¦æ±‚åšä¸€ä¸ªæ£ç¡®çš„ +æŠ¥å‘Šï¼Œå› ä¸ºå®ƒå…许精确地定ä½å¯¼è‡´é—®é¢˜çš„确切更改（然åŽå¾ˆå®¹æ˜“被æ¢å¤ä»¥å¿«é€Ÿä¿®å¤é—®é¢˜ï¼‰ã€‚ +å› æ¤å¦‚果时间å…许，考虑立å³è¿›è¡Œé€‚当的二分。有关如何详细信æ¯ï¼Œè¯·å‚阅“对回归的 +特别关照â€éƒ¨åˆ†å’Œæ–‡æ¡£â€œDocumentation/translations/zh_CN/admin-guide/bug-bisect.rstâ€ã€‚ + + +â€œæŠ¥å‘Šä»…åœ¨æ—§å†…æ ¸ç‰ˆæœ¬çº¿ä¸å‘生的问题â€çš„å‚考 +---------------------------------------- + +本节详细介ç»äº†å¦‚æžœæ— æ³•ç”¨ä¸»çº¿å†…æ ¸é‡çŽ°é—®é¢˜ï¼Œä½†å¸Œæœ›åœ¨æ—§ç‰ˆæœ¬çº¿ï¼ˆåˆç§°ç¨³å®šç‰ˆå†…æ ¸å’Œ +长期支æŒå†…æ ¸ï¼‰ä¸ä¿®å¤é—®é¢˜æ—¶éœ€è¦é‡‡å–çš„æ¥éª¤ã€‚ + +有些修å¤å¤ªå¤æ‚ +~~~~~~~~~~~~~~~ + + *请åšå¥½å‡†å¤‡ï¼ŒæŽ¥ä¸‹æ¥çš„å‡ ä¸ªæ¥éª¤å¯èƒ½æ— 法在旧版本ä¸è§£å†³é—®é¢˜ï¼šä¿®å¤å¯èƒ½å¤ªå¤§æˆ– + å¤ªå†’é™©ï¼Œæ— æ³•ç§»æ¤åˆ°é‚£é‡Œã€‚* + +å³ä½¿æ˜¯å¾®å°çš„ã€çœ‹ä¼¼æ˜Žæ˜¾çš„代ç å˜åŒ–，有时也会带æ¥æ–°çš„ã€å®Œå…¨æ„想ä¸åˆ°çš„问题。稳 +定版和长期支æŒå†…æ ¸çš„ç»´æŠ¤è€…éžå¸¸æ¸…æ¥šè¿™ä¸€ç‚¹ï¼Œå› æ¤ä»–们åªå¯¹è¿™äº›å†…æ ¸è¿›è¡Œç¬¦åˆ +“Documentation/translations/zh_CN/process/stable-kernel-rules.rstâ€ä¸æ‰€åˆ—出的 +规则的修改。 + +å¤æ‚或有风险的修改ä¸ç¬¦åˆæ¡ä»¶ï¼Œå› æ¤åªèƒ½åº”用于主线。其他的修å¤å¾ˆå®¹æ˜“被回溯到 +最新的稳定版和长期支æŒå†…æ ¸ï¼Œä½†æ˜¯é£Žé™©å¤ªå¤§ï¼Œæ— æ³•é›†æˆåˆ°æ—§ç‰ˆå†…æ ¸ä¸ã€‚所以è¦æ³¨æ„ +ä½ æ‰€å¸Œæœ›çš„ä¿®å¤å¯èƒ½æ˜¯é‚£äº›ä¸ä¼šè¢«å›žæº¯åˆ°ä½ 所关心的版本线的修å¤ä¹‹ä¸€ã€‚在这ç§æƒ…况 +ä¸‹ï¼Œä½ å°†åˆ«æ— é€‰æ‹©ï¼Œè¦ä¹ˆå¿å—这个问题，è¦ä¹ˆåˆ‡æ¢åˆ°ä¸€ä¸ªè¾ƒæ–°çš„ Linux 版本，除éžä½ +想自己把修å¤è¡¥ä¸åº”ç”¨åˆ°ä½ çš„å†…æ ¸ä¸ã€‚ + +通用准备 +~~~~~~~~~~ + + *执行上é¢â€œæŠ¥å‘Šä»…åœ¨æ—§å†…æ ¸ç‰ˆæœ¬çº¿ä¸å‘生的问题â€ä¸€èŠ‚ä¸çš„å‰ä¸‰ä¸ªæ¥éª¤ã€‚* + +您需è¦æ‰§è¡Œæœ¬æŒ‡å—å¦ä¸€èŠ‚ä¸å·²ç»æè¿°çš„å‡ ä¸ªæ¥éª¤ã€‚这些æ¥éª¤å°†è®©æ‚¨ï¼š + + * æ£€æŸ¥å†…æ ¸å¼€å‘人员是å¦ä»ç„¶ç»´æŠ¤æ‚¨å…³å¿ƒçš„Linuxå†…æ ¸ç‰ˆæœ¬è¡Œã€‚ + + * 在Linux稳定邮件列表ä¸æœç´¢é€€å‡ºçš„报告。 + + * 检查最新版本。 + + +检查代ç 历å²å’Œæœç´¢çŽ°æœ‰çš„讨论 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *在Linuxå†…æ ¸ç‰ˆæœ¬æŽ§åˆ¶ç³»ç»Ÿä¸æœç´¢ä¿®å¤ä¸»çº¿é—®é¢˜çš„æ›´æ”¹ï¼Œå› ä¸ºå®ƒçš„æ交消æ¯å¯èƒ½ + ä¼šå‘Šè¯‰ä½ ä¿®å¤æ˜¯å¦å·²ç»è®¡åˆ’好了支æŒã€‚å¦‚æžœä½ æ²¡æœ‰æ‰¾åˆ°ï¼Œæœç´¢é€‚当的邮件列表， + 寻找讨论æ¤ç±»é—®é¢˜æˆ–åŒè¡Œè¯„è®®å¯èƒ½ä¿®å¤çš„帖å；然åŽæ£€æŸ¥è®¨è®ºæ˜¯å¦è®¤ä¸ºä¿®å¤ä¸é€‚ + åˆæ”¯æŒã€‚如果支æŒæ ¹æœ¬ä¸è¢«è€ƒè™‘ï¼ŒåŠ å…¥æœ€æ–°çš„è®¨è®ºï¼Œè¯¢é—®æ˜¯å¦æœ‰å¯èƒ½ã€‚* + +åœ¨è®¸å¤šæƒ…å†µä¸‹ï¼Œä½ æ‰€å¤„ç†çš„问题会å‘生在主线上，但已在主线上得到了解决。修æ£å®ƒ +çš„æ交也需è¦è¢«å›žæº¯æ‰èƒ½è§£å†³è¿™ä¸ªé—®é¢˜ã€‚è¿™å°±æ˜¯ä¸ºä»€ä¹ˆä½ è¦æœç´¢å®ƒæˆ–任何相关讨论。 + + * 首先å°è¯•åœ¨å˜æ”¾ Linux å†…æ ¸æºä»£ç çš„ Git 仓库ä¸æ‰¾åˆ°ä¿®å¤ã€‚ä½ å¯ä»¥é€šè¿‡ + `kernel.org 上的网页 + <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ + 或 `GitHub ä¸Šçš„é•œåƒ <https://github.com/torvalds/linux>`_ æ¥å®žçŽ°ï¼›å¦‚æžœä½ + æœ‰ä¸€ä¸ªæœ¬åœ°å…‹éš†ï¼Œä½ ä¹Ÿå¯ä»¥åœ¨å‘½ä»¤è¡Œç”¨ ``git log --grep=<pattern>`` æ¥æœç´¢ã€‚ + + å¦‚æžœä½ æ‰¾åˆ°äº†ä¿®å¤ï¼Œè¯·æŸ¥çœ‹æ交消æ¯çš„尾部是å¦åŒ…å«äº†ç±»ä¼¼è¿™æ ·çš„â€œç¨³å®šç‰ˆæ ‡ç¾â€ï¼š + + Cc: <stable@vger.kernel.org> # 5.4+ + + åƒä¸Šé¢è¿™è¡Œï¼Œå¼€å‘è€…æ ‡è®°äº†å®‰å…¨ä¿®å¤å¯ä»¥å›žä¼ 到 5.4 åŠä»¥åŽçš„版本。大多数情况 + 下，它会在两周内被应用到那里，但有时需è¦æ›´é•¿çš„时间。 + + * 如果æäº¤æ²¡æœ‰å‘Šè¯‰ä½ ä»»ä½•ä¸œè¥¿ï¼Œæˆ–è€…ä½ æ‰¾ä¸åˆ°ä¿®å¤ï¼Œè¯·å†æ‰¾æ‰¾å…³äºŽè¿™ä¸ªé—®é¢˜çš„讨论。 + ç”¨ä½ æœ€å–œæ¬¢çš„æœç´¢å¼•æ“Žæœç´¢ç½‘ç»œï¼Œä»¥åŠ `Linux kernel developers mailing + list å†…æ ¸å¼€å‘者邮件列表 <https://lore.kernel.org/lkml/>`_ 的档案。也å¯ä»¥ + 阅读上é¢çš„ `定ä½å¯¼è‡´é—®é¢˜çš„å†…æ ¸åŒºåŸŸ` 一节，然åŽæŒ‰ç…§è¯´æ˜Žæ‰¾åˆ°å¯¼è‡´é—®é¢˜çš„åç³» + 统：它的缺陷跟踪器或邮件列表å˜æ¡£ä¸å¯èƒ½æœ‰ä½ è¦æ‰¾çš„ç”案。 + + * å¦‚æžœä½ çœ‹åˆ°äº†ä¸€ä¸ªè®¡åˆ’çš„ä¿®å¤ï¼Œè¯·æŒ‰ä¸Šæ‰€è¿°åœ¨ç‰ˆæœ¬æŽ§åˆ¶ç³»ç»Ÿä¸æœç´¢å®ƒï¼Œå› 为æäº¤å¯ + èƒ½ä¼šå‘Šè¯‰ä½ æ˜¯å¦å¯ä»¥è¿›è¡Œå›žæº¯ã€‚ + + * 检查讨论ä¸æ˜¯å¦æœ‰ä»»ä½•è¿¹è±¡è¡¨æ˜Žï¼Œè¯¥ä¿®å¤ç¨‹åºå¯èƒ½é£Žé™©å¤ªå¤§ï¼Œæ— æ³•å›žæº¯åˆ°ä½ å…³å¿ƒ + çš„ç‰ˆæœ¬çº¿ã€‚å¦‚æžœæ˜¯è¿™æ ·çš„è¯ï¼Œä½ å¿…é¡»å¿å—这个问题，或者切æ¢åˆ°åº”用了修å¤çš„内 + æ ¸ç‰ˆæœ¬çº¿ã€‚ + + * 如果修å¤çš„问题未包å«ç¨³å®šç‰ˆæ ‡ç¾ï¼Œå¹¶ä¸”æ²¡æœ‰è®¨è®ºè¿‡å›žæº¯é—®é¢˜ï¼Œè¯·åŠ å…¥è®¨è®ºï¼šå¦‚ + æžœåˆé€‚çš„è¯ï¼Œè¯·æåŠä½ 所é¢å¯¹çš„问题的版本，以åŠä½ 希望看到它被修å¤ã€‚ + + +请求建议 +~~~~~~~~~ + + *å‰é¢çš„æ¥éª¤ä¹‹ä¸€åº”该会给出一个解决方案。如果ä»æœªèƒ½æˆåŠŸï¼Œè¯·å‘å¯èƒ½å¼•èµ·é—®é¢˜ + çš„å系统的维护人员询问建议；抄é€ç‰¹å®šå系统的邮件列表以åŠç¨³å®šç‰ˆé‚®ä»¶åˆ—表。* + +如果å‰é¢çš„三个æ¥éª¤éƒ½æ²¡æœ‰è®©ä½ 更接近解决方案，那么åªå‰©ä¸‹ä¸€ä¸ªé€‰æ‹©ï¼šè¯·æ±‚建议。 +åœ¨ä½ å‘ç»™å¯èƒ½æ˜¯é—®é¢˜æ ¹æºçš„å系统的维护者的邮件ä¸è¿™æ ·åšï¼›æŠ„é€å系统的邮件列表 +以åŠç¨³å®šç‰ˆé‚®ä»¶åˆ—表（stable@vger.kernel.org）。 + + +为什么有些问题在报告åŽæ²¡æœ‰ä»»ä½•å›žåº”或ä»æœªè§£å†³ï¼Ÿ +=============================================== + +å½“å‘ Linux å¼€å‘者报告问题时，è¦æ³¨æ„åªæœ‰â€œé«˜ä¼˜å…ˆçº§çš„问题â€ï¼ˆå›žå½’ã€å®‰å…¨é—®é¢˜ã€ä¸¥ +é‡é—®é¢˜ï¼‰æ‰ä¸€å®šä¼šå¾—到解决。如果维护者或其他人都失败了，Linus Torvalds 他自己 +会确ä¿è¿™ä¸€ç‚¹ã€‚ä»–ä»¬å’Œå…¶ä»–å†…æ ¸å¼€å‘者也会解决很多其他问题。但是è¦çŸ¥é“，有时他 +们也会ä¸èƒ½æˆ–ä¸æ„¿å¸®å¿™ï¼›æœ‰æ—¶ç”šè‡³æ²¡æœ‰äººå‘报告给他们。 + +æœ€å¥½çš„è§£é‡Šå°±æ˜¯é‚£äº›å†…æ ¸å¼€å‘者常常是在业余时间为 Linux å†…æ ¸åšå‡ºè´¡çŒ®ã€‚å†…æ ¸ä¸çš„ +ä¸å°‘驱动程åºéƒ½æ˜¯ç”±è¿™æ ·çš„程åºå‘˜ç¼–写的，往往åªæ˜¯å› 为他们想让自己的硬件å¯ä»¥åœ¨ +自己喜欢的æ“作系统上使用。 + +这些程åºå‘˜å¤§å¤šæ•°æ—¶å€™ä¼šå¾ˆä¹æ„ä¿®å¤åˆ«äººæŠ¥å‘Šçš„问题。但是没有人å¯ä»¥å¼ºè¿«ä»–ä»¬è¿™æ · +åšï¼Œå› 为他们是自愿贡献的。 + +还有一些情况下，这些开å‘者真的很想解决一个问题，但å´ä¸èƒ½è§£å†³ï¼šæœ‰æ—¶ä»–ä»¬ç¼ºä¹ +硬件编程文档æ¥è§£å†³é—®é¢˜ã€‚è¿™ç§æƒ…况往往由于公开的文档太简陋，或者驱动程åºæ˜¯é€š +过逆å‘工程编写的。 + +业余开å‘者迟早也会ä¸å†å…³å¿ƒæŸé©±åŠ¨ã€‚也许他们的测试硬件å了，被更高级的玩æ„å– +代了，或者是太è€äº†ä»¥è‡³äºŽåªèƒ½åœ¨è®¡ç®—机åšç‰©é¦†é‡Œæ‰¾åˆ°ã€‚有时开å‘è€…æ ¹æœ¬å°±ä¸å…³å¿ƒä»– +们的代ç å’Œ Linux äº†ï¼Œå› ä¸ºåœ¨ä»–ä»¬çš„ç”Ÿæ´»ä¸ä¸€äº›ä¸åŒçš„东西å˜å¾—æ›´é‡è¦äº†ã€‚在æŸäº›æƒ… +况下，没有人愿æ„接手维护者的工作——也没有人å¯ä»¥è¢«å¼ºè¿«ï¼Œå› 为对 Linux å†…æ ¸çš„è´¡ +献是自愿的。然而被é—弃的驱动程åºä»ç„¶å˜åœ¨äºŽå†…æ ¸ä¸ï¼šå®ƒä»¬å¯¹äººä»¬ä»ç„¶æœ‰ç”¨ï¼Œåˆ 除 +它们å¯èƒ½å¯¼è‡´å›žå½’。 + +对于那些为 Linux å†…æ ¸å·¥ä½œè€ŒèŽ·å¾—æŠ¥é…¬çš„å¼€å‘者æ¥è¯´ï¼Œæƒ…况并没有什么ä¸åŒã€‚这些人 +现在贡献了大部分的å˜æ›´ã€‚但是他们的雇主迟早也会åœæ¢å…³æ³¨ä»–们的代ç æˆ–è€…è®©ç¨‹åº +员专注于其他事情。例如，硬件厂商主è¦é€šè¿‡é”€å”®æ–°ç¡¬ä»¶æ¥èµšé’±ï¼›å› æ¤ï¼Œä»–们ä¸çš„ä¸ +少人并没有投入太多时间和精力æ¥ç»´æŠ¤ä»–们多年å‰å°±åœæ¢é”€å”®çš„东西的 Linux å†…æ ¸é©± +动。ä¼ä¸šçº§ Linux å‘行商往往æŒç»ç»´æŠ¤çš„时间比较长，但在新版本ä¸å¾€å¾€ä¼šæŠŠå¯¹è€æ—§ +和稀有硬件的支æŒæ”¾åœ¨ä¸€è¾¹ï¼Œä»¥é™åˆ¶èŒƒå›´ã€‚一旦公å¸æŠ›å¼ƒäº†ä¸€äº›ä»£ç ，往往由业余贡 +献者接手，但æ£å¦‚上é¢æ到的：他们迟早也会放下代ç 。 + +优先级是一些问题没有被修å¤çš„å¦ä¸€ä¸ªåŽŸå› ï¼Œå› ä¸ºç»´æŠ¤è€…ç›¸å½“å¤šçš„æ—¶å€™æ˜¯è¢«è¿«è®¾ç½®è¿™ +äº›ä¼˜å…ˆçº§çš„ï¼Œå› ä¸ºåœ¨ Linux 上工作的时间是有é™çš„。对于业余时间或者雇主给予他们 +çš„å¼€å‘äººå‘˜ç”¨äºŽä¸Šæ¸¸å†…æ ¸ç»´æŠ¤å·¥ä½œçš„æ—¶é—´ä¹Ÿæ˜¯å¦‚æ¤ã€‚有时维护人员也会被报告淹没， +å³ä½¿ä¸€ä¸ªé©±åŠ¨ç¨‹åºå‡ 乎完美地工作。为了ä¸è¢«å®Œå…¨ç¼ ä½ï¼Œç¨‹åºå‘˜å¯èƒ½åˆ«æ— 选择，åªèƒ½ +对问题报告进行优先级排åºè€Œæ‹’ç»å…¶ä¸çš„一些报告。 + +ä¸è¿‡è¿™äº›éƒ½ä¸ç”¨å¤ªè¿‡æ‹…心，很多驱动都有积æžçš„维护者，他们对尽å¯èƒ½å¤šçš„解决问题 +相当感兴趣。 + + +结æŸè¯ +======= + +与其他å…è´¹/自由&å¼€æºè½¯ä»¶ï¼ˆFree/Libre & Open Source Software，FLOSS）相比， +å‘ Linux å†…æ ¸å¼€å‘者报告问题是很难的：这个文档的长度和å¤æ‚性以åŠå—里行间的内 +涵都说明了这一点。但目å‰å°±æ˜¯è¿™æ ·äº†ã€‚这篇文å—的主è¦ä½œè€…希望通过记录现状æ¥ä¸º +以åŽæ”¹å–„è¿™ç§çŠ¶å†µæ‰“下一些基础。 diff --git a/Documentation/translations/zh_CN/admin-guide/security-bugs.rst b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..b8120391755d --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst @@ -0,0 +1,74 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/security-bugs` + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +安全缺陷 +========= + +Linuxå†…æ ¸å¼€å‘人员éžå¸¸é‡è§†å®‰å…¨æ€§ã€‚å› æ¤æˆ‘们想知é“何时å‘现了安全æ¼æ´žï¼Œä»¥ä¾¿å°½å¿« +ä¿®å¤å’ŒæŠ«éœ²ã€‚请å‘Linuxå†…æ ¸å®‰å…¨å›¢é˜ŸæŠ¥å‘Šå®‰å…¨æ¼æ´žã€‚ + +è”络 +----- + +å¯ä»¥é€šè¿‡ç”µå邮件<security@kernel.org>è”ç³»Linuxå†…æ ¸å®‰å…¨å›¢é˜Ÿã€‚è¿™æ˜¯ä¸€ä¸ªå®‰å…¨äººå‘˜ +çš„ç§æœ‰åˆ—表，他们将帮助验è¯é”™è¯¯æŠ¥å‘Šå¹¶å¼€å‘å’Œå‘布修å¤ç¨‹åºã€‚如果您已ç»æœ‰äº†ä¸€ä¸ª +ä¿®å¤ï¼Œè¯·å°†å…¶åŒ…å«åœ¨æ‚¨çš„报告ä¸ï¼Œè¿™æ ·å¯ä»¥å¤§å¤§åŠ 快进程。安全团队å¯èƒ½ä¼šä»ŽåŒºåŸŸç»´æŠ¤ +人员那里获得é¢å¤–的帮助，以ç†è§£å’Œä¿®å¤å®‰å…¨æ¼æ´žã€‚ + +ä¸Žä»»ä½•ç¼ºé™·ä¸€æ ·ï¼Œæ供的信æ¯è¶Šå¤šï¼Œè¯Šæ–和修å¤å°±è¶Šå®¹æ˜“。如果您ä¸æ¸…楚哪些信æ¯æœ‰ç”¨ï¼Œ +请查看“Documentation/translations/zh_CN/admin-guide/reporting-issues.rstâ€ä¸ +概述的æ¥éª¤ã€‚任何利用æ¼æ´žçš„攻击代ç 都éžå¸¸æœ‰ç”¨ï¼Œæœªç»æŠ¥å‘Šè€…åŒæ„ä¸ä¼šå¯¹å¤–å‘布，除 +éžå·²ç»å…¬å¼€ã€‚ + +请尽å¯èƒ½å‘é€æ— 附件的纯文本电å邮件。如果所有的细节都è—在附件里，那么就很难对 +一个å¤æ‚的问题进行上下文引用的讨论。把它想象æˆä¸€ä¸ª +:doc:`常规的补ä¸æ交 <../process/submitting-patches>` （å³ä½¿ä½ 还没有补ä¸ï¼‰ï¼š +æ述问题和影å“，列出å¤çŽ°æ¥éª¤ï¼Œç„¶åŽç»™å‡ºä¸€ä¸ªå»ºè®®çš„解决方案，所有这些都是纯文本的。 + +披露和é™åˆ¶ä¿¡æ¯ +--------------- + +安全列表ä¸æ˜¯å…¬å¼€æ¸ é“。为æ¤ï¼Œè¯·å‚è§ä¸‹é¢çš„å作。 + +一旦开å‘出了å¥å£®çš„è¡¥ä¸ï¼Œå‘布过程就开始了。对公开的缺陷的修å¤ä¼šç«‹å³å‘布。 + +尽管我们倾å‘于在未公开缺陷的修å¤å¯ç”¨æ—¶å³å‘布补ä¸ï¼Œä½†åº”报告者或å—å½±å“方的请求， +è¿™å¯èƒ½ä¼šè¢«æŽ¨è¿Ÿåˆ°å‘布过程开始åŽçš„7æ—¥å†…ï¼Œå¦‚æžœæ ¹æ®ç¼ºé™·çš„严é‡æ€§éœ€è¦æ›´å¤šçš„时间， +则å¯é¢å¤–延长到14天。推迟å‘布修å¤çš„å”¯ä¸€æœ‰æ•ˆåŽŸå› æ˜¯ä¸ºäº†é€‚åº”QA的逻辑和需è¦å‘布 +å调的大规模部署。 + +虽然å¯èƒ½ä¸Žå—信任的个人共享å—é™ä¿¡æ¯ä»¥å¼€å‘ä¿®å¤ï¼Œä½†æœªç»æŠ¥å‘Šè€…许å¯ï¼Œæ¤ç±»ä¿¡æ¯ä¸ä¼š +与修å¤ç¨‹åºä¸€èµ·å‘布或å‘å¸ƒåœ¨ä»»ä½•å…¶ä»–æŠ«éœ²æ¸ é“上。这包括但ä¸é™äºŽåŽŸå§‹é”™è¯¯æŠ¥å‘Šå’Œ +åŽç»è®¨è®ºï¼ˆå¦‚有）ã€æ¼æ´žã€CVEä¿¡æ¯æˆ–报告者的身份。 + +æ¢å¥è¯è¯´ï¼Œæˆ‘们唯一感兴趣的是修å¤ç¼ºé™·ã€‚æ交给安全列表的所有其他资料以åŠå¯¹æŠ¥å‘Š +的任何åŽç»è®¨è®ºï¼Œå³ä½¿åœ¨è§£é™¤é™åˆ¶ä¹‹åŽï¼Œä¹Ÿå°†æ°¸ä¹…ä¿å¯†ã€‚ + +åè°ƒ +------ + +对æ•æ„Ÿç¼ºé™·ï¼ˆä¾‹å¦‚那些å¯èƒ½å¯¼è‡´æƒé™æå‡çš„缺陷）的修å¤å¯èƒ½éœ€è¦ä¸Žç§æœ‰é‚®ä»¶åˆ—表 +<linux-distros@vs.openwall.org>进行å调，以便分å‘供应商åšå¥½å‡†å¤‡ï¼Œåœ¨å…¬å¼€æŠ«éœ² +上游补ä¸æ—¶å‘布一个已修å¤çš„å†…æ ¸ã€‚å‘行版将需è¦ä¸€äº›æ—¶é—´æ¥æµ‹è¯•å»ºè®®çš„è¡¥ä¸ï¼Œé€šå¸¸ +会è¦æ±‚è‡³å°‘å‡ å¤©çš„é™åˆ¶ï¼Œè€Œä¾›åº”商更新å‘布更倾å‘于周二至周四。若åˆé€‚，安全团队 +å¯ä»¥å助这ç§å调，或者报告者å¯ä»¥ä»Žä¸€å¼€å§‹å°±åŒ…括linuxå‘行版。在这ç§æƒ…况下，请 +è®°ä½åœ¨ç”µå邮件主题行å‰é¢åŠ 上“[vs]â€ï¼Œå¦‚linuxå‘行版wikiä¸æ‰€è¿°ï¼š +<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。 + +CVEåˆ†é… +-------- + +安全团队通常ä¸åˆ†é…CVE，我们也ä¸éœ€è¦å®ƒä»¬æ¥è¿›è¡ŒæŠ¥å‘Šæˆ–ä¿®å¤ï¼Œå› 为这会使过程ä¸å¿… +è¦çš„å¤æ‚化，并å¯èƒ½è€½è¯¯ç¼ºé™·å¤„ç†ã€‚如果报告者希望在公开披露之å‰åˆ†é…一个CVEç¼–å·ï¼Œ +他们需è¦è”系上述的ç§æœ‰linux-distros列表。当在æ供补ä¸ä¹‹å‰å·²æœ‰è¿™æ ·çš„CVEç¼–å·æ—¶ï¼Œ +如报告者愿æ„，最好在æ交消æ¯ä¸æåŠå®ƒã€‚ + +ä¿å¯†åè®® +--------- + +Linuxå†…æ ¸å®‰å…¨å›¢é˜Ÿä¸æ˜¯ä¸€ä¸ªæ£å¼çš„æœºæž„å®žä½“ï¼Œå› æ¤æ— 法ç¾è®¢ä»»ä½•ä¿å¯†å议。 diff --git a/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst new file mode 100644 index 000000000000..bc51d7cff9b0 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst @@ -0,0 +1,157 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/tainted-kernels` + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +å—æ±¡æŸ“çš„å†…æ ¸ +------------- + +当å‘生一些在ç¨åŽè°ƒæŸ¥é—®é¢˜æ—¶å¯èƒ½ç›¸å…³çš„äº‹ä»¶æ—¶ï¼Œå†…æ ¸ä¼šå°†è‡ªå·±æ ‡è®°ä¸ºâ€œå—污染 +（tainted）â€çš„。ä¸ç”¨å¤ªè¿‡æ‹…心，大多数情况下è¿è¡Œå—æ±¡æŸ“çš„å†…æ ¸æ²¡æœ‰é—®é¢˜ï¼›è¿™äº›ä¿¡æ¯ +主è¦åœ¨æœ‰äººæƒ³è°ƒæŸ¥æŸä¸ªé—®é¢˜æ—¶æ‰æœ‰æ„ä¹‰çš„ï¼Œå› ä¸ºé—®é¢˜çš„çœŸæ£åŽŸå› å¯èƒ½æ˜¯å¯¼è‡´å†…æ ¸å—污染 +的事件。这就是为什么æ¥è‡ªå—æ±¡æŸ“å†…æ ¸çš„ç¼ºé™·æŠ¥å‘Šå¸¸å¸¸è¢«å¼€å‘äººå‘˜å¿½ç•¥ï¼Œå› æ¤è¯·å°è¯•ç”¨ +未å—æ±¡æŸ“çš„å†…æ ¸é‡çŽ°é—®é¢˜ã€‚ + +请注æ„，å³ä½¿åœ¨æ‚¨æ¶ˆé™¤å¯¼è‡´æ±¡æŸ“çš„åŽŸå› ï¼ˆäº¦å³å¸è½½ä¸“æœ‰å†…æ ¸æ¨¡å—）之åŽï¼Œå†…æ ¸ä»å°†ä¿æŒ +污染状æ€ï¼Œä»¥è¡¨ç¤ºå†…æ ¸ä»ç„¶ä¸å¯ä¿¡ã€‚è¿™ä¹Ÿæ˜¯ä¸ºä»€ä¹ˆå†…æ ¸åœ¨æ³¨æ„到内部问题（“kernel +bugâ€ï¼‰ã€å¯æ¢å¤é”™è¯¯ï¼ˆâ€œkernel oopsâ€ï¼‰æˆ–ä¸å¯æ¢å¤é”™è¯¯ï¼ˆâ€œkernel panicâ€ï¼‰æ—¶ä¼šæ‰“å° +å—污染状æ€ï¼Œå¹¶å°†æœ‰å…³æ¤çš„调试信æ¯å†™å…¥æ—¥å¿— ``dmesg`` 输出。也å¯ä»¥é€šè¿‡ +``/proc/`` ä¸çš„文件在è¿è¡Œæ—¶æ£€æŸ¥å—污染的状æ€ã€‚ + + +BUGã€Oops或Panics消æ¯ä¸çš„æ±¡æŸ“æ ‡å¿— +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在顶部以“CPU:â€å¼€å¤´çš„一行ä¸å¯ä»¥æ‰¾åˆ°å—污染的状æ€ï¼›å†…æ ¸æ˜¯å¦å—åˆ°æ±¡æŸ“å’ŒåŽŸå› ä¼šæ˜¾ç¤º +在进程ID（“PID:â€ï¼‰å’Œè§¦å‘事件命令的缩写å称（“Comm:â€ï¼‰ä¹‹åŽ:: + + BUG: unable to handle kernel NULL pointer dereference at 0000000000000000 + Oops: 0002 [#1] SMP PTI + CPU: 0 PID: 4424 Comm: insmod Tainted: P W O 4.20.0-0.rc6.fc30 #1 + Hardware name: Red Hat KVM, BIOS 0.5.1 01/01/2011 + RIP: 0010:my_oops_init+0x13/0x1000 [kpanic] + [...] + +å¦‚æžœå†…æ ¸åœ¨äº‹ä»¶å‘生时没有被污染，您将在那里看到“Not-tainted:â€ï¼›å¦‚果被污染，那 +么它将是“Tainted:â€ä»¥åŠå—æ¯æˆ–ç©ºæ ¼ã€‚åœ¨ä¸Šé¢çš„例åä¸ï¼Œå®ƒçœ‹èµ·æ¥æ˜¯è¿™æ ·çš„:: + + Tainted: P W O + +下表解释了这些å—符的å«ä¹‰ã€‚在本例ä¸ï¼Œç”±äºŽåŠ 载了专有模å—（ ``P`` ），出现了 +è¦å‘Šï¼ˆ ``W`` ï¼‰ï¼Œå¹¶ä¸”åŠ è½½äº†å¤–éƒ¨æž„å»ºçš„æ¨¡å—（ ``O`` ï¼‰ï¼Œæ‰€ä»¥å†…æ ¸æ—©äº›æ—¶å€™å—到 +了污染。è¦è§£ç 其他å—符，请使用下表。 + + +解ç è¿è¡Œæ—¶çš„æ±¡æŸ“çŠ¶æ€ +~~~~~~~~~~~~~~~~~~~~~ + +在è¿è¡Œæ—¶ï¼Œæ‚¨å¯ä»¥é€šè¿‡è¯»å– ``cat /proc/sys/kernel/tainted`` æ¥æŸ¥è¯¢å—污染状æ€ã€‚ +如果返回 ``0`` ï¼Œåˆ™å†…æ ¸æ²¡æœ‰å—到污染；任何其他数å—都表示å—åˆ°æ±¡æŸ“çš„åŽŸå› ã€‚è§£ç +这个数å—的最简å•æ–¹æ³•æ˜¯ä½¿ç”¨è„šæœ¬ ``tools/debugging/kernel-chktaint`` ，您的 +å‘行版å¯èƒ½ä¼šå°†å…¶ä½œä¸ºå为 ``linux-tools`` 或 ``kernel-tools`` 的包的一部分æ +供；如果没有，您å¯ä»¥ä»Ž +`git.kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/tools/debugging/kernel-chktaint>`_ +网站下载æ¤è„šæœ¬å¹¶ç”¨ ``sh kernel-chktaint`` 执行，它会在上é¢å¼•ç”¨çš„日志ä¸æœ‰ç±»ä¼¼ +è¯å¥çš„机器上打å°è¿™æ ·çš„内容:: + + Kernel is Tainted for following reasons: + * Proprietary module was loaded (#0) + * Kernel issued warning (#9) + * Externally-built ('out-of-tree') module was loaded (#12) + See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or + https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for + a more details explanation of the various taint flags. + Raw taint value as int/string: 4609/'P W O ' + +ä½ ä¹Ÿå¯ä»¥è¯•ç€è‡ªå·±è§£ç 这个数å—ã€‚å¦‚æžœå†…æ ¸è¢«æ±¡æŸ“çš„åŽŸå› åªæœ‰ä¸€ä¸ªï¼Œé‚£ä¹ˆè¿™å¾ˆç®€å•ï¼Œ +在本例ä¸æ‚¨å¯ä»¥é€šè¿‡ä¸‹è¡¨æ‰¾åˆ°æ•°å—ã€‚å¦‚æžœä½ éœ€è¦è§£ç æœ‰å¤šä¸ªåŽŸå› çš„æ•°å—ï¼Œå› ä¸ºå®ƒæ˜¯ä¸€ +个ä½åŸŸï¼ˆbitfield），其ä¸æ¯ä¸ªä½è¡¨ç¤ºä¸€ä¸ªç‰¹å®šç±»åž‹çš„污染的å˜åœ¨æˆ–ä¸å˜åœ¨ï¼Œæœ€å¥½è®© +å‰é¢æ到的脚本æ¥å¤„ç†ã€‚但是如果您需è¦å¿«é€Ÿçœ‹ä¸€ä¸‹ï¼Œå¯ä»¥ä½¿ç”¨è¿™ä¸ªshell命令æ¥æ£€æŸ¥ +设置了哪些ä½:: + + $ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done + +污染状æ€ä»£ç 表 +~~~~~~~~~~~~~~~ + +=== ===== ====== ======================================================== + ä½ æ—¥å¿— æ•°å— å†…æ ¸è¢«æ±¡æŸ“çš„åŽŸå› +=== ===== ====== ======================================================== + 0 G/P 1 å·²åŠ è½½ä¸“ç”¨æ¨¡å— + 1 _/F 2 模å—è¢«å¼ºåˆ¶åŠ è½½ + 2 _/S 4 å†…æ ¸è¿è¡Œåœ¨ä¸åˆè§„范的系统上 + 3 _/R 8 模å—被强制å¸è½½ + 4 _/M 16 处ç†å™¨æŠ¥å‘Šäº†æœºå™¨æ£€æµ‹å¼‚常（MCE） + 5 _/B 32 引用了错误的页或æŸäº›æ„å¤–çš„é¡µæ ‡å¿— + 6 _/U 64 用户空间应用程åºè¯·æ±‚的污染 + 7 _/D 128 å†…æ ¸æœ€è¿‘æ»æœºäº†ï¼Œå³æ›¾å‡ºçŽ°OOPS或BUG + 8 _/A 256 ACPI表被用户覆盖 + 9 _/W 512 å†…æ ¸å‘出è¦å‘Š + 10 _/C 1024 å·²åŠ è½½stagingé©±åŠ¨ç¨‹åº + 11 _/I 2048 已应用平å°å›ºä»¶ç¼ºé™·çš„解决方案 + 12 _/O 4096 å·²åŠ è½½å¤–éƒ¨æž„å»ºï¼ˆâ€œæ ‘å¤–â€ï¼‰æ¨¡å— + 13 _/E 8192 å·²åŠ è½½æœªç¾åçš„æ¨¡å— + 14 _/L 16384 å‘生软é”定 + 15 _/K 32768 å†…æ ¸å·²å®žæ—¶æ‰“è¡¥ä¸ + 16 _/X 65536 备用污染，为å‘行版定义并使用 + 17 _/T 131072 å†…æ ¸æ˜¯ç”¨ç»“æž„éšæœºåŒ–æ’件构建的 +=== ===== ====== ======================================================== + +注：å—符 ``_`` 表示空白，以便于阅读表。 + +污染的更详细解释 +~~~~~~~~~~~~~~~~~ + + 0) ``G`` åŠ è½½çš„æ‰€æœ‰æ¨¡å—都有GPL或兼容许å¯è¯ï¼Œ ``P`` åŠ è½½äº†ä»»ä½•ä¸“æœ‰æ¨¡å—。 + 没有MODULE_LICENSE（模å—许å¯è¯ï¼‰æˆ–MODULE_LICENSE未被insmod认å¯ä¸ºGPL + 兼容的模å—被认为是专有的。 + + + 1) ``F`` 任何模å—被 ``insmod -f`` å¼ºåˆ¶åŠ è½½ï¼Œ ``' '`` 所有模å—æ£å¸¸åŠ 载。 + + 2) ``S`` å†…æ ¸è¿è¡Œåœ¨ä¸åˆè§„范的处ç†å™¨æˆ–系统上：硬件已è¿è¡Œåœ¨ä¸å—支æŒçš„é…ç½®ä¸ï¼Œ + å› æ¤æ— 法ä¿è¯æ£ç¡®æ‰§è¡Œã€‚å†…æ ¸å°†è¢«æ±¡æŸ“ï¼Œä¾‹å¦‚ï¼š + + - 在x86上：PAE是通过intel CPU（如Pentium M）上的forcepae强制执行的，这些 + CPUä¸æŠ¥å‘ŠPAE，但å¯èƒ½æœ‰åŠŸèƒ½å®žçŽ°ï¼ŒSMPå†…æ ¸åœ¨éžå®˜æ–¹æ”¯æŒçš„SMP Athlon CPU上 + è¿è¡Œï¼ŒMSR被暴露到用户空间ä¸ã€‚ + - 在arm上：在æŸäº›CPU（如Keystone 2）上è¿è¡Œçš„å†…æ ¸ï¼Œæ²¡æœ‰å¯ç”¨æŸäº›å†…æ ¸ç‰¹æ€§ã€‚ + - 在arm64上：CPU之间å˜åœ¨ä¸åŒ¹é…çš„ç¡¬ä»¶ç‰¹æ€§ï¼Œå¼•å¯¼åŠ è½½ç¨‹åºä»¥ä¸åŒçš„模å¼å¼•å¯¼CPU。 + - æŸäº›é©±åŠ¨ç¨‹åºæ£åœ¨è¢«ç”¨åœ¨ä¸å—支æŒçš„体系结构上（例如x86_64以外的其他系统 + 上的scsi/snic，éžx86/x86_64/itanium上的scsi/ips，已ç»æŸå了arm64上 + irqchip/irq-gic的固件设置…）。 + + 3) ``R`` 模å—被 ``rmmod -f`` 强制å¸è½½ï¼Œ ``' '`` 所有模å—都æ£å¸¸å¸è½½ã€‚ + + 4) ``M`` 任何处ç†å™¨æŠ¥å‘Šäº†æœºå™¨æ£€æµ‹å¼‚常， ``' '`` 未å‘生机器检测异常。 + + 5) ``B`` 页é¢é‡Šæ”¾å‡½æ•°å‘现错误的页é¢å¼•ç”¨æˆ–æŸäº›æ„外的页é¢æ ‡å¿—。这表示硬件问题 + æˆ–å†…æ ¸é”™è¯¯ï¼›æ—¥å¿—ä¸åº”该有其他信æ¯æŒ‡ç¤ºå‘生æ¤æ±¡æŸ“çš„åŽŸå› ã€‚ + + 6) ``U`` 用户或用户应用程åºç‰¹æ„请求设置å—æ±¡æŸ“æ ‡å¿—ï¼Œå¦åˆ™åº”为 ``' '`` 。 + + 7) ``D`` å†…æ ¸æœ€è¿‘æ»æœºäº†ï¼Œå³å‡ºçŽ°äº†OOPS或BUG。 + + 8) ``A`` ACPI表被é‡å†™ã€‚ + + 9) ``W`` å†…æ ¸ä¹‹å‰å·²å‘出过è¦å‘Šï¼ˆå°½ç®¡æœ‰äº›è¦å‘Šå¯èƒ½ä¼šè®¾ç½®æ›´å…·ä½“çš„æ±¡æŸ“æ ‡å¿—ï¼‰ã€‚ + + 10) ``C`` å·²åŠ è½½staging驱动程åºã€‚ + + 11) ``I`` å†…æ ¸æ£åœ¨å¤„ç†å¹³å°å›ºä»¶ï¼ˆBIOS或类似软件）ä¸çš„严é‡é”™è¯¯ã€‚ + + 12) ``O`` å·²åŠ è½½å¤–éƒ¨æž„å»ºï¼ˆâ€œæ ‘å¤–â€ï¼‰æ¨¡å—。 + + 13) ``E`` 在支æŒæ¨¡å—ç¾åçš„å†…æ ¸ä¸åŠ 载了未ç¾å的模å—。 + + 14) ``L`` 系统上先å‰å‘生过软é”定。 + + 15) ``K`` å†…æ ¸å·²ç»å®žæ—¶æ‰“了补ä¸ã€‚ + + 16) ``X`` 备用污染，由Linuxå‘行版定义和使用。 + + 17) ``T`` å†…æ ¸æž„å»ºæ—¶ä½¿ç”¨äº†randstructæ’件，它å¯ä»¥æœ‰æ„生æˆéžå¸¸ä¸å¯»å¸¸çš„å†…æ ¸ç»“æž„ + 布局（甚至是性能病æ€çš„布局），这在调试时éžå¸¸æœ‰ç”¨ã€‚于构建时设置。 diff --git a/Documentation/translations/zh_CN/admin-guide/unicode.rst b/Documentation/translations/zh_CN/admin-guide/unicode.rst new file mode 100644 index 000000000000..b0b08d2b6eb7 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/unicode.rst @@ -0,0 +1,170 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/unicode.rst + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +Unicode（统一ç ï¼‰æ”¯æŒ +====================== + + （英文版）上次更新：2005-01-17ï¼Œç‰ˆæœ¬å· 1.4 + +æ¤æ–‡æ¡£ç”±H. Peter Anvin <unicode@lanana.org>管ç†ï¼Œæ˜¯Linux注册å称与编å·ç®¡ç†å±€ +（Linux Assigned Names And Numbers Authority，LANANA）项目的一部分。 +现行版本请è§ï¼š + + http://www.lanana.org/docs/unicode/admin-guide/unicode.rst + +简介 +----- + +Linuxå†…æ ¸ä»£ç 已被é‡å†™ä»¥ä½¿ç”¨Unicodeæ¥å°†å—ç¬¦æ˜ å°„åˆ°å—体。下载一个Unicode到å—体 +（Unicode-to-font）表，八ä½å—符集与UTF-8模å¼éƒ½å°†æ”¹ç”¨æ¤å—体æ¥æ˜¾ç¤ºã€‚ + +这微妙地改å˜äº†å…«ä½å—符表的è¯ä¹‰ã€‚现在的四个å—符表是： + +=============== =============================== ================ +æ˜ å°„ä»£å· æ˜ å°„å称 Escape代ç (G0) +=============== =============================== ================ +LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B +GRAF_MAP DEC VT100 pseudographics ESC ( 0 +IBMPC_MAP IBM code page 437 ESC ( U +USER_MAP User defined ESC ( K +=============== =============================== ================ + +特别是 ESC ( U ä¸å†æ˜¯â€œç›´é€šå—体â€ï¼Œå› 为å—体å¯èƒ½ä¸ŽIBMå—符集完全ä¸åŒã€‚ +例如，å³ä½¿åŠ 载了一个Latin-1å—体，也å…许使用å—图形（block graphics）。 + +请注æ„，尽管这些代ç 与ISO 2022类似，但这些代ç åŠå…¶ç”¨é€”都与ISO 2022ä¸åŒ¹é…ï¼› +Linux有两个八ä½ä»£ç （G0å’ŒG1），而ISO 2022有四个七ä½ä»£ç （G0-G3）。 + +æ ¹æ®Unicodeæ ‡å‡†/ISO 10646，U+F000到U+F8FF被ä¿ç•™ç”¨äºŽæ“ä½œç³»ç»ŸèŒƒå›´å†…çš„åˆ†é… +（Unicodeæ ‡å‡†å°†å…¶ç§°ä¸ºâ€œå›¢ä½“åŒºåŸŸï¼ˆCorporate Zone）â€ï¼Œå› 为这对于Linux是ä¸å‡†ç¡® +的，所以我们称之为“Linux区域â€ï¼‰ã€‚选择U+F000ä½œä¸ºèµ·ç‚¹ï¼Œå› ä¸ºå®ƒå…è®¸ç›´æŽ¥æ˜ å°„ +区域以2的大å€æ•°å¼€å§‹ï¼ˆä»¥é˜²éœ€è¦1024或2048个å—符的å—体）。这就留下U+E000到 +U+EFFF作为最终用户区。 + +[v1.2]：Unicodes范围从U+F000到U+F7FFå·²ç»è¢«ç¡¬ç¼–ç ä¸ºç›´æŽ¥æ˜ å°„åˆ°åŠ è½½çš„å—体， +ç»•è¿‡äº†ç¿»è¯‘è¡¨ã€‚ç”¨æˆ·å®šä¹‰çš„æ˜ å°„çŽ°åœ¨é»˜è®¤ä¸ºU+F000到U+F0FF，模拟å‰è¿°è¡Œä¸ºã€‚实际上， +æ¤èŒƒå›´å¯èƒ½è¾ƒçŸï¼›ä¾‹å¦‚，vgaconåªèƒ½å¤„ç†256å—符（U+F000..U+F0FF）或512å—符 +（U+F000..U+F1FF）å—体。 + +Linux 区域ä¸å®šä¹‰çš„实际å—符 +--------------------------- + +æ¤å¤–，还定义了Unicode 1.1.4ä¸ä¸å˜åœ¨çš„以下å—符；这些å—符由DEC VTå›¾å½¢æ˜ å°„ä½¿ç”¨ã€‚ +[v1.2]æ¤ç”¨æ³•å·²è¿‡æ—¶ï¼Œä¸åº”å†ä½¿ç”¨ï¼›è¯·å‚è§ä¸‹æ–‡ã€‚ + +====== ====================================== +U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 +U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 +U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 +U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== + +DEC VT220使用6x10å—符矩阵，这些å—符在DEC VT图形å—符集ä¸å½¢æˆä¸€ä¸ªå¹³æ»‘的过渡。 +我çœç•¥äº†æ‰«æ5è¡Œï¼Œå› ä¸ºå®ƒä¹Ÿè¢«ç”¨ä½œå—图形å—ç¬¦ï¼Œå› æ¤è¢«ç¼–ç 为U+2500 FORMS LIGHT +HORIZONTAL。 + +[v1.3]：这些å—符已æ£å¼æ·»åŠ 到Unicode 3.2.0ä¸ï¼›å®ƒä»¬åœ¨U+23BAã€U+23BBã€U+23BC〠+U+23BDå¤„æ·»åŠ ã€‚Linux现在使用新值。 + +[v1.2]ï¼šæ·»åŠ äº†ä»¥ä¸‹å—符æ¥è¡¨ç¤ºå¸¸è§çš„键盘符å·ï¼Œè¿™äº›ç¬¦å·ä¸å¤ªå¯èƒ½è¢«æ·»åŠ 到Unicode +ä¸ï¼Œå› 为它们éžå¸¸è®¨åŽŒåœ°å–决于特定供应商。当然，这是糟糕设计的一个好例å。 + +====== ====================================== +U+F810 KEYBOARD SYMBOL FLYING FLAG +U+F811 KEYBOARD SYMBOL PULLDOWN MENU +U+F812 KEYBOARD SYMBOL OPEN APPLE +U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== + +克林贡（Klingon）è¯æ”¯æŒ +------------------------ + +1996年，Linuxæ˜¯ä¸–ç•Œä¸Šç¬¬ä¸€ä¸ªæ·»åŠ å¯¹äººå·¥è¯è¨€å…‹æž—贡支æŒçš„æ“作系统，克林贡是由 +Marc Okrand为《星际迷航》电视连ç»å‰§åˆ›é€ 的。这ç§ç¼–ç åŽæ¥è¢«å¾å‹ŸUnicode注册表 +（ConScript Unicode Registry，CSUR）采用，并建议（但最终被拒ç»ï¼‰çº³å…¥Unicode +å¹³é¢ä¸€ã€‚ä¸è¿‡ï¼Œå®ƒä»ç„¶æ˜¯Linux区域ä¸çš„Linux/CSURç§æœ‰åˆ†é…。 + +è¿™ç§ç¼–ç å·²ç»å¾—到克林贡è¯è¨€ç ”究所（Klingon Language Institute）的认å¯ã€‚ +有关更多信æ¯ï¼Œè¯·è”系他们： + + http://www.kli.org/ + +由于Linux CZ开头部分的å—符大多是dingbats/symbols/formsç±»åž‹ï¼Œè€Œä¸”è¿™æ˜¯ä¸€ç§ +è¯è¨€ï¼Œå› æ¤æ ¹æ®æ ‡å‡†Unicode惯例，我将它放置在16å•å…ƒçš„边界上。 + +.. note:: + + 这个范围现在由å¾å‹ŸUnicode注册表æ£å¼ç®¡ç†ã€‚规范性引用文件为： + + https://www.evertype.com/standards/csur/klingon.html + +å…‹æž—è´¡è¯æœ‰ä¸€ä¸ª26个å—符的å—æ¯è¡¨ï¼Œä¸€ä¸ª10ä½æ•°çš„ä½ç½®æ•°å—ä¹¦å†™ç³»ç»Ÿï¼Œä»Žå·¦åˆ°å³ +，从上到下书写。 + +å…‹æž—è´¡å—æ¯çš„å‡ ç§å—形已ç»è¢«æ出。但是由于这组符å·çœ‹èµ·æ¥å§‹ç»ˆæ˜¯ä¸€è‡´çš„，åªæœ‰å®žé™… +的形状ä¸åŒï¼Œå› æ¤æŒ‰ç…§æ ‡å‡†Unicode惯例，这些差异被认为是å—体å˜ä½“。 + +====== ======================================================= +U+F8D0 KLINGON LETTER A +U+F8D1 KLINGON LETTER B +U+F8D2 KLINGON LETTER CH +U+F8D3 KLINGON LETTER D +U+F8D4 KLINGON LETTER E +U+F8D5 KLINGON LETTER GH +U+F8D6 KLINGON LETTER H +U+F8D7 KLINGON LETTER I +U+F8D8 KLINGON LETTER J +U+F8D9 KLINGON LETTER L +U+F8DA KLINGON LETTER M +U+F8DB KLINGON LETTER N +U+F8DC KLINGON LETTER NG +U+F8DD KLINGON LETTER O +U+F8DE KLINGON LETTER P +U+F8DF KLINGON LETTER Q + - Written <q> in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written <Q> in standard Okrand Latin transliteration +U+F8E1 KLINGON LETTER R +U+F8E2 KLINGON LETTER S +U+F8E3 KLINGON LETTER T +U+F8E4 KLINGON LETTER TLH +U+F8E5 KLINGON LETTER U +U+F8E6 KLINGON LETTER V +U+F8E7 KLINGON LETTER W +U+F8E8 KLINGON LETTER Y +U+F8E9 KLINGON LETTER GLOTTAL STOP + +U+F8F0 KLINGON DIGIT ZERO +U+F8F1 KLINGON DIGIT ONE +U+F8F2 KLINGON DIGIT TWO +U+F8F3 KLINGON DIGIT THREE +U+F8F4 KLINGON DIGIT FOUR +U+F8F5 KLINGON DIGIT FIVE +U+F8F6 KLINGON DIGIT SIX +U+F8F7 KLINGON DIGIT SEVEN +U+F8F8 KLINGON DIGIT EIGHT +U+F8F9 KLINGON DIGIT NINE + +U+F8FD KLINGON COMMA +U+F8FE KLINGON FULL STOP +U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= + +其他虚构和人工å—æ¯ +------------------- + +自从分é…了克林贡Linux Unicodeå—之åŽï¼ŒJohn Cowan <jcowan@reutershealth.com> +å’Œ Michael Everson <everson@evertype.com> 建立了一个虚构和人工å—æ¯çš„注册表。 +å¾å‹ŸUnicode注册表请访问： + + https://www.evertype.com/standards/csur/ + +所使用的范围ä½äºŽæœ€ç»ˆç”¨æˆ·åŒºåŸŸçš„ä½Žç«¯ï¼Œå› æ¤æ— 法进行规范化分é…，但建议希望对虚构 +å—æ¯è¿›è¡Œç¼–ç 的人员使用这些代ç ，以实现互æ“作性。对于克林贡è¯ï¼ŒCSUR采用了Linux +ç¼–ç 。CSUR的人æ£åœ¨æŽ¨åŠ¨å°†Tengwarå’ŒCirthæ·»åŠ åˆ°Unicodeå¹³é¢ä¸€ï¼›å°†å…‹æž—è´¡æ·»åŠ åˆ° +Unicodeå¹³é¢ä¸€è¢«æ‹’ç»ï¼Œå› æ¤ä¸Šè¿°ç¼–ç ä»ç„¶æ˜¯å®˜æ–¹çš„。 diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst new file mode 100644 index 000000000000..f1fa71e45c77 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -0,0 +1,126 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../core-api/irq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_core-api_index.rst: + + +=========== +æ ¸å¿ƒAPI文档 +=========== + +è¿™æ˜¯æ ¸å¿ƒå†…æ ¸API手册的首页。 éžå¸¸æ„Ÿè°¢ä¸ºæœ¬æ‰‹å†Œè½¬æ¢(和编写!)的文档! + +æ ¸å¿ƒå®žç”¨ç¨‹åº +============ + +本节包å«é€šç”¨çš„å’Œâ€œæ ¸å¿ƒä¸çš„æ ¸å¿ƒâ€æ–‡æ¡£ã€‚ 第一部分是 docbook 时期é—留下 +æ¥çš„å¤§é‡ kerneldoc ä¿¡æ¯ï¼›æœ‰æœä¸€æ—¥ï¼Œè‹¥æœ‰äººæœ‰åŠ¨åŠ›çš„è¯ï¼Œåº”当把它们拆分 +出æ¥ã€‚ + +Todolist: + + kernel-api + workqueue + printk-basics + printk-formats + symbol-namespaces + +æ•°æ®ç»“æž„å’Œä½Žçº§å®žç”¨ç¨‹åº +====================== + +åœ¨æ•´ä¸ªå†…æ ¸ä¸ä½¿ç”¨çš„函数库。 + +Todolist: + + kobject + kref + assoc_array + xarray + idr + circular-buffers + rbtree + generic-radix-tree + packing + bus-virt-phys-mapping + this_cpu_ops + timekeeping + errseq + +并å‘åŽŸè¯ +======== + +Linux如何让一切åŒæ—¶å‘生。 详情请å‚阅 +:doc:`/locking/index` + +.. toctree:: + :maxdepth: 1 + + irq/index + +Todolist: + + refcount-vs-atomic + local_ops + padata + ../RCU/index + +ä½Žçº§ç¡¬ä»¶ç®¡ç† +============ + +缓å˜ç®¡ç†ï¼ŒCPUçƒæ’拔管ç†ç‰ã€‚ + +Todolist: + + cachetlb + cpu_hotplug + memory-hotplug + genericirq + protection-keys + + +内å˜ç®¡ç† +======== + +å¦‚ä½•åœ¨å†…æ ¸ä¸åˆ†é…和使用内å˜ã€‚请注æ„，在 +:doc:`/vm/index` ä¸æœ‰æ›´å¤šçš„内å˜ç®¡ç†æ–‡æ¡£ã€‚ + +Todolist: + + memory-allocation + unaligned-memory-access + dma-api + dma-api-howto + dma-attributes + dma-isa-lpc + mm-api + genalloc + pin_user_pages + boot-time-mm + gfp_mask-from-fs-io + +å†…æ ¸è°ƒè¯•çš„æŽ¥å£ +============== + +Todolist: + + debug-objects + tracepoint + debugging-via-ohci1394 + +其它文档 +======== + +ä¸é€‚åˆæ”¾åœ¨å…¶å®ƒåœ°æ–¹æˆ–尚未归类的文件； + +Todolist: + + librs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/core-api/irq/concepts.rst b/Documentation/translations/zh_CN/core-api/irq/concepts.rst new file mode 100644 index 000000000000..41455bf0f783 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/concepts.rst @@ -0,0 +1,24 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/concepts` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_concepts.rst: + + +=========== +什么是IRQ？ +=========== + +IRQ (Interrupt ReQuest) 指æ¥è‡ªè®¾å¤‡çš„ä¸æ–请求。 +ç›®å‰ï¼Œå®ƒä»¬å¯ä»¥é€šè¿‡ä¸€ä¸ªå¼•è„šæˆ–通过一个数æ®åŒ…进入。 +多个设备å¯ä»¥è¿žæŽ¥åˆ°åŒä¸€ä¸ªå¼•è„šï¼Œä»Žè€Œå…±äº«ä¸€ä¸ªIRQ。 + +IRQç¼–å·æ˜¯ç”¨æ¥æ述硬件ä¸æ–æºçš„å†…æ ¸æ ‡è¯†ç¬¦ã€‚é€šå¸¸å®ƒæ˜¯ä¸€ä¸ªåˆ°å…¨å±€irq_desc数组的索引， +但是除了在linux/interrupt.hä¸å®žçŽ°çš„之外，其它细节是体系结构特å¾ç›¸å…³çš„。 + +IRQç¼–å·æ˜¯å¯¹æœºå™¨ä¸Šå¯èƒ½çš„ä¸æ–æºçš„枚举。通常枚举的是系统ä¸æ‰€æœ‰ä¸æ–控制器的输入引脚 +ç¼–å·ã€‚在ISAï¼ˆå·¥ä¸šæ ‡å‡†ä½“ç³»ç»“æž„ï¼‰çš„æƒ…å†µä¸‹æ‰€æžšä¸¾çš„æ˜¯ä¸¤ä¸ªi8259ä¸æ–控制器的16个输入引脚。 + +体系结构å¯ä»¥ç»™IRQå·èµ‹äºˆé¢å¤–çš„å«ä¹‰ï¼Œåœ¨æ¶‰åŠåˆ°ç¡¬ä»¶æ‰‹åŠ¨é…ç½®çš„æƒ…å†µä¸‹ï¼Œæˆ‘ä»¬é¼“åŠ±è¿™æ ·åšã€‚ +ISA IRQ是赋予这ç§é¢å¤–å«ä¹‰çš„一个典型例å。 diff --git a/Documentation/translations/zh_CN/core-api/irq/index.rst b/Documentation/translations/zh_CN/core-api/irq/index.rst new file mode 100644 index 000000000000..910ccabf041f --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/index.rst @@ -0,0 +1,19 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq_index.rst: + + +==== +IRQs +==== + +.. toctree:: + :maxdepth: 1 + + concepts + irq-affinity + irq-domain + irqflags-tracing diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst new file mode 100644 index 000000000000..82a4428f22fd --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst @@ -0,0 +1,76 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irq-affinity` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq-affinity.rst: + + +============== +SMP IRQ 亲和性 +============== + +å˜æ›´è®°å½•: + - 作者：最åˆç”±Ingo Molnar <mingo@redhat.com>开始撰写 + - åŽæœŸæ›´æ–°ç»´æŠ¤ï¼š Max Krasnyansky <maxk@qualcomm.com> + + +/proc/irq/IRQ#/smp_affinityå’Œ/proc/irq/IRQ#/smp_affinity_list指定了哪些CPU能 +够关è”到一个给定的IRQæºï¼Œè¿™ä¸¤ä¸ªæ–‡ä»¶åŒ…å«äº†è¿™äº›æŒ‡å®šcpuçš„cpuä½æŽ©ç (smp_affinity)å’Œcpu列 +表(smp_affinity_list)。它ä¸å…许关é—所有CPU， åŒæ—¶å¦‚æžœIRQ控制器ä¸æ”¯æŒä¸æ–请求亲和 +(IRQ affinity)，那么所有cpu的默认值将ä¿æŒä¸å˜(å³å…³è”到所有CPU). + +/proc/irq/default_smp_affinity指明了适用于所有éžæ¿€æ´»IRQ的默认亲和性掩ç 。一旦IRQ被 +分é…/激活，它的亲和ä½æŽ©ç 将被设置为默认掩ç 。然åŽå¯ä»¥å¦‚上所述改å˜å®ƒã€‚默认掩ç 是0xffffffff。 + +下é¢æ˜¯ä¸€ä¸ªå…ˆå°†IRQ44(eth1)é™åˆ¶åœ¨CPU0-3上，然åŽé™åˆ¶åœ¨CPU4-7上的例å(这是一个8CPUçš„SMP box) + +:: + + [root@moon 44]# cd /proc/irq/44 + [root@moon 44]# cat smp_affinity + ffffffff + + [root@moon 44]# echo 0f > smp_affinity + [root@moon 44]# cat smp_affinity + 0000000f + [root@moon 44]# ping -f h + PING hell (195.4.7.3): 56 data bytes + ... + --- hell ping statistics --- + 6029 packets transmitted, 6027 packets received, 0% packet loss + round-trip min/avg/max = 0.1/0.1/0.4 ms + [root@moon 44]# cat /proc/interrupts | grep 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 0 0 0 0 IO-APIC-level eth1 + +从上é¢ä¸€è¡Œå¯ä»¥çœ‹å‡ºï¼ŒIRQ44åªä¼ 递给å‰å››ä¸ªå¤„ç†å™¨ï¼ˆ0-3）。 +现在让我们把这个IRQé™åˆ¶åœ¨CPU(4-7)。 + +:: + + [root@moon 44]# echo f0 > smp_affinity + [root@moon 44]# cat smp_affinity + 000000f0 + [root@moon 44]# ping -f h + PING hell (195.4.7.3): 56 data bytes + .. + --- hell ping statistics --- + 2779 packets transmitted, 2777 packets received, 0% packet loss + round-trip min/avg/max = 0.1/0.5/585.4 ms + [root@moon 44]# cat /proc/interrupts | 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 1784 1069 1070 1069 IO-APIC-level eth1 + +这次IRQ44åªä¼ 递给最åŽå››ä¸ªå¤„ç†å™¨ã€‚ +å³CPU0-3的计数器没有å˜åŒ–。 + +下é¢æ˜¯ä¸€ä¸ªå°†ç›¸åŒçš„irq(44)é™åˆ¶åœ¨cpus 1024到1031的例å + +:: + + [root@moon 44]# echo 1024-1031 > smp_affinity_list + [root@moon 44]# cat smp_affinity_list + 1024-1031 + +需è¦æ³¨æ„的是，如果è¦ç”¨ä½æŽ©ç æ¥åšè¿™ä»¶äº‹ï¼Œå°±éœ€è¦32个为0çš„ä½æŽ©ç æ¥è¿½è¸ªå…¶ç›¸å…³çš„一个。 diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst new file mode 100644 index 000000000000..3c82dd307a46 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst @@ -0,0 +1,227 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irq-domain` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq-domain.rst: + + +======================= +irq_domain ä¸æ–å·æ˜ 射库 +======================= + +ç›®å‰Linuxå†…æ ¸çš„è®¾è®¡ä½¿ç”¨äº†ä¸€ä¸ªå·¨å¤§çš„æ•°å—空间，æ¯ä¸ªç‹¬ç«‹çš„IRQæºéƒ½è¢«åˆ†é…äº†ä¸€ä¸ªä¸ +åŒçš„æ•°å—。 +当åªæœ‰ä¸€ä¸ªä¸æ–控制器时，这很简å•ï¼Œä½†åœ¨æœ‰å¤šä¸ªä¸æ–控制器的系统ä¸ï¼Œå†…æ ¸å¿…é¡»ç¡®ä¿æ¯ +个ä¸æ–控制器都能得到éžé‡å¤çš„Linux IRQå·ï¼ˆæ•°å—）分é…。 + +注册为唯一的irqchipsçš„ä¸æ–控制器编å·å‘ˆçŽ°å‡ºä¸Šå‡çš„趋势：例如GPIO控制器ç‰ä¸åŒ +ç§ç±»çš„å驱动程åºé€šè¿‡å°†å…¶ä¸æ–处ç†ç¨‹åºå»ºæ¨¡ä¸ºirqchips，å³å®žé™…上是级è”ä¸æ–控制器， +é¿å…了é‡æ–°å®žçŽ°ä¸ŽIRQæ ¸å¿ƒç³»ç»Ÿç›¸åŒçš„回调机制。 + +在这里，ä¸æ–å·ä¸Žç¡¬ä»¶ä¸æ–å·ç¦»æ•£äº†æ‰€æœ‰ç§ç±»çš„对应关系：而在过去，IRQå·å¯ä»¥é€‰æ‹©ï¼Œ +使它们与硬件IRQçº¿è¿›å…¥æ ¹ä¸æ–控制器（å³å®žé™…å‘CPUå‘å°„ä¸æ–线的组件）相匹é…，现 +在这个编å·ä»…仅是一个数å—。 + +å‡ºäºŽè¿™ä¸ªåŽŸå› ï¼Œæˆ‘ä»¬éœ€è¦ä¸€ç§æœºåˆ¶å°†æŽ§åˆ¶å™¨æœ¬åœ°ä¸æ–å·ï¼ˆå³ç¡¬ä»¶irqç¼–å·ï¼‰ä¸ŽLinux IRQ +å·åˆ†å¼€ã€‚ + +irq_alloc_desc*() å’Œ irq_free_desc*() API æ供了对irqå·çš„分é…ï¼Œä½†å®ƒä»¬ä¸ +æ供任何对控制器本地IRQ(hwirq)å·åˆ°Linux IRQå·ç©ºé—´çš„åå‘æ˜ å°„çš„æ”¯æŒã€‚ + +irq_domain 库在 irq_alloc_desc*() API çš„åŸºç¡€ä¸Šå¢žåŠ äº† hwirq å’Œ IRQ å·ç +ä¹‹é—´çš„æ˜ å°„ã€‚ 相比于ä¸æ–控制器驱动开放编ç 自己的åå‘æ˜ å°„æ–¹æ¡ˆï¼Œæˆ‘ä»¬æ›´å–œæ¬¢ç”¨ +irq_domainæ¥ç®¡ç†æ˜ 射。 + +irq_domain还实现了从抽象的irq_fwspec结构体到hwirqå·çš„转æ¢ï¼ˆåˆ°ç›®å‰ä¸ºæ¢æ˜¯ +Device Treeå’ŒACPI GSI），并且å¯ä»¥å¾ˆå®¹æ˜“地扩展以支æŒå…¶å®ƒIRQ拓扑数æ®æºã€‚ + +irq_domain的用法 +================ + +ä¸æ–控制器驱动程åºé€šè¿‡ä»¥ä¸‹æ–¹å¼åˆ›å»ºå¹¶æ³¨å†Œä¸€ä¸ªirq_domain。调用 +irq_domain_add_*() 或 irq_domain_create_*()函数之一（æ¯ä¸ªæ˜ å°„æ–¹æ³•éƒ½æœ‰ä¸ +åŒçš„分é…器函数，åŽé¢ä¼šè¯¦ç»†ä»‹ç»ï¼‰ã€‚ 函数æˆåŠŸåŽä¼šè¿”回一个指å‘irq_domain的指针。 +调用者必须å‘分é…器函数æ供一个irq_domain_ops结构体。 + +在大多数情况下，irq_domain在开始时是空的，没有任何hwirqå’ŒIRQå·ä¹‹é—´çš„æ˜ å°„ã€‚ +通过调用irq_create_mapping()å°†æ˜ å°„æ·»åŠ åˆ°irq_domainä¸ï¼Œè¯¥å‡½æ•°æŽ¥å— +irq_domain和一个hwirqå·ä½œä¸ºå‚数。 如果hwirqçš„æ˜ å°„è¿˜ä¸å˜åœ¨ï¼Œé‚£ä¹ˆå®ƒå°†åˆ†é… +一个新的Linux irq_desc，将其与hwirqå…³è”èµ·æ¥ï¼Œå¹¶è°ƒç”¨.map()å›žè°ƒï¼Œè¿™æ ·é©±åŠ¨ +程åºå°±å¯ä»¥æ‰§è¡Œä»»ä½•å¿…è¦çš„硬件设置。 + +当接收到一个ä¸æ–时，应该使用irq_find_mapping()函数从hwirqå·ä¸æ‰¾åˆ° +Linux IRQå·ã€‚ + +在调用irq_find_mapping()之å‰ï¼Œè‡³å°‘è¦è°ƒç”¨ä¸€æ¬¡irq_create_mapping()函数， +以å…æ述符ä¸èƒ½è¢«åˆ†é…。 + +如果驱动程åºæœ‰Linuxçš„IRQå·æˆ–irq_data指针，并且需è¦çŸ¥é“相关的hwirqå·ï¼ˆæ¯” +如在irq_chip回调ä¸ï¼‰ï¼Œé‚£ä¹ˆå¯ä»¥ç›´æŽ¥ä»Žirq_data->hwirqä¸èŽ·å¾—。 + +irq_domainæ˜ å°„çš„ç±»åž‹ +==================== + +从hwirq到Linux irqçš„åå‘æ˜ å°„æœ‰å‡ ç§æœºåˆ¶ï¼Œæ¯ç§æœºåˆ¶ä½¿ç”¨ä¸åŒçš„分é…函数。应该 +使用哪ç§åå‘æ˜ å°„ç±»åž‹å–决于用例。 下é¢ä»‹ç»æ¯ä¸€ç§åå‘æ˜ å°„ç±»åž‹ï¼š + +çº¿æ€§æ˜ å°„ +-------- + +:: + + irq_domain_add_linear() + irq_domain_create_linear() + +线性åå‘æ˜ å°„ç»´æŠ¤äº†ä¸€ä¸ªå›ºå®šå¤§å°çš„表，该表以hwirqå·ä¸ºç´¢å¼•ã€‚ 当一个hwirqè¢«æ˜ å°„ +时，会给hwirq分é…一个irq_desc，并将irqå·å˜å‚¨åœ¨è¡¨ä¸ã€‚ + +当最大的hwirqå·å›ºå®šä¸”æ•°é‡ç›¸å¯¹è¾ƒå°‘时，线性图是一个很好的选择（~<256）。 è¿™ç§ +æ˜ å°„çš„ä¼˜ç‚¹æ˜¯å›ºå®šæ—¶é—´æŸ¥æ‰¾IRQå·ï¼Œè€Œä¸”irq_descsåªåˆ†é…给在用的IRQ。 缺点是该表 +必须尽å¯èƒ½å¤§çš„hwirqå·ã€‚ + +irq_domain_add_linear()å’Œirq_domain_create_linear()在功能上是ç‰ä»·çš„， +除了第一个å‚æ•°ä¸åŒ--å‰è€…接å—一个Open Firmware特定的 'struct device_node' 而 +åŽè€…接å—一个更通用的抽象 'struct fwnode_handle' 。 + +å¤§å¤šæ•°é©±åŠ¨åº”è¯¥ä½¿ç”¨çº¿æ€§æ˜ å°„ + +æ ‘çŠ¶æ˜ å°„ +-------- + +:: + + irq_domain_add_tree() + irq_domain_create_tree() + +irq_domain维护ç€ä»Žhwirqå·åˆ°Linux IRQçš„radixçš„æ ‘çŠ¶æ˜ å°„ã€‚ 当一个hwirqè¢«æ˜ å°„æ—¶ï¼Œ +一个irq_desc被分é…，hwirq被用作radixæ ‘çš„æŸ¥æ‰¾é”®ã€‚ + +如果hwirqå·å¯ä»¥éžå¸¸å¤§ï¼Œæ ‘çŠ¶æ˜ å°„æ˜¯ä¸€ä¸ªå¾ˆå¥½çš„é€‰æ‹©ï¼Œå› ä¸ºå®ƒä¸éœ€è¦åˆ†é…一个和最大hwirq +å·ä¸€æ ·å¤§çš„表。 缺点是，hwirq到IRQå·çš„查找å–决于表ä¸æœ‰å¤šå°‘æ¡ç›®ã€‚ + +irq_domain_add_tree()å’Œirq_domain_create_tree()在功能上是ç‰ä»·çš„，除了第一 +个å‚æ•°ä¸åŒâ€”—å‰è€…接å—一个Open Firmware特定的 'struct device_node' ，而åŽè€…æŽ¥å— +一个更通用的抽象 'struct fwnode_handle' 。 + +很少有驱动应该需è¦è¿™ä¸ªæ˜ 射。 + +æ— æ˜ å°„ +------ + +:: + + irq_domain_add_nomap() + +当硬件ä¸çš„hwirqå·æ˜¯å¯ç¼–程的时候，就å¯ä»¥é‡‡ç”¨æ— æ˜ å°„ç±»åž‹ã€‚ 在这ç§æƒ…况下，最好将 +Linux IRQå·ç¼–å…¥ç¡¬ä»¶æœ¬èº«ï¼Œè¿™æ ·å°±ä¸éœ€è¦æ˜ 射了。 调用irq_create_direct_mapping() +会分é…一个Linux IRQå·ï¼Œå¹¶è°ƒç”¨.map()å›žè°ƒï¼Œè¿™æ ·é©±åŠ¨å°±å¯ä»¥å°†Linux IRQå·ç¼–入硬件ä¸ã€‚ + +大多数驱动程åºä¸èƒ½ä½¿ç”¨è¿™ä¸ªæ˜ 射。 + +ä¼ ç»Ÿæ˜ å°„ç±»åž‹ +------------ + +:: + + irq_domain_add_simple() + irq_domain_add_legacy() + irq_domain_add_legacy_isa() + irq_domain_create_simple() + irq_domain_create_legacy() + +ä¼ ç»Ÿæ˜ å°„æ˜¯å·²ç»ä¸º hwirqs 分é…了一系列 irq_descs 的驱动程åºçš„特殊情况。 当驱动程 +åºä¸èƒ½ç«‹å³è½¬æ¢ä¸ºä½¿ç”¨çº¿æ€§æ˜ 射时，就会使用它。 例如，许多嵌入å¼ç³»ç»Ÿæ¿å¡æ”¯æŒæ–‡ä»¶ä½¿ç”¨ +一组用于IRQå·çš„定义（#defineï¼‰ï¼Œè¿™äº›å®šä¹‰è¢«ä¼ é€’ç»™struct设备注册。 在这ç§æƒ…况下， +ä¸èƒ½åŠ¨æ€åˆ†é…Linux IRQå·ï¼Œåº”è¯¥ä½¿ç”¨ä¼ ç»Ÿæ˜ å°„ã€‚ + +ä¼ ç»Ÿæ˜ å°„å‡è®¾å·²ç»ä¸ºæŽ§åˆ¶å™¨åˆ†é…了一个连ç»çš„IRQå·èŒƒå›´ï¼Œå¹¶ä¸”å¯ä»¥é€šè¿‡å‘hwirqå·æ·»åŠ 一 +个固定的å移æ¥è®¡ç®—IRQå·ï¼Œå之亦然。 缺点是需è¦ä¸æ–控制器管ç†IRQ分é…，并且需è¦ä¸ºæ¯ +个hwirq分é…一个irq_desc，å³ä½¿å®ƒæ²¡æœ‰è¢«ä½¿ç”¨ã€‚ + +åªæœ‰åœ¨å¿…须支æŒå›ºå®šçš„IRQæ˜ å°„æ—¶ï¼Œæ‰åº”ä½¿ç”¨ä¼ ç»Ÿæ˜ å°„ã€‚ 例如，ISAæŽ§åˆ¶å™¨å°†ä½¿ç”¨ä¼ ç»Ÿæ˜ å°„æ¥ +æ˜ å°„Linux IRQ 0-15ï¼Œè¿™æ ·çŽ°æœ‰çš„ISA驱动程åºå°±èƒ½å¾—到æ£ç¡®çš„IRQå·ã€‚ + +å¤§å¤šæ•°ä½¿ç”¨ä¼ ç»Ÿæ˜ å°„çš„ç”¨æˆ·åº”è¯¥ä½¿ç”¨irq_domain_add_simple()或 +irq_domain_create_simple()，åªæœ‰åœ¨ç³»ç»Ÿæä¾›IRQ范围时æ‰ä¼šä½¿ç”¨ä¼ 统域，å¦åˆ™å°†ä½¿ç”¨ +çº¿æ€§åŸŸæ˜ å°„ã€‚è¿™ä¸ªè°ƒç”¨çš„è¯ä¹‰æ˜¯è¿™æ ·çš„：如果指定了一个IRQ范围，那么 æ述符将被å³æ—¶åˆ†é… +给它，如果没有范围被分é…，它将ä¸ä¼šæ‰§è¡Œ irq_domain_add_linear() 或 +irq_domain_create_linear()，这æ„å‘³ç€ *no* irq æ述符将被分é…。 + +一个简å•åŸŸçš„典型用例是，irqchip供应商åŒæ—¶æ”¯æŒåŠ¨æ€å’Œé™æ€IRQ分é…。 + +为了é¿å…最终出现使用线性域而没有æ述符被分é…的情况，确ä¿ä½¿ç”¨ç®€å•åŸŸçš„驱动程åºåœ¨ä»»ä½• +irq_find_mapping()之å‰è°ƒç”¨irq_create_mapping()是éžå¸¸é‡è¦çš„ï¼Œå› ä¸ºåŽè€…实际上 +将用于é™æ€IRQ分é…情况。 + +irq_domain_add_simple()å’Œirq_domain_create_simple()ä»¥åŠ +irq_domain_add_legacy()å’Œirq_domain_create_legacy()在功能上是ç‰ä»·çš„ï¼Œåª +是第一个å‚æ•°ä¸åŒ--å‰è€…接å—Open Firmware特定的 'struct device_node' ，而åŽè€… +接å—一个更通用的抽象 'struct fwnode_handle' 。 + +IRQ域层级结构 +------------- + +在æŸäº›æž¶æž„上，å¯èƒ½æœ‰å¤šä¸ªä¸æ–控制器å‚与将一个ä¸æ–ä»Žè®¾å¤‡ä¼ é€åˆ°ç›®æ ‡CPU。 +让我们æ¥çœ‹çœ‹x86å¹³å°ä¸Šå…¸åž‹çš„ä¸æ–ä¼ é€’è·¯å¾„å§ +:: + + Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU + +涉åŠåˆ°çš„ä¸æ–控制器有三个: + +1) IOAPIC 控制器 +2) ä¸æ–é‡æ˜ 射控制器 +3) Local APIC 控制器 + +为了支æŒè¿™æ ·çš„硬件拓扑结构，使软件架构与硬件架构相匹é…，为æ¯ä¸ªä¸æ–控制器建立一 +个irq_domainæ•°æ®ç»“构，并将这些irq_domain组织æˆå±‚次结构。 + +在建立irq_domain层次结构时，é 近设备的irq_domain为å域，é è¿‘CPUçš„ +irq_domain为父域。所以在上é¢çš„例åä¸ï¼Œå°†å»ºç«‹å¦‚下的层次结构。 +:: + + CPU Vector irq_domain (root irq_domain to manage CPU vectors) + ^ + | + Interrupt Remapping irq_domain (manage irq_remapping entries) + ^ + | + IOAPIC irq_domain (manage IOAPIC delivery entries/pins) + +使用irq_domain层次结构的主è¦æŽ¥å£æœ‰å››ä¸ª: + +1) irq_domain_alloc_irqs(): 分é…IRQæ述符和与ä¸æ–控制器相关的资æºæ¥ä¼ 递这些ä¸æ–。 +2) irq_domain_free_irqs(): 释放IRQæ述符和与这些ä¸æ–相关的ä¸æ–控制器资æºã€‚ +3) irq_domain_activate_irq(): 激活ä¸æ–æŽ§åˆ¶å™¨ç¡¬ä»¶ä»¥ä¼ é€’ä¸æ–。 +4) irq_domain_deactivate_irq(): åœç”¨ä¸æ–控制器硬件，åœæ¢ä¼ 递ä¸æ–。 + +为了支æŒirq_domain层次结构，需è¦åšå¦‚下修改: + +1) 一个新的å—段 'parent' è¢«æ·»åŠ åˆ°irq_domain结构ä¸ï¼›å®ƒç”¨äºŽç»´æŠ¤irq_domain的层次信æ¯ã€‚ +2) 一个新的å—段 'parent_data' è¢«æ·»åŠ åˆ°irq_data结构ä¸ï¼›å®ƒç”¨äºŽå»ºç«‹å±‚次结构irq_data以 + 匹é…irq_domain层次结构。irq_data用于å˜å‚¨irq_domain指针和硬件irqå·ã€‚ +3) æ–°çš„å›žè°ƒè¢«æ·»åŠ åˆ°irq_domain_ops结构ä¸ï¼Œä»¥æ”¯æŒå±‚次结构的irq_domainæ“作。 + +在支æŒåˆ†å±‚irq_domain和分层irq_data准备就绪åŽï¼Œä¸ºæ¯ä¸ªä¸æ–控制器建立一个irq_domain结 +构，并为æ¯ä¸ªä¸ŽIRQ相关è”çš„irq_domain分é…一个irq_data结构。现在我们å¯ä»¥å†è¿›ä¸€æ¥æ”¯æŒå † +æ ˆå¼(层次结构)çš„irq_chip。也就是说，一个irq_chip与层次结构ä¸çš„æ¯ä¸ªirq_data相关è”。 +一个åirq_chipå¯ä»¥è‡ªå·±æˆ–通过与它的父irq_chipåˆä½œæ¥å®žçŽ°ä¸€ä¸ªæ‰€éœ€çš„æ“作。 + +é€šè¿‡å †æ ˆå¼çš„irq_chip，ä¸æ–控制器驱动åªéœ€è¦å¤„ç†è‡ªå·±ç®¡ç†çš„硬件，在需è¦çš„时候å¯ä»¥å‘其父 +irq_chip请求æœåŠ¡ã€‚所以我们å¯ä»¥å®žçŽ°æ›´ç®€æ´çš„软件架构。 + +为了让ä¸æ–控制器驱动程åºæ”¯æŒirq_domain层次结构，它需è¦åšåˆ°ä»¥ä¸‹å‡ 点: + +1) 实现 irq_domain_ops.alloc å’Œ irq_domain_ops.free +2) å¯é€‰æ‹©åœ°å®žçŽ° irq_domain_ops.activate å’Œ irq_domain_ops.deactivate. +3) å¯é€‰æ‹©åœ°å®žçŽ°ä¸€ä¸ªirq_chipæ¥ç®¡ç†ä¸æ–控制器硬件。 +4) ä¸éœ€è¦å®žçŽ°irq_domain_ops.mapå’Œirq_domain_ops.unmap，它们在层次结构 + irq_domainä¸æ˜¯ä¸ç”¨çš„。 + +irq_domain层次结构ç»ä¸æ˜¯x86特有的，大é‡ç”¨äºŽæ”¯æŒå…¶ä»–架构，如ARMã€ARM64ç‰ã€‚ + +调试功能 +======== + +打开CONFIG_GENERIC_IRQ_DEBUGFS，å¯è®©IRQå系统的大部分内部结构都在debugfsä¸æš´éœ²å‡ºæ¥ã€‚ diff --git a/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst new file mode 100644 index 000000000000..c889bd0f65d9 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst @@ -0,0 +1,45 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irqflags-tracing` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irqflags-tracing.rst: + + +================= +IRQ-flags状æ€è¿½è¸ª +================= + +:Author: 最åˆç”±Ingo Molnar <mingo@redhat.com>开始撰写 + +“irq-flags tracingâ€ï¼ˆä¸æ–æ ‡å¿—è¿½è¸ªï¼‰åŠŸèƒ½å¯ä»¥ “追踪†hardirqå’Œsoftirq的状æ€ï¼Œå®ƒè®© +感兴趣的åç³»ç»Ÿæœ‰æœºä¼šäº†è§£åˆ°åˆ°å†…æ ¸ä¸å‘生的æ¯ä¸€ä¸ª +hardirqs-off/hardirqs-onã€softirqs-off/softirqs-on事件。 + +CONFIG_TRACE_IRQFLAGS_SUPPORT是通用é”调试代ç æ供的CONFIG_PROVE_SPIN_LOCKING +å’ŒCONFIG_PROVE_RW_LOCKING所需è¦çš„。å¦åˆ™å°†åªæœ‰CONFIG_PROVE_MUTEX_LOCKINGå’Œ +CONFIG_PROVE_RWSEM_LOCKING在一个架构上被æä¾›--这些都是ä¸åœ¨IRQ上下文ä¸ä½¿ç”¨çš„ +é”API。（rwsems的一个异常是å¯ä»¥è§£å†³çš„） + +架构对这一点的支æŒå½“然ä¸å±žäºŽâ€œå¾®ä¸è¶³é“â€çš„èŒƒç•´ï¼Œå› ä¸ºå¾ˆå¤šä½Žçº§çš„æ±‡ç¼–ä»£ç 都è¦å¤„ç†irq-flags +的状æ€å˜åŒ–。但是一个架构å¯ä»¥ä»¥ä¸€ç§ç›¸å½“ç›´æŽ¥ä¸”æ— é£Žé™©çš„æ–¹å¼å¯ç”¨irq-flags-tracing。 + +架构如果想支æŒè¿™ä¸ªï¼Œéœ€è¦å…ˆåšä¸€äº›ä»£ç 组织上的改å˜: + +- 在他们的arch级Kconfig文件ä¸æ·»åŠ 并å¯ç”¨TRACE_IRQFLAGS_SUPPORT。 + +然åŽè¿˜éœ€è¦åšä¸€äº›åŠŸèƒ½ä¸Šçš„改å˜æ¥å®žçŽ°å¯¹irq-flags-tracing的支æŒ: + +- 在低级入å£ä»£ç ä¸å¢žåŠ （构建æ¡ä»¶ï¼‰å¯¹trace_hardirqs_off()/trace_hardirqs_on() + 函数的调用。é”验è¯å™¨ä¼šå¯†åˆ‡å…³æ³¨ “realâ€çš„irq-flags是å¦ä¸Ž “virtualâ€çš„irq-flags + 状æ€ç›¸åŒ¹é…，如果两者ä¸åŒ¹é…，则会å‘出è¦å‘Šï¼ˆå¹¶å…³é—自己）。通常维护archä¸ + irq-flags-track的大部分时间都是在这ç§çŠ¶æ€ä¸‹åº¦è¿‡çš„：看看lockdepçš„è¦å‘Šï¼Œè¯•ç€ + 找出我们还没有æžå®šçš„汇编代ç 。修å¤å¹¶é‡å¤ã€‚一旦系统å¯åŠ¨ï¼Œå¹¶ä¸”在irq-flags跟踪功 + 能ä¸æ²¡æœ‰å‡ºçŽ°lockdepè¦å‘Šçš„情况下，arch支æŒå°±å®Œæˆäº†ã€‚ + +- 如果该架构有ä¸å¯å±è”½çš„ä¸æ–，那么需è¦é€šè¿‡lockdep_off()/lockdep_on()å°†è¿™äº›ä¸ + æ–从irq跟踪[å’Œé”验è¯]机制ä¸æŽ’除。 + + 一般æ¥è¯´ï¼Œåœ¨ä¸€ä¸ªæž¶æž„ä¸ï¼Œä¸å®Œæ•´çš„irq-flags-tracing实现是没有风险的：lockdep + 会检测到这一点，并将自己关é—。å³é”验è¯å™¨ä»ç„¶å¯é 。应该ä¸ä¼šå› 为irq-tracingçš„é”™ + 误而崩溃。（除éžé€šè¿‡ä¿®æ”¹ä¸è¯¥ä¿®æ”¹çš„æ¡ä»¶æ¥æ›´æ”¹æ±‡ç¼–或寄å˜å™¨è€Œç ´å其他代ç ） diff --git a/Documentation/translations/zh_CN/cpu-freq/core.rst b/Documentation/translations/zh_CN/cpu-freq/core.rst new file mode 100644 index 000000000000..19fb9c029cfe --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/core.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/core` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_core.rst: + + +==================================== +CPUFreqæ ¸å¿ƒå’ŒCPUFreq通知器的通用说明 +==================================== + +作者: + - Dominik Brodowski <linux@brodo.de> + - David Kimdon <dwhedon@debian.org> + - Rafael J. Wysocki <rafael.j.wysocki@intel.com> + - Viresh Kumar <viresh.kumar@linaro.org> + +.. 目录: + + 1. CPUFreqæ ¸å¿ƒå’ŒæŽ¥å£ + 2. CPUFreq通知器 + 3. å«æœ‰Operating Performance Point (OPP)çš„CPUFreqè¡¨çš„ç”Ÿæˆ + +1. CPUFreqæ ¸å¿ƒå’ŒæŽ¥å£ +====================== + +cpufreqæ ¸å¿ƒä»£ç ä½äºŽdrivers/cpufreq/cpufreq.cä¸ã€‚这些cpufreq代ç 为CPUFreq架构的驱 +动程åºï¼ˆé‚£äº›æ“作硬件切æ¢é¢‘率的代ç ï¼‰ä»¥åŠ "通知器 "æä¾›äº†ä¸€ä¸ªæ ‡å‡†åŒ–çš„æŽ¥å£ã€‚ +这些是设备驱动程åºæˆ–需è¦äº†è§£ç–ç•¥å˜åŒ–çš„å…¶å®ƒå†…æ ¸éƒ¨åˆ†ï¼ˆå¦‚ ACPI çƒé‡ç®¡ç†ï¼‰æˆ–所有频率更改（除 +计时代ç 外），甚至需è¦å¼ºåˆ¶ç¡®å®šé€Ÿåº¦é™åˆ¶çš„通知器（如 ARM 架构上的 LCD 驱动程åºï¼‰ã€‚ +æ¤å¤–， å†…æ ¸ "常数" loops_per_jiffyä¼šæ ¹æ®é¢‘率å˜åŒ–而更新。 + +cpufreqç–略的引用计数由 cpufreq_cpu_get å’Œ cpufreq_cpu_put æ¥å®Œæˆï¼Œä»¥ç¡®ä¿ cpufreq 驱 +动程åºè¢«æ£ç¡®åœ°æ³¨å†Œåˆ°æ ¸å¿ƒä¸ï¼Œå¹¶ä¸”驱动程åºåœ¨ cpufreq_put_cpu 被调用之å‰ä¸ä¼šè¢«å¸è½½ã€‚这也ä¿è¯ +了æ¯ä¸ªCPUæ ¸çš„cpufreq ç–略在使用期间ä¸ä¼šè¢«é‡Šæ”¾ã€‚ + +2. CPUFreq 通知器 +==================== + +CPUFreq通知器符åˆæ ‡å‡†çš„å†…æ ¸é€šçŸ¥å™¨æŽ¥å£ã€‚ +关于通知器的细节请å‚阅 linux/include/linux/notifier.h。 + +这里有两个ä¸åŒçš„CPUfreq通知器 - ç–略通知器和转æ¢é€šçŸ¥å™¨ã€‚ + + +2.1 CPUFreqç–略通知器 +---------------------------- + +当创建或移除ç–略时，这些都会被通知。 + +阶段是在通知器的第二个å‚æ•°ä¸æŒ‡å®šçš„。当第一次创建ç–略时，阶段是CPUFREQ_CREATE_POLICY，当 +ç–略被移除时，阶段是CPUFREQ_REMOVE_POLICY。 + +第三个å‚æ•° ``void *pointer`` 指å‘一个结构体cpufreq_policy，其包括min，max(æ–°ç–略的下é™å’Œ +上é™ï¼ˆå•ä½ä¸ºkHz）)è¿™å‡ ä¸ªå€¼ã€‚ + + +2.2 CPUFreq转æ¢é€šçŸ¥å™¨ +-------------------------------- + +当CPUfreq驱动切æ¢CPUæ ¸å¿ƒé¢‘çŽ‡æ—¶ï¼Œç–ç•¥ä¸çš„æ¯ä¸ªåœ¨çº¿CPU都会收到两次通知，这些å˜åŒ–没有任何外部干 +预。 + +第二个å‚数指定阶段 - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. + +第三个å‚数是一个包å«å¦‚下值的结构体cpufreq_freqs： + +===== ==================== +cpu å—å½±å“cpuçš„ç¼–å· +old 旧频率 +new 新频率 +flags cpufreqé©±åŠ¨çš„æ ‡å¿— +===== ==================== + +3. å«æœ‰Operating Performance Point (OPP)çš„CPUFreqè¡¨çš„ç”Ÿæˆ +================================================================== +关于OPP的细节请å‚阅 Documentation/power/opp.rst + +dev_pm_opp_init_cpufreq_table - + 这个功能æ供了一个éšæ—¶å¯ç”¨çš„转æ¢ç¨‹åºï¼Œç”¨æ¥å°†OPP层关于å¯ç”¨é¢‘率的内部信æ¯ç¿»è¯‘æˆä¸€ç§å®¹æ˜“æ供给 + cpufreqçš„æ ¼å¼ã€‚ + + .. Warning:: + + ä¸è¦åœ¨ä¸æ–上下文ä¸ä½¿ç”¨æ¤å‡½æ•°ã€‚ + + 例如:: + + soc_pm_init() + { + /* Do things */ + r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); + if (!r) + policy->freq_table = freq_table; + /* Do other things */ + } + + .. note:: + + 该函数åªæœ‰åœ¨CONFIG_PM_OPP之外还å¯ç”¨äº†CONFIG_CPU_FREQæ—¶æ‰å¯ç”¨ã€‚ + +dev_pm_opp_free_cpufreq_table + 释放dev_pm_opp_init_cpufreq_table分é…的表。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst new file mode 100644 index 000000000000..0ca2cb646666 --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -0,0 +1,259 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/cpu-drivers` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_cpu-drivers.rst: + + +======================================= +如何实现一个新的CPUFreq处ç†å™¨é©±åŠ¨ç¨‹åºï¼Ÿ +======================================= + +作者: + + + - Dominik Brodowski <linux@brodo.de> + - Rafael J. Wysocki <rafael.j.wysocki@intel.com> + - Viresh Kumar <viresh.kumar@linaro.org> + +.. Contents + + 1. 怎么åšï¼Ÿ + 1.1 åˆå§‹åŒ– + 1.2 Per-CPU åˆå§‹åŒ– + 1.3 éªŒè¯ + 1.4 target/target_index 或 setpolicy? + 1.5 target/target_index + 1.6 setpolicy + 1.7 get_intermediate 与 target_intermediate + 2. 频率表助手 + + + +1. 怎么åšï¼Ÿ +=========== + +如æ¤ï¼Œä½ 刚刚得到了一个全新的CPU/芯片组åŠå…¶æ•°æ®æ‰‹å†Œï¼Œå¹¶å¸Œæœ›ä¸ºè¿™ä¸ªCPU/èŠ¯ç‰‡ç»„æ·»åŠ cpufreq +支æŒï¼Ÿå¾ˆå¥½ï¼Œè¿™é‡Œæœ‰ä¸€äº›è‡³å…³é‡è¦çš„æ示： + + +1.1 åˆå§‹åŒ– +---------- + +首先，在__initcall_level_7 (module_init())或更é åŽçš„函数ä¸æ£€æŸ¥è¿™ä¸ªå†…æ ¸æ˜¯å¦ +è¿è¡Œåœ¨æ£ç¡®çš„CPUå’Œæ£ç¡®çš„芯片组上。如果是，则使用cpufreq_register_driver()å‘ +CPUfreqæ ¸å¿ƒå±‚æ³¨å†Œä¸€ä¸ªcpufreq_driver结构体。 + +结构体cpufreq_driver应该包å«ä»€ä¹ˆæˆå‘˜? + + .name - 驱动的åå—。 + + .init - 一个指å‘per-policyåˆå§‹åŒ–函数的指针。 + + .verify - 一个指å‘"verification"函数的指针。 + + .setpolicy 或 .fast_switch 或 .target 或 .target_index - å·®å¼‚è§ + 下文。 + +并且å¯é€‰æ‹© + + .flags - cpufreqæ ¸çš„æ示。 + + .driver_data - cpufreq驱动程åºçš„特定数æ®ã€‚ + + .resolve_freq - 返回最适åˆç›®æ ‡é¢‘率的频率。ä¸è¿‡å¹¶ä¸èƒ½æ”¹å˜é¢‘率。 + + .get_intermediate å’Œ target_intermediate - 用于在改å˜CPU频率时切æ¢åˆ°ç¨³å®š + 的频率。 + + .get - 返回CPU的当å‰é¢‘率。 + + .bios_limit - 返回HW/BIOS对CPU的最大频率é™åˆ¶å€¼ã€‚ + + .exit - 一个指å‘per-policy清ç†å‡½æ•°çš„指针，该函数在cpuçƒæ’拔过程的CPU_POST_DEAD + 阶段被调用。 + + .stop_cpu - 一个指å‘per-policyåœæ¢å‡½æ•°çš„指针，该函数在cpuçƒæ’拔过程的CPU_DOWN_PREPARE + 阶段被调用。 + + .suspend - 一个指å‘per-policyæš‚åœå‡½æ•°çš„指针，该函数在关ä¸æ–且在该ç–略的调节器åœæ¢ + åŽè¢«è°ƒç”¨ã€‚ + + .resume - 一个指å‘per-policyæ¢å¤å‡½æ•°çš„指针，该函数在关ä¸æ–且在调节器å†ä¸€æ¬¡å¼€å§‹å‰è¢« + 调用。 + + .ready - 一个指å‘per-policy准备函数的指针，该函数在ç–略完全åˆå§‹åŒ–之åŽè¢«è°ƒç”¨ã€‚ + + .attr - 一个指å‘NULL结尾的"struct freq_attr"列表的指针，该函数å…许导出值到 + sysfs。 + + .boost_enabled - 如果设置，则å¯ç”¨æå‡(boost)频率。 + + .set_boost - 一个指å‘per-policy函数的指针，该函数用æ¥å¼€å¯/å…³é—æå‡(boost)频率功能。 + + +1.2 Per-CPU åˆå§‹åŒ– +------------------ + +æ¯å½“一个新的CPU被注册到设备模型ä¸ï¼Œæˆ–者在cpufreq驱动注册自己之åŽï¼Œå¦‚æžœæ¤CPUçš„cpufreqç– +ç•¥ä¸å˜åœ¨ï¼Œåˆ™ä¼šè°ƒç”¨per-policyçš„åˆå§‹åŒ–函数cpufreq_driver.init。请注æ„，.init()å’Œ.exit()ç¨‹åº +åªå¯¹ç–略调用一次，而ä¸æ˜¯å¯¹ç–略管ç†çš„æ¯ä¸ªCPU调用一次。它需è¦ä¸€ä¸ª ``struct cpufreq_policy +*policy`` 作为å‚数。现在该怎么åšå‘¢ï¼Ÿ + +如果有必è¦ï¼Œè¯·åœ¨ä½ çš„CPU上激活CPUfreq功能支æŒã€‚ + +然åŽï¼Œé©±åŠ¨ç¨‹åºå¿…须填写以下数值: + ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.min_freq å’Œ | | +|policy->cpuinfo.max_freq | 该CPU支æŒçš„最低和最高频率（kHz） | +| | | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.transition_latency | | +| | CPU在两个频率之间切æ¢æ‰€éœ€çš„时间，以 | +| | 纳秒为å•ä½ï¼ˆå¦‚适用，å¦åˆ™æŒ‡å®š | +| | CPUFREQ_ETERNAL） | ++-----------------------------------+--------------------------------------+ +|policy->cur | 该CPU当å‰çš„工作频率(如适用) | +| | | ++-----------------------------------+--------------------------------------+ +|policy->min, | | +|policy->max, | | +|policy->policy and, if necessary, | | +|policy->governor | 必须包å«è¯¥cpuçš„ “默认ç–ç•¥â€ã€‚ç¨åŽ | +| | 会用这些值调用 | +| | cpufreq_driver.verify and either | +| | cpufreq_driver.setpolicy or | +| | cpufreq_driver.target/target_index | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpus | 用与这个CPU一起åšDVFSçš„(在线+离线) | +| | CPU(å³ä¸Žå®ƒå…±äº«æ—¶é’Ÿ/电压轨)的掩ç æ›´æ–° | +| | 这个 | +| | | ++-----------------------------------+--------------------------------------+ + +对于设置其ä¸çš„一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表助手å¯èƒ½ä¼šæœ‰å¸® +助。关于它们的更多信æ¯ï¼Œè¯·å‚è§ç¬¬2节。 + + +1.3 éªŒè¯ +-------- + +当用户决定设置一个新的ç–ç•¥(ç”± “policy,governor,min,max组æˆâ€)时，必须对这个ç–略进行验è¯ï¼Œ +ä»¥ä¾¿çº æ£ä¸å…¼å®¹çš„值。为了验è¯è¿™äº›å€¼ï¼Œcpufreq_verify_within_limits(``struct cpufreq_policy +*policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函数å¯èƒ½ä¼šæœ‰å¸®åŠ©ã€‚ +关于频率表助手的详细内容请å‚è§ç¬¬2节。 + +您需è¦ç¡®ä¿è‡³å°‘有一个有效频率（或工作范围）在 policy->min å’Œ policy->max 范围内。如果有必 +è¦ï¼Œå…ˆå¢žåŠ policy->max，åªæœ‰åœ¨æ²¡æœ‰åŠžæ³•çš„情况下，æ‰å‡å°‘policy->min。 + + +1.4 target 或 target_index 或 setpolicy 或 fast_switch? +------------------------------------------------------- + +大多数cpufreq驱动甚至大多数cpu频率å‡é™ç®—法åªå…许将CPUé¢‘çŽ‡è®¾ç½®ä¸ºé¢„å®šä¹‰çš„å›ºå®šå€¼ã€‚å¯¹äºŽè¿™äº›ï¼Œä½ +å¯ä»¥ä½¿ç”¨->target()，->target_index()或->fast_switch()回调。 + +有些cpufreq功能的处ç†å™¨å¯ä»¥è‡ªå·±åœ¨æŸäº›é™åˆ¶ä¹‹é—´åˆ‡æ¢é¢‘率。这些应使用->setpolicy()回调。 + + +1.5. target/target_index +------------------------ + +target_index调用有两个å‚数：``struct cpufreq_policy * policy``å’Œ``unsigned int`` +索引(于列出的频率表)。 + +当调用这里时，CPUfreq驱动必须设置新的频率。实际频率必须由freq_table[index].frequency决定。 + +它应该总是在错误的情况下æ¢å¤åˆ°ä¹‹å‰çš„频率(å³policy->restore_freq)，å³ä½¿æˆ‘们之å‰åˆ‡æ¢åˆ°ä¸é—´é¢‘率。 + +已弃用 +---------- +ç›®æ ‡è°ƒç”¨æœ‰ä¸‰ä¸ªå‚数。``struct cpufreq_policy * policy``, unsigned int target_frequency, +unsigned int relation. + +CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须使用以下规则æ¥ç¡®å®šã€‚ + +- 紧跟 "ç›®æ ‡é¢‘çŽ‡"。 +- policy->min <= new_freq <= policy->max (这必须是有效的!!!) +- 如果 relation==CPUFREQ_REL_L，å°è¯•é€‰æ‹©ä¸€ä¸ªé«˜äºŽæˆ–ç‰äºŽ target_freq çš„ new_freq。("L代表 + 最低，但ä¸èƒ½ä½ŽäºŽ") +- 如果 relation==CPUFREQ_REL_H，å°è¯•é€‰æ‹©ä¸€ä¸ªä½ŽäºŽæˆ–ç‰äºŽ target_freq çš„ new_freq。("H代表 + 最高，但ä¸èƒ½é«˜äºŽ") + +这里，频率表助手å¯èƒ½ä¼šå¸®åŠ©ä½ --详è§ç¬¬2节。 + +1.6. fast_switch +---------------- + +这个函数用于从调度器的上下文进行频率切æ¢ã€‚并éžæ‰€æœ‰çš„驱动都è¦å®žçŽ°å®ƒï¼Œå› 为ä¸å…许在这个回调ä¸ç¡çœ 。这 +个回调必须ç»è¿‡é«˜åº¦ä¼˜åŒ–，以尽å¯èƒ½å¿«åœ°è¿›è¡Œåˆ‡æ¢ã€‚ + +这个函数有两个å‚数： ``struct cpufreq_policy *policy`` å’Œ ``unsigned int target_frequency``。 + + +1.7 setpolicy +------------- + +setpolicy调用åªéœ€è¦ä¸€ä¸ª``struct cpufreq_policy * policy``作为å‚数。需è¦å°†å¤„ç†å™¨å†…或芯片组内动æ€é¢‘ +率切æ¢çš„下é™è®¾ç½®ä¸ºpolicy->min，上é™è®¾ç½®ä¸ºpolicy->max，如果支æŒçš„è¯ï¼Œå½“policy->policy为 +CPUFREQ_POLICY_PERFORMANCE时选择é¢å‘性能的设置，当CPUFREQ_POLICY_POWERSAVE时选择é¢å‘çœç”µçš„设置。 +也å¯ä»¥æŸ¥çœ‹drivers/cpufreq/longrun.cä¸çš„å‚考实现。 + +1.8 get_intermediate å’Œ target_intermediate +-------------------------------------------- + +仅适用于 target_index() å’Œ CPUFREQ_ASYNC_NOTIFICATION 未设置的驱动。 + +get_intermediate应该返回一个平å°æƒ³è¦åˆ‡æ¢åˆ°çš„稳定的ä¸é—´é¢‘率，target_intermediate()应该将CPU设置为 +该频率，然åŽå†è·³è½¬åˆ°'index'å¯¹åº”çš„é¢‘çŽ‡ã€‚æ ¸å¿ƒä¼šè´Ÿè´£å‘é€é€šçŸ¥ï¼Œé©±åŠ¨ä¸å¿…在target_intermediate()或 +target_index()ä¸å¤„ç†ã€‚ + +在驱动程åºä¸æƒ³å› 为æŸä¸ªç›®æ ‡é¢‘率切æ¢åˆ°ä¸é—´é¢‘率的情况下，它们å¯ä»¥ä»Žget_intermediate()ä¸è¿”回'0'。在这ç§æƒ…况 +ä¸‹ï¼Œæ ¸å¿ƒå°†ç›´æŽ¥è°ƒç”¨->target_index()。 + +注æ„：->target_index()应该在失败的情况下æ¢å¤åˆ°policy->restore_freqï¼Œå› ä¸ºcore会为æ¤å‘é€é€šçŸ¥ã€‚ + + +2. 频率表助手 +============= + +由于大多数cpufreq处ç†å™¨åªå…è®¸è¢«è®¾ç½®ä¸ºå‡ ä¸ªç‰¹å®šçš„é¢‘çŽ‡ï¼Œå› æ¤ï¼Œä¸€ä¸ªå¸¦æœ‰ä¸€äº›å‡½æ•°çš„ “频率表â€å¯èƒ½ä¼šè¾…助处ç†å™¨é©±åŠ¨ +程åºçš„ä¸€äº›å·¥ä½œã€‚è¿™æ ·çš„ "频率表" 由一个cpufreq_frequency_tableæ¡ç›®æž„æˆçš„数组组æˆï¼Œ"driver_data" ä¸åŒ… +å«äº†é©±åŠ¨ç¨‹åºçš„具体数值，"frequency" ä¸åŒ…å«äº†ç›¸åº”çš„é¢‘çŽ‡ï¼Œå¹¶è®¾ç½®äº†æ ‡å¿—ã€‚åœ¨è¡¨çš„æœ€åŽï¼Œéœ€è¦æ·»åŠ 一个 +cpufreq_frequency_tableæ¡ç›®ï¼Œé¢‘率设置为CPUFREQ_TABLE_END。而如果想跳过表ä¸çš„一个æ¡ç›®ï¼Œåˆ™å°†é¢‘率设置为 +CPUFREQ_ENTRY_INVALID。这些æ¡ç›®ä¸éœ€è¦æŒ‰ç…§ä»»ä½•ç‰¹å®šçš„顺åºæŽ’åºï¼Œä½†å¦‚果它们是cpufreq æ ¸å¿ƒä¼šå¯¹å®ƒä»¬è¿›è¡Œå¿«é€Ÿçš„DVFS， +å› ä¸ºæœç´¢æœ€ä½³åŒ¹é…会更快。 + +如果ç–略在其policy->freq_tableå—段ä¸åŒ…å«ä¸€ä¸ªæœ‰æ•ˆçš„指针，cpufreqè¡¨å°±ä¼šè¢«æ ¸å¿ƒè‡ªåŠ¨éªŒè¯ã€‚ + +cpufreq_frequency_table_verify()ä¿è¯è‡³å°‘有一个有效的频率在policy->minå’Œpolicy->max范围内，并且所有其他 +æ ‡å‡†éƒ½è¢«æ»¡è¶³ã€‚è¿™å¯¹->verify调用很有帮助。 + +cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。åªè¦æŠŠæ•°å€¼ä¼ 递给这个函数，这个函数就会返 +回包å«CPUè¦è®¾ç½®çš„频率的频率表æ¡ç›®ã€‚ + +以下å®å¯ä»¥ä½œä¸ºcpufreq_frequency_tableçš„è¿ä»£å™¨ã€‚ + +cpufreq_for_each_entry(pos, table) - é历频率表的所有æ¡ç›®ã€‚ + +cpufreq_for_each_valid_entry(pos, table) - 该函数é历所有æ¡ç›®ï¼Œä¸åŒ…括CPUFREQ_ENTRY_INVALID频率。 +使用å‚æ•° "pos"-一个``cpufreq_frequency_table * `` 作为循环å˜é‡ï¼Œä½¿ç”¨å‚æ•° "table"-ä½œä¸ºä½ æƒ³è¿ä»£ +çš„``cpufreq_frequency_table * `` 。 + +例如:: + + struct cpufreq_frequency_table *pos, *driver_freq_table; + + cpufreq_for_each_entry(pos, driver_freq_table) { + /* Do something with pos */ + pos->frequency = ... + } + +å¦‚æžœä½ éœ€è¦åœ¨driver_freq_tableä¸å¤„ç†posçš„ä½ç½®ï¼Œä¸è¦å‡åŽ»æŒ‡é’ˆï¼Œå› 为它的代价相当高。相åï¼Œä½¿ç”¨å® +cpufreq_for_each_entry_idx() å’Œ cpufreq_for_each_valid_entry_idx() 。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst new file mode 100644 index 000000000000..c90d1d8353ed --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/cpufreq-stats` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_cpufreq-stats.rst: + + +========================================== +sysfs CPUFreq Stats的一般说明 +========================================== + +ç”¨æˆ·ä¿¡æ¯ + + +作者: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> + +.. Contents + + 1. 简介 + 2. æ供的统计数æ®(举例说明) + 3. é…ç½®cpufreq-stats + + +1. 简介 +=============== + +cpufreq-stats是一个为æ¯ä¸ªCPUæä¾›CPU频率统计的驱动。 +这些统计数æ®åœ¨/sysfsä¸ä»¥ä¸€å †åªè¯»æŽ¥å£çš„å½¢å¼æ供。这个接å£ï¼ˆåœ¨é…置好åŽï¼‰å°†å‡ºçŽ°åœ¨ +/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）ä¸cpufreqä¸‹çš„ä¸€ä¸ªå• +独的目录ä¸ï¼Œæ供给æ¯ä¸ªCPU。 +å„ç§ç»Ÿè®¡æ•°æ®å°†åœ¨æ¤ç›®å½•ä¸‹å½¢æˆåªè¯»æ–‡ä»¶ã€‚ + +æ¤é©±åŠ¨æ˜¯ç‹¬ç«‹äºŽä»»ä½•å¯èƒ½è¿è¡Œåœ¨ä½ 所用CPU上的特定cpufreq_driverè€Œè®¾è®¡çš„ã€‚å› æ¤ï¼Œå®ƒå°†ä¸Žæ‰€æœ‰ +cpufreq_driver一起工作。 + + +2. æ供的统计数æ®(举例说明) +===================================== + +cpufreq statsæ供了以下统计数æ®ï¼ˆåœ¨ä¸‹é¢è¯¦ç»†è§£é‡Šï¼‰ã€‚ + +- time_in_state +- total_trans +- trans_table + +所有的统计数æ®å°†ä»Žç»Ÿè®¡é©±åŠ¨è¢«è½½å…¥çš„时间（或统计被é‡ç½®çš„时间）开始，到æŸä¸€ç»Ÿè®¡æ•°æ®è¢«è¯»å–的时间为æ¢ã€‚ +显然，统计驱动ä¸ä¼šæœ‰ä»»ä½•å…³äºŽç»Ÿè®¡é©±åŠ¨è½½å…¥ä¹‹å‰çš„频率转æ¢ä¿¡æ¯ã€‚ + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l + total 0 + drwxr-xr-x 2 root root 0 May 14 16:06 . + drwxr-xr-x 3 root root 0 May 14 15:58 .. + --w------- 1 root root 4096 May 14 16:06 reset + -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state + -r--r--r-- 1 root root 4096 May 14 16:06 total_trans + -r--r--r-- 1 root root 4096 May 14 16:06 trans_table + +- **reset** + +åªå†™å±žæ€§ï¼Œå¯ç”¨äºŽé‡ç½®ç»Ÿè®¡è®¡æ•°å™¨ã€‚这对于评估ä¸åŒè°ƒèŠ‚器下的系统行为éžå¸¸æœ‰ç”¨ï¼Œä¸”æ— éœ€é‡å¯ã€‚ + + +- **time_in_state** + +æ¤é¡¹ç»™å‡ºäº†è¿™ä¸ªCPU所支æŒçš„æ¯ä¸ªé¢‘率所花费的时间。cat输出的æ¯ä¸€è¡Œéƒ½ä¼šæœ‰"<frequency> +<time>"对，表示这个CPU在<frequency>上花费了<time>个usertimeå•ä½çš„时间。这里的 +usertimeå•ä½æ˜¯10mS（类似于/procä¸è¾“出的其他时间）。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state + 3600000 2089 + 3400000 136 + 3200000 34 + 3000000 67 + 2800000 172488 + + +- **total_trans** + +给出了这个CPU上频率转æ¢çš„总次数。cat的输出将有一个å•ä¸€çš„计数，这就是频率转æ¢çš„总数。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans + 20 + +- **trans_table** + +这将æ供所有CPU频率转æ¢çš„细粒度信æ¯ã€‚这里的cat输出是一个二维矩阵，其ä¸ä¸€ä¸ªæ¡ç›®<i, j>（第 +i行，第j列）代表从Freq_i到Freq_j的转æ¢æ¬¡æ•°ã€‚Freq_i行和Freq_j列éµå¾ªé©±åŠ¨æœ€åˆæ供给cpufreq +æ ¸çš„é¢‘çŽ‡è¡¨çš„æŽ’åºé¡ºåºï¼Œå› æ¤å¯ä»¥æŽ’åºï¼ˆå‡åºæˆ–é™åºï¼‰æˆ–ä¸æŽ’åºã€‚ 这里的输出也包å«äº†æ¯è¡Œæ¯åˆ—的实际 +频率值，以便更好地阅读。 + +如果转æ¢è¡¨å¤§äºŽPAGE_SIZE，读å–时将返回一个-EFBIG错误。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table + From : To + : 3600000 3400000 3200000 3000000 2800000 + 3600000: 0 5 0 0 0 + 3400000: 4 0 2 0 0 + 3200000: 0 1 0 2 0 + 3000000: 0 0 1 0 3 + 2800000: 0 0 0 2 0 + +3. é…ç½®cpufreq-stats +============================ + +è¦åœ¨ä½ çš„å†…æ ¸ä¸é…ç½®cpufreq-stats:: + + Config Main Menu + Power management options (ACPI, APM) ---> + CPU Frequency scaling ---> + [*] CPU Frequency scaling + [*] CPU frequency translation statistics + + +"CPU Frequency scaling" (CONFIG_CPU_FREQ) 应该被å¯ç”¨ä»¥é…ç½®cpufreq-stats。 + +"CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT)æ供了包括 +time_in_stateã€total_transå’Œtrans_table的统计数æ®ã€‚ + +一旦å¯ç”¨äº†è¿™ä¸ªé€‰é¡¹ï¼Œå¹¶ä¸”ä½ çš„CPU支æŒcpufrequencyï¼Œä½ å°±å¯ä»¥åœ¨/sysfsä¸çœ‹åˆ°CPU频率统计。 diff --git a/Documentation/translations/zh_CN/cpu-freq/index.rst b/Documentation/translations/zh_CN/cpu-freq/index.rst new file mode 100644 index 000000000000..65074e211940 --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/index.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_index.rst: + + +======================================================= +Linux CPUFreq - Linux(TM)å†…æ ¸ä¸çš„CPU频率和电压å‡é™ä»£ç +======================================================= + +Author: Dominik Brodowski <linux@brodo.de> + + 时钟å‡é™å…è®¸ä½ åœ¨è¿è¡Œä¸æ”¹å˜CPU的时钟速度。这是一个很好的节çœç”µæ± 电é‡çš„æ–¹æ³•ï¼Œå› ä¸ºæ—¶ + 钟速度越低，CPU消耗的电é‡è¶Šå°‘。 + + +.. toctree:: + :maxdepth: 1 + + core + cpu-drivers + cpufreq-stats + +邮件列表 +------------ +这里有一个 CPU 频率å˜åŒ–çš„ CVS æ交和通用列表，您å¯ä»¥åœ¨è¿™é‡ŒæŠ¥å‘Šbugã€é—®é¢˜æˆ–æ交补ä¸ã€‚è¦å‘ +布消æ¯ï¼Œè¯·å‘é€ç”µå邮件到 linux-pm@vger.kernel.org。 + +链接 +----- +FTP档案: +* ftp://ftp.linux.org.uk/pub/linux/cpufreq/ + +如何访问CVS仓库: +* http://cvs.arm.linux.org.uk/ + +CPUFreq邮件列表: +* http://vger.kernel.org/vger-lists.html#linux-pm + +SA-1100çš„æ—¶é’Ÿå’Œç”µåŽ‹æ ‡åº¦: +* http://www.lartmaker.nl/projects/scaling diff --git a/Documentation/translations/zh_CN/dev-tools/gcov.rst b/Documentation/translations/zh_CN/dev-tools/gcov.rst new file mode 100644 index 000000000000..3158c9da1318 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/gcov.rst @@ -0,0 +1,264 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/gcov.rst +:Translator: 赵军奎 Bernard Zhao <bernard@vivo.com> + +在Linuxå†…æ ¸é‡Œä½¿ç”¨gcovåšä»£ç 覆盖率检查 +===================================== + +gcov分æžæ ¸å¿ƒæ”¯æŒåœ¨Linuxå†…æ ¸ä¸å¯ç”¨GCC的覆盖率测试工具 gcov_ ，Linuxå†…æ ¸ +è¿è¡Œæ—¶çš„代ç 覆盖率数æ®ä¼šä»¥gcovå…¼å®¹çš„æ ¼å¼å¯¼å‡ºåˆ°â€œgcovâ€debugfs目录ä¸ï¼Œå¯ +以通过gcovçš„ ``-o`` 选项（如下示例）获得指定文件的代ç è¿è¡Œè¦†ç›–çŽ‡ç»Ÿè®¡æ•°æ® +（需è¦è·³è½¬åˆ°å†…æ ¸ç¼–è¯‘è·¯å¾„ä¸‹å¹¶ä¸”è¦æœ‰rootæƒé™ï¼‰:: + + # cd /tmp/linux-out + # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c + +这将在当å‰ç›®å½•ä¸åˆ›å»ºå¸¦æœ‰æ‰§è¡Œè®¡æ•°æ³¨é‡Šçš„æºä»£ç 文件。 +在获得这些统计文件åŽï¼Œå¯ä»¥ä½¿ç”¨å›¾å½¢åŒ–çš„gcovå‰ç«¯å·¥å…·ï¼ˆæ¯”如 lcov_ ），æ¥å®žçŽ° +自动化处ç†Linuxå†…æ ¸çš„è¦†ç›–çŽ‡è¿è¡Œæ•°æ®ï¼ŒåŒæ—¶ç”Ÿæˆæ˜“于阅读的HTMLæ ¼å¼æ–‡ä»¶ã€‚ + +å¯èƒ½çš„用途: + +* 调试（用æ¥åˆ¤æ–æ¯ä¸€è¡Œçš„代ç 是å¦å·²ç»è¿è¡Œè¿‡ï¼‰ +* 测试改进（如何修改测试代ç ，尽å¯èƒ½åœ°è¦†ç›–到没有è¿è¡Œè¿‡çš„代ç ） +* å†…æ ¸æœ€å°åŒ–é…置（对于æŸä¸€ä¸ªé€‰é¡¹é…置，如果关è”的代ç 从æ¥æ²¡æœ‰è¿è¡Œè¿‡ï¼Œ + 是å¦è¿˜éœ€è¦è¿™ä¸ªé…置） + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php + + +准备 +---- + +å†…æ ¸æ‰“å¼€å¦‚ä¸‹é…ç½®:: + + CONFIG_DEBUG_FS=y + CONFIG_GCOV_KERNEL=y + +获å–æ•´ä¸ªå†…æ ¸çš„è¦†ç›–çŽ‡æ•°æ®ï¼Œè¿˜éœ€è¦æ‰“å¼€:: + + CONFIG_GCOV_PROFILE_ALL=y + +需è¦æ³¨æ„çš„æ˜¯ï¼Œæ•´ä¸ªå†…æ ¸å¼€å¯è¦†ç›–çŽ‡ç»Ÿè®¡ä¼šé€ æˆå†…æ ¸é•œåƒæ–‡ä»¶å°ºå¯¸çš„增大， +åŒæ—¶å†…æ ¸è¿è¡Œä¹Ÿä¼šå˜æ…¢ä¸€äº›ã€‚ +å¦å¤–，并ä¸æ˜¯æ‰€æœ‰çš„架构都支æŒæ•´ä¸ªå†…æ ¸å¼€å¯è¦†ç›–率统计。 + +代ç è¿è¡Œè¦†ç›–率数æ®åªåœ¨debugfs挂载完æˆåŽæ‰å¯ä»¥è®¿é—®:: + + mount -t debugfs none /sys/kernel/debug + + +定制化 +------ + +如果è¦å•ç‹¬é’ˆå¯¹æŸä¸€ä¸ªè·¯å¾„或者文件进行代ç 覆盖率统计，å¯ä»¥åœ¨å†…æ ¸ç›¸åº”è·¯ +径的Makefileä¸å¢žåŠ 如下的é…ç½®: + +- å•ç‹¬ç»Ÿè®¡å•ä¸ªæ–‡ä»¶ï¼ˆä¾‹å¦‚main.o）:: + + GCOV_PROFILE_main.o := y + +- å•ç‹¬ç»Ÿè®¡æŸä¸€ä¸ªè·¯å¾„:: + + GCOV_PROFILE := y + +如果è¦åœ¨æ•´ä¸ªå†…æ ¸çš„è¦†ç›–çŽ‡ç»Ÿè®¡ï¼ˆå¼€å¯CONFIG_GCOV_PROFILE_ALL）ä¸å•ç‹¬æŽ’除 +æŸä¸€ä¸ªæ–‡ä»¶æˆ–者路径，å¯ä»¥ä½¿ç”¨å¦‚下的方法:: + + GCOV_PROFILE_main.o := n + +å’Œ:: + + GCOV_PROFILE := n + +æ¤æœºåˆ¶ä»…支æŒé“¾æŽ¥åˆ°å†…æ ¸é•œåƒæˆ–ç¼–è¯‘ä¸ºå†…æ ¸æ¨¡å—的文件。 + + +相关文件 +-------- + +gcov功能需è¦åœ¨debugfsä¸åˆ›å»ºå¦‚下文件: + +``/sys/kernel/debug/gcov`` + gcovç›¸å…³åŠŸèƒ½çš„æ ¹è·¯å¾„ + +``/sys/kernel/debug/gcov/reset`` + 全局å¤ä½æ–‡ä»¶:å‘该文件写入数æ®åŽä¼šå°†æ‰€æœ‰çš„gcov统计数æ®æ¸…0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` + gcov工具å¯ä»¥è¯†åˆ«çš„覆盖率统计数æ®æ–‡ä»¶ï¼Œå‘该文件写入数æ®åŽ + 会将本文件的gcov统计数æ®æ¸…0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` + gcov工具需è¦çš„软连接文件（指å‘编译时生æˆçš„ä¿¡æ¯ç»Ÿè®¡æ–‡ä»¶ï¼‰ï¼Œè¿™ä¸ªæ–‡ä»¶æ˜¯ + 在gcc编译时如果é…置了选项 ``-ftest-coverage`` 时生æˆçš„。 + + +针对模å—的统计 +-------------- + +å†…æ ¸ä¸çš„模å—会动æ€çš„åŠ è½½å’Œå¸è½½ï¼Œæ¨¡å—å¸è½½æ—¶å¯¹åº”çš„æ•°æ®ä¼šè¢«æ¸…除掉。 +gcovæ供了一ç§æœºåˆ¶ï¼Œé€šè¿‡ä¿ç•™ç›¸å…³æ•°æ®çš„副本æ¥æ”¶é›†è¿™éƒ¨åˆ†å¸è½½æ¨¡å—的覆盖率数æ®ã€‚ +模å—å¸è½½åŽè¿™äº›å¤‡ä»½æ•°æ®åœ¨debugfsä¸ä¼šç»§ç»å˜åœ¨ã€‚ +一旦这个模å—é‡æ–°åŠ 载，模å—å…³è”çš„è¿è¡Œç»Ÿè®¡ä¼šè¢«åˆå§‹åŒ–æˆdebugfsä¸å¤‡ä»½çš„æ•°æ®ã€‚ + +å¯ä»¥é€šè¿‡å¯¹å†…æ ¸å‚æ•°gcov_persist的修改æ¥åœç”¨gcov对模å—的备份机制:: + + gcov_persist = 0 + +在è¿è¡Œæ—¶ï¼Œç”¨æˆ·è¿˜å¯ä»¥é€šè¿‡å†™å…¥æ¨¡å—çš„æ•°æ®æ–‡ä»¶æˆ–者写入gcovå¤ä½æ–‡ä»¶æ¥ä¸¢å¼ƒå·²å¸ +载模å—çš„æ•°æ®ã€‚ + + +编译机和测试机分离 +------------------ + +gcovçš„å†…æ ¸åˆ†æžæ’桩支æŒå†…æ ¸çš„ç¼–è¯‘å’Œè¿è¡Œæ˜¯åœ¨åŒä¸€å°æœºå™¨ä¸Šï¼Œä¹Ÿå¯ä»¥ç¼–è¯‘å’Œè¿ +行是在ä¸åŒçš„机器上。 +å¦‚æžœå†…æ ¸ç¼–è¯‘å’Œè¿è¡Œæ˜¯ä¸åŒçš„机器，那么需è¦é¢å¤–的准备工作，这å–决于gcov工具 +是在哪里使用的: + +.. _gcov-test_zh: + +a) è‹¥gcovè¿è¡Œåœ¨æµ‹è¯•æœºä¸Š + + 测试机上é¢gcov工具的版本必须è¦è·Ÿå†…æ ¸ç¼–è¯‘æœºå™¨ä½¿ç”¨çš„gcc版本相兼容， + åŒæ—¶ä¸‹é¢çš„文件è¦ä»Žç¼–译机拷è´åˆ°æµ‹è¯•æœºä¸Š: + + 从æºä»£ç ä¸: + - 所有的C文件和头文件 + + 从编译目录ä¸: + - 所有的C文件和头文件 + - 所有的.gcda文件和.gcno文件 + - 所有目录的链接 + + 特别需è¦æ³¨æ„，测试机器上é¢çš„目录结构跟编译机器上é¢çš„目录机构必须 + 完全一致。 + 如果文件是软链接，需è¦æ›¿æ¢æˆçœŸæ£çš„目录文件（这是由make的当å‰å·¥ä½œ + 目录å˜é‡CURDIR引起的）。 + +.. _gcov-build_zh: + +b) è‹¥gcovè¿è¡Œåœ¨ç¼–译机上 + + 测试用例è¿è¡Œç»“æŸåŽï¼Œå¦‚下的文件需è¦ä»Žæµ‹è¯•æœºä¸æ‹·è´åˆ°ç¼–译机上: + + 从sysfsä¸çš„gcov目录ä¸: + - 所有的.gcda文件 + - 所有的.gcno文件软链接 + + 这些文件å¯ä»¥æ‹·è´åˆ°ç¼–译机的任æ„目录下，gcov使用-o选项指定拷è´çš„ + 目录。 + + 比如一个是示例的目录结构如下:: + + /tmp/linux: å†…æ ¸æºç 目录 + /tmp/out: å†…æ ¸ç¼–è¯‘æ–‡ä»¶è·¯å¾„ï¼ˆmake O=指定） + /tmp/coverage: 从测试机器上é¢æ‹·è´çš„æ•°æ®æ–‡ä»¶è·¯å¾„ + + [user@build] cd /tmp/out + [user@build] gcov -o /tmp/coverage/tmp/out/init main.c + + +关于编译器的注æ„事项 +-------------------- + +GCCå’ŒLLVM gcov工具ä¸ä¸€å®šå…¼å®¹ã€‚ +如果编译器是GCC，使用 gcov_ æ¥å¤„ç†.gcnoå’Œ.gcda文件，如果是Clang编译器， +则使用 llvm-cov_ 。 + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html + +GCCå’ŒClang gcov之间的版本差异由Kconfig处ç†çš„。 +kconfigä¼šæ ¹æ®ç¼–译工具链的检查自动选择åˆé€‚çš„gcovæ ¼å¼ã€‚ + +é—®é¢˜å®šä½ +-------- + +å¯èƒ½å‡ºçŽ°çš„问题1 + ç¼–è¯‘åˆ°é“¾æŽ¥é˜¶æ®µæŠ¥é”™ç»ˆæ¢ + +é—®é¢˜åŽŸå› + 分æžæ ‡å¿—指定在了æºæ–‡ä»¶ä½†æ˜¯æ²¡æœ‰é“¾æŽ¥åˆ°ä¸»å†…æ ¸ï¼Œæˆ–è€…å®¢åˆ¶åŒ–äº†é“¾æŽ¥ç¨‹åº + +解决方法 + 通过在相应的Makefileä¸ä½¿ç”¨ ``GCOV_PROFILE := n`` + 或者 ``GCOV_PROFILE_basename.o := n`` æ¥å°†é“¾æŽ¥æŠ¥é”™çš„文件排除掉 + +å¯èƒ½å‡ºçŽ°çš„问题2 + 从sysfså¤åˆ¶çš„文件显示为空或ä¸å®Œæ•´ + +é—®é¢˜åŽŸå› + 由于seq_file的工作方å¼ï¼ŒæŸäº›å·¥å…·ï¼ˆä¾‹å¦‚cp或tar）å¯èƒ½æ— 法æ£ç¡®åœ°ä»Ž + sysfså¤åˆ¶æ–‡ä»¶ã€‚ + +解决方法 + 使用 ``cat`` è¯»å– ``.gcda`` 文件，使用 ``cp -d`` å¤åˆ¶é“¾æŽ¥ï¼Œæˆ–者使用附录B + ä¸æ‰€ç¤ºçš„机制。 + + +附录A：collect_on_build.sh +-------------------------- + +用于在编译机上收集覆盖率元文件的示例脚本 +ï¼ˆè§ :ref:`编译机和测试机分离 a. <gcov-test_zh>` ） + +.. code-block:: sh + + #!/bin/bash + + KSRC=$1 + KOBJ=$2 + DEST=$3 + + if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then + echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 + exit 1 + fi + + KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + + find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ + -perm /u+r,g+r | tar cfz $DEST -P -T - + + if [ $? -eq 0 ] ; then + echo "$DEST successfully created, copy to test system and unpack with:" + echo " tar xfz $DEST -P" + else + echo "Could not create file $DEST" + fi + + +附录B：collect_on_test.sh +------------------------- + +用于在测试机上收集覆盖率数æ®æ–‡ä»¶çš„示例脚本 +ï¼ˆè§ :ref:`编译机和测试机分离 b. <gcov-build_zh>` ） + +.. code-block:: sh + + #!/bin/bash -e + + DEST=$1 + GCDA=/sys/kernel/debug/gcov + + if [ -z "$DEST" ] ; then + echo "Usage: $0 <output.tar.gz>" >&2 + exit 1 + fi + + TEMPDIR=$(mktemp -d) + echo Collecting data.. + find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; + find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; + find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; + tar czf $DEST -C $TEMPDIR sys + rm -rf $TEMPDIR + + echo "$DEST successfully created, copy to build system and unpack with:" + echo " tar xfz $DEST" diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst new file mode 100644 index 000000000000..fd73c479917b --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -0,0 +1,35 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/index.rst +:Translator: 赵军奎 Bernard Zhao <bernard@vivo.com> + +============ +å†…æ ¸å¼€å‘工具 +============ + +æœ¬æ–‡æ¡£æ˜¯æœ‰å…³å†…æ ¸å¼€å‘工具文档的åˆé›†ã€‚ +ç›®å‰è¿™äº›æ–‡æ¡£å·²ç»æ•´ç†åœ¨ä¸€èµ·ï¼Œä¸éœ€è¦å†èŠ±è´¹é¢å¤–的精力。 +欢迎任何补ä¸ã€‚ + +.. class:: toc-title + + 目录 + +.. toctree:: + :maxdepth: 2 + + gcov + +Todolist: + + - coccinelle + - sparse + - kcov + - kasan + - ubsan + - kmemleak + - kcsan + - gdb-kernel-debugging + - kgdb + - kselftest + - kunit/index diff --git a/Documentation/translations/zh_CN/disclaimer-zh_CN.rst b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst index dcf803ede85a..3c6db094a63c 100644 --- a/Documentation/translations/zh_CN/disclaimer-zh_CN.rst +++ b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst @@ -6,4 +6,4 @@ .. note:: 如果您å‘现本文档与原始文件有任何ä¸åŒæˆ–者有翻译问题，请è”系该文件的译者， - 或者请求时奎亮的帮助：<alex.shi@linux.alibaba.com>。 + 或者请求时奎亮的帮助：<alexs@kernel.org>。 diff --git a/Documentation/translations/zh_CN/doc-guide/contributing.rst b/Documentation/translations/zh_CN/doc-guide/contributing.rst new file mode 100644 index 000000000000..394a13b438b0 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/contributing.rst @@ -0,0 +1,238 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/contributing.rst + +:译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +å¦‚ä½•å¸®åŠ©æ”¹è¿›å†…æ ¸æ–‡æ¡£ +==================== + +在任何软件开å‘项目ä¸ï¼Œæ–‡æ¡£éƒ½æ˜¯é‡è¦ç»„æˆéƒ¨åˆ†ã€‚好的文档有助于引入新的开å‘人员， +并帮助已有的开å‘人员更有效地工作。如果缺少高质é‡çš„文档，大é‡çš„时间就会浪费在 +代ç 的逆å‘工程和犯本å¯é¿å…的错误上。 + +ä¸å¹¸çš„æ˜¯ï¼Œå†…æ ¸çš„æ–‡æ¡£ç›®å‰è¿œè¿œä¸èƒ½æ»¡è¶³æ”¯æŒå¦‚æ¤è§„模和é‡è¦æ€§çš„项目的需è¦ã€‚ + +本指å—适用于希望帮助改善这ç§çŠ¶å†µçš„è´¡çŒ®è€…ã€‚å†…æ ¸æ–‡æ¡£çš„æ”¹è¿›å¯ä»¥ç”±å¼€å‘者在ä¸åŒçš„ +技能层级上进行；这也是一æ¡ç›¸å¯¹ç®€å•å¯ä»¥å¸®åŠ©æ‚¨äº†è§£å†…æ ¸è¿‡ç¨‹å¹¶åœ¨ç¤¾åŒºä¸æ‰¾åˆ°ä¸€å¸ä¹‹ +地的路径。下é¢çš„大部分内容是文档维护人员列出的最迫切需è¦å®Œæˆçš„任务。 + +文档待办事项列表 +---------------- + +为了使我们的文档达到应有的水平，需è¦å®Œæˆçš„任务数ä¸èƒœæ•°ã€‚æ¤åˆ—表包å«è®¸å¤šé‡è¦çš„ +项目，但还远远ä¸å¤Ÿè¯¦å°½ï¼›å¦‚果您知é“改进文档的其他方法，请ä¸è¦ç¾žäºŽå¯é½¿ã€‚ + +消除è¦å‘Šï¼ˆWARNING） +~~~~~~~~~~~~~~~~~~~ + +文档构建目å‰å‡ºçŽ°äº†æ•°é‡æƒŠäººçš„è¦å‘Šã€‚è™±å多了ä¸ç—’，债多了ä¸æ„；大伙儿忽略了它们， +他们永远ä¸ä¼šæ³¨æ„åˆ°ä»–ä»¬çš„å·¥ä½œå¢žåŠ äº†æ–°çš„è¦å‘Šã€‚å› æ¤ï¼Œæ¶ˆé™¤è¦å‘Šæ˜¯æ–‡æ¡£å¾…办事项列表 +ä¸ä¼˜å…ˆçº§æœ€é«˜çš„任务之一。这项任务本身相当简å•ï¼Œä½†å¿…须以æ£ç¡®çš„æ–¹å¼è¿›è¡Œï¼Œæ‰èƒ½å– +å¾—æˆåŠŸã€‚ + +C代ç 编译器å‘出的è¦å‘Šå¸¸å¸¸ä¼šè¢«è§†ä¸ºè¯¯æŠ¥ï¼Œä»Žè€Œå¯¼è‡´å‡ºçŽ°äº†æ—¨åœ¨è®©ç¼–译器é—嘴的补ä¸ã€‚ +文档构建ä¸çš„è¦å‘Šå‡ 乎总是指å‘真æ£çš„问题；è¦æ¶ˆé™¤è¿™äº›è¦å‘Šï¼Œéœ€è¦ç†è§£é—®é¢˜å¹¶ä»Žæºå¤´ä¸Š +è§£å†³é—®é¢˜ã€‚å› æ¤ï¼Œä¿®å¤æ–‡æ¡£è¦å‘Šçš„è¡¥ä¸ä¸åº”åœ¨æ ‡é¢˜ä¸ç›´æŽ¥å†™â€œä¿®å¤è¦å‘Šâ€ï¼›å®ƒä»¬åº”该指明 +真æ£ä¿®å¤çš„问题。 + +å¦ä¸€ä¸ªé‡ç‚¹æ˜¯ï¼Œæ–‡æ¡£è¦å‘Šå¸¸å¸¸ç”±C代ç 里kernel-doc注释ä¸çš„问题引起。虽然文档维护 +人员对收到这些修å¤è¡¥ä¸çš„å‰¯æœ¬è¡¨ç¤ºæ„Ÿè°¢ï¼Œä½†æ˜¯æ–‡æ¡£æ ‘å®žé™…ä¸Šé€šå¸¸å¹¶ä¸é€‚åˆæŽ¥å—这些 +è¡¥ä¸ï¼›å®ƒä»¬åº”该被交给相关å系统的维护人员。 + +例如，在一次文档构建ä¸ï¼Œæˆ‘å‡ ä¹Žæ˜¯éšæ„选å–了一对è¦å‘Š:: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + +（作了æ–行以便于阅读） + +简å•çœ‹ä¸€ä¸‹ä¸Šé¢ç»™å‡ºçš„æºæ–‡ä»¶ï¼Œä¼šå‘çŽ°å‡ ä¸ªkernel-doc注释，如下所示:: + + /** + * devm_devfreq_register_notifier() + - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + * @list: DEVFREQ_TRANSITION_NOTIFIER. + */ + +问题在于缺了一个“*â€ï¼Œè¿™ä¸ç¬¦åˆæž„建系统对C注释å—çš„æ ¼å¼è¦æ±‚。æ¤é—®é¢˜è‡ª2016年注释 +è¢«æ·»åŠ ä»¥æ¥ä¸€ç›´å˜åœ¨â€”—整整四年之久。修å¤å®ƒåªéœ€è¦æ·»åŠ 丢失的星å·ã€‚看一眼该文件的 +历å²è®°å½•ä»¥äº†è§£ä¸»é¢˜è¡Œçš„å¸¸è§„æ ¼å¼æ˜¯ä»€ä¹ˆæ ·ï¼Œå†ä½¿ç”¨ ``scripts/get_maintainer.pl`` +æ¥æžæ¸…è°åº”当收到æ¤è¡¥ä¸ã€‚生æˆçš„è¡¥ä¸å¦‚下所示:: + + [PATCH] PM / devfreq: Fix two malformed kerneldoc comments + + Two kerneldoc comments in devfreq.c fail to adhere to the required format, + resulting in these doc-build warnings: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + + Add a couple of missing asterisks and make kerneldoc a little happier. + + Signed-off-by: Jonathan Corbet <corbet@lwn.net> + --- + drivers/devfreq/devfreq.c | 4 ++-- + 1 file changed, 2 insertions(+), 2 deletions(-) + + diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c + index 57f6944d65a6..00c9b80b3d33 100644 + --- a/drivers/devfreq/devfreq.c + +++ b/drivers/devfreq/devfreq.c + @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) + + /** + * devm_devfreq_register_notifier() + - - Resource-managed devfreq_register_notifier() + + * - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); + + /** + * devm_devfreq_unregister_notifier() + - - Resource-managed devfreq_unregister_notifier() + + * - Resource-managed devfreq_unregister_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + -- + 2.24.1 + +整个过程åªèŠ±äº†å‡ 分钟。当然，我åŽæ¥å‘现有人在å¦ä¸€ä¸ªæ ‘ä¸ä¿®å¤äº†å®ƒï¼Œè¿™äº®å‡ºäº†å¦ä¸€ +个教è®ï¼šåœ¨æ·±å…¥ç ”究问题之å‰ï¼Œä¸€å®šè¦æ£€æŸ¥linux-nextæ ‘ï¼Œçœ‹çœ‹é—®é¢˜æ˜¯å¦å·²ç»ä¿®å¤ã€‚ + +其他修å¤å¯èƒ½éœ€è¦æ›´é•¿çš„时间，尤其是那些与缺少文档的结构体æˆå‘˜æˆ–函数å‚数相关的 +ä¿®å¤ã€‚è¿™ç§æƒ…况下，需è¦æ‰¾å‡ºè¿™äº›æˆå‘˜æˆ–å‚数的作用，并æ£ç¡®æè¿°å®ƒä»¬ã€‚æ€»ä¹‹ï¼Œè¿™ç§ +任务有时会有点ä¹å‘³ï¼Œä½†å®ƒéžå¸¸é‡è¦ã€‚如果我们真的å¯ä»¥ä»Žæ–‡æ¡£æž„建ä¸æ¶ˆé™¤è¦å‘Šï¼Œé‚£ä¹ˆ +我们就å¯ä»¥å¼€å§‹æœŸæœ›å¼€å‘人员开始注æ„é¿å…æ·»åŠ æ–°çš„è¦å‘Šäº†ã€‚ + +“迷失的â€kernel-doc注释 +~~~~~~~~~~~~~~~~~~~~~~ + +å¼€å‘者被鼓励去为他们的代ç 写kernel-doc注释，但是许多注释从未被引入文档构建。 +这使得这些信æ¯æ›´éš¾æ‰¾åˆ°ï¼Œä¾‹å¦‚使Sphinxæ— æ³•ç”ŸæˆæŒ‡å‘该文档的链接。将 ``kernel-doc`` +æŒ‡ä»¤æ·»åŠ åˆ°æ–‡æ¡£ä¸ä»¥å¼•å…¥è¿™äº›æ³¨é‡Šå¯ä»¥å¸®åŠ©ç¤¾åŒºèŽ·å¾—为编写注释所åšå·¥ä½œçš„全部价值。 + +``scripts/find-unused-docs.sh`` 工具å¯ä»¥ç”¨æ¥æ‰¾åˆ°è¿™äº›è¢«å¿½ç•¥çš„评论。 + +请注æ„，将导出的函数和数æ®ç»“构引入文档是最有价值的。许多å系统还具有供内部 +使用的kernel-doc注释；除éžè¿™äº›æ³¨é‡Šæ”¾åœ¨ä¸“门针对相关å系统开å‘人员的文档ä¸ï¼Œ +å¦åˆ™ä¸åº”将其引入文档构建ä¸ã€‚ + + +ä¿®æ£é”™å— +~~~~~~~~ + + +ä¿®å¤æ–‡æ¡£ä¸çš„æŽ’ç‰ˆæˆ–æ ¼å¼é”™è¯¯æ˜¯ä¸€ç§å¿«é€Ÿå¦ä¹ 如何创建和å‘é€ä¿®è¡¥ç¨‹åºçš„方法，也是 +一项有用的æœåŠ¡ã€‚我总是愿æ„接å—è¿™æ ·çš„è¡¥ä¸ã€‚这也æ„味ç€ï¼Œä¸€æ—¦ä½ ä¿®å¤äº†ä¸€äº›è¿™ç§ +错误，请考虑转移到更高级的任务，留下一些拼写错误给下一个åˆå¦è€…解决。 + +请注æ„，有些并 **ä¸æ˜¯** 拼写错误，ä¸åº”该被“修å¤â€ï¼š + + - å†…æ ¸æ–‡æ¡£ä¸ç”¨ç¾Žå¼å’Œè‹±å¼è‹±è¯æ‹¼å†™çš†å¯ï¼Œæ²¡æœ‰å¿…è¦äº’相倒æ¢ã€‚ + + - åœ¨å†…æ ¸æ–‡æ¡£ä¸ï¼Œæ²¡å¿…è¦è®¨è®ºå¥ç‚¹åŽé¢åº”è¯¥è·Ÿä¸€ä¸ªè¿˜æ˜¯ä¸¤ä¸ªç©ºæ ¼çš„é—®é¢˜ã€‚å…¶ä»–ä¸€äº›æœ‰ + åˆç†åˆ†æ§çš„地方，比如“牛津逗å·â€ï¼Œåœ¨è¿™ä¹Ÿæ˜¯è·‘题的。 + +与对任何项目的任何补ä¸ä¸€æ ·ï¼Œè¯·è€ƒè™‘您的更改是å¦çœŸçš„让事情å˜å¾—更好。 + +“上å¤â€æ–‡æ¡£ +~~~~~~~~~~ + +ä¸€äº›å†…æ ¸æ–‡æ¡£æ˜¯æœ€æ–°çš„ã€è¢«ç»´æŠ¤çš„，并且éžå¸¸æœ‰ç”¨ï¼Œæœ‰äº›æ–‡ä»¶ç¡®å¹¶éžå¦‚æ¤ã€‚å°˜å°ã€é™ˆæ—§ +å’Œä¸å‡†ç¡®çš„文档å¯èƒ½ä¼šè¯¯å¯¼è¯»è€…，并对我们的整个文档产生怀疑。任何解决这些问题的 +事情都是éžå¸¸å—欢迎的。 + +æ— è®ºä½•æ—¶å¤„ç†æ–‡æ¡£ï¼Œè¯·è€ƒè™‘它是å¦æ˜¯æœ€æ–°çš„，是å¦éœ€è¦æ›´æ–°ï¼Œæˆ–者是å¦åº”è¯¥å®Œå…¨åˆ é™¤ã€‚ +您å¯ä»¥æ³¨æ„ä»¥ä¸‹å‡ ä¸ªè¦å‘Šæ ‡å¿—： + + - 对2.xå†…æ ¸çš„å¼•ç”¨ + - 指å‘SourceForgeå˜å‚¨åº“ + - 历å²è®°å½•é™¤äº†æ‹¼å†™é”™è¯¯å•¥ä¹Ÿæ²¡æœ‰æŒç»å‡ å¹´ + - 讨论Git之å‰æ—¶ä»£çš„å·¥ä½œæµ + +å½“ç„¶ï¼Œæœ€å¥½çš„åŠžæ³•æ˜¯æ›´æ–°æ–‡æ¡£ï¼Œæ·»åŠ æ‰€éœ€çš„ä»»ä½•ä¿¡æ¯ã€‚è¿™æ ·çš„å·¥ä½œé€šå¸¸éœ€è¦ä¸Žç†Ÿæ‚‰ç›¸å…³ +å系统的开å‘人员åˆä½œã€‚当有人善æ„地询问开å‘人员，并å¬å–他们的回ç”然åŽé‡‡å– +行动时，开å‘人员通常更愿æ„与这些致力于改进文档的人员åˆä½œã€‚ + +有些文档已ç»æ²¡å¸Œæœ›äº†ï¼›ä¾‹å¦‚，我们å¶å°”会å‘现引用了很久以å‰ä»Žå†…æ ¸ä¸åˆ 除的代ç çš„ +æ–‡æ¡£ã€‚åˆ é™¤è¿‡æ—¶çš„æ–‡æ¡£ä¼šç¢°è§ä»¤äººæƒŠè®¶çš„é˜»åŠ›ï¼Œä½†æˆ‘ä»¬æ— è®ºå¦‚ä½•éƒ½åº”è¯¥è¿™æ ·åšã€‚æ–‡æ¡£ä¸ +多余的粗æžå¤§å¶å¯¹ä»»ä½•äººéƒ½æ²¡æœ‰å¸®åŠ©ã€‚ + +如果一个严é‡è¿‡æ—¶çš„文档ä¸å¯èƒ½æœ‰ä¸€äº›æœ‰ç”¨çš„ä¿¡æ¯ï¼Œè€Œæ‚¨åˆæ— 法更新它，那么最好在 +å¼€å¤´æ·»åŠ ä¸€ä¸ªè¦å‘Šã€‚建议使用以下文本:: + + .. warning :: + This document is outdated and in need of attention. Please use + this information with caution, and please consider sending patches + to update it. + +è¿™æ ·çš„è¯ï¼Œè‡³å°‘我们长期å—苦的读者会得到文件å¯èƒ½ä¼šæŠŠä»–们引入æ§é€”çš„è¦å‘Šã€‚ + +文档一致性 +~~~~~~~~~~ + +这里的è€å‰è¾ˆä»¬ä¼šè®°å¾—上世纪90年代出现在书架上的Linux书ç±ï¼Œå®ƒä»¬åªæ˜¯ä»Žç½‘上ä¸åŒ +ä½ç½®æœæ¥çš„文档文件的集åˆã€‚在æ¤ä¹‹åŽï¼Œï¼ˆå¤§éƒ¨åˆ†ï¼‰è¿™äº›ä¹¦éƒ½å¾—åˆ°äº†æ”¹è¿›ï¼Œä½†æ˜¯å†…æ ¸çš„ +文档ä»ç„¶ä¸»è¦æ˜¯å»ºç«‹åœ¨è¿™ç§æ¨¡åž‹ä¸Šã€‚它有数åƒä¸ªæ–‡ä»¶ï¼Œå‡ 乎æ¯ä¸ªæ–‡ä»¶éƒ½æ˜¯ä¸Žå…¶ä»–文件相 +ç‹¬ç«‹ç¼–å†™çš„ã€‚æˆ‘ä»¬æ²¡æœ‰ä¸€ä¸ªè¿žè´¯çš„å†…æ ¸æ–‡æ¡£ï¼›åªæœ‰æ•°åƒä¸ªç‹¬ç«‹çš„文档。 + +我们一直试图通过编篡一套“书ç±â€æ¥æ”¹å–„è¿™ç§æƒ…况，以为特定读者æä¾›æˆå¥—文档。这 +包括： + + - Documentation/translations/zh_CN/admin-guide/index.rst + - Documentation/core-api/index.rst + - Documentation/driver-api/index.rst + - Documentation/userspace-api/index.rst + +以åŠæ–‡æ¡£æœ¬èº«è¿™æœ¬â€œä¹¦â€ã€‚ + +将文档移到适当的书ä¸æ˜¯ä¸€é¡¹é‡è¦çš„任务，需è¦ç»§ç»è¿›è¡Œã€‚ä¸è¿‡è¿™é¡¹å·¥ä½œè¿˜æ˜¯æœ‰ä¸€äº› +挑战性。移动文档会给处ç†è¿™äº›æ–‡æ¡£çš„人带æ¥çŸæœŸçš„ç—›è‹¦ï¼›ä»–ä»¬å¯¹è¿™äº›æ›´æ”¹æ— ç”šçƒæƒ… +也是å¯ä»¥ç†è§£çš„。通常情况下，å¯ä»¥å°†ä¸€ä¸ªæ–‡æ¡£ç§»åŠ¨ä¸€ä¸‹ï¼›ä¸è¿‡æˆ‘们真的ä¸æƒ³ä¸€ç›´ç§»åŠ¨ +它们。 + +å³ä½¿æ‰€æœ‰æ–‡ä»¶éƒ½åœ¨æ£ç¡®çš„ä½ç½®ï¼Œæˆ‘们也åªæ˜¯æŠŠä¸€å¤§å †æ–‡ä»¶å˜æˆä¸€ç¾¤å°å †æ–‡ä»¶ã€‚试图将 +所有这些文件组åˆæˆä¸€ä¸ªæ•´ä½“çš„å·¥ä½œå°šæœªå¼€å§‹ã€‚å¦‚æžœä½ å¯¹å¦‚ä½•åœ¨è¿™æ–¹é¢å–得进展有好的 +想法，我们将很高兴了解。 + +æ ·å¼è¡¨ï¼ˆStylesheet）改进 +~~~~~~~~~~~~~~~~~~~~~~~~ + +éšç€Sphinx的采用，我们得到了比以å‰æ›´å¥½çš„HTML输出。但它ä»ç„¶éœ€è¦å¾ˆå¤§çš„改进； +Donald Knuthå’ŒEdward Tufteå¯èƒ½æ˜¯æ˜ åƒå¹³å¹³çš„。这需è¦è°ƒæ•´æˆ‘ä»¬çš„æ ·å¼è¡¨ï¼Œä»¥åˆ›å»º +更具排版效果ã€å¯è®¿é—®æ€§å’Œå¯è¯»æ€§çš„输出。 + +请注æ„ï¼šå¦‚æžœä½ æ‰¿æ‹…è¿™ä¸ªä»»åŠ¡ï¼Œä½ å°†è¿›å…¥ç»å…¸çš„两难领域。å³ä½¿æ˜¯ç›¸å¯¹æ˜Žæ˜¾çš„å˜åŒ–， +也会有很多æ„è§å’Œè®¨è®ºã€‚唉，这就是我们生活的世界的本质。 + +æ— LaTeXçš„PDF构建 +~~~~~~~~~~~~~~~~ + +对于拥有大é‡æ—¶é—´å’ŒPython技能的人æ¥è¯´ï¼Œè¿™ç»å¯¹æ˜¯ä¸€é¡¹ä¸å¹³å‡¡çš„任务。Sphinx工具链 +相对较å°ä¸”包å«è‰¯å¥½ï¼›å¾ˆå®¹æ˜“æ·»åŠ åˆ°å¼€å‘系统ä¸ã€‚但是构建PDF或EPUB输出需è¦å®‰è£… +LaTeX，它ç»å¯¹ç§°ä¸ä¸Šå°æˆ–包å«è‰¯å¥½çš„。消除Latex将是一件很好的事情。 + +最åˆæ˜¯å¸Œæœ›ä½¿ç”¨ `rst2pdf <https://rst2pdf.org/>`_ 工具æ¥ç”ŸæˆPDF，但结果å‘现 +æ— æ³•èƒœä»»è¿™é¡¹ä»»åŠ¡ã€‚ä¸è¿‡rst2pdfçš„å¼€å‘工作最近似乎åˆæœ‰äº†èµ·è‰²ï¼Œè¿™æ˜¯ä¸ªå……满希望的 +迹象。如果有开å‘人员愿æ„与该项目åˆä½œï¼Œä½¿rst2pdfå¯ä¸Žå†…æ ¸æ–‡æ¡£æž„å»ºä¸€èµ·å·¥ä½œï¼Œ +大家会éžå¸¸æ„Ÿæ¿€ã€‚ + +编写更多文档 +~~~~~~~~~~~~ + +å½“ç„¶ï¼Œå†…æ ¸ä¸è®¸å¤šéƒ¨åˆ†çš„文档严é‡ä¸è¶³ã€‚å¦‚æžœæ‚¨æœ‰ç¼–å†™ä¸€ä¸ªç‰¹å®šå†…æ ¸å系统文档的相应 +知识并愿æ„è¿™æ ·åšï¼Œè¯·ä¸è¦çŠ¹è±«ï¼Œç¼–写并å‘å†…æ ¸è´¡çŒ®ç»“æžœå§ï¼æ•°ä¸æ¸…çš„å†…æ ¸å¼€å‘人员和 +ç”¨æˆ·ä¼šæ„Ÿè°¢ä½ ã€‚ diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst new file mode 100644 index 000000000000..5151953c196f --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/index.rst @@ -0,0 +1,27 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/index.rst + +:译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +.. _doc_guide_zh: + +================ +å¦‚ä½•ç¼–å†™å†…æ ¸æ–‡æ¡£ +================ + +.. toctree:: + :maxdepth: 1 + + sphinx + kernel-doc + parse-headers + contributing + maintainer-profile + +.. only:: å项目与HTML + + 目录 + ==== + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst new file mode 100644 index 000000000000..82ec84470c0b --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -0,0 +1,499 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/kernel-doc.rst + +:译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +编写kernel-doc注释 +================== + +Linuxå†…æ ¸æºæ–‡ä»¶å¯ä»¥åŒ…å«kernel-docæ ¼å¼çš„结构化文档注释，用以æ述代ç 的函数〠+类型和设计。将文档嵌入æºæ–‡ä»¶æ›´å®¹æ˜“ä¿æŒæ–‡æ¡£æœ€æ–°ã€‚ + +.. note:: å†…æ ¸æ–‡æ¡£æ ¼å¼ä¸Žjavadocã€gtk-doc或Doxygen看似很相似，但由于历å²åŽŸå› ， + 实际有ç€æ˜Žæ˜¾çš„ä¸åŒã€‚å†…æ ¸æºåŒ…å«æˆåƒä¸Šä¸‡ä¸ªkernel-doc注释。请åšæŒéµå¾ª + æ¤å¤„æè¿°çš„é£Žæ ¼ã€‚ + +.. note:: kernel-docæ— æ³•åŒ…å«Rust代ç ：请å‚考 Documentation/rust/docs.rst 。 + +从注释ä¸æå–kernel-doc结构，并从ä¸ç”Ÿæˆé€‚当的 `Sphinx C 域`_ 函数和带有锚点的 +类型æ述。这些注释将被过滤以生æˆç‰¹æ®Škernel-doc高亮和交å‰å¼•ç”¨ã€‚详è§ä¸‹æ–‡ã€‚ + +.. _Sphinx C 域: http://www.sphinx-doc.org/en/stable/domains.html + +使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出到å¯åŠ 载模å—çš„æ¯ä¸ªå‡½æ•°éƒ½ +应该有一个kernel-doc注释。模å—使用的头文件ä¸çš„函数和数æ®ç»“构也应该有 +kernel-doc注释。 + +å¯¹äºŽå…¶ä»–å†…æ ¸æ–‡ä»¶ï¼ˆæœªæ ‡è®°ä¸º ``static`` ）ä¸å¤–部å¯è§çš„函数，æä¾›kernel-docæ ¼å¼ +的文档是一个很好的实践。我们也建议为ç§æœ‰ï¼ˆæ–‡ä»¶ ``static`` ）程åºæä¾›kernel-doc +æ ¼å¼çš„文档，以确ä¿å†…æ ¸æºä»£ç 布局的一致性。æ¤å»ºè®®ä¼˜å…ˆçº§è¾ƒä½Žï¼Œç”±å†…æ ¸æºæ–‡ä»¶çš„ +维护者自行决定。 + +å¦‚ä½•æ ¼å¼åŒ–kernel-doc注释 +------------------------ + +kernel-doc注释用 ``/**`` ä½œä¸ºå¼€å§‹æ ‡è®°ã€‚ ``kernel-doc`` 工具将æå–以这ç§æ–¹å¼ +æ ‡è®°çš„æ³¨é‡Šã€‚æ³¨é‡Šå…¶ä½™éƒ¨åˆ†çš„æ ¼å¼ç±»ä¼¼äºŽä¸€ä¸ªæ™®é€šçš„多行注释，左侧有一列星å·ï¼Œä»¥ +``*/`` 行结æŸã€‚ + +函数和类型的kernel-doc注释应该放在所æ述的函数或类型之å‰ï¼Œä»¥ä¾¿æœ€å¤§é™åº¦åœ°æ高 +更改代ç 的人åŒæ—¶æ›´æ”¹æ–‡æ¡£çš„å¯èƒ½æ€§ã€‚概述kernel-doc注释å¯ä»¥æ”¾åœ¨æœ€é¡¶éƒ¨çš„任何地方。 + +用详细模å¼å’Œä¸ç”Ÿæˆå®žé™…输出æ¥è¿è¡Œ ``kernel-doc`` 工具，å¯ä»¥éªŒè¯æ–‡æ¡£æ³¨é‡Šçš„æ ¼å¼ +是å¦æ£ç¡®ã€‚例如:: + + scripts/kernel-doc -v -none drivers/foo/bar.c + +当请求执行é¢å¤–çš„gccæ£€æŸ¥æ—¶ï¼Œå†…æ ¸æž„å»ºå°†éªŒè¯æ–‡æ¡£æ ¼å¼:: + + make W=n + +函数文档 +-------- + +函数和函数å¼å®çš„kernel-docæ³¨é‡Šçš„ä¸€èˆ¬æ ¼å¼æ˜¯:: + + /** + * 函数å() - 函数简è¦è¯´æ˜Ž. + * @å‚æ•°1: æ述第一个å‚æ•°. + * @å‚æ•°2: æ述第二个å‚æ•°. + * å¯ä»¥ä¸ºå‚æ•°æ供一段 + * 多行æè¿°. + * + * 更详细的æ述，进一æ¥è®¨è®ºå‡½æ•° 函数å(), è¿™å¯èƒ½å¯¹ä½¿ç”¨æˆ–修改它的人有用. + * 以空注释行开始, 内部å¯ä»¥åŒ…å«ç©ºæ³¨é‡Šè¡Œ. + * + * 详细æè¿°å¯ä»¥æœ‰å¤šä¸ªæ®µè½. + * + * Context: æ述函数是å¦å¯ä»¥ä¼‘çœ , 它需è¦ã€é‡Šæ”¾æˆ–期望æŒæœ‰ä»€ä¹ˆé”. + * å¯ä»¥å†™å¤šè¡Œ. + * Return: æ述函数返回值. + * + * 返回值æ述也å¯ä»¥æœ‰å¤šä¸ªæ®µè½, + * 并且应该放在注释å—的末尾. + */ + +函数ååŽé¢çš„简çŸæè¿°å¯ä»¥è·¨å¤šè¡Œï¼Œå¹¶ä»¥å‚æ•°æè¿°ã€ç©ºæ³¨é‡Šè¡Œæˆ–注释å—结尾结æŸã€‚ + +函数å‚æ•° +~~~~~~~~ + +æ¯ä¸ªå‡½æ•°å‚数都应该按照顺åºæ述，紧跟在函数简è¦è¯´æ˜Žä¹‹åŽã€‚ä¸è¦åœ¨å‡½æ•°æè¿°å’Œå‚æ•° +之间，也ä¸è¦åœ¨å‚数之间留空。 + +æ¯ä¸ª ``@å‚æ•°:`` æè¿°å¯ä»¥è·¨å¤šè¡Œã€‚ + +.. note:: + + 如果 ``@å‚æ•°`` æ述有多行，则说明的ç»è¡Œåº”该从上一行的åŒä¸€åˆ—开始:: + + * @å‚æ•°: 较长说明 + * çš„ç»è¡Œ + + 或:: + + * @å‚æ•°: + * 较长说明 + * çš„ç»è¡Œ + +如果函数的å‚æ•°æ•°ç›®å¯å˜ï¼Œåˆ™éœ€ç”¨kernel-docæ ¼å¼å¯¹å…¶è¿›è¡Œæè¿°:: + + * @...: æè¿° + +函数上下文 +~~~~~~~~~~ + +å¯è°ƒç”¨å‡½æ•°çš„上下文应该在 ``Context`` 节ä¸æ述。æ¤èŠ‚åº”è¯¥åŒ…æ‹¬å‡½æ•°æ˜¯ä¼‘çœ çš„è¿˜æ˜¯ +å¯ä»¥ä»Žä¸æ–上下文调用的，以åŠå®ƒéœ€è¦ä»€ä¹ˆé”ã€é‡Šæ”¾ä»€ä¹ˆé”和期望它的调用者æŒæœ‰ä»€ä¹ˆ +é”。 + +例如:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects <lock> to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases <mutex>. + * Context: Softirq or process context. Takes and releases <lock>, BH-safe. + * Context: Interrupt context. + +返回值 +~~~~~~ + +如有返回值，应在 ``Return`` 节ä¸æ述。 + +.. note:: + + #) 您æ供的多行æ述文本 *ä¸ä¼š* 识别æ¢è¡Œç¬¦ï¼Œå› æ¤å¦‚果您想将æŸäº›æ–‡æœ¬é¢„æ ¼å¼åŒ–， + 如:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + 它们在最终文档ä¸å˜æˆä¸€è¡Œ:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + å› æ¤ï¼Œä¸ºäº†åœ¨éœ€è¦çš„地方æ¢è¡Œï¼Œæ‚¨éœ€è¦ä½¿ç”¨ReST列表，例如:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) 如果您æ供的æ述性文本ä¸çš„行以æŸä¸ªåŽè·Ÿå†’å·çš„çŸè¯å¼€å¤´ï¼Œåˆ™æ¯ä¸€ä¸ªè¿™ç§çŸè¯ + éƒ½å°†è¢«è§†ä¸ºæ–°çš„èŠ‚æ ‡é¢˜ï¼Œå¯èƒ½ä¼šäº§ç”Ÿæ„æ–™ä¸åˆ°çš„效果。 + +结构体ã€å…±ç”¨ä½“ã€æžšä¸¾ç±»åž‹æ–‡æ¡£ +---------------------------- + +结构体（struct）ã€å…±ç”¨ä½“（union）ã€æžšä¸¾ï¼ˆenum）类型kernel-docæ³¨é‡Šçš„ä¸€èˆ¬æ ¼å¼ä¸º:: + + /** + * struct 结构体å - 简è¦æè¿°. + * @æˆå‘˜1: æˆå‘˜1æè¿°. + * @æˆå‘˜2: æˆå‘˜2æè¿°. + * å¯ä»¥ä¸ºæˆå‘˜æä¾› + * 多行æè¿°. + * + * 结构体的æè¿°. + */ + +å¯ä»¥ç”¨ ``union`` 或 ``enum`` 替æ¢ä¸Šé¢ç¤ºä¾‹ä¸çš„ ``struct`` ，以æ述共用体或枚举。 +``æˆå‘˜`` 用于表示枚举ä¸çš„å…ƒç´ æˆ–å…±ç”¨ä½“æˆå‘˜ã€‚ + +结构体å称åŽé¢çš„简è¦è¯´æ˜Žå¯ä»¥è·¨å¤šè¡Œï¼Œå¹¶ä»¥æˆå‘˜è¯´æ˜Žã€ç©ºç™½æ³¨é‡Šè¡Œæˆ–注释å—结尾结æŸã€‚ + +æˆå‘˜ +~~~~ + +结构体ã€å…±ç”¨ä½“和枚举的æˆå‘˜åº”以与函数å‚数相åŒçš„æ–¹å¼è®°å½•ï¼›å®ƒä»¬åŽç´§è·Ÿç®€çŸçš„æ述， +并且为多行。 + +在结构体或共用体æè¿°ä¸ï¼Œå¯ä»¥ä½¿ç”¨ ``private:`` å’Œ ``public:`` æ³¨é‡Šæ ‡ç¾ã€‚ +``private:`` 域内的å—段ä¸ä¼šåˆ—在生æˆçš„文档ä¸ã€‚ + +``private:`` å’Œ ``public:`` æ ‡ç¾å¿…须紧跟在 ``/*`` æ³¨é‡Šæ ‡è®°ä¹‹åŽã€‚å¯ä»¥é€‰æ‹©æ˜¯å¦ +在 ``:`` å’Œ ``*/`` 结æŸæ ‡è®°ä¹‹é—´åŒ…å«æ³¨é‡Šã€‚ + +例å:: + + /** + * struct å¼ ä¸‰ - 简çŸæè¿° + * @a: 第一个æˆå‘˜ + * @b: 第二个æˆå‘˜ + * @d: 第三个æˆå‘˜ + * + * 详细æè¿° + */ + struct å¼ ä¸‰ { + int a; + int b; + /* private: 仅内部使用 */ + int c; + /* public: 下一个是公有的 */ + int d; + }; + +嵌套的结构体/共用体 +~~~~~~~~~~~~~~~~~~~ + +嵌套的结构体/共用体å¯åƒè¿™æ ·è®°å½•:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int memb1; + int memb2; + }; + struct { + void *memb3; + int memb4; + }; + }; + union { + struct { + int memb1; + int memb2; + } st1; + struct { + void *memb1; + int memb2; + } st2; + } bar; + }; + +.. note:: + + #) 在记录嵌套结构体或共用体时，如果结构体/共用体 ``å¼ ä¸‰`` 已命åï¼Œåˆ™å…¶ä¸ + çš„æˆå‘˜ ``æŽå››`` 应记录为 ``@å¼ ä¸‰.æŽå››:`` + + #) 当嵌套结构体/共用体是匿å的时，其ä¸çš„æˆå‘˜ ``æŽå››`` 应记录为 ``@æŽå››:`` + +行间注释文档 +~~~~~~~~~~~~ + +结构æˆå‘˜ä¹Ÿå¯åœ¨å®šä¹‰æ—¶ä»¥è¡Œé—´æ³¨é‡Šå½¢å¼è®°å½•ã€‚有两ç§æ ·å¼ï¼Œä¸€ç§æ˜¯å•è¡Œæ³¨é‡Šï¼Œå…¶ä¸å¼€å§‹ +``/**`` å’Œç»“æŸ ``*/`` ä½äºŽåŒä¸€è¡Œï¼›å¦ä¸€ç§æ˜¯å¤šè¡Œæ³¨é‡Šï¼Œå¼€å¤´ç»“å°¾å„自ä½äºŽä¸€è¡Œï¼Œå°± +åƒæ‰€æœ‰å…¶ä»–æ ¸å¿ƒæ–‡æ¡£æ³¨é‡Šä¸€æ ·:: + + /** + * struct å¼ ä¸‰ - 简çŸæè¿°. + * @å¼ ä¸‰: æˆå‘˜å¼ 三. + */ + struct å¼ ä¸‰ { + int å¼ ä¸‰; + /** + * @æŽå››: æˆå‘˜æŽå››. + */ + int æŽå››; + /** + * @王五: æˆå‘˜çŽ‹äº”. + * + * æ¤å¤„，æˆå‘˜æè¿°å¯ä»¥ä¸ºå¥½å‡ 段. + */ + int 王五; + union { + /** @å„¿å: å•è¡Œæè¿°. */ + int å„¿å; + }; + /** @èµµå…: æè¿°@å¼ ä¸‰é‡Œé¢çš„结构体@èµµå… */ + struct { + /** + * @èµµå….女儿: æè¿°@å¼ ä¸‰.èµµå…里é¢çš„@女儿 + */ + int 女儿; + } èµµå…; + }; + +Typedef文档 +----------- + +Typedefçš„kernel-docæ–‡æ¡£æ³¨é‡Šçš„ä¸€èˆ¬æ ¼å¼ä¸º:: + + /** + * typedef 类型å称 - 简çŸæè¿°. + * + * 类型æè¿°. + */ + +还å¯ä»¥è®°å½•å¸¦æœ‰å‡½æ•°åŽŸåž‹çš„typedef:: + + /** + * typedef 类型å称 - 简çŸæè¿°. + * @å‚æ•°1: å‚æ•°1çš„æè¿° + * @å‚æ•°2: å‚æ•°2çš„æè¿° + * + * 类型æè¿°. + * + * Context: é”（Locking）上下文. + * Return: 返回值的æ„义. + */ + typedef void (*类型å称)(struct v4l2_ctrl *å‚æ•°1, void *å‚æ•°2); + +高亮与交å‰å¼•ç”¨ +-------------- + +在kernel-doc注释的æ述文本ä¸å¯ä»¥è¯†åˆ«ä»¥ä¸‹ç‰¹æ®Šæ¨¡å¼ï¼Œå¹¶å°†å…¶è½¬æ¢ä¸ºæ£ç¡®çš„ +reStructuredTextæ ‡è®°å’Œ `Sphinx C 域`_ 引用。 + +.. attention:: 以下内容 **ä»…** 在kernel-doc注释ä¸è¯†åˆ«ï¼Œ **ä¸ä¼š** 在普通的 + reStructuredText文档ä¸è¯†åˆ«ã€‚ + +``funcname()`` + 函数引用。 + +``@parameter`` + 函数å‚æ•°çš„å称（未交å‰å¼•ç”¨ï¼Œä»…æ ¼å¼åŒ–）。 + +``%CONST`` + 常é‡çš„å称（未交å‰å¼•ç”¨ï¼Œä»…æ ¼å¼åŒ–）。 + +````literal```` + é¢„æ ¼å¼åŒ–文本å—。输出将使用ç‰è·å—体。 + + è‹¥ä½ éœ€è¦ä½¿ç”¨åœ¨kernel-doc脚本或reStructuredTextä¸æœ‰ç‰¹æ®Šå«ä¹‰çš„å—符，则æ¤åŠŸèƒ½ + éžå¸¸æœ‰ç”¨ã€‚ + + è‹¥ä½ éœ€è¦åœ¨å‡½æ•°æè¿°ä¸ä½¿ç”¨ç±»ä¼¼äºŽ ``%ph`` 的东西，这特别有用。 + +``$ENVVAR`` + 环境å˜é‡å称（未交å‰å¼•ç”¨ï¼Œä»…æ ¼å¼åŒ–）。 + +``&struct name`` + 结构体引用。 + +``&enum name`` + 枚举引用。 + +``&typedef name`` + Typedef引用。 + +``&struct_name->member`` or ``&struct_name.member`` + 结构体或共用体æˆå‘˜å¼•ç”¨ã€‚交å‰å¼•ç”¨å°†é“¾æŽ¥åˆ°ç»“构体或共用体定义，而ä¸æ˜¯ç›´æŽ¥åˆ°æˆå‘˜ã€‚ + +``&name`` + 泛类型引用。请首选上é¢æ述的完整引用方å¼ã€‚æ¤æ³•ä¸»è¦æ˜¯ä¸ºäº†å¯èƒ½æœªæ述的注释。 + +从reStructuredText交å‰å¼•ç”¨ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +æ— éœ€é¢å¤–çš„è¯æ³•æ¥ä»ŽreStructuredText文档交å‰å¼•ç”¨kernel-do注释ä¸å®šä¹‰çš„函数和类型。 +åªéœ€ä»¥ ``()`` 结æŸå‡½æ•°å，并在类型之å‰å†™ä¸Š ``struct`` ， ``union`` ， ``enum`` +或 ``typedef`` 。 +例如:: + + See foo(). + See struct foo. + See union bar. + See enum baz. + See typedef meh. + +è‹¥è¦åœ¨äº¤å‰å¼•ç”¨é“¾æŽ¥ä¸ä½¿ç”¨è‡ªå®šä¹‰æ–‡æœ¬ï¼Œå¯ä»¥é€šè¿‡ä»¥ä¸‹è¯æ³•è¿›è¡Œ:: + + See :c:func:`my custom link text for function foo <foo>`. + See :c:type:`my custom link text for struct bar <bar>`. + +有关更多详细信æ¯ï¼Œè¯·å‚阅 `Sphinx C 域`_ 文档。 + +总述性文档注释 +-------------- + +为了促进æºä»£ç 和注释紧密è”åˆï¼Œå¯ä»¥å°†kernel-doc文档å—作为自由形å¼çš„注释，而 +ä¸æ˜¯å‡½æ•°ã€ç»“æž„ã€è”åˆã€æžšä¸¾æˆ–typedef的绑定kernel-doc。例如，这å¯ä»¥ç”¨äºŽè§£é‡Š +驱动程åºæˆ–库代ç çš„æ“作ç†è®ºã€‚ + +è¿™æ˜¯é€šè¿‡ä½¿ç”¨å¸¦æœ‰èŠ‚æ ‡é¢˜çš„ ``DOC:`` 节关键å—æ¥å®žçŽ°çš„。 + +æ€»è¿°æˆ–é«˜å±‚çº§æ–‡æ¡£æ³¨é‡Šçš„ä¸€èˆ¬æ ¼å¼ä¸º:: + + /** + * DOC: Theory of Operation + * + * The whizbang foobar is a dilly of a gizmo. It can do whatever you + * want it to do, at any time. It reads your mind. Here's how it works. + * + * foo bar splat + * + * The only drawback to this gizmo is that is can sometimes damage + * hardware, software, or its subject(s). + */ + +``DOC:`` åŽé¢çš„æ ‡é¢˜ç”¨ä½œæºæ–‡ä»¶ä¸çš„æ ‡é¢˜ï¼Œä½†ä¹Ÿç”¨ä½œæå–æ–‡æ¡£æ³¨é‡Šçš„æ ‡è¯†ç¬¦ã€‚å› æ¤ï¼Œ +文件ä¸çš„æ ‡é¢˜å¿…é¡»æ˜¯å”¯ä¸€çš„ã€‚ + +包å«kernel-doc注释 +================== + +文档注释å¯ä»¥è¢«åŒ…å«åœ¨ä»»ä½•ä½¿ç”¨ä¸“用kernel-doc Sphinx指令扩展的reStructuredText +文档ä¸ã€‚ + +kernel-docæŒ‡ä»¤çš„æ ¼å¼å¦‚下:: + + .. kernel-doc:: source + :option: + +*source* æ˜¯ç›¸å¯¹äºŽå†…æ ¸æºä»£ç æ ‘çš„æºæ–‡ä»¶è·¯å¾„。 +支æŒä»¥ä¸‹æŒ‡ä»¤é€‰é¡¹ï¼š + +export: *[source-pattern ...]* + 包括 *source* ä¸ä½¿ç”¨ ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的所有 + å‡½æ•°çš„æ–‡æ¡£ï¼Œæ— è®ºæ˜¯åœ¨ *source* ä¸è¿˜æ˜¯åœ¨ *source-pattern* 指定的任何文件ä¸ã€‚ + + 当kernel-doc注释被放置在头文件ä¸ï¼Œè€Œ ``EXPORT_SYMBOL`` å’Œ ``EXPORT_SYMBOL_GPL`` + ä½äºŽå‡½æ•°å®šä¹‰æ—边时， *source-pattern* éžå¸¸æœ‰ç”¨ã€‚ + + 例å:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + 包括 *source* ä¸æ‰€æœ‰åœ¨ *source* 或 *source-pattern* 的任何文件ä¸éƒ½æ²¡æœ‰ä½¿ç”¨ + ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的函数和类型的文档。 + + 例å:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: + +identifiers: *[ function/type ...]* + 在 *source* ä¸åŒ…å«æ¯ä¸ª *function* å’Œ *type* 的文档。如果没有指定 *function* ， + 则 *source* ä¸æ‰€æœ‰å‡½æ•°å’Œç±»åž‹çš„文档都将包å«åœ¨å†…。 + + 例å:: + + .. kernel-doc:: lib/bitmap.c + :identifiers: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :identifiers: + +no-identifiers: *[ function/type ...]* + 排除 *source* ä¸æ‰€æœ‰ *function* å’Œ *type* 的文档。 + + 例å:: + + .. kernel-doc:: lib/bitmap.c + :no-identifiers: bitmap_parselist + +functions: *[ function/type ...]* + 这是“identifiersâ€æŒ‡ä»¤çš„别å，已弃用。 + +doc: *title* + åŒ…å« *source* ä¸ç”± *title* æ ‡é¢˜æ ‡è¯†çš„ ``DOC:`` 文档段è½ã€‚ *title* ä¸å…许 + ç©ºæ ¼ï¼›ä¸è¦åœ¨ *title* ä¸ŠåŠ å¼•å·ã€‚ *title* 仅用作段è½çš„æ ‡è¯†ç¬¦ï¼Œä¸åŒ…å«åœ¨è¾“出ä¸ã€‚ + 请确ä¿åœ¨æ‰€é™„çš„reStructuredText文档ä¸æœ‰é€‚å½“çš„æ ‡é¢˜ã€‚ + + 例å:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port + +如果没有选项，kernel-doc指令将包å«æºæ–‡ä»¶ä¸çš„所有文档注释。 + +kernel-doc扩展包å«åœ¨å†…æ ¸æºä»£ç æ ‘ä¸ï¼Œä½äºŽ ``Documentation/sphinx/kerneldoc.py`` 。 +在内部，它使用 ``scripts/kernel-doc`` 脚本从æºä»£ç ä¸æå–文档注释。 + +.. _kernel_doc_zh: + +如何使用kernel-doc生æˆæ‰‹å†Œï¼ˆman）页 +----------------------------------- + +如果您åªæƒ³ä½¿ç”¨kernel-doc生æˆæ‰‹å†Œé¡µï¼Œå¯ä»¥ä»Žå†…æ ¸gitæ ‘è¿™æ ·åš:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- :^Documentation :^tools) \ + | scripts/split-man.pl /tmp/man + +一些旧版本的gitä¸æ”¯æŒè·¯å¾„排除è¯æ³•çš„æŸäº›å˜ä½“。 +以下命令之一å¯èƒ½é€‚用于这些版本:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ + | scripts/split-man.pl /tmp/man + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ + | scripts/split-man.pl /tmp/man + diff --git a/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst b/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst new file mode 100644 index 000000000000..35c88e5b3d83 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/maintainer-profile.rst + +:译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +文档å系统维护人员æ¡ç›®æ¦‚è¿° +========================== + +文档“å系统â€æ˜¯å†…æ ¸æ–‡æ¡£å’Œç›¸å…³åŸºç¡€è®¾æ–½çš„ä¸å¿ƒå调点。它涵盖了 Documentation/ 下 +的文件层级（Documentation/devicetree 除外）ã€scripts/ 下的å„ç§å®žç”¨ç¨‹åºï¼Œå¹¶ä¸” +在æŸäº›æƒ…况下的也包括 LICENSES/ 。 + +ä¸è¿‡å€¼å¾—注æ„的是，这个åç³»ç»Ÿçš„è¾¹ç•Œæ¯”é€šå¸¸æ›´åŠ æ¨¡ç³Šã€‚è®¸å¤šå…¶ä»–åç³»ç»Ÿç»´æŠ¤äººå‘˜éœ€è¦ +ä¿æŒå¯¹ Documentation/ æŸäº›éƒ¨åˆ†çš„控制，以便于å¯ä»¥æ›´è‡ªç”±åœ°åšæ›´æ”¹ã€‚除æ¤ä¹‹å¤–， +è®¸å¤šå†…æ ¸æ–‡æ¡£éƒ½ä»¥kernel-doc注释的形å¼å‡ºçŽ°åœ¨æºä»£ç ä¸ï¼›è¿™äº›æ³¨é‡Šé€šå¸¸ï¼ˆä½†ä¸æ€»æ˜¯ï¼‰ +由相关的å系统维护人员维护。 + +文档å系统的邮件列表是<linux-doc@vger.kernel.org>。 +è¡¥ä¸åº”å°½é‡é’ˆå¯¹docs-nextæ ‘ã€‚ + +æ交检查å•è¡¥é— +-------------- + +在进行文档更改时，您应当构建文档以测试，并确ä¿æ²¡æœ‰å¼•å…¥æ–°çš„错误或è¦å‘Šã€‚ç”Ÿæˆ +HTML文档并查看结果将有助于é¿å…对文档渲染结果的ä¸å¿…è¦äº‰æ‰§ã€‚ + +å¼€å‘周期的关键节点 +------------------ + +è¡¥ä¸å¯ä»¥éšæ—¶å‘é€ï¼Œä½†åœ¨åˆå¹¶çª—å£æœŸé—´ï¼Œå“åº”å°†æ¯”é€šå¸¸æ…¢ã€‚æ–‡æ¡£æ ‘å¾€å¾€åœ¨åˆå¹¶çª—å£æ‰“å¼€ +之å‰å…³é—å¾—æ¯”è¾ƒæ™šï¼Œå› ä¸ºæ–‡æ¡£è¡¥ä¸å¯¼è‡´å›žå½’的风险很å°ã€‚ + +å®¡é˜…èŠ‚å¥ +-------- + +我（译注：指Jonathan Corbet <corbet@lwn.net>）是文档å系统的唯一维护者，我在 +自己的时间里完æˆè¿™é¡¹å·¥ä½œï¼Œæ‰€ä»¥å¯¹è¡¥ä¸çš„å“应有时会很慢。当补ä¸è¢«åˆå¹¶æ—¶ï¼ˆæˆ–当我 +决定拒ç»åˆå¹¶è¡¥ä¸æ—¶ï¼‰ï¼Œæˆ‘都会å‘é€é€šçŸ¥ã€‚如果您在å‘é€è¡¥ä¸åŽä¸€å‘¨å†…没有收到回å¤ï¼Œ +请ä¸è¦çŠ¹è±«ï¼Œå‘é€æ醒就好。 + diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst new file mode 100644 index 000000000000..a08819e904ed --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst @@ -0,0 +1,187 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/parse-headers.rst + +:译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +===================== +包å«ç”¨æˆ·ç©ºé—´API头文件 +===================== + +有时，为了æ述用户空间API并在代ç 和文档之间生æˆäº¤å‰å¼•ç”¨ï¼Œéœ€è¦åŒ…å«å¤´æ–‡ä»¶å’Œç¤ºä¾‹ +C代ç 。为用户空间APIæ–‡ä»¶æ·»åŠ äº¤å‰å¼•ç”¨è¿˜æœ‰ä¸€ä¸ªå¥½å¤„：如果在文档ä¸æ‰¾ä¸åˆ°ç›¸åº”符å·ï¼Œ +Sphinx将生æˆè¦å‘Šã€‚这有助于ä¿æŒç”¨æˆ·ç©ºé—´APIæ–‡æ¡£ä¸Žå†…æ ¸æ›´æ”¹åŒæ¥ã€‚ +:ref:`parse_headers.pl <parse_headers_zh>` æ供了ç”Ÿæˆæ¤ç±»äº¤å‰å¼•ç”¨çš„一ç§æ–¹æ³•ã€‚ +在构建文档时，必须通过Makefileè°ƒç”¨å®ƒã€‚æœ‰å…³å¦‚ä½•åœ¨å†…æ ¸æ ‘ä¸ä½¿ç”¨å®ƒçš„示例，请å‚阅 +``Documentation/userspace-api/media/Makefile`` 。 + +.. _parse_headers_zh: + +parse_headers.pl +---------------- + +脚本å称 +~~~~~~~~ + + +parse_headers.pl——解æžä¸€ä¸ªC文件，识别函数ã€ç»“构体ã€æžšä¸¾ã€å®šä¹‰å¹¶å¯¹Sphinx文档 +创建交å‰å¼•ç”¨ã€‚ + + +ç”¨æ³•æ¦‚è¦ +~~~~~~~~ + + +\ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>] + +<选项> å¯ä»¥æ˜¯ï¼š --debug, --help 或 --usage 。 + + +选项 +~~~~ + + + +\ **--debug**\ + + å¼€å¯è„šæœ¬è¯¦ç»†æ¨¡å¼ï¼Œåœ¨è°ƒè¯•æ—¶å¾ˆæœ‰ç”¨ã€‚ + + +\ **--usage**\ + + 打å°ç®€çŸçš„帮助信æ¯å¹¶é€€å‡ºã€‚ + + + +\ **--help**\ + + 打å°æ›´è¯¦ç»†çš„帮助信æ¯å¹¶é€€å‡ºã€‚ + + +说明 +~~~~ + +通过C头文件或æºæ–‡ä»¶ï¼ˆ<C文件>）ä¸ä¸ºæè¿°API的文档编写的带交å‰å¼•ç”¨çš„ ..é¢„æ ¼å¼åŒ– +文本 å—将文件转æ¢æˆé‡æž„文本（RST）。它接å—一个å¯é€‰çš„<例外文件>，其ä¸æ述了 +å“ªäº›å…ƒç´ å°†è¢«å¿½ç•¥æˆ–æŒ‡å‘éžé»˜è®¤å¼•ç”¨ã€‚ + +输出被写入到<输出文件>。 + +它能够识别定义ã€å‡½æ•°ã€ç»“构体ã€typedefã€æžšä¸¾å’Œæžšä¸¾ç¬¦å·ï¼Œå¹¶ä¸ºå®ƒä»¬åˆ›å»ºäº¤å‰å¼•ç”¨ã€‚ +它还能够区分用于指定Linux ioctlçš„ ``#define`` 。 + +<例外文件> 包å«ä¸¤ç§ç±»åž‹çš„è¯å¥ï¼š \ **ignore**\ 或 \ **replace**\ . + +ignoreæ ‡è®°çš„è¯æ³•ä¸ºï¼š + + +ignore \ **type**\ \ **name**\ + +The \ **ignore**\ æ„味ç€å®ƒä¸ä¼šä¸ºç±»åž‹ä¸º \ **type**\ çš„ \ **name**\ 符å·ç”Ÿæˆ +交å‰å¼•ç”¨ã€‚ + + +replaceæ ‡è®°çš„è¯æ³•ä¸ºï¼š + + +replace \ **type**\ \ **name**\ \ **new_value**\ + +The \ **replace**\ 味ç€å®ƒå°†ä¸º \ **type**\ 类型的 \ **name**\ 符å·ç”Ÿæˆäº¤å‰å¼• +用，但是它将使用 \ **new_value**\ æ¥å–代默认的替æ¢è§„则。 + + +这两ç§è¯å¥ä¸ï¼Œ \ **type**\ å¯ä»¥æ˜¯ä»¥ä¸‹ä»»ä¸€é¡¹ï¼š + + +\ **ioctl**\ + + ignore 或 replace è¯å¥åº”用于ioctl定义，如： + + #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + + + +\ **define**\ + + ignore 或 replace è¯å¥åº”用于在<C文件>ä¸æ‰¾åˆ°çš„任何其他 ``#define`` 。 + + + +\ **typedef**\ + + ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„typedefè¯å¥ã€‚ + + + +\ **struct**\ + + ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„结构体å称è¯å¥ã€‚ + + + +\ **enum**\ + + ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„枚举å称è¯å¥ã€‚ + + + +\ **symbol**\ + + ignore å’Œ replace è¯å¥åº”用于<C文件>ä¸çš„枚举值å称è¯å¥ã€‚ + + replaceè¯å¥ä¸ï¼Œ \ **new_value**\ 会自动使用 \ **typedef**\ , \ **enum**\ + å’Œ \ **struct**\ 类型的 :c:type: å¼•ç”¨ï¼›ä»¥åŠ \ **ioctl**\ , \ **define**\ å’Œ + \ **symbol**\ 类型的 :ref: 。引用的类型也å¯ä»¥åœ¨replaceè¯å¥ä¸æ˜¾å¼å®šä¹‰ã€‚ + + +示例 +~~~~ + + +ignore define _VIDEODEV2_H + + +忽略<C文件>ä¸çš„ #define _VIDEODEV2_H 。 + +ignore symbol PRIVATE + + +如下结构体： + +enum foo { BAR1, BAR2, PRIVATE }; + +ä¸ä¼šä¸º \ **PRIVATE**\ 生æˆäº¤å‰å¼•ç”¨ã€‚ + +replace symbol BAR1 :c:type:\`foo\` +replace symbol BAR2 :c:type:\`foo\` + + +如下结构体： + +enum foo { BAR1, BAR2, PRIVATE }; + +它会让BAR1å’ŒBAR2枚举符å·äº¤å‰å¼•ç”¨C域ä¸çš„foo符å·ã€‚ + + + +缺陷 +~~~~ + + +请å‘Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。 + +ä¸æ–‡ç¿»è¯‘问题请找ä¸æ–‡ç¿»è¯‘维护者。 + + +ç‰ˆæƒ +~~~~ + + +版æƒæ‰€æœ‰ (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> + +许å¯è¯ GPLv2：GNU GPL version 2 <https://gnu.org/licenses/gpl.html> + +è¿™æ˜¯è‡ªç”±è½¯ä»¶ï¼šä½ å¯ä»¥è‡ªç”±åœ°ä¿®æ”¹å’Œé‡æ–°å‘布它。 +在法律å…许的范围内，**ä¸æ供任何ä¿è¯**。 diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst new file mode 100644 index 000000000000..951595c7d599 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -0,0 +1,415 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/sphinx.rst + +:译者: å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +.. _sphinxdoc_zh: + +简介 +==== + +Linuxå†…æ ¸ä½¿ç”¨ `Sphinx <http://www.sphinx-doc.org/>`_ æ¥æŠŠ ``Documentation`` +下的 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 文件转 +æ¢æˆæ¼‚亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令å³å¯æž„建HTML +或PDFæ ¼å¼çš„文档。生æˆçš„文档放在 ``Documentation/output`` 文件夹ä¸ã€‚ + +reStructuredText文件å¯èƒ½åŒ…å«åŒ…å«æ¥è‡ªæºæ–‡ä»¶çš„结构化文档注释或kernel-doc注释。 +通常它们用于æ述代ç 的功能ã€ç±»åž‹å’Œè®¾è®¡ã€‚kernel-doc注释有一些特殊的结构和 +æ ¼å¼ï¼Œä½†é™¤æ¤ä¹‹å¤–，它们还被作为reStructuredText处ç†ã€‚ + +最åŽï¼Œæœ‰æˆåƒä¸Šä¸‡çš„纯文本文档文件散布在 ``Documentation`` 里。éšç€æ—¶é—´æŽ¨ç§»ï¼Œ +å…¶ä¸ä¸€äº›å¯èƒ½ä¼šè½¬æ¢ä¸ºreStructuredText，但其ä¸å¤§éƒ¨åˆ†ä»ä¿æŒçº¯æ–‡æœ¬ã€‚ + +.. _sphinx_install_zh: + +安装Sphinx +========== + +Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。 + +这有一个脚本å¯ä»¥æ£€æŸ¥Sphinxçš„ä¾èµ–项。更多详细信æ¯è§ +:ref:`sphinx-pre-install_zh` 。 + +大多数å‘行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上å‡çº§å®ƒ +或其他一些Python包导致文档构建ä¸æ–的情况并ä¸å°‘è§ã€‚ + +é¿å…æ¤æƒ…况的一ç§æ–¹æ³•æ˜¯ä½¿ç”¨ä¸Žå‘行版附带的ä¸åŒçš„ç‰ˆæœ¬ã€‚å› æ¤ï¼Œå»ºè®®ä½¿ç”¨ +``virtualenv-3`` 或 ``virtualenv`` 在虚拟环境ä¸å®‰è£…Sphinx，具体å–决于å‘行版 +如何打包Python3。 + +.. note:: + + #) 低于1.5版本的Sphinxæ— æ³•ä¸ŽPythonçš„0.13.1或更高版本docutils一起æ£å¸¸å·¥ä½œã€‚ + 如果您想使用这些版本，那么应该è¿è¡Œ ``pip install 'docutils==0.12'`` 。 + + #) html输出建议使用RTDä¸»é¢˜ã€‚æ ¹æ®Sphinx版本的ä¸åŒï¼Œå®ƒåº”该用 + ``pip install sphinx_rtd_theme`` å•ç‹¬å®‰è£…。 + + #) 一些ReST页é¢åŒ…å«æ•°å¦è¡¨è¾¾å¼ã€‚由于Sphinx的工作方å¼ï¼Œè¿™äº›è¡¨è¾¾å¼æ˜¯ä½¿ç”¨ LaTeX + 编写的。它需è¦å®‰è£…amsfontså’Œamsmathå®åŒ…，以便显示。 + +总之，如您è¦å®‰è£…Sphinx 1.7.9版本，应执行:: + + $ virtualenv sphinx_1.7.9 + $ . sphinx_1.7.9/bin/activate + (sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt + +在è¿è¡Œ ``. sphinx_1.7.9/bin/activate`` 之åŽï¼Œæ示符将å˜åŒ–，以指示您æ£åœ¨ä½¿ç”¨æ–° +环境。如果您打开了一个新的shell，那么在构建文档之å‰ï¼Œæ‚¨éœ€è¦é‡æ–°è¿è¡Œæ¤å‘½ä»¤ä»¥å† +次进入虚拟环境ä¸ã€‚ + +图片输出 +-------- + +å†…æ ¸æ–‡æ¡£æž„å»ºç³»ç»ŸåŒ…å«ä¸€ä¸ªæ‰©å±•ï¼Œå¯ä»¥å¤„ç†GraphVizå’ŒSVGæ ¼å¼çš„图åƒï¼ˆå‚è§ +:ref:`sphinx_kfigure_zh` ）。 + +为了让它工作，您需è¦åŒæ—¶å®‰è£…GraphVizå’ŒImageMagick包。如果没有安装这些软件包， +构建系统ä»å°†æž„建文档，但ä¸ä¼šåœ¨è¾“出ä¸åŒ…å«ä»»ä½•å›¾åƒã€‚ + +PDFå’ŒLaTeX构建 +-------------- + +ç›®å‰åªæœ‰Sphinx 1.4åŠæ›´é«˜ç‰ˆæœ¬æ‰æ”¯æŒè¿™ç§æž„建。 + +对于PDFå’ŒLaTeXè¾“å‡ºï¼Œè¿˜éœ€è¦ ``XeLaTeX`` 3.14159265版本。（译注：æ¤ç‰ˆæœ¬å·çœŸå®ž +å˜åœ¨ï¼‰ + +æ ¹æ®å‘行版的ä¸åŒï¼Œæ‚¨å¯èƒ½è¿˜éœ€è¦å®‰è£…一系列 ``texlive`` 软件包，这些软件包æ供了 +``XeLaTeX`` 工作所需的最å°åŠŸèƒ½é›†ã€‚ + +.. _sphinx-pre-install_zh: + +检查Sphinxä¾èµ–项 +---------------- + +这有一个脚本å¯ä»¥è‡ªåŠ¨æ£€æŸ¥Sphinxä¾èµ–项。如果它认得您的å‘行版，还会æ示您所用å‘è¡Œ +版的安装命令:: + + $ ./scripts/sphinx-pre-install + Checking if the needed tools for Fedora release 26 (Twenty Six) are available + Warning: better to also install "texlive-luatex85". + You should run: + + sudo dnf install -y texlive-luatex85 + /usr/bin/virtualenv sphinx_1.7.9 + . sphinx_1.7.9/bin/activate + pip install -r Documentation/sphinx/requirements.txt + + Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + +默认情况下，它会检查htmlå’ŒPDF的所有ä¾èµ–项，包括图åƒã€æ•°å¦è¡¨è¾¾å¼å’ŒLaTeX构建的 +需求，并å‡è®¾å°†ä½¿ç”¨è™šæ‹ŸPython环境。html构建所需的ä¾èµ–é¡¹è¢«è®¤ä¸ºæ˜¯å¿…éœ€çš„ï¼Œå…¶ä»–ä¾ +赖项则是å¯é€‰çš„。 + +它支æŒä¸¤ä¸ªå¯é€‰å‚数： + +``--no-pdf`` + + ç¦ç”¨PDF检查； + +``--no-virtualenv`` + + 使用Sphinx的系统打包，而ä¸æ˜¯Python虚拟环境。 + +Sphinx构建 +========== + +生æˆæ–‡æ¡£çš„常用方法是è¿è¡Œ ``make htmldocs`` 或 ``make pdfdocs`` 。还有其它å¯ç”¨ +çš„æ ¼å¼ï¼šè¯·å‚阅 ``make help`` 的文档部分。生æˆçš„文档放在 ``Documentation/output`` +ä¸‹ç›¸åº”æ ¼å¼çš„å目录ä¸ã€‚ + +è¦ç”Ÿæˆæ–‡æ¡£ï¼Œæ˜¾ç„¶å¿…须安装Sphinx（ ``sphinx-build`` ）。è¦è®©HTML输出更漂亮，å¯ä»¥ +使用Read the Docs Sphinx主题（ ``sphinx_rtd_theme`` ）。对于PDFè¾“å‡ºï¼Œæ‚¨è¿˜éœ€è¦ +``XeLaTeX`` å’Œæ¥è‡ªImageMagick（https://www.imagemagick.org）的 ``convert(1)`` 。 +所有这些软件在大多å‘行版ä¸éƒ½å¯ç”¨æˆ–已打包。 + +è¦ä¼ 递é¢å¤–的选项给Sphinx，å¯ä»¥ä½¿ç”¨makeå˜é‡ ``SPHINXOPTS`` 。例如，使用 +``make SPHINXOPTS=-v htmldocs`` 获得更详细的输出。 + + +è¦åˆ 除生æˆçš„文档，请è¿è¡Œ ``make cleandocs`` 。 + +编写文档 +======== + +æ·»åŠ æ–°æ–‡æ¡£å¾ˆå®¹æ˜“ï¼Œåªéœ€ï¼š + +1. 在 ``Documentation`` 下æŸå¤„æ·»åŠ ä¸€ä¸ªæ–°çš„ ``.rst`` 文件。 +2. 从 ``Documentation/index.rst`` ä¸çš„Sphinx `ä¸»ç›®å½•æ ‘`_ 链接到它。 + +.. _ä¸»ç›®å½•æ ‘: http://www.sphinx-doc.org/en/stable/markup/toctree.html + +对于简å•çš„文档（比如您现在æ£åœ¨é˜…读的文档），这通常已ç»è¶³å¤Ÿå¥½äº†ï¼Œä½†æ˜¯å¯¹äºŽè¾ƒå¤§ +的文档，最好创建一个å目录（或者使用现有的å目录）。例如，图形å系统文档ä½äºŽ +``Documentation/gpu`` 下，拆分为多个 ``.rst`` 文件，并具有从主目录链接æ¥çš„å• +独索引 ``index.rst`` ï¼ˆæœ‰è‡ªå·±çš„ç›®å½•æ ‘ ``toctree`` ）。 + +请å‚阅 `Sphinx <http://www.sphinx-doc.org/>`_ å’Œ `reStructuredText +<http://docutils.sourceforge.net/rst.html>`_ 的文档，以了解如何使用它们。 +特别是Sphinx `reStructuredText 基础`_ 这是开始å¦ä¹ 使用reStructuredTextçš„ +好地方。还有一些 `Sphinx ç‰¹æ®Šæ ‡è®°ç»“æž„`_ 。 + +.. _reStructuredText 基础: http://www.sphinx-doc.org/en/stable/rest.html +.. _Sphinx ç‰¹æ®Šæ ‡è®°ç»“æž„: http://www.sphinx-doc.org/en/stable/markup/index.html + +å†…æ ¸æ–‡æ¡£çš„å…·ä½“æŒ‡å— +------------------ + +è¿™æ˜¯ä¸€äº›å†…æ ¸æ–‡æ¡£çš„å…·ä½“æŒ‡å—： + +* 请ä¸è¦è¿‡äºŽç—´è¿·è½¬æ¢æ ¼å¼åˆ°reStructuredText。ä¿æŒç®€å•ã€‚在大多数情况下，文档 + åº”è¯¥æ˜¯çº¯æ–‡æœ¬ï¼Œæ ¼å¼åº”足够一致，以便å¯ä»¥è½¬æ¢ä¸ºå…¶ä»–æ ¼å¼ã€‚ + +* 将现有文档转æ¢ä¸ºreStructuredText时，请尽é‡å‡å°‘æ ¼å¼æ›´æ”¹ã€‚ + +* 在转æ¢æ–‡æ¡£æ—¶ï¼Œè¿˜è¦æ›´æ–°å†…容，而ä¸ä»…ä»…æ˜¯æ ¼å¼ã€‚ + +* 请éµå¾ªæ ‡é¢˜ä¿®é¥°ç¬¦çš„顺åºï¼š + + 1. ``=`` æ–‡æ¡£æ ‡é¢˜ï¼Œè¦æœ‰ä¸Šçº¿:: + + ======== + æ–‡æ¡£æ ‡é¢˜ + ======== + + 2. ``=`` ç« :: + + ç« æ ‡é¢˜ + ====== + + 3. ``-`` 节:: + + èŠ‚æ ‡é¢˜ + ------ + + 4. ``~`` å°èŠ‚:: + + å°èŠ‚æ ‡é¢˜ + ~~~~~~~~ + + 尽管RST没有规定具体的顺åºï¼ˆâ€œæ²¡æœ‰å¼ºåŠ 一个固定数é‡å’Œé¡ºåºçš„èŠ‚æ ‡é¢˜è£…é¥°é£Žæ ¼ï¼Œæœ€ç»ˆ + 按照的顺åºå°†æ˜¯å®žé™…é‡åˆ°çš„顺åºã€‚â€ï¼‰ï¼Œä½†æ˜¯æ‹¥æœ‰ä¸€ä¸ªé€šç”¨çº§åˆ«çš„文档更容易éµå¾ªã€‚ + +* 对于æ’入固定宽度的文本å—（用于代ç æ ·ä¾‹ã€ç”¨ä¾‹ç‰ï¼‰ï¼š ``::`` 用于è¯æ³•é«˜äº®æ„ä¹‰ä¸ + 大的内容，尤其是çŸä»£ç 段； ``.. code-block:: <language>`` 用于需è¦è¯æ³•é«˜äº®çš„ + 较长代ç å—。对于嵌入到文本ä¸çš„简çŸä»£ç 片段，请使用 \`\` 。 + + +C域 +--- + +**Sphinx C域（Domain）** （name c）适用于C API文档。例如，函数原型： + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + +å†…æ ¸æ–‡æ¡£çš„CåŸŸæœ‰ä¸€äº›é™„åŠ ç‰¹æ€§ã€‚ä¾‹å¦‚ï¼Œæ‚¨å¯ä»¥ä½¿ç”¨è¯¸å¦‚ ``open`` 或 ``ioctl`` è¿™æ ·çš„ +通用å称é‡å‘½å函数的引用å称： + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + +函数å称（例如ioctl）ä»ä¿ç•™åœ¨è¾“出ä¸ï¼Œä½†å¼•ç”¨å称从 ``ioctl`` å˜ä¸º +``VIDIOC_LOG_STATUS`` 。æ¤å‡½æ•°çš„索引项也å˜ä¸º ``VIDIOC_LOG_STATUS`` 。 + +请注æ„，ä¸éœ€è¦ä½¿ç”¨ ``c:func:`` 生æˆå‡½æ•°æ–‡æ¡£çš„交å‰å¼•ç”¨ã€‚由于一些Sphinx扩展的 +神奇力é‡ï¼Œå¦‚果给定函数å的索引项å˜åœ¨ï¼Œæ–‡æ¡£æž„建系统会自动将对 ``function()`` +的引用转æ¢ä¸ºäº¤å‰å¼•ç”¨ã€‚å¦‚æžœåœ¨å†…æ ¸æ–‡æ¡£ä¸çœ‹åˆ° ``c:func:`` çš„ç”¨æ³•ï¼Œè¯·åˆ é™¤å®ƒã€‚ + + +列表 +---- + +我们建议使用 *列å¼è¡¨* æ ¼å¼ã€‚ *列å¼è¡¨* æ ¼å¼æ˜¯äºŒçº§åˆ—表。与ASCII艺术相比，它们对 +文本文件的读者æ¥è¯´å¯èƒ½æ²¡æœ‰é‚£ä¹ˆèˆ’适。但其优点是易于创建或修改，而且修改的差异 +（diff）更有æ„ä¹‰ï¼Œå› ä¸ºå·®å¼‚ä»…é™äºŽä¿®æ”¹çš„内容。 + +*平铺表* 也是一个二级列表，类似于 *列å¼è¡¨* ，但具有一些é¢å¤–特性： + +* 列范围：使用 ``cspan`` 修饰，å¯ä»¥é€šè¿‡å…¶ä»–列扩展å•å…ƒæ ¼ + +* 行范围：使用 ``rspan`` 修饰，å¯ä»¥é€šè¿‡å…¶ä»–行扩展å•å…ƒæ ¼ + +* è‡ªåŠ¨å°†è¡¨æ ¼è¡Œæœ€å³è¾¹çš„å•å…ƒæ ¼æ‰©å±•åˆ°è¯¥è¡Œå³ä¾§ç©ºç¼ºçš„å•å…ƒæ ¼ä¸Šã€‚若使用 + ``:fill-cells:`` 选项，æ¤è¡Œä¸ºå¯ä»¥ä»Ž *自动åˆå¹¶* 更改为 *自动æ’å…¥* ，自动 + æ’入（空）å•å…ƒæ ¼ï¼Œè€Œä¸æ˜¯æ‰©å±•åˆå¹¶åˆ°æœ€åŽä¸€ä¸ªå•å…ƒæ ¼ã€‚ + +选项： + +* ``:header-rows:`` [int] æ ‡é¢˜è¡Œè®¡æ•° +* ``:stub-columns:`` [int] æ ‡é¢˜åˆ—è®¡æ•° +* ``:widths:`` [[int] [int] ... ] 列宽 +* ``:fill-cells:`` æ’入缺少的å•å…ƒæ ¼ï¼Œè€Œä¸æ˜¯è‡ªåŠ¨åˆå¹¶ç¼ºå°‘çš„å•å…ƒæ ¼ + +修饰： + +* ``:cspan:`` [int] 扩展列 +* ``:rspan:`` [int] 扩展行 + +下é¢çš„例åæ¼”ç¤ºäº†å¦‚ä½•ä½¿ç”¨è¿™äº›æ ‡è®°ã€‚åˆ†çº§åˆ—è¡¨çš„ç¬¬ä¸€çº§æ˜¯ *è¡¨æ ¼è¡Œ* 。 *è¡¨æ ¼è¡Œ* ä¸ +åªå…è®¸ä¸€ä¸ªæ ‡è®°ï¼Œå³è¯¥ *è¡¨æ ¼è¡Œ* ä¸çš„å•å…ƒæ ¼åˆ—表。 *comments* （ ``..`` ）和 +*targets* 例外（例如引用 ``:ref:`最åŽä¸€è¡Œ <last row_zh>``` / :ref:`最åŽä¸€è¡Œ +<last row_zh>` ）。 + +.. code-block:: rst + + .. flat-table:: è¡¨æ ¼æ ‡é¢˜ + :widths: 2 1 1 3 + + * - 表头 列1 + - 表头 列2 + - 表头 列3 + - 表头 列4 + + * - è¡Œ1 + - å—段1.1 + - å—段1.2（自动扩展） + + * - è¡Œ2 + - å—段2.1 + - :rspan:`1` :cspan:`1` å—段2.2~3.3 + + * .. _`last row_zh`: + + - è¡Œ3 + +渲染效果： + + .. flat-table:: è¡¨æ ¼æ ‡é¢˜ + :widths: 2 1 1 3 + + * - 表头 列1 + - 表头 列2 + - 表头 列3 + - 表头 列4 + + * - è¡Œ1 + - å—段1.1 + - å—段1.2（自动扩展） + + * - è¡Œ2 + - å—段2.1 + - :rspan:`1` :cspan:`1` å—段2.2~3.3 + + * .. _`last row_zh`: + + - è¡Œ3 + +交å‰å¼•ç”¨ +-------- + +从一页文档到å¦ä¸€é¡µæ–‡æ¡£çš„交å‰å¼•ç”¨å¯ä»¥é€šè¿‡ç®€å•åœ°å†™å‡ºæ–‡ä»¶è·¯å¾„æ¥å®Œæˆï¼Œæ— ç‰¹æ®Šæ ¼å¼ +è¦æ±‚。路径å¯ä»¥æ˜¯ç»å¯¹è·¯å¾„或相对路径。ç»å¯¹è·¯å¾„从“Documentation/â€å¼€å§‹ã€‚ä¾‹å¦‚ï¼Œè¦ +交å‰å¼•ç”¨æ¤é¡µï¼Œä»¥ä¸‹å†™æ³•çš†å¯ï¼Œå–å†³äºŽå…·ä½“çš„æ–‡æ¡£ç›®å½•ï¼ˆæ³¨æ„ ``.rst`` 扩展å是å¯é€‰ +的）:: + + å‚è§ Documentation/doc-guide/sphinx.rst 。æ¤æ³•å§‹ç»ˆå¯ç”¨ã€‚ + 请查看 sphinx.rst ，仅在åŒçº§ç›®å½•ä¸æœ‰æ•ˆã€‚ + 请阅读 ../sphinx.rst ，上级目录ä¸çš„文件。 + +如果è¦ä½¿ç”¨ç›¸å¯¹è·¯å¾„，则需è¦ä½¿ç”¨Sphinxçš„ ``doc`` 修饰。例如，从åŒä¸€ç›®å½•å¼•ç”¨æ¤é¡µ +çš„æ“作如下:: + + å‚è§ :doc:`sphinx文档的自定义链接文本 <sphinx>`. + +对于大多数用例，å‰è€…æ˜¯é¦–é€‰ï¼Œå› ä¸ºå®ƒæ›´å¹²å‡€ï¼Œæ›´é€‚åˆé˜…读æºæ–‡ä»¶çš„人。如果您é‡åˆ°ä¸€ +个没有任何特殊作用的 ``:doc:`` 用法，请将其转æ¢ä¸ºæ–‡æ¡£è·¯å¾„。 + +有关交å‰å¼•ç”¨kernel-doc函数或类型的信æ¯ï¼Œè¯·å‚阅 +Documentation/doc-guide/kernel-doc.rst 。 + +.. _sphinx_kfigure_zh: + +图形图片 +======== + +如果è¦æ·»åŠ 图片，应该使用 ``kernel-figure`` å’Œ ``kernel-image`` 指令。例如， +è¦æ’入具有å¯ç¼©æ”¾å›¾åƒæ ¼å¼çš„图形，请使用SVG（:ref:`svg_image_example_zh` ）:: + + .. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: 简易 SVG 图片 + + SVG 图片示例 + +.. _svg_image_example_zh: + +.. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: 简易 SVG 图片 + + SVG 图片示例 + +å†…æ ¸figure（和imageï¼‰æŒ‡ä»¤æ”¯æŒ DOT æ ¼å¼æ–‡ä»¶ï¼Œè¯·å‚阅 + +* DOT：http://graphviz.org/pdf/dotguide.pdf +* Graphviz：http://www.graphviz.org/content/dot-language + +一个简å•çš„例å（:ref:`hello_dot_file_zh` ）:: + + .. kernel-figure:: ../../../doc-guide/hello.dot + :alt: ä½ å¥½ï¼Œä¸–ç•Œ + + DOT 示例 + +.. _hello_dot_file_zh: + +.. kernel-figure:: ../../../doc-guide/hello.dot + :alt: ä½ å¥½ï¼Œä¸–ç•Œ + + DOT 示例 + +åµŒå…¥çš„æ¸²æŸ“æ ‡è®°ï¼ˆæˆ–è¯è¨€ï¼‰ï¼Œå¦‚Graphvizçš„ **DOT** ç”± ``kernel-render`` 指令æä¾›:: + + .. kernel-render:: DOT + :alt: 有å‘图 + :caption: åµŒå…¥å¼ **DOT** (Graphviz) 代ç + + digraph foo { + "五棵æ¾" -> "国贸"; + } + +如何渲染å–决于安装的工具。如果安装了Graphviz，您将看到一个矢é‡å›¾åƒã€‚å¦åˆ™ï¼ŒåŽŸå§‹ +æ ‡è®°å°†ä½œä¸º *æ–‡å—å—* æ’入（:ref:`hello_dot_render_zh` ）。 + +.. _hello_dot_render_zh: + +.. kernel-render:: DOT + :alt: 有å‘图 + :caption: åµŒå…¥å¼ **DOT** (Graphviz) 代ç + + digraph foo { + "五棵æ¾" -> "国贸"; + } + +*render* æŒ‡ä»¤åŒ…å« *figure* 指令ä¸å·²çŸ¥çš„所有选项，以åŠé€‰é¡¹ ``caption`` 。如果 +``caption`` 有值，则æ’入一个 *figure* èŠ‚ç‚¹ï¼Œè‹¥æ— ï¼Œåˆ™æ’入一个 *image* 节点。 +如果您想引用它，还需è¦ä¸€ä¸ª ``caption`` （:ref:`hello_svg_render_zh` ）。 + +åµŒå…¥å¼ **SVG**:: + + .. kernel-render:: SVG + :caption: åµŒå…¥å¼ **SVG** æ ‡è®° + :alt: å³ä¸Šç®å¤´ + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> + ... + </svg> + +.. _hello_svg_render_zh: + +.. kernel-render:: SVG + :caption: åµŒå…¥å¼ **SVG** æ ‡è®° + :alt: å³ä¸Šç®å¤´ + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" + version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> + </svg> + diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index be6f11176200..ee6b20ca9080 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -18,8 +18,18 @@ admin-guide/index process/index + dev-tools/index + doc-guide/index + kernel-hacking/index filesystems/index arm64/index + sound/index + cpu-freq/index + mips/index + iio/index + riscv/index + core-api/index + openrisc/index ç›®å½•å’Œè¡¨æ ¼ ---------- diff --git a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst new file mode 100644 index 000000000000..ab974faddecf --- /dev/null +++ b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst @@ -0,0 +1,708 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kernel-hacking/hacking.rst + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +============== +å†…æ ¸éª‡å®¢æŒ‡åŒ— +============== + +:作者: Rusty Russell + +引言 +===== + +欢迎咱优雅的读者们æ¥é˜…读Rustyçš„éžå¸¸ä¸é 谱的Linuxå†…æ ¸éª‡å®¢ï¼ˆHacking）指å—。本文 +æè¿°äº†å†…æ ¸ä»£ç 的常è§ä¾‹ç¨‹å’Œä¸€èˆ¬è¦æ±‚ï¼šå…¶ç›®æ ‡æ˜¯å¼•å¯¼æœ‰ç»éªŒçš„C程åºå‘˜å…¥é—¨Linuxå†…æ ¸ +å¼€å‘。我回é¿äº†å®žçŽ°ç»†èŠ‚：这是代ç è¦åšçš„，也忽略了很多有用的例程。 + +åœ¨ä½ è¯»è¿™ç¯‡æ–‡ç« ä¹‹å‰ï¼Œè¯·ç†è§£æˆ‘从æ¥æ²¡æœ‰æƒ³è¿‡è¦å†™è¿™ç¯‡æ–‡ç« ï¼Œå› ä¸ºæˆ‘çš„èµ„åŽ†å¤ªä½Žäº†ï¼› +ä½†æˆ‘ä¸€ç›´æƒ³è¯»è¿™æ ·çš„æ–‡ç« ï¼Œè‡ªå·±å†™æ˜¯å”¯ä¸€çš„æ–¹æ³•ã€‚æˆ‘å¸Œæœ›å®ƒèƒ½æˆé•¿ä¸ºä¸€ä¸ªæœ€ä½³å®žè·µã€ +通用起点和其他信æ¯çš„汇编。 + +玩家 +======= + +在任何时候，系统ä¸çš„æ¯ä¸ªCPU都å¯ä»¥ï¼š + +- ä¸Žä»»ä½•è¿›ç¨‹æ— å…³ï¼ŒæœåŠ¡äºŽç¡¬ä»¶ä¸æ–ï¼› + +- ä¸Žä»»ä½•è¿›ç¨‹æ— å…³ï¼ŒæœåŠ¡äºŽè½¯ä»¶ä¸æ–（softirq）或å任务（tasklet）； + +- è¿è¡ŒäºŽå†…æ ¸ç©ºé—´ä¸ï¼Œä¸Žè¿›ç¨‹ï¼ˆç”¨æˆ·ä¸Šä¸‹æ–‡ï¼‰ç›¸å…³è”ï¼› + +- 在用户空间ä¸è¿è¡Œè¿›ç¨‹ã€‚ + +它们之间有优先级顺åºã€‚最下é¢çš„两个å¯ä»¥äº’相抢å ，但上é¢ä¸ºä¸¥æ ¼çš„层次结构： +æ¯ä¸ªå±‚级åªèƒ½è¢«ä¸Šæ–¹çš„抢å 。例如，当一个软ä¸æ–在CPU上è¿è¡Œæ—¶ï¼Œæ²¡æœ‰å…¶ä»–软ä¸æ– +会抢å 它，但是硬件ä¸æ–å¯ä»¥æŠ¢å 它。ä¸è¿‡ï¼Œç³»ç»Ÿä¸çš„任何其他CPU都是独立执行的。 + +我们将会看到许多方法，用户上下文å¯ä»¥é˜»æ¢ä¸æ–，从而æˆä¸ºçœŸæ£çš„ä¸å¯æŠ¢å 。 + +用户上下文 +------------ + +用户上下文是指当您从系统调用或其他陷阱进入时：就åƒç”¨æˆ·ç©ºé—´ä¸€æ ·ï¼Œæ‚¨å¯ä»¥è¢«æ›´ +é‡è¦çš„任务和ä¸æ–抢å 。您å¯ä»¥é€šè¿‡è°ƒç”¨ :c:func:`schedule()` 进行ç¡çœ 。 + +.. note:: + + 在模å—åŠ è½½å’Œå¸è½½ä»¥åŠå—设备层上的æ“ä½œæ—¶ï¼Œä½ å§‹ç»ˆå¤„äºŽç”¨æˆ·ä¸Šä¸‹æ–‡ä¸ã€‚ + +在用户上下文ä¸ï¼Œå½“å‰ ``current`` 指针（指示我们当å‰æ£åœ¨æ‰§è¡Œçš„任务）是有效的， +且 :c:func:`in_interrupt()` （ ``include/linux/preempt.h`` ）值为éžï¼ˆfalse）。 + +.. warning:: + + 请注æ„，如果您ç¦ç”¨äº†æŠ¢å 或软ä¸æ–（è§ä¸‹æ–‡ï¼‰ï¼Œ:c:func:`in_interrupt()` 会 + 返回å‡é˜³æ€§ã€‚ + +硬件ä¸æ–（Hard IRQs） +---------------------- + +åƒå®šæ—¶å™¨ã€ç½‘å¡å’Œé”®ç›˜ç‰éƒ½æ˜¯å¯èƒ½åœ¨ä»»æ„时刻产生ä¸æ–çš„çœŸå®žç¡¬ä»¶ã€‚å†…æ ¸è¿è¡Œä¸æ– +处ç†ç¨‹åºï¼Œä¸ºç¡¬ä»¶æä¾›æœåŠ¡ã€‚å†…æ ¸ç¡®ä¿å¤„ç†ç¨‹åºæ°¸è¿œä¸ä¼šé‡å…¥ï¼šå¦‚果相åŒçš„ä¸æ–到达， +å®ƒå°†è¢«æŽ’é˜Ÿï¼ˆæˆ–ä¸¢å¼ƒï¼‰ã€‚å› ä¸ºå®ƒä¼šå…³é—ä¸æ–，所以处ç†ç¨‹åºå¿…须很快：通常它åªæ˜¯ +确认ä¸æ–ï¼Œæ ‡è®°ä¸€ä¸ªâ€œè½¯ä»¶ä¸æ–â€ä»¥æ‰§è¡Œå¹¶é€€å‡ºã€‚ + +您å¯ä»¥é€šè¿‡ :c:func:`in_irq()` 返回真æ¥åˆ¤æ–您处于硬件ä¸æ–状æ€ã€‚ + +.. warning:: + + 请注æ„，如果ä¸æ–被ç¦ç”¨ï¼Œè¿™å°†è¿”回å‡é˜³æ€§ï¼ˆè§ä¸‹æ–‡ï¼‰ã€‚ + +软件ä¸æ–上下文：软ä¸æ–（Softirqs）与å任务（Tasklets） +------------------------------------------------------- + +当系统调用å³å°†è¿”回用户空间或硬件ä¸æ–处ç†ç¨‹åºé€€å‡ºæ—¶ï¼Œä»»ä½•æ ‡è®°ä¸ºæŒ‚起（通常通 +过硬件ä¸æ–）的“软件ä¸æ–â€å°†è¿è¡Œï¼ˆ ``kernel/softirq.c`` ）。 + +æ¤å¤„完æˆäº†è®¸å¤šçœŸæ£çš„ä¸æ–处ç†å·¥ä½œã€‚在å‘SMP过渡的早期，åªæœ‰â€œbottom halvesä¸‹åŠ +部â€ï¼ˆBHsï¼‰æœºåˆ¶ï¼Œæ— æ³•åˆ©ç”¨å¤šä¸ªCPU的优势。在从那些一团糟的就电脑切æ¢è¿‡æ¥åŽä¸ä¹…， +我们放弃了这个é™åˆ¶ï¼Œè½¬è€Œä½¿ç”¨â€œè½¯ä¸æ–â€ã€‚ + +``include/linux/interrupt.h`` 列出了ä¸åŒçš„软ä¸æ–。定时器软ä¸æ–是一个éžå¸¸é‡è¦ +的软ä¸æ–（ ``include/linux/timer.h`` ）：您å¯ä»¥æ³¨å†Œå®ƒä»¥åœ¨ç»™å®šæ—¶é—´åŽä¸ºæ‚¨è°ƒç”¨ +函数。 + +软ä¸æ–通常是一个很难处ç†çš„é—®é¢˜ï¼Œå› ä¸ºåŒä¸€ä¸ªè½¯ä¸æ–å°†åŒæ—¶åœ¨å¤šä¸ªCPU上è¿è¡Œã€‚å› æ¤ï¼Œ +å任务（ ``include/linux/interrupt.h`` ）更常用：它们是动æ€å¯æ³¨å†Œçš„（æ„å‘³ç€ +您å¯ä»¥æ‹¥æœ‰ä»»æ„æ•°é‡ï¼‰ï¼Œå¹¶ä¸”它们还ä¿è¯ä»»ä½•å任务都åªèƒ½åœ¨ä¸€ä¸ªCPU上è¿è¡Œï¼Œä¸åŒçš„ +å任务也å¯ä»¥åŒæ—¶è¿è¡Œã€‚ + +.. warning:: + + “taskletâ€è¿™ä¸ªåå—是误导性的：它们与“任务â€æ— 关，å¯èƒ½æ›´å¤šä¸Žå½“æ—¶ + 阿列克谢·库兹涅ä½å¤«äº«ç”¨çš„糟糕ä¼ç‰¹åŠ 有关。 + +ä½ å¯ä»¥ä½¿ç”¨ :c:func:`in_softirq()` å®ï¼ˆ ``include/linux/preempt.h`` ）æ¥ç¡®è®¤ +是å¦å¤„于软ä¸æ–（或å任务）ä¸ã€‚ + +.. warning:: + + 注æ„，如果æŒæœ‰ :ref:`bottom half lock <local_bh_disable_zh>` é”，这将返回 + å‡é˜³æ€§ã€‚ + +一些基本规则 +================ + +缺少内å˜ä¿æŠ¤ + å¦‚æžœä½ æŸå了内å˜ï¼Œæ— 论是在用户上下文还是ä¸æ–上下文ä¸ï¼Œæ•´ä¸ªæœºå™¨éƒ½ä¼šå´©æºƒã€‚ + ä½ ç¡®å®šä½ ä¸èƒ½åœ¨ç”¨æˆ·ç©ºé—´é‡Œåšä½ 想åšçš„事å—？ + +缺少浮点或MMX + FPU上下文ä¸ä¼šè¢«ä¿å˜ï¼›å³ä½¿åœ¨ç”¨æˆ·ä¸Šä¸‹æ–‡ä¸ï¼ŒFPU状æ€ä¹Ÿå¯èƒ½ä¸Žå½“å‰è¿›ç¨‹ä¸ä¸€è‡´ï¼š + 您会弄乱æŸäº›ç”¨æˆ·è¿›ç¨‹çš„FPU状æ€ã€‚如果真的è¦è¿™æ ·åšï¼Œå°±å¿…须显å¼åœ°ä¿å˜/æ¢å¤ + 完整的FPU状æ€ï¼ˆå¹¶é¿å…上下文切æ¢ï¼‰ã€‚这通常ä¸æ˜¯ä¸ªå¥½ä¸»æ„；请优先用定点算法。 + +ä¸¥æ ¼çš„å †æ ˆé™åˆ¶ + 对于大多数32ä½ä½“ç³»ç»“æž„ï¼Œæ ¹æ®é…置选项的ä¸åŒå†…æ ¸å †æ ˆå¤§çº¦ä¸º3K到6K；对于大 + 多数64ä½æœºå™¨ï¼Œå†…æ ¸å †æ ˆå¤§çº¦ä¸º14K，并且ç»å¸¸ä¸Žä¸æ–å…±äº«ï¼Œå› æ¤ä½ æ— æ³•ä½¿ç”¨å…¨éƒ¨ã€‚ + 应é¿å…æ·±åº¦é€’å½’å’Œæ ˆä¸Šçš„å·¨åž‹æœ¬åœ°æ•°ç»„ï¼ˆç”¨åŠ¨æ€åˆ†é…它们æ¥ä»£æ›¿ï¼‰ã€‚ + +Linuxå†…æ ¸æ˜¯å¯ç§»æ¤çš„ + å°±è¿™æ ·å§ã€‚您的代ç 应该是纯64ä½çš„，并且ä¸ä¾èµ–于å—节åºï¼ˆendian）。您还应该 + å°½é‡å‡å°‘CPU特定的东西，例如内è”汇编（inline assembly）应该被干净地å°è£…å’Œ + 最å°åŒ–以便于移æ¤ã€‚一般æ¥è¯´ï¼Œå®ƒåº”该局é™äºŽå†…æ ¸æ ‘ä¸æœ‰ä½“系结构ä¾èµ–的部分。 + +输入输出控制（ioctls）：é¿å…编写新的系统调用 +============================================== + +系统调用（system call）通常看起æ¥åƒè¿™æ ·:: + + asmlinkage long sys_mycall(int arg) + { + return 0; + } + + +é¦–å…ˆï¼Œåœ¨å¤§å¤šæ•°æƒ…å†µä¸‹ï¼Œæ‚¨æ— éœ€åˆ›å»ºæ–°çš„ç³»ç»Ÿè°ƒç”¨ã€‚åˆ›å»ºä¸€ä¸ªå—符设备并为其实现适当 +的输入输出控制（ioctls）。这比系统调用çµæ´»å¾—多，ä¸å¿…写进æ¯ä¸ªä½“系结构的 +``include/asm/unistd.h`` å’Œ ``arch/kernel/entry.S`` 文件里，而且更容易被Linus +接å—。 + +如果您的程åºæ‰€åšçš„åªæ˜¯è¯»å–或写入一些å‚数，请考虑实现 :c:func:`sysfs()` 接å£ã€‚ + +在输入输出控制ä¸ï¼Œæ‚¨å¤„于进程的用户上下文。出现错误时，返回一个负的错误å‚æ•° +（errno，请å‚阅 ``include/uapi/asm-generic/errno-base.h`` 〠+``include/uapi/asm-generic/errno.h`` å’Œ ``include/linux/errno.h`` ），å¦åˆ™è¿” +回0。 + +在ç¡çœ 之åŽï¼Œæ‚¨åº”该检查是å¦å‡ºçŽ°äº†ä¿¡å·ï¼šUnix/Linux处ç†ä¿¡å·çš„方法是暂时退出系统 +调用，并返回 ``-ERESTARTSYS`` 错误。系统调用入å£ä»£ç 将切æ¢å›žç”¨æˆ·ä¸Šä¸‹æ–‡ï¼Œå¤„ç† +ä¿¡å·å¤„ç†ç¨‹åºï¼Œç„¶åŽç³»ç»Ÿè°ƒç”¨å°†é‡æ–°å¯åŠ¨ï¼ˆé™¤éžç”¨æˆ·ç¦ç”¨äº†è¯¥åŠŸèƒ½ï¼‰ã€‚å› æ¤ï¼Œæ‚¨åº”该准 +备好处ç†é‡æ–°å¯åŠ¨ï¼Œä¾‹å¦‚若您处ç†æŸäº›æ•°æ®ç»“构到一åŠã€‚ + +:: + + if (signal_pending(current)) + return -ERESTARTSYS; + + +å¦‚æžœä½ è¦åšæ›´é•¿æ—¶é—´çš„è®¡ç®—ï¼šä¼˜å…ˆè€ƒè™‘ç”¨æˆ·ç©ºé—´ã€‚å¦‚æžœä½ çœŸçš„æƒ³åœ¨å†…æ ¸ä¸åšè¿™ä»¶äº‹ï¼Œä½ +åº”è¯¥å®šæœŸæ£€æŸ¥ä½ æ˜¯å¦éœ€è¦è®©å‡ºCPU（请记得æ¯ä¸ªCPU都有å作多任务）。 +ä¹ æƒ¯ç”¨æ³•:: + + cond_resched(); /* Will sleep */ + + +接å£è®¾è®¡çš„å°æ³¨é‡Šï¼šUNIXç³»ç»Ÿè°ƒç”¨çš„æ ¼è¨€æ˜¯â€œæ供机制而ä¸æ˜¯ç–ç•¥ +Provide mechanism not policyâ€ã€‚ + +æ»é”的“é…方†+==================== + +您ä¸èƒ½è°ƒç”¨ä»»ä½•å¯èƒ½ç¡çœ 的程åºï¼Œé™¤éžï¼š + +- 您处于用户上下文ä¸ã€‚ + +- ä½ æœªæ‹¥æœ‰ä»»ä½•è‡ªæ—‹é”。 + +- 您已ç»å¯ç”¨ä¸æ–（实际上，Andi Kleen说调度代ç 将为您å¯ç”¨å®ƒä»¬ï¼Œä½†è¿™å¯èƒ½ä¸æ˜¯ + 您想è¦çš„）。 + +注æ„，有些函数å¯èƒ½éšå¼åœ°ç¡çœ ：常è§çš„是用户空间访问函数（\*_user）和没有 +``GFP_ATOMIC`` 的内å˜åˆ†é…函数。 + +您应该始终打开 ``CONFIG_DEBUG_ATOMIC_SLEEP`` 项æ¥ç¼–è¯‘å†…æ ¸ï¼Œå¦‚æžœæ‚¨è¿å这些 +规则，它将è¦å‘Šæ‚¨ã€‚å¦‚æžœä½ **真的** è¿åäº†è§„åˆ™ï¼Œä½ æœ€ç»ˆä¼šé”ä½ä½ 的电脑。 + +çœŸçš„ä¼šè¿™æ ·ã€‚ + + +常用函数/ç¨‹åº +=============== + +:c:func:`printk()` +------------------ + +定义于 ``include/linux/printk.h`` + +:c:func:`printk()` å°†å†…æ ¸æ¶ˆæ¯æ供给控制å°ã€dmesgå’Œsyslog守护进程。它对于调 +试和报告错误很有用，并且å¯ä»¥åœ¨ä¸æ–上下文ä¸ä½¿ç”¨ï¼Œä½†æ˜¯ä½¿ç”¨æ—¶è¦å°å¿ƒï¼šå¦‚果机器 +的控制å°ä¸å……æ–¥ç€printk消æ¯åˆ™ä¼šæ— 法使用。它使用与ANSI C printfåŸºæœ¬å…¼å®¹çš„æ ¼å¼ +å—符串，并通过Cå—符串串è”为其æ供第一个“优先â€å‚æ•°:: + + printk(KERN_INFO "i = %u\n", i); + + +å‚è§ ``include/linux/kern_levels.h`` ；了解其他 ``KERN_`` 值；syslog将这些值 +解释为级别。特殊用法：打å°IP地å€ä½¿ç”¨:: + + __be32 ipaddress; + printk(KERN_INFO "my ip: %pI4\n", &ipaddress); + + +:c:func:`printk()` 内部使用的1K缓冲区，ä¸æ•èŽ·æº¢å‡ºã€‚请确ä¿è¶³å¤Ÿä½¿ç”¨ã€‚ + +.. note:: + + 当您开始在用户程åºä¸å°†printf打æˆprintk时，就知é“自己是真æ£çš„å†…æ ¸ç¨‹åºå‘˜äº† + :) + +.. note:: + + å¦ä¸€ä¸ªæ³¨é‡Šï¼šæœ€åˆçš„unix第å…版æºä»£ç 在其printf函数的顶部有一个注释：“printf + ä¸åº”该用于å½å½å–³å–³â€ã€‚ä½ ä¹Ÿåº”è¯¥éµå¾ªæ¤å»ºè®®ã€‚ + +:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()` +--------------------------------------------------------------------------------------------------- + +定义于 ``include/linux/uaccess.h`` / ``asm/uaccess.h`` + +**[ç¡çœ ]** + +:c:func:`put_user()` å’Œ :c:func:`get_user()` 用于从用户空间ä¸èŽ·å–å’Œå‘用户空 +é—´ä¸ä¼ 出å•ä¸ªå€¼ï¼ˆå¦‚intã€char或long）。指å‘用户空间的指针永远ä¸åº”该直接å–消 +引用：应该使用这些程åºå¤åˆ¶æ•°æ®ã€‚两者都返回 ``-EFAULT`` 或 0。 + +:c:func:`copy_to_user()` å’Œ :c:func:`copy_from_user()` 更通用：它们从/å‘用户 +空间å¤åˆ¶ä»»æ„æ•°é‡çš„æ•°æ®ã€‚ + +.. warning:: + + 与 :c:func:`put_user()` å’Œ :c:func:`get_user()` ä¸åŒï¼Œå®ƒä»¬è¿”回未å¤åˆ¶çš„ + æ•°æ®é‡ï¼ˆå³0ä»ç„¶æ„味ç€æˆåŠŸï¼‰ã€‚ + +ã€æ˜¯çš„ï¼Œè¿™ä¸ªæ„šè ¢çš„æŽ¥å£çœŸå¿ƒè®©æˆ‘尴尬。ç«çˆ†çš„å£æ°´ä»—大概æ¯å¹´éƒ½ä¼šå‘生。 +—— Rusty Russell】 + +这些函数å¯ä»¥éšå¼ç¡çœ 。它ä¸åº”该在用户上下文之外调用（没有æ„义）ã€è°ƒç”¨æ—¶ç¦ç”¨ä¸æ– +或获得自旋é”。 + +:c:func:`kmalloc()`/:c:func:`kfree()` +------------------------------------- + +定义于 ``include/linux/slab.h`` + +**[å¯èƒ½ç¡çœ ：è§ä¸‹]** + +这些函数用于动æ€è¯·æ±‚指针对é½çš„内å˜å—，类似用户空间ä¸çš„mallocå’Œfree，但 +:c:func:`kmalloc()` 需è¦é¢å¤–çš„æ ‡å¿—è¯ã€‚é‡è¦çš„值： + +``GFP_KERNEL`` + å¯ä»¥ç¡çœ 和交æ¢ä»¥é‡Šæ”¾å†…å˜ã€‚åªå…许在用户上下文ä¸ä½¿ç”¨ï¼Œä½†è¿™æ˜¯åˆ†é…内å˜æœ€å¯é + 的方法。 + +``GFP_ATOMIC`` + ä¸ä¼šç¡çœ 。较 ``GFP_KERNEL`` æ›´ä¸å¯é ，但å¯ä»¥ä»Žä¸æ–ä¸Šä¸‹æ–‡è°ƒç”¨ã€‚ä½ **应该** + 有一个很好的内å˜ä¸è¶³é”™è¯¯å¤„ç†ç–略。 + +``GFP_DMA`` + 分é…低于16MBçš„ISA DMAã€‚å¦‚æžœä½ ä¸çŸ¥é“é‚£æ˜¯ä»€ä¹ˆï¼Œé‚£ä½ å°±ä¸éœ€è¦äº†ã€‚éžå¸¸ä¸å¯é 。 + +å¦‚æžœæ‚¨çœ‹åˆ°ä¸€ä¸ªä»Žæ— æ•ˆä¸Šä¸‹æ–‡è¦å‘Šæ¶ˆæ¯è°ƒç”¨çš„ç¡çœ 的函数，那么您å¯èƒ½åœ¨æ²¡æœ‰ +``GFP_ATOMIC`` 的情况下从ä¸æ–上下文调用了一个ç¡çœ 的分é…å‡½æ•°ã€‚ä½ å¿…é¡»ç«‹å³ä¿®å¤ï¼Œ +å¿«ç‚¹ï¼ + +å¦‚æžœä½ è¦åˆ†é…至少 ``PAGE_SIZE`` （ ``asm/page.h`` 或 ``asm/page_types.h`` ） +å—节，请考虑使用 :c:func:`__get_free_pages()` （ ``include/linux/gfp.h`` ）。 +它采用顺åºå‚数（0表示页é¢å¤§å°ï¼Œ1表示åŒé¡µï¼Œ2表示四页……）和与上述相åŒçš„å†…å˜ +ä¼˜å…ˆçº§æ ‡å¿—å—。 + +如果分é…çš„å—节数超过一页，å¯ä»¥ä½¿ç”¨ :c:func:`vmalloc()` ã€‚å®ƒå°†åœ¨å†…æ ¸æ˜ å°„ä¸åˆ† +é…虚拟内å˜ã€‚æ¤å—在物ç†å†…å˜ä¸ä¸æ˜¯è¿žç»çš„，但是MMU（内å˜ç®¡ç†å•å…ƒï¼‰ä½¿å®ƒçœ‹èµ·æ¥åƒ +是为您准备好的连ç»ç©ºé—´ï¼ˆå› æ¤å®ƒåªæ˜¯çœ‹èµ·æ¥å¯¹cpuè¿žç»ï¼Œå¯¹å¤–部设备驱动程åºåˆ™ä¸ç„¶ï¼‰ã€‚ +如果您真的需è¦ä¸ºä¸€äº›å¥‡æ€ªçš„设备æ供大é‡ç‰©ç†ä¸Šè¿žç»çš„内å˜ï¼Œé‚£ä¹ˆæ‚¨å°±ä¼šé‡åˆ°é—®é¢˜ï¼š +Linux对æ¤æ”¯æŒå¾ˆå·®ï¼Œå› 为æ£åœ¨è¿è¡Œçš„å†…æ ¸ä¸çš„内å˜ç¢Žç‰‡åŒ–会使它å˜å¾—很困难。最好的 +方法是在引导过程的早期通过 :c:func:`alloc_bootmem()` 函数分é…。 + +在创建自己的常用对象缓å˜ä¹‹å‰ï¼Œè¯·è€ƒè™‘使用 ``include/linux/slab.h`` ä¸çš„slab +缓å˜ã€‚ + +:c:macro:`current` +------------------ + +定义于 ``include/asm/current.h`` + +æ¤å…¨å±€å˜é‡ï¼ˆå…¶å®žæ˜¯å®ï¼‰åŒ…å«æŒ‡å‘当å‰ä»»åŠ¡ç»“构（task structureï¼‰çš„æŒ‡é’ˆï¼Œå› æ¤ä»…在 +用户上下文ä¸æœ‰æ•ˆã€‚例如，当进程进行系统调用时，这将指å‘调用进程的任务结构。 +在ä¸æ–上下文ä¸ä¸ä¸ºç©ºï¼ˆ**not NULL**）。 + +:c:func:`mdelay()`/:c:func:`udelay()` +------------------------------------- + +定义于 ``include/asm/delay.h`` / ``include/linux/delay.h`` + +:c:func:`udelay()` å’Œ :c:func:`ndelay()` 函数å¯è¢«ç”¨äºŽå°æš‚åœã€‚ä¸è¦å¯¹å®ƒä»¬ä½¿ç”¨ +å¤§çš„å€¼ï¼Œå› ä¸ºè¿™æ ·ä¼šå¯¼è‡´æº¢å‡ºâ€”â€”å¸®åŠ©å‡½æ•° :c:func:`mdelay()` 在这里很有用，或者 +考虑 :c:func:`msleep()`。 + +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` +----------------------------------------------------------------------------------------------- + +定义于 ``include/asm/byteorder.h`` + +:c:func:`cpu_to_be32()` 系列函数（其ä¸â€œ32â€å¯ä»¥æ›¿æ¢ä¸º64或16，“beâ€å¯ä»¥æ›¿æ¢ä¸º +“leâ€ï¼‰æ˜¯åœ¨å†…æ ¸ä¸è¿›è¡Œå—节åºè½¬æ¢çš„常用方法：它们返回转æ¢åŽçš„值。所有的å˜ä½“也 +æä¾›åå‘转æ¢å‡½æ•°ï¼š +:c:func:`be32_to_cpu()` ç‰ã€‚ + +这些函数有两个主è¦çš„å˜ä½“：指针å˜ä½“，例如 :c:func:`cpu_to_be32p()` ï¼Œå®ƒèŽ·å– +指å‘给定类型的指针，并返回转æ¢åŽçš„值。å¦ä¸€ä¸ªå˜ä½“是“in-situâ€ç³»åˆ—，例如 +:c:func:`cpu_to_be32s()` ，它转æ¢æŒ‡é’ˆå¼•ç”¨çš„值，并返回void。 + +:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` +-------------------------------------------------------- + +定义于 ``include/linux/irqflags.h`` + + +这些程åºç¦ç”¨æœ¬åœ°CPU上的硬ä¸æ–，并还原它们。它们是å¯é‡å…¥çš„；在其一个 +``unsigned long flags`` å‚æ•°ä¸ä¿å˜ä»¥å‰çš„状æ€ã€‚如果您知é“ä¸æ–å·²å¯ç”¨ï¼Œé‚£ä¹ˆå¯ +直接使用 :c:func:`local_irq_disable()` å’Œ :c:func:`local_irq_enable()`。 + +.. _local_bh_disable_zh: + +:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` +-------------------------------------------------------- + +定义于 ``include/linux/bottom_half.h`` + + +这些程åºç¦ç”¨æœ¬åœ°CPU上的软ä¸æ–，并还原它们。它们是å¯é‡å…¥çš„；如果之å‰ç¦ç”¨äº† +软ä¸æ–，那么在调用这对函数之åŽä»ç„¶ä¼šç¦ç”¨å®ƒä»¬ã€‚它们阻æ¢è½¯ä¸æ–å’Œåä»»åŠ¡åœ¨å½“å‰ +CPU上è¿è¡Œã€‚ + +:c:func:`smp_processor_id()` +---------------------------- + +定义于 ``include/linux/smp.h`` + +:c:func:`get_cpu()` ç¦ç”¨æŠ¢å ï¼ˆè¿™æ ·æ‚¨å°±ä¸ä¼šçªç„¶ç§»åŠ¨åˆ°å¦ä¸€ä¸ªcpuï¼‰å¹¶è¿”å›žå½“å‰ +处ç†å™¨å·ï¼Œä»‹äºŽ0å’Œ ``NR_CPUS`` 之间。请注æ„，CPUç¼–å·ä¸ä¸€å®šæ˜¯è¿žç»çš„。完æˆåŽï¼Œ +使用 :c:func:`put_cpu()` å†æ¬¡è¿”回。 + +如果您知é“您ä¸èƒ½è¢«å¦ä¸€ä¸ªä»»åŠ¡æŠ¢å （å³æ‚¨å¤„于ä¸æ–上下文ä¸ï¼Œæˆ–å·²ç¦ç”¨æŠ¢å ），您 +å¯ä»¥ä½¿ç”¨ :c:func:`smp_processor_id()`。 + +``__init``/``__exit``/``__initdata`` +------------------------------------ + +定义于 ``include/linux/init.h`` + +引导之åŽï¼Œå†…æ ¸é‡Šæ”¾ä¸€ä¸ªç‰¹æ®Šçš„éƒ¨åˆ†ï¼›ç”¨ ``__init`` æ ‡è®°çš„å‡½æ•°å’Œç”¨ ``__initdata`` +æ ‡è®°çš„æ•°æ®ç»“构在引导完æˆåŽè¢«ä¸¢å¼ƒï¼šåŒæ ·åœ°ï¼Œæ¨¡å—在åˆå§‹åŒ–åŽä¸¢å¼ƒæ¤å†…å˜ã€‚ +``__exit`` 用于声明åªåœ¨é€€å‡ºæ—¶éœ€è¦çš„函数：如果æ¤æ–‡ä»¶æœªç¼–译为模å—，则该函数将 +è¢«åˆ é™¤ã€‚è¯·å‚阅头文件以使用。请注æ„，使用 :c:func:`EXPORT_SYMBOL()` 或 +:c:func:`EXPORT_SYMBOL_GPL()` å°†æ ‡è®°ä¸º ``__init`` 的函数导出到模å—是没有æ„义 +的——这将出问题。 + + +:c:func:`__initcall()`/:c:func:`module_init()` +---------------------------------------------- + +定义于 ``include/linux/init.h`` / ``include/linux/module.h`` + +å†…æ ¸çš„è®¸å¤šéƒ¨åˆ†éƒ½ä½œä¸ºæ¨¡å—ï¼ˆå†…æ ¸çš„å¯åŠ¨æ€åŠ 载部分）良好æœåŠ¡ã€‚使用 +:c:func:`module_init()` å’Œ :c:func:`module_exit()` å®å¯ä»¥ç®€åŒ–代ç ç¼–å†™ï¼Œæ— éœ€ +``#ifdef`` ，å³å¯ä»¥ä½œä¸ºæ¨¡å—è¿è¡Œæˆ–å†…ç½®åœ¨å†…æ ¸ä¸ã€‚ + +:c:func:`module_init()` å®å®šä¹‰åœ¨æ¨¡å—æ’入时（如果文件编译为模å—）或在引导时 +调用哪个函数：如果文件未编译为模å—，:c:func:`module_init()` å®å°†ç‰æ•ˆäºŽ +:c:func:`__initcall()` ，它通过链接器的é”力确ä¿åœ¨å¼•å¯¼æ—¶è°ƒç”¨è¯¥å‡½æ•°ã€‚ + +该函数å¯ä»¥è¿”回一个错误值，以导致模å—åŠ è½½å¤±è´¥ï¼ˆä¸å¹¸çš„是，如果将模å—ç¼–è¯‘åˆ°å†…æ ¸ +ä¸ï¼Œåˆ™æ¤æ“ä½œæ— æ•ˆï¼‰ã€‚æ¤å‡½æ•°åœ¨å¯ç”¨ä¸æ–的用户上下文ä¸è°ƒç”¨ï¼Œå› æ¤å¯ä»¥ç¡çœ 。 + +:c:func:`module_exit()` +----------------------- + + +定义于 ``include/linux/module.h`` + +这个å®å®šä¹‰äº†åœ¨æ¨¡å—åˆ é™¤æ—¶è¦è°ƒç”¨çš„å‡½æ•°ï¼ˆå¦‚æžœæ˜¯ç¼–è¯‘åˆ°å†…æ ¸ä¸çš„æ–‡ä»¶ï¼Œåˆ™æ— ç”¨æ¦ä¹‹åœ°ï¼‰ã€‚ +åªæœ‰åœ¨æ¨¡å—使用计数到零时æ‰ä¼šè°ƒç”¨å®ƒã€‚这个函数也å¯ä»¥ç¡çœ ，但ä¸èƒ½å¤±è´¥ï¼šå½“它返回 +时，所有的东西都必须清ç†å¹²å‡€ã€‚ + +注æ„，这个å®æ˜¯å¯é€‰çš„：如果它ä¸å˜åœ¨ï¼Œæ‚¨çš„模å—å°†ä¸å¯ç§»é™¤ï¼ˆé™¤éž ``rmmod -f`` ）。 + +:c:func:`try_module_get()`/:c:func:`module_put()` +------------------------------------------------- + +定义于 ``include/linux/module.h`` + +这些函数会æ“作模å—使用计数，以防æ¢åˆ 除（如果å¦ä¸€ä¸ªæ¨¡å—使用其导出的符å·ä¹‹ä¸€ï¼Œ +åˆ™æ— æ³•åˆ é™¤æ¨¡å—，å‚è§ä¸‹æ–‡ï¼‰ã€‚在调用模å—代ç 之å‰ï¼Œæ‚¨åº”该在该模å—上调用 +:c:func:`try_module_get()` ：若失败，那么该模å—å°†è¢«åˆ é™¤ï¼Œæ‚¨åº”è¯¥å°†å…¶è§†ä¸ºä¸å˜åœ¨ã€‚ +è‹¥æˆåŠŸï¼Œæ‚¨å°±å¯ä»¥å®‰å…¨åœ°è¿›å…¥æ¨¡å—，并在完æˆåŽè°ƒç”¨æ¨¡å— :c:func:`module_put()` 。 + +大多数å¯æ³¨å†Œç»“构体都有所有者å—段，例如在 +:c:type:`struct file_operations <file_operations>` 结构体ä¸ï¼Œæ¤å—段应设置为 +å® ``THIS_MODULE`` 。 + +ç‰å¾…队列 ``include/linux/wait.h`` +==================================== + +**[ç¡çœ ]** + +ç‰å¾…队列用于ç‰å¾…æŸç¨‹åºåœ¨æ¡ä»¶ä¸ºçœŸæ—¶å”¤é†’å¦ä¸€ç¨‹åºã€‚å¿…é¡»å°å¿ƒä½¿ç”¨ï¼Œä»¥ç¡®ä¿æ²¡æœ‰ç«žäº‰ +æ¡ä»¶ã€‚先声明一个 :c:type:`wait_queue_head_t` ，然åŽå¯¹å¸Œæœ›ç‰å¾…该æ¡ä»¶çš„进程声明 +一个关于它们自己的 :c:type:`wait_queue_entry_t` ，并将其放入队列ä¸ã€‚ + +声明 +----- + +使用 :c:func:`DECLARE_WAIT_QUEUE_HEAD()` å®å£°æ˜Žä¸€ä¸ª ``wait_queue_head_t`` ， +或者在åˆå§‹åŒ–代ç ä¸ä½¿ç”¨ :c:func:`init_waitqueue_head()` 程åºã€‚ + +排队 +----- + +将自己放在ç‰å¾…队列ä¸ç›¸å½“å¤æ‚ï¼Œå› ä¸ºä½ å¿…é¡»åœ¨æ£€æŸ¥æ¡ä»¶ä¹‹å‰å°†è‡ªå·±æ”¾å…¥é˜Ÿåˆ—ä¸ã€‚有一 +个å®å¯ä»¥æ¥æ‰§è¡Œæ¤æ“作： :c:func:`wait_event_interruptible()` +（ ``include/linux/wait.h`` ）第一个å‚数是ç‰å¾…队列头，第二个å‚数是计算的表达 +å¼ï¼›å½“该表达å¼ä¸ºtrueæ—¶å®è¿”回0，或者在接收到信å·æ—¶è¿”回 ``-ERESTARTSYS`` 。 +:c:func:`wait_event()` 版本会忽略信å·ã€‚ + +唤醒排队任务 +------------- + +调用 :c:func:`wake_up()` （ ``include/linux/wait.h`` ），它将唤醒队列ä¸çš„所有 +进程。例外情况：如果有一个进程设置了 ``TASK_EXCLUSIVE`` ï¼Œé˜Ÿåˆ—çš„å…¶ä½™éƒ¨åˆ†å°†ä¸ +会被唤醒。这个基本函数的其他å˜ä½“也å¯ä»¥åœ¨åŒä¸€ä¸ªå¤´æ–‡ä»¶ä¸ä½¿ç”¨ã€‚ + +原åæ“作 +========= + +æŸäº›æ“作在所有平å°ä¸Šéƒ½æœ‰ä¿è¯ã€‚第一类为æ“作 :c:type:`atomic_t` +（ ``include/asm/atomic.h`` ）的函数；它包å«ä¸€ä¸ªæœ‰ç¬¦å·æ•´æ•°ï¼ˆè‡³å°‘32ä½é•¿ï¼‰ï¼Œ +您必须使用这些函数æ¥æ“ä½œæˆ–è¯»å– :c:type:`atomic_t` å˜é‡ã€‚ +:c:func:`atomic_read()` å’Œ :c:func:`atomic_set()` 获å–并设置计数器，还有 +:c:func:`atomic_add()` ，:c:func:`atomic_sub()` ，:c:func:`atomic_inc()` ， +:c:func:`atomic_dec()` å’Œ :c:func:`atomic_dec_and_test()` （如果递å‡ä¸ºé›¶ï¼Œ +则返回true）。 + +是的。它在原åå˜é‡ä¸ºé›¶æ—¶è¿”回true（å³!=0）。 + +请注æ„，这些函数比普通的算术è¿ç®—é€Ÿåº¦æ…¢ï¼Œå› æ¤ä¸åº”过度使用。 + +第二类原åæ“作是在 ``unsigned long`` （ ``include/linux/bitops.h`` ）上的 +原åä½æ“作。这些æ“作通常采用指å‘ä½æ¨¡å¼ï¼ˆbit pattern）的指针，第0ä½æ˜¯æœ€ä½Žæœ‰æ•ˆ +ä½ã€‚:c:func:`set_bit()`，:c:func:`clear_bit()` å’Œ :c:func:`change_bit()` 设置〠+清除和更改给定ä½ã€‚:c:func:`test_and_set_bit()` ，:c:func:`test_and_clear_bit()` +å’Œ :c:func:`test_and_change_bit()` 执行相åŒçš„æ“作，但如果之å‰è®¾ç½®äº†ä½ï¼Œåˆ™è¿”回 +true；这些对于原åè®¾ç½®æ ‡å¿—ç‰¹åˆ«æœ‰ç”¨ã€‚ + +å¯ä»¥ä½¿ç”¨å¤§äºŽ ``BITS_PER_LONG`` ä½çš„ä½ç´¢å¼•è°ƒç”¨è¿™äº›æ“作。但结果在大端åºå¹³å°ä¸Š +ä¸å¤ªæ£å¸¸ï¼Œæ‰€ä»¥æœ€å¥½ä¸è¦è¿™æ ·åšã€‚ + +ç¬¦å· +===== + +åœ¨å†…æ ¸å†…éƒ¨ï¼Œæ£å¸¸çš„链接规则ä»ç„¶é€‚用（å³é™¤éžç”¨static关键å—将符å·å£°æ˜Žä¸ºæ–‡ä»¶èŒƒå›´ï¼Œ +å¦åˆ™å®ƒå¯ä»¥åœ¨å†…æ ¸ä¸çš„任何ä½ç½®ä½¿ç”¨ï¼‰ã€‚但是对于模å—，会ä¿ç•™ä¸€ä¸ªç‰¹æ®Šå¯å¯¼å‡ºç¬¦å·è¡¨ï¼Œ +该表将入å£ç‚¹é™åˆ¶ä¸ºå†…æ ¸å†…éƒ¨ã€‚æ¨¡å—也å¯ä»¥å¯¼å‡ºç¬¦å·ã€‚ + +:c:func:`EXPORT_SYMBOL()` +------------------------- + +定义于 ``include/linux/export.h`` + +这是导出符å·çš„ç»å…¸æ–¹æ³•ï¼šåŠ¨æ€åŠ 载的模å—将能够æ£å¸¸ä½¿ç”¨ç¬¦å·ã€‚ + +:c:func:`EXPORT_SYMBOL_GPL()` +----------------------------- + +定义于 ``include/linux/export.h`` + + +类似于 :c:func:`EXPORT_SYMBOL()`，åªæ˜¯ :c:func:`EXPORT_SYMBOL_GPL()` 导出的 +符å·åªèƒ½ç”±å…·æœ‰ç”± :c:func:`MODULE_LICENSE()` 指定GPL兼容许å¯è¯çš„模å—看到。这 +æ„味ç€æ¤å‡½æ•°è¢«è®¤ä¸ºæ˜¯ä¸€ä¸ªå†…部实现问题，而ä¸æ˜¯ä¸€ä¸ªçœŸæ£çš„接å£ã€‚一些维护人员和 +å¼€å‘äººå‘˜åœ¨æ·»åŠ ä¸€äº›æ–°çš„API或功能时å¯èƒ½å´éœ€è¦å¯¼å‡º EXPORT_SYMBOL_GPL()。 + +:c:func:`EXPORT_SYMBOL_NS()` +---------------------------- + +定义于 ``include/linux/export.h`` + +这是 ``EXPORT_SYMBOL()`` çš„å˜ä½“，å…许指定符å·å‘½å空间。符å·å称空间记录于 +Documentation/core-api/symbol-namespaces.rst 。 + +:c:func:`EXPORT_SYMBOL_NS_GPL()` +-------------------------------- + +定义于 ``include/linux/export.h`` + +这是 ``EXPORT_SYMBOL_GPL()`` çš„å˜ä½“，å…许指定符å·å‘½å空间。符å·å称空间记录于 +Documentation/core-api/symbol-namespaces.rst 。 + +程åºä¸Žæƒ¯ä¾‹ +=========== + +åŒå‘链表 ``include/linux/list.h`` +----------------------------------- + +å†…æ ¸å¤´æ–‡ä»¶ä¸æ›¾ç»æœ‰ä¸‰ç»„链表程åºï¼Œä½†è¿™ä¸€ç»„æ˜¯èµ¢å®¶ã€‚å¦‚æžœä½ å¯¹ä¸€ä¸ªå•é“¾è¡¨æ²¡æœ‰ç‰¹åˆ«è¿«åˆ‡çš„ +需求，那么这是一个ä¸é”™çš„选择。 + +通常 :c:func:`list_for_each_entry()` 很有用。 + +返回值惯例 +------------ + +对于在用户上下文ä¸è°ƒç”¨çš„代ç ，è¿èƒŒCè¯è¨€æƒ¯ä¾‹æ˜¯å¾ˆå¸¸è§çš„，å³è¿”回0表示æˆåŠŸï¼Œè¿”回 +负错误值（例如 ``-EFAULT`` ）表示失败。这在一开始å¯èƒ½æ˜¯ä¸ç›´è§‚çš„ï¼Œä½†åœ¨å†…æ ¸ä¸ +相当普é。 + +使用 :c:func:`ERR_PTR()` （ ``include/linux/err.h`` ）将负错误值编ç 到指针ä¸ï¼Œ +然åŽä½¿ç”¨ :c:func:`IS_ERR()` å’Œ :c:func:`PTR_ERR()` 将其å†å–出：é¿å…为错误值 +使用å•ç‹¬çš„指针å‚数。挺讨厌的，但的确是个好方å¼ã€‚ + +ç ´å编译 +---------- + +Linus和其他开å‘人员有时会更改开å‘å†…æ ¸ä¸çš„函数或结构体åç§°ï¼›è¿™æ ·åšä¸ä»…是为了 +让æ¯ä¸ªäººéƒ½ä¿æŒè¦æƒ•ï¼Œè¿˜åæ˜ äº†ä¸€ä¸ªé‡å¤§çš„更改（例如，ä¸èƒ½å†åœ¨æ‰“å¼€ä¸æ–的情况下 +调用，或者执行é¢å¤–的检查，或者ä¸æ‰§è¡Œä»¥å‰æ•èŽ·çš„检查）。通常这会附带一个linux +å†…æ ¸é‚®ä»¶åˆ—è¡¨ä¸ç›¸å½“å…¨é¢çš„注释；请æœç´¢å˜æ¡£ä»¥æŸ¥çœ‹ã€‚简å•åœ°å¯¹æ–‡ä»¶è¿›è¡Œå…¨å±€æ›¿æ¢é€šå¸¸ +会让事情å˜å¾— **更糟** 。 + +åˆå§‹åŒ–结构体æˆå‘˜ +------------------ + +åˆå§‹åŒ–结构体的首选方法是使用指定的åˆå§‹åŒ–器，如ISO C99所述。 +例如:: + + static struct block_device_operations opt_fops = { + .open = opt_open, + .release = opt_release, + .ioctl = opt_ioctl, + .check_media_change = opt_media_change, + }; + + +这使得很容易查找（grep），并且å¯ä»¥æ¸…楚地看到设置了哪些结构å—æ®µã€‚ä½ åº”è¯¥è¿™æ ·åšï¼Œ +å› ä¸ºå®ƒçœ‹èµ·æ¥å¾ˆé…·ã€‚ + +GNU 扩展 +---------- + +Linuxå†…æ ¸ä¸æ˜Žç¡®å…许GNU扩展。请注æ„，由于缺ä¹é€šç”¨æ€§ï¼Œä¸€äº›æ›´å¤æ‚的版本并没有 +得到很好的支æŒï¼Œä½†ä»¥ä¸‹å†…å®¹è¢«è®¤ä¸ºæ˜¯æ ‡å‡†çš„ï¼ˆæœ‰å…³æ›´å¤šè¯¦ç»†ä¿¡æ¯ï¼Œè¯·å‚阅GCC info页 +的“C 扩展â€éƒ¨åˆ†â€”—是的，实际上是info页，手册页åªæ˜¯infoä¸å†…容的简çŸæ‘˜è¦ï¼‰ã€‚ + +- 内è”函数 + +- è¯å¥è¡¨è¾¾å¼ï¼ˆStatement expressions）（å³ï¼ˆ{ å’Œ }）结构）。 + + +- 声明函数/å˜é‡/类型的属性（__attribute__） + +- typeof + +- 零长度数组 + +- å®å˜é‡ + +- 空指针è¿ç®— + +- éžå¸¸é‡ï¼ˆNon-Constant）åˆå§‹åŒ–ç¨‹åº + +- 汇编程åºæŒ‡ä»¤ï¼ˆåœ¨ arch/ å’Œ include/asm/ 之内） + +- å—符串函数å（__func__）。 + +- __builtin_constant_p() + +åœ¨å†…æ ¸ä¸ä½¿ç”¨long longæ—¶è¦å°å¿ƒï¼Œgcc为其生æˆçš„代ç éžå¸¸ç³Ÿç³•ï¼šé™¤æ³•å’Œä¹˜æ³•åœ¨i386上 +ä¸èƒ½å·¥ä½œï¼Œå› ä¸ºå†…æ ¸çŽ¯å¢ƒä¸ç¼ºå°‘用于它的gccè¿è¡Œæ—¶å‡½æ•°ã€‚ + +C++ +--- + +åœ¨å†…æ ¸ä¸ä½¿ç”¨C++通常是个å主æ„ï¼Œå› ä¸ºå†…æ ¸ä¸æ供必è¦çš„è¿è¡Œæ—¶çŽ¯å¢ƒï¼Œå¹¶ä¸”ä¸ä¸ºå…¶ +测试包å«æ–‡ä»¶ã€‚ä¸è¿‡è¿™ä»ç„¶æ˜¯å¯èƒ½çš„，但ä¸å»ºè®®ã€‚å¦‚æžœä½ çœŸçš„æƒ³è¿™ä¹ˆåšï¼Œè‡³å°‘别用 +异常处ç†ï¼ˆexceptions）。 + +#if +--- + +通常认为，在头文件（或.c文件顶部）ä¸ä½¿ç”¨å®æ¥æŠ½è±¡å‡½æ•°æ¯”在æºä»£ç ä¸ä½¿ç”¨â€œifâ€é¢„ +处ç†å™¨è¯å¥æ›´å¹²å‡€ã€‚ + +æŠŠä½ çš„ä¸œè¥¿æ”¾è¿›å†…æ ¸é‡Œ +====================== + +ä¸ºäº†è®©ä½ çš„ä¸œè¥¿æ›´æ£å¼ã€è¡¥ä¸æ›´æ•´æ´ï¼Œè¿˜æœ‰ä¸€äº›å·¥ä½œè¦åšï¼š + +- æžæ¸…æ¥šä½ åœ¨è°çš„地界儿上干活。查看æºæ–‡ä»¶çš„顶部〠``MAINTAINERS`` æ–‡ä»¶ä»¥åŠ + ``CREDITS`` 文件的最åŽä¸€éƒ¨åˆ†ã€‚ä½ åº”è¯¥å’Œæ¤äººå调，确ä¿ä½ 没有é‡æ–°å‘明轮å， + 或者å°è¯•ä¸€äº›å·²ç»è¢«æ‹’ç»çš„东西。 + + ç¡®ä¿ä½ æŠŠä½ çš„åå—和电å邮件地å€æ”¾åœ¨ä½ åˆ›å»ºæˆ–ä¿®æ”¹çš„ä»»ä½•æ–‡ä»¶çš„é¡¶éƒ¨ã€‚å½“äººä»¬å‘ + 现一个缺陷，或者想è¦åšå‡ºä¿®æ”¹æ—¶ï¼Œè¿™æ˜¯ä»–们首先会看的地方。 + +- é€šå¸¸ä½ éœ€è¦ä¸€ä¸ªé…置选项æ¥æ”¯æŒä½ çš„å†…æ ¸ç¼–ç¨‹ã€‚åœ¨é€‚å½“çš„ç›®å½•ä¸ç¼–辑 ``Kconfig`` 。 + é…ç½®è¯è¨€å¾ˆå®¹æ˜“通过剪切和粘贴æ¥ä½¿ç”¨ï¼Œåœ¨ + Documentation/kbuild/kconfig-language.rst ä¸æœ‰å®Œæ•´çš„文档。 + + 在您对选项的æè¿°ä¸ï¼Œè¯·ç¡®ä¿åŒæ—¶ç…§é¡¾åˆ°äº†ä¸“家用户和对æ¤åŠŸèƒ½ä¸€æ— 所知的用户。 + 在æ¤è¯´æ˜Žä»»ä½•ä¸å…¼å®¹å’Œé—®é¢˜ã€‚结尾一定è¦å†™ä¸Šâ€œå¦‚有疑问，就选Nâ€ï¼ˆæˆ–者是“Yâ€ï¼‰ï¼› + 这是针对那些看ä¸æ‡‚ä½ åœ¨è¯´ä»€ä¹ˆçš„äººçš„ã€‚ + +- 编辑 ``Makefile`` ：é…ç½®å˜é‡åœ¨è¿™é‡Œå¯¼å‡ºï¼Œå› æ¤é€šå¸¸ä½ åªéœ€æ·»åŠ 一行 + “obj-$(CONFIG_xxx) += xxx.oâ€ã€‚è¯æ³•è®°å½•åœ¨ + Documentation/kbuild/makefiles.rst 。 + +- å¦‚æžœä½ åšäº†ä¸€äº›æœ‰æ„义的事情，那å¯ä»¥æŠŠè‡ªå·±æ”¾è¿› ``CREDITS`` ，通常ä¸æ¢ä¸€ä¸ª + æ–‡ä»¶ï¼ˆæ— è®ºå¦‚ä½•ä½ çš„åå—都应该在æºæ–‡ä»¶çš„顶部）。维护人员æ„味ç€æ‚¨å¸Œæœ›åœ¨å¯¹ + å系统进行更改时得到询问，并了解缺陷；这æ„味ç€å¯¹æŸéƒ¨åˆ†ä»£ç åšå‡ºæ›´å¤šæ‰¿è¯ºã€‚ + +- 最åŽï¼Œåˆ«å¿˜è®°åŽ»é˜…读 Documentation/process/submitting-patches.rst ， + 也许还有 Documentation/process/submitting-drivers.rst 。 + +Kernel 仙女棒 +=============== + +æµè§ˆæºä»£ç 时的一些收è—。请éšæ„æ·»åŠ åˆ°æ¤åˆ—表。 + +``arch/x86/include/asm/delay.h``:: + + #define ndelay(n) (__builtin_constant_p(n) ? \ + ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ + __ndelay(n)) + + +``include/linux/fs.h``:: + + /* + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a dentry + * pointer with the same return value. + * + * This should be a per-architecture thing, to allow different + * error and pointer decisions. + */ + #define ERR_PTR(err) ((void *)((long)(err))) + #define PTR_ERR(ptr) ((long)(ptr)) + #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) + +``arch/x86/include/asm/uaccess_32.h:``:: + + #define copy_to_user(to,from,n) \ + (__builtin_constant_p(n) ? \ + __constant_copy_to_user((to),(from),(n)) : \ + __generic_copy_to_user((to),(from),(n))) + + +``arch/sparc/kernel/head.S:``:: + + /* + * Sun people can't spell worth damn. "compatibility" indeed. + * At least we *know* we can't spell, and use a spell-checker. + */ + + /* Uh, actually Linus it is I who cannot spell. Too much murky + * Sparc assembly will do this to ya. + */ + C_LABEL(cputypvar): + .asciz "compatibility" + + /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ + .align 4 + C_LABEL(cputypvar_sun4m): + .asciz "compatible" + + +``arch/sparc/lib/checksum.S:``:: + + /* Sun, you just can't beat me, you just can't. Stop trying, + * give up. I'm serious, I am going to kick the living shit + * out of you, game over, lights out. + */ + + +致谢 +===== + +æ„Ÿè°¢Andi Kleenæ出点å，回ç”æˆ‘çš„é—®é¢˜ï¼Œçº æ£æˆ‘的错误，充实内容ç‰å¸®åŠ©ã€‚ +æ„Ÿè°¢Philipp Rumpfåšäº†è®¸å¤šæ‹¼å†™å’Œæ¸…晰度修å¤ï¼Œä»¥åŠä¸€äº›ä¼˜ç§€çš„ä¸æ˜Žæ˜¾çš„点。 +æ„Ÿè°¢Werner Almesberger对 :c:func:`disable_irq()` åšäº†ä¸€ä¸ªå¾ˆå¥½çš„总结， +Jes Sorensenå’ŒAndrea Arcangeli补充了一些注æ„事项。 +æ„Ÿè°¢Michael Elizabeth Chastain检查并补充了é…置部分。 +æ„Ÿè°¢Telsa Gwynne教我DocBook。 diff --git a/Documentation/translations/zh_CN/kernel-hacking/index.rst b/Documentation/translations/zh_CN/kernel-hacking/index.rst new file mode 100644 index 000000000000..df530de2278d --- /dev/null +++ b/Documentation/translations/zh_CN/kernel-hacking/index.rst @@ -0,0 +1,22 @@ +.. _kernel_hacking_zh: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kernel-hacking/index.rst + +:译者: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +============= +å†…æ ¸éª‡å®¢æŒ‡å— +============= + +.. toctree:: + :maxdepth: 2 + + hacking + +TODO + +- locking diff --git a/Documentation/translations/zh_CN/openrisc/index.rst b/Documentation/translations/zh_CN/openrisc/index.rst new file mode 100644 index 000000000000..d722642796c8 --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/index.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_index: + + +================= +OpenRISC 体系架构 +================= + +.. toctree:: + :maxdepth: 2 + + openrisc_port + todo + +Todolist: + features + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/openrisc/openrisc_port.rst b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst new file mode 100644 index 000000000000..e87d0eec281d --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst @@ -0,0 +1,124 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/openrisc_port` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_port: + +============== +OpenRISC Linux +============== + +这是Linux对OpenRISC类微处ç†å™¨çš„移æ¤ï¼›å…·ä½“æ¥è¯´ï¼Œæœ€æ—©ç§»æ¤ç›®æ ‡æ˜¯32ä½ +OpenRISC 1000系列（或1k）。 + +关于OpenRISC处ç†å™¨å’Œæ£åœ¨è¿›è¡Œä¸çš„å¼€å‘çš„ä¿¡æ¯: + + ======= ============================= + 网站 https://openrisc.io + 邮箱 openrisc@lists.librecores.org + ======= ============================= + +--------------------------------------------------------------------- + +OpenRISC工具链和Linuxçš„æž„å»ºæŒ‡å— +=============================== + +为了构建和è¿è¡ŒLinux for OpenRISCï¼Œä½ è‡³å°‘éœ€è¦ä¸€ä¸ªåŸºæœ¬çš„工具链，或许 +还需è¦æž¶æž„模拟器。 这里概述了准备就ä½è¿™äº›éƒ¨åˆ†çš„æ¥éª¤ã€‚ + +1) 工具链 + +工具链二进制文件å¯ä»¥ä»Žopenrisc.io或我们的githubå‘布页é¢èŽ·å¾—。ä¸åŒ +工具链的构建指å—å¯ä»¥åœ¨openrisc.io或Stafford的工具链构建和å‘布脚本 +ä¸æ‰¾åˆ°ã€‚ + + ====== ================================================= + 二进制 https://github.com/openrisc/or1k-gcc/releases + 工具链 https://openrisc.io/software + 构建 https://github.com/stffrdhrn/or1k-toolchain-build + ====== ================================================= + +2) 构建 + +åƒå¾€å¸¸ä¸€æ ·æž„建Linuxå†…æ ¸:: + + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" defconfig + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" + +3) 在FPGA上è¿è¡Œï¼ˆå¯é€‰) + +OpenRISC社区通常使用FuseSoCæ¥ç®¡ç†æž„建和编程SoC到FPGAä¸ã€‚ 下é¢æ˜¯ç”¨ +OpenRISC SoC对De0 Nanoå¼€å‘æ¿è¿›è¡Œç¼–程的一个例å。 在构建过程ä¸ï¼Œ +FPGA RTL是从FuseSoC IPæ ¸åº“ä¸ä¸‹è½½çš„代ç ，并使用FPGA供应商工具构建。 +二进制文件用openocdåŠ è½½åˆ°ç”µè·¯æ¿ä¸Šã€‚ + +:: + + git clone https://github.com/olofk/fusesoc + cd fusesoc + sudo pip install -e . + + fusesoc init + fusesoc build de0_nano + fusesoc pgm de0_nano + + openocd -f interface/altera-usb-blaster.cfg \ + -f board/or1k_generic.cfg + + telnet localhost 4444 + > init + > halt; load_image vmlinux ; reset + +4) 在模拟器上è¿è¡Œï¼ˆå¯é€‰ï¼‰ + +QEMU是一个处ç†å™¨ä»¿çœŸå™¨ï¼Œæˆ‘们推è它æ¥æ¨¡æ‹ŸOpenRISCå¹³å°ã€‚ 请按照QEMU网 +站上的OpenRISC说明，让Linux在QEMU上è¿è¡Œã€‚ ä½ å¯ä»¥è‡ªå·±æž„建QEMUï¼Œä½†ä½ çš„ +Linuxå‘行版å¯èƒ½æ供了支æŒOpenRISC的二进制包。 + + ============= ====================================================== + qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC + ============= ====================================================== + +--------------------------------------------------------------------- + +术è¯è¡¨ +====== + +代ç ä¸ä½¿ç”¨äº†ä»¥ä¸‹ç¬¦å·çº¦å®šä»¥å°†èŒƒå›´é™åˆ¶åœ¨å‡ 个特定处ç†å™¨å®žçŽ°ä¸Šï¼š + +========= ======================= +openrisc: OpenRISC类型处ç†å™¨ +or1k: OpenRISC 1000系列处ç†å™¨ +or1200: OpenRISC 1200处ç†å™¨ +========= ======================= + +--------------------------------------------------------------------- + +åŽ†å² +==== + +2003-11-18 Matjaz Breskvar (phoenix@bsemi.com) + å°†linuxåˆæ¥ç§»æ¤åˆ°OpenRISC或32架构。 + æ‰€æœ‰çš„æ ¸å¿ƒåŠŸèƒ½éƒ½å®žçŽ°äº†ï¼Œå¹¶ä¸”å¯ä»¥ä½¿ç”¨ã€‚ + +2003-12-08 Matjaz Breskvar (phoenix@bsemi.com) + 彻底改å˜TLB失误处ç†ã€‚ + é‡å†™å¼‚常处ç†ã€‚ + 在默认的initrdä¸å®žçŽ°äº†sash-3.6的所有功能。 + 大幅改进的版本。 + +2004-04-10 Matjaz Breskvar (phoenix@bsemi.com) + 大é‡çš„bugä¿®å¤ã€‚ + 支æŒä»¥å¤ªç½‘，httpå’ŒtelnetæœåŠ¡å™¨åŠŸèƒ½ã€‚ + å¯ä»¥è¿è¡Œè®¸å¤šæ ‡å‡†çš„linux应用程åºã€‚ + +2004-06-26 Matjaz Breskvar (phoenix@bsemi.com) + 移æ¤åˆ°2.6.x。 + +2004-11-30 Matjaz Breskvar (phoenix@bsemi.com) + 大é‡çš„bugä¿®å¤å’Œå¢žå¼ºåŠŸèƒ½ã€‚ + å¢žåŠ äº†opencores framebuffer驱动。 + +2010-10-09 Jonas Bonn (jonas@southpole.se) + é‡å¤§é‡å†™ï¼Œä½¿å…¶ä¸Žä¸Šæ¸¸çš„Linux 2.6.36看é½ã€‚ diff --git a/Documentation/translations/zh_CN/openrisc/todo.rst b/Documentation/translations/zh_CN/openrisc/todo.rst new file mode 100644 index 000000000000..9944ad05473b --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/todo.rst @@ -0,0 +1,20 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/todo` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_todo.rst: + +======== +待办事项 +======== + +OpenRISC Linux的移æ¤å·²ç»å®Œå…¨æŠ•å…¥ä½¿ç”¨ï¼Œå¹¶ä¸”从 2.6.35 开始就一直在上游åŒæ¥ã€‚ +然而，还有一些剩余的项目需è¦åœ¨æœªæ¥å‡ 个月内完æˆã€‚ 下é¢æ˜¯ä¸€ä¸ªå³å°†è¿›è¡Œè°ƒæŸ¥çš„已知 +ä¸å°½å®Œç¾Žçš„项目列表，å³æˆ‘们的待办事项列表。 + +- 实现其余的DMA API……dma_map_sgç‰ã€‚ + +- 完æˆé‡å‘½å清ç†å·¥ä½œâ€¦â€¦ä»£ç ä¸æ到了or32，这是架构的一个è€åå—。 我们 + å·²ç»ç¡®å®šçš„åå—是or1k，这个改å˜æ£åœ¨ä»¥ç¼“慢积累的方å¼è¿›è¡Œã€‚ ç›®å‰ï¼Œor32相当 + 于or1k。 diff --git a/Documentation/translations/zh_CN/process/1.Intro.rst b/Documentation/translations/zh_CN/process/1.Intro.rst index 10a15f3dc282..4f9284cbe33b 100644 --- a/Documentation/translations/zh_CN/process/1.Intro.rst +++ b/Documentation/translations/zh_CN/process/1.Intro.rst @@ -1,162 +1,170 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/1.Intro.rst <development_process_intro>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _cn_development_process_intro: -ä»‹ç» +引言 ==== -æ‰§è¡Œæ‘˜è¦ +内容æè¦ -------- -æœ¬èŠ‚çš„å…¶ä½™éƒ¨åˆ†æ¶µç›–äº†å†…æ ¸å¼€å‘过程的范围，以åŠå¼€å‘人员åŠå…¶é›‡ä¸»åœ¨è¿™æ–¹é¢å¯èƒ½é‡ -到的å„ç§æŒ«æŠ˜ã€‚å†…æ ¸ä»£ç 应该åˆå¹¶åˆ°æ£å¼çš„（“主线â€ï¼‰å†…æ ¸ä¸æœ‰å¾ˆå¤šåŽŸå› ，包括对用 -户的自动å¯ç”¨æ€§ã€å¤šç§å½¢å¼çš„社区支æŒä»¥åŠå½±å“å†…æ ¸å¼€å‘æ–¹å‘的能力。æ供给Linux -å†…æ ¸çš„ä»£ç 必须在与GPL兼容的许å¯è¯ä¸‹å¯ç”¨ã€‚ +æœ¬èŠ‚çš„å…¶ä½™éƒ¨åˆ†æ¶µç›–äº†å†…æ ¸å¼€å‘的过程，以åŠå¼€å‘人员åŠå…¶é›‡ä¸»åœ¨è¿™æ–¹é¢å¯èƒ½é‡åˆ°çš„ +å„ç§é—®é¢˜ã€‚æœ‰å¾ˆå¤šåŽŸå› ä½¿å†…æ ¸ä»£ç 应被åˆå¹¶åˆ°æ£å¼çš„（“主线â€ï¼‰å†…æ ¸ä¸ï¼ŒåŒ…括对用户 +的自动å¯ç”¨æ€§ã€å¤šç§å½¢å¼çš„社区支æŒä»¥åŠå½±å“å†…æ ¸å¼€å‘æ–¹å‘的能力。æ供给Linuxå†…æ ¸ +的代ç 必须在与GPL兼容的许å¯è¯ä¸‹å¯ç”¨ã€‚ :ref:`cn_development_process` 介ç»äº†å¼€å‘过程ã€å†…æ ¸å‘布周期和åˆå¹¶çª—å£çš„机制。 -涵盖了补ä¸å¼€å‘ã€å®¡æŸ¥å’Œåˆå¹¶å‘¨æœŸä¸çš„å„个阶段。有一些关于工具和邮件列表的讨论。 -é¼“åŠ±å¸Œæœ›å¼€å§‹å†…æ ¸å¼€å‘çš„å¼€å‘人员作为åˆå§‹ç»ƒä¹ 跟踪并修å¤bug。 +涵盖了补ä¸å¼€å‘ã€å®¡æŸ¥å’Œåˆå¹¶å‘¨æœŸä¸çš„å„个阶段。还有一些关于工具和邮件列表的讨论？ +é¼“åŠ±å¸Œæœ›å¼€å§‹å†…æ ¸å¼€å‘çš„å¼€å‘人员跟踪并修å¤ç¼ºé™·ä»¥ä½œä¸ºåˆæ¥ç»ƒä¹ 。 -:ref:`cn_development_early_stage` 包括早期项目规划，é‡ç‚¹æ˜¯å°½å¿«è®©å¼€å‘社区å‚与 +:ref:`cn_development_early_stage` 包括项目的早期规划，é‡ç‚¹æ˜¯å°½å¿«è®©å¼€å‘社区 +å‚与进æ¥ã€‚ -:ref:`cn_development_coding` 是关于编ç 过程的；讨论了其他开å‘人员é‡åˆ°çš„å‡ ä¸ª -陷阱。对补ä¸çš„一些è¦æ±‚å·²ç»æ¶µç›–，并且介ç»äº†ä¸€äº›å·¥å…·ï¼Œè¿™äº›å·¥å…·æœ‰åŠ©äºŽç¡®ä¿å†…æ ¸ +:ref:`cn_development_coding` 是关于编程过程的；介ç»äº†å…¶ä»–å¼€å‘人员é‡åˆ°çš„å‡ ä¸ª +陷阱。也涵盖了对补ä¸çš„一些è¦æ±‚，并且介ç»äº†ä¸€äº›å·¥å…·ï¼Œè¿™äº›å·¥å…·æœ‰åŠ©äºŽç¡®ä¿å†…æ ¸ è¡¥ä¸æ˜¯æ£ç¡®çš„。 -:ref:`cn_development_posting` 讨论å‘布补ä¸ä»¥ä¾›è¯„审的过程。为了让开å‘社区 -认真对待，补ä¸å¿…é¡»æ£ç¡®æ ¼å¼åŒ–å’Œæ述，并且必须å‘é€åˆ°æ£ç¡®çš„地方。éµå¾ªæœ¬èŠ‚ä¸çš„ -建议有助于确ä¿ä¸ºæ‚¨çš„工作æ供最好的接纳。 +:ref:`cn_development_posting` æè¿°å‘布补ä¸ä»¥ä¾›è¯„审的过程。为了让开å‘社区能 +认真对待，补ä¸å¿…须被æ£ç¡®æ ¼å¼åŒ–å’Œæ述，并且必须å‘é€åˆ°æ£ç¡®çš„地方。éµå¾ªæœ¬èŠ‚ä¸çš„ +建议有助于确ä¿æ‚¨çš„工作能被较好地接纳。 -:ref:`cn_development_followthrough` 介ç»äº†å‘布补ä¸ä¹‹åŽå‘生的事情；该工作 -在这一点上还远远没有完æˆã€‚与审阅者一起工作是开å‘过程ä¸çš„一个é‡è¦éƒ¨åˆ†ï¼›æœ¬èŠ‚ -æ供了一些关于如何在这个é‡è¦é˜¶æ®µé¿å…问题的æ示。当补ä¸è¢«åˆå¹¶åˆ°ä¸»çº¿ä¸æ—¶ï¼Œ -å¼€å‘人员è¦æ³¨æ„ä¸è¦å‡å®šä»»åŠ¡å·²ç»å®Œæˆã€‚ +:ref:`cn_development_followthrough` 介ç»äº†å‘布补ä¸ä¹‹åŽå‘生的事情；工作在这时 +还远远没有完æˆã€‚与审阅者一起工作是开å‘过程ä¸çš„一个é‡è¦éƒ¨åˆ†ï¼›æœ¬èŠ‚æ供了一些 +关于如何在这个é‡è¦é˜¶æ®µé¿å…问题的æ示。当补ä¸è¢«åˆå¹¶åˆ°ä¸»çº¿ä¸æ—¶ï¼Œå¼€å‘人员è¦æ³¨æ„ +ä¸è¦å‡å®šä»»åŠ¡å·²ç»å®Œæˆã€‚ -:ref:`cn_development_advancedtopics` 介ç»äº†ä¸¤ä¸ªâ€œé«˜çº§â€ä¸»é¢˜ï¼š -使用Git管ç†è¡¥ä¸å’ŒæŸ¥çœ‹å…¶ä»–人å‘布的补ä¸ã€‚ +:ref:`cn_development_advancedtopics` 介ç»äº†ä¸¤ä¸ªâ€œé«˜çº§â€ä¸»é¢˜ï¼šä½¿ç”¨Git管ç†è¡¥ä¸ +和查看其他人å‘布的补ä¸ã€‚ -:ref:`cn_development_conclusion` æ€»ç»“äº†æœ‰å…³å†…æ ¸å¼€å‘的更多信æ¯ï¼Œé™„带有带有 -指å‘资æºçš„链接. +:ref:`cn_development_conclusion` æ€»ç»“äº†æœ‰å…³å†…æ ¸å¼€å‘的更多信æ¯ï¼Œé™„å¸¦æœ‰ç›¸å…³èµ„æº +链接。 -这个文件是关于什么的 +这个文档是关于什么的 -------------------- -Linuxå†…æ ¸æœ‰è¶…è¿‡800万行代ç ，æ¯ä¸ªç‰ˆæœ¬çš„贡献者超过1000人，是现å˜æœ€å¤§ã€æœ€æ´»è·ƒ -çš„å…费软件项目之一。从1991å¹´å¼€å§‹ï¼Œè¿™ä¸ªå†…æ ¸å·²ç»å‘展æˆä¸ºä¸€ä¸ªæœ€å¥½çš„æ“作系统 -组件，è¿è¡Œåœ¨è¢–çæ•°å—音ä¹æ’放器ã€å°å¼PCã€çŽ°å˜æœ€å¤§çš„超级计算机以åŠæ‰€æœ‰ç±»åž‹çš„ -系统上。它是一ç§é€‚ç”¨äºŽå‡ ä¹Žä»»ä½•æƒ…å†µçš„å¥å£®ã€é«˜æ•ˆå’Œå¯æ‰©å±•çš„解决方案。 +Linuxå†…æ ¸æœ‰è¶…è¿‡800万行代ç ，æ¯ä¸ªç‰ˆæœ¬çš„贡献者超过1000人，是现å˜æœ€å¤§ã€æœ€æ´»è·ƒçš„ +å…费软件项目之一。从1991å¹´å¼€å§‹ï¼Œè¿™ä¸ªå†…æ ¸å·²ç»å‘展æˆä¸ºä¸€ä¸ªæœ€å¥½çš„æ“作系统组件， +è¿è¡Œåœ¨è¢–çæ•°å—音ä¹æ’放器ã€å°å¼ç”µè„‘ã€çŽ°å˜æœ€å¤§çš„超级计算机以åŠæ‰€æœ‰ç±»åž‹çš„系统上。 +它是一ç§é€‚ç”¨äºŽå‡ ä¹Žä»»ä½•æƒ…å†µçš„å¥å£®ã€é«˜æ•ˆå’Œå¯æ‰©å±•çš„解决方案。 éšç€Linuxçš„å‘展，希望å‚与其开å‘çš„å¼€å‘人员（和公å¸ï¼‰çš„æ•°é‡ä¹Ÿåœ¨å¢žåŠ 。硬件供应商 希望确ä¿Linux能够很好地支æŒä»–们的产å“，使这些产å“对Linux用户具有å¸å¼•åŠ›ã€‚嵌入 å¼ç³»ç»Ÿä¾›åº”商使用Linux作为集æˆäº§å“的组件，希望Linux能够尽å¯èƒ½åœ°èƒœä»»æ‰‹å¤´çš„任务。 -分销商和其他基于Linux的软件供应商对Linuxå†…æ ¸çš„åŠŸèƒ½ã€æ€§èƒ½å’Œå¯é 性有ç€æ˜Žç¡®çš„ -兴趣。最终用户也常常希望修改Linux，使之更好地满足他们的需求。 +分销商和其他基于Linux的软件供应商切实关心Linuxå†…æ ¸çš„åŠŸèƒ½ã€æ€§èƒ½å’Œå¯é 性。最终 +用户也常常希望修改Linux，使之能更好地满足他们的需求。 Linux最引人注目的特性之一是这些开å‘人员å¯ä»¥è®¿é—®å®ƒï¼›ä»»ä½•å…·å¤‡å¿…è¦æŠ€èƒ½çš„人都å¯ä»¥ 改进Linux并影å“其开å‘æ–¹å‘。专有产å“ä¸èƒ½æ供这ç§å¼€æ”¾æ€§ï¼Œè¿™æ˜¯è‡ªç”±è½¯ä»¶çš„一个特点。 -但是，如果有什么ä¸åŒçš„è¯ï¼Œå†…æ ¸æ¯”å¤§å¤šæ•°å…¶ä»–è‡ªç”±è½¯ä»¶é¡¹ç›®æ›´å¼€æ”¾ã€‚ä¸€ä¸ªå…¸åž‹çš„ä¸‰ä¸ªæœˆ -å†…æ ¸å¼€å‘周期å¯ä»¥æ¶‰åŠ1000多个开å‘人员，他们为100多个ä¸åŒçš„å…¬å¸ -ï¼ˆæˆ–è€…æ ¹æœ¬æ²¡æœ‰å…¬å¸ï¼‰å·¥ä½œã€‚ +如果有什么ä¸åŒçš„è¯ï¼Œé‚£å°±æ˜¯å†…æ ¸æ¯”å¤§å¤šæ•°å…¶ä»–è‡ªç”±è½¯ä»¶é¡¹ç›®æ›´å¼€æ”¾ã€‚ä¸€ä¸ªå…¸åž‹çš„ä¸‰ä¸ª +æœˆå†…æ ¸å¼€å‘周期å¯ä»¥æ¶‰åŠ1000多个开å‘人员，他们为100多个ä¸åŒçš„å…¬å¸ï¼ˆæˆ–è€…æ ¹æœ¬ä¸ +隶属公å¸ï¼‰å·¥ä½œã€‚ -ä¸Žå†…æ ¸å¼€å‘社区åˆä½œå¹¶ä¸æ˜¯ç‰¹åˆ«å›°éš¾ã€‚但是，尽管如æ¤ï¼Œè®¸å¤šæ½œåœ¨çš„贡献者在å°è¯•åš -å†…æ ¸å·¥ä½œæ—¶é‡åˆ°äº†å›°éš¾ã€‚å†…æ ¸ç¤¾åŒºå·²ç»å‘展了自己独特的æ“作方å¼ï¼Œä½¿å…¶èƒ½å¤Ÿåœ¨æ¯å¤© +ä¸Žå†…æ ¸å¼€å‘社区åˆä½œå¹¶ä¸æ˜¯ç‰¹åˆ«å›°éš¾ã€‚但尽管如æ¤ï¼Œä»æœ‰è®¸å¤šæ½œåœ¨çš„贡献者在å°è¯•åš +å†…æ ¸å·¥ä½œæ—¶é‡åˆ°äº†å›°éš¾ã€‚å†…æ ¸ç¤¾åŒºå·²ç»å‘展出自己独特的æ“作方å¼ï¼Œä½¿å…¶èƒ½å¤Ÿåœ¨æ¯å¤© 都è¦æ›´æ”¹æ•°åƒè¡Œä»£ç 的环境ä¸é¡ºåˆ©è¿è¡Œï¼ˆå¹¶ç”Ÿæˆé«˜è´¨é‡çš„产å“ï¼‰ã€‚å› æ¤ï¼ŒLinuxå†…æ ¸å¼€å‘ -过程与专有的开å‘方法有很大的ä¸åŒä¹Ÿå°±ä¸è¶³ä¸ºå¥‡äº†ã€‚ +过程与专有的开å‘模å¼æœ‰å¾ˆå¤§çš„ä¸åŒä¹Ÿå°±ä¸è¶³ä¸ºå¥‡äº†ã€‚ -对于新开å‘人员æ¥è¯´ï¼Œå†…æ ¸çš„å¼€å‘过程å¯èƒ½ä¼šè®©äººæ„Ÿåˆ°å¥‡æ€ªå’Œæ惧，但这个背åŽæœ‰å……分的 -ç†ç”±å’Œåšå®žçš„ç»éªŒã€‚一个ä¸äº†è§£å†…æ ¸ç¤¾åŒºçš„æ–¹å¼çš„å¼€å‘人员（或者更糟的是，他们试图 -抛弃或规é¿å†…æ ¸ç¤¾åŒºçš„æ–¹å¼ï¼‰ä¼šæœ‰ä¸€ä¸ªä»¤äººæ²®ä¸§çš„体验。开å‘社区, 在帮助那些试图å¦ä¹ -的人的åŒæ—¶ï¼Œæ²¡æœ‰æ—¶é—´å¸®åŠ©é‚£äº›ä¸æ„¿æ„倾å¬æˆ–ä¸å…³å¿ƒå¼€å‘过程的人。 +对于新开å‘人员æ¥è¯´ï¼Œå†…æ ¸çš„å¼€å‘过程å¯èƒ½ä¼šè®©äººæ„Ÿåˆ°å¥‡æ€ªå’Œæ惧，但这背åŽæœ‰å……分的 +ç†ç”±å’Œåšå®žçš„ç»éªŒã€‚一个ä¸äº†è§£å†…æ ¸ç¤¾åŒºå·¥ä½œæ–¹å¼çš„å¼€å‘人员（或者更糟的是，他们 +试图抛弃或规é¿ä¹‹ï¼‰ä¼šå¾—到令人沮丧的体验。开å‘社区在帮助那些试图å¦ä¹ 的人的åŒæ—¶ï¼Œ +没有时间帮助那些ä¸æ„¿æ„倾å¬æˆ–ä¸å…³å¿ƒå¼€å‘过程的人。 -希望阅读本文的人能够é¿å…è¿™ç§ä»¤äººæ²®ä¸§çš„ç»åŽ†ã€‚这里有很多æ料，但阅读时所åšçš„ +希望阅读本文的人能够é¿å…è¿™ç§ä»¤äººæ²®ä¸§çš„ç»åŽ†ã€‚这些æ料很长，但阅读它们时所åšçš„ 努力会在çŸæ—¶é—´å†…得到回报。开å‘社区总是需è¦èƒ½è®©å†…æ ¸å˜æ›´å¥½çš„å¼€å‘人员；下é¢çš„ -æ–‡æœ¬åº”è¯¥å¸®åŠ©æ‚¨æˆ–ä¸ºæ‚¨å·¥ä½œçš„äººå‘˜åŠ å…¥æˆ‘ä»¬çš„ç¤¾åŒºã€‚ +æ–‡å—åº”è¯¥å¸®åŠ©æ‚¨æˆ–ä¸ºæ‚¨å·¥ä½œçš„äººå‘˜åŠ å…¥æˆ‘ä»¬çš„ç¤¾åŒºã€‚ 致谢 ---- -本文件由Jonathan Corbet撰写，corbet@lwn.net。以下人员的建议使之更为完善： +本文档由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ß. +Andrew Morton, Andrew Price, Tsugikazu Shibata å’Œ Jochen Voß 。 这项工作得到了Linux基金会的支æŒï¼Œç‰¹åˆ«æ„Ÿè°¢Amanda McPherson，他看到了这项工作 -的价值并把它å˜æˆçŽ°å®žã€‚ +的价值并将其å˜æˆçŽ°å®žã€‚ 代ç 进入主线的é‡è¦æ€§ -------------------- 有些公å¸å’Œå¼€å‘人员å¶å°”会想，为什么他们è¦è´¹å¿ƒå¦ä¹ å¦‚ä½•ä¸Žå†…æ ¸ç¤¾åŒºåˆä½œï¼Œå¹¶å°†ä»£ç æ”¾å…¥ä¸»çº¿å†…æ ¸ï¼ˆâ€œä¸»çº¿â€æ˜¯ç”±Linus Torvaldsç»´æŠ¤çš„å†…æ ¸ï¼ŒLinuxå‘行商将其用作基础）。 -在çŸæœŸå†…，贡献代ç 看起æ¥åƒæ˜¯ä¸€ç§å¯ä»¥é¿å…的开销；仅仅将代ç 分开并直接支æŒç”¨æˆ· +在çŸæœŸå†…，贡献代ç 看起æ¥åƒæ˜¯ä¸€ç§å¯ä»¥é¿å…的开销；维护独立代ç 并直接支æŒç”¨æˆ· 似乎更容易。事实上，ä¿æŒä»£ç ç‹¬ç«‹ï¼ˆâ€œæ ‘å¤–â€ï¼‰æ˜¯åœ¨ç»æµŽä¸Šæ˜¯é”™è¯¯çš„。 -ä½œä¸ºè¯´æ˜Žæ ‘å¤–ä»£ç æˆæœ¬çš„一ç§æ–¹æ³•ï¼Œä¸‹é¢æ˜¯å†…æ ¸å¼€å‘过程的一些相关方é¢ï¼›æœ¬æ–‡ç¨åŽå°† -更详细地讨论其ä¸çš„大部分内容。考虑： +ä¸ºäº†è¯´æ˜Žæ ‘å¤–ä»£ç æˆæœ¬ï¼Œä¸‹é¢ç»™å‡ºå†…æ ¸å¼€å‘过程的一些相关方é¢ï¼›æœ¬æ–‡ç¨åŽå°†æ›´è¯¦ç»†åœ° +讨论其ä¸çš„大部分内容。请考虑： - 所有Linux用户都å¯ä»¥ä½¿ç”¨åˆå¹¶åˆ°ä¸»çº¿å†…æ ¸ä¸çš„代ç 。它将自动出现在所有å¯ç”¨å®ƒçš„ - å‘行版上。ä¸éœ€è¦é©±åŠ¨ç¨‹åºç£ç›˜ã€ä¸‹è½½ï¼Œä¹Ÿä¸éœ€è¦ä¸ºå¤šä¸ªå‘行版的多个版本æ供支æŒï¼› - 对于开å‘人员和用户æ¥è¯´ï¼Œè¿™ä¸€åˆ‡éƒ½æ˜¯å¯è¡Œçš„。并入主线解决了大é‡çš„分布和支æŒé—®é¢˜ + å‘è¡Œç‰ˆä¸Šã€‚æ— éœ€é©±åŠ¨ç¨‹åºç£ç›˜ã€é¢å¤–下载，也ä¸éœ€è¦ä¸ºå¤šä¸ªå‘行版的多个版本æä¾› + 支æŒï¼›è¿™ä¸€åˆ‡å°†æ–¹ä¾¿æ‰€æœ‰å¼€å‘人员和用户。并入主线解决了大é‡çš„分å‘和支æŒé—®é¢˜ã€‚ -- å½“å†…æ ¸å¼€å‘人员努力维护一个稳定的用户空间接å£æ—¶ï¼Œå†…éƒ¨å†…æ ¸API处于ä¸æ–å˜åŒ–之ä¸. - 缺ä¹ä¸€ä¸ªç¨³å®šçš„内部接å£æ˜¯ä¸€ä¸ªæ·±æ€ç†Ÿè™‘的设计决ç–；它å…许在任何时候进行基本的改 - 进，并产生更高质é‡çš„代ç 。但该ç–略的一个结果是，如果è¦ä½¿ç”¨æ–°çš„å†…æ ¸ï¼Œä»»ä½•æ ‘å¤– - 代ç 都需è¦æŒç»çš„ç»´æŠ¤ã€‚ç»´æŠ¤æ ‘å¤–ä»£ç 需è¦å¤§é‡çš„工作æ‰èƒ½ä½¿ä»£ç ä¿æŒå·¥ä½œçŠ¶æ€ã€‚ +- å½“å†…æ ¸å¼€å‘人员努力维护一个稳定的用户空间接å£æ—¶ï¼Œå†…æ ¸å†…éƒ¨API处于ä¸æ–å˜åŒ–之ä¸ã€‚ + ä¸ç»´æŒç¨³å®šçš„内部接å£æ˜¯ä¸€ä¸ªæ…Žé‡çš„设计决ç–；它å…许在任何时候进行基本的改进， + 并产出更高质é‡çš„代ç 。但该ç–略导致结果是，若è¦ä½¿ç”¨æ–°çš„å†…æ ¸ï¼Œä»»ä½•æ ‘å¤–ä»£ç 都 + 需è¦æŒç»çš„ç»´æŠ¤ã€‚ç»´æŠ¤æ ‘å¤–ä»£ç 会需è¦å¤§é‡çš„工作æ‰èƒ½ä½¿ä»£ç ä¿æŒæ£å¸¸è¿è¡Œã€‚ - 相å，ä½äºŽä¸»çº¿ä¸çš„代ç ä¸éœ€è¦è¿™æ ·åšï¼Œå› 为一个简å•çš„规则è¦æ±‚进行API更改的任何 - å¼€å‘人员也必须修å¤ç”±äºŽè¯¥æ›´æ”¹è€Œç ´å的任何代ç ã€‚å› æ¤ï¼Œåˆå¹¶åˆ°ä¸»çº¿ä¸çš„代ç 大大 - é™ä½Žäº†ç»´æŠ¤æˆæœ¬ã€‚ + 相å，ä½äºŽä¸»çº¿ä¸çš„代ç ä¸éœ€è¦è¿™æ ·åšï¼Œå› 为基本规则è¦æ±‚进行APIæ›´æ”¹çš„ä»»ä½•å¼€å‘ + 人员也必须修å¤ç”±äºŽè¯¥æ›´æ”¹è€Œç ´å的任何代ç ã€‚å› æ¤ï¼Œåˆå¹¶åˆ°ä¸»çº¿ä¸çš„代ç 大大é™ä½Ž + 了维护æˆæœ¬ã€‚ -- 除æ¤ä¹‹å¤–ï¼Œå†…æ ¸ä¸çš„代ç 通常会被其他开å‘人员改进。令人惊讶的结果å¯èƒ½æ¥è‡ªæŽˆæƒ - 您的用户社区和客户改进您的产å“。 +- 除æ¤ä¹‹å¤–ï¼Œå†…æ ¸ä¸çš„代ç 通常会被其他开å‘人员改进。您授æƒçš„用户社区和客户对您 + 产å“的改进å¯èƒ½ä¼šä»¤äººæƒŠå–œã€‚ -- å†…æ ¸ä»£ç 在åˆå¹¶åˆ°ä¸»çº¿ä¹‹å‰å’Œä¹‹åŽéƒ½è¦ç»è¿‡å®¡æŸ¥ã€‚ä¸ç®¡åŽŸå§‹å¼€å‘人员的技能有多强， +- å†…æ ¸ä»£ç 在åˆå¹¶åˆ°ä¸»çº¿ä¹‹å‰å’Œä¹‹åŽéƒ½è¦ç»è¿‡å®¡æŸ¥ã€‚æ— è®ºåŽŸå§‹å¼€å‘人员的技能有多强， 这个审查过程总是能找到改进代ç 的方法。审查ç»å¸¸å‘现严é‡çš„错误和安全问题。 - 这对于在å°é—环境ä¸å¼€å‘的代ç 尤其如æ¤ï¼›è¿™ç§ä»£ç 从外部开å‘人员的审查ä¸èŽ·ç›Š - åŒªæµ…ã€‚æ ‘å¤–ä»£ç 是低质é‡ä»£ç 。 + 对于在å°é—环境ä¸å¼€å‘的代ç 尤其如æ¤ï¼›è¿™ç§ä»£ç 从外部开å‘人员的审查ä¸èŽ·ç›ŠåŒªæµ…。 + æ ‘å¤–ä»£ç 是低质é‡ä»£ç 。 - å‚与开å‘过程是您影å“å†…æ ¸å¼€å‘æ–¹å‘çš„æ–¹å¼ã€‚æ—观者的抱怨会被å¬åˆ°ï¼Œä½†æ˜¯æ´»è·ƒçš„ å¼€å‘äººå‘˜æœ‰æ›´å¼ºçš„å£°éŸ³â€”â€”å¹¶ä¸”èƒ½å¤Ÿå®žçŽ°ä½¿å†…æ ¸æ›´å¥½åœ°æ»¡è¶³å…¶éœ€æ±‚çš„æ›´æ”¹ã€‚ - 当å•ç‹¬ç»´æŠ¤ä»£ç 时，总是å˜åœ¨ç¬¬ä¸‰æ–¹ä¸ºç±»ä¼¼åŠŸèƒ½æä¾›ä¸åŒå®žçŽ°çš„å¯èƒ½æ€§ã€‚如果å‘生 - è¿™ç§æƒ…况，åˆå¹¶ä»£ç å°†å˜å¾—æ›´åŠ å›°éš¾â€”â€”ç”šè‡³åˆ°äº†ä¸å¯èƒ½çš„地æ¥ã€‚然åŽï¼Œæ‚¨å°†é¢ä¸´ä»¥ä¸‹ - 令人ä¸å¿«çš„选择：（1ï¼‰æ— é™æœŸåœ°ç»´æŠ¤æ ‘外的éžæ ‡å‡†ç‰¹æ€§ï¼Œæˆ–（2）放弃代ç 并将用户 - è¿ç§»åˆ°æ ‘内版本。 + è¿™ç§æƒ…况，åˆå¹¶ä»£ç å°†å˜å¾—æ›´åŠ å›°éš¾â€”â€”ç”šè‡³æˆä¸ºä¸å¯èƒ½ã€‚之åŽï¼Œæ‚¨å°†é¢ä¸´ä»¥ä¸‹ä»¤äºº + ä¸å¿«çš„选择：（1ï¼‰æ— é™æœŸåœ°ç»´æŠ¤æ ‘外的éžæ ‡å‡†ç‰¹æ€§ï¼Œæˆ–（2）放弃代ç 并将用户è¿ç§» + åˆ°æ ‘å†…ç‰ˆæœ¬ã€‚ -- 代ç çš„è´¡çŒ®æ˜¯ä½¿æ•´ä¸ªè¿‡ç¨‹å·¥ä½œçš„æ ¹æœ¬ã€‚é€šè¿‡è´¡çŒ®ä»£ç ，您å¯ä»¥å‘å†…æ ¸æ·»åŠ æ–°åŠŸèƒ½ï¼Œå¹¶ - æä¾›å…¶ä»–å†…æ ¸å¼€å‘人员使用的功能和示例。如果您已ç»ä¸ºLinuxå¼€å‘了代ç （或者 - æ£åœ¨è€ƒè™‘è¿™æ ·åšï¼‰ï¼Œé‚£ä¹ˆæ‚¨æ˜¾ç„¶å¯¹è¿™ä¸ªå¹³å°çš„æŒç»æˆåŠŸæ„Ÿå…´è¶£ï¼›è´¡çŒ®ä»£ç 是确ä¿æˆåŠŸ - 的最好方法之一。 +- 代ç 的贡献是使整个æµç¨‹å·¥ä½œçš„æ ¹æœ¬ã€‚é€šè¿‡è´¡çŒ®ä»£ç ，您å¯ä»¥å‘å†…æ ¸æ·»åŠ æ–°åŠŸèƒ½ï¼Œå¹¶ + æä¾›å…¶ä»–å†…æ ¸å¼€å‘人员使用的功能和示例。如果您已ç»ä¸ºLinuxå¼€å‘了代ç （或者æ£åœ¨ + è€ƒè™‘è¿™æ ·åšï¼‰ï¼Œé‚£ä¹ˆæ‚¨æ˜¾ç„¶å¯¹è¿™ä¸ªå¹³å°çš„æŒç»æˆåŠŸæ„Ÿå…´è¶£ï¼›è´¡çŒ®ä»£ç 是确ä¿æˆåŠŸçš„ + 最好方法之一。 上述所有ç†ç”±éƒ½é€‚ç”¨äºŽä»»ä½•æ ‘å¤–å†…æ ¸ä»£ç ，包括以专有的ã€ä»…二进制形å¼åˆ†å‘的代ç 。 -ç„¶è€Œï¼Œåœ¨è€ƒè™‘ä»»ä½•ç±»åž‹çš„çº¯äºŒè¿›åˆ¶å†…æ ¸ä»£ç 分布之å‰ï¼Œè¿˜éœ€è¦è€ƒè™‘å…¶ä»–å› ç´ ã€‚è¿™äº›åŒ…æ‹¬ï¼š +ç„¶è€Œï¼Œåœ¨è€ƒè™‘ä»»ä½•ç±»åž‹çš„çº¯äºŒè¿›åˆ¶å†…æ ¸ä»£ç 分布之å‰ï¼Œè¿˜éœ€è¦è€ƒè™‘å…¶ä»–å› ç´ ã€‚åŒ…æ‹¬ï¼š -- å›´ç»•ä¸“æœ‰å†…æ ¸æ¨¡å—分å‘的法律问题充其é‡æ˜¯æ¨¡ç³Šçš„ï¼›ç›¸å½“å¤šçš„å†…æ ¸ç‰ˆæƒæ‰€æœ‰è€…认为， - 大多数仅é™äºŒè¿›åˆ¶çš„模å—æ˜¯å†…æ ¸çš„æ´¾ç”Ÿäº§å“ï¼Œå› æ¤ï¼Œå®ƒä»¬çš„分å‘è¿å了GNU通用公共 - 许å¯è¯ï¼ˆä¸‹é¢å°†è¯¦ç»†ä»‹ç»ï¼‰ã€‚您的作者ä¸æ˜¯å¾‹å¸ˆï¼Œæœ¬æ–‡æ¡£ä¸çš„任何内容都ä¸å¯èƒ½è¢« +- å›´ç»•ä¸“æœ‰å†…æ ¸æ¨¡å—分å‘çš„æ³•å¾‹é—®é¢˜å…¶å®žè¾ƒä¸ºæ¨¡ç³Šï¼›ç›¸å½“å¤šçš„å†…æ ¸ç‰ˆæƒæ‰€æœ‰è€…认为， + 大多数仅二进制的模å—æ˜¯å†…æ ¸çš„æ´¾ç”Ÿäº§å“ï¼Œå› æ¤ï¼Œå®ƒä»¬çš„分å‘è¿å了GNU通用公共 + 许å¯è¯ï¼ˆä¸‹é¢å°†è¯¦ç»†ä»‹ç»ï¼‰ã€‚本文作者ä¸æ˜¯å¾‹å¸ˆï¼Œæœ¬æ–‡æ¡£ä¸çš„任何内容都ä¸å¯èƒ½è¢« 视为法律建议。å°é—æºä»£ç 模å—的真实法律地ä½åªèƒ½ç”±æ³•é™¢å†³å®šã€‚但ä¸ç®¡æ€Žæ ·ï¼Œå›°æ‰° 这些模å—çš„ä¸ç¡®å®šæ€§ä»ç„¶å˜åœ¨ã€‚ - 二进制模å—å¤§å¤§å¢žåŠ äº†è°ƒè¯•å†…æ ¸é—®é¢˜çš„éš¾åº¦ï¼Œä»¥è‡³äºŽå¤§å¤šæ•°å†…æ ¸å¼€å‘人员甚至都ä¸ä¼š å°è¯•ã€‚å› æ¤ï¼Œåªåˆ†å‘二进制模å—将使您的用户更难从社区获得支æŒã€‚ -- 对于åªæ”¯æŒäºŒè¿›åˆ¶çš„模å—çš„å‘行者æ¥è¯´ï¼Œæ”¯æŒä¹Ÿæ›´åŠ å›°éš¾ï¼Œä»–ä»¬å¿…é¡»ä¸ºä»–ä»¬å¸Œæœ›æ”¯æŒ - çš„æ¯ä¸ªå‘行版和æ¯ä¸ªå†…æ ¸ç‰ˆæœ¬æ供一个版本的模å—。为了æ供相当全é¢çš„覆盖范围， +- 对于仅二进制的模å—çš„å‘行者æ¥è¯´ï¼Œæ”¯æŒä¹Ÿæ›´åŠ 困难，他们必须为他们希望支æŒçš„ + æ¯ä¸ªå‘行版和æ¯ä¸ªå†…æ ¸ç‰ˆæœ¬æä¾›ä¸åŒç‰ˆæœ¬çš„模å—。为了æ供较为全é¢çš„覆盖范围， å¯èƒ½éœ€è¦ä¸€ä¸ªæ¨¡å—çš„å‡ å个构建，并且æ¯æ¬¡å‡çº§å†…æ ¸æ—¶ï¼Œæ‚¨çš„ç”¨æˆ·éƒ½å¿…é¡»å•ç‹¬å‡çº§ - 您的模å—。 + 这些模å—。 -- 上é¢æ到的关于代ç è¯„å®¡çš„æ‰€æœ‰é—®é¢˜éƒ½æ›´åŠ å˜åœ¨äºŽå°é—æºä»£ç 。由于该代ç æ ¹æœ¬ä¸å¯ - ç”¨ï¼Œå› æ¤ç¤¾åŒºæ— æ³•å¯¹å…¶è¿›è¡Œå®¡æŸ¥ï¼Œæ¯«æ— ç–‘é—®ï¼Œå®ƒå°†å˜åœ¨ä¸¥é‡é—®é¢˜ã€‚ +- 上é¢æ到的关于代ç è¯„å®¡çš„æ‰€æœ‰é—®é¢˜éƒ½æ›´åŠ å˜åœ¨äºŽå°é—æºä»£ç ä¸ã€‚由于该代ç æ ¹æœ¬ + ä¸å¯å¾—ï¼Œå› æ¤ç¤¾åŒºæ— æ³•å¯¹å…¶è¿›è¡Œå®¡æŸ¥ï¼Œæ¯«æ— ç–‘é—®ï¼Œå®ƒå°†å˜åœ¨ä¸¥é‡é—®é¢˜ã€‚ -尤其是嵌入å¼ç³»ç»Ÿçš„åˆ¶é€ å•†ï¼Œå¯èƒ½ä¼šå€¾å‘于忽视本节ä¸æ‰€è¯´çš„å¤§éƒ¨åˆ†å†…å®¹ï¼Œå› ä¸ºä»–ä»¬ +尤其是嵌入å¼ç³»ç»Ÿçš„åˆ¶é€ å•†ï¼Œå¯èƒ½ä¼šå€¾å‘于忽视本节ä¸æ‰€è¯´çš„å¤§éƒ¨åˆ†å†…å®¹ï¼›å› ä¸ºä»–ä»¬ 相信自己æ£åœ¨å•†ç”¨ä¸€ç§ä½¿ç”¨å†»ç»“å†…æ ¸ç‰ˆæœ¬çš„ç‹¬ç«‹äº§å“，在å‘布åŽä¸éœ€è¦å†è¿›è¡Œå¼€å‘。 这个论点忽略了广泛的代ç 审查的价值以åŠå…许用户å‘产å“æ·»åŠ åŠŸèƒ½çš„ä»·å€¼ã€‚ä½†è¿™äº› -产å“也有有é™çš„商业寿命，之åŽå¿…é¡»å‘布新版本的产å“。在这一点上，代ç 在主线上 -并得到良好维护的供应商将能够更好地å ä½ï¼Œä»¥ä½¿æ–°äº§å“快速上市。 +产å“的商业寿命有é™ï¼Œä¹‹åŽå¿…é¡»å‘布新版本的产å“。在这一点上，代ç 在主线上并得到 +良好维护的供应商将能够更好地å ä½ï¼Œä»¥ä½¿æ–°äº§å“快速上市。 è®¸å¯ ---- @@ -164,23 +172,24 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata, å’Œ Jochen Voß. 代ç æ˜¯æ ¹æ®ä¸€äº›è®¸å¯è¯æ供给Linuxå†…æ ¸çš„ï¼Œä½†æ˜¯æ‰€æœ‰ä»£ç 都必须与GNUé€šç”¨å…¬å…±è®¸å¯ è¯ï¼ˆGPLV2）的版本2å…¼å®¹ï¼Œè¯¥ç‰ˆæœ¬æ˜¯è¦†ç›–æ•´ä¸ªå†…æ ¸åˆ†å‘的许å¯è¯ã€‚在实践ä¸ï¼Œè¿™æ„味 ç€æ‰€æœ‰ä»£ç 贡献都由GPLv2（å¯é€‰åœ°ï¼Œè¯è¨€å…许在更高版本的GPL下分å‘）或3åå¥BSD -许å¯ï¼ˆNew BSD License, 译者注）覆盖。任何ä¸åŒ…å«åœ¨å…¼å®¹è®¸å¯è¯ä¸çš„贡献都ä¸ä¼š +许å¯ï¼ˆNew BSD License，译者注）覆盖。任何ä¸åŒ…å«åœ¨å…¼å®¹è®¸å¯è¯ä¸çš„贡献都ä¸ä¼š 被接å—åˆ°å†…æ ¸ä¸ã€‚ è´¡çŒ®ç»™å†…æ ¸çš„ä»£ç ä¸éœ€è¦ï¼ˆæˆ–请求）版æƒåˆ†é…。åˆå¹¶åˆ°ä¸»çº¿å†…æ ¸ä¸çš„所有代ç 都ä¿ç•™ 其原始所有æƒï¼›å› æ¤ï¼Œå†…æ ¸çŽ°åœ¨æ‹¥æœ‰æ•°åƒä¸ªæ‰€æœ‰è€…。 -è¿™ç§æ‰€æœ‰æƒç»“构的一个暗示是，任何改å˜å†…æ ¸è®¸å¯çš„å°è¯•éƒ½æ³¨å®šä¼šå¤±è´¥ã€‚很少有实际 -的场景å¯ä»¥èŽ·å¾—所有版æƒæ‰€æœ‰è€…çš„åŒæ„ï¼ˆæˆ–è€…ä»Žå†…æ ¸ä¸åˆ 除他们的代ç ï¼‰ã€‚å› æ¤ï¼Œç‰¹ -别是，在å¯é¢„è§çš„å°†æ¥ï¼Œä¸å¯èƒ½è¿ç§»åˆ°GPL的版本3。 +è¿™ç§æ‰€æœ‰æƒç»“构也暗示ç€ï¼Œä»»ä½•æ”¹å˜å†…æ ¸è®¸å¯çš„å°è¯•éƒ½æ³¨å®šä¼šå¤±è´¥ã€‚很少有实际情况 +å¯ä»¥èŽ·å¾—所有版æƒæ‰€æœ‰è€…çš„åŒæ„ï¼ˆæˆ–è€…ä»Žå†…æ ¸ä¸åˆ 除他们的代ç ï¼‰ã€‚å› æ¤ï¼Œå°¤å…¶æ˜¯åœ¨ +å¯é¢„è§çš„å°†æ¥ï¼Œè®¸å¯è¯ä¸å¤§å¯èƒ½è¿ç§»åˆ°GPL的版本3。 -æ‰€æœ‰è´¡çŒ®ç»™å†…æ ¸çš„ä»£ç 都必须是åˆæ³•çš„å…è´¹è½¯ä»¶ã€‚å› æ¤ï¼Œä¸æŽ¥å—匿å（或匿å）贡献 -者的代ç 。所有贡献者都需è¦åœ¨ä»–们的代ç 上“sign offâ€ï¼Œå£°æ˜Žä»£ç å¯ä»¥åœ¨GPL下与内 -æ ¸ä¸€èµ·åˆ†å‘ã€‚æ— æ³•æ供未被其所有者许å¯ä¸ºå…费软件的代ç ，或å¯èƒ½ä¸ºå†…æ ¸é€ æˆç‰ˆæƒ -相关问题的代ç （例如，由缺ä¹é€‚当ä¿æŠ¤çš„åå‘工程工作派生的代ç ）ä¸èƒ½è¢«æŽ¥å—。 +æ‰€æœ‰è´¡çŒ®ç»™å†…æ ¸çš„ä»£ç 都必须是åˆæ³•çš„å…è´¹è½¯ä»¶ã€‚å› æ¤ï¼Œä¸æŽ¥å—匿å（或化å）贡献 +者的代ç 。所有贡献者都需è¦åœ¨ä»–们的代ç 上“sign off（ç¾å‘）â€ï¼Œå£°æ˜Žä»£ç å¯ä»¥ +在GPLä¸‹ä¸Žå†…æ ¸ä¸€èµ·åˆ†å‘ã€‚æ— æ³•æ供未被其所有者许å¯ä¸ºå…费软件的代ç ，或å¯èƒ½ä¸º +å†…æ ¸é€ æˆç‰ˆæƒç›¸å…³é—®é¢˜çš„代ç （例如，由缺ä¹é€‚当ä¿æŠ¤çš„åå‘工程工作派生的代ç ） +ä¸èƒ½è¢«æŽ¥å—。 -有关版æƒç›¸å…³é—®é¢˜çš„问题在Linuxå¼€å‘邮件列表ä¸å¾ˆå¸¸è§ã€‚è¿™æ ·çš„é—®é¢˜é€šå¸¸ä¼šå¾—åˆ°ä¸å°‘ -ç”案，但è¦è®°ä½ï¼Œå›žç”这些问题的人ä¸æ˜¯å¾‹å¸ˆï¼Œä¸èƒ½æ供法律咨询。如果您有关于 -Linuxæºä»£ç 的法律问题，那么与了解该领域的律师交æµæ˜¯æ— 法替代的。ä¾é 从技术 -邮件列表ä¸èŽ·å¾—çš„ç”案是一件冒险的事情。 +有关版æƒé—®é¢˜çš„æ问在Linuxå¼€å‘邮件列表ä¸å¾ˆå¸¸è§ã€‚è¿™æ ·çš„é—®é¢˜é€šå¸¸ä¼šå¾—åˆ°ä¸å°‘ç”案， +但请记ä½ï¼Œå›žç”这些问题的人ä¸æ˜¯å¾‹å¸ˆï¼Œä¸èƒ½æ供法律咨询。如果您有关于Linuxæºä»£ç +的法律问题，没有什么å¯ä»¥ä»£æ›¿å’¨è¯¢äº†è§£è¿™ä¸€é¢†åŸŸçš„律师。ä¾èµ–从技术邮件列表ä¸èŽ·å¾— +çš„ç”案是一件冒险的事情。 diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst index ebe2e0254b3e..229629e305ca 100644 --- a/Documentation/translations/zh_CN/process/2.Process.rst +++ b/Documentation/translations/zh_CN/process/2.Process.rst @@ -1,17 +1,24 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/2.Process.rst <development_process>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _cn_development_process: -å¼€å‘æµç¨‹å¦‚何工作 +å¼€å‘æµç¨‹å¦‚何进行 ================ -90年代早期的Linuxå†…æ ¸å¼€å‘是一件相当æ¾æ•£çš„事情，涉åŠçš„用户和开å‘人员相对较 -少。由于拥有数以百万计的用户群，并且在一年的时间里有大约2000åå¼€å‘人员å‚与 -è¿›æ¥ï¼Œå†…æ ¸å› æ¤å¿…é¡»å‘展许多æµç¨‹æ¥ä¿æŒå¼€å‘的顺利进行。è¦æˆä¸ºæµç¨‹çš„æœ‰æ•ˆç»„æˆ -部分，需è¦å¯¹æµç¨‹çš„工作方å¼æœ‰ä¸€ä¸ªæ‰Žå®žçš„ç†è§£ã€‚ +90年代早期的Linuxå†…æ ¸å¼€å‘是一件相当æ¾æ•£çš„事情，涉åŠçš„用户和开å‘人员相对较少。 +由于拥有数以百万计的用户群，且æ¯å¹´æœ‰å¤§çº¦2000åå¼€å‘人员å‚与进æ¥ï¼Œå†…æ ¸å› æ¤å¿…é¡» +å‘展出许多既定æµç¨‹æ¥ä¿è¯å¼€å‘的顺利进行。è¦å‚与到æµç¨‹ä¸æ¥ï¼Œéœ€è¦å¯¹æ¤æµç¨‹çš„进行 +æ–¹å¼æœ‰ä¸€ä¸ªæ‰Žå®žçš„ç†è§£ã€‚ 总览 ---- @@ -20,112 +27,113 @@ å†…æ ¸ç‰ˆæœ¬ã€‚æœ€è¿‘çš„å‘布历å²è®°å½•å¦‚下： ====== ================= - 4.11 四月 30, 2017 - 4.12 七月 2, 2017 - 4.13 ä¹æœˆ 3, 2017 - 4.14 å一月 12, 2017 - 4.15 一月 28, 2018 - 4.16 四月 1, 2018 + 5.0 2019å¹´3月3æ—¥ + 5.1 2019å¹´5月5æ—¥ + 5.2 2019å¹´7月7æ—¥ + 5.3 2019å¹´9月15æ—¥ + 5.4 2019å¹´11月24æ—¥ + 5.5 2020å¹´1月6æ—¥ ====== ================= -æ¯4.x版本都是一个主è¦çš„å†…æ ¸ç‰ˆæœ¬ï¼Œå…·æœ‰æ–°ç‰¹æ€§ã€å†…部API更改ç‰ç‰ã€‚一个典型的4.x -版本包å«å¤§çº¦13000个å˜æ›´é›†ï¼Œå˜æ›´äº†å‡ å万行代ç ã€‚å› æ¤ï¼Œ4.x是Linuxå†…æ ¸å¼€å‘çš„å‰ +æ¯ä¸ª5.x版本都是一个主è¦çš„å†…æ ¸ç‰ˆæœ¬ï¼Œå…·æœ‰æ–°ç‰¹æ€§ã€å†…部API更改ç‰ç‰ã€‚一个典型的5.x +版本包å«å¤§çº¦13000个å˜æ›´é›†ï¼Œå˜æ›´äº†å‡ å万行代ç ã€‚å› æ¤ï¼Œ5.x是Linuxå†…æ ¸å¼€å‘çš„å‰ æ²¿ï¼›å†…æ ¸ä½¿ç”¨æ»šåŠ¨å¼€å‘模型，ä¸æ–集æˆé‡å¤§å˜åŒ–。 -对于æ¯ä¸ªç‰ˆæœ¬çš„è¡¥ä¸åˆå¹¶ï¼Œéµå¾ªä¸€ä¸ªç›¸å¯¹ç®€å•çš„规则。在æ¯ä¸ªå¼€å‘周期的开始，“åˆå¹¶ -窗å£â€è¢«æ‰“开。当时，被认为足够稳定（并且被开å‘社区接å—）的代ç 被åˆå¹¶åˆ°ä¸»çº¿å†… +对于æ¯ä¸ªç‰ˆæœ¬çš„è¡¥ä¸åˆå¹¶ï¼Œéµå¾ªä¸€ä¸ªç›¸å¯¹ç®€å•çš„规则。在æ¯ä¸ªå¼€å‘周期的开头，“åˆå¹¶ +窗å£â€è¢«æ‰“开。这时，被认为足够稳定（并且被开å‘社区接å—）的代ç 被åˆå¹¶åˆ°ä¸»çº¿å†… æ ¸ä¸ã€‚在这段时间内，新开å‘周期的大部分å˜æ›´ï¼ˆä»¥åŠæ‰€æœ‰ä¸»è¦å˜æ›´ï¼‰å°†ä»¥æŽ¥è¿‘æ¯å¤© 1000次å˜æ›´ï¼ˆâ€œè¡¥ä¸â€æˆ–“å˜æ›´é›†â€ï¼‰çš„速度åˆå¹¶ã€‚ -（顺便说一å¥ï¼Œå€¼å¾—注æ„的是，åˆå¹¶çª—å£æœŸé—´é›†æˆçš„更改并ä¸æ˜¯å‡ç©ºäº§ç”Ÿçš„；它们是 -æå‰æ”¶é›†ã€æµ‹è¯•å’Œåˆ†çº§çš„。ç¨åŽå°†è¯¦ç»†æ述该过程的工作方å¼ï¼‰ã€‚ +（顺便说一å¥ï¼Œå€¼å¾—注æ„的是，åˆå¹¶çª—å£æœŸé—´é›†æˆçš„更改并ä¸æ˜¯å‡ç©ºäº§ç”Ÿçš„ï¼›å®ƒä»¬æ˜¯ç» +æå‰æ”¶é›†ã€æµ‹è¯•å’Œåˆ†çº§çš„。ç¨åŽå°†è¯¦ç»†æ述该过程的工作方å¼ã€‚） åˆå¹¶çª—å£æŒç»å¤§çº¦ä¸¤å‘¨ã€‚在这段时间结æŸæ—¶ï¼ŒLinusTorvalds将声明窗å£å·²å…³é—，并 -释放第一个“rcâ€å†…æ ¸ã€‚ä¾‹å¦‚ï¼Œå¯¹äºŽç›®æ ‡ä¸º4.14çš„å†…æ ¸ï¼Œåœ¨åˆå¹¶çª—å£ç»“æŸæ—¶å‘生的释放 -将被称为4.14-rc1。RC1版本是一个信å·ï¼Œè¡¨ç¤ºåˆå¹¶æ–°ç‰¹æ€§çš„时间已ç»è¿‡åŽ»ï¼Œç¨³å®šä¸‹ä¸€ -ä¸ªå†…æ ¸çš„æ—¶é—´å·²ç»å¼€å§‹ã€‚ +释放第一个“rcâ€å†…æ ¸ã€‚ä¾‹å¦‚ï¼Œå¯¹äºŽç›®æ ‡ä¸º5.6çš„å†…æ ¸ï¼Œåœ¨åˆå¹¶çª—å£ç»“æŸæ—¶å‘生的释放 +将被称为5.6-rc1。-rc1 版本是一个信å·ï¼Œè¡¨ç¤ºåˆå¹¶æ–°ç‰¹æ€§çš„时间已ç»è¿‡åŽ»ï¼Œç¨³å®šä¸‹ä¸€ +ä¸ªå†…æ ¸çš„æ—¶é—´å·²ç»åˆ°æ¥ã€‚ 在接下æ¥çš„6到10周内，åªæœ‰ä¿®å¤é—®é¢˜çš„è¡¥ä¸æ‰åº”该æ交给主线。有时会å…许更大的 -更改，但这ç§æƒ…况很少å‘生；试图在åˆå¹¶çª—å£å¤–åˆå¹¶æ–°åŠŸèƒ½çš„å¼€å‘人员往往会å—åˆ°ä¸ +更改，但这ç§æƒ…况很少å‘生；试图在åˆå¹¶çª—å£å¤–åˆå¹¶æ–°åŠŸèƒ½çš„å¼€å‘人员往往å—ä¸åˆ° å‹å¥½çš„接待。一般æ¥è¯´ï¼Œå¦‚果您错过了给定特性的åˆå¹¶çª—å£ï¼Œæœ€å¥½çš„åšæ³•æ˜¯ç‰å¾…下一 -个开å‘周期。（对于以å‰ä¸æ”¯æŒçš„硬件，å¶å°”会对驱动程åºè¿›è¡Œä¾‹å¤–ï¼›å¦‚æžœå®ƒä»¬ä¸ -改å˜å·²æœ‰ä»£ç ，则ä¸ä¼šå¯¼è‡´å›žå½’，并且应该å¯ä»¥éšæ—¶å®‰å…¨åœ°æ·»åŠ ）。 +个开å‘周期。（å¶å°”会对未支æŒç¡¬ä»¶çš„驱动程åºè¿›è¡Œä¾‹å¤–；如果它们ä¸æ”¹å˜å·²æœ‰ä»£ç ， +则ä¸ä¼šå¯¼è‡´å›žå½’，应该å¯ä»¥éšæ—¶è¢«å®‰å…¨åœ°åŠ 入）。 éšç€ä¿®å¤ç¨‹åºè¿›å…¥ä¸»çº¿ï¼Œè¡¥ä¸é€Ÿåº¦å°†éšç€æ—¶é—´çš„推移而å˜æ…¢ã€‚Linus大约æ¯å‘¨å‘布一次 -æ–°çš„-rcå†…æ ¸ï¼›ä¸€ä¸ªæ£å¸¸çš„系列将在-rc6å’Œ-rc9ä¹‹é—´ï¼Œå†…æ ¸è¢«è®¤ä¸ºè¶³å¤Ÿç¨³å®šå¹¶æœ€ç»ˆå‘布。 +æ–°çš„-rcå†…æ ¸ï¼›åœ¨å†…æ ¸è¢«è®¤ä¸ºè¶³å¤Ÿç¨³å®šå¹¶æœ€ç»ˆå‘布å‰ï¼Œä¸€èˆ¬ä¼šè¾¾åˆ°-rc6到-rc9之间。 然åŽï¼Œæ•´ä¸ªè¿‡ç¨‹åˆé‡æ–°å¼€å§‹äº†ã€‚ -例如，这里是4.16çš„å¼€å‘周期进行情况（2018年的所有日期）: +例如，这里是5.4çš„å¼€å‘周期进行情况（2019年）: ============== ============================== - 一月 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 稳定版å‘布 + ä¹æœˆ 15 5.3 稳定版å‘布 + ä¹æœˆ 30 5.4-rc1 åˆå¹¶çª—å£å…³é— + å月 6 5.4-rc2 + å月 13 5.4-rc3 + å月 20 5.4-rc4 + å月 27 5.4-rc5 + å一月 3 5.4-rc6 + å一月 10 5.4-rc7 + å一月 17 5.4-rc8 + å一月 24 5.4 稳定版å‘布 ============== ============================== -å¼€å‘人员如何决定何时结æŸå¼€å‘周期并创建稳定的版本？使用的最é‡è¦çš„æŒ‡æ ‡æ˜¯ä»¥å‰ -版本的回归列表。ä¸æ¬¢è¿Žå‡ºçŽ°ä»»ä½•é”™è¯¯ï¼Œä½†æ˜¯é‚£äº›ç ´å了以å‰èƒ½å·¥ä½œçš„系统的错误被 -认为是特别严é‡çš„ã€‚å› æ¤ï¼Œå¯¼è‡´å›žå½’çš„è¡¥ä¸æ˜¯ä¸å—欢迎的，很å¯èƒ½åœ¨ç¨³å®šæœŸå†…åˆ é™¤ã€‚ +å¼€å‘人员如何决定何时结æŸå¼€å‘周期并创建稳定版本？最é‡è¦çš„æŒ‡æ ‡æ˜¯ä»¥å‰ç‰ˆæœ¬çš„ +回归列表。ä¸æ¬¢è¿Žå‡ºçŽ°ä»»ä½•é”™è¯¯ï¼Œä½†æ˜¯é‚£äº›ç ´å了以å‰èƒ½å·¥ä½œçš„系统的错误被认为是 +特别严é‡çš„ã€‚å› æ¤ï¼Œå¯¼è‡´å›žå½’çš„è¡¥ä¸æ˜¯ä¸å—欢迎的，很å¯èƒ½åœ¨ç¨³å®šæœŸå†…åˆ é™¤ã€‚ å¼€å‘äººå‘˜çš„ç›®æ ‡æ˜¯åœ¨ç¨³å®šå‘布之å‰ä¿®å¤æ‰€æœ‰å·²çŸ¥çš„回归。在现实世界ä¸ï¼Œè¿™ç§å®Œç¾Žæ˜¯ -很难实现的；在这ç§è§„模的项目ä¸ï¼Œå˜é‡å¤ªå¤šäº†ã€‚有一点，延迟最终版本åªä¼šä½¿é—®é¢˜ -å˜å¾—更糟；ç‰å¾…下一个åˆå¹¶çª—å£çš„ä¸€å †æ›´æ”¹å°†å˜å¤§ï¼Œä»Žè€Œåœ¨ä¸‹æ¬¡åˆ›å»ºæ›´å¤šçš„回归错误。 -å› æ¤ï¼Œå¤§å¤šæ•°4.xå†…æ ¸éƒ½æœ‰ä¸€äº›å·²çŸ¥çš„å›žå½’é”™è¯¯ï¼Œä¸è¿‡ï¼Œå¸Œæœ›æ²¡æœ‰ä¸€ä¸ªæ˜¯ä¸¥é‡çš„。 +很难实现的；在这ç§è§„模的项目ä¸ï¼Œå˜æ•°å¤ªå¤šäº†ã€‚需è¦è¯´æ˜Žçš„是，延迟最终版本åªä¼š +使问题å˜å¾—更糟；ç‰å¾…下一个åˆå¹¶çª—å£çš„更改将å˜å¤šï¼Œå¯¼è‡´ä¸‹æ¬¡å‡ºçŽ°æ›´å¤šçš„回归错误。 +å› æ¤ï¼Œå¤§å¤šæ•°5.xå†…æ ¸éƒ½æœ‰ä¸€äº›å·²çŸ¥çš„å›žå½’é”™è¯¯ï¼Œä¸è¿‡ï¼Œå¸Œæœ›æ²¡æœ‰ä¸€ä¸ªæ˜¯ä¸¥é‡çš„。 -一旦一个稳定的版本å‘布，它æ£åœ¨è¿›è¡Œçš„维护工作就被移交给“稳定团队â€ï¼Œç›®å‰ç”± -Greg Kroah-Hartman组æˆã€‚稳定团队将使用4.x.yç¼–å·æ–¹æ¡ˆä¸å®šæœŸçš„å‘布稳定版本的更 -新。è¦åŠ 入更新版本，补ä¸ç¨‹åºå¿…须（1）修å¤ä¸€ä¸ªé‡è¦çš„bug，（2）已ç»åˆå¹¶åˆ° -下一个开å‘主线ä¸ã€‚å†…æ ¸é€šå¸¸ä¼šåœ¨è¶…è¿‡å…¶åˆå§‹ç‰ˆæœ¬çš„一个以上的开å‘周期内接收稳定 -的更新。例如，4.13å†…æ ¸çš„åŽ†å²å¦‚下 +一旦一个稳定的版本å‘布，它的æŒç»ç»´æŠ¤å·¥ä½œå°±è¢«ç§»äº¤ç»™â€œç¨³å®šå›¢é˜Ÿâ€ï¼Œç›®å‰ç”± +Greg Kroah-Hartman领导。稳定团队将使用5.x.yç¼–å·æ–¹æ¡ˆä¸å®šæœŸåœ°å‘布稳定版本的 +更新。è¦åˆå…¥æ›´æ–°ç‰ˆæœ¬ï¼Œè¡¥ä¸å¿…须（1）修å¤ä¸€ä¸ªé‡è¦çš„缺陷，且（2）已ç»åˆå¹¶åˆ° +下一个开å‘版本主线ä¸ã€‚å†…æ ¸é€šå¸¸ä¼šåœ¨å…¶åˆå§‹ç‰ˆæœ¬åŽçš„一个以上的开å‘周期内收到 +稳定版更新。例如，5.2å†…æ ¸çš„åŽ†å²å¦‚下（2019年）： ============== =============================== - ä¹æœˆ 3 4.13 稳定版å‘布 - ä¹æœˆ 13 4.13.1 - ä¹æœˆ 20 4.13.2 - ä¹æœˆ 27 4.13.3 - å月 5 4.13.4 - å月 12 4.13.5 + 七月 7 5.2 稳定版å‘布 + 七月 13 5.2.1 + 七月 21 5.2.2 + 七月 26 5.2.3 + 七月 28 5.2.4 + 七月 31 5.2.5 ... ... - å一月 24 4.13.16 + å月 11 5.2.21 ============== =============================== -4.13.16是4.13版本的最终稳定更新。 +5.2.21是5.2版本的最终稳定更新。 æœ‰äº›å†…æ ¸è¢«æŒ‡å®šä¸ºâ€œé•¿æœŸâ€å†…æ ¸ï¼›å®ƒä»¬å°†å¾—åˆ°æ›´é•¿æ—¶é—´çš„æ”¯æŒã€‚在本文ä¸ï¼Œå½“å‰çš„长期 å†…æ ¸åŠå…¶ç»´æŠ¤è€…是： - ====== ====================== ============================== - 3.16 Ben Hutchings (é•¿æœŸç¨³å®šå†…æ ¸) - 4.1 Sasha Levin - 4.4 Greg Kroah-Hartman (é•¿æœŸç¨³å®šå†…æ ¸) - 4.9 Greg Kroah-Hartman - 4.14 Greg Kroah-Hartman - ====== ====================== ============================== + ====== ================================ ================ + 3.16 Ben Hutchings ï¼ˆé•¿æœŸç¨³å®šå†…æ ¸ï¼‰ + 4.4 Greg Kroah-Hartman & Sasha Levin ï¼ˆé•¿æœŸç¨³å®šå†…æ ¸ï¼‰ + 4.9 Greg Kroah-Hartman & Sasha Levin + 4.14 Greg Kroah-Hartman & Sasha Levin + 4.19 Greg Kroah-Hartman & Sasha Levin + 5.4 Greg Kroah-Hartman & Sasha Levin + ====== ================================ ================ -为长期支æŒé€‰æ‹©å†…æ ¸çº¯ç²¹æ˜¯ç»´æŠ¤äººå‘˜æœ‰å¿…è¦å’Œæ—¶é—´æ¥ç»´æŠ¤è¯¥ç‰ˆæœ¬çš„问题。目å‰è¿˜æ²¡æœ‰ -为å³å°†å‘布的任何特定版本æ供长期支æŒçš„已知计划。 +长期支æŒå†…æ ¸çš„é€‰æ‹©çº¯ç²¹æ˜¯ç»´æŠ¤äººå‘˜æ˜¯å¦æœ‰éœ€æ±‚和时间æ¥ç»´æŠ¤è¯¥ç‰ˆæœ¬çš„问题。 +ç›®å‰è¿˜æ²¡æœ‰ä¸ºå³å°†å‘布的任何特定版本æ供长期支æŒçš„已知计划。 è¡¥ä¸çš„生命周期 -------------- è¡¥ä¸ä¸ä¼šç›´æŽ¥ä»Žå¼€å‘äººå‘˜çš„é”®ç›˜è¿›å…¥ä¸»çº¿å†…æ ¸ã€‚ç›¸å，有一个ç¨å¾®å¤æ‚ï¼ˆå¦‚æžœæœ‰äº›éž æ£å¼ï¼‰çš„过程，旨在确ä¿å¯¹æ¯ä¸ªè¡¥ä¸è¿›è¡Œè´¨é‡å®¡æŸ¥ï¼Œå¹¶ç¡®ä¿æ¯ä¸ªè¡¥ä¸å®žçŽ°äº†ä¸€ä¸ªåœ¨ä¸»çº¿ -ä¸éœ€è¦çš„更改。对于å°çš„ä¿®å¤ï¼Œè¿™ä¸ªè¿‡ç¨‹å¯èƒ½ä¼šå¾ˆå¿«å‘生，或者，在大的和有争议的 -å˜æ›´çš„情况下，会æŒç»æ•°å¹´ã€‚许多开å‘人员的挫折æ¥è‡ªäºŽå¯¹è¿™ä¸ªè¿‡ç¨‹ç¼ºä¹ç†è§£æˆ–者 -试图绕过它。 +ä¸éœ€è¦çš„更改。对于å°çš„ä¿®å¤ï¼Œè¿™ä¸ªè¿‡ç¨‹å¯èƒ½ä¼šå¾ˆå¿«å®Œæˆï¼Œï¼Œè€Œå¯¹äºŽè¾ƒå¤§æˆ–有争议的 +å˜æ›´ï¼Œå¯èƒ½ä¼šæŒç»æ•°å¹´ã€‚许多开å‘人员的沮丧æ¥è‡ªäºŽå¯¹è¿™ä¸ªè¿‡ç¨‹ç¼ºä¹ç†è§£æˆ–者试图绕过它。 -为了å‡å°‘è¿™ç§æŒ«æŠ˜æ„Ÿï¼Œæœ¬æ–‡å°†æè¿°è¡¥ä¸å¦‚ä½•è¿›å…¥å†…æ ¸ã€‚ä¸‹é¢æ˜¯ä¸€ä¸ªä»‹ç»ï¼Œå®ƒä»¥æŸç§ -ç†æƒ³åŒ–çš„æ–¹å¼æ述了这个过程。更详细的过程将在åŽé¢çš„ç« èŠ‚ä¸ä»‹ç»ã€‚ +为了å‡å°‘è¿™ç§æŒ«è´¥ï¼Œæœ¬æ–‡å°†æè¿°è¡¥ä¸å¦‚ä½•è¿›å…¥å†…æ ¸ã€‚ä¸‹é¢çš„介ç»ä»¥ä¸€ç§è¾ƒä¸ºç†æƒ³åŒ–çš„ +æ–¹å¼æ述了这个过程。更详细的过程将在åŽé¢çš„ç« èŠ‚ä¸ä»‹ç»ã€‚ -è¡¥ä¸ç¨‹åºç»åŽ†çš„阶段通常是： +è¡¥ä¸é€šå¸¸è¦ç»åŽ†ä»¥ä¸‹é˜¶æ®µï¼š -- 设计。这就是补ä¸çš„真æ£éœ€æ±‚——以åŠæ»¡è¶³è¿™äº›éœ€æ±‚çš„æ–¹å¼â€”—的所在。设计工作通常 +- 设计。这就是补ä¸çš„真æ£éœ€æ±‚——以åŠæ»¡è¶³è¿™äº›éœ€æ±‚çš„æ–¹å¼â€”—所在。设计工作通常 是在ä¸æ¶‰åŠç¤¾åŒºçš„情况下完æˆçš„，但是如果å¯èƒ½çš„è¯ï¼Œæœ€å¥½æ˜¯åœ¨å…¬å¼€çš„æƒ…å†µä¸‹å®Œæˆ è¿™é¡¹å·¥ä½œï¼›è¿™æ ·å¯ä»¥èŠ‚çœå¾ˆå¤šç¨åŽå†é‡æ–°è®¾è®¡çš„时间。 @@ -134,53 +142,51 @@ Greg Kroah-Hartman组æˆã€‚稳定团队将使用4.x.yç¼–å·æ–¹æ¡ˆä¸å®šæœŸçš„å‘ - 更广泛的评审。当补ä¸æŽ¥è¿‘准备好纳入主线时，它应该被相关的å系统维护人员 接å———尽管这ç§æŽ¥å—并ä¸èƒ½ä¿è¯è¡¥ä¸ä¼šä¸€ç›´å»¶ä¼¸åˆ°ä¸»çº¿ã€‚è¡¥ä¸å°†å‡ºçŽ°åœ¨ç»´æŠ¤äººå‘˜çš„ - åç³»ç»Ÿæ ‘ä¸ï¼Œå¹¶è¿›å…¥ -next æ ‘ï¼ˆå¦‚ä¸‹æ‰€è¿°ï¼‰ã€‚å½“æµç¨‹å·¥ä½œæ—¶ï¼Œæ¤æ¥éª¤å°†å¯¼è‡´å¯¹è¡¥ä¸ - 进行更广泛的审查，并å‘现由于将æ¤è¡¥ä¸ä¸Žå…¶ä»–人所åšçš„工作集æˆè€Œå¯¼è‡´çš„任何 + åç³»ç»Ÿæ ‘ä¸ï¼Œå¹¶è¿›å…¥ -next æ ‘ï¼ˆå¦‚ä¸‹æ‰€è¿°ï¼‰ã€‚å½“æµç¨‹è¿›è¡Œæ—¶ï¼Œæ¤æ¥éª¤å°†ä¼šå¯¹è¡¥ä¸ + 进行更广泛的审查，并å‘现由于将æ¤è¡¥ä¸ä¸Žå…¶ä»–人所åšçš„工作åˆå¹¶è€Œå¯¼è‡´çš„任何 问题。 -- 请注æ„ï¼Œå¤§å¤šæ•°ç»´æŠ¤äººå‘˜ä¹Ÿæœ‰æ—¥å¸¸å·¥ä½œï¼Œå› æ¤åˆå¹¶è¡¥ä¸å¯èƒ½ä¸æ˜¯ä»–们的最高优先级。 - 如果您的补ä¸ç¨‹åºå¾—到了关于所需更改的å馈，那么您应该进行这些更改，或者为 - ä¸åº”è¯¥è¿›è¡Œè¿™äº›æ›´æ”¹çš„åŽŸå› è¾©æŠ¤ã€‚å¦‚æžœæ‚¨çš„è¡¥ä¸æ²¡æœ‰è¯„审æ„è§ï¼Œä½†æ²¡æœ‰è¢«å…¶ç›¸åº”çš„ - å系统或驱动程åºç»´æŠ¤è€…接å—，那么您应该åšæŒä¸æ‡ˆåœ°å°†è¡¥ä¸æ›´æ–°åˆ°å½“å‰å†…æ ¸ï¼Œä½¿ - 其干净地应用，并ä¸æ–地将其å‘é€ä»¥ä¾›å®¡æŸ¥å’Œåˆå¹¶ã€‚ +- 请注æ„ï¼Œå¤§å¤šæ•°ç»´æŠ¤äººå‘˜ä¹Ÿæœ‰æ—¥å¸¸å·¥ä½œï¼Œå› æ¤åˆå¹¶è¡¥ä¸å¯èƒ½ä¸æ˜¯ä»–们的最优先工作。 + 如果您的补ä¸å¾—到了需è¦æ›´æ”¹çš„å馈，那么您应该进行这些更改，或者解释为何 + ä¸åº”该进行这些更改。如果您的补ä¸æ²¡æœ‰è¯„审æ„è§ï¼Œä¹Ÿæ²¡æœ‰è¢«å…¶ç›¸åº”çš„å系统或 + 驱动程åºç»´æŠ¤è€…接å—，那么您应该åšæŒä¸æ‡ˆåœ°å°†è¡¥ä¸æ›´æ–°åˆ°å½“å‰å†…æ ¸ä½¿å…¶å¯è¢«æ£å¸¸ + 应用，并ä¸æ–地å‘é€å®ƒä»¥ä¾›å®¡æŸ¥å’Œåˆå¹¶ã€‚ - åˆå¹¶åˆ°ä¸»çº¿ã€‚最终，一个æˆåŠŸçš„è¡¥ä¸å°†è¢«åˆå¹¶åˆ°ç”±LinusTorvalds管ç†çš„主线å˜å‚¨åº“ - ä¸ã€‚æ¤æ—¶å¯èƒ½ä¼šå‡ºçŽ°æ›´å¤šçš„评论和/或问题；开å‘人员应对这些问题并解决出现的 - 任何问题很é‡è¦ã€‚ + ä¸ã€‚æ¤æ—¶å¯èƒ½ä¼šå‡ºçŽ°æ›´å¤šçš„评论和/或问题；对开å‘人员æ¥è¯´åº”对这些问题并解决 + 出现的任何问题ä»å¾ˆé‡è¦ã€‚ -- 稳定版å‘布。å¯èƒ½å—è¡¥ä¸å½±å“的用户数é‡çŽ°åœ¨å¾ˆå¤§ï¼Œå› æ¤å¯èƒ½å†æ¬¡å‡ºçŽ°æ–°çš„问题。 +- 稳定版å‘布。大é‡ç”¨æˆ·å¯èƒ½å—æ¤è¡¥ä¸å½±å“ï¼Œå› æ¤å¯èƒ½å†æ¬¡å‡ºçŽ°æ–°çš„问题。 - 长期维护。虽然开å‘人员在åˆå¹¶ä»£ç åŽå¯èƒ½ä¼šå¿˜è®°ä»£ç ，但这ç§è¡Œä¸ºå¾€å¾€ä¼šç»™å¼€å‘ - 社区留下ä¸è‰¯å°è±¡ã€‚åˆå¹¶ä»£ç æ¶ˆé™¤äº†ä¸€äº›ç»´æŠ¤è´Ÿæ‹…ï¼Œå› ä¸ºå…¶ä»–ä»£ç 将修å¤ç”±API - 更改引起的问题。但是，如果代ç è¦é•¿æœŸä¿æŒæœ‰ç”¨ï¼ŒåŽŸå§‹å¼€å‘人员应该继ç»ä¸º - 代ç 负责。 + 社区留下ä¸è‰¯å°è±¡ã€‚åˆå¹¶ä»£ç æ¶ˆé™¤äº†ä¸€äº›ç»´æŠ¤è´Ÿæ‹…ï¼Œå› ä¸ºå…¶ä»–äººå°†ä¿®å¤ç”±API更改 + 引起的问题。但是，如果代ç è¦é•¿æœŸä¿æŒå¯ç”¨ï¼ŒåŽŸå§‹å¼€å‘人员应该继ç»ä¸ºä»£ç 负责。 -å†…æ ¸å¼€å‘人员（或他们的雇主）犯的最大错误之一是试图将æµç¨‹ç®€åŒ–为一个 -“åˆå¹¶åˆ°ä¸»çº¿â€æ¥éª¤ã€‚è¿™ç§æ–¹æ³•æ€»æ˜¯ä¼šè®©æ‰€æœ‰ç›¸å…³äººå‘˜æ„Ÿåˆ°æ²®ä¸§ã€‚ +å†…æ ¸å¼€å‘人员（或他们的雇主）犯的最大错误之一是试图将æµç¨‹ç®€åŒ–为一个“åˆå¹¶åˆ° +主线â€æ¥éª¤ã€‚è¿™ç§æ–¹æ³•æ€»æ˜¯ä¼šè®©æ‰€æœ‰ç›¸å…³äººå‘˜æ„Ÿåˆ°æ²®ä¸§ã€‚ è¡¥ä¸å¦‚ä½•è¿›å…¥å†…æ ¸ ---------------- åªæœ‰ä¸€ä¸ªäººå¯ä»¥å°†è¡¥ä¸åˆå¹¶åˆ°ä¸»çº¿å†…æ ¸å˜å‚¨åº“ä¸ï¼šLinusTorvalds。但是，在进入 2.6.38å†…æ ¸çš„9500多个补ä¸ä¸ï¼Œåªæœ‰112个（大约1.3%）是由Linus自己直接选择的。 -å†…æ ¸é¡¹ç›®å·²ç»å‘展到一个规模，没有一个开å‘人员å¯ä»¥åœ¨æ²¡æœ‰æ”¯æŒçš„情况下检查和 -选择æ¯ä¸ªè¡¥ä¸ã€‚å†…æ ¸å¼€å‘人员处ç†è¿™ç§å¢žé•¿çš„æ–¹å¼æ˜¯é€šè¿‡ä½¿ç”¨å›´ç»•ä¿¡ä»»é“¾æž„建的 -助ç†ç³»ç»Ÿã€‚ +å†…æ ¸é¡¹ç›®å·²ç»å‘展到一个没有一个开å‘人员å¯ä»¥åœ¨æ²¡æœ‰æ”¯æŒçš„情况下检查和选择æ¯ä¸ª +è¡¥ä¸çš„è§„æ¨¡ã€‚å†…æ ¸å¼€å‘人员处ç†è¿™ç§å¢žé•¿çš„æ–¹å¼æ˜¯ä½¿ç”¨å›´ç»•ä¿¡ä»»é“¾æž„建的助ç†ç³»ç»Ÿã€‚ -å†…æ ¸ä»£ç 库在逻辑上被分解为一组å系统：网络ã€ç‰¹å®šçš„体系结构支æŒã€å†…å˜ç®¡ç†ã€ -视频设备ç‰ã€‚大多数å系统都有一个指定的维护人员，开å‘人员对该å系统ä¸çš„代ç -负有全部责任。这些å系统维护者（æ¾æ•£åœ°ï¼‰æ˜¯ä»–们所管ç†çš„å†…æ ¸éƒ¨åˆ†çš„å®ˆæŠ¤è€…ï¼› -他们（通常）会接å—一个补ä¸ä»¥åŒ…å«åˆ°ä¸»çº¿å†…æ ¸ä¸ã€‚ +å†…æ ¸ä»£ç 库在逻辑上被分解为一组å系统：网络ã€ç‰¹å®šä½“系结构支æŒã€å†…å˜ç®¡ç†ã€è§† +频设备ç‰ã€‚大多数å系统都有一个指定的维护人员，其总体负责该å系统ä¸çš„代ç 。 +这些å系统维护者（æ¾æ•£åœ°ï¼‰æ˜¯ä»–们所管ç†çš„å†…æ ¸éƒ¨åˆ†çš„â€œå®ˆé—¨å‘˜â€ï¼›ä»–们（通常） +会接å—一个补ä¸ä»¥åŒ…å«åˆ°ä¸»çº¿å†…æ ¸ä¸ã€‚ -å系统维护人员æ¯ä¸ªäººéƒ½ä½¿ç”¨gitæºä»£ç 管ç†å·¥å…·ç®¡ç†è‡ªå·±ç‰ˆæœ¬çš„å†…æ ¸æºä»£ç æ ‘ã€‚Git -ç‰å·¥å…·ï¼ˆä»¥åŠQuilt或Mercurialç‰ç›¸å…³å·¥å…·ï¼‰å…许维护人员跟踪补ä¸åˆ—表，包括作者 +å系统维护人员æ¯ä¸ªäººéƒ½ç®¡ç†ç€è‡ªå·±ç‰ˆæœ¬çš„å†…æ ¸æºä»£ç æ ‘ï¼Œé€šå¸¸ï¼ˆå¹¶éžæ€»æ˜¯ï¼‰ä½¿ç”¨Git。 +Gitç‰å·¥å…·ï¼ˆä»¥åŠQuilt或Mercurialç‰ç›¸å…³å·¥å…·ï¼‰å…许维护人员跟踪补ä¸åˆ—表，包括作者 ä¿¡æ¯å’Œå…¶ä»–元数æ®ã€‚在任何给定的时间，维护人员都å¯ä»¥ç¡®å®šä»–或她的å˜å‚¨åº“ä¸çš„哪 些补ä¸åœ¨ä¸»çº¿ä¸æ‰¾ä¸åˆ°ã€‚ -当åˆå¹¶çª—å£æ‰“开时，顶级维护人员将è¦æ±‚Linus从其å˜å‚¨åº“ä¸â€œæ‹‰å‡ºâ€ä»–们为åˆå¹¶é€‰æ‹© +当åˆå¹¶çª—å£æ‰“开时，顶级维护人员将è¦æ±‚Linus从å˜å‚¨åº“ä¸â€œæ‹‰å‡ºâ€ä»–们为åˆå¹¶é€‰æ‹© çš„è¡¥ä¸ã€‚如果LinusåŒæ„，补ä¸æµå°†æµå‘ä»–çš„å˜å‚¨åº“，æˆä¸ºä¸»çº¿å†…æ ¸çš„ä¸€éƒ¨åˆ†ã€‚ -Linus对拉æ“作ä¸æŽ¥æ”¶åˆ°çš„特定补ä¸çš„关注程度å„ä¸ç›¸åŒã€‚很明显，有时他看起æ¥å¾ˆ -关注。但是，作为一般规则，Linus相信å系统维护人员ä¸ä¼šå‘上游å‘é€åè¡¥ä¸ã€‚ +Linus对拉å–ä¸æŽ¥æ”¶åˆ°çš„特定补ä¸çš„关注程度å„ä¸ç›¸åŒã€‚很明显，有时他看起æ¥å¾ˆ +关注。但是一般æ¥è¯´ï¼ŒLinus相信å系统维护人员ä¸ä¼šå‘上游å‘é€åè¡¥ä¸ã€‚ å系统维护人员å过æ¥ä¹Ÿå¯ä»¥ä»Žå…¶ä»–维护人员那里获å–è¡¥ä¸ã€‚ä¾‹å¦‚ï¼Œç½‘ç»œæ ‘æ˜¯ç”±é¦–å…ˆ 在专用于网络设备驱动程åºã€æ— 线网络ç‰çš„æ ‘ä¸ç§¯ç´¯çš„è¡¥ä¸æž„建的。æ¤å˜å‚¨é“¾å¯ä»¥ @@ -195,26 +201,26 @@ Next æ ‘ åç³»ç»Ÿæ ‘é“¾å¼•å¯¼è¡¥ä¸æµåˆ°å†…æ ¸ï¼Œä½†å®ƒä¹Ÿæ出了一个有趣的问题：如果有人想查看为 下一个åˆå¹¶çª—å£å‡†å¤‡çš„所有补ä¸æ€Žä¹ˆåŠžï¼Ÿå¼€å‘人员将感兴趣的是，还有什么其他的 -更改有待解决，以查看是å¦å˜åœ¨éœ€è¦æ‹…心的冲çªï¼›ä¾‹å¦‚ï¼Œæ›´æ”¹æ ¸å¿ƒå†…æ ¸å‡½æ•°åŽŸåž‹çš„ +更改有待解决，以了解是å¦å˜åœ¨éœ€è¦æ‹…心的冲çªï¼›ä¾‹å¦‚ï¼Œæ›´æ”¹æ ¸å¿ƒå†…æ ¸å‡½æ•°åŽŸåž‹çš„ 修补程åºå°†ä¸Žä½¿ç”¨è¯¥å‡½æ•°æ—§å½¢å¼çš„任何其他修补程åºå†²çªã€‚审查人员和测试人员希望 -在所有这些å˜æ›´åˆ°è¾¾ä¸»çº¿å†…æ ¸ä¹‹å‰ï¼Œèƒ½å¤Ÿè®¿é—®å®ƒä»¬çš„集æˆå½¢å¼ä¸çš„å˜æ›´ã€‚您å¯ä»¥ä»Žæ‰€æœ‰ -有趣的åç³»ç»Ÿæ ‘ä¸æå–更改，但这将是一项大型且容易出错的工作。 +在所有这些å˜æ›´åˆ°è¾¾ä¸»çº¿å†…æ ¸ä¹‹å‰ï¼Œèƒ½å¤Ÿè®¿é—®å®ƒä»¬çš„集æˆå½¢å¼çš„å˜æ›´ã€‚您å¯ä»¥ä»Žæ‰€æœ‰ +相关的åç³»ç»Ÿæ ‘ä¸æå–更改，但这将是一项å¤æ‚且容易出错的工作。 -ç”案以-nextæ ‘çš„å½¢å¼å‡ºçŽ°ï¼Œåœ¨è¿™é‡Œåç³»ç»Ÿæ ‘è¢«æ”¶é›†ä»¥ä¾›æµ‹è¯•å’Œå®¡æŸ¥ã€‚Andrew Morton -ç»´æŠ¤çš„è¿™äº›æ—§æ ‘è¢«ç§°ä¸ºâ€œ-mmâ€ï¼ˆç”¨äºŽå†…å˜ç®¡ç†ï¼Œè¿™å°±æ˜¯å®ƒçš„å¯åŠ¨åå—）。-mm æ ‘é›†æˆäº† -一长串åç³»ç»Ÿæ ‘ä¸çš„è¡¥ä¸ï¼›å®ƒè¿˜åŒ…å«ä¸€äº›æ—¨åœ¨å¸®åŠ©è°ƒè¯•çš„è¡¥ä¸ã€‚ +解决方案以-nextæ ‘çš„å½¢å¼å‡ºçŽ°ï¼Œåœ¨è¿™é‡Œåç³»ç»Ÿæ ‘è¢«æ”¶é›†ä»¥ä¾›æµ‹è¯•å’Œå®¡æŸ¥ã€‚è¿™äº›æ ‘ä¸ +ç”±Andrew Morton维护的较è€çš„一个，被称为“-mmâ€ï¼ˆç”¨äºŽå†…å˜ç®¡ç†ï¼Œåˆ›å»ºæ—¶ä¸ºæ¤ï¼‰ã€‚ +-mm æ ‘é›†æˆäº†ä¸€é•¿ä¸²åç³»ç»Ÿæ ‘ä¸çš„è¡¥ä¸ï¼›å®ƒè¿˜åŒ…å«ä¸€äº›æ—¨åœ¨å¸®åŠ©è°ƒè¯•çš„è¡¥ä¸ã€‚ 除æ¤ä¹‹å¤–，-mm 还包å«å¤§é‡ç”±Andrew直接选择的补ä¸ã€‚这些补ä¸å¯èƒ½å·²ç»å‘布在邮件 -列表上，或者它们å¯èƒ½åº”ç”¨äºŽå†…æ ¸ä¸æ²¡æœ‰æŒ‡å®šåç³»ç»Ÿæ ‘çš„éƒ¨åˆ†ã€‚ç»“æžœï¼Œ-mm ä½œä¸ºä¸€ç§ -最åŽæ‰‹æ®µçš„åç³»ç»Ÿæ ‘è¿è¡Œï¼›å¦‚果没有其他明显的路径å¯ä»¥è®©è¡¥ä¸è¿›å…¥ä¸»çº¿ï¼Œé‚£ä¹ˆå®ƒå¾ˆ -å¯èƒ½ä»¥-mm 结æŸã€‚累积在-mm ä¸çš„å„ç§è¡¥ä¸æœ€ç»ˆå°†è¢«è½¬å‘到适当的åç³»ç»Ÿæ ‘ï¼Œæˆ–è€…ç›´æŽ¥ +列表上，或者它们å¯èƒ½åº”ç”¨äºŽå†…æ ¸ä¸æœªæŒ‡å®šåç³»ç»Ÿæ ‘çš„éƒ¨åˆ†ã€‚åŒæ—¶ï¼Œ-mm ä½œä¸ºæœ€åŽ +手段的åç³»ç»Ÿæ ‘ï¼›å¦‚æžœæ²¡æœ‰å…¶ä»–æ˜Žæ˜¾çš„è·¯å¾„å¯ä»¥è®©è¡¥ä¸è¿›å…¥ä¸»çº¿ï¼Œé‚£ä¹ˆå®ƒå¾ˆå¯èƒ½æœ€ +终选择-mm æ ‘ã€‚ç´¯ç§¯åœ¨-mm ä¸çš„å„ç§è¡¥ä¸æœ€ç»ˆå°†è¢«è½¬å‘到适当的åç³»ç»Ÿæ ‘ï¼Œæˆ–è€…ç›´æŽ¥ å‘é€åˆ°Linus。在典型的开å‘周期ä¸ï¼Œå¤§çº¦5-10%çš„è¡¥ä¸é€šè¿‡-mm 进入主线。 -当å‰-mm è¡¥ä¸å¯åœ¨â€œmmotmâ€ï¼ˆ-mm of the moment）目录ä¸æ‰¾åˆ°ï¼Œåœ°å€ï¼š +当å‰-mm è¡¥ä¸å¯åœ¨â€œmmotmâ€ï¼ˆ-mm of the moment）目录ä¸æ‰¾åˆ°ï¼š https://www.ozlabs.org/~akpm/mmotm/ -然而，使用mmotmæ ‘å¯èƒ½æ˜¯ä¸€ç§ä»¤äººæ²®ä¸§çš„体验；它甚至å¯èƒ½æ— 法编译。 +然而，使用MMOTMæ ‘å¯èƒ½ä¼šå分令人头疼；它甚至å¯èƒ½æ— 法编译。 下一个周期补ä¸åˆå¹¶çš„主è¦æ ‘是linux-next，由Stephen Rothwell ç»´æŠ¤ã€‚æ ¹æ®è®¾è®¡ linux-next 是下一个åˆå¹¶çª—å£å…³é—åŽä¸»çº¿çš„快照。linux-nextæ ‘åœ¨Linux-kernel å’Œ @@ -228,49 +234,48 @@ Linux-next å·²ç»æˆä¸ºå†…æ ¸å¼€å‘过程ä¸ä¸å¯æˆ–缺的一部分；在一个 Staging æ ‘ ---------- -å†…æ ¸æºä»£ç æ ‘åŒ…å«drivers/staging/directory，其ä¸æœ‰è®¸å¤šé©±åŠ¨ç¨‹åºæˆ–文件系统的 -å目录æ£åœ¨è¢«æ·»åŠ åˆ°å†…æ ¸æ ‘ä¸ã€‚它们然需è¦æ›´å¤šçš„工作的时候å¯ä»¥ä¿ç•™åœ¨ -driver/staging目录ä¸ï¼›ä¸€æ—¦å®Œæˆï¼Œå°±å¯ä»¥å°†å®ƒä»¬ç§»åˆ°å†…æ ¸ä¸ã€‚这是一ç§è·Ÿè¸ªä¸ç¬¦åˆ -Linuxå†…æ ¸ç¼–ç 或质é‡æ ‡å‡†çš„驱动程åºçš„方法，但人们å¯èƒ½å¸Œæœ›ä½¿ç”¨å®ƒä»¬å¹¶è·Ÿè¸ªå¼€å‘。 +å†…æ ¸æºä»£ç æ ‘åŒ…å«drivers/staging/目录，其ä¸æœ‰è®¸å¤šé©±åŠ¨ç¨‹åºæˆ–文件系统的å目录 +æ£åœ¨è¢«æ·»åŠ åˆ°å†…æ ¸æ ‘ä¸ã€‚它们在ä»ç„¶éœ€è¦æ›´å¤šçš„ä¿®æ£çš„时候å¯ä»¥ä¿ç•™åœ¨driver/staging/ +目录ä¸ï¼›ä¸€æ—¦å®Œæˆï¼Œå°±å¯ä»¥å°†å®ƒä»¬ç§»åˆ°å†…æ ¸ä¸ã€‚这是一ç§è·Ÿè¸ªä¸ç¬¦åˆLinuxå†…æ ¸ç¼–ç 或 +è´¨é‡æ ‡å‡†çš„驱动程åºçš„方法，人们å¯èƒ½å¸Œæœ›ä½¿ç”¨å®ƒä»¬å¹¶è·Ÿè¸ªå¼€å‘。 -Greg Kroah Hartman ç›®å‰è´Ÿè´£ç»´æŠ¤staging æ ‘ã€‚ä»éœ€è¦å·¥ä½œçš„驱动程åºå°†å‘é€ç»™ä»–， +Greg Kroah Hartman ç›®å‰è´Ÿè´£ç»´æŠ¤staging æ ‘ã€‚ä»éœ€è¦ä¿®æ£çš„驱动程åºå°†å‘é€ç»™ä»–， æ¯ä¸ªé©±åŠ¨ç¨‹åºåœ¨drivers/staging/ä¸éƒ½æœ‰è‡ªå·±çš„å目录。除了驱动程åºæºæ–‡ä»¶ä¹‹å¤–， -目录ä¸è¿˜åº”该有一个TODO文件。todo文件列出了驱动程åºéœ€è¦æŽ¥å—的挂起的工作， +目录ä¸è¿˜åº”该有一个TODO文件。TODO文件列出了驱动程åºéœ€è¦æŽ¥å—çš„æš‚åœçš„工作， 以åŠé©±åŠ¨ç¨‹åºçš„任何补ä¸éƒ½åº”该抄é€çš„人员列表。当å‰çš„规则è¦æ±‚，staging的驱动 程åºå¿…须至少æ£ç¡®ç¼–译。 -Staging 是一ç§ç›¸å¯¹å®¹æ˜“的方法，å¯ä»¥è®©æ–°çš„驱动程åºè¿›å…¥ä¸»çº¿ï¼Œå¹¸è¿çš„是，他们会 -引起其他开å‘人员的注æ„，并迅速改进。然而，进入staging并ä¸æ˜¯æ•…事的结尾； -stagingä¸æ²¡æœ‰çœ‹åˆ°å¸¸è§„进展的代ç æœ€ç»ˆå°†è¢«åˆ é™¤ã€‚ç»é”€å•†ä¹Ÿå€¾å‘于相对ä¸æ„¿æ„使用 -staging驱动程åºã€‚å› æ¤ï¼Œåœ¨æˆä¸ºä¸€ååˆé€‚的主线驱动的路上，staging å……å…¶é‡åªæ˜¯ -一个åœç•™ã€‚ +Staging 是一ç§è®©æ–°çš„驱动程åºè¿›å…¥ä¸»çº¿çš„相对容易的方法，它们会幸è¿åœ°å¼•èµ·å…¶ä»– +å¼€å‘人员的注æ„，并迅速改进。然而，进入staging并ä¸æ˜¯æ•…事的结尾；stagingä¸ +没有看到常规进展的代ç æœ€ç»ˆå°†è¢«åˆ é™¤ã€‚ç»é”€å•†ä¹Ÿå€¾å‘于相对ä¸æ„¿æ„使用staging驱动 +程åºã€‚å› æ¤ï¼Œåœ¨æˆä¸ºä¸€ä¸ªåˆé€‚的主线驱动的路上，staging 仅是一个ä¸è½¬ç«™ã€‚ 工具 ---- 从上é¢çš„文本å¯ä»¥çœ‹å‡ºï¼Œå†…æ ¸å¼€å‘过程在很大程度上ä¾èµ–于在ä¸åŒæ–¹å‘上èšé›†è¡¥ä¸çš„ èƒ½åŠ›ã€‚å¦‚æžœæ²¡æœ‰é€‚å½“å¼ºå¤§çš„å·¥å…·ï¼Œæ•´ä¸ªç³»ç»Ÿå°†æ— æ³•åœ¨ä»»ä½•åœ°æ–¹æ£å¸¸å·¥ä½œã€‚关于如何使用 -这些工具的教程远远超出了本文档的范围，但是还是有一些指å—的空间。 +这些工具的教程远远超出了本文档的范围，但还是用一点篇幅介ç»ä¸€äº›å…³é”®ç‚¹ã€‚ 到目å‰ä¸ºæ¢ï¼Œå†…æ ¸ç¤¾åŒºä½¿ç”¨çš„ä¸»è¦æºä»£ç 管ç†ç³»ç»Ÿæ˜¯git。Git是在自由软件社区ä¸å¼€å‘ 的许多分布å¼ç‰ˆæœ¬æŽ§åˆ¶ç³»ç»Ÿä¹‹ä¸€ã€‚它éžå¸¸é€‚åˆå†…æ ¸å¼€å‘ï¼Œå› ä¸ºå®ƒåœ¨å¤„ç†å¤§åž‹å˜å‚¨åº“å’Œ -大é‡è¡¥ä¸æ—¶æ€§èƒ½éžå¸¸å¥½ã€‚它还有一个难以å¦ä¹ 和使用的å声，尽管éšç€æ—¶é—´çš„推移它 -å˜å¾—æ›´å¥½äº†ã€‚å¯¹äºŽå†…æ ¸å¼€å‘人员æ¥è¯´ï¼Œå¯¹Gitçš„æŸç§ç†Ÿæ‚‰å‡ 乎是一ç§è¦æ±‚ï¼›å³ä½¿ä»–ä»¬ä¸ -将它用于自己的工作，他们也需è¦Gitæ¥è·Ÿä¸Šå…¶ä»–å¼€å‘人员（以åŠä¸»çº¿ï¼‰æ£åœ¨åšçš„事情。 +大é‡è¡¥ä¸æ—¶æ€§èƒ½éžå¸¸å¥½ã€‚它也以难以å¦ä¹ 和使用而著称，尽管éšç€æ—¶é—´çš„推移它å˜å¾— +æ›´å¥½äº†ã€‚å¯¹äºŽå†…æ ¸å¼€å‘人员æ¥è¯´ï¼Œå¯¹Gitçš„æŸç§ç†Ÿæ‚‰å‡ 乎是一ç§è¦æ±‚ï¼›å³ä½¿ä»–们ä¸å°†å®ƒ +用于自己的工作，他们也需è¦Gitæ¥è·Ÿä¸Šå…¶ä»–å¼€å‘人员（以åŠä¸»çº¿ï¼‰æ£åœ¨åšçš„事情。 -çŽ°åœ¨å‡ ä¹Žæ‰€æœ‰çš„Linuxå‘行版都打包了Git。主页ä½äºŽï¼š +çŽ°åœ¨å‡ ä¹Žæ‰€æœ‰çš„Linuxå‘行版都打包了Git。Git主页ä½äºŽï¼š https://git-scm.com/ -那个页é¢æœ‰æŒ‡å‘文档和教程的指针。 +æ¤é¡µé¢åŒ…å«äº†æ–‡æ¡£å’Œæ•™ç¨‹çš„链接。 -在ä¸ä½¿ç”¨gitçš„å†…æ ¸å¼€å‘人员ä¸ï¼Œæœ€æµè¡Œçš„é€‰æ‹©å‡ ä¹Žè‚¯å®šæ˜¯mercurial： +在ä¸ä½¿ç”¨gitçš„å†…æ ¸å¼€å‘人员ä¸ï¼Œæœ€æµè¡Œçš„é€‰æ‹©å‡ ä¹Žè‚¯å®šæ˜¯Mercurial： http://www.seleric.com/mercurial/ Mercurial与Git共享许多特性，但它æ供了一个界é¢ï¼Œè®¸å¤šäººè§‰å¾—它更易于使用。 -å¦ä¸€ä¸ªå€¼å¾—了解的工具是quilt: +å¦ä¸€ä¸ªå€¼å¾—了解的工具是Quilt: https://savannah.nongnu.org/projects/quilt @@ -282,79 +287,79 @@ Quilt 是一个补ä¸ç®¡ç†ç³»ç»Ÿï¼Œè€Œä¸æ˜¯æºä»£ç 管ç†ç³»ç»Ÿã€‚它ä¸ä¼šéš 邮件列表 -------- -大é‡çš„Linuxå†…æ ¸å¼€å‘工作是通过邮件列表完æˆçš„。如果ä¸åœ¨æŸä¸ªåœ°æ–¹åŠ 入至少一个列表， -就很难æˆä¸ºç¤¾åŒºä¸ä¸€ä¸ªåŠŸèƒ½å®Œå¤‡çš„æˆå‘˜ã€‚但是，Linux邮件列表对开å‘人员æ¥è¯´ä¹Ÿæ˜¯ä¸€ä¸ª -潜在的å±é™©ï¼Œä»–们å¯èƒ½ä¼šè¢«ä¸€å †ç”µå邮件淹没，è¿åLinux列表上使用的约定，或者 -两者兼而有之。 +大é‡çš„Linuxå†…æ ¸å¼€å‘工作是通过邮件列表完æˆçš„。如果ä¸åŠ 入至少一个æŸä¸ªåˆ—表， +就很难æˆä¸ºç¤¾åŒºä¸çš„一个“全功能â€æˆå‘˜ã€‚但是，Linux邮件列表对开å‘人员æ¥è¯´ä¹Ÿæ˜¯ +一个潜在的å±é™©ï¼Œä»–们å¯èƒ½ä¼šè¢«ä¸€å †ç”µå邮件淹没ã€è¿åLinux列表上使用的约定， +或者两者兼而有之。 å¤§å¤šæ•°å†…æ ¸é‚®ä»¶åˆ—è¡¨éƒ½åœ¨vger.kernel.org上è¿è¡Œï¼›ä¸»åˆ—表ä½äºŽï¼š http://vger.kernel.org/vger-lists.html -ä¸è¿‡ï¼Œä¹Ÿæœ‰ä¸€äº›åˆ—表托管在别处；其ä¸ä¸€äº›åˆ—表ä½äºŽlists.redhat.com。 +ä¸è¿‡ï¼Œä¹Ÿæœ‰ä¸€äº›åˆ—表托管在别处；其ä¸ä¸€äº›åˆ—表ä½äºŽ +redhat.com/mailman/listinfo。 -å½“ç„¶ï¼Œå†…æ ¸å¼€å‘çš„æ ¸å¿ƒé‚®ä»¶åˆ—è¡¨æ˜¯linux-kernel。这个åå•æ˜¯ä¸€ä¸ªä»¤äººç”Ÿç•çš„地方； -æ¯å¤©çš„ä¿¡æ¯é‡å¯ä»¥è¾¾åˆ°500æ¡ï¼Œå™ªéŸ³å¾ˆé«˜ï¼Œè°ˆè¯æŠ€æœ¯æ€§å¾ˆå¼ºï¼Œå‚与者并ä¸æ€»æ˜¯è¡¨çŽ°å‡º +å½“ç„¶ï¼Œå†…æ ¸å¼€å‘çš„æ ¸å¿ƒé‚®ä»¶åˆ—è¡¨æ˜¯linux-kernel。这个列表是一个令人生ç•çš„地方： +æ¯å¤©çš„ä¿¡æ¯é‡å¯ä»¥è¾¾åˆ°500æ¡ï¼Œå™ªéŸ³å¾ˆé«˜ï¼Œè°ˆè¯æŠ€æœ¯æ€§å¾ˆå¼ºï¼Œä¸”å‚与者并ä¸æ€»æ˜¯è¡¨çŽ°å‡º 高度的礼貌。但是，没有其他地方å¯ä»¥è®©å†…æ ¸å¼€å‘社区作为一个整体èšé›†åœ¨ä¸€èµ·ï¼› -é¿å…使用æ¤åˆ—表的开å‘人员将错过é‡è¦ä¿¡æ¯ã€‚ +ä¸ä½¿ç”¨æ¤åˆ—表的开å‘人员将错过é‡è¦ä¿¡æ¯ã€‚ -有一些æ示å¯ä»¥å¸®åŠ©åœ¨linux-kernel生å˜ï¼š +以下一些æ示å¯ä»¥å¸®åŠ©åœ¨linux-kernel生å˜ï¼š -- 将邮件转移到å•ç‹¬çš„文件夹，而ä¸æ˜¯ä¸»é‚®ç®±ã€‚我们必须能够æŒç»åœ°å¿½ç•¥æ´ªæµã€‚ +- 将邮件转移到å•ç‹¬çš„文件夹，而ä¸æ˜¯ä¸»é‚®ç®±æ–‡ä»¶å¤¹ã€‚我们必须能够æŒç»åœ°å¿½ç•¥æ´ªæµã€‚ -- ä¸è¦è¯•å›¾è·Ÿè¸ªæ¯ä¸€æ¬¡è°ˆè¯-其他人都ä¸ä¼šã€‚é‡è¦çš„是è¦å¯¹æ„Ÿå…´è¶£çš„主题（尽管请 - 注æ„，长时间的对è¯å¯ä»¥åœ¨ä¸æ›´æ”¹ç”µå邮件主题行的情况下å离原始主题）和å‚与 - 的人进行ç›é€‰ã€‚ +- ä¸è¦è¯•å›¾è·Ÿä¸Šæ¯ä¸€æ¬¡è°ˆè¯â€”â€”æ²¡äººä¼šè¿™æ ·ã€‚é‡è¦çš„是è¦ç›é€‰æ„Ÿå…´è¶£çš„ä¸»é¢˜ï¼ˆä½†è¯·æ³¨æ„ + 长时间的对è¯å¯èƒ½ä¼šå离原æ¥çš„主题，尽管未改å˜ç”µå邮件的主题）和å‚与的人。 -- ä¸è¦æŒ‘事。如果有人试图激起愤怒的å应，忽略他们。 +- ä¸è¦å›žå¤æŒ‘事的人。如果有人试图激起愤怒，请忽略他们。 -- 当å“应Linuxå†…æ ¸ç”µå邮件（或其他列表上的电å邮件）时，请为所有相关人员ä¿ç•™ - cc:header。如果没有强有力的ç†ç”±ï¼ˆå¦‚明确的请求），则ä¸åº”åˆ é™¤æ”¶ä»¶äººã€‚ä¸€å®šè¦ - ç¡®ä¿ä½ è¦å›žå¤çš„人在cc:listä¸ã€‚è¿™ä¸ªæƒ¯ä¾‹ä¹Ÿä½¿ä½ ä¸å¿…在回å¤é‚®ä»¶æ—¶æ˜Žç¡®è¦æ±‚被抄é€ã€‚ +- 当回å¤Linuxå†…æ ¸ç”µå邮件（或其他列表上的电å邮件）时，请为所有相关人员ä¿ç•™ + Cc: 抄é€å¤´ã€‚如果没有确实的ç†ç”±ï¼ˆå¦‚明确的请求），则ä¸åº”åˆ é™¤æ”¶ä»¶äººã€‚ä¸€å®šè¦ + ç¡®ä¿ä½ è¦å›žå¤çš„人在抄é€åˆ—表ä¸ã€‚è¿™ä¸ªæƒ¯ä¾‹ä¹Ÿä½¿ä½ ä¸å¿…在回å¤é‚®ä»¶æ—¶æ˜Žç¡®è¦æ±‚被抄é€ã€‚ -- 在æ出问题之å‰ï¼Œæœç´¢åˆ—表档案（和整个网络）。有些开å‘人员å¯èƒ½ä¼šå¯¹é‚£äº›æ˜¾ç„¶ +- 在æ出问题之å‰ï¼Œæœç´¢åˆ—表å˜æ¡£ï¼ˆå’Œæ•´ä¸ªç½‘络）。有些开å‘人员å¯èƒ½ä¼šå¯¹é‚£äº›æ˜¾ç„¶ 没有完æˆå®¶åºä½œä¸šçš„人感到ä¸è€çƒ¦ã€‚ -- é¿å…è´´é¡¶å¸–ï¼ˆæŠŠä½ çš„ç”æ¡ˆæ”¾åœ¨ä½ è¦å›žå¤çš„引文上é¢çš„åšæ³•ï¼‰ã€‚è¿™ä¼šè®©ä½ çš„å›žç”æ›´éš¾ +- é¿å…顶部回å¤ï¼ˆæŠŠä½ çš„ç”æ¡ˆæ”¾åœ¨ä½ è¦å›žå¤çš„引文上é¢çš„åšæ³•ï¼‰ã€‚è¿™ä¼šè®©ä½ çš„å›žç”æ›´éš¾ ç†è§£ï¼Œå°è±¡ä¹Ÿå¾ˆå·®ã€‚ -- 询问æ£ç¡®çš„邮件列表。linux-kernel å¯èƒ½æ˜¯é€šç”¨çš„讨论点，但它ä¸æ˜¯ä»Žæ‰€æœ‰å系统 - ä¸å¯»æ‰¾å¼€å‘人员的最佳场所。 +- 在æ£ç¡®çš„邮件列表å‘问。linux-kernel å¯èƒ½æ˜¯é€šç”¨çš„讨论场所，但它ä¸æ˜¯å¯»æ‰¾æ‰€æœ‰ + å系统开å‘人员的最佳场所。 -最åŽä¸€ç‚¹â€”—找到æ£ç¡®çš„邮件列表——是开å‘人员出错的常è§åœ°æ–¹ã€‚在Linuxå†…æ ¸ä¸Šæ出与 -ç½‘ç»œç›¸å…³çš„é—®é¢˜çš„äººå‡ ä¹Žè‚¯å®šä¼šæ”¶åˆ°ä¸€ä¸ªç¤¼è²Œçš„å»ºè®®ï¼Œè½¬è€Œåœ¨netdev列表上æ出， -å› ä¸ºè¿™æ˜¯å¤§å¤šæ•°ç½‘ç»œå¼€å‘人员ç»å¸¸å‡ºçŽ°çš„列表。还有其他列表å¯ç”¨äºŽscsi〠-video4linuxã€ideã€filesystemç‰å系统。查找邮件列表的最佳ä½ç½®æ˜¯ä¸Žå†…æ ¸æºä»£ç -一起打包的MAINTAINERS文件。 +最åŽä¸€ç‚¹â€”—找到æ£ç¡®çš„邮件列表——是开å‘人员常出错的地方。在linux-kernel上 +æå‡ºä¸Žç½‘ç»œç›¸å…³çš„é—®é¢˜çš„äººå‡ ä¹Žè‚¯å®šä¼šæ”¶åˆ°ä¸€ä¸ªç¤¼è²Œçš„å»ºè®®ï¼Œè½¬åˆ°netdev列表上æ出， +å› ä¸ºè¿™æ˜¯å¤§å¤šæ•°ç½‘ç»œå¼€å‘人员ç»å¸¸å‡ºçŽ°çš„列表。还有其他列表å¯ç”¨äºŽscsiã€video4linux〠+ideã€filesystemç‰å系统。查找邮件列表的最佳ä½ç½®æ˜¯ä¸Žå†…æ ¸æºä»£ç 一起打包的 +MAINTAINERS文件。 å¼€å§‹å†…æ ¸å¼€å‘ ------------ -å…³äºŽå¦‚ä½•å¼€å§‹å†…æ ¸å¼€å‘过程的问题很常è§â€”—æ¥è‡ªä¸ªäººå’Œå…¬å¸ã€‚åŒæ ·å¸¸è§çš„是错误，这 -使得关系的开始比必须的更困难。 +å…³äºŽå¦‚ä½•å¼€å§‹å†…æ ¸å¼€å‘过程的问题很常è§â€”—个人和公å¸çš†ç„¶ã€‚åŒæ ·å¸¸è§çš„是失误，这 +使得关系的开始比本应的更困难。 å…¬å¸é€šå¸¸å¸Œæœ›è˜è¯·çŸ¥åçš„å¼€å‘人员æ¥å¯åŠ¨å¼€å‘团队。实际上，这是一ç§æœ‰æ•ˆçš„技术。 -但它也往往是昂贵的，而且没有增长ç»éªŒä¸°å¯Œçš„å†…æ ¸å¼€å‘人员储备。考虑到时间的 -投入，å¯ä»¥è®©å†…部开å‘äººå‘˜åŠ å¿«Linuxå†…æ ¸çš„å¼€å‘速度。花这个时间å¯ä»¥è®©é›‡ä¸»æ‹¥æœ‰ -ä¸€æ‰¹äº†è§£å†…æ ¸å’Œå…¬å¸çš„å¼€å‘人员，他们也å¯ä»¥å¸®åŠ©åŸ¹è®å…¶ä»–人。从ä¸æœŸæ¥çœ‹ï¼Œè¿™å¾€å¾€ -是更有利å¯å›¾çš„方法。 +ä½†å®ƒä¹Ÿå¾€å¾€æ˜¯æ˜‚è´µçš„ï¼Œè€Œä¸”å¯¹å¢žåŠ æœ‰ç»éªŒçš„å†…æ ¸å¼€å‘人员的数é‡æ²¡æœ‰å¤šå¤§å¸®åŠ©ã€‚考 +虑到时间投入，å¯ä»¥è®©å†…部开å‘äººå‘˜åŠ å¿«Linuxå†…æ ¸çš„å¼€å‘速度。利用这段时间å¯ä»¥ +è®©é›‡ä¸»æ‹¥æœ‰ä¸€æ‰¹æ—¢äº†è§£å†…æ ¸åˆäº†è§£å…¬å¸çš„å¼€å‘人员，还å¯ä»¥å¸®åŠ©åŸ¹è®å…¶ä»–人。从ä¸æœŸ +æ¥çœ‹ï¼Œè¿™é€šå¸¸æ˜¯æ›´æœ‰åˆ©å¯å›¾çš„方法。 å¯ä»¥ç†è§£çš„是，å•ä¸ªå¼€å‘人员往往对起æ¥æ„Ÿåˆ°èŒ«ç„¶ã€‚从一个大型项目开始å¯èƒ½ä¼šå¾ˆ -å“人；人们往往想先用一些较å°çš„东西æ¥æµ‹è¯•æ°´åŸŸã€‚这是一些开å‘人员开始创建修补 -拼写错误或轻微编ç é£Žæ ¼é—®é¢˜çš„è¡¥ä¸çš„地方。ä¸å¹¸çš„æ˜¯ï¼Œè¿™æ ·çš„è¡¥ä¸ä¼šäº§ç”Ÿä¸€å®šç¨‹åº¦ -的噪音，这会分散整个开å‘社区的注æ„åŠ›ï¼Œå› æ¤ï¼Œè¶Šæ¥è¶Šå¤šçš„人看ä¸èµ·å®ƒä»¬ã€‚å¸Œæœ›å‘ -社区介ç»è‡ªå·±çš„æ–°å¼€å‘äººå‘˜å°†æ— æ³•é€šè¿‡è¿™äº›æ–¹å¼èŽ·å¾—他们想è¦çš„é‚£ç§æŽ¥å¾…。 +å“人；人们往往想先用一些较å°çš„东西æ¥è¯•è¯•æ°´ã€‚ç”±æ¤ï¼Œä¸€äº›å¼€å‘人员开始创建修补 +拼写错误或轻微编ç é£Žæ ¼é—®é¢˜çš„è¡¥ä¸ã€‚ä¸å¹¸çš„æ˜¯ï¼Œè¿™æ ·çš„è¡¥ä¸ä¼šäº§ç”Ÿä¸€å®šç¨‹åº¦çš„噪音， +这会分散整个开å‘社区的注æ„åŠ›ï¼Œå› æ¤ï¼Œå®ƒä»¬è¶Šæ¥è¶Šè¢«äººä¸çœ‹é‡ã€‚希望å‘ç¤¾åŒºä»‹ç» +自己的新开å‘äººå‘˜å°†æ— æ³•é€šè¿‡è¿™äº›æ–¹å¼èŽ·å¾—他们期待的åå“。 -Andrew Morton ä¸ºæœ‰æŠ±è´Ÿçš„å†…æ ¸å¼€å‘人员æ供了这个建议 +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 index b8676aec6005..de53dd12e911 100644 --- a/Documentation/translations/zh_CN/process/3.Early-stage.rst +++ b/Documentation/translations/zh_CN/process/3.Early-stage.rst @@ -1,7 +1,14 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/3.Early-stage.rst <development_early_stage>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _cn_development_early_stage: @@ -9,45 +16,45 @@ ======== 当考虑一个Linuxå†…æ ¸å¼€å‘项目时，很å¯èƒ½ä¼šç›´æŽ¥è·³è¿›åŽ»å¼€å§‹ç¼–ç 。然而，与任何é‡è¦ -çš„é¡¹ç›®ä¸€æ ·ï¼ŒæˆåŠŸçš„许多基础最好是在第一行代ç 编写之å‰å°±åšå¥½äº†ã€‚在早期计划和 -沟通ä¸èŠ±è´¹ä¸€äº›æ—¶é—´å¯ä»¥èŠ‚çœæ›´å¤šçš„时间。 +çš„é¡¹ç›®ä¸€æ ·ï¼Œè®¸å¤šæˆåŠŸçš„基础最好是在第一行代ç 编写之å‰å°±æ‰“下。在早期计划和 +沟通ä¸èŠ±è´¹ä¸€äº›æ—¶é—´å¯ä»¥åœ¨ä¹‹åŽèŠ‚çœæ›´å¤šçš„时间。 -详述问题 +æžæ¸…问题 -------- -ä¸Žä»»ä½•å·¥ç¨‹é¡¹ç›®ä¸€æ ·ï¼ŒæˆåŠŸçš„å†…æ ¸å¢žå¼ºä»Žè¦è§£å†³çš„问题的清晰æ述开始。在æŸäº›æƒ…况 -下，这个æ¥éª¤å¾ˆå®¹æ˜“：例如，当æŸä¸ªç‰¹å®šç¡¬ä»¶éœ€è¦é©±åŠ¨ç¨‹åºæ—¶ã€‚ä¸è¿‡ï¼Œåœ¨å…¶ä»–æ–¹é¢ï¼Œ -将实际问题与建议的解决方案混淆是很有诱惑力的，这å¯èƒ½ä¼šå¯¼è‡´å›°éš¾ã€‚ +ä¸Žä»»ä½•å·¥ç¨‹é¡¹ç›®ä¸€æ ·ï¼ŒæˆåŠŸçš„å†…æ ¸æ”¹å–„ä»Žæ¸…æ™°æè¿°è¦è§£å†³çš„问题开始。在æŸäº›æƒ…况 +下，这个æ¥éª¤å¾ˆå®¹æ˜“：例如当æŸä¸ªç‰¹å®šç¡¬ä»¶éœ€è¦é©±åŠ¨ç¨‹åºæ—¶ã€‚ä¸è¿‡ï¼Œåœ¨å…¶ä»–情况下， +很容易将实际问题与建议的解决方案混在一起，这å¯èƒ½ä¼šå¯¼è‡´éº»çƒ¦ã€‚ -举个例åï¼šå‡ å¹´å‰ï¼Œä½¿ç”¨Linux音频的开å‘人员寻求一ç§æ–¹æ³•æ¥è¿è¡Œåº”用程åºï¼Œè€Œä¸å› -ç³»ç»Ÿå»¶è¿Ÿè¿‡å¤§è€Œå¯¼è‡´é€€å‡ºæˆ–å…¶ä»–å·¥ä»¶ã€‚ä»–ä»¬å¾—åˆ°çš„è§£å†³æ–¹æ¡ˆæ˜¯ä¸€ä¸ªå†…æ ¸æ¨¡å—，旨在连 -接到Linux安全模å—（LSM）框架ä¸ï¼›è¿™ä¸ªæ¨¡å—å¯ä»¥é…置为å…许特定的应用程åºè®¿é—® -实时调度程åºã€‚这个模å—被实现并å‘é€åˆ°Linuxå†…æ ¸é‚®ä»¶åˆ—è¡¨ï¼Œåœ¨é‚£é‡Œå®ƒç«‹å³é‡åˆ°é—®é¢˜ã€‚ +举个例åï¼šå‡ å¹´å‰ï¼ŒLinux音频的开å‘人员寻求一ç§æ–¹æ³•æ¥è¿è¡Œåº”用程åºï¼Œè€Œä¸ä¼šå› +系统延迟过大而导致退出或其他问题。他们得到的解决方案是一个连接到Linux安全 +模å—（LSM）框架ä¸çš„å†…æ ¸æ¨¡å—；这个模å—å¯ä»¥é…置为å…许特定的应用程åºè®¿é—®å®žæ—¶ +调度程åºã€‚这个模å—被实现并å‘到linux-kernel邮件列表，在那里它立å³é‡åˆ°äº†éº»çƒ¦ã€‚ 对于音频开å‘人员æ¥è¯´ï¼Œè¿™ä¸ªå®‰å…¨æ¨¡å—足以解决他们当å‰çš„问题。但是，对于更广泛的 å†…æ ¸ç¤¾åŒºæ¥è¯´ï¼Œè¿™è¢«è§†ä¸ºå¯¹LSM框架的滥用（LSM框架并ä¸æ‰“算授予他们原本ä¸å…·å¤‡çš„ 进程特æƒï¼‰ï¼Œå¹¶å¯¹ç³»ç»Ÿç¨³å®šæ€§é€ æˆé£Žé™©ã€‚他们首选的解决方案包括çŸæœŸçš„通过rlimit 机制进行实时调度访问，以åŠé•¿æœŸçš„å‡å°‘延迟的工作。 -然而，音频社区看ä¸åˆ°ä»–们实施的特定解决方案的过去；他们ä¸æ„¿æ„接å—替代方案。 +ç„¶è€Œï¼ŒéŸ³é¢‘ç¤¾åŒºæ— æ³•è¶…è¶Šä»–ä»¬å®žæ–½çš„ç‰¹å®šè§£å†³æ–¹æ¡ˆæ¥çœ‹é—®é¢˜ï¼›ä»–们ä¸æ„¿æ„接å—替代方案。 ç”±æ¤äº§ç”Ÿçš„分æ§ä½¿è¿™äº›å¼€å‘äººå‘˜å¯¹æ•´ä¸ªå†…æ ¸å¼€å‘过程感到失望；其ä¸ä¸€ä¸ªå¼€å‘人员返回 -到音频列表并å‘布了以下内容： +到audio列表并å‘布了以下内容： - 有很多éžå¸¸å¥½çš„Linuxå†…æ ¸å¼€å‘人员，但他们往往会被一群傲慢的傻瓜所压倒。 - 试图å‘è¿™äº›äººä¼ è¾¾ç”¨æˆ·éœ€æ±‚æ˜¯æµªè´¹æ—¶é—´ã€‚ä»–ä»¬å¤ªâ€œèªæ˜Žâ€äº†ï¼Œæ ¹æœ¬å¬ä¸åˆ°å°‘数人 - çš„è¯ã€‚ + 有很多éžå¸¸å¥½çš„Linuxå†…æ ¸å¼€å‘人员，但他们往往会被一群傲慢的傻瓜所压倒。 + 试图å‘è¿™äº›äººä¼ è¾¾ç”¨æˆ·éœ€æ±‚æ˜¯æµªè´¹æ—¶é—´ã€‚ä»–ä»¬å¤ªâ€œèªæ˜Žâ€äº†ï¼Œæ ¹æœ¬å¬ä¸åˆ°å°‘æ•° + 人的è¯ã€‚ （http://lwn.net/articles/131776/） -实际情况ä¸åŒï¼›ä¸Žç‰¹å®šæ¨¡å—ç›¸æ¯”ï¼Œå†…æ ¸å¼€å‘人员更关心系统稳定性ã€é•¿æœŸç»´æŠ¤ä»¥åŠæ‰¾åˆ° -æ£ç¡®çš„问题解决方案。这个故事的寓æ„是把é‡ç‚¹æ”¾åœ¨é—®é¢˜ä¸Šâ€”—而ä¸æ˜¯å…·ä½“的解决方案 -上——并在投入创建代ç 之å‰ä¸Žå¼€å‘社区讨论这个问题。 +实际情况å´æ˜¯ä¸åŒçš„；与特定模å—ç›¸æ¯”ï¼Œå†…æ ¸å¼€å‘人员更关心系统稳定性ã€é•¿æœŸç»´æŠ¤ +以åŠæ‰¾åˆ°é—®é¢˜çš„æ£ç¡®è§£å†³æ–¹æ¡ˆã€‚这个故事的寓æ„是把é‡ç‚¹æ”¾åœ¨é—®é¢˜ä¸Šâ€”—而ä¸æ˜¯å…·ä½“çš„ +解决方案上——并在开始编写代ç 之å‰ä¸Žå¼€å‘社区讨论这个问题。 å› æ¤ï¼Œåœ¨è€ƒè™‘ä¸€ä¸ªå†…æ ¸å¼€å‘项目时，我们应该得到一组简çŸé—®é¢˜çš„ç”案： - - 究竟需è¦è§£å†³çš„问题是什么？ + - 需è¦è§£å†³çš„问题究竟是什么？ - - å—æ¤é—®é¢˜å½±å“的用户是è°ï¼Ÿè§£å†³æ–¹æ¡ˆåº”该解决哪些用例？ + - å—æ¤é—®é¢˜å½±å“的用户有哪些？解决方案应该解决哪些使用案例？ - å†…æ ¸çŽ°åœ¨ä¸ºä½•æ²¡èƒ½è§£å†³è¿™ä¸ªé—®é¢˜ï¼Ÿ @@ -62,100 +69,100 @@ - 很å¯èƒ½é—®é¢˜æ˜¯ç”±å†…æ ¸ä»¥æ‚¨ä¸ç†è§£çš„æ–¹å¼è§£å†³çš„。Linuxå†…æ ¸å¾ˆå¤§ï¼Œå…·æœ‰è®¸å¤šä¸æ˜Žæ˜¾ 的特性和功能。并ä¸æ˜¯æ‰€æœ‰çš„å†…æ ¸åŠŸèƒ½éƒ½åƒäººä»¬æ‰€å¸Œæœ›çš„é‚£æ ·æœ‰æ–‡æ¡£è®°å½•ï¼Œè€Œä¸”å¾ˆ - 容易é—æ¼ä¸€äº›ä¸œè¥¿ã€‚ä½ çš„ä½œè€…å‘出了一个完整的驱动程åºï¼Œå¤åˆ¶äº†ä¸€ä¸ªæ–°ä½œè€…ä¸ - 知é“的现有驱动程åºã€‚é‡æ–°è®¾è®¡çŽ°æœ‰è½®å的代ç ä¸ä»…浪费，而且ä¸ä¼šè¢«æŽ¥å—到主线 + 容易é—æ¼ä¸€äº›ä¸œè¥¿ã€‚æŸä½œè€…å‘布了一个完整的驱动程åºï¼Œé‡å¤äº†ä¸€ä¸ªå…¶ä¸ + 知é“的现有驱动程åºã€‚é‡æ–°å‘明现有轮å的代ç ä¸ä»…浪费，而且ä¸ä¼šè¢«æŽ¥å—到主线 å†…æ ¸ä¸ã€‚ - - 建议的解决方案ä¸å¯èƒ½æœ‰ä¸€äº›å…ƒç´ ä¸é€‚用于主线åˆå¹¶ã€‚在编写代ç 之å‰ï¼Œæœ€å¥½å…ˆ - äº†è§£è¿™æ ·çš„é—®é¢˜ã€‚ + - 建议的解决方案ä¸å¯èƒ½æœ‰ä¸€äº›è¦ç´ ä¸é€‚åˆå¹¶å…¥ä¸»çº¿ã€‚在编写代ç 之å‰ï¼Œæœ€å¥½å…ˆäº†è§£ + è¿™æ ·çš„é—®é¢˜ã€‚ - 其他开å‘人员完全有å¯èƒ½è€ƒè™‘过这个问题；他们å¯èƒ½æœ‰æ›´å¥½çš„解决方案的想法，并且 å¯èƒ½æ„¿æ„帮助创建这个解决方案。 åœ¨å†…æ ¸å¼€å‘社区的多年ç»éªŒç»™äº†æˆ‘们一个明确的教è®ï¼šé—门设计和开å‘çš„å†…æ ¸ä»£ç 总是 有一些问题，这些问题åªæœ‰åœ¨ä»£ç å‘布到社区ä¸æ—¶æ‰ä¼šè¢«å‘现。有时这些问题很严é‡ï¼Œ -需è¦æ•°æœˆæˆ–数年的努力æ‰èƒ½ä½¿ä»£ç è¾¾åˆ°å†…æ ¸ç¤¾åŒºçš„æ ‡å‡†ã€‚ä¸€äº›ä¾‹å包括： +需è¦æ•°æœˆæˆ–数年的努力æ‰èƒ½ä½¿ä»£ç è¾¾åˆ°å†…æ ¸ç¤¾åŒºçš„æ ‡å‡†ã€‚ä¾‹å¦‚ï¼š - 设计并实现了å•å¤„ç†å™¨ç³»ç»Ÿçš„DeviceScapeç½‘ç»œæ ˆã€‚åªæœ‰ä½¿å…¶é€‚åˆäºŽå¤šå¤„ç†å™¨ç³»ç»Ÿï¼Œ - æ‰èƒ½å°†å…¶åˆå¹¶åˆ°ä¸»çº¿ä¸ã€‚在代ç ä¸æ”¹è£…é”ç‰ç‰æ˜¯ä¸€é¡¹å›°éš¾çš„ä»»åŠ¡ï¼›å› æ¤ï¼Œè¿™æ®µä»£ç + æ‰èƒ½å°†å…¶åˆå¹¶åˆ°ä¸»çº¿ä¸ã€‚在代ç ä¸ä¿®æ”¹é”ç‰ç‰æ˜¯ä¸€é¡¹å›°éš¾çš„ä»»åŠ¡ï¼›å› æ¤ï¼Œè¿™æ®µä»£ç （现在称为mac80211）的åˆå¹¶è¢«æŽ¨è¿Ÿäº†ä¸€å¹´å¤šã€‚ - Reiser4文件系统包å«è®¸å¤šåŠŸèƒ½ï¼Œæ ¸å¿ƒå†…æ ¸å¼€å‘人员认为这些功能应该在虚拟文件 系统层ä¸å®žçŽ°ã€‚它还包括一些特性，这些特性在ä¸å°†ç³»ç»Ÿæš´éœ²äºŽç”¨æˆ·å¼•èµ·çš„æ»é”çš„ - 情况下是ä¸å®¹æ˜“实现的。这些问题的最新å‘现——以åŠå¯¹å…¶ä¸ä¸€äº›é—®é¢˜çš„æ‹’ç»â€”â€”å·²ç» - 导致Reiser4è¿œç¦»äº†ä¸»çº¿å†…æ ¸ã€‚ + 情况下是ä¸å®¹æ˜“实现的。这些问题过迟å‘现——以åŠæ‹’ç»å¤„ç†å…¶ä¸ä¸€äº›é—®é¢˜â€”â€”å·²ç» + 导致Reiser4ç½®èº«ä¸»çº¿å†…æ ¸ä¹‹å¤–ã€‚ - Apparmor安全模å—以被认为ä¸å®‰å…¨å’Œä¸å¯é çš„æ–¹å¼ä½¿ç”¨å†…部虚拟文件系统数æ®ç»“构。 - è¿™ç§æ‹…心（包括其他）使Apparmor多年ä¸åœ¨ä¸»çº¿ä¸Šã€‚ + è¿™ç§æ‹…心（包括其他）使Apparmor多年æ¥æ— 法进入主线。 -在æ¯ä¸€ç§æƒ…å†µä¸‹ï¼Œé€šè¿‡ä¸Žå†…æ ¸å¼€å‘人员的早期讨论，å¯ä»¥é¿å…大é‡çš„痛苦和é¢å¤–的工作。 +åœ¨è¿™äº›æƒ…å†µä¸‹ï¼Œä¸Žå†…æ ¸å¼€å‘人员的早期讨论，å¯ä»¥é¿å…大é‡çš„痛苦和é¢å¤–的工作。 -找è°äº¤æµ --------- +找è°äº¤æµï¼Ÿ +---------- 当开å‘人员决定公开他们的计划时，下一个问题是：我们从哪里开始？ç”案是找到æ£ç¡® 的邮件列表和æ£ç¡®çš„维护者。对于邮件列表，最好的方法是在维护者(MAINTAINERS)文件 -ä¸æŸ¥æ‰¾è¦å‘布的相关ä½ç½®ã€‚如果有一个åˆé€‚çš„å系统列表，那么å‘布它通常比在Linux -å†…æ ¸ä¸Šå‘布更å¯å–；您更有å¯èƒ½æŽ¥è§¦åˆ°åœ¨ç›¸å…³å系统ä¸å…·æœ‰ä¸“业知识的开å‘人员，并且 -环境å¯èƒ½å…·æ”¯æŒæ€§ã€‚ +ä¸æŸ¥æ‰¾è¦å‘布的相关ä½ç½®ã€‚如果有一个åˆé€‚çš„å系统列表，那么其上å‘布通常比在 +linux-kernel上å‘布更å¯å–；您更有å¯èƒ½æŽ¥è§¦åˆ°åœ¨ç›¸å…³å系统ä¸å…·æœ‰ä¸“ä¸šçŸ¥è¯†çš„å¼€å‘ +人员，并且环境å¯èƒ½å…·æ”¯æŒæ€§ã€‚ -找到维护人员å¯èƒ½ä¼šæœ‰ç‚¹å›°éš¾ã€‚åŒæ ·ï¼Œç»´æŠ¤è€…文件是开始的地方。但是，该文件往往ä¸æ€» -是最新的，并且并éžæ‰€æœ‰å系统都在那里表示。实际上，维护者文件ä¸åˆ—出的人员å¯èƒ½ +找到维护人员å¯èƒ½ä¼šæœ‰ç‚¹å›°éš¾ã€‚åŒæ ·ï¼Œç»´æŠ¤è€…æ–‡ä»¶æ˜¯å¼€å§‹çš„åœ°æ–¹ã€‚ä½†æ˜¯ï¼Œè¯¥æ–‡ä»¶å¾€å¾€ä¸ +是最新的，并且并éžæ‰€æœ‰å系统都在那里显示。实际上，维护者文件ä¸åˆ—出的人员å¯èƒ½ ä¸æ˜¯å½“å‰å®žé™…æ‹…ä»»è¯¥è§’è‰²çš„äººå‘˜ã€‚å› æ¤ï¼Œå½“对è”ç³»è°æœ‰ç–‘问时，一个有用的技巧是使用 -git（尤其是“git-logâ€ï¼‰æŸ¥çœ‹æ„Ÿå…´è¶£çš„å系统ä¸å½“å‰æ´»åŠ¨çš„用户。看看è°åœ¨å†™è¡¥ä¸ï¼Œ -如果有人的è¯ï¼Œè°ä¼šåœ¨è¿™äº›è¡¥ä¸ä¸ŠåŠ 上用线ç¾å的。这些人将是帮助新开å‘项目的最佳 -人选。 +git（尤其是“git-logâ€ï¼‰æŸ¥çœ‹æ„Ÿå…´è¶£çš„å系统ä¸å½“å‰æ´»åŠ¨çš„用户。看看è°åœ¨å†™è¡¥ä¸ã€ +è°ä¼šåœ¨è¿™äº›è¡¥ä¸ä¸ŠåŠ 上Signed-off-byè¡Œç¾å（如有）。这些人将是帮助新开å‘项目的 +最佳人选。 -找到åˆé€‚的维护者的任务有时是éžå¸¸å…·æœ‰æŒ‘æˆ˜æ€§çš„ï¼Œä»¥è‡³äºŽå†…æ ¸å¼€å‘äººå‘˜æ·»åŠ äº†ä¸€ä¸ª -脚本æ¥ç®€åŒ–过程： +找到åˆé€‚的维护者有时是éžå¸¸å…·æœ‰æŒ‘æˆ˜æ€§çš„ï¼Œä»¥è‡³äºŽå†…æ ¸å¼€å‘äººå‘˜æ·»åŠ äº†ä¸€ä¸ªè„šæœ¬æ¥ +简化这个过程： :: .../scripts/get_maintainer.pl -当给定“-fâ€é€‰é¡¹æ—¶ï¼Œæ¤è„šæœ¬å°†è¿”回给定文件或目录的当å‰ç»´æŠ¤è€…ã€‚å¦‚æžœåœ¨å‘½ä»¤è¡Œä¸Šä¼ é€’ -了一个补ä¸ï¼Œå®ƒå°†åˆ—出å¯èƒ½æŽ¥æ”¶è¡¥ä¸å‰¯æœ¬çš„维护人员。有许多选项å¯ä»¥è°ƒèŠ‚ -get_maintainer.plæœç´¢ç»´æŠ¤è€…的难易程度；请å°å¿ƒä½¿ç”¨æ›´å…·æ”»å‡»æ€§çš„é€‰é¡¹ï¼Œå› ä¸ºæœ€ç»ˆ +当给定“-fâ€é€‰é¡¹æ—¶ï¼Œæ¤è„šæœ¬å°†è¿”回指定文件或目录的当å‰ç»´æŠ¤è€…。如果在命令行上 +给出了一个补ä¸ï¼Œå®ƒå°†åˆ—出å¯èƒ½æŽ¥æ”¶è¡¥ä¸å‰¯æœ¬çš„维护人员。有许多选项å¯ä»¥è°ƒèŠ‚ +get_maintainer.plæœç´¢ç»´æŠ¤è€…çš„ä¸¥æ ¼ç¨‹åº¦ï¼›è¯·å°å¿ƒä½¿ç”¨æ›´æ¿€è¿›çš„é€‰é¡¹ï¼Œå› ä¸ºæœ€ç»ˆç»“æžœ å¯èƒ½ä¼šåŒ…括对您æ£åœ¨ä¿®æ”¹çš„代ç 没有真æ£å…´è¶£çš„å¼€å‘人员。 -如果所有其他方法都失败了，那么与Andrew Morton交谈å¯ä»¥æˆä¸ºä¸€ç§æœ‰æ•ˆçš„方法æ¥è·Ÿè¸ª -特定代ç 段的维护人员。 +如果所有其他方法都失败了，那么与Andrew Morton交æµæ˜¯è·Ÿè¸ªç‰¹å®šä»£ç 段维护人员 +的一ç§æœ‰æ•ˆæ–¹æ³•ã€‚ 何时邮寄？ ---------- -如果å¯èƒ½çš„è¯ï¼Œåœ¨æ—©æœŸé˜¶æ®µå‘å¸ƒä½ çš„è®¡åˆ’åªä¼šæœ‰å¸®åŠ©ã€‚æè¿°æ£åœ¨è§£å†³çš„问题以åŠå·²ç» +如果å¯èƒ½çš„è¯ï¼Œåœ¨æ—©æœŸé˜¶æ®µå‘å¸ƒä½ çš„è®¡åˆ’åªä¼šæ›´æœ‰å¸®åŠ©ã€‚æè¿°æ£åœ¨è§£å†³çš„问题以åŠå·²ç» 制定的关于如何实施的任何计划。您å¯ä»¥æ供的任何信æ¯éƒ½å¯ä»¥å¸®åŠ©å¼€å‘社区为项目 æ供有用的输入。 -在这个阶段å¯èƒ½å‘生的一件令人沮丧的事情ä¸æ˜¯æ•Œå¯¹çš„ååº”ï¼Œè€Œæ˜¯å¾ˆå°‘æˆ–æ ¹æœ¬æ²¡æœ‰ -å应。å¯æ‚²çš„事实是：（1ï¼‰å†…æ ¸å¼€å‘人员往往很忙；（2）ä¸ç¼ºå°‘有å®ä¼Ÿè®¡åˆ’和很少 -代ç （甚至代ç å‰æ™¯ï¼‰æ”¯æŒä»–们的人；（3）没有人有义务审查或评论别人å‘表的 -想法。除æ¤ä¹‹å¤–，高级设计常常éšè—一些问题，这些问题åªæœ‰åœ¨æœ‰äººçœŸæ£å°è¯•å®žçŽ° -这些设计时æ‰ä¼šè¢«å‘çŽ°ï¼›å› æ¤ï¼Œå†…æ ¸å¼€å‘人员å®æ„¿çœ‹åˆ°ä»£ç 。 +在这个阶段å¯èƒ½å‘生的一件令人沮丧的事情ä¸æ˜¯å¾—到å对æ„è§ï¼Œè€Œæ˜¯å¾ˆå°‘æˆ–æ ¹æœ¬æ²¡æœ‰ +å馈。令人伤心的事实是：（1ï¼‰å†…æ ¸å¼€å‘人员往往很忙；（2）ä¸ç¼ºå°‘有å®ä¼Ÿè®¡åˆ’但 +代ç （甚至代ç 设想）很少的人去支æŒä»–们；（3）没有人有义务审查或评论别人å‘表 +的想法。除æ¤ä¹‹å¤–，高层级的设计常常éšè—ç€ä¸€äº›é—®é¢˜ï¼Œè¿™äº›é—®é¢˜åªæœ‰åœ¨æœ‰äººçœŸæ£å°è¯• +实现这些设计时æ‰ä¼šè¢«å‘çŽ°ï¼›å› æ¤ï¼Œå†…æ ¸å¼€å‘人员å®æ„¿çœ‹åˆ°ä»£ç 。 -如果å‘表评论的请求在评论的方å¼ä¸Šæ²¡æœ‰ä»€ä¹ˆæ•ˆæžœï¼Œä¸è¦å‡è®¾è¿™æ„味ç€å¯¹é¡¹ç›®æ²¡æœ‰ -兴趣。ä¸å¹¸çš„æ˜¯ï¼Œä½ ä¹Ÿä¸èƒ½å‡è®¾ä½ 的想法没有问题。在这ç§æƒ…况下，最好的åšæ³•æ˜¯ -继ç»è¿›è¡Œï¼ŒæŠŠä½ 的进展éšæ—¶é€šçŸ¥ç¤¾åŒºã€‚ +如果å‘布请求评论（RFC）并没得到什么有用的评论，ä¸è¦ä»¥ä¸ºè¿™æ„味ç€æ— 人对æ¤é¡¹ç›® +有兴趣，åŒæ—¶ä½ 也ä¸èƒ½å‡è®¾ä½ 的想法没有问题。在这ç§æƒ…况下，最好的åšæ³•æ˜¯ç»§ç»è¿› +è¡Œï¼ŒæŠŠä½ çš„è¿›å±•éšæ—¶é€šçŸ¥ç¤¾åŒºã€‚ èŽ·å¾—å®˜æ–¹è®¤å¯ ----------------------- -如果您的工作是在公å¸çŽ¯å¢ƒä¸å®Œæˆçš„，就åƒå¤§å¤šæ•°Linuxå†…æ ¸å·¥ä½œä¸€æ ·ï¼Œæ˜¾ç„¶ï¼Œåœ¨æ‚¨å°† -å…¬å¸çš„计划或代ç å‘布到公共邮件列表之å‰ï¼Œå¿…须获得适当授æƒçš„ç»ç†çš„许å¯ã€‚å‘布 -ä¸ç¡®å®šæ˜¯å¦å…¼å®¹GPL的代ç å¯èƒ½æ˜¯æœ‰ç‰¹åˆ«é—®é¢˜çš„；公å¸çš„管ç†å±‚和法律人员越早能够就 -å‘å¸ƒå†…æ ¸å¼€å‘项目达æˆä¸€è‡´ï¼Œå¯¹å‚与的æ¯ä¸ªäººéƒ½è¶Šå¥½ã€‚ +如果您的工作是在公å¸çŽ¯å¢ƒä¸å®Œæˆçš„，就åƒå¤§å¤šæ•°Linuxå†…æ ¸å·¥ä½œä¸€æ ·ï¼›æ˜¾ç„¶ï¼Œåœ¨æ‚¨å°† +å…¬å¸çš„计划或代ç å‘布到公共邮件列表之å‰ï¼Œå¿…须获得有适当æƒåˆ©ç»ç†çš„许å¯ã€‚å‘布 +ä¸ç¡®å®šæ˜¯å¦å…¼å®¹GPL的代ç 尤其会带æ¥é—®é¢˜ï¼›å…¬å¸çš„管ç†å±‚和法律人员越早能够就å‘布 +å†…æ ¸å¼€å‘项目达æˆä¸€è‡´ï¼Œå¯¹å‚与的æ¯ä¸ªäººéƒ½è¶Šå¥½ã€‚ 一些读者å¯èƒ½ä¼šè®¤ä¸ºä»–ä»¬çš„æ ¸å¿ƒå·¥ä½œæ˜¯ä¸ºäº†æ”¯æŒè¿˜æ²¡æœ‰æ£å¼æ‰¿è®¤å˜åœ¨çš„产å“。将雇主 的计划公布在公共邮件列表上å¯èƒ½ä¸æ˜¯ä¸€ä¸ªå¯è¡Œçš„选择。在这ç§æƒ…况下，有必è¦è€ƒè™‘ ä¿å¯†æ˜¯å¦çœŸçš„是必è¦çš„；通常ä¸éœ€è¦æŠŠå¼€å‘计划关在门内。 -也就是说，有些情况下，一家公å¸åœ¨å¼€å‘过程的早期就ä¸èƒ½åˆæ³•åœ°æŠ«éœ²å…¶è®¡åˆ’。拥有 -ç»éªŒä¸°å¯Œçš„å†…æ ¸å¼€å‘人员的公å¸å¯ä»¥é€‰æ‹©ä»¥å¼€çŽ¯çš„æ–¹å¼è¿›è¡Œï¼Œå‰æ是他们以åŽèƒ½å¤Ÿé¿å… +的确，有些情况下一家公å¸åœ¨å¼€å‘è¿‡ç¨‹çš„æ—©æœŸæ— æ³•åˆæ³•åœ°æŠ«éœ²å…¶è®¡åˆ’。拥有ç»éªŒä¸°å¯Œ +çš„å†…æ ¸å¼€å‘人员的公å¸å¯èƒ½é€‰æ‹©ä»¥å¼€çŽ¯çš„æ–¹å¼è¿›è¡Œå¼€å‘，å‰æ是他们以åŽèƒ½å¤Ÿé¿å… 严é‡çš„集æˆé—®é¢˜ã€‚对于没有这ç§å†…部专业知识的公å¸ï¼Œæœ€å¥½çš„选择往往是è˜è¯·å¤–部 -å¼€å‘å•†æ ¹æ®ä¿å¯†å议审查计划。Linux基金会è¿è¡Œäº†ä¸€ä¸ªNDA程åºï¼Œæ—¨åœ¨å¸®åŠ©è§£å†³è¿™ç§ -情况； +å¼€å‘è€…æ ¹æ®ä¿å¯†å议审查计划。Linux基金会è¿è¡Œäº†ä¸€ä¸ªNDA程åºï¼Œæ—¨åœ¨å¸®åŠ©è§£å†³è¿™ç§ +情况；更多信æ¯å‚è§ï¼š - http://www.linuxfoundation.org/en/NDA_program + http://www.linuxfoundation.org/nda/ è¿™ç§å®¡æŸ¥é€šå¸¸è¶³ä»¥é¿å…以åŽå‡ºçŽ°ä¸¥é‡é—®é¢˜ï¼Œè€Œæ— 需公开披露项目。 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index 66cd8ee07606..94f7f866f103 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -1,155 +1,160 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/4.Coding.rst <development_coding>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _cn_development_coding: 使代ç æ£ç¡® ====================== -虽然对于一个åšå®žçš„ã€é¢å‘社区的设计过程有很多è¯è¦è¯´ï¼Œä½†æ˜¯ä»»ä½•å†…æ ¸å¼€å‘项目的 -è¯æ˜Žéƒ½åœ¨ç”Ÿæˆçš„代ç ä¸ã€‚它是将由其他开å‘人员检查并åˆå¹¶ï¼ˆæˆ–ä¸åˆå¹¶ï¼‰åˆ°ä¸»çº¿æ ‘ä¸ +虽然一个åšå®žçš„ã€é¢å‘社区的设计过程有很多值得说é“çš„ï¼Œä½†æ˜¯ä»»ä½•å†…æ ¸å¼€å‘项目工作 +çš„è¯æ˜Žéƒ½åæ˜ åœ¨ä»£ç ä¸ã€‚它是将由其他开å‘人员检查并åˆå¹¶ï¼ˆæˆ–ä¸åˆå¹¶ï¼‰åˆ°ä¸»çº¿æ ‘ä¸ çš„ä»£ç 。所以这段代ç çš„è´¨é‡å†³å®šäº†é¡¹ç›®çš„最终æˆåŠŸã€‚ -本节将检查编ç è¿‡ç¨‹ã€‚æˆ‘ä»¬å°†ä»Žå†…æ ¸å¼€å‘äººå‘˜å‡ºé”™çš„å‡ ç§æ–¹å¼å¼€å§‹ã€‚然åŽé‡ç‚¹å°†è½¬ç§» -到æ£ç¡®çš„事情和å¯ä»¥å¸®åŠ©è¿™ä¸ªä»»åŠ¡çš„工具上。 +本节将检查编ç è¿‡ç¨‹ã€‚æˆ‘ä»¬å°†ä»Žå†…æ ¸å¼€å‘äººå‘˜å¸¸çŠ¯çš„å‡ ç§é”™è¯¯å¼€å§‹ã€‚然åŽé‡ç‚¹å°†è½¬ç§» +到æ£ç¡®çš„åšæ³•å’Œç›¸å…³æœ‰ç”¨çš„工具上。 陷阱 ---- -ç¼–ç é£Žæ ¼ +代ç é£Žæ ¼ ******** -å†…æ ¸é•¿æœŸä»¥æ¥éƒ½æœ‰ä¸€ç§æ ‡å‡†çš„ç¼–ç é£Žæ ¼ï¼Œå¦‚ +å†…æ ¸é•¿æœŸä»¥æ¥éƒ½æœ‰å…¶æ ‡å‡†çš„代ç é£Žæ ¼ï¼Œå¦‚ :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` -ä¸æ‰€è¿°ã€‚在大部分时间里，该文件ä¸æ述的政ç–è¢«è®¤ä¸ºè‡³å¤šæ˜¯å»ºè®®æ€§çš„ã€‚å› æ¤ï¼Œå†…æ ¸ -ä¸å˜åœ¨å¤§é‡ä¸ç¬¦åˆç¼–ç é£Žæ ¼å‡†åˆ™çš„ä»£ç 。代ç çš„å˜åœ¨ä¼šç»™å†…æ ¸å¼€å‘人员带æ¥ä¸¤ä¸ªç‹¬ç«‹ -çš„å±å®³ã€‚ - -首先，è¦ç›¸ä¿¡å†…æ ¸ç¼–ç æ ‡å‡†å¹¶ä¸é‡è¦ï¼Œä¹Ÿä¸å¼ºåˆ¶æ‰§è¡Œã€‚äº‹å®žä¸Šï¼Œå¦‚æžœæ²¡æœ‰æŒ‰ç…§æ ‡å‡†å¯¹ä»£ -ç 进行编ç ，那么å‘å†…æ ¸æ·»åŠ æ–°ä»£ç 是éžå¸¸å›°éš¾çš„；许多开å‘人员甚至会在审查代ç 之 -å‰è¦æ±‚对代ç 进行é‡æ–°æ ¼å¼åŒ–ã€‚ä¸€ä¸ªä¸Žå†…æ ¸ä¸€æ ·å¤§çš„ä»£ç 库需è¦ä¸€äº›ç»Ÿä¸€çš„代ç ，以使 -å¼€å‘人员能够快速ç†è§£å…¶ä¸çš„任何部分。所以已ç»æ²¡æœ‰ç©ºé—´æ¥å˜æ”¾å¥‡æ€ªçš„æ ¼å¼åŒ–代ç 了。 - -å¶å°”ï¼Œå†…æ ¸çš„ç¼–ç é£Žæ ¼ä¼šä¸Žé›‡ä¸»çš„å¼ºåˆ¶é£Žæ ¼å‘生冲çªã€‚在这ç§æƒ…å†µä¸‹ï¼Œå†…æ ¸çš„é£Žæ ¼å¿…é¡» -在代ç åˆå¹¶ä¹‹å‰èŽ·èƒœã€‚将代ç æ”¾å…¥å†…æ ¸æ„味ç€ä»¥å¤šç§æ–¹å¼æ”¾å¼ƒä¸€å®šç¨‹åº¦çš„控制æƒâ€”—包括 -控制代ç çš„æ ¼å¼åŒ–æ–¹å¼ã€‚ - -å¦ä¸€ä¸ªé™·é˜±æ˜¯å‡å®šå·²ç»åœ¨å†…æ ¸ä¸çš„代ç 迫切需è¦ç¼–ç æ ·å¼çš„ä¿®å¤ã€‚å¼€å‘人员å¯èƒ½ä¼šå¼€å§‹ -生æˆé‡æ–°æ ¼å¼åŒ–è¡¥ä¸ï¼Œä½œä¸ºç†Ÿæ‚‰è¿‡ç¨‹çš„一ç§æ–¹å¼ï¼Œæˆ–者作为将其åç§°å†™å…¥å†…æ ¸å˜æ›´æ—¥å¿— -的一ç§æ–¹å¼ï¼Œæˆ–者两者兼而有之。但是纯编ç é£Žæ ¼çš„ä¿®å¤è¢«å¼€å‘社区视为噪音；它们往 -å¾€å—到冷é‡ã€‚å› æ¤ï¼Œæœ€å¥½é¿å…使用这ç§ç±»åž‹çš„è¡¥ä¸ã€‚ç”±äºŽå…¶ä»–åŽŸå› ï¼Œåœ¨å¤„ç†ä¸€æ®µä»£ç çš„ -åŒæ—¶ä¿®å¤å®ƒçš„æ ·å¼æ˜¯å¾ˆè‡ªç„¶çš„，但是编ç æ ·å¼çš„更改ä¸åº”该仅为了更改而进行。 - -ç¼–ç é£Žæ ¼çš„æ–‡æ¡£ä¹Ÿä¸åº”该被视为ç»å¯¹çš„法律，这是永远ä¸ä¼šè¢«è¿å的。如果有一个很好 -çš„ç†ç”±å对这ç§æ ·å¼ï¼ˆä¾‹å¦‚，如果拆分为适åˆ80列é™åˆ¶çš„行，那么它的å¯è¯»æ€§å°±ä¼šå¤§å¤§ -é™ä½Žï¼‰ï¼Œé‚£ä¹ˆå°±è¿™æ ·åšã€‚ - -请注æ„，您还å¯ä»¥ä½¿ç”¨ ``clang-format`` 工具æ¥å¸®åŠ©æ‚¨å¤„ç†è¿™äº›è§„则，自动é‡æ–°æ ¼å¼ -化部分代ç ，并查看完整的文件，以å‘现编ç æ ·å¼é”™è¯¯ã€æ‹¼å†™é”™è¯¯å’Œå¯èƒ½çš„改进。它还 -å¯ä»¥æ–¹ä¾¿åœ°è¿›è¡ŒæŽ’åºï¼ŒåŒ…括对é½å˜é‡/å®ã€å›žæµæ–‡æœ¬å’Œå…¶ä»–类似任务。有关详细信æ¯ï¼Œè¯· -å‚阅文件 :ref:`Documentation/process/clang-format.rst <clangformat>` +ä¸æ‰€è¿°ã€‚在多数时候，该文档ä¸æè¿°çš„å‡†åˆ™è‡³å¤šè¢«è®¤ä¸ºæ˜¯å»ºè®®æ€§çš„ã€‚å› æ¤ï¼Œå†…æ ¸ä¸å˜åœ¨ +大é‡ä¸ç¬¦åˆä»£ç é£Žæ ¼å‡†åˆ™çš„ä»£ç 。这ç§ä»£ç çš„å˜åœ¨ä¼šç»™å†…æ ¸å¼€å‘人员带æ¥ä¸¤æ–¹é¢çš„å±å®³ã€‚ + +é¦–å…ˆï¼Œç›¸ä¿¡å†…æ ¸ä»£ç æ ‡å‡†å¹¶ä¸é‡è¦ï¼Œä¹Ÿä¸å¼ºåˆ¶æ‰§è¡Œã€‚ä½†äº‹å®žä¸Šï¼Œå¦‚æžœæ²¡æœ‰æŒ‰ç…§æ ‡å‡† +编写代ç ，那么新代ç å°†å¾ˆéš¾åŠ å…¥åˆ°å†…æ ¸ä¸ï¼›è®¸å¤šå¼€å‘人员甚至会在审查代ç 之å‰è¦æ±‚ +对代ç 进行é‡æ–°æ ¼å¼åŒ–。一个åƒå†…æ ¸è¿™ä¹ˆå¤§çš„ä»£ç 库需è¦ä¸€äº›ç»Ÿä¸€æ ¼å¼çš„代ç ，以使 +å¼€å‘人员能够快速ç†è§£å…¶ä¸çš„任何部分。所以å†ä¹Ÿç»ä¸èµ·å¥‡æ€ªæ ¼å¼çš„代ç 的折腾了。 + +å†…æ ¸çš„ä»£ç é£Žæ ¼å¶å°”ä¼šä¸Žé›‡ä¸»çš„å¼ºåˆ¶é£Žæ ¼å‘生冲çªã€‚在这ç§æƒ…况下，必须在代ç åˆå¹¶ +之å‰éµä»Žå†…æ ¸ä»£ç é£Žæ ¼ã€‚å°†ä»£ç æ”¾å…¥å†…æ ¸æ„味ç€ä»¥å¤šç§æ–¹å¼æ”¾å¼ƒä¸€å®šç¨‹åº¦çš„控制æƒâ€”— +包括控制代ç æ ·å¼ã€‚ + +å¦ä¸€ä¸ªå±å®³æ˜¯è®¤ä¸ºå·²ç»åœ¨å†…æ ¸ä¸çš„代ç 迫切需è¦ä¿®å¤ä»£ç æ ·å¼ã€‚å¼€å‘者å¯èƒ½ä¼šå¼€å§‹ç¼–写 +é‡æ–°æ ¼å¼åŒ–è¡¥ä¸ï¼Œä½œä¸ºç†Ÿæ‚‰å¼€å‘过程的一ç§æ–¹å¼ï¼Œæˆ–者作为将其åå—å†™å…¥å†…æ ¸å˜æ›´æ—¥å¿— +的一ç§æ–¹å¼ï¼Œæˆ–者两者兼而有之。但是纯代ç é£Žæ ¼çš„ä¿®å¤è¢«å¼€å‘社区视为噪音，它们往 +å¾€å—到冷é‡ã€‚å› æ¤ï¼Œæœ€å¥½é¿å…编写这ç§ç±»åž‹çš„è¡¥ä¸ã€‚åœ¨ç”±äºŽå…¶ä»–åŽŸå› å¤„ç†ä¸€æ®µä»£ç çš„ +åŒæ—¶é¡ºå¸¦ä¿®å¤å…¶æ ·å¼æ˜¯å¾ˆè‡ªç„¶çš„，但是ä¸åº”该仅为了更改代ç æ ·å¼è€Œæ›´æ”¹ä¹‹ã€‚ + +代ç é£Žæ ¼æ–‡æ¡£ä¹Ÿä¸åº”该被视为ç»å¯¹ä¸å¯è¿å的规则。如果有一个足够的ç†ç”±åå¯¹è¿™ç§ +æ ·å¼ï¼ˆä¾‹å¦‚为了80列é™åˆ¶æ‹†åˆ†è¡Œä¼šå¯¼è‡´å¯è¯»æ€§å¤§å¤§é™ä½Žï¼‰ï¼Œé‚£ä¹ˆå°±è¿™æ ·åšå§ã€‚ + +注æ„您还å¯ä»¥ä½¿ç”¨ ``clang-format`` 工具æ¥å¸®åŠ©æ‚¨å¤„ç†è¿™äº›è§„则，快速自动é‡æ–°æ ¼å¼ +化部分代ç ，和审阅完整的文件以å‘现代ç æ ·å¼é”™è¯¯ã€æ‹¼å†™é”™è¯¯å’Œå¯èƒ½çš„改进。它还 +å¯ä»¥æ–¹ä¾¿åœ°æŽ’åº ``#includes`` ã€å¯¹é½å˜é‡/å®ã€é‡æŽ’文本和其他类似任务。有关详细 +ä¿¡æ¯ï¼Œè¯·å‚阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>` 抽象层 ****** 计算机科å¦æ•™æŽˆæ•™å¦ç”Ÿä»¥çµæ´»æ€§å’Œä¿¡æ¯éšè—çš„åä¹‰å¹¿æ³›ä½¿ç”¨æŠ½è±¡å±‚ã€‚å½“ç„¶ï¼Œå†…æ ¸å¹¿æ³› -地使用了抽象；任何涉åŠæ•°ç™¾ä¸‡è¡Œä»£ç 的项目都ä¸èƒ½åšåˆ°è¿™ä¸€ç‚¹å¹¶å˜æ´»ä¸‹æ¥ã€‚但ç»éªŒ -表明，过度或过早的抽象å¯èƒ½å’Œè¿‡æ—©çš„ä¼˜åŒ–ä¸€æ ·æœ‰å®³ã€‚æŠ½è±¡åº”ç”¨äºŽæ‰€éœ€çš„çº§åˆ«ï¼Œ +地使用了抽象；任何涉åŠæ•°ç™¾ä¸‡è¡Œä»£ç 的项目都必须åšåˆ°è¿™ä¸€ç‚¹ä»¥å˜ç»ä¸‹æ¥ã€‚但ç»éªŒ +表明，过度或过早的抽象å¯èƒ½å’Œè¿‡æ—©çš„ä¼˜åŒ–ä¸€æ ·æœ‰å®³ã€‚æŠ½è±¡åº”ç”¨åœ¨é€‚å½“å±‚çº§ï¼Œ ä¸è¦è¿‡åº¦ã€‚ -在一个简å•çš„级别上，考虑一个函数的å‚数，该å‚æ•°æ€»æ˜¯ç”±æ‰€æœ‰è°ƒç”¨æ–¹ä½œä¸ºé›¶ä¼ é€’ã€‚ -我们å¯ä»¥ä¿ç•™è¿™ä¸ªè®ºç‚¹: 以防有人最终需è¦ä½¿ç”¨å®ƒæ供的é¢å¤–çµæ´»æ€§ã€‚ä¸è¿‡ï¼Œåˆ°é‚£æ—¶ï¼Œ -实现这个é¢å¤–å‚数的代ç 很有å¯èƒ½ä»¥æŸç§ä»Žæœªè¢«æ³¨æ„到的微妙方å¼è¢«ç ´åâ€”â€”å› ä¸ºå®ƒä»Ž -未被使用过。或者，当需è¦é¢å¤–çš„çµæ´»æ€§æ—¶ï¼Œå®ƒä¸ä¼šä»¥ç¬¦åˆç¨‹åºå‘˜æ—©æœŸæœŸæœ›çš„æ–¹å¼æ¥ -è¿™æ ·åšã€‚å†…æ ¸å¼€å‘人员通常会æ交补ä¸æ¥åˆ 除未使用的å‚数；一般æ¥è¯´ï¼Œé¦–å…ˆä¸åº”该 -æ·»åŠ è¿™äº›å‚数。 +简å•ç‚¹ï¼Œå…ˆè€ƒè™‘一个调用时始终åªæœ‰ä¸€ä¸ªå‚数且总为零的函数。我们å¯ä»¥ä¿ç•™è¿™ä¸ªå‚数， +以在需è¦ä½¿ç”¨å®ƒæ—¶æ供的é¢å¤–çµæ´»æ€§ã€‚ä¸è¿‡ï¼Œåœ¨é‚£æ—¶å®žçŽ°äº†è¿™ä¸ªé¢å¤–å‚数的代ç 很有 +å¯èƒ½ä»¥æŸç§ä»Žæœªè¢«æ³¨æ„到的微妙方å¼è¢«ç ´åâ€”â€”å› ä¸ºå®ƒä»Žæœªè¢«ä½¿ç”¨è¿‡ã€‚æˆ–è€…å½“éœ€è¦é¢å¤– +çš„çµæ´»æ€§æ—¶ï¼Œå®ƒå¹¶æœªä»¥ç¬¦åˆç¨‹åºå‘˜å½“åˆæœŸæœ›çš„æ–¹å¼æ¥å®žçŽ°ã€‚å†…æ ¸å¼€å‘人员通常会æ交 +è¡¥ä¸æ¥åˆ 除未使用的å‚数；一般æ¥è¯´ï¼Œä¸€å¼€å§‹å°±ä¸åº”è¯¥æ·»åŠ è¿™äº›å‚数。 -éšè—硬件访问的抽象层——通常å…许大é‡çš„驱动程åºåœ¨å¤šä¸ªæ“作系统ä¸ä½¿ç”¨â€”—尤其ä¸å— +éšè—硬件访问的抽象层——通常为了å…许大é‡çš„驱动程åºå…¼å®¹å¤šä¸ªæ“作系统——尤其ä¸å— æ¬¢è¿Žã€‚è¿™æ ·çš„å±‚ä½¿ä»£ç å˜å¾—模糊，å¯èƒ½ä¼šé€ æˆæ€§èƒ½æŸå¤±ï¼›å®ƒä»¬ä¸å±žäºŽLinuxå†…æ ¸ã€‚ -å¦ä¸€æ–¹é¢ï¼Œå¦‚果您å‘现自己从å¦ä¸€ä¸ªå†…æ ¸å系统å¤åˆ¶äº†å¤§é‡çš„代ç ，那么现在是时候 -问一下，事实上，将这些代ç ä¸çš„一些æå–到å•ç‹¬çš„库ä¸ï¼Œæˆ–者在更高的层次上实现 -这些功能是å¦æœ‰æ„ä¹‰ã€‚åœ¨æ•´ä¸ªå†…æ ¸ä¸å¤åˆ¶ç›¸åŒçš„代ç 没有价值。 +å¦ä¸€æ–¹é¢ï¼Œå¦‚果您å‘现自己从å¦ä¸€ä¸ªå†…æ ¸å系统å¤åˆ¶äº†å¤§é‡çš„代ç ，那么是时候 +了解一下：是å¦éœ€è¦å°†è¿™äº›ä»£ç ä¸çš„部分æå–到å•ç‹¬çš„库ä¸ï¼Œæˆ–者在更高的层次上 +å®žçŽ°è¿™äº›åŠŸèƒ½ã€‚åœ¨æ•´ä¸ªå†…æ ¸ä¸å¤åˆ¶ç›¸åŒçš„代ç 没有价值。 #ifdef å’Œé¢„å¤„ç† *************** -C预处ç†å™¨ä¼¼ä¹Žç»™ä¸€äº›C程åºå‘˜å¸¦æ¥äº†å¼ºå¤§çš„诱惑，他们认为它是一ç§æœ‰æ•ˆåœ°å°†å¤§é‡çµ -活性编ç 到æºæ–‡ä»¶ä¸çš„方法。但是预处ç†å™¨ä¸æ˜¯C，大é‡ä½¿ç”¨å®ƒä¼šå¯¼è‡´ä»£ç å¯¹å…¶ä»–äººæ¥ -说更难读å–，对编译器æ¥è¯´æ›´éš¾æ£€æŸ¥æ£ç¡®æ€§ã€‚大é‡çš„预处ç†å™¨å‡ 乎总是代ç 需è¦ä¸€äº› +C预处ç†å™¨ä¼¼ä¹Žç»™ä¸€äº›C程åºå‘˜å¸¦æ¥äº†å¼ºå¤§çš„诱惑，他们认为它是一ç§å°†å¤§é‡çµæ´»æ€§åŠ å…¥ +æºä»£ç ä¸çš„方法。但是预处ç†å™¨ä¸æ˜¯C，大é‡ä½¿ç”¨å®ƒä¼šå¯¼è‡´ä»£ç 对其他人æ¥è¯´æ›´éš¾é˜…读， +对编译器æ¥è¯´æ›´éš¾æ£€æŸ¥æ£ç¡®æ€§ã€‚使用了大é‡é¢„处ç†å™¨å‡ 乎总是代ç 需è¦ä¸€äº› 清ç†å·¥ä½œçš„æ ‡å¿—ã€‚ -使用ifdefçš„æ¡ä»¶ç¼–è¯‘å®žé™…ä¸Šæ˜¯ä¸€ä¸ªå¼ºå¤§çš„åŠŸèƒ½ï¼Œå®ƒåœ¨å†…æ ¸ä¸ä½¿ç”¨ã€‚但是很少有人希望 -看到代ç 被大é‡åœ°æ’’上ifdefå—。作为一般规则，ifdef的使用应尽å¯èƒ½é™åˆ¶åœ¨å¤´æ–‡ä»¶ -ä¸ã€‚有æ¡ä»¶ç¼–译的代ç å¯ä»¥é™åˆ¶å‡½æ•°ï¼Œå¦‚果代ç ä¸å˜åœ¨ï¼Œè¿™äº›å‡½æ•°å°±ä¼šå˜æˆç©ºçš„ã€‚ç„¶åŽ -编译器将悄悄地优化对空函数的调用。结果是代ç æ›´åŠ æ¸…æ™°ï¼Œæ›´å®¹æ˜“ç†è§£ã€‚ +使用#ifdefçš„æ¡ä»¶ç¼–è¯‘å®žé™…ä¸Šæ˜¯ä¸€ä¸ªå¼ºå¤§çš„åŠŸèƒ½ï¼Œå®ƒåœ¨å†…æ ¸ä¸ä½¿ç”¨ã€‚但是很少有人希望 +看到代ç 被铺满#ifdefå—。一般规定，ifdef的使用应尽å¯èƒ½é™åˆ¶åœ¨å¤´æ–‡ä»¶ä¸ã€‚æ¡ä»¶ +编译代ç å¯ä»¥é™åˆ¶å‡½æ•°ï¼Œå¦‚果代ç ä¸å˜åœ¨ï¼Œè¿™äº›å‡½æ•°å°±ç›´æŽ¥å˜æˆç©ºçš„。然åŽç¼–译器将 +悄悄地优化对空函数的调用。使得代ç æ›´åŠ æ¸…æ™°ï¼Œæ›´å®¹æ˜“ç†è§£ã€‚ -C预处ç†å™¨å®å˜åœ¨è®¸å¤šå±é™©ï¼ŒåŒ…括å¯èƒ½å¯¹å…·æœ‰å‰¯ä½œç”¨ä¸”没有类型安全性的表达å¼è¿›è¡Œå¤š -é‡è¯„估。如果您试图定义å®ï¼Œè¯·è€ƒè™‘创建一个内è”函数。结果相åŒçš„代ç ï¼Œä½†æ˜¯å†…è” -函数更容易读å–，ä¸ä¼šå¤šæ¬¡è®¡ç®—å…¶å‚数，并且å…许编译器对å‚数和返回值执行类型检查。 +C预处ç†å™¨å®å˜åœ¨è®¸å¤šå±é™©æ€§ï¼ŒåŒ…括å¯èƒ½å¯¹å…·æœ‰å‰¯ä½œç”¨ä¸”没有类型安全的表达å¼è¿›è¡Œå¤š +é‡è¯„估。如果您试图定义å®ï¼Œè¯·è€ƒè™‘创建一个内è”函数替代。结果相åŒçš„代ç ï¼Œå†…è” +函数更容易阅读，ä¸ä¼šå¤šæ¬¡è®¡ç®—å…¶å‚数，并且å…许编译器对å‚数和返回值执行类型检查。 内è”函数 ******** ä¸è¿‡ï¼Œå†…è”函数本身也å˜åœ¨é£Žé™©ã€‚程åºå‘˜å¯ä»¥å€¾å¿ƒäºŽé¿å…函数调用和用内è”å‡½æ•°å¡«å……æº æ–‡ä»¶æ‰€å›ºæœ‰çš„æ•ˆçŽ‡ã€‚ç„¶è€Œï¼Œè¿™äº›åŠŸèƒ½å®žé™…ä¸Šä¼šé™ä½Žæ€§èƒ½ã€‚å› ä¸ºå®ƒä»¬çš„ä»£ç 在æ¯ä¸ªè°ƒç”¨ç«™ -点都被å¤åˆ¶ï¼Œæ‰€ä»¥å®ƒä»¬æœ€ç»ˆä¼šå¢žåŠ ç¼–è¯‘å†…æ ¸çš„å¤§å°ã€‚å过æ¥ï¼Œè¿™ä¼šå¯¹å¤„ç†å™¨çš„内å˜ç¼“å˜ -é€ æˆåŽ‹åŠ›ï¼Œä»Žè€Œå¤§å¤§é™ä½Žæ‰§è¡Œé€Ÿåº¦ã€‚通常，内è”函数应该éžå¸¸å°ï¼Œè€Œä¸”相对较少。毕竟， -函数调用的æˆæœ¬å¹¶ä¸é«˜ï¼›å¤§é‡å†…è”函数的创建是过早优化的典型例å。 +点都被å¤åˆ¶ä¸€éï¼Œæ‰€ä»¥æœ€ç»ˆä¼šå¢žåŠ ç¼–è¯‘å†…æ ¸çš„å¤§å°ã€‚æ¤å¤–，这也对处ç†å™¨çš„内å˜ç¼“å˜ +é€ æˆåŽ‹åŠ›ï¼Œä»Žè€Œå¤§å¤§é™ä½Žæ‰§è¡Œé€Ÿåº¦ã€‚通常内è”函数应该éžå¸¸å°ï¼Œè€Œä¸”相对较少。毕竟 +函数调用的æˆæœ¬å¹¶ä¸é«˜ï¼›å¤§é‡åˆ›å»ºå†…è”函数是过早优化的典型例å。 -一般æ¥è¯´ï¼Œå†…æ ¸ç¨‹åºå‘˜ä¼šå¿½ç•¥ç¼“å˜æ•ˆæžœï¼Œè¿™ä¼šå¸¦æ¥å±é™©ã€‚在开始的数æ®ç»“构课程ä¸ï¼Œç» -典的时间/空间æƒè¡¡é€šå¸¸ä¸é€‚ç”¨äºŽå½“ä»£ç¡¬ä»¶ã€‚ç©ºé—´å°±æ˜¯æ—¶é—´ï¼Œå› ä¸ºä¸€ä¸ªå¤§çš„ç¨‹åºæ¯”一个 +一般æ¥è¯´ï¼Œå†…æ ¸ç¨‹åºå‘˜ä¼šè‡ªå†’风险忽略缓å˜æ•ˆæžœã€‚在数æ®ç»“构课程开头ä¸çš„ç»å…¸ +时间/空间æƒè¡¡é€šå¸¸ä¸é€‚用于当代硬件。空间 *就是* æ—¶é—´ï¼Œå› ä¸ºä¸€ä¸ªå¤§çš„ç¨‹åºæ¯”一个 更紧凑的程åºè¿è¡Œå¾—慢。 -最近的编译器在决定一个给定函数是å¦åº”该被内è”æ–¹é¢æ‰®æ¼”ç€è¶Šæ¥è¶Šç§¯æžçš„角色。 -å› æ¤ï¼Œâ€œinlineâ€å…³é”®å—的自由放置å¯èƒ½ä¸ä»…仅是过度的，它也å¯èƒ½æ˜¯æ— 关的。 +较新的编译器越æ¥è¶Šæ¿€è¿›åœ°å†³å®šä¸€ä¸ªç»™å®šå‡½æ•°æ˜¯å¦åº”该内è”ã€‚å› æ¤ï¼Œéšæ„放置使用 +“inlineâ€å…³é”®å—å¯èƒ½ä¸ä»…仅是过度的，也å¯èƒ½æ˜¯æ— 用的。 é” ** -2006å¹´5月，“deviceescapeâ€ç½‘ç»œå †æ ˆåœ¨GPL下å‘å¸ƒï¼Œå¹¶è¢«çº³å…¥ä¸»çº¿å†…æ ¸ã€‚è¿™æ˜¯ä¸€ä¸ªå— -欢迎的消æ¯ï¼›å¯¹Linuxä¸æ— 线网络的支æŒå……å…¶é‡è¢«è®¤ä¸ºæ˜¯ä¸åˆæ ¼çš„，而deviceescape -å †æ ˆæ供了修å¤è¿™ç§æƒ…况的承诺。然而，直到2007å¹´6月（2.6.22），这段代ç æ‰çœŸ +2006å¹´5月，“deviceescapeâ€ç½‘ç»œå †æ ˆåœ¨å‰å‘¼åŽæ‹¥ä¸‹ä»¥GPLå‘å¸ƒï¼Œå¹¶è¢«çº³å…¥ä¸»çº¿å†…æ ¸ã€‚ +这是一个å—欢迎的消æ¯ï¼›Linuxä¸å¯¹æ— 线网络的支æŒå……å…¶é‡è¢«è®¤ä¸ºæ˜¯ä¸åˆæ ¼çš„，而 +Deviceescapeå †æ ˆæ‰¿è¯ºä¿®å¤è¿™ç§æƒ…况。然而直到2007å¹´6月（2.6.22），这段代ç æ‰çœŸ æ£è¿›å…¥ä¸»çº¿ã€‚å‘生了什么？ -这段代ç 显示了许多é—é—¨é€ è½¦çš„è¿¹è±¡ã€‚ä½†ä¸€ä¸ªç‰¹åˆ«å¤§çš„é—®é¢˜æ˜¯ï¼Œå®ƒå¹¶ä¸æ˜¯è®¾è®¡ç”¨äºŽå¤š -处ç†å™¨ç³»ç»Ÿã€‚在åˆå¹¶è¿™ä¸ªç½‘ç»œå †æ ˆï¼ˆçŽ°åœ¨ç§°ä¸ºmac80211）之å‰ï¼Œéœ€è¦å¯¹å…¶è¿›è¡Œä¸€ä¸ªé” -æ–¹æ¡ˆçš„æ”¹é€ ã€‚ +这段代ç 出现了许多é—é—¨é€ è½¦çš„è¿¹è±¡ã€‚ä½†ä¸€ä¸ªå¤§éº»çƒ¦æ˜¯ï¼Œå®ƒå¹¶ä¸æ˜¯ä¸ºå¤šå¤„ç†å™¨ç³»ç»Ÿè€Œ +设计。在åˆå¹¶è¿™ä¸ªç½‘ç»œå †æ ˆï¼ˆçŽ°åœ¨ç§°ä¸ºmac80211）之å‰ï¼Œéœ€è¦å¯¹å…¶è¿›è¡Œä¸€ä¸ªé”方案的 +æ”¹é€ ã€‚ 曾ç»ï¼ŒLinuxå†…æ ¸ä»£ç å¯ä»¥åœ¨ä¸è€ƒè™‘多处ç†å™¨ç³»ç»Ÿæ‰€å¸¦æ¥çš„并å‘性问题的情况下进行 -å¼€å‘。然而，现在，这个文件是写在åŒæ ¸ç¬”记本电脑上的。å³ä½¿åœ¨å•å¤„ç†å™¨ç³»ç»Ÿä¸Šï¼Œ +å¼€å‘。然而现在，这个文档就是在åŒæ ¸ç¬”记本电脑上写的。å³ä½¿åœ¨å•å¤„ç†å™¨ç³»ç»Ÿä¸Šï¼Œ 为æ高å“应能力所åšçš„工作也会æé«˜å†…æ ¸å†…çš„å¹¶å‘æ€§æ°´å¹³ã€‚ç¼–å†™å†…æ ¸ä»£ç 而ä¸è€ƒè™‘é” -çš„æ—¥åå·²ç»è¿‡åŽ»å¾ˆé•¿äº†ã€‚ +çš„æ—¥å早已远去。 å¯ä»¥ç”±å¤šä¸ªçº¿ç¨‹å¹¶å‘访问的任何资æºï¼ˆæ•°æ®ç»“æž„ã€ç¡¬ä»¶å¯„å˜å™¨ç‰ï¼‰å¿…须由é”ä¿æŠ¤ã€‚æ–° -的代ç 应该记ä½è¿™ä¸€è¦æ±‚；事åŽæ”¹è£…é”æ˜¯ä¸€é¡¹ç›¸å½“å›°éš¾çš„ä»»åŠ¡ã€‚å†…æ ¸å¼€å‘人员应该花 -时间充分了解å¯ç”¨çš„é”原è¯ï¼Œä»¥ä¾¿ä¸ºä½œä¸šé€‰æ‹©æ£ç¡®çš„工具。显示对并å‘性缺ä¹å…³æ³¨çš„ -代ç 进入主线将很困难。 +的代ç 应该谨记这一è¦æ±‚；事åŽä¿®æ”¹é”æ˜¯ä¸€é¡¹ç›¸å½“å›°éš¾çš„ä»»åŠ¡ã€‚å†…æ ¸å¼€å‘人员应该花 +时间充分了解å¯ç”¨çš„é”原è¯ï¼Œä»¥ä¾¿ä¸ºå·¥ä½œé€‰æ‹©æ£ç¡®çš„工具。对并å‘性缺ä¹å…³æ³¨çš„代ç +很难进入主线。 回归 **** -最åŽä¸€ä¸ªå€¼å¾—一æçš„å±é™©æ˜¯ï¼šå®ƒå¯èƒ½ä¼šå¼•èµ·æ”¹å˜ï¼ˆè¿™å¯èƒ½ä¼šå¸¦æ¥å¾ˆå¤§çš„改进），从而 -导致现有用户的æŸäº›ä¸œè¥¿ä¸æ–。这ç§å˜åŒ–被称为“回归â€ï¼Œå›žå½’å·²ç»æˆä¸ºä¸»çº¿å†…æ ¸æœ€ä¸ -å—欢迎的。除少数例外情况外，如果回归ä¸èƒ½åŠæ—¶ä¿®æ£ï¼Œä¼šå¯¼è‡´å›žå½’çš„å˜åŒ–将被å–消。 -最好首先é¿å…回归。 +最åŽä¸€ä¸ªå€¼å¾—一æçš„å±é™©æ˜¯å›žå½’：它å¯èƒ½ä¼šå¼•èµ·å¯¼è‡´çŽ°æœ‰ç”¨æˆ·çš„æŸäº›ä¸œè¥¿ä¸æ–çš„æ”¹å˜ +（这也å¯èƒ½ä¼šå¸¦æ¥å¾ˆå¤§çš„改进）。这ç§å˜åŒ–被称为“回归â€ï¼Œå›žå½’å·²ç»æˆä¸ºä¸»çº¿å†…æ ¸ +最ä¸å—欢迎的问题。除了少数例外情况，如果回归ä¸èƒ½åŠæ—¶ä¿®æ£ï¼Œä¼šå¯¼è‡´å›žå½’的修改 +将被å–消。最好首先é¿å…回归å‘生。 -人们常常争论，如果回归让更多人å¯ä»¥å·¥ä½œï¼Œè¿œè¶…过产生问题，那么回归是åˆç†çš„。 -å¦‚æžœå®ƒç ´å的一个系统å´ä¸ºå个系统带æ¥æ–°çš„功能，为什么ä¸è¿›è¡Œæ›´æ”¹å‘¢ï¼Ÿ2007å¹´7月， +人们常常争论，如果回归带æ¥çš„功能远超过产生的问题，那么回归是å¦ä¸ºå¯æŽ¥å—的。 +å¦‚æžœå®ƒç ´å了一个系统å´ä¸ºå个系统带æ¥æ–°çš„功能，为何ä¸æ”¹æ”¹æ€åº¦å‘¢ï¼Ÿ2007å¹´7月， Linus对这个问题给出了最佳ç”案: :: - 所以我们ä¸ä¼šé€šè¿‡å¼•å…¥æ–°é—®é¢˜æ¥ä¿®å¤é”™è¯¯ã€‚é‚£æ ·çš„è°Žè¨€å¾ˆç–¯ç‹‚ï¼Œæ²¡æœ‰äººçŸ¥é“ - ä½ æ˜¯å¦çœŸçš„有进展。是å‰è¿›ä¸¤æ¥ï¼ŒåŽé€€ä¸€æ¥ï¼Œè¿˜æ˜¯å‘å‰ä¸€æ¥ï¼Œå‘åŽä¸¤æ¥ï¼Ÿ + + 所以我们ä¸ä¼šé€šè¿‡å¼•å…¥æ–°é—®é¢˜æ¥ä¿®å¤é”™è¯¯ã€‚è¿™ç§æ–¹å¼æ˜¯é ä¸ä½çš„ï¼Œæ²¡äººçŸ¥é“ + 是å¦çœŸçš„有进展。是å‰è¿›ä¸¤æ¥ã€åŽé€€ä¸€æ¥ï¼Œè¿˜æ˜¯å‰è¿›ä¸€æ¥ã€åŽé€€ä¸¤æ¥ï¼Ÿ （http://lwn.net/articles/243460/） -一ç§ç‰¹åˆ«ä¸å—欢迎的回归类型是用户空间ABI的任何å˜åŒ–。一旦接å£è¢«å¯¼å‡ºåˆ°ç”¨æˆ·ç©ºé—´ï¼Œ +特别ä¸å—欢迎的一ç§å›žå½’类型是用户空间ABI的任何å˜åŒ–。一旦接å£è¢«å¯¼å‡ºåˆ°ç”¨æˆ·ç©ºé—´ï¼Œ å°±å¿…é¡»æ— é™æœŸåœ°æ”¯æŒå®ƒã€‚这一事实使得用户空间接å£çš„åˆ›å»ºç‰¹åˆ«å…·æœ‰æŒ‘æˆ˜æ€§ï¼šå› ä¸ºå®ƒä»¬ -ä¸èƒ½ä»¥ä¸å…¼å®¹çš„æ–¹å¼è¿›è¡Œæ›´æ”¹ï¼Œæ‰€ä»¥å¿…须第一次æ£ç¡®åœ°è¿›è¡Œæ›´æ”¹ã€‚å› æ¤ï¼Œç”¨æˆ·ç©ºé—´ç•Œé¢ -总是需è¦å¤§é‡çš„æ€è€ƒã€æ¸…晰的文档和广泛的审查。 +ä¸èƒ½ä»¥ä¸å…¼å®¹çš„æ–¹å¼è¿›è¡Œæ›´æ”¹ï¼Œæ‰€ä»¥å¿…é¡»ä¸€æ¬¡å°±å¯¹ã€‚å› æ¤ï¼Œç”¨æˆ·ç©ºé—´æŽ¥å£æ€»æ˜¯éœ€è¦å¤§é‡ +çš„æ€è€ƒã€æ¸…晰的文档和广泛的审查。 代ç 检查工具 @@ -157,13 +162,13 @@ Linus对这个问题给出了最佳ç”案: 至少目å‰ï¼Œç¼–å†™æ— é”™è¯¯ä»£ç ä»ç„¶æ˜¯æˆ‘们ä¸å¾ˆå°‘人能达到的ç†æƒ³çŠ¶æ€ã€‚ä¸è¿‡ï¼Œæˆ‘ä»¬å¸Œæœ›åš çš„æ˜¯ï¼Œåœ¨ä»£ç è¿›å…¥ä¸»çº¿å†…æ ¸ä¹‹å‰ï¼Œå°½å¯èƒ½å¤šåœ°æ•èŽ·å¹¶ä¿®å¤è¿™äº›é”™è¯¯ã€‚为æ¤ï¼Œå†…æ ¸å¼€å‘人 -员已ç»ç»„装了一系列令人å°è±¡æ·±åˆ»çš„工具，å¯ä»¥è‡ªåŠ¨æ•èŽ·å„ç§å„æ ·çš„æ¨¡ç³Šé—®é¢˜ã€‚è®¡ç®—æœº +员已ç»æ供了一系列令人å°è±¡æ·±åˆ»çš„工具，å¯ä»¥è‡ªåŠ¨æ•èŽ·å„ç§å„æ ·çš„éšè—问题。计算机 å‘现的任何问题都是一个以åŽä¸ä¼šå›°æ‰°ç”¨æˆ·çš„é—®é¢˜ï¼Œå› æ¤ï¼Œåªè¦æœ‰å¯èƒ½ï¼Œå°±åº”该使用 自动化工具。 -第一æ¥åªæ˜¯æ³¨æ„编译器产生的è¦å‘Šã€‚当代版本的GCCå¯ä»¥æ£€æµ‹ï¼ˆå¹¶è¦å‘Šï¼‰å¤§é‡æ½œåœ¨é”™è¯¯ã€‚ -通常，这些è¦å‘Šéƒ½æŒ‡å‘真æ£çš„问题。æ交以供审阅的代ç 通常ä¸ä¼šäº§ç”Ÿä»»ä½•ç¼–译器è¦å‘Šã€‚ -在消除è¦å‘Šæ—¶ï¼Œæ³¨æ„了解真æ£çš„åŽŸå› ï¼Œå¹¶å°½é‡é¿å…“修å¤â€ï¼Œä½¿è¦å‘Šæ¶ˆå¤±è€Œä¸è§£å†³å…¶åŽŸå› 。 +第一æ¥æ˜¯æ³¨æ„编译器产生的è¦å‘Šã€‚当å‰ç‰ˆæœ¬çš„GCCå¯ä»¥æ£€æµ‹ï¼ˆå¹¶è¦å‘Šï¼‰å¤§é‡æ½œåœ¨é”™è¯¯ã€‚ +通常，这些è¦å‘Šéƒ½æŒ‡å‘真æ£çš„问题。æ交以供审阅的代ç 一般ä¸ä¼šäº§ç”Ÿä»»ä½•ç¼–译器è¦å‘Šã€‚ +在消除è¦å‘Šæ—¶ï¼Œæ³¨æ„了解真æ£çš„åŽŸå› ï¼Œå¹¶å°½é‡é¿å…仅“修å¤â€ä½¿è¦å‘Šæ¶ˆå¤±è€Œä¸è§£å†³å…¶åŽŸå› 。 请注æ„，并éžæ‰€æœ‰ç¼–译器è¦å‘Šéƒ½é»˜è®¤å¯ç”¨ã€‚使用“make KCFLAGS=-Wâ€æž„å»ºå†…æ ¸ä»¥ 获得完整集åˆã€‚ @@ -172,45 +177,43 @@ Linus对这个问题给出了最佳ç”案: åèœå•ä¸ã€‚对于任何用于开å‘æˆ–æµ‹è¯•ç›®çš„çš„å†…æ ¸ï¼Œéƒ½åº”è¯¥å¯ç”¨å…¶ä¸å‡ 个选项。特别是， 您应该打开： - - å¯ç”¨ ENABLE_MUST_CHECK and FRAME_WARN 以获得一组é¢å¤–çš„è¦å‘Šï¼Œä»¥è§£å†³ä½¿ç”¨ä¸ - 推è使用的接å£æˆ–忽略函数的é‡è¦è¿”回值ç‰é—®é¢˜ã€‚这些è¦å‘Šç”Ÿæˆçš„输出å¯èƒ½æ˜¯å†—é•¿ - 的，但您ä¸å¿…担心æ¥è‡ªå†…æ ¸å…¶ä»–éƒ¨åˆ†çš„è¦å‘Šã€‚ + - FRAME_WARN 获å–大于给定数é‡çš„å †æ ˆå¸§çš„è¦å‘Šã€‚ + 这些è¦å‘Šç”Ÿæˆçš„输出å¯èƒ½æ¯”较冗长，但您ä¸å¿…担心æ¥è‡ªå†…æ ¸å…¶ä»–éƒ¨åˆ†çš„è¦å‘Šã€‚ - - DEBUG_OBJECTS å°†æ·»åŠ ä»£ç ï¼Œä»¥è·Ÿè¸ªå†…æ ¸åˆ›å»ºçš„å„ç§å¯¹è±¡çš„生å˜æœŸï¼Œå¹¶åœ¨å‡ºçŽ°é—®é¢˜æ—¶ - å‘出è¦å‘Šã€‚如果è¦æ·»åŠ 创建（和导出）自己的å¤æ‚对象的åç³»ç»Ÿï¼Œè¯·è€ƒè™‘æ·»åŠ å¯¹å¯¹è±¡ - 调试基础结构的支æŒã€‚ + - DEBUG_OBJECTS å°†æ·»åŠ ä»£ç ä»¥è·Ÿè¸ªå†…æ ¸åˆ›å»ºçš„å„ç§å¯¹è±¡çš„生命周期，并在出现问题 + æ—¶å‘出è¦å‘Šã€‚å¦‚æžœä½ è¦æ·»åŠ 创建（和导出）关于其自己的å¤æ‚对象的å系统，请 + 考虑打开对象调试基础结构的支æŒã€‚ - DEBUG_SLAB å¯ä»¥å‘现å„ç§å†…å˜åˆ†é…和使用错误；它应该用于大多数开å‘å†…æ ¸ã€‚ - - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP and DEBUG_MUTEXES 会å‘现许多常è§çš„ - é”定错误. + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP å’Œ DEBUG_MUTEXES 会å‘现许多常è§çš„ + é”错误。 -还有很多其他调试选项，其ä¸ä¸€äº›å°†åœ¨ä¸‹é¢è®¨è®ºã€‚å…¶ä¸ä¸€äº›å…·æœ‰æ˜¾è‘—的性能影å“，ä¸åº” -一直使用。但是，在å¦ä¹ å¯ç”¨é€‰é¡¹ä¸ŠèŠ±è´¹çš„一些时间å¯èƒ½ä¼šåœ¨çŸæœŸå†…得到多次回报。 +还有很多其他调试选项，其ä¸ä¸€äº›å°†åœ¨ä¸‹é¢è®¨è®ºã€‚å…¶ä¸ä¸€äº›æœ‰æ˜¾è‘—的性能影å“，ä¸åº” +一直使用。在å¦ä¹ å¯ç”¨é€‰é¡¹ä¸ŠèŠ±è´¹ä¸€äº›æ—¶é—´ï¼Œå¯èƒ½ä¼šåœ¨çŸæœŸå†…得到许多回报。 -å…¶ä¸ä¸€ä¸ªè¾ƒé‡çš„调试工具是é”定检查器或“lockdepâ€ã€‚该工具将跟踪系统ä¸æ¯ä¸ªé” +å…¶ä¸ä¸€ä¸ªè¾ƒé‡çš„调试工具是é”检查器或“lockdepâ€ã€‚该工具将跟踪系统ä¸æ¯ä¸ªé” （spinlock或mutex）的获å–和释放ã€èŽ·å–é”的相对顺åºã€å½“å‰ä¸æ–环境ç‰ç‰ã€‚然åŽï¼Œ -它å¯ä»¥ç¡®ä¿æ€»æ˜¯ä»¥ç›¸åŒçš„顺åºèŽ·å–é”，相åŒçš„ä¸æ–å‡è®¾é€‚用于所有情况，ç‰ç‰ã€‚æ¢å¥è¯ -说，lockdepå¯ä»¥æ‰¾åˆ°è®¸å¤šåœºæ™¯ï¼Œåœ¨è¿™äº›åœºæ™¯ä¸ï¼Œç³»ç»Ÿå¾ˆå°‘会æ»é”。在部署的系统ä¸ï¼Œ -è¿™ç§é—®é¢˜å¯èƒ½ä¼šå¾ˆç—›è‹¦ï¼ˆå¯¹äºŽå¼€å‘人员和用户而言）；LockDepå…许æå‰ä»¥è‡ªåŠ¨æ–¹å¼ -å‘现问题。具有任何类型的éžæ™®é€šé”定的代ç 在æ交包å«å‰åº”在å¯ç”¨lockdep的情况 -下è¿è¡Œã€‚ +它å¯ä»¥ç¡®ä¿æ€»æ˜¯ä»¥ç›¸åŒçš„顺åºèŽ·å–é”，相åŒçš„ä¸æ–å‡è®¾é€‚用于所有情况ç‰ç‰ã€‚æ¢å¥è¯ +说，lockdepå¯ä»¥æ‰¾åˆ°è®¸å¤šå¯¼è‡´ç³»ç»Ÿæ»é”的场景。在部署的系统ä¸ï¼Œè¿™ç§é—®é¢˜å¯èƒ½ä¼š +很痛苦（对于开å‘人员和用户而言）；LockDepå…许æå‰ä»¥è‡ªåŠ¨æ–¹å¼å‘现问题。具有 +任何类型的éžæ™®é€šé”的代ç 在æ交åˆå¹¶å‰åº”在å¯ç”¨lockdep的情况下è¿è¡Œæµ‹è¯•ã€‚ ä½œä¸ºä¸€ä¸ªå‹¤å¥‹çš„å†…æ ¸ç¨‹åºå‘˜ï¼Œæ¯«æ— 疑问，您将检查任何å¯èƒ½å¤±è´¥çš„æ“作（如内å˜åˆ†é…） -的返回状æ€ã€‚然而，事实上，最终的故障æ¢å¤è·¯å¾„å¯èƒ½å®Œå…¨æ²¡æœ‰ç»è¿‡æµ‹è¯•ã€‚未测试的 -代ç å¾€å¾€ä¼šè¢«ç ´å；如果所有这些错误处ç†è·¯å¾„éƒ½è¢«æ‰§è¡Œäº†å‡ æ¬¡ï¼Œé‚£ä¹ˆæ‚¨å¯èƒ½å¯¹ä»£ç +的返回状æ€ã€‚然而，事实上，最终的故障å¤çŽ°è·¯å¾„å¯èƒ½å®Œå…¨æ²¡æœ‰ç»è¿‡æµ‹è¯•ã€‚未测试的 +代ç 往往会出问题；如果所有这些错误处ç†è·¯å¾„éƒ½è¢«æ‰§è¡Œäº†å‡ æ¬¡ï¼Œé‚£ä¹ˆæ‚¨å¯èƒ½å¯¹ä»£ç 更有信心。 å†…æ ¸æ供了一个å¯ä»¥åšåˆ°è¿™ä¸€ç‚¹çš„错误注入框架，特别是在涉åŠå†…å˜åˆ†é…的情况下。 -å¯ç”¨æ•…障注入åŽï¼Œå†…å˜åˆ†é…çš„å¯é…置百分比将失败；这些失败å¯ä»¥é™åˆ¶åœ¨ç‰¹å®šçš„代ç +å¯ç”¨æ•…障注入åŽï¼Œå†…å˜åˆ†é…çš„å¯é…置失败的百分比；这些失败å¯ä»¥é™å®šåœ¨ç‰¹å®šçš„代ç 范围内。在å¯ç”¨äº†æ•…障注入的情况下è¿è¡Œï¼Œç¨‹åºå‘˜å¯ä»¥çœ‹åˆ°å½“情况æ¶åŒ–时代ç å¦‚ä½•å“ åº”ã€‚æœ‰å…³å¦‚ä½•ä½¿ç”¨æ¤å·¥å…·çš„详细信æ¯ï¼Œè¯·å‚阅 Documentation/fault-injection/fault-injection.rst。 -使用“sparseâ€é™æ€åˆ†æžå·¥å…·å¯ä»¥å‘现其他类型的错误。对于sparse，å¯ä»¥è¦å‘Šç¨‹åºå‘˜ -ç”¨æˆ·ç©ºé—´å’Œå†…æ ¸ç©ºé—´åœ°å€ä¹‹é—´çš„æ··æ·†ã€big endianå’Œsmall endianæ•°é‡çš„æ··åˆã€åœ¨éœ€ -è¦ä¸€ç»„ä½æ ‡å¿—çš„åœ°æ–¹ä¼ é€’æ•´æ•°å€¼ç‰ç‰ã€‚sparseå¿…é¡»å•ç‹¬å®‰è£…(如果您的分å‘æœåŠ¡å™¨æ²¡ -有将其打包，å¯ä»¥åœ¨ https://sparse.wiki.kernel.org/index.php/Main_page)找到, +“sparseâ€é™æ€åˆ†æžå·¥å…·å¯ä»¥å‘现其他类型的错误。sparseå¯ä»¥è¦å‘Šç¨‹åºå‘˜ç”¨æˆ·ç©ºé—´ +å’Œå†…æ ¸ç©ºé—´åœ°å€ä¹‹é—´çš„æ··æ·†ã€å¤§ç«¯åºä¸Žå°ç«¯åºçš„æ··æ·†ã€åœ¨éœ€è¦ä¸€ç»„ä½æ ‡å¿—çš„åœ°æ–¹ä¼ é€’ +整数值ç‰ç‰ã€‚sparseå¿…é¡»å•ç‹¬å®‰è£…(如果您的分å‘æœåŠ¡å™¨æ²¡æœ‰å°†å…¶æ‰“包， +å¯ä»¥åœ¨ https://sparse.wiki.kernel.org/index.php/Main_page 找到）, 然åŽå¯ä»¥é€šè¿‡åœ¨make命令ä¸æ·»åŠ “C=1â€åœ¨ä»£ç 上è¿è¡Œå®ƒã€‚ “Coccinelleâ€å·¥å…· :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` @@ -221,8 +224,8 @@ scripts/coccinelle目录下已ç»æ‰“åŒ…äº†ç›¸å½“å¤šçš„å†…æ ¸â€œè¯ä¹‰è¡¥ä¸â€ï¼ 其他类型的å¯ç§»æ¤æ€§é”™è¯¯æœ€å¥½é€šè¿‡ä¸ºå…¶ä»–体系结构编译代ç æ¥å‘现。如果没有S/390系统 -或Blackfinå¼€å‘æ¿ï¼Œæ‚¨ä»ç„¶å¯ä»¥æ‰§è¡Œç¼–译æ¥éª¤ã€‚å¯ä»¥åœ¨ä»¥ä¸‹ä½ç½®æ‰¾åˆ°ä¸€ç»„用于x86系统的 -大型交å‰ç¼–译器： +或Blackfinå¼€å‘æ¿ï¼Œæ‚¨ä»ç„¶å¯ä»¥æ‰§è¡Œç¼–译æ¥éª¤ã€‚å¯ä»¥åœ¨ä»¥ä¸‹ä½ç½®æ‰¾åˆ°ä¸€å¤§å †ç”¨äºŽx86系统的 +交å‰ç¼–译器： https://www.kernel.org/pub/tools/crosstool/ @@ -233,22 +236,22 @@ scripts/coccinelle目录下已ç»æ‰“åŒ…äº†ç›¸å½“å¤šçš„å†…æ ¸â€œè¯ä¹‰è¡¥ä¸â€ï¼ æ–‡æ¡£é€šå¸¸æ¯”å†…æ ¸å¼€å‘规则更为例外。å³ä¾¿å¦‚æ¤ï¼Œè¶³å¤Ÿçš„文档将有助于简化将新代ç åˆå¹¶ åˆ°å†…æ ¸ä¸çš„过程，使其他开å‘人员的生活更轻æ¾ï¼Œå¹¶å¯¹æ‚¨çš„用户有所帮助。在许多情况 -ä¸‹ï¼Œæ–‡ä»¶çš„æ·»åŠ å·²åŸºæœ¬ä¸Šæˆä¸ºå¼ºåˆ¶æ€§çš„。 +ä¸‹ï¼Œæ·»åŠ æ–‡æ¡£å·²åŸºæœ¬ä¸Šæ˜¯å¼ºåˆ¶æ€§çš„ã€‚ 任何补ä¸çš„第一个文档是其关è”çš„å˜æ›´æ—¥å¿—。日志æ¡ç›®åº”该æè¿°æ£åœ¨è§£å†³çš„问题ã€è§£å†³ 方案的形å¼ã€å¤„ç†è¡¥ä¸çš„人员ã€å¯¹æ€§èƒ½çš„任何相关影å“，以åŠç†è§£è¡¥ä¸å¯èƒ½éœ€è¦çš„任何 -其他内容。确ä¿changelog说明了为什么补ä¸å€¼å¾—应用；大é‡å¼€å‘人员未能æ供这些信æ¯ã€‚ +其他内容。确ä¿å˜æ›´æ—¥å¿—说明了*为什么*è¡¥ä¸å€¼å¾—应用；大é‡å¼€å‘者未能æ供这些信æ¯ã€‚ -ä»»ä½•æ·»åŠ æ–°ç”¨æˆ·ç©ºé—´ç•Œé¢çš„代ç （包括新的sysfs或/proc文件）都应该包å«è¯¥ç•Œé¢çš„ -文档，该文档使用户空间开å‘人员能够知é“他们在使用什么。请å‚阅 -Documentation/ABI/READMEï¼Œäº†è§£å¦‚ä½•æ ¼å¼åŒ–æ¤æ–‡æ¡£ä»¥åŠéœ€è¦æ供哪些信æ¯ã€‚ +ä»»ä½•æ·»åŠ æ–°ç”¨æˆ·ç©ºé—´æŽ¥å£çš„代ç ——包括新的sysfs或/proc文件——都应该包å«è¯¥æŽ¥å£ +的文档，该文档使用户空间开å‘人员能够知é“他们在使用什么。请å‚阅 +Documentation/ABI/README，了解如何æ¤æ–‡æ¡£æ ¼å¼ä»¥åŠéœ€è¦æ供哪些信æ¯ã€‚ -文件 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` -æè¿°äº†å†…æ ¸çš„æ‰€æœ‰å¼•å¯¼æ—¶é—´å‚æ•°ã€‚ä»»ä½•æ·»åŠ æ–°å‚æ•°çš„è¡¥ä¸éƒ½åº”该å‘è¯¥æ–‡ä»¶æ·»åŠ é€‚å½“çš„ +文档 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` +æè¿°äº†å†…æ ¸çš„æ‰€æœ‰å¼•å¯¼æ—¶é—´å‚æ•°ã€‚ä»»ä½•æ·»åŠ æ–°å‚æ•°çš„è¡¥ä¸éƒ½åº”该å‘è¯¥æ–‡æ¡£æ·»åŠ é€‚å½“çš„ æ¡ç›®ã€‚ -任何新的é…置选项都必须附有帮助文本，帮助文本清楚地解释了这些选项以åŠç”¨æˆ·å¯èƒ½ -希望何时选择它们。 +任何新的é…置选项都必须附有帮助文本，帮助文本需清楚地解释这些选项以åŠç”¨æˆ·å¯èƒ½ +希望何时使用它们。 许多å系统的内部APIä¿¡æ¯é€šè¿‡ä¸“é—¨æ ¼å¼åŒ–的注释进行记录；这些注释å¯ä»¥é€šè¿‡ “kernel-docâ€è„šæœ¬ä»¥å¤šç§æ–¹å¼æå–å’Œæ ¼å¼åŒ–。如果您在具有kerneldoc注释的åç³»ç»Ÿä¸ @@ -257,31 +260,31 @@ Documentation/ABI/READMEï¼Œäº†è§£å¦‚ä½•æ ¼å¼åŒ–æ¤æ–‡æ¡£ä»¥åŠéœ€è¦æä¾›å“ªäº æ¥è¯´æ˜¯ä¸€ä¸ªæœ‰ç”¨çš„æ´»åŠ¨ã€‚è¿™äº›æ³¨é‡Šçš„æ ¼å¼ä»¥åŠå¦‚何创建kerneldoc模æ¿çš„一些信æ¯å¯ä»¥åœ¨ :ref:`Documentation/doc-guide/ <doc_guide>` 上找到。 -任何阅读大é‡çŽ°æœ‰å†…æ ¸ä»£ç 的人都会注æ„到，注释的缺失往往是最值得注æ„的。å†ä¸€æ¬¡ï¼Œ -对新代ç 的期望比过去更高；åˆå¹¶æœªæ³¨é‡Šçš„代ç å°†æ›´åŠ å›°éš¾ã€‚è¿™å°±æ˜¯è¯´ï¼Œäººä»¬å‡ ä¹Žä¸å¸Œæœ› -用è¯è¨€æ³¨é‡Šä»£ç 。代ç 本身应该是å¯è¯»çš„，注释解释了更微妙的方é¢ã€‚ +任何阅读大é‡çŽ°æœ‰å†…æ ¸ä»£ç 的人都会注æ„到，注释的缺失往往是最值得注æ„的。åŒæ—¶ï¼Œ +对新代ç çš„è¦æ±‚比过去更高；åˆå¹¶æœªæ³¨é‡Šçš„代ç å°†æ›´åŠ å›°éš¾ã€‚è¿™å°±æ˜¯è¯´ï¼Œäººä»¬å¹¶ä¸æœŸæœ› +详细注释的代ç 。代ç 本身应该是自解释的，注释é˜é‡Šäº†æ›´å¾®å¦™çš„æ–¹é¢ã€‚ æŸäº›äº‹æƒ…应该总是被注释。使用内å˜å±éšœæ—¶ï¼Œåº”附上一行文å—，解释为什么需è¦è®¾ç½®å†…å˜ -å±éšœã€‚æ•°æ®ç»“æž„çš„é”定规则通常需è¦åœ¨æŸä¸ªåœ°æ–¹è§£é‡Šã€‚一般æ¥è¯´ï¼Œä¸»è¦æ•°æ®ç»“构需è¦å…¨é¢ -的文档。应该指出å•ç‹¬ä»£ç ä½ä¹‹é—´ä¸æ˜Žæ˜¾çš„ä¾èµ–性。任何å¯èƒ½è¯±ä½¿ä»£ç 看门人进行错误的 -“清ç†â€çš„事情都需è¦ä¸€ä¸ªæ³¨é‡Šæ¥è¯´æ˜Žä¸ºä»€ä¹ˆè¦è¿™æ ·åšã€‚ç‰ç‰ã€‚ +å±éšœã€‚æ•°æ®ç»“æž„çš„é”规则通常需è¦åœ¨æŸä¸ªåœ°æ–¹è§£é‡Šã€‚一般æ¥è¯´ï¼Œä¸»è¦æ•°æ®ç»“构需è¦å…¨é¢ +的文档。应该指出代ç ä¸åˆ†ç«‹çš„ä½ä¹‹é—´ä¸æ˜Žæ˜¾çš„ä¾èµ–性。任何å¯èƒ½è¯±ä½¿ä»£ç 管ç†äººè¿›è¡Œ +错误的“清ç†â€çš„事情都需è¦ä¸€ä¸ªæ³¨é‡Šæ¥è¯´æ˜Žä¸ºä»€ä¹ˆè¦è¿™æ ·åšã€‚ç‰ç‰ã€‚ 内部API更改 ----------- -å†…æ ¸æ供给用户空间的二进制接å£ä¸èƒ½è¢«ç ´å，除éžåœ¨æœ€ä¸¥é‡çš„情况下。相åï¼Œå†…æ ¸çš„ -内部编程接å£æ˜¯é«˜åº¦æµåŠ¨çš„，当需è¦æ—¶å¯ä»¥æ›´æ”¹ã€‚å¦‚æžœä½ å‘现自己ä¸å¾—ä¸å¤„ç†ä¸€ä¸ªå†…æ ¸ -APIï¼Œæˆ–è€…ä»…ä»…å› ä¸ºå®ƒä¸æ»¡è¶³ä½ 的需求而ä¸ä½¿ç”¨ç‰¹å®šçš„功能，这å¯èƒ½æ˜¯API需è¦æ”¹å˜çš„一 -ä¸ªæ ‡å¿—ã€‚ä½œä¸ºå†…æ ¸å¼€å‘人员，您有æƒè¿›è¡Œæ¤ç±»æ›´æ”¹ã€‚ +å†…æ ¸æ供给用户空间的二进制接å£ä¸èƒ½è¢«ç ´å，除éžé€¼ä¸å¾—å·²ã€‚è€Œå†…æ ¸çš„å†…éƒ¨ç¼–ç¨‹æŽ¥å£ +是高度æµåŠ¨çš„，当需è¦æ—¶å¯ä»¥æ›´æ”¹ã€‚å¦‚æžœä½ å‘现自己ä¸å¾—ä¸å¤„ç†ä¸€ä¸ªå†…æ ¸API，或者仅 +ä»…å› ä¸ºå®ƒä¸æ»¡è¶³ä½ çš„éœ€æ±‚å¯¼è‡´æ— æ³•ä½¿ç”¨ç‰¹å®šçš„åŠŸèƒ½ï¼Œè¿™å¯èƒ½æ˜¯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 index 9ff9945f918c..b0c65614844d 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -1,150 +1,157 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _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>`. +å‚与其ä¸çš„æ¯ä¸ªäººçš„ç”Ÿæ´»æ›´åŠ è½»æ¾ã€‚本文档试图æè¿°è¿™äº›çº¦å®šçš„éƒ¨åˆ†ç»†èŠ‚ï¼›æ›´å¤šä¿¡æ¯ +也å¯åœ¨ä»¥ä¸‹æ–‡æ¡£ä¸æ‰¾åˆ° +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`， +:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` +å’Œ :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。 何时邮寄 -------- -在补ä¸å®Œå…¨â€œå‡†å¤‡å¥½â€ä¹‹å‰ï¼Œæœ‰ä¸€ä¸ªä¸æ–的诱惑æ¥é¿å…å‘布补ä¸ã€‚对于简å•çš„è¡¥ä¸ï¼Œ -è¿™ä¸æ˜¯é—®é¢˜ã€‚但是，如果æ£åœ¨å®Œæˆçš„工作很å¤æ‚，那么在工作完æˆä¹‹å‰ä»Žç¤¾åŒºèŽ·å¾— -å馈就å¯ä»¥èŽ·å¾—å¾ˆå¤šå¥½å¤„ã€‚å› æ¤ï¼Œæ‚¨åº”该考虑å‘布æ£åœ¨è¿›è¡Œçš„工作，甚至使Gitæ ‘ -å¯ç”¨ï¼Œä»¥ä¾¿æ„Ÿå…´è¶£çš„å¼€å‘人员å¯ä»¥éšæ—¶èµ¶ä¸Šæ‚¨çš„工作。 +在补ä¸å®Œå…¨â€œå‡†å¤‡å¥½â€ä¹‹å‰ï¼Œé¿å…å‘布补ä¸æ˜¯ä¸€ç§æŒç»çš„诱惑。对于简å•çš„è¡¥ä¸ï¼Œè¿™ +ä¸æ˜¯é—®é¢˜ã€‚但是如果æ£åœ¨å®Œæˆçš„工作很å¤æ‚，那么在工作完æˆä¹‹å‰ä»Žç¤¾åŒºèŽ·å¾—å馈就 +å¯ä»¥èŽ·å¾—å¾ˆå¤šå¥½å¤„ã€‚å› æ¤ï¼Œæ‚¨åº”该考虑å‘布æ£åœ¨è¿›è¡Œçš„工作，甚至维护一个å¯ç”¨çš„Git +æ ‘ï¼Œä»¥ä¾¿æ„Ÿå…´è¶£çš„å¼€å‘人员å¯ä»¥éšæ—¶èµ¶ä¸Šæ‚¨çš„工作。 -当å‘布还没有准备好包å«çš„代ç 时，最好在å‘布本身ä¸è¿™æ ·è¯´ã€‚还应æåŠä»»ä½•æœ‰å¾…å®Œæˆ -的主è¦å·¥ä½œå’Œä»»ä½•å·²çŸ¥é—®é¢˜ã€‚很少有人会看到那些被认为是åŠç”Ÿä¸ç†Ÿçš„è¡¥ä¸ï¼Œä½†æ˜¯é‚£äº› -人会想到他们å¯ä»¥å¸®åŠ©ä½ 把工作推å‘æ£ç¡®çš„æ–¹å‘。 +当å‘布ä¸æœ‰å°šæœªå‡†å¤‡å¥½è¢«åŒ…å«çš„代ç ，最好在å‘布ä¸è¯´æ˜Žã€‚还应æåŠä»»ä½•æœ‰å¾…完æˆçš„ +主è¦å·¥ä½œå’Œä»»ä½•å·²çŸ¥é—®é¢˜ã€‚很少有人会愿æ„看那些被认为是åŠç”Ÿä¸ç†Ÿçš„è¡¥ä¸ï¼Œä½†æ˜¯ +那些愿æ„的人会带ç€ä»–们的点åæ¥ä¸€èµ·å¸®åŠ©ä½ 把工作推å‘æ£ç¡®çš„æ–¹å‘。 创建补ä¸ä¹‹å‰ ------------ -在考虑将补ä¸å‘é€åˆ°å¼€å‘社区之å‰ï¼Œæœ‰è®¸å¤šäº‹æƒ…应该åšã€‚这些包括： +在考虑将补ä¸å‘é€åˆ°å¼€å‘社区之å‰ï¼Œæœ‰è®¸å¤šäº‹æƒ…应该åšã€‚包括： - - å°½å¯èƒ½åœ°æµ‹è¯•ä»£ç ã€‚åˆ©ç”¨å†…æ ¸çš„è°ƒè¯•å·¥å…·ï¼Œç¡®ä¿å†…æ ¸ä½¿ç”¨æ‰€æœ‰åˆç†çš„é…ç½®é€‰é¡¹ç»„åˆ - 进行构建，使用跨编译器为ä¸åŒçš„体系结构进行构建ç‰ã€‚ + - å°½å¯èƒ½åœ°æµ‹è¯•ä»£ç ã€‚åˆ©ç”¨å†…æ ¸çš„è°ƒè¯•å·¥å…·ï¼Œç¡®ä¿å†…æ ¸ä½¿ç”¨äº†æ‰€æœ‰å¯èƒ½çš„é…ç½®é€‰é¡¹ç»„åˆ + 进行构建，使用交å‰ç¼–译器为ä¸åŒçš„体系结构进行构建ç‰ã€‚ - - ç¡®ä¿æ‚¨çš„代ç 符åˆå†…æ ¸ç¼–ç é£Žæ ¼æŒ‡å—。 + - ç¡®ä¿æ‚¨çš„代ç 符åˆå†…æ ¸ä»£ç é£Žæ ¼æŒ‡å—。 - 您的更改是å¦å…·æœ‰æ€§èƒ½å½±å“ï¼Ÿå¦‚æžœæ˜¯è¿™æ ·ï¼Œæ‚¨åº”è¯¥è¿è¡ŒåŸºå‡†æµ‹è¯•æ¥æ˜¾ç¤ºæ‚¨çš„å˜æ›´çš„ å½±å“（或好处）；结果的摘è¦åº”该包å«åœ¨è¡¥ä¸ä¸ã€‚ - ç¡®ä¿æ‚¨æœ‰æƒå‘布代ç 。如果这项工作是为雇主完æˆçš„，雇主对这项工作具有所有æƒï¼Œ - 并且必须åŒæ„æ ¹æ®GPL对其进行放行。 + 并且必须åŒæ„æ ¹æ®GPL对其进行å‘布。 一般æ¥è¯´ï¼Œåœ¨å‘布代ç 之å‰è¿›è¡Œä¸€äº›é¢å¤–çš„æ€è€ƒï¼Œå‡ 乎总是能在çŸæ—¶é—´å†…得到回报。 è¡¥ä¸å‡†å¤‡ -------- -准备å‘布补ä¸å¯èƒ½æ˜¯ä¸€ä¸ªæƒŠäººçš„工作é‡ï¼Œä½†å†æ¬¡å°è¯•èŠ‚çœæ—¶é—´åœ¨è¿™é‡Œé€šå¸¸æ˜¯ä¸æ˜Žæ™ºçš„， -å³ä½¿åœ¨çŸæœŸå†…。 +准备补ä¸å‘布的工作é‡å¯èƒ½å¾ˆæƒŠäººï¼Œä½†åœ¨æ¤å°è¯•èŠ‚çœæ—¶é—´é€šå¸¸æ˜¯ä¸æ˜Žæ™ºçš„，å³ä½¿åœ¨çŸæœŸ +内亦然。 -å¿…é¡»é’ˆå¯¹å†…æ ¸çš„ç‰¹å®šç‰ˆæœ¬å‡†å¤‡è¡¥ä¸ã€‚作为一般规则，补ä¸ç¨‹åºåº”该基于Linusçš„Gitæ ‘ä¸ -的当å‰ä¸»çº¿ã€‚当以主线为基础时，从一个众所周知的å‘布点开始——一个稳定的或RCçš„ -å‘布——而ä¸æ˜¯åœ¨ä¸€ä¸ªä¸»çº¿åˆ†æ”¯ä»»æ„点。 +å¿…é¡»é’ˆå¯¹å†…æ ¸çš„ç‰¹å®šç‰ˆæœ¬å‡†å¤‡è¡¥ä¸ã€‚一般æ¥è¯´ï¼Œè¡¥ä¸åº”该基于Linusçš„Gitæ ‘ä¸çš„å½“å‰ +主线。当以主线为基础时，请从一个众所周知的å‘布点开始——如稳定版本或 -rc +版本å‘布点——而ä¸æ˜¯åœ¨ä¸€ä¸ªä»»æ„的主线分支点。 -但是，å¯èƒ½éœ€è¦é’ˆå¯¹-mmã€linux-next或åç³»ç»Ÿæ ‘ç”Ÿæˆç‰ˆæœ¬ï¼Œä»¥ä¾¿äºŽæ›´å¹¿æ³›çš„测试和审查。 -æ ¹æ®è¡¥ä¸çš„区域以åŠå…¶ä»–åœ°æ–¹çš„æƒ…å†µï¼Œé’ˆå¯¹è¿™äº›å…¶ä»–æ ‘å»ºç«‹è¡¥ä¸å¯èƒ½éœ€è¦å¤§é‡çš„å·¥ä½œæ¥ +也å¯èƒ½éœ€è¦é’ˆå¯¹-mmã€linux-next或åç³»ç»Ÿæ ‘ç”Ÿæˆç‰ˆæœ¬ï¼Œä»¥ä¾¿äºŽæ›´å¹¿æ³›çš„测试和审查。 +æ ¹æ®è¡¥ä¸çš„区域以åŠå…¶ä»–åœ°æ–¹çš„æƒ…å†µï¼Œé’ˆå¯¹å…¶ä»–æ ‘å»ºç«‹çš„è¡¥ä¸å¯èƒ½éœ€è¦å¤§é‡çš„å·¥ä½œæ¥ è§£å†³å†²çªå’Œå¤„ç†API更改。 åªæœ‰æœ€ç®€å•çš„更改æ‰åº”æ ¼å¼åŒ–为å•ä¸ªè¡¥ä¸ï¼›å…¶ä»–所有更改都应作为一系列逻辑更改进行。 分割补ä¸æ˜¯ä¸€é—¨è‰ºæœ¯ï¼›ä¸€äº›å¼€å‘人员花了很长时间æ¥å¼„清楚如何按照社区期望的方å¼æ¥ -åšã€‚然而，有一些ç»éªŒæ³•åˆ™å¯ä»¥å¤§å¤§å¸®åŠ©ï¼š +分割。ä¸è¿‡ï¼Œè¿™äº›ç»éªŒæ³•åˆ™ä¹Ÿè®¸æœ‰å¸®åŠ©ï¼š - - 您å‘布的补ä¸ç¨‹åºç³»åˆ—å‡ ä¹Žè‚¯å®šä¸ä¼šæ˜¯å·¥ä½œç³»ç»Ÿä¸çš„一系列更改。相å，您所åšçš„ - 更改需è¦åœ¨æœ€ç»ˆå½¢å¼ä¸åŠ 以考虑，然åŽä»¥æœ‰æ„义的方å¼è¿›è¡Œæ‹†åˆ†ã€‚å¼€å‘人员对离散的〠- 自包å«çš„更改感兴趣，而ä¸æ˜¯æ‚¨èŽ·å–这些更改的路径。 + - 您å‘布的补ä¸ç³»åˆ—å‡ ä¹Žè‚¯å®šä¸ä¼šæ˜¯å¼€å‘过程ä¸ç‰ˆæœ¬æŽ§åˆ¶ç³»ç»Ÿä¸çš„一系列更改。相å， + 需è¦å¯¹æ‚¨æ‰€åšæ›´æ”¹çš„最终形å¼åŠ 以考虑，然åŽä»¥æœ‰æ„义的方å¼è¿›è¡Œæ‹†åˆ†ã€‚å¼€å‘人员对 + 离散的ã€è‡ªåŒ…å«çš„更改感兴趣，而ä¸æ˜¯æ‚¨åˆ›é€ 这些更改的原始路径。 - - æ¯ä¸ªé€»è¾‘上独立的å˜æ›´éƒ½åº”è¯¥æ ¼å¼åŒ–为å•ç‹¬çš„è¡¥ä¸ã€‚这些更改å¯ä»¥æ˜¯å°çš„（“å‘æ¤ - ç»“æž„æ·»åŠ å—段â€ï¼‰æˆ–å¤§çš„ï¼ˆä¾‹å¦‚ï¼Œæ·»åŠ ä¸€ä¸ªé‡è¦çš„新驱动程åºï¼‰ï¼Œä½†å®ƒä»¬åœ¨æ¦‚念上 - 应该是å°çš„，并且å¯ä»¥æŽ¥å—一行æ述。æ¯ä¸ªè¡¥ä¸éƒ½åº”该åšä¸€ä¸ªç‰¹å®šçš„更改，å¯ä»¥å•ç‹¬ - 检查并验è¯å®ƒæ‰€åšçš„事情。 + - æ¯ä¸ªé€»è¾‘上独立的å˜æ›´éƒ½åº”è¯¥æ ¼å¼åŒ–为å•ç‹¬çš„è¡¥ä¸ã€‚这些更改å¯ä»¥æ˜¯å°çš„ï¼ˆå¦‚â€œå‘ + æ¤ç»“æž„ä½“æ·»åŠ å—段â€ï¼‰æˆ–å¤§çš„ï¼ˆå¦‚æ·»åŠ ä¸€ä¸ªé‡è¦çš„新驱动程åºï¼‰ï¼Œä½†å®ƒä»¬åœ¨æ¦‚念上 + 应该是å°çš„，并且å¯ä»¥åœ¨ä¸€è¡Œå†…简述。æ¯ä¸ªè¡¥ä¸éƒ½åº”该åšä¸€ä¸ªç‰¹å®šçš„ã€å¯ä»¥å•ç‹¬ + 检查并验è¯å®ƒæ‰€åšçš„事情的更改。 - - 作为é‡ç”³ä¸Šè¿°å‡†åˆ™çš„一ç§æ–¹æ³•ï¼šä¸è¦åœ¨åŒä¸€è¡¥ä¸ä¸æ··åˆä¸åŒç±»åž‹çš„更改。如果一个 - è¡¥ä¸ä¿®å¤äº†ä¸€ä¸ªå…³é”®çš„安全æ¼æ´žï¼Œé‡æ–°æŽ’列了一些结构，并é‡æ–°æ ¼å¼åŒ–了代ç ，那么 - 很有å¯èƒ½å®ƒä¼šè¢«å¿½ç•¥ï¼Œè€Œé‡è¦çš„ä¿®å¤å°†ä¸¢å¤±ã€‚ + - æ¢ç§æ–¹å¼é‡ç”³ä¸Šè¿°å‡†åˆ™ï¼Œä¹Ÿå°±æ˜¯è¯´ï¼šä¸è¦åœ¨åŒä¸€è¡¥ä¸ä¸æ··åˆä¸åŒç±»åž‹çš„更改。如果 + 一个补ä¸ä¿®å¤äº†ä¸€ä¸ªå…³é”®çš„安全æ¼æ´žï¼Œåˆé‡æ–°æŽ’列了一些结构，还é‡æ–°æ ¼å¼åŒ–了代 + ç ，那么它很有å¯èƒ½ä¼šè¢«å¿½ç•¥ï¼Œä»Žè€Œå¯¼è‡´é‡è¦çš„ä¿®å¤ä¸¢å¤±ã€‚ - - æ¯ä¸ªè¡¥ä¸éƒ½åº”è¯¥äº§ç”Ÿä¸€ä¸ªå†…æ ¸ï¼Œå®ƒå¯ä»¥æ£ç¡®åœ°æž„建和è¿è¡Œï¼›å¦‚果补ä¸ç³»åˆ—在ä¸é—´è¢« - ä¸æ–，那么结果应该ä»ç„¶æ˜¯ä¸€ä¸ªå·¥ä½œçš„å†…æ ¸ã€‚è¡¥ä¸ç³»åˆ—的部分应用是使用 - “git bisctâ€å·¥å…·æŸ¥æ‰¾å›žå½’的一个常è§åœºæ™¯ï¼›å¦‚果结果是一个æŸåçš„å†…æ ¸ï¼Œé‚£ä¹ˆå¯¹äºŽ - 那些从事追踪问题的高尚工作的开å‘人员和用户æ¥è¯´ï¼Œå°†ä½¿ä»–ä»¬çš„ç”Ÿæ´»æ›´åŠ è‰°éš¾ã€‚ + - æ¯ä¸ªè¡¥ä¸éƒ½åº”该能创建一个å¯ä»¥æ£ç¡®åœ°æž„建和è¿è¡Œçš„å†…æ ¸ï¼›å¦‚æžœè¡¥ä¸ç³»åˆ—在ä¸é—´è¢« + æ–开，那么结果ä»åº”是一个æ£å¸¸å·¥ä½œçš„å†…æ ¸ã€‚éƒ¨åˆ†åº”ç”¨ä¸€ç³»åˆ—è¡¥ä¸æ˜¯ä½¿ç”¨ + “git bisctâ€å·¥å…·æŸ¥æ‰¾å›žå½’的一个常è§åœºæ™¯ï¼›å¦‚果结果是一个æŸåçš„å†…æ ¸ï¼Œé‚£ä¹ˆå°†ä½¿ + 那些从事追踪问题的高尚工作的开å‘äººå‘˜å’Œç”¨æˆ·çš„ç”Ÿæ´»æ›´åŠ è‰°éš¾ã€‚ - - ä¸è¿‡ï¼Œä¸è¦è¿‡åˆ†ã€‚一ä½å¼€å‘人员曾ç»å°†ä¸€ç»„编辑内容作为500个å•ç‹¬çš„è¡¥ä¸å‘布到一个 - 文件ä¸ï¼Œè¿™å¹¶æ²¡æœ‰ä½¿ä»–æˆä¸ºå†…æ ¸é‚®ä»¶åˆ—è¡¨ä¸æœ€å—欢迎的人。一个补ä¸å¯ä»¥ç›¸å½“大， - åªè¦å®ƒä»ç„¶åŒ…å«ä¸€ä¸ªå•ä¸€çš„逻辑å˜æ›´ã€‚ + - ä¸è¦è¿‡åˆ†åˆ†å‰²ã€‚一ä½å¼€å‘人员曾ç»å°†ä¸€ç»„针对å•ä¸ªæ–‡ä»¶çš„编辑分æˆ500个å•ç‹¬çš„è¡¥ä¸ + å‘布，这并没有使他æˆä¸ºå†…æ ¸é‚®ä»¶åˆ—è¡¨ä¸æœ€å—欢迎的人。一个补ä¸å¯ä»¥ç›¸å½“大， + åªè¦å®ƒä»ç„¶åŒ…å«ä¸€ä¸ªå•ä¸€çš„ *逻辑* å˜æ›´ã€‚ - - 用一系列补ä¸æ·»åŠ 一个全新的基础设施是很有诱惑力的，但是在系列ä¸çš„最åŽä¸€ä¸ª - è¡¥ä¸å¯ç”¨æ•´ä¸ªè¡¥ä¸ä¹‹å‰ï¼Œè¯¥åŸºç¡€è®¾æ–½æ˜¯ä¸ä½¿ç”¨çš„。如果å¯èƒ½çš„è¯ï¼Œåº”该é¿å…è¿™ç§ - è¯±æƒ‘ï¼›å¦‚æžœè¿™ä¸ªç³»åˆ—å¢žåŠ äº†å›žå½’ï¼Œé‚£ä¹ˆäºŒåˆ†æ³•å°†æŒ‡å‡ºæœ€åŽä¸€ä¸ªè¡¥ä¸æ˜¯å¯¼è‡´é—®é¢˜çš„ - è¡¥ä¸ï¼Œå³ä½¿çœŸæ£çš„bug在其他地方。åªè¦æœ‰å¯èƒ½ï¼Œæ·»åŠ 新代ç çš„è¡¥ä¸ç¨‹åºåº”è¯¥ç«‹å³ - 激活该代ç 。 + - 用一系列补ä¸æ·»åŠ 一个全新的基础设施，但是该设施在系列ä¸çš„最åŽä¸€ä¸ªè¡¥ä¸å¯ç”¨ + 整个å˜æ›´ä¹‹å‰ä¸èƒ½ä½¿ç”¨ï¼Œè¿™çœ‹èµ·æ¥å¾ˆè¯±äººã€‚如果å¯èƒ½çš„è¯ï¼Œåº”该é¿å…è¿™ç§è¯±æƒ‘ï¼› + å¦‚æžœè¿™ä¸ªç³»åˆ—å¢žåŠ äº†å›žå½’ï¼Œé‚£ä¹ˆäºŒåˆ†æ³•å°†æŒ‡å‡ºæœ€åŽä¸€ä¸ªè¡¥ä¸æ˜¯å¯¼è‡´é—®é¢˜çš„è¡¥ä¸ï¼Œ + å³ä½¿çœŸæ£çš„bug在其他地方。åªè¦æœ‰å¯èƒ½ï¼Œæ·»åŠ 新代ç çš„è¡¥ä¸ç¨‹åºåº”该立å³æ¿€æ´»è¯¥ + 代ç 。 -创建完美补ä¸ç³»åˆ—的工作å¯èƒ½æ˜¯ä¸€ä¸ªä»¤äººæ²®ä¸§çš„过程，在完æˆâ€œçœŸæ£çš„工作â€ä¹‹åŽéœ€è¦èŠ±è´¹ -大é‡çš„时间和æ€è€ƒã€‚但是，如果åšå¾—好，这是一段很好的时间。 +创建完美补ä¸ç³»åˆ—的工作å¯èƒ½æ˜¯ä¸€ä¸ªä»¤äººæ²®ä¸§çš„过程，在完æˆâ€œçœŸæ£çš„工作â€ä¹‹åŽéœ€è¦ +花费大é‡çš„时间和æ€è€ƒã€‚但是如果åšå¾—好，花费的时间就是值得的。 è¡¥ä¸æ ¼å¼å’Œæ›´æ”¹æ—¥å¿— ------------------ æ‰€ä»¥çŽ°åœ¨ä½ æœ‰äº†ä¸€ç³»åˆ—å®Œç¾Žçš„è¡¥ä¸å¯ä»¥å‘布，但是这项工作还没有完æˆã€‚æ¯ä¸ªè¡¥ä¸éƒ½ -需è¦è¢«æ ¼å¼åŒ–æˆä¸€æ¡æ¶ˆæ¯ï¼Œå®ƒå¯ä»¥å¿«é€Ÿè€Œæ¸…æ™°åœ°å°†å…¶ç›®çš„ä¼ è¾¾ç»™ä¸–ç•Œå…¶ä»–åœ°æ–¹ã€‚ä¸ºæ¤ï¼Œ +需è¦è¢«æ ¼å¼åŒ–æˆä¸€æ¡æ¶ˆæ¯ï¼Œä»¥å¿«é€Ÿè€Œæ¸…æ™°åœ°å°†å…¶ç›®çš„ä¼ è¾¾åˆ°ä¸–ç•Œå…¶ä»–åœ°æ–¹ã€‚ä¸ºæ¤ï¼Œ æ¯ä¸ªè¡¥ä¸å°†ç”±ä»¥ä¸‹éƒ¨åˆ†ç»„æˆï¼š - - 命åè¡¥ä¸ä½œè€…çš„å¯é€‰â€œfromâ€è¡Œã€‚åªæœ‰å½“ä½ é€šè¿‡ç”µåé‚®ä»¶ä¼ é€’åˆ«äººçš„è¡¥ä¸æ—¶ï¼Œè¿™ä¸€è¡Œ - æ‰æ˜¯å¿…è¦çš„ï¼Œä½†æ˜¯å¦‚æžœæœ‰ç–‘é—®ï¼Œæ·»åŠ å®ƒä¸ä¼šæœ‰ä»»ä½•ä¼¤å®³ã€‚ + - å¯é€‰çš„“Fromâ€è¡Œï¼Œè¡¨æ˜Žè¡¥ä¸ä½œè€…。åªæœ‰å½“ä½ é€šè¿‡ç”µå邮件å‘é€åˆ«äººçš„è¡¥ä¸æ—¶ï¼Œè¿™ä¸€è¡Œ + æ‰æ˜¯å¿…须的，但是为防æ¢ç–‘é—®åŠ ä¸Šå®ƒä¹Ÿä¸ä¼šæœ‰ä»€ä¹ˆå处。 - - 一行æè¿°è¡¥ä¸çš„作用。对于没有其他上下文的读者æ¥è¯´ï¼Œæ¤æ¶ˆæ¯åº”è¯¥è¶³å¤Ÿäº†è§£è¡¥ä¸ - 的范围；这是将在“çŸæ ¼å¼â€å˜æ›´æ—¥å¿—ä¸æ˜¾ç¤ºçš„行。æ¤æ¶ˆæ¯é€šå¸¸é¦–先用相关的å系统 - åç§°æ ¼å¼åŒ–，然åŽæ˜¯è¡¥ä¸çš„目的。例如： + - 一行æ述，说明补ä¸çš„作用。对于在没有其他上下文的情况下看到该消æ¯çš„读者æ¥è¯´ï¼Œ + 该消æ¯åº”足以确定修补程åºçš„范围；æ¤è¡Œå°†æ˜¾ç¤ºåœ¨â€œshort form（简çŸæ ¼å¼ï¼‰â€å˜æ›´ + 日志ä¸ã€‚æ¤æ¶ˆæ¯é€šå¸¸éœ€è¦å…ˆåŠ 上å系统å称å‰ç¼€ï¼Œç„¶åŽæ˜¯è¡¥ä¸çš„目的。例如： - :: + :: - gpio: fix build on CONFIG_GPIO_SYSFS=n + gpio: fix build on CONFIG_GPIO_SYSFS=n - - 一个空白行，åŽé¢æ˜¯è¡¥ä¸å†…容的详细æ述。这个æè¿°å¯ä»¥æ˜¯å¿…éœ€çš„ï¼›å®ƒåº”è¯¥è¯´æ˜Žè¡¥ä¸ + - 一行空白，åŽæŽ¥è¡¥ä¸å†…容的详细æ述。æ¤æè¿°å¯ä»¥æ˜¯ä»»æ„需è¦çš„é•¿åº¦ï¼›å®ƒåº”è¯¥è¯´æ˜Žè¡¥ä¸ çš„ä½œç”¨ä»¥åŠä¸ºä»€ä¹ˆå®ƒåº”è¯¥åº”ç”¨äºŽå†…æ ¸ã€‚ - - ä¸€ä¸ªæˆ–å¤šä¸ªæ ‡è®°è¡Œï¼Œè‡³å°‘æœ‰ä¸€ä¸ªç”±è¡¥ä¸ä½œè€…的：signed-off-by ç¾å。ç¾åå°†åœ¨ä¸‹é¢ - 更详细地æ述。 + - ä¸€ä¸ªæˆ–å¤šä¸ªæ ‡è®°è¡Œï¼Œè‡³å°‘æœ‰ä¸€ä¸ªç”±è¡¥ä¸ä½œè€…çš„ Signed-off-by ç¾åã€‚æ ‡è®°å°†åœ¨ä¸‹é¢ + 详细æ述。 -上é¢çš„项目一起构æˆè¡¥ä¸çš„å˜æ›´æ—¥å¿—。写一篇好的å˜æ›´æ—¥å¿—是一门至关é‡è¦ä½†å¸¸å¸¸è¢« -忽视的艺术；值得花一点时间æ¥è®¨è®ºè¿™ä¸ªé—®é¢˜ã€‚å½“ä½ å†™ä¸€ä¸ªå˜æ›´æ—¥å¿—æ—¶ï¼Œä½ åº”è¯¥è®°ä½ -有很多ä¸åŒçš„äººä¼šè¯»ä½ çš„è¯ã€‚å…¶ä¸åŒ…括å系统维护人员和审查人员，他们需è¦å†³å®šæ˜¯å¦ -应该包括补ä¸ï¼Œåˆ†é”€å•†å’Œå…¶ä»–维护人员试图决定是å¦åº”该将补ä¸åå‘移æ¤åˆ°å…¶ä»–å†…æ ¸ï¼Œ -bugæœå¯»äººå‘˜æƒ³çŸ¥é“è¡¥ä¸æ˜¯å¦è´Ÿè´£ä»–们æ£åœ¨è¿½æŸ¥çš„问题，想知é“å†…æ ¸å¦‚ä½•å˜åŒ–的用户。 -ç‰ç‰ã€‚一个好的å˜æ›´æ—¥å¿—以最直接和最简æ´çš„æ–¹å¼å‘æ‰€æœ‰è¿™äº›äººä¼ è¾¾æ‰€éœ€çš„ä¿¡æ¯ã€‚ +上é¢çš„项目一起构æˆè¡¥ä¸çš„å˜æ›´æ—¥å¿—。写一则好的å˜æ›´æ—¥å¿—是一门至关é‡è¦ä½†å¸¸å¸¸è¢« +忽视的艺术；值得花一点时间æ¥è®¨è®ºè¿™ä¸ªé—®é¢˜ã€‚å½“ä½ ç¼–å†™å˜æ›´æ—¥å¿—æ—¶ï¼Œä½ åº”è¯¥è®°ä½æœ‰ +很多ä¸åŒçš„äººä¼šè¯»ä½ çš„è¯ã€‚å…¶ä¸åŒ…括å系统维护人员和审查人员，他们需è¦å†³å®šæ˜¯å¦ +应该åˆå¹¶è¡¥ä¸ï¼Œåˆ†é”€å•†å’Œå…¶ä»–维护人员试图决定是å¦åº”该将补ä¸åå‘移æ¤åˆ°å…¶ä»–å†…æ ¸ï¼Œ +缺陷æœå¯»äººå‘˜æƒ³çŸ¥é“è¡¥ä¸æ˜¯å¦å¯¼è‡´ä»–们æ£åœ¨è¿½æŸ¥çš„问题，以åŠæƒ³çŸ¥é“å†…æ ¸å¦‚ä½•å˜åŒ–çš„ +用户ç‰ç‰ã€‚一个好的å˜æ›´æ—¥å¿—以最直接和最简æ´çš„æ–¹å¼å‘æ‰€æœ‰è¿™äº›äººä¼ è¾¾æ‰€éœ€çš„ä¿¡æ¯ã€‚ -为æ¤ï¼Œæ€»ç»“行应该æè¿°å˜æ›´çš„å½±å“和动机，以åŠåœ¨ä¸€è¡Œçº¦æŸæ¡ä»¶ä¸‹å¯èƒ½å‘生的å˜åŒ–。 +在结尾，总结行应该æè¿°å˜æ›´çš„å½±å“和动机，以åŠåœ¨ä¸€è¡Œçº¦æŸæ¡ä»¶ä¸‹å¯èƒ½å‘生的å˜åŒ–。 然åŽï¼Œè¯¦ç»†çš„æè¿°å¯ä»¥è¯¦è¿°è¿™äº›ä¸»é¢˜ï¼Œå¹¶æ供任何需è¦çš„é™„åŠ ä¿¡æ¯ã€‚如果补ä¸ä¿®å¤äº† -一个bug，请引用引入该bugçš„commit（如果å¯èƒ½ï¼Œè¯·åœ¨å¼•ç”¨commitsæ—¶åŒæ—¶æä¾›commit id -å’Œæ ‡é¢˜ï¼‰ã€‚å¦‚æžœæŸä¸ªé—®é¢˜ä¸Žç‰¹å®šçš„日志或编译器输出相关è”，请包å«è¯¥è¾“出以帮助其他 -人æœç´¢åŒä¸€é—®é¢˜çš„解决方案。如果更改是为了支æŒä»¥åŽè¡¥ä¸ä¸çš„其他更改，那么就这么 -说。如果更改了内部API，请详细说明这些更改以åŠå…¶ä»–å¼€å‘人员应该如何å“应。一般 -æ¥è¯´ï¼Œä½ 越能把自己放在æ¯ä¸ªé˜…è¯»ä½ çš„changelog的人的ä½ç½®ä¸Šï¼Œchangelogï¼ˆå’Œå†…æ ¸ +一个缺陷，请引用引入该缺陷的æ交（如果å¯èƒ½ï¼Œè¯·åœ¨å¼•ç”¨æ交时åŒæ—¶æ供其 id å’Œ +æ ‡é¢˜ï¼‰ã€‚å¦‚æžœæŸä¸ªé—®é¢˜ä¸Žç‰¹å®šçš„日志或编译器输出相关è”，请包å«è¯¥è¾“出以帮助其他 +人æœç´¢åŒä¸€é—®é¢˜çš„解决方案。如果更改是为了支æŒä»¥åŽè¡¥ä¸ä¸çš„其他更改，那么应当 +说明。如果更改了内部API，请详细说明这些更改以åŠå…¶ä»–å¼€å‘人员应该如何å“应。 +一般æ¥è¯´ï¼Œä½ 越把自己放在æ¯ä¸ªé˜…è¯»ä½ å˜æ›´æ—¥å¿—的人的ä½ç½®ä¸Šï¼Œå˜æ›´æ—¥å¿—ï¼ˆå’Œå†…æ ¸ 作为一个整体）就越好。 -ä¸ç”¨è¯´ï¼Œå˜æ›´æ—¥å¿—应该是将å˜æ›´æ交到修订控制系统时使用的文本。接下æ¥æ˜¯ï¼š +ä¸æ¶ˆè¯´ï¼Œå˜æ›´æ—¥å¿—是将å˜æ›´æ交到版本控制系统时使用的文本。接下æ¥å°†æ˜¯ï¼š - - è¡¥ä¸æœ¬èº«ï¼Œé‡‡ç”¨ç»Ÿä¸€çš„（“-uâ€ï¼‰è¡¥ä¸æ ¼å¼ã€‚将“-pâ€é€‰é¡¹ç”¨äºŽdiff将使函数å与更改 - 相关è”，从而使结果补ä¸æ›´å®¹æ˜“被其他人读å–。 + - è¡¥ä¸æœ¬èº«ï¼Œé‡‡ç”¨ç»Ÿä¸€çš„（“-uâ€ï¼‰è¡¥ä¸æ ¼å¼ã€‚使用“-pâ€é€‰é¡¹æ¥diff将使函数å与 + 更改相关è”，从而使结果补ä¸æ›´å®¹æ˜“被其他人读å–。 -您应该é¿å…在补ä¸ä¸åŒ…括对ä¸ç›¸å…³æ–‡ä»¶ï¼ˆä¾‹å¦‚，由构建过程生æˆçš„文件或编辑器 -备份文件）的更改。文档目录ä¸çš„文件“dontdiffâ€åœ¨è¿™æ–¹é¢æœ‰å¸®åŠ©ï¼›ä½¿ç”¨â€œ-Xâ€é€‰é¡¹å°† +您应该é¿å…在补ä¸ä¸åŒ…括与更改ä¸ç›¸å…³æ–‡ä»¶ï¼ˆä¾‹å¦‚，构建过程生æˆçš„文件或编辑器 +备份文件）。文档目录ä¸çš„“dontdiffâ€æ–‡ä»¶åœ¨è¿™æ–¹é¢æœ‰å¸®åŠ©ï¼›ä½¿ç”¨â€œ-Xâ€é€‰é¡¹å°† å…¶ä¼ é€’ç»™diff。 -上é¢æåˆ°çš„æ ‡ç¾ç”¨äºŽæè¿°å„ç§å¼€å‘人员如何与这个补ä¸çš„å¼€å‘相关è”。 +上é¢æåˆ°çš„æ ‡ç¾ï¼ˆtag）用于æè¿°å„ç§å¼€å‘人员如何与这个补ä¸çš„å¼€å‘相关è”。 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` 文档ä¸å¯¹å®ƒä»¬è¿›è¡Œäº†è¯¦ç»†æ述；下é¢æ˜¯ä¸€ä¸ªç®€çŸçš„总结。æ¯ä¸€è¡Œçš„æ ¼å¼å¦‚下： @@ -154,87 +161,87 @@ bugæœå¯»äººå‘˜æƒ³çŸ¥é“è¡¥ä¸æ˜¯å¦è´Ÿè´£ä»–们æ£åœ¨è¿½æŸ¥çš„问题，想知é å¸¸ç”¨çš„æ ‡ç¾æœ‰ï¼š - - Signed-off-by: 这是一个开å‘人员的è¯æ˜Žï¼Œä»–或她有æƒæ交补ä¸ä»¥åŒ…å«åˆ°å†…æ ¸ä¸ã€‚ - 这是开å‘æ¥æºè®¤è¯å议，其全文å¯åœ¨ + - Signed-off-by: 这是一个开å‘人员的è¯æ˜Žï¼Œè¯æ˜Žä»–或她有æƒæ交补ä¸ä»¥åŒ…å«åˆ°å†…æ ¸ + ä¸ã€‚这表明åŒæ„å¼€å‘者æ¥æºè®¤è¯åè®®ï¼Œå…¶å…¨æ–‡è§ :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - ä¸æ‰¾åˆ°ï¼Œå¦‚果没有适当的ç¾å—，则ä¸èƒ½åˆå¹¶åˆ°ä¸»çº¿ä¸ã€‚ + 如果没有åˆé€‚çš„ç¾å—，则ä¸èƒ½åˆå¹¶åˆ°ä¸»çº¿ä¸ã€‚ - Co-developed-by: 声明补ä¸æ˜¯ç”±å¤šä¸ªå¼€å‘人员共åŒåˆ›å»ºçš„ï¼›å½“å‡ ä¸ªäººåœ¨ä¸€ä¸ªè¡¥ä¸ä¸Š - 工作时，它用于将属性赋予共åŒä½œè€…（除了 From: æ‰€èµ‹äºˆçš„ä½œè€…ä¹‹å¤–ï¼‰ã€‚å› ä¸º - Co-developed-by: 表示作者身份，所以æ¯ä¸ªå…±åŒå¼€å‘人, 必须紧跟在相关åˆä½œä½œè€… - çš„ç¾å之åŽã€‚具体内容和示例å¯ä»¥åœ¨ä»¥ä¸‹æ–‡ä»¶ä¸æ‰¾åˆ° + 工作时，它用于给出共åŒä½œè€…（除了 From: 所给出的作者之外）。由于 + Co-developed-by: 表示作者身份，所以æ¯ä¸ªå…±åŒå¼€å‘人，必须紧跟在相关åˆä½œä½œè€… + çš„Signed-off-by之åŽã€‚具体内容和示例è§ä»¥ä¸‹æ–‡ä»¶ :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - Acked-by: 表示å¦ä¸€ä¸ªå¼€å‘人员（通常是相关代ç 的维护人员）åŒæ„è¡¥ä¸é€‚åˆåŒ…å« åœ¨å†…æ ¸ä¸ã€‚ - - Tested-by: 声明指定的人已ç»æµ‹è¯•äº†è¡¥ä¸å¹¶å‘现它å¯ä»¥å·¥ä½œã€‚ + - Tested-by: 声明æŸäººå·²ç»æµ‹è¯•äº†è¡¥ä¸å¹¶ç¡®è®¤å®ƒå¯ä»¥å·¥ä½œã€‚ - - Reviewed-by: 指定的开å‘人员已ç»å®¡æŸ¥äº†è¡¥ä¸çš„æ£ç¡®æ€§ï¼›æœ‰å…³è¯¦ç»†ä¿¡æ¯ï¼Œè¯·å‚阅 + - Reviewed-by: 表示æŸå¼€å‘人员已ç»å®¡æŸ¥äº†è¡¥ä¸çš„æ£ç¡®æ€§ï¼›æœ‰å…³è¯¦ç»†ä¿¡æ¯ï¼Œè¯·å‚阅 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - - Reported-by: 指定报告æ¤è¡¥ä¸ä¿®å¤çš„问题的用户；æ¤æ ‡è®°ç”¨äºŽæ供感谢。 + - Reported-by: 指定报告æ¤è¡¥ä¸ä¿®å¤çš„问题的用户；æ¤æ ‡è®°ç”¨äºŽè¡¨ç¤ºæ„Ÿè°¢ã€‚ - - Cc：指定的人收到了补ä¸çš„副本，并有机会对æ¤å‘表评论。 + - Cc：指定æŸäººæ”¶åˆ°äº†è¡¥ä¸çš„副本，并有机会对æ¤å‘表评论。 -在补ä¸ä¸æ·»åŠ æ ‡ç¾æ—¶è¦å°å¿ƒï¼šåªæœ‰cc:æ‰é€‚åˆåœ¨æ²¡æœ‰æŒ‡å®šäººå‘˜æ˜Žç¡®è®¸å¯çš„æƒ…å†µä¸‹æ·»åŠ ã€‚ +在补ä¸ä¸æ·»åŠ æ ‡ç¾æ—¶è¦å°å¿ƒï¼šåªæœ‰Cc:æ‰é€‚åˆåœ¨æ²¡æœ‰æŒ‡å®šäººå‘˜æ˜Žç¡®è®¸å¯çš„æƒ…å†µä¸‹æ·»åŠ ã€‚ å‘é€è¡¥ä¸ -------- -在邮寄补ä¸ä¹‹å‰ï¼Œæ‚¨è¿˜éœ€è¦æ³¨æ„ä»¥ä¸‹å‡ ç‚¹ï¼š +在寄出补ä¸ä¹‹å‰ï¼Œæ‚¨è¿˜éœ€è¦æ³¨æ„ä»¥ä¸‹å‡ ç‚¹ï¼š - - 您确定您的邮件å‘é€ç¨‹åºä¸ä¼šæŸåè¡¥ä¸å—？有å…费的空白更改或由邮件客户端 - 执行的行包装的补ä¸ä¸ä¼šåœ¨å¦ä¸€ç«¯å¤åŽŸï¼Œå¹¶ä¸”通常ä¸ä¼šè¿›è¡Œä»»ä½•è¯¦ç»†æ£€æŸ¥ã€‚如果有 - 任何疑问，把补ä¸å¯„ç»™ä½ è‡ªå·±ï¼Œè®©ä½ è‡ªå·±ç›¸ä¿¡å®ƒæ˜¯å®Œå¥½æ— æŸçš„。 + - 您确定您的邮件å‘é€ç¨‹åºä¸ä¼šæŸåè¡¥ä¸å—ï¼Ÿè¢«é‚®ä»¶å®¢æˆ·ç«¯æ›´æ”¹ç©ºç™½æˆ–ä¿®é¥°äº†è¡Œçš„è¡¥ä¸ + æ— æ³•è¢«å¦ä¸€ç«¯æŽ¥å—，并且通常ä¸ä¼šè¿›è¡Œä»»ä½•è¯¦ç»†æ£€æŸ¥ã€‚如果有任何疑问，先把补ä¸å¯„ + ç»™ä½ è‡ªå·±ï¼Œè®©ä½ è‡ªå·±ç¡®å®šå®ƒæ˜¯å®Œå¥½æ— æŸçš„。 :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` - æ供了一些有用的æ示，å¯ä»¥è®©ç‰¹å®šçš„邮件客户机工作以å‘é€è¡¥ä¸ã€‚ + æ供了一些有用的æ示，å¯ä»¥è®©ç‰¹å®šçš„邮件客户端æ£å¸¸å‘é€è¡¥ä¸ã€‚ - - ä½ ç¡®å®šä½ çš„è¡¥ä¸æ²¡æœ‰æ„šè ¢çš„错误å—？您应该始终通过scripts/checkpatch.plè¿è¡Œ - è¡¥ä¸ç¨‹åºï¼Œå¹¶è§£å†³å®ƒæ出的投诉。请记ä½ï¼Œcheckpatch.pl虽然是大é‡æ€è€ƒå†…æ ¸ - è¡¥ä¸åº”è¯¥æ˜¯ä»€ä¹ˆæ ·å的体现，但它并ä¸æ¯”您èªæ˜Žã€‚如果修å¤checkpatch.pl投诉会 + - ä½ ç¡®å®šä½ çš„è¡¥ä¸æ²¡æœ‰è’å”的错误å—？您应该始终通过scripts/checkpatch.pl检查 + è¡¥ä¸ç¨‹åºï¼Œå¹¶è§£å†³å®ƒæ出的问题。请记ä½ï¼Œcheckpatch.plï¼Œè™½ç„¶ä½“çŽ°äº†å¯¹å†…æ ¸è¡¥ä¸ + åº”è¯¥æ˜¯ä»€ä¹ˆæ ·çš„å¤§é‡æ€è€ƒï¼Œä½†å®ƒå¹¶ä¸æ¯”您èªæ˜Žã€‚如果修å¤checkpatch.pl给的问题会 使代ç å˜å¾—更糟，请ä¸è¦è¿™æ ·åšã€‚ è¡¥ä¸åº”始终以纯文本形å¼å‘é€ã€‚请ä¸è¦å°†å®ƒä»¬ä½œä¸ºé™„件å‘é€ï¼›è¿™ä½¿å¾—审阅者在ç”å¤ä¸æ›´éš¾ 引用补ä¸çš„部分。相å，åªéœ€å°†è¡¥ä¸ç›´æŽ¥æ”¾åˆ°æ‚¨çš„消æ¯ä¸ã€‚ -邮寄补ä¸æ—¶ï¼Œé‡è¦çš„是将副本å‘é€ç»™ä»»ä½•å¯èƒ½æ„Ÿå…´è¶£çš„人。与其他一些项目ä¸åŒï¼Œå†…æ ¸ -鼓励人们错误地å‘é€è¿‡å¤šçš„副本；ä¸è¦å‡å®šç›¸å…³äººå‘˜ä¼šçœ‹åˆ°æ‚¨åœ¨é‚®ä»¶åˆ—表ä¸çš„å‘布。 +寄出补ä¸æ—¶ï¼Œé‡è¦çš„是将副本å‘é€ç»™ä»»ä½•å¯èƒ½æ„Ÿå…´è¶£çš„人。与其他一些项目ä¸åŒï¼Œå†…æ ¸ +鼓励人们甚至错误地å‘é€è¿‡å¤šçš„副本；ä¸è¦å‡å®šç›¸å…³äººå‘˜ä¼šçœ‹åˆ°æ‚¨åœ¨é‚®ä»¶åˆ—表ä¸çš„å‘布。 尤其是，副本应å‘é€è‡³ï¼š - - å—å½±å“å系统的维护人员。如å‰æ‰€è¿°ï¼Œç»´æŠ¤äººå‘˜æ–‡ä»¶æ˜¯æŸ¥æ‰¾è¿™äº›äººå‘˜çš„第一个地方。 + - å—å½±å“å系统的维护人员。如å‰æ‰€è¿°ï¼Œç»´æŠ¤äººå‘˜æ–‡ä»¶æ˜¯æŸ¥æ‰¾è¿™äº›äººå‘˜çš„首选地方。 - 其他在åŒä¸€é¢†åŸŸå·¥ä½œçš„å¼€å‘人员，尤其是那些现在å¯èƒ½åœ¨é‚£é‡Œå·¥ä½œçš„å¼€å‘人员。使用 git查看还有è°ä¿®æ”¹äº†æ‚¨æ£åœ¨å¤„ç†çš„文件，这很有帮助。 - - 如果您对错误报告或功能请求åšå‡ºå“应，也å¯ä»¥æŠ„é€åŽŸå§‹å‘é€äººã€‚ + - 如果您对æŸé”™è¯¯æŠ¥å‘Šæˆ–功能请求åšå‡ºå“应，也å¯ä»¥æŠ„é€åŽŸå§‹å‘é€äººã€‚ - - 将副本å‘é€åˆ°ç›¸å…³é‚®ä»¶åˆ—表，或者，如果没有其他应用，则å‘é€åˆ°Linuxå†…æ ¸åˆ—è¡¨ã€‚ + - 将副本å‘é€åˆ°ç›¸å…³é‚®ä»¶åˆ—è¡¨ï¼Œæˆ–è€…è‹¥æ— ç›¸å…³åˆ—è¡¨ï¼Œåˆ™å‘é€åˆ°linux-kernel列表。 - - 如果您æ£åœ¨ä¿®å¤ä¸€ä¸ªbug，请考虑该修å¤æ˜¯å¦åº”è¿›å…¥ä¸‹ä¸€ä¸ªç¨³å®šæ›´æ–°ã€‚å¦‚æžœæ˜¯è¿™æ ·ï¼Œ - stable@vger.kernel.org 应该得到补ä¸çš„副本。å¦å¤–，在补ä¸æœ¬èº«çš„æ ‡ç¾ä¸æ·»åŠ - 一个“cc:stable@vger.kernel.orgâ€ï¼›è¿™å°†ä½¿ç¨³å®šå›¢é˜Ÿåœ¨ä¿®å¤è¿›å…¥ä¸»çº¿æ—¶æ”¶åˆ°é€šçŸ¥ã€‚ + - 如果您æ£åœ¨ä¿®å¤ä¸€ä¸ªç¼ºé™·ï¼Œè¯·è€ƒè™‘该修å¤æ˜¯å¦åº”è¿›å…¥ä¸‹ä¸€ä¸ªç¨³å®šæ›´æ–°ã€‚å¦‚æžœæ˜¯è¿™æ ·ï¼Œ + è¡¥ä¸å‰¯æœ¬ä¹Ÿåº”å‘到stable@vger.kernel.org 。å¦å¤–，在补ä¸æœ¬èº«çš„æ ‡ç¾ä¸æ·»åŠ 一个 + “Cc: stable@vger.kernel.orgâ€ï¼›è¿™å°†ä½¿ç¨³å®šç‰ˆå›¢é˜Ÿåœ¨ä¿®å¤è¿›å…¥ä¸»çº¿æ—¶æ”¶åˆ°é€šçŸ¥ã€‚ -当为一个补ä¸é€‰æ‹©æŽ¥æ”¶è€…时，最好知é“ä½ è®¤ä¸ºè°æœ€ç»ˆä¼šæŽ¥å—这个补ä¸å¹¶å°†å…¶åˆå¹¶ã€‚虽然 -å¯ä»¥å°†è¡¥ä¸ç›´æŽ¥å‘é€ç»™LinusTorvalds并让他åˆå¹¶ï¼Œä½†é€šå¸¸æƒ…况下ä¸ä¼šè¿™æ ·åšã€‚Linus -很忙，并且有åç³»ç»Ÿç»´æŠ¤äººå‘˜è´Ÿè´£ç›‘è§†å†…æ ¸çš„ç‰¹å®šéƒ¨åˆ†ã€‚é€šå¸¸æ‚¨ä¼šå¸Œæœ›ç»´æŠ¤äººå‘˜åˆå¹¶æ‚¨ -çš„è¡¥ä¸ã€‚如果没有明显的维护人员，Andrew Morton通常是最åŽçš„è¡¥ä¸ç›®æ ‡ã€‚ +当为一个补ä¸é€‰æ‹©æŽ¥æ”¶è€…æ—¶ï¼Œæœ€å¥½æ¸…æ¥šä½ è®¤ä¸ºè°æœ€ç»ˆä¼šæŽ¥å—这个补ä¸å¹¶å°†å…¶åˆå¹¶ã€‚虽然 +å¯ä»¥å°†è¡¥ä¸ç›´æŽ¥å‘ç»™Linus Torvalds并让他åˆå¹¶ï¼Œä½†é€šå¸¸æƒ…况下ä¸ä¼šè¿™æ ·åšã€‚Linus很 +忙，并且有åç³»ç»Ÿç»´æŠ¤äººå‘˜è´Ÿè´£ç›‘è§†å†…æ ¸çš„ç‰¹å®šéƒ¨åˆ†ã€‚é€šå¸¸æ‚¨ä¼šå¸Œæœ›ç»´æŠ¤äººå‘˜åˆå¹¶æ‚¨çš„ +è¡¥ä¸ã€‚如果没有明显的维护人员，Andrew Morton通常是最åŽçš„è¡¥ä¸æŽ¥æ”¶è€…。 -è¡¥ä¸éœ€è¦å¥½çš„主题行。补ä¸ç¨‹åºè¡Œçš„è§„èŒƒæ ¼å¼å¦‚下： +è¡¥ä¸éœ€è¦å¥½çš„主题行。补ä¸ä¸»é¢˜è¡Œçš„è§„èŒƒæ ¼å¼å¦‚下： :: [PATCH nn/mm] subsys: one-line description of the patch -å…¶ä¸â€œnnâ€æ˜¯è¡¥ä¸çš„åºå·ï¼Œâ€œmmâ€æ˜¯ç³»åˆ—ä¸è¡¥ä¸çš„总数，“subsysâ€æ˜¯å—å½±å“å系统的å称。 -显然，一个å•ç‹¬çš„è¡¥ä¸å¯ä»¥çœç•¥nn/mm。 +å…¶ä¸â€œnnâ€æ˜¯è¡¥ä¸çš„åºå·ï¼Œâ€œmmâ€æ˜¯ç³»åˆ—ä¸è¡¥ä¸çš„总数，“subsysâ€æ˜¯å—å½±å“å系统的 +å称。当然，一个å•ç‹¬çš„è¡¥ä¸å¯ä»¥çœç•¥nn/mm。 -如果您有一系列é‡è¦çš„è¡¥ä¸ï¼Œé‚£ä¹ˆé€šå¸¸å°†ä»‹ç»æ€§æ述作为零部分å‘é€ã€‚ä¸è¿‡ï¼Œè¿™ç§çº¦å®š -并没有得到普ééµå¾ªï¼›å¦‚果您使用它，请记ä½ç®€ä»‹ä¸çš„ä¿¡æ¯ä¸ä¼šä½¿å®ƒè¿›å…¥å†…æ ¸å˜æ›´æ—¥å¿—。 +如果您有一系列é‡è¦çš„è¡¥ä¸ï¼Œé‚£ä¹ˆé€šå¸¸å‘é€ä¸€ä¸ªç®€ä»‹ä½œä¸ºç¬¬ã€‡éƒ¨åˆ†ã€‚ä¸è¿‡ï¼Œè¿™ä¸ªçº¦å®š +并没有得到普ééµå¾ªï¼›å¦‚果您使用它，请记ä½ç®€ä»‹ä¸çš„ä¿¡æ¯ä¸ä¼šè¿›å…¥å†…æ ¸å˜æ›´æ—¥å¿—。 å› æ¤ï¼Œè¯·ç¡®ä¿è¡¥ä¸æœ¬èº«å…·æœ‰å®Œæ•´çš„å˜æ›´æ—¥å¿—ä¿¡æ¯ã€‚ 一般æ¥è¯´ï¼Œå¤šéƒ¨åˆ†è¡¥ä¸çš„第二部分和åŽç»éƒ¨åˆ†åº”作为对第一部分的回å¤å‘é€ï¼Œä»¥ä¾¿å®ƒä»¬ 在接收端都连接在一起。åƒgitå’Œcoiltè¿™æ ·çš„å·¥å…·æœ‰å‘½ä»¤ï¼Œå¯ä»¥é€šè¿‡é€‚当的线程å‘é€ -一组补ä¸ã€‚但是，如果您有一个长系列，并且æ£åœ¨ä½¿ç”¨git，请远离–chain reply-to -选项，以é¿å…创建异常深的嵌套。 +一组补ä¸ã€‚但是，如果您有一长串补ä¸ï¼Œå¹¶æ£ä½¿ç”¨git，请ä¸è¦ä½¿ç”¨â€“-chain-reply-to +选项，以é¿å…创建过深的嵌套。 diff --git a/Documentation/translations/zh_CN/process/6.Followthrough.rst b/Documentation/translations/zh_CN/process/6.Followthrough.rst index f509e077e1cb..2a127e737b6a 100644 --- a/Documentation/translations/zh_CN/process/6.Followthrough.rst +++ b/Documentation/translations/zh_CN/process/6.Followthrough.rst @@ -1,145 +1,152 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/6.Followthrough.rst <development_followthrough>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _cn_development_followthrough: è·Ÿè¿› ==== -在这一点上，您已ç»éµå¾ªäº†åˆ°ç›®å‰ä¸ºæ¢ç»™å‡ºçš„指导方针，并且，éšç€æ‚¨è‡ªå·±çš„工程技能 -çš„å¢žåŠ ï¼Œå·²ç»å‘布了一系列完美的补ä¸ã€‚å³ä½¿æ˜¯ç»éªŒä¸°å¯Œçš„å†…æ ¸å¼€å‘人员也能犯的最大 -错误之一是，认为他们的工作现在已ç»å®Œæˆäº†ã€‚事实上，å‘布补ä¸æ„味ç€è¿›å…¥æµç¨‹çš„下 -一个阶段，å¯èƒ½è¿˜éœ€è¦åšå¾ˆå¤šå·¥ä½œã€‚ +æ¤æ—¶ï¼Œæ‚¨å·²ç»éµå¾ªäº†åˆ°ç›®å‰ä¸ºæ¢ç»™å‡ºçš„指导方针，并且，éšç€æ‚¨è‡ªå·±çš„å·¥ç¨‹æŠ€èƒ½çš„å¢žåŠ ï¼Œ +å·²ç»å‘布了一系列完美的补ä¸ã€‚å³ä½¿æ˜¯ç»éªŒä¸°å¯Œçš„å†…æ ¸å¼€å‘人员也能犯的最大错误之一 +是，认为他们的工作现在已ç»å®Œæˆäº†ã€‚事实上，å‘布补ä¸æ„味ç€è¿›å…¥æµç¨‹çš„下一个阶段， +å¯èƒ½è¿˜éœ€è¦åšå¾ˆå¤šå·¥ä½œã€‚ -一个补ä¸åœ¨ç¬¬ä¸€æ¬¡å‘布时就éžå¸¸å‡ºè‰²ï¼Œæ²¡æœ‰æ”¹è¿›çš„余地,这是很罕è§çš„ã€‚å†…æ ¸å¼€å‘æµç¨‹ -è®¤è¯†åˆ°è¿™ä¸€äº‹å®žï¼Œå› æ¤ï¼Œå®ƒéžå¸¸æ³¨é‡å¯¹å·²å‘布代ç 的改进。作为代ç 的作者，您应该与 +一个补ä¸åœ¨é¦–次å‘布时就éžå¸¸å‡ºè‰²ã€æ²¡æœ‰æ”¹è¿›çš„余地，这是很罕è§çš„ã€‚å†…æ ¸å¼€å‘æµç¨‹å·² +è®¤è¯†åˆ°è¿™ä¸€äº‹å®žï¼Œå› æ¤å®ƒéžå¸¸æ³¨é‡å¯¹å·²å‘布代ç 的改进。作为代ç 的作者，您应该与 å†…æ ¸ç¤¾åŒºåˆä½œï¼Œä»¥ç¡®ä¿æ‚¨çš„代ç 符åˆå†…æ ¸çš„è´¨é‡æ ‡å‡†ã€‚如果ä¸å‚与这个过程，很å¯èƒ½ä¼š -阻æ¢å°†è¡¥ä¸åŒ…å«åˆ°ä¸»çº¿ä¸ã€‚ +æ— æ³•å°†è¡¥ä¸åˆå¹¶åˆ°ä¸»çº¿ä¸ã€‚ 与审阅者åˆä½œ ------------ 任何æ„义上的补ä¸éƒ½ä¼šå¯¼è‡´å…¶ä»–å¼€å‘人员在审查代ç æ—¶å‘表大é‡è¯„è®ºã€‚å¯¹äºŽè®¸å¤šå¼€å‘ -人员æ¥è¯´ï¼Œä¸Žå®¡æŸ¥äººå‘˜åˆä½œå¯èƒ½æ˜¯å†…æ ¸å¼€å‘过程ä¸æœ€ä»¤äººç”Ÿç•çš„éƒ¨åˆ†ã€‚ä½†æ˜¯ï¼Œå¦‚æžœä½ +人员æ¥è¯´ï¼Œä¸Žå®¡é˜…人员åˆä½œå¯èƒ½æ˜¯å†…æ ¸å¼€å‘过程ä¸æœ€ä»¤äººç”Ÿç•çš„éƒ¨åˆ†ã€‚ä½†æ˜¯å¦‚æžœä½ è®°ä½ä¸€äº›äº‹æƒ…，生活会å˜å¾—容易得多： - - å¦‚æžœä½ å·²ç»å¾ˆå¥½åœ°è§£é‡Šäº†ä½ çš„è¡¥ä¸ï¼Œè¯„论人员会ç†è§£å®ƒçš„价值，以åŠä¸ºä»€ä¹ˆä½ 会 - 费尽心æ€åŽ»å†™å®ƒã€‚但是这个并ä¸èƒ½é˜»æ¢ä»–们æ出一个基本的问题：五年或åå¹´åŽ - 用这个代ç ç»´æŠ¤ä¸€ä¸ªå†…æ ¸ä¼šæ˜¯ä»€ä¹ˆæ„Ÿè§‰ï¼Ÿä½ å¯èƒ½è¢«è¦æ±‚åšå‡ºçš„许多改å˜â€”—从编ç é£Žæ ¼ - 的调整到大é‡çš„é‡å†™â€”—都æ¥è‡ªäºŽå¯¹Linuxçš„ç†è§£ï¼Œå³ä»ŽçŽ°åœ¨èµ·åå¹´åŽï¼ŒLinuxä»å°†åœ¨ - å¼€å‘ä¸ã€‚ + - å¦‚æžœä½ å·²ç»å¾ˆå¥½åœ°è§£é‡Šäº†ä½ çš„è¡¥ä¸ï¼Œå®¡é˜…人员会ç†è§£å®ƒçš„价值，以åŠä¸ºä»€ä¹ˆä½ 会 + 费尽心æ€åŽ»å†™å®ƒã€‚但是这个并ä¸èƒ½é˜»æ¢ä»–们æ出一个基本的问题：在五年或åå¹´åŽ + 维护å«æœ‰æ¤ä»£ç çš„å†…æ ¸ä¼šæ€Žä¹ˆæ ·ï¼Ÿä½ å¯èƒ½è¢«è¦æ±‚åšå‡ºçš„许多改å˜â€”—从编ç é£Žæ ¼çš„ + 调整到大é‡çš„é‡å†™â€”—都æ¥è‡ªäºŽå¯¹Linuxçš„ç†è§£ï¼Œå³ä»ŽçŽ°åœ¨èµ·åå¹´åŽï¼ŒLinuxä»å°† + 在开å‘ä¸ã€‚ - 代ç 审查是一项艰苦的工作，这是一项相对åƒåŠ›ä¸è®¨å¥½çš„工作；人们记得è°ç¼–写了 - å†…æ ¸ä»£ç ，但对于那些审查它的人æ¥è¯´ï¼Œå‡ 乎没有什么æŒä¹…çš„åå£°ã€‚å› æ¤ï¼Œè¯„论 + å†…æ ¸ä»£ç ，但对于那些审查它的人æ¥è¯´ï¼Œå‡ 乎没有什么长久的åå£°ã€‚å› æ¤ï¼Œå®¡é˜… 人员å¯èƒ½ä¼šå˜å¾—æš´èºï¼Œå°¤å…¶æ˜¯å½“他们看到åŒæ ·çš„错误被一éåˆä¸€é地犯下时。如果 - ä½ å¾—åˆ°äº†ä¸€ä¸ªçœ‹èµ·æ¥æ„¤æ€’ã€ä¾®è¾±æˆ–å®Œå…¨å†’çŠ¯ä½ çš„è¯„è®ºï¼ŒæŠµåˆ¶ä»¥åŒæ ·æ–¹å¼å›žåº”的冲动。 - 代ç 审查是关于代ç 的，而ä¸æ˜¯å…³äºŽäººçš„，代ç 审查人员ä¸ä¼šäº²è‡ªæ”»å‡»æ‚¨ã€‚ + ä½ å¾—åˆ°äº†ä¸€ä¸ªçœ‹èµ·æ¥æ„¤æ€’ã€ä¾®è¾±æˆ–å®Œå…¨å†’çŠ¯ä½ çš„è¯„è®ºï¼Œè¯·æŠ‘åˆ¶ä»¥åŒæ ·æ–¹å¼å›žåº”的冲动。 + 代ç 审查是关于代ç 的，而ä¸æ˜¯å…³äºŽäººçš„，代ç 审阅人员ä¸ä¼šäº²è‡ªæ”»å‡»æ‚¨ã€‚ - - åŒæ ·ï¼Œä»£ç 审查人员也ä¸æƒ³ä»¥ç‰ºç‰²ä½ 雇主的利益为代价æ¥å®£ä¼ 他们雇主的议程。 + - åŒæ ·ï¼Œä»£ç 审阅人员也ä¸æƒ³ä»¥ç‰ºç‰²ä½ 雇主的利益为代价æ¥å®£ä¼ 他们雇主的议程。 å†…æ ¸å¼€å‘人员通常希望今åŽå‡ å¹´èƒ½åœ¨å†…æ ¸ä¸Šå·¥ä½œï¼Œä½†ä»–ä»¬æ˜Žç™½ä»–ä»¬çš„é›‡ä¸»å¯èƒ½ä¼šæ”¹ å˜ã€‚ä»–ä»¬çœŸçš„ï¼Œå‡ ä¹Žæ¯«æ— ä¾‹å¤–åœ°ï¼Œè‡´åŠ›äºŽåˆ›é€ ä»–ä»¬æ‰€èƒ½åšåˆ°çš„æœ€å¥½çš„å†…æ ¸ï¼›ä»–ä»¬å¹¶ æ²¡æœ‰è¯•å›¾ç»™é›‡ä¸»çš„ç«žäº‰å¯¹æ‰‹é€ æˆä¸é€‚。 -æ‰€æœ‰è¿™äº›å½’æ ¹ç»“åº•éƒ½æ˜¯ï¼Œå½“å®¡é˜…è€…å‘您å‘é€è¯„论时，您需è¦æ³¨æ„他们æ£åœ¨è¿›è¡Œçš„技术 -观察。ä¸è¦è®©ä»–们的表达方å¼æˆ–ä½ è‡ªå·±çš„éª„å‚²é˜»æ¢è¿™ç§äº‹æƒ…çš„å‘ç”Ÿã€‚å½“ä½ åœ¨ä¸€ä¸ªè¡¥ä¸ -上得到评论时，花点时间去ç†è§£è¯„论人想说什么。如果å¯èƒ½çš„è¯ï¼Œè¯·ä¿®å¤å®¡é˜…者è¦æ±‚ -您修å¤çš„内容。然åŽå›žå¤å®¡ç¨¿äººï¼šè°¢è°¢ä»–们，并æè¿°ä½ å°†å¦‚ä½•å›žç”他们的问题。 +æ‰€æœ‰è¿™äº›å½’æ ¹ç»“åº•å°±æ˜¯ï¼Œå½“å®¡é˜…è€…å‘您å‘é€è¯„论时，您需è¦æ³¨æ„他们æ£åœ¨è¿›è¡Œçš„技术 +评论。ä¸è¦è®©ä»–们的表达方å¼æˆ–ä½ è‡ªå·±çš„éª„å‚²é˜»æ¢æ¤äº‹ã€‚å½“ä½ åœ¨ä¸€ä¸ªè¡¥ä¸ä¸Šå¾—到评论 +时，花点时间去ç†è§£è¯„论人想说什么。如果å¯èƒ½çš„è¯ï¼Œè¯·ä¿®å¤å®¡é˜…者è¦æ±‚您修å¤çš„内 +容。然åŽå›žå¤å®¡é˜…者：谢谢他们，并æè¿°ä½ å°†å¦‚ä½•å›žç”他们的问题。 请注æ„，您ä¸å¿…åŒæ„审阅者建议的æ¯ä¸ªæ›´æ”¹ã€‚如果您认为审阅者误解了您的代ç ，请 解释到底å‘生了什么。如果您对建议的更改有技术上的异议，请æ述它并è¯æ˜Žæ‚¨å¯¹è¯¥ -问题的解决方案是æ£ç¡®çš„ã€‚å¦‚æžœä½ çš„è§£é‡Šæœ‰é“ç†ï¼Œå®¡ç¨¿äººä¼šæŽ¥å—的。ä¸è¿‡ï¼Œå¦‚æžœä½ çš„ -解释ä¸èƒ½è¯æ˜Žæ˜¯æœ‰è¯´æœåŠ›çš„，尤其是当其他人开始åŒæ„审稿人的观点时，请花些时间 -é‡æ–°è€ƒè™‘ä¸€ä¸‹ã€‚ä½ å¾ˆå®¹æ˜“å¯¹è‡ªå·±è§£å†³é—®é¢˜çš„æ–¹æ³•è§†è€Œä¸è§ï¼Œä»¥è‡³äºŽä½ 没有æ„识到æŸä¸ª -é—®é¢˜æ ¹æœ¬æ˜¯é”™è¯¯çš„ï¼Œæˆ–è€…ä½ ç”šè‡³æ²¡æœ‰è§£å†³æ£ç¡®çš„问题。 +问题的解决方案是æ£ç¡®çš„ã€‚å¦‚æžœä½ çš„è§£é‡Šæœ‰é“ç†ï¼Œå®¡é˜…者会接å—的。ä¸è¿‡ï¼Œå¦‚æžœä½ çš„ +解释è¯æ˜Žç¼ºä¹è¯´æœåŠ›ï¼Œå°¤å…¶æ˜¯å½“其他人开始åŒæ„审稿人的观点时，请花些时间é‡æ–°è€ƒè™‘ +ä¸€ä¸‹ã€‚ä½ å¾ˆå®¹æ˜“å¯¹è‡ªå·±è§£å†³é—®é¢˜çš„æ–¹æ³•è§†è€Œä¸è§ï¼Œä»¥è‡³äºŽä½ 没有æ„识到æŸäº›ä¸œè¥¿å®Œå…¨ +æ˜¯é”™è¯¯çš„ï¼Œæˆ–è€…ä½ ç”šè‡³æ²¡æœ‰è§£å†³æ£ç¡®çš„问题。 -Andrew Morton建议，æ¯ä¸€æ¡ä¸ä¼šå¯¼è‡´ä»£ç 更改的评论都应该导致é¢å¤–的代ç 注释； -è¿™å¯ä»¥å¸®åŠ©æœªæ¥çš„评论人员é¿å…出现第一次出现的问题。 +Andrew Morton建议，æ¯ä¸€ä¸ªä¸ä¼šå¯¼è‡´ä»£ç 更改的审阅评论都应该产生一个é¢å¤–的代ç +注释；这å¯ä»¥å¸®åŠ©æœªæ¥çš„审阅人员é¿å…第一次出现的问题。 -一个致命的错误是忽视评论，希望它们会消失。他们ä¸ä¼šèµ°çš„ã€‚å¦‚æžœæ‚¨åœ¨æ²¡æœ‰å¯¹ä¹‹å‰ -收到的注释åšå‡ºå“应的情况下é‡æ–°å‘布代ç ，那么很å¯èƒ½ä¼šå‘现补ä¸æ¯«æ— 用处。 +一个致命的错误是忽视评论，希望它们会消失。它们ä¸ä¼šèµ°çš„ã€‚å¦‚æžœæ‚¨åœ¨æ²¡æœ‰å¯¹ä¹‹å‰ +收到的评论åšå‡ºå“应的情况下é‡æ–°å‘布代ç ，那么很å¯èƒ½ä¼šå‘现补ä¸æ¯«æ— 用处。 说到é‡æ–°å‘布代ç ：请记ä½ï¼Œå®¡é˜…者ä¸ä¼šè®°ä½æ‚¨ä¸Šæ¬¡å‘布的代ç çš„æ‰€æœ‰ç»†èŠ‚ã€‚å› æ¤ï¼Œ -æ醒审查人员以å‰æ出的问题以åŠæ‚¨å¦‚何处ç†è¿™äº›é—®é¢˜æ€»æ˜¯ä¸€ä¸ªå¥½ä¸»æ„；补ä¸å˜æ›´ +æ醒审阅人员以å‰æ出的问题以åŠæ‚¨å¦‚何处ç†è¿™äº›é—®é¢˜æ€»æ˜¯ä¸€ä¸ªå¥½ä¸»æ„；补ä¸å˜æ›´ 日志是æä¾›æ¤ç±»ä¿¡æ¯çš„好地方。审阅者ä¸å¿…æœç´¢åˆ—表档案æ¥ç†Ÿæ‚‰ä¸Šæ¬¡æ‰€è¯´çš„内容； -如果您帮助他们开始è¿è¡Œï¼Œå½“他们é‡æ–°è®¿é—®æ‚¨çš„代ç 时，他们的心情会更好。 +如果您帮助他们直接开始，当他们é‡æ–°æŸ¥çœ‹æ‚¨çš„代ç 时，心情会更好。 å¦‚æžœä½ å·²ç»è¯•ç€åšæ£ç¡®çš„事情，但事情ä»ç„¶æ²¡æœ‰è¿›å±•å‘¢ï¼Ÿå¤§å¤šæ•°æŠ€æœ¯ä¸Šçš„分æ§éƒ½å¯ä»¥ -通过讨论æ¥è§£å†³ï¼Œä½†æœ‰æ—¶äººä»¬åªéœ€è¦åšå‡ºå†³å®šã€‚å¦‚æžœä½ çœŸçš„è®¤ä¸ºè¿™ä¸ªå†³å®šå¯¹ä½ ä¸åˆ©ï¼Œ -ä½ å¯ä»¥è¯•ç€å‘更高的æƒåŠ›ä¸Šè¯‰ã€‚åœ¨è¿™ç¯‡æ–‡ç« ä¸ï¼Œæ›´é«˜çš„æƒåŠ›å€¾å‘于Andrew Morton。 -Andrewåœ¨å†…æ ¸å¼€å‘社区ä¸å—i很大的尊é‡ï¼›ä»–ç»å¸¸ä¸ºä¼¼ä¹Žè¢«ç»æœ›åœ°é˜»å¡žäº‹æƒ…清障。 -尽管如æ¤ï¼Œå¯¹Andrew的呼åä¸åº”轻而易举，也ä¸åº”åœ¨æ‰€æœ‰å…¶ä»–æ›¿ä»£æ–¹æ¡ˆéƒ½è¢«æŽ¢ç´¢ä¹‹å‰ -使用。当然，记ä½ï¼Œä»–也å¯èƒ½ä¸åŒæ„ä½ çš„æ„è§ã€‚ +通过讨论æ¥è§£å†³ï¼Œä½†æœ‰æ—¶äººä»¬ä»éœ€è¦åšå‡ºå†³å®šã€‚å¦‚æžœä½ çœŸçš„è®¤ä¸ºè¿™ä¸ªå†³å®šå¯¹ä½ ä¸åˆ©ï¼Œ +ä½ å¯ä»¥è¯•ç€å‘有更高æƒåŠ›çš„人上诉。对于本文，更高æƒåŠ›çš„人是 Andrew Morton 。 +Andrew åœ¨å†…æ ¸å¼€å‘社区ä¸éžå¸¸å—尊敬；他ç»å¸¸ä¸ºä¼¼ä¹Žè¢«ç»æœ›é˜»å¡žçš„事情清障。尽管 +如æ¤ï¼Œä¸åº”轻易就直接找 Andrew ，也ä¸åº”在所有其他替代方案都被å°è¯•ä¹‹å‰æ‰¾ä»–。 +当然，记ä½ï¼Œä»–也å¯èƒ½ä¸åŒæ„ä½ çš„æ„è§ã€‚ 接下æ¥ä¼šå‘生什么 ---------------- -如果一个补ä¸è¢«è®¤ä¸ºæ˜¯æ·»åŠ åˆ°å†…æ ¸ä¸çš„一件好事，并且一旦大多数审查问题得到解决， -下一æ¥é€šå¸¸æ˜¯è¿›å…¥åç³»ç»Ÿç»´æŠ¤äººå‘˜çš„æ ‘ä¸ã€‚工作方å¼å› å系统而异；æ¯ä¸ªç»´æŠ¤äººå‘˜éƒ½ -有自己的工作方å¼ã€‚特别是，å¯èƒ½æœ‰ä¸æ¢ä¸€æ£µæ ‘â€”â€”ä¸€æ£µæ ‘ï¼Œä¹Ÿè®¸ï¼Œä¸“é—¨ç”¨äºŽè®¡åˆ’ä¸‹ä¸€ -个åˆå¹¶çª—å£çš„è¡¥ä¸ï¼Œå¦ä¸€æ£µæ ‘用于长期工作。 +如果一个补ä¸è¢«è®¤ä¸ºé€‚åˆæ·»åŠ åˆ°å†…æ ¸ä¸ï¼Œå¹¶ä¸”大多数审查问题得到解决，下一æ¥é€šå¸¸ +是进入åç³»ç»Ÿç»´æŠ¤äººå‘˜çš„æ ‘ä¸ã€‚工作方å¼å› å系统而异；æ¯ä¸ªç»´æŠ¤äººå‘˜éƒ½æœ‰è‡ªå·±çš„ +工作方å¼ã€‚特别是å¯èƒ½æœ‰ä¸æ¢ä¸€æ£µæ ‘â€”â€”ä¹Ÿè®¸ä¸€æ£µæ ‘ä¸“é—¨ç”¨äºŽè®¡åˆ’ä¸‹ä¸€ä¸ªåˆå¹¶çª—å£çš„ +è¡¥ä¸ï¼Œå¦ä¸€æ£µæ ‘用于长期工作。 -对于应用于没有明显åç³»ç»Ÿæ ‘ï¼ˆä¾‹å¦‚å†…å˜ç®¡ç†ä¿®è¡¥ç¨‹åºï¼‰çš„区域的修补程åºï¼Œé»˜è®¤æ ‘ -通常以-mm结尾。影å“多个å系统的补ä¸ä¹Ÿå¯ä»¥æœ€ç»ˆé€šè¿‡-mmæ ‘ã€‚ +对于应用到ä¸å±žäºŽæ˜Žæ˜¾åç³»ç»Ÿæ ‘ï¼ˆä¾‹å¦‚å†…å˜ç®¡ç†ä¿®è¡¥ç¨‹åºï¼‰çš„区域的修补程åºï¼Œé»˜è®¤æ ‘ +通常上溯到-mm。影å“多个å系统的补ä¸ä¹Ÿå¯ä»¥æœ€ç»ˆè¿›å…¥-mmæ ‘ã€‚ 包å«åœ¨åç³»ç»Ÿæ ‘ä¸å¯ä»¥æ高补ä¸çš„å¯è§æ€§ã€‚çŽ°åœ¨ï¼Œä½¿ç”¨è¯¥æ ‘çš„å…¶ä»–å¼€å‘人员将默认获 å¾—è¡¥ä¸ã€‚åç³»ç»Ÿæ ‘é€šå¸¸ä¹Ÿä¸ºLinuxæ供支æŒï¼Œä½¿å…¶å†…容对整个开å‘社区å¯è§ã€‚在这一点 上，您很å¯èƒ½ä¼šä»Žä¸€ç»„新的审阅者那里得到更多的评论；这些评论需è¦åƒä¸Šä¸€è½®é‚£æ · -得到回ç”。 +得到回应。 -在这一点上也会å‘生什么，这å–å†³äºŽä½ çš„è¡¥ä¸çš„性质，是与其他人æ£åœ¨åšçš„工作å‘生 +在这时也会å‘生点什么，这å–å†³äºŽä½ çš„è¡¥ä¸çš„性质，是å¦ä¸Žå…¶ä»–人æ£åœ¨åšçš„工作å‘生 冲çªã€‚在最å的情况下，严é‡çš„è¡¥ä¸å†²çªå¯èƒ½ä¼šå¯¼è‡´ä¸€äº›å·¥ä½œè¢«æç½®ï¼Œä»¥ä¾¿å‰©ä½™çš„è¡¥ä¸ å¯ä»¥æˆå½¢å¹¶åˆå¹¶ã€‚å¦ä¸€äº›æ—¶å€™ï¼Œå†²çªè§£å†³å°†æ¶‰åŠåˆ°ä¸Žå…¶ä»–å¼€å‘人员åˆä½œï¼Œå¯èƒ½è¿˜ä¼š åœ¨æ ‘ä¹‹é—´ç§»åŠ¨ä¸€äº›è¡¥ä¸ï¼Œä»¥ç¡®ä¿æ‰€æœ‰çš„应用都是干净的。这项工作å¯èƒ½æ˜¯ä¸€ä»¶ç—›è‹¦çš„ -事情，但è¦è®¡ç®—您的ç¦ç¥‰ï¼šåœ¨Linuxä¸‹ä¸€æ£µæ ‘å‡ºçŽ°ä¹‹å‰ï¼Œè¿™äº›å†²çªé€šå¸¸åªåœ¨åˆå¹¶çª—å£ -ä¸å‡ºçŽ°ï¼Œå¿…须迅速解决。现在å¯ä»¥åœ¨åˆå¹¶çª—å£æ‰“开之å‰ï¼Œåœ¨ç©ºé—²æ—¶è§£å†³è¿™äº›é—®é¢˜ã€‚ +事情，但也需庆幸现在的幸ç¦ï¼šåœ¨linux-nextæ ‘å‡ºçŽ°ä¹‹å‰ï¼Œè¿™äº›å†²çªé€šå¸¸åªåœ¨åˆå¹¶çª—å£ +ä¸å‡ºçŽ°ï¼Œå¿…须迅速解决。现在å¯ä»¥åœ¨åˆå¹¶çª—å£æ‰“开之å‰çš„空闲时间解决这些问题。 有æœä¸€æ—¥ï¼Œå¦‚果一切顺利，您将登录并看到您的补ä¸å·²ç»åˆå¹¶åˆ°ä¸»çº¿å†…æ ¸ä¸ã€‚ç¥è´ºä½ ï¼ -然而，一旦庆ç¥æ´»åŠ¨å®Œæˆï¼ˆå¹¶ä¸”您已ç»å°†è‡ªå·±æ·»åŠ 到维护人员文件ä¸ï¼‰ï¼Œå°±å€¼å¾—è®°ä½ -一个é‡è¦çš„å°äº‹å®žï¼šå·¥ä½œä»ç„¶æ²¡æœ‰å®Œæˆã€‚并入主线带æ¥äº†è‡ªèº«çš„挑战。 +然而，一旦庆ç¥å®Œäº†ï¼ˆå¹¶ä¸”您已ç»å°†è‡ªå·±æ·»åŠ 到维护人员文件ä¸ï¼‰ï¼Œå°±ä¸€å®šè¦è®°ä½ +一个é‡è¦çš„å°äº‹å®žï¼šå·¥ä½œä»ç„¶æ²¡æœ‰å®Œæˆã€‚并入主线也带æ¥äº†å®ƒçš„挑战。 -首先，补ä¸çš„å¯è§æ€§å†æ¬¡æ高。å¯èƒ½ä¼šæœ‰æ–°ä¸€è½®çš„å¼€å‘者评论，他们以å‰ä¸çŸ¥é“è¿™ -个补ä¸ã€‚忽略它们å¯èƒ½å¾ˆæœ‰è¯±æƒ‘åŠ›ï¼Œå› ä¸ºæ‚¨çš„ä»£ç ä¸å†å˜åœ¨ä»»ä½•è¢«åˆå¹¶çš„问题。但是， -è¦æŠµåˆ¶è¿™ç§è¯±æƒ‘，您ä»ç„¶éœ€è¦å¯¹æœ‰é—®é¢˜æˆ–建议的开å‘人员作出å“应。 +首先，补ä¸çš„å¯è§æ€§å†æ¬¡æ高。å¯èƒ½ä¼šæœ‰ä»¥å‰ä¸çŸ¥é“这个补ä¸çš„å¼€å‘者的新一轮评论。 +忽略它们å¯èƒ½å¾ˆæœ‰è¯±æƒ‘åŠ›ï¼Œå› ä¸ºæ‚¨çš„ä»£ç ä¸å†å˜åœ¨ä»»ä½•è¢«åˆå¹¶çš„问题。但是，è¦æŠµåˆ¶ +è¿™ç§è¯±æƒ‘，您ä»ç„¶éœ€è¦å¯¹æœ‰é—®é¢˜æˆ–建议的开å‘人员作出å“应。 -ä¸è¿‡ï¼Œæ›´é‡è¦çš„是：将代ç 包å«åœ¨ä¸»çº¿ä¸ä¼šå°†ä»£ç 交给更大的一组测试人员。å³ä½¿æ‚¨ -为尚未æ供的硬件æ供了驱动程åºï¼Œæ‚¨ä¹Ÿä¼šæƒŠè®¶äºŽæœ‰å¤šå°‘人会将您的代ç æž„å»ºåˆ°å†…æ ¸ -ä¸ã€‚当然，如果有测试人员，也会有错误报告。 +ä¸è¿‡ï¼Œæ›´é‡è¦çš„是：将代ç 包å«åœ¨ä¸»çº¿ä¸ä¼šå°†ä»£ç 交给更多的一些测试人员。å³ä½¿æ‚¨ +为尚未å¯ç”¨çš„硬件æ供了驱动程åºï¼Œæ‚¨ä¹Ÿä¼šæƒŠè®¶äºŽæœ‰å¤šå°‘人会将您的代ç æž„å»ºåˆ°å†…æ ¸ +ä¸ã€‚当然，如果有测试人员，也å¯èƒ½ä¼šæœ‰é”™è¯¯æŠ¥å‘Šã€‚ -æœ€ç³Ÿç³•çš„é”™è¯¯æŠ¥å‘Šæ˜¯å›žå½’ã€‚å¦‚æžœä½ çš„è¡¥ä¸å¯¼è‡´å›žå½’ï¼Œä½ ä¼šå‘现很多ä¸èˆ’æœçš„眼ç›ç›¯ç€ -ä½ ï¼›å›žå½’éœ€è¦å°½å¿«ä¿®å¤ã€‚如果您ä¸æ„¿æ„æˆ–æ— æ³•ä¿®å¤å›žå½’（其他人都ä¸ä¼šä¸ºæ‚¨ä¿®å¤ï¼‰ï¼Œ +æœ€ç³Ÿç³•çš„é”™è¯¯æŠ¥å‘Šæ˜¯å›žå½’ã€‚å¦‚æžœä½ çš„è¡¥ä¸å¯¼è‡´å›žå½’ï¼Œä½ ä¼šå‘çŽ°å¤šåˆ°è®©ä½ ä¸èˆ’æœçš„眼ç›ç›¯ +ç€ä½ ；回归需è¦å°½å¿«ä¿®å¤ã€‚如果您ä¸æ„¿æ„æˆ–æ— æ³•ä¿®å¤å›žå½’（其他人都ä¸ä¼šä¸ºæ‚¨ä¿®å¤ï¼‰ï¼Œ 那么在稳定期内，您的补ä¸å‡ 乎肯定会被移除。除了å¦å®šæ‚¨ä¸ºä½¿è¡¥ä¸è¿›å…¥ä¸»çº¿æ‰€åšçš„ -所有工作之外，如果由于未能修å¤å›žå½’而å–消补ä¸ï¼Œå¾ˆå¯èƒ½ä¼šä½¿å°†æ¥çš„工作更难åˆå¹¶ã€‚ +所有工作之外，如果由于未能修å¤å›žå½’而å–消补ä¸ï¼Œå¾ˆå¯èƒ½ä¼šä½¿å°†æ¥çš„工作更难被åˆå¹¶ã€‚ -在处ç†å®Œä»»ä½•å›žå½’之åŽï¼Œå¯èƒ½è¿˜æœ‰å…¶ä»–普通的bug需è¦å¤„ç†ã€‚稳定期是修å¤è¿™äº›é”™è¯¯å¹¶ -ç¡®ä¿ä»£ç åœ¨ä¸»çº¿å†…æ ¸ç‰ˆæœ¬ä¸çš„首次å‘布尽å¯èƒ½å¯é 的最好机会。所以，请回ç”错误 +在处ç†å®Œä»»ä½•å›žå½’之åŽï¼Œå¯èƒ½è¿˜æœ‰å…¶ä»–普通缺陷需è¦å¤„ç†ã€‚稳定期是修å¤è¿™äº›é”™è¯¯å¹¶ +ç¡®ä¿ä»£ç åœ¨ä¸»çº¿å†…æ ¸ç‰ˆæœ¬ä¸çš„首次å‘布尽å¯èƒ½å¯é 的最好机会。所以，请回应错误 报告，并尽å¯èƒ½è§£å†³é—®é¢˜ã€‚这就是稳定期的目的；一旦解决了旧补ä¸çš„任何问题，就 -å¯ä»¥å¼€å§‹åˆ›å»ºé…·çš„æ–°è¡¥ä¸ã€‚ +å¯ä»¥å¼€å§‹å°½æƒ…创建新补ä¸ã€‚ -别忘了，还有其他里程碑也å¯èƒ½ä¼šåˆ›å»ºbug报告：下一个主线稳定版本，当著åçš„å‘è¡Œ -商选择包å«è¡¥ä¸çš„å†…æ ¸ç‰ˆæœ¬æ—¶ï¼Œç‰ç‰ã€‚继ç»å“应这些报告是您工作的基本骄傲。但是， -如果这ä¸æ˜¯è¶³å¤Ÿçš„动机，那么也值得考虑的是，开å‘社区会记ä½é‚£äº›åœ¨åˆå¹¶åŽå¯¹ä»£ç -失去兴趣的开å‘äººå‘˜ã€‚ä¸‹ä¸€æ¬¡ä½ å‘布补ä¸æ—¶ï¼Œä»–ä»¬ä¼šä»¥ä½ ä»¥åŽä¸ä¼šåœ¨èº«è¾¹ç»´æŠ¤å®ƒä¸ºå‡ -设æ¥è¯„估它。 +别忘了，还有其他节点也å¯èƒ½ä¼šåˆ›å»ºç¼ºé™·æŠ¥å‘Šï¼šä¸‹ä¸€ä¸ªä¸»çº¿ç¨³å®šç‰ˆæœ¬ï¼Œå½“è‘—åçš„å‘è¡Œ +商选择包å«æ‚¨è¡¥ä¸çš„å†…æ ¸ç‰ˆæœ¬æ—¶ç‰ç‰ã€‚继ç»å“åº”è¿™äº›æŠ¥å‘Šæ˜¯æ‚¨å·¥ä½œçš„åŸºæœ¬ç´ å…»ã€‚ä½†æ˜¯ +如果这ä¸èƒ½æ供足够的动机，那么也需è¦è€ƒè™‘：开å‘社区会记ä½é‚£äº›åœ¨åˆå¹¶åŽå¯¹ä»£ç +失去兴趣的开å‘äººå‘˜ã€‚ä¸‹ä¸€æ¬¡ä½ å‘布补ä¸æ—¶ï¼Œä»–ä»¬ä¼šä»¥ä½ ä»¥åŽä¸ä¼šæŒç»ç»´æŠ¤å®ƒä¸ºå‰æ +æ¥è¯„估它。 其他å¯èƒ½å‘生的事情 ------------------ -æœ‰ä¸€å¤©ï¼Œä½ å¯ä»¥æ‰“å¼€ä½ çš„é‚®ä»¶å®¢æˆ·ç«¯ï¼Œçœ‹åˆ°æœ‰äººç»™ä½ å¯„äº†ä¸€ä¸ªä»£ç è¡¥ä¸ã€‚毕竟，这是 +æŸå¤©ï¼Œå½“ä½ æ‰“å¼€ä½ çš„é‚®ä»¶å®¢æˆ·ç«¯æ—¶ï¼Œçœ‹åˆ°æœ‰äººç»™ä½ å¯„äº†ä¸€ä¸ªä»£ç è¡¥ä¸ã€‚毕竟，这是 让您的代ç 公开å˜åœ¨çš„好处之一。如果您åŒæ„这个补ä¸ï¼Œæ‚¨å¯ä»¥å°†å®ƒè½¬å‘ç»™å系统 -维护人员（确ä¿åŒ…å«ä¸€ä¸ªæ£ç¡®çš„From:è¡Œï¼Œè¿™æ ·å±žæ€§æ˜¯æ£ç¡®çš„ï¼Œå¹¶æ·»åŠ ä¸€ä¸ªæ‚¨è‡ªå·± -çš„ç¾å‡†ï¼‰ï¼Œæˆ–者回å¤ä¸€ä¸ªAcked-by，让原始å‘é€è€…å‘上å‘é€å®ƒã€‚ +维护人员（确ä¿åŒ…å«ä¸€ä¸ªæ£ç¡®çš„From:è¡Œï¼Œè¿™æ ·å±žæ€§æ˜¯æ£ç¡®çš„ï¼Œå¹¶æ·»åŠ ä¸€ä¸ªæ‚¨è‡ªå·±çš„ +signoff ），或者回å¤ä¸€ä¸ª Acked-by: 让原始å‘é€è€…å‘上å‘é€å®ƒã€‚ -如果您ä¸åŒæ„è¡¥ä¸ï¼Œè¯·å‘é€ä¸€ä¸ªç¤¼è²Œçš„回å¤ï¼Œè§£é‡ŠåŽŸå› 。如果å¯èƒ½çš„è¯ï¼Œå‘Šè¯‰ä½œè€…éœ€è¦ -åšå“ªäº›æ›´æ”¹æ‰èƒ½è®©æ‚¨æŽ¥å—è¡¥ä¸ã€‚对于代ç 的编写者和维护者所å对的åˆå¹¶è¡¥ä¸ï¼Œå˜åœ¨ç€ -一定的阻力，但仅æ¤è€Œå·²ã€‚å¦‚æžœä½ è¢«è®¤ä¸ºä¸å¿…è¦çš„阻ç¢äº†å¥½çš„工作，那么这些补ä¸æœ€ -终会ç»è¿‡ä½ 身边并进入主线。在Linuxå†…æ ¸ä¸ï¼Œæ²¡æœ‰äººå¯¹ä»»ä½•ä»£ç 拥有ç»å¯¹çš„å¦å†³æƒã€‚ -除了Linus。 +如果您ä¸åŒæ„è¡¥ä¸ï¼Œè¯·ç¤¼è²Œåœ°å›žå¤ï¼Œè§£é‡ŠåŽŸå› 。如果å¯èƒ½çš„è¯ï¼Œå‘Šè¯‰ä½œè€…需è¦åšå“ªäº› +更改æ‰èƒ½è®©æ‚¨æŽ¥å—è¡¥ä¸ã€‚åˆå¹¶ä»£ç 的编写者和维护者所å对的补ä¸çš„ç¡®å˜åœ¨ç€ä¸€å®šçš„ +阻力，但仅æ¤è€Œå·²ã€‚å¦‚æžœä½ è¢«è®¤ä¸ºä¸å¿…è¦çš„阻ç¢äº†å¥½çš„工作，那么这些补ä¸æœ€ç»ˆä¼š +ç»•è¿‡ä½ å¹¶è¿›å…¥ä¸»çº¿ã€‚åœ¨Linuxå†…æ ¸ä¸ï¼Œæ²¡æœ‰äººå¯¹ä»»ä½•ä»£ç 拥有ç»å¯¹çš„å¦å†³æƒã€‚å¯èƒ½é™¤ +了Linus。 在éžå¸¸ç½•è§çš„情况下，您å¯èƒ½ä¼šçœ‹åˆ°å®Œå…¨ä¸åŒçš„东西：å¦ä¸€ä¸ªå¼€å‘人员å‘布了针对您 -的问题的ä¸åŒè§£å†³æ–¹æ¡ˆã€‚在这一点上，两个补ä¸ä¸çš„一个å¯èƒ½ä¸ä¼šåˆå¹¶ï¼Œâ€œæˆ‘的在这里 -是第一个â€ä¸è¢«è®¤ä¸ºæ˜¯ä¸€ä¸ªä»¤äººä¿¡æœçš„技术论æ®ã€‚如果有人的补ä¸å–ä»£äº†ä½ çš„è¡¥ä¸è€Œè¿› -入了主线，那么åªæœ‰ä¸€ç§æ–¹æ³•å¯ä»¥å›žåº”ä½ ï¼šé«˜å…´ä½ çš„é—®é¢˜å¾—åˆ°è§£å†³ï¼Œç»§ç»ä½ 的工作。 -以这ç§æ–¹å¼æŠŠä¸€ä¸ªäººçš„工作推到一边å¯èƒ½ä¼šä¼¤å®³å’Œæ°”é¦ï¼Œä½†æ˜¯åœ¨ä»–们忘记了è°çš„è¡¥ä¸ -真æ£è¢«åˆå¹¶å¾ˆä¹…之åŽï¼Œç¤¾åŒºä¼šè®°ä½ä½ çš„å应。 +的问题的ä¸åŒè§£å†³æ–¹æ¡ˆã€‚在这时，两个补ä¸ä¹‹ä¸€å¯èƒ½ä¸ä¼šè¢«åˆå¹¶ï¼Œâ€œæˆ‘çš„è¡¥ä¸é¦–å…ˆ +å‘布â€ä¸è¢«è®¤ä¸ºæ˜¯ä¸€ä¸ªä»¤äººä¿¡æœçš„技术论æ®ã€‚如果有别人的补ä¸å–ä»£äº†ä½ çš„è¡¥ä¸è€Œè¿› +入了主线，那么åªæœ‰ä¸€ç§æ–¹æ³•å¯ä»¥å›žåº”ä½ ï¼šå¾ˆé«˜å…´ä½ çš„é—®é¢˜è§£å†³äº†ï¼Œè¯·ç»§ç»å·¥ä½œå§ã€‚ +以这ç§æ–¹å¼æŠŠæŸäººçš„工作推到一边å¯èƒ½å¯¼è‡´ä¼¤å¿ƒå’Œæ°”é¦ï¼Œä½†æ˜¯ç¤¾åŒºä¼šè®°ä½ä½ çš„å应， +å³ä½¿å¾ˆä¹…以åŽä»–们已ç»å¿˜è®°äº†è°çš„è¡¥ä¸çœŸæ£è¢«åˆå¹¶ã€‚ diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst index 2f0ef750746f..6d0dadae13b1 100644 --- a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst @@ -1,7 +1,14 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _cn_development_advancedtopics: @@ -15,110 +22,112 @@ --------------- å†…æ ¸ä½¿ç”¨åˆ†å¸ƒå¼ç‰ˆæœ¬æŽ§åˆ¶å§‹äºŽ2002å¹´åˆï¼Œå½“æ—¶Linus首次开始使用专有的Bitkeeper应用 -程åºã€‚虽然bitkeeperå˜åœ¨äº‰è®®ï¼Œä½†å®ƒæ‰€ä½“现的软件版本管ç†æ–¹æ³•å´è‚¯å®šä¸æ˜¯ã€‚åˆ†å¸ƒå¼ -版本控制å¯ä»¥ç«‹å³åŠ é€Ÿå†…æ ¸å¼€å‘项目。在当å‰çš„æ—¶ä»£ï¼Œæœ‰å‡ ç§å…费的比特ä¿æŒå™¨æ›¿ä»£å“。 -æ— è®ºå¥½åï¼Œå†…æ ¸é¡¹ç›®éƒ½å°†Git作为其选择的工具。 +程åºã€‚虽然BitKeeperå˜åœ¨äº‰è®®ï¼Œä½†å®ƒæ‰€ä½“现的软件版本管ç†æ–¹æ³•å´è‚¯å®šä¸æ˜¯ã€‚åˆ†å¸ƒå¼ +版本控制å¯ä»¥ç«‹å³åŠ é€Ÿå†…æ ¸å¼€å‘é¡¹ç›®ã€‚çŽ°åœ¨æœ‰å¥½å‡ ç§å…费的BitKeeper替代å“。 +ä½†æ— è®ºå¥½åï¼Œå†…æ ¸é¡¹ç›®éƒ½å·²ç»é€‰æ‹©äº†Git作为其工具。 -使用Git管ç†è¡¥ä¸å¯ä»¥ä½¿å¼€å‘äººå‘˜çš„ç”Ÿæ´»æ›´åŠ è½»æ¾ï¼Œå°¤å…¶æ˜¯éšç€è¡¥ä¸æ•°é‡çš„å¢žåŠ ã€‚Git -也有其粗糙的边缘和一定的å±é™©ï¼Œå®ƒæ˜¯ä¸€ä¸ªå¹´è½»å’Œå¼ºå¤§çš„工具，ä»ç„¶åœ¨å…¶å¼€å‘人员完善 +使用Git管ç†è¡¥ä¸å¯ä»¥ä½¿å¼€å‘äººå‘˜çš„ç”Ÿæ´»æ›´åŠ è½»æ¾ï¼Œå°¤å…¶æ˜¯éšç€è¡¥ä¸æ•°é‡çš„增长。Git也 +有其粗糙的边角和一定的å±é™©æ€§ï¼Œå®ƒæ˜¯ä¸€ä¸ªå¹´è½»å’Œå¼ºå¤§çš„工具，ä»ç„¶åœ¨å…¶å¼€å‘人员完善 ä¸ã€‚本文档ä¸ä¼šè¯•å›¾æ•™ä¼šè¯»è€…如何使用git；这会是个巨长的文档。相å，这里的é‡ç‚¹ -将是Git如何特别适åˆå†…æ ¸å¼€å‘过程。想è¦åŠ å¿«Gitçš„å¼€å‘人员å¯ä»¥åœ¨ä»¥ä¸‹ç½‘站上找到 -更多信æ¯ï¼š +将是Git如何特别适åˆå†…æ ¸å¼€å‘过程。想è¦åŠ 快用Git速度的开å‘人员å¯ä»¥åœ¨ä»¥ä¸‹ç½‘站上 +找到更多信æ¯ï¼š https://git-scm.com/ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html -在å°è¯•ä½¿ç”¨å®ƒä½¿è¡¥ä¸å¯ä¾›å…¶ä»–人使用之å‰ï¼Œç¬¬ä¸€è¦åŠ¡æ˜¯é˜…读上述站点，对Git的工作 -æ–¹å¼æœ‰ä¸€ä¸ªæ‰Žå®žçš„了解。使用Gitçš„å¼€å‘人员应该能够获得主线å˜å‚¨åº“的副本，探索 -修订历å²ï¼Œæäº¤å¯¹æ ‘çš„æ›´æ”¹ï¼Œä½¿ç”¨åˆ†æ”¯ç‰ã€‚了解Git用于é‡å†™åŽ†å²çš„工具（如Rebase） -也很有用。Git有自己的术è¯å’Œæ¦‚念；Git的新用户应该了解refsã€è¿œç¨‹åˆ†æ”¯ã€ç´¢å¼•ã€ -å¿«è¿›åˆå¹¶ã€æŽ¨æ‹‰ã€åˆ†ç¦»å¤´ç‰ã€‚一开始å¯èƒ½æœ‰ç‚¹å“人，但这些概念ä¸éš¾é€šè¿‡ä¸€ç‚¹å¦ä¹ æ¥ +åŒæ—¶ç½‘上也能找到å„ç§å„æ ·çš„æ•™ç¨‹ã€‚ + +在å°è¯•ä½¿ç”¨å®ƒç”Ÿæˆè¡¥ä¸ä¾›ä»–人使用之å‰ï¼Œç¬¬ä¸€è¦åŠ¡æ˜¯é˜…读上述网页，对Gitçš„å·¥ä½œæ–¹å¼ +有一个扎实的了解。使用Gitçš„å¼€å‘人员应能进行拉å–主线å˜å‚¨åº“的副本，查询修订 +历å²ï¼Œæäº¤å¯¹æ ‘çš„æ›´æ”¹ï¼Œä½¿ç”¨åˆ†æ”¯ç‰æ“作。了解Git用于é‡å†™åŽ†å²çš„工具（如rebase） +也很有用。Git有自己的术è¯å’Œæ¦‚念；Git的新用户应该了解引用ã€è¿œç¨‹åˆ†æ”¯ã€ç´¢å¼•ã€ +å¿«è¿›åˆå¹¶ã€æŽ¨æ‹‰ã€æ¸¸ç¦»å¤´ç‰ã€‚一开始å¯èƒ½æœ‰ç‚¹å“人，但这些概念ä¸éš¾é€šè¿‡ä¸€ç‚¹å¦ä¹ æ¥ ç†è§£ã€‚ 使用git生æˆé€šè¿‡ç”µå邮件æ交的补ä¸æ˜¯æé«˜é€Ÿåº¦çš„ä¸€ä¸ªå¾ˆå¥½çš„ç»ƒä¹ ã€‚ -当您准备好开始安装Gitæ ‘ä¾›å…¶ä»–äººæŸ¥çœ‹æ—¶ï¼Œæ‚¨å½“ç„¶éœ€è¦ä¸€ä¸ªå¯ä»¥ä»Žä¸æå–çš„æœåŠ¡å™¨ã€‚ -如果您有一个å¯ä»¥è®¿é—®Internet的系统，那么使用gitå®ˆæŠ¤è¿›ç¨‹è®¾ç½®è¿™æ ·çš„æœåŠ¡å™¨ç›¸ -对简å•ã€‚å¦åˆ™ï¼Œå…费的公共托管网站（例如github）开始出现在网络上。æˆç†Ÿçš„å¼€å‘ -人员å¯ä»¥åœ¨kernel.org上获得一个å¸æˆ·ï¼Œä½†è¿™äº›å¸æˆ·å¹¶ä¸å®¹æ˜“找到；有关更多信æ¯ï¼Œ -请å‚阅 https://kernel.org/faq/ +当您准备好开始建立Gitæ ‘ä¾›å…¶ä»–äººæŸ¥çœ‹æ—¶ï¼Œæ— ç–‘éœ€è¦ä¸€ä¸ªå¯ä»¥ä»Žä¸æ‹‰å–çš„æœåŠ¡å™¨ã€‚ +如果您有一个å¯ä»¥è®¿é—®å› 特网的系统，那么使用git-daemonè®¾ç½®è¿™æ ·çš„æœåŠ¡å™¨ç›¸å¯¹ +简å•ã€‚åŒæ—¶ï¼Œå…费的公共托管网站（例如github）也开始出现在网络上。æˆç†Ÿçš„å¼€å‘ +人员å¯ä»¥åœ¨kernel.org上获得一个å¸æˆ·ï¼Œä½†è¿™äº›å¸æˆ·å¹¶ä¸å®¹æ˜“得到；更多有关信æ¯ï¼Œ +请å‚阅 https://kernel.org/faq/ 。 æ£å¸¸çš„Git工作æµç¨‹æ¶‰åŠåˆ°è®¸å¤šåˆ†æ”¯çš„使用。æ¯ä¸€æ¡å¼€å‘线都å¯ä»¥åˆ†ä¸ºå•ç‹¬çš„“主题 -分支â€ï¼Œå¹¶ç‹¬ç«‹ç»´æŠ¤ã€‚Git的分支机构很便宜，没有ç†ç”±ä¸å…费使用它们。而且，在 -任何情况下，您都ä¸åº”该在任何您打算让其他人从ä¸å—益的分支ä¸è¿›è¡Œå¼€å‘。应该 -å°å¿ƒåœ°åˆ›å»ºå…¬å¼€å¯ç”¨çš„分支；当它们处于完整的形å¼å¹¶å‡†å¤‡å¥½è¿è¡Œæ—¶(而ä¸æ˜¯ä¹‹å‰ï¼‰ï¼Œ -åˆå¹¶å¼€å‘分支的补ä¸ã€‚ +分支â€ï¼Œå¹¶ç‹¬ç«‹ç»´æŠ¤ã€‚Git的分支很容易使用，没有ç†ç”±ä¸ä½¿ç”¨å®ƒä»¬ã€‚而且，在任何 +情况下，您都ä¸åº”该在任何您打算让其他人从ä¸æ‹‰å–的分支ä¸è¿›è¡Œå¼€å‘。应该å°å¿ƒåœ° +创建公开å¯ç”¨çš„分支；当开å‘分支处于完整状æ€å¹¶å·²å‡†å¤‡å¥½æ—¶(而ä¸æ˜¯ä¹‹å‰ï¼‰æ‰åˆå¹¶ +å¼€å‘分支的补ä¸ã€‚ Gitæ供了一些强大的工具，å¯ä»¥è®©æ‚¨é‡å†™å¼€å‘历å²ã€‚一个ä¸æ–¹ä¾¿çš„è¡¥ä¸ï¼ˆæ¯”如说， ä¸€ä¸ªæ‰“ç ´äºŒåˆ†æ³•çš„è¡¥ä¸ï¼Œæˆ–者有其他一些明显的缺陷）å¯ä»¥åœ¨é€‚当的ä½ç½®ä¿®å¤ï¼Œæˆ–者 -完全从历å²ä¸æ¶ˆå¤±ã€‚一个补ä¸ç³»åˆ—å¯ä»¥è¢«é‡å†™ï¼Œå°±å¥½åƒå®ƒæ˜¯åœ¨ä»Šå¤©çš„主线之上写的 -ä¸€æ ·ï¼Œå³ä½¿ä½ å·²ç»èŠ±äº†å‡ 个月的时间在写它。å¯ä»¥é€æ˜Žåœ°å°†æ›´æ”¹ä»Žä¸€ä¸ªåˆ†æ”¯è½¬ç§»åˆ°å¦ -一个分支。ç‰ç‰ã€‚明智地使用git修改历å²çš„能力å¯ä»¥å¸®åŠ©åˆ›å»ºé—®é¢˜æ›´å°‘的干净补ä¸é›†ã€‚ +完全从历å²ä¸æ¶ˆå¤±ã€‚一个补ä¸ç³»åˆ—å¯ä»¥è¢«é‡å†™ï¼Œå°±å¥½åƒå®ƒæ˜¯åœ¨ä»Šå¤©çš„ä¸»çº¿ä¸Šå†™çš„ä¸€æ ·ï¼Œ +å³ä½¿ä½ å·²ç»èŠ±äº†å‡ 个月的时间在写它。å¯ä»¥é€æ˜Žåœ°å°†æ›´æ”¹ä»Žä¸€ä¸ªåˆ†æ”¯è½¬ç§»åˆ°å¦ä¸€ä¸ª +分支。ç‰ç‰ã€‚明智地使用git修改历å²çš„能力å¯ä»¥å¸®åŠ©åˆ›å»ºé—®é¢˜æ›´å°‘的干净补ä¸é›†ã€‚ -然而，过度使用这ç§èƒ½åŠ›å¯èƒ½ä¼šå¯¼è‡´å…¶ä»–问题，而ä¸ä»…仅是对创建完美项目历å²çš„ -简å•ç—´è¿·ã€‚é‡å†™åŽ†å²å°†é‡å†™è¯¥åŽ†å²ä¸åŒ…å«çš„更改，将ç»è¿‡æµ‹è¯•ï¼ˆå¸Œæœ›ï¼‰çš„å†…æ ¸æ ‘å˜ -为未ç»æµ‹è¯•çš„å†…æ ¸æ ‘ã€‚ä½†æ˜¯ï¼Œé™¤æ¤ä¹‹å¤–，如果开å‘人员没有对项目历å²çš„共享视图， -ä»–ä»¬å°±æ— æ³•è½»æ¾åœ°å作；如果您é‡å†™äº†å…¶ä»–å¼€å‘人员拉入他们å˜å‚¨åº“的历å²ï¼Œæ‚¨å°† -使这些开å‘äººå‘˜çš„ç”Ÿæ´»æ›´åŠ å›°éš¾ã€‚å› æ¤ï¼Œè¿™é‡Œæœ‰ä¸€ä¸ªç®€å•çš„ç»éªŒæ³•åˆ™ï¼šè¢«å¯¼å‡ºåˆ°å…¶ä»– -人的历å²åœ¨æ¤åŽé€šå¸¸è¢«è®¤ä¸ºæ˜¯ä¸å¯å˜çš„。 +然而，过度使用这ç§åŠŸèƒ½å¯èƒ½ä¼šå¯¼è‡´å…¶ä»–问题，而ä¸ä»…仅是对创建完美项目历å²çš„ +简å•ç—´è¿·ã€‚é‡å†™åŽ†å²å°†é‡å†™è¯¥åŽ†å²ä¸åŒ…å«çš„更改，将ç»è¿‡æµ‹è¯•ï¼ˆå¸Œæœ›å¦‚æ¤ï¼‰çš„å†…æ ¸æ ‘ +å˜ä¸ºæœªç»æµ‹è¯•çš„å†…æ ¸æ ‘ã€‚é™¤æ¤ä¹‹å¤–，如果开å‘人员没有共享项目历å²ï¼Œä»–ä»¬å°±æ— æ³• +è½»æ¾åœ°å作；如果您é‡å†™äº†å…¶ä»–å¼€å‘人员拉入他们å˜å‚¨åº“的历å²ï¼Œæ‚¨å°†ä½¿è¿™äº›å¼€å‘ +äººå‘˜çš„ç”Ÿæ´»æ›´åŠ å›°éš¾ã€‚å› æ¤ï¼Œè¿™é‡Œæœ‰ä¸€ä¸ªç®€å•çš„ç»éªŒæ³•åˆ™ï¼šè¢«å¯¼å‡ºåˆ°å…¶ä»–åœ°æ–¹çš„åŽ†å² +在æ¤åŽé€šå¸¸è¢«è®¤ä¸ºæ˜¯ä¸å¯å˜çš„。 å› æ¤ï¼Œä¸€æ—¦å°†ä¸€ç»„更改推é€åˆ°å…¬å¼€å¯ç”¨çš„æœåŠ¡å™¨ä¸Šï¼Œå°±ä¸åº”该é‡å†™è¿™äº›æ›´æ”¹ã€‚如果您 -å°è¯•å¼ºåˆ¶è¿›è¡Œä¸ä¼šå¯¼è‡´å¿«è¿›åˆå¹¶ï¼ˆå³ä¸å…±äº«åŒä¸€åŽ†å²è®°å½•çš„更改）的更改，Gitå°†å° -试强制执行æ¤è§„则。å¯ä»¥é‡å†™æ¤æ£€æŸ¥ï¼Œæœ‰æ—¶å¯èƒ½éœ€è¦é‡å†™å¯¼å‡ºçš„æ ‘ã€‚åœ¨æ ‘ä¹‹é—´ç§»åŠ¨å˜ -更集以é¿å…Linux-nextä¸çš„冲çªå°±æ˜¯ä¸€ä¸ªä¾‹å。但这ç§è¡Œä¸ºåº”该是罕è§çš„。这就是为 -什么开å‘应该在ç§æœ‰åˆ†æ”¯ä¸è¿›è¡Œï¼ˆå¿…è¦æ—¶å¯ä»¥é‡å†™ï¼‰å¹¶ä¸”åªæœ‰åœ¨å…¬å…±åˆ†æ”¯å¤„于åˆç†çš„ -高级状æ€æ—¶æ‰è½¬ç§»åˆ°å…¬å…±åˆ†æ”¯ä¸çš„åŽŸå› ä¹‹ä¸€ã€‚ +å°è¯•å¼ºåˆ¶è¿›è¡Œæ— 法快进åˆå¹¶çš„更改（å³ä¸å…±äº«åŒä¸€åŽ†å²è®°å½•çš„更改），Gitå°†å°è¯•å¼ºåˆ¶ +执行æ¤è§„则。这å¯èƒ½è¦†ç›–检查，有时甚至需è¦é‡å†™å¯¼å‡ºçš„æ ‘ã€‚åœ¨æ ‘ä¹‹é—´ç§»åŠ¨å˜æ›´é›†ä»¥ +é¿å…linux-nextä¸çš„冲çªå°±æ˜¯ä¸€ä¸ªä¾‹å。但这ç§è¡Œä¸ºåº”该是罕è§çš„。这就是为什么 +å¼€å‘应该在ç§æœ‰åˆ†æ”¯ä¸è¿›è¡Œï¼ˆå¿…è¦æ—¶å¯ä»¥é‡å†™ï¼‰å¹¶ä¸”åªæœ‰åœ¨å…¬å…±åˆ†æ”¯å¤„于åˆç†çš„较新 +状æ€æ—¶æ‰è½¬ç§»åˆ°å…¬å…±åˆ†æ”¯ä¸çš„åŽŸå› ä¹‹ä¸€ã€‚ 当主线（或其他一组å˜æ›´æ‰€åŸºäºŽçš„æ ‘ï¼‰å‰è¿›æ—¶ï¼Œå¾ˆå®¹æ˜“ä¸Žè¯¥æ ‘åˆå¹¶ä»¥ä¿æŒé¢†å…ˆåœ°ä½ã€‚ 对于一个ç§æœ‰çš„分支，rebasing å¯èƒ½æ˜¯ä¸€ä¸ªå¾ˆå®¹æ˜“跟上å¦ä¸€æ£µæ ‘的方法，但是一旦 -ä¸€æ£µæ ‘è¢«å¯¼å‡ºåˆ°å…¨ä¸–ç•Œï¼Œrebasingå°±ä¸æ˜¯ä¸€ä¸ªé€‰é¡¹ã€‚一旦å‘生这ç§æƒ…况，就必须进行 -完全åˆå¹¶ï¼ˆmerge）。åˆå¹¶æœ‰æ—¶æ˜¯å¾ˆæœ‰æ„义的，但是过于频ç¹çš„åˆå¹¶ä¼šä¸å¿…è¦åœ°æ‰°ä¹± -历å²ã€‚在这ç§æƒ…况下，建议的技术是ä¸ç»å¸¸åˆå¹¶ï¼Œé€šå¸¸åªåœ¨ç‰¹å®šçš„å‘布点（如主线-rc -å‘布）åˆå¹¶ã€‚å¦‚æžœæ‚¨å¯¹ç‰¹å®šçš„æ›´æ”¹æ„Ÿåˆ°ç´§å¼ ï¼Œåˆ™å¯ä»¥å§‹ç»ˆåœ¨ç§æœ‰åˆ†æ”¯ä¸æ‰§è¡Œæµ‹è¯•åˆå¹¶ã€‚ -在这ç§æƒ…况下，git rerere 工具很有用；它记ä½åˆå¹¶å†²çªæ˜¯å¦‚ä½•è§£å†³çš„ï¼Œè¿™æ ·æ‚¨å°± -ä¸å¿…é‡å¤ç›¸åŒçš„工作。 +ä¸€æ£µæ ‘è¢«å¯¼å‡ºåˆ°å¤–ç•Œï¼Œrebasingå°±ä¸å¯å–了。一旦å‘生这ç§æƒ…况，就必须进行完全 +åˆå¹¶ï¼ˆmerge）。åˆå¹¶æœ‰æ—¶æ˜¯å¾ˆæœ‰æ„义的，但是过于频ç¹çš„åˆå¹¶ä¼šä¸å¿…è¦åœ°æ‰°ä¹±åŽ†å²ã€‚ +在这ç§æƒ…况下建议的åšæ³•æ˜¯ä¸è¦é¢‘ç¹åˆå¹¶ï¼Œé€šå¸¸åªåœ¨ç‰¹å®šçš„å‘布点（如主线-rcå‘布） +åˆå¹¶ã€‚å¦‚æžœæ‚¨å¯¹ç‰¹å®šçš„æ›´æ”¹æ„Ÿåˆ°ç´§å¼ ï¼Œåˆ™å¯ä»¥å§‹ç»ˆåœ¨ç§æœ‰åˆ†æ”¯ä¸æ‰§è¡Œæµ‹è¯•åˆå¹¶ã€‚在 +è¿™ç§æƒ…况下，git“rerereâ€å·¥å…·å¾ˆæœ‰ç”¨ï¼›å®ƒèƒ½è®°ä½åˆå¹¶å†²çªæ˜¯å¦‚ä½•è§£å†³çš„ï¼Œè¿™æ ·æ‚¨ +å°±ä¸å¿…é‡å¤ç›¸åŒçš„工作。 关于Gitè¿™æ ·çš„å·¥å…·çš„ä¸€ä¸ªæœ€å¤§çš„åå¤æŠ±æ€¨æ˜¯ï¼šè¡¥ä¸ä»Žä¸€ä¸ªå˜å‚¨åº“到å¦ä¸€ä¸ªå˜å‚¨åº“çš„ 大é‡ç§»åŠ¨ä½¿å¾—很容易陷入错误建议的å˜æ›´ä¸ï¼Œè¿™äº›å˜æ›´é¿å¼€å®¡æŸ¥é›·è¾¾è¿›å…¥ä¸»çº¿ã€‚当内 -æ ¸å¼€å‘人员看到这ç§æƒ…况å‘生时，他们往往会感到ä¸é«˜å…´ï¼›åœ¨Gitæ ‘ä¸Šæ”¾ç½®æœªæŸ¥çœ‹æˆ– -主题外的补ä¸å¯èƒ½ä¼šå½±å“您将æ¥èŽ·å–æ ‘çš„èƒ½åŠ›ã€‚å¼•ç”¨Linus: +æ ¸å¼€å‘人员看到这ç§æƒ…况å‘生时，他们往往会感到ä¸é«˜å…´ï¼›åœ¨Gitæ ‘ä¸Šæ”¾ç½®æœªå®¡é˜…æˆ– +主题外的补ä¸å¯èƒ½ä¼šå½±å“您将æ¥è®©æ ‘被拉å–的能力。引用Linusçš„è¯: :: - ä½ å¯ä»¥ç»™æˆ‘å‘è¡¥ä¸ï¼Œä½†è¦æˆ‘ä»Žä½ å“ªé‡Œå–一个Gitè¡¥ä¸ï¼Œæˆ‘需è¦çŸ¥é“ä½ çŸ¥é“ - ä½ åœ¨åšä»€ä¹ˆï¼Œæˆ‘需è¦èƒ½å¤Ÿç›¸ä¿¡äº‹æƒ…而ä¸åŽ»æ£€æŸ¥æ¯ä¸ªä¸ªäººæ”¹å˜ã€‚ + ä½ å¯ä»¥ç»™æˆ‘å‘è¡¥ä¸ï¼Œä½†å½“æˆ‘ä»Žä½ é‚£é‡Œæ‹‰å–一个Gitè¡¥ä¸æ—¶ï¼Œæˆ‘需è¦çŸ¥é“ä½ æ¸…æ¥š + 自己在åšä»€ä¹ˆï¼Œæˆ‘需è¦èƒ½å¤Ÿç›¸ä¿¡äº‹æƒ…而 *æ— éœ€* 手动检查æ¯ä¸ªå•ç‹¬çš„更改。 （http://lwn.net/articles/224135/）。 为了é¿å…è¿™ç§æƒ…况，请确ä¿ç»™å®šåˆ†æ”¯ä¸çš„所有补ä¸éƒ½ä¸Žç›¸å…³ä¸»é¢˜ç´§å¯†ç›¸å…³ï¼›â€œé©±åŠ¨ç¨‹åº ä¿®å¤â€åˆ†æ”¯ä¸åº”æ›´æ”¹æ ¸å¿ƒå†…å˜ç®¡ç†ä»£ç 。而且，最é‡è¦çš„是，ä¸è¦ä½¿ç”¨Gitæ ‘æ¥ç»•è¿‡ -审查过程。ä¸æ—¶çš„å°†æ ‘çš„æ‘˜è¦å‘布到相关的列表ä¸ï¼Œå½“时间åˆé€‚时，请求 -Linux-next ä¸åŒ…å«è¯¥æ ‘。 +审查过程。ä¸æ—¶çš„å°†æ ‘çš„æ‘˜è¦å‘布到相关的列表ä¸ï¼Œåœ¨åˆé€‚时候请求linux-nextä¸ +包å«è¯¥æ ‘。 -如果其他人开始å‘é€è¡¥ä¸ä»¥åŒ…å«åˆ°æ‚¨çš„æ ‘ä¸ï¼Œä¸è¦å¿˜è®°æŸ¥çœ‹å®ƒä»¬ã€‚还è¦ç¡®ä¿æ‚¨ç»´æŠ¤æ£ç¡® -的作者信æ¯ï¼› ``git am`` 工具在这方é¢åšå¾—最好，但是如果它通过第三方转å‘给您， -您å¯èƒ½éœ€è¦åœ¨è¡¥ä¸ä¸æ·»åŠ “From：â€è¡Œã€‚ +如果其他人开始å‘é€è¡¥ä¸ä»¥åŒ…å«åˆ°æ‚¨çš„æ ‘ä¸ï¼Œä¸è¦å¿˜è®°å®¡é˜…它们。还è¦ç¡®ä¿æ‚¨ç»´æŠ¤æ£ç¡® +的作者信æ¯ï¼› git “amâ€å·¥å…·åœ¨è¿™æ–¹é¢åšå¾—最好，但是如果补ä¸é€šè¿‡ç¬¬ä¸‰æ–¹è½¬å‘给您， +您å¯èƒ½éœ€è¦åœ¨è¡¥ä¸ä¸æ·»åŠ “From:â€è¡Œã€‚ -请求pullæ“作时，请务必æ供所有相关信æ¯ï¼šæ ‘çš„ä½ç½®ã€è¦æ‹‰çš„分支以åŠæ‹‰æ“作将导致 -的更改。在这方é¢ï¼Œgit request pull 命令éžå¸¸æœ‰ç”¨ï¼›å®ƒå°†æŒ‰ç…§å…¶ä»–å¼€å‘人员的预期 -æ ¼å¼åŒ–请求，并检查以确ä¿æ‚¨è®°ä½äº†å°†è¿™äº›æ›´æ”¹æŽ¨é€åˆ°å…¬å…±æœåŠ¡å™¨ã€‚ +请求拉å–时，请务必æ供所有相关信æ¯ï¼šæ ‘çš„ä½ç½®ã€è¦æ‹‰å–的分支以åŠæ‹‰å–将导致的 +æ›´æ”¹ã€‚åœ¨è¿™æ–¹é¢ git request-pull 命令éžå¸¸æœ‰ç”¨ï¼›å®ƒå°†æŒ‰ç…§å…¶ä»–å¼€å‘人员所期望的 +æ ¼å¼åŒ–请求，并检查以确ä¿æ‚¨å·²è®°å¾—将这些更改推é€åˆ°å…¬å…±æœåŠ¡å™¨ã€‚ -å®¡æŸ¥è¡¥ä¸ +å®¡é˜…è¡¥ä¸ -------- -一些读者当然会å对将本节与“高级主题â€æ”¾åœ¨ä¸€èµ·ï¼Œå› 为å³ä½¿æ˜¯åˆšå¼€å§‹çš„å†…æ ¸å¼€å‘人员 -也应该检查补ä¸ã€‚当然，å¦ä¹ å¦‚ä½•åœ¨å†…æ ¸çŽ¯å¢ƒä¸ç¼–程没有比查看其他人å‘布的代ç 更好 -的方法了。æ¤å¤–，审阅者永远供ä¸åº”求；通过查看代ç ，您å¯ä»¥å¯¹æ•´ä¸ªæµç¨‹åšå‡ºé‡å¤§è´¡çŒ®ã€‚ +一些读者显然会å对将本节与“高级主题â€æ”¾åœ¨ä¸€èµ·ï¼Œå› 为å³ä½¿æ˜¯åˆšå¼€å§‹çš„å†…æ ¸å¼€å‘人员 +也应该审阅补ä¸ã€‚当然，没有比查看其他人å‘布的代ç 更好的方法æ¥å¦ä¹ å¦‚ä½•åœ¨å†…æ ¸çŽ¯å¢ƒ +ä¸ç¼–程了。æ¤å¤–，审阅者永远供ä¸åº”求；通过审阅代ç ，您å¯ä»¥å¯¹æ•´ä¸ªæµç¨‹åšå‡ºé‡å¤§è´¡çŒ®ã€‚ -审查代ç å¯èƒ½æ˜¯ä¸€ä¸ªä»¤äººç”Ÿç•çš„å‰æ™¯ï¼Œç‰¹åˆ«æ˜¯å¯¹äºŽä¸€ä¸ªæ–°çš„å†…æ ¸å¼€å‘人员æ¥è¯´ï¼Œä»–们 +审查代ç å¯èƒ½æ˜¯ä¸€å‰¯ä»¤äººç”Ÿç•çš„å›¾æ™¯ï¼Œç‰¹åˆ«æ˜¯å¯¹ä¸€ä¸ªæ–°çš„å†…æ ¸å¼€å‘人员æ¥è¯´ï¼Œä»–们 å¯èƒ½ä¼šå¯¹å…¬å¼€è¯¢é—®ä»£ç æ„Ÿåˆ°ç´§å¼ ï¼Œè€Œè¿™äº›ä»£ç 是由那些有更多ç»éªŒçš„人å‘布的。ä¸è¿‡ï¼Œ -å³ä½¿æ˜¯æœ€æœ‰ç»éªŒçš„å¼€å‘人员编写的代ç 也å¯ä»¥å¾—到改进。也许对评审员（所有评审员） -最好的建议是：把评审评论当æˆé—®é¢˜è€Œä¸æ˜¯æ‰¹è¯„。询问“在这æ¡è·¯å¾„ä¸å¦‚何释放é”？†+å³ä½¿æ˜¯æœ€æœ‰ç»éªŒçš„å¼€å‘人员编写的代ç 也å¯ä»¥å¾—到改进。也许对（所有）审阅者最好 +的建议是：把审阅评论当æˆé—®é¢˜è€Œä¸æ˜¯æ‰¹è¯„。询问“在这æ¡è·¯å¾„ä¸å¦‚何释放é”？†总是比说“这里的é”是错误的â€æ›´å¥½ã€‚ -ä¸åŒçš„å¼€å‘人员将从ä¸åŒçš„角度审查代ç 。一些主è¦å…³æ³¨çš„是编ç æ ·å¼ä»¥åŠä»£ç 行是 -å¦æœ‰å°¾éšç©ºæ ¼ã€‚其他人将主è¦å…³æ³¨è¡¥ä¸ä½œä¸ºä¸€ä¸ªæ•´ä½“实现的å˜æ›´æ˜¯å¦å¯¹å†…æ ¸æœ‰å¥½å¤„ã€‚ -然而，其他人会检查是å¦å˜åœ¨é”定问题ã€å †æ ˆä½¿ç”¨è¿‡åº¦ã€å¯èƒ½çš„安全问题ã€åœ¨å…¶ä»– -地方å‘现的代ç é‡å¤ã€è¶³å¤Ÿçš„文档ã€å¯¹æ€§èƒ½çš„ä¸åˆ©å½±å“ã€ç”¨æˆ·ç©ºé—´ABI更改ç‰ã€‚所有 -类型的检查，如果它们导致更好的代ç è¿›å…¥å†…æ ¸ï¼Œéƒ½æ˜¯å—欢迎和值得的。 +ä¸åŒçš„å¼€å‘人员将从ä¸åŒçš„角度审查代ç 。部分人会主è¦å…³æ³¨ä»£ç é£Žæ ¼ä»¥åŠä»£ç 行是 +å¦æœ‰å°¾éšç©ºæ ¼ã€‚其他人会主è¦å…³æ³¨è¡¥ä¸ä½œä¸ºä¸€ä¸ªæ•´ä½“实现的å˜æ›´æ˜¯å¦å¯¹å†…æ ¸æœ‰å¥½å¤„ã€‚ +åŒæ—¶ä¹Ÿæœ‰äººä¼šæ£€æŸ¥æ˜¯å¦å˜åœ¨é”问题ã€å †æ ˆä½¿ç”¨è¿‡åº¦ã€å¯èƒ½çš„安全问题ã€åœ¨å…¶ä»–地方 +å‘现的代ç é‡å¤ã€è¶³å¤Ÿçš„文档ã€å¯¹æ€§èƒ½çš„ä¸åˆ©å½±å“ã€ç”¨æˆ·ç©ºé—´ABI更改ç‰ã€‚所有类型 +的检查，åªè¦å®ƒä»¬èƒ½å¼•å¯¼æ›´å¥½çš„代ç è¿›å…¥å†…æ ¸ï¼Œéƒ½æ˜¯å—欢迎和值得的。 diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst index 90cec3de6106..71c3e30efc6f 100644 --- a/Documentation/translations/zh_CN/process/8.Conclusion.rst +++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst @@ -1,7 +1,13 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:æ ¡è¯‘: + + å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> .. _cn_development_conclusion: @@ -9,56 +15,56 @@ ======== 关于Linuxå†…æ ¸å¼€å‘和相关主题的信æ¯æ¥æºå¾ˆå¤šã€‚é¦–å…ˆæ˜¯åœ¨å†…æ ¸æºä»£ç 分å‘ä¸æ‰¾åˆ°çš„ -文档目录。顶级 :ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` -文件是一个é‡è¦çš„起点 +文档目录。顶级 +: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>` +å’Œ :ref:`Documentation/transaltions/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` ä¹Ÿæ˜¯æ‰€æœ‰å†…æ ¸å¼€å‘äººå‘˜éƒ½åº”è¯¥é˜…è¯»çš„å†…å®¹ã€‚è®¸å¤šå†…éƒ¨å†…æ ¸API都是使用kerneldoc机制 -记录的；“make htmldocsâ€æˆ–“make pdfdocsâ€å¯ç”¨äºŽä»¥HTML或PDFæ ¼å¼ç”Ÿæˆè¿™äº›æ–‡æ¡£ï¼ˆ -尽管æŸäº›å‘行版æ供的tex版本会é‡åˆ°å†…部é™åˆ¶ï¼Œæ— 法æ£ç¡®å¤„ç†æ–‡æ¡£ï¼‰ã€‚ +记录的；“make htmldocsâ€æˆ–“make pdfdocsâ€å¯ç”¨äºŽä»¥HTML或PDFæ ¼å¼ç”Ÿæˆè¿™äº›æ–‡æ¡£ +（尽管æŸäº›å‘行版æ供的tex版本会é‡åˆ°å†…部é™åˆ¶ï¼Œæ— 法æ£ç¡®å¤„ç†æ–‡æ¡£ï¼‰ã€‚ -ä¸åŒçš„网站在å„ä¸ªç»†èŠ‚å±‚æ¬¡ä¸Šè®¨è®ºå†…æ ¸å¼€å‘。您的作者想谦虚地建议用 https://lwn.net/ -作为æ¥æºï¼›æœ‰å…³è®¸å¤šç‰¹å®šå†…æ ¸ä¸»é¢˜çš„ä¿¡æ¯å¯ä»¥é€šè¿‡ä»¥ä¸‹ç½‘å€çš„lwnå†…æ ¸ç´¢å¼•æ‰¾åˆ°ï¼š +ä¸åŒçš„网站在å„ä¸ªç»†èŠ‚å±‚æ¬¡ä¸Šè®¨è®ºå†…æ ¸å¼€å‘。本文作者想谦虚地建议用 https://lwn.net/ +作为æ¥æºï¼›æœ‰å…³è®¸å¤šç‰¹å®šå†…æ ¸ä¸»é¢˜çš„ä¿¡æ¯å¯ä»¥é€šè¿‡ä»¥ä¸‹ç½‘å€çš„ LWN å†…æ ¸ç´¢å¼•æ‰¾åˆ°ï¼š - http://lwn.net/kernel/index/ + http://lwn.net/kernel/index/ 除æ¤ä¹‹å¤–ï¼Œå†…æ ¸å¼€å‘人员的一个å®è´µèµ„æºæ˜¯ï¼š - https://kernelnewbies.org/ + https://kernelnewbies.org/ -当然，我们ä¸åº”该忘记 https://kernel.org/ è¿™æ˜¯å†…æ ¸å‘布信æ¯çš„最终ä½ç½®ã€‚ +当然，也ä¸åº”该忘记 https://kernel.org/ ï¼Œè¿™æ˜¯å†…æ ¸å‘布信æ¯çš„最终ä½ç½®ã€‚ å…³äºŽå†…æ ¸å¼€å‘有很多书： - Linux设备驱动程åºï¼Œç¬¬ä¸‰ç‰ˆï¼ˆJonathan Corbetã€Alessandro Rubiniå’ŒGreg Kroah Hartman）。 - 在线：http://lwn.net/kernel/ldd3/ + 《Linux设备驱动程åºã€‹ç¬¬ä¸‰ç‰ˆï¼ˆJonathan Corbetã€Alessandro Rubiniå’ŒGreg Kroah Hartman） + 线上版本在 http://lwn.net/kernel/ldd3/ - Linuxå†…æ ¸å¼€å‘（Robert Love）。 + 《Linuxå†…æ ¸è®¾è®¡ä¸Žå®žçŽ°ã€‹ï¼ˆRobert Love） - 了解Linuxå†…æ ¸ï¼ˆDaniel Bovetå’ŒMarco Cesati）。 + 《深入ç†è§£Linuxå†…æ ¸ã€‹(Daniel Bovetå’ŒMarco Cesati） -然而，所有这些书都有一个共åŒçš„缺点：当它们上架时，它们往往有些过时，而且它们 -å·²ç»ä¸Šæž¶ä¸€æ®µæ—¶é—´äº†ã€‚ä¸è¿‡ï¼Œåœ¨é‚£é‡Œè¿˜å¯ä»¥æ‰¾åˆ°ç›¸å½“多的好信æ¯ã€‚ +然而，所有这些书都有一个共åŒçš„缺点：它们上架时就往往有些过时，而且已ç»ä¸Šæž¶ +一段时间了。ä¸è¿‡ï¼Œåœ¨é‚£é‡Œè¿˜æ˜¯å¯ä»¥æ‰¾åˆ°ç›¸å½“多的好信æ¯ã€‚ 有关git的文档，请访问： - https://www.kernel.org/pub/software/scm/git/docs/ + https://www.kernel.org/pub/software/scm/git/docs/ - https://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html 结论 ==== -ç¥è´ºæ‰€æœ‰é€šè¿‡è¿™ç¯‡å†—长的文件的人。希望它能够帮助您ç†è§£Linuxå†…æ ¸æ˜¯å¦‚ä½•å¼€å‘的， +ç¥è´ºæ‰€æœ‰é€šè¿‡è¿™ç¯‡å†—长的文档的人。希望它能够帮助您ç†è§£Linuxå†…æ ¸æ˜¯å¦‚ä½•å¼€å‘的， 以åŠæ‚¨å¦‚何å‚与这个过程。 -最åŽï¼Œé‡è¦çš„是å‚与。任何开æºè½¯ä»¶é¡¹ç›®éƒ½ä¸è¶…过其贡献者投入其ä¸çš„总和。Linuxå†…æ ¸ -çš„å‘展速度和以å‰ä¸€æ ·å¿«ï¼Œå› 为它得到了大é‡å¼€å‘人员的帮助，他们都在努力使它å˜å¾— -æ›´å¥½ã€‚å†…æ ¸æ˜¯ä¸€ä¸ªä¸»è¦çš„例å，说明当æˆåƒä¸Šä¸‡çš„人为了一个共åŒçš„ç›®æ ‡ä¸€èµ·å·¥ä½œæ—¶ï¼Œ -å¯ä»¥åšäº›ä»€ä¹ˆã€‚ +最åŽï¼Œé‡è¦çš„是å‚与。任何开æºè½¯ä»¶é¡¹ç›®éƒ½ä¸ä¼šè¶…过其贡献者投入其ä¸çš„总和。Linux +å†…æ ¸çš„å‘展速度和以å‰ä¸€æ ·å¿«ï¼Œå› 为它得到了大é‡å¼€å‘人员的帮助，他们都在努力使它 +å˜å¾—æ›´å¥½ã€‚å†…æ ¸æ˜¯ä¸€ä¸ªæœ€æˆåŠŸçš„例å，说明了当æˆåƒä¸Šä¸‡çš„人为了一个共åŒçš„ç›®æ ‡ä¸€èµ· +工作时，å¯ä»¥åšå‡ºä»€ä¹ˆã€‚ -ä¸è¿‡ï¼Œå†…æ ¸æ€»æ˜¯å¯ä»¥ä»Žæ›´å¤§çš„å¼€å‘人员基础ä¸èŽ·ç›Šã€‚总有更多的工作è¦åšã€‚但是，åŒæ · +ä¸è¿‡ï¼Œå†…æ ¸æ€»æ˜¯å¯ä»¥ä»Žæ›´å¤§çš„å¼€å‘人员基础ä¸èŽ·ç›Šã€‚总有更多的工作è¦åšã€‚但是åŒæ · é‡è¦çš„是，Linux生æ€ç³»ç»Ÿä¸çš„大多数其他å‚与者å¯ä»¥é€šè¿‡ä¸ºå†…æ ¸åšå‡ºè´¡çŒ®è€Œå—益。使 代ç 进入主线是æ高代ç è´¨é‡ã€é™ä½Žç»´æŠ¤å’Œåˆ†å‘æˆæœ¬ã€æé«˜å¯¹å†…æ ¸å¼€å‘æ–¹å‘çš„å½±å“程度 -ç‰çš„关键。这是一ç§äººäººéƒ½èµ¢çš„å±€é¢ã€‚è¸¢å¼€ä½ çš„ç¼–è¾‘ï¼Œæ¥åŠ 入我们å§ï¼Œä½ 会éžå¸¸å— -欢迎的。 +ç‰çš„关键。这是一ç§å…±èµ¢çš„å±€é¢ã€‚å¯åŠ¨ä½ 的编辑器，æ¥åŠ 入我们å§ï¼›ä½ 会éžå¸¸å—欢迎的。 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index 8051a7b322c5..39e9c88fbaa6 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -13,11 +13,11 @@ 与Linux å†…æ ¸ç¤¾åŒºä¸€èµ·å·¥ä½œ ======================== -é‚£ä¹ˆä½ æƒ³æˆä¸ºLinuxå†…æ ¸å¼€å‘人员？ æ¬¢è¿Žï¼ ä¸ä½†ä»ŽæŠ€æœ¯æ„ä¹‰ä¸Šè®²æœ‰å¾ˆå¤šå…³äºŽå†…æ ¸çš„çŸ¥è¯† -需è¦å¦ï¼Œè€Œä¸”了解我们社区的工作方å¼ä¹Ÿå¾ˆé‡è¦ã€‚ é˜…è¯»è¿™äº›æ–‡ç« å¯ä»¥è®©æ‚¨ä»¥æ›´è½»æ¾åœ°, -麻烦最少的方å¼å°†æ›´æ”¹åˆå¹¶åˆ°å†…æ ¸ã€‚ +ä½ æƒ³æˆä¸ºLinuxå†…æ ¸å¼€å‘人员å—？欢迎之至ï¼åœ¨å¦ä¹ è®¸å¤šå…³äºŽå†…æ ¸çš„æŠ€æœ¯çŸ¥è¯†çš„åŒæ—¶ï¼Œ +了解我们社区的工作方å¼ä¹Ÿå¾ˆé‡è¦ã€‚阅读这些文档å¯ä»¥è®©æ‚¨ä»¥æ›´è½»æ¾çš„ã€éº»çƒ¦æ›´å°‘çš„ +æ–¹å¼å°†æ›´æ”¹åˆå¹¶åˆ°å†…æ ¸ã€‚ -以下是æ¯ä½å¼€å‘人员应阅读的基本指å—。 +以下是æ¯ä½å¼€å‘人员都应阅读的基本指å—： .. toctree:: :maxdepth: 1 @@ -47,7 +47,7 @@ management-style embargoed-hardware-issues -这些是一些总体技术指å—，由于缺ä¹æ›´å¥½çš„地方，现在已ç»æ”¾åœ¨è¿™é‡Œ +这些是一些总体性技术指å—，由于ä¸å¤§å¥½åˆ†ç±»è€Œæ”¾åœ¨è¿™é‡Œï¼š .. toctree:: :maxdepth: 1 diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index 7bb9d4165ed3..42f0635ca70a 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -62,12 +62,10 @@ CMAGIC 0x0111 user ``include/linux/ 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`` SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` @@ -79,14 +77,12 @@ TTY_MAGIC 0x5401 tty_struct ``include/linux/ 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`` diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index 50386e0e42e7..a64858d321fc 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -82,24 +82,22 @@ Linuxå†…æ ¸è¡¥ä¸æäº¤æ¸…å• è¯·å‚阅 ``Documentation/ABI/README`` 。更改用户空间接å£çš„è¡¥ä¸åº”è¯¥æŠ„é€ linux-api@vger.kernel.org。 -20) 检查是å¦å…¨éƒ¨é€šè¿‡ ``make headers_check`` 。 - -21) 已通过至少注入slabå’Œpage分é…失败进行检查。请å‚阅 ``Documentation/fault-injection/`` +20) 已通过至少注入slabå’Œpage分é…失败进行检查。请å‚阅 ``Documentation/fault-injection/`` 如果新代ç æ˜¯å®žè´¨æ€§çš„ï¼Œé‚£ä¹ˆæ·»åŠ å系统特定的故障注入å¯èƒ½æ˜¯åˆé€‚的。 -22) æ–°æ·»åŠ çš„ä»£ç å·²ç»ç”¨ ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 +21) æ–°æ·»åŠ çš„ä»£ç å·²ç»ç”¨ ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 将产生大é‡å™ªå£°ï¼Œä½†å¯¹äºŽæŸ¥æ‰¾è¯¸å¦‚“è¦å‘Šï¼šæœ‰ç¬¦å·å’Œæ— 符å·ä¹‹é—´çš„比较â€ä¹‹ç±»çš„错误 很有用。 -23) 在它被åˆå¹¶åˆ°-mmè¡¥ä¸é›†ä¸ä¹‹åŽè¿›è¡Œæµ‹è¯•ï¼Œä»¥ç¡®ä¿å®ƒä»ç„¶ä¸Žæ‰€æœ‰å…¶ä»–排队的补ä¸ä»¥ +22) 在它被åˆå¹¶åˆ°-mmè¡¥ä¸é›†ä¸ä¹‹åŽè¿›è¡Œæµ‹è¯•ï¼Œä»¥ç¡®ä¿å®ƒä»ç„¶ä¸Žæ‰€æœ‰å…¶ä»–排队的补ä¸ä»¥ åŠVMã€VFS和其他å系统ä¸çš„å„ç§æ›´æ”¹ä¸€èµ·å·¥ä½œã€‚ -24) 所有内å˜å±éšœä¾‹å¦‚ ``barrier()``, ``rmb()``, ``wmb()`` 都需è¦æºä»£ç ä¸çš„注 +23) 所有内å˜å±éšœä¾‹å¦‚ ``barrier()``, ``rmb()``, ``wmb()`` 都需è¦æºä»£ç ä¸çš„注 释æ¥è§£é‡Šå®ƒä»¬æ£åœ¨æ‰§è¡Œçš„æ“作åŠå…¶åŽŸå› 的逻辑。 -25) 如果补ä¸æ·»åŠ 了任何ioctl，那么也è¦æ›´æ–° ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +24) 如果补ä¸æ·»åŠ 了任何ioctl，那么也è¦æ›´æ–° ``Documentation/userspace-api/ioctl/ioctl-number.rst`` -26) 如果修改åŽçš„æºä»£ç ä¾èµ–或使用与以下 ``Kconfig`` 符å·ç›¸å…³çš„ä»»ä½•å†…æ ¸API或 +25) 如果修改åŽçš„æºä»£ç ä¾èµ–或使用与以下 ``Kconfig`` 符å·ç›¸å…³çš„ä»»ä½•å†…æ ¸API或 功能，则在ç¦ç”¨ç›¸å…³ ``Kconfig`` 符å·å’Œ/或 ``=m`` （如果该选项å¯ç”¨ï¼‰çš„情况 下测试以下多个构建[并éžæ‰€æœ‰è¿™äº›éƒ½åŒæ—¶å˜åœ¨ï¼Œåªæ˜¯å®ƒä»¬çš„å„ç§/éšæœºç»„åˆ]： diff --git a/Documentation/translations/zh_CN/riscv/boot-image-header.rst b/Documentation/translations/zh_CN/riscv/boot-image-header.rst new file mode 100644 index 000000000000..241bf9c1bcbe --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/boot-image-header.rst @@ -0,0 +1,67 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/boot-image-header` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_boot-image-header.rst: + + +========================== +RISC-V Linuxå¯åŠ¨é•œåƒæ–‡ä»¶å¤´ +========================== + +:Author: Atish Patra <atish.patra@wdc.com> +:Date: 20 May 2019 + +æ¤æ–‡æ¡£ä»…æè¿°RISC-V Linux å¯åŠ¨æ–‡ä»¶å¤´çš„详情。 + +TODO: + 写一个完整的å¯åŠ¨æŒ‡å—。 + +在解压åŽçš„Linuxå†…æ ¸é•œåƒä¸å˜åœ¨ä»¥ä¸‹64å—节的文件头:: + + u32 code0; /* Executable code */ + u32 code1; /* Executable code */ + u64 text_offset; /* Image load offset, little endian */ + u64 image_size; /* Effective Image size, little endian */ + u64 flags; /* kernel flags, little endian */ + u32 version; /* Version of this header */ + u32 res1 = 0; /* Reserved */ + u64 res2 = 0; /* Reserved */ + u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ + u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */ + u32 res3; /* Reserved for PE COFF offset */ + +è¿™ç§å¤´æ ¼å¼ä¸ŽPE/COFF文件头兼容，并在很大程度上å—到ARM64文件头的å¯å‘ã€‚å› æ¤ï¼ŒARM64 +å’ŒRISC-V文件头å¯ä»¥åœ¨æœªæ¥åˆå¹¶ä¸ºä¸€ä¸ªå…±åŒçš„头。 + +æ³¨æ„ +==== + +- å°†æ¥ä¹Ÿå¯ä»¥å¤ç”¨è¿™ä¸ªæ–‡ä»¶å¤´ï¼Œç”¨æ¥å¯¹RISC-Vçš„EFIæ¡©æ供支æŒã€‚ä¸ºäº†ä½¿å†…æ ¸é•œåƒå¦‚åŒä¸€ä¸ª + EFI应用程åºä¸€æ ·åŠ 载，EFI规范ä¸è§„å®šåœ¨å†…æ ¸é•œåƒçš„开始需è¦PE/COFFé•œåƒæ–‡ä»¶å¤´ã€‚为了 + 支æŒEFI桩，应该用“MZâ€é”术å—符替æ¢æŽ‰code0，并且res3（å移é‡æœª0x3c）应指å‘PE/COFF + 文件头的其余部分. + +- 表示文件头版本å·çš„Drop-bitä½åŸŸ + + ========== ========== + Bits 0:15 æ¬¡è¦ ç‰ˆæœ¬ + Bits 16:31 ä¸»è¦ ç‰ˆæœ¬ + ========== ========== + + è¿™ä¿æŒäº†æ–°æ—§ç‰ˆæœ¬ä¹‹é—´çš„兼容性。 + 当å‰ç‰ˆæœ¬è¢«å®šä¹‰ä¸º0.2。 + +- 从版本0.2开始，结构体æˆå‘˜â€œmagicâ€å°±å·²ç»è¢«å¼ƒç”¨ï¼Œåœ¨ä¹‹åŽçš„版本ä¸ï¼Œå¯èƒ½ä¼šç§»é™¤æŽ‰å®ƒã€‚ + 最åˆï¼Œè¯¥æˆå‘˜åº”该与ARM64头的“magicâ€æˆå‘˜åŒ¹é…，但é—憾的是并没有。 + “magic2â€æˆå‘˜ä»£æ›¿â€œmagicâ€æˆå‘˜ä¸ŽARM64头相匹é…。 + +- 在当å‰çš„æ–‡ä»¶å¤´ï¼Œæ ‡å¿—ä½åŸŸåªå‰©ä¸‹äº†ä¸€ä¸ªä½ã€‚ + + ===== ============================== + Bit 0 å†…æ ¸å—节åºã€‚1 if BE, 0 if LE. + ===== ============================== + +- å¯¹äºŽå¼•å¯¼åŠ è½½ç¨‹åºåŠ è½½å†…æ ¸æ˜ åƒæ¥è¯´ï¼Œimage_sizeæˆå‘˜å¯¹å¼•å¯¼åŠ 载程åºè€Œè¨€æ˜¯å¿…é¡»çš„ï¼Œå¦ + 则将引导失败。 diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst new file mode 100644 index 000000000000..db13b1101490 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_index: + + +=============== +RISC-V 体系结构 +=============== + +.. toctree:: + :maxdepth: 1 + + boot-image-header + pmu + patch-acceptance + + +.. only:: subproject and html + + 目录 + ==== + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst new file mode 100644 index 000000000000..9fd1c8216763 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/patch-acceptance` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_patch-acceptance: + + +arch/riscv å¼€å‘è€…ç»´æŠ¤æŒ‡å— +========================= + +概述 +---- +RISC-V指令集体系结构是公开开å‘的： +æ£åœ¨è¿›è¡Œçš„è‰æ¡ˆå¯ä¾›æ‰€æœ‰äººæŸ¥çœ‹å’Œæµ‹è¯•å®žçŽ°ã€‚新模å—或者扩展è‰æ¡ˆå¯èƒ½ä¼šåœ¨å¼€å‘过程ä¸å‘ +生更改---有时以ä¸å…¼å®¹çš„æ–¹å¼å¯¹ä»¥å‰çš„è‰æ¡ˆè¿›è¡Œæ›´æ”¹ã€‚è¿™ç§çµæ´»æ€§å¯èƒ½ä¼šç»™RISC-V Linux +维护者带æ¥æŒ‘战。Linuxå¼€å‘过程更喜欢ç»è¿‡è‰¯å¥½æ£€æŸ¥å’Œæµ‹è¯•çš„代ç ，而ä¸æ˜¯è¯•éªŒä»£ç 。我 +们希望推广åŒæ ·çš„规则到å³å°†è¢«å†…æ ¸åˆå¹¶çš„RISC-V相关代ç 。 + +é™„åŠ çš„æäº¤æ£€æŸ¥å• +---------------- +我们仅接å—ç›¸å…³æ ‡å‡†å·²ç»è¢«RISC-VåŸºé‡‘ä¼šæ ‡å‡†ä¸ºâ€œå·²æ‰¹å‡†â€æˆ–“已冻结â€çš„扩展或模å—çš„è¡¥ä¸ã€‚ +（开å‘者当然å¯ä»¥ç»´æŠ¤è‡ªå·±çš„Linuxå†…æ ¸æ ‘ï¼Œå…¶ä¸åŒ…å«æ‰€éœ€ä»£ç 扩展è‰æ¡ˆçš„代ç 。） + +æ¤å¤–，RISC-V规范å…许爱好者创建自己的自定义扩展。这些自定义拓展ä¸éœ€è¦é€šè¿‡RISC-V +åŸºé‡‘ä¼šçš„ä»»ä½•å®¡æ ¸æˆ–æ‰¹å‡†ã€‚ä¸ºäº†é¿å…将爱好者一些特别的RISC-Væ‹“å±•æ·»åŠ è¿›å†…æ ¸ä»£ç å¸¦æ¥ +的维护å¤æ‚性和对性能的潜在影å“，我们将åªæŽ¥å—RISC-V基金会æ£å¼å†»ç»“或批准的的扩展 +è¡¥ä¸ã€‚（开å‘者当然å¯ä»¥ç»´æŠ¤è‡ªå·±çš„Linuxå†…æ ¸æ ‘ï¼Œå…¶ä¸åŒ…å«ä»–们想è¦çš„任何自定义扩展 +的代ç 。） diff --git a/Documentation/translations/zh_CN/riscv/pmu.rst b/Documentation/translations/zh_CN/riscv/pmu.rst new file mode 100644 index 000000000000..22dcf3a9ca6e --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/pmu.rst @@ -0,0 +1,233 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/pmu` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_pmu: + + +======================== +RISC-Vå¹³å°ä¸Šå¯¹PMUsçš„æ”¯æŒ +======================== + +Alan Kao <alankao@andestech.com>, Mar 2018 + +简介 +------------ + +截æ¢æœ¬æ–‡æ’°å†™æ—¶ï¼Œåœ¨The RISC-V ISA Privileged Version 1.10ä¸æ到的 perf_event +相关特性如下: +（详情请查阅手册） + +* [m|s]counteren +* mcycle[h], cycle[h] +* minstret[h], instret[h] +* mhpeventx, mhpcounterx[h] + +仅有以上这些功能，移æ¤perf需è¦åšå¾ˆå¤šå·¥ä½œï¼Œç©¶å…¶åŽŸå› 是缺少以下通用架构的性能 +监测特性: + +* å¯ç”¨/åœç”¨è®¡æ•°å™¨ + 在我们这里，计数器一直在自由è¿è¡Œã€‚ +* 计数器溢出引起的ä¸æ– + 规范ä¸æ²¡æœ‰è¿™ç§åŠŸèƒ½ã€‚ +* ä¸æ–指示器 + ä¸å¯èƒ½æ‰€æœ‰çš„计数器都有很多的ä¸æ–端å£ï¼Œæ‰€ä»¥éœ€è¦ä¸€ä¸ªä¸æ–指示器让软件æ¥åˆ¤æ– + 哪个计数器刚好溢出。 +* 写入计数器 + ç”±äºŽå†…æ ¸ä¸èƒ½ä¿®æ”¹è®¡æ•°å™¨ï¼Œæ‰€ä»¥ä¼šæœ‰ä¸€ä¸ªSBIæ¥æ”¯æŒè¿™ä¸ªåŠŸèƒ½[1]。 å¦å¤–，一些厂商 + 考虑实现M-S-Uåž‹å·æœºå™¨çš„硬件扩展æ¥ç›´æŽ¥å†™å…¥è®¡æ•°å™¨ã€‚ + +这篇文档旨在为开å‘者æä¾›ä¸€ä¸ªåœ¨å†…æ ¸ä¸æ”¯æŒPMU的简è¦æŒ‡å—。下é¢çš„ç« èŠ‚ç®€è¦è§£é‡Šäº† +perf' 机制和待办事项。 + +ä½ å¯ä»¥åœ¨è¿™é‡ŒæŸ¥çœ‹ä»¥å‰çš„讨论[1][2]。 å¦å¤–，查看附录ä¸çš„ç›¸å…³å†…æ ¸ç»“æž„ä½“å¯èƒ½ä¼šæœ‰ +帮助。 + + +1. åˆå§‹åŒ– +--------- + +*riscv_pmu* 是一个类型为 *struct riscv_pmu* 的全局指针，它包å«äº†æ ¹æ®perf内部 +约定的å„ç§æ–¹æ³•å’ŒPMU-specificå‚æ•°ã€‚äººä»¬åº”è¯¥å£°æ˜Žè¿™æ ·çš„å®žä¾‹æ¥ä»£è¡¨PMU。 默认情况 +下， *riscv_pmu* 指å‘一个常é‡ç»“构体 *riscv_base_pmu* ，它对基准QEMU模型有éžå¸¸ +基础的支æŒã€‚ + + +然åŽä»–/她å¯ä»¥å°†å®žä¾‹çš„指针分é…ç»™ *riscv_pmu* ï¼Œè¿™æ ·å°±å¯ä»¥åˆ©ç”¨å·²ç»å®žçŽ°çš„最å°é€» +辑，或者创建他/她自己的 *riscv_init_platform_pmu* 实现。 + +æ¢å¥è¯è¯´ï¼ŒçŽ°æœ‰çš„ *riscv_base_pmu* æºåªæ˜¯æ供了一个å‚考实现。 å¼€å‘者å¯ä»¥çµæ´»åœ° +决定多少部分å¯ç”¨ï¼Œåœ¨æœ€æžç«¯çš„情况下，他们å¯ä»¥æ ¹æ®è‡ªå·±çš„需è¦å®šåˆ¶æ¯ä¸€ä¸ªå‡½æ•°ã€‚ + + +2. Event Initialization +----------------------- + +当用户å¯åŠ¨perf命令æ¥ç›‘控一些事件时，首先会被用户空间的perf工具解释为多个 +*perf_event_open* 系统调用，然åŽè¿›ä¸€æ¥è°ƒç”¨ä¸Šä¸€æ¥åˆ†é…çš„ *event_init* æˆå‘˜å‡½æ•° +的主体。 在 *riscv_base_pmu* 的情况下，就是 *riscv_event_init* 。 + +该功能的主è¦ç›®çš„是将用户æ供的事件翻译æˆæ˜ 射图，从而å¯ä»¥ç›´æŽ¥å¯¹HW-related的控 +制寄å˜å™¨æˆ–计数器进行æ“作。该翻译基于 *riscv_pmu* ä¸æä¾›çš„æ˜ å°„å’Œæ–¹æ³•ã€‚ + +注æ„，有些功能也å¯ä»¥åœ¨è¿™ä¸ªé˜¶æ®µå®Œæˆ: + +(1) ä¸æ–设置，这个在下一节说； +(2) 特é™çº§è®¾ç½®(仅用户空间ã€ä»…å†…æ ¸ç©ºé—´ã€ä¸¤è€…都有)ï¼› +(3) æžæž„函数设置。 通常应用 *riscv_destroy_event* å³å¯ï¼› +(4) 对éžé‡‡æ ·äº‹ä»¶çš„调整，这将被函数应用，如 *perf_adjust_period* ，通常如下:: + + if (!is_sampling_event(event)) { + hwc->sample_period = x86_pmu.max_period; + hwc->last_period = hwc->sample_period; + local64_set(&hwc->period_left, hwc->sample_period); + } + + +在 *riscv_base_pmu* 的情况下，目å‰åªæ供了（3）。 + + +3. ä¸æ– +------- + +3.1. ä¸æ–åˆå§‹åŒ– + +è¿™ç§æƒ…况ç»å¸¸å‡ºçŽ°åœ¨ *event_init* 方案的开头。通常情况下，这应该是一个代ç 段，如:: + + int x86_reserve_hardware(void) + { + int err = 0; + + if (!atomic_inc_not_zero(&pmc_refcount)) { + mutex_lock(&pmc_reserve_mutex); + if (atomic_read(&pmc_refcount) == 0) { + if (!reserve_pmc_hardware()) + err = -EBUSY; + else + reserve_ds_buffers(); + } + if (!err) + atomic_inc(&pmc_refcount); + mutex_unlock(&pmc_reserve_mutex); + } + + return err; + } + +而神奇的是 *reserve_pmc_hardware* ，它通常åšåŽŸåæ“作，使实现的IRQå¯ä»¥ä»ŽæŸä¸ªå…¨å±€å‡½ +数指针访问。 而 *release_pmc_hardware* 的作用æ£å¥½ç›¸å，它用在上一节æåˆ°çš„äº‹ä»¶åˆ†é… +器ä¸ã€‚ + + (注：从所有架构的实现æ¥çœ‹ï¼Œ*reserve/release* 对总是IRQ设置，所以 *pmc_hardware* + 似乎有些误导。 它并ä¸å¤„ç†äº‹ä»¶å’Œç‰©ç†è®¡æ•°å™¨ä¹‹é—´çš„绑定，这一点将在下一节介ç»ã€‚) + +3.2. IRQ结构体 + +基本上，一个IRQè¿è¡Œä»¥ä¸‹ä¼ªä»£ç :: + + for each hardware counter that triggered this overflow + + get the event of this counter + + // following two steps are defined as *read()*, + // check the section Reading/Writing Counters for details. + count the delta value since previous interrupt + update the event->count (# event occurs) by adding delta, and + event->hw.period_left by subtracting delta + + if the event overflows + sample data + set the counter appropriately for the next overflow + + if the event overflows again + too frequently, throttle this event + fi + fi + + end for + + 然而截至目å‰ï¼Œæ²¡æœ‰ä¸€ä¸ªRISC-V的实现为perf设计了ä¸æ–，所以具体的实现è¦åœ¨æœªæ¥å®Œæˆã€‚ + +4. Reading/Writing 计数 +----------------------- + +它们看似差ä¸å¤šï¼Œä½†perf对待它们的æ€åº¦å´æˆªç„¶ä¸åŒã€‚ 对于读，在 *struct pmu* ä¸æœ‰ä¸€ä¸ª +*read* 接å£ï¼Œä½†å®ƒçš„作用ä¸ä»…仅是读。 æ ¹æ®ä¸Šä¸‹æ–‡ï¼Œ*read* 函数ä¸ä»…è¦è¯»å–计数器的内容 +（event->count），还è¦æ›´æ–°å·¦å‘¨æœŸåˆ°ä¸‹ä¸€ä¸ªä¸æ–（event->hw.period_left）。 + + 但 perf çš„æ ¸å¿ƒä¸éœ€è¦ç›´æŽ¥å†™è®¡æ•°å™¨ã€‚ 写计数器éšè—在以下两点的抽象化之åŽï¼Œ + 1） *pmu->start* ，从å—é¢ä¸Šçœ‹å°±æ˜¯å¼€å§‹è®¡æ•°ï¼Œæ‰€ä»¥å¿…须把计数器设置æˆä¸€ä¸ªåˆé€‚的值，以 + 便下一次ä¸æ–ï¼› + 2）在IRQ里é¢ï¼Œåº”该把计数器设置æˆåŒæ ·çš„åˆç†å€¼ã€‚ + +在RISC-Vä¸ï¼Œè¯»æ“作ä¸æ˜¯é—®é¢˜ï¼Œä½†å†™æ“作就需è¦è´¹äº›åŠ›æ°”äº†ï¼Œå› ä¸ºS模å¼ä¸å…许写计数器。 + + +5. add()/del()/start()/stop() +----------------------------- + +基本æ€æƒ³: add()/del() å‘PMUæ·»åŠ /åˆ é™¤äº‹ä»¶ï¼Œstart()/stop() å¯åŠ¨/åœæ¢PMUä¸æŸä¸ªäº‹ä»¶ +的计数器。 所有这些函数都使用相åŒçš„å‚æ•°: *struct perf_event *event* å’Œ *int flag* 。 + +把 perf 看作一个状æ€æœºï¼Œé‚£ä¹ˆä½ 会å‘现这些函数作为这些状æ€ä¹‹é—´çš„状æ€è½¬æ¢è¿‡ç¨‹ã€‚ +定义了三ç§çŠ¶æ€ï¼ˆevent->hw.state）: + +* PERF_HES_STOPPED: 计数åœæ¢ +* PERF_HES_UPTODATE: event->count是最新的 +* PERF_HES_ARCH: ä¾èµ–于体系结构的用法，。。。我们现在并ä¸éœ€è¦å®ƒã€‚ + +这些状æ€è½¬æ¢çš„æ£å¸¸æµç¨‹å¦‚下: + +* 用户å¯åŠ¨ä¸€ä¸ª perf 事件，导致调用 *event_init* 。 +* 当被上下文切æ¢è¿›æ¥çš„时候，*add* 会被 perf core è°ƒç”¨ï¼Œå¹¶å¸¦æœ‰ä¸€ä¸ªæ ‡å¿— PERF_EF_START， + ä¹Ÿå°±æ˜¯è¯´äº‹ä»¶è¢«æ·»åŠ åŽåº”该被å¯åŠ¨ã€‚ 在这个阶段，如果有的è¯ï¼Œä¸€èˆ¬äº‹ä»¶ä¼šè¢«ç»‘定到一个物 + ç†è®¡æ•°å™¨ä¸Šã€‚当状æ€å˜ä¸ºPERF_HES_STOPPEDå’ŒPERF_HES_UPTODATEï¼Œå› ä¸ºçŽ°åœ¨å·²ç»åœæ¢äº†, + （软件）事件计数ä¸éœ€è¦æ›´æ–°ã€‚ + + - 然åŽè°ƒç”¨ *start* ，并å¯ç”¨è®¡æ•°å™¨ã€‚ + 通过PERF_EF_RELOADæ ‡å¿—ï¼Œå®ƒå‘计数器写入一个适当的值（详细情况请å‚考上一节）。 + å¦‚æžœæ ‡å¿—ä¸åŒ…å«PERF_EF_RELOAD，则ä¸ä¼šå†™å…¥ä»»ä½•å†…容。 + 现在状æ€è¢«é‡ç½®ä¸ºnoneï¼Œå› ä¸ºå®ƒæ—¢æ²¡æœ‰åœæ¢ä¹Ÿæ²¡æœ‰æ›´æ–°ï¼ˆè®¡æ•°å·²ç»å¼€å§‹ï¼‰ã€‚ + +*当被上下文切æ¢å‡ºæ¥æ—¶è¢«è°ƒç”¨ã€‚ 然åŽï¼Œå®ƒæ£€æŸ¥å‡ºPMUä¸çš„所有事件，并调用 *stop* æ¥æ›´æ–°å®ƒä»¬ + 的计数。 + + - *stop* 被 *del* å’Œperfæ ¸å¿ƒè°ƒç”¨ï¼Œæ ‡å¿—ä¸ºPERF_EF_UPDATE，它ç»å¸¸ä»¥ç›¸åŒçš„逻辑和 *read* + 共用åŒä¸€ä¸ªå程åºã€‚ + 状æ€åˆä¸€æ¬¡å˜ä¸ºPERF_HES_STOPPEDå’ŒPERF_HES_UPTODATE。 + + - 这两对程åºçš„生命周期: *add* å’Œ *del* 在任务切æ¢æ—¶è¢«åå¤è°ƒç”¨ï¼›*start* å’Œ *stop* 在 + perfæ ¸å¿ƒéœ€è¦å¿«é€Ÿåœæ¢å’Œå¯åŠ¨æ—¶ä¹Ÿä¼šè¢«è°ƒç”¨ï¼Œæ¯”如在调整ä¸æ–周期时。 + +ç›®å‰çš„实现已ç»è¶³å¤Ÿäº†ï¼Œå°†æ¥å¯ä»¥å¾ˆå®¹æ˜“地扩展到功能。 + +A. 相关结构体 +------------- + +* struct pmu: include/linux/perf_event.h +* struct riscv_pmu: arch/riscv/include/asm/perf_event.h + + 两个结构体都被设计为åªè¯»ã€‚ + + *struct pmu* 定义了一些函数指针接å£ï¼Œå®ƒä»¬å¤§å¤šä»¥ *struct perf_event* 作为主å‚æ•°ï¼Œæ ¹æ® + perf的内部状æ€æœºå¤„ç†perf事件（详情请查看kernel/events/core.c）。 + + *struct riscv_pmu* 定义了PMU的具体å‚数。 命åéµå¾ªæ‰€æœ‰å…¶å®ƒæž¶æž„的惯例。 + +* struct perf_event: include/linux/perf_event.h +* struct hw_perf_event + + 表示 perf 事件的通用结构体，以åŠç¡¬ä»¶ç›¸å…³çš„细节。 + +* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h + + ä¿å˜äº‹ä»¶çŠ¶æ€çš„结构有两个固定æˆå‘˜ã€‚ + 事件的数é‡å’Œäº‹ä»¶çš„数组。 + +å‚考文献 +-------- + +[1] https://github.com/riscv/riscv-linux/pull/124 + +[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA diff --git a/Documentation/translations/zh_CN/sound/hd-audio/controls.rst b/Documentation/translations/zh_CN/sound/hd-audio/controls.rst new file mode 100644 index 000000000000..54c028ab9a40 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/hd-audio/controls.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Chinese translator: Huang Jianghui <huangjianghui@uniontech.com> +--------------------------------------------------------------------- +.. include:: ../../disclaimer-zh_CN.rst +以下为æ£æ–‡ +--------------------------------------------------------------------- +====================================== +高清音频编解ç 器特定混音器控件 +====================================== + + +æ¤æ–‡ä»¶è§£é‡Šç‰¹å®šäºŽç¼–解ç 器的混音器控件. + +瑞昱编解ç 器 +------------ + +声é“æ¨¡å¼ + 这是一个用于更改环绕声é“设置的枚举控件,仅在环绕声é“打开时显示出现。 + 它给出è¦ä½¿ç”¨çš„通é“æ•°:"2ch","4ch","6ch"，和"8ch"ã€‚æ ¹æ®é…置，这还控 + 制多I/Oæ’å”çš„æ’å”é‡åˆ†é…。 + +自动é™éŸ³æ¨¡å¼ + 这是一个枚举控件，用于更改耳机和线路输出æ’å”的自动é™éŸ³è¡Œä¸ºã€‚如果内 + 置扬声器ã€è€³æœºå’Œ/或线路输出æ’å”在机器上å¯ç”¨ï¼Œåˆ™æ˜¾ç¤ºè¯¥æŽ§ä»¶ã€‚当åªæœ‰ + 耳机或者线路输出的时候，它给出â€ç¦ç”¨â€œå’Œâ€å¯ç”¨â€œçŠ¶æ€ã€‚当å¯ç”¨åŽï¼Œæ’å”æ’ + å…¥åŽæ‰¬å£°å™¨ä¼šè‡ªåŠ¨é™éŸ³ã€‚ + + 当耳机和线路输出æ’å”都å˜åœ¨æ—¶ï¼Œå®ƒç»™å‡ºâ€ç¦ç”¨â€œã€â€ä»…扬声器“和â€çº¿è·¯è¾“出+扬 + 声器“。当â€ä»…扬声器“被选择，æ’入耳机或者线路输出æ’å”å¯ä½¿æ‰¬å£°å™¨é™éŸ³ï¼Œ + 但ä¸ä¼šä½¿çº¿è·¯è¾“出é™éŸ³ã€‚当线路输出+扬声器被选择，æ’入耳机æ’å”会åŒæ—¶ä½¿æ‰¬ + 声器和线路输出é™éŸ³ã€‚ + + +矽玛特编解ç 器 +-------------- + +模拟环回 + æ¤æŽ§ä»¶å¯ç”¨/ç¦ç”¨æ¨¡æ‹ŸçŽ¯å›žç”µè·¯ã€‚åªæœ‰åœ¨ç¼–解ç 器æ示ä¸å°†â€lookback“设置为真 + æ—¶æ‰ä¼šå‡ºçŽ°(è§HD-Audio.txt)。请注æ„，在æŸäº›ç¼–解ç 器上，模拟环回和æ£å¸¸ + PCMæ’放是独å çš„,å³å½“æ¤é€‰é¡¹æ‰“开时，您将å¬ä¸åˆ°ä»»ä½•PCMæµã€‚ + +交æ¢ä¸ç½®/低频 + 交æ¢ä¸ç½®å’Œä½Žé¢‘通é“顺åºï¼Œé€šå¸¸æƒ…况下，左侧对应ä¸ç½®ï¼Œå³ä¾§å¯¹åº”低频,å¯åŠ¨æ¤ + 项åŽï¼Œå·¦è¾¹ä½Žé¢‘，å³è¾¹ä¸ç½®ã€‚ + +耳机作为线路输出 + 当æ¤æŽ§åˆ¶å¼€å¯æ—¶ï¼Œå°†è€³æœºè§†ä¸ºçº¿è·¯è¾“出æ’å”。也就是说，耳机ä¸ä¼šè‡ªåŠ¨é™éŸ³å…¶ä»– + 线路输出，没有耳机放大器被设置到引脚上。 + +麦克风æ’å£æ¨¡å¼ã€çº¿è·¯æ’å”模å¼ç‰ + 这些枚举控制输入æ’å”引脚的方å‘å’Œåç½®ã€‚æ ¹æ®æ’å”类型，它å¯ä»¥è®¾ç½®ä¸ºâ€éº¦å…‹é£Ž + 输入“和â€çº¿è·¯è¾“入“以确定输入åç½®,或者当引脚是环绕声é“的多I/Oæ’å”时，它 + å¯ä»¥è®¾ç½®ä¸ºâ€çº¿è·¯è¾“出“。 + + +å¨ç››ç¼–解ç 器 +------------ + +智能5.1 + 一个枚举控件，用于为环绕输出é‡æ–°åˆ†é…多个I/Oæ’å”的任务。当它打开时，相应 + 的输入æ’å”（通常是线路输入和麦克风输入）被切æ¢ä¸ºçŽ¯ç»•å’Œä¸å¤®ä½Žé¢‘输出æ’å”。 + +独立耳机 + å¯ç”¨æ¤æžšä¸¾æŽ§åˆ¶æ—¶ï¼Œè€³æœºè¾“出从å•ä¸ªæµï¼ˆç¬¬ä¸‰ä¸ªPCM，如hw:0,2）而ä¸æ˜¯ä¸»æµè·¯ç”±ã€‚ + 如果耳机DAC与侧边或ä¸å¤®ä½Žé¢‘通é“DAC共享，则DAC将自动切æ¢åˆ°è€³æœºã€‚ + +çŽ¯å›žæ··åˆ + 一个用于确定是å¦å¯åŠ¨äº†æ¨¡æ‹ŸçŽ¯å›žè·¯ç”±çš„枚举控件。当它å¯ç”¨åŽï¼Œæ¨¡æ‹ŸçŽ¯å›žè·¯ç”±åˆ° + å‰ç½®é€šé“。åŒæ ·ï¼Œè€³æœºä¸Žæ‰¬å£°å™¨è¾“出也采用相åŒçš„路径。作为一个副作用，当设置 + æ¤æ¨¡å¼åŽï¼Œå•ä¸ªéŸ³é‡æŽ§åˆ¶å°†ä¸å†é€‚ç”¨äºŽè€³æœºå’Œæ‰¬å£°å™¨ï¼Œå› ä¸ºåªæœ‰ä¸€ä¸ªDAC连接到混 + 音器å°éƒ¨ä»¶ã€‚ + +动æ€ç”µæºæŽ§åˆ¶ + æ¤æŽ§ä»¶å†³å®šæ˜¯å¦å¯åŠ¨æ¯ä¸ªæ’å”的动æ€ç”µæºæŽ§åˆ¶æ£€æµ‹ã€‚å¯ç”¨æ—¶ï¼Œæ ¹æ®æ’å”çš„æ’入情况 + 动æ€æ›´æ”¹ç»„件的电æºçŠ¶æ€ï¼ˆD0/D3）以节çœç”µé‡æ¶ˆè€—。但是，如果您的系统没有æ + ä¾›æ£ç¡®çš„æ’å”æ£€æµ‹ï¼Œè¿™å°†æ— æ³•å·¥ä½œ;在这ç§æƒ…况下，请关é—æ¤æŽ§ä»¶ã€‚ + +æ’å”检测 + æ¤æŽ§ä»¶ä»…为VT1708编解ç 器æ供，它ä¸ä¼šä¸ºæ¯ä¸ªæ’å”æ’æ‹”æ供适当的未请求事件。 + 当æ¤æŽ§ä»¶æ‰“开，驱动将轮询æ’å”检测，以便耳机自动é™éŸ³å¯ä»¥å·¥ä½œï¼Œè€Œå…³é—æ¤æŽ§ + 件将é™ä½ŽåŠŸè€—。 + + +科胜讯编解ç 器 +-------------- + +自动é™éŸ³æ¨¡å¼ + è§ç‘žæ˜±è§£ç 器 + + + +模拟编解ç 器 +------------ + +通é“æ¨¡å¼ + 这是一个用于更改环绕声é“设置的枚举控件,仅在环绕声é“å¯ç”¨æ—¶æ˜¾ç¤ºã€‚它æ供了能 + 被使用的通é“æ•°:â€2ch“ã€â€4ch“和â€6châ€œã€‚æ ¹æ®é…置，这还控制多I/Oæ’å”çš„æ’å”é‡ + 分é…。 + +独立耳机 + å¯åŠ¨æ¤æžšä¸¾æŽ§åˆ¶åŽï¼Œè€³æœºè¾“出从å•ä¸ªæµï¼ˆç¬¬ä¸‰ä¸ªPCM，如hw:0,2）而ä¸æ˜¯ä¸»æµè·¯ç”±ã€‚ diff --git a/Documentation/translations/zh_CN/sound/hd-audio/index.rst b/Documentation/translations/zh_CN/sound/hd-audio/index.rst new file mode 100644 index 000000000000..d9885d53b069 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/hd-audio/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../sound/hd-audio/index` +:Translator: Huang Jianghui <huangjianghui@uniontech.com> + + +高清音频 +======== + +.. toctree:: + :maxdepth: 2 + + controls diff --git a/Documentation/translations/zh_CN/sound/index.rst b/Documentation/translations/zh_CN/sound/index.rst new file mode 100644 index 000000000000..28d5dca34a63 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../sound/index` +:Translator: Huang Jianghui <huangjianghui@uniontech.com> + + +==================== +Linux 声音å系统文档 +==================== + +.. toctree:: + :maxdepth: 2 + + hd-audio/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/usb/usbip_protocol.rst b/Documentation/usb/usbip_protocol.rst index 988c832166cd..0b8541fda4d8 100644 --- a/Documentation/usb/usbip_protocol.rst +++ b/Documentation/usb/usbip_protocol.rst @@ -2,15 +2,15 @@ USB/IP protocol =============== -PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! -28 Jun 2011 +Architecture +============ The USB/IP protocol follows a server/client architecture. The server exports the -USB devices and the clients imports them. The device driver for the exported +USB devices and the clients import them. The device driver for the exported USB device runs on the client machine. The client may ask for the list of the exported USB devices. To get the list the -client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST +client opens a TCP/IP connection to the server, and sends an OP_REQ_DEVLIST packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent in one or more pieces at the low level transport layer). The server sends back the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the @@ -30,7 +30,7 @@ TCP/IP connection is closed. | | Once the client knows the list of exported USB devices it may decide to use one -of them. First the client opens a TCP/IP connection towards the server and +of them. First the client opens a TCP/IP connection to the server and sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the import was successful the TCP/IP connection remains open and will be used to transfer the URB traffic between the client and the server. The client may @@ -84,17 +84,61 @@ server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. | <---------------------------------------------- | | . | | : | + +For UNLINK, note that after a successful USBIP_RET_UNLINK, the unlinked URB +submission would not have a corresponding USBIP_RET_SUBMIT (this is explained in +function stub_recv_cmd_unlink of drivers/usb/usbip/stub_rx.c). + +:: + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USB devices) + | | + | USBIP_CMD_SUBMIT(seqnum = p) | + | ----------------------------------------------> | | | | USBIP_CMD_UNLINK | + | (seqnum = p+1, unlink_seqnum = p) | | ----------------------------------------------> | | | | USBIP_RET_UNLINK | + | (seqnum = p+1, status = -ECONNRESET) | + | <---------------------------------------------- | + | | + | Note: No USBIP_RET_SUBMIT(seqnum = p) | + | <--X---X---X---X---X---X---X---X---X---X---X--- | + | . | + | : | + | | + | USBIP_CMD_SUBMIT(seqnum = q) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = q) | + | <---------------------------------------------- | + | | + | USBIP_CMD_UNLINK | + | (seqnum = q+1, unlink_seqnum = q) | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | (seqnum = q+1, status = 0) | | <---------------------------------------------- | | | The fields are in network (big endian) byte order meaning that the most significant byte (MSB) is stored at the lowest address. +Protocol Version +================ + +The documented USBIP version is v1.1.1. The binary representation of this +version in message headers is 0x0111. + +This is defined in tools/usb/usbip/configure.ac + +Message Format +============== OP_REQ_DEVLIST: Retrieve the list of exported USB devices. @@ -102,7 +146,7 @@ OP_REQ_DEVLIST: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB | | | | | devices. | @@ -116,7 +160,7 @@ OP_REP_DEVLIST: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0.| +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. | +-----------+--------+------------+---------------------------------------------------+ @@ -165,8 +209,8 @@ OP_REP_DEVLIST: | 0x143 | 1 | | bNumInterfaces | +-----------+--------+------------+---------------------------------------------------+ | 0x144 | | m_0 | From now on each interface is described, all | -| | | | together bNumInterfaces times, with the | -| | | | the following 4 fields: | +| | | | together bNumInterfaces times, with the following | +| | | | 4 fields: | +-----------+--------+------------+---------------------------------------------------+ | | 1 | | bInterfaceClass | +-----------+--------+------------+---------------------------------------------------+ @@ -177,7 +221,7 @@ OP_REP_DEVLIST: | 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. | +| i*0x138 + | | | with the path field. | | m_(i-1)*4 | | | | +-----------+--------+------------+---------------------------------------------------+ @@ -187,7 +231,7 @@ OP_REQ_IMPORT: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x8003 | Command code: import a remote USB device. | +-----------+--------+------------+---------------------------------------------------+ @@ -206,7 +250,7 @@ OP_REP_IMPORT: +-----------+--------+------------+---------------------------------------------------+ | Offset | Length | Value | Description | +===========+========+============+===================================================+ -| 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 | +| 0 | 2 | | USBIP version | +-----------+--------+------------+---------------------------------------------------+ | 2 | 2 | 0x0003 | Reply code: Reply to import. | +-----------+--------+------------+---------------------------------------------------+ @@ -254,158 +298,156 @@ OP_REP_IMPORT: | 0x13E | 1 | | bNumInterfaces | +-----------+--------+------------+---------------------------------------------------+ -USBIP_CMD_SUBMIT: - Submit an URB +The following four commands have a common basic header called +'usbip_header_basic', and their headers, called 'usbip_header' (before +transfer_buffer payload), have the same length, therefore paddings are needed. -+-----------+--------+------------+---------------------------------------------------+ -| 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. | -+-----------+--------+------------+---------------------------------------------------+ +usbip_header_basic: ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 4 | command | ++-----------+--------+---------------------------------------------------+ +| 4 | 4 | seqnum: sequential number that identifies requests| +| | | and corresponding responses; | +| | | incremented per connection | ++-----------+--------+---------------------------------------------------+ +| 8 | 4 | devid: specifies a remote USB device uniquely | +| | | instead of busnum and devnum; | +| | | for client (request), this value is | +| | | ((busnum << 16) | devnum); | +| | | for server (response), this shall be set to 0 | ++-----------+--------+---------------------------------------------------+ +| 0xC | 4 | direction: | +| | | | +| | | - 0: USBIP_DIR_OUT | +| | | - 1: USBIP_DIR_IN | +| | | | +| | | only used by client, for server this shall be 0 | ++-----------+--------+---------------------------------------------------+ +| 0x10 | 4 | ep: endpoint number | +| | | only used by client, for server this shall be 0; | +| | | for UNLINK, this shall be 0 | ++-----------+--------+---------------------------------------------------+ - +-------------------------+------------+---------+-----------+----------+-------------+ - | 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_CMD_SUBMIT: + Submit an URB ++-----------+--------+---------------------------------------------------+ +| Offset | Length | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000001 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | transfer_flags: possible values depend on the | +| | | URB transfer_flags (refer to URB doc in | +| | | Documentation/driver-api/usb/URB.rst) | +| | | but with URB_NO_TRANSFER_DMA_MAP masked. Refer to | +| | | function usbip_pack_cmd_submit and function | +| | | tweak_transfer_flags in drivers/usb/usbip/ | +| | | usbip_common.c. The following fields may also ref | +| | | to function usbip_pack_cmd_submit and URB doc | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 4 | transfer_buffer_length: | +| | | use URB transfer_buffer_length | ++-----------+--------+---------------------------------------------------+ +| 0x1C | 4 | start_frame: use URB start_frame; | +| | | initial frame for ISO transfer; | +| | | shall be set to 0 if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x20 | 4 | number_of_packets: number of ISO packets; | +| | | shall be set to 0xffffffff if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 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 | n | transfer_buffer. | +| | | If direction is USBIP_DIR_OUT then n equals | +| | | transfer_buffer_length; otherwise n equals 0. | +| | | For ISO transfers the padding between each ISO | +| | | packets is not transmitted. | ++-----------+--------+---------------------------------------------------+ +| 0x30+n | m | iso_packet_descriptor | ++-----------+--------+---------------------------------------------------+ 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 | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000003 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | status: zero for successful URB transaction, | +| | | otherwise some kind of error happened. | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 4 | actual_length: number of URB data bytes; | +| | | use URB actual_length | ++-----------+--------+---------------------------------------------------+ +| 0x1C | 4 | start_frame: use URB start_frame; | +| | | initial frame for ISO transfer; | +| | | shall be set to 0 if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x20 | 4 | number_of_packets: number of ISO packets; | +| | | shall be set to 0xffffffff if not ISO transfer | ++-----------+--------+---------------------------------------------------+ +| 0x24 | 4 | error_count | ++-----------+--------+---------------------------------------------------+ +| 0x28 | 8 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ +| 0x30 | n | transfer_buffer. | +| | | If direction is USBIP_DIR_IN then n equals | +| | | actual_length; otherwise n equals 0. | +| | | For ISO transfers the padding between each ISO | +| | | packets is not transmitted. | ++-----------+--------+---------------------------------------------------+ +| 0x30+n | m | iso_packet_descriptor | ++-----------+--------+---------------------------------------------------+ 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 | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000002 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | unlink_seqnum, of the SUBMIT request to unlink | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 24 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ 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 | Description | ++===========+========+===================================================+ +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000004 | ++-----------+--------+---------------------------------------------------+ +| 0x14 | 4 | status: This is similar to the status of | +| | | USBIP_RET_SUBMIT (share the same memory offset). | +| | | When UNLINK is successful, status is -ECONNRESET; | +| | | when USBIP_CMD_UNLINK is after USBIP_RET_SUBMIT | +| | | status is 0 | ++-----------+--------+---------------------------------------------------+ +| 0x18 | 24 | padding, shall be set to 0 | ++-----------+--------+---------------------------------------------------+ + +EXAMPLE +======= + + The following data is captured from wire with Human Interface Devices (HID) + payload + +:: + + CmdIntrIN: 00000001 00000d05 0001000f 00000001 00000001 00000200 00000040 ffffffff 00000000 00000004 00000000 00000000 + CmdIntrOUT: 00000001 00000d06 0001000f 00000000 00000001 00000000 00000040 ffffffff 00000000 00000004 00000000 00000000 + ffffffff860008a784ce5ae212376300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 + RetIntrOut: 00000003 00000d06 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000 + RetIntrIn: 00000003 00000d05 00000000 00000000 00000000 00000000 00000040 ffffffff 00000000 00000000 00000000 00000000 + ffffffff860011a784ce5ae2123763612891b1020100000400000000000000000000000000000000000000000000000000000000000000000000000000000000 diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 599bd4493944..9bfc2b510c64 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -209,7 +209,6 @@ Code Seq# Include File Comments linux/fs.h, 'X' all fs/ocfs2/ocfs_fs.h conflict! 'X' 01 linux/pktcdvd.h conflict! -'Y' all linux/cyclades.h 'Z' 14-15 drivers/message/fusion/mptctl.h '[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices <mailto:gregkh@linuxfoundation.org> @@ -245,6 +244,7 @@ Code Seq# Include File Comments 'i' 00-3F linux/i2o-dev.h conflict! 'i' 0B-1F linux/ipmi.h conflict! 'i' 80-8F linux/i8k.h +'i' 90-9F `linux/iio/*.h` IIO 'j' 00-3F linux/joystick.h 'k' 00-0F linux/spi/spidev.h conflict! 'k' 00-05 video/kyro.h conflict! @@ -327,6 +327,8 @@ Code Seq# Include File Comments 0xA4 00-1F uapi/asm/sgx.h <mailto:linux-sgx@vger.kernel.org> 0xA5 01 linux/surface_aggregator/cdev.h Microsoft Surface Platform System Aggregator <mailto:luzmaximilian@gmail.com> +0xA5 20-2F linux/surface_aggregator/dtx.h Microsoft Surface DTX driver + <mailto:luzmaximilian@gmail.com> 0xAA 00-3F linux/uapi/linux/userfaultfd.h 0xAB 00-1F linux/nbd.h 0xAC 00-1F linux/raw.h @@ -347,6 +349,7 @@ Code Seq# Include File Comments 0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> 0xB6 all linux/fpga-dfl.h 0xB7 all uapi/linux/remoteproc_cdev.h <mailto:linux-remoteproc@vger.kernel.org> +0xB7 all uapi/linux/nsfs.h <mailto:Andrei Vagin <avagin@openvz.org>> 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h 0xCA 10-2F uapi/misc/ocxl.h diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst index c7309a2fcbce..d5e014ce19b5 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst @@ -35,7 +35,7 @@ device information, applications call the ioctl with a pointer to a struct :c:type:`cec_caps`. The driver fills the structure and returns the information to the application. The ioctl never fails. -.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.6cm}| .. c:type:: cec_caps @@ -63,7 +63,7 @@ returns the information to the application. The ioctl never fails. - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` macro. -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. _cec-capabilities: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst index 13116b0b5c17..0e19855730e1 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst @@ -39,7 +39,7 @@ provide a pointer to a cec_connector_info struct which will be populated by the kernel with the info provided by the adapter's driver. This ioctl is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| .. c:type:: cec_connector_info @@ -59,7 +59,7 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. * - } - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. _connector-type: @@ -82,7 +82,7 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. Information about the connector can be found in :ref:`cec-drm-connector-info`. -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| .. c:type:: cec_drm_connector_info diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst index c760c07b6b3f..f3293a589dd6 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst @@ -67,7 +67,7 @@ logical address types are already defined will return with error ``EBUSY``. .. c:type:: cec_log_addrs -.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}| +.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{8.0cm}| .. cssclass:: longtable @@ -150,7 +150,7 @@ logical address types are already defined will return with error ``EBUSY``. give the CEC framework more information about the device type, even though the framework won't use it directly in the CEC message. -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| .. _cec-log-addrs-flags: @@ -186,7 +186,7 @@ logical address types are already defined will return with error ``EBUSY``. All other messages are ignored. -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| .. _cec-versions: @@ -211,7 +211,7 @@ logical address types are already defined will return with error ``EBUSY``. - 6 - CEC version according to the HDMI 2.0 standard. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-prim-dev-types: @@ -256,7 +256,7 @@ logical address types are already defined will return with error ``EBUSY``. - 7 - Use for a video processor device. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-log-addr-types: @@ -304,7 +304,7 @@ logical address types are already defined will return with error ``EBUSY``. Control). -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _cec-all-dev-types-flags: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst index 736fda5ad73d..71d6a9e81f75 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst @@ -44,7 +44,7 @@ two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with the same state). In that case the intermediate state changes were lost but it is guaranteed that the state did change in between the two events. -.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.2cm}| .. c:type:: cec_event_state_change @@ -74,7 +74,7 @@ it is guaranteed that the state did change in between the two events. .. c:type:: cec_event_lost_msgs -.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| .. flat-table:: struct cec_event_lost_msgs :header-rows: 0 @@ -93,7 +93,7 @@ it is guaranteed that the state did change in between the two events. replied to within a second according to the CEC specification, this is more than enough. -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| .. c:type:: cec_event @@ -128,7 +128,7 @@ it is guaranteed that the state did change in between the two events. * - } - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-events: @@ -201,7 +201,7 @@ it is guaranteed that the state did change in between the two events. if the 5V is high, then an initial event will be generated for that filehandle. -.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| +.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.7cm}| .. _cec-event-flags: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst index 663bdef8d6da..5fe105a13a6e 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst @@ -72,7 +72,7 @@ always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. Available initiator modes are: -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-mode-initiator_e: @@ -106,7 +106,7 @@ Available initiator modes are: Available follower modes are: -.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}| +.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}| .. _cec-mode-follower_e: diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst index b2fc051e99f4..bd7f7e7235cb 100644 --- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst +++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst @@ -84,7 +84,7 @@ physical address, but the cable is still connected and CEC still works. In order to detect/wake up the device it is allowed to send poll and 'Image/Text View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). -.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}| +.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{12.8cm}| .. c:type:: cec_msg @@ -196,7 +196,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). supports this, otherwise it is always 0. This counter is only valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. -.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}| +.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.1cm}| .. _cec-msg-flags: @@ -229,7 +229,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). capability. If that is not set, then the ``EPERM`` error code is returned. -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-tx-status: @@ -298,7 +298,7 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - The transmit timed out. This should not normally happen and this indicates a driver problem. -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| .. _cec-rx-status: diff --git a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst index 064c8c5a1943..b0efce40471f 100644 --- a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst +++ b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst @@ -44,7 +44,7 @@ error injection status:: # <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position # <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message # <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message - # <op>[,<mode>] rx-arb-lost <poll> generate a POLL message to trigger an arbitration lost + # any[,<mode>] rx-arb-lost [<poll>] generate a POLL message to trigger an arbitration lost # # TX error injection settings: # tx-ignore-nack-until-eom ignore early NACKs until EOM diff --git a/Documentation/userspace-api/media/dvb/fe-type-t.rst b/Documentation/userspace-api/media/dvb/fe-type-t.rst index e8499d482700..e8986254897f 100644 --- a/Documentation/userspace-api/media/dvb/fe-type-t.rst +++ b/Documentation/userspace-api/media/dvb/fe-type-t.rst @@ -11,7 +11,7 @@ fe_type_t type, defined as: .. c:type:: fe_type -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: Frontend types :header-rows: 1 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst index 0c4c5d2cfcb2..d56ee6669ab9 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst @@ -39,7 +39,7 @@ ioctl never fails. .. c:type:: media_device_info -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_device_info :header-rows: 0 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst index 92dd8ecd538c..73bda02498af 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst @@ -50,7 +50,7 @@ id's until they get an error. .. c:type:: media_entity_desc -.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| +.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}| .. flat-table:: struct media_entity_desc :header-rows: 0 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst index 3bc98a6a2ec5..381804a91c99 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst @@ -54,7 +54,7 @@ returned during the enumeration process. .. c:type:: media_links_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_links_enum :header-rows: 0 @@ -82,7 +82,7 @@ returned during the enumeration process. .. c:type:: media_pad_desc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_pad_desc :header-rows: 0 @@ -109,7 +109,7 @@ returned during the enumeration process. .. c:type:: media_link_desc -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct media_link_desc :header-rows: 0 diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst index 8f8b3b586edd..77ea5c5e9d7f 100644 --- a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst +++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst @@ -46,7 +46,7 @@ other values untouched. If the ``topology_version`` remains the same, the ioctl should fill the desired arrays with the media graph elements. -.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3cm}| .. c:type:: media_v2_topology @@ -119,7 +119,7 @@ desired arrays with the media graph elements. converted to a 64-bits integer. It can be zero. if zero, the ioctl won't store the links. It will just update ``num_links`` -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_entity @@ -156,7 +156,7 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_interface @@ -189,7 +189,7 @@ desired arrays with the media graph elements. - Used only for device node interfaces. See :c:type:`media_v2_intf_devnode` for details. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_intf_devnode @@ -206,7 +206,7 @@ desired arrays with the media graph elements. - ``minor`` - Device node minor number. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_pad @@ -241,7 +241,7 @@ desired arrays with the media graph elements. - Reserved for future extensions. Drivers and applications must set this array to zero. -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| .. c:type:: media_v2_link diff --git a/Documentation/userspace-api/media/mediactl/media-types.rst b/Documentation/userspace-api/media/mediactl/media-types.rst index e1e4043b3b1c..0a26397bd01d 100644 --- a/Documentation/userspace-api/media/mediactl/media-types.rst +++ b/Documentation/userspace-api/media/mediactl/media-types.rst @@ -5,7 +5,7 @@ Types and flags used to represent the media graph elements ========================================================== -.. tabularcolumns:: |p{8.2cm}|p{10.3cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. _media-entity-functions: .. _MEDIA-ENT-F-UNKNOWN: @@ -251,7 +251,7 @@ Types and flags used to represent the media graph elements - The entity represents a connector. -.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}| +.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{4.8cm}| .. _media-intf-type: .. _MEDIA-INTF-T-DVB-FE: diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index aafbfda1f401..28ed94088015 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -25,7 +25,7 @@ the remote via /dev/input/event devices. .. _rc_standard_keymap: -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: IR default keymapping :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 1b0fdc160533..e991ba73d873 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -157,7 +157,7 @@ of appropriately sized buffers for each use case). struct v4l2_buffer ================== -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.4cm}|p{12.0cm}| .. cssclass:: longtable @@ -314,7 +314,7 @@ struct v4l2_buffer struct v4l2_plane ================= -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{10.3cm}| .. cssclass:: longtable @@ -389,7 +389,7 @@ enum v4l2_buf_type .. cssclass:: longtable -.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -452,16 +452,16 @@ Buffer Flags .. raw:: latex - \small + \footnotesize -.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| +.. tabularcolumns:: |p{6.5cm}|p{1.8cm}|p{9.0cm}| .. cssclass:: longtable .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 3 1 4 + :widths: 65 18 70 * .. _`V4L2-BUF-FLAG-MAPPED`: @@ -585,7 +585,7 @@ Buffer Flags - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` - 0x00000200 - - Only valid if ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is + - Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is set. It is typically used with stateless decoders where multiple output buffers each decode to a slice of the decoded frame. Applications can set this flag when queueing the output buffer @@ -681,7 +681,7 @@ Buffer Flags enum v4l2_memory ================ -.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.5cm}| .. flat-table:: :header-rows: 0 @@ -715,7 +715,7 @@ The :c:type:`v4l2_buffer_timecode` structure is designed to hold a struct v4l2_timecode -------------------- -.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| .. flat-table:: :header-rows: 0 @@ -751,8 +751,6 @@ struct v4l2_timecode Timecode Types -------------- -.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| - .. flat-table:: :header-rows: 0 :stub-columns: 0 @@ -780,7 +778,7 @@ Timecode Types Timecode Flags -------------- -.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 126f66482a0d..26a4ace42ca5 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -17,10 +17,6 @@ PAL and by SDTV in general. The default transfer function is range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 170M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -98,10 +94,6 @@ default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: Rec. 709 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -225,10 +217,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: sRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -308,9 +296,6 @@ would break how applications interpret the quantization range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: opRGB Chromaticities :header-rows: 1 :stub-columns: 0 @@ -373,10 +358,6 @@ definition television (UHDTV). The default transfer function is ``V4L2_YCBCR_ENC_BT2020``. The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: BT.2020 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -478,9 +459,6 @@ is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: DCI-P3 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -532,9 +510,6 @@ quantization is limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: SMPTE 240M Chromaticities :header-rows: 1 :stub-columns: 0 @@ -603,9 +578,6 @@ limited range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: NTSC 1953 Chromaticities :header-rows: 1 :stub-columns: 0 @@ -683,9 +655,6 @@ range. The chromaticities of the primary colors and the white reference are: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: EBU Tech. 3213 Chromaticities :header-rows: 1 :stub-columns: 0 diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst index 8c263c5a85d8..ea0435182e44 100644 --- a/Documentation/userspace-api/media/v4l/common.rst +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -51,6 +51,7 @@ applicable to all devices. ext-ctrls-fm-tx ext-ctrls-fm-rx ext-ctrls-detect + ext-ctrls-colorimetry fourcc format planar-apis diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index 4e5652eb6126..f8d0b923da20 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -154,10 +154,13 @@ Control IDs ``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` Enables a power line frequency filter to avoid flicker. Possible values for ``enum v4l2_power_line_frequency`` are: - ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0), - ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1), - ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and - ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3). + + ========================================== == + ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0 + ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1 + ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2 + ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3 + ========================================== == ``V4L2_CID_HUE_AUTO`` ``(boolean)`` Enables automatic hue control by the device. The effect of setting @@ -197,7 +200,7 @@ Control IDs -.. tabularcolumns:: |p{5.5cm}|p{12cm}| +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-meta.rst b/Documentation/userspace-api/media/v4l/dev-meta.rst index 8ec3a73dcae4..0e7e1ee1471a 100644 --- a/Documentation/userspace-api/media/v4l/dev-meta.rst +++ b/Documentation/userspace-api/media/v4l/dev-meta.rst @@ -49,7 +49,7 @@ to 0. .. c:type:: v4l2_meta_format -.. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}| +.. tabularcolumns:: |p{1.4cm}|p{2.4cm}|p{13.5cm}| .. flat-table:: struct v4l2_meta_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-overlay.rst b/Documentation/userspace-api/media/v4l/dev-overlay.rst index 07cc92564c16..4f4b23b95b9b 100644 --- a/Documentation/userspace-api/media/v4l/dev-overlay.rst +++ b/Documentation/userspace-api/media/v4l/dev-overlay.rst @@ -37,6 +37,10 @@ capturing and overlay. Optionally these drivers may also permit capturing and overlay with a single file descriptor for compatibility with V4L and earlier versions of V4L2. [#f1]_ +A common application of two file descriptors is the X11 +:ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. +While the X server controls video overlay, the application can take +advantage of memory mapping and DMA. Querying Capabilities ===================== @@ -289,11 +293,6 @@ To start or stop the frame buffer overlay applications call the :ref:`VIDIOC_OVERLAY` ioctl. .. [#f1] - A common application of two file descriptors is the XFree86 - :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application. - While the X server controls video overlay, the application can take - advantage of memory mapping and DMA. - In the opinion of the designers of this API, no driver writer taking the efforts to support simultaneous capturing and overlay will restrict this ability by requiring a single file descriptor, as in diff --git a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst index 3f43a01ba938..58f97c3a7792 100644 --- a/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst @@ -97,7 +97,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{1.6cm}|p{4.2cm}|p{11.7cm}| +.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.5cm}| .. c:type:: v4l2_vbi_format @@ -180,7 +180,7 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does - This array is reserved for future extensions. Drivers and applications must set it to zero. -.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.6cm}| +.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.4cm}| .. _vbifmt-flags: diff --git a/Documentation/userspace-api/media/v4l/dev-rds.rst b/Documentation/userspace-api/media/v4l/dev-rds.rst index 207216d5e6a5..b1dadc24561f 100644 --- a/Documentation/userspace-api/media/v4l/dev-rds.rst +++ b/Documentation/userspace-api/media/v4l/dev-rds.rst @@ -91,8 +91,6 @@ RDS datastructures .. c:type:: v4l2_rds_data -.. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| - .. flat-table:: struct v4l2_rds_data :header-rows: 0 :stub-columns: 0 @@ -133,7 +131,7 @@ RDS datastructures .. _v4l2-rds-block-codes: -.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}| .. flat-table:: Block defines :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst index 80b25a7e8017..928884dfe09d 100644 --- a/Documentation/userspace-api/media/v4l/dev-sdr.rst +++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst @@ -80,7 +80,7 @@ data transfer, set by the driver in order to inform application. .. c:type:: v4l2_sdr_format -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_sdr_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index f0df144c9f63..97ec2b115c71 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -108,7 +108,7 @@ struct v4l2_sliced_vbi_format \scriptsize \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.4cm}|p{4.4cm}|p{4.4cm}| +.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.45cm}|p{4.45cm}|p{4.45cm}| .. cssclass:: longtable @@ -213,9 +213,9 @@ Sliced VBI services .. raw:: latex - \scriptsize + \footnotesize -.. tabularcolumns:: |p{4.1cm}|p{1.1cm}|p{2.4cm}|p{2.0cm}|p{7.3cm}| +.. tabularcolumns:: |p{4.2cm}|p{1.1cm}|p{2.1cm}|p{2.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 1 @@ -253,13 +253,7 @@ Sliced VBI services :ref:`en300294` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -282,6 +276,21 @@ format while i/o is in progress (between a :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first :c:func:`read()` or :c:func:`write()` call). +.. _v4l2-sliced-wss-625-payload: + +V4L2_SLICED_WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + Reading and writing sliced VBI data =================================== @@ -298,7 +307,7 @@ struct :c:type:`v4l2_sliced_vbi_data` elements must be zero. struct v4l2_sliced_vbi_data --------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{2.2cm}|p{13.9cm}| .. flat-table:: :header-rows: 0 @@ -455,7 +464,7 @@ number). struct v4l2_mpeg_vbi_fmt_ivtv ----------------------------- -.. tabularcolumns:: |p{1.0cm}|p{3.8cm}|p{1.0cm}|p{11.2cm}| +.. tabularcolumns:: |p{4.2cm}|p{2.0cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 @@ -490,7 +499,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field ------------------------------------------------------------- -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 @@ -519,7 +528,11 @@ Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 ------------------------------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{4.6cm}|p{2.0cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -560,13 +573,16 @@ structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 one line of unspecified data that should be ignored by applications. +.. raw:: latex + + \normalsize .. _v4l2-mpeg-vbi-itv0-1: struct v4l2_mpeg_vbi_ITV0 ------------------------- -.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.9cm}| +.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.7cm}| .. flat-table:: :header-rows: 0 @@ -587,7 +603,7 @@ struct v4l2_mpeg_vbi_ITV0 struct v4l2_mpeg_vbi_itv0_line ------------------------------ -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -609,7 +625,7 @@ struct v4l2_mpeg_vbi_itv0_line Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field ------------------------------------------------------------ -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.5cm}| .. flat-table:: :header-rows: 1 diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst index 2aa8157efae1..fd1de0a73a9f 100644 --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst @@ -209,9 +209,11 @@ list entity names and pad numbers). .. raw:: latex + \begingroup \scriptsize + \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}| +.. tabularcolumns:: |p{2.0cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}| .. _sample-pipeline-config: @@ -298,7 +300,7 @@ list entity names and pad numbers). .. raw:: latex - \normalsize + \endgroup 1. Initial state. The sensor source pad format is set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the diff --git a/Documentation/userspace-api/media/v4l/diff-v4l.rst b/Documentation/userspace-api/media/v4l/diff-v4l.rst index caa05fbbd396..33243ecb5033 100644 --- a/Documentation/userspace-api/media/v4l/diff-v4l.rst +++ b/Documentation/userspace-api/media/v4l/diff-v4l.rst @@ -72,7 +72,11 @@ and radio devices supporting a set of related functions like video capturing, video overlay and VBI capturing. See :ref:`open` for an introduction. -.. tabularcolumns:: |p{5.5cm}|p{6.5cm}|p{5.5cm} +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}| .. cssclass:: longtable @@ -148,6 +152,10 @@ introduction. - ``-`` - See above. +.. raw:: latex + + \normalsize + The ``audios`` field was replaced by ``capabilities`` flag ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or outputs. To determine their number applications can enumerate audio diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst index c05a2d2c675d..4c5061aa9cd4 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst @@ -32,6 +32,7 @@ enum v4l2_exposure_auto_type - should ignore such requests. Possible values are: +.. tabularcolumns:: |p{7.1cm}|p{10.4cm}| .. flat-table:: :header-rows: 0 @@ -81,7 +82,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.7cm}|p{8.8cm}| +.. tabularcolumns:: |p{8.7cm}|p{8.7cm}| .. flat-table:: :header-rows: 0 @@ -173,7 +174,7 @@ enum v4l2_exposure_metering - control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS`` control value. -.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| .. flat-table:: :header-rows: 0 @@ -199,7 +200,7 @@ enum v4l2_exposure_metering - enum v4l2_auto_focus_range - Determines auto focus distance range for which lens may be adjusted. -.. tabularcolumns:: |p{6.8cm}|p{10.7cm}| +.. tabularcolumns:: |p{6.9cm}|p{10.6cm}| .. flat-table:: :header-rows: 0 @@ -274,7 +275,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.2 cm}|p{10.3cm}| +.. tabularcolumns:: |p{7.4cm}|p{10.1cm}| .. flat-table:: :header-rows: 0 @@ -384,7 +385,9 @@ enum v4l2_scene_mode - \small -.. tabularcolumns:: |p{5.9cm}|p{11.5cm}| +.. tabularcolumns:: |p{5.9cm}|p{11.6cm}| + +.. cssclass:: longtable .. flat-table:: :header-rows: 0 @@ -519,6 +522,7 @@ enum v4l2_scene_mode - have the ``V4L2_CAMERA_ORIENTATION_EXTERNAL`` orientation. +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index 01e3b1a3fb99..3fc04daa9ffb 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -34,7 +34,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_sps -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| .. flat-table:: struct v4l2_ctrl_h264_sps :header-rows: 0 @@ -96,6 +100,10 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>` +.. raw:: latex + + \normalsize + .. _h264_sps_constraints_set_flags: ``Sequence Parameter Set Constraints Set Flags`` @@ -171,7 +179,9 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_pps -.. cssclass:: longtable +.. raw:: latex + + \small .. flat-table:: struct v4l2_ctrl_h264_pps :header-rows: 0 @@ -212,43 +222,57 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Picture Parameter Set Flags <h264_pps_flags>` +.. raw:: latex + + \normalsize + .. _h264_pps_flags: ``Picture Parameter Set Flags`` -.. cssclass:: longtable +.. raw:: latex + + \begingroup + \scriptsize + \setlength{\tabcolsep}{2pt} + +.. tabularcolumns:: |p{9.8cm}|p{1.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 1 1 2 + :widths: 10 1 4 * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` - - 0x00000001 + - 0x0001 - * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` - - 0x00000002 + - 0x0002 - * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` - - 0x00000004 + - 0x0004 - * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` - - 0x00000008 + - 0x0008 - * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` - - 0x00000010 + - 0x0010 - * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` - - 0x00000020 + - 0x0020 - * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` - - 0x00000040 + - 0x0040 - * - ``V4L2_H264_PPS_FLAG_SCALING_MATRIX_PRESENT`` - - 0x00000080 - - Indicates that ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` + - 0x0080 + - ``V4L2_CID_STATELESS_H264_SCALING_MATRIX`` must be used for this picture. +.. raw:: latex + + \endgroup + ``V4L2_CID_STATELESS_H264_SCALING_MATRIX (struct)`` Specifies the scaling matrix (as extracted from the bitstream) for the associated H264 slice data. The bitstream parameters are @@ -259,7 +283,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_scaling_matrix -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.6cm}|p{4.8cm}|p{11.9cm}| .. flat-table:: struct v4l2_ctrl_h264_scaling_matrix :header-rows: 0 @@ -290,7 +318,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_slice_params -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| .. flat-table:: struct v4l2_ctrl_h264_slice_params :header-rows: 0 @@ -333,11 +365,11 @@ Stateless Codec Control ID * - __u8 - ``num_ref_idx_l0_active_minus1`` - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l0_default_active_minus1. + set to the value of num_ref_idx_l0_default_active_minus1 * - __u8 - ``num_ref_idx_l1_active_minus1`` - If num_ref_idx_active_override_flag is not set, this field must be - set to the value of num_ref_idx_l1_default_active_minus1. + set to the value of num_ref_idx_l1_default_active_minus1 * - __u8 - ``reserved`` - Applications and drivers must set this to zero. @@ -351,6 +383,10 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Slice Parameter Flags <h264_slice_flags>` +.. raw:: latex + + \normalsize + .. _h264_slice_flags: ``Slice Parameter Set Flags`` @@ -378,7 +414,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_pred_weights -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.9cm}|p{4.9cm}|p{7.5cm}| .. flat-table:: struct v4l2_ctrl_h264_pred_weights :header-rows: 0 @@ -396,9 +436,17 @@ Stateless Codec Control ID - The weight factors at index 0 are the weight factors for the reference list 0, the one at index 1 for the reference list 1. +.. raw:: latex + + \normalsize + .. c:type:: v4l2_h264_weight_factors -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.5cm}|p{11.8cm}| .. flat-table:: struct v4l2_h264_weight_factors :header-rows: 0 @@ -418,6 +466,10 @@ Stateless Codec Control ID - ``chroma_offset[32][2]`` - +.. raw:: latex + + \normalsize + ``Picture Reference`` .. c:type:: v4l2_h264_reference @@ -440,7 +492,11 @@ Stateless Codec Control ID ``Reference Fields`` -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.4cm}|p{0.8cm}|p{11.1cm}| .. flat-table:: :header-rows: 0 @@ -458,6 +514,10 @@ Stateless Codec Control ID - The frame (or the top/bottom fields, if it's a field pair) is used for short-term reference. +.. raw:: latex + + \normalsize + ``V4L2_CID_STATELESS_H264_DECODE_PARAMS (struct)`` Specifies the decode parameters (as extracted from the bitstream) for the associated H264 slice data. This includes the necessary @@ -469,7 +529,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_h264_decode_params -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}| .. flat-table:: struct v4l2_ctrl_h264_decode_params :header-rows: 0 @@ -524,11 +588,19 @@ Stateless Codec Control ID - ``flags`` - See :ref:`Decode Parameters Flags <h264_decode_params_flags>` +.. raw:: latex + + \normalsize + .. _h264_decode_params_flags: ``Decode Parameters Flags`` -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{8.3cm}|p{2.1cm}|p{6.9cm}| .. flat-table:: :header-rows: 0 @@ -545,9 +617,17 @@ Stateless Codec Control ID - 0x00000004 - +.. raw:: latex + + \normalsize + .. c:type:: v4l2_h264_dpb_entry -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.9cm}|p{11.4cm}| .. flat-table:: struct v4l2_h264_dpb_entry :header-rows: 0 @@ -583,11 +663,19 @@ Stateless Codec Control ID - ``flags`` - See :ref:`DPB Entry Flags <h264_dpb_flags>` +.. raw:: latex + + \normalsize + .. _h264_dpb_flags: ``DPB Entries Flags`` -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.7cm}|p{2.1cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 @@ -607,6 +695,10 @@ Stateless Codec Control ID - 0x00000008 - The DPB entry is a single field or a complementary field pair. +.. raw:: latex + + \normalsize + ``V4L2_CID_STATELESS_H264_DECODE_MODE (enum)`` Specifies the decoding mode to use. Currently exposes slice-based and frame-based decoding but new modes might be added later on. @@ -619,7 +711,11 @@ Stateless Codec Control ID .. c:type:: v4l2_stateless_h264_decode_mode -.. cssclass:: longtable +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}| .. flat-table:: :header-rows: 0 @@ -644,6 +740,10 @@ Stateless Codec Control ID selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS`` control shall not be set. +.. raw:: latex + + \normalsize + ``V4L2_CID_STATELESS_H264_START_CODE (enum)`` Specifies the H264 slice start code expected for each slice. This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE @@ -655,23 +755,32 @@ Stateless Codec Control ID .. c:type:: v4l2_stateless_h264_start_code -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.9cm}|p{0.4cm}|p{9.0cm}| .. flat-table:: :header-rows: 0 :stub-columns: 0 - :widths: 1 1 2 + :widths: 4 1 4 * - ``V4L2_STATELESS_H264_START_CODE_NONE`` - 0 - Selecting this value specifies that H264 slices are passed - to the driver without any start code. + to the driver without any start code. The bitstream data should be + according to :ref:`h264` 7.3.1 NAL unit syntax, hence contains + emulation prevention bytes when required. * - ``V4L2_STATELESS_H264_START_CODE_ANNEX_B`` - 1 - Selecting this value specifies that H264 slices are expected to be prefixed by Annex B start codes. According to :ref:`h264` valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. +.. raw:: latex + + \normalsize .. _codec-stateless-fwht: @@ -683,9 +792,11 @@ Stateless Codec Control ID .. c:type:: v4l2_ctrl_fwht_params -.. cssclass:: longtable +.. raw:: latex + + \small -.. tabularcolumns:: |p{1.4cm}|p{4.3cm}|p{11.8cm}| +.. tabularcolumns:: |p{1.4cm}|p{3.9cm}|p{12.0cm}| .. flat-table:: struct v4l2_ctrl_fwht_params :header-rows: 0 @@ -724,16 +835,20 @@ Stateless Codec Control ID - ``quantization`` - The quantization range, from enum :c:type:`v4l2_quantization`. +.. raw:: latex + \normalsize .. _fwht-flags: FWHT Flags ========== -.. cssclass:: longtable +.. raw:: latex -.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.3cm}| + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.3cm}|p{8.0cm}| .. flat-table:: :header-rows: 0 @@ -778,7 +893,7 @@ FWHT Flags - Set if this is an I-frame. * - ``V4L2_FWHT_FL_COMPONENTS_NUM_MSK`` - 0x00070000 - - The number of color components - 1. + - The number of color components minus one. * - ``V4L2_FWHT_FL_PIXENC_MSK`` - 0x00180000 - The mask for the pixel encoding. @@ -791,3 +906,341 @@ FWHT Flags * - ``V4L2_FWHT_FL_PIXENC_HSV`` - 0x00180000 - Set if the pixel encoding is HSV. + +.. raw:: latex + + \normalsize + +.. _v4l2-codec-stateless-vp8: + +``V4L2_CID_STATELESS_VP8_FRAME (struct)`` + Specifies the frame parameters for the associated VP8 parsed frame data. + This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for VP8. + The bitstream parameters are defined according to :ref:`vp8`. + +.. c:type:: v4l2_ctrl_vp8_frame + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{4.6cm}|p{5.7cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_vp8_frame + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_vp8_segment` + - ``segment`` + - Structure with segment-based adjustments metadata. + * - struct :c:type:`v4l2_vp8_loop_filter` + - ``lf`` + - Structure with loop filter level adjustments metadata. + * - struct :c:type:`v4l2_vp8_quantization` + - ``quant`` + - Structure with VP8 dequantization indices metadata. + * - struct :c:type:`v4l2_vp8_entropy` + - ``entropy`` + - Structure with VP8 entropy coder probabilities metadata. + * - struct :c:type:`v4l2_vp8_entropy_coder_state` + - ``coder_state`` + - Structure with VP8 entropy coder state. + * - __u16 + - ``width`` + - The width of the frame. Must be set for all frames. + * - __u16 + - ``height`` + - The height of the frame. Must be set for all frames. + * - __u8 + - ``horizontal_scale`` + - Horizontal scaling factor. + * - __u8 + - ``vertical_scaling factor`` + - Vertical scale. + * - __u8 + - ``version`` + - Bitstream version. + * - __u8 + - ``prob_skip_false`` + - Indicates the probability that the macroblock is not skipped. + * - __u8 + - ``prob_intra`` + - Indicates the probability that a macroblock is intra-predicted. + * - __u8 + - ``prob_last`` + - Indicates the probability that the last reference frame is used + for inter-prediction + * - __u8 + - ``prob_gf`` + - Indicates the probability that the golden reference frame is used + for inter-prediction + * - __u8 + - ``num_dct_parts`` + - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. + * - __u32 + - ``first_part_size`` + - Size of the first partition, i.e. the control partition. + * - __u32 + - ``first_part_header_bits`` + - Size in bits of the first partition header portion. + * - __u32 + - ``dct_part_sizes[8]`` + - DCT coefficients sizes. + * - __u64 + - ``last_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-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. + * - __u64 + - ``golden_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as last reference frame, used + with inter-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. + * - __u64 + - ``alt_frame_ts`` + - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used + with inter-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. + * - __u64 + - ``flags`` + - See :ref:`Frame Flags <vp8_frame_flags>` + +.. raw:: latex + + \normalsize + +.. _vp8_frame_flags: + +``Frame Flags`` + +.. tabularcolumns:: |p{9.8cm}|p{0.8cm}|p{6.7cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_FRAME_FLAG_KEY_FRAME`` + - 0x01 + - Indicates if the frame is a key frame. + * - ``V4L2_VP8_FRAME_FLAG_EXPERIMENTAL`` + - 0x02 + - Experimental bitstream. + * - ``V4L2_VP8_FRAME_FLAG_SHOW_FRAME`` + - 0x04 + - Show frame flag, indicates if the frame is for display. + * - ``V4L2_VP8_FRAME_FLAG_MB_NO_SKIP_COEFF`` + - 0x08 + - Enable/disable skipping of macroblocks with no non-zero coefficients. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_GOLDEN`` + - 0x10 + - Sign of motion vectors when the golden frame is referenced. + * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_ALT`` + - 0x20 + - Sign of motion vectors when the alt frame is referenced. + +.. c:type:: v4l2_vp8_entropy_coder_state + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| + +.. flat-table:: struct v4l2_vp8_entropy_coder_state + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``range`` + - coder state value for "Range" + * - __u8 + - ``value`` + - coder state value for "Value"- + * - __u8 + - ``bit_count`` + - number of bits left. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_segment + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.2cm}|p{4.0cm}|p{12.1cm}| + +.. flat-table:: struct v4l2_vp8_segment + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``quant_update[4]`` + - Signed quantizer value update. + * - __s8 + - ``lf_update[4]`` + - Signed loop filter level value update. + * - __u8 + - ``segment_probs[3]`` + - Segment probabilities. + * - __u8 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Segment Flags <vp8_segment_flags>` + +.. _vp8_segment_flags: + +``Segment Flags`` + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{10cm}|p{1.0cm}|p{6.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_SEGMENT_FLAG_ENABLED`` + - 0x01 + - Enable/disable segment-based adjustments. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_MAP`` + - 0x02 + - Indicates if the macroblock segmentation map is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_FEATURE_DATA`` + - 0x04 + - Indicates if the segment feature data is updated in this frame. + * - ``V4L2_VP8_SEGMENT_FLAG_DELTA_VALUE_MODE`` + - 0x08 + - If is set, the segment feature data mode is delta-value. + If cleared, it's absolute-value. + +.. raw:: latex + + \normalsize + +.. c:type:: v4l2_vp8_loop_filter + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{3.9cm}|p{11.9cm}| + +.. flat-table:: struct v4l2_vp8_loop_filter + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s8 + - ``ref_frm_delta[4]`` + - Reference adjustment (signed) delta value. + * - __s8 + - ``mb_mode_delta[4]`` + - Macroblock prediction mode adjustment (signed) delta value. + * - __u8 + - ``sharpness_level`` + - Sharpness level + * - __u8 + - ``level`` + - Filter level + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + * - __u32 + - ``flags`` + - See :ref:`Loop Filter Flags <vp8_loop_filter_flags>` + +.. _vp8_loop_filter_flags: + +``Loop Filter Flags`` + +.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_VP8_LF_ADJ_ENABLE`` + - 0x01 + - Enable/disable macroblock-level loop filter adjustment. + * - ``V4L2_VP8_LF_DELTA_UPDATE`` + - 0x02 + - Indicates if the delta values used in an adjustment are updated. + * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` + - 0x04 + - If set, indicates the filter type is simple. + If cleared, the filter type is normal. + +.. c:type:: v4l2_vp8_quantization + +.. tabularcolumns:: |p{1.5cm}|p{3.5cm}|p{12.3cm}| + +.. flat-table:: struct v4l2_vp8_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``y_ac_qi`` + - Luma AC coefficient table index. + * - __s8 + - ``y_dc_delta`` + - Luma DC delta vaue. + * - __s8 + - ``y2_dc_delta`` + - Y2 block DC delta value. + * - __s8 + - ``y2_ac_delta`` + - Y2 block AC delta value. + * - __s8 + - ``uv_dc_delta`` + - Chroma DC delta value. + * - __s8 + - ``uv_ac_delta`` + - Chroma AC delta value. + * - __u16 + - ``padding`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_vp8_entropy + +.. cssclass:: longtable + +.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}| + +.. flat-table:: struct v4l2_vp8_entropy + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``coeff_probs[4][8][3][11]`` + - Coefficient update probabilities. + * - __u8 + - ``y_mode_probs[4]`` + - Luma mode update probabilities. + * - __u8 + - ``uv_mode_probs[3]`` + - Chroma mode update probabilities. + * - __u8 + - ``mv_probs[2][19]`` + - MV decoding update probabilities. + * - __u8 + - ``padding[3]`` + - Applications and drivers must set this to zero. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 00944e97d638..b0de4e6e7ebd 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -392,7 +392,7 @@ enum v4l2_mpeg_audio_mode_extension - which subbands are in intensity stereo. All other subbands are coded in stereo. Layer III is not (yet) supported. Possible values are: - +.. tabularcolumns:: |p{9.1cm}|p{8.4cm}| .. flat-table:: :header-rows: 0 @@ -580,7 +580,7 @@ enum v4l2_mpeg_video_bitrate_mode - ``V4L2_CID_MPEG_VIDEO_BITRATE (integer)`` - Video bitrate in bits per second. + Average video bitrate in bits per second. ``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)`` Peak video bitrate in bits per second. Must be larger or equal to @@ -605,7 +605,7 @@ enum v4l2_mpeg_video_frame_skip_mode - are: -.. tabularcolumns:: |p{9.2cm}|p{8.3cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. raw:: latex @@ -615,12 +615,12 @@ enum v4l2_mpeg_video_frame_skip_mode - :header-rows: 0 :stub-columns: 0 - * - ``V4L2_MPEG_FRAME_SKIP_MODE_DISABLED`` + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_DISABLED`` - Frame skip mode is disabled. - * - ``V4L2_MPEG_FRAME_SKIP_MODE_LEVEL_LIMIT`` + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` - Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard. - * - ``V4L2_MPEG_FRAME_SKIP_MODE_BUF_LIMIT`` + * - ``V4L2_MPEG_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` - Frame skip mode enabled and buffer limit is set by the :ref:`VBV (MPEG1/2/4) <v4l2-mpeg-video-vbv-size>` or :ref:`CPB (H264) buffer size <v4l2-mpeg-video-h264-cpb-size>` control. @@ -674,11 +674,64 @@ enum v4l2_mpeg_video_frame_skip_mode - is currently displayed (decoded). This value is reset to 0 whenever the decoder is started. +``V4L2_CID_MPEG_VIDEO_DEC_CONCEAL_COLOR (integer64)`` + This control sets the conceal color in YUV color space. It describes + the client preference of the error conceal color in case of an error + where the reference frame is missing. The decoder should fill the + reference buffer with the preferred color and use it for future + decoding. The control is using 16 bits per channel. + Applicable to decoders. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - + - 8bit format + - 10bit format + - 12bit format + * - Y luminance + - Bit 0:7 + - Bit 0:9 + - Bit 0:11 + * - Cb chrominance + - Bit 16:23 + - Bit 16:25 + - Bit 16:27 + * - Cr chrominance + - Bit 32:39 + - Bit 32:41 + - Bit 32:43 + * - Must be zero + - Bit 48:63 + - Bit 48:63 + - Bit 48:63 + ``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)`` If enabled the decoder expects to receive a single slice per buffer, otherwise the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs. +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE (boolean)`` + If the display delay is enabled then the decoder is forced to return + a CAPTURE buffer (decoded frame) after processing a certain number + of OUTPUT buffers. The delay can be set through + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY``. This + feature can be used for example for generating thumbnails of videos. + Applicable to the decoder. + +``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY (integer)`` + Display delay value for decoder. The decoder is forced to + return a decoded frame after the set 'display delay' number of + frames. If this number is low it may result in frames returned out + of display order, in addition the hardware may still be using the + returned buffer as a reference picture for subsequent frames. + +``V4L2_CID_MPEG_VIDEO_AU_DELIMITER (boolean)`` + If enabled then, AUD (Access Unit Delimiter) NALUs will be generated. + That could be useful to find the start of a frame without having to + fully parse each NALU. Applicable to the H264 and HEVC encoders. + ``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)`` Enable writing sample aspect ratio in the Video Usability Information. Applicable to the H264 encoder. @@ -873,7 +926,11 @@ enum v4l2_mpeg_video_h264_profile - The profile information for H264. Applicable to the H264 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -916,7 +973,9 @@ enum v4l2_mpeg_video_h264_profile - * - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_HIGH`` - Constrained High profile +.. raw:: latex + \normalsize .. _v4l2-mpeg-video-mpeg2-profile: @@ -927,7 +986,11 @@ enum v4l2_mpeg_video_mpeg2_profile - The profile information for MPEG2. Applicable to MPEG2 codecs. Possible values are: +.. raw:: latex + \small + +.. tabularcolumns:: |p{10.2cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -947,6 +1010,9 @@ enum v4l2_mpeg_video_mpeg2_profile - - Multi-view profile (MVP) +.. raw:: latex + + \normalsize .. _v4l2-mpeg-video-mpeg4-profile: @@ -957,7 +1023,11 @@ enum v4l2_mpeg_video_mpeg4_profile - The profile information for MPEG4. Applicable to the MPEG4 encoder. Possible values are: +.. raw:: latex + + \small +.. tabularcolumns:: |p{11.8cm}|p{5.7cm}| .. flat-table:: :header-rows: 0 @@ -972,9 +1042,11 @@ enum v4l2_mpeg_video_mpeg4_profile - * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_SIMPLE_SCALABLE`` - Simple Scalable profile * - ``V4L2_MPEG_VIDEO_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY`` - - + - Advanced Coding Efficiency profile +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)`` The maximum number of reference pictures used for encoding. @@ -1030,7 +1102,7 @@ enum v4l2_mpeg_video_h264_loop_filter_mode - \small -.. tabularcolumns:: |p{13.6cm}|p{3.9cm}| +.. tabularcolumns:: |p{13.5cm}|p{4.0cm}| .. flat-table:: :header-rows: 0 @@ -1425,7 +1497,7 @@ enum v4l2_mpeg_video_h264_fmo_change_dir - Specifies a direction of the slice group change for raster and wipe maps. Applicable to the H264 encoder. Possible values are: - +.. tabularcolumns:: |p{9.6cm}|p{7.9cm}| .. flat-table:: :header-rows: 0 @@ -1549,9 +1621,9 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. c:type:: v4l2_ctrl_mpeg2_slice_params -.. cssclass:: longtable +.. tabularcolumns:: |p{5.6cm}|p{4.6cm}|p{7.1cm}| -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| +.. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_mpeg2_slice_params :header-rows: 0 @@ -1594,7 +1666,7 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. cssclass:: longtable -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| +.. tabularcolumns:: |p{1.4cm}|p{6.5cm}|p{9.4cm}| .. flat-table:: struct v4l2_mpeg2_sequence :header-rows: 0 @@ -1625,9 +1697,13 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. c:type:: v4l2_mpeg2_picture +.. raw:: latex + + \small + .. cssclass:: longtable -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| +.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}| .. flat-table:: struct v4l2_mpeg2_picture :header-rows: 0 @@ -1675,6 +1751,10 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - ``progressive_frame`` - Indicates whether the current frame is progressive. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)`` Specifies quantization matrices (as extracted from the bitstream) for the associated MPEG-2 slice data. @@ -1686,9 +1766,9 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - .. c:type:: v4l2_ctrl_mpeg2_quantization -.. cssclass:: longtable +.. tabularcolumns:: |p{0.8cm}|p{8.0cm}|p{8.5cm}| -.. tabularcolumns:: |p{1.2cm}|p{8.0cm}|p{7.4cm}| +.. cssclass:: longtable .. raw:: latex @@ -1739,6 +1819,10 @@ 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. +.. raw:: latex + + \normalsize + ``V4L2_CID_FWHT_I_FRAME_QP (integer)`` Quantization parameter for an I frame for FWHT. Valid range: from 1 to 31. @@ -1747,329 +1831,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - Quantization parameter for a P frame for FWHT. Valid range: from 1 to 31. -.. _v4l2-mpeg-vp8: - -``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER (struct)`` - Specifies the frame parameters for the associated VP8 parsed frame data. - This includes the necessary parameters for - configuring a stateless hardware decoding pipeline for VP8. - The bitstream parameters are defined according to :ref:`vp8`. - - .. note:: - - This compound control is not yet part of the public kernel API and - it is expected to change. - -.. c:type:: v4l2_ctrl_vp8_frame_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{5.8cm}|p{4.8cm}|p{6.6cm}| - -.. flat-table:: struct v4l2_ctrl_vp8_frame_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`v4l2_vp8_segment_header` - - ``segment_header`` - - Structure with segment-based adjustments metadata. - * - struct :c:type:`v4l2_vp8_loopfilter_header` - - ``loopfilter_header`` - - Structure with loop filter level adjustments metadata. - * - struct :c:type:`v4l2_vp8_quantization_header` - - ``quant_header`` - - Structure with VP8 dequantization indices metadata. - * - struct :c:type:`v4l2_vp8_entropy_header` - - ``entropy_header`` - - Structure with VP8 entropy coder probabilities metadata. - * - struct :c:type:`v4l2_vp8_entropy_coder_state` - - ``coder_state`` - - Structure with VP8 entropy coder state. - * - __u16 - - ``width`` - - The width of the frame. Must be set for all frames. - * - __u16 - - ``height`` - - The height of the frame. Must be set for all frames. - * - __u8 - - ``horizontal_scale`` - - Horizontal scaling factor. - * - __u8 - - ``vertical_scaling factor`` - - Vertical scale. - * - __u8 - - ``version`` - - Bitstream version. - * - __u8 - - ``prob_skip_false`` - - Indicates the probability that the macroblock is not skipped. - * - __u8 - - ``prob_intra`` - - Indicates the probability that a macroblock is intra-predicted. - * - __u8 - - ``prob_last`` - - Indicates the probability that the last reference frame is used - for inter-prediction - * - __u8 - - ``prob_gf`` - - Indicates the probability that the golden reference frame is used - for inter-prediction - * - __u8 - - ``num_dct_parts`` - - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8. - * - __u32 - - ``first_part_size`` - - Size of the first partition, i.e. the control partition. - * - __u32 - - ``first_part_header_bits`` - - Size in bits of the first partition header portion. - * - __u32 - - ``dct_part_sizes[8]`` - - DCT coefficients sizes. - * - __u64 - - ``last_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-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. - * - __u64 - - ``golden_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as last reference frame, used - with inter-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. - * - __u64 - - ``alt_frame_ts`` - - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used - with inter-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. - * - __u64 - - ``flags`` - - See :ref:`Frame Header Flags <vp8_frame_header_flags>` - -.. _vp8_frame_header_flags: - -``Frame Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_FRAME_HEADER_FLAG_KEY_FRAME`` - - 0x01 - - Indicates if the frame is a key frame. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_EXPERIMENTAL`` - - 0x02 - - Experimental bitstream. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SHOW_FRAME`` - - 0x04 - - Show frame flag, indicates if the frame is for display. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_MB_NO_SKIP_COEFF`` - - 0x08 - - Enable/disable skipping of macroblocks with no non-zero coefficients. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_GOLDEN`` - - 0x10 - - Sign of motion vectors when the golden frame is referenced. - * - ``V4L2_VP8_FRAME_HEADER_FLAG_SIGN_BIAS_ALT`` - - 0x20 - - Sign of motion vectors when the alt frame is referenced. - -.. c:type:: v4l2_vp8_entropy_coder_state - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_coder_state - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``range`` - - - * - __u8 - - ``value`` - - - * - __u8 - - ``bit_count`` - - - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_segment_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_segment_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``quant_update[4]`` - - Signed quantizer value update. - * - __s8 - - ``lf_update[4]`` - - Signed loop filter level value update. - * - __u8 - - ``segment_probs[3]`` - - Segment probabilities. - * - __u8 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Segment Header Flags <vp8_segment_header_flags>` - -.. _vp8_segment_header_flags: - -``Segment Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_ENABLED`` - - 0x01 - - Enable/disable segment-based adjustments. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_MAP`` - - 0x02 - - Indicates if the macroblock segmentation map is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_UPDATE_FEATURE_DATA`` - - 0x04 - - Indicates if the segment feature data is updated in this frame. - * - ``V4L2_VP8_SEGMENT_HEADER_FLAG_DELTA_VALUE_MODE`` - - 0x08 - - If is set, the segment feature data mode is delta-value. - If cleared, it's absolute-value. - -.. c:type:: v4l2_vp8_loopfilter_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_loopfilter_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __s8 - - ``ref_frm_delta[4]`` - - Reference adjustment (signed) delta value. - * - __s8 - - ``mb_mode_delta[4]`` - - Macroblock prediction mode adjustment (signed) delta value. - * - __u8 - - ``sharpness_level`` - - Sharpness level - * - __u8 - - ``level`` - - Filter level - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - * - __u32 - - ``flags`` - - See :ref:`Loopfilter Header Flags <vp8_loopfilter_header_flags>` - -.. _vp8_loopfilter_header_flags: - -``Loopfilter Header Flags`` - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - ``V4L2_VP8_LF_HEADER_ADJ_ENABLE`` - - 0x01 - - Enable/disable macroblock-level loop filter adjustment. - * - ``V4L2_VP8_LF_HEADER_DELTA_UPDATE`` - - 0x02 - - Indicates if the delta values used in an adjustment are updated. - * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE`` - - 0x04 - - If set, indicates the filter type is simple. - If cleared, the filter type is normal. - -.. c:type:: v4l2_vp8_quantization_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_quantization_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``y_ac_qi`` - - Luma AC coefficient table index. - * - __s8 - - ``y_dc_delta`` - - Luma DC delta vaue. - * - __s8 - - ``y2_dc_delta`` - - Y2 block DC delta value. - * - __s8 - - ``y2_ac_delta`` - - Y2 block AC delta value. - * - __s8 - - ``uv_dc_delta`` - - Chroma DC delta value. - * - __s8 - - ``uv_ac_delta`` - - Chroma AC delta value. - * - __u16 - - ``padding`` - - Applications and drivers must set this to zero. - -.. c:type:: v4l2_vp8_entropy_header - -.. cssclass:: longtable - -.. tabularcolumns:: |p{1.5cm}|p{6.3cm}|p{9.4cm}| - -.. flat-table:: struct v4l2_vp8_entropy_header - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u8 - - ``coeff_probs[4][8][3][11]`` - - Coefficient update probabilities. - * - __u8 - - ``y_mode_probs[4]`` - - Luma mode update probabilities. - * - __u8 - - ``uv_mode_probs[3]`` - - Chroma mode update probabilities. - * - __u8 - - ``mv_probs[2][19]`` - - MV decoding update probabilities. - * - __u8 - - ``padding[3]`` - - Applications and drivers must set this to zero. - .. raw:: latex \normalsize @@ -2096,6 +1857,11 @@ MFC 5.1 Control IDs feature can be used for example for generating thumbnails of videos. Applicable to the H264 decoder. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY_ENABLE`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)`` Display delay value for H264 decoder. The decoder is forced to return a decoded frame after the set 'display delay' number of @@ -2103,6 +1869,11 @@ MFC 5.1 Control IDs of display order, in addition the hardware may still be using the returned buffer as a reference picture for subsequent frames. + .. note:: + + This control is deprecated. Use the standard + ``V4L2_CID_MPEG_VIDEO_DEC_DISPLAY_DELAY`` control instead. + ``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)`` The number of reference pictures used for encoding a P picture. Applicable to the H264 encoder. @@ -2187,7 +1958,7 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - are: -.. tabularcolumns:: |p{9.2cm}|p{8.3cm}| +.. tabularcolumns:: |p{9.4cm}|p{8.1cm}| .. raw:: latex @@ -2197,12 +1968,12 @@ enum v4l2_mpeg_mfc51_video_frame_skip_mode - :header-rows: 0 :stub-columns: 0 - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_DISABLED`` - Frame skip mode is disabled. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_LEVEL_LIMIT`` - Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard. - * - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT`` + * - ``V4L2_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE_BUF_LIMIT`` - Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control. @@ -2231,7 +2002,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}| +.. tabularcolumns:: |p{9.9cm}|p{7.6cm}| .. flat-table:: :header-rows: 0 @@ -2267,6 +2038,7 @@ enum v4l2_mpeg_cx2341x_video_spatial_filter_mode - are: +.. tabularcolumns:: |p{11.5cm}|p{6.0cm}| .. flat-table:: :header-rows: 0 @@ -2292,11 +2064,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}| +.. tabularcolumns:: |p{13.1cm}|p{4.4cm}| .. raw:: latex - \small + \footnotesize .. flat-table:: :header-rows: 0 @@ -2317,8 +2089,6 @@ enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type - \normalsize - - .. _chroma-spatial-filter-type: ``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE`` @@ -2328,8 +2098,11 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - Select the algorithm for the Chroma Spatial Filter (default ``1D_HOR``). Possible values are: +.. raw:: latex -.. tabularcolumns:: |p{14.0cm}|p{3.5cm}| + \footnotesize + +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -2340,7 +2113,9 @@ enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR`` - One-dimensional horizontal +.. raw:: latex + \normalsize .. _v4l2-mpeg-cx2341x-video-temporal-filter-mode: @@ -2351,7 +2126,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - Sets the Temporal Filter mode (default ``MANUAL``). Possible values are: +.. raw:: latex + \footnotesize .. flat-table:: :header-rows: 0 @@ -2362,7 +2139,9 @@ enum v4l2_mpeg_cx2341x_video_temporal_filter_mode - * - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO`` - Choose the filter automatically +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))`` The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default @@ -2377,6 +2156,11 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - Median Filter Type (default ``OFF``). Possible values are: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{11.0cm}|p{6.5cm}| .. flat-table:: :header-rows: 0 @@ -2393,7 +2177,9 @@ enum v4l2_mpeg_cx2341x_video_median_filter_type - * - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG`` - Diagonal filter +.. raw:: latex + \normalsize ``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))`` Threshold above which the luminance median filter is enabled @@ -2470,7 +2256,7 @@ enum v4l2_vp8_num_ref_frames - The number of reference pictures for encoding P frames. Possible values are: -.. tabularcolumns:: |p{7.9cm}|p{9.6cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. raw:: latex @@ -2525,7 +2311,7 @@ enum v4l2_vp8_golden_frame_sel - \scriptsize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.6cm}|p{8.9cm}| .. flat-table:: :header-rows: 0 @@ -2735,7 +2521,7 @@ enum v4l2_mpeg_video_hevc_hier_coding_type - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 @@ -2804,7 +2590,7 @@ enum v4l2_mpeg_video_hevc_profile - \footnotesize -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{9.0cm}|p{8.5cm}| .. flat-table:: :header-rows: 0 @@ -2830,47 +2616,21 @@ enum v4l2_mpeg_video_hevc_profile - enum v4l2_mpeg_video_hevc_level - Selects the desired level for HEVC encoder. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` - - Level 1.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` - - Level 2.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` - - Level 2.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` - - Level 3.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` - - Level 3.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` - - Level 4.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` - - Level 4.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` - - Level 5.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` - - Level 5.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` - - Level 5.2 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` - - Level 6.0 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` - - Level 6.1 - * - ``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` - - Level 6.2 - -.. raw:: latex - - \normalsize - +================================== ========= +``V4L2_MPEG_VIDEO_HEVC_LEVEL_1`` Level 1.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2`` Level 2.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_2_1`` Level 2.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3`` Level 3.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_3_1`` Level 3.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4`` Level 4.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_4_1`` Level 4.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5`` Level 5.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_1`` Level 5.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_5_2`` Level 5.2 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6`` Level 6.0 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_1`` Level 6.1 +``V4L2_MPEG_VIDEO_HEVC_LEVEL_6_2`` Level 6.2 +================================== ========= ``V4L2_CID_MPEG_VIDEO_HEVC_FRAME_RATE_RESOLUTION (integer)`` Indicates the number of evenly spaced subintervals, called ticks, within @@ -2889,24 +2649,10 @@ enum v4l2_mpeg_video_hevc_tier - this flag to 1 indicates High tier. High tier is for applications requiring high bit rates. -.. raw:: latex - - \footnotesize - -.. tabularcolumns:: |p{9.0cm}|p{8.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` - - Main tier. - * - ``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` - - High tier. - -.. raw:: latex - - \normalsize +================================== ========== +``V4L2_MPEG_VIDEO_HEVC_TIER_MAIN`` Main tier. +``V4L2_MPEG_VIDEO_HEVC_TIER_HIGH`` High tier. +================================== ========== ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_PARTITION_DEPTH (integer)`` @@ -2962,7 +2708,7 @@ enum v4l2_mpeg_video_hevc_hier_refresh_type - \footnotesize -.. tabularcolumns:: |p{8.0cm}|p{9.0cm}| +.. tabularcolumns:: |p{6.2cm}|p{11.3cm}| .. flat-table:: :header-rows: 0 @@ -3042,7 +2788,7 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - \footnotesize -.. tabularcolumns:: |p{6.0cm}|p{11.0cm}| +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| .. flat-table:: :header-rows: 0 @@ -3102,6 +2848,12 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_ctrl_hevc_sps +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.2cm}|p{9.2cm}|p{6.9cm}| + .. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_hevc_sps @@ -3176,10 +2928,18 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``flags`` - See :ref:`Sequence Parameter Set Flags <hevc_sps_flags>` +.. raw:: latex + + \normalsize + .. _hevc_sps_flags: ``Sequence Parameter Set Flags`` +.. raw:: latex + + \small + .. cssclass:: longtable .. flat-table:: @@ -3215,6 +2975,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - 0x00000100 - +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_PPS (struct)`` Specifies the Picture Parameter Set fields (as extracted from the bitstream) for the associated HEVC slice data. @@ -3224,6 +2988,8 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_ctrl_hevc_pps +.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}| + .. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_hevc_pps @@ -3278,7 +3044,9 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - ``Picture Parameter Set Flags`` -.. cssclass:: longtable +.. raw:: latex + + \small .. flat-table:: :header-rows: 0 @@ -3343,6 +3111,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - 0x00040000 - +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS (struct)`` Specifies various slice-specific parameters, especially from the NAL unit header, general slice segment header and weighted prediction parameter @@ -3353,6 +3125,12 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_ctrl_hevc_slice_params +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}| + .. cssclass:: longtable .. flat-table:: struct v4l2_ctrl_hevc_slice_params @@ -3455,11 +3233,17 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``flags`` - See :ref:`Slice Parameters Flags <hevc_slice_params_flags>` +.. raw:: latex + + \normalsize + .. _hevc_slice_params_flags: ``Slice Parameters Flags`` -.. cssclass:: longtable +.. raw:: latex + + \scriptsize .. flat-table:: :header-rows: 0 @@ -3494,9 +3278,17 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - 0x00000100 - +.. raw:: latex + + \normalsize + .. c:type:: v4l2_hevc_dpb_entry -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{12.1cm}| .. flat-table:: struct v4l2_hevc_dpb_entry :header-rows: 0 @@ -3528,9 +3320,17 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``padding[2]`` - Applications and drivers must set this to zero. +.. raw:: latex + + \normalsize + .. c:type:: v4l2_hevc_pred_weight_table -.. cssclass:: longtable +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{0.8cm}|p{10.6cm}|p{5.9cm}| .. flat-table:: struct v4l2_hevc_pred_weight_table :header-rows: 0 @@ -3571,6 +3371,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - - ``padding[6]`` - Applications and drivers must set this to zero. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE (enum)`` Specifies the decoding mode to use. Currently exposes slice-based and frame-based decoding but new modes might be added later on. @@ -3588,7 +3392,11 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_mpeg_video_hevc_decode_mode -.. cssclass:: longtable +.. raw:: latex + + \small + +.. tabularcolumns:: |p{9.4cm}|p{0.6cm}|p{7.3cm}| .. flat-table:: :header-rows: 0 @@ -3605,6 +3413,10 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - The OUTPUT buffer must contain all slices needed to decode the frame. The OUTPUT buffer must also contain both fields. +.. raw:: latex + + \normalsize + ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE (enum)`` Specifies the HEVC slice start code expected for each slice. This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE @@ -3621,7 +3433,7 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - .. c:type:: v4l2_mpeg_video_hevc_start_code -.. cssclass:: longtable +.. tabularcolumns:: |p{9.2cm}|p{0.6cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 @@ -3631,7 +3443,9 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_NONE`` - 0 - Selecting this value specifies that HEVC slices are passed - to the driver without any start code. + to the driver without any start code. The bitstream data should be + according to :ref:`hevc` 7.3.1.1 General NAL unit syntax, hence + contains emulation prevention bytes when required. * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_ANNEX_B`` - 1 - Selecting this value specifies that HEVC slices are expected @@ -3646,3 +3460,21 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - so this has to come from client. This is applicable to H264 and valid Range is from 0 to 63. Source Rec. ITU-T H.264 (06/2019); G.7.4.1.1, G.8.8.1. + +``V4L2_CID_MPEG_VIDEO_LTR_COUNT (integer)`` + Specifies the maximum number of Long Term Reference (LTR) frames at any + given time that the encoder can keep. + This is applicable to the H264 and HEVC encoders. + +``V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX (integer)`` + After setting this control the frame that will be queued next + will be marked as a Long Term Reference (LTR) frame + and given this LTR index which ranges from 0 to LTR_COUNT-1. + This is applicable to the H264 and HEVC encoders. + Source Rec. ITU-T H.264 (06/2019); Table 7.9 + +``V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES (bitmask)`` + Specifies the Long Term Reference (LTR) frame(s) to be used for + encoding the next frame queued after setting this control. + This provides a bitmask which consists of bits [0, LTR_COUNT-1]. + This is applicable to the H264 and HEVC encoders. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst new file mode 100644 index 000000000000..1e7265155715 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _colorimetry-controls: + +***************************** +Colorimetry Control Reference +***************************** + +The Colorimetry class includes controls for High Dynamic Range +imaging for representing colors in digital images and video. The +controls should be used for video and image encoding and decoding +as well as in HDMI receivers and transmitters. + +Colorimetry Control IDs +----------------------- + +.. _colorimetry-control-id: + +``V4L2_CID_COLORIMETRY_CLASS (class)`` + The Colorimetry class descriptor. Calling + :ref:`VIDIOC_QUERYCTRL` for this control will + return a description of this control class. + +``V4L2_CID_COLORIMETRY_HDR10_CLL_INFO (struct)`` + The Content Light Level defines upper bounds for the nominal target + brightness light level of the pictures. + +.. c:type:: v4l2_ctrl_hdr10_cll_info + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_cll_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``max_content_light_level`` + - The upper bound for the maximum light level among all individual + samples for the pictures of a video sequence, cd/m\ :sup:`2`. + When equal to 0 no such upper bound is present. + * - __u16 + - ``max_pic_average_light_level`` + - The upper bound for the maximum average light level among the + samples for any individual picture of a video sequence, + cd/m\ :sup:`2`. When equal to 0 no such upper bound is present. + +``V4L2_CID_COLORIMETRY_HDR10_MASTERING_DISPLAY (struct)`` + The mastering display defines the color volume (the color primaries, + white point and luminance range) of a display considered to be the + mastering display for the current video content. + +.. c:type:: v4l2_ctrl_hdr10_mastering_display + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hdr10_mastering_display + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``display_primaries_x[3]`` + - Specifies the normalized x chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to the Red color primary. + * - __u16 + - ``display_primaries_y[3]`` + - Specifies the normalized y chromaticity coordinate of the color + primary component c of the mastering display in increments of 0.00002. + For describing the mastering display that uses Red, Green and Blue + color primaries, index value c equal to 0 corresponds to the Green + primary, c equal to 1 corresponds to Blue primary and c equal to 2 + corresponds to Red color primary. + * - __u16 + - ``white_point_x`` + - Specifies the normalized x chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u16 + - ``white_point_y`` + - Specifies the normalized y chromaticity coordinate of the white + point of the mastering display in increments of 0.00002. + * - __u32 + - ``max_luminance`` + - Specifies the nominal maximum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. + * - __u32 + - ``min_luminance`` + - specifies the nominal minimum display luminance of the mastering + display in units of 0.0001 cd/m\ :sup:`2`. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst index a6f696bf89dd..d2794e03ac6d 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst @@ -99,7 +99,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.3cm}|p{10.4cm}| +.. tabularcolumns:: |p{7.3cm}|p{10.2cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst index ad4b878cd034..d22c5efb806a 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst @@ -63,6 +63,7 @@ Flash Control IDs presence of some faults. See V4L2_CID_FLASH_FAULT. +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| .. flat-table:: :header-rows: 0 @@ -73,14 +74,16 @@ Flash Control IDs * - ``V4L2_FLASH_LED_MODE_FLASH`` - Flash mode. * - ``V4L2_FLASH_LED_MODE_TORCH`` - - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. + - Torch mode. + + See V4L2_CID_FLASH_TORCH_INTENSITY. ``V4L2_CID_FLASH_STROBE_SOURCE (menu)`` Defines the source of the flash LED strobe. -.. tabularcolumns:: |p{7.5cm}|p{10.0cm}| +.. tabularcolumns:: |p{7.5cm}|p{7.5cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index e07a2dbcd65d..60f9a09422d6 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -64,13 +64,12 @@ JPEG Control IDs .. _jpeg-quality-control: ``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)`` - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off - between image quality and size. It provides simpler method for - applications to control image quality, without a need for direct - reconfiguration of luminance and chrominance quantization tables. In - cases where a driver uses quantization tables configured directly by - an application, using interfaces defined elsewhere, - ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by + Determines trade-off between image quality and size. + It provides simpler method for applications to control image quality, + without a need for direct reconfiguration of luminance and chrominance + quantization tables. In cases where a driver uses quantization tables + configured directly by an application, using interfaces defined + elsewhere, ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by driver to 0. The value range of this control is driver-specific. Only positive, diff --git a/Documentation/userspace-api/media/v4l/field-order.rst b/Documentation/userspace-api/media/v4l/field-order.rst index 54548ea4308c..9a0ed8fc550f 100644 --- a/Documentation/userspace-api/media/v4l/field-order.rst +++ b/Documentation/userspace-api/media/v4l/field-order.rst @@ -62,7 +62,7 @@ enum v4l2_field .. c:type:: v4l2_field -.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{11.1cm}| +.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{10.9cm}| .. cssclass:: longtable diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index acad5f3ca0c1..6dba70da822b 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -7,7 +7,13 @@ Compressed Formats .. _compressed-formats: -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.8cm}|p{1.2cm}|p{10.3cm}| + +.. cssclass:: longtable .. flat-table:: Compressed Image Formats :header-rows: 1 @@ -147,22 +153,17 @@ Compressed Formats - ``V4L2_PIX_FMT_VP8_FRAME`` - 'VP8F' - - VP8 parsed frame, as extracted from the container. - This format is adapted for stateless video decoders that implement a - VP8 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`). + - VP8 parsed frame, including the frame header, as extracted from the container. + This format is adapted for stateless video decoders that implement an + VP8 pipeline with the :ref:`stateless_decoder`. Metadata associated with the frame to decode is required to be passed - through the ``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER`` control. - See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`. + through the ``V4L2_CID_STATELESS_VP8_FRAME`` control. + See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-vp8>`. Exactly one output and one capture buffer must be provided for use with this pixel format. The output buffer must contain the appropriate number of macroblocks to decode a full corresponding frame to the matching capture buffer. - .. note:: - - This format is not yet part of the public kernel API and it - is expected to change. - * .. _V4L2-PIX-FMT-VP9: - ``V4L2_PIX_FMT_VP9`` @@ -220,3 +221,7 @@ Compressed Formats Metadata associated with the frame to decode is required to be passed through the ``V4L2_CID_STATELESS_FWHT_PARAMS`` control. See the :ref:`associated Codec Control ID <codec-stateless-fwht>`. + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index eb551b57557e..65520c3af7cf 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -36,10 +36,10 @@ Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes, .. raw:: latex \begingroup - \tiny + \scriptsize \setlength{\tabcolsep}{2pt} -.. 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}| +.. tabularcolumns:: |p{3.5cm}|p{0.96cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}|p{0.52cm}| .. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc) :header-rows: 2 @@ -220,6 +220,16 @@ the second byte and Y'\ :sub:`7-0` in the third byte. - Y'\ :sub:`7-0` - X\ :sub:`7-0` + * .. _V4L2-PIX-FMT-YUV24: + + - ``V4L2_PIX_FMT_YUV24`` + - 'YUV3' + + - Y'\ :sub:`7-0` + - Cb\ :sub:`7-0` + - Cr\ :sub:`7-0` + - -\ + .. note:: - The alpha component is expected to contain a meaningful value that can be @@ -234,6 +244,12 @@ the second byte and Y'\ :sub:`7-0` in the third byte. These formats, commonly referred to as YUYV or YUY2, subsample the chroma components horizontally by 2, storing 2 pixels in 4 bytes. +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{3.4cm}|p{1.2cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}| + .. flat-table:: Packed YUV 4:2:2 Formats :header-rows: 1 :stub-columns: 0 @@ -301,6 +317,10 @@ components horizontally by 2, storing 2 pixels in 4 bytes. - Y'\ :sub:`3` - Cb\ :sub:`2` +.. raw:: latex + + \normalsize + **Color Sample Location:** Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` horizontally. @@ -312,6 +332,12 @@ horizontally. This format subsamples the chroma components horizontally by 4, storing 8 pixels in 12 bytes. +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{2.9cm}|p{0.8cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}| + .. flat-table:: Packed YUV 4:1:1 Formats :header-rows: 1 :stub-columns: 0 @@ -348,11 +374,15 @@ pixels in 12 bytes. - Y'\ :sub:`6` - Y'\ :sub:`7` +.. raw:: latex + + \normalsize + .. note:: Do not confuse ``V4L2_PIX_FMT_Y41P`` with :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from - "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 *planar*". + "YUV 4:1:1 **packed**", while YUV411P stands for "YUV 4:1:1 **planar**". **Color Sample Location:** Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index c9231e18859b..0b879c0da713 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -17,7 +17,11 @@ you think your format should be listed in a standard format section please make a proposal on the linux-media mailing list. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. raw:: latex + + \small .. _reserved-formats: @@ -256,3 +260,7 @@ please make a proposal on the linux-media mailing list. of tiles, resulting in 32-aligned resolutions for the luminance plane and 16-aligned resolutions for the chrominance plane (with 2x2 subsampling). + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 897676ee2c9d..48b0f787274c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -655,12 +655,7 @@ nomenclature that instead use the order of components as seen in a 24- or .. raw:: latex - \begingroup - \tiny - \setlength{\tabcolsep}{2pt} - -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}| - + \small .. flat-table:: RGB Formats With 8 Bits Per Component :header-rows: 1 @@ -765,7 +760,7 @@ nomenclature that instead use the order of components as seen in a 24- or .. raw:: latex - \endgroup + \normalsize Deprecated RGB Formats diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst index 15f1900cd914..3322b0600f1d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst @@ -9,7 +9,9 @@ V4L2_PIX_FMT_IPU3_SBGGR10 ('ip3b'), V4L2_PIX_FMT_IPU3_SGBRG10 ('ip3g'), V4L2_PIX_FMT_IPU3_SGRBG10 ('ip3G'), V4L2_PIX_FMT_IPU3_SRGGB10 ('ip3r') ********************************************************************************************************************************************** +==================== 10-bit Bayer formats +==================== Description =========== @@ -25,7 +27,11 @@ Below is an example of a small image in V4L2_PIX_FMT_IPU3_SBGGR10 format. **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{0.8cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}|p{3.3cm}| .. flat-table:: @@ -333,3 +339,7 @@ Each cell is one byte. - R\ :sub:`0323high` - G\ :sub:`0324low` - G\ :sub:`0324high`\ (bits 1--0) + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst index dc52e827b5d3..fd5feb415531 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst @@ -33,7 +33,7 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| +.. tabularcolumns:: |p{2.4cm}|p{1.4cm}|p{1.2cm}|p{1.2cm}|p{1.2cm}|p{9.3cm}| .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index a2f8ebfceb84..b6e79e2f8ce4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -31,7 +31,7 @@ Below is an example of a small V4L2_PIX_FMT_SBGGR12P image: **Byte Order.** Each cell is one byte. -.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}| +.. tabularcolumns:: |p{2.2cm}|p{1.2cm}|p{1.2cm}|p{3.1cm}|p{1.2cm}|p{1.2cm}|p{6.4cm}| .. flat-table:: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst index 7e5d45f30cab..4f5120a6c678 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst @@ -11,7 +11,9 @@ V4L2_PIX_FMT_SRGGB14 ('RG14'), V4L2_PIX_FMT_SGRBG14 ('GR14'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +======================================== 14-bit Bayer formats expanded to 16 bits +======================================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst index e25baedfca77..3572e42adb22 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst @@ -36,9 +36,11 @@ Each cell is one byte. .. raw:: latex + \begingroup \footnotesize + \setlength{\tabcolsep}{2pt} -.. 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}| +.. tabularcolumns:: |p{1.6cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{3.5cm}|p{3.5cm}|p{3.5cm}| .. flat-table:: :header-rows: 0 @@ -141,5 +143,5 @@ Each cell is one byte. .. raw:: latex - \normalsize + \endgroup diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst index 93a210e22592..2f2f1ef430d9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst @@ -11,7 +11,9 @@ V4L2_PIX_FMT_SRGGB16 ('RG16'), V4L2_PIX_FMT_SGRBG16 ('GR16'), V4L2_PIX_FMT_SGBRG *************************************************************************************************************************** +==================== 16-bit Bayer formats +==================== Description diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst index 81e72f115994..02061c5a9778 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst @@ -10,8 +10,9 @@ V4L2_PIX_FMT_SRGGB8 ('RGGB'), V4L2_PIX_FMT_SGRBG8 ('GRBG'), V4L2_PIX_FMT_SGBRG8 *************************************************************************************************************************** +=================== 8-bit Bayer formats - +=================== Description =========== diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst index 977facc3a1f4..ad4da988c3a3 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst @@ -13,7 +13,7 @@ describing all planes of that format. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.0cm}|p{11.9cm}| .. c:type:: v4l2_plane_pix_format @@ -52,7 +52,7 @@ describing all planes of that format. \small -.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}| +.. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.3cm}| .. c:type:: v4l2_pix_format_mplane diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst index 71e828093310..9c423ffe02f9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst @@ -4,7 +4,7 @@ Single-planar format structure ****************************** -.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}| +.. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7cm}| .. c:type:: v4l2_pix_format @@ -205,7 +205,7 @@ Single-planar format structure the flag V4L2_FMT_FLAG_CSC_XFER_FUNC in the corresponding struct :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.8cm}|p{2.3cm}|p{8.2cm}| .. _format-flags: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst index 0c8c5e0a380e..91942c4f0967 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -19,6 +19,12 @@ are often referred to as greyscale formats. - `0` denotes padding bits set to 0. +.. raw:: latex + + \scriptsize + +.. tabularcolumns:: |p{3.6cm}|p{3.0cm}|p{1.3cm}|p{2.6cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}| + .. flat-table:: Luma-Only Image Formats :header-rows: 1 :stub-columns: 0 @@ -119,6 +125,10 @@ are often referred to as greyscale formats. - ... - ... +.. raw:: latex + + \normalsize + .. note:: For the Y16 and Y16_BE formats, the actual sampling precision may be lower diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst index 1e0db602cc1b..090c091affd2 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -48,6 +48,12 @@ relationship between the luma and chroma line padding and stride. All components are stored with the same number of bits per component. +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{5.2cm}|p{1.0cm}|p{1.5cm}|p{1.9cm}|p{1.2cm}|p{1.8cm}|p{2.7cm}| + .. flat-table:: Overview of Semi-Planar YUV Formats :header-rows: 1 :stub-columns: 0 @@ -146,12 +152,14 @@ All components are stored with the same number of bits per component. - Yes - Linear -.. note:: +.. raw:: latex + + \normalsize - .. [1] Order of chroma samples in the second plane - .. [2] Indicates if planes have to be contiguous in memory or can be - disjoint - .. [3] Macroblock size in pixels +.. [1] Order of chroma samples in the second plane +.. [2] Indicates if planes have to be contiguous in memory or can be + disjoint +.. [3] Macroblock size in pixels **Color Sample Location:** @@ -481,6 +489,12 @@ relationship between the luma and chroma line padding and stride. All components are stored with the same number of bits per component. +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.0cm}|p{1.1cm}|p{1.5cm}|p{2.2cm}|p{1.2cm}|p{3.7cm}| + .. flat-table:: Overview of Fully Planar YUV Formats :header-rows: 1 :stub-columns: 0 @@ -565,11 +579,13 @@ All components are stored with the same number of bits per component. - Y, Cr, Cb - No -.. note:: +.. raw:: latex + + \normalsize - .. [4] Order of luma and chroma planes - .. [5] Indicates if planes have to be contiguous in memory or can be - disjoint +.. [4] Order of luma and chroma planes +.. [5] Indicates if planes have to be contiguous in memory or can be + disjoint **Color Sample Location:** diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 7f16cbe46e5c..bd68588b2683 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -5,10 +5,12 @@ Media Bus Formats ================= -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_mbus_framefmt +.. tabularcolumns:: |p{2.0cm}|p{4.0cm}|p{11.3cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_mbus_framefmt :header-rows: 0 :stub-columns: 0 @@ -113,6 +115,8 @@ Media Bus Formats .. _v4l2-mbus-framefmt-flags: +.. tabularcolumns:: |p{6.5cm}|p{1.6cm}|p{9.2cm}| + .. flat-table:: v4l2_mbus_framefmt Flags :header-rows: 0 :stub-columns: 0 @@ -204,7 +208,7 @@ The following tables list existing packed RGB formats. .. it switches to long table, and there's no way to override it. -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-rgb: @@ -1567,8 +1571,8 @@ The following tables list existing packed RGB formats. - MEDIA_BUS_FMT_RGB101010_1X30 - 0x1018 - - - 0 - - 0 + - + - - r\ :sub:`9` - r\ :sub:`8` - r\ :sub:`7` @@ -1890,7 +1894,7 @@ JEIDA defined bit mapping will be named .. raw:: latex - \tiny + \small .. _v4l2-mbus-pixelcode-rgb-lvds: @@ -2152,7 +2156,7 @@ organization is given as an example for the first pixel only. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|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{6.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|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-bayer: @@ -3005,7 +3009,7 @@ the following codes. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8: @@ -7210,7 +7214,7 @@ The following table list existing packed 36bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{4.1cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-36bit: @@ -7398,7 +7402,7 @@ The following table list existing packed 48bit wide YUV formats. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-yuv8-48bit: @@ -7851,7 +7855,7 @@ The following table lists existing JPEG compressed formats. .. _v4l2-mbus-pixelcode-jpeg: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{10.1cm}| +.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{9.9cm}| .. flat-table:: JPEG Formats :header-rows: 1 @@ -7884,7 +7888,7 @@ formats. .. _v4l2-mbus-pixelcode-vendor-specific: -.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| .. flat-table:: Vendor and device specific formats :header-rows: 1 @@ -7909,7 +7913,7 @@ This section lists all metadata formats. The following table lists the existing metadata formats. -.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.7cm}| +.. tabularcolumns:: |p{8.0cm}|p{1.4cm}|p{7.9cm}| .. flat-table:: Metadata formats :header-rows: 1 diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst index 3a834d050110..1cb1531c1e52 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst @@ -6,10 +6,16 @@ Selection flags *************** -.. tabularcolumns:: |p{5.2cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.6cm}| - .. _v4l2-selection-flags-table: +.. raw:: latex + + \small + +.. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{6.5cm}|p{1.2cm}|p{1.2cm}| + +.. cssclass:: longtable + .. flat-table:: Selection flag definitions :header-rows: 1 :stub-columns: 0 @@ -42,3 +48,7 @@ Selection flags inside the subdevice to all further processing steps. - No - Yes + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst index e877ebbdb32e..b46bae984f35 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst @@ -12,7 +12,13 @@ of the two interfaces they are used. .. _v4l2-selection-targets-table: -.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{7.4cm}|p{1.2cm}|p{1.4cm}| +.. raw:: latex + + \small + +.. tabularcolumns:: |p{6.2cm}|p{1.4cm}|p{7.3cm}|p{1.2cm}|p{0.8cm}| + +.. cssclass:: longtable .. flat-table:: Selection target definitions :header-rows: 1 @@ -69,3 +75,7 @@ of the two interfaces they are used. modified by hardware. - Yes - No + +.. raw:: latex + + \normalsize diff --git a/Documentation/userspace-api/media/v4l/vbi_525.svg b/Documentation/userspace-api/media/v4l/vbi_525.svg index b01086d466a6..1951de29a111 100644 --- a/Documentation/userspace-api/media/v4l/vbi_525.svg +++ b/Documentation/userspace-api/media/v4l/vbi_525.svg @@ -14,7 +14,7 @@ xml:space="preserve" width="208.73068mm" height="51.395489mm" - viewBox="0 0 739.59691 182.11" + viewBox="0 0 788.90338 194.25067" sodipodi:docname="vbi_525.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -25,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_625.svg b/Documentation/userspace-api/media/v4l/vbi_625.svg index 41c1ce920d14..21f524de3aed 100644 --- a/Documentation/userspace-api/media/v4l/vbi_625.svg +++ b/Documentation/userspace-api/media/v4l/vbi_625.svg @@ -14,7 +14,7 @@ xml:space="preserve" width="209.46608mm" height="51.576824mm" - viewBox="0 0 742.20265 182.75252" + viewBox="0 0 791.6828 194.93604" sodipodi:docname="vbi_625.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -25,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" fit-margin-top="0" diff --git a/Documentation/userspace-api/media/v4l/vbi_hsync.svg b/Documentation/userspace-api/media/v4l/vbi_hsync.svg index 7fcf12a7ece0..d360251e5f20 100644 --- a/Documentation/userspace-api/media/v4l/vbi_hsync.svg +++ b/Documentation/userspace-api/media/v4l/vbi_hsync.svg @@ -14,7 +14,7 @@ xml:space="preserve" width="192.39857mm" height="146.83536mm" - viewBox="0 0 681.72724 520.28277" + viewBox="0 0 727.17572 554.96826" sodipodi:docname="vbi_hsync.svg"><sodipodi:namedview pagecolor="#ffffff" bordercolor="#666666" @@ -25,7 +25,7 @@ inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="1920" - inkscape:window-height="997" + inkscape:window-height="1000" id="namedview4" showgrid="false" inkscape:zoom="1.5350601" diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst index b06e5b528e11..f98f18c9e91c 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst @@ -72,7 +72,7 @@ than the number requested. .. c:type:: v4l2_create_buffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_create_buffers :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index 00c31410d4e4..551ac9d3c6ef 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -45,7 +45,7 @@ overlay devices. .. c:type:: v4l2_cropcap -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_cropcap :header-rows: 0 @@ -96,7 +96,7 @@ overlay devices. .. _v4l2-rect-crop: -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_rect :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst index bde6e952b267..1a1e093936f1 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst @@ -75,7 +75,7 @@ is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. _name-v4l2-dbg-match: @@ -101,7 +101,7 @@ instructions. - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_dbg_chip_info @@ -127,7 +127,7 @@ instructions. - Reserved fields, both application and driver must set these to 0. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _name-chip-match-types: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst index e1a6abe705bd..53f10c7319b2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst @@ -85,7 +85,7 @@ It is available from the LinuxTV v4l-dvb repository; see `https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access instructions. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_dbg_match @@ -131,7 +131,7 @@ instructions. - The value read from, or to be written into the register. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _chip-match-types: diff --git a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst index fd71ceece037..7ccae3b91616 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst @@ -59,7 +59,7 @@ In principle, these ioctls are optional, not all drivers may support them. They introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders (as further documented in :ref:`decoder`). -.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}| +.. tabularcolumns:: |p{2.0cm}|p{1.1cm}|p{2.2cm}|p{11.8cm}| .. c:type:: v4l2_decoder_cmd @@ -129,7 +129,9 @@ introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decod - -.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}| +.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.1cm}| + +.. cssclass:: longtable .. _decoder-cmds: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst index 634af717c8ba..6eb40073c906 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -37,11 +37,10 @@ structure are filled by the driver. The file handle will also receive exceptions which the application may get by e.g. using the select system call. -.. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}| - .. c:type:: v4l2_event -.. cssclass: longtable +.. tabularcolumns:: |p{3.0cm}|p{3.4cm}|p{10.9cm}| + .. flat-table:: struct v4l2_event :header-rows: 0 @@ -98,7 +97,7 @@ call. zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.2cm}|p{2.6cm}|p{8.5cm}| .. cssclass:: longtable @@ -188,7 +187,7 @@ call. - Base event number for driver-private events. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_vsync @@ -202,7 +201,7 @@ call. - The upcoming field. See enum :c:type:`v4l2_field`. -.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{10.8cm}| .. c:type:: v4l2_event_ctrl @@ -252,7 +251,7 @@ call. :ref:`v4l2_queryctrl <v4l2-queryctrl>`. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_frame_sync @@ -266,7 +265,7 @@ call. - The sequence number of the frame being received. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_src_change @@ -281,7 +280,7 @@ call. :ref:`src-changes-flags`. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_event_motion_det @@ -310,7 +309,7 @@ call. automatically assigned to the default region 0. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _ctrl-changes-flags: @@ -335,7 +334,7 @@ call. step or the default value of the control changed. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _src-changes-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst index 27bd6a83e42c..8ced100bb156 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst @@ -55,7 +55,7 @@ the desired pad number in the struct zero the ``reserved`` array. Attempts to query capabilities on a pad that doesn't support them will return an ``EINVAL`` error code. -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.2cm}|p{12.9cm}| .. c:type:: v4l2_bt_timings_cap @@ -96,7 +96,7 @@ that doesn't support them will return an ``EINVAL`` error code. Drivers must set the array to zero. -.. tabularcolumns:: |p{1.0cm}|p{4.0cm}|p{3.5cm}|p{9.2cm}| +.. tabularcolumns:: |p{4.4cm}|p{3.6cm}|p{9.3cm}| .. c:type:: v4l2_dv_timings_cap @@ -128,7 +128,7 @@ that doesn't support them will return an ``EINVAL`` error code. * - } - -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| .. _dv-bt-cap-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst index 5673606711b4..2b5867a68b31 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst @@ -66,7 +66,7 @@ These ioctls are optional, not all drivers may support them. They were introduced in Linux 2.6.21. They are, however, mandatory for stateful mem2mem encoders (as further documented in :ref:`encoder`). -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_encoder_cmd @@ -89,7 +89,7 @@ encoders (as further documented in :ref:`encoder`). the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-cmds: @@ -133,7 +133,7 @@ encoders (as further documented in :ref:`encoder`). the encoder is already running, this command does nothing. No flags are defined for this command. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _encoder-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst index 20730cd4f6ef..a91c1a3f0e32 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst @@ -67,7 +67,7 @@ return an ``EINVAL`` error code. .. c:type:: v4l2_enum_dv_timings -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_enum_dv_timings :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index 2b3fa9c23146..000c154b0f98 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -71,10 +71,12 @@ the ``mbus_code`` field is handled differently: formats shall not depend on the active configuration of the video device or device pipeline. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_fmtdesc +.. cssclass:: longtable + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + .. flat-table:: struct v4l2_fmtdesc :header-rows: 0 :stub-columns: 0 @@ -135,7 +137,9 @@ the ``mbus_code`` field is handled differently: zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{8.4cm}|p{1.8cm}|p{7.1cm}| + +.. cssclass:: longtable .. _fmtdesc-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst index 1f0949726045..34cd39feaeaa 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst @@ -99,8 +99,6 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmival_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmival_stepwise :header-rows: 0 :stub-columns: 0 @@ -119,7 +117,7 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmivalenum -.. tabularcolumns:: |p{1.8cm}|p{4.4cm}|p{2.4cm}|p{8.9cm}| +.. tabularcolumns:: |p{4.9cm}|p{3.3cm}|p{9.1cm}| .. flat-table:: struct v4l2_frmivalenum :header-rows: 0 @@ -154,7 +152,6 @@ application should zero out all members except for the *IN* fields. - * - __u32 - ``reserved[2]`` - - - Reserved space for future use. Must be zeroed by drivers and applications. @@ -164,7 +161,7 @@ Enums .. c:type:: v4l2_frmivaltypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmivaltypes :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst index c9a36bcf699f..7271fe37ce3f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst @@ -89,8 +89,6 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmsize_discrete -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_discrete :header-rows: 0 :stub-columns: 0 @@ -106,8 +104,6 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmsize_stepwise -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. flat-table:: struct v4l2_frmsize_stepwise :header-rows: 0 :stub-columns: 0 @@ -135,7 +131,7 @@ application should zero out all members except for the *IN* fields. .. c:type:: v4l2_frmsizeenum -.. tabularcolumns:: |p{1.4cm}|p{5.9cm}|p{2.3cm}|p{8.0cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.8cm}|p{8.1cm}| .. flat-table:: struct v4l2_frmsizeenum :header-rows: 0 @@ -173,7 +169,7 @@ Enums .. c:type:: v4l2_frmsizetypes -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_frmsizetypes :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst index a0764fca8d18..e385929bed62 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst @@ -40,7 +40,7 @@ fields, and zero out the ``reserved`` array of a struct This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability of the corresponding tuner/modulator is set. -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_frequency_band @@ -108,7 +108,7 @@ of the corresponding tuner/modulator is set. Applications and drivers must set the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _band-modulation: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst index 0f62e681a827..d5f0535bd866 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enuminput.rst @@ -38,7 +38,7 @@ fill the rest of the structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all inputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{3.0cm}|p{3.5cm}|p{10.8cm}| .. c:type:: v4l2_input @@ -101,7 +101,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{1.0cm}|p{9.7cm}| .. _input-type: @@ -123,7 +123,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - This input is a touch device for capturing raw touch data. -.. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}| +.. tabularcolumns:: |p{5.6cm}|p{2.6cm}|p{9.1cm}| .. _input-status: @@ -194,7 +194,7 @@ at index zero, incrementing by one until the driver returns ``EINVAL``. - VTR time constant. [?] -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.4cm}|p{8.3cm}| .. _input-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst index 91fcf99094d2..06ee8386ae86 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst @@ -39,7 +39,7 @@ when the index is out of bounds. To enumerate all outputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_output @@ -96,7 +96,7 @@ shall begin at index zero, incrementing by one until the driver returns zero. -.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.5cm}|p{0.6cm}|p{9.2cm}| .. _output-type: @@ -118,7 +118,7 @@ shall begin at index zero, incrementing by one until the driver returns - The video output will be copied to a :ref:`video overlay <overlay>`. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.4cm}|p{2.4cm}|p{8.5cm}| .. _output-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst index b5704e8cf909..6af71b74d42e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enumstd.rst @@ -47,7 +47,7 @@ or output. [#f1]_ .. c:type:: v4l2_standard -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_standard :header-rows: 0 @@ -86,7 +86,7 @@ or output. [#f1]_ .. c:type:: v4l2_fract -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_fract :header-rows: 0 @@ -100,7 +100,7 @@ or output. [#f1]_ - ``denominator`` - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _v4l2-std-id: diff --git a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst index 212377c90442..982e8bcd9c47 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-expbuf.rst @@ -112,7 +112,7 @@ Examples .. c:type:: v4l2_exportbuffer -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_exportbuffer :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst index 4c93bd55bd97..bf61db04d12e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audio.rst @@ -49,7 +49,7 @@ ioctl. Drivers may switch to a different audio mode if the request cannot be satisfied. However, this is a write-only ioctl, it does not return the actual new audio mode. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_audio @@ -79,7 +79,7 @@ return the actual new audio mode. the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-capability: @@ -99,7 +99,7 @@ return the actual new audio mode. - Automatic Volume Level mode is supported. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _audio-mode: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst index 194f22493517..9ab15add2911 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst @@ -58,7 +58,7 @@ as ``VIDIOC_G_AUDOUT`` does. .. c:type:: v4l2_audioout -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_audioout :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst index 0ac1509e41cc..570d98308dc4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-crop.rst @@ -71,7 +71,7 @@ When cropping is not supported then no parameters are changed and .. c:type:: v4l2_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_crop :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst index 4f1bed53fad5..80e8c63d530f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst @@ -57,7 +57,7 @@ These ioctls work only with user controls. For other control classes the .. c:type:: v4l2_control -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_control :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst index 760a33d43b7d..6518d857c131 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst @@ -82,10 +82,12 @@ EBUSY EPERM ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - .. c:type:: v4l2_bt_timings +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_bt_timings :header-rows: 0 :stub-columns: 0 @@ -171,7 +173,7 @@ EPERM - Reserved for future extensions. Drivers and applications must set the array to zero. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.1cm}| .. c:type:: v4l2_dv_timings @@ -194,7 +196,7 @@ EPERM * - } - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. _dv-timing-types: @@ -213,7 +215,9 @@ EPERM - 0 - BT.656/1120 timings -.. tabularcolumns:: |p{4.5cm}|p{12.8cm}| +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. cssclass:: longtable .. _dv-bt-standards: @@ -236,7 +240,9 @@ EPERM There are no horizontal syncs/porches at all in this format. Total blanking timings must be set in hsync or vsync fields only. -.. tabularcolumns:: |p{7.0cm}|p{10.5cm}| +.. tabularcolumns:: |p{7.7cm}|p{9.8cm}| + +.. cssclass:: longtable .. _dv-bt-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst index 39d523a449a7..fc5535c50d61 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-edid.rst @@ -100,7 +100,7 @@ EDID is no longer available. .. c:type:: v4l2_edid -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_edid :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst index 7698e65ccccf..c6792bbe3d04 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst @@ -54,7 +54,7 @@ will be zero. Currently this ioctl is only defined for MPEG-2 program streams and video elementary streams. -.. tabularcolumns:: |p{3.8cm}|p{5.6cm}|p{8.1cm}| +.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}| .. c:type:: v4l2_enc_idx @@ -81,7 +81,7 @@ video elementary streams. their ``offset``. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_enc_idx_entry @@ -113,7 +113,7 @@ video elementary streams. - Reserved for future extensions. Drivers must set the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _enc-idx-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index b9c62affbb5a..3ba22983d21f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -118,11 +118,15 @@ correct. This prevents the situation where only some of the controls were set/get. Only low-level errors (e. g. a failed i2c command) can still cause this situation. -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{1.5cm}|p{11.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{4.0cm}|p{6.5cm}| .. c:type:: v4l2_ext_control -.. cssclass: longtable +.. raw:: latex + + \footnotesize + +.. cssclass:: longtable .. flat-table:: struct v4l2_ext_control :header-rows: 0 @@ -134,11 +138,12 @@ still cause this situation. - Identifies the control, set by the application. * - __u32 - ``size`` - - The total size in bytes of the payload of this control. This is - normally 0, but for pointer controls this should be set to the - size of the memory containing the payload, or that will receive - the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is - less than is required to store the payload result, then it is set + - The total size in bytes of the payload of this control. + * - :cspan:`2` The ``size`` field is normally 0, but for pointer + controls this should be set to the size of the memory that contains + the payload or that will receive the payload. + If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value + is less than is required to store the payload result, then it is set to a value large enough to store the payload result and ``ENOSPC`` is returned. @@ -212,6 +217,18 @@ still cause this situation. - ``p_fwht_params`` - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``. + * - struct :c:type:`v4l2_ctrl_vp8_frame` * + - ``p_vp8_frame`` + - A pointer to a struct :c:type:`v4l2_ctrl_vp8_frame`. Valid if this control is + of type ``V4L2_CTRL_TYPE_VP8_FRAME``. + * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` * + - ``p_hdr10_cll`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``. + * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` * + - ``p_hdr10_mastering`` + - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is + of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``. * - void * - ``ptr`` - A pointer to a compound type which can be an N-dimensional array @@ -221,7 +238,11 @@ still cause this situation. * - } - -.. tabularcolumns:: |p{4.0cm}|p{2.2cm}|p{2.1cm}|p{8.2cm}| +.. raw:: latex + + \normalsize + +.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{10.8cm}| .. c:type:: v4l2_ext_controls @@ -235,29 +256,18 @@ still cause this situation. * - union { - (anonymous) * - __u32 - - ``ctrl_class`` - - The control class to which all controls belong, see - :ref:`ctrl-class`. Drivers that use a kernel framework for - handling controls will also accept a value of 0 here, meaning that - the controls can belong to any control class. Whether drivers - support this can be tested by setting ``ctrl_class`` to 0 and - calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that - succeeds, then the driver supports this feature. - * - __u32 - ``which`` - Which value of the control to get/set/try. - ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the - control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default + * - :cspan:`2` ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of + the control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default value of the control and ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that these controls have to be retrieved from a request or tried/set for a request. In the latter case the ``request_fd`` field contains the file descriptor of the request that should be used. If the device does not support requests, then ``EACCES`` will be returned. - .. note:: - - When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that you can only - get the default value of the control, you cannot set or try it. + When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that you can only + get the default value of the control, you cannot set or try it. For backwards compatibility you can also use a control class here (see :ref:`ctrl-class`). In that case all controls have to @@ -265,9 +275,12 @@ still cause this situation. just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and that require a control class here. You can test for such drivers - by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling - VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the - driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + by setting ``which`` to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling + :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a count of 0. + If that fails, then the driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``. + * - __u32 + - ``ctrl_class`` + - Deprecated name kept for backwards compatibility. Use ``which`` instead. * - } - * - __u32 @@ -275,7 +288,8 @@ still cause this situation. - The number of controls in the controls array. May also be zero. * - __u32 - ``error_idx`` - - Set by the driver in case of an error. If the error is associated + - Index of the failing control. Set by the driver in case of an error. + * - :cspan:`2` If the error is associated with a particular control, then ``error_idx`` is set to the index of that control. If the error is not related to a specific control, or the validation step failed (see below), then @@ -334,7 +348,9 @@ still cause this situation. Ignored if ``count`` equals zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.3cm}|p{2.0cm}|p{8.0cm}| + +.. cssclass:: longtable .. _ctrl-class: @@ -394,6 +410,10 @@ still cause this situation. - 0xa40000 - The class containing stateless codec controls. These controls are described in :ref:`codec-stateless-controls`. + * - ``V4L2_CTRL_CLASS_COLORIMETRY`` + - 0xa50000 + - The class containing colorimetry controls. These controls are + described in :ref:`colorimetry-controls`. Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst index dc1f16343b22..b6cc1a823207 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst @@ -75,7 +75,7 @@ jeopardize the system security, its stability or even damage the hardware, therefore only the superuser can set the parameters for a destructive video overlay. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}| .. c:type:: v4l2_framebuffer @@ -207,7 +207,7 @@ destructive video overlay. - ``priv`` - Reserved. Drivers and applications must set this field to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-cap: @@ -255,7 +255,7 @@ destructive video overlay. chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY`` -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}| .. _framebuffer-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst index 7e9f8475ea63..675c385e5aca 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst @@ -89,7 +89,7 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical .. c:type:: v4l2_format -.. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}| +.. tabularcolumns:: |p{7.4cm}|p{4.4cm}|p{5.5cm}| .. flat-table:: struct v4l2_format :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst index 5445a4a442e4..0d037665a89e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst @@ -51,7 +51,7 @@ structure. When the requested frequency is not possible the driver assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a write-only ioctl, it does not return the actual new frequency. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_frequency diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst index 93ed111dfcb9..d4565d2cc1f5 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst @@ -54,7 +54,7 @@ stored in the JPEG-encoded fields. These define how the JPEG field is encoded. If you omit them, applications assume you've used standard encoding. You usually do want to add them. -.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. c:type:: v4l2_jpegcompression @@ -91,7 +91,7 @@ encoding. You usually do want to add them. control is exposed by a driver applications should use it instead and ignore this field. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _jpeg-markers: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst index 2ac2473e341b..6bdf925f9a4a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst @@ -60,7 +60,7 @@ context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. -.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| +.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}| .. c:type:: v4l2_modulator @@ -119,8 +119,9 @@ To change the radio frequency the Drivers and applications must set the array to zero. +.. tabularcolumns:: |p{6.0cm}|p{2.0cm}|p{9.3cm}| -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. cssclass:: longtable .. _modulator-txsubchans: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst index 724f7fa7bae1..8b5600fbf013 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst @@ -56,7 +56,7 @@ To get and set the streaming parameters applications call the pointer to a struct :c:type:`v4l2_streamparm` which contains a union holding separate parameters for input and output devices. -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| +.. tabularcolumns:: |p{3.7cm}|p{3.5cm}|p{10.1cm}| .. c:type:: v4l2_streamparm @@ -85,10 +85,9 @@ union holding separate parameters for input and output devices. - ``raw_data``\ [200] - A place holder for future extensions. * - } - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_captureparm @@ -147,7 +146,7 @@ union holding separate parameters for input and output devices. the array to zero. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_outputparm @@ -207,7 +206,7 @@ union holding separate parameters for input and output devices. the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-caps: @@ -222,7 +221,7 @@ union holding separate parameters for input and output devices. field. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _parm-flags: diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst index d72a0c716fca..3031256159c3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-priority.rst @@ -45,7 +45,7 @@ with a pointer to this variable. .. c:type:: v4l2_priority -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. flat-table:: enum v4l2_priority :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst index 9a9e589cce77..2b5b27260741 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-selection.rst @@ -129,7 +129,7 @@ Selection targets and flags are documented in .. c:type:: v4l2_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_selection :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst index 752f7f5fae73..90d40f6af57b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst @@ -45,7 +45,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. .. c:type:: v4l2_sliced_vbi_cap -.. tabularcolumns:: |p{1.2cm}|p{4.2cm}|p{4.1cm}|p{4.0cm}|p{4.0cm}| +.. tabularcolumns:: |p{1.4cm}|p{4.4cm}|p{4.5cm}|p{3.6cm}|p{3.6cm}| .. flat-table:: struct v4l2_sliced_vbi_cap :header-rows: 0 @@ -122,7 +122,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. \scriptsize -.. tabularcolumns:: |p{3.5cm}|p{1.0cm}|p{2.0cm}|p{2.0cm}|p{8.0cm}| +.. tabularcolumns:: |p{3.9cm}|p{1.0cm}|p{2.0cm}|p{3.0cm}|p{7.0cm}| .. _vbi-services: @@ -162,13 +162,7 @@ the sliced VBI API is unsupported or ``type`` is invalid. :ref:`itu1119` - PAL/SECAM line 23 - - - - :: - - Byte 0 1 - msb lsb msb lsb - Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 + - See :ref:`v4l2-sliced-vbi-cap-wss-625-payload` below. * - ``V4L2_SLICED_VBI_525`` - 0x1000 - :cspan:`2` Set of services applicable to 525 line systems. @@ -176,10 +170,27 @@ the sliced VBI API is unsupported or ``type`` is invalid. - 0x4401 - :cspan:`2` Set of services applicable to 625 line systems. + .. raw:: latex \normalsize +.. _v4l2-sliced-vbi-cap-wss-625-payload: + +V4L2_SLICED_VBI_CAP WSS_625 payload +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The payload for ``V4L2_SLICED_WSS_625`` is: + + +-----+------------------+-----------------------+ + |Byte | 0 | 1 | + +-----+--------+---------+-----------+-----------+ + | | msb | lsb | msb | lsb | + | +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 | + +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+ + + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst index 116e66c01556..b0522f1ff7a4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst @@ -59,7 +59,7 @@ to zero. The term 'tuner' means SDR receiver in this context. To change the radio frequency the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. - .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}| + .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}| .. c:type:: v4l2_tuner @@ -182,7 +182,7 @@ To change the radio frequency the Drivers and applications must set the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. c:type:: v4l2_tuner_type @@ -205,7 +205,7 @@ To change the radio frequency the - 5 - Tuner controls the RF part of a Software Digital Radio (SDR) -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}| .. _tuner-capability: @@ -296,7 +296,7 @@ To change the radio frequency the instead of 62.5 kHz. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-rxsubchans: @@ -334,7 +334,7 @@ To change the radio frequency the - The tuner receives an RDS channel. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _tuner-audmode: diff --git a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst index b512b1fbf9a3..63e23f6f95ee 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-querycap.rst @@ -38,10 +38,12 @@ pointer to a struct :c:type:`v4l2_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns an ``EINVAL`` error code. -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| - .. c:type:: v4l2_capability +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| + +.. cssclass:: longtable + .. flat-table:: struct v4l2_capability :header-rows: 0 :stub-columns: 0 @@ -130,7 +132,7 @@ specification the ioctl returns an ``EINVAL`` error code. zero. -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{7.0cm}|p{2.6cm}|p{7.7cm}| .. _device-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 82f61f1e2fb8..8a285daedc6a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -94,7 +94,7 @@ inclusive. See also the examples in :ref:`control`. -.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.5cm}| .. _v4l2-queryctrl: @@ -172,7 +172,7 @@ See also the examples in :ref:`control`. zero. -.. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}| +.. tabularcolumns:: |p{1.2cm}|p{5.5cm}|p{10.6cm}| .. _v4l2-query-ext-ctrl: @@ -272,7 +272,7 @@ See also the examples in :ref:`control`. the array to zero. -.. tabularcolumns:: |p{1.2cm}|p{1.0cm}|p{1.7cm}|p{13.0cm}| +.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}| .. _v4l2-querymenu: @@ -306,10 +306,13 @@ See also the examples in :ref:`control`. - Reserved for future extensions. Drivers must set the array to zero. +.. c:type:: v4l2_ctrl_type -.. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}| +.. raw:: latex -.. c:type:: v4l2_ctrl_type + \footnotesize + +.. tabularcolumns:: |p{6.5cm}|p{1.5cm}|p{1.1cm}|p{1.5cm}|p{6.8cm}| .. cssclass:: longtable @@ -486,13 +489,23 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC slice parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_VP8_FRAME`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_vp8_frame`, containing VP8 + frame parameters for stateless video decoders. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. raw:: latex -.. _control-flags: + \normalsize + +.. tabularcolumns:: |p{7.3cm}|p{1.8cm}|p{8.2cm}| .. cssclass:: longtable +.. _control-flags: + .. flat-table:: Control Flags :header-rows: 0 :stub-columns: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst index c1c88e00b106..50ea72043bb0 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst @@ -71,7 +71,7 @@ aborting or finishing any DMA in progress, an implicit .. c:type:: v4l2_requestbuffers -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_requestbuffers :header-rows: 0 @@ -109,8 +109,6 @@ aborting or finishing any DMA in progress, an implicit - A place holder for future extensions. Drivers and applications must set the array to zero. -.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| - .. _v4l2-buf-capabilities: .. _V4L2-BUF-CAP-SUPPORTS-MMAP: .. _V4L2-BUF-CAP-SUPPORTS-USERPTR: @@ -120,6 +118,12 @@ aborting or finishing any DMA in progress, an implicit .. _V4L2-BUF-CAP-SUPPORTS-M2M-HOLD-CAPTURE-BUF: .. _V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS: +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.1cm}|p{2.2cm}|p{7.0cm}| + .. cssclass:: longtable .. flat-table:: V4L2 Buffer Capabilities Flags @@ -157,6 +161,10 @@ aborting or finishing any DMA in progress, an implicit :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`. +.. raw:: latex + + \normalsize + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst index 1948f31c2dbc..ed10f380579a 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst @@ -58,7 +58,7 @@ set. If this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` error code is returned and no seek takes place. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_hw_freq_seek diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst index 17acf3fd8396..3703943b412f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst @@ -61,7 +61,7 @@ multiple pads of the same sub-device is not defined. .. c:type:: v4l2_subdev_frame_interval_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval_enum :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst index 8016fba7023f..c25a9896df0e 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -63,7 +63,7 @@ information about try formats. .. c:type:: v4l2_subdev_frame_size_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_size_enum :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst index 1fd950e34a0b..417f1a19bcc4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -48,7 +48,7 @@ information about the try formats. .. c:type:: v4l2_subdev_mbus_code_enum -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_mbus_code_enum :header-rows: 0 @@ -79,7 +79,11 @@ information about the try formats. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{7.7cm}| +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{8.8cm}|p{2.2cm}|p{6.3cm}| .. _v4l2-subdev-mbus-code-flags: @@ -124,6 +128,10 @@ information about the try formats. ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set. See :ref:`v4l2-mbus-format` on how to do this. +.. raw:: latex + + \normalsize + Return Value ============ diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst index 2d78b4f5928d..bd15c0a5a66b 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst @@ -78,7 +78,7 @@ modified format should be as close as possible to the original request. .. c:type:: v4l2_subdev_crop -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_crop :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst index 90b9bbfb61dd..7acdbb939d89 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst @@ -81,7 +81,7 @@ doesn't match the device capabilities. They must instead modify the format to match what the hardware can provide. The modified format should be as close as possible to the original request. -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. c:type:: v4l2_subdev_format @@ -107,7 +107,7 @@ should be as close as possible to the original request. the array to zero. -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| .. _v4l2-subdev-format-whence: diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst index 3a50f8b2843d..d7fe7543c506 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst @@ -76,7 +76,7 @@ the same sub-device is not defined. .. c:type:: v4l2_subdev_frame_interval -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_frame_interval :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst index f35b9562df21..f9172a42f036 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst @@ -70,7 +70,7 @@ Selection targets and flags are documented in .. c:type:: v4l2_subdev_selection -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| .. flat-table:: struct v4l2_subdev_selection :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst index 949d9775b03d..9b8d8644ec0f 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst @@ -38,7 +38,7 @@ a struct :c:type:`v4l2_subdev_capability` which is filled by the driver. When the driver is not compatible with this specification the ioctl returns ``ENOTTY`` error code. -.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| +.. tabularcolumns:: |p{1.5cm}|p{2.9cm}|p{12.9cm}| .. c:type:: v4l2_subdev_capability @@ -75,7 +75,7 @@ the driver is not compatible with this specification the ioctl returns - ``reserved``\ [14] - Reserved for future extensions. Set to 0 by the V4L2 core. -.. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}| +.. tabularcolumns:: |p{6.8cm}|p{2.4cm}|p{8.1cm}| .. _subdevice-capabilities: diff --git a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst index d1ad35164033..a6fc3c5fe99d 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst @@ -39,7 +39,7 @@ Description Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by using the :ref:`VIDIOC_DQEVENT` ioctl. -.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}| +.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}| .. c:type:: v4l2_event_subscription @@ -71,7 +71,7 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. the array to zero. -.. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}| +.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}| .. _event-flags: diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions index 0ed170c6e720..f59940352faa 100644 --- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions @@ -147,6 +147,9 @@ replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AREA :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP8_FRAME :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_CLL_INFO :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 1a2b5210cdbf..245d80581f15 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -55,7 +55,7 @@ not cause harm to the host, their actual behavior is not guaranteed by the API. See "General description" for details on the ioctl usage model that is supported by KVM. -It is important to note that althought VM ioctls may only be issued from +It is important to note that although VM ioctls may only be issued from the process that created the VM, a VM's lifecycle is associated with its file descriptor, not its creator (process). In other words, the VM and its resources, *including the associated address space*, are not freed @@ -182,6 +182,9 @@ is dependent on the CPU capability and the kernel configuration. The limit can be retrieved using KVM_CAP_ARM_VM_IPA_SIZE of the KVM_CHECK_EXTENSION ioctl() at run-time. +Creation of the VM will fail if the requested IPA size (whether it is +implicit or explicit) is unsupported on the host. + Please note that configuring the IPA size does not affect the capability exposed by the guest CPUs in ID_AA64MMFR0_EL1[PARange]. It only affects size of the address translated by the stage2 level (guest physical to @@ -1492,7 +1495,8 @@ Fails if any VCPU has already been created. Define which vcpu is the Bootstrap Processor (BSP). Values are the same as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default -is vcpu 0. +is vcpu 0. This ioctl has to be called before vcpu creation, +otherwise it will return EBUSY error. 4.42 KVM_GET_XSAVE @@ -4803,8 +4807,10 @@ If an MSR access is not permitted through the filtering, it generates a allows user space to deflect and potentially handle various MSR accesses into user space. -If a vCPU is in running state while this ioctl is invoked, the vCPU may -experience inconsistent filtering behavior on MSR accesses. +Note, invoking this ioctl with a vCPU is running is inherently racy. However, +KVM does guarantee that vCPUs will see either the previous filter or the new +filter, e.g. MSRs with identical settings in both the old and new filter will +have deterministic behavior. 4.127 KVM_XEN_HVM_SET_ATTR -------------------------- diff --git a/Documentation/watchdog/pcwd-watchdog.rst b/Documentation/watchdog/pcwd-watchdog.rst index 405e2a370082..151505c856f6 100644 --- a/Documentation/watchdog/pcwd-watchdog.rst +++ b/Documentation/watchdog/pcwd-watchdog.rst @@ -47,7 +47,7 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com> WDIOC_GETSTATUS This returns the status of the card, with the bits of WDIOF_* bitwise-anded into the value. (The comments - are in linux/pcwd.h) + are in include/uapi/linux/watchdog.h) WDIOC_GETBOOTSTATUS This returns the status of the card that was reported diff --git a/Documentation/x86/sgx.rst b/Documentation/x86/sgx.rst index eaee1368b4fd..dd0ac96ff9ef 100644 --- a/Documentation/x86/sgx.rst +++ b/Documentation/x86/sgx.rst @@ -209,3 +209,44 @@ An application may be loaded into a container enclave which is specially configured with a library OS and run-time which permits the application to run. The enclave run-time and library OS work together to execute the application when a thread enters the enclave. + +Impact of Potential Kernel SGX Bugs +=================================== + +EPC leaks +--------- + +When EPC page leaks happen, a WARNING like this is shown in dmesg: + +"EREMOVE returned ... and an EPC page was leaked. SGX may become unusable..." + +This is effectively a kernel use-after-free of an EPC page, and due +to the way SGX works, the bug is detected at freeing. Rather than +adding the page back to the pool of available EPC pages, the kernel +intentionally leaks the page to avoid additional errors in the future. + +When this happens, the kernel will likely soon leak more EPC pages, and +SGX will likely become unusable because the memory available to SGX is +limited. However, while this may be fatal to SGX, the rest of the kernel +is unlikely to be impacted and should continue to work. + +As a result, when this happpens, user should stop running any new +SGX workloads, (or just any new workloads), and migrate all valuable +workloads. Although a machine reboot can recover all EPC memory, the bug +should be reported to Linux developers. + + +Virtual EPC +=========== + +The implementation has also a virtual EPC driver to support SGX enclaves +in guests. Unlike the SGX driver, an EPC page allocated by the virtual +EPC driver doesn't have a specific enclave associated with it. This is +because KVM doesn't track how a guest uses EPC pages. + +As a result, the SGX core page reclaimer doesn't support reclaiming EPC +pages allocated to KVM guests through the virtual EPC driver. If the +user wants to deploy SGX applications both on the host and in guests +on the same machine, the user should reserve enough EPC (by taking out +total virtual EPC size of all SGX VMs from the physical EPC size) for +host SGX applications so they can run with acceptable performance. |
