diff options
Diffstat (limited to 'Documentation')
826 files changed, 27167 insertions, 9876 deletions
diff --git a/Documentation/ABI/stable/sysfs-driver-dma-idxd b/Documentation/ABI/stable/sysfs-driver-dma-idxd index 825e619250bf..f2ec42949a54 100644 --- a/Documentation/ABI/stable/sysfs-driver-dma-idxd +++ b/Documentation/ABI/stable/sysfs-driver-dma-idxd @@ -270,6 +270,12 @@ Description: Shows the operation capability bits displayed in bitmap format correlates to the operations allowed. It's visible only on platforms that support the capability. +What: /sys/bus/dsa/devices/wq<m>.<n>/driver_name +Date: Sept 8, 2023 +KernelVersion: 6.7.0 +Contact: dmaengine@vger.kernel.org +Description: Name of driver to be bounded to the wq. + What: /sys/bus/dsa/devices/engine<m>.<n>/group_id Date: Oct 25, 2019 KernelVersion: 5.6.0 diff --git a/Documentation/ABI/testing/configfs-tsm b/Documentation/ABI/testing/configfs-tsm new file mode 100644 index 000000000000..dd24202b5ba5 --- /dev/null +++ b/Documentation/ABI/testing/configfs-tsm @@ -0,0 +1,82 @@ +What: /sys/kernel/config/tsm/report/$name/inblob +Date: September, 2023 +KernelVersion: v6.7 +Contact: linux-coco@lists.linux.dev +Description: + (WO) Up to 64 bytes of user specified binary data. For replay + protection this should include a nonce, but the kernel does not + place any restrictions on the content. + +What: /sys/kernel/config/tsm/report/$name/outblob +Date: September, 2023 +KernelVersion: v6.7 +Contact: linux-coco@lists.linux.dev +Description: + (RO) Binary attestation report generated from @inblob and other + options The format of the report is implementation specific + where the implementation is conveyed via the @provider + attribute. + +What: /sys/kernel/config/tsm/report/$name/auxblob +Date: October, 2023 +KernelVersion: v6.7 +Contact: linux-coco@lists.linux.dev +Description: + (RO) Optional supplemental data that a TSM may emit, visibility + of this attribute depends on TSM, and may be empty if no + auxiliary data is available. + + When @provider is "sev_guest" this file contains the + "cert_table" from SEV-ES Guest-Hypervisor Communication Block + Standardization v2.03 Section 4.1.8.1 MSG_REPORT_REQ. + https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56421.pdf + +What: /sys/kernel/config/tsm/report/$name/provider +Date: September, 2023 +KernelVersion: v6.7 +Contact: linux-coco@lists.linux.dev +Description: + (RO) A name for the format-specification of @outblob like + "sev_guest" [1] or "tdx_guest" [2] in the near term, or a + common standard format in the future. + + [1]: SEV Secure Nested Paging Firmware ABI Specification + Revision 1.55 Table 22 + https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf + + [2]: Intel® Trust Domain Extensions Data Center Attestation + Primitives : Quote Generation Library and Quote Verification + Library Revision 0.8 Appendix 4,5 + https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf + +What: /sys/kernel/config/tsm/report/$name/generation +Date: September, 2023 +KernelVersion: v6.7 +Contact: linux-coco@lists.linux.dev +Description: + (RO) The value in this attribute increments each time @inblob or + any option is written. Userspace can detect conflicts by + checking generation before writing to any attribute and making + sure the number of writes matches expectations after reading + @outblob, or it can prevent conflicts by creating a report + instance per requesting context. + +What: /sys/kernel/config/tsm/report/$name/privlevel +Date: September, 2023 +KernelVersion: v6.7 +Contact: linux-coco@lists.linux.dev +Description: + (WO) Attribute is visible if a TSM implementation provider + supports the concept of attestation reports for TVMs running at + different privilege levels, like SEV-SNP "VMPL", specify the + privilege level via this attribute. The minimum acceptable + value is conveyed via @privlevel_floor and the maximum + acceptable value is TSM_PRIVLEVEL_MAX (3). + +What: /sys/kernel/config/tsm/report/$name/privlevel_floor +Date: September, 2023 +KernelVersion: v6.7 +Contact: linux-coco@lists.linux.dev +Description: + (RO) Indicates the minimum permissible value that can be written + to @privlevel. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2 index 3371c39f651d..a2bf4fd82a5b 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uac2 +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2 @@ -35,4 +35,6 @@ Description: req_number the number of pre-allocated requests for both capture and playback function_name name of the interface + c_terminal_type code of the capture terminal type + p_terminal_type code of the playback terminal type ===================== ======================================= diff --git a/Documentation/ABI/testing/debugfs-driver-qat b/Documentation/ABI/testing/debugfs-driver-qat index 6731ffacc5f0..b2db010d851e 100644 --- a/Documentation/ABI/testing/debugfs-driver-qat +++ b/Documentation/ABI/testing/debugfs-driver-qat @@ -1,4 +1,4 @@ -What: /sys/kernel/debug/qat_<device>_<BDF>/qat/fw_counters +What: /sys/kernel/debug/qat_<device>_<BDF>/fw_counters Date: November 2023 KernelVersion: 6.6 Contact: qat-linux@intel.com @@ -59,3 +59,25 @@ Description: (RO) Read returns the device health status. The driver does not monitor for Heartbeat. It is left for a user to poll the status periodically. + +What: /sys/kernel/debug/qat_<device>_<BDF>/pm_status +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Read returns power management information specific to the + QAT device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/kernel/debug/qat_<device>_<BDF>/cnv_errors +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Read returns, for each Acceleration Engine (AE), the number + of errors and the type of the last error detected by the device + when performing verified compression. + Reported counters:: + + <N>: Number of Compress and Verify (CnV) errors and type + of the last CnV error detected by Acceleration + Engine N. diff --git a/Documentation/ABI/testing/sysfs-bus-cdx b/Documentation/ABI/testing/sysfs-bus-cdx index 7af477f49998..8c067ff99e54 100644 --- a/Documentation/ABI/testing/sysfs-bus-cdx +++ b/Documentation/ABI/testing/sysfs-bus-cdx @@ -28,14 +28,57 @@ Description: of a device manufacturer. Combination of Vendor ID and Device ID identifies a device. +What: /sys/bus/cdx/devices/.../subsystem_vendor +Date: July 2023 +Contact: puneet.gupta@amd.com +Description: + Subsystem Vendor ID for this CDX device, in hexadecimal. + Subsystem Vendor ID is 16 bit identifier specific to the + card manufacturer. + +What: /sys/bus/cdx/devices/.../subsystem_device +Date: July 2023 +Contact: puneet.gupta@amd.com +Description: + Subsystem Device ID for this CDX device, in hexadecimal + Subsystem Device ID is 16 bit identifier specific to the + card manufacturer. + +What: /sys/bus/cdx/devices/.../class +Date: July 2023 +Contact: puneet.gupta@amd.com +Description: + This file contains the class of the CDX device, in hexadecimal. + Class is 24 bit identifier specifies the functionality of the device. + +What: /sys/bus/cdx/devices/.../revision +Date: July 2023 +Contact: puneet.gupta@amd.com +Description: + This file contains the revision field of the CDX device, in hexadecimal. + Revision is 8 bit revision identifier of the device. + +What: /sys/bus/cdx/devices/.../enable +Date: October 2023 +Contact: abhijit.gangurde@amd.com +Description: + CDX bus should be disabled before updating the devices in FPGA. + Writing n/0/off will attempt to disable the CDX bus and. + writing y/1/on will attempt to enable the CDX bus. Reading this file + gives the current state of the bus, 1 for enabled and 0 for disabled. + + For example:: + + # echo 1 > /sys/bus/cdx/.../enable + What: /sys/bus/cdx/devices/.../reset Date: March 2023 Contact: nipun.gupta@amd.com Description: - Writing y/1/on to this file resets the CDX device. - On resetting the device, the corresponding driver is notified - twice, once before the device is being reset, and again after - the reset has been complete. + Writing y/1/on to this file resets the CDX device or all devices + on the bus. On resetting the device, the corresponding driver is + notified twice, once before the device is being reset, and again + after the reset has been complete. For example:: @@ -54,3 +97,18 @@ Description: For example:: # echo 1 > /sys/bus/cdx/devices/.../remove + +What: /sys/bus/cdx/devices/.../modalias +Date: July 2023 +Contact: nipun.gupta@amd.com +Description: + This attribute indicates the CDX ID of the device. + That is in the format: + cdx:vXXXXdXXXXsvXXXXsdXXXXcXXXXXX, + where: + + - vXXXX contains the vendor ID; + - dXXXX contains the device ID; + - svXXXX contains the subsystem vendor ID; + - sdXXXX contains the subsystem device ID; + - cXXXXXX contains the device class. diff --git a/Documentation/ABI/testing/sysfs-bus-cxl b/Documentation/ABI/testing/sysfs-bus-cxl index 087f762ebfd5..e76c3600607f 100644 --- a/Documentation/ABI/testing/sysfs-bus-cxl +++ b/Documentation/ABI/testing/sysfs-bus-cxl @@ -178,6 +178,21 @@ Description: hardware decoder target list. +What: /sys/bus/cxl/devices/portX/decoders_committed +Date: October, 2023 +KernelVersion: v6.7 +Contact: linux-cxl@vger.kernel.org +Description: + (RO) A memory device is considered active when any of its + decoders are in the "committed" state (See CXL 3.0 8.2.4.19.7 + CXL HDM Decoder n Control Register). Hotplug and destructive + operations like "sanitize" are blocked while device is actively + decoding a Host Physical Address range. Note that this number + may be elevated without any regionX objects active or even + enumerated, as this may be due to decoders established by + platform firwmare or a previous kernel (kexec). + + What: /sys/bus/cxl/devices/decoderX.Y Date: June, 2021 KernelVersion: v5.14 @@ -369,6 +384,21 @@ Description: provided it is currently idle / not bound to a driver. +What: /sys/bus/cxl/devices/decoderX.Y/qos_class +Date: May, 2023 +KernelVersion: v6.5 +Contact: linux-cxl@vger.kernel.org +Description: + (RO) For CXL host platforms that support "QoS Telemmetry" this + root-decoder-only attribute conveys a platform specific cookie + that identifies a QoS performance class for the CXL Window. + This class-id can be compared against a similar "qos_class" + published for each memory-type that an endpoint supports. While + it is not required that endpoints map their local memory-class + to a matching platform class, mismatches are not recommended and + there are platform specific side-effects that may result. + + What: /sys/bus/cxl/devices/regionZ/uuid Date: May, 2022 KernelVersion: v6.0 diff --git a/Documentation/ABI/testing/sysfs-bus-i3c b/Documentation/ABI/testing/sysfs-bus-i3c index 1f4a2662335b..e5248fd67a56 100644 --- a/Documentation/ABI/testing/sysfs-bus-i3c +++ b/Documentation/ABI/testing/sysfs-bus-i3c @@ -67,7 +67,7 @@ What: /sys/bus/i3c/devices/i3c-<bus-id>/pid KernelVersion: 5.0 Contact: linux-i3c@vger.kernel.org Description: - PID stands for Provisional ID and is used to uniquely identify + PID stands for Provisioned ID and is used to uniquely identify a device on a bus. This PID contains information about the vendor, the part and an instance ID so that several devices of the same type can be connected on the same bus. @@ -123,7 +123,7 @@ What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/pid KernelVersion: 5.0 Contact: linux-i3c@vger.kernel.org Description: - PID stands for Provisional ID and is used to uniquely identify + PID stands for Provisioned ID and is used to uniquely identify a device on a bus. This PID contains information about the vendor, the part and an instance ID so that several devices of the same type can be connected on the same bus. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index a2854dc9a839..19cde14f3869 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -279,6 +279,35 @@ Description: but should match other such assignments on device). Units after application of scale and offset are m/s^2. +What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_z_raw +KernelVersion: 6.5 +Contact: linux-iio@vger.kernel.org +Description: + Angular displacement between two consecutive samples on x, y or + z (may be arbitrarily assigned but should match other such + assignments on device). + In order to compute the total angular displacement during a + desired period of time, the application should sum-up the delta + angle samples acquired during that time. + Units after application of scale and offset are radians. + +What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_z_raw +KernelVersion: 6.5 +Contact: linux-iio@vger.kernel.org +Description: + The linear velocity change between two consecutive samples on x, + y or z (may be arbitrarily assigned but should match other such + assignments on device). + In order to compute the total linear velocity change during a + desired period of time, the application should sum-up the delta + velocity samples acquired during that time. + Units after application of scale and offset are meters per + second. + What: /sys/bus/iio/devices/iio:deviceX/in_angl_raw What: /sys/bus/iio/devices/iio:deviceX/in_anglY_raw KernelVersion: 4.17 @@ -461,6 +490,8 @@ What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_scale What: /sys/bus/iio/devices/iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_scale What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_scale What: /sys/bus/iio/devices/iio:deviceX/in_countY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_deltaangl_scale +What: /sys/bus/iio/devices/iio:deviceX/in_deltavelocity_scale What: /sys/bus/iio/devices/iio:deviceX/in_angl_scale What: /sys/bus/iio/devices/iio:deviceX/in_intensity_x_scale What: /sys/bus/iio/devices/iio:deviceX/in_intensity_y_scale @@ -1332,6 +1363,12 @@ Description: 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_deltaangl_x_en +What: /sys/.../iio:deviceX/bufferY/in_deltaangl_y_en +What: /sys/.../iio:deviceX/bufferY/in_deltaangl_z_en +What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_x_en +What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_y_en +What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_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 @@ -1362,6 +1399,8 @@ Description: Scan element control for triggered data capture. What: /sys/.../iio:deviceX/bufferY/in_accel_type +What: /sys/.../iio:deviceX/bufferY/in_deltaangl_type +What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_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 @@ -1416,6 +1455,12 @@ 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_deltaangl_x_index +What: /sys/.../iio:deviceX/bufferY/in_deltaangl_y_index +What: /sys/.../iio:deviceX/bufferY/in_deltaangl_z_index +What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_x_index +What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_y_index +What: /sys/.../iio:deviceX/bufferY/in_deltavelocity_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 @@ -2179,3 +2224,33 @@ Contact: linux-iio@vger.kernel.org Description: Number of conditions that must occur, during a running period, before an event is generated. + +What: /sys/bus/iio/devices/iio:deviceX/in_colortemp_raw +KernelVersion: 6.7 +Contact: linux-iio@vger.kernel.org +Description: + Represents light color temperature, which measures light color + temperature in Kelvin. + +What: /sys/bus/iio/devices/iio:deviceX/in_chromaticity_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_chromaticity_y_raw +KernelVersion: 6.7 +Contact: linux-iio@vger.kernel.org +Description: + The x and y light color coordinate on the CIE 1931 chromaticity + diagram. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_mag_either_label +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_mag_rising_label +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_thresh_falling_label +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltageY_thresh_rising_label +What: /sys/bus/iio/devices/iio:deviceX/events/in_anglvelY_mag_rising_label +What: /sys/bus/iio/devices/iio:deviceX/events/in_anglY_thresh_rising_label +What: /sys/bus/iio/devices/iio:deviceX/events/in_phaseY_mag_rising_label +KernelVersion: 6.7 +Contact: linux-iio@vger.kernel.org +Description: + Optional symbolic label to a device channel event. + If a label is defined for this event add that to the event + specific attributes. This is useful for userspace to be able to + better identify an individual event. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-mcp3564 b/Documentation/ABI/testing/sysfs-bus-iio-adc-mcp3564 new file mode 100644 index 000000000000..b168aa44b233 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-mcp3564 @@ -0,0 +1,53 @@ +What: /sys/bus/iio/devices/iio:deviceX/boost_current_gain +KernelVersion: 6.4 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to set the gain of the biasing current + circuit of the Delta-Sigma modulator. The different BOOST + settings are applied to the entire modulator circuit, including + the voltage reference buffers. + +What: /sys/bus/iio/devices/iio:deviceX/boost_current_gain_available +KernelVersion: 6.4 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns a list with the possible gain values for + the current biasing circuit of the Delta-Sigma modulator. + +What: /sys/bus/iio/devices/iio:deviceX/auto_zeroing_mux_enable +KernelVersion: 6.4 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to enable the analog input multiplexer + auto-zeroing algorithm (the input multiplexer and the ADC + include an offset cancellation algorithm that cancels the offset + contribution of the ADC). When the offset cancellation algorithm + is enabled, ADC takes two conversions, one with the differential + input as VIN+/VIN-, one with VIN+/VIN- inverted. In this case the + conversion time is multiplied by two compared to the default + case where the algorithm is disabled. This technique allows the + cancellation of the ADC offset error and the achievement of + ultra-low offset without any digital calibration. The resulting + offset is the residue of the difference between the two + conversions, which is on the order of magnitude of the noise + floor. This offset is effectively canceled at every conversion, + so the residual offset error temperature drift is extremely low. + Write '1' to enable it, write '0' to disable it. + +What: /sys/bus/iio/devices/iio:deviceX/auto_zeroing_ref_enable +KernelVersion: 6.4 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to enable the chopping algorithm for the + internal voltage reference buffer. This setting has no effect + when external voltage reference is selected. + Internal voltage reference buffer injects a certain quantity of + 1/f noise into the system that can be modulated with the + incoming input signals and can limit the SNR performance at + higher Oversampling Ratio values (over 256). To overcome this + limitation, the buffer includes an auto-zeroing algorithm that + greatly reduces (cancels out) the 1/f noise and cancels the + offset value of the reference buffer. As a result, the SNR of + the system is not affected by this 1/f noise component of the + reference buffer, even at maximum oversampling ratio values. + Write '1' to enable it, write '0' to disable it. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-resolver-ad2s1210 b/Documentation/ABI/testing/sysfs-bus-iio-resolver-ad2s1210 new file mode 100644 index 000000000000..f92c79342b93 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-resolver-ad2s1210 @@ -0,0 +1,27 @@ +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_max +KernelVersion: 6.7 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns the current Degradation of Signal Reset Maximum + Threshold value in millivolts. Writing sets the value. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_max_available +KernelVersion: 6.7 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns the allowable voltage range for + in_altvoltage0_mag_rising_reset_max. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_min +KernelVersion: 6.7 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns the current Degradation of Signal Reset Minimum + Threshold value in millivolts. Writing sets the value. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_altvoltage0_mag_rising_reset_min_available +KernelVersion: 6.7 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns the allowable voltage range for + in_altvoltage0_mag_rising_reset_min. diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem index 46cfe02058fd..34ee8c59ab25 100644 --- a/Documentation/ABI/testing/sysfs-bus-papr-pmem +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem @@ -8,7 +8,7 @@ Description: more bits set in the dimm-health-bitmap retrieved in response to H_SCM_HEALTH hcall. The details of the bit flags returned in response to this hcall is available - at 'Documentation/powerpc/papr_hcalls.rst' . Below are + at 'Documentation/arch/powerpc/papr_hcalls.rst' . Below are the flags reported in this sysfs file: * "not_armed" diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index a44bfe020061..2b7108e21977 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -313,6 +313,15 @@ Description: Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per direction. Devices before USB 3.2 are single lane (tx_lanes = 1) +What: /sys/bus/usb/devices/.../typec +Date: November 2023 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Symlink to the USB Type-C partner device. USB Type-C partner + represents the component that communicates over the + Configuration Channel (CC signal on USB Type-C connectors and + cables) with the local port. + What: /sys/bus/usb/devices/usbX/bAlternateSetting Description: The current interface alternate setting number, in decimal. diff --git a/Documentation/ABI/testing/sysfs-bus-vdpa b/Documentation/ABI/testing/sysfs-bus-vdpa index 28a6111202ba..4da53878bff6 100644 --- a/Documentation/ABI/testing/sysfs-bus-vdpa +++ b/Documentation/ABI/testing/sysfs-bus-vdpa @@ -1,4 +1,4 @@ -What: /sys/bus/vdpa/driver_autoprobe +What: /sys/bus/vdpa/drivers_autoprobe Date: March 2020 Contact: virtualization@lists.linux-foundation.org Description: @@ -17,7 +17,7 @@ Description: Writing a device name to this file will cause the kernel binds devices to a compatible driver. - This can be useful when /sys/bus/vdpa/driver_autoprobe is + This can be useful when /sys/bus/vdpa/drivers_autoprobe is disabled. What: /sys/bus/vdpa/drivers/.../bind diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes index f205d39409a3..9c82c7b42ff8 100644 --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes @@ -383,6 +383,36 @@ Description: Note that any changes to this attribute requires a reboot for changes to take effect. +What: /sys/class/firmware-attributes/*/attributes/save_settings +Date: August 2023 +KernelVersion: 6.6 +Contact: Mark Pearson <mpearson-lenovo@squebb.ca> +Description: + On Lenovo platforms there is a limitation in the number of times an attribute can be + saved. This is an architectural limitation and it limits the number of attributes + that can be modified to 48. + A solution for this is instead of the attribute being saved after every modification, + to allow a user to bulk set the attributes, and then trigger a final save. This allows + unlimited attributes. + + Read the attribute to check what save mode is enabled (single or bulk). + E.g: + # cat /sys/class/firmware-attributes/thinklmi/attributes/save_settings + single + + Write the attribute with 'bulk' to enable bulk save mode. + Write the attribute with 'single' to enable saving, after every attribute set. + The default setting is single mode. + E.g: + # echo bulk > /sys/class/firmware-attributes/thinklmi/attributes/save_settings + + When in bulk mode write 'save' to trigger a save of all currently modified attributes. + Note, once a save has been triggered, in bulk mode, attributes can no longer be set and + will return a permissions error. This is to prevent users hitting the 48+ save limitation + (which requires entering the BIOS to clear the error condition) + E.g: + # echo save > /sys/class/firmware-attributes/thinklmi/attributes/save_settings + What: /sys/class/firmware-attributes/*/attributes/debug_cmd Date: July 2021 KernelVersion: 5.14 diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia index c4d46970c1cf..369b4ae8be5f 100644 --- a/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia +++ b/Documentation/ABI/testing/sysfs-class-led-driver-turris-omnia @@ -12,3 +12,17 @@ Description: (RW) On the front panel of the Turris Omnia router there is also able to change this setting from software. Format: %i + +What: /sys/class/leds/<led>/device/gamma_correction +Date: August 2023 +KernelVersion: 6.6 +Contact: Marek Behún <kabel@kernel.org> +Description: (RW) Newer versions of the microcontroller firmware of the + Turris Omnia router support gamma correction for the RGB LEDs. + This feature can be enabled/disabled by writing to this file. + + If the feature is not supported because the MCU firmware is too + old, the file always reads as 0, and writing to the file results + in the EOPNOTSUPP error. + + Format: %i diff --git a/Documentation/ABI/testing/sysfs-class-usb_power_delivery b/Documentation/ABI/testing/sysfs-class-usb_power_delivery index 1bf9d1d7902c..61d233c320ea 100644 --- a/Documentation/ABI/testing/sysfs-class-usb_power_delivery +++ b/Documentation/ABI/testing/sysfs-class-usb_power_delivery @@ -124,6 +124,13 @@ Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> Description: The voltage the supply supports in millivolts. +What: /sys/class/usb_power_delivery/.../source-capabilities/<position>:fixed_supply/peak_current +Date: October 2023 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + This file shows the value of the Fixed Power Source Peak Current + Capability field. + What: /sys/class/usb_power_delivery/.../source-capabilities/<position>:fixed_supply/maximum_current Date: May 2022 Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 7ecd5c8161a6..a1db6db47505 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -354,9 +354,6 @@ Description: Parameters for the CPU cache attributes - ReadWriteAllocate: both writeallocate and readallocate - attributes: - LEGACY used only on IA64 and is same as write_policy - coherency_line_size: the minimum amount of data in bytes that gets transferred from memory to cache diff --git a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc index a8ab58035c95..c12316dfd973 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc +++ b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc @@ -17,7 +17,7 @@ Description: Read only. Returns the firmware version of Intel MAX10 What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_address Date: January 2021 KernelVersion: 5.12 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the first MAC address in a block of sequential MAC addresses assigned to the board that is managed by the Intel MAX10 BMC. It is stored in @@ -28,7 +28,7 @@ Description: Read only. Returns the first MAC address in a block What: /sys/bus/.../drivers/intel-m10-bmc/.../mac_count Date: January 2021 KernelVersion: 5.12 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the number of sequential MAC addresses assigned to the board managed by the Intel MAX10 BMC. This value is stored in FLASH and is mirrored diff --git a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update index 0a41afe0ab4c..9051695d2211 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update +++ b/Documentation/ABI/testing/sysfs-driver-intel-m10-bmc-sec-update @@ -1,7 +1,7 @@ What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/sr_root_entry_hash Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the root entry hash for the static region if one is programmed, else it returns the string: "hash not programmed". This file is only @@ -11,7 +11,7 @@ Description: Read only. Returns the root entry hash for the static What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/pr_root_entry_hash Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the root entry hash for the partial reconfiguration region if one is programmed, else it returns the string: "hash not programmed". This file @@ -21,7 +21,7 @@ Description: Read only. Returns the root entry hash for the partial What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/bmc_root_entry_hash Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns the root entry hash for the BMC image if one is programmed, else it returns the string: "hash not programmed". This file is only visible if the @@ -31,7 +31,7 @@ Description: Read only. Returns the root entry hash for the BMC image What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/sr_canceled_csks Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns a list of indices for canceled code signing keys for the static region. The standard bitmap list format is used (e.g. "1,2-6,9"). @@ -39,7 +39,7 @@ Description: Read only. Returns a list of indices for canceled code What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/pr_canceled_csks Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns a list of indices for canceled code signing keys for the partial reconfiguration region. The standard bitmap list format is used (e.g. "1,2-6,9"). @@ -47,7 +47,7 @@ Description: Read only. Returns a list of indices for canceled code What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/bmc_canceled_csks Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns a list of indices for canceled code signing keys for the BMC. The standard bitmap list format is used (e.g. "1,2-6,9"). @@ -55,7 +55,7 @@ Description: Read only. Returns a list of indices for canceled code What: /sys/bus/platform/drivers/intel-m10bmc-sec-update/.../security/flash_count Date: Sep 2022 KernelVersion: 5.20 -Contact: Russ Weight <russell.h.weight@intel.com> +Contact: Peter Colberg <peter.colberg@intel.com> Description: Read only. Returns number of times the secure update staging area has been flashed. Format: "%u". diff --git a/Documentation/ABI/testing/sysfs-driver-qat b/Documentation/ABI/testing/sysfs-driver-qat index ef6d6c57105e..bbf329cf0d67 100644 --- a/Documentation/ABI/testing/sysfs-driver-qat +++ b/Documentation/ABI/testing/sysfs-driver-qat @@ -29,6 +29,8 @@ Description: (RW) Reports the current configuration of the QAT device. services * asym;sym: identical to sym;asym * dc: the device is configured for running compression services + * dcc: identical to dc but enables the dc chaining feature, + hash then compression. If this is not required chose dc * sym: the device is configured for running symmetric crypto services * asym: the device is configured for running asymmetric crypto @@ -93,3 +95,49 @@ Description: (RW) This configuration option provides a way to force the device i 0 This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat/rp2srv +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) This attribute provides a way for a user to query a + specific ring pair for the type of service that it is currently + configured for. + + When written to, the value is cached and used to perform the + read operation. Allowed values are in the range 0 to N-1, where + N is the max number of ring pairs supported by a device. This + can be queried using the attribute qat/num_rps. + + A read returns the service associated to the ring pair queried. + + The values are: + + * dc: the ring pair is configured for running compression services + * sym: the ring pair is configured for running symmetric crypto + services + * asym: the ring pair is configured for running asymmetric crypto + services + + Example usage:: + + # echo 1 > /sys/bus/pci/devices/<BDF>/qat/rp2srv + # cat /sys/bus/pci/devices/<BDF>/qat/rp2srv + sym + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat/num_rps +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RO) Returns the number of ring pairs that a single device has. + + Example usage:: + + # cat /sys/bus/pci/devices/<BDF>/qat/num_rps + 64 + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-driver-qat_ras b/Documentation/ABI/testing/sysfs-driver-qat_ras new file mode 100644 index 000000000000..176dea1e9c0a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-qat_ras @@ -0,0 +1,41 @@ +What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_correctable +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Reports the number of correctable errors detected by the device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_nonfatal +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Reports the number of non fatal errors detected by the device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_ras/errors_fatal +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (RO) Reports the number of fatal errors detected by the device. + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_ras/reset_error_counters +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: (WO) Write to resets all error counters of a device. + + The following example reports how to reset the counters:: + + # echo 1 > /sys/bus/pci/devices/<BDF>/qat_ras/reset_error_counters + # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_correctable + 0 + # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_nonfatal + 0 + # cat /sys/bus/pci/devices/<BDF>/qat_ras/errors_fatal + 0 + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-driver-qat_rl b/Documentation/ABI/testing/sysfs-driver-qat_rl new file mode 100644 index 000000000000..8c282ae3155d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-qat_rl @@ -0,0 +1,226 @@ +What: /sys/bus/pci/devices/<BDF>/qat_rl/sla_op +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (WO) This attribute is used to perform an operation on an SLA. + The supported operations are: add, update, rm, rm_all, and get. + + Input values must be filled through the associated attribute in + this group before a write to this file. + If the operation completes successfully, the associated + attributes will be updated. + The associated attributes are: cir, pir, srv, rp, and id. + + Supported operations: + + * add: Creates a new SLA with the provided inputs from user. + * Inputs: cir, pir, srv, and rp + * Output: id + + * get: Returns the configuration of the specified SLA in id attribute + * Inputs: id + * Outputs: cir, pir, srv, and rp + + * update: Updates the SLA with new values set in the following attributes + * Inputs: id, cir, and pir + + * rm: Removes the specified SLA in the id attribute. + * Inputs: id + + * rm_all: Removes all the configured SLAs. + * Inputs: None + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/rp +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) When read, reports the current assigned ring pairs for the + queried SLA. + When wrote to, configures the ring pairs associated to a new SLA. + + The value is a 64-bit bit mask and is written/displayed in hex. + Each bit of this mask represents a single ring pair i.e., + bit 1 == ring pair id 0; bit 3 == ring pair id 2. + + Selected ring pairs must to be assigned to a single service, + i.e. the one provided with the srv attribute. The service + assigned to a certain ring pair can be checked by querying + the attribute qat/rp2srv. + + The maximum number of ring pairs is 4 per SLA. + + Applicability in sla_op: + + * WRITE: add operation + * READ: get operation + + Example usage:: + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp + 0x5 + + ## Write + # echo 0x5 > /sys/bus/pci/devices/<BDF>/qat_rl/rp + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/id +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) If written to, the value is used to retrieve a particular + SLA and operate on it. + This is valid only for the following operations: update, rm, + and get. + A read of this attribute is only guaranteed to have correct data + after creation of an SLA. + + Applicability in sla_op: + + * WRITE: rm and update operations + * READ: add and get operations + + Example usage:: + + ## Read + ## Set attributes e.g. cir, pir, srv, etc + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/id + 4 + + ## Write + # echo 7 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp + 0x5 ## ring pair ID 0 and ring pair ID 2 + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/cir +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) Committed information rate (CIR). Rate guaranteed to be + achieved by a particular SLA. The value is expressed in + permille scale, i.e. 1000 refers to the maximum device + throughput for a selected service. + + After sending a "get" to sla_op, this will be populated with the + CIR for that queried SLA. + Write to this file before sending an "add/update" sla_op, to set + the SLA to the specified value. + + Applicability in sla_op: + + * WRITE: add and update operations + * READ: get operation + + Example usage:: + + ## Write + # echo 500 > /sys/bus/pci/devices/<BDF>/qat_rl/cir + # echo "add" /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/cir + 500 + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/pir +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) Peak information rate (PIR). The maximum rate that can be + achieved by that particular SLA. An SLA can reach a value + between CIR and PIR when the device is not fully utilized by + requests from other users (assigned to different SLAs). + + After sending a "get" to sla_op, this will be populated with the + PIR for that queried SLA. + Write to this file before sending an "add/update" sla_op, to set + the SLA to the specified value. + + Applicability in sla_op: + + * WRITE: add and update operations + * READ: get operation + + Example usage:: + + ## Write + # echo 750 > /sys/bus/pci/devices/<BDF>/qat_rl/pir + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/pir + 750 + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/srv +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) Service (SRV). Represents the service (sym, asym, dc) + associated to an SLA. + Can be written to or queried to set/show the SRV type for an SLA. + The SRV attribute is used to specify the SRV type before adding + an SLA. After an SLA is configured, reports the service + associated to that SLA. + + Applicability in sla_op: + + * WRITE: add and update operations + * READ: get operation + + Example usage:: + + ## Write + # echo "dc" > /sys/bus/pci/devices/<BDF>/qat_rl/srv + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/id + 4 + + ## Read + # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id + # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/srv + dc + + This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem +Date: January 2024 +KernelVersion: 6.7 +Contact: qat-linux@intel.com +Description: + (RW) This file will return the remaining capability for a + particular service/sla. This is the remaining value that a new + SLA can be set to or a current SLA can be increased with. + + Example usage:: + + # echo "asym" > /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem + # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem + 250 + # echo 250 > /sys/bus/pci/devices/<BDF>/qat_rl/cir + # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op + # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem + 0 + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries index fe0289c87768..b6c23807b804 100644 --- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries +++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries @@ -2,7 +2,7 @@ What: /sys/firmware/dmi/entries/ Date: February 2011 Contact: Mike Waychison <mikew@google.com> Description: - Many machines' firmware (x86 and ia64) export DMI / + Many machines' firmware (x86 and arm64) export DMI / SMBIOS tables to the operating system. Getting at this information is often valuable to userland, especially in cases where there are OEM extensions used. diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon index 420b30f09cf0..b35649a46a2f 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-damon +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -151,6 +151,13 @@ Contact: SeongJae Park <sj@kernel.org> Description: Writing to and reading from this file sets and gets the action of the scheme. +What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/apply_interval_us +Date: Sep 2023 +Contact: SeongJae Park <sj@kernel.org> +Description: Writing a value to this file sets the action apply interval of + the scheme in microseconds. Reading this file returns the + value. + What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min Date: Mar 2022 Contact: SeongJae Park <sj@kernel.org> diff --git a/Documentation/ABI/testing/sysfs-tty b/Documentation/ABI/testing/sysfs-tty index 820e412d38a8..895c47f05f6f 100644 --- a/Documentation/ABI/testing/sysfs-tty +++ b/Documentation/ABI/testing/sysfs-tty @@ -87,19 +87,22 @@ What: /sys/class/tty/ttyS<x>/close_delay Date: October 2012 Contact: Alan Cox <alan@linux.intel.com> Description: - Show the closing delay time for this port in ms. + Show the closing delay time for this port in centiseconds. - These sysfs values expose the TIOCGSERIAL interface via - sysfs rather than via ioctls. + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. What: /sys/class/tty/ttyS<x>/closing_wait Date: October 2012 Contact: Alan Cox <alan@linux.intel.com> Description: - Show the close wait time for this port in ms. + Show the close wait time for this port in centiseconds. - These sysfs values expose the TIOCGSERIAL interface via - sysfs rather than via ioctls. + Waiting forever is represented as 0. If waiting on close is + disabled then the value is 65535. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. What: /sys/class/tty/ttyS<x>/custom_divisor Date: October 2012 diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst index 0c7552a00c8c..42e1e78353f3 100644 --- a/Documentation/PCI/pci-error-recovery.rst +++ b/Documentation/PCI/pci-error-recovery.rst @@ -364,7 +364,7 @@ Note, however, not all failures are truly "permanent". Some are caused by over-heating, some by a poorly seated card. Many PCI error events are caused by software bugs, e.g. DMAs to wild addresses or bogus split transactions due to programming -errors. See the discussion in Documentation/powerpc/eeh-pci-error-recovery.rst +errors. See the discussion in Documentation/arch/powerpc/eeh-pci-error-recovery.rst for additional detail on real-life experience of the causes of software errors. @@ -404,7 +404,7 @@ That is, the recovery API only requires that: .. note:: Implementation details for the powerpc platform are discussed in - the file Documentation/powerpc/eeh-pci-error-recovery.rst + the file Documentation/arch/powerpc/eeh-pci-error-recovery.rst As of this writing, there is a growing list of device drivers with patches implementing error recovery. Not all of these patches are in diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst index 93d899d53258..414f8a2012d6 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst @@ -181,7 +181,7 @@ operations is carried out at several levels: of this wait (or series of waits, as the case may be) is to permit a concurrent CPU-hotplug operation to complete. #. In the case of RCU-sched, one of the last acts of an outgoing CPU is - to invoke ``rcu_report_dead()``, which reports a quiescent state for + to invoke ``rcutree_report_cpu_dead()``, which reports a quiescent state for that CPU. However, this is likely paranoia-induced redundancy. +-----------------------------------------------------------------------+ diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg index 7ac6f9269806..63eff867175a 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-registry.svg @@ -566,15 +566,6 @@ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_migrate_callbacks()</text> <text xml:space="preserve" - x="8335.4873" - y="5357.1006" - font-style="normal" - font-weight="bold" - font-size="192" - id="text202-7-9-6-0" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_migrate_callbacks()</text> - <text - xml:space="preserve" x="8768.4678" y="6224.9038" font-style="normal" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg index 7ddc094d7f28..d82a77d03d8c 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-fqs.svg @@ -1135,7 +1135,7 @@ font-weight="bold" font-size="192" id="text202-7-5-3-27-6-5" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_report_dead()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text> <text xml:space="preserve" x="3745.7725" @@ -1256,7 +1256,7 @@ font-style="normal" y="3679.27" x="-3804.9949" - xml:space="preserve">rcu_cpu_starting()</text> + xml:space="preserve">rcutree_report_cpu_starting()</text> <g style="fill:none;stroke-width:0.025in" id="g3107-7-5-0" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg index 069f6f8371c2..53e0dc2a2c79 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg @@ -1448,15 +1448,6 @@ style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_migrate_callbacks()</text> <text xml:space="preserve" - x="8335.4873" - y="5357.1006" - font-style="normal" - font-weight="bold" - font-size="192" - id="text202-7-9-6-0" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_migrate_callbacks()</text> - <text - xml:space="preserve" x="8768.4678" y="6224.9038" font-style="normal" @@ -3274,7 +3265,7 @@ font-weight="bold" font-size="192" id="text202-7-5-3-27-6-5" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_report_dead()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text> <text xml:space="preserve" x="3745.7725" @@ -3395,7 +3386,7 @@ font-style="normal" y="3679.27" x="-3804.9949" - xml:space="preserve">rcu_cpu_starting()</text> + xml:space="preserve">rcutree_report_cpu_starting()</text> <g style="fill:none;stroke-width:0.025in" id="g3107-7-5-0" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg index 2c9310ba29ba..4fa7506082bf 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-hotplug.svg @@ -607,7 +607,7 @@ font-weight="bold" font-size="192" id="text202-7-5-3-27-6" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_report_dead()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcutree_report_cpu_dead()</text> <text xml:space="preserve" x="3745.7725" @@ -728,7 +728,7 @@ font-style="normal" y="3679.27" x="-3804.9949" - xml:space="preserve">rcu_cpu_starting()</text> + xml:space="preserve">rcutree_report_cpu_starting()</text> <g style="fill:none;stroke-width:0.025in" id="g3107-7-5-0" diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index f3b605285a87..cccafdaa1f84 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -1955,12 +1955,12 @@ if offline CPUs block an RCU grace period for too long. An offline CPU's quiescent state will be reported either: -1. As the CPU goes offline using RCU's hotplug notifier (rcu_report_dead()). +1. As the CPU goes offline using RCU's hotplug notifier (rcutree_report_cpu_dead()). 2. When grace period initialization (rcu_gp_init()) detects a race either with CPU offlining or with a task unblocking on a leaf ``rcu_node`` structure whose CPUs are all offline. -The CPU-online path (rcu_cpu_starting()) should never need to report +The CPU-online path (rcutree_report_cpu_starting()) should never need to report a quiescent state for an offline CPU. However, as a debugging measure, it does emit a warning if a quiescent state was not already reported for that CPU. diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst index bdc4bcc5289f..ed5c9d8c9afe 100644 --- a/Documentation/RCU/listRCU.rst +++ b/Documentation/RCU/listRCU.rst @@ -8,6 +8,15 @@ One of the most common uses of RCU is protecting read-mostly linked lists that all of the required memory ordering is provided by the list macros. This document describes several list-based RCU use cases. +When iterating a list while holding the rcu_read_lock(), writers may +modify the list. The reader is guaranteed to see all of the elements +which were added to the list before they acquired the rcu_read_lock() +and are still on the list when they drop the rcu_read_unlock(). +Elements which are added to, or removed from the list may or may not +be seen. If the writer calls list_replace_rcu(), the reader may see +either the old element or the new element; they will not see both, +nor will they see neither. + Example 1: Read-mostly list: Deferred Destruction ------------------------------------------------- diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index e488c8e557a9..60ce02475142 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -59,8 +59,8 @@ experiment with should focus on Section 2. People who prefer to start with example uses should focus on Sections 3 and 4. People who need to understand the RCU implementation should focus on Section 5, then dive into the kernel source code. People who reason best by analogy should -focus on Section 6. Section 7 serves as an index to the docbook API -documentation, and Section 8 is the traditional answer key. +focus on Section 6 and 7. Section 8 serves as an index to the docbook +API documentation, and Section 9 is the traditional answer key. So, start with the section that makes the most sense to you and your preferred method of learning. If you need to know everything about diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index ff456871bf4b..ca7d9402f6be 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -551,6 +551,7 @@ memory.stat file includes following statistics: event happens each time a page is unaccounted from the cgroup. swap # of bytes of swap usage + swapcached # of bytes of swap cached in memory dirty # of bytes that are waiting to get written back to the disk. writeback # of bytes of file/anon cache that are queued for syncing to disk. diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index b26b5274eaaf..3f85254f3cef 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -210,6 +210,35 @@ cgroup v2 currently supports the following mount options. relying on the original semantics (e.g. specifying bogusly high 'bypass' protection values at higher tree levels). + memory_hugetlb_accounting + Count HugeTLB memory usage towards the cgroup's overall + memory usage for the memory controller (for the purpose of + statistics reporting and memory protetion). This is a new + behavior that could regress existing setups, so it must be + explicitly opted in with this mount option. + + A few caveats to keep in mind: + + * There is no HugeTLB pool management involved in the memory + controller. The pre-allocated pool does not belong to anyone. + Specifically, when a new HugeTLB folio is allocated to + the pool, it is not accounted for from the perspective of the + memory controller. It is only charged to a cgroup when it is + actually used (for e.g at page fault time). Host memory + overcommit management has to consider this when configuring + hard limits. In general, HugeTLB pool management should be + done via other mechanisms (such as the HugeTLB controller). + * Failure to charge a HugeTLB folio to the memory controller + results in SIGBUS. This could happen even if the HugeTLB pool + still has pages available (but the cgroup limit is hit and + reclaim attempt fails). + * Charging HugeTLB memory towards the memory controller affects + memory protection and reclaim dynamics. Any userspace tuning + (of low, min limits for e.g) needs to take this into account. + * HugeTLB pages utilized while this option is not selected + will not be tracked by the memory controller (even if cgroup + v2 is remounted later on). + Organizing Processes and Threads -------------------------------- @@ -364,6 +393,13 @@ constraint, a threaded controller must be able to handle competition between threads in a non-leaf cgroup and its child cgroups. Each threaded controller defines how such competitions are handled. +Currently, the following controllers are threaded and can be enabled +in a threaded cgroup:: + +- cpu +- cpuset +- perf_event +- pids [Un]populated Notification -------------------------- @@ -1532,6 +1568,15 @@ PAGE_SIZE multiple when read back. collapsing an existing range of pages. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE is not set. + thp_swpout (npn) + Number of transparent hugepages which are swapout in one piece + without splitting. + + thp_swpout_fallback (npn) + Number of transparent hugepages which were split before swapout. + Usually because failed to allocate some continuous swap space + for the huge page. + memory.numa_stat A read-only nested-keyed file which exists on non-root cgroups. @@ -2023,7 +2068,7 @@ IO Priority ~~~~~~~~~~~ A single attribute controls the behavior of the I/O priority cgroup policy, -namely the blkio.prio.class attribute. The following values are accepted for +namely the io.prio.class attribute. The following values are accepted for that attribute: no-change @@ -2052,9 +2097,11 @@ The following numerical values are associated with the I/O priority policies: +----------------+---+ | no-change | 0 | +----------------+---+ -| rt-to-be | 2 | +| promote-to-rt | 1 | +----------------+---+ -| all-to-idle | 3 | +| restrict-to-be | 2 | ++----------------+---+ +| idle | 3 | +----------------+---+ The numerical value that corresponds to each I/O priority class is as follows: @@ -2074,7 +2121,7 @@ The algorithm to set the I/O priority class for a request is as follows: - If I/O priority class policy is promote-to-rt, change the request I/O priority class to IOPRIO_CLASS_RT and change the request I/O priority level to 4. -- If I/O priorityt class is not promote-to-rt, translate the I/O priority +- If I/O priority class policy is not promote-to-rt, translate the I/O priority class policy into a number, then change the request I/O priority class into the maximum of the I/O priority class policy number and the numerical I/O priority class. @@ -2226,6 +2273,49 @@ Cpuset Interface Files Its value will be affected by memory nodes hotplug events. + cpuset.cpus.exclusive + A read-write multiple values file which exists on non-root + cpuset-enabled cgroups. + + It lists all the exclusive CPUs that are allowed to be used + to create a new cpuset partition. Its value is not used + unless the cgroup becomes a valid partition root. See the + "cpuset.cpus.partition" section below for a description of what + a cpuset partition is. + + When the cgroup becomes a partition root, the actual exclusive + CPUs that are allocated to that partition are listed in + "cpuset.cpus.exclusive.effective" which may be different + from "cpuset.cpus.exclusive". If "cpuset.cpus.exclusive" + has previously been set, "cpuset.cpus.exclusive.effective" + is always a subset of it. + + Users can manually set it to a value that is different from + "cpuset.cpus". The only constraint in setting it is that the + list of CPUs must be exclusive with respect to its sibling. + + For a parent cgroup, any one of its exclusive CPUs can only + be distributed to at most one of its child cgroups. Having an + exclusive CPU appearing in two or more of its child cgroups is + not allowed (the exclusivity rule). A value that violates the + exclusivity rule will be rejected with a write error. + + The root cgroup is a partition root and all its available CPUs + are in its exclusive CPU set. + + cpuset.cpus.exclusive.effective + A read-only multiple values file which exists on all non-root + cpuset-enabled cgroups. + + This file shows the effective set of exclusive CPUs that + can be used to create a partition root. The content of this + file will always be a subset of "cpuset.cpus" and its parent's + "cpuset.cpus.exclusive.effective" if its parent is not the root + cgroup. It will also be a subset of "cpuset.cpus.exclusive" + if it is set. If "cpuset.cpus.exclusive" is not set, it is + treated to have an implicit value of "cpuset.cpus" in the + formation of local partition. + cpuset.cpus.partition A read-write single value file which exists on non-root cpuset-enabled cgroups. This flag is owned by the parent cgroup @@ -2239,26 +2329,41 @@ Cpuset Interface Files "isolated" Partition root without load balancing ========== ===================================== - The root cgroup is always a partition root and its state - cannot be changed. All other non-root cgroups start out as - "member". + A cpuset partition is a collection of cpuset-enabled cgroups with + a partition root at the top of the hierarchy and its descendants + except those that are separate partition roots themselves and + their descendants. A partition has exclusive access to the + set of exclusive CPUs allocated to it. Other cgroups outside + of that partition cannot use any CPUs in that set. + + There are two types of partitions - local and remote. A local + partition is one whose parent cgroup is also a valid partition + root. A remote partition is one whose parent cgroup is not a + valid partition root itself. Writing to "cpuset.cpus.exclusive" + is optional for the creation of a local partition as its + "cpuset.cpus.exclusive" file will assume an implicit value that + is the same as "cpuset.cpus" if it is not set. Writing the + proper "cpuset.cpus.exclusive" values down the cgroup hierarchy + before the target partition root is mandatory for the creation + of a remote partition. + + Currently, a remote partition cannot be created under a local + partition. All the ancestors of a remote partition root except + the root cgroup cannot be a partition root. + + The root cgroup is always a partition root and its state cannot + be changed. All other non-root cgroups start out as "member". When set to "root", the current cgroup is the root of a new - partition or scheduling domain that comprises itself and all - its descendants except those that are separate partition roots - themselves and their descendants. + partition or scheduling domain. The set of exclusive CPUs is + determined by the value of its "cpuset.cpus.exclusive.effective". - When set to "isolated", the CPUs in that partition root will + When set to "isolated", the CPUs in that partition will be in an isolated state without any load balancing from the scheduler. Tasks placed in such a partition with multiple CPUs should be carefully distributed and bound to each of the individual CPUs for optimal performance. - The value shown in "cpuset.cpus.effective" of a partition root - is the CPUs that the partition root can dedicate to a potential - new child partition root. The new child subtracts available - CPUs from its parent "cpuset.cpus.effective". - A partition root ("root" or "isolated") can be in one of the two possible states - valid or invalid. An invalid partition root is in a degraded state where some state information may @@ -2281,37 +2386,33 @@ Cpuset Interface Files In the case of an invalid partition root, a descriptive string on why the partition is invalid is included within parentheses. - For a partition root to become valid, the following conditions + For a local partition root to be valid, the following conditions must be met. - 1) The "cpuset.cpus" is exclusive with its siblings , i.e. they - are not shared by any of its siblings (exclusivity rule). - 2) The parent cgroup is a valid partition root. - 3) The "cpuset.cpus" is not empty and must contain at least - one of the CPUs from parent's "cpuset.cpus", i.e. they overlap. - 4) The "cpuset.cpus.effective" cannot be empty unless there is + 1) The parent cgroup is a valid partition root. + 2) The "cpuset.cpus.exclusive.effective" file cannot be empty, + though it may contain offline CPUs. + 3) The "cpuset.cpus.effective" cannot be empty unless there is no task associated with this partition. - External events like hotplug or changes to "cpuset.cpus" can - cause a valid partition root to become invalid and vice versa. - Note that a task cannot be moved to a cgroup with empty - "cpuset.cpus.effective". + For a remote partition root to be valid, all the above conditions + except the first one must be met. - For a valid partition root with the sibling cpu exclusivity - rule enabled, changes made to "cpuset.cpus" that violate the - exclusivity rule will invalidate the partition as well as its - sibling partitions with conflicting cpuset.cpus values. So - care must be taking in changing "cpuset.cpus". + External events like hotplug or changes to "cpuset.cpus" or + "cpuset.cpus.exclusive" can cause a valid partition root to + become invalid and vice versa. Note that a task cannot be + moved to a cgroup with empty "cpuset.cpus.effective". A valid non-root parent partition may distribute out all its CPUs - to its child partitions when there is no task associated with it. + to its child local partitions when there is no task associated + with it. - Care must be taken to change a valid partition root to - "member" as all its child partitions, if present, will become + Care must be taken to change a valid partition root to "member" + as all its child local partitions, if present, will become invalid causing disruption to tasks running in those child partitions. These inactivated partitions could be recovered if their parent is switched back to a partition root with a proper - set of "cpuset.cpus". + value in "cpuset.cpus" or "cpuset.cpus.exclusive". Poll and inotify events are triggered whenever the state of "cpuset.cpus.partition" changes. That includes changes caused @@ -2321,6 +2422,11 @@ Cpuset Interface Files to "cpuset.cpus.partition" without the need to do continuous polling. + A user can pre-configure certain CPUs to an isolated state + with load balancing disabled at boot time with the "isolcpus" + kernel boot command line option. If those CPUs are to be put + into a partition, they have to be used in an isolated partition. + Device controller ----------------- diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 0b3d39c610d9..0c526dac8428 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -259,7 +259,7 @@ Debug Messages at Module Initialization Time When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for ``foo.params``, strips ``foo.``, and passes them to the kernel along with -params given in modprobe args or ``/etc/modprob.d/*.conf`` files, +params given in modprobe args or ``/etc/modprobe.d/*.conf`` files, in the following order: 1. parameters given via ``/etc/modprobe.d/*.conf``:: diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst index b24e7c40d832..090f3a185e18 100644 --- a/Documentation/admin-guide/efi-stub.rst +++ b/Documentation/admin-guide/efi-stub.rst @@ -15,7 +15,7 @@ between architectures is in drivers/firmware/efi/libstub. For arm64, there is no compressed kernel support, so the Image itself masquerades as a PE/COFF image and the EFI stub is linked into the -kernel. The arm64 EFI stub lives in arch/arm64/kernel/efi-entry.S +kernel. The arm64 EFI stub lives in drivers/firmware/efi/libstub/arm64.c and drivers/firmware/efi/libstub/arm64-stub.c. By using the EFI boot stub it's possible to boot a Linux kernel diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst index 48ca0bd85604..48c7b0b72aed 100644 --- a/Documentation/admin-guide/hw-vuln/mds.rst +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -102,9 +102,19 @@ The possible values in this file are: * - 'Vulnerable' - The processor is vulnerable, but no mitigation enabled * - 'Vulnerable: Clear CPU buffers attempted, no microcode' - - The processor is vulnerable but microcode is not updated. - - The mitigation is enabled on a best effort basis. See :ref:`vmwerv` + - The processor is vulnerable but microcode is not updated. The + mitigation is enabled on a best effort basis. + + If the processor is vulnerable but the availability of the microcode + based mitigation mechanism is not advertised via CPUID, the kernel + selects a best effort mitigation mode. This mode invokes the mitigation + instructions without a guarantee that they clear the CPU buffers. + + This is done to address virtualization scenarios where the host has the + microcode update applied, but the hypervisor is not yet updated to + expose the CPUID to the guest. If the host has updated microcode the + protection takes effect; otherwise a few CPU cycles are wasted + pointlessly. * - 'Mitigation: Clear CPU buffers' - The processor is vulnerable and the CPU buffer clearing mitigation is enabled. @@ -119,24 +129,6 @@ to the above information: 'SMT Host state unknown' Kernel runs in a VM, Host SMT state unknown ======================== ============================================ -.. _vmwerv: - -Best effort mitigation mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - If the processor is vulnerable, but the availability of the microcode based - mitigation mechanism is not advertised via CPUID the kernel selects a best - effort mitigation mode. This mode invokes the mitigation instructions - without a guarantee that they clear the CPU buffers. - - This is done to address virtualization scenarios where the host has the - microcode update applied, but the hypervisor is not yet updated to expose - the CPUID to the guest. If the host has updated microcode the protection - takes effect otherwise a few cpu cycles are wasted pointlessly. - - The state in the mds sysfs file reflects this situation accordingly. - - Mitigation mechanism ------------------------- diff --git a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst index c98fd11907cc..1302fd1b55e8 100644 --- a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst +++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst @@ -225,8 +225,19 @@ The possible values in this file are: * - 'Vulnerable' - The processor is vulnerable, but no mitigation enabled * - 'Vulnerable: Clear CPU buffers attempted, no microcode' - - The processor is vulnerable, but microcode is not updated. The + - The processor is vulnerable but microcode is not updated. The mitigation is enabled on a best effort basis. + + If the processor is vulnerable but the availability of the microcode + based mitigation mechanism is not advertised via CPUID, the kernel + selects a best effort mitigation mode. This mode invokes the mitigation + instructions without a guarantee that they clear the CPU buffers. + + This is done to address virtualization scenarios where the host has the + microcode update applied, but the hypervisor is not yet updated to + expose the CPUID to the guest. If the host has updated microcode the + protection takes effect; otherwise a few CPU cycles are wasted + pointlessly. * - 'Mitigation: Clear CPU buffers' - The processor is vulnerable and the CPU buffer clearing mitigation is enabled. diff --git a/Documentation/admin-guide/hw-vuln/srso.rst b/Documentation/admin-guide/hw-vuln/srso.rst index b6cfb51cb0b4..e715bfc09879 100644 --- a/Documentation/admin-guide/hw-vuln/srso.rst +++ b/Documentation/admin-guide/hw-vuln/srso.rst @@ -46,12 +46,22 @@ The possible values in this file are: The processor is not vulnerable - * 'Vulnerable: no microcode': +* 'Vulnerable': + + The processor is vulnerable and no mitigations have been applied. + + * 'Vulnerable: No microcode': The processor is vulnerable, no microcode extending IBPB functionality to address the vulnerability has been applied. - * 'Mitigation: microcode': + * 'Vulnerable: Safe RET, no microcode': + + The "Safe RET" mitigation (see below) has been applied to protect the + kernel, but the IBPB-extending microcode has not been applied. User + space tasks may still be vulnerable. + + * 'Vulnerable: Microcode, no safe RET': Extended IBPB functionality microcode patch has been applied. It does not address User->Kernel and Guest->Host transitions protection but it @@ -72,11 +82,11 @@ The possible values in this file are: (spec_rstack_overflow=microcode) - * 'Mitigation: safe RET': + * 'Mitigation: Safe RET': - Software-only mitigation. It complements the extended IBPB microcode - patch functionality by addressing User->Kernel and Guest->Host - transitions protection. + Combined microcode/software mitigation. It complements the + extended IBPB microcode patch functionality by addressing + User->Kernel and Guest->Host transitions protection. Selected by default or by spec_rstack_overflow=safe-ret @@ -129,7 +139,7 @@ an indrect branch prediction barrier after having applied the required microcode patch for one's system. This mitigation comes also at a performance cost. -Mitigation: safe RET +Mitigation: Safe RET -------------------- The mitigation works by ensuring all RET instructions speculate to diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst index 014167ef8dd1..444f84e22a91 100644 --- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst +++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst @@ -98,7 +98,19 @@ The possible values in this file are: * - 'Vulnerable' - The CPU is affected by this vulnerability and the microcode and kernel mitigation are not applied. * - 'Vulnerable: Clear CPU buffers attempted, no microcode' - - The system tries to clear the buffers but the microcode might not support the operation. + - The processor is vulnerable but microcode is not updated. The + mitigation is enabled on a best effort basis. + + If the processor is vulnerable but the availability of the microcode + based mitigation mechanism is not advertised via CPUID, the kernel + selects a best effort mitigation mode. This mode invokes the mitigation + instructions without a guarantee that they clear the CPU buffers. + + This is done to address virtualization scenarios where the host has the + microcode update applied, but the hypervisor is not yet updated to + expose the CPUID to the guest. If the host has updated microcode the + protection takes effect; otherwise a few CPU cycles are wasted + pointlessly. * - 'Mitigation: Clear CPU buffers' - The microcode has been updated to clear the buffers. TSX is still enabled. * - 'Mitigation: TSX disabled' @@ -106,25 +118,6 @@ The possible values in this file are: * - 'Not affected' - The CPU is not affected by this issue. -.. _ucode_needed: - -Best effort mitigation mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the processor is vulnerable, but the availability of the microcode-based -mitigation mechanism is not advertised via CPUID the kernel selects a best -effort mitigation mode. This mode invokes the mitigation instructions -without a guarantee that they clear the CPU buffers. - -This is done to address virtualization scenarios where the host has the -microcode update applied, but the hypervisor is not yet updated to expose the -CPUID to the guest. If the host has updated microcode the protection takes -effect; otherwise a few CPU cycles are wasted pointlessly. - -The state in the tsx_async_abort sysfs file reflects this situation -accordingly. - - Mitigation mechanism -------------------- diff --git a/Documentation/admin-guide/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst index a748e7eb4429..5762e7477a0c 100644 --- a/Documentation/admin-guide/kdump/kdump.rst +++ b/Documentation/admin-guide/kdump/kdump.rst @@ -17,7 +17,7 @@ You can use common commands, such as cp, scp or makedumpfile to copy the memory image to a dump file on the local disk, or across the network to a remote system. -Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64, +Kdump and kexec are currently supported on the x86, x86_64, ppc64, s390x, arm and arm64 architectures. When the system kernel boots, it reserves a small section of memory for @@ -113,7 +113,7 @@ There are two possible methods of using Kdump. 2) Or use the system kernel binary itself as dump-capture kernel and there is no need to build a separate dump-capture kernel. This is possible only with the architectures which support a relocatable kernel. As - of today, i386, x86_64, ppc64, ia64, arm and arm64 architectures support + of today, i386, x86_64, ppc64, arm and arm64 architectures support relocatable kernel. Building a relocatable kernel is advantageous from the point of view that @@ -236,24 +236,6 @@ Dump-capture kernel config options (Arch Dependent, ppc64) Make and install the kernel and its modules. -Dump-capture kernel config options (Arch Dependent, ia64) ----------------------------------------------------------- - -- No specific options are required to create a dump-capture kernel - for ia64, other than those specified in the arch independent section - above. This means that it is possible to use the system kernel - as a dump-capture kernel if desired. - - The crashkernel region can be automatically placed by the system - kernel at runtime. This is done by specifying the base address as 0, - or omitting it all together:: - - crashkernel=256M@0 - - or:: - - crashkernel=256M - Dump-capture kernel config options (Arch Dependent, arm) ---------------------------------------------------------- @@ -348,11 +330,6 @@ Boot into System Kernel On ppc64, use "crashkernel=128M@32M". - On ia64, 256M@256M is a generous value that typically works. - The region may be automatically placed on ia64, see the - dump-capture kernel config option notes above. - If use sparse memory, the size should be rounded to GRANULE boundaries. - On s390x, typically use "crashkernel=xxM". The value of xx is dependent on the memory consumption of the kdump system. In general this is not dependent on the memory size of the production system. @@ -383,10 +360,6 @@ For ppc64: - Use vmlinux -For ia64: - - - Use vmlinux or vmlinuz.gz - For s390x: - Use image or bzImage @@ -428,14 +401,10 @@ to load dump-capture kernel:: --initrd=<initrd-for-dump-capture-kernel> \ --append="root=<root-dev> <arch-specific-options>" -Please note, that --args-linux does not need to be specified for ia64. -It is planned to make this a no-op on that architecture, but for now -it should be omitted - Following are the arch specific command line options to be used while loading dump-capture kernel. -For i386, x86_64 and ia64: +For i386 and x86_64: "1 irqpoll nr_cpus=1 reset_devices" diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index 599e8d3bcbc3..78e4d2e7ba14 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -413,36 +413,6 @@ of a higher page table lookup overhead, and also consumes more page table space per process. Used to check whether PAE was enabled in the crash kernel when converting virtual addresses to physical addresses. -ia64 -==== - -pgdat_list|(pgdat_list, MAX_NUMNODES) -------------------------------------- - -pg_data_t array storing all NUMA nodes information. MAX_NUMNODES -indicates the number of the nodes. - -node_memblk|(node_memblk, NR_NODE_MEMBLKS) ------------------------------------------- - -List of node memory chunks. Filled when parsing the SRAT table to obtain -information about memory nodes. NR_NODE_MEMBLKS indicates the number of -node memory chunks. - -These values are used to compute the number of nodes the crashed kernel used. - -node_memblk_s|(node_memblk_s, start_paddr)|(node_memblk_s, size) ----------------------------------------------------------------- - -The size of a struct node_memblk_s and the offsets of the -node_memblk_s's members. Used to compute the number of nodes. - -PGTABLE_3|PGTABLE_4 -------------------- - -User-space tools need to know whether the crash kernel was in 3-level or -4-level paging mode. Used to distinguish the page table. - ARM64 ===== diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 0a1731a0f0ef..2a4bc78c27ec 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -580,6 +580,10 @@ named mounts. Specifying both "all" and "named" disables all v1 hierarchies. + cgroup_favordynmods= [KNL] Enable or Disable favordynmods. + Format: { "true" | "false" } + Defaults to the value of CONFIG_CGROUP_FAVOR_DYNMODS. + cgroup.memory= [KNL] Pass options to the cgroup memory controller. Format: <string> nosocket -- Disable socket memory accounting. @@ -1331,6 +1335,7 @@ earlyprintk=dbgp[debugController#] earlyprintk=pciserial[,force],bus:device.function[,baudrate] earlyprintk=xdbc[xhciController#] + earlyprintk=bios earlyprintk is useful when the kernel crashes before the normal console is initialized. It is not enabled by @@ -1361,6 +1366,8 @@ The sclp output can only be used on s390. + The bios output can only be used on SuperH. + The optional "force" to "pciserial" enables use of a PCI device even when its classcode is not of the UART class. @@ -1449,7 +1456,7 @@ See comment before function elanfreq_setup() in arch/x86/kernel/cpu/cpufreq/elanfreq.c. - elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] + elfcorehdr=[size[KMG]@]offset[KMG] [PPC,SH,X86,S390] Specifies physical address of start of kernel core image elf header and optionally the size. Generally kexec loader will pass this option to capture kernel. @@ -1512,12 +1519,6 @@ floppy= [HW] See Documentation/admin-guide/blockdev/floppy.rst. - force_pal_cache_flush - [IA-64] Avoid check_sal_cache_flush which may hang on - buggy SAL_CACHE_FLUSH implementations. Using this - parameter will force ia64_sal_cache_flush to call - ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. - forcepae [X86-32] Forcefully enable Physical Address Extension (PAE). Many Pentium M systems disable PAE but may have a @@ -1893,6 +1894,12 @@ 0 -- machine default 1 -- force brightness inversion + ia32_emulation= [X86-64] + Format: <bool> + When true, allows loading 32-bit programs and executing 32-bit + syscalls, essentially overriding IA32_EMULATION_DEFAULT_DISABLED at + boot time. When false, unconditionally disables IA32 emulation. + icn= [HW,ISDN] Format: <io>[,<membase>[,<icn_id>[,<icn_id2>]]] @@ -2913,6 +2920,38 @@ to extract confidential information from the kernel are also disabled. + locktorture.acq_writer_lim= [KNL] + Set the time limit in jiffies for a lock + acquisition. Acquisitions exceeding this limit + will result in a splat once they do complete. + + locktorture.bind_readers= [KNL] + Specify the list of CPUs to which the readers are + to be bound. + + locktorture.bind_writers= [KNL] + Specify the list of CPUs to which the writers are + to be bound. + + locktorture.call_rcu_chains= [KNL] + Specify the number of self-propagating call_rcu() + chains to set up. These are used to ensure that + there is a high probability of an RCU grace period + in progress at any given time. Defaults to 0, + which disables these call_rcu() chains. + + locktorture.long_hold= [KNL] + Specify the duration in milliseconds for the + occasional long-duration lock hold time. Defaults + to 100 milliseconds. Select 0 to disable. + + locktorture.nested_locks= [KNL] + Specify the maximum lock nesting depth that + locktorture is to exercise, up to a limit of 8 + (MAX_NESTED_LOCKS). Specify zero to disable. + Note that this parameter is ineffective on types + of locks that do not support nested acquisition. + locktorture.nreaders_stress= [KNL] Set the number of locking read-acquisition kthreads. Defaults to being automatically set based on the @@ -2928,6 +2967,25 @@ Set time (s) between CPU-hotplug operations, or zero to disable CPU-hotplug testing. + locktorture.rt_boost= [KNL] + Do periodic testing of real-time lock priority + boosting. Select 0 to disable, 1 to boost + only rt_mutex, and 2 to boost unconditionally. + Defaults to 2, which might seem to be an + odd choice, but which should be harmless for + non-real-time spinlocks, due to their disabling + of preemption. Note that non-realtime mutexes + disable boosting. + + locktorture.rt_boost_factor= [KNL] + Number that determines how often and for how + long priority boosting is exercised. This is + scaled down by the number of writers, so that the + number of boosts per unit time remains roughly + constant as the number of writers increases. + On the other hand, the duration of each boost + increases with the number of writers. + locktorture.shuffle_interval= [KNL] Set task-shuffle interval (jiffies). Shuffling tasks allows some CPUs to go into dyntick-idle @@ -2950,13 +3008,13 @@ locktorture.torture_type= [KNL] Specify the locking implementation to test. + locktorture.verbose= [KNL] + Enable additional printk() statements. + locktorture.writer_fifo= [KNL] Run the write-side locktorture kthreads at sched_set_fifo() real-time priority. - locktorture.verbose= [KNL] - Enable additional printk() statements. - logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver Format: <irq> @@ -3275,6 +3333,11 @@ mga= [HW,DRM] + microcode.force_minrev= [X86] + Format: <bool> + Enable or disable the microcode minimal revision + enforcement for the runtime microcode loader. + min_addr=nn[KMG] [KNL,BOOT,IA-64] All physical memory below this physical address is ignored. @@ -4769,6 +4832,13 @@ Set maximum number of finished RCU callbacks to process in one batch. + rcutree.do_rcu_barrier= [KNL] + Request a call to rcu_barrier(). This is + throttled so that userspace tests can safely + hammer on the sysfs variable if they so choose. + If triggered before the RCU grace-period machinery + is fully active, this will error out with EAGAIN. + rcutree.dump_tree= [KNL] Dump the structure of the rcu_node combining tree out at early boot. This is used for diagnostic @@ -5422,6 +5492,12 @@ test until boot completes in order to avoid interference. + refscale.lookup_instances= [KNL] + Number of data elements to use for the forms of + SLAB_TYPESAFE_BY_RCU testing. A negative number + is negated and multiplied by nr_cpu_ids, while + zero specifies nr_cpu_ids. + refscale.loops= [KNL] Set the number of loops over the synchronization primitive under test. Increasing this number @@ -5858,6 +5934,13 @@ This feature may be more efficiently disabled using the csdlock_debug- kernel parameter. + smp.panic_on_ipistall= [KNL] + If a csd_lock_timeout extends for more than + the specified number of milliseconds, panic the + system. By default, let CSD-lock acquisition + take as long as they take. Specifying 300,000 + for this value provides a 5-minute timeout. + smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port smsc-ircc2.ircc_sir= [HW] SIR base I/O port diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index e27a1c3f634e..98d304010170 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -53,6 +53,7 @@ detailed description): - Lap mode sensor - Setting keyboard language - WWAN Antenna type + - Auxmac A compatibility table by model and feature is maintained on the web site, http://ibm-acpi.sf.net/. I appreciate any success or failure @@ -1511,6 +1512,25 @@ Currently 2 antenna types are supported as mentioned below: The property is read-only. If the platform doesn't have support the sysfs class is not created. +Auxmac +------ + +sysfs: auxmac + +Some newer Thinkpads have a feature called MAC Address Pass-through. This +feature is implemented by the system firmware to provide a system unique MAC, +that can override a dock or USB ethernet dongle MAC, when connected to a +network. This property enables user-space to easily determine the MAC address +if the feature is enabled. + +The values of this auxiliary MAC are: + + cat /sys/devices/platform/thinkpad_acpi/auxmac + +If the feature is disabled, the value will be 'disabled'. + +This property is read-only. + Adaptive keyboard ----------------- diff --git a/Documentation/admin-guide/media/mgb4.rst b/Documentation/admin-guide/media/mgb4.rst new file mode 100644 index 000000000000..2977f74d7e26 --- /dev/null +++ b/Documentation/admin-guide/media/mgb4.rst @@ -0,0 +1,374 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +mgb4 sysfs interface +==================== + +The mgb4 driver provides a sysfs interface, that is used to configure video +stream related parameters (some of them must be set properly before the v4l2 +device can be opened) and obtain the video device/stream status. + +There are two types of parameters - global / PCI card related, found under +``/sys/class/video4linux/videoX/device`` and module specific found under +``/sys/class/video4linux/videoX``. + + +Global (PCI card) parameters +============================ + +**module_type** (R): + Module type. + + | 0 - No module present + | 1 - FPDL3 + | 2 - GMSL + +**module_version** (R): + Module version number. Zero in case of a missing module. + +**fw_type** (R): + Firmware type. + + | 1 - FPDL3 + | 2 - GMSL + +**fw_version** (R): + Firmware version number. + +**serial_number** (R): + Card serial number. The format is:: + + PRODUCT-REVISION-SERIES-SERIAL + + where each component is a 8b number. + + +Common FPDL3/GMSL input parameters +================================== + +**input_id** (R): + Input number ID, zero based. + +**oldi_lane_width** (RW): + Number of deserializer output lanes. + + | 0 - single + | 1 - dual (default) + +**color_mapping** (RW): + Mapping of the incoming bits in the signal to the colour bits of the pixels. + + | 0 - OLDI/JEIDA + | 1 - SPWG/VESA (default) + +**link_status** (R): + Video link status. If the link is locked, chips are properly connected and + communicating at the same speed and protocol. The link can be locked without + an active video stream. + + A value of 0 is equivalent to the V4L2_IN_ST_NO_SYNC flag of the V4L2 + VIDIOC_ENUMINPUT status bits. + + | 0 - unlocked + | 1 - locked + +**stream_status** (R): + Video stream status. A stream is detected if the link is locked, the input + pixel clock is running and the DE signal is moving. + + A value of 0 is equivalent to the V4L2_IN_ST_NO_SIGNAL flag of the V4L2 + VIDIOC_ENUMINPUT status bits. + + | 0 - not detected + | 1 - detected + +**video_width** (R): + Video stream width. This is the actual width as detected by the HW. + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in the width + field of the v4l2_bt_timings struct. + +**video_height** (R): + Video stream height. This is the actual height as detected by the HW. + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in the height + field of the v4l2_bt_timings struct. + +**vsync_status** (R): + The type of VSYNC pulses as detected by the video format detector. + + The value is equivalent to the flags returned by VIDIOC_QUERY_DV_TIMINGS in + the polarities field of the v4l2_bt_timings struct. + + | 0 - active low + | 1 - active high + | 2 - not available + +**hsync_status** (R): + The type of HSYNC pulses as detected by the video format detector. + + The value is equivalent to the flags returned by VIDIOC_QUERY_DV_TIMINGS in + the polarities field of the v4l2_bt_timings struct. + + | 0 - active low + | 1 - active high + | 2 - not available + +**vsync_gap_length** (RW): + If the incoming video signal does not contain synchronization VSYNC and + HSYNC pulses, these must be generated internally in the FPGA to achieve + the correct frame ordering. This value indicates, how many "empty" pixels + (pixels with deasserted Data Enable signal) are necessary to generate the + internal VSYNC pulse. + +**hsync_gap_length** (RW): + If the incoming video signal does not contain synchronization VSYNC and + HSYNC pulses, these must be generated internally in the FPGA to achieve + the correct frame ordering. This value indicates, how many "empty" pixels + (pixels with deasserted Data Enable signal) are necessary to generate the + internal HSYNC pulse. The value must be greater than 1 and smaller than + vsync_gap_length. + +**pclk_frequency** (R): + Input pixel clock frequency in kHz. + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in + the pixelclock field of the v4l2_bt_timings struct. + + *Note: The frequency_range parameter must be set properly first to get + a valid frequency here.* + +**hsync_width** (R): + Width of the HSYNC signal in PCLK clock ticks. + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in + the hsync field of the v4l2_bt_timings struct. + +**vsync_width** (R): + Width of the VSYNC signal in PCLK clock ticks. + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in + the vsync field of the v4l2_bt_timings struct. + +**hback_porch** (R): + Number of PCLK pulses between deassertion of the HSYNC signal and the first + valid pixel in the video line (marked by DE=1). + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in + the hbackporch field of the v4l2_bt_timings struct. + +**hfront_porch** (R): + Number of PCLK pulses between the end of the last valid pixel in the video + line (marked by DE=1) and assertion of the HSYNC signal. + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in + the hfrontporch field of the v4l2_bt_timings struct. + +**vback_porch** (R): + Number of video lines between deassertion of the VSYNC signal and the video + line with the first valid pixel (marked by DE=1). + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in + the vbackporch field of the v4l2_bt_timings struct. + +**vfront_porch** (R): + Number of video lines between the end of the last valid pixel line (marked + by DE=1) and assertion of the VSYNC signal. + + The value is identical to what VIDIOC_QUERY_DV_TIMINGS returns in + the vfrontporch field of the v4l2_bt_timings struct. + +**frequency_range** (RW) + PLL frequency range of the OLDI input clock generator. The PLL frequency is + derived from the Pixel Clock Frequency (PCLK) and is equal to PCLK if + oldi_lane_width is set to "single" and PCLK/2 if oldi_lane_width is set to + "dual". + + | 0 - PLL < 50MHz (default) + | 1 - PLL >= 50MHz + + *Note: This parameter can not be changed while the input v4l2 device is + open.* + + +Common FPDL3/GMSL output parameters +=================================== + +**output_id** (R): + Output number ID, zero based. + +**video_source** (RW): + Output video source. If set to 0 or 1, the source is the corresponding card + input and the v4l2 output devices are disabled. If set to 2 or 3, the source + is the corresponding v4l2 video output device. The default is + the corresponding v4l2 output, i.e. 2 for OUT1 and 3 for OUT2. + + | 0 - input 0 + | 1 - input 1 + | 2 - v4l2 output 0 + | 3 - v4l2 output 1 + + *Note: This parameter can not be changed while ANY of the input/output v4l2 + devices is open.* + +**display_width** (RW): + Display width. There is no autodetection of the connected display, so the + proper value must be set before the start of streaming. The default width + is 1280. + + *Note: This parameter can not be changed while the output v4l2 device is + open.* + +**display_height** (RW): + Display height. There is no autodetection of the connected display, so the + proper value must be set before the start of streaming. The default height + is 640. + + *Note: This parameter can not be changed while the output v4l2 device is + open.* + +**frame_rate** (RW): + Output video frame rate in frames per second. The default frame rate is + 60Hz. + +**hsync_polarity** (RW): + HSYNC signal polarity. + + | 0 - active low (default) + | 1 - active high + +**vsync_polarity** (RW): + VSYNC signal polarity. + + | 0 - active low (default) + | 1 - active high + +**de_polarity** (RW): + DE signal polarity. + + | 0 - active low + | 1 - active high (default) + +**pclk_frequency** (RW): + Output pixel clock frequency. Allowed values are between 25000-190000(kHz) + and there is a non-linear stepping between two consecutive allowed + frequencies. The driver finds the nearest allowed frequency to the given + value and sets it. When reading this property, you get the exact + frequency set by the driver. The default frequency is 70000kHz. + + *Note: This parameter can not be changed while the output v4l2 device is + open.* + +**hsync_width** (RW): + Width of the HSYNC signal in pixels. The default value is 16. + +**vsync_width** (RW): + Width of the VSYNC signal in video lines. The default value is 2. + +**hback_porch** (RW): + Number of PCLK pulses between deassertion of the HSYNC signal and the first + valid pixel in the video line (marked by DE=1). The default value is 32. + +**hfront_porch** (RW): + Number of PCLK pulses between the end of the last valid pixel in the video + line (marked by DE=1) and assertion of the HSYNC signal. The default value + is 32. + +**vback_porch** (RW): + Number of video lines between deassertion of the VSYNC signal and the video + line with the first valid pixel (marked by DE=1). The default value is 2. + +**vfront_porch** (RW): + Number of video lines between the end of the last valid pixel line (marked + by DE=1) and assertion of the VSYNC signal. The default value is 2. + + +FPDL3 specific input parameters +=============================== + +**fpdl3_input_width** (RW): + Number of deserializer input lines. + + | 0 - auto (default) + | 1 - single + | 2 - dual + +FPDL3 specific output parameters +================================ + +**fpdl3_output_width** (RW): + Number of serializer output lines. + + | 0 - auto (default) + | 1 - single + | 2 - dual + +GMSL specific input parameters +============================== + +**gmsl_mode** (RW): + GMSL speed mode. + + | 0 - 12Gb/s (default) + | 1 - 6Gb/s + | 2 - 3Gb/s + | 3 - 1.5Gb/s + +**gmsl_stream_id** (RW): + The GMSL multi-stream contains up to four video streams. This parameter + selects which stream is captured by the video input. The value is the + zero-based index of the stream. The default stream id is 0. + + *Note: This parameter can not be changed while the input v4l2 device is + open.* + +**gmsl_fec** (RW): + GMSL Forward Error Correction (FEC). + + | 0 - disabled + | 1 - enabled (default) + + +==================== +mgb4 mtd partitions +==================== + +The mgb4 driver creates a MTD device with two partitions: + - mgb4-fw.X - FPGA firmware. + - mgb4-data.X - Factory settings, e.g. card serial number. + +The *mgb4-fw* partition is writable and is used for FW updates, *mgb4-data* is +read-only. The *X* attached to the partition name represents the card number. +Depending on the CONFIG_MTD_PARTITIONED_MASTER kernel configuration, you may +also have a third partition named *mgb4-flash* available in the system. This +partition represents the whole, unpartitioned, card's FLASH memory and one should +not fiddle with it... + +==================== +mgb4 iio (triggers) +==================== + +The mgb4 driver creates an Industrial I/O (IIO) device that provides trigger and +signal level status capability. The following scan elements are available: + +**activity**: + The trigger levels and pending status. + + | bit 1 - trigger 1 pending + | bit 2 - trigger 2 pending + | bit 5 - trigger 1 level + | bit 6 - trigger 2 level + +**timestamp**: + The trigger event timestamp. + +The iio device can operate either in "raw" mode where you can fetch the signal +levels (activity bits 5 and 6) using sysfs access or in triggered buffer mode. +In the triggered buffer mode you can follow the signal level changes (activity +bits 1 and 2) using the iio device in /dev. If you enable the timestamps, you +will also get the exact trigger event time that can be matched to a video frame +(every mgb4 video frame has a timestamp with the same clock source). + +*Note: although the activity sample always contains all the status bits, it makes +no sense to get the pending bits in raw mode or the level bits in the triggered +buffer mode - the values do not represent valid data in such case.* diff --git a/Documentation/admin-guide/media/pci-cardlist.rst b/Documentation/admin-guide/media/pci-cardlist.rst index 42528795d4da..7d8e3c8987db 100644 --- a/Documentation/admin-guide/media/pci-cardlist.rst +++ b/Documentation/admin-guide/media/pci-cardlist.rst @@ -77,6 +77,7 @@ ipu3-cio2 Intel ipu3-cio2 driver ivtv Conexant cx23416/cx23415 MPEG encoder/decoder ivtvfb Conexant cx23415 framebuffer mantis MANTIS based cards +mgb4 Digiteq Automotive MGB4 frame grabber mxb Siemens-Nixdorf 'Multimedia eXtension Board' netup-unidvb NetUP Universal DVB card ngene Micronas nGene diff --git a/Documentation/admin-guide/media/v4l-drivers.rst b/Documentation/admin-guide/media/v4l-drivers.rst index 1c41f87c3917..61283d67ceef 100644 --- a/Documentation/admin-guide/media/v4l-drivers.rst +++ b/Documentation/admin-guide/media/v4l-drivers.rst @@ -17,6 +17,7 @@ Video4Linux (V4L) driver-specific documentation imx7 ipu3 ivtv + mgb4 omap3isp omap4_camera philips diff --git a/Documentation/admin-guide/media/visl.rst b/Documentation/admin-guide/media/visl.rst index 7d2dc78341c9..4328c6c72d30 100644 --- a/Documentation/admin-guide/media/visl.rst +++ b/Documentation/admin-guide/media/visl.rst @@ -78,7 +78,7 @@ The trace events are defined on a per-codec basis, e.g.: .. code-block:: bash - $ ls /sys/kernel/debug/tracing/events/ | grep visl + $ ls /sys/kernel/tracing/events/ | grep visl visl_fwht_controls visl_h264_controls visl_hevc_controls @@ -90,13 +90,13 @@ For example, in order to dump HEVC SPS data: .. code-block:: bash - $ echo 1 > /sys/kernel/debug/tracing/events/visl_hevc_controls/v4l2_ctrl_hevc_sps/enable + $ echo 1 > /sys/kernel/tracing/events/visl_hevc_controls/v4l2_ctrl_hevc_sps/enable The SPS data will be dumped to the trace buffer, i.e.: .. code-block:: bash - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace video_parameter_set_id 0 seq_parameter_set_id 0 pic_width_in_luma_samples 1920 diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index 8da1b7281827..da94feb97ed1 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -20,18 +20,18 @@ DAMON provides below interfaces for different users. you can write and use your personalized DAMON sysfs wrapper programs that reads/writes the sysfs files instead of you. The `DAMON user space tool <https://github.com/awslabs/damo>`_ is one example of such programs. -- *debugfs interface. (DEPRECATED!)* - :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface - <sysfs_interface>`. This is deprecated, so users should move to the - :ref:`sysfs interface <sysfs_interface>`. If you depend on this and cannot - move, please report your usecase to damon@lists.linux.dev and - linux-mm@kvack.org. - *Kernel Space Programming Interface.* :doc:`This </mm/damon/api>` is for kernel space programmers. Using this, users can utilize every feature of DAMON most flexibly and efficiently by writing kernel space DAMON application programs for you. You can even extend DAMON for various address spaces. For detail, please refer to the interface :doc:`document </mm/damon/api>`. +- *debugfs interface. (DEPRECATED!)* + :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface + <sysfs_interface>`. This is deprecated, so users should move to the + :ref:`sysfs interface <sysfs_interface>`. If you depend on this and cannot + move, please report your usecase to damon@lists.linux.dev and + linux-mm@kvack.org. .. _sysfs_interface: @@ -76,7 +76,7 @@ comma (","). :: │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ │ schemes/nr_schemes - │ │ │ │ │ │ 0/action + │ │ │ │ │ │ 0/action,apply_interval_us │ │ │ │ │ │ │ access_pattern/ │ │ │ │ │ │ │ │ sz/min,max │ │ │ │ │ │ │ │ nr_accesses/min,max @@ -105,14 +105,12 @@ having the root permission could use this directory. kdamonds/ --------- -The monitoring-related information including request specifications and results -are called DAMON context. DAMON executes each context with a kernel thread -called kdamond, and multiple kdamonds could run in parallel. - Under the ``admin`` directory, one directory, ``kdamonds``, which has files for -controlling the kdamonds exist. In the beginning, this directory has only one -file, ``nr_kdamonds``. Writing a number (``N``) to the file creates the number -of child directories named ``0`` to ``N-1``. Each directory represents each +controlling the kdamonds (refer to +:ref:`design <damon_design_execution_model_and_data_structures>` for more +details) exists. In the beginning, this directory has only one file, +``nr_kdamonds``. Writing a number (``N``) to the file creates the number of +child directories named ``0`` to ``N-1``. Each directory represents each kdamond. kdamonds/<N>/ @@ -150,9 +148,10 @@ kdamonds/<N>/contexts/ In the beginning, this directory has only one file, ``nr_contexts``. Writing a number (``N``) to the file creates the number of child directories named as -``0`` to ``N-1``. Each directory represents each monitoring context. At the -moment, only one context per kdamond is supported, so only ``0`` or ``1`` can -be written to the file. +``0`` to ``N-1``. Each directory represents each monitoring context (refer to +:ref:`design <damon_design_execution_model_and_data_structures>` for more +details). At the moment, only one context per kdamond is supported, so only +``0`` or ``1`` can be written to the file. .. _sysfs_contexts: @@ -270,8 +269,8 @@ schemes/<N>/ ------------ In each scheme directory, five directories (``access_pattern``, ``quotas``, -``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and one file -(``action``) exist. +``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and two files +(``action`` and ``apply_interval``) exist. The ``action`` file is for setting and getting the scheme's :ref:`action <damon_design_damos_action>`. The keywords that can be written to and read @@ -297,6 +296,9 @@ Note that support of each action depends on the running DAMON operations set - ``stat``: Do nothing but count the statistics. Supported by all operations sets. +The ``apply_interval_us`` file is for setting and getting the scheme's +:ref:`apply_interval <damon_design_damos>` in microseconds. + schemes/<N>/access_pattern/ --------------------------- @@ -392,7 +394,7 @@ pages of all memory cgroups except ``/having_care_already``.:: echo N > 1/matching Note that ``anon`` and ``memcg`` filters are currently supported only when -``paddr`` `implementation <sysfs_contexts>` is being used. +``paddr`` :ref:`implementation <sysfs_contexts>` is being used. Also, memory regions that are filtered out by ``addr`` or ``target`` filters are not counted as the scheme has tried to those, while regions that filtered @@ -430,9 +432,9 @@ that reading it returns the total size of the scheme tried regions, and creates directories named integer starting from ``0`` under this directory. Each directory contains files exposing detailed information about each of the memory region that the corresponding scheme's ``action`` has tried to be applied under -this directory, during next :ref:`aggregation interval -<sysfs_monitoring_attrs>`. The information includes address range, -``nr_accesses``, and ``age`` of the region. +this directory, during next :ref:`apply interval <damon_design_damos>` of the +corresponding scheme. The information includes address range, ``nr_accesses``, +and ``age`` of the region. Writing ``update_schemes_tried_bytes`` to the relevant ``kdamonds/<N>/state`` file will only update the ``total_bytes`` file, and will not create the @@ -495,6 +497,62 @@ Please note that it's highly recommended to use user space tools like `damo <https://github.com/awslabs/damo>`_ rather than manually reading and writing the files as above. Above is only for an example. +.. _tracepoint: + +Tracepoints for Monitoring Results +================================== + +Users can get the monitoring results via the :ref:`tried_regions +<sysfs_schemes_tried_regions>`. The interface is useful for getting a +snapshot, but it could be inefficient for fully recording all the monitoring +results. For the purpose, two trace points, namely ``damon:damon_aggregated`` +and ``damon:damos_before_apply``, are provided. ``damon:damon_aggregated`` +provides the whole monitoring results, while ``damon:damos_before_apply`` +provides the monitoring results for regions that each DAMON-based Operation +Scheme (:ref:`DAMOS <damon_design_damos>`) is gonna be applied. Hence, +``damon:damos_before_apply`` is more useful for recording internal behavior of +DAMOS, or DAMOS target access +:ref:`pattern <damon_design_damos_access_pattern>` based query-like efficient +monitoring results recording. + +While the monitoring is turned on, you could record the tracepoint events and +show results using tracepoint supporting tools like ``perf``. For example:: + + # echo on > monitor_on + # perf record -e damon:damon_aggregated & + # sleep 5 + # kill 9 $(pidof perf) + # echo off > monitor_on + # perf script + kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864 + [...] + +Each line of the perf script output represents each monitoring region. The +first five fields are as usual other tracepoint outputs. The sixth field +(``target_id=X``) shows the ide of the monitoring target of the region. The +seventh field (``nr_regions=X``) shows the total number of monitoring regions +for the target. The eighth field (``X-Y:``) shows the start (``X``) and end +(``Y``) addresses of the region in bytes. The ninth field (``X``) shows the +``nr_accesses`` of the region (refer to +:ref:`design <damon_design_region_based_sampling>` for more details of the +counter). Finally the tenth field (``X``) shows the ``age`` of the region +(refer to :ref:`design <damon_design_age_tracking>` for more details of the +counter). + +If the event was ``damon:damos_beofre_apply``, the ``perf script`` output would +be somewhat like below:: + + kdamond.0 47293 [000] 80801.060214: damon:damos_before_apply: ctx_idx=0 scheme_idx=0 target_idx=0 nr_regions=11 121932607488-135128711168: 0 136 + [...] + +Each line of the output represents each monitoring region that each DAMON-based +Operation Scheme was about to be applied at the traced time. The first five +fields are as usual. It shows the index of the DAMON context (``ctx_idx=X``) +of the scheme in the list of the contexts of the context's kdamond, the index +of the scheme (``scheme_idx=X``) in the list of the schemes of the context, in +addition to the output of ``damon_aggregated`` tracepoint. + + .. _debugfs_interface: debugfs Interface (DEPRECATED!) @@ -790,23 +848,3 @@ directory by putting the name of the context to the ``rm_contexts`` file. :: Note that ``mk_contexts``, ``rm_contexts``, and ``monitor_on`` files are in the root directory only. - - -.. _tracepoint: - -Tracepoint for Monitoring Results -================================= - -Users can get the monitoring results via the :ref:`tried_regions -<sysfs_schemes_tried_regions>` or a tracepoint, ``damon:damon_aggregated``. -While the tried regions directory is useful for getting a snapshot, the -tracepoint is useful for getting a full record of the results. While the -monitoring is turned on, you could record the tracepoint events and show -results using tracepoint supporting tools like ``perf``. For example:: - - # echo on > monitor_on - # perf record -e damon:damon_aggregated & - # sleep 5 - # kill 9 $(pidof perf) - # echo off > monitor_on - # perf script diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index 776f244bdae4..e59231ac6bb7 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -155,6 +155,15 @@ stable_node_chains_prune_millisecs scan. It's a noop if not a single KSM page hit the ``max_page_sharing`` yet. +smart_scan + Historically KSM checked every candidate page for each scan. It did + not take into account historic information. When smart scan is + enabled, pages that have previously not been de-duplicated get + skipped. How often these pages are skipped depends on how often + de-duplication has already been tried and failed. By default this + optimization is enabled. The ``pages_skipped`` metric shows how + effective the setting is. + The effectiveness of KSM and MADV_MERGEABLE is shown in ``/sys/kernel/mm/ksm/``: general_profit @@ -169,6 +178,8 @@ pages_unshared how many pages unique but repeatedly checked for merging pages_volatile how many pages changing too fast to be placed in a tree +pages_skipped + how many pages did the "smart" page scanning algorithm skip full_scans how many times all mergeable areas have been scanned stable_node_chains diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index cfe034cf1e87..098f14d83e99 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -33,7 +33,7 @@ used to expose persistent memory, other performance-differentiated memory and reserved memory regions as ordinary system RAM to Linux. Linux only supports memory hot(un)plug on selected 64 bit architectures, such as -x86_64, arm64, ppc64, s390x and ia64. +x86_64, arm64, ppc64 and s390x. Memory Hot(Un)Plug Granularity ------------------------------ @@ -75,7 +75,7 @@ Memory hotunplug consists of two phases: (1) Offlining memory blocks (2) Removing the memory from Linux -In the fist phase, memory is "hidden" from the page allocator again, for +In the first phase, memory is "hidden" from the page allocator again, for example, by migrating busy memory to other memory locations and removing all relevant free pages from the page allocator After this phase, the memory is no longer visible in memory statistics of the system. @@ -250,15 +250,15 @@ Observing the State of Memory Blocks The state (online/offline/going-offline) of a memory block can be observed either via:: - % cat /sys/device/system/memory/memoryXXX/state + % cat /sys/devices/system/memory/memoryXXX/state Or alternatively (1/0) via:: - % cat /sys/device/system/memory/memoryXXX/online + % cat /sys/devices/system/memory/memoryXXX/online For an online memory block, the managing zone can be observed via:: - % cat /sys/device/system/memory/memoryXXX/valid_zones + % cat /sys/devices/system/memory/memoryXXX/valid_zones Configuring Memory Hot(Un)Plug ============================== @@ -326,7 +326,7 @@ however, a memory block might span memory holes. A memory block spanning memory holes cannot be offlined. For example, assume 1 GiB memory block size. A device for a memory starting at -0x100000000 is ``/sys/device/system/memory/memory4``:: +0x100000000 is ``/sys/devices/system/memory/memory4``:: (0x100000000 / 1Gib = 4) diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst index c8f380271cad..fe17cf210426 100644 --- a/Documentation/admin-guide/mm/pagemap.rst +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -227,3 +227,92 @@ Before Linux 3.11 pagemap bits 55-60 were used for "page-shift" (which is always 12 at most architectures). Since Linux 3.11 their meaning changes after first clear of soft-dirty bits. Since Linux 4.2 they are used for flags unconditionally. + +Pagemap Scan IOCTL +================== + +The ``PAGEMAP_SCAN`` IOCTL on the pagemap file can be used to get or optionally +clear the info about page table entries. The following operations are supported +in this IOCTL: + +- Scan the address range and get the memory ranges matching the provided criteria. + This is performed when the output buffer is specified. +- Write-protect the pages. The ``PM_SCAN_WP_MATCHING`` is used to write-protect + the pages of interest. The ``PM_SCAN_CHECK_WPASYNC`` aborts the operation if + non-Async Write Protected pages are found. The ``PM_SCAN_WP_MATCHING`` can be + used with or without ``PM_SCAN_CHECK_WPASYNC``. +- Both of those operations can be combined into one atomic operation where we can + get and write protect the pages as well. + +Following flags about pages are currently supported: + +- ``PAGE_IS_WPALLOWED`` - Page has async-write-protection enabled +- ``PAGE_IS_WRITTEN`` - Page has been written to from the time it was write protected +- ``PAGE_IS_FILE`` - Page is file backed +- ``PAGE_IS_PRESENT`` - Page is present in the memory +- ``PAGE_IS_SWAPPED`` - Page is in swapped +- ``PAGE_IS_PFNZERO`` - Page has zero PFN +- ``PAGE_IS_HUGE`` - Page is THP or Hugetlb backed + +The ``struct pm_scan_arg`` is used as the argument of the IOCTL. + + 1. The size of the ``struct pm_scan_arg`` must be specified in the ``size`` + field. This field will be helpful in recognizing the structure if extensions + are done later. + 2. The flags can be specified in the ``flags`` field. The ``PM_SCAN_WP_MATCHING`` + and ``PM_SCAN_CHECK_WPASYNC`` are the only added flags at this time. The get + operation is optionally performed depending upon if the output buffer is + provided or not. + 3. The range is specified through ``start`` and ``end``. + 4. The walk can abort before visiting the complete range such as the user buffer + can get full etc. The walk ending address is specified in``end_walk``. + 5. The output buffer of ``struct page_region`` array and size is specified in + ``vec`` and ``vec_len``. + 6. The optional maximum requested pages are specified in the ``max_pages``. + 7. The masks are specified in ``category_mask``, ``category_anyof_mask``, + ``category_inverted`` and ``return_mask``. + +Find pages which have been written and WP them as well:: + + struct pm_scan_arg arg = { + .size = sizeof(arg), + .flags = PM_SCAN_CHECK_WPASYNC | PM_SCAN_CHECK_WPASYNC, + .. + .category_mask = PAGE_IS_WRITTEN, + .return_mask = PAGE_IS_WRITTEN, + }; + +Find pages which have been written, are file backed, not swapped and either +present or huge:: + + struct pm_scan_arg arg = { + .size = sizeof(arg), + .flags = 0, + .. + .category_mask = PAGE_IS_WRITTEN | PAGE_IS_SWAPPED, + .category_inverted = PAGE_IS_SWAPPED, + .category_anyof_mask = PAGE_IS_PRESENT | PAGE_IS_HUGE, + .return_mask = PAGE_IS_WRITTEN | PAGE_IS_SWAPPED | + PAGE_IS_PRESENT | PAGE_IS_HUGE, + }; + +The ``PAGE_IS_WRITTEN`` flag can be considered as a better-performing alternative +of soft-dirty flag. It doesn't get affected by VMA merging of the kernel and hence +the user can find the true soft-dirty pages in case of normal pages. (There may +still be extra dirty pages reported for THP or Hugetlb pages.) + +"PAGE_IS_WRITTEN" category is used with uffd write protect-enabled ranges to +implement memory dirty tracking in userspace: + + 1. The userfaultfd file descriptor is created with ``userfaultfd`` syscall. + 2. The ``UFFD_FEATURE_WP_UNPOPULATED`` and ``UFFD_FEATURE_WP_ASYNC`` features + are set by ``UFFDIO_API`` IOCTL. + 3. The memory range is registered with ``UFFDIO_REGISTER_MODE_WP`` mode + through ``UFFDIO_REGISTER`` IOCTL. + 4. Then any part of the registered memory or the whole memory region must + be write protected using ``PAGEMAP_SCAN`` IOCTL with flag ``PM_SCAN_WP_MATCHING`` + or the ``UFFDIO_WRITEPROTECT`` IOCTL can be used. Both of these perform the + same operation. The former is better in terms of performance. + 5. Now the ``PAGEMAP_SCAN`` IOCTL can be used to either just find pages which + have been written to since they were last marked and/or optionally write protect + the pages as well. diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst index 4349a8c2b978..203e26da5f92 100644 --- a/Documentation/admin-guide/mm/userfaultfd.rst +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -244,6 +244,41 @@ write-protected (so future writes will also result in a WP fault). These ioctls support a mode flag (``UFFDIO_COPY_MODE_WP`` or ``UFFDIO_CONTINUE_MODE_WP`` respectively) to configure the mapping this way. +If the userfaultfd context has ``UFFD_FEATURE_WP_ASYNC`` feature bit set, +any vma registered with write-protection will work in async mode rather +than the default sync mode. + +In async mode, there will be no message generated when a write operation +happens, meanwhile the write-protection will be resolved automatically by +the kernel. It can be seen as a more accurate version of soft-dirty +tracking and it can be different in a few ways: + + - The dirty result will not be affected by vma changes (e.g. vma + merging) because the dirty is only tracked by the pte. + + - It supports range operations by default, so one can enable tracking on + any range of memory as long as page aligned. + + - Dirty information will not get lost if the pte was zapped due to + various reasons (e.g. during split of a shmem transparent huge page). + + - Due to a reverted meaning of soft-dirty (page clean when uffd-wp bit + set; dirty when uffd-wp bit cleared), it has different semantics on + some of the memory operations. For example: ``MADV_DONTNEED`` on + anonymous (or ``MADV_REMOVE`` on a file mapping) will be treated as + dirtying of memory by dropping uffd-wp bit during the procedure. + +The user app can collect the "written/dirty" status by looking up the +uffd-wp bit for the pages being interested in /proc/pagemap. + +The page will not be under track of uffd-wp async mode until the page is +explicitly write-protected by ``ioctl(UFFDIO_WRITEPROTECT)`` with the mode +flag ``UFFDIO_WRITEPROTECT_MODE_WP`` set. Trying to resolve a page fault +that was tracked by async mode userfaultfd-wp is invalid. + +When userfaultfd-wp async mode is used alone, it can be applied to all +kinds of memory. + Memory Poisioning Emulation --------------------------- diff --git a/Documentation/admin-guide/module-signing.rst b/Documentation/admin-guide/module-signing.rst index 2898b2703297..a8667a777490 100644 --- a/Documentation/admin-guide/module-signing.rst +++ b/Documentation/admin-guide/module-signing.rst @@ -28,10 +28,10 @@ trusted userspace bits. This facility uses X.509 ITU-T standard certificates to encode the public keys involved. The signatures are not themselves encoded in any industrial standard -type. The facility currently only supports the RSA public key encryption -standard (though it is pluggable and permits others to be used). The possible -hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and -SHA-512 (the algorithm is selected by data in the signature). +type. The built-in facility currently only supports the RSA & NIST P-384 ECDSA +public key signing standard (though it is pluggable and permits others to be +used). The possible hash algorithms that can be used are SHA-2 and SHA-3 of +sizes 256, 384, and 512 (the algorithm is selected by data in the signature). ========================== @@ -81,11 +81,12 @@ This has a number of options available: sign the modules with: =============================== ========================================== - ``CONFIG_MODULE_SIG_SHA1`` :menuselection:`Sign modules with SHA-1` - ``CONFIG_MODULE_SIG_SHA224`` :menuselection:`Sign modules with SHA-224` ``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256` ``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384` ``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512` + ``CONFIG_MODULE_SIG_SHA3_256`` :menuselection:`Sign modules with SHA3-256` + ``CONFIG_MODULE_SIG_SHA3_384`` :menuselection:`Sign modules with SHA3-384` + ``CONFIG_MODULE_SIG_SHA3_512`` :menuselection:`Sign modules with SHA3-512` =============================== ========================================== The algorithm selected here will also be built into the kernel (rather @@ -145,6 +146,10 @@ into vmlinux) using parameters in the:: file (which is also generated if it does not already exist). +One can select between RSA (``MODULE_SIG_KEY_TYPE_RSA``) and ECDSA +(``MODULE_SIG_KEY_TYPE_ECDSA``) to generate either RSA 4k or NIST +P-384 keypair. + It is strongly recommended that you provide your own x509.genkey file. Most notably, in the x509.genkey file, the req_distinguished_name section diff --git a/Documentation/admin-guide/perf/ampere_cspmu.rst b/Documentation/admin-guide/perf/ampere_cspmu.rst new file mode 100644 index 000000000000..94f93f5aee6c --- /dev/null +++ b/Documentation/admin-guide/perf/ampere_cspmu.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================ +Ampere SoC Performance Monitoring Unit (PMU) +============================================ + +Ampere SoC PMU is a generic PMU IP that follows Arm CoreSight PMU architecture. +Therefore, the driver is implemented as a submodule of arm_cspmu driver. At the +first phase it's used for counting MCU events on AmpereOne. + + +MCU PMU events +-------------- + +The PMU driver supports setting filters for "rank", "bank", and "threshold". +Note, that the filters are per PMU instance rather than per event. + + +Example for perf tool use:: + + / # perf list ampere + + ampere_mcu_pmu_0/act_sent/ [Kernel PMU event] + <...> + ampere_mcu_pmu_1/rd_sent/ [Kernel PMU event] + <...> + + / # perf stat -a -e ampere_mcu_pmu_0/act_sent,bank=5,rank=3,threshold=2/,ampere_mcu_pmu_1/rd_sent/ \ + sleep 1 diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index f60be04e4e33..a2e6f2c81146 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -22,3 +22,4 @@ Performance monitor support nvidia-pmu meson-ddr-pmu cxl + ampere_cspmu diff --git a/Documentation/admin-guide/pm/intel_idle.rst b/Documentation/admin-guide/pm/intel_idle.rst index b799a43da62e..39bd6ecce7de 100644 --- a/Documentation/admin-guide/pm/intel_idle.rst +++ b/Documentation/admin-guide/pm/intel_idle.rst @@ -170,7 +170,7 @@ and ``idle=nomwait``. If any of them is present in the kernel command line, the ``MWAIT`` instruction is not allowed to be used, so the initialization of ``intel_idle`` will fail. -Apart from that there are four module parameters recognized by ``intel_idle`` +Apart from that there are five module parameters recognized by ``intel_idle`` itself that can be set via the kernel command line (they cannot be updated via sysfs, so that is the only way to change their values). @@ -216,6 +216,21 @@ are ignored). The idle states disabled this way can be enabled (on a per-CPU basis) from user space via ``sysfs``. +The ``ibrs_off`` module parameter is a boolean flag (defaults to +false). If set, it is used to control if IBRS (Indirect Branch Restricted +Speculation) should be turned off when the CPU enters an idle state. +This flag does not affect CPUs that use Enhanced IBRS which can remain +on with little performance impact. + +For some CPUs, IBRS will be selected as mitigation for Spectre v2 and Retbleed +security vulnerabilities by default. Leaving the IBRS mode on while idling may +have a performance impact on its sibling CPU. The IBRS mode will be turned off +by default when the CPU enters into a deep idle state, but not in some +shallower ones. Setting the ``ibrs_off`` module parameter will force the IBRS +mode to off when the CPU is in any one of the available idle states. This may +help performance of a sibling CPU at the expense of a slightly higher wakeup +latency for the idle CPU. + .. _intel-idle-core-and-package-idle-states: diff --git a/Documentation/admin-guide/pstore-blk.rst b/Documentation/admin-guide/pstore-blk.rst index 2d22ead9520e..1bb2a1c292aa 100644 --- a/Documentation/admin-guide/pstore-blk.rst +++ b/Documentation/admin-guide/pstore-blk.rst @@ -76,7 +76,7 @@ kmsg_size ~~~~~~~~~ The chunk size in KB for oops/panic front-end. It **MUST** be a multiple of 4. -It's optional if you do not care oops/panic log. +It's optional if you do not care about the oops/panic log. There are multiple chunks for oops/panic front-end depending on the remaining space except other pstore front-ends. @@ -88,7 +88,7 @@ pmsg_size ~~~~~~~~~ The chunk size in KB for pmsg front-end. It **MUST** be a multiple of 4. -It's optional if you do not care pmsg log. +It's optional if you do not care about the pmsg log. Unlike oops/panic front-end, there is only one chunk for pmsg front-end. @@ -100,7 +100,7 @@ console_size ~~~~~~~~~~~~ The chunk size in KB for console front-end. It **MUST** be a multiple of 4. -It's optional if you do not care console log. +It's optional if you do not care about the console log. Similar to pmsg front-end, there is only one chunk for console front-end. @@ -111,7 +111,7 @@ ftrace_size ~~~~~~~~~~~ The chunk size in KB for ftrace front-end. It **MUST** be a multiple of 4. -It's optional if you do not care console log. +It's optional if you do not care about the ftrace log. Similar to oops front-end, there are multiple chunks for ftrace front-end depending on the count of cpu processors. Each chunk size is equal to diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt index 74ea7f391942..0d5965138f8f 100644 --- a/Documentation/admin-guide/spkguide.txt +++ b/Documentation/admin-guide/spkguide.txt @@ -7,7 +7,7 @@ Last modified on Mon Sep 27 14:26:31 2010 Document version 1.3 Copyright (c) 2005 Gene Collins -Copyright (c) 2008 Samuel Thibault +Copyright (c) 2008, 2023 Samuel Thibault Copyright (c) 2009, 2010 the Speakup Team Permission is granted to copy, distribute and/or modify this document @@ -83,8 +83,7 @@ spkout -- Speak Out txprt -- Transport dummy -- Plain text terminal -Note: Speakup does * NOT * support usb connections! Speakup also does * -NOT * support the internal Tripletalk! +Note: Speakup does * NOT * support the internal Tripletalk! Speakup does support two other synthesizers, but because they work in conjunction with other software, they must be loaded as modules after @@ -94,6 +93,12 @@ These are as follows: decpc -- DecTalk PC (not available at boot up) soft -- One of several software synthesizers (not available at boot up) +By default speakup looks for the synthesizer on the ttyS0 serial port. This can +be changed with the device parameter of the modules, for instance for +DoubleTalk LT: + +speakup_ltlk.dev=ttyUSB0 + See the sections on loading modules and software synthesizers later in this manual for further details. It should be noted here that the speakup.synth boot parameter will have no effect if Speakup has been diff --git a/Documentation/admin-guide/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst index a321b84eccaa..47499a1742bd 100644 --- a/Documentation/admin-guide/sysctl/fs.rst +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -42,16 +42,16 @@ pre-allocation or re-sizing of any kernel data structures. dentry-state ------------ -This file shows the values in ``struct dentry_stat``, as defined in -``linux/include/linux/dcache.h``:: +This file shows the values in ``struct dentry_stat_t``, as defined in +``fs/dcache.c``:: struct dentry_stat_t dentry_stat { - int nr_dentry; - int nr_unused; - int age_limit; /* age in seconds */ - int want_pages; /* pages requested by system */ - int nr_negative; /* # of unused negative dentries */ - int dummy; /* Reserved for future use */ + long nr_dentry; + long nr_unused; + long age_limit; /* age in seconds */ + long want_pages; /* pages requested by system */ + long nr_negative; /* # of unused negative dentries */ + long dummy; /* Reserved for future use */ }; Dentries are dynamically allocated and deallocated. diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index cf33de56da27..6584a1f9bfe3 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -436,7 +436,7 @@ ignore-unaligned-usertrap On architectures where unaligned accesses cause traps, and where this feature is supported (``CONFIG_SYSCTL_ARCH_UNALIGN_NO_WARN``; -currently, ``arc``, ``ia64`` and ``loongarch``), controls whether all +currently, ``arc`` and ``loongarch``), controls whether all unaligned traps are logged. = ============================================================= @@ -445,10 +445,7 @@ unaligned traps are logged. setting. = ============================================================= -See also `unaligned-trap`_ and `unaligned-dump-stack`_. On ``ia64``, -this allows system administrators to override the -``IA64_THREAD_UAC_NOPRINT`` ``prctl`` and avoid logs being flooded. - +See also `unaligned-trap`_. io_uring_disabled ================= @@ -1182,7 +1179,8 @@ automatically on platforms where it can run (that is, platforms with asymmetric CPU topologies and having an Energy Model available). If your platform happens to meet the requirements for EAS but you do not want to use it, change -this value to 0. +this value to 0. On Non-EAS platforms, write operation fails and +read doesn't return anything. task_delayacct =============== @@ -1538,22 +1536,6 @@ See Documentation/admin-guide/kernel-parameters.rst and Documentation/trace/boottime-trace.rst. -.. _unaligned-dump-stack: - -unaligned-dump-stack (ia64) -=========================== - -When logging unaligned accesses, controls whether the stack is -dumped. - -= =================================================== -0 Do not dump the stack. This is the default setting. -1 Dump the stack. -= =================================================== - -See also `ignore-unaligned-usertrap`_. - - unaligned-trap ============== diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 4877563241f3..c7525942f12c 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -71,6 +71,7 @@ two flavors of JITs, the newer eBPF JIT currently supported on: - s390x - riscv64 - riscv32 + - loongarch64 And the older cBPF JIT supported on the following archs: diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 45ba1f4dc004..c59889de122b 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -742,8 +742,8 @@ overcommit_memory This value contains a flag that enables memory overcommitment. -When this flag is 0, the kernel attempts to estimate the amount -of free memory left when userspace requests more memory. +When this flag is 0, the kernel compares the userspace memory request +size against total memory plus swap and rejects obvious overcommits. When this flag is 1, the kernel pretends there is always enough memory until it actually runs out. diff --git a/Documentation/arch/arm64/cpu-feature-registers.rst b/Documentation/arch/arm64/cpu-feature-registers.rst index de6d8a4790e2..44f9bd78539d 100644 --- a/Documentation/arch/arm64/cpu-feature-registers.rst +++ b/Documentation/arch/arm64/cpu-feature-registers.rst @@ -268,6 +268,8 @@ infrastructure: +------------------------------+---------+---------+ | SHA3 | [35-32] | y | +------------------------------+---------+---------+ + | B16B16 | [27-24] | y | + +------------------------------+---------+---------+ | BF16 | [23-20] | y | +------------------------------+---------+---------+ | BitPerm | [19-16] | y | diff --git a/Documentation/arch/arm64/elf_hwcaps.rst b/Documentation/arch/arm64/elf_hwcaps.rst index 76ff9d7398fd..4b8399ac592b 100644 --- a/Documentation/arch/arm64/elf_hwcaps.rst +++ b/Documentation/arch/arm64/elf_hwcaps.rst @@ -308,6 +308,15 @@ HWCAP2_MOPS HWCAP2_HBC Functionality implied by ID_AA64ISAR2_EL1.BC == 0b0001. +HWCAP2_SVE_B16B16 + Functionality implied by ID_AA64ZFR0_EL1.B16B16 == 0b0001. + +HWCAP2_LRCPC3 + Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0011. + +HWCAP2_LSE128 + Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0011. + 4. Unused AT_HWCAP bits ----------------------- diff --git a/Documentation/arch/ia64/aliasing.rst b/Documentation/arch/ia64/aliasing.rst deleted file mode 100644 index 36a1e1d4842b..000000000000 --- a/Documentation/arch/ia64/aliasing.rst +++ /dev/null @@ -1,246 +0,0 @@ -================================== -Memory Attribute Aliasing on IA-64 -================================== - -Bjorn Helgaas <bjorn.helgaas@hp.com> - -May 4, 2006 - - -Memory Attributes -================= - - Itanium supports several attributes for virtual memory references. - The attribute is part of the virtual translation, i.e., it is - contained in the TLB entry. The ones of most interest to the Linux - kernel are: - - == ====================== - WB Write-back (cacheable) - UC Uncacheable - WC Write-coalescing - == ====================== - - System memory typically uses the WB attribute. The UC attribute is - used for memory-mapped I/O devices. The WC attribute is uncacheable - like UC is, but writes may be delayed and combined to increase - performance for things like frame buffers. - - The Itanium architecture requires that we avoid accessing the same - page with both a cacheable mapping and an uncacheable mapping[1]. - - The design of the chipset determines which attributes are supported - on which regions of the address space. For example, some chipsets - support either WB or UC access to main memory, while others support - only WB access. - -Memory Map -========== - - Platform firmware describes the physical memory map and the - supported attributes for each region. At boot-time, the kernel uses - the EFI GetMemoryMap() interface. ACPI can also describe memory - devices and the attributes they support, but Linux/ia64 currently - doesn't use this information. - - The kernel uses the efi_memmap table returned from GetMemoryMap() to - learn the attributes supported by each region of physical address - space. Unfortunately, this table does not completely describe the - address space because some machines omit some or all of the MMIO - regions from the map. - - The kernel maintains another table, kern_memmap, which describes the - memory Linux is actually using and the attribute for each region. - This contains only system memory; it does not contain MMIO space. - - The kern_memmap table typically contains only a subset of the system - memory described by the efi_memmap. Linux/ia64 can't use all memory - in the system because of constraints imposed by the identity mapping - scheme. - - The efi_memmap table is preserved unmodified because the original - boot-time information is required for kexec. - -Kernel Identity Mappings -======================== - - Linux/ia64 identity mappings are done with large pages, currently - either 16MB or 64MB, referred to as "granules." Cacheable mappings - are speculative[2], so the processor can read any location in the - page at any time, independent of the programmer's intentions. This - means that to avoid attribute aliasing, Linux can create a cacheable - identity mapping only when the entire granule supports cacheable - access. - - Therefore, kern_memmap contains only full granule-sized regions that - can referenced safely by an identity mapping. - - Uncacheable mappings are not speculative, so the processor will - generate UC accesses only to locations explicitly referenced by - software. This allows UC identity mappings to cover granules that - are only partially populated, or populated with a combination of UC - and WB regions. - -User Mappings -============= - - User mappings are typically done with 16K or 64K pages. The smaller - page size allows more flexibility because only 16K or 64K has to be - homogeneous with respect to memory attributes. - -Potential Attribute Aliasing Cases -================================== - - There are several ways the kernel creates new mappings: - -mmap of /dev/mem ----------------- - - This uses remap_pfn_range(), which creates user mappings. These - mappings may be either WB or UC. If the region being mapped - happens to be in kern_memmap, meaning that it may also be mapped - by a kernel identity mapping, the user mapping must use the same - attribute as the kernel mapping. - - If the region is not in kern_memmap, the user mapping should use - an attribute reported as being supported in the EFI memory map. - - Since the EFI memory map does not describe MMIO on some - machines, this should use an uncacheable mapping as a fallback. - -mmap of /sys/class/pci_bus/.../legacy_mem ------------------------------------------ - - This is very similar to mmap of /dev/mem, except that legacy_mem - only allows mmap of the one megabyte "legacy MMIO" area for a - specific PCI bus. Typically this is the first megabyte of - physical address space, but it may be different on machines with - several VGA devices. - - "X" uses this to access VGA frame buffers. Using legacy_mem - rather than /dev/mem allows multiple instances of X to talk to - different VGA cards. - - The /dev/mem mmap constraints apply. - -mmap of /proc/bus/pci/.../??.? ------------------------------- - - This is an MMIO mmap of PCI functions, which additionally may or - may not be requested as using the WC attribute. - - If WC is requested, and the region in kern_memmap is either WC - or UC, and the EFI memory map designates the region as WC, then - the WC mapping is allowed. - - Otherwise, the user mapping must use the same attribute as the - kernel mapping. - -read/write of /dev/mem ----------------------- - - This uses copy_from_user(), which implicitly uses a kernel - identity mapping. This is obviously safe for things in - kern_memmap. - - There may be corner cases of things that are not in kern_memmap, - but could be accessed this way. For example, registers in MMIO - space are not in kern_memmap, but could be accessed with a UC - mapping. This would not cause attribute aliasing. But - registers typically can be accessed only with four-byte or - eight-byte accesses, and the copy_from_user() path doesn't allow - any control over the access size, so this would be dangerous. - -ioremap() ---------- - - This returns a mapping for use inside the kernel. - - If the region is in kern_memmap, we should use the attribute - specified there. - - If the EFI memory map reports that the entire granule supports - WB, we should use that (granules that are partially reserved - or occupied by firmware do not appear in kern_memmap). - - If the granule contains non-WB memory, but we can cover the - region safely with kernel page table mappings, we can use - ioremap_page_range() as most other architectures do. - - Failing all of the above, we have to fall back to a UC mapping. - -Past Problem Cases -================== - -mmap of various MMIO regions from /dev/mem by "X" on Intel platforms --------------------------------------------------------------------- - - The EFI memory map may not report these MMIO regions. - - These must be allowed so that X will work. This means that - when the EFI memory map is incomplete, every /dev/mem mmap must - succeed. It may create either WB or UC user mappings, depending - on whether the region is in kern_memmap or the EFI memory map. - -mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled ----------------------------------------------------------------------- - - The EFI memory map reports the following attributes: - - =============== ======= ================== - 0x00000-0x9FFFF WB only - 0xA0000-0xBFFFF UC only (VGA frame buffer) - 0xC0000-0xFFFFF WB only - =============== ======= ================== - - This mmap is done with user pages, not kernel identity mappings, - so it is safe to use WB mappings. - - The kernel VGA driver may ioremap the VGA frame buffer at 0xA0000, - which uses a granule-sized UC mapping. This granule will cover some - WB-only memory, but since UC is non-speculative, the processor will - never generate an uncacheable reference to the WB-only areas unless - the driver explicitly touches them. - -mmap of 0x0-0xFFFFF legacy_mem by "X" -------------------------------------- - - If the EFI memory map reports that the entire range supports the - same attributes, we can allow the mmap (and we will prefer WB if - supported, as is the case with HP sx[12]000 machines with VGA - disabled). - - If EFI reports the range as partly WB and partly UC (as on sx[12]000 - machines with VGA enabled), we must fail the mmap because there's no - safe attribute to use. - - If EFI reports some of the range but not all (as on Intel firmware - that doesn't report the VGA frame buffer at all), we should fail the - mmap and force the user to map just the specific region of interest. - -mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled ------------------------------------------------------------------------- - - The EFI memory map reports the following attributes:: - - 0x00000-0xFFFFF WB only (no VGA MMIO hole) - - This is a special case of the previous case, and the mmap should - fail for the same reason as above. - -read of /sys/devices/.../rom ----------------------------- - - For VGA devices, this may cause an ioremap() of 0xC0000. This - used to be done with a UC mapping, because the VGA frame buffer - at 0xA0000 prevents use of a WB granule. The UC mapping causes - an MCA on HP sx[12]000 chipsets. - - We should use WB page table mappings to avoid covering the VGA - frame buffer. - -Notes -===== - - [1] SDM rev 2.2, vol 2, sec 4.4.1. - [2] SDM rev 2.2, vol 2, sec 4.4.6. diff --git a/Documentation/arch/ia64/efirtc.rst b/Documentation/arch/ia64/efirtc.rst deleted file mode 100644 index fd8328408301..000000000000 --- a/Documentation/arch/ia64/efirtc.rst +++ /dev/null @@ -1,144 +0,0 @@ -========================== -EFI Real Time Clock driver -========================== - -S. Eranian <eranian@hpl.hp.com> - -March 2000 - -1. Introduction -=============== - -This document describes the efirtc.c driver has provided for -the IA-64 platform. - -The purpose of this driver is to supply an API for kernel and user applications -to get access to the Time Service offered by EFI version 0.92. - -EFI provides 4 calls one can make once the OS is booted: GetTime(), -SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this -driver. We describe those calls as well the design of the driver in the -following sections. - -2. Design Decisions -=================== - -The original ideas was to provide a very simple driver to get access to, -at first, the time of day service. This is required in order to access, in a -portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock -to initialize the system view of the time during boot. - -Because we wanted to minimize the impact on existing user-level apps using -the CMOS clock, we decided to expose an API that was very similar to the one -used today with the legacy RTC driver (driver/char/rtc.c). However, because -EFI provides a simpler services, not all ioctl() are available. Also -new ioctl()s have been introduced for things that EFI provides but not the -legacy. - -EFI uses a slightly different way of representing the time, noticeably -the reference date is different. Year is the using the full 4-digit format. -The Epoch is January 1st 1998. For backward compatibility reasons we don't -expose this new way of representing time. Instead we use something very -similar to the struct tm, i.e. struct rtc_time, as used by hwclock. -One of the reasons for doing it this way is to allow for EFI to still evolve -without necessarily impacting any of the user applications. The decoupling -enables flexibility and permits writing wrapper code is ncase things change. - -The driver exposes two interfaces, one via the device file and a set of -ioctl()s. The other is read-only via the /proc filesystem. - -As of today we don't offer a /proc/sys interface. - -To allow for a uniform interface between the legacy RTC and EFI time service, -we have created the include/linux/rtc.h header file to contain only the -"public" API of the two drivers. The specifics of the legacy RTC are still -in include/linux/mc146818rtc.h. - - -3. Time of day service -====================== - -The part of the driver gives access to the time of day service of EFI. -Two ioctl()s, compatible with the legacy RTC calls: - - Read the CMOS clock:: - - ioctl(d, RTC_RD_TIME, &rtc); - - Write the CMOS clock:: - - ioctl(d, RTC_SET_TIME, &rtc); - -The rtc is a pointer to a data structure defined in rtc.h which is close -to a struct tm:: - - struct rtc_time { - int tm_sec; - int tm_min; - int tm_hour; - int tm_mday; - int tm_mon; - int tm_year; - int tm_wday; - int tm_yday; - int tm_isdst; - }; - -The driver takes care of converting back an forth between the EFI time and -this format. - -Those two ioctl()s can be exercised with the hwclock command: - -For reading:: - - # /sbin/hwclock --show - Mon Mar 6 15:32:32 2000 -0.910248 seconds - -For setting:: - - # /sbin/hwclock --systohc - -Root privileges are required to be able to set the time of day. - -4. Wakeup Alarm service -======================= - -EFI provides an API by which one can program when a machine should wakeup, -i.e. reboot. This is very different from the alarm provided by the legacy -RTC which is some kind of interval timer alarm. For this reason we don't use -the same ioctl()s to get access to the service. Instead we have -introduced 2 news ioctl()s to the interface of an RTC. - -We have added 2 new ioctl()s that are specific to the EFI driver: - - Read the current state of the alarm:: - - ioctl(d, RTC_WKALM_RD, &wkt) - - Set the alarm or change its status:: - - ioctl(d, RTC_WKALM_SET, &wkt) - -The wkt structure encapsulates a struct rtc_time + 2 extra fields to get -status information:: - - struct rtc_wkalrm { - - unsigned char enabled; /* =1 if alarm is enabled */ - unsigned char pending; /* =1 if alarm is pending */ - - struct rtc_time time; - } - -As of today, none of the existing user-level apps supports this feature. -However writing such a program should be hard by simply using those two -ioctl(). - -Root privileges are required to be able to set the alarm. - -5. References -============= - -Checkout the following Web site for more information on EFI: - -http://developer.intel.com/technology/efi/ diff --git a/Documentation/arch/ia64/err_inject.rst b/Documentation/arch/ia64/err_inject.rst deleted file mode 100644 index 900f71e93a29..000000000000 --- a/Documentation/arch/ia64/err_inject.rst +++ /dev/null @@ -1,1067 +0,0 @@ -======================================== -IPF Machine Check (MC) error inject tool -======================================== - -IPF Machine Check (MC) error inject tool is used to inject MC -errors from Linux. The tool is a test bed for IPF MC work flow including -hardware correctable error handling, OS recoverable error handling, MC -event logging, etc. - -The tool includes two parts: a kernel driver and a user application -sample. The driver provides interface to PAL to inject error -and query error injection capabilities. The driver code is in -arch/ia64/kernel/err_inject.c. The application sample (shown below) -provides a combination of various errors and calls the driver's interface -(sysfs interface) to inject errors or query error injection capabilities. - -The tool can be used to test Intel IPF machine MC handling capabilities. -It's especially useful for people who can not access hardware MC injection -tool to inject error. It's also very useful to integrate with other -software test suits to do stressful testing on IPF. - -Below is a sample application as part of the whole tool. The sample -can be used as a working test tool. Or it can be expanded to include -more features. It also can be a integrated into a library or other user -application to have more thorough test. - -The sample application takes err.conf as error configuration input. GCC -compiles the code. After you install err_inject driver, you can run -this sample application to inject errors. - -Errata: Itanium 2 Processors Specification Update lists some errata against -the pal_mc_error_inject PAL procedure. The following err.conf has been tested -on latest Montecito PAL. - -err.conf:: - - #This is configuration file for err_inject_tool. - #The format of the each line is: - #cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer - #where - # cpu: logical cpu number the error will be inject in. - # loop: times the error will be injected. - # interval: In second. every so often one error is injected. - # err_type_info, err_struct_info: PAL parameters. - # - #Note: All values are hex w/o or w/ 0x prefix. - - - #On cpu2, inject only total 0x10 errors, interval 5 seconds - #corrected, data cache, hier-2, physical addr(assigned by tool code). - #working on Montecito latest PAL. - 2, 10, 5, 4101, 95 - - #On cpu4, inject and consume total 0x10 errors, interval 5 seconds - #corrected, data cache, hier-2, physical addr(assigned by tool code). - #working on Montecito latest PAL. - 4, 10, 5, 4109, 95 - - #On cpu15, inject and consume total 0x10 errors, interval 5 seconds - #recoverable, DTR0, hier-2. - #working on Montecito latest PAL. - 0xf, 0x10, 5, 4249, 15 - -The sample application source code: - -err_injection_tool.c:: - - /* - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, but - * WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or - * NON INFRINGEMENT. See the GNU General Public License for more - * details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * Copyright (C) 2006 Intel Co - * Fenghua Yu <fenghua.yu@intel.com> - * - */ - #include <sys/types.h> - #include <sys/stat.h> - #include <fcntl.h> - #include <stdio.h> - #include <sched.h> - #include <unistd.h> - #include <stdlib.h> - #include <stdarg.h> - #include <string.h> - #include <errno.h> - #include <time.h> - #include <sys/ipc.h> - #include <sys/sem.h> - #include <sys/wait.h> - #include <sys/mman.h> - #include <sys/shm.h> - - #define MAX_FN_SIZE 256 - #define MAX_BUF_SIZE 256 - #define DATA_BUF_SIZE 256 - #define NR_CPUS 512 - #define MAX_TASK_NUM 2048 - #define MIN_INTERVAL 5 // seconds - #define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte. - #define PARA_FIELD_NUM 5 - #define MASK_SIZE (NR_CPUS/64) - #define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/" - - int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask); - - int verbose; - #define vbprintf if (verbose) printf - - int log_info(int cpu, const char *fmt, ...) - { - FILE *log; - char fn[MAX_FN_SIZE]; - char buf[MAX_BUF_SIZE]; - va_list args; - - sprintf(fn, "%d.log", cpu); - log=fopen(fn, "a+"); - if (log==NULL) { - perror("Error open:"); - return -1; - } - - va_start(args, fmt); - vprintf(fmt, args); - memset(buf, 0, MAX_BUF_SIZE); - vsprintf(buf, fmt, args); - va_end(args); - - fwrite(buf, sizeof(buf), 1, log); - fclose(log); - - return 0; - } - - typedef unsigned long u64; - typedef unsigned int u32; - - typedef union err_type_info_u { - struct { - u64 mode : 3, /* 0-2 */ - err_inj : 3, /* 3-5 */ - err_sev : 2, /* 6-7 */ - err_struct : 5, /* 8-12 */ - struct_hier : 3, /* 13-15 */ - reserved : 48; /* 16-63 */ - } err_type_info_u; - u64 err_type_info; - } err_type_info_t; - - typedef union err_struct_info_u { - struct { - u64 siv : 1, /* 0 */ - c_t : 2, /* 1-2 */ - cl_p : 3, /* 3-5 */ - cl_id : 3, /* 6-8 */ - cl_dp : 1, /* 9 */ - reserved1 : 22, /* 10-31 */ - tiv : 1, /* 32 */ - trigger : 4, /* 33-36 */ - trigger_pl : 3, /* 37-39 */ - reserved2 : 24; /* 40-63 */ - } err_struct_info_cache; - struct { - u64 siv : 1, /* 0 */ - tt : 2, /* 1-2 */ - tc_tr : 2, /* 3-4 */ - tr_slot : 8, /* 5-12 */ - reserved1 : 19, /* 13-31 */ - tiv : 1, /* 32 */ - trigger : 4, /* 33-36 */ - trigger_pl : 3, /* 37-39 */ - reserved2 : 24; /* 40-63 */ - } err_struct_info_tlb; - struct { - u64 siv : 1, /* 0 */ - regfile_id : 4, /* 1-4 */ - reg_num : 7, /* 5-11 */ - reserved1 : 20, /* 12-31 */ - tiv : 1, /* 32 */ - trigger : 4, /* 33-36 */ - trigger_pl : 3, /* 37-39 */ - reserved2 : 24; /* 40-63 */ - } err_struct_info_register; - struct { - u64 reserved; - } err_struct_info_bus_processor_interconnect; - u64 err_struct_info; - } err_struct_info_t; - - typedef union err_data_buffer_u { - struct { - u64 trigger_addr; /* 0-63 */ - u64 inj_addr; /* 64-127 */ - u64 way : 5, /* 128-132 */ - index : 20, /* 133-152 */ - : 39; /* 153-191 */ - } err_data_buffer_cache; - struct { - u64 trigger_addr; /* 0-63 */ - u64 inj_addr; /* 64-127 */ - u64 way : 5, /* 128-132 */ - index : 20, /* 133-152 */ - reserved : 39; /* 153-191 */ - } err_data_buffer_tlb; - struct { - u64 trigger_addr; /* 0-63 */ - } err_data_buffer_register; - struct { - u64 reserved; /* 0-63 */ - } err_data_buffer_bus_processor_interconnect; - u64 err_data_buffer[ERR_DATA_BUFFER_SIZE]; - } err_data_buffer_t; - - typedef union capabilities_u { - struct { - u64 i : 1, - d : 1, - rv : 1, - tag : 1, - data : 1, - mesi : 1, - dp : 1, - reserved1 : 3, - pa : 1, - va : 1, - wi : 1, - reserved2 : 20, - trigger : 1, - trigger_pl : 1, - reserved3 : 30; - } capabilities_cache; - struct { - u64 d : 1, - i : 1, - rv : 1, - tc : 1, - tr : 1, - reserved1 : 27, - trigger : 1, - trigger_pl : 1, - reserved2 : 30; - } capabilities_tlb; - struct { - u64 gr_b0 : 1, - gr_b1 : 1, - fr : 1, - br : 1, - pr : 1, - ar : 1, - cr : 1, - rr : 1, - pkr : 1, - dbr : 1, - ibr : 1, - pmc : 1, - pmd : 1, - reserved1 : 3, - regnum : 1, - reserved2 : 15, - trigger : 1, - trigger_pl : 1, - reserved3 : 30; - } capabilities_register; - struct { - u64 reserved; - } capabilities_bus_processor_interconnect; - } capabilities_t; - - typedef struct resources_s { - u64 ibr0 : 1, - ibr2 : 1, - ibr4 : 1, - ibr6 : 1, - dbr0 : 1, - dbr2 : 1, - dbr4 : 1, - dbr6 : 1, - reserved : 48; - } resources_t; - - - long get_page_size(void) - { - long page_size=sysconf(_SC_PAGESIZE); - return page_size; - } - - #define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size()) - #define SHM_SIZE (2*PAGE_SIZE*NR_CPUS) - #define SHM_VA 0x2000000100000000 - - int shmid; - void *shmaddr; - - int create_shm(void) - { - key_t key; - char fn[MAX_FN_SIZE]; - - /* cpu0 is always existing */ - sprintf(fn, PATH_FORMAT, 0); - if ((key = ftok(fn, 's')) == -1) { - perror("ftok"); - return -1; - } - - shmid = shmget(key, SHM_SIZE, 0644 | IPC_CREAT); - if (shmid == -1) { - if (errno==EEXIST) { - shmid = shmget(key, SHM_SIZE, 0); - if (shmid == -1) { - perror("shmget"); - return -1; - } - } - else { - perror("shmget"); - return -1; - } - } - vbprintf("shmid=%d", shmid); - - /* connect to the segment: */ - shmaddr = shmat(shmid, (void *)SHM_VA, 0); - if (shmaddr == (void*)-1) { - perror("shmat"); - return -1; - } - - memset(shmaddr, 0, SHM_SIZE); - mlock(shmaddr, SHM_SIZE); - - return 0; - } - - int free_shm() - { - munlock(shmaddr, SHM_SIZE); - shmdt(shmaddr); - semctl(shmid, 0, IPC_RMID); - - return 0; - } - - #ifdef _SEM_SEMUN_UNDEFINED - union semun - { - int val; - struct semid_ds *buf; - unsigned short int *array; - struct seminfo *__buf; - }; - #endif - - u32 mode=1; /* 1: physical mode; 2: virtual mode. */ - int one_lock=1; - key_t key[NR_CPUS]; - int semid[NR_CPUS]; - - int create_sem(int cpu) - { - union semun arg; - char fn[MAX_FN_SIZE]; - int sid; - - sprintf(fn, PATH_FORMAT, cpu); - sprintf(fn, "%s/%s", fn, "err_type_info"); - if ((key[cpu] = ftok(fn, 'e')) == -1) { - perror("ftok"); - return -1; - } - - if (semid[cpu]!=0) - return 0; - - /* clear old semaphore */ - if ((sid = semget(key[cpu], 1, 0)) != -1) - semctl(sid, 0, IPC_RMID); - - /* get one semaphore */ - if ((semid[cpu] = semget(key[cpu], 1, IPC_CREAT | IPC_EXCL)) == -1) { - perror("semget"); - printf("Please remove semaphore with key=0x%lx, then run the tool.\n", - (u64)key[cpu]); - return -1; - } - - vbprintf("semid[%d]=0x%lx, key[%d]=%lx\n",cpu,(u64)semid[cpu],cpu, - (u64)key[cpu]); - /* initialize the semaphore to 1: */ - arg.val = 1; - if (semctl(semid[cpu], 0, SETVAL, arg) == -1) { - perror("semctl"); - return -1; - } - - return 0; - } - - static int lock(int cpu) - { - struct sembuf lock; - - lock.sem_num = cpu; - lock.sem_op = 1; - semop(semid[cpu], &lock, 1); - - return 0; - } - - static int unlock(int cpu) - { - struct sembuf unlock; - - unlock.sem_num = cpu; - unlock.sem_op = -1; - semop(semid[cpu], &unlock, 1); - - return 0; - } - - void free_sem(int cpu) - { - semctl(semid[cpu], 0, IPC_RMID); - } - - int wr_multi(char *fn, unsigned long *data, int size) - { - int fd; - char buf[MAX_BUF_SIZE]; - int ret; - - if (size==1) - sprintf(buf, "%lx", *data); - else if (size==3) - sprintf(buf, "%lx,%lx,%lx", data[0], data[1], data[2]); - else { - fprintf(stderr,"write to file with wrong size!\n"); - return -1; - } - - fd=open(fn, O_RDWR); - if (!fd) { - perror("Error:"); - return -1; - } - ret=write(fd, buf, sizeof(buf)); - close(fd); - return ret; - } - - int wr(char *fn, unsigned long data) - { - return wr_multi(fn, &data, 1); - } - - int rd(char *fn, unsigned long *data) - { - int fd; - char buf[MAX_BUF_SIZE]; - - fd=open(fn, O_RDONLY); - if (fd<0) { - perror("Error:"); - return -1; - } - read(fd, buf, MAX_BUF_SIZE); - *data=strtoul(buf, NULL, 16); - close(fd); - return 0; - } - - int rd_status(char *path, int *status) - { - char fn[MAX_FN_SIZE]; - sprintf(fn, "%s/status", path); - if (rd(fn, (u64*)status)<0) { - perror("status reading error.\n"); - return -1; - } - - return 0; - } - - int rd_capabilities(char *path, u64 *capabilities) - { - char fn[MAX_FN_SIZE]; - sprintf(fn, "%s/capabilities", path); - if (rd(fn, capabilities)<0) { - perror("capabilities reading error.\n"); - return -1; - } - - return 0; - } - - int rd_all(char *path) - { - unsigned long err_type_info, err_struct_info, err_data_buffer; - int status; - unsigned long capabilities, resources; - char fn[MAX_FN_SIZE]; - - sprintf(fn, "%s/err_type_info", path); - if (rd(fn, &err_type_info)<0) { - perror("err_type_info reading error.\n"); - return -1; - } - printf("err_type_info=%lx\n", err_type_info); - - sprintf(fn, "%s/err_struct_info", path); - if (rd(fn, &err_struct_info)<0) { - perror("err_struct_info reading error.\n"); - return -1; - } - printf("err_struct_info=%lx\n", err_struct_info); - - sprintf(fn, "%s/err_data_buffer", path); - if (rd(fn, &err_data_buffer)<0) { - perror("err_data_buffer reading error.\n"); - return -1; - } - printf("err_data_buffer=%lx\n", err_data_buffer); - - sprintf(fn, "%s/status", path); - if (rd("status", (u64*)&status)<0) { - perror("status reading error.\n"); - return -1; - } - printf("status=%d\n", status); - - sprintf(fn, "%s/capabilities", path); - if (rd(fn,&capabilities)<0) { - perror("capabilities reading error.\n"); - return -1; - } - printf("capabilities=%lx\n", capabilities); - - sprintf(fn, "%s/resources", path); - if (rd(fn, &resources)<0) { - perror("resources reading error.\n"); - return -1; - } - printf("resources=%lx\n", resources); - - return 0; - } - - int query_capabilities(char *path, err_type_info_t err_type_info, - u64 *capabilities) - { - char fn[MAX_FN_SIZE]; - err_struct_info_t err_struct_info; - err_data_buffer_t err_data_buffer; - - err_struct_info.err_struct_info=0; - memset(err_data_buffer.err_data_buffer, -1, ERR_DATA_BUFFER_SIZE*8); - - sprintf(fn, "%s/err_type_info", path); - wr(fn, err_type_info.err_type_info); - sprintf(fn, "%s/err_struct_info", path); - wr(fn, 0x0); - sprintf(fn, "%s/err_data_buffer", path); - wr_multi(fn, err_data_buffer.err_data_buffer, ERR_DATA_BUFFER_SIZE); - - // Fire pal_mc_error_inject procedure. - sprintf(fn, "%s/call_start", path); - wr(fn, mode); - - if (rd_capabilities(path, capabilities)<0) - return -1; - - return 0; - } - - int query_all_capabilities() - { - int status; - err_type_info_t err_type_info; - int err_sev, err_struct, struct_hier; - int cap=0; - u64 capabilities; - char path[MAX_FN_SIZE]; - - err_type_info.err_type_info=0; // Initial - err_type_info.err_type_info_u.mode=0; // Query mode; - err_type_info.err_type_info_u.err_inj=0; - - printf("All capabilities implemented in pal_mc_error_inject:\n"); - sprintf(path, PATH_FORMAT ,0); - for (err_sev=0;err_sev<3;err_sev++) - for (err_struct=0;err_struct<5;err_struct++) - for (struct_hier=0;struct_hier<5;struct_hier++) - { - status=-1; - capabilities=0; - err_type_info.err_type_info_u.err_sev=err_sev; - err_type_info.err_type_info_u.err_struct=err_struct; - err_type_info.err_type_info_u.struct_hier=struct_hier; - - if (query_capabilities(path, err_type_info, &capabilities)<0) - continue; - - if (rd_status(path, &status)<0) - continue; - - if (status==0) { - cap=1; - printf("For err_sev=%d, err_struct=%d, struct_hier=%d: ", - err_sev, err_struct, struct_hier); - printf("capabilities 0x%lx\n", capabilities); - } - } - if (!cap) { - printf("No capabilities supported.\n"); - return 0; - } - - return 0; - } - - int err_inject(int cpu, char *path, err_type_info_t err_type_info, - err_struct_info_t err_struct_info, - err_data_buffer_t err_data_buffer) - { - int status; - char fn[MAX_FN_SIZE]; - - log_info(cpu, "err_type_info=%lx, err_struct_info=%lx, ", - err_type_info.err_type_info, - err_struct_info.err_struct_info); - log_info(cpu,"err_data_buffer=[%lx,%lx,%lx]\n", - err_data_buffer.err_data_buffer[0], - err_data_buffer.err_data_buffer[1], - err_data_buffer.err_data_buffer[2]); - sprintf(fn, "%s/err_type_info", path); - wr(fn, err_type_info.err_type_info); - sprintf(fn, "%s/err_struct_info", path); - wr(fn, err_struct_info.err_struct_info); - sprintf(fn, "%s/err_data_buffer", path); - wr_multi(fn, err_data_buffer.err_data_buffer, ERR_DATA_BUFFER_SIZE); - - // Fire pal_mc_error_inject procedure. - sprintf(fn, "%s/call_start", path); - wr(fn,mode); - - if (rd_status(path, &status)<0) { - vbprintf("fail: read status\n"); - return -100; - } - - if (status!=0) { - log_info(cpu, "fail: status=%d\n", status); - return status; - } - - return status; - } - - static int construct_data_buf(char *path, err_type_info_t err_type_info, - err_struct_info_t err_struct_info, - err_data_buffer_t *err_data_buffer, - void *va1) - { - char fn[MAX_FN_SIZE]; - u64 virt_addr=0, phys_addr=0; - - vbprintf("va1=%lx\n", (u64)va1); - memset(&err_data_buffer->err_data_buffer_cache, 0, ERR_DATA_BUFFER_SIZE*8); - - switch (err_type_info.err_type_info_u.err_struct) { - case 1: // Cache - switch (err_struct_info.err_struct_info_cache.cl_id) { - case 1: //Virtual addr - err_data_buffer->err_data_buffer_cache.inj_addr=(u64)va1; - break; - case 2: //Phys addr - sprintf(fn, "%s/virtual_to_phys", path); - virt_addr=(u64)va1; - if (wr(fn,virt_addr)<0) - return -1; - rd(fn, &phys_addr); - err_data_buffer->err_data_buffer_cache.inj_addr=phys_addr; - break; - default: - printf("Not supported cl_id\n"); - break; - } - break; - case 2: // TLB - break; - case 3: // Register file - break; - case 4: // Bus/system interconnect - default: - printf("Not supported err_struct\n"); - break; - } - - return 0; - } - - typedef struct { - u64 cpu; - u64 loop; - u64 interval; - u64 err_type_info; - u64 err_struct_info; - u64 err_data_buffer[ERR_DATA_BUFFER_SIZE]; - } parameters_t; - - parameters_t line_para; - int para; - - static int empty_data_buffer(u64 *err_data_buffer) - { - int empty=1; - int i; - - for (i=0;i<ERR_DATA_BUFFER_SIZE; i++) - if (err_data_buffer[i]!=-1) - empty=0; - - return empty; - } - - int err_inj() - { - err_type_info_t err_type_info; - err_struct_info_t err_struct_info; - err_data_buffer_t err_data_buffer; - int count; - FILE *fp; - unsigned long cpu, loop, interval, err_type_info_conf, err_struct_info_conf; - u64 err_data_buffer_conf[ERR_DATA_BUFFER_SIZE]; - int num; - int i; - char path[MAX_FN_SIZE]; - parameters_t parameters[MAX_TASK_NUM]={}; - pid_t child_pid[MAX_TASK_NUM]; - time_t current_time; - int status; - - if (!para) { - fp=fopen("err.conf", "r"); - if (fp==NULL) { - perror("Error open err.conf"); - return -1; - } - - num=0; - while (!feof(fp)) { - char buf[256]; - memset(buf,0,256); - fgets(buf, 256, fp); - count=sscanf(buf, "%lx, %lx, %lx, %lx, %lx, %lx, %lx, %lx\n", - &cpu, &loop, &interval,&err_type_info_conf, - &err_struct_info_conf, - &err_data_buffer_conf[0], - &err_data_buffer_conf[1], - &err_data_buffer_conf[2]); - if (count!=PARA_FIELD_NUM+3) { - err_data_buffer_conf[0]=-1; - err_data_buffer_conf[1]=-1; - err_data_buffer_conf[2]=-1; - count=sscanf(buf, "%lx, %lx, %lx, %lx, %lx\n", - &cpu, &loop, &interval,&err_type_info_conf, - &err_struct_info_conf); - if (count!=PARA_FIELD_NUM) - continue; - } - - parameters[num].cpu=cpu; - parameters[num].loop=loop; - parameters[num].interval= interval>MIN_INTERVAL - ?interval:MIN_INTERVAL; - parameters[num].err_type_info=err_type_info_conf; - parameters[num].err_struct_info=err_struct_info_conf; - memcpy(parameters[num++].err_data_buffer, - err_data_buffer_conf,ERR_DATA_BUFFER_SIZE*8) ; - - if (num>=MAX_TASK_NUM) - break; - } - } - else { - parameters[0].cpu=line_para.cpu; - parameters[0].loop=line_para.loop; - parameters[0].interval= line_para.interval>MIN_INTERVAL - ?line_para.interval:MIN_INTERVAL; - parameters[0].err_type_info=line_para.err_type_info; - parameters[0].err_struct_info=line_para.err_struct_info; - memcpy(parameters[0].err_data_buffer, - line_para.err_data_buffer,ERR_DATA_BUFFER_SIZE*8) ; - - num=1; - } - - /* Create semaphore: If one_lock, one semaphore for all processors. - Otherwise, one semaphore for each processor. */ - if (one_lock) { - if (create_sem(0)) { - printf("Can not create semaphore...exit\n"); - free_sem(0); - return -1; - } - } - else { - for (i=0;i<num;i++) { - if (create_sem(parameters[i].cpu)) { - printf("Can not create semaphore for cpu%d...exit\n",i); - free_sem(parameters[num].cpu); - return -1; - } - } - } - - /* Create a shm segment which will be used to inject/consume errors on.*/ - if (create_shm()==-1) { - printf("Error to create shm...exit\n"); - return -1; - } - - for (i=0;i<num;i++) { - pid_t pid; - - current_time=time(NULL); - log_info(parameters[i].cpu, "\nBegine at %s", ctime(¤t_time)); - log_info(parameters[i].cpu, "Configurations:\n"); - log_info(parameters[i].cpu,"On cpu%ld: loop=%lx, interval=%lx(s)", - parameters[i].cpu, - parameters[i].loop, - parameters[i].interval); - log_info(parameters[i].cpu," err_type_info=%lx,err_struct_info=%lx\n", - parameters[i].err_type_info, - parameters[i].err_struct_info); - - sprintf(path, PATH_FORMAT, (int)parameters[i].cpu); - err_type_info.err_type_info=parameters[i].err_type_info; - err_struct_info.err_struct_info=parameters[i].err_struct_info; - memcpy(err_data_buffer.err_data_buffer, - parameters[i].err_data_buffer, - ERR_DATA_BUFFER_SIZE*8); - - pid=fork(); - if (pid==0) { - unsigned long mask[MASK_SIZE]; - int j, k; - - void *va1, *va2; - - /* Allocate two memory areas va1 and va2 in shm */ - va1=shmaddr+parameters[i].cpu*PAGE_SIZE; - va2=shmaddr+parameters[i].cpu*PAGE_SIZE+PAGE_SIZE; - - vbprintf("va1=%lx, va2=%lx\n", (u64)va1, (u64)va2); - memset(va1, 0x1, PAGE_SIZE); - memset(va2, 0x2, PAGE_SIZE); - - if (empty_data_buffer(err_data_buffer.err_data_buffer)) - /* If not specified yet, construct data buffer - * with va1 - */ - construct_data_buf(path, err_type_info, - err_struct_info, &err_data_buffer,va1); - - for (j=0;j<MASK_SIZE;j++) - mask[j]=0; - - cpu=parameters[i].cpu; - k = cpu%64; - j = cpu/64; - mask[j] = 1UL << k; - - if (sched_setaffinity(0, MASK_SIZE*8, mask)==-1) { - perror("Error sched_setaffinity:"); - return -1; - } - - for (j=0; j<parameters[i].loop; j++) { - log_info(parameters[i].cpu,"Injection "); - log_info(parameters[i].cpu,"on cpu%ld: #%d/%ld ", - - parameters[i].cpu,j+1, parameters[i].loop); - - /* Hold the lock */ - if (one_lock) - lock(0); - else - /* Hold lock on this cpu */ - lock(parameters[i].cpu); - - if ((status=err_inject(parameters[i].cpu, - path, err_type_info, - err_struct_info, err_data_buffer)) - ==0) { - /* consume the error for "inject only"*/ - memcpy(va2, va1, PAGE_SIZE); - memcpy(va1, va2, PAGE_SIZE); - log_info(parameters[i].cpu, - "successful\n"); - } - else { - log_info(parameters[i].cpu,"fail:"); - log_info(parameters[i].cpu, - "status=%d\n", status); - unlock(parameters[i].cpu); - break; - } - if (one_lock) - /* Release the lock */ - unlock(0); - /* Release lock on this cpu */ - else - unlock(parameters[i].cpu); - - if (j < parameters[i].loop-1) - sleep(parameters[i].interval); - } - current_time=time(NULL); - log_info(parameters[i].cpu, "Done at %s", ctime(¤t_time)); - return 0; - } - else if (pid<0) { - perror("Error fork:"); - continue; - } - child_pid[i]=pid; - } - for (i=0;i<num;i++) - waitpid(child_pid[i], NULL, 0); - - if (one_lock) - free_sem(0); - else - for (i=0;i<num;i++) - free_sem(parameters[i].cpu); - - printf("All done.\n"); - - return 0; - } - - void help() - { - printf("err_inject_tool:\n"); - printf("\t-q: query all capabilities. default: off\n"); - printf("\t-m: procedure mode. 1: physical 2: virtual. default: 1\n"); - printf("\t-i: inject errors. default: off\n"); - printf("\t-l: one lock per cpu. default: one lock for all\n"); - printf("\t-e: error parameters:\n"); - printf("\t\tcpu,loop,interval,err_type_info,err_struct_info[,err_data_buffer[0],err_data_buffer[1],err_data_buffer[2]]\n"); - printf("\t\t cpu: logical cpu number the error will be inject in.\n"); - printf("\t\t loop: times the error will be injected.\n"); - printf("\t\t interval: In second. every so often one error is injected.\n"); - printf("\t\t err_type_info, err_struct_info: PAL parameters.\n"); - printf("\t\t err_data_buffer: PAL parameter. Optional. If not present,\n"); - printf("\t\t it's constructed by tool automatically. Be\n"); - printf("\t\t careful to provide err_data_buffer and make\n"); - printf("\t\t sure it's working with the environment.\n"); - printf("\t Note:no space between error parameters.\n"); - printf("\t default: Take error parameters from err.conf instead of command line.\n"); - printf("\t-v: verbose. default: off\n"); - printf("\t-h: help\n\n"); - printf("The tool will take err.conf file as "); - printf("input to inject single or multiple errors "); - printf("on one or multiple cpus in parallel.\n"); - } - - int main(int argc, char **argv) - { - char c; - int do_err_inj=0; - int do_query_all=0; - int count; - u32 m; - - /* Default one lock for all cpu's */ - one_lock=1; - while ((c = getopt(argc, argv, "m:iqvhle:")) != EOF) - switch (c) { - case 'm': /* Procedure mode. 1: phys 2: virt */ - count=sscanf(optarg, "%x", &m); - if (count!=1 || (m!=1 && m!=2)) { - printf("Wrong mode number.\n"); - help(); - return -1; - } - mode=m; - break; - case 'i': /* Inject errors */ - do_err_inj=1; - break; - case 'q': /* Query */ - do_query_all=1; - break; - case 'v': /* Verbose */ - verbose=1; - break; - case 'l': /* One lock per cpu */ - one_lock=0; - break; - case 'e': /* error arguments */ - /* Take parameters: - * #cpu, loop, interval, err_type_info, err_struct_info[, err_data_buffer] - * err_data_buffer is optional. Recommend not to specify - * err_data_buffer. Better to use tool to generate it. - */ - count=sscanf(optarg, - "%lx, %lx, %lx, %lx, %lx, %lx, %lx, %lx\n", - &line_para.cpu, - &line_para.loop, - &line_para.interval, - &line_para.err_type_info, - &line_para.err_struct_info, - &line_para.err_data_buffer[0], - &line_para.err_data_buffer[1], - &line_para.err_data_buffer[2]); - if (count!=PARA_FIELD_NUM+3) { - line_para.err_data_buffer[0]=-1, - line_para.err_data_buffer[1]=-1, - line_para.err_data_buffer[2]=-1; - count=sscanf(optarg, "%lx, %lx, %lx, %lx, %lx\n", - &line_para.cpu, - &line_para.loop, - &line_para.interval, - &line_para.err_type_info, - &line_para.err_struct_info); - if (count!=PARA_FIELD_NUM) { - printf("Wrong error arguments.\n"); - help(); - return -1; - } - } - para=1; - break; - continue; - break; - case 'h': - help(); - return 0; - default: - break; - } - - if (do_query_all) - query_all_capabilities(); - if (do_err_inj) - err_inj(); - - if (!do_query_all && !do_err_inj) - help(); - - return 0; - } diff --git a/Documentation/arch/ia64/features.rst b/Documentation/arch/ia64/features.rst deleted file mode 100644 index d7226fdcf5f8..000000000000 --- a/Documentation/arch/ia64/features.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. kernel-feat:: $srctree/Documentation/features ia64 diff --git a/Documentation/arch/ia64/fsys.rst b/Documentation/arch/ia64/fsys.rst deleted file mode 100644 index a702d2cc94b6..000000000000 --- a/Documentation/arch/ia64/fsys.rst +++ /dev/null @@ -1,303 +0,0 @@ -=================================== -Light-weight System Calls for IA-64 -=================================== - - Started: 13-Jan-2003 - - Last update: 27-Sep-2003 - - David Mosberger-Tang - <davidm@hpl.hp.com> - -Using the "epc" instruction effectively introduces a new mode of -execution to the ia64 linux kernel. We call this mode the -"fsys-mode". To recap, the normal states of execution are: - - - kernel mode: - Both the register stack and the memory stack have been - switched over to kernel memory. The user-level state is saved - in a pt-regs structure at the top of the kernel memory stack. - - - user mode: - Both the register stack and the kernel stack are in - user memory. The user-level state is contained in the - CPU registers. - - - bank 0 interruption-handling mode: - This is the non-interruptible state which all - interruption-handlers start execution in. The user-level - state remains in the CPU registers and some kernel state may - be stored in bank 0 of registers r16-r31. - -In contrast, fsys-mode has the following special properties: - - - execution is at privilege level 0 (most-privileged) - - - CPU registers may contain a mixture of user-level and kernel-level - state (it is the responsibility of the kernel to ensure that no - security-sensitive kernel-level state is leaked back to - user-level) - - - execution is interruptible and preemptible (an fsys-mode handler - can disable interrupts and avoid all other interruption-sources - to avoid preemption) - - - neither the memory-stack nor the register-stack can be trusted while - in fsys-mode (they point to the user-level stacks, which may - be invalid, or completely bogus addresses) - -In summary, fsys-mode is much more similar to running in user-mode -than it is to running in kernel-mode. Of course, given that the -privilege level is at level 0, this means that fsys-mode requires some -care (see below). - - -How to tell fsys-mode -===================== - -Linux operates in fsys-mode when (a) the privilege level is 0 (most -privileged) and (b) the stacks have NOT been switched to kernel memory -yet. For convenience, the header file <asm-ia64/ptrace.h> provides -three macros:: - - user_mode(regs) - user_stack(task,regs) - fsys_mode(task,regs) - -The "regs" argument is a pointer to a pt_regs structure. The "task" -argument is a pointer to the task structure to which the "regs" -pointer belongs to. user_mode() returns TRUE if the CPU state pointed -to by "regs" was executing in user mode (privilege level 3). -user_stack() returns TRUE if the state pointed to by "regs" was -executing on the user-level stack(s). Finally, fsys_mode() returns -TRUE if the CPU state pointed to by "regs" was executing in fsys-mode. -The fsys_mode() macro is equivalent to the expression:: - - !user_mode(regs) && user_stack(task,regs) - -How to write an fsyscall handler -================================ - -The file arch/ia64/kernel/fsys.S contains a table of fsyscall-handlers -(fsyscall_table). This table contains one entry for each system call. -By default, a system call is handled by fsys_fallback_syscall(). This -routine takes care of entering (full) kernel mode and calling the -normal Linux system call handler. For performance-critical system -calls, it is possible to write a hand-tuned fsyscall_handler. For -example, fsys.S contains fsys_getpid(), which is a hand-tuned version -of the getpid() system call. - -The entry and exit-state of an fsyscall handler is as follows: - -Machine state on entry to fsyscall handler ------------------------------------------- - - ========= =============================================================== - r10 0 - r11 saved ar.pfs (a user-level value) - r15 system call number - r16 "current" task pointer (in normal kernel-mode, this is in r13) - r32-r39 system call arguments - b6 return address (a user-level value) - ar.pfs previous frame-state (a user-level value) - PSR.be cleared to zero (i.e., little-endian byte order is in effect) - - all other registers may contain values passed in from user-mode - ========= =============================================================== - -Required machine state on exit to fsyscall handler --------------------------------------------------- - - ========= =========================================================== - r11 saved ar.pfs (as passed into the fsyscall handler) - r15 system call number (as passed into the fsyscall handler) - r32-r39 system call arguments (as passed into the fsyscall handler) - b6 return address (as passed into the fsyscall handler) - ar.pfs previous frame-state (as passed into the fsyscall handler) - ========= =========================================================== - -Fsyscall handlers can execute with very little overhead, but with that -speed comes a set of restrictions: - - * Fsyscall-handlers MUST check for any pending work in the flags - member of the thread-info structure and if any of the - TIF_ALLWORK_MASK flags are set, the handler needs to fall back on - doing a full system call (by calling fsys_fallback_syscall). - - * Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11, - r15, b6, and ar.pfs) because they will be needed in case of a - system call restart. Of course, all "preserved" registers also - must be preserved, in accordance to the normal calling conventions. - - * Fsyscall-handlers MUST check argument registers for containing a - NaT value before using them in any way that could trigger a - NaT-consumption fault. If a system call argument is found to - contain a NaT value, an fsyscall-handler may return immediately - with r8=EINVAL, r10=-1. - - * Fsyscall-handlers MUST NOT use the "alloc" instruction or perform - any other operation that would trigger mandatory RSE - (register-stack engine) traffic. - - * Fsyscall-handlers MUST NOT write to any stacked registers because - it is not safe to assume that user-level called a handler with the - proper number of arguments. - - * Fsyscall-handlers need to be careful when accessing per-CPU variables: - unless proper safe-guards are taken (e.g., interruptions are avoided), - execution may be pre-empted and resumed on another CPU at any given - time. - - * Fsyscall-handlers must be careful not to leak sensitive kernel' - information back to user-level. In particular, before returning to - user-level, care needs to be taken to clear any scratch registers - that could contain sensitive information (note that the current - task pointer is not considered sensitive: it's already exposed - through ar.k6). - - * Fsyscall-handlers MUST NOT access user-memory without first - validating access-permission (this can be done typically via - probe.r.fault and/or probe.w.fault) and without guarding against - memory access exceptions (this can be done with the EX() macros - defined by asmmacro.h). - -The above restrictions may seem draconian, but remember that it's -possible to trade off some of the restrictions by paying a slightly -higher overhead. For example, if an fsyscall-handler could benefit -from the shadow register bank, it could temporarily disable PSR.i and -PSR.ic, switch to bank 0 (bsw.0) and then use the shadow registers as -needed. In other words, following the above rules yields extremely -fast system call execution (while fully preserving system call -semantics), but there is also a lot of flexibility in handling more -complicated cases. - -Signal handling -=============== - -The delivery of (asynchronous) signals must be delayed until fsys-mode -is exited. This is accomplished with the help of the lower-privilege -transfer trap: arch/ia64/kernel/process.c:do_notify_resume_user() -checks whether the interrupted task was in fsys-mode and, if so, sets -PSR.lp and returns immediately. When fsys-mode is exited via the -"br.ret" instruction that lowers the privilege level, a trap will -occur. The trap handler clears PSR.lp again and returns immediately. -The kernel exit path then checks for and delivers any pending signals. - -PSR Handling -============ - -The "epc" instruction doesn't change the contents of PSR at all. This -is in contrast to a regular interruption, which clears almost all -bits. Because of that, some care needs to be taken to ensure things -work as expected. The following discussion describes how each PSR bit -is handled. - -======= ======================================================================= -PSR.be Cleared when entering fsys-mode. A srlz.d instruction is used - to ensure the CPU is in little-endian mode before the first - load/store instruction is executed. PSR.be is normally NOT - restored upon return from an fsys-mode handler. In other - words, user-level code must not rely on PSR.be being preserved - across a system call. -PSR.up Unchanged. -PSR.ac Unchanged. -PSR.mfl Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.mfh Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.ic Unchanged. Note: fsys-mode handlers can clear the bit, if needed. -PSR.i Unchanged. Note: fsys-mode handlers can clear the bit, if needed. -PSR.pk Unchanged. -PSR.dt Unchanged. -PSR.dfl Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.dfh Unchanged. Note: fsys-mode handlers must not write-registers! -PSR.sp Unchanged. -PSR.pp Unchanged. -PSR.di Unchanged. -PSR.si Unchanged. -PSR.db Unchanged. The kernel prevents user-level from setting a hardware - breakpoint that triggers at any privilege level other than - 3 (user-mode). -PSR.lp Unchanged. -PSR.tb Lazy redirect. If a taken-branch trap occurs while in - fsys-mode, the trap-handler modifies the saved machine state - such that execution resumes in the gate page at - syscall_via_break(), with privilege level 3. Note: the - taken branch would occur on the branch invoking the - fsyscall-handler, at which point, by definition, a syscall - restart is still safe. If the system call number is invalid, - the fsys-mode handler will return directly to user-level. This - return will trigger a taken-branch trap, but since the trap is - taken _after_ restoring the privilege level, the CPU has already - left fsys-mode, so no special treatment is needed. -PSR.rt Unchanged. -PSR.cpl Cleared to 0. -PSR.is Unchanged (guaranteed to be 0 on entry to the gate page). -PSR.mc Unchanged. -PSR.it Unchanged (guaranteed to be 1). -PSR.id Unchanged. Note: the ia64 linux kernel never sets this bit. -PSR.da Unchanged. Note: the ia64 linux kernel never sets this bit. -PSR.dd Unchanged. Note: the ia64 linux kernel never sets this bit. -PSR.ss Lazy redirect. If set, "epc" will cause a Single Step Trap to - be taken. The trap handler then modifies the saved machine - state such that execution resumes in the gate page at - syscall_via_break(), with privilege level 3. -PSR.ri Unchanged. -PSR.ed Unchanged. Note: This bit could only have an effect if an fsys-mode - handler performed a speculative load that gets NaTted. If so, this - would be the normal & expected behavior, so no special treatment is - needed. -PSR.bn Unchanged. Note: fsys-mode handlers may clear the bit, if needed. - Doing so requires clearing PSR.i and PSR.ic as well. -PSR.ia Unchanged. Note: the ia64 linux kernel never sets this bit. -======= ======================================================================= - -Using fast system calls -======================= - -To use fast system calls, userspace applications need simply call -__kernel_syscall_via_epc(). For example - --- example fgettimeofday() call -- - --- fgettimeofday.S -- - -:: - - #include <asm/asmmacro.h> - - GLOBAL_ENTRY(fgettimeofday) - .prologue - .save ar.pfs, r11 - mov r11 = ar.pfs - .body - - mov r2 = 0xa000000000020660;; // gate address - // found by inspection of System.map for the - // __kernel_syscall_via_epc() function. See - // below for how to do this for real. - - mov b7 = r2 - mov r15 = 1087 // gettimeofday syscall - ;; - br.call.sptk.many b6 = b7 - ;; - - .restore sp - - mov ar.pfs = r11 - br.ret.sptk.many rp;; // return to caller - END(fgettimeofday) - --- end fgettimeofday.S -- - -In reality, getting the gate address is accomplished by two extra -values passed via the ELF auxiliary vector (include/asm-ia64/elf.h) - - * AT_SYSINFO : is the address of __kernel_syscall_via_epc() - * AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO - -The ELF DSO is a pre-linked library that is mapped in by the kernel at -the gate page. It is a proper ELF shared object so, with a dynamic -loader that recognises the library, you should be able to make calls to -the exported functions within it as with any other shared library. -AT_SYSINFO points into the kernel DSO at the -__kernel_syscall_via_epc() function for historical reasons (it was -used before the kernel DSO) and as a convenience. diff --git a/Documentation/arch/ia64/ia64.rst b/Documentation/arch/ia64/ia64.rst deleted file mode 100644 index b725019a9492..000000000000 --- a/Documentation/arch/ia64/ia64.rst +++ /dev/null @@ -1,49 +0,0 @@ -=========================================== -Linux kernel release for the IA-64 Platform -=========================================== - - These are the release notes for Linux since version 2.4 for IA-64 - platform. This document provides information specific to IA-64 - ONLY, to get additional information about the Linux kernel also - read the original Linux README provided with the kernel. - -Installing the Kernel -===================== - - - IA-64 kernel installation is the same as the other platforms, see - original README for details. - - -Software Requirements -===================== - - Compiling and running this kernel requires an IA-64 compliant GCC - compiler. And various software packages also compiled with an - IA-64 compliant GCC compiler. - - -Configuring the Kernel -====================== - - Configuration is the same, see original README for details. - - -Compiling the Kernel: - - - Compiling this kernel doesn't differ from other platform so read - the original README for details BUT make sure you have an IA-64 - compliant GCC compiler. - -IA-64 Specifics -=============== - - - General issues: - - * Hardly any performance tuning has been done. Obvious targets - include the library routines (IP checksum, etc.). Less - obvious targets include making sure we don't flush the TLB - needlessly, etc. - - * SMP locks cleanup/optimization - - * IA32 support. Currently experimental. It mostly works. diff --git a/Documentation/arch/ia64/index.rst b/Documentation/arch/ia64/index.rst deleted file mode 100644 index 761f2154dfa2..000000000000 --- a/Documentation/arch/ia64/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -================== -IA-64 Architecture -================== - -.. toctree:: - :maxdepth: 1 - - ia64 - aliasing - efirtc - err_inject - fsys - irq-redir - mca - serial - - features diff --git a/Documentation/arch/ia64/irq-redir.rst b/Documentation/arch/ia64/irq-redir.rst deleted file mode 100644 index 6bbbbe4f73ef..000000000000 --- a/Documentation/arch/ia64/irq-redir.rst +++ /dev/null @@ -1,80 +0,0 @@ -============================== -IRQ affinity on IA64 platforms -============================== - -07.01.2002, Erich Focht <efocht@ess.nec.de> - - -By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be -controlled. The behavior on IA64 platforms is slightly different from -that described in Documentation/core-api/irq/irq-affinity.rst for i386 systems. - -Because of the usage of SAPIC mode and physical destination mode the -IRQ target is one particular CPU and cannot be a mask of several -CPUs. Only the first non-zero bit is taken into account. - - -Usage examples -============== - -The target CPU has to be specified as a hexadecimal CPU mask. The -first non-zero bit is the selected CPU. This format has been kept for -compatibility reasons with i386. - -Set the delivery mode of interrupt 41 to fixed and route the -interrupts to CPU #3 (logical CPU number) (2^3=0x08):: - - echo "8" >/proc/irq/41/smp_affinity - -Set the default route for IRQ number 41 to CPU 6 in lowest priority -delivery mode (redirectable):: - - echo "r 40" >/proc/irq/41/smp_affinity - -The output of the command:: - - cat /proc/irq/IRQ#/smp_affinity - -gives the target CPU mask for the specified interrupt vector. If the CPU -mask is preceded by the character "r", the interrupt is redirectable -(i.e. lowest priority mode routing is used), otherwise its route is -fixed. - - - -Initialization and default behavior -=================================== - -If the platform features IRQ redirection (info provided by SAL) all -IO-SAPIC interrupts are initialized with CPU#0 as their default target -and the routing is the so called "lowest priority mode" (actually -fixed SAPIC mode with hint). The XTP chipset registers are used as hints -for the IRQ routing. Currently in Linux XTP registers can have three -values: - - - minimal for an idle task, - - normal if any other task runs, - - maximal if the CPU is going to be switched off. - -The IRQ is routed to the CPU with lowest XTP register value, the -search begins at the default CPU. Therefore most of the interrupts -will be handled by CPU #0. - -If the platform doesn't feature interrupt redirection IOSAPIC fixed -routing is used. The target CPUs are distributed in a round robin -manner. IRQs will be routed only to the selected target CPUs. Check -with:: - - cat /proc/interrupts - - - -Comments -======== - -On large (multi-node) systems it is recommended to route the IRQs to -the node to which the corresponding device is connected. -For systems like the NEC AzusA we get IRQ node-affinity for free. This -is because usually the chipsets on each node redirect the interrupts -only to their own CPUs (as they cannot see the XTP registers on the -other nodes). diff --git a/Documentation/arch/ia64/mca.rst b/Documentation/arch/ia64/mca.rst deleted file mode 100644 index 08270bba44a4..000000000000 --- a/Documentation/arch/ia64/mca.rst +++ /dev/null @@ -1,198 +0,0 @@ -============================================================= -An ad-hoc collection of notes on IA64 MCA and INIT processing -============================================================= - -Feel free to update it with notes about any area that is not clear. - ---- - -MCA/INIT are completely asynchronous. They can occur at any time, when -the OS is in any state. Including when one of the cpus is already -holding a spinlock. Trying to get any lock from MCA/INIT state is -asking for deadlock. Also the state of structures that are protected -by locks is indeterminate, including linked lists. - ---- - -The complicated ia64 MCA process. All of this is mandated by Intel's -specification for ia64 SAL, error recovery and unwind, it is not as -if we have a choice here. - -* MCA occurs on one cpu, usually due to a double bit memory error. - This is the monarch cpu. - -* SAL sends an MCA rendezvous interrupt (which is a normal interrupt) - to all the other cpus, the slaves. - -* Slave cpus that receive the MCA interrupt call down into SAL, they - end up spinning disabled while the MCA is being serviced. - -* If any slave cpu was already spinning disabled when the MCA occurred - then it cannot service the MCA interrupt. SAL waits ~20 seconds then - sends an unmaskable INIT event to the slave cpus that have not - already rendezvoused. - -* Because MCA/INIT can be delivered at any time, including when the cpu - is down in PAL in physical mode, the registers at the time of the - event are _completely_ undefined. In particular the MCA/INIT - handlers cannot rely on the thread pointer, PAL physical mode can - (and does) modify TP. It is allowed to do that as long as it resets - TP on return. However MCA/INIT events expose us to these PAL - internal TP changes. Hence curr_task(). - -* If an MCA/INIT event occurs while the kernel was running (not user - space) and the kernel has called PAL then the MCA/INIT handler cannot - assume that the kernel stack is in a fit state to be used. Mainly - because PAL may or may not maintain the stack pointer internally. - Because the MCA/INIT handlers cannot trust the kernel stack, they - have to use their own, per-cpu stacks. The MCA/INIT stacks are - preformatted with just enough task state to let the relevant handlers - do their job. - -* Unlike most other architectures, the ia64 struct task is embedded in - the kernel stack[1]. So switching to a new kernel stack means that - we switch to a new task as well. Because various bits of the kernel - assume that current points into the struct task, switching to a new - stack also means a new value for current. - -* Once all slaves have rendezvoused and are spinning disabled, the - monarch is entered. The monarch now tries to diagnose the problem - and decide if it can recover or not. - -* Part of the monarch's job is to look at the state of all the other - tasks. The only way to do that on ia64 is to call the unwinder, - as mandated by Intel. - -* The starting point for the unwind depends on whether a task is - running or not. That is, whether it is on a cpu or is blocked. The - monarch has to determine whether or not a task is on a cpu before it - knows how to start unwinding it. The tasks that received an MCA or - INIT event are no longer running, they have been converted to blocked - tasks. But (and its a big but), the cpus that received the MCA - rendezvous interrupt are still running on their normal kernel stacks! - -* To distinguish between these two cases, the monarch must know which - tasks are on a cpu and which are not. Hence each slave cpu that - switches to an MCA/INIT stack, registers its new stack using - set_curr_task(), so the monarch can tell that the _original_ task is - no longer running on that cpu. That gives us a decent chance of - getting a valid backtrace of the _original_ task. - -* MCA/INIT can be nested, to a depth of 2 on any cpu. In the case of a - nested error, we want diagnostics on the MCA/INIT handler that - failed, not on the task that was originally running. Again this - requires set_curr_task() so the MCA/INIT handlers can register their - own stack as running on that cpu. Then a recursive error gets a - trace of the failing handler's "task". - -[1] - My (Keith Owens) original design called for ia64 to separate its - struct task and the kernel stacks. Then the MCA/INIT data would be - chained stacks like i386 interrupt stacks. But that required - radical surgery on the rest of ia64, plus extra hard wired TLB - entries with its associated performance degradation. David - Mosberger vetoed that approach. Which meant that separate kernel - stacks meant separate "tasks" for the MCA/INIT handlers. - ---- - -INIT is less complicated than MCA. Pressing the nmi button or using -the equivalent command on the management console sends INIT to all -cpus. SAL picks one of the cpus as the monarch and the rest are -slaves. All the OS INIT handlers are entered at approximately the same -time. The OS monarch prints the state of all tasks and returns, after -which the slaves return and the system resumes. - -At least that is what is supposed to happen. Alas there are broken -versions of SAL out there. Some drive all the cpus as monarchs. Some -drive them all as slaves. Some drive one cpu as monarch, wait for that -cpu to return from the OS then drive the rest as slaves. Some versions -of SAL cannot even cope with returning from the OS, they spin inside -SAL on resume. The OS INIT code has workarounds for some of these -broken SAL symptoms, but some simply cannot be fixed from the OS side. - ---- - -The scheduler hooks used by ia64 (curr_task, set_curr_task) are layer -violations. Unfortunately MCA/INIT start off as massive layer -violations (can occur at _any_ time) and they build from there. - -At least ia64 makes an attempt at recovering from hardware errors, but -it is a difficult problem because of the asynchronous nature of these -errors. When processing an unmaskable interrupt we sometimes need -special code to cope with our inability to take any locks. - ---- - -How is ia64 MCA/INIT different from x86 NMI? - -* x86 NMI typically gets delivered to one cpu. MCA/INIT gets sent to - all cpus. - -* x86 NMI cannot be nested. MCA/INIT can be nested, to a depth of 2 - per cpu. - -* x86 has a separate struct task which points to one of multiple kernel - stacks. ia64 has the struct task embedded in the single kernel - stack, so switching stack means switching task. - -* x86 does not call the BIOS so the NMI handler does not have to worry - about any registers having changed. MCA/INIT can occur while the cpu - is in PAL in physical mode, with undefined registers and an undefined - kernel stack. - -* i386 backtrace is not very sensitive to whether a process is running - or not. ia64 unwind is very, very sensitive to whether a process is - running or not. - ---- - -What happens when MCA/INIT is delivered what a cpu is running user -space code? - -The user mode registers are stored in the RSE area of the MCA/INIT on -entry to the OS and are restored from there on return to SAL, so user -mode registers are preserved across a recoverable MCA/INIT. Since the -OS has no idea what unwind data is available for the user space stack, -MCA/INIT never tries to backtrace user space. Which means that the OS -does not bother making the user space process look like a blocked task, -i.e. the OS does not copy pt_regs and switch_stack to the user space -stack. Also the OS has no idea how big the user space RSE and memory -stacks are, which makes it too risky to copy the saved state to a user -mode stack. - ---- - -How do we get a backtrace on the tasks that were running when MCA/INIT -was delivered? - -mca.c:::ia64_mca_modify_original_stack(). That identifies and -verifies the original kernel stack, copies the dirty registers from -the MCA/INIT stack's RSE to the original stack's RSE, copies the -skeleton struct pt_regs and switch_stack to the original stack, fills -in the skeleton structures from the PAL minstate area and updates the -original stack's thread.ksp. That makes the original stack look -exactly like any other blocked task, i.e. it now appears to be -sleeping. To get a backtrace, just start with thread.ksp for the -original task and unwind like any other sleeping task. - ---- - -How do we identify the tasks that were running when MCA/INIT was -delivered? - -If the previous task has been verified and converted to a blocked -state, then sos->prev_task on the MCA/INIT stack is updated to point to -the previous task. You can look at that field in dumps or debuggers. -To help distinguish between the handler and the original tasks, -handlers have _TIF_MCA_INIT set in thread_info.flags. - -The sos data is always in the MCA/INIT handler stack, at offset -MCA_SOS_OFFSET. You can get that value from mca_asm.h or calculate it -as KERNEL_STACK_SIZE - sizeof(struct pt_regs) - sizeof(struct -ia64_sal_os_state), with 16 byte alignment for all structures. - -Also the comm field of the MCA/INIT task is modified to include the pid -of the original task, for humans to use. For example, a comm field of -'MCA 12159' means that pid 12159 was running when the MCA was -delivered. diff --git a/Documentation/arch/ia64/serial.rst b/Documentation/arch/ia64/serial.rst deleted file mode 100644 index 1de70c305a79..000000000000 --- a/Documentation/arch/ia64/serial.rst +++ /dev/null @@ -1,165 +0,0 @@ -============== -Serial Devices -============== - -Serial Device Naming -==================== - - As of 2.6.10, serial devices on ia64 are named based on the - order of ACPI and PCI enumeration. The first device in the - ACPI namespace (if any) becomes /dev/ttyS0, the second becomes - /dev/ttyS1, etc., and PCI devices are named sequentially - starting after the ACPI devices. - - Prior to 2.6.10, there were confusing exceptions to this: - - - Firmware on some machines (mostly from HP) provides an HCDP - table[1] that tells the kernel about devices that can be used - as a serial console. If the user specified "console=ttyS0" - or the EFI ConOut path contained only UART devices, the - kernel registered the device described by the HCDP as - /dev/ttyS0. - - - If there was no HCDP, we assumed there were UARTs at the - legacy COM port addresses (I/O ports 0x3f8 and 0x2f8), so - the kernel registered those as /dev/ttyS0 and /dev/ttyS1. - - Any additional ACPI or PCI devices were registered sequentially - after /dev/ttyS0 as they were discovered. - - With an HCDP, device names changed depending on EFI configuration - and "console=" arguments. Without an HCDP, device names didn't - change, but we registered devices that might not really exist. - - For example, an HP rx1600 with a single built-in serial port - (described in the ACPI namespace) plus an MP[2] (a PCI device) has - these ports: - - ========== ========== ============ ============ ======= - Type MMIO pre-2.6.10 pre-2.6.10 2.6.10+ - address - (EFI console (EFI console - on builtin) on MP port) - ========== ========== ============ ============ ======= - builtin 0xff5e0000 ttyS0 ttyS1 ttyS0 - MP UPS 0xf8031000 ttyS1 ttyS2 ttyS1 - MP Console 0xf8030000 ttyS2 ttyS0 ttyS2 - MP 2 0xf8030010 ttyS3 ttyS3 ttyS3 - MP 3 0xf8030038 ttyS4 ttyS4 ttyS4 - ========== ========== ============ ============ ======= - -Console Selection -================= - - EFI knows what your console devices are, but it doesn't tell the - kernel quite enough to actually locate them. The DIG64 HCDP - table[1] does tell the kernel where potential serial console - devices are, but not all firmware supplies it. Also, EFI supports - multiple simultaneous consoles and doesn't tell the kernel which - should be the "primary" one. - - So how do you tell Linux which console device to use? - - - If your firmware supplies the HCDP, it is simplest to - configure EFI with a single device (either a UART or a VGA - card) as the console. Then you don't need to tell Linux - anything; the kernel will automatically use the EFI console. - - (This works only in 2.6.6 or later; prior to that you had - to specify "console=ttyS0" to get a serial console.) - - - Without an HCDP, Linux defaults to a VGA console unless you - specify a "console=" argument. - - NOTE: Don't assume that a serial console device will be /dev/ttyS0. - It might be ttyS1, ttyS2, etc. Make sure you have the appropriate - entries in /etc/inittab (for getty) and /etc/securetty (to allow - root login). - -Early Serial Console -==================== - - The kernel can't start using a serial console until it knows where - the device lives. Normally this happens when the driver enumerates - all the serial devices, which can happen a minute or more after the - kernel starts booting. - - 2.6.10 and later kernels have an "early uart" driver that works - very early in the boot process. The kernel will automatically use - this if the user supplies an argument like "console=uart,io,0x3f8", - or if the EFI console path contains only a UART device and the - firmware supplies an HCDP. - -Troubleshooting Serial Console Problems -======================================= - - No kernel output after elilo prints "Uncompressing Linux... done": - - - You specified "console=ttyS0" but Linux changed the device - to which ttyS0 refers. Configure exactly one EFI console - device[3] and remove the "console=" option. - - - The EFI console path contains both a VGA device and a UART. - EFI and elilo use both, but Linux defaults to VGA. Remove - the VGA device from the EFI console path[3]. - - - Multiple UARTs selected as EFI console devices. EFI and - elilo use all selected devices, but Linux uses only one. - Make sure only one UART is selected in the EFI console - path[3]. - - - You're connected to an HP MP port[2] but have a non-MP UART - selected as EFI console device. EFI uses the MP as a - console device even when it isn't explicitly selected. - Either move the console cable to the non-MP UART, or change - the EFI console path[3] to the MP UART. - - Long pause (60+ seconds) between "Uncompressing Linux... done" and - start of kernel output: - - - No early console because you used "console=ttyS<n>". Remove - the "console=" option if your firmware supplies an HCDP. - - - If you don't have an HCDP, the kernel doesn't know where - your console lives until the driver discovers serial - devices. Use "console=uart,io,0x3f8" (or appropriate - address for your machine). - - Kernel and init script output works fine, but no "login:" prompt: - - - Add getty entry to /etc/inittab for console tty. Look for - the "Adding console on ttyS<n>" message that tells you which - device is the console. - - "login:" prompt, but can't login as root: - - - Add entry to /etc/securetty for console tty. - - No ACPI serial devices found in 2.6.17 or later: - - - Turn on CONFIG_PNP and CONFIG_PNPACPI. Prior to 2.6.17, ACPI - serial devices were discovered by 8250_acpi. In 2.6.17, - 8250_acpi was replaced by the combination of 8250_pnp and - CONFIG_PNPACPI. - - - -[1] - http://www.dig64.org/specifications/agreement - The table was originally defined as the "HCDP" for "Headless - Console/Debug Port." The current version is the "PCDP" for - "Primary Console and Debug Port Devices." - -[2] - The HP MP (management processor) is a PCI device that provides - several UARTs. One of the UARTs is often used as a console; the - EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart". - The external connection is usually a 25-pin connector, and a - special dongle converts that to three 9-pin connectors, one of - which is labelled "Console." - -[3] - EFI console devices are configured using the EFI Boot Manager - "Boot option maintenance" menu. You may have to interrupt the - boot sequence to use this menu, and you will have to reset the - box after changing console configuration. diff --git a/Documentation/arch/index.rst b/Documentation/arch/index.rst index 84b80255b851..3f9962e45c09 100644 --- a/Documentation/arch/index.rst +++ b/Documentation/arch/index.rst @@ -12,15 +12,14 @@ implementation. arc/index arm/index arm64/index - ia64/index loongarch/index m68k/index mips/index nios2/index openrisc/index parisc/index - ../powerpc/index - ../riscv/index + powerpc/index + riscv/index s390/index sh/index sparc/index diff --git a/Documentation/powerpc/associativity.rst b/Documentation/arch/powerpc/associativity.rst index 4d01c7368561..4d01c7368561 100644 --- a/Documentation/powerpc/associativity.rst +++ b/Documentation/arch/powerpc/associativity.rst diff --git a/Documentation/powerpc/booting.rst b/Documentation/arch/powerpc/booting.rst index 11aa440f98cc..11aa440f98cc 100644 --- a/Documentation/powerpc/booting.rst +++ b/Documentation/arch/powerpc/booting.rst diff --git a/Documentation/powerpc/bootwrapper.rst b/Documentation/arch/powerpc/bootwrapper.rst index cdfa2bc8425f..cdfa2bc8425f 100644 --- a/Documentation/powerpc/bootwrapper.rst +++ b/Documentation/arch/powerpc/bootwrapper.rst diff --git a/Documentation/powerpc/cpu_families.rst b/Documentation/arch/powerpc/cpu_families.rst index eb7e60649b43..eb7e60649b43 100644 --- a/Documentation/powerpc/cpu_families.rst +++ b/Documentation/arch/powerpc/cpu_families.rst diff --git a/Documentation/powerpc/cpu_features.rst b/Documentation/arch/powerpc/cpu_features.rst index b7bcdd2f41bb..b7bcdd2f41bb 100644 --- a/Documentation/powerpc/cpu_features.rst +++ b/Documentation/arch/powerpc/cpu_features.rst diff --git a/Documentation/powerpc/cxl.rst b/Documentation/arch/powerpc/cxl.rst index d2d77057610e..d2d77057610e 100644 --- a/Documentation/powerpc/cxl.rst +++ b/Documentation/arch/powerpc/cxl.rst diff --git a/Documentation/powerpc/cxlflash.rst b/Documentation/arch/powerpc/cxlflash.rst index cea67931b3b9..e8f488acfa41 100644 --- a/Documentation/powerpc/cxlflash.rst +++ b/Documentation/arch/powerpc/cxlflash.rst @@ -32,7 +32,7 @@ Introduction responsible for the initialization of the adapter, setting up the special path for user space access, and performing error recovery. It communicates directly the Flash Accelerator Functional Unit (AFU) - as described in Documentation/powerpc/cxl.rst. + as described in Documentation/arch/powerpc/cxl.rst. The cxlflash driver supports two, mutually exclusive, modes of operation at the device (LUN) level: diff --git a/Documentation/powerpc/dawr-power9.rst b/Documentation/arch/powerpc/dawr-power9.rst index 310f2e0cea81..310f2e0cea81 100644 --- a/Documentation/powerpc/dawr-power9.rst +++ b/Documentation/arch/powerpc/dawr-power9.rst diff --git a/Documentation/powerpc/dexcr.rst b/Documentation/arch/powerpc/dexcr.rst index 615a631f51fa..615a631f51fa 100644 --- a/Documentation/powerpc/dexcr.rst +++ b/Documentation/arch/powerpc/dexcr.rst diff --git a/Documentation/powerpc/dscr.rst b/Documentation/arch/powerpc/dscr.rst index f735ec5375d5..f735ec5375d5 100644 --- a/Documentation/powerpc/dscr.rst +++ b/Documentation/arch/powerpc/dscr.rst diff --git a/Documentation/powerpc/eeh-pci-error-recovery.rst b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst index d6643a91bdf8..d6643a91bdf8 100644 --- a/Documentation/powerpc/eeh-pci-error-recovery.rst +++ b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst diff --git a/Documentation/powerpc/elf_hwcaps.rst b/Documentation/arch/powerpc/elf_hwcaps.rst index 3366e5b18e67..4c896cf077c2 100644 --- a/Documentation/powerpc/elf_hwcaps.rst +++ b/Documentation/arch/powerpc/elf_hwcaps.rst @@ -202,7 +202,7 @@ PPC_FEATURE2_VEC_CRYPTO PPC_FEATURE2_HTM_NOSC System calls fail if called in a transactional state, see - Documentation/powerpc/syscall64-abi.rst + Documentation/arch/powerpc/syscall64-abi.rst PPC_FEATURE2_ARCH_3_00 The processor supports the v3.0B / v3.0C userlevel architecture. Processors @@ -217,11 +217,11 @@ PPC_FEATURE2_DARN PPC_FEATURE2_SCV The scv 0 instruction may be used for system calls, see - Documentation/powerpc/syscall64-abi.rst. + Documentation/arch/powerpc/syscall64-abi.rst. PPC_FEATURE2_HTM_NO_SUSPEND A limited Transactional Memory facility that does not support suspend is - available, see Documentation/powerpc/transactional_memory.rst. + available, see Documentation/arch/powerpc/transactional_memory.rst. PPC_FEATURE2_ARCH_3_1 The processor supports the v3.1 userlevel architecture. Processors diff --git a/Documentation/powerpc/elfnote.rst b/Documentation/arch/powerpc/elfnote.rst index 3ec8d61e9a33..3ec8d61e9a33 100644 --- a/Documentation/powerpc/elfnote.rst +++ b/Documentation/arch/powerpc/elfnote.rst diff --git a/Documentation/powerpc/features.rst b/Documentation/arch/powerpc/features.rst index aeae73df86b0..aeae73df86b0 100644 --- a/Documentation/powerpc/features.rst +++ b/Documentation/arch/powerpc/features.rst diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/arch/powerpc/firmware-assisted-dump.rst index e363fc48529a..e363fc48529a 100644 --- a/Documentation/powerpc/firmware-assisted-dump.rst +++ b/Documentation/arch/powerpc/firmware-assisted-dump.rst diff --git a/Documentation/powerpc/hvcs.rst b/Documentation/arch/powerpc/hvcs.rst index 6808acde672f..6808acde672f 100644 --- a/Documentation/powerpc/hvcs.rst +++ b/Documentation/arch/powerpc/hvcs.rst diff --git a/Documentation/powerpc/imc.rst b/Documentation/arch/powerpc/imc.rst index 633bcee7dc85..633bcee7dc85 100644 --- a/Documentation/powerpc/imc.rst +++ b/Documentation/arch/powerpc/imc.rst diff --git a/Documentation/powerpc/index.rst b/Documentation/arch/powerpc/index.rst index a50834798454..9749f6dc258f 100644 --- a/Documentation/powerpc/index.rst +++ b/Documentation/arch/powerpc/index.rst @@ -26,6 +26,7 @@ powerpc isa-versions kaslr-booke32 mpc52xx + kvm-nested papr_hcalls pci_iov_resource_on_powernv pmu-ebb diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/arch/powerpc/isa-versions.rst index a8d6b6028b3e..a8d6b6028b3e 100644 --- a/Documentation/powerpc/isa-versions.rst +++ b/Documentation/arch/powerpc/isa-versions.rst diff --git a/Documentation/powerpc/kasan.txt b/Documentation/arch/powerpc/kasan.txt index a4f647e4fffa..a4f647e4fffa 100644 --- a/Documentation/powerpc/kasan.txt +++ b/Documentation/arch/powerpc/kasan.txt diff --git a/Documentation/powerpc/kaslr-booke32.rst b/Documentation/arch/powerpc/kaslr-booke32.rst index 5681c1d1b65b..5681c1d1b65b 100644 --- a/Documentation/powerpc/kaslr-booke32.rst +++ b/Documentation/arch/powerpc/kaslr-booke32.rst diff --git a/Documentation/arch/powerpc/kvm-nested.rst b/Documentation/arch/powerpc/kvm-nested.rst new file mode 100644 index 000000000000..630602a8aa00 --- /dev/null +++ b/Documentation/arch/powerpc/kvm-nested.rst @@ -0,0 +1,634 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================================== +Nested KVM on POWER +==================================== + +Introduction +============ + +This document explains how a guest operating system can act as a +hypervisor and run nested guests through the use of hypercalls, if the +hypervisor has implemented them. The terms L0, L1, and L2 are used to +refer to different software entities. L0 is the hypervisor mode entity +that would normally be called the "host" or "hypervisor". L1 is a +guest virtual machine that is directly run under L0 and is initiated +and controlled by L0. L2 is a guest virtual machine that is initiated +and controlled by L1 acting as a hypervisor. + +Existing API +============ + +Linux/KVM has had support for Nesting as an L0 or L1 since 2018 + +The L0 code was added:: + + commit 8e3f5fc1045dc49fd175b978c5457f5f51e7a2ce + Author: Paul Mackerras <paulus@ozlabs.org> + Date: Mon Oct 8 16:31:03 2018 +1100 + KVM: PPC: Book3S HV: Framework and hcall stubs for nested virtualization + +The L1 code was added:: + + commit 360cae313702cdd0b90f82c261a8302fecef030a + Author: Paul Mackerras <paulus@ozlabs.org> + Date: Mon Oct 8 16:31:04 2018 +1100 + KVM: PPC: Book3S HV: Nested guest entry via hypercall + +This API works primarily using a single hcall h_enter_nested(). This +call made by the L1 to tell the L0 to start an L2 vCPU with the given +state. The L0 then starts this L2 and runs until an L2 exit condition +is reached. Once the L2 exits, the state of the L2 is given back to +the L1 by the L0. The full L2 vCPU state is always transferred from +and to L1 when the L2 is run. The L0 doesn't keep any state on the L2 +vCPU (except in the short sequence in the L0 on L1 -> L2 entry and L2 +-> L1 exit). + +The only state kept by the L0 is the partition table. The L1 registers +it's partition table using the h_set_partition_table() hcall. All +other state held by the L0 about the L2s is cached state (such as +shadow page tables). + +The L1 may run any L2 or vCPU without first informing the L0. It +simply starts the vCPU using h_enter_nested(). The creation of L2s and +vCPUs is done implicitly whenever h_enter_nested() is called. + +In this document, we call this existing API the v1 API. + +New PAPR API +=============== + +The new PAPR API changes from the v1 API such that the creating L2 and +associated vCPUs is explicit. In this document, we call this the v2 +API. + +h_enter_nested() is replaced with H_GUEST_VCPU_RUN(). Before this can +be called the L1 must explicitly create the L2 using h_guest_create() +and any associated vCPUs() created with h_guest_create_vCPU(). Getting +and setting vCPU state can also be performed using h_guest_{g|s}et +hcall. + +The basic execution flow is for an L1 to create an L2, run it, and +delete it is: + +- L1 and L0 negotiate capabilities with H_GUEST_{G,S}ET_CAPABILITIES() + (normally at L1 boot time). + +- L1 requests the L0 create an L2 with H_GUEST_CREATE() and receives a token + +- L1 requests the L0 create an L2 vCPU with H_GUEST_CREATE_VCPU() + +- L1 and L0 communicate the vCPU state using the H_GUEST_{G,S}ET() hcall + +- L1 requests the L0 runs the vCPU running H_GUEST_VCPU_RUN() hcall + +- L1 deletes L2 with H_GUEST_DELETE() + +More details of the individual hcalls follows: + +HCALL Details +============= + +This documentation is provided to give an overall understating of the +API. It doesn't aim to provide all the details required to implement +an L1 or L0. Latest version of PAPR can be referred to for more details. + +All these HCALLs are made by the L1 to the L0. + +H_GUEST_GET_CAPABILITIES() +-------------------------- + +This is called to get the capabilities of the L0 nested +hypervisor. This includes capabilities such the CPU versions (eg +POWER9, POWER10) that are supported as L2s:: + + H_GUEST_GET_CAPABILITIES(uint64 flags) + + Parameters: + Input: + flags: Reserved + Output: + R3: Return code + R4: Hypervisor Supported Capabilities bitmap 1 + +H_GUEST_SET_CAPABILITIES() +-------------------------- + +This is called to inform the L0 of the capabilities of the L1 +hypervisor. The set of flags passed here are the same as +H_GUEST_GET_CAPABILITIES() + +Typically, GET will be called first and then SET will be called with a +subset of the flags returned from GET. This process allows the L0 and +L1 to negotiate an agreed set of capabilities:: + + H_GUEST_SET_CAPABILITIES(uint64 flags, + uint64 capabilitiesBitmap1) + Parameters: + Input: + flags: Reserved + capabilitiesBitmap1: Only capabilities advertised through + H_GUEST_GET_CAPABILITIES + Output: + R3: Return code + R4: If R3 = H_P2: The number of invalid bitmaps + R5: If R3 = H_P2: The index of first invalid bitmap + +H_GUEST_CREATE() +---------------- + +This is called to create an L2. A unique ID of the L2 created +(similar to an LPID) is returned, which can be used on subsequent HCALLs to +identify the L2:: + + H_GUEST_CREATE(uint64 flags, + uint64 continueToken); + Parameters: + Input: + flags: Reserved + continueToken: Initial call set to -1. Subsequent calls, + after H_Busy or H_LongBusyOrder has been + returned, value that was returned in R4. + Output: + R3: Return code. Notable: + H_Not_Enough_Resources: Unable to create Guest VCPU due to not + enough Hypervisor memory. See H_GUEST_CREATE_GET_STATE(flags = + takeOwnershipOfVcpuState) + R4: If R3 = H_Busy or_H_LongBusyOrder -> continueToken + +H_GUEST_CREATE_VCPU() +--------------------- + +This is called to create a vCPU associated with an L2. The L2 id +(returned from H_GUEST_CREATE()) should be passed it. Also passed in +is a unique (for this L2) vCPUid. This vCPUid is allocated by the +L1:: + + H_GUEST_CREATE_VCPU(uint64 flags, + uint64 guestId, + uint64 vcpuId); + Parameters: + Input: + flags: Reserved + guestId: ID obtained from H_GUEST_CREATE + vcpuId: ID of the vCPU to be created. This must be within the + range of 0 to 2047 + Output: + R3: Return code. Notable: + H_Not_Enough_Resources: Unable to create Guest VCPU due to not + enough Hypervisor memory. See H_GUEST_CREATE_GET_STATE(flags = + takeOwnershipOfVcpuState) + +H_GUEST_GET_STATE() +------------------- + +This is called to get state associated with an L2 (Guest-wide or vCPU specific). +This info is passed via the Guest State Buffer (GSB), a standard format as +explained later in this doc, necessary details below: + +This can get either L2 wide or vcpu specific information. Examples of +L2 wide is the timebase offset or process scoped page table +info. Examples of vCPU specific are GPRs or VSRs. A bit in the flags +parameter specifies if this call is L2 wide or vCPU specific and the +IDs in the GSB must match this. + +The L1 provides a pointer to the GSB as a parameter to this call. Also +provided is the L2 and vCPU IDs associated with the state to set. + +The L1 writes only the IDs and sizes in the GSB. L0 writes the +associated values for each ID in the GSB:: + + H_GUEST_GET_STATE(uint64 flags, + uint64 guestId, + uint64 vcpuId, + uint64 dataBuffer, + uint64 dataBufferSizeInBytes); + Parameters: + Input: + flags: + Bit 0: getGuestWideState: Request state of the Guest instead + of an individual VCPU. + Bit 1: takeOwnershipOfVcpuState Indicate the L1 is taking + over ownership of the VCPU state and that the L0 can free + the storage holding the state. The VCPU state will need to + be returned to the Hypervisor via H_GUEST_SET_STATE prior + to H_GUEST_RUN_VCPU being called for this VCPU. The data + returned in the dataBuffer is in a Hypervisor internal + format. + Bits 2-63: Reserved + guestId: ID obtained from H_GUEST_CREATE + vcpuId: ID of the vCPU pass to H_GUEST_CREATE_VCPU + dataBuffer: A L1 real address of the GSB. + If takeOwnershipOfVcpuState, size must be at least the size + returned by ID=0x0001 + dataBufferSizeInBytes: Size of dataBuffer + Output: + R3: Return code + R4: If R3 = H_Invalid_Element_Id: The array index of the bad + element ID. + If R3 = H_Invalid_Element_Size: The array index of the bad + element size. + If R3 = H_Invalid_Element_Value: The array index of the bad + element value. + +H_GUEST_SET_STATE() +------------------- + +This is called to set L2 wide or vCPU specific L2 state. This info is +passed via the Guest State Buffer (GSB), necessary details below: + +This can set either L2 wide or vcpu specific information. Examples of +L2 wide is the timebase offset or process scoped page table +info. Examples of vCPU specific are GPRs or VSRs. A bit in the flags +parameter specifies if this call is L2 wide or vCPU specific and the +IDs in the GSB must match this. + +The L1 provides a pointer to the GSB as a parameter to this call. Also +provided is the L2 and vCPU IDs associated with the state to set. + +The L1 writes all values in the GSB and the L0 only reads the GSB for +this call:: + + H_GUEST_SET_STATE(uint64 flags, + uint64 guestId, + uint64 vcpuId, + uint64 dataBuffer, + uint64 dataBufferSizeInBytes); + Parameters: + Input: + flags: + Bit 0: getGuestWideState: Request state of the Guest instead + of an individual VCPU. + Bit 1: returnOwnershipOfVcpuState Return Guest VCPU state. See + GET_STATE takeOwnershipOfVcpuState + Bits 2-63: Reserved + guestId: ID obtained from H_GUEST_CREATE + vcpuId: ID of the vCPU pass to H_GUEST_CREATE_VCPU + dataBuffer: A L1 real address of the GSB. + If takeOwnershipOfVcpuState, size must be at least the size + returned by ID=0x0001 + dataBufferSizeInBytes: Size of dataBuffer + Output: + R3: Return code + R4: If R3 = H_Invalid_Element_Id: The array index of the bad + element ID. + If R3 = H_Invalid_Element_Size: The array index of the bad + element size. + If R3 = H_Invalid_Element_Value: The array index of the bad + element value. + +H_GUEST_RUN_VCPU() +------------------ + +This is called to run an L2 vCPU. The L2 and vCPU IDs are passed in as +parameters. The vCPU runs with the state set previously using +H_GUEST_SET_STATE(). When the L2 exits, the L1 will resume from this +hcall. + +This hcall also has associated input and output GSBs. Unlike +H_GUEST_{S,G}ET_STATE(), these GSB pointers are not passed in as +parameters to the hcall (This was done in the interest of +performance). The locations of these GSBs must be preregistered using +the H_GUEST_SET_STATE() call with ID 0x0c00 and 0x0c01 (see table +below). + +The input GSB may contain only VCPU specific elements to be set. This +GSB may also contain zero elements (ie 0 in the first 4 bytes of the +GSB) if nothing needs to be set. + +On exit from the hcall, the output buffer is filled with elements +determined by the L0. The reason for the exit is contained in GPR4 (ie +NIP is put in GPR4). The elements returned depend on the exit +type. For example, if the exit reason is the L2 doing a hcall (GPR4 = +0xc00), then GPR3-12 are provided in the output GSB as this is the +state likely needed to service the hcall. If additional state is +needed, H_GUEST_GET_STATE() may be called by the L1. + +To synthesize interrupts in the L2, when calling H_GUEST_RUN_VCPU() +the L1 may set a flag (as a hcall parameter) and the L0 will +synthesize the interrupt in the L2. Alternatively, the L1 may +synthesize the interrupt itself using H_GUEST_SET_STATE() or the +H_GUEST_RUN_VCPU() input GSB to set the state appropriately:: + + H_GUEST_RUN_VCPU(uint64 flags, + uint64 guestId, + uint64 vcpuId, + uint64 dataBuffer, + uint64 dataBufferSizeInBytes); + Parameters: + Input: + flags: + Bit 0: generateExternalInterrupt: Generate an external interrupt + Bit 1: generatePrivilegedDoorbell: Generate a Privileged Doorbell + Bit 2: sendToSystemResetâ€: Generate a System Reset Interrupt + Bits 3-63: Reserved + guestId: ID obtained from H_GUEST_CREATE + vcpuId: ID of the vCPU pass to H_GUEST_CREATE_VCPU + Output: + R3: Return code + R4: If R3 = H_Success: The reason L1 VCPU exited (ie. NIA) + 0x000: The VCPU stopped running for an unspecified reason. An + example of this is the Hypervisor stopping a VCPU running + due to an outstanding interrupt for the Host Partition. + 0x980: HDEC + 0xC00: HCALL + 0xE00: HDSI + 0xE20: HISI + 0xE40: HEA + 0xF80: HV Fac Unavail + If R3 = H_Invalid_Element_Id, H_Invalid_Element_Size, or + H_Invalid_Element_Value: R4 is offset of the invalid element + in the input buffer. + +H_GUEST_DELETE() +---------------- + +This is called to delete an L2. All associated vCPUs are also +deleted. No specific vCPU delete call is provided. + +A flag may be provided to delete all guests. This is used to reset the +L0 in the case of kdump/kexec:: + + H_GUEST_DELETE(uint64 flags, + uint64 guestId) + Parameters: + Input: + flags: + Bit 0: deleteAllGuests: deletes all guests + Bits 1-63: Reserved + guestId: ID obtained from H_GUEST_CREATE + Output: + R3: Return code + +Guest State Buffer +================== + +The Guest State Buffer (GSB) is the main method of communicating state +about the L2 between the L1 and L0 via H_GUEST_{G,S}ET() and +H_GUEST_VCPU_RUN() calls. + +State may be associated with a whole L2 (eg timebase offset) or a +specific L2 vCPU (eg. GPR state). Only L2 VCPU state maybe be set by +H_GUEST_VCPU_RUN(). + +All data in the GSB is big endian (as is standard in PAPR) + +The Guest state buffer has a header which gives the number of +elements, followed by the GSB elements themselves. + +GSB header: + ++----------+----------+-------------------------------------------+ +| Offset | Size | Purpose | +| Bytes | Bytes | | ++==========+==========+===========================================+ +| 0 | 4 | Number of elements | ++----------+----------+-------------------------------------------+ +| 4 | | Guest state buffer elements | ++----------+----------+-------------------------------------------+ + +GSB element: + ++----------+----------+-------------------------------------------+ +| Offset | Size | Purpose | +| Bytes | Bytes | | ++==========+==========+===========================================+ +| 0 | 2 | ID | ++----------+----------+-------------------------------------------+ +| 2 | 2 | Size of Value | ++----------+----------+-------------------------------------------+ +| 4 | As above | Value | ++----------+----------+-------------------------------------------+ + +The ID in the GSB element specifies what is to be set. This includes +archtected state like GPRs, VSRs, SPRs, plus also some meta data about +the partition like the timebase offset and partition scoped page +table information. + ++--------+-------+----+--------+----------------------------------+ +| ID | Size | RW | Thread | Details | +| | Bytes | | Guest | | +| | | | Scope | | ++========+=======+====+========+==================================+ +| 0x0000 | | RW | TG | NOP element | ++--------+-------+----+--------+----------------------------------+ +| 0x0001 | 0x08 | R | G | Size of L0 vCPU state. See: | +| | | | | H_GUEST_GET_STATE: | +| | | | | flags = takeOwnershipOfVcpuState | ++--------+-------+----+--------+----------------------------------+ +| 0x0002 | 0x08 | R | G | Size Run vCPU out buffer | ++--------+-------+----+--------+----------------------------------+ +| 0x0003 | 0x04 | RW | G | Logical PVR | ++--------+-------+----+--------+----------------------------------+ +| 0x0004 | 0x08 | RW | G | TB Offset (L1 relative) | ++--------+-------+----+--------+----------------------------------+ +| 0x0005 | 0x18 | RW | G |Partition scoped page tbl info: | +| | | | | | +| | | | |- 0x00 Addr part scope table | +| | | | |- 0x08 Num addr bits | +| | | | |- 0x10 Size root dir | ++--------+-------+----+--------+----------------------------------+ +| 0x0006 | 0x10 | RW | G |Process Table Information: | +| | | | | | +| | | | |- 0x0 Addr proc scope table | +| | | | |- 0x8 Table size. | ++--------+-------+----+--------+----------------------------------+ +| 0x0007-| | | | Reserved | +| 0x0BFF | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x0C00 | 0x10 | RW | T |Run vCPU Input Buffer: | +| | | | | | +| | | | |- 0x0 Addr of buffer | +| | | | |- 0x8 Buffer Size. | ++--------+-------+----+--------+----------------------------------+ +| 0x0C01 | 0x10 | RW | T |Run vCPU Output Buffer: | +| | | | | | +| | | | |- 0x0 Addr of buffer | +| | | | |- 0x8 Buffer Size. | ++--------+-------+----+--------+----------------------------------+ +| 0x0C02 | 0x08 | RW | T | vCPU VPA Address | ++--------+-------+----+--------+----------------------------------+ +| 0x0C03-| | | | Reserved | +| 0x0FFF | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x1000-| 0x08 | RW | T | GPR 0-31 | +| 0x101F | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x1020 | 0x08 | T | T | HDEC expiry TB | ++--------+-------+----+--------+----------------------------------+ +| 0x1021 | 0x08 | RW | T | NIA | ++--------+-------+----+--------+----------------------------------+ +| 0x1022 | 0x08 | RW | T | MSR | ++--------+-------+----+--------+----------------------------------+ +| 0x1023 | 0x08 | RW | T | LR | ++--------+-------+----+--------+----------------------------------+ +| 0x1024 | 0x08 | RW | T | XER | ++--------+-------+----+--------+----------------------------------+ +| 0x1025 | 0x08 | RW | T | CTR | ++--------+-------+----+--------+----------------------------------+ +| 0x1026 | 0x08 | RW | T | CFAR | ++--------+-------+----+--------+----------------------------------+ +| 0x1027 | 0x08 | RW | T | SRR0 | ++--------+-------+----+--------+----------------------------------+ +| 0x1028 | 0x08 | RW | T | SRR1 | ++--------+-------+----+--------+----------------------------------+ +| 0x1029 | 0x08 | RW | T | DAR | ++--------+-------+----+--------+----------------------------------+ +| 0x102A | 0x08 | RW | T | DEC expiry TB | ++--------+-------+----+--------+----------------------------------+ +| 0x102B | 0x08 | RW | T | VTB | ++--------+-------+----+--------+----------------------------------+ +| 0x102C | 0x08 | RW | T | LPCR | ++--------+-------+----+--------+----------------------------------+ +| 0x102D | 0x08 | RW | T | HFSCR | ++--------+-------+----+--------+----------------------------------+ +| 0x102E | 0x08 | RW | T | FSCR | ++--------+-------+----+--------+----------------------------------+ +| 0x102F | 0x08 | RW | T | FPSCR | ++--------+-------+----+--------+----------------------------------+ +| 0x1030 | 0x08 | RW | T | DAWR0 | ++--------+-------+----+--------+----------------------------------+ +| 0x1031 | 0x08 | RW | T | DAWR1 | ++--------+-------+----+--------+----------------------------------+ +| 0x1032 | 0x08 | RW | T | CIABR | ++--------+-------+----+--------+----------------------------------+ +| 0x1033 | 0x08 | RW | T | PURR | ++--------+-------+----+--------+----------------------------------+ +| 0x1034 | 0x08 | RW | T | SPURR | ++--------+-------+----+--------+----------------------------------+ +| 0x1035 | 0x08 | RW | T | IC | ++--------+-------+----+--------+----------------------------------+ +| 0x1036-| 0x08 | RW | T | SPRG 0-3 | +| 0x1039 | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x103A | 0x08 | W | T | PPR | ++--------+-------+----+--------+----------------------------------+ +| 0x103B | 0x08 | RW | T | MMCR 0-3 | +| 0x103E | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x103F | 0x08 | RW | T | MMCRA | ++--------+-------+----+--------+----------------------------------+ +| 0x1040 | 0x08 | RW | T | SIER | ++--------+-------+----+--------+----------------------------------+ +| 0x1041 | 0x08 | RW | T | SIER 2 | ++--------+-------+----+--------+----------------------------------+ +| 0x1042 | 0x08 | RW | T | SIER 3 | ++--------+-------+----+--------+----------------------------------+ +| 0x1043 | 0x08 | RW | T | BESCR | ++--------+-------+----+--------+----------------------------------+ +| 0x1044 | 0x08 | RW | T | EBBHR | ++--------+-------+----+--------+----------------------------------+ +| 0x1045 | 0x08 | RW | T | EBBRR | ++--------+-------+----+--------+----------------------------------+ +| 0x1046 | 0x08 | RW | T | AMR | ++--------+-------+----+--------+----------------------------------+ +| 0x1047 | 0x08 | RW | T | IAMR | ++--------+-------+----+--------+----------------------------------+ +| 0x1048 | 0x08 | RW | T | AMOR | ++--------+-------+----+--------+----------------------------------+ +| 0x1049 | 0x08 | RW | T | UAMOR | ++--------+-------+----+--------+----------------------------------+ +| 0x104A | 0x08 | RW | T | SDAR | ++--------+-------+----+--------+----------------------------------+ +| 0x104B | 0x08 | RW | T | SIAR | ++--------+-------+----+--------+----------------------------------+ +| 0x104C | 0x08 | RW | T | DSCR | ++--------+-------+----+--------+----------------------------------+ +| 0x104D | 0x08 | RW | T | TAR | ++--------+-------+----+--------+----------------------------------+ +| 0x104E | 0x08 | RW | T | DEXCR | ++--------+-------+----+--------+----------------------------------+ +| 0x104F | 0x08 | RW | T | HDEXCR | ++--------+-------+----+--------+----------------------------------+ +| 0x1050 | 0x08 | RW | T | HASHKEYR | ++--------+-------+----+--------+----------------------------------+ +| 0x1051 | 0x08 | RW | T | HASHPKEYR | ++--------+-------+----+--------+----------------------------------+ +| 0x1052 | 0x08 | RW | T | CTRL | ++--------+-------+----+--------+----------------------------------+ +| 0x1053-| | | | Reserved | +| 0x1FFF | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x2000 | 0x04 | RW | T | CR | ++--------+-------+----+--------+----------------------------------+ +| 0x2001 | 0x04 | RW | T | PIDR | ++--------+-------+----+--------+----------------------------------+ +| 0x2002 | 0x04 | RW | T | DSISR | ++--------+-------+----+--------+----------------------------------+ +| 0x2003 | 0x04 | RW | T | VSCR | ++--------+-------+----+--------+----------------------------------+ +| 0x2004 | 0x04 | RW | T | VRSAVE | ++--------+-------+----+--------+----------------------------------+ +| 0x2005 | 0x04 | RW | T | DAWRX0 | ++--------+-------+----+--------+----------------------------------+ +| 0x2006 | 0x04 | RW | T | DAWRX1 | ++--------+-------+----+--------+----------------------------------+ +| 0x2007-| 0x04 | RW | T | PMC 1-6 | +| 0x200c | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x200D | 0x04 | RW | T | WORT | ++--------+-------+----+--------+----------------------------------+ +| 0x200E | 0x04 | RW | T | PSPB | ++--------+-------+----+--------+----------------------------------+ +| 0x200F-| | | | Reserved | +| 0x2FFF | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x3000-| 0x10 | RW | T | VSR 0-63 | +| 0x303F | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0x3040-| | | | Reserved | +| 0xEFFF | | | | | ++--------+-------+----+--------+----------------------------------+ +| 0xF000 | 0x08 | R | T | HDAR | ++--------+-------+----+--------+----------------------------------+ +| 0xF001 | 0x04 | R | T | HDSISR | ++--------+-------+----+--------+----------------------------------+ +| 0xF002 | 0x04 | R | T | HEIR | ++--------+-------+----+--------+----------------------------------+ +| 0xF003 | 0x08 | R | T | ASDR | ++--------+-------+----+--------+----------------------------------+ + + +Miscellaneous info +================== + +State not in ptregs/hvregs +-------------------------- + +In the v1 API, some state is not in the ptregs/hvstate. This includes +the vector register and some SPRs. For the L1 to set this state for +the L2, the L1 loads up these hardware registers before the +h_enter_nested() call and the L0 ensures they end up as the L2 state +(by not touching them). + +The v2 API removes this and explicitly sets this state via the GSB. + +L1 Implementation details: Caching state +---------------------------------------- + +In the v1 API, all state is sent from the L1 to the L0 and vice versa +on every h_enter_nested() hcall. If the L0 is not currently running +any L2s, the L0 has no state information about them. The only +exception to this is the location of the partition table, registered +via h_set_partition_table(). + +The v2 API changes this so that the L0 retains the L2 state even when +it's vCPUs are no longer running. This means that the L1 only needs to +communicate with the L0 about L2 state when it needs to modify the L2 +state, or when it's value is out of date. This provides an opportunity +for performance optimisation. + +When a vCPU exits from a H_GUEST_RUN_VCPU() call, the L1 internally +marks all L2 state as invalid. This means that if the L1 wants to know +the L2 state (say via a kvm_get_one_reg() call), it needs call +H_GUEST_GET_STATE() to get that state. Once it's read, it's marked as +valid in L1 until the L2 is run again. + +Also, when an L1 modifies L2 vcpu state, it doesn't need to write it +to the L0 until that L2 vcpu runs again. Hence when the L1 updates +state (say via a kvm_set_one_reg() call), it writes to an internal L1 +copy and only flushes this copy to the L0 when the L2 runs again via +the H_GUEST_VCPU_RUN() input buffer. + +This lazy updating of state by the L1 avoids unnecessary +H_GUEST_{G|S}ET_STATE() calls. diff --git a/Documentation/powerpc/mpc52xx.rst b/Documentation/arch/powerpc/mpc52xx.rst index 5243b1763fad..5243b1763fad 100644 --- a/Documentation/powerpc/mpc52xx.rst +++ b/Documentation/arch/powerpc/mpc52xx.rst diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/arch/powerpc/papr_hcalls.rst index 80d2c0aadab5..80d2c0aadab5 100644 --- a/Documentation/powerpc/papr_hcalls.rst +++ b/Documentation/arch/powerpc/papr_hcalls.rst diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.rst b/Documentation/arch/powerpc/pci_iov_resource_on_powernv.rst index f5a5793e1613..f5a5793e1613 100644 --- a/Documentation/powerpc/pci_iov_resource_on_powernv.rst +++ b/Documentation/arch/powerpc/pci_iov_resource_on_powernv.rst diff --git a/Documentation/powerpc/pmu-ebb.rst b/Documentation/arch/powerpc/pmu-ebb.rst index 4f474758eb55..4f474758eb55 100644 --- a/Documentation/powerpc/pmu-ebb.rst +++ b/Documentation/arch/powerpc/pmu-ebb.rst diff --git a/Documentation/powerpc/ptrace.rst b/Documentation/arch/powerpc/ptrace.rst index 5629edf4d56e..5629edf4d56e 100644 --- a/Documentation/powerpc/ptrace.rst +++ b/Documentation/arch/powerpc/ptrace.rst diff --git a/Documentation/powerpc/qe_firmware.rst b/Documentation/arch/powerpc/qe_firmware.rst index a358f152b7e7..a358f152b7e7 100644 --- a/Documentation/powerpc/qe_firmware.rst +++ b/Documentation/arch/powerpc/qe_firmware.rst diff --git a/Documentation/powerpc/syscall64-abi.rst b/Documentation/arch/powerpc/syscall64-abi.rst index 56490c4c0c07..56490c4c0c07 100644 --- a/Documentation/powerpc/syscall64-abi.rst +++ b/Documentation/arch/powerpc/syscall64-abi.rst diff --git a/Documentation/powerpc/transactional_memory.rst b/Documentation/arch/powerpc/transactional_memory.rst index 040a20675fd1..040a20675fd1 100644 --- a/Documentation/powerpc/transactional_memory.rst +++ b/Documentation/arch/powerpc/transactional_memory.rst diff --git a/Documentation/powerpc/ultravisor.rst b/Documentation/arch/powerpc/ultravisor.rst index ba6b1bf1cc44..ba6b1bf1cc44 100644 --- a/Documentation/powerpc/ultravisor.rst +++ b/Documentation/arch/powerpc/ultravisor.rst diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/arch/powerpc/vas-api.rst index a9625a2fa0c6..a9625a2fa0c6 100644 --- a/Documentation/powerpc/vas-api.rst +++ b/Documentation/arch/powerpc/vas-api.rst diff --git a/Documentation/powerpc/vcpudispatch_stats.rst b/Documentation/arch/powerpc/vcpudispatch_stats.rst index 5704657a5987..5704657a5987 100644 --- a/Documentation/powerpc/vcpudispatch_stats.rst +++ b/Documentation/arch/powerpc/vcpudispatch_stats.rst diff --git a/Documentation/powerpc/vmemmap_dedup.rst b/Documentation/arch/powerpc/vmemmap_dedup.rst index dc4db59fdf87..dc4db59fdf87 100644 --- a/Documentation/powerpc/vmemmap_dedup.rst +++ b/Documentation/arch/powerpc/vmemmap_dedup.rst diff --git a/Documentation/riscv/acpi.rst b/Documentation/arch/riscv/acpi.rst index 9870a282815b..9870a282815b 100644 --- a/Documentation/riscv/acpi.rst +++ b/Documentation/arch/riscv/acpi.rst diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/arch/riscv/boot-image-header.rst index df2ffc173e80..df2ffc173e80 100644 --- a/Documentation/riscv/boot-image-header.rst +++ b/Documentation/arch/riscv/boot-image-header.rst diff --git a/Documentation/riscv/boot.rst b/Documentation/arch/riscv/boot.rst index 6077b587a842..6077b587a842 100644 --- a/Documentation/riscv/boot.rst +++ b/Documentation/arch/riscv/boot.rst diff --git a/Documentation/riscv/features.rst b/Documentation/arch/riscv/features.rst index c70ef6ac2368..c70ef6ac2368 100644 --- a/Documentation/riscv/features.rst +++ b/Documentation/arch/riscv/features.rst diff --git a/Documentation/riscv/hwprobe.rst b/Documentation/arch/riscv/hwprobe.rst index a52996b22f75..a52996b22f75 100644 --- a/Documentation/riscv/hwprobe.rst +++ b/Documentation/arch/riscv/hwprobe.rst diff --git a/Documentation/riscv/index.rst b/Documentation/arch/riscv/index.rst index 4dab0cb4b900..4dab0cb4b900 100644 --- a/Documentation/riscv/index.rst +++ b/Documentation/arch/riscv/index.rst diff --git a/Documentation/riscv/patch-acceptance.rst b/Documentation/arch/riscv/patch-acceptance.rst index 634aa222b410..634aa222b410 100644 --- a/Documentation/riscv/patch-acceptance.rst +++ b/Documentation/arch/riscv/patch-acceptance.rst diff --git a/Documentation/riscv/uabi.rst b/Documentation/arch/riscv/uabi.rst index 8960fac42c40..8960fac42c40 100644 --- a/Documentation/riscv/uabi.rst +++ b/Documentation/arch/riscv/uabi.rst diff --git a/Documentation/riscv/vector.rst b/Documentation/arch/riscv/vector.rst index 75dd88a62e1d..75dd88a62e1d 100644 --- a/Documentation/riscv/vector.rst +++ b/Documentation/arch/riscv/vector.rst diff --git a/Documentation/riscv/vm-layout.rst b/Documentation/arch/riscv/vm-layout.rst index 69ff6da1dbf8..69ff6da1dbf8 100644 --- a/Documentation/riscv/vm-layout.rst +++ b/Documentation/arch/riscv/vm-layout.rst diff --git a/Documentation/arch/sh/index.rst b/Documentation/arch/sh/index.rst index c64776738cf6..01fce7c131f1 100644 --- a/Documentation/arch/sh/index.rst +++ b/Documentation/arch/sh/index.rst @@ -43,12 +43,6 @@ mach-x3proto Busses ====== -SuperHyway ----------- - -.. kernel-doc:: drivers/sh/superhyway/superhyway.c - :export: - Maple ----- diff --git a/Documentation/arch/x86/amd-memory-encryption.rst b/Documentation/arch/x86/amd-memory-encryption.rst index 934310ce7258..07caa8fff852 100644 --- a/Documentation/arch/x86/amd-memory-encryption.rst +++ b/Documentation/arch/x86/amd-memory-encryption.rst @@ -130,4 +130,4 @@ SNP feature support. More details in AMD64 APM[1] Vol 2: 15.34.10 SEV_STATUS MSR -[1] https://www.amd.com/system/files/TechDocs/40332.pdf +[1] https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/24593.pdf diff --git a/Documentation/arch/x86/amd_hsmp.rst b/Documentation/arch/x86/amd_hsmp.rst index 440e4b645a1c..c92bfd55359f 100644 --- a/Documentation/arch/x86/amd_hsmp.rst +++ b/Documentation/arch/x86/amd_hsmp.rst @@ -41,6 +41,24 @@ In-kernel integration: * Locking across callers is taken care by the driver. +HSMP sysfs interface +==================== + +1. Metrics table binary sysfs + +AMD MI300A MCM provides GET_METRICS_TABLE message to retrieve +most of the system management information from SMU in one go. + +The metrics table is made available as hexadecimal sysfs binary file +under per socket sysfs directory created at +/sys/devices/platform/amd_hsmp/socket%d/metrics_bin + +Note: lseek() is not supported as entire metrics table is read. + +Metrics table definitions will be documented as part of Public PPR. +The same is defined in the amd_hsmp.h header. + + An example ========== diff --git a/Documentation/arch/x86/iommu.rst b/Documentation/arch/x86/iommu.rst index 42c7a6faa39a..41fbadfe2221 100644 --- a/Documentation/arch/x86/iommu.rst +++ b/Documentation/arch/x86/iommu.rst @@ -5,7 +5,7 @@ x86 IOMMU Support The architecture specs can be obtained from the below locations. - Intel: http://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/vt-directed-io-spec.pdf -- AMD: https://www.amd.com/system/files/TechDocs/48882_IOMMU.pdf +- AMD: https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/specifications/48882_3_07_PUB.pdf This guide gives a quick cheat sheet for some basic understanding. diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst index cb05d90111b4..a6279df64a9d 100644 --- a/Documentation/arch/x86/resctrl.rst +++ b/Documentation/arch/x86/resctrl.rst @@ -35,7 +35,7 @@ about the feature from resctrl's info directory. To use the feature mount the file system:: - # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps]] /sys/fs/resctrl + # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps][,debug]] /sys/fs/resctrl mount options are: @@ -46,6 +46,9 @@ mount options are: "mba_MBps": Enable the MBA Software Controller(mba_sc) to specify MBA bandwidth in MBps +"debug": + Make debug files accessible. Available debug files are annotated with + "Available only with debug option". L2 and L3 CDP are controlled separately. @@ -124,6 +127,13 @@ related to allocation: "P": Corresponding region is pseudo-locked. No sharing allowed. +"sparse_masks": + Indicates if non-contiguous 1s value in CBM is supported. + + "0": + Only contiguous 1s value in CBM is supported. + "1": + Non-contiguous 1s value in CBM is supported. Memory bandwidth(MB) subdirectory contains the following files with respect to allocation: @@ -299,7 +309,14 @@ All groups contain the following files: "tasks": Reading this file shows the list of all tasks that belong to this group. Writing a task id to the file will add a task to the - group. If the group is a CTRL_MON group the task is removed from + group. Multiple tasks can be added by separating the task ids + with commas. Tasks will be assigned sequentially. Multiple + failures are not supported. A single failure encountered while + attempting to assign a task will cause the operation to abort and + already added tasks before the failure will remain in the group. + Failures will be logged to /sys/fs/resctrl/info/last_cmd_status. + + If the group is a CTRL_MON group the task is removed from whichever previous CTRL_MON group owned the task and also from any MON group that owned the task. If the group is a MON group, then the task must already belong to the CTRL_MON parent of this @@ -342,6 +359,10 @@ When control is enabled all CTRL_MON groups will also contain: file. On successful pseudo-locked region creation the mode will automatically change to "pseudo-locked". +"ctrl_hw_id": + Available only with debug option. The identifier used by hardware + for the control group. On x86 this is the CLOSID. + When monitoring is enabled all MON groups will also contain: "mon_data": @@ -355,6 +376,10 @@ When monitoring is enabled all MON groups will also contain: the sum for all tasks in the CTRL_MON group and all tasks in MON groups. Please see example section for more details on usage. +"mon_hw_id": + Available only with debug option. The identifier used by hardware + for the monitor group. On x86 this is the RMID. + Resource allocation rules ------------------------- @@ -445,12 +470,13 @@ For cache resources we describe the portion of the cache that is available for allocation using a bitmask. The maximum value of the mask is defined by each cpu model (and may be different for different cache levels). It is found using CPUID, but is also provided in the "info" directory of -the resctrl file system in "info/{resource}/cbm_mask". Intel hardware +the resctrl file system in "info/{resource}/cbm_mask". Some Intel hardware requires that these masks have all the '1' bits in a contiguous block. So 0x3, 0x6 and 0xC are legal 4-bit masks with two bits set, but 0x5, 0x9 -and 0xA are not. On a system with a 20-bit mask each bit represents 5% -of the capacity of the cache. You could partition the cache into four -equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. +and 0xA are not. Check /sys/fs/resctrl/info/{resource}/sparse_masks +if non-contiguous 1s value is supported. On a system with a 20-bit mask +each bit represents 5% of the capacity of the cache. You could partition +the cache into four equal parts with masks: 0x1f, 0x3e0, 0x7c00, 0xf8000. Memory bandwidth Allocation and monitoring ========================================== diff --git a/Documentation/arch/x86/topology.rst b/Documentation/arch/x86/topology.rst index 7f58010ea86a..08ebf9edbfc1 100644 --- a/Documentation/arch/x86/topology.rst +++ b/Documentation/arch/x86/topology.rst @@ -55,19 +55,19 @@ Package-related topology information in the kernel: The number of dies in a package. This information is retrieved via CPUID. - - cpuinfo_x86.cpu_die_id: + - cpuinfo_x86.topo.die_id: The physical ID of the die. This information is retrieved via CPUID. - - cpuinfo_x86.phys_proc_id: + - cpuinfo_x86.topo.pkg_id: The physical ID of the package. This information is retrieved via CPUID and deduced from the APIC IDs of the cores in the package. Modern systems use this value for the socket. There may be multiple - packages within a socket. This value may differ from cpu_die_id. + packages within a socket. This value may differ from topo.die_id. - - cpuinfo_x86.logical_proc_id: + - cpuinfo_x86.topo.logical_pkg_id: The logical ID of the package. As we do not trust BIOSes to enumerate the packages in a consistent way, we introduced the concept of logical package @@ -79,9 +79,7 @@ Package-related topology information in the kernel: The maximum possible number of packages in the system. Helpful for per package facilities to preallocate per package information. - - cpu_llc_id: - - A per-CPU variable containing: + - cpuinfo_x86.topo.llc_id: - On Intel, the first APIC ID of the list of CPUs sharing the Last Level Cache diff --git a/Documentation/block/blk-mq.rst b/Documentation/block/blk-mq.rst index 31f52f326971..fc06761b6ea9 100644 --- a/Documentation/block/blk-mq.rst +++ b/Documentation/block/blk-mq.rst @@ -56,7 +56,7 @@ sent to the software queue. Then, after the requests are processed by software queues, they will be placed at the hardware queue, a second stage queue where the hardware has direct access to process those requests. However, if the hardware does not have enough -resources to accept more requests, blk-mq will places requests on a temporary +resources to accept more requests, blk-mq will place requests on a temporary queue, to be sent in the future, when the hardware is able. Software staging queues diff --git a/Documentation/block/ioprio.rst b/Documentation/block/ioprio.rst index f72b0de65af7..a25c6d5df87b 100644 --- a/Documentation/block/ioprio.rst +++ b/Documentation/block/ioprio.rst @@ -80,9 +80,6 @@ ionice.c tool:: #elif defined(__x86_64__) #define __NR_ioprio_set 251 #define __NR_ioprio_get 252 - #elif defined(__ia64__) - #define __NR_ioprio_set 1274 - #define __NR_ioprio_get 1275 #else #error "Unsupported arch" #endif diff --git a/Documentation/bpf/libbpf/program_types.rst b/Documentation/bpf/libbpf/program_types.rst index ad4d4d5eecb0..63bb88846e50 100644 --- a/Documentation/bpf/libbpf/program_types.rst +++ b/Documentation/bpf/libbpf/program_types.rst @@ -56,6 +56,16 @@ described in more detail in the footnotes. | | ``BPF_CGROUP_UDP6_RECVMSG`` | ``cgroup/recvmsg6`` | | + +----------------------------------------+----------------------------------+-----------+ | | ``BPF_CGROUP_UDP6_SENDMSG`` | ``cgroup/sendmsg6`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_CONNECT`` | ``cgroup/connect_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_SENDMSG`` | ``cgroup/sendmsg_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_RECVMSG`` | ``cgroup/recvmsg_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_GETPEERNAME`` | ``cgroup/getpeername_unix`` | | +| +----------------------------------------+----------------------------------+-----------+ +| | ``BPF_CGROUP_UNIX_GETSOCKNAME`` | ``cgroup/getsockname_unix`` | | +-------------------------------------------+----------------------------------------+----------------------------------+-----------+ | ``BPF_PROG_TYPE_CGROUP_SOCK`` | ``BPF_CGROUP_INET4_POST_BIND`` | ``cgroup/post_bind4`` | | + +----------------------------------------+----------------------------------+-----------+ diff --git a/Documentation/bpf/prog_flow_dissector.rst b/Documentation/bpf/prog_flow_dissector.rst index 4d86780ab0f1..f24270b8b034 100644 --- a/Documentation/bpf/prog_flow_dissector.rst +++ b/Documentation/bpf/prog_flow_dissector.rst @@ -113,7 +113,7 @@ Flags used by ``eth_get_headlen`` to estimate length of all headers for GRO. * ``BPF_FLOW_DISSECTOR_F_STOP_AT_FLOW_LABEL`` - tells BPF flow dissector to stop parsing as soon as it reaches IPv6 flow label; used by - ``___skb_get_hash`` and ``__skb_get_hash_symmetric`` to get flow hash. + ``___skb_get_hash`` to get flow hash. * ``BPF_FLOW_DISSECTOR_F_STOP_AT_ENCAP`` - tells BPF flow dissector to stop parsing as soon as it reaches encapsulated headers; used by routing infrastructure. diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst index c5d53a6e8c79..245b6defc298 100644 --- a/Documentation/bpf/standardization/instruction-set.rst +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -283,6 +283,14 @@ For signed operations (``BPF_SDIV`` and ``BPF_SMOD``), for ``BPF_ALU``, is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then interpreted as a 64-bit signed value. +Note that there are varying definitions of the signed modulo operation +when the dividend or divisor are negative, where implementations often +vary by language such that Python, Ruby, etc. differ from C, Go, Java, +etc. This specification requires that signed modulo use truncated division +(where -13 % 3 == -1) as implemented in C, Go, etc.: + + a % n = a - n * trunc(a / n) + The ``BPF_MOVSX`` instruction does a move operation with sign extension. ``BPF_ALU | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into 32 bit operands, and zeroes the remaining upper 32 bits. diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index 9511e405aabd..dcb0e379e5e8 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -40,12 +40,6 @@ Command Line Switches supplied here is lower than the number of physically available CPUs, then those CPUs can not be brought online later. -``additional_cpus=n`` - Use this to limit hotpluggable CPUs. This option sets - ``cpu_possible_mask = cpu_present_mask + additional_cpus`` - - This option is limited to the IA64 architecture. - ``possible_cpus=n`` This option sets ``possible_cpus`` bits in ``cpu_possible_mask``. diff --git a/Documentation/core-api/debugging-via-ohci1394.rst b/Documentation/core-api/debugging-via-ohci1394.rst index 981ad4f89fd3..cb3d3228dfc8 100644 --- a/Documentation/core-api/debugging-via-ohci1394.rst +++ b/Documentation/core-api/debugging-via-ohci1394.rst @@ -23,9 +23,9 @@ Retrieving a full system memory dump is also possible over the FireWire, using data transfer rates in the order of 10MB/s or more. With most FireWire controllers, memory access is limited to the low 4 GB -of physical address space. This can be a problem on IA64 machines where -memory is located mostly above that limit, but it is rarely a problem on -more common hardware such as x86, x86-64 and PowerPC. +of physical address space. This can be a problem on machines where memory is +located mostly above that limit, but it is rarely a problem on more common +hardware such as x86, x86-64 and PowerPC. At least LSI FW643e and FW643e2 controllers are known to support access to physical addresses above 4 GB, but this feature is currently not enabled by diff --git a/Documentation/core-api/maple_tree.rst b/Documentation/core-api/maple_tree.rst index 45defcf15da7..96f3d5f076b5 100644 --- a/Documentation/core-api/maple_tree.rst +++ b/Documentation/core-api/maple_tree.rst @@ -175,7 +175,7 @@ will return the previous entry which occurs before the entry at index. mas_find() will find the first entry which exists at or above index on the first call, and the next entry from every subsequent calls. -mas_find_rev() will find the fist entry which exists at or below the last on +mas_find_rev() will find the first entry which exists at or below the last on the first call, and the previous entry from every subsequent calls. If the user needs to yield the lock during an operation, then the maple state diff --git a/Documentation/crypto/devel-algos.rst b/Documentation/crypto/devel-algos.rst index 3506899ef83e..9b7782f4f6e0 100644 --- a/Documentation/crypto/devel-algos.rst +++ b/Documentation/crypto/devel-algos.rst @@ -235,6 +235,4 @@ Specifics Of Asynchronous HASH Transformation Some of the drivers will want to use the Generic ScatterWalk in case the implementation needs to be fed separate chunks of the scatterlist which -contains the input data. The buffer containing the resulting hash will -always be properly aligned to .cra_alignmask so there is no need to -worry about this. +contains the input data. diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 382818a7197a..858c77fe7dc4 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -1,5 +1,8 @@ -The Kernel Address Sanitizer (KASAN) -==================================== +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (C) 2023, Google LLC. + +Kernel Address Sanitizer (KASAN) +================================ Overview -------- diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 3ae866dcc924..94b6802ab0ab 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 .. Copyright (C) 2019, Google LLC. -The Kernel Concurrency Sanitizer (KCSAN) -======================================== +Kernel Concurrency Sanitizer (KCSAN) +==================================== The Kernel Concurrency Sanitizer (KCSAN) is a dynamic race detector, which relies on compile-time instrumentation, and uses a watchpoint-based sampling diff --git a/Documentation/dev-tools/kmsan.rst b/Documentation/dev-tools/kmsan.rst index 55fa82212eb2..323eedad53cd 100644 --- a/Documentation/dev-tools/kmsan.rst +++ b/Documentation/dev-tools/kmsan.rst @@ -1,9 +1,9 @@ .. SPDX-License-Identifier: GPL-2.0 .. Copyright (C) 2022, Google LLC. -=================================== -The Kernel Memory Sanitizer (KMSAN) -=================================== +=============================== +Kernel Memory Sanitizer (KMSAN) +=============================== KMSAN is a dynamic error detector aimed at finding uses of uninitialized values. It is based on compiler instrumentation, and is quite similar to the diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index deede972f254..ab376b316c36 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -112,7 +112,7 @@ You can specify multiple tests to skip:: You can also specify a restricted list of tests to run together with a dedicated skiplist:: - $ make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest + $ make TARGETS="breakpoints size timers" SKIP_TARGETS=size kselftest See the top-level tools/testing/selftests/Makefile for the list of all possible targets. @@ -165,7 +165,7 @@ To see the list of available tests, the `-l` option can be used:: The `-c` option can be used to run all the tests from a test collection, or the `-t` option for specific single tests. Either can be used multiple times:: - $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep + $ ./run_kselftest.sh -c size -c seccomp -t timers:posix_timers -t timer:nanosleep For other features see the script usage output, seen with the `-h` option. @@ -210,7 +210,7 @@ option is supported, such as:: tests by using variables specified in `Running a subset of selftests`_ section:: - $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz + $ make -C tools/testing/selftests gen_tar TARGETS="size" FORMAT=.xz .. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress diff --git a/Documentation/dev-tools/ubsan.rst b/Documentation/dev-tools/ubsan.rst index 1be6618e232d..2de7c63415da 100644 --- a/Documentation/dev-tools/ubsan.rst +++ b/Documentation/dev-tools/ubsan.rst @@ -1,5 +1,7 @@ -The Undefined Behavior Sanitizer - UBSAN -======================================== +.. SPDX-License-Identifier: GPL-2.0 + +Undefined Behavior Sanitizer - UBSAN +==================================== UBSAN is a runtime undefined behaviour checker. diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index 8b395893bd85..3e886194b043 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -6,7 +6,7 @@ DT_MK_SCHEMA ?= dt-mk-schema DT_SCHEMA_LINT = $(shell which yamllint || \ echo "warning: python package 'yamllint' not installed, skipping" >&2) -DT_SCHEMA_MIN_VERSION = 2022.3 +DT_SCHEMA_MIN_VERSION = 2023.9 PHONY += check_dtschema_version check_dtschema_version: diff --git a/Documentation/devicetree/bindings/arm/amd,pensando.yaml b/Documentation/devicetree/bindings/arm/amd,pensando.yaml new file mode 100644 index 000000000000..e5c2591834a8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/amd,pensando.yaml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/amd,pensando.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: AMD Pensando SoC Platforms + +maintainers: + - Brad Larson <blarson@amd.com> + +properties: + $nodename: + const: "/" + compatible: + oneOf: + + - description: Boards with Pensando Elba SoC + items: + - enum: + - amd,pensando-elba-ortano + - const: amd,pensando-elba + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index 1c1094cd6b77..caab7ceeda45 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -155,6 +155,7 @@ properties: - enum: - bananapi,bpi-m2s - khadas,vim3 + - libretech,aml-a311d-cc - radxa,zero2 - const: amlogic,a311d - const: amlogic,g12b @@ -196,6 +197,7 @@ properties: - hardkernel,odroid-hc4 - haochuangyi,h96-max - khadas,vim3l + - libretech,aml-s905d3-cc - seirobotics,sei610 - const: amlogic,sm1 @@ -203,6 +205,7 @@ properties: items: - enum: - amlogic,ad401 + - amlogic,ad402 - const: amlogic,a1 - description: Boards with the Amlogic C3 C302X/C308L SoC diff --git a/Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml b/Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml index 6216cfb0a188..2d5545a2b49c 100644 --- a/Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml +++ b/Documentation/devicetree/bindings/arm/arm,coresight-cti.yaml @@ -92,11 +92,8 @@ properties: maxItems: 1 cpu: - $ref: /schemas/types.yaml#/definitions/phandle description: - Handle to cpu this device is associated with. This must appear in the - base cti node if compatible string arm,coresight-cti-v8-arch is used, - or may appear in a trig-conns child node when appropriate. + Handle to cpu this CTI is associated with. power-domains: maxItems: 1 @@ -113,12 +110,12 @@ properties: description: defines a phandle reference to an associated CoreSight trace device. When the associated trace device is enabled, then the respective CTI - will be enabled. Use in a trig-conns node, or in CTI base node when - compatible string arm,coresight-cti-v8-arch used. If the associated - device has not been registered then the node name will be stored as - the connection name for later resolution. If the associated device is - not a CoreSight device or not registered then the node name will remain - the connection name and automatic enabling will not occur. + will be enabled. Use in CTI base node when compatible string + arm,coresight-cti-v8-arch used. If the associated device has not been + registered then the node name will be stored as the connection name for + later resolution. If the associated device is not a CoreSight device or + not registered then the node name will remain the connection name and + automatic enabling will not occur. # size cells and address cells required if trig-conns node present. "#size-cells": @@ -130,6 +127,8 @@ properties: patternProperties: '^trig-conns@([0-9]+)$': type: object + additionalProperties: false + description: A trigger connections child node which describes the trigger signals between this CTI and another hardware device. This device may be a CPU, @@ -141,6 +140,21 @@ patternProperties: reg: maxItems: 1 + cpu: + description: + Handle to cpu this trigger connection is associated with. + + arm,cs-dev-assoc: + $ref: /schemas/types.yaml#/definitions/phandle + description: + defines a phandle reference to an associated CoreSight trace device. + When the associated trace device is enabled, then the respective CTI + will be enabled. If the associated device has not been registered + then the node name will be stored as the connection name for later + resolution. If the associated device is not a CoreSight device or + not registered then the node name will remain the connection name + and automatic enabling will not occur. + arm,trig-in-sigs: $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 1 diff --git a/Documentation/devicetree/bindings/arm/arm,integrator.yaml b/Documentation/devicetree/bindings/arm/arm,integrator.yaml index 98ff5698ae1f..1bdbd1b7ee38 100644 --- a/Documentation/devicetree/bindings/arm/arm,integrator.yaml +++ b/Documentation/devicetree/bindings/arm/arm,integrator.yaml @@ -40,45 +40,6 @@ properties: items: - const: arm,integrator-sp - core-module@10000000: - type: object - description: the root node in the Integrator platforms must contain - a core module child node. They are always at physical address - 0x10000000 in all the Integrator variants. - properties: - compatible: - items: - - const: arm,core-module-integrator - - const: syscon - - const: simple-mfd - reg: - maxItems: 1 - - required: - - compatible - - reg - -patternProperties: - "^syscon@[0-9a-f]+$": - description: All Integrator boards must provide a system controller as a - node in the root of the device tree. - type: object - properties: - compatible: - items: - - enum: - - arm,integrator-ap-syscon - - arm,integrator-cp-syscon - - arm,integrator-sp-syscon - - const: syscon - reg: - maxItems: 1 - - required: - - compatible - - reg - - required: - compatible - core-module@10000000 diff --git a/Documentation/devicetree/bindings/arm/arm,realview.yaml b/Documentation/devicetree/bindings/arm/arm,realview.yaml index 8d3ed2e4ed31..d1bdee98f9af 100644 --- a/Documentation/devicetree/bindings/arm/arm,realview.yaml +++ b/Documentation/devicetree/bindings/arm/arm,realview.yaml @@ -75,43 +75,6 @@ properties: type: object description: All RealView boards must provide a syscon system controller node inside the soc node. - properties: - compatible: - oneOf: - - items: - - const: arm,realview-eb11mp-revb-syscon - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-eb11mp-revc-syscon - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-eb-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pb1176-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pb11mp-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pba8-syscon - - const: syscon - - const: simple-mfd - - items: - - const: arm,realview-pbx-syscon - - const: syscon - - const: simple-mfd - - required: - - compatible - - reg required: - compatible diff --git a/Documentation/devicetree/bindings/arm/arm,versatile.yaml b/Documentation/devicetree/bindings/arm/arm,versatile.yaml index 13e52ba92060..7a3caf6af200 100644 --- a/Documentation/devicetree/bindings/arm/arm,versatile.yaml +++ b/Documentation/devicetree/bindings/arm/arm,versatile.yaml @@ -14,6 +14,14 @@ description: |+ with various pluggable interface boards, in essence the Versatile PB version is a superset of the Versatile AB version. + The root node in the Versatile platforms must contain a core module child + node. They are always at physical address 0x10000000 in all the Versatile + variants. + + When fitted with the IB2 Interface Board, the Versatile AB will present an + optional system controller node which controls the extra peripherals on the + interface board. + properties: $nodename: const: '/' @@ -32,38 +40,6 @@ properties: items: - const: arm,versatile-pb - core-module@10000000: - type: object - description: the root node in the Versatile platforms must contain - a core module child node. They are always at physical address - 0x10000000 in all the Versatile variants. - properties: - compatible: - items: - - const: arm,core-module-versatile - - const: syscon - - const: simple-mfd - reg: - maxItems: 1 - - required: - - compatible - - reg - -patternProperties: - "^syscon@[0-9a-f]+$": - type: object - description: When fitted with the IB2 Interface Board, the Versatile - AB will present an optional system controller node which controls the - extra peripherals on the interface board. - properties: - compatible: - contains: - const: arm,versatile-ib2-syscon - required: - - compatible - - reg - required: - compatible - core-module@10000000 diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml index 68f717670f78..749ee54a3ff8 100644 --- a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml @@ -79,6 +79,7 @@ properties: - facebook,elbert-bmc - facebook,fuji-bmc - facebook,greatlakes-bmc + - facebook,minerva-cmc - facebook,yosemite4-bmc - ibm,everest-bmc - ibm,rainier-bmc diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.yaml b/Documentation/devicetree/bindings/arm/atmel-at91.yaml index dfb8fd089197..89d75fbb1de4 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.yaml +++ b/Documentation/devicetree/bindings/arm/atmel-at91.yaml @@ -79,6 +79,13 @@ properties: - const: atmel,sama5d2 - const: atmel,sama5 + - description: Microchip SAMA5D29 Curiosity + items: + - const: microchip,sama5d29-curiosity + - const: atmel,sama5d29 + - const: atmel,sama5d2 + - const: atmel,sama5 + - items: - const: atmel,sama5d27 - const: atmel,sama5d2 diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml index 0d17cbad9778..ffd526363fda 100644 --- a/Documentation/devicetree/bindings/arm/cpus.yaml +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -190,6 +190,7 @@ properties: - qcom,kryo280 - qcom,kryo360 - qcom,kryo385 + - qcom,kryo465 - qcom,kryo468 - qcom,kryo485 - qcom,kryo560 @@ -308,7 +309,9 @@ properties: power-domains property. For PSCI based platforms, the name corresponding to the index of the PSCI - PM domain provider, must be "psci". + PM domain provider, must be "psci". For SCMI based platforms, the name + corresponding to the index of an SCMI performance domain provider, must be + "perf". qcom,saw: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 9450b2c8a678..32b195852a75 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -25,8 +25,11 @@ properties: - description: i.MX23 based Boards items: - enum: + - creative,x-fi3 - fsl,imx23-evk + - fsl,stmp378x-devb - olimex,imx23-olinuxino + - sandisk,sansa_fuze_plus - const: fsl,imx23 - description: i.MX25 Product Development Kit @@ -385,6 +388,12 @@ properties: - const: toradex,apalis_imx6q - const: fsl,imx6q + - description: i.MX6Q Variscite VAR-SOM-MX6 Boards + items: + - const: variscite,mx6customboard + - const: variscite,var-som-imx6q + - const: fsl,imx6q + - description: TQ-Systems TQMa6Q SoM (variant A) on MBa6x items: - const: tq,imx6q-mba6x-a @@ -975,7 +984,9 @@ properties: - description: PHYTEC phyCORE-i.MX8MM SoM based boards items: - - const: phytec,imx8mm-phyboard-polis-rdk # phyBOARD-Polis RDK + - enum: + - phytec,imx8mm-phyboard-polis-rdk # phyBOARD-Polis RDK + - phytec,imx8mm-phygate-tauri-l # phyGATE-Tauri-L Gateway - const: phytec,imx8mm-phycore-som # phyCORE-i.MX8MM SoM - const: fsl,imx8mm @@ -1389,6 +1400,13 @@ properties: - fsl,ls1043a-qds - const: fsl,ls1043a + - description: TQ-Systems LS1043A based Boards + items: + - enum: + - tq,ls1043a-tqmls1043a-mbls10xxa + - const: tq,ls1043a-tqmls1043a + - const: fsl,ls1043a + - description: LS1046A based Boards items: - enum: @@ -1397,6 +1415,13 @@ properties: - fsl,ls1046a-rdb - const: fsl,ls1046a + - description: TQ-Systems LS1046A based Boards + items: + - enum: + - tq,ls1046a-tqmls1046a-mbls10xxa + - const: tq,ls1046a-tqmls1046a + - const: fsl,ls1046a + - description: LS1088A based Boards items: - enum: @@ -1404,6 +1429,13 @@ properties: - fsl,ls1088a-rdb - const: fsl,ls1088a + - description: TQ-Systems LS1088A based Boards + items: + - enum: + - tq,ls1088a-tqmls1088a-mbls10xxa + - const: tq,ls1088a-tqmls1088a + - const: fsl,ls1088a + - description: LS2080A based Boards items: - enum: @@ -1429,7 +1461,7 @@ properties: - fsl,lx2162a-qds - const: fsl,lx2160a - - description: SolidRun LX2160A based Boards + - description: SolidRun LX2160A CEX-7 based Boards items: - enum: - solidrun,clearfog-cx @@ -1437,6 +1469,13 @@ properties: - const: solidrun,lx2160a-cex7 - const: fsl,lx2160a + - description: SolidRun LX2162A SoM based Boards + items: + - enum: + - solidrun,lx2162a-clearfog + - const: solidrun,lx2162a-som + - const: fsl,lx2160a + - description: S32G2 based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml b/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml index 553dcbc70e35..d60792b1d995 100644 --- a/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml +++ b/Documentation/devicetree/bindings/arm/intel-ixp4xx.yaml @@ -16,12 +16,28 @@ properties: oneOf: - items: - enum: + - adieng,coyote + - arcom,vulcan + - dlink,dsm-g600-a + - freecom,fsg-3 + - gateway,7001 + - gateworks,gw2348 + - goramo,multilink-router + - intel,ixdp425 + - intel,ixdpg425 + - iom,nas-100d - linksys,nslu2 + - netgear,wg302v1 + - netgear,wg302v2 + - usr,8200 - welltech,epbx100 + - linksys,wrv54g + - gemtek,gtwx5715 - const: intel,ixp42x - items: - enum: - gateworks,gw2358 + - intel,kixrp435 - const: intel,ixp43x additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index ae12b1cab9fb..a5999b3afc35 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -133,11 +133,22 @@ properties: - enum: - mediatek,mt8183-evb - const: mediatek,mt8183 + - description: Google Hayato rev5 + items: + - const: google,hayato-rev5-sku2 + - const: google,hayato-sku2 + - const: google,hayato + - const: mediatek,mt8192 - description: Google Hayato items: - const: google,hayato-rev1 - const: google,hayato - const: mediatek,mt8192 + - description: Google Spherion rev4 (Acer Chromebook 514) + items: + - const: google,spherion-rev4 + - const: google,spherion + - const: mediatek,mt8192 - description: Google Spherion (Acer Chromebook 514) items: - const: google,spherion-rev3 @@ -250,6 +261,11 @@ properties: - const: mediatek,mt8365 - items: - enum: + - mediatek,mt8395-evk + - const: mediatek,mt8395 + - const: mediatek,mt8195 + - items: + - enum: - mediatek,mt8516-pumpkin - const: mediatek,mt8516 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml index 28ded09d72e3..e7720caf31b3 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mt7622-wed.yaml @@ -22,6 +22,7 @@ properties: - mediatek,mt7622-wed - mediatek,mt7981-wed - mediatek,mt7986-wed + - mediatek,mt7988-wed - const: syscon reg: diff --git a/Documentation/devicetree/bindings/arm/psci.yaml b/Documentation/devicetree/bindings/arm/psci.yaml index 0c5381e081bd..cbb012e217ab 100644 --- a/Documentation/devicetree/bindings/arm/psci.yaml +++ b/Documentation/devicetree/bindings/arm/psci.yaml @@ -101,6 +101,7 @@ properties: patternProperties: "^power-domain-": $ref: /schemas/power/power-domain.yaml# + unevaluatedProperties: false type: object description: | diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index adbfaea32343..7f80f48a0954 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -50,6 +50,7 @@ description: | msm8998 qcs404 qcm2290 + qcm6490 qdu1000 qrb2210 qrb4210 @@ -79,6 +80,7 @@ description: | sm6125 sm6350 sm6375 + sm7125 sm7225 sm8150 sm8250 @@ -189,6 +191,7 @@ properties: - items: - enum: + - longcheer,l9100 - samsung,a7 - sony,kanuti-tulip - square,apq8039-t2 @@ -391,6 +394,11 @@ properties: - const: qcom,qrb2210 - const: qcom,qcm2290 + - items: + - enum: + - fairphone,fp5 + - const: qcom,qcm6490 + - description: Qualcomm Technologies, Inc. Distributed Unit 1000 platform items: - enum: @@ -479,6 +487,11 @@ properties: - const: google,lazor-rev8 - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 (rev9) + items: + - const: google,lazor-rev9 + - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 (newest rev) items: - const: google,lazor @@ -500,6 +513,11 @@ properties: - const: google,lazor-rev8-sku2 - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with KB Backlight (rev9) + items: + - const: google,lazor-rev9-sku2 + - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with KB Backlight (newest rev) items: - const: google,lazor-sku2 @@ -521,9 +539,16 @@ properties: - const: google,lazor-rev8-sku0 - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with LTE (rev9) + items: + - const: google,lazor-rev9-sku0 + - const: google,lazor-rev9-sku10 + - const: qcom,sc7180 + - description: Acer Chromebook Spin 513 with LTE (newest rev) items: - const: google,lazor-sku0 + - const: google,lazor-sku10 - const: qcom,sc7180 - description: Acer Chromebook 511 (rev4 - rev8) @@ -535,9 +560,16 @@ properties: - const: google,lazor-rev8-sku4 - const: qcom,sc7180 + - description: Acer Chromebook 511 (rev9) + items: + - const: google,lazor-rev9-sku4 + - const: google,lazor-rev9-sku15 + - const: qcom,sc7180 + - description: Acer Chromebook 511 (newest rev) items: - const: google,lazor-sku4 + - const: google,lazor-sku15 - const: qcom,sc7180 - description: Acer Chromebook 511 without Touchscreen (rev4) @@ -554,9 +586,16 @@ properties: - const: google,lazor-rev8-sku6 - const: qcom,sc7180 + - description: Acer Chromebook 511 without Touchscreen (rev9) + items: + - const: google,lazor-rev9-sku6 + - const: google,lazor-rev9-sku18 + - const: qcom,sc7180 + - description: Acer Chromebook 511 without Touchscreen (newest rev) items: - const: google,lazor-sku6 + - const: google,lazor-sku18 - const: qcom,sc7180 - description: Google Mrbland with AUO panel (rev0) @@ -945,6 +984,11 @@ properties: - items: - enum: + - xiaomi,joyeuse + - const: qcom,sm7125 + + - items: + - enum: - fairphone,fp4 - const: qcom,sm7225 @@ -1086,6 +1130,7 @@ allOf: - qcom,sm6115 - qcom,sm6125 - qcom,sm6350 + - qcom,sm7125 - qcom,sm7225 - qcom,sm8150 - qcom,sm8250 diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index ca5389862887..5f7c6c4aad8f 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -660,6 +660,11 @@ properties: - pine64,quartz64-b - const: rockchip,rk3566 + - description: Pine64 QuartzPro64 + items: + - const: pine64,quartzpro64 + - const: rockchip,rk3588 + - description: Pine64 SoQuartz SoM items: - enum: @@ -669,6 +674,11 @@ properties: - const: pine64,soquartz - const: rockchip,rk3566 + - description: Powkiddy RGB30 + items: + - const: powkiddy,rgb30 + - const: rockchip,rk3566 + - description: Radxa Compute Module 3(CM3) items: - enum: @@ -870,6 +880,16 @@ properties: - const: tronsmart,orion-r68-meta - const: rockchip,rk3368 + - description: Turing RK1 + items: + - const: turing,rk1 + - const: rockchip,rk3588 + + - description: Xunlong Orange Pi 5 Plus + items: + - const: xunlong,orangepi-5-plus + - const: rockchip,rk3588 + - description: Xunlong Orange Pi R1 Plus / LTS items: - enum: @@ -877,6 +897,11 @@ properties: - xunlong,orangepi-r1-plus-lts - const: rockchip,rk3328 + - description: Xunlong Orange Pi 5 + items: + - const: xunlong,orangepi-5 + - const: rockchip,rk3588s + - description: Zkmagic A95X Z2 items: - const: zkmagic,a95x-z2 diff --git a/Documentation/devicetree/bindings/arm/sti.yaml b/Documentation/devicetree/bindings/arm/sti.yaml index 3ca054c64377..842def3e3f2b 100644 --- a/Documentation/devicetree/bindings/arm/sti.yaml +++ b/Documentation/devicetree/bindings/arm/sti.yaml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: GPL-2.0 +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) %YAML 1.2 --- $id: http://devicetree.org/schemas/arm/sti.yaml# @@ -13,13 +13,20 @@ properties: $nodename: const: '/' compatible: - items: - - enum: - - st,stih415 - - st,stih416 - - st,stih407 - - st,stih410 - - st,stih418 + oneOf: + - items: + - const: st,stih407-b2120 + - const: st,stih407 + - items: + - enum: + - st,stih410-b2120 + - st,stih410-b2260 + - const: st,stih410 + - items: + - enum: + - st,stih418-b2199 + - st,stih418-b2264 + - const: st,stih418 additionalProperties: true diff --git a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml index 4bf28e717a56..df087c81c69e 100644 --- a/Documentation/devicetree/bindings/arm/stm32/stm32.yaml +++ b/Documentation/devicetree/bindings/arm/stm32/stm32.yaml @@ -146,6 +146,7 @@ properties: - lxa,stm32mp157c-mc1 # Linux Automation MC-1 - lxa,stm32mp157c-tac-gen1 # Linux Automation TAC (Generation 1) - lxa,stm32mp157c-tac-gen2 # Linux Automation TAC (Generation 2) + - oct,stm32mp157c-osd32-red # Octavo OSD32MP1 RED board - const: oct,stm32mp15xx-osd32 - enum: - st,stm32mp157 diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index e4dd678f4212..11c5ce941dd7 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -51,6 +51,11 @@ properties: - const: allwinner,parrot - const: allwinner,sun8i-a33 + - description: Anbernic RG-Nano + items: + - const: anbernic,rg-nano + - const: allwinner,sun8i-v3s + - description: Amarula A64 Relic items: - const: amarula,a64-relic @@ -151,6 +156,17 @@ properties: - const: roofull,beelink-x2 - const: allwinner,sun8i-h3 + - description: BigTreeTech Manta M4/8P + items: + - const: bigtreetech,cb1-manta + - const: bigtreetech,cb1 + - const: allwinner,sun50i-h616 + + - description: BigTreeTech Pi + items: + - const: bigtreetech,pi + - const: allwinner,sun50i-h616 + - description: Chuwi V7 CW0825 items: - const: chuwi,v7-cw0825 diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml deleted file mode 100644 index 89191cfdf619..000000000000 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.yaml +++ /dev/null @@ -1,393 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/arm/tegra/nvidia,tegra20-pmc.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Tegra Power Management Controller (PMC) - -maintainers: - - Thierry Reding <thierry.reding@gmail.com> - - Jonathan Hunter <jonathanh@nvidia.com> - -properties: - compatible: - enum: - - nvidia,tegra20-pmc - - nvidia,tegra30-pmc - - nvidia,tegra114-pmc - - nvidia,tegra124-pmc - - nvidia,tegra210-pmc - - reg: - maxItems: 1 - description: - Offset and length of the register set for the device. - - clock-names: - items: - - const: pclk - - const: clk32k_in - description: - Must includes entries pclk and clk32k_in. - pclk is the Tegra clock of that name and clk32k_in is 32KHz clock - input to Tegra. - - clocks: - maxItems: 2 - description: - Must contain an entry for each entry in clock-names. - See ../clocks/clocks-bindings.txt for details. - - '#clock-cells': - const: 1 - description: - Tegra PMC has clk_out_1, clk_out_2, and clk_out_3. - PMC also has blink control which allows 32Khz clock output to - Tegra blink pad. - Consumer of PMC clock should specify the desired clock by having - the clock ID in its "clocks" phandle cell with pmc clock provider. - See include/dt-bindings/soc/tegra-pmc.h for the list of Tegra PMC - clock IDs. - - '#interrupt-cells': - const: 2 - description: - Specifies number of cells needed to encode an interrupt source. - The value must be 2. - - interrupt-controller: true - - nvidia,invert-interrupt: - $ref: /schemas/types.yaml#/definitions/flag - description: Inverts the PMU interrupt signal. - The PMU is an external Power Management Unit, whose interrupt output - signal is fed into the PMC. This signal is optionally inverted, and - then fed into the ARM GIC. The PMC is not involved in the detection - or handling of this interrupt signal, merely its inversion. - - nvidia,core-power-req-active-high: - $ref: /schemas/types.yaml#/definitions/flag - description: Core power request active-high. - - nvidia,sys-clock-req-active-high: - $ref: /schemas/types.yaml#/definitions/flag - description: System clock request active-high. - - nvidia,combined-power-req: - $ref: /schemas/types.yaml#/definitions/flag - description: combined power request for CPU and Core. - - nvidia,cpu-pwr-good-en: - $ref: /schemas/types.yaml#/definitions/flag - description: - CPU power good signal from external PMIC to PMC is enabled. - - nvidia,suspend-mode: - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1, 2] - description: - The suspend mode that the platform should use. - Mode 0 is for LP0, CPU + Core voltage off and DRAM in self-refresh - Mode 1 is for LP1, CPU voltage off and DRAM in self-refresh - Mode 2 is for LP2, CPU voltage off - - nvidia,cpu-pwr-good-time: - $ref: /schemas/types.yaml#/definitions/uint32 - description: CPU power good time in uSec. - - nvidia,cpu-pwr-off-time: - $ref: /schemas/types.yaml#/definitions/uint32 - description: CPU power off time in uSec. - - nvidia,core-pwr-good-time: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: - <Oscillator-stable-time Power-stable-time> - Core power good time in uSec. - - nvidia,core-pwr-off-time: - $ref: /schemas/types.yaml#/definitions/uint32 - description: Core power off time in uSec. - - nvidia,lp0-vec: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: - <start length> Starting address and length of LP0 vector. - The LP0 vector contains the warm boot code that is executed - by AVP when resuming from the LP0 state. - The AVP (Audio-Video Processor) is an ARM7 processor and - always being the first boot processor when chip is power on - or resume from deep sleep mode. When the system is resumed - from the deep sleep mode, the warm boot code will restore - some PLLs, clocks and then brings up CPU0 for resuming the - system. - - core-supply: - description: - Phandle to voltage regulator connected to the SoC Core power rail. - - core-domain: - type: object - description: | - The vast majority of hardware blocks of Tegra SoC belong to a - Core power domain, which has a dedicated voltage rail that powers - the blocks. - - properties: - operating-points-v2: - description: - Should contain level, voltages and opp-supported-hw property. - The supported-hw is a bitfield indicating SoC speedo or process - ID mask. - - "#power-domain-cells": - const: 0 - - required: - - operating-points-v2 - - "#power-domain-cells" - - additionalProperties: false - - i2c-thermtrip: - type: object - description: - On Tegra30, Tegra114 and Tegra124 if i2c-thermtrip subnode exists, - hardware-triggered thermal reset will be enabled. - - properties: - nvidia,i2c-controller-id: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - ID of I2C controller to send poweroff command to PMU. - Valid values are described in section 9.2.148 - "APBDEV_PMC_SCRATCH53_0" of the Tegra K1 Technical Reference - Manual. - - nvidia,bus-addr: - $ref: /schemas/types.yaml#/definitions/uint32 - description: Bus address of the PMU on the I2C bus. - - nvidia,reg-addr: - $ref: /schemas/types.yaml#/definitions/uint32 - description: PMU I2C register address to issue poweroff command. - - nvidia,reg-data: - $ref: /schemas/types.yaml#/definitions/uint32 - description: Poweroff command to write to PMU. - - nvidia,pinmux-id: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Pinmux used by the hardware when issuing Poweroff command. - Defaults to 0. Valid values are described in section 12.5.2 - "Pinmux Support" of the Tegra4 Technical Reference Manual. - - required: - - nvidia,i2c-controller-id - - nvidia,bus-addr - - nvidia,reg-addr - - nvidia,reg-data - - additionalProperties: false - - powergates: - type: object - description: | - This node contains a hierarchy of power domain nodes, which should - match the powergates on the Tegra SoC. Each powergate node - represents a power-domain on the Tegra SoC that can be power-gated - by the Tegra PMC. - Hardware blocks belonging to a power domain should contain - "power-domains" property that is a phandle pointing to corresponding - powergate node. - The name of the powergate node should be one of the below. Note that - not every powergate is applicable to all Tegra devices and the following - list shows which powergates are applicable to which devices. - Please refer to Tegra TRM for mode details on the powergate nodes to - use for each power-gate block inside Tegra. - Name Description Devices Applicable - 3d 3D Graphics Tegra20/114/124/210 - 3d0 3D Graphics 0 Tegra30 - 3d1 3D Graphics 1 Tegra30 - aud Audio Tegra210 - dfd Debug Tegra210 - dis Display A Tegra114/124/210 - disb Display B Tegra114/124/210 - heg 2D Graphics Tegra30/114/124/210 - iram Internal RAM Tegra124/210 - mpe MPEG Encode All - nvdec NVIDIA Video Decode Engine Tegra210 - nvjpg NVIDIA JPEG Engine Tegra210 - pcie PCIE Tegra20/30/124/210 - sata SATA Tegra30/124/210 - sor Display interfaces Tegra124/210 - ve2 Video Encode Engine 2 Tegra210 - venc Video Encode Engine All - vdec Video Decode Engine Tegra20/30/114/124 - vic Video Imaging Compositor Tegra124/210 - xusba USB Partition A Tegra114/124/210 - xusbb USB Partition B Tegra114/124/210 - xusbc USB Partition C Tegra114/124/210 - - patternProperties: - "^[a-z0-9]+$": - type: object - additionalProperties: false - - properties: - clocks: - minItems: 1 - maxItems: 8 - description: - Must contain an entry for each clock required by the PMC - for controlling a power-gate. - See ../clocks/clock-bindings.txt document for more details. - - resets: - minItems: 1 - maxItems: 8 - description: - Must contain an entry for each reset required by the PMC - for controlling a power-gate. - See ../reset/reset.txt for more details. - - power-domains: - maxItems: 1 - - '#power-domain-cells': - const: 0 - description: Must be 0. - - required: - - clocks - - resets - - '#power-domain-cells' - - additionalProperties: false - -patternProperties: - "^[a-f0-9]+-[a-f0-9]+$": - type: object - description: - This is a Pad configuration node. On Tegra SOCs a pad is a set of - pins which are configured as a group. The pin grouping is a fixed - attribute of the hardware. The PMC can be used to set pad power state - and signaling voltage. A pad can be either in active or power down mode. - The support for power state and signaling voltage configuration varies - depending on the pad in question. 3.3V and 1.8V signaling voltages - are supported on pins where software controllable signaling voltage - switching is available. - - The pad configuration state nodes are placed under the pmc node and they - are referred to by the pinctrl client properties. For more information - see Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt. - The pad name should be used as the value of the pins property in pin - configuration nodes. - - The following pads are present on Tegra124 and Tegra132 - audio, bb, cam, comp, csia, csb, cse, dsi, dsib, dsic, dsid, hdmi, hsic, - hv, lvds, mipi-bias, nand, pex-bias, pex-clk1, pex-clk2, pex-cntrl, - sdmmc1, sdmmc3, sdmmc4, sys_ddc, uart, usb0, usb1, usb2, usb_bias. - - The following pads are present on Tegra210 - audio, audio-hv, cam, csia, csib, csic, csid, csie, csif, dbg, - debug-nonao, dmic, dp, dsi, dsib, dsic, dsid, emmc, emmc2, gpio, hdmi, - hsic, lvds, mipi-bias, pex-bias, pex-clk1, pex-clk2, pex-cntrl, sdmmc1, - sdmmc3, spi, spi-hv, uart, usb0, usb1, usb2, usb3, usb-bias. - - properties: - pins: - $ref: /schemas/types.yaml#/definitions/string - description: Must contain name of the pad(s) to be configured. - - low-power-enable: - $ref: /schemas/types.yaml#/definitions/flag - description: Configure the pad into power down mode. - - low-power-disable: - $ref: /schemas/types.yaml#/definitions/flag - description: Configure the pad into active mode. - - power-source: - $ref: /schemas/types.yaml#/definitions/uint32 - description: - Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 or - TEGRA_IO_PAD_VOLTAGE_3V3 to select between signaling voltages. - The values are defined in - include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h. - Power state can be configured on all Tegra124 and Tegra132 - pads. None of the Tegra124 or Tegra132 pads support signaling - voltage switching. - All of the listed Tegra210 pads except pex-cntrl support power - state configuration. Signaling voltage switching is supported - on below Tegra210 pads. - audio, audio-hv, cam, dbg, dmic, gpio, pex-cntrl, sdmmc1, - sdmmc3, spi, spi-hv, and uart. - - required: - - pins - - additionalProperties: false - -required: - - compatible - - reg - - clock-names - - clocks - - '#clock-cells' - -additionalProperties: false - -dependencies: - "nvidia,suspend-mode": ["nvidia,core-pwr-off-time", "nvidia,cpu-pwr-off-time"] - "nvidia,core-pwr-off-time": ["nvidia,core-pwr-good-time"] - "nvidia,cpu-pwr-off-time": ["nvidia,cpu-pwr-good-time"] - -examples: - - | - - #include <dt-bindings/clock/tegra210-car.h> - #include <dt-bindings/pinctrl/pinctrl-tegra-io-pad.h> - #include <dt-bindings/soc/tegra-pmc.h> - - tegra_pmc: pmc@7000e400 { - compatible = "nvidia,tegra210-pmc"; - reg = <0x7000e400 0x400>; - core-supply = <®ulator>; - clocks = <&tegra_car TEGRA210_CLK_PCLK>, <&clk32k_in>; - clock-names = "pclk", "clk32k_in"; - #clock-cells = <1>; - - nvidia,invert-interrupt; - nvidia,suspend-mode = <0>; - nvidia,cpu-pwr-good-time = <0>; - nvidia,cpu-pwr-off-time = <0>; - nvidia,core-pwr-good-time = <4587 3876>; - nvidia,core-pwr-off-time = <39065>; - nvidia,core-power-req-active-high; - nvidia,sys-clock-req-active-high; - - pd_core: core-domain { - operating-points-v2 = <&core_opp_table>; - #power-domain-cells = <0>; - }; - - powergates { - pd_audio: aud { - clocks = <&tegra_car TEGRA210_CLK_APE>, - <&tegra_car TEGRA210_CLK_APB2APE>; - resets = <&tegra_car 198>; - power-domains = <&pd_core>; - #power-domain-cells = <0>; - }; - - pd_xusbss: xusba { - clocks = <&tegra_car TEGRA210_CLK_XUSB_SS>; - resets = <&tegra_car TEGRA210_CLK_XUSB_SS>; - power-domains = <&pd_core>; - #power-domain-cells = <0>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml index 3c7a2425f3e6..a17297cbefcb 100644 --- a/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml +++ b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml @@ -151,7 +151,7 @@ allOf: - interconnects - power-domains -additionalProperties: true +additionalProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml index 44892aa589fd..580f9a97ddf7 100644 --- a/Documentation/devicetree/bindings/cache/qcom,llcc.yaml +++ b/Documentation/devicetree/bindings/cache/qcom,llcc.yaml @@ -20,6 +20,7 @@ description: | properties: compatible: enum: + - qcom,qdu1000-llcc - qcom,sc7180-llcc - qcom,sc7280-llcc - qcom,sc8180x-llcc @@ -44,6 +45,14 @@ properties: interrupts: maxItems: 1 + nvmem-cells: + items: + - description: Reference to an nvmem node for multi channel DDR + + nvmem-cell-names: + items: + - const: multi-chan-ddr + required: - compatible - reg @@ -92,6 +101,7 @@ allOf: compatible: contains: enum: + - qcom,qdu1000-llcc - qcom,sc8180x-llcc - qcom,sc8280xp-llcc then: diff --git a/Documentation/devicetree/bindings/clock/amlogic,s4-peripherals-clkc.yaml b/Documentation/devicetree/bindings/clock/amlogic,s4-peripherals-clkc.yaml new file mode 100644 index 000000000000..c229e4f0c1d9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,s4-peripherals-clkc.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Amlogic, Inc. All rights reserved +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/amlogic,s4-peripherals-clkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic S4 Peripherals Clock Controller + +maintainers: + - Yu Tu <yu.tu@amlogic.com> + +properties: + compatible: + const: amlogic,s4-peripherals-clkc + + reg: + maxItems: 1 + + clocks: + minItems: 14 + items: + - description: input fixed pll div2 + - description: input fixed pll div2p5 + - description: input fixed pll div3 + - description: input fixed pll div4 + - description: input fixed pll div5 + - description: input fixed pll div7 + - description: input hifi pll + - description: input gp0 pll + - description: input mpll0 + - description: input mpll1 + - description: input mpll2 + - description: input mpll3 + - description: input hdmi pll + - description: input oscillator (usually at 24MHz) + - description: input external 32kHz reference (optional) + + clock-names: + minItems: 14 + items: + - const: fclk_div2 + - const: fclk_div2p5 + - const: fclk_div3 + - const: fclk_div4 + - const: fclk_div5 + - const: fclk_div7 + - const: hifi_pll + - const: gp0_pll + - const: mpll0 + - const: mpll1 + - const: mpll2 + - const: mpll3 + - const: hdmi_pll + - const: xtal + - const: ext_32k + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - "#clock-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/amlogic,s4-peripherals-clkc.h> + + clkc_periphs: clock-controller@fe000000 { + compatible = "amlogic,s4-peripherals-clkc"; + reg = <0xfe000000 0x49c>; + clocks = <&clkc_pll 3>, + <&clkc_pll 13>, + <&clkc_pll 5>, + <&clkc_pll 7>, + <&clkc_pll 9>, + <&clkc_pll 11>, + <&clkc_pll 17>, + <&clkc_pll 15>, + <&clkc_pll 25>, + <&clkc_pll 27>, + <&clkc_pll 29>, + <&clkc_pll 31>, + <&clkc_pll 20>, + <&xtal>; + clock-names = "fclk_div2", "fclk_div2p5", "fclk_div3", "fclk_div4", + "fclk_div5", "fclk_div7", "hifi_pll", "gp0_pll", + "mpll0", "mpll1", "mpll2", "mpll3", "hdmi_pll", "xtal"; + #clock-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/clock/amlogic,s4-pll-clkc.yaml b/Documentation/devicetree/bindings/clock/amlogic,s4-pll-clkc.yaml new file mode 100644 index 000000000000..d8932ec26ca8 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,s4-pll-clkc.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Amlogic, Inc. All rights reserved +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/amlogic,s4-pll-clkc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Amlogic S4 PLL Clock Controller + +maintainers: + - Yu Tu <yu.tu@amlogic.com> + +properties: + compatible: + const: amlogic,s4-pll-clkc + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: xtal + + "#clock-cells": + const: 1 + +required: + - compatible + - reg + - clocks + - clock-names + - "#clock-cells" + +additionalProperties: false + +examples: + - | + clkc_pll: clock-controller@fe008000 { + compatible = "amlogic,s4-pll-clkc"; + reg = <0xfe008000 0x1e8>; + clocks = <&xtal>; + clock-names = "xtal"; + #clock-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,hfpll.txt b/Documentation/devicetree/bindings/clock/qcom,hfpll.txt index ec02a024424c..5769cbbe76be 100644 --- a/Documentation/devicetree/bindings/clock/qcom,hfpll.txt +++ b/Documentation/devicetree/bindings/clock/qcom,hfpll.txt @@ -12,6 +12,9 @@ PROPERTIES "qcom,hfpll-apq8064", "qcom,hfpll" "qcom,hfpll-msm8974", "qcom,hfpll" "qcom,hfpll-msm8960", "qcom,hfpll" + "qcom,msm8976-hfpll-a53", "qcom,hfpll" + "qcom,msm8976-hfpll-a72", "qcom,hfpll" + "qcom,msm8976-hfpll-cci", "qcom,hfpll" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml index fd14d18309a8..4eb5e59f6772 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,rpmhcc.yaml @@ -28,6 +28,7 @@ properties: - qcom,sdx55-rpmh-clk - qcom,sdx65-rpmh-clk - qcom,sdx75-rpmh-clk + - qcom,sm4450-rpmh-clk - qcom,sm6350-rpmh-clk - qcom,sm8150-rpmh-clk - qcom,sm8250-rpmh-clk diff --git a/Documentation/devicetree/bindings/clock/qcom,sm4450-gcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm4450-gcc.yaml new file mode 100644 index 000000000000..5953c8d92436 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,sm4450-gcc.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/clock/qcom,sm4450-gcc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Global Clock & Reset Controller on SM4450 + +maintainers: + - Ajit Pandey <quic_ajipan@quicinc.com> + - Taniya Das <quic_tdas@quicinc.com> + +description: | + Qualcomm global clock control module provides the clocks, resets and power + domains on SM4450 + + See also:: include/dt-bindings/clock/qcom,sm4450-gcc.h + +properties: + compatible: + const: qcom,sm4450-gcc + + clocks: + items: + - description: Board XO source + - description: Sleep clock source + - description: UFS Phy Rx symbol 0 clock source + - description: UFS Phy Rx symbol 1 clock source + - description: UFS Phy Tx symbol 0 clock source + - description: USB3 Phy wrapper pipe clock source + +required: + - compatible + - clocks + +allOf: + - $ref: qcom,gcc.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + clock-controller@100000 { + compatible = "qcom,sm4450-gcc"; + reg = <0x00100000 0x001f4200>; + clocks = <&rpmhcc RPMH_CXO_CLK>, <&sleep_clk>, + <&ufs_mem_phy 0>, <&ufs_mem_phy 1>, + <&ufs_mem_phy 2>, <&usb_1_qmpphy>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; + +... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml index 8178c35bc348..dc3c18e4ead7 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml @@ -13,11 +13,15 @@ description: | Qualcomm camera clock control module provides the clocks, resets and power domains on SM8450. - See also:: include/dt-bindings/clock/qcom,sm8450-camcc.h + See also:: + include/dt-bindings/clock/qcom,sm8450-camcc.h + include/dt-bindings/clock/qcom,sm8550-camcc.h properties: compatible: - const: qcom,sm8450-camcc + enum: + - qcom,sm8450-camcc + - qcom,sm8550-camcc clocks: items: diff --git a/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml b/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml index fe2fba18ae84..80a8c7114c31 100644 --- a/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,rzg2l-cpg.yaml @@ -27,6 +27,7 @@ properties: - renesas,r9a07g043-cpg # RZ/G2UL{Type-1,Type-2} and RZ/Five - renesas,r9a07g044-cpg # RZ/G2{L,LC} - renesas,r9a07g054-cpg # RZ/V2L + - renesas,r9a08g045-cpg # RZ/G3S - renesas,r9a09g011-cpg # RZ/V2M reg: diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml index c1d225fcf2d5..56fc71d6a081 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.yaml @@ -23,6 +23,7 @@ properties: - enum: - qcom,qcm2290-cpufreq-hw - qcom,sc7180-cpufreq-hw + - qcom,sdm670-cpufreq-hw - qcom,sdm845-cpufreq-hw - qcom,sm6115-cpufreq-hw - qcom,sm6350-cpufreq-hw @@ -36,11 +37,13 @@ properties: - qcom,sa8775p-cpufreq-epss - qcom,sc7280-cpufreq-epss - qcom,sc8280xp-cpufreq-epss + - qcom,sdx75-cpufreq-epss - qcom,sm6375-cpufreq-epss - qcom,sm8250-cpufreq-epss - qcom,sm8350-cpufreq-epss - qcom,sm8450-cpufreq-epss - qcom,sm8550-cpufreq-epss + - qcom,sm8650-cpufreq-epss - const: qcom,cpufreq-epss reg: @@ -128,6 +131,7 @@ allOf: - qcom,qdu1000-cpufreq-epss - qcom,sc7180-cpufreq-hw - qcom,sc8280xp-cpufreq-epss + - qcom,sdm670-cpufreq-hw - qcom,sdm845-cpufreq-hw - qcom,sm6115-cpufreq-hw - qcom,sm6350-cpufreq-hw diff --git a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml index 7e1bb992ce90..547265b8b118 100644 --- a/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml +++ b/Documentation/devicetree/bindings/cpufreq/qcom-cpufreq-nvmem.yaml @@ -27,8 +27,12 @@ select: enum: - qcom,apq8064 - qcom,apq8096 + - qcom,ipq5332 + - qcom,ipq6018 - qcom,ipq8064 - qcom,ipq8074 + - qcom,ipq9574 + - qcom,msm8909 - qcom,msm8939 - qcom,msm8960 - qcom,msm8974 @@ -43,7 +47,9 @@ patternProperties: - if: properties: compatible: - const: operating-points-v2-kryo-cpu + enum: + - operating-points-v2-krait-cpu + - operating-points-v2-kryo-cpu then: $ref: /schemas/opp/opp-v2-kryo-cpu.yaml# diff --git a/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml index d531f3af3ea4..41df80bcdcd9 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml +++ b/Documentation/devicetree/bindings/crypto/fsl-imx-sahara.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/crypto/fsl-imx-sahara.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Freescale SAHARA Cryptographic Accelerator included in some i.MX chips +title: Freescale SAHARA Cryptographic Accelerator maintainers: - Steffen Trumtrar <s.trumtrar@pengutronix.de> @@ -19,19 +19,56 @@ properties: maxItems: 1 interrupts: - maxItems: 1 + items: + - description: SAHARA Interrupt for Host 0 + - description: SAHARA Interrupt for Host 1 + minItems: 1 + + clocks: + items: + - description: Sahara IPG clock + - description: Sahara AHB clock + + clock-names: + items: + - const: ipg + - const: ahb required: - compatible - reg - interrupts + - clocks + - clock-names + +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,imx53-sahara + then: + properties: + interrupts: + minItems: 2 + maxItems: 2 + else: + properties: + interrupts: + maxItems: 1 additionalProperties: false examples: - | + #include <dt-bindings/clock/imx27-clock.h> + crypto@10025000 { compatible = "fsl,imx27-sahara"; - reg = < 0x10025000 0x800>; + reg = <0x10025000 0x800>; interrupts = <75>; + clocks = <&clks IMX27_CLK_SAHARA_IPG_GATE>, + <&clks IMX27_CLK_SAHARA_AHB_GATE>; + clock-names = "ipg", "ahb"; }; diff --git a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml index 7da9aa82d837..ca4f7d1cefaa 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml @@ -13,6 +13,7 @@ properties: compatible: items: - enum: + - qcom,sa8775p-inline-crypto-engine - qcom,sm8450-inline-crypto-engine - qcom,sm8550-inline-crypto-engine - const: qcom,inline-crypto-engine diff --git a/Documentation/devicetree/bindings/crypto/qcom,prng.yaml b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml index bb42f4588b40..13070db0f70c 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,prng.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,prng.yaml @@ -11,9 +11,17 @@ maintainers: properties: compatible: - enum: - - qcom,prng # 8916 etc. - - qcom,prng-ee # 8996 and later using EE + oneOf: + - enum: + - qcom,prng # 8916 etc. + - qcom,prng-ee # 8996 and later using EE + - items: + - enum: + - qcom,sa8775p-trng + - qcom,sc7280-trng + - qcom,sm8450-trng + - qcom,sm8550-trng + - const: qcom,trng reg: maxItems: 1 @@ -28,8 +36,18 @@ properties: required: - compatible - reg - - clocks - - clock-names + +allOf: + - if: + not: + properties: + compatible: + contains: + const: qcom,trng + then: + required: + - clocks + - clock-names additionalProperties: false diff --git a/Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml b/Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml new file mode 100644 index 000000000000..50d3fabe958d --- /dev/null +++ b/Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/devfreq/event/rockchip,dfi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip DFI + +maintainers: + - Sascha Hauer <s.hauer@pengutronix.de> + +properties: + compatible: + enum: + - rockchip,rk3399-dfi + - rockchip,rk3568-dfi + - rockchip,rk3588-dfi + + clocks: + maxItems: 1 + + clock-names: + items: + - const: pclk_ddr_mon + + interrupts: + minItems: 1 + maxItems: 4 + + reg: + maxItems: 1 + + rockchip,pmu: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the syscon managing the "PMU general register files". + +required: + - compatible + - interrupts + - reg + +if: + properties: + compatible: + contains: + enum: + - rockchip,rk3399-dfi + +then: + required: + - clocks + - clock-names + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/rk3308-cru.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + + dfi: dfi@ff630000 { + compatible = "rockchip,rk3399-dfi"; + reg = <0x00 0xff630000 0x00 0x4000>; + interrupts = <GIC_SPI 131 IRQ_TYPE_LEVEL_HIGH 0>; + rockchip,pmu = <&pmugrf>; + clocks = <&cru PCLK_DDR_MON>; + clock-names = "pclk_ddr_mon"; + }; + }; diff --git a/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt b/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt deleted file mode 100644 index 148191b0fc15..000000000000 --- a/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt +++ /dev/null @@ -1,18 +0,0 @@ - -* Rockchip rk3399 DFI device - -Required properties: -- compatible: Must be "rockchip,rk3399-dfi". -- reg: physical base address of each DFI and length of memory mapped region -- rockchip,pmu: phandle to the syscon managing the "pmu general register files" -- clocks: phandles for clock specified in "clock-names" property -- clock-names : the name of clock used by the DFI, must be "pclk_ddr_mon"; - -Example: - dfi: dfi@ff630000 { - compatible = "rockchip,rk3399-dfi"; - reg = <0x00 0xff630000 0x00 0x4000>; - rockchip,pmu = <&pmugrf>; - clocks = <&cru PCLK_DDR_MON>; - clock-names = "pclk_ddr_mon"; - }; diff --git a/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml b/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml index 1f8f2182e2f1..9cc1fd0751cd 100644 --- a/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml +++ b/Documentation/devicetree/bindings/display/ilitek,ili9486.yaml @@ -50,10 +50,6 @@ examples: - | #include <dt-bindings/gpio/gpio.h> - backlight: backlight { - compatible = "gpio-backlight"; - gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; - }; spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml index 90e323e19edb..3cabbba86581 100644 --- a/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9163.yaml @@ -48,10 +48,6 @@ examples: - | #include <dt-bindings/gpio/gpio.h> - backlight: backlight { - compatible = "gpio-backlight"; - gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; - }; spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple-lvds-dual-ports.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple-lvds-dual-ports.yaml new file mode 100644 index 000000000000..a5a596ff8e75 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panel-simple-lvds-dual-ports.yaml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/panel-simple-lvds-dual-ports.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Simple LVDS panels with one power supply and dual LVDS ports + +maintainers: + - Liu Ying <victor.liu@nxp.com> + - Thierry Reding <thierry.reding@gmail.com> + - Sam Ravnborg <sam@ravnborg.org> + +description: | + This binding file is a collection of the LVDS panels that + has dual LVDS ports and requires only a single power-supply. + The first port receives odd pixels, and the second port receives even pixels. + There are optionally a backlight and an enable GPIO. + The panel may use an OF graph binding for the association to the display, + or it may be a direct child node of the display. + + If the panel is more advanced a dedicated binding file is required. + +allOf: + - $ref: panel-common.yaml# + +properties: + + compatible: + enum: + # compatible must be listed in alphabetical order, ordered by compatible. + # The description in the comment is mandatory for each compatible. + + # AU Optronics Corporation 13.3" FHD (1920x1080) TFT LCD panel + - auo,g133han01 + # AU Optronics Corporation 18.5" FHD (1920x1080) TFT LCD panel + - auo,g185han01 + # AU Optronics Corporation 19.0" (1280x1024) TFT LCD panel + - auo,g190ean01 + # Kaohsiung Opto-Electronics Inc. 10.1" WUXGA (1920 x 1200) LVDS TFT LCD panel + - koe,tx26d202vm0bwa + # NLT Technologies, Ltd. 15.6" FHD (1920x1080) LVDS TFT LCD panel + - nlt,nl192108ac18-02d + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: The first sink port. + + properties: + dual-lvds-odd-pixels: + type: boolean + description: The first sink port for odd pixels. + + required: + - dual-lvds-odd-pixels + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + description: The second sink port. + + properties: + dual-lvds-even-pixels: + type: boolean + description: The second sink port for even pixels. + + required: + - dual-lvds-even-pixels + + required: + - port@0 + - port@1 + + backlight: true + enable-gpios: true + power-supply: true + +additionalProperties: false + +required: + - compatible + - ports + - power-supply + +examples: + - | + panel: panel-lvds { + compatible = "koe,tx26d202vm0bwa"; + power-supply = <&vdd_lcd_reg>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + dual-lvds-odd-pixels; + reg = <0>; + + panel_lvds0_in: endpoint { + remote-endpoint = <&lvds0_out>; + }; + }; + + port@1 { + dual-lvds-even-pixels; + reg = <1>; + + panel_lvds1_in: endpoint { + remote-endpoint = <&lvds1_out>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 81ac402ceed1..3ec9ee95045f 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -65,14 +65,8 @@ properties: - auo,g104sn02 # AU Optronics Corporation 12.1" (1280x800) TFT LCD panel - auo,g121ean01 - # AU Optronics Corporation 13.3" FHD (1920x1080) TFT LCD panel - - auo,g133han01 # AU Optronics Corporation 15.6" (1366x768) TFT LCD panel - auo,g156xtn01 - # AU Optronics Corporation 18.5" FHD (1920x1080) TFT LCD panel - - auo,g185han01 - # AU Optronics Corporation 19.0" (1280x1024) TFT LCD panel - - auo,g190ean01 # AU Optronics Corporation 31.5" FHD (1920x1080) TFT LCD panel - auo,p320hvn03 # AU Optronics Corporation 21.5" FHD (1920x1080) color TFT LCD panel @@ -204,8 +198,6 @@ properties: - kingdisplay,kd116n21-30nv-a010 # Kaohsiung Opto-Electronics Inc. 5.7" QVGA (320 x 240) TFT LCD panel - koe,tx14d24vm1bpa - # Kaohsiung Opto-Electronics Inc. 10.1" WUXGA (1920 x 1200) LVDS TFT LCD panel - - koe,tx26d202vm0bwa # Kaohsiung Opto-Electronics. TX31D200VM0BAA 12.3" HSXGA LVDS panel - koe,tx31d200vm0baa # Kyocera Corporation 7" WVGA (800x480) transmissive color TFT @@ -256,8 +248,6 @@ properties: - neweast,wjfh116008a # Newhaven Display International 480 x 272 TFT LCD panel - newhaven,nhd-4.3-480272ef-atxl - # NLT Technologies, Ltd. 15.6" FHD (1920x1080) LVDS TFT LCD panel - - nlt,nl192108ac18-02d # New Vision Display 7.0" 800 RGB x 480 TFT LCD panel - nvd,9128 # OKAYA Electric America, Inc. RS800480T-7X0GP 7" WVGA LCD panel diff --git a/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml b/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml index 621f27148419..3b0ebc0db8e0 100644 --- a/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml +++ b/Documentation/devicetree/bindings/display/sitronix,st7735r.yaml @@ -54,11 +54,6 @@ examples: - | #include <dt-bindings/gpio/gpio.h> - backlight: backlight { - compatible = "gpio-backlight"; - gpios = <&gpio 44 GPIO_ACTIVE_HIGH>; - }; - spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/dma/qcom,gpi.yaml b/Documentation/devicetree/bindings/dma/qcom,gpi.yaml index f61145c91b6d..88d0de3d1b46 100644 --- a/Documentation/devicetree/bindings/dma/qcom,gpi.yaml +++ b/Documentation/devicetree/bindings/dma/qcom,gpi.yaml @@ -69,6 +69,8 @@ properties: dma-channel-mask: maxItems: 1 + dma-coherent: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml index 98139489d4b5..b6864d0ee81e 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.yaml +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml @@ -12,6 +12,7 @@ maintainers: allOf: - $ref: /schemas/nvmem/nvmem.yaml + - $ref: /schemas/nvmem/nvmem-deprecated-cells.yaml select: properties: @@ -68,10 +69,14 @@ properties: - items: pattern: c32$ - items: + pattern: c32d-wl$ + - items: pattern: cs32$ - items: pattern: c64$ - items: + pattern: c64d-wl$ + - items: pattern: cs64$ - items: pattern: c128$ diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml index b138f3d23df8..4591523b51a0 100644 --- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml +++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml @@ -38,6 +38,9 @@ properties: with shmem address(4KB-page, offset) as parameters items: - const: arm,scmi-smc-param + - description: SCMI compliant firmware with Qualcomm SMC/HVC transport + items: + - const: qcom,scmi-smc - description: SCMI compliant firmware with SCMI Virtio transport. The virtio transport only supports a single device. items: @@ -149,8 +152,15 @@ properties: '#clock-cells': const: 1 - required: - - '#clock-cells' + '#power-domain-cells': + const: 1 + + oneOf: + - required: + - '#clock-cells' + + - required: + - '#power-domain-cells' protocol@14: $ref: '#/$defs/protocol-node' @@ -306,6 +316,7 @@ else: enum: - arm,scmi-smc - arm,scmi-smc-param + - qcom,scmi-smc then: required: - arm,smc-id diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml index 4233ea839bfc..0613a37a851a 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.yaml +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.yaml @@ -24,6 +24,7 @@ properties: - qcom,scm-apq8064 - qcom,scm-apq8084 - qcom,scm-ipq4019 + - qcom,scm-ipq5018 - qcom,scm-ipq5332 - qcom,scm-ipq6018 - qcom,scm-ipq806x @@ -56,6 +57,7 @@ properties: - qcom,scm-sm6125 - qcom,scm-sm6350 - qcom,scm-sm6375 + - qcom,scm-sm7150 - qcom,scm-sm8150 - qcom,scm-sm8250 - qcom,scm-sm8350 @@ -89,6 +91,14 @@ properties: protocol to handle sleeping SCM calls. maxItems: 1 + qcom,sdi-enabled: + description: + Indicates that the SDI (Secure Debug Image) has been enabled by TZ + by default and it needs to be disabled. + If not disabled WDT assertion or reboot will cause the board to hang + in the debug mode. + type: boolean + qcom,dload-mode: $ref: /schemas/types.yaml#/definitions/phandle-array items: diff --git a/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml b/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml index d0ca2af89f1e..918776d16ef3 100644 --- a/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/fsl-imx-gpio.yaml @@ -19,10 +19,18 @@ properties: - fsl,imx35-gpio - fsl,imx7d-gpio - items: + - enum: + - fsl,imx27-gpio + - const: fsl,imx21-gpio + - items: - const: fsl,imx35-gpio - const: fsl,imx31-gpio - items: - enum: + - fsl,imx25-gpio + - const: fsl,imx35-gpio + - items: + - enum: - fsl,imx50-gpio - fsl,imx51-gpio - fsl,imx53-gpio diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml index 7c2d152e8617..a27f92950257 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.yaml @@ -20,6 +20,7 @@ description: | properties: compatible: oneOf: + - const: fsl,imx8ulp-gpio - const: fsl,vf610-gpio - items: - const: fsl,imx7ulp-gpio @@ -27,16 +28,18 @@ properties: - items: - enum: - fsl,imx93-gpio - - fsl,imx8ulp-gpio - - const: fsl,imx7ulp-gpio + - fsl,imx95-gpio + - const: fsl,imx8ulp-gpio reg: - description: The first reg tuple represents the PORT module, the second tuple - represents the GPIO module. + minItems: 1 maxItems: 2 interrupts: - maxItems: 1 + items: + - description: GPIO Trustzone non-secure interrupt number + - description: GPIO Trustzone secure interrupt number + minItems: 1 interrupt-controller: true @@ -59,7 +62,8 @@ properties: - const: port gpio-ranges: - maxItems: 1 + minItems: 1 + maxItems: 4 patternProperties: "^.+-hog(-[0-9]+)?$": @@ -77,6 +81,30 @@ required: - "#gpio-cells" - gpio-controller +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,vf610-gpio + - fsl,imx7ulp-gpio + then: + properties: + interrupts: + maxItems: 1 + reg: + items: + - description: PORT register base address + - description: GPIO register base address + else: + properties: + interrupts: + minItems: 2 + reg: + items: + - description: GPIO register base address + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt deleted file mode 100644 index 8dc41ed99685..000000000000 --- a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt +++ /dev/null @@ -1,38 +0,0 @@ -Intel IXP4xx XScale Networking Processors GPIO - -This GPIO controller is found in the Intel IXP4xx processors. -It supports 16 GPIO lines. - -The interrupt portions of the GPIO controller is hierarchical: -the synchronous edge detector is part of the GPIO block, but the -actual enabling/disabling of the interrupt line is done in the -main IXP4xx interrupt controller which has a 1:1 mapping for -the first 12 GPIO lines to 12 system interrupts. - -The remaining 4 GPIO lines can not be used for receiving -interrupts. - -The interrupt parent of this GPIO controller must be the -IXP4xx interrupt controller. - -Required properties: - -- compatible : Should be - "intel,ixp4xx-gpio" -- reg : Should contain registers location and length -- gpio-controller : marks this as a GPIO controller -- #gpio-cells : Should be 2, see gpio/gpio.txt -- interrupt-controller : marks this as an interrupt controller -- #interrupt-cells : a standard two-cell interrupt, see - interrupt-controller/interrupts.txt - -Example: - -gpio0: gpio@c8004000 { - compatible = "intel,ixp4xx-gpio"; - reg = <0xc8004000 0x1000>; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; -}; diff --git a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml new file mode 100644 index 000000000000..bfcb1f364c3a --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/intel,ixp4xx-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Intel IXP4xx XScale Networking Processors GPIO Controller + +description: | + This GPIO controller is found in the Intel IXP4xx + processors. It supports 16 GPIO lines. + The interrupt portions of the GPIO controller is hierarchical. + The synchronous edge detector is part of the GPIO block, but the + actual enabling/disabling of the interrupt line is done in the + main IXP4xx interrupt controller which has a 1-to-1 mapping for + the first 12 GPIO lines to 12 system interrupts. + The remaining 4 GPIO lines can not be used for receiving + interrupts. + The interrupt parent of this GPIO controller must be the + IXP4xx interrupt controller. + GPIO 14 and 15 can be used as clock outputs rather than GPIO, + and this can be enabled by a special flag. + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +properties: + compatible: + const: intel,ixp4xx-gpio + + reg: + maxItems: 1 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + interrupt-controller: true + + "#interrupt-cells": + const: 2 + + intel,ixp4xx-gpio14-clkout: + description: If defined, enables clock output on GPIO 14 + instead of GPIO. + type: boolean + + intel,ixp4xx-gpio15-clkout: + description: If defined, enables clock output on GPIO 15 + instead of GPIO. + type: boolean + +required: + - compatible + - reg + - "#gpio-cells" + - interrupt-controller + - "#interrupt-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + gpio@c8004000 { + compatible = "intel,ixp4xx-gpio"; + reg = <0xc8004000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml b/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml index fb86e8ce6349..cf3b1b270aa8 100644 --- a/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/loongson,ls-gpio.yaml @@ -11,9 +11,22 @@ maintainers: properties: compatible: - enum: - - loongson,ls2k-gpio - - loongson,ls7a-gpio + oneOf: + - enum: + - loongson,ls2k-gpio + - loongson,ls2k0500-gpio0 + - loongson,ls2k0500-gpio1 + - loongson,ls2k2000-gpio0 + - loongson,ls2k2000-gpio1 + - loongson,ls2k2000-gpio2 + - loongson,ls3a5000-gpio + - loongson,ls7a-gpio + - items: + - const: loongson,ls2k1000-gpio + - const: loongson,ls2k-gpio + - items: + - const: loongson,ls7a1000-gpio + - const: loongson,ls7a-gpio reg: maxItems: 1 @@ -49,7 +62,7 @@ examples: #include <dt-bindings/interrupt-controller/irq.h> gpio0: gpio@1fe00500 { - compatible = "loongson,ls2k-gpio"; + compatible = "loongson,ls2k1000-gpio", "loongson,ls2k-gpio"; reg = <0x1fe00500 0x38>; ngpios = <64>; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml new file mode 100644 index 000000000000..011e5b65c79c --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc2991.yaml @@ -0,0 +1,128 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/adi,ltc2991.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices LTC2991 Octal I2C Voltage, Current and Temperature Monitor + +maintainers: + - Antoniu Miclaus <antoniu.miclaus@analog.com> + +description: | + The LTC2991 is used to monitor system temperatures, voltages and currents. + Through the I2C serial interface, the eight monitors can individually measure + supply voltages and can be paired for differential measurements of current + sense resistors or temperature sensing transistors. + + Datasheet: + https://www.analog.com/en/products/ltc2991.html + +properties: + compatible: + const: adi,ltc2991 + + reg: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + vcc-supply: true + +patternProperties: + "^channel@[0-3]$": + type: object + description: + Represents the differential/temperature channels. + + properties: + reg: + description: + The channel number. LTC2991 can monitor 4 currents/temperatures. + items: + minimum: 0 + maximum: 3 + + shunt-resistor-micro-ohms: + description: + The value of curent sense resistor in micro ohms. Pin configuration is + set for differential input pair. + + adi,temperature-enable: + description: + Enables temperature readings. Pin configuration is set for remote + diode temperature measurement. + type: boolean + + required: + - reg + + allOf: + - if: + required: + - shunt-resistor-micro-ohms + then: + properties: + adi,temperature-enable: false + + additionalProperties: false + +required: + - compatible + - reg + - vcc-supply + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + hwmon@48 { + compatible = "adi,ltc2991"; + reg = <0x48>; + vcc-supply = <&vcc>; + }; + }; + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + hwmon@48 { + #address-cells = <1>; + #size-cells = <0>; + + compatible = "adi,ltc2991"; + reg = <0x48>; + vcc-supply = <&vcc>; + + channel@0 { + reg = <0x0>; + shunt-resistor-micro-ohms = <100000>; + }; + + channel@1 { + reg = <0x1>; + shunt-resistor-micro-ohms = <100000>; + }; + + channel@2 { + reg = <0x2>; + adi,temperature-enable; + }; + + channel@3 { + reg = <0x3>; + adi,temperature-enable; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml b/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml index 2dc8b07b4d3b..f60e06ab7d0a 100644 --- a/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml +++ b/Documentation/devicetree/bindings/hwmon/adi,max31827.yaml @@ -32,6 +32,68 @@ properties: Must have values in the interval (1.6V; 3.6V) in order for the device to function correctly. + adi,comp-int: + description: + If present interrupt mode is used. If not present comparator mode is used + (default). + type: boolean + + adi,alarm-pol: + description: + Sets the alarms active state. + - 0 = active low + - 1 = active high + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + adi,fault-q: + description: + Select how many consecutive temperature faults must occur before + overtemperature or undertemperature faults are indicated in the + corresponding status bits. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [1, 2, 4, 8] + + adi,timeout-enable: + description: + Enables timeout. Bus timeout resets the I2C-compatible interface when SCL + is low for more than 30ms (nominal). + type: boolean + +allOf: + - if: + properties: + compatible: + contains: + const: adi,max31829 + + then: + properties: + adi,alarm-pol: + default: 1 + + else: + properties: + adi,alarm-pol: + default: 0 + + - if: + properties: + compatible: + contains: + const: adi,max31827 + + then: + properties: + adi,fault-q: + default: 1 + + else: + properties: + adi,fault-q: + default: 4 + + required: - compatible - reg @@ -49,6 +111,10 @@ examples: compatible = "adi,max31827"; reg = <0x42>; vref-supply = <®_vdd>; + adi,comp-int; + adi,alarm-pol = <0>; + adi,fault-q = <1>; + adi,timeout-enable; }; }; ... diff --git a/Documentation/devicetree/bindings/hwmon/ina3221.txt b/Documentation/devicetree/bindings/hwmon/ina3221.txt deleted file mode 100644 index fa63b6171407..000000000000 --- a/Documentation/devicetree/bindings/hwmon/ina3221.txt +++ /dev/null @@ -1,54 +0,0 @@ -Texas Instruments INA3221 Device Tree Bindings - -1) ina3221 node - Required properties: - - compatible: Must be "ti,ina3221" - - reg: I2C address - - Optional properties: - - ti,single-shot: This chip has two power modes: single-shot (chip takes one - measurement and then shuts itself down) and continuous ( - chip takes continuous measurements). The continuous mode is - more reliable and suitable for hardware monitor type device, - but the single-shot mode is more power-friendly and useful - for battery-powered device which cares power consumptions - while still needs some measurements occasionally. - If this property is present, the single-shot mode will be - used, instead of the default continuous one for monitoring. - - = The node contains optional child nodes for three channels = - = Each child node describes the information of input source = - - - #address-cells: Required only if a child node is present. Must be 1. - - #size-cells: Required only if a child node is present. Must be 0. - -2) child nodes - Required properties: - - reg: Must be 0, 1 or 2, corresponding to IN1, IN2 or IN3 port of INA3221 - - Optional properties: - - label: Name of the input source - - shunt-resistor-micro-ohms: Shunt resistor value in micro-Ohm - -Example: - -ina3221@40 { - compatible = "ti,ina3221"; - reg = <0x40>; - #address-cells = <1>; - #size-cells = <0>; - - input@0 { - reg = <0x0>; - status = "disabled"; - }; - input@1 { - reg = <0x1>; - shunt-resistor-micro-ohms = <5000>; - }; - input@2 { - reg = <0x2>; - label = "VDD_5V"; - shunt-resistor-micro-ohms = <5000>; - }; -}; diff --git a/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt b/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt index 8523777f560c..18095ba87a5a 100644 --- a/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/npcm750-pwm-fan.txt @@ -1,12 +1,16 @@ -Nuvoton NPCM7xx PWM and Fan Tacho controller device +Nuvoton NPCM PWM and Fan Tacho controller device The Nuvoton BMC NPCM7XX supports 8 Pulse-width modulation (PWM) controller outputs and 16 Fan tachometer controller inputs. +The Nuvoton BMC NPCM8XX supports 12 Pulse-width modulation (PWM) +controller outputs and 16 Fan tachometer controller inputs. + Required properties for pwm-fan node - #address-cells : should be 1. - #size-cells : should be 0. - compatible : "nuvoton,npcm750-pwm-fan" for Poleg NPCM7XX. + : "nuvoton,npcm845-pwm-fan" for Arbel NPCM8XX. - reg : specifies physical base address and size of the registers. - reg-names : must contain: * "pwm" for the PWM registers. diff --git a/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml b/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml new file mode 100644 index 000000000000..ded1c115764b --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/pmbus/infineon,tda38640.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- + +$id: http://devicetree.org/schemas/hwmon/pmbus/infineon,tda38640.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Infineon TDA38640 Synchronous Buck Regulator with SVID and I2C + +maintainers: + - Naresh Solanki <naresh.solanki@9elements.com> + +description: | + The Infineon TDA38640 is a 40A Single-voltage Synchronous Buck + Regulator with SVID and I2C designed for Industrial use. + + Datasheet: https://www.infineon.com/dgdl/Infineon-TDA38640-0000-DataSheet-v02_04-EN.pdf?fileId=8ac78c8c80027ecd018042f2337f00c9 + +properties: + compatible: + enum: + - infineon,tda38640 + + reg: + maxItems: 1 + + infineon,en-pin-fixed-level: + description: + Indicates that the chip EN pin is at fixed level or left + unconnected(has internal pull-down). + type: boolean + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + tda38640@40 { + compatible = "infineon,tda38640"; + reg = <0x40>; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml index 8648877d2d01..378d1f6aeeb3 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml @@ -26,6 +26,7 @@ properties: - ti,ina226 - ti,ina230 - ti,ina231 + - ti,ina237 - ti,ina238 reg: diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml new file mode 100644 index 000000000000..5f10f1207d69 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ti,ina3221.yaml @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/ti,ina3221.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments INA3221 Current and Voltage Monitor + +maintainers: + - Jean Delvare <jdelvare@suse.com> + - Guenter Roeck <linux@roeck-us.net> + +properties: + compatible: + const: ti,ina3221 + + reg: + maxItems: 1 + + ti,single-shot: + description: | + This chip has two power modes: single-shot (chip takes one measurement + and then shuts itself down) and continuous (chip takes continuous + measurements). The continuous mode is more reliable and suitable for + hardware monitor type device, but the single-shot mode is more power- + friendly and useful for battery-powered device which cares power + consumptions while still needs some measurements occasionally. + + If this property is present, the single-shot mode will be used, instead + of the default continuous one for monitoring. + $ref: /schemas/types.yaml#/definitions/flag + + "#address-cells": + description: Required only if a child node is present. + const: 1 + + "#size-cells": + description: Required only if a child node is present. + const: 0 + +patternProperties: + "^input@[0-2]$": + description: The node contains optional child nodes for three channels. + Each child node describes the information of input source. Input channels + default to enabled in the chip. Unless channels are explicitly disabled + in device-tree, input channels will be enabled. + type: object + additionalProperties: false + properties: + reg: + description: Must be 0, 1 and 2, corresponding to the IN1, IN2 or IN3 + ports of the INA3221, respectively. + enum: [ 0, 1, 2 ] + + label: + description: name of the input source + + shunt-resistor-micro-ohms: + description: shunt resistor value in micro-Ohm + + ti,summation-disable: + description: | + The INA3221 has a critical alert pin that can be controlled by the + summation control function. This function adds the single + shunt-voltage conversions for the desired channels in order to + compare the combined sum to the programmed limit. The Shunt-Voltage + Sum Limit register contains the programmed value that is compared + to the value in the Shunt-Voltage Sum register in order to + determine if the total summed limit is exceeded. If the + shunt-voltage sum limit value is exceeded, the critical alert pin + is asserted. + + For the summation limit to have a meaningful value, it is necessary + to use the same shunt-resistor value on all enabled channels. If + this is not the case or if a channel should not be used for + triggering the critical alert pin, then this property can be used + exclude specific channels from the summation control function. + type: boolean + + required: + - reg + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + power-sensor@40 { + compatible = "ti,ina3221"; + reg = <0x40>; + #address-cells = <1>; + #size-cells = <0>; + + input@0 { + reg = <0x0>; + /* + * Input channels are enabled by default in the device and so + * to disable, must be explicitly disabled in device-tree. + */ + status = "disabled"; + }; + + input@1 { + reg = <0x1>; + shunt-resistor-micro-ohms = <5000>; + }; + + input@2 { + reg = <0x2>; + label = "VDD_5V"; + shunt-resistor-micro-ohms = <5000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt deleted file mode 100644 index 86b2e433a969..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.txt +++ /dev/null @@ -1,135 +0,0 @@ -Pinctrl-based I2C Bus DeMux - -This binding describes an I2C bus demultiplexer that uses pin multiplexing to -route the I2C signals, and represents the pin multiplexing configuration using -the pinctrl device tree bindings. This may be used to select one I2C IP core at -runtime which may have a better feature set for a given task than another I2C -IP core on the SoC. The most simple example is to fall back to GPIO bitbanging -if your current runtime configuration hits an errata of the internal IP core. - - +-------------------------------+ - | SoC | - | | +-----+ +-----+ - | +------------+ | | dev | | dev | - | |I2C IP Core1|--\ | +-----+ +-----+ - | +------------+ \-------+ | | | - | |Pinctrl|--|------+--------+ - | +------------+ +-------+ | - | |I2C IP Core2|--/ | - | +------------+ | - | | - +-------------------------------+ - -Required properties: -- compatible: "i2c-demux-pinctrl" -- i2c-parent: List of phandles of I2C masters available for selection. The first - one will be used as default. -- i2c-bus-name: The name of this bus. Also needed as pinctrl-name for the I2C - parents. - -Furthermore, I2C mux properties and child nodes. See i2c-mux.yaml in this -directory. - -Example: - -Here is a snipplet for a bus to be demuxed. It contains various i2c clients for -HDMI, so the bus is named "i2c-hdmi": - - i2chdmi: i2c@8 { - - compatible = "i2c-demux-pinctrl"; - i2c-parent = <&gpioi2c>, <&iic2>, <&i2c2>; - i2c-bus-name = "i2c-hdmi"; - #address-cells = <1>; - #size-cells = <0>; - - ak4643: sound-codec@12 { - compatible = "asahi-kasei,ak4643"; - - #sound-dai-cells = <0>; - reg = <0x12>; - }; - - composite-in@20 { - compatible = "adi,adv7180"; - reg = <0x20>; - remote = <&vin1>; - - port { - adv7180: endpoint { - bus-width = <8>; - remote-endpoint = <&vin1ep0>; - }; - }; - }; - - hdmi@39 { - compatible = "adi,adv7511w"; - reg = <0x39>; - interrupt-parent = <&gpio1>; - interrupts = <15 IRQ_TYPE_LEVEL_LOW>; - - adi,input-depth = <8>; - adi,input-colorspace = "rgb"; - adi,input-clock = "1x"; - adi,input-style = <1>; - adi,input-justification = "evenly"; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - adv7511_in: endpoint { - remote-endpoint = <&du_out_lvds0>; - }; - }; - - port@1 { - reg = <1>; - adv7511_out: endpoint { - remote-endpoint = <&hdmi_con>; - }; - }; - }; - }; - }; - -And for clarification, here are the snipplets for the i2c-parents: - - gpioi2c: i2c@9 { - #address-cells = <1>; - #size-cells = <0>; - compatible = "i2c-gpio"; - gpios = <&gpio5 6 GPIO_ACTIVE_HIGH /* sda */ - &gpio5 5 GPIO_ACTIVE_HIGH /* scl */ - >; - i2c-gpio,delay-us = <5>; - }; - -... - -&i2c2 { - pinctrl-0 = <&i2c2_pins>; - pinctrl-names = "i2c-hdmi"; - - clock-frequency = <100000>; -}; - -... - -&iic2 { - pinctrl-0 = <&iic2_pins>; - pinctrl-names = "i2c-hdmi"; - - clock-frequency = <100000>; -}; - -Please note: - -- pinctrl properties for the parent I2C controllers need a pinctrl state - with the same name as i2c-bus-name, not "default"! - -- the i2c masters must have their status "disabled". This driver will - enable them at runtime when needed. diff --git a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml new file mode 100644 index 000000000000..2c08f2a7cf1e --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml @@ -0,0 +1,172 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-demux-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Pinctrl-based I2C Bus Demultiplexer + +maintainers: + - Wolfram Sang <wsa+renesas@sang-engineering.com> + +description: | + This binding describes an I2C bus demultiplexer that uses pin multiplexing to + route the I2C signals, and represents the pin multiplexing configuration + using the pinctrl device tree bindings. This may be used to select one I2C + IP core at runtime which may have a better feature set for a given task than + another I2C IP core on the SoC. The most simple example is to fall back to + GPIO bitbanging if your current runtime configuration hits an errata of the + internal IP core. + + +-------------------------------+ + | SoC | + | | +-----+ +-----+ + | +------------+ | | dev | | dev | + | |I2C IP Core1|--\ | +-----+ +-----+ + | +------------+ \-------+ | | | + | |Pinctrl|--|------+--------+ + | +------------+ +-------+ | + | |I2C IP Core2|--/ | + | +------------+ | + | | + +-------------------------------+ + +allOf: + - $ref: i2c-mux.yaml + - $ref: /schemas/i2c/i2c-controller.yaml# + +properties: + compatible: + const: i2c-demux-pinctrl + + i2c-parent: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + List of phandles of I2C masters available for selection. The first one + will be used as default. + + i2c-bus-name: + $ref: /schemas/types.yaml#/definitions/string + description: + The name of this bus. Also needed as pinctrl-name for the I2C parents. + +required: + - compatible + - i2c-parent + - i2c-bus-name + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + gpioi2c2: i2c-9 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "i2c-gpio"; + scl-gpios = <&gpio5 5 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>; + sda-gpios = <&gpio5 6 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>; + i2c-gpio,delay-us = <5>; + + // The I2C controller must have its status "disabled". The I2C bus + // demultiplexer will enable it at runtime when needed. + status = "disabled"; + }; + + iic2: i2c@e6520000 { + reg = <0xe6520000 0x425>; + pinctrl-0 = <&iic2_pins>; + // The pinctrl property for the parent I2C controller needs a pinctrl + // state with the same name as i2c-bus-name in the I2C bus demultiplexer + // node, not "default"! + pinctrl-names = "i2c-hdmi"; + + clock-frequency = <100000>; + + // The I2C controller must have its status "disabled". The I2C bus + // demultiplexer will enable it at runtime when needed. + status = "disabled"; + }; + + i2c2: i2c@e6530000 { + reg = <0 0xe6530000 0 0x40>; + pinctrl-0 = <&i2c2_pins>; + // The pinctrl property for the parent I2C controller needs a pinctrl + // state with the same name as i2c-bus-name in the I2C bus demultiplexer + // node, not "default"! + pinctrl-names = "i2c-hdmi"; + + clock-frequency = <100000>; + + // The I2C controller must have its status "disabled". The I2C bus + // demultiplexer will enable it at runtime when needed. + status = "disabled"; + }; + + // Example for a bus to be demuxed. It contains various I2C clients for + // HDMI, so the bus is named "i2c-hdmi": + i2chdmi: i2c-mux3 { + compatible = "i2c-demux-pinctrl"; + i2c-parent = <&iic2>, <&i2c2>, <&gpioi2c2>; + i2c-bus-name = "i2c-hdmi"; + #address-cells = <1>; + #size-cells = <0>; + + ak4643: codec@12 { + compatible = "asahi-kasei,ak4643"; + #sound-dai-cells = <0>; + reg = <0x12>; + }; + + composite-in@20 { + compatible = "adi,adv7180"; + reg = <0x20>; + + port { + adv7180: endpoint { + bus-width = <8>; + remote-endpoint = <&vin1ep0>; + }; + }; + }; + + hdmi@39 { + compatible = "adi,adv7511w"; + reg = <0x39>; + interrupt-parent = <&gpio1>; + interrupts = <15 IRQ_TYPE_LEVEL_LOW>; + clocks = <&cec_clock>; + clock-names = "cec"; + + avdd-supply = <&fixedregulator1v8>; + dvdd-supply = <&fixedregulator1v8>; + pvdd-supply = <&fixedregulator1v8>; + dvdd-3v-supply = <&fixedregulator3v3>; + bgvdd-supply = <&fixedregulator1v8>; + + adi,input-depth = <8>; + adi,input-colorspace = "rgb"; + adi,input-clock = "1x"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + adv7511_in: endpoint { + remote-endpoint = <&lvds0_out>; + }; + }; + + port@1 { + reg = <1>; + adv7511_out: endpoint { + remote-endpoint = <&hdmi_con_out>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml index 042d4dc636ee..8386cfe21532 100644 --- a/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml +++ b/Documentation/devicetree/bindings/i2c/qcom,i2c-cci.yaml @@ -25,6 +25,7 @@ properties: - items: - enum: + - qcom,sc7280-cci - qcom,sdm845-cci - qcom,sm6350-cci - qcom,sm8250-cci @@ -159,6 +160,7 @@ allOf: compatible: contains: enum: + - qcom,sc7280-cci - qcom,sm8250-cci - qcom,sm8450-cci then: diff --git a/Documentation/devicetree/bindings/i3c/i3c.yaml b/Documentation/devicetree/bindings/i3c/i3c.yaml index ab69f4115de4..c816e295d565 100644 --- a/Documentation/devicetree/bindings/i3c/i3c.yaml +++ b/Documentation/devicetree/bindings/i3c/i3c.yaml @@ -55,6 +55,12 @@ properties: May not be supported by all controllers. + mctp-controller: + type: boolean + description: | + Indicates that the system is accessible via this bus as an endpoint for + MCTP over I3C transport. + required: - "#address-cells" - "#size-cells" @@ -119,12 +125,12 @@ patternProperties: minimum: 0 maximum: 0x7f - description: | - First half of the Provisional ID (following the PID + First half of the Provisioned ID (following the PID definition provided by the I3C specification). Contains the manufacturer ID left-shifted by 1. - description: | - Second half of the Provisional ID (following the PID + Second half of the Provisioned ID (following the PID definition provided by the I3C specification). Contains the ORing of the part ID left-shifted by 16, diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml index 986df1a6ff0a..66ea894dbe55 100644 --- a/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml @@ -4,19 +4,23 @@ $id: http://devicetree.org/schemas/iio/accel/kionix,kx022a.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: ROHM/Kionix KX022A Accelerometer +title: ROHM/Kionix KX022A, KX132-1211 and KX132ACR-LBZ Accelerometers maintainers: - Matti Vaittinen <mazziesaccount@gmail.com> description: | - KX022A is a 3-axis accelerometer supporting +/- 2G, 4G, 8G and 16G ranges, - output data-rates from 0.78Hz to 1600Hz and a hardware-fifo buffering. - KX022A can be accessed either via I2C or SPI. + KX022A, KX132ACR-LBZ and KX132-1211 are 3-axis accelerometers supporting + +/- 2G, 4G, 8G and 16G ranges, variable output data-rates and a + hardware-fifo buffering. These accelerometers can be accessed either + via I2C or SPI. properties: compatible: - const: kionix,kx022a + enum: + - kionix,kx022a + - kionix,kx132-1211 + - rohm,kx132acr-lbz reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml index 875f394576c2..5cc6a9684077 100644 --- a/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml +++ b/Documentation/devicetree/bindings/iio/adc/lltc,ltc2497.yaml @@ -4,21 +4,31 @@ $id: http://devicetree.org/schemas/iio/adc/lltc,ltc2497.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Linear Technology / Analog Devices LTC2497 ADC +title: Linear Technology / Analog Devices LTC2497 and LTC2309 ADC maintainers: - Michael Hennerich <michael.hennerich@analog.com> + - Liam Beguin <liambeguin@gmail.com> description: | - 16bit ADC supporting up to 16 single ended or 8 differential inputs. - I2C interface. + LTC2309: + low noise, low power, 8-channel, 12-bit successive approximation ADC with an + I2C compatible serial interface. - https://www.analog.com/media/en/technical-documentation/data-sheets/2497fb.pdf - https://www.analog.com/media/en/technical-documentation/data-sheets/2499fe.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/2309fd.pdf + + LTC2497: + LTC2499: + 16bit ADC supporting up to 16 single ended or 8 differential inputs. + I2C interface. + + https://www.analog.com/media/en/technical-documentation/data-sheets/2497fb.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/2499fe.pdf properties: compatible: enum: + - lltc,ltc2309 - lltc,ltc2497 - lltc,ltc2499 diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3564.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3564.yaml new file mode 100644 index 000000000000..675319276197 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3564.yaml @@ -0,0 +1,205 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/microchip,mcp3564.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Microchip MCP346X and MCP356X ADC Family + +maintainers: + - Marius Cristea <marius.cristea@microchip.com> + +description: | + Bindings for the Microchip family of 153.6 ksps, Low-Noise 16/24-Bit + Delta-Sigma ADCs with an SPI interface. Datasheet can be found here: + Datasheet for MCP3561, MCP3562, MCP3564 can be found here: + https://ww1.microchip.com/downloads/aemDocuments/documents/MSLD/ProductDocuments/DataSheets/MCP3561-2-4-Family-Data-Sheet-DS20006181C.pdf + Datasheet for MCP3561R, MCP3562R, MCP3564R can be found here: + https://ww1.microchip.com/downloads/aemDocuments/documents/APID/ProductDocuments/DataSheets/MCP3561_2_4R-Data-Sheet-DS200006391C.pdf + Datasheet for MCP3461, MCP3462, MCP3464 can be found here: + https://ww1.microchip.com/downloads/aemDocuments/documents/APID/ProductDocuments/DataSheets/MCP3461-2-4-Two-Four-Eight-Channel-153.6-ksps-Low-Noise-16-Bit-Delta-Sigma-ADC-Data-Sheet-20006180D.pdf + Datasheet for MCP3461R, MCP3462R, MCP3464R can be found here: + https://ww1.microchip.com/downloads/aemDocuments/documents/APID/ProductDocuments/DataSheets/MCP3461-2-4R-Family-Data-Sheet-DS20006404C.pdf + +properties: + compatible: + enum: + - microchip,mcp3461 + - microchip,mcp3462 + - microchip,mcp3464 + - microchip,mcp3461r + - microchip,mcp3462r + - microchip,mcp3464r + - microchip,mcp3561 + - microchip,mcp3562 + - microchip,mcp3564 + - microchip,mcp3561r + - microchip,mcp3562r + - microchip,mcp3564r + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 20000000 + + spi-cpha: true + + spi-cpol: true + + vdd-supply: true + + avdd-supply: true + + clocks: + description: + Phandle and clock identifier for external sampling clock. + If not specified, the internal crystal oscillator will be used. + maxItems: 1 + + interrupts: + description: IRQ line of the ADC + maxItems: 1 + + drive-open-drain: + description: + Whether to drive the IRQ signal as push-pull (default) or open-drain. Note + that the device requires this pin to become "high", otherwise it will stop + converting. + type: boolean + + vref-supply: + description: + Some devices have a specific reference voltage supplied on a different + pin to the other supplies. Needed to be able to establish channel scaling + unless there is also an internal reference available (e.g. mcp3564r). In + case of "r" devices (e. g. mcp3564r), if it does not exists the internal + reference will be used. + + microchip,hw-device-address: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 3 + description: + The address is set on a per-device basis by fuses in the factory, + configured on request. If not requested, the fuses are set for 0x1. + The device address is part of the device markings to avoid + potential confusion. This address is coded on two bits, so four possible + addresses are available when multiple devices are present on the same + SPI bus with only one Chip Select line for all devices. + Each device communication starts by a CS falling edge, followed by the + clocking of the device address (BITS[7:6] - top two bits of COMMAND BYTE + which is first one on the wire). + + "#io-channel-cells": + const: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + +patternProperties: + "^channel@([0-9]|([1-7][0-9]))$": + $ref: adc.yaml + type: object + unevaluatedProperties: false + description: Represents the external channels which are connected to the ADC. + + properties: + reg: + description: The channel number in single-ended and differential mode. + minimum: 0 + maximum: 79 + + required: + - reg + +dependencies: + spi-cpol: [ spi-cpha ] + spi-cpha: [ spi-cpol ] + +required: + - compatible + - reg + - microchip,hw-device-address + - spi-max-frequency + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + - # External vref, no internal reference + if: + properties: + compatible: + contains: + enum: + - microchip,mcp3461 + - microchip,mcp3462 + - microchip,mcp3464 + - microchip,mcp3561 + - microchip,mcp3562 + - microchip,mcp3564 + then: + required: + - vref-supply + +unevaluatedProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + compatible = "microchip,mcp3564r"; + reg = <0>; + vref-supply = <&vref_reg>; + spi-cpha; + spi-cpol; + spi-max-frequency = <10000000>; + microchip,hw-device-address = <1>; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + /* CH0 to AGND */ + reg = <0>; + label = "CH0"; + }; + + channel@1 { + /* CH1 to AGND */ + reg = <1>; + label = "CH1"; + }; + + /* diff-channels */ + channel@11 { + reg = <11>; + + /* CN0, CN1 */ + diff-channels = <0 1>; + label = "CH0_CH1"; + }; + + channel@22 { + reg = <0x22>; + + /* CN1, CN2 */ + diff-channels = <1 2>; + label = "CH1_CH3"; + }; + + channel@23 { + reg = <0x23>; + + /* CN1, CN3 */ + diff-channels = <1 3>; + label = "CH1_CH3"; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml index f7b3fde4115a..06951ec5f5da 100644 --- a/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml +++ b/Documentation/devicetree/bindings/iio/adc/microchip,mcp3911.yaml @@ -18,7 +18,13 @@ description: | properties: compatible: enum: + - microchip,mcp3910 - microchip,mcp3911 + - microchip,mcp3912 + - microchip,mcp3913 + - microchip,mcp3914 + - microchip,mcp3918 + - microchip,mcp3919 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml index e004659099c1..d605999ffe28 100644 --- a/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1015.yaml @@ -23,6 +23,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + "#address-cells": const: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/ti,twl6030-gpadc.yaml b/Documentation/devicetree/bindings/iio/adc/ti,twl6030-gpadc.yaml new file mode 100644 index 000000000000..e779a8986e0b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,twl6030-gpadc.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,twl6030-gpadc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: GPADC subsystem in the TWL6030 power module + +maintainers: + - Andreas Kemnade <andreas@kemnade.info> + +description: + The GPADC subsystem in the TWL603X consists of a 10-bit ADC + combined with a 15-input analog multiplexer in the TWL6030 resp. a + 19-input analog muliplexer in the TWL6032. + +properties: + compatible: + enum: + - ti,twl6030-gpadc + - ti,twl6032-gpadc + + interrupts: + maxItems: 1 + + "#io-channel-cells": + const: 1 + +required: + - compatible + - interrupts + - "#io-channel-cells" + +additionalProperties: false + +examples: + - | + gpadc { + compatible = "ti,twl6030-gpadc"; + interrupts = <3>; + #io-channel-cells = <1>; + }; +... diff --git a/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml b/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml index 2594fa192f93..2a04906531fb 100644 --- a/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml +++ b/Documentation/devicetree/bindings/iio/addac/adi,ad74115.yaml @@ -32,7 +32,8 @@ properties: spi-cpol: true - reset-gpios: true + reset-gpios: + maxItems: 1 interrupts: minItems: 1 diff --git a/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml b/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml index 9fda56fa49c3..2ee6080deac7 100644 --- a/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml +++ b/Documentation/devicetree/bindings/iio/amplifiers/adi,hmc425a.yaml @@ -4,20 +4,26 @@ $id: http://devicetree.org/schemas/iio/amplifiers/adi,hmc425a.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: HMC425A 6-bit Digital Step Attenuator +title: Analog Devices HMC425A and similar Digital Step Attenuators maintainers: - Michael Hennerich <michael.hennerich@analog.com> description: | - Digital Step Attenuator IIO device with gpio interface. + Digital Step Attenuator IIO devices with gpio interface. + Offer various frequency and attenuation ranges. HMC425A 0.5 dB LSB GaAs MMIC 6-BIT DIGITAL POSITIVE CONTROL ATTENUATOR, 2.2 - 8.0 GHz - https://www.analog.com/media/en/technical-documentation/data-sheets/hmc425A.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/hmc425A.pdf + + HMC540S 1 dB LSB Silicon MMIC 4-Bit Digital Positive Control Attenuator, 0.1 - 8 GHz + https://www.analog.com/media/en/technical-documentation/data-sheets/hmc540s.pdf + properties: compatible: enum: - adi,hmc425a + - adi,hmc540s vcc-supply: true diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml index 4e508bfcc9d8..5121685337b5 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5758.yaml @@ -78,7 +78,8 @@ properties: - const: -1000 - const: 22000 - reset-gpios: true + reset-gpios: + maxItems: 1 adi,dc-dc-ilim-microamp: enum: [150000, 200000, 250000, 300000, 350000, 400000] diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml index b9b5beac33b2..5b6cde86b5a5 100644 --- a/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml +++ b/Documentation/devicetree/bindings/iio/health/ti,afe4403.yaml @@ -23,7 +23,8 @@ properties: maxItems: 1 description: Connected to ADC_RDY pin. - reset-gpios: true + reset-gpios: + maxItems: 1 required: - compatible diff --git a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml index 2958c4ca75b4..167d10bd60af 100644 --- a/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml +++ b/Documentation/devicetree/bindings/iio/health/ti,afe4404.yaml @@ -23,7 +23,8 @@ properties: maxItems: 1 description: Connected to ADC_RDY pin. - reset-gpios: true + reset-gpios: + maxItems: 1 additionalProperties: false diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml index 1db6952ddca5..297b8a1a7ffb 100644 --- a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml +++ b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml @@ -48,6 +48,11 @@ properties: mount-matrix: true + invensense,level-shifter: + type: boolean + description: | + From ancient platform data struct: false: VLogic, true: VDD + i2c-gate: $ref: /schemas/i2c/i2c-controller.yaml unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml index ee8724ad33ab..28b667a9cb76 100644 --- a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml +++ b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml @@ -93,6 +93,9 @@ properties: wakeup-source: $ref: /schemas/types.yaml#/definitions/flag + mount-matrix: + description: an optional 3x3 mounting rotation matrix + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/pressure/rohm,bm1390.yaml b/Documentation/devicetree/bindings/iio/pressure/rohm,bm1390.yaml new file mode 100644 index 000000000000..7c4ca6322bf8 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/pressure/rohm,bm1390.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/pressure/rohm,bm1390.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BM1390 pressure sensor + +maintainers: + - Matti Vaittinen <mazziesaccount@gmail.com> + +description: + BM1390GLV-Z is a pressure sensor which performs internal temperature + compensation for the MEMS. Pressure range is from 300 hPa to 1300 hPa + and sample averaging and IIR filtering is built in. Temperature + measurement is also supported. + +properties: + compatible: + const: rohm,bm1390glv-z + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + vdd-supply: true + +required: + - compatible + - reg + - vdd-supply + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + pressure-sensor@5d { + compatible = "rohm,bm1390glv-z"; + reg = <0x5d>; + + interrupt-parent = <&gpio1>; + interrupts = <29 IRQ_TYPE_LEVEL_LOW>; + + vdd-supply = <&vdd>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/resolver/adi,ad2s1210.yaml b/Documentation/devicetree/bindings/iio/resolver/adi,ad2s1210.yaml new file mode 100644 index 000000000000..8980b3cd8337 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/resolver/adi,ad2s1210.yaml @@ -0,0 +1,177 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/resolver/adi,ad2s1210.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices AD2S1210 Resolver-to-Digital Converter + +maintainers: + - Michael Hennerich <michael.hennerich@analog.com> + +description: | + The AD2S1210 is a complete 10-bit to 16-bit resolution tracking + resolver-to-digital converter, integrating an on-board programmable + sinusoidal oscillator that provides sine wave excitation for + resolvers. + + The AD2S1210 allows the user to read the angular position or the + angular velocity data directly from the parallel outputs or through + the serial interface. + + The mode of operation of the communication channel (parallel or serial) is + selected by the A0 and A1 input pins. In normal mode, data is latched by + toggling the SAMPLE line and can then be read directly. In configuration mode, + data is read or written using a register access scheme (address byte with + read/write flag and data byte). + + A1 A0 Result + 0 0 Normal mode - position output + 0 1 Normal mode - velocity output + 1 0 Reserved + 1 1 Configuration mode + + In normal mode, the resolution of the digital output is selected using + the RES0 and RES1 input pins. In configuration mode, the resolution is + selected by setting the RES0 and RES1 bits in the control register. + + RES1 RES0 Resolution (Bits) + 0 0 10 + 0 1 12 + 1 0 14 + 1 1 16 + + Note on SPI connections: The CS line on the AD2S1210 should hard-wired to + logic low and the WR/FSYNC line on the AD2S1210 should be connected to the + SPI CSn output of the SPI controller. + + Datasheet: + https://www.analog.com/media/en/technical-documentation/data-sheets/ad2s1210.pdf + +properties: + compatible: + const: adi,ad2s1210 + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 25000000 + + spi-cpha: true + + avdd-supply: + description: + A 4.75 to 5.25 V regulator that powers the Analog Supply Voltage (AVDD) + pin. + + dvdd-supply: + description: + A 4.75 to 5.25 V regulator that powers the Digital Supply Voltage (DVDD) + pin. + + vdrive-supply: + description: + A 2.3 to 5.25 V regulator that powers the Logic Power Supply Input + (VDrive) pin. + + clocks: + maxItems: 1 + description: External oscillator clock (CLKIN). + + reset-gpios: + description: + GPIO connected to the /RESET pin. As the line needs to be low for the + reset to be active, it should be configured as GPIO_ACTIVE_LOW. + maxItems: 1 + + sample-gpios: + description: + GPIO connected to the /SAMPLE pin. As the line needs to be low to trigger + a sample, it should be configured as GPIO_ACTIVE_LOW. + maxItems: 1 + + mode-gpios: + description: + GPIO lines connected to the A0 and A1 pins. These pins select the data + transfer mode. + minItems: 2 + maxItems: 2 + + resolution-gpios: + description: + GPIO lines connected to the RES0 and RES1 pins. These pins select the + resolution of the digital output. If omitted, it is assumed that the + RES0 and RES1 pins are hard-wired to match the assigned-resolution-bits + property. + minItems: 2 + maxItems: 2 + + fault-gpios: + description: + GPIO lines connected to the LOT and DOS pins. These pins combined indicate + the type of fault present, if any. As these pins a pulled low to indicate + a fault condition, they should be configured as GPIO_ACTIVE_LOW. + minItems: 2 + maxItems: 2 + + adi,fixed-mode: + description: + This is used to indicate the selected mode if A0 and A1 are hard-wired + instead of connected to GPIOS (i.e. mode-gpios is omitted). + $ref: /schemas/types.yaml#/definitions/string + enum: [config, velocity, position] + + assigned-resolution-bits: + description: + Resolution of the digital output required by the application. This + determines the precision of the angle and/or the maximum speed that can + be measured. If resolution-gpios is omitted, it is assumed that RES0 and + RES1 are hard-wired to match this value. + enum: [10, 12, 14, 16] + +required: + - compatible + - reg + - spi-cpha + - avdd-supply + - dvdd-supply + - vdrive-supply + - clocks + - sample-gpios + - assigned-resolution-bits + +oneOf: + - required: + - mode-gpios + - required: + - adi,fixed-mode + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + spi { + #address-cells = <1>; + #size-cells = <0>; + + resolver@0 { + compatible = "adi,ad2s1210"; + reg = <0>; + spi-max-frequency = <20000000>; + spi-cpha; + avdd-supply = <&avdd_regulator>; + dvdd-supply = <&dvdd_regulator>; + vdrive-supply = <&vdrive_regulator>; + clocks = <&ext_osc>; + sample-gpios = <&gpio0 90 GPIO_ACTIVE_LOW>; + mode-gpios = <&gpio0 86 0>, <&gpio0 87 0>; + resolution-gpios = <&gpio0 88 0>, <&gpio0 89 0>; + assigned-resolution-bits = <16>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml b/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml new file mode 100644 index 000000000000..88764adcd696 --- /dev/null +++ b/Documentation/devicetree/bindings/input/qcom,pm8921-keypad.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/qcom,pm8921-keypad.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm PM8921 PMIC KeyPad + +maintainers: + - Dmitry Baryshkov <dmitry.baryshkov@linaro.org> + +allOf: + - $ref: input.yaml# + - $ref: matrix-keymap.yaml# + +properties: + compatible: + enum: + - qcom,pm8058-keypad + - qcom,pm8921-keypad + + reg: + maxItems: 1 + + interrupts: + items: + - description: key sense + - description: key stuck + + wakeup-source: + type: boolean + description: use any event on keypad as wakeup event + + linux,keypad-wakeup: + type: boolean + deprecated: true + description: legacy version of the wakeup-source property + + debounce: + description: + Time in microseconds that key must be pressed or + released for state change interrupt to trigger. + $ref: /schemas/types.yaml#/definitions/uint32 + + scan-delay: + $ref: /schemas/types.yaml#/definitions/uint32 + description: time in microseconds to pause between successive scans of the + matrix array + + row-hold: + $ref: /schemas/types.yaml#/definitions/uint32 + description: time in nanoseconds to pause between scans of each row in the + matrix array. + +required: + - compatible + - reg + - interrupts + - linux,keymap + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/input/input.h> + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + #address-cells = <1>; + #size-cells = <0>; + + keypad@148 { + compatible = "qcom,pm8921-keypad"; + reg = <0x148>; + interrupt-parent = <&pmicintc>; + interrupts = <74 IRQ_TYPE_EDGE_RISING>, <75 IRQ_TYPE_EDGE_RISING>; + linux,keymap = < + MATRIX_KEY(0, 0, KEY_VOLUMEUP) + MATRIX_KEY(0, 1, KEY_VOLUMEDOWN) + MATRIX_KEY(0, 2, KEY_CAMERA_FOCUS) + MATRIX_KEY(0, 3, KEY_CAMERA) + >; + keypad,num-rows = <1>; + keypad,num-columns = <5>; + debounce = <15>; + scan-delay = <32>; + row-hold = <91500>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt deleted file mode 100644 index 4a9dc6ba96b1..000000000000 --- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt +++ /dev/null @@ -1,90 +0,0 @@ -Qualcomm PM8xxx PMIC Keypad - -PROPERTIES - -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,pm8058-keypad" - "qcom,pm8921-keypad" - -- reg: - Usage: required - Value type: <prop-encoded-array> - Definition: address of keypad control register - -- interrupts: - Usage: required - Value type: <prop-encoded-array> - Definition: the first interrupt specifies the key sense interrupt - and the second interrupt specifies the key stuck interrupt. - The format of the specifier is defined by the binding - document describing the node's interrupt parent. - -- linux,keymap: - Usage: required - Value type: <prop-encoded-array> - Definition: the linux keymap. More information can be found in - input/matrix-keymap.txt. - -- linux,keypad-no-autorepeat: - Usage: optional - Value type: <bool> - Definition: don't enable autorepeat feature. - -- wakeup-source: - Usage: optional - Value type: <bool> - Definition: use any event on keypad as wakeup event. - (Legacy property supported: "linux,keypad-wakeup") - -- keypad,num-rows: - Usage: required - Value type: <u32> - Definition: number of rows in the keymap. More information can be found - in input/matrix-keymap.txt. - -- keypad,num-columns: - Usage: required - Value type: <u32> - Definition: number of columns in the keymap. More information can be - found in input/matrix-keymap.txt. - -- debounce: - Usage: optional - Value type: <u32> - Definition: time in microseconds that key must be pressed or release - for key sense interrupt to trigger. - -- scan-delay: - Usage: optional - Value type: <u32> - Definition: time in microseconds to pause between successive scans - of the matrix array. - -- row-hold: - Usage: optional - Value type: <u32> - Definition: time in nanoseconds to pause between scans of each row in - the matrix array. - -EXAMPLE - - keypad@148 { - compatible = "qcom,pm8921-keypad"; - reg = <0x148>; - interrupt-parent = <&pmicintc>; - interrupts = <74 1>, <75 1>; - linux,keymap = < - MATRIX_KEY(0, 0, KEY_VOLUMEUP) - MATRIX_KEY(0, 1, KEY_VOLUMEDOWN) - MATRIX_KEY(0, 2, KEY_CAMERA_FOCUS) - MATRIX_KEY(0, 3, KEY_CAMERA) - >; - keypad,num-rows = <1>; - keypad,num-columns = <5>; - debounce = <15>; - scan-delay = <32>; - row-hold = <91500>; - }; diff --git a/Documentation/devicetree/bindings/input/syna,rmi4.yaml b/Documentation/devicetree/bindings/input/syna,rmi4.yaml index 4d4e1a8e36be..b522c8d3ce0d 100644 --- a/Documentation/devicetree/bindings/input/syna,rmi4.yaml +++ b/Documentation/devicetree/bindings/input/syna,rmi4.yaml @@ -164,6 +164,8 @@ patternProperties: "^rmi4-f[0-9a-f]+@[0-9a-f]+$": type: object + additionalProperties: true + description: Other functions, not documented yet. diff --git a/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt b/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt index f5021214edec..6c201a2ba8ac 100644 --- a/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt +++ b/Documentation/devicetree/bindings/input/twl4030-pwrbutton.txt @@ -1,7 +1,7 @@ Texas Instruments TWL family (twl4030) pwrbutton module This module is part of the TWL4030. For more details about the whole -chip see Documentation/devicetree/bindings/mfd/twl-family.txt. +chip see Documentation/devicetree/bindings/mfd/ti,twl.yaml. This module provides a simple power button event via an Interrupt. diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8939.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8939.yaml new file mode 100644 index 000000000000..fd15ab5014fb --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8939.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,msm8939.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8939 Network-On-Chip interconnect + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +description: | + The Qualcomm MSM8939 interconnect providers support adjusting the + bandwidth requirements between the various NoC fabrics. + +allOf: + - $ref: qcom,rpm-common.yaml# + +properties: + compatible: + enum: + - qcom,msm8939-bimc + - qcom,msm8939-pcnoc + - qcom,msm8939-snoc + + reg: + maxItems: 1 + +patternProperties: + '^interconnect-[a-z0-9\-]+$': + type: object + $ref: qcom,rpm-common.yaml# + description: + The interconnect providers do not have a separate QoS register space, + but share parent's space. + + allOf: + - $ref: qcom,rpm-common.yaml# + + properties: + compatible: + const: qcom,msm8939-snoc-mm + + required: + - compatible + + unevaluatedProperties: false + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmcc.h> + + snoc: interconnect@580000 { + compatible = "qcom,msm8939-snoc"; + reg = <0x00580000 0x14000>; + #interconnect-cells = <1>; + }; + + bimc: interconnect@400000 { + compatible = "qcom,msm8939-bimc"; + reg = <0x00400000 0x62000>; + #interconnect-cells = <1>; + + snoc_mm: interconnect-snoc { + compatible = "qcom,msm8939-snoc-mm"; + #interconnect-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8996.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8996.yaml new file mode 100644 index 000000000000..e3f964aaad1b --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8996.yaml @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,msm8996.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm MSM8996 Network-On-Chip interconnect + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +description: | + The Qualcomm MSM8996 interconnect providers support adjusting the + bandwidth requirements between the various NoC fabrics. + +properties: + compatible: + enum: + - qcom,msm8996-a0noc + - qcom,msm8996-a1noc + - qcom,msm8996-a2noc + - qcom,msm8996-bimc + - qcom,msm8996-cnoc + - qcom,msm8996-mnoc + - qcom,msm8996-pnoc + - qcom,msm8996-snoc + + reg: + maxItems: 1 + + clock-names: + minItems: 1 + maxItems: 3 + + clocks: + minItems: 1 + maxItems: 3 + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +allOf: + - $ref: qcom,rpm-common.yaml# + - if: + properties: + compatible: + const: qcom,msm8996-a0noc + + then: + properties: + clocks: + items: + - description: Aggregate0 System NoC AXI Clock. + - description: Aggregate0 Config NoC AHB Clock. + - description: Aggregate0 NoC MPU Clock. + + clock-names: + items: + - const: aggre0_snoc_axi + - const: aggre0_cnoc_ahb + - const: aggre0_noc_mpu_cfg + + required: + - power-domains + + - if: + properties: + compatible: + const: qcom,msm8996-mnoc + + then: + properties: + clocks: + items: + - description: CPU-NoC High-performance Bus Clock. + + clock-names: + const: iface + + - if: + properties: + compatible: + const: qcom,msm8996-a2noc + + then: + properties: + clocks: + items: + - description: Aggregate2 NoC UFS AXI Clock + - description: UFS AXI Clock + + clock-names: + items: + - const: aggre2_ufs_axi + - const: ufs_axi + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-msm8996.h> + #include <dt-bindings/clock/qcom,mmcc-msm8996.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + + bimc: interconnect@408000 { + compatible = "qcom,msm8996-bimc"; + reg = <0x00408000 0x5a000>; + #interconnect-cells = <1>; + }; + + a0noc: interconnect@543000 { + compatible = "qcom,msm8996-a0noc"; + reg = <0x00543000 0x6000>; + #interconnect-cells = <1>; + clocks = <&gcc GCC_AGGRE0_SNOC_AXI_CLK>, + <&gcc GCC_AGGRE0_CNOC_AHB_CLK>, + <&gcc GCC_AGGRE0_NOC_MPU_CFG_AHB_CLK>; + clock-names = "aggre0_snoc_axi", + "aggre0_cnoc_ahb", + "aggre0_noc_mpu_cfg"; + power-domains = <&gcc AGGRE0_NOC_GDSC>; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml b/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml index f65a2fe846de..b6c15314c5c5 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,qcm2290.yaml @@ -13,6 +13,9 @@ description: | The Qualcomm QCM2290 interconnect providers support adjusting the bandwidth requirements between the various NoC fabrics. +allOf: + - $ref: qcom,rpm-common.yaml# + properties: reg: maxItems: 1 @@ -23,19 +26,6 @@ properties: - qcom,qcm2290-cnoc - qcom,qcm2290-snoc - '#interconnect-cells': - const: 1 - - clock-names: - items: - - const: bus - - const: bus_a - - clocks: - items: - - description: Bus Clock - - description: Bus A Clock - # Child node's properties patternProperties: '^interconnect-[a-z0-9]+$': @@ -44,6 +34,9 @@ patternProperties: The interconnect providers do not have a separate QoS register space, but share parent's space. + allOf: + - $ref: qcom,rpm-common.yaml# + properties: compatible: enum: @@ -51,35 +44,16 @@ patternProperties: - qcom,qcm2290-mmrt-virt - qcom,qcm2290-mmnrt-virt - '#interconnect-cells': - const: 1 - - clock-names: - items: - - const: bus - - const: bus_a - - clocks: - items: - - description: Bus Clock - - description: Bus A Clock - required: - compatible - - '#interconnect-cells' - - clock-names - - clocks - additionalProperties: false + unevaluatedProperties: false required: - compatible - reg - - '#interconnect-cells' - - clock-names - - clocks -additionalProperties: false +unevaluatedProperties: false examples: - | @@ -89,32 +63,20 @@ examples: compatible = "qcom,qcm2290-snoc"; reg = <0x01880000 0x60200>; #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_SNOC_CLK>, - <&rpmcc RPM_SMD_SNOC_A_CLK>; qup_virt: interconnect-qup { compatible = "qcom,qcm2290-qup-virt"; #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_QUP_CLK>, - <&rpmcc RPM_SMD_QUP_A_CLK>; }; mmnrt_virt: interconnect-mmnrt { compatible = "qcom,qcm2290-mmnrt-virt"; #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_MMNRT_CLK>, - <&rpmcc RPM_SMD_MMNRT_A_CLK>; }; mmrt_virt: interconnect-mmrt { compatible = "qcom,qcm2290-mmrt-virt"; #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_MMRT_CLK>, - <&rpmcc RPM_SMD_MMRT_A_CLK>; }; }; @@ -122,16 +84,10 @@ examples: compatible = "qcom,qcm2290-cnoc"; reg = <0x01900000 0x8200>; #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_CNOC_CLK>, - <&rpmcc RPM_SMD_CNOC_A_CLK>; }; bimc: interconnect@4480000 { compatible = "qcom,qcm2290-bimc"; reg = <0x04480000 0x80000>; #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_BIMC_CLK>, - <&rpmcc RPM_SMD_BIMC_A_CLK>; }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpm-common.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpm-common.yaml new file mode 100644 index 000000000000..1ea52b091609 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpm-common.yaml @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,rpm-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +description: + RPM interconnect providers support for managing system bandwidth requirements + through manual requests based on either predefined values or as indicated by + the bus monitor hardware. Each provider node represents a NoC bus master, + driven by a dedicated clock source. + +properties: + '#interconnect-cells': + oneOf: + - const: 2 + - const: 1 + deprecated: true + +required: + - '#interconnect-cells' + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml index 4f95d512012a..08c1c6b9d7cf 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml @@ -7,13 +7,16 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm RPM Network-On-Chip Interconnect maintainers: - - Georgi Djakov <georgi.djakov@linaro.org> + - Georgi Djakov <djakov@kernel.org> description: | RPM interconnect providers support system bandwidth requirements through RPM processor. The provider is able to communicate with the RPM through the RPM shared memory device. +allOf: + - $ref: qcom,rpm-common.yaml# + properties: reg: maxItems: 1 @@ -23,259 +26,22 @@ properties: - qcom,msm8916-bimc - qcom,msm8916-pcnoc - qcom,msm8916-snoc - - qcom,msm8939-bimc - - qcom,msm8939-pcnoc - - qcom,msm8939-snoc - - qcom,msm8996-a0noc - - qcom,msm8996-a1noc - - qcom,msm8996-a2noc - - qcom,msm8996-bimc - - qcom,msm8996-cnoc - - qcom,msm8996-mnoc - - qcom,msm8996-pnoc - - qcom,msm8996-snoc - qcom,qcs404-bimc - qcom,qcs404-pcnoc - qcom,qcs404-snoc - - qcom,sdm660-a2noc - - qcom,sdm660-bimc - - qcom,sdm660-cnoc - - qcom,sdm660-gnoc - - qcom,sdm660-mnoc - - qcom,sdm660-snoc - - '#interconnect-cells': - description: | - Value: <1> is one cell in an interconnect specifier for the - interconnect node id, <2> requires the interconnect node id and an - extra path tag. - enum: [ 1, 2 ] - - clocks: - minItems: 2 - maxItems: 7 - - clock-names: - minItems: 2 - maxItems: 7 - - power-domains: - maxItems: 1 - -# Child node's properties -patternProperties: - '^interconnect-[a-z0-9]+$': - type: object - additionalProperties: false - description: - snoc-mm is a child of snoc, sharing snoc's register address space. - - properties: - compatible: - enum: - - qcom,msm8939-snoc-mm - - '#interconnect-cells': - const: 1 - - clock-names: - items: - - const: bus - - const: bus_a - - clocks: - items: - - description: Bus Clock - - description: Bus A Clock - - required: - - compatible - - '#interconnect-cells' - - clock-names - - clocks required: - compatible - reg - - '#interconnect-cells' - - clock-names - - clocks - -additionalProperties: false - -allOf: - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8916-bimc - - qcom,msm8916-pcnoc - - qcom,msm8916-snoc - - qcom,msm8939-bimc - - qcom,msm8939-pcnoc - - qcom,msm8939-snoc - - qcom,msm8996-a1noc - - qcom,msm8996-bimc - - qcom,msm8996-cnoc - - qcom,msm8996-pnoc - - qcom,msm8996-snoc - - qcom,qcs404-bimc - - qcom,qcs404-pcnoc - - qcom,qcs404-snoc - - qcom,sdm660-bimc - - qcom,sdm660-cnoc - - qcom,sdm660-gnoc - - qcom,sdm660-snoc - - then: - properties: - clock-names: - items: - - const: bus - - const: bus_a - - clocks: - items: - - description: Bus Clock - - description: Bus A Clock - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8996-mnoc - - qcom,sdm660-mnoc - - then: - properties: - clock-names: - items: - - const: bus - - const: bus_a - - const: iface - - clocks: - items: - - description: Bus Clock. - - description: Bus A Clock. - - description: CPU-NoC High-performance Bus Clock. - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8996-a0noc - - then: - properties: - clock-names: - items: - - const: aggre0_snoc_axi - - const: aggre0_cnoc_ahb - - const: aggre0_noc_mpu_cfg - - clocks: - items: - - description: Aggregate0 System NoC AXI Clock. - - description: Aggregate0 Config NoC AHB Clock. - - description: Aggregate0 NoC MPU Clock. - - required: - - power-domains - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8996-a2noc - - then: - properties: - clock-names: - items: - - const: bus - - const: bus_a - - const: aggre2_ufs_axi - - const: ufs_axi - - clocks: - items: - - description: Bus Clock - - description: Bus A Clock - - description: Aggregate2 NoC UFS AXI Clock - - description: UFS AXI Clock - - - if: - properties: - compatible: - contains: - enum: - - qcom,sdm660-a2noc - - then: - properties: - clock-names: - items: - - const: bus - - const: bus_a - - const: ipa - - const: ufs_axi - - const: aggre2_ufs_axi - - const: aggre2_usb3_axi - - const: cfg_noc_usb2_axi - - clocks: - items: - - description: Bus Clock. - - description: Bus A Clock. - - description: IPA Clock. - - description: UFS AXI Clock. - - description: Aggregate2 UFS AXI Clock. - - description: Aggregate2 USB3 AXI Clock. - - description: Config NoC USB2 AXI Clock. - - - if: - not: - properties: - compatible: - contains: - enum: - - qcom,msm8939-snoc - then: - patternProperties: - '^interconnect-[a-z0-9]+$': false +unevaluatedProperties: false examples: - | #include <dt-bindings/clock/qcom,rpmcc.h> bimc: interconnect@400000 { - compatible = "qcom,msm8916-bimc"; - reg = <0x00400000 0x62000>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_BIMC_CLK>, - <&rpmcc RPM_SMD_BIMC_A_CLK>; - }; - - pcnoc: interconnect@500000 { - compatible = "qcom,msm8916-pcnoc"; - reg = <0x00500000 0x11000>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_PCNOC_CLK>, - <&rpmcc RPM_SMD_PCNOC_A_CLK>; - }; - - snoc: interconnect@580000 { - compatible = "qcom,msm8916-snoc"; - reg = <0x00580000 0x14000>; - #interconnect-cells = <1>; - clock-names = "bus", "bus_a"; - clocks = <&rpmcc RPM_SMD_SNOC_CLK>, - <&rpmcc RPM_SMD_SNOC_A_CLK>; + compatible = "qcom,msm8916-bimc"; + reg = <0x00400000 0x62000>; + #interconnect-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml index a46497af1fd8..74ab080249ff 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpmh.yaml @@ -113,6 +113,7 @@ allOf: properties: compatible: enum: + - qcom,sdx65-mc-virt - qcom,sm8250-qup-virt then: required: diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml new file mode 100644 index 000000000000..8f6bc6399626 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sdm660.yaml @@ -0,0 +1,108 @@ +# 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: + - Konrad Dybcio <konradybcio@kernel.org> + +description: | + The Qualcomm SDM660 interconnect providers support adjusting the + bandwidth requirements between the various NoC fabrics. + +properties: + compatible: + enum: + - qcom,sdm660-a2noc + - qcom,sdm660-bimc + - qcom,sdm660-cnoc + - qcom,sdm660-gnoc + - qcom,sdm660-mnoc + - qcom,sdm660-snoc + + reg: + maxItems: 1 + + clock-names: + minItems: 1 + maxItems: 5 + + clocks: + minItems: 1 + maxItems: 5 + +required: + - compatible + - reg + +unevaluatedProperties: false + +allOf: + - $ref: qcom,rpm-common.yaml# + - if: + properties: + compatible: + const: qcom,sdm660-mnoc + + then: + properties: + clocks: + items: + - description: CPU-NoC High-performance Bus Clock. + + clock-names: + const: iface + + - if: + properties: + compatible: + const: qcom,sdm660-a2noc + + then: + properties: + clocks: + items: + - description: IPA Clock. + - description: UFS AXI Clock. + - description: Aggregate2 UFS AXI Clock. + - description: Aggregate2 USB3 AXI Clock. + - description: Config NoC USB2 AXI Clock. + + clock-names: + items: + - const: ipa + - const: ufs_axi + - const: aggre2_ufs_axi + - const: aggre2_usb3_axi + - const: cfg_noc_usb2_axi + +examples: + - | + #include <dt-bindings/clock/qcom,gcc-sdm660.h> + #include <dt-bindings/clock/qcom,mmcc-sdm660.h> + #include <dt-bindings/clock/qcom,rpmcc.h> + + bimc: interconnect@1008000 { + compatible = "qcom,sdm660-bimc"; + reg = <0x01008000 0x78000>; + #interconnect-cells = <1>; + }; + + a2noc: interconnect@1704000 { + compatible = "qcom,sdm660-a2noc"; + reg = <0x01704000 0xc100>; + #interconnect-cells = <1>; + clocks = <&rpmcc RPM_SMD_IPA_CLK>, + <&gcc GCC_UFS_AXI_CLK>, + <&gcc GCC_AGGRE2_UFS_AXI_CLK>, + <&gcc GCC_AGGRE2_USB3_AXI_CLK>, + <&gcc GCC_CFG_NOC_USB2_AXI_CLK>; + clock-names = "ipa", + "ufs_axi", + "aggre2_ufs_axi", + "aggre2_usb3_axi", + "cfg_noc_usb2_axi"; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdx75-rpmh.yaml b/Documentation/devicetree/bindings/interconnect/qcom,sdx75-rpmh.yaml new file mode 100644 index 000000000000..71cf7e252bfc --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sdx75-rpmh.yaml @@ -0,0 +1,92 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interconnect/qcom,sdx75-rpmh.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm RPMh Network-On-Chip Interconnect on SDX75 + +maintainers: + - Rohit Agarwal <quic_rohiagar@quicinc.com> + +description: + RPMh interconnect providers support system bandwidth requirements through + RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is + able to communicate with the BCM through the Resource State Coordinator (RSC) + associated with each execution environment. Provider nodes must point to at + least one RPMh device child node pertaining to their RSC and each provider + can map to multiple RPMh resources. + +properties: + compatible: + enum: + - qcom,sdx75-clk-virt + - qcom,sdx75-dc-noc + - qcom,sdx75-gem-noc + - qcom,sdx75-mc-virt + - qcom,sdx75-pcie-anoc + - qcom,sdx75-system-noc + + '#interconnect-cells': true + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + +allOf: + - $ref: qcom,rpmh-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - qcom,sdx75-clk-virt + - qcom,sdx75-mc-virt + then: + properties: + reg: false + else: + required: + - reg + + - if: + properties: + compatible: + contains: + enum: + - qcom,sdx75-clk-virt + then: + properties: + clocks: + items: + - description: RPMH CC QPIC Clock + required: + - clocks + else: + properties: + clocks: false + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmh.h> + + clk_virt: interconnect-0 { + compatible = "qcom,sdx75-clk-virt"; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + clocks = <&rpmhcc RPMH_QPIC_CLK>; + }; + + system_noc: interconnect@1640000 { + compatible = "qcom,sdx75-system-noc"; + reg = <0x1640000 0x4b400>; + #interconnect-cells = <2>; + qcom,bcm-voters = <&apps_bcm_voter>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml index 4847b04be1a1..86d61896f591 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/qcom,pdc.yaml @@ -35,6 +35,7 @@ properties: - qcom,sdm845-pdc - qcom,sdx55-pdc - qcom,sdx65-pdc + - qcom,sm4450-pdc - qcom,sm6350-pdc - qcom,sm8150-pdc - qcom,sm8250-pdc diff --git a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml index dc1f28e55266..0c07e8dda445 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml +++ b/Documentation/devicetree/bindings/interrupt-controller/sifive,plic-1.0.0.yaml @@ -65,6 +65,8 @@ properties: - items: - enum: - allwinner,sun20i-d1-plic + - sophgo,cv1800b-plic + - sophgo,sg2042-plic - thead,th1520-plic - const: thead,c900-plic - items: diff --git a/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml new file mode 100644 index 000000000000..065f2544b63b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/thead,c900-aclint-mswi.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/thead,c900-aclint-mswi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sophgo sg2042 CLINT Machine-level Software Interrupt Device + +maintainers: + - Inochi Amaoto <inochiama@outlook.com> + +properties: + compatible: + items: + - enum: + - sophgo,sg2042-aclint-mswi + - const: thead,c900-aclint-mswi + + reg: + maxItems: 1 + + interrupts-extended: + minItems: 1 + maxItems: 4095 + +additionalProperties: false + +required: + - compatible + - reg + - interrupts-extended + +examples: + - | + interrupt-controller@94000000 { + compatible = "sophgo,sg2042-aclint-mswi", "thead,c900-aclint-mswi"; + interrupts-extended = <&cpu1intc 3>, + <&cpu2intc 3>, + <&cpu3intc 3>, + <&cpu4intc 3>; + reg = <0x94000000 0x00010000>; + }; +... diff --git a/Documentation/devicetree/bindings/leds/backlight/common.yaml b/Documentation/devicetree/bindings/leds/backlight/common.yaml index 3b60afbab68b..e0983e44934c 100644 --- a/Documentation/devicetree/bindings/leds/backlight/common.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/common.yaml @@ -33,4 +33,21 @@ properties: due to restrictions in a specific system, such as mounting conditions. $ref: /schemas/types.yaml#/definitions/uint32 + brightness-levels: + description: + Array of distinct brightness levels. The levels must be in the range + accepted by the underlying LED device. Typically these are in the range + from 0 to 255, but any range starting at 0 will do, as long as they are + accepted by the LED. + The 0 value means a 0% of brightness (darkest/off), while the last value + in the array represents a full 100% brightness (brightest). + If this array is not provided, the driver default mapping is used. + $ref: /schemas/types.yaml#/definitions/uint32-array + + default-brightness-level: + description: + The default brightness level (index into the array defined by the + "brightness-levels" property). + $ref: /schemas/types.yaml#/definitions/uint32 + additionalProperties: true diff --git a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml index d7b78198abc2..f5554da6bc6c 100644 --- a/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/led-backlight.yaml @@ -16,6 +16,9 @@ description: can also be used to describe a backlight device controlled by the output of a LED driver. +allOf: + - $ref: common.yaml# + properties: compatible: const: led-backlight @@ -26,25 +29,11 @@ properties: items: maxItems: 1 - brightness-levels: - description: - Array of distinct brightness levels. The levels must be in the range - accepted by the underlying LED devices. This is used to translate a - backlight brightness level into a LED brightness level. If it is not - provided, the identity mapping is used. - $ref: /schemas/types.yaml#/definitions/uint32-array - - default-brightness-level: - description: - The default brightness level (index into the array defined by the - "brightness-levels" property). - $ref: /schemas/types.yaml#/definitions/uint32 - required: - compatible - leds -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt deleted file mode 100644 index b4cffdaa4137..000000000000 --- a/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt +++ /dev/null @@ -1,10 +0,0 @@ -88pm860x-backlight bindings - -Optional properties: - - maxim,max8925-dual-string: whether support dual string - -Example: - - backlights { - maxim,max8925-dual-string = <0>; - }; diff --git a/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml b/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml new file mode 100644 index 000000000000..4191e33626f5 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/mps,mp3309c.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/mps,mp3309c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MPS MP3309C backlight + +maintainers: + - Flavio Suligoi <f.suligoi@asem.it> + +description: | + The Monolithic Power (MPS) MP3309C is a WLED step-up converter, featuring a + programmable switching frequency to optimize efficiency. + It supports two different dimming modes: + + - analog mode, via I2C commands (default) + - PWM controlled mode. + + The datasheet is available at: + https://www.monolithicpower.com/en/mp3309c.html + +allOf: + - $ref: common.yaml# + +properties: + compatible: + const: mps,mp3309c + + reg: + maxItems: 1 + + pwms: + description: if present, the backlight is controlled in PWM mode. + maxItems: 1 + + enable-gpios: + description: GPIO used to enable the backlight in "analog-i2c" dimming mode. + maxItems: 1 + + mps,overvoltage-protection-microvolt: + description: Overvoltage protection (13.5V, 24V or 35.5V). + enum: [ 13500000, 24000000, 35500000 ] + default: 35500000 + + mps,no-sync-mode: + description: disable synchronous rectification mode + type: boolean + +required: + - compatible + - reg + - max-brightness + - default-brightness + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + /* Backlight with PWM control */ + backlight_pwm: backlight@17 { + compatible = "mps,mp3309c"; + reg = <0x17>; + pwms = <&pwm1 0 3333333 0>; /* 300 Hz --> (1/f) * 1*10^9 */ + max-brightness = <100>; + default-brightness = <80>; + mps,overvoltage-protection-microvolt = <24000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml index 535690288990..b71f6454a4ac 100644 --- a/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.yaml @@ -11,6 +11,9 @@ maintainers: - Daniel Thompson <daniel.thompson@linaro.org> - Jingoo Han <jingoohan1@gmail.com> +allOf: + - $ref: common.yaml# + properties: compatible: const: pwm-backlight @@ -39,21 +42,6 @@ properties: Delay in ms between disabling the backlight using GPIO and setting PWM value to 0. - brightness-levels: - description: - Array of distinct brightness levels. Typically these are in the range - from 0 to 255, but any range starting at 0 will do. The actual brightness - level (PWM duty cycle) will be interpolated from these values. 0 means a - 0% duty cycle (darkest/off), while the last value in the array represents - a 100% duty cycle (brightest). - $ref: /schemas/types.yaml#/definitions/uint32-array - - default-brightness-level: - description: - The default brightness level (index into the array defined by the - "brightness-levels" property). - $ref: /schemas/types.yaml#/definitions/uint32 - num-interpolated-steps: description: Number of interpolated steps between each value of brightness-levels @@ -69,7 +57,7 @@ required: - compatible - pwms -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml index 5fb7007f3618..c8d0ba5f2327 100644 --- a/Documentation/devicetree/bindings/leds/common.yaml +++ b/Documentation/devicetree/bindings/leds/common.yaml @@ -43,7 +43,7 @@ properties: LED_COLOR_ID available, add a new one. $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 - maximum: 9 + maximum: 14 function-enumerator: description: @@ -191,6 +191,8 @@ properties: each of them having its own LED assigned (assuming they are not hardwired). In such cases this property should contain phandle(s) of related source device(s). + Another example is a GPIO line that will be monitored and mirror the + state of the line (with or without inversion flags) to the LED. In many cases LED can be related to more than one device (e.g. one USB LED vs. multiple USB ports). Each source should be represented by a node in the device tree and be referenced by a phandle and a set of phandle diff --git a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml index f2a6fa140f38..7526e3149f72 100644 --- a/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml +++ b/Documentation/devicetree/bindings/leds/irled/pwm-ir-tx.yaml @@ -15,7 +15,10 @@ description: properties: compatible: - const: pwm-ir-tx + oneOf: + - const: pwm-ir-tx + - const: nokia,n900-ir + deprecated: true pwms: maxItems: 1 diff --git a/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml b/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml new file mode 100644 index 000000000000..832c030a5acf --- /dev/null +++ b/Documentation/devicetree/bindings/leds/kinetic,ktd202x.yaml @@ -0,0 +1,171 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/kinetic,ktd202x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Kinetic KTD2026/7 RGB/White LED Driver + +maintainers: + - André Apitzsch <git@apitzsch.eu> + +description: | + The KTD2026/7 is a RGB/White LED driver with I2C interface. + + The data sheet can be found at: + https://www.kinet-ic.com/uploads/KTD2026-7-04h.pdf + +properties: + compatible: + enum: + - kinetic,ktd2026 + - kinetic,ktd2027 + + reg: + maxItems: 1 + + vin-supply: + description: Regulator providing power to the "VIN" pin. + + vio-supply: + description: Regulator providing power for pull-up of the I/O lines. + Note that this regulator does not directly connect to KTD2026, but is + needed for the correct operation of the status ("ST") and I2C lines. + + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + multi-led: + type: object + $ref: leds-class-multicolor.yaml# + unevaluatedProperties: false + + properties: + "#address-cells": + const: 1 + + "#size-cells": + const: 0 + + patternProperties: + "^led@[0-3]$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + description: Index of the LED. + minimum: 0 + maximum: 3 + + required: + - reg + - color + + required: + - "#address-cells" + - "#size-cells" + +patternProperties: + "^led@[0-3]$": + type: object + $ref: common.yaml# + unevaluatedProperties: false + + properties: + reg: + description: Index of the LED. + minimum: 0 + maximum: 3 + + required: + - reg + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/leds/common.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@30 { + compatible = "kinetic,ktd2026"; + reg = <0x30>; + #address-cells = <1>; + #size-cells = <0>; + + vin-supply = <&pm8916_l17>; + vio-supply = <&pm8916_l6>; + + led@0 { + reg = <0>; + function = LED_FUNCTION_STATUS; + color = <LED_COLOR_ID_RED>; + }; + + led@1 { + reg = <1>; + function = LED_FUNCTION_STATUS; + color = <LED_COLOR_ID_GREEN>; + }; + + led@2 { + reg = <2>; + function = LED_FUNCTION_STATUS; + color = <LED_COLOR_ID_BLUE>; + }; + }; + }; + - | + #include <dt-bindings/leds/common.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + led-controller@30 { + compatible = "kinetic,ktd2026"; + reg = <0x30>; + #address-cells = <1>; + #size-cells = <0>; + + vin-supply = <&pm8916_l17>; + vio-supply = <&pm8916_l6>; + + multi-led { + color = <LED_COLOR_ID_RGB>; + function = LED_FUNCTION_STATUS; + + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + color = <LED_COLOR_ID_RED>; + }; + + led@1 { + reg = <1>; + color = <LED_COLOR_ID_GREEN>; + }; + + led@2 { + reg = <2>; + color = <LED_COLOR_ID_BLUE>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/leds/register-bit-led.yaml b/Documentation/devicetree/bindings/leds/register-bit-led.yaml index ed26ec19ecbd..20930d327ae9 100644 --- a/Documentation/devicetree/bindings/leds/register-bit-led.yaml +++ b/Documentation/devicetree/bindings/leds/register-bit-led.yaml @@ -60,7 +60,7 @@ examples: - | syscon@10000000 { - compatible = "arm,realview-pb1176-syscon", "syscon"; + compatible = "arm,realview-pb1176-syscon", "syscon", "simple-mfd"; reg = <0x10000000 0x1000>; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml index 191c1ce15009..12e7a7d536a3 100644 --- a/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml +++ b/Documentation/devicetree/bindings/mailbox/fsl,mu.yaml @@ -72,9 +72,9 @@ properties: type : Channel type channel : Channel number - This MU support 5 type of unidirectional channels, each type + This MU support 6 type of unidirectional channels, each type has 4 channels except RST channel which only has 1 channel. - A total of 17 channels. Following types are + A total of 21 channels. Following types are supported: 0 - TX channel with 32bit transmit register and IRQ transmit acknowledgment support. @@ -82,6 +82,7 @@ properties: 2 - TX doorbell channel. Without own register and no ACK support. 3 - RX doorbell channel. 4 - RST channel + 5 - Tx doorbell channel. With S/W ACK from the other side. const: 2 clocks: diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml index d2e25ff6db7f..a38413f8d132 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.yaml @@ -125,10 +125,12 @@ allOf: items: - description: primary pll parent of the clock driver - description: XO clock + - description: GCC GPLL0 clock source clock-names: items: - const: pll - const: xo + - const: gpll0 - if: properties: diff --git a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml index cc6f66eccc84..a35f9483dc71 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml +++ b/Documentation/devicetree/bindings/mailbox/qcom-ipcc.yaml @@ -34,6 +34,7 @@ properties: - qcom,sm8350-ipcc - qcom,sm8450-ipcc - qcom,sm8550-ipcc + - qcom,sm8650-ipcc - const: qcom,ipcc reg: diff --git a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml index aeaddbf574b0..8b15a0532120 100644 --- a/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml +++ b/Documentation/devicetree/bindings/mailbox/xlnx,zynqmp-ipi-mailbox.yaml @@ -74,6 +74,10 @@ patternProperties: type: object # DT nodes are json objects additionalProperties: false properties: + + compatible: + const: xlnx,zynqmp-ipi-dest-mailbox + xlnx,ipi-id: description: Remote Xilinx IPI agent ID of which the mailbox is connected to. @@ -95,6 +99,7 @@ patternProperties: - const: remote_response_region required: + - compatible - reg - reg-names - "#mbox-cells" @@ -124,6 +129,7 @@ examples: ranges; mailbox: mailbox@ff9905c0 { + compatible = "xlnx,zynqmp-ipi-dest-mailbox"; reg = <0x0 0xff9905c0 0x0 0x20>, <0x0 0xff9905e0 0x0 0x20>, <0x0 0xff990e80 0x0 0x20>, diff --git a/Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml b/Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml index 3f9fa92703bb..0f95fe8dd9ac 100644 --- a/Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml +++ b/Documentation/devicetree/bindings/media/amlogic,meson6-ir.yaml @@ -19,6 +19,7 @@ properties: - amlogic,meson6-ir - amlogic,meson8b-ir - amlogic,meson-gxbb-ir + - amlogic,meson-s4-ir - items: - const: amlogic,meson-gx-ir - const: amlogic,meson-gxbb-ir diff --git a/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml b/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml index 30a335b10762..2008a47c0580 100644 --- a/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml +++ b/Documentation/devicetree/bindings/media/cdns,csi2rx.yaml @@ -18,6 +18,7 @@ properties: items: - enum: - starfive,jh7110-csi2rx + - ti,j721e-csi2rx - const: cdns,csi2rx reg: diff --git a/Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml b/Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml index 1e2df8cf2937..60f19e1152b3 100644 --- a/Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml +++ b/Documentation/devicetree/bindings/media/i2c/hynix,hi846.yaml @@ -14,6 +14,9 @@ description: |- interface and CCI (I2C compatible) control bus. The output format is raw Bayer. +allOf: + - $ref: /schemas/media/video-interface-devices.yaml# + properties: compatible: const: hynix,hi846 @@ -86,7 +89,7 @@ required: - vddd-supply - port -additionalProperties: false +unevaluatedProperties: false examples: - | @@ -109,6 +112,8 @@ examples: vddio-supply = <®_camera_vddio>; reset-gpios = <&gpio1 25 GPIO_ACTIVE_LOW>; shutdown-gpios = <&gpio5 4 GPIO_ACTIVE_LOW>; + orientation = <0>; + rotation = <0>; port { camera_out: endpoint { diff --git a/Documentation/devicetree/bindings/media/i2c/onnn,mt9m114.yaml b/Documentation/devicetree/bindings/media/i2c/onnn,mt9m114.yaml new file mode 100644 index 000000000000..f6b87892068a --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/onnn,mt9m114.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/onnn,mt9m114.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: onsemi 1/6-inch 720p CMOS Digital Image Sensor + +maintainers: + - Laurent Pinchart <laurent.pinchart@ideasonboard.com> + +description: |- + The onsemi MT9M114 is a 1/6-inch 720p (1.26 Mp) CMOS digital image sensor + with an active pixel-array size of 1296H x 976V. It is programmable through + an I2C interface and outputs image data over a 8-bit parallel or 1-lane MIPI + CSI-2 connection. + +properties: + compatible: + const: onnn,mt9m114 + + reg: + description: I2C device address + enum: + - 0x48 + - 0x5d + + clocks: + description: EXTCLK clock signal + maxItems: 1 + + vdd-supply: + description: + Core digital voltage supply, 1.8V + + vddio-supply: + description: + I/O digital voltage supply, 1.8V or 2.8V + + vaa-supply: + description: + Analog voltage supply, 2.8V + + reset-gpios: + description: |- + Reference to the GPIO connected to the RESET_BAR pin, if any (active + low). + + port: + $ref: /schemas/graph.yaml#/$defs/port-base + additionalProperties: false + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + additionalProperties: false + + properties: + bus-type: + enum: [4, 5, 6] + + link-frequencies: true + remote-endpoint: true + + # The number and mapping of lanes (for CSI-2), and the bus width and + # signal polarities (for parallel and BT.656) are fixed and must not + # be specified. + + required: + - bus-type + - link-frequencies + +required: + - compatible + - reg + - clocks + - vdd-supply + - vddio-supply + - vaa-supply + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/media/video-interfaces.h> + + i2c0 { + #address-cells = <1>; + #size-cells = <0>; + + sensor@48 { + compatible = "onnn,mt9m114"; + reg = <0x48>; + + clocks = <&clk24m 0>; + + reset-gpios = <&gpio5 21 GPIO_ACTIVE_LOW>; + + vddio-supply = <®_cam_1v8>; + vdd-supply = <®_cam_1v8>; + vaa-supply = <®_2p8v>; + + port { + endpoint { + bus-type = <MEDIA_BUS_TYPE_CSI2_DPHY>; + link-frequencies = /bits/ 64 <384000000>; + remote-endpoint = <&mipi_csi_in>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml index 763cebe03dc2..67c1c291327b 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov02a10.yaml @@ -68,12 +68,6 @@ properties: marked GPIO_ACTIVE_LOW. maxItems: 1 - rotation: - enum: - - 0 # Sensor Mounted Upright - - 180 # Sensor Mounted Upside Down - default: 0 - port: $ref: /schemas/graph.yaml#/$defs/port-base additionalProperties: false @@ -114,7 +108,7 @@ required: - reset-gpios - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml index 50579c947f3c..d96199031b66 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov4689.yaml @@ -52,10 +52,6 @@ properties: description: GPIO connected to the reset pin (active low) - orientation: true - - rotation: true - port: $ref: /schemas/graph.yaml#/$defs/port-base additionalProperties: false @@ -95,7 +91,7 @@ required: - dvdd-supply - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml index a621032f9bd0..2c5e69356658 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5640.yaml @@ -44,11 +44,6 @@ properties: description: > Reference to the GPIO connected to the reset pin, if any. - rotation: - enum: - - 0 - - 180 - port: description: Digital Output Port $ref: /schemas/graph.yaml#/$defs/port-base @@ -85,7 +80,7 @@ required: - DOVDD-supply - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5642.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5642.yaml new file mode 100644 index 000000000000..01f8b2b3fd17 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5642.yaml @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/i2c/ovti,ov5642.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OmniVision OV5642 Image Sensor + +maintainers: + - Fabio Estevam <festevam@gmail.com> + +allOf: + - $ref: /schemas/media/video-interface-devices.yaml# + +properties: + compatible: + const: ovti,ov5642 + + reg: + maxItems: 1 + + clocks: + description: XCLK Input Clock + + AVDD-supply: + description: Analog voltage supply, 2.8V. + + DVDD-supply: + description: Digital core voltage supply, 1.5V. + + DOVDD-supply: + description: Digital I/O voltage supply, 1.8V. + + powerdown-gpios: + maxItems: 1 + description: Reference to the GPIO connected to the powerdown pin, if any. + + reset-gpios: + maxItems: 1 + description: Reference to the GPIO connected to the reset pin, if any. + + port: + $ref: /schemas/graph.yaml#/$defs/port-base + description: | + Video output port. + + properties: + endpoint: + $ref: /schemas/media/video-interfaces.yaml# + unevaluatedProperties: false + + properties: + bus-type: + enum: [5, 6] + + bus-width: + enum: [8, 10] + default: 10 + + data-shift: + enum: [0, 2] + default: 0 + + hsync-active: + enum: [0, 1] + default: 1 + + vsync-active: + enum: [0, 1] + default: 1 + + pclk-sample: + enum: [0, 1] + default: 1 + + allOf: + - if: + properties: + bus-type: + const: 6 + then: + properties: + hsync-active: false + vsync-active: false + + - if: + properties: + bus-width: + const: 10 + then: + properties: + data-shift: + const: 0 + + required: + - bus-type + + additionalProperties: false + +required: + - compatible + - reg + - clocks + - port + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/media/video-interfaces.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + camera@3c { + compatible = "ovti,ov5642"; + reg = <0x3c>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_ov5642>; + clocks = <&clk_ext_camera>; + DOVDD-supply = <&vgen4_reg>; + AVDD-supply = <&vgen3_reg>; + DVDD-supply = <&vgen2_reg>; + powerdown-gpios = <&gpio1 19 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>; + + port { + ov5642_to_parallel: endpoint { + bus-type = <MEDIA_BUS_TYPE_PARALLEL>; + remote-endpoint = <¶llel_from_ov5642>; + bus-width = <8>; + data-shift = <2>; /* lines 9:2 are used */ + hsync-active = <0>; + vsync-active = <0>; + pclk-sample = <1>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml b/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml index 6829a4aadd22..3368b3bd8ef2 100644 --- a/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ovti,ov5693.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Omnivision OV5693/OV5695 CMOS Sensors maintainers: - - Tommaso Merciai <tommaso.merciai@amarulasolutions.com> + - Tommaso Merciai <tomm.merciai@gmail.com> description: | The Omnivision OV5693/OV5695 are high performance, 1/4-inch, 5 megapixel, CMOS diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml index e2470dd5920c..60903da84e1f 100644 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx214.yaml @@ -91,7 +91,7 @@ required: - vddd-supply - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml b/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml index 642f9b15d359..9a00dab2e8a3 100644 --- a/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx415.yaml @@ -44,14 +44,6 @@ properties: description: Sensor reset (XCLR) GPIO maxItems: 1 - flash-leds: true - - lens-focus: true - - orientation: true - - rotation: true - port: $ref: /schemas/graph.yaml#/$defs/port-base unevaluatedProperties: false @@ -89,7 +81,7 @@ required: - ovdd-supply - port -additionalProperties: false +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml index 289737721c2c..0b71e6f911a8 100644 --- a/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml +++ b/Documentation/devicetree/bindings/media/i2c/ti,ds90ub960.yaml @@ -69,6 +69,7 @@ properties: maxItems: 1 i2c-alias: + $ref: /schemas/types.yaml#/definitions/uint32 description: The I2C address used for the serializer. Transactions to this address on the I2C bus where the deserializer resides are diff --git a/Documentation/devicetree/bindings/media/nokia,n900-ir b/Documentation/devicetree/bindings/media/nokia,n900-ir deleted file mode 100644 index 13a18ce37dd1..000000000000 --- a/Documentation/devicetree/bindings/media/nokia,n900-ir +++ /dev/null @@ -1,20 +0,0 @@ -Device-Tree bindings for LIRC TX driver for Nokia N900(RX51) - -Required properties: - - compatible: should be "nokia,n900-ir". - - pwms: specifies PWM used for IR signal transmission. - -Example node: - - pwm9: dmtimer-pwm@9 { - compatible = "ti,omap-dmtimer-pwm"; - ti,timers = <&timer9>; - ti,clock-source = <0x00>; /* timer_sys_ck */ - #pwm-cells = <3>; - }; - - ir: n900-ir { - compatible = "nokia,n900-ir"; - - pwms = <&pwm9 0 26316 0>; /* 38000 Hz */ - }; diff --git a/Documentation/devicetree/bindings/media/nuvoton,npcm-ece.yaml b/Documentation/devicetree/bindings/media/nuvoton,npcm-ece.yaml new file mode 100644 index 000000000000..b47468e54504 --- /dev/null +++ b/Documentation/devicetree/bindings/media/nuvoton,npcm-ece.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nuvoton,npcm-ece.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton NPCM Encoding Compression Engine + +maintainers: + - Joseph Liu <kwliu@nuvoton.com> + - Marvin Lin <kflin@nuvoton.com> + +description: | + Video Encoding Compression Engine (ECE) present on Nuvoton NPCM SoCs. + +properties: + compatible: + enum: + - nuvoton,npcm750-ece + - nuvoton,npcm845-ece + + reg: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - resets + +additionalProperties: false + +examples: + - | + #include <dt-bindings/reset/nuvoton,npcm7xx-reset.h> + + ece: video-codec@f0820000 { + compatible = "nuvoton,npcm750-ece"; + reg = <0xf0820000 0x2000>; + resets = <&rstc NPCM7XX_RESET_IPSRST2 NPCM7XX_RESET_ECE>; + }; diff --git a/Documentation/devicetree/bindings/media/nuvoton,npcm-vcd.yaml b/Documentation/devicetree/bindings/media/nuvoton,npcm-vcd.yaml new file mode 100644 index 000000000000..c885f559d2e5 --- /dev/null +++ b/Documentation/devicetree/bindings/media/nuvoton,npcm-vcd.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/nuvoton,npcm-vcd.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton NPCM Video Capture/Differentiation Engine + +maintainers: + - Joseph Liu <kwliu@nuvoton.com> + - Marvin Lin <kflin@nuvoton.com> + +description: | + Video Capture/Differentiation Engine (VCD) present on Nuvoton NPCM SoCs. + +properties: + compatible: + enum: + - nuvoton,npcm750-vcd + - nuvoton,npcm845-vcd + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + nuvoton,sysgcr: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to access GCR (Global Control Register) registers. + + nuvoton,sysgfxi: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to access GFXI (Graphics Core Information) registers. + + nuvoton,ece: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to access ECE (Encoding Compression Engine) registers. + + memory-region: + maxItems: 1 + description: + CMA pool to use for buffers allocation instead of the default CMA pool. + +required: + - compatible + - reg + - interrupts + - resets + - nuvoton,sysgcr + - nuvoton,sysgfxi + - nuvoton,ece + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/reset/nuvoton,npcm7xx-reset.h> + + vcd: vcd@f0810000 { + compatible = "nuvoton,npcm750-vcd"; + reg = <0xf0810000 0x10000>; + interrupts = <GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH>; + resets = <&rstc NPCM7XX_RESET_IPSRST2 NPCM7XX_RESET_VCD>; + nuvoton,sysgcr = <&gcr>; + nuvoton,sysgfxi = <&gfxi>; + nuvoton,ece = <&ece>; + }; diff --git a/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml b/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml index d5f80976f4cf..6228fd2b3246 100644 --- a/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml +++ b/Documentation/devicetree/bindings/media/qcom,sdm845-venus-v2.yaml @@ -48,6 +48,14 @@ properties: iommus: maxItems: 2 + interconnects: + maxItems: 2 + + interconnect-names: + items: + - const: video-mem + - const: cpu-cfg + operating-points-v2: true opp-table: type: object diff --git a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml index 772ec3283bc6..c57e1f488895 100644 --- a/Documentation/devicetree/bindings/media/rockchip-vpu.yaml +++ b/Documentation/devicetree/bindings/media/rockchip-vpu.yaml @@ -68,6 +68,13 @@ properties: iommus: maxItems: 1 + resets: + items: + - description: AXI reset line + - description: AXI bus interface unit reset line + - description: APB reset line + - description: APB bus interface unit reset line + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml b/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml index 3691cd4962b2..3a5ff3f47060 100644 --- a/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml +++ b/Documentation/devicetree/bindings/media/samsung,exynos4212-fimc-is.yaml @@ -75,13 +75,20 @@ properties: power-domains: maxItems: 1 + samsung,pmu-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Power Management Unit (PMU) system controller interface, used to + power/start the ISP. + patternProperties: "^pmu@[0-9a-f]+$": type: object additionalProperties: false + deprecated: true description: Node representing the SoC's Power Management Unit (duplicated with the - correct PMU node in the SoC). + correct PMU node in the SoC). Deprecated, use samsung,pmu-syscon. properties: reg: @@ -131,6 +138,7 @@ required: - clock-names - interrupts - ranges + - samsung,pmu-syscon - '#size-cells' additionalProperties: false @@ -179,15 +187,12 @@ examples: <&sysmmu_fimc_fd>, <&sysmmu_fimc_mcuctl>; iommu-names = "isp", "drc", "fd", "mcuctl"; power-domains = <&pd_isp>; + samsung,pmu-syscon = <&pmu_system_controller>; #address-cells = <1>; #size-cells = <1>; ranges; - pmu@10020000 { - reg = <0x10020000 0x3000>; - }; - i2c-isp@12140000 { compatible = "samsung,exynos4212-i2c-isp"; reg = <0x12140000 0x100>; diff --git a/Documentation/devicetree/bindings/media/samsung,fimc.yaml b/Documentation/devicetree/bindings/media/samsung,fimc.yaml index b3486c38a05b..7808d61f1fa3 100644 --- a/Documentation/devicetree/bindings/media/samsung,fimc.yaml +++ b/Documentation/devicetree/bindings/media/samsung,fimc.yaml @@ -118,7 +118,7 @@ examples: #clock-cells = <1>; #address-cells = <1>; #size-cells = <1>; - ranges = <0x0 0x0 0x18000000>; + ranges = <0x0 0x0 0xba1000>; clocks = <&clock CLK_SCLK_CAM0>, <&clock CLK_SCLK_CAM1>, <&clock CLK_PIXELASYNCM0>, <&clock CLK_PIXELASYNCM1>; @@ -133,9 +133,9 @@ examples: pinctrl-0 = <&cam_port_a_clk_active &cam_port_b_clk_active>; pinctrl-names = "default"; - fimc@11800000 { + fimc@0 { compatible = "samsung,exynos4212-fimc"; - reg = <0x11800000 0x1000>; + reg = <0x00000000 0x1000>; interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; clocks = <&clock CLK_FIMC0>, <&clock CLK_SCLK_FIMC0>; @@ -152,9 +152,9 @@ examples: /* ... FIMC 1-3 */ - csis@11880000 { + csis@80000 { compatible = "samsung,exynos4210-csis"; - reg = <0x11880000 0x4000>; + reg = <0x00080000 0x4000>; interrupts = <GIC_SPI 78 IRQ_TYPE_LEVEL_HIGH>; clocks = <&clock CLK_CSIS0>, <&clock CLK_SCLK_CSIS0>; @@ -187,9 +187,9 @@ examples: /* ... CSIS 1 */ - fimc-lite@12390000 { + fimc-lite@b90000 { compatible = "samsung,exynos4212-fimc-lite"; - reg = <0x12390000 0x1000>; + reg = <0xb90000 0x1000>; interrupts = <GIC_SPI 105 IRQ_TYPE_LEVEL_HIGH>; power-domains = <&pd_isp>; clocks = <&isp_clock CLK_ISP_FIMC_LITE0>; @@ -199,9 +199,9 @@ examples: /* ... FIMC-LITE 1 */ - fimc-is@12000000 { + fimc-is@800000 { compatible = "samsung,exynos4212-fimc-is"; - reg = <0x12000000 0x260000>; + reg = <0x00800000 0x260000>; interrupts = <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>; clocks = <&isp_clock CLK_ISP_FIMC_LITE0>, @@ -237,18 +237,15 @@ examples: <&sysmmu_fimc_fd>, <&sysmmu_fimc_mcuctl>; iommu-names = "isp", "drc", "fd", "mcuctl"; power-domains = <&pd_isp>; + samsung,pmu-syscon = <&pmu_system_controller>; #address-cells = <1>; #size-cells = <1>; ranges; - pmu@10020000 { - reg = <0x10020000 0x3000>; - }; - - i2c-isp@12140000 { + i2c-isp@940000 { compatible = "samsung,exynos4212-i2c-isp"; - reg = <0x12140000 0x100>; + reg = <0x00940000 0x100>; clocks = <&isp_clock CLK_ISP_I2C1_ISP>; clock-names = "i2c_isp"; pinctrl-0 = <&fimc_is_i2c1>; diff --git a/Documentation/devicetree/bindings/media/ti,j721e-csi2rx-shim.yaml b/Documentation/devicetree/bindings/media/ti,j721e-csi2rx-shim.yaml new file mode 100644 index 000000000000..f762fdc05e4d --- /dev/null +++ b/Documentation/devicetree/bindings/media/ti,j721e-csi2rx-shim.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/ti,j721e-csi2rx-shim.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI J721E CSI2RX Shim + +description: | + The TI J721E CSI2RX Shim is a wrapper around Cadence CSI2RX bridge that + enables sending captured frames to memory over PSI-L DMA. In the J721E + Technical Reference Manual (SPRUIL1B) it is referred to as "SHIM" under the + CSI_RX_IF section. + +maintainers: + - Jai Luthra <j-luthra@ti.com> + +properties: + compatible: + const: ti,j721e-csi2rx-shim + + dmas: + maxItems: 1 + + dma-names: + items: + - const: rx0 + + reg: + maxItems: 1 + + power-domains: + maxItems: 1 + + ranges: true + + "#address-cells": true + + "#size-cells": true + +patternProperties: + "^csi-bridge@": + type: object + description: CSI2 bridge node. + $ref: cdns,csi2rx.yaml# + +required: + - compatible + - reg + - dmas + - dma-names + - power-domains + - ranges + - "#address-cells" + - "#size-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/soc/ti,sci_pm_domain.h> + + ti_csi2rx0: ticsi2rx@4500000 { + compatible = "ti,j721e-csi2rx-shim"; + dmas = <&main_udmap 0x4940>; + dma-names = "rx0"; + reg = <0x4500000 0x1000>; + power-domains = <&k3_pds 26 TI_SCI_PD_EXCLUSIVE>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + cdns_csi2rx: csi-bridge@4504000 { + compatible = "ti,j721e-csi2rx", "cdns,csi2rx"; + reg = <0x4504000 0x1000>; + clocks = <&k3_clks 26 2>, <&k3_clks 26 0>, <&k3_clks 26 2>, + <&k3_clks 26 2>, <&k3_clks 26 3>, <&k3_clks 26 3>; + clock-names = "sys_clk", "p_clk", "pixel_if0_clk", + "pixel_if1_clk", "pixel_if2_clk", "pixel_if3_clk"; + phys = <&dphy0>; + phy-names = "dphy"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + csi2_0: port@0 { + + reg = <0>; + + csi2rx0_in_sensor: endpoint { + remote-endpoint = <&csi2_cam0>; + bus-type = <4>; /* CSI2 DPHY. */ + clock-lanes = <0>; + data-lanes = <1 2>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/video-interfaces.yaml b/Documentation/devicetree/bindings/media/video-interfaces.yaml index a211d49dc2ac..26e3e7d7c67b 100644 --- a/Documentation/devicetree/bindings/media/video-interfaces.yaml +++ b/Documentation/devicetree/bindings/media/video-interfaces.yaml @@ -160,6 +160,7 @@ properties: $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 1 maxItems: 8 + uniqueItems: true items: # Assume up to 9 physical lane indices maximum: 8 diff --git a/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml b/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml index b40cec0eb651..ee74a362f4ca 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ingenic,nemc.yaml @@ -40,6 +40,7 @@ patternProperties: ".*@[0-9]+$": type: object $ref: mc-peripheral-props.yaml# + additionalProperties: true required: - compatible diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml index 56e62cd0b36a..25f3bb9890ae 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/renesas,rpc-if.yaml @@ -80,6 +80,8 @@ properties: patternProperties: "flash@[0-9a-f]+$": type: object + additionalProperties: true + properties: compatible: contains: diff --git a/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml b/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml index 4e4af3cfc0fe..1f58ee99be28 100644 --- a/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/rockchip,rk3399-dmc.yaml @@ -18,7 +18,7 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle description: Node to get DDR loading. Refer to - Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt. + Documentation/devicetree/bindings/devfreq/event/rockchip,dfi.yaml. clocks: maxItems: 1 diff --git a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml index b049837ee669..c7a8a041da50 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/ti,gpmc.yaml @@ -130,7 +130,7 @@ patternProperties: bus. The device can be a NAND chip, SRAM device, NOR device or an ASIC. $ref: ti,gpmc-child.yaml - + additionalProperties: true required: - compatible diff --git a/Documentation/devicetree/bindings/memory-controllers/xlnx,versal-ddrmc-edac.yaml b/Documentation/devicetree/bindings/memory-controllers/xlnx,versal-ddrmc-edac.yaml new file mode 100644 index 000000000000..12f8e9f350bc --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/xlnx,versal-ddrmc-edac.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/xlnx,versal-ddrmc-edac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Versal DDRMC (Integrated DDR Memory Controller) + +maintainers: + - Shubhrajyoti Datta <shubhrajyoti.datta@amd.com> + - Sai Krishna Potthuri <sai.krishna.potthuri@amd.com> + +description: + The integrated DDR Memory Controllers (DDRMCs) support both DDR4 and LPDDR4/ + 4X memory interfaces. Versal DDR memory controller has an optional ECC support + which correct single bit ECC errors and detect double bit ECC errors. + +properties: + compatible: + const: xlnx,versal-ddrmc + + reg: + items: + - description: DDR Memory Controller registers + - description: NOC registers corresponding to DDR Memory Controller + + reg-names: + items: + - const: base + - const: noc + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - reg-names + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + + bus { + #address-cells = <2>; + #size-cells = <2>; + memory-controller@f6150000 { + compatible = "xlnx,versal-ddrmc"; + reg = <0x0 0xf6150000 0x0 0x2000>, <0x0 0xf6070000 0x0 0x20000>; + reg-names = "base", "noc"; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/arm,dev-platforms-syscon.yaml b/Documentation/devicetree/bindings/mfd/arm,dev-platforms-syscon.yaml new file mode 100644 index 000000000000..46b164ae0831 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/arm,dev-platforms-syscon.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/arm,dev-platforms-syscon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Arm Ltd Developer Platforms System Controllers + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +description: + The Arm Ltd Integrator, Realview, and Versatile families of developer + platforms are contain various system controller blocks. Often these blocks + are part of a daughterboard or motherboard module. + +properties: + compatible: + oneOf: + - items: + - enum: + - arm,integrator-ap-syscon + - arm,integrator-cp-syscon + - arm,integrator-sp-syscon + - arm,im-pd1-syscon + - const: syscon + - items: + - enum: + - arm,core-module-integrator + - arm,integrator-ap-syscon + - arm,integrator-cp-syscon + - arm,integrator-sp-syscon + - arm,realview-eb-syscon + - arm,realview-pb1176-syscon + - arm,realview-pb11mp-syscon + - arm,realview-pba8-syscon + - arm,realview-pbx-syscon + - arm,versatile-ib2-syscon + - const: syscon + - const: simple-mfd + - items: + - enum: + - arm,realview-eb11mp-revb-syscon + - arm,realview-eb11mp-revc-syscon + - const: arm,realview-eb-syscon + - const: syscon + - const: simple-mfd + + reg: + maxItems: 1 + + ranges: true + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + +required: + - compatible + - reg + +additionalProperties: + type: object + +... diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml index c14def1b2ad2..9c2a04829da5 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml @@ -148,47 +148,47 @@ examples: pinctrl_nand: nand-pins { function = "nand"; - group = "nand_grp"; + pins = "nand_grp"; }; pinctrl_gpio35_alt: gpio35_alt-pins { function = "gpio35_alt"; - pin = "gpio35"; + pins = "gpio35"; }; pinctrl_dectpd: dectpd-pins { function = "dectpd"; - group = "dectpd_grp"; + pins = "dectpd_grp"; }; pinctrl_vdsl_phy_override_0: vdsl_phy_override_0-pins { function = "vdsl_phy_override_0"; - group = "vdsl_phy_override_0_grp"; + pins = "vdsl_phy_override_0_grp"; }; pinctrl_vdsl_phy_override_1: vdsl_phy_override_1-pins { function = "vdsl_phy_override_1"; - group = "vdsl_phy_override_1_grp"; + pins = "vdsl_phy_override_1_grp"; }; pinctrl_vdsl_phy_override_2: vdsl_phy_override_2-pins { function = "vdsl_phy_override_2"; - group = "vdsl_phy_override_2_grp"; + pins = "vdsl_phy_override_2_grp"; }; pinctrl_vdsl_phy_override_3: vdsl_phy_override_3-pins { function = "vdsl_phy_override_3"; - group = "vdsl_phy_override_3_grp"; + pins = "vdsl_phy_override_3_grp"; }; pinctrl_dsl_gpio8: dsl_gpio8-pins { function = "dsl_gpio8"; - group = "dsl_gpio8"; + pins = "dsl_gpio8"; }; pinctrl_dsl_gpio9: dsl_gpio9-pins { function = "dsl_gpio9"; - group = "dsl_gpio9"; + pins = "dsl_gpio9"; }; }; }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml index 4d594739b382..c2941638c8f2 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml @@ -230,7 +230,7 @@ examples: pinctrl_nand: nand-pins { function = "nand"; - group = "nand_grp"; + pins = "nand_grp"; }; }; }; diff --git a/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml b/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml index aae83d432880..44e77d77d314 100644 --- a/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml +++ b/Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml @@ -240,7 +240,7 @@ examples: pinctrl_uart1: uart1-pins { function = "uart1"; - group = "uart1_grp"; + pins = "uart1_grp"; }; }; }; diff --git a/Documentation/devicetree/bindings/mfd/max8925.txt b/Documentation/devicetree/bindings/mfd/max8925.txt deleted file mode 100644 index 4f0dc6638e5e..000000000000 --- a/Documentation/devicetree/bindings/mfd/max8925.txt +++ /dev/null @@ -1,64 +0,0 @@ -* Maxim max8925 Power Management IC - -Required parent device properties: -- compatible : "maxim,max8925" -- reg : the I2C slave address for the max8925 chip -- interrupts : IRQ line for the max8925 chip -- interrupt-controller: describes the max8925 as an interrupt - controller (has its own domain) -- #interrupt-cells : should be 1. - - The cell is the max8925 local IRQ number - -Optional parent device properties: -- maxim,tsc-irq: there are 2 IRQ lines for max8925, one is indicated in - interrupts property, the other is indicated here. - -max8925 consists of a large and varied group of sub-devices: - -Device Supply Names Description ------- ------------ ----------- -max8925-onkey : : On key -max8925-rtc : : RTC -max8925-regulator : : Regulators -max8925-backlight : : Backlight -max8925-touch : : Touchscreen -max8925-power : : Charger - -Example: - - pmic: max8925@3c { - compatible = "maxim,max8925"; - reg = <0x3c>; - interrupts = <1>; - interrupt-parent = <&intcmux4>; - interrupt-controller; - #interrupt-cells = <1>; - maxim,tsc-irq = <0>; - - regulators { - SDV1 { - regulator-min-microvolt = <637500>; - regulator-max-microvolt = <1425000>; - regulator-boot-on; - regulator-always-on; - }; - - LDO1 { - regulator-min-microvolt = <750000>; - regulator-max-microvolt = <3900000>; - regulator-boot-on; - regulator-always-on; - }; - - }; - backlight { - maxim,max8925-dual-string = <0>; - }; - charger { - batt-detect = <0>; - topoff-threshold = <1>; - fast-charge = <7>; - no-temp-support = <0>; - no-insert-detect = <0>; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/max8998.txt b/Documentation/devicetree/bindings/mfd/max8998.txt deleted file mode 100644 index 4ed52184d081..000000000000 --- a/Documentation/devicetree/bindings/mfd/max8998.txt +++ /dev/null @@ -1,125 +0,0 @@ -* Maxim MAX8998, National/TI LP3974 multi-function device - -The Maxim MAX8998 is a multi-function device which includes voltage/current -regulators, real time clock, battery charging controller and several -other sub-blocks. It is interfaced using an I2C interface. Each sub-block -is addressed by the host system using different i2c slave address. - -PMIC sub-block --------------- - -The PMIC sub-block contains a number of voltage and current regulators, -with controllable parameters and dynamic voltage scaling capability. -In addition, it includes a real time clock and battery charging controller -as well. It is accessible at I2C address 0x66. - -Required properties: -- compatible: Should be one of the following: - - "maxim,max8998" for Maxim MAX8998 - - "national,lp3974" or "ti,lp3974" for National/TI LP3974. -- reg: Specifies the i2c slave address of the pmic block. It should be 0x66. - -Optional properties: -- interrupts: Interrupt specifiers for two interrupt sources. - - First interrupt specifier is for main interrupt. - - Second interrupt specifier is for power-on/-off interrupt. -- max8998,pmic-buck1-dvs-gpios: GPIO specifiers for two host gpios used - for buck 1 dvs. The format of the gpio specifier depends on the gpio - controller. -- max8998,pmic-buck2-dvs-gpio: GPIO specifier for host gpio used - for buck 2 dvs. The format of the gpio specifier depends on the gpio - controller. -- max8998,pmic-buck1-default-dvs-idx: Default voltage setting selected from - the possible 4 options selectable by the dvs gpios. The value of this - property should be 0, 1, 2 or 3. If not specified or out of range, - a default value of 0 is taken. -- max8998,pmic-buck2-default-dvs-idx: Default voltage setting selected from - the possible 2 options selectable by the dvs gpios. The value of this - property should be 0 or 1. If not specified or out of range, a default - value of 0 is taken. -- max8998,pmic-buck-voltage-lock: If present, disallows changing of - preprogrammed buck dvfs voltages. - -Additional properties required if max8998,pmic-buck1-dvs-gpios is defined: -- max8998,pmic-buck1-dvs-voltage: An array of 4 voltage values in microvolts - for buck1 regulator that can be selected using dvs gpio. - -Additional properties required if max8998,pmic-buck2-dvs-gpio is defined: -- max8998,pmic-buck2-dvs-voltage: An array of 2 voltage values in microvolts - for buck2 regulator that can be selected using dvs gpio. - -Regulators: All the regulators of MAX8998 to be instantiated shall be -listed in a child node named 'regulators'. Each regulator is represented -by a child node of the 'regulators' node. - - regulator-name { - /* standard regulator bindings here */ - }; - -Following regulators of the MAX8998 PMIC block are supported. Note that -the 'n' in regulator name, as in LDOn or BUCKn, represents the LDO or BUCK -number as described in MAX8998 datasheet. - - - LDOn - - valid values for n are 2 to 17 - - Example: LDO2, LDO10, LDO17 - - BUCKn - - valid values for n are 1 to 4. - - Example: BUCK1, BUCK2, BUCK3, BUCK4 - - - ENVICHG: Battery Charging Current Monitor Output. This is a fixed - voltage type regulator - - - ESAFEOUT1: (ldo19) - - ESAFEOUT2: (ld020) - - - CHARGER: main battery charger current control - -Standard regulator bindings are used inside regulator subnodes. Check - Documentation/devicetree/bindings/regulator/regulator.txt -for more details. - -Example: - - pmic@66 { - compatible = "maxim,max8998-pmic"; - reg = <0x66>; - interrupt-parent = <&wakeup_eint>; - interrupts = <4 0>, <3 0>; - - /* Buck 1 DVS settings */ - max8998,pmic-buck1-default-dvs-idx = <0>; - max8998,pmic-buck1-dvs-gpios = <&gpx0 0 1 0 0>, /* SET1 */ - <&gpx0 1 1 0 0>; /* SET2 */ - max8998,pmic-buck1-dvs-voltage = <1350000>, <1300000>, - <1000000>, <950000>; - - /* Buck 2 DVS settings */ - max8998,pmic-buck2-default-dvs-idx = <0>; - max8998,pmic-buck2-dvs-gpio = <&gpx0 0 3 0 0>; /* SET3 */ - max8998,pmic-buck2-dvs-voltage = <1350000>, <1300000>; - - /* Regulators to instantiate */ - regulators { - ldo2_reg: LDO2 { - regulator-name = "VDD_ALIVE_1.1V"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "VDD_ARM_1.2V"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - regulator-boot-on; - }; - - charger_reg: CHARGER { - regulator-name = "CHARGER"; - regulator-min-microamp = <90000>; - regulator-max-microamp = <800000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml b/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml index da67742c5aa9..0da5cae3852e 100644 --- a/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml +++ b/Documentation/devicetree/bindings/mfd/maxim,max5970.yaml @@ -45,8 +45,13 @@ properties: patternProperties: "^led@[0-3]$": $ref: /schemas/leds/common.yaml# + unevaluatedProperties: false type: object + properties: + reg: + maximum: 3 + additionalProperties: false vss1-supply: diff --git a/Documentation/devicetree/bindings/mfd/maxim,max8925.yaml b/Documentation/devicetree/bindings/mfd/maxim,max8925.yaml new file mode 100644 index 000000000000..86dd810851ab --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max8925.yaml @@ -0,0 +1,145 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max8925.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MAX8925 PMIC from Maxim Integrated. + +maintainers: + - Lee Jones <lee@kernel.org> + +properties: + compatible: + const: maxim,max8925 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + description: + The cell is the IRQ number + + maxim,tsc-irq: + description: second interrupt from max8925 + $ref: /schemas/types.yaml#/definitions/uint32 + + regulators: + type: object + + patternProperties: + "^SDV[1-3]$|^LDO[1-9]$|^LDO1[0-9]$|^LDO20$": + description: regulator configuration for SDV1-3 and LDO1-20 + $ref: /schemas/regulator/regulator.yaml + unevaluatedProperties: false + + additionalProperties: false + + backlight: + type: object + properties: + maxim,max8925-dual-string: + description: set to 1 to support dual string + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + additionalProperties: false + + charger: + type: object + properties: + batt-detect: + description: set to 1 if battery detection via ID pin is supported + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + topoff-threshold: + description: charging current in topoff mode, configures bits 5-6 in CHG_CNTL1 + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 3 + default: 0 + + fast-charge: + description: set charging current in fast mode, configures bits 0-3 in CHG_CNTL1 + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + default: 0 + + no-temp-support: + description: set to 1 if temperature sensing is not supported + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + no-insert-detect: + description: set to 1 if AC detection is not supported + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + + additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - "#interrupt-cells" + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@3c { + compatible = "maxim,max8925"; + reg = <0x3c>; + interrupts = <1>; + interrupt-parent = <&intcmux4>; + interrupt-controller; + #interrupt-cells = <1>; + maxim,tsc-irq = <0>; + + regulators { + SDV1 { + regulator-min-microvolt = <637500>; + regulator-max-microvolt = <1425000>; + regulator-boot-on; + regulator-always-on; + }; + + LDO1 { + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <3900000>; + regulator-boot-on; + regulator-always-on; + }; + }; + + backlight { + maxim,max8925-dual-string = <0>; + }; + + charger { + batt-detect = <0>; + topoff-threshold = <1>; + fast-charge = <7>; + no-temp-support = <0>; + no-insert-detect = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/maxim,max8998.yaml b/Documentation/devicetree/bindings/mfd/maxim,max8998.yaml new file mode 100644 index 000000000000..f3c3f64fd012 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/maxim,max8998.yaml @@ -0,0 +1,324 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/maxim,max8998.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX8998, National/TI LP3974 Power Management IC + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +description: + The Maxim MAX8998 is a Power Management IC which includes voltage/current + regulators, real time clock, battery charging controller and several other + sub-blocks. It is interfaced using an I2C interface. Each sub-block is + addressed by the host system using different i2c slave address. + +properties: + compatible: + enum: + - maxim,max8998 + - national,lp3974 + - ti,lp3974 + + reg: + maxItems: 1 + + interrupts: + minItems: 1 + items: + - description: Main interrupt + - description: Power-on/-off interrupt + + max8998,pmic-buck1-dvs-gpios: + maxItems: 2 + description: + Two host gpios used for buck1 DVS. + + max8998,pmic-buck2-dvs-gpio: + maxItems: 1 + description: + Host gpio used for buck2 DVS. + + max8998,pmic-buck1-default-dvs-idx: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1, 2, 3] + default: 0 + description: + Default voltage setting selected from the possible 4 options selectable + by the DVS gpios. + + max8998,pmic-buck2-default-dvs-idx: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + default: 0 + description: + Default voltage setting selected from the possible 2 options selectable + by the DVS GPIOs. + + max8998,pmic-buck-voltage-lock: + type: boolean + description: + If present, disallows changing of preprogrammed buck DVS voltages. + + max8998,pmic-buck1-dvs-voltage: + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 4 + description: + Four voltage values in microvolts for buck1 regulator that can be + selected using DVS GPIO. + + max8998,pmic-buck2-dvs-voltage: + $ref: /schemas/types.yaml#/definitions/uint32-array + maxItems: 2 + description: + Two voltage values in microvolts for buck2 regulator that can be + selected using DVS GPIO. + + regulators: + type: object + additionalProperties: false + + properties: + CHARGER: + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + description: + CHARGER is main battery charger current control, wrongly represented + as regulator. + + properties: + regulator-min-microamp: + minimum: 90000 + maximum: 800000 + + regulator-max-microamp: + minimum: 90000 + maximum: 800000 + + regulator-min-microvolt: false + regulator-max-microvolt: false + + required: + - regulator-name + + patternProperties: + "^(LDO([2-9]|1[0-7])|BUCK[1-4])$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + + required: + - regulator-name + + "^(EN32KHz-AP|EN32KHz-CP|ENVICHG|ESAFEOUT[12])$": + type: object + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false + description: | + EN32KHz-AP and EN32KHz-CP are 32768 Hz clocks, wrongly represented as + regulators. + ENVICHG is a Battery Charging Current Monitor Output. + + properties: + regulator-min-microvolt: false + regulator-max-microvolt: false + + required: + - regulator-name + +dependencies: + max8998,pmic-buck1-dvs-gpios: [ "max8998,pmic-buck1-dvs-voltage" ] + max8998,pmic-buck2-dvs-gpio: [ "max8998,pmic-buck2-dvs-voltage" ] + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@66 { + compatible = "national,lp3974"; + reg = <0x66>; + interrupts-extended = <&gpx0 7 IRQ_TYPE_LEVEL_LOW>, + <&gpx2 7 IRQ_TYPE_LEVEL_LOW>; + pinctrl-names = "default"; + pinctrl-0 = <&lp3974_irq>; + + max8998,pmic-buck1-default-dvs-idx = <0>; + max8998,pmic-buck1-dvs-gpios = <&gpx0 5 GPIO_ACTIVE_HIGH>, + <&gpx0 6 GPIO_ACTIVE_HIGH>; + max8998,pmic-buck1-dvs-voltage = <1100000>, <1000000>, + <1100000>, <1000000>; + max8998,pmic-buck2-default-dvs-idx = <0>; + max8998,pmic-buck2-dvs-gpio = <&gpe2 0 GPIO_ACTIVE_HIGH>; + max8998,pmic-buck2-dvs-voltage = <1200000>, <1100000>; + + regulators { + LDO2 { + regulator-name = "VALIVE_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + }; + + LDO3 { + regulator-name = "VUSB+MIPI_1.1V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + }; + + LDO4 { + regulator-name = "VADC_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + LDO5 { + regulator-name = "VTF_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + + LDO6 { + regulator-name = "LDO6"; + regulator-min-microvolt = <2000000>; + regulator-max-microvolt = <2000000>; + }; + + LDO7 { + regulator-name = "VLCD+VMIPI_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + LDO8 { + regulator-name = "VUSB+VDAC_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + LDO9 { + regulator-name = "VCC_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + }; + + LDO10 { + regulator-name = "VPLL_1.1V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-boot-on; + regulator-always-on; + }; + + LDO11 { + regulator-name = "CAM_AF_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + LDO12 { + regulator-name = "PS_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + + LDO13 { + regulator-name = "VHIC_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; + + LDO14 { + regulator-name = "CAM_I_HOST_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + LDO15 { + regulator-name = "CAM_S_DIG+FM33_CORE_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; + + LDO16 { + regulator-name = "CAM_S_ANA_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + + LDO17 { + regulator-name = "VCC_3.0V_LCD"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3000000>; + }; + + BUCK1 { + regulator-name = "VINT_1.1V"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + regulator-always-on; + }; + + BUCK2 { + regulator-name = "VG3D_1.1V"; + regulator-min-microvolt = <750000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + }; + + BUCK3 { + regulator-name = "VCC_1.8V"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + + BUCK4 { + regulator-name = "VMEM_1.2V"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + }; + + EN32KHz-AP { + regulator-name = "32KHz AP"; + regulator-always-on; + }; + + EN32KHz-CP { + regulator-name = "32KHz CP"; + }; + + ENVICHG { + regulator-name = "VICHG"; + }; + + ESAFEOUT1 { + regulator-name = "SAFEOUT1"; + }; + + ESAFEOUT2 { + regulator-name = "SAFEOUT2"; + regulator-boot-on; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml b/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml index fc2a53148e1c..37423c2e0fdf 100644 --- a/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml +++ b/Documentation/devicetree/bindings/mfd/mediatek,mt6357.yaml @@ -40,6 +40,7 @@ properties: regulators: type: object $ref: /schemas/regulator/mediatek,mt6357-regulator.yaml + unevaluatedProperties: false description: List of MT6357 BUCKs and LDOs regulators. @@ -59,6 +60,7 @@ properties: keys: type: object $ref: /schemas/input/mediatek,pmic-keys.yaml + unevaluatedProperties: false description: MT6357 power and home keys. diff --git a/Documentation/devicetree/bindings/mfd/mt6397.txt b/Documentation/devicetree/bindings/mfd/mt6397.txt index 294693a8906c..10540aa7afa1 100644 --- a/Documentation/devicetree/bindings/mfd/mt6397.txt +++ b/Documentation/devicetree/bindings/mfd/mt6397.txt @@ -22,8 +22,9 @@ compatible: "mediatek,mt6323" for PMIC MT6323 "mediatek,mt6331" for PMIC MT6331 and MT6332 "mediatek,mt6357" for PMIC MT6357 - "mediatek,mt6358" for PMIC MT6358 and MT6366 + "mediatek,mt6358" for PMIC MT6358 "mediatek,mt6359" for PMIC MT6359 + "mediatek,mt6366", "mediatek,mt6358" for PMIC MT6366 "mediatek,mt6397" for PMIC MT6397 Optional subnodes: @@ -40,6 +41,7 @@ Optional subnodes: - compatible: "mediatek,mt6323-regulator" see ../regulator/mt6323-regulator.txt - compatible: "mediatek,mt6358-regulator" + - compatible: "mediatek,mt6366-regulator", "mediatek-mt6358-regulator" see ../regulator/mt6358-regulator.txt - compatible: "mediatek,mt6397-regulator" see ../regulator/mt6397-regulator.txt diff --git a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml index 9f03436b1cdc..9fa568603930 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,spmi-pmic.yaml @@ -58,6 +58,7 @@ properties: - qcom,pm8350 - qcom,pm8350b - qcom,pm8350c + - qcom,pm8450 - qcom,pm8550 - qcom,pm8550b - qcom,pm8550ve @@ -168,6 +169,10 @@ patternProperties: type: object $ref: /schemas/thermal/qcom,spmi-temp-alarm.yaml# + "^typec@[0-9a-f]+$": + type: object + $ref: /schemas/usb/qcom,pmic-typec.yaml# + "^usb-detect@[0-9a-f]+$": type: object $ref: /schemas/extcon/qcom,pm8941-misc.yaml# @@ -234,13 +239,13 @@ examples: interrupt-controller; #interrupt-cells = <4>; - pmi8998_lsid0: pmic@2 { + pmic@2 { compatible = "qcom,pmi8998", "qcom,spmi-pmic"; reg = <0x2 SPMI_USID>; #address-cells = <1>; #size-cells = <0>; - pmi8998_gpio: gpio@c000 { + gpio@c000 { compatible = "qcom,pmi8998-gpio", "qcom,spmi-gpio"; reg = <0xc000>; gpio-controller; @@ -325,7 +330,7 @@ examples: }; }; - pm6150_gpio: gpio@c000 { + gpio@c000 { compatible = "qcom,pm6150-gpio", "qcom,spmi-gpio"; reg = <0xc000>; gpio-controller; diff --git a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml index 5ad9d5deaaf8..33c3d023a106 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml @@ -27,6 +27,7 @@ properties: - qcom,sdm845-tcsr - qcom,sdx55-tcsr - qcom,sdx65-tcsr + - qcom,sm4450-tcsr - qcom,sm8150-tcsr - qcom,sm8450-tcsr - qcom,tcsr-apq8064 diff --git a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml index 9c51c1b19067..7fe3875a5996 100644 --- a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.yaml @@ -43,13 +43,37 @@ properties: interrupt-controller: true patternProperties: + "gpio@[0-9a-f]+$": + type: object + $ref: /schemas/pinctrl/qcom,pmic-gpio.yaml# + + "keypad@[0-9a-f]+$": + type: object + $ref: /schemas/input/qcom,pm8921-keypad.yaml# + "led@[0-9a-f]+$": type: object $ref: /schemas/leds/qcom,pm8058-led.yaml# + "mpps@[0-9a-f]+$": + type: object + $ref: /schemas/pinctrl/qcom,pmic-mpp.yaml# + + "pwrkey@[0-9a-f]+$": + type: object + $ref: /schemas/input/qcom,pm8921-pwrkey.yaml# + "rtc@[0-9a-f]+$": type: object - $ref: ../rtc/qcom-pm8xxx-rtc.yaml + $ref: /schemas/rtc/qcom-pm8xxx-rtc.yaml# + + "vibrator@[0-9a-f]+$": + type: object + $ref: /schemas/input/qcom,pm8xxx-vib.yaml# + + "xoadc@[0-9a-f]+$": + type: object + $ref: /schemas/iio/adc/qcom,pm8018-adc.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml index 4992f71b6fc3..44f8188360dd 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk805.yaml @@ -42,9 +42,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -80,6 +83,7 @@ properties: "^(DCDC_REG[1-4]|LDO_REG[1-3])$": type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false allOf: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml index cf2500f2e9a0..3c2b06629b75 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk806.yaml @@ -29,6 +29,8 @@ properties: '#gpio-cells': const: 2 + system-power-controller: true + vcc1-supply: description: The input supply for dcdc-reg1. diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml index f5908fa01a61..d2ac6fbd5ce6 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk808.yaml @@ -37,9 +37,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -107,6 +110,7 @@ properties: "^(DCDC_REG[1-4]|LDO_REG[1-8]|SWITCH_REG[1-2])$": type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false required: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml index 7fb849ac74a7..839c0521f1e5 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk809.yaml @@ -37,9 +37,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -86,7 +89,8 @@ properties: patternProperties: "^(LDO_REG[1-9]|DCDC_REG[1-5]|SWITCH_REG[1-2])$": type: object - $ref: ../regulator/regulator.yaml# + $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false allOf: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml index 269fb85b2027..92b1592e8942 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk817.yaml @@ -38,9 +38,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: diff --git a/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml b/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml index b57c4b005cf4..fd4b9de364aa 100644 --- a/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml +++ b/Documentation/devicetree/bindings/mfd/rockchip,rk818.yaml @@ -37,9 +37,12 @@ properties: rockchip,system-power-controller: type: boolean + deprecated: true description: Telling whether or not this PMIC is controlling the system power. + system-power-controller: true + wakeup-source: type: boolean description: @@ -99,6 +102,7 @@ properties: "^(DCDC_REG[1-4]|DCDC_BOOST|LDO_REG[1-9]|SWITCH_REG|HDMI_SWITCH|OTG_SWITCH)$": type: object $ref: ../regulator/regulator.yaml# + unevaluatedProperties: false unevaluatedProperties: false required: diff --git a/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml b/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml index 5e0002f099e4..cb2a42caabb5 100644 --- a/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml +++ b/Documentation/devicetree/bindings/mfd/stericsson,db8500-prcmu.yaml @@ -75,7 +75,7 @@ properties: unevaluatedProperties: false db8500_varm: - description: The voltage for the ARM Cortex A-9 CPU. + description: The voltage for the ARM Cortex-A9 CPU. type: object $ref: ../regulator/regulator.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 8103154bbb52..084b5c2a2a3c 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -49,6 +49,8 @@ properties: - hisilicon,peri-subctrl - hpe,gxp-sysreg - intel,lgm-syscon + - loongson,ls1b-syscon + - loongson,ls1c-syscon - marvell,armada-3700-usb2-host-misc - mediatek,mt8135-pctl-a-syscfg - mediatek,mt8135-pctl-b-syscfg @@ -61,6 +63,7 @@ properties: - rockchip,px30-qos - rockchip,rk3036-qos - rockchip,rk3066-qos + - rockchip,rk3128-qos - rockchip,rk3228-qos - rockchip,rk3288-qos - rockchip,rk3368-qos @@ -69,6 +72,7 @@ properties: - rockchip,rk3588-qos - rockchip,rv1126-qos - starfive,jh7100-sysmain + - ti,am654-dss-oldi-io-ctrl - const: syscon diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml index f6cac4b1079c..ae149eb8593d 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87524-q1.yaml @@ -37,6 +37,7 @@ properties: "^buck[0123]$": type: object $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false required: - buck0 diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml index dc5a29b5ef7d..5167d6eb904a 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87561-q1.yaml @@ -41,6 +41,7 @@ properties: buck3210: type: object $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false required: - buck3210 diff --git a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml index 012d25111054..eca430edf608 100644 --- a/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml +++ b/Documentation/devicetree/bindings/mfd/ti,lp87565-q1.yaml @@ -47,6 +47,7 @@ properties: "^buck(10|23)$": type: object $ref: /schemas/regulator/regulator.yaml# + unevaluatedProperties: false required: - buck10 diff --git a/Documentation/devicetree/bindings/mfd/ti,twl.yaml b/Documentation/devicetree/bindings/mfd/ti,twl.yaml new file mode 100644 index 000000000000..c04d57ba22b4 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ti,twl.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/ti,twl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments TWL family + +maintainers: + - Andreas Kemnade <andreas@kemnade.info> + +description: | + The TWLs are Integrated Power Management Chips. + Some version might contain much more analog function like + USB transceiver or Audio amplifier. + These chips are connected to an i2c bus. + +properties: + compatible: + description: + TWL4030 for integrated power-management/audio CODEC device used in OMAP3 + based boards + TWL6030/32 for integrated power-management used in OMAP4 based boards + enum: + - ti,twl4030 + - ti,twl6030 + - ti,twl6032 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + "#interrupt-cells": + const: 1 + + "#clock-cells": + const: 1 + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - "#interrupt-cells" + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@48 { + compatible = "ti,twl6030"; + reg = <0x48>; + interrupts = <39>; /* IRQ_SYS_1N cascaded to gic */ + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + }; + }; + diff --git a/Documentation/devicetree/bindings/mfd/twl-family.txt b/Documentation/devicetree/bindings/mfd/twl-family.txt deleted file mode 100644 index c2f9302965de..000000000000 --- a/Documentation/devicetree/bindings/mfd/twl-family.txt +++ /dev/null @@ -1,46 +0,0 @@ -Texas Instruments TWL family - -The TWLs are Integrated Power Management Chips. -Some version might contain much more analog function like -USB transceiver or Audio amplifier. -These chips are connected to an i2c bus. - - -Required properties: -- compatible : Must be "ti,twl4030"; - For Integrated power-management/audio CODEC device used in OMAP3 - based boards -- compatible : Must be "ti,twl6030"; - For Integrated power-management used in OMAP4 based boards -- interrupts : This i2c device has an IRQ line connected to the main SoC -- interrupt-controller : Since the twl support several interrupts internally, - it is considered as an interrupt controller cascaded to the SoC one. -- #interrupt-cells = <1>; - -Optional node: -- Child nodes contain in the twl. The twl family is made of several variants - that support a different number of features. - The children nodes will thus depend of the capability of the variant. - - -Example: -/* - * Integrated Power Management Chip - * https://www.ti.com/lit/ds/symlink/twl6030.pdf - */ -twl@48 { - compatible = "ti,twl6030"; - reg = <0x48>; - interrupts = <39>; /* IRQ_SYS_1N cascaded to gic */ - interrupt-controller; - #interrupt-cells = <1>; - interrupt-parent = <&gic>; - #address-cells = <1>; - #size-cells = <0>; - - twl_rtc { - compatible = "ti,twl_rtc"; - interrupts = <11>; - reg = <0>; - }; -}; diff --git a/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml b/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml index 9ad55746133b..06f1779835a1 100644 --- a/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml +++ b/Documentation/devicetree/bindings/mfd/x-powers,axp152.yaml @@ -67,7 +67,10 @@ allOf: properties: compatible: contains: - const: x-powers,axp305 + enum: + - x-powers,axp15060 + - x-powers,axp305 + - x-powers,axp313a then: required: diff --git a/Documentation/devicetree/bindings/mmc/npcm,sdhci.yaml b/Documentation/devicetree/bindings/mmc/npcm,sdhci.yaml new file mode 100644 index 000000000000..196fdbfa16ed --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/npcm,sdhci.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mmc/npcm,sdhci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NPCM SDHCI Controller + +maintainers: + - Tomer Maimon <tmaimon77@gmail.com> + +allOf: + - $ref: mmc-controller.yaml# + +properties: + compatible: + enum: + - nuvoton,npcm750-sdhci + - nuvoton,npcm845-sdhci + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +unevaluatedProperties: false + +examples: + - | + mmc@f0840000 { + compatible = "nuvoton,npcm750-sdhci"; + reg = <0xf0840000 0x200>; + interrupts = <0 27 4>; + clocks = <&clk 4>; + }; diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index 7756a8687eaf..94e228787630 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -59,6 +59,7 @@ properties: - renesas,sdhi-r9a07g043 # RZ/G2UL - renesas,sdhi-r9a07g044 # RZ/G2{L,LC} - renesas,sdhi-r9a07g054 # RZ/V2L + - renesas,sdhi-r9a08g045 # RZ/G3S - renesas,sdhi-r9a09g011 # RZ/V2M - const: renesas,rcar-gen3-sdhi # R-Car Gen3 or RZ/G2 - items: @@ -122,6 +123,7 @@ allOf: - renesas,sdhi-r9a07g043 - renesas,sdhi-r9a07g044 - renesas,sdhi-r9a07g054 + - renesas,sdhi-r9a08g045 - renesas,sdhi-r9a09g011 then: properties: diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml index 10f34aa8ba8a..86fae733d9a0 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.yaml @@ -58,6 +58,7 @@ properties: - qcom,sm8350-sdhci - qcom,sm8450-sdhci - qcom,sm8550-sdhci + - qcom,sm8650-sdhci - const: qcom,sdhci-msm-v5 # for sdcc version 5.0 reg: @@ -85,10 +86,10 @@ properties: - const: iface - const: core - const: xo - - const: ice - - const: bus - - const: cal - - const: sleep + - enum: [ice, bus, cal, sleep] + - enum: [ice, bus, cal, sleep] + - enum: [ice, bus, cal, sleep] + - enum: [ice, bus, cal, sleep] dma-coherent: true diff --git a/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml b/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml index 51e1b04e799f..553a75195c2e 100644 --- a/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml +++ b/Documentation/devicetree/bindings/mmc/starfive,jh7110-mmc.yaml @@ -55,7 +55,6 @@ required: - clocks - clock-names - interrupts - - starfive,sysreg unevaluatedProperties: false @@ -73,5 +72,4 @@ examples: fifo-depth = <32>; fifo-watermark-aligned; data-addr = <0>; - starfive,sysreg = <&sys_syscon 0x14 0x1a 0x7c000000>; }; diff --git a/Documentation/devicetree/bindings/mtd/mtd.yaml b/Documentation/devicetree/bindings/mtd/mtd.yaml index b82ca03e969c..f322290ee516 100644 --- a/Documentation/devicetree/bindings/mtd/mtd.yaml +++ b/Documentation/devicetree/bindings/mtd/mtd.yaml @@ -43,7 +43,12 @@ patternProperties: deprecated: true "^otp(-[0-9]+)?$": - $ref: ../nvmem/nvmem.yaml# + type: object + + allOf: + - $ref: ../nvmem/nvmem.yaml# + - $ref: ../nvmem/nvmem-deprecated-cells.yaml# + unevaluatedProperties: false description: | diff --git a/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml b/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml index 331e564f29dc..058253d6d889 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml @@ -29,6 +29,24 @@ properties: "#size-cells": true + compression: + $ref: /schemas/types.yaml#/definitions/string + description: | + Compression algorithm used to store the data in this partition, chosen + from a list of well-known algorithms. + + The contents are compressed using this algorithm. + + enum: + - none + - bzip2 + - gzip + - lzop + - lz4 + - lzma + - xz + - zstd + patternProperties: "@[0-9a-f]+$": $ref: partition.yaml# @@ -64,6 +82,7 @@ examples: uimage@100000 { reg = <0x0100000 0x200000>; + compress = "lzma"; }; }; diff --git a/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml index 5474d63268dc..9518281007af 100644 --- a/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml +++ b/Documentation/devicetree/bindings/mtd/partitions/nvmem-cells.yaml @@ -19,6 +19,7 @@ maintainers: allOf: - $ref: /schemas/mtd/partitions/partition.yaml# - $ref: /schemas/nvmem/nvmem.yaml# + - $ref: /schemas/nvmem/nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml index 4bfac9186886..7fe0352dff0f 100644 --- a/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml +++ b/Documentation/devicetree/bindings/net/allwinner,sun8i-a83t-emac.yaml @@ -158,6 +158,8 @@ allOf: patternProperties: "^ethernet-phy@[0-9a-f]$": type: object + $ref: ethernet-phy.yaml# + unevaluatedProperties: false description: Integrated PHY node diff --git a/Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml b/Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml index aa3162c74833..75d8138298fb 100644 --- a/Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml +++ b/Documentation/devicetree/bindings/net/brcm,asp-v2.0.yaml @@ -53,7 +53,7 @@ properties: const: 0 patternProperties: - "^port@[0-9]+$": + "^port@[0-9a-f]+$": type: object $ref: ethernet-controller.yaml# diff --git a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml index b06c416893ff..f21bdd0f408d 100644 --- a/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml +++ b/Documentation/devicetree/bindings/net/dsa/brcm,sf2.yaml @@ -78,6 +78,7 @@ properties: ports: type: object + additionalProperties: true patternProperties: '^port@[0-9a-f]$': diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.yaml b/Documentation/devicetree/bindings/net/dsa/dsa.yaml index ec74a660beda..6107189d276a 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.yaml +++ b/Documentation/devicetree/bindings/net/dsa/dsa.yaml @@ -40,17 +40,8 @@ $defs: patternProperties: "^(ethernet-)?ports$": - type: object - additionalProperties: false - - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 - patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-9a-f]+$": description: Ethernet switch ports $ref: dsa-port.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml index e532c6b795f4..1c2444121e60 100644 --- a/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml +++ b/Documentation/devicetree/bindings/net/dsa/mediatek,mt7530.yaml @@ -60,7 +60,7 @@ description: | Check out example 6. - - Port 5 can be wired to an external phy. Port 5 becomes a DSA slave. + - Port 5 can be wired to an external phy. Port 5 becomes a DSA user port. For the multi-chip module MT7530, the external phy must be wired TX to TX to gmac1 of the SoC for this to work. Ubiquiti EdgeRouter X SFP is wired @@ -154,10 +154,12 @@ properties: patternProperties: "^(ethernet-)?ports$": type: object + additionalProperties: true patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-6]$": type: object + additionalProperties: true properties: reg: @@ -184,7 +186,7 @@ $defs: patternProperties: "^(ethernet-)?ports$": patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-6]$": if: required: [ ethernet ] then: @@ -210,7 +212,7 @@ $defs: patternProperties: "^(ethernet-)?ports$": patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-6]$": if: required: [ ethernet ] then: diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml index 03b5567be389..b3029c64d0d5 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml @@ -38,6 +38,8 @@ properties: Should be a gpio specifier for a reset line. maxItems: 1 + wakeup-source: true + microchip,synclko-125: $ref: /schemas/types.yaml#/definitions/flag description: @@ -49,6 +51,26 @@ properties: Set if the output SYNCLKO clock should be disabled. Do not mix with microchip,synclko-125. + microchip,io-drive-strength-microamp: + description: + IO Pad Drive Strength + enum: [8000, 16000] + default: 16000 + + microchip,hi-drive-strength-microamp: + description: + High Speed Drive Strength. Controls drive strength of GMII / RGMII / + MII / RMII (except TX_CLK/REFCLKI, COL and CRS) and CLKO_25_125 lines. + enum: [2000, 4000, 8000, 12000, 16000, 20000, 24000, 28000] + default: 24000 + + microchip,lo-drive-strength-microamp: + description: + Low Speed Drive Strength. Controls drive strength of TX_CLK / REFCLKI, + COL, CRS, LEDs, PME_N, NTRP_N, SDO and SDI/SDA/MDIO lines. + enum: [2000, 4000, 8000, 12000, 16000, 20000, 24000, 28000] + default: 8000 + interrupts: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml index 8d7e878b84dc..9973d64f15a7 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,lan937x.yaml @@ -37,8 +37,9 @@ properties: patternProperties: "^(ethernet-)?ports$": + additionalProperties: true patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-7]$": allOf: - if: properties: diff --git a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml index 4d5f5cc6d031..9432565f4f5d 100644 --- a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml +++ b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml @@ -43,6 +43,7 @@ properties: # PHY 1. mdios: type: object + additionalProperties: false properties: '#address-cells': @@ -74,8 +75,9 @@ properties: patternProperties: "^(ethernet-)?ports$": + additionalProperties: true patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-9]$": allOf: - if: properties: diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml index df64eebebe18..167398ab253a 100644 --- a/Documentation/devicetree/bindings/net/dsa/qca8k.yaml +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.yaml @@ -73,6 +73,7 @@ $ref: dsa.yaml# patternProperties: "^(ethernet-)?ports$": type: object + additionalProperties: true patternProperties: "^(ethernet-)?port@[0-6]$": type: object diff --git a/Documentation/devicetree/bindings/net/dsa/realtek.yaml b/Documentation/devicetree/bindings/net/dsa/realtek.yaml index cfd69c2604ea..cce692f57b08 100644 --- a/Documentation/devicetree/bindings/net/dsa/realtek.yaml +++ b/Documentation/devicetree/bindings/net/dsa/realtek.yaml @@ -68,6 +68,8 @@ properties: interrupt-controller: type: object + additionalProperties: false + description: | This defines an interrupt controller with an IRQ line (typically a GPIO) that will demultiplex and handle the interrupt from the single diff --git a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml index 833d2f68daa1..ea285ef3e64f 100644 --- a/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml +++ b/Documentation/devicetree/bindings/net/dsa/renesas,rzn1-a5psw.yaml @@ -61,17 +61,11 @@ properties: ethernet-ports: type: object - properties: - '#address-cells': - const: 1 - '#size-cells': - const: 0 - + additionalProperties: true patternProperties: "^(ethernet-)?port@[0-4]$": type: object - description: Ethernet switch ports - + additionalProperties: true properties: pcs-handle: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml index 82a5d7927ca4..34fd24ff6a71 100644 --- a/Documentation/devicetree/bindings/net/engleder,tsnep.yaml +++ b/Documentation/devicetree/bindings/net/engleder,tsnep.yaml @@ -63,6 +63,7 @@ properties: mdio: type: object $ref: mdio.yaml# + unevaluatedProperties: false description: optional node for embedded MDIO controller required: diff --git a/Documentation/devicetree/bindings/net/ethernet-switch.yaml b/Documentation/devicetree/bindings/net/ethernet-switch.yaml index f1b9075dc7fb..72ac67ca3415 100644 --- a/Documentation/devicetree/bindings/net/ethernet-switch.yaml +++ b/Documentation/devicetree/bindings/net/ethernet-switch.yaml @@ -36,7 +36,7 @@ patternProperties: const: 0 patternProperties: - "^(ethernet-)?port@[0-9]+$": + "^(ethernet-)?port@[0-9a-f]+$": type: object description: Ethernet switch ports @@ -53,14 +53,16 @@ oneOf: additionalProperties: true $defs: - base: + ethernet-ports: description: An ethernet switch without any extra port properties $ref: '#' patternProperties: - "^(ethernet-)?port@[0-9]+$": - description: Ethernet switch ports - $ref: ethernet-switch-port.yaml# - unevaluatedProperties: false + "^(ethernet-)?ports$": + patternProperties: + "^(ethernet-)?port@[0-9a-f]+$": + description: Ethernet switch ports + $ref: ethernet-switch-port.yaml# + unevaluatedProperties: false ... diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index b494e009326e..8948a11c994e 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -59,6 +59,7 @@ properties: - const: fsl,imx6sx-fec - items: - enum: + - fsl,imx8dxl-fec - fsl,imx8qxp-fec - const: fsl,imx8qm-fec - const: fsl,imx6sx-fec diff --git a/Documentation/devicetree/bindings/net/loongson,ls1b-gmac.yaml b/Documentation/devicetree/bindings/net/loongson,ls1b-gmac.yaml new file mode 100644 index 000000000000..c4f3224bad38 --- /dev/null +++ b/Documentation/devicetree/bindings/net/loongson,ls1b-gmac.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/loongson,ls1b-gmac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-1B Gigabit Ethernet MAC Controller + +maintainers: + - Keguang Zhang <keguang.zhang@gmail.com> + +description: | + Loongson-1B Gigabit Ethernet MAC Controller is based on + Synopsys DesignWare MAC (version 3.50a). + + Main features + - Dual 10/100/1000Mbps GMAC controllers + - Full-duplex operation (IEEE 802.3x flow control automatic transmission) + - Half-duplex operation (CSMA/CD Protocol and back-pressure support) + - RX Checksum Offload + - TX Checksum insertion + - MII interface + - RGMII interface + +select: + properties: + compatible: + contains: + enum: + - loongson,ls1b-gmac + required: + - compatible + +properties: + compatible: + items: + - enum: + - loongson,ls1b-gmac + - const: snps,dwmac-3.50a + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: stmmaceth + + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: macirq + + loongson,ls1-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the syscon containing some extra configurations + including PHY interface mode. + + phy-mode: + enum: + - mii + - rgmii-id + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - interrupt-names + - loongson,ls1-syscon + +allOf: + - $ref: snps,dwmac.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/loongson,ls1x-clk.h> + #include <dt-bindings/interrupt-controller/irq.h> + + gmac0: ethernet@1fe10000 { + compatible = "loongson,ls1b-gmac", "snps,dwmac-3.50a"; + reg = <0x1fe10000 0x10000>; + + clocks = <&clkc LS1X_CLKID_AHB>; + clock-names = "stmmaceth"; + + interrupt-parent = <&intc1>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + + loongson,ls1-syscon = <&syscon>; + + phy-handle = <&phy0>; + phy-mode = "mii"; + snps,pbl = <1>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,dwmac-mdio"; + + phy0: ethernet-phy@0 { + reg = <0x0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/loongson,ls1c-emac.yaml b/Documentation/devicetree/bindings/net/loongson,ls1c-emac.yaml new file mode 100644 index 000000000000..99001b940b83 --- /dev/null +++ b/Documentation/devicetree/bindings/net/loongson,ls1c-emac.yaml @@ -0,0 +1,113 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/loongson,ls1c-emac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Loongson-1C Ethernet MAC Controller + +maintainers: + - Keguang Zhang <keguang.zhang@gmail.com> + +description: | + Loongson-1C Ethernet MAC Controller is based on + Synopsys DesignWare MAC (version 3.50a). + + Main features + - 10/100Mbps + - Full-duplex operation (IEEE 802.3x flow control automatic transmission) + - Half-duplex operation (CSMA/CD Protocol and back-pressure support) + - IEEE 802.1Q VLAN tag detection for reception frames + - MII interface + - RMII interface + +select: + properties: + compatible: + contains: + enum: + - loongson,ls1c-emac + required: + - compatible + +properties: + compatible: + items: + - enum: + - loongson,ls1c-emac + - const: snps,dwmac-3.50a + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + items: + - const: stmmaceth + + interrupts: + maxItems: 1 + + interrupt-names: + items: + - const: macirq + + loongson,ls1-syscon: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Phandle to the syscon containing some extra configurations + including PHY interface mode. + + phy-mode: + enum: + - mii + - rmii + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - interrupt-names + - loongson,ls1-syscon + +allOf: + - $ref: snps,dwmac.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/loongson,ls1x-clk.h> + #include <dt-bindings/interrupt-controller/irq.h> + + emac: ethernet@1fe10000 { + compatible = "loongson,ls1c-emac", "snps,dwmac-3.50a"; + reg = <0x1fe10000 0x10000>; + + clocks = <&clkc LS1X_CLKID_AHB>; + clock-names = "stmmaceth"; + + interrupt-parent = <&intc1>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq"; + + loongson,ls1-syscon = <&syscon>; + + phy-handle = <&phy0>; + phy-mode = "mii"; + snps,pbl = <1>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,dwmac-mdio"; + + phy0: ethernet-phy@13 { + reg = <0x13>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml b/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml index 77c9bbf987e1..accff93d38f8 100644 --- a/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml +++ b/Documentation/devicetree/bindings/net/microchip,lan95xx.yaml @@ -44,6 +44,8 @@ properties: local-mac-address: true mac-address: true + nvmem-cells: true + nvmem-cell-names: true required: - compatible diff --git a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml index 8ee2c7d7ff42..86a9c3fc76c8 100644 --- a/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml +++ b/Documentation/devicetree/bindings/net/mscc,vsc7514-switch.yaml @@ -24,7 +24,7 @@ allOf: compatible: const: mscc,vsc7514-switch then: - $ref: ethernet-switch.yaml# + $ref: ethernet-switch.yaml#/$defs/ethernet-ports required: - interrupts - interrupt-names @@ -33,28 +33,18 @@ allOf: minItems: 21 reg-names: minItems: 21 - ethernet-ports: - patternProperties: - "^port@[0-9a-f]+$": - $ref: ethernet-switch-port.yaml# - unevaluatedProperties: false - if: properties: compatible: const: mscc,vsc7512-switch then: - $ref: /schemas/net/dsa/dsa.yaml# + $ref: /schemas/net/dsa/dsa.yaml#/$defs/ethernet-ports properties: reg: maxItems: 20 reg-names: maxItems: 20 - ethernet-ports: - patternProperties: - "^port@[0-9a-f]+$": - $ref: /schemas/net/dsa/dsa-port.yaml# - unevaluatedProperties: false properties: compatible: @@ -185,7 +175,7 @@ examples: }; # VSC7512 (DSA) - | - ethernet-switch@1{ + ethernet-switch@1 { compatible = "mscc,vsc7512-switch"; reg = <0x71010000 0x10000>, <0x71030000 0x10000>, @@ -212,22 +202,22 @@ examples: "port7", "port8", "port9", "port10", "qsys", "ana", "s0", "s1", "s2"; - ethernet-ports { - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - reg = <0>; - ethernet = <&mac_sw>; - phy-handle = <&phy0>; - phy-mode = "internal"; - }; - port@1 { - reg = <1>; - phy-handle = <&phy1>; - phy-mode = "internal"; - }; + ethernet-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + ethernet = <&mac_sw>; + phy-handle = <&phy0>; + phy-mode = "internal"; + }; + port@1 { + reg = <1>; + phy-handle = <&phy1>; + phy-mode = "internal"; }; }; + }; ... diff --git a/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml b/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml index ab8867e6939b..85bfa45f5122 100644 --- a/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml +++ b/Documentation/devicetree/bindings/net/nxp,tja11xx.yaml @@ -20,6 +20,7 @@ allOf: patternProperties: "^ethernet-phy@[0-9a-f]+$": type: object + additionalProperties: false description: | Some packages have multiple PHYs. Secondary PHY should be defines as subnode of the first (parent) PHY. diff --git a/Documentation/devicetree/bindings/net/renesas,ether.yaml b/Documentation/devicetree/bindings/net/renesas,ether.yaml index 06b38c9bc6ec..29355ab98569 100644 --- a/Documentation/devicetree/bindings/net/renesas,ether.yaml +++ b/Documentation/devicetree/bindings/net/renesas,ether.yaml @@ -81,9 +81,8 @@ properties: active-high patternProperties: - "^ethernet-phy@[0-9a-f]$": + "@[0-9a-f]$": type: object - $ref: ethernet-phy.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml index 3f41294f5997..5d074f27d462 100644 --- a/Documentation/devicetree/bindings/net/renesas,etheravb.yaml +++ b/Documentation/devicetree/bindings/net/renesas,etheravb.yaml @@ -109,9 +109,8 @@ properties: enum: [0, 2000] patternProperties: - "^ethernet-phy@[0-9a-f]$": + "@[0-9a-f]$": type: object - $ref: ethernet-phy.yaml# required: - compatible diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index ddf9522a5dc2..5c2769dc689a 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -394,6 +394,11 @@ properties: When a PFC frame is received with priorities matching the bitmask, the queue is blocked from transmitting for the pause time specified in the PFC frame. + + snps,coe-unsupported: + type: boolean + description: TX checksum offload is unsupported by the TX queue. + allOf: - if: required: diff --git a/Documentation/devicetree/bindings/net/ti,cc1352p7.yaml b/Documentation/devicetree/bindings/net/ti,cc1352p7.yaml new file mode 100644 index 000000000000..3dde10de4630 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ti,cc1352p7.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/ti,cc1352p7.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments Simplelink CC1352P7 wireless MCU + +description: + The CC1352P7 MCU can be connected via SPI or UART. + +maintainers: + - Ayush Singh <ayushdevel1325@gmail.com> + +properties: + compatible: + const: ti,cc1352p7 + + clocks: + items: + - description: high-frequency main system (MCU and peripherals) clock + - description: low-frequency system clock + + clock-names: + items: + - const: sclk_hf + - const: sclk_lf + + reset-gpios: + maxItems: 1 + + vdds-supply: true + +required: + - compatible + +additionalProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + + serial { + mcu { + compatible = "ti,cc1352p7"; + clocks = <&sclk_hf 0>, <&sclk_lf 25>; + clock-names = "sclk_hf", "sclk_lf"; + reset-gpios = <&pio 35 GPIO_ACTIVE_LOW>; + vdds-supply = <&vdds>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml index b04ac4966608..f07ae3173b03 100644 --- a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml +++ b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml @@ -86,7 +86,7 @@ properties: const: 0 patternProperties: - "^port@[0-9]+$": + "^port@[12]$": type: object description: CPSW external ports diff --git a/Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml b/Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml index 311c570165f9..229c8f32019f 100644 --- a/Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml +++ b/Documentation/devicetree/bindings/net/ti,icssg-prueth.yaml @@ -19,6 +19,7 @@ allOf: properties: compatible: enum: + - ti,am642-icssg-prueth # for AM64x SoC family - ti,am654-icssg-prueth # for AM65x SoC family sram: @@ -106,6 +107,13 @@ properties: phandle to system controller node and register offset to ICSSG control register for RGMII transmit delay + ti,half-duplex-capable: + type: boolean + description: + Indicates that the PHY output pin COL is routed to ICSSG GPIO pin + (PRGx_PRU0/1_GPIO10) as input so that the ICSSG MII port is + capable of half duplex operations. + required: - reg anyOf: diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml index 296001e7f498..4424c3c5e75c 100644 --- a/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml +++ b/Documentation/devicetree/bindings/nvmem/allwinner,sun4i-a10-sid.yaml @@ -12,6 +12,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: @@ -23,7 +24,9 @@ properties: - const: allwinner,sun20i-d1-sid - const: allwinner,sun50i-a64-sid - items: - - const: allwinner,sun50i-a100-sid + - enum: + - allwinner,sun50i-a100-sid + - allwinner,sun50i-h616-sid - const: allwinner,sun50i-a64-sid - const: allwinner,sun50i-h5-sid - const: allwinner,sun50i-h6-sid diff --git a/Documentation/devicetree/bindings/nvmem/amlogic,meson-gxbb-efuse.yaml b/Documentation/devicetree/bindings/nvmem/amlogic,meson-gxbb-efuse.yaml index e49c2754ff55..9801fe6f91b5 100644 --- a/Documentation/devicetree/bindings/nvmem/amlogic,meson-gxbb-efuse.yaml +++ b/Documentation/devicetree/bindings/nvmem/amlogic,meson-gxbb-efuse.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/amlogic,meson6-efuse.yaml b/Documentation/devicetree/bindings/nvmem/amlogic,meson6-efuse.yaml index 84b3dfd21e09..b5cf740f96fa 100644 --- a/Documentation/devicetree/bindings/nvmem/amlogic,meson6-efuse.yaml +++ b/Documentation/devicetree/bindings/nvmem/amlogic,meson6-efuse.yaml @@ -12,6 +12,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/apple,efuses.yaml b/Documentation/devicetree/bindings/nvmem/apple,efuses.yaml index e0860b6b85f3..d3abdafdbca0 100644 --- a/Documentation/devicetree/bindings/nvmem/apple,efuses.yaml +++ b/Documentation/devicetree/bindings/nvmem/apple,efuses.yaml @@ -16,6 +16,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.yaml b/Documentation/devicetree/bindings/nvmem/imx-ocotp.yaml index 99e60d713dac..be1314454bec 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.yaml +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.yaml @@ -16,6 +16,7 @@ description: | allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/mediatek,efuse.yaml b/Documentation/devicetree/bindings/nvmem/mediatek,efuse.yaml index 7ec2988b597e..cf5f9e22bb7e 100644 --- a/Documentation/devicetree/bindings/nvmem/mediatek,efuse.yaml +++ b/Documentation/devicetree/bindings/nvmem/mediatek,efuse.yaml @@ -16,6 +16,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: $nodename: diff --git a/Documentation/devicetree/bindings/nvmem/microchip,sama7g5-otpc.yaml b/Documentation/devicetree/bindings/nvmem/microchip,sama7g5-otpc.yaml index a296d348adb4..cc25f2927682 100644 --- a/Documentation/devicetree/bindings/nvmem/microchip,sama7g5-otpc.yaml +++ b/Documentation/devicetree/bindings/nvmem/microchip,sama7g5-otpc.yaml @@ -16,6 +16,7 @@ description: | allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml b/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml index a9b822aeaa7e..f43186f98607 100644 --- a/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml +++ b/Documentation/devicetree/bindings/nvmem/mxs-ocotp.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/nvmem-deprecated-cells.yaml b/Documentation/devicetree/bindings/nvmem/nvmem-deprecated-cells.yaml new file mode 100644 index 000000000000..951af28bbfb3 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/nvmem-deprecated-cells.yaml @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/nvmem-deprecated-cells.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVMEM old syntax for fixed cells + +maintainers: + - Srinivas Kandagatla <srinivas.kandagatla@linaro.org> + +description: | + Before introducing NVMEM layouts all NVMEM (fixed) cells were defined + as direct device subnodes. That syntax was replaced by "fixed-layout" + and is deprecated now. No new bindings should use it. + +patternProperties: + "@[0-9a-f]+(,[0-7])?$": + type: object + allOf: + - $ref: layouts/fixed-cell.yaml + - properties: + compatible: false + deprecated: true + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/nvmem/nvmem.yaml b/Documentation/devicetree/bindings/nvmem/nvmem.yaml index 9f921d940142..4fd015d402ce 100644 --- a/Documentation/devicetree/bindings/nvmem/nvmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/nvmem.yaml @@ -46,15 +46,6 @@ properties: container may reference more advanced (dynamic) layout parsers. -patternProperties: - "@[0-9a-f]+(,[0-7])?$": - type: object - allOf: - - $ref: layouts/fixed-cell.yaml - - properties: - compatible: false - deprecated: true - additionalProperties: true examples: diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml index 8740938c32eb..8c8f05d9eaf1 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml index 9b133f783d29..2ada2099946d 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,sec-qfprom.yaml @@ -16,6 +16,7 @@ description: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml b/Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml index cd980def97b8..068bedf5dbc9 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml @@ -16,6 +16,7 @@ description: | allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/rockchip,otp.yaml b/Documentation/devicetree/bindings/nvmem/rockchip,otp.yaml index 9c6eff788928..a44d44b32809 100644 --- a/Documentation/devicetree/bindings/nvmem/rockchip,otp.yaml +++ b/Documentation/devicetree/bindings/nvmem/rockchip,otp.yaml @@ -49,6 +49,7 @@ required: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# - if: properties: diff --git a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.yaml b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.yaml index c5403e149080..b80fd8d1ae5b 100644 --- a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.yaml +++ b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.yaml @@ -11,6 +11,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml b/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml index efccc5aacbe0..e27cbae2d63a 100644 --- a/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml +++ b/Documentation/devicetree/bindings/nvmem/socionext,uniphier-efuse.yaml @@ -12,6 +12,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/sunplus,sp7021-ocotp.yaml b/Documentation/devicetree/bindings/nvmem/sunplus,sp7021-ocotp.yaml index da3f1de7d281..af97eeb8316c 100644 --- a/Documentation/devicetree/bindings/nvmem/sunplus,sp7021-ocotp.yaml +++ b/Documentation/devicetree/bindings/nvmem/sunplus,sp7021-ocotp.yaml @@ -12,6 +12,7 @@ maintainers: allOf: - $ref: nvmem.yaml# + - $ref: nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml b/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml index 36d97fb87865..9c36afc7084b 100644 --- a/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml +++ b/Documentation/devicetree/bindings/nvmem/u-boot,env.yaml @@ -51,6 +51,8 @@ properties: ethaddr: type: object description: Ethernet interfaces base MAC address. + additionalProperties: false + properties: "#nvmem-cell-cells": description: The first argument is a MAC address offset. diff --git a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml index bbbad31ae4ca..fd04d060c1de 100644 --- a/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml +++ b/Documentation/devicetree/bindings/opp/opp-v2-kryo-cpu.yaml @@ -26,7 +26,9 @@ description: | properties: compatible: - const: operating-points-v2-kryo-cpu + enum: + - operating-points-v2-krait-cpu + - operating-points-v2-kryo-cpu nvmem-cells: description: | @@ -47,6 +49,8 @@ patternProperties: opp-microvolt: true + opp-peak-kBps: true + opp-supported-hw: description: | A single 32 bit bitmap value, representing compatible HW. @@ -63,14 +67,22 @@ patternProperties: 5: MSM8996SG, speedbin 1 6: MSM8996SG, speedbin 2 7-31: unused - enum: [0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, - 0x9, 0xd, 0xe, 0xf, - 0x10, 0x20, 0x30, 0x70] + + Bitmap for IPQ806x SoC: + 0: IPQ8062 + 1: IPQ8064/IPQ8066/IPQ8068 + 2: IPQ8065/IPQ8069 + 3-31: unused + + Other platforms use bits directly corresponding to speedbin index. clock-latency-ns: true required-opps: true + patternProperties: + '^opp-microvolt-speed[0-9]+-pvs[0-9]+$': true + required: - opp-hz @@ -256,6 +268,22 @@ examples: }; }; + /* Dummy opp table to give example for named opp-microvolt */ + opp-table-2 { + compatible = "operating-points-v2-krait-cpu"; + nvmem-cells = <&speedbin_efuse>; + + opp-384000000 { + opp-hz = /bits/ 64 <384000000>; + opp-microvolt-speed0-pvs0 = <1000000 950000 1050000>; + opp-microvolt-speed0-pvs1 = <925000 878750 971250>; + opp-microvolt-speed0-pvs2 = <875000 831250 918750>; + opp-microvolt-speed0-pvs3 = <800000 760000 840000>; + opp-supported-hw = <0x7>; + clock-latency-ns = <100000>; + }; + }; + smem { compatible = "qcom,smem"; memory-region = <&smem_mem>; diff --git a/Documentation/devicetree/bindings/pci/rcar-gen4-pci-ep.yaml b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-ep.yaml new file mode 100644 index 000000000000..fe38f62da066 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-ep.yaml @@ -0,0 +1,115 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/rcar-gen4-pci-ep.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen4 PCIe Endpoint + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +allOf: + - $ref: snps,dw-pcie-ep.yaml# + +properties: + compatible: + items: + - const: renesas,r8a779f0-pcie-ep # R-Car S4-8 + - const: renesas,rcar-gen4-pcie-ep # R-Car Gen4 + + reg: + maxItems: 7 + + reg-names: + items: + - const: dbi + - const: dbi2 + - const: atu + - const: dma + - const: app + - const: phy + - const: addr_space + + interrupts: + maxItems: 3 + + interrupt-names: + items: + - const: dma + - const: sft_ce + - const: app + + clocks: + maxItems: 2 + + clock-names: + items: + - const: core + - const: ref + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + items: + - const: pwr + + max-link-speed: + maximum: 4 + + num-lanes: + maximum: 4 + + max-functions: + maximum: 2 + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - resets + - reset-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a779f0-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a779f0-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pcie0_ep: pcie-ep@e65d0000 { + compatible = "renesas,r8a779f0-pcie-ep", "renesas,rcar-gen4-pcie-ep"; + reg = <0 0xe65d0000 0 0x2000>, <0 0xe65d2000 0 0x1000>, + <0 0xe65d3000 0 0x2000>, <0 0xe65d5000 0 0x1200>, + <0 0xe65d6200 0 0x0e00>, <0 0xe65d7000 0 0x0400>, + <0 0xfe000000 0 0x400000>; + reg-names = "dbi", "dbi2", "atu", "dma", "app", "phy", "addr_space"; + interrupts = <GIC_SPI 417 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 418 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 422 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "dma", "sft_ce", "app"; + clocks = <&cpg CPG_MOD 624>, <&pcie0_clkref>; + clock-names = "core", "ref"; + power-domains = <&sysc R8A779F0_PD_ALWAYS_ON>; + resets = <&cpg 624>; + reset-names = "pwr"; + max-link-speed = <4>; + num-lanes = <2>; + max-functions = /bits/ 8 <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/rcar-gen4-pci-host.yaml b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-host.yaml new file mode 100644 index 000000000000..ffb34339b637 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rcar-gen4-pci-host.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (C) 2022-2023 Renesas Electronics Corp. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/rcar-gen4-pci-host.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas R-Car Gen4 PCIe Host + +maintainers: + - Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com> + +allOf: + - $ref: snps,dw-pcie.yaml# + +properties: + compatible: + items: + - const: renesas,r8a779f0-pcie # R-Car S4-8 + - const: renesas,rcar-gen4-pcie # R-Car Gen4 + + reg: + maxItems: 7 + + reg-names: + items: + - const: dbi + - const: dbi2 + - const: atu + - const: dma + - const: app + - const: phy + - const: config + + interrupts: + maxItems: 4 + + interrupt-names: + items: + - const: msi + - const: dma + - const: sft_ce + - const: app + + clocks: + maxItems: 2 + + clock-names: + items: + - const: core + - const: ref + + power-domains: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + items: + - const: pwr + + max-link-speed: + maximum: 4 + + num-lanes: + maximum: 4 + +required: + - compatible + - reg + - reg-names + - interrupts + - interrupt-names + - clocks + - clock-names + - power-domains + - resets + - reset-names + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/r8a779f0-cpg-mssr.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/r8a779f0-sysc.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pcie: pcie@e65d0000 { + compatible = "renesas,r8a779f0-pcie", "renesas,rcar-gen4-pcie"; + reg = <0 0xe65d0000 0 0x1000>, <0 0xe65d2000 0 0x0800>, + <0 0xe65d3000 0 0x2000>, <0 0xe65d5000 0 0x1200>, + <0 0xe65d6200 0 0x0e00>, <0 0xe65d7000 0 0x0400>, + <0 0xfe000000 0 0x400000>; + reg-names = "dbi", "dbi2", "atu", "dma", "app", "phy", "config"; + interrupts = <GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 417 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 418 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 422 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "msi", "dma", "sft_ce", "app"; + clocks = <&cpg CPG_MOD 624>, <&pcie0_clkref>; + clock-names = "core", "ref"; + power-domains = <&sysc R8A779F0_PD_ALWAYS_ON>; + resets = <&cpg 624>; + reset-names = "pwr"; + max-link-speed = <4>; + num-lanes = <2>; + #address-cells = <3>; + #size-cells = <2>; + bus-range = <0x00 0xff>; + device_type = "pci"; + ranges = <0x01000000 0 0x00000000 0 0xfe000000 0 0x00400000>, + <0x02000000 0 0x30000000 0 0x30000000 0 0x10000000>; + dma-ranges = <0x42000000 0 0x00000000 0 0x00000000 1 0x00000000>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 2 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 3 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <0 0 0 4 &gic GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>; + snps,enable-cdm-check; + }; + }; diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml index d87e13496834..dc05761c5cf9 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-common.yaml @@ -33,11 +33,11 @@ properties: specific for each activated function, while the rest of the sub-spaces are common for all of them (if there are more than one). minItems: 2 - maxItems: 6 + maxItems: 7 reg-names: minItems: 2 - maxItems: 6 + maxItems: 7 interrupts: description: diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml index 8fc2151691a4..bbdb01d22848 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie-ep.yaml @@ -33,11 +33,11 @@ properties: normal controller functioning. iATU memory IO region is also required if the space is unrolled (IP-core version >= 4.80a). minItems: 2 - maxItems: 5 + maxItems: 7 reg-names: minItems: 2 - maxItems: 5 + maxItems: 7 items: oneOf: - description: diff --git a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml index 8bbdeb8821f8..022055edbf9e 100644 --- a/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/snps,dw-pcie.yaml @@ -42,11 +42,11 @@ properties: are required for the normal controller work. iATU memory IO region is also required if the space is unrolled (IP-core version >= 4.80a). minItems: 2 - maxItems: 5 + maxItems: 7 reg-names: minItems: 2 - maxItems: 5 + maxItems: 7 items: oneOf: - description: diff --git a/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml b/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml index 897602559b37..426f90a47f35 100644 --- a/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml +++ b/Documentation/devicetree/bindings/pci/xlnx,nwl-pcie.yaml @@ -118,7 +118,7 @@ examples: compatible = "xlnx,nwl-pcie-2.11"; reg = <0x0 0xfd0e0000 0x0 0x1000>, <0x0 0xfd480000 0x0 0x1000>, - <0x80 0x00000000 0x0 0x1000000>; + <0x80 0x00000000 0x0 0x10000000>; reg-names = "breg", "pcireg", "cfg"; ranges = <0x02000000 0x0 0xe0000000 0x0 0xe0000000 0x0 0x10000000>, <0x43000000 0x00000006 0x0 0x00000006 0x0 0x00000002 0x0>; diff --git a/Documentation/devicetree/bindings/pci/xlnx,xdma-host.yaml b/Documentation/devicetree/bindings/pci/xlnx,xdma-host.yaml new file mode 100644 index 000000000000..0aa00b8e49b3 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/xlnx,xdma-host.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pci/xlnx,xdma-host.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx XDMA PL PCIe Root Port Bridge + +maintainers: + - Thippeswamy Havalige <thippeswamy.havalige@amd.com> + +allOf: + - $ref: /schemas/pci/pci-bus.yaml# + +properties: + compatible: + const: xlnx,xdma-host-3.00 + + reg: + maxItems: 1 + + ranges: + maxItems: 2 + + interrupts: + items: + - description: interrupt asserted when miscellaneous interrupt is received. + - description: msi0 interrupt asserted when an MSI is received. + - description: msi1 interrupt asserted when an MSI is received. + + interrupt-names: + items: + - const: misc + - const: msi0 + - const: msi1 + + interrupt-map-mask: + items: + - const: 0 + - const: 0 + - const: 0 + - const: 7 + + interrupt-map: + maxItems: 4 + + "#interrupt-cells": + const: 1 + + interrupt-controller: + description: identifies the node as an interrupt controller + type: object + properties: + interrupt-controller: true + + "#address-cells": + const: 0 + + "#interrupt-cells": + const: 1 + + required: + - interrupt-controller + - "#address-cells" + - "#interrupt-cells" + + additionalProperties: false + +required: + - compatible + - reg + - ranges + - interrupts + - interrupt-map + - interrupt-map-mask + - "#interrupt-cells" + - interrupt-controller + +unevaluatedProperties: false + +examples: + + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/interrupt-controller/irq.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + pcie@a0000000 { + compatible = "xlnx,xdma-host-3.00"; + reg = <0x0 0xa0000000 0x0 0x10000000>; + ranges = <0x2000000 0x0 0xb0000000 0x0 0xb0000000 0x0 0x1000000>, + <0x43000000 0x5 0x0 0x5 0x0 0x0 0x1000000>; + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + device_type = "pci"; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 89 IRQ_TYPE_LEVEL_HIGH>, <GIC_SPI 90 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 91 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "misc", "msi0", "msi1"; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + interrupt-map = <0 0 0 1 &pcie_intc_0 0>, + <0 0 0 2 &pcie_intc_0 1>, + <0 0 0 3 &pcie_intc_0 2>, + <0 0 0 4 &pcie_intc_0 3>; + pcie_intc_0: interrupt-controller { + #address-cells = <0>; + #interrupt-cells = <1>; + interrupt-controller; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/marvell,pxa1928-usb-phy.yaml b/Documentation/devicetree/bindings/phy/marvell,pxa1928-usb-phy.yaml new file mode 100644 index 000000000000..be33f036cda8 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/marvell,pxa1928-usb-phy.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/marvell,pxa1928-usb-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell PXA1928 USB/HSIC PHY + +maintainers: + - Duje Mihanović <duje.mihanovic@skole.hr> + +properties: + compatible: + enum: + - marvell,pxa1928-usb-phy + - marvell,pxa1928-hsic-phy + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + '#phy-cells': + const: 0 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - '#phy-cells' + +additionalProperties: false + +examples: + - | + #include <dt-bindings/clock/marvell,pxa1928.h> + + usbphy: phy@7000 { + compatible = "marvell,pxa1928-usb-phy"; + reg = <0x7000 0xe0>; + clocks = <&apmu PXA1928_CLK_USB>; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml b/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml index a63b20dfa4a5..6703689fcdbe 100644 --- a/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml +++ b/Documentation/devicetree/bindings/phy/mediatek,dsi-phy.yaml @@ -30,6 +30,7 @@ properties: - const: mediatek,mt8173-mipi-tx - items: - enum: + - mediatek,mt8188-mipi-tx - mediatek,mt8365-mipi-tx - const: mediatek,mt8183-mipi-tx - const: mediatek,mt2701-mipi-tx diff --git a/Documentation/devicetree/bindings/phy/mediatek,mt7628-usbphy.yaml b/Documentation/devicetree/bindings/phy/mediatek,mt7628-usbphy.yaml new file mode 100644 index 000000000000..ce2c228e3216 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/mediatek,mt7628-usbphy.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/mediatek,mt7628-usbphy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek/Ralink USB PHY + +maintainers: + - Sergio Paracuellos <sergio.paracuellos@gmail.com> + +properties: + compatible: + enum: + - mediatek,mt7620-usbphy + - mediatek,mt7628-usbphy + - ralink,rt3352-usbphy + + reg: + maxItems: 1 + + "#phy-cells": + const: 0 + + ralink,sysctl: + description: + phandle to a ralink syscon register region. + $ref: /schemas/types.yaml#/definitions/phandle + + resets: + items: + - description: USB Host reset controller + - description: USB Device reset controller + + reset-names: + items: + - const: host + - const: device + +required: + - compatible + - "#phy-cells" + - ralink,sysctl + - resets + - reset-names + +allOf: + - if: + properties: + compatible: + contains: + const: mediatek,mt7628-usbphy + then: + required: + - reg + else: + properties: + reg: false + +additionalProperties: false + +examples: + - | + phy@10120000 { + compatible = "mediatek,mt7628-usbphy"; + reg = <0x10120000 0x1000>; + #phy-cells = <0>; + ralink,sysctl = <&sysc>; + resets = <&rstctrl 22>, + <&rstctrl 25>; + reset-names = "host", "device"; + }; + +... diff --git a/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt b/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt deleted file mode 100644 index 35f03df00130..000000000000 --- a/Documentation/devicetree/bindings/phy/phy-stih407-usb.txt +++ /dev/null @@ -1,24 +0,0 @@ -ST STiH407 USB PHY controller - -This file documents the dt bindings for the usb picoPHY driver which is the PHY for both USB2 and USB3 -host controllers (when controlling usb2/1.1 devices) available on STiH407 SoC family from STMicroelectronics. - -Required properties: -- compatible : should be "st,stih407-usb2-phy" -- st,syscfg : phandle of sysconfig bank plus integer array containing phyparam and phyctrl register offsets -- resets : list of phandle and reset specifier pairs. There should be two entries, one - for the whole phy and one for the port -- reset-names : list of reset signal names. Should be "global" and "port" -See: Documentation/devicetree/bindings/reset/st,stih407-powerdown.yaml -See: Documentation/devicetree/bindings/reset/reset.txt - -Example: - -usb2_picophy0: usbpicophy@f8 { - compatible = "st,stih407-usb2-phy"; - #phy-cells = <0>; - st,syscfg = <&syscfg_core 0x100 0xf4>; - resets = <&softreset STIH407_PICOPHY_SOFTRESET>, - <&picophyreset STIH407_PICOPHY0_RESET>; - reset-names = "global", "port"; -}; diff --git a/Documentation/devicetree/bindings/phy/pxa1928-usb-phy.txt b/Documentation/devicetree/bindings/phy/pxa1928-usb-phy.txt deleted file mode 100644 index da94426aa694..000000000000 --- a/Documentation/devicetree/bindings/phy/pxa1928-usb-phy.txt +++ /dev/null @@ -1,18 +0,0 @@ -* Marvell PXA1928 USB and HSIC PHYs - -Required properties: -- compatible: "marvell,pxa1928-usb-phy" or "marvell,pxa1928-hsic-phy" -- reg: base address and length of the registers -- clocks - A single clock. From common clock binding. -- #phys-cells: should be 0. From common phy binding. -- resets: reference to the reset controller - -Example: - - usbphy: phy@7000 { - compatible = "marvell,pxa1928-usb-phy"; - reg = <0x7000 0xe0>; - clocks = <&apmu_clocks PXA1928_CLK_USB>; - #phy-cells = <0>; - }; - diff --git a/Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml b/Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml index 2671a048c926..e77576d06c0e 100644 --- a/Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,ipq5332-usb-hsphy.yaml @@ -17,7 +17,9 @@ description: properties: compatible: items: - - const: qcom,ipq5332-usb-hsphy + - enum: + - qcom,ipq5018-usb-hsphy + - qcom,ipq5332-usb-hsphy "#phy-cells": const: 0 diff --git a/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-usb3-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-usb3-phy.yaml deleted file mode 100644 index 827109d37041..000000000000 --- a/Documentation/devicetree/bindings/phy/qcom,msm8996-qmp-usb3-phy.yaml +++ /dev/null @@ -1,287 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/phy/qcom,msm8996-qmp-usb3-phy.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm QMP PHY controller (USB, MSM8996) - -maintainers: - - Vinod Koul <vkoul@kernel.org> - -description: - QMP PHY controller supports physical layer functionality for a number of - controllers on Qualcomm chipsets, such as, PCIe, UFS, and USB. - - Note that these bindings are for SoCs up to SC8180X. For newer SoCs, see - qcom,sc8280xp-qmp-usb3-uni-phy.yaml. - -properties: - compatible: - enum: - - qcom,ipq6018-qmp-usb3-phy - - qcom,ipq8074-qmp-usb3-phy - - qcom,msm8996-qmp-usb3-phy - - qcom,msm8998-qmp-usb3-phy - - qcom,sdm845-qmp-usb3-uni-phy - - qcom,sdx55-qmp-usb3-uni-phy - - qcom,sdx65-qmp-usb3-uni-phy - - qcom,sm8150-qmp-usb3-uni-phy - - qcom,sm8250-qmp-usb3-uni-phy - - qcom,sm8350-qmp-usb3-uni-phy - - reg: - items: - - description: serdes - - "#address-cells": - enum: [ 1, 2 ] - - "#size-cells": - enum: [ 1, 2 ] - - ranges: true - - clocks: - minItems: 3 - maxItems: 4 - - clock-names: - minItems: 3 - maxItems: 4 - - power-domains: - maxItems: 1 - - resets: - maxItems: 2 - - reset-names: - maxItems: 2 - - vdda-phy-supply: true - - vdda-pll-supply: true - - vddp-ref-clk-supply: true - -patternProperties: - "^phy@[0-9a-f]+$": - type: object - description: single PHY-provider child node - properties: - reg: - minItems: 3 - maxItems: 6 - - clocks: - items: - - description: PIPE clock - - clock-names: - deprecated: true - items: - - const: pipe0 - - "#clock-cells": - const: 0 - - clock-output-names: - maxItems: 1 - - "#phy-cells": - const: 0 - - required: - - reg - - clocks - - "#clock-cells" - - clock-output-names - - "#phy-cells" - - additionalProperties: false - -required: - - compatible - - reg - - "#address-cells" - - "#size-cells" - - ranges - - clocks - - clock-names - - resets - - reset-names - - vdda-phy-supply - - vdda-pll-supply - -additionalProperties: false - -allOf: - - if: - properties: - compatible: - contains: - enum: - - qcom,sdm845-qmp-usb3-uni-phy - then: - properties: - clocks: - maxItems: 4 - clock-names: - items: - - const: aux - - const: cfg_ahb - - const: ref - - const: com_aux - resets: - maxItems: 2 - reset-names: - items: - - const: phy - - const: common - - - if: - properties: - compatible: - contains: - enum: - - qcom,ipq8074-qmp-usb3-phy - - qcom,msm8996-qmp-usb3-phy - - qcom,msm8998-qmp-usb3-phy - - qcom,sdx55-qmp-usb3-uni-phy - - qcom,sdx65-qmp-usb3-uni-phy - then: - properties: - clocks: - maxItems: 3 - clock-names: - items: - - const: aux - - const: cfg_ahb - - const: ref - resets: - maxItems: 2 - reset-names: - items: - - const: phy - - const: common - - - if: - properties: - compatible: - contains: - enum: - - qcom,sm8150-qmp-usb3-uni-phy - - qcom,sm8250-qmp-usb3-uni-phy - - qcom,sm8350-qmp-usb3-uni-phy - then: - properties: - clocks: - maxItems: 4 - clock-names: - items: - - const: aux - - const: ref_clk_src - - const: ref - - const: com_aux - resets: - maxItems: 2 - reset-names: - items: - - const: phy - - const: common - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8998-qmp-usb3-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX lane 1 - - description: RX lane 1 - - description: PCS - - description: TX lane 2 - - description: RX lane 2 - - - if: - properties: - compatible: - contains: - enum: - - qcom,ipq6018-qmp-usb3-phy - - qcom,ipq8074-qmp-usb3-phy - - qcom,sdx55-qmp-usb3-uni-phy - - qcom,sdx65-qmp-usb3-uni-phy - - qcom,sm8150-qmp-usb3-uni-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX - - description: RX - - description: PCS - - description: PCS_MISC - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8996-qmp-usb3-phy - - qcom,sm8250-qmp-usb3-uni-phy - - qcom,sm8350-qmp-usb3-uni-phy - then: - patternProperties: - "^phy@[0-9a-f]+$": - properties: - reg: - items: - - description: TX - - description: RX - - description: PCS - -examples: - - | - #include <dt-bindings/clock/qcom,gcc-sdm845.h> - usb_2_qmpphy: phy-wrapper@88eb000 { - compatible = "qcom,sdm845-qmp-usb3-uni-phy"; - reg = <0x088eb000 0x18c>; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x088eb000 0x2000>; - - clocks = <&gcc GCC_USB3_SEC_PHY_AUX_CLK >, - <&gcc GCC_USB_PHY_CFG_AHB2PHY_CLK>, - <&gcc GCC_USB3_SEC_CLKREF_CLK>, - <&gcc GCC_USB3_SEC_PHY_COM_AUX_CLK>; - clock-names = "aux", "cfg_ahb", "ref", "com_aux"; - - resets = <&gcc GCC_USB3PHY_PHY_SEC_BCR>, - <&gcc GCC_USB3_PHY_SEC_BCR>; - reset-names = "phy", "common"; - - vdda-phy-supply = <&vdda_usb2_ss_1p2>; - vdda-pll-supply = <&vdda_usb2_ss_core>; - - usb_2_ssphy: phy@200 { - reg = <0x200 0x128>, - <0x400 0x1fc>, - <0x800 0x218>, - <0x600 0x70>; - - clocks = <&gcc GCC_USB3_SEC_PHY_PIPE_CLK>; - - #clock-cells = <0>; - clock-output-names = "usb3_uni_phy_pipe_clk_src"; - - #phy-cells = <0>; - }; - }; diff --git a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml index d981d77e82e4..f3a3296c811c 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml @@ -19,6 +19,7 @@ properties: - qcom,msm8996-qmp-ufs-phy - qcom,msm8998-qmp-ufs-phy - qcom,sa8775p-qmp-ufs-phy + - qcom,sc7280-qmp-ufs-phy - qcom,sc8180x-qmp-ufs-phy - qcom,sc8280xp-qmp-ufs-phy - qcom,sdm845-qmp-ufs-phy @@ -85,6 +86,7 @@ allOf: contains: enum: - qcom,sa8775p-qmp-ufs-phy + - qcom,sc7280-qmp-ufs-phy - qcom,sm8450-qmp-ufs-phy then: properties: diff --git a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml index f99fbbcd68fb..57702f7f2a46 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml @@ -16,20 +16,34 @@ description: properties: compatible: enum: + - qcom,ipq6018-qmp-usb3-phy + - qcom,ipq8074-qmp-usb3-phy - qcom,ipq9574-qmp-usb3-phy + - qcom,msm8996-qmp-usb3-phy + - qcom,msm8998-qmp-usb3-phy - qcom,qcm2290-qmp-usb3-phy - qcom,sa8775p-qmp-usb3-uni-phy - qcom,sc8280xp-qmp-usb3-uni-phy + - qcom,sdm845-qmp-usb3-uni-phy + - qcom,sdx55-qmp-usb3-uni-phy + - qcom,sdx65-qmp-usb3-uni-phy + - qcom,sdx75-qmp-usb3-uni-phy - qcom,sm6115-qmp-usb3-phy + - qcom,sm8150-qmp-usb3-uni-phy + - qcom,sm8250-qmp-usb3-uni-phy + - qcom,sm8350-qmp-usb3-uni-phy + reg: maxItems: 1 clocks: - maxItems: 4 + minItems: 4 + maxItems: 5 clock-names: - maxItems: 4 + minItems: 4 + maxItems: 5 power-domains: maxItems: 1 @@ -74,9 +88,18 @@ allOf: compatible: contains: enum: + - qcom,ipq6018-qmp-usb3-phy + - qcom,ipq8074-qmp-usb3-phy - qcom,ipq9574-qmp-usb3-phy + - qcom,msm8996-qmp-usb3-phy + - qcom,msm8998-qmp-usb3-phy + - qcom,sdx55-qmp-usb3-uni-phy + - qcom,sdx65-qmp-usb3-uni-phy + - qcom,sdx75-qmp-usb3-uni-phy then: properties: + clocks: + maxItems: 4 clock-names: items: - const: aux @@ -109,6 +132,9 @@ allOf: enum: - qcom,sa8775p-qmp-usb3-uni-phy - qcom,sc8280xp-qmp-usb3-uni-phy + - qcom,sm8150-qmp-usb3-uni-phy + - qcom,sm8250-qmp-usb3-uni-phy + - qcom,sm8350-qmp-usb3-uni-phy then: properties: clocks: @@ -119,6 +145,33 @@ allOf: - const: ref - const: com_aux - const: pipe + + - if: + properties: + compatible: + contains: + enum: + - qcom,sdm845-qmp-usb3-uni-phy + then: + properties: + clocks: + maxItems: 5 + clock-names: + items: + - const: aux + - const: cfg_ahb + - const: ref + - const: com_aux + - const: pipe + + - if: + properties: + compatible: + contains: + enum: + - qcom,sa8775p-qmp-usb3-uni-phy + - qcom,sc8280xp-qmp-usb3-uni-phy + then: required: - power-domains diff --git a/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-phy.yaml index c53bab107b6d..c95828607ab6 100644 --- a/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-phy.yaml @@ -14,7 +14,12 @@ description: properties: compatible: - const: qcom,sm8550-snps-eusb2-phy + oneOf: + - items: + - enum: + - qcom,sdx75-snps-eusb2-phy + - const: qcom,sm8550-snps-eusb2-phy + - const: qcom,sm8550-snps-eusb2-phy reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml b/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml index 029569d5fcf3..24c733c10e0e 100644 --- a/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,snps-eusb2-repeater.yaml @@ -32,6 +32,27 @@ properties: vdd3-supply: true + qcom,tune-usb2-disc-thres: + $ref: /schemas/types.yaml#/definitions/uint8 + description: High-Speed disconnect threshold + minimum: 0 + maximum: 7 + default: 0 + + qcom,tune-usb2-amplitude: + $ref: /schemas/types.yaml#/definitions/uint8 + description: High-Speed trasmit amplitude + minimum: 0 + maximum: 15 + default: 8 + + qcom,tune-usb2-preem: + $ref: /schemas/types.yaml#/definitions/uint8 + description: High-Speed TX pre-emphasis tuning + minimum: 0 + maximum: 7 + default: 5 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/phy/ralink-usb-phy.txt b/Documentation/devicetree/bindings/phy/ralink-usb-phy.txt deleted file mode 100644 index 9d2868a437ab..000000000000 --- a/Documentation/devicetree/bindings/phy/ralink-usb-phy.txt +++ /dev/null @@ -1,23 +0,0 @@ -Mediatek/Ralink USB PHY - -Required properties: - - compatible: "ralink,rt3352-usbphy" - "mediatek,mt7620-usbphy" - "mediatek,mt7628-usbphy" - - reg: required for "mediatek,mt7628-usbphy", unused otherwise - - #phy-cells: should be 0 - - ralink,sysctl: a phandle to a ralink syscon register region - - resets: the two reset controllers for host and device - - reset-names: the names of the 2 reset controllers - -Example: - -usbphy: phy { - compatible = "mediatek,mt7628-usbphy"; - reg = <0x10120000 0x1000>; - #phy-cells = <0>; - - ralink,sysctl = <&sysc>; - resets = <&rstctrl 22 &rstctrl 25>; - reset-names = "host", "device"; -}; diff --git a/Documentation/devicetree/bindings/phy/st,stih407-usb2-phy.yaml b/Documentation/devicetree/bindings/phy/st,stih407-usb2-phy.yaml new file mode 100644 index 000000000000..e45cdd98aab2 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/st,stih407-usb2-phy.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/st,stih407-usb2-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STiH407 USB PHY controller + +maintainers: + - Patrice Chotard <patrice.chotard@foss.st.com> + +description: + The USB picoPHY device is the PHY for both USB2 and USB3 host controllers + (when controlling usb2/1.1 devices) available on STiH407 SoC family from + STMicroelectronics. + +properties: + compatible: + const: st,stih407-usb2-phy + + st,syscfg: + description: Phandle to the syscfg bank + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: phandle to syscfg + - description: phyparam register offset + - description: phyctrl register offset + + resets: + items: + - description: Phandle and reset specifier pair for the whole phy. + - description: Phandle and reset specifier pair for the port. + + reset-names: + items: + - const: global + - const: port + + "#phy-cells": + const: 0 + +required: + - compatible + - st,syscfg + - resets + - reset-names + - "#phy-cells" + +additionalProperties: false + +examples: + - | + #include <dt-bindings/reset/stih407-resets.h> + usb-phy { + compatible = "st,stih407-usb2-phy"; + #phy-cells = <0>; + st,syscfg = <&syscfg_core 0x100 0xf4>; + resets = <&softreset STIH407_PICOPHY_SOFTRESET>, + <&picophyreset STIH407_PICOPHY0_RESET>; + reset-names = "global", "port"; + }; +... diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml index 4e7a456ea4cc..c7df4cd34197 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml @@ -16,6 +16,7 @@ properties: compatible: enum: - amlogic,c3-periphs-pinctrl + - amlogic,t7-periphs-pinctrl - amlogic,meson-a1-periphs-pinctrl - amlogic,meson-s4-periphs-pinctrl diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml index 4478a76171f7..62890a0aead1 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6318-pinctrl.yaml @@ -24,6 +24,7 @@ patternProperties: '-pins$': type: object $ref: pinmux-node.yaml# + additionalProperties: false properties: function: @@ -37,6 +38,10 @@ patternProperties: enum: [ gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7, gpio8, gpio9, gpio10, gpio11, gpio12, gpio13, gpio40 ] + patternProperties: + '-pins$': + $ref: '#/patternProperties/-pins$' + allOf: - $ref: pinctrl.yaml# diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml index 73e1caa7c011..7cc0e1650835 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm63268-pinctrl.yaml @@ -24,6 +24,7 @@ patternProperties: '-pins$': type: object $ref: pinmux-node.yaml# + unevaluatedProperties: false properties: function: @@ -36,11 +37,15 @@ patternProperties: pins: enum: [ gpio0, gpio1, gpio16, gpio17, gpio8, gpio9, gpio18, gpio19, - gpio22, gpio23, gpio30, gpio31, nand_grp, gpio35 + gpio22, gpio23, gpio30, gpio31, nand_grp, gpio35, dectpd_grp, vdsl_phy_override_0_grp, vdsl_phy_override_1_grp, vdsl_phy_override_2_grp, vdsl_phy_override_3_grp, dsl_gpio8, dsl_gpio9 ] + patternProperties: + '-pins$': + $ref: '#/patternProperties/-pins$' + allOf: - $ref: pinctrl.yaml# @@ -122,46 +127,46 @@ examples: pinctrl_nand: nand-pins { function = "nand"; - group = "nand_grp"; + pins = "nand_grp"; }; pinctrl_gpio35_alt: gpio35_alt-pins { function = "gpio35_alt"; - pin = "gpio35"; + pins = "gpio35"; }; pinctrl_dectpd: dectpd-pins { function = "dectpd"; - group = "dectpd_grp"; + pins = "dectpd_grp"; }; pinctrl_vdsl_phy_override_0: vdsl_phy_override_0-pins { function = "vdsl_phy_override_0"; - group = "vdsl_phy_override_0_grp"; + pins = "vdsl_phy_override_0_grp"; }; pinctrl_vdsl_phy_override_1: vdsl_phy_override_1-pins { function = "vdsl_phy_override_1"; - group = "vdsl_phy_override_1_grp"; + pins = "vdsl_phy_override_1_grp"; }; pinctrl_vdsl_phy_override_2: vdsl_phy_override_2-pins { function = "vdsl_phy_override_2"; - group = "vdsl_phy_override_2_grp"; + pins = "vdsl_phy_override_2_grp"; }; pinctrl_vdsl_phy_override_3: vdsl_phy_override_3-pins { function = "vdsl_phy_override_3"; - group = "vdsl_phy_override_3_grp"; + pins = "vdsl_phy_override_3_grp"; }; pinctrl_dsl_gpio8: dsl_gpio8-pins { function = "dsl_gpio8"; - group = "dsl_gpio8"; + pins = "dsl_gpio8"; }; pinctrl_dsl_gpio9: dsl_gpio9-pins { function = "dsl_gpio9"; - group = "dsl_gpio9"; + pins = "dsl_gpio9"; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml index 2750ba42aeb8..f57bb34c3130 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6328-pinctrl.yaml @@ -24,6 +24,7 @@ patternProperties: '-pins$': type: object $ref: pinmux-node.yaml# + unevaluatedProperties: false properties: function: @@ -36,6 +37,10 @@ patternProperties: gpio20, gpio25, gpio26, gpio27, gpio28, hsspi_cs1, usb_port1 ] + patternProperties: + '-pins$': + $ref: '#/patternProperties/-pins$' + allOf: - $ref: pinctrl.yaml# diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml index 2f6c540498bc..ce6fc5380c52 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6358-pinctrl.yaml @@ -24,15 +24,16 @@ patternProperties: '-pins$': type: object $ref: pinmux-node.yaml# + unevaluatedProperties: false properties: function: enum: [ ebi_cs, uart1, serial_led, legacy_led, led, spi_cs, utopia, pwm_syn_clk, sys_irq ] - pins: + groups: enum: [ ebi_cs_grp, uart1_grp, serial_led_grp, legacy_led_grp, - led_grp, spi_cs_grp, utopia_grp, pwm_syn_clk, sys_irq_grp ] + led_grp, spi_cs_grp, utopia_grp, pwm_syn_clk_grp, sys_irq_grp ] allOf: - $ref: pinctrl.yaml# diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml index b3044f805753..5f7ed7d3dd49 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6362-pinctrl.yaml @@ -24,6 +24,7 @@ patternProperties: '-pins$': type: object $ref: pinmux-node.yaml# + unevaluatedProperties: false properties: function: @@ -41,6 +42,10 @@ patternProperties: gpio15, gpio16, gpio17, gpio18, gpio19, gpio20, gpio21, gpio22, gpio23, gpio24, gpio25, gpio26, gpio27, nand_grp ] + patternProperties: + '-pins$': + $ref: '#/patternProperties/-pins$' + allOf: - $ref: pinctrl.yaml# @@ -204,6 +209,6 @@ examples: pinctrl_nand: nand-pins { function = "nand"; - group = "nand_grp"; + pins = "nand_grp"; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml index 3236871827df..d549e945505b 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm6368-pinctrl.yaml @@ -24,6 +24,7 @@ patternProperties: '-pins$': type: object $ref: pinmux-node.yaml# + unevaluatedProperties: false properties: function: @@ -42,6 +43,10 @@ patternProperties: gpio24, gpio25, gpio26, gpio27, gpio28, gpio29, gpio30, gpio31, uart1_grp ] + patternProperties: + '-pins$': + $ref: '#/patternProperties/-pins$' + allOf: - $ref: pinctrl.yaml# @@ -215,6 +220,6 @@ examples: pinctrl_uart1: uart1-pins { function = "uart1"; - group = "uart1_grp"; + pins = "uart1_grp"; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml new file mode 100644 index 000000000000..3e8472898800 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml @@ -0,0 +1,217 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/nuvoton,npcm845-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Nuvoton NPCM845 Pin Controller and GPIO + +maintainers: + - Tomer Maimon <tmaimon77@gmail.com> + +description: + The Nuvoton BMC NPCM8XX Pin Controller multi-function routed through + the multiplexing block, Each pin supports GPIO functionality (GPIOx) + and multiple functions that directly connect the pin to different + hardware blocks. + +properties: + compatible: + const: nuvoton,npcm845-pinctrl + + ranges: + maxItems: 1 + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + + nuvoton,sysgcr: + $ref: /schemas/types.yaml#/definitions/phandle + description: a phandle to access GCR registers. + +patternProperties: + '^gpio@': + type: object + additionalProperties: false + + description: + Eight GPIO banks that each contain 32 GPIOs. + + properties: + gpio-controller: true + + '#gpio-cells': + const: 2 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + gpio-ranges: + maxItems: 1 + + required: + - gpio-controller + - '#gpio-cells' + - reg + - interrupts + - gpio-ranges + + '-mux$': + $ref: pinmux-node.yaml# + + properties: + groups: + description: + One or more groups of pins to mux to a certain function + items: + enum: [ iox1, iox2, smb1d, smb2d, lkgpo1, lkgpo2, ioxh, gspi, + smb5b, smb5c, lkgpo0, pspi, jm1, jm2, smb4den, smb4b, + smb4c, smb15, smb16, smb17, smb18, smb19, smb20, smb21, + smb22, smb23, smb23b, smb4d, smb14, smb5, smb4, smb3, + spi0cs1, spi0cs2, spi0cs3, spi1cs0, spi1cs1, spi1cs2, + spi1cs3, spi1cs23, smb3c, smb3b, bmcuart0a, uart1, jtag2, + bmcuart1, uart2, sg1mdio, bmcuart0b, r1err, r1md, r1oen, + r2oen, rmii3, r3oen, smb3d, fanin0, fanin1, fanin2, fanin3, + fanin4, fanin5, fanin6, fanin7, fanin8, fanin9, fanin10, + fanin11, fanin12, fanin13, fanin14, fanin15, pwm0, pwm1, pwm2, + pwm3, r2, r2err, r2md, r3rxer, ga20kbc, smb5d, lpc, espi, rg2, + ddr, i3c0, i3c1, i3c2, i3c3, i3c4, i3c5, smb0, smb1, smb2, + smb2c, smb2b, smb1c, smb1b, smb8, smb9, smb10, smb11, sd1, + sd1pwr, pwm4, pwm5, pwm6, pwm7, pwm8, pwm9, pwm10, pwm11, + mmc8, mmc, mmcwp, mmccd, mmcrst, clkout, serirq, lpcclk, + scipme, smi, smb6, smb7, spi1, faninx, r1, spi3, spi3cs1, + spi3quad, spi3cs2, spi3cs3, nprd_smi, smb0b, smb0c, smb0den, + smb0d, ddc, rg2mdio, wdog1, wdog2, smb12, smb13, spix, + spixcs1, clkreq, hgpio0, hgpio1, hgpio2, hgpio3, hgpio4, + hgpio5, hgpio6, hgpio7 ] + + function: + description: + The function that a group of pins is muxed to + enum: [ iox1, iox2, smb1d, smb2d, lkgpo1, lkgpo2, ioxh, gspi, + smb5b, smb5c, lkgpo0, pspi, jm1, jm2, smb4den, smb4b, + smb4c, smb15, smb16, smb17, smb18, smb19, smb20, smb21, + smb22, smb23, smb23b, smb4d, smb14, smb5, smb4, smb3, + spi0cs1, spi0cs2, spi0cs3, spi1cs0, spi1cs1, spi1cs2, + spi1cs3, spi1cs23, smb3c, smb3b, bmcuart0a, uart1, jtag2, + bmcuart1, uart2, sg1mdio, bmcuart0b, r1err, r1md, r1oen, + r2oen, rmii3, r3oen, smb3d, fanin0, fanin1, fanin2, fanin3, + fanin4, fanin5, fanin6, fanin7, fanin8, fanin9, fanin10, + fanin11, fanin12, fanin13, fanin14, fanin15, pwm0, pwm1, pwm2, + pwm3, r2, r2err, r2md, r3rxer, ga20kbc, smb5d, lpc, espi, rg2, + ddr, i3c0, i3c1, i3c2, i3c3, i3c4, i3c5, smb0, smb1, smb2, + smb2c, smb2b, smb1c, smb1b, smb8, smb9, smb10, smb11, sd1, + sd1pwr, pwm4, pwm5, pwm6, pwm7, pwm8, pwm9, pwm10, pwm11, + mmc8, mmc, mmcwp, mmccd, mmcrst, clkout, serirq, lpcclk, + scipme, smi, smb6, smb7, spi1, faninx, r1, spi3, spi3cs1, + spi3quad, spi3cs2, spi3cs3, nprd_smi, smb0b, smb0c, smb0den, + smb0d, ddc, rg2mdio, wdog1, wdog2, smb12, smb13, spix, + spixcs1, clkreq, hgpio0, hgpio1, hgpio2, hgpio3, hgpio4, + hgpio5, hgpio6, hgpio7 ] + + dependencies: + groups: [ function ] + function: [ groups ] + + additionalProperties: false + + '^pin': + $ref: pincfg-node.yaml# + + properties: + pins: + description: + A list of pins to configure in certain ways, such as enabling + debouncing + items: + pattern: '^GPIO([0-9]|[0-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-6])' + + bias-disable: true + + bias-pull-up: true + + bias-pull-down: true + + input-enable: true + + output-low: true + + output-high: true + + drive-push-pull: true + + drive-open-drain: true + + input-debounce: + description: + Debouncing periods in microseconds, one period per interrupt + bank found in the controller + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 4 + + slew-rate: + description: | + 0: Low rate + 1: High rate + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + drive-strength: + enum: [ 0, 1, 2, 4, 8, 12 ] + + additionalProperties: false + +allOf: + - $ref: pinctrl.yaml# + +required: + - compatible + - ranges + - '#address-cells' + - '#size-cells' + - nuvoton,sysgcr + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/gpio/gpio.h> + + soc { + #address-cells = <2>; + #size-cells = <2>; + + pinctrl: pinctrl@f0010000 { + compatible = "nuvoton,npcm845-pinctrl"; + ranges = <0x0 0x0 0xf0010000 0x8000>; + #address-cells = <1>; + #size-cells = <1>; + nuvoton,sysgcr = <&gcr>; + + gpio0: gpio@0 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x0 0xb0>; + interrupts = <GIC_SPI 116 IRQ_TYPE_LEVEL_HIGH>; + gpio-ranges = <&pinctrl 0 0 32>; + }; + + fanin0_pin: fanin0-mux { + groups = "fanin0"; + function = "fanin0"; + }; + + pin34_slew: pin34-slew { + pins = "GPIO34/I3C4_SDA"; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml index 2aedb7e7bc8b..5ece3b9d676b 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,mdm9607-tlmm.yaml @@ -43,7 +43,8 @@ patternProperties: "-state$": oneOf: - $ref: "#/$defs/qcom-mdm9607-tlmm-state" - - patternProperties: + - additionalProperties: false + patternProperties: ".*": $ref: "#/$defs/qcom-mdm9607-tlmm-state" diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml index 9efb76509580..a602bf0d27fb 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8226-pinctrl.yaml @@ -67,8 +67,8 @@ $defs: Specify the alternative function to be configured for the specified pins. Functions are only valid for gpio pins. enum: [ gpio, cci_i2c0, blsp_uim1, blsp_uim2, blsp_uim3, blsp_uim5, - blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, blsp_i2c5, blsp_spi1, - blsp_spi2, blsp_spi3, blsp_spi5, blsp_uart1, blsp_uart2, + blsp_i2c1, blsp_i2c2, blsp_i2c3, blsp_i2c4, blsp_i2c5, blsp_i2c6, + blsp_spi1, blsp_spi2, blsp_spi3, blsp_spi5, blsp_uart1, blsp_uart2, blsp_uart3, blsp_uart4, blsp_uart5, cam_mclk0, cam_mclk1, gp0_clk, gp1_clk, sdc3, wlan ] diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml index e119a226a4b1..2173c5255638 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sa8775p-tlmm.yaml @@ -28,6 +28,7 @@ properties: gpio-controller: true "#gpio-cells": true gpio-ranges: true + wakeup-parent: true gpio-reserved-ranges: minItems: 1 diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml index 368d44ff5468..c8735ab97e40 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/qcom,sc7280-pinctrl.yaml @@ -41,6 +41,10 @@ properties: gpio-ranges: maxItems: 1 + gpio-reserved-ranges: + minItems: 1 + maxItems: 88 + gpio-line-names: maxItems: 175 diff --git a/Documentation/devicetree/bindings/pinctrl/realtek,rtd1315e-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/realtek,rtd1315e-pinctrl.yaml new file mode 100644 index 000000000000..fc6c65fea73b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/realtek,rtd1315e-pinctrl.yaml @@ -0,0 +1,188 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Realtek Semiconductor Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/realtek,rtd1315e-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek DHC RTD1315E Pin Controller + +maintainers: + - TY Chang <tychang@realtek.com> + +description: + The Realtek DHC RTD1315E is a high-definition media processor SoC. The + RTD1315E pin controller is used to control pin function, pull up/down + resistor, drive strength, schmitt trigger and power source. + +properties: + compatible: + const: realtek,rtd1315e-pinctrl + + reg: + maxItems: 1 + +patternProperties: + '-pins$': + type: object + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + properties: + pins: + items: + enum: [ gpio_0, gpio_1, emmc_rst_n, emmc_dd_sb, emmc_clk, emmc_cmd, + gpio_6, gpio_7, gpio_8, gpio_9, gpio_10, gpio_11, gpio_12, + gpio_13, gpio_14, gpio_15, gpio_16, gpio_17, gpio_18, gpio_19, + gpio_20, emmc_data_0, emmc_data_1, emmc_data_2, usb_cc2, gpio_25, + gpio_26, gpio_27, gpio_28, gpio_29, gpio_30, gpio_31, gpio_32, + gpio_33, gpio_34, gpio_35, hif_data, hif_en, hif_rdy, hif_clk, + gpio_dummy_40, gpio_dummy_41, gpio_dummy_42, gpio_dummy_43, + gpio_dummy_44, gpio_dummy_45, gpio_46, gpio_47, gpio_48, gpio_49, + gpio_50, usb_cc1, emmc_data_3, emmc_data_4, ir_rx, ur0_rx, ur0_tx, + gpio_57, gpio_58, gpio_59, gpio_60, gpio_61, gpio_62, gpio_dummy_63, + gpio_dummy_64, gpio_dummy_65, gpio_66, gpio_67, gpio_68, gpio_69, + gpio_70, gpio_71, gpio_72, gpio_dummy_73, emmc_data_5, emmc_data_6, + emmc_data_7, gpio_dummy_77, gpio_78, gpio_79, gpio_80, gpio_81, + ur2_loc, gspi_loc, hi_width, sf_en, arm_trace_dbg_en, + ejtag_aucpu_loc, ejtag_acpu_loc, ejtag_vcpu_loc, ejtag_scpu_loc, + dmic_loc, vtc_dmic_loc, vtc_tdm_loc, vtc_i2si_loc, tdm_ai_loc, + ai_loc, spdif_loc, hif_en_loc, scan_switch, wd_rset, boot_sel, + reset_n, testmode ] + + function: + enum: [ gpio, nf, emmc, ao, gspi_loc0, gspi_loc1, uart0, uart1, + uart2_loc0, uart2_loc1, i2c0, i2c1, i2c4, i2c5, pcie1, + etn_led, etn_phy, spi, pwm0_loc0, pwm0_loc1, pwm1_loc0, + pwm1_loc1, pwm2_loc0, pwm2_loc1, pwm3_loc0, pwm3_loc1, + spdif_optical_loc0, spdif_optical_loc1, usb_cc1, usb_cc2, + sd, dmic_loc0, dmic_loc1, ai_loc0, ai_loc1, tdm_ai_loc0, + tdm_ai_loc1, hi_loc0, hi_m, vtc_i2so, vtc_i2si_loc0, + vtc_i2si_loc1, vtc_dmic_loc0, vtc_dmic_loc1, vtc_tdm_loc0, + vtc_tdm_loc1, dc_fan, pll_test_loc0, pll_test_loc1, + ir_rx, uart2_disable, gspi_disable, hi_width_disable, + hi_width_1bit, sf_disable, sf_enable, scpu_ejtag_loc0, + scpu_ejtag_loc1, scpu_ejtag_loc2, scpu_ejtag_loc3, + acpu_ejtag_loc0, acpu_ejtag_loc1, acpu_ejtag_loc2, + vcpu_ejtag_loc0, vcpu_ejtag_loc1, vcpu_ejtag_loc2, + aucpu_ejtag_loc0, aucpu_ejtag_loc1, aucpu_ejtag_loc2, + gpu_ejtag, iso_tristate, dbg_out0, dbg_out1, standby_dbg, + spdif, arm_trace_debug_disable, arm_trace_debug_enable, + aucpu_ejtag_disable, acpu_ejtag_disable, vcpu_ejtag_disable, + scpu_ejtag_disable, vtc_dmic_loc_disable, vtc_tdm_disable, + vtc_i2si_disable, tdm_ai_disable, ai_disable, spdif_disable, + hif_disable, hif_enable, test_loop, pmic_pwrup ] + + drive-strength: + enum: [4, 8] + + bias-pull-down: true + + bias-pull-up: true + + bias-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-push-pull: true + + power-source: + description: | + Valid arguments are described as below: + 0: power supply of 1.8V + 1: power supply of 3.3V + enum: [0, 1] + + realtek,drive-strength-p: + description: | + Some of pins can be driven using the P-MOS and N-MOS transistor to + achieve finer adjustments. The block-diagram representation is as + follows: + VDD + | + ||--+ + +-----o|| P-MOS-FET + | ||--+ + IN --+ +----- out + | ||--+ + +------|| N-MOS-FET + ||--+ + | + GND + The driving strength of the P-MOS/N-MOS transistors impacts the + waveform's rise/fall times. Greater driving strength results in + shorter rise/fall times. Each P-MOS and N-MOS transistor offers + 8 configurable levels (0 to 7), with higher values indicating + greater driving strength, contributing to achieving the desired + speed. + + The realtek,drive-strength-p is used to control the driving strength + of the P-MOS output. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + realtek,drive-strength-n: + description: | + Similar to the realtek,drive-strength-p, the realtek,drive-strength-n + is used to control the driving strength of the N-MOS output. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + realtek,duty-cycle: + description: | + An integer describing the level to adjust output duty cycle, controlling + the proportion of positive and negative waveforms in nanoseconds. + Valid arguments are described as below: + 0: 0ns + 2: + 0.25ns + 3: + 0.5ns + 4: -0.25ns + 5: -0.5ns + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 2, 3, 4, 5 ] + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@4e000 { + compatible = "realtek,rtd1315e-pinctrl"; + reg = <0x4e000 0x130>; + + emmc-hs200-pins { + pins = "emmc_clk", + "emmc_cmd", + "emmc_data_0", + "emmc_data_1", + "emmc_data_2", + "emmc_data_3", + "emmc_data_4", + "emmc_data_5", + "emmc_data_6", + "emmc_data_7"; + function = "emmc"; + realtek,drive-strength-p = <0x2>; + realtek,drive-strength-n = <0x2>; + }; + + i2c-0-pins { + pins = "gpio_12", + "gpio_13"; + function = "i2c0"; + drive-strength = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/realtek,rtd1319d-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/realtek,rtd1319d-pinctrl.yaml new file mode 100644 index 000000000000..f07361d60acd --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/realtek,rtd1319d-pinctrl.yaml @@ -0,0 +1,187 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Realtek Semiconductor Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/realtek,rtd1319d-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek DHC RTD1319D Pin Controller + +maintainers: + - TY Chang <tychang@realtek.com> + +description: + The Realtek DHC RTD1319D is a high-definition media processor SoC. The + RTD1319D pin controller is used to control pin function, pull up/down + resistor, drive strength, schmitt trigger and power source. + +properties: + compatible: + const: realtek,rtd1319d-pinctrl + + reg: + maxItems: 1 + +patternProperties: + '-pins$': + type: object + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + properties: + pins: + items: + enum: [ gpio_0, gpio_1, gpio_2, gpio_3, gpio_4, gpio_5, gpio_6, gpio_7, + gpio_8, gpio_9, gpio_10, gpio_11, gpio_12, gpio_13, gpio_14, + gpio_15, gpio_16, gpio_17, gpio_18, gpio_19, gpio_20, gpio_21, + gpio_22, gpio_23, usb_cc2, gpio_25, gpio_26, gpio_27, gpio_28, + gpio_29, gpio_30, gpio_31, gpio_32, gpio_33, gpio_34, gpio_35, + hif_data, hif_en, hif_rdy, hif_clk, gpio_40, gpio_41, gpio_42, + gpio_43, gpio_44, gpio_45, gpio_46, gpio_47, gpio_48, gpio_49, + gpio_50, usb_cc1, gpio_52, gpio_53, ir_rx, ur0_rx, ur0_tx, + gpio_57, gpio_58, gpio_59, gpio_60, gpio_61, gpio_62, gpio_63, + gpio_64, emmc_rst_n, emmc_dd_sb, emmc_clk, emmc_cmd, emmc_data_0, + emmc_data_1, emmc_data_2, emmc_data_3, emmc_data_4, emmc_data_5, + emmc_data_6, emmc_data_7, dummy, gpio_78, gpio_79, gpio_80, + gpio_81, ur2_loc, gspi_loc, hi_width, sf_en, arm_trace_dbg_en, + ejtag_aucpu_loc, ejtag_acpu_loc, ejtag_vcpu_loc, ejtag_scpu_loc, + dmic_loc, ejtag_secpu_loc, vtc_dmic_loc, vtc_tdm_loc, vtc_i2si_loc, + tdm_ai_loc, ai_loc, spdif_loc, hif_en_loc, sc0_loc, sc1_loc, + scan_switch, wd_rset, boot_sel, reset_n, testmode ] + + function: + enum: [ gpio, nf, emmc, tp0, tp1, sc0, sc0_data0, sc0_data1, sc0_data2, + sc1, sc1_data0, sc1_data1, sc1_data2, ao, gspi_loc0, gspi_loc1, + uart0, uart1, uart2_loc0, uart2_loc1, i2c0, i2c1, i2c3, i2c4, + i2c5, pcie1, sdio, etn_led, etn_phy, spi, pwm0_loc0, pwm0_loc1, + pwm1_loc0, pwm1_loc1, pwm2_loc0, pwm2_loc1, pwm3_loc0, pwm3_loc1, + qam_agc_if0, qam_agc_if1, spdif_optical_loc0, spdif_optical_loc1, + usb_cc1, usb_cc2, vfd, sd, dmic_loc0, dmic_loc1, ai_loc0, ai_loc1, + tdm_ai_loc0, tdm_ai_loc1, hi_loc0, hi_m, vtc_i2so, vtc_i2si_loc0, + vtc_i2si_loc1, vtc_dmic_loc0, vtc_dmic_loc1, vtc_tdm_loc0, + vtc_tdm_loc1, dc_fan, pll_test_loc0, pll_test_loc1, ir_rx, + uart2_disable, gspi_disable, hi_width_disable, hi_width_1bit, + sf_disable, sf_enable, scpu_ejtag_loc0, scpu_ejtag_loc1, + scpu_ejtag_loc2, acpu_ejtag_loc0, acpu_ejtag_loc1, acpu_ejtag_loc2, + vcpu_ejtag_loc0, vcpu_ejtag_loc1, vcpu_ejtag_loc2, secpu_ejtag_loc0, + secpu_ejtag_loc1, secpu_ejtag_loc2, aucpu_ejtag_loc0, aucpu_ejtag_loc1, + aucpu_ejtag_loc2, iso_tristate, dbg_out0, dbg_out1, standby_dbg, + spdif, arm_trace_debug_disable, arm_trace_debug_enable, + aucpu_ejtag_disable, acpu_ejtag_disable, vcpu_ejtag_disable, + scpu_ejtag_disable, secpu_ejtag_disable, vtc_dmic_loc_disable, + vtc_tdm_disable, vtc_i2si_disable, tdm_ai_disable, ai_disable, + spdif_disable, hif_disable, hif_enable, test_loop, pmic_pwrup ] + + drive-strength: + enum: [4, 8] + + bias-pull-down: true + + bias-pull-up: true + + bias-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-push-pull: true + + power-source: + description: | + Valid arguments are described as below: + 0: power supply of 1.8V + 1: power supply of 3.3V + enum: [0, 1] + + realtek,drive-strength-p: + description: | + Some of pins can be driven using the P-MOS and N-MOS transistor to + achieve finer adjustments. The block-diagram representation is as + follows: + VDD + | + ||--+ + +-----o|| P-MOS-FET + | ||--+ + IN --+ +----- out + | ||--+ + +------|| N-MOS-FET + ||--+ + | + GND + The driving strength of the P-MOS/N-MOS transistors impacts the + waveform's rise/fall times. Greater driving strength results in + shorter rise/fall times. Each P-MOS and N-MOS transistor offers + 8 configurable levels (0 to 7), with higher values indicating + greater driving strength, contributing to achieving the desired + speed. + + The realtek,drive-strength-p is used to control the driving strength + of the P-MOS output. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + realtek,drive-strength-n: + description: | + Similar to the realtek,drive-strength-p, the realtek,drive-strength-n + is used to control the driving strength of the N-MOS output. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + realtek,duty-cycle: + description: | + An integer describing the level to adjust output duty cycle, controlling + the proportion of positive and negative waveforms in nanoseconds. + Valid arguments are described as below: + 0: 0ns + 2: + 0.25ns + 3: + 0.5ns + 4: -0.25ns + 5: -0.5ns + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 2, 3, 4, 5 ] + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@4e000 { + compatible = "realtek,rtd1319d-pinctrl"; + reg = <0x4e000 0x130>; + + emmc-hs200-pins { + pins = "emmc_clk", + "emmc_cmd", + "emmc_data_0", + "emmc_data_1", + "emmc_data_2", + "emmc_data_3", + "emmc_data_4", + "emmc_data_5", + "emmc_data_6", + "emmc_data_7"; + function = "emmc"; + realtek,drive-strength-p = <0x2>; + realtek,drive-strength-n = <0x2>; + }; + + i2c-0-pins { + pins = "gpio_12", + "gpio_13"; + function = "i2c0"; + drive-strength = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/realtek,rtd1619b-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/realtek,rtd1619b-pinctrl.yaml new file mode 100644 index 000000000000..671e4ec84624 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/realtek,rtd1619b-pinctrl.yaml @@ -0,0 +1,186 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Realtek Semiconductor Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/realtek,rtd1619b-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek DHC RTD1619B Pin Controller + +maintainers: + - TY Chang <tychang@realtek.com> + +description: + The Realtek DHC RTD1619B is a high-definition media processor SoC. The + RTD1619B pin controller is used to control pin function, pull up/down + resistor, drive strength, schmitt trigger and power source. + +properties: + compatible: + const: realtek,rtd1619b-pinctrl + + reg: + maxItems: 1 + +patternProperties: + '-pins$': + type: object + allOf: + - $ref: pincfg-node.yaml# + - $ref: pinmux-node.yaml# + + properties: + pins: + items: + enum: [ gpio_0, gpio_1, gpio_2, gpio_3, gpio_4, gpio_5, gpio_6, gpio_7, + gpio_8, gpio_9, gpio_10, gpio_11, gpio_12, gpio_13, gpio_14, + gpio_15, gpio_16, gpio_17, gpio_18, gpio_19, gpio_20, gpio_21, + gpio_22, gpio_23, usb_cc2, gpio_25, gpio_26, gpio_27, gpio_28, + gpio_29, gpio_30, gpio_31, gpio_32, gpio_33, gpio_34, gpio_35, + hif_data, hif_en, hif_rdy, hif_clk, gpio_40, gpio_41, gpio_42, + gpio_43, gpio_44, gpio_45, gpio_46, gpio_47, gpio_48, gpio_49, + gpio_50, usb_cc1, gpio_52, gpio_53, ir_rx, ur0_rx, ur0_tx, + gpio_57, gpio_58, gpio_59, gpio_60, gpio_61, gpio_62, gpio_63, + gpio_64, gpio_65, gpio_66, gpio_67, gpio_68, gpio_69, gpio_70, + gpio_71, gpio_72, gpio_73, gpio_74, gpio_75, gpio_76, emmc_cmd, + spi_ce_n, spi_sck, spi_so, spi_si, emmc_rst_n, emmc_dd_sb, + emmc_clk, emmc_data_0, emmc_data_1, emmc_data_2, emmc_data_3, + emmc_data_4, emmc_data_5, emmc_data_6, emmc_data_7, ur2_loc, + gspi_loc, sdio_loc, hi_loc, hi_width, sf_en, arm_trace_dbg_en, + pwm_01_open_drain_en_loc0, pwm_23_open_drain_en_loc0, + pwm_01_open_drain_en_loc1, pwm_23_open_drain_en_loc1, + ejtag_acpu_loc, ejtag_vcpu_loc, ejtag_scpu_loc, dmic_loc, + iso_gspi_loc, ejtag_ve3_loc, ejtag_aucpu0_loc, ejtag_aucpu1_loc ] + + function: + enum: [ gpio, nf, nf_spi, spi, pmic, spdif, spdif_coaxial, spdif_optical_loc0, + spdif_optical_loc1, emmc_spi, emmc, sc1, uart0, uart1, uart2_loc0, uart2_loc1, + gspi_loc1, iso_gspi_loc1, i2c0, i2c1, i2c3, i2c4, i2c5, pwm0, pwm1, pwm2, + pwm3, etn_led, etn_phy, etn_clk, sc0, vfd, gspi_loc0, iso_gspi_loc0, pcie1, + pcie2, sd, sdio_loc0, sdio_loc1, hi, hi_m, dc_fan, pll_test_loc0, pll_test_loc1, + usb_cc1, usb_cc2, ir_rx, tdm_ai_loc0, tdm_ai_loc1, dmic_loc0, dmic_loc1, + ai_loc0, ai_loc1, tp0, tp1, ao, uart2_disable, gspi_disable, sdio_disable, + hi_loc_disable, hi_loc0, hi_width_disable, hi_width_1bit, vtc_i2si_loc0, + vtc_tdm_loc0, vtc_dmic_loc0, vtc_i2si_loc1, vtc_tdm_loc1, vtc_dmic_loc1, + vtc_i2so, ve3_ejtag_loc0, aucpu0_ejtag_loc0, aucpu1_ejtag_loc0, ve3_ejtag_loc1, + aucpu0_ejtag_loc1, aucpu1_ejtag_loc1, ve3_ejtag_loc2, aucpu0_ejtag_loc2, + aucpu1_ejtag_loc2, scpu_ejtag_loc0, acpu_ejtag_loc0, vcpu_ejtag_loc0, + scpu_ejtag_loc1, acpu_ejtag_loc1, vcpu_ejtag_loc1, scpu_ejtag_loc2, + acpu_ejtag_loc2, vcpu_ejtag_loc2, ve3_ejtag_disable, aucpu0_ejtag_disable, + aucpu1_ejtag_disable, acpu_ejtag_disable, vcpu_ejtag_disable, + scpu_ejtag_disable, iso_gspi_disable, sf_disable, sf_enable, + arm_trace_debug_disable, arm_trace_debug_enable, pwm_normal, pwm_open_drain, + standby_dbg, test_loop_dis ] + + drive-strength: + enum: [4, 8] + + bias-pull-down: true + + bias-pull-up: true + + bias-disable: true + + input-schmitt-enable: true + + input-schmitt-disable: true + + drive-push-pull: true + + power-source: + description: | + Valid arguments are described as below: + 0: power supply of 1.8V + 1: power supply of 3.3V + enum: [0, 1] + + realtek,drive-strength-p: + description: | + Some of pins can be driven using the P-MOS and N-MOS transistor to + achieve finer adjustments. The block-diagram representation is as + follows: + VDD + | + ||--+ + +-----o|| P-MOS-FET + | ||--+ + IN --+ +----- out + | ||--+ + +------|| N-MOS-FET + ||--+ + | + GND + The driving strength of the P-MOS/N-MOS transistors impacts the + waveform's rise/fall times. Greater driving strength results in + shorter rise/fall times. Each P-MOS and N-MOS transistor offers + 8 configurable levels (0 to 7), with higher values indicating + greater driving strength, contributing to achieving the desired + speed. + + The realtek,drive-strength-p is used to control the driving strength + of the P-MOS output. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + realtek,drive-strength-n: + description: | + Similar to the realtek,drive-strength-p, the realtek,drive-strength-n + is used to control the driving strength of the N-MOS output. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + realtek,duty-cycle: + description: | + An integer describing the level to adjust output duty cycle, controlling + the proportion of positive and negative waveforms in nanoseconds. + Valid arguments are described as below: + 0: 0ns + 2: + 0.25ns + 3: + 0.5ns + 4: -0.25ns + 5: -0.5ns + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 2, 3, 4, 5 ] + + required: + - pins + + additionalProperties: false + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + pinctrl@4e000 { + compatible = "realtek,rtd1619b-pinctrl"; + reg = <0x4e000 0x130>; + + emmc-hs200-pins { + pins = "emmc_clk", + "emmc_cmd", + "emmc_data_0", + "emmc_data_1", + "emmc_data_2", + "emmc_data_3", + "emmc_data_4", + "emmc_data_5", + "emmc_data_6", + "emmc_data_7"; + function = "emmc"; + realtek,drive-strength-p = <0x2>; + realtek,drive-strength-n = <0x2>; + }; + + i2c-0-pins { + pins = "gpio_12", + "gpio_13"; + function = "i2c0"; + drive-strength = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml index 145c5442f268..b5ca40d0e251 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml @@ -25,6 +25,7 @@ properties: - enum: - renesas,r9a07g043-pinctrl # RZ/G2UL{Type-1,Type-2} and RZ/Five - renesas,r9a07g044-pinctrl # RZ/G2{L,LC} + - renesas,r9a08g045-pinctrl # RZ/G3S - items: - enum: @@ -73,10 +74,26 @@ properties: additionalProperties: anyOf: - type: object + additionalProperties: false allOf: - $ref: pincfg-node.yaml# - $ref: pinmux-node.yaml# + - if: + properties: + compatible: + contains: + enum: + - renesas,r9a08g045-pinctrl + then: + properties: + drive-strength: false + output-impedance-ohms: false + slew-rate: false + else: + properties: + drive-strength-microamp: false + description: Pin controller client devices use pin configuration subnodes (children and grandchildren) for desired pin configuration. @@ -91,6 +108,10 @@ additionalProperties: pins: true drive-strength: enum: [ 2, 4, 8, 12 ] + drive-strength-microamp: + enum: [ 1900, 2200, 4000, 4400, 4500, 4700, 5200, 5300, 5700, + 5800, 6000, 6050, 6100, 6550, 6800, 7000, 8000, 9000, + 10000 ] output-impedance-ohms: enum: [ 33, 50, 66, 100 ] power-source: diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml index cb81a17bd0b1..5fa5d31f8866 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzv2m-pinctrl.yaml @@ -53,6 +53,7 @@ properties: additionalProperties: anyOf: - type: object + additionalProperties: false allOf: - $ref: pincfg-node.yaml# - $ref: pinmux-node.yaml# diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml index 10c335efe619..20e806dce1ec 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.yaml @@ -115,6 +115,8 @@ additionalProperties: type: object additionalProperties: type: object + additionalProperties: false + properties: rockchip,pins: $ref: /schemas/types.yaml#/definitions/uint32-matrix diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml index 2120ef71a78d..e1eb45a9eda4 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.yaml @@ -48,7 +48,8 @@ properties: description: Phandle+args to the syscon node which includes IRQ mux selection. $ref: /schemas/types.yaml#/definitions/phandle-array items: - - items: + - minItems: 2 + items: - description: syscon node which includes IRQ mux selection - description: The offset of the IRQ mux selection register - description: The field mask of IRQ mux, needed if different of 0xf diff --git a/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml b/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml index d80bbedfe3aa..dab3d92bc273 100644 --- a/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml +++ b/Documentation/devicetree/bindings/power/amlogic,meson-sec-pwrc.yaml @@ -12,7 +12,7 @@ maintainers: - Jianxin Pan <jianxin.pan@amlogic.com> description: |+ - Secure Power Domains used in Meson A1/C1/S4 & C3 SoCs, and should be the child node + Secure Power Domains used in Meson A1/C1/S4 & C3/T7 SoCs, and should be the child node of secure-monitor. properties: @@ -21,6 +21,7 @@ properties: - amlogic,meson-a1-pwrc - amlogic,meson-s4-pwrc - amlogic,c3-pwrc + - amlogic,t7-pwrc "#power-domain-cells": const: 1 diff --git a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml index c9acef80f452..8985e2df8a56 100644 --- a/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml +++ b/Documentation/devicetree/bindings/power/mediatek,power-controller.yaml @@ -31,6 +31,7 @@ properties: - mediatek,mt8188-power-controller - mediatek,mt8192-power-controller - mediatek,mt8195-power-controller + - mediatek,mt8365-power-controller '#power-domain-cells': const: 1 @@ -88,6 +89,7 @@ $defs: "include/dt-bindings/power/mediatek,mt8188-power.h" - for MT8188 type power domain. "include/dt-bindings/power/mt8192-power.h" - for MT8192 type power domain. "include/dt-bindings/power/mt8195-power.h" - for MT8195 type power domain. + "include/dt-bindings/power/mediatek,mt8365-power.h" - for MT8365 type power domain. maxItems: 1 clocks: @@ -115,6 +117,10 @@ $defs: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the device containing the INFRACFG register range. + mediatek,infracfg-nao: + $ref: /schemas/types.yaml#/definitions/phandle + description: phandle to the device containing the INFRACFG-NAO register range. + mediatek,smi: $ref: /schemas/types.yaml#/definitions/phandle description: phandle to the device containing the SMI register range. diff --git a/Documentation/devicetree/bindings/power/power-domain.yaml b/Documentation/devicetree/bindings/power/power-domain.yaml index d1235e562041..8fdb529d560b 100644 --- a/Documentation/devicetree/bindings/power/power-domain.yaml +++ b/Documentation/devicetree/bindings/power/power-domain.yaml @@ -13,8 +13,9 @@ maintainers: description: |+ System on chip designs are often divided into multiple PM domains that can be - used for power gating of selected IP blocks for power saving by reduced leakage - current. + used for power gating of selected IP blocks for power saving by reduced + leakage current. Moreover, in some cases the similar PM domains may also be + capable of scaling performance for a group of IP blocks. This device tree binding can be used to bind PM domain consumer devices with their PM domains provided by PM domain providers. A PM domain provider can be @@ -25,7 +26,7 @@ description: |+ properties: $nodename: - pattern: "^(power-controller|power-domain)([@-].*)?$" + pattern: "^(power-controller|power-domain|performance-domain)([@-].*)?$" domain-idle-states: $ref: /schemas/types.yaml#/definitions/phandle-array @@ -44,11 +45,11 @@ properties: operating-points-v2: description: - Phandles to the OPP tables of power domains provided by a power domain - provider. If the provider provides a single power domain only or all - the power domains provided by the provider have identical OPP tables, - then this shall contain a single phandle. Refer to ../opp/opp-v2-base.yaml - for more information. + Phandles to the OPP tables of power domains that are capable of scaling + performance, provided by a power domain provider. If the provider provides + a single power domain only or all the power domains provided by the + provider have identical OPP tables, then this shall contain a single + phandle. Refer to ../opp/opp-v2-base.yaml for more information. "#power-domain-cells": description: diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index 9b03c41d3604..da9c5846f4e1 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -15,42 +15,52 @@ description: properties: compatible: - enum: - - qcom,mdm9607-rpmpd - - qcom,msm8226-rpmpd - - qcom,msm8909-rpmpd - - qcom,msm8916-rpmpd - - qcom,msm8939-rpmpd - - qcom,msm8953-rpmpd - - qcom,msm8976-rpmpd - - qcom,msm8994-rpmpd - - qcom,msm8996-rpmpd - - qcom,msm8998-rpmpd - - qcom,qcm2290-rpmpd - - qcom,qcs404-rpmpd - - qcom,qdu1000-rpmhpd - - qcom,sa8155p-rpmhpd - - qcom,sa8540p-rpmhpd - - qcom,sa8775p-rpmhpd - - qcom,sdm660-rpmpd - - qcom,sc7180-rpmhpd - - qcom,sc7280-rpmhpd - - qcom,sc8180x-rpmhpd - - qcom,sc8280xp-rpmhpd - - qcom,sdm670-rpmhpd - - qcom,sdm845-rpmhpd - - qcom,sdx55-rpmhpd - - qcom,sdx65-rpmhpd - - qcom,sdx75-rpmhpd - - qcom,sm6115-rpmpd - - qcom,sm6125-rpmpd - - qcom,sm6350-rpmhpd - - qcom,sm6375-rpmpd - - qcom,sm8150-rpmhpd - - qcom,sm8250-rpmhpd - - qcom,sm8350-rpmhpd - - qcom,sm8450-rpmhpd - - qcom,sm8550-rpmhpd + oneOf: + - enum: + - qcom,mdm9607-rpmpd + - qcom,msm8226-rpmpd + - qcom,msm8909-rpmpd + - qcom,msm8916-rpmpd + - qcom,msm8917-rpmpd + - qcom,msm8939-rpmpd + - qcom,msm8953-rpmpd + - qcom,msm8976-rpmpd + - qcom,msm8994-rpmpd + - qcom,msm8996-rpmpd + - qcom,msm8998-rpmpd + - qcom,qcm2290-rpmpd + - qcom,qcs404-rpmpd + - qcom,qdu1000-rpmhpd + - qcom,qm215-rpmpd + - qcom,sa8155p-rpmhpd + - qcom,sa8540p-rpmhpd + - qcom,sa8775p-rpmhpd + - qcom,sc7180-rpmhpd + - qcom,sc7280-rpmhpd + - qcom,sc8180x-rpmhpd + - qcom,sc8280xp-rpmhpd + - qcom,sc8380xp-rpmhpd + - qcom,sdm660-rpmpd + - qcom,sdm670-rpmhpd + - qcom,sdm845-rpmhpd + - qcom,sdx55-rpmhpd + - qcom,sdx65-rpmhpd + - qcom,sdx75-rpmhpd + - qcom,sm6115-rpmpd + - qcom,sm6125-rpmpd + - qcom,sm6350-rpmhpd + - qcom,sm6375-rpmpd + - qcom,sm7150-rpmhpd + - qcom,sm8150-rpmhpd + - qcom,sm8250-rpmhpd + - qcom,sm8350-rpmhpd + - qcom,sm8450-rpmhpd + - qcom,sm8550-rpmhpd + - qcom,sm8650-rpmhpd + - items: + - enum: + - qcom,msm8937-rpmpd + - const: qcom,msm8917-rpmpd '#power-domain-cells': const: 1 diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml index b54ec003a1e0..a4b437fce37c 100644 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.yaml @@ -18,6 +18,9 @@ description: > Finally the operating system assumes the power off failed if the system is still running after waiting some time (timeout-ms). +allOf: + - $ref: restart-handler.yaml# + properties: compatible: const: gpio-poweroff @@ -40,6 +43,9 @@ properties: default: 100 description: Delay to wait after driving gpio inactive + priority: + default: 0 + timeout-ms: default: 3000 description: Time to wait before assuming the power off sequence failed. diff --git a/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml b/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml index 3412fe7e1e80..d342b113fca2 100644 --- a/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml +++ b/Documentation/devicetree/bindings/power/reset/syscon-poweroff.yaml @@ -15,6 +15,9 @@ description: |+ defined by the register map pointed by syscon reference plus the offset with the value and mask defined in the poweroff node. Default will be little endian mode, 32 bit access only. + The SYSCON register map is normally retrieved from the parental dt-node. So + the SYSCON poweroff node should be represented as a sub-node of a "syscon", + "simple-mfd" node. properties: compatible: @@ -30,7 +33,10 @@ properties: regmap: $ref: /schemas/types.yaml#/definitions/phandle - description: Phandle to the register map node. + deprecated: true + description: + Phandle to the register map node. This property is deprecated in favor of + the syscon-poweroff node being a child of a system controller node. value: $ref: /schemas/types.yaml#/definitions/uint32 @@ -38,7 +44,6 @@ properties: required: - compatible - - regmap - offset additionalProperties: false @@ -56,7 +61,6 @@ examples: - | poweroff { compatible = "syscon-poweroff"; - regmap = <®mapnode>; offset = <0x0>; mask = <0x7a>; }; diff --git a/Documentation/devicetree/bindings/power/supply/max8925_battery.txt b/Documentation/devicetree/bindings/power/supply/max8925_battery.txt deleted file mode 100644 index d7e3e0c0f71d..000000000000 --- a/Documentation/devicetree/bindings/power/supply/max8925_battery.txt +++ /dev/null @@ -1,18 +0,0 @@ -max8925-battery bindings -~~~~~~~~~~~~~~~~ - -Optional properties : - - batt-detect: whether support battery detect - - topoff-threshold: set charging current in topoff mode - - fast-charge: set charging current in fast mode - - no-temp-support: whether support temperature protection detect - - no-insert-detect: whether support insert detect - -Example: - charger { - batt-detect = <0>; - topoff-threshold = <1>; - fast-charge = <7>; - no-temp-support = <0>; - no-insert-detect = <0>; - }; diff --git a/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml index 2627cd3eed83..377cbb2c2c1f 100644 --- a/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml +++ b/Documentation/devicetree/bindings/power/supply/maxim,max17040.yaml @@ -55,6 +55,14 @@ properties: interrupts: maxItems: 1 + io-channels: + items: + - description: battery temperature + + io-channel-names: + items: + - const: temp + wakeup-source: type: boolean description: | @@ -95,3 +103,26 @@ examples: wakeup-source; }; }; + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + fuel-gauge@36 { + compatible = "maxim,max17043"; + reg = <0x36>; + + interrupt-parent = <&gpio>; + interrupts = <144 IRQ_TYPE_EDGE_FALLING>; + + monitored-battery = <&battery>; + power-supplies = <&charger>; + + io-channels = <&adc 8>; + io-channel-names = "temp"; + + maxim,alert-low-soc-level = <10>; + wakeup-source; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/mitsumi,mm8013.yaml b/Documentation/devicetree/bindings/power/supply/mitsumi,mm8013.yaml new file mode 100644 index 000000000000..6865640cbdfa --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/mitsumi,mm8013.yaml @@ -0,0 +1,38 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/mitsumi,mm8013.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mitsumi MM8013 fuel gauge + +maintainers: + - Konrad Dybcio <konradybcio@kernel.org> + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: mitsumi,mm8013 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + fuel-gauge@55 { + compatible = "mitsumi,mm8013"; + reg = <0x55>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml new file mode 100644 index 000000000000..ad764e69ab57 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-bms-vm.yaml @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/qcom,pm8916-bms-vm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Voltage Mode BMS + +maintainers: + - Nikita Travkin <nikita@trvn.ru> + +description: + Voltage Mode BMS is a hardware block found in some Qualcomm PMICs + such as pm8916. This block performs battery voltage monitoring. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: qcom,pm8916-bms-vm + + reg: + maxItems: 1 + + interrupts: + items: + - description: BMS FSM left S3 mode + - description: BMS FSM entered S2 mode + - description: OCV measured in S3 mode + - description: OCV below threshold + - description: FIFO update done + - description: BMS FSM switched state + + interrupt-names: + items: + - const: cv_leave + - const: cv_enter + - const: ocv_good + - const: ocv_thr + - const: fifo + - const: state_chg + + monitored-battery: true + + power-supplies: true + +required: + - compatible + - reg + - interrupts + - interrupt-names + - monitored-battery + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + #address-cells = <1>; + #size-cells = <0>; + + battery@4000 { + compatible = "qcom,pm8916-bms-vm"; + reg = <0x4000>; + interrupts = <0x0 0x40 0 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 1 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 2 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 3 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 4 IRQ_TYPE_EDGE_RISING>, + <0x0 0x40 5 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "cv_leave", + "cv_enter", + "ocv_good", + "ocv_thr", + "fifo", + "state_chg"; + + monitored-battery = <&battery>; + power-supplies = <&pm8916_charger>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom,pm8916-lbc.yaml b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-lbc.yaml new file mode 100644 index 000000000000..cdf14e5ed119 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom,pm8916-lbc.yaml @@ -0,0 +1,128 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/power/supply/qcom,pm8916-lbc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Linear Battery Charger + +maintainers: + - Nikita Travkin <nikita@trvn.ru> + +description: + Linear Battery Charger hardware block, found in some Qualcomm PMICs + such as pm8916. Implements a simple, autonomous CC/CV charger. + +allOf: + - $ref: power-supply.yaml# + +properties: + compatible: + const: qcom,pm8916-lbc + + reg: + items: + - description: Charger + - description: Battery + - description: USB + - description: MISC + + reg-names: + items: + - const: chgr + - const: bat_if + - const: usb + - const: misc + + interrupts: + items: + - description: Battery detection + - description: Fast charging + - description: Charging failed + - description: Charging done + - description: Battery present + - description: Battery temperature OK + - description: USB coarse detection + - description: USB IN valid + - description: Charger gone + - description: Overtemperature + + interrupt-names: + items: + - const: vbat_det + - const: fast_chg + - const: chg_fail + - const: chg_done + - const: bat_pres + - const: temp_ok + - const: coarse_det + - const: usb_vbus + - const: chg_gone + - const: overtemp + + qcom,fast-charge-safe-voltage: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 4000000 + maximum: 4775000 + description: + Maximum safe battery voltage in uV; May be pre-set by bootloader, + in which case, setting this will harmlessly fail. + + qcom,fast-charge-safe-current: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 90000 + maximum: 1440000 + description: + Maximum safe battery charge current in uA; May be pre-set by + bootloader, in which case setting this will harmlessly fail. + + monitored-battery: true + +required: + - compatible + - reg + - interrupts + - interrupt-names + - qcom,fast-charge-safe-voltage + - qcom,fast-charge-safe-current + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + pmic { + #address-cells = <1>; + #size-cells = <0>; + + charger@1000 { + compatible = "qcom,pm8916-lbc"; + reg = <0x1000>, <0x1200>, <0x1300>, <0x1600>; + reg-names = "chgr", "bat_if", "usb", "misc"; + + interrupts = <0x0 0x10 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 5 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 6 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 7 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 2 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 4 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "vbat_det", + "fast_chg", + "chg_fail", + "chg_done", + "bat_pres", + "temp_ok", + "coarse_det", + "usb_vbus", + "chg_gone", + "overtemp"; + monitored-battery = <&battery>; + + qcom,fast-charge-safe-current = <900000>; + qcom,fast-charge-safe-voltage = <4300000>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml b/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml index f255f3858d08..2e21846463ba 100644 --- a/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml +++ b/Documentation/devicetree/bindings/power/supply/sbs,sbs-manager.yaml @@ -47,6 +47,12 @@ patternProperties: "^i2c@[1-4]$": type: object $ref: /schemas/i2c/i2c-controller.yaml# + unevaluatedProperties: false + + properties: + reg: + minimum: 1 + maximum: 4 examples: - | diff --git a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt b/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt deleted file mode 100644 index ee125cb0e46d..000000000000 --- a/Documentation/devicetree/bindings/power/supply/stericsson,ab8500-battery.txt +++ /dev/null @@ -1,34 +0,0 @@ -AB85000 PMIC contains a node, which contains shared -information about the battery connected to the PMIC. -The node has no compatible property. - -Properties of this node are: - -thermistor-on-batctrl: - A boolean value indicating thermistor interface to battery - - Note: - 'btemp' and 'batctrl' are the pins interfaced for battery temperature - measurement, 'btemp' signal is used when NTC(negative temperature - coefficient) resister is interfaced external to battery whereas - 'batctrl' pin is used when NTC resister is internal to battery. - - Example: - ab8500_battery: ab8500_battery { - thermistor-on-batctrl; - }; - indicates: NTC resister is internal to battery, 'batctrl' is used - for thermal measurement. - - The absence of property 'thermal-on-batctrl' indicates - NTC resister is external to battery and 'btemp' signal is used - for thermal measurement. - -battery-type: - This shall be the battery manufacturing technology type, - allowed types are: - "UNKNOWN" "NiMH" "LION" "LIPO" "LiFe" "NiCd" "LiMn" - Example: - ab8500_battery: ab8500_battery { - stericsson,battery-type = "LIPO"; - } diff --git a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml index f2d1dc7e7b3f..65bfb492b3a4 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml +++ b/Documentation/devicetree/bindings/pwm/pwm-rockchip.yaml @@ -32,6 +32,7 @@ properties: - rockchip,rk3308-pwm - rockchip,rk3568-pwm - rockchip,rk3588-pwm + - rockchip,rv1126-pwm - const: rockchip,rk3328-pwm reg: diff --git a/Documentation/devicetree/bindings/regulator/adi,max77503-regulator.yaml b/Documentation/devicetree/bindings/regulator/adi,max77503-regulator.yaml new file mode 100644 index 000000000000..aa581e550be2 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/adi,max77503-regulator.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright (c) 2023 Analog Devices, Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/adi,max77503-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices MAX77503 Buck Converter + +maintainers: + - Gokhan Celik <Gokhan.Celik@analog.com> + +description: | + The Analog Devices MAX77503 is a single channel 14V input, 1.5A + high-efficiency buck converter. This converter has 94% efficiency + for 2-Cell/3-Cell battery applications. + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + enum: + - adi,max77503 + + reg: + description: I2C address of the device + items: + - enum: [0x1e, 0x24, 0x37] + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@1e { + compatible = "adi,max77503"; + reg = <0x1e>; + + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <5000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/da9210.txt b/Documentation/devicetree/bindings/regulator/da9210.txt deleted file mode 100644 index 58065ca9e3b4..000000000000 --- a/Documentation/devicetree/bindings/regulator/da9210.txt +++ /dev/null @@ -1,29 +0,0 @@ -* Dialog Semiconductor DA9210 Multi-phase 12A DCDC BUCK Converter - -Required properties: - -- compatible: must be "dlg,da9210" -- reg: the i2c slave address of the regulator. It should be 0x68. - -Optional properties: - -- interrupts: a reference to the DA9210 interrupt, if available. - -Any standard regulator properties can be used to configure the single da9210 -DCDC. - -Example: - - da9210@68 { - compatible = "dlg,da9210"; - reg = <0x68>; - - interrupt-parent = <...>; - interrupts = <...>; - - regulator-min-microvolt = <300000>; - regulator-max-microvolt = <1570000>; - regulator-min-microamp = <1600000>; - regulator-max-microamp = <4600000>; - regulator-boot-on; - }; diff --git a/Documentation/devicetree/bindings/regulator/dlg,da9210.yaml b/Documentation/devicetree/bindings/regulator/dlg,da9210.yaml new file mode 100644 index 000000000000..81f23de36de4 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/dlg,da9210.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/dlg,da9210.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Dialog Semiconductor DA9210 Multi-Phase 12A DC-DC Buck Converter + +maintainers: + - Support Opensource <support.opensource@diasemi.com> + +allOf: + - $ref: regulator.yaml# + +properties: + compatible: + const: dlg,da9210 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@68 { + compatible = "dlg,da9210"; + reg = <0x68>; + + interrupt-parent = <&irqc0>; + interrupts = <2 IRQ_TYPE_LEVEL_LOW>; + + regulator-min-microvolt = <300000>; + regulator-max-microvolt = <1570000>; + regulator-min-microamp = <1600000>; + regulator-max-microamp = <4600000>; + regulator-boot-on; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml index ac0281b1cceb..ce7751b9129c 100644 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml @@ -100,6 +100,11 @@ properties: vin-supply: description: Input supply phandle. + interrupts: + maxItems: 1 + description: + Interrupt signaling a critical under-voltage event. + required: - compatible - regulator-name diff --git a/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml index 05f72391185e..7394c0a339c5 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max20086.yaml @@ -43,6 +43,7 @@ properties: "^OUT[1-4]$": type: object $ref: regulator.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml b/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml index 78c0b63243f7..6d6bbfbd26d4 100644 --- a/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml +++ b/Documentation/devicetree/bindings/regulator/maxim,max77826.yaml @@ -30,10 +30,12 @@ properties: "^LDO([1-9]|1[0-5])$": type: object $ref: regulator.yaml# + unevaluatedProperties: false "^BUCK|BUCKBOOST$": type: object $ref: regulator.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/mediatek,mt6358-regulator.yaml b/Documentation/devicetree/bindings/regulator/mediatek,mt6358-regulator.yaml new file mode 100644 index 000000000000..c50402fcba72 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mediatek,mt6358-regulator.yaml @@ -0,0 +1,250 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mediatek,mt6358-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek MT6358 Regulator + +maintainers: + - Zhiyong Tao <zhiyong.tao@mediatek.com> + +description: + Regulator node of the PMIC. This node should under the PMIC's device node. + All voltage regulators provided by the PMIC are described as sub-nodes of + this node. + +properties: + compatible: + oneOf: + - const: mediatek,mt6358-regulator + - items: + - const: mediatek,mt6366-regulator + - const: mediatek,mt6358-regulator + + vsys-ldo1-supply: + description: Supply for LDOs vfe28, vxo22, vcn28, vaux18, vaud28, vsim1, vusb, vbif28 + vsys-ldo2-supply: + description: Supply for LDOs vldo28 (MT6358 only), vio28, vmc, vmch, vsim2 + vsys-ldo3-supply: + description: Supply for LDOs vcn33, vcama[12] (MT6358 only), vemc, vibr + vsys-vcore-supply: + description: Supply for buck regulator vcore + vsys-vdram1-supply: + description: Supply for buck regulator vdram1 + vsys-vgpu-supply: + description: Supply for buck regulator vgpu + vsys-vmodem-supply: + description: Supply for buck regulator vmodem + vsys-vpa-supply: + description: Supply for buck regulator vpa + vsys-vproc11-supply: + description: Supply for buck regulator vproc11 + vsys-vproc12-supply: + description: Supply for buck regulator vproc12 + vsys-vs1-supply: + description: Supply for buck regulator vs1 + vsys-vs2-supply: + description: Supply for buck regulator vs2 + vs1-ldo1-supply: + description: + Supply for LDOs vrf18, vefuse, vcn18, vcamio (MT6358 only), vio18, vm18 (MT6366 only) + vs2-ldo1-supply: + description: Supply for LDOs vdram2, vmddr (MT6366 only) + vs2-ldo2-supply: + description: Supply for LDOs vrf12, va12 + vs2-ldo3-supply: + description: + Supply for LDOs vsram-core (MT6366 only), vsram-gpu, vsram-others, vsram-proc11, vsram-proc12 + vs2-ldo4-supply: + description: Supply for LDO vcamd + +patternProperties: + "^(buck_)?v(core|dram1|gpu|modem|pa|proc1[12]|s[12])$": + description: Buck regulators + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: + description: | + Buck regulatpr operating modes allowed. Valid values below. + Users should use the macros from dt-bindings/regulator/mediatek,mt6397-regulator.h + 0 (MT6397_BUCK_MODE_AUTO): Auto PFM/PWM mode + 1 (MT6397_BUCK_MODE_FORCE_PWM): Forced PWM mode + items: + enum: [0, 1] + unevaluatedProperties: false + + "^(ldo_)?v(a|rf)12$": + description: LDOs with fixed 1.2V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?v((aux|cn|io|rf)18|camio)$": + description: + LDOs with fixed 1.8V output and 0~100/10mV tuning (vcn18 on MT6366 has variable output) + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?vxo22$": + description: LDOs with fixed 2.2V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?v(aud|bif|cn|fe|io)28$": + description: LDOs with fixed 2.8V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?vusb$": + description: LDOs with fixed 3.0V output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?vsram[_-](core|gpu|others|proc1[12])$": + description: LDOs with variable output + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + + "^(ldo_)?v(cama[12]|camd|cn33|dram2|efuse|emc|ibr|ldo28|m18|mc|mch|mddr|sim[12])$": + description: LDOs with variable output and 0~100/10mV tuning + type: object + $ref: regulator.yaml# + properties: + regulator-allowed-modes: false + unevaluatedProperties: false + +required: + - compatible + +additionalProperties: false + +allOf: + - if: + properties: + compatible: + const: mediatek,mt6358-regulator + then: + patternProperties: + # Old regulator node name scheme (with prefix and underscores) only + # ([^y-] is used to avoid matching -supply + "^(?<!buck_)(?<!ldo_)v.*[^y-](?!-supply)$": false + "^ldo_vsram-": false + # vsram_core regulator doesn't exist on MT6358 + "^ldo_vsram[-_]core$": false + + properties: + # vm18 and vmddr regulators don't exist on MT6358 + ldo_vm18: false + ldo_vmddr: false + + - if: + properties: + compatible: + contains: + const: mediatek,mt6366-regulator + then: + patternProperties: + # Prefer cleaned up regulator node names + "^(buck|ldo)_": false + # Don't allow underscores + "^vsram_": false + # vcam* regulators don't exist on MT6366 + "^vcam": false + + properties: + # vldo28 regulator doesn't exist on MT6366 + vldo28: false + # vs2_ldo4 supply pin doesn't exist on MT6366 + vs2-ldo4-supply: false + +examples: + - | + #include <dt-bindings/regulator/mediatek,mt6397-regulator.h> + + regulator { + compatible = "mediatek,mt6358-regulator"; + + buck_vgpu { + regulator-name = "vgpu"; + regulator-min-microvolt = <625000>; + regulator-max-microvolt = <900000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + regulator-allowed-modes = <MT6397_BUCK_MODE_AUTO + MT6397_BUCK_MODE_FORCE_PWM>; + }; + + ldo_vsram_gpu { + regulator-name = "vsram_gpu"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1000000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + }; + }; + + - | + #include <dt-bindings/regulator/mediatek,mt6397-regulator.h> + + regulator { + compatible = "mediatek,mt6366-regulator", "mediatek,mt6358-regulator"; + + vdram1 { + regulator-name = "pp1125_emi_vdd2"; + regulator-min-microvolt = <1125000>; + regulator-max-microvolt = <1125000>; + regulator-ramp-delay = <12500>; + regulator-enable-ramp-delay = <0>; + regulator-allowed-modes = <MT6397_BUCK_MODE_AUTO + MT6397_BUCK_MODE_FORCE_PWM>; + regulator-always-on; + }; + + vproc11 { + regulator-name = "ppvar_dvdd_proc_bc_mt6366"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1200000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <200>; + regulator-allowed-modes = <MT6397_BUCK_MODE_AUTO + MT6397_BUCK_MODE_FORCE_PWM>; + regulator-always-on; + }; + + vmddr { + regulator-name = "pm0750_emi_vmddr"; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <750000>; + regulator-enable-ramp-delay = <325>; + regulator-always-on; + }; + + vsram-proc11 { + regulator-name = "pp0900_dvdd_sram_bc"; + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1120000>; + regulator-ramp-delay = <6250>; + regulator-enable-ramp-delay = <240>; + regulator-always-on; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mps,mpq2286.yaml b/Documentation/devicetree/bindings/regulator/mps,mpq2286.yaml new file mode 100644 index 000000000000..1296f9b30862 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mps,mpq2286.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/mps,mpq2286.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Monolithic Power System MPQ2286 PMIC + +maintainers: + - Saravanan Sekar <saravanan@linumiz.com> + +properties: + compatible: + enum: + - mps,mpq2286 + + reg: + maxItems: 1 + + regulators: + type: object + + properties: + buck: + type: object + $ref: regulator.yaml# + + unevaluatedProperties: false + + additionalProperties: false + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@3 { + compatible = "mps,mpq2286"; + reg = <0x3>; + + regulators { + buck { + regulator-name = "buck"; + regulator-min-microvolt = <1600000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt b/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt deleted file mode 100644 index b6384306db5c..000000000000 --- a/Documentation/devicetree/bindings/regulator/mt6358-regulator.txt +++ /dev/null @@ -1,350 +0,0 @@ -MediaTek MT6358 Regulator - -All voltage regulators provided by the MT6358 PMIC are described as the -subnodes of the MT6358 regulators node. Each regulator is named according -to its regulator type, buck_<name> and ldo_<name>. The definition for each -of these nodes is defined using the standard binding for regulators at -Documentation/devicetree/bindings/regulator/regulator.txt. - -The valid names for regulators are:: -BUCK: - buck_vdram1, buck_vcore, buck_vpa, buck_vproc11, buck_vproc12, buck_vgpu, - buck_vs2, buck_vmodem, buck_vs1 -LDO: - ldo_vdram2, ldo_vsim1, ldo_vibr, ldo_vrf12, ldo_vio18, ldo_vusb, ldo_vcamio, - ldo_vcamd, ldo_vcn18, ldo_vfe28, ldo_vsram_proc11, ldo_vcn28, ldo_vsram_others, - ldo_vsram_gpu, ldo_vxo22, ldo_vefuse, ldo_vaux18, ldo_vmch, ldo_vbif28, - ldo_vsram_proc12, ldo_vcama1, ldo_vemc, ldo_vio28, ldo_va12, ldo_vrf18, - ldo_vcn33, ldo_vcama2, ldo_vmc, ldo_vldo28, ldo_vaud28, ldo_vsim2 - -Example: - - pmic { - compatible = "mediatek,mt6358"; - - mt6358regulator: mt6358regulator { - compatible = "mediatek,mt6358-regulator"; - - mt6358_vdram1_reg: buck_vdram1 { - regulator-compatible = "buck_vdram1"; - regulator-name = "vdram1"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <2087500>; - regulator-ramp-delay = <12500>; - regulator-enable-ramp-delay = <0>; - regulator-always-on; - }; - - mt6358_vcore_reg: buck_vcore { - regulator-name = "vcore"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - regulator-always-on; - }; - - mt6358_vpa_reg: buck_vpa { - regulator-name = "vpa"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <3650000>; - regulator-ramp-delay = <50000>; - regulator-enable-ramp-delay = <250>; - }; - - mt6358_vproc11_reg: buck_vproc11 { - regulator-name = "vproc11"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - regulator-always-on; - }; - - mt6358_vproc12_reg: buck_vproc12 { - regulator-name = "vproc12"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - regulator-always-on; - }; - - mt6358_vgpu_reg: buck_vgpu { - regulator-name = "vgpu"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <200>; - }; - - mt6358_vs2_reg: buck_vs2 { - regulator-name = "vs2"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <2087500>; - regulator-ramp-delay = <12500>; - regulator-enable-ramp-delay = <0>; - regulator-always-on; - }; - - mt6358_vmodem_reg: buck_vmodem { - regulator-name = "vmodem"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <900>; - regulator-always-on; - }; - - mt6358_vs1_reg: buck_vs1 { - regulator-name = "vs1"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <2587500>; - regulator-ramp-delay = <12500>; - regulator-enable-ramp-delay = <0>; - regulator-always-on; - }; - - mt6358_vdram2_reg: ldo_vdram2 { - regulator-name = "vdram2"; - regulator-min-microvolt = <600000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <3300>; - }; - - mt6358_vsim1_reg: ldo_vsim1 { - regulator-name = "vsim1"; - regulator-min-microvolt = <1700000>; - regulator-max-microvolt = <3100000>; - regulator-enable-ramp-delay = <540>; - }; - - mt6358_vibr_reg: ldo_vibr { - regulator-name = "vibr"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - }; - - mt6358_vrf12_reg: ldo_vrf12 { - compatible = "regulator-fixed"; - regulator-name = "vrf12"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <1200000>; - regulator-enable-ramp-delay = <120>; - }; - - mt6358_vio18_reg: ldo_vio18 { - compatible = "regulator-fixed"; - regulator-name = "vio18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <2700>; - regulator-always-on; - }; - - mt6358_vusb_reg: ldo_vusb { - regulator-name = "vusb"; - regulator-min-microvolt = <3000000>; - regulator-max-microvolt = <3100000>; - regulator-enable-ramp-delay = <270>; - regulator-always-on; - }; - - mt6358_vcamio_reg: ldo_vcamio { - compatible = "regulator-fixed"; - regulator-name = "vcamio"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vcamd_reg: ldo_vcamd { - regulator-name = "vcamd"; - regulator-min-microvolt = <900000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vcn18_reg: ldo_vcn18 { - compatible = "regulator-fixed"; - regulator-name = "vcn18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vfe28_reg: ldo_vfe28 { - compatible = "regulator-fixed"; - regulator-name = "vfe28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsram_proc11_reg: ldo_vsram_proc11 { - regulator-name = "vsram_proc11"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - regulator-always-on; - }; - - mt6358_vcn28_reg: ldo_vcn28 { - compatible = "regulator-fixed"; - regulator-name = "vcn28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsram_others_reg: ldo_vsram_others { - regulator-name = "vsram_others"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - regulator-always-on; - }; - - mt6358_vsram_gpu_reg: ldo_vsram_gpu { - regulator-name = "vsram_gpu"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - }; - - mt6358_vxo22_reg: ldo_vxo22 { - compatible = "regulator-fixed"; - regulator-name = "vxo22"; - regulator-min-microvolt = <2200000>; - regulator-max-microvolt = <2200000>; - regulator-enable-ramp-delay = <120>; - regulator-always-on; - }; - - mt6358_vefuse_reg: ldo_vefuse { - regulator-name = "vefuse"; - regulator-min-microvolt = <1700000>; - regulator-max-microvolt = <1900000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vaux18_reg: ldo_vaux18 { - compatible = "regulator-fixed"; - regulator-name = "vaux18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vmch_reg: ldo_vmch { - regulator-name = "vmch"; - regulator-min-microvolt = <2900000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - }; - - mt6358_vbif28_reg: ldo_vbif28 { - compatible = "regulator-fixed"; - regulator-name = "vbif28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsram_proc12_reg: ldo_vsram_proc12 { - regulator-name = "vsram_proc12"; - regulator-min-microvolt = <500000>; - regulator-max-microvolt = <1293750>; - regulator-ramp-delay = <6250>; - regulator-enable-ramp-delay = <240>; - regulator-always-on; - }; - - mt6358_vcama1_reg: ldo_vcama1 { - regulator-name = "vcama1"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <3000000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vemc_reg: ldo_vemc { - regulator-name = "vemc"; - regulator-min-microvolt = <2900000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - regulator-always-on; - }; - - mt6358_vio28_reg: ldo_vio28 { - compatible = "regulator-fixed"; - regulator-name = "vio28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_va12_reg: ldo_va12 { - compatible = "regulator-fixed"; - regulator-name = "va12"; - regulator-min-microvolt = <1200000>; - regulator-max-microvolt = <1200000>; - regulator-enable-ramp-delay = <270>; - regulator-always-on; - }; - - mt6358_vrf18_reg: ldo_vrf18 { - compatible = "regulator-fixed"; - regulator-name = "vrf18"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - regulator-enable-ramp-delay = <120>; - }; - - mt6358_vcn33_reg: ldo_vcn33 { - regulator-name = "vcn33"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3500000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vcama2_reg: ldo_vcama2 { - regulator-name = "vcama2"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <3000000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vmc_reg: ldo_vmc { - regulator-name = "vmc"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <3300000>; - regulator-enable-ramp-delay = <60>; - }; - - mt6358_vldo28_reg: ldo_vldo28 { - regulator-name = "vldo28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <3000000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vaud28_reg: ldo_vaud28 { - compatible = "regulator-fixed"; - regulator-name = "vaud28"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-enable-ramp-delay = <270>; - }; - - mt6358_vsim2_reg: ldo_vsim2 { - regulator-name = "vsim2"; - regulator-min-microvolt = <1700000>; - regulator-max-microvolt = <3100000>; - regulator-enable-ramp-delay = <540>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml index eb61e04ef852..b5181719daa1 100644 --- a/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml +++ b/Documentation/devicetree/bindings/regulator/onnn,fan53880.yaml @@ -48,10 +48,12 @@ properties: "^LDO[1-4]$": type: object $ref: regulator.yaml# + unevaluatedProperties: false "^BUCK|BOOST$": type: object $ref: regulator.yaml# + unevaluatedProperties: false additionalProperties: false diff --git a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml index 127a6f39b7f0..acd37f28ef53 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,rpmh-regulator.yaml @@ -50,6 +50,7 @@ description: | For PM8550, smps1 - smps6, ldo1 - ldo17, bob1 - bob2 For PM8998, smps1 - smps13, ldo1 - ldo28, lvs1 - lvs2 For PMI8998, bob + For PMC8380, smps1 - smps8, ldo1 - lodo3 For PMR735A, smps1 - smps3, ldo1 - ldo7 For PMX55, smps1 - smps7, ldo1 - ldo16 For PMX65, smps1 - smps8, ldo1 - ldo21 @@ -78,6 +79,7 @@ properties: - qcom,pm8998-rpmh-regulators - qcom,pmc8180-rpmh-regulators - qcom,pmc8180c-rpmh-regulators + - qcom,pmc8380-rpmh-regulators - qcom,pmg1110-rpmh-regulators - qcom,pmi8998-rpmh-regulators - qcom,pmm8155au-rpmh-regulators @@ -368,6 +370,16 @@ allOf: properties: compatible: enum: + - qcom,pmc8380-rpmh-regulators + then: + patternProperties: + "^vdd-l[1-3]-supply$": true + "^vdd-s[1-8]-supply$": true + + - if: + properties: + compatible: + enum: - qcom,pmg1110-rpmh-regulators then: properties: diff --git a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml index bdf34c2de96b..7a1b7d2abbd4 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,spmi-regulator.yaml @@ -17,12 +17,15 @@ properties: - qcom,pm660l-regulators - qcom,pm8004-regulators - qcom,pm8005-regulators + - qcom,pm8019-regulators - qcom,pm8226-regulators - qcom,pm8841-regulators + - qcom,pm8909-regulators - qcom,pm8916-regulators - qcom,pm8941-regulators - qcom,pm8950-regulators - qcom,pm8994-regulators + - qcom,pma8084-regulators - qcom,pmi8994-regulators - qcom,pmp8074-regulators - qcom,pms405-regulators @@ -32,7 +35,7 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle patternProperties: - "^(5vs[1-2]|(l|s)[1-9][0-9]?|lvs[1-3])$": + "^(5vs[1-2]|(l|s)[1-9][0-9]?|lvs[1-4])$": description: List of regulators and its properties type: object $ref: regulator.yaml# @@ -181,6 +184,25 @@ allOf: compatible: contains: enum: + - qcom,pm8019-regulators + then: + properties: + vdd_l1-supply: true + vdd_l2_l3-supply: true + vdd_l4_l5_l6-supply: true + vdd_l7_l8_l11-supply: true + vdd_l9-supply: true + vdd_l10-supply: true + vdd_l12-supply: true + vdd_l13_l14-supply: true + patternProperties: + "^vdd_s[1-4]-supply$": true + + - if: + properties: + compatible: + contains: + enum: - qcom,pm8226-regulators then: properties: @@ -211,6 +233,24 @@ allOf: compatible: contains: enum: + - qcom,pm8909-regulators + then: + properties: + vdd_s1-supply: true + vdd_s2-supply: true + vdd_l1-supply: true + vdd_l2_l5-supply: true + vdd_l3_l6_l10-supply: true + vdd_l4_l7-supply: true + vdd_l8_l11_l15_l18-supply: true + vdd_l9_l12_l14_l17-supply: true + vdd_l13-supply: true + + - if: + properties: + compatible: + contains: + enum: - qcom,pm8916-regulators then: properties: @@ -300,6 +340,32 @@ allOf: compatible: contains: enum: + - qcom,pma8084-regulators + then: + properties: + vdd_l1_l11-supply: true + vdd_l2_l3_l4_l27-supply: true + vdd_l5_l7-supply: true + vdd_l6_l12_l14_l15_l26-supply: true + vdd_l8-supply: true + vdd_l9_l10_l13_l20_l23_l24-supply: true + vdd_l16_l25-supply: true + vdd_l17-supply: true + vdd_l18-supply: true + vdd_l19-supply: true + vdd_l21-supply: true + vdd_l22-supply: true + vdd_lvs1_2-supply: true + vdd_lvs3_4-supply: true + vdd_5vs1-supply: true + patternProperties: + "^vdd_s([1-9]|1[0-2])-supply$": true + + - if: + properties: + compatible: + contains: + enum: - qcom,pmi8994-regulators then: properties: diff --git a/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml b/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml index 895415772d1d..09102dda4942 100644 --- a/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml +++ b/Documentation/devicetree/bindings/remoteproc/mtk,scp.yaml @@ -21,6 +21,7 @@ properties: - mediatek,mt8188-scp - mediatek,mt8192-scp - mediatek,mt8195-scp + - mediatek,mt8195-scp-dual reg: description: @@ -31,10 +32,7 @@ properties: reg-names: minItems: 2 - items: - - const: sram - - const: cfg - - const: l1tcm + maxItems: 3 clocks: description: @@ -58,6 +56,93 @@ properties: memory-region: maxItems: 1 + cros-ec-rpmsg: + $ref: /schemas/mfd/google,cros-ec.yaml + description: + This subnode represents the rpmsg device. The properties + of this node are defined by the individual bindings for + the rpmsg devices. + + required: + - mediatek,rpmsg-name + + unevaluatedProperties: false + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + + ranges: + description: + Standard ranges definition providing address translations for + local SCP SRAM address spaces to bus addresses. + +patternProperties: + "^scp@[a-f0-9]+$": + type: object + description: + The MediaTek SCP integrated to SoC might be a multi-core version. + The other cores are represented as child nodes of the boot core. + There are some integration differences for the IP like the usage of + address translator for translating SoC bus addresses into address space + for the processor. + + Each SCP core has own cache memory. The SRAM and L1TCM are shared by + cores. The power of cache, SRAM and L1TCM power should be enabled + before booting SCP cores. The size of cache, SRAM, and L1TCM are varied + on differnt SoCs. + + The SCP cores do not use an MMU, but has a set of registers to + control the translations between 32-bit CPU addresses into system bus + addresses. Cache and memory access settings are provided through a + Memory Protection Unit (MPU), programmable only from the SCP. + + properties: + compatible: + enum: + - mediatek,scp-core + + reg: + description: The base address and size of SRAM. + maxItems: 1 + + reg-names: + const: sram + + interrupts: + maxItems: 1 + + firmware-name: + $ref: /schemas/types.yaml#/definitions/string + description: + If present, name (or relative path) of the file within the + firmware search path containing the firmware image used when + initializing sub cores of multi-core SCP. + + memory-region: + maxItems: 1 + + cros-ec-rpmsg: + $ref: /schemas/mfd/google,cros-ec.yaml + description: + This subnode represents the rpmsg device. The properties + of this node are defined by the individual bindings for + the rpmsg devices. + + required: + - mediatek,rpmsg-name + + unevaluatedProperties: false + + required: + - compatible + - reg + - reg-names + + additionalProperties: false + required: - compatible - reg @@ -87,23 +172,39 @@ allOf: reg: maxItems: 2 reg-names: + items: + - const: sram + - const: cfg + - if: + properties: + compatible: + enum: + - mediatek,mt8192-scp + - mediatek,mt8195-scp + then: + properties: + reg: + maxItems: 3 + reg-names: + items: + - const: sram + - const: cfg + - const: l1tcm + - if: + properties: + compatible: + enum: + - mediatek,mt8195-scp-dual + then: + properties: + reg: maxItems: 2 + reg-names: + items: + - const: cfg + - const: l1tcm -additionalProperties: - type: object - description: - Subnodes of the SCP represent rpmsg devices. The names of the devices - are not important. The properties of these nodes are defined by the - individual bindings for the rpmsg devices. - properties: - mediatek,rpmsg-name: - $ref: /schemas/types.yaml#/definitions/string-array - description: - Contains the name for the rpmsg device. Used to match - the subnode to rpmsg device announced by SCP. - - required: - - mediatek,rpmsg-name +additionalProperties: false examples: - | @@ -118,7 +219,42 @@ examples: clocks = <&infracfg CLK_INFRA_SCPSYS>; clock-names = "main"; - cros_ec { + cros-ec-rpmsg { + compatible = "google,cros-ec-rpmsg"; mediatek,rpmsg-name = "cros-ec-rpmsg"; }; }; + + - | + scp@10500000 { + compatible = "mediatek,mt8195-scp-dual"; + reg = <0x10720000 0xe0000>, + <0x10700000 0x8000>; + reg-names = "cfg", "l1tcm"; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x10500000 0x100000>; + + scp@0 { + compatible = "mediatek,scp-core"; + reg = <0x0 0xa0000>; + reg-names = "sram"; + + cros-ec-rpmsg { + compatible = "google,cros-ec-rpmsg"; + mediatek,rpmsg-name = "cros-ec-rpmsg"; + }; + }; + + scp@a0000 { + compatible = "mediatek,scp-core"; + reg = <0xa0000 0x20000>; + reg-names = "sram"; + + cros-ec-rpmsg { + compatible = "google,cros-ec-rpmsg"; + mediatek,rpmsg-name = "cros-ec-rpmsg"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml index a2b0079de039..661c2b425da3 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.yaml @@ -66,7 +66,9 @@ allOf: - qcom,msm8953-adsp-pil - qcom,msm8974-adsp-pil - qcom,msm8996-adsp-pil + - qcom,msm8996-slpi-pil - qcom,msm8998-adsp-pas + - qcom,msm8998-slpi-pas - qcom,sdm845-adsp-pas - qcom,sdm845-cdsp-pas - qcom,sdm845-slpi-pas @@ -84,24 +86,6 @@ allOf: compatible: contains: enum: - - qcom,msm8996-slpi-pil - - qcom,msm8998-slpi-pas - then: - properties: - clocks: - items: - - description: XO clock - - description: AGGRE2 clock - clock-names: - items: - - const: xo - - const: aggre2 - - - if: - properties: - compatible: - contains: - enum: - qcom,msm8226-adsp-pil - qcom,msm8953-adsp-pil - qcom,msm8974-adsp-pil diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml index 0643faae2c39..971734085d51 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,msm8996-mss-pil.yaml @@ -220,7 +220,6 @@ allOf: - description: GCC MSS GPLL0 clock - description: GCC MSS SNOC_AXI clock - description: GCC MSS MNOC_AXI clock - - description: RPM PNOC clock - description: RPM QDSS clock clock-names: items: @@ -231,7 +230,6 @@ allOf: - const: gpll0_mss - const: snoc_axi - const: mnoc_axi - - const: pnoc - const: qdss glink-edge: false required: diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml index 689d5d535331..f10f329677d8 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sc7180-pas.yaml @@ -16,6 +16,7 @@ description: properties: compatible: enum: + - qcom,sc7180-adsp-pas - qcom,sc7180-mpss-pas - qcom,sc7280-mpss-pas @@ -30,26 +31,6 @@ properties: items: - const: xo - interrupts: - minItems: 6 - - interrupt-names: - minItems: 6 - - power-domains: - minItems: 2 - items: - - description: CX power domain - - description: MX power domain - - description: MSS power domain - - power-domain-names: - minItems: 2 - items: - - const: cx - - const: mx - - const: mss - memory-region: maxItems: 1 description: Reference to the reserved-memory for the Hexagon core @@ -75,19 +56,69 @@ allOf: properties: compatible: enum: + - qcom,sc7180-adsp-pas + then: + properties: + interrupts: + maxItems: 5 + interrupt-names: + maxItems: 5 + else: + properties: + interrupts: + minItems: 6 + interrupt-names: + minItems: 6 + + - if: + properties: + compatible: + enum: + - qcom,sc7180-adsp-pas + then: + properties: + power-domains: + items: + - description: LCX power domain + - description: LMX power domain + power-domain-names: + items: + - const: lcx + - const: lmx + + - if: + properties: + compatible: + enum: - qcom,sc7180-mpss-pas then: properties: power-domains: - minItems: 3 + items: + - description: CX power domain + - description: MX power domain + - description: MSS power domain power-domain-names: - minItems: 3 - else: + items: + - const: cx + - const: mx + - const: mss + + - if: + properties: + compatible: + enum: + - qcom,sc7280-mpss-pas + then: properties: power-domains: - maxItems: 2 + items: + - description: CX power domain + - description: MX power domain power-domain-names: - maxItems: 2 + items: + - const: cx + - const: mx unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sm6375-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sm6375-pas.yaml new file mode 100644 index 000000000000..3e4a03eb4532 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sm6375-pas.yaml @@ -0,0 +1,145 @@ +# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/remoteproc/qcom,sm6375-pas.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SM6375 Peripheral Authentication Service + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +description: + Qualcomm SM6375 SoC Peripheral Authentication Service loads and boots + firmware on the Qualcomm DSP Hexagon cores. + +properties: + compatible: + enum: + - qcom,sm6375-adsp-pas + - qcom,sm6375-cdsp-pas + - qcom,sm6375-mpss-pas + + reg: + maxItems: 1 + + clocks: + items: + - description: XO clock + + clock-names: + items: + - const: xo + + memory-region: + maxItems: 1 + description: Reference to the reserved-memory for the Hexagon core + + firmware-name: + $ref: /schemas/types.yaml#/definitions/string + description: Firmware name for the Hexagon core + + smd-edge: false + +required: + - compatible + - reg + +allOf: + - $ref: /schemas/remoteproc/qcom,pas-common.yaml# + - if: + properties: + compatible: + enum: + - qcom,sm6375-adsp-pas + - qcom,sm6375-cdsp-pas + then: + properties: + interrupts: + maxItems: 5 + interrupt-names: + maxItems: 5 + else: + properties: + interrupts: + minItems: 6 + interrupt-names: + minItems: 6 + + - if: + properties: + compatible: + enum: + - qcom,sm6375-adsp-pas + then: + properties: + power-domains: + items: + - description: LCX power domain + - description: LMX power domain + power-domain-names: + items: + - const: lcx + - const: lmx + + - if: + properties: + compatible: + enum: + - qcom,sm6375-cdsp-pas + - qcom,sm6375-mpss-pas + then: + properties: + power-domains: + items: + - description: CX power domain + power-domain-names: + items: + - const: cx + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/clock/qcom,rpmcc.h> + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/mailbox/qcom-ipcc.h> + #include <dt-bindings/power/qcom-rpmpd.h> + + remoteproc_adsp: remoteproc@a400000 { + compatible = "qcom,sm6375-adsp-pas"; + reg = <0x0a400000 0x100>; + + interrupts-extended = <&intc GIC_SPI 282 IRQ_TYPE_LEVEL_HIGH>, + <&smp2p_adsp_in 0 IRQ_TYPE_EDGE_RISING>, + <&smp2p_adsp_in 1 IRQ_TYPE_EDGE_RISING>, + <&smp2p_adsp_in 2 IRQ_TYPE_EDGE_RISING>, + <&smp2p_adsp_in 3 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "wdog", "fatal", "ready", + "handover", "stop-ack"; + + clocks = <&rpmcc RPM_SMD_XO_CLK_SRC>; + clock-names = "xo"; + + power-domains = <&rpmpd SM6375_VDD_LPI_CX>, + <&rpmpd SM6375_VDD_LPI_MX>; + power-domain-names = "lcx", "lmx"; + + memory-region = <&pil_adsp_mem>; + + qcom,smem-states = <&smp2p_adsp_out 0>; + qcom,smem-state-names = "stop"; + + glink-edge { + interrupts-extended = <&ipcc IPCC_CLIENT_LPASS + IPCC_MPROC_SIGNAL_GLINK_QMP + IRQ_TYPE_EDGE_RISING>; + mboxes = <&ipcc IPCC_CLIENT_LPASS + IPCC_MPROC_SIGNAL_GLINK_QMP>; + + label = "lpass"; + qcom,remote-pid = <2>; + + /* ... */ + }; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml index 4bea679a0f61..5c280117dc93 100644 --- a/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/renesas,rcar-rproc.yaml @@ -31,7 +31,7 @@ properties: remoteproc device. This is variable and describes the memories shared with the remote processor (e.g. remoteproc firmware and carveouts, rpmsg vrings, ...). - (see ../reserved-memory/reserved-memory.yaml) + (see reserved-memory/reserved-memory.yaml in dtschema project) required: - compatible diff --git a/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml b/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml index baccd98754a9..faf16cf14085 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml +++ b/Documentation/devicetree/bindings/remoteproc/ti,pru-rproc.yaml @@ -66,6 +66,17 @@ properties: Should contain the name of the default firmware image file located on the firmware search path. + interrupts: + maxItems: 1 + description: + Interrupt specifiers enable the virtio/rpmsg communication between MPU + and the PRU/RTU cores. For the values of the interrupt cells please refer + to interrupt-controller/ti,pruss-intc.yaml schema. + + interrupt-names: + items: + - const: vring + if: properties: compatible: @@ -171,6 +182,9 @@ examples: <0x22400 0x100>; reg-names = "iram", "control", "debug"; firmware-name = "am65x-pru0_0-fw"; + interrupt-parent = <&icssg0_intc>; + interrupts = <16 2 2>; + interrupt-names = "vring"; }; rtu0_0: rtu@4000 { @@ -180,6 +194,9 @@ examples: <0x23400 0x100>; reg-names = "iram", "control", "debug"; firmware-name = "am65x-rtu0_0-fw"; + interrupt-parent = <&icssg0_intc>; + interrupts = <20 4 4>; + interrupt-names = "vring"; }; tx_pru0_0: txpru@a000 { @@ -198,6 +215,9 @@ examples: <0x24400 0x100>; reg-names = "iram", "control", "debug"; firmware-name = "am65x-pru0_1-fw"; + interrupt-parent = <&icssg0_intc>; + interrupts = <18 3 3>; + interrupt-names = "vring"; }; rtu0_1: rtu@6000 { @@ -207,6 +227,9 @@ examples: <0x23c00 0x100>; reg-names = "iram", "control", "debug"; firmware-name = "am65x-rtu0_1-fw"; + interrupt-parent = <&icssg0_intc>; + interrupts = <22 5 5>; + interrupt-names = "vring"; }; tx_pru0_1: txpru@c000 { diff --git a/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml b/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml deleted file mode 100644 index 851ec24d6142..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/framebuffer.yaml +++ /dev/null @@ -1,52 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/framebuffer.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: /reserved-memory framebuffer node - -maintainers: - - devicetree-spec@vger.kernel.org - -allOf: - - $ref: reserved-memory.yaml - -properties: - compatible: - const: framebuffer - description: > - This indicates a region of memory meant to be used as a framebuffer for - a set of display devices. It can be used by an operating system to keep - the framebuffer from being overwritten and use it as the backing memory - for a display device (such as simple-framebuffer). - -unevaluatedProperties: false - -examples: - - | - / { - compatible = "foo"; - model = "foo"; - #address-cells = <1>; - #size-cells = <1>; - - chosen { - framebuffer { - compatible = "simple-framebuffer"; - memory-region = <&fb>; - }; - }; - - reserved-memory { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - fb: framebuffer@80000000 { - compatible = "framebuffer"; - reg = <0x80000000 0x007e9000>; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml b/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml deleted file mode 100644 index 592f180e6b0d..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml +++ /dev/null @@ -1,40 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/memory-region.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Reserved Memory Region - -maintainers: - - devicetree-spec@vger.kernel.org - -description: | - Regions in the /reserved-memory node may be referenced by other device - nodes by adding a memory-region property to the device node. - -select: true - -properties: - memory-region: - $ref: /schemas/types.yaml#/definitions/phandle-array - description: > - Phandle to a /reserved-memory child node assigned to the device. - - memory-region-names: - $ref: /schemas/types.yaml#/definitions/string-array - description: > - A list of names, one for each corresponding entry in the - memory-region property - -additionalProperties: true - -examples: - - | - fb0: video@12300000 { - /* ... */ - reg = <0x12300000 0x1000>; - memory-region = <&display_reserved>; - }; - -... diff --git a/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml b/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml index bab982f00485..46407e9c1d4f 100644 --- a/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml +++ b/Documentation/devicetree/bindings/reserved-memory/qcom,rmtfs-mem.yaml @@ -26,6 +26,17 @@ properties: description: > identifier of the client to use this region for buffers + qcom,use-guard-pages: + type: boolean + description: > + Indicates that the firmware, or hardware, does not gracefully handle + memory protection of this region when placed adjacent to other protected + memory regions, and that padding around the used portion of the memory + region is necessary. + + When this is set, the first and last page should be left unused, and the + effective size of the region will thereby shrink with two pages. + qcom,vmid: $ref: /schemas/types.yaml#/definitions/uint32-array description: > diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt index 1810701a8509..8ce72996d500 100644 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt @@ -1 +1 @@ -This file has been moved to reserved-memory.yaml. +This file has been moved to reserved-memory.yaml in the dtschema repository. diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml deleted file mode 100644 index c680e397cfd2..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml +++ /dev/null @@ -1,181 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/reserved-memory.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: /reserved-memory Child Node Common - -maintainers: - - devicetree-spec@vger.kernel.org - -description: > - Reserved memory is specified as a node under the /reserved-memory node. The - operating system shall exclude reserved memory from normal usage one can - create child nodes describing particular reserved (excluded from normal use) - memory regions. Such memory regions are usually designed for the special - usage by various device drivers. - - Each child of the reserved-memory node specifies one or more regions - of reserved memory. Each child node may either use a 'reg' property to - specify a specific range of reserved memory, or a 'size' property with - optional constraints to request a dynamically allocated block of - memory. - - Following the generic-names recommended practice, node names should - reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). - Unit address (@<address>) should be appended to the name if the node - is a static allocation. - -properties: - reg: true - - size: - oneOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - $ref: /schemas/types.yaml#/definitions/uint64 - description: > - Length based on parent's \#size-cells. Size in bytes of memory to - reserve. - - alignment: - oneOf: - - $ref: /schemas/types.yaml#/definitions/uint32 - - $ref: /schemas/types.yaml#/definitions/uint64 - description: > - Length based on parent's \#size-cells. Address boundary for - alignment of allocation. - - alloc-ranges: - $ref: /schemas/types.yaml#/definitions/uint32-array - description: > - Address and Length pairs. Specifies regions of memory that are - acceptable to allocate from. - - iommu-addresses: - $ref: /schemas/types.yaml#/definitions/phandle-array - description: > - A list of phandle and specifier pairs that describe static IO virtual - address space mappings and carveouts associated with a given reserved - memory region. The phandle in the first cell refers to the device for - which the mapping or carveout is to be created. - - The specifier consists of an address/size pair and denotes the IO - virtual address range of the region for the given device. The exact - format depends on the values of the "#address-cells" and "#size-cells" - properties of the device referenced via the phandle. - - When used in combination with a "reg" property, an IOVA mapping is to - be established for this memory region. One example where this can be - useful is to create an identity mapping for physical memory that the - firmware has configured some hardware to access (such as a bootsplash - framebuffer). - - If no "reg" property is specified, the "iommu-addresses" property - defines carveout regions in the IOVA space for the given device. This - can be useful if a certain memory region should not be mapped through - the IOMMU. - - no-map: - type: boolean - description: > - Indicates the operating system must not create a virtual mapping - of the region as part of its standard mapping of system memory, - nor permit speculative access to it under any circumstances other - than under the control of the device driver using the region. - - reusable: - type: boolean - description: > - The operating system can use the memory in this region with the - limitation that the device driver(s) owning the region need to be - able to reclaim it back. Typically that means that the operating - system can use that region to store volatile or cached data that - can be otherwise regenerated or migrated elsewhere. - -allOf: - - if: - required: - - no-map - - then: - not: - required: - - reusable - - - if: - required: - - reusable - - then: - not: - required: - - no-map - -oneOf: - - oneOf: - - required: - - reg - - - required: - - size - - - oneOf: - # IOMMU reservations - - required: - - iommu-addresses - - # IOMMU mappings - - required: - - reg - - iommu-addresses - -additionalProperties: true - -examples: - - | - / { - compatible = "foo"; - model = "foo"; - - #address-cells = <2>; - #size-cells = <2>; - - reserved-memory { - #address-cells = <2>; - #size-cells = <2>; - ranges; - - adsp_resv: reservation-adsp { - /* - * Restrict IOVA mappings for ADSP buffers to the 512 MiB region - * from 0x40000000 - 0x5fffffff. Anything outside is reserved by - * the ADSP for I/O memory and private memory allocations. - */ - iommu-addresses = <&adsp 0x0 0x00000000 0x00 0x40000000>, - <&adsp 0x0 0x60000000 0xff 0xa0000000>; - }; - - fb: framebuffer@90000000 { - reg = <0x0 0x90000000 0x0 0x00800000>; - iommu-addresses = <&dc0 0x0 0x90000000 0x0 0x00800000>; - }; - }; - - bus@0 { - #address-cells = <1>; - #size-cells = <1>; - ranges = <0x0 0x0 0x0 0x40000000>; - - adsp: adsp@2990000 { - reg = <0x2990000 0x2000>; - memory-region = <&adsp_resv>; - }; - - dc0: display@15200000 { - reg = <0x15200000 0x10000>; - memory-region = <&fb>; - }; - }; - }; -... diff --git a/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml b/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml deleted file mode 100644 index 457de0920cd1..000000000000 --- a/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml +++ /dev/null @@ -1,97 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/reserved-memory/shared-dma-pool.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: /reserved-memory DMA pool - -maintainers: - - devicetree-spec@vger.kernel.org - -allOf: - - $ref: reserved-memory.yaml - -properties: - compatible: - oneOf: - - const: shared-dma-pool - description: > - This indicates a region of memory meant to be used as a shared - pool of DMA buffers for a set of devices. It can be used by an - operating system to instantiate the necessary pool management - subsystem if necessary. - - - const: restricted-dma-pool - description: > - This indicates a region of memory meant to be used as a pool - of restricted DMA buffers for a set of devices. The memory - region would be the only region accessible to those devices. - When using this, the no-map and reusable properties must not - be set, so the operating system can create a virtual mapping - that will be used for synchronization. The main purpose for - restricted DMA is to mitigate the lack of DMA access control - on systems without an IOMMU, which could result in the DMA - accessing the system memory at unexpected times and/or - unexpected addresses, possibly leading to data leakage or - corruption. The feature on its own provides a basic level of - protection against the DMA overwriting buffer contents at - unexpected times. However, to protect against general data - leakage and system memory corruption, the system needs to - provide way to lock down the memory access, e.g., MPU. Note - that since coherent allocation needs remapping, one must set - up another device coherent pool by shared-dma-pool and use - dma_alloc_from_dev_coherent instead for atomic coherent - allocation. - - linux,cma-default: - type: boolean - description: > - If this property is present, then Linux will use the region for - the default pool of the contiguous memory allocator. - - linux,dma-default: - type: boolean - description: > - If this property is present, then Linux will use the region for - the default pool of the consistent DMA allocator. - -if: - properties: - compatible: - contains: - const: restricted-dma-pool -then: - properties: - no-map: false - reusable: false - -unevaluatedProperties: false - -examples: - - | - reserved-memory { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - /* global autoconfigured region for contiguous allocations */ - linux,cma { - compatible = "shared-dma-pool"; - reusable; - size = <0x4000000>; - alignment = <0x2000>; - linux,cma-default; - }; - - display_reserved: framebuffer@78000000 { - reg = <0x78000000 0x800000>; - }; - - restricted_dma_reserved: restricted-dma-pool@50000000 { - compatible = "restricted-dma-pool"; - reg = <0x50000000 0x4000000>; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/riscv/cpus.yaml b/Documentation/devicetree/bindings/riscv/cpus.yaml index 97e8441eda1c..f392e367d673 100644 --- a/Documentation/devicetree/bindings/riscv/cpus.yaml +++ b/Documentation/devicetree/bindings/riscv/cpus.yaml @@ -47,6 +47,7 @@ properties: - sifive,u74-mc - thead,c906 - thead,c910 + - thead,c920 - const: riscv - items: - enum: diff --git a/Documentation/devicetree/bindings/riscv/extensions.yaml b/Documentation/devicetree/bindings/riscv/extensions.yaml index cc1f546fdbdc..c91ab0e46648 100644 --- a/Documentation/devicetree/bindings/riscv/extensions.yaml +++ b/Documentation/devicetree/bindings/riscv/extensions.yaml @@ -128,6 +128,12 @@ properties: changes to interrupts as frozen at commit ccbddab ("Merge pull request #42 from riscv/jhauser-2023-RC4") of riscv-aia. + - const: smstateen + description: | + The standard Smstateen extension for controlling access to CSRs + added by other RISC-V extensions in H/S/VS/U/VU modes and as + ratified at commit a28bfae (Ratified (#7)) of riscv-state-enable. + - const: ssaia description: | The standard Ssaia supervisor-level extension for the advanced @@ -212,6 +218,12 @@ properties: ratified in the 20191213 version of the unprivileged ISA specification. + - const: zicond + description: + The standard Zicond extension for conditional arithmetic and + conditional-select/move operations as ratified in commit 95cf1f9 + ("Add changes requested by Ved during signoff") of riscv-zicond. + - const: zicsr description: | The standard Zicsr extension for control and status register diff --git a/Documentation/devicetree/bindings/riscv/sophgo.yaml b/Documentation/devicetree/bindings/riscv/sophgo.yaml new file mode 100644 index 000000000000..86748c5390be --- /dev/null +++ b/Documentation/devicetree/bindings/riscv/sophgo.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/riscv/sophgo.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sophgo SoC-based boards + +maintainers: + - Chao Wei <chao.wei@sophgo.com> + - Chen Wang <unicorn_wang@outlook.com> + +description: + Sophgo SoC-based boards + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - enum: + - milkv,duo + - const: sophgo,cv1800b + - items: + - enum: + - milkv,pioneer + - const: sophgo,sg2042 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml index 457a6e43d810..afa52af442a7 100644 --- a/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml +++ b/Documentation/devicetree/bindings/rng/amlogic,meson-rng.yaml @@ -14,6 +14,7 @@ properties: compatible: enum: - amlogic,meson-rng + - amlogic,meson-s4-rng reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml b/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml index 187b172d0cca..717f6b321f88 100644 --- a/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml +++ b/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml @@ -15,7 +15,9 @@ maintainers: properties: compatible: - const: st,stm32-rng + enum: + - st,stm32-rng + - st,stm32mp13-rng reg: maxItems: 1 @@ -30,11 +32,27 @@ properties: type: boolean description: If set enable the clock detection management + st,rng-lock-conf: + type: boolean + description: If set, the RNG configuration in RNG_CR, RNG_HTCR and + RNG_NSCR will be locked. + required: - compatible - reg - clocks +allOf: + - if: + properties: + compatible: + contains: + enum: + - st,stm32-rng + then: + properties: + st,rng-lock-conf: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/rtc/amlogic,meson6-rtc.yaml b/Documentation/devicetree/bindings/rtc/amlogic,meson6-rtc.yaml index 8bf7d3a9be98..3a4551253e3e 100644 --- a/Documentation/devicetree/bindings/rtc/amlogic,meson6-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/amlogic,meson6-rtc.yaml @@ -13,6 +13,7 @@ maintainers: allOf: - $ref: rtc.yaml# - $ref: /schemas/nvmem/nvmem.yaml# + - $ref: /schemas/nvmem/nvmem-deprecated-cells.yaml# properties: compatible: diff --git a/Documentation/devicetree/bindings/rtc/cirrus,ep9301-rtc.yaml b/Documentation/devicetree/bindings/rtc/cirrus,ep9301-rtc.yaml new file mode 100644 index 000000000000..a95f6af2b1c0 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/cirrus,ep9301-rtc.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/cirrus,ep9301-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cirrus EP93xx Real Time Clock controller + +maintainers: + - Hartley Sweeten <hsweeten@visionengravers.com> + - Alexander Sverdlin <alexander.sverdlin@gmail.com> + +allOf: + - $ref: rtc.yaml# + +properties: + compatible: + oneOf: + - const: cirrus,ep9301-rtc + - items: + - enum: + - cirrus,ep9302-rtc + - cirrus,ep9307-rtc + - cirrus,ep9312-rtc + - cirrus,ep9315-rtc + - const: cirrus,ep9301-rtc + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + rtc@80920000 { + compatible = "cirrus,ep9301-rtc"; + reg = <0x80920000 0x100>; + }; diff --git a/Documentation/devicetree/bindings/rtc/epson,rtc7301.txt b/Documentation/devicetree/bindings/rtc/epson,rtc7301.txt deleted file mode 100644 index 5f9df3f1467c..000000000000 --- a/Documentation/devicetree/bindings/rtc/epson,rtc7301.txt +++ /dev/null @@ -1,16 +0,0 @@ -EPSON TOYOCOM RTC-7301SF/DG - -Required properties: - -- compatible: Should be "epson,rtc7301sf" or "epson,rtc7301dg" -- reg: Specifies base physical address and size of the registers. -- interrupts: A single interrupt specifier. - -Example: - -rtc: rtc@44a00000 { - compatible = "epson,rtc7301dg"; - reg = <0x44a00000 0x10000>; - interrupt-parent = <&axi_intc_0>; - interrupts = <3 2>; -}; diff --git a/Documentation/devicetree/bindings/rtc/epson,rtc7301.yaml b/Documentation/devicetree/bindings/rtc/epson,rtc7301.yaml new file mode 100644 index 000000000000..bdb5cadb31cc --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/epson,rtc7301.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/epson,rtc7301.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Epson Toyocom RTC-7301SF/DG + +description: + The only difference between the two variants is the packaging. + The DG variant is a DIL package, and the SF variant is a flat + package. + +maintainers: + - Akinobu Mita <akinobu.mita@gmail.com> + +properties: + compatible: + enum: + - epson,rtc7301dg + - epson,rtc7301sf + + reg: + maxItems: 1 + + reg-io-width: + description: + The size (in bytes) of the IO accesses that should be performed + on the device. + enum: [1, 4] + default: 4 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + rtc: rtc@44a00000 { + compatible = "epson,rtc7301dg"; + reg = <0x44a00000 0x10000>; + reg-io-width = <4>; + interrupt-parent = <&axi_intc_0>; + interrupts = <3 2>; + }; diff --git a/Documentation/devicetree/bindings/rtc/maxim,mcp795.txt b/Documentation/devicetree/bindings/rtc/maxim,mcp795.txt deleted file mode 100644 index a59fdd8c236d..000000000000 --- a/Documentation/devicetree/bindings/rtc/maxim,mcp795.txt +++ /dev/null @@ -1,11 +0,0 @@ -* Maxim MCP795 SPI Serial Real-Time Clock - -Required properties: -- compatible: Should contain "maxim,mcp795". -- reg: SPI address for chip - -Example: - mcp795: rtc@0 { - compatible = "maxim,mcp795"; - reg = <0>; - }; diff --git a/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml b/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml index 27a9de10f0af..7680089d1d92 100644 --- a/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml +++ b/Documentation/devicetree/bindings/rtc/microcrystal,rv3032.yaml @@ -38,6 +38,8 @@ properties: - 3000 - 4400 + wakeup-source: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/rtc/mstar,ssd202d-rtc.yaml b/Documentation/devicetree/bindings/rtc/mstar,ssd202d-rtc.yaml new file mode 100644 index 000000000000..4c1f22ef5a2c --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/mstar,ssd202d-rtc.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/mstar,ssd202d-rtc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mstar SSD202D Real Time Clock + +maintainers: + - Daniel Palmer <daniel@0x0f.com> + - Romain Perier <romain.perier@gmail.com> + +allOf: + - $ref: rtc.yaml# + +properties: + compatible: + enum: + - mstar,ssd202d-rtc + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + rtc@6800 { + compatible = "mstar,ssd202d-rtc"; + reg = <0x6800 0x200>; + }; +... diff --git a/Documentation/devicetree/bindings/rtc/nxp,pcf2123.yaml b/Documentation/devicetree/bindings/rtc/nxp,pcf2123.yaml new file mode 100644 index 000000000000..96e377a4d1bc --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/nxp,pcf2123.yaml @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/nxp,pcf2123.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP PCF2123 SPI Real Time Clock + +maintainers: + - Javier Carrasco <javier.carrasco.cruz@gmail.com> + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + - $ref: rtc.yaml# + +properties: + compatible: + enum: + - nxp,pcf2123 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/arm-gic.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + + rtc@3 { + compatible = "nxp,pcf2123"; + reg = <3>; + interrupts = <GIC_SPI 130 IRQ_TYPE_LEVEL_LOW>; + spi-cs-high; + }; + }; +... diff --git a/Documentation/devicetree/bindings/rtc/nxp,pcf8523.txt b/Documentation/devicetree/bindings/rtc/nxp,pcf8523.txt deleted file mode 100644 index 0b1080c60f63..000000000000 --- a/Documentation/devicetree/bindings/rtc/nxp,pcf8523.txt +++ /dev/null @@ -1,18 +0,0 @@ -* NXP PCF8523 Real Time Clock - -Required properties: -- compatible: Should contain "nxp,pcf8523". -- reg: I2C address for chip. - -Optional property: -- quartz-load-femtofarads: The capacitive load of the quartz(x-tal), - expressed in femto Farad (fF). Valid values are 7000 and 12500. - Default value (if no value is specified) is 12500fF. - -Example: - -pcf8523: rtc@68 { - compatible = "nxp,pcf8523"; - reg = <0x68>; - quartz-load-femtofarads = <7000>; -}; diff --git a/Documentation/devicetree/bindings/rtc/nxp,pcf8523.yaml b/Documentation/devicetree/bindings/rtc/nxp,pcf8523.yaml new file mode 100644 index 000000000000..d11c8bc16bc0 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/nxp,pcf8523.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/rtc/nxp,pcf8523.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP PCF8523 Real Time Clock + +maintainers: + - Sam Ravnborg <sam@ravnborg.org> + +allOf: + - $ref: rtc.yaml# + +properties: + compatible: + const: nxp,pcf8523 + + reg: + maxItems: 1 + + quartz-load-femtofarads: + description: + The capacitive load of the crystal, expressed in femto Farad (fF). + enum: [ 7000, 12500 ] + default: 12500 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + rtc@68 { + compatible = "nxp,pcf8523"; + reg = <0x68>; + quartz-load-femtofarads = <7000>; + }; + }; diff --git a/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt b/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt deleted file mode 100644 index 7371f525a687..000000000000 --- a/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt +++ /dev/null @@ -1,17 +0,0 @@ -NXP PCF2123 SPI Real Time Clock - -Required properties: -- compatible: should be: "nxp,pcf2123" - or "microcrystal,rv2123" -- reg: should be the SPI slave chipselect address - -Optional properties: -- spi-cs-high: PCF2123 needs chipselect high - -Example: - -pcf2123: rtc@3 { - compatible = "nxp,pcf2123" - reg = <3> - spi-cs-high; -}; diff --git a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml index 2a65f31ac5a0..c9e3c5262c21 100644 --- a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml @@ -45,6 +45,8 @@ properties: - isil,isl1208 # Intersil ISL1218 Low Power RTC with Battery Backed SRAM - isil,isl1218 + # SPI-BUS INTERFACE REAL TIME CLOCK MODULE + - maxim,mcp795 # Real Time Clock Module with I2C-Bus - microcrystal,rv3029 # Real Time Clock diff --git a/Documentation/devicetree/bindings/serial/esp,esp32-acm.yaml b/Documentation/devicetree/bindings/serial/esp,esp32-acm.yaml new file mode 100644 index 000000000000..77fbb2c72171 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/esp,esp32-acm.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause + +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/esp,esp32-acm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ESP32S3 ACM gadget controller + +maintainers: + - Max Filippov <jcmvbkbc@gmail.com> + +description: + Fixed function USB CDC-ACM gadget controller of the Espressif ESP32S3 SoC. + +allOf: + - $ref: serial.yaml# + +properties: + compatible: + const: esp,esp32s3-acm + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + serial@60038000 { + compatible = "esp,esp32s3-acm"; + reg = <0x60038000 0x1000>; + interrupts = <96 3 0>; + }; diff --git a/Documentation/devicetree/bindings/serial/esp,esp32-uart.yaml b/Documentation/devicetree/bindings/serial/esp,esp32-uart.yaml new file mode 100644 index 000000000000..2a80ca997a0c --- /dev/null +++ b/Documentation/devicetree/bindings/serial/esp,esp32-uart.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause + +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/esp,esp32-uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ESP32xx UART controllers + +maintainers: + - Max Filippov <jcmvbkbc@gmail.com> + +description: + ESP32 UART controller is a part of the ESP32 SoC. + ESP32S3 UART controller is a part of the ESP32S3 SoC. + Both SoCs are produced by Espressif Systems Co. Ltd. + +allOf: + - $ref: serial.yaml# + +properties: + compatible: + enum: + - esp,esp32-uart + - esp,esp32s3-uart + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + serial@60000000 { + compatible = "esp,esp32s3-uart"; + reg = <0x60000000 0x80>; + interrupts = <27 1 0>; + clocks = <&serial_clk>; + }; diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml index 40414247d61a..83035553044a 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.yaml @@ -70,6 +70,8 @@ properties: interrupts: maxItems: 1 + wakeup-source: true + fsl,dte-mode: $ref: /schemas/types.yaml#/definitions/flag description: | diff --git a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml index 6a400a5e6fc7..da032effffe6 100644 --- a/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-mxs-auart.yaml @@ -14,10 +14,13 @@ allOf: properties: compatible: - enum: - - fsl,imx23-auart - - fsl,imx28-auart - - alphascale,asm9260-auart + oneOf: + - const: fsl,imx23-auart + - const: alphascale,asm9260-auart + - items: + - enum: + - fsl,imx28-auart + - const: fsl,imx23-auart reg: maxItems: 1 @@ -82,7 +85,7 @@ examples: }; auart0: serial@8006a000 { - compatible = "fsl,imx28-auart"; + compatible = "fsl,imx28-auart", "fsl,imx23-auart"; reg = <0x8006a000 0x2000>; interrupts = <112>; dmas = <&dma_apbx 8>, <&dma_apbx 9>; diff --git a/Documentation/devicetree/bindings/serial/maxim,max310x.txt b/Documentation/devicetree/bindings/serial/maxim,max310x.txt deleted file mode 100644 index 79e10a05a96a..000000000000 --- a/Documentation/devicetree/bindings/serial/maxim,max310x.txt +++ /dev/null @@ -1,48 +0,0 @@ -* Maxim MAX310X advanced Universal Asynchronous Receiver-Transmitter (UART) - -Required properties: -- compatible: Should be one of the following: - - "maxim,max3107" for Maxim MAX3107, - - "maxim,max3108" for Maxim MAX3108, - - "maxim,max3109" for Maxim MAX3109, - - "maxim,max14830" for Maxim MAX14830. -- reg: SPI chip select number. -- interrupts: Specifies the interrupt source of the parent interrupt - controller. The format of the interrupt specifier depends on the - parent interrupt controller. -- clocks: phandle to the IC source clock. -- clock-names: Should be "xtal" if clock is an external crystal or - "osc" if an external clock source is used. - -Optional properties: -- gpio-controller: Marks the device node as a GPIO controller. -- #gpio-cells: Should be two. The first cell is the GPIO number and - the second cell is used to specify the GPIO polarity: - 0 = active high, - 1 = active low. - -Example: - -/ { - clocks { - spi_uart_clk: osc_max14830 { - compatible = "fixed-clock"; - #clock-cells = <0>; - clock-frequency = <3686400>; - }; - - }; -}; - -&spi0 { - max14830: max14830@0 { - compatible = "maxim,max14830"; - reg = <0>; - clocks = <&spi_uart_clk>; - clock-names = "osc"; - interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_LEVEL_LOW>; - gpio-controller; - #gpio-cells = <2>; - }; -}; diff --git a/Documentation/devicetree/bindings/serial/maxim,max310x.yaml b/Documentation/devicetree/bindings/serial/maxim,max310x.yaml new file mode 100644 index 000000000000..889eeaca64a0 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/maxim,max310x.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/maxim,max310x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Maxim MAX310X Advanced Universal Asynchronous Receiver-Transmitter (UART) + +maintainers: + - Hugo Villeneuve <hvilleneuve@dimonoff.com> + +properties: + compatible: + enum: + - maxim,max3107 + - maxim,max3108 + - maxim,max3109 + - maxim,max14830 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + enum: + - xtal # External crystal + - osc # External clock source + + gpio-controller: true + + "#gpio-cells": + const: 2 + + gpio-line-names: + minItems: 1 + maxItems: 16 + +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + - $ref: /schemas/serial/serial.yaml# + - $ref: /schemas/serial/rs485.yaml# + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + serial@2c { + compatible = "maxim,max3107"; + reg = <0x2c>; + clocks = <&xtal4m>; + clock-names = "xtal"; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; + gpio-controller; + #gpio-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml index 04d55fecf47c..a5d67563cd53 100644 --- a/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml +++ b/Documentation/devicetree/bindings/serial/nvidia,tegra20-hsuart.yaml @@ -91,11 +91,6 @@ properties: - description: range upper bound - description: adjustment (in permyriad, i.e. 0.01%) -allOf: - - $ref: serial.yaml - -unevaluatedProperties: false - required: - compatible - reg @@ -106,6 +101,11 @@ required: - dmas - dma-names +allOf: + - $ref: serial.yaml + +unevaluatedProperties: false + examples: - | #include <dt-bindings/clock/tegra30-car.h> diff --git a/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt b/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt deleted file mode 100644 index 1a7e4bff0456..000000000000 --- a/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.txt +++ /dev/null @@ -1,118 +0,0 @@ -* NXP SC16IS7xx advanced Universal Asynchronous Receiver-Transmitter (UART) -* i2c as bus - -Required properties: -- compatible: Should be one of the following: - - "nxp,sc16is740" for NXP SC16IS740, - - "nxp,sc16is741" for NXP SC16IS741, - - "nxp,sc16is750" for NXP SC16IS750, - - "nxp,sc16is752" for NXP SC16IS752, - - "nxp,sc16is760" for NXP SC16IS760, - - "nxp,sc16is762" for NXP SC16IS762. -- reg: I2C address of the SC16IS7xx device. -- interrupts: Should contain the UART interrupt -- clocks: Reference to the IC source clock. - OR (when there is no clock provider visible to the platform) -- clock-frequency: The source clock frequency for the IC. - -Optional properties: -- gpio-controller: Marks the device node as a GPIO controller. -- #gpio-cells: Should be two. The first cell is the GPIO number and - the second cell is used to specify the GPIO polarity: - 0 = active high, - 1 = active low. -- irda-mode-ports: An array that lists the indices of the port that - should operate in IrDA mode. -- nxp,modem-control-line-ports: An array that lists the indices of the port that - should have shared GPIO lines configured as - modem control lines. - -Example: - sc16is750: sc16is750@51 { - compatible = "nxp,sc16is750"; - reg = <0x51>; - clocks = <&clk20m>; - interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; - gpio-controller; - #gpio-cells = <2>; - }; - - sc16is752: sc16is752@53 { - compatible = "nxp,sc16is752"; - reg = <0x53>; - clocks = <&clk20m>; - interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; - nxp,modem-control-line-ports = <1>; /* Port 1 as modem control lines */ - gpio-controller; /* Port 0 as GPIOs */ - #gpio-cells = <2>; - }; - - sc16is752: sc16is752@54 { - compatible = "nxp,sc16is752"; - reg = <0x54>; - clocks = <&clk20m>; - interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; - nxp,modem-control-line-ports = <0 1>; /* Ports 0 and 1 as modem control lines */ - }; - -* spi as bus - -Required properties: -- compatible: Should be one of the following: - - "nxp,sc16is740" for NXP SC16IS740, - - "nxp,sc16is741" for NXP SC16IS741, - - "nxp,sc16is750" for NXP SC16IS750, - - "nxp,sc16is752" for NXP SC16IS752, - - "nxp,sc16is760" for NXP SC16IS760, - - "nxp,sc16is762" for NXP SC16IS762. -- reg: SPI chip select number. -- interrupts: Specifies the interrupt source of the parent interrupt - controller. The format of the interrupt specifier depends on the - parent interrupt controller. -- clocks: phandle to the IC source clock. - -Optional properties: -- gpio-controller: Marks the device node as a GPIO controller. -- #gpio-cells: Should be two. The first cell is the GPIO number and - the second cell is used to specify the GPIO polarity: - 0 = active high, - 1 = active low. -- irda-mode-ports: An array that lists the indices of the port that - should operate in IrDA mode. -- nxp,modem-control-line-ports: An array that lists the indices of the port that - should have shared GPIO lines configured as - modem control lines. - -Example: - sc16is750: sc16is750@0 { - compatible = "nxp,sc16is750"; - reg = <0>; - clocks = <&clk20m>; - interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; - gpio-controller; - #gpio-cells = <2>; - }; - - sc16is752: sc16is752@1 { - compatible = "nxp,sc16is752"; - reg = <1>; - clocks = <&clk20m>; - interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; - nxp,modem-control-line-ports = <1>; /* Port 1 as modem control lines */ - gpio-controller; /* Port 0 as GPIOs */ - #gpio-cells = <2>; - }; - - sc16is752: sc16is752@2 { - compatible = "nxp,sc16is752"; - reg = <2>; - clocks = <&clk20m>; - interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; - nxp,modem-control-line-ports = <0 1>; /* Ports 0 and 1 as modem control lines */ - }; diff --git a/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.yaml b/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.yaml new file mode 100644 index 000000000000..5dec15b7e7c3 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/nxp,sc16is7xx.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/nxp,sc16is7xx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP SC16IS7xx Advanced Universal Asynchronous Receiver-Transmitter (UART) + +maintainers: + - Hugo Villeneuve <hvilleneuve@dimonoff.com> + +properties: + compatible: + enum: + - nxp,sc16is740 + - nxp,sc16is741 + - nxp,sc16is750 + - nxp,sc16is752 + - nxp,sc16is760 + - nxp,sc16is762 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-frequency: + description: + When there is no clock provider visible to the platform, this + is the source crystal or external clock frequency for the IC in Hz. + minimum: 1 + maximum: 80000000 + + gpio-controller: true + + "#gpio-cells": + const: 2 + + gpio-line-names: + minItems: 1 + maxItems: 8 + + irda-mode-ports: + description: | + An array that lists the indices of the port that should operate in IrDA + mode: + 0: port A + 1: port B + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 2 + items: + minimum: 0 + maximum: 1 + + nxp,modem-control-line-ports: + description: | + An array that lists the indices of the port that should have shared GPIO + lines configured as modem control lines: + 0: port A + 1: port B + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 2 + items: + minimum: 0 + maximum: 1 + +required: + - compatible + - reg + - interrupts + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + - $ref: /schemas/serial/serial.yaml# + - $ref: /schemas/serial/rs485.yaml# + +oneOf: + - required: + - clocks + - required: + - clock-frequency + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + serial@51 { + compatible = "nxp,sc16is750"; + reg = <0x51>; + clocks = <&clk20m>; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + gpio-controller; + #gpio-cells = <2>; + }; + + serial@53 { + compatible = "nxp,sc16is752"; + reg = <0x53>; + clocks = <&clk20m>; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + nxp,modem-control-line-ports = <1>; /* Port 1 as modem control lines */ + gpio-controller; /* Port 0 as GPIOs */ + #gpio-cells = <2>; + }; + + serial@54 { + compatible = "nxp,sc16is752"; + reg = <0x54>; + clocks = <&clk20m>; + interrupt-parent = <&gpio3>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + nxp,modem-control-line-ports = <0 1>; /* Ports 0 and 1 as modem control lines */ + }; + }; diff --git a/Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml b/Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml index a052aaef21f4..ea6abfe2d95e 100644 --- a/Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml +++ b/Documentation/devicetree/bindings/serial/qcom,msm-uart.yaml @@ -40,11 +40,11 @@ required: - interrupts - reg -unevaluatedProperties: false - allOf: - $ref: /schemas/serial/serial.yaml# +unevaluatedProperties: false + examples: - | serial@a9c00000 { diff --git a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.yaml b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.yaml index 484b9a51f6a9..ee52bf8e8917 100644 --- a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.yaml +++ b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.yaml @@ -78,8 +78,6 @@ required: - interrupts - reg -unevaluatedProperties: false - allOf: - $ref: /schemas/serial/serial.yaml# @@ -97,6 +95,8 @@ allOf: reg: maxItems: 1 +unevaluatedProperties: false + examples: - | #include <dt-bindings/interrupt-controller/arm-gic.h> diff --git a/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml b/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml index 3fc2601f1338..89f1eb0f2c5a 100644 --- a/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,em-uart.yaml @@ -38,6 +38,13 @@ properties: - const: sclk - const: pclk +required: + - compatible + - reg + - interrupts + - clocks + - clock-names + allOf: - $ref: serial.yaml# @@ -53,13 +60,6 @@ allOf: clock-names: minItems: 2 -required: - - compatible - - reg - - interrupts - - clocks - - clock-names - unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml index 1c7f1276aed6..2046e2dc0a3d 100644 --- a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml @@ -111,8 +111,6 @@ required: - clock-names - power-domains -unevaluatedProperties: false - if: properties: compatible: @@ -125,6 +123,8 @@ then: required: - resets +unevaluatedProperties: false + examples: - | #include <dt-bindings/clock/r8a7795-cpg-mssr.h> diff --git a/Documentation/devicetree/bindings/serial/renesas,scif.yaml b/Documentation/devicetree/bindings/serial/renesas,scif.yaml index 99030fc18c45..4610a5bd580c 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scif.yaml @@ -79,6 +79,7 @@ properties: - enum: - renesas,scif-r9a07g043 # RZ/G2UL and RZ/Five - renesas,scif-r9a07g054 # RZ/V2L + - renesas,scif-r9a08g045 # RZ/G3S - const: renesas,scif-r9a07g044 # RZ/G2{L,LC} fallback reg: diff --git a/Documentation/devicetree/bindings/serial/renesas,scifa.yaml b/Documentation/devicetree/bindings/serial/renesas,scifa.yaml index 499507678cdf..c98657cf4666 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scifa.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scifa.yaml @@ -77,8 +77,6 @@ required: - clock-names - power-domains -unevaluatedProperties: false - if: properties: compatible: @@ -89,6 +87,8 @@ then: required: - resets +unevaluatedProperties: false + examples: - | #include <dt-bindings/clock/r8a7790-cpg-mssr.h> diff --git a/Documentation/devicetree/bindings/serial/renesas,scifb.yaml b/Documentation/devicetree/bindings/serial/renesas,scifb.yaml index 810d8a991fdd..fb695b3111ac 100644 --- a/Documentation/devicetree/bindings/serial/renesas,scifb.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,scifb.yaml @@ -77,8 +77,6 @@ required: - clock-names - power-domains -unevaluatedProperties: false - if: properties: compatible: @@ -89,6 +87,8 @@ then: required: - resets +unevaluatedProperties: false + examples: - | #include <dt-bindings/clock/r8a7740-clock.h> diff --git a/Documentation/devicetree/bindings/serial/rs485.yaml b/Documentation/devicetree/bindings/serial/rs485.yaml index 303a443d9e29..9418fd66a8e9 100644 --- a/Documentation/devicetree/bindings/serial/rs485.yaml +++ b/Documentation/devicetree/bindings/serial/rs485.yaml @@ -29,6 +29,10 @@ properties: default: 0 maximum: 100 + rs485-rts-active-high: + description: drive RTS high when sending (this is the default). + $ref: /schemas/types.yaml#/definitions/flag + rs485-rts-active-low: description: drive RTS low when sending (default is high). $ref: /schemas/types.yaml#/definitions/flag diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml index 8bd88d5cbb11..ac60ab1e35e3 100644 --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml @@ -24,9 +24,6 @@ properties: - enum: - apple,s5l-uart - axis,artpec8-uart - - samsung,s3c2410-uart - - samsung,s3c2412-uart - - samsung,s3c2440-uart - samsung,s3c6400-uart - samsung,s5pv210-uart - samsung,exynos4210-uart @@ -86,8 +83,6 @@ required: - interrupts - reg -unevaluatedProperties: false - allOf: - $ref: serial.yaml# @@ -96,7 +91,6 @@ allOf: compatible: contains: enum: - - samsung,s3c2410-uart - samsung,s5pv210-uart then: properties: @@ -128,6 +122,8 @@ allOf: - const: uart - const: clk_uart_baud0 +unevaluatedProperties: false + examples: - | #include <dt-bindings/clock/samsung,s3c64xx-clock.h> diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml index ea277560a596..65804ca274ae 100644 --- a/Documentation/devicetree/bindings/serial/serial.yaml +++ b/Documentation/devicetree/bindings/serial/serial.yaml @@ -87,16 +87,8 @@ properties: description: TX FIFO threshold configuration (in bytes). -if: - required: - - uart-has-rtscts -then: - properties: - cts-gpios: false - rts-gpios: false - patternProperties: - "^bluetooth|gnss|gps|mcu$": + "^(bluetooth|bluetooth-gnss|gnss|gps|mcu)$": if: type: object then: @@ -136,6 +128,14 @@ patternProperties: required: - compatible +if: + required: + - uart-has-rtscts +then: + properties: + cts-gpios: false + rts-gpios: false + additionalProperties: true examples: diff --git a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml index ec888f48cac8..e802e25923aa 100644 --- a/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml +++ b/Documentation/devicetree/bindings/soc/fsl/cpm_qe/fsl,cpm1-scc-qmc.yaml @@ -64,6 +64,7 @@ patternProperties: description: A channel managed by this controller type: object + additionalProperties: false properties: reg: @@ -100,6 +101,32 @@ patternProperties: Channel assigned Rx time-slots within the Rx time-slots routed by the TSA to this cell. + compatible: + items: + - enum: + - fsl,mpc885-scc-qmc-hdlc + - fsl,mpc866-scc-qmc-hdlc + - const: fsl,cpm1-scc-qmc-hdlc + - const: fsl,qmc-hdlc + + fsl,framer: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the framer node. The framer is in charge of an E1/T1 line + interface connected to the TDM bus. It can be used to get the E1/T1 line + status such as link up/down. + + allOf: + - if: + properties: + compatible: + not: + contains: + const: fsl,qmc-hdlc + then: + properties: + fsl,framer: false + required: - reg - fsl,tx-ts-mask @@ -137,7 +164,7 @@ examples: channel@16 { /* Ch16 : First 4 even TS from all routed from TSA */ reg = <16>; - fsl,mode = "transparent"; + fsl,operational-mode = "transparent"; fsl,reverse-data; fsl,tx-ts-mask = <0x00000000 0x000000aa>; fsl,rx-ts-mask = <0x00000000 0x000000aa>; @@ -146,7 +173,7 @@ examples: channel@17 { /* Ch17 : First 4 odd TS from all routed from TSA */ reg = <17>; - fsl,mode = "transparent"; + fsl,operational-mode = "transparent"; fsl,reverse-data; fsl,tx-ts-mask = <0x00000000 0x00000055>; fsl,rx-ts-mask = <0x00000000 0x00000055>; @@ -154,9 +181,13 @@ examples: channel@19 { /* Ch19 : 8 TS (TS 8..15) from all routed from TSA */ + compatible = "fsl,mpc885-scc-qmc-hdlc", + "fsl,cpm1-scc-qmc-hdlc", + "fsl,qmc-hdlc"; reg = <19>; - fsl,mode = "hdlc"; + fsl,operational-mode = "hdlc"; fsl,tx-ts-mask = <0x00000000 0x0000ff00>; fsl,rx-ts-mask = <0x00000000 0x0000ff00>; + fsl,framer = <&framer>; }; }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml index f0fa92b04b32..3b212f26abc5 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/mediatek,mt7986-wo-ccif.yaml @@ -20,6 +20,7 @@ properties: items: - enum: - mediatek,mt7986-wo-ccif + - mediatek,mt7988-wo-ccif - const: syscon reg: diff --git a/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml index f21eb907ee90..7eda63d5682f 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml +++ b/Documentation/devicetree/bindings/soc/mediatek/mtk-svs.yaml @@ -22,6 +22,7 @@ properties: compatible: enum: - mediatek,mt8183-svs + - mediatek,mt8188-svs - mediatek,mt8192-svs reg: diff --git a/Documentation/devicetree/bindings/soc/nuvoton/nuvoton,gfxi.yaml b/Documentation/devicetree/bindings/soc/nuvoton/nuvoton,gfxi.yaml new file mode 100644 index 000000000000..0222a43977ab --- /dev/null +++ b/Documentation/devicetree/bindings/soc/nuvoton/nuvoton,gfxi.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/nuvoton/nuvoton,gfxi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Graphics Core Information block in Nuvoton SoCs + +maintainers: + - Joseph Liu <kwliu@nuvoton.com> + - Marvin Lin <kflin@nuvoton.com> + +description: + The Graphics Core Information (GFXI) are a block of registers in Nuvoton SoCs + that analyzes Graphics core behavior and provides information in registers. + +properties: + compatible: + items: + - enum: + - nuvoton,npcm750-gfxi + - nuvoton,npcm845-gfxi + - const: syscon + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + gfxi: gfxi@e000 { + compatible = "nuvoton,npcm750-gfxi", "syscon"; + reg = <0xe000 0x100>; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml index 8a4b7ba3aaf6..7b031ef09669 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,geni-se.yaml @@ -52,6 +52,8 @@ properties: iommus: maxItems: 1 + dma-coherent: true + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml index bceb479f74c5..422921cf1f82 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml @@ -35,6 +35,12 @@ properties: '#size-cells': const: 0 + orientation-gpios: + description: Array of input gpios for the Type-C connector orientation indication. + The GPIO indication is used to detect the orientation of the Type-C connector. + The array should contain a gpio entry for each PMIC Glink connector, in reg order. + It is defined that GPIO active level means "CC2" or Reversed/Flipped orientation. + patternProperties: '^connector@\d$': $ref: /schemas/connector/usb-connector.yaml# @@ -44,6 +50,19 @@ patternProperties: required: - compatible +allOf: + - if: + not: + properties: + compatible: + contains: + enum: + - qcom,sm8450-pmic-glink + - qcom,sm8550-pmic-glink + then: + properties: + orientation-gpios: false + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml index e52e176d8cb3..4386b2c3fa4d 100644 --- a/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml +++ b/Documentation/devicetree/bindings/soc/renesas/renesas,rzg2l-sysc.yaml @@ -23,6 +23,7 @@ properties: - renesas,r9a07g043-sysc # RZ/G2UL and RZ/Five - renesas,r9a07g044-sysc # RZ/G2{L,LC} - renesas,r9a07g054-sysc # RZ/V2L + - renesas,r9a08g045-sysc # RZ/G3S reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml index 53b95f348f8e..16ca3ff7b1ae 100644 --- a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml +++ b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml @@ -302,7 +302,7 @@ properties: - description: R-Car E3 (R8A77990) items: - enum: - - renesas,ebisu # Ebisu (RTP0RC77990SEB0010S) + - renesas,ebisu # Ebisu (RTP0RC77990SEB0010S), Ebisu-4D (RTP0RC77990SEB0020S) - const: renesas,r8a77990 - description: R-Car D3 (R8A77995) @@ -335,6 +335,13 @@ properties: - const: renesas,spider-cpu - const: renesas,r8a779f0 + - description: R-Car S4-8 (R8A779F4) + items: + - enum: + - renesas,s4sk # R-Car S4 Starter Kit board (Y-ASK-RCAR-S4-1000BASE-T#WS12) + - const: renesas,r8a779f4 + - const: renesas,r8a779f0 + - description: R-Car V4H (R8A779G0) items: - enum: @@ -474,6 +481,25 @@ properties: - renesas,rzv2mevk2 # RZ/V2M Eval Board v2.0 - const: renesas,r9a09g011 + - description: RZ/G3S (R9A08G045) + items: + - enum: + - renesas,r9a08g045s33 # PCIe support + - const: renesas,r9a08g045 + + - description: RZ/G3S SMARC Module (SoM) + items: + - const: renesas,rzg3s-smarcm # RZ/G3S SMARC Module (SoM) + - const: renesas,r9a08g045s33 # PCIe support + - const: renesas,r9a08g045 + + - description: RZ SMARC Carrier-II Evaluation Kit + items: + - const: renesas,smarc2-evk # RZ SMARC Carrier-II EVK + - const: renesas,rzg3s-smarcm # RZ/G3S SMARC SoM + - const: renesas,r9a08g045s33 # PCIe support + - const: renesas,r9a08g045 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/soc/sti/st,sti-syscon.yaml b/Documentation/devicetree/bindings/soc/sti/st,sti-syscon.yaml new file mode 100644 index 000000000000..5f97d9ff17fb --- /dev/null +++ b/Documentation/devicetree/bindings/soc/sti/st,sti-syscon.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/sti/st,sti-syscon.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STi platform sysconfig + +maintainers: + - Patrice Chotard <patrice.chotard@foss.st.com> + +description: | + Binding for the various sysconfig nodes used within the STi + platform device-tree to point to some common configuration + registers used by other nodes. + +properties: + compatible: + items: + - enum: + - st,stih407-core-syscfg + - st,stih407-flash-syscfg + - st,stih407-front-syscfg + - st,stih407-lpm-syscfg + - st,stih407-rear-syscfg + - st,stih407-sbc-reg-syscfg + - st,stih407-sbc-syscfg + - const: syscon + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + syscfg_sbc: syscon@9620000 { + compatible = "st,stih407-sbc-syscfg", "syscon"; + reg = <0x9620000 0x1000>; + }; + +... diff --git a/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-pmc.yaml b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-pmc.yaml new file mode 100644 index 000000000000..b86f6f53ca95 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/tegra/nvidia,tegra20-pmc.yaml @@ -0,0 +1,416 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/tegra/nvidia,tegra20-pmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Tegra Power Management Controller (PMC) + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + +properties: + compatible: + enum: + - nvidia,tegra20-pmc + - nvidia,tegra30-pmc + - nvidia,tegra114-pmc + - nvidia,tegra124-pmc + - nvidia,tegra210-pmc + + reg: + maxItems: 1 + + clock-names: + items: + # Tegra clock of the same name + - const: pclk + # 32 KHz clock input + - const: clk32k_in + + clocks: + maxItems: 2 + + '#clock-cells': + const: 1 + description: | + Tegra PMC has clk_out_1, clk_out_2, and clk_out_3. PMC also has blink + control which allows 32Khz clock output to Tegra blink pad. + + Consumer of PMC clock should specify the desired clock by having the + clock ID in its "clocks" phandle cell with PMC clock provider. See + include/dt-bindings/soc/tegra-pmc.h for the list of Tegra PMC clock IDs. + + '#interrupt-cells': + const: 2 + description: Specifies number of cells needed to encode an interrupt + source. + + interrupt-controller: true + + nvidia,invert-interrupt: + $ref: /schemas/types.yaml#/definitions/flag + description: Inverts the PMU interrupt signal. The PMU is an external Power + Management Unit, whose interrupt output signal is fed into the PMC. This + signal is optionally inverted, and then fed into the ARM GIC. The PMC is + not involved in the detection or handling of this interrupt signal, + merely its inversion. + + nvidia,core-power-req-active-high: + $ref: /schemas/types.yaml#/definitions/flag + description: core power request active-high + + nvidia,sys-clock-req-active-high: + $ref: /schemas/types.yaml#/definitions/flag + description: system clock request active-high + + nvidia,combined-power-req: + $ref: /schemas/types.yaml#/definitions/flag + description: combined power request for CPU and core + + nvidia,cpu-pwr-good-en: + $ref: /schemas/types.yaml#/definitions/flag + description: CPU power good signal from external PMIC to PMC is enabled + + nvidia,suspend-mode: + $ref: /schemas/types.yaml#/definitions/uint32 + description: the suspend mode that the platform should use + oneOf: + - description: LP0, CPU + Core voltage off and DRAM in self-refresh + const: 0 + - description: LP1, CPU voltage off and DRAM in self-refresh + const: 1 + - description: LP2, CPU voltage off + const: 2 + + nvidia,cpu-pwr-good-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: CPU power good time in microseconds + + nvidia,cpu-pwr-off-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: CPU power off time in microseconds + + nvidia,core-pwr-good-time: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: core power good time in microseconds + items: + - description: oscillator stable time + - description: power stable time + + nvidia,core-pwr-off-time: + $ref: /schemas/types.yaml#/definitions/uint32 + description: core power off time in microseconds + + nvidia,lp0-vec: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: | + Starting address and length of LP0 vector. The LP0 vector contains the + warm boot code that is executed by AVP when resuming from the LP0 state. + The AVP (Audio-Video Processor) is an ARM7 processor and always being + the first boot processor when chip is power on or resume from deep sleep + mode. When the system is resumed from the deep sleep mode, the warm boot + code will restore some PLLs, clocks and then brings up CPU0 for resuming + the system. + items: + - description: starting address of LP0 vector + - description: length of LP0 vector + + core-supply: + description: phandle to voltage regulator connected to the SoC core power + rail + + core-domain: + type: object + description: The vast majority of hardware blocks of Tegra SoC belong to a + core power domain, which has a dedicated voltage rail that powers the + blocks. + additionalProperties: false + properties: + operating-points-v2: + description: Should contain level, voltages and opp-supported-hw + property. The supported-hw is a bitfield indicating SoC speedo or + process ID mask. + + "#power-domain-cells": + const: 0 + + required: + - operating-points-v2 + - "#power-domain-cells" + + i2c-thermtrip: + type: object + description: On Tegra30, Tegra114 and Tegra124 if i2c-thermtrip subnode + exists, hardware-triggered thermal reset will be enabled. + additionalProperties: false + properties: + nvidia,i2c-controller-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: ID of I2C controller to send poweroff command to PMU. + Valid values are described in section 9.2.148 "APBDEV_PMC_SCRATCH53_0" + of the Tegra K1 Technical Reference Manual. + + nvidia,bus-addr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: bus address of the PMU on the I2C bus + + nvidia,reg-addr: + $ref: /schemas/types.yaml#/definitions/uint32 + description: PMU I2C register address to issue poweroff command + + nvidia,reg-data: + $ref: /schemas/types.yaml#/definitions/uint32 + description: power-off command to write to PMU + + nvidia,pinmux-id: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Pinmux used by the hardware when issuing power-off command. + Defaults to 0. Valid values are described in section 12.5.2 "Pinmux + Support" of the Tegra4 Technical Reference Manual. + + required: + - nvidia,i2c-controller-id + - nvidia,bus-addr + - nvidia,reg-addr + - nvidia,reg-data + + powergates: + type: object + additionalProperties: false + description: | + This node contains a hierarchy of power domain nodes, which should match + the powergates on the Tegra SoC. Each powergate node represents a power- + domain on the Tegra SoC that can be power-gated by the Tegra PMC. + + Hardware blocks belonging to a power domain should contain "power-domains" + property that is a phandle pointing to corresponding powergate node. + + The name of the powergate node should be one of the below. Note that not + every powergate is applicable to all Tegra devices and the following list + shows which powergates are applicable to which devices. + + Please refer to Tegra TRM for mode details on the powergate nodes to use + for each power-gate block inside Tegra. + + Name Description Devices Applicable + -------------------------------------------------------------- + 3d 3D Graphics Tegra20/114/124/210 + 3d0 3D Graphics 0 Tegra30 + 3d1 3D Graphics 1 Tegra30 + aud Audio Tegra210 + dfd Debug Tegra210 + dis Display A Tegra114/124/210 + disb Display B Tegra114/124/210 + heg 2D Graphics Tegra30/114/124/210 + iram Internal RAM Tegra124/210 + mpe MPEG Encode All + nvdec NVIDIA Video Decode Engine Tegra210 + nvjpg NVIDIA JPEG Engine Tegra210 + pcie PCIE Tegra20/30/124/210 + sata SATA Tegra30/124/210 + sor Display interfaces Tegra124/210 + ve2 Video Encode Engine 2 Tegra210 + venc Video Encode Engine All + vdec Video Decode Engine Tegra20/30/114/124 + vic Video Imaging Compositor Tegra124/210 + xusba USB Partition A Tegra114/124/210 + xusbb USB Partition B Tegra114/124/210 + xusbc USB Partition C Tegra114/124/210 + + patternProperties: + "^[a-z0-9]+$": + type: object + additionalProperties: false + properties: + clocks: + minItems: 1 + maxItems: 10 + + resets: + minItems: 1 + maxItems: 8 + + power-domains: + maxItems: 1 + + '#power-domain-cells': + const: 0 + description: Must be 0. + + required: + - clocks + - resets + - '#power-domain-cells' + + pinmux: + type: object + additionalProperties: + type: object + description: | + This is a pad configuration node. On Tegra SoCs a pad is a set of pins + which are configured as a group. The pin grouping is a fixed attribute + of the hardware. The PMC can be used to set pad power state and + signaling voltage. A pad can be either in active or power down mode. + The support for power state and signaling voltage configuration varies + depending on the pad in question. 3.3V and 1.8V signaling voltages are + supported on pins where software controllable signaling voltage + switching is available. + + The pad configuration state nodes are placed under the pmc node and + they are referred to by the pinctrl client properties. For more + information see: + + Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + + The pad name should be used as the value of the pins property in pin + configuration nodes. + + The following pads are present on Tegra124 and Tegra132: + + audio, bb, cam, comp, csia, csb, cse, dsi, dsib, dsic, dsid, hdmi, + hsic, hv, lvds, mipi-bias, nand, pex-bias, pex-clk1, pex-clk2, + pex-cntrl, sdmmc1, sdmmc3, sdmmc4, sys_ddc, uart, usb0, usb1, usb2, + usb_bias + + The following pads are present on Tegra210: + + audio, audio-hv, cam, csia, csib, csic, csid, csie, csif, dbg, + debug-nonao, dmic, dp, dsi, dsib, dsic, dsid, emmc, emmc2, gpio, + hdmi, hsic, lvds, mipi-bias, pex-bias, pex-clk1, pex-clk2, pex-cntrl, + sdmmc1, sdmmc3, spi, spi-hv, uart, usb0, usb1, usb2, usb3, usb-bias + additionalProperties: false + properties: + pins: + $ref: /schemas/types.yaml#/definitions/string-array + description: Must contain name of the pad(s) to be configured. + + low-power-enable: + $ref: /schemas/types.yaml#/definitions/flag + description: Configure the pad into power down mode. + + low-power-disable: + $ref: /schemas/types.yaml#/definitions/flag + description: Configure the pad into active mode. + + power-source: + $ref: /schemas/types.yaml#/definitions/uint32 + description: | + Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 or + TEGRA_IO_PAD_VOLTAGE_3V3 to select between signaling voltages. The + values are defined in: + + include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h + + Power state can be configured on all Tegra124 and Tegra132 pads. + None of the Tegra124 or Tegra132 pads support signaling voltage + switching. All of the listed Tegra210 pads except pex-cntrl support + power state configuration. Signaling voltage switching is supported + on the following Tegra210 pads: + + audio, audio-hv, cam, dbg, dmic, gpio, pex-cntrl, sdmmc1, sdmmc3, + spi, spi-hv, uart + + required: + - pins + +required: + - compatible + - reg + - clock-names + - clocks + - '#clock-cells' + +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra124-pmc + then: + properties: + pinmux: + additionalProperties: + type: object + properties: + pins: + items: + enum: [ audio, bb, cam, comp, csia, csb, cse, dsi, dsib, + dsic, dsid, hdmi, hsic, hv, lvds, mipi-bias, nand, + pex-bias, pex-clk1, pex-clk2, pex-cntrl, sdmmc1, + sdmmc3, sdmmc4, sys_ddc, uart, usb0, usb1, usb2, + usb_bias ] + + - if: + properties: + compatible: + contains: + const: nvidia,tegra210-pmc + then: + properties: + pinmux: + additionalProperties: + type: object + properties: + pins: + items: + enum: [ audio, audio-hv, cam, csia, csib, csic, csid, csie, + csif, dbg, debug-nonao, dmic, dp, dsi, dsib, dsic, + dsid, emmc, emmc2, gpio, hdmi, hsic, lvds, mipi-bias, + pex-bias, pex-clk1, pex-clk2, pex-cntrl, sdmmc1, + sdmmc3, spi, spi-hv, uart, usb0, usb1, usb2, usb3, + usb-bias ] + +additionalProperties: false + +dependencies: + "nvidia,suspend-mode": ["nvidia,core-pwr-off-time", "nvidia,cpu-pwr-off-time"] + "nvidia,core-pwr-off-time": ["nvidia,core-pwr-good-time"] + "nvidia,cpu-pwr-off-time": ["nvidia,cpu-pwr-good-time"] + +examples: + - | + #include <dt-bindings/clock/tegra210-car.h> + #include <dt-bindings/pinctrl/pinctrl-tegra-io-pad.h> + #include <dt-bindings/soc/tegra-pmc.h> + + pmc@7000e400 { + compatible = "nvidia,tegra210-pmc"; + reg = <0x7000e400 0x400>; + core-supply = <®ulator>; + clocks = <&tegra_car TEGRA210_CLK_PCLK>, <&clk32k_in>; + clock-names = "pclk", "clk32k_in"; + #clock-cells = <1>; + + nvidia,invert-interrupt; + nvidia,suspend-mode = <0>; + nvidia,cpu-pwr-good-time = <0>; + nvidia,cpu-pwr-off-time = <0>; + nvidia,core-pwr-good-time = <4587 3876>; + nvidia,core-pwr-off-time = <39065>; + nvidia,core-power-req-active-high; + nvidia,sys-clock-req-active-high; + + pd_core: core-domain { + operating-points-v2 = <&core_opp_table>; + #power-domain-cells = <0>; + }; + + powergates { + pd_audio: aud { + clocks = <&tegra_car TEGRA210_CLK_APE>, + <&tegra_car TEGRA210_CLK_APB2APE>; + resets = <&tegra_car 198>; + power-domains = <&pd_core>; + #power-domain-cells = <0>; + }; + + pd_xusbss: xusba { + clocks = <&tegra_car TEGRA210_CLK_XUSB_SS>; + resets = <&tegra_car TEGRA210_CLK_XUSB_SS>; + power-domains = <&pd_core>; + #power-domain-cells = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index fa9f9a853365..60b5e3fd1115 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -13,19 +13,17 @@ select: false definitions: port-base: - $ref: /schemas/graph.yaml#/$defs/port-base + allOf: + - $ref: /schemas/graph.yaml#/$defs/port-base + - $ref: /schemas/sound/dai-params.yaml# properties: - convert-rate: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate - convert-channels: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels - convert-sample-format: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format mclk-fs: $ref: simple-card.yaml#/definitions/mclk-fs endpoint-base: - $ref: /schemas/graph.yaml#/$defs/endpoint-base + allOf: + - $ref: /schemas/graph.yaml#/$defs/endpoint-base + - $ref: /schemas/sound/dai-params.yaml# properties: mclk-fs: $ref: simple-card.yaml#/definitions/mclk-fs @@ -68,12 +66,6 @@ definitions: - pdm - msb - lsb - convert-rate: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate - convert-channels: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels - convert-sample-format: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format dai-tdm-slot-num: description: Number of slots in use. diff --git a/Documentation/devicetree/bindings/sound/audio-graph.yaml b/Documentation/devicetree/bindings/sound/audio-graph.yaml index ed31e04ff6a6..71f52f7e55f6 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph.yaml @@ -9,6 +9,9 @@ title: Audio Graph maintainers: - Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> +allOf: + - $ref: /schemas/sound/dai-params.yaml# + properties: dais: $ref: /schemas/types.yaml#/definitions/phandle-array @@ -30,12 +33,6 @@ properties: widget ("Microphone", "Line", "Headphone", "Speaker"), the second being the machine specific name for the widget. $ref: /schemas/types.yaml#/definitions/non-unique-string-array - convert-rate: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-rate - convert-channels: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-channels - convert-sample-format: - $ref: /schemas/sound/dai-params.yaml#/$defs/dai-sample-format pa-gpios: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/awinic,aw87390.yaml b/Documentation/devicetree/bindings/sound/awinic,aw87390.yaml new file mode 100644 index 000000000000..ba9d8767c5d5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/awinic,aw87390.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/awinic,aw87390.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Awinic Aw87390 Audio Amplifier + +maintainers: + - Weidong Wang <wangweidong.a@awinic.com> + +description: + The awinic aw87390 is specifically designed to improve + the musical output dynamic range, enhance the overall + sound quallity, which is a new high efficiency, low + noise, constant large volume, 6th Smart K audio amplifier. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: awinic,aw87390 + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + + awinic,audio-channel: + description: + It is used to distinguish multiple PA devices, so that different + configurations can be loaded to different PA devices + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + +required: + - compatible + - reg + - "#sound-dai-cells" + - awinic,audio-channel + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + audio-codec@58 { + compatible = "awinic,aw87390"; + reg = <0x58>; + #sound-dai-cells = <0>; + awinic,audio-channel = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml b/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml index 4051c2538caf..ac5f2e0f42cb 100644 --- a/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml +++ b/Documentation/devicetree/bindings/sound/awinic,aw88395.yaml @@ -14,14 +14,12 @@ description: digital Smart K audio amplifier with an integrated 10.25V smart boost convert. -allOf: - - $ref: dai-common.yaml# - properties: compatible: enum: - awinic,aw88395 - awinic,aw88261 + - awinic,aw88399 reg: maxItems: 1 @@ -32,11 +30,36 @@ properties: reset-gpios: maxItems: 1 + awinic,audio-channel: + description: + It is used to distinguish multiple PA devices, so that different + configurations can be loaded to different PA devices + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 7 + + awinic,sync-flag: + description: + Flag bit used to keep the phase synchronized in the case of multiple PA + $ref: /schemas/types.yaml#/definitions/flag + required: - compatible - reg - '#sound-dai-cells' - - reset-gpios + - awinic,audio-channel + +allOf: + - $ref: dai-common.yaml# + - if: + properties: + compatible: + contains: + enum: + - awinic,aw88261 + then: + properties: + reset-gpios: false unevaluatedProperties: false @@ -51,5 +74,7 @@ examples: reg = <0x34>; #sound-dai-cells = <0>; reset-gpios = <&gpio 10 GPIO_ACTIVE_LOW>; + awinic,audio-channel = <0>; + awinic,sync-flag; }; }; diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml index 4118aa54bbd5..7f9d8c7a635a 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,cs42l43.yaml @@ -83,7 +83,7 @@ properties: Current at which the headset micbias sense clamp will engage, 0 to disable. enum: [ 0, 14, 24, 43, 52, 61, 71, 90, 99 ] - default: 0 + default: 14 cirrus,bias-ramp-ms: description: @@ -97,7 +97,7 @@ properties: Time in microseconds the type detection will run for. Long values will cause more audible effects, but give more accurate detection. enum: [ 20, 100, 1000, 10000, 50000, 75000, 100000, 200000 ] - default: 10000 + default: 1000 cirrus,button-automute: type: boolean diff --git a/Documentation/devicetree/bindings/sound/dai-params.yaml b/Documentation/devicetree/bindings/sound/dai-params.yaml index f5fb71f9b603..cd8508175564 100644 --- a/Documentation/devicetree/bindings/sound/dai-params.yaml +++ b/Documentation/devicetree/bindings/sound/dai-params.yaml @@ -11,15 +11,14 @@ maintainers: select: false -$defs: - - dai-channels: +properties: + convert-channels: description: Number of audio channels used by DAI $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1 maximum: 32 - dai-sample-format: + convert-sample-format: description: Audio sample format used by DAI $ref: /schemas/types.yaml#/definitions/string enum: @@ -29,12 +28,10 @@ $defs: - s24_3le - s32_le - dai-sample-rate: + convert-rate: description: Audio sample rate used by DAI $ref: /schemas/types.yaml#/definitions/uint32 minimum: 8000 maximum: 192000 -properties: {} - additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/dialog,da7219.yaml b/Documentation/devicetree/bindings/sound/dialog,da7219.yaml index eb7d219e2c86..19137abdba3e 100644 --- a/Documentation/devicetree/bindings/sound/dialog,da7219.yaml +++ b/Documentation/devicetree/bindings/sound/dialog,da7219.yaml @@ -89,6 +89,7 @@ properties: da7219_aad: type: object + additionalProperties: false description: Configuration of advanced accessory detection. properties: diff --git a/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml b/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml index ff5cd9241941..b522ed7dcc51 100644 --- a/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,qmc-audio.yaml @@ -33,6 +33,7 @@ patternProperties: description: A DAI managed by this controller type: object + additionalProperties: false properties: reg: diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml index 90520f89208b..77af276ed2a2 100644 --- a/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml +++ b/Documentation/devicetree/bindings/sound/mediatek,mt8188-afe.yaml @@ -29,7 +29,7 @@ properties: maxItems: 1 description: | Shared memory region for AFE memif. A "shared-dma-pool". - See ../reserved-memory/reserved-memory.yaml for details. + See dtschema reserved-memory/shared-dma-pool.yaml for details. mediatek,topckgen: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml b/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml index 43b3b67bdf3b..4c8c95057ef7 100644 --- a/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml +++ b/Documentation/devicetree/bindings/sound/mediatek,mt8188-mt6359.yaml @@ -17,6 +17,7 @@ properties: enum: - mediatek,mt8188-mt6359-evb - mediatek,mt8188-nau8825 + - mediatek,mt8188-rt5682s audio-routing: description: diff --git a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml index d80083df03eb..bdf7b0960533 100644 --- a/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml +++ b/Documentation/devicetree/bindings/sound/mt8186-mt6366-rt1019-rt5682s.yaml @@ -17,6 +17,7 @@ properties: enum: - mediatek,mt8186-mt6366-rt1019-rt5682s-sound - mediatek,mt8186-mt6366-rt5682s-max98360-sound + - mediatek,mt8186-mt6366-rt5650-sound mediatek,platform: $ref: /schemas/types.yaml#/definitions/phandle diff --git a/Documentation/devicetree/bindings/sound/nxp,tfa9879.yaml b/Documentation/devicetree/bindings/sound/nxp,tfa9879.yaml new file mode 100644 index 000000000000..df26248573ad --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nxp,tfa9879.yaml @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/nxp,tfa9879.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP TFA9879 class-D audio amplifier + +maintainers: + - Peter Rosin <peda@axentia.se> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: nxp,tfa9879 + + reg: + maxItems: 1 + + "#sound-dai-cells": + const: 0 + +required: + - compatible + - reg + - '#sound-dai-cells' + +unevaluatedProperties: false + +examples: + - | + i2c1 { + #address-cells = <1>; + #size-cells = <0>; + amplifier@6c { + compatible = "nxp,tfa9879"; + reg = <0x6c>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2c1>; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/pcm512x.txt b/Documentation/devicetree/bindings/sound/pcm512x.txt index 3aae3b41bd8e..77006a4aec4a 100644 --- a/Documentation/devicetree/bindings/sound/pcm512x.txt +++ b/Documentation/devicetree/bindings/sound/pcm512x.txt @@ -1,12 +1,12 @@ -PCM512x audio CODECs +PCM512x and TAS575x audio CODECs/amplifiers These devices support both I2C and SPI (configured with pin strapping -on the board). +on the board). The TAS575x devices only support I2C. Required properties: - - compatible : One of "ti,pcm5121", "ti,pcm5122", "ti,pcm5141" or - "ti,pcm5142" + - compatible : One of "ti,pcm5121", "ti,pcm5122", "ti,pcm5141", + "ti,pcm5142", "ti,tas5754" or "ti,tas5756" - reg : the I2C address of the device for I2C, the chip select number for SPI. @@ -25,6 +25,7 @@ Optional properties: through <6>. The device will be configured for clock input on the given pll-in pin and PLL output on the given pll-out pin. An external connection from the pll-out pin to the SCLK pin is assumed. + Caution: the TAS-desvices only support gpios 1,2 and 3 Examples: diff --git a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml index 4156981fe02b..962701e9eb42 100644 --- a/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,lpass-tx-macro.yaml @@ -13,6 +13,7 @@ properties: compatible: enum: - qcom,sc7280-lpass-tx-macro + - qcom,sm6115-lpass-tx-macro - qcom,sm8250-lpass-tx-macro - qcom,sm8450-lpass-tx-macro - qcom,sm8550-lpass-tx-macro @@ -101,6 +102,23 @@ allOf: properties: compatible: enum: + - qcom,sm6115-lpass-tx-macro + then: + properties: + clocks: + minItems: 4 + maxItems: 4 + clock-names: + items: + - const: mclk + - const: npl + - const: dcodec + - const: fsgen + + - if: + properties: + compatible: + enum: - qcom,sm8550-lpass-tx-macro then: properties: diff --git a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml index 262de7a60a73..e082a4fe095d 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml @@ -25,6 +25,7 @@ properties: - qcom,apq8016-sbc-sndcard - qcom,msm8916-qdsp6-sndcard - qcom,qrb5165-rb5-sndcard + - qcom,sc7180-qdsp6-sndcard - qcom,sc8280xp-sndcard - qcom,sdm845-sndcard - qcom,sm8250-sndcard diff --git a/Documentation/devicetree/bindings/sound/realtek,rt5616.yaml b/Documentation/devicetree/bindings/sound/realtek,rt5616.yaml new file mode 100644 index 000000000000..248320804e5f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/realtek,rt5616.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/realtek,rt5616.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek rt5616 ALSA SoC audio codec driver + +description: | + Pins on the device (for linking into audio routes) for RT5616: + + * IN1P + * IN2P + * IN2N + * LOUTL + * LOUTR + * HPOL + * HPOR + +maintainers: + - Bard Liao <bardliao@realtek.com> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: realtek,rt5616 + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + audio-codec@1b { + compatible = "realtek,rt5616"; + reg = <0x1b>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/richtek,rtq9128.yaml b/Documentation/devicetree/bindings/sound/richtek,rtq9128.yaml new file mode 100644 index 000000000000..d54686a19ab7 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/richtek,rtq9128.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/richtek,rtq9128.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Richtek RTQ9128 Automative Audio Power Amplifier + +maintainers: + - ChiYuan Huang <cy_huang@richtek.com> + +description: + The RTQ9128 is a ultra-low output noise, high-efficiency, four-channel + class-D audio power amplifier and delivering 4x75W into 4OHm at 10% + THD+N from a 25V supply in automotive applications. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - richtek,rtq9128 + + reg: + maxItems: 1 + + enable-gpios: + maxItems: 1 + + richtek,tdm-input-data2-select: + type: boolean + description: + By default, if TDM mode is used, TDM data input will select 'DATA1' pin + as the data source. This option will configure TDM data input source from + 'DATA1' to 'DATA2' pin. + + '#sound-dai-cells': + const: 0 + +required: + - compatible + - reg + - '#sound-dai-cells' + +unevaluatedProperties: false + +examples: + - | + #include <dt-bindings/gpio/gpio.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + speaker@1a { + compatible = "richtek,rtq9128"; + reg = <0x1a>; + enable-gpios = <&gpio 26 GPIO_ACTIVE_HIGH>; + #sound-dai-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/rt5616.txt b/Documentation/devicetree/bindings/sound/rt5616.txt deleted file mode 100644 index 540a4bf252e4..000000000000 --- a/Documentation/devicetree/bindings/sound/rt5616.txt +++ /dev/null @@ -1,32 +0,0 @@ -RT5616 audio CODEC - -This device supports I2C only. - -Required properties: - -- compatible : "realtek,rt5616". - -- reg : The I2C address of the device. - -Optional properties: - -- clocks: The phandle of the master clock to the CODEC. - -- clock-names: Should be "mclk". - -Pins on the device (for linking into audio routes) for RT5616: - - * IN1P - * IN2P - * IN2N - * LOUTL - * LOUTR - * HPOL - * HPOR - -Example: - -rt5616: codec@1b { - compatible = "realtek,rt5616"; - reg = <0x1b>; -}; diff --git a/Documentation/devicetree/bindings/sound/starfive,jh7110-pwmdac.yaml b/Documentation/devicetree/bindings/sound/starfive,jh7110-pwmdac.yaml new file mode 100644 index 000000000000..e2b4db6aa2fb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/starfive,jh7110-pwmdac.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/starfive,jh7110-pwmdac.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: StarFive JH7110 PWM-DAC Controller + +description: + The PWM-DAC Controller uses PWM square wave generators plus RC filters to + form a DAC for audio play in StarFive JH7110 SoC. This audio play controller + supports 16 bit audio format, up to 48K sampling frequency, up to left and + right dual channels. + +maintainers: + - Hal Feng <hal.feng@starfivetech.com> + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + const: starfive,jh7110-pwmdac + + reg: + maxItems: 1 + + clocks: + items: + - description: PWMDAC APB + - description: PWMDAC CORE + + clock-names: + items: + - const: apb + - const: core + + resets: + maxItems: 1 + description: PWMDAC APB + + dmas: + maxItems: 1 + description: TX DMA Channel + + dma-names: + const: tx + + "#sound-dai-cells": + const: 0 + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - dmas + - dma-names + - "#sound-dai-cells" + +additionalProperties: false + +examples: + - | + pwmdac@100b0000 { + compatible = "starfive,jh7110-pwmdac"; + reg = <0x100b0000 0x1000>; + clocks = <&syscrg 157>, + <&syscrg 158>; + clock-names = "apb", "core"; + resets = <&syscrg 96>; + dmas = <&dma 22>; + dma-names = "tx"; + #sound-dai-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/sound/tas5805m.yaml b/Documentation/devicetree/bindings/sound/tas5805m.yaml index 63edf52f061c..12c41974274e 100644 --- a/Documentation/devicetree/bindings/sound/tas5805m.yaml +++ b/Documentation/devicetree/bindings/sound/tas5805m.yaml @@ -37,6 +37,8 @@ properties: generated from TI's PPC3 tool. $ref: /schemas/types.yaml#/definitions/string +additionalProperties: false + examples: - | i2c { @@ -52,5 +54,4 @@ examples: ti,dsp-config-name = "mono_pbtl_48khz"; }; }; - -additionalProperties: true +... diff --git a/Documentation/devicetree/bindings/sound/tfa9879.txt b/Documentation/devicetree/bindings/sound/tfa9879.txt deleted file mode 100644 index 1620e6848436..000000000000 --- a/Documentation/devicetree/bindings/sound/tfa9879.txt +++ /dev/null @@ -1,23 +0,0 @@ -NXP TFA9879 class-D audio amplifier - -Required properties: - -- compatible : "nxp,tfa9879" - -- reg : the I2C address of the device - -- #sound-dai-cells : must be 0. - -Example: - -&i2c1 { - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_i2c1>; - - amp: amp@6c { - #sound-dai-cells = <0>; - compatible = "nxp,tfa9879"; - reg = <0x6c>; - }; -}; - diff --git a/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml index b6a4360ab845..0b4f003989a4 100644 --- a/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml +++ b/Documentation/devicetree/bindings/sound/ti,pcm3168a.yaml @@ -60,6 +60,7 @@ properties: ports: $ref: audio-graph-port.yaml#/definitions/port-base + unevaluatedProperties: false properties: port@0: $ref: audio-graph-port.yaml# diff --git a/Documentation/devicetree/bindings/sound/wm8782.txt b/Documentation/devicetree/bindings/sound/wm8782.txt index 256cdec6ec4d..1a28f3280972 100644 --- a/Documentation/devicetree/bindings/sound/wm8782.txt +++ b/Documentation/devicetree/bindings/sound/wm8782.txt @@ -8,10 +8,17 @@ Required properties: - Vdda-supply : phandle to a regulator for the analog power supply (2.7V - 5.5V) - Vdd-supply : phandle to a regulator for the digital power supply (2.7V - 3.6V) +Optional properties: + + - wlf,fsampen: + FSAMPEN pin value, 0 for low, 1 for high, 2 for disconnected. + Defaults to 0 if left unspecified. + Example: wm8782: stereo-adc { compatible = "wlf,wm8782"; Vdda-supply = <&vdda_supply>; Vdd-supply = <&vdd_supply>; + wlf,fsampen = <2>; /* 192KHz */ }; diff --git a/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml b/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml index 7d60a9654912..3591c8c49bfe 100644 --- a/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml +++ b/Documentation/devicetree/bindings/soundwire/qcom,soundwire.yaml @@ -209,17 +209,6 @@ properties: label: maxItems: 1 -patternProperties: - "^.*@[0-9a-f],[0-9a-f]$": - type: object - additionalProperties: true - description: - Child nodes for a standalone audio codec or speaker amplifier IC. - It has RX and TX Soundwire secondary devices. - properties: - compatible: - pattern: "^sdw[0-9a-f]{1}[0-9a-f]{4}[0-9a-f]{4}[0-9a-f]{2}$" - required: - compatible - reg @@ -240,7 +229,10 @@ oneOf: - required: - qcom,ports-sinterval -additionalProperties: false +allOf: + - $ref: soundwire-controller.yaml# + +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml index a6f34bdd1d3c..e1ab3f523ad6 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun4i-a10-spi.yaml @@ -46,6 +46,8 @@ properties: patternProperties: "^.*@[0-9a-f]+": type: object + additionalProperties: true + properties: reg: items: diff --git a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml index 28b8ace63044..3b47b68b92cb 100644 --- a/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml +++ b/Documentation/devicetree/bindings/spi/allwinner,sun6i-a31-spi.yaml @@ -68,6 +68,8 @@ properties: patternProperties: "^.*@[0-9a-f]+": type: object + additionalProperties: true + properties: reg: items: diff --git a/Documentation/devicetree/bindings/spi/arm,pl022-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/arm,pl022-peripheral-props.yaml new file mode 100644 index 000000000000..bb8b6863b109 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/arm,pl022-peripheral-props.yaml @@ -0,0 +1,61 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/spi/arm,pl022-peripheral-props.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Peripheral-specific properties for Arm PL022 SPI controller + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + +select: false + +properties: + pl022,interface: + description: SPI interface type + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # SPI + - 1 # Texas Instruments Synchronous Serial Frame Format + - 2 # Microwire (Half Duplex) + + pl022,com-mode: + description: Specifies the transfer mode + $ref: /schemas/types.yaml#/definitions/uint32 + enum: + - 0 # interrupt mode + - 1 # polling mode + - 2 # DMA mode + default: 1 + + pl022,rx-level-trig: + description: Rx FIFO watermark level + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 4 + + pl022,tx-level-trig: + description: Tx FIFO watermark level + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 4 + + pl022,ctrl-len: + description: Microwire interface - Control length + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0x03 + maximum: 0x1f + + pl022,wait-state: + description: Microwire interface - Wait state + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + + pl022,duplex: + description: Microwire interface - Full/Half duplex + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + +additionalProperties: true +... diff --git a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml index 9ae1611175f2..48e97e240265 100644 --- a/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml +++ b/Documentation/devicetree/bindings/spi/nvidia,tegra210-quad.yaml @@ -50,6 +50,7 @@ properties: patternProperties: "@[0-9a-f]+$": type: object + additionalProperties: true properties: spi-rx-bus-width: diff --git a/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml b/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml index 93f14dd01afc..88be13268962 100644 --- a/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml +++ b/Documentation/devicetree/bindings/spi/qcom,spi-qup.yaml @@ -44,9 +44,17 @@ properties: - const: tx - const: rx + interconnects: + maxItems: 1 + interrupts: maxItems: 1 + operating-points-v2: true + + power-domains: + maxItems: 1 + reg: maxItems: 1 @@ -62,7 +70,9 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/clock/qcom,gcc-msm8996.h> + #include <dt-bindings/interconnect/qcom,msm8996.h> #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/power/qcom-rpmpd.h> spi@7575000 { compatible = "qcom,spi-qup-v2.2.1"; @@ -76,6 +86,9 @@ examples: pinctrl-1 = <&blsp1_spi1_sleep>; dmas = <&blsp1_dma 12>, <&blsp1_dma 13>; dma-names = "tx", "rx"; + power-domains = <&rpmpd MSM8996_VDDCX>; + operating-points-v2 = <&spi_opp_table>; + interconnects = <&pnoc MASTER_BLSP_1 &bimc SLAVE_EBI_CH0>; #address-cells = <1>; #size-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml b/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml index e59183e53690..bed829837df1 100644 --- a/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml +++ b/Documentation/devicetree/bindings/spi/renesas,rzv2m-csi.yaml @@ -39,6 +39,12 @@ properties: power-domains: maxItems: 1 + renesas,csi-no-ss: + type: boolean + description: + The CSI Slave Selection (SS) pin won't be used to enable transmission and + reception. Only available when in target mode. + required: - compatible - reg @@ -50,6 +56,9 @@ required: - '#address-cells' - '#size-cells' +dependencies: + renesas,csi-no-ss: [ spi-slave ] + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml b/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml index 339fb39529f3..ac1503de0478 100644 --- a/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml +++ b/Documentation/devicetree/bindings/spi/rockchip-sfc.yaml @@ -47,6 +47,8 @@ properties: patternProperties: "^flash@[0-3]$": type: object + additionalProperties: true + properties: reg: minimum: 0 diff --git a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml index a47cb144b09f..6348a387a21c 100644 --- a/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml +++ b/Documentation/devicetree/bindings/spi/snps,dw-apb-ssi.yaml @@ -160,6 +160,8 @@ properties: patternProperties: "^.*@[0-9a-f]+$": type: object + additionalProperties: true + properties: reg: minimum: 0 diff --git a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml index 782a014b63a7..15938f81fdce 100644 --- a/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml +++ b/Documentation/devicetree/bindings/spi/spi-peripheral-props.yaml @@ -113,8 +113,14 @@ properties: minItems: 2 maxItems: 4 + st,spi-midi-ns: + description: | + Only for STM32H7, (Master Inter-Data Idleness) minimum time + delay in nanoseconds inserted between two consecutive data frames. + # The controller specific properties go here. allOf: + - $ref: arm,pl022-peripheral-props.yaml# - $ref: cdns,qspi-nor-peripheral-props.yaml# - $ref: samsung,spi-peripheral-props.yaml# - $ref: nvidia,tegra210-quad-peripheral-props.yaml# diff --git a/Documentation/devicetree/bindings/spi/spi-pl022.yaml b/Documentation/devicetree/bindings/spi/spi-pl022.yaml index 5e5a704a766e..7f174b7d0a26 100644 --- a/Documentation/devicetree/bindings/spi/spi-pl022.yaml +++ b/Documentation/devicetree/bindings/spi/spi-pl022.yaml @@ -74,57 +74,6 @@ properties: resets: maxItems: 1 -patternProperties: - "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": - type: object - # SPI slave nodes must be children of the SPI master node and can - # contain the following properties. - properties: - pl022,interface: - description: SPI interface type - $ref: /schemas/types.yaml#/definitions/uint32 - enum: - - 0 # SPI - - 1 # Texas Instruments Synchronous Serial Frame Format - - 2 # Microwire (Half Duplex) - - pl022,com-mode: - description: Specifies the transfer mode - $ref: /schemas/types.yaml#/definitions/uint32 - enum: - - 0 # interrupt mode - - 1 # polling mode - - 2 # DMA mode - default: 1 - - pl022,rx-level-trig: - description: Rx FIFO watermark level - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 4 - - pl022,tx-level-trig: - description: Tx FIFO watermark level - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 4 - - pl022,ctrl-len: - description: Microwire interface - Control length - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0x03 - maximum: 0x1f - - pl022,wait-state: - description: Microwire interface - Wait state - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - - pl022,duplex: - description: Microwire interface - Full/Half duplex - $ref: /schemas/types.yaml#/definitions/uint32 - enum: [0, 1] - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml index 9ca1a843c820..ae0f082bd377 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml @@ -18,15 +18,6 @@ maintainers: allOf: - $ref: spi-controller.yaml# - - if: - properties: - compatible: - contains: - const: st,stm32f4-spi - - then: - properties: - st,spi-midi-ns: false properties: compatible: @@ -59,17 +50,6 @@ properties: - const: rx - const: tx -patternProperties: - "^[a-zA-Z][a-zA-Z0-9,+\\-._]{0,63}@[0-9a-f]+$": - type: object - # SPI slave nodes must be children of the SPI master node and can - # contain the following properties. - properties: - st,spi-midi-ns: - description: | - Only for STM32H7, (Master Inter-Data Idleness) minimum time - delay in nanoseconds inserted between two consecutive data frames. - required: - compatible - reg diff --git a/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml b/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml index 3721c8c8ec64..e02d04d4f71e 100644 --- a/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/fsl,scu-thermal.yaml @@ -18,7 +18,9 @@ allOf: properties: compatible: items: - - const: fsl,imx8qxp-sc-thermal + - enum: + - fsl,imx8dxl-sc-thermal + - fsl,imx8qxp-sc-thermal - const: fsl,imx-sc-thermal '#thermal-sensor-cells': diff --git a/Documentation/devicetree/bindings/thermal/imx-thermal.yaml b/Documentation/devicetree/bindings/thermal/imx-thermal.yaml index 3aecea77869f..808d987bd8d1 100644 --- a/Documentation/devicetree/bindings/thermal/imx-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/imx-thermal.yaml @@ -60,6 +60,9 @@ properties: clocks: maxItems: 1 + "#thermal-sensor-cells": + const: 0 + required: - compatible - interrupts @@ -67,6 +70,9 @@ required: - nvmem-cells - nvmem-cell-names +allOf: + - $ref: thermal-sensor.yaml# + additionalProperties: false examples: @@ -104,5 +110,6 @@ examples: nvmem-cells = <&tempmon_calib>, <&tempmon_temp_grade>; nvmem-cell-names = "calib", "temp_grade"; clocks = <&clks IMX6SX_CLK_PLL3_USB_OTG>; + #thermal-sensor-cells = <0>; }; }; diff --git a/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml b/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml index fe9ae4c425c0..e6665af52ee6 100644 --- a/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml +++ b/Documentation/devicetree/bindings/thermal/mediatek,lvts-thermal.yaml @@ -18,6 +18,7 @@ description: | properties: compatible: enum: + - mediatek,mt7988-lvts-ap - mediatek,mt8192-lvts-ap - mediatek,mt8192-lvts-mcu - mediatek,mt8195-lvts-ap diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml index 04a2ba1aa946..b0237d236021 100644 --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.yaml @@ -68,7 +68,12 @@ properties: patternProperties: "^(light|heavy|oc1)$": type: object + additionalProperties: false + properties: + "#cooling-cells": + const: 2 + nvidia,priority: $ref: /schemas/types.yaml#/definitions/uint32 minimum: 1 diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml index 27e9e16e6455..437b74732886 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.yaml @@ -51,6 +51,7 @@ properties: - qcom,msm8996-tsens - qcom,msm8998-tsens - qcom,qcm2290-tsens + - qcom,sa8775p-tsens - qcom,sc7180-tsens - qcom,sc7280-tsens - qcom,sc8180x-tsens diff --git a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml index 4f3acdc4dec0..4a8dabc48170 100644 --- a/Documentation/devicetree/bindings/thermal/thermal-zones.yaml +++ b/Documentation/devicetree/bindings/thermal/thermal-zones.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/base.yaml# title: Thermal zone maintainers: - - Amit Kucheria <amitk@kernel.org> + - Daniel Lezcano <daniel.lezcano@linaro.org> description: | Thermal management is achieved in devicetree by describing the sensor hardware diff --git a/Documentation/devicetree/bindings/timer/cirrus,ep9301-timer.yaml b/Documentation/devicetree/bindings/timer/cirrus,ep9301-timer.yaml new file mode 100644 index 000000000000..e463e11e259d --- /dev/null +++ b/Documentation/devicetree/bindings/timer/cirrus,ep9301-timer.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/cirrus,ep9301-timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cirrus Logic EP93xx timer + +maintainers: + - Alexander Sverdlin <alexander.sverdlin@gmail.com> + - Nikita Shubin <nikita.shubin@maquefel.me> + +properties: + compatible: + oneOf: + - const: cirrus,ep9301-timer + - items: + - enum: + - cirrus,ep9302-timer + - cirrus,ep9307-timer + - cirrus,ep9312-timer + - cirrus,ep9315-timer + - const: cirrus,ep9301-timer + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + timer@80810000 { + compatible = "cirrus,ep9301-timer"; + reg = <0x80810000 0x100>; + interrupt-parent = <&vic1>; + interrupts = <19>; + }; +... diff --git a/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml b/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml index dbe1267af06a..e2607377cbae 100644 --- a/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml +++ b/Documentation/devicetree/bindings/timer/fsl,imxgpt.yaml @@ -36,7 +36,9 @@ properties: - fsl,imxrt1170-gpt - const: fsl,imx6dl-gpt - items: - - const: fsl,imx6ul-gpt + - enum: + - fsl,imx6ul-gpt + - fsl,imx7d-gpt - const: fsl,imx6sx-gpt reg: @@ -46,14 +48,18 @@ properties: maxItems: 1 clocks: + minItems: 2 items: - description: SoC GPT ipg clock - description: SoC GPT per clock + - description: SoC GPT osc per clock clock-names: + minItems: 2 items: - const: ipg - const: per + - const: osc_per required: - compatible @@ -62,6 +68,29 @@ required: - clocks - clock-names +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,imx6dl-gpt + - fsl,imx6q-gpt + then: + properties: + clocks: + minItems: 2 + maxItems: 3 + clock-names: + minItems: 2 + maxItems: 3 + else: + properties: + clocks: + maxItems: 2 + clock-names: + maxItems: 2 + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml b/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml index bffdab0b0185..3931054b42fb 100644 --- a/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,rz-mtu3.yaml @@ -11,8 +11,8 @@ maintainers: description: | This hardware block consists of eight 16-bit timer channels and one - 32- bit timer channel. It supports the following specifications: - - Pulse input/output: 28 lines max. + 32-bit timer channel. It supports the following specifications: + - Pulse input/output: 28 lines max - Pulse input 3 lines - Count clock 11 clocks for each channel (14 clocks for MTU0, 12 clocks for MTU2, and 10 clocks for MTU5, four clocks for MTU1-MTU2 combination @@ -23,11 +23,11 @@ description: | - Input capture function (noise filter setting available) - Counter-clearing operation - Simultaneous writing to multiple timer counters (TCNT) - (excluding MTU8). + (excluding MTU8) - Simultaneous clearing on compare match or input capture - (excluding MTU8). + (excluding MTU8) - Simultaneous input and output to registers in synchronization with - counter operations (excluding MTU8). + counter operations (excluding MTU8) - Up to 12-phase PWM output in combination with synchronous operation (excluding MTU8) - [MTU0 MTU3, MTU4, MTU6, MTU7, and MTU8] @@ -40,26 +40,26 @@ description: | - [MTU3, MTU4, MTU6, and MTU7] - Through interlocked operation of MTU3/4 and MTU6/7, the positive and negative signals in six phases (12 phases in total) can be output in - complementary PWM and reset-synchronized PWM operation. + complementary PWM and reset-synchronized PWM operation - In complementary PWM mode, values can be transferred from buffer registers to temporary registers at crests and troughs of the timer- counter values or when the buffer registers (TGRD registers in MTU4 - and MTU7) are written to. - - Double-buffering selectable in complementary PWM mode. + and MTU7) are written to + - Double-buffering selectable in complementary PWM mode - [MTU3 and MTU4] - Through interlocking with MTU0, a mode for driving AC synchronous motors (brushless DC motors) by using complementary PWM output and reset-synchronized PWM output is settable and allows the selection - of two types of waveform output (chopping or level). + of two types of waveform output (chopping or level) - [MTU5] - - Capable of operation as a dead-time compensation counter. + - Capable of operation as a dead-time compensation counter - [MTU0/MTU5, MTU1, MTU2, and MTU8] - 32-bit phase counting mode specifiable by combining MTU1 and MTU2 and - through interlocked operation with MTU0/MTU5 and MTU8. + through interlocked operation with MTU0/MTU5 and MTU8 - Interrupt-skipping function - In complementary PWM mode, interrupts on crests and troughs of counter values and triggers to start conversion by the A/D converter can be - skipped. + skipped - Interrupt sources: 43 sources. - Buffer operation: - Automatic transfer of register data (transfer from the buffer @@ -68,9 +68,9 @@ description: | - A/D converter start triggers can be generated - A/D converter start request delaying function enables A/D converter to be started with any desired timing and to be synchronized with - PWM output. + PWM output - Low power consumption function - - The MTU3a can be placed in the module-stop state. + - The MTU3a can be placed in the module-stop state There are two phase counting modes. 16-bit phase counting mode in which MTU1 and MTU2 operate independently, and cascade connection 32-bit phase @@ -109,6 +109,7 @@ properties: compatible: items: - enum: + - renesas,r9a07g043-mtu3 # RZ/{G2UL,Five} - renesas,r9a07g044-mtu3 # RZ/G2{L,LC} - renesas,r9a07g054-mtu3 # RZ/V2L - const: renesas,rz-mtu3 @@ -169,27 +170,27 @@ properties: - const: tgib0 - const: tgic0 - const: tgid0 - - const: tgiv0 + - const: tciv0 - const: tgie0 - const: tgif0 - const: tgia1 - const: tgib1 - - const: tgiv1 - - const: tgiu1 + - const: tciv1 + - const: tciu1 - const: tgia2 - const: tgib2 - - const: tgiv2 - - const: tgiu2 + - const: tciv2 + - const: tciu2 - const: tgia3 - const: tgib3 - const: tgic3 - const: tgid3 - - const: tgiv3 + - const: tciv3 - const: tgia4 - const: tgib4 - const: tgic4 - const: tgid4 - - const: tgiv4 + - const: tciv4 - const: tgiu5 - const: tgiv5 - const: tgiw5 @@ -197,18 +198,18 @@ properties: - const: tgib6 - const: tgic6 - const: tgid6 - - const: tgiv6 + - const: tciv6 - const: tgia7 - const: tgib7 - const: tgic7 - const: tgid7 - - const: tgiv7 + - const: tciv7 - const: tgia8 - const: tgib8 - const: tgic8 - const: tgid8 - - const: tgiv8 - - const: tgiu8 + - const: tciv8 + - const: tciu8 clocks: maxItems: 1 @@ -285,16 +286,16 @@ examples: <GIC_SPI 211 IRQ_TYPE_EDGE_RISING>, <GIC_SPI 212 IRQ_TYPE_EDGE_RISING>, <GIC_SPI 213 IRQ_TYPE_EDGE_RISING>; - interrupt-names = "tgia0", "tgib0", "tgic0", "tgid0", "tgiv0", "tgie0", + interrupt-names = "tgia0", "tgib0", "tgic0", "tgid0", "tciv0", "tgie0", "tgif0", - "tgia1", "tgib1", "tgiv1", "tgiu1", - "tgia2", "tgib2", "tgiv2", "tgiu2", - "tgia3", "tgib3", "tgic3", "tgid3", "tgiv3", - "tgia4", "tgib4", "tgic4", "tgid4", "tgiv4", + "tgia1", "tgib1", "tciv1", "tciu1", + "tgia2", "tgib2", "tciv2", "tciu2", + "tgia3", "tgib3", "tgic3", "tgid3", "tciv3", + "tgia4", "tgib4", "tgic4", "tgid4", "tciv4", "tgiu5", "tgiv5", "tgiw5", - "tgia6", "tgib6", "tgic6", "tgid6", "tgiv6", - "tgia7", "tgib7", "tgic7", "tgid7", "tgiv7", - "tgia8", "tgib8", "tgic8", "tgid8", "tgiv8", "tgiu8"; + "tgia6", "tgib6", "tgic6", "tgid6", "tciv6", + "tgia7", "tgib7", "tgic7", "tgid7", "tciv7", + "tgia8", "tgib8", "tgic8", "tgid8", "tciv8", "tciu8"; clocks = <&cpg CPG_MOD R9A07G044_MTU_X_MCK_MTU3>; power-domains = <&cpg>; resets = <&cpg R9A07G044_MTU_X_PRESET_MTU3>; diff --git a/Documentation/devicetree/bindings/timer/sifive,clint.yaml b/Documentation/devicetree/bindings/timer/sifive,clint.yaml index a0185e15a42f..e8be6c470364 100644 --- a/Documentation/devicetree/bindings/timer/sifive,clint.yaml +++ b/Documentation/devicetree/bindings/timer/sifive,clint.yaml @@ -37,6 +37,7 @@ properties: - items: - enum: - allwinner,sun20i-d1-clint + - sophgo,cv1800b-clint - thead,th1520-clint - const: thead,c900-clint - items: diff --git a/Documentation/devicetree/bindings/timer/thead,c900-aclint-mtimer.yaml b/Documentation/devicetree/bindings/timer/thead,c900-aclint-mtimer.yaml new file mode 100644 index 000000000000..fbd235650e52 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/thead,c900-aclint-mtimer.yaml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/thead,c900-aclint-mtimer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Sophgo CLINT Timer + +maintainers: + - Inochi Amaoto <inochiama@outlook.com> + +properties: + compatible: + items: + - enum: + - sophgo,sg2042-aclint-mtimer + - const: thead,c900-aclint-mtimer + + reg: + maxItems: 1 + + interrupts-extended: + minItems: 1 + maxItems: 4095 + +additionalProperties: false + +required: + - compatible + - reg + - interrupts-extended + +examples: + - | + timer@ac000000 { + compatible = "sophgo,sg2042-aclint-mtimer", "thead,c900-aclint-mtimer"; + interrupts-extended = <&cpu1intc 7>, + <&cpu2intc 7>, + <&cpu3intc 7>, + <&cpu4intc 7>; + reg = <0xac000000 0x00010000>; + }; +... diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 430a814f64a5..c3190f2a168a 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -151,8 +151,6 @@ properties: - infineon,slb9645tt # Infineon SLB9673 I2C TPM 2.0 - infineon,slb9673 - # Infineon TDA38640 Voltage Regulator - - infineon,tda38640 # Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor - infineon,tlv493d-a1b6 # Infineon Multi-phase Digital VR Controller xdpe11280 @@ -311,8 +309,6 @@ properties: - nuvoton,w83773g # OKI ML86V7667 video decoder - oki,ml86v7667 - # OV5642: Color CMOS QSXGA (5-megapixel) Image Sensor with OmniBSI and Embedded TrueFocus - - ovti,ov5642 # 48-Lane, 12-Port PCI Express Gen 2 (5.0 GT/s) Switch - plx,pex8648 # Pulsedlight LIDAR range-finding sensor @@ -348,6 +344,8 @@ properties: # Silicon Labs SI3210 Programmable CMOS SLIC/CODEC with SPI interface - silabs,si3210 # Relative Humidity and Temperature Sensors + - silabs,si7005 + # Relative Humidity and Temperature Sensors - silabs,si7020 # Skyworks SKY81452: Six-Channel White LED Driver with Touch Panel Bias Supply - skyworks,sky81452 diff --git a/Documentation/devicetree/bindings/ufs/ufs-common.yaml b/Documentation/devicetree/bindings/ufs/ufs-common.yaml index bbaee4f5f7b2..985ea8f64de8 100644 --- a/Documentation/devicetree/bindings/ufs/ufs-common.yaml +++ b/Documentation/devicetree/bindings/ufs/ufs-common.yaml @@ -20,11 +20,25 @@ properties: items: - description: Minimum frequency for given clock in Hz - description: Maximum frequency for given clock in Hz + deprecated: true description: | + Preferred is operating-points-v2. + Array of <min max> operating frequencies in Hz stored in the same order - as the clocks property. If this property is not defined or a value in the - array is "0" then it is assumed that the frequency is set by the parent - clock or a fixed rate clock source. + as the clocks property. If either this property or operating-points-v2 is + not defined or a value in the array is "0" then it is assumed that the + frequency is set by the parent clock or a fixed rate clock source. + + operating-points-v2: + description: + Preferred over freq-table-hz. + If present, each OPP must contain array of frequencies stored in the same + order for each clock. If clock frequency in the array is "0" then it is + assumed that the frequency is set by the parent clock or a fixed rate + clock source. + + opp-table: + type: object interrupts: maxItems: 1 @@ -75,8 +89,23 @@ properties: dependencies: freq-table-hz: [ clocks ] + operating-points-v2: [ clocks, clock-names ] required: - interrupts +allOf: + - if: + required: + - freq-table-hz + then: + properties: + operating-points-v2: false + - if: + required: + - operating-points-v2 + then: + properties: + freq-table-hz: false + additionalProperties: true diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml index 1394557517b1..b7e664f7395b 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml @@ -15,7 +15,9 @@ properties: oneOf: - enum: - chipidea,usb2 + - fsl,imx27-usb - lsi,zevio-usb + - nuvoton,npcm750-udc - nvidia,tegra20-ehci - nvidia,tegra20-udc - nvidia,tegra30-ehci @@ -66,6 +68,10 @@ properties: - items: - const: xlnx,zynq-usb-2.20a - const: chipidea,usb2 + - items: + - enum: + - nuvoton,npcm845-udc + - const: nuvoton,npcm750-udc reg: minItems: 1 @@ -388,6 +394,7 @@ allOf: enum: - chipidea,usb2 - lsi,zevio-usb + - nuvoton,npcm750-udc - nvidia,tegra20-udc - nvidia,tegra30-udc - nvidia,tegra114-udc diff --git a/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml b/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml index f6e7a5c1ff0b..f9410eb76a62 100644 --- a/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml +++ b/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml @@ -11,8 +11,12 @@ maintainers: properties: compatible: - enum: - - fcs,fsa4480 + oneOf: + - const: fcs,fsa4480 + - items: + - enum: + - ocs,ocp96011 + - const: fcs,fsa4480 reg: maxItems: 1 @@ -32,10 +36,43 @@ properties: type: boolean port: - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base description: A port node to link the FSA4480 to a TypeC controller for the purpose of handling altmode muxing and orientation switching. + unevaluatedProperties: false + + properties: + endpoint: + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false + + properties: + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + Specifies how the AUX+/- lines are connected to SBU1/2. + oneOf: + - items: + - const: 0 + - const: 1 + description: | + Default AUX/SBU layout (FSA4480) + - AUX+ connected to SBU2 + - AUX- connected to SBU1 + Default AUX/SBU layout (OCP96011) + - AUX+ connected to SBU1 + - AUX- connected to SBU2 + - items: + - const: 1 + - const: 0 + description: | + Swapped AUX/SBU layout (FSA4480) + - AUX+ connected to SBU1 + - AUX- connected to SBU2 + Swapped AUX/SBU layout (OCP96011) + - AUX+ connected to SBU2 + - AUX- connected to SBU1 required: - compatible diff --git a/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml b/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml index d0927f6768a4..ee08b9c3721f 100644 --- a/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml +++ b/Documentation/devicetree/bindings/usb/genesys,gl850g.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/usb/genesys,gl850g.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Genesys Logic GL850G USB 2.0 hub controller +title: Genesys Logic USB hub controller maintainers: - Icenowy Zheng <uwu@icenowy.me> @@ -18,6 +18,7 @@ properties: - usb5e3,608 - usb5e3,610 - usb5e3,620 + - usb5e3,626 reg: true diff --git a/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml b/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml index f196beb826d8..d3b2b666ec2a 100644 --- a/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml +++ b/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml @@ -19,6 +19,7 @@ properties: compatible: items: - enum: + - nxp,cbdtu02043 - onnn,fsusb43l10x - pericom,pi3usb102 - const: gpio-sbu-mux @@ -50,7 +51,6 @@ required: - compatible - enable-gpios - select-gpios - - mode-switch - orientation-switch - port diff --git a/Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml b/Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml new file mode 100644 index 000000000000..eee548ac1abe --- /dev/null +++ b/Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/nxp,ptn36502.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NXP PTN36502 Type-C USB 3.1 Gen 1 and DisplayPort v1.2 combo redriver + +maintainers: + - Luca Weiss <luca.weiss@fairphone.com> + +properties: + compatible: + enum: + - nxp,ptn36502 + + reg: + maxItems: 1 + + vdd18-supply: + description: Power supply for VDD18 pin + + retimer-switch: + description: Flag the port as possible handle of SuperSpeed signals retiming + type: boolean + + orientation-switch: + description: Flag the port as possible handler of orientation switching + type: boolean + + ports: + $ref: /schemas/graph.yaml#/properties/ports + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Super Speed (SS) Output endpoint to the Type-C connector + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: Super Speed (SS) Input endpoint from the Super-Speed PHY + + port@2: + $ref: /schemas/graph.yaml#/properties/port + description: + Sideband Use (SBU) AUX lines endpoint to the Type-C connector for the purpose of + handling altmode muxing and orientation switching. + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + typec-mux@1a { + compatible = "nxp,ptn36502"; + reg = <0x1a>; + + vdd18-supply = <&usb_redrive_1v8>; + + retimer-switch; + orientation-switch; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + usb_con_ss: endpoint { + remote-endpoint = <&typec_con_ss>; + }; + }; + port@1 { + reg = <1>; + phy_con_ss: endpoint { + remote-endpoint = <&usb_phy_ss>; + }; + }; + port@2 { + reg = <2>; + usb_con_sbu: endpoint { + remote-endpoint = <&typec_dp_aux>; + }; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml index 67591057f234..e889158ca205 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.yaml @@ -14,6 +14,7 @@ properties: items: - enum: - qcom,ipq4019-dwc3 + - qcom,ipq5018-dwc3 - qcom,ipq5332-dwc3 - qcom,ipq6018-dwc3 - qcom,ipq8064-dwc3 @@ -34,6 +35,7 @@ properties: - qcom,sdm845-dwc3 - qcom,sdx55-dwc3 - qcom,sdx65-dwc3 + - qcom,sdx75-dwc3 - qcom,sm4250-dwc3 - qcom,sm6115-dwc3 - qcom,sm6125-dwc3 @@ -180,6 +182,8 @@ allOf: - qcom,sdm670-dwc3 - qcom,sdm845-dwc3 - qcom,sdx55-dwc3 + - qcom,sdx65-dwc3 + - qcom,sdx75-dwc3 - qcom,sm6350-dwc3 then: properties: @@ -238,6 +242,7 @@ allOf: compatible: contains: enum: + - qcom,ipq5018-dwc3 - qcom,ipq5332-dwc3 - qcom,msm8994-dwc3 - qcom,qcs404-dwc3 @@ -363,6 +368,7 @@ allOf: - qcom,sdm845-dwc3 - qcom,sdx55-dwc3 - qcom,sdx65-dwc3 + - qcom,sdx75-dwc3 - qcom,sm4250-dwc3 - qcom,sm6125-dwc3 - qcom,sm6350-dwc3 @@ -411,6 +417,7 @@ allOf: compatible: contains: enum: + - qcom,ipq5018-dwc3 - qcom,ipq5332-dwc3 - qcom,sdm660-dwc3 then: diff --git a/Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml b/Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml new file mode 100644 index 000000000000..345d0132d4a5 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2023 Realtek Semiconductor Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/realtek,rtd-dwc3.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek DWC3 USB SoC Controller Glue + +maintainers: + - Stanley Chang <stanley_chang@realtek.com> + +description: + The Realtek DHC SoC embeds a DWC3 USB IP Core configured for USB 2.0 + and USB 3.0 in host or dual-role mode. + +properties: + compatible: + items: + - enum: + - realtek,rtd1295-dwc3 + - realtek,rtd1315e-dwc3 + - realtek,rtd1319-dwc3 + - realtek,rtd1319d-dwc3 + - realtek,rtd1395-dwc3 + - realtek,rtd1619-dwc3 + - realtek,rtd1619b-dwc3 + - const: realtek,rtd-dwc3 + + reg: + items: + - description: Address and length of register set for wrapper of dwc3 core. + - description: Address and length of register set for pm control. + + '#address-cells': + const: 1 + + '#size-cells': + const: 1 + + ranges: true + +patternProperties: + "^usb@[0-9a-f]+$": + $ref: snps,dwc3.yaml# + description: Required child node + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - ranges + +additionalProperties: false + +examples: + - | + usb@98013e00 { + compatible = "realtek,rtd1319d-dwc3", "realtek,rtd-dwc3"; + reg = <0x98013e00 0x140>, <0x98013f60 0x4>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + usb@98050000 { + compatible = "snps,dwc3"; + reg = <0x98050000 0x9000>; + interrupts = <0 94 4>; + phys = <&usb2phy &usb3phy>; + phy-names = "usb2-phy", "usb3-phy"; + dr_mode = "otg"; + usb-role-switch; + role-switch-default-mode = "host"; + snps,dis_u2_susphy_quirk; + snps,parkmode-disable-ss-quirk; + snps,parkmode-disable-hs-quirk; + maximum-speed = "high-speed"; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/realtek,rtd-type-c.yaml b/Documentation/devicetree/bindings/usb/realtek,rtd-type-c.yaml new file mode 100644 index 000000000000..6142b0b5b534 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/realtek,rtd-type-c.yaml @@ -0,0 +1,82 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2023 Realtek Semiconductor Corporation +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/realtek,rtd-type-c.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Realtek DHC RTD SoCs USB Type-C Connector detection + +maintainers: + - Stanley Chang <stanley_chang@realtek.com> + +description: + Realtek digital home center (DHC) RTD series SoCs include a type c module. + This module is able to detect the state of type c connector. + +properties: + compatible: + enum: + - realtek,rtd1295-type-c + - realtek,rtd1312c-type-c + - realtek,rtd1315e-type-c + - realtek,rtd1319-type-c + - realtek,rtd1319d-type-c + - realtek,rtd1395-type-c + - realtek,rtd1619-type-c + - realtek,rtd1619b-type-c + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + nvmem-cell-names: + items: + - const: usb-cal + + nvmem-cells: + maxItems: 1 + description: + The phandle to nvmem cell that contains the trimming data. + The type c parameter trimming data specified via efuse. + If unspecified, default value is used. + + realtek,rd-ctrl-gpios: + description: The gpio node to control external Rd on board. + maxItems: 1 + + connector: + $ref: /schemas/connector/usb-connector.yaml# + description: Properties for usb c connector. + type: object + +required: + - compatible + - reg + - interrupts + +additionalProperties: false + +examples: + - | + #include <dt-bindings/interrupt-controller/irq.h> + + type-c@7220 { + compatible = "realtek,rtd1619b-type-c"; + reg = <0x7220 0x20>; + interrupts = <0 60 IRQ_TYPE_LEVEL_HIGH>; + + pinctrl-names = "default"; + pinctrl-0 = <&usb_cc1_pins>, <&usb_cc2_pins>; + nvmem-cells = <&otp_usb_cal>; + nvmem-cell-names = "usb-cal"; + + connector { + compatible = "usb-c-connector"; + label = "USB-C"; + data-role = "dual"; + power-role = "dual"; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml index 291844c8f3e1..c4924113f9bd 100644 --- a/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/rockchip,dwc3.yaml @@ -15,14 +15,11 @@ description: Phy documentation is provided in the following places. USB2.0 PHY - Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.yaml + Documentation/devicetree/bindings/phy/rockchip,inno-usb2phy.yaml Type-C PHY Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt -allOf: - - $ref: snps,dwc3.yaml# - select: properties: compatible: @@ -30,6 +27,7 @@ select: enum: - rockchip,rk3328-dwc3 - rockchip,rk3568-dwc3 + - rockchip,rk3588-dwc3 required: - compatible @@ -39,6 +37,7 @@ properties: - enum: - rockchip,rk3328-dwc3 - rockchip,rk3568-dwc3 + - rockchip,rk3588-dwc3 - const: snps,dwc3 reg: @@ -58,7 +57,9 @@ properties: Master/Core clock, must to be >= 62.5 MHz for SS operation and >= 30MHz for HS operation - description: - Controller grf clock + Controller grf clock OR UTMI clock + - description: + PIPE clock clock-names: minItems: 3 @@ -66,7 +67,10 @@ properties: - const: ref_clk - const: suspend_clk - const: bus_clk - - const: grf_clk + - enum: + - grf_clk + - utmi + - const: pipe power-domains: maxItems: 1 @@ -86,6 +90,52 @@ required: - clocks - clock-names +allOf: + - $ref: snps,dwc3.yaml# + - if: + properties: + compatible: + contains: + const: rockchip,rk3328-dwc3 + then: + properties: + clocks: + minItems: 3 + maxItems: 4 + clock-names: + minItems: 3 + items: + - const: ref_clk + - const: suspend_clk + - const: bus_clk + - const: grf_clk + - if: + properties: + compatible: + contains: + const: rockchip,rk3568-dwc3 + then: + properties: + clocks: + maxItems: 3 + clock-names: + maxItems: 3 + - if: + properties: + compatible: + contains: + const: rockchip,rk3588-dwc3 + then: + properties: + clock-names: + minItems: 3 + items: + - const: ref_clk + - const: suspend_clk + - const: bus_clk + - const: utmi + - const: pipe + examples: - | #include <dt-bindings/clock/rk3328-cru.h> diff --git a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml index a696f23730d3..ee5af4b381b1 100644 --- a/Documentation/devicetree/bindings/usb/snps,dwc3.yaml +++ b/Documentation/devicetree/bindings/usb/snps,dwc3.yaml @@ -310,6 +310,62 @@ properties: maximum: 62 deprecated: true + snps,rx-thr-num-pkt: + description: + USB RX packet threshold count. In host mode, this field specifies + the space that must be available in the RX FIFO before the core can + start the corresponding USB RX transaction (burst). + In device mode, this field specifies the space that must be + available in the RX FIFO before the core can send ERDY for a + flow-controlled endpoint. It is only used for SuperSpeed. + The valid values for this field are from 1 to 15. (DWC3 SuperSpeed + USB 3.0 Controller Databook) + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 15 + + snps,rx-max-burst: + description: + Max USB RX burst size. In host mode, this field specifies the + Maximum Bulk IN burst the DWC_usb3 core can perform. When the system + bus is slower than the USB, RX FIFO can overrun during a long burst. + You can program a smaller value to this field to limit the RX burst + size that the core can perform. It only applies to SS Bulk, + Isochronous, and Interrupt IN endpoints in the host mode. + In device mode, this field specifies the NUMP value that is sent in + ERDY for an OUT endpoint. + The valid values for this field are from 1 to 16. (DWC3 SuperSpeed + USB 3.0 Controller Databook) + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 16 + + snps,tx-thr-num-pkt: + description: + USB TX packet threshold count. This field specifies the number of + packets that must be in the TXFIFO before the core can start + transmission for the corresponding USB transaction (burst). + This count is valid in both host and device modes. It is only used + for SuperSpeed operation. + Valid values are from 1 to 15. (DWC3 SuperSpeed USB 3.0 Controller + Databook) + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 15 + + snps,tx-max-burst: + description: + Max USB TX burst size. When the system bus is slower than the USB, + TX FIFO can underrun during a long burst. Program a smaller value + to this field to limit the TX burst size that the core can execute. + In Host mode, it only applies to SS Bulk, Isochronous, and Interrupt + OUT endpoints. This value is not used in device mode. + Valid values are from 1 to 16. (DWC3 SuperSpeed USB 3.0 Controller + Databook) + $ref: /schemas/types.yaml#/definitions/uint8 + minimum: 1 + maximum: 16 + snps,rx-thr-num-pkt-prd: description: Periodic ESS RX packet threshold count (host mode only). Set this and diff --git a/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml b/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml index 5497a60cddbc..323d664ae06a 100644 --- a/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml +++ b/Documentation/devicetree/bindings/usb/ti,tps6598x.yaml @@ -20,8 +20,23 @@ properties: enum: - ti,tps6598x - apple,cd321x + - ti,tps25750 + reg: - maxItems: 1 + minItems: 1 + items: + - description: main PD controller address + - description: | + I2C slave address field in PBMs input data + which is used as the device address when writing the + patch for TPS25750. + The patch address can be any value except 0x00, 0x20, + 0x21, 0x22, and 0x23 + + reg-names: + items: + - const: main + - const: patch-address wakeup-source: true @@ -32,11 +47,46 @@ properties: items: - const: irq + connector: + $ref: /schemas/connector/usb-connector.yaml# + + firmware-name: + description: | + Should contain the name of the default patch binary + file located on the firmware search path which is + used to switch the controller into APP mode. + This is used when tps25750 doesn't have an EEPROM + connected to it. + maxItems: 1 + required: - compatible - reg -additionalProperties: true +allOf: + - if: + properties: + compatible: + contains: + const: ti,tps25750 + then: + properties: + reg: + maxItems: 2 + + connector: + required: + - data-role + + required: + - connector + - reg-names + else: + properties: + reg: + maxItems: 1 + +additionalProperties: false examples: - | @@ -68,4 +118,36 @@ examples: }; }; }; + + - | + #include <dt-bindings/interrupt-controller/irq.h> + i2c { + #address-cells = <1>; + #size-cells = <0>; + + typec@21 { + compatible = "ti,tps25750"; + reg = <0x21>, <0x0f>; + reg-names = "main", "patch-address"; + + interrupt-parent = <&msmgpio>; + interrupts = <100 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "irq"; + firmware-name = "tps25750.bin"; + + pinctrl-names = "default"; + pinctrl-0 = <&typec_pins>; + + typec_con0: connector { + compatible = "usb-c-connector"; + label = "USB-C"; + data-role = "dual"; + port { + typec_ep0: endpoint { + remote-endpoint = <&otg_ep>; + }; + }; + }; + }; + }; ... diff --git a/Documentation/devicetree/bindings/usb/vialab,vl817.yaml b/Documentation/devicetree/bindings/usb/vialab,vl817.yaml index 76db9071b352..c815010ba9c2 100644 --- a/Documentation/devicetree/bindings/usb/vialab,vl817.yaml +++ b/Documentation/devicetree/bindings/usb/vialab,vl817.yaml @@ -37,7 +37,6 @@ properties: required: - compatible - reg - - reset-gpios - vdd-supply - peer-hub diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 25fd2dc378f5..309b94c328c8 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -59,6 +59,8 @@ patternProperties: description: AD Holdings Plc. "^adi,.*": description: Analog Devices, Inc. + "^adieng,.*": + description: ADI Engineering, Inc. "^advantech,.*": description: Advantech Corporation "^aeroflexgaisler,.*": @@ -127,6 +129,8 @@ patternProperties: description: Arasan Chip Systems "^archermind,.*": description: ArcherMind Technology (Nanjing) Co., Ltd. + "^arcom,.*": + description: Arcom Controllers "^arctic,.*": description: Arctic Sand "^arcx,.*": @@ -194,6 +198,8 @@ patternProperties: description: Shanghai Belling Co., Ltd. "^bhf,.*": description: Beckhoff Automation GmbH & Co. KG + "^bigtreetech,.*": + description: Shenzhen BigTree Tech Co., LTD "^bitmain,.*": description: Bitmain Technologies "^blutek,.*": @@ -484,6 +490,8 @@ patternProperties: description: FocalTech Systems Co.,Ltd "^forlinx,.*": description: Baoding Forlinx Embedded Technology Co., Ltd. + "^freecom,.*": + description: Freecom Gmbh "^frida,.*": description: Shenzhen Frida LCD Co., Ltd. "^friendlyarm,.*": @@ -496,6 +504,8 @@ patternProperties: description: FX Technology Ltd. "^gardena,.*": description: GARDENA GmbH + "^gateway,.*": + description: Gateway Communications "^gateworks,.*": description: Gateworks Corporation "^gcw,.*": @@ -510,6 +520,8 @@ patternProperties: description: GE Fanuc Intelligent Platforms Embedded Systems, Inc. "^gemei,.*": description: Gemei Digital Technology Co., Ltd. + "^gemtek,.*": + description: Gemtek Technology Co., Ltd. "^genesys,.*": description: Genesys Logic, Inc. "^geniatech,.*": @@ -530,6 +542,8 @@ patternProperties: description: Shenzhen Huiding Technology Co., Ltd. "^google,.*": description: Google, Inc. + "^goramo,.*": + description: Goramo Gorecki "^gplus,.*": description: GPLUS "^grinn,.*": @@ -805,6 +819,8 @@ patternProperties: description: Mantix Display Technology Co.,Ltd. "^mapleboard,.*": description: Mapleboard.org + "^marantec,.*": + description: Marantec electronics GmbH "^marvell,.*": description: Marvell Technology Group Ltd. "^maxbotix,.*": @@ -863,6 +879,8 @@ patternProperties: description: MikroElektronika d.o.o. "^mikrotik,.*": description: MikroTik + "^milkv,.*": + description: MilkV Technology Co., Ltd "^miniand,.*": description: Miniand Tech "^minix,.*": @@ -871,6 +889,8 @@ patternProperties: description: MiraMEMS Sensing Technology Co., Ltd. "^mitsubishi,.*": description: Mitsubishi Electric Corporation + "^mitsumi,.*": + description: Mitsumi Electric Co., Ltd. "^mixel,.*": description: Mixel, Inc. "^miyoo,.*": @@ -1275,6 +1295,8 @@ patternProperties: description: Solomon Systech Limited "^sony,.*": description: Sony Corporation + "^sophgo,.*": + description: Sophgo Technology Inc. "^sourceparts,.*": description: Source Parts Inc. "^spansion,.*": @@ -1422,6 +1444,8 @@ patternProperties: description: Truly Semiconductors Limited "^tsd,.*": description: Theobroma Systems Design und Consulting GmbH + "^turing,.*": + description: Turing Machines, Inc. "^tyan,.*": description: Tyan Computer Corporation "^u-blox,.*": @@ -1446,6 +1470,8 @@ patternProperties: description: United Radiant Technology Corporation "^usi,.*": description: Universal Scientific Industrial Co., Ltd. + "^usr,.*": + description: U.S. Robotics Corporation "^utoo,.*": description: Aigo Digital Technology Co., Ltd. "^v3,.*": diff --git a/Documentation/devicetree/bindings/watchdog/atmel,at91rm9200-wdt.yaml b/Documentation/devicetree/bindings/watchdog/atmel,at91rm9200-wdt.yaml new file mode 100644 index 000000000000..7af3571d89f2 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/atmel,at91rm9200-wdt.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/atmel,at91rm9200-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel AT91RM9200 System Timer Watchdog + +maintainers: + - Nicolas Ferre <nicolas.ferre@microchip.com> + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + const: atmel,at91rm9200-wdt + + reg: + maxItems: 1 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + watchdog@fffffd00 { + compatible = "atmel,at91rm9200-wdt"; + reg = <0xfffffd00 0x10>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/atmel-at91rm9200-wdt.txt b/Documentation/devicetree/bindings/watchdog/atmel-at91rm9200-wdt.txt deleted file mode 100644 index d4d86cf8f9eb..000000000000 --- a/Documentation/devicetree/bindings/watchdog/atmel-at91rm9200-wdt.txt +++ /dev/null @@ -1,9 +0,0 @@ -Atmel AT91RM9200 System Timer Watchdog - -Required properties: -- compatible: must be "atmel,at91sam9260-wdt". - -Example: - watchdog@fffffd00 { - compatible = "atmel,at91rm9200-wdt"; - }; diff --git a/Documentation/devicetree/bindings/watchdog/cnxt,cx92755-wdt.yaml b/Documentation/devicetree/bindings/watchdog/cnxt,cx92755-wdt.yaml new file mode 100644 index 000000000000..1844d7e026fe --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/cnxt,cx92755-wdt.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/cnxt,cx92755-wdt.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Conexant Digicolor SoCs Watchdog timer + +description: | + The watchdog functionality in Conexant Digicolor SoCs relies on the so called + "Agent Communication" block. This block includes the eight programmable system + timer counters. The first timer (called "Timer A") is the only one that can be + used as watchdog. + +allOf: + - $ref: watchdog.yaml# + +maintainers: + - Baruch Siach <baruch@tkos.co.il> + +properties: + compatible: + const: cnxt,cx92755-wdt + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - clocks + +unevaluatedProperties: false + +examples: + - | + watchdog@f0000fc0 { + compatible = "cnxt,cx92755-wdt"; + reg = <0xf0000fc0 0x8>; + clocks = <&main_clk>; + timeout-sec = <15>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt b/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt deleted file mode 100644 index 354314d854ef..000000000000 --- a/Documentation/devicetree/bindings/watchdog/da9062-wdt.txt +++ /dev/null @@ -1,34 +0,0 @@ -* Dialog Semiconductor DA9062/61 Watchdog Timer - -Required properties: - -- compatible: should be one of the following valid compatible string lines: - "dlg,da9061-watchdog", "dlg,da9062-watchdog" - "dlg,da9062-watchdog" - -Optional properties: -- dlg,use-sw-pm: Add this property to disable the watchdog during suspend. - Only use this option if you can't use the watchdog automatic suspend - function during a suspend (see register CONTROL_B). -- dlg,wdt-sd: Set what happens on watchdog timeout. If this bit is set the - watchdog timeout triggers SHUTDOWN, if cleared the watchdog triggers - POWERDOWN. Can be 0 or 1. Only use this option if you want to change the - default chip's OTP setting for WATCHDOG_SD bit. If this property is NOT - set the WATCHDOG_SD bit and on timeout watchdog behavior will match the - chip's OTP settings. - -Example: DA9062 - - pmic0: da9062@58 { - watchdog { - compatible = "dlg,da9062-watchdog"; - }; - }; - -Example: DA9061 using a fall-back compatible for the DA9062 watchdog driver - - pmic0: da9061@58 { - watchdog { - compatible = "dlg,da9061-watchdog", "dlg,da9062-watchdog"; - }; - }; diff --git a/Documentation/devicetree/bindings/watchdog/digicolor-wdt.txt b/Documentation/devicetree/bindings/watchdog/digicolor-wdt.txt deleted file mode 100644 index a882967e17d4..000000000000 --- a/Documentation/devicetree/bindings/watchdog/digicolor-wdt.txt +++ /dev/null @@ -1,25 +0,0 @@ -Conexant Digicolor SoCs Watchdog timer - -The watchdog functionality in Conexant Digicolor SoCs relies on the so called -"Agent Communication" block. This block includes the eight programmable system -timer counters. The first timer (called "Timer A") is the only one that can be -used as watchdog. - -Required properties: - -- compatible : Should be "cnxt,cx92755-wdt" -- reg : Specifies base physical address and size of the registers -- clocks : phandle; specifies the clock that drives the timer - -Optional properties: - -- timeout-sec : Contains the watchdog timeout in seconds - -Example: - - watchdog@f0000fc0 { - compatible = "cnxt,cx92755-wdt"; - reg = <0xf0000fc0 0x8>; - clocks = <&main_clk>; - timeout-sec = <15>; - }; diff --git a/Documentation/devicetree/bindings/watchdog/dlg,da9062-watchdog.yaml b/Documentation/devicetree/bindings/watchdog/dlg,da9062-watchdog.yaml new file mode 100644 index 000000000000..f058628bb632 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/dlg,da9062-watchdog.yaml @@ -0,0 +1,50 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/watchdog/dlg,da9062-watchdog.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Dialog Semiconductor DA9062/61 Watchdog Timer + +maintainers: + - Steve Twiss <stwiss.opensource@diasemi.com> + +allOf: + - $ref: watchdog.yaml# + +properties: + compatible: + enum: + - dlg,da9061-watchdog + - dlg,da9062-watchdog + + dlg,use-sw-pm: + type: boolean + description: + Add this property to disable the watchdog during suspend. + Only use this option if you can't use the watchdog automatic suspend + function during a suspend (see register CONTROL_B). + + dlg,wdt-sd: + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [0, 1] + description: + Set what happens on watchdog timeout. If this bit is set the + watchdog timeout triggers SHUTDOWN, if cleared the watchdog triggers + POWERDOWN. Can be 0 or 1. Only use this option if you want to change the + default chip's OTP setting for WATCHDOG_SD bit. If this property is NOT + set the WATCHDOG_SD bit and on timeout watchdog behavior will match the + chip's OTP settings. + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + watchdog { + compatible = "dlg,da9062-watchdog"; + dlg,use-sw-pm; + dlg,wdt-sd = <1>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml b/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml index 47701248cd8d..8b7aa922249b 100644 --- a/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml +++ b/Documentation/devicetree/bindings/watchdog/fsl,scu-wdt.yaml @@ -18,7 +18,9 @@ allOf: properties: compatible: items: - - const: fsl,imx8qxp-sc-wdt + - enum: + - fsl,imx8dxl-sc-wdt + - fsl,imx8qxp-sc-wdt - const: fsl,imx-sc-wdt required: diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index 4a381d20f2b4..0a6cf19a1459 100644 --- a/Documentation/devicetree/bindings/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -159,11 +159,14 @@ It is possible to run both in a single command:: make dt_binding_check dtbs_check It is also possible to run checks with a subset of matching schema files by -setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. +setting the ``DT_SCHEMA_FILES`` variable to 1 or more specific schema files or +patterns (partial match of a fixed string). Each file or pattern should be +separated by ':'. :: make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml + make dt_binding_check DT_SCHEMA_FILES=trivial-devices.yaml:rtc.yaml make dt_binding_check DT_SCHEMA_FILES=/gpio/ make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst index d4793826ad9a..662c7a840cd5 100644 --- a/Documentation/doc-guide/contributing.rst +++ b/Documentation/doc-guide/contributing.rst @@ -138,6 +138,10 @@ times, but it's highly important. If we can actually eliminate warnings from the documentation build, then we can start expecting developers to avoid adding new ones. +In addition to warnings from the regular documentation build, you can also +run ``make refcheckdocs`` to find references to nonexistent documentation +files. + Languishing kerneldoc comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/driver-api/80211/mac80211.rst b/Documentation/driver-api/80211/mac80211.rst index 67d2e58b45e4..e38a220401f5 100644 --- a/Documentation/driver-api/80211/mac80211.rst +++ b/Documentation/driver-api/80211/mac80211.rst @@ -120,7 +120,7 @@ functions/definitions ieee80211_rx ieee80211_rx_ni ieee80211_rx_irqsafe - ieee80211_tx_status + ieee80211_tx_status_skb ieee80211_tx_status_ni ieee80211_tx_status_irqsafe ieee80211_rts_get diff --git a/Documentation/driver-api/dpll.rst b/Documentation/driver-api/dpll.rst new file mode 100644 index 000000000000..e3d593841aa7 --- /dev/null +++ b/Documentation/driver-api/dpll.rst @@ -0,0 +1,551 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +The Linux kernel dpll subsystem +=============================== + +DPLL +==== + +PLL - Phase Locked Loop is an electronic circuit which syntonizes clock +signal of a device with an external clock signal. Effectively enabling +device to run on the same clock signal beat as provided on a PLL input. + +DPLL - Digital Phase Locked Loop is an integrated circuit which in +addition to plain PLL behavior incorporates a digital phase detector +and may have digital divider in the loop. As a result, the frequency on +DPLL's input and output may be configurable. + +Subsystem +========= + +The main purpose of dpll subsystem is to provide general interface +to configure devices that use any kind of Digital PLL and could use +different sources of input signal to synchronize to, as well as +different types of outputs. +The main interface is NETLINK_GENERIC based protocol with an event +monitoring multicast group defined. + +Device object +============= + +Single dpll device object means single Digital PLL circuit and bunch of +connected pins. +It reports the supported modes of operation and current status to the +user in response to the `do` request of netlink command +``DPLL_CMD_DEVICE_GET`` and list of dplls registered in the subsystem +with `dump` netlink request of the same command. +Changing the configuration of dpll device is done with `do` request of +netlink ``DPLL_CMD_DEVICE_SET`` command. +A device handle is ``DPLL_A_ID``, it shall be provided to get or set +configuration of particular device in the system. It can be obtained +with a ``DPLL_CMD_DEVICE_GET`` `dump` request or +a ``DPLL_CMD_DEVICE_ID_GET`` `do` request, where the one must provide +attributes that result in single device match. + +Pin object +========== + +A pin is amorphic object which represents either input or output, it +could be internal component of the device, as well as externally +connected. +The number of pins per dpll vary, but usually multiple pins shall be +provided for a single dpll device. +Pin's properties, capabilities and status is provided to the user in +response to `do` request of netlink ``DPLL_CMD_PIN_GET`` command. +It is also possible to list all the pins that were registered in the +system with `dump` request of ``DPLL_CMD_PIN_GET`` command. +Configuration of a pin can be changed by `do` request of netlink +``DPLL_CMD_PIN_SET`` command. +Pin handle is a ``DPLL_A_PIN_ID``, it shall be provided to get or set +configuration of particular pin in the system. It can be obtained with +``DPLL_CMD_PIN_GET`` `dump` request or ``DPLL_CMD_PIN_ID_GET`` `do` +request, where user provides attributes that result in single pin match. + +Pin selection +============= + +In general, selected pin (the one which signal is driving the dpll +device) can be obtained from ``DPLL_A_PIN_STATE`` attribute, and only +one pin shall be in ``DPLL_PIN_STATE_CONNECTED`` state for any dpll +device. + +Pin selection can be done either manually or automatically, depending +on hardware capabilities and active dpll device work mode +(``DPLL_A_MODE`` attribute). The consequence is that there are +differences for each mode in terms of available pin states, as well as +for the states the user can request for a dpll device. + +In manual mode (``DPLL_MODE_MANUAL``) the user can request or receive +one of following pin states: + +- ``DPLL_PIN_STATE_CONNECTED`` - the pin is used to drive dpll device +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin is not used to drive dpll + device + +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can request or +receive one of following pin states: + +- ``DPLL_PIN_STATE_SELECTABLE`` - the pin shall be considered as valid + input for automatic selection algorithm +- ``DPLL_PIN_STATE_DISCONNECTED`` - the pin shall be not considered as + a valid input for automatic selection algorithm + +In automatic mode (``DPLL_MODE_AUTOMATIC``) the user can only receive +pin state ``DPLL_PIN_STATE_CONNECTED`` once automatic selection +algorithm locks a dpll device with one of the inputs. + +Shared pins +=========== + +A single pin object can be attached to multiple dpll devices. +Then there are two groups of configuration knobs: + +1) Set on a pin - the configuration affects all dpll devices pin is + registered to (i.e., ``DPLL_A_PIN_FREQUENCY``), +2) Set on a pin-dpll tuple - the configuration affects only selected + dpll device (i.e., ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE``, + ``DPLL_A_PIN_DIRECTION``). + +MUX-type pins +============= + +A pin can be MUX-type, it aggregates child pins and serves as a pin +multiplexer. One or more pins are registered with MUX-type instead of +being directly registered to a dpll device. +Pins registered with a MUX-type pin provide user with additional nested +attribute ``DPLL_A_PIN_PARENT_PIN`` for each parent they were registered +with. +If a pin was registered with multiple parent pins, they behave like a +multiple output multiplexer. In this case output of a +``DPLL_CMD_PIN_GET`` would contain multiple pin-parent nested +attributes with current state related to each parent, like:: + + 'pin': [{{ + 'clock-id': 282574471561216, + 'module-name': 'ice', + 'capabilities': 4, + 'id': 13, + 'parent-pin': [ + {'parent-id': 2, 'state': 'connected'}, + {'parent-id': 3, 'state': 'disconnected'} + ], + 'type': 'synce-eth-port' + }}] + +Only one child pin can provide its signal to the parent MUX-type pin at +a time, the selection is done by requesting change of a child pin state +on desired parent, with the use of ``DPLL_A_PIN_PARENT`` nested +attribute. Example of netlink `set state on parent pin` message format: + + ========================== ============================================= + ``DPLL_A_PIN_ID`` child pin id + ``DPLL_A_PIN_PARENT_PIN`` nested attribute for requesting configuration + related to parent pin + ``DPLL_A_PIN_PARENT_ID`` parent pin id + ``DPLL_A_PIN_STATE`` requested pin state on parent + ========================== ============================================= + +Pin priority +============ + +Some devices might offer a capability of automatic pin selection mode +(enum value ``DPLL_MODE_AUTOMATIC`` of ``DPLL_A_MODE`` attribute). +Usually, automatic selection is performed on the hardware level, which +means only pins directly connected to the dpll can be used for automatic +input pin selection. +In automatic selection mode, the user cannot manually select a input +pin for the device, instead the user shall provide all directly +connected pins with a priority ``DPLL_A_PIN_PRIO``, the device would +pick a highest priority valid signal and use it to control the DPLL +device. Example of netlink `set priority on parent pin` message format: + + ============================ ============================================= + ``DPLL_A_PIN_ID`` configured pin id + ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting configuration + related to parent dpll device + ``DPLL_A_PIN_PARENT_ID`` parent dpll device id + ``DPLL_A_PIN_PRIO`` requested pin prio on parent dpll + ============================ ============================================= + +Child pin of MUX-type pin is not capable of automatic input pin selection, +in order to configure active input of a MUX-type pin, the user needs to +request desired pin state of the child pin on the parent pin, +as described in the ``MUX-type pins`` chapter. + +Phase offset measurement and adjustment +======================================== + +Device may provide ability to measure a phase difference between signals +on a pin and its parent dpll device. If pin-dpll phase offset measurement +is supported, it shall be provided with ``DPLL_A_PIN_PHASE_OFFSET`` +attribute for each parent dpll device. + +Device may also provide ability to adjust a signal phase on a pin. +If pin phase adjustment is supported, minimal and maximal values that pin +handle shall be provide to the user on ``DPLL_CMD_PIN_GET`` respond +with ``DPLL_A_PIN_PHASE_ADJUST_MIN`` and ``DPLL_A_PIN_PHASE_ADJUST_MAX`` +attributes. Configured phase adjust value is provided with +``DPLL_A_PIN_PHASE_ADJUST`` attribute of a pin, and value change can be +requested with the same attribute with ``DPLL_CMD_PIN_SET`` command. + + =============================== ====================================== + ``DPLL_A_PIN_ID`` configured pin id + ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase adjustment + ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase adjustment + ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase + adjustment on parent dpll device + ``DPLL_A_PIN_PARENT_DEVICE`` nested attribute for requesting + configuration on given parent dpll + device + ``DPLL_A_PIN_PARENT_ID`` parent dpll device id + ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference + between a pin and parent dpll device + =============================== ====================================== + +All phase related values are provided in pico seconds, which represents +time difference between signals phase. The negative value means that +phase of signal on pin is earlier in time than dpll's signal. Positive +value means that phase of signal on pin is later in time than signal of +a dpll. + +Phase adjust (also min and max) values are integers, but measured phase +offset values are fractional with 3-digit decimal places and shell be +divided with ``DPLL_PIN_PHASE_OFFSET_DIVIDER`` to get integer part and +modulo divided to get fractional part. + +Configuration commands group +============================ + +Configuration commands are used to get information about registered +dpll devices (and pins), as well as set configuration of device or pins. +As dpll devices must be abstracted and reflect real hardware, +there is no way to add new dpll device via netlink from user space and +each device should be registered by its driver. + +All netlink commands require ``GENL_ADMIN_PERM``. This is to prevent +any spamming/DoS from unauthorized userspace applications. + +List of netlink commands with possible attributes +================================================= + +Constants identifying command types for dpll device uses a +``DPLL_CMD_`` prefix and suffix according to command purpose. +The dpll device related attributes use a ``DPLL_A_`` prefix and +suffix according to attribute purpose. + + ==================================== ================================= + ``DPLL_CMD_DEVICE_ID_GET`` command to get device ID + ``DPLL_A_MODULE_NAME`` attr module name of registerer + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_TYPE`` attr type of dpll device + ==================================== ================================= + + ==================================== ================================= + ``DPLL_CMD_DEVICE_GET`` command to get device info or + dump list of available devices + ``DPLL_A_ID`` attr unique dpll device ID + ``DPLL_A_MODULE_NAME`` attr module name of registerer + ``DPLL_A_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_MODE`` attr selection mode + ``DPLL_A_MODE_SUPPORTED`` attr available selection modes + ``DPLL_A_LOCK_STATUS`` attr dpll device lock status + ``DPLL_A_TEMP`` attr device temperature info + ``DPLL_A_TYPE`` attr type of dpll device + ==================================== ================================= + + ==================================== ================================= + ``DPLL_CMD_DEVICE_SET`` command to set dpll device config + ``DPLL_A_ID`` attr internal dpll device index + ``DPLL_A_MODE`` attr selection mode to configure + ==================================== ================================= + +Constants identifying command types for pins uses a +``DPLL_CMD_PIN_`` prefix and suffix according to command purpose. +The pin related attributes use a ``DPLL_A_PIN_`` prefix and suffix +according to attribute purpose. + + ==================================== ================================= + ``DPLL_CMD_PIN_ID_GET`` command to get pin ID + ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer + ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided + by registerer + ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided + by registerer + ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided + by registerer + ``DPLL_A_PIN_TYPE`` attr type of a pin + ==================================== ================================= + + ==================================== ================================== + ``DPLL_CMD_PIN_GET`` command to get pin info or dump + list of available pins + ``DPLL_A_PIN_ID`` attr unique a pin ID + ``DPLL_A_PIN_MODULE_NAME`` attr module name of registerer + ``DPLL_A_PIN_CLOCK_ID`` attr Unique Clock Identifier + (EUI-64), as defined by the + IEEE 1588 standard + ``DPLL_A_PIN_BOARD_LABEL`` attr pin board label provided + by registerer + ``DPLL_A_PIN_PANEL_LABEL`` attr pin panel label provided + by registerer + ``DPLL_A_PIN_PACKAGE_LABEL`` attr pin package label provided + by registerer + ``DPLL_A_PIN_TYPE`` attr type of a pin + ``DPLL_A_PIN_FREQUENCY`` attr current frequency of a pin + ``DPLL_A_PIN_FREQUENCY_SUPPORTED`` nested attr provides supported + frequencies + ``DPLL_A_PIN_ANY_FREQUENCY_MIN`` attr minimum value of frequency + ``DPLL_A_PIN_ANY_FREQUENCY_MAX`` attr maximum value of frequency + ``DPLL_A_PIN_PHASE_ADJUST_MIN`` attr minimum value of phase + adjustment + ``DPLL_A_PIN_PHASE_ADJUST_MAX`` attr maximum value of phase + adjustment + ``DPLL_A_PIN_PHASE_ADJUST`` attr configured value of phase + adjustment on parent device + ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent device + the pin is connected with + ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id + ``DPLL_A_PIN_PRIO`` attr priority of pin on the + dpll device + ``DPLL_A_PIN_STATE`` attr state of pin on the parent + dpll device + ``DPLL_A_PIN_DIRECTION`` attr direction of a pin on the + parent dpll device + ``DPLL_A_PIN_PHASE_OFFSET`` attr measured phase difference + between a pin and parent dpll + ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin + the pin is connected with + ``DPLL_A_PIN_PARENT_ID`` attr parent pin id + ``DPLL_A_PIN_STATE`` attr state of pin on the parent + pin + ``DPLL_A_PIN_CAPABILITIES`` attr bitmask of pin capabilities + ==================================== ================================== + + ==================================== ================================= + ``DPLL_CMD_PIN_SET`` command to set pins configuration + ``DPLL_A_PIN_ID`` attr unique a pin ID + ``DPLL_A_PIN_FREQUENCY`` attr requested frequency of a pin + ``DPLL_A_PIN_PHASE_ADJUST`` attr requested value of phase + adjustment on parent device + ``DPLL_A_PIN_PARENT_DEVICE`` nested attr for each parent dpll + device configuration request + ``DPLL_A_PIN_PARENT_ID`` attr parent dpll device id + ``DPLL_A_PIN_DIRECTION`` attr requested direction of a pin + ``DPLL_A_PIN_PRIO`` attr requested priority of pin on + the dpll device + ``DPLL_A_PIN_STATE`` attr requested state of pin on + the dpll device + ``DPLL_A_PIN_PARENT_PIN`` nested attr for each parent pin + configuration request + ``DPLL_A_PIN_PARENT_ID`` attr parent pin id + ``DPLL_A_PIN_STATE`` attr requested state of pin on + parent pin + ==================================== ================================= + +Netlink dump requests +===================== + +The ``DPLL_CMD_DEVICE_GET`` and ``DPLL_CMD_PIN_GET`` commands are +capable of dump type netlink requests, in which case the response is in +the same format as for their ``do`` request, but every device or pin +registered in the system is returned. + +SET commands format +=================== + +``DPLL_CMD_DEVICE_SET`` - to target a dpll device, the user provides +``DPLL_A_ID``, which is unique identifier of dpll device in the system, +as well as parameter being configured (``DPLL_A_MODE``). + +``DPLL_CMD_PIN_SET`` - to target a pin user must provide a +``DPLL_A_PIN_ID``, which is unique identifier of a pin in the system. +Also configured pin parameters must be added. +If ``DPLL_A_PIN_FREQUENCY`` is configured, this affects all the dpll +devices that are connected with the pin, that is why frequency attribute +shall not be enclosed in ``DPLL_A_PIN_PARENT_DEVICE``. +Other attributes: ``DPLL_A_PIN_PRIO``, ``DPLL_A_PIN_STATE`` or +``DPLL_A_PIN_DIRECTION`` must be enclosed in +``DPLL_A_PIN_PARENT_DEVICE`` as their configuration relates to only one +of parent dplls, targeted by ``DPLL_A_PIN_PARENT_ID`` attribute which is +also required inside that nest. +For MUX-type pins the ``DPLL_A_PIN_STATE`` attribute is configured in +similar way, by enclosing required state in ``DPLL_A_PIN_PARENT_PIN`` +nested attribute and targeted parent pin id in ``DPLL_A_PIN_PARENT_ID``. + +In general, it is possible to configure multiple parameters at once, but +internally each parameter change will be invoked separately, where order +of configuration is not guaranteed by any means. + +Configuration pre-defined enums +=============================== + +.. kernel-doc:: include/uapi/linux/dpll.h + +Notifications +============= + +dpll device can provide notifications regarding status changes of the +device, i.e. lock status changes, input/output changes or other alarms. +There is one multicast group that is used to notify user-space apps via +netlink socket: ``DPLL_MCGRP_MONITOR`` + +Notifications messages: + + ============================== ===================================== + ``DPLL_CMD_DEVICE_CREATE_NTF`` dpll device was created + ``DPLL_CMD_DEVICE_DELETE_NTF`` dpll device was deleted + ``DPLL_CMD_DEVICE_CHANGE_NTF`` dpll device has changed + ``DPLL_CMD_PIN_CREATE_NTF`` dpll pin was created + ``DPLL_CMD_PIN_DELETE_NTF`` dpll pin was deleted + ``DPLL_CMD_PIN_CHANGE_NTF`` dpll pin has changed + ============================== ===================================== + +Events format is the same as for the corresponding get command. +Format of ``DPLL_CMD_DEVICE_`` events is the same as response of +``DPLL_CMD_DEVICE_GET``. +Format of ``DPLL_CMD_PIN_`` events is same as response of +``DPLL_CMD_PIN_GET``. + +Device driver implementation +============================ + +Device is allocated by dpll_device_get() call. Second call with the +same arguments will not create new object but provides pointer to +previously created device for given arguments, it also increases +refcount of that object. +Device is deallocated by dpll_device_put() call, which first +decreases the refcount, once refcount is cleared the object is +destroyed. + +Device should implement set of operations and register device via +dpll_device_register() at which point it becomes available to the +users. Multiple driver instances can obtain reference to it with +dpll_device_get(), as well as register dpll device with their own +ops and priv. + +The pins are allocated separately with dpll_pin_get(), it works +similarly to dpll_device_get(). Function first creates object and then +for each call with the same arguments only the object refcount +increases. Also dpll_pin_put() works similarly to dpll_device_put(). + +A pin can be registered with parent dpll device or parent pin, depending +on hardware needs. Each registration requires registerer to provide set +of pin callbacks, and private data pointer for calling them: + +- dpll_pin_register() - register pin with a dpll device, +- dpll_pin_on_pin_register() - register pin with another MUX type pin. + +Notifications of adding or removing dpll devices are created within +subsystem itself. +Notifications about registering/deregistering pins are also invoked by +the subsystem. +Notifications about status changes either of dpll device or a pin are +invoked in two ways: + +- after successful change was requested on dpll subsystem, the subsystem + calls corresponding notification, +- requested by device driver with dpll_device_change_ntf() or + dpll_pin_change_ntf() when driver informs about the status change. + +The device driver using dpll interface is not required to implement all +the callback operation. Nevertheless, there are few required to be +implemented. +Required dpll device level callback operations: + +- ``.mode_get``, +- ``.lock_status_get``. + +Required pin level callback operations: + +- ``.state_on_dpll_get`` (pins registered with dpll device), +- ``.state_on_pin_get`` (pins registered with parent pin), +- ``.direction_get``. + +Every other operation handler is checked for existence and +``-EOPNOTSUPP`` is returned in case of absence of specific handler. + +The simplest implementation is in the OCP TimeCard driver. The ops +structures are defined like this: + +.. code-block:: c + + static const struct dpll_device_ops dpll_ops = { + .lock_status_get = ptp_ocp_dpll_lock_status_get, + .mode_get = ptp_ocp_dpll_mode_get, + .mode_supported = ptp_ocp_dpll_mode_supported, + }; + + static const struct dpll_pin_ops dpll_pins_ops = { + .frequency_get = ptp_ocp_dpll_frequency_get, + .frequency_set = ptp_ocp_dpll_frequency_set, + .direction_get = ptp_ocp_dpll_direction_get, + .direction_set = ptp_ocp_dpll_direction_set, + .state_on_dpll_get = ptp_ocp_dpll_state_get, + }; + +The registration part is then looks like this part: + +.. code-block:: c + + clkid = pci_get_dsn(pdev); + bp->dpll = dpll_device_get(clkid, 0, THIS_MODULE); + if (IS_ERR(bp->dpll)) { + err = PTR_ERR(bp->dpll); + dev_err(&pdev->dev, "dpll_device_alloc failed\n"); + goto out; + } + + err = dpll_device_register(bp->dpll, DPLL_TYPE_PPS, &dpll_ops, bp); + if (err) + goto out; + + for (i = 0; i < OCP_SMA_NUM; i++) { + bp->sma[i].dpll_pin = dpll_pin_get(clkid, i, THIS_MODULE, &bp->sma[i].dpll_prop); + if (IS_ERR(bp->sma[i].dpll_pin)) { + err = PTR_ERR(bp->dpll); + goto out_dpll; + } + + err = dpll_pin_register(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, + &bp->sma[i]); + if (err) { + dpll_pin_put(bp->sma[i].dpll_pin); + goto out_dpll; + } + } + +In the error path we have to rewind every allocation in the reverse order: + +.. code-block:: c + + while (i) { + --i; + dpll_pin_unregister(bp->dpll, bp->sma[i].dpll_pin, &dpll_pins_ops, &bp->sma[i]); + dpll_pin_put(bp->sma[i].dpll_pin); + } + dpll_device_put(bp->dpll); + +More complex example can be found in Intel's ICE driver or nVidia's mlx5 driver. + +SyncE enablement +================ +For SyncE enablement it is required to allow control over dpll device +for a software application which monitors and configures the inputs of +dpll device in response to current state of a dpll device and its +inputs. +In such scenario, dpll device input signal shall be also configurable +to drive dpll with signal recovered from the PHY netdevice. +This is done by exposing a pin to the netdevice - attaching pin to the +netdevice itself with +``netdev_dpll_pin_set(struct net_device *dev, struct dpll_pin *dpll_pin)``. +Exposed pin id handle ``DPLL_A_PIN_ID`` is then identifiable by the user +as it is attached to rtnetlink respond to get ``RTM_NEWLINK`` command in +nested attribute ``IFLA_DPLL_PIN``. diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 8be086b3f829..c5f99d834ec5 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -322,10 +322,8 @@ IOMAP devm_platform_ioremap_resource_byname() devm_platform_get_and_ioremap_resource() devm_iounmap() - pcim_iomap() - pcim_iomap_regions() : do request_region() and iomap() on multiple BARs - pcim_iomap_table() : array of mapped addresses indexed by BAR - pcim_iounmap() + + Note: For the PCI devices the specific pcim_*() functions may be used, see below. IRQ devm_free_irq() @@ -392,8 +390,16 @@ PCI devm_pci_alloc_host_bridge() : managed PCI host bridge allocation devm_pci_remap_cfgspace() : ioremap PCI configuration space devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource + pcim_enable_device() : after success, all PCI ops become managed + pcim_iomap() : do iomap() on a single BAR + pcim_iomap_regions() : do request_region() and iomap() on multiple BARs + pcim_iomap_regions_request_all() : do request_region() on all and iomap() on multiple BARs + pcim_iomap_table() : array of mapped addresses indexed by BAR + pcim_iounmap() : do iounmap() on a single BAR + pcim_iounmap_regions() : do iounmap() and release_region() on multiple BARs pcim_pin_device() : keep PCI device enabled after release + pcim_set_mwi() : enable Memory-Write-Invalidate PCI transaction PHY devm_usb_get_phy() diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index de6fc79ad6f0..3e588b9d678c 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -29,6 +29,10 @@ warnings. These stubs are used for two use cases: will use it under other compile-time configurations. In this case the consumer must make sure not to call into these functions, or the user will be met with console warnings that may be perceived as intimidating. + Combining truly optional GPIOLIB usage with calls to + ``[devm_]gpiod_get_optional()`` is a *bad idea*, and will result in weird + error messages. Use the ordinary getter functions with optional GPIOLIB: + some open coding of error handling should be expected when you do this. All the functions that work with the descriptor-based GPIO interface are prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst index 02653defa011..23a0b93c62b1 100644 --- a/Documentation/driver-api/i3c/protocol.rst +++ b/Documentation/driver-api/i3c/protocol.rst @@ -71,8 +71,8 @@ During DAA, each I3C device reports 3 important things: related capabilities * DCR: Device Characteristic Register. This 8-bit register describes the functionalities provided by the device -* Provisional ID: A 48-bit unique identifier. On a given bus there should be no - Provisional ID collision, otherwise the discovery mechanism may fail. +* Provisioned ID: A 48-bit unique identifier. On a given bus there should be no + Provisioned ID collision, otherwise the discovery mechanism may fail. I3C slave events ================ diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 1e16a40da3ba..f549a68951d7 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -114,6 +114,7 @@ available subsections can be seen below. zorro hte/index wmi + dpll .. only:: subproject and html diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 93f4f2536c25..6456145f96ed 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -1,8 +1,14 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _media_writing_camera_sensor_drivers: + Writing camera sensor drivers ============================= +This document covers the in-kernel APIs only. For the best practices on +userspace API implementation in camera sensor drivers, please see +:ref:`media_using_camera_sensor_drivers`. + CSI-2 and parallel (BT.601 and BT.656) busses --------------------------------------------- @@ -13,7 +19,7 @@ Handling clocks Camera sensors have an internal clock tree including a PLL and a number of divisors. The clock tree is generally configured by the driver based on a few -input parameters that are specific to the hardware:: the external clock frequency +input parameters that are specific to the hardware: the external clock frequency and the link frequency. The two parameters generally are obtained from system firmware. **No other frequencies should be used in any circumstances.** @@ -32,110 +38,61 @@ can rely on this frequency being used. Devicetree ~~~~~~~~~~ -The currently preferred way to achieve this is using ``assigned-clocks``, -``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See -``Documentation/devicetree/bindings/clock/clock-bindings.txt`` for more -information. The driver then gets the frequency using ``clk_get_rate()``. +The preferred way to achieve this is using ``assigned-clocks``, +``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See the +`clock device tree bindings +<https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml>`_ +for more information. The driver then gets the frequency using +``clk_get_rate()``. This approach has the drawback that there's no guarantee that the frequency hasn't been modified directly or indirectly by another driver, or supported by the board's clock tree to begin with. Changes to the Common Clock Framework API are required to ensure reliability. -Frame size ----------- - -There are two distinct ways to configure the frame size produced by camera -sensors. - -Freely configurable camera sensor drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Freely configurable camera sensor drivers expose the device's internal -processing pipeline as one or more sub-devices with different cropping and -scaling configurations. The output size of the device is the result of a series -of cropping and scaling operations from the device's pixel array's size. - -An example of such a driver is the CCS driver (see ``drivers/media/i2c/ccs``). - -Register list based drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Register list based drivers generally, instead of able to configure the device -they control based on user requests, are limited to a number of preset -configurations that combine a number of different parameters that on hardware -level are independent. How a driver picks such configuration is based on the -format set on a source pad at the end of the device's internal pipeline. - -Most sensor drivers are implemented this way, see e.g. -``drivers/media/i2c/imx319.c`` for an example. - -Frame interval configuration ----------------------------- - -There are two different methods for obtaining possibilities for different frame -intervals as well as configuring the frame interval. Which one to implement -depends on the type of the device. - -Raw camera sensors -~~~~~~~~~~~~~~~~~~ - -Instead of a high level parameter such as frame interval, the frame interval is -a result of the configuration of a number of camera sensor implementation -specific parameters. Luckily, these parameters tend to be the same for more or -less all modern raw camera sensors. - -The frame interval is calculated using the following equation:: - - frame interval = (analogue crop width + horizontal blanking) * - (analogue crop height + vertical blanking) / pixel rate - -The formula is bus independent and is applicable for raw timing parameters on -large variety of devices beyond camera sensors. Devices that have no analogue -crop, use the full source image size, i.e. pixel array size. - -Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and -``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control -is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in -the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same -sub-device. The unit of that control is pixels per second. - -Register list based drivers need to implement read-only sub-device nodes for the -purpose. Devices that are not register list based need these to configure the -device's internal processing pipeline. - -The first entity in the linear pipeline is the pixel array. The pixel array may -be followed by other entities that are there to allow configuring binning, -skipping, scaling or digital crop :ref:`v4l2-subdev-selections`. - -USB cameras etc. devices -~~~~~~~~~~~~~~~~~~~~~~~~ - -USB video class hardware, as well as many cameras offering a similar higher -level interface natively, generally use the concept of frame interval (or frame -rate) on device level in firmware or hardware. This means lower level controls -implemented by raw cameras may not be used on uAPI (or even kAPI) to control the -frame interval on these devices. - Power management ---------------- -Always use runtime PM to manage the power states of your device. Camera sensor -drivers are in no way special in this respect: they are responsible for -controlling the power state of the device they otherwise control as well. In -general, the device must be powered on at least when its registers are being -accessed and when it is streaming. - -Existing camera sensor drivers may rely on the old -struct v4l2_subdev_core_ops->s_power() callback for bridge or ISP drivers to -manage their power state. This is however **deprecated**. If you feel you need -to begin calling an s_power from an ISP or a bridge driver, instead please add -runtime PM support to the sensor driver you are using. Likewise, new drivers -should not use s_power. - -Please see examples in e.g. ``drivers/media/i2c/ov8856.c`` and -``drivers/media/i2c/ccs/ccs-core.c``. The two drivers work in both ACPI -and DT based systems. +Camera sensors are used in conjunction with other devices to form a camera +pipeline. They must obey the rules listed herein to ensure coherent power +management over the pipeline. + +Camera sensor drivers are responsible for controlling the power state of the +device they otherwise control as well. They shall use runtime PM to manage +power states. Runtime PM shall be enabled at probe time and disabled at remove +time. Drivers should enable runtime PM autosuspend. + +The runtime PM handlers shall handle clocks, regulators, GPIOs, and other +system resources required to power the sensor up and down. For drivers that +don't use any of those resources (such as drivers that support ACPI systems +only), the runtime PM handlers may be left unimplemented. + +In general, the device shall be powered on at least when its registers are +being accessed and when it is streaming. Drivers should use +``pm_runtime_resume_and_get()`` when starting streaming and +``pm_runtime_put()`` or ``pm_runtime_put_autosuspend()`` when stopping +streaming. They may power the device up at probe time (for example to read +identification registers), but should not keep it powered unconditionally after +probe. + +At system suspend time, the whole camera pipeline must stop streaming, and +restart when the system is resumed. This requires coordination between the +camera sensor and the rest of the camera pipeline. Bridge drivers are +responsible for this coordination, and instruct camera sensors to stop and +restart streaming by calling the appropriate subdev operations +(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera +sensor drivers shall therefore **not** keep track of the streaming state to +stop streaming in the PM suspend handler and restart it in the resume handler. +Drivers should in general not implement the system PM handlers. + +Camera sensor drivers shall **not** implement the subdev ``.s_power()`` +operation, as it is deprecated. While this operation is implemented in some +existing drivers as they predate the deprecation, new drivers shall use runtime +PM instead. If you feel you need to begin calling ``.s_power()`` from an ISP or +a bridge driver, instead add runtime PM support to the sensor driver you are +using and drop its ``.s_power()`` handler. + +Please also see :ref:`examples <media-camera-sensor-examples>`. Control framework ~~~~~~~~~~~~~~~~~ @@ -155,21 +112,36 @@ access the device. Rotation, orientation and flipping ---------------------------------- -Some systems have the camera sensor mounted upside down compared to its natural -mounting rotation. In such cases, drivers shall expose the information to -userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION -<v4l2-camera-sensor-rotation>` control. - -Sensor drivers shall also report the sensor's mounting orientation with the -:ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`. - Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to register the appropriate controls. -Sensor drivers that have any vertical or horizontal flips embedded in the -register programming sequences shall initialize the V4L2_CID_HFLIP and -V4L2_CID_VFLIP controls with the values programmed by the register sequences. -The default values of these controls shall be 0 (disabled). Especially these -controls shall not be inverted, independently of the sensor's mounting -rotation. +.. _media-camera-sensor-examples: + +Example drivers +--------------- + +Features implemented by sensor drivers vary, and depending on the set of +supported features and other qualities, particular sensor drivers better serve +the purpose of an example. The following drivers are known to be good examples: + +.. flat-table:: Example sensor drivers + :header-rows: 0 + :widths: 1 1 1 2 + + * - Driver name + - File(s) + - Driver type + - Example topic + * - CCS + - ``drivers/media/i2c/ccs/`` + - Freely configurable + - Power management (ACPI and DT), UAPI + * - imx219 + - ``drivers/media/i2c/imx219.c`` + - Register list based + - Power management (DT), UAPI, mode selection + * - imx319 + - ``drivers/media/i2c/imx319.c`` + - Register list based + - Power management (ACPI and DT) diff --git a/Documentation/driver-api/media/drivers/ccs/ccs.rst b/Documentation/driver-api/media/drivers/ccs/ccs.rst index 7389204afcb8..776eec72bc80 100644 --- a/Documentation/driver-api/media/drivers/ccs/ccs.rst +++ b/Documentation/driver-api/media/drivers/ccs/ccs.rst @@ -30,7 +30,7 @@ that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the sink pad (0). Additionally, if a device has no scaler or digital crop functionality, the -source pad (1) expses another digital crop selection rectangle that can only +source pad (1) exposes another digital crop selection rectangle that can only crop at the end of the lines and frames. Scaler @@ -78,6 +78,14 @@ For SMIA (non-++) compliant devices the static data file name is vvvv or vv denotes MIPI and SMIA manufacturer IDs respectively, mmmm model ID and rrrr or rr revision number. +CCS tools +~~~~~~~~~ + +`CCS tools <https://github.com/MIPI-Alliance/ccs-tools/>`_ is a set of +tools for working with CCS static data files. CCS tools includes a +definition of the human-readable CCS static data YAML format and includes a +program to convert it to a binary. + Register definition generator ----------------------------- diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst index 239045ecc8f4..58cba831ade5 100644 --- a/Documentation/driver-api/media/v4l2-core.rst +++ b/Documentation/driver-api/media/v4l2-core.rst @@ -13,7 +13,6 @@ Video4Linux devices v4l2-subdev v4l2-event v4l2-controls - v4l2-videobuf v4l2-videobuf2 v4l2-dv-timings v4l2-flash-led-class diff --git a/Documentation/driver-api/media/v4l2-dev.rst b/Documentation/driver-api/media/v4l2-dev.rst index 99e3b5fa7444..d5cb19b21a9f 100644 --- a/Documentation/driver-api/media/v4l2-dev.rst +++ b/Documentation/driver-api/media/v4l2-dev.rst @@ -157,14 +157,6 @@ changing the e.g. exposure of the webcam. Of course, you can always do all the locking yourself by leaving both lock pointers at ``NULL``. -If you use the old :ref:`videobuf framework <vb_framework>` then you must -pass the :c:type:`video_device`->lock to the videobuf queue initialize -function: if videobuf has to wait for a frame to arrive, then it will -temporarily unlock the lock and relock it afterwards. If your driver also -waits in the code, then you should do the same to allow other -processes to access the device node while the first process is waiting for -something. - In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the ``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable. If you use the ``queue->lock`` pointer, then you can use the helper functions diff --git a/Documentation/driver-api/media/v4l2-videobuf.rst b/Documentation/driver-api/media/v4l2-videobuf.rst deleted file mode 100644 index 4b1d84eefeb8..000000000000 --- a/Documentation/driver-api/media/v4l2-videobuf.rst +++ /dev/null @@ -1,403 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _vb_framework: - -Videobuf Framework -================== - -Author: Jonathan Corbet <corbet@lwn.net> - -Current as of 2.6.33 - -.. note:: - - The videobuf framework was deprecated in favor of videobuf2. Shouldn't - be used on new drivers. - -Introduction ------------- - -The videobuf layer functions as a sort of glue layer between a V4L2 driver -and user space. It handles the allocation and management of buffers for -the storage of video frames. There is a set of functions which can be used -to implement many of the standard POSIX I/O system calls, including read(), -poll(), and, happily, mmap(). Another set of functions can be used to -implement the bulk of the V4L2 ioctl() calls related to streaming I/O, -including buffer allocation, queueing and dequeueing, and streaming -control. Using videobuf imposes a few design decisions on the driver -author, but the payback comes in the form of reduced code in the driver and -a consistent implementation of the V4L2 user-space API. - -Buffer types ------------- - -Not all video devices use the same kind of buffers. In fact, there are (at -least) three common variations: - - - Buffers which are scattered in both the physical and (kernel) virtual - address spaces. (Almost) all user-space buffers are like this, but it - makes great sense to allocate kernel-space buffers this way as well when - it is possible. Unfortunately, it is not always possible; working with - this kind of buffer normally requires hardware which can do - scatter/gather DMA operations. - - - Buffers which are physically scattered, but which are virtually - contiguous; buffers allocated with vmalloc(), in other words. These - buffers are just as hard to use for DMA operations, but they can be - useful in situations where DMA is not available but virtually-contiguous - buffers are convenient. - - - Buffers which are physically contiguous. Allocation of this kind of - buffer can be unreliable on fragmented systems, but simpler DMA - controllers cannot deal with anything else. - -Videobuf can work with all three types of buffers, but the driver author -must pick one at the outset and design the driver around that decision. - -[It's worth noting that there's a fourth kind of buffer: "overlay" buffers -which are located within the system's video memory. The overlay -functionality is considered to be deprecated for most use, but it still -shows up occasionally in system-on-chip drivers where the performance -benefits merit the use of this technique. Overlay buffers can be handled -as a form of scattered buffer, but there are very few implementations in -the kernel and a description of this technique is currently beyond the -scope of this document.] - -Data structures, callbacks, and initialization ----------------------------------------------- - -Depending on which type of buffers are being used, the driver should -include one of the following files: - -.. code-block:: none - - <media/videobuf-dma-sg.h> /* Physically scattered */ - <media/videobuf-vmalloc.h> /* vmalloc() buffers */ - <media/videobuf-dma-contig.h> /* Physically contiguous */ - -The driver's data structure describing a V4L2 device should include a -struct videobuf_queue instance for the management of the buffer queue, -along with a list_head for the queue of available buffers. There will also -need to be an interrupt-safe spinlock which is used to protect (at least) -the queue. - -The next step is to write four simple callbacks to help videobuf deal with -the management of buffers: - -.. code-block:: none - - struct videobuf_queue_ops { - int (*buf_setup)(struct videobuf_queue *q, - unsigned int *count, unsigned int *size); - int (*buf_prepare)(struct videobuf_queue *q, - struct videobuf_buffer *vb, - enum v4l2_field field); - void (*buf_queue)(struct videobuf_queue *q, - struct videobuf_buffer *vb); - void (*buf_release)(struct videobuf_queue *q, - struct videobuf_buffer *vb); - }; - -buf_setup() is called early in the I/O process, when streaming is being -initiated; its purpose is to tell videobuf about the I/O stream. The count -parameter will be a suggested number of buffers to use; the driver should -check it for rationality and adjust it if need be. As a practical rule, a -minimum of two buffers are needed for proper streaming, and there is -usually a maximum (which cannot exceed 32) which makes sense for each -device. The size parameter should be set to the expected (maximum) size -for each frame of data. - -Each buffer (in the form of a struct videobuf_buffer pointer) will be -passed to buf_prepare(), which should set the buffer's size, width, height, -and field fields properly. If the buffer's state field is -VIDEOBUF_NEEDS_INIT, the driver should pass it to: - -.. code-block:: none - - int videobuf_iolock(struct videobuf_queue* q, struct videobuf_buffer *vb, - struct v4l2_framebuffer *fbuf); - -Among other things, this call will usually allocate memory for the buffer. -Finally, the buf_prepare() function should set the buffer's state to -VIDEOBUF_PREPARED. - -When a buffer is queued for I/O, it is passed to buf_queue(), which should -put it onto the driver's list of available buffers and set its state to -VIDEOBUF_QUEUED. Note that this function is called with the queue spinlock -held; if it tries to acquire it as well things will come to a screeching -halt. Yes, this is the voice of experience. Note also that videobuf may -wait on the first buffer in the queue; placing other buffers in front of it -could again gum up the works. So use list_add_tail() to enqueue buffers. - -Finally, buf_release() is called when a buffer is no longer intended to be -used. The driver should ensure that there is no I/O active on the buffer, -then pass it to the appropriate free routine(s): - -.. code-block:: none - - /* Scatter/gather drivers */ - int videobuf_dma_unmap(struct videobuf_queue *q, - struct videobuf_dmabuf *dma); - int videobuf_dma_free(struct videobuf_dmabuf *dma); - - /* vmalloc drivers */ - void videobuf_vmalloc_free (struct videobuf_buffer *buf); - - /* Contiguous drivers */ - void videobuf_dma_contig_free(struct videobuf_queue *q, - struct videobuf_buffer *buf); - -One way to ensure that a buffer is no longer under I/O is to pass it to: - -.. code-block:: none - - int videobuf_waiton(struct videobuf_buffer *vb, int non_blocking, int intr); - -Here, vb is the buffer, non_blocking indicates whether non-blocking I/O -should be used (it should be zero in the buf_release() case), and intr -controls whether an interruptible wait is used. - -File operations ---------------- - -At this point, much of the work is done; much of the rest is slipping -videobuf calls into the implementation of the other driver callbacks. The -first step is in the open() function, which must initialize the -videobuf queue. The function to use depends on the type of buffer used: - -.. code-block:: none - - void videobuf_queue_sg_init(struct videobuf_queue *q, - struct videobuf_queue_ops *ops, - struct device *dev, - spinlock_t *irqlock, - enum v4l2_buf_type type, - enum v4l2_field field, - unsigned int msize, - void *priv); - - void videobuf_queue_vmalloc_init(struct videobuf_queue *q, - struct videobuf_queue_ops *ops, - struct device *dev, - spinlock_t *irqlock, - enum v4l2_buf_type type, - enum v4l2_field field, - unsigned int msize, - void *priv); - - void videobuf_queue_dma_contig_init(struct videobuf_queue *q, - struct videobuf_queue_ops *ops, - struct device *dev, - spinlock_t *irqlock, - enum v4l2_buf_type type, - enum v4l2_field field, - unsigned int msize, - void *priv); - -In each case, the parameters are the same: q is the queue structure for the -device, ops is the set of callbacks as described above, dev is the device -structure for this video device, irqlock is an interrupt-safe spinlock to -protect access to the data structures, type is the buffer type used by the -device (cameras will use V4L2_BUF_TYPE_VIDEO_CAPTURE, for example), field -describes which field is being captured (often V4L2_FIELD_NONE for -progressive devices), msize is the size of any containing structure used -around struct videobuf_buffer, and priv is a private data pointer which -shows up in the priv_data field of struct videobuf_queue. Note that these -are void functions which, evidently, are immune to failure. - -V4L2 capture drivers can be written to support either of two APIs: the -read() system call and the rather more complicated streaming mechanism. As -a general rule, it is necessary to support both to ensure that all -applications have a chance of working with the device. Videobuf makes it -easy to do that with the same code. To implement read(), the driver need -only make a call to one of: - -.. code-block:: none - - ssize_t videobuf_read_one(struct videobuf_queue *q, - char __user *data, size_t count, - loff_t *ppos, int nonblocking); - - ssize_t videobuf_read_stream(struct videobuf_queue *q, - char __user *data, size_t count, - loff_t *ppos, int vbihack, int nonblocking); - -Either one of these functions will read frame data into data, returning the -amount actually read; the difference is that videobuf_read_one() will only -read a single frame, while videobuf_read_stream() will read multiple frames -if they are needed to satisfy the count requested by the application. A -typical driver read() implementation will start the capture engine, call -one of the above functions, then stop the engine before returning (though a -smarter implementation might leave the engine running for a little while in -anticipation of another read() call happening in the near future). - -The poll() function can usually be implemented with a direct call to: - -.. code-block:: none - - unsigned int videobuf_poll_stream(struct file *file, - struct videobuf_queue *q, - poll_table *wait); - -Note that the actual wait queue eventually used will be the one associated -with the first available buffer. - -When streaming I/O is done to kernel-space buffers, the driver must support -the mmap() system call to enable user space to access the data. In many -V4L2 drivers, the often-complex mmap() implementation simplifies to a -single call to: - -.. code-block:: none - - int videobuf_mmap_mapper(struct videobuf_queue *q, - struct vm_area_struct *vma); - -Everything else is handled by the videobuf code. - -The release() function requires two separate videobuf calls: - -.. code-block:: none - - void videobuf_stop(struct videobuf_queue *q); - int videobuf_mmap_free(struct videobuf_queue *q); - -The call to videobuf_stop() terminates any I/O in progress - though it is -still up to the driver to stop the capture engine. The call to -videobuf_mmap_free() will ensure that all buffers have been unmapped; if -so, they will all be passed to the buf_release() callback. If buffers -remain mapped, videobuf_mmap_free() returns an error code instead. The -purpose is clearly to cause the closing of the file descriptor to fail if -buffers are still mapped, but every driver in the 2.6.32 kernel cheerfully -ignores its return value. - -ioctl() operations ------------------- - -The V4L2 API includes a very long list of driver callbacks to respond to -the many ioctl() commands made available to user space. A number of these -- those associated with streaming I/O - turn almost directly into videobuf -calls. The relevant helper functions are: - -.. code-block:: none - - int videobuf_reqbufs(struct videobuf_queue *q, - struct v4l2_requestbuffers *req); - int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b); - int videobuf_qbuf(struct videobuf_queue *q, struct v4l2_buffer *b); - int videobuf_dqbuf(struct videobuf_queue *q, struct v4l2_buffer *b, - int nonblocking); - int videobuf_streamon(struct videobuf_queue *q); - int videobuf_streamoff(struct videobuf_queue *q); - -So, for example, a VIDIOC_REQBUFS call turns into a call to the driver's -vidioc_reqbufs() callback which, in turn, usually only needs to locate the -proper struct videobuf_queue pointer and pass it to videobuf_reqbufs(). -These support functions can replace a great deal of buffer management -boilerplate in a lot of V4L2 drivers. - -The vidioc_streamon() and vidioc_streamoff() functions will be a bit more -complex, of course, since they will also need to deal with starting and -stopping the capture engine. - -Buffer allocation ------------------ - -Thus far, we have talked about buffers, but have not looked at how they are -allocated. The scatter/gather case is the most complex on this front. For -allocation, the driver can leave buffer allocation entirely up to the -videobuf layer; in this case, buffers will be allocated as anonymous -user-space pages and will be very scattered indeed. If the application is -using user-space buffers, no allocation is needed; the videobuf layer will -take care of calling get_user_pages() and filling in the scatterlist array. - -If the driver needs to do its own memory allocation, it should be done in -the vidioc_reqbufs() function, *after* calling videobuf_reqbufs(). The -first step is a call to: - -.. code-block:: none - - struct videobuf_dmabuf *videobuf_to_dma(struct videobuf_buffer *buf); - -The returned videobuf_dmabuf structure (defined in -<media/videobuf-dma-sg.h>) includes a couple of relevant fields: - -.. code-block:: none - - struct scatterlist *sglist; - int sglen; - -The driver must allocate an appropriately-sized scatterlist array and -populate it with pointers to the pieces of the allocated buffer; sglen -should be set to the length of the array. - -Drivers using the vmalloc() method need not (and cannot) concern themselves -with buffer allocation at all; videobuf will handle those details. The -same is normally true of contiguous-DMA drivers as well; videobuf will -allocate the buffers (with dma_alloc_coherent()) when it sees fit. That -means that these drivers may be trying to do high-order allocations at any -time, an operation which is not always guaranteed to work. Some drivers -play tricks by allocating DMA space at system boot time; videobuf does not -currently play well with those drivers. - -As of 2.6.31, contiguous-DMA drivers can work with a user-supplied buffer, -as long as that buffer is physically contiguous. Normal user-space -allocations will not meet that criterion, but buffers obtained from other -kernel drivers, or those contained within huge pages, will work with these -drivers. - -Filling the buffers -------------------- - -The final part of a videobuf implementation has no direct callback - it's -the portion of the code which actually puts frame data into the buffers, -usually in response to interrupts from the device. For all types of -drivers, this process works approximately as follows: - - - Obtain the next available buffer and make sure that somebody is actually - waiting for it. - - - Get a pointer to the memory and put video data there. - - - Mark the buffer as done and wake up the process waiting for it. - -Step (1) above is done by looking at the driver-managed list_head structure -- the one which is filled in the buf_queue() callback. Because starting -the engine and enqueueing buffers are done in separate steps, it's possible -for the engine to be running without any buffers available - in the -vmalloc() case especially. So the driver should be prepared for the list -to be empty. It is equally possible that nobody is yet interested in the -buffer; the driver should not remove it from the list or fill it until a -process is waiting on it. That test can be done by examining the buffer's -done field (a wait_queue_head_t structure) with waitqueue_active(). - -A buffer's state should be set to VIDEOBUF_ACTIVE before being mapped for -DMA; that ensures that the videobuf layer will not try to do anything with -it while the device is transferring data. - -For scatter/gather drivers, the needed memory pointers will be found in the -scatterlist structure described above. Drivers using the vmalloc() method -can get a memory pointer with: - -.. code-block:: none - - void *videobuf_to_vmalloc(struct videobuf_buffer *buf); - -For contiguous DMA drivers, the function to use is: - -.. code-block:: none - - dma_addr_t videobuf_to_dma_contig(struct videobuf_buffer *buf); - -The contiguous DMA API goes out of its way to hide the kernel-space address -of the DMA buffer from drivers. - -The final step is to set the size field of the relevant videobuf_buffer -structure to the actual size of the captured image, set state to -VIDEOBUF_DONE, then call wake_up() on the done queue. At this point, the -buffer is owned by the videobuf layer and the driver should not touch it -again. - -Developers who are interested in more information can go into the relevant -header files; there are a few low-level functions declared there which have -not been talked about here. Note also that all of these calls are exported -GPL-only, so they will not be available to non-GPL kernel modules. diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst index 2d6b99766ee8..78dded03e5d8 100644 --- a/Documentation/driver-api/pps.rst +++ b/Documentation/driver-api/pps.rst @@ -200,11 +200,17 @@ Generators Sometimes one needs to be able not only to catch PPS signals but to produce them also. For example, running a distributed simulation, which requires -computers' clock to be synchronized very tightly. One way to do this is to -invent some complicated hardware solutions but it may be neither necessary -nor affordable. The cheap way is to load a PPS generator on one of the -computers (master) and PPS clients on others (slaves), and use very simple -cables to deliver signals using parallel ports, for example. +computers' clock to be synchronized very tightly. + + +Parallel port generator +------------------------ + +One way to do this is to invent some complicated hardware solutions but it +may be neither necessary nor affordable. The cheap way is to load a PPS +generator on one of the computers (master) and PPS clients on others +(slaves), and use very simple cables to deliver signals using parallel +ports, for example. Parallel port cable pinout:: diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst index 3fdc95f7a1d1..bb264490a87a 100644 --- a/Documentation/driver-api/pwm.rst +++ b/Documentation/driver-api/pwm.rst @@ -111,13 +111,13 @@ channel that was exported. The following properties will then be available: duty_cycle The active time of the PWM signal (read/write). - Value is in nanoseconds and must be less than the period. + Value is in nanoseconds and must be less than or equal to the period. polarity Changes the polarity of the PWM signal (read/write). Writes to this property only work if the PWM chip supports changing - the polarity. The polarity can only be changed if the PWM is not - enabled. Value is the string "normal" or "inversed". + the polarity. + Value is the string "normal" or "inversed". enable Enable/disable the PWM signal (read/write). diff --git a/Documentation/driver-api/thermal/intel_dptf.rst b/Documentation/driver-api/thermal/intel_dptf.rst index 9ab4316322a1..8fb8c5b2d685 100644 --- a/Documentation/driver-api/thermal/intel_dptf.rst +++ b/Documentation/driver-api/thermal/intel_dptf.rst @@ -164,6 +164,16 @@ ABI. ``power_limit_1_tmax_us`` (RO) Maximum powercap sysfs constraint_1_time_window_us for Intel RAPL +``power_floor_status`` (RO) + When set to 1, the power floor of the system in the current + configuration has been reached. It needs to be reconfigured to allow + power to be reduced any further. + +``power_floor_enable`` (RW) + When set to 1, enable reading and notification of the power floor + status. Notifications are triggered for the power_floor_status + attribute value changes. + :file:`/sys/bus/pci/devices/0000\:00\:04.0/` ``tcc_offset_degree_celsius`` (RW) @@ -315,3 +325,57 @@ DPTF Fan Control ---------------------------------------- Refer to Documentation/admin-guide/acpi/fan_performance_states.rst + +Workload Type Hints +---------------------------------------- + +The firmware in Meteor Lake processor generation is capable of identifying +workload type and passing hints regarding it to the OS. A special sysfs +interface is provided to allow user space to obtain workload type hints from +the firmware and control the rate at which they are provided. + +User space can poll attribute "workload_type_index" for the current hint or +can receive a notification whenever the value of this attribute is updated. + +file:`/sys/bus/pci/devices/0000:00:04.0/workload_hint/` +Segment 0, bus 0, device 4, function 0 is reserved for the processor thermal +device on all Intel client processors. So, the above path doesn't change +based on the processor generation. + +``workload_hint_enable`` (RW) + Enable firmware to send workload type hints to user space. + +``notification_delay_ms`` (RW) + Minimum delay in milliseconds before firmware will notify OS. This is + for the rate control of notifications. This delay is between changing + the workload type prediction in the firmware and notifying the OS about + the change. The default delay is 1024 ms. The delay of 0 is invalid. + The delay is rounded up to the nearest power of 2 to simplify firmware + programming of the delay value. The read of notification_delay_ms + attribute shows the effective value used. + +``workload_type_index`` (RO) + Predicted workload type index. User space can get notification of + change via existing sysfs attribute change notification mechanism. + + The supported index values and their meaning for the Meteor Lake + processor generation are as follows: + + 0 - Idle: System performs no tasks, power and idle residency are + consistently low for long periods of time. + + 1 – Battery Life: Power is relatively low, but the processor may + still be actively performing a task, such as video playback for + a long period of time. + + 2 – Sustained: Power level that is relatively high for a long period + of time, with very few to no periods of idleness, which will + eventually exhaust RAPL Power Limit 1 and 2. + + 3 – Bursty: Consumes a relatively constant average amount of power, but + periods of relative idleness are interrupted by bursts of + activity. The bursts are relatively short and the periods of + relative idleness between them typically prevent RAPL Power + Limit 1 from being exhausted. + + 4 – Unknown: Can't classify. diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst index 2d32606a4278..b490da11f257 100644 --- a/Documentation/driver-api/tty/index.rst +++ b/Documentation/driver-api/tty/index.rst @@ -36,6 +36,7 @@ In-detail description of the named TTY structures is in separate documents: tty_struct tty_ldisc tty_buffer + tty_ioctl tty_internals Writing TTY Driver diff --git a/Documentation/driver-api/tty/tty_ioctl.rst b/Documentation/driver-api/tty/tty_ioctl.rst new file mode 100644 index 000000000000..3ff1ac5e07f1 --- /dev/null +++ b/Documentation/driver-api/tty/tty_ioctl.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +TTY IOCTL Helpers +================= + +.. kernel-doc:: drivers/tty/tty_ioctl.c + +.. kernel-doc:: include/linux/tty.h + :identifiers: tty_get_baud_rate diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst index d32c27e11b90..02f6825ff830 100644 --- a/Documentation/driver-api/usb/dma.rst +++ b/Documentation/driver-api/usb/dma.rst @@ -93,44 +93,18 @@ DMA address space of the device. However, most buffers passed to your driver can safely be used with such DMA mapping. (See the first section of Documentation/core-api/dma-api-howto.rst, titled "What memory is DMA-able?") -- When you're using scatterlists, you can map everything at once. On some - systems, this kicks in an IOMMU and turns the scatterlists into single - DMA transactions:: +- When you have the scatterlists which have been mapped for the USB controller, + you could use the new ``usb_sg_*()`` calls, which would turn scatterlist + into URBs:: - int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int nents); + int usb_sg_init(struct usb_sg_request *io, struct usb_device *dev, + unsigned pipe, unsigned period, struct scatterlist *sg, + int nents, size_t length, gfp_t mem_flags); - void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int n_hw_ents); + void usb_sg_wait(struct usb_sg_request *io); - void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe, - struct scatterlist *sg, int n_hw_ents); + void usb_sg_cancel(struct usb_sg_request *io); - It's probably easier to use the new ``usb_sg_*()`` calls, which do the DMA - mapping and apply other tweaks to make scatterlist i/o be fast. - -- Some drivers may prefer to work with the model that they're mapping large - buffers, synchronizing their safe re-use. (If there's no re-use, then let - usbcore do the map/unmap.) Large periodic transfers make good examples - here, since it's cheaper to just synchronize the buffer than to unmap it - each time an urb completes and then re-map it on during resubmission. - - These calls all work with initialized urbs: ``urb->dev``, ``urb->pipe``, - ``urb->transfer_buffer``, and ``urb->transfer_buffer_length`` must all be - valid when these calls are used (``urb->setup_packet`` must be valid too - if urb is a control request):: - - struct urb *usb_buffer_map (struct urb *urb); - - void usb_buffer_dmasync (struct urb *urb); - - void usb_buffer_unmap (struct urb *urb); - - The calls manage ``urb->transfer_dma`` for you, and set - ``URB_NO_TRANSFER_DMA_MAP`` so that usbcore won't map or unmap the buffer. - They cannot be used for setup_packet buffers in control requests. - -Note that several of those interfaces are currently commented out, since -they don't have current users. See the source code. Other than the dmasync -calls (where the underlying DMA primitives have changed), most of them can -easily be commented back in if you want to use them. + When the USB controller doesn't support DMA, the ``usb_sg_init()`` would try + to submit URBs in PIO way as long as the page in scatterlists is not in the + Highmem, which could be very rare in modern architectures. diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt b/Documentation/features/core/cBPF-JIT/arch-support.txt index 0a1f5bb7eeb9..937840080de7 100644 --- a/Documentation/features/core/cBPF-JIT/arch-support.txt +++ b/Documentation/features/core/cBPF-JIT/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index 6c0f3d759e6a..7434b43c2ff8 100644 --- a/Documentation/features/core/eBPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt index 0b94099cf6ac..0735cb5367b4 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index 94d9dece580f..ccada815569f 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/thread-info-in-task/arch-support.txt b/Documentation/features/core/thread-info-in-task/arch-support.txt index 97c65ed2ac23..2afeb6bf6e64 100644 --- a/Documentation/features/core/thread-info-in-task/arch-support.txt +++ b/Documentation/features/core/thread-info-in-task/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index aed5679da651..a72330e25542 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index c4581c2edb28..39c6e78c0cbe 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt index 9ec5d13f4939..bbf029f095cb 100644 --- a/Documentation/features/debug/debug-vm-pgtable/arch-support.txt +++ b/Documentation/features/debug/debug-vm-pgtable/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt index dc4014f7e1f8..63494bddc263 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/debug/kcov/arch-support.txt b/Documentation/features/debug/kcov/arch-support.txt index de84cefbcdd3..4449e1f55cd8 100644 --- a/Documentation/features/debug/kcov/arch-support.txt +++ b/Documentation/features/debug/kcov/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 5e91ec78c80b..f287f16ce0ec 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | ok | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/debug/kmemleak/arch-support.txt b/Documentation/features/debug/kmemleak/arch-support.txt index 4e205ef70363..f45149cfa313 100644 --- a/Documentation/features/debug/kmemleak/arch-support.txt +++ b/Documentation/features/debug/kmemleak/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index 38a0a54b79f5..02febc883588 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index aad83b57587a..1ea27aedd098 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index 61380010a4a7..022be42e64f9 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index 83a4639a5c0a..92f5d0f444fa 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt index 4c64c5d596f7..de8f43f2e5d6 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index 24c8423b0abc..0c698003ce9c 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt index 059110a5fa6e..3e431767581d 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index bfe0921a3853..3c6ce35d704f 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt index 68329e96dffa..2c3a4b91f16d 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt index a36e231670d7..b6b00469f7d0 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index 5deb845477e4..b286a5fff283 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index 2d3961bfef5d..22f2990392ff 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 641a7d2ff2a3..713a69fcd697 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt index 33866eb242c1..09431518b0e8 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt index c8e4c7c65012..f9db4dd8ef79 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt index 23260ca44946..d96b778b87ed 100644 --- a/Documentation/features/sched/membarrier-sync-core/arch-support.txt +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -35,7 +35,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index 532cc67cdf92..984601c7c479 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | .. | | hexagon: | .. | - | ia64: | TODO | | loongarch: | ok | | m68k: | .. | | microblaze: | .. | diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index 3a7237b989cd..13feb679649e 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | ok | | microblaze: | TODO | diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt index 9bffac80019e..ccba965e8d07 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 625160048f68..4d4bfac52970 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | ok | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | ok | diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index 72bc5bad0348..891be9f61903 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index ceb036610d09..3d10075a8a8a 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | .. | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt index c063dffd5261..21f11d47ef72 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | ok | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index 47909c3dd602..57406c0d5353 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -13,7 +13,6 @@ | arm64: | ok | | csky: | ok | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt index 5acd64b97dba..5a7508b8c967 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | TODO | | csky: | TODO | | hexagon: | TODO | - | ia64: | ok | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index 9dd7d75d0465..b4a5ce16940d 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | .. | | hexagon: | .. | - | ia64: | TODO | | loongarch: | ok | | m68k: | .. | | microblaze: | .. | diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 76208db88f3b..8fd22073a847 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | .. | | microblaze: | .. | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index 34647d9bdca4..2d6de7b04538 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | TODO | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index a24149e59d73..1638c2cb17f1 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index d2b22a06945e..3f777f8b67d5 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -12,7 +12,6 @@ | arm64: | ok | | csky: | TODO | | hexagon: | TODO | - | ia64: | TODO | | loongarch: | ok | | m68k: | TODO | | microblaze: | TODO | diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index f200d7874495..57c6ae23b3fc 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -199,7 +199,7 @@ may not. All metadatas can be now observed in two different spaces (views): | | |__________________| 64 bytes - Xattrs, extents, data inline are followed by the corresponding inode with + Xattrs, extents, data inline are placed after the corresponding inode with proper alignment, and they could be optional for different data mappings. _currently_ total 5 data layouts are supported: diff --git a/Documentation/filesystems/files.rst b/Documentation/filesystems/files.rst index bcf84459917f..9e38e4c221ca 100644 --- a/Documentation/filesystems/files.rst +++ b/Documentation/filesystems/files.rst @@ -62,7 +62,7 @@ the fdtable structure - be held. 4. To look up the file structure given an fd, a reader - must use either lookup_fd_rcu() or files_lookup_fd_rcu() APIs. These + must use either lookup_fdget_rcu() or files_lookup_fdget_rcu() APIs. These take care of barrier requirements due to lock-free lookup. An example:: @@ -70,43 +70,22 @@ the fdtable structure - struct file *file; rcu_read_lock(); - file = lookup_fd_rcu(fd); - if (file) { - ... - } - .... + file = lookup_fdget_rcu(fd); rcu_read_unlock(); - -5. Handling of the file structures is special. Since the look-up - of the fd (fget()/fget_light()) are lock-free, it is possible - that look-up may race with the last put() operation on the - file structure. This is avoided using atomic_long_inc_not_zero() - on ->f_count:: - - rcu_read_lock(); - file = files_lookup_fd_rcu(files, fd); if (file) { - if (atomic_long_inc_not_zero(&file->f_count)) - *fput_needed = 1; - else - /* Didn't get the reference, someone's freed */ - file = NULL; + ... + fput(file); } - rcu_read_unlock(); .... - return file; - - atomic_long_inc_not_zero() detects if refcounts is already zero or - goes to zero during increment. If it does, we fail - fget()/fget_light(). -6. Since both fdtable and file structures can be looked up +5. Since both fdtable and file structures can be looked up lock-free, they must be installed using rcu_assign_pointer() API. If they are looked up lock-free, rcu_dereference() must be used. However it is advisable to use files_fdtable() - and lookup_fd_rcu()/files_lookup_fd_rcu() which take care of these issues. + and lookup_fdget_rcu()/files_lookup_fdget_rcu() which take care of these + issues. -7. While updating, the fdtable pointer must be looked up while +6. While updating, the fdtable pointer must be looked up while holding files->file_lock. If ->file_lock is dropped, then another thread expand the files thereby creating a new fdtable and making the earlier fdtable pointer stale. @@ -126,3 +105,19 @@ the fdtable structure - Since locate_fd() can drop ->file_lock (and reacquire ->file_lock), the fdtable pointer (fdt) must be loaded after locate_fd(). +On newer kernels rcu based file lookup has been switched to rely on +SLAB_TYPESAFE_BY_RCU instead of call_rcu(). It isn't sufficient anymore +to just acquire a reference to the file in question under rcu using +atomic_long_inc_not_zero() since the file might have already been +recycled and someone else might have bumped the reference. In other +words, callers might see reference count bumps from newer users. For +this is reason it is necessary to verify that the pointer is the same +before and after the reference count increment. This pattern can be seen +in get_file_rcu() and __files_get_rcu(). + +In addition, it isn't possible to access or check fields in struct file +without first aqcuiring a reference on it under rcu lookup. Not doing +that was always very dodgy and it was only usable for non-pointer data +in struct file. With SLAB_TYPESAFE_BY_RCU it is necessary that callers +either first acquire a reference or they must hold the files_lock of the +fdtable. diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index a624e92f2687..1b84f818e574 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -261,9 +261,9 @@ DIRECT_KEY policies The Adiantum encryption mode (see `Encryption modes and usage`_) is suitable for both contents and filenames encryption, and it accepts -long IVs --- long enough to hold both an 8-byte logical block number -and a 16-byte per-file nonce. Also, the overhead of each Adiantum key -is greater than that of an AES-256-XTS key. +long IVs --- long enough to hold both an 8-byte data unit index and a +16-byte per-file nonce. Also, the overhead of each Adiantum key is +greater than that of an AES-256-XTS key. Therefore, to improve performance and save memory, for Adiantum a "direct key" configuration is supported. When the user has enabled @@ -300,8 +300,8 @@ IV_INO_LBLK_32 policies IV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the -SipHash key is derived from the master key) and added to the file -logical block number mod 2^32 to produce a 32-bit IV. +SipHash key is derived from the master key) and added to the file data +unit index mod 2^32 to produce a 32-bit IV. This format is optimized for use with inline encryption hardware compliant with the eMMC v5.2 standard, which supports only 32 IV bits @@ -451,31 +451,62 @@ acceleration is recommended: Contents encryption ------------------- -For file contents, each filesystem block is encrypted independently. -Starting from Linux kernel 5.5, encryption of filesystems with block -size less than system's page size is supported. - -Each block's IV is set to the logical block number within the file as -a little endian number, except that: - -- With CBC mode encryption, ESSIV is also used. Specifically, each IV - is encrypted with AES-256 where the AES-256 key is the SHA-256 hash - of the file's data encryption key. - -- With `DIRECT_KEY policies`_, the file's nonce is appended to the IV. - Currently this is only allowed with the Adiantum encryption mode. - -- With `IV_INO_LBLK_64 policies`_, the logical block number is limited - to 32 bits and is placed in bits 0-31 of the IV. The inode number - (which is also limited to 32 bits) is placed in bits 32-63. - -- With `IV_INO_LBLK_32 policies`_, the logical block number is limited - to 32 bits and is placed in bits 0-31 of the IV. The inode number - is then hashed and added mod 2^32. - -Note that because file logical block numbers are included in the IVs, -filesystems must enforce that blocks are never shifted around within -encrypted files, e.g. via "collapse range" or "insert range". +For contents encryption, each file's contents is divided into "data +units". Each data unit is encrypted independently. The IV for each +data unit incorporates the zero-based index of the data unit within +the file. This ensures that each data unit within a file is encrypted +differently, which is essential to prevent leaking information. + +Note: the encryption depending on the offset into the file means that +operations like "collapse range" and "insert range" that rearrange the +extent mapping of files are not supported on encrypted files. + +There are two cases for the sizes of the data units: + +* Fixed-size data units. This is how all filesystems other than UBIFS + work. A file's data units are all the same size; the last data unit + is zero-padded if needed. By default, the data unit size is equal + to the filesystem block size. On some filesystems, users can select + a sub-block data unit size via the ``log2_data_unit_size`` field of + the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_. + +* Variable-size data units. This is what UBIFS does. Each "UBIFS + data node" is treated as a crypto data unit. Each contains variable + length, possibly compressed data, zero-padded to the next 16-byte + boundary. Users cannot select a sub-block data unit size on UBIFS. + +In the case of compression + encryption, the compressed data is +encrypted. UBIFS compression works as described above. f2fs +compression works a bit differently; it compresses a number of +filesystem blocks into a smaller number of filesystem blocks. +Therefore a f2fs-compressed file still uses fixed-size data units, and +it is encrypted in a similar way to a file containing holes. + +As mentioned in `Key hierarchy`_, the default encryption setting uses +per-file keys. In this case, the IV for each data unit is simply the +index of the data unit in the file. However, users can select an +encryption setting that does not use per-file keys. For these, some +kind of file identifier is incorporated into the IVs as follows: + +- With `DIRECT_KEY policies`_, the data unit index is placed in bits + 0-63 of the IV, and the file's nonce is placed in bits 64-191. + +- With `IV_INO_LBLK_64 policies`_, the data unit index is placed in + bits 0-31 of the IV, and the file's inode number is placed in bits + 32-63. This setting is only allowed when data unit indices and + inode numbers fit in 32 bits. + +- With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed + and added to the data unit index. The resulting value is truncated + to 32 bits and placed in bits 0-31 of the IV. This setting is only + allowed when data unit indices and inode numbers fit in 32 bits. + +The byte order of the IV is always little endian. + +If the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an +ESSIV layer is automatically included. In this case, before the IV is +passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256 +key is the SHA-256 hash of the file's contents encryption key. Filenames encryption -------------------- @@ -544,7 +575,8 @@ follows:: __u8 contents_encryption_mode; __u8 filenames_encryption_mode; __u8 flags; - __u8 __reserved[4]; + __u8 log2_data_unit_size; + __u8 __reserved[3]; __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; }; @@ -586,6 +618,29 @@ This structure must be initialized as follows: The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are mutually exclusive. +- ``log2_data_unit_size`` is the log2 of the data unit size in bytes, + or 0 to select the default data unit size. The data unit size is + the granularity of file contents encryption. For example, setting + ``log2_data_unit_size`` to 12 causes file contents be passed to the + underlying encryption algorithm (such as AES-256-XTS) in 4096-byte + data units, each with its own IV. + + Not all filesystems support setting ``log2_data_unit_size``. ext4 + and f2fs support it since Linux v6.7. On filesystems that support + it, the supported nonzero values are 9 through the log2 of the + filesystem block size, inclusively. The default value of 0 selects + the filesystem block size. + + The main use case for ``log2_data_unit_size`` is for selecting a + data unit size smaller than the filesystem block size for + compatibility with inline encryption hardware that only supports + smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be + useful for checking which data unit sizes are supported by a + particular system's inline encryption hardware. + + Leave this field zeroed unless you are certain you need it. Using + an unnecessarily small data unit size reduces performance. + - For v2 encryption policies, ``__reserved`` must be zeroed. - For v1 encryption policies, ``master_key_descriptor`` specifies how @@ -1079,8 +1134,8 @@ The caller must zero all input fields, then fill in ``key_spec``: On success, 0 is returned and the kernel fills in the output fields: - ``status`` indicates whether the key is absent, present, or - incompletely removed. Incompletely removed means that the master - secret has been removed, but some files are still in use; i.e., + incompletely removed. Incompletely removed means that removal has + been initiated, but some files are still in use; i.e., `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY. diff --git a/Documentation/filesystems/nfs/exporting.rst b/Documentation/filesystems/nfs/exporting.rst index 4b30daee399a..f04ce1215a03 100644 --- a/Documentation/filesystems/nfs/exporting.rst +++ b/Documentation/filesystems/nfs/exporting.rst @@ -122,12 +122,9 @@ are exportable by setting the s_export_op field in the struct super_block. This field must point to a "struct export_operations" struct which has the following members: - encode_fh (optional) + encode_fh (mandatory) Takes a dentry and creates a filehandle fragment which may later be used - to find or create a dentry for the same object. The default - implementation creates a filehandle fragment that encodes a 32bit inode - and generation number for the inode encoded, and if necessary the - same information for the parent. + to find or create a dentry for the same object. fh_to_dentry (mandatory) Given a filehandle fragment, this should find the implied object and @@ -241,3 +238,10 @@ following flags are defined: all of an inode's dirty data on last close. Exports that behave this way should set EXPORT_OP_FLUSH_ON_CLOSE so that NFSD knows to skip waiting for writeback when closing such files. + + EXPORT_OP_ASYNC_LOCK - Indicates a capable filesystem to do async lock + requests from lockd. Only set EXPORT_OP_ASYNC_LOCK if the filesystem has + it's own ->lock() functionality as core posix_lock_file() implementation + has no async lock request handling yet. For more information about how to + indicate an async lock request from a ->lock() file_operations struct, see + fs/locks.c and comment for the function vfs_lock_file(). diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 5b93268e400f..0407f361f32a 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -344,10 +344,11 @@ escaping the colons with a single backslash. For example: mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged -Since kernel version v6.5, directory names containing colons can also -be provided as lower layer using the fsconfig syscall from new mount api: +Since kernel version v6.8, directory names containing colons can also +be configured as lower layer using the "lowerdir+" mount options and the +fsconfig syscall from new mount api. For example: - fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir", "/a:lower::dir", 0); + fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/a:lower::dir", 0); In the latter case, colons in lower layer directory names will be escaped as an octal characters (\072) when displayed in /proc/self/mountinfo. @@ -416,6 +417,16 @@ Only the data of the files in the "data-only" lower layers may be visible when a "metacopy" file in one of the lower layers above it, has a "redirect" to the absolute path of the "lower data" file in the "data-only" lower layer. +Since kernel version v6.8, "data-only" lower layers can also be added using +the "datadir+" mount options and the fsconfig syscall from new mount api. +For example: + + fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l1", 0); + fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l2", 0); + fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l3", 0); + fsconfig(fs_fd, FSCONFIG_SET_STRING, "datadir+", "/do1", 0); + fsconfig(fs_fd, FSCONFIG_SET_STRING, "datadir+", "/do2", 0); + fs-verity support ---------------------- @@ -504,6 +515,29 @@ directory tree on the same or different underlying filesystem, and even to a different machine. With the "inodes index" feature, trying to mount the copied layers will fail the verification of the lower root file handle. +Nesting overlayfs mounts +------------------------ + +It is possible to use a lower directory that is stored on an overlayfs +mount. For regular files this does not need any special care. However, files +that have overlayfs attributes, such as whiteouts or "overlay.*" xattrs will be +interpreted by the underlying overlayfs mount and stripped out. In order to +allow the second overlayfs mount to see the attributes they must be escaped. + +Overlayfs specific xattrs are escaped by using a special prefix of +"overlay.overlay.". So, a file with a "trusted.overlay.overlay.metacopy" xattr +in the lower dir will be exposed as a regular file with a +"trusted.overlay.metacopy" xattr in the overlayfs mount. This can be nested by +repeating the prefix multiple time, as each instance only removes one prefix. + +A lower dir with a regular whiteout will always be handled by the overlayfs +mount, so to support storing an effective whiteout file in an overlayfs mount an +alternative form of whiteout is supported. This form is a regular, zero-size +file with the "overlay.whiteout" xattr set, inside a directory with the +"overlay.whiteouts" xattr set. Such whiteouts are never created by overlayfs, +but can be used by userspace tools (like containers) that generate lower layers. +These alternative whiteouts can be escaped using the standard xattr escape +mechanism in order to properly nest to any depth. Non-standard behavior --------------------- diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 4d05b9862451..878e72b2f8b7 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -1045,3 +1045,19 @@ filesystem type is now moved to a later point when the devices are closed: As this is a VFS level change it has no practical consequences for filesystems other than that all of them must use one of the provided kill_litter_super(), kill_anon_super(), or kill_block_super() helpers. + +--- + +**mandatory** + +Lock ordering has been changed so that s_umount ranks above open_mutex again. +All places where s_umount was taken under open_mutex have been fixed up. + +--- + +**mandatory** + +export_operations ->encode_fh() no longer has a default implementation to +encode FILEID_INO32_GEN* file handles. +Filesystems that used the default implementation may use the generic helper +generic_encode_ino32_fh() explicitly. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 2b59cff8be17..49ef12df631b 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -689,9 +689,15 @@ files are there, and which are missing. File Content ============ =============================================================== apm Advanced power management info + bootconfig Kernel command line obtained from boot config, + and, if there were kernel parameters from the + boot loader, a "# Parameters from bootloader:" + line followed by a line containing those + parameters prefixed by "# ". (5.5) buddyinfo Kernel memory allocator information (see text) (2.5) bus Directory containing bus specific information - cmdline Kernel command line + cmdline Kernel command line, both from bootloader and embedded + in the kernel image cpuinfo Info about the CPU devices Available devices (block and character) dma Used DMS channels diff --git a/Documentation/filesystems/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs-online-fsck-design.rst index 1625d1131093..a0678101a7d0 100644 --- a/Documentation/filesystems/xfs-online-fsck-design.rst +++ b/Documentation/filesystems/xfs-online-fsck-design.rst @@ -1585,7 +1585,7 @@ The transaction sequence looks like this: 2. The second transaction contains a physical update to the free space btrees of AG 3 to release the former BMBT block and a second physical update to the free space btrees of AG 7 to release the unmapped file space. - Observe that the the physical updates are resequenced in the correct order + Observe that the physical updates are resequenced in the correct order when possible. Attached to the transaction is a an extent free done (EFD) log item. The EFD contains a pointer to the EFI logged in transaction #1 so that log diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 56d9913a3370..d79f69390991 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -64,6 +64,49 @@ If the driver needs to perform more complex initialization like getting and configuring GPIOs it can get its ACPI handle and extract this information from ACPI tables. +ACPI device objects +=================== + +Generally speaking, there are two categories of devices in a system in which +ACPI is used as an interface between the platform firmware and the OS: Devices +that can be discovered and enumerated natively, through a protocol defined for +the specific bus that they are on (for example, configuration space in PCI), +without the platform firmware assistance, and devices that need to be described +by the platform firmware so that they can be discovered. Still, for any device +known to the platform firmware, regardless of which category it falls into, +there can be a corresponding ACPI device object in the ACPI Namespace in which +case the Linux kernel will create a struct acpi_device object based on it for +that device. + +Those struct acpi_device objects are never used for binding drivers to natively +discoverable devices, because they are represented by other types of device +objects (for example, struct pci_dev for PCI devices) that are bound to by +device drivers (the corresponding struct acpi_device object is then used as +an additional source of information on the configuration of the given device). +Moreover, the core ACPI device enumeration code creates struct platform_device +objects for the majority of devices that are discovered and enumerated with the +help of the platform firmware and those platform device objects can be bound to +by platform drivers in direct analogy with the natively enumerable devices +case. Therefore it is logically inconsistent and so generally invalid to bind +drivers to struct acpi_device objects, including drivers for devices that are +discovered with the help of the platform firmware. + +Historically, ACPI drivers that bound directly to struct acpi_device objects +were implemented for some devices enumerated with the help of the platform +firmware, but this is not recommended for any new drivers. As explained above, +platform device objects are created for those devices as a rule (with a few +exceptions that are not relevant here) and so platform drivers should be used +for handling them, even though the corresponding ACPI device objects are the +only source of device configuration information in that case. + +For every device having a corresponding struct acpi_device object, the pointer +to it is returned by the ACPI_COMPANION() macro, so it is always possible to +get to the device configuration information stored in the ACPI device object +this way. Accordingly, struct acpi_device can be regarded as a part of the +interface between the kernel and the ACPI Namespace, whereas device objects of +other types (for example, struct pci_dev or struct platform_device) are used +for interacting with the rest of the system. + DMA support =========== diff --git a/Documentation/hwmon/adt7475.rst b/Documentation/hwmon/adt7475.rst index ef3ea1ea9bc1..f90f769d82d6 100644 --- a/Documentation/hwmon/adt7475.rst +++ b/Documentation/hwmon/adt7475.rst @@ -90,7 +90,7 @@ ADT7476: ADT7490: * 6 voltage inputs - * 1 Imon input (not implemented) + * 1 Imon input * PECI support (not implemented) * 2 GPIO pins (not implemented) * system acoustics optimizations (not implemented) @@ -107,6 +107,7 @@ in2 VCC (4) VCC (4) VCC (4) VCC (3) in3 5VIN (20) 5VIN (20) in4 12VIN (21) 12VIN (21) in5 VTT (8) +in6 Imon (19) ==== =========== =========== ========= ========== Special Features diff --git a/Documentation/hwmon/aquacomputer_d5next.rst b/Documentation/hwmon/aquacomputer_d5next.rst index 94dc2d93d180..cb073c79479c 100644 --- a/Documentation/hwmon/aquacomputer_d5next.rst +++ b/Documentation/hwmon/aquacomputer_d5next.rst @@ -16,6 +16,8 @@ Supported devices: * Aquacomputer Aquastream XT watercooling pump * Aquacomputer Aquastream Ultimate watercooling pump * Aquacomputer Poweradjust 3 fan controller +* Aquacomputer High Flow USB flow meter +* Aquacomputer MPS Flow devices Author: Aleksa Savic @@ -73,6 +75,11 @@ It also exposes pressure and flow speed readings. The Poweradjust 3 controller exposes a single external temperature sensor. +The High Flow USB exposes an internal and external temperature sensor, and a flow meter. + +The MPS Flow devices expose the same entries as the High Flow USB because they have +the same USB product ID and report sensors equivalently. + Depending on the device, not all sysfs and debugfs entries will be available. Writing to virtual temperature sensors is not currently supported. diff --git a/Documentation/hwmon/asus_ec_sensors.rst b/Documentation/hwmon/asus_ec_sensors.rst index 7e3cd5b6686f..0bf99ba406dd 100644 --- a/Documentation/hwmon/asus_ec_sensors.rst +++ b/Documentation/hwmon/asus_ec_sensors.rst @@ -15,6 +15,7 @@ Supported boards: * ROG CROSSHAIR VIII HERO * ROG CROSSHAIR VIII IMPACT * ROG CROSSHAIR X670E HERO + * ROG CROSSHAIR X670E GENE * ROG MAXIMUS XI HERO * ROG MAXIMUS XI HERO (WI-FI) * ROG STRIX B550-E GAMING diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 88dadea85cfc..72f4e6065bae 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -121,6 +121,7 @@ Hardware Monitoring Kernel Drivers ltc2947 ltc2978 ltc2990 + ltc2991 ltc3815 ltc4151 ltc4215 @@ -178,6 +179,7 @@ Hardware Monitoring Kernel Drivers peci-cputemp peci-dimmtemp pmbus + powerz powr1220 pxe1610 pwm-fan diff --git a/Documentation/hwmon/ltc2991.rst b/Documentation/hwmon/ltc2991.rst new file mode 100644 index 000000000000..15d8b4d7e471 --- /dev/null +++ b/Documentation/hwmon/ltc2991.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Kernel driver ltc2991 +===================== + +Supported chips: + + * Analog Devices LTC2991 + + Prefix: 'ltc2991' + + Addresses scanned: I2C 0x48 - 0x4f + + Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/2991ff.pdf + +Authors: + + - Antoniu Miclaus <antoniu.miclaus@analog.com> + + +Description +----------- + +This driver supports hardware monitoring for Analog Devices LTC2991 Octal I2C +Voltage, Current and Temperature Monitor. + +The LTC2991 is used to monitor system temperatures, voltages and currents. +Through the I2C serial interface, the eight monitors can individually measure +supply voltages and can be paired for differential measurements of current sense +resistors or temperature sensing transistors. Additional measurements include +internal temperatureand internal VCC. + + +sysfs-Interface +--------------- + +The following attributes are supported. Limits are read-only. + +=============== ================= +inX_input: voltage input +currX_input: current input +tempX_input: temperature input +=============== ================= diff --git a/Documentation/hwmon/max31827.rst b/Documentation/hwmon/max31827.rst index b0971d05b8a4..9a1055a007cf 100644 --- a/Documentation/hwmon/max31827.rst +++ b/Documentation/hwmon/max31827.rst @@ -73,8 +73,8 @@ the conversion frequency to 1 conv/s. The conversion time varies depending on the resolution. The conversion time doubles with every bit of increased resolution. For 10 bit resolution 35ms are needed, while for 12 bit resolution (default) 140ms. When chip is in shutdown mode and a read operation is -requested, one-shot is triggered, the device waits for 140 (conversion time) + 1 -(error) ms, and only after that is the temperature value register read. +requested, one-shot is triggered, the device waits for 140 (conversion time) ms, +and only after that is the temperature value register read. The LSB of the temperature values is 0.0625 degrees Celsius, but the values of the temperatures are displayed in milli-degrees. This means, that some data is diff --git a/Documentation/hwmon/nct6683.rst b/Documentation/hwmon/nct6683.rst index 2e1408d174bd..3e7f6ee779c2 100644 --- a/Documentation/hwmon/nct6683.rst +++ b/Documentation/hwmon/nct6683.rst @@ -62,5 +62,6 @@ Intel DH87RL NCT6683D EC firmware version 1.0 build 04/03/13 Intel DH87MC NCT6683D EC firmware version 1.0 build 04/03/13 Intel DB85FL NCT6683D EC firmware version 1.0 build 04/03/13 ASRock X570 NCT6683D EC firmware version 1.0 build 06/28/19 +ASRock X670E NCT6686D EC firmware version 1.0 build 05/19/22 MSI B550 NCT6687D EC firmware version 1.0 build 05/07/20 =============== =============================================== diff --git a/Documentation/hwmon/powerz.rst b/Documentation/hwmon/powerz.rst new file mode 100644 index 000000000000..317084e0b76b --- /dev/null +++ b/Documentation/hwmon/powerz.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver POWERZ +==================== + +Supported chips: + + * ChargerLAB POWER-Z KM003C + + Prefix: 'powerz' + + Addresses scanned: - + +Author: + + - Thomas Weißschuh <linux@weissschuh.net> + +Description +----------- + +This driver implements support for the ChargerLAB POWER-Z USB-C power testing +family. + +The device communicates with the custom protocol over USB. + +The channel labels exposed via hwmon match the labels used by the on-device +display and the official POWER-Z PC software. + +As current can flow in both directions through the tester the sign of the +channel "curr1_input" (label "IBUS") indicates the direction. diff --git a/Documentation/hwmon/sch5627.rst b/Documentation/hwmon/sch5627.rst index ecb4fc84d045..8639dff234fc 100644 --- a/Documentation/hwmon/sch5627.rst +++ b/Documentation/hwmon/sch5627.rst @@ -33,3 +33,13 @@ The hardware monitoring part of the SMSC SCH5627 is accessed by talking through an embedded microcontroller. An application note describing the protocol for communicating with the microcontroller is available upon request. Please mail me if you want a copy. + + +Controlling fan speed +--------------------- + +The SCH5627 allows for partially controlling the fan speed. If a temperature +channel excedes tempX_max, all fans are forced to maximum speed. The same is not +true for tempX_crit, presumably some other measures to cool down the system are +take in this case. +In which way the value of fanX_min affects the fan speed is currently unknown. diff --git a/Documentation/i2c/busses/i2c-i801.rst b/Documentation/i2c/busses/i2c-i801.rst index e76e68ccf718..10eced6c2e46 100644 --- a/Documentation/i2c/busses/i2c-i801.rst +++ b/Documentation/i2c/busses/i2c-i801.rst @@ -47,6 +47,7 @@ Supported adapters: * Intel Alder Lake (PCH) * Intel Raptor Lake (PCH) * Intel Meteor Lake (SOC and PCH) + * Intel Birch Stream (SOC) Datasheets: Publicly available at the Intel website diff --git a/Documentation/i2c/fault-codes.rst b/Documentation/i2c/fault-codes.rst index 80b14e718b52..b0864d1268bd 100644 --- a/Documentation/i2c/fault-codes.rst +++ b/Documentation/i2c/fault-codes.rst @@ -39,6 +39,10 @@ Also, codes returned by adapter probe methods follow rules which are specific to their host bus (such as PCI, or the platform bus). +EAFNOSUPPORT + Returned by I2C adapters not supporting 10 bit addresses when + they are requested to use such an address. + EAGAIN Returned by I2C adapters when they lose arbitration in master transmit mode: some other master was transmitting different diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst index bd906407e307..9c8d1d046ea5 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -243,6 +243,12 @@ The output directory is often set using "O=..." on the commandline. The value can be overridden in which case the default value is ignored. +INSTALL_DTBS_PATH +----------------- +INSTALL_DTBS_PATH specifies where to install device tree blobs for +relocations required by build roots. This is not defined in the +makefile but the argument can be passed to make if needed. + KBUILD_ABS_SRCTREE -------------------------------------------------- Kbuild uses a relative path to point to the tree when possible. For instance, diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index e67eb261c9b0..ad118b7a1806 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -53,7 +53,7 @@ knowledge about the kernel Makefiles, plus detailed knowledge about the public interface for kbuild. *Arch developers* are people who work on an entire architecture, such -as sparc or ia64. Arch developers need to know about the arch Makefile +as sparc or x86. Arch developers need to know about the arch Makefile as well as kbuild Makefiles. *Kbuild developers* are people who work on the kernel build system itself. @@ -937,6 +937,10 @@ Example:: # net/bpfilter/Makefile bpfilter_umh-userldflags += -static +To specify libraries linked to a userspace program, you can use +``<executable>-userldlibs``. The ``userldlibs`` syntax specifies libraries +linked to all userspace programs created in the current Makefile. + When linking bpfilter_umh, it will be passed the extra option -static. From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used. @@ -1623,6 +1627,13 @@ INSTALL_MOD_STRIP INSTALL_MOD_STRIP value will be used as the option(s) to the strip command. +INSTALL_DTBS_PATH + This variable specifies a prefix for relocations required by build + roots. It defines a place for installing the device tree blobs. Like + INSTALL_MOD_PATH, it isn't defined in the Makefile, but can be passed + by the user if desired. Otherwise it defaults to the kernel install + path. + Makefile language ================= diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 6b64072d4bf2..7ad4bfc2cc03 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -101,7 +101,7 @@ to do something different in the near future. ../doc-guide/maintainer-profile ../nvdimm/maintainer-entry-profile - ../riscv/patch-acceptance + ../arch/riscv/patch-acceptance ../driver-api/media/maintainer-entry-profile ../driver-api/vfio-pci-device-specific-driver-acceptance ../nvme/feature-and-quirk-policy diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 06e14efd8662..d414e145f912 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -396,6 +396,10 @@ Memory barriers come in four basic varieties: (2) Address-dependency barriers (historical). + [!] This section is marked as HISTORICAL: For more up-to-date + information, including how compiler transformations related to pointer + comparisons can sometimes cause problems, see + Documentation/RCU/rcu_dereference.rst. An address-dependency barrier is a weaker form of read barrier. In the case where two loads are performed such that the second depends on the @@ -556,6 +560,9 @@ There are certain things that the Linux kernel memory barriers do not guarantee: ADDRESS-DEPENDENCY BARRIERS (HISTORICAL) ---------------------------------------- +[!] This section is marked as HISTORICAL: For more up-to-date information, +including how compiler transformations related to pointer comparisons can +sometimes cause problems, see Documentation/RCU/rcu_dereference.rst. As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for DEC Alpha, which means that about the only people who need to pay attention diff --git a/Documentation/misc-devices/eeprom.rst b/Documentation/misc-devices/eeprom.rst deleted file mode 100644 index 008249675ccc..000000000000 --- a/Documentation/misc-devices/eeprom.rst +++ /dev/null @@ -1,107 +0,0 @@ -==================== -Kernel driver eeprom -==================== - -Supported chips: - - * Any EEPROM chip in the designated address range - - Prefix: 'eeprom' - - Addresses scanned: I2C 0x50 - 0x57 - - Datasheets: Publicly available from: - - Atmel (www.atmel.com), - Catalyst (www.catsemi.com), - Fairchild (www.fairchildsemi.com), - Microchip (www.microchip.com), - Philips (www.semiconductor.philips.com), - Rohm (www.rohm.com), - ST (www.st.com), - Xicor (www.xicor.com), - and others. - - ========= ============= ============================================ - Chip Size (bits) Address - ========= ============= ============================================ - 24C01 1K 0x50 (shadows at 0x51 - 0x57) - 24C01A 1K 0x50 - 0x57 (Typical device on DIMMs) - 24C02 2K 0x50 - 0x57 - 24C04 4K 0x50, 0x52, 0x54, 0x56 - (additional data at 0x51, 0x53, 0x55, 0x57) - 24C08 8K 0x50, 0x54 (additional data at 0x51, 0x52, - 0x53, 0x55, 0x56, 0x57) - 24C16 16K 0x50 (additional data at 0x51 - 0x57) - Sony 2K 0x57 - - Atmel 34C02B 2K 0x50 - 0x57, SW write protect at 0x30-37 - Catalyst 34FC02 2K 0x50 - 0x57, SW write protect at 0x30-37 - Catalyst 34RC02 2K 0x50 - 0x57, SW write protect at 0x30-37 - Fairchild 34W02 2K 0x50 - 0x57, SW write protect at 0x30-37 - Microchip 24AA52 2K 0x50 - 0x57, SW write protect at 0x30-37 - ST M34C02 2K 0x50 - 0x57, SW write protect at 0x30-37 - ========= ============= ============================================ - - -Authors: - - Frodo Looijaard <frodol@dds.nl>, - - Philip Edelbrock <phil@netroedge.com>, - - Jean Delvare <jdelvare@suse.de>, - - Greg Kroah-Hartman <greg@kroah.com>, - - IBM Corp. - -Description ------------ - -This is a simple EEPROM module meant to enable reading the first 256 bytes -of an EEPROM (on a SDRAM DIMM for example). However, it will access serial -EEPROMs on any I2C adapter. The supported devices are generically called -24Cxx, and are listed above; however the numbering for these -industry-standard devices may vary by manufacturer. - -This module was a programming exercise to get used to the new project -organization laid out by Frodo, but it should be at least completely -effective for decoding the contents of EEPROMs on DIMMs. - -DIMMS will typically contain a 24C01A or 24C02, or the 34C02 variants. -The other devices will not be found on a DIMM because they respond to more -than one address. - -DDC Monitors may contain any device. Often a 24C01, which responds to all 8 -addresses, is found. - -Recent Sony Vaio laptops have an EEPROM at 0x57. We couldn't get the -specification, so it is guess work and far from being complete. - -The Microchip 24AA52/24LCS52, ST M34C02, and others support an additional -software write protect register at 0x30 - 0x37 (0x20 less than the memory -location). The chip responds to "write quick" detection at this address but -does not respond to byte reads. If this register is present, the lower 128 -bytes of the memory array are not write protected. Any byte data write to -this address will write protect the memory array permanently, and the -device will no longer respond at the 0x30-37 address. The eeprom driver -does not support this register. - -Lacking functionality ---------------------- - -* Full support for larger devices (24C04, 24C08, 24C16). These are not - typically found on a PC. These devices will appear as separate devices at - multiple addresses. - -* Support for really large devices (24C32, 24C64, 24C128, 24C256, 24C512). - These devices require two-byte address fields and are not supported. - -* Enable Writing. Again, no technical reason why not, but making it easy - to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy - to disable the DIMMs (potentially preventing the computer from booting) - until the values are restored somehow. - -Use ---- - -After inserting the module (and any other required SMBus/i2c modules), you -should have some EEPROM directories in ``/sys/bus/i2c/devices/*`` of names such -as "0-0050". Inside each of these is a series of files, the eeprom file -contains the binary data from EEPROM. diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst index ecc40fbbcfb8..7de16797987a 100644 --- a/Documentation/misc-devices/index.rst +++ b/Documentation/misc-devices/index.rst @@ -17,7 +17,6 @@ fit into other categories. ad525x_dpot apds990x bh1770glc - eeprom c2port dw-xdata-pcie ibmvmc diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst index a20383d01a95..1f7e0586b5fa 100644 --- a/Documentation/mm/damon/design.rst +++ b/Documentation/mm/damon/design.rst @@ -154,6 +154,8 @@ The monitoring overhead of this mechanism will arbitrarily increase as the size of the target workload grows. +.. _damon_design_region_based_sampling: + Region Based Sampling ~~~~~~~~~~~~~~~~~~~~~ @@ -163,9 +165,10 @@ assumption (pages in a region have the same access frequencies) is kept, only one page in the region is required to be checked. Thus, for each ``sampling interval``, DAMON randomly picks one page in each region, waits for one ``sampling interval``, checks whether the page is accessed meanwhile, and -increases the access frequency of the region if so. Therefore, the monitoring -overhead is controllable by setting the number of regions. DAMON allows users -to set the minimum and the maximum number of regions for the trade-off. +increases the access frequency counter of the region if so. The counter is +called ``nr_regions`` of the region. Therefore, the monitoring overhead is +controllable by setting the number of regions. DAMON allows users to set the +minimum and the maximum number of regions for the trade-off. This scheme, however, cannot preserve the quality of the output if the assumption is not guaranteed. @@ -190,6 +193,8 @@ In this way, DAMON provides its best-effort quality and minimal overhead while keeping the bounds users set for their trade-off. +.. _damon_design_age_tracking: + Age Tracking ~~~~~~~~~~~~ @@ -254,7 +259,8 @@ works, DAMON provides a feature called Data Access Monitoring-based Operation Schemes (DAMOS). It lets users specify their desired schemes at a high level. For such specifications, DAMON starts monitoring, finds regions having the access pattern of interest, and applies the user-desired operation actions -to the regions as soon as found. +to the regions, for every user-specified time interval called +``apply_interval``. .. _damon_design_damos_action: @@ -471,3 +477,15 @@ modules for proactive reclamation and LRU lists manipulation are provided. For more detail, please read the usage documents for those (:doc:`/admin-guide/mm/damon/reclaim` and :doc:`/admin-guide/mm/damon/lru_sort`). + + +.. _damon_design_execution_model_and_data_structures: + +Execution Model and Data Structures +=================================== + +The monitoring-related information including the monitoring request +specification and DAMON-based operation schemes are stored in a data structure +called DAMON ``context``. DAMON executes each context with a kernel thread +called ``kdamond``. Multiple kdamonds could run in parallel, for different +types of monitoring. diff --git a/Documentation/mm/overcommit-accounting.rst b/Documentation/mm/overcommit-accounting.rst index a4895d6fc1c2..e2263477f6d5 100644 --- a/Documentation/mm/overcommit-accounting.rst +++ b/Documentation/mm/overcommit-accounting.rst @@ -8,8 +8,7 @@ The Linux kernel supports the following overcommit handling modes Heuristic overcommit handling. Obvious overcommits of address space are refused. Used for a typical system. It ensures a seriously wild allocation fails while allowing overcommit to - reduce swap usage. root is allowed to allocate slightly more - memory in this mode. This is the default. + reduce swap usage. This is the default. 1 Always overcommit. Appropriate for some scientific diff --git a/Documentation/mm/page_tables.rst b/Documentation/mm/page_tables.rst index 7840c1891751..be47b192a596 100644 --- a/Documentation/mm/page_tables.rst +++ b/Documentation/mm/page_tables.rst @@ -152,3 +152,130 @@ Page table handling code that wishes to be architecture-neutral, such as the virtual memory manager, will need to be written so that it traverses all of the currently five levels. This style should also be preferred for architecture-specific code, so as to be robust to future changes. + + +MMU, TLB, and Page Faults +========================= + +The `Memory Management Unit (MMU)` is a hardware component that handles virtual +to physical address translations. It may use relatively small caches in hardware +called `Translation Lookaside Buffers (TLBs)` and `Page Walk Caches` to speed up +these translations. + +When CPU accesses a memory location, it provides a virtual address to the MMU, +which checks if there is the existing translation in the TLB or in the Page +Walk Caches (on architectures that support them). If no translation is found, +MMU uses the page walks to determine the physical address and create the map. + +The dirty bit for a page is set (i.e., turned on) when the page is written to. +Each page of memory has associated permission and dirty bits. The latter +indicate that the page has been modified since it was loaded into memory. + +If nothing prevents it, eventually the physical memory can be accessed and the +requested operation on the physical frame is performed. + +There are several reasons why the MMU can't find certain translations. It could +happen because the CPU is trying to access memory that the current task is not +permitted to, or because the data is not present into physical memory. + +When these conditions happen, the MMU triggers page faults, which are types of +exceptions that signal the CPU to pause the current execution and run a special +function to handle the mentioned exceptions. + +There are common and expected causes of page faults. These are triggered by +process management optimization techniques called "Lazy Allocation" and +"Copy-on-Write". Page faults may also happen when frames have been swapped out +to persistent storage (swap partition or file) and evicted from their physical +locations. + +These techniques improve memory efficiency, reduce latency, and minimize space +occupation. This document won't go deeper into the details of "Lazy Allocation" +and "Copy-on-Write" because these subjects are out of scope as they belong to +Process Address Management. + +Swapping differentiates itself from the other mentioned techniques because it's +undesirable since it's performed as a means to reduce memory under heavy +pressure. + +Swapping can't work for memory mapped by kernel logical addresses. These are a +subset of the kernel virtual space that directly maps a contiguous range of +physical memory. Given any logical address, its physical address is determined +with simple arithmetic on an offset. Accesses to logical addresses are fast +because they avoid the need for complex page table lookups at the expenses of +frames not being evictable and pageable out. + +If the kernel fails to make room for the data that must be present in the +physical frames, the kernel invokes the out-of-memory (OOM) killer to make room +by terminating lower priority processes until pressure reduces under a safe +threshold. + +Additionally, page faults may be also caused by code bugs or by maliciously +crafted addresses that the CPU is instructed to access. A thread of a process +could use instructions to address (non-shared) memory which does not belong to +its own address space, or could try to execute an instruction that want to write +to a read-only location. + +If the above-mentioned conditions happen in user-space, the kernel sends a +`Segmentation Fault` (SIGSEGV) signal to the current thread. That signal usually +causes the termination of the thread and of the process it belongs to. + +This document is going to simplify and show an high altitude view of how the +Linux kernel handles these page faults, creates tables and tables' entries, +check if memory is present and, if not, requests to load data from persistent +storage or from other devices, and updates the MMU and its caches. + +The first steps are architecture dependent. Most architectures jump to +`do_page_fault()`, whereas the x86 interrupt handler is defined by the +`DEFINE_IDTENTRY_RAW_ERRORCODE()` macro which calls `handle_page_fault()`. + +Whatever the routes, all architectures end up to the invocation of +`handle_mm_fault()` which, in turn, (likely) ends up calling +`__handle_mm_fault()` to carry out the actual work of allocating the page +tables. + +The unfortunate case of not being able to call `__handle_mm_fault()` means +that the virtual address is pointing to areas of physical memory which are not +permitted to be accessed (at least from the current context). This +condition resolves to the kernel sending the above-mentioned SIGSEGV signal +to the process and leads to the consequences already explained. + +`__handle_mm_fault()` carries out its work by calling several functions to +find the entry's offsets of the upper layers of the page tables and allocate +the tables that it may need. + +The functions that look for the offset have names like `*_offset()`, where the +"*" is for pgd, p4d, pud, pmd, pte; instead the functions to allocate the +corresponding tables, layer by layer, are called `*_alloc`, using the +above-mentioned convention to name them after the corresponding types of tables +in the hierarchy. + +The page table walk may end at one of the middle or upper layers (PMD, PUD). + +Linux supports larger page sizes than the usual 4KB (i.e., the so called +`huge pages`). When using these kinds of larger pages, higher level pages can +directly map them, with no need to use lower level page entries (PTE). Huge +pages contain large contiguous physical regions that usually span from 2MB to +1GB. They are respectively mapped by the PMD and PUD page entries. + +The huge pages bring with them several benefits like reduced TLB pressure, +reduced page table overhead, memory allocation efficiency, and performance +improvement for certain workloads. However, these benefits come with +trade-offs, like wasted memory and allocation challenges. + +At the very end of the walk with allocations, if it didn't return errors, +`__handle_mm_fault()` finally calls `handle_pte_fault()`, which via `do_fault()` +performs one of `do_read_fault()`, `do_cow_fault()`, `do_shared_fault()`. +"read", "cow", "shared" give hints about the reasons and the kind of fault it's +handling. + +The actual implementation of the workflow is very complex. Its design allows +Linux to handle page faults in a way that is tailored to the specific +characteristics of each architecture, while still sharing a common overall +structure. + +To conclude this high altitude view of how Linux handles page faults, let's +add that the page faults handler can be disabled and enabled respectively with +`pagefault_disable()` and `pagefault_enable()`. + +Several code path make use of the latter two functions because they need to +disable traps into the page faults handler, mostly to prevent deadlocks. diff --git a/Documentation/mm/vmemmap_dedup.rst b/Documentation/mm/vmemmap_dedup.rst index 59891f72420e..593ede6d314b 100644 --- a/Documentation/mm/vmemmap_dedup.rst +++ b/Documentation/mm/vmemmap_dedup.rst @@ -211,7 +211,7 @@ the device (altmap). The following page sizes are supported in DAX: PAGE_SIZE (4K on x86_64), PMD_SIZE (2M on x86_64) and PUD_SIZE (1G on x86_64). -For powerpc equivalent details see Documentation/powerpc/vmemmap_dedup.rst +For powerpc equivalent details see Documentation/arch/powerpc/vmemmap_dedup.rst The differences with HugeTLB are relatively minor. diff --git a/Documentation/netlink/genetlink-c.yaml b/Documentation/netlink/genetlink-c.yaml index 9806c44f604c..c58f7153fcf8 100644 --- a/Documentation/netlink/genetlink-c.yaml +++ b/Documentation/netlink/genetlink-c.yaml @@ -13,6 +13,11 @@ $defs: type: [ string, integer ] pattern: ^[0-9A-Za-z_]+( - 1)?$ minimum: 0 + len-or-limit: + # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc. + type: [ string, integer ] + pattern: ^[su](8|16|32|64)-(min|max)$ + minimum: 0 # Schema for specs title: Protocol @@ -26,10 +31,6 @@ properties: type: string doc: type: string - version: - description: Generic Netlink family version. Default is 1. - type: integer - minimum: 1 protocol: description: Schema compatibility level. Default is "genetlink". enum: [ genetlink, genetlink-c ] @@ -46,6 +47,12 @@ properties: max-by-define: description: Makes the number of attributes and commands be specified by a define, not an enum value. type: boolean + cmd-max-name: + description: Name of the define for the last operation in the list. + type: string + cmd-cnt-name: + description: The explicit name for constant holding the count of operations (last operation + 1). + type: string # End genetlink-c definitions: @@ -142,13 +149,14 @@ properties: type: array items: type: object - required: [ name, type ] + required: [ name ] additionalProperties: False properties: name: type: string type: &attr-type - enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, + enum: [ unused, pad, flag, binary, + uint, sint, u8, u16, u32, u64, s32, s64, string, nest, array-nest, nest-type-value ] doc: description: Documentation of the attribute. @@ -187,13 +195,19 @@ properties: type: string min: description: Min value for an integer attribute. - type: integer + $ref: '#/$defs/len-or-limit' + max: + description: Max value for an integer attribute. + $ref: '#/$defs/len-or-limit' min-len: description: Min length for a binary attribute. $ref: '#/$defs/len-or-define' max-len: description: Max length for a string or a binary attribute. $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' sub-type: *attr-type display-hint: &display-hint description: | @@ -215,6 +229,18 @@ properties: not: required: [ name-prefix ] + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + operations: description: Operations supported by the protocol. type: object @@ -275,6 +301,11 @@ properties: type: array items: enum: [ strict, dump, dump-strict ] + config-cond: + description: | + Name of the kernel config option gating the presence of + the operation, without the 'CONFIG_' prefix. + type: string do: &subop-type description: Main command handler. type: object diff --git a/Documentation/netlink/genetlink-legacy.yaml b/Documentation/netlink/genetlink-legacy.yaml index 12a0a045605d..938703088306 100644 --- a/Documentation/netlink/genetlink-legacy.yaml +++ b/Documentation/netlink/genetlink-legacy.yaml @@ -13,6 +13,11 @@ $defs: type: [ string, integer ] pattern: ^[0-9A-Za-z_]+( - 1)?$ minimum: 0 + len-or-limit: + # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc. + type: [ string, integer ] + pattern: ^[su](8|16|32|64)-(min|max)$ + minimum: 0 # Schema for specs title: Protocol @@ -26,10 +31,6 @@ properties: type: string doc: type: string - version: - description: Generic Netlink family version. Default is 1. - type: integer - minimum: 1 protocol: description: Schema compatibility level. Default is "genetlink". enum: [ genetlink, genetlink-c, genetlink-legacy ] # Trim @@ -46,6 +47,12 @@ properties: max-by-define: description: Makes the number of attributes and commands be specified by a define, not an enum value. type: boolean + cmd-max-name: + description: Name of the define for the last operation in the list. + type: string + cmd-cnt-name: + description: The explicit name for constant holding the count of operations (last operation + 1). + type: string # End genetlink-c # Start genetlink-legacy kernel-policy: @@ -53,6 +60,10 @@ properties: Defines if the input policy in the kernel is global, per-operation, or split per operation type. Default is split. enum: [ split, per-op, global ] + version: + description: Generic Netlink family version. Default is 1. + type: integer + minimum: 1 # End genetlink-legacy definitions: @@ -180,14 +191,15 @@ properties: type: array items: type: object - required: [ name, type ] + required: [ name ] additionalProperties: False properties: name: type: string type: &attr-type description: The netlink attribute type - enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, + enum: [ unused, pad, flag, binary, bitfield32, + uint, sint, u8, u16, u32, u64, s32, s64, string, nest, array-nest, nest-type-value ] doc: description: Documentation of the attribute. @@ -226,13 +238,19 @@ properties: type: string min: description: Min value for an integer attribute. - type: integer + $ref: '#/$defs/len-or-limit' + max: + description: Max value for an integer attribute. + $ref: '#/$defs/len-or-limit' min-len: description: Min length for a binary attribute. $ref: '#/$defs/len-or-define' max-len: description: Max length for a string or a binary attribute. $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' sub-type: *attr-type display-hint: *display-hint # Start genetlink-c @@ -254,6 +272,18 @@ properties: not: required: [ name-prefix ] + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + operations: description: Operations supported by the protocol. type: object @@ -316,12 +346,17 @@ properties: description: Command flags. type: array items: - enum: [ admin-perm ] + enum: [ admin-perm, uns-admin-perm ] dont-validate: description: Kernel attribute validation flags. type: array items: enum: [ strict, dump, dump-strict ] + config-cond: + description: | + Name of the kernel config option gating the presence of + the operation, without the 'CONFIG_' prefix. + type: string # Start genetlink-legacy fixed-header: *fixed-header # End genetlink-legacy diff --git a/Documentation/netlink/genetlink.yaml b/Documentation/netlink/genetlink.yaml index 3d338c48bf21..3283bf458ff1 100644 --- a/Documentation/netlink/genetlink.yaml +++ b/Documentation/netlink/genetlink.yaml @@ -13,6 +13,11 @@ $defs: type: [ string, integer ] pattern: ^[0-9A-Za-z_]+( - 1)?$ minimum: 0 + len-or-limit: + # literal int or limit based on fixed-width type e.g. u8-min, u16-max, etc. + type: [ string, integer ] + pattern: ^[su](8|16|32|64)-(min|max)$ + minimum: 0 # Schema for specs title: Protocol @@ -26,10 +31,6 @@ properties: type: string doc: type: string - version: - description: Generic Netlink family version. Default is 1. - type: integer - minimum: 1 protocol: description: Schema compatibility level. Default is "genetlink". enum: [ genetlink ] @@ -115,13 +116,14 @@ properties: type: array items: type: object - required: [ name, type ] + required: [ name ] additionalProperties: False properties: name: type: string type: &attr-type - enum: [ unused, pad, flag, binary, u8, u16, u32, u64, s32, s64, + enum: [ unused, pad, flag, binary, + uint, sint, u8, u16, u32, u64, s32, s64, string, nest, array-nest, nest-type-value ] doc: description: Documentation of the attribute. @@ -160,13 +162,19 @@ properties: type: string min: description: Min value for an integer attribute. - type: integer + $ref: '#/$defs/len-or-limit' + max: + description: Max value for an integer attribute. + $ref: '#/$defs/len-or-limit' min-len: description: Min length for a binary attribute. $ref: '#/$defs/len-or-define' max-len: description: Max length for a string or a binary attribute. $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' sub-type: *attr-type display-hint: &display-hint description: | @@ -184,6 +192,18 @@ properties: not: required: [ name-prefix ] + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + operations: description: Operations supported by the protocol. type: object @@ -244,6 +264,11 @@ properties: type: array items: enum: [ strict, dump, dump-strict ] + config-cond: + description: | + Name of the kernel config option gating the presence of + the operation, without the 'CONFIG_' prefix. + type: string do: &subop-type description: Main command handler. type: object diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml index 896797876414..775cce8c548a 100644 --- a/Documentation/netlink/netlink-raw.yaml +++ b/Documentation/netlink/netlink-raw.yaml @@ -47,6 +47,12 @@ properties: max-by-define: description: Makes the number of attributes and commands be specified by a define, not an enum value. type: boolean + cmd-max-name: + description: Name of the define for the last operation in the list. + type: string + cmd-cnt-name: + description: The explicit name for constant holding the count of operations (last operation + 1). + type: string # End genetlink-c # Start genetlink-legacy kernel-policy: @@ -187,7 +193,7 @@ properties: type: array items: type: object - required: [ name, type ] + required: [ name ] additionalProperties: False properties: name: @@ -240,6 +246,9 @@ properties: max-len: description: Max length for a string or a binary attribute. $ref: '#/$defs/len-or-define' + exact-len: + description: Exact length for a string or a binary attribute. + $ref: '#/$defs/len-or-define' sub-type: *attr-type display-hint: *display-hint # Start genetlink-c @@ -261,6 +270,18 @@ properties: not: required: [ name-prefix ] + # type property is only required if not in subset definition + if: + properties: + subset-of: + not: + type: string + then: + properties: + attributes: + items: + required: [ type ] + operations: description: Operations supported by the protocol. type: object diff --git a/Documentation/netlink/specs/devlink.yaml b/Documentation/netlink/specs/devlink.yaml index 065661acb878..c6ba4889575a 100644 --- a/Documentation/netlink/specs/devlink.yaml +++ b/Documentation/netlink/specs/devlink.yaml @@ -15,6 +15,161 @@ definitions: name: ingress - name: egress + - + type: enum + name: port-type + entries: + - + name: notset + - + name: auto + - + name: eth + - + name: ib + - + type: enum + name: port-flavour + entries: + - + name: physical + - + name: cpu + - + name: dsa + - + name: pci_pf + - + name: pci_vf + - + name: virtual + - + name: unused + - + name: pci_sf + - + type: enum + name: port-fn-state + entries: + - + name: inactive + - + name: active + - + type: enum + name: port-fn-opstate + entries: + - + name: detached + - + name: attached + - + type: enum + name: port-fn-attr-cap + entries: + - + name: roce-bit + - + name: migratable-bit + - + type: enum + name: sb-threshold-type + entries: + - + name: static + - + name: dynamic + - + type: enum + name: eswitch-mode + entries: + - + name: legacy + - + name: switchdev + - + type: enum + name: eswitch-inline-mode + entries: + - + name: none + - + name: link + - + name: network + - + name: transport + - + type: enum + name: eswitch-encap-mode + entries: + - + name: none + - + name: basic + - + type: enum + name: dpipe-match-type + entries: + - + name: field-exact + - + type: enum + name: dpipe-action-type + entries: + - + name: field-modify + - + type: enum + name: dpipe-field-mapping-type + entries: + - + name: none + - + name: ifindex + - + type: enum + name: resource-unit + entries: + - + name: entry + - + type: enum + name: reload-action + entries: + - + name: driver-reinit + value: 1 + - + name: fw-activate + - + type: enum + name: param-cmode + entries: + - + name: runtime + - + name: driverinit + - + name: permanent + - + type: enum + name: flash-overwrite + entries: + - + name: settings-bit + - + name: identifiers-bit + - + type: enum + name: trap-action + entries: + - + name: drop + - + name: trap + - + name: mirror attribute-sets: - @@ -31,6 +186,17 @@ attribute-sets: - name: port-index type: u32 + - + name: port-type + type: u16 + enum: port-type + + # TODO: fill in the attributes in between + + - + name: port-split-count + type: u32 + value: 9 # TODO: fill in the attributes in between @@ -45,18 +211,224 @@ attribute-sets: name: sb-pool-index type: u16 value: 17 - - name: sb-pool-type type: u8 enum: sb-pool-type + - + name: sb-pool-size + type: u32 + - + name: sb-pool-threshold-type + type: u8 + enum: sb-threshold-type + - + name: sb-threshold + type: u32 + - + name: sb-tc-index + type: u16 + value: 22 # TODO: fill in the attributes in between - - name: sb-tc-index + name: eswitch-mode type: u16 - value: 22 + value: 25 + enum: eswitch-mode + + - + name: eswitch-inline-mode + type: u16 + enum: eswitch-inline-mode + - + name: dpipe-tables + type: nest + nested-attributes: dl-dpipe-tables + - + name: dpipe-table + type: nest + multi-attr: true + nested-attributes: dl-dpipe-table + - + name: dpipe-table-name + type: string + - + name: dpipe-table-size + type: u64 + - + name: dpipe-table-matches + type: nest + nested-attributes: dl-dpipe-table-matches + - + name: dpipe-table-actions + type: nest + nested-attributes: dl-dpipe-table-actions + - + name: dpipe-table-counters-enabled + type: u8 + - + name: dpipe-entries + type: nest + nested-attributes: dl-dpipe-entries + - + name: dpipe-entry + type: nest + multi-attr: true + nested-attributes: dl-dpipe-entry + - + name: dpipe-entry-index + type: u64 + - + name: dpipe-entry-match-values + type: nest + nested-attributes: dl-dpipe-entry-match-values + - + name: dpipe-entry-action-values + type: nest + nested-attributes: dl-dpipe-entry-action-values + - + name: dpipe-entry-counter + type: u64 + - + name: dpipe-match + type: nest + multi-attr: true + nested-attributes: dl-dpipe-match + - + name: dpipe-match-value + type: nest + multi-attr: true + nested-attributes: dl-dpipe-match-value + - + name: dpipe-match-type + type: u32 + enum: dpipe-match-type + - + name: dpipe-action + type: nest + multi-attr: true + nested-attributes: dl-dpipe-action + - + name: dpipe-action-value + type: nest + multi-attr: true + nested-attributes: dl-dpipe-action-value + - + name: dpipe-action-type + type: u32 + enum: dpipe-action-type + - + name: dpipe-value + type: binary + - + name: dpipe-value-mask + type: binary + - + name: dpipe-value-mapping + type: u32 + - + name: dpipe-headers + type: nest + nested-attributes: dl-dpipe-headers + - + name: dpipe-header + type: nest + multi-attr: true + nested-attributes: dl-dpipe-header + - + name: dpipe-header-name + type: string + - + name: dpipe-header-id + type: u32 + - + name: dpipe-header-fields + type: nest + nested-attributes: dl-dpipe-header-fields + - + name: dpipe-header-global + type: u8 + - + name: dpipe-header-index + type: u32 + - + name: dpipe-field + type: nest + multi-attr: true + nested-attributes: dl-dpipe-field + - + name: dpipe-field-name + type: string + - + name: dpipe-field-id + type: u32 + - + name: dpipe-field-bitwidth + type: u32 + - + name: dpipe-field-mapping-type + type: u32 + enum: dpipe-field-mapping-type + - + name: pad + type: pad + - + name: eswitch-encap-mode + type: u8 + value: 62 + enum: eswitch-encap-mode + - + name: resource-list + type: nest + nested-attributes: dl-resource-list + - + name: resource + type: nest + multi-attr: true + nested-attributes: dl-resource + - + name: resource-name + type: string + - + name: resource-id + type: u64 + - + name: resource-size + type: u64 + - + name: resource-size-new + type: u64 + - + name: resource-size-valid + type: u8 + - + name: resource-size-min + type: u64 + - + name: resource-size-max + type: u64 + - + name: resource-size-gran + type: u64 + - + name: resource-unit + type: u8 + enum: resource-unit + - + name: resource-occ + type: u64 + - + name: dpipe-table-resource-id + type: u64 + - + name: dpipe-table-resource-units + type: u64 + - + name: port-flavour + type: u16 + enum: port-flavour # TODO: fill in the attributes in between @@ -68,16 +440,40 @@ attribute-sets: # TODO: fill in the attributes in between - + name: param-type + type: u8 + value: 83 + + # TODO: fill in the attributes in between + + - + name: param-value-cmode + type: u8 + enum: param-cmode + value: 87 + - name: region-name type: string - value: 88 # TODO: fill in the attributes in between - + name: region-snapshot-id + type: u32 + value: 92 + + # TODO: fill in the attributes in between + + - + name: region-chunk-addr + type: u64 + value: 96 + - + name: region-chunk-len + type: u64 + - name: info-driver-name type: string - value: 98 - name: info-serial-number type: string @@ -106,6 +502,29 @@ attribute-sets: # TODO: fill in the attributes in between - + name: fmsg + type: nest + nested-attributes: dl-fmsg + value: 106 + - + name: fmsg-obj-nest-start + type: flag + - + name: fmsg-pair-nest-start + type: flag + - + name: fmsg-arr-nest-start + type: flag + - + name: fmsg-nest-end + type: flag + - + name: fmsg-obj-name + type: string + + # TODO: fill in the attributes in between + + - name: health-reporter-name type: string value: 115 @@ -113,9 +532,36 @@ attribute-sets: # TODO: fill in the attributes in between - + name: health-reporter-graceful-period + type: u64 + value: 120 + - + name: health-reporter-auto-recover + type: u8 + - + name: flash-update-file-name + type: string + - + name: flash-update-component + type: string + + # TODO: fill in the attributes in between + + - + name: port-pci-pf-number + type: u16 + value: 127 + + # TODO: fill in the attributes in between + + - name: trap-name type: string value: 130 + - + name: trap-action + type: u8 + enum: trap-action # TODO: fill in the attributes in between @@ -131,23 +577,68 @@ attribute-sets: # TODO: fill in the attributes in between - - name: trap-policer-id + name: netns-fd + type: u32 + value: 138 + - + name: netns-pid + type: u32 + - + name: netns-id type: u32 - value: 142 # TODO: fill in the attributes in between - - name: reload-action + name: health-reporter-auto-dump type: u8 - value: 153 + value: 141 + - + name: trap-policer-id + type: u32 + - + name: trap-policer-rate + type: u64 + - + name: trap-policer-burst + type: u64 + - + name: port-function + type: nest + nested-attributes: dl-port-function + + # TODO: fill in the attributes in between + + - + name: port-controller-number + type: u32 + value: 150 # TODO: fill in the attributes in between - + name: flash-update-overwrite-mask + type: bitfield32 + enum: flash-overwrite + enum-as-flags: True + value: 152 + - + name: reload-action + type: u8 + enum: reload-action + - + name: reload-actions-performed + type: bitfield32 + enum: reload-action + enum-as-flags: True + - + name: reload-limits + type: bitfield32 + enum: reload-action + enum-as-flags: True + - name: dev-stats type: nest - value: 156 nested-attributes: dl-dev-stats - name: reload-stats @@ -182,9 +673,25 @@ attribute-sets: # TODO: fill in the attributes in between - + name: port-pci-sf-number + type: u32 + value: 164 + + # TODO: fill in the attributes in between + + - + name: rate-tx-share + type: u64 + value: 166 + - + name: rate-tx-max + type: u64 + - name: rate-node-name type: string - value: 168 + - + name: rate-parent-node-name + type: string # TODO: fill in the attributes in between @@ -193,60 +700,329 @@ attribute-sets: type: u32 value: 171 + # TODO: fill in the attributes in between + + - + name: linecard-type + type: string + value: 173 + + # TODO: fill in the attributes in between + + - + name: selftests + type: nest + value: 176 + nested-attributes: dl-selftest-id + - + name: rate-tx-priority + type: u32 + - + name: rate-tx-weight + type: u32 + - + name: region-direct + type: flag + - name: dl-dev-stats subset-of: devlink attributes: - name: reload-stats - type: nest - name: remote-reload-stats - type: nest - name: dl-reload-stats subset-of: devlink attributes: - name: reload-action-info - type: nest - name: dl-reload-act-info subset-of: devlink attributes: - name: reload-action - type: u8 - name: reload-action-stats - type: nest - name: dl-reload-act-stats subset-of: devlink attributes: - name: reload-stats-entry - type: nest - name: dl-reload-stats-entry subset-of: devlink attributes: - name: reload-stats-limit - type: u8 - name: reload-stats-value - type: u32 - name: dl-info-version subset-of: devlink attributes: - name: info-version-name - type: string - name: info-version-value - type: string + - + name: dl-port-function + name-prefix: devlink-port-fn-attr- + attr-max-name: devlink-port-function-attr-max + attributes: + - + name-prefix: devlink-port-function-attr- + name: hw-addr + type: binary + value: 1 + - + name: state + type: u8 + enum: port-fn-state + - + name: opstate + type: u8 + enum: port-fn-opstate + - + name: caps + type: bitfield32 + enum: port-fn-attr-cap + enum-as-flags: True + + - + name: dl-dpipe-tables + subset-of: devlink + attributes: + - + name: dpipe-table + + - + name: dl-dpipe-table + subset-of: devlink + attributes: + - + name: dpipe-table-name + - + name: dpipe-table-size + - + name: dpipe-table-name + - + name: dpipe-table-size + - + name: dpipe-table-matches + - + name: dpipe-table-actions + - + name: dpipe-table-counters-enabled + - + name: dpipe-table-resource-id + - + name: dpipe-table-resource-units + + - + name: dl-dpipe-table-matches + subset-of: devlink + attributes: + - + name: dpipe-match + + - + name: dl-dpipe-table-actions + subset-of: devlink + attributes: + - + name: dpipe-action + + - + name: dl-dpipe-entries + subset-of: devlink + attributes: + - + name: dpipe-entry + + - + name: dl-dpipe-entry + subset-of: devlink + attributes: + - + name: dpipe-entry-index + - + name: dpipe-entry-match-values + - + name: dpipe-entry-action-values + - + name: dpipe-entry-counter + + - + name: dl-dpipe-entry-match-values + subset-of: devlink + attributes: + - + name: dpipe-match-value + + - + name: dl-dpipe-entry-action-values + subset-of: devlink + attributes: + - + name: dpipe-action-value + + - + name: dl-dpipe-match + subset-of: devlink + attributes: + - + name: dpipe-match-type + - + name: dpipe-header-id + - + name: dpipe-header-global + - + name: dpipe-header-index + - + name: dpipe-field-id + + - + name: dl-dpipe-match-value + subset-of: devlink + attributes: + - + name: dpipe-match + - + name: dpipe-value + - + name: dpipe-value-mask + - + name: dpipe-value-mapping + + - + name: dl-dpipe-action + subset-of: devlink + attributes: + - + name: dpipe-action-type + - + name: dpipe-header-id + - + name: dpipe-header-global + - + name: dpipe-header-index + - + name: dpipe-field-id + + - + name: dl-dpipe-action-value + subset-of: devlink + attributes: + - + name: dpipe-action + - + name: dpipe-value + - + name: dpipe-value-mask + - + name: dpipe-value-mapping + + - + name: dl-dpipe-headers + subset-of: devlink + attributes: + - + name: dpipe-header + + - + name: dl-dpipe-header + subset-of: devlink + attributes: + - + name: dpipe-header-name + - + name: dpipe-header-id + - + name: dpipe-header-global + - + name: dpipe-header-fields + + - + name: dl-dpipe-header-fields + subset-of: devlink + attributes: + - + name: dpipe-field + + - + name: dl-dpipe-field + subset-of: devlink + attributes: + - + name: dpipe-field-name + - + name: dpipe-field-id + - + name: dpipe-field-bitwidth + - + name: dpipe-field-mapping-type + + - + name: dl-resource + subset-of: devlink + attributes: + # - + # name: resource-list + # This is currently unsupported due to circular dependency + - + name: resource-name + - + name: resource-id + - + name: resource-size + - + name: resource-size-new + - + name: resource-size-valid + - + name: resource-size-min + - + name: resource-size-max + - + name: resource-size-gran + - + name: resource-unit + - + name: resource-occ + + - + name: dl-resource-list + subset-of: devlink + attributes: + - + name: resource + + - + name: dl-fmsg + subset-of: devlink + attributes: + - + name: fmsg-obj-nest-start + - + name: fmsg-pair-nest-start + - + name: fmsg-arr-nest-start + - + name: fmsg-nest-end + - + name: fmsg-obj-name + + - + name: dl-selftest-id + name-prefix: devlink-attr-selftest-id- + attributes: + - + name: flash + type: flag operations: enum-model: directional @@ -255,10 +1031,7 @@ operations: name: get doc: Get devlink instances. attribute-set: devlink - dont-validate: - - strict - - dump - + dont-validate: [ strict, dump ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -273,7 +1046,6 @@ operations: - bus-name - dev-name - reload-failed - - reload-action - dev-stats dump: reply: *get-reply @@ -282,9 +1054,7 @@ operations: name: port-get doc: Get devlink port instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit-port post: devlink-nl-post-doit @@ -303,16 +1073,90 @@ operations: reply: value: 3 # due to a bug, port dump returns DEVLINK_CMD_NEW attributes: *port-id-attrs + - + name: port-set + doc: Set devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - port-type + - port-function - # TODO: fill in the operations in between + - + name: port-new + doc: Create devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - port-flavour + - port-pci-pf-number + - port-pci-sf-number + - port-controller-number + reply: + value: 7 + attributes: *port-id-attrs + + - + name: port-del + doc: Delete devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs + + - + name: port-split + doc: Split devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - port-split-count + + - + name: port-unsplit + doc: Unplit devlink port instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs - name: sb-get doc: Get shared buffer instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -330,15 +1174,11 @@ operations: attributes: *dev-id-attrs reply: *sb-get-reply - # TODO: fill in the operations in between - - name: sb-pool-get doc: Get shared buffer pool instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -357,15 +1197,29 @@ operations: attributes: *dev-id-attrs reply: *sb-pool-get-reply - # TODO: fill in the operations in between + - + name: sb-pool-set + doc: Set shared buffer pool instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - sb-index + - sb-pool-index + - sb-pool-threshold-type + - sb-pool-size - name: sb-port-pool-get doc: Get shared buffer port-pool combinations and threshold. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit-port post: devlink-nl-post-doit @@ -385,15 +1239,29 @@ operations: attributes: *dev-id-attrs reply: *sb-port-pool-get-reply - # TODO: fill in the operations in between + - + name: sb-port-pool-set + doc: Set shared buffer port-pool combinations and threshold. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - sb-index + - sb-pool-index + - sb-threshold - name: sb-tc-pool-bind-get doc: Get shared buffer port-TC to pool bindings and threshold. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit-port post: devlink-nl-post-doit @@ -414,41 +1282,264 @@ operations: attributes: *dev-id-attrs reply: *sb-tc-pool-bind-get-reply - # TODO: fill in the operations in between + - + name: sb-tc-pool-bind-set + doc: Set shared buffer port-TC to pool bindings and threshold. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - sb-index + - sb-pool-index + - sb-pool-type + - sb-tc-index + - sb-threshold + + - + name: sb-occ-snapshot + doc: Take occupancy snapshot of shared buffer. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + value: 27 + attributes: + - bus-name + - dev-name + - sb-index + + - + name: sb-occ-max-clear + doc: Clear occupancy watermarks of shared buffer. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - sb-index + + - + name: eswitch-get + doc: Get eswitch attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: *dev-id-attrs + reply: + value: 29 + attributes: &eswitch-attrs + - bus-name + - dev-name + - eswitch-mode + - eswitch-inline-mode + - eswitch-encap-mode + + - + name: eswitch-set + doc: Set eswitch attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: *eswitch-attrs + + - + name: dpipe-table-get + doc: Get dpipe table attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - dpipe-table-name + reply: + value: 31 + attributes: + - bus-name + - dev-name + - dpipe-tables + + - + name: dpipe-entries-get + doc: Get dpipe entries attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - dpipe-table-name + reply: + attributes: + - bus-name + - dev-name + - dpipe-entries + + - + name: dpipe-headers-get + doc: Get dpipe headers attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + reply: + attributes: + - bus-name + - dev-name + - dpipe-headers + + - + name: dpipe-table-counters-set + doc: Set dpipe counter attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - dpipe-table-name + - dpipe-table-counters-enabled + + - + name: resource-set + doc: Set resource attributes. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - resource-id + - resource-size + + - + name: resource-dump + doc: Get resource attributes. + attribute-set: devlink + dont-validate: [ strict ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + reply: + value: 36 + attributes: + - bus-name + - dev-name + - resource-list + + - + name: reload + doc: Reload devlink. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - reload-action + - reload-limits + - netns-pid + - netns-fd + - netns-id + reply: + attributes: + - bus-name + - dev-name + - reload-actions-performed - name: param-get doc: Get param instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit request: - value: 38 attributes: ¶m-id-attrs - bus-name - dev-name - param-name reply: ¶m-get-reply - value: 38 attributes: *param-id-attrs dump: request: attributes: *dev-id-attrs reply: *param-get-reply - # TODO: fill in the operations in between + - + name: param-set + doc: Set param instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - param-name + - param-type + # param-value-data is missing here as the type is variable + - param-value-cmode - name: region-get doc: Get region instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit-port-optional post: devlink-nl-post-doit @@ -467,16 +1558,97 @@ operations: attributes: *dev-id-attrs reply: *region-get-reply - # TODO: fill in the operations in between + - + name: region-new + doc: Create region snapshot. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + value: 44 + attributes: ®ion-snapshot-id-attrs + - bus-name + - dev-name + - port-index + - region-name + - region-snapshot-id + reply: + value: 44 + attributes: *region-snapshot-id-attrs + + - + name: region-del + doc: Delete region snapshot. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *region-snapshot-id-attrs + + - + name: region-read + doc: Read region data. + attribute-set: devlink + dont-validate: [ dump-strict ] + flags: [ admin-perm ] + dump: + request: + attributes: + - bus-name + - dev-name + - port-index + - region-name + - region-snapshot-id + - region-direct + - region-chunk-addr + - region-chunk-len + reply: + value: 46 + attributes: + - bus-name + - dev-name + - port-index + - region-name + + - + name: port-param-get + doc: Get port param instances. + attribute-set: devlink + dont-validate: [ strict, dump-strict ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs + reply: + attributes: *port-id-attrs + dump: + reply: + attributes: *port-id-attrs + + - + name: port-param-set + doc: Set port param instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port + post: devlink-nl-post-doit + request: + attributes: *port-id-attrs - name: info-get doc: Get device information, like driver name, hardware and firmware versions etc. attribute-set: devlink - dont-validate: - - strict - - dump - + dont-validate: [ strict, dump ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -500,9 +1672,7 @@ operations: name: health-reporter-get doc: Get health reporter instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit-port-optional post: devlink-nl-post-doit @@ -519,15 +1689,97 @@ operations: attributes: *port-id-attrs reply: *health-reporter-get-reply - # TODO: fill in the operations in between + - + name: health-reporter-set + doc: Set health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - port-index + - health-reporter-name + - health-reporter-graceful-period + - health-reporter-auto-recover + - health-reporter-auto-dump + + - + name: health-reporter-recover + doc: Recover health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *health-reporter-id-attrs + + - + name: health-reporter-diagnose + doc: Diagnose health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *health-reporter-id-attrs + + - + name: health-reporter-dump-get + doc: Dump health reporter instances. + attribute-set: devlink + dont-validate: [ dump-strict ] + flags: [ admin-perm ] + dump: + request: + attributes: *health-reporter-id-attrs + reply: + value: 56 + attributes: + - fmsg + + - + name: health-reporter-dump-clear + doc: Clear dump of health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + attributes: *health-reporter-id-attrs + + - + name: flash-update + doc: Flash update devlink instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - flash-update-file-name + - flash-update-component + - flash-update-overwrite-mask - name: trap-get doc: Get trap instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -545,15 +1797,27 @@ operations: attributes: *dev-id-attrs reply: *trap-get-reply - # TODO: fill in the operations in between + - + name: trap-set + doc: Set trap instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - trap-name + - trap-action - name: trap-group-get doc: Get trap group instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -571,15 +1835,28 @@ operations: attributes: *dev-id-attrs reply: *trap-group-get-reply - # TODO: fill in the operations in between + - + name: trap-group-set + doc: Set trap group instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - trap-group-name + - trap-action + - trap-policer-id - name: trap-policer-get doc: Get trap policer instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -597,15 +1874,41 @@ operations: attributes: *dev-id-attrs reply: *trap-policer-get-reply - # TODO: fill in the operations in between + - + name: trap-policer-set + doc: Get trap policer instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - trap-policer-id + - trap-policer-rate + - trap-policer-burst + + - + name: health-reporter-test + doc: Test health reporter instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit-port-optional + post: devlink-nl-post-doit + request: + value: 73 + attributes: *health-reporter-id-attrs - name: rate-get doc: Get rate instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -624,15 +1927,66 @@ operations: attributes: *dev-id-attrs reply: *rate-get-reply - # TODO: fill in the operations in between + - + name: rate-set + doc: Set rate instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - rate-node-name + - rate-tx-share + - rate-tx-max + - rate-tx-priority + - rate-tx-weight + - rate-parent-node-name + + - + name: rate-new + doc: Create rate instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - rate-node-name + - rate-tx-share + - rate-tx-max + - rate-tx-priority + - rate-tx-weight + - rate-parent-node-name + + - + name: rate-del + doc: Delete rate instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - rate-node-name - name: linecard-get doc: Get line card instances. attribute-set: devlink - dont-validate: - - strict - + dont-validate: [ strict ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -650,16 +2004,27 @@ operations: attributes: *dev-id-attrs reply: *linecard-get-reply - # TODO: fill in the operations in between + - + name: linecard-set + doc: Set line card instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - linecard-index + - linecard-type - name: selftests-get doc: Get device selftest instances. attribute-set: devlink - dont-validate: - - strict - - dump - + dont-validate: [ strict, dump ] do: pre: devlink-nl-pre-doit post: devlink-nl-post-doit @@ -671,3 +2036,18 @@ operations: attributes: *dev-id-attrs dump: reply: *selftests-get-reply + + - + name: selftests-run + doc: Run device selftest instances. + attribute-set: devlink + dont-validate: [ strict ] + flags: [ admin-perm ] + do: + pre: devlink-nl-pre-doit + post: devlink-nl-post-doit + request: + attributes: + - bus-name + - dev-name + - selftests diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml new file mode 100644 index 000000000000..cf8abe1c0550 --- /dev/null +++ b/Documentation/netlink/specs/dpll.yaml @@ -0,0 +1,510 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: dpll + +doc: DPLL subsystem. + +definitions: + - + type: enum + name: mode + doc: | + working modes a dpll can support, differentiates if and how dpll selects + one of its inputs to syntonize with it, valid values for DPLL_A_MODE + attribute + entries: + - + name: manual + doc: input can be only selected by sending a request to dpll + value: 1 + - + name: automatic + doc: highest prio input pin auto selected by dpll + render-max: true + - + type: enum + name: lock-status + doc: | + provides information of dpll device lock status, valid values for + DPLL_A_LOCK_STATUS attribute + entries: + - + name: unlocked + doc: | + dpll was not yet locked to any valid input (or forced by setting + DPLL_A_MODE to DPLL_MODE_DETACHED) + value: 1 + - + name: locked + doc: | + dpll is locked to a valid signal, but no holdover available + - + name: locked-ho-acq + doc: | + dpll is locked and holdover acquired + - + name: holdover + doc: | + dpll is in holdover state - lost a valid lock or was forced + by disconnecting all the pins (latter possible only + when dpll lock-state was already DPLL_LOCK_STATUS_LOCKED_HO_ACQ, + if dpll lock-state was not DPLL_LOCK_STATUS_LOCKED_HO_ACQ, the + dpll's lock-state shall remain DPLL_LOCK_STATUS_UNLOCKED) + render-max: true + - + type: const + name: temp-divider + value: 1000 + doc: | + temperature divider allowing userspace to calculate the + temperature as float with three digit decimal precision. + Value of (DPLL_A_TEMP / DPLL_TEMP_DIVIDER) is integer part of + temperature value. + Value of (DPLL_A_TEMP % DPLL_TEMP_DIVIDER) is fractional part of + temperature value. + - + type: enum + name: type + doc: type of dpll, valid values for DPLL_A_TYPE attribute + entries: + - + name: pps + doc: dpll produces Pulse-Per-Second signal + value: 1 + - + name: eec + doc: dpll drives the Ethernet Equipment Clock + render-max: true + - + type: enum + name: pin-type + doc: | + defines possible types of a pin, valid values for DPLL_A_PIN_TYPE + attribute + entries: + - + name: mux + doc: aggregates another layer of selectable pins + value: 1 + - + name: ext + doc: external input + - + name: synce-eth-port + doc: ethernet port PHY's recovered clock + - + name: int-oscillator + doc: device internal oscillator + - + name: gnss + doc: GNSS recovered clock + render-max: true + - + type: enum + name: pin-direction + doc: | + defines possible direction of a pin, valid values for + DPLL_A_PIN_DIRECTION attribute + entries: + - + name: input + doc: pin used as a input of a signal + value: 1 + - + name: output + doc: pin used to output the signal + render-max: true + - + type: const + name: pin-frequency-1-hz + value: 1 + - + type: const + name: pin-frequency-10-khz + value: 10000 + - + type: const + name: pin-frequency-77_5-khz + value: 77500 + - + type: const + name: pin-frequency-10-mhz + value: 10000000 + - + type: enum + name: pin-state + doc: | + defines possible states of a pin, valid values for + DPLL_A_PIN_STATE attribute + entries: + - + name: connected + doc: pin connected, active input of phase locked loop + value: 1 + - + name: disconnected + doc: pin disconnected, not considered as a valid input + - + name: selectable + doc: pin enabled for automatic input selection + render-max: true + - + type: flags + name: pin-capabilities + doc: | + defines possible capabilities of a pin, valid flags on + DPLL_A_PIN_CAPABILITIES attribute + entries: + - + name: direction-can-change + doc: pin direction can be changed + - + name: priority-can-change + doc: pin priority can be changed + - + name: state-can-change + doc: pin state can be changed + - + type: const + name: phase-offset-divider + value: 1000 + doc: | + phase offset divider allows userspace to calculate a value of + measured signal phase difference between a pin and dpll device + as a fractional value with three digit decimal precision. + Value of (DPLL_A_PHASE_OFFSET / DPLL_PHASE_OFFSET_DIVIDER) is an + integer part of a measured phase offset value. + Value of (DPLL_A_PHASE_OFFSET % DPLL_PHASE_OFFSET_DIVIDER) is a + fractional part of a measured phase offset value. + +attribute-sets: + - + name: dpll + enum-name: dpll_a + attributes: + - + name: id + type: u32 + - + name: module-name + type: string + - + name: pad + type: pad + - + name: clock-id + type: u64 + - + name: mode + type: u32 + enum: mode + - + name: mode-supported + type: u32 + enum: mode + multi-attr: true + - + name: lock-status + type: u32 + enum: lock-status + - + name: temp + type: s32 + - + name: type + type: u32 + enum: type + - + name: pin + enum-name: dpll_a_pin + attributes: + - + name: id + type: u32 + - + name: parent-id + type: u32 + - + name: module-name + type: string + - + name: pad + type: pad + - + name: clock-id + type: u64 + - + name: board-label + type: string + - + name: panel-label + type: string + - + name: package-label + type: string + - + name: type + type: u32 + enum: pin-type + - + name: direction + type: u32 + enum: pin-direction + - + name: frequency + type: u64 + - + name: frequency-supported + type: nest + multi-attr: true + nested-attributes: frequency-range + - + name: frequency-min + type: u64 + - + name: frequency-max + type: u64 + - + name: prio + type: u32 + - + name: state + type: u32 + enum: pin-state + - + name: capabilities + type: u32 + - + name: parent-device + type: nest + multi-attr: true + nested-attributes: pin-parent-device + - + name: parent-pin + type: nest + multi-attr: true + nested-attributes: pin-parent-pin + - + name: phase-adjust-min + type: s32 + - + name: phase-adjust-max + type: s32 + - + name: phase-adjust + type: s32 + - + name: phase-offset + type: s64 + - + name: pin-parent-device + subset-of: pin + attributes: + - + name: parent-id + - + name: direction + - + name: prio + - + name: state + - + name: phase-offset + - + name: pin-parent-pin + subset-of: pin + attributes: + - + name: parent-id + - + name: state + - + name: frequency-range + subset-of: pin + attributes: + - + name: frequency-min + - + name: frequency-max + +operations: + enum-name: dpll_cmd + list: + - + name: device-id-get + doc: | + Get id of dpll device that matches given attributes + attribute-set: dpll + flags: [ admin-perm ] + + do: + pre: dpll-lock-doit + post: dpll-unlock-doit + request: + attributes: + - module-name + - clock-id + - type + reply: + attributes: + - id + + - + name: device-get + doc: | + Get list of DPLL devices (dump) or attributes of a single dpll device + attribute-set: dpll + flags: [ admin-perm ] + + do: + pre: dpll-pre-doit + post: dpll-post-doit + request: + attributes: + - id + reply: &dev-attrs + attributes: + - id + - module-name + - mode + - mode-supported + - lock-status + - temp + - clock-id + - type + + dump: + pre: dpll-lock-dumpit + post: dpll-unlock-dumpit + reply: *dev-attrs + + - + name: device-set + doc: Set attributes for a DPLL device + attribute-set: dpll + flags: [ admin-perm ] + + do: + pre: dpll-pre-doit + post: dpll-post-doit + request: + attributes: + - id + - + name: device-create-ntf + doc: Notification about device appearing + notify: device-get + mcgrp: monitor + - + name: device-delete-ntf + doc: Notification about device disappearing + notify: device-get + mcgrp: monitor + - + name: device-change-ntf + doc: Notification about device configuration being changed + notify: device-get + mcgrp: monitor + - + name: pin-id-get + doc: | + Get id of a pin that matches given attributes + attribute-set: pin + flags: [ admin-perm ] + + do: + pre: dpll-lock-doit + post: dpll-unlock-doit + request: + attributes: + - module-name + - clock-id + - board-label + - panel-label + - package-label + - type + reply: + attributes: + - id + + - + name: pin-get + doc: | + Get list of pins and its attributes. + - dump request without any attributes given - list all the pins in the + system + - dump request with target dpll - list all the pins registered with + a given dpll device + - do request with target dpll and target pin - single pin attributes + attribute-set: pin + flags: [ admin-perm ] + + do: + pre: dpll-pin-pre-doit + post: dpll-pin-post-doit + request: + attributes: + - id + reply: &pin-attrs + attributes: + - id + - board-label + - panel-label + - package-label + - type + - frequency + - frequency-supported + - capabilities + - parent-device + - parent-pin + - phase-adjust-min + - phase-adjust-max + - phase-adjust + + dump: + pre: dpll-lock-dumpit + post: dpll-unlock-dumpit + request: + attributes: + - id + reply: *pin-attrs + + - + name: pin-set + doc: Set attributes of a target pin + attribute-set: pin + flags: [ admin-perm ] + + do: + pre: dpll-pin-pre-doit + post: dpll-pin-post-doit + request: + attributes: + - id + - frequency + - direction + - prio + - state + - parent-device + - parent-pin + - phase-adjust + - + name: pin-create-ntf + doc: Notification about pin appearing + notify: pin-get + mcgrp: monitor + - + name: pin-delete-ntf + doc: Notification about pin disappearing + notify: pin-get + mcgrp: monitor + - + name: pin-change-ntf + doc: Notification about pin configuration being changed + notify: pin-get + mcgrp: monitor + +mcast-groups: + list: + - + name: monitor diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml index 837b565577ca..5c7a65b009b4 100644 --- a/Documentation/netlink/specs/ethtool.yaml +++ b/Documentation/netlink/specs/ethtool.yaml @@ -818,13 +818,10 @@ attribute-sets: attributes: - name: hist-bkt-low - type: u32 - name: hist-bkt-hi - type: u32 - name: hist-val - type: u64 - name: stats attributes: diff --git a/Documentation/netlink/specs/handshake.yaml b/Documentation/netlink/specs/handshake.yaml index 6d89e30f5fd5..b934cc513e3d 100644 --- a/Documentation/netlink/specs/handshake.yaml +++ b/Documentation/netlink/specs/handshake.yaml @@ -34,16 +34,16 @@ attribute-sets: attributes: - name: cert - type: u32 + type: s32 - name: privkey - type: u32 + type: s32 - name: accept attributes: - name: sockfd - type: u32 + type: s32 - name: handler-class type: u32 @@ -79,7 +79,7 @@ attribute-sets: type: u32 - name: sockfd - type: u32 + type: s32 - name: remote-auth type: u32 diff --git a/Documentation/netlink/specs/mptcp.yaml b/Documentation/netlink/specs/mptcp.yaml new file mode 100644 index 000000000000..49f90cfb4698 --- /dev/null +++ b/Documentation/netlink/specs/mptcp.yaml @@ -0,0 +1,393 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: mptcp_pm +protocol: genetlink-legacy +doc: Multipath TCP. + +c-family-name: mptcp-pm-name +c-version-name: mptcp-pm-ver +max-by-define: true +kernel-policy: per-op +cmd-cnt-name: --mptcp-pm-cmd-after-last + +definitions: + - + type: enum + name: event-type + enum-name: mptcp-event-type + name-prefix: mptcp-event- + entries: + - + name: unspec + doc: unused event + - + name: created + doc: + token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport + A new MPTCP connection has been created. It is the good time to + allocate memory and send ADD_ADDR if needed. Depending on the + traffic-patterns it can take a long time until the + MPTCP_EVENT_ESTABLISHED is sent. + - + name: established + doc: + token, family, saddr4 | saddr6, daddr4 | daddr6, sport, dport + A MPTCP connection is established (can start new subflows). + - + name: closed + doc: + token + A MPTCP connection has stopped. + - + name: announced + value: 6 + doc: + token, rem_id, family, daddr4 | daddr6 [, dport] + A new address has been announced by the peer. + - + name: removed + doc: + token, rem_id + An address has been lost by the peer. + - + name: sub-established + value: 10 + doc: + token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport, + dport, backup, if_idx [, error] + A new subflow has been established. 'error' should not be set. + - + name: sub-closed + doc: + token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport, + dport, backup, if_idx [, error] + A subflow has been closed. An error (copy of sk_err) could be set if an + error has been detected for this subflow. + - + name: sub-priority + value: 13 + doc: + token, family, loc_id, rem_id, saddr4 | saddr6, daddr4 | daddr6, sport, + dport, backup, if_idx [, error] + The priority of a subflow has changed. 'error' should not be set. + - + name: listener-created + value: 15 + doc: + family, sport, saddr4 | saddr6 + A new PM listener is created. + - + name: listener-closed + doc: + family, sport, saddr4 | saddr6 + A PM listener is closed. + +attribute-sets: + - + name: address + name-prefix: mptcp-pm-addr-attr- + attributes: + - + name: unspec + type: unused + value: 0 + - + name: family + type: u16 + - + name: id + type: u8 + - + name: addr4 + type: u32 + byte-order: big-endian + - + name: addr6 + type: binary + checks: + exact-len: 16 + - + name: port + type: u16 + byte-order: big-endian + - + name: flags + type: u32 + - + name: if-idx + type: s32 + - + name: subflow-attribute + name-prefix: mptcp-subflow-attr- + attributes: + - + name: unspec + type: unused + value: 0 + - + name: token-rem + type: u32 + - + name: token-loc + type: u32 + - + name: relwrite-seq + type: u32 + - + name: map-seq + type: u64 + - + name: map-sfseq + type: u32 + - + name: ssn-offset + type: u32 + - + name: map-datalen + type: u16 + - + name: flags + type: u32 + - + name: id-rem + type: u8 + - + name: id-loc + type: u8 + - + name: pad + type: pad + - + name: endpoint + name-prefix: mptcp-pm-endpoint- + attributes: + - + name: addr + type: nest + nested-attributes: address + - + name: attr + name-prefix: mptcp-pm-attr- + attr-cnt-name: --mptcp-attr-after-last + attributes: + - + name: unspec + type: unused + value: 0 + - + name: addr + type: nest + nested-attributes: address + - + name: rcv-add-addrs + type: u32 + - + name: subflows + type: u32 + - + name: token + type: u32 + - + name: loc-id + type: u8 + - + name: addr-remote + type: nest + nested-attributes: address + - + name: event-attr + enum-name: mptcp-event-attr + name-prefix: mptcp-attr- + attributes: + - + name: unspec + type: unused + value: 0 + - + name: token + type: u32 + - + name: family + type: u16 + - + name: loc-id + type: u8 + - + name: rem-id + type: u8 + - + name: saddr4 + type: u32 + byte-order: big-endian + - + name: saddr6 + type: binary + checks: + min-len: 16 + - + name: daddr4 + type: u32 + byte-order: big-endian + - + name: daddr6 + type: binary + checks: + min-len: 16 + - + name: sport + type: u16 + byte-order: big-endian + - + name: dport + type: u16 + byte-order: big-endian + - + name: backup + type: u8 + - + name: error + type: u8 + - + name: flags + type: u16 + - + name: timeout + type: u32 + - + name: if_idx + type: u32 + - + name: reset-reason + type: u32 + - + name: reset-flags + type: u32 + - + name: server-side + type: u8 + +operations: + list: + - + name: unspec + doc: unused + value: 0 + - + name: add-addr + doc: Add endpoint + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &add-addr-attrs + request: + attributes: + - addr + - + name: del-addr + doc: Delete endpoint + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: *add-addr-attrs + - + name: get-addr + doc: Get endpoint information + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &get-addr-attrs + request: + attributes: + - addr + reply: + attributes: + - addr + dump: + reply: + attributes: + - addr + - + name: flush-addrs + doc: flush addresses + attribute-set: endpoint + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: *add-addr-attrs + - + name: set-limits + doc: Set protocol limits + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &mptcp-limits + request: + attributes: + - rcv-add-addrs + - subflows + - + name: get-limits + doc: Get protocol limits + attribute-set: attr + dont-validate: [ strict ] + do: &mptcp-get-limits + request: + attributes: + - rcv-add-addrs + - subflows + reply: + attributes: + - rcv-add-addrs + - subflows + - + name: set-flags + doc: Change endpoint flags + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &mptcp-set-flags + request: + attributes: + - addr + - token + - addr-remote + - + name: announce + doc: announce new sf + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &announce-add + request: + attributes: + - addr + - token + - + name: remove + doc: announce removal + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: + request: + attributes: + - token + - loc-id + - + name: subflow-create + doc: todo + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: &sf-create + request: + attributes: + - addr + - token + - addr-remote + - + name: subflow-destroy + doc: todo + attribute-set: attr + dont-validate: [ strict ] + flags: [ uns-admin-perm ] + do: *sf-create diff --git a/Documentation/netlink/specs/netdev.yaml b/Documentation/netlink/specs/netdev.yaml index 1c7284fd535b..14511b13f305 100644 --- a/Documentation/netlink/specs/netdev.yaml +++ b/Documentation/netlink/specs/netdev.yaml @@ -42,6 +42,19 @@ definitions: doc: This feature informs if netdev implements non-linear XDP buffer support in ndo_xdp_xmit callback. + - + type: flags + name: xdp-rx-metadata + render-max: true + entries: + - + name: timestamp + doc: + Device is capable of exposing receive HW timestamp via bpf_xdp_metadata_rx_timestamp(). + - + name: hash + doc: + Device is capable of exposing receive packet hash via bpf_xdp_metadata_rx_hash(). attribute-sets: - @@ -61,13 +74,18 @@ attribute-sets: doc: Bitmask of enabled xdp-features. type: u64 enum: xdp-act - enum-as-flags: true - name: xdp-zc-max-segs doc: max fragment count supported by ZC driver type: u32 checks: min: 1 + - + name: xdp-rx-metadata-features + doc: Bitmask of supported XDP receive metadata features. + See Documentation/networking/xdp-rx-metadata.rst for more details. + type: u64 + enum: xdp-rx-metadata operations: list: @@ -84,6 +102,7 @@ operations: - ifindex - xdp-features - xdp-zc-max-segs + - xdp-rx-metadata-features dump: reply: *dev-all - diff --git a/Documentation/netlink/specs/nfsd.yaml b/Documentation/netlink/specs/nfsd.yaml new file mode 100644 index 000000000000..05acc73e2e33 --- /dev/null +++ b/Documentation/netlink/specs/nfsd.yaml @@ -0,0 +1,89 @@ +# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) + +name: nfsd +protocol: genetlink +uapi-header: linux/nfsd_netlink.h + +doc: NFSD configuration over generic netlink. + +attribute-sets: + - + name: rpc-status + attributes: + - + name: xid + type: u32 + byte-order: big-endian + - + name: flags + type: u32 + - + name: prog + type: u32 + - + name: version + type: u8 + - + name: proc + type: u32 + - + name: service_time + type: s64 + - + name: pad + type: pad + - + name: saddr4 + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: daddr4 + type: u32 + byte-order: big-endian + display-hint: ipv4 + - + name: saddr6 + type: binary + display-hint: ipv6 + - + name: daddr6 + type: binary + display-hint: ipv6 + - + name: sport + type: u16 + byte-order: big-endian + - + name: dport + type: u16 + byte-order: big-endian + - + name: compound-ops + type: u32 + multi-attr: true + +operations: + list: + - + name: rpc-status-get + doc: dump pending nfsd rpc + attribute-set: rpc-status + dump: + pre: nfsd-nl-rpc-status-get-start + post: nfsd-nl-rpc-status-get-done + reply: + attributes: + - xid + - flags + - prog + - version + - proc + - service_time + - saddr4 + - daddr4 + - saddr6 + - daddr6 + - sport + - dport + - compound-ops diff --git a/Documentation/networking/device_drivers/appletalk/cops.rst b/Documentation/networking/device_drivers/appletalk/cops.rst deleted file mode 100644 index 964ba80599a9..000000000000 --- a/Documentation/networking/device_drivers/appletalk/cops.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -======================================== -The COPS LocalTalk Linux driver (cops.c) -======================================== - -By Jay Schulist <jschlst@samba.org> - -This driver has two modes and they are: Dayna mode and Tangent mode. -Each mode corresponds with the type of card. It has been found -that there are 2 main types of cards and all other cards are -the same and just have different names or only have minor differences -such as more IO ports. As this driver is tested it will -become more clear exactly what cards are supported. - -Right now these cards are known to work with the COPS driver. The -LT-200 cards work in a somewhat more limited capacity than the -DL200 cards, which work very well and are in use by many people. - -TANGENT driver mode: - - Tangent ATB-II, Novell NL-1000, Daystar Digital LT-200 - -DAYNA driver mode: - - Dayna DL2000/DaynaTalk PC (Half Length), COPS LT-95, - - Farallon PhoneNET PC III, Farallon PhoneNET PC II - -Other cards possibly supported mode unknown though: - - Dayna DL2000 (Full length) - -The COPS driver defaults to using Dayna mode. To change the driver's -mode if you built a driver with dual support use board_type=1 or -board_type=2 for Dayna or Tangent with insmod. - -Operation/loading of the driver -=============================== - -Use modprobe like this: /sbin/modprobe cops.o (IO #) (IRQ #) -If you do not specify any options the driver will try and use the IO = 0x240, -IRQ = 5. As of right now I would only use IRQ 5 for the card, if autoprobing. - -To load multiple COPS driver Localtalk cards you can do one of the following:: - - insmod cops io=0x240 irq=5 - insmod -o cops2 cops io=0x260 irq=3 - -Or in lilo.conf put something like this:: - - append="ether=5,0x240,lt0 ether=3,0x260,lt1" - -Then bring up the interface with ifconfig. It will look something like this:: - - lt0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-F7-00-00-00-00-00-00-00-00 - inet addr:192.168.1.2 Bcast:192.168.1.255 Mask:255.255.255.0 - UP BROADCAST RUNNING NOARP MULTICAST MTU:600 Metric:1 - RX packets:0 errors:0 dropped:0 overruns:0 frame:0 - TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 coll:0 - -Netatalk Configuration -====================== - -You will need to configure atalkd with something like the following to make -it work with the cops.c driver. - -* For single LTalk card use:: - - dummy -seed -phase 2 -net 2000 -addr 2000.10 -zone "1033" - lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" - -* For multiple cards, Ethernet and LocalTalk:: - - eth0 -seed -phase 2 -net 3000 -addr 3000.20 -zone "1033" - lt0 -seed -phase 1 -net 1000 -addr 1000.50 -zone "1033" - -* For multiple LocalTalk cards, and an Ethernet card. - -* Order seems to matter here, Ethernet last:: - - lt0 -seed -phase 1 -net 1000 -addr 1000.10 -zone "LocalTalk1" - lt1 -seed -phase 1 -net 2000 -addr 2000.20 -zone "LocalTalk2" - eth0 -seed -phase 2 -net 3000 -addr 3000.30 -zone "EtherTalk" diff --git a/Documentation/networking/device_drivers/appletalk/index.rst b/Documentation/networking/device_drivers/appletalk/index.rst deleted file mode 100644 index c196baeb0856..000000000000 --- a/Documentation/networking/device_drivers/appletalk/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) - -AppleTalk Device Drivers -======================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - cops - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst index 9827e816084b..43de285b8a92 100644 --- a/Documentation/networking/device_drivers/ethernet/index.rst +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -32,6 +32,7 @@ Contents: intel/e1000 intel/e1000e intel/fm10k + intel/idpf intel/igb intel/igbvf intel/ixgbe diff --git a/Documentation/networking/device_drivers/ethernet/intel/idpf.rst b/Documentation/networking/device_drivers/ethernet/intel/idpf.rst new file mode 100644 index 000000000000..adb16e2abd21 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/intel/idpf.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +========================================================================== +idpf Linux* Base Driver for the Intel(R) Infrastructure Data Path Function +========================================================================== + +Intel idpf Linux driver. +Copyright(C) 2023 Intel Corporation. + +.. contents:: + +The idpf driver serves as both the Physical Function (PF) and Virtual Function +(VF) driver for the Intel(R) Infrastructure Data Path Function. + +Driver information can be obtained using ethtool, lspci, and ip. + +For questions related to hardware requirements, refer to the documentation +supplied with your Intel adapter. All hardware requirements listed apply to use +with Linux. + + +Identifying Your Adapter +======================== +For information on how to identify your adapter, and for the latest Intel +network drivers, refer to the Intel Support website: +http://www.intel.com/support + + +Additional Features and Configurations +====================================== + +ethtool +------- +The driver utilizes the ethtool interface for driver configuration and +diagnostics, as well as displaying statistical information. The latest ethtool +version is required for this functionality. If you don't have one yet, you can +obtain it at: +https://kernel.org/pub/software/network/ethtool/ + + +Viewing Link Messages +--------------------- +Link messages will not be displayed to the console if the distribution is +restricting system messages. In order to see network driver link messages on +your console, set dmesg to eight by entering the following:: + + # dmesg -n 8 + +.. note:: + This setting is not saved across reboots. + + +Jumbo Frames +------------ +Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) +to a value larger than the default value of 1500. + +Use the ip command to increase the MTU size. For example, enter the following +where <ethX> is the interface number:: + + # ip link set mtu 9000 dev <ethX> + # ip link set up dev <ethX> + +.. note:: + The maximum MTU setting for jumbo frames is 9706. This corresponds to the + maximum jumbo frame size of 9728 bytes. + +.. note:: + This driver will attempt to use multiple page sized buffers to receive + each jumbo packet. This should help to avoid buffer starvation issues when + allocating receive packets. + +.. note:: + Packet loss may have a greater impact on throughput when you use jumbo + frames. If you observe a drop in performance after enabling jumbo frames, + enabling flow control may mitigate the issue. + + +Performance Optimization +======================== +Driver defaults are meant to fit a wide variety of workloads, but if further +optimization is required, we recommend experimenting with the following +settings. + + +Interrupt Rate Limiting +----------------------- +This driver supports an adaptive interrupt throttle rate (ITR) mechanism that +is tuned for general workloads. The user can customize the interrupt rate +control for specific workloads, via ethtool, adjusting the number of +microseconds between interrupts. + +To set the interrupt rate manually, you must disable adaptive mode:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off + +For lower CPU utilization: + - Disable adaptive ITR and lower Rx and Tx interrupts. The examples below + affect every queue of the specified interface. + + - Setting rx-usecs and tx-usecs to 80 will limit interrupts to about + 12,500 interrupts per second per queue:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 80 + tx-usecs 80 + +For reduced latency: + - Disable adaptive ITR and ITR by setting rx-usecs and tx-usecs to 0 + using ethtool:: + + # ethtool -C <ethX> adaptive-rx off adaptive-tx off rx-usecs 0 + tx-usecs 0 + +Per-queue interrupt rate settings: + - The following examples are for queues 1 and 3, but you can adjust other + queues. + + - To disable Rx adaptive ITR and set static Rx ITR to 10 microseconds or + about 100,000 interrupts/second, for queues 1 and 3:: + + # ethtool --per-queue <ethX> queue_mask 0xa --coalesce adaptive-rx off + rx-usecs 10 + + - To show the current coalesce settings for queues 1 and 3:: + + # ethtool --per-queue <ethX> queue_mask 0xa --show-coalesce + + + +Virtualized Environments +------------------------ +In addition to the other suggestions in this section, the following may be +helpful to optimize performance in VMs. + + - Using the appropriate mechanism (vcpupin) in the VM, pin the CPUs to + individual LCPUs, making sure to use a set of CPUs included in the + device's local_cpulist: /sys/class/net/<ethX>/device/local_cpulist. + + - Configure as many Rx/Tx queues in the VM as available. (See the idpf driver + documentation for the number of queues supported.) For example:: + + # ethtool -L <virt_interface> rx <max> tx <max> + + +Support +======= +For general information, go to the Intel support website at: +http://www.intel.com/support/ + +If an issue is identified with the released source code on a supported kernel +with a supported adapter, email the specific information related to the issue +to intel-wired-lan@lists.osuosl.org. + + +Trademarks +========== +Intel is a trademark or registered trademark of Intel Corporation or its +subsidiaries in the United States and/or other countries. + +* Other names and brands may be claimed as the property of others. diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst index 0a42c3395ffa..20d3b7e87049 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/kconfig.rst @@ -67,7 +67,7 @@ Enabling the driver and kconfig options | Enables :ref:`IPSec XFRM cryptography-offload acceleration <xfrm_device>`. -**CONFIG_MLX5_EN_MACSEC=(y/n)** +**CONFIG_MLX5_MACSEC=(y/n)** | Build support for MACsec cryptography-offload acceleration in the NIC. diff --git a/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst b/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst index c5673ec4559b..d731b5a98561 100644 --- a/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst +++ b/Documentation/networking/device_drivers/ethernet/neterion/s2io.rst @@ -64,8 +64,8 @@ c. Multi-buffer receive mode. Scattering of packet across multiple IBM xSeries). d. MSI/MSI-X. Can be enabled on platforms which support this feature - (IA64, Xeon) resulting in noticeable performance improvement(up to 7% - on certain platforms). + resulting in noticeable performance improvement (up to 7% on certain + platforms). e. Statistics. Comprehensive MAC-level and software statistics displayed using "ethtool -S" option. diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 601eacaf12f3..0dd30a84ce25 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -8,7 +8,6 @@ Contents: .. toctree:: :maxdepth: 2 - appletalk/index atm/index cable/index can/index @@ -16,7 +15,6 @@ Contents: ethernet/index fddi/index hamradio/index - qlogic/index wifi/index wwan/index diff --git a/Documentation/networking/device_drivers/qlogic/index.rst b/Documentation/networking/device_drivers/qlogic/index.rst deleted file mode 100644 index ad05b04286e4..000000000000 --- a/Documentation/networking/device_drivers/qlogic/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) - -QLogic QLGE Device Drivers -=============================================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - qlge - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/networking/device_drivers/qlogic/qlge.rst b/Documentation/networking/device_drivers/qlogic/qlge.rst deleted file mode 100644 index 0b888253d152..000000000000 --- a/Documentation/networking/device_drivers/qlogic/qlge.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -======================================= -QLogic QLGE 10Gb Ethernet device driver -======================================= - -This driver use drgn and devlink for debugging. - -Dump kernel data structures in drgn ------------------------------------ - -To dump kernel data structures, the following Python script can be used -in drgn: - -.. code-block:: python - - def align(x, a): - """the alignment a should be a power of 2 - """ - mask = a - 1 - return (x+ mask) & ~mask - - def struct_size(struct_type): - struct_str = "struct {}".format(struct_type) - return sizeof(Object(prog, struct_str, address=0x0)) - - def netdev_priv(netdevice): - NETDEV_ALIGN = 32 - return netdevice.value_() + align(struct_size("net_device"), NETDEV_ALIGN) - - name = 'xxx' - qlge_device = None - netdevices = prog['init_net'].dev_base_head.address_of_() - for netdevice in list_for_each_entry("struct net_device", netdevices, "dev_list"): - if netdevice.name.string_().decode('ascii') == name: - print(netdevice.name) - - ql_adapter = Object(prog, "struct ql_adapter", address=netdev_priv(qlge_device)) - -The struct ql_adapter will be printed in drgn as follows, - - >>> ql_adapter - (struct ql_adapter){ - .ricb = (struct ricb){ - .base_cq = (u8)0, - .flags = (u8)120, - .mask = (__le16)26637, - .hash_cq_id = (u8 [1024]){ 172, 142, 255, 255 }, - .ipv6_hash_key = (__le32 [10]){}, - .ipv4_hash_key = (__le32 [4]){}, - }, - .flags = (unsigned long)0, - .wol = (u32)0, - .nic_stats = (struct nic_stats){ - .tx_pkts = (u64)0, - .tx_bytes = (u64)0, - .tx_mcast_pkts = (u64)0, - .tx_bcast_pkts = (u64)0, - .tx_ucast_pkts = (u64)0, - .tx_ctl_pkts = (u64)0, - .tx_pause_pkts = (u64)0, - ... - }, - .active_vlans = (unsigned long [64]){ - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 52780853100545, 18446744073709551615, - 18446619461681283072, 0, 42949673024, 2147483647, - }, - .rx_ring = (struct rx_ring [17]){ - { - .cqicb = (struct cqicb){ - .msix_vect = (u8)0, - .reserved1 = (u8)0, - .reserved2 = (u8)0, - .flags = (u8)0, - .len = (__le16)0, - .rid = (__le16)0, - ... - }, - .cq_base = (void *)0x0, - .cq_base_dma = (dma_addr_t)0, - } - ... - } - } - -coredump via devlink --------------------- - - -And the coredump obtained via devlink in json format looks like, - -.. code:: shell - - $ devlink health dump show DEVICE reporter coredump -p -j - { - "Core Registers": { - "segment": 1, - "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] - }, - "Test Logic Regs": { - "segment": 2, - "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] - }, - "RMII Registers": { - "segment": 3, - "values": [ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] - }, - ... - "Sem Registers": { - "segment": 50, - "values": [ 0,0,0,0 ] - } - } - -When the module parameter qlge_force_coredump is set to be true, the MPI -RISC reset before coredumping. So coredumping will much longer since -devlink tool has to wait for 5 secs for the resetting to be -finished. diff --git a/Documentation/networking/devlink/i40e.rst b/Documentation/networking/devlink/i40e.rst new file mode 100644 index 000000000000..d3cb5bb5197e --- /dev/null +++ b/Documentation/networking/devlink/i40e.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +i40e devlink support +==================== + +This document describes the devlink features implemented by the ``i40e`` +device driver. + +Info versions +============= + +The ``i40e`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 5 90 + + * - Name + - Type + - Example + - Description + * - ``board.id`` + - fixed + - K15190-000 + - The Product Board Assembly (PBA) identifier of the board. + * - ``fw.mgmt`` + - running + - 9.130 + - 2-digit version number of the management firmware that controls the + PHY, link, etc. + * - ``fw.mgmt.api`` + - running + - 1.15 + - 2-digit version number of the API exported over the AdminQ by the + management firmware. Used by the driver to identify what commands + are supported. + * - ``fw.mgmt.build`` + - running + - 73618 + - Build number of the source for the management firmware. + * - ``fw.undi`` + - running + - 1.3429.0 + - Version of the Option ROM containing the UEFI driver. The version is + reported in ``major.minor.patch`` format. The major version is + incremented whenever a major breaking change occurs, or when the + minor version would overflow. The minor version is incremented for + non-breaking changes and reset to 1 when the major version is + incremented. The patch version is normally 0 but is incremented when + a fix is delivered as a patch against an older base Option ROM. + * - ``fw.psid.api`` + - running + - 9.30 + - Version defining the format of the flash contents. + * - ``fw.bundle_id`` + - running + - 0x8000e5f3 + - Unique identifier of the firmware image file that was loaded onto + the device. Also referred to as the EETRACK identifier of the NVM. diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index b49749e2b9a6..e14d7a701b72 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -18,6 +18,34 @@ netlink commands. Drivers are encouraged to use the devlink instance lock for their own needs. +Drivers need to be cautious when taking devlink instance lock and +taking RTNL lock at the same time. Devlink instance lock needs to be taken +first, only after that RTNL lock could be taken. + +Nested instances +---------------- + +Some objects, like linecards or port functions, could have another +devlink instances created underneath. In that case, drivers should make +sure to respect following rules: + + - Lock ordering should be maintained. If driver needs to take instance + lock of both nested and parent instances at the same time, devlink + instance lock of the parent instance should be taken first, only then + instance lock of the nested instance could be taken. + - Driver should use object-specific helpers to setup the + nested relationship: + + - ``devl_nested_devlink_set()`` - called to setup devlink -> nested + devlink relationship (could be user for multiple nested instances. + - ``devl_port_fn_devlink_set()`` - called to setup port function -> + nested devlink relationship. + - ``devlink_linecard_nested_dl_set()`` - called to setup linecard -> + nested devlink relationship. + +The nested devlink info is exposed to the userspace over object-specific +attributes of devlink netlink. + Interface documentation ----------------------- @@ -52,6 +80,7 @@ parameters, info versions, and other features it supports. bnxt etas_es58x hns3 + i40e ionic ice mlx4 diff --git a/Documentation/networking/dsa/b53.rst b/Documentation/networking/dsa/b53.rst index b41637cdb82b..1cb3ff648f88 100644 --- a/Documentation/networking/dsa/b53.rst +++ b/Documentation/networking/dsa/b53.rst @@ -52,7 +52,7 @@ VLAN programming would basically change the CPU port's default PVID and make it untagged, undesirable. In difference to the configuration described in :ref:`dsa-vlan-configuration` -the default VLAN 1 has to be removed from the slave interface configuration in +the default VLAN 1 has to be removed from the user interface configuration in single port and gateway configuration, while there is no need to add an extra VLAN configuration in the bridge showcase. @@ -68,13 +68,13 @@ By default packages are tagged with vid 1: ip link add link eth0 name eth0.2 type vlan id 2 ip link add link eth0 name eth0.3 type vlan id 3 - # The master interface needs to be brought up before the slave ports. + # The conduit interface needs to be brought up before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up ip link set eth0.3 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -113,11 +113,11 @@ bridge # tag traffic on CPU port ip link add link eth0 name eth0.1 type vlan id 1 - # The master interface needs to be brought up before the slave ports. + # The conduit interface needs to be brought up before the user ports. ip link set eth0 up ip link set eth0.1 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -149,12 +149,12 @@ gateway ip link add link eth0 name eth0.1 type vlan id 1 ip link add link eth0 name eth0.2 type vlan id 2 - # The master interface needs to be brought up before the slave ports. + # The conduit interface needs to be brought up before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up diff --git a/Documentation/networking/dsa/bcm_sf2.rst b/Documentation/networking/dsa/bcm_sf2.rst index dee234039e1e..d2571435696f 100644 --- a/Documentation/networking/dsa/bcm_sf2.rst +++ b/Documentation/networking/dsa/bcm_sf2.rst @@ -67,7 +67,7 @@ MDIO indirect accesses ---------------------- Due to a limitation in how Broadcom switches have been designed, external -Broadcom switches connected to a SF2 require the use of the DSA slave MDIO bus +Broadcom switches connected to a SF2 require the use of the DSA user MDIO bus in order to properly configure them. By default, the SF2 pseudo-PHY address, and an external switch pseudo-PHY address will both be snooping for incoming MDIO transactions, since they are at the same address (30), resulting in some kind of diff --git a/Documentation/networking/dsa/configuration.rst b/Documentation/networking/dsa/configuration.rst index d2934c40f0f1..6cc4ded3cc23 100644 --- a/Documentation/networking/dsa/configuration.rst +++ b/Documentation/networking/dsa/configuration.rst @@ -31,38 +31,38 @@ at https://www.kernel.org/pub/linux/utils/net/iproute2/ Through DSA every port of a switch is handled like a normal linux Ethernet interface. The CPU port is the switch port connected to an Ethernet MAC chip. -The corresponding linux Ethernet interface is called the master interface. -All other corresponding linux interfaces are called slave interfaces. +The corresponding linux Ethernet interface is called the conduit interface. +All other corresponding linux interfaces are called user interfaces. -The slave interfaces depend on the master interface being up in order for them -to send or receive traffic. Prior to kernel v5.12, the state of the master +The user interfaces depend on the conduit interface being up in order for them +to send or receive traffic. Prior to kernel v5.12, the state of the conduit interface had to be managed explicitly by the user. Starting with kernel v5.12, the behavior is as follows: -- when a DSA slave interface is brought up, the master interface is +- when a DSA user interface is brought up, the conduit interface is automatically brought up. -- when the master interface is brought down, all DSA slave interfaces are +- when the conduit interface is brought down, all DSA user interfaces are automatically brought down. In this documentation the following Ethernet interfaces are used: *eth0* - the master interface + the conduit interface *eth1* - another master interface + another conduit interface *lan1* - a slave interface + a user interface *lan2* - another slave interface + another user interface *lan3* - a third slave interface + a third user interface *wan* - A slave interface dedicated for upstream traffic + A user interface dedicated for upstream traffic Further Ethernet interfaces can be configured similar. The configured IPs and networks are: @@ -96,11 +96,11 @@ without using a VLAN based configuration. ip addr add 192.0.2.5/30 dev lan2 ip addr add 192.0.2.9/30 dev lan3 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -108,11 +108,11 @@ without using a VLAN based configuration. *bridge* .. code-block:: sh - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -134,11 +134,11 @@ without using a VLAN based configuration. *gateway* .. code-block:: sh - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -178,14 +178,14 @@ configuration. ip link add link eth0 name eth0.2 type vlan id 2 ip link add link eth0 name eth0.3 type vlan id 3 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up ip link set eth0.3 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -221,12 +221,12 @@ configuration. # tag traffic on CPU port ip link add link eth0 name eth0.1 type vlan id 1 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up ip link set eth0.1 up - # bring up the slave interfaces + # bring up the user interfaces ip link set lan1 up ip link set lan2 up ip link set lan3 up @@ -261,13 +261,13 @@ configuration. ip link add link eth0 name eth0.1 type vlan id 1 ip link add link eth0 name eth0.2 type vlan id 2 - # For kernels earlier than v5.12, the master interface needs to be - # brought up manually before the slave ports. + # For kernels earlier than v5.12, the conduit interface needs to be + # brought up manually before the user ports. ip link set eth0 up ip link set eth0.1 up ip link set eth0.2 up - # bring up the slave interfaces + # bring up the user interfaces ip link set wan up ip link set lan1 up ip link set lan2 up @@ -380,22 +380,22 @@ affinities according to the available CPU ports. Secondly, it is possible to perform load balancing between CPU ports on a per packet basis, rather than statically assigning user ports to CPU ports. -This can be achieved by placing the DSA masters under a LAG interface (bonding +This can be achieved by placing the DSA conduits under a LAG interface (bonding or team). DSA monitors this operation and creates a mirror of this software LAG -on the CPU ports facing the physical DSA masters that constitute the LAG slave +on the CPU ports facing the physical DSA conduits that constitute the LAG slave devices. To make use of multiple CPU ports, the firmware (device tree) description of -the switch must mark all the links between CPU ports and their DSA masters +the switch must mark all the links between CPU ports and their DSA conduits using the ``ethernet`` reference/phandle. At startup, only a single CPU port -and DSA master will be used - the numerically first port from the firmware +and DSA conduit will be used - the numerically first port from the firmware description which has an ``ethernet`` property. It is up to the user to -configure the system for the switch to use other masters. +configure the system for the switch to use other conduits. DSA uses the ``rtnl_link_ops`` mechanism (with a "dsa" ``kind``) to allow -changing the DSA master of a user port. The ``IFLA_DSA_MASTER`` u32 netlink -attribute contains the ifindex of the master device that handles each slave -device. The DSA master must be a valid candidate based on firmware node +changing the DSA conduit of a user port. The ``IFLA_DSA_CONDUIT`` u32 netlink +attribute contains the ifindex of the conduit device that handles each user +device. The DSA conduit must be a valid candidate based on firmware node information, or a LAG interface which contains only slaves which are valid candidates. @@ -403,7 +403,7 @@ Using iproute2, the following manipulations are possible: .. code-block:: sh - # See the DSA master in current use + # See the DSA conduit in current use ip -d link show dev swp0 (...) dsa master eth0 @@ -414,7 +414,7 @@ Using iproute2, the following manipulations are possible: ip link set swp2 type dsa master eth1 ip link set swp3 type dsa master eth0 - # CPU ports in LAG, using explicit assignment of the DSA master + # CPU ports in LAG, using explicit assignment of the DSA conduit ip link add bond0 type bond mode balance-xor && ip link set bond0 up ip link set eth1 down && ip link set eth1 master bond0 ip link set swp0 type dsa master bond0 @@ -426,7 +426,7 @@ Using iproute2, the following manipulations are possible: (...) dsa master bond0 - # CPU ports in LAG, relying on implicit migration of the DSA master + # CPU ports in LAG, relying on implicit migration of the DSA conduit ip link add bond0 type bond mode balance-xor && ip link set bond0 up ip link set eth0 down && ip link set eth0 master bond0 ip link set eth1 down && ip link set eth1 master bond0 @@ -435,24 +435,24 @@ Using iproute2, the following manipulations are possible: dsa master bond0 Notice that in the case of CPU ports under a LAG, the use of the -``IFLA_DSA_MASTER`` netlink attribute is not strictly needed, but rather, DSA -reacts to the ``IFLA_MASTER`` attribute change of its present master (``eth0``) +``IFLA_DSA_CONDUIT`` netlink attribute is not strictly needed, but rather, DSA +reacts to the ``IFLA_MASTER`` attribute change of its present conduit (``eth0``) and migrates all user ports to the new upper of ``eth0``, ``bond0``. Similarly, when ``bond0`` is destroyed using ``RTM_DELLINK``, DSA migrates the user ports -that were assigned to this interface to the first physical DSA master which is +that were assigned to this interface to the first physical DSA conduit which is eligible, based on the firmware description (it effectively reverts to the startup configuration). In a setup with more than 2 physical CPU ports, it is therefore possible to mix -static user to CPU port assignment with LAG between DSA masters. It is not -possible to statically assign a user port towards a DSA master that has any -upper interfaces (this includes LAG devices - the master must always be the LAG +static user to CPU port assignment with LAG between DSA conduits. It is not +possible to statically assign a user port towards a DSA conduit that has any +upper interfaces (this includes LAG devices - the conduit must always be the LAG in this case). -Live changing of the DSA master (and thus CPU port) affinity of a user port is +Live changing of the DSA conduit (and thus CPU port) affinity of a user port is permitted, in order to allow dynamic redistribution in response to traffic. -Physical DSA masters are allowed to join and leave at any time a LAG interface -used as a DSA master; however, DSA will reject a LAG interface as a valid -candidate for being a DSA master unless it has at least one physical DSA master +Physical DSA conduits are allowed to join and leave at any time a LAG interface +used as a DSA conduit; however, DSA will reject a LAG interface as a valid +candidate for being a DSA conduit unless it has at least one physical DSA conduit as a slave device. diff --git a/Documentation/networking/dsa/dsa.rst b/Documentation/networking/dsa/dsa.rst index a94ddf83348a..7b2e69cd7ef0 100644 --- a/Documentation/networking/dsa/dsa.rst +++ b/Documentation/networking/dsa/dsa.rst @@ -25,7 +25,7 @@ presence of a management port connected to an Ethernet controller capable of receiving Ethernet frames from the switch. This is a very common setup for all kinds of Ethernet switches found in Small Home and Office products: routers, gateways, or even top-of-rack switches. This host Ethernet controller will -be later referred to as "master" and "cpu" in DSA terminology and code. +be later referred to as "conduit" and "cpu" in DSA terminology and code. The D in DSA stands for Distributed, because the subsystem has been designed with the ability to configure and manage cascaded switches on top of each other @@ -35,7 +35,7 @@ of multiple switches connected to each other is called a "switch tree". For each front-panel port, DSA creates specialized network devices which are used as controlling and data-flowing endpoints for use by the Linux networking -stack. These specialized network interfaces are referred to as "slave" network +stack. These specialized network interfaces are referred to as "user" network interfaces in DSA terminology and code. The ideal case for using DSA is when an Ethernet switch supports a "switch tag" @@ -56,12 +56,16 @@ Note that DSA does not currently create network interfaces for the "cpu" and - the "cpu" port is the Ethernet switch facing side of the management controller, and as such, would create a duplication of feature, since you - would get two interfaces for the same conduit: master netdev, and "cpu" netdev + would get two interfaces for the same conduit: conduit netdev, and "cpu" netdev - the "dsa" port(s) are just conduits between two or more switches, and as such cannot really be used as proper network interfaces either, only the downstream, or the top-most upstream interface makes sense with that model +NB: for the past 15 years, the DSA subsystem had been making use of the terms +"master" (rather than "conduit") and "slave" (rather than "user"). These terms +have been removed from the DSA codebase and phased out of the uAPI. + Switch tagging protocols ------------------------ @@ -80,14 +84,14 @@ methods of the ``struct dsa_device_ops`` structure, which are detailed below. Tagging protocols generally fall in one of three categories: 1. The switch-specific frame header is located before the Ethernet header, - shifting to the right (from the perspective of the DSA master's frame + shifting to the right (from the perspective of the DSA conduit's frame parser) the MAC DA, MAC SA, EtherType and the entire L2 payload. 2. The switch-specific frame header is located before the EtherType, keeping - the MAC DA and MAC SA in place from the DSA master's perspective, but + the MAC DA and MAC SA in place from the DSA conduit's perspective, but shifting the 'real' EtherType and L2 payload to the right. 3. The switch-specific frame header is located at the tail of the packet, keeping all frame headers in place and not altering the view of the packet - that the DSA master's frame parser has. + that the DSA conduit's frame parser has. A tagging protocol may tag all packets with switch tags of the same length, or the tag length might vary (for example packets with PTP timestamps might @@ -95,7 +99,7 @@ require an extended switch tag, or there might be one tag length on TX and a different one on RX). Either way, the tagging protocol driver must populate the ``struct dsa_device_ops::needed_headroom`` and/or ``struct dsa_device_ops::needed_tailroom`` with the length in octets of the longest switch frame header/trailer. The DSA -framework will automatically adjust the MTU of the master interface to +framework will automatically adjust the MTU of the conduit interface to accommodate for this extra size in order for DSA user ports to support the standard MTU (L2 payload length) of 1500 octets. The ``needed_headroom`` and ``needed_tailroom`` properties are also used to request from the network stack, @@ -140,18 +144,18 @@ adding or removing the ``ETH_P_EDSA`` EtherType and some padding octets). It is possible to construct cascaded setups of DSA switches even if their tagging protocols are not compatible with one another. In this case, there are no DSA links in this fabric, and each switch constitutes a disjoint DSA switch -tree. The DSA links are viewed as simply a pair of a DSA master (the out-facing +tree. The DSA links are viewed as simply a pair of a DSA conduit (the out-facing port of the upstream DSA switch) and a CPU port (the in-facing port of the downstream DSA switch). The tagging protocol of the attached DSA switch tree can be viewed through the -``dsa/tagging`` sysfs attribute of the DSA master:: +``dsa/tagging`` sysfs attribute of the DSA conduit:: cat /sys/class/net/eth0/dsa/tagging If the hardware and driver are capable, the tagging protocol of the DSA switch tree can be changed at runtime. This is done by writing the new tagging -protocol name to the same sysfs device attribute as above (the DSA master and +protocol name to the same sysfs device attribute as above (the DSA conduit and all attached switch ports must be down while doing this). It is desirable that all tagging protocols are testable with the ``dsa_loop`` @@ -159,7 +163,7 @@ mockup driver, which can be attached to any network interface. The goal is that any network interface should be capable of transmitting the same packet in the same way, and the tagger should decode the same received packet in the same way regardless of the driver used for the switch control path, and the driver used -for the DSA master. +for the DSA conduit. The transmission of a packet goes through the tagger's ``xmit`` function. The passed ``struct sk_buff *skb`` has ``skb->data`` pointing at @@ -183,44 +187,44 @@ virtual DSA user network interface corresponding to the physical front-facing switch port that the packet was received on. Since tagging protocols in category 1 and 2 break software (and most often also -hardware) packet dissection on the DSA master, features such as RPS (Receive -Packet Steering) on the DSA master would be broken. The DSA framework deals +hardware) packet dissection on the DSA conduit, features such as RPS (Receive +Packet Steering) on the DSA conduit would be broken. The DSA framework deals with this by hooking into the flow dissector and shifting the offset at which -the IP header is to be found in the tagged frame as seen by the DSA master. +the IP header is to be found in the tagged frame as seen by the DSA conduit. This behavior is automatic based on the ``overhead`` value of the tagging protocol. If not all packets are of equal size, the tagger can implement the ``flow_dissect`` method of the ``struct dsa_device_ops`` and override this default behavior by specifying the correct offset incurred by each individual RX packet. Tail taggers do not cause issues to the flow dissector. -Checksum offload should work with category 1 and 2 taggers when the DSA master +Checksum offload should work with category 1 and 2 taggers when the DSA conduit driver declares NETIF_F_HW_CSUM in vlan_features and looks at csum_start and csum_offset. For those cases, DSA will shift the checksum start and offset by -the tag size. If the DSA master driver still uses the legacy NETIF_F_IP_CSUM +the tag size. If the DSA conduit driver still uses the legacy NETIF_F_IP_CSUM or NETIF_F_IPV6_CSUM in vlan_features, the offload might only work if the offload hardware already expects that specific tag (perhaps due to matching -vendors). DSA slaves inherit those flags from the master port, and it is up to +vendors). DSA user ports inherit those flags from the conduit, and it is up to the driver to correctly fall back to software checksum when the IP header is not where the hardware expects. If that check is ineffective, the packets might go to the network without a proper checksum (the checksum field will have the pseudo IP header sum). For category 3, when the offload hardware does not already expect the switch tag in use, the checksum must be calculated before any -tag is inserted (i.e. inside the tagger). Otherwise, the DSA master would +tag is inserted (i.e. inside the tagger). Otherwise, the DSA conduit would include the tail tag in the (software or hardware) checksum calculation. Then, when the tag gets stripped by the switch during transmission, it will leave an incorrect IP checksum in place. Due to various reasons (most common being category 1 taggers being associated -with DSA-unaware masters, mangling what the master perceives as MAC DA), the -tagging protocol may require the DSA master to operate in promiscuous mode, to +with DSA-unaware conduits, mangling what the conduit perceives as MAC DA), the +tagging protocol may require the DSA conduit to operate in promiscuous mode, to receive all frames regardless of the value of the MAC DA. This can be done by -setting the ``promisc_on_master`` property of the ``struct dsa_device_ops``. -Note that this assumes a DSA-unaware master driver, which is the norm. +setting the ``promisc_on_conduit`` property of the ``struct dsa_device_ops``. +Note that this assumes a DSA-unaware conduit driver, which is the norm. -Master network devices ----------------------- +Conduit network devices +----------------------- -Master network devices are regular, unmodified Linux network device drivers for +Conduit network devices are regular, unmodified Linux network device drivers for the CPU/management Ethernet interface. Such a driver might occasionally need to know whether DSA is enabled (e.g.: to enable/disable specific offload features), but the DSA subsystem has been proven to work with industry standard drivers: @@ -232,14 +236,14 @@ Ethernet switch. Networking stack hooks ---------------------- -When a master netdev is used with DSA, a small hook is placed in the +When a conduit netdev is used with DSA, a small hook is placed in the networking stack is in order to have the DSA subsystem process the Ethernet switch specific tagging protocol. DSA accomplishes this by registering a specific (and fake) Ethernet type (later becoming ``skb->protocol``) with the networking stack, this is also known as a ``ptype`` or ``packet_type``. A typical Ethernet Frame receive sequence looks like this: -Master network device (e.g.: e1000e): +Conduit network device (e.g.: e1000e): 1. Receive interrupt fires: @@ -269,16 +273,16 @@ Master network device (e.g.: e1000e): - inspect and strip switch tag protocol to determine originating port - locate per-port network device - - invoke ``eth_type_trans()`` with the DSA slave network device + - invoke ``eth_type_trans()`` with the DSA user network device - invoked ``netif_receive_skb()`` -Past this point, the DSA slave network devices get delivered regular Ethernet +Past this point, the DSA user network devices get delivered regular Ethernet frames that can be processed by the networking stack. -Slave network devices ---------------------- +User network devices +-------------------- -Slave network devices created by DSA are stacked on top of their master network +User network devices created by DSA are stacked on top of their conduit network device, each of these network interfaces will be responsible for being a controlling and data-flowing end-point for each front-panel port of the switch. These interfaces are specialized in order to: @@ -289,31 +293,31 @@ These interfaces are specialized in order to: Wake-on-LAN, register dumps... - manage external/internal PHY: link, auto-negotiation, etc. -These slave network devices have custom net_device_ops and ethtool_ops function +These user network devices have custom net_device_ops and ethtool_ops function pointers which allow DSA to introduce a level of layering between the networking stack/ethtool and the switch driver implementation. -Upon frame transmission from these slave network devices, DSA will look up which +Upon frame transmission from these user network devices, DSA will look up which switch tagging protocol is currently registered with these network devices and invoke a specific transmit routine which takes care of adding the relevant switch tag in the Ethernet frames. -These frames are then queued for transmission using the master network device +These frames are then queued for transmission using the conduit network device ``ndo_start_xmit()`` function. Since they contain the appropriate switch tag, the Ethernet switch will be able to process these incoming frames from the management interface and deliver them to the physical switch port. When using multiple CPU ports, it is possible to stack a LAG (bonding/team) -device between the DSA slave devices and the physical DSA masters. The LAG -device is thus also a DSA master, but the LAG slave devices continue to be DSA -masters as well (just with no user port assigned to them; this is needed for -recovery in case the LAG DSA master disappears). Thus, the data path of the LAG -DSA master is used asymmetrically. On RX, the ``ETH_P_XDSA`` handler, which -calls ``dsa_switch_rcv()``, is invoked early (on the physical DSA master; -LAG slave). Therefore, the RX data path of the LAG DSA master is not used. -On the other hand, TX takes place linearly: ``dsa_slave_xmit`` calls -``dsa_enqueue_skb``, which calls ``dev_queue_xmit`` towards the LAG DSA master. -The latter calls ``dev_queue_xmit`` towards one physical DSA master or the +device between the DSA user devices and the physical DSA conduits. The LAG +device is thus also a DSA conduit, but the LAG slave devices continue to be DSA +conduits as well (just with no user port assigned to them; this is needed for +recovery in case the LAG DSA conduit disappears). Thus, the data path of the LAG +DSA conduit is used asymmetrically. On RX, the ``ETH_P_XDSA`` handler, which +calls ``dsa_switch_rcv()``, is invoked early (on the physical DSA conduit; +LAG slave). Therefore, the RX data path of the LAG DSA conduit is not used. +On the other hand, TX takes place linearly: ``dsa_user_xmit`` calls +``dsa_enqueue_skb``, which calls ``dev_queue_xmit`` towards the LAG DSA conduit. +The latter calls ``dev_queue_xmit`` towards one physical DSA conduit or the other, and in both cases, the packet exits the system through a hardware path towards the switch. @@ -352,11 +356,11 @@ perspective:: || swp0 | | swp1 | | swp2 | | swp3 || ++------+-+------+-+------+-+------++ -Slave MDIO bus --------------- +User MDIO bus +------------- -In order to be able to read to/from a switch PHY built into it, DSA creates a -slave MDIO bus which allows a specific switch driver to divert and intercept +In order to be able to read to/from a switch PHY built into it, DSA creates an +user MDIO bus which allows a specific switch driver to divert and intercept MDIO reads/writes towards specific PHY addresses. In most MDIO-connected switches, these functions would utilize direct or indirect PHY addressing mode to return standard MII registers from the switch builtin PHYs, allowing the PHY @@ -364,7 +368,7 @@ library and/or to return link status, link partner pages, auto-negotiation results, etc. For Ethernet switches which have both external and internal MDIO buses, the -slave MII bus can be utilized to mux/demux MDIO reads and writes towards either +user MII bus can be utilized to mux/demux MDIO reads and writes towards either internal or external MDIO devices this switch might be connected to: internal PHYs, external PHYs, or even external switches. @@ -381,10 +385,10 @@ DSA data structures are defined in ``include/net/dsa.h`` as well as - ``dsa_platform_data``: platform device configuration data which can reference a collection of dsa_chip_data structures if multiple switches are cascaded, - the master network device this switch tree is attached to needs to be + the conduit network device this switch tree is attached to needs to be referenced -- ``dsa_switch_tree``: structure assigned to the master network device under +- ``dsa_switch_tree``: structure assigned to the conduit network device under ``dsa_ptr``, this structure references a dsa_platform_data structure as well as the tagging protocol supported by the switch tree, and which receive/transmit function hooks should be invoked, information about the directly attached @@ -392,7 +396,7 @@ DSA data structures are defined in ``include/net/dsa.h`` as well as referenced to address individual switches in the tree. - ``dsa_switch``: structure describing a switch device in the tree, referencing - a ``dsa_switch_tree`` as a backpointer, slave network devices, master network + a ``dsa_switch_tree`` as a backpointer, user network devices, conduit network device, and a reference to the backing``dsa_switch_ops`` - ``dsa_switch_ops``: structure referencing function pointers, see below for a @@ -404,7 +408,7 @@ Design limitations Lack of CPU/DSA network devices ------------------------------- -DSA does not currently create slave network devices for the CPU or DSA ports, as +DSA does not currently create user network devices for the CPU or DSA ports, as described before. This might be an issue in the following cases: - inability to fetch switch CPU port statistics counters using ethtool, which @@ -419,7 +423,7 @@ described before. This might be an issue in the following cases: Common pitfalls using DSA setups -------------------------------- -Once a master network device is configured to use DSA (dev->dsa_ptr becomes +Once a conduit network device is configured to use DSA (dev->dsa_ptr becomes non-NULL), and the switch behind it expects a tagging protocol, this network interface can only exclusively be used as a conduit interface. Sending packets directly through this interface (e.g.: opening a socket using this interface) @@ -440,7 +444,7 @@ DSA currently leverages the following subsystems: MDIO/PHY library ---------------- -Slave network devices exposed by DSA may or may not be interfacing with PHY +User network devices exposed by DSA may or may not be interfacing with PHY devices (``struct phy_device`` as defined in ``include/linux/phy.h)``, but the DSA subsystem deals with all possible combinations: @@ -450,7 +454,7 @@ subsystem deals with all possible combinations: - special, non-autonegotiated or non MDIO-managed PHY devices: SFPs, MoCA; a.k.a fixed PHYs -The PHY configuration is done by the ``dsa_slave_phy_setup()`` function and the +The PHY configuration is done by the ``dsa_user_phy_setup()`` function and the logic basically looks like this: - if Device Tree is used, the PHY device is looked up using the standard @@ -463,7 +467,7 @@ logic basically looks like this: and connected transparently using the special fixed MDIO bus driver - finally, if the PHY is built into the switch, as is very common with - standalone switch packages, the PHY is probed using the slave MII bus created + standalone switch packages, the PHY is probed using the user MII bus created by DSA @@ -472,7 +476,7 @@ SWITCHDEV DSA directly utilizes SWITCHDEV when interfacing with the bridge layer, and more specifically with its VLAN filtering portion when configuring VLANs on top -of per-port slave network devices. As of today, the only SWITCHDEV objects +of per-port user network devices. As of today, the only SWITCHDEV objects supported by DSA are the FDB and VLAN objects. Devlink @@ -589,8 +593,8 @@ is torn down when the first switch unregisters. It is mandatory for DSA switch drivers to implement the ``shutdown()`` callback of their respective bus, and call ``dsa_switch_shutdown()`` from it (a minimal version of the full teardown performed by ``dsa_unregister_switch()``). -The reason is that DSA keeps a reference on the master net device, and if the -driver for the master device decides to unbind on shutdown, DSA's reference +The reason is that DSA keeps a reference on the conduit net device, and if the +driver for the conduit device decides to unbind on shutdown, DSA's reference will block that operation from finalizing. Either ``dsa_switch_shutdown()`` or ``dsa_unregister_switch()`` must be called, @@ -615,7 +619,7 @@ Switch configuration tag formats. - ``change_tag_protocol``: when the default tagging protocol has compatibility - problems with the master or other issues, the driver may support changing it + problems with the conduit or other issues, the driver may support changing it at runtime, either through a device tree property or through sysfs. In that case, further calls to ``get_tag_protocol`` should report the protocol in current use. @@ -643,22 +647,22 @@ Switch configuration PHY cannot be found. In this case, probing of the DSA switch continues without that particular port. -- ``port_change_master``: method through which the affinity (association used +- ``port_change_conduit``: method through which the affinity (association used for traffic termination purposes) between a user port and a CPU port can be changed. By default all user ports from a tree are assigned to the first available CPU port that makes sense for them (most of the times this means the user ports of a tree are all assigned to the same CPU port, except for H topologies as described in commit 2c0b03258b8b). The ``port`` argument - represents the index of the user port, and the ``master`` argument represents - the new DSA master ``net_device``. The CPU port associated with the new - master can be retrieved by looking at ``struct dsa_port *cpu_dp = - master->dsa_ptr``. Additionally, the master can also be a LAG device where - all the slave devices are physical DSA masters. LAG DSA masters also have a - valid ``master->dsa_ptr`` pointer, however this is not unique, but rather a - duplicate of the first physical DSA master's (LAG slave) ``dsa_ptr``. In case - of a LAG DSA master, a further call to ``port_lag_join`` will be emitted + represents the index of the user port, and the ``conduit`` argument represents + the new DSA conduit ``net_device``. The CPU port associated with the new + conduit can be retrieved by looking at ``struct dsa_port *cpu_dp = + conduit->dsa_ptr``. Additionally, the conduit can also be a LAG device where + all the slave devices are physical DSA conduits. LAG DSA also have a + valid ``conduit->dsa_ptr`` pointer, however this is not unique, but rather a + duplicate of the first physical DSA conduit's (LAG slave) ``dsa_ptr``. In case + of a LAG DSA conduit, a further call to ``port_lag_join`` will be emitted separately for the physical CPU ports associated with the physical DSA - masters, requesting them to create a hardware LAG associated with the LAG + conduits, requesting them to create a hardware LAG associated with the LAG interface. PHY devices and link management @@ -670,16 +674,16 @@ PHY devices and link management should return a 32-bit bitmask of "flags" that is private between the switch driver and the Ethernet PHY driver in ``drivers/net/phy/\*``. -- ``phy_read``: Function invoked by the DSA slave MDIO bus when attempting to read +- ``phy_read``: Function invoked by the DSA user MDIO bus when attempting to read the switch port MDIO registers. If unavailable, return 0xffff for each read. For builtin switch Ethernet PHYs, this function should allow reading the link status, auto-negotiation results, link partner pages, etc. -- ``phy_write``: Function invoked by the DSA slave MDIO bus when attempting to write +- ``phy_write``: Function invoked by the DSA user MDIO bus when attempting to write to the switch port MDIO registers. If unavailable return a negative error code. -- ``adjust_link``: Function invoked by the PHY library when a slave network device +- ``adjust_link``: Function invoked by the PHY library when a user network device is attached to a PHY device. This function is responsible for appropriately configuring the switch port link parameters: speed, duplex, pause based on what the ``phy_device`` is providing. @@ -698,14 +702,14 @@ Ethtool operations typically return statistics strings, private flags strings, etc. - ``get_ethtool_stats``: ethtool function used to query per-port statistics and - return their values. DSA overlays slave network devices general statistics: + return their values. DSA overlays user network devices general statistics: RX/TX counters from the network device, with switch driver specific statistics per port - ``get_sset_count``: ethtool function used to query the number of statistics items - ``get_wol``: ethtool function used to obtain Wake-on-LAN settings per-port, this - function may for certain implementations also query the master network device + function may for certain implementations also query the conduit network device Wake-on-LAN settings if this interface needs to participate in Wake-on-LAN - ``set_wol``: ethtool function used to configure Wake-on-LAN settings per-port, @@ -747,13 +751,13 @@ Power management should resume all Ethernet switch activities and re-configure the switch to be in a fully active state -- ``port_enable``: function invoked by the DSA slave network device ndo_open +- ``port_enable``: function invoked by the DSA user network device ndo_open function when a port is administratively brought up, this function should fully enable a given switch port. DSA takes care of marking the port with ``BR_STATE_BLOCKING`` if the port is a bridge member, or ``BR_STATE_FORWARDING`` if it was not, and propagating these changes down to the hardware -- ``port_disable``: function invoked by the DSA slave network device ndo_close +- ``port_disable``: function invoked by the DSA user network device ndo_close function when a port is administratively brought down, this function should fully disable a given switch port. DSA takes care of marking the port with ``BR_STATE_DISABLED`` and propagating changes to the hardware if this port is diff --git a/Documentation/networking/dsa/lan9303.rst b/Documentation/networking/dsa/lan9303.rst index e3c820db28ad..ab81b4e0139e 100644 --- a/Documentation/networking/dsa/lan9303.rst +++ b/Documentation/networking/dsa/lan9303.rst @@ -4,7 +4,7 @@ LAN9303 Ethernet switch driver The LAN9303 is a three port 10/100 Mbps ethernet switch with integrated phys for the two external ethernet ports. The third port is an RMII/MII interface to a -host master network interface (e.g. fixed link). +host conduit network interface (e.g. fixed link). Driver details diff --git a/Documentation/networking/dsa/sja1105.rst b/Documentation/networking/dsa/sja1105.rst index e0219c1452ab..8ab60eef07d4 100644 --- a/Documentation/networking/dsa/sja1105.rst +++ b/Documentation/networking/dsa/sja1105.rst @@ -79,7 +79,7 @@ The hardware tags all traffic internally with a port-based VLAN (pvid), or it decodes the VLAN information from the 802.1Q tag. Advanced VLAN classification is not possible. Once attributed a VLAN tag, frames are checked against the port's membership rules and dropped at ingress if they don't match any VLAN. -This behavior is available when switch ports are enslaved to a bridge with +This behavior is available when switch ports join a bridge with ``vlan_filtering 1``. Normally the hardware is not configurable with respect to VLAN awareness, but @@ -122,7 +122,7 @@ on egress. Using ``vlan_filtering=1``, the behavior is the other way around: offloaded flows can be steered to TX queues based on the VLAN PCP, but the DSA net devices are no longer able to do that. To inject frames into a hardware TX queue with VLAN awareness active, it is necessary to create a VLAN -sub-interface on the DSA master port, and send normal (0x8100) VLAN-tagged +sub-interface on the DSA conduit port, and send normal (0x8100) VLAN-tagged towards the switch, with the VLAN PCP bits set appropriately. Management traffic (having DMAC 01-80-C2-xx-xx-xx or 01-19-1B-xx-xx-xx) is the @@ -389,7 +389,7 @@ MDIO bus and PHY management The SJA1105 does not have an MDIO bus and does not perform in-band AN either. Therefore there is no link state notification coming from the switch device. A board would need to hook up the PHYs connected to the switch to any other -MDIO bus available to Linux within the system (e.g. to the DSA master's MDIO +MDIO bus available to Linux within the system (e.g. to the DSA conduit's MDIO bus). Link state management then works by the driver manually keeping in sync (over SPI commands) the MAC link speed with the settings negotiated by the PHY. diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst index f69da5074860..7d8c5380492f 100644 --- a/Documentation/networking/filter.rst +++ b/Documentation/networking/filter.rst @@ -650,8 +650,8 @@ before a conversion to the new layout is being done behind the scenes! Currently, the classic BPF format is being used for JITing on most 32-bit architectures, whereas x86-64, aarch64, s390x, powerpc64, -sparc64, arm32, riscv64, riscv32 perform JIT compilation from eBPF -instruction set. +sparc64, arm32, riscv64, riscv32, loongarch64 perform JIT compilation +from eBPF instruction set. Testing ------- diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 5b75c3f7a137..683eb42309cc 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -59,7 +59,6 @@ Contents: gtp ila ioam6-sysctl - ipddp ip_dynaddr ipsec ip-sysctl @@ -107,6 +106,7 @@ Contents: sysfs-tagging tc-actions-env-rules tc-queue-filters + tcp_ao tcp-thin team timestamping diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index a66054d0763a..4dfe0d9a57bb 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -745,6 +745,13 @@ tcp_comp_sack_nr - INTEGER Default : 44 +tcp_backlog_ack_defer - BOOLEAN + If set, user thread processing socket backlog tries sending + one ACK for the whole queue. This helps to avoid potential + long latencies at end of a TCP socket syscall. + + Default : true + tcp_slow_start_after_idle - BOOLEAN If set, provide RFC2861 behavior and time out the congestion window after an idle period. An idle period is defined at @@ -1176,6 +1183,19 @@ tcp_plb_cong_thresh - INTEGER Default: 128 +tcp_pingpong_thresh - INTEGER + The number of estimated data replies sent for estimated incoming data + requests that must happen before TCP considers that a connection is a + "ping-pong" (request-response) connection for which delayed + acknowledgments can provide benefits. + + This threshold is 1 by default, but some applications may need a higher + threshold for optimal performance. + + Possible Values: 1 - 255 + + Default: 1 + UDP variables ============= @@ -2304,6 +2324,17 @@ accept_ra_pinfo - BOOLEAN - enabled if accept_ra is enabled. - disabled if accept_ra is disabled. +ra_honor_pio_life - BOOLEAN + Whether to use RFC4862 Section 5.5.3e to determine the valid + lifetime of an address matching a prefix sent in a Router + Advertisement Prefix Information Option. + + - If enabled, the PIO valid lifetime will always be honored. + - If disabled, RFC4862 section 5.5.3e is used to determine + the valid lifetime of the address. + + Default: 0 (disabled) + accept_ra_rt_info_min_plen - INTEGER Minimum prefix length of Route Information in RA. @@ -2471,12 +2502,18 @@ use_tempaddr - INTEGER * -1 (for point-to-point devices and loopback devices) temp_valid_lft - INTEGER - valid lifetime (in seconds) for temporary addresses. + valid lifetime (in seconds) for temporary addresses. If less than the + minimum required lifetime (typically 5 seconds), temporary addresses + will not be created. Default: 172800 (2 days) temp_prefered_lft - INTEGER - Preferred lifetime (in seconds) for temporary addresses. + Preferred lifetime (in seconds) for temporary addresses. If + temp_prefered_lft is less than the minimum required lifetime (typically + 5 seconds), the preferred lifetime is the minimum required. If + temp_prefered_lft is greater than temp_valid_lft, the preferred lifetime + is temp_valid_lft. Default: 86400 (1 day) diff --git a/Documentation/networking/ipddp.rst b/Documentation/networking/ipddp.rst deleted file mode 100644 index be7091b77927..000000000000 --- a/Documentation/networking/ipddp.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -========================================================= -AppleTalk-IP Decapsulation and AppleTalk-IP Encapsulation -========================================================= - -Documentation ipddp.c - -This file is written by Jay Schulist <jschlst@samba.org> - -Introduction ------------- - -AppleTalk-IP (IPDDP) is the method computers connected to AppleTalk -networks can use to communicate via IP. AppleTalk-IP is simply IP datagrams -inside AppleTalk packets. - -Through this driver you can either allow your Linux box to communicate -IP over an AppleTalk network or you can provide IP gatewaying functions -for your AppleTalk users. - -You can currently encapsulate or decapsulate AppleTalk-IP on LocalTalk, -EtherTalk and PPPTalk. The only limit on the protocol is that of what -kernel AppleTalk layer and drivers are available. - -Each mode requires its own user space software. - -Compiling AppleTalk-IP Decapsulation/Encapsulation -================================================== - -AppleTalk-IP decapsulation needs to be compiled into your kernel. You -will need to turn on AppleTalk-IP driver support. Then you will need to -select ONE of the two options; IP to AppleTalk-IP encapsulation support or -AppleTalk-IP to IP decapsulation support. If you compile the driver -statically you will only be able to use the driver for the function you have -enabled in the kernel. If you compile the driver as a module you can -select what mode you want it to run in via a module loading param. -ipddp_mode=1 for AppleTalk-IP encapsulation and ipddp_mode=2 for -AppleTalk-IP to IP decapsulation. - -Basic instructions for user space tools -======================================= - -I will briefly describe the operation of the tools, but you will -need to consult the supporting documentation for each set of tools. - -Decapsulation - You will need to download a software package called -MacGate. In this distribution there will be a tool called MacRoute -which enables you to add routes to the kernel for your Macs by hand. -Also the tool MacRegGateWay is included to register the -proper IP Gateway and IP addresses for your machine. Included in this -distribution is a patch to netatalk-1.4b2+asun2.0a17.2 (available from -ftp.u.washington.edu/pub/user-supported/asun/) this patch is optional -but it allows automatic adding and deleting of routes for Macs. (Handy -for locations with large Mac installations) - -Encapsulation - You will need to download a software daemon called ipddpd. -This software expects there to be an AppleTalk-IP gateway on the network. -You will also need to add the proper routes to route your Linux box's IP -traffic out the ipddp interface. - -Common Uses of ipddp.c ----------------------- -Of course AppleTalk-IP decapsulation and encapsulation, but specifically -decapsulation is being used most for connecting LocalTalk networks to -IP networks. Although it has been used on EtherTalk networks to allow -Macs that are only able to tunnel IP over EtherTalk. - -Encapsulation has been used to allow a Linux box stuck on a LocalTalk -network to use IP. It should work equally well if you are stuck on an -EtherTalk only network. - -Further Assistance -------------------- -You can contact me (Jay Schulist <jschlst@samba.org>) with any -questions regarding decapsulation or encapsulation. Bradford W. Johnson -<johns393@maroon.tc.umn.edu> originally wrote the ipddp.c driver for IP -encapsulation in AppleTalk. diff --git a/Documentation/networking/mptcp-sysctl.rst b/Documentation/networking/mptcp-sysctl.rst index 15f1919d640c..69975ce25a02 100644 --- a/Documentation/networking/mptcp-sysctl.rst +++ b/Documentation/networking/mptcp-sysctl.rst @@ -25,6 +25,17 @@ add_addr_timeout - INTEGER (seconds) Default: 120 +close_timeout - INTEGER (seconds) + Set the make-after-break timeout: in absence of any close or + shutdown syscall, MPTCP sockets will maintain the status + unchanged for such time, after the last subflow removal, before + moving to TCP_CLOSE. + + The default value matches TCP_TIMEWAIT_LEN. This is a per-namespace + sysctl. + + Default: 60 + checksum_enabled - BOOLEAN Control whether DSS checksum can be enabled. diff --git a/Documentation/networking/msg_zerocopy.rst b/Documentation/networking/msg_zerocopy.rst index b3ea96af9b49..78fb70e748b7 100644 --- a/Documentation/networking/msg_zerocopy.rst +++ b/Documentation/networking/msg_zerocopy.rst @@ -7,7 +7,8 @@ Intro ===== The MSG_ZEROCOPY flag enables copy avoidance for socket send calls. -The feature is currently implemented for TCP and UDP sockets. +The feature is currently implemented for TCP, UDP and VSOCK (with +virtio transport) sockets. Opportunity and Caveats @@ -174,7 +175,9 @@ read_notification() call in the previous snippet. A notification is encoded in the standard error format, sock_extended_err. The level and type fields in the control data are protocol family -specific, IP_RECVERR or IPV6_RECVERR. +specific, IP_RECVERR or IPV6_RECVERR (for TCP or UDP socket). +For VSOCK socket, cmsg_level will be SOL_VSOCK and cmsg_type will be +VSOCK_RECVERR. Error origin is the new type SO_EE_ORIGIN_ZEROCOPY. ee_errno is zero, as explained before, to avoid blocking read and write system calls on @@ -235,12 +238,15 @@ Implementation Loopback -------- +For TCP and UDP: Data sent to local sockets can be queued indefinitely if the receive process does not read its socket. Unbound notification latency is not acceptable. For this reason all packets generated with MSG_ZEROCOPY that are looped to a local socket will incur a deferred copy. This includes looping onto packet sockets (e.g., tcpdump) and tun devices. +For VSOCK: +Data path sent to local sockets is the same as for non-local sockets. Testing ======= @@ -254,3 +260,6 @@ instance when run with msg_zerocopy.sh between a veth pair across namespaces, the test will not show any improvement. For testing, the loopback restriction can be temporarily relaxed by making skb_orphan_frags_rx identical to skb_orphan_frags. + +For VSOCK type of socket example can be found in +tools/testing/vsock/vsock_test_zerocopy.c. diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst index 7a9de0568e84..390730a74332 100644 --- a/Documentation/networking/netconsole.rst +++ b/Documentation/networking/netconsole.rst @@ -99,9 +99,6 @@ Dynamic reconfiguration: Dynamic reconfigurability is a useful addition to netconsole that enables remote logging targets to be dynamically added, removed, or have their parameters reconfigured at runtime from a configfs-based userspace interface. -[ Note that the parameters of netconsole targets that were specified/created -from the boot/module option are not exposed via this interface, and hence -cannot be modified dynamically. ] To include this feature, select CONFIG_NETCONSOLE_DYNAMIC when building the netconsole module (or kernel, if netconsole is built-in). @@ -155,6 +152,25 @@ You can also update the local interface dynamically. This is especially useful if you want to use interfaces that have newly come up (and may not have existed when netconsole was loaded / initialized). +Netconsole targets defined at boot time (or module load time) with the +`netconsole=` param are assigned the name `cmdline<index>`. For example, the +first target in the parameter is named `cmdline0`. You can control and modify +these targets by creating configfs directories with the matching name. + +Let's suppose you have two netconsole targets defined at boot time:: + + netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc;4444@10.0.0.1/eth1,9353@10.0.0.3/12:34:56:78:9a:bc + +You can modify these targets in runtime by creating the following targets:: + + mkdir cmdline0 + cat cmdline0/remote_ip + 10.0.0.2 + + mkdir cmdline1 + cat cmdline1/remote_ip + 10.0.0.3 + Extended console: ================= diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst index 215ebc92752c..60993cb56b32 100644 --- a/Documentation/networking/page_pool.rst +++ b/Documentation/networking/page_pool.rst @@ -58,7 +58,9 @@ a page will cause no race conditions is enough. .. kernel-doc:: include/net/page_pool/helpers.h :identifiers: page_pool_put_page page_pool_put_full_page - page_pool_recycle_direct page_pool_dev_alloc_pages + page_pool_recycle_direct page_pool_free_va + page_pool_dev_alloc_pages page_pool_dev_alloc_frag + page_pool_dev_alloc page_pool_dev_alloc_va page_pool_get_dma_addr page_pool_get_dma_dir .. kernel-doc:: net/core/page_pool.c diff --git a/Documentation/networking/pktgen.rst b/Documentation/networking/pktgen.rst index 1225f0f63ff0..c945218946e1 100644 --- a/Documentation/networking/pktgen.rst +++ b/Documentation/networking/pktgen.rst @@ -178,6 +178,7 @@ Examples:: IPSEC # IPsec encapsulation (needs CONFIG_XFRM) NODE_ALLOC # node specific memory allocation NO_TIMESTAMP # disable timestamping + SHARED # enable shared SKB pgset 'flag ![name]' Clear a flag to determine behaviour. Note that you might need to use single quote in interactive mode, so that your shell wouldn't expand @@ -288,6 +289,16 @@ To avoid breaking existing testbed scripts for using AH type and tunnel mode, you can use "pgset spi SPI_VALUE" to specify which transformation mode to employ. +Disable shared SKB +================== +By default, SKBs sent by pktgen are shared (user count > 1). +To test with non-shared SKBs, remove the "SHARED" flag by simply setting:: + + pg_set "flag !SHARED" + +However, if the "clone_skb" or "burst" parameters are configured, the skb +still needs to be held by pktgen for further access. Hence the skb must be +shared. Current commands and configuration options ========================================== @@ -357,6 +368,7 @@ Current commands and configuration options IPSEC NODE_ALLOC NO_TIMESTAMP + SHARED spi (ipsec) diff --git a/Documentation/networking/scaling.rst b/Documentation/networking/scaling.rst index 92c9fb46d6a2..03ae19a689fc 100644 --- a/Documentation/networking/scaling.rst +++ b/Documentation/networking/scaling.rst @@ -105,6 +105,48 @@ a separate CPU. For interrupt handling, HT has shown no benefit in initial tests, so limit the number of queues to the number of CPU cores in the system. +Dedicated RSS contexts +~~~~~~~~~~~~~~~~~~~~~~ + +Modern NICs support creating multiple co-existing RSS configurations +which are selected based on explicit matching rules. This can be very +useful when application wants to constrain the set of queues receiving +traffic for e.g. a particular destination port or IP address. +The example below shows how to direct all traffic to TCP port 22 +to queues 0 and 1. + +To create an additional RSS context use:: + + # ethtool -X eth0 hfunc toeplitz context new + New RSS context is 1 + +Kernel reports back the ID of the allocated context (the default, always +present RSS context has ID of 0). The new context can be queried and +modified using the same APIs as the default context:: + + # ethtool -x eth0 context 1 + RX flow hash indirection table for eth0 with 13 RX ring(s): + 0: 0 1 2 3 4 5 6 7 + 8: 8 9 10 11 12 0 1 2 + [...] + # ethtool -X eth0 equal 2 context 1 + # ethtool -x eth0 context 1 + RX flow hash indirection table for eth0 with 13 RX ring(s): + 0: 0 1 0 1 0 1 0 1 + 8: 0 1 0 1 0 1 0 1 + [...] + +To make use of the new context direct traffic to it using an n-tuple +filter:: + + # ethtool -N eth0 flow-type tcp6 dst-port 22 context 1 + Added rule with ID 1023 + +When done, remove the context and the rule:: + + # ethtool -N eth0 delete 1023 + # ethtool -X eth0 context 1 delete + RPS: Receive Packet Steering ============================ diff --git a/Documentation/networking/sfp-phylink.rst b/Documentation/networking/sfp-phylink.rst index 55b65f607a64..8054d33f449f 100644 --- a/Documentation/networking/sfp-phylink.rst +++ b/Documentation/networking/sfp-phylink.rst @@ -200,10 +200,12 @@ this documentation. when the in-band link state changes - otherwise the link will never come up. - The :c:func:`validate` method should mask the supplied supported mask, - and ``state->advertising`` with the supported ethtool link modes. - These are the new ethtool link modes, so bitmask operations must be - used. For an example, see ``drivers/net/ethernet/marvell/mvneta.c``. + The :c:func:`mac_get_caps` method is optional, and if provided should + return the phylink MAC capabilities that are supported for the passed + ``interface`` mode. In general, there is no need to implement this method. + Phylink will use these capabilities in combination with permissible + capabilities for ``interface`` to determine the allowable ethtool link + modes. The :c:func:`mac_link_state` method is used to read the link state from the MAC, and report back the settings that the MAC is currently diff --git a/Documentation/networking/tcp_ao.rst b/Documentation/networking/tcp_ao.rst new file mode 100644 index 000000000000..cfa5bf1cc542 --- /dev/null +++ b/Documentation/networking/tcp_ao.rst @@ -0,0 +1,444 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================== +TCP Authentication Option Linux implementation (RFC5925) +======================================================== + +TCP Authentication Option (TCP-AO) provides a TCP extension aimed at verifying +segments between trusted peers. It adds a new TCP header option with +a Message Authentication Code (MAC). MACs are produced from the content +of a TCP segment using a hashing function with a password known to both peers. +The intent of TCP-AO is to deprecate TCP-MD5 providing better security, +key rotation and support for variety of hashing algorithms. + +1. Introduction +=============== + +.. table:: Short and Limited Comparison of TCP-AO and TCP-MD5 + + +----------------------+------------------------+-----------------------+ + | | TCP-MD5 | TCP-AO | + +======================+========================+=======================+ + |Supported hashing |MD5 |Must support HMAC-SHA1 | + |algorithms |(cryptographically weak)|(chosen-prefix attacks)| + | | |and CMAC-AES-128 (only | + | | |side-channel attacks). | + | | |May support any hashing| + | | |algorithm. | + +----------------------+------------------------+-----------------------+ + |Length of MACs (bytes)|16 |Typically 12-16. | + | | |Other variants that fit| + | | |TCP header permitted. | + +----------------------+------------------------+-----------------------+ + |Number of keys per |1 |Many | + |TCP connection | | | + +----------------------+------------------------+-----------------------+ + |Possibility to change |Non-practical (both |Supported by protocol | + |an active key |peers have to change | | + | |them during MSL) | | + +----------------------+------------------------+-----------------------+ + |Protection against |No |Yes: ignoring them | + |ICMP 'hard errors' | |by default on | + | | |established connections| + +----------------------+------------------------+-----------------------+ + |Protection against |No |Yes: pseudo-header | + |traffic-crossing | |includes TCP ports. | + |attack | | | + +----------------------+------------------------+-----------------------+ + |Protection against |No |Sequence Number | + |replayed TCP segments | |Extension (SNE) and | + | | |Initial Sequence | + | | |Numbers (ISNs) | + +----------------------+------------------------+-----------------------+ + |Supports |Yes |No. ISNs+SNE are needed| + |Connectionless Resets | |to correctly sign RST. | + +----------------------+------------------------+-----------------------+ + |Standards |RFC 2385 |RFC 5925, RFC 5926 | + +----------------------+------------------------+-----------------------+ + + +1.1 Frequently Asked Questions (FAQ) with references to RFC 5925 +---------------------------------------------------------------- + +Q: Can either SendID or RecvID be non-unique for the same 4-tuple +(srcaddr, srcport, dstaddr, dstport)? + +A: No [3.1]:: + + >> The IDs of MKTs MUST NOT overlap where their TCP connection + identifiers overlap. + +Q: Can Master Key Tuple (MKT) for an active connection be removed? + +A: No, unless it's copied to Transport Control Block (TCB) [3.1]:: + + It is presumed that an MKT affecting a particular connection cannot + be destroyed during an active connection -- or, equivalently, that + its parameters are copied to an area local to the connection (i.e., + instantiated) and so changes would affect only new connections. + +Q: If an old MKT needs to be deleted, how should it be done in order +to not remove it for an active connection? (As it can be still in use +at any moment later) + +A: Not specified by RFC 5925, seems to be a problem for key management +to ensure that no one uses such MKT before trying to remove it. + +Q: Can an old MKT exist forever and be used by another peer? + +A: It can, it's a key management task to decide when to remove an old key [6.1]:: + + Deciding when to start using a key is a performance issue. Deciding + when to remove an MKT is a security issue. Invalid MKTs are expected + to be removed. TCP-AO provides no mechanism to coordinate their removal, + as we consider this a key management operation. + +also [6.1]:: + + The only way to avoid reuse of previously used MKTs is to remove the MKT + when it is no longer considered permitted. + +Linux TCP-AO will try its best to prevent you from removing a key that's +being used, considering it a key management failure. But sine keeping +an outdated key may become a security issue and as a peer may +unintentionally prevent the removal of an old key by always setting +it as RNextKeyID - a forced key removal mechanism is provided, where +userspace has to supply KeyID to use instead of the one that's being removed +and the kernel will atomically delete the old key, even if the peer is +still requesting it. There are no guarantees for force-delete as the peer +may yet not have the new key - the TCP connection may just break. +Alternatively, one may choose to shut down the socket. + +Q: What happens when a packet is received on a new connection with no known +MKT's RecvID? + +A: RFC 5925 specifies that by default it is accepted with a warning logged, but +the behaviour can be configured by the user [7.5.1.a]:: + + If the segment is a SYN, then this is the first segment of a new + connection. Find the matching MKT for this segment, using the segment's + socket pair and its TCP-AO KeyID, matched against the MKT's TCP connection + identifier and the MKT's RecvID. + + i. If there is no matching MKT, remove TCP-AO from the segment. + Proceed with further TCP handling of the segment. + NOTE: this presumes that connections that do not match any MKT + should be silently accepted, as noted in Section 7.3. + +[7.3]:: + + >> A TCP-AO implementation MUST allow for configuration of the behavior + of segments with TCP-AO but that do not match an MKT. The initial default + of this configuration SHOULD be to silently accept such connections. + If this is not the desired case, an MKT can be included to match such + connections, or the connection can indicate that TCP-AO is required. + Alternately, the configuration can be changed to discard segments with + the AO option not matching an MKT. + +[10.2.b]:: + + Connections not matching any MKT do not require TCP-AO. Further, incoming + segments with TCP-AO are not discarded solely because they include + the option, provided they do not match any MKT. + +Note that Linux TCP-AO implementation differs in this aspect. Currently, TCP-AO +segments with unknown key signatures are discarded with warnings logged. + +Q: Does the RFC imply centralized kernel key management in any way? +(i.e. that a key on all connections MUST be rotated at the same time?) + +A: Not specified. MKTs can be managed in userspace, the only relevant part to +key changes is [7.3]:: + + >> All TCP segments MUST be checked against the set of MKTs for matching + TCP connection identifiers. + +Q: What happens when RNextKeyID requested by a peer is unknown? Should +the connection be reset? + +A: It should not, no action needs to be performed [7.5.2.e]:: + + ii. If they differ, determine whether the RNextKeyID MKT is ready. + + 1. If the MKT corresponding to the segment’s socket pair and RNextKeyID + is not available, no action is required (RNextKeyID of a received + segment needs to match the MKT’s SendID). + +Q: How current_key is set and when does it change? It is a user-triggered +change, or is it by a request from the remote peer? Is it set by the user +explicitly, or by a matching rule? + +A: current_key is set by RNextKeyID [6.1]:: + + Rnext_key is changed only by manual user intervention or MKT management + protocol operation. It is not manipulated by TCP-AO. Current_key is updated + by TCP-AO when processing received TCP segments as discussed in the segment + processing description in Section 7.5. Note that the algorithm allows + the current_key to change to a new MKT, then change back to a previously + used MKT (known as "backing up"). This can occur during an MKT change when + segments are received out of order, and is considered a feature of TCP-AO, + because reordering does not result in drops. + +[7.5.2.e.ii]:: + + 2. If the matching MKT corresponding to the segment’s socket pair and + RNextKeyID is available: + + a. Set current_key to the RNextKeyID MKT. + +Q: If both peers have multiple MKTs matching the connection's socket pair +(with different KeyIDs), how should the sender/receiver pick KeyID to use? + +A: Some mechanism should pick the "desired" MKT [3.3]:: + + Multiple MKTs may match a single outgoing segment, e.g., when MKTs + are being changed. Those MKTs cannot have conflicting IDs (as noted + elsewhere), and some mechanism must determine which MKT to use for each + given outgoing segment. + + >> An outgoing TCP segment MUST match at most one desired MKT, indicated + by the segment’s socket pair. The segment MAY match multiple MKTs, provided + that exactly one MKT is indicated as desired. Other information in + the segment MAY be used to determine the desired MKT when multiple MKTs + match; such information MUST NOT include values in any TCP option fields. + +Q: Can TCP-MD5 connection migrate to TCP-AO (and vice-versa): + +A: No [1]:: + + TCP MD5-protected connections cannot be migrated to TCP-AO because TCP MD5 + does not support any changes to a connection’s security algorithm + once established. + +Q: If all MKTs are removed on a connection, can it become a non-TCP-AO signed +connection? + +A: [7.5.2] doesn't have the same choice as SYN packet handling in [7.5.1.i] +that would allow accepting segments without a sign (which would be insecure). +While switching to non-TCP-AO connection is not prohibited directly, it seems +what the RFC means. Also, there's a requirement for TCP-AO connections to +always have one current_key [3.3]:: + + TCP-AO requires that every protected TCP segment match exactly one MKT. + +[3.3]:: + + >> An incoming TCP segment including TCP-AO MUST match exactly one MKT, + indicated solely by the segment’s socket pair and its TCP-AO KeyID. + +[4.4]:: + + One or more MKTs. These are the MKTs that match this connection’s + socket pair. + +Q: Can a non-TCP-AO connection become a TCP-AO-enabled one? + +A: No: for already established non-TCP-AO connection it would be impossible +to switch using TCP-AO as the traffic key generation requires the initial +sequence numbers. Paraphrasing, starting using TCP-AO would require +re-establishing the TCP connection. + +2. In-kernel MKTs database vs database in userspace +=================================================== + +Linux TCP-AO support is implemented using ``setsockopt()s``, in a similar way +to TCP-MD5. It means that a userspace application that wants to use TCP-AO +should perform ``setsockopt()`` on a TCP socket when it wants to add, +remove or rotate MKTs. This approach moves the key management responsibility +to userspace as well as decisions on corner cases, i.e. what to do if +the peer doesn't respect RNextKeyID; moving more code to userspace, especially +responsible for the policy decisions. Besides, it's flexible and scales well +(with less locking needed than in the case of an in-kernel database). One also +should keep in mind that mainly intended users are BGP processes, not any +random applications, which means that compared to IPsec tunnels, +no transparency is really needed and modern BGP daemons already have +``setsockopt()s`` for TCP-MD5 support. + +.. table:: Considered pros and cons of the approaches + + +----------------------+------------------------+-----------------------+ + | | ``setsockopt()`` | in-kernel DB | + +======================+========================+=======================+ + | Extendability | ``setsockopt()`` | Netlink messages are | + | | commands should be | simple and extendable | + | | extendable syscalls | | + +----------------------+------------------------+-----------------------+ + | Required userspace | BGP or any application | could be transparent | + | changes | that wants TCP-AO needs| as tunnels, providing | + | | to perform | something like | + | | ``setsockopt()s`` | ``ip tcpao add key`` | + | | and do key management | (delete/show/rotate) | + +----------------------+------------------------+-----------------------+ + |MKTs removal or adding| harder for userspace | harder for kernel | + +----------------------+------------------------+-----------------------+ + | Dump-ability | ``getsockopt()`` | Netlink .dump() | + | | | callback | + +----------------------+------------------------+-----------------------+ + | Limits on kernel | equal | + | resources/memory | | + +----------------------+------------------------+-----------------------+ + | Scalability | contention on | contention on | + | | ``TCP_LISTEN`` sockets | the whole database | + +----------------------+------------------------+-----------------------+ + | Monitoring & warnings| ``TCP_DIAG`` | same Netlink socket | + +----------------------+------------------------+-----------------------+ + | Matching of MKTs | half-problem: only | hard | + | | listen sockets | | + +----------------------+------------------------+-----------------------+ + + +3. uAPI +======= + +Linux provides a set of ``setsockopt()s`` and ``getsockopt()s`` that let +userspace manage TCP-AO on a per-socket basis. In order to add/delete MKTs +``TCP_AO_ADD_KEY`` and ``TCP_AO_DEL_KEY`` TCP socket options must be used +It is not allowed to add a key on an established non-TCP-AO connection +as well as to remove the last key from TCP-AO connection. + +``setsockopt(TCP_AO_DEL_KEY)`` command may specify ``tcp_ao_del::current_key`` ++ ``tcp_ao_del::set_current`` and/or ``tcp_ao_del::rnext`` ++ ``tcp_ao_del::set_rnext`` which makes such delete "forced": it +provides userspace a way to delete a key that's being used and atomically set +another one instead. This is not intended for normal use and should be used +only when the peer ignores RNextKeyID and keeps requesting/using an old key. +It provides a way to force-delete a key that's not trusted but may break +the TCP-AO connection. + +The usual/normal key-rotation can be performed with ``setsockopt(TCP_AO_INFO)``. +It also provides a uAPI to change per-socket TCP-AO settings, such as +ignoring ICMPs, as well as clear per-socket TCP-AO packet counters. +The corresponding ``getsockopt(TCP_AO_INFO)`` can be used to get those +per-socket TCP-AO settings. + +Another useful command is ``getsockopt(TCP_AO_GET_KEYS)``. One can use it +to list all MKTs on a TCP socket or use a filter to get keys for a specific +peer and/or sndid/rcvid, VRF L3 interface or get current_key/rnext_key. + +To repair TCP-AO connections ``setsockopt(TCP_AO_REPAIR)`` is available, +provided that the user previously has checkpointed/dumped the socket with +``getsockopt(TCP_AO_REPAIR)``. + +A tip here for scaled TCP_LISTEN sockets, that may have some thousands TCP-AO +keys, is: use filters in ``getsockopt(TCP_AO_GET_KEYS)`` and asynchronous +delete with ``setsockopt(TCP_AO_DEL_KEY)``. + +Linux TCP-AO also provides a bunch of segment counters that can be helpful +with troubleshooting/debugging issues. Every MKT has good/bad counters +that reflect how many packets passed/failed verification. +Each TCP-AO socket has the following counters: +- for good segments (properly signed) +- for bad segments (failed TCP-AO verification) +- for segments with unknown keys +- for segments where an AO signature was expected, but wasn't found +- for the number of ignored ICMPs + +TCP-AO per-socket counters are also duplicated with per-netns counters, +exposed with SNMP. Those are ``TCPAOGood``, ``TCPAOBad``, ``TCPAOKeyNotFound``, +``TCPAORequired`` and ``TCPAODroppedIcmps``. + +RFC 5925 very permissively specifies how TCP port matching can be done for +MKTs:: + + TCP connection identifier. A TCP socket pair, i.e., a local IP + address, a remote IP address, a TCP local port, and a TCP remote port. + Values can be partially specified using ranges (e.g., 2-30), masks + (e.g., 0xF0), wildcards (e.g., "*"), or any other suitable indication. + +Currently Linux TCP-AO implementation doesn't provide any TCP port matching. +Probably, port ranges are the most flexible for uAPI, but so far +not implemented. + +4. ``setsockopt()`` vs ``accept()`` race +======================================== + +In contrast with TCP-MD5 established connection which has just one key, +TCP-AO connections may have many keys, which means that accepted connections +on a listen socket may have any amount of keys as well. As copying all those +keys on a first properly signed SYN would make the request socket bigger, that +would be undesirable. Currently, the implementation doesn't copy keys +to request sockets, but rather look them up on the "parent" listener socket. + +The result is that when userspace removes TCP-AO keys, that may break +not-yet-established connections on request sockets as well as not removing +keys from sockets that were already established, but not yet ``accept()``'ed, +hanging in the accept queue. + +The reverse is valid as well: if userspace adds a new key for a peer on +a listener socket, the established sockets in accept queue won't +have the new keys. + +At this moment, the resolution for the two races: +``setsockopt(TCP_AO_ADD_KEY)`` vs ``accept()`` +and ``setsockopt(TCP_AO_DEL_KEY)`` vs ``accept()`` is delegated to userspace. +This means that it's expected that userspace would check the MKTs on the socket +that was returned by ``accept()`` to verify that any key rotation that +happened on listen socket is reflected on the newly established connection. + +This is a similar "do-nothing" approach to TCP-MD5 from the kernel side and +may be changed later by introducing new flags to ``tcp_ao_add`` +and ``tcp_ao_del``. + +Note that this race is rare for it needs TCP-AO key rotation to happen +during the 3-way handshake for the new TCP connection. + +5. Interaction with TCP-MD5 +=========================== + +A TCP connection can not migrate between TCP-AO and TCP-MD5 options. The +established sockets that have either AO or MD5 keys are restricted for +adding keys of the other option. + +For listening sockets the picture is different: BGP server may want to receive +both TCP-AO and (deprecated) TCP-MD5 clients. As a result, both types of keys +may be added to TCP_CLOSED or TCP_LISTEN sockets. It's not allowed to add +different types of keys for the same peer. + +6. SNE Linux implementation +=========================== + +RFC 5925 [6.2] describes the algorithm of how to extend TCP sequence numbers +with SNE. In short: TCP has to track the previous sequence numbers and set +sne_flag when the current SEQ number rolls over. The flag is cleared when +both current and previous SEQ numbers cross 0x7fff, which is 32Kb. + +In times when sne_flag is set, the algorithm compares SEQ for each packet with +0x7fff and if it's higher than 32Kb, it assumes that the packet should be +verified with SNE before the increment. As a result, there's +this [0; 32Kb] window, when packets with (SNE - 1) can be accepted. + +Linux implementation simplifies this a bit: as the network stack already tracks +the first SEQ byte that ACK is wanted for (snd_una) and the next SEQ byte that +is wanted (rcv_nxt) - that's enough information for a rough estimation +on where in the 4GB SEQ number space both sender and receiver are. +When they roll over to zero, the corresponding SNE gets incremented. + +tcp_ao_compute_sne() is called for each TCP-AO segment. It compares SEQ numbers +from the segment with snd_una or rcv_nxt and fits the result into a 2GB window around them, +detecting SEQ numbers rolling over. That simplifies the code a lot and only +requires SNE numbers to be stored on every TCP-AO socket. + +The 2GB window at first glance seems much more permissive compared to +RFC 5926. But that is only used to pick the correct SNE before/after +a rollover. It allows more TCP segment replays, but yet all regular +TCP checks in tcp_sequence() are applied on the verified segment. +So, it trades a bit more permissive acceptance of replayed/retransmitted +segments for the simplicity of the algorithm and what seems better behaviour +for large TCP windows. + +7. Links +======== + +RFC 5925 The TCP Authentication Option + https://www.rfc-editor.org/rfc/pdfrfc/rfc5925.txt.pdf + +RFC 5926 Cryptographic Algorithms for the TCP Authentication Option (TCP-AO) + https://www.rfc-editor.org/rfc/pdfrfc/rfc5926.txt.pdf + +Draft "SHA-2 Algorithm for the TCP Authentication Option (TCP-AO)" + https://datatracker.ietf.org/doc/html/draft-nayak-tcp-sha2-03 + +RFC 2385 Protection of BGP Sessions via the TCP MD5 Signature Option + https://www.rfc-editor.org/rfc/pdfrfc/rfc2385.txt.pdf + +:Author: Dmitry Safonov <dima@arista.com> diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst index 25ce72af81c2..205696780b78 100644 --- a/Documentation/networking/xdp-rx-metadata.rst +++ b/Documentation/networking/xdp-rx-metadata.rst @@ -105,6 +105,13 @@ bpf_tail_call Adding programs that access metadata kfuncs to the ``BPF_MAP_TYPE_PROG_ARRAY`` is currently not supported. +Supported Devices +================= + +It is possible to query which kfunc the particular netdev implements via +netlink. See ``xdp-rx-metadata-features`` attribute set in +``Documentation/netlink/specs/netdev.yaml``. + Example ======= diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst index bf7cbfb4caa5..43291704338e 100644 --- a/Documentation/process/7.AdvancedTopics.rst +++ b/Documentation/process/7.AdvancedTopics.rst @@ -146,6 +146,7 @@ pull. The git request-pull command can be helpful in this regard; it will format the request as other developers expect, and will also check to be sure that you have remembered to push those changes to the public server. +.. _development_advancedtopics_reviews: Reviewing patches ----------------- @@ -167,6 +168,12 @@ comments as questions rather than criticisms. Asking "how does the lock get released in this path?" will always work better than stating "the locking here is wrong." +Another technique that is useful in case of a disagreement is to ask for others +to chime in. If a discussion reaches a stalemate after a few exchanges, +then call for opinions of other reviewers or maintainers. Often those in +agreement with a reviewer remain silent unless called upon. +The opinion of multiple people carries exponentially more weight. + Different developers will review code from different points of view. Some are mostly concerned with coding style and whether code lines have trailing white space. Others will focus primarily on whether the change implemented @@ -176,3 +183,14 @@ security issues, duplication of code found elsewhere, adequate documentation, adverse effects on performance, user-space ABI changes, etc. All types of review, if they lead to better code going into the kernel, are welcome and worthwhile. + +There is no strict requirement to use specific tags like ``Reviewed-by``. +In fact reviews in plain English are more informative and encouraged +even when a tag is provided, e.g. "I looked at aspects A, B and C of this +submission and it looks good to me." +Some form of a review message or reply is obviously necessary otherwise +maintainers will not know that the reviewer has looked at the patch at all! + +Last but not least patch review may become a negative process, focused +on pointing out problems. Please throw in a compliment once in a while, +particularly for newbies! diff --git a/Documentation/process/backporting.rst b/Documentation/process/backporting.rst new file mode 100644 index 000000000000..e1a6ea0a1e8a --- /dev/null +++ b/Documentation/process/backporting.rst @@ -0,0 +1,604 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +Backporting and conflict resolution +=================================== + +:Author: Vegard Nossum <vegard.nossum@oracle.com> + +.. contents:: + :local: + :depth: 3 + :backlinks: none + +Introduction +============ + +Some developers may never really have to deal with backporting patches, +merging branches, or resolving conflicts in their day-to-day work, so +when a merge conflict does pop up, it can be daunting. Luckily, +resolving conflicts is a skill like any other, and there are many useful +techniques you can use to make the process smoother and increase your +confidence in the result. + +This document aims to be a comprehensive, step-by-step guide to +backporting and conflict resolution. + +Applying the patch to a tree +============================ + +Sometimes the patch you are backporting already exists as a git commit, +in which case you just cherry-pick it directly using +``git cherry-pick``. However, if the patch comes from an email, as it +often does for the Linux kernel, you will need to apply it to a tree +using ``git am``. + +If you've ever used ``git am``, you probably already know that it is +quite picky about the patch applying perfectly to your source tree. In +fact, you've probably had nightmares about ``.rej`` files and trying to +edit the patch to make it apply. + +It is strongly recommended to instead find an appropriate base version +where the patch applies cleanly and *then* cherry-pick it over to your +destination tree, as this will make git output conflict markers and let +you resolve conflicts with the help of git and any other conflict +resolution tools you might prefer to use. For example, if you want to +apply a patch that just arrived on LKML to an older stable kernel, you +can apply it to the most recent mainline kernel and then cherry-pick it +to your older stable branch. + +It's generally better to use the exact same base as the one the patch +was generated from, but it doesn't really matter that much as long as it +applies cleanly and isn't too far from the original base. The only +problem with applying the patch to the "wrong" base is that it may pull +in more unrelated changes in the context of the diff when cherry-picking +it to the older branch. + +A good reason to prefer ``git cherry-pick`` over ``git am`` is that git +knows the precise history of an existing commit, so it will know when +code has moved around and changed the line numbers; this in turn makes +it less likely to apply the patch to the wrong place (which can result +in silent mistakes or messy conflicts). + +If you are using `b4`_. and you are applying the patch directly from an +email, you can use ``b4 am`` with the options ``-g``/``--guess-base`` +and ``-3``/``--prep-3way`` to do some of this automatically (see the +`b4 presentation`_ for more information). However, the rest of this +article will assume that you are doing a plain ``git cherry-pick``. + +.. _b4: https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestation +.. _b4 presentation: https://youtu.be/mF10hgVIx9o?t=2996 + +Once you have the patch in git, you can go ahead and cherry-pick it into +your source tree. Don't forget to cherry-pick with ``-x`` if you want a +written record of where the patch came from! + +Note that if you are submiting a patch for stable, the format is +slightly different; the first line after the subject line needs tobe +either:: + + commit <upstream commit> upstream + +or:: + + [ Upstream commit <upstream commit> ] + +Resolving conflicts +=================== + +Uh-oh; the cherry-pick failed with a vaguely threatening message:: + + CONFLICT (content): Merge conflict + +What to do now? + +In general, conflicts appear when the context of the patch (i.e., the +lines being changed and/or the lines surrounding the changes) doesn't +match what's in the tree you are trying to apply the patch *to*. + +For backports, what likely happened was that the branch you are +backporting from contains patches not in the branch you are backporting +to. However, the reverse is also possible. In any case, the result is a +conflict that needs to be resolved. + +If your attempted cherry-pick fails with a conflict, git automatically +edits the files to include so-called conflict markers showing you where +the conflict is and how the two branches have diverged. Resolving the +conflict typically means editing the end result in such a way that it +takes into account these other commits. + +Resolving the conflict can be done either by hand in a regular text +editor or using a dedicated conflict resolution tool. + +Many people prefer to use their regular text editor and edit the +conflict directly, as it may be easier to understand what you're doing +and to control the final result. There are definitely pros and cons to +each method, and sometimes there's value in using both. + +We will not cover using dedicated merge tools here beyond providing some +pointers to various tools that you could use: + +- `Emacs Ediff mode <https://www.emacswiki.org/emacs/EdiffMode>`__ +- `vimdiff/gvimdiff <https://linux.die.net/man/1/vimdiff>`__ +- `KDiff3 <http://kdiff3.sourceforge.net/>`__ +- `TortoiseMerge <https://tortoisesvn.net/TortoiseMerge.html>`__ +- `Meld <https://meldmerge.org/help/>`__ +- `P4Merge <https://www.perforce.com/products/helix-core-apps/merge-diff-tool-p4merge>`__ +- `Beyond Compare <https://www.scootersoftware.com/>`__ +- `IntelliJ <https://www.jetbrains.com/help/idea/resolve-conflicts.html>`__ +- `VSCode <https://code.visualstudio.com/docs/editor/versioncontrol>`__ + +To configure git to work with these, see ``git mergetool --help`` or +the official `git-mergetool documentation`_. + +.. _git-mergetool documentation: https://git-scm.com/docs/git-mergetool + +Prerequisite patches +-------------------- + +Most conflicts happen because the branch you are backporting to is +missing some patches compared to the branch you are backporting *from*. +In the more general case (such as merging two independent branches), +development could have happened on either branch, or the branches have +simply diverged -- perhaps your older branch had some other backports +applied to it that themselves needed conflict resolutions, causing a +divergence. + +It's important to always identify the commit or commits that caused the +conflict, as otherwise you cannot be confident in the correctness of +your resolution. As an added bonus, especially if the patch is in an +area you're not that famliar with, the changelogs of these commits will +often give you the context to understand the code and potential problems +or pitfalls with your conflict resolution. + +git log +~~~~~~~ + +A good first step is to look at ``git log`` for the file that has the +conflict -- this is usually sufficient when there aren't a lot of +patches to the file, but may get confusing if the file is big and +frequently patched. You should run ``git log`` on the range of commits +between your currently checked-out branch (``HEAD``) and the parent of +the patch you are picking (``<commit>``), i.e.:: + + git log HEAD..<commit>^ -- <path> + +Even better, if you want to restrict this output to a single function +(because that's where the conflict appears), you can use the following +syntax:: + + git log -L:'\<function\>':<path> HEAD..<commit>^ + +.. note:: + The ``\<`` and ``\>`` around the function name ensure that the + matches are anchored on a word boundary. This is important, as this + part is actually a regex and git only follows the first match, so + if you use ``-L:thread_stack:kernel/fork.c`` it may only give you + results for the function ``try_release_thread_stack_to_cache`` even + though there are many other functions in that file containing the + string ``thread_stack`` in their names. + +Another useful option for ``git log`` is ``-G``, which allows you to +filter on certain strings appearing in the diffs of the commits you are +listing:: + + git log -G'regex' HEAD..<commit>^ -- <path> + +This can also be a handy way to quickly find when something (e.g. a +function call or a variable) was changed, added, or removed. The search +string is a regular expression, which means you can potentially search +for more specific things like assignments to a specific struct member:: + + git log -G'\->index\>.*=' + +git blame +~~~~~~~~~ + +Another way to find prerequisite commits (albeit only the most recent +one for a given conflict) is to run ``git blame``. In this case, you +need to run it against the parent commit of the patch you are +cherry-picking and the file where the conflict appared, i.e.:: + + git blame <commit>^ -- <path> + +This command also accepts the ``-L`` argument (for restricting the +output to a single function), but in this case you specify the filename +at the end of the command as usual:: + + git blame -L:'\<function\>' <commit>^ -- <path> + +Navigate to the place where the conflict occurred. The first column of +the blame output is the commit ID of the patch that added a given line +of code. + +It might be a good idea to ``git show`` these commits and see if they +look like they might be the source of the conflict. Sometimes there will +be more than one of these commits, either because multiple commits +changed different lines of the same conflict area *or* because multiple +subsequent patches changed the same line (or lines) multiple times. In +the latter case, you may have to run ``git blame`` again and specify the +older version of the file to look at in order to dig further back in +the history of the file. + +Prerequisite vs. incidental patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Having found the patch that caused the conflict, you need to determine +whether it is a prerequisite for the patch you are backporting or +whether it is just incidental and can be skipped. An incidental patch +would be one that touches the same code as the patch you are +backporting, but does not change the semantics of the code in any +material way. For example, a whitespace cleanup patch is completely +incidental -- likewise, a patch that simply renames a function or a +variable would be incidental as well. On the other hand, if the function +being changed does not even exist in your current branch then this would +not be incidental at all and you need to carefully consider whether the +patch adding the function should be cherry-picked first. + +If you find that there is a necessary prerequisite patch, then you need +to stop and cherry-pick that instead. If you've already resolved some +conflicts in a different file and don't want to do it again, you can +create a temporary copy of that file. + +To abort the current cherry-pick, go ahead and run +``git cherry-pick --abort``, then restart the cherry-picking process +with the commit ID of the prerequisite patch instead. + +Understanding conflict markers +------------------------------ + +Combined diffs +~~~~~~~~~~~~~~ + +Let's say you've decided against picking (or reverting) additional +patches and you just want to resolve the conflict. Git will have +inserted conflict markers into your file. Out of the box, this will look +something like:: + + <<<<<<< HEAD + this is what's in your current tree before cherry-picking + ======= + this is what the patch wants it to be after cherry-picking + >>>>>>> <commit>... title + +This is what you would see if you opened the file in your editor. +However, if you were to run ``git diff`` without any arguments, the +output would look something like this:: + + $ git diff + [...] + ++<<<<<<<< HEAD + +this is what's in your current tree before cherry-picking + ++======== + + this is what the patch wants it to be after cherry-picking + ++>>>>>>>> <commit>... title + +When you are resolving a conflict, the behavior of ``git diff`` differs +from its normal behavior. Notice the two columns of diff markers +instead of the usual one; this is a so-called "`combined diff`_", here +showing the 3-way diff (or diff-of-diffs) between + +#. the current branch (before cherry-picking) and the current working + directory, and +#. the current branch (before cherry-picking) and the file as it looks + after the original patch has been applied. + +.. _combined diff: https://git-scm.com/docs/diff-format#_combined_diff_format + + +Better diffs +~~~~~~~~~~~~ + +3-way combined diffs include all the other changes that happened to the +file between your current branch and the branch you are cherry-picking +from. While this is useful for spotting other changes that you need to +take into account, this also makes the output of ``git diff`` somewhat +intimidating and difficult to read. You may instead prefer to run +``git diff HEAD`` (or ``git diff --ours``) which shows only the diff +between the current branch before cherry-picking and the current working +directory. It looks like this:: + + $ git diff HEAD + [...] + +<<<<<<<< HEAD + this is what's in your current tree before cherry-picking + +======== + +this is what the patch wants it to be after cherry-picking + +>>>>>>>> <commit>... title + +As you can see, this reads just like any other diff and makes it clear +which lines are in the current branch and which lines are being added +because they are part of the merge conflict or the patch being +cherry-picked. + +Merge styles and diff3 +~~~~~~~~~~~~~~~~~~~~~~ + +The default conflict marker style shown above is known as the ``merge`` +style. There is also another style available, known as the ``diff3`` +style, which looks like this:: + + <<<<<<< HEAD + this is what is in your current tree before cherry-picking + ||||||| parent of <commit> (title) + this is what the patch expected to find there + ======= + this is what the patch wants it to be after being applied + >>>>>>> <commit> (title) + +As you can see, this has 3 parts instead of 2, and includes what git +expected to find there but didn't. It is *highly recommended* to use +this conflict style as it makes it much clearer what the patch actually +changed; i.e., it allows you to compare the before-and-after versions +of the file for the commit you are cherry-picking. This allows you to +make better decisions about how to resolve the conflict. + +To change conflict marker styles, you can use the following command:: + + git config merge.conflictStyle diff3 + +There is a third option, ``zdiff3``, introduced in `Git 2.35`_, +which has the same 3 sections as ``diff3``, but where common lines have +been trimmed off, making the conflict area smaller in some cases. + +.. _Git 2.35: https://github.blog/2022-01-24-highlights-from-git-2-35/ + +Iterating on conflict resolutions +--------------------------------- + +The first step in any conflict resolution process is to understand the +patch you are backporting. For the Linux kernel this is especially +important, since an incorrect change can lead to the whole system +crashing -- or worse, an undetected security vulnerability. + +Understanding the patch can be easy or difficult depending on the patch +itself, the changelog, and your familiarity with the code being changed. +However, a good question for every change (or every hunk of the patch) +might be: "Why is this hunk in the patch?" The answers to these +questions will inform your conflict resolution. + +Resolution process +~~~~~~~~~~~~~~~~~~ + +Sometimes the easiest thing to do is to just remove all but the first +part of the conflict, leaving the file essentially unchanged, and apply +the changes by hand. Perhaps the patch is changing a function call +argument from ``0`` to ``1`` while a conflicting change added an +entirely new (and insignificant) parameter to the end of the parameter +list; in that case, it's easy enough to change the argument from ``0`` +to ``1`` by hand and leave the rest of the arguments alone. This +technique of manually applying changes is mostly useful if the conflict +pulled in a lot of unrelated context that you don't really need to care +about. + +For particularly nasty conflicts with many conflict markers, you can use +``git add`` or ``git add -i`` to selectively stage your resolutions to +get them out of the way; this also lets you use ``git diff HEAD`` to +always see what remains to be resolved or ``git diff --cached`` to see +what your patch looks like so far. + +Dealing with file renames +~~~~~~~~~~~~~~~~~~~~~~~~~ + +One of the most annoying things that can happen while backporting a +patch is discovering that one of the files being patched has been +renamed, as that typically means git won't even put in conflict markers, +but will just throw up its hands and say (paraphrased): "Unmerged path! +You do the work..." + +There are generally a few ways to deal with this. If the patch to the +renamed file is small, like a one-line change, the easiest thing is to +just go ahead and apply the change by hand and be done with it. On the +other hand, if the change is big or complicated, you definitely don't +want to do it by hand. + +As a first pass, you can try something like this, which will lower the +rename detection threshold to 30% (by default, git uses 50%, meaning +that two files need to have at least 50% in common for it to consider +an add-delete pair to be a potential rename):: + + git cherry-pick -strategy=recursive -Xrename-threshold=30 + +Sometimes the right thing to do will be to also backport the patch that +did the rename, but that's definitely not the most common case. Instead, +what you can do is to temporarily rename the file in the branch you're +backporting to (using ``git mv`` and committing the result), restart the +attempt to cherry-pick the patch, rename the file back (``git mv`` and +committing again), and finally squash the result using ``git rebase -i`` +(see the `rebase tutorial`_) so it appears as a single commit when you +are done. + +.. _rebase tutorial: https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec + +Gotchas +------- + +Function arguments +~~~~~~~~~~~~~~~~~~ + +Pay attention to changing function arguments! It's easy to gloss over +details and think that two lines are the same but actually they differ +in some small detail like which variable was passed as an argument +(especially if the two variables are both a single character that look +the same, like i and j). + +Error handling +~~~~~~~~~~~~~~ + +If you cherry-pick a patch that includes a ``goto`` statement (typically +for error handling), it is absolutely imperative to double check that +the target label is still correct in the branch you are backporting to. +The same goes for added ``return``, ``break``, and ``continue`` +statements. + +Error handling is typically located at the bottom of the function, so it +may not be part of the conflict even though could have been changed by +other patches. + +A good way to ensure that you review the error paths is to always use +``git diff -W`` and ``git show -W`` (AKA ``--function-context``) when +inspecting your changes. For C code, this will show you the whole +function that's being changed in a patch. One of the things that often +go wrong during backports is that something else in the function changed +on either of the branches that you're backporting from or to. By +including the whole function in the diff you get more context and can +more easily spot problems that might otherwise go unnoticed. + +Refactored code +~~~~~~~~~~~~~~~ + +Something that happens quite often is that code gets refactored by +"factoring out" a common code sequence or pattern into a helper +function. When backporting patches to an area where such a refactoring +has taken place, you effectively need to do the reverse when +backporting: a patch to a single location may need to be applied to +multiple locations in the backported version. (One giveaway for this +scenario is that a function was renamed -- but that's not always the +case.) + +To avoid incomplete backports, it's worth trying to figure out if the +patch fixes a bug that appears in more than one place. One way to do +this would be to use ``git grep``. (This is actually a good idea to do +in general, not just for backports.) If you do find that the same kind +of fix would apply to other places, it's also worth seeing if those +places exist upstream -- if they don't, it's likely the patch may need +to be adjusted. ``git log`` is your friend to figure out what happened +to these areas as ``git blame`` won't show you code that has been +removed. + +If you do find other instances of the same pattern in the upstream tree +and you're not sure whether it's also a bug, it may be worth asking the +patch author. It's not uncommon to find new bugs during backporting! + +Verifying the result +==================== + +colordiff +--------- + +Having committed a conflict-free new patch, you can now compare your +patch to the original patch. It is highly recommended that you use a +tool such as `colordiff`_ that can show two files side by side and color +them according to the changes between them:: + + colordiff -yw -W 200 <(git diff -W <upstream commit>^-) <(git diff -W HEAD^-) | less -SR + +.. _colordiff: https://www.colordiff.org/ + +Here, ``-y`` means to do a side-by-side comparison; ``-w`` ignores +whitespace, and ``-W 200`` sets the width of the output (as otherwise it +will use 130 by default, which is often a bit too little). + +The ``rev^-`` syntax is a handy shorthand for ``rev^..rev``, essentially +giving you just the diff for that single commit; also see +the official `git rev-parse documentation`_. + +.. _git rev-parse documentation: https://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand_notations + +Again, note the inclusion of ``-W`` for ``git diff``; this ensures that +you will see the full function for any function that has changed. + +One incredibly important thing that colordiff does is to highlight lines +that are different. For example, if an error-handling ``goto`` has +changed labels between the original and backported patch, colordiff will +show these side-by-side but highlighted in a different color. Thus, it +is easy to see that the two ``goto`` statements are jumping to different +labels. Likewise, lines that were not modified by either patch but +differ in the context will also be highlighted and thus stand out during +a manual inspection. + +Of course, this is just a visual inspection; the real test is building +and running the patched kernel (or program). + +Build testing +------------- + +We won't cover runtime testing here, but it can be a good idea to build +just the files touched by the patch as a quick sanity check. For the +Linux kernel you can build single files like this, assuming you have the +``.config`` and build environment set up correctly:: + + make path/to/file.o + +Note that this won't discover linker errors, so you should still do a +full build after verifying that the single file compiles. By compiling +the single file first you can avoid having to wait for a full build *in +case* there are compiler errors in any of the files you've changed. + +Runtime testing +--------------- + +Even a successful build or boot test is not necessarily enough to rule +out a missing dependency somewhere. Even though the chances are small, +there could be code changes where two independent changes to the same +file result in no conflicts, no compile-time errors, and runtime errors +only in exceptional cases. + +One concrete example of this was a pair of patches to the system call +entry code where the first patch saved/restored a register and a later +patch made use of the same register somewhere in the middle of this +sequence. Since there was no overlap between the changes, one could +cherry-pick the second patch, have no conflicts, and believe that +everything was fine, when in fact the code was now scribbling over an +unsaved register. + +Although the vast majority of errors will be caught during compilation +or by superficially exercising the code, the only way to *really* verify +a backport is to review the final patch with the same level of scrutiny +as you would (or should) give to any other patch. Having unit tests and +regression tests or other types of automatic testing can help increase +the confidence in the correctness of a backport. + +Submitting backports to stable +============================== + +As the stable maintainers try to cherry-pick mainline fixes onto their +stable kernels, they may send out emails asking for backports when when +encountering conflicts, see e.g. +<https://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/>. +These emails typically include the exact steps you need to cherry-pick +the patch to the correct tree and submit the patch. + +One thing to make sure is that your changelog conforms to the expected +format:: + + <original patch title> + + [ Upstream commit <mainline rev> ] + + <rest of the original changelog> + [ <summary of the conflicts and their resolutions> ] + Signed-off-by: <your name and email> + +The "Upstream commit" line is sometimes slightly different depending on +the stable version. Older version used this format:: + + commit <mainline rev> upstream. + +It is most common to indicate the kernel version the patch applies to +in the email subject line (using e.g. +``git send-email --subject-prefix='PATCH 6.1.y'``), but you can also put +it in the Signed-off-by:-area or below the ``---`` line. + +The stable maintainers expect separate submissions for each active +stable version, and each submission should also be tested separately. + +A few final words of advice +=========================== + +1) Approach the backporting process with humility. +2) Understand the patch you are backporting; this means reading both + the changelog and the code. +3) Be honest about your confidence in the result when submitting the + patch. +4) Ask relevant maintainers for explicit acks. + +Examples +======== + +The above shows roughly the idealized process of backporting a patch. +For a more concrete example, see this video tutorial where two patches +are backported from mainline to stable: +`Backporting Linux Kernel Patches`_. + +.. _Backporting Linux Kernel Patches: https://youtu.be/sBR7R1V2FeA diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index b48da698d6f2..bb96ca0f774b 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,7 +31,7 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version -Rust (optional) 1.71.1 rustc --version +Rust (optional) 1.73.0 rustc --version bindgen (optional) 0.65.1 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index b501cd977053..a1daa309b58d 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -66,12 +66,13 @@ lack of a better place. :maxdepth: 1 applying-patches + backporting adding-syscalls magic-number volatile-considered-harmful botching-up-ioctls clang-format - ../riscv/patch-acceptance + ../arch/riscv/patch-acceptance ../core-api/unaligned-memory-access .. only:: subproject and html diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index 09dcf6377c27..7feacc20835e 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -441,6 +441,21 @@ in a way which would break what would normally be considered uAPI. new ``netdevsim`` features must be accompanied by selftests under ``tools/testing/selftests/``. +Reviewer guidance +----------------- + +Reviewing other people's patches on the list is highly encouraged, +regardless of the level of expertise. For general guidance and +helpful tips please see :ref:`development_advancedtopics_reviews`. + +It's safe to assume that netdev maintainers know the community and the level +of expertise of the reviewers. The reviewers should not be concerned about +their comments impeding or derailing the patch flow. + +Less experienced reviewers are highly encouraged to do more in-depth +review of submissions and not focus exclusively on trivial or subjective +matters like code formatting, tags etc. + Testimonials / feedback ----------------------- diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst index 5a6993795bd2..692a3ba56cca 100644 --- a/Documentation/process/security-bugs.rst +++ b/Documentation/process/security-bugs.rst @@ -66,15 +66,32 @@ lifted, in perpetuity. Coordination with other groups ------------------------------ -The kernel security team strongly recommends that reporters of potential -security issues NEVER contact the "linux-distros" mailing list until -AFTER discussing it with the kernel security team. Do not Cc: both -lists at once. You may contact the linux-distros mailing list after a -fix has been agreed on and you fully understand the requirements that -doing so will impose on you and the kernel community. - -The different lists have different goals and the linux-distros rules do -not contribute to actually fixing any potential security problems. +While the kernel security team solely focuses on getting bugs fixed, +other groups focus on fixing issues in distros and coordinating +disclosure between operating system vendors. Coordination is usually +handled by the "linux-distros" mailing list and disclosure by the +public "oss-security" mailing list, both of which are closely related +and presented in the linux-distros wiki: +<https://oss-security.openwall.org/wiki/mailing-lists/distros> + +Please note that the respective policies and rules are different since +the 3 lists pursue different goals. Coordinating between the kernel +security team and other teams is difficult since for the kernel security +team occasional embargoes (as subject to a maximum allowed number of +days) start from the availability of a fix, while for "linux-distros" +they start from the initial post to the list regardless of the +availability of a fix. + +As such, the kernel security team strongly recommends that as a reporter +of a potential security issue you DO NOT contact the "linux-distros" +mailing list UNTIL a fix is accepted by the affected code's maintainers +and you have read the distros wiki page above and you fully understand +the requirements that contacting "linux-distros" will impose on you and +the kernel community. This also means that in general it doesn't make +sense to Cc: both lists at once, except maybe for coordination if and +while an accepted fix has not yet been merged. In other words, until a +fix is accepted do not Cc: "linux-distros", and after it's merged do not +Cc: the kernel security team. CVE assignment -------------- diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 41f1e07abfdf..1704f1c686d0 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -101,6 +101,19 @@ comment: git cherry-pick fd21073 git cherry-pick <this commit> + Note that for a patch series, you do not have to list as prerequisites the + patches present in the series itself. For example, if you have the following + patch series: + + .. code-block:: none + + patch1 + patch2 + + where patch2 depends on patch1, you do not have to list patch1 as + prerequisite of patch2 if you have already marked patch1 for stable + inclusion. + * For patches that may have kernel version prerequisites specify them using the following format in the sign-off area: diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index efac910e2659..86d346bcb8ef 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -327,6 +327,8 @@ politely and address the problems they have pointed out. When sending a next version, add a ``patch changelog`` to the cover letter or to individual patches explaining difference against previous submission (see :ref:`the_canonical_patch_format`). +Notify people that commented on your patch about new versions by adding them to +the patches CC list. See Documentation/process/email-clients.rst for recommendations on email clients and mailing list etiquette. @@ -366,10 +368,10 @@ busy people and may not get to your patch right away. Once upon a time, patches used to disappear into the void without comment, but the development process works more smoothly than that now. You should -receive comments within a week or so; if that does not happen, make sure -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. +receive comments within a few weeks (typically 2-3); if that does not +happen, make sure 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:: diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst index e599be2cec9b..965f2db529e0 100644 --- a/Documentation/rust/index.rst +++ b/Documentation/rust/index.rst @@ -6,6 +6,25 @@ Rust Documentation related to Rust within the kernel. To start using Rust in the kernel, please read the quick-start.rst guide. + +The Rust experiment +------------------- + +The Rust support was merged in v6.1 into mainline in order to help in +determining whether Rust as a language was suitable for the kernel, i.e. worth +the tradeoffs. + +Currently, the Rust support is primarily intended for kernel developers and +maintainers interested in the Rust support, so that they can start working on +abstractions and drivers, as well as helping the development of infrastructure +and tools. + +If you are an end user, please note that there are currently no in-tree +drivers/modules suitable or intended for production use, and that the Rust +support is still in development/experimental, especially for certain kernel +configurations. + + .. only:: rustdoc and html You can also browse `rustdoc documentation <rustdoc/kernel/index.html>`_. diff --git a/Documentation/scheduler/sched-arch.rst b/Documentation/scheduler/sched-arch.rst index 505cd27f9a92..ed07efea7d02 100644 --- a/Documentation/scheduler/sched-arch.rst +++ b/Documentation/scheduler/sched-arch.rst @@ -10,7 +10,7 @@ Context switch By default, the switch_to arch function is called with the runqueue locked. This is usually not a problem unless switch_to may need to take the runqueue lock. This is usually due to a wake up operation in -the context switch. See arch/ia64/include/asm/switch_to.h for an example. +the context switch. To request the scheduler call switch_to with the runqueue unlocked, you must `#define __ARCH_WANT_UNLOCKED_CTXSW` in a header file @@ -68,7 +68,5 @@ Possible arch/ problems Possible arch problems I found (and either tried to fix or didn't): -ia64 - is safe_halt call racy vs interrupts? (does it sleep?) (See #4a) - sparc - IRQs on at this point(?), change local_irq_save to _disable. - TODO: needs secondary CPUs to disable preempt (See #1) diff --git a/Documentation/scheduler/sched-capacity.rst b/Documentation/scheduler/sched-capacity.rst index e2c1cf743158..de414b33dd2a 100644 --- a/Documentation/scheduler/sched-capacity.rst +++ b/Documentation/scheduler/sched-capacity.rst @@ -39,14 +39,15 @@ per Hz, leading to:: ------------------- Two different capacity values are used within the scheduler. A CPU's -``capacity_orig`` is its maximum attainable capacity, i.e. its maximum -attainable performance level. A CPU's ``capacity`` is its ``capacity_orig`` to -which some loss of available performance (e.g. time spent handling IRQs) is -subtracted. +``original capacity`` is its maximum attainable capacity, i.e. its maximum +attainable performance level. This original capacity is returned by +the function arch_scale_cpu_capacity(). A CPU's ``capacity`` is its ``original +capacity`` to which some loss of available performance (e.g. time spent +handling IRQs) is subtracted. Note that a CPU's ``capacity`` is solely intended to be used by the CFS class, -while ``capacity_orig`` is class-agnostic. The rest of this document will use -the term ``capacity`` interchangeably with ``capacity_orig`` for the sake of +while ``original capacity`` is class-agnostic. The rest of this document will use +the term ``capacity`` interchangeably with ``original capacity`` for the sake of brevity. 1.3 Platform examples diff --git a/Documentation/scheduler/sched-energy.rst b/Documentation/scheduler/sched-energy.rst index fc853c8cc346..70e2921ef725 100644 --- a/Documentation/scheduler/sched-energy.rst +++ b/Documentation/scheduler/sched-energy.rst @@ -359,32 +359,9 @@ in milli-Watts or in an 'abstract scale'. 6.3 - Energy Model complexity ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The task wake-up path is very latency-sensitive. When the EM of a platform is -too complex (too many CPUs, too many performance domains, too many performance -states, ...), the cost of using it in the wake-up path can become prohibitive. -The energy-aware wake-up algorithm has a complexity of: - - C = Nd * (Nc + Ns) - -with: Nd the number of performance domains; Nc the number of CPUs; and Ns the -total number of OPPs (ex: for two perf. domains with 4 OPPs each, Ns = 8). - -A complexity check is performed at the root domain level, when scheduling -domains are built. EAS will not start on a root domain if its C happens to be -higher than the completely arbitrary EM_MAX_COMPLEXITY threshold (2048 at the -time of writing). - -If you really want to use EAS but the complexity of your platform's Energy -Model is too high to be used with a single root domain, you're left with only -two possible options: - - 1. split your system into separate, smaller, root domains using exclusive - cpusets and enable EAS locally on each of them. This option has the - benefit to work out of the box but the drawback of preventing load - balance between root domains, which can result in an unbalanced system - overall; - 2. submit patches to reduce the complexity of the EAS wake-up algorithm, - hence enabling it to cope with larger EMs in reasonable time. +EAS does not impose any complexity limit on the number of PDs/OPPs/CPUs but +restricts the number of CPUs to EM_MAX_NUM_CPUS to prevent overflows during +the energy estimation. 6.4 - Schedutil governor diff --git a/Documentation/scheduler/sched-rt-group.rst b/Documentation/scheduler/sched-rt-group.rst index 655a096ec8fb..d685609ed3d7 100644 --- a/Documentation/scheduler/sched-rt-group.rst +++ b/Documentation/scheduler/sched-rt-group.rst @@ -39,10 +39,10 @@ Most notable: 1.1 The problem --------------- -Realtime scheduling is all about determinism, a group has to be able to rely on +Real-time scheduling is all about determinism, a group has to be able to rely on the amount of bandwidth (eg. CPU time) being constant. In order to schedule -multiple groups of realtime tasks, each group must be assigned a fixed portion -of the CPU time available. Without a minimum guarantee a realtime group can +multiple groups of real-time tasks, each group must be assigned a fixed portion +of the CPU time available. Without a minimum guarantee a real-time group can obviously fall short. A fuzzy upper limit is of no use since it cannot be relied upon. Which leaves us with just the single fixed portion. @@ -50,14 +50,14 @@ relied upon. Which leaves us with just the single fixed portion. ---------------- CPU time is divided by means of specifying how much time can be spent running -in a given period. We allocate this "run time" for each realtime group which -the other realtime groups will not be permitted to use. +in a given period. We allocate this "run time" for each real-time group which +the other real-time groups will not be permitted to use. -Any time not allocated to a realtime group will be used to run normal priority +Any time not allocated to a real-time group will be used to run normal priority tasks (SCHED_OTHER). Any allocated run time not used will also be picked up by SCHED_OTHER. -Let's consider an example: a frame fixed realtime renderer must deliver 25 +Let's consider an example: a frame fixed real-time renderer must deliver 25 frames a second, which yields a period of 0.04s per frame. Now say it will also have to play some music and respond to input, leaving it with around 80% CPU time dedicated for the graphics. We can then give this group a run time of 0.8 @@ -70,7 +70,7 @@ needs only about 3% CPU time to do so, it can do with a 0.03 * 0.005s = of 0.00015s. The remaining CPU time will be used for user input and other tasks. Because -realtime tasks have explicitly allocated the CPU time they need to perform +real-time tasks have explicitly allocated the CPU time they need to perform their tasks, buffer underruns in the graphics or audio can be eliminated. NOTE: the above example is not fully implemented yet. We still @@ -87,18 +87,20 @@ lack an EDF scheduler to make non-uniform periods usable. The system wide settings are configured under the /proc virtual file system: /proc/sys/kernel/sched_rt_period_us: - The scheduling period that is equivalent to 100% CPU bandwidth + The scheduling period that is equivalent to 100% CPU bandwidth. /proc/sys/kernel/sched_rt_runtime_us: - A global limit on how much time realtime scheduling may use. Even without - CONFIG_RT_GROUP_SCHED enabled, this will limit time reserved to realtime - processes. With CONFIG_RT_GROUP_SCHED it signifies the total bandwidth - available to all realtime groups. + A global limit on how much time real-time scheduling may use. This is always + less or equal to the period_us, as it denotes the time allocated from the + period_us for the real-time tasks. Even without CONFIG_RT_GROUP_SCHED enabled, + this will limit time reserved to real-time processes. With + CONFIG_RT_GROUP_SCHED=y it signifies the total bandwidth available to all + real-time groups. * Time is specified in us because the interface is s32. This gives an operating range from 1us to about 35 minutes. * sched_rt_period_us takes values from 1 to INT_MAX. - * sched_rt_runtime_us takes values from -1 to (INT_MAX - 1). + * sched_rt_runtime_us takes values from -1 to sched_rt_period_us. * A run time of -1 specifies runtime == period, ie. no limit. @@ -108,7 +110,7 @@ The system wide settings are configured under the /proc virtual file system: The default values for sched_rt_period_us (1000000 or 1s) and sched_rt_runtime_us (950000 or 0.95s). This gives 0.05s to be used by SCHED_OTHER (non-RT tasks). These defaults were chosen so that a run-away -realtime tasks will not lock up the machine but leave a little time to recover +real-time tasks will not lock up the machine but leave a little time to recover it. By setting runtime to -1 you'd get the old behaviour back. By default all bandwidth is assigned to the root group and new groups get the @@ -116,10 +118,10 @@ period from /proc/sys/kernel/sched_rt_period_us and a run time of 0. If you want to assign bandwidth to another group, reduce the root group's bandwidth and assign some or all of the difference to another group. -Realtime group scheduling means you have to assign a portion of total CPU -bandwidth to the group before it will accept realtime tasks. Therefore you will -not be able to run realtime tasks as any user other than root until you have -done that, even if the user has the rights to run processes with realtime +Real-time group scheduling means you have to assign a portion of total CPU +bandwidth to the group before it will accept real-time tasks. Therefore you will +not be able to run real-time tasks as any user other than root until you have +done that, even if the user has the rights to run processes with real-time priority! diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst index 6ed8d2fa6f9e..59f8fc106cb0 100644 --- a/Documentation/security/index.rst +++ b/Documentation/security/index.rst @@ -6,6 +6,7 @@ Security Documentation :maxdepth: 1 credentials + snp-tdx-threat-model IMA-templates keys/index lsm diff --git a/Documentation/security/snp-tdx-threat-model.rst b/Documentation/security/snp-tdx-threat-model.rst new file mode 100644 index 000000000000..ec66f2ed80c9 --- /dev/null +++ b/Documentation/security/snp-tdx-threat-model.rst @@ -0,0 +1,253 @@ +====================================================== +Confidential Computing in Linux for x86 virtualization +====================================================== + +.. contents:: :local: + +By: Elena Reshetova <elena.reshetova@intel.com> and Carlos Bilbao <carlos.bilbao@amd.com> + +Motivation +========== + +Kernel developers working on confidential computing for virtualized +environments in x86 operate under a set of assumptions regarding the Linux +kernel threat model that differ from the traditional view. Historically, +the Linux threat model acknowledges attackers residing in userspace, as +well as a limited set of external attackers that are able to interact with +the kernel through various networking or limited HW-specific exposed +interfaces (USB, thunderbolt). The goal of this document is to explain +additional attack vectors that arise in the confidential computing space +and discuss the proposed protection mechanisms for the Linux kernel. + +Overview and terminology +======================== + +Confidential Computing (CoCo) is a broad term covering a wide range of +security technologies that aim to protect the confidentiality and integrity +of data in use (vs. data at rest or data in transit). At its core, CoCo +solutions provide a Trusted Execution Environment (TEE), where secure data +processing can be performed and, as a result, they are typically further +classified into different subtypes depending on the SW that is intended +to be run in TEE. This document focuses on a subclass of CoCo technologies +that are targeting virtualized environments and allow running Virtual +Machines (VM) inside TEE. From now on in this document will be referring +to this subclass of CoCo as 'Confidential Computing (CoCo) for the +virtualized environments (VE)'. + +CoCo, in the virtualization context, refers to a set of HW and/or SW +technologies that allow for stronger security guarantees for the SW running +inside a CoCo VM. Namely, confidential computing allows its users to +confirm the trustworthiness of all SW pieces to include in its reduced +Trusted Computing Base (TCB) given its ability to attest the state of these +trusted components. + +While the concrete implementation details differ between technologies, all +available mechanisms aim to provide increased confidentiality and +integrity for the VM's guest memory and execution state (vCPU registers), +more tightly controlled guest interrupt injection, as well as some +additional mechanisms to control guest-host page mapping. More details on +the x86-specific solutions can be found in +:doc:`Intel Trust Domain Extensions (TDX) </arch/x86/tdx>` and +`AMD Memory Encryption <https://www.amd.com/system/files/techdocs/sev-snp-strengthening-vm-isolation-with-integrity-protection-and-more.pdf>`_. + +The basic CoCo guest layout includes the host, guest, the interfaces that +communicate guest and host, a platform capable of supporting CoCo VMs, and +a trusted intermediary between the guest VM and the underlying platform +that acts as a security manager. The host-side virtual machine monitor +(VMM) typically consists of a subset of traditional VMM features and +is still in charge of the guest lifecycle, i.e. create or destroy a CoCo +VM, manage its access to system resources, etc. However, since it +typically stays out of CoCo VM TCB, its access is limited to preserve the +security objectives. + +In the following diagram, the "<--->" lines represent bi-directional +communication channels or interfaces between the CoCo security manager and +the rest of the components (data flow for guest, host, hardware) :: + + +-------------------+ +-----------------------+ + | CoCo guest VM |<---->| | + +-------------------+ | | + | Interfaces | | CoCo security manager | + +-------------------+ | | + | Host VMM |<---->| | + +-------------------+ | | + | | + +--------------------+ | | + | CoCo platform |<--->| | + +--------------------+ +-----------------------+ + +The specific details of the CoCo security manager vastly diverge between +technologies. For example, in some cases, it will be implemented in HW +while in others it may be pure SW. + +Existing Linux kernel threat model +================================== + +The overall components of the current Linux kernel threat model are:: + + +-----------------------+ +-------------------+ + | |<---->| Userspace | + | | +-------------------+ + | External attack | | Interfaces | + | vectors | +-------------------+ + | |<---->| Linux Kernel | + | | +-------------------+ + +-----------------------+ +-------------------+ + | Bootloader/BIOS | + +-------------------+ + +-------------------+ + | HW platform | + +-------------------+ + +There is also communication between the bootloader and the kernel during +the boot process, but this diagram does not represent it explicitly. The +"Interfaces" box represents the various interfaces that allow +communication between kernel and userspace. This includes system calls, +kernel APIs, device drivers, etc. + +The existing Linux kernel threat model typically assumes execution on a +trusted HW platform with all of the firmware and bootloaders included on +its TCB. The primary attacker resides in the userspace, and all of the data +coming from there is generally considered untrusted, unless userspace is +privileged enough to perform trusted actions. In addition, external +attackers are typically considered, including those with access to enabled +external networks (e.g. Ethernet, Wireless, Bluetooth), exposed hardware +interfaces (e.g. USB, Thunderbolt), and the ability to modify the contents +of disks offline. + +Regarding external attack vectors, it is interesting to note that in most +cases external attackers will try to exploit vulnerabilities in userspace +first, but that it is possible for an attacker to directly target the +kernel; particularly if the host has physical access. Examples of direct +kernel attacks include the vulnerabilities CVE-2019-19524, CVE-2022-0435 +and CVE-2020-24490. + +Confidential Computing threat model and its security objectives +=============================================================== + +Confidential Computing adds a new type of attacker to the above list: a +potentially misbehaving host (which can also include some part of a +traditional VMM or all of it), which is typically placed outside of the +CoCo VM TCB due to its large SW attack surface. It is important to note +that this doesn’t imply that the host or VMM are intentionally +malicious, but that there exists a security value in having a small CoCo +VM TCB. This new type of adversary may be viewed as a more powerful type +of external attacker, as it resides locally on the same physical machine +(in contrast to a remote network attacker) and has control over the guest +kernel communication with most of the HW:: + + +------------------------+ + | CoCo guest VM | + +-----------------------+ | +-------------------+ | + | |<--->| | Userspace | | + | | | +-------------------+ | + | External attack | | | Interfaces | | + | vectors | | +-------------------+ | + | |<--->| | Linux Kernel | | + | | | +-------------------+ | + +-----------------------+ | +-------------------+ | + | | Bootloader/BIOS | | + +-----------------------+ | +-------------------+ | + | |<--->+------------------------+ + | | | Interfaces | + | | +------------------------+ + | CoCo security |<--->| Host/Host-side VMM | + | manager | +------------------------+ + | | +------------------------+ + | |<--->| CoCo platform | + +-----------------------+ +------------------------+ + +While traditionally the host has unlimited access to guest data and can +leverage this access to attack the guest, the CoCo systems mitigate such +attacks by adding security features like guest data confidentiality and +integrity protection. This threat model assumes that those features are +available and intact. + +The **Linux kernel CoCo VM security objectives** can be summarized as follows: + +1. Preserve the confidentiality and integrity of CoCo guest's private +memory and registers. + +2. Prevent privileged escalation from a host into a CoCo guest Linux kernel. +While it is true that the host (and host-side VMM) requires some level of +privilege to create, destroy, or pause the guest, part of the goal of +preventing privileged escalation is to ensure that these operations do not +provide a pathway for attackers to gain access to the guest's kernel. + +The above security objectives result in two primary **Linux kernel CoCo +VM assets**: + +1. Guest kernel execution context. +2. Guest kernel private memory. + +The host retains full control over the CoCo guest resources, and can deny +access to them at any time. Examples of resources include CPU time, memory +that the guest can consume, network bandwidth, etc. Because of this, the +host Denial of Service (DoS) attacks against CoCo guests are beyond the +scope of this threat model. + +The **Linux CoCo VM attack surface** is any interface exposed from a CoCo +guest Linux kernel towards an untrusted host that is not covered by the +CoCo technology SW/HW protection. This includes any possible +side-channels, as well as transient execution side channels. Examples of +explicit (not side-channel) interfaces include accesses to port I/O, MMIO +and DMA interfaces, access to PCI configuration space, VMM-specific +hypercalls (towards Host-side VMM), access to shared memory pages, +interrupts allowed to be injected into the guest kernel by the host, as +well as CoCo technology-specific hypercalls, if present. Additionally, the +host in a CoCo system typically controls the process of creating a CoCo +guest: it has a method to load into a guest the firmware and bootloader +images, the kernel image together with the kernel command line. All of this +data should also be considered untrusted until its integrity and +authenticity is established via attestation. + +The table below shows a threat matrix for the CoCo guest Linux kernel but +does not discuss potential mitigation strategies. The matrix refers to +CoCo-specific versions of the guest, host and platform. + +.. list-table:: CoCo Linux guest kernel threat matrix + :widths: auto + :align: center + :header-rows: 1 + + * - Threat name + - Threat description + + * - Guest malicious configuration + - A misbehaving host modifies one of the following guest's + configuration: + + 1. Guest firmware or bootloader + + 2. Guest kernel or module binaries + + 3. Guest command line parameters + + This allows the host to break the integrity of the code running + inside a CoCo guest, and violates the CoCo security objectives. + + * - CoCo guest data attacks + - A misbehaving host retains full control of the CoCo guest's data + in-transit between the guest and the host-managed physical or + virtual devices. This allows any attack against confidentiality, + integrity or freshness of such data. + + * - Malformed runtime input + - A misbehaving host injects malformed input via any communication + interface used by the guest's kernel code. If the code is not + prepared to handle this input correctly, this can result in a host + --> guest kernel privilege escalation. This includes traditional + side-channel and/or transient execution attack vectors. + + * - Malicious runtime input + - A misbehaving host injects a specific input value via any + communication interface used by the guest's kernel code. The + difference with the previous attack vector (malformed runtime input) + is that this input is not malformed, but its value is crafted to + impact the guest's kernel security. Examples of such inputs include + providing a malicious time to the guest or the entropy to the guest + random number generator. Additionally, the timing of such events can + be an attack vector on its own, if it results in a particular guest + kernel action (i.e. processing of a host-injected interrupt). + resistant to supplied host input. + diff --git a/Documentation/sound/soc/codec-to-codec.rst b/Documentation/sound/soc/codec-to-codec.rst index 4eaa9a0c41fc..0418521b6e03 100644 --- a/Documentation/sound/soc/codec-to-codec.rst +++ b/Documentation/sound/soc/codec-to-codec.rst @@ -70,7 +70,8 @@ file: .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_CBM_CFM, .ignore_suspend = 1, - .params = &dsp_codec_params, + .c2c_params = &dsp_codec_params, + .num_c2c_params = 1, }, { .name = "DSP-CODEC", @@ -81,12 +82,13 @@ file: .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_CBM_CFM, .ignore_suspend = 1, - .params = &dsp_codec_params, + .c2c_params = &dsp_codec_params, + .num_c2c_params = 1, }, Above code snippet is motivated from sound/soc/samsung/speyside.c. -Note the "params" callback which lets the dapm know that this +Note the "c2c_params" callback which lets the dapm know that this dai_link is a codec to codec connection. In dapm core a route is created between cpu_dai playback widget diff --git a/Documentation/sound/soc/dpcm.rst b/Documentation/sound/soc/dpcm.rst index 77f67ded53de..2d7ad1d91504 100644 --- a/Documentation/sound/soc/dpcm.rst +++ b/Documentation/sound/soc/dpcm.rst @@ -368,7 +368,8 @@ The machine driver sets some additional parameters to the DAI link i.e. .codec_name = "modem", .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_CBM_CFM, - .params = &dai_params, + .c2c_params = &dai_params, + .num_c2c_params = 1, } < ... more DAI links here ... > diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index a99716bf44b5..4eb150bf509c 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -93,7 +93,7 @@ def markup_ctype_refs(match): # RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') def markup_c_expr(match): - return '\ ``' + match.group(2) + '``\ ' + return '\\ ``' + match.group(2) + '``\\ ' # # Parse Sphinx 3.x C markups, replacing them by backward-compatible ones @@ -151,7 +151,7 @@ class CObject(Base_CObject): def handle_func_like_macro(self, sig, signode): u"""Handles signatures of function-like macros. - If the objtype is 'function' and the the signature ``sig`` is a + If the objtype is 'function' and the signature ``sig`` is a function-like macro, the name of the macro is returned. Otherwise ``False`` is returned. """ diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index b5feb5b1d905..49797c55479c 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -138,7 +138,7 @@ class KernelCmd(Directive): code_block += "\n " + l lines = code_block + "\n\n" - line_regex = re.compile("^\.\. LINENO (\S+)\#([0-9]+)$") + line_regex = re.compile(r"^\.\. LINENO (\S+)\#([0-9]+)$") ln = 0 n = 0 f = fname diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index 27b701ed3681..b5fa2f0542a5 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -104,7 +104,7 @@ class KernelFeat(Directive): lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) - line_regex = re.compile("^\.\. FILE (\S+)$") + line_regex = re.compile(r"^\.\. FILE (\S+)$") out_lines = "" diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 9395892c7ba3..7acf09963daa 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -130,7 +130,7 @@ class KernelDocDirective(Directive): result = ViewList() lineoffset = 0; - line_regex = re.compile("^\.\. LINENO ([0-9]+)$") + line_regex = re.compile(r"^\.\. LINENO ([0-9]+)$") for line in lines: match = line_regex.search(line) if match: @@ -138,7 +138,7 @@ class KernelDocDirective(Directive): lineoffset = int(match.group(1)) - 1 # we must eat our comments since the upset the markup else: - doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno) + doc = str(env.srcdir) + "/" + env.docname + ":" + str(self.lineno) result.append(line, doc + ": " + filename, lineoffset) lineoffset += 1 diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index cefdbb7e7523..13e885bbd499 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -309,7 +309,7 @@ def convert_image(img_node, translator, src_fname=None): if dst_fname: # the builder needs not to copy one more time, so pop it if exists. translator.builder.images.pop(img_node['uri'], None) - _name = dst_fname[len(translator.builder.outdir) + 1:] + _name = dst_fname[len(str(translator.builder.outdir)) + 1:] if isNewer(dst_fname, src_fname): kernellog.verbose(app, diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index 328b3631a585..dcad0fff4723 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -77,7 +77,7 @@ class MaintainersInclude(Include): line = line.rstrip() # Linkify all non-wildcard refs to ReST files in Documentation/. - pat = '(Documentation/([^\s\?\*]*)\.rst)' + pat = r'(Documentation/([^\s\?\*]*)\.rst)' m = re.search(pat, line) if m: # maintainers.rst is in a subdirectory, so include "../". @@ -90,11 +90,11 @@ class MaintainersInclude(Include): output = "| %s" % (line.replace("\\", "\\\\")) # Look for and record field letter to field name mappings: # R: Designated *reviewer*: FullName <address@domain> - m = re.search("\s(\S):\s", line) + m = re.search(r"\s(\S):\s", line) if m: field_letter = m.group(1) if field_letter and not field_letter in fields: - m = re.search("\*([^\*]+)\*", line) + m = re.search(r"\*([^\*]+)\*", line) if m: fields[field_letter] = m.group(1) elif subsystems: @@ -112,7 +112,7 @@ class MaintainersInclude(Include): field_content = "" # Collapse whitespace in subsystem name. - heading = re.sub("\s+", " ", line) + heading = re.sub(r"\s+", " ", line) output = output + "%s\n%s" % (heading, "~" * len(heading)) field_prev = "" else: diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index 90a0535a932a..930dc23998a0 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -35,6 +35,7 @@ Human interfaces sound/index gpu/index fb/index + leds/index Networking interfaces --------------------- @@ -70,7 +71,6 @@ Storage interfaces fpga/index i2c/index iio/index - leds/index pcmcia/index spi/index w1/index diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst index fc7ce76eab65..f825970a1495 100644 --- a/Documentation/trace/kprobes.rst +++ b/Documentation/trace/kprobes.rst @@ -315,7 +315,6 @@ architectures: - i386 (Supports jump optimization) - x86_64 (AMD-64, EM64T) (Supports jump optimization) - ppc64 -- ia64 (Does not support probes on instruction slot1.) - sparc64 (Return probes not yet implemented.) - arm - ppc diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index e24c009789a0..048dc0dbce64 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -107,14 +107,14 @@ GetOptions( ); # Defaults for dynamically discovered regex's -my $regex_direct_begin_default = 'order=([0-9]*) may_writepage=([0-9]*) gfp_flags=([A-Z_|]*)'; +my $regex_direct_begin_default = 'order=([0-9]*) gfp_flags=([A-Z_|]*)'; my $regex_direct_end_default = 'nr_reclaimed=([0-9]*)'; my $regex_kswapd_wake_default = 'nid=([0-9]*) order=([0-9]*)'; my $regex_kswapd_sleep_default = 'nid=([0-9]*)'; -my $regex_wakeup_kswapd_default = 'nid=([0-9]*) zid=([0-9]*) order=([0-9]*) gfp_flags=([A-Z_|]*)'; -my $regex_lru_isolate_default = 'isolate_mode=([0-9]*) classzone_idx=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_skipped=([0-9]*) nr_taken=([0-9]*) lru=([a-z_]*)'; +my $regex_wakeup_kswapd_default = 'nid=([0-9]*) order=([0-9]*) gfp_flags=([A-Z_|]*)'; +my $regex_lru_isolate_default = 'classzone=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_skipped=([0-9]*) nr_taken=([0-9]*) lru=([a-z_]*)'; my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) nr_dirty=([0-9]*) nr_writeback=([0-9]*) nr_congested=([0-9]*) nr_immediate=([0-9]*) nr_activate_anon=([0-9]*) nr_activate_file=([0-9]*) nr_ref_keep=([0-9]*) nr_unmap_fail=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; -my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_scanned=([0-9]*) nr_rotated=([0-9]*) priority=([0-9]*)'; +my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_taken=([0-9]*) nr_active=([0-9]*) nr_deactivated=([0-9]*) nr_referenced=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)' ; my $regex_writepage_default = 'page=([0-9a-f]*) pfn=([0-9]*) flags=([A-Z_|]*)'; # Dyanically discovered regex @@ -184,8 +184,7 @@ sub generate_traceevent_regex { $regex_direct_begin = generate_traceevent_regex( "vmscan/mm_vmscan_direct_reclaim_begin", $regex_direct_begin_default, - "order", "may_writepage", - "gfp_flags"); + "order", "gfp_flags"); $regex_direct_end = generate_traceevent_regex( "vmscan/mm_vmscan_direct_reclaim_end", $regex_direct_end_default, @@ -201,11 +200,11 @@ $regex_kswapd_sleep = generate_traceevent_regex( $regex_wakeup_kswapd = generate_traceevent_regex( "vmscan/mm_vmscan_wakeup_kswapd", $regex_wakeup_kswapd_default, - "nid", "zid", "order", "gfp_flags"); + "nid", "order", "gfp_flags"); $regex_lru_isolate = generate_traceevent_regex( "vmscan/mm_vmscan_lru_isolate", $regex_lru_isolate_default, - "isolate_mode", "classzone_idx", "order", + "classzone", "order", "nr_requested", "nr_scanned", "nr_skipped", "nr_taken", "lru"); $regex_lru_shrink_inactive = generate_traceevent_regex( @@ -218,11 +217,10 @@ $regex_lru_shrink_inactive = generate_traceevent_regex( $regex_lru_shrink_active = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_active", $regex_lru_shrink_active_default, - "nid", "zid", - "lru", - "nr_scanned", "nr_rotated", "priority"); + "nid", "nr_taken", "nr_active", "nr_deactivated", "nr_referenced", + "priority", "flags"); $regex_writepage = generate_traceevent_regex( - "vmscan/mm_vmscan_writepage", + "vmscan/mm_vmscan_write_folio", $regex_writepage_default, "page", "pfn", "flags"); @@ -371,7 +369,7 @@ EVENT_PROCESS: print " $regex_wakeup_kswapd\n"; next; } - my $order = $3; + my $order = $2; $perprocesspid{$process_pid}->{MM_VMSCAN_WAKEUP_KSWAPD_PERORDER}[$order]++; } elsif ($tracepoint eq "mm_vmscan_lru_isolate") { $details = $6; @@ -381,18 +379,14 @@ EVENT_PROCESS: print " $regex_lru_isolate/o\n"; next; } - my $isolate_mode = $1; - my $nr_scanned = $5; - my $file = $8; - - # To closer match vmstat scanning statistics, only count isolate_both - # and isolate_inactive as scanning. isolate_active is rotation - # isolate_inactive == 1 - # isolate_active == 2 - # isolate_both == 3 - if ($isolate_mode != 2) { + my $nr_scanned = $4; + my $lru = $7; + + # To closer match vmstat scanning statistics, only count + # inactive lru as scanning + if ($lru =~ /inactive_/) { $perprocesspid{$process_pid}->{HIGH_NR_SCANNED} += $nr_scanned; - if ($file =~ /_file/) { + if ($lru =~ /_file/) { $perprocesspid{$process_pid}->{HIGH_NR_FILE_SCANNED} += $nr_scanned; } else { $perprocesspid{$process_pid}->{HIGH_NR_ANON_SCANNED} += $nr_scanned; diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst index f9530d0ac5d3..d8f12442aaa6 100644 --- a/Documentation/trace/user_events.rst +++ b/Documentation/trace/user_events.rst @@ -14,6 +14,11 @@ Programs can view status of the events via /sys/kernel/tracing/user_events_status and can both register and write data out via /sys/kernel/tracing/user_events_data. +Programs can also use /sys/kernel/tracing/dynamic_events to register and +delete user based events via the u: prefix. The format of the command to +dynamic_events is the same as the ioctl with the u: prefix applied. This +requires CAP_PERFMON due to the event persisting, otherwise -EPERM is returned. + Typically programs will register a set of events that they wish to expose to tools that can read trace_events (such as ftrace and perf). The registration process tells the kernel which address and bit to reflect if any tool has @@ -45,7 +50,7 @@ This command takes a packed struct user_reg as an argument:: /* Input: Enable size in bytes at address */ __u8 enable_size; - /* Input: Flags for future use, set to 0 */ + /* Input: Flags to use, if any */ __u16 flags; /* Input: Address to update when enabled */ @@ -69,7 +74,7 @@ The struct user_reg requires all the above inputs to be set appropriately. This must be 4 (32-bit) or 8 (64-bit). 64-bit values are only allowed to be used on 64-bit kernels, however, 32-bit can be used on all kernels. -+ flags: The flags to use, if any. For the initial version this must be 0. ++ flags: The flags to use, if any. Callers should first attempt to use flags and retry without flags to ensure support for lower versions of the kernel. If a flag is not supported -EINVAL is returned. @@ -80,6 +85,13 @@ The struct user_reg requires all the above inputs to be set appropriately. + name_args: The name and arguments to describe the event, see command format for details. +The following flags are currently supported. + ++ USER_EVENT_REG_PERSIST: The event will not delete upon the last reference + closing. Callers may use this if an event should exist even after the + process closes or unregisters the event. Requires CAP_PERFMON otherwise + -EPERM is returned. + Upon successful registration the following is set. + write_index: The index to use for this file descriptor that represents this @@ -141,7 +153,10 @@ event (in both user and kernel space). User programs should use a separate file to request deletes than the one used for registration due to this. **NOTE:** By default events will auto-delete when there are no references left -to the event. Flags in the future may change this logic. +to the event. If programs do not want auto-delete, they must use the +USER_EVENT_REG_PERSIST flag when registering the event. Once that flag is used +the event exists until DIAG_IOCSDEL is invoked. Both register and delete of an +event that persists requires CAP_PERFMON, otherwise -EPERM is returned. Unregistering ------------- diff --git a/Documentation/translations/it_IT/riscv/patch-acceptance.rst b/Documentation/translations/it_IT/riscv/patch-acceptance.rst index edf67252b3fb..2d7afb1f6959 100644 --- a/Documentation/translations/it_IT/riscv/patch-acceptance.rst +++ b/Documentation/translations/it_IT/riscv/patch-acceptance.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :doc:`../../../riscv/patch-acceptance` +:Original: :doc:`../../../arch/riscv/patch-acceptance` :Translator: Federico Vaga <federico.vaga@vaga.pv.it> arch/riscv linee guida alla manutenzione per gli sviluppatori diff --git a/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst b/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..c261b428b3f0 --- /dev/null +++ b/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst @@ -0,0 +1,341 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/embargoed-hardware-issues.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +Problemas de hardware embargados +================================ + +Alcance +------- + +Los problemas de hardware que resultan en problemas de seguridad son una +categorÃa diferente de errores de seguridad que los errores de software +puro que solo afectan al kernel de Linux. + +Los problemas de hardware como Meltdown, Spectre, L1TF, etc. deben +tratarse de manera diferente porque usualmente afectan a todos los +sistemas operativos (“OSâ€) y, por lo tanto, necesitan coordinación entre +vendedores diferentes de OS, distribuciones, vendedores de hardware y +otras partes. Para algunos de los problemas, las mitigaciones de software +pueden depender de actualizaciones de microcódigo o firmware, los cuales +necesitan una coordinación adicional. + +.. _Contacto: + +Contacto +-------- + +El equipo de seguridad de hardware del kernel de Linux es separado del +equipo regular de seguridad del kernel de Linux. + +El equipo solo maneja la coordinación de los problemas de seguridad de +hardware embargados. Los informes de errores de seguridad de software puro +en el kernel de Linux no son manejados por este equipo y el "reportero" +(quien informa del error) será guiado a contactar el equipo de seguridad +del kernel de Linux (:doc:`errores de seguridad <security-bugs>`) en su +lugar. + +El equipo puede contactar por correo electrónico en +<hardware-security@kernel.org>. Esta es una lista privada de oficiales de +seguridad que lo ayudarán a coordinar un problema de acuerdo con nuestro +proceso documentado. + +La lista esta encriptada y el correo electrónico a la lista puede ser +enviado por PGP o S/MIME encriptado y debe estar firmado con la llave de +PGP del reportero o el certificado de S/MIME. La llave de PGP y el +certificado de S/MIME de la lista están disponibles en las siguientes +URLs: + + - PGP: https://www.kernel.org/static/files/hardware-security.asc + - S/MIME: https://www.kernel.org/static/files/hardware-security.crt + +Si bien los problemas de seguridad del hardware a menudo son manejados por +el vendedor de hardware afectado, damos la bienvenida al contacto de +investigadores o individuos que hayan identificado una posible falla de +hardware. + +Oficiales de seguridad de hardware +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +El equipo actual de oficiales de seguridad de hardware: + + - Linus Torvalds (Linux Foundation Fellow) + - Greg Kroah-Hartman (Linux Foundation Fellow) + - Thomas Gleixner (Linux Foundation Fellow) + +Operación de listas de correo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Las listas de correo encriptadas que se utilizan en nuestro proceso están +alojados en la infraestructura de IT de la Fundación Linux. Al proporcionar +este servicio, los miembros del personal de operaciones de IT de la +Fundación Linux técnicamente tienen la capacidad de acceder a la +información embargada, pero están obligados a la confidencialidad por su +contrato de trabajo. El personal de IT de la Fundación Linux también es +responsable para operar y administrar el resto de la infraestructura de +kernel.org. + +El actual director de infraestructura de proyecto de IT de la Fundación +Linux es Konstantin Ryabitsev. + +Acuerdos de no divulgación +-------------------------- + +El equipo de seguridad de hardware del kernel de Linux no es un organismo +formal y, por lo tanto, no puede firmar cualquier acuerdo de no +divulgación. La comunidad del kernel es consciente de la naturaleza +delicada de tales problemas y ofrece un Memorando de Entendimiento en su +lugar. + +Memorando de Entendimiento +-------------------------- + +La comunidad del kernel de Linux tiene una comprensión profunda del +requisito de mantener los problemas de seguridad de hardware bajo embargo +para la coordinación entre diferentes vendedores de OS, distribuidores, +vendedores de hardware y otras partes. + +La comunidad del kernel de Linux ha manejado con éxito los problemas de +seguridad del hardware en el pasado y tiene los mecanismos necesarios para +permitir el desarrollo compatible con la comunidad bajo restricciones de +embargo. + +La comunidad del kernel de Linux tiene un equipo de seguridad de hardware +dedicado para el contacto inicial, el cual supervisa el proceso de manejo +de tales problemas bajo las reglas de embargo. + +El equipo de seguridad de hardware identifica a los desarrolladores +(expertos en dominio) que formarán el equipo de respuesta inicial para un +problema en particular. El equipo de respuesta inicial puede involucrar +más desarrolladores (expertos en dominio) para abordar el problema de la +mejor manera técnica. + +Todos los desarrolladores involucrados se comprometen a adherirse a las +reglas del embargo y a mantener confidencial la información recibida. La +violación de la promesa conducirá a la exclusión inmediata del problema +actual y la eliminación de todas las listas de correo relacionadas. +Además, el equipo de seguridad de hardware también excluirá al +delincuente de problemas futuros. El impacto de esta consecuencia es un +elemento de disuasión altamente efectivo en nuestra comunidad. En caso de +que ocurra una violación, el equipo de seguridad de hardware informará a +las partes involucradas inmediatamente. Si usted o alguien tiene +conocimiento de una posible violación, por favor, infórmelo inmediatamente +a los oficiales de seguridad de hardware. + +Proceso +^^^^^^^ + +Debido a la naturaleza distribuida globalmente del desarrollo del kernel +de Linux, las reuniones cara a cara hacen imposible abordar los +problemas de seguridad del hardware. Las conferencias telefónicas son +difÃciles de coordinar debido a las zonas horarias y otros factores y +solo deben usarse cuando sea absolutamente necesario. El correo +electrónico encriptado ha demostrado ser el método de comunicación más +efectivo y seguro para estos tipos de problemas. + +Inicio de la divulgación +"""""""""""""""""""""""" + +La divulgación comienza contactado al equipo de seguridad de hardware del +kernel de Linux por correo electrónico. Este contacto inicial debe +contener una descripción del problema y una lista de cualquier hardware +afectado conocido. Si su organización fabrica o distribuye el hardware +afectado, le animamos a considerar también que otro hardware podrÃa estar +afectado. + +El equipo de seguridad de hardware proporcionará una lista de correo +encriptada especÃfica para el incidente que se utilizará para la discusión +inicial con el reportero, la divulgación adicional y la coordinación. + +El equipo de seguridad de hardware proporcionará a la parte reveladora una +lista de desarrolladores (expertos de dominios) a quienes se debe informar +inicialmente sobre el problema después de confirmar con los +desarrolladores que se adherirán a este Memorando de Entendimiento y al +proceso documentado. Estos desarrolladores forman el equipo de respuesta +inicial y serán responsables de manejar el problema después del contacto +inicial. El equipo de seguridad de hardware apoyará al equipo de +respuesta, pero no necesariamente involucrandose en el proceso de desarrollo +de mitigación. + +Si bien los desarrolladores individuales pueden estar cubiertos por un +acuerdo de no divulgación a través de su empleador, no pueden firmar +acuerdos individuales de no divulgación en su papel de desarrolladores +del kernel de Linux. Sin embargo, aceptarán adherirse a este proceso +documentado y al Memorando de Entendimiento. + +La parte reveladora debe proporcionar una lista de contactos para todas +las demás entidades ya que han sido, o deberÃan ser, informadas sobre el +problema. Esto sirve para varios propósitos: + + - La lista de entidades divulgadas permite la comunicación en toda la + industria, por ejemplo, otros vendedores de OS, vendedores de HW, etc. + + - Las entidades divulgadas pueden ser contactadas para nombrar a expertos + que deben participar en el desarrollo de la mitigación. + + - Si un experto que se requiere para manejar un problema es empleado por + una entidad cotizada o un miembro de una entidad cotizada, los equipos + de respuesta pueden solicitar la divulgación de ese experto a esa + entidad. Esto asegura que el experto también forme parte del equipo de + respuesta de la entidad. + +Divulgación +""""""""""" + +La parte reveladora proporcionará información detallada al equipo de +respuesta inicial a través de la lista de correo encriptada especifica. + +Según nuestra experiencia, la documentación técnica de estos problemas +suele ser un punto de partida suficiente y es mejor hacer aclaraciones +técnicas adicionales a través del correo electrónico. + +Desarrollo de la mitigación +""""""""""""""""""""""""""" + +El equipo de respuesta inicial configura una lista de correo encriptada o +reutiliza una existente si es apropiada. + +El uso de una lista de correo está cerca del proceso normal de desarrollo +de Linux y se ha utilizado con éxito en el desarrollo de mitigación para +varios problemas de seguridad de hardware en el pasado. + +La lista de correo funciona en la misma manera que el desarrollo normal de +Linux. Los parches se publican, discuten y revisan y, si se acuerda, se +aplican a un repositorio git no público al que solo pueden acceder los +desarrolladores participantes a través de una conexión segura. El +repositorio contiene la rama principal de desarrollo en comparación con +el kernel principal y las ramas backport para versiones estables del +kernel según sea necesario. + +El equipo de respuesta inicial identificará a más expertos de la +comunidad de desarrolladores del kernel de Linux según sea necesario. La +incorporación de expertos puede ocurrir en cualquier momento del proceso +de desarrollo y debe manejarse de manera oportuna. + +Si un experto es empleado por o es miembro de una entidad en la lista de +divulgación proporcionada por la parte reveladora, entonces se solicitará +la participación de la entidad pertinente. + +Si no es asÃ, entonces se informará a la parte reveladora sobre la +participación de los expertos. Los expertos están cubiertos por el +Memorando de Entendimiento y se solicita a la parte reveladora que +reconozca la participación. En caso de que la parte reveladora tenga una +razón convincente para objetar, entonces esta objeción debe plantearse +dentro de los cinco dÃas laborables y resolverse con el equipo de +incidente inmediatamente. Si la parte reveladora no reacciona dentro de +los cinco dÃas laborables, esto se toma como un reconocimiento silencioso. + +Después del reconocimiento o la resolución de una objeción, el experto es +revelado por el equipo de incidente y se incorpora al proceso de +desarrollo. + +Lanzamiento coordinado +"""""""""""""""""""""" + +Las partes involucradas negociarán la fecha y la hora en la que termina el +embargo. En ese momento, las mitigaciones preparadas se integran en los +árboles de kernel relevantes y se publican. + +Si bien entendemos que los problemas de seguridad del hardware requieren +un tiempo de embargo coordinado, el tiempo de embargo debe limitarse al +tiempo mÃnimo que se requiere para que todas las partes involucradas +desarrollen, prueben y preparen las mitigaciones. Extender el tiempo de +embargo artificialmente para cumplir con las fechas de discusión de la +conferencia u otras razones no técnicas está creando más trabajo y carga +para los desarrolladores y los equipos de respuesta involucrados, ya que +los parches necesitan mantenerse actualizados para seguir el desarrollo en +curso del kernel upstream, lo cual podrÃa crear cambios conflictivos. + +Asignación de CVE +""""""""""""""""" + +Ni el equipo de seguridad de hardware ni el equipo de respuesta inicial +asignan CVEs, ni se requieren para el proceso de desarrollo. Si los CVEs +son proporcionados por la parte reveladora, pueden usarse con fines de +documentación. + +Embajadores del proceso +----------------------- + +Para obtener asistencia con este proceso, hemos establecido embajadores +en varias organizaciones, que pueden responder preguntas o proporcionar +orientación sobre el proceso de reporte y el manejo posterior. Los +embajadores no están involucrados en la divulgación de un problema en +particular, a menos que lo solicite un equipo de respuesta o una parte +revelada involucrada. La lista de embajadores actuales: + + ============= ======================================================== + AMD Tom Lendacky <thomas.lendacky@amd.com> + Ampere Darren Hart <darren@os.amperecomputing.com> + ARM Catalin Marinas <catalin.marinas@arm.com> + IBM Power Anton Blanchard <anton@linux.ibm.com> + IBM Z Christian Borntraeger <borntraeger@de.ibm.com> + Intel Tony Luck <tony.luck@intel.com> + Qualcomm Trilok Soni <tsoni@codeaurora.org> + Samsung Javier González <javier.gonz@samsung.com> + + Microsoft James Morris <jamorris@linux.microsoft.com> + Xen Andrew Cooper <andrew.cooper3@citrix.com> + + Canonical John Johansen <john.johansen@canonical.com> + Debian Ben Hutchings <ben@decadent.org.uk> + Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> + Red Hat Josh Poimboeuf <jpoimboe@redhat.com> + SUSE Jiri Kosina <jkosina@suse.cz> + + Google Kees Cook <keescook@chromium.org> + + LLVM Nick Desaulniers <ndesaulniers@google.com> + ============= ======================================================== + +Si quiere que su organización se añada a la lista de embajadores, por +favor póngase en contacto con el equipo de seguridad de hardware. El +embajador nominado tiene que entender y apoyar nuestro proceso +completamente y está idealmente bien conectado en la comunidad del kernel +de Linux. + +Listas de correo encriptadas +---------------------------- + +Usamos listas de correo encriptadas para la comunicación. El principio de +funcionamiento de estas listas es que el correo electrónico enviado a la +lista se encripta con la llave PGP de la lista o con el certificado S/MIME +de la lista. El software de lista de correo descifra el correo electrónico +y lo vuelve a encriptar individualmente para cada suscriptor con la llave +PGP del suscriptor o el certificado S/MIME. Los detalles sobre el software +de la lista de correo y la configuración que se usa para asegurar la +seguridad de las listas y la protección de los datos se pueden encontrar +aquÃ: https://korg.wiki.kernel.org/userdoc/remail. + +Llaves de lista +^^^^^^^^^^^^^^^ + +Para el contacto inicial, consulte :ref:`Contacto`. Para las listas de +correo especificas de incidentes, la llave y el certificado S/MIME se +envÃan a los suscriptores por correo electrónico desde la lista +especifica. + +Suscripción a listas especÃficas de incidentes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +La suscripción es manejada por los equipos de respuesta. Las partes +reveladas que quieren participar en la comunicación envÃan una lista de +suscriptores potenciales al equipo de respuesta para que el equipo de +respuesta pueda validar las solicitudes de suscripción. + +Cada suscriptor necesita enviar una solicitud de suscripción al equipo de +respuesta por correo electrónico. El correo electrónico debe estar firmado +con la llave PGP del suscriptor o el certificado S/MIME. Si se usa una +llave PGP, debe estar disponible desde un servidor de llave publica y esta +idealmente conectada a la red de confianza PGP del kernel de Linux. Véase +también: https://www.kernel.org/signature.html. + +El equipo de respuesta verifica que la solicitud del suscriptor sea válida +y añade al suscriptor a la lista. Después de la suscripción, el suscriptor +recibirá un correo electrónico de la lista que está firmado con la llave +PGP de la lista o el certificado S/MIME de la lista. El cliente de correo +electrónico del suscriptor puede extraer la llave PGP o el certificado +S/MIME de la firma, de modo que el suscriptor pueda enviar correo +electrónico encriptado a la lista. diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 09bfece0f52f..d6f3ccfb160e 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -22,3 +22,5 @@ adding-syscalls researcher-guidelines contribution-maturity-model + security-bugs + embargoed-hardware-issues diff --git a/Documentation/translations/sp_SP/process/security-bugs.rst b/Documentation/translations/sp_SP/process/security-bugs.rst new file mode 100644 index 000000000000..d07c7e579b52 --- /dev/null +++ b/Documentation/translations/sp_SP/process/security-bugs.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/security-bugs.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +Errores de seguridad +==================== + +Los desarrolladores del kernel de Linux se toman la seguridad muy en +serio. Como tal, nos gustarÃa saber cuándo se encuentra un error de +seguridad para que pueda ser corregido y divulgado lo más rápido posible. +Por favor, informe sobre los errores de seguridad al equipo de seguridad +del kernel de Linux. + +Contacto +-------- + +El equipo de seguridad del kernel de Linux puede ser contactado por correo +electrónico en <security@kernel.org>. Esta es una lista privada de +oficiales de seguridad que ayudarán a verificar el informe del error y +desarrollarán y publicarán una corrección. Si ya tiene una corrección, por +favor, inclúyala con su informe, ya que eso puede acelerar considerablemente +el proceso. Es posible que el equipo de seguridad traiga ayuda adicional +de mantenedores del área para comprender y corregir la vulnerabilidad de +seguridad. + +Como ocurre con cualquier error, cuanta más información se proporcione, +más fácil será diagnosticarlo y corregirlo. Por favor, revise el +procedimiento descrito en 'Documentation/admin-guide/reporting-issues.rst' +si no tiene claro que información es útil. Cualquier código de explotación +es muy útil y no será divulgado sin el consentimiento del "reportero" (el +que envia el error) a menos que ya se haya hecho público. + +Por favor, envÃe correos electrónicos en texto plano sin archivos +adjuntos cuando sea posible. Es mucho más difÃcil tener una discusión +citada en contexto sobre un tema complejo si todos los detalles están +ocultos en archivos adjuntos. Piense en ello como un +:doc:`envÃo de parche regular <submitting-patches>` (incluso si no tiene +un parche todavÃa) describa el problema y el impacto, enumere los pasos +de reproducción, y sÃgalo con una solución propuesta, todo en texto plano. + + +Divulgación e información embargada +----------------------------------- + +La lista de seguridad no es un canal de divulgación. Para eso, ver +Coordinación debajo. Una vez que se ha desarrollado una solución robusta, +comienza el proceso de lanzamiento. Las soluciones para errores conocidos +públicamente se lanzan inmediatamente. + +Aunque nuestra preferencia es lanzar soluciones para errores no divulgados +públicamente tan pronto como estén disponibles, esto puede postponerse a +petición del reportero o una parte afectada por hasta 7 dÃas calendario +desde el inicio del proceso de lanzamiento, con una extensión excepcional +a 14 dÃas de calendario si se acuerda que la criticalidad del error requiere +más tiempo. La única razón válida para aplazar la publicación de una +solución es para acomodar la logÃstica de QA y los despliegues a gran +escala que requieren coordinación de lanzamiento. + +Si bien la información embargada puede compartirse con personas de +confianza para desarrollar una solución, dicha información no se publicará +junto con la solución o en cualquier otro canal de divulgación sin el +permiso del reportero. Esto incluye, pero no se limita al informe original +del error y las discusiones de seguimiento (si las hay), exploits, +información sobre CVE o la identidad del reportero. + +En otras palabras, nuestro único interés es solucionar los errores. Toda +otra información presentada a la lista de seguridad y cualquier discusión +de seguimiento del informe se tratan confidencialmente incluso después de +que se haya levantado el embargo, en perpetuidad. + +Coordinación con otros grupos +----------------------------- + +El equipo de seguridad del kernel recomienda encarecidamente que los +reporteros de posibles problemas de seguridad NUNCA contacten la lista +de correo “linux-distros†hasta DESPUES de discutirlo con el equipo de +seguridad del kernel. No Cc: ambas listas a la vez. Puede ponerse en +contacto con la lista de correo linux-distros después de que se haya +acordado una solución y comprenda completamente los requisitos que al +hacerlo le impondrá a usted y la comunidad del kernel. + +Las diferentes listas tienen diferentes objetivos y las reglas de +linux-distros no contribuyen en realidad a solucionar ningún problema de +seguridad potencial. + +Asignación de CVE +----------------- + +El equipo de seguridad no asigna CVEs, ni los requerimos para informes o +correcciones, ya que esto puede complicar innecesariamente el proceso y +puede retrasar el manejo de errores. Si un reportero desea que se le +asigne un identificador CVE, debe buscar uno por sà mismo, por ejemplo, +poniéndose en contacto directamente con MITRE. Sin embargo, en ningún +caso se retrasará la inclusión de un parche para esperar a que llegue un +identificador CVE. + +Acuerdos de no divulgación +-------------------------- + +El equipo de seguridad del kernel de Linux no es un organismo formal y, +por lo tanto, no puede firmar cualquier acuerdo de no divulgación. diff --git a/Documentation/translations/zh_CN/arch/index.rst b/Documentation/translations/zh_CN/arch/index.rst index e3d273d7d599..71186d9df7c9 100644 --- a/Documentation/translations/zh_CN/arch/index.rst +++ b/Documentation/translations/zh_CN/arch/index.rst @@ -10,7 +10,7 @@ mips/index arm64/index - ../riscv/index + ../arch/riscv/index openrisc/index parisc/index loongarch/index @@ -18,7 +18,6 @@ TODOList: * arm/index -* ia64/index * m68k/index * nios2/index * powerpc/index diff --git a/Documentation/translations/zh_CN/riscv/boot-image-header.rst b/Documentation/translations/zh_CN/arch/riscv/boot-image-header.rst index 0234c28a7114..779b5172fe24 100644 --- a/Documentation/translations/zh_CN/riscv/boot-image-header.rst +++ b/Documentation/translations/zh_CN/arch/riscv/boot-image-header.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/boot-image-header.rst +:Original: Documentation/arch/riscv/boot-image-header.rst :翻译: diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/arch/riscv/index.rst index 131e405aa857..3b041c116169 100644 --- a/Documentation/translations/zh_CN/riscv/index.rst +++ b/Documentation/translations/zh_CN/arch/riscv/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/index.rst +:Original: Documentation/arch/riscv/index.rst :翻译: diff --git a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst b/Documentation/translations/zh_CN/arch/riscv/patch-acceptance.rst index d180d24717bf..c8eb230ca8ee 100644 --- a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst +++ b/Documentation/translations/zh_CN/arch/riscv/patch-acceptance.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/patch-acceptance.rst +:Original: Documentation/arch/riscv/patch-acceptance.rst :翻译: diff --git a/Documentation/translations/zh_CN/riscv/vm-layout.rst b/Documentation/translations/zh_CN/arch/riscv/vm-layout.rst index 91884e2dfff8..4b9f4dcf6c19 100644 --- a/Documentation/translations/zh_CN/riscv/vm-layout.rst +++ b/Documentation/translations/zh_CN/arch/riscv/vm-layout.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/riscv/vm-layout.rst +:Original: Documentation/arch/riscv/vm-layout.rst :翻译: diff --git a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst index 4772a900c37a..bc0d7ea6d834 100644 --- a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst +++ b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst @@ -49,12 +49,6 @@ CPUçƒæ‹”æ’支æŒçš„一个更新颖的用途是它在SMPçš„æš‚åœæ¢å¤æ”¯æŒä¸ é™åˆ¶å†…æ ¸å°†æ”¯æŒçš„CPU总é‡ã€‚如果这里æ供的数é‡ä½ŽäºŽå®žé™…å¯ç”¨çš„CPUæ•°é‡ï¼Œé‚£ä¹ˆå…¶ä»–CPU 以åŽå°±ä¸èƒ½ä¸Šçº¿äº†ã€‚ -``additional_cpus=n`` - 使用它æ¥é™åˆ¶å¯çƒæ’拔的CPU。该选项设置 - ``cpu_possible_mask = cpu_present_mask + additional_cpus`` - - 这个选项åªé™äºŽIA64架构。 - ``possible_cpus=n`` 这个选项设置 ``cpu_possible_mask`` ä¸çš„ ``possible_cpus`` ä½ã€‚ diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 299704c0818d..6ccec9657cc6 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -52,12 +52,9 @@ core-api/index driver-api/index + subsystem-apis å†…æ ¸ä¸çš„é” <locking/index> -TODOList: - -* subsystem-apis - å¼€å‘工具和æµç¨‹ -------------- diff --git a/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst b/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst index a1ee99c4786e..0f5acfb1012e 100644 --- a/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst +++ b/Documentation/translations/zh_CN/maintainer/maintainer-entry-profile.rst @@ -89,4 +89,4 @@ ../doc-guide/maintainer-profile ../../../nvdimm/maintainer-entry-profile - ../../../riscv/patch-acceptance + ../../../arch/riscv/patch-acceptance diff --git a/Documentation/translations/zh_CN/scheduler/sched-arch.rst b/Documentation/translations/zh_CN/scheduler/sched-arch.rst index ce3f39d9b3cb..b2ac3c743a3a 100644 --- a/Documentation/translations/zh_CN/scheduler/sched-arch.rst +++ b/Documentation/translations/zh_CN/scheduler/sched-arch.rst @@ -20,8 +20,7 @@ ========== 1. è¿è¡Œé˜Ÿåˆ—é” é»˜è®¤æƒ…å†µä¸‹ï¼Œswitch_to arch函数在调用时é”定了è¿è¡Œé˜Ÿåˆ—。这通常ä¸æ˜¯ä¸€ä¸ªé—®é¢˜ï¼Œé™¤éž -switch_toå¯èƒ½éœ€è¦èŽ·å–è¿è¡Œé˜Ÿåˆ—é”。这通常是由于上下文切æ¢ä¸çš„唤醒æ“ä½œé€ æˆçš„ã€‚è§ -arch/ia64/include/asm/switch_to.h的例å。 +switch_toå¯èƒ½éœ€è¦èŽ·å–è¿è¡Œé˜Ÿåˆ—é”。这通常是由于上下文切æ¢ä¸çš„唤醒æ“ä½œé€ æˆçš„。 为了è¦æ±‚调度器在è¿è¡Œé˜Ÿåˆ—解é”的情况下调用switch_toï¼Œä½ å¿…é¡»åœ¨å¤´æ–‡ä»¶ ä¸`#define __ARCH_WANT_UNLOCKED_CTXSW`(通常是定义switch_to的那个文件）。 @@ -68,7 +67,5 @@ arch/x86/kernel/process.c有轮询和ç¡çœ 空闲函数的例å。 我å‘现的å¯èƒ½çš„arch问题（并试图解决或没有解决）。: -ia64 - safe_halt的调用与ä¸æ–相比，是å¦å¾ˆè’谬？ (它ç¡çœ 了å—) (å‚考 #4a) - sparc - 在这一点上，IRQ是开ç€çš„（？），把local_irq_save改为_disable。 - 待办事项: 需è¦ç¬¬äºŒä¸ªCPUæ¥ç¦ç”¨æŠ¢å (å‚考 #1) diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst new file mode 100644 index 000000000000..47780bb0772f --- /dev/null +++ b/Documentation/translations/zh_CN/subsystem-apis.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ./disclaimer-zh_CN.rst + +:Original: Documentation/subsystem-apis.rst + +:翻译: + + å”艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============== +å†…æ ¸å系统文档 +============== + +这些书ç±ä»Žå†…æ ¸å¼€å‘者的角度，详细介ç»äº†ç‰¹å®šå†…æ ¸å系统 +的如何工作。这里的大部分信æ¯ç›´æŽ¥å–è‡ªå†…æ ¸æºä»£ç ，并 +æ ¹æ®éœ€è¦æ·»åŠ 了补充ææ–™ï¼ˆæˆ–è€…è‡³å°‘æ˜¯æˆ‘ä»¬è®¾æ³•æ·»åŠ çš„ - å¯ +能 *ä¸æ˜¯* 所有的æ料都有需è¦ï¼‰ã€‚ + +æ ¸å¿ƒå系统 +---------- + +.. toctree:: + :maxdepth: 1 + + core-api/index + driver-api/index + mm/index + power/index + scheduler/index + locking/index + +TODOList: + +* timers/index + +äººæœºæŽ¥å£ +-------- + +.. toctree:: + :maxdepth: 1 + + sound/index + +TODOList: + +* input/index +* hid/index +* gpu/index +* fb/index + +ç½‘ç»œæŽ¥å£ +-------- + +.. toctree:: + :maxdepth: 1 + + infiniband/index + +TODOList: + +* networking/index +* netlabel/index +* isdn/index +* mhi/index + +å˜å‚¨æŽ¥å£ +-------- + +.. toctree:: + :maxdepth: 1 + + filesystems/index + +TODOList: + +* block/index +* cdrom/index +* scsi/index +* target/index + +**Fixme**: 这里还需è¦æ›´å¤šçš„分类组织工作。 + +.. toctree:: + :maxdepth: 1 + + accounting/index + cpu-freq/index + iio/index + virt/index + PCI/index + peci/index + +TODOList: + +* fpga/index +* i2c/index +* leds/index +* pcmcia/index +* spi/index +* w1/index +* watchdog/index +* hwmon/index +* accel/index +* security/index +* crypto/index +* bpf/index +* usb/index +* misc-devices/index +* wmi/index diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt index a88fcbc11eca..9cc97ec75d7a 100644 --- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt +++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt @@ -768,18 +768,6 @@ const char *video_device_node_name(struct video_device *vdev); æ¤åŠŸèƒ½ï¼Œè€Œéžè®¿é—® video_device::num å’Œ video_device::minor 域。 -视频缓冲辅助函数 ---------------- - -v4l2 æ ¸å¿ƒ API æ供了一个处ç†è§†é¢‘ç¼“å†²çš„æ ‡å‡†æ–¹æ³•(称为“videobufâ€)。 -这些方法使驱动å¯ä»¥é€šè¿‡ç»Ÿä¸€çš„æ–¹å¼å®žçŽ° read()ã€mmap() å’Œ overlay()。 -ç›®å‰åœ¨è®¾å¤‡ä¸Šæ”¯æŒè§†é¢‘缓冲的方法有分散/èšé›† DMA(videobuf-dma-sg)〠-线性 DMA(videobuf-dma-contig)以åŠå¤§å¤šç”¨äºŽ USB 设备的用 vmalloc -分é…的缓冲(videobuf-vmalloc)。 - -请å‚阅 Documentation/driver-api/media/v4l2-videobuf.rst，以获得更多关于 videobuf -层的使用信æ¯ã€‚ - v4l2_fh 结构体 ------------- diff --git a/Documentation/translations/zh_TW/admin-guide/README.rst b/Documentation/translations/zh_TW/admin-guide/README.rst index 7fc56e1e3348..4cb581f5994a 100644 --- a/Documentation/translations/zh_TW/admin-guide/README.rst +++ b/Documentation/translations/zh_TW/admin-guide/README.rst @@ -9,16 +9,16 @@ å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> 胡皓文 Hu Haowen <src.res.211@gmail.com> -Linuxå…§æ ¸5.x版本 <http://kernel.org/> +Linuxå…§æ ¸6.x版本 <http://kernel.org/> ========================================= -以下是Linux版本5的發行註記。仔細閱讀它們， +以下是Linux版本6的發行註記。仔細閱讀它們， å®ƒå€‘æœƒå‘Šè¨´ä½ é€™äº›éƒ½æ˜¯ä»€éº¼ï¼Œè§£é‡‹å¦‚ä½•å®‰è£å…§æ ¸ï¼Œä»¥åŠé‡åˆ°å•é¡Œæ™‚該如何åšã€‚ 什麼是Linux？ --------------- - Linux是Unix作æ¥ç³»çµ±çš„克隆版本，由Linus Torvalds在一個鬆散的網絡黑客 + Linux是Unixæ“作系統的克隆版本，由Linus Torvalds在一個鬆散的網絡黑客 （Hacker，無貶義）團隊的幫助下從é 開始編寫。它旨在實ç¾å…¼å®¹POSIXå’Œ 單一UNIXè¦ç¯„。 @@ -28,7 +28,7 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> Linux在GNU通用公共許å¯è‰ï¼Œç‰ˆæœ¬2（GNU GPLv2）下分發，詳見隨附的COPYING文件。 -它能在什麼樣的硬體上é‹è¡Œï¼Ÿ +它能在什麼樣的硬件上é‹è¡Œï¼Ÿ ----------------------------- 雖然Linux最åˆæ˜¯çˆ²32ä½çš„x86 PC機（386或更高版本）開發的，但今天它也能é‹è¡Œåœ¨ @@ -40,16 +40,16 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> 單元（PMMU）和一個移æ¤çš„GNU Cç·¨è¯å™¨ï¼ˆgccï¼›GNU Compiler Collection，GCC的一 部分）。Linux也被移æ¤åˆ°è¨±å¤šæ²’有PMMU的體系架構ä¸ï¼Œå„˜ç®¡åŠŸèƒ½é¡¯ç„¶å—到了一定的 é™åˆ¶ã€‚ - Linux也被移æ¤åˆ°äº†å…¶è‡ªå·±ä¸Šã€‚ç¾åœ¨å¯ä»¥å°‡å…§æ ¸ä½œçˆ²ç”¨æˆ¶ç©ºé–“應用程å¼é‹è¡Œâ€”—這被 + Linux也被移æ¤åˆ°äº†å…¶è‡ªå·±ä¸Šã€‚ç¾åœ¨å¯ä»¥å°‡å…§æ ¸ä½œçˆ²ç”¨æˆ¶ç©ºé–“應用程åºé‹è¡Œâ€”—這被 稱爲用戶模å¼Linux（UML）。 文檔 ----- -網際網路上和書ç±ä¸Šéƒ½æœ‰å¤§é‡çš„é›»å文檔，既有Linux專屬文檔，也有與一般UNIXå•é¡Œç›¸é—œ +å› ç‰¹ç¶²ä¸Šå’Œæ›¸ç±ä¸Šéƒ½æœ‰å¤§é‡çš„é›»å文檔，既有Linux專屬文檔，也有與一般UNIXå•é¡Œç›¸é—œ 的文檔。我建è°åœ¨ä»»ä½•Linux FTP站點上查找LDP（Linuxæ–‡æª”é …ç›®ï¼‰æ›¸ç±çš„文檔å目錄。 本自述文件並ä¸æ˜¯é—œæ–¼ç³»çµ±çš„文檔：有更好的å¯ç”¨è³‡æºã€‚ - - 網際網路上和書ç±ä¸Šéƒ½æœ‰å¤§é‡çš„（電å）文檔，既有Linux專屬文檔，也有與普通 + - å› ç‰¹ç¶²ä¸Šå’Œæ›¸ç±ä¸Šéƒ½æœ‰å¤§é‡çš„（電å）文檔，既有Linux專屬文檔，也有與普通 UNIXå•é¡Œç›¸é—œçš„文檔。我建è°åœ¨ä»»ä½•æœ‰LDP（Linuxæ–‡æª”é …ç›®ï¼‰æ›¸ç±çš„Linux FTP 站點上查找文檔å目錄。本自述文件並ä¸æ˜¯é—œæ–¼ç³»çµ±çš„文檔：有更好的å¯ç”¨è³‡æºã€‚ @@ -58,33 +58,33 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> :ref:`Documentation/process/changes.rst <changes>` 文件，它包å«äº†å‡ç´šå…§æ ¸ å¯èƒ½æœƒå°Žè‡´çš„å•é¡Œçš„相關信æ¯ã€‚ -安è£å…§æ ¸åŽŸå§‹ç¢¼ +安è£å…§æ ¸æºä»£ç¢¼ --------------- - - 如果您è¦å®‰è£å®Œæ•´çš„åŽŸå§‹ç¢¼ï¼Œè«‹æŠŠå…§æ ¸tar檔案包放在您有權é™çš„目錄ä¸ï¼ˆä¾‹å¦‚您 + - 如果您è¦å®‰è£å®Œæ•´çš„æºä»£ç¢¼ï¼Œè«‹æŠŠå…§æ ¸tar檔案包放在您有權é™çš„目錄ä¸ï¼ˆä¾‹å¦‚您 的主目錄）並將其解包:: - xz -cd linux-5.x.tar.xz | tar xvf - + xz -cd linux-6.x.tar.xz | tar xvf - - 將「Xã€æ›¿æ›æˆæœ€æ–°å…§æ ¸çš„版本號。 + 將“Xâ€æ›¿æ›æˆæœ€æ–°å…§æ ¸çš„版本號。 - ã€ä¸è¦ã€‘使用 /usr/src/linux 目錄ï¼é€™è£¡æœ‰ä¸€çµ„庫é æ–‡ä»¶ä½¿ç”¨çš„å…§æ ¸é 文件 + ã€ä¸è¦ã€‘使用 /usr/src/linux 目錄ï¼é€™è£æœ‰ä¸€çµ„庫é æ–‡ä»¶ä½¿ç”¨çš„å…§æ ¸é 文件 （通常是ä¸å®Œæ•´çš„）。它們應該與庫匹é…，而ä¸æ˜¯è¢«å…§æ ¸çš„變化æžå¾—一團糟。 - - 您還å¯ä»¥é€šéŽæ‰“補ä¸åœ¨5.x版本之間å‡ç´šã€‚補ä¸ä»¥xzæ ¼å¼åˆ†ç™¼ã€‚è¦é€šéŽæ‰“補ä¸é€²è¡Œ - 安è£ï¼Œè«‹ç²å–所有較新的補ä¸æ–‡ä»¶ï¼Œé€²å…¥å…§æ ¸åŽŸå§‹ç¢¼ï¼ˆlinux-5.x）的目錄並 + - 您還å¯ä»¥é€šéŽæ‰“補ä¸åœ¨6.x版本之間å‡ç´šã€‚補ä¸ä»¥xzæ ¼å¼åˆ†ç™¼ã€‚è¦é€šéŽæ‰“補ä¸é€²è¡Œ + 安è£ï¼Œè«‹ç²å–所有較新的補ä¸æ–‡ä»¶ï¼Œé€²å…¥å…§æ ¸æºä»£ç¢¼ï¼ˆlinux-6.x）的目錄並 執行:: - xz -cd ../patch-5.x.xz | patch -p1 + xz -cd ../patch-6.x.xz | patch -p1 - è«‹ã€æŒ‰é †åºã€‘替æ›æ‰€æœ‰å¤§æ–¼ç•¶å‰åŽŸå§‹ç¢¼æ¨¹ç‰ˆæœ¬çš„「xã€ï¼Œé€™æ¨£å°±å¯ä»¥äº†ã€‚您å¯èƒ½æƒ³è¦ + è«‹ã€æŒ‰é †åºã€‘替æ›æ‰€æœ‰å¤§æ–¼ç•¶å‰æºä»£ç¢¼æ¨¹ç‰ˆæœ¬çš„“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è£œä¸ + 與6.xå…§æ ¸çš„è£œä¸ä¸åŒï¼Œ6.x.yå…§æ ¸ï¼ˆä¹Ÿç¨±çˆ²ç©©å®šç‰ˆå…§æ ¸ï¼‰çš„è£œä¸ä¸æ˜¯å¢žé‡çš„，而是 + 直接應用於基本的6.xå…§æ ¸ã€‚ä¾‹å¦‚ï¼Œå¦‚æžœæ‚¨çš„åŸºæœ¬å…§æ ¸æ˜¯6.0，並且希望應用6.0.3 + 補ä¸ï¼Œå‰‡ä¸æ‡‰å…ˆæ‡‰ç”¨6.0.1å’Œ6.0.2的補ä¸ã€‚類似地，如果您é‹è¡Œçš„是6.0.2å…§æ ¸ï¼Œ + 並且希望跳轉到6.0.3，那麼在應用6.0.3補ä¸ä¹‹å‰ï¼Œå¿…é ˆé¦–å…ˆæ’¤éŠ·6.0.2è£œä¸ ï¼ˆå³patch -R）。更多關於這方é¢çš„內容，請閱讀 :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 @@ -93,7 +93,7 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> linux/scripts/patch-kernel linux - 上é¢å‘½ä»¤ä¸çš„第一個åƒæ•¸æ˜¯å…§æ ¸åŽŸå§‹ç¢¼çš„ä½ç½®ã€‚補ä¸æ˜¯åœ¨ç•¶å‰ç›®éŒ„應用的，但是 + 上é¢å‘½ä»¤ä¸çš„第一個åƒæ•¸æ˜¯å…§æ ¸æºä»£ç¢¼çš„ä½ç½®ã€‚補ä¸æ˜¯åœ¨ç•¶å‰ç›®éŒ„應用的，但是 å¯ä»¥å°‡å¦ä¸€å€‹ç›®éŒ„指定爲第二個åƒæ•¸ã€‚ - 確ä¿æ²’有éŽæ™‚çš„ .o 文件和ä¾è³´é …:: @@ -101,30 +101,30 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> cd linux make mrproper - ç¾åœ¨æ‚¨æ‡‰è©²å·²ç¶“æ£ç¢ºå®‰è£äº†åŽŸå§‹ç¢¼ã€‚ + ç¾åœ¨æ‚¨æ‡‰è©²å·²ç¶“æ£ç¢ºå®‰è£äº†æºä»£ç¢¼ã€‚ -軟體è¦æ±‚ +軟件è¦æ±‚ --------- - ç·¨è¯å’Œé‹è¡Œ5.xå…§æ ¸éœ€è¦å„種軟體包的最新版本。請åƒè€ƒ + ç·¨è¯å’Œé‹è¡Œ6.xå…§æ ¸éœ€è¦å„種軟件包的最新版本。請åƒè€ƒ :ref:`Documentation/process/changes.rst <changes>` - 來了解最低版本è¦æ±‚以åŠå¦‚何å‡ç´šè»Ÿé«”包。請注æ„，使用éŽèˆŠç‰ˆæœ¬çš„這些包å¯èƒ½æœƒ + 來了解最低版本è¦æ±‚以åŠå¦‚何å‡ç´šè»Ÿä»¶åŒ…。請注æ„，使用éŽèˆŠç‰ˆæœ¬çš„這些包å¯èƒ½æœƒ å°Žè‡´å¾ˆé›£è¿½è¹¤çš„é–“æŽ¥éŒ¯èª¤ï¼Œå› æ¤ä¸è¦ä»¥çˆ²åœ¨ç”Ÿæˆæˆ–æ“作éŽç¨‹ä¸å‡ºç¾æ˜Žé¡¯å•é¡Œæ™‚å¯ä»¥ åªæ›´æ–°åŒ…。 çˆ²å…§æ ¸å»ºç«‹ç›®éŒ„ --------------- - ç·¨è¯å…§æ ¸æ™‚，默èªæƒ…æ³ä¸‹æ‰€æœ‰è¼¸å‡ºæ–‡ä»¶éƒ½å°‡èˆ‡å…§æ ¸åŽŸå§‹ç¢¼æ”¾åœ¨ä¸€èµ·ã€‚使用 + ç·¨è¯å…§æ ¸æ™‚，默èªæƒ…æ³ä¸‹æ‰€æœ‰è¼¸å‡ºæ–‡ä»¶éƒ½å°‡èˆ‡å…§æ ¸æºä»£ç¢¼æ”¾åœ¨ä¸€èµ·ã€‚使用 ``make O=output/dir`` é¸é …å¯ä»¥çˆ²è¼¸å‡ºæ–‡ä»¶ï¼ˆåŒ…括 .config）指定備用ä½ç½®ã€‚ 例如:: - kernel source code: /usr/src/linux-5.x + kernel source code: /usr/src/linux-6.x build directory: /home/name/build/kernel è¦é…ç½®å’Œæ§‹å»ºå…§æ ¸ï¼Œè«‹ä½¿ç”¨:: - cd /usr/src/linux-5.x + cd /usr/src/linux-6.x make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install @@ -136,7 +136,7 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> å³ä½¿åªå‡ç´šä¸€å€‹å°ç‰ˆæœ¬ï¼Œä¹Ÿä¸è¦è·³éŽæ¤æ¥é©Ÿã€‚æ¯å€‹ç‰ˆæœ¬ä¸éƒ½æœƒæ·»åŠ æ–°çš„é…ç½®é¸é …， 如果é…置文件沒有按é 定è¨ç½®ï¼Œå°±æœƒå‡ºç¾å¥‡æ€ªçš„å•é¡Œã€‚å¦‚æžœæ‚¨æƒ³ä»¥æœ€å°‘çš„å·¥ä½œé‡ - å°‡ç¾æœ‰é…ç½®å‡ç´šåˆ°æ–°ç‰ˆæœ¬ï¼Œè«‹ä½¿ç”¨ ``makeoldconfig`` ，它åªæœƒè©¢å•æ‚¨æ–°é…ç½® + å°‡ç¾æœ‰é…ç½®å‡ç´šåˆ°æ–°ç‰ˆæœ¬ï¼Œè«‹ä½¿ç”¨ ``make oldconfig`` ，它åªæœƒè©¢å•æ‚¨æ–°é…ç½® é¸é …çš„ç”案。 - 其他é…置命令包括:: @@ -164,17 +164,17 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> "make ${PLATFORM}_defconfig" 使用arch/$arch/configs/${PLATFORM}_defconfigä¸ çš„é»˜èªé¸é …值創建一個./.config文件。 - 用「makehelpã€ä¾†ç²å–您體系架構ä¸æ‰€æœ‰å¯ç”¨å¹³å°çš„列表。 + 用“make helpâ€ä¾†ç²å–您體系架構ä¸æ‰€æœ‰å¯ç”¨å¹³è‡ºçš„列表。 "make allyesconfig" - 通éŽå„˜å¯èƒ½å°‡é¸é …值è¨ç½®çˆ²ã€Œyã€ï¼Œå‰µå»ºä¸€å€‹ + 通éŽå„˜å¯èƒ½å°‡é¸é …值è¨ç½®çˆ²â€œyâ€ï¼Œå‰µå»ºä¸€å€‹ ./.config文件。 "make allmodconfig" - 通éŽå„˜å¯èƒ½å°‡é¸é …值è¨ç½®çˆ²ã€Œmã€ï¼Œå‰µå»ºä¸€å€‹ + 通éŽå„˜å¯èƒ½å°‡é¸é …值è¨ç½®çˆ²â€œmâ€ï¼Œå‰µå»ºä¸€å€‹ ./.config文件。 - "make allnoconfig" 通éŽå„˜å¯èƒ½å°‡é¸é …值è¨ç½®çˆ²ã€Œnã€ï¼Œå‰µå»ºä¸€å€‹ + "make allnoconfig" 通éŽå„˜å¯èƒ½å°‡é¸é …值è¨ç½®çˆ²â€œnâ€ï¼Œå‰µå»ºä¸€å€‹ ./.config文件。 "make randconfig" 通éŽéš¨æ©Ÿè¨ç½®é¸é …值來創建./.config文件。 @@ -182,7 +182,7 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> "make localmodconfig" 基於當å‰é…ç½®å’ŒåŠ è¼‰çš„æ¨¡å¡Šï¼ˆlsmod）創建é…置。ç¦ç”¨ å·²åŠ è¼‰çš„æ¨¡å¡Šä¸éœ€è¦çš„任何模塊é¸é …。 - è¦çˆ²å¦ä¸€å°è¨ˆç®—機創建localmodconfig，請將該計算機 + è¦çˆ²å¦ä¸€è‡ºè¨ˆç®—機創建localmodconfig，請將該計算機 çš„lsmodå˜å„²åˆ°ä¸€å€‹æ–‡ä»¶ä¸ï¼Œä¸¦å°‡å…¶ä½œçˆ²lsmodåƒæ•¸å‚³å…¥ã€‚ æ¤å¤–，通éŽåœ¨åƒæ•¸LMC_KEEPä¸æŒ‡å®šæ¨¡å¡Šçš„路徑，å¯ä»¥å°‡ @@ -200,9 +200,10 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> "make localyesconfig" 與localmodconfig類似，åªæ˜¯å®ƒæœƒå°‡æ‰€æœ‰æ¨¡å¡Šé¸é …è½‰æ› çˆ²å…§ç½®ï¼ˆ=yï¼‰ã€‚ä½ å¯ä»¥åŒæ™‚通éŽLMC_KEEPä¿ç•™æ¨¡å¡Šã€‚ - "make kvmconfig" 爲kvmå®¢é«”å…§æ ¸æ”¯æŒå•“用其他é¸é …。 + "make kvm_guest.config" + 爲kvmå®¢æˆ¶æ©Ÿå…§æ ¸æ”¯æŒå•“用其他é¸é …。 - "make xenconfig" 爲xen dom0å®¢é«”å…§æ ¸æ”¯æŒå•“用其他é¸é …。 + "make xen.config" 爲xen dom0å®¢æˆ¶æ©Ÿå…§æ ¸æ”¯æŒå•“用其他é¸é …。 "make tinyconfig" é…置儘å¯èƒ½å°çš„å…§æ ¸ã€‚ @@ -218,10 +219,10 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> 這種情æ³ä¸‹ï¼Œæ•¸å¸ä»¿çœŸæ°¸é ä¸æœƒè¢«ä½¿ç”¨ã€‚å…§æ ¸æœƒç¨å¾®å¤§ä¸€é»žï¼Œä½†ä¸ç®¡ 是å¦æœ‰æ•¸å¸å”處ç†å™¨ï¼Œéƒ½å¯ä»¥åœ¨ä¸åŒçš„機器上工作。 - - 「kernel hackingã€é…ç½®ç´°ç¯€é€šå¸¸æœƒå°Žè‡´æ›´å¤§æˆ–æ›´æ…¢çš„å…§æ ¸ï¼ˆæˆ–å…©è€… + - “kernel hackingâ€é…ç½®ç´°ç¯€é€šå¸¸æœƒå°Žè‡´æ›´å¤§æˆ–æ›´æ…¢çš„å…§æ ¸ï¼ˆæˆ–å…©è€… 兼而有之），甚至å¯ä»¥é€šéŽé…ç½®ä¸€äº›ä¾‹ç¨‹ä¾†ä¸»å‹•å˜—è©¦ç ´å£žå£žä»£ç¢¼ä»¥ç™¼ç¾ å…§æ ¸å•é¡Œï¼Œå¾žè€Œé™ä½Žå…§æ ¸çš„穩定性（kmalloc()ï¼‰ã€‚å› æ¤ï¼Œæ‚¨å¯èƒ½æ‡‰è©² - ç”¨æ–¼ç ”ç©¶ã€Œé–‹ç™¼ã€ã€ã€Œå¯¦é©—ã€æˆ–「調試ã€ç‰¹æ€§ç›¸é—œå•é¡Œã€‚ + ç”¨æ–¼ç ”ç©¶â€œé–‹ç™¼â€ã€â€œå¯¦é©—â€æˆ–“調試â€ç‰¹æ€§ç›¸é—œå•é¡Œã€‚ ç·¨è¯å…§æ ¸ --------- @@ -229,10 +230,8 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> - 確ä¿æ‚¨è‡³å°‘有gcc 5.1å¯ç”¨ã€‚ 有關更多信æ¯ï¼Œè«‹åƒé–± :ref:`Documentation/process/changes.rst <changes>` 。 - 請注æ„，您ä»ç„¶å¯ä»¥ä½¿ç”¨æ¤å…§æ ¸é‹è¡Œa.out用戶程åºã€‚ - - 執行 ``make`` ä¾†å‰µå»ºå£“ç¸®å…§æ ¸æ˜ åƒã€‚如果您安è£äº†lilo以é©é…å…§æ ¸makefile， - 那麼也å¯ä»¥é€²è¡Œ ``makeinstall`` ，但是您å¯èƒ½éœ€è¦å…ˆæª¢æŸ¥ç‰¹å®šçš„liloè¨ç½®ã€‚ + 那麼也å¯ä»¥é€²è¡Œ ``make install`` ，但是您å¯èƒ½éœ€è¦å…ˆæª¢æŸ¥ç‰¹å®šçš„liloè¨ç½®ã€‚ 實際安è£å¿…é ˆä»¥root身份執行，但任何æ£å¸¸æ§‹å»ºéƒ½ä¸éœ€è¦ã€‚ ç„¡é ˆå¾’ç„¶ä½¿ç”¨root身份。 @@ -242,8 +241,8 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> - è©³ç´°çš„å…§æ ¸ç·¨è¯/生æˆè¼¸å‡ºï¼š é€šå¸¸ï¼Œå…§æ ¸æ§‹å»ºç³»çµ±åœ¨ç›¸ç•¶å®‰éœçš„模å¼ä¸‹é‹è¡Œï¼ˆä½†ä¸æ˜¯å®Œå…¨å®‰éœï¼‰ã€‚但是有時您或 - å…¶ä»–å…§æ ¸é–‹ç™¼äººå“¡éœ€è¦çœ‹åˆ°ç·¨è¯ã€é€£çµæˆ–其他命令的執行éŽç¨‹ã€‚爲æ¤ï¼Œå¯ä½¿ç”¨ - 「verbose（詳細）ã€æ§‹å»ºæ¨¡å¼ã€‚ + å…¶ä»–å…§æ ¸é–‹ç™¼äººå“¡éœ€è¦çœ‹åˆ°ç·¨è¯ã€éˆæŽ¥æˆ–其他命令的執行éŽç¨‹ã€‚爲æ¤ï¼Œå¯ä½¿ç”¨ + “verbose（詳細）â€æ§‹å»ºæ¨¡å¼ã€‚ å‘ ``make`` å‘½ä»¤å‚³éž ``V=1`` 來實ç¾ï¼Œä¾‹å¦‚:: make V=1 all @@ -255,15 +254,15 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> èˆ‡å·¥ä½œå…§æ ¸ç‰ˆæœ¬è™Ÿç›¸åŒçš„æ–°å…§æ ¸ï¼Œè«‹åœ¨é€²è¡Œ ``make modules_install`` å®‰è£ ä¹‹å‰å‚™ä»½modules目錄。 - 或者，在編è¯ä¹‹å‰ï¼Œä½¿ç”¨å…§æ ¸é…ç½®é¸é …「LOCALVERSIONã€å‘常è¦å…§æ ¸ç‰ˆæœ¬é™„åŠ - 一個唯一的後綴。LOCALVERSIONå¯ä»¥åœ¨ã€ŒGeneral Setupã€èœå–®ä¸è¨ç½®ã€‚ + 或者，在編è¯ä¹‹å‰ï¼Œä½¿ç”¨å…§æ ¸é…ç½®é¸é …“LOCALVERSIONâ€å‘常è¦å…§æ ¸ç‰ˆæœ¬é™„åŠ + 一個唯一的後綴。LOCALVERSIONå¯ä»¥åœ¨â€œGeneral Setupâ€èœå–®ä¸è¨ç½®ã€‚ - çˆ²äº†å¼•å°Žæ–°å…§æ ¸ï¼Œæ‚¨éœ€è¦å°‡å…§æ ¸æ˜ åƒï¼ˆä¾‹å¦‚ç·¨è¯å¾Œçš„ .../linux/arch/x86/boot/bzImage）複製到常è¦å¯å¼•å°Žå…§æ ¸çš„ä½ç½®ã€‚ - ä¸å†æ”¯æŒåœ¨æ²’有LILOç‰å•“å‹•è£è¼‰ç¨‹åºå¹«åŠ©çš„情æ³ä¸‹ç›´æŽ¥å¾žè»Ÿç›¤å¼•å°Žå…§æ ¸ã€‚ - 如果從硬碟引導Linux，很å¯èƒ½ä½¿ç”¨LILO，它使用/etc/lilo.confæ–‡ä»¶ä¸ + 如果從硬盤引導Linux，很å¯èƒ½ä½¿ç”¨LILO，它使用/etc/lilo.confæ–‡ä»¶ä¸ æŒ‡å®šçš„å…§æ ¸æ˜ åƒæ–‡ä»¶ã€‚å…§æ ¸æ˜ åƒæ–‡ä»¶é€šå¸¸æ˜¯/vmlinuzã€/boot/vmlinuz〠/bzImage或/boot/bzImageã€‚ä½¿ç”¨æ–°å…§æ ¸å‰ï¼Œè«‹ä¿å˜èˆŠæ˜ åƒçš„副本，並複製 æ–°æ˜ åƒè¦†è“‹èˆŠæ˜ åƒã€‚然後您ã€å¿…é ˆé‡æ–°é‹è¡ŒLILOã€‘ä¾†æ›´æ–°åŠ è¼‰æ˜ å°„ï¼å¦å‰‡ï¼Œ @@ -284,68 +283,13 @@ Linuxå…§æ ¸5.x版本 <http://kernel.org/> è‹¥é‡åˆ°å•é¡Œ ----------- - - 如果您發ç¾äº†ä¸€äº›å¯èƒ½ç”±æ–¼å…§æ ¸ç¼ºé™·æ‰€å°Žè‡´çš„å•é¡Œï¼Œè«‹æª¢æŸ¥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（錯誤地）忽略了編è¯å…§æ ¸çš„起始 - å移é‡ã€‚ +如果您發ç¾äº†ä¸€äº›å¯èƒ½ç”±æ–¼å…§æ ¸ç¼ºé™·æ‰€å°Žè‡´çš„å•é¡Œï¼Œè«‹åƒé–±ï¼š +Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 。 + +想è¦ç†è§£å…§æ ¸éŒ¯èª¤å ±å‘Šï¼Œè«‹åƒé–±ï¼š +Documentation/translations/zh_CN/admin-guide/bug-hunting.rst 。 + +更多用GDBèª¿è©¦å…§æ ¸çš„ä¿¡æ¯ï¼Œè«‹åƒé–±ï¼š +Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst +å’Œ Documentation/dev-tools/kgdb.rst 。 diff --git a/Documentation/translations/zh_TW/admin-guide/bootconfig.rst b/Documentation/translations/zh_TW/admin-guide/bootconfig.rst new file mode 100644 index 000000000000..abac5aa60f67 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/bootconfig.rst @@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/bootconfig.rst + +:è¯è€…: å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +======== +引導é…ç½® +======== + +:作者: Masami Hiramatsu <mhiramat@kernel.org> + +概述 +==== + +引導é…置擴展了ç¾æœ‰çš„å…§æ ¸å‘½ä»¤è¡Œï¼Œä»¥ä¸€ç¨®æ›´æœ‰æ•ˆçŽ‡çš„æ–¹å¼åœ¨å¼•å°Žå…§æ ¸æ™‚進一æ¥æ”¯æŒ +éµå€¼æ•¸æ“šã€‚這å…許管ç†å“¡å‚³éžä¸€ä»½çµæ§‹åŒ–é—œéµå—çš„é…置文件。 + +é…置文件語法 +============ + +引導é…置文件的語法採用éžå¸¸ç°¡å–®çš„éµå€¼çµæ§‹ã€‚æ¯å€‹é—œéµå—由點連接的單詞組æˆï¼Œéµ +和值由 ``=`` 連接。值以分號（ ``;`` ）或æ›è¡Œç¬¦ï¼ˆ ``\n`` ）çµå°¾ã€‚數組值ä¸æ¯ +å€‹å…ƒç´ ç”±é€—è™Ÿï¼ˆ ``,`` ）分隔。:: + + KEY[.WORD[...]] = VALUE[, VALUE2[...]][;] + +èˆ‡å…§æ ¸å‘½ä»¤è¡Œèªžæ³•ä¸åŒï¼Œé€—號和 ``=`` 周åœå…è¨±æœ‰ç©ºæ ¼ã€‚ + +é—œéµå—åªå…許包å«å—æ¯ã€æ•¸å—ã€é€£å—符（ ``-`` ）和下劃線（ ``_`` ）。值å¯åŒ…å« +å¯æ‰“å°å—ç¬¦å’Œç©ºæ ¼ï¼Œä½†åˆ†è™Ÿï¼ˆ ``;`` ）ã€æ›è¡Œç¬¦ï¼ˆ ``\n`` ）ã€é€—號（ ``,`` ）〠+井號（ ``#`` ）和å³å¤§æ‹¬è™Ÿï¼ˆ ``}`` ）ç‰åˆ†éš”符除外。 + +å¦‚æžœä½ éœ€è¦åœ¨å€¼ä¸ä½¿ç”¨é€™äº›åˆ†éš”符，å¯ä»¥ç”¨é›™å¼•è™Ÿï¼ˆ ``"VALUE"`` ）或單引號 +（ ``'VALUE'`` ）括起來。注æ„，引號無法轉義。 + +éµçš„值å¯ä»¥çˆ²ç©ºæˆ–ä¸å˜åœ¨ã€‚這些éµç”¨æ–¼æª¢æŸ¥è©²éµæ˜¯å¦å˜åœ¨ï¼ˆé¡žä¼¼å¸ƒçˆ¾å€¼ï¼‰ã€‚ + +éµå€¼èªžæ³• +-------- + +引導é…置文件語法å…許用戶通éŽå¤§æ‹¬è™Ÿåˆä½µéµå部分相åŒçš„é—œéµå—。例如:: + + foo.bar.baz = value1 + foo.bar.qux.quux = value2 + +也å¯ä»¥å¯«æˆ:: + + foo.bar { + baz = value1 + qux.quux = value2 + } + +或者更緊湊一些，寫æˆ:: + + foo.bar { baz = value1; qux.quux = value2 } + +在這兩種樣å¼ä¸ï¼Œå¼•å°Žè§£æžæ™‚相åŒçš„é—œéµå—都會自動åˆä½µã€‚å› æ¤å¯ä»¥è¿½åŠ 類似的樹或 +éµå€¼ã€‚ + +相åŒé—œéµå—的值 +-------------- + +ç¦æ¢å…©å€‹æˆ–多個值或數組共享åŒä¸€å€‹é—œéµå—。例如:: + + foo = bar, baz + foo = qux # !錯誤! 我們ä¸å¯ä»¥é‡å®šç¾©ç›¸åŒçš„é—œéµå— + +å¦‚æžœä½ æƒ³è¦æ›´æ–°å€¼ï¼Œå¿…é ˆé¡¯å¼ä½¿ç”¨è¦†è“‹æ“作符 ``:=`` 。例如:: + + foo = bar, baz + foo := qux + +這樣 ``foo`` é—œéµå—的值就變æˆäº† ``qux`` 。這å°æ–¼é€šéŽæ·»åŠ （部分）自定義引導 +é…置來覆蓋默èªå€¼éžå¸¸æœ‰ç”¨ï¼Œå…於解æžé»˜èªå¼•å°Žé…置。 + +å¦‚æžœä½ æƒ³å°ç¾æœ‰é—œéµå—è¿½åŠ å€¼ä½œçˆ²æ•¸çµ„æˆå“¡ï¼Œå¯ä»¥ä½¿ç”¨ ``+=`` æ“作符。例如:: + + foo = bar, baz + foo += qux + +這樣， ``foo`` é—œéµå—å°±åŒæ™‚æ“有了 ``bar`` ， ``baz`` å’Œ ``qux`` 。 + +æ¤å¤–，父關éµå—下å¯åŒæ™‚å˜åœ¨å€¼å’Œåé—œéµå—。 +例如，下列é…置是å¯è¡Œçš„。:: + + foo = value1 + foo.bar = value2 + foo := value3 # 這會更新foo的值。 + +注æ„，裸值ä¸èƒ½ç›´æŽ¥æ”¾é€²çµæ§‹åŒ–é—œéµå—ä¸ï¼Œå¿…é ˆåœ¨å¤§æ‹¬è™Ÿå¤–å®šç¾©å®ƒã€‚ä¾‹å¦‚:: + + foo { + bar = value1 + bar { + baz = value2 + qux = value3 + } + } + +åŒæ™‚，關éµå—ä¸‹å€¼ç¯€é»žçš„é †åºæ˜¯å›ºå®šçš„。如果值和åé—œéµå—åŒæ™‚å˜åœ¨ï¼Œå€¼æ°¸é 是該關 +éµå—的第一個åç¯€é»žã€‚å› æ¤å¦‚果用戶先指定åé—œéµå—，如:: + + foo.bar = value1 + foo = value2 + +則在程åºï¼ˆå’Œ/proc/bootconfig）ä¸ï¼Œå®ƒæœƒæŒ‰å¦‚下顯示:: + + foo = value2 + foo.bar = value1 + +註釋 +---- + +é…置語法接å—shellè…³æœ¬é¢¨æ ¼çš„è¨»é‡‹ã€‚è¨»é‡‹ä»¥äº•è™Ÿï¼ˆ ``#`` ）開始，到æ›è¡Œç¬¦ +（ ``\n`` ）çµæŸã€‚ + +:: + + # comment line + foo = value # value is set to foo. + bar = 1, # 1st element + 2, # 2nd element + 3 # 3rd element + +會被解æžçˆ²:: + + foo = value + bar = 1, 2, 3 + +注æ„ä½ ä¸èƒ½æŠŠè¨»é‡‹æ”¾åœ¨å€¼å’Œåˆ†éš”符（ ``,`` 或 ``;`` ）之間。如下é…置語法是錯誤的:: + + key = 1 # comment + ,2 + + +/proc/bootconfig +================ + +/proc/bootconfig是引導é…置的用戶空間接å£ã€‚與/proc/cmdlineä¸åŒï¼Œæ¤æ–‡ä»¶å…§å®¹ä»¥ +éµå€¼åˆ—表樣å¼é¡¯ç¤ºã€‚ +æ¯å€‹éµå€¼å°ä¸€è¡Œï¼Œæ¨£å¼å¦‚下:: + + KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...] + + +用引導é…ç½®å¼•å°Žå…§æ ¸ +================== + +用引導é…ç½®å¼•å°Žå…§æ ¸æœ‰å…©ç¨®æ–¹æ³•ï¼šå°‡å¼•å°Žé…ç½®é™„åŠ åˆ°initrdé¡åƒæˆ–ç›´æŽ¥åµŒå…¥å…§æ ¸ä¸ã€‚ + +*initrd: initial RAM disk，åˆå§‹å…§å˜ç£ç›¤* + +將引導é…ç½®é™„åŠ åˆ°initrd +---------------------- + +由於默èªæƒ…æ³ä¸‹å¼•å°Žé…置文件是用initrdåŠ è¼‰çš„ï¼Œå› æ¤å®ƒå°‡è¢«æ·»åŠ 到initrd（initramfs） +é¡åƒæ–‡ä»¶çš„末尾，其ä¸åŒ…å«å¡«å……ã€å¤§å°ã€æ ¡é©—值和12å—節幻數，如下所示:: + + [initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n] + +大å°å’Œæ ¡é©—值爲å°ç«¯åºå˜æ”¾çš„32ä½ç„¡ç¬¦è™Ÿå€¼ã€‚ + +當引導é…ç½®è¢«åŠ åˆ°initrdé¡åƒæ™‚，整個文件大å°æœƒå°é½Šåˆ°4å—節。空å—符（ ``\0`` ） +會填補å°é½Šç©ºéš™ã€‚å› æ¤ ``size`` 就是引導é…置文件的長度+å¡«å……çš„å—節。 + +Linuxå…§æ ¸åœ¨å…§å˜ä¸è§£ç¢¼initrdé¡åƒçš„最後部分以ç²å–引導é…置數據。由於這種“æ¹è² å¼â€ +的方法，åªè¦å¼•å°ŽåŠ 載器傳éžäº†æ£ç¢ºçš„initrd文件大å°ï¼Œå°±ç„¡éœ€æ›´æ”¹æˆ–æ›´æ–°å¼•å°ŽåŠ è¼‰å™¨ +å’Œå…§æ ¸é¡åƒæœ¬èº«ã€‚å¦‚æžœå¼•å°ŽåŠ è¼‰å™¨æ„外傳éžäº†æ›´é•·çš„大å°ï¼Œå…§æ ¸å°‡ç„¡æ³•æ‰¾åˆ°å¼•å°Žé…置數 +據。 + +Linuxå…§æ ¸åœ¨tools/bootconfig下æ供了 ``bootconfig`` 命令來完æˆæ¤æ“作，管ç†å“¡ +å¯ä»¥ç”¨å®ƒå¾žinitrdé¡åƒä¸åˆªé™¤æˆ–è¿½åŠ é…ç½®æ–‡ä»¶ã€‚ä½ å¯ä»¥ç”¨ä»¥ä¸‹å‘½ä»¤ä¾†æ§‹å»ºå®ƒ:: + + # make -C tools/bootconfig + +è¦å‘initrdé¡åƒæ·»åŠ ä½ çš„å¼•å°Žé…置文件，請按如下命令æ“作（舊數據會自動移除）:: + + # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z + +è¦å¾žé¡åƒä¸ç§»é™¤é…置，å¯ä»¥ä½¿ç”¨-dé¸é …:: + + # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z + +ç„¶å¾Œåœ¨å…§æ ¸å‘½ä»¤è¡Œä¸Šæ·»åŠ ``bootconfig`` å‘Šè¨´å…§æ ¸åŽ»initrdæ–‡ä»¶æœ«å°¾å°‹æ‰¾å…§æ ¸é…置。 + +將引導é…ç½®åµŒå…¥å…§æ ¸ +------------------ + +å¦‚æžœä½ ä¸èƒ½ä½¿ç”¨initrd，也å¯ä»¥é€šéŽKconfigé¸é …將引導é…ç½®æ–‡ä»¶åµŒå…¥å…§æ ¸ä¸ã€‚在æ¤æƒ… +æ³ä¸‹ï¼Œä½ 需è¦ç”¨ä»¥ä¸‹é¸é …é‡æ–°ç·¨è¯å…§æ ¸:: + + CONFIG_BOOT_CONFIG_EMBED=y + CONFIG_BOOT_CONFIG_EMBED_FILE="/引導é…ç½®/文件/çš„/路徑" + +``CONFIG_BOOT_CONFIG_EMBED_FILE`` 需è¦å¾žæºç¢¼æ¨¹æˆ–å°è±¡æ¨¹é–‹å§‹çš„引導é…置文件的 +絕å°/相å°è·¯å¾‘ã€‚å…§æ ¸æœƒå°‡å…¶åµŒå…¥ä½œçˆ²é»˜èªå¼•å°Žé…置。 + +與將引導é…ç½®é™„åŠ åˆ°initrdä¸€æ¨£ï¼Œä½ ä¹Ÿéœ€è¦åœ¨å…§æ ¸å‘½ä»¤è¡Œä¸Šæ·»åŠ ``bootconfig`` 告訴 +å…§æ ¸åŽ»å•“ç”¨å…§åµŒçš„å¼•å°Žé…置。 + +注æ„，å³ä½¿ä½ 已經è¨ç½®äº†æ¤é¸é …，ä»å¯ç”¨é™„åŠ åˆ°initrd的其他引導é…置覆蓋內嵌的引導 +é…置。 + +通éŽå¼•å°Žé…置傳éžå…§æ ¸åƒæ•¸ +======================== + +é™¤äº†å…§æ ¸å‘½ä»¤è¡Œï¼Œå¼•å°Žé…置也å¯ä»¥ç”¨æ–¼å‚³éžå…§æ ¸åƒæ•¸ã€‚所有 ``kernel`` é—œéµå—ä¸‹çš„éµ +值å°éƒ½å°‡ç›´æŽ¥å‚³éžçµ¦å…§æ ¸å‘½ä»¤è¡Œã€‚æ¤å¤–， ``init`` 下的éµå€¼å°å°‡é€šéŽå‘½ä»¤è¡Œå‚³éžçµ¦ +init進程。åƒæ•¸æŒ‰ä»¥ä¸‹é †åºèˆ‡ç”¨æˆ¶çµ¦å®šçš„å…§æ ¸å‘½ä»¤è¡Œå—ç¬¦ä¸²ç›¸é€£ï¼Œå› æ¤å‘½ä»¤è¡Œåƒæ•¸å¯ä»¥ +覆蓋引導é…ç½®åƒæ•¸ï¼ˆé€™å–決於å系統如何處ç†åƒæ•¸ï¼Œä½†é€šå¸¸å‰é¢çš„åƒæ•¸å°‡è¢«å¾Œé¢çš„åƒæ•¸ +覆蓋）:: + + [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params] + +如果引導é…置文件給出的kernel/initåƒæ•¸æ˜¯:: + + kernel { + root = 01234567-89ab-cdef-0123-456789abcd + } + init { + splash + } + +é€™å°‡è¢«è¤‡åˆ¶åˆ°å…§æ ¸å‘½ä»¤è¡Œå—符串ä¸ï¼Œå¦‚下所示:: + + root="01234567-89ab-cdef-0123-456789abcd" -- splash + +如果用戶給出的其他命令行是:: + + ro bootconfig -- quiet + +å‰‡æœ€å¾Œçš„å…§æ ¸å‘½ä»¤è¡Œå¦‚ä¸‹:: + + root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet + + +é…置文件的é™åˆ¶ +============== + +當å‰æœ€å¤§çš„é…置大å°æ˜¯32KB，關éµå—總數（ä¸æ˜¯éµå€¼æ¢ç›®ï¼‰å¿…é ˆå°‘æ–¼1024個節點。 +注æ„：這ä¸æ˜¯æ¢ç›®æ•¸è€Œæ˜¯ç¯€é»žæ•¸ï¼Œæ¢ç›®å¿…é ˆæ¶ˆè€—è¶…éŽ2個節點（一個關éµå—和一個值）。 +所以從ç†è«–上講最多512個éµå€¼å°ã€‚如果關éµå—å¹³å‡åŒ…å«3個單詞，則å¯æœ‰256個éµå€¼å°ã€‚ +在大多數情æ³ä¸‹ï¼Œé…ç½®é …çš„æ•¸é‡å°‡å°‘æ–¼100個æ¢ç›®ï¼Œå°æ–¼8KBï¼Œå› æ¤é€™æ‡‰è©²è¶³å¤ 了。如果 +節點數超éŽ1024，解æžå™¨å°‡è¿”回錯誤，å³ä½¿æ–‡ä»¶å¤§å°å°æ–¼32KB。（請注æ„，æ¤æœ€å¤§å°ºå¯¸ +ä¸åŒ…括填充的空å—符。） +ç„¡è«–å¦‚ä½•ï¼Œå› çˆ² ``bootconfig`` å‘½ä»¤åœ¨é™„åŠ å•“å‹•é…置到initrdæ˜ åƒæ™‚會驗è‰å®ƒï¼Œç”¨æˆ¶ +å¯ä»¥åœ¨å¼•å°Žä¹‹å‰æ³¨æ„到它。 + + +引導é…ç½®API +=========== + +用戶å¯ä»¥æŸ¥è©¢æˆ–éæ·éµå€¼å°ï¼Œä¹Ÿå¯ä»¥æŸ¥æ‰¾ï¼ˆå‰ç¶´ï¼‰æ ¹é—œéµå—節點，並在查找該節點下的 +éµå€¼ã€‚ + +如果您有一個關éµå—å—符串，則å¯ä»¥ç›´æŽ¥ä½¿ç”¨ xbc_find_value() 查詢該éµçš„值。如果 +ä½ æƒ³çŸ¥é“引導é…ç½®è£æœ‰å“ªäº›é—œéµå—，å¯ä»¥ä½¿ç”¨ xbc_for_each_key_value() è¿ä»£éµå€¼å°ã€‚ +請注æ„，您需è¦ä½¿ç”¨ xbc_array_for_each_value() 訪å•æ•¸çµ„的值，例如:: + + vnode = NULL; + xbc_find_value("key.word", &vnode); + if (vnode && xbc_node_is_array(vnode)) + xbc_array_for_each_value(vnode, value) { + printk("%s ", value); + } + +如果您想查找具有å‰ç¶´å—符串的éµï¼Œå¯ä»¥ä½¿ç”¨ xbc_find_node() 通éŽå‰ç¶´å—符串查找 +節點，然後用 xbc_node_for_each_key_value() è¿ä»£å‰ç¶´ç¯€é»žä¸‹çš„éµã€‚ + +但最典型的用法是ç²å–å‰ç¶´ä¸‹çš„命å值或å‰ç¶´ä¸‹çš„命å數組，例如:: + + root = xbc_find_node("key.prefix"); + value = xbc_node_find_value(root, "option", &vnode); + ... + xbc_node_for_each_array_value(root, "array-option", value, anode) { + ... + } + +這將訪å•å€¼â€œkey.prefix.optionâ€çš„值和“key.prefix.array-optionâ€çš„數組。 + +鎖是ä¸éœ€è¦çš„ï¼Œå› çˆ²åœ¨åˆå§‹åŒ–之後é…ç½®åªè®€ã€‚如果需è¦ä¿®æ”¹ï¼Œå¿…é ˆè¤‡è£½æ‰€æœ‰æ•¸æ“šå’Œé—œéµå—。 + + +函數與çµæ§‹é«” +============ + +相關定義的kernel-docåƒè¦‹ï¼š + + - include/linux/bootconfig.h + - lib/bootconfig.c + diff --git a/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst index b448dbf5ac87..3f10a9f8f223 100644 --- a/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst +++ b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst @@ -17,14 +17,14 @@ 引言 ===== -始終嘗試由來自kernel.orgçš„åŽŸå§‹ç¢¼æ§‹å»ºçš„æœ€æ–°å…§æ ¸ã€‚å¦‚æžœæ‚¨æ²’æœ‰ä¿¡å¿ƒé€™æ¨£åšï¼Œè«‹å°‡ +始終嘗試由來自kernel.orgçš„æºä»£ç¢¼æ§‹å»ºçš„æœ€æ–°å…§æ ¸ã€‚å¦‚æžœæ‚¨æ²’æœ‰ä¿¡å¿ƒé€™æ¨£åšï¼Œè«‹å°‡ éŒ¯èª¤å ±å‘Šçµ¦æ‚¨çš„ç™¼è¡Œç‰ˆä¾›æ‡‰å•†ï¼Œè€Œä¸æ˜¯å…§æ ¸é–‹ç™¼äººå“¡ã€‚ 找到缺陷（bug）並ä¸ç¸½æ˜¯é‚£éº¼å®¹æ˜“，ä¸éŽä»ç„¶å¾—åŽ»æ‰¾ã€‚å¦‚æžœä½ æ‰¾ä¸åˆ°å®ƒï¼Œä¸è¦æ”¾æ£„。 -儘å¯èƒ½å¤šçš„å‘相關ç¶è·äººå“¡å ±å‘Šæ‚¨ç™¼ç¾çš„ä¿¡æ¯ã€‚è«‹åƒé–±MAINTAINERS文件以了解您所 +儘å¯èƒ½å¤šçš„å‘相關ç¶è·äººå“¡å ±å‘Šæ‚¨ç™¼ç¾çš„ä¿¡æ¯ã€‚è«‹åƒé–±MAINTAINERS文件以çžè§£æ‚¨æ‰€ 關注的å系統的ç¶è·äººå“¡ã€‚ -在æäº¤éŒ¯èª¤å ±å‘Šä¹‹å‰ï¼Œè«‹é–±è®€ã€ŒDocumentation/admin-guide/reporting-issues.rstã€ã€‚ +在æäº¤éŒ¯èª¤å ±å‘Šä¹‹å‰ï¼Œè«‹é–±è®€â€œDocumentation/admin-guide/reporting-issues.rstâ€ã€‚ è¨å‚™æœªå‡ºç¾ï¼ˆDevices not appearing） ==================================== @@ -38,7 +38,7 @@ æ“作æ¥é©Ÿï¼š -- 從gitåŽŸå§‹ç¢¼æ§‹å»ºå…§æ ¸ +- 從gitæºä»£ç¢¼æ§‹å»ºå…§æ ¸ - 以æ¤é–‹å§‹äºŒåˆ† [#f1]_:: $ git bisect start @@ -76,7 +76,7 @@ 如需進一æ¥åƒè€ƒï¼Œè«‹é–±è®€ï¼š - ``git-bisect`` 的手冊é -- `Fighting regressions with git bisect（用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>`_ diff --git a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst index 9a3de3bff5e7..631fd2650929 100644 --- a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst +++ b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst @@ -48,8 +48,8 @@ [<c1549f43>] ? sysenter_past_esp+0x40/0x6a ---[ end trace 6ebc60ef3981792f ]--- -é€™æ¨£çš„å †æ£§è·Ÿè¹¤æä¾›äº†è¶³å¤ çš„ä¿¡æ¯ä¾†è˜åˆ¥å…§æ ¸åŽŸå§‹ç¢¼ä¸ç™¼ç”ŸéŒ¯èª¤çš„é‚£ä¸€è¡Œã€‚æ ¹æ“šå•é¡Œçš„ -åš´é‡æ€§ï¼Œå®ƒé‚„å¯èƒ½åŒ…å« **「Oopsã€** 一詞，比如:: +é€™æ¨£çš„å †æ£§è·Ÿè¹¤æä¾›äº†è¶³å¤ çš„ä¿¡æ¯ä¾†è˜åˆ¥å…§æ ¸æºä»£ç¢¼ä¸ç™¼ç”ŸéŒ¯èª¤çš„é‚£ä¸€è¡Œã€‚æ ¹æ“šå•é¡Œçš„ +åš´é‡æ€§ï¼Œå®ƒé‚„å¯èƒ½åŒ…å« **“Oopsâ€** 一詞，比如:: BUG: unable to handle kernel NULL pointer dereference at (null) IP: [<c06969d4>] iret_exc+0x7d0/0xa59 @@ -58,17 +58,17 @@ ... 儘管有 **Oops** æˆ–å…¶ä»–é¡žåž‹çš„å †æ£§è·Ÿè¹¤ï¼Œä½†é€šå¸¸éœ€è¦æ‰¾åˆ°å‡ºå•é¡Œçš„行來è˜åˆ¥å’Œè™•ç†ç¼º -é™·ã€‚åœ¨æœ¬ç« ä¸ï¼Œæˆ‘們將åƒè€ƒã€ŒOopsã€ä¾†äº†è§£éœ€è¦åˆ†æžçš„å„ç¨®å †æ£§è·Ÿè¹¤ã€‚ +é™·ã€‚åœ¨æœ¬ç« ä¸ï¼Œæˆ‘們將åƒè€ƒâ€œOopsâ€ä¾†äº†è§£éœ€è¦åˆ†æžçš„å„ç¨®å †æ£§è·Ÿè¹¤ã€‚ å¦‚æžœå…§æ ¸æ˜¯ç”¨ ``CONFIG_DEBUG_INFO`` ç·¨è¯çš„，那麼å¯ä»¥ä½¿ç”¨æ–‡ä»¶ï¼š `scripts/decode_stacktrace.sh` 。 -連çµçš„模塊 +éˆæŽ¥çš„模塊 ----------- -å—到汙染或æ£åœ¨åŠ 載/å¸è¼‰çš„模塊用「（…）ã€æ¨™è¨˜ï¼Œæ±™æŸ“標誌在 -`Documentation/admin-guide/tainted-kernels.rst` 文件ä¸é€²è¡Œäº†æ述，「æ£åœ¨è¢«åŠ -載ã€ç”¨ã€Œ+ã€æ¨™è¨»ï¼Œã€Œæ£åœ¨è¢«å¸è¼‰ã€ç”¨ã€Œ-ã€æ¨™è¨»ã€‚ +å—到污染或æ£åœ¨åŠ 載/å¸è¼‰çš„模塊用“（…）â€æ¨™è¨˜ï¼Œæ±¡æŸ“標誌在 +`Documentation/admin-guide/tainted-kernels.rst` 文件ä¸é€²è¡Œäº†æ述，“æ£åœ¨è¢«åŠ +載â€ç”¨â€œ+â€æ¨™è¨»ï¼Œâ€œæ£åœ¨è¢«å¸è¼‰â€ç”¨â€œ-â€æ¨™è¨»ã€‚ Oops消æ¯åœ¨å“ªï¼Ÿ @@ -81,19 +81,19 @@ syslog文件，通常是 ``/var/log/messages`` （å–決於 ``/etc/syslog.conf`` 有時 ``klogd`` 會掛掉，這種情æ³ä¸‹æ‚¨å¯ä»¥é‹è¡Œ ``dmesg > file`` å¾žå…§æ ¸ç·©è¡å€ 讀å–數據並ä¿å˜å®ƒã€‚或者您å¯ä»¥ ``cat /proc/kmsg > file`` ï¼Œä½†æ˜¯æ‚¨å¿…é ˆé©æ™‚ -ä¸æ–·ä»¥åœæ¢å‚³è¼¸ï¼Œå› 爲 ``kmsg`` 是一個「永無æ¢å¢ƒçš„文件ã€ã€‚ +ä¸æ–·ä»¥åœæ¢å‚³è¼¸ï¼Œå› 爲 ``kmsg`` 是一個“永無æ¢å¢ƒçš„文件â€ã€‚ -如果機器嚴é‡å´©æ½°ï¼Œç„¡æ³•è¼¸å…¥å‘½ä»¤æˆ–ç£ç¢Ÿä¸å¯ç”¨ï¼Œé‚£é‚„有三個é¸é …： +如果機器嚴é‡å´©æ½°ï¼Œç„¡æ³•è¼¸å…¥å‘½ä»¤æˆ–ç£ç›¤ä¸å¯ç”¨ï¼Œé‚£é‚„有三個é¸é …： (1) 手動複製å±å¹•ä¸Šçš„文本，並在機器é‡æ–°å•“動後輸入。很難å—，但這是çªç„¶å´©æ½°ä¸‹ - 唯一的é¸æ“‡ã€‚æˆ–è€…ä½ å¯ä»¥ç”¨æ•¸ä½ç›¸æ©Ÿæ‹ä¸‹å±å¹•â€”—雖然ä¸é‚£éº¼å¥½ï¼Œä½†ç¸½æ¯”什麼都沒 - 有好。如果消æ¯æ»¾å‹•è¶…出控制å°é ‚部，使用更高解æžåº¦ï¼ˆä¾‹å¦‚ ``vga=791`` ） - 引導啓動將å…許您閱讀更多文本。（è¦å‘Šï¼šé€™éœ€è¦ ``vesafb`` ï¼Œå› æ¤å°ã€Œæ—©æœŸã€ + 唯一的é¸æ“‡ã€‚æˆ–è€…ä½ å¯ä»¥ç”¨æ•¸ç¢¼ç›¸æ©Ÿæ‹ä¸‹å±å¹•â€”—雖然ä¸é‚£éº¼å¥½ï¼Œä½†ç¸½æ¯”什麼都沒 + 有好。如果消æ¯æ»¾å‹•è¶…å‡ºæŽ§åˆ¶æª¯é ‚éƒ¨ï¼Œä½¿ç”¨æ›´é«˜åˆ†è¾¨çŽ‡ï¼ˆä¾‹å¦‚ ``vga=791`` ） + 引導啓動將å…許您閱讀更多文本。（è¦å‘Šï¼šé€™éœ€è¦ ``vesafb`` ï¼Œå› æ¤å°â€œæ—©æœŸâ€ çš„Oppses沒有幫助） (2) 從串å£çµ‚端啓動（åƒè¦‹ :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` ）， - 在å¦ä¸€å°æ©Ÿå™¨ä¸Šé‹è¡Œæ•¸æ“šæ©Ÿç„¶å¾Œç”¨ä½ å–œæ¡çš„通信程åºæ•ç²è¼¸å‡ºã€‚ + 在å¦ä¸€è‡ºæ©Ÿå™¨ä¸Šé‹è¡Œèª¿åˆ¶è§£èª¿å™¨ç„¶å¾Œç”¨ä½ å–œæ¡çš„通信程åºæ•ç²è¼¸å‡ºã€‚ Minicomé‹è¡Œè‰¯å¥½ã€‚ (3) 使用Kdump（åƒé–± Documentation/admin-guide/kdump/kdump.rst ），使用 @@ -103,7 +103,7 @@ syslog文件，通常是 ``/var/log/messages`` （å–決於 ``/etc/syslog.conf`` 找到缺陷ä½ç½® ------------- -å¦‚æžœä½ èƒ½æŒ‡å‡ºç¼ºé™·åœ¨å…§æ ¸åŽŸå§‹ç¢¼ä¸çš„ä½ç½®ï¼Œå‰‡å ±å‘Šç¼ºé™·çš„效果會éžå¸¸å¥½ã€‚這有兩種方法。 +å¦‚æžœä½ èƒ½æŒ‡å‡ºç¼ºé™·åœ¨å…§æ ¸æºä»£ç¢¼ä¸çš„ä½ç½®ï¼Œå‰‡å ±å‘Šç¼ºé™·çš„效果會éžå¸¸å¥½ã€‚這有兩種方法。 通常來說使用 ``gdb`` 會比較容易，ä¸éŽå…§æ ¸éœ€è¦ç”¨èª¿è©¦ä¿¡æ¯ä¾†é ç·¨è¯ã€‚ gdb @@ -187,7 +187,7 @@ GNU 調試器（GNU debugger， ``gdb`` ）是從 ``vmlinux`` 文件ä¸æ‰¾å‡ºOOP objdump ^^^^^^^^ -è¦èª¿è©¦å…§æ ¸ï¼Œè«‹ä½¿ç”¨objdump並從崩潰輸出ä¸æŸ¥æ‰¾åå…進ä½å移，以找到有效的代碼/匯 +è¦èª¿è©¦å…§æ ¸ï¼Œè«‹ä½¿ç”¨objdump並從崩潰輸出ä¸æŸ¥æ‰¾åå…進制å移，以找到有效的代碼/匯 編行。如果沒有調試符號，您將看到所示例程的彙編程åºä»£ç¢¼ï¼Œä½†æ˜¯å¦‚æžœå…§æ ¸æœ‰èª¿è©¦ 符號，C代碼也將å¯è¦‹ï¼ˆèª¿è©¦ç¬¦è™Ÿå¯ä»¥åœ¨å…§æ ¸é…ç½®èœå–®çš„hackingé …ä¸å•“用）。例如:: @@ -197,7 +197,7 @@ objdump 您需è¦è™•æ–¼å…§æ ¸æ¨¹çš„é ‚å±¤ä»¥ä¾¿æ¤ç²å¾—您的C文件。 -如果您無法訪å•åŽŸå§‹ç¢¼ï¼Œä»ç„¶å¯ä»¥ä½¿ç”¨ä»¥ä¸‹æ–¹æ³•èª¿è©¦ä¸€äº›å´©æ½°è½‰å„²ï¼ˆå¦‚Dave Millerçš„ +如果您無法訪å•æºä»£ç¢¼ï¼Œä»ç„¶å¯ä»¥ä½¿ç”¨ä»¥ä¸‹æ–¹æ³•èª¿è©¦ä¸€äº›å´©æ½°è½‰å„²ï¼ˆå¦‚Dave Millerçš„ 示例崩潰轉儲輸出所示）:: EIP is at +0x14/0x4c0 @@ -234,9 +234,9 @@ objdump å ±å‘Šç¼ºé™· --------- -ä¸€æ—¦ä½ é€šéŽå®šä½ç¼ºé™·æ‰¾åˆ°äº†å…¶ç™¼ç”Ÿçš„åœ°æ–¹ï¼Œä½ å¯ä»¥å˜—試自己修復它或者å‘ä¸Šæ¸¸å ±å‘Šå®ƒã€‚ +ä¸€æ—¦ä½ é€šéŽå®šä½ç¼ºé™·æ‰¾åˆ°äº†å…¶ç™¼ç”Ÿçš„åœ°æ–¹ï¼Œä½ å¯ä»¥å˜—試自己修復它或者å‘上éŠå ±å‘Šå®ƒã€‚ -爲了å‘ä¸Šæ¸¸å ±å‘Šï¼Œæ‚¨æ‡‰è©²æ‰¾å‡ºç”¨æ–¼é–‹ç™¼å—影響代碼的郵件列表。這å¯ä»¥ä½¿ç”¨ ``get_maintainer.pl`` 。 +爲了å‘上éŠå ±å‘Šï¼Œæ‚¨æ‡‰è©²æ‰¾å‡ºç”¨æ–¼é–‹ç™¼å—影響代碼的郵件列表。這å¯ä»¥ä½¿ç”¨ ``get_maintainer.pl`` 。 例如，您在gspcaçš„sonixj.c文件ä¸ç™¼ç¾ä¸€å€‹ç¼ºé™·ï¼Œå‰‡å¯ä»¥é€šéŽä»¥ä¸‹æ–¹æ³•æ‰¾åˆ°å®ƒçš„ç¶è·è€…:: @@ -251,7 +251,7 @@ objdump 請注æ„它將指出： -- 最後接觸原始碼的開發人員（如果這是在git樹ä¸å®Œæˆçš„）。在上é¢çš„例åä¸æ˜¯Tejun +- 最後接觸æºä»£ç¢¼çš„開發人員（如果這是在git樹ä¸å®Œæˆçš„）。在上é¢çš„例åä¸æ˜¯Tejun å’ŒBhaktipriya（在這個特定的案例ä¸ï¼Œæ²’有人真æ£åƒèˆ‡é€™å€‹æ–‡ä»¶çš„開發）； - é©…å‹•ç¶è·äººå“¡ï¼ˆHans Verkuil）； - å系統ç¶è·äººå“¡ï¼ˆMauro Carvalho Chehab）； diff --git a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst index bd0c08aab8ea..6961006b4a2d 100644 --- a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst +++ b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst @@ -7,10 +7,10 @@ 清除 WARN_ONCE -------------- -WARN_ONCE / WARN_ON_ONCE / printk_once 僅僅列å°ä¸€æ¬¡æ¶ˆæ¯. +WARN_ONCE / WARN_ON_ONCE / printk_once 僅僅打å°ä¸€æ¬¡æ¶ˆæ¯. echo 1 > /sys/kernel/debug/clear_warn_once -å¯ä»¥æ¸…除這種狀態並且å†æ¬¡å…許列å°ä¸€æ¬¡å‘Šè¦ä¿¡æ¯ï¼Œé€™å°æ–¼é‹è¡Œæ¸¬è©¦é›†å¾Œé‡ç¾å•é¡Œ +å¯ä»¥æ¸…除這種狀態並且å†æ¬¡å…許打å°ä¸€æ¬¡å‘Šè¦ä¿¡æ¯ï¼Œé€™å°æ–¼é‹è¡Œæ¸¬è©¦é›†å¾Œé‡ç¾å•é¡Œ 很有用。 diff --git a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst index 9e04aeac1a5c..cc046f3b7ffa 100644 --- a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst +++ b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst @@ -20,13 +20,13 @@ Linux通éŽ``/proc/stat``å’Œ``/proc/uptime``導出å„種信æ¯ï¼Œç”¨æˆ¶ç©ºé–“å·¥ ... -這裡系統èªçˆ²åœ¨é»˜èªæŽ¡æ¨£å‘¨æœŸå…§æœ‰10.01%的時間工作在用戶空間，2.92%的時 +這è£ç³»çµ±èªçˆ²åœ¨é»˜èªæŽ¡æ¨£é€±æœŸå…§æœ‰10.01%的時間工作在用戶空間，2.92%的時 間用在系統空間，總體上有81.63%的時間是空閒的。 大多數情æ³ä¸‹``/proc/stat``çš„ä¿¡æ¯å¹¾ä¹ŽçœŸå¯¦åæ˜ äº†ç³»çµ±ä¿¡æ¯ï¼Œç„¶è€Œï¼Œç”±æ–¼å…§ æ ¸æŽ¡é›†é€™äº›æ•¸æ“šçš„æ–¹å¼/時間的特點，有時這些信æ¯æ ¹æœ¬ä¸å¯é 。 -那麼這些信æ¯æ˜¯å¦‚何被æœé›†çš„呢？æ¯ç•¶æ™‚é–“ä¸æ–·è§¸ç™¼æ™‚ï¼Œå…§æ ¸æŸ¥çœ‹æ¤åˆ»é‹è¡Œçš„ +那麼這些信æ¯æ˜¯å¦‚何被è’集的呢？æ¯ç•¶æ™‚é–“ä¸æ–·è§¸ç™¼æ™‚ï¼Œå…§æ ¸æŸ¥çœ‹æ¤åˆ»é‹è¡Œçš„ é€²ç¨‹é¡žåž‹ï¼Œä¸¦å¢žåŠ èˆ‡æ¤é¡žåž‹/狀態進程å°æ‡‰çš„計數器的值。這種方法的å•é¡Œæ˜¯ 在兩次時間ä¸æ–·ä¹‹é–“ç³»çµ±ï¼ˆé€²ç¨‹ï¼‰èƒ½å¤ åœ¨å¤šç¨®ç‹€æ…‹ä¹‹é–“åˆ‡æ›å¤šæ¬¡ï¼Œè€Œè¨ˆæ•¸å™¨åª å¢žåŠ æœ€å¾Œä¸€ç¨®ç‹€æ…‹ä¸‹çš„è¨ˆæ•¸ã€‚ @@ -34,7 +34,7 @@ Linux通éŽ``/proc/stat``å’Œ``/proc/uptime``導出å„種信æ¯ï¼Œç”¨æˆ¶ç©ºé–“å·¥ 舉例 --- -å‡è¨ç³»çµ±æœ‰ä¸€å€‹é€²ç¨‹ä»¥å¦‚下方å¼å‘¨æœŸæ€§åœ°å 用cpu:: +å‡è¨ç³»çµ±æœ‰ä¸€å€‹é€²ç¨‹ä»¥å¦‚下方å¼é€±æœŸæ€§åœ°ä½”用cpu:: 兩個時é˜ä¸æ–·ä¹‹é–“的時間線 |-----------------------| @@ -46,7 +46,7 @@ Linux通éŽ``/proc/stat``å’Œ``/proc/uptime``導出å„種信æ¯ï¼Œç”¨æˆ¶ç©ºé–“å·¥ 在上é¢çš„情æ³ä¸‹ï¼Œæ ¹æ“š``/proc/stat``çš„ä¿¡æ¯ï¼ˆç”±æ–¼ç•¶ç³»çµ±è™•æ–¼ç©ºé–’狀態時， 時間ä¸æ–·ç¶“å¸¸æœƒç™¼ç”Ÿï¼‰ç³»çµ±çš„è² è¼‰å°‡æœƒæ˜¯0 -å¤§å®¶èƒ½å¤ æƒ³åƒå…§æ ¸çš„這種行爲會發生在許多情æ³ä¸‹ï¼Œé€™å°‡å°Žè‡´``/proc/stat`` +å¤§å®¶èƒ½å¤ æƒ³è±¡å…§æ ¸çš„é€™ç¨®è¡Œçˆ²æœƒç™¼ç”Ÿåœ¨è¨±å¤šæƒ…æ³ä¸‹ï¼Œé€™å°‡å°Žè‡´``/proc/stat`` ä¸å˜åœ¨ç›¸ç•¶å¤æ€ªçš„ä¿¡æ¯:: /* gcc -o hog smallhog.c */ diff --git a/Documentation/translations/zh_TW/admin-guide/cputopology.rst b/Documentation/translations/zh_TW/admin-guide/cputopology.rst new file mode 100644 index 000000000000..5c46d1b3b065 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/cputopology.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/cputopology.rst + +:ç¿»è¯: + + å”è—舟 Tang Yizhou <tangyeechou@gmail.com> + +========================== +如何通éŽsysfså°‡CPU拓撲導出 +========================== + +CPU拓撲信æ¯é€šéŽsysfså°Žå‡ºã€‚é¡¯ç¤ºçš„é …ï¼ˆå±¬æ€§ï¼‰å’ŒæŸäº›æž¶æ§‹çš„/proc/cpuinfo輸出相似。它們ä½æ–¼ +/sys/devices/system/cpu/cpuX/topology/。請閱讀ABI文件： +Documentation/ABI/stable/sysfs-devices-system-cpu。 + +drivers/base/topology.c是體系çµæ§‹ä¸æ€§çš„，它導出了這些屬性。然而，dieã€clusterã€book〠+draw這些層次çµæ§‹ç›¸é—œçš„文件僅在體系çµæ§‹æ供了下文æè¿°çš„å®çš„æ¢ä»¶ä¸‹è¢«å‰µå»ºã€‚ + +å°æ–¼æ”¯æŒé€™å€‹ç‰¹æ€§çš„體系çµæ§‹ï¼Œå®ƒå¿…é ˆåœ¨include/asm-XXX/topology.hä¸å®šç¾©é€™äº›å®ä¸çš„一部分:: + + #define topology_physical_package_id(cpu) + #define topology_die_id(cpu) + #define topology_cluster_id(cpu) + #define topology_core_id(cpu) + #define topology_book_id(cpu) + #define topology_drawer_id(cpu) + #define topology_sibling_cpumask(cpu) + #define topology_core_cpumask(cpu) + #define topology_cluster_cpumask(cpu) + #define topology_die_cpumask(cpu) + #define topology_book_cpumask(cpu) + #define topology_drawer_cpumask(cpu) + +``**_id macros`` 的類型是int。 +``**_cpumask macros`` 的類型是 ``(const) struct cpumask *`` 。後者和æ°ç•¶çš„ +``**_siblings`` sysfs屬性å°æ‡‰ï¼ˆé™¤äº†topology_sibling_cpumask()，它和thread_siblings +å°æ‡‰ï¼‰ã€‚ + +爲了在所有體系çµæ§‹ä¸Šä¿æŒä¸€è‡´ï¼Œinclude/linux/topology.hæ供了上述所有å®çš„默èªå®šç¾©ï¼Œä»¥é˜² +它們未在include/asm-XXX/topology.hä¸å®šç¾©: + +1) topology_physical_package_id: -1 +2) topology_die_id: -1 +3) topology_cluster_id: -1 +4) topology_core_id: 0 +5) topology_book_id: -1 +6) topology_drawer_id: -1 +7) topology_sibling_cpumask: 僅入åƒCPU +8) topology_core_cpumask: 僅入åƒCPU +9) topology_cluster_cpumask: 僅入åƒCPU +10) topology_die_cpumask: 僅入åƒCPU +11) topology_book_cpumask: 僅入åƒCPU +12) topology_drawer_cpumask: 僅入åƒCPU + +æ¤å¤–，CPU拓撲信æ¯ç”±/sys/devices/system/cpuæ供，包å«ä¸‹è¿°æ–‡ä»¶ã€‚輸出å°æ‡‰çš„內部數據æºæ”¾åœ¨ +方括號（"[]"）ä¸ã€‚ + + =========== ================================================================== + kernel_max: å…§æ ¸é…ç½®å…許的最大CPU下標值。[NR_CPUS-1] + + offline: 由於熱æ’拔移除或者超éŽå…§æ ¸å…許的CPU上é™ï¼ˆä¸Šæ–‡æè¿°çš„kernel_max） + 導致未上線的CPU。[~cpu_online_mask + cpus >= NR_CPUS] + + online: 在線的CPU，å¯ä¾›èª¿åº¦ä½¿ç”¨ã€‚[cpu_online_mask] + + possible: 已被分é…資æºçš„CPU，如果它們CPU實際å˜åœ¨ï¼Œå¯ä»¥ä¸Šç·šã€‚ + [cpu_possible_mask] + + present: 被系統è˜åˆ¥å¯¦éš›å˜åœ¨çš„CPU。[cpu_present_mask] + =========== ================================================================== + +ä¸Šè¿°è¼¸å‡ºçš„æ ¼å¼å’Œcpulist_parse()兼容[åƒè¦‹ <linux/cpumask.h>]。下é¢çµ¦äº›ä¾‹å。 + +在本例ä¸ï¼Œç³»çµ±ä¸æœ‰64個CPU，但是CPU 32-63超éŽäº†kernel_maxå€¼ï¼Œå› çˆ²NR_CPUSé…ç½®é …æ˜¯32， +å–值範åœè¢«é™åˆ¶çˆ²0..31。æ¤å¤–注æ„CPU2å’Œ4-31未上線，但是å¯ä»¥ä¸Šç·šï¼Œå› 爲它們åŒæ™‚å˜åœ¨æ–¼ +presentå’Œpossible:: + + kernel_max: 31 + offline: 2,4-31,32-63 + online: 0-1,3 + possible: 0-31 + present: 0-31 + +在本例ä¸ï¼ŒNR_CPUSé…ç½®é …æ˜¯128ï¼Œä½†å…§æ ¸å•“å‹•æ™‚è¨ç½®possible_cpus=144。系統ä¸æœ‰4個CPU， +CPU2被手動è¨ç½®ä¸‹ç·šï¼ˆä¹Ÿæ˜¯å”¯ä¸€ä¸€å€‹å¯ä»¥ä¸Šç·šçš„CPU）:: + + kernel_max: 127 + offline: 2,4-127,128-143 + online: 0-1,3 + possible: 0-127 + present: 0-3 + +閱讀Documentation/core-api/cpu_hotplug.rstå¯çžè§£é–‹æ©Ÿåƒæ•¸possible_cpus=NUM，åŒæ™‚é‚„ +å¯ä»¥çžè§£å„種cpumaskçš„ä¿¡æ¯ã€‚ + diff --git a/Documentation/translations/zh_TW/admin-guide/index.rst b/Documentation/translations/zh_TW/admin-guide/index.rst index 2804d619201d..aba8939351e0 100644 --- a/Documentation/translations/zh_TW/admin-guide/index.rst +++ b/Documentation/translations/zh_TW/admin-guide/index.rst @@ -3,13 +3,14 @@ .. include:: ../disclaimer-zh_TW.rst :Original: :doc:`../../../admin-guide/index` -:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + 胡皓文 Hu Haowen <src.res.211@gmail.com> Linux å…§æ ¸ç”¨æˆ¶å’Œç®¡ç†å“¡æŒ‡å— ========================== 下é¢æ˜¯ä¸€çµ„éš¨æ™‚é–“æ·»åŠ åˆ°å…§æ ¸ä¸çš„é¢å‘用戶的文檔的集åˆã€‚到目å‰çˆ²æ¢ï¼Œé‚„沒有一個 -æ•´é«”çš„é †åºæˆ–組織 - 這些ææ–™ä¸æ˜¯ä¸€å€‹å–®ä¸€çš„，連貫的文件ï¼å¹¸é‹çš„話，情æ³æœƒéš¨è‘— +æ•´é«”çš„é †åºæˆ–組織 - 這些ææ–™ä¸æ˜¯ä¸€å€‹å–®ä¸€çš„，連貫的文件ï¼å¹¸é‹çš„話，情æ³æœƒéš¨ç€ 時間的推移而迅速改善。 這個åˆå§‹éƒ¨åˆ†åŒ…å«ç¸½é«”ä¿¡æ¯ï¼ŒåŒ…括æè¿°å…§æ ¸çš„README， é—œæ–¼å…§æ ¸åƒæ•¸çš„文檔ç‰ã€‚ @@ -21,15 +22,15 @@ Linux å…§æ ¸ç”¨æˆ¶å’Œç®¡ç†å“¡æŒ‡å— Todolist: - kernel-parameters - devices - sysctl/index +* kernel-parameters +* devices +* sysctl/index 本節介紹CPUæ¼æ´žåŠå…¶ç·©è§£æŽªæ–½ã€‚ Todolist: - hw-vuln/index +* hw-vuln/index 下é¢çš„一組文檔，é‡å°çš„是試圖跟蹤å•é¡Œå’Œbug的用戶。 @@ -37,6 +38,7 @@ Todolist: :maxdepth: 1 reporting-issues + reporting-regressions security-bugs bug-hunting bug-bisect @@ -45,18 +47,17 @@ Todolist: Todolist: - reporting-bugs - ramoops - dynamic-debug-howto - kdump/index - perf/index +* ramoops +* dynamic-debug-howto +* kdump/index +* perf/index -這是應用程å¼é–‹ç™¼äººå“¡æ„Ÿèˆˆè¶£çš„ç« ç¯€çš„é–‹å§‹ã€‚å¯ä»¥åœ¨é€™è£¡æ‰¾åˆ°æ¶µè“‹å…§æ ¸ABIå„個 +這是應用程åºé–‹ç™¼äººå“¡æ„Ÿèˆˆè¶£çš„ç« ç¯€çš„é–‹å§‹ã€‚å¯ä»¥åœ¨é€™è£æ‰¾åˆ°æ¶µè“‹å…§æ ¸ABIå„個 æ–¹é¢çš„文檔。 Todolist: - sysfs-rules +* sysfs-rules 本手冊的其餘部分包括å„種指å—ï¼Œä»‹ç´¹å¦‚ä½•æ ¹æ“šæ‚¨çš„å–œå¥½é…ç½®å…§æ ¸çš„ç‰¹å®šè¡Œçˆ²ã€‚ @@ -64,67 +65,67 @@ Todolist: .. toctree:: :maxdepth: 1 + bootconfig clearing-warn-once cpu-load + cputopology + lockup-watchdogs unicode + sysrq + mm/index Todolist: - acpi/index - aoe/index - auxdisplay/index - bcache - binderfs - binfmt-misc - blockdev/index - bootconfig - braille-console - btmrvl - cgroup-v1/index - cgroup-v2 - cifs/index - cputopology - dell_rbu - device-mapper/index - edid - efi-stub - ext4 - nfs/index - gpio/index - highuid - hw_random - initrd - iostats - java - jfs - kernel-per-CPU-kthreads - laptops/index - lcd-panel-cgram - ldm - lockup-watchdogs - LSM/index - md - media/index - mm/index - module-signing - mono - namespaces/index - numastat - parport - perf-security - pm/index - pnp - rapidio - ras - rtc - serial-console - svga - sysrq - thunderbolt - ufs - vga-softcursor - video-output - xfs +* acpi/index +* aoe/index +* auxdisplay/index +* bcache +* binderfs +* binfmt-misc +* blockdev/index +* braille-console +* btmrvl +* cgroup-v1/index +* cgroup-v2 +* cifs/index +* dell_rbu +* device-mapper/index +* edid +* efi-stub +* ext4 +* nfs/index +* gpio/index +* highuid +* hw_random +* initrd +* iostats +* java +* jfs +* kernel-per-CPU-kthreads +* laptops/index +* lcd-panel-cgram +* ldm +* LSM/index +* md +* media/index +* module-signing +* mono +* namespaces/index +* numastat +* parport +* perf-security +* pm/index +* pnp +* rapidio +* ras +* rtc +* serial-console +* svga +* thunderbolt +* ufs +* vga-softcursor +* video-output +* xfs .. only:: subproject and html diff --git a/Documentation/translations/zh_TW/admin-guide/init.rst b/Documentation/translations/zh_TW/admin-guide/init.rst index db3fdf611080..be6e34f5f7fa 100644 --- a/Documentation/translations/zh_TW/admin-guide/init.rst +++ b/Documentation/translations/zh_TW/admin-guide/init.rst @@ -9,8 +9,8 @@ å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> 胡皓文 Hu Haowen <src.res.211@gmail.com> -解釋「No working init found.ã€å•“å‹•æŽ›èµ·æ¶ˆæ¯ -========================================== +解釋“No working init found.â€å•“å‹•æŽ›èµ·æ¶ˆæ¯ +========================================= :作者: @@ -18,41 +18,41 @@ Cristian Souza <cristianmsbr at gmail period com> -本文檔æä¾›äº†åŠ è¼‰åˆå§‹åŒ–二進ä½ï¼ˆinit binaryï¼‰å¤±æ•—çš„ä¸€äº›é«˜å±¤ç´šåŽŸå› ï¼ˆå¤§è‡´æŒ‰åŸ·è¡Œ +本文檔æä¾›äº†åŠ è¼‰åˆå§‹åŒ–二進制（init binaryï¼‰å¤±æ•—çš„ä¸€äº›é«˜å±¤ç´šåŽŸå› ï¼ˆå¤§è‡´æŒ‰åŸ·è¡Œ é †åºåˆ—出）。 -1) **ç„¡æ³•æŽ›è¼‰æ ¹æ–‡ä»¶ç³»çµ±Unable to mount root FS** ：請è¨ç½®ã€Œdebugã€å…§æ ¸åƒæ•¸ï¼ˆåœ¨ +1) **ç„¡æ³•æŽ›è¼‰æ ¹æ–‡ä»¶ç³»çµ±Unable to mount root FS** ：請è¨ç½®â€œdebugâ€å…§æ ¸åƒæ•¸ï¼ˆåœ¨ å¼•å°ŽåŠ è¼‰ç¨‹åºbootloaderé…置文件或CONFIG_CMDLINE）以ç²å–æ›´è©³ç´°çš„å…§æ ¸æ¶ˆæ¯ã€‚ -2) **åˆå§‹åŒ–二進ä½ä¸å˜åœ¨æ–¼æ ¹æ–‡ä»¶ç³»çµ±ä¸Šinit binary doesn't exist on rootfs** ： +2) **åˆå§‹åŒ–二進制ä¸å˜åœ¨æ–¼æ ¹æ–‡ä»¶ç³»çµ±ä¸Šinit binary doesn't exist on rootfs** ： 確ä¿æ‚¨çš„æ ¹æ–‡ä»¶ç³»çµ±é¡žåž‹æ£ç¢ºï¼ˆä¸¦ä¸” ``root=`` å…§æ ¸åƒæ•¸æŒ‡å‘æ£ç¢ºçš„分å€ï¼‰ï¼›æ“有 - 所需的驅動程åºï¼Œä¾‹å¦‚SCSI或USBç‰å˜å„²ç¡¬é«”；文件系統（ext3ã€jffs2ç‰ï¼‰æ˜¯å…§å»ºçš„ + 所需的驅動程åºï¼Œä¾‹å¦‚SCSI或USBç‰å˜å„²ç¡¬ä»¶ï¼›æ–‡ä»¶ç³»çµ±ï¼ˆext3ã€jffs2ç‰ï¼‰æ˜¯å…§å»ºçš„ （或者作爲模塊由initrdé åŠ è¼‰ï¼‰ã€‚ -3) **控制å°è¨å‚™æ壞Broken console device** ： ``console= setup`` ä¸å¯èƒ½å˜åœ¨ - è¡çª --> åˆå§‹æŽ§åˆ¶å°ä¸å¯ç”¨ï¼ˆinitial console unavailable）。例如，由於串行 - IRQå•é¡Œï¼ˆå¦‚缺少基於ä¸æ–·çš„é…置）導致的æŸäº›ä¸²è¡ŒæŽ§åˆ¶å°ä¸å¯é 。嘗試使用ä¸åŒçš„ +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`` 丟失或æ壞。使用 +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 +5) **ç„¡æ³•åŠ è¼‰äºŒé€²åˆ¶Binary cannot be loaded** ：請確ä¿äºŒé€²åˆ¶çš„體系çµæ§‹èˆ‡æ‚¨çš„ + 硬件匹é…。例如i386ä¸åŒ¹é…x86_64，或者嘗試在ARMç¡¬ä»¶ä¸ŠåŠ è¼‰x86。如果您嘗試在 + æ¤è™•åŠ 載éžäºŒé€²åˆ¶æ–‡ä»¶ï¼ˆshell腳本？），您應該確ä¿è…³æœ¬åœ¨å…¶å·¥ä½œé （shebang header）行 ``#!/...`` ä¸æŒ‡å®šèƒ½æ£å¸¸å·¥ä½œçš„解釋器（包括其庫ä¾è³´é …ï¼‰ã€‚åœ¨è™•ç† - 腳本之å‰ï¼Œæœ€å¥½å…ˆæ¸¬è©¦ä¸€å€‹ç°¡å–®çš„éžè…³æœ¬äºŒé€²ä½æ–‡ä»¶ï¼Œæ¯”如 ``/bin/sh`` ï¼Œä¸¦ç¢ºèª + 腳本之å‰ï¼Œæœ€å¥½å…ˆæ¸¬è©¦ä¸€å€‹ç°¡å–®çš„éžè…³æœ¬äºŒé€²åˆ¶æ–‡ä»¶ï¼Œæ¯”如 ``/bin/sh`` ï¼Œä¸¦ç¢ºèª å®ƒèƒ½æˆåŠŸåŸ·è¡Œã€‚è¦äº†è§£æ›´å¤šä¿¡æ¯ï¼Œè«‹å°‡ä»£ç¢¼æ·»åŠ 到 ``init/main.c`` 以顯示 kernel_execve()的返回值。 -當您發ç¾æ–°çš„å¤±æ•—åŽŸå› æ™‚ï¼Œè«‹æ“´å±•æœ¬è§£é‡‹ï¼ˆç•¢ç«ŸåŠ è¼‰åˆå§‹åŒ–二進ä½æ˜¯ä¸€å€‹ **é—œéµ** 且 +當您發ç¾æ–°çš„å¤±æ•—åŽŸå› æ™‚ï¼Œè«‹æ“´å±•æœ¬è§£é‡‹ï¼ˆç•¢ç«ŸåŠ è¼‰åˆå§‹åŒ–二進制是一個 **é—œéµ** 且 艱難的éŽæ¸¡æ¥é©Ÿï¼Œéœ€è¦å„˜å¯èƒ½ç„¡ç—›åœ°é€²è¡Œï¼‰ï¼Œç„¶å¾Œå‘LKMLæ交一個補ä¸ã€‚ å¾…è¾¦äº‹é …ï¼š - 通éŽä¸€å€‹å¯ä»¥å˜å„² ``kernel_execve()`` çµæžœå€¼çš„çµæ§‹é«”數組實ç¾å„種 - ``run_init_process()`` 調用，並在失敗時通éŽç–Šä»£ **所有** çµæžœä¾†è¨˜éŒ„一切 + ``run_init_process()`` 調用，並在失敗時通éŽè¿ä»£ **所有** çµæžœä¾†è¨˜éŒ„一切 （éžå¸¸é‡è¦çš„å¯ç”¨æ€§ä¿®å¾©ï¼‰ã€‚ -- 試著使實ç¾æœ¬èº«åœ¨ä¸€èˆ¬æƒ…æ³ä¸‹æ›´æœ‰å¹«åŠ©ï¼Œä¾‹å¦‚在å—影響的地方æä¾›é¡å¤–的錯誤消æ¯ã€‚ +- 試ç€ä½¿å¯¦ç¾æœ¬èº«åœ¨ä¸€èˆ¬æƒ…æ³ä¸‹æ›´æœ‰å¹«åŠ©ï¼Œä¾‹å¦‚在å—影響的地方æä¾›é¡å¤–的錯誤消æ¯ã€‚ diff --git a/Documentation/translations/zh_TW/admin-guide/lockup-watchdogs.rst b/Documentation/translations/zh_TW/admin-guide/lockup-watchdogs.rst new file mode 100644 index 000000000000..f65b0c96e8e3 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/lockup-watchdogs.rst @@ -0,0 +1,67 @@ +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/lockup-watchdogs.rst +:Translator: Hailong Liu <liu.hailong6@zte.com.cn> + +.. _tw_lockup-watchdogs: + + +================================================= +Softlockup與hardlockup檢測機制(åˆå:nmi_watchdog) +================================================= + +Linuxä¸å…§æ ¸å¯¦ç¾äº†ä¸€ç¨®ç”¨ä»¥æª¢æ¸¬ç³»çµ±ç™¼ç”Ÿsoftlockupå’Œhardlockup的看門狗機制。 + +Softlockupæ˜¯ä¸€ç¨®æœƒå¼•ç™¼ç³»çµ±åœ¨å…§æ ¸æ…‹ä¸ä¸€ç›´å¾ªç’°è¶…éŽ20秒（詳見下é¢â€œå¯¦ç¾â€å°ç¯€ï¼‰å°Žè‡´ +其他任務沒有機會得到é‹è¡Œçš„BUG。一旦檢測到'softlockup'發生，默èªæƒ…æ³ä¸‹ç³»çµ±æœƒæ‰“ +å°ç•¶å‰å †æ£§è·Ÿè¹¤ä¿¡æ¯ä¸¦é€²å…¥éŽ–定狀態。也å¯é…置使其在檢測到'softlockup'後進入panic +狀態；通éŽsysctl命令è¨ç½®â€œkernel.softlockup_panicâ€ã€ä½¿ç”¨å…§æ ¸å•“å‹•åƒæ•¸ +“softlockup_panicâ€ï¼ˆè©³è¦‹Documentation/admin-guide/kernel-parameters.rst）以åŠä½¿ +èƒ½å…§æ ¸ç·¨è¯é¸é …“BOOTPARAM_SOFTLOCKUP_PANICâ€éƒ½å¯å¯¦ç¾é€™ç¨®é…置。 + +而'hardlockup'æ˜¯ä¸€ç¨®æœƒå¼•ç™¼ç³»çµ±åœ¨å…§æ ¸æ…‹ä¸€ç›´å¾ªç’°è¶…éŽ10秒é˜ï¼ˆè©³è¦‹"實ç¾"å°ç¯€ï¼‰å°Žè‡´å…¶ +ä»–ä¸æ–·æ²’有機會é‹è¡Œçš„缺陷。與'softlockup'情æ³é¡žä¼¼ï¼Œé™¤äº†ä½¿ç”¨sysctl命令è¨ç½® +'hardlockup_panic'ã€ä½¿èƒ½å…§æ ¸é¸é …“BOOTPARAM_HARDLOCKUP_PANICâ€ä»¥åŠä½¿ç”¨å…§æ ¸åƒæ•¸ +"nmi_watchdog"(詳見:â€Documentation/admin-guide/kernel-parameters.rst“)外，一旦檢 +測到'hardlockup'默èªæƒ…æ³ä¸‹ç³»çµ±æ‰“å°ç•¶å‰å †æ£§è·Ÿè¹¤ä¿¡æ¯ï¼Œç„¶å¾Œé€²å…¥éŽ–定狀態。 + +這個panicé¸é …也å¯ä»¥èˆ‡panic_timeoutçµåˆä½¿ç”¨ï¼ˆé€™å€‹panic_timeout是通éŽç¨å…·è¿·æƒ‘性的 +sysctl命令"kernel.panic"來è¨ç½®ï¼‰ï¼Œä½¿ç³»çµ±åœ¨panic指定時間後自動é‡å•“。 + +å¯¦ç¾ +==== + +Softlockupå’Œhardlockup分別建立在hrtimer(高精度定時器)å’Œperf兩個å系統上而實ç¾ã€‚ +這也就æ„味ç€ç†è«–上任何架構åªè¦å¯¦ç¾äº†é€™å…©å€‹å系統就支æŒé€™å…©ç¨®æª¢æ¸¬æ©Ÿåˆ¶ã€‚ + +Hrtimer用於週期性產生ä¸æ–·ä¸¦å–šé†’watchdog線程；NMI perf事件則以â€watchdog_thresh“ +(ç·¨è¯æ™‚默èªåˆå§‹åŒ–爲10秒，也å¯é€šéŽâ€watchdog_thresh“這個sysctl接å£ä¾†é€²è¡Œé…置修改) +爲間隔週期產生以檢測 hardlockups。如果一個CPU在這個時間段內沒有檢測到hrtimerä¸ +斷髮生，'hardlockup 檢測器'(å³NMI perf事件處ç†å‡½æ•¸)將會視系統é…置而é¸æ“‡ç”¢ç”Ÿå…§æ ¸ +è¦å‘Šæˆ–者直接panic。 + +而watchdogç·šç¨‹æœ¬è³ªä¸Šæ˜¯ä¸€å€‹é«˜å„ªå…ˆç´šå…§æ ¸ç·šç¨‹ï¼Œæ¯èª¿åº¦ä¸€æ¬¡å°±å°æ™‚間戳進行一次更新。 +如果時間戳在2*watchdog_thresh(這個是softlockup的觸發門é™)這段時間都未更新,那麼 +"softlocup 檢測器"(內部hrtimer定時器回調函數)會將相關的調試信æ¯æ‰“å°åˆ°ç³»çµ±æ—¥èªŒä¸ï¼Œ +然後如果系統é…置了進入panicæµç¨‹å‰‡é€²å…¥panic，å¦å‰‡å…§æ ¸ç¹¼çºŒåŸ·è¡Œã€‚ + +Hrtimer定時器的週期是2*watchdog_thresh/5，也就是說在hardlockup被觸發å‰hrtimer有 +2~3次機會產生時é˜ä¸æ–·ã€‚ + +如上所述,å…§æ ¸ç›¸ç•¶æ–¼çˆ²ç³»çµ±ç®¡ç†å“¡æ供了一個å¯èª¿ç¯€hrtimer定時器和perf事件週期長度 +的調節旋鈕。如何通éŽé€™å€‹æ—‹éˆ•çˆ²ç‰¹å®šä½¿ç”¨å ´æ™¯é…置一個åˆç†çš„週期值è¦å°lockups檢測的 +響應速度和lockups檢測開銷這二者之間進行權衡。 + +默èªæƒ…æ³ä¸‹æ‰€æœ‰åœ¨ç·šcpu上都會é‹è¡Œä¸€å€‹watchdog線程。ä¸éŽåœ¨å…§æ ¸é…置了â€NO_HZ_FULL“的 +情æ³ä¸‹watchdog線程默èªåªæœƒé‹è¡Œåœ¨ç®¡å®¶(housekeeping)cpu上，而â€nohz_full“啓動åƒæ•¸æŒ‡ +定的cpu上則ä¸æœƒæœ‰watchdog線程é‹è¡Œã€‚試想，如果我們å…許watchdog線程在â€nohz_full“指 +定的cpu上é‹è¡Œï¼Œé€™äº›cpuä¸Šå¿…é ˆå¾—é‹è¡Œæ™‚é˜å®šæ™‚器來激發watchdog線程調度；這樣一來就會 +使â€nohz_full“ä¿è·ç”¨æˆ¶ç¨‹åºå…å—å…§æ ¸å¹²æ“¾çš„åŠŸèƒ½å¤±æ•ˆã€‚ç•¶ç„¶ï¼Œå‰¯ä½œç”¨å°±æ˜¯â€nohz_full“指定 +çš„cpuå³ä½¿åœ¨å…§æ ¸ç”¢ç”Ÿäº†lockupå•é¡Œæˆ‘們也無法檢測到。ä¸éŽï¼Œè‡³å°‘我們å¯ä»¥å…許watchdog +線程在管家(non-tickless)æ ¸ä¸Šç¹¼çºŒé‹è¡Œä»¥ä¾¿æˆ‘們能繼續æ£å¸¸çš„監測這些cpus上的lockups +事件。 + +ä¸è«–哪種情æ³éƒ½å¯ä»¥é€šéŽsysctl命令kernel.watchdog_cpumask來å°æ²’有é‹è¡Œwatchdog線程 +çš„cpu集åˆé€²è¡Œèª¿ç¯€ã€‚å°æ–¼nohz_full而言,如果nohz_full cpu上有異常掛ä½çš„情æ³ï¼Œé€šéŽ +這種方å¼æ‰“開這些cpu上的watchdog進行調試å¯èƒ½æœƒæœ‰æ‰€ä½œç”¨ã€‚ + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/index.rst new file mode 100644 index 000000000000..a472eb3c708b --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/index.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/index.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯: + +============ +ç›£æ¸¬æ•¸æ“šè¨ªå• +============ + +:doc:`DAMON </mm/damon/index>` å…許輕é‡ç´šçš„數據訪å•ç›£æ¸¬ã€‚使用DAMON， +用戶å¯ä»¥åˆ†æžä»–們系統的內å˜è¨ªå•æ¨¡å¼ï¼Œä¸¦å„ªåŒ–它們。 + +.. toctree:: + :maxdepth: 2 + + start + usage + reclaim + lru_sort + + + + + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/lru_sort.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/lru_sort.rst new file mode 100644 index 000000000000..1ffc4b6b1d12 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/lru_sort.rst @@ -0,0 +1,264 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/lru_sort.rst + +:ç¿»è¯: + + 臧雷剛 Leigang Zang <zangleigang@hisilicon.com> + +:æ ¡è¯: + +================== +基於DAMONçš„LRUæŽ’åº +================== + +基於DAMONçš„LRU排åºæ˜¯ä¸€å€‹éœæ…‹çš„å…§æ ¸æ¨¡å¡Šï¼Œæ—¨åœ¨ç”¨æ–¼ä»¥ä¸»å‹•çš„ã€è¼•é‡ç´šçš„數據訪å•æ¨¡åž‹ +爲基礎的é é¢å„ªå…ˆç´šè™•ç†çš„LRUéˆè¡¨ä¸Šï¼Œä»¥ä½¿å¾—LRU上的數據訪å•æ¨¡åž‹æ›´çˆ²å¯ä¿¡ã€‚ + +哪è£éœ€è¦ä¸»å‹•çš„LRUæŽ’åº +===================== + +在一個大型系統ä¸ï¼Œä»¥é 爲粒度的訪å•æª¢æ¸¬æœƒæœ‰æ¯”較顯著的開銷，LRU通常ä¸æœƒä¸»å‹•åŽ»æŽ’åºï¼Œ +而是å°éƒ¨åˆ†ç‰¹æ®Šäº‹ä»¶é€²è¡Œéƒ¨åˆ†çš„ã€éŸ¿æ‡‰å¼çš„排åºï¼Œä¾‹å¦‚：特殊的用戶請求，系統調用或者 +å…§å˜å£“åŠ›ã€‚é€™å°Žè‡´ï¼Œåœ¨æœ‰äº›å ´æ™¯ä¸‹ï¼ŒLRUä¸èƒ½å¤ 完美的作爲一個å¯ä¿¡çš„數據訪å•æ¨¡åž‹ï¼Œæ¯”如 +在內å˜å£“力下å°ç›®æ¨™å…§å˜é€²è¡Œå›žæ”¶ã€‚ + +å› çˆ²DAMONèƒ½å¤ å„˜å¯èƒ½æº–確的è˜åˆ¥æ•¸æ“šè¨ªå•æ¨¡åž‹ï¼ŒåŒæ™‚åªå¼•èµ·ç”¨æˆ¶æŒ‡å®šç¯„åœçš„開銷，主動的 +執行DAMON_LRU_SORT讓LRU變得更爲å¯ä¿¡æ˜¯æœ‰ç›Šçš„，而且這隻需è¦è¼ƒå°‘å’Œå¯æŽ§çš„開銷。 + +這是如何工作的 +============== + +DAMON_LRU_SORT使用DAMON尋找熱é （範åœå…§çš„é é¢è¨ªå•é »çŽ‡é«˜æ–¼ç”¨æˆ¶æŒ‡å®šçš„閾值）和冷é +（範åœå…§çš„é é¢åœ¨è¶…éŽç”¨æˆ¶æŒ‡å®šçš„時間無訪å•ï¼‰ï¼Œä¸¦æ高熱é å’Œé™ä½Žå†·é 在LRUä¸çš„優先級。 +爲了é¿å…在排åºéŽç¨‹ä½”用更多的CPU計算資æºï¼Œå¯ä»¥è¨ç½®ä¸€å€‹CPU佔用時間的約æŸå€¼ã€‚在約 +æŸä¸‹ï¼Œåˆ†åˆ¥æå‡æˆ–者é™ä½Žæ›´å¤šçš„熱é 和冷é 。系統管ç†å“¡ä¹Ÿå¯ä»¥é…置三個內å˜æ°´ä½ä»¥æŽ§åˆ¶ +在何種æ¢ä»¶ä¸‹è‡ªå‹•æ¿€æ´»æˆ–者åœæ¢é€™ç¨®æ©Ÿåˆ¶ã€‚ + +冷熱閾值和CPUç´„æŸçš„默èªå€¼æ˜¯æ¯”較ä¿å®ˆçš„。這æ„味ç€ï¼Œåœ¨é»˜èªåƒæ•¸ä¸‹ï¼Œæ¨¡å¡Šå¯ä»¥å»£æ³›ä¸”ç„¡ +è² ä½œç”¨çš„ä½¿ç”¨åœ¨å¸¸è¦‹ç’°å¢ƒä¸ï¼ŒåŒæ™‚在åªæ¶ˆè€—一å°éƒ¨åˆ†CPU時間的情æ³ä¸‹ï¼Œçµ¦æœ‰å…§å˜å£“力的系 +çµ±æ供一定水平的冷熱è˜åˆ¥ã€‚ + +接å£ï¼šæ¨¡å¡Šåƒæ•¸ +============== + +使用æ¤ç‰¹æ€§ï¼Œä½ 首先需è¦ç¢ºèªä½ 的系統ä¸é‹è¡Œçš„å…§æ ¸åœ¨ç·¨è¯æ™‚啓用了 +``CONFIG_DAMON_LRU_SORT=y``. + +爲了讓系統管ç†å“¡æ‰“開或者關閉並且調節指定的系統，DAMON_LRU_SORTè¨è¨ˆäº†æ¨¡å¡Šåƒæ•¸ã€‚ +這æ„味ç€ï¼Œä½ å¯ä»¥æ·»åŠ ``damon_lru_sort.<parameter>=<value>`` åˆ°å…§æ ¸çš„å•“å‹•å‘½ä»¤è¡Œ +åƒæ•¸ï¼Œæˆ–者在 ``/sys/modules/damon_lru_sort/parameters/<parameter>`` 寫入æ£ç¢ºçš„ +值。 + +下邊是æ¯å€‹åƒæ•¸çš„æè¿° + +enabled +------- + +打開或者關閉DAMON_LRU_SORT. + +ä½ å¯ä»¥é€šéŽè¨ç½®é€™å€‹åƒæ•¸çˆ² ``Y`` 來打開DAMON_LRU_SORT。è¨ç½®çˆ² ``N`` 關閉 +DAMON_LRU_SORT。注æ„，在基於水ä½çš„激活的情æ³ä¸‹ï¼ŒDAMON_LRU_SORT有å¯èƒ½ä¸æœƒçœŸæ£åŽ» +監測或者åšLRU排åºã€‚å°é€™ç¨®æƒ…æ³ï¼Œåƒè€ƒä¸‹æ–¹é—œæ–¼æ°´ä½çš„æ述。 + +commit_inputs +------------- + +讓DAMON_LRU_SORTå†æ¬¡è®€å–輸入åƒæ•¸ï¼Œé™¤äº† ``enabled`` 。 + +在DAMON_LRU_SORTé‹è¡Œæ™‚，新的輸入åƒæ•¸é»˜èªä¸æœƒè¢«æ‡‰ç”¨ã€‚一旦這個åƒæ•¸è¢«è¨ç½®çˆ² ``Y`` +，DAMON_LRU_SORT會å†æ¬¡è®€å–除了 ``enabled`` 之外的åƒæ•¸ã€‚讀å–完æˆå¾Œï¼Œé€™å€‹åƒæ•¸æœƒè¢« +è¨ç½®çˆ² ``N`` 。如果在讀å–時發ç¾æœ‰ç„¡æ•ˆåƒæ•¸ï¼ŒDAMON_LRU_SORT會被關閉。 + +hot_thres_access_freq +--------------------- + +熱點內å˜å€åŸŸçš„訪å•é »çŽ‡é–¾å€¼ï¼Œåƒåˆ†æ¯”。 + +如果一個內å˜å€åŸŸçš„訪å•é »çŽ‡å¤§æ–¼ç‰æ–¼é€™å€‹å€¼ï¼ŒDAMON_LRU_SORT把這個å€åŸŸçœ‹ä½œç†±å€ï¼Œä¸¦ +在LRU上把這個å€åŸŸæ¨™è¨˜çˆ²å·²è¨ªå•ï¼Œå› 些在內å˜å£“力下這部分內å˜ä¸æœƒè¢«å›žæ”¶ã€‚默èªçˆ²50%。 + +cold_min_age +------------ + +用於è˜åˆ¥å†·å…§å˜å€åŸŸçš„時間閾值，單ä½æ˜¯å¾®ç§’。 + +如果一個內å˜å€åŸŸåœ¨é€™å€‹æ™‚間內未被訪å•éŽï¼ŒDAMON_LRU_SORT把這個å€åŸŸçœ‹ä½œå†·å€ï¼Œä¸¦åœ¨ +LRU上把這個å€åŸŸæ¨™è¨˜çˆ²æœªè¨ªå•ï¼Œå› æ¤åœ¨å…§å˜å£“力下這些內å˜æœƒé¦–先被回收。默èªå€¼çˆ²120 +秒。 + +quota_ms +-------- + +嘗試LRUéˆè¡¨æŽ’åºçš„時間é™åˆ¶ï¼Œå–®ä½æ˜¯æ¯«ç§’。 + +DAMON_LRU_SORT在一個時間窗å£å…§ï¼ˆquota_reset_interval_ms）內最多嘗試這麼長時間來 +å°LRU進行排åºã€‚這個å¯ä»¥ç”¨ä¾†ä½œçˆ²CPU計算資æºçš„ç´„æŸã€‚如果值爲0，則表示無é™åˆ¶ã€‚ + +默èª10毫秒。 + +quota_reset_interval_ms +----------------------- + +é…é¡è¨ˆæ™‚é‡ç½®é€±æœŸï¼Œæ¯«ç§’。 + +é…é¡è¨ˆæ™‚é‡ç½®é€±æœŸã€‚å³ï¼Œåœ¨quota_reset_interval_ms毫秒內，DAMON_LRU_SORTå°LRU進行 +排åºä¸æœƒè¶…éŽquota_ms或者quota_sz。 + +默èª1秒。 + +wmarks_interval +--------------- + +æ°´ä½çš„檢查週期，單ä½æ˜¯å¾®ç§’。 + +當DAMON_LRU_SORT使能但是由於水ä½è€Œä¸æ´»èºæ™‚檢查水ä½å‰æœ€å°çš„ç‰å¾…時間。默èªå€¼5秒。 + +wmarks_high +----------- + +空閒內å˜é«˜æ°´ä½ï¼Œåƒåˆ†æ¯”。 + +如果空閒內å˜æ°´ä½é«˜æ–¼é€™å€‹å€¼ï¼ŒDAMON_LRU_SORTåœæ¢å·¥ä½œï¼Œä¸åšä»»ä½•äº‹ï¼Œé™¤äº†é€±æœŸæ€§çš„檢 +查水ä½ã€‚默èª200(20%)。 + +wmarks_mid +---------- + +空閒內å˜ä¸é–“æ°´ä½ï¼Œåƒåˆ†æ¯”。 + +如果空閒內å˜æ°´ä½åœ¨é€™å€‹å€¼èˆ‡ä½Žæ°´ä½ä¹‹é–“，DAMON_LRU_SORT開始工作，開始檢測並å°LRUéˆ +表進行排åºã€‚默èª150(15%)。 + +wmarks_low +---------- + +空閒內å˜ä½Žæ°´ä½ï¼Œåƒåˆ†æ¯”。 + +如果空閒內å˜å°æ–¼é€™å€‹å€¼ï¼ŒDAMON_LRU_SORTä¸å†å·¥ä½œï¼Œä¸åšä»»ä½•äº‹ï¼Œé™¤äº†é€±æœŸæ€§çš„檢查水 +線。默èª50(5%)。 + +sample_interval +--------------- + +監測的採樣週期，微秒。 + +DAMONå°å†·å…§å˜ç›£æ¸¬çš„採樣週期。更多細節請åƒè€ƒDAMON文檔 (:doc:`usage`) 。默èª5 +毫秒。 + +aggr_interval +------------- + +監測的收集週期，微秒。 + +DAMONå°å†·å…§å˜é€²è¡Œæ”¶é›†çš„時間週期。更多細節請åƒè€ƒDAMON文檔 (:doc:`usage`) ã€‚é»˜èª +100毫秒。 + +min_nr_regions +-------------- + +最å°ç›£æ¸¬å€åŸŸæ•¸é‡ã€‚ + +å°å†·å…§å˜å€åŸŸç›£æ¸¬çš„最å°æ•¸é‡ã€‚這個值å¯ä»¥ä½œçˆ²ç›£æ¸¬è³ªé‡çš„下é™ã€‚ä¸éŽï¼Œé€™å€‹å€¼è¨ç½®çš„éŽ +å¤§æœƒå¢žåŠ é–‹éŠ·ã€‚æ›´å¤šç´°ç¯€è«‹åƒè€ƒDAMON文檔 (:doc:`usage`) 。默èªå€¼çˆ²10。 + +max_nr_regions +-------------- + +最大監測å€åŸŸæ•¸é‡ã€‚ + +å°å†·å…§å˜å€åŸŸç›£æ¸¬çš„最大數é‡ã€‚這個值å¯ä»¥ä½œçˆ²ç›£æ¸¬è³ªé‡çš„上é™ã€‚然而，這個值è¨ç½®çš„éŽ +低會導致監測çµæžœè®Šå·®ã€‚更多細節請åƒè€ƒDAMON文檔 (:doc:`usage`) 。默èªå€¼çˆ²1000。 + +monitor_region_start +-------------------- + +目標內å˜å€åŸŸçš„起始物ç†åœ°å€ã€‚ + +DAMON_LRU_SORTè¦è™•ç†çš„目標內å˜å€åŸŸçš„起始物ç†åœ°å€ã€‚默èªï¼Œä½¿ç”¨ç³»çµ±æœ€å¤§å…§å˜ã€‚ + +monitor_region_end +------------------ + +目標內å˜å€åŸŸçš„çµæŸç‰©ç†åœ°å€ã€‚ + +DAMON_LRU_SORTè¦è™•ç†çš„目標內å˜å€åŸŸçš„çµæŸç‰©ç†åœ°å€ã€‚默èªï¼Œä½¿ç”¨ç³»çµ±æœ€å¤§å…§å˜ã€‚ + +kdamond_pid +----------- + +DAMON線程的PID。 + +如果DAMON_LRU_SORT是使能的，這個表示任務線程的PID。其它情æ³çˆ²-1。 + +nr_lru_sort_tried_hot_regions +----------------------------- + +被嘗試進行LRU排åºçš„熱內å˜å€åŸŸçš„數é‡ã€‚ + +bytes_lru_sort_tried_hot_regions +-------------------------------- + +被嘗試進行LRU排åºçš„熱內å˜å€åŸŸçš„大å°ï¼ˆå—節）。 + +nr_lru_sorted_hot_regions +------------------------- + +æˆåŠŸé€²è¡ŒLRU排åºçš„熱內å˜å€åŸŸçš„數é‡ã€‚ + +bytes_lru_sorted_hot_regions +---------------------------- + +æˆåŠŸé€²è¡ŒLRU排åºçš„熱內å˜å€åŸŸçš„大å°ï¼ˆå—節）。 + +nr_hot_quota_exceeds +-------------------- + +熱å€åŸŸæ™‚é–“ç´„æŸè¶…éŽé™åˆ¶çš„次數。 + +nr_lru_sort_tried_cold_regions +------------------------------ + +被嘗試進行LRU排åºçš„冷內å˜å€åŸŸçš„數é‡ã€‚ + +bytes_lru_sort_tried_cold_regions +--------------------------------- + +被嘗試進行LRU排åºçš„冷內å˜å€åŸŸçš„大å°ï¼ˆå—節）。 + +nr_lru_sorted_cold_regions +-------------------------- + +æˆåŠŸé€²è¡ŒLRU排åºçš„冷內å˜å€åŸŸçš„數é‡ã€‚ + +bytes_lru_sorted_cold_regions +----------------------------- + +æˆåŠŸé€²è¡ŒLRU排åºçš„冷內å˜å€åŸŸçš„大å°ï¼ˆå—節）。 + +nr_cold_quota_exceeds +--------------------- + +冷å€åŸŸæ™‚é–“ç´„æŸè¶…éŽé™åˆ¶çš„次數。 + +Example +======= + +如下是一個é‹è¡Œæ™‚的命令示例，使DAMON_LRU_SORT查找訪å•é »çŽ‡è¶…éŽ50%çš„å€åŸŸä¸¦å°å…¶é€²è¡Œ +LRU的優先級的æå‡ï¼ŒåŒæ™‚é™ä½Žé‚£äº›è¶…éŽ120秒無人訪å•çš„å…§å˜å€åŸŸçš„優先級。優先級的處 +ç†è¢«é™åˆ¶åœ¨æœ€å¤š1%çš„CPU以é¿å…DAMON_LRU_SORT消費éŽå¤šCPU時間。在系統空閒內å˜è¶…éŽ50% +時DAMON_LRU_SORTåœæ¢å·¥ä½œï¼Œä¸¦åœ¨ä½Žæ–¼40%時é‡æ–°é–‹å§‹å·¥ä½œã€‚如果DAMON_RECLAIM沒有å–å¾— +進展且空閒內å˜ä½Žæ–¼20%，å†æ¬¡è®“DAMON_LRU_SORTåœæ¢å·¥ä½œï¼Œä»¥æ¤å›žé€€åˆ°ä»¥LRUéˆè¡¨çˆ²åŸºç¤Ž +以é é¢çˆ²å–®ä½çš„å…§å˜å›žæ”¶ä¸Šã€‚ :: + + # cd /sys/modules/damon_lru_sort/parameters + # echo 500 > hot_thres_access_freq + # echo 120000000 > cold_min_age + # echo 10 > quota_ms + # echo 1000 > quota_reset_interval_ms + # echo 500 > wmarks_high + # echo 400 > wmarks_mid + # echo 200 > wmarks_low + # echo Y > enabled + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/reclaim.rst new file mode 100644 index 000000000000..efed29c40e44 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/reclaim.rst @@ -0,0 +1,229 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/reclaim.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯: + +=============== +基於DAMON的回收 +=============== + +基於DAMON的回收（DAMON_RECLAIM）是一個éœæ…‹çš„å…§æ ¸æ¨¡å¡Šï¼Œæ—¨åœ¨ç”¨æ–¼è¼•åº¦å…§å˜å£“力下的主動和輕 +é‡ç´šçš„回收。它的目的ä¸æ˜¯å–代基於LRU列表的é é¢å›žæ”¶ï¼Œè€Œæ˜¯æœ‰é¸æ“‡åœ°ç”¨æ–¼ä¸åŒç¨‹åº¦çš„å…§å˜å£“åŠ›å’Œè¦ +求。 + +哪些地方需è¦ä¸»å‹•å›žæ”¶ï¼Ÿ +====================== + +在一般的內å˜è¶…é‡ä½¿ç”¨ï¼ˆover-committed systems，虛擬化相關術語）的系統上，主動回收冷é +有助於節çœå…§å˜å’Œæ¸›å°‘延é²é«˜å³¯ï¼Œé€™äº›å»¶é²æ˜¯ç”±ç›´æŽ¥å›žæ”¶é€²ç¨‹æˆ–kswapdçš„CPU消耗引起的，åŒæ™‚åªç”¢ +生最å°çš„æ€§èƒ½ä¸‹é™ [1]_ [2]_ 。 + +基於空閒é å ±å‘Š [3]_ çš„å…§å˜éŽåº¦æ‰¿è«¾çš„虛擬化系統就是很好的例å。在這樣的系統ä¸ï¼Œå®¢æˆ¶æ©Ÿ +å‘ä¸»æ©Ÿå ±å‘Šä»–å€‘çš„ç©ºé–’å…§å˜ï¼Œè€Œä¸»æ©Ÿå‰‡å°‡å ±å‘Šçš„å…§å˜é‡æ–°åˆ†é…çµ¦å…¶ä»–å®¢æˆ¶ã€‚å› æ¤ï¼Œç³»çµ±çš„å…§å˜å¾—到了充 +分的利用。然而，客戶å¯èƒ½ä¸é‚£éº¼ç¯€çœå…§å˜ï¼Œä¸»è¦æ˜¯å› çˆ²ä¸€äº›å…§æ ¸å系統和用戶空間應用程åºè¢«è¨è¨ˆçˆ² +使用盡å¯èƒ½å¤šçš„å…§å˜ã€‚然後，客戶機å¯èƒ½åªå‘ä¸»æ©Ÿå ±å‘Šå°‘é‡çš„å…§å˜æ˜¯ç©ºé–’的，導致系統的內å˜åˆ©ç”¨çŽ‡ä¸‹é™ã€‚ +在客戶ä¸é‹è¡Œä¸»å‹•å›žæ”¶å¯ä»¥ç·©è§£é€™å€‹å•é¡Œã€‚ + +它是如何工作的？ +================ + +DAMON_RECLAIM找到在特定時間內沒有被訪å•çš„å…§å˜å€åŸŸä¸¦åˆ†é 。爲了é¿å…它在分é æ“作ä¸æ¶ˆè€—éŽå¤š +çš„CPU，å¯ä»¥é…置一個速度é™åˆ¶ã€‚在這個速度é™åˆ¶ä¸‹ï¼Œå®ƒé¦–先分é 出那些沒有被訪å•éŽçš„å…§å˜å€åŸŸã€‚ç³» +統管ç†å“¡é‚„å¯ä»¥é…置在什麼情æ³ä¸‹é€™å€‹æ–¹æ¡ˆæ‡‰è©²è‡ªå‹•æ¿€æ´»å’Œåœç”¨ä¸‰å€‹å…§å˜å£“力水ä½ã€‚ + +接å£: 模塊åƒæ•¸ +============== + +è¦ä½¿ç”¨é€™å€‹åŠŸèƒ½ï¼Œä½ 首先è¦ç¢ºä¿ä½ 的系統é‹è¡Œåœ¨ä¸€å€‹ä»¥ ``CONFIG_DAMON_RECLAIM=y`` 構建的內 +æ ¸ä¸Šã€‚ + +爲了讓系統管ç†å“¡å•“用或ç¦ç”¨å®ƒï¼Œä½µçˆ²çµ¦å®šçš„系統進行調整，DAMON_RECLAIM利用了模塊åƒæ•¸ã€‚也就 +æ˜¯èªªï¼Œä½ å¯ä»¥æŠŠ ``damon_reclaim.<parameter>=<value>`` æ”¾åœ¨å…§æ ¸å•“å‹•å‘½ä»¤è¡Œä¸Šï¼Œæˆ–è€…æŠŠ +é©ç•¶çš„值寫入 ``/sys/module/damon_reclaim/parameters/<parameter>`` 文件。 + +下é¢æ˜¯æ¯å€‹åƒæ•¸çš„æ述。 + +enabled +------- + +啓用或ç¦ç”¨DAMON_RECLAIM。 + +ä½ å¯ä»¥é€šéŽæŠŠé€™å€‹åƒæ•¸çš„值è¨ç½®çˆ² ``Y`` 來啓用DAMON_RCLAIM，把它è¨ç½®çˆ² ``N`` å¯ä»¥ç¦ç”¨ +DAMON_RECLAIM。注æ„，由於基於水ä½çš„激活æ¢ä»¶ï¼ŒDAMON_RECLAIMä¸èƒ½é€²è¡ŒçœŸæ£çš„監測和回收。 +這一點請åƒè€ƒä¸‹é¢é—œæ–¼æ°´ä½åƒæ•¸çš„æ述。 + +min_age +------- + +è˜åˆ¥å†·å…§å˜å€åŸŸçš„時間閾值，單ä½æ˜¯å¾®ç§’。 + +如果一個內å˜å€åŸŸåœ¨é€™å€‹æ™‚間或更長的時間內沒有被訪å•ï¼ŒDAMON_RECLAIM會將該å€åŸŸè˜åˆ¥çˆ²å†·çš„， +並回收它。 + +默èªçˆ²120秒。 + +quota_ms +-------- + +回收的時間é™åˆ¶ï¼Œä»¥æ¯«ç§’爲單ä½ã€‚ + +DAMON_RECLAIM 試圖在一個時間窗å£ï¼ˆquota_reset_interval_ms）內åªä½¿ç”¨åˆ°é€™å€‹æ™‚間，以 +嘗試回收冷é 。這å¯ä»¥ç”¨ä¾†é™åˆ¶DAMON_RECLAIMçš„CPU消耗。如果該值爲零，則該é™åˆ¶è¢«ç¦ç”¨ã€‚ + +默èªçˆ²10ms。 + +quota_sz +-------- + +回收的內å˜å¤§å°é™åˆ¶ï¼Œå–®ä½çˆ²å—節。 + +DAMON_RECLAIM 收å–在一個時間窗å£ï¼ˆquota_reset_interval_ms）內試圖回收的內å˜é‡ï¼Œä¸¦ +使其ä¸è¶…éŽé€™å€‹é™åˆ¶ã€‚這å¯ä»¥ç”¨ä¾†é™åˆ¶CPUå’ŒIO的消耗。如果該值爲零，則é™åˆ¶è¢«ç¦ç”¨ã€‚ + +默èªæƒ…æ³ä¸‹æ˜¯128 MiB。 + +quota_reset_interval_ms +----------------------- + +時間/大å°é…é¡æ”¶å–é‡ç½®é–“隔，單ä½çˆ²æ¯«ç§’。 + +時間（quota_ms）和大å°ï¼ˆquota_sz）的é…é¡çš„目標é‡ç½®é–“隔。也就是說，DAMON_RECLAIM在 +嘗試回收‘ä¸â€™è¶…éŽquota_ms毫秒或quota_szå—節的內å˜ã€‚ + +默èªçˆ²1秒。 + +wmarks_interval +--------------- + +當DAMON_RECLAIM被啓用但由於其水ä½è¦å‰‡è€Œä¸æ´»èºæ™‚，在檢查水ä½ä¹‹å‰çš„最å°ç‰å¾…時間。 + +wmarks_high +----------- + +高水ä½çš„å¯ç”¨å…§å˜çŽ‡ï¼ˆæ¯åƒå—節）。 + +如果系統的å¯ç”¨å…§å˜ï¼ˆä»¥æ¯åƒå—節爲單ä½ï¼‰é«˜æ–¼é€™å€‹æ•¸å€¼ï¼ŒDAMON_RECLAIM就會變得ä¸æ´»èºï¼Œæ‰€ä»¥ +它什麼也ä¸åšï¼Œåªæ˜¯å®šæœŸæª¢æŸ¥æ°´ä½ã€‚ + +wmarks_mid +---------- + +ä¸é–“æ°´ä½çš„å¯ç”¨å…§å˜çŽ‡ï¼ˆæ¯åƒå—節）。 + +如果系統的空閒內å˜ï¼ˆä»¥æ¯åƒå—節爲單ä½ï¼‰åœ¨é€™å€‹å’Œä½Žæ°´ä½ç·šä¹‹é–“，DAMON_RECLAIM就會被激活， +å› æ¤é–‹å§‹ç›£æ¸¬å’Œå›žæ”¶ã€‚ + +wmarks_low +---------- + +低水ä½çš„å¯ç”¨å…§å˜çŽ‡ï¼ˆæ¯åƒå—節）。 + +如果系統的空閒內å˜ï¼ˆä»¥æ¯åƒå—節爲單ä½ï¼‰ä½Žæ–¼é€™å€‹æ•¸å€¼ï¼ŒDAMON_RECLAIM就會變得ä¸æ´»èºï¼Œæ‰€ä»¥ +它除了定期檢查水ä½å¤–什麼都ä¸åšã€‚在這種情æ³ä¸‹ï¼Œç³»çµ±æœƒé€€å›žåˆ°åŸºæ–¼LRU列表的é é¢ç²’度回收é‚輯。 + +sample_interval +--------------- + +監測的採樣間隔，單ä½æ˜¯å¾®ç§’。 + +DAMON用於監測冷內å˜çš„採樣間隔。更多細節請åƒè€ƒDAMON文檔 (:doc:`usage`) 。 + +aggr_interval +------------- + +監測的èšé›†é–“隔，單ä½æ˜¯å¾®ç§’。 + +DAMONå°å†·å…§å˜ç›£æ¸¬çš„èšé›†é–“隔。更多細節請åƒè€ƒDAMON文檔 (:doc:`usage`)。 + +min_nr_regions +-------------- + +監測å€åŸŸçš„最å°æ•¸é‡ã€‚ + +DAMON用於冷內å˜ç›£æ¸¬çš„最å°ç›£æ¸¬å€åŸŸæ•¸ã€‚這å¯ä»¥ç”¨ä¾†è¨ç½®ç›£æ¸¬è³ªé‡çš„下é™ã€‚ä½†æ˜¯ï¼Œè¨ +置的太高å¯èƒ½æœƒå°Žè‡´ç›£æ¸¬é–‹éŠ·çš„å¢žåŠ ã€‚æ›´å¤šç´°ç¯€è«‹åƒè€ƒDAMON文檔 (:doc:`usage`) 。 + +max_nr_regions +-------------- + +監測å€åŸŸçš„最大數é‡ã€‚ + +DAMON用於冷內å˜ç›£æ¸¬çš„最大監測å€åŸŸæ•¸ã€‚這å¯ä»¥ç”¨ä¾†è¨ç½®ç›£æ¸¬é–‹éŠ·çš„上é™å€¼ã€‚但是， +è¨ç½®å¾—太低å¯èƒ½æœƒå°Žè‡´ç›£æ¸¬è³ªé‡ä¸å¥½ã€‚更多細節請åƒè€ƒDAMON文檔 (:doc:`usage`) 。 + +monitor_region_start +-------------------- + +目標內å˜å€åŸŸçš„物ç†åœ°å€èµ·é»žã€‚ + +DAMON_RECLAIMå°‡å°å…¶é€²è¡Œå·¥ä½œçš„å…§å˜å€åŸŸçš„起始物ç†åœ°å€ã€‚也就是說，DAMON_RECLAIM +將在這個å€åŸŸä¸æ‰¾åˆ°å†·çš„å…§å˜å€åŸŸä¸¦é€²è¡Œå›žæ”¶ã€‚默èªæƒ…æ³ä¸‹ï¼Œè©²å€åŸŸä½¿ç”¨æœ€å¤§ç³»çµ±å…§å˜å€ã€‚ + +monitor_region_end +------------------ + +目標內å˜å€åŸŸçš„çµæŸç‰©ç†åœ°å€ã€‚ + +DAMON_RECLAIMå°‡å°å…¶é€²è¡Œå·¥ä½œçš„å…§å˜å€åŸŸçš„末端物ç†åœ°å€ã€‚也就是說，DAMON_RECLAIMå°‡ +在這個å€åŸŸå…§æ‰¾åˆ°å†·çš„å…§å˜å€åŸŸä¸¦é€²è¡Œå›žæ”¶ã€‚默èªæƒ…æ³ä¸‹ï¼Œè©²å€åŸŸä½¿ç”¨æœ€å¤§ç³»çµ±å…§å˜å€ã€‚ + +kdamond_pid +----------- + +DAMON線程的PID。 + +如果DAMON_RECLAIM被啓用，這將æˆçˆ²å·¥ä½œç·šç¨‹çš„PID。å¦å‰‡ï¼Œçˆ²-1。 + +nr_reclaim_tried_regions +------------------------ + +試圖通éŽDAMON_RECLAIM回收的內å˜å€åŸŸçš„數é‡ã€‚ + +bytes_reclaim_tried_regions +--------------------------- + +試圖通éŽDAMON_RECLAIM回收的內å˜å€åŸŸçš„總å—節數。 + +nr_reclaimed_regions +-------------------- + +通éŽDAMON_RECLAIMæˆåŠŸå›žæ”¶çš„å…§å˜å€åŸŸçš„數é‡ã€‚ + +bytes_reclaimed_regions +----------------------- + +通éŽDAMON_RECLAIMæˆåŠŸå›žæ”¶çš„å…§å˜å€åŸŸçš„總å—節數。 + +nr_quota_exceeds +---------------- + +超éŽæ™‚é–“/空間é…é¡é™åˆ¶çš„次數。 + +例å +==== + +下é¢çš„é‹è¡Œç¤ºä¾‹å‘½ä»¤ä½¿DAMON_RECLAIM找到30秒或更長時間沒有訪å•çš„å…§å˜å€åŸŸä¸¦â€œå›žæ”¶â€ï¼Ÿ +爲了é¿å…DAMON_RECLAIM在分é æ“作ä¸æ¶ˆè€—éŽå¤šçš„CPU時間，回收被é™åˆ¶åœ¨æ¯ç§’1GiB以內。 +它還è¦æ±‚DAMON_RECLAIM在系統的å¯ç”¨å…§å˜çŽ‡è¶…éŽ50%時ä¸åšä»»ä½•äº‹æƒ…，但如果它低於40%時 +就開始真æ£çš„工作。如果DAMON_RECLAIM沒有å–å¾—é€²å±•ï¼Œå› æ¤ç©ºé–’å…§å˜çŽ‡ä½Žæ–¼20%，它會è¦æ±‚ +DAMON_RECLAIMå†æ¬¡ä»€éº¼éƒ½ä¸åšï¼Œé€™æ¨£æˆ‘們就å¯ä»¥é€€å›žåˆ°åŸºæ–¼LRU列表的é é¢ç²’度回收了:: + + # cd /sys/module/damon_reclaim/parameters + # echo 30000000 > min_age + # echo $((1 * 1024 * 1024 * 1024)) > quota_sz + # echo 1000 > quota_reset_interval_ms + # echo 500 > wmarks_high + # echo 400 > wmarks_mid + # echo 200 > wmarks_low + # echo Y > enabled + +.. [1] https://research.google/pubs/pub48551/ +.. [2] https://lwn.net/Articles/787611/ +.. [3] https://www.kernel.org/doc/html/latest/mm/free_page_reporting.html + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/start.rst new file mode 100644 index 000000000000..1822956be0e0 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/start.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/start.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯: + +======== +å…¥é–€æŒ‡å— +======== + +本文通éŽæ¼”示DAMON的默èªç”¨æˆ¶ç©ºé–“工具，簡è¦åœ°ä»‹ç´¹çžå¦‚何使用DAMON。請注æ„，爲了簡潔 +起見，本文檔åªæ述了它的部分功能。更多細節請åƒè€ƒè©²å·¥å…·çš„使用文檔。 +`doc <https://github.com/awslabs/damo/blob/next/USAGE.md>`_ . + + +å‰ææ¢ä»¶ +======== + +å…§æ ¸ +---- + +é¦–å…ˆï¼Œä½ è¦ç¢ºä¿ä½ 當å‰ç³»çµ±ä¸è·‘çš„å…§æ ¸æ§‹å»ºæ™‚é¸å®šäº†é€™å€‹åŠŸèƒ½é¸é … ``CONFIG_DAMON_*=y``. + + +用戶空間工具 +------------ + +在演示ä¸ï¼Œæˆ‘們將使用DAMON的默èªç”¨æˆ¶ç©ºé–“工具，稱爲DAMON Operator（DAMO）。它å¯ä»¥åœ¨ +https://github.com/awslabs/damo找到。下é¢çš„例åå‡è¨DAMOåœ¨ä½ çš„$PATH上。當然，但 +這並ä¸æ˜¯å¼·åˆ¶æ€§çš„。 + +å› çˆ²DAMO使用了DAMONçš„sysfs接å£ï¼ˆè©³æƒ…è«‹åƒè€ƒ:doc:`usage`ï¼‰ï¼Œä½ æ‡‰è©²ç¢ºä¿ +:doc:`sysfs </filesystems/sysfs>` 被掛載。 + +記錄數據訪å•æ¨¡å¼ +================ + +下é¢çš„命令記錄了一個程åºçš„å…§å˜è¨ªå•æ¨¡å¼ï¼Œä¸¦å°‡ç›£æ¸¬çµæžœä¿å˜åˆ°æ–‡ä»¶ä¸ã€‚ :: + + $ git clone https://github.com/sjp38/masim + $ cd masim; make; ./masim ./configs/zigzag.cfg & + $ sudo damo record -o damon.data $(pidof masim) + +命令的å‰å…©è¡Œä¸‹è¼‰äº†ä¸€å€‹äººå·¥å…§å˜è¨ªå•ç”Ÿæˆå™¨ç¨‹åºä¸¦åœ¨å¾Œè‡ºé‹è¡Œã€‚生æˆå™¨å°‡é‡è¤‡åœ°é€ä¸€è¨ªå•å…©å€‹ +100 MiB大å°çš„å…§å˜å€åŸŸã€‚ä½ å¯ä»¥ç”¨ä½ çš„çœŸå¯¦å·¥ä½œè² è¼‰ä¾†ä»£æ›¿å®ƒã€‚æœ€å¾Œä¸€è¡Œè¦æ±‚ ``damo`` å°‡ +訪å•æ¨¡å¼è¨˜éŒ„在 ``damon.data`` 文件ä¸ã€‚ + + +將記錄的模å¼å¯è¦–化 +================== + +ä½ å¯ä»¥åœ¨heatmapä¸ç›´è§€åœ°çœ‹åˆ°é€™ç¨®æ¨¡å¼ï¼Œé¡¯ç¤ºå“ªå€‹å…§å˜å€åŸŸï¼ˆX軸）何時被訪å•ï¼ˆY軸）以åŠè¨ª +å•çš„é »çŽ‡ï¼ˆæ•¸å—）。:: + + $ sudo damo report heats --heatmap stdout + 22222222222222222222222222222222222222211111111111111111111111111111111111111100 + 44444444444444444444444444444444444444434444444444444444444444444444444444443200 + 44444444444444444444444444444444444444433444444444444444444444444444444444444200 + 33333333333333333333333333333333333333344555555555555555555555555555555555555200 + 33333333333333333333333333333333333344444444444444444444444444444444444444444200 + 22222222222222222222222222222222222223355555555555555555555555555555555555555200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 33333333333333333333333333333333333333355555555555555555555555555555555555555200 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 33333333333333333333333333333333333333444444444444444444444444444444444444443200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + [...] + # access_frequency: 0 1 2 3 4 5 6 7 8 9 + # x-axis: space (139728247021568-139728453431248: 196.848 MiB) + # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) + # resolution: 80x40 (2.461 MiB and 1.758 s for each character) + +ä½ ä¹Ÿå¯ä»¥ç›´è§€åœ°çœ‹åˆ°å·¥ä½œé›†çš„大å°åˆ†ä½ˆï¼ŒæŒ‰å¤§å°æŽ’åºã€‚:: + + $ sudo damo report wss --range 0 101 10 + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 0 B | | + 10 95.328 MiB |**************************** | + 20 95.332 MiB |**************************** | + 30 95.340 MiB |**************************** | + 40 95.387 MiB |**************************** | + 50 95.387 MiB |**************************** | + 60 95.398 MiB |**************************** | + 70 95.398 MiB |**************************** | + 80 95.504 MiB |**************************** | + 90 190.703 MiB |********************************************************* | + 100 196.875 MiB |***********************************************************| + +在上述命令ä¸ä½¿ç”¨ ``--sortby`` é¸é …，å¯ä»¥é¡¯ç¤ºå·¥ä½œé›†çš„大å°æ˜¯å¦‚ä½•æŒ‰æ™‚é–“é †åºè®ŠåŒ–的。:: + + $ sudo damo report wss --range 0 101 10 --sortby time + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 3.051 MiB | | + 10 190.703 MiB |***********************************************************| + 20 95.336 MiB |***************************** | + 30 95.328 MiB |***************************** | + 40 95.387 MiB |***************************** | + 50 95.332 MiB |***************************** | + 60 95.320 MiB |***************************** | + 70 95.398 MiB |***************************** | + 80 95.398 MiB |***************************** | + 90 95.340 MiB |***************************** | + 100 95.398 MiB |***************************** | + + +數據訪å•æ¨¡å¼æ„ŸçŸ¥çš„å…§å˜ç®¡ç† +========================== + +以下三個命令使æ¯ä¸€å€‹å¤§å°>=4Kçš„å…§å˜å€åŸŸåœ¨ä½ çš„å·¥ä½œè² è¼‰ä¸æ²’有被訪å•>=60秒，就會被æ›æŽ‰ã€‚ :: + + $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme + $ echo "4K max 0 0 60s max pageout" >> test_scheme + $ damo schemes -c test_scheme <pid of your workload> + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst new file mode 100644 index 000000000000..6dee719a32ea --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst @@ -0,0 +1,592 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/damon/usage.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯: + +======== +詳細用法 +======== + +DAMON 爲ä¸åŒçš„用戶æ供了下é¢é€™äº›æŽ¥å£ã€‚ + +- *DAMON用戶空間工具。* + `這 <https://github.com/awslabs/damo>`_ 爲有這特權的人， 如系統管ç†å“¡ï¼Œå¸Œæœ›æœ‰ä¸€å€‹å‰›å¥½ + å¯ä»¥å·¥ä½œçš„人性化界é¢ã€‚ + 使用它，用戶å¯ä»¥ä»¥äººæ€§åŒ–çš„æ–¹å¼ä½¿ç”¨DAMON的主è¦åŠŸèƒ½ã€‚ä¸éŽï¼Œå®ƒå¯èƒ½ä¸æœƒçˆ²ç‰¹æ®Šæƒ…æ³é€²è¡Œé«˜åº¦èª¿æ•´ã€‚ + 它åŒæ™‚支æŒè™›æ“¬å’Œç‰©ç†åœ°å€ç©ºé–“的監測。更多細節，請åƒè€ƒå®ƒçš„ `使用文檔 + <https://github.com/awslabs/damo/blob/next/USAGE.md>`_。 +- *sysfs接å£ã€‚* + :ref:`這 <sysfs_interface>` 是爲那些希望更高級的使用DAMON的特權用戶空間程åºå“¡æº–備的。 + 使用它，用戶å¯ä»¥é€šéŽè®€å–和寫入特殊的sysfs文件來使用DAMON的主è¦åŠŸèƒ½ã€‚å› æ¤ï¼Œä½ å¯ä»¥ç·¨å¯«å’Œä½¿ + ç”¨ä½ å€‹æ€§åŒ–çš„DAMON sysfs包è£ç¨‹åºï¼Œä»£æ›¿ä½ 讀/寫sysfs文件。 `DAMON用戶空間工具 + <https://github.com/awslabs/damo>`_ 就是這種程åºçš„一個例å 它åŒæ™‚支æŒè™›æ“¬å’Œç‰©ç†åœ°å€ + 空間的監測。注æ„，這個界é¢åªæ供簡單的監測çµæžœ :ref:`統計 <damos_stats>`。å°æ–¼è©³ç´°çš„監測 + çµæžœï¼ŒDAMONæ供了一個:ref:`跟蹤點 <tracepoint>`。 +- *debugfs interface.* + :ref:`這 <debugfs_interface>` 幾乎與:ref:`sysfs interface <sysfs_interface>` 接 + å£ç›¸åŒã€‚這將在下一個LTSå…§æ ¸ç™¼ä½ˆå¾Œè¢«ç§»é™¤ï¼Œæ‰€ä»¥ç”¨æˆ¶æ‡‰è©²è½‰ç§»åˆ° + :ref:`sysfs interface <sysfs_interface>`。 +- *å…§æ ¸ç©ºé–“ç·¨ç¨‹æŽ¥å£ã€‚* + :doc:`這 </mm/damon/api>` é€™æ˜¯çˆ²å…§æ ¸ç©ºé–“ç¨‹åºå“¡æº–備的。使用它，用戶å¯ä»¥é€šéŽçˆ²ä½ 編寫內 + æ ¸ç©ºé–“çš„DAMON應用程åºï¼Œæœ€éˆæ´»æœ‰æ•ˆåœ°åˆ©ç”¨DAMONçš„æ¯ä¸€å€‹åŠŸèƒ½ã€‚ä½ ç”šè‡³å¯ä»¥çˆ²å„種地å€ç©ºé–“擴展DAMON。 + 詳細情æ³è«‹åƒè€ƒæŽ¥å£ :doc:`文件 </mm/damon/api>`。 + +sysfsæŽ¥å£ +========= +DAMONçš„sysfs接å£æ˜¯åœ¨å®šç¾© ``CONFIG_DAMON_SYSFS`` 時建立的。它在其sysfs目錄下創建多 +個目錄和文件， ``<sysfs>/kernel/mm/damon/`` ã€‚ä½ å¯ä»¥é€šéŽå°è©²ç›®éŒ„下的文件進行寫入和 +讀å–來控制DAMON。 + +å°æ–¼ä¸€å€‹ç°¡çŸçš„例å，用戶å¯ä»¥ç›£æ¸¬ä¸€å€‹çµ¦å®šå·¥ä½œè² 載的虛擬地å€ç©ºé–“，如下所示:: + + # cd /sys/kernel/mm/damon/admin/ + # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts + # echo vaddr > kdamonds/0/contexts/0/operations + # echo 1 > kdamonds/0/contexts/0/targets/nr_targets + # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target + # echo on > kdamonds/0/state + +文件層次çµæ§‹ +------------ + +DAMON sysfs接å£çš„文件層次çµæ§‹å¦‚下圖所示。在下圖ä¸ï¼Œçˆ¶å關係用縮進表示，æ¯å€‹ç›®éŒ„有 +``/`` 後綴，æ¯å€‹ç›®éŒ„ä¸çš„文件用逗號（","）分開。 :: + + /sys/kernel/mm/damon/admin + │ kdamonds/nr_kdamonds + │ │ 0/state,pid + │ │ │ contexts/nr_contexts + │ │ │ │ 0/operations + │ │ │ │ │ monitoring_attrs/ + │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us + │ │ │ │ │ │ nr_regions/min,max + │ │ │ │ │ targets/nr_targets + │ │ │ │ │ │ 0/pid_target + │ │ │ │ │ │ │ regions/nr_regions + │ │ │ │ │ │ │ │ 0/start,end + │ │ │ │ │ │ │ │ ... + │ │ │ │ │ │ ... + │ │ │ │ │ schemes/nr_schemes + │ │ │ │ │ │ 0/action + │ │ │ │ │ │ │ access_pattern/ + │ │ │ │ │ │ │ │ sz/min,max + │ │ │ │ │ │ │ │ nr_accesses/min,max + │ │ │ │ │ │ │ │ age/min,max + │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil + │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ │ tried_regions/ + │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age + │ │ │ │ │ │ │ │ ... + │ │ │ │ │ │ ... + │ │ │ │ ... + │ │ ... + +æ ¹ +-- + +DAMON sysfs接å£çš„æ ¹æ˜¯ ``<sysfs>/kernel/mm/damon/`` ，它有一個å爲 ``admin`` çš„ +目錄。該目錄包å«ç‰¹æ¬Šç”¨æˆ¶ç©ºé–“程åºæŽ§åˆ¶DAMON的文件。æ“æœ‰æ ¹æ¬Šé™çš„用戶空間工具或deamonså¯ä»¥ +使用這個目錄。 + +kdamonds/ +--------- + +與監測相關的信æ¯åŒ…括請求è¦æ ¼å’Œçµæžœè¢«ç¨±çˆ²DAMON上下文。DAMON用一個å«åškdamondçš„å…§æ ¸ç·šç¨‹ +執行æ¯å€‹ä¸Šä¸‹æ–‡ï¼Œå¤šå€‹kdamondså¯ä»¥ä¸¦è¡Œé‹è¡Œã€‚ + +在 ``admin`` 目錄下，有一個目錄，å³``kdamonds``，它有控制kdamonds的文件å˜åœ¨ã€‚在開始 +時，這個目錄åªæœ‰ä¸€å€‹æ–‡ä»¶ï¼Œ``nr_kdamonds``。å‘該文件寫入一個數å—（``N``），就會創建å爲 +``0`` 到 ``N-1`` çš„å目錄數é‡ã€‚æ¯å€‹ç›®éŒ„代表æ¯å€‹kdamond。 + +kdamonds/<N>/ +------------- + +在æ¯å€‹kdamond目錄ä¸ï¼Œå˜åœ¨å…©å€‹æ–‡ä»¶ï¼ˆ``state`` å’Œ ``pid`` ）和一個目錄( ``contexts`` )。 + +è®€å– ``state`` 時，如果kdamond當å‰æ£åœ¨é‹è¡Œï¼Œå‰‡è¿”回 ``on`` ，如果沒有é‹è¡Œå‰‡è¿”回 ``off`` 。 +寫入 ``on`` 或 ``off`` 使kdamondè™•æ–¼ç‹€æ…‹ã€‚å‘ ``state`` 文件寫 ``update_schemes_stats`` ， +æ›´æ–°kdamondçš„æ¯å€‹åŸºæ–¼DAMONçš„æ“作方案的統計文件的內容。關於統計信æ¯çš„細節，請åƒè€ƒ +:ref:`stats section <sysfs_schemes_stats>`. å°‡ ``update_schemes_tried_regions`` 寫到 +``state`` 文件，爲kdamondçš„æ¯å€‹åŸºæ–¼DAMONçš„æ“作方案，更新基於DAMONçš„æ“作方案動作的嘗試å€åŸŸç›®éŒ„。 +å°‡`clear_schemes_tried_regions`寫入`state`文件，清除kdamondçš„æ¯å€‹åŸºæ–¼DAMONçš„æ“作方案的動作 +嘗試å€åŸŸç›®éŒ„。 關於基於DAMONçš„æ“作方案動作嘗試å€åŸŸç›®éŒ„的細節，請åƒè€ƒ:ref:tried_regions 部分 +<sysfs_schemes_tried_regions>`。 + +如果狀態爲 ``on``ï¼Œè®€å– ``pid`` 顯示kdamond線程的pid。 + +``contexts`` 目錄包å«æŽ§åˆ¶é€™å€‹kdamondè¦åŸ·è¡Œçš„監測上下文的文件。 + +kdamonds/<N>/contexts/ +---------------------- + +在開始時，這個目錄åªæœ‰ä¸€å€‹æ–‡ä»¶ï¼Œå³ ``nr_contexts`` 。å‘該文件寫入一個數å—( ``N`` )，就會創 +建å爲``0`` 到 ``N-1`` çš„å目錄數é‡ã€‚æ¯å€‹ç›®éŒ„代表æ¯å€‹ç›£æ¸¬èƒŒæ™¯ã€‚ç›®å‰ï¼Œæ¯å€‹kdamondåªæ”¯æŒ +一個上下文，所以åªæœ‰ ``0`` 或 ``1`` å¯ä»¥è¢«å¯«å…¥æ–‡ä»¶ã€‚ + +contexts/<N>/ +------------- + +在æ¯å€‹ä¸Šä¸‹æ–‡ç›®éŒ„ä¸ï¼Œå˜åœ¨ä¸€å€‹æ–‡ä»¶(``operations``)和三個目錄(``monitoring_attrs``, +``targets``, å’Œ ``schemes``)。 + +DAMON支æŒå¤šç¨®é¡žåž‹çš„監測æ“作，包括å°è™›æ“¬åœ°å€ç©ºé–“和物ç†åœ°å€ç©ºé–“çš„ç›£æ¸¬ã€‚ä½ å¯ä»¥é€šéŽå‘文件 +ä¸å¯«å…¥ä»¥ä¸‹é—œéµè©žä¹‹ä¸€ï¼Œä¸¦å¾žæ–‡ä»¶ä¸è®€å–，來è¨ç½®å’Œç²å–DAMON將爲上下文使用何種類型的監測æ“作。 + + - vaddr: 監測特定進程的虛擬地å€ç©ºé–“ + - paddr: 監視系統的物ç†åœ°å€ç©ºé–“ + +contexts/<N>/monitoring_attrs/ +------------------------------ + +用於指定監測屬性的文件，包括所需的監測質é‡å’Œæ•ˆçŽ‡ï¼Œéƒ½åœ¨ ``monitoring_attrs`` 目錄ä¸ã€‚ +å…·é«”ä¾†èªªï¼Œé€™å€‹ç›®éŒ„ä¸‹æœ‰å…©å€‹ç›®éŒ„ï¼Œå³ ``intervals`` å’Œ ``nr_regions`` 。 + +在 ``intervals`` 目錄下，å˜åœ¨DAMON的採樣間隔(``sample_us``)ã€èšé›†é–“éš”(``aggr_us``) +和更新間隔(``update_us``)ä¸‰å€‹æ–‡ä»¶ã€‚ä½ å¯ä»¥é€šéŽå¯«å…¥å’Œè®€å‡ºé€™äº›æ–‡ä»¶ä¾†è¨ç½®å’Œç²å–微秒級的值。 + +在 ``nr_regions`` 目錄下，有兩個文件分別用於DAMON監測å€åŸŸçš„下é™å’Œä¸Šé™ï¼ˆ``min`` å’Œ ``max`` ）， +這兩個文件控制ç€ç›£æ¸¬çš„é–‹éŠ·ã€‚ä½ å¯ä»¥é€šéŽå‘這些文件的寫入和讀出來è¨ç½®å’Œç²å–這些值。 + +關於間隔和監測å€åŸŸç¯„åœçš„更多細節，請åƒè€ƒè¨è¨ˆæ–‡ä»¶ (:doc:`/mm/damon/design`)。 + +contexts/<N>/targets/ +--------------------- + +在開始時，這個目錄åªæœ‰ä¸€å€‹æ–‡ä»¶ ``nr_targets`` 。å‘該文件寫入一個數å—(``N``)，就å¯ä»¥å‰µå»º +å爲 ``0`` 到 ``N-1`` çš„å目錄的數é‡ã€‚æ¯å€‹ç›®éŒ„代表æ¯å€‹ç›£æ¸¬ç›®æ¨™ã€‚ + +targets/<N>/ +------------ + +在æ¯å€‹ç›®æ¨™ç›®éŒ„ä¸ï¼Œå˜åœ¨ä¸€å€‹æ–‡ä»¶(``pid_target``)和一個目錄(``regions``)。 + +å¦‚æžœä½ æŠŠ ``vaddr`` 寫到 ``contexts/<N>/operations`` ä¸ï¼Œæ¯å€‹ç›®æ¨™æ‡‰è©²æ˜¯ä¸€å€‹é€²ç¨‹ã€‚ä½ +å¯ä»¥é€šéŽå°‡é€²ç¨‹çš„pid寫到 ``pid_target`` 文件ä¸ä¾†æŒ‡å®šDAMON的進程。 + +targets/<N>/regions +------------------- + +當使用 ``vaddr`` 監測æ“作集時（ ``vaddr`` 被寫入 ``contexts/<N>/operations`` æ–‡ +件），DAMON自動è¨ç½®å’Œæ›´æ–°ç›£æ¸¬ç›®æ¨™å€åŸŸï¼Œé€™æ¨£å°±å¯ä»¥è¦†è“‹ç›®æ¨™é€²ç¨‹çš„整個內å˜æ˜ å°„ã€‚ç„¶è€Œï¼Œç”¨æˆ¶å¯ +能希望將åˆå§‹ç›£æ¸¬å€åŸŸè¨ç½®çˆ²ç‰¹å®šçš„地å€ç¯„åœã€‚ + +相å，當使用 ``paddr`` 監測æ“作集時，DAMONä¸æœƒè‡ªå‹•è¨ç½®å’Œæ›´æ–°ç›£æ¸¬ç›®æ¨™å€åŸŸï¼ˆ ``paddr`` +被寫入 ``contexts/<N>/operations`` ä¸ï¼‰ã€‚å› æ¤ï¼Œåœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œç”¨æˆ¶æ‡‰è©²è‡ªå·±è¨ç½®ç›£æ¸¬ç›®æ¨™ +å€åŸŸã€‚ + +在這種情æ³ä¸‹ï¼Œç”¨æˆ¶å¯ä»¥æŒ‰ç…§è‡ªå·±çš„æ„願明確è¨ç½®åˆå§‹ç›£æ¸¬ç›®æ¨™å€åŸŸï¼Œå°‡é©ç•¶çš„值寫入該目錄下的文件。 + +開始時，這個目錄åªæœ‰ä¸€å€‹æ–‡ä»¶ï¼Œ ``nr_regions`` 。å‘該文件寫入一個數å—(``N``)，就å¯ä»¥å‰µ +建å爲 ``0`` 到 ``N-1`` çš„å目錄。æ¯å€‹ç›®éŒ„代表æ¯å€‹åˆå§‹ç›£æ¸¬ç›®æ¨™å€åŸŸã€‚ + +regions/<N>/ +------------ + +在æ¯å€‹å€åŸŸç›®éŒ„ä¸ï¼Œä½ 會發ç¾å…©å€‹æ–‡ä»¶ï¼ˆ ``start`` å’Œ ``end`` ï¼‰ã€‚ä½ å¯ä»¥é€šéŽå‘文件寫入 +和從文件ä¸è®€å‡ºï¼Œåˆ†åˆ¥è¨ç½®å’Œç²å¾—åˆå§‹ç›£æ¸¬ç›®æ¨™å€åŸŸçš„起始和çµæŸåœ°å€ã€‚ + +æ¯å€‹å€åŸŸä¸æ‡‰è©²èˆ‡å…¶ä»–å€åŸŸé‡ç–Šã€‚ 目錄“Nâ€çš„“çµæŸâ€æ‡‰ç‰æ–¼æˆ–å°æ–¼ç›®éŒ„“N+1â€çš„“開始â€ã€‚ + +contexts/<N>/schemes/ +--------------------- + +å°æ–¼ä¸€ç‰ˆçš„基於DAMON的數據訪å•æ„ŸçŸ¥çš„å…§å˜ç®¡ç†å„ªåŒ–，用戶通常希望系統å°ç‰¹å®šè¨ªå•æ¨¡å¼çš„å…§å˜å€ +域應用內å˜ç®¡ç†æ“作。DAMON從用戶那è£æŽ¥æ”¶é€™ç¨®å½¢å¼åŒ–çš„æ“ä½œæ–¹æ¡ˆï¼Œä¸¦å°‡é€™äº›æ–¹æ¡ˆæ‡‰ç”¨æ–¼ç›®æ¨™å…§å˜ +å€åŸŸã€‚用戶å¯ä»¥é€šéŽè®€å–和寫入這個目錄下的文件來ç²å¾—å’Œè¨ç½®é€™äº›æ–¹æ¡ˆã€‚ + +在開始時，這個目錄åªæœ‰ä¸€å€‹æ–‡ä»¶ï¼Œ``nr_schemes``。å‘該文件寫入一個數å—(``N``)，就å¯ä»¥ +創建å爲``0``到``N-1``çš„å目錄的數é‡ã€‚æ¯å€‹ç›®éŒ„代表æ¯å€‹åŸºæ–¼DAMONçš„æ“作方案。 + +schemes/<N>/ +------------ + +在æ¯å€‹æ–¹æ¡ˆç›®éŒ„ä¸ï¼Œå˜åœ¨äº”個目錄(``access_pattern``ã€``quotas``ã€``watermarks``〠+``stats`` å’Œ ``tried_regions``)和一個文件(``action``)。 + +``action`` 文件用於è¨ç½®å’Œç²å–ä½ æƒ³æ‡‰ç”¨æ–¼å…·æœ‰ç‰¹å®šè¨ªå•æ¨¡å¼çš„å…§å˜å€åŸŸçš„動作。å¯ä»¥å¯«å…¥æ–‡ä»¶ +和從文件ä¸è®€å–çš„é—œéµè©žåŠå…¶å«ç¾©å¦‚下。 + + - ``willneed``: å°æœ‰ ``MADV_WILLNEED`` çš„å€åŸŸèª¿ç”¨ ``madvise()`` 。 + - ``cold``: å°å…·æœ‰ ``MADV_COLD`` çš„å€åŸŸèª¿ç”¨ ``madvise()`` 。 + - ``pageout``: 爲具有 ``MADV_PAGEOUT`` çš„å€åŸŸèª¿ç”¨ ``madvise()`` 。 + - ``hugepage``: 爲帶有 ``MADV_HUGEPAGE`` çš„å€åŸŸèª¿ç”¨ ``madvise()`` 。 + - ``nohugepage``: 爲帶有 ``MADV_NOHUGEPAGE`` çš„å€åŸŸèª¿ç”¨ ``madvise()``。 + - ``lru_prio``: 在其LRU列表上å°å€åŸŸé€²è¡Œå„ªå…ˆæŽ’åºã€‚ + - ``lru_deprio``: å°å€åŸŸçš„LRU列表進行é™ä½Žå„ªå…ˆè™•ç†ã€‚ + - ``stat``: 什麼都ä¸åšï¼Œåªè¨ˆç®—統計數據 + +schemes/<N>/access_pattern/ +--------------------------- + +æ¯å€‹åŸºæ–¼DAMONçš„æ“作方案的目標訪å•æ¨¡å¼ç”±ä¸‰å€‹ç¯„åœæ§‹æˆï¼ŒåŒ…括以å—節爲單ä½çš„å€åŸŸå¤§å°ã€æ¯å€‹ +èšåˆå€é–“的監測訪å•æ¬¡æ•¸å’Œå€åŸŸå¹´é½¡çš„èšåˆå€é–“數。 + +在 ``access_pattern`` 目錄下，å˜åœ¨ä¸‰å€‹ç›®éŒ„（ ``sz``, ``nr_accesses``, å’Œ ``age`` ）， +æ¯å€‹ç›®éŒ„有兩個文件（``min`` å’Œ ``max`` ï¼‰ã€‚ä½ å¯ä»¥é€šéŽå‘ ``sz``, ``nr_accesses``, å’Œ +``age`` 目錄下的 ``min`` å’Œ ``max`` 文件分別寫入和讀å–來è¨ç½®å’Œç²å–給定方案的訪å•æ¨¡å¼ã€‚ + +schemes/<N>/quotas/ +------------------- + +æ¯å€‹ ``動作`` 的最佳 ``目標訪å•æ¨¡å¼`` å–æ±ºæ–¼å·¥ä½œè² è¼‰ï¼Œæ‰€ä»¥ä¸å®¹æ˜“找到。更糟糕的是，將æŸäº›å‹•ä½œ +的方案è¨ç½®å¾—éŽæ–¼æ¿€é€²æœƒé€ æˆåš´é‡çš„開銷。爲了é¿å…這種開銷，用戶å¯ä»¥çˆ²æ¯å€‹æ–¹æ¡ˆé™åˆ¶æ™‚間和大å°é…é¡ã€‚ +具體來說，用戶å¯ä»¥è¦æ±‚DAMON儘é‡åªä½¿ç”¨ç‰¹å®šçš„時間（``時間é…é¡``）來應用動作，並且在給定的時間間 +隔（``é‡ç½®é–“éš”``）內，åªå°å…·æœ‰ç›®æ¨™è¨ªå•æ¨¡å¼çš„å…§å˜å€åŸŸæ‡‰ç”¨å‹•ä½œï¼Œè€Œä¸ä½¿ç”¨ç‰¹å®šæ•¸é‡ï¼ˆ``大å°é…é¡``）。 + +當é 計超éŽé…é¡é™åˆ¶æ™‚，DAMONæœƒæ ¹æ“š ``目標訪å•æ¨¡å¼`` 的大å°ã€è¨ªå•é »çŽ‡å’Œå¹´é½¡ï¼Œå°æ‰¾åˆ°çš„å…§å˜å€åŸŸ +進行優先排åºã€‚爲了進行個性化的優先排åºï¼Œç”¨æˆ¶å¯ä»¥çˆ²é€™ä¸‰å€‹å±¬æ€§è¨ç½®æ¬Šé‡ã€‚ + +在 ``quotas`` 目錄下，å˜åœ¨ä¸‰å€‹æ–‡ä»¶ï¼ˆ``ms``, ``bytes``, ``reset_interval_ms``）和一個 +目錄(``weights``)，其ä¸æœ‰ä¸‰å€‹æ–‡ä»¶(``sz_permil``, ``nr_accesses_permil``, å’Œ +``age_permil``)。 + +ä½ å¯ä»¥è¨ç½®ä»¥æ¯«ç§’爲單ä½çš„ ``時間é…é¡`` ，以å—節爲單ä½çš„ ``大å°é…é¡`` ，以åŠä»¥æ¯«ç§’爲單ä½çš„ ``é‡ +置間隔`` ，分別å‘é€™ä¸‰å€‹æ–‡ä»¶å¯«å…¥æ•¸å€¼ã€‚ä½ é‚„å¯ä»¥é€šéŽå‘ ``weights`` ç›®éŒ„ä¸‹çš„ä¸‰å€‹æ–‡ä»¶å¯«å…¥æ•¸å€¼ä¾†è¨ +置大å°ã€è¨ªå•é »çŽ‡å’Œå¹´é½¡çš„優先權，單ä½çˆ²åƒåˆ†ä¹‹ä¸€ã€‚ + +schemes/<N>/watermarks/ +----------------------- + +çˆ²äº†ä¾¿æ–¼æ ¹æ“šç³»çµ±ç‹€æ…‹æ¿€æ´»å’Œåœç”¨æ¯å€‹æ–¹æ¡ˆï¼ŒDAMONæ供了一個稱爲水ä½çš„功能。該功能接收五個值，稱爲 +``度é‡`` ã€``é–“éš”`` ã€``高`` ã€``ä¸`` ã€``低`` 。``度é‡å€¼`` 是指å¯ä»¥æ¸¬é‡çš„系統度é‡å€¼ï¼Œå¦‚ +自由內å˜æ¯”率。如果系統的度é‡å€¼ ``高`` æ–¼memoent的高值或 ``低`` 於低值，則該方案被åœç”¨ã€‚如果 +該值低於 ``ä¸`` ，則該方案被激活。 + +在水ä½ç›®éŒ„下，å˜åœ¨äº”個文件(``metric``, ``interval_us``,``high``, ``mid``, and ``low``) +用於è¨ç½®æ¯å€‹å€¼ã€‚ä½ å¯ä»¥é€šéŽå‘這些文件的寫入來分別è¨ç½®å’Œç²å–這五個值。 + +å¯ä»¥å¯«å…¥ ``metric`` 文件的關éµè©žå’Œå«ç¾©å¦‚下。 + + - none: å¿½ç•¥æ°´ä½ + - free_mem_rate: 系統的自由內å˜çŽ‡ï¼ˆåƒåˆ†æ¯”）。 + +``interval`` 應以微秒爲單ä½å¯«å…¥ã€‚ + +schemes/<N>/stats/ +------------------ + +DAMON統計æ¯å€‹æ–¹æ¡ˆè¢«å˜—試應用的å€åŸŸçš„總數é‡å’Œå—節數，æ¯å€‹æ–¹æ¡ˆè¢«æˆåŠŸæ‡‰ç”¨çš„å€åŸŸçš„兩個數å—ï¼Œä»¥åŠ +超éŽé…é¡é™åˆ¶çš„總數é‡ã€‚這些統計數據å¯ç”¨æ–¼åœ¨ç·šåˆ†æžæˆ–調整方案。 + +å¯ä»¥é€šéŽè®€å– ``stats`` 目錄下的文件(``nr_tried``, ``sz_tried``, ``nr_applied``, +``sz_applied``, å’Œ ``qt_exceeds``)）分別檢索這些統計數據。這些文件ä¸æ˜¯å¯¦æ™‚更新的，所以 +ä½ æ‡‰è©²è¦æ±‚DAMON sysfs接å£é€šéŽåœ¨ç›¸é—œçš„ ``kdamonds/<N>/state`` 文件ä¸å¯«å…¥ä¸€å€‹ç‰¹æ®Šçš„é—œéµå— +``update_schemes_stats`` 來更新統計信æ¯çš„文件內容。 + +schemes/<N>/tried_regions/ +-------------------------- + +當一個特殊的關éµå— ``update_schemes_tried_regions`` 被寫入相關的 ``kdamonds/<N>/state`` +文件時，DAMON會在這個目錄下創建從 ``0`` 開始命å的整數目錄。æ¯å€‹ç›®éŒ„包å«çš„文件暴露了關於æ¯å€‹ +å…§å˜å€åŸŸçš„詳細信æ¯ï¼Œåœ¨ä¸‹ä¸€å€‹ :ref:`èšé›†å€é–“ <sysfs_monitoring_attrs>`，相應的方案的 ``動作`` +已經嘗試在這個目錄下應用。這些信æ¯åŒ…括地å€ç¯„åœã€``nr_accesses`` 以åŠå€åŸŸçš„ ``年齡`` 。 + +當å¦ä¸€å€‹ç‰¹æ®Šçš„é—œéµå— ``clear_schemes_tried_regions`` 被寫入相關的 ``kdamonds/<N>/state`` +文件時，這些目錄將被刪除。 + +tried_regions/<N>/ +------------------ + +在æ¯å€‹å€åŸŸç›®éŒ„ä¸ï¼Œä½ 會發ç¾å››å€‹æ–‡ä»¶(``start``, ``end``, ``nr_accesses``, and ``age``)。 +讀å–這些文件將顯示相應的基於DAMONçš„æ“作方案 ``動作`` 試圖應用的å€åŸŸçš„開始和çµæŸåœ°å€ã€``nr_accesses`` +å’Œ ``年齡`` 。 + +用例 +~~~~ + +下é¢çš„命令應用了一個方案：â€å¦‚果一個大å°çˆ²[4KiB, 8KiB]çš„å…§å˜å€åŸŸåœ¨[10, 20]çš„èšåˆæ™‚間間隔內 +顯示出æ¯ä¸€å€‹èšåˆæ™‚é–“é–“éš”[0, 5]的訪å•é‡ï¼Œè«‹åˆ†é 該å€åŸŸã€‚å°æ–¼åˆ†é ，æ¯ç§’最多隻能使用10msï¼Œè€Œä¸”æ¯ +秒分é ä¸èƒ½è¶…éŽ1GiB。在這一é™åˆ¶ä¸‹ï¼Œé¦–先分é 出具有較長年齡的內å˜å€åŸŸã€‚å¦å¤–，æ¯5秒é˜æª¢æŸ¥ä¸€æ¬¡ç³»çµ± +çš„å¯ç”¨å…§å˜çŽ‡ï¼Œç•¶å¯ç”¨å…§å˜çŽ‡ä½Žæ–¼50%時開始監測和分é ，但如果å¯ç”¨å…§å˜çŽ‡å¤§æ–¼60%，或低於30%ï¼Œå‰‡åœ +æ¢ç›£æ¸¬ã€‚“ :: + + # cd <sysfs>/kernel/mm/damon/admin + # # populate directories + # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts; + # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes + # cd kdamonds/0/contexts/0/schemes/0 + # # set the basic access pattern and the action + # echo 4096 > access_pattern/sz/min + # echo 8192 > access_pattern/sz/max + # echo 0 > access_pattern/nr_accesses/min + # echo 5 > access_pattern/nr_accesses/max + # echo 10 > access_pattern/age/min + # echo 20 > access_pattern/age/max + # echo pageout > action + # # set quotas + # echo 10 > quotas/ms + # echo $((1024*1024*1024)) > quotas/bytes + # echo 1000 > quotas/reset_interval_ms + # # set watermark + # echo free_mem_rate > watermarks/metric + # echo 5000000 > watermarks/interval_us + # echo 600 > watermarks/high + # echo 500 > watermarks/mid + # echo 300 > watermarks/low + +請注æ„，我們強烈建è°ä½¿ç”¨ç”¨æˆ¶ç©ºé–“的工具，如 `damo <https://github.com/awslabs/damo>`_ ， +而ä¸æ˜¯åƒä¸Šé¢é‚£æ¨£æ‰‹å‹•è®€å¯«æ–‡ä»¶ã€‚以上åªæ˜¯ä¸€å€‹ä¾‹å。 + +debugfsæŽ¥å£ +=========== + +.. note:: + + DAMON debugfs接å£å°‡åœ¨ä¸‹ä¸€å€‹LTSå…§æ ¸ç™¼ä½ˆå¾Œè¢«ç§»é™¤ï¼Œæ‰€ä»¥ç”¨æˆ¶æ‡‰è©²è½‰ç§»åˆ° + :ref:`sysfs接å£<sysfs_interface>`。 + +DAMON導出了八個文件, ``attrs``, ``target_ids``, ``init_regions``, +``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` å’Œ +``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. + + +屬性 +---- + +用戶å¯ä»¥é€šéŽè®€å–和寫入 ``attrs`` 文件ç²å¾—å’Œè¨ç½® ``採樣間隔`` 〠``èšé›†é–“éš”`` 〠``æ›´æ–°é–“éš”`` +以åŠç›£æ¸¬ç›®æ¨™å€åŸŸçš„最å°/最大數é‡ã€‚è¦è©³ç´°çžè§£ç›£æ¸¬å±¬æ€§ï¼Œè«‹åƒè€ƒ `:doc:/mm/damon/design` 。例如， +下é¢çš„命令將這些值è¨ç½®çˆ²5msã€100msã€1000msã€10å’Œ1000，然後å†æ¬¡æª¢æŸ¥:: + + # cd <debugfs>/damon + # echo 5000 100000 1000000 10 1000 > attrs + # cat attrs + 5000 100000 1000000 10 1000 + + +目標ID +------ + +一些類型的地å€ç©ºé–“支æŒå¤šå€‹ç›£æ¸¬ç›®æ¨™ã€‚例如，虛擬內å˜åœ°å€ç©ºé–“的監測å¯ä»¥æœ‰å¤šå€‹é€²ç¨‹ä½œçˆ²ç›£æ¸¬ç›®æ¨™ã€‚用戶 +å¯ä»¥é€šéŽå¯«å…¥ç›®æ¨™çš„相關id值來è¨ç½®ç›®æ¨™ï¼Œä¸¦é€šéŽè®€å– ``target_ids`` 文件來ç²å¾—當å‰ç›®æ¨™çš„id。在監 +測虛擬地å€ç©ºé–“的情æ³ä¸‹ï¼Œé€™äº›å€¼æ‡‰è©²æ˜¯ç›£æ¸¬ç›®æ¨™é€²ç¨‹çš„pid。例如，下é¢çš„命令將pid爲42å’Œ4242çš„é€²ç¨‹è¨ +爲監測目標，並å†æ¬¡æª¢æŸ¥:: + + # cd <debugfs>/damon + # echo 42 4242 > target_ids + # cat target_ids + 42 4242 + +用戶還å¯ä»¥é€šéŽåœ¨æ–‡ä»¶ä¸å¯«å…¥ä¸€å€‹ç‰¹æ®Šçš„é—œéµå— "paddr\n" 來監測系統的物ç†å…§å˜åœ°å€ç©ºé–“ã€‚å› çˆ²ç‰©ç†åœ° +å€ç©ºé–“監測ä¸æ”¯æŒå¤šå€‹ç›®æ¨™ï¼Œè®€å–文件會顯示一個å‡å€¼ï¼Œå³ ``42`` ，如下圖所示:: + + # cd <debugfs>/damon + # echo paddr > target_ids + # cat target_ids + 42 + +請注æ„，è¨ç½®ç›®æ¨™ID並ä¸å•“動監測。 + + +åˆå§‹ç›£æ¸¬ç›®æ¨™å€åŸŸ +---------------- + +在虛擬地å€ç©ºé–“監測的情æ³ä¸‹ï¼ŒDAMON自動è¨ç½®å’Œæ›´æ–°ç›£æ¸¬çš„目標å€åŸŸï¼Œé€™æ¨£å°±å¯ä»¥è¦†è“‹ç›®æ¨™é€²ç¨‹çš„整個 +å…§å˜æ˜ 射。然而，用戶å¯èƒ½å¸Œæœ›å°‡ç›£æ¸¬å€åŸŸé™åˆ¶åœ¨ç‰¹å®šçš„地å€ç¯„åœå…§ï¼Œå¦‚å †ã€æ£§æˆ–ç‰¹å®šçš„æ–‡ä»¶æ˜ å°„å€åŸŸã€‚ +或者，一些用戶å¯ä»¥çŸ¥é“ä»–å€‘å·¥ä½œè² è¼‰çš„åˆå§‹è¨ªå•æ¨¡å¼ï¼Œå› æ¤å¸Œæœ›çˆ²â€œè‡ªé©æ‡‰å€åŸŸèª¿æ•´â€è¨ç½®æœ€ä½³åˆå§‹å€åŸŸã€‚ + +相比之下，DAMON在物ç†å…§å˜ç›£æ¸¬çš„情æ³ä¸‹ä¸æœƒè‡ªå‹•è¨ç½®å’Œæ›´æ–°ç›£æ¸¬ç›®æ¨™å€åŸŸã€‚å› æ¤ï¼Œç”¨æˆ¶æ‡‰è©²è‡ªå·±è¨ç½® +監測目標å€åŸŸã€‚ + +在這種情æ³ä¸‹ï¼Œç”¨æˆ¶å¯ä»¥é€šéŽåœ¨ ``init_regions`` 文件ä¸å¯«å…¥é©ç•¶çš„值，明確地è¨ç½®ä»–們想è¦çš„åˆ +始監測目標å€åŸŸã€‚輸入應該是一個由三個整數組æˆçš„éšŠåˆ—ï¼Œç”¨ç©ºæ ¼éš”é–‹ï¼Œä»£è¡¨ä¸€å€‹å€åŸŸçš„å½¢å¼å¦‚下:: + + <target idx> <start address> <end address> + +目標idx應該是 ``target_ids`` 文件ä¸ç›®æ¨™çš„索引，從 ``0`` 開始，å€åŸŸæ‡‰è©²æŒ‰ç…§åœ°å€é †åºå‚³éžã€‚ +例如，下é¢çš„命令將è¨ç½®å¹¾å€‹åœ°å€ç¯„åœï¼Œ ``1-100`` å’Œ ``100-200`` 作爲pid 42çš„åˆå§‹ç›£æ¸¬ç›®æ¨™ +å€åŸŸï¼Œé€™æ˜¯ ``target_ids`` ä¸çš„第一個（索引 ``0`` ），å¦å¤–幾個地å€ç¯„åœï¼Œ ``20-40`` å’Œ +``50-100`` 作爲pid 4242的地å€ï¼Œé€™æ˜¯ ``target_ids`` ä¸çš„第二個（索引 ``1`` ）:: + + # cd <debugfs>/damon + # cat target_ids + 42 4242 + # echo "0 1 100 \ + 0 100 200 \ + 1 20 40 \ + 1 50 100" > init_regions + +請注æ„，這åªæ˜¯è¨ç½®äº†åˆå§‹çš„監測目標å€åŸŸã€‚在虛擬內å˜ç›£æ¸¬çš„情æ³ä¸‹ï¼ŒDAMON會在一個 ``æ›´æ–°é–“éš”`` +後自動更新å€åŸŸçš„é‚Šç•Œã€‚å› æ¤ï¼Œåœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œå¦‚果用戶ä¸å¸Œæœ›æ›´æ–°çš„話，應該把 ``æ›´æ–°é–“éš”`` è¨ +ç½®å¾—è¶³å¤ å¤§ã€‚ + + +方案 +---- + +å°æ–¼é€šå¸¸çš„基於DAMON的數據訪å•æ„ŸçŸ¥çš„å…§å˜ç®¡ç†å„ªåŒ–，用戶åªæ˜¯å¸Œæœ›ç³»çµ±å°ç‰¹å®šè¨ªå•æ¨¡å¼çš„å…§å˜å€åŸŸæ‡‰ç”¨å…§ +å˜ç®¡ç†æ“作。DAMON從用戶那è£æŽ¥æ”¶é€™ç¨®å½¢å¼åŒ–çš„æ“作方案，並將這些方案應用到目標進程ä¸ã€‚ + +用戶å¯ä»¥é€šéŽè®€å–和寫入 ``scheme`` debugfs文件來ç²å¾—å’Œè¨ç½®é€™äº›æ–¹æ¡ˆã€‚讀å–該文件還å¯ä»¥é¡¯ç¤ºæ¯å€‹ +方案的統計數據。在文件ä¸ï¼Œæ¯ä¸€å€‹æ–¹æ¡ˆéƒ½æ‡‰è©²åœ¨æ¯ä¸€è¡Œä¸ä»¥ä¸‹åˆ—å½¢å¼è¡¨ç¤ºå‡ºä¾†:: + + <target access pattern> <action> <quota> <watermarks> + +ä½ å¯ä»¥é€šéŽç°¡å–®åœ°åœ¨æ–‡ä»¶ä¸å¯«å…¥ä¸€å€‹ç©ºå—符串來ç¦ç”¨æ–¹æ¡ˆã€‚ + +目標訪å•æ¨¡å¼ +~~~~~~~~~~~~ + +``<目標訪å•æ¨¡å¼>`` 是由三個範åœæ§‹æˆçš„，形å¼å¦‚下:: + + min-size max-size min-acc max-acc min-age max-age + +具體來說，å€åŸŸå¤§å°çš„å—節數（ `min-size` å’Œ `max-size` ），訪å•é »çŽ‡çš„æ¯èšåˆå€é–“的監測訪å•æ¬¡ +數（ `min-acc` å’Œ `max-acc` ），å€åŸŸå¹´é½¡çš„èšåˆå€é–“數（ `min-age` å’Œ `max-age` ）都被指定。 +請注æ„，這些範åœæ˜¯å°é–‰å€é–“。 + +動作 +~~~~ + +``<action>`` 是一個é 定義的內å˜ç®¡ç†å‹•ä½œçš„整數，DAMON將應用於具有目標訪å•æ¨¡å¼çš„å€åŸŸã€‚æ”¯æŒ +的數å—和它們的å«ç¾©å¦‚下:: + + - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED`` + - 1: Call ``madvise()`` for the region with ``MADV_COLD`` + - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT`` + - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE`` + - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` + - 5: Do nothing but count the statistics + +é…é¡ +~~~~ + +æ¯å€‹ ``動作`` 的最佳 ``目標訪å•æ¨¡å¼`` å–æ±ºæ–¼å·¥ä½œè² è¼‰ï¼Œæ‰€ä»¥ä¸å®¹æ˜“找到。更糟糕的是，將æŸå€‹ +動作的方案è¨ç½®å¾—éŽæ–¼æ¿€é€²æœƒå°Žè‡´åš´é‡çš„開銷。爲了é¿å…這種開銷，用戶å¯ä»¥é€šéŽä¸‹é¢è¡¨æ ¼ä¸çš„ ``<quota>`` +來é™åˆ¶æ–¹æ¡ˆçš„時間和大å°é…é¡:: + + <ms> <sz> <reset interval> <priority weights> + +這使得DAMON在 ``<reset interval>`` 毫秒內，儘é‡åªç”¨ ``<ms>`` æ¯«ç§’çš„æ™‚é–“å° ``目標訪 +å•æ¨¡å¼`` çš„å…§å˜å€åŸŸæ‡‰ç”¨å‹•ä½œï¼Œä¸¦åœ¨ ``<reset interval>`` å…§åªå°æœ€å¤š<sz>å—節的內å˜å€åŸŸæ‡‰ +用動作。將 ``<ms>`` å’Œ ``<sz>`` 都è¨ç½®çˆ²é›¶ï¼Œå¯ä»¥ç¦ç”¨é…é¡é™åˆ¶ã€‚ + +當é 計超éŽé…é¡é™åˆ¶æ™‚，DAMONæœƒæ ¹æ“š ``目標訪å•æ¨¡å¼`` 的大å°ã€è¨ªå•é »çŽ‡å’Œå¹´é½¡ï¼Œå°ç™¼ç¾çš„å…§å˜ +å€åŸŸé€²è¡Œå„ªå…ˆæŽ’åºã€‚爲了實ç¾å€‹æ€§åŒ–的優先級，用戶å¯ä»¥åœ¨ ``<優先級權é‡>`` ä¸è¨ç½®é€™ä¸‰å€‹å±¬æ€§çš„ +權é‡ï¼Œå…·é«”å½¢å¼å¦‚下:: + + <size weight> <access frequency weight> <age weight> + +æ°´ä½ +~~~~ + +有些方案需è¦æ ¹æ“šç³»çµ±ç‰¹å®šæŒ‡æ¨™çš„當å‰å€¼ä¾†é‹è¡Œï¼Œå¦‚自由內å˜æ¯”率。å°æ–¼é€™ç¨®æƒ…æ³ï¼Œç”¨æˆ¶å¯ä»¥çˆ²è©²æ¢ +件指定水ä½ã€‚:: + + <metric> <check interval> <high mark> <middle mark> <low mark> + +``<metric>`` 是一個é 定義的整數，用於è¦æª¢æŸ¥çš„度é‡ã€‚支æŒçš„數å—和它們的å«ç¾©å¦‚下。 + + - 0: å¿½è¦–æ°´ä½ + - 1: 系統空閒內å˜çŽ‡ (åƒåˆ†æ¯”) + +æ¯éš” ``<檢查間隔>`` 微秒檢查一次公制的值。 + +如果該值高於 ``<高標>`` 或低於 ``<低標>`` ，該方案被åœç”¨ã€‚如果該值低於 ``<ä¸æ¨™>`` ， +該方案將被激活。 + +統計數據 +~~~~~~~~ + +它還統計æ¯å€‹æ–¹æ¡ˆè¢«å˜—試應用的å€åŸŸçš„總數é‡å’Œå—節數，æ¯å€‹æ–¹æ¡ˆè¢«æˆåŠŸæ‡‰ç”¨çš„å€åŸŸçš„兩個數é‡ï¼Œä»¥ +åŠè¶…éŽé…é¡é™åˆ¶çš„總數é‡ã€‚這些統計數據å¯ç”¨æ–¼åœ¨ç·šåˆ†æžæˆ–調整方案。 + +統計數據å¯ä»¥é€šéŽè®€å–方案文件來顯示。讀å–è©²æ–‡ä»¶å°‡é¡¯ç¤ºä½ åœ¨æ¯ä¸€è¡Œä¸è¼¸å…¥çš„æ¯å€‹ ``方案`` ， +統計的五個數å—å°‡è¢«åŠ åœ¨æ¯ä¸€è¡Œçš„末尾。 + +例å +~~~~ + +下é¢çš„命令應用了一個方案：â€å¦‚果一個大å°çˆ²[4KiB, 8KiB]çš„å…§å˜å€åŸŸåœ¨[10, 20]çš„èšåˆæ™‚é–“ +間隔內顯示出æ¯ä¸€å€‹èšåˆæ™‚é–“é–“éš”[0, 5]的訪å•é‡ï¼Œè«‹åˆ†é 出該å€åŸŸã€‚å°æ–¼åˆ†é ，æ¯ç§’最多隻能使 +用10ms，而且æ¯ç§’分é ä¸èƒ½è¶…éŽ1GiB。在這一é™åˆ¶ä¸‹ï¼Œé¦–先分é 出具有較長年齡的內å˜å€åŸŸã€‚å¦å¤–， +æ¯5秒é˜æª¢æŸ¥ä¸€æ¬¡ç³»çµ±çš„å¯ç”¨å…§å˜çŽ‡ï¼Œç•¶å¯ç”¨å…§å˜çŽ‡ä½Žæ–¼50%時開始監測和分é ，但如果å¯ç”¨å…§å˜çŽ‡ +大於60%，或低於30%，則åœæ¢ç›£æ¸¬â€œ:: + + # cd <debugfs>/damon + # scheme="4096 8192 0 5 10 20 2" # target access pattern and action + # scheme+=" 10 $((1024*1024*1024)) 1000" # quotas + # scheme+=" 0 0 100" # prioritization weights + # scheme+=" 1 5000000 600 500 300" # watermarks + # echo "$scheme" > schemes + + +é–‹é—œ +---- + +除éžä½ 明確地啓動監測，å¦å‰‡å¦‚上所述的文件è¨ç½®ä¸æœƒç”¢ç”Ÿæ•ˆæžœã€‚ä½ å¯ä»¥é€šéŽå¯«å…¥å’Œè®€å– ``monitor_on`` +文件來啓動ã€åœæ¢å’Œæª¢æŸ¥ç›£æ¸¬çš„當å‰ç‹€æ…‹ã€‚寫入 ``on`` 該文件å¯ä»¥å•“å‹•å°æœ‰å±¬æ€§çš„目標的監測。寫入 +``off`` 該文件則åœæ¢é€™äº›ç›®æ¨™ã€‚如果æ¯å€‹ç›®æ¨™é€²ç¨‹è¢«çµ‚æ¢ï¼ŒDAMON也會åœæ¢ã€‚下é¢çš„示例命令開啓ã€é—œ +閉和檢查DAMON的狀態:: + + # cd <debugfs>/damon + # echo on > monitor_on + # echo off > monitor_on + # cat monitor_on + off + +請注æ„ï¼Œç•¶ç›£æ¸¬é–‹å•“æ™‚ï¼Œä½ ä¸èƒ½å¯«åˆ°ä¸Šè¿°çš„debugfsæ–‡ä»¶ã€‚å¦‚æžœä½ åœ¨DAMONé‹è¡Œæ™‚寫到這些文件，將會返 +回一個錯誤代碼，如 ``-EBUSY`` 。 + + +監測線程PID +----------- + +DAMON通éŽä¸€å€‹å«åškdamondçš„å…§æ ¸ç·šç¨‹ä¾†é€²è¡Œè«‹æ±‚ç›£æ¸¬ã€‚ä½ å¯ä»¥é€šéŽè®€å– ``kdamond_pid`` æ–‡ä»¶ç² +得該線程的 ``pid`` 。當監測被 ``關閉`` 時，讀å–該文件ä¸æœƒè¿”回任何信æ¯:: + + # cd <debugfs>/damon + # cat monitor_on + off + # cat kdamond_pid + none + # echo on > monitor_on + # cat kdamond_pid + 18594 + + +使用多個監測線程 +---------------- + +æ¯å€‹ç›£æ¸¬ä¸Šä¸‹æ–‡éƒ½æœƒå‰µå»ºä¸€å€‹ ``kdamond`` ç·šç¨‹ã€‚ä½ å¯ä»¥ä½¿ç”¨ ``mk_contexts`` å’Œ ``rm_contexts`` +文件爲多個 ``kdamond`` 需è¦çš„用例創建和刪除監測上下文。 + +將新上下文的å稱寫入 ``mk_contexts`` 文件，在 ``DAMON debugfs`` 目錄上創建一個該å稱的目錄。 +該目錄將有該上下文的 ``DAMON debugfs`` 文件:: + + # cd <debugfs>/damon + # ls foo + # ls: cannot access 'foo': No such file or directory + # echo foo > mk_contexts + # ls foo + # attrs init_regions kdamond_pid schemes target_ids + +如果ä¸å†éœ€è¦ä¸Šä¸‹æ–‡ï¼Œä½ å¯ä»¥é€šéŽæŠŠä¸Šä¸‹æ–‡çš„åå—放到 ``rm_contexts`` 文件ä¸ä¾†åˆªé™¤å®ƒå’Œç›¸æ‡‰çš„目錄:: + + # echo foo > rm_contexts + # ls foo + # ls: cannot access 'foo': No such file or directory + +注æ„， ``mk_contexts`` 〠``rm_contexts`` å’Œ ``monitor_on`` 文件åªåœ¨æ ¹ç›®éŒ„下。 + + +監測çµæžœçš„監測點 +================ + +DAMON通éŽä¸€å€‹tracepoint ``damon:damon_aggregated`` æ供監測çµæžœ. ç•¶ç›£æ¸¬é–‹å•“æ™‚ï¼Œä½ å¯ +以記錄追蹤點事件，並使用追蹤點支æŒå·¥å…·å¦‚perf顯示çµæžœã€‚比如說:: + + # echo on > monitor_on + # perf record -e damon:damon_aggregated & + # sleep 5 + # kill 9 $(pidof perf) + # echo off > monitor_on + # perf script + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/index.rst b/Documentation/translations/zh_TW/admin-guide/mm/index.rst new file mode 100644 index 000000000000..0b04d925b68c --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/index.rst @@ -0,0 +1,50 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/index.rst + +:ç¿»è¯: + + å¾é‘« xu xin <xu.xin16@zte.com.cn> + + +======== +å…§å˜ç®¡ç† +======== + +Linuxå…§å˜ç®¡ç†å系統，顧åæ€ç¾©ï¼Œæ˜¯è² 責系統ä¸çš„å…§å˜ç®¡ç†ã€‚它包括了虛擬內å˜èˆ‡è«‹æ±‚ +分é 的實ç¾ï¼Œå…§æ ¸å…§éƒ¨çµæ§‹å’Œç”¨æˆ¶ç©ºé–“程åºçš„å…§å˜åˆ†é…ã€å°‡æ–‡ä»¶æ˜ 射到進程地å€ç©ºé–“以 +åŠè¨±å¤šå…¶ä»–很酷的事情。 + +Linuxå…§å˜ç®¡ç†æ˜¯ä¸€å€‹å…·æœ‰è¨±å¤šå¯é…ç½®è¨ç½®çš„複雜系統, 且這些è¨ç½®ä¸çš„大多數都å¯ä»¥é€š +éŽ ``/proc`` 文件系統ç²å¾—，並且å¯ä»¥ä½¿ç”¨ ``sysctl`` 進行查詢和調整。這些API接 +å£è¢«æ述在Documentation/admin-guide/sysctl/vm.rst文件和 `man 5 proc`_ ä¸ã€‚ + +.. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html + +Linuxå…§å˜ç®¡ç†æœ‰å®ƒè‡ªå·±çš„è¡“èªžï¼Œå¦‚æžœä½ é‚„ä¸ç†Ÿæ‚‰å®ƒï¼Œè«‹è€ƒæ…®é–±è®€ä¸‹é¢åƒè€ƒï¼š +Documentation/admin-guide/mm/concepts.rst. + +在æ¤ç›®éŒ„下，我們詳細æè¿°çžå¦‚何與Linuxå…§å˜ç®¡ç†ä¸çš„å„種機制交互。 + +.. toctree:: + :maxdepth: 1 + + damon/index + ksm + +Todolist: +* concepts +* cma_debugfs +* hugetlbpage +* idle_page_tracking +* memory-hotplug +* nommu-mmap +* numa_memory_policy +* numaperf +* pagemap +* soft-dirty +* swap_numa +* transhuge +* userfaultfd +* zswap + diff --git a/Documentation/translations/zh_TW/admin-guide/mm/ksm.rst b/Documentation/translations/zh_TW/admin-guide/mm/ksm.rst new file mode 100644 index 000000000000..1b4944b3cf61 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/mm/ksm.rst @@ -0,0 +1,199 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/mm/ksm.rst + +:ç¿»è¯: + + å¾é‘« xu xin <xu.xin16@zte.com.cn> + + +============ +å…§æ ¸åŒé åˆä½µ +============ + + +概述 +==== + +KSM是一種能節çœå…§å˜çš„數據去é‡åŠŸèƒ½ï¼Œç”±CONFIG_KSM=y啓用，並在2.6.32版本時被添 +åŠ åˆ°Linuxå…§æ ¸ã€‚è©³è¦‹ ``mm/ksm.c`` 的實ç¾ï¼Œä»¥åŠhttp://lwn.net/Articles/306704 +å’Œhttps://lwn.net/Articles/330589 + +KSM最åˆç›®çš„是爲了與KVM（å³è‘—åçš„å…§æ ¸å…±äº«å…§å˜ï¼‰ä¸€èµ·ä½¿ç”¨è€Œé–‹ç™¼çš„，通éŽå…±äº«è™›æ“¬æ©Ÿ +之間的公共數據，將更多虛擬機放入物ç†å…§å˜ã€‚但它å°æ–¼ä»»ä½•æœƒç”Ÿæˆå¤šå€‹ç›¸åŒæ•¸æ“šå¯¦ä¾‹çš„ +應用程åºéƒ½æ˜¯å¾ˆæœ‰ç”¨çš„。 + +KSM的守è·é€²ç¨‹ksmd會定期掃æ那些已註冊的用戶內å˜å€åŸŸï¼ŒæŸ¥æ‰¾å…§å®¹ç›¸åŒçš„é é¢ï¼Œé€™äº› +é é¢å¯ä»¥è¢«å–®å€‹å¯«ä¿è·é é¢æ›¿æ›ï¼ˆå¦‚果進程以後想è¦æ›´æ–°å…¶å…§å®¹ï¼Œå°‡è‡ªå‹•è¤‡è£½ï¼‰ã€‚使用： +引用:`sysfs intraface <ksm_sysfs>` 接å£ä¾†é…ç½®KSM守è·ç¨‹åºåœ¨å–®å€‹éŽç¨‹ä¸æ‰€æŽƒæçš„é +數以åŠå…©å€‹éŽç¨‹ä¹‹é–“的間隔時間。 + +KSMåªåˆä¸¦åŒ¿å（ç§æœ‰ï¼‰é é¢ï¼Œå¾žä¸åˆä¸¦é ç·©å˜ï¼ˆæ–‡ä»¶ï¼‰é é¢ã€‚KSMçš„åˆä½µé é¢æœ€åˆåªèƒ½è¢« +éŽ–å®šåœ¨å…§æ ¸å…§å˜ä¸ï¼Œä½†ç¾åœ¨å¯ä»¥å°±åƒå…¶ä»–用戶é é¢ä¸€æ¨£è¢«æ›å‡ºï¼ˆä½†ç•¶å®ƒå€‘被交æ›å›žä¾†æ™‚å…± +äº«æœƒè¢«ç ´å£ž: ksmdå¿…é ˆé‡æ–°ç™¼ç¾å®ƒå€‘的身份並å†æ¬¡åˆä½µï¼‰ã€‚ + +以madvise控制KSM +================ + +KSM僅在特定的地å€ç©ºé–“å€åŸŸæ™‚é‹è¡Œï¼Œå³æ‡‰ç”¨ç¨‹åºé€šéŽä½¿ç”¨å¦‚下所示的madvise(2)系統調 +用來請求æŸå¡Šåœ°å€æˆçˆ²å¯èƒ½çš„åˆä½µå€™é¸è€…的地å€ç©ºé–“:: + + int madvise(addr, length, MADV_MERGEABLE) + +應用程åºç•¶ç„¶ä¹Ÿå¯ä»¥é€šéŽèª¿ç”¨:: + + int madvise(addr, length, MADV_UNMERGEABLE) + +來å–消該請求，並æ¢å¾©çˆ²éžå…±äº«é é¢ï¼šæ¤æ™‚KSM將去除åˆä½µåœ¨è©²ç¯„åœå…§çš„任何åˆä½µé 。注æ„： +這個去除åˆä½µçš„調用å¯èƒ½çªç„¶éœ€è¦çš„å…§å˜é‡è¶…éŽå¯¦éš›å¯ç”¨çš„å…§å˜é‡-那麼å¯èƒ½æœƒå‡ºç¾EAGAIN +失敗，但更å¯èƒ½æœƒå–šé†’OOM killer。 + +如果KSM未被é…置到æ£åœ¨é‹è¡Œçš„å…§æ ¸ä¸ï¼Œå‰‡madvise MADV_MERGEABLE å’Œ MADV_UNMERGEABLE +的調用åªæœƒä»¥EINVAL 失敗。如果æ£åœ¨é‹è¡Œçš„å…§æ ¸æ˜¯ç”¨CONFIG_KSM=yæ–¹å¼æ§‹å»ºçš„，那麼這些 +調用通常會æˆåŠŸï¼šå³ä½¿KSM守è·ç¨‹åºç•¶å‰æ²’有é‹è¡Œï¼ŒMADV_MERGEABLE ä»ç„¶æœƒåœ¨KSM守è·ç¨‹åº +啓動時註冊範åœï¼Œå³ä½¿è©²ç¯„åœä¸èƒ½åŒ…å«KSM實際å¯ä»¥åˆä½µçš„任何é é¢ï¼Œå³ä½¿MADV_UNMERGEABLE +應用於從未標記爲MADV_MERGEABLE的範åœã€‚ + +如果一塊內å˜å€åŸŸå¿…é ˆè¢«æ‹†åˆ†çˆ²è‡³å°‘ä¸€å€‹æ–°çš„MADV_MERGEABLEå€åŸŸæˆ–MADV_UNMERGEABLEå€åŸŸï¼Œ +ç•¶è©²é€²ç¨‹å°‡è¶…éŽ ``vm.max_map_count`` çš„è¨å®šï¼Œå‰‡madviseå¯èƒ½è¿”回ENOMEM。（請åƒé–±æ–‡æª” +Documentation/admin-guide/sysctl/vm.rst）。 + +與其他madvise調用一樣，它們在用戶地å€ç©ºé–“çš„æ˜ å°„å€åŸŸä¸Šä½¿ç”¨ï¼šå¦‚果指定的範åœåŒ…å«æœª +æ˜ å°„çš„é–“éš™ï¼ˆå„˜ç®¡åœ¨ä¸é–“çš„æ˜ å°„å€åŸŸå·¥ä½œï¼‰ï¼Œå®ƒå€‘å°‡å ±å‘ŠENOMEMï¼Œå¦‚æžœæ²’æœ‰è¶³å¤ çš„å…§å˜ç”¨æ–¼ +內部çµæ§‹ï¼Œå‰‡å¯èƒ½æœƒå› EAGAIN而失敗。 + +KSM守è·é€²ç¨‹sysfsæŽ¥å£ +==================== + +KSM守è·é€²ç¨‹å¯ä»¥ç”±``/sys/kernel/mm/ksm/`` ä¸çš„sysfs文件控制，所有人都å¯ä»¥è®€å–，但 +åªèƒ½ç”±root用戶寫入。å„接å£è§£é‡‹å¦‚下： + + +pages_to_scan + ksmd進程進入ç¡çœ å‰è¦æŽƒæçš„é 數。 + 例如， ``echo 100 > /sys/kernel/mm/ksm/pages_to_scan`` + + 默èªå€¼ï¼š100（該值被é¸æ“‡ç”¨æ–¼æ¼”示目的） + +sleep_millisecs + ksmd在下次掃æå‰æ‡‰ä¼‘çœ å¤šå°‘æ¯«ç§’ + 例如， ``echo 20 > /sys/kernel/mm/ksm/sleep_millisecs`` + + 默èªå€¼ï¼š20（該值被é¸æ“‡ç”¨æ–¼æ¼”示目的） + +merge_across_nodes + 指定是å¦å¯ä»¥åˆä½µä¾†è‡ªä¸åŒNUMA節點的é é¢ã€‚當è¨ç½®çˆ²0時，ksm僅åˆä½µåœ¨ç‰©ç†ä¸Šä½ + æ–¼åŒä¸€NUMA節點的內å˜å€åŸŸä¸çš„é é¢ã€‚這é™ä½Žäº†è¨ªå•å…±äº«é é¢çš„延é²ã€‚在有明顯的 + NUMAè·é›¢ä¸Šï¼Œå…·æœ‰æ›´å¤šç¯€é»žçš„系統å¯èƒ½å—益於è¨ç½®è©²å€¼çˆ²0時的更低延é²ã€‚而å°æ–¼ + 需è¦å°å…§å˜ä½¿ç”¨é‡æœ€å°åŒ–的較å°ç³»çµ±ä¾†èªªï¼Œè¨ç½®è©²å€¼çˆ²1（默èªè¨ç½®ï¼‰å‰‡å¯èƒ½æœƒå— + 益於更大共享é é¢ã€‚在決定使用哪種è¨ç½®ä¹‹å‰ï¼Œæ‚¨å¯èƒ½å¸Œæœ›æ¯”較系統在æ¯ç¨®è¨ç½®ä¸‹ + 的性能。 ``merge_across_nodes`` 僅當系統ä¸æ²’有ksm共享é é¢æ™‚，æ‰èƒ½è¢«æ›´æ”¹è¨ + 置：首先將接å£`run` è¨ç½®çˆ²2從而å°é 進行去åˆä½µï¼Œç„¶å¾Œåœ¨ä¿®æ”¹ + ``merge_across_nodes`` 後å†å°‡â€˜run’åˆè¨ç½®çˆ²1ï¼Œä»¥æ ¹æ“šæ–°è¨ç½®ä¾†é‡æ–°åˆä½µã€‚ + + 默èªå€¼ï¼š1（如早期的發佈版本一樣åˆä½µè·¨ç«™é»žï¼‰ + +run + * è¨ç½®çˆ²0å¯åœæ¢ksmdé‹è¡Œï¼Œä½†ä¿ç•™åˆä½µé é¢ï¼Œ + * è¨ç½®çˆ²1å¯é‹è¡Œksmd，例如， ``echo 1 > /sys/kernel/mm/ksm/run`` ， + * è¨ç½®çˆ²2å¯åœæ¢ksmdé‹è¡Œï¼Œä¸¦ä¸”å°æ‰€æœ‰ç›®å‰å·²åˆä½µçš„é 進行去åˆä½µï¼Œä½†ä¿ç•™å¯åˆä½µ + å€åŸŸä»¥ä¾›ä¸‹æ¬¡é‹è¡Œã€‚ + + 默èªå€¼ï¼š0ï¼ˆå¿…é ˆè¨ç½®çˆ²1æ‰èƒ½æ¿€æ´»KSM，除éžç¦ç”¨äº†CONFIG_SYSFS） + +use_zero_pages + 指定是å¦æ‡‰ç•¶ç‰¹æ®Šè™•ç†ç©ºé （å³é‚£äº›åƒ…å«zero的已分é…é ）。當該值è¨ç½®çˆ²1時， + 空é èˆ‡å…§æ ¸é›¶é åˆä½µï¼Œè€Œä¸æ˜¯åƒé€šå¸¸æƒ…æ³ä¸‹é‚£æ¨£ç©ºé 自身彼æ¤åˆä½µã€‚這å¯ä»¥æ ¹æ“š + å·¥ä½œè² è¼‰çš„ä¸åŒï¼Œåœ¨å…·æœ‰ç€è‰²é›¶é 的架構上å¯ä»¥æ高性能。啓用æ¤è¨ç½®æ™‚應å°å¿ƒï¼Œ + å› çˆ²å®ƒå¯èƒ½æœƒé™ä½ŽæŸäº›å·¥ä½œè² 載的KSM性能，比如，當待åˆä½µçš„候é¸é é¢çš„æ ¡é©—å’Œ + 與空é é¢çš„æ ¡é©—å’Œæ°å¥½åŒ¹é…的時候。æ¤è¨ç½®å¯éš¨æ™‚更改，僅å°é‚£äº›æ›´æ”¹å¾Œå†åˆä½µ + çš„é é¢æœ‰æ•ˆã€‚ + + 默èªå€¼ï¼š0（如åŒæ—©æœŸç‰ˆæœ¬çš„KSMæ£å¸¸è¡¨ç¾ï¼‰ + +max_page_sharing + 單個KSMé é¢å…許的最大共享站點數。這將強制執行é‡è¤‡æ•¸æ“šæ¶ˆé™¤é™åˆ¶ï¼Œä»¥é¿å…涉 + åŠéæ·å…±äº«KSMé é¢çš„è™›æ“¬æ˜ å°„çš„è™›æ“¬å…§å˜æ“作的高延é²ã€‚最å°å€¼çˆ²2ï¼Œå› çˆ²æ–°å‰µ + 建的KSMé é¢å°‡è‡³å°‘有兩個共享者。該值越高，KSMåˆä½µå…§å˜çš„é€Ÿåº¦è¶Šå¿«ï¼ŒåŽ»é‡ + å› å也越高，但是å°æ–¼ä»»ä½•çµ¦å®šçš„KSMé é¢ï¼Œè™›æ“¬æ˜ 射的最壞情æ³éæ·çš„速度也會 + 越慢。減慢了這種éæ·é€Ÿåº¦å°±æ„味ç€åœ¨äº¤æ›ã€å£“縮ã€NUMA平衡和é é¢é·ç§»æœŸé–“， + æŸäº›è™›æ“¬å…§å˜æ“作將有更高的延é²ï¼Œå¾žè€Œé™ä½Žé€™äº›è™›æ“¬å…§å˜æ“作調用者的響應能力。 + 其他任務如果ä¸æ¶‰åŠåŸ·è¡Œè™›æ“¬æ˜ å°„éæ·çš„VMæ“作，其任務調度延é²ä¸å—æ¤åƒæ•¸çš„å½± + éŸ¿ï¼Œå› çˆ²é€™äº›éæ·æœ¬èº«æ˜¯èª¿åº¦å‹å¥½çš„。 + +stable_node_chains_prune_millisecs + 指定KSM檢查特定é é¢çš„å…ƒæ•¸æ“šçš„é »çŽ‡ï¼ˆå³é‚£äº›é”到éŽæ™‚ä¿¡æ¯æ•¸æ“šåŽ»é‡é™åˆ¶æ¨™æº–çš„ + é é¢ï¼‰å–®ä½æ˜¯æ¯«ç§’。較å°çš„毫秒值將以更低的延é²ä¾†é‡‹æ”¾KSM元數據，但它們將使 + ksmd在掃æ期間使用更多CPU。如果還沒有一個KSMé é¢é”到 ``max_page_sharing`` + 標準，那就沒有什麼用。 + +KSM與MADV_MERGEABLE的工作有效性體ç¾æ–¼ ``/sys/kernel/mm/ksm/`` 路徑下的接å£ï¼š + +pages_shared + 表示多少共享é æ£åœ¨è¢«ä½¿ç”¨ +pages_sharing + 表示還有多少站點æ£åœ¨å…±äº«é€™äº›å…±äº«é ，å³ç¯€çœäº†å¤šå°‘ +pages_unshared + 表示有多少é 是唯一的，但被å覆檢查以進行åˆä½µ +pages_volatile + 表示有多少é å› è®ŠåŒ–å¤ªå¿«è€Œç„¡æ³•æ”¾åœ¨treeä¸ +full_scans + 表示所有å¯åˆä½µå€åŸŸå·²æŽƒæ多少次 +stable_node_chains + é”到 ``max_page_sharing`` é™åˆ¶çš„KSMé 數 +stable_node_dups + é‡è¤‡çš„KSMé 數 + +比值 ``pages_sharing/pages_shared`` 的最大值å—é™åˆ¶æ–¼ ``max_page_sharing`` +çš„è¨å®šã€‚è¦æƒ³å¢žåŠ 該比值，則相應地è¦å¢žåŠ ``max_page_sharing`` 的值。 + +監測KSM的收益 +============= + +KSMå¯ä»¥é€šéŽåˆä½µç›¸åŒçš„é é¢ä¾†ç¯€çœå…§å˜ï¼Œä½†ä¹Ÿæœƒæ¶ˆè€—é¡å¤–çš„å…§å˜ï¼Œå› 爲它需è¦ç”Ÿæˆä¸€äº›rmap_items +來ä¿å˜æ¯å€‹æŽƒæé é¢çš„ç°¡è¦rmapä¿¡æ¯ã€‚å…¶ä¸æœ‰äº›é é¢å¯èƒ½æœƒè¢«åˆä½µï¼Œä½†æœ‰äº›é é¢åœ¨è¢«æª¢æŸ¥å¹¾æ¬¡ +後å¯èƒ½ç„¡æ³•è¢«åˆä½µï¼Œé€™äº›éƒ½æ˜¯ç„¡ç›Šçš„å…§å˜æ¶ˆè€—。 + +1) 如何確定KSM在全系統範åœå…§æ˜¯ç¯€çœå…§å˜é‚„是消耗內å˜ï¼Ÿé€™è£æœ‰ä¸€å€‹ç°¡å–®çš„近似計算方法供åƒè€ƒ:: + + general_profit =~ pages_sharing * sizeof(page) - (all_rmap_items) * + sizeof(rmap_item); + + å…¶ä¸all_rmap_itemså¯ä»¥é€šéŽå° ``pages_sharing`` 〠``pages_shared`` 〠``pages_unshared`` + å’Œ ``pages_volatile`` 的求和而輕鬆ç²å¾—。 + +2) 單一進程ä¸KSM的收益也å¯ä»¥é€šéŽä»¥ä¸‹è¿‘似的計算得到:: + + process_profit =~ ksm_merging_pages * sizeof(page) - + ksm_rmap_items * sizeof(rmap_item). + + å…¶ä¸ksm_merging_pages顯示在 ``/proc/<pid>/`` 目錄下，而ksm_rmap_items + 顯示在 ``/proc/<pid>/ksm_stat`` 。 + +從應用的角度來看， ``ksm_rmap_items`` å’Œ ``ksm_merging_pages`` çš„é«˜æ¯”ä¾‹æ„ +味ç€ä¸å¥½çš„madvise-appliedç–略，所以開發者或管ç†å“¡å¿…é ˆé‡æ–°è€ƒæ…®å¦‚何改變madvisç– +略。舉個例åä¾›åƒè€ƒï¼Œä¸€å€‹é é¢çš„大å°é€šå¸¸æ˜¯4K，而rmap_item的大å°åœ¨32ä½CPU架構上分 +別是32B，在64ä½CPU架構上是64B。所以如果 ``ksm_rmap_items/ksm_merging_pages`` +的比例在64ä½CPU上超éŽ64，或者在32ä½CPU上超éŽ128，那麼應用程åºçš„madviseç–略應 +è©²è¢«æ”¾æ£„ï¼Œå› çˆ²ksmæ”¶ç›Šå¤§ç´„çˆ²é›¶æˆ–è² å€¼ã€‚ + +監控KSM事件 +=========== + +在/proc/vmstatä¸æœ‰ä¸€äº›è¨ˆæ•¸å™¨ï¼Œå¯ä»¥ç”¨ä¾†ç›£æŽ§KSM事件。KSMå¯èƒ½æœ‰åŠ©æ–¼ç¯€çœå…§å˜ï¼Œé€™æ˜¯ +ä¸€ç¨®æ¬Šè¡¡ï¼Œå› çˆ²å®ƒå¯èƒ½æœƒåœ¨KSM COW或複製ä¸çš„交æ›ä¸Šéå—延é²ã€‚這些事件å¯ä»¥å¹«åŠ©ç”¨æˆ¶è©•ä¼° +是å¦æˆ–如何使用KSM。例如，如果cow_ksmå¢žåŠ å¾—å¤ªå¿«ï¼Œç”¨æˆ¶å¯ä»¥æ¸›å°‘madvise(, , MADV_MERGEABLE) +的範åœã€‚ + +cow_ksm + 在æ¯æ¬¡KSMé é¢è§¸ç™¼å¯«æ™‚æ‹·è²ï¼ˆCOW）時都會被éžå¢žï¼Œç•¶ç”¨æˆ¶è©¦åœ–寫入KSMé é¢æ™‚， + æˆ‘å€‘å¿…é ˆåšä¸€å€‹æ‹·è²ã€‚ + +ksm_swpin_copy + 在æ›å…¥æ™‚，æ¯æ¬¡KSMé 被複制時都會被éžå¢žã€‚請注æ„，KSMé 在æ›å…¥æ™‚å¯èƒ½æœƒè¢«è¤‡ + åˆ¶ï¼Œå› çˆ²do_swap_page()ä¸èƒ½åšæ‰€æœ‰çš„鎖，而需è¦é‡çµ„一個跨anon_vmaçš„KSMé 。 + +-- +Izik Eidus, +Hugh Dickins, 2009å¹´11月17日。 + diff --git a/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst index ea51342879c0..fe5a5a07d51a 100644 --- a/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst +++ b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst @@ -1,13 +1,6 @@ .. 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. +.. See the bottom of this file for additional redistribution information. + .. include:: ../disclaimer-zh_TW.rst @@ -26,14 +19,16 @@ 簡明指å—ï¼ˆäº¦å³ å¤ªé•·ä¸çœ‹ï¼‰ ========================== -您é¢è‡¨çš„是å¦çˆ²åŒç³»åˆ—穩定版或長期支æŒå…§æ ¸çš„æ™®é€šå…§æ ¸çš„å›žæ¸ï¼Ÿæ˜¯å¦ä»ç„¶å—支æŒï¼Ÿ +您é¢è‡¨çš„是å¦çˆ²åŒç³»åˆ—穩定版或長期支æŒå…§æ ¸çš„æ™®é€šå…§æ ¸çš„è¿´æ¸ï¼Ÿæ˜¯å¦ä»ç„¶å—支æŒï¼Ÿ è«‹æœç´¢ `LKMLå…§æ ¸éƒµä»¶åˆ—è¡¨ <https://lore.kernel.org/lkml/>`_ å’Œ `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ å˜æª”ä¸åŒ¹é…çš„å ±å‘Šä¸¦ åŠ å…¥è¨Žè«–ã€‚å¦‚æžœæ‰¾ä¸åˆ°åŒ¹é…çš„å ±å‘Šï¼Œè«‹å®‰è£è©²ç³»åˆ—的最新版本。如果它ä»ç„¶å‡ºç¾å•é¡Œï¼Œ -å ±å‘Šçµ¦ç©©å®šç‰ˆéƒµä»¶åˆ—è¡¨ï¼ˆstable@vger.kernel.org）。 +è«‹å ±å‘Šçµ¦ç©©å®šç‰ˆéƒµä»¶åˆ—è¡¨ï¼ˆstable@vger.kernel.org）並抄é€å›žæ¸éƒµä»¶åˆ—表 +（regressions@lists.linux.dev）；ç†æƒ³æƒ…æ³ä¸‹ï¼Œé‚„å¯ä»¥æŠ„é€ç¶è·è€…和相關å系統的 +郵件列表。 在所有其他情æ³ä¸‹ï¼Œè«‹å„˜å¯èƒ½çŒœæ¸¬æ˜¯å“ªå€‹å…§æ ¸éƒ¨åˆ†å°Žè‡´äº†å•é¡Œã€‚查看MAINTAINERS文件， -了解開發人員希望如何得知å•é¡Œï¼Œå¤§å¤šæ•¸æƒ…æ³ä¸‹ï¼Œå ±å‘Šå•é¡Œéƒ½æ˜¯é€šéŽé›»åéƒµä»¶å’ŒæŠ„é€ +çžè§£é–‹ç™¼äººå“¡å¸Œæœ›å¦‚何得知å•é¡Œï¼Œå¤§å¤šæ•¸æƒ…æ³ä¸‹ï¼Œå ±å‘Šå•é¡Œéƒ½æ˜¯é€šéŽé›»åéƒµä»¶å’ŒæŠ„é€ ç›¸é—œéƒµä»¶åˆ—è¡¨é€²è¡Œçš„ã€‚æª¢æŸ¥å ±å‘Šç›®çš„åœ°çš„å˜æª”ä¸æ˜¯å¦å·²æœ‰åŒ¹é…çš„å ±å‘Šï¼›ä¹Ÿè«‹æœç´¢ `LKML <https://lore.kernel.org/lkml/>`_ 和網絡。如果找ä¸åˆ°å¯åŠ 入的討論，請 å®‰è£ `æœ€æ–°çš„ä¸»ç·šå…§æ ¸ <https://kernel.org/>`_ 。如果ä»å˜åœ¨å•é¡Œï¼Œè«‹ç™¼é€å ±å‘Šã€‚ @@ -45,21 +40,22 @@ **通用æ醒** ：當安è£å’Œæ¸¬è©¦ä¸Šè¿°å…§æ ¸æ™‚，請確ä¿å®ƒæ˜¯æ™®é€šçš„（å³ï¼šæ²’有補ä¸ï¼Œä¹Ÿæ²’ æœ‰ä½¿ç”¨é™„åŠ æ¨¡å¡Šï¼‰ã€‚é‚„è¦ç¢ºä¿å®ƒæ˜¯åœ¨ä¸€å€‹æ£å¸¸çš„環境ä¸æ§‹å»ºå’Œé‹è¡Œï¼Œä¸¦ä¸”在å•é¡Œç™¼ç”Ÿ -之å‰æ²’有被汙染（tainted）。 +之å‰æ²’有被污染（tainted）。 -åœ¨ç·¨å¯«å ±å‘Šæ™‚ï¼Œè¦æ¶µè“‹èˆ‡å•é¡Œç›¸é—œçš„所有信æ¯ï¼Œå¦‚ä½¿ç”¨çš„å…§æ ¸å’Œç™¼è¡Œç‰ˆã€‚åœ¨ç¢°è¦‹å›žæ¸æ™‚， -嘗試給出引入它的更改的æ交ID，二分å¯ä»¥æ‰¾åˆ°å®ƒã€‚如果您åŒæ™‚é¢è‡¨Linuxå…§æ ¸çš„å¤šå€‹ -å•é¡Œï¼Œè«‹åˆ†åˆ¥å ±å‘Šæ¯å€‹å•é¡Œã€‚ +ç•¶ä½ åŒæ™‚é¢è‡¨Linuxå…§æ ¸çš„å¤šå€‹å•é¡Œæ™‚ï¼Œè«‹åˆ†åˆ¥å ±å‘Šã€‚åœ¨ç·¨å¯«å ±å‘Šæ™‚ï¼Œè¦æ¶µè“‹èˆ‡å•é¡Œ +相關的所有信æ¯ï¼Œå¦‚ä½¿ç”¨çš„å…§æ ¸å’Œç™¼è¡Œç‰ˆã€‚å¦‚æžœç¢°è¦‹è¿´æ¸ï¼Œè«‹æŠŠå ±å‘ŠæŠ„é€å›žæ¸éƒµä»¶åˆ—表 +（regressions@lists.linux.dev）。也請試試用二分法找出æºé ；如果æˆåŠŸæ‰¾åˆ°ï¼Œè«‹ +åœ¨å ±å‘Šä¸å¯«ä¸Šå®ƒçš„æ交ID並抄é€sign-off-byéˆä¸çš„所有人。 ä¸€æ—¦å ±å‘Šç™¼å‡ºï¼Œè«‹å›žç”任何出ç¾çš„å•é¡Œï¼Œä¸¦å„˜å¯èƒ½åœ°æ供幫助。這包括通éŽä¸æ™‚é‡æ–° -測試新版本並發é€ç‹€æ…‹æ›´æ–°ä¾†æŽ¨å‹•é€²å±•ã€‚ +測試新版本併發é€ç‹€æ…‹æ›´æ–°ä¾†æŽ¨å‹•é€²å±•ã€‚ 如何å‘å…§æ ¸ç¶è·äººå“¡å ±å‘Šå•é¡Œçš„é€æ¥æŒ‡å— ===================================== -上é¢çš„簡明指å—概述了如何å‘Linuxå…§æ ¸é–‹ç™¼äººå“¡å ±å‘Šå•é¡Œã€‚å°æ–¼å·²ç¶“熟悉å‘自由和開 -æºè»Ÿé«”（FLOSSï¼‰é …ç›®å ±å‘Šå•é¡Œçš„人來說，這å¯èƒ½æ˜¯ä»–們所需è¦çš„全部內容。å°æ–¼å…¶ä»– +上é¢çš„簡明指å—概述çžå¦‚何å‘Linuxå…§æ ¸é–‹ç™¼äººå“¡å ±å‘Šå•é¡Œã€‚å°æ–¼å·²ç¶“熟悉å‘自由和開 +æºè»Ÿä»¶ï¼ˆFLOSSï¼‰é …ç›®å ±å‘Šå•é¡Œçš„人來說，這å¯èƒ½æ˜¯ä»–們所需è¦çš„全部內容。å°æ–¼å…¶ä»– 人，本部分更爲詳細，並一æ¥ä¸€æ¥åœ°æ述。爲了便於閱讀，它ä»ç„¶å„˜é‡ç°¡æ½”，並çœç•¥ 了許多細節；這些在é€æ¥æŒ‡å—後的åƒè€ƒç« 節ä¸é€²è¡Œäº†æè¿°ï¼Œè©²ç« ç¯€æ›´è©³ç´°åœ°è§£é‡‹äº†æ¯ å€‹æ¥é©Ÿã€‚ @@ -68,16 +64,16 @@ 儘早æ„è˜åˆ°çœ‹èµ·ä¾†åƒLinuxå…§æ ¸æ¯›ç—…çš„å•é¡Œå¯èƒ½å¯¦éš›ä¸Šæ˜¯ç”±å…¶ä»–åŽŸå› å¼•èµ·çš„ã€‚é€™äº›æ¥é©Ÿ å¯ä»¥ç¢ºä¿ä½ 最終ä¸æœƒè¦ºå¾—在這一éŽç¨‹ä¸æŠ•å…¥çš„時間是浪費： - * 您是å¦é¢è‡¨ç¡¬é«”或軟體供應商æ供的Linuxå…§æ ¸çš„å•é¡Œï¼Ÿé‚£éº¼åŸºæœ¬ä¸Šæ‚¨æœ€å¥½åœæ¢é–±è®€ + * 您是å¦é¢è‡¨ç¡¬ä»¶æˆ–軟件供應商æ供的Linuxå…§æ ¸çš„å•é¡Œï¼Ÿé‚£éº¼åŸºæœ¬ä¸Šæ‚¨æœ€å¥½åœæ¢é–±è®€ 本文檔，轉而å‘æ‚¨çš„ä¾›æ‡‰å•†å ±å‘Šå•é¡Œï¼Œé™¤éžæ‚¨é¡˜æ„自己安è£æœ€æ–°çš„Linux版本。尋找 和解決å•é¡Œå¾€å¾€éœ€è¦å¾Œè€…。 - * 使用您喜愛的網絡æœå°‹å¼•æ“Žå°ç¾æœ‰å ±å‘Šé€²è¡Œç²—ç•¥æœç´¢ï¼›æ¤å¤–，請檢查 + * 使用您喜愛的網絡æœç´¢å¼•æ“Žå°ç¾æœ‰å ±å‘Šé€²è¡Œç²—ç•¥æœç´¢ï¼›æ¤å¤–，請檢查 `Linuxå…§æ ¸éƒµä»¶åˆ—è¡¨ï¼ˆLKML） <https://lore.kernel.org/lkml/>`_ çš„å˜æª”。如果 找到匹é…çš„å ±å‘Šï¼Œè«‹åŠ å…¥è¨Žè«–è€Œä¸æ˜¯ç™¼é€æ–°å ±å‘Šã€‚ - * çœ‹çœ‹ä½ æ£åœ¨è™•ç†çš„å•é¡Œæ˜¯å¦çˆ²å›žæ¸å•é¡Œã€å®‰å…¨å•é¡Œæˆ–éžå¸¸åš´é‡çš„å•é¡Œï¼šé€™äº›éƒ½æ˜¯éœ€ - è¦åœ¨æŽ¥ä¸‹ä¾†çš„一些æ¥é©Ÿä¸ç‰¹åˆ¥è™•ç†çš„「高優先級å•é¡Œã€ã€‚ + * çœ‹çœ‹ä½ æ£åœ¨è™•ç†çš„å•é¡Œæ˜¯å¦çˆ²è¿´æ¸å•é¡Œã€å®‰å…¨å•é¡Œæˆ–éžå¸¸åš´é‡çš„å•é¡Œï¼šé€™äº›éƒ½æ˜¯éœ€ + è¦åœ¨æŽ¥ä¸‹ä¾†çš„一些æ¥é©Ÿä¸ç‰¹åˆ¥è™•ç†çš„“高優先級å•é¡Œâ€ã€‚ * 確ä¿ä¸æ˜¯å…§æ ¸ç’°å¢ƒå°Žè‡´äº†æ‚¨é¢è‡¨çš„å•é¡Œã€‚ @@ -86,15 +82,15 @@ * 確ä¿æ‚¨çš„系統ä¸æœƒé€šéŽå‹•æ…‹æ§‹å»ºé¡å¤–çš„å…§æ ¸æ¨¡å¡Šä¾†å¢žå¼·å…¶å…§æ ¸ï¼ŒåƒDKMS這樣的解決 方案å¯èƒ½åœ¨æ‚¨ä¸çŸ¥æƒ…的情æ³ä¸‹å°±åœ¨æœ¬åœ°é€²è¡Œäº†é€™æ¨£çš„工作。 - * 當å•é¡Œç™¼ç”Ÿæ™‚ï¼Œæª¢æŸ¥æ‚¨çš„å…§æ ¸æ˜¯å¦è¢«ã€Œæ±™æŸ“ã€ï¼Œå› çˆ²ä½¿å…§æ ¸è¨ç½®é€™å€‹æ¨™èªŒçš„事件å¯èƒ½ + * 當å•é¡Œç™¼ç”Ÿæ™‚ï¼Œæª¢æŸ¥æ‚¨çš„å…§æ ¸æ˜¯å¦è¢«â€œæ±¡æŸ“â€ï¼Œå› çˆ²ä½¿å…§æ ¸è¨ç½®é€™å€‹æ¨™èªŒçš„事件å¯èƒ½ 會導致您é¢è‡¨çš„å•é¡Œã€‚ * 粗略地寫下如何é‡ç¾é€™å€‹å•é¡Œã€‚如果您åŒæ™‚處ç†å¤šå€‹å•é¡Œï¼Œè«‹çˆ²æ¯å€‹å•é¡Œå–®ç¨å¯«æ³¨ 釋，並確ä¿å®ƒå€‘在新啓動的系統上ç¨ç«‹å‡ºç¾ã€‚這是必è¦çš„ï¼Œå› çˆ²æ¯å€‹å•é¡Œéƒ½éœ€è¦åˆ† åˆ¥å ±å‘Šçµ¦å…§æ ¸é–‹ç™¼äººå“¡ï¼Œé™¤éžå®ƒå€‘åš´é‡ç³¾çºåœ¨ä¸€èµ·ã€‚ - * 如果您æ£é¢è‡¨ç©©å®šç‰ˆæˆ–長期支æŒç‰ˆæœ¬ç·šçš„回æ¸ï¼ˆä¾‹å¦‚從5.10.4更新到5.10.5æ™‚å‡ºç¾ - æ•…éšœï¼‰ï¼Œè«‹æŸ¥çœ‹å¾Œæ–‡ã€Œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„回æ¸ã€å°ç¯€ã€‚ + * 如果您æ£é¢è‡¨ç©©å®šç‰ˆæˆ–長期支æŒç‰ˆæœ¬ç·šçš„è¿´æ¸ï¼ˆä¾‹å¦‚從5.10.4更新到5.10.5æ™‚å‡ºç¾ + æ•…éšœï¼‰ï¼Œè«‹æŸ¥çœ‹å¾Œæ–‡â€œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„è¿´æ¸â€å°ç¯€ã€‚ * 定ä½å¯èƒ½å¼•èµ·å•é¡Œçš„驅動程åºæˆ–å…§æ ¸åç³»çµ±ã€‚æ‰¾å‡ºå…¶é–‹ç™¼äººå“¡æœŸæœ›çš„å ±å‘Šçš„æ–¹å¼å’Œ ä½ç½®ã€‚注æ„：大多數情æ³ä¸‹ä¸æœƒæ˜¯ bugzilla.kernel.orgï¼Œå› çˆ²å•é¡Œé€šå¸¸éœ€è¦é€š @@ -105,61 +101,62 @@ 在完æˆé€™äº›æº–å‚™ä¹‹å¾Œï¼Œä½ å°‡é€²å…¥ä¸»è¦éƒ¨åˆ†ï¼š - * 除éžæ‚¨å·²ç¶“在é‹è¡Œæœ€æ–°çš„「主線ã€Linuxå…§æ ¸ï¼Œå¦å‰‡æœ€å¥½åœ¨å ±å‘Šæµç¨‹å‰å®‰è£å®ƒã€‚在æŸäº› - 情æ³ä¸‹ï¼Œä½¿ç”¨æœ€æ–°çš„「穩定版ã€Linuxé€²è¡Œæ¸¬è©¦å’Œå ±å‘Šä¹Ÿæ˜¯å¯ä»¥æŽ¥å—的替代方案；在 + * 除éžæ‚¨å·²ç¶“在é‹è¡Œæœ€æ–°çš„“主線â€Linuxå…§æ ¸ï¼Œå¦å‰‡æœ€å¥½åœ¨å ±å‘Šæµç¨‹å‰å®‰è£å®ƒã€‚在æŸäº› + 情æ³ä¸‹ï¼Œä½¿ç”¨æœ€æ–°çš„“穩定版â€Linuxé€²è¡Œæ¸¬è©¦å’Œå ±å‘Šä¹Ÿæ˜¯å¯ä»¥æŽ¥å—的替代方案；在 åˆä½µçª—å£æœŸé–“，這實際上å¯èƒ½æ˜¯æœ€å¥½çš„方法，但在開發階段最好還是暫åœå¹¾å¤©ã€‚ç„¡è«– - ä½ é¸æ“‡ä»€éº¼ç‰ˆæœ¬ï¼Œæœ€å¥½ä½¿ç”¨ã€Œæ™®é€šã€æ§‹å»ºã€‚忽略這些建è°æœƒå¤§å¤§å¢žåŠ æ‚¨çš„å ±å‘Šè¢«æ‹’çµ• + ä½ é¸æ“‡ä»€éº¼ç‰ˆæœ¬ï¼Œæœ€å¥½ä½¿ç”¨â€œæ™®é€šâ€æ§‹å»ºã€‚忽略這些建è°æœƒå¤§å¤§å¢žåŠ æ‚¨çš„å ±å‘Šè¢«æ‹’çµ• 或忽略的風險。 - * 確ä¿æ‚¨å‰›å‰›å®‰è£çš„å…§æ ¸åœ¨é‹è¡Œæ™‚ä¸æœƒã€Œæ±™æŸ“ã€è‡ªå·±ã€‚ + * 確ä¿æ‚¨å‰›å‰›å®‰è£çš„å…§æ ¸åœ¨é‹è¡Œæ™‚ä¸æœƒâ€œæ±¡æŸ“â€è‡ªå·±ã€‚ * 在您剛剛安è£çš„å…§æ ¸ä¸å¾©ç¾é€™å€‹å•é¡Œã€‚如果它沒有出ç¾ï¼Œè«‹æŸ¥çœ‹ä¸‹æ–¹åªç™¼ç”Ÿåœ¨ 穩定版和長期支æŒå…§æ ¸çš„å•é¡Œçš„說明。 - * å„ªåŒ–ä½ çš„ç†è¨˜ï¼šè©¦è‘—找到並寫出最直接的復ç¾å•é¡Œçš„方法。確ä¿æœ€çµ‚çµæžœåŒ…å«æ‰€æœ‰ + * å„ªåŒ–ä½ çš„ç†è¨˜ï¼šè©¦ç€æ‰¾åˆ°ä¸¦å¯«å‡ºæœ€ç›´æŽ¥çš„復ç¾å•é¡Œçš„方法。確ä¿æœ€çµ‚çµæžœåŒ…å«æ‰€æœ‰ é‡è¦çš„細節，åŒæ™‚讓第一次è½èªªçš„人容易閱讀和ç†è§£ã€‚如果您在æ¤éŽç¨‹ä¸å¸åˆ°äº†ä¸€ 些æ±è¥¿ï¼Œè«‹è€ƒæ…®å†æ¬¡æœç´¢é—œæ–¼è©²å•é¡Œçš„ç¾æœ‰å ±å‘Šã€‚ - * 如果失敗涉åŠã€Œpanicã€ã€ã€ŒOopsã€ã€ã€Œwarningã€æˆ–「BUGã€ï¼Œè«‹è€ƒæ…®è§£ç¢¼å…§æ ¸æ—¥èªŒä»¥æŸ¥æ‰¾è§¸ + * 如果失敗涉åŠâ€œpanicâ€ã€â€œOopsâ€ã€â€œwarningâ€æˆ–“BUGâ€ï¼Œè«‹è€ƒæ…®è§£ç¢¼å…§æ ¸æ—¥èªŒä»¥æŸ¥æ‰¾è§¸ 發錯誤的代碼行。 - * 如果您的å•é¡Œæ˜¯å›žæ¸å•é¡Œï¼Œè«‹å„˜å¯èƒ½ç¸®å°å¼•å…¥å•é¡Œæ™‚的範åœã€‚ + * 如果您的å•é¡Œæ˜¯è¿´æ¸å•é¡Œï¼Œè«‹å„˜å¯èƒ½ç¸®å°å¼•å…¥å•é¡Œæ™‚的範åœã€‚ * 通éŽè©³ç´°æè¿°å•é¡Œä¾†é–‹å§‹ç·¨å¯«å ±å‘Šã€‚記得包括以下æ¢ç›®ï¼šæ‚¨çˆ²å¾©ç¾è€Œå®‰è£çš„最新內 æ ¸ç‰ˆæœ¬ã€ä½¿ç”¨çš„Linux發行版以åŠé—œæ–¼å¦‚何復ç¾è©²å•é¡Œçš„說明。如果å¯èƒ½ï¼Œå°‡å…§æ ¸ - 構建é…置（.config）和 ``dmesg`` 的輸出放在網上的æŸå€‹åœ°æ–¹ï¼Œä¸¦é€£çµåˆ°å®ƒã€‚包 + 構建é…置（.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]ã€æ¨™è¨˜ã€‚ + <https://kernel.org/>`_ ，確ä¿æ¤ç‰¹å®šç‰ˆæœ¬ç·šçš„最新版沒有“[EOL]â€æ¨™è¨˜ã€‚ * 檢查 `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ ä¸çš„ç¾æœ‰å ±å‘Šã€‚ - * 從特定的版本線安è£æœ€æ–°ç‰ˆæœ¬ä½œçˆ²ç´”æ·¨å…§æ ¸ã€‚ç¢ºä¿é€™å€‹å…§æ ¸æ²’有被汙染，並且ä»ç„¶ - å˜åœ¨å•é¡Œï¼Œå› 爲å•é¡Œå¯èƒ½å·²ç¶“在那裡被修復了。如果您第一次發ç¾ä¾›æ‡‰å•†å…§æ ¸çš„å•é¡Œï¼Œ + * 從特定的版本線安è£æœ€æ–°ç‰ˆæœ¬ä½œçˆ²ç´”æ·¨å…§æ ¸ã€‚ç¢ºä¿é€™å€‹å…§æ ¸æ²’有被污染，並且ä»ç„¶ + å˜åœ¨å•é¡Œï¼Œå› 爲å•é¡Œå¯èƒ½å·²ç¶“在那è£è¢«ä¿®å¾©äº†ã€‚如果您第一次發ç¾ä¾›æ‡‰å•†å…§æ ¸çš„å•é¡Œï¼Œ 請檢查已知最新版本的普通構建是å¦å¯ä»¥æ£å¸¸é‹è¡Œã€‚ - * å‘Linux穩定版郵件列表發é€ä¸€å€‹ç°¡çŸçš„å•é¡Œå ±å‘Š(stable@vger.kernel.org)。大致 - æè¿°å•é¡Œï¼Œä¸¦è§£é‡‹å¦‚何復ç¾ã€‚講清楚首個出ç¾å•é¡Œçš„版本和最後一個工作æ£å¸¸çš„版本。 - 然後ç‰å¾…進一æ¥çš„指示。 + * å‘Linux穩定版郵件列表發é€ä¸€å€‹ç°¡çŸçš„å•é¡Œå ±å‘Šï¼ˆstable@vger.kernel.orgï¼‰ä¸¦æŠ„é€ + Linuxè¿´æ¸éƒµä»¶åˆ—表（regressions@lists.linux.devï¼‰ï¼›å¦‚æžœä½ æ‡·ç–‘æ˜¯ç”±æŸå系統 + 引起的，請抄é€å…¶ç¶è·äººå“¡å’Œå系統郵件列表。大致æè¿°å•é¡Œï¼Œä¸¦è§£é‡‹å¦‚何復ç¾ã€‚ + 講清楚首個出ç¾å•é¡Œçš„版本和最後一個工作æ£å¸¸çš„版本。然後ç‰å¾…進一æ¥çš„指示。 下é¢çš„åƒè€ƒç« 節部分詳細解釋了這些æ¥é©Ÿä¸çš„æ¯ä¸€æ¥ã€‚ @@ -167,14 +164,14 @@ å ±å‘Šåªç™¼ç”Ÿåœ¨è¼ƒèˆŠå…§æ ¸ç‰ˆæœ¬ç·šçš„å•é¡Œ ---------------------------------- -è‹¥æ‚¨å˜—è©¦äº†ä¸Šè¿°çš„æœ€æ–°ä¸»ç·šå…§æ ¸ï¼Œä½†æœªèƒ½åœ¨é‚£è£¡å¾©ç¾å•é¡Œï¼Œé‚£éº¼æœ¬å°ç¯€é©ç”¨æ–¼æ‚¨ï¼›ä»¥ä¸‹ +è‹¥æ‚¨å˜—è©¦äº†ä¸Šè¿°çš„æœ€æ–°ä¸»ç·šå…§æ ¸ï¼Œä½†æœªèƒ½åœ¨é‚£è£å¾©ç¾å•é¡Œï¼Œé‚£éº¼æœ¬å°ç¯€é©ç”¨æ–¼æ‚¨ï¼›ä»¥ä¸‹ æµç¨‹æœ‰åŠ©æ–¼ä½¿å•é¡Œåœ¨ä»ç„¶æ”¯æŒçš„穩定版或長期支æŒç‰ˆæœ¬ç·šï¼Œæˆ–者定期基於最新穩定版或 長期支æŒå…§æ ¸çš„ä¾›æ‡‰å•†å…§æ ¸ä¸å¾—到修復。如果是這種情æ³ï¼Œè«‹åŸ·è¡Œä»¥ä¸‹æ¥é©Ÿï¼š * è«‹åšå¥½æº–備，接下來的幾個æ¥é©Ÿå¯èƒ½ç„¡æ³•åœ¨èˆŠç‰ˆæœ¬ä¸è§£æ±ºå•é¡Œï¼šä¿®å¾©å¯èƒ½å¤ªå¤§æˆ–太 - 冒險，無法移æ¤åˆ°é‚£è£¡ã€‚ + 冒險，無法移æ¤åˆ°é‚£è£ã€‚ - * 執行å‰ç¯€ã€Œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„回æ¸ã€ä¸çš„å‰ä¸‰å€‹æ¥é©Ÿã€‚ + * 執行å‰ç¯€â€œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„è¿´æ¸â€ä¸çš„å‰ä¸‰å€‹æ¥é©Ÿã€‚ * 在Linuxå…§æ ¸ç‰ˆæœ¬æŽ§åˆ¶ç³»çµ±ä¸æœç´¢ä¿®å¾©ä¸»ç·šå•é¡Œçš„æ›´æ”¹ï¼Œå› çˆ²å®ƒçš„æ交消æ¯å¯èƒ½æœƒ å‘Šè¨´ä½ ä¿®å¾©æ˜¯å¦å·²ç¶“計劃好了支æŒã€‚å¦‚æžœä½ æ²’æœ‰æ‰¾åˆ°ï¼Œæœç´¢é©ç•¶çš„郵件列表，尋找 @@ -219,14 +216,14 @@ 確ä¿æ‚¨ä½¿ç”¨çš„是上游Linuxå…§æ ¸ ---------------------------- - *您是å¦é¢è‡¨ç¡¬é«”或軟體供應商æ供的Linuxå…§æ ¸çš„å•é¡Œï¼Ÿé‚£éº¼åŸºæœ¬ä¸Šæ‚¨æœ€å¥½åœæ¢é–± + *您是å¦é¢è‡¨ç¡¬ä»¶æˆ–軟件供應商æ供的Linuxå…§æ ¸çš„å•é¡Œï¼Ÿé‚£éº¼åŸºæœ¬ä¸Šæ‚¨æœ€å¥½åœæ¢é–± 讀本文檔，轉而å‘æ‚¨çš„ä¾›æ‡‰å•†å ±å‘Šå•é¡Œï¼Œé™¤éžæ‚¨é¡˜æ„自己安è£æœ€æ–°çš„Linux版本。 尋找和解決å•é¡Œå¾€å¾€éœ€è¦å¾Œè€…。* -與大多數程å¼è¨è¨ˆå¸«ä¸€æ¨£ï¼ŒLinuxå…§æ ¸é–‹ç™¼äººå“¡ä¸å–œæ¡èŠ±æ™‚間處ç†ä»–們ç¶è·çš„原始碼ä¸æ ¹æœ¬ -ä¸æœƒç™¼ç”Ÿçš„å•é¡Œçš„å ±å‘Šã€‚é€™åªæœƒæµªè²»æ¯å€‹äººçš„æ™‚é–“ï¼Œå°¤å…¶æ˜¯ä½ çš„æ™‚é–“ã€‚ä¸å¹¸çš„是，當 +與大多數程åºå“¡ä¸€æ¨£ï¼ŒLinuxå…§æ ¸é–‹ç™¼äººå“¡ä¸å–œæ¡èŠ±æ™‚間處ç†ä»–們ç¶è·çš„æºä»£ç¢¼ä¸æ ¹æœ¬ +ä¸æœƒç™¼ç”Ÿçš„å•é¡Œçš„å ±å‘Šã€‚é€™éš»æœƒæµªè²»æ¯å€‹äººçš„æ™‚é–“ï¼Œå°¤å…¶æ˜¯ä½ çš„æ™‚é–“ã€‚ä¸å¹¸çš„是，當 涉åŠåˆ°å…§æ ¸æ™‚，這樣的情æ³å¾ˆå®¹æ˜“ç™¼ç”Ÿï¼Œä¸¦ä¸”å¸¸å¸¸å°Žè‡´é›™æ–¹æ°£é¤’ã€‚é€™æ˜¯å› çˆ²å¹¾ä¹Žæ‰€æœ‰é -è£åœ¨è¨å‚™ï¼ˆå°å¼æ©Ÿã€ç†è¨˜æœ¬é›»è…¦ã€æ™ºæ…§åž‹æ‰‹æ©Ÿã€è·¯ç”±å™¨ç‰ï¼‰ä¸Šçš„Linuxå…§æ ¸ï¼Œä»¥åŠå¤§å¤šæ•¸ +è£åœ¨è¨å‚™ï¼ˆè‡ºå¼æ©Ÿã€ç†è¨˜æœ¬é›»è…¦ã€æ™ºèƒ½æ‰‹æ©Ÿã€è·¯ç”±å™¨ç‰ï¼‰ä¸Šçš„Linuxå…§æ ¸ï¼Œä»¥åŠå¤§å¤šæ•¸ ç”±Linux發行商æä¾›çš„å…§æ ¸ï¼Œéƒ½èˆ‡ç”±kernel.org發行的官方Linuxå…§æ ¸ç›¸è·ç”šé ：從Linux 開發的角度來看，這些供應商æä¾›çš„å…§æ ¸é€šå¸¸æ˜¯å¤è€çš„或者經éŽäº†å¤§é‡ä¿®æ”¹ï¼Œé€šå¸¸å…©é»ž 兼具。 @@ -235,19 +232,19 @@ å¯èƒ½å·²ç¶“ç”±Linuxå…§æ ¸é–‹ç™¼äººå“¡åœ¨æ•¸æœˆæˆ–æ•¸å¹´å‰ä¿®å¾©ï¼›æ¤å¤–，供應商的修改和增強å¯èƒ½ 會導致您é¢è‡¨çš„å•é¡Œï¼Œå³ä½¿å®ƒå€‘看起來很å°æˆ–者完全ä¸ç›¸é—œã€‚é€™å°±æ˜¯çˆ²ä»€éº¼æ‚¨æ‡‰è©²å‘ ä¾›æ‡‰å•†å ±å‘Šé€™äº›å…§æ ¸çš„å•é¡Œã€‚å®ƒçš„é–‹ç™¼è€…æ‡‰è©²æŸ¥çœ‹å ±å‘Šï¼Œå¦‚æžœå®ƒæ˜¯ä¸€å€‹ä¸Šæ¸¸å•é¡Œï¼Œç›´æŽ¥ -æ–¼ä¸Šæ¸¸ä¿®å¾©æˆ–å°‡å ±å‘Šè½‰ç™¼åˆ°é‚£è£¡ã€‚åœ¨å¯¦è¸ä¸ï¼Œé€™æœ‰æ™‚è¡Œä¸é€šã€‚å› æ¤ï¼Œæ‚¨å¯èƒ½éœ€è¦è€ƒæ…® +æ–¼ä¸Šæ¸¸ä¿®å¾©æˆ–å°‡å ±å‘Šè½‰ç™¼åˆ°é‚£è£ã€‚在實è¸ä¸ï¼Œé€™æœ‰æ™‚è¡Œä¸é€šã€‚å› æ¤ï¼Œæ‚¨å¯èƒ½éœ€è¦è€ƒæ…® 通éŽè‡ªå·±å®‰è£æœ€æ–°çš„Linuxå…§æ ¸å…§æ ¸ä¾†ç¹žéŽä¾›æ‡‰å•†ã€‚如果如果您é¸æ“‡æ¤æ–¹æ³•ï¼Œé‚£éº¼æœ¬æŒ‡ å—後é¢çš„æ¥é©Ÿå°‡è§£é‡‹å¦‚何在排除了其他å¯èƒ½å°Žè‡´æ‚¨çš„å•é¡Œçš„åŽŸå› å¾ŒåŸ·è¡Œæ¤æ“作。 -注æ„å‰æ®µä½¿ç”¨çš„詞語是「大多數ã€ï¼Œå› 爲有時候開發人員實際上願æ„處ç†ä¾›æ‡‰å•†å…§æ ¸å‡ºç¾ +注æ„å‰æ®µä½¿ç”¨çš„詞語是“大多數â€ï¼Œå› 爲有時候開發人員實際上願æ„處ç†ä¾›æ‡‰å•†å…§æ ¸å‡ºç¾ çš„å•é¡Œå ±å‘Šã€‚他們是å¦é€™éº¼åšå¾ˆå¤§ç¨‹åº¦ä¸Šå–決於開發人員和相關å•é¡Œã€‚å¦‚æžœç™¼è¡Œç‰ˆåª æ ¹æ“šæœ€è¿‘çš„Linux版本å°å…§æ ¸é€²è¡Œäº†è¼ƒå°ä¿®æ”¹ï¼Œé‚£éº¼æ©Ÿæœƒå°±æ¯”較大；例如å°æ–¼Debian GNU/Linux Sid或Fedora Rawhide所æä¾›çš„ä¸»ç·šå…§æ ¸ã€‚ä¸€äº›é–‹ç™¼äººå“¡é‚„å°‡æŽ¥å—基於最新 ç©©å®šå…§æ ¸çš„ç™¼è¡Œç‰ˆå…§æ ¸å•é¡Œå ±å‘Šï¼Œåªè¦å®ƒæ”¹å‹•ä¸å¤§ï¼›ä¾‹å¦‚Arch Linuxã€å¸¸è¦Fedora版本 å’ŒopenSUSE Turboweed。但是請記ä½ï¼Œæ‚¨æœ€å¥½ä½¿ç”¨ä¸»ç·šLinux，並é¿å…在æ¤æµç¨‹ä¸ä½¿ç”¨ -ç©©å®šç‰ˆå…§æ ¸ï¼Œå¦‚ã€Œå®‰è£ä¸€å€‹æ–°çš„å…§æ ¸é€²è¡Œæ¸¬è©¦ã€ä¸€ç¯€ä¸æ‰€è©³è¿°ã€‚ +ç©©å®šç‰ˆå…§æ ¸ï¼Œå¦‚â€œå®‰è£ä¸€å€‹æ–°çš„å…§æ ¸é€²è¡Œæ¸¬è©¦â€ä¸€ç¯€ä¸æ‰€è©³è¿°ã€‚ -當然，您å¯ä»¥å¿½ç•¥æ‰€æœ‰é€™äº›å»ºè°ï¼Œä¸¦å‘上游Linuxé–‹ç™¼äººå“¡å ±å‘ŠèˆŠçš„æˆ–ç¶“éŽå¤§é‡ä¿®æ”¹çš„ +當然，您å¯ä»¥å¿½ç•¥æ‰€æœ‰é€™äº›å»ºè°ï¼Œä¸¦å‘上éŠLinuxé–‹ç™¼äººå“¡å ±å‘ŠèˆŠçš„æˆ–ç¶“éŽå¤§é‡ä¿®æ”¹çš„ ä¾›æ‡‰å•†å…§æ ¸çš„å•é¡Œã€‚但是注æ„ï¼Œé€™æ¨£çš„å ±å‘Šç¶“å¸¸è¢«æ‹’çµ•æˆ–å¿½è¦–ï¼Œæ‰€ä»¥è‡ªè¡Œå°å¿ƒè€ƒæ…®ä¸€ä¸‹ã€‚ ä¸éŽé€™é‚„æ˜¯æ¯”æ ¹æœ¬ä¸å ±å‘Šå•é¡Œè¦å¥½ï¼šæœ‰æ™‚å€™é€™æ¨£çš„å ±å‘Šæœƒç›´æŽ¥æˆ–é–“æŽ¥åœ°å¹«åŠ©è§£æ±ºä¹‹å¾Œçš„ å•é¡Œã€‚ @@ -256,64 +253,61 @@ GNU/Linux Sid或Fedora Rawhide所æä¾›çš„ä¸»ç·šå…§æ ¸ã€‚ä¸€äº›é–‹ç™¼äººå“¡é‚„å° æœç´¢ç¾æœ‰å ±å‘Šï¼ˆç¬¬ä¸€éƒ¨åˆ†ï¼‰ ------------------------- - *使用您喜愛的網絡æœå°‹å¼•æ“Žå°ç¾æœ‰å ±å‘Šé€²è¡Œç²—ç•¥æœç´¢ï¼›æ¤å¤–，請檢查Linuxå…§æ ¸ + *使用您喜愛的網絡æœç´¢å¼•æ“Žå°ç¾æœ‰å ±å‘Šé€²è¡Œç²—ç•¥æœç´¢ï¼›æ¤å¤–，請檢查Linuxå…§æ ¸ 郵件列表（LKML）的å˜æª”。如果找到匹é…çš„å ±å‘Šï¼Œè«‹åŠ å…¥è¨Žè«–è€Œä¸æ˜¯ç™¼é€æ–°å ±å‘Šã€‚* å ±å‘Šä¸€å€‹åˆ¥äººå·²ç¶“æ出的å•é¡Œï¼Œå°æ¯å€‹äººä¾†èªªéƒ½æ˜¯æµªè²»æ™‚é–“ï¼Œå°¤å…¶æ˜¯ä½œçˆ²å ±å‘Šäººçš„ä½ ã€‚ 所以徹底檢查是å¦æœ‰äººå·²ç¶“å ±å‘Šäº†é€™å€‹å•é¡Œï¼Œé€™å°ä½ 自己是有利的。在æµç¨‹ä¸çš„這一æ¥ï¼Œ -å¯ä»¥åªåŸ·è¡Œä¸€å€‹ç²—略的æœç´¢ï¼šä¸€æ—¦æ‚¨çŸ¥é“您的å•é¡Œéœ€è¦å ±å‘Šåˆ°å“ªè£¡ï¼Œç¨å¾Œçš„æ¥é©Ÿå°‡å‘Šè¨´ +å¯ä»¥åªåŸ·è¡Œä¸€å€‹ç²—略的æœç´¢ï¼šä¸€æ—¦æ‚¨çŸ¥é“您的å•é¡Œéœ€è¦å ±å‘Šåˆ°å“ªè£ï¼Œç¨å¾Œçš„æ¥é©Ÿå°‡å‘Šè¨´ 您如何詳細æœç´¢ã€‚儘管如æ¤ï¼Œä¸è¦å€‰ä¿ƒå®Œæˆé€™ä¸€æ¥ï¼Œå®ƒå¯ä»¥ç¯€çœæ‚¨çš„時間和減少麻煩。 -åªéœ€å…ˆç”¨ä½ 最喜æ¡çš„æœå°‹å¼•æ“Žåœ¨ç¶²éš›ç¶²è·¯ä¸Šæœç´¢ã€‚然後å†æœç´¢Linuxå…§æ ¸éƒµä»¶åˆ—è¡¨ï¼ˆLKML） +åªéœ€å…ˆç”¨ä½ 最喜æ¡çš„æœç´¢å¼•æ“Žåœ¨äº’è¯ç¶²ä¸Šæœç´¢ã€‚然後å†æœç´¢Linuxå…§æ ¸éƒµä»¶åˆ—è¡¨ï¼ˆLKML） å˜æª”。 -如果æœç´¢çµæžœå¯¦åœ¨å¤ªå¤šï¼Œå¯ä»¥è€ƒæ…®è®“ä½ çš„æœå°‹å¼•æ“Žå°‡æœç´¢æ™‚間範åœé™åˆ¶åœ¨éŽåŽ»çš„一個 -æœˆæˆ–ä¸€å¹´ã€‚è€Œä¸”ç„¡è«–ä½ åœ¨å“ªè£¡æœç´¢ï¼Œä¸€å®šè¦ç”¨æ°ç•¶çš„æœç´¢é—œéµè©žï¼›ä¹Ÿè¦è®ŠåŒ–å¹¾æ¬¡é—œéµ -詞。åŒæ™‚，試著從別人的角度看å•é¡Œï¼šé€™å°‡å¹«åŠ©ä½ 想出其他的關éµè©žã€‚å¦å¤–ï¼Œä¸€å®šä¸ +如果æœç´¢çµæžœå¯¦åœ¨å¤ªå¤šï¼Œå¯ä»¥è€ƒæ…®è®“ä½ çš„æœç´¢å¼•æ“Žå°‡æœç´¢æ™‚間範åœé™åˆ¶åœ¨éŽåŽ»çš„一個 +æœˆæˆ–ä¸€å¹´ã€‚è€Œä¸”ç„¡è«–ä½ åœ¨å“ªè£æœç´¢ï¼Œä¸€å®šè¦ç”¨æ°ç•¶çš„æœç´¢é—œéµè©žï¼›ä¹Ÿè¦è®ŠåŒ–å¹¾æ¬¡é—œéµ +詞。åŒæ™‚，試ç€å¾žåˆ¥äººçš„角度看å•é¡Œï¼šé€™å°‡å¹«åŠ©ä½ 想出其他的關éµè©žã€‚å¦å¤–ï¼Œä¸€å®šä¸ è¦åŒæ™‚使用éŽå¤šçš„é—œéµè©žã€‚記ä½æœç´¢æ™‚è¦åŒæ™‚嘗試包å«å’Œä¸åŒ…å«å…§æ ¸é©…動程åºçš„å稱 -或å—影響的硬體組件的å稱ç‰ä¿¡æ¯ã€‚但其確切的å“牌å稱（比如說「è¯ç¢©ç´…é” Radeon -RX 5700 XT Gaming OCã€ï¼‰å¾€å¾€å¹«åŠ©ä¸å¤§ï¼Œå› 爲它太具體了。相å，嘗試æœç´¢è¡“語，如 -型號（Radeon 5700 或 Radeon 5000ï¼‰å’Œæ ¸å¿ƒä»£è™Ÿï¼ˆã€ŒNaviã€æˆ–「Navi10ã€ï¼‰ï¼Œä»¥åŠåŒ…å« -å’Œä¸åŒ…å«å…¶è£½é€ 商（「AMDã€ï¼‰ã€‚ +或å—影響的硬件組件的å稱ç‰ä¿¡æ¯ã€‚但其確切的å“牌å稱（比如說“è¯ç¢©ç´…é” 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）發生ä¸å…¼å®¹çš„æ›´æ”¹é€ æˆçš„。顯著 -的性能é™ä½Žæˆ–åŠŸè€—å¢žåŠ ä¹Ÿå¯ä»¥ç¨±çˆ²å›žæ¸ã€‚但是請記ä½:æ–°å…§æ ¸éœ€è¦ä½¿ç”¨èˆ‡èˆŠå…§æ ¸ç›¸ä¼¼çš„ -é…置來構建（åƒè¦‹ä¸‹é¢å¦‚何實ç¾é€™ä¸€é»žï¼‰ã€‚é€™æ˜¯å› çˆ²å…§æ ¸é–‹ç™¼äººå“¡åœ¨å¯¦ç¾æ–°ç‰¹æ€§æ™‚有 -時無法é¿å…ä¸å…¼å®¹æ€§ï¼›ä½†æ˜¯çˆ²äº†é¿å…回æ¸ï¼Œé€™äº›ç‰¹æ€§å¿…é ˆåœ¨æ§‹å»ºé…置期間顯å¼åœ°å•“用。 +如果æŸå€‹æ‡‰ç”¨ç¨‹åºæˆ–實際用例在原先的Linuxå…§æ ¸ä¸Šé‹è¡Œè‰¯å¥½ï¼Œä½†åœ¨ä½¿ç”¨é¡žä¼¼é…置編è¯çš„ +較新版本上效果更差ã€æˆ–è€…æ ¹æœ¬ä¸èƒ½ç”¨ï¼Œé‚£éº¼ä½ 就需è¦è™•ç†è¿´æ¸å•é¡Œã€‚ +Documentation/admin-guide/reporting-regressions.rst å°æ¤é€²è¡Œäº†æ›´è©³ç´°çš„解釋。 +它還æä¾›äº†å¾ˆå¤šä½ å¯èƒ½æƒ³çŸ¥é“的關於迴æ¸çš„其他信æ¯ï¼›ä¾‹å¦‚，它解釋çžå¦‚何將您的å•é¡Œ +æ·»åŠ åˆ°è¿´æ¸è·Ÿè¹¤åˆ—表ä¸ï¼Œä»¥ç¢ºä¿å®ƒä¸æœƒè¢«å¿½ç•¥ã€‚ 什麼是安全å•é¡Œç•™çµ¦æ‚¨è‡ªå·±åˆ¤æ–·ã€‚在繼續之å‰ï¼Œè«‹è€ƒæ…®é–±è®€ -「Documentation/translations/zh_TW/admin-guide/security-bugs.rstã€ï¼Œ -å› çˆ²å®ƒæ供了如何最æ°ç•¶åœ°è™•ç†å®‰å…¨å•é¡Œçš„é¡å¤–細節。 +Documentation/translations/zh_CN/admin-guide/security-bugs.rst ， +å› çˆ²å®ƒæä¾›çžå¦‚何最æ°ç•¶åœ°è™•ç†å®‰å…¨å•é¡Œçš„é¡å¤–細節。 -當發生了完全無法接å—的糟糕事情時，æ¤å•é¡Œå°±æ˜¯ä¸€å€‹ã€Œéžå¸¸åš´é‡çš„å•é¡Œã€ã€‚例如， -Linuxå…§æ ¸ç ´å£žäº†å®ƒè™•ç†çš„數據或æ壞了它é‹è¡Œçš„ç¡¬é«”ã€‚ç•¶å…§æ ¸çªç„¶é¡¯ç¤ºéŒ¯èª¤æ¶ˆæ¯ -（「kernel panicã€ï¼‰ä¸¦åœæ¢å·¥ä½œï¼Œæˆ–è€…æ ¹æœ¬æ²’æœ‰ä»»ä½•åœæ¢ä¿¡æ¯æ™‚，您也在處ç†ä¸€å€‹åš´é‡ -çš„å•é¡Œã€‚注æ„：ä¸è¦æ··æ·†ã€Œpanicã€ï¼ˆå…§æ ¸åœæ¢è‡ªèº«çš„致命錯誤）和「Oopsã€ï¼ˆå¯æ¢å¾©éŒ¯èª¤ï¼‰ï¼Œ +當發生了完全無法接å—的糟糕事情時，æ¤å•é¡Œå°±æ˜¯ä¸€å€‹â€œéžå¸¸åš´é‡çš„å•é¡Œâ€ã€‚例如， +Linuxå…§æ ¸ç ´å£žäº†å®ƒè™•ç†çš„數據或æ壞了它é‹è¡Œçš„ç¡¬ä»¶ã€‚ç•¶å…§æ ¸çªç„¶é¡¯ç¤ºéŒ¯èª¤æ¶ˆæ¯ +（“kernel panicâ€ï¼‰ä¸¦åœæ¢å·¥ä½œï¼Œæˆ–è€…æ ¹æœ¬æ²’æœ‰ä»»ä½•åœæ¢ä¿¡æ¯æ™‚，您也在處ç†ä¸€å€‹åš´é‡ +çš„å•é¡Œã€‚注æ„：ä¸è¦æ··æ·†â€œpanicâ€ï¼ˆå…§æ ¸åœæ¢è‡ªèº«çš„致命錯誤）和“Oopsâ€ï¼ˆå¯æ¢å¾©éŒ¯èª¤ï¼‰ï¼Œ å› çˆ²é¡¯ç¤ºå¾Œè€…ä¹‹å¾Œå…§æ ¸ä»ç„¶åœ¨é‹è¡Œã€‚ @@ -325,22 +319,22 @@ Linuxå…§æ ¸ç ´å£žäº†å®ƒè™•ç†çš„數據或æ壞了它é‹è¡Œçš„ç¡¬é«”ã€‚ç•¶å…§æ ¸ 看起來很åƒå…§æ ¸å•é¡Œçš„å•é¡Œæœ‰æ™‚是由構建或é‹è¡Œæ™‚ç’°å¢ƒå¼•èµ·çš„ã€‚å¾ˆé›£å®Œå…¨æŽ’é™¤é€™ç¨®å• é¡Œï¼Œä½†ä½ æ‡‰è©²å„˜é‡æ¸›å°‘這種å•é¡Œï¼š - * æ§‹å»ºå…§æ ¸æ™‚ï¼Œè«‹ä½¿ç”¨ç¶“éŽé©—è‰çš„å·¥å…·ï¼Œå› çˆ²ç·¨è¯å™¨æˆ–二進ä½æ–‡ä»¶ä¸çš„錯誤å¯èƒ½æœƒå°Ž + * æ§‹å»ºå…§æ ¸æ™‚ï¼Œè«‹ä½¿ç”¨ç¶“éŽé©—è‰çš„å·¥å…·ï¼Œå› çˆ²ç·¨è¯å™¨æˆ–二進制文件ä¸çš„錯誤å¯èƒ½æœƒå°Ž è‡´å…§æ ¸å‡ºç¾éŒ¯èª¤è¡Œçˆ²ã€‚ * 確ä¿æ‚¨çš„計算機組件在其è¨è¨ˆè¦ç¯„å…§é‹è¡Œï¼›é€™å°è™•ç†å™¨ã€å…§å˜å’Œä¸»æ¿å°¤çˆ²é‡è¦ã€‚å› æ¤ï¼Œç•¶é¢è‡¨æ½›åœ¨çš„å…§æ ¸å•é¡Œæ™‚，åœæ¢ä½Žé›»å£“æˆ–è¶…é »ã€‚ - * 儘é‡ç¢ºä¿ä¸æ˜¯ç¡¬é«”æ•…éšœå°Žè‡´äº†ä½ çš„å•é¡Œã€‚例如，內å˜æ壞會導致大é‡çš„å•é¡Œï¼Œé€™äº› + * 儘é‡ç¢ºä¿ä¸æ˜¯ç¡¬ä»¶æ•…éšœå°Žè‡´äº†ä½ çš„å•é¡Œã€‚例如，內å˜æ壞會導致大é‡çš„å•é¡Œï¼Œé€™äº› å•é¡Œæœƒè¡¨ç¾çˆ²çœ‹èµ·ä¾†åƒå…§æ ¸å•é¡Œã€‚ * å¦‚æžœä½ æ£åœ¨è™•ç†ä¸€å€‹æ–‡ä»¶ç³»çµ±å•é¡Œï¼Œä½ å¯èƒ½éœ€è¦ç”¨ ``fsck`` 檢查一下文件系統， å› çˆ²å®ƒå¯èƒ½æœƒä»¥æŸç¨®æ–¹å¼è¢«æ壞，從而導致無法é æœŸçš„å…§æ ¸è¡Œçˆ²ã€‚ - * 在處ç†å›žæ¸å•é¡Œæ™‚，è¦ç¢ºä¿æ²’æœ‰åœ¨æ›´æ–°å…§æ ¸çš„åŒæ™‚ç™¼ç”Ÿäº†å…¶ä»–è®ŠåŒ–ã€‚ä¾‹å¦‚ï¼Œé€™å€‹å• - é¡Œå¯èƒ½æ˜¯ç”±åŒæ™‚更新的其他軟體引起的。也有å¯èƒ½æ˜¯åœ¨ä½ 第一次é‡å•“é€²å…¥æ–°å…§æ ¸æ™‚ï¼Œ - æŸå€‹ç¡¬é«”å·§åˆåœ°å£žäº†ã€‚更新系統 BIOS 或改變 BIOS è¨ç½®ä¸çš„æŸäº›å…§å®¹ä¹Ÿæœƒå°Žè‡´ - 一些看起來很åƒå…§æ ¸å›žæ¸çš„å•é¡Œã€‚ + * 在處ç†è¿´æ¸å•é¡Œæ™‚，è¦ç¢ºä¿æ²’æœ‰åœ¨æ›´æ–°å…§æ ¸çš„åŒæ™‚ç™¼ç”Ÿäº†å…¶ä»–è®ŠåŒ–ã€‚ä¾‹å¦‚ï¼Œé€™å€‹å• + é¡Œå¯èƒ½æ˜¯ç”±åŒæ™‚更新的其他軟件引起的。也有å¯èƒ½æ˜¯åœ¨ä½ 第一次é‡å•“é€²å…¥æ–°å…§æ ¸æ™‚ï¼Œ + æŸå€‹ç¡¬ä»¶å·§åˆåœ°å£žäº†ã€‚更新系統 BIOS 或改變 BIOS è¨ç½®ä¸çš„æŸäº›å…§å®¹ä¹Ÿæœƒå°Žè‡´ + 一些看起來很åƒå…§æ ¸è¿´æ¸çš„å•é¡Œã€‚ 爲緊急情æ³åšå¥½æº–å‚™ @@ -349,8 +343,8 @@ Linuxå…§æ ¸ç ´å£žäº†å®ƒè™•ç†çš„數據或æ壞了它é‹è¡Œçš„ç¡¬é«”ã€‚ç•¶å…§æ ¸ *創建一個全新的備份，並將系統修復和還原工具放在手邊* 我得æ醒您，您æ£åœ¨å’Œè¨ˆç®—機打交é“，計算機有時會出ç¾æ„想ä¸åˆ°çš„事情，尤其是當 -您折騰其作æ¥ç³»çµ±çš„å…§æ ¸ç‰é—œéµéƒ¨ä»¶æ™‚ã€‚è€Œé€™å°±æ˜¯ä½ åœ¨é€™å€‹éŽç¨‹ä¸è¦åšçš„äº‹æƒ…ã€‚å› æ¤ï¼Œ -一定è¦å‰µå»ºä¸€å€‹å…¨æ–°çš„備份；還è¦ç¢ºä¿ä½ 手é 有修復或é‡è£ä½œæ¥ç³»çµ±çš„所有工具， +您折騰其æ“ä½œç³»çµ±çš„å…§æ ¸ç‰é—œéµéƒ¨ä»¶æ™‚ã€‚è€Œé€™å°±æ˜¯ä½ åœ¨é€™å€‹éŽç¨‹ä¸è¦åšçš„äº‹æƒ…ã€‚å› æ¤ï¼Œ +一定è¦å‰µå»ºä¸€å€‹å…¨æ–°çš„備份；還è¦ç¢ºä¿ä½ 手é 有修復或é‡è£æ“作系統的所有工具， 以åŠæ¢å¾©å‚™ä»½æ‰€éœ€çš„一切。 @@ -366,67 +360,67 @@ Linuxå…§æ ¸ç ´å£žäº†å®ƒè™•ç†çš„數據或æ壞了它é‹è¡Œçš„ç¡¬é«”ã€‚ç•¶å…§æ ¸ 的任何模塊。然後é‡æ–°å•“å‹•å†ç¹¼çºŒã€‚ 注æ„ï¼Œä½ å¯èƒ½ä¸çŸ¥é“ä½ çš„ç³»çµ±æ£åœ¨ä½¿ç”¨é€™äº›è§£æ±ºæ–¹æ¡ˆä¹‹ä¸€ï¼šç•¶ä½ å®‰è£ Nvidia 專有圖 -形驅動程åºã€VirtualBox æˆ–å…¶ä»–éœ€è¦ Linux å…§æ ¸ä»¥å¤–çš„æ¨¡å¡Šæ”¯æŒçš„軟體時，它們通 -常會éœé»˜è¨ç½®ã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ å¯èƒ½éœ€è¦å¸è¼‰é€™äº›è»Ÿé«”的軟體包，以擺脫任何第三方 +形驅動程åºã€VirtualBox æˆ–å…¶ä»–éœ€è¦ Linux å…§æ ¸ä»¥å¤–çš„æ¨¡å¡Šæ”¯æŒçš„軟件時，它們通 +常會éœé»˜è¨ç½®ã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ å¯èƒ½éœ€è¦å¸è¼‰é€™äº›è»Ÿä»¶çš„軟件包，以擺脫任何第三方 å…§æ ¸æ¨¡å¡Šã€‚ -檢測「汙染ã€æ¨™èªŒ +檢查“污染â€æ¨™èªŒ ---------------- - *當å•é¡Œç™¼ç”Ÿæ™‚ï¼Œæª¢æŸ¥æ‚¨çš„å…§æ ¸æ˜¯å¦è¢«ã€Œæ±™æŸ“ã€ï¼Œå› çˆ²ä½¿å…§æ ¸è¨ç½®é€™å€‹æ¨™èªŒçš„äº‹ä»¶å¯ + *當å•é¡Œç™¼ç”Ÿæ™‚ï¼Œæª¢æŸ¥æ‚¨çš„å…§æ ¸æ˜¯å¦è¢«â€œæ±¡æŸ“â€ï¼Œå› çˆ²ä½¿å…§æ ¸è¨ç½®é€™å€‹æ¨™èªŒçš„äº‹ä»¶å¯ èƒ½æœƒå°Žè‡´æ‚¨é¢è‡¨çš„å•é¡Œã€‚* -當æŸäº›å¯èƒ½æœƒå°Žè‡´çœ‹èµ·ä¾†å®Œå…¨ä¸ç›¸é—œçš„å¾ŒçºŒéŒ¯èª¤çš„äº‹æƒ…ç™¼ç”Ÿæ™‚ï¼Œå…§æ ¸æœƒç”¨ã€Œæ±™æŸ“ -（taint）ã€æ¨™èªŒæ¨™è¨˜è‡ªå·±ã€‚å¦‚æžœæ‚¨çš„å…§æ ¸å—到汙染，那麼您é¢è‡¨çš„å¯èƒ½æ˜¯é€™æ¨£çš„錯誤。 +當æŸäº›å¯èƒ½æœƒå°Žè‡´çœ‹èµ·ä¾†å®Œå…¨ä¸ç›¸é—œçš„å¾ŒçºŒéŒ¯èª¤çš„äº‹æƒ…ç™¼ç”Ÿæ™‚ï¼Œå…§æ ¸æœƒç”¨â€œæ±¡æŸ“ +（taint）â€æ¨™èªŒæ¨™è¨˜è‡ªå·±ã€‚å¦‚æžœæ‚¨çš„å…§æ ¸å—到污染，那麼您é¢è‡¨çš„å¯èƒ½æ˜¯é€™æ¨£çš„錯誤。 å› æ¤åœ¨æŠ•å…¥æ›´å¤šæ™‚間到這個éŽç¨‹ä¸ä¹‹å‰ï¼Œå„˜æ—©æŽ’除æ¤æƒ…æ³å¯èƒ½å°ä½ 有好處。這是這個 -æ¥é©Ÿå‡ºç¾åœ¨é€™è£¡çš„å”¯ä¸€åŽŸå› ï¼Œå› çˆ²é€™å€‹éŽç¨‹ç¨å¾Œæœƒå‘Šè¨´æ‚¨å®‰è£æœ€æ–°çš„ä¸»ç·šå…§æ ¸ï¼›ç„¶å¾Œ -您將需è¦å†æ¬¡æª¢æŸ¥æ±™æŸ“æ¨™èªŒï¼Œå› çˆ²ç•¶å®ƒå‡ºå•é¡Œçš„æ™‚å€™å…§æ ¸å ±å‘Šæœƒé—œæ³¨å®ƒã€‚ +æ¥é©Ÿå‡ºç¾åœ¨é€™è£çš„å”¯ä¸€åŽŸå› ï¼Œå› çˆ²é€™å€‹éŽç¨‹ç¨å¾Œæœƒå‘Šè¨´æ‚¨å®‰è£æœ€æ–°çš„ä¸»ç·šå…§æ ¸ï¼›ç„¶å¾Œ +您將需è¦å†æ¬¡æª¢æŸ¥æ±¡æŸ“æ¨™èªŒï¼Œå› çˆ²ç•¶å®ƒå‡ºå•é¡Œçš„æ™‚å€™å…§æ ¸å ±å‘Šæœƒé—œæ³¨å®ƒã€‚ -在æ£åœ¨é‹è¡Œçš„ç³»çµ±ä¸Šæª¢æŸ¥å…§æ ¸æ˜¯å¦æ±™æŸ“éžå¸¸å®¹æ˜“：如果 ``cat /proc/sys/kernel/tainted`` -返回「0ã€ï¼Œé‚£éº¼å…§æ ¸æ²’有被汙染，一切æ£å¸¸ã€‚在æŸäº›æƒ…æ³ä¸‹ç„¡æ³•æª¢æŸ¥è©²æ–‡ä»¶ï¼›é€™å°±æ˜¯ -çˆ²ä»€éº¼ç•¶å…§æ ¸å ±å‘Šå…§éƒ¨å•é¡Œï¼ˆã€Œkernel bugã€ï¼‰ã€å¯æ¢å¾©éŒ¯èª¤ï¼ˆã€Œkernel Oopsã€ï¼‰æˆ–åœæ¢ -æ“作å‰ä¸å¯æ¢å¾©çš„錯誤（「kernel panicã€ï¼‰æ™‚，它也會æ到汙染狀態。當其ä¸ä¸€å€‹éŒ¯ -誤發生時，查看列å°çš„錯誤消æ¯çš„é ‚éƒ¨ï¼Œæœç´¢ä»¥ã€ŒCPU:ã€é–‹é 的行。如果發ç¾å•é¡Œæ™‚å…§ -æ ¸æœªè¢«æ±™æŸ“ï¼Œé‚£éº¼å®ƒæ‡‰è©²ä»¥ã€ŒNot infectedã€çµæŸï¼›å¦‚æžœä½ çœ‹åˆ°ã€ŒTainted:ã€ä¸”後跟一些 -ç©ºæ ¼å’Œå—æ¯ï¼Œé‚£å°±è¢«æ±™æŸ“了。 +在æ£åœ¨é‹è¡Œçš„ç³»çµ±ä¸Šæª¢æŸ¥å…§æ ¸æ˜¯å¦æ±¡æŸ“éžå¸¸å®¹æ˜“：如果 ``cat /proc/sys/kernel/tainted`` +返回“0â€ï¼Œé‚£éº¼å…§æ ¸æ²’有被污染，一切æ£å¸¸ã€‚在æŸäº›æƒ…æ³ä¸‹ç„¡æ³•æª¢æŸ¥è©²æ–‡ä»¶ï¼›é€™å°±æ˜¯ +çˆ²ä»€éº¼ç•¶å…§æ ¸å ±å‘Šå…§éƒ¨å•é¡Œï¼ˆâ€œkernel bugâ€ï¼‰ã€å¯æ¢å¾©éŒ¯èª¤ï¼ˆâ€œkernel Oopsâ€ï¼‰æˆ–åœæ¢ +æ“作å‰ä¸å¯æ¢å¾©çš„錯誤（“kernel panicâ€ï¼‰æ™‚，它也會æ到污染狀態。當其ä¸ä¸€å€‹éŒ¯ +誤發生時，查看打å°çš„錯誤消æ¯çš„é ‚éƒ¨ï¼Œæœç´¢ä»¥â€œCPU:â€é–‹é 的行。如果發ç¾å•é¡Œæ™‚å…§ +æ ¸æœªè¢«æ±¡æŸ“ï¼Œé‚£éº¼å®ƒæ‡‰è©²ä»¥â€œNot infectedâ€çµæŸï¼›å¦‚æžœä½ çœ‹åˆ°â€œTainted:â€ä¸”後跟一些 +ç©ºæ ¼å’Œå—æ¯ï¼Œé‚£å°±è¢«æ±¡æŸ“了。 -å¦‚æžœä½ çš„å…§æ ¸è¢«æ±™æŸ“äº†ï¼Œè«‹é–±è®€ã€ŒDocumentation/translations/zh_TW/admin-guide/tainted-kernels.rst〠-ä»¥æ‰¾å‡ºåŽŸå› ã€‚è¨æ³•æ¶ˆé™¤æ±™æŸ“å› ç´ ã€‚é€šå¸¸æ˜¯ç”±ä»¥ä¸‹ä¸‰ç¨®å› ç´ ä¹‹ä¸€å¼•èµ·çš„ï¼š +å¦‚æžœä½ çš„å…§æ ¸è¢«æ±¡æŸ“äº†ï¼Œè«‹é–±è®€ Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst +ä»¥æ‰¾å‡ºåŽŸå› ã€‚è¨æ³•æ¶ˆé™¤æ±¡æŸ“å› ç´ ã€‚é€šå¸¸æ˜¯ç”±ä»¥ä¸‹ä¸‰ç¨®å› ç´ ä¹‹ä¸€å¼•èµ·çš„ï¼š - 1. 發生了一個å¯æ¢å¾©çš„錯誤（「kernel Oopsã€ï¼‰ï¼Œå…§æ ¸æ±™æŸ“äº†è‡ªå·±ï¼Œå› çˆ²å…§æ ¸çŸ¥é“在 + 1. 發生了一個å¯æ¢å¾©çš„錯誤（“kernel Oopsâ€ï¼‰ï¼Œå…§æ ¸æ±¡æŸ“äº†è‡ªå·±ï¼Œå› çˆ²å…§æ ¸çŸ¥é“在 æ¤ä¹‹å¾Œå®ƒå¯èƒ½æœƒå‡ºç¾å¥‡æ€ªçš„行爲錯亂。在這種情æ³ä¸‹ï¼Œæª¢æŸ¥æ‚¨çš„å…§æ ¸æˆ–ç³»çµ±æ—¥èªŒï¼Œ 並尋找以下列文å—é–‹é 的部分:: Oops: 0000 [#1] SMP - 如方括號ä¸çš„「#1ã€æ‰€ç¤ºï¼Œé€™æ˜¯è‡ªå•“動以來的第一次Oops。æ¯å€‹Oopså’Œæ¤å¾Œç™¼ç”Ÿçš„ + 如方括號ä¸çš„“#1â€æ‰€ç¤ºï¼Œé€™æ˜¯è‡ªå•“動以來的第一次Oops。æ¯å€‹Oopså’Œæ¤å¾Œç™¼ç”Ÿçš„ 任何其他å•é¡Œéƒ½å¯èƒ½æ˜¯é¦–個Oops的後續å•é¡Œï¼Œå³ä½¿é€™å…©å€‹å•é¡Œçœ‹èµ·ä¾†å®Œå…¨ä¸ç›¸é—œã€‚ 通éŽæ¶ˆé™¤é¦–個Oopsçš„åŽŸå› ä¸¦åœ¨ä¹‹å¾Œå¾©ç¾è©²å•é¡Œï¼Œå¯ä»¥æŽ’除這種情æ³ã€‚有時僅僅 é‡æ–°å•“å‹•å°±è¶³å¤ äº†ï¼Œæœ‰æ™‚æ›´æ”¹é…置後é‡æ–°å•“å‹•å¯ä»¥æ¶ˆé™¤Oops。但是在這個æµç¨‹ä¸ ä¸è¦èŠ±è²»å¤ªå¤šæ™‚é–“åœ¨é€™ä¸€é»žä¸Šï¼Œå› çˆ²å¼•èµ·Oopsçš„åŽŸå› å¯èƒ½å·²ç¶“在您ç¨å¾Œå°‡æŒ‰æµç¨‹ 安è£çš„æ–°Linuxå…§æ ¸ç‰ˆæœ¬ä¸ä¿®å¾©äº†ã€‚ - 2. 您的系統使用的軟體安è£äº†è‡ªå·±çš„å…§æ ¸æ¨¡å¡Šï¼Œä¾‹å¦‚Nvidia的專有圖形驅動程åºæˆ– - VirtualBoxã€‚ç•¶å…§æ ¸å¾žå¤–éƒ¨æºï¼ˆå³ä½¿å®ƒå€‘是開æºçš„ï¼‰åŠ è¼‰æ¤é¡žæ¨¡å¡Šæ™‚，它會汙染 + 2. 您的系統使用的軟件安è£äº†è‡ªå·±çš„å…§æ ¸æ¨¡å¡Šï¼Œä¾‹å¦‚Nvidia的專有圖形驅動程åºæˆ– + VirtualBoxã€‚ç•¶å…§æ ¸å¾žå¤–éƒ¨æºï¼ˆå³ä½¿å®ƒå€‘是開æºçš„ï¼‰åŠ è¼‰æ¤é¡žæ¨¡å¡Šæ™‚，它會污染 自己：它們有時會在ä¸ç›¸é—œçš„å…§æ ¸å€åŸŸå°Žè‡´éŒ¯èª¤ï¼Œå¾žè€Œå¯èƒ½å°Žè‡´æ‚¨é¢è‡¨çš„å•é¡Œã€‚ å› æ¤ï¼Œç•¶æ‚¨æƒ³è¦å‘Linuxå…§æ ¸é–‹ç™¼äººå“¡å ±å‘Šå•é¡Œæ™‚ï¼Œæ‚¨å¿…é ˆé˜»æ¢é€™äº›æ¨¡å¡ŠåŠ 載。 - 大多數情æ³ä¸‹æœ€ç°¡å–®çš„方法是：臨時å¸è¼‰é€™äº›è»Ÿé«”，包括它們å¯èƒ½å·²ç¶“安è£çš„ä»» + 大多數情æ³ä¸‹æœ€ç°¡å–®çš„方法是：臨時å¸è¼‰é€™äº›è»Ÿä»¶ï¼ŒåŒ…括它們å¯èƒ½å·²ç¶“安è£çš„ä»» 何模塊。之後é‡æ–°å•“動。 - 3. ç•¶å…§æ ¸åŠ è¼‰é§ç•™åœ¨Linuxå…§æ ¸åŽŸå§‹ç¢¼staging樹ä¸çš„模塊時，它也會汙染自身。這 + 3. ç•¶å…§æ ¸åŠ è¼‰é§ç•™åœ¨Linuxå…§æ ¸æºä»£ç¢¼staging樹ä¸çš„模塊時，它也會污染自身。這 是一個特殊的å€åŸŸï¼Œä»£ç¢¼ï¼ˆä¸»è¦æ˜¯é©…動程åºï¼‰é‚„沒有é”到æ£å¸¸Linuxå…§æ ¸çš„è³ªé‡ - æ¨™æº–ã€‚ç•¶æ‚¨å ±å‘Šæ¤ç¨®æ¨¡å¡Šçš„å•é¡Œæ™‚ï¼Œå…§æ ¸å—到汙染顯然是沒有å•é¡Œçš„ï¼›åªéœ€ç¢ºä¿ - å•é¡Œæ¨¡å¡Šæ˜¯é€ æˆæ±™æŸ“çš„å”¯ä¸€åŽŸå› ã€‚å¦‚æžœå•é¡Œç™¼ç”Ÿåœ¨ä¸€å€‹ä¸ç›¸é—œçš„å€åŸŸï¼Œé‡æ–°å•“å‹• + æ¨™æº–ã€‚ç•¶æ‚¨å ±å‘Šæ¤ç¨®æ¨¡å¡Šçš„å•é¡Œæ™‚ï¼Œå…§æ ¸å—到污染顯然是沒有å•é¡Œçš„ï¼›åªéœ€ç¢ºä¿ + å•é¡Œæ¨¡å¡Šæ˜¯é€ æˆæ±¡æŸ“çš„å”¯ä¸€åŽŸå› ã€‚å¦‚æžœå•é¡Œç™¼ç”Ÿåœ¨ä¸€å€‹ä¸ç›¸é—œçš„å€åŸŸï¼Œé‡æ–°å•“å‹• 並通éŽæŒ‡å®š ``foo.blacklist=1`` ä½œçˆ²å…§æ ¸åƒæ•¸è‡¨æ™‚阻æ¢è©²æ¨¡å¡Šè¢«åŠ 載（用有 - å•é¡Œçš„模塊å替æ›ã€Œfooã€ï¼‰ã€‚ + å•é¡Œçš„模塊å替æ›â€œfooâ€ï¼‰ã€‚ 記錄如何é‡ç¾å•é¡Œ ------------------ *粗略地寫下如何é‡ç¾é€™å€‹å•é¡Œã€‚如果您åŒæ™‚處ç†å¤šå€‹å•é¡Œï¼Œè«‹çˆ²æ¯å€‹å•é¡Œå–®ç¨å¯« - 注釋，並確ä¿å®ƒå€‘在新啓動的系統上ç¨ç«‹å‡ºç¾ã€‚這是必è¦çš„ï¼Œå› çˆ²æ¯å€‹å•é¡Œéƒ½éœ€ + 註釋，並確ä¿å®ƒå€‘在新啓動的系統上ç¨ç«‹å‡ºç¾ã€‚這是必è¦çš„ï¼Œå› çˆ²æ¯å€‹å•é¡Œéƒ½éœ€ è¦åˆ†åˆ¥å ±å‘Šçµ¦å…§æ ¸é–‹ç™¼äººå“¡ï¼Œé™¤éžå®ƒå€‘åš´é‡ç³¾çºåœ¨ä¸€èµ·ã€‚* å¦‚æžœä½ åŒæ™‚處ç†å¤šå€‹å•é¡Œï¼Œå¿…é ˆåˆ†åˆ¥å ±å‘Šæ¯å€‹å•é¡Œï¼Œå› 爲它們å¯èƒ½ç”±ä¸åŒçš„開發人員 @@ -438,20 +432,20 @@ Linuxå…§æ ¸ç ´å£žäº†å®ƒè™•ç†çš„數據或æ壞了它é‹è¡Œçš„ç¡¬é«”ã€‚ç•¶å…§æ ¸ 注æ„ï¼šå ±å‘Šåªç™¼ç”ŸéŽä¸€æ¬¡çš„å•é¡Œå¾€å¾€æ˜¯æ²’有çµæžœçš„ï¼Œå› çˆ²å®ƒå€‘å¯èƒ½æ˜¯ç”±æ–¼å®‡å®™è¼»å°„å°Ž 致的ä½ç¿»è½‰ã€‚æ‰€ä»¥ä½ æ‡‰è©²å˜—è©¦é€šéŽé‡ç¾å•é¡Œä¾†æŽ’除這種情æ³ï¼Œç„¶å¾Œå†ç¹¼çºŒã€‚å¦‚æžœä½ æœ‰ -è¶³å¤ çš„ç¶“é©—ä¾†å€åˆ†ç”±æ–¼ç¡¬é«”故障引起的一次性錯誤和難以é‡ç¾çš„ç½•è¦‹å…§æ ¸å•é¡Œï¼Œå¯ä»¥ +è¶³å¤ çš„ç¶“é©—ä¾†å€åˆ†ç”±æ–¼ç¡¬ä»¶æ•…障引起的一次性錯誤和難以é‡ç¾çš„ç½•è¦‹å…§æ ¸å•é¡Œï¼Œå¯ä»¥ 忽略這個建è°ã€‚ -穩定版或長期支æŒå…§æ ¸çš„回æ¸ï¼Ÿ +穩定版或長期支æŒå…§æ ¸çš„è¿´æ¸ï¼Ÿ ----------------------------- - *如果您æ£é¢è‡¨ç©©å®šç‰ˆæˆ–長期支æŒç‰ˆæœ¬ç·šçš„回æ¸ï¼ˆä¾‹å¦‚從5.10.4更新到5.10.5æ™‚å‡ºç¾ - æ•…éšœï¼‰ï¼Œè«‹æŸ¥çœ‹å¾Œæ–‡ã€Œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„回æ¸ã€å°ç¯€ã€‚* + *如果您æ£é¢è‡¨ç©©å®šç‰ˆæˆ–長期支æŒç‰ˆæœ¬ç·šçš„è¿´æ¸ï¼ˆä¾‹å¦‚從5.10.4更新到5.10.5æ™‚å‡ºç¾ + æ•…éšœï¼‰ï¼Œè«‹æŸ¥çœ‹å¾Œæ–‡â€œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„è¿´æ¸â€å°ç¯€ã€‚* -穩定版和長期支æŒå…§æ ¸ç‰ˆæœ¬ç·šä¸çš„回æ¸æ˜¯Linux開發人員éžå¸¸å¸Œæœ›è§£æ±ºçš„å•é¡Œï¼Œé€™æ¨£çš„ -å•é¡Œç”šè‡³æ¯”主線開發分支ä¸çš„回æ¸æ›´ä¸æ‡‰å‡ºç¾ï¼Œå› 爲它們會很快影響到很多人。開發人員 -希望儘快了解æ¤é¡žå•é¡Œï¼Œå› æ¤æœ‰ä¸€å€‹ç°¡åŒ–æµç¨‹ä¾†å ±å‘Šé€™äº›å•é¡Œã€‚注æ„ï¼Œä½¿ç”¨æ›´æ–°å…§æ ¸ç‰ˆ -本線的回æ¸ï¼ˆæ¯”如從5.9.15切æ›åˆ°5.10.5時出ç¾æ•…障）ä¸ç¬¦åˆæ¢ä»¶ã€‚ +穩定版和長期支æŒå…§æ ¸ç‰ˆæœ¬ç·šä¸çš„è¿´æ¸æ˜¯Linux開發人員éžå¸¸å¸Œæœ›è§£æ±ºçš„å•é¡Œï¼Œé€™æ¨£çš„ +å•é¡Œç”šè‡³æ¯”主線開發分支ä¸çš„è¿´æ¸æ›´ä¸æ‡‰å‡ºç¾ï¼Œå› 爲它們會很快影響到很多人。開發人員 +希望儘快çžè§£æ¤é¡žå•é¡Œï¼Œå› æ¤æœ‰ä¸€å€‹ç°¡åŒ–æµç¨‹ä¾†å ±å‘Šé€™äº›å•é¡Œã€‚注æ„ï¼Œä½¿ç”¨æ›´æ–°å…§æ ¸ç‰ˆ +本線的迴æ¸ï¼ˆæ¯”如從5.9.15切æ›åˆ°5.10.5時出ç¾æ•…障）ä¸ç¬¦åˆæ¢ä»¶ã€‚ ä½ éœ€è¦å°‡å•é¡Œå ±å‘Šåˆ°ä½•è™• @@ -462,9 +456,9 @@ Linuxå…§æ ¸ç ´å£žäº†å®ƒè™•ç†çš„數據或æ壞了它é‹è¡Œçš„ç¡¬é«”ã€‚ç•¶å…§æ ¸ éŽéƒµä»¶ç™¼é€çµ¦ç¶è·äººå“¡å’Œå…¬å…±éƒµä»¶åˆ—表。* å°‡å ±å‘Šç™¼é€çµ¦åˆé©çš„人是至關é‡è¦çš„ï¼Œå› çˆ²Linuxå…§æ ¸æ˜¯ä¸€å€‹å¤§é …ç›®ï¼Œå¤§å¤šæ•¸é–‹ç™¼äººå“¡ -åªç†Ÿæ‚‰å…¶ä¸çš„一å°éƒ¨åˆ†ã€‚例如，相當多的程å¼è¨è¨ˆå¸«åªé—œå¿ƒä¸€å€‹é©…動程åºï¼Œæ¯”如一個WiFi -晶片驅動程åºï¼›å®ƒçš„開發人員å¯èƒ½å°ç–é 的或ä¸ç›¸é—œçš„「å系統ã€ï¼ˆå¦‚TCPå †æ£§ã€ -PCIe/PCIå系統ã€å…§å˜ç®¡ç†æˆ–文件系統）的內部知è˜äº†è§£å¾ˆå°‘或完全ä¸äº†è§£ã€‚ +åªç†Ÿæ‚‰å…¶ä¸çš„一å°éƒ¨åˆ†ã€‚例如，相當多的程åºå“¡åªé—œå¿ƒä¸€å€‹é©…動程åºï¼Œæ¯”如一個WiFi +芯片驅動程åºï¼›å®ƒçš„開發人員å¯èƒ½å°ç–é 的或ä¸ç›¸é—œçš„“å系統â€ï¼ˆå¦‚TCPå †æ£§ã€ +PCIe/PCIå系統ã€å…§å˜ç®¡ç†æˆ–文件系統）的內部知è˜çžè§£å¾ˆå°‘或完全ä¸çžè§£ã€‚ å•é¡Œåœ¨æ–¼ï¼šLinuxå…§æ ¸ç¼ºå°‘ä¸€å€‹ï¼Œå¯ä»¥ç°¡å–®åœ°å°‡å•é¡Œæ¸æª”並讓需è¦äº†è§£å®ƒçš„開發人員了 解它的，ä¸å¿ƒåŒ–ç¼ºé™·è·Ÿè¹¤å™¨ã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ å¿…é ˆæ‰¾åˆ°æ£ç¢ºçš„é€”å¾‘ä¾†è‡ªå·±å ±å‘Šå•é¡Œã€‚ @@ -476,10 +470,10 @@ PCIe/PCIå系統ã€å…§å˜ç®¡ç†æˆ–文件系統）的內部知è˜äº†è§£å¾ˆå°‘或 爲了說明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，讓我們å‡è¨æ‚¨çš„ç†è¨˜ 本電腦ä¸çš„WiFiåœ¨æ›´æ–°å…§æ ¸å¾Œçªç„¶å‡ºç¾äº†éŒ¯èª¤è¡Œçˆ²ã€‚這種情æ³ä¸‹å¯èƒ½æ˜¯WiFié©…å‹•çš„å• -題。顯然，它也å¯èƒ½ç”±æ–¼é©…動基於的æŸäº›ä»£ç¢¼ï¼Œä½†é™¤éžä½ 懷疑有這樣的æ±è¥¿æœƒé™„著在 -驅動程åºä¸Šã€‚如果真的是其他的å•é¡Œï¼Œé©…動程åºçš„開發人員會讓åˆé©çš„人åƒèˆ‡é€²ä¾†ã€‚ +題。顯然，它也å¯èƒ½ç”±æ–¼é©…動基於的æŸäº›ä»£ç¢¼ï¼Œä½†é™¤éžä½ 懷疑有這樣的æ±è¥¿æœƒé™„ç€åœ¨ +驅動程åºä¸Šã€‚如果真的是其他的å•é¡Œï¼Œé©…動程åºçš„開發人員會讓åˆé©çš„人蔘與進來。 -éºæ†¾çš„是，沒有通用且簡單的辦法來檢查哪個代碼驅動了特定硬體組件。 +éºæ†¾çš„是，沒有通用且簡單的辦法來檢查哪個代碼驅動了特定硬件組件。 在WiFi驅動出ç¾å•é¡Œçš„情æ³ä¸‹ï¼Œä½ å¯èƒ½æƒ³æŸ¥çœ‹ ``lspci -k`` çš„è¼¸å‡ºï¼Œå› çˆ²å®ƒåˆ—å‡ºäº† PCI/PCIe總線上的è¨å‚™å’Œé©…å‹•å®ƒçš„å…§æ ¸æ¨¡å¡Š:: @@ -492,19 +486,19 @@ PCI/PCIe總線上的è¨å‚™å’Œé©…å‹•å®ƒçš„å…§æ ¸æ¨¡å¡Š:: Kernel modules: ath10k_pci [...] -ä½†å¦‚æžœä½ çš„WiFi晶片通éŽUSB或其他內部總線連接，這種方法就行ä¸é€šäº†ã€‚åœ¨é€™ç¨®æƒ…æ³ +ä½†å¦‚æžœä½ çš„WiFi芯片通éŽUSB或其他內部總線連接，這種方法就行ä¸é€šäº†ã€‚åœ¨é€™ç¨®æƒ…æ³ ä¸‹ï¼Œæ‚¨å¯èƒ½éœ€è¦æª¢æŸ¥æ‚¨çš„WiFi管ç†å™¨æˆ– ``ip link`` 的輸出。尋找有å•é¡Œçš„ç¶²çµ¡æŽ¥å£ -çš„å稱，它å¯èƒ½é¡žä¼¼æ–¼ã€Œwlp58s0ã€ã€‚æ¤å稱å¯ä»¥ç”¨ä¾†æ‰¾åˆ°é©…動它的模塊:: +çš„å稱，它å¯èƒ½é¡žä¼¼æ–¼â€œwlp58s0â€ã€‚æ¤å稱å¯ä»¥ç”¨ä¾†æ‰¾åˆ°é©…動它的模塊:: [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module ath10k_pci 如果這些技巧ä¸èƒ½é€²ä¸€æ¥å¹«åŠ©æ‚¨ï¼Œè«‹å˜—試在網上æœç´¢å¦‚何縮å°ç›¸é—œé©…動程åºæˆ–å系統 -的範åœã€‚å¦‚æžœä½ ä¸ç¢ºå®šæ˜¯å“ªä¸€å€‹ï¼šè©¦è‘—猜一下，å³ä½¿ä½ 猜得ä¸å¥½ï¼Œä¹Ÿæœƒæœ‰äººæœƒå¹«åŠ©ä½ +的範åœã€‚å¦‚æžœä½ ä¸ç¢ºå®šæ˜¯å“ªä¸€å€‹ï¼šè©¦ç€çŒœä¸€ä¸‹ï¼Œå³ä½¿ä½ 猜得ä¸å¥½ï¼Œä¹Ÿæœƒæœ‰äººæœƒå¹«åŠ©ä½ 的。 一旦您知é“了相應的驅動程åºæˆ–å系統，您就希望在MAINTAINERS文件ä¸æœç´¢å®ƒã€‚如果 -是「ath10k_pciã€ï¼Œæ‚¨ä¸æœƒæ‰¾åˆ°ä»»ä½•æ±è¥¿ï¼Œå› 爲åç¨±å¤ªå…·é«”äº†ã€‚æœ‰æ™‚ä½ éœ€è¦åœ¨ç¶²ä¸Šå°‹æ‰¾ +是“ath10k_pciâ€ï¼Œæ‚¨ä¸æœƒæ‰¾åˆ°ä»»ä½•æ±è¥¿ï¼Œå› 爲åç¨±å¤ªå…·é«”äº†ã€‚æœ‰æ™‚ä½ éœ€è¦åœ¨ç¶²ä¸Šå°‹æ‰¾ 幫助；但在æ¤ä¹‹å‰ï¼Œè«‹å˜—試使用一個ç¨çŸæˆ–修改éŽçš„å稱來æœç´¢MAINTAINERSæ–‡ä»¶ï¼Œå› çˆ²é€™æ¨£ä½ å¯èƒ½æœƒç™¼ç¾é¡žä¼¼é€™æ¨£çš„æ±è¥¿:: @@ -516,23 +510,23 @@ PCI/PCIe總線上的è¨å‚™å’Œé©…å‹•å®ƒçš„å…§æ ¸æ¨¡å¡Š:: 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:ã€ã€‚æ¤æ–‡ä»¶é ‚部有一段解釋了這些和其他縮寫。 +注æ„：如果您閱讀在Linuxæºä»£ç¢¼æ¨¹çš„æ ¹ç›®éŒ„ä¸æ‰¾åˆ°çš„原始ç¶è·è€…文件，則行æ述將是 +縮寫。例如，“Mail:（郵件）â€å°‡æ˜¯â€œM:â€ï¼Œâ€œMailing list:（郵件列表）â€å°‡æ˜¯â€œLâ€ï¼Œ +“Status:（狀態）â€å°‡æ˜¯â€œS:â€ã€‚æ¤æ–‡ä»¶é ‚部有一段解釋了這些和其他縮寫。 -首先查看「Statusã€ç‹€æ…‹è¡Œã€‚ç†æƒ³æƒ…æ³ä¸‹ï¼Œå®ƒæ‡‰è©²å¾—到「Supported（支æŒï¼‰ã€æˆ– -「Maintained（ç¶è·ï¼‰ã€ã€‚如果狀態爲「Obsolete（éŽæ™‚的）ã€ï¼Œé‚£éº¼ä½ 在使用一些éŽæ™‚çš„ -方法，需è¦è½‰æ›åˆ°æ–°çš„解決方案上。有時候，åªæœ‰åœ¨æ„Ÿåˆ°æœ‰å‹•åŠ›æ™‚，æ‰æœƒæœ‰äººçˆ²ä»£ç¢¼ -æ供「Odd Fixesã€ã€‚如果碰見「Orphanã€ï¼Œä½ 就完全ä¸èµ°é‹äº†ï¼Œå› 爲å†ä¹Ÿæ²’有人關心代碼 -了，åªå‰©ä¸‹é€™äº›é¸é …:準備好與å•é¡Œå…±å˜ï¼Œè‡ªå·±ä¿®å¾©å®ƒï¼Œæˆ–者找一個願æ„修復它的程å¼è¨è¨ˆå¸«ã€‚ +首先查看“Statusâ€ç‹€æ…‹è¡Œã€‚ç†æƒ³æƒ…æ³ä¸‹ï¼Œå®ƒæ‡‰è©²å¾—到“Supported（支æŒï¼‰â€æˆ– +“Maintained（ç¶è·ï¼‰â€ã€‚如果狀態爲“Obsolete（éŽæ™‚的）â€ï¼Œé‚£éº¼ä½ 在使用一些éŽæ™‚çš„ +方法，需è¦è½‰æ›åˆ°æ–°çš„解決方案上。有時候，åªæœ‰åœ¨æ„Ÿåˆ°æœ‰å‹•åŠ›æ™‚，纔會有人爲代碼 +æ供“Odd Fixesâ€ã€‚如果碰見“Orphanâ€ï¼Œä½ 就完全ä¸èµ°é‹äº†ï¼Œå› 爲å†ä¹Ÿæ²’有人關心代碼 +了，åªå‰©ä¸‹é€™äº›é¸é …:準備好與å•é¡Œå…±å˜ï¼Œè‡ªå·±ä¿®å¾©å®ƒï¼Œæˆ–者找一個願æ„修復它的程åºå“¡ã€‚ -檢查狀態後，尋找以「bug:ã€é–‹é çš„ä¸€è¡Œï¼šå®ƒå°‡å‘Šè¨´ä½ åœ¨å“ªè£¡å¯ä»¥æ‰¾åˆ°å系統特定的缺 +檢查狀態後，尋找以“bug:â€é–‹é çš„ä¸€è¡Œï¼šå®ƒå°‡å‘Šè¨´ä½ åœ¨å“ªè£å¯ä»¥æ‰¾åˆ°å系統特定的缺 陷跟蹤器來æäº¤ä½ çš„å•é¡Œã€‚上é¢çš„例å沒有æ¤è¡Œã€‚å¤§å¤šæ•¸éƒ¨åˆ†éƒ½æ˜¯é€™æ¨£ï¼Œå› çˆ² Linux å…§æ ¸çš„é–‹ç™¼å®Œå…¨æ˜¯ç”±éƒµä»¶é©…å‹•çš„ã€‚å¾ˆå°‘æœ‰å系統使用缺陷跟蹤器，且其ä¸åªæœ‰ä¸€éƒ¨åˆ† ä¾è³´æ–¼ bugzilla.kernel.org。 -在這種以åŠå…¶ä»–很多情æ³ä¸‹ï¼Œä½ å¿…é ˆå°‹æ‰¾ä»¥ã€ŒMail:ã€é–‹é 的行。這些行æ到了特定代碼 -çš„ç¶è·è€…çš„åå—和電å郵件地å€ã€‚也å¯ä»¥æŸ¥æ‰¾ä»¥ã€ŒMailing list:ã€é–‹é çš„è¡Œï¼Œå®ƒå‘Šè¨´ä½ +在這種以åŠå…¶ä»–很多情æ³ä¸‹ï¼Œä½ å¿…é ˆå°‹æ‰¾ä»¥â€œMail:â€é–‹é 的行。這些行æ到了特定代碼 +çš„ç¶è·è€…çš„åå—和電å郵件地å€ã€‚也å¯ä»¥æŸ¥æ‰¾ä»¥â€œMailing list:â€é–‹é çš„è¡Œï¼Œå®ƒå‘Šè¨´ä½ é–‹ç™¼ä»£ç¢¼çš„å…¬å…±éƒµä»¶åˆ—è¡¨ã€‚ä½ çš„å ±å‘Šä¹‹å¾Œéœ€è¦é€šéŽéƒµä»¶ç™¼åˆ°é€™äº›åœ°å€ã€‚å¦å¤–，å°æ–¼æ‰€æœ‰ 通éŽé›»å郵件發é€çš„å•é¡Œå ±å‘Šï¼Œä¸€å®šè¦æŠ„é€ Linux Kernel Mailing List（LKML） <linux-kernel@vger.kernel.org>。在以後通éŽéƒµä»¶ç™¼é€å•é¡Œå ±å‘Šæ™‚，ä¸è¦éºæ¼ä»»ä½• @@ -544,8 +538,8 @@ PCI/PCIe總線上的è¨å‚™å’Œé©…å‹•å®ƒçš„å…§æ ¸æ¨¡å¡Š:: ~~~~~~~~~~~~~~~~~~~~ å°æ–¼æ‰‹é 有Linuxæºç¢¼çš„人來說，有第二個å¯ä»¥æ‰¾åˆ°åˆé©çš„å ±å‘Šåœ°é»žçš„é¸æ“‡ï¼šè…³æœ¬ -「scripts/get_maintainer.plã€ï¼Œå®ƒå˜—試找到所有è¦è¯ç¹«çš„人。它會查詢MAINTAINERS -文件，並需è¦ç”¨ç›¸é—œåŽŸå§‹ç¢¼çš„路徑來調用。å°æ–¼ç·¨è¯æˆæ¨¡å¡Šçš„驅動程åºï¼Œç¶“常å¯ä»¥ç”¨ +“scripts/get_maintainer.plâ€ï¼Œå®ƒå˜—試找到所有è¦è¯ç¹«çš„人。它會查詢MAINTAINERS +文件，並需è¦ç”¨ç›¸é—œæºä»£ç¢¼çš„路徑來調用。å°æ–¼ç·¨è¯æˆæ¨¡å¡Šçš„驅動程åºï¼Œç¶“常å¯ä»¥ç”¨ 這樣的命令找到:: $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' @@ -561,13 +555,13 @@ PCI/PCIe總線上的è¨å‚™å’Œé©…å‹•å®ƒçš„å…§æ ¸æ¨¡å¡Š:: netdev@vger.kernel.org (open list:NETWORKING DRIVERS) linux-kernel@vger.kernel.org (open list) -ä¸è¦æŠŠä½ çš„å ±å‘Šç™¼çµ¦æ‰€æœ‰çš„äººã€‚ç™¼é€çµ¦ç¶è·è€…，腳本稱之爲「supporter:ã€ï¼›å¦å¤–æŠ„é€ +ä¸è¦æŠŠä½ çš„å ±å‘Šç™¼çµ¦æ‰€æœ‰çš„äººã€‚ç™¼é€çµ¦ç¶è·è€…，腳本稱之爲“supporter:â€ï¼›å¦å¤–æŠ„é€ ä»£ç¢¼æœ€ç›¸é—œçš„éƒµä»¶åˆ—è¡¨ï¼Œä»¥åŠ Linux å…§æ ¸éƒµä»¶åˆ—è¡¨ï¼ˆLKML）。在æ¤ä¾‹ä¸ï¼Œä½ 需è¦å°‡å ± -告發é€çµ¦ 「Some Human <shuman@example.com>ã€ ï¼Œä¸¦æŠ„é€ -「ath10k@lists.infradead.orgã€å’Œã€Œlinux-kernel@vger.kernel.orgã€ã€‚ +告發é€çµ¦ “Some Human <shuman@example.com>â€ ï¼Œä¸¦æŠ„é€ +“ath10k@lists.infradead.orgâ€å’Œâ€œlinux-kernel@vger.kernel.orgâ€ã€‚ -注æ„ï¼šå¦‚æžœä½ ç”¨ git 克隆了 Linux åŽŸå§‹ç¢¼ï¼Œä½ å¯èƒ½éœ€è¦ç”¨--git å†æ¬¡èª¿ç”¨ -get_maintainer.pl。腳本會查看æ交æ·å²ï¼Œä»¥æ‰¾åˆ°æœ€è¿‘哪些人åƒèˆ‡äº†ç›¸é—œä»£ç¢¼çš„編寫， +注æ„ï¼šå¦‚æžœä½ ç”¨ git 克隆了 Linux æºä»£ç¢¼ï¼Œä½ å¯èƒ½éœ€è¦ç”¨--git å†æ¬¡èª¿ç”¨ +get_maintainer.pl。腳本會查看æ交æ·å²ï¼Œä»¥æ‰¾åˆ°æœ€è¿‘哪些人蔘與了相關代碼的編寫， å› çˆ²ä»–å€‘å¯èƒ½æœƒæ供幫助。但è¦å°å¿ƒä½¿ç”¨é€™äº›çµæžœï¼Œå› çˆ²å®ƒå¾ˆå®¹æ˜“è®“ä½ èª¤å…¥æ§é€”。 例如，這種情æ³å¸¸å¸¸æœƒç™¼ç”Ÿåœ¨å¾ˆå°‘被修改的地方（比如è€èˆŠçš„或未ç¶è·çš„驅動程åºï¼‰ï¼š 有時這樣的代碼會在樹級清ç†æœŸé–“è¢«æ ¹æœ¬ä¸é—œå¿ƒæ¤é©…動程åºçš„開發者修改。 @@ -580,73 +574,74 @@ get_maintainer.pl。腳本會查看æ交æ·å²ï¼Œä»¥æ‰¾åˆ°æœ€è¿‘哪些人åƒèˆ‡ 如果找到匹é…çš„å ±å‘Šï¼Œè«‹åŠ å…¥è¨Žè«–è€Œä¸æ˜¯ç™¼é€æ–°å ±å‘Šã€‚* 如å‰æ‰€è¿°ï¼šå ±å‘Šä¸€å€‹åˆ¥äººå·²ç¶“æ出的å•é¡Œï¼Œå°æ¯å€‹äººä¾†èªªéƒ½æ˜¯æµªè²»æ™‚é–“ï¼Œå°¤å…¶æ˜¯ä½œçˆ²å ±å‘Š -äººçš„ä½ ã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ æ‡‰è©²å†æ¬¡æœç´¢ç¾æœ‰çš„å ±å‘Šã€‚ç¾åœ¨ä½ 已經知é“å•é¡Œéœ€è¦å ±å‘Šåˆ°å“ªè£¡ã€‚ +äººçš„ä½ ã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ æ‡‰è©²å†æ¬¡æœç´¢ç¾æœ‰çš„å ±å‘Šã€‚ç¾åœ¨ä½ 已經知é“å•é¡Œéœ€è¦å ±å‘Šåˆ°å“ªè£ã€‚ 如果是郵件列表，那麼一般在 `lore.kernel.org <https://lore.kernel.org/>`_ å¯ä»¥ 找到相應å˜æª”。 但有些列表é‹è¡Œåœ¨å…¶ä»–地方。例如å‰é¢æ¥é©Ÿä¸ç•¶ä¾‹åçš„ath10k WiFi驅動程åºå°±æ˜¯é€™ç¨® -情æ³ã€‚ä½†æ˜¯ä½ é€šå¸¸å¯ä»¥åœ¨ç¶²ä¸Šå¾ˆå®¹æ˜“地找到這些列表的檔案。例如æœç´¢ã€Œarchive -ath10k@lists.infradead.orgã€ï¼Œå°‡å¼•å°Žæ‚¨åˆ°ath10k郵件列表的信æ¯é ，該é é¢é ‚éƒ¨é€£çµ +情æ³ã€‚ä½†æ˜¯ä½ é€šå¸¸å¯ä»¥åœ¨ç¶²ä¸Šå¾ˆå®¹æ˜“地找到這些列表的檔案。例如æœç´¢â€œarchive +ath10k@lists.infradead.orgâ€ï¼Œå°‡å¼•å°Žæ‚¨åˆ°ath10k郵件列表的信æ¯é ，該é é¢é ‚部éˆæŽ¥ 到其 `列表å˜æª” <https://lists.infradead.org/pipermail/ath10k/>`_ 。éºæ†¾çš„是， -這個列表和其他一些列表缺ä¹æœç´¢å…¶å˜æª”的功能。在這種情æ³ä¸‹å¯ä»¥ä½¿ç”¨å¸¸è¦çš„網際網路 -æœå°‹å¼•æ“Žï¼Œä¸¦æ·»åŠ 類似「site:lists.infadead.org/pipermail/ath10k/ã€é€™ -樣的æœç´¢æ¢ä»¶ï¼Œé€™æœƒæŠŠçµæžœé™åˆ¶åœ¨è©²é€£çµä¸çš„檔案。 +這個列表和其他一些列表缺ä¹æœç´¢å…¶å˜æª”的功能。在這種情æ³ä¸‹å¯ä»¥ä½¿ç”¨å¸¸è¦çš„互è¯ç¶² +æœç´¢å¼•æ“Žï¼Œä¸¦æ·»åŠ 類似“site:lists.infadead.org/pipermail/ath10k/â€é€™ +樣的æœç´¢æ¢ä»¶ï¼Œé€™æœƒæŠŠçµæžœé™åˆ¶åœ¨è©²éˆæŽ¥ä¸çš„檔案。 -也請進一æ¥æœç´¢ç¶²çµ¡ã€LKMLå’Œbugzilla.kernel.org網站。 +也請進一æ¥æœç´¢ç¶²çµ¡ã€LKMLå’Œbugzilla.kernel.orgç¶²ç«™ã€‚å¦‚æžœä½ çš„å ±å‘Šéœ€è¦ç™¼é€åˆ°ç¼ºé™· +跟蹤器ä¸ï¼Œé‚£éº¼æ‚¨å¯èƒ½é‚„需è¦æª¢æŸ¥å系統的郵件列表å˜æª”ï¼Œå› çˆ²å¯èƒ½æœ‰äººåªåœ¨é‚£è£å ±å‘Šäº†å®ƒã€‚ -有關如何æœç´¢ä»¥åŠåœ¨æ‰¾åˆ°åŒ¹é…å ±å‘Šæ™‚å¦‚ä½•æ“作的詳細信æ¯ï¼Œè«‹åƒé–±ä¸Šé¢çš„「æœç´¢ç¾æœ‰å ±å‘Š -（第一部分）ã€ã€‚ +有關如何æœç´¢ä»¥åŠåœ¨æ‰¾åˆ°åŒ¹é…å ±å‘Šæ™‚å¦‚ä½•æ“作的詳細信æ¯ï¼Œè«‹åƒé–±ä¸Šé¢çš„“æœç´¢ç¾æœ‰å ±å‘Š +（第一部分）â€ã€‚ -ä¸è¦æ€¥è‘—完æˆå ±å‘ŠéŽç¨‹çš„這一æ¥ï¼šèŠ±30到60分é˜ç”šè‡³æ›´å¤šçš„時間å¯ä»¥çˆ²ä½ å’Œå…¶ä»–äººç¯€çœ / +ä¸è¦æ€¥ç€å®Œæˆå ±å‘ŠéŽç¨‹çš„這一æ¥ï¼šèŠ±30到60分é˜ç”šè‡³æ›´å¤šçš„時間å¯ä»¥çˆ²ä½ å’Œå…¶ä»–äººç¯€çœ / 減少相當多的時間和麻煩。 安è£ä¸€å€‹æ–°çš„å…§æ ¸é€²è¡Œæ¸¬è©¦ -------------------------- - *除éžæ‚¨å·²ç¶“在é‹è¡Œæœ€æ–°çš„「主線ã€Linuxå…§æ ¸ï¼Œå¦å‰‡æœ€å¥½åœ¨å ±å‘Šæµç¨‹å‰å®‰è£å®ƒã€‚在 - æŸäº›æƒ…æ³ä¸‹ï¼Œä½¿ç”¨æœ€æ–°çš„「穩定版ã€Linuxé€²è¡Œæ¸¬è©¦å’Œå ±å‘Šä¹Ÿæ˜¯å¯ä»¥æŽ¥å—的替代方案； + *除éžæ‚¨å·²ç¶“在é‹è¡Œæœ€æ–°çš„“主線â€Linuxå…§æ ¸ï¼Œå¦å‰‡æœ€å¥½åœ¨å ±å‘Šæµç¨‹å‰å®‰è£å®ƒã€‚在 + æŸäº›æƒ…æ³ä¸‹ï¼Œä½¿ç”¨æœ€æ–°çš„“穩定版â€Linuxé€²è¡Œæ¸¬è©¦å’Œå ±å‘Šä¹Ÿæ˜¯å¯ä»¥æŽ¥å—的替代方案； 在åˆä½µçª—å£æœŸé–“，這實際上å¯èƒ½æ˜¯æœ€å¥½çš„方法，但在開發階段最好還是暫åœå¹¾å¤©ã€‚ - ç„¡è«–ä½ é¸æ“‡ä»€éº¼ç‰ˆæœ¬ï¼Œæœ€å¥½ä½¿ç”¨ã€Œæ™®é€šã€æ§‹å»ºã€‚忽略這些建è°æœƒå¤§å¤§å¢žåŠ æ‚¨çš„å ±å‘Š + ç„¡è«–ä½ é¸æ“‡ä»€éº¼ç‰ˆæœ¬ï¼Œæœ€å¥½ä½¿ç”¨â€œæ™®é€šâ€æ§‹å»ºã€‚忽略這些建è°æœƒå¤§å¤§å¢žåŠ æ‚¨çš„å ±å‘Š 被拒絕或忽略的風險。* -æ£å¦‚第一æ¥çš„詳細解釋ä¸æ‰€æ到的：與大多數程å¼è¨è¨ˆå¸«ä¸€æ¨£ï¼Œèˆ‡å¤§å¤šæ•¸ç¨‹å¼è¨è¨ˆå¸«ä¸€æ¨£ï¼ŒLinux -å…§æ ¸é–‹ç™¼äººå“¡ä¸å–œæ¡èŠ±æ™‚間處ç†ä»–們ç¶è·çš„原始碼ä¸æ ¹æœ¬ä¸æœƒç™¼ç”Ÿçš„å•é¡Œçš„å ±å‘Šã€‚é€™éš» +æ£å¦‚第一æ¥çš„詳細解釋ä¸æ‰€æ到的：與大多數程åºå“¡ä¸€æ¨£ï¼Œèˆ‡å¤§å¤šæ•¸ç¨‹åºå“¡ä¸€æ¨£ï¼ŒLinux +å…§æ ¸é–‹ç™¼äººå“¡ä¸å–œæ¡èŠ±æ™‚間處ç†ä»–們ç¶è·çš„æºä»£ç¢¼ä¸æ ¹æœ¬ä¸æœƒç™¼ç”Ÿçš„å•é¡Œçš„å ±å‘Šã€‚é€™éš» 會浪費æ¯å€‹äººçš„æ™‚é–“ï¼Œå°¤å…¶æ˜¯ä½ çš„æ™‚é–“ã€‚é€™å°±æ˜¯çˆ²ä»€éº¼åœ¨å ±å‘Šå•é¡Œä¹‹å‰ï¼Œæ‚¨å¿…é ˆå…ˆç¢ºèª å•é¡Œä»ç„¶å˜åœ¨æ–¼æœ€æ–°çš„上游代碼ä¸ï¼Œé€™ç¬¦åˆæ¯å€‹äººçš„利益。您å¯ä»¥å¿½ç•¥æ¤å»ºè°ï¼Œä½†å¦‚å‰ æ‰€è¿°ï¼šé€™æ¨£åšæœƒæ¥µå¤§åœ°å¢žåŠ å•é¡Œå ±å‘Šè¢«æ‹’絕或被忽略的風險。 -å…§æ ¸ã€Œæœ€æ–°ä¸Šæ¸¸ã€çš„範åœé€šå¸¸æŒ‡ï¼š +å…§æ ¸â€œæœ€æ–°ä¸Šæ¸¸â€çš„範åœé€šå¸¸æŒ‡ï¼š * 安è£ä¸€å€‹ä¸»ç·šå…§æ ¸ï¼›æœ€æ–°çš„ç©©å®šç‰ˆå…§æ ¸ä¹Ÿå¯ä»¥æ˜¯ä¸€å€‹é¸æ“‡ï¼Œä½†å¤§å¤šæ•¸æ™‚候都最好é¿å…。 - 長期支æŒå…§æ ¸ï¼ˆæœ‰æ™‚稱爲「LTSå…§æ ¸ã€ï¼‰ä¸é©åˆæ¤æµç¨‹ã€‚下一å°ç¯€å°‡æ›´è©³ç´°åœ°è§£é‡‹æ‰€æœ‰ + 長期支æŒå…§æ ¸ï¼ˆæœ‰æ™‚稱爲“LTSå…§æ ¸â€ï¼‰ä¸é©åˆæ¤æµç¨‹ã€‚下一å°ç¯€å°‡æ›´è©³ç´°åœ°è§£é‡‹æ‰€æœ‰ 這些。 * 下一å°ç¯€æè¿°ç²å–和安è£é€™æ¨£ä¸€å€‹å…§æ ¸çš„方法。它還指出了使用é ç·¨è¯å…§æ ¸æ˜¯å¯ä»¥çš„， - ä½†æ™®é€šçš„å…§æ ¸æ›´å¥½ï¼Œé€™æ„味著：它是直接使用從 `kernel.org <https://kernel.org/>`_ - ç²å¾—çš„Linux原始碼構建並且沒有任何方å¼ä¿®æ”¹æˆ–增強。 + ä½†æ™®é€šçš„å…§æ ¸æ›´å¥½ï¼Œé€™æ„味ç€ï¼šå®ƒæ˜¯ç›´æŽ¥ä½¿ç”¨å¾ž `kernel.org <https://kernel.org/>`_ + ç²å¾—çš„Linuxæºä»£ç¢¼æ§‹å»ºä¸¦ä¸”沒有任何方å¼ä¿®æ”¹æˆ–增強。 é¸æ“‡é©åˆæ¸¬è©¦çš„版本 ~~~~~~~~~~~~~~~~~~~~ -å‰å¾€ `kernel.org <https://kernel.org/>`_ 來決定使用哪個版本。忽略那個寫著 -「Latest release最新版本ã€çš„å·¨å¤§é»ƒè‰²æŒ‰éˆ•ï¼Œå¾€ä¸‹çœ‹æœ‰ä¸€å€‹è¡¨æ ¼ã€‚åœ¨è¡¨æ ¼çš„é ‚éƒ¨ï¼Œä½ æœƒ -看到一行以「mainlineã€é–‹é çš„å—樣，大多數情æ³ä¸‹å®ƒæœƒæŒ‡å‘一個版本號類似「5.8-rc2〠-çš„é ç™¼å¸ƒç‰ˆæœ¬ã€‚å¦‚æžœæ˜¯é€™æ¨£çš„è©±ï¼Œä½ å°‡éœ€è¦ä½¿ç”¨é€™å€‹ä¸»ç·šå…§æ ¸é€²è¡Œæ¸¬è©¦ã€‚ä¸è¦è®“「rc〠-åš‡åˆ°ä½ ï¼Œé€™äº›ã€Œé–‹ç™¼ç‰ˆå…§æ ¸ã€å¯¦éš›ä¸Šéžå¸¸å¯é â€”â€”è€Œä¸”ä½ å·²ç¶“æŒ‰ç…§ä¸Šé¢çš„指示åšäº†å‚™ä»½ï¼Œ +å‰å¾€ `kernel.org <https://kernel.org/>`_ ä¾†æ±ºå®šä½¿ç”¨å“ªå€‹ç‰ˆæœ¬ã€‚å¿½ç•¥é‚£å€‹å¯«ç€ +“Latest release最新版本â€çš„å·¨å¤§é»ƒè‰²æŒ‰éˆ•ï¼Œå¾€ä¸‹çœ‹æœ‰ä¸€å€‹è¡¨æ ¼ã€‚åœ¨è¡¨æ ¼çš„é ‚éƒ¨ï¼Œä½ æœƒ +看到一行以“mainlineâ€é–‹é çš„å—樣，大多數情æ³ä¸‹å®ƒæœƒæŒ‡å‘一個版本號類似“5.8-rc2†+çš„é ç™¼ä½ˆç‰ˆæœ¬ã€‚å¦‚æžœæ˜¯é€™æ¨£çš„è©±ï¼Œä½ å°‡éœ€è¦ä½¿ç”¨é€™å€‹ä¸»ç·šå…§æ ¸é€²è¡Œæ¸¬è©¦ã€‚ä¸è¦è®““rc†+åš‡åˆ°ä½ ï¼Œé€™äº›â€œé–‹ç™¼ç‰ˆå…§æ ¸â€å¯¦éš›ä¸Šéžå¸¸å¯é â€”â€”è€Œä¸”ä½ å·²ç¶“æŒ‰ç…§ä¸Šé¢çš„指示åšäº†å‚™ä»½ï¼Œ ä¸æ˜¯å—Žï¼Ÿ -大概æ¯ä¹åˆ°å周，「mainlineã€å¯èƒ½æœƒçµ¦ä½ 指出一個版本號類似「5.7ã€çš„æ£å¼ç‰ˆæœ¬ã€‚如果 -碰見這種情æ³ï¼Œè«‹è€ƒæ…®æš«åœå ±å‘ŠéŽç¨‹ï¼Œç›´åˆ°ä¸‹ä¸€å€‹ç‰ˆæœ¬çš„第一個é 發布（5.8-rc1）出 -ç¾åœ¨ `kernel.org <https://kernel.org/>`_ ä¸Šã€‚é€™æ˜¯å› çˆ² Linux 的開發周期æ£åœ¨ -兩周的「åˆä½µçª—å£ã€å…§ã€‚大部分的改動和所有干擾性的改動都會在這段時間內被åˆä½µåˆ° +大概æ¯ä¹åˆ°å週，“mainlineâ€å¯èƒ½æœƒçµ¦ä½ 指出一個版本號類似“5.7â€çš„æ£å¼ç‰ˆæœ¬ã€‚如果 +碰見這種情æ³ï¼Œè«‹è€ƒæ…®æš«åœå ±å‘ŠéŽç¨‹ï¼Œç›´åˆ°ä¸‹ä¸€å€‹ç‰ˆæœ¬çš„第一個é 發佈（5.8-rc1）出 +ç¾åœ¨ `kernel.org <https://kernel.org/>`_ ä¸Šã€‚é€™æ˜¯å› çˆ² Linux 的開發週期æ£åœ¨ +兩週的“åˆä½µçª—å£â€å…§ã€‚大部分的改動和所有干擾性的改動都會在這段時間內被åˆä½µåˆ° 下一個版本ä¸ã€‚在æ¤æœŸé–“使用主線是比較å±éšªçš„ã€‚å…§æ ¸é–‹ç™¼è€…é€šå¸¸ä¹Ÿå¾ˆå¿™ï¼Œå¯èƒ½æ²’有 多餘的時間來處ç†å•é¡Œå ±å‘Šã€‚這也是很有å¯èƒ½åœ¨åˆä½µçª—å£ä¸æ‡‰ç”¨äº†è¨±å¤šä¿®æ”¹ä¾†ä¿®å¾©ä½ -所é¢è‡¨çš„å•é¡Œï¼›é€™å°±æ˜¯çˆ²ä»€éº¼ä½ å¾ˆå¿«å°±å¾—ç”¨ä¸€å€‹æ–°çš„å…§æ ¸ç‰ˆæœ¬é‡æ–°æ¸¬è©¦ï¼Œå°±åƒä¸‹é¢ã€Œç™¼ -å¸ƒå ±å‘Šå¾Œçš„è²¬ä»»ã€ä¸€ç¯€ä¸æ‰€è¿°çš„那樣。 +所é¢è‡¨çš„å•é¡Œï¼›é€™å°±æ˜¯çˆ²ä»€éº¼ä½ å¾ˆå¿«å°±å¾—ç”¨ä¸€å€‹æ–°çš„å…§æ ¸ç‰ˆæœ¬é‡æ–°æ¸¬è©¦ï¼Œå°±åƒä¸‹é¢â€œç™¼ +å¸ƒå ±å‘Šå¾Œçš„è²¬ä»»â€ä¸€ç¯€ä¸æ‰€è¿°çš„那樣。 -這就是爲什麼è¦ç‰åˆ°åˆä½µçª—å£çµæŸå¾Œæ‰åŽ»åšã€‚ä½†æ˜¯å¦‚æžœä½ è™•ç†çš„是一些ä¸æ‡‰è©²ç‰å¾…çš„ +這就是爲什麼è¦ç‰åˆ°åˆä½µçª—å£çµæŸå¾Œçº”去åšã€‚ä½†æ˜¯å¦‚æžœä½ è™•ç†çš„是一些ä¸æ‡‰è©²ç‰å¾…çš„ æ±è¥¿ï¼Œå‰‡ç„¡éœ€é€™æ¨£åšã€‚在這種情æ³ä¸‹ï¼Œå¯ä»¥è€ƒæ…®é€šéŽ git ç²å–æœ€æ–°çš„ä¸»ç·šå…§æ ¸ï¼ˆè¦‹ä¸‹ 文），或者使用 kernel.org 上æ供的最新穩定版本。如果 mainline å› çˆ²æŸäº›åŽŸå› ä¸ç„¡æ³•æ£å¸¸å·¥ä½œï¼Œé‚£éº¼ä½¿ç”¨å®ƒä¹Ÿæ˜¯å¯ä»¥æŽ¥å—的。總的來說：用它來é‡ç¾å•é¡Œä¹Ÿæ¯”完全 @@ -657,7 +652,7 @@ ath10k@lists.infradead.orgã€ï¼Œå°‡å¼•å°Žæ‚¨åˆ°ath10k郵件列表的信æ¯é ， 需è¦å…ˆåœ¨ä¸»ç·šä¿®å¾©ï¼Œç„¶å¾Œæ‰èƒ½å¾—到回傳，這å¯èƒ½éœ€è¦å¹¾å¤©æˆ–幾周。å¦ä¸€å€‹åŽŸå› 是：您 希望的修復å°æ–¼å›žå‚³ä¾†èªªå¯èƒ½å¤ªé›£æˆ–å¤ªå†’éšªï¼›å› æ¤å†æ¬¡å ±å‘Šå•é¡Œä¸å¤ªå¯èƒ½æ”¹è®Šä»»ä½•äº‹æƒ…。 -這些方é¢ä¹Ÿéƒ¨åˆ†è¡¨æ˜Žäº†çˆ²ä»€éº¼é•·æœŸæ”¯æŒå…§æ ¸ï¼ˆæœ‰æ™‚稱爲「LTSå…§æ ¸ã€ï¼‰ä¸é©åˆå ±å‘Šæµç¨‹ï¼š +這些方é¢ä¹Ÿéƒ¨åˆ†è¡¨æ˜Žäº†çˆ²ä»€éº¼é•·æœŸæ”¯æŒå…§æ ¸ï¼ˆæœ‰æ™‚稱爲“LTSå…§æ ¸â€ï¼‰ä¸é©åˆå ±å‘Šæµç¨‹ï¼š 它們與當å‰ä»£ç¢¼çš„è·é›¢å¤ªé ã€‚å› æ¤ï¼Œå…ˆåŽ»æ¸¬è©¦ä¸»ç·šï¼Œç„¶å¾Œå†æŒ‰æµç¨‹èµ°ï¼šå¦‚果主線沒有 出ç¾å•é¡Œï¼Œæµç¨‹å°‡æŒ‡å°Žæ‚¨å¦‚何在舊版本線ä¸ä¿®å¾©å®ƒã€‚ @@ -669,31 +664,31 @@ ath10k@lists.infradead.orgã€ï¼Œå°‡å¼•å°Žæ‚¨åˆ°ath10k郵件列表的信æ¯é ， **使用é ç·¨è¯çš„å…§æ ¸** ：這往往是最快速ã€æœ€ç°¡å–®ã€æœ€å®‰å…¨çš„æ–¹æ³•â€”â€”å°¤å…¶æ˜¯åœ¨ä½ ä¸ç†Ÿ 悉 Linux å…§æ ¸çš„æƒ…æ³ä¸‹ã€‚å•é¡Œæ˜¯ï¼šç™¼è¡Œå•†æˆ–é™„åŠ å˜å„²åº«æ供的大多數版本都是從修改 -éŽçš„LinuxåŽŸå§‹ç¢¼æ§‹å»ºçš„ã€‚å› æ¤å®ƒå€‘ä¸æ˜¯æ™®é€šçš„，通常ä¸é©åˆæ–¼æ¸¬è©¦å’Œå•é¡Œå ±å‘Šï¼šé€™äº› +éŽçš„Linuxæºä»£ç¢¼æ§‹å»ºçš„ã€‚å› æ¤å®ƒå€‘ä¸æ˜¯æ™®é€šçš„，通常ä¸é©åˆæ–¼æ¸¬è©¦å’Œå•é¡Œå ±å‘Šï¼šé€™äº› 更改å¯èƒ½æœƒå°Žè‡´æ‚¨é¢è‡¨çš„å•é¡Œæˆ–以æŸç¨®æ–¹å¼å½±éŸ¿å•é¡Œã€‚ 但是如果您使用的是æµè¡Œçš„Linux發行版，那麼您就很幸é‹äº†ï¼šå°æ–¼å¤§éƒ¨åˆ†çš„發行版， 您å¯ä»¥åœ¨ç¶²ä¸Šæ‰¾åˆ°åŒ…å«æœ€æ–°ä¸»ç·šæˆ–穩定版本Linuxå…§æ ¸åŒ…çš„å˜å„²åº«ã€‚ä½¿ç”¨é€™äº›æ˜¯å®Œå…¨å¯ -以的，åªè¦å¾žå˜å„²åº«çš„æè¿°ä¸ç¢ºèªå®ƒå€‘是普通的或者至少接近普通。æ¤å¤–，請確ä¿è»Ÿé«” -包包å«kernel.org上æä¾›çš„æœ€æ–°ç‰ˆæœ¬å…§æ ¸ã€‚å¦‚æžœé€™äº›è»Ÿé«”åŒ…çš„æ™‚é–“è¶…éŽä¸€å‘¨ï¼Œé‚£éº¼å®ƒå€‘ -å¯èƒ½å°±ä¸åˆé©äº†ï¼Œå› çˆ²æ–°çš„ä¸»ç·šå’Œç©©å®šç‰ˆå…§æ ¸é€šå¸¸è‡³å°‘æ¯å‘¨ç™¼å¸ƒä¸€æ¬¡ã€‚ +以的，åªè¦å¾žå˜å„²åº«çš„æè¿°ä¸ç¢ºèªå®ƒå€‘是普通的或者至少接近普通。æ¤å¤–，請確ä¿è»Ÿä»¶ +包包å«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 å…§æ ¸åŽŸå§‹ç¢¼ã€‚é€™äº›å¾ˆå¯èƒ½æ¯”最新的主線é ç™¼å¸ƒç‰ˆæœ¬æ›´æ–°ä¸€äº›ã€‚ä¸ -用擔心：它們和æ£å¼çš„é 發布版本一樣å¯é ，除éžå…§æ ¸çš„開發周期目å‰æ£è™•æ–¼åˆä½µçª— +ä¸ç²å–最新的 Linux å…§æ ¸æºä»£ç¢¼ã€‚這些很å¯èƒ½æ¯”最新的主線é ç™¼ä½ˆç‰ˆæœ¬æ›´æ–°ä¸€äº›ã€‚ä¸ +用擔心：它們和æ£å¼çš„é 發佈版本一樣å¯é ，除éžå…§æ ¸çš„開發週期目å‰æ£è™•æ–¼åˆä½µçª— å£ä¸ã€‚ä¸éŽå³ä¾¿å¦‚æ¤ï¼Œå®ƒå€‘也是相當å¯é 的。 **常è¦æ–¹æ³•** ：ä¸ç†Ÿæ‚‰ git 的人通常最好從 `kernel.org <https://kernel.org/>`_ 下載æºç¢¼çš„tar å˜æª”包。 -å¦‚ä½•å¯¦éš›æ§‹å»ºä¸€å€‹å…§æ ¸ä¸¦ä¸åœ¨é€™è£¡æè¿°ï¼Œå› çˆ²è¨±å¤šç¶²ç«™å·²ç¶“è§£é‡‹äº†å¿…è¦çš„æ¥é©Ÿã€‚如果 +å¦‚ä½•å¯¦éš›æ§‹å»ºä¸€å€‹å…§æ ¸ä¸¦ä¸åœ¨é€™è£æè¿°ï¼Œå› çˆ²è¨±å¤šç¶²ç«™å·²ç¶“è§£é‡‹äº†å¿…è¦çš„æ¥é©Ÿã€‚如果 ä½ æ˜¯æ–°æ‰‹ï¼Œå¯ä»¥è€ƒæ…®æŒ‰ç…§é‚£äº›å»ºè°ä½¿ç”¨ ``make localmodconfig`` 來åšï¼Œå®ƒå°‡å˜—è©¦ç² å–ä½ ç•¶å‰å…§æ ¸çš„é…ç½®ï¼Œç„¶å¾Œæ ¹æ“šä½ çš„ç³»çµ±é€²è¡Œä¸€äº›èª¿æ•´ã€‚é€™æ¨£åšä¸¦ä¸èƒ½ä½¿ç·¨è¯å‡ºä¾†çš„ å…§æ ¸æ›´å¥½ï¼Œä½†å¯ä»¥æ›´å¿«åœ°ç·¨è¯ã€‚ @@ -702,19 +697,19 @@ ath10k@lists.infradead.orgã€ï¼Œå°‡å¼•å°Žæ‚¨åˆ°ath10k郵件列表的信æ¯é ， 啓用 CONFIG_KALLSYMS é¸é …。æ¤å¤–，還å¯ä»¥å•“用 CONFIG_DEBUG_KERNEL å’Œ CONFIG_DEBUG_INFO；後者是相關é¸é …，但åªæœ‰å•“用å‰è€…æ‰èƒ½é–‹å•“。請注æ„， CONFIG_DEBUG_INFO 會需è¦æ›´å¤šå„²å˜ç©ºé–“ä¾†æ§‹å»ºå…§æ ¸ã€‚ä½†é€™æ˜¯å€¼å¾—çš„ï¼Œå› çˆ²é€™äº›é¸é …å°‡ -å…許您ç¨å¾Œç²¾ç¢ºå®šä½è§¸ç™¼å•é¡Œçš„確切代碼行。下é¢çš„「解碼失敗信æ¯ã€ä¸€ç¯€å°æ¤é€²è¡Œäº†æ›´ +å…許您ç¨å¾Œç²¾ç¢ºå®šä½è§¸ç™¼å•é¡Œçš„確切代碼行。下é¢çš„“解碼失敗信æ¯â€ä¸€ç¯€å°æ¤é€²è¡Œäº†æ›´ 詳細的解釋。 但請記ä½ï¼šå§‹çµ‚記錄é‡åˆ°çš„å•é¡Œï¼Œä»¥é˜²é›£ä»¥é‡ç¾ã€‚發é€æœªè§£ç¢¼çš„å ±å‘Šç¸½æ¯”ä¸å ±å‘Šè¦å¥½ã€‚ -檢查「汙染ã€æ¨™èªŒ +檢查“污染â€æ¨™èªŒ ---------------- - *確ä¿æ‚¨å‰›å‰›å®‰è£çš„å…§æ ¸åœ¨é‹è¡Œæ™‚ä¸æœƒã€Œæ±™æŸ“ã€è‡ªå·±ã€‚* + *確ä¿æ‚¨å‰›å‰›å®‰è£çš„å…§æ ¸åœ¨é‹è¡Œæ™‚ä¸æœƒâ€œæ±¡æŸ“â€è‡ªå·±ã€‚* æ£å¦‚上é¢å·²ç¶“詳細介紹éŽçš„：當發生一些å¯èƒ½æœƒå°Žè‡´ä¸€äº›çœ‹èµ·ä¾†å®Œå…¨ä¸ç›¸é—œçš„後續錯 -èª¤çš„äº‹æƒ…æ™‚ï¼Œå…§æ ¸æœƒè¨ç½®ä¸€å€‹ã€Œæ±™æŸ“ã€æ¨™èªŒã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ éœ€è¦æª¢æŸ¥ä½ 剛剛安è£çš„å…§ +èª¤çš„äº‹æƒ…æ™‚ï¼Œå…§æ ¸æœƒè¨ç½®ä¸€å€‹â€œæ±¡æŸ“â€æ¨™èªŒã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ éœ€è¦æª¢æŸ¥ä½ 剛剛安è£çš„å…§ æ ¸æ˜¯å¦æœ‰è¨ç½®æ¤æ¨™èªŒã€‚如果有的話，幾乎在任何情æ³ä¸‹ä½ 都需è¦åœ¨å ±å‘Šå•é¡Œä¹‹å‰å…ˆæ¶ˆ 除它。詳細的æ“作方法請看上é¢çš„ç« ç¯€ã€‚ @@ -729,43 +724,43 @@ CONFIG_DEBUG_INFO 會需è¦æ›´å¤šå„²å˜ç©ºé–“ä¾†æ§‹å»ºå…§æ ¸ã€‚ä½†é€™æ˜¯å€¼å¾—çš å¯ä»¥è€ƒæ…®ä½¿ç”¨æ¤ç‰ˆæœ¬ç·šï¼Œæ”¾æ£„å ±å‘Šå•é¡Œã€‚但是請記ä½ï¼Œåªè¦å®ƒæ²’有在 `kernel.org <https://kernel.org/>`_ 的穩定版和長期版（以åŠç”±é€™äº›ç‰ˆæœ¬è¡ç”Ÿå‡ºä¾†çš„å» å•†å…§æ ¸ï¼‰ ä¸å¾—到修復，其他用戶å¯èƒ½ä»ç„¶æœƒå—åˆ°å®ƒçš„å›°æ“¾ã€‚å¦‚æžœä½ å–œæ¡ä½¿ç”¨å…¶ä¸çš„一個，或 -者åªæ˜¯æƒ³å¹«åŠ©å®ƒå€‘的用戶，請å‰å¾€ä¸‹é¢çš„ã€Œå ±å‘Šåªç™¼ç”Ÿåœ¨è¼ƒèˆŠå…§æ ¸ç‰ˆæœ¬ç·šçš„å•é¡Œã€ä¸€ç¯€ã€‚ +者åªæ˜¯æƒ³å¹«åŠ©å®ƒå€‘的用戶，請å‰å¾€ä¸‹é¢çš„â€œå ±å‘Šåªç™¼ç”Ÿåœ¨è¼ƒèˆŠå…§æ ¸ç‰ˆæœ¬ç·šçš„å•é¡Œâ€ä¸€ç¯€ã€‚ 優化復ç¾å•é¡Œçš„æè¿° -------------------- - *å„ªåŒ–ä½ çš„ç†è¨˜ï¼šè©¦è‘—找到並寫出最直接的復ç¾å•é¡Œçš„方法。確ä¿æœ€çµ‚çµæžœåŒ…å«æ‰€ + *å„ªåŒ–ä½ çš„ç†è¨˜ï¼šè©¦ç€æ‰¾åˆ°ä¸¦å¯«å‡ºæœ€ç›´æŽ¥çš„復ç¾å•é¡Œçš„方法。確ä¿æœ€çµ‚çµæžœåŒ…å«æ‰€ 有é‡è¦çš„細節，åŒæ™‚讓第一次è½èªªçš„人容易閱讀和ç†è§£ã€‚如果您在æ¤éŽç¨‹ä¸å¸åˆ° 了一些æ±è¥¿ï¼Œè«‹è€ƒæ…®å†æ¬¡æœç´¢é—œæ–¼è©²å•é¡Œçš„ç¾æœ‰å ±å‘Šã€‚* éŽæ–¼è¤‡é›œçš„å ±å‘Šæœƒè®“åˆ¥äººå¾ˆé›£ç†è§£ã€‚å› æ¤è«‹å„˜é‡æ‰¾åˆ°ä¸€å€‹å¯ä»¥ç›´æŽ¥æè¿°ã€æ˜“æ–¼ä»¥æ›¸é¢ å½¢å¼ç†è§£çš„å†ç¾æ–¹æ³•ã€‚包å«æ‰€æœ‰é‡è¦çš„細節，但åŒæ™‚也è¦å„˜é‡ä¿æŒç°¡çŸã€‚ -在這在å‰é¢çš„æ¥é©Ÿä¸ï¼Œä½ 很å¯èƒ½å·²ç¶“äº†è§£äº†ä¸€äº›é—œæ–¼ä½ æ‰€é¢è‡¨çš„å•é¡Œçš„點。利用這些 +在這在å‰é¢çš„æ¥é©Ÿä¸ï¼Œä½ 很å¯èƒ½å·²ç¶“çžè§£äº†ä¸€äº›é—œæ–¼ä½ 所é¢è‡¨çš„å•é¡Œçš„點。利用這些 知è˜ï¼Œå†æ¬¡æœç´¢å¯ä»¥è½‰è€ŒåŠ 入的ç¾æœ‰å ±å‘Šã€‚ è§£ç¢¼å¤±æ•—ä¿¡æ¯ ------------- - *如果失敗涉åŠã€Œpanicã€ã€ã€ŒOopsã€ã€ã€Œwarningã€æˆ–「BUGã€ï¼Œè«‹è€ƒæ…®è§£ç¢¼å…§æ ¸æ—¥èªŒä»¥æŸ¥æ‰¾ + *如果失敗涉åŠâ€œpanicâ€ã€â€œOopsâ€ã€â€œwarningâ€æˆ–“BUGâ€ï¼Œè«‹è€ƒæ…®è§£ç¢¼å…§æ ¸æ—¥èªŒä»¥æŸ¥æ‰¾ 觸發錯誤的代碼行。* -ç•¶å…§æ ¸æª¢æ¸¬åˆ°å…§éƒ¨å•é¡Œæ™‚，它會記錄一些有關已執行代碼的信æ¯ã€‚這使得在原始碼ä¸ç²¾ +ç•¶å…§æ ¸æª¢æ¸¬åˆ°å…§éƒ¨å•é¡Œæ™‚，它會記錄一些有關已執行代碼的信æ¯ã€‚這使得在æºä»£ç¢¼ä¸ç²¾ 確定ä½è§¸ç™¼å•é¡Œçš„行並顯示如何調用它æˆçˆ²å¯èƒ½ã€‚但åªæœ‰åœ¨é…ç½®å…§æ ¸æ™‚å•“ç”¨äº† CONFIG_DEBUG_INFO å’Œ CONFIG_KALLSYMSé¸é …時，這種方法æ‰èµ·æ•ˆã€‚如果已啓用æ¤é¸é …， -è«‹è€ƒæ…®è§£ç¢¼å…§æ ¸æ—¥èªŒä¸çš„ä¿¡æ¯ã€‚這將使我們更容易ç†è§£æ˜¯ä»€éº¼å°Žè‡´äº†ã€Œpanicã€ã€ã€ŒOopsã€ã€ -「warningã€æˆ–「BUGã€ï¼Œå¾žè€Œå¢žåŠ 了有人æ供修復的機率。 +è«‹è€ƒæ…®è§£ç¢¼å…§æ ¸æ—¥èªŒä¸çš„ä¿¡æ¯ã€‚這將使我們更容易ç†è§£æ˜¯ä»€éº¼å°Žè‡´äº†â€œpanicâ€ã€â€œOopsâ€ã€ +“warningâ€æˆ–“BUGâ€ï¼Œå¾žè€Œå¢žåŠ 了有人æ供修復的幾率。 -解碼å¯ä»¥é€šéŽLinux原始碼樹ä¸çš„腳本來完æˆã€‚如果您é‹è¡Œçš„å…§æ ¸æ˜¯ä¹‹å‰è‡ªå·±ç·¨è¯çš„， +解碼å¯ä»¥é€šéŽ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原始碼ç²å–）:: +æ–¹å¼èª¿ç”¨è…³æœ¬ï¼ˆå¦‚果發行版未打包，則å¯èƒ½éœ€è¦å¾ž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/ @@ -778,10 +773,10 @@ CONFIG_DEBUG_INFO å’Œ CONFIG_KALLSYMSé¸é …時，這種方法æ‰èµ·æ•ˆã€‚如果å [ 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ã€æ§‹å»ºçš„， +在本例ä¸ï¼ŒåŸ·è¡Œçš„代碼是從文件“~/linux-5.10.5/test-module/test-module.câ€æ§‹å»ºçš„， 錯誤出ç¾åœ¨ç¬¬16行的指令ä¸ã€‚ -該腳本也會如æ¤è§£ç¢¼ä»¥ã€ŒCall traceã€é–‹é 的部分ä¸æ到的地å€ï¼Œè©²éƒ¨åˆ†é¡¯ç¤ºå‡ºç¾å•é¡Œçš„ +該腳本也會如æ¤è§£ç¢¼ä»¥â€œCall traceâ€é–‹é 的部分ä¸æ到的地å€ï¼Œè©²éƒ¨åˆ†é¡¯ç¤ºå‡ºç¾å•é¡Œçš„ 函數的路徑。æ¤å¤–ï¼Œè…³æœ¬é‚„æœƒé¡¯ç¤ºå…§æ ¸æ£åœ¨åŸ·è¡Œçš„代碼部分的彙編輸出。 注æ„ï¼Œå¦‚æžœä½ æ²’æ³•åšåˆ°é€™ä¸€é»žï¼Œåªéœ€è·³éŽé€™ä¸€æ¥ï¼Œä¸¦åœ¨å ±å‘Šä¸èªªæ˜ŽåŽŸå› ã€‚å¦‚æžœä½ å¹¸é‹çš„ @@ -790,60 +785,60 @@ CONFIG_DEBUG_INFO å’Œ CONFIG_KALLSYMSé¸é …時，這種方法æ‰èµ·æ•ˆã€‚如果å 別擔心，如果您碰到的情æ³éœ€è¦é€™æ¨£åšï¼Œé–‹ç™¼äººå“¡æœƒå‘Šè¨´æ‚¨è©²æ€Žéº¼åšã€‚ -å°å›žæ¸çš„特別關照 +å°è¿´æ¸çš„特別關照 ----------------- - *如果您的å•é¡Œæ˜¯å›žæ¸å•é¡Œï¼Œè«‹å„˜å¯èƒ½ç¸®å°å¼•å…¥å•é¡Œæ™‚的範åœã€‚* + *如果您的å•é¡Œæ˜¯è¿´æ¸å•é¡Œï¼Œè«‹å„˜å¯èƒ½ç¸®å°å¼•å…¥å•é¡Œæ™‚的範åœã€‚* Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這就是爲什麼他 -èªçˆ²å›žæ¸æ˜¯ä¸å¯æŽ¥å—的，並希望看到它們被迅速修復。這就是爲什麼引入了回æ¸çš„改 -動導致的å•é¡Œè‹¥ç„¡æ³•é€šéŽå…¶ä»–æ–¹å¼å¿«é€Ÿè§£æ±ºï¼Œé€šå¸¸æœƒè¢«è¿…é€Ÿæ’¤éŠ·ã€‚å› æ¤ï¼Œå ±å‘Šå›žæ¸æœ‰ -點åƒã€ŒçŽ‹ç‚¸ã€ï¼Œæœƒè¿…速得到修復。但è¦åšåˆ°é€™ä¸€é»žï¼Œéœ€è¦çŸ¥é“導致回æ¸çš„變化。通常情 +èªçˆ²è¿´æ¸æ˜¯ä¸å¯æŽ¥å—的，並希望看到它們被迅速修復。這就是爲什麼引入了迴æ¸çš„改 +動導致的å•é¡Œè‹¥ç„¡æ³•é€šéŽå…¶ä»–æ–¹å¼å¿«é€Ÿè§£æ±ºï¼Œé€šå¸¸æœƒè¢«è¿…é€Ÿæ’¤éŠ·ã€‚å› æ¤ï¼Œå ±å‘Šè¿´æ¸æœ‰ +點åƒâ€œçŽ‹ç‚¸â€ï¼Œæœƒè¿…速得到修復。但è¦åšåˆ°é€™ä¸€é»žï¼Œéœ€è¦çŸ¥é“導致迴æ¸çš„變化。通常情 æ³ä¸‹ï¼Œè¦ç”±å ±å‘Šè€…來追查罪éç¦é¦–ï¼Œå› çˆ²ç¶è·è€…往往沒有時間或手é è¨ç½®ä¸ä¾¿ä¾†è‡ªè¡Œ é‡ç¾å®ƒã€‚ -有一個å«åšã€ŒäºŒåˆ†ã€çš„éŽç¨‹å¯ä»¥ä¾†å°‹æ‰¾è®ŠåŒ–，這在 -「Documentation/translations/zh_TW/admin-guide/bug-bisect.rstã€æ–‡æª”ä¸é€²è¡Œäº†è©³ç´° +有一個å«åšâ€œäºŒåˆ†â€çš„éŽç¨‹å¯ä»¥ä¾†å°‹æ‰¾è®ŠåŒ–，這在 +Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 文檔ä¸é€²è¡Œäº†è©³ç´° çš„æ述，這個éŽç¨‹é€šå¸¸éœ€è¦ä½ 構建å到二åå€‹å…§æ ¸é¡åƒï¼Œæ¯æ¬¡éƒ½å˜—試在構建下一個é¡åƒ -之å‰é‡ç¾å•é¡Œã€‚是的，這需è¦èŠ±è²»ä¸€äº›æ™‚間，但ä¸ç”¨æ“”心，它比大多數人想åƒçš„è¦å¿«å¾—多。 -多虧了「binary search二進ä½æœç´¢ã€ï¼Œé€™å°‡å¼•å°Žä½ 在原始碼管ç†ç³»çµ±ä¸æ‰¾åˆ°å°Žè‡´å›žæ¸çš„æ交。 +之å‰é‡ç¾å•é¡Œã€‚是的，這需è¦èŠ±è²»ä¸€äº›æ™‚間，但ä¸ç”¨æ“”心，它比大多數人想象的è¦å¿«å¾—多。 +多虧了“binary search二分æœç´¢â€ï¼Œé€™å°‡å¼•å°Žä½ 在æºä»£ç¢¼ç®¡ç†ç³»çµ±ä¸æ‰¾åˆ°å°Žè‡´è¿´æ¸çš„æ交。 ä¸€æ—¦ä½ æ‰¾åˆ°å®ƒï¼Œå°±åœ¨ç¶²ä¸Šæœç´¢å…¶ä¸»é¡Œã€æ交ID和縮çŸçš„æ交ID（æ交IDçš„å‰12個å—符）。 如果有的話，這將引導您找到關於它的ç¾æœ‰å ±å‘Šã€‚ 需è¦æ³¨æ„的是，二分法需è¦ä¸€é»žç«…門，ä¸æ˜¯æ¯å€‹äººéƒ½æ‡‚得訣竅，也需è¦ç›¸ç•¶å¤šçš„努力， ä¸æ˜¯æ¯å€‹äººéƒ½é¡˜æ„投入。儘管如æ¤ï¼Œé‚„是強烈建è°è‡ªå·±é€²è¡Œä¸€æ¬¡äºŒåˆ†ã€‚å¦‚æžœä½ çœŸçš„ -ä¸èƒ½æˆ–者ä¸æƒ³èµ°é€™æ¢è·¯ï¼Œè‡³å°‘è¦æ‰¾å‡ºæ˜¯å“ªå€‹ä¸»ç·šå…§æ ¸å¼•å…¥çš„回æ¸ã€‚比如說從 5.5.15 +ä¸èƒ½æˆ–者ä¸æƒ³èµ°é€™æ¢è·¯ï¼Œè‡³å°‘è¦æ‰¾å‡ºæ˜¯å“ªå€‹ä¸»ç·šå…§æ ¸å¼•å…¥çš„è¿´æ¸ã€‚比如說從 5.5.15 切æ›åˆ° 5.8.4 的時候出ç¾äº†ä¸€äº›å•é¡Œï¼Œé‚£éº¼è‡³å°‘å¯ä»¥å˜—試一下相近的所有的主線版本 （5.6ã€5.7 å’Œ 5.8）來檢查它是什麼時候出ç¾çš„。除éžä½ æƒ³åœ¨ä¸€å€‹ç©©å®šç‰ˆæˆ–é•·æœŸæ”¯æŒ -å…§æ ¸ä¸æ‰¾åˆ°ä¸€å€‹å›žæ¸ï¼Œå¦å‰‡è¦é¿å…測試那些編號有三段的版本（5.6.12ã€5.7.8ï¼‰ï¼Œå› -爲那會使çµæžœé›£ä»¥è§£é‡‹ï¼Œå¯èƒ½æœƒè®“ä½ çš„æ¸¬è©¦è®Šå¾—ç„¡ç”¨ã€‚ä¸€æ—¦ä½ æ‰¾åˆ°äº†å¼•å…¥å›žæ¸çš„ä¸»è¦ +å…§æ ¸ä¸æ‰¾åˆ°ä¸€å€‹è¿´æ¸ï¼Œå¦å‰‡è¦é¿å…測試那些編號有三段的版本（5.6.12ã€5.7.8ï¼‰ï¼Œå› +爲那會使çµæžœé›£ä»¥è§£é‡‹ï¼Œå¯èƒ½æœƒè®“ä½ çš„æ¸¬è©¦è®Šå¾—ç„¡ç”¨ã€‚ä¸€æ—¦ä½ æ‰¾åˆ°äº†å¼•å…¥è¿´æ¸çš„ä¸»è¦ ç‰ˆæœ¬ï¼Œå°±å¯ä»¥æ”¾å¿ƒåœ°ç¹¼çºŒå ±å‘Šäº†ã€‚但請記ä½ï¼šåœ¨ä¸çŸ¥é“罪éç¦é¦–的情æ³ä¸‹ï¼Œé–‹ç™¼äººå“¡ 是å¦èƒ½å¤ æ供幫助å–決於手é çš„å•é¡Œã€‚有時他們å¯èƒ½æœƒå¾žå ±å‘Šä¸ç¢ºèªæ˜¯ä»€éº¼å‡ºç¾äº†å• 題，並能修復它；有時他們å¯èƒ½ç„¡æ³•æ供幫助，除éžä½ 進行二分。 -當處ç†å›žæ¸å•é¡Œæ™‚，請確ä¿ä½ 所é¢è‡¨çš„å•é¡ŒçœŸçš„æ˜¯ç”±å…§æ ¸å¼•èµ·çš„ï¼Œè€Œä¸æ˜¯ç”±å…¶ä»–æ±è¥¿ +當處ç†è¿´æ¸å•é¡Œæ™‚，請確ä¿ä½ 所é¢è‡¨çš„å•é¡ŒçœŸçš„æ˜¯ç”±å…§æ ¸å¼•èµ·çš„ï¼Œè€Œä¸æ˜¯ç”±å…¶ä»–æ±è¥¿ 引起的，如上文所述。 -在整個éŽç¨‹ä¸ï¼Œè«‹è¨˜ä½ï¼šåªæœ‰ç•¶èˆŠå…§æ ¸å’Œæ–°å…§æ ¸çš„é…置相似時，å•é¡Œæ‰ç®—回æ¸ã€‚最好 -的方法是：把é…置文件（``.config``ï¼‰å¾žèˆŠçš„å·¥ä½œå…§æ ¸ç›´æŽ¥è¤‡è£½åˆ°ä½ å˜—è©¦çš„æ¯å€‹æ–°å…§ -æ ¸ç‰ˆæœ¬ã€‚ä¹‹å¾Œé‹è¡Œ ``make oldnoconfig`` 來調整它以é©æ‡‰æ–°ç‰ˆæœ¬çš„需è¦ï¼Œè€Œä¸å•“用 -ä»»ä½•æ–°çš„åŠŸèƒ½ï¼Œå› çˆ²é‚£äº›åŠŸèƒ½ä¹Ÿå¯èƒ½å°Žè‡´å›žæ¸ã€‚ +在整個éŽç¨‹ä¸ï¼Œè«‹è¨˜ä½ï¼šåªæœ‰ç•¶èˆŠå…§æ ¸å’Œæ–°å…§æ ¸çš„é…置相似時，å•é¡Œçº”ç®—è¿´æ¸ã€‚這å¯ä»¥ +é€šéŽ ``make olddefconfig`` 來實ç¾ï¼Œè©³ç´°è§£é‡‹åƒè¦‹ +Documentation/admin-guide/reporting-regressions.rst ；它還æ供了大é‡å…¶ä»–您 +å¯èƒ½å¸Œæœ›çžè§£çš„有關回æ¸çš„ä¿¡æ¯ã€‚ -撰寫並發é€å ±å‘Š +撰寫併發é€å ±å‘Š --------------- *通éŽè©³ç´°æè¿°å•é¡Œä¾†é–‹å§‹ç·¨å¯«å ±å‘Šã€‚記得包括以下æ¢ç›®ï¼šæ‚¨çˆ²å¾©ç¾è€Œå®‰è£çš„最新 å…§æ ¸ç‰ˆæœ¬ã€ä½¿ç”¨çš„Linux發行版以åŠé—œæ–¼å¦‚何復ç¾è©²å•é¡Œçš„說明。如果å¯èƒ½ï¼Œå°‡å…§ - æ ¸æ§‹å»ºé…置（.config）和 ``dmesg`` 的輸出放在網上的æŸå€‹åœ°æ–¹ï¼Œä¸¦é€£çµåˆ°å®ƒã€‚ + æ ¸æ§‹å»ºé…置（.config）和 ``dmesg`` 的輸出放在網上的æŸå€‹åœ°æ–¹ï¼Œä¸¦éˆæŽ¥åˆ°å®ƒã€‚ 包å«æˆ–上傳所有其他å¯èƒ½ç›¸é—œçš„ä¿¡æ¯ï¼Œå¦‚Oops的輸出/截圖或來自 ``lspci`` çš„è¼¸å‡ºã€‚ä¸€æ—¦ä½ å¯«å®Œäº†é€™å€‹ä¸»è¦éƒ¨åˆ†ï¼Œè«‹åœ¨ä¸Šæ–¹æ’入一個æ£å¸¸é•·åº¦çš„段è½å¿«é€Ÿæ¦‚ è¿°å•é¡Œå’Œå½±éŸ¿ã€‚å†åœ¨æ¤ä¹‹ä¸Šæ·»åŠ 一個簡單æè¿°å•é¡Œçš„å¥å，以得到人們的閱讀。 ç¾åœ¨çµ¦å‡ºä¸€å€‹æ›´çŸçš„æ述性標題或主題。然後就å¯ä»¥åƒMAINTAINERSæ–‡ä»¶å‘Šè¨´ä½ çš„ - 那樣發é€æˆ–æäº¤å ±å‘Šäº†ï¼Œé™¤éžä½ 在處ç†ä¸€å€‹ã€Œé«˜å„ªå…ˆç´šå•é¡Œã€ï¼šå®ƒå€‘需è¦æŒ‰ç…§ä¸‹é¢ - 「高優先級å•é¡Œçš„特殊處ç†ã€æ‰€è¿°ç‰¹åˆ¥é—œç…§ã€‚* + 那樣發é€æˆ–æäº¤å ±å‘Šäº†ï¼Œé™¤éžä½ 在處ç†ä¸€å€‹â€œé«˜å„ªå…ˆç´šå•é¡Œâ€ï¼šå®ƒå€‘需è¦æŒ‰ç…§ä¸‹é¢ + “高優先級å•é¡Œçš„特殊處ç†â€æ‰€è¿°ç‰¹åˆ¥é—œç…§ã€‚* -ç¾åœ¨ä½ å·²ç¶“æº–å‚™å¥½äº†ä¸€åˆ‡ï¼Œæ˜¯æ™‚å€™å¯«ä½ çš„å ±å‘Šäº†ã€‚ä¸Šæ–‡å‰è¨€ä¸é€£çµçš„三篇文檔å°å¦‚何 +ç¾åœ¨ä½ å·²ç¶“æº–å‚™å¥½äº†ä¸€åˆ‡ï¼Œæ˜¯æ™‚å€™å¯«ä½ çš„å ±å‘Šäº†ã€‚ä¸Šæ–‡å‰è¨€ä¸éˆæŽ¥çš„三篇文檔å°å¦‚何 å¯«å ±å‘Šåšäº†éƒ¨åˆ†è§£é‡‹ã€‚這就是爲什麼本文將åªæåˆ°ä¸€äº›åŸºæœ¬çš„å…§å®¹ä»¥åŠ Linux å…§æ ¸ç‰¹ 有的æ±è¥¿ã€‚ @@ -855,7 +850,7 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 æ¯ä»½å ±å‘Šéƒ½æ‡‰æåŠçš„äº‹é … ~~~~~~~~~~~~~~~~~~~~~~~~ -詳細æè¿°ä½ çš„å•é¡Œæ˜¯å¦‚ä½•ç™¼ç”Ÿåœ¨ä½ å®‰è£çš„æ–°ç´”æ·¨å…§æ ¸ä¸Šçš„ã€‚è©¦è‘—åŒ…å«ä½ 之å‰å¯«çš„和優 +詳細æè¿°ä½ çš„å•é¡Œæ˜¯å¦‚ä½•ç™¼ç”Ÿåœ¨ä½ å®‰è£çš„æ–°ç´”æ·¨å…§æ ¸ä¸Šçš„ã€‚è©¦ç€åŒ…å«ä½ 之å‰å¯«çš„和優 化éŽçš„分æ¥èªªæ˜Žï¼Œæ¦‚è¿°ä½ å’Œå…¶ä»–äººå¦‚ä½•é‡ç¾é€™å€‹å•é¡Œï¼›åœ¨æ¥µå°‘數無法é‡ç¾çš„情æ³ä¸‹ï¼Œ 儘é‡æè¿°ä½ åšäº†ä»€éº¼ä¾†è§¸ç™¼å®ƒã€‚ @@ -864,19 +859,19 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 * ``cat /proc/version`` 的輸出，其ä¸åŒ…å« Linux å…§æ ¸ç‰ˆæœ¬è™Ÿå’Œæ§‹å»ºæ™‚çš„ç·¨è¯å™¨ã€‚ - * 機器æ£åœ¨é‹è¡Œçš„ Linux 發行版（ ``hostnamectl | grep 「Operating System「`` ） + * 機器æ£åœ¨é‹è¡Œçš„ Linux 發行版（ ``hostnamectl | grep “Operating System“`` ） - * CPU 和作æ¥ç³»çµ±çš„架構（ ``uname -mi`` ） + * CPU å’Œæ“作系統的架構（ ``uname -mi`` ） - * 如果您æ£åœ¨è™•ç†å›žæ¸ï¼Œä¸¦é€²è¡Œäº†äºŒåˆ†ï¼Œè«‹æåŠå°Žè‡´å›žæ¸çš„變更的主題和æ交ID。 + * 如果您æ£åœ¨è™•ç†è¿´æ¸ï¼Œä¸¦é€²è¡Œäº†äºŒåˆ†ï¼Œè«‹æåŠå°Žè‡´è¿´æ¸çš„變更的主題和æ交ID。 -許多情æ³ä¸‹ï¼Œè®“è®€ä½ å ±å‘Šçš„äººå¤šäº†è§£å…©ä»¶äº‹ä¹Ÿæ˜¯æ˜Žæ™ºä¹‹èˆ‰ï¼š +許多情æ³ä¸‹ï¼Œè®“è®€ä½ å ±å‘Šçš„äººå¤šçžè§£å…©ä»¶äº‹ä¹Ÿæ˜¯æ˜Žæ™ºä¹‹èˆ‰ï¼š - * 用於構建 Linux å…§æ ¸çš„é…置（「.configã€æ–‡ä»¶ï¼‰ + * 用於構建 Linux å…§æ ¸çš„é…置（“.configâ€æ–‡ä»¶ï¼‰ - * å…§æ ¸çš„ä¿¡æ¯ï¼Œä½ 從 ``dmesg`` 得到的信æ¯å¯«åˆ°ä¸€å€‹æ–‡ä»¶é‡Œã€‚確ä¿å®ƒä»¥åƒã€ŒLinux + * å…§æ ¸çš„ä¿¡æ¯ï¼Œä½ 從 ``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ã€é€™æ¨£çš„行開始，如果沒有，那麼第 + 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020â€é€™æ¨£çš„行開始，如果沒有，那麼第 一次啓動階段的é‡è¦ä¿¡æ¯å·²ç¶“被丟棄了。在這種情æ³ä¸‹ï¼Œå¯ä»¥è€ƒæ…®ä½¿ç”¨ ``journalctl -b 0 -k`` ï¼›æˆ–è€…ä½ ä¹Ÿå¯ä»¥é‡å•“，é‡ç¾é€™å€‹å•é¡Œï¼Œç„¶å¾Œèª¿ç”¨ ``dmesg`` 。 @@ -887,39 +882,39 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 * 將文件上傳到æŸå€‹å…¬é–‹çš„åœ°æ–¹ï¼ˆä½ çš„ç¶²ç«™ï¼Œå…¬å…±æ–‡ä»¶ç²˜è²¼æœå‹™ï¼Œåœ¨ `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上創建的工單……）， - ä¸¦åœ¨ä½ çš„å ±å‘Šä¸æ”¾ä¸Šé€£çµã€‚ç†æƒ³æƒ…æ³ä¸‹è«‹ä½¿ç”¨å…許這些文件ä¿å˜å¾ˆå¤šå¹´çš„åœ°æ–¹ï¼Œå› + ä¸¦åœ¨ä½ çš„å ±å‘Šä¸æ”¾ä¸ŠéŠæŽ¥ã€‚ç†æƒ³æƒ…æ³ä¸‹è«‹ä½¿ç”¨å…許這些文件ä¿å˜å¾ˆå¤šå¹´çš„åœ°æ–¹ï¼Œå› çˆ²å®ƒå€‘å¯èƒ½åœ¨å¾ˆå¤šå¹´å¾Œå°åˆ¥äººæœ‰ç”¨ï¼›ä¾‹å¦‚ 5 年或 10 年後，一個開發者æ£åœ¨ä¿®æ”¹ 一些代碼，而這些代碼æ£æ˜¯çˆ²äº†ä¿®å¾©ä½ çš„å•é¡Œã€‚ - * æŠŠæ–‡ä»¶æ”¾åœ¨ä¸€é‚Šï¼Œç„¶å¾Œèªªæ˜Žä½ æœƒåœ¨ä»–äººå›žå¾©æ™‚å†å–®ç¨ç™¼é€ã€‚åªè¦è¨˜å¾—å ±å‘Šç™¼å‡ºåŽ»å¾Œï¼Œ + * æŠŠæ–‡ä»¶æ”¾åœ¨ä¸€é‚Šï¼Œç„¶å¾Œèªªæ˜Žä½ æœƒåœ¨ä»–äººå›žè¦†æ™‚å†å–®ç¨ç™¼é€ã€‚åªè¦è¨˜å¾—å ±å‘Šç™¼å‡ºåŽ»å¾Œï¼Œ 真æ£åšåˆ°é€™ä¸€é»žå°±å¯ä»¥äº†ã€‚;-) æ供這些æ±è¥¿å¯èƒ½æ˜¯æ˜Žæ™ºçš„ ~~~~~~~~~~~~~~~~~~~~~~~~~~ -æ ¹æ“šå•é¡Œçš„ä¸åŒï¼Œä½ å¯èƒ½éœ€è¦æ供更多的背景數據。這裡有一些關於æ供什麼比較好 +æ ¹æ“šå•é¡Œçš„ä¸åŒï¼Œä½ å¯èƒ½éœ€è¦æ供更多的背景數據。這è£æœ‰ä¸€äº›é—œæ–¼æ供什麼比較好 的建è°ï¼š - * å¦‚æžœä½ è™•ç†çš„æ˜¯å…§æ ¸çš„ã€Œwarningã€ã€ã€ŒOOPSã€æˆ–「panicã€ï¼Œè«‹åŒ…å«å®ƒã€‚å¦‚æžœä½ ä¸èƒ½è¤‡è£½ - 粘貼它，試著用netconsole網絡終端é 程跟蹤或者至少æ‹ä¸€å¼µå±å¹•çš„照片。 + * å¦‚æžœä½ è™•ç†çš„æ˜¯å…§æ ¸çš„â€œwarningâ€ã€â€œOOPSâ€æˆ–“panicâ€ï¼Œè«‹åŒ…å«å®ƒã€‚å¦‚æžœä½ ä¸èƒ½è¤‡è£½ + 粘貼它，試ç€ç”¨netconsole網絡終端é 程跟蹤或者至少æ‹ä¸€å¼µå±å¹•çš„照片。 - * 如果å•é¡Œå¯èƒ½èˆ‡ä½ çš„é›»è…¦ç¡¬é«”æœ‰é—œï¼Œè«‹èªªæ˜Žä½ ä½¿ç”¨çš„æ˜¯ä»€éº¼ç³»çµ±ã€‚ä¾‹å¦‚ï¼Œå¦‚æžœä½ çš„ - 顯å¡æœ‰å•é¡Œï¼Œè«‹æåŠå®ƒçš„è£½é€ å•†ï¼Œé¡¯å¡çš„型號，以åŠä½¿ç”¨çš„晶片。如果是ç†è¨˜æœ¬é›» - 腦，請æåŠå®ƒçš„型號å稱，但儘é‡ç¢ºä¿æ„義明確。例如「戴爾 XPS 13ã€å°±ä¸å¾ˆæ˜Žç¢ºï¼Œ + * 如果å•é¡Œå¯èƒ½èˆ‡ä½ çš„é›»è…¦ç¡¬ä»¶æœ‰é—œï¼Œè«‹èªªæ˜Žä½ ä½¿ç”¨çš„æ˜¯ä»€éº¼ç³»çµ±ã€‚ä¾‹å¦‚ï¼Œå¦‚æžœä½ çš„ + 顯å¡æœ‰å•é¡Œï¼Œè«‹æåŠå®ƒçš„è£½é€ å•†ï¼Œé¡¯å¡çš„型號，以åŠä½¿ç”¨çš„芯片。如果是ç†è¨˜æœ¬é›» + 腦，請æåŠå®ƒçš„型號å稱，但儘é‡ç¢ºä¿æ„義明確。例如“戴爾 XPS 13â€å°±ä¸å¾ˆæ˜Žç¢ºï¼Œ å› çˆ²å®ƒå¯èƒ½æ˜¯ 2012 年的那款，那款除了看起來和ç¾åœ¨éŠ·å”®çš„沒有什麼ä¸åŒä¹‹å¤–， 兩者沒有任何共åŒä¹‹è™•ã€‚å› æ¤ï¼Œåœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œè¦åŠ 上準確的型號，例如 2019 - 年內推出的 XPS 13 型號爲「9380ã€æˆ–「7390ã€ã€‚åƒã€Œè¯æƒ³ Thinkpad T590ã€é€™æ¨£çš„åå— + 年內推出的 XPS 13 型號爲“9380â€æˆ–“7390â€ã€‚åƒâ€œè¯æƒ³ Thinkpad T590â€é€™æ¨£çš„åå— ä¹Ÿæœ‰äº›å«ç³Šä¸æ¸…：這款ç†è¨˜æœ¬æœ‰å¸¶ç¨ç«‹é¡¯å¡å’Œä¸å¸¶çš„å型號，所以è¦å„˜é‡æ‰¾åˆ°æº–確 的型號å稱或註明主è¦éƒ¨ä»¶ã€‚ - * 說明æ£åœ¨ä½¿ç”¨çš„ç›¸é—œè»Ÿé«”ã€‚å¦‚æžœä½ åœ¨åŠ è¼‰æ¨¡å¡Šæ™‚é‡åˆ°äº†å•é¡Œï¼Œä½ è¦èªªæ˜Žæ£åœ¨ä½¿ç”¨çš„ + * 說明æ£åœ¨ä½¿ç”¨çš„ç›¸é—œè»Ÿä»¶ã€‚å¦‚æžœä½ åœ¨åŠ è¼‰æ¨¡å¡Šæ™‚é‡åˆ°äº†å•é¡Œï¼Œä½ è¦èªªæ˜Žæ£åœ¨ä½¿ç”¨çš„ kmodã€systemd å’Œ udev 的版本。如果其ä¸ä¸€å€‹ DRM 驅動出ç¾å•é¡Œï¼Œä½ è¦èªªæ˜Ž libdrm å’Œ Mesa 的版本；還è¦èªªæ˜Žä½ çš„ Wayland åˆæˆå™¨æˆ– X-Server åŠå…¶é©…動。 å¦‚æžœä½ æœ‰æ–‡ä»¶ç³»çµ±å•é¡Œï¼Œè«‹è¨»æ˜Žç›¸æ‡‰çš„文件系統實用程åºçš„版本（e2fsprogs, btrfs-progs, xfsprogs……）。 * å¾žå…§æ ¸ä¸æ”¶é›†å¯èƒ½æœ‰ç”¨çš„é¡å¤–ä¿¡æ¯ã€‚例如， ``lspci -nn`` 的輸出å¯ä»¥å¹«åŠ©åˆ¥äºº - è˜åˆ¥ä½ ä½¿ç”¨çš„ç¡¬é«”ã€‚å¦‚æžœä½ çš„ç¡¬é«”æœ‰å•é¡Œï¼Œä½ 甚至å¯ä»¥çµ¦å‡º ``sudo lspci -vvv`` + è˜åˆ¥ä½ ä½¿ç”¨çš„ç¡¬ä»¶ã€‚å¦‚æžœä½ çš„ç¡¬ä»¶æœ‰å•é¡Œï¼Œä½ 甚至å¯ä»¥çµ¦å‡º ``sudo lspci -vvv`` çš„çµæžœï¼Œå› 爲它æ供了組件是如何é…置的信æ¯ã€‚å°æ–¼ä¸€äº›å•é¡Œï¼Œå¯èƒ½æœ€å¥½åŒ…å« ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ， ``/proc/modules`` 或 ``/proc/scsi/scsi`` ç‰æ–‡ä»¶çš„內容。一些å系統還æ @@ -936,7 +931,7 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 ~~~~~~~~~~~~~~~~~~~~~~ ç¾åœ¨ä½ å·²ç¶“æº–å‚™å¥½äº†å ±å‘Šçš„è©³ç´°éƒ¨åˆ†ï¼Œè®“æˆ‘å€‘é€²å…¥æœ€é‡è¦çš„部分：開é å¹¾å¥ã€‚ç¾åœ¨åˆ° -å ±å‘Šçš„æœ€å‰é¢ï¼Œåœ¨ä½ 剛æ‰å¯«çš„部分之å‰åŠ 上類似「The detailed description:ã€ï¼ˆè©³ç´° +å ±å‘Šçš„æœ€å‰é¢ï¼Œåœ¨ä½ 剛纔寫的部分之å‰åŠ 上類似“The detailed description:â€ï¼ˆè©³ç´° æ述）這樣的內容，並在最å‰é¢æ’入兩個新行。ç¾åœ¨å¯«ä¸€å€‹æ£å¸¸é•·åº¦çš„段è½ï¼Œå¤§è‡´æ¦‚ 述這個å•é¡Œã€‚去掉所有枯燥的細節，把é‡é»žæ”¾åœ¨è®€è€…需è¦çŸ¥é“çš„é—œéµéƒ¨åˆ†ï¼Œä»¥è®“人了 è§£é€™æ˜¯æ€Žéº¼å›žäº‹ï¼›å¦‚æžœä½ èªçˆ²é€™å€‹ç¼ºé™·å½±éŸ¿äº†å¾ˆå¤šç”¨æˆ¶ï¼Œå°±æ一下這點來å¸å¼•å¤§å®¶é—œ @@ -946,10 +941,10 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 è¦æ›´åŠ æŠ½è±¡ï¼Œçˆ²å ±å‘Šå¯«ä¸€å€‹æ›´çŸçš„主題/標題。 ç¾åœ¨ä½ å·²ç¶“å¯«å¥½äº†é€™éƒ¨åˆ†ï¼Œè«‹èŠ±é»žæ™‚é–“ä¾†å„ªåŒ–å®ƒï¼Œå› çˆ²å®ƒæ˜¯ä½ çš„å ±å‘Šä¸æœ€é‡è¦çš„部分： -很多人會先讀這部分，然後æ‰æœƒæ±ºå®šæ˜¯å¦å€¼å¾—花時間閱讀其他部分。 +很多人會先讀這部分，然後纔會決定是å¦å€¼å¾—花時間閱讀其他部分。 ç¾åœ¨å°±åƒ :ref:`MAINTAINERS <maintainers>` ç¶è·è€…æ–‡ä»¶å‘Šè¨´ä½ çš„é‚£æ¨£ç™¼é€æˆ–æ交 -å ±å‘Šï¼Œé™¤éžå®ƒæ˜¯å‰é¢æ¦‚述的那些「高優先級å•é¡Œã€ä¹‹ä¸€ï¼šåœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œè«‹å…ˆé–±è®€ä¸‹ä¸€ +å ±å‘Šï¼Œé™¤éžå®ƒæ˜¯å‰é¢æ¦‚述的那些“高優先級å•é¡Œâ€ä¹‹ä¸€ï¼šåœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œè«‹å…ˆé–±è®€ä¸‹ä¸€ å°ç¯€ï¼Œç„¶å¾Œå†ç™¼é€å ±å‘Šã€‚ 高優先級å•é¡Œçš„ç‰¹æ®Šè™•ç† @@ -960,11 +955,19 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 **éžå¸¸åš´é‡çš„缺陷** ：確ä¿åœ¨ä¸»é¡Œæˆ–工單標題以åŠç¬¬ä¸€æ®µä¸æ˜Žé¡¯æ¨™å‡º severeness （éžå¸¸åš´é‡çš„）。 -**回æ¸** ：如果å•é¡Œæ˜¯ä¸€å€‹å›žæ¸ï¼Œè«‹åœ¨éƒµä»¶çš„主題或缺陷跟蹤器的標題ä¸æ·»åŠ -[REGRESSION]。如果您沒有進行二分，請至少註明您測試的最新主線版本（比如 5.7） -和出ç¾å•é¡Œçš„最新版本（比如 5.8）。如果您æˆåŠŸåœ°é€²è¡Œäº†äºŒåˆ†ï¼Œè«‹è¨»æ˜Žå°Žè‡´å›žæ¸ -çš„æ交IDå’Œä¸»é¡Œã€‚ä¹Ÿè«‹æ·»åŠ è©²è®Šæ›´çš„ä½œè€…åˆ°ä½ çš„å ±å‘Šä¸ï¼›å¦‚果您需è¦å°‡æ‚¨çš„缺陷æ交 -到缺陷跟蹤器ä¸ï¼Œè«‹å°‡å ±å‘Šä»¥ç§äººéƒµä»¶çš„å½¢å¼è½‰ç™¼çµ¦ä»–ï¼Œä¸¦è¨»æ˜Žå ±å‘Šæ交地點。 +**è¿´æ¸** ï¼šå ±å‘Šçš„ä¸»é¡Œæ‡‰ä»¥â€œ[REGRESSION]â€é–‹é 。 + +如果您æˆåŠŸç”¨äºŒåˆ†æ³•å®šä½äº†å•é¡Œï¼Œè«‹ä½¿ç”¨å¼•å…¥è¿´æ¸ä¹‹æ›´æ”¹çš„標題作爲主題的第二部分。 +è«‹åœ¨å ±å‘Šä¸å¯«æ˜Žâ€œç½ªéç¦é¦–â€çš„æ交ID。如果未能æˆåŠŸäºŒåˆ†ï¼Œè«‹åœ¨å ±å‘Šä¸è¬›æ˜Žæœ€å¾Œä¸€å€‹ +æ£å¸¸å·¥ä½œçš„版本（例如5.7）和最先發生å•é¡Œçš„版本（例如5.8-rc1）。 + +通éŽéƒµä»¶ç™¼é€å ±å‘Šæ™‚，請抄é€Linuxè¿´æ¸éƒµä»¶åˆ—表（regressions@lists.linux.dev）。 +å¦‚æžœå ±å‘Šéœ€è¦æ交到æŸå€‹web追蹤器，請繼續æ交；並在æ交後，通éŽéƒµä»¶å°‡å ±å‘Šè½‰ç™¼ +至迴æ¸åˆ—表；抄é€ç›¸é—œå系統的ç¶è·äººå“¡å’Œéƒµä»¶åˆ—表。請確ä¿å ±å‘Šæ˜¯å…§è¯è½‰ç™¼çš„，ä¸è¦ +把它作爲附件。å¦å¤–è«‹åœ¨é ‚éƒ¨æ·»åŠ ä¸€å€‹ç°¡çŸçš„說明，在那è£å¯«ä¸Šå·¥å–®çš„網å€ã€‚ + +åœ¨éƒµå¯„æˆ–è½‰ç™¼å ±å‘Šæ™‚ï¼Œå¦‚æžœæˆåŠŸäºŒåˆ†ï¼Œéœ€è¦å°‡â€œç½ªéç¦é¦–â€çš„ä½œè€…æ·»åŠ åˆ°æ”¶ä»¶äººä¸ï¼›åŒæ™‚ +抄é€signed-off-byéˆä¸çš„æ¯å€‹äººï¼Œæ‚¨å¯ä»¥åœ¨æ交消æ¯çš„末尾找到。 **安全å•é¡Œ** ：å°æ–¼é€™ç¨®å•é¡Œï¼Œä½ å°‡å¿…é ˆè©•ä¼°ï¼šå¦‚æžœç´°ç¯€è¢«å…¬é–‹æŠ«éœ²ï¼Œæ˜¯å¦æœƒå°å…¶ä»– 用戶產生çŸæœŸé¢¨éšªã€‚如果ä¸æœƒï¼Œåªéœ€æŒ‰ç…§æ‰€è¿°ç¹¼çºŒå ±å‘Šå•é¡Œã€‚如果有æ¤é¢¨éšªï¼Œä½ éœ€è¦ @@ -972,47 +975,47 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 * 如果 MAINTAINERS 文件指示您通éŽéƒµä»¶å ±å‘Šå•é¡Œï¼Œè«‹ä¸è¦æŠ„é€ä»»ä½•å…¬å…±éƒµä»¶åˆ—表。 - * å¦‚æžœä½ æ‡‰è©²åœ¨ç¼ºé™·è·Ÿè¹¤å™¨ä¸æ交å•é¡Œï¼Œè«‹ç¢ºä¿å°‡å·¥å–®æ¨™è¨˜çˆ²ã€Œç§æœ‰ã€æˆ–「安全å•é¡Œã€ã€‚ + * å¦‚æžœä½ æ‡‰è©²åœ¨ç¼ºé™·è·Ÿè¹¤å™¨ä¸æ交å•é¡Œï¼Œè«‹ç¢ºä¿å°‡å·¥å–®æ¨™è¨˜çˆ²â€œç§æœ‰â€æˆ–“安全å•é¡Œâ€ã€‚ 如果缺陷跟蹤器沒有æä¾›ä¿æŒå ±å‘Šç§å¯†æ€§çš„æ–¹æ³•ï¼Œé‚£å°±åˆ¥æƒ³äº†ï¼ŒæŠŠä½ çš„å ±å‘Šä»¥ç§äºº 郵件的形å¼ç™¼é€çµ¦ç¶è·è€…å§ã€‚ -在這兩種情æ³ä¸‹ï¼Œéƒ½ä¸€å®šè¦å°‡å ±å‘Šç™¼åˆ° MAINTAINERS 文件ä¸ã€Œå®‰å…¨è¯çµ¡ã€éƒ¨åˆ†åˆ—出的 +在這兩種情æ³ä¸‹ï¼Œéƒ½ä¸€å®šè¦å°‡å ±å‘Šç™¼åˆ° MAINTAINERS 文件ä¸â€œå®‰å…¨è¯çµ¡â€éƒ¨åˆ†åˆ—出的 地å€ã€‚ç†æƒ³çš„情æ³æ˜¯åœ¨ç™¼é€å ±å‘Šçš„時候直接抄é€ä»–們。如果您在缺陷跟蹤器ä¸æ交了 -å ±å‘Šï¼Œè«‹å°‡å ±å‘Šçš„æ–‡æœ¬è½‰ç™¼åˆ°é€™äº›åœ°å€ï¼›ä½†è«‹åœ¨å ±å‘Šçš„é ‚éƒ¨åŠ ä¸Šæ³¨é‡‹ï¼Œè¡¨æ˜Žæ‚¨æ交了 -å ±å‘Šï¼Œä¸¦é™„ä¸Šå·¥å–®é€£çµã€‚ +å ±å‘Šï¼Œè«‹å°‡å ±å‘Šçš„æ–‡æœ¬è½‰ç™¼åˆ°é€™äº›åœ°å€ï¼›ä½†è«‹åœ¨å ±å‘Šçš„é ‚éƒ¨åŠ ä¸Šè¨»é‡‹ï¼Œè¡¨æ˜Žæ‚¨æ交了 +å ±å‘Šï¼Œä¸¦é™„ä¸Šå·¥å–®éˆæŽ¥ã€‚ -更多信æ¯è«‹åƒè¦‹ã€ŒDocumentation/translations/zh_TW/admin-guide/security-bugs.rstã€ã€‚ +更多信æ¯è«‹åƒè¦‹ Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 -ç™¼å¸ƒå ±å‘Šå¾Œçš„è²¬ä»» +ç™¼ä½ˆå ±å‘Šå¾Œçš„è²¬ä»» ------------------ *ç‰å¾…別人的åæ‡‰ï¼Œç¹¼çºŒæŽ¨é€²äº‹æƒ…ï¼Œç›´åˆ°ä½ èƒ½å¤ æŽ¥å—這樣或那樣的çµæžœã€‚å› æ¤ï¼Œè«‹ 公開和åŠæ™‚地回應任何詢å•ã€‚測試æ出的修復。ç©æ¥µåœ°æ¸¬è©¦ï¼šè‡³å°‘é‡æ–°æ¸¬è©¦æ¯å€‹ 新主線版本的首個候é¸ç‰ˆæœ¬ï¼ˆRCï¼‰ï¼Œä¸¦å ±å‘Šä½ çš„çµæžœã€‚如果出ç¾æ‹–延，就å‹å¥½åœ° - æé†’ä¸€ä¸‹ã€‚å¦‚æžœä½ æ²’æœ‰å¾—åˆ°ä»»ä½•å¹«åŠ©æˆ–è€…æœªèƒ½æ»¿æ„，請試著自己幫助自己。* + æé†’ä¸€ä¸‹ã€‚å¦‚æžœä½ æ²’æœ‰å¾—åˆ°ä»»ä½•å¹«åŠ©æˆ–è€…æœªèƒ½æ»¿æ„，請試ç€è‡ªå·±å¹«åŠ©è‡ªå·±ã€‚* å¦‚æžœä½ çš„å ±å‘Šéžå¸¸å„ªç§€ï¼Œè€Œä¸”ä½ çœŸçš„å¾ˆå¹¸é‹ï¼Œé‚£éº¼æŸå€‹é–‹ç™¼è€…å¯èƒ½æœƒç«‹å³ç™¼ç¾å°Žè‡´å• é¡Œçš„åŽŸå› ï¼›ç„¶å¾Œä»–å€‘å¯èƒ½æœƒå¯«ä¸€å€‹è£œä¸ä¾†ä¿®å¾©ã€æ¸¬è©¦å®ƒï¼Œä¸¦ç›´æŽ¥ç™¼é€çµ¦ä¸»ç·šé›†æˆï¼ŒåŒ -時標記它以便以後回溯到需è¦å®ƒçš„穩定版和長期支æŒå…§æ ¸ã€‚é‚£éº¼ä½ éœ€è¦åšçš„就是回復 -一å¥ã€ŒThank you very muchã€ï¼ˆéžå¸¸æ„Ÿè¬ï¼‰ï¼Œç„¶å¾Œåœ¨ç™¼å¸ƒå¾Œæ›ä¸Šä¿®å¾©å¥½çš„版本。 +時標記它以便以後回溯到需è¦å®ƒçš„穩定版和長期支æŒå…§æ ¸ã€‚é‚£éº¼ä½ éœ€è¦åšçš„就是回覆 +一å¥â€œThank you very muchâ€ï¼ˆéžå¸¸æ„Ÿè¬ï¼‰ï¼Œç„¶å¾Œåœ¨ç™¼ä½ˆå¾Œæ›ä¸Šä¿®å¾©å¥½çš„版本。 -但這種ç†æƒ³ç‹€æ³å¾ˆå°‘ç™¼ç”Ÿã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ æŠŠå ±å‘Šæ‹¿å‡ºä¾†ä¹‹å¾Œå·¥ä½œæ‰é–‹å§‹ã€‚ä½ è¦åšçš„ -事情è¦è¦–情æ³è€Œå®šï¼Œä½†é€šå¸¸æœƒæ˜¯ä¸‹é¢åˆ—å‡ºçš„äº‹æƒ…ã€‚ä½†åœ¨æ·±å…¥ç ”ç©¶ç´°ç¯€ä¹‹å‰ï¼Œé€™è£¡æœ‰å¹¾ +但這種ç†æƒ³ç‹€æ³å¾ˆå°‘ç™¼ç”Ÿã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ æŠŠå ±å‘Šæ‹¿å‡ºä¾†ä¹‹å¾Œå·¥ä½œçº”é–‹å§‹ã€‚ä½ è¦åšçš„ +事情è¦è¦–情æ³è€Œå®šï¼Œä½†é€šå¸¸æœƒæ˜¯ä¸‹é¢åˆ—å‡ºçš„äº‹æƒ…ã€‚ä½†åœ¨æ·±å…¥ç ”ç©¶ç´°ç¯€ä¹‹å‰ï¼Œé€™è£æœ‰å¹¾ 件é‡è¦çš„äº‹æƒ…ï¼Œä½ éœ€è¦è¨˜ä½é€™éƒ¨åˆ†çš„éŽç¨‹ã€‚ 關於進一æ¥äº’å‹•çš„ä¸€èˆ¬å»ºè° ~~~~~~~~~~~~~~~~~~~~~~~~~~ -**總是公開回復** ï¼šç•¶ä½ åœ¨ç¼ºé™·è·Ÿè¹¤å™¨ä¸æ交å•é¡Œæ™‚，一定è¦åœ¨é‚£è£¡å›žå¾©ï¼Œä¸è¦ç§ä¸‹ -è¯ç¹«ä»»ä½•é–‹ç™¼è€…。å°æ–¼éƒµä»¶å ±å‘Šï¼Œåœ¨å›žå¾©æ‚¨æ”¶åˆ°çš„任何郵件時，總是使用「全部回復〠+**總是公開回復** ï¼šç•¶ä½ åœ¨ç¼ºé™·è·Ÿè¹¤å™¨ä¸æ交å•é¡Œæ™‚，一定è¦åœ¨é‚£è£å›žè¦†ï¼Œä¸è¦ç§ä¸‹ +è¯ç¹«ä»»ä½•é–‹ç™¼è€…。å°æ–¼éƒµä»¶å ±å‘Šï¼Œåœ¨å›žè¦†æ‚¨æ”¶åˆ°çš„ä»»ä½•éƒµä»¶æ™‚ï¼Œç¸½æ˜¯ä½¿ç”¨â€œå…¨éƒ¨å›žè¦†â€ åŠŸèƒ½ã€‚é€™åŒ…æ‹¬å¸¶æœ‰ä»»ä½•ä½ å¯èƒ½æƒ³è¦æ·»åŠ åˆ°ä½ çš„å ±å‘Šä¸çš„é¡å¤–數據的郵件：進入郵件應 -用程åºã€Œå·²ç™¼é€ã€æ–‡ä»¶å¤¾ï¼Œä¸¦åœ¨éƒµä»¶ä¸Šä½¿ç”¨ã€Œå…¨éƒ¨å›žå¾©ã€ä¾†å›žå¾©å ±å‘Šã€‚這種方法å¯ä»¥ç¢ºä¿ -公共郵件列表和其他所有åƒèˆ‡è€…都能åŠæ™‚了解情æ³ï¼›å®ƒé‚„能ä¿æŒéƒµä»¶ç·šç¨‹çš„完整性， +用程åºâ€œå·²ç™¼é€â€æ–‡ä»¶å¤¾ï¼Œä¸¦åœ¨éƒµä»¶ä¸Šä½¿ç”¨â€œå…¨éƒ¨å›žè¦†â€ä¾†å›žå¾©å ±å‘Šã€‚這種方法å¯ä»¥ç¢ºä¿ +公共郵件列表和其他所有åƒèˆ‡è€…都能åŠæ™‚çžè§£æƒ…æ³ï¼›å®ƒé‚„能ä¿æŒéƒµä»¶ç·šç¨‹çš„完整性， 這å°æ–¼éƒµä»¶åˆ—表將所有相關郵件æ¸çˆ²ä¸€é¡žæ˜¯éžå¸¸é‡è¦çš„。 -åªæœ‰å…©ç¨®æƒ…æ³ä¸é©åˆåœ¨ç¼ºé™·è·Ÿè¹¤å™¨æˆ–「全部回復ã€ä¸ç™¼è¡¨è©•è«–： +åªæœ‰å…©ç¨®æƒ…æ³ä¸é©åˆåœ¨ç¼ºé™·è·Ÿè¹¤å™¨æˆ–“全部回覆â€ä¸ç™¼è¡¨è©•è«–： * æœ‰äººè®“ä½ ç§ä¸‹ç™¼æ±è¥¿ã€‚ @@ -1022,32 +1025,32 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 **在請求解釋或幫助之å‰å…ˆç ”究一下** ：在這部分éŽç¨‹ä¸ï¼Œæœ‰äººå¯èƒ½æœƒå‘Šè¨´ä½ 用尚未 掌æ¡çš„技能åšä¸€äº›äº‹æƒ…ã€‚ä¾‹å¦‚ä½ å¯èƒ½æœƒè¢«è¦æ±‚ä½¿ç”¨ä¸€äº›ä½ å¾žæœªè½èªªéŽçš„測試工具；或 -è€…ä½ å¯èƒ½æœƒè¢«è¦æ±‚在 Linux å…§æ ¸åŽŸå§‹ç¢¼ä¸Šæ‡‰ç”¨ä¸€å€‹è£œä¸ä¾†æ¸¬è©¦å®ƒæ˜¯å¦æœ‰å¹«åŠ©ã€‚在æŸäº› -情æ³ä¸‹ï¼Œç™¼å€‹å›žå¾©è©¢å•å¦‚何åšå°±å¯ä»¥äº†ã€‚但在走這æ¢è·¯ä¹‹å‰ï¼Œå„˜é‡é€šéŽåœ¨ç¶²éš›ç¶²è·¯ä¸Šæœ +è€…ä½ å¯èƒ½æœƒè¢«è¦æ±‚在 Linux å…§æ ¸æºä»£ç¢¼ä¸Šæ‡‰ç”¨ä¸€å€‹è£œä¸ä¾†æ¸¬è©¦å®ƒæ˜¯å¦æœ‰å¹«åŠ©ã€‚在æŸäº› +情æ³ä¸‹ï¼Œç™¼å€‹å›žè¦†è©¢å•å¦‚何åšå°±å¯ä»¥äº†ã€‚但在走這æ¢è·¯ä¹‹å‰ï¼Œå„˜é‡é€šéŽåœ¨äº’è¯ç¶²ä¸Šæœ 索自行找到ç”案；或者考慮在其他地方詢å•å»ºè°ã€‚比如詢å•æœ‹å‹ï¼Œæˆ–è€…åˆ°ä½ å¹³æ™‚å¸¸åŽ» çš„èŠå¤©å®¤æˆ–論壇發帖諮詢。 **è¦æœ‰è€å¿ƒ** ï¼šå¦‚æžœä½ çœŸçš„å¾ˆå¹¸é‹ï¼Œä½ å¯èƒ½æœƒåœ¨å¹¾å€‹å°æ™‚內收到å°ä½ çš„å ±å‘Šçš„ç”覆。 但大多數情æ³ä¸‹æœƒèŠ±è²»æ›´å¤šçš„æ™‚é–“ï¼Œå› çˆ²ç¶è·è€…分散在全çƒå„åœ°ï¼Œå› æ¤å¯èƒ½åœ¨ä¸åŒçš„ -時å€â€”—在那裡他們已經享å—è‘—é 離éµç›¤çš„夜晚。 +時å€â€”—在那è£ä»–們已經享å—ç€é 離éµç›¤çš„夜晚。 ä¸€èˆ¬ä¾†èªªï¼Œå…§æ ¸é–‹ç™¼è€…éœ€è¦ä¸€åˆ°äº”å€‹å·¥ä½œæ—¥ä¾†å›žå¾©å ±å‘Šã€‚æœ‰æ™‚æœƒèŠ±è²»æ›´é•·çš„æ™‚é–“ï¼Œå› çˆ²ä»–å€‘å¯èƒ½æ£å¿™æ–¼åˆä½µçª—å£ã€å…¶ä»–工作ã€åƒåŠ 開發者會è°ï¼Œæˆ–者åªæ˜¯åœ¨äº«å—一個漫長 çš„æš‘å‡ã€‚ -「高優先級的å•é¡Œã€ï¼ˆè¦‹ä¸Šé¢çš„解釋）例外：ç¶è·è€…應該儘快解決這些å•é¡Œï¼›é€™å°±æ˜¯çˆ² +“高優先級的å•é¡Œâ€ï¼ˆè¦‹ä¸Šé¢çš„解釋）例外：ç¶è·è€…應該儘快解決這些å•é¡Œï¼›é€™å°±æ˜¯çˆ² ä»€éº¼ä½ æ‡‰è©²æœ€å¤šç‰å¾…一個星期（如果是緊急的事情，則åªéœ€å…©å¤©ï¼‰ï¼Œç„¶å¾Œå†ç™¼é€å‹å¥½ çš„æ醒。 -有時ç¶è·è€…å¯èƒ½æ²’有åŠæ™‚回復；有時候å¯èƒ½æœƒå‡ºç¾åˆ†æ§ï¼Œä¾‹å¦‚一個å•é¡Œæ˜¯å¦ç¬¦åˆå›žæ¸ +有時ç¶è·è€…å¯èƒ½æ²’有åŠæ™‚回覆；有時候å¯èƒ½æœƒå‡ºç¾åˆ†æ§ï¼Œä¾‹å¦‚一個å•é¡Œæ˜¯å¦ç¬¦åˆè¿´æ¸ çš„æ¢ä»¶ã€‚在這種情æ³ä¸‹ï¼Œåœ¨éƒµä»¶åˆ—表上æå‡ºä½ çš„é¡§æ…®ï¼Œä¸¦è«‹æ±‚å…¶ä»–äººå…¬é–‹æˆ–ç§ä¸‹å›žå¾© 如何繼續推進。如果失敗了，å¯èƒ½æ‡‰è©²è®“更高級別的ç¶è·è€…介入。如果是 WiFi 驅動， 那就是無線ç¶è·è€…；如果沒有更高級別的ç¶è·è€…，或者其他一切努力都失敗了，那 這å¯èƒ½æ˜¯ä¸€ç¨®ç½•è¦‹çš„ã€å¯ä»¥è®“ Linus Torvalds åƒèˆ‡é€²ä¾†çš„情æ³ã€‚ -**主動測試** ：æ¯ç•¶ä¸€å€‹æ–°çš„ä¸»ç·šå…§æ ¸ç‰ˆæœ¬çš„ç¬¬ä¸€å€‹é 發布版本（rc1）發布的時候， +**主動測試** ：æ¯ç•¶ä¸€å€‹æ–°çš„ä¸»ç·šå…§æ ¸ç‰ˆæœ¬çš„ç¬¬ä¸€å€‹é 發佈版本（rc1）發佈的時候， 去檢查一下這個å•é¡Œæ˜¯å¦å¾—到了解決，或者是å¦æœ‰ä»€éº¼é‡è¦çš„變化。在工單ä¸æˆ–在 -å›žå¾©å ±å‘Šçš„éƒµä»¶ä¸æåŠçµæžœï¼ˆç¢ºä¿æ‰€æœ‰åƒèˆ‡è¨Žè«–的人都被抄é€ï¼‰ã€‚é€™å°‡è¡¨æ˜Žä½ çš„æ‰¿è«¾ +å›žè¦†å ±å‘Šçš„éƒµä»¶ä¸æåŠçµæžœï¼ˆç¢ºä¿æ‰€æœ‰åƒèˆ‡è¨Žè«–的人都被抄é€ï¼‰ã€‚é€™å°‡è¡¨æ˜Žä½ çš„æ‰¿è«¾ å’Œä½ é¡˜æ„幫忙。如果å•é¡ŒæŒçºŒå˜åœ¨ï¼Œå®ƒä¹Ÿæœƒæ醒開發者確ä¿ä»–們ä¸æœƒå¿˜è¨˜å®ƒã€‚其他一 些ä¸å®šæœŸçš„é‡æ–°æ¸¬è©¦ï¼ˆä¾‹å¦‚用rc3ã€rc5 和最終版本）也是一個好主æ„，但åªæœ‰åœ¨ç›¸é—œ çš„æ±è¥¿ç™¼ç”Ÿè®ŠåŒ–æˆ–è€…ä½ æ£åœ¨å¯«ä»€éº¼æ±è¥¿çš„時候æ‰å ±å‘Šä½ çš„çµæžœã€‚ @@ -1057,10 +1060,10 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 查詢和測試請求 ~~~~~~~~~~~~~~~ -å¦‚æžœä½ çš„å ±å‘Šå¾—åˆ°äº†å›žå¾©å‰‡éœ€å±¥è¡Œä»¥ä¸‹è²¬ä»»ï¼š +å¦‚æžœä½ çš„å ±å‘Šå¾—åˆ°äº†å›žè¦†å‰‡éœ€å±¥è¡Œä»¥ä¸‹è²¬ä»»ï¼š **æª¢æŸ¥èˆ‡ä½ æ‰“äº¤é“的人** ：大多數情æ³ä¸‹ï¼Œæœƒæ˜¯ç¶è·è€…或特定代碼å€åŸŸçš„é–‹ç™¼äººå“¡å° -ä½ çš„å ±å‘Šåšå‡ºå›žæ‡‰ã€‚但由於å•é¡Œé€šå¸¸æ˜¯å…¬é–‹å ±å‘Šçš„，所以回復的å¯èƒ½æ˜¯ä»»ä½•äººâ€”—包括 +ä½ çš„å ±å‘Šåšå‡ºå›žæ‡‰ã€‚但由於å•é¡Œé€šå¸¸æ˜¯å…¬é–‹å ±å‘Šçš„，所以回覆的å¯èƒ½æ˜¯ä»»ä½•äººâ€”—包括 那些想è¦å¹«å¿™çš„人，但最後å¯èƒ½æœƒç”¨ä»–們的å•é¡Œæˆ–è«‹æ±‚å¼•å°Žä½ å®Œå…¨å離軌é“。這很少 發生，但這是快速上網æœæœçœ‹ä½ æ£åœ¨èˆ‡èª°äº’å‹•æ˜¯æ˜Žæ™ºä¹‹èˆ‰çš„è¨±å¤šåŽŸå› ä¹‹ä¸€ã€‚é€šéŽé€™æ¨£ åšï¼Œä½ 也å¯ä»¥çŸ¥é“ä½ çš„å ±å‘Šæ˜¯å¦è¢«æ£ç¢ºçš„人è½åˆ°ï¼Œå› 爲如果討論沒有導致滿æ„çš„å•é¡Œ @@ -1086,63 +1089,63 @@ Linux 首å¸é–‹ç™¼è€… Linus Torvalds èªçˆ² Linux å…§æ ¸æ°¸é ä¸æ‡‰æƒ¡åŒ–，這 å ±å‘Šåˆ°é”時，ç¶è·è€…剛剛離開éµç›¤ä¸€æ®µæ™‚間，或者有更é‡è¦çš„事情è¦è™•ç†ã€‚在寫æ醒 信的時候，è¦å–„æ„地å•ä¸€ä¸‹ï¼Œæ˜¯å¦é‚„需è¦ä½ 這邊æä¾›ä»€éº¼ä¾†è®“äº‹æƒ…æŽ¨é€²ä¸‹åŽ»ã€‚å¦‚æžœå ± 告是通éŽéƒµä»¶ç™¼å‡ºä¾†çš„ï¼Œé‚£å°±åœ¨éƒµä»¶çš„ç¬¬ä¸€è¡Œå›žè¦†ä½ çš„åˆå§‹éƒµä»¶ï¼ˆè¦‹ä¸Šæ–‡ï¼‰ï¼Œå…¶ä¸åŒ… -æ‹¬ä¸‹æ–¹çš„åŽŸå§‹å ±å‘Šçš„å®Œæ•´å¼•ç”¨ï¼šé€™æ˜¯å°‘æ•¸å¹¾ç¨®æƒ…æ³ä¸‹ï¼Œé€™æ¨£çš„「TOFUã€ï¼ˆText Over, +æ‹¬ä¸‹æ–¹çš„åŽŸå§‹å ±å‘Šçš„å®Œæ•´å¼•ç”¨ï¼šé€™æ˜¯å°‘æ•¸å¹¾ç¨®æƒ…æ³ä¸‹ï¼Œé€™æ¨£çš„“TOFUâ€ï¼ˆText Over, Fullquote Underæ–‡å—在上，完整引用在下）是æ£ç¢ºçš„åšæ³•ï¼Œå› 爲這樣所有的收件人都 會以é©ç•¶çš„é †åºç«‹å³è®“細節到手é 上來。 -在æ醒之後，å†ç‰ä¸‰å‘¨çš„å›žè¦†ã€‚å¦‚æžœä½ ä»ç„¶æ²’有得到é©ç•¶çš„åé¥‹ï¼Œä½ é¦–å…ˆæ‡‰è©²é‡æ–°è€ƒ +在æ醒之後，å†ç‰ä¸‰é€±çš„å›žè¦†ã€‚å¦‚æžœä½ ä»ç„¶æ²’有得到é©ç•¶çš„åé¥‹ï¼Œä½ é¦–å…ˆæ‡‰è©²é‡æ–°è€ƒ æ…®ä½ çš„æ–¹æ³•ã€‚ä½ æ˜¯å¦å¯èƒ½å˜—試接觸了錯誤的人？是ä¸æ˜¯å ±å‘Šä¹Ÿè¨±ä»¤äººå感或者太混亂， 以至於人們決定完全é é›¢å®ƒï¼ŸæŽ’é™¤é€™äº›å› ç´ çš„æœ€å¥½æ–¹æ³•æ˜¯ï¼šæŠŠå ±å‘Šçµ¦ä¸€å…©å€‹ç†Ÿæ‚‰ FLOSS å•é¡Œå ±å‘Šçš„人看，詢å•ä»–們的æ„見。åŒæ™‚徵求他們關於如何繼續推進的建è°ã€‚ -這å¯èƒ½æ„å‘³è‘—ï¼šæº–å‚™ä¸€ä»½æ›´å¥½çš„å ±å‘Šï¼Œè®“é€™äº›äººåœ¨ä½ ç™¼å‡ºåŽ»ä¹‹å‰å°å®ƒé€²è¡Œå¯©æŸ¥ã€‚這樣 +這å¯èƒ½æ„味ç€ï¼šæº–å‚™ä¸€ä»½æ›´å¥½çš„å ±å‘Šï¼Œè®“é€™äº›äººåœ¨ä½ ç™¼å‡ºåŽ»ä¹‹å‰å°å®ƒé€²è¡Œå¯©æŸ¥ã€‚這樣 的方法完全å¯ä»¥ï¼›åªéœ€èªªæ˜Žé€™æ˜¯é—œæ–¼é€™å€‹å•é¡Œçš„ç¬¬äºŒä»½æ”¹é€²çš„å ±å‘Šï¼Œä¸¦é™„ä¸Šç¬¬ä¸€ä»½å ± -告的連çµã€‚ +å‘Šçš„éˆæŽ¥ã€‚ å¦‚æžœå ±å‘Šæ˜¯æ°ç•¶çš„ï¼Œä½ å¯ä»¥ç™¼é€ç¬¬äºŒå°æ醒信；在其ä¸è©¢å•çˆ²ä»€éº¼å ±å‘Šæ²’有得到任何 -回復。第二å°æ醒郵件的好時機是在新 Linux å…§æ ¸ç‰ˆæœ¬çš„é¦–å€‹é 發布版本（'rc1'） -發布後ä¸ä¹…ï¼Œå› çˆ²ç„¡è«–å¦‚ä½•ä½ éƒ½æ‡‰è©²åœ¨é‚£å€‹æ™‚å€™é‡æ–°æ¸¬è©¦ä¸¦æ供狀態更新（見上文）。 +回覆。第二å°æ醒郵件的好時機是在新 Linux å…§æ ¸ç‰ˆæœ¬çš„é¦–å€‹é 發佈版本（'rc1'） +發佈後ä¸ä¹…ï¼Œå› çˆ²ç„¡è«–å¦‚ä½•ä½ éƒ½æ‡‰è©²åœ¨é‚£å€‹æ™‚å€™é‡æ–°æ¸¬è©¦ä¸¦æ供狀態更新（見上文）。 -如果第二次æ醒的çµæžœåˆåœ¨ä¸€å‘¨å…§æ²’有任何å應，å¯ä»¥å˜—試è¯ç¹«ä¸Šç´šç¶è·è€…è©¢å•æ„見： +如果第二次æ醒的çµæžœåˆåœ¨ä¸€é€±å…§æ²’有任何å應，å¯ä»¥å˜—試è¯ç¹«ä¸Šç´šç¶è·è€…è©¢å•æ„見： å³ä½¿å†å¿™çš„ç¶è·è€…在這時候也至少應該發éŽæŸç¨®ç¢ºèªã€‚ 記ä½è¦åšå¥½å¤±æœ›çš„準備：ç†æƒ³ç‹€æ³ä¸‹ç¶è·è€…最好å°æ¯ä¸€å€‹å•é¡Œå ±å‘Šåšå‡ºå›žæ‡‰ï¼Œä½†ä»–們 -åªæœ‰ç¾©å‹™è§£æ±ºä¹‹å‰åˆ—出的「高優先級å•é¡Œã€ã€‚æ‰€ä»¥ï¼Œå¦‚æžœä½ å¾—åˆ°çš„å›žè¦†æ˜¯ã€Œè¬è¬ä½ çš„å ±å‘Šï¼Œ -我目å‰æœ‰æ›´é‡è¦çš„å•é¡Œè¦è™•ç†ï¼Œåœ¨å¯é è¦‹çš„æœªä¾†æ²’æœ‰æ™‚é–“åŽ»ç ”ç©¶é€™å€‹å•é¡Œã€ï¼Œé‚£è«‹ä¸ +åªæœ‰ç¾©å‹™è§£æ±ºä¹‹å‰åˆ—出的“高優先級å•é¡Œâ€ã€‚æ‰€ä»¥ï¼Œå¦‚æžœä½ å¾—åˆ°çš„å›žè¦†æ˜¯â€œè¬è¬ä½ çš„å ±å‘Šï¼Œ +我目å‰æœ‰æ›´é‡è¦çš„å•é¡Œè¦è™•ç†ï¼Œåœ¨å¯é è¦‹çš„æœªä¾†æ²’æœ‰æ™‚é–“åŽ»ç ”ç©¶é€™å€‹å•é¡Œâ€ï¼Œé‚£è«‹ä¸ è¦å¤ªæ²®å–ªã€‚ 也有å¯èƒ½åœ¨ç¼ºé™·è·Ÿè¹¤å™¨æˆ–列表ä¸é€²è¡Œäº†ä¸€äº›è¨Žè«–之後，什麼都沒有發生，æ醒也無助 於激勵大家進行修復。這種情æ³å¯èƒ½æ˜¯æ¯€æ»…性的，但在 Linux å…§æ ¸é–‹ç™¼ä¸ç¢ºå¯¦æœƒç™¼ç”Ÿã€‚ -這些和其他得ä¸åˆ°å¹«åŠ©çš„åŽŸå› åœ¨æœ¬æ–‡çµå°¾è™•çš„「爲什麼有些å•é¡Œåœ¨è¢«å ±å‘Šå¾Œæ²’有得到 -任何回應或者ä»ç„¶æ²’有修復ã€ä¸é€²è¡Œäº†è§£é‡‹ã€‚ +這些和其他得ä¸åˆ°å¹«åŠ©çš„åŽŸå› åœ¨æœ¬æ–‡çµå°¾è™•çš„“爲什麼有些å•é¡Œåœ¨è¢«å ±å‘Šå¾Œæ²’有得到 +任何回應或者ä»ç„¶æ²’有修復â€ä¸é€²è¡Œäº†è§£é‡‹ã€‚ å¦‚æžœä½ æ²’æœ‰å¾—åˆ°ä»»ä½•å¹«åŠ©æˆ–å•é¡Œæœ€çµ‚沒有得到解決，ä¸è¦æ²®å–ªï¼šLinux å…§æ ¸æ˜¯ FLOSS， -å› æ¤ä½ ä»ç„¶å¯ä»¥è‡ªå·±å¹«åŠ©è‡ªå·±ã€‚ä¾‹å¦‚ï¼Œä½ å¯ä»¥è©¦è‘—找到其他å—影響的人，和他們一 +å› æ¤ä½ ä»ç„¶å¯ä»¥è‡ªå·±å¹«åŠ©è‡ªå·±ã€‚ä¾‹å¦‚ï¼Œä½ å¯ä»¥è©¦ç€æ‰¾åˆ°å…¶ä»–å—影響的人，和他們一 èµ·åˆä½œä¾†è§£æ±ºé€™å€‹å•é¡Œã€‚這樣的團隊å¯ä»¥ä¸€èµ·æº–å‚™ä¸€ä»½æ–°çš„å ±å‘Šï¼Œæ到團隊有多少人， çˆ²ä»€éº¼ä½ å€‘èªçˆ²é€™æ˜¯æ‡‰è©²å¾—åˆ°è§£æ±ºçš„äº‹æƒ…ã€‚ä¹Ÿè¨±ä½ å€‘é‚„å¯ä»¥ä¸€èµ·ç¸®å°ç¢ºåˆ‡åŽŸå› 或引 -入回æ¸çš„變化，這往往會使修復更容易。而且如果é‹æ°£å¥½çš„話，團隊ä¸å¯èƒ½æœƒæœ‰æ‡‚點 -編程的人，也許能寫出一個修複方案。 +入迴æ¸çš„變化，這往往會使修復更容易。而且如果é‹æ°£å¥½çš„話，團隊ä¸å¯èƒ½æœƒæœ‰æ‡‚點 +編程的人，也許能寫出一個修復方案。 -ã€Œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„回æ¸ã€çš„åƒè€ƒ +â€œå ±å‘Šç©©å®šç‰ˆå’Œé•·æœŸæ”¯æŒå…§æ ¸ç·šçš„è¿´æ¸â€çš„åƒè€ƒ ------------------------------------------ -本å°ç¯€æ供了在穩定版和長期支æŒå…§æ ¸ç·šä¸é¢å°å›žæ¸æ™‚需è¦åŸ·è¡Œçš„æ¥é©Ÿçš„詳細信æ¯ã€‚ +本å°ç¯€æ供了在穩定版和長期支æŒå…§æ ¸ç·šä¸é¢å°è¿´æ¸æ™‚需è¦åŸ·è¡Œçš„æ¥é©Ÿçš„詳細信æ¯ã€‚ 確ä¿ç‰¹å®šç‰ˆæœ¬ç·šä»ç„¶å—æ”¯æŒ ~~~~~~~~~~~~~~~~~~~~~~~~~ *æª¢æŸ¥å…§æ ¸é–‹ç™¼äººå“¡æ˜¯å¦ä»ç„¶ç¶è·ä½ 關心的Linuxå…§æ ¸ç‰ˆæœ¬ç·šï¼šåŽ» kernel.org çš„ - 首é ，確ä¿æ¤ç‰¹å®šç‰ˆæœ¬ç·šçš„最新版沒有「[EOL]ã€æ¨™è¨˜ã€‚* + 首é ，確ä¿æ¤ç‰¹å®šç‰ˆæœ¬ç·šçš„最新版沒有“[EOL]â€æ¨™è¨˜ã€‚* å¤§å¤šæ•¸å…§æ ¸ç‰ˆæœ¬ç·šåªæ”¯æŒä¸‰å€‹æœˆå·¦å³ï¼Œå› 爲延長ç¶è·æ™‚é–“æœƒå¸¶ä¾†ç›¸ç•¶å¤šçš„å·¥ä½œã€‚å› æ¤ï¼Œ æ¯å¹´åªæœƒé¸æ“‡ä¸€å€‹ç‰ˆæœ¬ä¾†æ”¯æŒè‡³å°‘兩年（通常是å…å¹´ï¼‰ã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ éœ€è¦æª¢æŸ¥ å…§æ ¸é–‹ç™¼è€…æ˜¯å¦é‚„支æŒä½ 關心的版本線。 -注æ„，如果 `kernel.org <https://kernel.org/>`_ 在首é 上列出了兩個「穩定ã€ç‰ˆæœ¬ï¼Œ +注æ„，如果 `kernel.org <https://kernel.org/>`_ 在首é 上列出了兩個“穩定â€ç‰ˆæœ¬ï¼Œ ä½ æ‡‰è©²è€ƒæ…®åˆ‡æ›åˆ°è¼ƒæ–°çš„版本，而忘掉較舊的版本：å°å®ƒçš„支æŒå¯èƒ½å¾ˆå¿«å°±æœƒçµæŸã€‚ -然後，它將被標記爲「生命周期çµæŸã€ï¼ˆEOL）。é”到這個程度的版本線ä»ç„¶æœƒåœ¨ -`kernel.org <https://kernel.org/>`_ 首é 上被顯示一兩周，但ä¸é©åˆç”¨æ–¼æ¸¬è©¦å’Œ +然後，它將被標記爲“生命週期çµæŸâ€ï¼ˆEOL）。é”到這個程度的版本線ä»ç„¶æœƒåœ¨ +`kernel.org <https://kernel.org/>`_ 首é 上被顯示一兩週，但ä¸é©åˆç”¨æ–¼æ¸¬è©¦å’Œ å ±å‘Šã€‚ æœç´¢ç©©å®šç‰ˆéƒµä»¶åˆ—表 @@ -1158,57 +1161,63 @@ FLOSS å•é¡Œå ±å‘Šçš„人看，詢å•ä»–們的æ„見。åŒæ™‚å¾µæ±‚ä»–å€‘é—œæ–¼å¦ ç”¨æœ€æ–°ç‰ˆæœ¬å¾©ç¾å•é¡Œ ~~~~~~~~~~~~~~~~~~~ - *從特定的版本線安è£æœ€æ–°ç‰ˆæœ¬ä½œçˆ²ç´”æ·¨å…§æ ¸ã€‚ç¢ºä¿é€™å€‹å…§æ ¸æ²’æœ‰è¢«æ±™æŸ“ï¼Œä¸¦ä¸”ä» - 然å˜åœ¨å•é¡Œï¼Œå› 爲å•é¡Œå¯èƒ½å·²ç¶“在那裡被修復了。* + *從特定的版本線安è£æœ€æ–°ç‰ˆæœ¬ä½œçˆ²ç´”æ·¨å…§æ ¸ã€‚ç¢ºä¿é€™å€‹å…§æ ¸æ²’æœ‰è¢«æ±¡æŸ“ï¼Œä¸¦ä¸”ä» + 然å˜åœ¨å•é¡Œï¼Œå› 爲å•é¡Œå¯èƒ½å·²ç¶“在那è£è¢«ä¿®å¾©äº†ã€‚* 在投入更多時間到這個éŽç¨‹ä¸ä¹‹å‰ï¼Œä½ è¦æª¢æŸ¥é€™å€‹å•é¡Œæ˜¯å¦åœ¨ä½ 關注的版本線的最新 -版本ä¸å·²ç¶“å¾—åˆ°äº†ä¿®å¾©ã€‚é€™å€‹å…§æ ¸éœ€è¦æ˜¯ç´”淨的，在å•é¡Œç™¼ç”Ÿä¹‹å‰ä¸æ‡‰è©²è¢«æ±™æŸ“ï¼Œæ£ +版本ä¸å·²ç¶“å¾—åˆ°äº†ä¿®å¾©ã€‚é€™å€‹å…§æ ¸éœ€è¦æ˜¯ç´”淨的，在å•é¡Œç™¼ç”Ÿä¹‹å‰ä¸æ‡‰è©²è¢«æ±¡æŸ“ï¼Œæ£ å¦‚ä¸Šé¢å·²ç¶“在測試主線的éŽç¨‹ä¸è©³ç´°ä»‹ç´¹éŽçš„一樣。 -您是å¦æ˜¯ç¬¬ä¸€æ¬¡æ³¨æ„åˆ°ä¾›æ‡‰å•†å…§æ ¸çš„å›žæ¸ï¼Ÿä¾›æ‡‰å•†çš„更改å¯èƒ½æœƒç™¼ç”Ÿè®ŠåŒ–ã€‚ä½ éœ€è¦é‡æ–° +您是å¦æ˜¯ç¬¬ä¸€æ¬¡æ³¨æ„åˆ°ä¾›æ‡‰å•†å…§æ ¸çš„è¿´æ¸ï¼Ÿä¾›æ‡‰å•†çš„更改å¯èƒ½æœƒç™¼ç”Ÿè®ŠåŒ–ã€‚ä½ éœ€è¦é‡æ–° 檢查排除來這個å•é¡Œã€‚當您從5.10.4-vendor.42更新到5.10.5-vendor.43時，記錄æ壞 çš„ä¿¡æ¯ã€‚然後在測試了å‰ä¸€æ®µä¸æ‰€è¿°çš„最新5.10版本之後，檢查Linux 5.10.4的普通版本 -是å¦ä¹Ÿå¯ä»¥æ£å¸¸å·¥ä½œã€‚如果å•é¡Œåœ¨é‚£è£¡å‡ºç¾ï¼Œé‚£å°±ä¸ç¬¦åˆä¸Šæ¸¸å›žæ¸çš„æ¢ä»¶ï¼Œæ‚¨éœ€è¦åˆ‡æ› +是å¦ä¹Ÿå¯ä»¥æ£å¸¸å·¥ä½œã€‚如果å•é¡Œåœ¨é‚£è£å‡ºç¾ï¼Œé‚£å°±ä¸ç¬¦åˆä¸Šæ¸¸è¿´æ¸çš„æ¢ä»¶ï¼Œæ‚¨éœ€è¦åˆ‡æ› 回主é€æ¥æŒ‡å—ä¾†å ±å‘Šå•é¡Œã€‚ -å ±å‘Šå›žæ¸ +å ±å‘Šè¿´æ¸ ~~~~~~~~~~ - *å‘Linux穩定版郵件列表發é€ä¸€å€‹ç°¡çŸçš„å•é¡Œå ±å‘Š(stable@vger.kernel.org)。 - 大致æè¿°å•é¡Œï¼Œä¸¦è§£é‡‹å¦‚何復ç¾ã€‚講清楚首個出ç¾å•é¡Œçš„版本和最後一個工作æ£å¸¸ - 的版本。然後ç‰å¾…進一æ¥çš„指示。* + *å‘Linux穩定版郵件列表發é€ä¸€å€‹ç°¡çŸçš„å•é¡Œå ±å‘Š(stable@vger.kernel.org)並 + 抄é€Linuxè¿´æ¸éƒµä»¶åˆ—表（regressions@lists.linux.devï¼‰ï¼›å¦‚æžœä½ æ‡·ç–‘æ˜¯ç”±æŸ + å系統引起的，請抄é€å…¶ç¶è·äººå“¡å’Œå系統郵件列表。大致æè¿°å•é¡Œï¼Œä¸¦è§£é‡‹å¦‚ + 何復ç¾ã€‚講清楚首個出ç¾å•é¡Œçš„版本和最後一個工作æ£å¸¸çš„版本。然後ç‰å¾…進一 + æ¥çš„指示。* -ç•¶å ±å‘Šåœ¨ç©©å®šç‰ˆæˆ–é•·æœŸæ”¯æŒå…§æ ¸ç·šå…§ç™¼ç”Ÿçš„回æ¸ï¼ˆä¾‹å¦‚在從5.10.4更新到5.10.5時）， -一份簡çŸçš„å ±å‘Šè¶³ä»¥å¿«é€Ÿå ±å‘Šå•é¡Œã€‚å› æ¤åªéœ€è¦ç²—略的æ述。 +ç•¶å ±å‘Šåœ¨ç©©å®šç‰ˆæˆ–é•·æœŸæ”¯æŒå…§æ ¸ç·šå…§ç™¼ç”Ÿçš„è¿´æ¸ï¼ˆä¾‹å¦‚在從5.10.4更新到5.10.5時）， +一份簡çŸçš„å ±å‘Šè¶³ä»¥å¿«é€Ÿå ±å‘Šå•é¡Œã€‚å› æ¤åªéœ€å‘穩定版和迴æ¸éƒµä»¶åˆ—表發é€ç²—略的æè¿°ï¼› +ä¸éŽå¦‚æžœä½ æ‡·ç–‘æŸå系統導致æ¤å•é¡Œçš„話，請一併抄é€å…¶ç¶è·äººå“¡å’Œå系統郵件列表， +é€™æœƒåŠ å¿«é€²ç¨‹ã€‚ -但是請注æ„ï¼Œå¦‚æžœæ‚¨èƒ½å¤ æŒ‡æ˜Žå¼•å…¥å•é¡Œçš„確切版本，這將å°é–‹ç™¼äººå“¡æœ‰å¾ˆå¤§å¹«åŠ©ã€‚å› æ¤ -å¦‚æžœæœ‰æ™‚é–“çš„è©±ï¼Œè«‹å˜—è©¦ä½¿ç”¨æ™®é€šå…§æ ¸æ‰¾åˆ°è©²ç‰ˆæœ¬ã€‚è®“æˆ‘å€‘å‡è¨ç™¼è¡Œç‰ˆç™¼å¸ƒLinuxå…§æ ¸ +請注æ„ï¼Œå¦‚æžœæ‚¨èƒ½å¤ æŒ‡æ˜Žå¼•å…¥å•é¡Œçš„確切版本，這將å°é–‹ç™¼äººå“¡æœ‰å¾ˆå¤§å¹«åŠ©ã€‚å› æ¤ +å¦‚æžœæœ‰æ™‚é–“çš„è©±ï¼Œè«‹å˜—è©¦ä½¿ç”¨æ™®é€šå…§æ ¸æ‰¾åˆ°è©²ç‰ˆæœ¬ã€‚è®“æˆ‘å€‘å‡è¨ç™¼è¡Œç‰ˆç™¼ä½ˆ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_TW/admin-guide/bug-bisect.rstã€ã€‚ +å› æ¤å¦‚果時間å…許，考慮立å³é€²è¡Œé©ç•¶çš„二分。有關如何詳細信æ¯ï¼Œè«‹åƒé–±â€œå°è¿´æ¸çš„ +特別關照â€éƒ¨åˆ†å’Œæ–‡æª” Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 。 +如果æˆåŠŸäºŒåˆ†çš„話，請將“罪éç¦é¦–â€çš„ä½œè€…æ·»åŠ åˆ°æ”¶ä»¶äººä¸ï¼›åŒæ™‚抄é€æ‰€æœ‰åœ¨ +signed-off-byéˆä¸çš„人，您å¯ä»¥åœ¨æ交消æ¯çš„末尾找到。 -ã€Œå ±å‘Šåƒ…åœ¨èˆŠå…§æ ¸ç‰ˆæœ¬ç·šä¸ç™¼ç”Ÿçš„å•é¡Œã€çš„åƒè€ƒ ------------------------------------------- +â€œå ±å‘Šåƒ…åœ¨èˆŠå…§æ ¸ç‰ˆæœ¬ç·šä¸ç™¼ç”Ÿçš„å•é¡Œâ€çš„åƒè€ƒ +---------------------------------------- -æœ¬ç¯€è©³ç´°ä»‹ç´¹äº†å¦‚æžœç„¡æ³•ç”¨ä¸»ç·šå…§æ ¸é‡ç¾å•é¡Œï¼Œä½†å¸Œæœ›åœ¨èˆŠç‰ˆæœ¬ç·šï¼ˆåˆç¨±ç©©å®šç‰ˆå…§æ ¸å’Œ +本節詳細介紹çžå¦‚æžœç„¡æ³•ç”¨ä¸»ç·šå…§æ ¸é‡ç¾å•é¡Œï¼Œä½†å¸Œæœ›åœ¨èˆŠç‰ˆæœ¬ç·šï¼ˆåˆç¨±ç©©å®šç‰ˆå…§æ ¸å’Œ 長期支æŒå…§æ ¸ï¼‰ä¸ä¿®å¾©å•é¡Œæ™‚需è¦æŽ¡å–çš„æ¥é©Ÿã€‚ 有些修復太複雜 ~~~~~~~~~~~~~~~ *è«‹åšå¥½æº–備，接下來的幾個æ¥é©Ÿå¯èƒ½ç„¡æ³•åœ¨èˆŠç‰ˆæœ¬ä¸è§£æ±ºå•é¡Œï¼šä¿®å¾©å¯èƒ½å¤ªå¤§æˆ– - 太冒險，無法移æ¤åˆ°é‚£è£¡ã€‚* + 太冒險，無法移æ¤åˆ°é‚£è£ã€‚* å³ä½¿æ˜¯å¾®å°çš„ã€çœ‹ä¼¼æ˜Žé¡¯çš„代碼變化，有時也會帶來新的ã€å®Œå…¨æ„想ä¸åˆ°çš„å•é¡Œã€‚ç©© 定版和長期支æŒå…§æ ¸çš„ç¶è·è€…éžå¸¸æ¸…æ¥šé€™ä¸€é»žï¼Œå› æ¤ä»–們åªå°é€™äº›å…§æ ¸é€²è¡Œç¬¦åˆ -「Documentation/translations/zh_TW/process/stable-kernel-rules.rstã€ä¸æ‰€åˆ—出的 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst ä¸æ‰€åˆ—出的 è¦å‰‡çš„修改。 複雜或有風險的修改ä¸ç¬¦åˆæ¢ä»¶ï¼Œå› æ¤åªèƒ½æ‡‰ç”¨æ–¼ä¸»ç·šã€‚其他的修復很容易被回溯到 @@ -1220,7 +1229,7 @@ FLOSS å•é¡Œå ±å‘Šçš„人看，詢å•ä»–們的æ„見。åŒæ™‚å¾µæ±‚ä»–å€‘é—œæ–¼å¦ é€šç”¨æº–å‚™ ~~~~~~~~~~ - *執行上é¢ã€Œå ±å‘Šåƒ…åœ¨èˆŠå…§æ ¸ç‰ˆæœ¬ç·šä¸ç™¼ç”Ÿçš„å•é¡Œã€ä¸€ç¯€ä¸çš„å‰ä¸‰å€‹æ¥é©Ÿã€‚* + *執行上é¢â€œå ±å‘Šåƒ…åœ¨èˆŠå…§æ ¸ç‰ˆæœ¬ç·šä¸ç™¼ç”Ÿçš„å•é¡Œâ€ä¸€ç¯€ä¸çš„å‰ä¸‰å€‹æ¥é©Ÿã€‚* 您需è¦åŸ·è¡Œæœ¬æŒ‡å—å¦ä¸€ç¯€ä¸å·²ç¶“æ述的幾個æ¥é©Ÿã€‚這些æ¥é©Ÿå°‡è®“您： @@ -1242,21 +1251,21 @@ FLOSS å•é¡Œå ±å‘Šçš„人看，詢å•ä»–們的æ„見。åŒæ™‚å¾µæ±‚ä»–å€‘é—œæ–¼å¦ åœ¨è¨±å¤šæƒ…æ³ä¸‹ï¼Œä½ 所處ç†çš„å•é¡Œæœƒç™¼ç”Ÿåœ¨ä¸»ç·šä¸Šï¼Œä½†å·²åœ¨ä¸»ç·šä¸Šå¾—到了解決。修æ£å®ƒ çš„æ交也需è¦è¢«å›žæº¯æ‰èƒ½è§£æ±ºé€™å€‹å•é¡Œã€‚é€™å°±æ˜¯çˆ²ä»€éº¼ä½ è¦æœç´¢å®ƒæˆ–任何相關討論。 - * 首先嘗試在å˜æ”¾ Linux å…§æ ¸åŽŸå§‹ç¢¼çš„ Git 倉庫ä¸æ‰¾åˆ°ä¿®å¾©ã€‚ä½ å¯ä»¥é€šéŽ + * 首先åšè©¦åœ¨å˜æ”¾ 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 + ç”¨ä½ æœ€å–œæ¡çš„æœç´¢å¼•æ“Žæœç´¢ç¶²çµ¡ï¼Œä»¥åŠ `Linux kernel developers mailing list å…§æ ¸é–‹ç™¼è€…éƒµä»¶åˆ—è¡¨ <https://lore.kernel.org/lkml/>`_ 的檔案。也å¯ä»¥ 閱讀上é¢çš„ `定ä½å°Žè‡´å•é¡Œçš„å…§æ ¸å€åŸŸ` 一節，然後按照說明找到導致å•é¡Œçš„åç³» 統：它的缺陷跟蹤器或郵件列表å˜æª”ä¸å¯èƒ½æœ‰ä½ è¦æ‰¾çš„ç”案。 @@ -1286,41 +1295,41 @@ FLOSS å•é¡Œå ±å‘Šçš„人看，詢å•ä»–們的æ„見。åŒæ™‚å¾µæ±‚ä»–å€‘é—œæ–¼å¦ çˆ²ä»€éº¼æœ‰äº›å•é¡Œåœ¨å ±å‘Šå¾Œæ²’有任何回應或ä»æœªè§£æ±ºï¼Ÿ =============================================== -ç•¶å‘ Linux é–‹ç™¼è€…å ±å‘Šå•é¡Œæ™‚，è¦æ³¨æ„åªæœ‰ã€Œé«˜å„ªå…ˆç´šçš„å•é¡Œã€ï¼ˆå›žæ¸ã€å®‰å…¨å•é¡Œã€åš´ +ç•¶å‘ Linux é–‹ç™¼è€…å ±å‘Šå•é¡Œæ™‚，è¦æ³¨æ„åªæœ‰â€œé«˜å„ªå…ˆç´šçš„å•é¡Œâ€ï¼ˆè¿´æ¸ã€å®‰å…¨å•é¡Œã€åš´ é‡å•é¡Œï¼‰æ‰ä¸€å®šæœƒå¾—到解決。如果ç¶è·è€…或其他人都失敗了，Linus Torvalds 他自己 會確ä¿é€™ä¸€é»žã€‚ä»–å€‘å’Œå…¶ä»–å…§æ ¸é–‹ç™¼è€…ä¹Ÿæœƒè§£æ±ºå¾ˆå¤šå…¶ä»–å•é¡Œã€‚但是è¦çŸ¥é“，有時他 們也會ä¸èƒ½æˆ–ä¸é¡˜å¹«å¿™ï¼›æœ‰æ™‚ç”šè‡³æ²’æœ‰äººç™¼å ±å‘Šçµ¦ä»–å€‘ã€‚ æœ€å¥½çš„è§£é‡‹å°±æ˜¯é‚£äº›å…§æ ¸é–‹ç™¼è€…å¸¸å¸¸æ˜¯åœ¨æ¥é¤˜æ™‚間爲 Linux å…§æ ¸åšå‡ºè²¢ç»ã€‚å…§æ ¸ä¸çš„ -ä¸å°‘驅動程åºéƒ½æ˜¯ç”±é€™æ¨£çš„程å¼è¨è¨ˆå¸«ç·¨å¯«çš„，往往åªæ˜¯å› 爲他們想讓自己的硬體å¯ä»¥åœ¨ -自己喜æ¡çš„作æ¥ç³»çµ±ä¸Šä½¿ç”¨ã€‚ +ä¸å°‘驅動程åºéƒ½æ˜¯ç”±é€™æ¨£çš„程åºå“¡ç·¨å¯«çš„，往往åªæ˜¯å› 爲他們想讓自己的硬件å¯ä»¥åœ¨ +自己喜æ¡çš„æ“作系統上使用。 -這些程å¼è¨è¨ˆå¸«å¤§å¤šæ•¸æ™‚候會很樂æ„ä¿®å¾©åˆ¥äººå ±å‘Šçš„å•é¡Œã€‚但是沒有人å¯ä»¥å¼·è¿«ä»–們這樣 +這些程åºå“¡å¤§å¤šæ•¸æ™‚候會很樂æ„ä¿®å¾©åˆ¥äººå ±å‘Šçš„å•é¡Œã€‚但是沒有人å¯ä»¥å¼·è¿«ä»–們這樣 åšï¼Œå› 爲他們是自願貢ç»çš„。 還有一些情æ³ä¸‹ï¼Œé€™äº›é–‹ç™¼è€…真的很想解決一個å•é¡Œï¼Œä½†å»ä¸èƒ½è§£æ±ºï¼šæœ‰æ™‚ä»–å€‘ç¼ºä¹ -硬體編程文檔來解決å•é¡Œã€‚這種情æ³å¾€å¾€ç”±æ–¼å…¬é–‹çš„文檔太簡陋，或者驅動程åºæ˜¯é€š +硬件編程文檔來解決å•é¡Œã€‚這種情æ³å¾€å¾€ç”±æ–¼å…¬é–‹çš„文檔太簡陋，或者驅動程åºæ˜¯é€š éŽé€†å‘工程編寫的。 -æ¥é¤˜é–‹ç™¼è€…é²æ—©ä¹Ÿæœƒä¸å†é—œå¿ƒæŸé©…動。也許他們的測試硬體壞了，被更高級的玩æ„å– -代了，或者是太è€äº†ä»¥è‡³æ–¼åªèƒ½åœ¨è¨ˆç®—æ©Ÿåšç‰©é¤¨è£¡æ‰¾åˆ°ã€‚æœ‰æ™‚é–‹ç™¼è€…æ ¹æœ¬å°±ä¸é—œå¿ƒä»– +æ¥é¤˜é–‹ç™¼è€…é²æ—©ä¹Ÿæœƒä¸å†é—œå¿ƒæŸé©…動。也許他們的測試硬件壞了，被更高級的玩æ„å– +代了，或者是太è€äº†ä»¥è‡³æ–¼åªèƒ½åœ¨è¨ˆç®—æ©Ÿåšç‰©é¤¨è£æ‰¾åˆ°ã€‚æœ‰æ™‚é–‹ç™¼è€…æ ¹æœ¬å°±ä¸é—œå¿ƒä»– 們的代碼和 Linux äº†ï¼Œå› çˆ²åœ¨ä»–å€‘çš„ç”Ÿæ´»ä¸ä¸€äº›ä¸åŒçš„æ±è¥¿è®Šå¾—æ›´é‡è¦äº†ã€‚在æŸäº›æƒ… æ³ä¸‹ï¼Œæ²’有人願æ„接手ç¶è·è€…的工作——也沒有人å¯ä»¥è¢«å¼·è¿«ï¼Œå› çˆ²å° Linux å…§æ ¸çš„è²¢ ç»æ˜¯è‡ªé¡˜çš„。然而被éºæ£„的驅動程åºä»ç„¶å˜åœ¨æ–¼å…§æ ¸ä¸ï¼šå®ƒå€‘å°äººå€‘ä»ç„¶æœ‰ç”¨ï¼Œåˆªé™¤ -它們å¯èƒ½å°Žè‡´å›žæ¸ã€‚ +它們å¯èƒ½å°Žè‡´è¿´æ¸ã€‚ å°æ–¼é‚£äº›çˆ² Linux å…§æ ¸å·¥ä½œè€Œç²å¾—å ±é…¬çš„é–‹ç™¼è€…ä¾†èªªï¼Œæƒ…æ³ä¸¦æ²’有什麼ä¸åŒã€‚這些人 ç¾åœ¨è²¢ç»äº†å¤§éƒ¨åˆ†çš„變更。但是他們的僱主é²æ—©ä¹Ÿæœƒåœæ¢é—œæ³¨ä»–å€‘çš„ä»£ç¢¼æˆ–è€…è®“ç¨‹åº -å“¡å°ˆæ³¨æ–¼å…¶ä»–äº‹æƒ…ã€‚ä¾‹å¦‚ï¼Œç¡¬é«”å» å•†ä¸»è¦é€šéŽéŠ·å”®æ–°ç¡¬é«”ä¾†è³ºéŒ¢ï¼›å› æ¤ï¼Œä»–們ä¸çš„ä¸ +å“¡å°ˆæ³¨æ–¼å…¶ä»–äº‹æƒ…ã€‚ä¾‹å¦‚ï¼Œç¡¬ä»¶å» å•†ä¸»è¦é€šéŽéŠ·å”®æ–°ç¡¬ä»¶ä¾†è³ºéŒ¢ï¼›å› æ¤ï¼Œä»–們ä¸çš„ä¸ å°‘äººä¸¦æ²’æœ‰æŠ•å…¥å¤ªå¤šæ™‚é–“å’Œç²¾åŠ›ä¾†ç¶è·ä»–們多年å‰å°±åœæ¢éŠ·å”®çš„æ±è¥¿çš„ Linux å…§æ ¸é©… 動。ä¼æ¥ç´š Linux 發行商往往æŒçºŒç¶è·çš„時間比較長，但在新版本ä¸å¾€å¾€æœƒæŠŠå°è€èˆŠ -和稀有硬體的支æŒæ”¾åœ¨ä¸€é‚Šï¼Œä»¥é™åˆ¶ç¯„åœã€‚一旦公å¸æ‹‹æ£„了一些代碼，往往由æ¥é¤˜è²¢ +和稀有硬件的支æŒæ”¾åœ¨ä¸€é‚Šï¼Œä»¥é™åˆ¶ç¯„åœã€‚一旦公å¸æ‹‹æ£„了一些代碼，往往由æ¥é¤˜è²¢ ç»è€…接手，但æ£å¦‚上é¢æ到的：他們é²æ—©ä¹Ÿæœƒæ”¾ä¸‹ä»£ç¢¼ã€‚ 優先級是一些å•é¡Œæ²’有被修復的å¦ä¸€å€‹åŽŸå› ï¼Œå› çˆ²ç¶è·è€…相當多的時候是被迫è¨ç½®é€™ äº›å„ªå…ˆç´šçš„ï¼Œå› çˆ²åœ¨ Linux 上工作的時間是有é™çš„。å°æ–¼æ¥é¤˜æ™‚間或者僱主給予他們 çš„é–‹ç™¼äººå“¡ç”¨æ–¼ä¸Šæ¸¸å…§æ ¸ç¶è·å·¥ä½œçš„時間也是如æ¤ã€‚有時ç¶è·äººå“¡ä¹Ÿæœƒè¢«å ±å‘Šæ·¹æ²’， -å³ä½¿ä¸€å€‹é©…動程åºå¹¾ä¹Žå®Œç¾Žåœ°å·¥ä½œã€‚爲了ä¸è¢«å®Œå…¨çºä½ï¼Œç¨‹å¼è¨è¨ˆå¸«å¯èƒ½åˆ¥ç„¡é¸æ“‡ï¼Œåªèƒ½ +å³ä½¿ä¸€å€‹é©…動程åºå¹¾ä¹Žå®Œç¾Žåœ°å·¥ä½œã€‚爲了ä¸è¢«å®Œå…¨çºä½ï¼Œç¨‹åºå“¡å¯èƒ½åˆ¥ç„¡é¸æ“‡ï¼Œåªèƒ½ å°å•é¡Œå ±å‘Šé€²è¡Œå„ªå…ˆç´šæŽ’åºè€Œæ‹’絕其ä¸çš„ä¸€äº›å ±å‘Šã€‚ ä¸éŽé€™äº›éƒ½ä¸ç”¨å¤ªéŽæ“”心，很多驅動都有ç©æ¥µçš„ç¶è·è€…，他們å°å„˜å¯èƒ½å¤šçš„解決å•é¡Œ @@ -1330,8 +1339,32 @@ FLOSS å•é¡Œå ±å‘Šçš„人看，詢å•ä»–們的æ„見。åŒæ™‚å¾µæ±‚ä»–å€‘é—œæ–¼å¦ çµæŸèªž ======= -與其他å…è²»/自由&é–‹æºè»Ÿé«”（Free/Libre & Open Source Software，FLOSS）相比， -å‘ Linux å…§æ ¸é–‹ç™¼è€…å ±å‘Šå•é¡Œæ˜¯å¾ˆé›£çš„：這個文檔的長度和複雜性以åŠå—裡行間的內 +與其他å…è²»/自由&é–‹æºè»Ÿä»¶ï¼ˆFree/Libre & Open Source Software，FLOSS）相比， +å‘ Linux å…§æ ¸é–‹ç™¼è€…å ±å‘Šå•é¡Œæ˜¯å¾ˆé›£çš„：這個文檔的長度和複雜性以åŠå—è£è¡Œé–“çš„å…§ 涵都說明了這一點。但目å‰å°±æ˜¯é€™æ¨£äº†ã€‚這篇文å—的主è¦ä½œè€…希望通éŽè¨˜éŒ„ç¾ç‹€ä¾†çˆ² 以後改善這種狀æ³æ‰“下一些基礎。 + +.. + end-of-content +.. + This English version of this document 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. For translation problems, please + contact with translators. 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". +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. 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. + diff --git a/Documentation/translations/zh_TW/admin-guide/reporting-regressions.rst b/Documentation/translations/zh_TW/admin-guide/reporting-regressions.rst new file mode 100644 index 000000000000..d7dcb2a26564 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/reporting-regressions.rst @@ -0,0 +1,371 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. ã€é‡åˆ†ç™¼ä¿¡æ¯åƒè¦‹æœ¬æ–‡ä»¶çµå°¾ã€‘ + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/reporting-regressions.rst + +:è¯è€…: + + å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + + +============ +å ±å‘Šè¿´æ¸å•é¡Œ +============ + +“*我們拒絕出ç¾è¿´æ¸*â€æ˜¯Linuxå…§æ ¸é–‹ç™¼çš„é¦–è¦è¦å‰‡ï¼›Linuxçš„ç™¼èµ·è€…å’Œé ˜è»é–‹ç™¼è€…Linus +Torvalds立下了æ¤è¦å‰‡ä¸¦ç¢ºä¿å®ƒè¢«è½å¯¦ã€‚ + +本文檔æ述了這æ¢è¦å‰‡å°ç”¨æˆ¶çš„æ„義，以åŠLinuxå…§æ ¸é–‹ç™¼æ¨¡åž‹å¦‚ä½•ç¢ºä¿è§£æ±ºæ‰€æœ‰è¢«å ±å‘Š +çš„è¿´æ¸ï¼›é—œæ–¼å…§æ ¸é–‹ç™¼è€…如何處ç†çš„æ–¹é¢åƒè¦‹ Documentation/process/handling-regressions.rst 。 + + +本文é‡é»žï¼ˆäº¦å³â€œå¤ªé•·ä¸çœ‹â€ï¼‰ +========================== + +#. 如果æŸç¨‹åºåœ¨åŽŸå…ˆçš„Linuxå…§æ ¸ä¸Šé‹è¡Œè‰¯å¥½ï¼Œä½†åœ¨è¼ƒæ–°ç‰ˆæœ¬ä¸Šæ•ˆæžœæ›´å·®ã€æˆ–è€…æ ¹æœ¬ä¸ + èƒ½ç”¨ï¼Œé‚£éº¼ä½ å°±ç¢°è¦‹è¿´æ¸å•é¡Œäº†ã€‚注æ„ï¼Œæ–°å…§æ ¸éœ€è¦ä½¿ç”¨é¡žä¼¼é…置編è¯ï¼›æ›´å¤šç›¸é—œç´° + 節åƒè¦‹ä¸‹æ–¹ã€‚ + +#. 按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst ä¸ + æ‰€èªªçš„å ±å‘Šä½ çš„å•é¡Œï¼Œè©²æ–‡æª”已經包å«äº†æ‰€æœ‰é—œæ–¼è¿´æ¸çš„é‡è¦æ–¹é¢ï¼Œçˆ²äº†æ–¹ä¾¿èµ·è¦‹ä¹Ÿ + 複製到了下é¢ã€‚兩個é‡é»žï¼šåœ¨å ±å‘Šä¸»é¡Œä¸ä½¿ç”¨â€œ[REGRESSION]â€é–‹é 並抄é€æˆ–轉發到 + `è¿´æ¸éƒµä»¶åˆ—表 <https://lore.kernel.org/regressions/>`_ + （regressions@lists.linux.dev）。 + +#. å¯é¸ä½†æ˜¯å»ºè°ï¼šåœ¨ç™¼é€æˆ–è½‰ç™¼å ±å‘Šæ™‚ï¼ŒæŒ‡æ˜Žè©²å›žæ¸ç™¼ç”Ÿçš„起點，以便Linuxå…§æ ¸è¿´æ¸ + 追蹤機器人“regzbotâ€å¯ä»¥è¿½è¹¤æ¤å•é¡Œ:: + + #regzbot introduced v5.13..v5.14-rc1 + + +與用戶相關的所有Linuxå…§æ ¸è¿´æ¸ç´°ç¯€ +================================= + + +基本é‡é»ž +-------- + + +什麼是“迴æ¸â€ä»¥åŠä»€éº¼æ˜¯â€œç„¡è¿´æ¸è¦å‰‡â€ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果æŸç¨‹åº/實例在原先的Linuxå…§æ ¸ä¸Šé‹è¡Œè‰¯å¥½ï¼Œä½†åœ¨è¼ƒæ–°ç‰ˆæœ¬ä¸Šæ•ˆæžœæ›´å·®ã€æˆ–è€…æ ¹æœ¬ +ä¸èƒ½ç”¨ï¼Œé‚£éº¼ä½ 就碰見迴æ¸å•é¡Œäº†ã€‚“無迴æ¸è¦å‰‡â€ä¸å…許出ç¾é€™ç¨®æƒ…æ³ã€‚如果å¶ç„¶ç™¼ +生了，導致å•é¡Œçš„開發者應當迅速修復å•é¡Œã€‚ + +也就是說，若Linux 5.13ä¸çš„WiFi驅動程åºé‹è¡Œè‰¯å¥½ï¼Œä½†æ˜¯åœ¨5.14版本上å»ä¸èƒ½ç”¨ã€é€Ÿ +度明顯變慢或出ç¾éŒ¯èª¤ï¼Œé‚£å°±å‡ºç¾äº†è¿´æ¸ã€‚如果æŸæ£å¸¸å·¥ä½œçš„應用程åºçªç„¶åœ¨æ–°å…§æ ¸ä¸Š +出ç¾ä¸ç©©å®šï¼Œé€™ä¹Ÿæ˜¯è¿´æ¸ï¼›é€™äº›å•é¡Œå¯èƒ½æ˜¯ç”±æ–¼procfsã€sysfs或Linuxæ供給用戶空間 +軟件的許多其他接å£ä¹‹ä¸€çš„變化。但請記ä½ï¼Œå‰è¿°ä¾‹åä¸çš„5.14需è¦ä½¿ç”¨é¡žä¼¼æ–¼5.13çš„ +é…置構建。這å¯ä»¥ç”¨ ``make olddefconfig`` 實ç¾ï¼Œè©³ç´°è§£é‡‹è¦‹ä¸‹ã€‚ + +注æ„本節第一å¥è©±ä¸çš„“實例â€ï¼šå³ä½¿é–‹ç™¼è€…需è¦éµå¾ªâ€œç„¡è¿´æ¸â€è¦å‰‡ï¼Œä½†ä»å¯è‡ªç”±åœ°æ”¹ +è®Šå…§æ ¸çš„ä»»ä½•æ–¹é¢ï¼Œç”šè‡³æ˜¯å°Žå‡ºåˆ°ç”¨æˆ¶ç©ºé–“çš„API或ABI，åªè¦åˆ¥ç ´å£žç¾æœ‰çš„應用程åºæˆ– +用例。 + +還需注æ„，“無迴æ¸â€è¦å‰‡åªé™åˆ¶å…§æ ¸æ供給用戶空間的接å£ã€‚它ä¸é©ç”¨æ–¼å…§æ ¸å…§éƒ¨æŽ¥ +å£ï¼Œæ¯”如一些外部開發的驅動程åºç”¨ä¾†æ’入鉤ååˆ°å…§æ ¸çš„æ¨¡å¡ŠAPI。 + +å¦‚ä½•å ±å‘Šè¿´æ¸ï¼Ÿ +~~~~~~~~~~~~~~ + +åªéœ€æŒ‰ç…§ Documentation/translations/zh_CN/admin-guide/reporting-issues.rst ä¸ +æ‰€èªªçš„å ±å‘Šä½ çš„å•é¡Œï¼Œè©²æ–‡æª”已經包å«äº†è¦é»žã€‚下é¢å¹¾é»žæ¦‚述了一下åªåœ¨è¿´æ¸ä¸é‡è¦çš„ +æ–¹é¢ï¼š + + * 在檢查å¯åŠ 入討論的ç¾æœ‰å ±å‘Šæ™‚，別忘了æœç´¢ `Linuxè¿´æ¸éƒµä»¶åˆ—表 + <https://lore.kernel.org/regressions/>`_ å’Œ `regzbot網é ç•Œé¢ + <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + + * åœ¨å ±å‘Šä¸»é¡Œçš„é–‹é åŠ ä¸Šâ€œ[REGRESSION]â€ã€‚ + + * åœ¨ä½ çš„å ±å‘Šä¸æ˜Žç¢ºæœ€å¾Œä¸€å€‹æ£å¸¸å·¥ä½œçš„å…§æ ¸ç‰ˆæœ¬å’Œé¦–å€‹å‡ºå•é¡Œçš„版本。如若å¯èƒ½ï¼Œ + 用二分法嘗試找出導致迴æ¸çš„變更，更多細節見下。 + + * è¨˜å¾—æŠŠå ±å‘Šç™¼åˆ°Linuxè¿´æ¸éƒµä»¶åˆ—表（regressions@lists.linux.dev）。 + + * 如果通éŽéƒµä»¶å ±å‘Šè¿´æ¸ï¼Œè«‹æŠ„é€å›žæ¸åˆ—表。 + + * å¦‚æžœä½ ä½¿ç”¨æŸäº›ç¼ºé™·è¿½è¹¤å™¨å ±å‘Šè¿´æ¸ï¼Œè«‹é€šéŽéƒµä»¶è½‰ç™¼å·²æäº¤çš„å ±å‘Šåˆ°è¿´æ¸åˆ—表， + 並抄é€ç¶è·è€…以åŠå‡ºå•é¡Œçš„相關å系統的郵件列表。 + + 如果是穩定版或長期支æŒç‰ˆç³»åˆ—（如v5.15.3…v5.15.5）的迴æ¸ï¼Œè«‹è¨˜å¾—æŠ„é€ + `Linux穩定版郵件列表 <https://lore.kernel.org/stable/>`_ （stable@vger.kernel.org）。 + + å¦‚æžœä½ æˆåŠŸåœ°åŸ·è¡Œäº†äºŒåˆ†ï¼Œè«‹æŠ„é€è‚‡äº‹æ交的信æ¯ä¸æ‰€æœ‰ç°½äº†â€œSigned-off-by:â€çš„人。 + +在抄é€ä½ çš„å ±å‘Šåˆ°åˆ—è¡¨æ™‚ï¼Œä¹Ÿè«‹è¨˜å¾—é€šçŸ¥å‰è¿°çš„Linuxå…§æ ¸è¿´æ¸è¿½è¹¤æ©Ÿå™¨äººã€‚åªéœ€åœ¨éƒµä»¶ +ä¸åŒ…å«å¦‚下片段:: + + #regzbot introduced: v5.13..v5.14-rc1 + +Regzbotæœƒå°±å°‡ä½ çš„éƒµä»¶è¦–çˆ²åœ¨æŸå€‹ç‰¹å®šç‰ˆæœ¬å€é–“çš„è¿´æ¸å ±å‘Šã€‚上例ä¸å³linux v5.13ä» +然æ£å¸¸ï¼Œè€ŒLinux 5.14-rc1是首個您é‡åˆ°å•é¡Œçš„ç‰ˆæœ¬ã€‚å¦‚æžœä½ åŸ·è¡Œäº†äºŒåˆ†ä»¥æŸ¥æ‰¾å°Žè‡´å›ž +æ¸çš„æ交，請使用指定肇事æ交的id代替:: + + #regzbot introduced: 1f2e3d4c5d + +æ·»åŠ é€™æ¨£çš„â€œregzbot命令â€å°ä½ 是有好處的，它會確ä¿å ±å‘Šä¸æœƒè¢«å¿½ç•¥ã€‚å¦‚æžœä½ çœç•¥äº† +它，Linuxå…§æ ¸çš„è¿´æ¸è·Ÿè¹¤è€…æœƒæŠŠä½ çš„è¿´æ¸å‘Šè¨´regzbot，åªè¦ä½ 發é€äº†ä¸€å€‹å‰¯æœ¬åˆ°è¿´æ¸ +郵件列表。但是迴æ¸è·Ÿè¹¤è€…åªæœ‰ä¸€å€‹äººï¼Œæœ‰æ™‚ä¸å¾—ä¸ä¼‘æ¯æˆ–甚至å¶çˆ¾äº«å—å¯ä»¥é 離電腦 +的時光（è½èµ·ä¾†å¾ˆç˜‹ç‹‚ï¼‰ã€‚å› æ¤ï¼Œä¾è³´æ¤äººæ‰‹å‹•å°‡å›žæ¸æ·»åŠ 到 `已追蹤且尚未解決的 +Linuxå…§æ ¸è¿´æ¸åˆ—表 <https://linux-regtracking.leemhuis.info/regzbot/>`_ å’Œ +regzbot發é€çš„æ¯é€±è¿´æ¸å ±å‘Šï¼Œå¯èƒ½æœƒå‡ºç¾å»¶é²ã€‚ 這樣的延誤會導致Linus Torvalds +在決定“繼續開發還是發佈新版本？â€æ™‚忽略嚴é‡çš„è¿´æ¸ã€‚ + +真的修復了所有的迴æ¸å—Žï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~ + +幾乎所有都是，åªè¦å¼•èµ·å•é¡Œçš„變更（肇事æ交）被å¯é 定ä½ã€‚也有些迴æ¸å¯ä»¥ä¸ç”¨é€™ +æ¨£ï¼Œä½†é€šå¸¸æ˜¯å¿…é ˆçš„ã€‚ + +誰需è¦æ‰¾å‡ºè¿´æ¸çš„æ ¹æœ¬åŽŸå› ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å—影響代碼å€åŸŸçš„開發者應該自行嘗試定ä½å•é¡Œæ‰€åœ¨ã€‚但僅é 他們的努力往往是ä¸å¯ +能åšåˆ°çš„，很多å•é¡Œåªç™¼ç”Ÿåœ¨é–‹ç™¼è€…的無法接觸的其他特定外部環境ä¸â€”—例如特定的 +硬件平臺ã€å›ºä»¶ã€Linux發行版ã€ç³»çµ±çš„é…置或應用程åºã€‚é€™å°±æ˜¯çˆ²ä»€éº¼æœ€çµ‚å¾€å¾€æ˜¯å ± +告者定ä½è‚‡äº‹æ交；有時用戶甚至需è¦å†é‹è¡Œé¡å¤–æ¸¬è©¦ä»¥æŸ¥æ˜Žç¢ºåˆ‡çš„æ ¹æœ¬åŽŸå› ã€‚é–‹ç™¼ +者應該æ供建è°å’Œå¯èƒ½çš„幫助，以使普通用戶更容易完æˆè©²æµç¨‹ã€‚ + +如何找到罪éç¦é¦–？ +~~~~~~~~~~~~~~~~~~ + +如 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst （簡è¦ï¼‰ +å’Œ Documentation/translations/zh_CN/admin-guide/bug-bisect.rst （詳細）ä¸æ‰€ +述，執行二分。è½èµ·ä¾†å·¥ä½œé‡å¾ˆå¤§ï¼Œä½†å¤§éƒ¨åˆ†æƒ…æ³ä¸‹å¾ˆå¿«å°±èƒ½æ‰¾åˆ°ç½ªéç¦é¦–。如果這很 +困難或å¯é 地é‡ç¾å•é¡Œå¾ˆè€—時，請考慮與其他å—影響的用戶åˆä½œï¼Œä¸€èµ·ç¸®å°æœç´¢ç¯„åœã€‚ + +當出ç¾è¿´æ¸æ™‚我å¯ä»¥å‘誰尋求建è°ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +發é€éƒµä»¶åˆ°è¿´æ¸éƒµä»¶åˆ—表（regressions@lists.linux.dev）åŒæ™‚抄é€Linuxå…§æ ¸çš„è¿´æ¸ +跟蹤者（regressions@leemhuis.info）;如果å•é¡Œéœ€è¦ä¿å¯†è™•ç†ï¼Œå¯ä»¥çœç•¥åˆ—表。 + + +關於迴æ¸çš„更多細節 +------------------ + + +“無迴æ¸è¦å‰‡â€çš„目標是什麼？ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用戶應該放心å‡ç´šå…§æ ¸ç‰ˆæœ¬ï¼Œè€Œä¸å¿…擔心有程åºå¯èƒ½å´©æ½°ã€‚這符åˆå…§æ ¸é–‹ç™¼è€…的利益， +å¯ä»¥ä½¿æ›´æ–°æœ‰å¸å¼•åŠ›ï¼šä»–們ä¸å¸Œæœ›ç”¨æˆ¶åœç•™åœ¨åœæ¢ç¶è·æˆ–超éŽä¸€å¹´åŠçš„穩定/長期Linux +版本系列上。這也符åˆæ‰€æœ‰äººçš„åˆ©ç›Šï¼Œå› çˆ² `那些系列å¯èƒ½å«æœ‰å·²çŸ¥çš„缺陷ã€å®‰å…¨å•é¡Œ +或其他後續版本已經修復的å•é¡Œ +<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_ 。 +æ¤å¤–ï¼Œå…§æ ¸é–‹ç™¼è€…å¸Œæœ›ä½¿ç”¨æˆ¶æ¸¬è©¦æœ€æ–°çš„é 發行版或常è¦ç™¼è¡Œç‰ˆè®Šå¾—簡單而有å¸å¼•åŠ›ã€‚ +這åŒæ¨£ç¬¦åˆæ‰€æœ‰äººçš„åˆ©ç›Šï¼Œå¦‚æžœæ–°ç‰ˆæœ¬å‡ºä¾†å¾Œå¾ˆå¿«å°±æœ‰ç›¸é—œå ±å‘Šï¼Œæœƒä½¿è¿½è¹¤å’Œä¿®å¾©å•é¡Œ +更容易。 + +實際ä¸â€œç„¡è¿´æ¸â€è¦å‰‡çœŸçš„å¯è¡Œå—Žï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +這ä¸æ˜¯å¥çŽ©ç¬‘話，請見Linux創建者和主è¦é–‹ç™¼äººå“¡Linus Torvalds在郵件列表ä¸çš„許 +多發言，其ä¸ä¸€äº›åœ¨ Documentation/process/handling-regressions.rst ä¸è¢«å¼•ç”¨ã€‚ + +æ¤è¦å‰‡çš„例外情æ³æ¥µçˆ²ç½•è¦‹ï¼›ä¹‹å‰ç•¶é–‹ç™¼è€…èªçˆ²æŸå€‹ç‰¹å®šçš„情æ³æœ‰å¿…è¦æ´å¼•ä¾‹å¤–時， +基本都被è‰æ˜ŽéŒ¯äº†ã€‚ + +誰來確ä¿â€œç„¡è¿´æ¸â€è¢«è½å¯¦ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~ + +照看和支æ’樹的å系統ç¶è·è€…應該關心這一點——例如，Linus Torvalds之於主線， +Greg Kroah-Hartmanç‰äººä¹‹æ–¼å„種穩定/長期系列。 + +他們都得到了別人的幫助，以確ä¿è¿´æ¸å ±å‘Šä¸æœƒè¢«éºæ¼ã€‚å…¶ä¸ä¹‹ä¸€æ˜¯Thorsten +Leemhuis，他目å‰æ“”ä»»Linuxå…§æ ¸çš„â€œè¿´æ¸è·Ÿè¹¤è€…â€ï¼›çˆ²äº†åšå¥½é€™é …工作，他使用了 +regzbot——Linuxå…§æ ¸è¿´æ¸è·Ÿè¹¤æ©Ÿå™¨äººã€‚所以這就是爲什麼è¦æŠ„é€æˆ–è½‰ç™¼ä½ çš„å ±å‘Šåˆ° +è¿´æ¸éƒµä»¶åˆ—è¡¨ä¾†é€šçŸ¥é€™äº›äººï¼Œå·²ç¶“æœ€å¥½åœ¨ä½ çš„éƒµä»¶ä¸åŒ…å«â€œregzbot命令â€ä¾†ç«‹å³è¿½è¹¤å®ƒã€‚ + +è¿´æ¸é€šå¸¸å¤šä¹…能修復？ +~~~~~~~~~~~~~~~~~~~~ + +é–‹ç™¼è€…æ‡‰è©²å„˜å¿«ä¿®å¾©ä»»ä½•è¢«å ±å‘Šçš„è¿´æ¸ï¼Œä»¥æä¾›åŠæ™‚爲å—影響的用戶æ供解決方案，並 +防æ¢æ›´å¤šç”¨æˆ¶é‡åˆ°å•é¡Œï¼›ç„¶è€Œï¼Œé–‹ç™¼äººå“¡éœ€è¦èŠ±è¶³å¤ 的時間和注æ„力確ä¿è¿´æ¸ä¿®å¾©ä¸æœƒ +é€ æˆé¡å¤–çš„æ害。 + +å› æ¤ï¼Œç”案å–決於å„ç¨®å› ç´ ï¼Œå¦‚è¿´æ¸çš„影響ã€å˜åœ¨æ™‚長或出ç¾æ–¼å“ªå€‹Linux版本系列。 +但最終，大多數的迴æ¸æ‡‰è©²åœ¨å…©é€±å…§ä¿®å¾©ã€‚ + +當å•é¡Œå¯ä»¥é€šéŽå‡ç´šæŸäº›è»Ÿä»¶è§£æ±ºæ™‚，是迴æ¸å—Žï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +基本都是。如果開發人員告訴您其他情æ³ï¼Œè«‹è«®è©¢ä¸Šè¿°è¿´æ¸è·Ÿè¹¤è€…。 + +ç•¶æ–°å…§æ ¸è®Šæ…¢æˆ–èƒ½è€—å¢žåŠ ï¼Œæ˜¯è¿´æ¸å—Žï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但有一些差別。在微型基準測試ä¸è®Šæ…¢5%ä¸å¤ªå¯èƒ½è¢«è¦–爲迴æ¸ï¼Œé™¤éžå®ƒä¹Ÿæœƒå° +廣泛基準測試的çµæžœç”¢ç”Ÿè¶…éŽ1%的影響。如果有疑å•ï¼Œè«‹å°‹æ±‚建è°ã€‚ + +當更新Linuxæ™‚å¤–éƒ¨å…§æ ¸æ¨¡å¡Šå´©æ½°äº†ï¼Œæ˜¯è¿´æ¸å—Žï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ä¸ï¼Œå› 爲“無迴æ¸â€è¦å‰‡åƒ…é™æ–¼Linuxå…§æ ¸æ供給用戶空間的接å£å’Œæœå‹™ã€‚å› æ¤ï¼Œå®ƒä¸åŒ…括 +構建或é‹è¡Œå¤–éƒ¨é–‹ç™¼çš„å…§æ ¸æ¨¡å¡Šï¼Œå› çˆ²å®ƒå€‘åœ¨å…§æ ¸ç©ºé–“ä¸é‹è¡Œèˆ‡æŽ›é€²å…§æ ¸ä½¿ç”¨çš„內部接 +å£å¶çˆ¾æœƒè®ŠåŒ–。 + +如何處ç†å®‰å…¨ä¿®å¾©å¼•èµ·çš„è¿´æ¸ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在極爲罕見的情æ³ä¸‹ï¼Œå®‰å…¨å•é¡Œç„¡æ³•åœ¨ä¸å¼•èµ·è¿´æ¸çš„情æ³ä¸‹ä¿®å¾©ï¼›é€™äº›ä¿®å¾©éƒ½è¢«æ”¾æ£„了， +å› çˆ²å®ƒå€‘çµ‚ç©¶æœƒå¼•èµ·å•é¡Œã€‚幸é‹çš„是這種兩難境地基本都å¯ä»¥é¿å…，å—影響å€åŸŸçš„ä¸»è¦ +開發者以åŠLinus Torvalds本人通常都會努力在ä¸å¼•å…¥è¿´æ¸çš„情æ³ä¸‹è§£æ±ºå®‰å…¨å•é¡Œã€‚ + +å¦‚æžœä½ ä»ç„¶é¢è‡¨æ¤ç¨®æƒ…æ³ï¼Œè«‹æŸ¥çœ‹éƒµä»¶åˆ—表檔案是å¦æœ‰äººç›¡åŠ›é¿å…éŽè¿´æ¸ã€‚如果沒有， +è«‹å ±å‘Šå®ƒï¼›å¦‚æœ‰ç–‘å•ï¼Œè«‹å¦‚上所述尋求建è°ã€‚ + +當修復迴æ¸æ™‚ä¸å¯é¿å…會引入å¦ä¸€å€‹ï¼Œå¦‚何處ç†ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +很éºæ†¾é€™ç¨®äº‹ç¢ºå¯¦æœƒå‡ºç¾ï¼Œä½†å¹¸é‹çš„是並ä¸ç¶“常出ç¾ï¼›å¦‚果發生了，å—影響代碼å€çš„資 +深開發者應當調查該å•é¡Œä»¥æ‰¾åˆ°é¿å…è¿´æ¸çš„解決方法，至少é¿å…å®ƒå€‘çš„å½±éŸ¿ã€‚å¦‚æžœä½ é‡ +到這樣的情æ³ï¼Œå¦‚上所述：檢查之å‰çš„討論是å¦æœ‰äººå·²ç¶“盡了最大努力，如有疑å•è«‹å°‹ +求建è°ã€‚ + +å°æ示：如果人們在æ¯å€‹é–‹ç™¼é€±æœŸä¸å®šæœŸçµ¦å‡ºä¸»ç·šé 發佈（å³v5.15-rc1或-rc3）以供 +測試，則å¯ä»¥é¿å…這種情æ³ã€‚爲了更好地解釋，å¯ä»¥è¨æƒ³ä¸€å€‹åœ¨Linux v5.14å’Œv5.15-rc1 +之間集æˆçš„更改，該更改導致了迴æ¸ï¼Œä½†åŒæ™‚是應用於5.15-rc1的其他改進的強ä¾è³´ã€‚ +如果有人在5.15發佈之å‰å°±ç™¼ç¾ä¸¦å ±å‘Šäº†é€™å€‹å•é¡Œï¼Œé‚£éº¼æ‰€æœ‰æ›´æ”¹éƒ½å¯ä»¥ç›´æŽ¥æ’¤éŠ·ï¼Œå¾ž +而解決迴æ¸å•é¡Œã€‚而就在幾天或幾周後，æ¤è§£æ±ºæ–¹æ¡ˆè®Šæˆäº†ä¸å¯èƒ½ï¼Œå› 爲一些軟件å¯èƒ½ +已經開始ä¾è³´æ–¼å¾ŒçºŒæ›´æ”¹ä¹‹ä¸€ï¼šæ’¤éŠ·æ‰€æœ‰æ›´æ”¹å°‡å°Žè‡´ä¸Šè¿°ç”¨æˆ¶è»Ÿä»¶å‡ºç¾è¿´æ¸ï¼Œé€™æ˜¯ä¸å¯ +接å—的。 + +若我所ä¾è³´çš„功能在數月å‰è¢«ç§»é™¤äº†ï¼Œæ˜¯è¿´æ¸å—Žï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但如å‰ç¯€æ‰€è¿°ï¼Œé€šå¸¸å¾ˆé›£ä¿®å¾©æ¤é¡žè¿´æ¸ã€‚å› æ¤éœ€è¦é€æ¡ˆè™•ç†ã€‚這也是定期測試主 +ç·šé 發佈å°æ‰€æœ‰äººæœ‰å¥½è™•çš„å¦ä¸€å€‹åŽŸå› 。 + +如果我似乎是唯一å—影響的人，是å¦ä»é©ç”¨â€œç„¡è¿´æ¸â€è¦å‰‡ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +é©ç”¨ï¼Œä½†åƒ…é™æ–¼å¯¦éš›ä½¿ç”¨ï¼šLinuxé–‹ç™¼äººå“¡å¸Œæœ›èƒ½å¤ è‡ªç”±åœ°å–消那些åªèƒ½åœ¨é–£æ¨“å’Œåšç‰© +館ä¸æ‰¾åˆ°çš„硬件的支æŒã€‚ + +請注æ„，有時爲了å–得進展，ä¸å¾—ä¸å‡ºç¾è¿´æ¸â€”—後者也是防æ¢Linuxåœæ»¯ä¸å‰æ‰€å¿…需 +çš„ã€‚å› æ¤å¦‚果迴æ¸æ‰€å½±éŸ¿çš„用戶很少，那麼爲了他們和其他人更大的利益，還是讓事情 +éŽåŽ»å§ã€‚尤其是å˜åœ¨æŸç¨®è¦é¿è¿´æ¸çš„簡單方法，例如更新一些軟件或者使用專門爲æ¤ç›® +çš„å‰µå»ºçš„å…§æ ¸åƒæ•¸ã€‚ + +è¿´æ¸è¦å‰‡æ˜¯å¦ä¹Ÿé©ç”¨æ–¼staging樹ä¸çš„代碼？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ä¸ï¼Œåƒè¦‹ `é©ç”¨æ–¼æ‰€æœ‰staging代碼é…ç½®é¸é …的幫助文本 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/Kconfig>`_ ， +其早已è²æ˜Ž:: + + 請注æ„：這些驅動æ£åœ¨ç©æ¥µé–‹ç™¼ä¸ï¼Œå¯èƒ½ç„¡æ³•æ£å¸¸å·¥ä½œï¼Œä¸¦å¯èƒ½åŒ…å«æœƒåœ¨ä¸ä¹…çš„ + 將來發生變化的用戶接å£ã€‚ + +雖然stagingé–‹ç™¼äººå“¡é€šå¸¸å …æŒâ€œç„¡è¿´æ¸â€çš„原則，但有時爲了å–得進展也會é•èƒŒå®ƒã€‚這就 +是爲什麼當staging樹的WiFi驅動被基本推倒é‡ä¾†æ™‚，有些用戶ä¸å¾—ä¸è™•ç†è¿´æ¸ï¼ˆé€šå¸¸å¯ +以忽略）。 + +çˆ²ä»€éº¼è¼ƒæ–°ç‰ˆæœ¬å¿…é ˆâ€œä½¿ç”¨ç›¸ä¼¼é…置編è¯â€ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å› çˆ²Linuxå…§æ ¸é–‹ç™¼äººå“¡æœ‰æ™‚æœƒé›†æˆå·²çŸ¥çš„會導致迴æ¸çš„變更，但使它們æˆçˆ²å¯é¸çš„，並 +åœ¨å…§æ ¸çš„é»˜èªé…置下ç¦ç”¨å®ƒå€‘。這一技巧å…許進æ¥ï¼Œå¦å‰‡â€œç„¡è¿´æ¸â€è¦å‰‡å°‡å°Žè‡´åœæ»¯ã€‚ + +例如，試想一個新的å¯ä»¥é˜»æ¢æƒ¡æ„軟件濫用æŸå€‹å…§æ ¸çš„接å£çš„安全特性，åŒæ™‚åˆéœ€è¦æ»¿è¶³ +å¦ä¸€å€‹å¾ˆç½•è¦‹çš„應用程åºã€‚上述的方法å¯ä½¿å…©æ–¹éƒ½æ»¿æ„：使用這些應用程åºçš„人å¯ä»¥é—œé–‰ +新的安全功能，而其他ä¸æœƒé‡åˆ°éº»ç…©çš„人å¯ä»¥å•“用它。 + +å¦‚ä½•å‰µå»ºèˆ‡èˆŠå…§æ ¸ç›¸ä¼¼çš„é…置？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ç”¨ä¸€å€‹å·²çŸ¥è‰¯å¥½çš„å…§æ ¸å•“å‹•æ©Ÿå™¨ï¼Œä¸¦ç”¨ ``make olddefconfig`` é…置新版的Linux。這 +æœƒè®“å…§æ ¸çš„æ§‹å»ºè…³æœ¬å¾žæ£åœ¨é‹è¡Œçš„å…§æ ¸ä¸æ‘˜éŒ„é…置文件（“.configâ€æ–‡ä»¶ï¼‰ï¼Œä½œçˆ²å³å°‡ç·¨ +è¯çš„新版本的基礎é…置；åŒæ™‚將所有新的é…ç½®é¸é …è¨çˆ²é»˜èªå€¼ï¼Œä»¥ç¦ç”¨å¯èƒ½å°Žè‡´è¿´æ¸çš„ +新功能。 + +å¦‚ä½•å ±å‘Šåœ¨é ç·¨è¯çš„æ™®é€šå…§æ ¸ä¸ç™¼ç¾çš„è¿´æ¸ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +您需è¦ç¢ºä¿æ–°çš„å…§æ ¸æ˜¯ç”¨èˆ‡èˆŠç‰ˆç›¸ä¼¼çš„é…置編è¯ï¼ˆè¦‹ä¸Šæ–‡ï¼‰ï¼Œå› çˆ²é‚£äº›æ§‹å»ºå®ƒå€‘çš„äººå¯ +èƒ½å•“ç”¨äº†ä¸€äº›å·²çŸ¥çš„èˆ‡æ–°å…§æ ¸ä¸å…¼å®¹çš„特性。如有疑å•ï¼Œè«‹å‘å…§æ ¸çš„æä¾›è€…å ±å‘Šå•é¡Œä¸¦ +尋求建è°ã€‚ + + +用“regzbotâ€è¿½è¹¤è¿´æ¸çš„æ›´å¤šä¿¡æ¯ +----------------------------- + +什麼是迴æ¸è¿½è¹¤ï¼Ÿçˆ²å•¥æˆ‘需è¦é—œå¿ƒå®ƒï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +åƒâ€œç„¡è¿´æ¸â€é€™æ¨£çš„è¦å‰‡éœ€è¦æœ‰äººä¾†ç¢ºä¿å®ƒå€‘被éµå®ˆï¼Œå¦å‰‡æœƒè¢«æœ‰æ„/ç„¡æ„æ‰“ç ´ã€‚æ·å²è‰ +明çžé€™ä¸€é»žå°æ–¼Linuxå…§æ ¸é–‹ç™¼ä¹Ÿé©ç”¨ã€‚這就是爲什麼Linuxå…§æ ¸çš„è¿´æ¸è·Ÿè¹¤è€…Thorsten +Leemhuis，，和å¦ä¸€äº›äººç›¡åŠ›é—œæ³¨æ‰€æœ‰çš„è¿´æ¸ç›´åˆ°ä»–們解決。他們從未爲æ¤ç²å¾—å ±é…¬ï¼Œ +å› æ¤é€™é …工作是在盡最大努力的基礎上完æˆçš„。 + +爲什麼/如何使用機器人追蹤Linuxå…§æ ¸è¿´æ¸ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +由於Linuxå…§æ ¸é–‹ç™¼éŽç¨‹çš„分佈å¼å’Œé¬†æ•£çµæ§‹ï¼Œå®Œå…¨æ‰‹å‹•è·Ÿè¹¤è¿´æ¸å·²ç¶“被è‰æ˜Žæ˜¯ç›¸ç•¶å›°é›£ +çš„ã€‚å› æ¤Linuxå…§æ ¸çš„è¿´æ¸è·Ÿè¹¤è€…開發了regzbotä¾†ä¿ƒé€²é€™é …å·¥ä½œï¼Œå…¶é•·æœŸç›®æ¨™æ˜¯å„˜å¯èƒ½çˆ² +所有相關人員自動化迴æ¸è·Ÿè¹¤ã€‚ + +Regzbot通éŽç›£è¦–跟蹤的迴æ¸å ±å‘Šçš„回覆來工作。æ¤å¤–，它還查找用“Link:â€æ¨™ç±¤å¼•ç”¨é€™ +äº›å ±å‘Šçš„è£œä¸ï¼›å°é€™äº›è£œä¸çš„回覆也會被跟蹤。çµåˆé€™äº›æ•¸æ“šï¼Œå¯ä»¥å¾ˆå¥½åœ°çžè§£ç•¶å‰ä¿® +復éŽç¨‹çš„狀態。 + +如何查看regzbot當å‰è¿½è¹¤çš„è¿´æ¸ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +åƒè¦‹ `regzbot在線 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + +何種å•é¡Œå¯ä»¥ç”±regzbot追蹤？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +該機器人åªçˆ²äº†è·Ÿè¹¤è¿´æ¸ï¼Œå› æ¤è«‹ä¸è¦è®“regzbot涉åŠå¸¸è¦å•é¡Œã€‚但是å°æ–¼Linuxå…§æ ¸çš„ +è¿´æ¸è·Ÿè¹¤è€…來說，讓regzbot跟蹤嚴é‡å•é¡Œä¹Ÿå¯ä»¥ï¼Œå¦‚有關掛起ã€æ壞數據或內部錯誤 +（Panicã€Oopsã€BUG（）ã€warningâ€¦ï¼‰çš„å ±å‘Šã€‚ + +如何修改被追蹤迴æ¸çš„相關信æ¯ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +åœ¨ç›´æŽ¥æˆ–é–“æŽ¥å›žå¾©å ±å‘Šéƒµä»¶æ™‚ä½¿ç”¨â€œregzbot命令â€å³å¯ã€‚最簡單的方法是：在“已發é€â€æ–‡ +件夾或郵件列表å˜æª”ä¸æ‰¾åˆ°å ±å‘Šï¼Œç„¶å¾Œä½¿ç”¨éƒµä»¶å®¢æˆ¶ç«¯çš„“全部回覆â€åŠŸèƒ½å°å…¶é€²è¡Œå›žè¦†ã€‚ +在該郵件ä¸çš„ç¨ç«‹æ®µè½ä¸å¯ä½¿ç”¨ä»¥ä¸‹å‘½ä»¤ä¹‹ä¸€ï¼ˆå³ä½¿ç”¨ç©ºè¡Œå°‡é€™äº›å‘½ä»¤ä¸çš„一個或多個與 +其餘郵件文本分隔開）。 + + * æ›´æ–°è¿´æ¸å¼•å…¥èµ·é»žï¼Œä¾‹å¦‚在執行二分之後:: + + #regzbot introduced: 1f2e3d4c5d + + * è¨ç½®æˆ–更新標題:: + + #regzbot title: foo + + * 監視討論或bugzilla.kernel.org上有關討論或修復的工單:: + + #regzbot monitor: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + #regzbot monitor: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 標記一個有更多相關細節的地方，例如有關但主題ä¸åŒçš„郵件列表帖å或缺陷追蹤器ä¸çš„工單:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 標記迴æ¸å·²å¤±æ•ˆ:: + + #regzbot invalid: wasn't a regression, problem has always existed + +Regzbot還支æŒå…¶ä»–一些主è¦ç”±é–‹ç™¼äººå“¡æˆ–è¿´æ¸è¿½è¹¤äººå“¡ä½¿ç”¨çš„命令。命令的更多細節請 +åƒè€ƒ `å…¥é–€æŒ‡å— <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ +å’Œ `åƒè€ƒæ‰‹å†Š <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ 。 + +.. + æ£æ–‡çµæŸ +.. + 如本文件開é 所述，本文以GPL-2.0+或CC-BY-4.0許å¯ç™¼è¡Œã€‚如您想僅在CC-BY-4.0許 + å¯ä¸‹é‡åˆ†ç™¼æœ¬æ–‡ï¼Œè«‹ç”¨â€œLinuxå…§æ ¸é–‹ç™¼è€…â€ä½œçˆ²ä½œè€…，並用如下éˆæŽ¥ä½œçˆ²ä¾†æºï¼š + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst +.. + 注æ„：本RST文件內容åªæœ‰åœ¨ä¾†è‡ªLinuxå…§æ ¸æºä»£ç¢¼æ™‚是使用CC-BY-4.0許å¯çš„ï¼Œå› çˆ²ç¶“ + éŽè™•ç†çš„ç‰ˆæœ¬ï¼ˆå¦‚ç¶“å…§æ ¸çš„æ§‹å»ºç³»çµ±ï¼‰å¯èƒ½åŒ…å«ä¾†è‡ªä½¿ç”¨æ›´åš´æ ¼è¨±å¯è‰çš„文件的內容。 + diff --git a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst index 65c8dd24c96d..c0e9fc247695 100644 --- a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst +++ b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst @@ -19,17 +19,17 @@ Linuxå…§æ ¸é–‹ç™¼äººå“¡éžå¸¸é‡è¦–å®‰å…¨æ€§ã€‚å› æ¤æˆ‘們想知é“ä½•æ™‚ç™¼ç¾ ----- å¯ä»¥é€šéŽé›»å郵件<security@kernel.org>è¯ç¹«Linuxå…§æ ¸å®‰å…¨åœ˜éšŠã€‚é€™æ˜¯ä¸€å€‹å®‰å…¨äººå“¡ -çš„ç§æœ‰åˆ—表，他們將幫助驗è‰éŒ¯èª¤å ±å‘Šä¸¦é–‹ç™¼å’Œç™¼å¸ƒä¿®å¾©ç¨‹åºã€‚如果您已經有了一個 +çš„ç§æœ‰åˆ—表，他們將幫助驗è‰éŒ¯èª¤å ±å‘Šä¸¦é–‹ç™¼å’Œç™¼ä½ˆä¿®å¾©ç¨‹åºã€‚如果您已經有了一個 修復，請將其包å«åœ¨æ‚¨çš„å ±å‘Šä¸ï¼Œé€™æ¨£å¯ä»¥å¤§å¤§åŠ 快進程。安全團隊å¯èƒ½æœƒå¾žå€åŸŸç¶è· -人員那裡ç²å¾—é¡å¤–的幫助，以ç†è§£å’Œä¿®å¾©å®‰å…¨æ¼æ´žã€‚ +人員那è£ç²å¾—é¡å¤–的幫助，以ç†è§£å’Œä¿®å¾©å®‰å…¨æ¼æ´žã€‚ 與任何缺陷一樣，æ供的信æ¯è¶Šå¤šï¼Œè¨ºæ–·å’Œä¿®å¾©å°±è¶Šå®¹æ˜“。如果您ä¸æ¸…楚哪些信æ¯æœ‰ç”¨ï¼Œ -請查看「Documentation/translations/zh_TW/admin-guide/reporting-issues.rstã€ä¸ +請查看“Documentation/translations/zh_CN/admin-guide/reporting-issues.rstâ€ä¸ 概述的æ¥é©Ÿã€‚任何利用æ¼æ´žçš„攻擊代碼都éžå¸¸æœ‰ç”¨ï¼Œæœªç¶“å ±å‘Šè€…åŒæ„ä¸æœƒå°å¤–發布，除 éžå·²ç¶“公開。 -請儘å¯èƒ½ç™¼é€ç„¡é™„件的純文本電å郵件。如果所有的細節都è—åœ¨é™„ä»¶é‡Œï¼Œé‚£éº¼å°±å¾ˆé›£å° -一個複雜的å•é¡Œé€²è¡Œä¸Šä¸‹æ–‡å¼•ç”¨çš„討論。把它想åƒæˆä¸€å€‹ +請儘å¯èƒ½ç™¼é€ç„¡é™„件的純文本電å郵件。如果所有的細節都è—在附件è£ï¼Œé‚£éº¼å°±å¾ˆé›£å° +一個複雜的å•é¡Œé€²è¡Œä¸Šä¸‹æ–‡å¼•ç”¨çš„討論。把它想象æˆä¸€å€‹ :doc:`常è¦çš„補ä¸æ交 <../process/submitting-patches>` （å³ä½¿ä½ 還沒有補ä¸ï¼‰ï¼š æè¿°å•é¡Œå’Œå½±éŸ¿ï¼Œåˆ—出復ç¾æ¥é©Ÿï¼Œç„¶å¾Œçµ¦å‡ºä¸€å€‹å»ºè°çš„解決方案，所有這些都是純文本的。 @@ -38,15 +38,15 @@ Linuxå…§æ ¸é–‹ç™¼äººå“¡éžå¸¸é‡è¦–å®‰å…¨æ€§ã€‚å› æ¤æˆ‘們想知é“ä½•æ™‚ç™¼ç¾ å®‰å…¨åˆ—è¡¨ä¸æ˜¯å…¬é–‹æ¸ é“。爲æ¤ï¼Œè«‹åƒè¦‹ä¸‹é¢çš„å”作。 -一旦開發出了å¥å£¯çš„補ä¸ï¼Œç™¼å¸ƒéŽç¨‹å°±é–‹å§‹äº†ã€‚å°å…¬é–‹çš„缺陷的修復會立å³ç™¼å¸ƒã€‚ +一旦開發出了å¥å£¯çš„補ä¸ï¼Œç™¼ä½ˆéŽç¨‹å°±é–‹å§‹äº†ã€‚å°å…¬é–‹çš„缺陷的修復會立å³ç™¼ä½ˆã€‚ -儘管我們傾å‘於在未公開缺陷的修復å¯ç”¨æ™‚å³ç™¼å¸ƒè£œä¸ï¼Œä½†æ‡‰å ±å‘Šè€…或å—影響方的請求， -這å¯èƒ½æœƒè¢«æŽ¨é²åˆ°ç™¼å¸ƒéŽç¨‹é–‹å§‹å¾Œçš„7æ—¥å…§ï¼Œå¦‚æžœæ ¹æ“šç¼ºé™·çš„åš´é‡æ€§éœ€è¦æ›´å¤šçš„時間， -則å¯é¡å¤–延長到14天。推é²ç™¼å¸ƒä¿®å¾©çš„å”¯ä¸€æœ‰æ•ˆåŽŸå› æ˜¯çˆ²äº†é©æ‡‰QAçš„é‚輯和需è¦ç™¼å¸ƒ +儘管我們傾å‘於在未公開缺陷的修復å¯ç”¨æ™‚å³ç™¼ä½ˆè£œä¸ï¼Œä½†æ‡‰å ±å‘Šè€…或å—影響方的請求， +這å¯èƒ½æœƒè¢«æŽ¨é²åˆ°ç™¼ä½ˆéŽç¨‹é–‹å§‹å¾Œçš„7æ—¥å…§ï¼Œå¦‚æžœæ ¹æ“šç¼ºé™·çš„åš´é‡æ€§éœ€è¦æ›´å¤šçš„時間， +則å¯é¡å¤–延長到14天。推é²ç™¼ä½ˆä¿®å¾©çš„å”¯ä¸€æœ‰æ•ˆåŽŸå› æ˜¯çˆ²äº†é©æ‡‰QAçš„é‚輯和需è¦ç™¼ä½ˆ å”調的大è¦æ¨¡éƒ¨ç½²ã€‚ 雖然å¯èƒ½èˆ‡å—信任的個人共享å—é™ä¿¡æ¯ä»¥é–‹ç™¼ä¿®å¾©ï¼Œä½†æœªç¶“å ±å‘Šè€…è¨±å¯ï¼Œæ¤é¡žä¿¡æ¯ä¸æœƒ -與修復程åºä¸€èµ·ç™¼å¸ƒæˆ–ç™¼å¸ƒåœ¨ä»»ä½•å…¶ä»–æŠ«éœ²æ¸ é“上。這包括但ä¸é™æ–¼åŽŸå§‹éŒ¯èª¤å ±å‘Šå’Œ +與修復程åºä¸€èµ·ç™¼ä½ˆæˆ–ç™¼ä½ˆåœ¨ä»»ä½•å…¶ä»–æŠ«éœ²æ¸ é“上。這包括但ä¸é™æ–¼åŽŸå§‹éŒ¯èª¤å ±å‘Šå’Œ 後續討論（如有）ã€æ¼æ´žã€CVEä¿¡æ¯æˆ–å ±å‘Šè€…çš„èº«ä»½ã€‚ æ›å¥è©±èªªï¼Œæˆ‘們唯一感興趣的是修復缺陷。æ交給安全列表的所有其他資料以åŠå°å ±å‘Š @@ -57,10 +57,10 @@ Linuxå…§æ ¸é–‹ç™¼äººå“¡éžå¸¸é‡è¦–å®‰å…¨æ€§ã€‚å› æ¤æˆ‘們想知é“ä½•æ™‚ç™¼ç¾ å°æ•æ„Ÿç¼ºé™·ï¼ˆä¾‹å¦‚那些å¯èƒ½å°Žè‡´æ¬Šé™æå‡çš„缺陷）的修復å¯èƒ½éœ€è¦èˆ‡ç§æœ‰éƒµä»¶åˆ—表 <linux-distros@vs.openwall.org>進行å”調，以便分發供應商åšå¥½æº–備，在公開披露 -上游補ä¸æ™‚ç™¼å¸ƒä¸€å€‹å·²ä¿®å¾©çš„å…§æ ¸ã€‚ç™¼è¡Œç‰ˆå°‡éœ€è¦ä¸€äº›æ™‚間來測試建è°çš„補ä¸ï¼Œé€šå¸¸ -會è¦æ±‚至少幾天的é™åˆ¶ï¼Œè€Œä¾›æ‡‰å•†æ›´æ–°ç™¼å¸ƒæ›´å‚¾å‘於周二至周四。若åˆé©ï¼Œå®‰å…¨åœ˜éšŠ +上游補ä¸æ™‚ç™¼ä½ˆä¸€å€‹å·²ä¿®å¾©çš„å…§æ ¸ã€‚ç™¼è¡Œç‰ˆå°‡éœ€è¦ä¸€äº›æ™‚間來測試建è°çš„補ä¸ï¼Œé€šå¸¸ +會è¦æ±‚至少幾天的é™åˆ¶ï¼Œè€Œä¾›æ‡‰å•†æ›´æ–°ç™¼å¸ƒæ›´å‚¾å‘於週二至週四。若åˆé©ï¼Œå®‰å…¨åœ˜éšŠ å¯ä»¥å”助這種å”èª¿ï¼Œæˆ–è€…å ±å‘Šè€…å¯ä»¥å¾žä¸€é–‹å§‹å°±åŒ…括linux發行版。在這種情æ³ä¸‹ï¼Œè«‹ -記ä½åœ¨é›»å郵件主題行å‰é¢åŠ 上「[vs]ã€ï¼Œå¦‚linux發行版wikiä¸æ‰€è¿°ï¼š +記ä½åœ¨é›»å郵件主題行å‰é¢åŠ 上“[vs]â€ï¼Œå¦‚linux發行版wikiä¸æ‰€è¿°ï¼š <http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。 CVEåˆ†é… diff --git a/Documentation/translations/zh_TW/admin-guide/sysrq.rst b/Documentation/translations/zh_TW/admin-guide/sysrq.rst new file mode 100644 index 000000000000..4a08db00a495 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/sysrq.rst @@ -0,0 +1,281 @@ +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/sysrq.rst + +:ç¿»è¯: + + 黃è»è¯ Junhua Huang <huang.junhua@zte.com.cn> + +:æ ¡è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_admin-guide_sysrq: + +Linux é”法系統請求éµé§å®¢ +======================== + +é‡å° sysrq.c 的文檔說明 + +什麼是é”法 SysRq éµï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~ + +å®ƒæ˜¯ä¸€å€‹ä½ å¯ä»¥è¼¸å…¥çš„具有é”法般的組åˆéµã€‚ +ç„¡è«–å…§æ ¸åœ¨åšä»€éº¼ï¼Œå…§æ ¸éƒ½æœƒéŸ¿æ‡‰ SysRq éµçš„輸入，除éžå…§æ ¸å®Œå…¨å¡æ»ã€‚ + +如何使能é”法 SysRq éµï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~ + +在é…ç½®å…§æ ¸æ™‚ï¼Œæˆ‘å€‘éœ€è¦è¨ç½® 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' 爲 'Y'。 +當é‹è¡Œä¸€å€‹ç·¨è¯é€² sysrq åŠŸèƒ½çš„å…§æ ¸æ™‚ï¼Œ/proc/sys/kernel/sysrq 控制ç€è¢« +SysRq éµèª¿ç”¨çš„功能許å¯ã€‚這個文件的默èªå€¼ç”± CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE +é…置符號è¨å®šï¼Œæ–‡ä»¶æœ¬èº«é»˜èªè¨ç½®çˆ² 1。以下是 /proc/sys/kernel/sysrq ä¸å¯èƒ½çš„ +值列表： + + - 0 - 完全ä¸ä½¿èƒ½ SysRq éµ + - 1 - 使能 SysRq éµçš„全部功能 + - >1 - å°æ–¼å…許的 SysRq éµåŠŸèƒ½çš„比特掩碼（åƒè¦‹ä¸‹é¢æ›´è©³ç´°çš„功能æ述）:: + + 2 = 0x2 - 使能å°æŽ§åˆ¶æª¯æ—¥èªŒè¨˜éŒ„級別的控制 + 4 = 0x4 - 使能å°éµç›¤çš„控制 (SAK, unraw) + 8 = 0x8 - 使能å°é€²ç¨‹çš„èª¿è©¦å°Žå‡ºç‰ + 16 = 0x10 - 使能åŒæ¥å‘½ä»¤ + 32 = 0x20 - 使能é‡æ–°æŽ›è¼‰åªè®€ + 64 = 0x40 - 使能å°é€²ç¨‹çš„信號æ“作 (term, kill, oom-kill) + 128 = 0x80 - å…許é‡å•“ã€æ–·é›» + 256 = 0x100 - å…許讓所有實時任務變普通任務 + +ä½ å¯ä»¥é€šéŽå¦‚下命令把值è¨ç½®åˆ°é€™å€‹æ–‡ä»¶ä¸:: + + echo "number" >/proc/sys/kernel/sysrq + +這è£è¢«å¯«å…¥çš„ number å¯ä»¥æ˜¯ 10 é€²åˆ¶æ•¸ï¼Œæˆ–è€…æ˜¯å¸¶ç€ 0x å‰ç¶´çš„ 16 進制數。 +CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE å¿…é ˆæ˜¯ä»¥ 16 進制數寫入。 + +注æ„，``/proc/sys/kernel/sysrq`` 的值隻影響通éŽéµç›¤è§¸ç™¼ SySRq 的調用，å°æ–¼ +é€šéŽ ``/proc/sysrq-trigger`` 的任何æ“作調用都是å…許的 +（通éŽå…·æœ‰ç³»çµ±æ¬Šé™çš„用戶）。 + +如何使用é”法 SysRq éµï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~ + +在 x86 架構上 + ä½ å¯ä»¥æŒ‰ä¸‹éµç›¤çµ„åˆéµ :kbd:`ALT-SysRq-<command key>`。 + + .. note:: + 一些éµç›¤å¯èƒ½æ²’æœ‰æ¨™è˜ 'SySRq' éµã€‚'SySRq' éµä¹Ÿè¢«ç•¶åš 'Print Screen'éµã€‚ + åŒæ™‚有些éµç›¤ç„¡æ³•è™•ç†åŒæ™‚按下這麼多éµï¼Œå› æ¤ä½ å¯ä»¥å…ˆæŒ‰ä¸‹éµç›¤ :kbd:`Alt` éµï¼Œ + 然後按下éµç›¤ :kbd:`SysRq` éµï¼Œå†é‡‹æ”¾éµç›¤ :kbd:`SysRq` éµï¼Œä¹‹å¾ŒæŒ‰ä¸‹éµç›¤ä¸Šå‘½ä»¤éµ + :kbd:`<command key>`，最後釋放所有éµã€‚ + +在 SPARC 架構上 + ä½ å¯ä»¥æŒ‰ä¸‹éµç›¤çµ„åˆéµ :kbd:`ALT-STOP-<command key>` 。 + +在串行控制檯（åªé‡å° PC 類型的標準串å£ï¼‰ + ä½ å¯ä»¥ç™¼ä¸€å€‹ ``BREAK`` ，然後在 5 秒內發é€ä¸€å€‹å‘½ä»¤éµï¼Œ + ç™¼é€ ``BREAK`` 兩次將被翻è¯çˆ²ä¸€å€‹æ£å¸¸çš„ BREAK æ“作。 + +在 PowerPC 架構上 + 按下éµç›¤çµ„åˆéµ :kbd:`ALT - Print Screen` （或者 :kbd:`F13`） - :kbd:`<命令éµ>` 。 + :kbd:`Print Screen` （或者 :kbd:`F13`） - :kbd:`<命令éµ>` 或許也能實ç¾ã€‚ + +在其他架構上 + å¦‚æžœä½ çŸ¥é“其他架構的組åˆéµï¼Œè«‹å‘Šè¨´æˆ‘，我å¯ä»¥æŠŠå®ƒå€‘æ·»åŠ åˆ°é€™éƒ¨åˆ†ã€‚ + +在所有架構上 + 寫一個å—符到 /proc/sysrq-trigger 文件，例如:: + + echo t > /proc/sysrq-trigger + +é€™å€‹å‘½ä»¤éµ :kbd:`<command key>` 是å€åˆ†å¤§å°å¯«çš„。 + +什麼是命令éµï¼Ÿ +~~~~~~~~~~~~~~ + +=========== ================================================================ +å‘½ä»¤éµ åŠŸèƒ½ +=========== ================================================================ +``b`` 將立å³é‡å•“系統，ä¸æœƒåŒæ¥æˆ–者å¸è¼‰ç£ç›¤ã€‚ + +``c`` 將執行系統 crash，如果é…置了系統 crashdump，將執行 crashdump。 + +``d`` 顯示所有æŒæœ‰çš„鎖。 + +``e`` ç™¼é€ SIGTERM 信號給所有進程，除了 init 進程。 + +``f`` 將調用 oom killer 殺掉一個éŽåº¦ä½”用內å˜çš„進程，如果什麼任務都沒殺， + 也ä¸æœƒ panic。 + +``g`` kgdb ä½¿ç”¨ï¼ˆå…§æ ¸èª¿è©¦å™¨ï¼‰ã€‚ + +``h`` 將會顯示幫助。（實際上除了這è£åˆ—舉的éµï¼Œå…¶ä»–的都將顯示幫助， + 但是 ``h`` 容易記ä½ï¼‰:-) + +``i`` ç™¼é€ SIGKILL 給所有進程，除了 init 進程。 + +``j`` 強制性的 “解å‡å®ƒâ€ - 用於被 FIFREEZE ioctl æ“作å‡ä½çš„文件系統。 + +``k`` 安全訪å•ç¥•é‘°(SAK)殺掉在當å‰è™›æ“¬æŽ§åˆ¶æª¯çš„所有程åºï¼Œæ³¨æ„：åƒè€ƒ + ä¸‹é¢ SAK 節é‡è¦è«–述。 + +``l`` 顯示所有活動 cpu 的棧回溯。 + +``m`` 將導出當å‰å…§å˜ä¿¡æ¯åˆ°ä½ 的控制檯。 + +``n`` 用於使所有實時任務變æˆæ™®é€šä»»å‹™ã€‚ + +``o`` 將關閉系統（如果é…置和支æŒçš„話）。 + +``p`` 將導出當å‰å¯„å˜å™¨å’Œæ¨™èªŒä½åˆ°æŽ§åˆ¶æª¯ã€‚ + +``q`` 將導出æ¯å€‹ cpu 上所有已è£å‚™çš„高精度定時器（ä¸æ˜¯å®Œæ•´çš„ + time_list 文件顯示的 timers）和所有時é˜äº‹ä»¶è¨å‚™çš„詳細信æ¯ã€‚ + +``r`` 關閉éµç›¤çš„原始模å¼ï¼Œè¨ç½®çˆ²è½‰æ›æ¨¡å¼ã€‚ + +``s`` 將嘗試åŒæ¥æ‰€æœ‰çš„已掛載文件系統。 + +``t`` 將導出當å‰æ‰€æœ‰ä»»å‹™åˆ—表和它們的信æ¯åˆ°æŽ§åˆ¶æª¯ã€‚ + +``u`` 將嘗試é‡æ–°æŽ›è¼‰å·²æŽ›è¼‰æ–‡ä»¶ç³»çµ±çˆ²åªè®€ã€‚ + +``v`` 強制æ¢å¾©å¹€ç·©å˜æŽ§åˆ¶æª¯ã€‚ +``v`` 觸發 ETM ç·©å˜å°Žå‡º [ARM 架構特有] + +``w`` 導出處於ä¸å¯ä¸æ–·ç‹€æ…‹ï¼ˆé˜»å¡žï¼‰çš„任務。 + +``x`` 在 ppc/powerpc 架構上用於 xmon 接å£ã€‚ + 在 sparc64 架構上用於顯示全局的 PMU（性能監控單元）寄å˜å™¨ã€‚ + 在 MIPS 架構上導出所有的 tlb æ¢ç›®ã€‚ + +``y`` 顯示全局 cpu 寄å˜å™¨ [SPARC-64 架構特有] + +``z`` 導出 ftrace ç·©å˜ä¿¡æ¯ + +``0``-``9`` è¨ç½®æŽ§åˆ¶æª¯æ—¥èªŒç´šåˆ¥ï¼Œè©²ç´šåˆ¥æŽ§åˆ¶ä»€éº¼æ¨£çš„å…§æ ¸ä¿¡æ¯å°‡è¢«æ‰“å°åˆ°ä½ çš„ + 控制檯。（比如 ``0`` ，將使得åªæœ‰ç·Šæ€¥ä¿¡æ¯ï¼Œåƒ PANICs or OOPSes + æ‰èƒ½åˆ°ä½ 的控制檯。） +=========== ================================================================ + +好了，我能用他們åšä»€éº¼å‘¢ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +å—¯ï¼Œç•¶ä½ çš„ X æœå‹™ç«¯æˆ–者 svgalib 程åºå´©æ½°ï¼Œunraw(r) éžåŽŸå§‹æ¨¡å¼å‘½ä»¤éµæ˜¯éžå¸¸ +方便的。 + +sak(k)（安全訪å•ç¥•é‘°ï¼‰åœ¨ä½ 嘗試登陸的åŒæ™‚，åˆæƒ³ç¢ºä¿ç•¶å‰æŽ§åˆ¶æª¯æ²’有å¯ä»¥ç²å–ä½ çš„ +密碼的特洛伊木馬程åºé‹è¡Œæ™‚是有用的。它會殺掉給定控制檯的所有程åºï¼Œé€™æ¨£ä½ +å°±å¯ä»¥ç¢ºèªç•¶å‰çš„登陸æ示程åºæ˜¯å¯¦éš›ä¾†è‡ª init 進程的程åºï¼Œè€Œä¸æ˜¯æŸäº›ç‰¹æ´›ä¼Š +木馬程åºã€‚ + +.. important:: + + 在其實際的形å¼ä¸ï¼Œåœ¨å…¼å®¹ C2 安全標準的系統上，它ä¸æ˜¯ä¸€å€‹çœŸæ£çš„ SAK， + 它也ä¸æ‡‰è©²èª¤èªçˆ²æ¤ã€‚ + +似乎其他人發ç¾å…¶å¯ä»¥ä½œçˆ²ï¼ˆç³»çµ±çµ‚端è¯æ©Ÿéµï¼‰ç•¶ä½ 想退出一個程åºï¼Œ +åŒæ™‚ä¸æœƒè®“ä½ åˆ‡æ›æŽ§åˆ¶æª¯çš„方法。（比如，X æœå‹™ç«¯æˆ–者 svgalib 程åºï¼‰ + +``reboot(b)`` æ˜¯å€‹å¥½æ–¹æ³•ï¼Œç•¶ä½ ä¸èƒ½é—œé–‰æ©Ÿå™¨æ™‚，它ç‰åŒæ–¼æŒ‰ä¸‹"復ä½"按鈕。 + +``crash(c)`` å¯ä»¥ç”¨æ–¼æ‰‹å‹•è§¸ç™¼ä¸€å€‹ crashdump，當系統å¡ä½æ™‚。 +注æ„當 crashdump 機制ä¸å¯ç”¨æ™‚，這個åªæ˜¯è§¸ç™¼ä¸€å€‹å…§æ ¸ crash。 + +``sync(s)`` 在拔掉å¯ç§»å‹•ä»‹è³ªä¹‹å‰ï¼Œæˆ–者在使用ä¸æ供優雅關機的 +æ•‘æ´ shell 之後很方便 -- 它將確ä¿ä½ 的數據被安全地寫入ç£ç›¤ã€‚注æ„ï¼Œåœ¨ä½ çœ‹åˆ° +å±å¹•ä¸Šå‡ºç¾ "OK" å’Œ "Done" 之å‰ï¼ŒåŒæ¥é‚„沒有發生。 + +``umount(u)`` å¯ä»¥ç”¨ä¾†æ¨™è¨˜æ–‡ä»¶ç³»çµ±æ£å¸¸å¸è¼‰ï¼Œå¾žæ£åœ¨é‹è¡Œçš„系統角度來看，它們將 +被é‡æ–°æŽ›è¼‰çˆ²åªè®€ã€‚這個é‡æ–°æŽ›è¼‰å‹•ä½œç›´åˆ°ä½ 看到 "OK" å’Œ "Done" ä¿¡æ¯å‡ºç¾åœ¨å±å¹•ä¸Š +纔算完æˆã€‚ + +日誌級別 ``0`` - ``9`` ç”¨æ–¼ç•¶ä½ çš„æŽ§åˆ¶æª¯è¢«å¤§é‡çš„å…§æ ¸ä¿¡æ¯è¡æ“Šï¼Œä½ ä¸æƒ³çœ‹è¦‹çš„時候。 +é¸æ“‡ ``0`` å°‡ç¦æ¢é™¤äº†æœ€ç·Šæ€¥çš„å…§æ ¸ä¿¡æ¯å¤–çš„æ‰€æœ‰çš„å…§æ ¸ä¿¡æ¯è¼¸å‡ºåˆ°æŽ§åˆ¶æª¯ã€‚（但是如果 +syslogd/klogd 進程是é‹è¡Œçš„，它們ä»å°‡è¢«è¨˜éŒ„。） + +``term(e)`` å’Œ ``kill(i)`` ç”¨æ–¼ç•¶ä½ æœ‰äº›æœ‰é»žå¤±æŽ§çš„é€²ç¨‹ï¼Œä½ ç„¡æ³•é€šéŽå…¶ä»–æ–¹å¼æ®ºæŽ‰ +它們的時候，特別是它æ£åœ¨å‰µå»ºå…¶ä»–進程。 + +"just thaw ``it(j)`` " ç”¨æ–¼ç•¶ä½ çš„ç³»çµ±ç”±æ–¼ä¸€å€‹ FIFREEZE ioctl 調用而產生的文件 +系統å‡çµï¼Œè€Œå°Žè‡´çš„ä¸éŸ¿æ‡‰æ™‚。 + +有的時候 SysRq éµåœ¨ä½¿ç”¨å®ƒä¹‹å¾Œï¼Œçœ‹èµ·ä¾†åƒæ˜¯â€œå¡ä½â€äº†ï¼Œæˆ‘能åšäº›ä»€éº¼ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +這也會發生在我這，我發ç¾è¼•æ•²éµç›¤å…©å´çš„ shiftã€alt å’Œ control éµï¼Œç„¶å¾Œå†æ¬¡æ•²æ“Š +一個無效的 SysRq éµåºåˆ—å¯ä»¥è§£æ±ºå•é¡Œã€‚（比如，åƒéµç›¤çµ„åˆéµ :kbd:`alt-sysrq-z` ） +切æ›åˆ°å¦ä¸€å€‹è™›æ“¬æŽ§åˆ¶æª¯ï¼ˆéµç›¤æ“作 :kbd:`ALT+Fn` ），然後å†åˆ‡å›žä¾†æ‡‰è©²ä¹Ÿæœ‰å¹«åŠ©ã€‚ + +我敲擊了 SysRq éµï¼Œä½†åƒæ˜¯ä»€éº¼éƒ½æ²’發生，發生了什麼錯誤？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +有一些éµç›¤å°æ–¼ SysRq éµè¨ç½®äº†ä¸åŒçš„éµå€¼ï¼Œè€Œä¸æ˜¯æå‰å®šç¾©çš„ 99 +(查看在 ``include/uapi/linux/input-event-codes.h`` æ–‡ä»¶ä¸ ``KEY_SYSRQ`` 的定義) +æˆ–è€…å°±æ ¹æœ¬æ²’æœ‰ SysRq éµã€‚åœ¨é€™äº›å ´æ™¯ä¸‹ï¼ŒåŸ·è¡Œ ``showkey -s`` 命令來找到一個åˆé© +的掃æ碼åºåˆ—，然後使用 ``setkeycodes <sequence> 99`` å‘½ä»¤æ˜ å°„é€™å€‹åºåˆ—值到通用 +çš„ SysRq éµç·¨ç¢¼ä¸Šï¼ˆæ¯”如 ``setkeycodes e05b 99`` ）。最好將這個命令放在啓動腳本 +ä¸ã€‚ +å“¦ï¼Œé †ä¾¿èªªä¸€å¥ï¼Œä½ å秒é˜ä¸è¼¸å…¥ä»»ä½•æ±è¥¿å°±å°‡é€€å‡º “showkeyâ€ã€‚ + +æˆ‘æƒ³æ·»åŠ ä¸€å€‹ SysRq éµäº‹ä»¶åˆ°ä¸€å€‹æ¨¡å¡Šä¸ï¼Œå¦‚何去åšå‘¢ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +爲了註冊一個基礎函數到這個表ä¸ï¼Œé¦–å…ˆä½ å¿…é ˆåŒ…å« ``include/linux/sysrq.h`` é +文件，這個é æ–‡ä»¶å®šç¾©äº†ä½ æ‰€éœ€è¦çš„所有æ±è¥¿ã€‚ç„¶å¾Œä½ å¿…é ˆå‰µå»ºä¸€å€‹ ``sysrq_key_op`` +çµæ§‹é«”，然後åˆå§‹åŒ–它，使用如下內容，A） ä½ å°‡ä½¿ç”¨çš„é€™å€‹éµçš„處ç†å‡½æ•¸ï¼Œ B） 一個 +help_msg å—符串，在 SysRq éµæ‰“å°å¹«åŠ©ä¿¡æ¯æ™‚將打å°å‡ºä¾†ï¼ŒC） 一個 action_msg å— +ç¬¦ä¸²ï¼Œå°±åœ¨ä½ çš„è™•ç†å‡½æ•¸èª¿ç”¨å‰æ‰“å°å‡ºä¾†ã€‚ä½ çš„è™•ç†å‡½æ•¸å¿…é ˆç¬¦åˆåœ¨ 'sysrq.h' æ–‡ä»¶ä¸ +的函數原型。 + +在 ``sysrq_key_op`` çµæ§‹é«”è¢«å‰µå»ºå¾Œï¼Œä½ å¯ä»¥èª¿ç”¨å…§æ ¸å‡½æ•¸ +``register_sysrq_key(int key, const struct sysrq_key_op *op_p);``， +該函數在表ä¸çš„ 'key' å°æ‡‰ä½ç½®å…§å®¹æ˜¯ç©ºçš„情æ³ä¸‹ï¼Œå°‡é€šéŽ ``op_p`` 指é‡è¨»å†Šé€™å€‹æ“作 +å‡½æ•¸åˆ°è¡¨ä¸ 'key' å°æ‡‰ä½ç½®ä¸Šã€‚在模塊å¸è¼‰çš„æ™‚å€™ï¼Œä½ å¿…é ˆèª¿ç”¨ +``unregister_sysrq_key(int key, const struct sysrq_key_op *op_p)`` 函數，該函數 +åªæœ‰åœ¨ç•¶å‰è©²éµå°æ‡‰çš„處ç†å‡½æ•¸è¢«è¨»å†Šåˆ°äº† 'key' å°æ‡‰ä½ç½®æ™‚，纔會移除 'op_p' æŒ‡é‡ +å°æ‡‰çš„éµå€¼æ“作函數。這是爲了防æ¢åœ¨ä½ 註冊之後，該ä½ç½®è¢«æ”¹å¯«çš„情æ³ã€‚ + +é”法 SysRq éµç³»çµ±çš„工作原ç†æ˜¯å°‡éµå°æ‡‰æ“作函數註冊到éµçš„æ“作查找表， +該表定義在 'drivers/tty/sysrq.c' 文件ä¸ã€‚ +該éµè¡¨æœ‰è¨±å¤šåœ¨ç·¨è¯æ™‚候就註冊進去的æ“作函數，但是是å¯è®Šçš„。 +並且有兩個函數作爲æ“作該表的接å£è¢«å°Žå‡º:: + + register_sysrq_key å’Œ unregister_sysrq_key. + +當然，永é ä¸è¦åœ¨è¡¨ä¸ç•™ä¸‹ç„¡æ•ˆæŒ‡é‡ï¼Œå³ï¼Œç•¶ä½ 的模塊å˜åœ¨èª¿ç”¨ register_sysrq_key() +函數，它一定è¦èª¿ç”¨ unregister_sysrq_key() 來清除它使用éŽçš„ SysRq éµè¡¨æ¢ç›®ã€‚ +表ä¸çš„空指é‡æ˜¯å®‰å…¨çš„。:) + +如果å°æ–¼æŸç¨®åŽŸå› ，在 handle_sysrq 調用的處ç†å‡½æ•¸ä¸ï¼Œä½ èªçˆ²æœ‰å¿…è¦èª¿ç”¨ +handle_sysrq å‡½æ•¸æ™‚ï¼Œä½ å¿…é ˆæ„è˜åˆ°ç•¶å‰ä½ 處於一個鎖ä¸ï¼ˆä½ åŒæ™‚也處於一箇ä¸æ–·è™•ç† +函數ä¸ï¼Œé€™æ„味ç€ä¸èƒ½ç¡çœ ï¼‰ã€‚æ‰€ä»¥é€™æ™‚ä½ å¿…é ˆä½¿ç”¨ ``__handle_sysrq_nolock`` 替代。 + +當我敲擊一個 SysRq 組åˆéµæ™‚，åªæœ‰æ¨™é¡Œæ‰“å°å‡ºç¾åœ¨æŽ§åˆ¶æª¯ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SysRq éµçš„輸出和所有其他控制檯輸出一樣，å—制於控制檯日誌級別控制。 +這æ„味ç€ï¼Œå¦‚æžœå…§æ ¸ä»¥ç™¼è¡Œç‰ˆå…§æ ¸ä¸å¸¸è¦‹çš„ "quiet" æ–¹å¼å•“動，則輸出å¯èƒ½ä¸æœƒå‡ºç¾åœ¨å¯¦éš› +的控制檯上，å³ä½¿å®ƒæœƒå‡ºç¾åœ¨ dmesg ç·©å˜ä¸ï¼Œä¹Ÿå¯ä»¥é€šéŽ dmesg 命令和 ``/proc/kmsg`` +文件的消費訪å•åˆ°ã€‚作爲一個特例，來自 sysrq 命令的標題行將被傳éžçµ¦æ‰€æœ‰æŽ§åˆ¶æª¯ +使用者，就好åƒç•¶å‰æ—¥èªŒç´šåˆ¥æ˜¯æœ€å¤§çš„一樣。如果åªç™¼å‡ºæ¨™é¡Œé ，則幾乎å¯ä»¥è‚¯å®šå…§æ ¸æ—¥èªŒ +ç´šåˆ¥å¤ªä½Žã€‚å¦‚æžœä½ éœ€è¦æŽ§åˆ¶æª¯ä¸Šçš„è¼¸å‡ºï¼Œé‚£éº¼ä½ å°‡éœ€è¦è‡¨æ™‚æ高控制檯日誌級別，通éŽä½¿ç”¨ +éµç›¤çµ„åˆéµ :kbd:`alt-sysrq-8` 或者:: + + echo 8 > /proc/sysrq-trigger + +åœ¨è§¸ç™¼äº†ä½ æ„Ÿèˆˆè¶£çš„ SysRq éµå‘½ä»¤å¾Œï¼Œè¨˜å¾—æ¢å¾©æ—¥èªŒç´šåˆ¥åˆ°æ£å¸¸æƒ…æ³ã€‚ + +我有很多å•é¡Œæ™‚，å¯ä»¥è«‹æ•™èª°ï¼Ÿ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +è«‹æ•™åœ¨å…§æ ¸éƒµä»¶åˆ—è¡¨ä¸Šçš„äººï¼Œéƒµç®±ï¼š + linux-kernel@vger.kernel.org + +è‡´è¬ +~~~~ + +- Mydraal <vulpyne@vulpyne.net> 撰寫了該文件 +- Adam Sulmicki <adam@cfar.umd.edu> 進行了更新 +- Jeremy M. Dolan <jmd@turbogeek.org> 在 2001/01/28 10:15:59 進行了更新 +- Crutcher Dunnavant <crutcher+kernel@datastacks.com> æ·»åŠ éµè¨»å†Šéƒ¨åˆ† + diff --git a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst index ebe3812ead82..47629f6b05de 100644 --- a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst +++ b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst @@ -9,27 +9,27 @@ å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> 胡皓文 Hu Haowen <src.res.211@gmail.com> -å—æ±™æŸ“çš„å…§æ ¸ +å—æ±¡æŸ“çš„å…§æ ¸ ------------- -當發生一些在ç¨å¾Œèª¿æŸ¥å•é¡Œæ™‚å¯èƒ½ç›¸é—œçš„äº‹ä»¶æ™‚ï¼Œå…§æ ¸æœƒå°‡è‡ªå·±æ¨™è¨˜çˆ²ã€Œå—汙染 -（tainted）ã€çš„。ä¸ç”¨å¤ªéŽæ“”心，大多數情æ³ä¸‹é‹è¡Œå—æ±™æŸ“çš„å…§æ ¸æ²’æœ‰å•é¡Œï¼›é€™äº›ä¿¡æ¯ -主è¦åœ¨æœ‰äººæƒ³èª¿æŸ¥æŸå€‹å•é¡Œæ™‚æ‰æœ‰æ„ç¾©çš„ï¼Œå› çˆ²å•é¡Œçš„真æ£åŽŸå› å¯èƒ½æ˜¯å°Žè‡´å…§æ ¸å—汙染 -的事件。這就是爲什麼來自å—æ±™æŸ“å…§æ ¸çš„ç¼ºé™·å ±å‘Šå¸¸å¸¸è¢«é–‹ç™¼äººå“¡å¿½ç•¥ï¼Œå› æ¤è«‹å˜—試用 -未å—æ±™æŸ“çš„å…§æ ¸é‡ç¾å•é¡Œã€‚ +當發生一些在ç¨å¾Œèª¿æŸ¥å•é¡Œæ™‚å¯èƒ½ç›¸é—œçš„äº‹ä»¶æ™‚ï¼Œå…§æ ¸æœƒå°‡è‡ªå·±æ¨™è¨˜çˆ²â€œå—污染 +（tainted）â€çš„。ä¸ç”¨å¤ªéŽæ“”心，大多數情æ³ä¸‹é‹è¡Œå—æ±¡æŸ“çš„å…§æ ¸æ²’æœ‰å•é¡Œï¼›é€™äº›ä¿¡æ¯ +主è¦åœ¨æœ‰äººæƒ³èª¿æŸ¥æŸå€‹å•é¡Œæ™‚纔有æ„ç¾©çš„ï¼Œå› çˆ²å•é¡Œçš„真æ£åŽŸå› å¯èƒ½æ˜¯å°Žè‡´å…§æ ¸å—污染 +的事件。這就是爲什麼來自å—æ±¡æŸ“å…§æ ¸çš„ç¼ºé™·å ±å‘Šå¸¸å¸¸è¢«é–‹ç™¼äººå“¡å¿½ç•¥ï¼Œå› æ¤è«‹å˜—試用 +未å—æ±¡æŸ“çš„å…§æ ¸é‡ç¾å•é¡Œã€‚ -請注æ„，å³ä½¿åœ¨æ‚¨æ¶ˆé™¤å°Žè‡´æ±™æŸ“çš„åŽŸå› ï¼ˆäº¦å³å¸è¼‰å°ˆæœ‰å…§æ ¸æ¨¡å¡Šï¼‰ä¹‹å¾Œï¼Œå…§æ ¸ä»å°‡ä¿æŒ -æ±™æŸ“ç‹€æ…‹ï¼Œä»¥è¡¨ç¤ºå…§æ ¸ä»ç„¶ä¸å¯ä¿¡ã€‚é€™ä¹Ÿæ˜¯çˆ²ä»€éº¼å…§æ ¸åœ¨æ³¨æ„到內部å•é¡Œï¼ˆã€Œkernel -bugã€ï¼‰ã€å¯æ¢å¾©éŒ¯èª¤ï¼ˆã€Œkernel oopsã€ï¼‰æˆ–ä¸å¯æ¢å¾©éŒ¯èª¤ï¼ˆã€Œkernel panicã€ï¼‰æ™‚æœƒåˆ—å° -å—汙染狀態，並將有關æ¤çš„調試信æ¯å¯«å…¥æ—¥èªŒ ``dmesg`` 輸出。也å¯ä»¥é€šéŽ -``/proc/`` ä¸çš„文件在é‹è¡Œæ™‚檢查å—汙染的狀態。 +請注æ„，å³ä½¿åœ¨æ‚¨æ¶ˆé™¤å°Žè‡´æ±¡æŸ“çš„åŽŸå› ï¼ˆäº¦å³å¸è¼‰å°ˆæœ‰å…§æ ¸æ¨¡å¡Šï¼‰ä¹‹å¾Œï¼Œå…§æ ¸ä»å°‡ä¿æŒ +æ±¡æŸ“ç‹€æ…‹ï¼Œä»¥è¡¨ç¤ºå…§æ ¸ä»ç„¶ä¸å¯ä¿¡ã€‚é€™ä¹Ÿæ˜¯çˆ²ä»€éº¼å…§æ ¸åœ¨æ³¨æ„到內部å•é¡Œï¼ˆâ€œkernel +bugâ€ï¼‰ã€å¯æ¢å¾©éŒ¯èª¤ï¼ˆâ€œkernel oopsâ€ï¼‰æˆ–ä¸å¯æ¢å¾©éŒ¯èª¤ï¼ˆâ€œkernel panicâ€ï¼‰æ™‚æœƒæ‰“å° +å—污染狀態，並將有關æ¤çš„調試信æ¯å¯«å…¥æ—¥èªŒ ``dmesg`` 輸出。也å¯ä»¥é€šéŽ +``/proc/`` ä¸çš„文件在é‹è¡Œæ™‚檢查å—污染的狀態。 -BUGã€Oops或Panics消æ¯ä¸çš„汙染標誌 +BUGã€Oops或Panics消æ¯ä¸çš„污染標誌 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -åœ¨é ‚éƒ¨ä»¥ã€ŒCPU:ã€é–‹é 的一行ä¸å¯ä»¥æ‰¾åˆ°å—æ±™æŸ“çš„ç‹€æ…‹ï¼›å…§æ ¸æ˜¯å¦å—åˆ°æ±™æŸ“å’ŒåŽŸå› æœƒé¡¯ç¤º -在進程ID（「PID:ã€ï¼‰å’Œè§¸ç™¼äº‹ä»¶å‘½ä»¤çš„縮寫å稱（「Comm:ã€ï¼‰ä¹‹å¾Œ:: +åœ¨é ‚éƒ¨ä»¥â€œCPU:â€é–‹é 的一行ä¸å¯ä»¥æ‰¾åˆ°å—æ±¡æŸ“çš„ç‹€æ…‹ï¼›å…§æ ¸æ˜¯å¦å—åˆ°æ±¡æŸ“å’ŒåŽŸå› æœƒé¡¯ç¤º +在進程ID（“PID:â€ï¼‰å’Œè§¸ç™¼äº‹ä»¶å‘½ä»¤çš„縮寫å稱（“Comm:â€ï¼‰ä¹‹å¾Œ:: BUG: unable to handle kernel NULL pointer dereference at 0000000000000000 Oops: 0002 [#1] SMP PTI @@ -38,27 +38,27 @@ BUGã€Oops或Panics消æ¯ä¸çš„汙染標誌 RIP: 0010:my_oops_init+0x13/0x1000 [kpanic] [...] -å¦‚æžœå…§æ ¸åœ¨äº‹ä»¶ç™¼ç”Ÿæ™‚æ²’æœ‰è¢«æ±™æŸ“ï¼Œæ‚¨å°‡åœ¨é‚£è£¡çœ‹åˆ°ã€ŒNot-tainted:ã€ï¼›å¦‚果被汙染，那 -麼它將是「Tainted:ã€ä»¥åŠå—æ¯æˆ–ç©ºæ ¼ã€‚åœ¨ä¸Šé¢çš„例åä¸ï¼Œå®ƒçœ‹èµ·ä¾†æ˜¯é€™æ¨£çš„:: +å¦‚æžœå…§æ ¸åœ¨äº‹ä»¶ç™¼ç”Ÿæ™‚æ²’æœ‰è¢«æ±¡æŸ“ï¼Œæ‚¨å°‡åœ¨é‚£è£çœ‹åˆ°â€œNot-tainted:â€ï¼›å¦‚果被污染，那 +麼它將是“Tainted:â€ä»¥åŠå—æ¯æˆ–ç©ºæ ¼ã€‚åœ¨ä¸Šé¢çš„例åä¸ï¼Œå®ƒçœ‹èµ·ä¾†æ˜¯é€™æ¨£çš„:: Tainted: P W O 下表解釋了這些å—符的å«ç¾©ã€‚在本例ä¸ï¼Œç”±æ–¼åŠ 載了專有模塊（ ``P`` ），出ç¾äº† è¦å‘Šï¼ˆ ``W`` ï¼‰ï¼Œä¸¦ä¸”åŠ è¼‰äº†å¤–éƒ¨æ§‹å»ºçš„æ¨¡å¡Šï¼ˆ ``O`` ï¼‰ï¼Œæ‰€ä»¥å…§æ ¸æ—©äº›æ™‚å€™å—到 -了汙染。è¦è§£ç¢¼å…¶ä»–å—符，請使用下表。 +了污染。è¦è§£ç¢¼å…¶ä»–å—符，請使用下表。 -解碼é‹è¡Œæ™‚的汙染狀態 +解碼é‹è¡Œæ™‚的污染狀態 ~~~~~~~~~~~~~~~~~~~~~ -在é‹è¡Œæ™‚，您å¯ä»¥é€šéŽè®€å– ``cat /proc/sys/kernel/tainted`` 來查詢å—汙染狀態。 -如果返回 ``0`` ï¼Œå‰‡å…§æ ¸æ²’æœ‰å—到汙染；任何其他數å—都表示å—åˆ°æ±™æŸ“çš„åŽŸå› ã€‚è§£ç¢¼ +在é‹è¡Œæ™‚，您å¯ä»¥é€šéŽè®€å– ``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) @@ -69,19 +69,19 @@ BUGã€Oops或Panics消æ¯ä¸çš„汙染標誌 a more details explanation of the various taint flags. Raw taint value as int/string: 4609/'P W O ' -ä½ ä¹Ÿå¯ä»¥è©¦è‘—自己解碼這個數å—ã€‚å¦‚æžœå…§æ ¸è¢«æ±™æŸ“çš„åŽŸå› åªæœ‰ä¸€å€‹ï¼Œé‚£éº¼é€™å¾ˆç°¡å–®ï¼Œ +ä½ ä¹Ÿå¯ä»¥è©¦ç€è‡ªå·±è§£ç¢¼é€™å€‹æ•¸å—ã€‚å¦‚æžœå…§æ ¸è¢«æ±¡æŸ“çš„åŽŸå› åªæœ‰ä¸€å€‹ï¼Œé‚£éº¼é€™å¾ˆç°¡å–®ï¼Œ 在本例ä¸æ‚¨å¯ä»¥é€šéŽä¸‹è¡¨æ‰¾åˆ°æ•¸å—ã€‚å¦‚æžœä½ éœ€è¦è§£ç¢¼æœ‰å¤šå€‹åŽŸå› 的數å—ï¼Œå› çˆ²å®ƒæ˜¯ä¸€ -個ä½åŸŸï¼ˆbitfield），其ä¸æ¯å€‹ä½è¡¨ç¤ºä¸€å€‹ç‰¹å®šé¡žåž‹çš„汙染的å˜åœ¨æˆ–ä¸å˜åœ¨ï¼Œæœ€å¥½è®“ +個ä½åŸŸï¼ˆ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 æ¨¡å¡Šè¢«å¼·åˆ¶åŠ è¼‰ @@ -89,23 +89,23 @@ BUGã€Oops或Panics消æ¯ä¸çš„汙染標誌 3 _/R 8 模塊被強制å¸è¼‰ 4 _/M 16 處ç†å™¨å ±å‘Šäº†æ©Ÿå™¨æª¢æ¸¬ç•°å¸¸ï¼ˆMCE） 5 _/B 32 引用了錯誤的é 或æŸäº›æ„外的é 標誌 - 6 _/U 64 用戶空間應用程å¼è«‹æ±‚的汙染 + 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 å·²åŠ è¼‰å¤–éƒ¨æ§‹å»ºï¼ˆã€Œæ¨¹å¤–ã€ï¼‰æ¨¡å¡Š + 11 _/I 2048 已應用平臺固件缺陷的解決方案 + 12 _/O 4096 å·²åŠ è¼‰å¤–éƒ¨æ§‹å»ºï¼ˆâ€œæ¨¹å¤–â€ï¼‰æ¨¡å¡Š 13 _/E 8192 å·²åŠ è¼‰æœªç°½å的模塊 14 _/L 16384 發生軟鎖定 15 _/K 32768 å…§æ ¸å·²å¯¦æ™‚æ‰“è£œä¸ - 16 _/X 65536 備用汙染，爲發行版定義並使用 + 16 _/X 65536 備用污染，爲發行版定義並使用 17 _/T 131072 å…§æ ¸æ˜¯ç”¨çµæ§‹éš¨æ©ŸåŒ–æ’件構建的 === ===== ====== ======================================================== -註：å—符 ``_`` 表示空白，以便於閱讀表。 +注：å—符 ``_`` 表示空白，以便於閱讀表。 -汙染的更詳細解釋 +污染的更詳細解釋 ~~~~~~~~~~~~~~~~~ 0) ``G`` åŠ è¼‰çš„æ‰€æœ‰æ¨¡å¡Šéƒ½æœ‰GPL或兼容許å¯è‰ï¼Œ ``P`` åŠ è¼‰äº†ä»»ä½•å°ˆæœ‰æ¨¡å¡Šã€‚ @@ -115,14 +115,14 @@ BUGã€Oops或Panics消æ¯ä¸çš„汙染標誌 1) ``F`` 任何模塊被 ``insmod -f`` å¼·åˆ¶åŠ è¼‰ï¼Œ ``' '`` 所有模塊æ£å¸¸åŠ 載。 - 2) ``S`` å…§æ ¸é‹è¡Œåœ¨ä¸åˆè¦ç¯„的處ç†å™¨æˆ–系統上：硬體已é‹è¡Œåœ¨ä¸å—支æŒçš„é…ç½®ä¸ï¼Œ - å› æ¤ç„¡æ³•ä¿è‰æ£ç¢ºåŸ·è¡Œã€‚å…§æ ¸å°‡è¢«æ±™æŸ“ï¼Œä¾‹å¦‚ï¼š + 2) ``S`` å…§æ ¸é‹è¡Œåœ¨ä¸åˆè¦ç¯„的處ç†å™¨æˆ–系統上：硬件已é‹è¡Œåœ¨ä¸å—支æŒçš„é…ç½®ä¸ï¼Œ + å› æ¤ç„¡æ³•ä¿è‰æ£ç¢ºåŸ·è¡Œã€‚å…§æ ¸å°‡è¢«æ±¡æŸ“ï¼Œä¾‹å¦‚ï¼š - 在x86上：PAE是通éŽintel CPU（如Pentium M）上的forcepae強制執行的，這些 CPUä¸å ±å‘ŠPAE，但å¯èƒ½æœ‰åŠŸèƒ½å¯¦ç¾ï¼ŒSMPå…§æ ¸åœ¨éžå®˜æ–¹æ”¯æŒçš„SMP Athlon CPU上 é‹è¡Œï¼ŒMSR被暴露到用戶空間ä¸ã€‚ - 在arm上：在æŸäº›CPU（如Keystone 2）上é‹è¡Œçš„å…§æ ¸ï¼Œæ²’æœ‰å•“ç”¨æŸäº›å…§æ ¸ç‰¹æ€§ã€‚ - - 在arm64上：CPU之間å˜åœ¨ä¸åŒ¹é…çš„ç¡¬é«”ç‰¹æ€§ï¼Œå¼•å°ŽåŠ è¼‰ç¨‹åºä»¥ä¸åŒçš„模å¼å¼•å°ŽCPU。 + - 在arm64上：CPU之間å˜åœ¨ä¸åŒ¹é…çš„ç¡¬ä»¶ç‰¹æ€§ï¼Œå¼•å°ŽåŠ è¼‰ç¨‹åºä»¥ä¸åŒçš„模å¼å¼•å°ŽCPU。 - æŸäº›é©…動程åºæ£åœ¨è¢«ç”¨åœ¨ä¸å—支æŒçš„體系çµæ§‹ä¸Šï¼ˆä¾‹å¦‚x86_64以外的其他系統 上的scsi/snic，éžx86/x86_64/itanium上的scsi/ips，已經æ壞了arm64上 irqchip/irq-gic的固件è¨ç½®â€¦ï¼‰ã€‚ @@ -131,22 +131,22 @@ BUGã€Oops或Panics消æ¯ä¸çš„汙染標誌 4) ``M`` 任何處ç†å™¨å ±å‘Šäº†æ©Ÿå™¨æª¢æ¸¬ç•°å¸¸ï¼Œ ``' '`` 未發生機器檢測異常。 - 5) ``B`` é é¢é‡‹æ”¾å‡½æ•¸ç™¼ç¾éŒ¯èª¤çš„é é¢å¼•ç”¨æˆ–æŸäº›æ„外的é é¢æ¨™èªŒã€‚這表示硬體å•é¡Œ - æˆ–å…§æ ¸éŒ¯èª¤ï¼›æ—¥èªŒä¸æ‡‰è©²æœ‰å…¶ä»–ä¿¡æ¯æŒ‡ç¤ºç™¼ç”Ÿæ¤æ±™æŸ“çš„åŽŸå› ã€‚ + 5) ``B`` é é¢é‡‹æ”¾å‡½æ•¸ç™¼ç¾éŒ¯èª¤çš„é é¢å¼•ç”¨æˆ–æŸäº›æ„外的é é¢æ¨™èªŒã€‚這表示硬件å•é¡Œ + æˆ–å…§æ ¸éŒ¯èª¤ï¼›æ—¥èªŒä¸æ‡‰è©²æœ‰å…¶ä»–ä¿¡æ¯æŒ‡ç¤ºç™¼ç”Ÿæ¤æ±¡æŸ“çš„åŽŸå› ã€‚ - 6) ``U`` 用戶或用戶應用程å¼ç‰¹æ„請求è¨ç½®å—汙染標誌，å¦å‰‡æ‡‰çˆ² ``' '`` 。 + 6) ``U`` 用戶或用戶應用程åºç‰¹æ„請求è¨ç½®å—污染標誌，å¦å‰‡æ‡‰çˆ² ``' '`` 。 7) ``D`` å…§æ ¸æœ€è¿‘æ»æ©Ÿäº†ï¼Œå³å‡ºç¾äº†OOPS或BUG。 8) ``A`` ACPI表被é‡å¯«ã€‚ - 9) ``W`` å…§æ ¸ä¹‹å‰å·²ç™¼å‡ºéŽè¦å‘Šï¼ˆå„˜ç®¡æœ‰äº›è¦å‘Šå¯èƒ½æœƒè¨ç½®æ›´å…·é«”的汙染標誌）。 + 9) ``W`` å…§æ ¸ä¹‹å‰å·²ç™¼å‡ºéŽè¦å‘Šï¼ˆå„˜ç®¡æœ‰äº›è¦å‘Šå¯èƒ½æœƒè¨ç½®æ›´å…·é«”的污染標誌）。 10) ``C`` å·²åŠ è¼‰staging驅動程åºã€‚ - 11) ``I`` å…§æ ¸æ£åœ¨è™•ç†å¹³å°å›ºä»¶ï¼ˆBIOS或類似軟體）ä¸çš„åš´é‡éŒ¯èª¤ã€‚ + 11) ``I`` å…§æ ¸æ£åœ¨è™•ç†å¹³è‡ºå›ºä»¶ï¼ˆBIOS或類似軟件）ä¸çš„åš´é‡éŒ¯èª¤ã€‚ - 12) ``O`` å·²åŠ è¼‰å¤–éƒ¨æ§‹å»ºï¼ˆã€Œæ¨¹å¤–ã€ï¼‰æ¨¡å¡Šã€‚ + 12) ``O`` å·²åŠ è¼‰å¤–éƒ¨æ§‹å»ºï¼ˆâ€œæ¨¹å¤–â€ï¼‰æ¨¡å¡Šã€‚ 13) ``E`` 在支æŒæ¨¡å¡Šç°½åçš„å…§æ ¸ä¸åŠ 載了未簽å的模塊。 @@ -154,8 +154,8 @@ BUGã€Oops或Panics消æ¯ä¸çš„汙染標誌 15) ``K`` å…§æ ¸å·²ç¶“å¯¦æ™‚æ‰“äº†è£œä¸ã€‚ - 16) ``X`` 備用汙染，由Linux發行版定義和使用。 + 16) ``X`` 備用污染，由Linux發行版定義和使用。 17) ``T`` å…§æ ¸æ§‹å»ºæ™‚ä½¿ç”¨äº†randstructæ’件，它å¯ä»¥æœ‰æ„生æˆéžå¸¸ä¸å°‹å¸¸çš„å…§æ ¸çµæ§‹ - 布局（甚至是性能病態的布局），這在調試時éžå¸¸æœ‰ç”¨ã€‚於構建時è¨ç½®ã€‚ + 佈局（甚至是性能病態的佈局），這在調試時éžå¸¸æœ‰ç”¨ã€‚於構建時è¨ç½®ã€‚ diff --git a/Documentation/translations/zh_TW/admin-guide/unicode.rst b/Documentation/translations/zh_TW/admin-guide/unicode.rst index 7908b369b85b..a2b48b5d0a64 100644 --- a/Documentation/translations/zh_TW/admin-guide/unicode.rst +++ b/Documentation/translations/zh_TW/admin-guide/unicode.rst @@ -37,15 +37,15 @@ IBMPC_MAP IBM code page 437 ESC ( U USER_MAP User defined ESC ( K =============== =============================== ================ -特別是 ESC ( U ä¸å†æ˜¯ã€Œç›´é€šå—é«”ã€ï¼Œå› 爲å—é«”å¯èƒ½èˆ‡IBMå—符集完全ä¸åŒã€‚ +特別是 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ä½œçˆ²èµ·é»žï¼Œå› çˆ²å®ƒå…è¨±ç›´æŽ¥æ˜ å°„ +æ ¹æ“šUnicode標準/ISO 10646，U+F000到U+F8FF被ä¿ç•™ç”¨æ–¼æ“作系統範åœå…§çš„åˆ†é… +（Unicode標準將其稱爲“團體å€åŸŸï¼ˆCorporate Zone）â€ï¼Œå› 爲這å°æ–¼Linux是ä¸æº–確 +的，所以我們稱之爲“Linuxå€åŸŸâ€ï¼‰ã€‚é¸æ“‡U+F000ä½œçˆ²èµ·é»žï¼Œå› çˆ²å®ƒå…è¨±ç›´æŽ¥æ˜ å°„ å€åŸŸä»¥2的大å€æ•¸é–‹å§‹ï¼ˆä»¥é˜²éœ€è¦1024或2048個å—符的å—體）。這就留下U+E000到 U+EFFF作爲最終用戶å€ã€‚ @@ -87,7 +87,7 @@ U+F813 KEYBOARD SYMBOL SOLID APPLE 克林貢（Klingonï¼‰èªžæ”¯æŒ ------------------------ -1996年，Linuxæ˜¯ä¸–ç•Œä¸Šç¬¬ä¸€å€‹æ·»åŠ å°äººå·¥èªžè¨€å…‹æž—貢支æŒçš„作æ¥ç³»çµ±ï¼Œå…‹æž—貢是由 +1996年，Linuxæ˜¯ä¸–ç•Œä¸Šç¬¬ä¸€å€‹æ·»åŠ å°äººå·¥èªžè¨€å…‹æž—貢支æŒçš„æ“作系統，克林貢是由 Marc Okrandçˆ²ã€Šæ˜Ÿéš›è¿·èˆªã€‹é›»è¦–é€£çºŒåŠ‡å‰µé€ çš„ã€‚é€™ç¨®ç·¨ç¢¼å¾Œä¾†è¢«å¾µå‹ŸUnicode註冊表 （ConScript Unicode Registry，CSUR）採用，並建è°ï¼ˆä½†æœ€çµ‚被拒絕）ç´å…¥Unicode å¹³é¢ä¸€ã€‚ä¸éŽï¼Œå®ƒä»ç„¶æ˜¯Linuxå€åŸŸä¸çš„Linux/CSURç§æœ‰åˆ†é…。 diff --git a/Documentation/translations/zh_TW/arch/arm/Booting b/Documentation/translations/zh_TW/arch/arm/Booting new file mode 100644 index 000000000000..a5375f262de2 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/arm/Booting @@ -0,0 +1,176 @@ +Chinese translated version of Documentation/arch/arm/booting.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Russell King <linux@arm.linux.org.uk> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arch/arm/booting.rst çš„ä¸æ–‡ç¿»è¯ + +如果想評論或更新本文的內容，請直接è¯ç¹«åŽŸæ–‡æª”çš„ç¶è·è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ +交æµæœ‰å›°é›£çš„話，也å¯ä»¥å‘ä¸æ–‡ç‰ˆç¶è·è€…求助。如果本翻è¯æ›´æ–°ä¸åŠæ™‚或者翻 +è¯å˜åœ¨å•é¡Œï¼Œè«‹è¯ç¹«ä¸æ–‡ç‰ˆç¶è·è€…。 + +英文版ç¶è·è€…： Russell King <linux@arm.linux.org.uk> +ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> +ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> +ä¸æ–‡ç‰ˆæ ¡è¯è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> + +以下爲æ£æ–‡ +--------------------------------------------------------------------- + + å•“å‹• ARM Linux + ============== + +作者：Russell King +日期：2002å¹´5月18æ—¥ + +以下文檔é©ç”¨æ–¼ 2.4.18-rmk6 åŠä»¥ä¸Šç‰ˆæœ¬ã€‚ + +爲了啓動 ARM Linuxï¼Œä½ éœ€è¦ä¸€å€‹å¼•å°Žè£è¼‰ç¨‹åºï¼ˆboot loader）， +å®ƒæ˜¯ä¸€å€‹åœ¨ä¸»å…§æ ¸å•“å‹•å‰é‹è¡Œçš„一個å°ç¨‹åºã€‚引導è£è¼‰ç¨‹åºéœ€è¦åˆå§‹åŒ–å„種 +è¨å‚™ï¼Œä¸¦æœ€çµ‚調用 Linux å…§æ ¸ï¼Œå°‡ä¿¡æ¯å‚³éžçµ¦å…§æ ¸ã€‚ + +從本質上講，引導è£è¼‰ç¨‹åºæ‡‰æ供（至少）以下功能： + +1ã€è¨ç½®å’Œåˆå§‹åŒ– RAM。 +2ã€åˆå§‹åŒ–一個串å£ã€‚ +3ã€æª¢æ¸¬æ©Ÿå™¨çš„類型（machine type）。 +4ã€è¨ç½®å…§æ ¸æ¨™ç±¤åˆ—表（tagged list）。 +5ã€èª¿ç”¨å…§æ ¸æ˜ åƒã€‚ + + +1ã€è¨ç½®å’Œåˆå§‹åŒ– RAM +------------------- + +ç¾æœ‰çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: 強制 +æ–°é–‹ç™¼çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: 強制 + +引導è£è¼‰ç¨‹åºæ‡‰è©²æ‰¾åˆ°ä¸¦åˆå§‹åŒ–系統ä¸æ‰€æœ‰å…§æ ¸ç”¨æ–¼ä¿æŒç³»çµ±è®Šé‡æ•¸æ“šçš„ RAM。 +這個æ“作的執行是è¨å‚™ä¾è³´çš„。（它å¯èƒ½ä½¿ç”¨å…§éƒ¨ç®—法來自動定ä½å’Œè¨ˆç®—所有 +RAM，或å¯èƒ½ä½¿ç”¨å°é€™å€‹è¨å‚™å·²çŸ¥çš„ RAM ä¿¡æ¯ï¼Œé‚„å¯èƒ½ä½¿ç”¨ä»»ä½•å¼•å°Žè£è¼‰ç¨‹åº +è¨è¨ˆè€…想到的匹é…方法。） + + +2ã€åˆå§‹åŒ–ä¸€å€‹ä¸²å£ +----------------------------- + +ç¾æœ‰çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: å¯é¸ã€å»ºè° +æ–°é–‹ç™¼çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: å¯é¸ã€å»ºè° + +å¼•å°ŽåŠ è¼‰ç¨‹åºæ‡‰è©²åˆå§‹åŒ–並使能一個目標æ¿ä¸Šçš„串å£ã€‚這å…è¨±å…§æ ¸ä¸²å£é©…å‹• +自動檢測哪個串å£ç”¨æ–¼å…§æ ¸æŽ§åˆ¶æª¯ã€‚(一般用於調試或與目標æ¿é€šä¿¡ã€‚) + +ä½œçˆ²æ›¿ä»£æ–¹æ¡ˆï¼Œå¼•å°ŽåŠ è¼‰ç¨‹åºä¹Ÿå¯ä»¥é€šéŽæ¨™ç±¤åˆ—表傳éžç›¸é—œçš„'console=' +é¸é …çµ¦å…§æ ¸ä»¥æŒ‡å®šæŸå€‹ä¸²å£ï¼Œè€Œä¸²å£æ•¸æ“šæ ¼å¼çš„é¸é …在以下文檔ä¸æ述： + + Documentation/admin-guide/kernel-parameters.rst。 + + +3ã€æª¢æ¸¬æ©Ÿå™¨é¡žåž‹ +-------------------------- + +ç¾æœ‰çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: å¯é¸ +æ–°é–‹ç™¼çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: 強制 + +å¼•å°ŽåŠ è¼‰ç¨‹åºæ‡‰è©²é€šéŽæŸäº›æ–¹å¼æª¢æ¸¬è‡ªèº«æ‰€è™•çš„機器類型。這是一個硬件 +代碼或通éŽæŸ¥çœ‹æ‰€é€£æŽ¥çš„硬件用æŸäº›ç®—法得到，這些超出了本文檔的範åœã€‚ +å¼•å°ŽåŠ è¼‰ç¨‹åºæœ€çµ‚å¿…é ˆèƒ½æ供一個 MACH_TYPE_xxx å€¼çµ¦å…§æ ¸ã€‚ +(詳見 linux/arch/arm/tools/mach-types )。 + +4ã€è¨ç½®å•“動數據 +------------------ + +ç¾æœ‰çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: å¯é¸ã€å¼·çƒˆå»ºè° +æ–°é–‹ç™¼çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: 強制 + +å¼•å°ŽåŠ è¼‰ç¨‹åºå¿…é ˆæ供標籤列表或者 dtb æ˜ åƒä»¥å‚³éžé…ç½®æ•¸æ“šçµ¦å…§æ ¸ã€‚å•“å‹• +數據的物ç†åœ°å€é€šéŽå¯„å˜å™¨ r2 傳éžçµ¦å…§æ ¸ã€‚ + +4aã€è¨ç½®å…§æ ¸æ¨™ç±¤åˆ—表 +-------------------------------- + +bootloader å¿…é ˆå‰µå»ºå’Œåˆå§‹åŒ–å…§æ ¸æ¨™ç±¤åˆ—è¡¨ã€‚ä¸€å€‹æœ‰æ•ˆçš„æ¨™ç±¤åˆ—è¡¨ä»¥ +ATAG_CORE 標籤開始，並以 ATAG_NONE 標籤çµæŸã€‚ATAG_CORE 標籤å¯ä»¥æ˜¯ +空的，也å¯ä»¥æ˜¯éžç©ºã€‚一個空 ATAG_CORE 標籤其 size 域è¨ç½®çˆ² +‘2’(0x00000002)。ATAG_NONE 標籤的 size åŸŸå¿…é ˆè¨ç½®çˆ²é›¶ã€‚ + +在列表ä¸å¯ä»¥ä¿å˜ä»»æ„數é‡çš„標籤。å°æ–¼ä¸€å€‹é‡è¤‡çš„æ¨™ç±¤æ˜¯è¿½åŠ åˆ°ä¹‹å‰æ¨™ç±¤ +所攜帶的信æ¯ä¹‹å¾Œï¼Œé‚„是會覆蓋原來的信æ¯ï¼Œæ˜¯æœªå®šç¾©çš„。æŸäº›æ¨™ç±¤çš„行爲 +是å‰è€…，其他是後者。 + +bootloader å¿…é ˆå‚³éžä¸€å€‹ç³»çµ±å…§å˜çš„ä½ç½®å’Œæœ€å°å€¼ï¼Œä»¥åŠæ ¹æ–‡ä»¶ç³»çµ±ä½ç½®ã€‚ +å› æ¤ï¼Œæœ€å°çš„標籤列表如下所示： + + +-----------+ +åŸºåœ°å€ -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | 地å€å¢žé•·æ–¹å‘ + +-----------+ | + | ATAG_NONE | | + +-----------+ v + +標籤列表應該ä¿å˜åœ¨ç³»çµ±çš„ RAM ä¸ã€‚ + +æ¨™ç±¤åˆ—è¡¨å¿…é ˆç½®æ–¼å…§æ ¸è‡ªè§£å£“å’Œ initrd'bootp' 程åºéƒ½ä¸æœƒè¦†è“‹çš„å…§å˜å€ã€‚ +建è°æ”¾åœ¨ RAM çš„é 16KiB ä¸ã€‚ + +4bã€è¨ç½®è¨å‚™æ¨¹ +------------------------- + +bootloader å¿…é ˆä»¥ 64bit 地å€å°é½Šçš„å½¢å¼åŠ 載一個è¨å‚™æ¨¹æ˜ åƒ(dtb)到系統 +RAM ä¸ï¼Œä¸¦ç”¨å•“動數據åˆå§‹åŒ–它。dtb æ ¼å¼åœ¨æ–‡æª” +https://www.devicetree.org/specifications/ ä¸ã€‚å…§æ ¸å°‡æœƒåœ¨ +dtb 物ç†åœ°å€è™•æŸ¥æ‰¾ dtb é”數值（0xd00dfeed），以確定 dtb 是å¦å·²ç¶“代替 +標籤列表被傳éžé€²ä¾†ã€‚ + +bootloader å¿…é ˆå‚³éžä¸€å€‹ç³»çµ±å…§å˜çš„ä½ç½®å’Œæœ€å°å€¼ï¼Œä»¥åŠæ ¹æ–‡ä»¶ç³»çµ±ä½ç½®ã€‚ +dtb å¿…é ˆç½®æ–¼å…§æ ¸è‡ªè§£å£“ä¸æœƒè¦†è“‹çš„å…§å˜å€ã€‚建è°å°‡å…¶æ”¾ç½®æ–¼ RAM çš„é 16KiB +ä¸ã€‚但是ä¸å¯å°‡å…¶æ”¾ç½®æ–¼â€œ0â€ç‰©ç†åœ°å€è™•ï¼Œå› çˆ²å…§æ ¸èªçˆ²ï¼šr2 ä¸çˆ² 0，æ„å‘³ç€ +沒有標籤列表和 dtb 傳éžéŽä¾†ã€‚ + +5ã€èª¿ç”¨å…§æ ¸æ˜ åƒ +--------------------------- + +ç¾æœ‰çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: 強制 +æ–°é–‹ç™¼çš„å¼•å°ŽåŠ è¼‰ç¨‹åº: 強制 + +èª¿ç”¨å…§æ ¸æ˜ åƒ zImage 有兩個é¸æ“‡ã€‚如果 zImge ä¿å˜åœ¨ flash ä¸ï¼Œä¸”是爲了 +在 flash ä¸ç›´æŽ¥é‹è¡Œè€Œè¢«æ£ç¢ºéˆæŽ¥çš„ã€‚é€™æ¨£å¼•å°ŽåŠ è¼‰ç¨‹åºå°±å¯ä»¥åœ¨ flash ä¸ +直接調用 zImage。 + +zImage 也å¯ä»¥è¢«æ”¾åœ¨ç³»çµ± RAM（任æ„ä½ç½®ï¼‰ä¸è¢«èª¿ç”¨ã€‚注æ„ï¼šå…§æ ¸ä½¿ç”¨æ˜ åƒ +基地å€çš„å‰ 16KB RAM 空間來ä¿å˜é 表。建è°å°‡æ˜ åƒç½®æ–¼ RAM çš„ 32KB 處。 + +å°æ–¼ä»¥ä¸Šä»»æ„一種情æ³ï¼Œéƒ½å¿…é ˆç¬¦åˆä»¥ä¸‹å•“動狀態： + +- åœæ¢æ‰€æœ‰ DMA è¨å‚™ï¼Œé€™æ¨£å…§å˜æ•¸æ“šå°±ä¸æœƒå› 爲虛å‡ç¶²çµ¡åŒ…或ç£ç›¤æ•¸æ“šè€Œè¢«ç ´å£žã€‚ + 這å¯èƒ½å¯ä»¥ç¯€çœä½ 許多的調試時間。 + +- CPU 寄å˜å™¨é…ç½® + r0 = 0， + r1 = ï¼ˆåœ¨ä¸Šé¢ 3 ä¸ç²å–的）機器類型碼。 + r2 = 標籤列表在系統 RAM ä¸çš„物ç†åœ°å€ï¼Œæˆ– + è¨å‚™æ¨¹å¡Š(dtb)在系統 RAM ä¸çš„物ç†åœ°å€ + +- CPU æ¨¡å¼ + 所有形å¼çš„ä¸æ–·å¿…é ˆè¢«ç¦æ¢ (IRQs å’Œ FIQs) + CPU å¿…é ˆè™•æ–¼ SVC 模å¼ã€‚(å°æ–¼ Angel 調試有特例å˜åœ¨) + +- ç·©å˜ï¼ŒMMUs + MMU å¿…é ˆé—œé–‰ã€‚ + 指令緩å˜é–‹å•“或關閉都å¯ä»¥ã€‚ + 數據緩å˜å¿…é ˆé—œé–‰ã€‚ + +- å¼•å°ŽåŠ è¼‰ç¨‹åºæ‡‰è©²é€šéŽç›´æŽ¥è·³è½‰åˆ°å…§æ ¸æ˜ åƒçš„第一æ¢æŒ‡ä»¤ä¾†èª¿ç”¨å…§æ ¸æ˜ åƒã€‚ + + å°æ–¼æ”¯æŒ ARM 指令集的 CPUï¼Œè·³å…¥å…§æ ¸å…¥å£æ™‚å¿…é ˆè™•åœ¨ ARM 狀態，å³ä½¿ + å°æ–¼ Thumb-2 å…§æ ¸ä¹Ÿæ˜¯å¦‚æ¤ã€‚ + + å°æ–¼åƒ…æ”¯æŒ Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入 + å…§æ ¸å…¥å£æ™‚å¿…é ˆè™•æ–¼ Thumb 狀態。 + diff --git a/Documentation/translations/zh_TW/arch/arm/kernel_user_helpers.txt b/Documentation/translations/zh_TW/arch/arm/kernel_user_helpers.txt new file mode 100644 index 000000000000..4c0bff97af31 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/arm/kernel_user_helpers.txt @@ -0,0 +1,285 @@ +Chinese translated version of Documentation/arch/arm/kernel_user_helpers.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Nicolas Pitre <nicolas.pitre@linaro.org> + Dave Martin <dave.martin@linaro.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arch/arm/kernel_user_helpers.rst çš„ä¸æ–‡ç¿»è¯ + +如果想評論或更新本文的內容，請直接è¯ç¹«åŽŸæ–‡æª”çš„ç¶è·è€…ã€‚å¦‚æžœä½ ä½¿ç”¨è‹±æ–‡ +交æµæœ‰å›°é›£çš„話，也å¯ä»¥å‘ä¸æ–‡ç‰ˆç¶è·è€…求助。如果本翻è¯æ›´æ–°ä¸åŠæ™‚或者翻 +è¯å˜åœ¨å•é¡Œï¼Œè«‹è¯ç¹«ä¸æ–‡ç‰ˆç¶è·è€…。 +英文版ç¶è·è€…： Nicolas Pitre <nicolas.pitre@linaro.org> + Dave Martin <dave.martin@linaro.org> +ä¸æ–‡ç‰ˆç¶è·è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> +ä¸æ–‡ç‰ˆç¿»è¯è€…： å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> +ä¸æ–‡ç‰ˆæ ¡è¯è€…： 宋冬生 Dongsheng Song <dongshneg.song@gmail.com> + å‚…ç…’ Fu Wei <tekkamanninja@gmail.com> + + +以下爲æ£æ–‡ +--------------------------------------------------------------------- +å…§æ ¸æ供的用戶空間輔助代碼 +========================= + +åœ¨å…§æ ¸å…§å˜ç©ºé–“的固定地å€è™•ï¼Œæœ‰ä¸€å€‹ç”±å…§æ ¸æ供並å¯å¾žç”¨æˆ¶ç©ºé–“訪å•çš„代碼 +段。它用於å‘用戶空間æä¾›å› åœ¨è¨±å¤š ARM CPU ä¸æœªå¯¦ç¾çš„特性和/或指令而需 +å…§æ ¸æ供幫助的æŸäº›æ“作。這些代碼直接在用戶模å¼ä¸‹åŸ·è¡Œçš„想法是爲了ç²å¾— +æœ€ä½³æ•ˆçŽ‡ï¼Œä½†é‚£äº›èˆ‡å…§æ ¸è¨ˆæ•¸å™¨è¯ç¹«éŽæ–¼ç·Šå¯†çš„部分，則被留給了用戶庫實ç¾ã€‚ +事實上，æ¤ä»£ç¢¼ç”šè‡³å¯èƒ½å› ä¸åŒçš„ CPU 而異，這å–決於其å¯ç”¨çš„指令集或它 +是å¦çˆ² SMP 系統。æ›å¥è©±èªªï¼Œå…§æ ¸ä¿ç•™åœ¨ä¸ä½œå‡ºè¦å‘Šçš„情æ³ä¸‹æ ¹æ“šéœ€è¦æ›´æ”¹ +這些代碼的權利。åªæœ‰æœ¬æ–‡æª”æè¿°çš„å…¥å£åŠå…¶çµæžœæ˜¯ä¿è‰ç©©å®šçš„。 + +這與完全æˆç†Ÿçš„ VDSO 實ç¾ä¸åŒï¼ˆä½†å…©è€…並ä¸è¡çªï¼‰ï¼Œå„˜ç®¡å¦‚æ¤ï¼ŒVDSO å¯é˜»æ¢ +æŸäº›é€šéŽå¸¸é‡é«˜æ•ˆè·³è½‰åˆ°é‚£äº›ä»£ç¢¼æ®µçš„彙編技巧。且由於那些代碼段在返回用戶 +代碼å‰åƒ…使用少é‡çš„代碼週期，則一個 VDSO 間接é 程調用將會在這些簡單的 +æ“ä½œä¸Šå¢žåŠ ä¸€å€‹å¯æ¸¬é‡çš„開銷。 + +在å°é‚£äº›æ“有原生支æŒçš„新型處ç†å™¨é€²è¡Œä»£ç¢¼å„ªåŒ–時，僅在已爲其他æ“作使用 +了類似的新增指令，而導致二進制çµæžœå·²èˆ‡æ—©æœŸ ARM 處ç†å™¨ä¸å…¼å®¹çš„情æ³ä¸‹ï¼Œ +用戶空間æ‰æ‡‰ç¹žéŽé€™äº›è¼”助代碼，並在內è¯å‡½æ•¸ä¸å¯¦ç¾é€™äº›æ“ä½œï¼ˆç„¡è«–æ˜¯é€šéŽ +ç·¨è¯å™¨åœ¨ä»£ç¢¼ä¸ç›´æŽ¥æ”¾ç½®ï¼Œé‚„是作爲庫函數調用實ç¾çš„一部分）。也就是說， +å¦‚æžœä½ ç·¨è¯çš„代碼ä¸æœƒçˆ²äº†å…¶ä»–目的使用新指令，則ä¸è¦åƒ…爲了é¿å…使用這些 +å…§æ ¸è¼”åŠ©ä»£ç¢¼ï¼Œå°Žè‡´äºŒé€²åˆ¶ç¨‹åºç„¡æ³•åœ¨æ—©æœŸè™•ç†å™¨ä¸Šé‹è¡Œã€‚ + +新的輔助代碼å¯èƒ½éš¨ç€æ™‚é–“çš„æŽ¨ç§»è€Œå¢žåŠ ï¼Œæ‰€ä»¥æ–°å…§æ ¸ä¸çš„æŸäº›è¼”助代碼在舊 +å…§æ ¸ä¸å¯èƒ½ä¸å˜åœ¨ã€‚å› æ¤ï¼Œç¨‹åºå¿…é ˆåœ¨å°ä»»ä½•è¼”助代碼調用å‡è¨æ˜¯å®‰å…¨ä¹‹å‰ï¼Œ +檢測 __kuser_helper_version 的值（見下文）。ç†æƒ³æƒ…æ³ä¸‹ï¼Œé€™ç¨®æª¢æ¸¬æ‡‰è©² +åªåœ¨é€²ç¨‹å•“å‹•æ™‚åŸ·è¡Œä¸€æ¬¡ï¼›å¦‚æžœå…§æ ¸ç‰ˆæœ¬ä¸æ”¯æŒæ‰€éœ€è¼”助代碼，則該進程å¯å„˜æ—© +ä¸æ¢åŸ·è¡Œã€‚ + +kuser_helper_version +-------------------- + +ä½ç½®: 0xffff0ffc + +åƒè€ƒè²æ˜Ž: + + extern int32_t __kuser_helper_version; + +定義: + + 這個å€åŸŸåŒ…å«äº†ç•¶å‰é‹è¡Œå…§æ ¸å¯¦ç¾çš„輔助代碼版本號。用戶空間å¯ä»¥é€šéŽè®€ + å–æ¤ç‰ˆæœ¬è™Ÿä»¥ç¢ºå®šç‰¹å®šçš„輔助代碼是å¦å˜åœ¨ã€‚ + +使用範例: + +#define __kuser_helper_version (*(int32_t *)0xffff0ffc) + +void check_kuser_version(void) +{ + if (__kuser_helper_version < 2) { + fprintf(stderr, "can't do atomic operations, kernel too old\n"); + abort(); + } +} + +注æ„: + + 用戶空間å¯ä»¥å‡è¨é€™å€‹åŸŸçš„值ä¸æœƒåœ¨ä»»ä½•å–®å€‹é€²ç¨‹çš„生å˜æœŸå…§æ”¹è®Šã€‚也就 + 是說，這個域å¯ä»¥åƒ…在庫的åˆå§‹åŒ–階段或進程啓動階段讀å–一次。 + +kuser_get_tls +------------- + +ä½ç½®: 0xffff0fe0 + +åƒè€ƒåŽŸåž‹: + + void * __kuser_get_tls(void); + +輸入: + + lr = è¿”å›žåœ°å€ + +輸出: + + r0 = TLS 值 + +被篡改的寄å˜å™¨: + + ç„¡ + +定義: + + ç²å–之å‰é€šéŽ __ARM_NR_set_tls 系統調用è¨ç½®çš„ TLS 值。 + +使用範例: + +typedef void * (__kuser_get_tls_t)(void); +#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) + +void foo() +{ + void *tls = __kuser_get_tls(); + printf("TLS = %p\n", tls); +} + +注æ„: + + - 僅在 __kuser_helper_version >= 1 時，æ¤è¼”助代碼å˜åœ¨ + ï¼ˆå¾žå…§æ ¸ç‰ˆæœ¬ 2.6.12 開始）。 + +kuser_cmpxchg +------------- + +ä½ç½®: 0xffff0fc0 + +åƒè€ƒåŽŸåž‹: + + int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); + +輸入: + + r0 = oldval + r1 = newval + r2 = ptr + lr = è¿”å›žåœ°å€ + +輸出: + + r0 = æˆåŠŸä»£ç¢¼ (零或éžé›¶) + C flag = 如果 r0 == 0 則置 1，如果 r0 != 0 則清零。 + +被篡改的寄å˜å™¨: + + r3, ip, flags + +定義: + + 僅在 *ptr 爲 oldval 時原åä¿å˜ newval æ–¼ *ptr ä¸ã€‚ + 如果 *ptr 被改變，則返回值爲零，å¦å‰‡çˆ²éžé›¶å€¼ã€‚ + 如果 *ptr 被改變，則 C flag 也會被置 1，以實ç¾èª¿ç”¨ä»£ç¢¼ä¸çš„彙編 + 優化。 + +使用範例: + +typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); +#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) + +int atomic_add(volatile int *ptr, int val) +{ + int old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg(old, new, ptr)); + + return new; +} + +注æ„: + + - é€™å€‹ä¾‹ç¨‹å·²æ ¹æ“šéœ€è¦åŒ…å«äº†å…§å˜å±éšœã€‚ + + - 僅在 __kuser_helper_version >= 2 時，æ¤è¼”助代碼å˜åœ¨ + ï¼ˆå¾žå…§æ ¸ç‰ˆæœ¬ 2.6.12 開始）。 + +kuser_memory_barrier +-------------------- + +ä½ç½®: 0xffff0fa0 + +åƒè€ƒåŽŸåž‹: + + void __kuser_memory_barrier(void); + +輸入: + + lr = è¿”å›žåœ°å€ + +輸出: + + ç„¡ + +被篡改的寄å˜å™¨: + + ç„¡ + +定義: + + 應用於任何需è¦å…§å˜å±éšœä»¥é˜²æ¢æ‰‹å‹•æ•¸æ“šä¿®æ”¹å¸¶ä¾†çš„一致性å•é¡Œï¼Œä»¥åŠ + __kuser_cmpxchg ä¸ã€‚ + +使用範例: + +typedef void (__kuser_dmb_t)(void); +#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) + +注æ„: + + - 僅在 __kuser_helper_version >= 3 時，æ¤è¼”助代碼å˜åœ¨ + ï¼ˆå¾žå…§æ ¸ç‰ˆæœ¬ 2.6.15 開始）。 + +kuser_cmpxchg64 +--------------- + +ä½ç½®: 0xffff0f60 + +åƒè€ƒåŽŸåž‹: + + int __kuser_cmpxchg64(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); + +輸入: + + r0 = æŒ‡å‘ oldval + r1 = æŒ‡å‘ newval + r2 = 指å‘目標值 + lr = è¿”å›žåœ°å€ + +輸出: + + r0 = æˆåŠŸä»£ç¢¼ (零或éžé›¶) + C flag = 如果 r0 == 0 則置 1，如果 r0 != 0 則清零。 + +被篡改的寄å˜å™¨: + + r3, lr, flags + +定義: + + 僅在 *ptr ç‰æ–¼ *oldval 指å‘çš„ 64 ä½å€¼æ™‚，原åä¿å˜ *newval + 指å‘çš„ 64 ä½å€¼æ–¼ *ptr ä¸ã€‚如果 *ptr 被改變，則返回值爲零， + å¦å‰‡çˆ²éžé›¶å€¼ã€‚ + + 如果 *ptr 被改變，則 C flag 也會被置 1，以實ç¾èª¿ç”¨ä»£ç¢¼ä¸çš„彙編 + 優化。 + +使用範例: + +typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); +#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) + +int64_t atomic_add64(volatile int64_t *ptr, int64_t val) +{ + int64_t old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg64(&old, &new, ptr)); + + return new; +} + +注æ„: + + - é€™å€‹ä¾‹ç¨‹å·²æ ¹æ“šéœ€è¦åŒ…å«äº†å…§å˜å±éšœã€‚ + + - 由於這個éŽç¨‹çš„代碼長度（æ¤è¼”助代碼跨越 2 個常è¦çš„ kuser “槽â€ï¼‰ï¼Œ + å› æ¤ 0xffff0f80 ä¸è¢«ä½œçˆ²æœ‰æ•ˆçš„å…¥å£é»žã€‚ + + - 僅在 __kuser_helper_version >= 5 時，æ¤è¼”助代碼å˜åœ¨ + ï¼ˆå¾žå…§æ ¸ç‰ˆæœ¬ 3.1 開始）。 + diff --git a/Documentation/translations/zh_TW/arch/arm64/amu.rst b/Documentation/translations/zh_TW/arch/arm64/amu.rst index 21ac0db63889..1b451eae2bee 100644 --- a/Documentation/translations/zh_TW/arch/arm64/amu.rst +++ b/Documentation/translations/zh_TW/arch/arm64/amu.rst @@ -28,11 +28,11 @@ AArch64 Linux ä¸æ“´å±•çš„活動監控單元 AMUv1 架構實ç¾äº†ä¸€å€‹ç”±4個固定的64ä½äº‹ä»¶è¨ˆæ•¸å™¨çµ„æˆçš„計數器組。 - - CPU å‘¨æœŸè¨ˆæ•¸å™¨ï¼šåŒ CPU çš„é »çŽ‡å¢žé•· + - CPU é€±æœŸè¨ˆæ•¸å™¨ï¼šåŒ CPU çš„é »çŽ‡å¢žé•· - 常é‡è¨ˆæ•¸å™¨ï¼šåŒå›ºå®šçš„系統時é˜é »çŽ‡å¢žé•· - 淘汰指令計數器: åŒæ¯æ¬¡æž¶æ§‹æŒ‡ä»¤åŸ·è¡Œå¢žé•· - - å…§å˜åœé “周期計數器：計算由在時é˜åŸŸå…§çš„最後一級緩å˜ä¸æœªå‘½ä¸è€Œå¼•èµ· - 的指令調度åœé “周期數 + - å…§å˜åœé “週期計數器：計算由在時é˜åŸŸå…§çš„最後一級緩å˜ä¸æœªå‘½ä¸è€Œå¼•èµ· + 的指令調度åœé “週期數 當處於 WFI 或者 WFE 狀態時，計數器ä¸æœƒå¢žé•·ã€‚ diff --git a/Documentation/translations/zh_TW/arch/arm64/booting.txt b/Documentation/translations/zh_TW/arch/arm64/booting.txt index 3cc8f593e006..be0de91ecebd 100644 --- a/Documentation/translations/zh_TW/arch/arm64/booting.txt +++ b/Documentation/translations/zh_TW/arch/arm64/booting.txt @@ -41,8 +41,8 @@ AArch64 異常模型由多個異常級（EL0 - EL3）組æˆï¼Œå°æ–¼ EL0 å’Œ EL1 有å°æ‡‰çš„安全和éžå®‰å…¨æ¨¡å¼ã€‚EL2 是系統管ç†ç´šï¼Œä¸”僅å˜åœ¨æ–¼éžå®‰å…¨æ¨¡å¼ä¸‹ã€‚ EL3 是最高特權級，且僅å˜åœ¨æ–¼å®‰å…¨æ¨¡å¼ä¸‹ã€‚ -基於本文檔的目的，我們將簡單地使用『引導è£è¼‰ç¨‹åºã€ï¼ˆã€Žboot loaderã€ï¼‰ -這個術語來定義在將控制權交給 Linux å…§æ ¸å‰ CPU 上執行的所有軟體。 +基於本文檔的目的，我們將簡單地使用‘引導è£è¼‰ç¨‹åºâ€™ï¼ˆâ€˜boot loader’） +這個術語來定義在將控制權交給 Linux å…§æ ¸å‰ CPU 上執行的所有軟件。 這å¯èƒ½åŒ…å«å®‰å…¨ç›£æŽ§å’Œç³»çµ±ç®¡ç†ä»£ç¢¼ï¼Œæˆ–者它å¯èƒ½åªæ˜¯ä¸€äº›ç”¨æ–¼æº–備最å°å•“å‹• 環境的指令。 @@ -74,7 +74,7 @@ RAM，或å¯èƒ½ä½¿ç”¨å°é€™å€‹è¨å‚™å·²çŸ¥çš„ RAM ä¿¡æ¯ï¼Œé‚„å¯èƒ½æ˜¯å¼•å°Žè£ 數據塊將在使能緩å˜çš„情æ³ä¸‹ä»¥ 2MB ç²’åº¦è¢«æ˜ å°„ï¼Œæ•…å…¶ä¸èƒ½è¢«ç½®æ–¼å¿…é ˆä»¥ç‰¹å®š å±¬æ€§æ˜ å°„çš„2Må€åŸŸå…§ã€‚ -註： v4.2 之å‰çš„版本åŒæ™‚è¦æ±‚è¨å‚™æ¨¹æ•¸æ“šå¡Šè¢«ç½®æ–¼å¾žå…§æ ¸æ˜ åƒä»¥ä¸‹ +注： v4.2 之å‰çš„版本åŒæ™‚è¦æ±‚è¨å‚™æ¨¹æ•¸æ“šå¡Šè¢«ç½®æ–¼å¾žå…§æ ¸æ˜ åƒä»¥ä¸‹ text_offset å—節處算起第一個 512MB 內。 3ã€è§£å£“å…§æ ¸æ˜ åƒ @@ -106,7 +106,7 @@ AArch64 å…§æ ¸ç•¶å‰æ²’有æä¾›è‡ªè§£å£“ä»£ç¢¼ï¼Œå› æ¤å¦‚果使用了壓縮內 u32 res5; /* ä¿ç•™ （用於 PE COFF å移） */ -æ˜ åƒé 注釋： +æ˜ åƒé 註釋： - 自 v3.17 起，除éžå¦æœ‰èªªæ˜Žï¼Œæ‰€æœ‰åŸŸéƒ½æ˜¯å°ç«¯æ¨¡å¼ã€‚ @@ -143,7 +143,7 @@ AArch64 å…§æ ¸ç•¶å‰æ²’有æä¾›è‡ªè§£å£“ä»£ç¢¼ï¼Œå› æ¤å¦‚果使用了壓縮內 å—節處，並從該處被調用。2MB å°é½ŠåŸºå€å’Œå…§æ ¸æ˜ åƒèµ·å§‹åœ°å€ä¹‹é–“çš„å€åŸŸå°æ–¼ å…§æ ¸ä¾†èªªæ²’æœ‰ç‰¹æ®Šæ„義，且å¯èƒ½è¢«ç”¨æ–¼å…¶ä»–目的。 å¾žæ˜ åƒèµ·å§‹åœ°å€ç®—èµ·ï¼Œæœ€å°‘å¿…é ˆæº–å‚™ image_size å—節的空閒內å˜ä¾›å…§æ ¸ä½¿ç”¨ã€‚ -註： v4.6 之å‰çš„ç‰ˆæœ¬ç„¡æ³•ä½¿ç”¨å…§æ ¸æ˜ åƒç‰©ç†å移以下的內å˜ï¼Œæ‰€ä»¥ç•¶æ™‚å»ºè° +注： v4.6 之å‰çš„ç‰ˆæœ¬ç„¡æ³•ä½¿ç”¨å…§æ ¸æ˜ åƒç‰©ç†å移以下的內å˜ï¼Œæ‰€ä»¥ç•¶æ™‚å»ºè° å°‡æ˜ åƒå„˜é‡æ”¾ç½®åœ¨é 近系統內å˜èµ·å§‹çš„地方。 任何æä¾›çµ¦å…§æ ¸çš„å…§å˜ï¼ˆç”šè‡³åœ¨æ˜ åƒèµ·å§‹åœ°å€ä¹‹å‰ï¼‰ï¼Œè‹¥æœªå¾žå…§æ ¸ä¸æ¨™è¨˜çˆ²ä¿ç•™ @@ -151,7 +151,7 @@ AArch64 å…§æ ¸ç•¶å‰æ²’有æä¾›è‡ªè§£å£“ä»£ç¢¼ï¼Œå› æ¤å¦‚果使用了壓縮內 åœ¨è·³è½‰å…¥å…§æ ¸å‰ï¼Œå¿…é ˆç¬¦åˆä»¥ä¸‹ç‹€æ…‹ï¼š -- åœæ¢æ‰€æœ‰ DMA è¨å‚™ï¼Œé€™æ¨£å…§å˜æ•¸æ“šå°±ä¸æœƒå› 爲虛å‡ç¶²çµ¡åŒ…或ç£ç¢Ÿæ•¸æ“šè€Œ +- åœæ¢æ‰€æœ‰ DMA è¨å‚™ï¼Œé€™æ¨£å…§å˜æ•¸æ“šå°±ä¸æœƒå› 爲虛å‡ç¶²çµ¡åŒ…或ç£ç›¤æ•¸æ“šè€Œ è¢«ç ´å£žã€‚é€™å¯èƒ½å¯ä»¥ç¯€çœä½ 許多的調試時間。 - 主 CPU 通用寄å˜å™¨è¨ç½® @@ -175,7 +175,7 @@ AArch64 å…§æ ¸ç•¶å‰æ²’有æä¾›è‡ªè§£å£“ä»£ç¢¼ï¼Œå› æ¤å¦‚果使用了壓縮內 而ä¸é€šéŽè™›æ“¬åœ°å€æ“作ç¶è·æ§‹æž¶ç·©å˜çš„系統緩å˜ï¼ˆä¸æŽ¨è–¦ï¼‰ï¼Œå¿…é ˆè¢«é…置且 ç¦ç”¨ã€‚ - *è¯è€…註：å°æ–¼ PoC 以åŠç·©å˜ç›¸é—œå…§å®¹ï¼Œè«‹åƒè€ƒ ARMv8 構架åƒè€ƒæ‰‹å†Š + *è¯è€…注：å°æ–¼ PoC 以åŠç·©å˜ç›¸é—œå…§å®¹ï¼Œè«‹åƒè€ƒ ARMv8 構架åƒè€ƒæ‰‹å†Š ARM DDI 0487A - 架構計時器 @@ -189,7 +189,7 @@ AArch64 å…§æ ¸ç•¶å‰æ²’有æä¾›è‡ªè§£å£“ä»£ç¢¼ï¼Œå› æ¤å¦‚果使用了壓縮內 接收。 - 系統寄å˜å™¨ - åœ¨é€²å…¥å…§æ ¸æ˜ åƒçš„異常級ä¸ï¼Œæ‰€æœ‰æ§‹æž¶ä¸å¯å¯«çš„系統寄å˜å™¨å¿…é ˆé€šéŽè»Ÿé«” + åœ¨é€²å…¥å…§æ ¸æ˜ åƒçš„異常級ä¸ï¼Œæ‰€æœ‰æ§‹æž¶ä¸å¯å¯«çš„系統寄å˜å™¨å¿…é ˆé€šéŽè»Ÿä»¶ 在一個更高的異常級別下åˆå§‹åŒ–，以防æ¢åœ¨ 未知 狀態下é‹è¡Œã€‚ å°æ–¼æ“有 GICv3 ä¸æ–·æŽ§åˆ¶å™¨ä¸¦ä»¥ v3 模å¼é‹è¡Œçš„系統： @@ -214,14 +214,14 @@ AArch64 å…§æ ¸ç•¶å‰æ²’有æä¾›è‡ªè§£å£“ä»£ç¢¼ï¼Œå› æ¤å¦‚果使用了壓縮內 引導è£è¼‰ç¨‹åºå¿…é ˆåœ¨æ¯å€‹ CPU è™•æ–¼ä»¥ä¸‹ç‹€æ…‹æ™‚è·³å…¥å…§æ ¸å…¥å£ï¼š - 主 CPU å¿…é ˆç›´æŽ¥è·³å…¥å…§æ ¸æ˜ åƒçš„第一æ¢æŒ‡ä»¤ã€‚通éŽæ¤ CPU 傳éžçš„è¨å‚™æ¨¹ - æ•¸æ“šå¡Šå¿…é ˆåœ¨æ¯å€‹ CPU 節點ä¸åŒ…å«ä¸€å€‹ 『enable-method〠屬性，所 + æ•¸æ“šå¡Šå¿…é ˆåœ¨æ¯å€‹ CPU 節點ä¸åŒ…å«ä¸€å€‹ ‘enable-method’ 屬性，所 支æŒçš„ enable-method 請見下文。 引導è£è¼‰ç¨‹åºå¿…é ˆç”Ÿæˆé€™äº›è¨å‚™æ¨¹å±¬æ€§ï¼Œä¸¦åœ¨è·³å…¥å…§æ ¸å…¥å£ä¹‹å‰å°‡å…¶æ’å…¥ 數據塊。 -- enable-method 爲 「spin-table〠的 CPU å¿…é ˆåœ¨å®ƒå€‘çš„ CPU - 節點ä¸åŒ…å«ä¸€å€‹ 『cpu-release-addr〠屬性。這個屬性標è˜äº†ä¸€å€‹ +- enable-method 爲 “spin-table†的 CPU å¿…é ˆåœ¨å®ƒå€‘çš„ CPU + 節點ä¸åŒ…å«ä¸€å€‹ ‘cpu-release-addr’ 屬性。這個屬性標è˜äº†ä¸€å€‹ 64 ä½è‡ªç„¶å°é½Šä¸”åˆå§‹åŒ–爲零的內å˜ä½ç½®ã€‚ 這些 CPU å¿…é ˆåœ¨å…§å˜ä¿ç•™å€ï¼ˆé€šéŽè¨å‚™æ¨¹ä¸çš„ /memreserve/ åŸŸå‚³éž @@ -231,15 +231,15 @@ AArch64 å…§æ ¸ç•¶å‰æ²’有æä¾›è‡ªè§£å£“ä»£ç¢¼ï¼Œå› æ¤å¦‚果使用了壓縮內 時，CPU å¿…é ˆè·³å…¥æ¤å€¼æ‰€æŒ‡å‘的地å€ã€‚æ¤å€¼çˆ²ä¸€å€‹å–®ç¨çš„ 64 ä½å°ç«¯å€¼ï¼Œ å› æ¤ CPU é ˆåœ¨è·³è½‰å‰å°‡æ‰€è®€å–的值轉æ›çˆ²å…¶æœ¬èº«çš„端模å¼ã€‚ -- enable-method 爲 「psci〠的 CPU ä¿æŒåœ¨å…§æ ¸å¤–（比如，在 +- enable-method 爲 “psci†的 CPU ä¿æŒåœ¨å…§æ ¸å¤–（比如，在 memory 節點ä¸æè¿°çˆ²å…§æ ¸ç©ºé–“çš„å…§å˜å€å¤–，或在通éŽè¨å‚™æ¨¹ /memreserve/ 域ä¸æè¿°çˆ²å…§æ ¸ä¿ç•™å€çš„空間ä¸ï¼‰ã€‚å…§æ ¸å°‡æœƒç™¼èµ·åœ¨ ARM 文檔（編號 - ARM DEN 0022A：用於 ARM 上的電æºç‹€æ…‹å”調接å£ç³»çµ±è»Ÿé«”）ä¸æè¿°çš„ + ARM DEN 0022A：用於 ARM 上的電æºç‹€æ…‹å”調接å£ç³»çµ±è»Ÿä»¶ï¼‰ä¸æè¿°çš„ CPU_ON 調用來將 CPU å¸¶å…¥å…§æ ¸ã€‚ *è¯è€…注: ARM DEN 0022A 已更新到 ARM DEN 0022C。 - è¨å‚™æ¨¹å¿…é ˆåŒ…å«ä¸€å€‹ 『psci〠節點，請åƒè€ƒä»¥ä¸‹æ–‡æª”： + è¨å‚™æ¨¹å¿…é ˆåŒ…å«ä¸€å€‹ ‘psci’ 節點，請åƒè€ƒä»¥ä¸‹æ–‡æª”： Documentation/devicetree/bindings/arm/psci.yaml diff --git a/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst index ca7ff749a67b..d2c1c2f23812 100644 --- a/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst +++ b/Documentation/translations/zh_TW/arch/arm64/elf_hwcaps.rst @@ -17,11 +17,11 @@ ARM64 ELF hwcaps 1. 簡介 ------- -有些硬體或軟體功能僅在æŸäº› CPU 實ç¾ä¸Šå’Œ/或在具體æŸå€‹å…§æ ¸é…置上å¯ç”¨ï¼Œä½† +有些硬件或軟件功能僅在æŸäº› CPU 實ç¾ä¸Šå’Œ/或在具體æŸå€‹å…§æ ¸é…置上å¯ç”¨ï¼Œä½† å°æ–¼è™•æ–¼ EL0 的用戶空間代碼沒有å¯ç”¨çš„架構發ç¾æ©Ÿåˆ¶ã€‚å…§æ ¸é€šéŽåœ¨è¼”助å‘é‡è¡¨ 公開一組稱爲 hwcaps 的標誌而把這些功能暴露給用戶空間。 -用戶空間軟體å¯ä»¥é€šéŽç²å–輔助å‘é‡çš„ AT_HWCAP 或 AT_HWCAP2 æ¢ç›®ä¾†æ¸¬è©¦åŠŸèƒ½ï¼Œ +用戶空間軟件å¯ä»¥é€šéŽç²å–輔助å‘é‡çš„ AT_HWCAP 或 AT_HWCAP2 æ¢ç›®ä¾†æ¸¬è©¦åŠŸèƒ½ï¼Œ 並測試是å¦è¨ç½®äº†ç›¸é—œæ¨™èªŒï¼Œä¾‹å¦‚:: bool floating_point_is_present(void) @@ -33,7 +33,7 @@ ARM64 ELF hwcaps return false; } -如果軟體ä¾è³´æ–¼ hwcap æ述的功能，在嘗試使用該功能å‰å‰‡æ‡‰æª¢æŸ¥ç›¸é—œçš„ hwcap +如果軟件ä¾è³´æ–¼ hwcap æ述的功能，在嘗試使用該功能å‰å‰‡æ‡‰æª¢æŸ¥ç›¸é—œçš„ hwcap 標誌以驗è‰è©²åŠŸèƒ½æ˜¯å¦å˜åœ¨ã€‚ ä¸èƒ½é€šéŽå…¶ä»–æ–¹å¼æŽ¢æŸ¥é€™äº›åŠŸèƒ½ã€‚當一個功能ä¸å¯ç”¨æ™‚，嘗試使用它å¯èƒ½å°Žè‡´ä¸å¯ @@ -44,8 +44,8 @@ ARM64 ELF hwcaps ---------------- 大多數 hwcaps 旨在說明通éŽæž¶æ§‹ ID 寄å˜å™¨(處於 EL0 的用戶空間代碼無法訪å•) -æ述的功能的å˜åœ¨ã€‚這些 hwcap é€šéŽ ID 寄å˜å™¨æ¬„ä½å®šç¾©ï¼Œä¸¦ä¸”æ‡‰æ ¹æ“š ARM 體系 -çµæ§‹åƒè€ƒæ‰‹å†Šï¼ˆARM ARM）ä¸å®šç¾©çš„欄ä½ä¾†è§£é‡‹èªªæ˜Žã€‚ +æ述的功能的å˜åœ¨ã€‚這些 hwcap é€šéŽ ID 寄å˜å™¨å—æ®µå®šç¾©ï¼Œä¸¦ä¸”æ‡‰æ ¹æ“š ARM 體系 +çµæ§‹åƒè€ƒæ‰‹å†Šï¼ˆARM ARM）ä¸å®šç¾©çš„å—段來解釋說明。 這些 hwcaps 以下é¢çš„å½¢å¼æè¿°:: diff --git a/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt index c2d02cd5017d..7d1f0593d7ca 100644 --- a/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt +++ b/Documentation/translations/zh_TW/arch/arm64/legacy_instructions.txt @@ -31,7 +31,7 @@ Documentation/arch/arm64/legacy_instructions.rst çš„ä¸æ–‡ç¿»è¯ 以下爲æ£æ–‡ --------------------------------------------------------------------- Linux å…§æ ¸åœ¨ arm64 上的移æ¤æ供了一個基礎框架，以支æŒæ§‹æž¶ä¸æ£åœ¨è¢«æ·˜æ±°æˆ–已廢棄指令的模擬執行。 -這個基礎框架的代碼使用未定義指令鉤å（hooks）來支æŒæ¨¡æ“¬ã€‚如果指令å˜åœ¨ï¼Œå®ƒä¹Ÿå…許在硬體ä¸å•“用該指令。 +這個基礎框架的代碼使用未定義指令鉤å（hooks）來支æŒæ¨¡æ“¬ã€‚如果指令å˜åœ¨ï¼Œå®ƒä¹Ÿå…許在硬件ä¸å•“用該指令。 模擬模å¼å¯é€šéŽå¯« sysctl 節點（/proc/sys/abi）來控制。 ä¸åŒçš„執行方å¼åŠ sysctl 節點的相應值，解釋如下： @@ -42,18 +42,18 @@ Linux å…§æ ¸åœ¨ arm64 上的移æ¤æ供了一個基礎框架，以支æŒæ§‹æž¶ä * Emulate（模擬） 值： 1 - 使用軟體模擬方å¼ã€‚爲解決軟體é·ç§»å•é¡Œï¼Œé€™ç¨®æ¨¡æ“¬æŒ‡ä»¤æ¨¡å¼çš„使用是被跟蹤的，並會發出速率é™åˆ¶è¦å‘Šã€‚ + 使用軟件模擬方å¼ã€‚爲解決軟件é·ç§»å•é¡Œï¼Œé€™ç¨®æ¨¡æ“¬æŒ‡ä»¤æ¨¡å¼çš„使用是被跟蹤的，並會發出速率é™åˆ¶è¦å‘Šã€‚ 它是那些構架ä¸æ£åœ¨è¢«æ·˜æ±°çš„指令，如 CP15 barriers（隔離指令），的默èªè™•ç†æ–¹å¼ã€‚ -* Hardware Execution（硬體執行） +* Hardware Execution（硬件執行） 值： 2 - 雖然標記爲æ£åœ¨è¢«æ·˜æ±°ï¼Œä½†ä¸€äº›å¯¦ç¾å¯èƒ½æ供硬體執行這些指令的使能/ç¦ç”¨æ“作。 - 使用硬體執行一般會有更好的性能，但將無法收集é‹è¡Œæ™‚å°æ£è¢«æ·˜æ±°æŒ‡ä»¤çš„使用統計數據。 + 雖然標記爲æ£åœ¨è¢«æ·˜æ±°ï¼Œä½†ä¸€äº›å¯¦ç¾å¯èƒ½æ供硬件執行這些指令的使能/ç¦ç”¨æ“作。 + 使用硬件執行一般會有更好的性能，但將無法收集é‹è¡Œæ™‚å°æ£è¢«æ·˜æ±°æŒ‡ä»¤çš„使用統計數據。 默èªåŸ·è¡Œæ¨¡å¼ä¾è³´æ–¼æŒ‡ä»¤åœ¨æ§‹æž¶ä¸ç‹€æ…‹ã€‚æ£åœ¨è¢«æ·˜æ±°çš„指令應該以模擬（Emulate）作爲默èªæ¨¡å¼ï¼Œ è€Œå·²å»¢æ£„çš„æŒ‡ä»¤å¿…é ˆé»˜èªä½¿ç”¨æœªå®šç¾©ï¼ˆUndefï¼‰æ¨¡å¼ -注æ„：指令模擬å¯èƒ½ç„¡æ³•æ‡‰å°æ‰€æœ‰æƒ…æ³ã€‚更多詳情請åƒè€ƒå–®ç¨çš„指令注釋。 +注æ„：指令模擬å¯èƒ½ç„¡æ³•æ‡‰å°æ‰€æœ‰æƒ…æ³ã€‚更多詳情請åƒè€ƒå–®ç¨çš„指令註釋。 å—支æŒçš„éºç•™æŒ‡ä»¤ ------------- @@ -71,7 +71,7 @@ Linux å…§æ ¸åœ¨ arm64 上的移æ¤æ供了一個基礎框架，以支æŒæ§‹æž¶ä 節點: /proc/sys/abi/setend 狀態: æ£è¢«æ·˜æ±°ï¼Œä¸æŽ¨è–¦ä½¿ç”¨ 默èªåŸ·è¡Œæ–¹å¼: Emulate (1)* -註：爲了使能這個特性，系統ä¸çš„所有 CPU å¿…é ˆåœ¨ EL0 支æŒæ··åˆå—節åºã€‚ +注：爲了使能這個特性，系統ä¸çš„所有 CPU å¿…é ˆåœ¨ EL0 支æŒæ··åˆå—節åºã€‚ 如果一個新的 CPU （ä¸æ”¯æŒæ··åˆå—節åºï¼‰ 在使能這個特性後被熱æ’入系統， 在應用ä¸å¯èƒ½æœƒå‡ºç¾ä¸å¯é 期的çµæžœã€‚ diff --git a/Documentation/translations/zh_TW/arch/arm64/memory.txt b/Documentation/translations/zh_TW/arch/arm64/memory.txt index 0280200e791f..e41c518e71c6 100644 --- a/Documentation/translations/zh_TW/arch/arm64/memory.txt +++ b/Documentation/translations/zh_TW/arch/arm64/memory.txt @@ -28,17 +28,17 @@ Documentation/arch/arm64/memory.rst çš„ä¸æ–‡ç¿»è¯ 以下爲æ£æ–‡ --------------------------------------------------------------------- - Linux 在 AArch64 ä¸çš„å…§å˜å¸ƒå±€ + Linux 在 AArch64 ä¸çš„å…§å˜ä½ˆå±€ =========================== 作者: Catalin Marinas <catalin.marinas@arm.com> -本文檔æè¿° AArch64 Linux å…§æ ¸æ‰€ä½¿ç”¨çš„è™›æ“¬å…§å˜å¸ƒå±€ã€‚æ¤æ§‹æž¶å¯ä»¥å¯¦ç¾ +本文檔æè¿° AArch64 Linux å…§æ ¸æ‰€ä½¿ç”¨çš„è™›æ“¬å…§å˜ä½ˆå±€ã€‚æ¤æ§‹æž¶å¯ä»¥å¯¦ç¾ é 大å°çˆ² 4KB çš„ 4 級轉æ›è¡¨å’Œé 大å°çˆ² 64KB çš„ 3 級轉æ›è¡¨ã€‚ AArch64 Linux 使用 3 級或 4 級轉æ›è¡¨ï¼Œå…¶é 大å°é…置爲 4KB，å°æ–¼ç”¨æˆ¶å’Œå…§æ ¸ 分別都有 39-bit (512GB) 或 48-bit (256TB) 的虛擬地å€ç©ºé–“。 -å°æ–¼é 大å°çˆ² 64KBçš„é…置，僅使用 2 級轉æ›è¡¨ï¼Œæœ‰ 42-bit (4TB) 的虛擬地å€ç©ºé–“，但內å˜å¸ƒå±€ç›¸åŒã€‚ +å°æ–¼é 大å°çˆ² 64KBçš„é…置，僅使用 2 級轉æ›è¡¨ï¼Œæœ‰ 42-bit (4TB) 的虛擬地å€ç©ºé–“，但內å˜ä½ˆå±€ç›¸åŒã€‚ 用戶地å€ç©ºé–“çš„ 63:48 ä½çˆ² 0ï¼Œè€Œå…§æ ¸åœ°å€ç©ºé–“的相應ä½çˆ² 1。TTBRx çš„ é¸æ“‡ç”±è™›æ“¬åœ°å€çš„ 63 ä½çµ¦å‡ºã€‚swapper_pg_dir 僅包å«å…§æ ¸ï¼ˆå…¨å±€ï¼‰æ˜ 射， @@ -46,7 +46,7 @@ AArch64 Linux 使用 3 級或 4 級轉æ›è¡¨ï¼Œå…¶é 大å°é…置爲 4KB，å°æ– TTBR1 ä¸ï¼Œä¸”從ä¸å¯«å…¥ TTBR0。 -AArch64 Linux 在é 大å°çˆ² 4KB，並使用 3 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï¼š +AArch64 Linux 在é 大å°çˆ² 4KB，並使用 3 級轉æ›è¡¨æ™‚çš„å…§å˜ä½ˆå±€ï¼š èµ·å§‹åœ°å€ çµæŸåœ°å€ å¤§å° ç”¨é€” ----------------------------------------------------------------------- @@ -54,7 +54,7 @@ AArch64 Linux 在é 大å°çˆ² 4KB，並使用 3 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï¼ ffffff8000000000 ffffffffffffffff 512GB å…§æ ¸ç©ºé–“ -AArch64 Linux 在é 大å°çˆ² 4KB，並使用 4 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï¼š +AArch64 Linux 在é 大å°çˆ² 4KB，並使用 4 級轉æ›è¡¨æ™‚çš„å…§å˜ä½ˆå±€ï¼š èµ·å§‹åœ°å€ çµæŸåœ°å€ å¤§å° ç”¨é€” ----------------------------------------------------------------------- @@ -62,7 +62,7 @@ AArch64 Linux 在é 大å°çˆ² 4KB，並使用 4 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï¼ ffff000000000000 ffffffffffffffff 256TB å…§æ ¸ç©ºé–“ -AArch64 Linux 在é 大å°çˆ² 64KB，並使用 2 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï¼š +AArch64 Linux 在é 大å°çˆ² 64KB，並使用 2 級轉æ›è¡¨æ™‚çš„å…§å˜ä½ˆå±€ï¼š èµ·å§‹åœ°å€ çµæŸåœ°å€ å¤§å° ç”¨é€” ----------------------------------------------------------------------- @@ -70,7 +70,7 @@ AArch64 Linux 在é 大å°çˆ² 64KB，並使用 2 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï fffffc0000000000 ffffffffffffffff 4TB å…§æ ¸ç©ºé–“ -AArch64 Linux 在é 大å°çˆ² 64KB，並使用 3 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï¼š +AArch64 Linux 在é 大å°çˆ² 64KB，並使用 3 級轉æ›è¡¨æ™‚çš„å…§å˜ä½ˆå±€ï¼š èµ·å§‹åœ°å€ çµæŸåœ°å€ å¤§å° ç”¨é€” ----------------------------------------------------------------------- @@ -78,7 +78,7 @@ AArch64 Linux 在é 大å°çˆ² 64KB，並使用 3 級轉æ›è¡¨æ™‚çš„å…§å˜å¸ƒå±€ï ffff000000000000 ffffffffffffffff 256TB å…§æ ¸ç©ºé–“ -æ›´è©³ç´°çš„å…§æ ¸è™›æ“¬å…§å˜å¸ƒå±€ï¼Œè«‹åƒé–±å…§æ ¸å•“å‹•ä¿¡æ¯ã€‚ +æ›´è©³ç´°çš„å…§æ ¸è™›æ“¬å…§å˜ä½ˆå±€ï¼Œè«‹åƒé–±å…§æ ¸å•“å‹•ä¿¡æ¯ã€‚ 4KB é 大å°çš„轉æ›è¡¨æŸ¥æ‰¾ï¼š diff --git a/Documentation/translations/zh_TW/arch/arm64/perf.rst b/Documentation/translations/zh_TW/arch/arm64/perf.rst index 645f3944a0f4..405d5f66964f 100644 --- a/Documentation/translations/zh_TW/arch/arm64/perf.rst +++ b/Documentation/translations/zh_TW/arch/arm64/perf.rst @@ -59,7 +59,7 @@ EL2（VHE å…§æ ¸ 或 non-VHE 虛擬機監控器）。 KVM 客戶機å¯èƒ½é‹è¡Œåœ¨ EL0（用戶空間）和 EL1ï¼ˆå…§æ ¸ï¼‰ã€‚ -由於宿主機和客戶機之間é‡ç–Šçš„異常級別，我們ä¸èƒ½åƒ…僅ä¾é PMU 的硬體異 +由於宿主機和客戶機之間é‡ç–Šçš„異常級別，我們ä¸èƒ½åƒ…僅ä¾é PMU 的硬件異 常éŽæ¿¾æ©Ÿåˆ¶-å› æ¤æˆ‘å€‘å¿…é ˆå•“ç”¨/ç¦ç”¨å°æ–¼å®¢æˆ¶æ©Ÿé€²å…¥å’Œé€€å‡ºçš„計數。而這在 VHE å’Œ non-VHE 系統上表ç¾ä¸åŒã€‚ diff --git a/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt index f6f41835a54a..70371807ca83 100644 --- a/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt +++ b/Documentation/translations/zh_TW/arch/arm64/silicon-errata.txt @@ -28,39 +28,39 @@ Documentation/arch/arm64/silicon-errata.rst çš„ä¸æ–‡ç¿»è¯ 以下爲æ£æ–‡ --------------------------------------------------------------------- - 晶片勘誤和軟體補救措施 + 芯片勘誤和軟件補救措施 ================== 作者: Will Deacon <will.deacon@arm.com> 日期: 2015å¹´11月27æ—¥ -一個ä¸å¹¸çš„ç¾å¯¦ï¼šç¡¬é«”經常帶有一些所謂的「瑕疵（errata）ã€ï¼Œå°Žè‡´å…¶åœ¨ -æŸäº›ç‰¹å®šæƒ…æ³ä¸‹æœƒé•èƒŒæ§‹æž¶å®šç¾©çš„行爲。就基於 ARM 的硬體而言，這些瑕疵 +一個ä¸å¹¸çš„ç¾å¯¦ï¼šç¡¬ä»¶ç¶“常帶有一些所謂的“瑕疵（errata）â€ï¼Œå°Žè‡´å…¶åœ¨ +æŸäº›ç‰¹å®šæƒ…æ³ä¸‹æœƒé•èƒŒæ§‹æž¶å®šç¾©çš„行爲。就基於 ARM 的硬件而言，這些瑕疵 大體å¯åˆ†çˆ²ä»¥ä¸‹å¹¾é¡žï¼š A 類：無å¯è¡Œè£œæ•‘措施的嚴é‡ç¼ºé™·ã€‚ B 類：有å¯æŽ¥å—的補救措施的é‡å¤§æˆ–åš´é‡ç¼ºé™·ã€‚ C 類：在æ£å¸¸æ“作ä¸ä¸æœƒé¡¯ç¾çš„å°ç‘•ç–µã€‚ -更多資訊，請在 infocenter.arm.com （需註冊）ä¸æŸ¥é–±ã€Œè»Ÿé«”開發者勘誤 -ç†è¨˜ã€ï¼ˆã€ŒSoftware Developers Errata Noticeã€ï¼‰æ–‡æª”。 +更多資訊，請在 infocenter.arm.com （需註冊）ä¸æŸ¥é–±â€œè»Ÿä»¶é–‹ç™¼è€…勘誤 +ç†è¨˜â€ï¼ˆâ€œSoftware Developers Errata Noticeâ€ï¼‰æ–‡æª”。 -å°æ–¼ Linux 而言，B 類缺陷å¯èƒ½éœ€è¦ä½œæ¥ç³»çµ±çš„æŸäº›ç‰¹åˆ¥è™•ç†ã€‚例如，é¿å… +å°æ–¼ Linux 而言，B 類缺陷å¯èƒ½éœ€è¦æ“作系統的æŸäº›ç‰¹åˆ¥è™•ç†ã€‚例如，é¿å… 一個特殊的代碼åºåˆ—，或是以一種特定的方å¼é…置處ç†å™¨ã€‚在æŸç¨®ä¸å¤ªå¸¸è¦‹çš„ 情æ³ä¸‹ï¼Œçˆ²å°‡ A 類缺陷當作 C 類處ç†ï¼Œå¯èƒ½éœ€è¦ç”¨é¡žä¼¼çš„手段。這些手段被 -統稱爲「軟體補救措施ã€ï¼Œä¸”僅在少數情æ³éœ€è¦ï¼ˆä¾‹å¦‚，那些需è¦ä¸€å€‹é‹è¡Œåœ¨ +統稱爲“軟件補救措施â€ï¼Œä¸”僅在少數情æ³éœ€è¦ï¼ˆä¾‹å¦‚，那些需è¦ä¸€å€‹é‹è¡Œåœ¨ éžå®‰å…¨ç•°å¸¸ç´šçš„補救措施 *並且* 能被 Linux 觸發的情æ³ï¼‰ã€‚ -å°æ–¼å°šåœ¨è¨Žè«–ä¸çš„å¯èƒ½å°æœªå—瑕疵影響的系統產生干擾的軟體補救措施，有一個 -ç›¸æ‡‰çš„å…§æ ¸é…置（Kconfig）é¸é …è¢«åŠ åœ¨ ã€Œå…§æ ¸ç‰¹æ€§ï¼ˆKernel Features）ã€-> -「基於å¯é¸æ–¹æ³•æ¡†æž¶çš„ ARM 瑕疵補救措施（ARM errata workarounds via +å°æ–¼å°šåœ¨è¨Žè«–ä¸çš„å¯èƒ½å°æœªå—瑕疵影響的系統產生干擾的軟件補救措施，有一個 +ç›¸æ‡‰çš„å…§æ ¸é…置（Kconfig）é¸é …è¢«åŠ åœ¨ â€œå…§æ ¸ç‰¹æ€§ï¼ˆKernel Features）â€-> +“基於å¯é¸æ–¹æ³•æ¡†æž¶çš„ ARM 瑕疵補救措施（ARM errata workarounds via the alternatives framework）"。這些é¸é …被默èªé–‹å•“，若探測到å—影響的CPU， 補ä¸å°‡åœ¨é‹è¡Œæ™‚被使用。至於å°ç³»çµ±é‹è¡Œå½±éŸ¿è¼ƒå°çš„è£œæ•‘æŽªæ–½ï¼Œå…§æ ¸é…ç½®é¸é … -並ä¸å˜åœ¨ï¼Œä¸”代碼以æŸç¨®è¦é¿ç‘•ç–µçš„æ–¹å¼è¢«æ§‹é€ （帶注釋爲宜）。 +並ä¸å˜åœ¨ï¼Œä¸”代碼以æŸç¨®è¦é¿ç‘•ç–µçš„æ–¹å¼è¢«æ§‹é€ （帶註釋爲宜）。 -這種åšæ³•å°æ–¼åœ¨ä»»æ„å…§æ ¸åŽŸå§‹ç¢¼æ¨¹ä¸æº–確地判斷出哪個瑕疵已被軟體方法所補救 -ç¨å¾®æœ‰é»žéº»ç…©ï¼Œæ‰€ä»¥åœ¨ Linux å…§æ ¸ä¸æ¤æ–‡ä»¶ä½œçˆ²è»Ÿé«”補救措施的註冊表， -並將在新的軟體補救措施被æ交和å‘後移æ¤ï¼ˆbackportedï¼‰åˆ°ç©©å®šå…§æ ¸æ™‚è¢«æ›´æ–°ã€‚ +這種åšæ³•å°æ–¼åœ¨ä»»æ„å…§æ ¸æºä»£ç¢¼æ¨¹ä¸æº–確地判斷出哪個瑕疵已被軟件方法所補救 +ç¨å¾®æœ‰é»žéº»ç…©ï¼Œæ‰€ä»¥åœ¨ Linux å…§æ ¸ä¸æ¤æ–‡ä»¶ä½œçˆ²è»Ÿä»¶è£œæ•‘措施的註冊表， +並將在新的軟件補救措施被æ交和å‘後移æ¤ï¼ˆbackportedï¼‰åˆ°ç©©å®šå…§æ ¸æ™‚è¢«æ›´æ–°ã€‚ | 實ç¾è€… | å—影響的組件 | 勘誤編號 | å…§æ ¸é…ç½® | +----------------+-----------------+-----------------+-------------------------+ diff --git a/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt index c0be1d1e0d01..9812d99549ba 100644 --- a/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt +++ b/Documentation/translations/zh_TW/arch/arm64/tagged-pointers.txt @@ -36,14 +36,14 @@ Documentation/arch/arm64/tagged-pointers.rst çš„ä¸æ–‡ç¿»è¯ AArch64 Linux ä¸çš„潛在用途。 å…§æ ¸æ供的地å€è½‰æ›è¡¨é…ç½®ä½¿é€šéŽ TTBR0 完æˆçš„虛擬地å€è½‰æ›ï¼ˆå³ç”¨æˆ¶ç©ºé–“ -æ˜ å°„ï¼‰ï¼Œå…¶è™›æ“¬åœ°å€çš„最高 8 ä½ï¼ˆ63:56）會被轉æ›ç¡¬é«”所忽略。這種機制 -讓這些ä½å¯ä¾›æ‡‰ç”¨ç¨‹å¼è‡ªç”±ä½¿ç”¨ï¼Œå…¶æ³¨æ„äº‹é …å¦‚ä¸‹ï¼š +æ˜ å°„ï¼‰ï¼Œå…¶è™›æ“¬åœ°å€çš„最高 8 ä½ï¼ˆ63:56）會被轉æ›ç¡¬ä»¶æ‰€å¿½ç•¥ã€‚這種機制 +讓這些ä½å¯ä¾›æ‡‰ç”¨ç¨‹åºè‡ªç”±ä½¿ç”¨ï¼Œå…¶æ³¨æ„äº‹é …å¦‚ä¸‹ï¼š (1) å…§æ ¸è¦æ±‚所有傳éžåˆ° EL1 的用戶空間地å€å¸¶æœ‰ 0x00 標記。 - 這æ„味著任何攜帶用戶空間虛擬地å€çš„系統調用（syscall） + 這æ„味ç€ä»»ä½•æ”œå¸¶ç”¨æˆ¶ç©ºé–“虛擬地å€çš„系統調用（syscall） åƒæ•¸ *å¿…é ˆ* åœ¨é™·å…¥å…§æ ¸å‰ä½¿å®ƒå€‘的最高å—節被清零。 - (2) éžé›¶æ¨™è¨˜åœ¨å‚³éžä¿¡è™Ÿæ™‚ä¸è¢«ä¿å˜ã€‚這æ„味著在應用程å¼ä¸åˆ©ç”¨äº† + (2) éžé›¶æ¨™è¨˜åœ¨å‚³éžä¿¡è™Ÿæ™‚ä¸è¢«ä¿å˜ã€‚這æ„味ç€åœ¨æ‡‰ç”¨ç¨‹åºä¸åˆ©ç”¨äº† 標記的信號處ç†å‡½æ•¸ç„¡æ³•ä¾è³´ siginfo_t 的用戶空間虛擬 地å€æ‰€æ”œå¸¶çš„包å«å…¶å…§éƒ¨åŸŸä¿¡æ¯çš„標記。æ¤è¦å‰‡çš„一個例外是 當信號是在調試觀察點的異常處ç†ç¨‹åºä¸ç”¢ç”Ÿçš„，æ¤æ™‚標記的 @@ -53,5 +53,5 @@ AArch64 Linux ä¸çš„潛在用途。 的高å—節，C ç·¨è¯å™¨å¾ˆå¯èƒ½ç„¡æ³•åˆ¤æ–·å®ƒå€‘是ä¸åŒçš„。 æ¤æ§‹æž¶æœƒé˜»æ¢å°å¸¶æ¨™è¨˜çš„ PC 指é‡çš„åˆ©ç”¨ï¼Œå› æ¤åœ¨ç•°å¸¸è¿”回時，其高å—節 -將被è¨ç½®æˆä¸€å€‹çˆ² 「55〠的擴展符。 +將被è¨ç½®æˆä¸€å€‹çˆ² “55†的擴展符。 diff --git a/Documentation/translations/zh_TW/arch/index.rst b/Documentation/translations/zh_TW/arch/index.rst new file mode 100644 index 000000000000..7c0490589465 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/index.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +處ç†å™¨é«”ç³»çµæ§‹ +============== + +以下文檔æ供了具體架構實ç¾çš„編程細節。 + +.. toctree:: + :maxdepth: 2 + + mips/index + arm64/index + openrisc/index + parisc/index + loongarch/index + +TODOList: + +* arm/index +* m68k/index +* nios2/index +* powerpc/index +* s390/index +* sh/index +* sparc/index +* x86/index +* xtensa/index +* ../riscv/index + diff --git a/Documentation/translations/zh_TW/arch/loongarch/booting.rst b/Documentation/translations/zh_TW/arch/loongarch/booting.rst new file mode 100644 index 000000000000..88291090cea1 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/booting.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/booting.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +==================== +å•“å‹• Linux/LoongArch +==================== + +:作者: å¸å»¶é¨° <siyanteng@loongson.cn> +:日期: 2022å¹´11月18æ—¥ + +BootLoader傳éžçµ¦å…§æ ¸çš„ä¿¡æ¯ +========================== + +LoongArch支æŒACPIå’ŒFDT啓動，需è¦å‚³éžçµ¦å…§æ ¸çš„ä¿¡æ¯åŒ…括memmapã€initrdã€cmdlineã€å¯ +é¸çš„ACPI/FDT表ç‰ã€‚ + +å…§æ ¸åœ¨ `kernel_entry` å…¥å£è™•è¢«å‚³éžä»¥ä¸‹åƒæ•¸: + + - a0 = efi_boot: `efi_boot` 是一個標誌，表示這個啓動環境是å¦å®Œå…¨ç¬¦åˆUEFI + çš„è¦æ±‚。 + + - a1 = cmdline: `cmdline` 是一個指å‘å…§æ ¸å‘½ä»¤è¡Œçš„æŒ‡é‡ã€‚ + + - a2 = systemtable: `systemtable` 指å‘EFI的系統表，在這個階段涉åŠçš„所有 + 指é‡éƒ½æ˜¯ç‰©ç†åœ°å€ã€‚ + +Linux/LoongArchå…§æ ¸é¡åƒæ–‡ä»¶é +============================= + +å…§æ ¸é¡åƒæ˜¯EFIé¡åƒã€‚作爲PE文件，它們有一個64å—節的é 部çµæ§‹é«”，如下所示:: + + u32 MZ_MAGIC /* "MZ", MS-DOS é */ + u32 res0 = 0 /* ä¿ç•™ */ + u64 kernel_entry /* å…§æ ¸å…¥å£é»ž */ + u64 _end - _text /* å…§æ ¸é¡åƒæœ‰æ•ˆå¤§å° */ + u64 load_offset /* åŠ è¼‰å…§æ ¸é¡åƒç›¸å°å…§å˜èµ·å§‹åœ°å€çš„åç§»é‡ */ + u64 res1 = 0 /* ä¿ç•™ */ + u64 res2 = 0 /* ä¿ç•™ */ + u64 res3 = 0 /* ä¿ç•™ */ + u32 LINUX_PE_MAGIC /* é”術數 */ + u32 pe_header - _head /* 到PEé çš„åç§»é‡ */ + diff --git a/Documentation/translations/zh_TW/arch/loongarch/features.rst b/Documentation/translations/zh_TW/arch/loongarch/features.rst new file mode 100644 index 000000000000..b64e430f55ae --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/features.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/features.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +.. kernel-feat:: $srctree/Documentation/features loongarch + diff --git a/Documentation/translations/zh_TW/arch/loongarch/index.rst b/Documentation/translations/zh_TW/arch/loongarch/index.rst new file mode 100644 index 000000000000..7281e050fe1c --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/index.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +================= +LoongArch體系çµæ§‹ +================= + +.. toctree:: + :maxdepth: 2 + :numbered: + + introduction + booting + irq-chip-model + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/loongarch/introduction.rst b/Documentation/translations/zh_TW/arch/loongarch/introduction.rst new file mode 100644 index 000000000000..a5603f9b0a1b --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/introduction.rst @@ -0,0 +1,354 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/introduction.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +============= +LoongArch介紹 +============= + +LoongArch是一種新的RISC ISA，在一定程度上類似於MIPSå’ŒRISC-V。LoongArch指令集 +包括一個精簡32ä½ç‰ˆï¼ˆLA32R）ã€ä¸€å€‹æ¨™æº–32ä½ç‰ˆï¼ˆLA32S）ã€ä¸€å€‹64ä½ç‰ˆï¼ˆLA64）。 +LoongArch定義了四個特權級（PLV0~PLV3），其ä¸PLV0æ˜¯æœ€é«˜ç‰¹æ¬Šç´šï¼Œç”¨æ–¼å…§æ ¸ï¼›è€ŒPLV3 +是最低特權級，用於應用程åºã€‚本文檔介紹了LoongArch的寄å˜å™¨ã€åŸºç¤ŽæŒ‡ä»¤é›†ã€è™›æ“¬å…§ +å˜ä»¥åŠå…¶ä»–一些主題。 + +寄å˜å™¨ +====== + +LoongArch的寄å˜å™¨åŒ…括通用寄å˜å™¨ï¼ˆGPRs）ã€æµ®é»žå¯„å˜å™¨ï¼ˆFPRs）ã€å‘é‡å¯„å˜å™¨ï¼ˆVRs） +和用於特權模å¼ï¼ˆPLV0）的控制狀態寄å˜å™¨ï¼ˆCSRs）。 + +通用寄å˜å™¨ +---------- + +LoongArch包括32個通用寄å˜å™¨ï¼ˆ ``$r0`` ~ ``$r31`` ），LA32ä¸æ¯å€‹å¯„å˜å™¨çˆ²32ä½å¯¬ï¼Œ +LA64ä¸æ¯å€‹å¯„å˜å™¨çˆ²64ä½å¯¬ã€‚ ``$r0`` 的內容總是固定爲0，而其他寄å˜å™¨åœ¨é«”ç³»çµæ§‹å±¤é¢ +沒有特殊功能。（ ``$r1`` 算是一個例外，在BL指令ä¸å›ºå®šç”¨ä½œéˆæŽ¥è¿”回寄å˜å™¨ã€‚） + +å…§æ ¸ä½¿ç”¨äº†ä¸€å¥—LoongArch寄å˜å™¨ç´„定，定義在LoongArch ELF psABIè¦ç¯„ä¸ï¼Œè©³ç´°æè¿°åƒè¦‹ +:ref:`åƒè€ƒæ–‡ç» <loongarch-references-zh_TW>`: + +================= =============== =================== ========== +寄å˜å™¨å 別å 用途 跨調用ä¿æŒ +================= =============== =================== ========== +``$r0`` ``$zero`` 常é‡0 ä¸ä½¿ç”¨ +``$r1`` ``$ra`` è¿”å›žåœ°å€ å¦ +``$r2`` ``$tp`` TLS/線程信æ¯æŒ‡é‡ ä¸ä½¿ç”¨ +``$r3`` ``$sp`` æ£§æŒ‡é‡ æ˜¯ +``$r4``-``$r11`` ``$a0``-``$a7`` åƒæ•¸å¯„å˜å™¨ å¦ +``$r4``-``$r5`` ``$v0``-``$v1`` 返回值 å¦ +``$r12``-``$r20`` ``$t0``-``$t8`` 臨時寄å˜å™¨ å¦ +``$r21`` ``$u0`` æ¯CPU變é‡åŸºåœ°å€ ä¸ä½¿ç”¨ +``$r22`` ``$fp`` å¹€æŒ‡é‡ æ˜¯ +``$r23``-``$r31`` ``$s0``-``$s8`` éœæ…‹å¯„å˜å™¨ 是 +================= =============== =================== ========== + +.. note:: + 注æ„： ``$r21`` 寄å˜å™¨åœ¨ELF psABIä¸ä¿ç•™æœªä½¿ç”¨ï¼Œä½†æ˜¯åœ¨Linuxå…§æ ¸ç”¨æ–¼ä¿ + å˜æ¯CPU變é‡åŸºåœ°å€ã€‚該寄å˜å™¨æ²’有ABI命å，ä¸éŽåœ¨å…§æ ¸ä¸ç¨±çˆ² ``$u0`` 。在 + 一些éºç•™ä»£ç¢¼ä¸æœ‰æ™‚å¯èƒ½è¦‹åˆ° ``$v0`` å’Œ ``$v1`` ，它們是 ``$a0`` å’Œ + ``$a1`` 的別å，屬於已經廢棄的用法。 + +浮點寄å˜å™¨ +---------- + +當系統ä¸å˜åœ¨FPU時，LoongArch有32個浮點寄å˜å™¨ï¼ˆ ``$f0`` ~ ``$f31`` ）。在LA64 +çš„CPUæ ¸ä¸Šï¼Œæ¯å€‹å¯„å˜å™¨å‡çˆ²64ä½å¯¬ã€‚ + +浮點寄å˜å™¨çš„使用約定與LoongArch ELF psABIè¦ç¯„çš„æ述相åŒï¼š + +================= ================== =================== ========== +寄å˜å™¨å 別å 用途 跨調用ä¿æŒ +================= ================== =================== ========== +``$f0``-``$f7`` ``$fa0``-``$fa7`` åƒæ•¸å¯„å˜å™¨ å¦ +``$f0``-``$f1`` ``$fv0``-``$fv1`` 返回值 å¦ +``$f8``-``$f23`` ``$ft0``-``$ft15`` 臨時寄å˜å™¨ å¦ +``$f24``-``$f31`` ``$fs0``-``$fs7`` éœæ…‹å¯„å˜å™¨ 是 +================= ================== =================== ========== + +.. note:: + 注æ„：在一些éºç•™ä»£ç¢¼ä¸æœ‰æ™‚å¯èƒ½è¦‹åˆ° ``$fv0`` å’Œ ``$fv1`` ，它們是 + ``$fa0`` å’Œ ``$fa1`` 的別å，屬於已經廢棄的用法。 + + +å‘é‡å¯„å˜å™¨ +---------- + +LoongArchç¾æœ‰å…©ç¨®å‘é‡æ“´å±•ï¼š + +- 128ä½å‘é‡æ“´å±•LSX（全稱Loongson SIMD eXtention）， +- 256ä½å‘é‡æ“´å±•LASX（全稱Loongson Advanced SIMD eXtention）。 + +LSX使用 ``$v0`` ~ ``$v31`` å‘é‡å¯„å˜å™¨ï¼Œè€ŒLASX則使用 ``$x0`` ~ ``$x31`` 。 + +浮點寄å˜å™¨å’Œå‘é‡å¯„å˜å™¨æ˜¯è¤‡ç”¨çš„，比如：在一個實ç¾äº†LSXå’ŒLASXçš„æ ¸ä¸Šï¼Œ ``$x0`` çš„ +低128ä½èˆ‡ ``$v0`` 共用， ``$v0`` 的低64ä½èˆ‡ ``$f0`` 共用，其他寄å˜å™¨ä¾æ¤é¡žæŽ¨ã€‚ + +控制狀態寄å˜å™¨ +-------------- + +控制狀態寄å˜å™¨åªèƒ½åœ¨ç‰¹æ¬Šæ¨¡å¼ï¼ˆPLV0）下訪å•: + +================= ==================================== ========== +åœ°å€ å…¨ç¨±æè¿° 簡稱 +================= ==================================== ========== +0x0 當å‰æ¨¡å¼ä¿¡æ¯ CRMD +0x1 異常å‰æ¨¡å¼ä¿¡æ¯ PRMD +0x2 擴展部件使能 EUEN +0x3 é›œé …æŽ§åˆ¶ MISC +0x4 異常é…ç½® ECFG +0x5 異常狀態 ESTAT +0x6 ç•°å¸¸è¿”å›žåœ°å€ ERA +0x7 出錯(Faulting)è™›æ“¬åœ°å€ BADV +0x8 出錯(Faulting)æŒ‡ä»¤å— BADI +0xC 異常入å£åœ°å€ EENTRY +0x10 TLB索引 TLBIDX +0x11 TLBè¡¨é …é«˜ä½ TLBEHI +0x12 TLBè¡¨é …ä½Žä½0 TLBELO0 +0x13 TLBè¡¨é …ä½Žä½1 TLBELO1 +0x18 地å€ç©ºé–“標è˜ç¬¦ ASID +0x19 低åŠåœ°å€ç©ºé–“é å…¨å±€ç›®éŒ„åŸºå€ PGDL +0x1A 高åŠåœ°å€ç©ºé–“é å…¨å±€ç›®éŒ„åŸºå€ PGDH +0x1B é å…¨å±€ç›®éŒ„åŸºå€ PGD +0x1C é 表éæ·æŽ§åˆ¶ä½ŽåŠéƒ¨åˆ† PWCL +0x1D é 表éæ·æŽ§åˆ¶é«˜åŠéƒ¨åˆ† PWCH +0x1E STLBé å¤§å° STLBPS +0x1F 縮減虛地å€é…ç½® RVACFG +0x20 CPU編號 CPUID +0x21 特權資æºé…置信æ¯1 PRCFG1 +0x22 特權資æºé…置信æ¯2 PRCFG2 +0x23 特權資æºé…置信æ¯3 PRCFG3 +0x30+n (0≤n≤15) 數據ä¿å˜å¯„å˜å™¨ SAVEn +0x40 定時器編號 TID +0x41 定時器é…ç½® TCFG +0x42 定時器值 TVAL +0x43 計時器補償 CNTC +0x44 定時器ä¸æ–·æ¸…除 TICLR +0x60 LLBit相關控制 LLBCTL +0x80 實ç¾ç›¸é—œæŽ§åˆ¶1 IMPCTL1 +0x81 實ç¾ç›¸é—œæŽ§åˆ¶2 IMPCTL2 +0x88 TLBé‡å¡«ç•°å¸¸å…¥å£åœ°å€ TLBRENTRY +0x89 TLBé‡å¡«ç•°å¸¸å‡ºéŒ¯(Faulting)è™›åœ°å€ TLBRBADV +0x8A TLBé‡å¡«ç•°å¸¸è¿”å›žåœ°å€ TLBRERA +0x8B TLBé‡å¡«ç•°å¸¸æ•¸æ“šä¿å˜ TLBRSAVE +0x8C TLBé‡å¡«ç•°å¸¸è¡¨é …低ä½0 TLBRELO0 +0x8D TLBé‡å¡«ç•°å¸¸è¡¨é …低ä½1 TLBRELO1 +0x8E TLBé‡å¡«ç•°å¸¸è¡¨é …é«˜ä½ TLBEHI +0x8F TLBé‡å¡«ç•°å¸¸å‰æ¨¡å¼ä¿¡æ¯ TLBRPRMD +0x90 機器錯誤控制 MERRCTL +0x91 機器錯誤信æ¯1 MERRINFO1 +0x92 機器錯誤信æ¯2 MERRINFO2 +0x93 機器錯誤異常入å£åœ°å€ MERRENTRY +0x94 æ©Ÿå™¨éŒ¯èª¤ç•°å¸¸è¿”å›žåœ°å€ MERRERA +0x95 機器錯誤異常數據ä¿å˜ MERRSAVE +0x98 高速緩å˜æ¨™ç±¤ CTAG +0x180+n (0≤n≤3) ç›´æŽ¥æ˜ å°„é…置窗å£n DMWn +0x200+2n (0≤n≤31) 性能監測é…ç½®n PMCFGn +0x201+2n (0≤n≤31) 性能監測計數器n PMCNTn +0x300 å…§å˜è®€å¯«ç›£è¦–點整體控制 MWPC +0x301 å…§å˜è®€å¯«ç›£è¦–點整體狀態 MWPS +0x310+8n (0≤n≤7) å…§å˜è®€å¯«ç›£è¦–點né…ç½®1 MWPnCFG1 +0x311+8n (0≤n≤7) å…§å˜è®€å¯«ç›£è¦–點né…ç½®2 MWPnCFG2 +0x312+8n (0≤n≤7) å…§å˜è®€å¯«ç›£è¦–點né…ç½®3 MWPnCFG3 +0x313+8n (0≤n≤7) å…§å˜è®€å¯«ç›£è¦–點né…ç½®4 MWPnCFG4 +0x380 å–指監視點整體控制 FWPC +0x381 å–指監視點整體狀態 FWPS +0x390+8n (0≤n≤7) å–指監視點né…ç½®1 FWPnCFG1 +0x391+8n (0≤n≤7) å–指監視點né…ç½®2 FWPnCFG2 +0x392+8n (0≤n≤7) å–指監視點né…ç½®3 FWPnCFG3 +0x393+8n (0≤n≤7) å–指監視點né…ç½®4 FWPnCFG4 +0x500 調試寄å˜å™¨ DBG +0x501 èª¿è©¦ç•°å¸¸è¿”å›žåœ°å€ DERA +0x502 調試數據ä¿å˜ DSAVE +================= ==================================== ========== + +ERA，TLBRERA，MERRERAå’ŒDERA有時也分別稱爲EPC，TLBREPC，MERREPCå’ŒDEPC。 + +基礎指令集 +========== + +æŒ‡ä»¤æ ¼å¼ +-------- + +LoongArch的指令å—長爲32ä½ï¼Œä¸€å…±æœ‰9ç¨®åŸºæœ¬æŒ‡ä»¤æ ¼å¼ï¼ˆä»¥åŠä¸€äº›è®Šé«”）: + +=========== ========================== +æ ¼å¼å稱 æŒ‡ä»¤æ§‹æˆ +=========== ========================== +2R Opcode + Rj + Rd +3R Opcode + Rk + Rj + Rd +4R Opcode + Ra + Rk + Rj + Rd +2RI8 Opcode + I8 + Rj + Rd +2RI12 Opcode + I12 + Rj + Rd +2RI14 Opcode + I14 + Rj + Rd +2RI16 Opcode + I16 + Rj + Rd +1RI21 Opcode + I21L + Rj + I21H +I26 Opcode + I26L + I26H +=========== ========================== + +Opcode是指令æ“作碼，Rjå’ŒRk是æºæ“作數（寄å˜å™¨ï¼‰ï¼ŒRd是目標æ“作數（寄å˜å™¨ï¼‰ï¼ŒRa是 +4R-typeæ ¼å¼ç‰¹æœ‰çš„é™„åŠ æ“作數（寄å˜å™¨ï¼‰ã€‚I8/I12/I14/I16/I21/I26分別是8ä½/12ä½/14ä½/ +16ä½/21ä½/26ä½çš„ç«‹å³æ•¸ã€‚å…¶ä¸è¼ƒé•·çš„21ä½å’Œ26ä½ç«‹å³æ•¸åœ¨æŒ‡ä»¤å—ä¸è¢«åˆ†å‰²çˆ²é«˜ä½éƒ¨åˆ†èˆ‡ä½Žä½ +éƒ¨åˆ†ï¼Œæ‰€ä»¥ä½ å€‘åœ¨é€™è£çš„æ ¼å¼æè¿°ä¸èƒ½å¤ 看到I21L/I21Hå’ŒI26L/I26H這樣帶後綴的表述。 + +指令列表 +-------- + +爲了簡便起見，我們在æ¤åªç¾…列一下指令å稱（助記符），需è¦è©³ç´°ä¿¡æ¯è«‹é–±è®€ +:ref:`åƒè€ƒæ–‡ç» <loongarch-references-zh_TW>` ä¸çš„文檔。 + +1. ç®—è¡“é‹ç®—指令:: + + ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D + SLT SLTU SLTI SLTUI + AND OR NOR XOR ANDN ORN ANDI ORI XORI + MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU + MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU + PCADDI PCADDU12I PCADDU18I + LU12I.W LU32I.D LU52I.D ADDU16I.D + +2. 移ä½é‹ç®—指令:: + + SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W + SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D + +3. ä½åŸŸæ“作指令:: + + EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D + BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D + REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D + MASKEQZ MASKNEZ + +4. 分支轉移指令:: + + BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL + +5. 訪å˜è®€å¯«æŒ‡ä»¤:: + + LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D + LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D + LDPTR.W LDPTR.D STPTR.W STPTR.D + PRELD PRELDX + +6. 原åæ“作指令:: + + LL.W SC.W LL.D SC.D + AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D + AMMAX.W AMMAX.D AMMIN.W AMMIN.D + +7. 柵障指令:: + + IBAR DBAR + +8. 特殊指令:: + + SYSCALL BREAK CPUCFG NOP IDLE ERTN(ERET) DBCL(DBGCALL) RDTIMEL.W RDTIMEH.W RDTIME.D + ASRTLE.D ASRTGT.D + +9. 特權指令:: + + CSRRD CSRWR CSRXCHG + IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D + CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE + +è™›æ“¬å…§å˜ +======== + +LoongArchå¯ä»¥ä½¿ç”¨ç›´æŽ¥æ˜ 射虛擬內å˜å’Œåˆ†é æ˜ å°„è™›æ“¬å…§å˜ã€‚ + +ç›´æŽ¥æ˜ å°„è™›æ“¬å…§å˜é€šéŽCSR.DMWn（n=0~3）來進行é…置，虛擬地å€ï¼ˆVA）和物ç†åœ°å€ï¼ˆPA） +ä¹‹é–“æœ‰ç°¡å–®çš„æ˜ å°„é—œä¿‚:: + + VA = PA + 固定å移 + +分é æ˜ å°„çš„è™›æ“¬åœ°å€ï¼ˆVA）和物ç†åœ°å€ï¼ˆPA）有任æ„çš„æ˜ å°„é—œä¿‚ï¼Œé€™ç¨®é—œä¿‚è¨˜éŒ„åœ¨TLBå’Œé +表ä¸ã€‚LoongArchçš„TLB包括一個全相è¯çš„MTLB（Multiple Page Size TLB，多樣é 大å°TLB） +和一個組相è¯çš„STLB（Single Page Size TLB，單一é 大å°TLB）。 + +缺çœç‹€æ…‹ä¸‹ï¼ŒLA32的整個虛擬地å€ç©ºé–“é…置如下： + +============ =========================== =========================== +å€æ®µå 地å€ç¯„åœ å±¬æ€§ +============ =========================== =========================== +``UVRANGE`` ``0x00000000 - 0x7FFFFFFF`` 分é æ˜ å°„, å¯ç·©å˜, PLV0~3 +``KPRANGE0`` ``0x80000000 - 0x9FFFFFFF`` ç›´æŽ¥æ˜ å°„, éžç·©å˜, PLV0 +``KPRANGE1`` ``0xA0000000 - 0xBFFFFFFF`` ç›´æŽ¥æ˜ å°„, å¯ç·©å˜, PLV0 +``KVRANGE`` ``0xC0000000 - 0xFFFFFFFF`` 分é æ˜ å°„, å¯ç·©å˜, PLV0 +============ =========================== =========================== + +用戶態（PLV3）åªèƒ½è¨ªå•UVRANGE，å°æ–¼ç›´æŽ¥æ˜ å°„çš„KPRANGE0å’ŒKPRANGE1，將虛擬地å€çš„第 +30~31ä½æ¸…零就ç‰æ–¼ç‰©ç†åœ°å€ã€‚例如：物ç†åœ°å€0x00001000å°æ‡‰çš„éžç·©å˜ç›´æŽ¥æ˜ å°„è™›æ“¬åœ°å€ +是0x80001000，而其å¯ç·©å˜ç›´æŽ¥æ˜ 射虛擬地å€æ˜¯0xA0001000。 + +缺çœç‹€æ…‹ä¸‹ï¼ŒLA64的整個虛擬地å€ç©ºé–“é…置如下： + +============ ====================== ================================== +å€æ®µå 地å€ç¯„åœ å±¬æ€§ +============ ====================== ================================== +``XUVRANGE`` ``0x0000000000000000 - 分é æ˜ å°„, å¯ç·©å˜, PLV0~3 + 0x3FFFFFFFFFFFFFFF`` +``XSPRANGE`` ``0x4000000000000000 - ç›´æŽ¥æ˜ å°„, å¯ç·©å˜ / éžç·©å˜, PLV0 + 0x7FFFFFFFFFFFFFFF`` +``XKPRANGE`` ``0x8000000000000000 - ç›´æŽ¥æ˜ å°„, å¯ç·©å˜ / éžç·©å˜, PLV0 + 0xBFFFFFFFFFFFFFFF`` +``XKVRANGE`` ``0xC000000000000000 - 分é æ˜ å°„, å¯ç·©å˜, PLV0 + 0xFFFFFFFFFFFFFFFF`` +============ ====================== ================================== + +用戶態（PLV3）åªèƒ½è¨ªå•XUVRANGE，å°æ–¼ç›´æŽ¥æ˜ å°„çš„XSPRANGEå’ŒXKPRANGE，將虛擬地å€çš„第 +60~63ä½æ¸…零就ç‰æ–¼ç‰©ç†åœ°å€ï¼Œè€Œå…¶ç·©å˜å±¬æ€§æ˜¯é€šéŽè™›æ“¬åœ°å€çš„第60~61ä½é…置的（0è¡¨ç¤ºå¼·åº +éžç·©å˜ï¼Œ1表示一致å¯ç·©å˜ï¼Œ2表示弱åºéžç·©å˜ï¼‰ã€‚ + +ç›®å‰ï¼Œæˆ‘們僅用XKPRANGEä¾†é€²è¡Œç›´æŽ¥æ˜ å°„ï¼ŒXSPRANGEä¿ç•™çµ¦ä»¥å¾Œç”¨ã€‚ + +æ¤è™•çµ¦å‡ºä¸€å€‹ç›´æŽ¥æ˜ 射的例å：物ç†åœ°å€0x00000000_00001000çš„å¼·åºéžç·©å˜ç›´æŽ¥æ˜ å°„è™›æ“¬åœ°å€ +（在XKPRANGEä¸ï¼‰æ˜¯0x80000000_00001000，其一致å¯ç·©å˜ç›´æŽ¥æ˜ 射虛擬地å€ï¼ˆåœ¨XKPRANGEä¸ï¼‰ +是0x90000000_00001000，而其弱åºéžç·©å˜ç›´æŽ¥æ˜ 射虛擬地å€ï¼ˆåœ¨XKPRANGEä¸ï¼‰æ˜¯0xA0000000_ +00001000。 + +Loongson與LoongArch的關係 +========================= + +LoongArch是一種RISC指令集架構（ISA），ä¸åŒæ–¼ç¾å˜çš„任何一種ISA，而Loongson（å³é¾ +芯）是一個處ç†å™¨å®¶æ—。é¾èŠ¯åŒ…括三個系列：Loongson-1（é¾èŠ¯1號）是32ä½è™•ç†å™¨ç³»åˆ—， +Loongson-2（é¾èŠ¯2號）是低端64ä½è™•ç†å™¨ç³»åˆ—，而Loongson-3（é¾èŠ¯3號）是高端64ä½è™•ç† +器系列。舊的é¾èŠ¯è™•ç†å™¨åŸºæ–¼MIPS架構，而新的é¾èŠ¯è™•ç†å™¨åŸºæ–¼LoongArch架構。以é¾èŠ¯3號 +爲例：é¾èŠ¯3A1000/3B1500/3A2000/3A3000/3A4000都是兼容MIPS的，而é¾èŠ¯3A5000（以åŠå°‡ +來的型號）都是基於LoongArch的。 + +.. _loongarch-references-zh_TW: + +åƒè€ƒæ–‡ç» +======== + +Loongson官方網站（é¾èŠ¯ä¸ç§‘技術股份有é™å…¬å¸ï¼‰ï¼š + + http://www.loongson.cn/ + +Loongson與LoongArch的開發者網站（軟件與文檔資æºï¼‰ï¼š + + http://www.loongnix.cn/ + + https://github.com/loongson/ + + https://loongson.github.io/LoongArch-Documentation/ + +LoongArch指令集架構的文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-CN.pdf （ä¸æ–‡ç‰ˆï¼‰ + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.02-EN.pdf （英文版） + +LoongArchçš„ELF psABI文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-CN.pdf （ä¸æ–‡ç‰ˆï¼‰ + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v2.01-EN.pdf （英文版） + +Loongson與LoongArchçš„Linuxå…§æ ¸æºç¢¼å€‰åº«ï¼š + + https://git.kernel.org/pub/scm/linux/kernel/git/chenhuacai/linux-loongson.git + diff --git a/Documentation/translations/zh_TW/arch/loongarch/irq-chip-model.rst b/Documentation/translations/zh_TW/arch/loongarch/irq-chip-model.rst new file mode 100644 index 000000000000..dbe9595bbf16 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/loongarch/irq-chip-model.rst @@ -0,0 +1,158 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/loongarch/irq-chip-model.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +================================== +LoongArchçš„IRQ芯片模型（層級關係） +================================== + +ç›®å‰ï¼ŒåŸºæ–¼LoongArch的處ç†å™¨ï¼ˆå¦‚é¾èŠ¯3A5000）åªèƒ½èˆ‡LS7A芯片組é…åˆå·¥ä½œã€‚LoongArch計算機 +ä¸çš„ä¸æ–·æŽ§åˆ¶å™¨ï¼ˆå³IRQ芯片）包括CPUINTC（CPU Core Interrupt Controller）ã€LIOINTC（ +Legacy I/O Interrupt Controller）ã€EIOINTC（Extended I/O Interrupt Controller）〠+HTVECINTC（Hyper-Transport Vector Interrupt Controller）ã€PCH-PIC（LS7AèŠ¯ç‰‡çµ„çš„ä¸»ä¸ +斷控制器）ã€PCH-LPC（LS7A芯片組的LPCä¸æ–·æŽ§åˆ¶å™¨ï¼‰å’ŒPCH-MSI（MSIä¸æ–·æŽ§åˆ¶å™¨ï¼‰ã€‚ + +CPUINTC是一種CPU內部的æ¯å€‹æ ¸æœ¬åœ°çš„ä¸æ–·æŽ§åˆ¶å™¨ï¼ŒLIOINTC/EIOINTC/HTVECINTC是CPU內部的 +全局ä¸æ–·æŽ§åˆ¶å™¨ï¼ˆæ¯å€‹èŠ¯ç‰‡ä¸€å€‹ï¼Œæ‰€æœ‰æ ¸å…±äº«ï¼‰ï¼Œè€ŒPCH-PIC/PCH-LPC/PCH-MSI是CPUå¤–éƒ¨çš„ä¸ +斷控制器（在é…套芯片組è£é¢ï¼‰ã€‚這些ä¸æ–·æŽ§åˆ¶å™¨ï¼ˆæˆ–者說IRQèŠ¯ç‰‡ï¼‰ä»¥ä¸€ç¨®å±¤æ¬¡æ¨¹çš„çµ„ç¹”å½¢å¼ +ç´šè¯åœ¨ä¸€èµ·ï¼Œä¸€å…±æœ‰å…©ç¨®å±¤ç´šé—œä¿‚模型（傳統IRQ模型和擴展IRQ模型）。 + +傳統IRQ模型 +=========== + +在這種模型è£é¢ï¼ŒIPI（Inter-Processor Interrupt）和CPU本地時é˜ä¸æ–·ç›´æŽ¥ç™¼é€åˆ°CPUINTC， +CPU串å£ï¼ˆUARTs）ä¸æ–·é«®é€åˆ°LIOINTC，而其他所有è¨å‚™çš„ä¸æ–·å‰‡åˆ†åˆ¥ç™¼é€åˆ°æ‰€é€£æŽ¥çš„PCH-PIC/ +PCH-LPC/PCH-MSI，然後被HTVECINTC統一收集，å†ç™¼é€åˆ°LIOINTC，最後到é”CPUINTC:: + + +-----+ +---------+ +-------+ + | IPI | --> | CPUINTC | <-- | Timer | + +-----+ +---------+ +-------+ + ^ + | + +---------+ +-------+ + | LIOINTC | <-- | UARTs | + +---------+ +-------+ + ^ + | + +-----------+ + | HTVECINTC | + +-----------+ + ^ ^ + | | + +---------+ +---------+ + | PCH-PIC | | PCH-MSI | + +---------+ +---------+ + ^ ^ ^ + | | | + +---------+ +---------+ +---------+ + | PCH-LPC | | Devices | | Devices | + +---------+ +---------+ +---------+ + ^ + | + +---------+ + | Devices | + +---------+ + +擴展IRQ模型 +=========== + +在這種模型è£é¢ï¼ŒIPI（Inter-Processor Interrupt）和CPU本地時é˜ä¸æ–·ç›´æŽ¥ç™¼é€åˆ°CPUINTC， +CPU串å£ï¼ˆUARTs）ä¸æ–·é«®é€åˆ°LIOINTC，而其他所有è¨å‚™çš„ä¸æ–·å‰‡åˆ†åˆ¥ç™¼é€åˆ°æ‰€é€£æŽ¥çš„PCH-PIC/ +PCH-LPC/PCH-MSI，然後被EIOINTC統一收集，å†ç›´æŽ¥åˆ°é”CPUINTC:: + + +-----+ +---------+ +-------+ + | IPI | --> | CPUINTC | <-- | Timer | + +-----+ +---------+ +-------+ + ^ ^ + | | + +---------+ +---------+ +-------+ + | EIOINTC | | LIOINTC | <-- | UARTs | + +---------+ +---------+ +-------+ + ^ ^ + | | + +---------+ +---------+ + | PCH-PIC | | PCH-MSI | + +---------+ +---------+ + ^ ^ ^ + | | | + +---------+ +---------+ +---------+ + | PCH-LPC | | Devices | | Devices | + +---------+ +---------+ +---------+ + ^ + | + +---------+ + | Devices | + +---------+ + +ACPI相關的定義 +============== + +CPUINTC:: + + ACPI_MADT_TYPE_CORE_PIC; + struct acpi_madt_core_pic; + enum acpi_madt_core_pic_version; + +LIOINTC:: + + ACPI_MADT_TYPE_LIO_PIC; + struct acpi_madt_lio_pic; + enum acpi_madt_lio_pic_version; + +EIOINTC:: + + ACPI_MADT_TYPE_EIO_PIC; + struct acpi_madt_eio_pic; + enum acpi_madt_eio_pic_version; + +HTVECINTC:: + + ACPI_MADT_TYPE_HT_PIC; + struct acpi_madt_ht_pic; + enum acpi_madt_ht_pic_version; + +PCH-PIC:: + + ACPI_MADT_TYPE_BIO_PIC; + struct acpi_madt_bio_pic; + enum acpi_madt_bio_pic_version; + +PCH-MSI:: + + ACPI_MADT_TYPE_MSI_PIC; + struct acpi_madt_msi_pic; + enum acpi_madt_msi_pic_version; + +PCH-LPC:: + + ACPI_MADT_TYPE_LPC_PIC; + struct acpi_madt_lpc_pic; + enum acpi_madt_lpc_pic_version; + +åƒè€ƒæ–‡ç» +======== + +é¾èŠ¯3A5000的文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-3A5000-usermanual-1.02-CN.pdf (ä¸æ–‡ç‰ˆ) + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-3A5000-usermanual-1.02-EN.pdf (英文版) + +é¾èŠ¯LS7A芯片組的文檔： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-CN.pdf (ä¸æ–‡ç‰ˆ) + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (英文版) + +.. note:: + - CPUINTC：å³ã€Šé¾èŠ¯æž¶æ§‹åƒè€ƒæ‰‹å†Šå·ä¸€ã€‹ç¬¬7.4節所æè¿°çš„CSR.ECFG/CSR.ESTAT寄å˜å™¨åŠå…¶ + ä¸æ–·æŽ§åˆ¶é‚輯； + - LIOINTC：å³ã€Šé¾èŠ¯3A5000處ç†å™¨ä½¿ç”¨æ‰‹å†Šã€‹ç¬¬11.1節所æ述的“傳統I/Oä¸æ–·â€ï¼› + - EIOINTC：å³ã€Šé¾èŠ¯3A5000處ç†å™¨ä½¿ç”¨æ‰‹å†Šã€‹ç¬¬11.2節所æ述的“擴展I/Oä¸æ–·â€ï¼› + - HTVECINTC：å³ã€Šé¾èŠ¯3A5000處ç†å™¨ä½¿ç”¨æ‰‹å†Šã€‹ç¬¬14.3節所æ述的“HyperTransportä¸æ–·â€ï¼› + - PCH-PIC/PCH-MSI：å³ã€Šé¾èŠ¯7A1000橋片用戶手冊》第5ç« æ‰€æ述的“ä¸æ–·æŽ§åˆ¶å™¨â€ï¼› + - PCH-LPC：å³ã€Šé¾èŠ¯7A1000橋片用戶手冊》第24.3節所æ述的“LPCä¸æ–·â€ã€‚ + diff --git a/Documentation/translations/zh_TW/arch/mips/booting.rst b/Documentation/translations/zh_TW/arch/mips/booting.rst new file mode 100644 index 000000000000..7e104abf5a51 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/booting.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/booting.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_booting: + +BMIPSè¨å‚™æ¨¹å¼•å°Ž +------------------------ + + 一些bootloadersåªæ”¯æŒåœ¨å…§æ ¸é¡åƒé–‹å§‹åœ°å€è™•çš„單一入å£é»žã€‚而其它 + bootloaders將跳轉到ELF的開始地å€è™•ã€‚兩種方案都支æŒçš„ï¼›å› çˆ² + CONFIG_BOOT_RAW=y and CONFIG_NO_EXCEPT_FILL=y, 所以第一æ¢æŒ‡ä»¤ + 會立å³è·³è½‰åˆ°kernel_entry()å…¥å£è™•åŸ·è¡Œã€‚ + + 與arch/arm情æ³(b)類似，dtæ„ŸçŸ¥çš„å¼•å°ŽåŠ è¼‰ç¨‹åºéœ€è¦è¨ç½®ä»¥ä¸‹å¯„å˜å™¨: + + a0 : 0 + + a1 : 0xffffffff + + a2 : RAMä¸æŒ‡å‘è¨å‚™æ¨¹å¡Šçš„物ç†æŒ‡é‡(在chapterIIä¸å®šç¾©)。 + è¨å‚™æ¨¹å¯ä»¥ä½æ–¼å‰512MB物ç†åœ°å€ç©ºé–“(0x00000000 - + 0x1fffffff)的任何ä½ç½®ï¼Œä»¥64ä½é‚Šç•Œå°é½Šã€‚ + + 傳統bootloadersä¸æœƒä½¿ç”¨é€™æ¨£çš„約定，並且它們ä¸å‚³å…¥DT塊。 + 在這種情æ³ä¸‹ï¼ŒLinux將通éŽé¸ä¸CONFIG_DT_*查找DTB。 + + 以上約定åªåœ¨32ä½ç³»çµ±ä¸å®šç¾©ï¼Œå› 爲目å‰æ²’有任何64ä½çš„BMIPS實ç¾ã€‚ + diff --git a/Documentation/translations/zh_TW/arch/mips/features.rst b/Documentation/translations/zh_TW/arch/mips/features.rst new file mode 100644 index 000000000000..f69410420035 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/features.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/features.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_features: + +.. kernel-feat:: $srctree/Documentation/features mips + diff --git a/Documentation/translations/zh_TW/arch/mips/index.rst b/Documentation/translations/zh_TW/arch/mips/index.rst new file mode 100644 index 000000000000..4b7d28806489 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/index.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/index.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +=========================== +MIPS特性文檔 +=========================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + booting + ingenic-tcu + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/mips/ingenic-tcu.rst b/Documentation/translations/zh_TW/arch/mips/ingenic-tcu.rst new file mode 100644 index 000000000000..4385c0f3e9cd --- /dev/null +++ b/Documentation/translations/zh_TW/arch/mips/ingenic-tcu.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/mips/ingenic-tcu.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_ingenic-tcu: + +=============================================== +å›æ£ JZ47xx SoC定時器/計數器硬件單元 +=============================================== + +å›æ£ JZ47xx SoCä¸çš„定時器/計數器單元(TCU)æ˜¯ä¸€å€‹å¤šåŠŸèƒ½ç¡¬ä»¶å¡Šã€‚å®ƒæœ‰å¤šé” +8個通é“，å¯ä»¥ç”¨ä½œè¨ˆæ•¸å™¨ï¼Œè¨ˆæ™‚器，或脈è¡å¯¬åº¦èª¿è£½å™¨ã€‚ + +- JZ4725B, JZ4750, JZ4755 åªæœ‰ï¼–個TCU通é“。其它SoC都有８個通é“。 + +- JZ4725B引入了一個ç¨ç«‹çš„通é“，稱爲æ“作系統計時器(OST)。這是一個32ä½å¯ + 編程定時器。在JZ4760BåŠä»¥ä¸Šåž‹è™Ÿä¸Šï¼Œå®ƒæ˜¯64ä½çš„。 + +- æ¯å€‹TCU通é“都有自己的時é˜æºï¼Œå¯ä»¥é€šéŽ TCSR 寄å˜å™¨è¨ç½®é€šé“çš„çˆ¶ç´šæ™‚é˜ + æºï¼ˆpclkã€extã€rtc）ã€é–‹é—œä»¥åŠåˆ†é »ã€‚ + + - 看門狗和OST硬件模塊在它們的寄å˜å™¨ç©ºé–“ä¸ä¹Ÿæœ‰ç›¸åŒå½¢å¼çš„TCSR寄å˜å™¨ã€‚ + - 用於關閉/é–‹å•“çš„ TCU 寄å˜å™¨ä¹Ÿå¯ä»¥é—œé–‰/開啓看門狗和 OST 時é˜ã€‚ + +- æ¯å€‹TCU通é“在兩種模å¼çš„å…¶ä¸ä¸€ç¨®æ¨¡å¼ä¸‹é‹è¡Œï¼š + + - æ¨¡å¼ TCU1：通é“無法在ç¡çœ 模å¼ä¸‹é‹è¡Œï¼Œä½†æ›´æ˜“æ–¼æ“作。 + - æ¨¡å¼ TCU2：通é“å¯ä»¥åœ¨ç¡çœ 模å¼ä¸‹é‹è¡Œï¼Œä½†æ“作比 TCU1 通é“複雜一些。 + +- æ¯å€‹ TCU 通é“的模å¼å–決於使用的SoC： + + - 在最è€çš„SoC（高於JZ4740），八個通é“都é‹è¡Œåœ¨TCU1模å¼ã€‚ + - 在 JZ4725B，通é“5é‹è¡Œåœ¨TCU2,其它通é“則é‹è¡Œåœ¨TCU1。 + - 在最新的SoC（JZ4750åŠä¹‹å¾Œï¼‰ï¼Œé€šé“1-2é‹è¡Œåœ¨TCU2，其它通é“則é‹è¡Œ + 在TCU1。 + +- æ¯å€‹é€šé“都å¯ä»¥ç”Ÿæˆä¸æ–·ã€‚有些通é“共享一æ¢ä¸æ–·ç·šï¼Œè€Œæœ‰äº›æ²’有，其在SoCåž‹ + 號之間的變更： + + - 在很è€çš„SoC（JZ4740åŠæ›´ä½Žï¼‰ï¼Œé€šé“0和通é“1有它們自己的ä¸æ–·ç·šï¼›é€š + é“2-7共享最後一æ¢ä¸æ–·ç·šã€‚ + - 在 JZ4725B，通é“0有它自己的ä¸æ–·ç·šï¼›é€šé“1-5共享一æ¢ä¸æ–·ç·šï¼›OST + 使用最後一æ¢ä¸æ–·ç·šã€‚ + - 在比較新的SoC（JZ4750åŠä»¥å¾Œï¼‰ï¼Œé€šé“5有它自己的ä¸æ–·ç·šï¼›é€š + é“0-4和（如果是8通é“）6-7全部共享一æ¢ä¸æ–·ç·šï¼›OST使用最後一æ¢ä¸ + 斷線。 + +å¯¦ç¾ +==== + +TCU硬件的功能分佈在多個驅動程åºï¼š + +============== =================================== +æ™‚é˜ drivers/clk/ingenic/tcu.c +ä¸æ–· drivers/irqchip/irq-ingenic-tcu.c +定時器 drivers/clocksource/ingenic-timer.c +OST drivers/clocksource/ingenic-ost.c +脈è¡å¯¬åº¦èª¿è£½å™¨ drivers/pwm/pwm-jz4740.c +看門狗 drivers/watchdog/jz4740_wdt.c +============== =================================== + +å› çˆ²å¯ä»¥å¾žç›¸åŒçš„寄å˜å™¨æŽ§åˆ¶å±¬æ–¼ä¸åŒé©…動程åºå’Œæ¡†æž¶çš„TCUçš„å„種功能，所以 +所有這些驅動程åºéƒ½é€šéŽç›¸åŒçš„控制總線通用接å£è¨ªå•å®ƒå€‘的寄å˜å™¨ã€‚ + +有關TCU驅動程åºçš„è¨å‚™æ¨¹ç¶å®šçš„更多信æ¯ï¼Œè«‹åƒé–±: +Documentation/devicetree/bindings/timer/ingenic,tcu.yaml. + diff --git a/Documentation/translations/zh_TW/arch/openrisc/index.rst b/Documentation/translations/zh_TW/arch/openrisc/index.rst new file mode 100644 index 000000000000..7585960783fc --- /dev/null +++ b/Documentation/translations/zh_TW/arch/openrisc/index.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/openrisc/index.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_openrisc_index: + +================= +OpenRISC 體系架構 +================= + +.. toctree:: + :maxdepth: 2 + + openrisc_port + todo + +Todolist: + features + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/openrisc/openrisc_port.rst b/Documentation/translations/zh_TW/arch/openrisc/openrisc_port.rst new file mode 100644 index 000000000000..422fe9f7a3f2 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/openrisc/openrisc_port.rst @@ -0,0 +1,128 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/openrisc/openrisc_port.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_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_TW/arch/openrisc/todo.rst b/Documentation/translations/zh_TW/arch/openrisc/todo.rst new file mode 100644 index 000000000000..df261b9e3002 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/openrisc/todo.rst @@ -0,0 +1,24 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/openrisc/todo.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_openrisc_todo.rst: + +======== +å¾…è¾¦äº‹é … +======== + +OpenRISC Linux的移æ¤å·²ç¶“完全投入使用，並且從 2.6.35 開始就一直在上游åŒæ¥ã€‚ +ç„¶è€Œï¼Œé‚„æœ‰ä¸€äº›å‰©é¤˜çš„é …ç›®éœ€è¦åœ¨æœªä¾†å¹¾å€‹æœˆå…§å®Œæˆã€‚ 下é¢æ˜¯ä¸€å€‹å³å°‡é€²è¡Œèª¿æŸ¥çš„已知 +ä¸ç›¡å®Œç¾Žçš„é …ç›®åˆ—è¡¨ï¼Œå³æˆ‘å€‘çš„å¾…è¾¦äº‹é …åˆ—è¡¨ã€‚ + +- 實ç¾å…¶é¤˜çš„DMA API……dma_map_sgç‰ã€‚ + +- 完æˆé‡å‘½å清ç†å·¥ä½œâ€¦â€¦ä»£ç¢¼ä¸æ到了or32，這是架構的一個è€åå—。 我們 + 已經確定的åå—是or1k，這個改變æ£åœ¨ä»¥ç·©æ…¢ç©ç´¯çš„æ–¹å¼é€²è¡Œã€‚ ç›®å‰ï¼Œor32相當 + æ–¼or1k。 + diff --git a/Documentation/translations/zh_TW/arch/parisc/debugging.rst b/Documentation/translations/zh_TW/arch/parisc/debugging.rst new file mode 100644 index 000000000000..c9ee804aebbd --- /dev/null +++ b/Documentation/translations/zh_TW/arch/parisc/debugging.rst @@ -0,0 +1,46 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/parisc/debugging.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_parisc_debugging: + +================= +調試PA-RISC +================= + +好å§ï¼Œé€™è£æœ‰ä¸€äº›é—œæ–¼èª¿è©¦linux/parisc的較底層部分的信æ¯ã€‚ + + +1. 絕å°åœ°å€ +===================== + +很多彙編代碼目å‰é‹è¡Œåœ¨å¯¦æ¨¡å¼ä¸‹ï¼Œé€™æ„味ç€æœƒä½¿ç”¨çµ•å°åœ°å€ï¼Œè€Œä¸æ˜¯åƒå…§æ ¸å…¶ä»– +部分那樣使用虛擬地å€ã€‚è¦å°‡çµ•å°åœ°å€è½‰æ›çˆ²è™›æ“¬åœ°å€ï¼Œä½ å¯ä»¥åœ¨System.mapä¸æŸ¥ +æ‰¾ï¼Œæ·»åŠ __PAGE_OFFSET（目å‰æ˜¯0x10000000）。 + + +2. HPMCs +======== + +當實模å¼çš„代碼試圖訪å•ä¸å˜åœ¨çš„å…§å˜æ™‚，會出ç¾HPMC（high priority machine +check）而ä¸æ˜¯å…§æ ¸oops。若è¦èª¿è©¦HPMC，請嘗試找到系統響應程åº/請求程åºåœ°å€ã€‚ +系統請求程åºåœ°å€æ‡‰è©²èˆ‡ï¼ˆæŸï¼‰è™•ç†å™¨çš„HPA（I/O範åœå…§çš„高地å€ï¼‰ç›¸åŒ¹é…；系統響應程 +åºåœ°å€æ˜¯å¯¦æ¨¡å¼ä»£ç¢¼è©¦åœ–訪å•çš„地å€ã€‚ + +系統響應程åºåœ°å€çš„典型值是大於__PAGE_OFFSET （0x10000000）的地å€ï¼Œé€™æ„å‘³ç€ +在實模å¼è©¦åœ–訪å•å®ƒä¹‹å‰ï¼Œè™›æ“¬åœ°å€æ²’有被翻è¯æˆç‰©ç†åœ°å€ã€‚ + + +3. 有趣的Qä½ +============ + +æŸäº›éžå¸¸é—œéµçš„ä»£ç¢¼å¿…é ˆæ¸…é™¤PSWä¸çš„Qä½ã€‚當Qä½è¢«æ¸…除時，CPUä¸æœƒæ›´æ–°ä¸æ–·è™•ç† +程åºæ‰€è®€å–的寄å˜å™¨ï¼Œä»¥æ‰¾å‡ºæ©Ÿå™¨è¢«ä¸æ–·çš„ä½ç½®â€”â€”æ‰€ä»¥å¦‚æžœä½ åœ¨æ¸…é™¤Qä½çš„æŒ‡ä»¤å’Œå† +次è¨ç½®Qä½çš„RFI之間é‡åˆ°ä¸æ–·ï¼Œä½ ä¸çŸ¥é“它到底發生在哪è£ã€‚å¦‚æžœä½ å¹¸é‹çš„話，IAOQ +會指å‘清除Qä½çš„æŒ‡ä»¤ï¼Œå¦‚æžœä½ ä¸å¹¸é‹çš„話，它會指å‘任何地方。通常Qä½çš„å•é¡Œæœƒ +表ç¾çˆ²ç„¡æ³•è§£é‡‹çš„系統掛起或物ç†å…§å˜è¶Šç•Œã€‚ + diff --git a/Documentation/translations/zh_TW/arch/parisc/index.rst b/Documentation/translations/zh_TW/arch/parisc/index.rst new file mode 100644 index 000000000000..35941bf68c88 --- /dev/null +++ b/Documentation/translations/zh_TW/arch/parisc/index.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/parisc/index.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_parisc_index: + +==================== +PA-RISC體系架構 +==================== + +.. toctree:: + :maxdepth: 2 + + debugging + registers + +Todolist: + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/arch/parisc/registers.rst b/Documentation/translations/zh_TW/arch/parisc/registers.rst new file mode 100644 index 000000000000..695acb21134a --- /dev/null +++ b/Documentation/translations/zh_TW/arch/parisc/registers.rst @@ -0,0 +1,157 @@ +.. include:: ../../disclaimer-zh_TW.rst + +:Original: Documentation/arch/parisc/registers.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +.. _tw_parisc_registers: + +========================= +Linux/PA-RISC的寄å˜å™¨ç”¨æ³• +========================= + +[ 用星號表示目å‰å°šæœªå¯¦ç¾çš„計劃用途。 ] + +ABI約定的通用寄å˜å™¨ +=================== + +控制寄å˜å™¨ +---------- + +============================ ================================= +CR 0 (æ¢å¾©è¨ˆæ•¸å™¨) 用於ptrace +CR 1-CR 7(無定義) 未使用 +CR 8 (Protection ID) æ¯é€²ç¨‹å€¼* +CR 9, 12, 13 (PIDS) 未使用 +CR10 (CCR) FPU延é²ä¿å˜* +CR11 按照ABIçš„è¦å®šï¼ˆSAR） +CR14 (ä¸æ–·å‘é‡) åˆå§‹åŒ–爲 fault_vector +CR15 (EIEM) 所有ä½åˆå§‹åŒ–爲1* +CR16 (間隔計時器) 讀å–週期數/寫入開始時間間隔計時器 +CR17-CR22 ä¸æ–·åƒæ•¸ +CR19 ä¸æ–·æŒ‡ä»¤å¯„å˜å™¨ +CR20 ä¸æ–·ç©ºé–“寄å˜å™¨ +CR21 ä¸æ–·å移é‡å¯„å˜å™¨ +CR22 ä¸æ–· PSW +CR23 (EIRR) 讀å–未決ä¸æ–·/å¯«å…¥æ¸…é™¤ä½ +CR24 (TR 0) å…§æ ¸ç©ºé–“é ç›®éŒ„æŒ‡é‡ +CR25 (TR 1) 用戶空間é ç›®éŒ„æŒ‡é‡ +CR26 (TR 2) ä¸ä½¿ç”¨ +CR27 (TR 3) 線程æè¿°ç¬¦æŒ‡é‡ +CR28 (TR 4) ä¸ä½¿ç”¨ +CR29 (TR 5) ä¸ä½¿ç”¨ +CR30 (TR 6) ç•¶å‰ / 0 +CR31 (TR 7) 臨時寄å˜å™¨ï¼Œåœ¨ä¸åŒåœ°æ–¹ä½¿ç”¨ +============================ ================================= + +空間寄å˜å™¨ï¼ˆå…§æ ¸æ¨¡å¼ï¼‰ +---------------------- + +======== ============================== +SR0 臨時空間寄å˜å™¨ +SR4-SR7 è¨ç½®çˆ²0 +SR1 臨時空間寄å˜å™¨ +SR2 å…§æ ¸ä¸æ‡‰è©²ç ´å£žå®ƒ +SR3 用於用戶空間訪å•ï¼ˆç•¶å‰é€²ç¨‹ï¼‰ +======== ============================== + +空間寄å˜å™¨ï¼ˆç”¨æˆ¶æ¨¡å¼ï¼‰ +---------------------- + +======== ============================ +SR0 臨時空間寄å˜å™¨ +SR1 臨時空間寄å˜å™¨ +SR2 ä¿å˜Linux gateway page的空間 +SR3 åœ¨å…§æ ¸ä¸ä¿å˜ç”¨æˆ¶åœ°å€ç©ºé–“的值 +SR4-SR7 定義了用戶/å…§æ ¸çš„çŸåœ°å€ç©ºé–“ +======== ============================ + + +處ç†å™¨ç‹€æ…‹å— +------------ + +====================== ================================================ +W （64ä½åœ°å€ï¼‰ 0 +E （å°å°¾ç«¯ï¼‰ 0 +S （安全間隔計時器） 0 +T （產生分支陷阱） 0 +H （高特權級陷阱） 0 +L （低特權級陷阱） 0 +N （撤銷下一æ¢æŒ‡ä»¤ï¼‰ 被C代碼使用 +X （數據å˜å„²ä¸æ–·ç¦ç”¨ï¼‰ 0 +B （產生分支） 被C代碼使用 +C （代碼地å€è½‰è¯ï¼‰ 1, 在執行實模å¼ä»£ç¢¼æ™‚爲0 +V （除法æ¥é•·æ ¡æ£ï¼‰ 被C代碼使用 +M （HPMC 掩碼） 0, 在執行HPMCæ“作*時爲1 +C/B （進/借 ä½ï¼‰ 被C代碼使用 +O （有åºå¼•ç”¨ï¼‰ 1* +F （性能監視器） 0 +R （回收計數器陷阱） 0 +Q （收集ä¸æ–·ç‹€æ…‹ï¼‰ 1 （在rfi之å‰çš„代碼ä¸çˆ²0） +P （ä¿è·æ¨™è˜ç¬¦ï¼‰ 1* +D （數據地å€è½‰è¯ï¼‰ 1, 在執行實模å¼ä»£ç¢¼æ™‚爲0 +I （外部ä¸æ–·æŽ©ç¢¼ï¼‰ ç”±cli()/sti()å®ä½¿ç”¨ã€‚ +====================== ================================================ + +“隱形â€å¯„å˜å™¨ï¼ˆå½±å寄å˜å™¨ï¼‰ +--------------------------- + +============= =================== +PSW W 默èªå€¼ 0 +PSW E 默èªå€¼ 0 +å½±å寄å˜å™¨ 被ä¸æ–·è™•ç†ä»£ç¢¼ä½¿ç”¨ +TOCå•“ç”¨ä½ 1 +============= =================== + +---------------------------------------------------------- + +PA-RISC架構定義了7個寄å˜å™¨ä½œçˆ²â€œå½±å寄å˜å™¨â€ã€‚這些寄å˜å™¨åœ¨ +RETURN FROM INTERRUPTION AND RESTORE指令ä¸ä½¿ç”¨ï¼Œé€šéŽæ¶ˆ +除ä¸æ–·è™•ç†ç¨‹åºä¸å°ä¸€èˆ¬å¯„å˜å™¨ï¼ˆGR）的ä¿å˜å’Œæ¢å¾©çš„需è¦ä¾†æ¸› +少狀態ä¿å˜å’Œæ¢å¾©æ™‚間。影å寄å˜å™¨æ˜¯GRs 1, 8, 9, 16, 17, +24å’Œ25。 + +------------------------------------------------------------------------- + +寄å˜å™¨ä½¿ç”¨èªªæ˜Žï¼Œæœ€åˆç”±John Marvinæ供，並由Randolph Chungæ供一些補充說明。 + +å°æ–¼é€šç”¨å¯„å˜å™¨: + +r1,r2,r19-r26,r28,r29 & r31å¯ä»¥åœ¨ä¸ä¿å˜å®ƒå€‘的情æ³ä¸‹è¢«ä½¿ç”¨ã€‚ç•¶ç„¶ï¼Œå¦‚æžœä½ +關心它們，在調用å¦ä¸€å€‹ç¨‹åºä¹‹å‰ï¼Œä½ 也需è¦ä¿å˜å®ƒå€‘。上é¢çš„一些寄å˜å™¨ç¢ºå¯¦ +有特殊的å«ç¾©ï¼Œä½ 應該注æ„一下: + + r1: + addil指令是硬性è¦å®šå°‡å…¶çµæžœæ”¾åœ¨r1ä¸ï¼Œæ‰€ä»¥å¦‚æžœä½ ä½¿ç”¨é€™æ¢æŒ‡ä»¤è¦ + 注æ„這點。 + + r2: + 這就是返回指é‡ã€‚ä¸€èˆ¬ä¾†èªªï¼Œä½ ä¸æƒ³ä½¿ç”¨å®ƒï¼Œå› çˆ²ä½ éœ€è¦é€™å€‹æŒ‡é‡ä¾†è¿” + å›žçµ¦ä½ çš„èª¿ç”¨è€…ã€‚ç„¶è€Œï¼Œå®ƒèˆ‡é€™çµ„å¯„å˜å™¨çµ„åˆåœ¨ä¸€èµ·ï¼Œå› 爲調用者ä¸èƒ½ + ä¾è³´ä½ 返回時的值是相åŒçš„ï¼Œä¹Ÿå°±æ˜¯èªªï¼Œä½ å¯ä»¥å°‡r2複製到å¦ä¸€å€‹å¯„å˜ + 器，並在作廢r2後通éŽè©²å¯„å˜å™¨è¿”回，這應該ä¸æœƒçµ¦èª¿ç”¨ç¨‹åºå¸¶ä¾†å•é¡Œã€‚ + + r19-r22: + 這些通常被èªçˆ²æ˜¯è‡¨æ™‚寄å˜å™¨ã€‚ + 請注æ„，在64ä½ä¸å®ƒå€‘是arg7-arg4。 + + r23-r26: + 這些是arg3-arg0ï¼Œä¹Ÿå°±æ˜¯èªªï¼Œå¦‚æžœä½ ä¸å†é—œå¿ƒå‚³å…¥çš„å€¼ï¼Œä½ å¯ä»¥ä½¿ç”¨ + 它們。 + + r28,r29: + 這倆是ret0å’Œret1ã€‚å®ƒå€‘æ˜¯ä½ å‚³å…¥è¿”å›žå€¼çš„åœ°æ–¹ã€‚r28是主返回值。當返回 + å°çµæ§‹é«”時，r29也å¯ä»¥ç”¨ä¾†å°‡æ•¸æ“šå‚³å›žçµ¦èª¿ç”¨ç¨‹åºã€‚ + + r30: + æ£§æŒ‡é‡ + + r31: + ble指令將返回指é‡æ”¾åœ¨é€™è£ã€‚ + + + r3-r18,r27,r30需è¦è¢«ä¿å˜å’Œæ¢å¾©ã€‚r3-r18åªæ˜¯ä¸€èˆ¬ç”¨é€”的寄å˜å™¨ã€‚ + r27是數據指é‡ï¼Œç”¨ä¾†ä½¿å°å…¨å±€è®Šé‡çš„引用更容易。r30是棧指é‡ã€‚ + diff --git a/Documentation/translations/zh_TW/cpu-freq/core.rst b/Documentation/translations/zh_TW/cpu-freq/core.rst index f1951e1b23bb..4f98d1e9f34b 100644 --- a/Documentation/translations/zh_TW/cpu-freq/core.rst +++ b/Documentation/translations/zh_TW/cpu-freq/core.rst @@ -1,13 +1,15 @@ .. SPDX-License-Identifier: GPL-2.0 - .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/core` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res.211@gmail.com> +:Original: Documentation/cpu-freq/core.rst + +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> -.. _tw_core.rst: +:æ ¡è¯: + å”è—舟 Tang Yizhou <tangyeechou@gmail.com> ==================================== CPUFreqæ ¸å¿ƒå’ŒCPUFreq通知器的通用說明 @@ -29,10 +31,10 @@ CPUFreqæ ¸å¿ƒå’ŒCPUFreq通知器的通用說明 ====================== cpufreqæ ¸å¿ƒä»£ç¢¼ä½æ–¼drivers/cpufreq/cpufreq.cä¸ã€‚這些cpufreq代碼爲CPUFreq架構的驅 -動程åºï¼ˆé‚£äº›æ“作硬體切æ›é »çŽ‡çš„ä»£ç¢¼ï¼‰ä»¥åŠ "通知器 "æ供了一個標準化的接å£ã€‚ -這些是è¨å‚™é©…動程åºæˆ–需è¦äº†è§£ç–ç•¥è®ŠåŒ–çš„å…¶å®ƒå…§æ ¸éƒ¨åˆ†ï¼ˆå¦‚ ACPI 熱é‡ç®¡ç†ï¼‰æˆ–æ‰€æœ‰é »çŽ‡æ›´æ”¹ï¼ˆé™¤ -計時代碼外），甚至需è¦å¼·åˆ¶ç¢ºå®šé€Ÿåº¦é™åˆ¶çš„通知器（如 ARM 架構上的 LCD 驅動程åºï¼‰ã€‚ -æ¤å¤–， å…§æ ¸ "常數" loops_per_jiffyæœƒæ ¹æ“šé »çŽ‡è®ŠåŒ–è€Œæ›´æ–°ã€‚ +動程åºï¼ˆé‚£äº›åŸ·è¡Œç¡¬ä»¶é »çŽ‡åˆ‡æ›çš„ä»£ç¢¼ï¼‰ä»¥åŠ "通知器" æ供了一個標準化的接å£ã€‚ +包括è¨å‚™é©…動程åºï¼›éœ€è¦äº†è§£ç–略變化（如 ACPI 熱é‡ç®¡ç†ï¼‰ï¼Œæˆ–æ‰€æœ‰é »çŽ‡è®ŠåŒ–ï¼ˆå¦‚è¨ˆæ™‚ä»£ç¢¼ï¼‰ï¼Œ +甚至需è¦å¼·åˆ¶é™åˆ¶çˆ²æŒ‡å®šé »çŽ‡ï¼ˆå¦‚ ARM 架構上的 LCD 驅動程åºï¼‰çš„å…¶å®ƒå…§æ ¸çµ„ä»¶ã€‚ +æ¤å¤–ï¼Œå…§æ ¸ "常數" loops_per_jiffy æœƒæ ¹æ“šé »çŽ‡è®ŠåŒ–è€Œæ›´æ–°ã€‚ cpufreqç–略的引用計數由 cpufreq_cpu_get å’Œ cpufreq_cpu_put 來完æˆï¼Œä»¥ç¢ºä¿ cpufreq é©… 動程åºè¢«æ£ç¢ºåœ°è¨»å†Šåˆ°æ ¸å¿ƒä¸ï¼Œä¸¦ä¸”驅動程åºåœ¨ cpufreq_put_cpu 被調用之å‰ä¸æœƒè¢«å¸è¼‰ã€‚這也ä¿è‰ @@ -41,10 +43,10 @@ cpufreqç–略的引用計數由 cpufreq_cpu_get å’Œ cpufreq_cpu_put 來完æˆï¼Œ 2. CPUFreq 通知器 ==================== -CPUFreq通知器符åˆæ¨™æº–çš„å…§æ ¸é€šçŸ¥å™¨æŽ¥å£ã€‚ +CPUFreq通知器éµå¾ªæ¨™æº–çš„å…§æ ¸é€šçŸ¥å™¨æŽ¥å£ã€‚ 關於通知器的細節請åƒé–± linux/include/linux/notifier.h。 -這裡有兩個ä¸åŒçš„CPUfreq通知器 - ç–略通知器和轉æ›é€šçŸ¥å™¨ã€‚ +這è£æœ‰å…©å€‹ä¸åŒçš„CPUfreq通知器 - ç–略通知器和轉æ›é€šçŸ¥å™¨ã€‚ 2.1 CPUFreqç–略通知器 @@ -62,27 +64,27 @@ CPUFreq通知器符åˆæ¨™æº–çš„å…§æ ¸é€šçŸ¥å™¨æŽ¥å£ã€‚ 2.2 CPUFreq轉æ›é€šçŸ¥å™¨ -------------------------------- -當CPUfreq驅動切æ›CPUæ ¸å¿ƒé »çŽ‡æ™‚ï¼Œç–ç•¥ä¸çš„æ¯å€‹åœ¨ç·šCPU都會收到兩次通知，這些變化沒有任何外部干 +當CPUfreq驅動切æ›CPUæ ¸å¿ƒé »çŽ‡æ™‚ï¼Œç–ç•¥ä¸çš„æ¯å€‹åœ¨ç·šCPU都會收到兩次通知，這些變化沒有任何外部幹 é 。 第二個åƒæ•¸æŒ‡å®šéšŽæ®µ - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. 第三個åƒæ•¸æ˜¯ä¸€å€‹åŒ…å«å¦‚下值的çµæ§‹é«”cpufreq_freqs： -===== ==================== -cpu å—影響cpu的編號 +====== =============================== +policy 指å‘struct cpufreq_policyçš„æŒ‡é‡ old èˆŠé »çŽ‡ new æ–°é »çŽ‡ flags cpufreq驅動的標誌 -===== ==================== +====== =============================== 3. å«æœ‰Operating Performance Point (OPP)çš„CPUFreqè¡¨çš„ç”Ÿæˆ ================================================================== 關於OPP的細節請åƒé–± Documentation/power/opp.rst dev_pm_opp_init_cpufreq_table - - 這個功能æ供了一個隨時å¯ç”¨çš„轉æ›ç¨‹åºï¼Œç”¨ä¾†å°‡OPP層關於å¯ç”¨é »çŽ‡çš„內部信æ¯ç¿»è¯æˆä¸€ç¨®å®¹æ˜“æ供給 - cpufreqçš„æ ¼å¼ã€‚ + 這個函數æ供了一個隨時å¯ç”¨çš„轉æ›ä¾‹ç¨‹ï¼Œç”¨ä¾†å°‡OPP層關於å¯ç”¨é »çŽ‡çš„內部信æ¯ç¿»è¯æˆä¸€ç¨® + cpufreq易於處ç†çš„æ ¼å¼ã€‚ .. Warning:: @@ -101,7 +103,7 @@ dev_pm_opp_init_cpufreq_table - .. note:: - 該函數åªæœ‰åœ¨CONFIG_PM_OPP之外還啓用了CONFIG_CPU_FREQ時æ‰å¯ç”¨ã€‚ + 該函數åªæœ‰åœ¨CONFIG_PM_OPP之外還啓用了CONFIG_CPU_FREQ時纔å¯ç”¨ã€‚ dev_pm_opp_free_cpufreq_table 釋放dev_pm_opp_init_cpufreq_table分é…的表。 diff --git a/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst index 671b1bf0e2c5..add3de2d4523 100644 --- a/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst +++ b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst @@ -2,12 +2,15 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/cpu-drivers` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res.211@gmail.com> +:Original: Documentation/cpu-freq/cpu-drivers.rst -.. _tw_cpu-drivers.rst: +:ç¿»è¯: + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯: + + å”è—舟 Tang Yizhou <tangyeechou@gmail.com> ======================================= 如何實ç¾ä¸€å€‹æ–°çš„CPUFreq處ç†å™¨é©…動程åºï¼Ÿ @@ -37,15 +40,15 @@ 1. 怎麼åšï¼Ÿ =========== -如æ¤ï¼Œä½ 剛剛得到了一個全新的CPU/晶片組åŠå…¶æ•¸æ“šæ‰‹å†Šï¼Œä¸¦å¸Œæœ›çˆ²é€™å€‹CPU/æ™¶ç‰‡çµ„æ·»åŠ cpufreq -支æŒï¼Ÿå¾ˆå¥½ï¼Œé€™è£¡æœ‰ä¸€äº›è‡³é—œé‡è¦çš„æ示： +å¦‚æžœï¼Œä½ å‰›å‰›å¾—åˆ°äº†ä¸€å€‹å…¨æ–°çš„CPU/芯片組åŠå…¶æ•¸æ“šæ‰‹å†Šï¼Œä¸¦å¸Œæœ›çˆ²é€™å€‹CPU/èŠ¯ç‰‡çµ„æ·»åŠ cpufreq +支æŒï¼Ÿå¾ˆå¥½ï¼Œé€™è£æœ‰ä¸€äº›è‡³é—œé‡è¦çš„æ示： 1.1 åˆå§‹åŒ– ---------- -首先，在__initcall_level_7 (module_init())或更é 後的函數ä¸æª¢æŸ¥é€™å€‹å…§æ ¸æ˜¯å¦ -é‹è¡Œåœ¨æ£ç¢ºçš„CPUå’Œæ£ç¢ºçš„晶片組上。如果是，則使用cpufreq_register_driver()å‘ +首先，在 __initcall level 7 (module_init())或更é 後的函數ä¸æª¢æŸ¥é€™å€‹å…§æ ¸æ˜¯å¦ +é‹è¡Œåœ¨æ£ç¢ºçš„CPUå’Œæ£ç¢ºçš„芯片組上。如果是，則使用cpufreq_register_driver()å‘ CPUfreqæ ¸å¿ƒå±¤è¨»å†Šä¸€å€‹cpufreq_driverçµæ§‹é«”。 çµæ§‹é«”cpufreq_driver應該包å«ä»€éº¼æˆå“¡? @@ -59,11 +62,11 @@ CPUfreqæ ¸å¿ƒå±¤è¨»å†Šä¸€å€‹cpufreq_driverçµæ§‹é«”。 .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差異見 下文。 -並且å¯é¸æ“‡ +其它å¯é¸æˆå“¡ - .flags - cpufreqæ ¸çš„æ示。 + .flags - 給cpufreqæ ¸å¿ƒçš„æ示。 - .driver_data - cpufreq驅動程åºçš„特定數據。 + .driver_data - cpufreq驅動程åºçš„特有數據。 .get_intermediate å’Œ target_intermediate - 用於在改變CPUé »çŽ‡æ™‚åˆ‡æ›åˆ°ç©©å®š çš„é »çŽ‡ã€‚ @@ -72,18 +75,18 @@ CPUfreqæ ¸å¿ƒå±¤è¨»å†Šä¸€å€‹cpufreq_driverçµæ§‹é«”。 .bios_limit - 返回HW/BIOSå°CPUçš„æœ€å¤§é »çŽ‡é™åˆ¶å€¼ã€‚ - .exit - 一個指å‘per-policy清ç†å‡½æ•¸çš„指é‡ï¼Œè©²å‡½æ•¸åœ¨cpu熱æ’æ‹”éŽç¨‹çš„CPU_POST_DEAD + .exit - 一個指å‘per-policy清ç†å‡½æ•¸çš„指é‡ï¼Œè©²å‡½æ•¸åœ¨CPU熱æ’æ‹”éŽç¨‹çš„CPU_POST_DEAD 階段被調用。 .suspend - 一個指å‘per-policyæš«åœå‡½æ•¸çš„指é‡ï¼Œè©²å‡½æ•¸åœ¨é—œä¸æ–·ä¸”在該ç–略的調節器åœæ¢ 後被調用。 - .resume - 一個指å‘per-policyæ¢å¾©å‡½æ•¸çš„指é‡ï¼Œè©²å‡½æ•¸åœ¨é—œä¸æ–·ä¸”在調節器å†ä¸€æ¬¡é–‹å§‹å‰è¢« + .resume - 一個指å‘per-policyæ¢å¾©å‡½æ•¸çš„指é‡ï¼Œè©²å‡½æ•¸åœ¨é—œä¸æ–·ä¸”在調節器å†ä¸€æ¬¡å•“å‹•å‰è¢« 調用。 .ready - 一個指å‘per-policy準備函數的指é‡ï¼Œè©²å‡½æ•¸åœ¨ç–略完全åˆå§‹åŒ–之後被調用。 - .attr - 一個指å‘NULLçµå°¾çš„"struct freq_attr"列表的指é‡ï¼Œè©²å‡½æ•¸å…許導出值到 + .attr - 一個指å‘NULLçµå°¾çš„"struct freq_attr"列表的指é‡ï¼Œè©²åˆ—表å…許導出值到 sysfs。 .boost_enabled - 如果è¨ç½®ï¼Œå‰‡å•“用æå‡(boost)é »çŽ‡ã€‚ @@ -94,95 +97,93 @@ CPUfreqæ ¸å¿ƒå±¤è¨»å†Šä¸€å€‹cpufreq_driverçµæ§‹é«”。 1.2 Per-CPU åˆå§‹åŒ– ------------------ -æ¯ç•¶ä¸€å€‹æ–°çš„CPU被註冊到è¨å‚™æ¨¡åž‹ä¸ï¼Œæˆ–者在cpufreq驅動註冊自己之後，如果æ¤CPUçš„cpufreqç– -ç•¥ä¸å˜åœ¨ï¼Œå‰‡æœƒèª¿ç”¨per-policyçš„åˆå§‹åŒ–函數cpufreq_driver.init。請注æ„，.init()å’Œ.exit()ç¨‹åº -åªå°ç–略調用一次，而ä¸æ˜¯å°ç–略管ç†çš„æ¯å€‹CPU調用一次。它需è¦ä¸€å€‹ ``struct cpufreq_policy +æ¯ç•¶ä¸€å€‹æ–°çš„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.min_freqå’Œ | 該CPU支æŒçš„æœ€ä½Žå’Œæœ€é«˜é »çŽ‡ï¼ˆkHz） | +|policy->cpuinfo.max_freq | | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpuinfo.transition_latency | | -| | CPUåœ¨å…©å€‹é »çŽ‡ä¹‹é–“åˆ‡æ›æ‰€éœ€çš„時間，以 | -| | ç´ç§’爲單ä½ï¼ˆå¦‚é©ç”¨ï¼Œå¦å‰‡æŒ‡å®š | -| | CPUFREQ_ETERNAL） | +|policy->cpuinfo.transition_latency | CPUåœ¨å…©å€‹é »çŽ‡ä¹‹é–“åˆ‡æ›æ‰€éœ€çš„時間，以 | +| | ç´ç§’爲單ä½ï¼ˆå¦‚ä¸é©ç”¨ï¼Œè¨å®šçˆ² | +| | CPUFREQ_ETERNAL） | +| | | +-----------------------------------+--------------------------------------+ -|policy->cur | 該CPU當å‰çš„å·¥ä½œé »çŽ‡(如é©ç”¨) | -| | | +|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->min, | å¿…é ˆåŒ…å«è©²CPUçš„"默èªç–ç•¥"。ç¨å¾Œ | +|policy->max, | 會用這些值調用 | +|policy->policy and, if necessary, | cpufreq_driver.verify和下é¢å‡½æ•¸ | +|policy->governor | 之一：cpufreq_driver.setpolicy或 | +| | cpufreq_driver.target/target_index | +| | | +-----------------------------------+--------------------------------------+ -|policy->cpus | 用與這個CPU一起åšDVFSçš„(在線+離線) | -| | CPU(å³èˆ‡å®ƒå…±äº«æ™‚é˜/電壓軌)的掩碼更新 | -| | 這個 | -| | | +|policy->cpus | 該policy通éŽDVFS框架影響的全部CPU | +| | (å³èˆ‡æœ¬CPU共享"時é˜/電壓"å°)æ§‹æˆ | +| | 掩碼(åŒæ™‚包å«åœ¨ç·šå’Œé›¢ç·šCPU)，用掩碼 | +| | 更新本å—段 | +| | | +-----------------------------------+--------------------------------------+ -å°æ–¼è¨ç½®å…¶ä¸çš„一些值(cpuinfo.min[max]_freq, policy->min[max])ï¼Œé »çŽ‡è¡¨åŠ©æ‰‹å¯èƒ½æœƒæœ‰å¹« +å°æ–¼è¨ç½®å…¶ä¸çš„一些值(cpuinfo.min[max]_freq, policy->min[max])ï¼Œé »çŽ‡è¡¨è¼”åŠ©å‡½æ•¸å¯èƒ½æœƒæœ‰å¹« 助。關於它們的更多信æ¯ï¼Œè«‹åƒè¦‹ç¬¬2節。 1.3 é©—è‰ -------- -當用戶決定è¨ç½®ä¸€å€‹æ–°çš„ç–ç•¥(ç”± 「policy,governor,min,max組æˆã€)æ™‚ï¼Œå¿…é ˆå°é€™å€‹ç–略進行驗è‰ï¼Œ +當用戶決定è¨ç½®ä¸€å€‹æ–°çš„ç–ç•¥(ç”±"policy,governor,min,max組æˆ")æ™‚ï¼Œå¿…é ˆå°é€™å€‹ç–略進行驗è‰ï¼Œ 以便糾æ£ä¸å…¼å®¹çš„值。爲了驗è‰é€™äº›å€¼ï¼Œcpufreq_verify_within_limits(``struct cpufreq_policy *policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函數å¯èƒ½æœƒæœ‰å¹«åŠ©ã€‚ -é—œæ–¼é »çŽ‡è¡¨åŠ©æ‰‹çš„è©³ç´°å…§å®¹è«‹åƒè¦‹ç¬¬2節。 +é—œæ–¼é »çŽ‡è¡¨è¼”åŠ©å‡½æ•¸çš„è©³ç´°å…§å®¹è«‹åƒè¦‹ç¬¬2節。 您需è¦ç¢ºä¿è‡³å°‘æœ‰ä¸€å€‹æœ‰æ•ˆé »çŽ‡ï¼ˆæˆ–å·¥ä½œç¯„åœï¼‰åœ¨ policy->min å’Œ policy->max 範åœå…§ã€‚如果有必 -è¦ï¼Œå…ˆå¢žåŠ policy->max，åªæœ‰åœ¨æ²’有辦法的情æ³ä¸‹ï¼Œæ‰æ¸›å°‘policy->min。 +è¦ï¼Œå…ˆå¢žå¤§policy->max，åªæœ‰åœ¨æ²’有解決方案的情æ³ä¸‹ï¼Œæ‰æ¸›å°policy->min。 1.4 target 或 target_index 或 setpolicy 或 fast_switch? ------------------------------------------------------- -大多數cpufreq驅動甚至大多數cpué »çŽ‡å‡é™ç®—法åªå…許將CPUé »çŽ‡è¨ç½®çˆ²é 定義的固定值。å°æ–¼é€™äº›ï¼Œä½ +大多數cpufreq驅動甚至大多數CPUé »çŽ‡å‡é™ç®—法åªå…許將CPUé »çŽ‡è¨ç½®çˆ²é 定義的固定值。å°æ–¼é€™äº›ï¼Œä½ å¯ä»¥ä½¿ç”¨->target()，->target_index()或->fast_switch()回調。 -有些cpufreq功能的處ç†å™¨å¯ä»¥è‡ªå·±åœ¨æŸäº›é™åˆ¶ä¹‹é–“切æ›é »çŽ‡ã€‚這些應使用->setpolicy()回調。 +æœ‰äº›å…·æœ‰ç¡¬ä»¶èª¿é »èƒ½åŠ›çš„è™•ç†å™¨å¯ä»¥è‡ªè¡Œä¾æ“šæŸäº›é™åˆ¶ä¾†åˆ‡æ›CPUé »çŽ‡ã€‚å®ƒå€‘æ‡‰ä½¿ç”¨->setpolicy()回調。 1.5. target/target_index ------------------------ -target_index調用有兩個åƒæ•¸ï¼š``struct cpufreq_policy * policy``å’Œ``unsigned int`` -索引(æ–¼åˆ—å‡ºçš„é »çŽ‡è¡¨)。 +target_index調用有兩個åƒæ•¸ï¼š ``struct cpufreq_policy * policy`` å’Œ ``unsigned int`` +索引(ç”¨æ–¼ç´¢å¼•é »çŽ‡è¡¨é …)。 -當調用這裡時，CPUfreqé©…å‹•å¿…é ˆè¨ç½®æ–°çš„é »çŽ‡ã€‚å¯¦éš›é »çŽ‡å¿…é ˆç”±freq_table[index].frequency決定。 +當調用這è£æ™‚，CPUfreqé©…å‹•å¿…é ˆè¨ç½®æ–°çš„é »çŽ‡ã€‚å¯¦éš›é »çŽ‡å¿…é ˆç”±freq_table[index].frequency決定。 -它應該總是在錯誤的情æ³ä¸‹æ¢å¾©åˆ°ä¹‹å‰çš„é »çŽ‡(å³policy->restore_freq)，å³ä½¿æˆ‘們之å‰åˆ‡æ›åˆ°ä¸é–“é »çŽ‡ã€‚ +在發生錯誤的情æ³ä¸‹ç¸½æ˜¯æ‡‰è©²æ¢å¾©åˆ°ä¹‹å‰çš„é »çŽ‡(å³policy->restore_freq)，å³ä½¿æˆ‘們已經切æ›åˆ°äº† +ä¸é–“é »çŽ‡ã€‚ 已棄用 ---------- -目標調用有三個åƒæ•¸ã€‚``struct cpufreq_policy * policy``, unsigned int target_frequency, +target調用有三個åƒæ•¸ã€‚``struct cpufreq_policy * policy``, unsigned int target_frequency, unsigned int relation. -CPUfreqé©…å‹•åœ¨èª¿ç”¨é€™è£¡æ™‚å¿…é ˆè¨ç½®æ–°çš„é »çŽ‡ã€‚å¯¦éš›çš„é »çŽ‡å¿…é ˆä½¿ç”¨ä»¥ä¸‹è¦å‰‡ä¾†ç¢ºå®šã€‚ +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節。 +這è£ï¼Œé »çŽ‡è¡¨è¼”助函數å¯èƒ½æœƒå¹«åŠ©ä½ -- 詳見第2節。 1.6. fast_switch ---------------- @@ -196,51 +197,52 @@ CPUfreqé©…å‹•åœ¨èª¿ç”¨é€™è£¡æ™‚å¿…é ˆè¨ç½®æ–°çš„é »çŽ‡ã€‚å¯¦éš›çš„é »çŽ‡å¿…é ˆä 1.7 setpolicy ------------- -setpolicy調用åªéœ€è¦ä¸€å€‹``struct cpufreq_policy * policy``作爲åƒæ•¸ã€‚需è¦å°‡è™•ç†å™¨å…§æˆ–æ™¶ç‰‡çµ„å…§å‹•æ…‹é » +setpolicy調用åªéœ€è¦ä¸€å€‹ ``struct cpufreq_policy * policy`` 作爲åƒæ•¸ã€‚需è¦å°‡è™•ç†å™¨å…§æˆ–èŠ¯ç‰‡çµ„å…§å‹•æ…‹é » 率切æ›çš„下é™è¨ç½®çˆ²policy->min，上é™è¨ç½®çˆ²policy->max，如果支æŒçš„話，當policy->policy爲 -CPUFREQ_POLICY_PERFORMANCE時é¸æ“‡é¢å‘性能的è¨ç½®ï¼Œç•¶CPUFREQ_POLICY_POWERSAVE時é¸æ“‡é¢å‘çœé›»çš„è¨ç½®ã€‚ +CPUFREQ_POLICY_PERFORMANCE時é¸æ“‡é¢å‘性能的è¨ç½®ï¼Œçˆ²CPUFREQ_POLICY_POWERSAVE時é¸æ“‡é¢å‘çœé›»çš„è¨ç½®ã€‚ 也å¯ä»¥æŸ¥çœ‹drivers/cpufreq/longrun.cä¸çš„åƒè€ƒå¯¦ç¾ã€‚ 1.8 get_intermediate å’Œ target_intermediate -------------------------------------------- -僅é©ç”¨æ–¼ target_index() å’Œ CPUFREQ_ASYNC_NOTIFICATION 未è¨ç½®çš„驅動。 +僅é©ç”¨æ–¼æœªè¨ç½® target_index() å’Œ CPUFREQ_ASYNC_NOTIFICATION 的驅動。 -get_intermediate應該返回一個平å°æƒ³è¦åˆ‡æ›åˆ°çš„穩定的ä¸é–“é »çŽ‡ï¼Œtarget_intermediate()應該將CPUè¨ç½®çˆ² -è©²é »çŽ‡ï¼Œç„¶å¾Œå†è·³è½‰åˆ°'index'å°æ‡‰çš„é »çŽ‡ã€‚æ ¸å¿ƒæœƒè² è²¬ç™¼é€é€šçŸ¥ï¼Œé©…å‹•ä¸å¿…在target_intermediate()或 -target_index()ä¸è™•ç†ã€‚ +get_intermediate應該返回一個平臺想è¦åˆ‡æ›åˆ°çš„穩定的ä¸é–“é »çŽ‡ï¼Œtarget_intermediate()應該將CPUè¨ç½®çˆ² +è©²é »çŽ‡ï¼Œç„¶å¾Œå†è·³è½‰åˆ°'index'å°æ‡‰çš„é »çŽ‡ã€‚cpufreqæ ¸å¿ƒæœƒè² è²¬ç™¼é€é€šçŸ¥ï¼Œé©…å‹•ä¸å¿…在 +target_intermediate()或target_index()ä¸è™•ç†å®ƒå€‘。 -在驅動程åºä¸æƒ³å› 爲æŸå€‹ç›®æ¨™é »çŽ‡åˆ‡æ›åˆ°ä¸é–“é »çŽ‡çš„æƒ…æ³ä¸‹ï¼Œå®ƒå€‘å¯ä»¥å¾žget_intermediate()ä¸è¿”回'0'ã€‚åœ¨é€™ç¨®æƒ…æ³ -ä¸‹ï¼Œæ ¸å¿ƒå°‡ç›´æŽ¥èª¿ç”¨->target_index()。 +在驅動程åºä¸æƒ³çˆ²æŸå€‹ç›®æ¨™é »çŽ‡åˆ‡æ›åˆ°ä¸é–“é »çŽ‡çš„æƒ…æ³ä¸‹ï¼Œå®ƒå€‘å¯ä»¥è®“get_intermediate()返回'0'。 +在這種情æ³ä¸‹ï¼Œcpufreqæ ¸å¿ƒå°‡ç›´æŽ¥èª¿ç”¨->target_index()。 -注æ„：->target_index()應該在失敗的情æ³ä¸‹æ¢å¾©åˆ°policy->restore_freqï¼Œå› çˆ²core會爲æ¤ç™¼é€é€šçŸ¥ã€‚ +注æ„：->target_index()應該在發生失敗的情æ³ä¸‹å°‡é »çŽ‡æ¢å¾©åˆ°policy->restore_freq， +å› çˆ²cpufreqæ ¸å¿ƒæœƒçˆ²æ¤ç™¼é€é€šçŸ¥ã€‚ -2. é »çŽ‡è¡¨åŠ©æ‰‹ -============= +2. é »çŽ‡è¡¨è¼”åŠ©å‡½æ•¸ +================= -由於大多數cpufreq處ç†å™¨åªå…許被è¨ç½®çˆ²å¹¾å€‹ç‰¹å®šçš„é »çŽ‡ï¼Œå› æ¤ï¼Œä¸€å€‹å¸¶æœ‰ä¸€äº›å‡½æ•¸çš„ ã€Œé »çŽ‡è¡¨ã€å¯èƒ½æœƒè¼”助處ç†å™¨é©…å‹• -程åºçš„一些工作。這樣的 "é »çŽ‡è¡¨" 由一個cpufreq_frequency_tableæ¢ç›®æ§‹æˆçš„數組組æˆï¼Œ"driver_data" ä¸åŒ… -å«äº†é©…動程åºçš„具體數值，"frequency" ä¸åŒ…å«äº†ç›¸æ‡‰çš„é »çŽ‡ï¼Œä¸¦è¨ç½®äº†æ¨™èªŒã€‚在表的最後，需è¦æ·»åŠ 一個 -cpufreq_frequency_tableæ¢ç›®ï¼Œé »çŽ‡è¨ç½®çˆ²CPUFREQ_TABLE_END。而如果想跳éŽè¡¨ä¸çš„一個æ¢ç›®ï¼Œå‰‡å°‡é »çŽ‡è¨ç½®çˆ² -CPUFREQ_ENTRY_INVALID。這些æ¢ç›®ä¸éœ€è¦æŒ‰ç…§ä»»ä½•ç‰¹å®šçš„é †åºæŽ’åºï¼Œä½†å¦‚果它們是cpufreq æ ¸å¿ƒæœƒå°å®ƒå€‘進行快速的DVFS， +由於大多數支æŒcpufreq的處ç†å™¨åªå…許被è¨ç½®çˆ²å¹¾å€‹ç‰¹å®šçš„é »çŽ‡ï¼Œå› æ¤ï¼Œ"é »çŽ‡è¡¨"和一些相關函數å¯èƒ½æœƒè¼”助處ç†å™¨é©…å‹• +程åºçš„一些工作。這樣的"é »çŽ‡è¡¨"是一個由struct cpufreq_frequency_tableçš„æ¢ç›®æ§‹æˆçš„數組，"driver_data"æˆå“¡åŒ… +å«é©…動程åºçš„專用值，"frequency"æˆå“¡åŒ…å«äº†ç›¸æ‡‰çš„é »çŽ‡ï¼Œæ¤å¤–還有標誌æˆå“¡ã€‚在表的最後，需è¦æ·»åŠ 一個 +cpufreq_frequency_tableæ¢ç›®ï¼Œé »çŽ‡è¨ç½®çˆ²CPUFREQ_TABLE_END。如果想跳éŽè¡¨ä¸çš„一個æ¢ç›®ï¼Œå‰‡å°‡é »çŽ‡è¨ç½®çˆ² +CPUFREQ_ENTRY_INVALID。這些æ¢ç›®ä¸éœ€è¦æŒ‰ç…§ä»»ä½•ç‰¹å®šçš„é †åºæŽ’åºï¼Œå¦‚果排åºäº†ï¼Œcpufreqæ ¸å¿ƒåŸ·è¡ŒDVFS會更快一點， å› çˆ²æœç´¢æœ€ä½³åŒ¹é…會更快。 -如果ç–略在其policy->freq_table欄ä½ä¸åŒ…å«ä¸€å€‹æœ‰æ•ˆçš„指é‡ï¼Œcpufreqè¡¨å°±æœƒè¢«æ ¸å¿ƒè‡ªå‹•é©—è‰ã€‚ +如果在policy->freq_tableå—段ä¸åŒ…å«ä¸€å€‹æœ‰æ•ˆçš„é »çŽ‡è¡¨æŒ‡é‡ï¼Œé »çŽ‡è¡¨å°±æœƒè¢«cpufreqæ ¸å¿ƒè‡ªå‹•é©—è‰ã€‚ cpufreq_frequency_table_verify()ä¿è‰è‡³å°‘æœ‰ä¸€å€‹æœ‰æ•ˆçš„é »çŽ‡åœ¨policy->minå’Œpolicy->max範åœå…§ï¼Œä¸¦ä¸”所有其他 -標準都被滿足。這å°->verify調用很有幫助。 +準則都被滿足。這å°->verify調用很有幫助。 -cpufreq_frequency_table_target()是å°æ‡‰æ–¼->targetéšŽæ®µçš„é »çŽ‡è¡¨åŠ©æ‰‹ã€‚åªè¦æŠŠæ•¸å€¼å‚³éžçµ¦é€™å€‹å‡½æ•¸ï¼Œé€™å€‹å‡½æ•¸å°±æœƒè¿” +cpufreq_frequency_table_target()是å°æ‡‰æ–¼->targetéšŽæ®µçš„é »çŽ‡è¡¨è¼”åŠ©å‡½æ•¸ã€‚åªè¦æŠŠå€¼å‚³éžçµ¦é€™å€‹å‡½æ•¸ï¼Œé€™å€‹å‡½æ•¸å°±æœƒè¿” 回包å«CPUè¦è¨ç½®çš„é »çŽ‡çš„é »çŽ‡è¡¨æ¢ç›®ã€‚ -以下å®å¯ä»¥ä½œçˆ²cpufreq_frequency_table的疊代器。 +以下å®å¯ä»¥ä½œçˆ²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 * `` 。 +使用åƒæ•¸"pos" -- 一個 ``cpufreq_frequency_table *`` 作爲循環指é‡ï¼Œä½¿ç”¨åƒæ•¸"table" -- ä½œçˆ²ä½ æƒ³è¿ä»£ +çš„ ``cpufreq_frequency_table *`` 。 例如:: @@ -251,6 +253,6 @@ cpufreq_for_each_valid_entry(pos, table) - 該函數éæ·æ‰€æœ‰æ¢ç›®ï¼Œä¸åŒ…æ pos->frequency = ... } -å¦‚æžœä½ éœ€è¦åœ¨driver_freq_tableä¸è™•ç†posçš„ä½ç½®ï¼Œä¸è¦æ¸›åŽ»æŒ‡é‡ï¼Œå› 爲它的代價相當高。相åï¼Œä½¿ç”¨å® +å¦‚æžœä½ éœ€è¦åœ¨driver_freq_tableä¸è™•ç†posçš„ä½ç½®ï¼Œä¸è¦åšæŒ‡é‡æ¸›æ³•ï¼Œå› çˆ²å®ƒçš„ä»£åƒ¹ç›¸ç•¶é«˜ã€‚ä½œçˆ²æ›¿ä»£ï¼Œä½¿ç”¨å® cpufreq_for_each_entry_idx() å’Œ cpufreq_for_each_valid_entry_idx() 。 diff --git a/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst index 49088becd5fa..01ec8c837fe9 100644 --- a/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst +++ b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst @@ -2,18 +2,21 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/cpufreq-stats` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res.211@gmail.com> +:Original: Documentation/cpu-freq/cpufreq-stats.rst -.. _tw_cpufreq-stats.rst: +:ç¿»è¯: + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> + +:æ ¡è¯: + + å”è—舟 Tang Yizhou <tangyeechou@gmail.com> ========================================== sysfs CPUFreq Stats的一般說明 ========================================== -ç”¨æˆ¶ä¿¡æ¯ +çˆ²ä½¿ç”¨è€…æº–å‚™çš„ä¿¡æ¯ ä½œè€…: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> @@ -28,17 +31,16 @@ sysfs CPUFreq Stats的一般說明 1. 簡介 =============== -cpufreq-stats是一個爲æ¯å€‹CPUæä¾›CPUé »çŽ‡çµ±è¨ˆçš„é©…å‹•ã€‚ -這些統計數據在/sysfsä¸ä»¥ä¸€å †åªè®€æŽ¥å£çš„å½¢å¼æ供。這個接å£ï¼ˆåœ¨é…置好後）將出ç¾åœ¨ -/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）ä¸cpufreq下的一個單 -ç¨çš„目錄ä¸ï¼Œæ供給æ¯å€‹CPU。 -å„種統計數據將在æ¤ç›®éŒ„下形æˆåªè®€æ–‡ä»¶ã€‚ +cpufreq-stats是一種爲æ¯å€‹CPUæä¾›CPUé »çŽ‡çµ±è¨ˆçš„é©…å‹•ã€‚ +這些統計數據以/sysfsä¸ä¸€ç³»åˆ—åªè®€æŽ¥å£çš„å½¢å¼å‘ˆç¾ã€‚cpufreq-stats接å£ï¼ˆè‹¥å·²é…置）將爲æ¯å€‹CPUç”Ÿæˆ +/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）ä¸cpufreq目錄下的stats目錄。 +å„é …çµ±è¨ˆæ•¸æ“šå°‡åœ¨stats目錄下形æˆå°æ‡‰çš„åªè®€æ–‡ä»¶ã€‚ -æ¤é©…動是ç¨ç«‹æ–¼ä»»ä½•å¯èƒ½é‹è¡Œåœ¨ä½ 所用CPU上的特定cpufreq_driver而è¨è¨ˆçš„ã€‚å› æ¤ï¼Œå®ƒå°‡èˆ‡æ‰€æœ‰ -cpufreq_driver一起工作。 +æ¤é©…動是以ç¨ç«‹æ–¼ä»»ä½•å¯èƒ½é‹è¡Œåœ¨ä½ 所用CPU上的特定cpufreq_driverçš„æ–¹å¼è¨è¨ˆçš„ã€‚å› æ¤ï¼Œå®ƒå°‡èƒ½å’Œä»»ä½• +cpufreq_driverå”åŒå·¥ä½œã€‚ -2. æ供的統計數據(舉例說明) +2. å·²æ供的統計數據(有例å) ===================================== cpufreq statsæ供了以下統計數據（在下é¢è©³ç´°è§£é‡‹ï¼‰ã€‚ @@ -47,8 +49,8 @@ cpufreq statsæ供了以下統計數據（在下é¢è©³ç´°è§£é‡‹ï¼‰ã€‚ - total_trans - trans_table -所有的統計數據將從統計驅動被載入的時間（或統計被é‡ç½®çš„時間）開始，到æŸä¸€çµ±è¨ˆæ•¸æ“šè¢«è®€å–的時間爲æ¢ã€‚ -顯然，統計驅動ä¸æœƒæœ‰ä»»ä½•é—œæ–¼çµ±è¨ˆé©…動載入之å‰çš„é »çŽ‡è½‰æ›ä¿¡æ¯ã€‚ +所有統計數據來自以下時間範åœï¼šå¾žçµ±è¨ˆé©…å‹•è¢«åŠ è¼‰çš„æ™‚é–“ï¼ˆæˆ–çµ±è¨ˆæ•¸æ“šè¢«é‡ç½®çš„時間）開始，到æŸä¸€çµ±è¨ˆæ•¸æ“šè¢«è®€å–的時間爲æ¢ã€‚ +顯然，統計驅動ä¸æœƒä¿å˜å®ƒè¢«åŠ 載之å‰çš„ä»»ä½•é »çŽ‡è½‰æ›ä¿¡æ¯ã€‚ :: @@ -63,14 +65,14 @@ cpufreq statsæ供了以下統計數據（在下é¢è©³ç´°è§£é‡‹ï¼‰ã€‚ - **reset** -åªå¯«å±¬æ€§ï¼Œå¯ç”¨æ–¼é‡ç½®çµ±è¨ˆè¨ˆæ•¸å™¨ã€‚這å°æ–¼è©•ä¼°ä¸åŒèª¿ç¯€å™¨ä¸‹çš„系統行爲éžå¸¸æœ‰ç”¨ï¼Œä¸”無需é‡å•“。 +åªå¯«å±¬æ€§ï¼Œå¯ç”¨æ–¼é‡ç½®çµ±è¨ˆè¨ˆæ•¸å™¨ã€‚這å°æ–¼è©•ä¼°ä¸åŒèª¿ç¯€å™¨çš„系統行爲éžå¸¸æœ‰ç”¨ï¼Œä¸”無需é‡å•“。 - **time_in_state** -æ¤é …給出了這個CPU所支æŒçš„æ¯å€‹é »çŽ‡æ‰€èŠ±è²»çš„時間。cat輸出的æ¯ä¸€è¡Œéƒ½æœƒæœ‰"<frequency> -<time>"å°ï¼Œè¡¨ç¤ºé€™å€‹CPU在<frequency>上花費了<time>個usertimeå–®ä½çš„時間。這裡的 -usertimeå–®ä½æ˜¯10mS（類似於/procä¸è¼¸å‡ºçš„其他時間）。 +æ¤æ–‡ä»¶çµ¦å‡ºäº†åœ¨æœ¬CPU支æŒçš„æ¯å€‹é »çŽ‡ä¸Šåˆ†åˆ¥èŠ±è²»çš„時間。cat輸出的æ¯ä¸€è¡Œéƒ½æ˜¯ä¸€å€‹"<frequency> +<time>"å°ï¼Œè¡¨ç¤ºé€™å€‹CPU在<frequency>上花費了<time>個usertimeå–®ä½çš„時間。輸出的æ¯ä¸€è¡Œå°æ‡‰ +一個CPU支æŒçš„é »çŽ‡ã€‚é€™è£usertimeå–®ä½æ˜¯10mS（類似於/proc導出的其它時間）。 :: @@ -84,7 +86,7 @@ usertimeå–®ä½æ˜¯10mS（類似於/procä¸è¼¸å‡ºçš„其他時間）。 - **total_trans** -給出了這個CPUä¸Šé »çŽ‡è½‰æ›çš„總次數。catçš„è¼¸å‡ºå°‡æœ‰ä¸€å€‹å–®ä¸€çš„è¨ˆæ•¸ï¼Œé€™å°±æ˜¯é »çŽ‡è½‰æ›çš„總數。 +æ¤æ–‡ä»¶çµ¦å‡ºäº†é€™å€‹CPUé »çŽ‡è½‰æ›çš„總次數。catçš„è¼¸å‡ºæ˜¯ä¸€å€‹è¨ˆæ•¸å€¼ï¼Œå®ƒå°±æ˜¯é »çŽ‡è½‰æ›çš„總次數。 :: @@ -93,10 +95,10 @@ usertimeå–®ä½æ˜¯10mS（類似於/procä¸è¼¸å‡ºçš„其他時間）。 - **trans_table** -這將æ供所有CPUé »çŽ‡è½‰æ›çš„細粒度信æ¯ã€‚這裡的cat輸出是一個二ç¶çŸ©é™£ï¼Œå…¶ä¸ä¸€å€‹æ¢ç›®<i, j>（第 +本文件æ供所有CPUé »çŽ‡è½‰æ›çš„細粒度信æ¯ã€‚這è£çš„cat輸出是一個二ç¶çŸ©é™£ï¼Œå…¶ä¸ä¸€å€‹æ¢ç›®<i, j>（第 i行，第j列）代表從Freq_i到Freq_j的轉æ›æ¬¡æ•¸ã€‚Freq_i行和Freq_j列éµå¾ªé©…動最åˆæ供給cpufreq -æ ¸çš„é »çŽ‡è¡¨çš„æŽ’åºé †åºï¼Œå› æ¤å¯ä»¥æŽ’åºï¼ˆå‡åºæˆ–é™åºï¼‰æˆ–ä¸æŽ’åºã€‚ 這裡的輸出也包å«äº†æ¯è¡Œæ¯åˆ—的實際 -é »çŽ‡å€¼ï¼Œä»¥ä¾¿æ›´å¥½åœ°é–±è®€ã€‚ +æ ¸å¿ƒçš„é »çŽ‡è¡¨çš„æŽ’åˆ—é †åºï¼Œå› æ¤å¯ä»¥å·²æŽ’åºï¼ˆå‡åºæˆ–é™åºï¼‰æˆ–未排åºã€‚這è£çš„輸出也包å«äº†å¯¦éš› +é »çŽ‡å€¼ï¼Œåˆ†åˆ¥æŒ‰è¡Œå’ŒæŒ‰åˆ—é¡¯ç¤ºï¼Œä»¥ä¾¿æ›´å¥½åœ°é–±è®€ã€‚ 如果轉æ›è¡¨å¤§æ–¼PAGE_SIZE，讀å–時將返回一個-EFBIG錯誤。 @@ -114,7 +116,7 @@ i行，第j列）代表從Freq_i到Freq_j的轉æ›æ¬¡æ•¸ã€‚Freq_i行和Freq_j列 3. é…ç½®cpufreq-stats ============================ -è¦åœ¨ä½ çš„å…§æ ¸ä¸é…ç½®cpufreq-stats:: +按以下方å¼åœ¨ä½ çš„å…§æ ¸ä¸é…ç½®cpufreq-stats:: Config Main Menu Power management options (ACPI, APM) ---> @@ -123,7 +125,7 @@ i行，第j列）代表從Freq_i到Freq_j的轉æ›æ¬¡æ•¸ã€‚Freq_i行和Freq_j列 [*] CPU frequency translation statistics -"CPU Frequency scaling" (CONFIG_CPU_FREQ) 應該被啓用以é…ç½®cpufreq-stats。 +"CPU Frequency scaling" (CONFIG_CPU_FREQ) 應該被啓用，以支æŒé…ç½®cpufreq-stats。 "CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT)æ供了包括 time_in_stateã€total_transå’Œtrans_table的統計數據。 diff --git a/Documentation/translations/zh_TW/cpu-freq/index.rst b/Documentation/translations/zh_TW/cpu-freq/index.rst index c6cf825b57a5..a9df16870b21 100644 --- a/Documentation/translations/zh_TW/cpu-freq/index.rst +++ b/Documentation/translations/zh_TW/cpu-freq/index.rst @@ -2,12 +2,13 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../cpu-freq/index` -:Translator: Yanteng Si <siyanteng@loongson.cn> - Hu Haowen <src.res.211@gmail.com> +:Original: Documentation/cpu-freq/index.rst -.. _tw_index.rst: +:ç¿»è¯: + + å¸å»¶é¨° Yanteng Si <siyanteng@loongson.cn> +.. _tw_index.rst: ======================================================= Linux CPUFreq - Linux(TM)å…§æ ¸ä¸çš„CPUé »çŽ‡å’Œé›»å£“å‡é™ä»£ç¢¼ @@ -28,10 +29,10 @@ Author: Dominik Brodowski <linux@brodo.de> 郵件列表 ------------ -這裡有一個 CPU é »çŽ‡è®ŠåŒ–çš„ CVS æ交和通用列表，您å¯ä»¥åœ¨é€™è£¡å ±å‘Šbugã€å•é¡Œæˆ–æ交補ä¸ã€‚è¦ç™¼ +這è£æœ‰ä¸€å€‹ CPU é »çŽ‡è®ŠåŒ–çš„ CVS æ交和通用列表，您å¯ä»¥åœ¨é€™è£å ±å‘Šbugã€å•é¡Œæˆ–æ交補ä¸ã€‚è¦ç™¼ 布消æ¯ï¼Œè«‹ç™¼é€é›»å郵件到 linux-pm@vger.kernel.org。 -é€£çµ +éˆæŽ¥ ----- FTP檔案: * ftp://ftp.linux.org.uk/pub/linux/cpufreq/ diff --git a/Documentation/translations/zh_TW/dev-tools/gcov.rst b/Documentation/translations/zh_TW/dev-tools/gcov.rst new file mode 100644 index 000000000000..ce1c9a97de16 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/gcov.rst @@ -0,0 +1,265 @@ +.. include:: ../disclaimer-zh_TW.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_TW/dev-tools/gdb-kernel-debugging.rst b/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst new file mode 100644 index 000000000000..c881e8872b19 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst @@ -0,0 +1,168 @@ +.. highlight:: none + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/gdb-kernel-debugging.rst +:Translator: 高超 gao chao <gaochao49@huawei.com> + +通éŽgdbèª¿è©¦å…§æ ¸å’Œæ¨¡å¡Š +===================== + +Kgdbå…§æ ¸èª¿è©¦å™¨ã€QEMUç‰è™›æ“¬æ©Ÿç®¡ç†ç¨‹åºæˆ–基於JTAG的硬件接å£ï¼Œæ”¯æŒåœ¨é‹è¡Œæ™‚使用gdb +調試Linuxå…§æ ¸åŠå…¶æ¨¡å¡Šã€‚Gdbæ供了一個強大的python腳本接å£ï¼Œå…§æ ¸ä¹Ÿæ供了一套 +è¼”åŠ©è…³æœ¬ä»¥ç°¡åŒ–å…¸åž‹çš„å…§æ ¸èª¿è©¦æ¥é©Ÿã€‚本文檔爲如何啓用和使用這些腳本æ供了一個簡è¦çš„教程。 +æ¤æ•™ç¨‹åŸºæ–¼QEMU/KVM虛擬機，但文ä¸ç¤ºä¾‹ä¹Ÿé©ç”¨æ–¼å…¶ä»–gdb stub。 + + +環境é…ç½®è¦æ±‚ +------------ + +- gdb 7.2+ (推薦版本: 7.4+) 且開啓pythonæ”¯æŒ (通常發行版上都已支æŒ) + +è¨ç½® +---- + +- 創建一個QEMU/KVMçš„linux虛擬機（詳情請åƒè€ƒ www.linux-kvm.org å’Œ www.qemu.org ）。 + å°æ–¼äº¤å‰é–‹ç™¼ï¼Œhttps://landley.net/aboriginal/bin æ供了一些é¡åƒå’Œå·¥å…·éˆï¼Œ + å¯ä»¥å¹«åŠ©æ建交å‰é–‹ç™¼ç’°å¢ƒã€‚ + +- ç·¨è¯å…§æ ¸æ™‚é–‹å•“CONFIG_GDB_SCRIPTS，關閉CONFIG_DEBUG_INFO_REDUCED。 + 如果架構支æŒCONFIG_FRAME_POINTER，請ä¿æŒé–‹å•“。 + +- 在guest環境上安è£è©²å…§æ ¸ã€‚如有必è¦ï¼Œé€šéŽåœ¨å…§æ ¸command lineä¸æ·»åŠ “nokaslrâ€ä¾†é—œé–‰KASLR。 + æ¤å¤–，QEMUå…許通éŽ-kernelã€-appendã€-initrd這些命令行é¸é …ç›´æŽ¥å•“å‹•å…§æ ¸ã€‚ + 但這通常僅在ä¸ä¾è³´å…§æ ¸æ¨¡å¡Šæ™‚纔有效。有關æ¤æ¨¡å¼çš„更多詳細信æ¯ï¼Œè«‹åƒé–±QEMU文檔。 + 在這種情æ³ä¸‹ï¼Œå¦‚果架構支æŒKASLR，應該在ç¦ç”¨CONFIG_RANDOMIZE_BASE的情æ³ä¸‹æ§‹å»ºå…§æ ¸ã€‚ + +- 啓用QEMU/KVMçš„gdb stub，å¯ä»¥é€šéŽå¦‚下方å¼å¯¦ç¾ + + - 在VM啓動時，通éŽåœ¨QEMU命令行ä¸æ·»åŠ “-sâ€åƒæ•¸ + + 或 + + - 在é‹è¡Œæ™‚通éŽå¾žQEMU監視控制檯發é€â€œgdbserver†+ +- 切æ›åˆ°/path/to/linux-build(å…§æ ¸æºç¢¼ç·¨è¯)目錄 + +- å•“å‹•gdb：gdb vmlinux + + 注æ„：æŸäº›ç™¼è¡Œç‰ˆå¯èƒ½æœƒå°‡gdbè…³æœ¬çš„è‡ªå‹•åŠ è¼‰é™åˆ¶åœ¨å·²çŸ¥çš„安全目錄ä¸ã€‚ + 如果gdbå ±å‘Šæ‹’çµ•åŠ è¼‰vmlinux-gdb.py（相關命令找ä¸åˆ°ï¼‰ï¼Œè«‹å°‡:: + + add-auto-load-safe-path /path/to/linux-build + + æ·»åŠ åˆ°~/.gdbinit。更多詳細信æ¯ï¼Œè«‹åƒé–±gdb幫助信æ¯ã€‚ + +- 連接到已啓動的guest環境:: + + (gdb) target remote :1234 + + +使用Linuxæ供的gdb腳本的示例 +---------------------------- + +- åŠ è¼‰æ¨¡å¡Šï¼ˆä»¥åŠä¸»å…§æ ¸ï¼‰ç¬¦è™Ÿ:: + + (gdb) lx-symbols + loading vmlinux + scanning for modules in /home/user/linux/build + loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko + loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko + loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko + loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko + loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko + ... + loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko + +- å°ä¸€äº›å°šæœªåŠ 載的模塊ä¸çš„函數函數è¨ç½®æ–·é»žï¼Œä¾‹å¦‚:: + + (gdb) b btrfs_init_sysfs + Function "btrfs_init_sysfs" not defined. + Make breakpoint pending on future shared library load? (y or [n]) y + Breakpoint 1 (btrfs_init_sysfs) pending. + +- 繼續執行:: + + (gdb) c + +- åŠ è¼‰æ¨¡å¡Šä¸¦ä¸”èƒ½è§€å¯Ÿåˆ°æ£åœ¨åŠ 載的符號以åŠæ–·é»žå‘½ä¸:: + + loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko + loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko + loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko + loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko + + Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 + 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); + +- æŸ¥çœ‹å…§æ ¸çš„æ—¥èªŒç·©è¡å€:: + + (gdb) lx-dmesg + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Linux version 3.8.0-rc4-dbg+ (... + [ 0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314 + [ 0.000000] e820: BIOS-provided physical RAM map: + [ 0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable + [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved + .... + +- 查看當å‰task structçµæ§‹é«”çš„å—段（僅x86å’Œarm64支æŒï¼‰:: + + (gdb) p $lx_current().pid + $1 = 4998 + (gdb) p $lx_current().comm + $2 = "modprobe\000\000\000\000\000\000\000" + +- å°ç•¶å‰æˆ–指定的CPU使用per-cpu函數:: + + (gdb) p $lx_per_cpu("runqueues").nr_running + $3 = 1 + (gdb) p $lx_per_cpu("runqueues", 2).nr_running + $4 = 0 + +- 使用container_of查看更多hrtimersä¿¡æ¯:: + + (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next + (gdb) p *$container_of($next, "struct hrtimer", "node") + $5 = { + node = { + node = { + __rb_parent_color = 18446612133355256072, + rb_right = 0x0 <irq_stack_union>, + rb_left = 0x0 <irq_stack_union> + }, + expires = { + tv64 = 1835268000000 + } + }, + _softexpires = { + tv64 = 1835268000000 + }, + function = 0xffffffff81078232 <tick_sched_timer>, + base = 0xffff88003fd0d6f0, + state = 1, + start_pid = 0, + start_site = 0xffffffff81055c1f <hrtimer_start_range_ns+20>, + start_comm = "swapper/2\000\000\000\000\000\000" + } + + +命令和輔助調試功能列表 +---------------------- + +命令和輔助調試功能å¯èƒ½æœƒéš¨ç€æ™‚間的推移而改進，æ¤æ–‡é¡¯ç¤ºçš„是åˆå§‹ç‰ˆæœ¬çš„部分示例:: + + (gdb) apropos lx + function lx_current -- Return current task + function lx_module -- Find module by name and return the module variable + function lx_per_cpu -- Return per-cpu variable + function lx_task_by_pid -- Find Linux task by PID and return the task_struct variable + function lx_thread_info -- Calculate Linux thread_info from task variable + lx-dmesg -- Print Linux kernel log buffer + lx-lsmod -- List currently loaded modules + lx-symbols -- (Re-)load symbols of Linux kernel and currently loaded modules + +å¯ä»¥é€šéŽâ€œhelp <command-name>â€æˆ–“help function <function-name>â€å‘½ä»¤ +ç²å–指定命令或指定調試功能的更多詳細信æ¯ã€‚ + diff --git a/Documentation/translations/zh_TW/dev-tools/index.rst b/Documentation/translations/zh_TW/dev-tools/index.rst new file mode 100644 index 000000000000..0d38e5f80e54 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/index.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/index.rst +:Translator: 趙è»å¥Ž Bernard Zhao <bernard@vivo.com> + +============ +å…§æ ¸é–‹ç™¼å·¥å…· +============ + +æœ¬æ–‡æª”æ˜¯æœ‰é—œå…§æ ¸é–‹ç™¼å·¥å…·æ–‡æª”çš„åˆé›†ã€‚ +ç›®å‰é€™äº›æ–‡æª”已經整ç†åœ¨ä¸€èµ·ï¼Œä¸éœ€è¦å†èŠ±è²»é¡å¤–的精力。 +æ¡è¿Žä»»ä½•è£œä¸ã€‚ + +有關測試專用工具的簡è¦æ¦‚述，åƒè¦‹ +Documentation/translations/zh_TW/dev-tools/testing-overview.rst + +.. class:: toc-title + + 目錄 + +.. toctree:: + :maxdepth: 2 + + testing-overview + sparse + gcov + kasan + gdb-kernel-debugging + +Todolist: + + - coccinelle + - kcov + - ubsan + - kmemleak + - kcsan + - kfence + - kgdb + - kselftest + - kunit/index + diff --git a/Documentation/translations/zh_TW/dev-tools/kasan.rst b/Documentation/translations/zh_TW/dev-tools/kasan.rst new file mode 100644 index 000000000000..979eb84bc58f --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/kasan.rst @@ -0,0 +1,463 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/kasan.rst +:Translator: è¬å®¶å…µ Wan Jiabing <wanjiabing@vivo.com> + +å…§æ ¸åœ°å€æ¶ˆæ¯’劑(KASAN) +===================== + +概述 +---- + +Kernel Address SANitizer(KASAN)是一種動態內å˜å®‰å…¨éŒ¯èª¤æª¢æ¸¬å·¥å…·ï¼Œä¸»è¦åŠŸèƒ½æ˜¯ +檢查內å˜è¶Šç•Œè¨ªå•å’Œä½¿ç”¨å·²é‡‹æ”¾å…§å˜çš„å•é¡Œã€‚ + +KASAN有三種模å¼: + +1. 通用KASAN +2. 基於軟件標籤的KASAN +3. 基於硬件標籤的KASAN + +用CONFIG_KASAN_GENERIC啓用的通用KASAN，是用於調試的模å¼ï¼Œé¡žä¼¼æ–¼ç”¨æˆ¶ç©º +é–“çš„ASan。這種模å¼åœ¨è¨±å¤šCPU架構上都被支æŒï¼Œä½†å®ƒæœ‰æ˜Žé¡¯çš„性能和內å˜é–‹éŠ·ã€‚ + +基於軟件標籤的KASAN或SW_TAGS KASAN，通éŽCONFIG_KASAN_SW_TAGS啓用， +å¯ä»¥ç”¨æ–¼èª¿è©¦å’Œè‡ªæˆ‘測試，類似於用戶空間HWASan。這種模å¼åªæ”¯æŒarm64，但其 +é©åº¦çš„å…§å˜é–‹éŠ·å…許在內å˜å—é™çš„è¨å‚™ä¸Šç”¨çœŸå¯¦çš„å·¥ä½œè² è¼‰é€²è¡Œæ¸¬è©¦ã€‚ + +基於硬件標籤的KASAN或HW_TAGS KASAN，用CONFIG_KASAN_HW_TAGS啓用，被 +用作ç¾å ´å…§å˜éŒ¯èª¤æª¢æ¸¬å™¨æˆ–作爲安全緩解的模å¼ã€‚這種模å¼åªåœ¨æ”¯æŒMTE（內å˜æ¨™ç±¤ +擴展）的arm64 CPU上工作，但它的內å˜å’Œæ€§èƒ½é–‹éŠ·å¾ˆä½Žï¼Œå› æ¤å¯ä»¥åœ¨ç”Ÿç”¢ä¸ä½¿ç”¨ã€‚ + +關於æ¯ç¨®KASAN模å¼çš„å…§å˜å’Œæ€§èƒ½å½±éŸ¿çš„細節，請åƒè¦‹ç›¸æ‡‰çš„Kconfigé¸é …çš„æ述。 + +通用模å¼å’ŒåŸºæ–¼è»Ÿä»¶æ¨™ç±¤çš„模å¼é€šå¸¸è¢«ç¨±çˆ²è»Ÿä»¶æ¨¡å¼ã€‚基於軟件標籤的模å¼å’ŒåŸºæ–¼ +硬件標籤的模å¼è¢«ç¨±çˆ²åŸºæ–¼æ¨™ç±¤çš„模å¼ã€‚ + +æ”¯æŒ +---- + +體系架構 +~~~~~~~~ + +在x86_64ã€armã€arm64ã€powerpcã€riscvã€s390ã€xtensaå’Œloongarch上支æŒé€šç”¨KASAN， +而基於標籤的KASAN模å¼åªåœ¨arm64上支æŒã€‚ + +ç·¨è¯å™¨ +~~~~~~ + +軟件KASAN模å¼ä½¿ç”¨ç·¨è¯æ™‚工具在æ¯å€‹å…§å˜è¨ªå•ä¹‹å‰æ’å…¥æœ‰æ•ˆæ€§æª¢æŸ¥ï¼Œå› æ¤éœ€è¦ä¸€å€‹ +æ供支æŒçš„ç·¨è¯å™¨ç‰ˆæœ¬ã€‚基於硬件標籤的模å¼ä¾é 硬件來執行這些檢查，但ä»ç„¶éœ€è¦ +一個支æŒå…§å˜æ¨™ç±¤æŒ‡ä»¤çš„ç·¨è¯å™¨ç‰ˆæœ¬ã€‚ + +通用KASAN需è¦GCC 8.3.0ç‰ˆæœ¬æˆ–æ›´é«˜ç‰ˆæœ¬ï¼Œæˆ–è€…å…§æ ¸æ”¯æŒçš„任何Clang版本。 + +基於軟件標籤的KASAN需è¦GCC 11+æˆ–è€…å…§æ ¸æ”¯æŒçš„任何Clang版本。 + +基於硬件標籤的KASAN需è¦GCC 10+或Clang 12+。 + +å…§å˜é¡žåž‹ +~~~~~~~~ + +通用KASAN支æŒåœ¨æ‰€æœ‰çš„slabã€page_allocã€vmapã€vmallocã€å †æ£§å’Œå…¨å±€å…§å˜ +ä¸æŸ¥æ‰¾éŒ¯èª¤ã€‚ + +基於軟件標籤的KASAN支æŒslabã€page_allocã€vmallocå’Œå †æ£§å…§å˜ã€‚ + +基於硬件標籤的KASAN支æŒslabã€page_allocå’Œä¸å¯åŸ·è¡Œçš„vmallocå…§å˜ã€‚ + +å°æ–¼slab，兩種軟件KASAN模å¼éƒ½æ”¯æŒSLUBå’ŒSLAB分é…器，而基於硬件標籤的 +KASANåªæ”¯æŒSLUB。 + +用法 +---- + +è¦å•“用KASAN，請使用以下命令é…ç½®å…§æ ¸:: + + CONFIG_KASAN=y + +åŒæ™‚在 ``CONFIG_KASAN_GENERIC`` (啓用通用KASAN模å¼)， ``CONFIG_KASAN_SW_TAGS`` +(啓用基於硬件標籤的KASAN模å¼)，和 ``CONFIG_KASAN_HW_TAGS`` (啓用基於硬件標籤 +çš„KASAN模å¼)之間進行é¸æ“‡ã€‚ + +å°æ–¼è»Ÿä»¶æ¨¡å¼ï¼Œé‚„å¯ä»¥åœ¨ ``CONFIG_KASAN_OUTLINE`` å’Œ ``CONFIG_KASAN_INLINE`` +之間進行é¸æ“‡ã€‚outlineå’Œinline是編è¯å™¨æ’æ¨é¡žåž‹ã€‚å‰è€…產生較å°çš„二進制文件， +而後者快2å€ã€‚ + +è¦å°‡å—影響的slabå°è±¡çš„allocå’Œfreeå †æ£§è·Ÿè¹¤åŒ…å«åˆ°å ±å‘Šä¸ï¼Œè«‹å•“用 +``CONFIG_STACKTRACE`` 。è¦åŒ…括å—影響物ç†é é¢çš„分é…å’Œé‡‹æ”¾å †æ£§è·Ÿè¹¤çš„è©±ï¼Œ +請啓用 ``CONFIG_PAGE_OWNER`` 並使用 ``page_owner=on`` 進行引導。 + +å•“å‹•åƒæ•¸ +~~~~~~~~ + +KASANå—到通用 ``panic_on_warn`` 命令行åƒæ•¸çš„影響。當它被啓用時，KASAN +在打å°å‡ºéŒ¯èª¤å ±å‘Šå¾Œæœƒä½¿å…§æ ¸æ慌。 + +默èªæƒ…æ³ä¸‹ï¼ŒKASANåªå°ç¬¬ä¸€å€‹ç„¡æ•ˆçš„å…§å˜è¨ªå•æ‰“å°éŒ¯èª¤å ±å‘Šã€‚使用 +``kasan_multi_shot``，KASANå°æ¯ä¸€å€‹ç„¡æ•ˆçš„訪å•éƒ½æ‰“å°ä¸€ä»½å ±å‘Šã€‚這會ç¦ç”¨ +了KASANå ±å‘Šçš„ ``panic_on_warn``。 + +å¦å¤–，ç¨ç«‹æ–¼ ``panic_on_warn`` 〠``kasan.fault=`` bootåƒæ•¸å¯ä»¥ç”¨ +來控制ææ…Œå’Œå ±å‘Šè¡Œçˆ²ã€‚ + +- ``kasan.fault=report`` 或 ``=panic`` 控制是å¦åªæ‰“å°KASAN report或 + åŒæ™‚ä½¿å…§æ ¸æ慌（默èªï¼š ``report`` ）。å³ä½¿ ``kasan_multi_shot`` 被 + 啓用，æ慌也會發生。 + +基於軟件和硬件標籤的KASAN模å¼ï¼ˆè¦‹ä¸‹é¢é—œæ–¼å„種模å¼çš„部分）支æŒæ”¹è®Šå †æ£§è·Ÿ +蹤收集行爲： + +- ``kasan.stacktrace=off`` 或 ``=on`` ç¦ç”¨æˆ–啓用分é…å’Œé‡‹æ”¾å †æ£§ç—• + 跡的收集（默èªï¼š ``on`` ）。 + +- ``kasan.stack_ring_size=<number of entries>`` æŒ‡å®šå †æ£§ç’°çš„æ¢ + 目數（默èªï¼š ``32768`` ）。 + +基於硬件標籤的KASAN模å¼æ˜¯çˆ²äº†åœ¨ç”Ÿç”¢ä¸ä½œçˆ²ä¸€ç¨®å®‰å…¨ç·©è§£æŽªæ–½ä½¿ç”¨ã€‚å› æ¤ï¼Œå®ƒ +支æŒé¡å¤–çš„å•“å‹•åƒæ•¸ï¼Œå…許完全ç¦ç”¨KASAN或控制其功能。 + +- ``kasan=off`` 或 ``=on`` 控制KASAN是å¦è¢«å•“用（默èªï¼š ``on`` ）。 + +- ``kasan.mode=sync``, ``=async`` or ``=asymm`` 控制KASANæ˜¯å¦ + 被é…置爲åŒæ¥ã€ç•°æ¥æˆ–éžå°ç¨±çš„執行模å¼ï¼ˆé»˜èªï¼š ``åŒæ¥`` ）。 + åŒæ¥æ¨¡å¼ï¼šç•¶æ¨™ç±¤æª¢æŸ¥ç•°å¸¸ç™¼ç”Ÿæ™‚，會立å³æª¢æ¸¬åˆ°ä¸è‰¯è¨ªå•ã€‚ + ç•°æ¥æ¨¡å¼ï¼šä¸è‰¯è¨ªå•çš„檢測是延é²çš„。當標籤檢查異常發生時，信æ¯è¢«å˜å„²åœ¨ç¡¬ + 件ä¸ï¼ˆå°æ–¼arm64來說是在TFSR_EL1寄å˜å™¨ä¸ï¼‰ã€‚å…§æ ¸é€±æœŸæ€§åœ°æª¢æŸ¥ç¡¬ä»¶ï¼Œä¸¦\ + 且åªåœ¨é€™äº›æª¢æŸ¥ä¸å ±å‘Šæ¨™ç±¤ç•°å¸¸ã€‚ + éžå°ç¨±æ¨¡å¼ï¼šè®€å–時åŒæ¥æª¢æ¸¬ä¸è‰¯è¨ªå•ï¼Œå¯«å…¥æ™‚ç•°æ¥æª¢æ¸¬ã€‚ + +- ``kasan.vmalloc=off`` or ``=on`` ç¦ç”¨æˆ–啓用vmalloc分é…的標記（默èªï¼š ``on`` ）。 + +éŒ¯èª¤å ±å‘Š +~~~~~~~~ + +典型的KASANå ±å‘Šå¦‚ä¸‹æ‰€ç¤º:: + + ================================================================== + BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] + Write of size 1 at addr ffff8801f44ec37b by task insmod/2760 + + CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.10.2-1 04/01/2014 + Call Trace: + dump_stack+0x94/0xd8 + print_address_description+0x73/0x280 + kasan_report+0x144/0x187 + __asan_report_store1_noabort+0x17/0x20 + kmalloc_oob_right+0xa8/0xbc [test_kasan] + kmalloc_tests_init+0x16/0x700 [test_kasan] + do_one_initcall+0xa5/0x3ae + do_init_module+0x1b6/0x547 + load_module+0x75df/0x8070 + __do_sys_init_module+0x1c6/0x200 + __x64_sys_init_module+0x6e/0xb0 + do_syscall_64+0x9f/0x2c0 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + RIP: 0033:0x7f96443109da + RSP: 002b:00007ffcf0b51b08 EFLAGS: 00000202 ORIG_RAX: 00000000000000af + RAX: ffffffffffffffda RBX: 000055dc3ee521a0 RCX: 00007f96443109da + RDX: 00007f96445cff88 RSI: 0000000000057a50 RDI: 00007f9644992000 + RBP: 000055dc3ee510b0 R08: 0000000000000003 R09: 0000000000000000 + R10: 00007f964430cd0a R11: 0000000000000202 R12: 00007f96445cff88 + R13: 000055dc3ee51090 R14: 0000000000000000 R15: 0000000000000000 + + Allocated by task 2760: + save_stack+0x43/0xd0 + kasan_kmalloc+0xa7/0xd0 + kmem_cache_alloc_trace+0xe1/0x1b0 + kmalloc_oob_right+0x56/0xbc [test_kasan] + kmalloc_tests_init+0x16/0x700 [test_kasan] + do_one_initcall+0xa5/0x3ae + do_init_module+0x1b6/0x547 + load_module+0x75df/0x8070 + __do_sys_init_module+0x1c6/0x200 + __x64_sys_init_module+0x6e/0xb0 + do_syscall_64+0x9f/0x2c0 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + + Freed by task 815: + save_stack+0x43/0xd0 + __kasan_slab_free+0x135/0x190 + kasan_slab_free+0xe/0x10 + kfree+0x93/0x1a0 + umh_complete+0x6a/0xa0 + call_usermodehelper_exec_async+0x4c3/0x640 + ret_from_fork+0x35/0x40 + + The buggy address belongs to the object at ffff8801f44ec300 + which belongs to the cache kmalloc-128 of size 128 + The buggy address is located 123 bytes inside of + 128-byte region [ffff8801f44ec300, ffff8801f44ec380) + The buggy address belongs to the page: + page:ffffea0007d13b00 count:1 mapcount:0 mapping:ffff8801f7001640 index:0x0 + flags: 0x200000000000100(slab) + raw: 0200000000000100 ffffea0007d11dc0 0000001a0000001a ffff8801f7001640 + raw: 0000000000000000 0000000080150015 00000001ffffffff 0000000000000000 + page dumped because: kasan: bad access detected + + Memory state around the buggy address: + ffff8801f44ec200: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb + ffff8801f44ec280: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc + >ffff8801f44ec300: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 03 + ^ + ffff8801f44ec380: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb + ffff8801f44ec400: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc + ================================================================== + +å ±å‘Šæ¨™é¡Œç¸½çµäº†ç™¼ç”Ÿçš„錯誤類型以åŠå°Žè‡´è©²éŒ¯èª¤çš„訪å•é¡žåž‹ã€‚緊隨其後的是錯誤訪å•çš„ +å †æ£§è·Ÿè¹¤ã€æ‰€è¨ªå•å…§å˜åˆ†é…ä½ç½®çš„å †æ£§è·Ÿè¹¤ï¼ˆå°æ–¼è¨ªå•äº†slabå°è±¡çš„情æ³ï¼‰ä»¥åŠå°è±¡ +被釋放的ä½ç½®çš„å †æ£§è·Ÿè¹¤ï¼ˆå°æ–¼è¨ªå•å·²é‡‹æ”¾å…§å˜çš„å•é¡Œå ±å‘Šï¼‰ã€‚接下來是å°è¨ªå•çš„ +slabå°è±¡çš„æ述以åŠé—œæ–¼è¨ªå•çš„å…§å˜é çš„ä¿¡æ¯ã€‚ + +æœ€å¾Œï¼Œå ±å‘Šå±•ç¤ºäº†è¨ªå•åœ°å€å‘¨åœçš„å…§å˜ç‹€æ…‹ã€‚在內部，KASANå–®ç¨è·Ÿè¹¤æ¯å€‹å…§å˜é¡†ç²’çš„ +å…§å˜ç‹€æ…‹ï¼Œæ ¹æ“šKASAN模å¼åˆ†çˆ²8或16個å°é½Šå—ç¯€ã€‚å ±å‘Šçš„å…§å˜ç‹€æ…‹éƒ¨åˆ†ä¸çš„æ¯å€‹æ•¸å— +都顯示了åœç¹žè¨ªå•åœ°å€çš„å…¶ä¸ä¸€å€‹å…§å˜é¡†ç²’的狀態。 + +å°æ–¼é€šç”¨KASAN，æ¯å€‹å…§å˜é¡†ç²’的大å°çˆ²8個å—節。æ¯å€‹é¡†ç²’的狀態被編碼在一個影åå—節 +ä¸ã€‚這8個å—節å¯ä»¥æ˜¯å¯è¨ªå•çš„，部分訪å•çš„，已釋放的或æˆçˆ²Redzone的一部分。KASAN +å°æ¯å€‹å½±åå—節使用以下編碼:00表示å°æ‡‰å…§å˜å€åŸŸçš„所有8個å—節都å¯ä»¥è¨ªå•ï¼›æ•¸å—N +(1 <= N <= 7)表示å‰N個å—節å¯è¨ªå•ï¼Œå…¶ä»–(8 - N)個å—節ä¸å¯è¨ªå•ï¼›ä»»ä½•è² 值都表示 +無法訪å•æ•´å€‹8å—節。KASAN使用ä¸åŒçš„è² å€¼ä¾†å€åˆ†ä¸åŒé¡žåž‹çš„ä¸å¯è¨ªå•å…§å˜ï¼Œå¦‚redzones +或已釋放的內å˜ï¼ˆåƒè¦‹ mm/kasan/kasan.h）。 + +在上é¢çš„å ±å‘Šä¸ï¼Œç®é 指å‘å½±åå—節 ``03`` ，表示訪å•çš„地å€æ˜¯éƒ¨åˆ†å¯è¨ªå•çš„。 + +å°æ–¼åŸºæ–¼æ¨™ç±¤çš„KASAN模å¼ï¼Œå ±å‘Šæœ€å¾Œçš„部分顯示了訪å•åœ°å€å‘¨åœçš„å…§å˜æ¨™ç±¤ +(åƒè€ƒ `實施細則`_ ç« ç¯€)。 + +請注æ„，KASAN錯誤標題（如 ``slab-out-of-bounds`` 或 ``use-after-free`` ） +是儘é‡æŽ¥è¿‘çš„:KASANæ ¹æ“šå…¶æ“有的有é™ä¿¡æ¯æ‰“å°å‡ºæœ€å¯èƒ½çš„錯誤類型。錯誤的實際類型 +å¯èƒ½æœƒæœ‰æ‰€ä¸åŒã€‚ + +通用KASANé‚„å ±å‘Šå…©å€‹è¼”åŠ©èª¿ç”¨å †æ£§è·Ÿè¹¤ã€‚é€™äº›å †æ£§è·Ÿè¹¤æŒ‡å‘代碼ä¸èˆ‡å°è±¡äº¤äº’但ä¸ç›´æŽ¥ +出ç¾åœ¨éŒ¯èª¤è¨ªå•å †æ£§è·Ÿè¹¤ä¸çš„ä½ç½®ã€‚ç›®å‰ï¼Œé€™åŒ…括 call_rcu() 和排隊的工作隊列。 + +實施細則 +-------- + +通用KASAN +~~~~~~~~~ + +軟件KASAN模å¼ä½¿ç”¨å½±åå…§å˜ä¾†è¨˜éŒ„æ¯å€‹å…§å˜å—節是å¦å¯ä»¥å®‰å…¨è¨ªå•ï¼Œä¸¦ä½¿ç”¨ç·¨è¯æ™‚工具 +在æ¯æ¬¡å…§å˜è¨ªå•ä¹‹å‰æ’入影åå…§å˜æª¢æŸ¥ã€‚ + +通用KASANå°‡1/8çš„å…§æ ¸å…§å˜å°ˆç”¨æ–¼å…¶å½±åå…§å˜ï¼ˆ16TB以覆蓋x86_64上的128TB），並使用 +具有比例和å移é‡çš„ç›´æŽ¥æ˜ å°„å°‡å…§å˜åœ°å€è½‰æ›çˆ²å…¶ç›¸æ‡‰çš„å½±å地å€ã€‚ + +這是將地å€è½‰æ›çˆ²å…¶ç›¸æ‡‰å½±å地å€çš„函數:: + + static inline void *kasan_mem_to_shadow(const void *addr) + { + return (void *)((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) + + KASAN_SHADOW_OFFSET; + } + +åœ¨é€™è£ ``KASAN_SHADOW_SCALE_SHIFT = 3`` 。 + +ç·¨è¯æ™‚工具用於æ’入內å˜è¨ªå•æª¢æŸ¥ã€‚ç·¨è¯å™¨åœ¨æ¯æ¬¡è¨ªå•å¤§å°çˆ²1ã€2ã€4ã€8或16çš„å…§å˜ä¹‹å‰ +æ’入函數調用( ``__asan_load*(addr)`` , ``__asan_store*(addr)``)ã€‚é€™äº›å‡½æ•¸é€šéŽ +檢查相應的影åå…§å˜ä¾†æª¢æŸ¥å…§å˜è¨ªå•æ˜¯å¦æœ‰æ•ˆã€‚ + +使用inlineæ’æ¨ï¼Œç·¨è¯å™¨ä¸é€²è¡Œå‡½æ•¸èª¿ç”¨ï¼Œè€Œæ˜¯ç›´æŽ¥æ’入代碼來檢查影åå…§å˜ã€‚æ¤é¸é … +é¡¯è‘—åœ°å¢žå¤§äº†å…§æ ¸é«”ç©ï¼Œä½†èˆ‡outlineæ’æ¨å…§æ ¸ç›¸æ¯”，它æ供了x1.1-x2的性能æå‡ã€‚ + +通用KASAN是唯一一種通éŽéš”離延é²é‡æ–°ä½¿ç”¨å·²é‡‹æ”¾å°è±¡çš„æ¨¡å¼ +（åƒè¦‹ mm/kasan/quarantine.c 以çžè§£å¯¦ç¾ï¼‰ã€‚ + +基於軟件標籤的KASANæ¨¡å¼ +~~~~~~~~~~~~~~~~~~~~~~~ + +基於軟件標籤的KASAN使用軟件內å˜æ¨™ç±¤æ–¹æ³•ä¾†æª¢æŸ¥è¨ªå•æœ‰æ•ˆæ€§ã€‚ç›®å‰åƒ…é‡å°arm64架構實ç¾ã€‚ + +基於軟件標籤的KASAN使用arm64 CPUçš„é ‚éƒ¨å—節忽略(TBI)ç‰¹æ€§åœ¨å…§æ ¸æŒ‡é‡çš„é ‚éƒ¨å—ç¯€ä¸ +å˜å„²ä¸€å€‹æŒ‡é‡æ¨™ç±¤ã€‚它使用影åå…§å˜ä¾†å˜å„²èˆ‡æ¯å€‹16å—節內å˜å–®å…ƒç›¸é—œçš„å…§å˜æ¨™ç±¤(å› æ¤ï¼Œ +å®ƒå°‡å…§æ ¸å…§å˜çš„1/16專用於影åå…§å˜)。 + +在æ¯æ¬¡å…§å˜åˆ†é…時，基於軟件標籤的KASAN都會生æˆä¸€å€‹éš¨æ©Ÿæ¨™ç±¤ï¼Œç”¨é€™å€‹æ¨™ç±¤æ¨™è¨˜åˆ†é… +çš„å…§å˜ï¼Œä¸¦å°‡ç›¸åŒçš„標籤嵌入到返回的指é‡ä¸ã€‚ + +基於軟件標籤的KASAN使用編è¯æ™‚工具在æ¯æ¬¡å…§å˜è¨ªå•ä¹‹å‰æ’入檢查。這些檢查確ä¿æ£åœ¨ +訪å•çš„å…§å˜çš„標籤ç‰æ–¼ç”¨æ–¼è¨ªå•è©²å…§å˜çš„指é‡çš„標籤。如果標籤ä¸åŒ¹é…，基於軟件標籤 +çš„KASAN會打å°éŒ¯èª¤å ±å‘Šã€‚ + +基於軟件標籤的KASAN也有兩種æ’æ¨æ¨¡å¼ï¼ˆoutline，發出回調來檢查內å˜è¨ªå•ï¼›inline， +執行內è¯çš„å½±åå…§å˜æª¢æŸ¥ï¼‰ã€‚使用outlineæ’æ¨æ¨¡å¼ï¼Œæœƒå¾žåŸ·è¡Œè¨ªå•æª¢æŸ¥çš„函數打å°éŒ¯èª¤ +å ±å‘Šã€‚ä½¿ç”¨inlineæ’æ¨ï¼Œç·¨è¯å™¨æœƒç™¼å‡º ``brk`` 指令，並使用專用的 ``brk`` 處ç†ç¨‹åº +來打å°éŒ¯èª¤å ±å‘Šã€‚ + +基於軟件標籤的KASAN使用0xFF作爲匹é…所有指é‡æ¨™ç±¤ï¼ˆä¸æª¢æŸ¥é€šéŽå¸¶æœ‰0xFF指é‡æ¨™ç±¤ +的指é‡é€²è¡Œçš„訪å•ï¼‰ã€‚值0xFE當å‰ä¿ç•™ç”¨æ–¼æ¨™è¨˜å·²é‡‹æ”¾çš„å…§å˜å€åŸŸã€‚ + + +基於硬件標籤的KASANæ¨¡å¼ +~~~~~~~~~~~~~~~~~~~~~~~ + +基於硬件標籤的KASAN在概念上類似於軟件模å¼ï¼Œä½†å®ƒæ˜¯ä½¿ç”¨ç¡¬ä»¶å…§å˜æ¨™ç±¤ä½œçˆ²æ”¯æŒè€Œ +ä¸æ˜¯ç·¨è¯å™¨æ’æ¨å’Œå½±åå…§å˜ã€‚ + +基於硬件標籤的KASANç›®å‰åƒ…é‡å°arm64架構實ç¾ï¼Œä¸¦ä¸”基於ARMv8.5指令集架構ä¸å¼•å…¥ +çš„arm64å…§å˜æ¨™è¨˜æ“´å±•(MTE)和最高å—節忽略(TBI)。 + +特殊的arm64指令用於爲æ¯æ¬¡å…§å˜åˆ†é…指定內å˜æ¨™ç±¤ã€‚相åŒçš„標籤被指定給指å‘é€™äº›åˆ†é… +的指é‡ã€‚在æ¯æ¬¡å…§å˜è¨ªå•æ™‚，硬件確ä¿æ£åœ¨è¨ªå•çš„å…§å˜çš„標籤ç‰æ–¼ç”¨æ–¼è¨ªå•è©²å…§å˜çš„æŒ‡é‡ +的標籤。如果標籤ä¸åŒ¹é…，則會生æˆæ•…障並打å°å ±å‘Šã€‚ + +基於硬件標籤的KASAN使用0xFF作爲匹é…所有指é‡æ¨™ç±¤ï¼ˆä¸æª¢æŸ¥é€šéŽå¸¶æœ‰0xFF指é‡æ¨™ç±¤çš„ +指é‡é€²è¡Œçš„訪å•ï¼‰ã€‚值0xFE當å‰ä¿ç•™ç”¨æ–¼æ¨™è¨˜å·²é‡‹æ”¾çš„å…§å˜å€åŸŸã€‚ + +如果硬件ä¸æ”¯æŒMTE（ARMv8.5之å‰ï¼‰ï¼Œå‰‡ä¸æœƒå•“用基於硬件標籤的KASAN。在這種情æ³ä¸‹ï¼Œ +所有KASAN引導åƒæ•¸éƒ½å°‡è¢«å¿½ç•¥ã€‚ + +請注æ„，啓用CONFIG_KASAN_HW_TAGSå§‹çµ‚æœƒå°Žè‡´å•“ç”¨å…§æ ¸ä¸çš„TBI。å³ä½¿æ供了 +``kasan.mode=off`` 或硬件ä¸æ”¯æŒMTE（但支æŒTBI）。 + +基於硬件標籤的KASANåªå ±å‘Šç¬¬ä¸€å€‹ç™¼ç¾çš„錯誤。之後，MTE標籤檢查將被ç¦ç”¨ã€‚ + +å½±åå…§å˜ +-------- + +本節的內容åªé©ç”¨æ–¼è»Ÿä»¶KASAN模å¼ã€‚ + +å…§æ ¸å°‡å…§å˜æ˜ 射到地å€ç©ºé–“的幾個ä¸åŒéƒ¨åˆ†ã€‚å…§æ ¸è™›æ“¬åœ°å€çš„範åœå¾ˆå¤§ï¼šæ²’æœ‰è¶³å¤ çš„çœŸå¯¦ +å…§å˜ä¾†æ”¯æŒå…§æ ¸å¯ä»¥è¨ªå•çš„æ¯å€‹åœ°å€çš„真實影åå€åŸŸã€‚å› æ¤ï¼ŒKASANåªçˆ²åœ°å€ç©ºé–“çš„æŸäº› +éƒ¨åˆ†æ˜ å°„çœŸå¯¦çš„å½±å。 + +默èªè¡Œçˆ² +~~~~~~~~ + +默èªæƒ…æ³ä¸‹ï¼Œé«”ç³»çµæ§‹åƒ…將實際內å˜æ˜ å°„åˆ°ç”¨æ–¼ç·šæ€§æ˜ å°„çš„é™°å½±å€åŸŸï¼ˆä»¥åŠå¯èƒ½çš„其他 +å°å€åŸŸï¼‰ã€‚å°æ–¼æ‰€æœ‰å…¶ä»–å€åŸŸ —— 例如vmallocå’Œvmemmap空間 —— 一個åªè®€é é¢è¢«æ˜ å°„ +到陰影å€åŸŸä¸Šã€‚這個åªè®€çš„å½±åé é¢è²æ˜Žæ‰€æœ‰å…§å˜è¨ªå•éƒ½æ˜¯å…許的。 + +這給模塊帶來了一個å•é¡Œï¼šå®ƒå€‘ä¸å˜åœ¨æ–¼ç·šæ€§æ˜ å°„ä¸ï¼Œè€Œæ˜¯å˜åœ¨æ–¼å°ˆç”¨çš„模塊空間ä¸ã€‚ +通éŽé€£æŽ¥æ¨¡å¡Šåˆ†é…器，KASANè‡¨æ™‚æ˜ å°„çœŸå¯¦çš„å½±åå…§å˜ä»¥è¦†è“‹å®ƒå€‘。例如，這å…許檢測 +å°æ¨¡å¡Šå…¨å±€è®Šé‡çš„無效訪å•ã€‚ + +é€™ä¹Ÿé€ æˆäº†èˆ‡ ``VMAP_STACK`` çš„ä¸å…¼å®¹ï¼šå¦‚æžœå †æ£§ä½æ–¼vmalloc空間ä¸ï¼Œå®ƒå°‡è¢«åˆ†é… +åªè®€é é¢çš„å½±åå…§å˜ï¼Œä¸¦ä¸”å…§æ ¸åœ¨å˜—è©¦çˆ²å †æ£§è®Šé‡è¨ç½®å½±å數據時會出錯。 + +CONFIG_KASAN_VMALLOC +~~~~~~~~~~~~~~~~~~~~ + +使用 ``CONFIG_KASAN_VMALLOC`` ，KASANå¯ä»¥ä»¥æ›´å¤§çš„å…§å˜ä½¿ç”¨çˆ²ä»£åƒ¹è¦†è“‹vmalloc +空間。目å‰ï¼Œé€™åœ¨arm64ã€x86ã€riscvã€s390å’Œpowerpc上å—支æŒã€‚ + +這通éŽé€£æŽ¥åˆ°vmallocå’Œvmap並動態分é…真實的影åå…§å˜ä¾†æ”¯æŒæ˜ 射。 + +vmalloc空間ä¸çš„å¤§å¤šæ•¸æ˜ å°„éƒ½å¾ˆå°ï¼Œéœ€è¦ä¸åˆ°ä¸€æ•´é çš„é™°å½±ç©ºé–“ã€‚å› æ¤ï¼Œçˆ²æ¯å€‹æ˜ å°„ +分é…一個完整的影åé é¢å°‡æ˜¯ä¸€ç¨®æµªè²»ã€‚æ¤å¤–，爲了確ä¿ä¸åŒçš„æ˜ å°„ä½¿ç”¨ä¸åŒçš„å½±å +é é¢ï¼Œæ˜ å°„å¿…é ˆèˆ‡ ``KASAN_GRANULE_SIZE * PAGE_SIZE`` å°é½Šã€‚ + +相å，KASANè·¨å¤šå€‹æ˜ å°„å…±äº«å¾Œå‚™ç©ºé–“ã€‚ç•¶vmalloc空間ä¸çš„æ˜ å°„ä½¿ç”¨å½±åå€åŸŸçš„特定 +é é¢æ™‚，它會分é…一個後備é é¢ã€‚æ¤é é¢ç¨å¾Œå¯ä»¥ç”±å…¶ä»–vmallocæ˜ å°„å…±äº«ã€‚ + +KASAN連接到vmap基礎架構以懶清ç†æœªä½¿ç”¨çš„å½±åå…§å˜ã€‚ + +爲了é¿å…交æ›æ˜ 射的困難，KASANé 測覆蓋vmalloc空間的陰影å€åŸŸéƒ¨åˆ†å°‡ä¸æœƒè¢«æ—©æœŸ +çš„é™°å½±é é¢è¦†è“‹ï¼Œä½†æ˜¯å°‡ä¸æœƒè¢«æ˜ 射。這將需è¦æ›´æ”¹ç‰¹å®šæ–¼arch的代碼。 + +這å…許在x86ä¸Šæ”¯æŒ ``VMAP_STACK`` ，並且å¯ä»¥ç°¡åŒ–å°æ²’有固定模塊å€åŸŸçš„架構的支æŒã€‚ + +å°æ–¼é–‹ç™¼è€… +---------- + +å¿½ç•¥è¨ªå• +~~~~~~~~ + +軟件KASAN模å¼ä½¿ç”¨ç·¨è¯å™¨æ’æ¨ä¾†æ’入有效性檢查。æ¤é¡žæª¢æ¸¬å¯èƒ½èˆ‡å…§æ ¸çš„æŸäº›éƒ¨åˆ† +ä¸å…¼å®¹ï¼Œå› æ¤éœ€è¦ç¦ç”¨ã€‚ + +å…§æ ¸çš„å…¶ä»–éƒ¨åˆ†å¯èƒ½æœƒè¨ªå•å·²åˆ†é…å°è±¡çš„元數據。通常，KASANæœƒæª¢æ¸¬ä¸¦å ±å‘Šæ¤é¡žè¨ªå•ï¼Œ +但在æŸäº›æƒ…æ³ä¸‹ï¼ˆä¾‹å¦‚，在內å˜åˆ†é…器ä¸ï¼‰ï¼Œé€™äº›è¨ªå•æ˜¯æœ‰æ•ˆçš„。 + +å°æ–¼è»Ÿä»¶KASAN模å¼ï¼Œè¦ç¦ç”¨ç‰¹å®šæ–‡ä»¶æˆ–目錄的檢測，請將 ``KASAN_SANITIZE`` æ·»åŠ +åˆ°ç›¸æ‡‰çš„å…§æ ¸Makefileä¸: + +- å°æ–¼å–®å€‹æ–‡ä»¶(例如，main.o):: + + KASAN_SANITIZE_main.o := n + +- å°æ–¼ä¸€å€‹ç›®éŒ„下的所有文件:: + + KASAN_SANITIZE := n + +å°æ–¼è»Ÿä»¶KASAN模å¼ï¼Œè¦åœ¨æ¯å€‹å‡½æ•¸çš„基礎上ç¦ç”¨æª¢æ¸¬ï¼Œè«‹ä½¿ç”¨KASAN特定的 +``__no_sanitize_address`` 函數屬性或通用的 ``noinstr`` 。 + +請注æ„，ç¦ç”¨ç·¨è¯å™¨æ’æ¨ï¼ˆåŸºæ–¼æ¯å€‹æ–‡ä»¶æˆ–æ¯å€‹å‡½æ•¸ï¼‰æœƒä½¿KASAN忽略在軟件KASANæ¨¡å¼ +的代碼ä¸ç›´æŽ¥ç™¼ç”Ÿçš„訪å•ã€‚當訪å•æ˜¯é–“接發生的（通éŽèª¿ç”¨æª¢æ¸¬å‡½æ•¸ï¼‰æˆ–使用沒有編è¯å™¨ +æ’æ¨çš„基於硬件標籤的模å¼æ™‚，它沒有幫助。 + +å°æ–¼è»Ÿä»¶KASAN模å¼ï¼Œè¦åœ¨ç•¶å‰ä»»å‹™çš„ä¸€éƒ¨åˆ†å…§æ ¸ä»£ç¢¼ä¸ç¦ç”¨KASANå ±å‘Šï¼Œè«‹ä½¿ç”¨ +``kasan_disable_current()``/``kasan_enable_current()`` 部分註釋這部分代碼。 +這也會ç¦ç”¨é€šéŽå‡½æ•¸èª¿ç”¨ç™¼ç”Ÿçš„間接訪å•çš„å ±å‘Šã€‚ + +å°æ–¼åŸºæ–¼æ¨™ç±¤çš„KASAN模å¼ï¼Œè¦ç¦ç”¨è¨ªå•æª¢æŸ¥ï¼Œè«‹ä½¿ç”¨ ``kasan_reset_tag()`` 或 +``page_kasan_tag_reset()`` 。請注æ„ï¼Œé€šéŽ ``page_kasan_tag_reset()`` +臨時ç¦ç”¨è¨ªå•æª¢æŸ¥éœ€è¦é€šéŽ ``page_kasan_tag`` / ``page_kasan_tag_set`` ä¿ +å˜å’Œæ¢å¾©æ¯é KASAN標籤。 + +測試 +~~~~ + +有一些KASAN測試å¯ä»¥é©—è‰KASAN是å¦æ£å¸¸å·¥ä½œä¸¦å¯ä»¥æª¢æ¸¬æŸäº›é¡žåž‹çš„å…§å˜æ壞。 +測試由兩部分組æˆ: + +1. 與KUnit測試框架集æˆçš„測試。使用 ``CONFIG_KASAN_KUNIT_TEST`` 啓用。 +這些測試å¯ä»¥é€šéŽå¹¾ç¨®ä¸åŒçš„æ–¹å¼è‡ªå‹•é‹è¡Œå’Œéƒ¨åˆ†é©—è‰ï¼›è«‹åƒé–±ä¸‹é¢çš„說明。 + +2. 與KUnitä¸å…¼å®¹çš„測試。使用 ``CONFIG_KASAN_MODULE_TEST`` 啓用並且åªèƒ½ä½œçˆ²æ¨¡å¡Š +é‹è¡Œã€‚這些測試åªèƒ½é€šéŽåŠ è¼‰å…§æ ¸æ¨¡å¡Šä¸¦æª¢æŸ¥å…§æ ¸æ—¥èªŒä»¥ç²å–KASANå ±å‘Šä¾†æ‰‹å‹•é©—è‰ã€‚ + +如果檢測到錯誤，æ¯å€‹KUnit兼容的KASAN測試都會打å°å¤šå€‹KASANå ±å‘Šä¹‹ä¸€ï¼Œç„¶å¾Œæ¸¬è©¦æ‰“å° +其編號和狀態。 + +當測試通éŽ:: + + ok 28 - kmalloc_double_kzfree + +當由於 ``kmalloc`` 失敗而導致測試失敗時:: + + # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 + Expected ptr is not null, but is + not ok 4 - kmalloc_large_oob_right + +當由於缺少KASANå ±å‘Šè€Œå°Žè‡´æ¸¬è©¦å¤±æ•—æ™‚:: + + # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 + KASAN failure expected in "kfree_sensitive(ptr)", but none occurred + not ok 44 - kmalloc_double_kzfree + + +最後打å°æ‰€æœ‰KASAN測試的累ç©ç‹€æ…‹ã€‚æˆåŠŸ:: + + ok 1 - kasan + +或者，如果其ä¸ä¸€é …測試失敗:: + + not ok 1 - kasan + +有幾種方法å¯ä»¥é‹è¡Œèˆ‡KUnit兼容的KASAN測試。 + +1. å¯åŠ 載模塊 + + 啓用 ``CONFIG_KUNIT`` 後，KASAN-KUnit測試å¯ä»¥æ§‹å»ºçˆ²å¯åŠ 載模塊，並通éŽä½¿ç”¨ + ``insmod`` 或 ``modprobe`` åŠ è¼‰ ``test_kasan.ko`` 來é‹è¡Œã€‚ + +2. 內置 + + 通éŽå…§ç½® ``CONFIG_KUNIT`` ，也å¯ä»¥å…§ç½®KASAN-KUnit測試。在這種情æ³ä¸‹ï¼Œ + 測試將在啓動時作爲後期åˆå§‹åŒ–調用é‹è¡Œã€‚ + +3. 使用kunit_tool + + 通éŽå…§ç½® ``CONFIG_KUNIT`` å’Œ ``CONFIG_KASAN_KUNIT_TEST`` ，還å¯ä»¥ä½¿ç”¨ + ``kunit_tool`` 以更易讀的方å¼æŸ¥çœ‹KUnit測試çµæžœã€‚這ä¸æœƒæ‰“å°é€šéŽæ¸¬è©¦ + çš„KASANå ±å‘Šã€‚æœ‰é—œ ``kunit_tool`` 更多最新信æ¯ï¼Œè«‹åƒé–± + `KUnit文檔 <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ 。 + +.. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html + diff --git a/Documentation/translations/zh_TW/sparse.txt b/Documentation/translations/zh_TW/dev-tools/sparse.rst index 35d3d1d748e6..11d64709d6a4 100644 --- a/Documentation/translations/zh_TW/sparse.txt +++ b/Documentation/translations/zh_TW/dev-tools/sparse.rst @@ -27,7 +27,7 @@ Copyright 2006 Bob Copeland <me@bobcopeland.com> 使用 sparse 工具åšé¡žåž‹æª¢æŸ¥ ~~~~~~~~~~~~~~~~~~~~~~~~~~ -"__bitwise" æ˜¯ä¸€ç¨®é¡žåž‹å±¬æ€§ï¼Œæ‰€ä»¥ä½ æ‡‰è©²é€™æ¨£ä½¿ç”¨å®ƒï¼š +"__bitwise" æ˜¯ä¸€ç¨®é¡žåž‹å±¬æ€§ï¼Œæ‰€ä»¥ä½ æ‡‰è©²é€™æ¨£ä½¿ç”¨å®ƒ:: typedef int __bitwise pm_request_t; @@ -47,7 +47,7 @@ Copyright 2006 Bob Copeland <me@bobcopeland.com> å¦ç™½ä¾†èªªï¼Œä½ 並ä¸éœ€è¦ä½¿ç”¨æžšèˆ‰é¡žåž‹ã€‚上é¢é‚£äº›å¯¦éš›éƒ½å¯ä»¥æ¿ƒç¸®æˆä¸€å€‹ç‰¹æ®Šçš„"int __bitwise"類型。 -所以更簡單的辦法åªè¦é€™æ¨£åšï¼š +所以更簡單的辦法åªè¦é€™æ¨£åš:: typedef int __bitwise pm_request_t; diff --git a/Documentation/translations/zh_TW/dev-tools/testing-overview.rst b/Documentation/translations/zh_TW/dev-tools/testing-overview.rst new file mode 100644 index 000000000000..fb3f691f46c3 --- /dev/null +++ b/Documentation/translations/zh_TW/dev-tools/testing-overview.rst @@ -0,0 +1,162 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/dev-tools/testing-overview.rst +:Translator: 胡皓文 Hu Haowen <src.res.211@gmail.com> + +============ +å…§æ ¸æ¸¬è©¦æŒ‡å— +============ + +有許多ä¸åŒçš„工具å¯ä»¥ç”¨æ–¼æ¸¬è©¦Linuxå…§æ ¸ï¼Œå› æ¤çžè§£ä»€éº¼æ™‚候使用它們å¯èƒ½ +很困難。本文檔粗略概述了它們之間的å€åˆ¥ï¼Œä¸¦é—¡é‡‹äº†å®ƒå€‘是怎樣糅åˆåœ¨ä¸€èµ· +的。 + +編寫和é‹è¡Œæ¸¬è©¦ +============== + +å¤§å¤šæ•¸å…§æ ¸æ¸¬è©¦éƒ½æ˜¯ç”¨kselftest或KUnit框架之一編寫的。它們都讓é‹è¡Œæ¸¬è©¦ +æ›´åŠ ç°¡åŒ–ï¼Œä½µçˆ²ç·¨å¯«æ–°æ¸¬è©¦æ供幫助。 + +å¦‚æžœä½ æƒ³é©—è‰å…§æ ¸çš„è¡Œçˆ²â€”â€”å°¤å…¶æ˜¯å…§æ ¸çš„ç‰¹å®šéƒ¨åˆ†â€”â€”é‚£ä½ å°±è¦ä½¿ç”¨kUnit或 +kselftest。 + +KUnitå’Œkselftestçš„å€åˆ¥ +---------------------- + +.. note:: + 由於本文段ä¸éƒ¨åˆ†è¡“語尚無較好的å°æ‡‰ä¸æ–‡é‡‹ç¾©ï¼Œå¯èƒ½å°Žè‡´èˆ‡åŽŸæ–‡å«ç¾© + å˜åœ¨äº›è¨±å·®ç•°ï¼Œå› æ¤å»ºè°è®€è€…çµåˆåŽŸæ–‡ + （Documentation/dev-tools/testing-overview.rst）輔助閱讀。 + 如å°éƒ¨åˆ†ç¿»è¯æœ‰ç•°è°æˆ–有更好的翻è¯æ„見，æ¡è¿Žè¯ç¹«è¯è€…進行修訂。 + +KUnit（Documentation/dev-tools/kunit/index.rst）是用於“白箱â€æ¸¬ +è©¦çš„ä¸€å€‹å®Œæ•´çš„å…§æ ¸å…§éƒ¨ç³»çµ±ï¼šå› çˆ²æ¸¬è©¦ä»£ç¢¼æ˜¯å…§æ ¸çš„ä¸€éƒ¨åˆ†ï¼Œæ‰€ä»¥å®ƒèƒ½å¤ è¨ª +å•ç”¨æˆ¶ç©ºé–“ä¸èƒ½è¨ªå•åˆ°çš„內部çµæ§‹å’ŒåŠŸèƒ½ã€‚ + +å› æ¤ï¼ŒKUnit測試最好é‡å°å…§æ ¸ä¸è¼ƒå°çš„ã€è‡ªåŒ…å«çš„éƒ¨åˆ†ï¼Œä»¥ä¾¿èƒ½å¤ ç¨ç«‹åœ°æ¸¬ +試。“單元â€æ¸¬è©¦çš„概念亦是如æ¤ã€‚ + +比如，一個KUnit測試å¯èƒ½æ¸¬è©¦ä¸€å€‹å–®ç¨çš„å…§æ ¸åŠŸèƒ½ï¼ˆç”šè‡³é€šéŽä¸€å€‹å‡½æ•¸æ¸¬è©¦ +一個單一的代碼路徑，例如一個錯誤處ç†æ¡ˆä¾‹ï¼‰ï¼Œè€Œä¸æ˜¯æ•´å€‹åœ°æ¸¬è©¦ä¸€å€‹ç‰¹æ€§ã€‚ + +這也使得KUnit測試構建和é‹è¡Œéžå¸¸åœ°å¿«ï¼Œå¾žè€Œèƒ½å¤ 作爲開發æµç¨‹çš„一部分被 +é »ç¹åœ°é‹è¡Œã€‚ + +有關更詳細的介紹，請åƒé–±KUnitæ¸¬è©¦ä»£ç¢¼é¢¨æ ¼æŒ‡å— +Documentation/dev-tools/kunit/style.rst + +kselftest（Documentation/dev-tools/kselftest.rst），相å°ä¾†èªªï¼Œå¤§é‡ç”¨ +於用戶空間，並且通常測試用戶空間的腳本或程åºã€‚ + +這使得編寫複雜的測試，或者需è¦æ“ä½œæ›´å¤šå…¨å±€ç³»çµ±ç‹€æ…‹çš„æ¸¬è©¦æ›´åŠ å®¹æ˜“ï¼ˆè«¸ +如生æˆé€²ç¨‹ä¹‹é¡žï¼‰ã€‚然而，從kselftestç›´æŽ¥èª¿ç”¨å…§æ ¸å‡½æ•¸æ˜¯ä¸è¡Œçš„。這也就 +æ„味ç€åªæœ‰é€šéŽæŸç¨®æ–¹å¼ï¼ˆå¦‚系統調用ã€é©…å‹•è¨å‚™ã€æ–‡ä»¶ç³»çµ±ç‰ï¼‰å°Žå‡ºåˆ°äº†ç”¨ +æˆ¶ç©ºé–“çš„å…§æ ¸åŠŸèƒ½æ‰èƒ½ä½¿ç”¨kselftest來測試。爲æ¤ï¼Œæœ‰äº›æ¸¬è©¦åŒ…å«äº†ä¸€å€‹ä¼´ +ç”Ÿçš„å…§æ ¸æ¨¡å¡Šç”¨æ–¼å°Žå‡ºæ›´å¤šçš„ä¿¡æ¯å’ŒåŠŸèƒ½ã€‚ä¸éŽï¼Œå°æ–¼åŸºæœ¬ä¸Šæˆ–è€…å®Œå…¨åœ¨å…§æ ¸ +ä¸é‹è¡Œçš„測試，KUnitå¯èƒ½æ˜¯æ›´ä½³å·¥å…·ã€‚ + +kselftestä¹Ÿå› æ¤éžå¸¸é©åˆæ–¼å…¨éƒ¨åŠŸèƒ½çš„æ¸¬è©¦ï¼Œå› çˆ²é€™äº›åŠŸèƒ½æœƒå°‡æŽ¥å£æš´éœ²åˆ° +ç”¨æˆ¶ç©ºé–“ï¼Œå¾žè€Œèƒ½å¤ è¢«æ¸¬è©¦ï¼Œè€Œä¸æ˜¯å±•ç¾å¯¦ç¾ç´°ç¯€ã€‚“systemâ€æ¸¬è©¦å’Œ +“end-to-endâ€æ¸¬è©¦äº¦æ˜¯å¦‚æ¤ã€‚ + +比如，一個新的系統調用應該伴隨有新的kselftest測試。 + +代碼覆蓋率工具 +============== + +支æŒå…©ç¨®ä¸åŒä»£ç¢¼ä¹‹é–“的覆蓋率測é‡å·¥å…·ã€‚它們å¯ä»¥ç”¨ä¾†é©—è‰ä¸€é …測試執行的 +ç¢ºåˆ‡å‡½æ•¸æˆ–ä»£ç¢¼è¡Œã€‚é€™æœ‰åŠ©æ–¼æ±ºå®šå…§æ ¸è¢«æ¸¬è©¦äº†å¤šå°‘ï¼Œæˆ–ç”¨ä¾†æŸ¥æ‰¾åˆé©çš„測試 +ä¸æ²’有覆蓋到的極端情æ³ã€‚ + +Documentation/translations/zh_CN/dev-tools/gcov.rst 是GCC的覆蓋率測試 +工具，能用於ç²å–å…§æ ¸çš„å…¨å±€æˆ–æ¯å€‹æ¨¡å¡Šçš„覆蓋率。與KCOVä¸åŒçš„是，這個工具 +ä¸è¨˜éŒ„æ¯å€‹ä»»å‹™çš„覆蓋率。覆蓋率數據å¯ä»¥é€šéŽdebugfs讀å–，並通éŽå¸¸è¦çš„ +gcov工具進行解釋。 + +Documentation/dev-tools/kcov.rst æ˜¯èƒ½å¤ æ§‹å»ºåœ¨å…§æ ¸ä¹‹ä¸ï¼Œç”¨æ–¼åœ¨æ¯å€‹ä»»å‹™ +的層é¢æ•æ‰è¦†è“‹çŽ‡çš„ä¸€å€‹åŠŸèƒ½ã€‚å› æ¤ï¼Œå®ƒå°æ–¼æ¨¡ç³Šæ¸¬è©¦å’Œé—œæ–¼ä»£ç¢¼åŸ·è¡ŒæœŸé–“ä¿¡ +æ¯çš„其它情æ³éžå¸¸æœ‰ç”¨ï¼Œæ¯”如在一個單一系統調用è£ä½¿ç”¨å®ƒå°±å¾ˆæœ‰ç”¨ã€‚ + +動態分æžå·¥å…· +============ + +å…§æ ¸ä¹Ÿæ”¯æŒè¨±å¤šå‹•æ…‹åˆ†æžå·¥å…·ï¼Œç”¨ä»¥æª¢æ¸¬æ£åœ¨é‹è¡Œçš„å…§æ ¸ä¸å‡ºç¾çš„多種類型的 +å•é¡Œã€‚這些工具通常æ¯å€‹åŽ»å°‹æ‰¾ä¸€é¡žä¸åŒçš„缺陷，比如éžæ³•å…§å˜è¨ªå•ï¼Œæ•¸æ“šç«¶ +çˆç‰ä½µç™¼å•é¡Œï¼Œæˆ–整型溢出ç‰å…¶ä»–未定義行爲。 + +如下所示： + +* kmemleak檢測å¯èƒ½çš„å…§å˜æ³„æ¼ã€‚åƒé–± + Documentation/dev-tools/kmemleak.rst +* KASAN檢測éžæ³•å…§å˜è¨ªå•ï¼Œå¦‚數組越界和釋放後é‡ç”¨ï¼ˆUAF）。åƒé–± + Documentation/dev-tools/kasan.rst +* UBSAN檢測C標準ä¸æœªå®šç¾©çš„行爲，如整型溢出。åƒé–± + Documentation/dev-tools/ubsan.rst +* KCSAN檢測數據競çˆã€‚åƒé–± Documentation/dev-tools/kcsan.rst +* KFENCE是一個低開銷的內å˜å•é¡Œæª¢æ¸¬å™¨ï¼Œæ¯”KASAN更快且能被用於批é‡æ§‹å»ºã€‚ + åƒé–± Documentation/dev-tools/kfence.rst +* lockdep是一個鎖定æ£ç¢ºæ€§æª¢æ¸¬å™¨ã€‚åƒé–± + Documentation/locking/lockdep-design.rst +* 除æ¤ä»¥å¤–ï¼Œåœ¨å…§æ ¸ä¸é‚„有一些其它的調試工具，大多數能在 + lib/Kconfig.debug ä¸æ‰¾åˆ°ã€‚ + +這些工具傾å‘æ–¼å°å…§æ ¸é€²è¡Œæ•´é«”測試，並且ä¸åƒkselftestå’ŒKUnit一樣“傳éžâ€ã€‚ +它們å¯ä»¥é€šéŽåœ¨å•“用這些工具時é‹è¡Œå…§æ ¸æ¸¬è©¦ä»¥èˆ‡kselftest或KUnitçµåˆèµ·ä¾†ï¼š +ä¹‹å¾Œä½ å°±èƒ½ç¢ºä¿é€™äº›éŒ¯èª¤åœ¨æ¸¬è©¦éŽç¨‹ä¸éƒ½ä¸æœƒç™¼ç”Ÿäº†ã€‚ + +一些工具與KUnitå’Œkselftest集æˆï¼Œä¸¦ä¸”在檢測到å•é¡Œæ™‚會自動打斷測試。 + +éœæ…‹åˆ†æžå·¥å…· +============ + +除了測試é‹è¡Œä¸çš„å…§æ ¸ï¼Œæˆ‘å€‘é‚„å¯ä»¥ä½¿ç”¨**éœæ…‹åˆ†æž**工具直接分æžå…§æ ¸çš„æºä»£ +碼（**在編è¯æ™‚**ï¼‰ã€‚å…§æ ¸ä¸å¸¸ç”¨çš„工具å…許人們檢查整個æºä»£ç¢¼æ¨¹æˆ–å…¶ä¸çš„特 +定文件。它們使得在開發éŽç¨‹ä¸æ›´å®¹æ˜“發ç¾å’Œä¿®å¾©å•é¡Œã€‚ + + Sparseå¯ä»¥é€šéŽåŸ·è¡Œé¡žåž‹æª¢æŸ¥ã€éŽ–檢查ã€å€¼ç¯„åœæª¢æŸ¥ä¾†å¹«åŠ©æ¸¬è©¦å…§æ ¸ï¼Œæ¤å¤–é‚„ + å¯ä»¥åœ¨æª¢æŸ¥ä»£ç¢¼æ™‚å ±å‘Šå„種錯誤和è¦å‘Šã€‚關於如何使用它的細節，請åƒé–± + Documentation/translations/zh_CN/dev-tools/sparse.rst。 + + Smatch擴展了Sparse，並æ供了å°ç·¨ç¨‹é‚輯錯誤的é¡å¤–檢查，如開關語å¥ä¸ + 缺少斷點，錯誤檢查ä¸æœªä½¿ç”¨çš„返回值，忘記在錯誤路徑的返回ä¸è¨ç½®éŒ¯èª¤ä»£ + 碼ç‰ã€‚Smatch也有é‡å°æ›´åš´é‡å•é¡Œçš„測試，如整數溢出ã€ç©ºæŒ‡é‡è§£é™¤å¼•ç”¨å’Œå…§ + å˜æ³„æ¼ã€‚è¦‹é …ç›®é é¢http://smatch.sourceforge.net/。 + + Coccinelle是我們å¯ä»¥ä½¿ç”¨çš„å¦ä¸€å€‹éœæ…‹åˆ†æžå™¨ã€‚Coccinelle經常被用來 + 幫助æºä»£ç¢¼çš„é‡æ§‹å’Œä¸¦è¡Œæ¼”化，但它也å¯ä»¥å¹«åŠ©é¿å…常見代碼模å¼ä¸å‡ºç¾çš„æŸ + 些錯誤。å¯ç”¨çš„測試類型包括API測試ã€å…§æ ¸è¿ä»£å™¨çš„æ£ç¢ºä½¿ç”¨æ¸¬è©¦ã€è‡ªç”±æ“ + 作的åˆç†æ€§æª¢æŸ¥ã€éŽ–定行爲的分æžï¼Œä»¥åŠå·²çŸ¥çš„有助於ä¿æŒå…§æ ¸ä½¿ç”¨ä¸€è‡´æ€§çš„ + 進一æ¥æ¸¬è©¦ã€‚詳情請見Documentation/dev-tools/coccinelle.rst。 + + ä¸éŽè¦æ³¨æ„的是，éœæ…‹åˆ†æžå·¥å…·å˜åœ¨**å‡é™½æ€§**çš„å•é¡Œã€‚åœ¨è©¦åœ–ä¿®å¾©éŒ¯èª¤å’Œè¦ + 告之å‰ï¼Œéœ€è¦ä»”細評估它們。 + +何時使用Sparseå’ŒSmatch +---------------------- + +Sparseåšé¡žåž‹æª¢æŸ¥ï¼Œä¾‹å¦‚é©—è‰è¨»é‡‹çš„變é‡ä¸æœƒå°Žè‡´ç„¡ç¬¦è™Ÿçš„錯誤，檢測 +``__user`` 指é‡ä½¿ç”¨ä¸ç•¶çš„地方，以åŠåˆ†æžç¬¦è™Ÿåˆå§‹åŒ–器的兼容性。 + +Smatch進行æµç¨‹åˆ†æžï¼Œå¦‚æžœå…許建立函數數據庫，它還會進行跨函數分æžã€‚ +Smatch試圖回ç”一些å•é¡Œï¼Œæ¯”如這個緩è¡å€æ˜¯åœ¨å“ªè£åˆ†é…的？它有多大？這 +個索引å¯ä»¥ç”±ç”¨æˆ¶æŽ§åˆ¶å—Žï¼Ÿé€™å€‹è®Šé‡æ¯”那個變é‡å¤§å—Žï¼Ÿ + +一般來說，在Smatchä¸å¯«æª¢æŸ¥æ¯”在Sparseä¸å¯«æª¢æŸ¥è¦å®¹æ˜“。儘管如æ¤ï¼Œ +Sparseå’ŒSmatch的檢查還是有一些é‡ç–Šçš„地方。 + +Smatchå’ŒCoccinelleçš„å¼·é … +------------------------ + +Coccinelleå¯èƒ½æ˜¯æœ€å®¹æ˜“寫檢查的。它在é 處ç†å™¨ä¹‹å‰å·¥ä½œï¼Œæ‰€ä»¥ç”¨Coccinelle +檢查å®ä¸çš„錯誤更容易。Coccinelleé‚„èƒ½çˆ²ä½ å‰µå»ºè£œä¸ï¼Œé€™æ˜¯å…¶ä»–工具無法åšåˆ°çš„。 + +例如，用Coccinelleä½ å¯ä»¥å¾ž ``kmalloc_array(x, size, GFP_KERNEL)`` +到 ``kmalloc_array(x, size, GFP_KERNEL)`` 進行大è¦æ¨¡è½‰æ›ï¼Œé€™çœŸçš„很 +æœ‰ç”¨ã€‚å¦‚æžœä½ åªæ˜¯å‰µå»ºä¸€å€‹Smatchè¦å‘Šï¼Œä¸¦è©¦åœ–把轉æ›çš„工作推給ç¶è·è€…，他們會很 +惱ç«ã€‚ä½ å°‡ä¸å¾—ä¸çˆ²æ¯å€‹è¦å‘Šçˆè«–是å¦çœŸçš„å¯ä»¥æº¢å‡ºã€‚ + +Coccinelleä¸å°è®Šé‡å€¼é€²è¡Œåˆ†æžï¼Œè€Œé€™æ£æ˜¯Smatchçš„å¼·é …ã€‚å¦ä¸€æ–¹é¢ï¼ŒCoccinelle +å…è¨±ä½ ç”¨ç°¡å–®çš„æ–¹æ³•åšç°¡å–®çš„事情。 + diff --git a/Documentation/translations/zh_TW/filesystems/debugfs.rst b/Documentation/translations/zh_TW/filesystems/debugfs.rst index ddf801943c92..78e2e08af95e 100644 --- a/Documentation/translations/zh_TW/filesystems/debugfs.rst +++ b/Documentation/translations/zh_TW/filesystems/debugfs.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :doc:`../../../filesystems/debugfs` +:Original: Documentation/filesystems/debugfs.rst ======= Debugfs @@ -11,20 +11,19 @@ Debugfs è¯è€… :: - ä¸æ–‡ç‰ˆç¶è·è€…ï¼šç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> - ä¸æ–‡ç‰ˆç¿»è¯è€…ï¼šç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> - ä¸æ–‡ç‰ˆæ ¡è¯è€…: ç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> + ä¸æ–‡ç‰ˆç¶è·è€…： ç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> + ä¸æ–‡ç‰ˆç¿»è¯è€…： ç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> + ä¸æ–‡ç‰ˆæ ¡è¯è€…: ç¾…æ¥šæˆ Chucheng Luo <luochucheng@vivo.com> ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…: 胡皓文 Hu Haowen <src.res.211@gmail.com> 版權所有2020 ç¾…æ¥šæˆ <luochucheng@vivo.com> -版權所有2021 胡皓文 Hu Haowen <src.res.211@gmail.com> Debugfsæ˜¯å…§æ ¸é–‹ç™¼äººå“¡åœ¨ç”¨æˆ¶ç©ºé–“ç²å–ä¿¡æ¯çš„簡單方法。與/procä¸åŒï¼Œprocåªæ供進程 -ä¿¡æ¯ã€‚也ä¸åƒsysfs,å…·æœ‰åš´æ ¼çš„ã€Œæ¯å€‹æ–‡ä»¶ä¸€å€‹å€¼ã€Œçš„è¦å‰‡ã€‚debugfsæ ¹æœ¬æ²’æœ‰è¦å‰‡,開發 -人員å¯ä»¥åœ¨é€™è£¡æ”¾ç½®ä»–們想è¦çš„任何信æ¯ã€‚debugfs文件系統也ä¸èƒ½ç”¨ä½œç©©å®šçš„ABI接å£ã€‚ +ä¿¡æ¯ã€‚也ä¸åƒsysfs,å…·æœ‰åš´æ ¼çš„â€œæ¯å€‹æ–‡ä»¶ä¸€å€‹å€¼â€œçš„è¦å‰‡ã€‚debugfsæ ¹æœ¬æ²’æœ‰è¦å‰‡,開發 +人員å¯ä»¥åœ¨é€™è£æ”¾ç½®ä»–們想è¦çš„任何信æ¯ã€‚debugfs文件系統也ä¸èƒ½ç”¨ä½œç©©å®šçš„ABI接å£ã€‚ 從ç†è«–上講，debugfs導出文件的時候沒有任何約æŸã€‚但是[1]實際情æ³ä¸¦ä¸ç¸½æ˜¯é‚£éº¼ 簡單。å³ä½¿æ˜¯debugfs接å£ï¼Œä¹Ÿæœ€å¥½æ ¹æ“šéœ€è¦é€²è¡Œè¨è¨ˆ,並儘é‡ä¿æŒæŽ¥å£ä¸è®Šã€‚ @@ -34,8 +33,8 @@ Debugfs通常使用以下命令安è£:: mount -t debugfs none /sys/kernel/debug （或ç‰æ•ˆçš„/etc/fstab行）。 -debugfsæ ¹ç›®éŒ„é»˜èªåƒ…å¯ç”±root用戶訪å•ã€‚è¦æ›´æ”¹å°æ–‡ä»¶æ¨¹çš„訪å•ï¼Œè«‹ä½¿ç”¨ã€Œ uidã€ï¼Œã€Œ gid〠-和「 modeã€æŽ›è¼‰é¸é …。請注æ„，debugfs API僅按照GPLå”è°å°Žå‡ºåˆ°æ¨¡å¡Šã€‚ +debugfsæ ¹ç›®éŒ„é»˜èªåƒ…å¯ç”±root用戶訪å•ã€‚è¦æ›´æ”¹å°æ–‡ä»¶æ¨¹çš„訪å•ï¼Œè«‹ä½¿ç”¨â€œ uidâ€ï¼Œâ€œ gid†+和“ modeâ€æŽ›è¼‰é¸é …。請注æ„，debugfs API僅按照GPLå”è°å°Žå‡ºåˆ°æ¨¡å¡Šã€‚ 使用debugfs的代碼應包å«<linux/debugfs.h>。然後，首先是創建至少一個目錄來ä¿å˜ 一組debugfs文件:: @@ -54,8 +53,8 @@ debugfsæ ¹ç›®éŒ„é»˜èªåƒ…å¯ç”±root用戶訪å•ã€‚è¦æ›´æ”¹å°æ–‡ä»¶æ¨¹çš„è¨ªå• struct dentry *parent, void *data, const struct file_operations *fops); -在這裡，name是è¦å‰µå»ºçš„文件的å稱，modeæ述了訪å•æ–‡ä»¶æ‡‰å…·æœ‰çš„權é™ï¼ŒparentæŒ‡å‘ -應該ä¿å˜æ–‡ä»¶çš„目錄，dataå°‡å˜å„²åœ¨ç”¢ç”Ÿçš„inodeçµæ§‹é«”çš„i_private欄ä½ä¸ï¼Œè€Œfops是 +在這è£ï¼Œname是è¦å‰µå»ºçš„文件的å稱，modeæ述了訪å•æ–‡ä»¶æ‡‰å…·æœ‰çš„權é™ï¼ŒparentæŒ‡å‘ +應該ä¿å˜æ–‡ä»¶çš„目錄，dataå°‡å˜å„²åœ¨ç”¢ç”Ÿçš„inodeçµæ§‹é«”çš„i_privateå—段ä¸ï¼Œè€Œfops是 一組文件æ“作函數，這些函數ä¸å¯¦ç¾æ–‡ä»¶æ“作的具體行爲。至少，read（）和/或 write（）æ“作應æ供；其他å¯ä»¥æ ¹æ“šéœ€è¦åŒ…括在內。åŒæ¨£çš„，返回值將是指å‘創建文件 çš„dentry指é‡ï¼ŒéŒ¯èª¤æ™‚返回ERR_PTR（-ERROR），系統ä¸æ”¯æŒdebugfs時返回值爲ERR_PTR @@ -81,7 +80,7 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å struct dentry *parent, u64 *value); 這些文件支æŒè®€å–和寫入給定值。如果æŸå€‹æ–‡ä»¶ä¸æ”¯æŒå¯«å…¥ï¼Œåªéœ€æ ¹æ“šéœ€è¦è¨ç½®mode -åƒæ•¸ä½ã€‚這些文件ä¸çš„值以å進ä½è¡¨ç¤ºï¼›å¦‚果需è¦ä½¿ç”¨åå…進ä½ï¼Œå¯ä»¥ä½¿ç”¨ä»¥ä¸‹å‡½æ•¸ +åƒæ•¸ä½ã€‚這些文件ä¸çš„值以å進制表示；如果需è¦ä½¿ç”¨åå…進制，å¯ä»¥ä½¿ç”¨ä»¥ä¸‹å‡½æ•¸ 替代:: void debugfs_create_x8(const char *name, umode_t mode, @@ -93,7 +92,7 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å void debugfs_create_x64(const char *name, umode_t mode, struct dentry *parent, u64 *value); -這些功能åªæœ‰åœ¨é–‹ç™¼äººå“¡çŸ¥é“導出值的大å°çš„時候æ‰æœ‰ç”¨ã€‚æŸäº›æ•¸æ“šé¡žåž‹åœ¨ä¸åŒçš„架構上 +這些功能åªæœ‰åœ¨é–‹ç™¼äººå“¡çŸ¥é“導出值的大å°çš„時候纔有用。æŸäº›æ•¸æ“šé¡žåž‹åœ¨ä¸åŒçš„架構上 有ä¸åŒçš„寬度，這樣會使情æ³è®Šå¾—有些複雜。在這種特殊情æ³ä¸‹å¯ä»¥ä½¿ç”¨ä»¥ä¸‹å‡½æ•¸:: void debugfs_create_size_t(const char *name, umode_t mode, @@ -101,7 +100,7 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å ä¸å‡ºæ‰€æ–™ï¼Œæ¤å‡½æ•¸å°‡å‰µå»ºä¸€å€‹debugfs文件來表示類型爲size_t的變é‡ã€‚ -åŒæ¨£åœ°ï¼Œä¹Ÿæœ‰å°Žå‡ºç„¡ç¬¦è™Ÿé•·æ•´åž‹è®Šé‡çš„函數，分別以å進ä½å’Œåå…進ä½è¡¨ç¤ºå¦‚下:: +åŒæ¨£åœ°ï¼Œä¹Ÿæœ‰å°Žå‡ºç„¡ç¬¦è™Ÿé•·æ•´åž‹è®Šé‡çš„函數，分別以å進制和åå…進制表示如下:: struct dentry *debugfs_create_ulong(const char *name, umode_t mode, struct dentry *parent, @@ -125,7 +124,7 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å 讀å–æ¤æ–‡ä»¶å°‡ç²å¾—atomic_t值，寫入æ¤æ–‡ä»¶å°‡è¨ç½®atomic_t值。 -å¦ä¸€å€‹é¸æ“‡æ˜¯é€šéŽä»¥ä¸‹çµæ§‹é«”和函數導出一個任æ„二進ä½æ•¸æ“šå¡Š:: +å¦ä¸€å€‹é¸æ“‡æ˜¯é€šéŽä»¥ä¸‹çµæ§‹é«”和函數導出一個任æ„二進制數據塊:: struct debugfs_blob_wrapper { void *data; @@ -136,10 +135,10 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å struct dentry *parent, struct debugfs_blob_wrapper *blob); -讀å–æ¤æ–‡ä»¶å°‡è¿”回由指é‡æŒ‡å‘debugfs_blob_wrapperçµæ§‹é«”的數據。一些驅動使用「blobs〠-作爲一種返回幾行（éœæ…‹ï¼‰æ ¼å¼åŒ–文本的簡單方法。這個函數å¯ç”¨æ–¼å°Žå‡ºäºŒé€²ä½ä¿¡æ¯ï¼Œä½† +讀å–æ¤æ–‡ä»¶å°‡è¿”回由指é‡æŒ‡å‘debugfs_blob_wrapperçµæ§‹é«”的數據。一些驅動使用“blobs†+作爲一種返回幾行（éœæ…‹ï¼‰æ ¼å¼åŒ–文本的簡單方法。這個函數å¯ç”¨æ–¼å°Žå‡ºäºŒé€²åˆ¶ä¿¡æ¯ï¼Œä½† 似乎在主線ä¸æ²’有任何代碼這樣åšã€‚請注æ„，使用debugfs_create_blob（）命令創建的 -所有文件是åªè®€çš„。 +所有文件是隻讀的。 如果您è¦è½‰å„²ä¸€å€‹å¯„å˜å™¨å¡Šï¼ˆåœ¨é–‹ç™¼éŽç¨‹ä¸ç¶“常會這麼åšï¼Œä½†æ˜¯é€™æ¨£çš„調試代碼很少上傳 到主線ä¸ã€‚Debugfsæ供兩個函數：一個用於創建僅寄å˜å™¨æ–‡ä»¶ï¼Œå¦ä¸€å€‹æŠŠä¸€å€‹å¯„å˜å™¨å¡Š @@ -163,7 +162,7 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å void debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, int nregs, void __iomem *base, char *prefix); -「baseã€åƒæ•¸å¯èƒ½çˆ²0，但您å¯èƒ½éœ€è¦ä½¿ç”¨__stringify構建reg32數組，實際上有許多寄å˜å™¨ +“baseâ€åƒæ•¸å¯èƒ½çˆ²0，但您å¯èƒ½éœ€è¦ä½¿ç”¨__stringify構建reg32數組，實際上有許多寄å˜å™¨ å稱（å®ï¼‰æ˜¯å¯„å˜å™¨å¡Šåœ¨åŸºå€ä¸Šçš„å—節å移é‡ã€‚ 如果è¦åœ¨debugfsä¸è½‰å„²u32數組，å¯ä»¥ä½¿ç”¨ä»¥ä¸‹å‡½æ•¸å‰µå»ºæ–‡ä»¶:: @@ -172,7 +171,7 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å struct dentry *parent, u32 *array, u32 elements); -「arrayã€åƒæ•¸æ供數據，而「elementsã€åƒæ•¸çˆ²æ•¸çµ„ä¸å…ƒç´ 的數é‡ã€‚注æ„：數組創建後，數組 +“arrayâ€åƒæ•¸æ供數據，而“elementsâ€åƒæ•¸çˆ²æ•¸çµ„ä¸å…ƒç´ 的數é‡ã€‚注æ„：數組創建後，數組 大å°ç„¡æ³•æ›´æ”¹ã€‚ 有一個函數來創建與è¨å‚™ç›¸é—œçš„seq_file:: @@ -183,8 +182,8 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å int (*read_fn)(struct seq_file *s, void *data)); -「devã€åƒæ•¸æ˜¯èˆ‡æ¤debugfs文件相關的è¨å‚™ï¼Œä¸¦ä¸”「read_fnã€æ˜¯ä¸€å€‹å‡½æ•¸æŒ‡é‡ï¼Œé€™å€‹å‡½æ•¸åœ¨ -列å°seq_file內容的時候被回調。 +“devâ€åƒæ•¸æ˜¯èˆ‡æ¤debugfs文件相關的è¨å‚™ï¼Œä¸¦ä¸”“read_fnâ€æ˜¯ä¸€å€‹å‡½æ•¸æŒ‡é‡ï¼Œé€™å€‹å‡½æ•¸åœ¨ +打å°seq_file內容的時候被回調。 還有一些其他的é¢å‘目錄的函數:: @@ -199,7 +198,7 @@ file_size是åˆå§‹æ–‡ä»¶å¤§å°ã€‚其他åƒæ•¸è·Ÿå‡½æ•¸debugfs_create_file的相å 調用debugfs_rename()將爲ç¾æœ‰çš„debugfs文件é‡å‘½å，å¯èƒ½åŒæ™‚切æ›ç›®éŒ„。 new_name 函數調用之å‰ä¸èƒ½å˜åœ¨ï¼›è¿”回值爲old_dentry，其ä¸åŒ…å«æ›´æ–°çš„ä¿¡æ¯ã€‚å¯ä»¥ä½¿ç”¨ -debugfs_create_symlink（）創建符號連çµã€‚ +debugfs_create_symlink（）創建符號éˆæŽ¥ã€‚ 所有debugfsç”¨æˆ¶å¿…é ˆè€ƒæ…®çš„ä¸€ä»¶äº‹æ˜¯ï¼š @@ -219,6 +218,6 @@ dentry值å¯ä»¥çˆ²NULL或錯誤值，在這種情æ³ä¸‹ï¼Œä¸æœƒæœ‰ä»»ä½•æ–‡ä»¶è 如果將å°æ‡‰é ‚層目錄的dentry傳éžçµ¦ä»¥ä¸Šå‡½æ•¸ï¼Œå‰‡è©²ç›®éŒ„下的整個層次çµæ§‹å°‡æœƒè¢«åˆªé™¤ã€‚ -注釋： +註釋： [1] http://lwn.net/Articles/309298/ diff --git a/Documentation/translations/zh_TW/filesystems/index.rst b/Documentation/translations/zh_TW/filesystems/index.rst index 789e742fa3c5..d7f9d61f654c 100644 --- a/Documentation/translations/zh_TW/filesystems/index.rst +++ b/Documentation/translations/zh_TW/filesystems/index.rst @@ -12,7 +12,7 @@ Linux Kernelä¸çš„文件系統 ======================== -這份æ£åœ¨é–‹ç™¼çš„手冊或許在未來æŸå€‹è¼ç…Œçš„æ—¥å裡以易懂的形å¼å°‡Linux虛擬\ +這份æ£åœ¨é–‹ç™¼çš„手冊或許在未來æŸå€‹è¼ç…Œçš„æ—¥åè£ä»¥æ˜“懂的形å¼å°‡Linux虛擬\ 文件系統（VFS）層以åŠåŸºæ–¼å…¶ä¸Šçš„å„種文件系統如何工作呈ç¾çµ¦å¤§å®¶ã€‚當å‰\ å¯ä»¥çœ‹åˆ°ä¸‹é¢çš„內容。 diff --git a/Documentation/translations/zh_TW/filesystems/sysfs.txt b/Documentation/translations/zh_TW/filesystems/sysfs.txt index a84eba2af9d3..ebe90651fc3b 100644 --- a/Documentation/translations/zh_TW/filesystems/sysfs.txt +++ b/Documentation/translations/zh_TW/filesystems/sysfs.txt @@ -61,7 +61,7 @@ Documentation/core-api/kobject.rst 文檔以ç²å¾—更多關於 kobject 接å£çš„ 任何 kobject 在系統ä¸è¨»å†Šï¼Œå°±æœƒæœ‰ä¸€å€‹ç›®éŒ„在 sysfs ä¸è¢«å‰µå»ºã€‚這個 目錄是作爲該 kobject 的父å°è±¡æ‰€åœ¨ç›®éŒ„çš„åç›®éŒ„å‰µå»ºçš„ï¼Œä»¥æº–ç¢ºåœ°å‚³éž -å…§æ ¸çš„å°è±¡å±¤æ¬¡åˆ°ç”¨æˆ¶ç©ºé–“。sysfs ä¸çš„é ‚å±¤ç›®éŒ„ä»£è¡¨è‘—å…§æ ¸å°è±¡å±¤æ¬¡çš„ +å…§æ ¸çš„å°è±¡å±¤æ¬¡åˆ°ç”¨æˆ¶ç©ºé–“。sysfs ä¸çš„é ‚å±¤ç›®éŒ„ä»£è¡¨ç€å…§æ ¸å°è±¡å±¤æ¬¡çš„ å…±åŒç¥–先；例如：æŸäº›å°è±¡å±¬æ–¼æŸå€‹å系統。 Sysfs 在與其目錄關è¯çš„ kernfs_node å°è±¡ä¸å…§éƒ¨ä¿å˜ä¸€å€‹æŒ‡å‘å¯¦ç¾ @@ -198,7 +198,7 @@ Sysfs 將會爲æ¯æ¬¡è®€å¯«æ“ä½œèª¿ç”¨ä¸€æ¬¡é€™å€‹æ–¹æ³•ã€‚é€™ä½¿å¾—é€™äº›æ–¹æ³ ä¸æœƒä¸å¤ªé«˜ã€‚ 這使得用戶空間å¯ä»¥å±€éƒ¨åœ°è®€å’Œä»»æ„çš„å‘å‰æœç´¢æ•´å€‹æ–‡ä»¶ã€‚如果用戶空間 - å‘後æœç´¢åˆ°é›¶æˆ–使用『0ã€å移執行一個pread(2)æ“作，show()方法將 + å‘後æœç´¢åˆ°é›¶æˆ–使用‘0’å移執行一個pread(2)æ“作，show()方法將 å†æ¬¡è¢«èª¿ç”¨ï¼Œä»¥é‡æ–°å¡«å……ç·©å˜ã€‚ - 在寫方é¢ï¼ˆwrite(2)），sysfs 希望在第一次寫æ“作時得到整個緩è¡å€ã€‚ @@ -253,7 +253,7 @@ static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); （注æ„：真æ£çš„實ç¾ä¸å…許用戶空間è¨ç½®è¨å‚™å。） -é ‚å±¤ç›®éŒ„å¸ƒå±€ +é ‚å±¤ç›®éŒ„ä½ˆå±€ ~~~~~~~~~~~~ sysfs ç›®éŒ„çš„å®‰æŽ’é¡¯ç¤ºäº†å…§æ ¸æ•¸æ“šçµæ§‹ä¹‹é–“的關係。 @@ -272,23 +272,23 @@ fs/ devices/ 包å«äº†ä¸€å€‹è¨å‚™æ¨¹çš„æ–‡ä»¶ç³»çµ±è¡¨ç¤ºã€‚ä»–ç›´æŽ¥æ˜ å°„äº†å…§éƒ¨çš„å…§æ ¸ è¨å‚™æ¨¹ï¼Œåæ˜ äº†è¨å‚™çš„層次çµæ§‹ã€‚ -bus/ 包å«äº†å…§æ ¸ä¸å„種總線類型的平é¢ç›®éŒ„布局。æ¯å€‹ç¸½ç·šç›®éŒ„包å«å…©å€‹ +bus/ 包å«äº†å…§æ ¸ä¸å„種總線類型的平é¢ç›®éŒ„佈局。æ¯å€‹ç¸½ç·šç›®éŒ„包å«å…©å€‹ å目錄: devices/ drivers/ -devices/ 包å«äº†ç³»çµ±ä¸å‡ºç¾çš„æ¯å€‹è¨å‚™çš„符號連çµï¼Œä»–å€‘æŒ‡å‘ root/ 下的 +devices/ 包å«äº†ç³»çµ±ä¸å‡ºç¾çš„æ¯å€‹è¨å‚™çš„符號éˆæŽ¥ï¼Œä»–å€‘æŒ‡å‘ root/ 下的 è¨å‚™ç›®éŒ„。 -drivers/ 包å«äº†æ¯å€‹å·²çˆ²ç‰¹å®šç¸½ç·šä¸Šçš„è¨å‚™è€ŒæŽ›è¼‰çš„驅動程åºçš„目錄(這裡 +drivers/ 包å«äº†æ¯å€‹å·²çˆ²ç‰¹å®šç¸½ç·šä¸Šçš„è¨å‚™è€ŒæŽ›è¼‰çš„驅動程åºçš„目錄(é€™è£ å‡å®šé©…動沒有跨越多個總線類型)。 fs/ 包å«äº†ä¸€å€‹çˆ²æ–‡ä»¶ç³»çµ±è¨ç«‹çš„目錄。ç¾åœ¨æ¯å€‹æƒ³è¦å°Žå‡ºå±¬æ€§çš„æ–‡ä»¶ç³»çµ±å¿…é ˆ 在 fs/ 下創建自己的層次çµæ§‹(åƒè¦‹Documentation/filesystems/fuse.rst)。 dev/ 包å«å…©å€‹å目錄： char/ å’Œ block/。在這兩個å目錄ä¸ï¼Œæœ‰ä»¥ -<major>:<minor> æ ¼å¼å‘½å的符號連çµã€‚這些符號連çµæŒ‡å‘ sysfs 目錄 +<major>:<minor> æ ¼å¼å‘½å的符號éˆæŽ¥ã€‚這些符號éˆæŽ¥æŒ‡å‘ sysfs 目錄 ä¸ç›¸æ‡‰çš„è¨å‚™ã€‚/sys/dev æ供一個通éŽä¸€å€‹ stat(2) æ“作çµæžœï¼ŒæŸ¥æ‰¾ è¨å‚™ sysfs 接å£å¿«æ·çš„方法。 diff --git a/Documentation/translations/zh_TW/filesystems/tmpfs.rst b/Documentation/translations/zh_TW/filesystems/tmpfs.rst index 2c8439b2b77e..aed61cc3064d 100644 --- a/Documentation/translations/zh_TW/filesystems/tmpfs.rst +++ b/Documentation/translations/zh_TW/filesystems/tmpfs.rst @@ -4,8 +4,7 @@ :Original: Documentation/filesystems/tmpfs.rst -Translated by Wang Qing <wangqing@vivo.com> -and Hu Haowen <src.res.211@gmail.com> +translated by Wang Qing<wangqing@vivo.com> ===== Tmpfs @@ -13,18 +12,18 @@ Tmpfs Tmpfs是一個將所有文件都ä¿å˜åœ¨è™›æ“¬å…§å˜ä¸çš„文件系統。 -tmpfsä¸çš„所有內容都是臨時的，也就是說沒有任何文件會在硬碟上創建。 +tmpfsä¸çš„所有內容都是臨時的，也就是說沒有任何文件會在硬盤上創建。 如果å¸è¼‰tmpfs實例，所有ä¿å˜åœ¨å…¶ä¸çš„文件都會丟失。 -tmpfs將所有文件ä¿å˜åœ¨å…§æ ¸ç·©å˜ä¸ï¼Œéš¨è‘—文件內容增長或縮å°å¯ä»¥å°‡ä¸éœ€è¦çš„ -é é¢swap出去。它具有最大é™åˆ¶ï¼Œå¯ä»¥é€šéŽã€Œmount -o remount ...ã€èª¿æ•´ã€‚ +tmpfs將所有文件ä¿å˜åœ¨å…§æ ¸ç·©å˜ä¸ï¼Œéš¨ç€æ–‡ä»¶å…§å®¹å¢žé•·æˆ–縮å°å¯ä»¥å°‡ä¸éœ€è¦çš„ +é é¢swap出去。它具有最大é™åˆ¶ï¼Œå¯ä»¥é€šéŽâ€œmount -o remount ...â€èª¿æ•´ã€‚ å’Œramfs（創建tmpfs的模æ¿ï¼‰ç›¸æ¯”，tmpfs包å«äº¤æ›å’Œé™åˆ¶æª¢æŸ¥ã€‚å’Œtmpfsç›¸ä¼¼çš„å¦ -一個æ±è¥¿æ˜¯RAMç£ç¢Ÿï¼ˆ/dev/ram*），å¯ä»¥åœ¨ç‰©ç†RAMä¸æ¨¡æ“¬å›ºå®šå¤§å°çš„硬碟，並在 +一個æ±è¥¿æ˜¯RAMç£ç›¤ï¼ˆ/dev/ram*），å¯ä»¥åœ¨ç‰©ç†RAMä¸æ¨¡æ“¬å›ºå®šå¤§å°çš„硬盤，並在 æ¤ä¹‹ä¸Šå‰µå»ºä¸€å€‹æ™®é€šçš„文件系統。Ramdisks無法swapï¼Œå› æ¤ç„¡æ³•èª¿æ•´å®ƒå€‘的大å°ã€‚ 由於tmpfs完全ä¿å˜æ–¼é é¢ç·©å˜å’Œswapä¸ï¼Œå› æ¤æ‰€æœ‰tmpfsé é¢å°‡åœ¨/proc/meminfo -ä¸é¡¯ç¤ºçˆ²ã€ŒShmemã€ï¼Œè€Œåœ¨free(1)ä¸é¡¯ç¤ºçˆ²ã€ŒSharedã€ã€‚請注æ„，這些計數還包括 +ä¸é¡¯ç¤ºçˆ²â€œShmemâ€ï¼Œè€Œåœ¨free(1)ä¸é¡¯ç¤ºçˆ²â€œSharedâ€ã€‚請注æ„，這些計數還包括 共享內å˜(shmem，請åƒé–±ipcs(1))。ç²å¾—計數的最å¯é 方法是使用df(1)å’Œdu(1)。 tmpfs具有以下用途： @@ -45,7 +44,7 @@ tmpfs具有以下用途： tmpfsçš„å‰èº«(shm fs)æ‰èƒ½ä½¿ç”¨SYSV共享內å˜) 3) 很多人（包括我）都覺的在/tmpå’Œ/var/tmp上掛載éžå¸¸æ–¹ä¾¿ï¼Œä¸¦å…·æœ‰è¼ƒå¤§çš„ - swap分å€ã€‚ç›®å‰å¾ªç’°æŽ›è¼‰tmpfså¯ä»¥æ£å¸¸å·¥ä½œï¼Œæ‰€ä»¥å¤§å¤šæ•¸ç™¼å¸ƒéƒ½æ‡‰ç•¶å¯ä»¥ + swap分å€ã€‚ç›®å‰å¾ªç’°æŽ›è¼‰tmpfså¯ä»¥æ£å¸¸å·¥ä½œï¼Œæ‰€ä»¥å¤§å¤šæ•¸ç™¼ä½ˆéƒ½æ‡‰ç•¶å¯ä»¥ 使用mkinitrd通éŽ/tmp訪å•/tmp。 4) 也許還有更多我ä¸çŸ¥é“的地方:-) @@ -58,11 +57,11 @@ size tmpfs實例分é…çš„å—節數é™åˆ¶ã€‚默èªå€¼æ˜¯ä¸swap時物ç†RAM 如果tmpfs實例éŽå¤§ï¼Œæ©Ÿå™¨å°‡æ»éŽ–ï¼Œå› çˆ²OOM處ç†å°‡ç„¡æ³•é‡‹æ”¾è©²å…§å˜ã€‚ nr_blocks 與size相åŒï¼Œä½†ä»¥PAGE_SIZE爲單ä½ã€‚ nr_inodes tmpfs實例的最大inode個數。默èªå€¼æ˜¯ç‰©ç†å…§å˜é 數的一åŠï¼Œæˆ–者 - (有高端內å˜çš„機器)低端內å˜RAMçš„é 數，二者以較低者為準。 + (有高端內å˜çš„機器)低端內å˜RAMçš„é 數，二者以較低者爲準。 ========= =========================================================== 這些åƒæ•¸æŽ¥å—後綴k，m或g表示åƒï¼Œå…†å’Œåƒå…†å—節，å¯ä»¥åœ¨remount時更改。 -sizeåƒæ•¸ä¹ŸæŽ¥å—後綴％用來é™åˆ¶tmpfs實例å 用物ç†RAM的百分比： +sizeåƒæ•¸ä¹ŸæŽ¥å—後綴％用來é™åˆ¶tmpfs實例佔用物ç†RAM的百分比： 未指定size或nr_blocks時，默èªå€¼çˆ²size=50ï¼… 如果nr_blocks=0（或size=0），block個數將ä¸å—é™åˆ¶ï¼›å¦‚æžœnr_inodes=0， @@ -71,26 +70,26 @@ inode個數將ä¸å—é™åˆ¶ã€‚這樣掛載通常是ä¸æ˜Žæ™ºçš„ï¼Œå› çˆ²å®ƒå…許 å ´æ™¯ä¸‹çš„è¨ªå•ã€‚ tmpfs具有爲所有文件è¨ç½®NUMAå…§å˜åˆ†é…ç–略掛載é¸é …(如果啓用了CONFIG_NUMA), -å¯ä»¥é€šéŽã€Œmount -o remount ...ã€èª¿æ•´ +å¯ä»¥é€šéŽâ€œmount -o remount ...â€èª¿æ•´ ======================== ========================= mpol=default 採用進程分é…ç–ç•¥ (è«‹åƒé–± set_mempolicy(2)) mpol=prefer:Node 傾å‘å¾žçµ¦å®šçš„ç¯€é»žåˆ†é… -mpol=bind:NodeList åªå…許從指定的éŠè¡¨åˆ†é… +mpol=bind:NodeList åªå…許從指定的éˆè¡¨åˆ†é… mpol=interleave 傾å‘æ–¼ä¾æ¬¡å¾žæ¯å€‹ç¯€é»žåˆ†é… mpol=interleave:NodeList ä¾æ¬¡å¾žæ¯å€‹ç¯€é»žåˆ†é… mpol=local 優先本地節點分é…å…§å˜ ======================== ========================= -NodeListæ ¼å¼æ˜¯ä»¥é€—號分隔的å進ä½æ•¸å—表示大å°å’Œç¯„åœï¼Œæœ€å¤§å’Œæœ€å°ç¯„åœæ˜¯ç”¨- -分隔符的å進ä½æ•¸ä¾†è¡¨ç¤ºã€‚例如，mpol=bind0-3,5,7,9-15 +NodeListæ ¼å¼æ˜¯ä»¥é€—號分隔的å進制數å—表示大å°å’Œç¯„åœï¼Œæœ€å¤§å’Œæœ€å°ç¯„åœæ˜¯ç”¨- +分隔符的å進制數來表示。例如，mpol=bind0-3,5,7,9-15 帶有有效NodeListçš„å…§å˜ç–ç•¥å°‡æŒ‰æŒ‡å®šæ ¼å¼ä¿å˜ï¼Œåœ¨å‰µå»ºæ–‡ä»¶æ™‚使用。當任務在該 文件系統上創建文件時，會使用到掛載時的內å˜ç–ç•¥NodeListé¸é …，如果è¨ç½®çš„話， 由調用任務的cpuset[è«‹åƒè¦‹Documentation/admin-guide/cgroup-v1/cpusets.rst] 以åŠä¸‹é¢åˆ—出的å¯é¸æ¨™èªŒç´„æŸã€‚如果NodeLists爲è¨ç½®çˆ²ç©ºé›†ï¼Œå‰‡æ–‡ä»¶çš„å…§å˜ç–略將 -æ¢å¾©çˆ²ã€Œé»˜èªã€ç–略。 +æ¢å¾©çˆ²â€œé»˜èªâ€ç–略。 NUMAå…§å˜åˆ†é…ç–略有å¯é¸æ¨™èªŒï¼Œå¯ä»¥ç”¨æ–¼æ¨¡å¼çµåˆã€‚在掛載tmpfs時指定這些å¯é¸ 標誌å¯ä»¥åœ¨NodeList之å‰ç”Ÿæ•ˆã€‚ @@ -107,12 +106,12 @@ Documentation/admin-guide/mm/numa_memory_policy.rst列出所有å¯ç”¨çš„å…§å˜ è«‹æ³¨æ„ï¼Œå¦‚æžœå…§æ ¸ä¸æ”¯æŒNUMA，那麼使用mpolé¸é …掛載tmpfs將會失敗；nodelistæŒ‡å®šä¸ åœ¨ç·šçš„ç¯€é»žä¹Ÿæœƒå¤±æ•—ã€‚å¦‚æžœæ‚¨çš„ç³»çµ±ä¾è³´æ–¼æ¤ï¼Œä½†å…§æ ¸æœƒé‹è¡Œä¸å¸¶NUMA功能(也許是安全 revoceryå…§æ ¸)，或者具有較少的節點在線，建è°å¾žè‡ªå‹•æ¨¡å¼ä¸çœç•¥mpolé¸é …掛載é¸é …。 -å¯ä»¥åœ¨ä»¥å¾Œé€šéŽã€Œmount -o remount,mpol=Policy:NodeList MountPointã€æ·»åŠ 到掛載點。 +å¯ä»¥åœ¨ä»¥å¾Œé€šéŽâ€œmount -o remount,mpol=Policy:NodeList MountPointâ€æ·»åŠ 到掛載點。 è¦æŒ‡å®šåˆå§‹æ ¹ç›®éŒ„，å¯ä»¥ä½¿ç”¨å¦‚下掛載é¸é …： ==== ==================== -æ¨¡å¼ æ¬Šé™ç”¨å…«é€²ä½æ•¸å—表示 +æ¨¡å¼ æ¬Šé™ç”¨å…«é€²åˆ¶æ•¸å—表示 uid 用戶ID gid 組ID ==== ==================== @@ -129,7 +128,7 @@ inode32 使用32ä½inode 在32ä½å…§æ ¸ä¸Šï¼Œé»˜èªæ˜¯inode32，掛載時指定inode64會被拒絕。 在64ä½å…§æ ¸ä¸Šï¼Œé»˜èªé…置是CONFIG_TMPFS_INODE64。inode64é¿å…了單個è¨å‚™ä¸Šå¯èƒ½æœ‰å¤šå€‹ -具有相åŒinode編號的文件；比如32ä½æ‡‰ç”¨ç¨‹å¼ä½¿ç”¨glibc如果長期訪å•tmpfs，一旦é”到33 +具有相åŒinode編號的文件；比如32ä½æ‡‰ç”¨ç¨‹åºä½¿ç”¨glibc如果長期訪å•tmpfs，一旦é”到33 ä½inode編號，就有EOVERFLOW失敗的å±éšªï¼Œç„¡æ³•æ‰“開大於2GiB的文件，並返回EINVAL。 所以'mount -t tmpfs -o size=10G,nr_inodes=10k,mode=700 tmpfs /mytmpfs'將在 diff --git a/Documentation/translations/zh_TW/filesystems/virtiofs.rst b/Documentation/translations/zh_TW/filesystems/virtiofs.rst index 086fce5839dd..6150ad964e78 100644 --- a/Documentation/translations/zh_TW/filesystems/virtiofs.rst +++ b/Documentation/translations/zh_TW/filesystems/virtiofs.rst @@ -10,7 +10,6 @@ ä¸æ–‡ç‰ˆç¶è·è€…： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> ä¸æ–‡ç‰ˆç¿»è¯è€…： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> ä¸æ–‡ç‰ˆæ ¡è¯è€…： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> - ä¸æ–‡ç‰ˆæ ¡è¯è€…： 王文虎 Wang Wenhu <wenhu.wang@vivo.com> ç¹é«”ä¸æ–‡ç‰ˆæ ¡è¯è€…：胡皓文 Hu Haowen <src.res.211@gmail.com> =========================================== @@ -21,7 +20,7 @@ virtiofs: virtio-fs 主機<->客機共享文件系統 介紹 ==== -Linuxçš„virtiofs文件系統實ç¾äº†ä¸€å€‹åŠè™›æ“¬åŒ–VIRTIO類型「virtio-fsã€è¨å‚™çš„驅動，通éŽè©²\ +Linuxçš„virtiofs文件系統實ç¾äº†ä¸€å€‹åŠè™›æ“¬åŒ–VIRTIO類型“virtio-fsâ€è¨å‚™çš„驅動，通éŽè©²\ é¡žåž‹è¨å‚™å¯¦ç¾å®¢æ©Ÿ<->主機文件系統共享。它å…許客機掛載一個已經導出到主機的目錄。 客機通常需è¦è¨ªå•ä¸»æ©Ÿæˆ–者é ç¨‹ç³»çµ±ä¸Šçš„æ–‡ä»¶ã€‚ä½¿ç”¨å ´æ™¯åŒ…æ‹¬ï¼šåœ¨æ–°å®¢æ©Ÿå®‰è£æ™‚讓文件å°å…¶\ @@ -42,12 +41,12 @@ Linuxçš„virtiofs文件系統實ç¾äº†ä¸€å€‹åŠè™›æ“¬åŒ–VIRTIO類型「virtio-fsã guest# mount -t virtiofs myfs /mnt -請查閱 https://virtio-fs.gitlab.io/ 了解é…ç½®QEMUå’Œvirtiofsd守è·ç¨‹åºçš„詳細信æ¯ã€‚ +請查閱 https://virtio-fs.gitlab.io/ çžè§£é…ç½®QEMUå’Œvirtiofsd守è·ç¨‹åºçš„詳細信æ¯ã€‚ 內幕 ==== 由於virtio-fsè¨å‚™å°‡FUSEå”è°ç”¨æ–¼æ–‡ä»¶ç³»çµ±è«‹æ±‚ï¼Œå› æ¤Linuxçš„virtiofs文件系統與FUSEæ–‡\ -件系統客戶端緊密集æˆåœ¨ä¸€èµ·ã€‚客機充當FUSE客戶端而主機充當FUSE伺æœå™¨ï¼Œå…§æ ¸èˆ‡ç”¨æˆ¶ç©º\ +件系統客戶端緊密集æˆåœ¨ä¸€èµ·ã€‚客機充當FUSE客戶端而主機充當FUSEæœå‹™å™¨ï¼Œå…§æ ¸èˆ‡ç”¨æˆ¶ç©º\ 間之間的/dev/fuse接å£ç”±virtio-fsè¨å‚™æŽ¥å£ä»£æ›¿ã€‚ FUSE請求被置於虛擬隊列ä¸ç”±ä¸»æ©Ÿè™•ç†ã€‚主機填充緩è¡å€ä¸çš„響應部分，而客機處ç†è«‹æ±‚的完æˆéƒ¨åˆ†ã€‚ @@ -55,7 +54,7 @@ FUSE請求被置於虛擬隊列ä¸ç”±ä¸»æ©Ÿè™•ç†ã€‚主機填充緩è¡å€ä¸çš„é å°‡/dev/fuseæ˜ å°„åˆ°è™›æ“¬éšŠåˆ—éœ€è¦è§£æ±º/dev/fuse和虛擬隊列之間語義上的差異。æ¯æ¬¡è®€å–\ /dev/fuseè¨å‚™æ™‚，FUSE客戶端都å¯ä»¥é¸æ“‡è¦å‚³è¼¸çš„請求，從而å¯ä»¥ä½¿æŸäº›è«‹æ±‚優先於其他\ è«‹æ±‚ã€‚è™›æ“¬éšŠåˆ—æœ‰å…¶éšŠåˆ—èªžç¾©ï¼Œç„¡æ³•æ›´æ”¹å·²å…¥éšŠè«‹æ±‚çš„é †åºã€‚在虛擬隊列已滿的情æ³ä¸‹å°¤ -其關éµï¼Œå› 爲æ¤æ™‚ä¸å¯èƒ½åŠ 入高優先級的請求。爲了解決æ¤å·®ç•°ï¼Œvirtio-fsè¨å‚™æŽ¡ç”¨ã€Œhiprioã€\ +其關éµï¼Œå› 爲æ¤æ™‚ä¸å¯èƒ½åŠ 入高優先級的請求。爲了解決æ¤å·®ç•°ï¼Œvirtio-fsè¨å‚™æŽ¡ç”¨â€œhiprioâ€\ （高優先級）虛擬隊列，專門用於有別於普通請求的高優先級請求。 diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst index d1cf0b4d8e46..563ac9bfc66b 100644 --- a/Documentation/translations/zh_TW/index.rst +++ b/Documentation/translations/zh_TW/index.rst @@ -55,11 +55,11 @@ TODOList: :maxdepth: 1 process/license-rules + dev-tools/index TODOList: * doc-guide/index -* dev-tools/index * dev-tools/testing-overview * kernel-hacking/index * rust/index @@ -101,9 +101,10 @@ TODOList: 體系çµæ§‹æ–‡æª” ------------ -TODOList: +.. toctree:: + :maxdepth: 1 -* arch/index + arch/index 其他文檔 -------- diff --git a/Documentation/translations/zh_TW/process/1.Intro.rst b/Documentation/translations/zh_TW/process/1.Intro.rst index f236fe95a6c6..6e754ac48964 100644 --- a/Documentation/translations/zh_TW/process/1.Intro.rst +++ b/Documentation/translations/zh_TW/process/1.Intro.rst @@ -22,12 +22,12 @@ -------- æœ¬ç¯€çš„å…¶é¤˜éƒ¨åˆ†æ¶µè“‹äº†å…§æ ¸é–‹ç™¼çš„éŽç¨‹ï¼Œä»¥åŠé–‹ç™¼äººå“¡åŠå…¶åƒ±ä¸»åœ¨é€™æ–¹é¢å¯èƒ½é‡åˆ°çš„ -å„種å•é¡Œã€‚æœ‰å¾ˆå¤šåŽŸå› ä½¿å…§æ ¸ä»£ç¢¼æ‡‰è¢«åˆä½µåˆ°æ£å¼çš„（「主線ã€ï¼‰å…§æ ¸ä¸ï¼ŒåŒ…括å°ç”¨æˆ¶ +å„種å•é¡Œã€‚æœ‰å¾ˆå¤šåŽŸå› ä½¿å…§æ ¸ä»£ç¢¼æ‡‰è¢«åˆä½µåˆ°æ£å¼çš„（“主線â€ï¼‰å…§æ ¸ä¸ï¼ŒåŒ…括å°ç”¨æˆ¶ 的自動å¯ç”¨æ€§ã€å¤šç¨®å½¢å¼çš„社å€æ”¯æŒä»¥åŠå½±éŸ¿å…§æ ¸é–‹ç™¼æ–¹å‘的能力。æ供給Linuxå…§æ ¸ çš„ä»£ç¢¼å¿…é ˆåœ¨èˆ‡GPL兼容的許å¯è‰ä¸‹å¯ç”¨ã€‚ -:ref:`tw_development_process` 介紹了開發éŽç¨‹ã€å…§æ ¸ç™¼å¸ƒå‘¨æœŸå’Œåˆä½µçª—å£çš„機制。 -涵蓋了補ä¸é–‹ç™¼ã€å¯©æŸ¥å’Œåˆä½µå‘¨æœŸä¸çš„å„個階段。還有一些關於工具和郵件列表的討論？ +:ref:`tw_development_process` 介紹了開發éŽç¨‹ã€å…§æ ¸ç™¼ä½ˆé€±æœŸå’Œåˆä¸¦çª—å£çš„機制。 +涵蓋了補ä¸é–‹ç™¼ã€å¯©æŸ¥å’Œåˆä¸¦é€±æœŸä¸çš„å„個階段。還有一些關於工具和郵件列表的討論？ é¼“å‹µå¸Œæœ›é–‹å§‹å…§æ ¸é–‹ç™¼çš„é–‹ç™¼äººå“¡è·Ÿè¹¤ä¸¦ä¿®å¾©ç¼ºé™·ä»¥ä½œçˆ²åˆæ¥ç·´ç¿’。 @@ -38,39 +38,39 @@ 陷阱。也涵蓋了å°è£œä¸çš„一些è¦æ±‚，並且介紹了一些工具，這些工具有助於確ä¿å…§æ ¸ 補ä¸æ˜¯æ£ç¢ºçš„。 -:ref:`tw_development_posting` æ述發布補ä¸ä»¥ä¾›è©•å¯©çš„éŽç¨‹ã€‚爲了讓開發社å€èƒ½ +:ref:`tw_development_posting` æ述發佈補ä¸ä»¥ä¾›è©•å¯©çš„éŽç¨‹ã€‚爲了讓開發社å€èƒ½ èªçœŸå°å¾…，補ä¸å¿…é ˆè¢«æ£ç¢ºæ ¼å¼åŒ–å’Œæè¿°ï¼Œä¸¦ä¸”å¿…é ˆç™¼é€åˆ°æ£ç¢ºçš„地方。éµå¾ªæœ¬ç¯€ä¸çš„ 建è°æœ‰åŠ©æ–¼ç¢ºä¿æ‚¨çš„工作能被較好地接ç´ã€‚ -:ref:`tw_development_followthrough` 介紹了發布補ä¸ä¹‹å¾Œç™¼ç”Ÿçš„事情；工作在這時 +:ref:`tw_development_followthrough` 介紹了發佈補ä¸ä¹‹å¾Œç™¼ç”Ÿçš„事情；工作在這時 é‚„é é 沒有完æˆã€‚與審閱者一起工作是開發éŽç¨‹ä¸çš„一個é‡è¦éƒ¨åˆ†ï¼›æœ¬ç¯€æ供了一些 關於如何在這個é‡è¦éšŽæ®µé¿å…å•é¡Œçš„æ示。當補ä¸è¢«åˆä½µåˆ°ä¸»ç·šä¸æ™‚，開發人員è¦æ³¨æ„ ä¸è¦å‡å®šä»»å‹™å·²ç¶“完æˆã€‚ -:ref:`tw_development_advancedtopics` 介紹了兩個「高級ã€ä¸»é¡Œï¼šä½¿ç”¨Git管ç†è£œä¸ -和查看其他人發布的補ä¸ã€‚ +:ref:`tw_development_advancedtopics` 介紹了兩個“高級â€ä¸»é¡Œï¼šä½¿ç”¨Git管ç†è£œä¸ +和查看其他人發佈的補ä¸ã€‚ :ref:`tw_development_conclusion` 總çµäº†æœ‰é—œå…§æ ¸é–‹ç™¼çš„更多信æ¯ï¼Œé™„å¸¶æœ‰ç›¸é—œè³‡æº -連çµã€‚ +éˆæŽ¥ã€‚ 這個文檔是關於什麼的 -------------------- Linuxå…§æ ¸æœ‰è¶…éŽ800è¬è¡Œä»£ç¢¼ï¼Œæ¯å€‹ç‰ˆæœ¬çš„è²¢ç»è€…超éŽ1000人，是ç¾å˜æœ€å¤§ã€æœ€æ´»èºçš„ -å…è²»è»Ÿé«”é …ç›®ä¹‹ä¸€ã€‚å¾ž1991å¹´é–‹å§‹ï¼Œé€™å€‹å…§æ ¸å·²ç¶“ç™¼å±•æˆçˆ²ä¸€å€‹æœ€å¥½çš„作æ¥ç³»çµ±çµ„件， -é‹è¡Œåœ¨è¢–ç數ä½éŸ³æ¨‚æ’放器ã€æ¡Œä¸Šåž‹é›»è…¦ã€ç¾å˜æœ€å¤§çš„超級計算機以åŠæ‰€æœ‰é¡žåž‹çš„系統上。 +å…è²»è»Ÿä»¶é …ç›®ä¹‹ä¸€ã€‚å¾ž1991å¹´é–‹å§‹ï¼Œé€™å€‹å…§æ ¸å·²ç¶“ç™¼å±•æˆçˆ²ä¸€å€‹æœ€å¥½çš„æ“作系統組件， +é‹è¡Œåœ¨è¢–ç數å—音樂æ’放器ã€è‡ºå¼é›»è…¦ã€ç¾å˜æœ€å¤§çš„超級計算機以åŠæ‰€æœ‰é¡žåž‹çš„系統上。 它是一種é©ç”¨æ–¼å¹¾ä¹Žä»»ä½•æƒ…æ³çš„å¥å£¯ã€é«˜æ•ˆå’Œå¯æ“´å±•çš„解決方案。 -隨著Linux的發展，希望åƒèˆ‡å…¶é–‹ç™¼çš„開發人員（和公å¸ï¼‰çš„數é‡ä¹Ÿåœ¨å¢žåŠ 。硬體供應商 +隨ç€Linux的發展，希望åƒèˆ‡å…¶é–‹ç™¼çš„開發人員（和公å¸ï¼‰çš„數é‡ä¹Ÿåœ¨å¢žåŠ 。硬件供應商 希望確ä¿Linuxèƒ½å¤ å¾ˆå¥½åœ°æ”¯æŒä»–們的產å“，使這些產å“å°Linux用戶具有å¸å¼•åŠ›ã€‚嵌入 å¼ç³»çµ±ä¾›æ‡‰å•†ä½¿ç”¨Linux作爲集æˆç”¢å“的組件，希望Linuxèƒ½å¤ å„˜å¯èƒ½åœ°å‹ä»»æ‰‹é 的任務。 -分銷商和其他基於Linux的軟體供應商切實關心Linuxå…§æ ¸çš„åŠŸèƒ½ã€æ€§èƒ½å’Œå¯é 性。最終 +分銷商和其他基於Linux的軟件供應商切實關心Linuxå…§æ ¸çš„åŠŸèƒ½ã€æ€§èƒ½å’Œå¯é 性。最終 用戶也常常希望修改Linux，使之能更好地滿足他們的需求。 Linux最引人注目的特性之一是這些開發人員å¯ä»¥è¨ªå•å®ƒï¼›ä»»ä½•å…·å‚™å¿…è¦æŠ€èƒ½çš„人都å¯ä»¥ -改進Linux並影響其開發方å‘。專有產å“ä¸èƒ½æ供這種開放性，這是自由軟體的一個特點。 -如果有什麼ä¸åŒçš„è©±ï¼Œé‚£å°±æ˜¯å…§æ ¸æ¯”å¤§å¤šæ•¸å…¶ä»–è‡ªç”±è»Ÿé«”é …ç›®æ›´é–‹æ”¾ã€‚ä¸€å€‹å…¸åž‹çš„ä¸‰å€‹ -æœˆå…§æ ¸é–‹ç™¼å‘¨æœŸå¯ä»¥æ¶‰åŠ1000多個開發人員，他們爲100多個ä¸åŒçš„å…¬å¸ï¼ˆæˆ–è€…æ ¹æœ¬ä¸ +改進Linux並影響其開發方å‘。專有產å“ä¸èƒ½æ供這種開放性，這是自由軟件的一個特點。 +如果有什麼ä¸åŒçš„è©±ï¼Œé‚£å°±æ˜¯å…§æ ¸æ¯”å¤§å¤šæ•¸å…¶ä»–è‡ªç”±è»Ÿä»¶é …ç›®æ›´é–‹æ”¾ã€‚ä¸€å€‹å…¸åž‹çš„ä¸‰å€‹ +æœˆå…§æ ¸é–‹ç™¼é€±æœŸå¯ä»¥æ¶‰åŠ1000多個開發人員，他們爲100多個ä¸åŒçš„å…¬å¸ï¼ˆæˆ–è€…æ ¹æœ¬ä¸ éš¸å±¬å…¬å¸ï¼‰å·¥ä½œã€‚ èˆ‡å…§æ ¸é–‹ç™¼ç¤¾å€åˆä½œä¸¦ä¸æ˜¯ç‰¹åˆ¥å›°é›£ã€‚但儘管如æ¤ï¼Œä»æœ‰è¨±å¤šæ½›åœ¨çš„è²¢ç»è€…åœ¨å˜—è©¦åš @@ -79,7 +79,7 @@ Linux最引人注目的特性之一是這些開發人員å¯ä»¥è¨ªå•å®ƒï¼›ä»»ä½• éŽç¨‹èˆ‡å°ˆæœ‰çš„開發模å¼æœ‰å¾ˆå¤§çš„ä¸åŒä¹Ÿå°±ä¸è¶³çˆ²å¥‡äº†ã€‚ å°æ–¼æ–°é–‹ç™¼äººå“¡ä¾†èªªï¼Œå…§æ ¸çš„開發éŽç¨‹å¯èƒ½æœƒè®“人感到奇怪和æ懼，但這背後有充分的 -ç†ç”±å’Œå …實的經驗。一個ä¸äº†è§£å…§æ ¸ç¤¾å€å·¥ä½œæ–¹å¼çš„開發人員（或者更糟的是，他們 +ç†ç”±å’Œå …實的經驗。一個ä¸çžè§£å…§æ ¸ç¤¾å€å·¥ä½œæ–¹å¼çš„開發人員（或者更糟的是，他們 試圖拋棄或è¦é¿ä¹‹ï¼‰æœƒå¾—到令人沮喪的體驗。開發社å€åœ¨å¹«åŠ©é‚£äº›è©¦åœ–å¸ç¿’的人的åŒæ™‚， 沒有時間幫助那些ä¸é¡˜æ„傾è½æˆ–ä¸é—œå¿ƒé–‹ç™¼éŽç¨‹çš„人。 @@ -102,20 +102,20 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata å’Œ Jochen Voß 。 -------------------- 有些公å¸å’Œé–‹ç™¼äººå“¡å¶çˆ¾æœƒæƒ³ï¼Œçˆ²ä»€éº¼ä»–們è¦è²»å¿ƒå¸ç¿’å¦‚ä½•èˆ‡å…§æ ¸ç¤¾å€åˆä½œï¼Œä¸¦å°‡ä»£ç¢¼ -æ”¾å…¥ä¸»ç·šå…§æ ¸ï¼ˆã€Œä¸»ç·šã€æ˜¯ç”±Linus Torvaldsç¶è·çš„å…§æ ¸ï¼ŒLinux發行商將其用作基礎）。 +æ”¾å…¥ä¸»ç·šå…§æ ¸ï¼ˆâ€œä¸»ç·šâ€æ˜¯ç”±Linus Torvaldsç¶è·çš„å…§æ ¸ï¼ŒLinux發行商將其用作基礎）。 在çŸæœŸå…§ï¼Œè²¢ç»ä»£ç¢¼çœ‹èµ·ä¾†åƒæ˜¯ä¸€ç¨®å¯ä»¥é¿å…的開銷；ç¶è·ç¨ç«‹ä»£ç¢¼ä¸¦ç›´æŽ¥æ”¯æŒç”¨æˆ¶ -似乎更容易。事實上，ä¿æŒä»£ç¢¼ç¨ç«‹ï¼ˆã€Œæ¨¹å¤–ã€ï¼‰æ˜¯åœ¨ç¶“濟上是錯誤的。 +似乎更容易。事實上，ä¿æŒä»£ç¢¼ç¨ç«‹ï¼ˆâ€œæ¨¹å¤–â€ï¼‰æ˜¯åœ¨ç¶“濟上是錯誤的。 爲了說明樹外代碼æˆæœ¬ï¼Œä¸‹é¢çµ¦å‡ºå…§æ ¸é–‹ç™¼éŽç¨‹çš„一些相關方é¢ï¼›æœ¬æ–‡ç¨å¾Œå°‡æ›´è©³ç´°åœ° 討論其ä¸çš„大部分內容。請考慮： - 所有Linux用戶都å¯ä»¥ä½¿ç”¨åˆä½µåˆ°ä¸»ç·šå…§æ ¸ä¸çš„代碼。它將自動出ç¾åœ¨æ‰€æœ‰å•“用它的 - 發行版上。無需驅動程åºç£ç¢Ÿã€é¡å¤–下載，也ä¸éœ€è¦çˆ²å¤šå€‹ç™¼è¡Œç‰ˆçš„多個版本æä¾› + 發行版上。無需驅動程åºç£ç›¤ã€é¡å¤–下載，也ä¸éœ€è¦çˆ²å¤šå€‹ç™¼è¡Œç‰ˆçš„多個版本æä¾› 支æŒï¼›é€™ä¸€åˆ‡å°‡æ–¹ä¾¿æ‰€æœ‰é–‹ç™¼äººå“¡å’Œç”¨æˆ¶ã€‚併入主線解決了大é‡çš„分發和支æŒå•é¡Œã€‚ - ç•¶å…§æ ¸é–‹ç™¼äººå“¡åŠªåŠ›ç¶è·ä¸€å€‹ç©©å®šçš„用戶空間接å£æ™‚ï¼Œå…§æ ¸å…§éƒ¨API處於ä¸æ–·è®ŠåŒ–之ä¸ã€‚ ä¸ç¶æŒç©©å®šçš„內部接å£æ˜¯ä¸€å€‹æ…Žé‡çš„è¨è¨ˆæ±ºç–；它å…許在任何時候進行基本的改進， - 並產出更高質é‡çš„代碼。但該ç–略導致çµæžœæ˜¯ï¼Œè‹¥è¦ä½¿ç”¨æ–°çš„å…§æ ¸ï¼Œä»»ä½•æ¨¹å¤–ä»£ç¢¼éƒ½ + 併產出更高質é‡çš„代碼。但該ç–略導致çµæžœæ˜¯ï¼Œè‹¥è¦ä½¿ç”¨æ–°çš„å…§æ ¸ï¼Œä»»ä½•æ¨¹å¤–ä»£ç¢¼éƒ½ 需è¦æŒçºŒçš„ç¶è·ã€‚ç¶è·æ¨¹å¤–代碼會需è¦å¤§é‡çš„工作æ‰èƒ½ä½¿ä»£ç¢¼ä¿æŒæ£å¸¸é‹è¡Œã€‚ 相å，ä½æ–¼ä¸»ç·šä¸çš„代碼ä¸éœ€è¦é€™æ¨£åšï¼Œå› 爲基本è¦å‰‡è¦æ±‚進行API更改的任何開發 @@ -140,60 +140,60 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata å’Œ Jochen Voß 。 - 代碼的貢ç»æ˜¯ä½¿æ•´å€‹æµç¨‹å·¥ä½œçš„æ ¹æœ¬ã€‚é€šéŽè²¢ç»ä»£ç¢¼ï¼Œæ‚¨å¯ä»¥å‘å…§æ ¸æ·»åŠ æ–°åŠŸèƒ½ï¼Œä¸¦ æä¾›å…¶ä»–å…§æ ¸é–‹ç™¼äººå“¡ä½¿ç”¨çš„åŠŸèƒ½å’Œç¤ºä¾‹ã€‚å¦‚æžœæ‚¨å·²ç¶“çˆ²Linux開發了代碼（或者æ£åœ¨ - 考慮這樣åšï¼‰ï¼Œé‚£éº¼æ‚¨é¡¯ç„¶å°é€™å€‹å¹³å°çš„æŒçºŒæˆåŠŸæ„Ÿèˆˆè¶£ï¼›è²¢ç»ä»£ç¢¼æ˜¯ç¢ºä¿æˆåŠŸçš„ + 考慮這樣åšï¼‰ï¼Œé‚£éº¼æ‚¨é¡¯ç„¶å°é€™å€‹å¹³è‡ºçš„æŒçºŒæˆåŠŸæ„Ÿèˆˆè¶£ï¼›è²¢ç»ä»£ç¢¼æ˜¯ç¢ºä¿æˆåŠŸçš„ 最好方法之一。 -上述所有ç†ç”±éƒ½é©ç”¨æ–¼ä»»ä½•æ¨¹å¤–å…§æ ¸ä»£ç¢¼ï¼ŒåŒ…æ‹¬ä»¥å°ˆæœ‰çš„ã€åƒ…二進ä½å½¢å¼åˆ†ç™¼çš„代碼。 -然而，在考慮任何類型的純二進ä½å…§æ ¸ä»£ç¢¼åˆ†å¸ƒä¹‹å‰ï¼Œé‚„需è¦è€ƒæ…®å…¶ä»–å› ç´ ã€‚åŒ…æ‹¬ï¼š +上述所有ç†ç”±éƒ½é©ç”¨æ–¼ä»»ä½•æ¨¹å¤–å…§æ ¸ä»£ç¢¼ï¼ŒåŒ…æ‹¬ä»¥å°ˆæœ‰çš„ã€åƒ…二進制形å¼åˆ†ç™¼çš„代碼。 +ç„¶è€Œï¼Œåœ¨è€ƒæ…®ä»»ä½•é¡žåž‹çš„ç´”äºŒé€²åˆ¶å…§æ ¸ä»£ç¢¼åˆ†ä½ˆä¹‹å‰ï¼Œé‚„需è¦è€ƒæ…®å…¶ä»–å› ç´ ã€‚åŒ…æ‹¬ï¼š - åœç¹žå°ˆæœ‰å…§æ ¸æ¨¡å¡Šåˆ†ç™¼çš„法律å•é¡Œå…¶å¯¦è¼ƒçˆ²æ¨¡ç³Šï¼›ç›¸ç•¶å¤šçš„å…§æ ¸ç‰ˆæ¬Šæ‰€æœ‰è€…èªçˆ²ï¼Œ - 大多數僅二進ä½çš„æ¨¡å¡Šæ˜¯å…§æ ¸çš„æ´¾ç”Ÿç”¢å“ï¼Œå› æ¤ï¼Œå®ƒå€‘的分發é•å了GNU通用公共 + å¤§å¤šæ•¸åƒ…äºŒé€²åˆ¶çš„æ¨¡å¡Šæ˜¯å…§æ ¸çš„æ´¾ç”Ÿç”¢å“ï¼Œå› æ¤ï¼Œå®ƒå€‘的分發é•å了GNU通用公共 許å¯è‰ï¼ˆä¸‹é¢å°‡è©³ç´°ä»‹ç´¹ï¼‰ã€‚本文作者ä¸æ˜¯å¾‹å¸«ï¼Œæœ¬æ–‡æª”ä¸çš„任何內容都ä¸å¯èƒ½è¢« - 視爲法律建è°ã€‚å°é–‰åŽŸå§‹ç¢¼æ¨¡å¡Šçš„真實法律地ä½åªèƒ½ç”±æ³•é™¢æ±ºå®šã€‚但ä¸ç®¡æ€Žæ¨£ï¼Œå›°æ“¾ + 視爲法律建è°ã€‚å°é–‰æºä»£ç¢¼æ¨¡å¡Šçš„真實法律地ä½åªèƒ½ç”±æ³•é™¢æ±ºå®šã€‚但ä¸ç®¡æ€Žæ¨£ï¼Œå›°æ“¾ 這些模塊的ä¸ç¢ºå®šæ€§ä»ç„¶å˜åœ¨ã€‚ -- 二進ä½æ¨¡å¡Šå¤§å¤§å¢žåŠ äº†èª¿è©¦å…§æ ¸å•é¡Œçš„é›£åº¦ï¼Œä»¥è‡³æ–¼å¤§å¤šæ•¸å…§æ ¸é–‹ç™¼äººå“¡ç”šè‡³éƒ½ä¸æœƒ - å˜—è©¦ã€‚å› æ¤ï¼Œåªåˆ†ç™¼äºŒé€²ä½æ¨¡å¡Šå°‡ä½¿æ‚¨çš„用戶更難從社å€ç²å¾—支æŒã€‚ +- äºŒé€²åˆ¶æ¨¡å¡Šå¤§å¤§å¢žåŠ äº†èª¿è©¦å…§æ ¸å•é¡Œçš„é›£åº¦ï¼Œä»¥è‡³æ–¼å¤§å¤šæ•¸å…§æ ¸é–‹ç™¼äººå“¡ç”šè‡³éƒ½ä¸æœƒ + å˜—è©¦ã€‚å› æ¤ï¼Œåªåˆ†ç™¼äºŒé€²åˆ¶æ¨¡å¡Šå°‡ä½¿æ‚¨çš„用戶更難從社å€ç²å¾—支æŒã€‚ -- å°æ–¼åƒ…二進ä½çš„模塊的發行者來說，支æŒä¹Ÿæ›´åŠ å›°é›£ï¼Œä»–å€‘å¿…é ˆçˆ²ä»–å€‘å¸Œæœ›æ”¯æŒçš„ +- å°æ–¼åƒ…二進制的模塊的發行者來說，支æŒä¹Ÿæ›´åŠ å›°é›£ï¼Œä»–å€‘å¿…é ˆçˆ²ä»–å€‘å¸Œæœ›æ”¯æŒçš„ æ¯å€‹ç™¼è¡Œç‰ˆå’Œæ¯å€‹å…§æ ¸ç‰ˆæœ¬æä¾›ä¸åŒç‰ˆæœ¬çš„模塊。爲了æ供較爲全é¢çš„覆蓋範åœï¼Œ å¯èƒ½éœ€è¦ä¸€å€‹æ¨¡å¡Šçš„å¹¾å個構建，並且æ¯æ¬¡å‡ç´šå…§æ ¸æ™‚ï¼Œæ‚¨çš„ç”¨æˆ¶éƒ½å¿…é ˆå–®ç¨å‡ç´š 這些模塊。 -- 上é¢æ到的關於代碼評審的所有å•é¡Œéƒ½æ›´åŠ å˜åœ¨æ–¼å°é–‰åŽŸå§‹ç¢¼ä¸ã€‚ç”±æ–¼è©²ä»£ç¢¼æ ¹æœ¬ +- 上é¢æ到的關於代碼評審的所有å•é¡Œéƒ½æ›´åŠ å˜åœ¨æ–¼å°é–‰æºä»£ç¢¼ä¸ã€‚ç”±æ–¼è©²ä»£ç¢¼æ ¹æœ¬ ä¸å¯å¾—ï¼Œå› æ¤ç¤¾å€ç„¡æ³•å°å…¶é€²è¡Œå¯©æŸ¥ï¼Œæ¯«ç„¡ç–‘å•ï¼Œå®ƒå°‡å˜åœ¨åš´é‡å•é¡Œã€‚ 尤其是嵌入å¼ç³»çµ±çš„è£½é€ å•†ï¼Œå¯èƒ½æœƒå‚¾å‘於忽視本節ä¸æ‰€èªªçš„å¤§éƒ¨åˆ†å…§å®¹ï¼›å› çˆ²ä»–å€‘ -相信自己æ£åœ¨å•†ç”¨ä¸€ç¨®ä½¿ç”¨å‡çµå…§æ ¸ç‰ˆæœ¬çš„ç¨ç«‹ç”¢å“，在發布後ä¸éœ€è¦å†é€²è¡Œé–‹ç™¼ã€‚ +相信自己æ£åœ¨å•†ç”¨ä¸€ç¨®ä½¿ç”¨å‡çµå…§æ ¸ç‰ˆæœ¬çš„ç¨ç«‹ç”¢å“，在發佈後ä¸éœ€è¦å†é€²è¡Œé–‹ç™¼ã€‚ 這個論點忽略了廣泛的代碼審查的價值以åŠå…許用戶å‘產å“æ·»åŠ åŠŸèƒ½çš„åƒ¹å€¼ã€‚ä½†é€™äº› -產å“的商æ¥å£½å‘½æœ‰é™ï¼Œä¹‹å¾Œå¿…é ˆç™¼å¸ƒæ–°ç‰ˆæœ¬çš„ç”¢å“。在這一點上，代碼在主線上並得到 -良好ç¶è·çš„ä¾›æ‡‰å•†å°‡èƒ½å¤ æ›´å¥½åœ°å ä½ï¼Œä»¥ä½¿æ–°ç”¢å“快速上市。 +產å“的商æ¥å£½å‘½æœ‰é™ï¼Œä¹‹å¾Œå¿…é ˆç™¼ä½ˆæ–°ç‰ˆæœ¬çš„ç”¢å“。在這一點上，代碼在主線上並得到 +良好ç¶è·çš„ä¾›æ‡‰å•†å°‡èƒ½å¤ æ›´å¥½åœ°ä½”ä½ï¼Œä»¥ä½¿æ–°ç”¢å“快速上市。 è¨±å¯ ---- ä»£ç¢¼æ˜¯æ ¹æ“šä¸€äº›è¨±å¯è‰æ供給Linuxå…§æ ¸çš„ï¼Œä½†æ˜¯æ‰€æœ‰ä»£ç¢¼éƒ½å¿…é ˆèˆ‡GNUé€šç”¨å…¬å…±è¨±å¯ è‰ï¼ˆGPLV2）的版本2å…¼å®¹ï¼Œè©²ç‰ˆæœ¬æ˜¯è¦†è“‹æ•´å€‹å…§æ ¸åˆ†ç™¼çš„è¨±å¯è‰ã€‚在實è¸ä¸ï¼Œé€™æ„味 -著所有代碼貢ç»éƒ½ç”±GPLv2（å¯é¸åœ°ï¼Œèªžè¨€å…許在更高版本的GPL下分發）或3åå¥BSD +ç€æ‰€æœ‰ä»£ç¢¼è²¢ç»éƒ½ç”±GPLv2（å¯é¸åœ°ï¼Œèªžè¨€å…許在更高版本的GPL下分發）或3åå¥BSD 許å¯ï¼ˆNew BSD License，è¯è€…注）覆蓋。任何ä¸åŒ…å«åœ¨å…¼å®¹è¨±å¯è‰ä¸çš„è²¢ç»éƒ½ä¸æœƒ 被接å—åˆ°å…§æ ¸ä¸ã€‚ è²¢ç»çµ¦å…§æ ¸çš„代碼ä¸éœ€è¦ï¼ˆæˆ–請求）版權分é…。åˆä½µåˆ°ä¸»ç·šå…§æ ¸ä¸çš„所有代碼都ä¿ç•™ å…¶åŽŸå§‹æ‰€æœ‰æ¬Šï¼›å› æ¤ï¼Œå…§æ ¸ç¾åœ¨æ“有數åƒå€‹æ‰€æœ‰è€…。 -這種所有權çµæ§‹ä¹Ÿæš—ç¤ºè‘—ï¼Œä»»ä½•æ”¹è®Šå…§æ ¸è¨±å¯çš„å˜—è©¦éƒ½è¨»å®šæœƒå¤±æ•—ã€‚å¾ˆå°‘æœ‰å¯¦éš›æƒ…æ³ +這種所有權çµæ§‹ä¹Ÿæš—示ç€ï¼Œä»»ä½•æ”¹è®Šå…§æ ¸è¨±å¯çš„å˜—è©¦éƒ½è¨»å®šæœƒå¤±æ•—ã€‚å¾ˆå°‘æœ‰å¯¦éš›æƒ…æ³ å¯ä»¥ç²å¾—所有版權所有者的åŒæ„ï¼ˆæˆ–è€…å¾žå…§æ ¸ä¸åˆªé™¤ä»–å€‘çš„ä»£ç¢¼ï¼‰ã€‚å› æ¤ï¼Œå°¤å…¶æ˜¯åœ¨ å¯é 見的將來，許å¯è‰ä¸å¤§å¯èƒ½é·ç§»åˆ°GPL的版本3。 -所有貢ç»çµ¦å…§æ ¸çš„ä»£ç¢¼éƒ½å¿…é ˆæ˜¯åˆæ³•çš„å…è²»è»Ÿé«”ã€‚å› æ¤ï¼Œä¸æŽ¥å—匿å（或化åï¼‰è²¢ç» -者的代碼。所有貢ç»è€…都需è¦åœ¨ä»–們的代碼上「sign off（簽發）ã€ï¼Œè²æ˜Žä»£ç¢¼å¯ä»¥ -在GPLä¸‹èˆ‡å…§æ ¸ä¸€èµ·åˆ†ç™¼ã€‚ç„¡æ³•æ供未被其所有者許å¯çˆ²å…費軟體的代碼，或å¯èƒ½çˆ² +所有貢ç»çµ¦å…§æ ¸çš„ä»£ç¢¼éƒ½å¿…é ˆæ˜¯åˆæ³•çš„å…è²»è»Ÿä»¶ã€‚å› æ¤ï¼Œä¸æŽ¥å—匿å（或化åï¼‰è²¢ç» +者的代碼。所有貢ç»è€…都需è¦åœ¨ä»–們的代碼上“sign off（簽發）â€ï¼Œè²æ˜Žä»£ç¢¼å¯ä»¥ +在GPLä¸‹èˆ‡å…§æ ¸ä¸€èµ·åˆ†ç™¼ã€‚ç„¡æ³•æ供未被其所有者許å¯çˆ²å…費軟件的代碼，或å¯èƒ½çˆ² å…§æ ¸é€ æˆç‰ˆæ¬Šç›¸é—œå•é¡Œçš„代碼（例如，由缺ä¹é©ç•¶ä¿è·çš„åå‘工程工作派生的代碼） ä¸èƒ½è¢«æŽ¥å—。 有關版權å•é¡Œçš„æå•åœ¨Linux開發郵件列表ä¸å¾ˆå¸¸è¦‹ã€‚這樣的å•é¡Œé€šå¸¸æœƒå¾—到ä¸å°‘ç”案， -但請記ä½ï¼Œå›žç”這些å•é¡Œçš„人ä¸æ˜¯å¾‹å¸«ï¼Œä¸èƒ½æ供法律諮詢。如果您有關於Linux原始碼 -的法律å•é¡Œï¼Œæ²’有什麼å¯ä»¥ä»£æ›¿è«®è©¢äº†è§£é€™ä¸€é ˜åŸŸçš„律師。ä¾è³´å¾žæŠ€è¡“郵件列表ä¸ç²å¾— +但請記ä½ï¼Œå›žç”這些å•é¡Œçš„人ä¸æ˜¯å¾‹å¸«ï¼Œä¸èƒ½æ供法律諮詢。如果您有關於Linuxæºä»£ç¢¼ +的法律å•é¡Œï¼Œæ²’有什麼å¯ä»¥ä»£æ›¿è«®è©¢çžè§£é€™ä¸€é ˜åŸŸçš„律師。ä¾è³´å¾žæŠ€è¡“郵件列表ä¸ç²å¾— çš„ç”案是一件冒險的事情。 diff --git a/Documentation/translations/zh_TW/process/2.Process.rst b/Documentation/translations/zh_TW/process/2.Process.rst index 17bb4e07d171..49385d65c216 100644 --- a/Documentation/translations/zh_TW/process/2.Process.rst +++ b/Documentation/translations/zh_TW/process/2.Process.rst @@ -26,8 +26,8 @@ 總覽 ---- -å…§æ ¸é–‹ç™¼äººå“¡ä½¿ç”¨ä¸€å€‹é¬†æ•£çš„åŸºæ–¼æ™‚é–“çš„ç™¼å¸ƒéŽç¨‹ï¼Œæ¯å…©åˆ°ä¸‰å€‹æœˆç™¼å¸ƒä¸€æ¬¡æ–°çš„ä¸»è¦ -å…§æ ¸ç‰ˆæœ¬ã€‚æœ€è¿‘çš„ç™¼å¸ƒæ·å²è¨˜éŒ„如下： +å…§æ ¸é–‹ç™¼äººå“¡ä½¿ç”¨ä¸€å€‹é¬†æ•£çš„åŸºæ–¼æ™‚é–“çš„ç™¼ä½ˆéŽç¨‹ï¼Œæ¯å…©åˆ°ä¸‰å€‹æœˆç™¼ä½ˆä¸€æ¬¡æ–°çš„ä¸»è¦ +å…§æ ¸ç‰ˆæœ¬ã€‚æœ€è¿‘çš„ç™¼ä½ˆæ·å²è¨˜éŒ„如下： ====== ================= 5.0 2019å¹´3月3æ—¥ @@ -42,33 +42,33 @@ 版本包å«å¤§ç´„13000個變更集，變更了幾åè¬è¡Œä»£ç¢¼ã€‚å› æ¤ï¼Œ5.x是Linuxå…§æ ¸é–‹ç™¼çš„å‰ æ²¿ï¼›å…§æ ¸ä½¿ç”¨æ»¾å‹•é–‹ç™¼æ¨¡åž‹ï¼Œä¸æ–·é›†æˆé‡å¤§è®ŠåŒ–。 -å°æ–¼æ¯å€‹ç‰ˆæœ¬çš„補ä¸åˆä½µï¼Œéµå¾ªä¸€å€‹ç›¸å°ç°¡å–®çš„è¦å‰‡ã€‚在æ¯å€‹é–‹ç™¼å‘¨æœŸçš„é–‹é ，「åˆä½µ -窗å£ã€è¢«æ‰“開。這時，被èªçˆ²è¶³å¤ 穩定（並且被開發社å€æŽ¥å—）的代碼被åˆä½µåˆ°ä¸»ç·šå…§ -æ ¸ä¸ã€‚在這段時間內，新開發周期的大部分變更（以åŠæ‰€æœ‰ä¸»è¦è®Šæ›´ï¼‰å°‡ä»¥æŽ¥è¿‘æ¯å¤© -1000次變更（「補ä¸ã€æˆ–「變更集ã€ï¼‰çš„速度åˆä½µã€‚ +å°æ–¼æ¯å€‹ç‰ˆæœ¬çš„補ä¸åˆä½µï¼Œéµå¾ªä¸€å€‹ç›¸å°ç°¡å–®çš„è¦å‰‡ã€‚在æ¯å€‹é–‹ç™¼é€±æœŸçš„é–‹é ，“åˆä½µ +窗å£â€è¢«æ‰“開。這時，被èªçˆ²è¶³å¤ 穩定（並且被開發社å€æŽ¥å—）的代碼被åˆä½µåˆ°ä¸»ç·šå…§ +æ ¸ä¸ã€‚在這段時間內，新開發週期的大部分變更（以åŠæ‰€æœ‰ä¸»è¦è®Šæ›´ï¼‰å°‡ä»¥æŽ¥è¿‘æ¯å¤© +1000次變更（“補ä¸â€æˆ–“變更集â€ï¼‰çš„速度åˆä½µã€‚ ï¼ˆé †ä¾¿èªªä¸€å¥ï¼Œå€¼å¾—注æ„的是，åˆä½µçª—å£æœŸé–“集æˆçš„更改並ä¸æ˜¯æ†‘空產生的；它們是經 æå‰æ”¶é›†ã€æ¸¬è©¦å’Œåˆ†ç´šçš„。ç¨å¾Œå°‡è©³ç´°æ述該éŽç¨‹çš„工作方å¼ã€‚） -åˆä½µçª—å£æŒçºŒå¤§ç´„兩周。在這段時間çµæŸæ™‚，LinusTorvaldså°‡è²æ˜Žçª—å£å·²é—œé–‰ï¼Œä¸¦ -釋放第一個「rcã€å…§æ ¸ã€‚例如，å°æ–¼ç›®æ¨™çˆ²5.6çš„å…§æ ¸ï¼Œåœ¨åˆä½µçª—å£çµæŸæ™‚發生的釋放 +åˆä½µçª—å£æŒçºŒå¤§ç´„兩週。在這段時間çµæŸæ™‚，Linus Torvaldså°‡è²æ˜Žçª—å£å·²é—œé–‰ï¼Œä¸¦ +釋放第一個“rcâ€å…§æ ¸ã€‚例如，å°æ–¼ç›®æ¨™çˆ²5.6çš„å…§æ ¸ï¼Œåœ¨åˆä½µçª—å£çµæŸæ™‚發生的釋放 將被稱爲5.6-rc1。-rc1 版本是一個信號，表示åˆä½µæ–°ç‰¹æ€§çš„時間已經éŽåŽ»ï¼Œç©©å®šä¸‹ä¸€ å€‹å…§æ ¸çš„æ™‚é–“å·²ç¶“åˆ°ä¾†ã€‚ 在接下來的6到10周內，åªæœ‰ä¿®å¾©å•é¡Œçš„補ä¸æ‰æ‡‰è©²æ交給主線。有時會å…許更大的 更改，但這種情æ³å¾ˆå°‘發生；試圖在åˆä½µçª—å£å¤–åˆä½µæ–°åŠŸèƒ½çš„開發人員往往å—ä¸åˆ° å‹å¥½çš„接待。一般來說，如果您錯éŽäº†çµ¦å®šç‰¹æ€§çš„åˆä½µçª—å£ï¼Œæœ€å¥½çš„åšæ³•æ˜¯ç‰å¾…下一 -個開發周期。（å¶çˆ¾æœƒå°æœªæ”¯æŒç¡¬é«”的驅動程åºé€²è¡Œä¾‹å¤–；如果它們ä¸æ”¹è®Šå·²æœ‰ä»£ç¢¼ï¼Œ -則ä¸æœƒå°Žè‡´å›žæ¸ï¼Œæ‡‰è©²å¯ä»¥éš¨æ™‚è¢«å®‰å…¨åœ°åŠ å…¥ï¼‰ã€‚ +個開發週期。（å¶çˆ¾æœƒå°æœªæ”¯æŒç¡¬ä»¶çš„驅動程åºé€²è¡Œä¾‹å¤–；如果它們ä¸æ”¹è®Šå·²æœ‰ä»£ç¢¼ï¼Œ +則ä¸æœƒå°Žè‡´è¿´æ¸ï¼Œæ‡‰è©²å¯ä»¥éš¨æ™‚è¢«å®‰å…¨åœ°åŠ å…¥ï¼‰ã€‚ -隨著修復程åºé€²å…¥ä¸»ç·šï¼Œè£œä¸é€Ÿåº¦å°‡éš¨è‘—時間的推移而變慢。Linus大約æ¯å‘¨ç™¼å¸ƒä¸€æ¬¡ -æ–°çš„-rcå…§æ ¸ï¼›åœ¨å…§æ ¸è¢«èªçˆ²è¶³å¤ 穩定並最終發布å‰ï¼Œä¸€èˆ¬æœƒé”到-rc6到-rc9之間。 +隨ç€ä¿®å¾©ç¨‹åºé€²å…¥ä¸»ç·šï¼Œè£œä¸é€Ÿåº¦å°‡éš¨ç€æ™‚間的推移而變慢。Linus大約æ¯é€±ç™¼ä½ˆä¸€æ¬¡ +æ–°çš„-rcå…§æ ¸ï¼›åœ¨å…§æ ¸è¢«èªçˆ²è¶³å¤ 穩定並最終發佈å‰ï¼Œä¸€èˆ¬æœƒé”到-rc6到-rc9之間。 然後，整個éŽç¨‹åˆé‡æ–°é–‹å§‹äº†ã€‚ -例如，這裡是5.4的開發周期進行情æ³ï¼ˆ2019年）: +例如，這è£æ˜¯5.4的開發週期進行情æ³ï¼ˆ2019年）: ============== ============================== - ä¹æœˆ 15 5.3 穩定版發布 + ä¹æœˆ 15 5.3 穩定版發佈 ä¹æœˆ 30 5.4-rc1 åˆä½µçª—å£é—œé–‰ å月 6 5.4-rc2 å月 13 5.4-rc3 @@ -77,26 +77,26 @@ å一月 3 5.4-rc6 å一月 10 5.4-rc7 å一月 17 5.4-rc8 - å一月 24 5.4 穩定版發布 + å一月 24 5.4 穩定版發佈 ============== ============================== -開發人員如何決定何時çµæŸé–‹ç™¼å‘¨æœŸä¸¦å‰µå»ºç©©å®šç‰ˆæœ¬ï¼Ÿæœ€é‡è¦çš„指標是以å‰ç‰ˆæœ¬çš„ -回æ¸åˆ—表。ä¸æ¡è¿Žå‡ºç¾ä»»ä½•éŒ¯èª¤ï¼Œä½†æ˜¯é‚£äº›ç ´å£žäº†ä»¥å‰èƒ½å·¥ä½œçš„系統的錯誤被èªçˆ²æ˜¯ -特別嚴é‡çš„ã€‚å› æ¤ï¼Œå°Žè‡´å›žæ¸çš„補ä¸æ˜¯ä¸å—æ¡è¿Žçš„，很å¯èƒ½åœ¨ç©©å®šæœŸå…§åˆªé™¤ã€‚ +開發人員如何決定何時çµæŸé–‹ç™¼é€±æœŸä¸¦å‰µå»ºç©©å®šç‰ˆæœ¬ï¼Ÿæœ€é‡è¦çš„指標是以å‰ç‰ˆæœ¬çš„ +è¿´æ¸åˆ—表。ä¸æ¡è¿Žå‡ºç¾ä»»ä½•éŒ¯èª¤ï¼Œä½†æ˜¯é‚£äº›ç ´å£žäº†ä»¥å‰èƒ½å·¥ä½œçš„系統的錯誤被èªçˆ²æ˜¯ +特別嚴é‡çš„ã€‚å› æ¤ï¼Œå°Žè‡´è¿´æ¸çš„補ä¸æ˜¯ä¸å—æ¡è¿Žçš„，很å¯èƒ½åœ¨ç©©å®šæœŸå…§åˆªé™¤ã€‚ -開發人員的目標是在穩定發布之å‰ä¿®å¾©æ‰€æœ‰å·²çŸ¥çš„回æ¸ã€‚在ç¾å¯¦ä¸–ç•Œä¸ï¼Œé€™ç¨®å®Œç¾Žæ˜¯ +開發人員的目標是在穩定發佈之å‰ä¿®å¾©æ‰€æœ‰å·²çŸ¥çš„è¿´æ¸ã€‚在ç¾å¯¦ä¸–ç•Œä¸ï¼Œé€™ç¨®å®Œç¾Žæ˜¯ 很難實ç¾çš„；在這種è¦æ¨¡çš„é …ç›®ä¸ï¼Œè®Šæ•¸å¤ªå¤šäº†ã€‚需è¦èªªæ˜Žçš„是，延é²æœ€çµ‚版本åªæœƒ -使å•é¡Œè®Šå¾—更糟；ç‰å¾…下一個åˆä½µçª—å£çš„更改將變多，導致下次出ç¾æ›´å¤šçš„回æ¸éŒ¯èª¤ã€‚ -å› æ¤ï¼Œå¤§å¤šæ•¸5.xå…§æ ¸éƒ½æœ‰ä¸€äº›å·²çŸ¥çš„å›žæ¸éŒ¯èª¤ï¼Œä¸éŽï¼Œå¸Œæœ›æ²’有一個是嚴é‡çš„。 +使å•é¡Œè®Šå¾—更糟；ç‰å¾…下一個åˆä½µçª—å£çš„更改將變多，導致下次出ç¾æ›´å¤šçš„è¿´æ¸éŒ¯èª¤ã€‚ +å› æ¤ï¼Œå¤§å¤šæ•¸5.xå…§æ ¸éƒ½æœ‰ä¸€äº›å·²çŸ¥çš„è¿´æ¸éŒ¯èª¤ï¼Œä¸éŽï¼Œå¸Œæœ›æ²’有一個是嚴é‡çš„。 -一旦一個穩定的版本發布，它的æŒçºŒç¶è·å·¥ä½œå°±è¢«ç§»äº¤çµ¦ã€Œç©©å®šåœ˜éšŠã€ï¼Œç›®å‰ç”± -Greg Kroah-Hartmané ˜å°Žã€‚ç©©å®šåœ˜éšŠå°‡ä½¿ç”¨5.x.y編號方案ä¸å®šæœŸåœ°ç™¼å¸ƒç©©å®šç‰ˆæœ¬çš„ +一旦一個穩定的版本發佈，它的æŒçºŒç¶è·å·¥ä½œå°±è¢«ç§»äº¤çµ¦â€œç©©å®šåœ˜éšŠâ€ï¼Œç›®å‰ç”± +Greg Kroah-Hartmané ˜å°Žã€‚ç©©å®šåœ˜éšŠå°‡ä½¿ç”¨5.x.y編號方案ä¸å®šæœŸåœ°ç™¼ä½ˆç©©å®šç‰ˆæœ¬çš„ 更新。è¦åˆå…¥æ›´æ–°ç‰ˆæœ¬ï¼Œè£œä¸å¿…é ˆï¼ˆ1）修復一個é‡è¦çš„缺陷，且（2）已經åˆä½µåˆ° -下一個開發版本主線ä¸ã€‚å…§æ ¸é€šå¸¸æœƒåœ¨å…¶åˆå§‹ç‰ˆæœ¬å¾Œçš„一個以上的開發周期內收到 +下一個開發版本主線ä¸ã€‚å…§æ ¸é€šå¸¸æœƒåœ¨å…¶åˆå§‹ç‰ˆæœ¬å¾Œçš„一個以上的開發週期內收到 穩定版更新。例如，5.2å…§æ ¸çš„æ·å²å¦‚下（2019年）： ============== =============================== - 七月 7 5.2 穩定版發布 + 七月 7 5.2 穩定版發佈 七月 13 5.2.1 七月 21 5.2.2 七月 26 5.2.3 @@ -108,7 +108,7 @@ Greg Kroah-Hartmané ˜å°Žã€‚ç©©å®šåœ˜éšŠå°‡ä½¿ç”¨5.x.y編號方案ä¸å®šæœŸåœ°ç™¼ 5.2.21是5.2版本的最終穩定更新。 -æœ‰äº›å…§æ ¸è¢«æŒ‡å®šçˆ²ã€Œé•·æœŸã€å…§æ ¸ï¼›å®ƒå€‘將得到更長時間的支æŒã€‚在本文ä¸ï¼Œç•¶å‰çš„長期 +æœ‰äº›å…§æ ¸è¢«æŒ‡å®šçˆ²â€œé•·æœŸâ€å…§æ ¸ï¼›å®ƒå€‘將得到更長時間的支æŒã€‚在本文ä¸ï¼Œç•¶å‰çš„長期 å…§æ ¸åŠå…¶ç¶è·è€…是： ====== ================================ ================ @@ -121,9 +121,9 @@ Greg Kroah-Hartmané ˜å°Žã€‚ç©©å®šåœ˜éšŠå°‡ä½¿ç”¨5.x.y編號方案ä¸å®šæœŸåœ°ç™¼ ====== ================================ ================ 長期支æŒå…§æ ¸çš„é¸æ“‡ç´”粹是ç¶è·äººå“¡æ˜¯å¦æœ‰éœ€æ±‚和時間來ç¶è·è©²ç‰ˆæœ¬çš„å•é¡Œã€‚ -ç›®å‰é‚„沒有爲å³å°‡ç™¼å¸ƒçš„任何特定版本æ供長期支æŒçš„已知計劃。 +ç›®å‰é‚„沒有爲å³å°‡ç™¼ä½ˆçš„任何特定版本æ供長期支æŒçš„已知計劃。 -補ä¸çš„生命周期 +補ä¸çš„生命週期 -------------- 補ä¸ä¸æœƒç›´æŽ¥å¾žé–‹ç™¼äººå“¡çš„éµç›¤é€²å…¥ä¸»ç·šå…§æ ¸ã€‚相å，有一個ç¨å¾®è¤‡é›œï¼ˆå¦‚æžœæœ‰äº›éž @@ -140,7 +140,7 @@ Greg Kroah-Hartmané ˜å°Žã€‚ç©©å®šåœ˜éšŠå°‡ä½¿ç”¨5.x.y編號方案ä¸å®šæœŸåœ°ç™¼ 是在ä¸æ¶‰åŠç¤¾å€çš„情æ³ä¸‹å®Œæˆçš„，但是如果å¯èƒ½çš„話，最好是在公開的情æ³ä¸‹å®Œæˆ é€™é …å·¥ä½œï¼›é€™æ¨£å¯ä»¥ç¯€çœå¾ˆå¤šç¨å¾Œå†é‡æ–°è¨è¨ˆçš„時間。 -- 早期評審。補ä¸è¢«ç™¼å¸ƒåˆ°ç›¸é—œçš„郵件列表ä¸ï¼Œåˆ—表ä¸çš„開發人員會回復他們å¯èƒ½æœ‰ +- 早期評審。補ä¸è¢«é«®å¸ƒåˆ°ç›¸é—œçš„郵件列表ä¸ï¼Œåˆ—表ä¸çš„開發人員會回覆他們å¯èƒ½æœ‰ çš„ä»»ä½•è©•è«–ã€‚å¦‚æžœä¸€åˆ‡é †åˆ©çš„è©±ï¼Œé€™å€‹éŽç¨‹æ‡‰è©²æœƒç™¼ç¾è£œä¸çš„任何主è¦å•é¡Œã€‚ - 更廣泛的評審。當補ä¸æŽ¥è¿‘準備好ç´å…¥ä¸»ç·šæ™‚，它應該被相關的å系統ç¶è·äººå“¡ @@ -153,48 +153,48 @@ Greg Kroah-Hartmané ˜å°Žã€‚ç©©å®šåœ˜éšŠå°‡ä½¿ç”¨5.x.y編號方案ä¸å®šæœŸåœ°ç™¼ 如果您的補ä¸å¾—到了需è¦æ›´æ”¹çš„å饋，那麼您應該進行這些更改，或者解釋爲何 ä¸æ‡‰è©²é€²è¡Œé€™äº›æ›´æ”¹ã€‚如果您的補ä¸æ²’有評審æ„見，也沒有被其相應的å系統或 驅動程åºç¶è·è€…接å—ï¼Œé‚£éº¼æ‚¨æ‡‰è©²å …æŒä¸æ‡ˆåœ°å°‡è£œä¸æ›´æ–°åˆ°ç•¶å‰å…§æ ¸ä½¿å…¶å¯è¢«æ£å¸¸ - 應用，並ä¸æ–·åœ°ç™¼é€å®ƒä»¥ä¾›å¯©æŸ¥å’Œåˆä½µã€‚ + 應用，並ä¸æ–·åœ°ç™¼é€å®ƒä»¥ä¾›å¯©æŸ¥å’Œåˆä¸¦ã€‚ - åˆä½µåˆ°ä¸»ç·šã€‚最終，一個æˆåŠŸçš„補ä¸å°‡è¢«åˆä½µåˆ°ç”±LinusTorvalds管ç†çš„主線å˜å„²åº« ä¸ã€‚æ¤æ™‚å¯èƒ½æœƒå‡ºç¾æ›´å¤šçš„è©•è«–å’Œ/或å•é¡Œï¼›å°é–‹ç™¼äººå“¡ä¾†èªªæ‡‰å°é€™äº›å•é¡Œä¸¦è§£æ±º 出ç¾çš„任何å•é¡Œä»å¾ˆé‡è¦ã€‚ -- 穩定版發布。大é‡ç”¨æˆ¶å¯èƒ½å—æ¤è£œä¸å½±éŸ¿ï¼Œå› æ¤å¯èƒ½å†æ¬¡å‡ºç¾æ–°çš„å•é¡Œã€‚ +- 穩定版發佈。大é‡ç”¨æˆ¶å¯èƒ½å—æ¤è£œä¸å½±éŸ¿ï¼Œå› æ¤å¯èƒ½å†æ¬¡å‡ºç¾æ–°çš„å•é¡Œã€‚ - 長期ç¶è·ã€‚雖然開發人員在åˆä½µä»£ç¢¼å¾Œå¯èƒ½æœƒå¿˜è¨˜ä»£ç¢¼ï¼Œä½†é€™ç¨®è¡Œçˆ²å¾€å¾€æœƒçµ¦é–‹ç™¼ 社å€ç•™ä¸‹ä¸è‰¯å°è±¡ã€‚åˆä½µä»£ç¢¼æ¶ˆé™¤äº†ä¸€äº›ç¶è·è² æ“”ï¼Œå› çˆ²å…¶ä»–äººå°‡ä¿®å¾©ç”±API更改 引起的å•é¡Œã€‚但是，如果代碼è¦é•·æœŸä¿æŒå¯ç”¨ï¼ŒåŽŸå§‹é–‹ç™¼äººå“¡æ‡‰è©²ç¹¼çºŒçˆ²ä»£ç¢¼è² 責。 -å…§æ ¸é–‹ç™¼äººå“¡ï¼ˆæˆ–ä»–å€‘çš„åƒ±ä¸»ï¼‰çŠ¯çš„æœ€å¤§éŒ¯èª¤ä¹‹ä¸€æ˜¯è©¦åœ–å°‡æµç¨‹ç°¡åŒ–爲一個「åˆä½µåˆ° -主線ã€æ¥é©Ÿã€‚這種方法總是會讓所有相關人員感到沮喪。 +å…§æ ¸é–‹ç™¼äººå“¡ï¼ˆæˆ–ä»–å€‘çš„åƒ±ä¸»ï¼‰çŠ¯çš„æœ€å¤§éŒ¯èª¤ä¹‹ä¸€æ˜¯è©¦åœ–å°‡æµç¨‹ç°¡åŒ–爲一個“åˆä½µåˆ° +主線â€æ¥é©Ÿã€‚這種方法總是會讓所有相關人員感到沮喪。 補ä¸å¦‚ä½•é€²å…¥å…§æ ¸ ---------------- -åªæœ‰ä¸€å€‹äººå¯ä»¥å°‡è£œä¸åˆä½µåˆ°ä¸»ç·šå…§æ ¸å˜å„²åº«ä¸ï¼šLinusTorvalds。但是，在進入 +åªæœ‰ä¸€å€‹äººå¯ä»¥å°‡è£œä¸åˆä½µåˆ°ä¸»ç·šå…§æ ¸å˜å„²åº«ä¸ï¼šLinus Torvalds。但是，在進入 2.6.38å…§æ ¸çš„9500多個補ä¸ä¸ï¼Œåªæœ‰112個（大約1.3%）是由Linus自己直接é¸æ“‡çš„。 å…§æ ¸é …ç›®å·²ç¶“ç™¼å±•åˆ°ä¸€å€‹æ²’æœ‰ä¸€å€‹é–‹ç™¼äººå“¡å¯ä»¥åœ¨æ²’有支æŒçš„情æ³ä¸‹æª¢æŸ¥å’Œé¸æ“‡æ¯å€‹ 補ä¸çš„è¦æ¨¡ã€‚å…§æ ¸é–‹ç™¼äººå“¡è™•ç†é€™ç¨®å¢žé•·çš„æ–¹å¼æ˜¯ä½¿ç”¨åœç¹žä¿¡ä»»éˆæ§‹å»ºçš„助ç†ç³»çµ±ã€‚ å…§æ ¸ä»£ç¢¼åº«åœ¨é‚輯上被分解爲一組å系統：網絡ã€ç‰¹å®šé«”ç³»çµæ§‹æ”¯æŒã€å…§å˜ç®¡ç†ã€è¦– é »è¨å‚™ç‰ã€‚大多數å系統都有一個指定的ç¶è·äººå“¡ï¼Œå…¶ç¸½é«”è² è²¬è©²å系統ä¸çš„代碼。 -這些å系統ç¶è·è€…（鬆散地）是他們所管ç†çš„å…§æ ¸éƒ¨åˆ†çš„ã€Œå®ˆé–€å“¡ã€ï¼›ä»–們（通常） +這些å系統ç¶è·è€…（鬆散地）是他們所管ç†çš„å…§æ ¸éƒ¨åˆ†çš„â€œå®ˆé–€å“¡â€ï¼›ä»–們（通常） 會接å—一個補ä¸ä»¥åŒ…å«åˆ°ä¸»ç·šå…§æ ¸ä¸ã€‚ -å系統ç¶è·äººå“¡æ¯å€‹äººéƒ½ç®¡ç†è‘—è‡ªå·±ç‰ˆæœ¬çš„å…§æ ¸åŽŸå§‹ç¢¼æ¨¹ï¼Œé€šå¸¸ï¼ˆä¸¦éžç¸½æ˜¯ï¼‰ä½¿ç”¨Git。 +å系統ç¶è·äººå“¡æ¯å€‹äººéƒ½ç®¡ç†ç€è‡ªå·±ç‰ˆæœ¬çš„å…§æ ¸æºä»£ç¢¼æ¨¹ï¼Œé€šå¸¸ï¼ˆä¸¦éžç¸½æ˜¯ï¼‰ä½¿ç”¨Git。 Gitç‰å·¥å…·ï¼ˆä»¥åŠQuilt或Mercurialç‰ç›¸é—œå·¥å…·ï¼‰å…許ç¶è·äººå“¡è·Ÿè¹¤è£œä¸åˆ—表，包括作者 ä¿¡æ¯å’Œå…¶ä»–元數據。在任何給定的時間，ç¶è·äººå“¡éƒ½å¯ä»¥ç¢ºå®šä»–或她的å˜å„²åº«ä¸çš„哪 些補ä¸åœ¨ä¸»ç·šä¸æ‰¾ä¸åˆ°ã€‚ -當åˆä½µçª—å£æ‰“é–‹æ™‚ï¼Œé ‚ç´šç¶è·äººå“¡å°‡è¦æ±‚Linus從å˜å„²åº«ä¸ã€Œæ‹‰å‡ºã€ä»–們爲åˆä½µé¸æ“‡ +當åˆä¸¦çª—å£æ‰“é–‹æ™‚ï¼Œé ‚ç´šç¶è·äººå“¡å°‡è¦æ±‚Linus從å˜å„²åº«ä¸â€œæ‹‰å‡ºâ€ä»–們爲åˆä½µé¸æ“‡ 的補ä¸ã€‚如果LinusåŒæ„，補ä¸æµå°‡æµå‘ä»–çš„å˜å„²åº«ï¼Œæˆçˆ²ä¸»ç·šå…§æ ¸çš„一部分。 Linuså°æ‹‰å–ä¸æŽ¥æ”¶åˆ°çš„特定補ä¸çš„關注程度å„ä¸ç›¸åŒã€‚很明顯，有時他看起來很 -關注。但是一般來說，Linus相信å系統ç¶è·äººå“¡ä¸æœƒå‘上游發é€å£žè£œä¸ã€‚ +關注。但是一般來說，Linus相信å系統ç¶è·äººå“¡ä¸æœƒå‘上éŠç™¼é€å£žè£œä¸ã€‚ -å系統ç¶è·äººå“¡åéŽä¾†ä¹Ÿå¯ä»¥å¾žå…¶ä»–ç¶è·äººå“¡é‚£è£¡ç²å–補ä¸ã€‚例如，網絡樹是由首先 +å系統ç¶è·äººå“¡åéŽä¾†ä¹Ÿå¯ä»¥å¾žå…¶ä»–ç¶è·äººå“¡é‚£è£ç²å–補ä¸ã€‚例如，網絡樹是由首先 在專用於網絡è¨å‚™é©…動程åºã€ç„¡ç·šç¶²çµ¡ç‰çš„樹ä¸ç©ç´¯çš„補ä¸æ§‹å»ºçš„。æ¤å˜å„²éˆå¯ä»¥ -ä»»æ„長，但很少超éŽå…©å€‹æˆ–三個連çµã€‚由於éˆä¸çš„æ¯å€‹ç¶è·è€…都信任那些管ç†è¼ƒä½Ž -級別樹的ç¶è·è€…，所以這個éŽç¨‹ç¨±çˆ²ã€Œä¿¡ä»»éˆã€ã€‚ +ä»»æ„長，但很少超éŽå…©å€‹æˆ–三個éˆæŽ¥ã€‚由於éˆä¸çš„æ¯å€‹ç¶è·è€…都信任那些管ç†è¼ƒä½Ž +級別樹的ç¶è·è€…，所以這個éŽç¨‹ç¨±çˆ²â€œä¿¡ä»»éˆâ€ã€‚ 顯然，在這樣的系統ä¸ï¼Œç²å–å…§æ ¸è£œä¸å–決於找到æ£ç¢ºçš„ç¶è·è€…。直接å‘Linusç™¼é€ è£œä¸é€šå¸¸ä¸æ˜¯æ£ç¢ºçš„方法。 @@ -204,30 +204,30 @@ Next 樹 å系統樹éˆå¼•å°Žè£œä¸æµåˆ°å…§æ ¸ï¼Œä½†å®ƒä¹Ÿæ出了一個有趣的å•é¡Œï¼šå¦‚果有人想查看爲 下一個åˆä½µçª—å£æº–備的所有補ä¸æ€Žéº¼è¾¦ï¼Ÿé–‹ç™¼äººå“¡å°‡æ„Ÿèˆˆè¶£çš„是，還有什麼其他的 -更改有待解決，以了解是å¦å˜åœ¨éœ€è¦æ“”心的è¡çªï¼›ä¾‹å¦‚ï¼Œæ›´æ”¹æ ¸å¿ƒå…§æ ¸å‡½æ•¸åŽŸåž‹çš„ +更改有待解決，以çžè§£æ˜¯å¦å˜åœ¨éœ€è¦æ“”心的è¡çªï¼›ä¾‹å¦‚ï¼Œæ›´æ”¹æ ¸å¿ƒå…§æ ¸å‡½æ•¸åŽŸåž‹çš„ 修補程åºå°‡èˆ‡ä½¿ç”¨è©²å‡½æ•¸èˆŠå½¢å¼çš„任何其他修補程åºè¡çªã€‚審查人員和測試人員希望 在所有這些變更到é”ä¸»ç·šå…§æ ¸ä¹‹å‰ï¼Œèƒ½å¤ 訪å•å®ƒå€‘的集æˆå½¢å¼çš„變更。您å¯ä»¥å¾žæ‰€æœ‰ 相關的å系統樹ä¸æå–æ›´æ”¹ï¼Œä½†é€™å°‡æ˜¯ä¸€é …è¤‡é›œä¸”å®¹æ˜“å‡ºéŒ¯çš„å·¥ä½œã€‚ -解決方案以-next樹的形å¼å‡ºç¾ï¼Œåœ¨é€™è£¡åç³»çµ±æ¨¹è¢«æ”¶é›†ä»¥ä¾›æ¸¬è©¦å’Œå¯©æŸ¥ã€‚é€™äº›æ¨¹ä¸ -ç”±Andrew Mortonç¶è·çš„較è€çš„一個，被稱爲「-mmã€ï¼ˆç”¨æ–¼å…§å˜ç®¡ç†ï¼Œå‰µå»ºæ™‚爲æ¤ï¼‰ã€‚ +解決方案以-next樹的形å¼å‡ºç¾ï¼Œåœ¨é€™è£åç³»çµ±æ¨¹è¢«æ”¶é›†ä»¥ä¾›æ¸¬è©¦å’Œå¯©æŸ¥ã€‚é€™äº›æ¨¹ä¸ +ç”±Andrew Mortonç¶è·çš„較è€çš„一個，被稱爲“-mmâ€ï¼ˆç”¨æ–¼å…§å˜ç®¡ç†ï¼Œå‰µå»ºæ™‚爲æ¤ï¼‰ã€‚ -mm 樹集æˆäº†ä¸€é•·ä¸²å系統樹ä¸çš„補ä¸ï¼›å®ƒé‚„包å«ä¸€äº›æ—¨åœ¨å¹«åŠ©èª¿è©¦çš„補ä¸ã€‚ 除æ¤ä¹‹å¤–，-mm 還包å«å¤§é‡ç”±Andrew直接é¸æ“‡çš„補ä¸ã€‚這些補ä¸å¯èƒ½å·²ç¶“發布在郵件 列表上，或者它們å¯èƒ½æ‡‰ç”¨æ–¼å…§æ ¸ä¸æœªæŒ‡å®šå系統樹的部分。åŒæ™‚，-mm 作爲最後 手段的å系統樹；如果沒有其他明顯的路徑å¯ä»¥è®“補ä¸é€²å…¥ä¸»ç·šï¼Œé‚£éº¼å®ƒå¾ˆå¯èƒ½æœ€ 終é¸æ“‡-mm 樹。累ç©åœ¨-mm ä¸çš„å„種補ä¸æœ€çµ‚將被轉發到é©ç•¶çš„å系統樹，或者直接 -發é€åˆ°Linus。在典型的開發周期ä¸ï¼Œå¤§ç´„5-10%的補ä¸é€šéŽ-mm 進入主線。 +發é€åˆ°Linus。在典型的開發週期ä¸ï¼Œå¤§ç´„5-10%的補ä¸é€šéŽ-mm 進入主線。 -當å‰-mm 補ä¸å¯åœ¨ã€Œmmotmã€ï¼ˆ-mm of the moment）目錄ä¸æ‰¾åˆ°ï¼š +當å‰-mm 補ä¸å¯åœ¨â€œmmotmâ€ï¼ˆ-mm of the moment）目錄ä¸æ‰¾åˆ°ï¼š https://www.ozlabs.org/~akpm/mmotm/ 然而，使用MMOTM樹å¯èƒ½æœƒå分令人é 疼；它甚至å¯èƒ½ç„¡æ³•ç·¨è¯ã€‚ -下一個周期補ä¸åˆä½µçš„主è¦æ¨¹æ˜¯linux-next，由Stephen Rothwell ç¶è·ã€‚æ ¹æ“šè¨è¨ˆ +下一個週期補ä¸åˆä½µçš„主è¦æ¨¹æ˜¯linux-next，由Stephen Rothwell ç¶è·ã€‚æ ¹æ“šè¨è¨ˆ linux-next 是下一個åˆä½µçª—å£é—œé–‰å¾Œä¸»ç·šçš„快照。linux-next樹在Linux-kernel å’Œ -Linux-next 郵件列表ä¸ç™¼å¸ƒï¼Œå¯å¾žä»¥ä¸‹ä½ç½®ä¸‹è¼‰ï¼š +Linux-next 郵件列表ä¸ç™¼ä½ˆï¼Œå¯å¾žä»¥ä¸‹ä½ç½®ä¸‹è¼‰ï¼š https://www.kernel.org/pub/linux/kernel/next/ @@ -237,7 +237,7 @@ Linux-next 已經æˆçˆ²å…§æ ¸é–‹ç™¼éŽç¨‹ä¸ä¸å¯æˆ–缺的一部分；在一個 Staging 樹 ---------- -å…§æ ¸åŽŸå§‹ç¢¼æ¨¹åŒ…å«drivers/staging/目錄，其ä¸æœ‰è¨±å¤šé©…動程åºæˆ–文件系統的å目錄 +å…§æ ¸æºä»£ç¢¼æ¨¹åŒ…å«drivers/staging/目錄，其ä¸æœ‰è¨±å¤šé©…動程åºæˆ–文件系統的å目錄 æ£åœ¨è¢«æ·»åŠ åˆ°å…§æ ¸æ¨¹ä¸ã€‚它們在ä»ç„¶éœ€è¦æ›´å¤šçš„ä¿®æ£çš„時候å¯ä»¥ä¿ç•™åœ¨driver/staging/ 目錄ä¸ï¼›ä¸€æ—¦å®Œæˆï¼Œå°±å¯ä»¥å°‡å®ƒå€‘ç§»åˆ°å…§æ ¸ä¸ã€‚這是一種跟蹤ä¸ç¬¦åˆLinuxå…§æ ¸ç·¨ç¢¼æˆ– 質é‡æ¨™æº–的驅動程åºçš„方法，人們å¯èƒ½å¸Œæœ›ä½¿ç”¨å®ƒå€‘並跟蹤開發。 @@ -251,7 +251,7 @@ Greg Kroah Hartman ç›®å‰è² 責ç¶è·staging 樹。ä»éœ€è¦ä¿®æ£çš„é©…å‹•ç¨‹åº Staging 是一種讓新的驅動程åºé€²å…¥ä¸»ç·šçš„相å°å®¹æ˜“的方法，它們會幸é‹åœ°å¼•èµ·å…¶ä»– 開發人員的注æ„，並迅速改進。然而，進入staging並ä¸æ˜¯æ•…事的çµå°¾ï¼›stagingä¸ æ²’æœ‰çœ‹åˆ°å¸¸è¦é€²å±•çš„代碼最終將被刪除。經銷商也傾å‘於相å°ä¸é¡˜æ„使用stagingé©…å‹• -程åºã€‚å› æ¤ï¼Œåœ¨æˆçˆ²ä¸€å€‹åˆé©çš„主線驅動的路上，staging 僅是一個ä¸è½‰ç«™ã€‚ +程åºã€‚å› æ¤ï¼Œåœ¨æˆçˆ²ä¸€å€‹åˆé©çš„主線驅動的路上，staging 僅是一箇ä¸è½‰ç«™ã€‚ 工具 ---- @@ -260,9 +260,9 @@ Staging 是一種讓新的驅動程åºé€²å…¥ä¸»ç·šçš„相å°å®¹æ˜“的方法，它 能力。如果沒有é©ç•¶å¼·å¤§çš„工具，整個系統將無法在任何地方æ£å¸¸å·¥ä½œã€‚關於如何使用 這些工具的教程é é 超出了本文檔的範åœï¼Œä½†é‚„是用一點篇幅介紹一些關éµé»žã€‚ -到目å‰çˆ²æ¢ï¼Œå…§æ ¸ç¤¾å€ä½¿ç”¨çš„主è¦åŽŸå§‹ç¢¼ç®¡ç†ç³»çµ±æ˜¯git。Git是在自由軟體社å€ä¸é–‹ç™¼ -的許多分布å¼ç‰ˆæœ¬æŽ§åˆ¶ç³»çµ±ä¹‹ä¸€ã€‚它éžå¸¸é©åˆå…§æ ¸é–‹ç™¼ï¼Œå› 爲它在處ç†å¤§åž‹å˜å„²åº«å’Œ -大é‡è£œä¸æ™‚性能éžå¸¸å¥½ã€‚它也以難以å¸ç¿’和使用而著稱，儘管隨著時間的推移它變得 +到目å‰çˆ²æ¢ï¼Œå…§æ ¸ç¤¾å€ä½¿ç”¨çš„主è¦æºä»£ç¢¼ç®¡ç†ç³»çµ±æ˜¯git。Git是在自由軟件社å€ä¸é–‹ç™¼ +的許多分佈å¼ç‰ˆæœ¬æŽ§åˆ¶ç³»çµ±ä¹‹ä¸€ã€‚它éžå¸¸é©åˆå…§æ ¸é–‹ç™¼ï¼Œå› 爲它在處ç†å¤§åž‹å˜å„²åº«å’Œ +大é‡è£œä¸æ™‚性能éžå¸¸å¥½ã€‚它也以難以å¸ç¿’和使用而著稱，儘管隨ç€æ™‚間的推移它變得 更好了。å°æ–¼å…§æ ¸é–‹ç™¼äººå“¡ä¾†èªªï¼Œå°Gitçš„æŸç¨®ç†Ÿæ‚‰å¹¾ä¹Žæ˜¯ä¸€ç¨®è¦æ±‚ï¼›å³ä½¿ä»–們ä¸å°‡å®ƒ 用於自己的工作，他們也需è¦Git來跟上其他開發人員（以åŠä¸»ç·šï¼‰æ£åœ¨åšçš„事情。 @@ -270,7 +270,7 @@ Staging 是一種讓新的驅動程åºé€²å…¥ä¸»ç·šçš„相å°å®¹æ˜“的方法，它 https://git-scm.com/ -æ¤é é¢åŒ…å«äº†æ–‡æª”和教程的連çµã€‚ +æ¤é é¢åŒ…å«äº†æ–‡æª”和教程的éˆæŽ¥ã€‚ 在ä¸ä½¿ç”¨gitçš„å…§æ ¸é–‹ç™¼äººå“¡ä¸ï¼Œæœ€æµè¡Œçš„é¸æ“‡å¹¾ä¹Žè‚¯å®šæ˜¯Mercurial： @@ -282,16 +282,16 @@ Mercurial與Git共享許多特性，但它æ供了一個界é¢ï¼Œè¨±å¤šäººè¦ºå¾ https://savannah.nongnu.org/projects/quilt -Quilt 是一個補ä¸ç®¡ç†ç³»çµ±ï¼Œè€Œä¸æ˜¯åŽŸå§‹ç¢¼ç®¡ç†ç³»çµ±ã€‚它ä¸æœƒéš¨è‘—時間的推移跟蹤æ·å²ï¼› +Quilt 是一個補ä¸ç®¡ç†ç³»çµ±ï¼Œè€Œä¸æ˜¯æºä»£ç¢¼ç®¡ç†ç³»çµ±ã€‚它ä¸æœƒéš¨ç€æ™‚間的推移跟蹤æ·å²ï¼› 相å，它é¢å‘æ ¹æ“šä¸æ–·ç™¼å±•çš„代碼庫跟蹤一組特定的更改。一些主è¦çš„å系統ç¶è·äººå“¡ -使用Quilt來管ç†æ‰“ç®—å‘上游移動的補ä¸ã€‚å°æ–¼æŸäº›æ¨¹çš„管ç†ï¼ˆä¾‹å¦‚-mm），quilt 是 +使用Quilt來管ç†æ‰“ç®—å‘上éŠç§»å‹•çš„補ä¸ã€‚å°æ–¼æŸäº›æ¨¹çš„管ç†ï¼ˆä¾‹å¦‚-mm），quilt 是 最好的工具。 郵件列表 -------- 大é‡çš„Linuxå…§æ ¸é–‹ç™¼å·¥ä½œæ˜¯é€šéŽéƒµä»¶åˆ—表完æˆçš„。如果ä¸åŠ 入至少一個æŸå€‹åˆ—表， -就很難æˆçˆ²ç¤¾å€ä¸çš„一個「全功能ã€æˆå“¡ã€‚但是，Linux郵件列表å°é–‹ç™¼äººå“¡ä¾†èªªä¹Ÿæ˜¯ +就很難æˆçˆ²ç¤¾å€ä¸çš„一個“全功能â€æˆå“¡ã€‚但是，Linux郵件列表å°é–‹ç™¼äººå“¡ä¾†èªªä¹Ÿæ˜¯ 一個潛在的å±éšªï¼Œä»–們å¯èƒ½æœƒè¢«ä¸€å †é›»å郵件淹沒ã€é•åLinux列表上使用的約定， 或者兩者兼而有之。 @@ -316,14 +316,14 @@ redhat.com/mailman/listinfo。 - ä¸è¦å›žå¾©æŒ‘事的人。如果有人試圖激起憤怒，請忽略他們。 -- 當回復Linuxå…§æ ¸é›»å郵件（或其他列表上的電å郵件）時，請爲所有相關人員ä¿ç•™ +- 當回覆Linuxå…§æ ¸é›»å郵件（或其他列表上的電å郵件）時，請爲所有相關人員ä¿ç•™ Cc: 抄é€é 。如果沒有確實的ç†ç”±ï¼ˆå¦‚明確的請求），則ä¸æ‡‰åˆªé™¤æ”¶ä»¶äººã€‚ä¸€å®šè¦ ç¢ºä¿ä½ è¦å›žå¾©çš„人在抄é€åˆ—表ä¸ã€‚é€™å€‹æ…£ä¾‹ä¹Ÿä½¿ä½ ä¸å¿…在回覆郵件時明確è¦æ±‚被抄é€ã€‚ - 在æ出å•é¡Œä¹‹å‰ï¼Œæœç´¢åˆ—表å˜æª”（和整個網絡）。有些開發人員å¯èƒ½æœƒå°é‚£äº›é¡¯ç„¶ 沒有完æˆå®¶åºä½œæ¥çš„人感到ä¸è€ç…©ã€‚ -- é¿å…é ‚éƒ¨å›žå¾©ï¼ˆæŠŠä½ çš„ç”æ¡ˆæ”¾åœ¨ä½ è¦å›žå¾©çš„引文上é¢çš„åšæ³•ï¼‰ã€‚é€™æœƒè®“ä½ çš„å›žç”更難 +- é¿å…é ‚éƒ¨å›žè¦†ï¼ˆæŠŠä½ çš„ç”æ¡ˆæ”¾åœ¨ä½ è¦å›žå¾©çš„引文上é¢çš„åšæ³•ï¼‰ã€‚é€™æœƒè®“ä½ çš„å›žç”更難 ç†è§£ï¼Œå°è±¡ä¹Ÿå¾ˆå·®ã€‚ - 在æ£ç¢ºçš„郵件列表發å•ã€‚linux-kernel å¯èƒ½æ˜¯é€šç”¨çš„è¨Žè«–å ´æ‰€ï¼Œä½†å®ƒä¸æ˜¯å°‹æ‰¾æ‰€æœ‰ @@ -332,7 +332,7 @@ redhat.com/mailman/listinfo。 最後一點——找到æ£ç¢ºçš„郵件列表——是開發人員常出錯的地方。在linux-kernel上 æ出與網絡相關的å•é¡Œçš„人幾乎肯定會收到一個禮貌的建è°ï¼Œè½‰åˆ°netdev列表上æ出， å› çˆ²é€™æ˜¯å¤§å¤šæ•¸ç¶²çµ¡é–‹ç™¼äººå“¡ç¶“å¸¸å‡ºç¾çš„列表。還有其他列表å¯ç”¨æ–¼scsiã€video4linux〠-ideã€filesystemç‰å系統。查找郵件列表的最佳ä½ç½®æ˜¯èˆ‡å…§æ ¸åŽŸå§‹ç¢¼ä¸€èµ·æ‰“包的 +ideã€filesystemç‰å系統。查找郵件列表的最佳ä½ç½®æ˜¯èˆ‡å…§æ ¸æºä»£ç¢¼ä¸€èµ·æ‰“包的 MAINTAINERS文件。 é–‹å§‹å…§æ ¸é–‹ç™¼ @@ -344,7 +344,7 @@ MAINTAINERS文件。 å…¬å¸é€šå¸¸å¸Œæœ›è˜è«‹çŸ¥å的開發人員來啓動開發團隊。實際上，這是一種有效的技術。 但它也往往是昂貴的，而且å°å¢žåŠ æœ‰ç¶“é©—çš„å…§æ ¸é–‹ç™¼äººå“¡çš„æ•¸é‡æ²’有多大幫助。考 慮到時間投入，å¯ä»¥è®“å…§éƒ¨é–‹ç™¼äººå“¡åŠ å¿«Linuxå…§æ ¸çš„é–‹ç™¼é€Ÿåº¦ã€‚åˆ©ç”¨é€™æ®µæ™‚é–“å¯ä»¥ -讓僱主æ“æœ‰ä¸€æ‰¹æ—¢äº†è§£å…§æ ¸åˆäº†è§£å…¬å¸çš„開發人員，還å¯ä»¥å¹«åŠ©åŸ¹è¨“其他人。從ä¸æœŸ +讓僱主æ“有一批既çžè§£å…§æ ¸åˆçžè§£å…¬å¸çš„開發人員，還å¯ä»¥å¹«åŠ©åŸ¹è¨“其他人。從ä¸æœŸ 來看，這通常是更有利å¯åœ–的方法。 å¯ä»¥ç†è§£çš„是，單個開發人員往往å°èµ·æ¥æ„Ÿåˆ°èŒ«ç„¶ã€‚å¾žä¸€å€‹å¤§åž‹é …ç›®é–‹å§‹å¯èƒ½æœƒå¾ˆ @@ -353,17 +353,17 @@ MAINTAINERS文件。 這會分散整個開發社å€çš„注æ„åŠ›ï¼Œå› æ¤ï¼Œå®ƒå€‘越來越被人ä¸çœ‹é‡ã€‚希望å‘社å€ä»‹ç´¹ 自己的新開發人員將無法通éŽé€™äº›æ–¹å¼ç²å¾—他們期待的å響。 -Andrew Morton çˆ²æœ‰æŠ±è² çš„å…§æ ¸é–‹ç™¼äººå“¡æä¾›äº†å¦‚ä¸‹å»ºè° +Andrew Morton çˆ²æœ‰æŠ±è² çš„å…§æ ¸é–‹ç™¼äººå“¡æä¾›çžå¦‚ä¸‹å»ºè° :: - æ‰€æœ‰å…§æ ¸é–‹ç™¼è€…çš„ç¬¬ä¸€å€‹é …ç›®è‚¯å®šæ‡‰è©²æ˜¯ã€Œç¢ºä¿å…§æ ¸åœ¨æ‚¨å¯ä»¥æ“作的所有 - 機器上始終完美é‹è¡Œã€ã€‚通常的方法是和其他人一起解決å•é¡Œï¼ˆé€™å¯èƒ½éœ€ + æ‰€æœ‰å…§æ ¸é–‹ç™¼è€…çš„ç¬¬ä¸€å€‹é …ç›®è‚¯å®šæ‡‰è©²æ˜¯â€œç¢ºä¿å…§æ ¸åœ¨æ‚¨å¯ä»¥æ“作的所有 + 機器上始終完美é‹è¡Œâ€ã€‚通常的方法是和其他人一起解決å•é¡Œï¼ˆé€™å¯èƒ½éœ€ è¦å …æŒï¼ï¼‰ï¼Œä½†å°±æ˜¯å¦‚æ¤â€”â€”é€™æ˜¯å…§æ ¸é–‹ç™¼çš„ä¸€éƒ¨åˆ†ã€‚ (http://lwn.net/Articles/283982/) -在沒有明顯å•é¡Œéœ€è¦è§£æ±ºçš„情æ³ä¸‹ï¼Œé€šå¸¸å»ºè°é–‹ç™¼äººå“¡æŸ¥çœ‹ç•¶å‰çš„回æ¸å’Œé–‹æ”¾ç¼ºé™· +在沒有明顯å•é¡Œéœ€è¦è§£æ±ºçš„情æ³ä¸‹ï¼Œé€šå¸¸å»ºè°é–‹ç™¼äººå“¡æŸ¥çœ‹ç•¶å‰çš„è¿´æ¸å’Œé–‹æ”¾ç¼ºé™· 列表。從來都ä¸ç¼ºå°‘需è¦è§£æ±ºçš„å•é¡Œï¼›é€šéŽè§£æ±ºé€™äº›å•é¡Œï¼Œé–‹ç™¼äººå“¡å°‡å¾žè©²éŽç¨‹ç²å¾— 經驗，åŒæ™‚與開發社å€çš„其他æˆå“¡å»ºç«‹ç›¸äº’å°Šé‡ã€‚ diff --git a/Documentation/translations/zh_TW/process/3.Early-stage.rst b/Documentation/translations/zh_TW/process/3.Early-stage.rst index 636e506fd196..a6959e6350f4 100644 --- a/Documentation/translations/zh_TW/process/3.Early-stage.rst +++ b/Documentation/translations/zh_TW/process/3.Early-stage.rst @@ -26,13 +26,13 @@ -------- èˆ‡ä»»ä½•å·¥ç¨‹é …ç›®ä¸€æ¨£ï¼ŒæˆåŠŸçš„å…§æ ¸æ”¹å–„å¾žæ¸…æ™°æè¿°è¦è§£æ±ºçš„å•é¡Œé–‹å§‹ã€‚在æŸäº›æƒ…æ³ -下，這個æ¥é©Ÿå¾ˆå®¹æ˜“：例如當æŸå€‹ç‰¹å®šç¡¬é«”需è¦é©…動程åºæ™‚。ä¸éŽï¼Œåœ¨å…¶ä»–情æ³ä¸‹ï¼Œ +下，這個æ¥é©Ÿå¾ˆå®¹æ˜“：例如當æŸå€‹ç‰¹å®šç¡¬ä»¶éœ€è¦é©…動程åºæ™‚。ä¸éŽï¼Œåœ¨å…¶ä»–情æ³ä¸‹ï¼Œ 很容易將實際å•é¡Œèˆ‡å»ºè°çš„解決方案混在一起，這å¯èƒ½æœƒå°Žè‡´éº»ç…©ã€‚ -舉個例å：幾年å‰ï¼ŒLinuxéŸ³é »çš„é–‹ç™¼äººå“¡å°‹æ±‚ä¸€ç¨®æ–¹æ³•ä¾†é‹è¡Œæ‡‰ç”¨ç¨‹å¼ï¼Œè€Œä¸æœƒå› +舉個例å：幾年å‰ï¼ŒLinuxéŸ³é »çš„é–‹ç™¼äººå“¡å°‹æ±‚ä¸€ç¨®æ–¹æ³•ä¾†é‹è¡Œæ‡‰ç”¨ç¨‹åºï¼Œè€Œä¸æœƒå› 系統延é²éŽå¤§è€Œå°Žè‡´é€€å‡ºæˆ–其他å•é¡Œã€‚他們得到的解決方案是一個連接到Linux安全 -模塊（LSM）框架ä¸çš„å…§æ ¸æ¨¡å¡Šï¼›é€™å€‹æ¨¡å¡Šå¯ä»¥é…置爲å…許特定的應用程å¼è¨ªå•å¯¦æ™‚ -調度程åºã€‚這個模塊被實ç¾ä¸¦ç™¼åˆ°linux-kernel郵件列表，在那裡它立å³é‡åˆ°äº†éº»ç…©ã€‚ +模塊（LSM）框架ä¸çš„å…§æ ¸æ¨¡å¡Šï¼›é€™å€‹æ¨¡å¡Šå¯ä»¥é…置爲å…許特定的應用程åºè¨ªå•å¯¦æ™‚ +調度程åºã€‚這個模塊被實ç¾ä½µç™¼åˆ°linux-kernel郵件列表，在那è£å®ƒç«‹å³é‡åˆ°äº†éº»ç…©ã€‚ å°æ–¼éŸ³é »é–‹ç™¼äººå“¡ä¾†èªªï¼Œé€™å€‹å®‰å…¨æ¨¡å¡Šè¶³ä»¥è§£æ±ºä»–們當å‰çš„å•é¡Œã€‚但是，å°æ–¼æ›´å»£æ³›çš„ å…§æ ¸ç¤¾å€ä¾†èªªï¼Œé€™è¢«è¦–爲å°LSM框架的濫用（LSM框架並ä¸æ‰“算授予他們原本ä¸å…·å‚™çš„ @@ -41,15 +41,15 @@ ç„¶è€Œï¼ŒéŸ³é »ç¤¾å€ç„¡æ³•è¶…越他們實施的特定解決方案來看å•é¡Œï¼›ä»–們ä¸é¡˜æ„接å—替代方案。 ç”±æ¤ç”¢ç”Ÿçš„分æ§ä½¿é€™äº›é–‹ç™¼äººå“¡å°æ•´å€‹å…§æ ¸é–‹ç™¼éŽç¨‹æ„Ÿåˆ°å¤±æœ›ï¼›å…¶ä¸ä¸€å€‹é–‹ç™¼äººå“¡è¿”回 -到audio列表並發布了以下內容： +到audio列表併發布了以下內容： 有很多éžå¸¸å¥½çš„Linuxå…§æ ¸é–‹ç™¼äººå“¡ï¼Œä½†ä»–å€‘å¾€å¾€æœƒè¢«ä¸€ç¾£å‚²æ…¢çš„å‚»ç“œæ‰€å£“å€’ã€‚ - 試圖å‘這些人傳é”用戶需求是浪費時間。他們太「è°æ˜Žã€äº†ï¼Œæ ¹æœ¬è½ä¸åˆ°å°‘數 + 試圖å‘這些人傳é”用戶需求是浪費時間。他們太“è°æ˜Žâ€äº†ï¼Œæ ¹æœ¬è½ä¸åˆ°å°‘數 人的話。 （http://lwn.net/Articles/131776/） -實際情æ³å»æ˜¯ä¸åŒçš„ï¼›èˆ‡ç‰¹å®šæ¨¡å¡Šç›¸æ¯”ï¼Œå…§æ ¸é–‹ç™¼äººå“¡æ›´é—œå¿ƒç³»çµ±ç©©å®šæ€§ã€é•·æœŸç¶è· +實際情æ³å»æ˜¯ä¸åŒçš„ï¼›èˆ‡ç‰¹å®šæ¨¡å¡Šç›¸æ¯”ï¼Œå…§æ ¸é–‹ç™¼äººå“¡æ›´é—œå¿ƒç¹«çµ±ç©©å®šæ€§ã€é•·æœŸç¶è· 以åŠæ‰¾åˆ°å•é¡Œçš„æ£ç¢ºè§£æ±ºæ–¹æ¡ˆã€‚這個故事的寓æ„是把é‡é»žæ”¾åœ¨å•é¡Œä¸Šâ€”—而ä¸æ˜¯å…·é«”çš„ 解決方案上——並在開始編寫代碼之å‰èˆ‡é–‹ç™¼ç¤¾å€è¨Žè«–這個å•é¡Œã€‚ @@ -72,7 +72,7 @@ - 很å¯èƒ½å•é¡Œæ˜¯ç”±å…§æ ¸ä»¥æ‚¨ä¸ç†è§£çš„æ–¹å¼è§£æ±ºçš„。Linuxå…§æ ¸å¾ˆå¤§ï¼Œå…·æœ‰è¨±å¤šä¸æ˜Žé¡¯ 的特性和功能。並ä¸æ˜¯æ‰€æœ‰çš„å…§æ ¸åŠŸèƒ½éƒ½åƒäººå€‘所希望的那樣有文檔記錄，而且很 - 容易éºæ¼ä¸€äº›æ±è¥¿ã€‚æŸä½œè€…發布了一個完整的驅動程åºï¼Œé‡è¤‡äº†ä¸€å€‹å…¶ä¸ + 容易éºæ¼ä¸€äº›æ±è¥¿ã€‚æŸä½œè€…發佈了一個完整的驅動程åºï¼Œé‡è¤‡äº†ä¸€å€‹å…¶ä¸ 知é“çš„ç¾æœ‰é©…動程åºã€‚é‡æ–°ç™¼æ˜Žç¾æœ‰è¼ªå的代碼ä¸åƒ…浪費，而且ä¸æœƒè¢«æŽ¥å—到主線 å…§æ ¸ä¸ã€‚ @@ -83,7 +83,7 @@ å¯èƒ½é¡˜æ„幫助創建這個解決方案。 åœ¨å…§æ ¸é–‹ç™¼ç¤¾å€çš„多年經驗給了我們一個明確的教訓：閉門è¨è¨ˆå’Œé–‹ç™¼çš„å…§æ ¸ä»£ç¢¼ç¸½æ˜¯ -有一些å•é¡Œï¼Œé€™äº›å•é¡Œåªæœ‰åœ¨ä»£ç¢¼ç™¼å¸ƒåˆ°ç¤¾å€ä¸æ™‚æ‰æœƒè¢«ç™¼ç¾ã€‚有時這些å•é¡Œå¾ˆåš´é‡ï¼Œ +有一些å•é¡Œï¼Œé€™äº›å•é¡Œåªæœ‰åœ¨ä»£ç¢¼ç™¼ä½ˆåˆ°ç¤¾å€ä¸æ™‚纔會被發ç¾ã€‚有時這些å•é¡Œå¾ˆåš´é‡ï¼Œ 需è¦æ•¸æœˆæˆ–數年的努力æ‰èƒ½ä½¿ä»£ç¢¼é”åˆ°å…§æ ¸ç¤¾å€çš„標準。例如： - è¨è¨ˆä¸¦å¯¦ç¾äº†å–®è™•ç†å™¨ç³»çµ±çš„DeviceScape網絡棧。åªæœ‰ä½¿å…¶é©åˆæ–¼å¤šè™•ç†å™¨ç³»çµ±ï¼Œ @@ -103,16 +103,16 @@ 找誰交æµï¼Ÿ ---------- -當開發人員決定公開他們的計劃時，下一個å•é¡Œæ˜¯ï¼šæˆ‘們從哪裡開始？ç”案是找到æ£ç¢º +當開發人員決定公開他們的計劃時，下一個å•é¡Œæ˜¯ï¼šæˆ‘們從哪è£é–‹å§‹ï¼Ÿç”案是找到æ£ç¢º 的郵件列表和æ£ç¢ºçš„ç¶è·è€…。å°æ–¼éƒµä»¶åˆ—表，最好的方法是在ç¶è·è€…(MAINTAINERS)文件 -ä¸æŸ¥æ‰¾è¦ç™¼å¸ƒçš„相關ä½ç½®ã€‚如果有一個åˆé©çš„å系統列表，那麼其上發布通常比在 -linux-kernel上發布更å¯å–；您更有å¯èƒ½æŽ¥è§¸åˆ°åœ¨ç›¸é—œå系統ä¸å…·æœ‰å°ˆæ¥çŸ¥è˜çš„開發 +ä¸æŸ¥æ‰¾è¦ç™¼ä½ˆçš„相關ä½ç½®ã€‚如果有一個åˆé©çš„å系統列表，那麼其上發佈通常比在 +linux-kernel上發佈更å¯å–；您更有å¯èƒ½æŽ¥è§¸åˆ°åœ¨ç›¸é—œå系統ä¸å…·æœ‰å°ˆæ¥çŸ¥è˜çš„開發 人員，並且環境å¯èƒ½å…·æ”¯æŒæ€§ã€‚ 找到ç¶è·äººå“¡å¯èƒ½æœƒæœ‰é»žå›°é›£ã€‚åŒæ¨£ï¼Œç¶è·è€…æ–‡ä»¶æ˜¯é–‹å§‹çš„åœ°æ–¹ã€‚ä½†æ˜¯ï¼Œè©²æ–‡ä»¶å¾€å¾€ä¸ -是最新的，並且並éžæ‰€æœ‰å系統都在那裡顯示。實際上，ç¶è·è€…文件ä¸åˆ—出的人員å¯èƒ½ +是最新的，並且並éžæ‰€æœ‰å系統都在那è£é¡¯ç¤ºã€‚實際上，ç¶è·è€…文件ä¸åˆ—出的人員å¯èƒ½ ä¸æ˜¯ç•¶å‰å¯¦éš›æ“”ä»»è©²è§’è‰²çš„äººå“¡ã€‚å› æ¤ï¼Œç•¶å°è¯ç¹«èª°æœ‰ç–‘å•æ™‚，一個有用的技巧是使用 -git（尤其是「git-logã€ï¼‰æŸ¥çœ‹æ„Ÿèˆˆè¶£çš„å系統ä¸ç•¶å‰æ´»å‹•çš„用戶。看看誰在寫補ä¸ã€ +git（尤其是“git-logâ€ï¼‰æŸ¥çœ‹æ„Ÿèˆˆè¶£çš„å系統ä¸ç•¶å‰æ´»å‹•çš„用戶。看看誰在寫補ä¸ã€ 誰會在這些補ä¸ä¸ŠåŠ 上Signed-off-by行簽åï¼ˆå¦‚æœ‰ï¼‰ã€‚é€™äº›äººå°‡æ˜¯å¹«åŠ©æ–°é–‹ç™¼é …ç›®çš„ 最佳人é¸ã€‚ @@ -123,7 +123,7 @@ git（尤其是「git-logã€ï¼‰æŸ¥çœ‹æ„Ÿèˆˆè¶£çš„å系統ä¸ç•¶å‰æ´»å‹•çš„用æ .../scripts/get_maintainer.pl -當給定「-fã€é¸é …時，æ¤è…³æœ¬å°‡è¿”回指定文件或目錄的當å‰ç¶è·è€…。如果在命令行上 +當給定“-fâ€é¸é …時，æ¤è…³æœ¬å°‡è¿”回指定文件或目錄的當å‰ç¶è·è€…。如果在命令行上 給出了一個補ä¸ï¼Œå®ƒå°‡åˆ—出å¯èƒ½æŽ¥æ”¶è£œä¸å‰¯æœ¬çš„ç¶è·äººå“¡ã€‚有許多é¸é …å¯ä»¥èª¿ç¯€ get_maintainer.plæœç´¢ç¶è·è€…çš„åš´æ ¼ç¨‹åº¦ï¼›è«‹å°å¿ƒä½¿ç”¨æ›´æ¿€é€²çš„é¸é …ï¼Œå› çˆ²æœ€çµ‚çµæžœ å¯èƒ½æœƒåŒ…括å°æ‚¨æ£åœ¨ä¿®æ”¹çš„代碼沒有真æ£èˆˆè¶£çš„開發人員。 @@ -134,17 +134,17 @@ get_maintainer.plæœç´¢ç¶è·è€…çš„åš´æ ¼ç¨‹åº¦ï¼›è«‹å°å¿ƒä½¿ç”¨æ›´æ¿€é€²çš„é¸ ä½•æ™‚éƒµå¯„ï¼Ÿ ---------- -如果å¯èƒ½çš„è©±ï¼Œåœ¨æ—©æœŸéšŽæ®µç™¼å¸ƒä½ çš„è¨ˆåŠƒåªæœƒæ›´æœ‰å¹«åŠ©ã€‚æè¿°æ£åœ¨è§£æ±ºçš„å•é¡Œä»¥åŠå·²ç¶“ +如果å¯èƒ½çš„è©±ï¼Œåœ¨æ—©æœŸéšŽæ®µç™¼ä½ˆä½ çš„è¨ˆåŠƒåªæœƒæ›´æœ‰å¹«åŠ©ã€‚æè¿°æ£åœ¨è§£æ±ºçš„å•é¡Œä»¥åŠå·²ç¶“ 制定的關於如何實施的任何計劃。您å¯ä»¥æ供的任何信æ¯éƒ½å¯ä»¥å¹«åŠ©é–‹ç™¼ç¤¾å€çˆ²é …ç›® æ供有用的輸入。 在這個階段å¯èƒ½ç™¼ç”Ÿçš„一件令人沮喪的事情ä¸æ˜¯å¾—到åå°æ„è¦‹ï¼Œè€Œæ˜¯å¾ˆå°‘æˆ–æ ¹æœ¬æ²’æœ‰ å饋。令人傷心的事實是：（1ï¼‰å…§æ ¸é–‹ç™¼äººå“¡å¾€å¾€å¾ˆå¿™ï¼›ï¼ˆ2）ä¸ç¼ºå°‘有å®å‰è¨ˆåŠƒä½† 代碼（甚至代碼è¨æƒ³ï¼‰å¾ˆå°‘的人去支æŒä»–們；（3）沒有人有義務審查或評論別人發表 -的想法。除æ¤ä¹‹å¤–，高層級的è¨è¨ˆå¸¸å¸¸éš±è—著一些å•é¡Œï¼Œé€™äº›å•é¡Œåªæœ‰åœ¨æœ‰äººçœŸæ£å˜—試 -實ç¾é€™äº›è¨è¨ˆæ™‚æ‰æœƒè¢«ç™¼ç¾ï¼›å› æ¤ï¼Œå…§æ ¸é–‹ç™¼äººå“¡å¯§é¡˜çœ‹åˆ°ä»£ç¢¼ã€‚ +的想法。除æ¤ä¹‹å¤–，高層級的è¨è¨ˆå¸¸å¸¸éš±è—ç€ä¸€äº›å•é¡Œï¼Œé€™äº›å•é¡Œåªæœ‰åœ¨æœ‰äººçœŸæ£å˜—試 +實ç¾é€™äº›è¨è¨ˆæ™‚纔會被發ç¾ï¼›å› æ¤ï¼Œå…§æ ¸é–‹ç™¼äººå“¡å¯§é¡˜çœ‹åˆ°ä»£ç¢¼ã€‚ -如果發布請求評論（RFC）並沒得到什麼有用的評論，ä¸è¦ä»¥çˆ²é€™æ„味著無人å°æ¤é …ç›® +如果發佈請求評論（RFC）並沒得到什麼有用的評論，ä¸è¦ä»¥çˆ²é€™æ„味ç€ç„¡äººå°æ¤é …ç›® 有興趣，åŒæ™‚ä½ ä¹Ÿä¸èƒ½å‡è¨ä½ 的想法沒有å•é¡Œã€‚在這種情æ³ä¸‹ï¼Œæœ€å¥½çš„åšæ³•æ˜¯ç¹¼çºŒé€² è¡Œï¼ŒæŠŠä½ çš„é€²å±•éš¨æ™‚é€šçŸ¥ç¤¾å€ã€‚ @@ -152,12 +152,12 @@ get_maintainer.plæœç´¢ç¶è·è€…çš„åš´æ ¼ç¨‹åº¦ï¼›è«‹å°å¿ƒä½¿ç”¨æ›´æ¿€é€²çš„é¸ ----------------------- 如果您的工作是在公å¸ç’°å¢ƒä¸å®Œæˆçš„，就åƒå¤§å¤šæ•¸Linuxå…§æ ¸å·¥ä½œä¸€æ¨£ï¼›é¡¯ç„¶ï¼Œåœ¨æ‚¨å°‡ -å…¬å¸çš„計劃或代碼發布到公共郵件列表之å‰ï¼Œå¿…é ˆç²å¾—有é©ç•¶æ¬Šåˆ©ç¶“ç†çš„許å¯ã€‚發布 -ä¸ç¢ºå®šæ˜¯å¦å…¼å®¹GPL的代碼尤其會帶來å•é¡Œï¼›å…¬å¸çš„管ç†å±¤å’Œæ³•å¾‹äººå“¡è¶Šæ—©èƒ½å¤ 就發布 +å…¬å¸çš„計劃或代碼發佈到公共郵件列表之å‰ï¼Œå¿…é ˆç²å¾—有é©ç•¶æ¬Šåˆ©ç¶“ç†çš„許å¯ã€‚發佈 +ä¸ç¢ºå®šæ˜¯å¦å…¼å®¹GPL的代碼尤其會帶來å•é¡Œï¼›å…¬å¸çš„管ç†å±¤å’Œæ³•å¾‹äººå“¡è¶Šæ—©èƒ½å¤ 就發佈 å…§æ ¸é–‹ç™¼é …ç›®é”æˆä¸€è‡´ï¼Œå°åƒèˆ‡çš„æ¯å€‹äººéƒ½è¶Šå¥½ã€‚ 一些讀者å¯èƒ½æœƒèªçˆ²ä»–å€‘çš„æ ¸å¿ƒå·¥ä½œæ˜¯çˆ²äº†æ”¯æŒé‚„沒有æ£å¼æ‰¿èªå˜åœ¨çš„產å“。將僱主 -的計劃公布在公共郵件列表上å¯èƒ½ä¸æ˜¯ä¸€å€‹å¯è¡Œçš„é¸æ“‡ã€‚在這種情æ³ä¸‹ï¼Œæœ‰å¿…è¦è€ƒæ…® +的計劃公佈在公共郵件列表上å¯èƒ½ä¸æ˜¯ä¸€å€‹å¯è¡Œçš„é¸æ“‡ã€‚在這種情æ³ä¸‹ï¼Œæœ‰å¿…è¦è€ƒæ…® ä¿å¯†æ˜¯å¦çœŸçš„是必è¦çš„；通常ä¸éœ€è¦æŠŠé–‹ç™¼è¨ˆåŠƒé—œåœ¨é–€å…§ã€‚ 的確，有些情æ³ä¸‹ä¸€å®¶å…¬å¸åœ¨é–‹ç™¼éŽç¨‹çš„早期無法åˆæ³•åœ°æŠ«éœ²å…¶è¨ˆåŠƒã€‚æ“有經驗è±å¯Œ diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index adb5339aab6a..7a4e01eabd81 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -19,7 +19,7 @@ ====================== é›–ç„¶ä¸€å€‹å …å¯¦çš„ã€é¢å‘社å€çš„è¨è¨ˆéŽç¨‹æœ‰å¾ˆå¤šå€¼å¾—說é“çš„ï¼Œä½†æ˜¯ä»»ä½•å…§æ ¸é–‹ç™¼é …ç›®å·¥ä½œ -çš„è‰æ˜Žéƒ½åæ˜ åœ¨ä»£ç¢¼ä¸ã€‚它是將由其他開發人員檢查併åˆä¸¦ï¼ˆæˆ–ä¸åˆä½µï¼‰åˆ°ä¸»ç·šæ¨¹ä¸ +çš„è‰æ˜Žéƒ½åæ˜ åœ¨ä»£ç¢¼ä¸ã€‚它是將由其他開發人員檢查併åˆä¸¦ï¼ˆæˆ–ä¸åˆä¸¦ï¼‰åˆ°ä¸»ç·šæ¨¹ä¸ 的代碼。所以這段代碼的質é‡æ±ºå®šäº†é …目的最終æˆåŠŸã€‚ 本節將檢查編碼éŽç¨‹ã€‚æˆ‘å€‘å°‡å¾žå…§æ ¸é–‹ç™¼äººå“¡å¸¸çŠ¯çš„å¹¾ç¨®éŒ¯èª¤é–‹å§‹ã€‚ç„¶å¾Œé‡é»žå°‡è½‰ç§» @@ -32,7 +32,7 @@ ******** å…§æ ¸é•·æœŸä»¥ä¾†éƒ½æœ‰å…¶æ¨™æº–çš„ä»£ç¢¼é¢¨æ ¼ï¼Œå¦‚ -:ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` +:ref:`Documentation/translations/zh_CN/process/coding-style.rst <tw_codingstyle>` ä¸æ‰€è¿°ã€‚在多數時候，該文檔ä¸æ述的準則至多被èªçˆ²æ˜¯å»ºè°æ€§çš„ã€‚å› æ¤ï¼Œå…§æ ¸ä¸å˜åœ¨ 大é‡ä¸ç¬¦åˆä»£ç¢¼é¢¨æ ¼æº–則的代碼。這種代碼的å˜åœ¨æœƒçµ¦å…§æ ¸é–‹ç™¼äººå“¡å¸¶ä¾†å…©æ–¹é¢çš„å±å®³ã€‚ @@ -42,7 +42,7 @@ é–‹ç™¼äººå“¡èƒ½å¤ å¿«é€Ÿç†è§£å…¶ä¸çš„任何部分。所以å†ä¹Ÿç¶“ä¸èµ·å¥‡æ€ªæ ¼å¼çš„代碼的折騰了。 å…§æ ¸çš„ä»£ç¢¼é¢¨æ ¼å¶çˆ¾æœƒèˆ‡åƒ±ä¸»çš„å¼·åˆ¶é¢¨æ ¼ç™¼ç”Ÿè¡çªã€‚在這種情æ³ä¸‹ï¼Œå¿…é ˆåœ¨ä»£ç¢¼åˆä½µ -之å‰éµå¾žå…§æ ¸ä»£ç¢¼é¢¨æ ¼ã€‚å°‡ä»£ç¢¼æ”¾å…¥å…§æ ¸æ„味著以多種方å¼æ”¾æ£„一定程度的控制權—— +之å‰éµå¾žå…§æ ¸ä»£ç¢¼é¢¨æ ¼ã€‚å°‡ä»£ç¢¼æ”¾å…¥å…§æ ¸æ„味ç€ä»¥å¤šç¨®æ–¹å¼æ”¾æ£„一定程度的控制權—— 包括控制代碼樣å¼ã€‚ å¦ä¸€å€‹å±å®³æ˜¯èªçˆ²å·²ç¶“åœ¨å…§æ ¸ä¸çš„代碼迫切需è¦ä¿®å¾©ä»£ç¢¼æ¨£å¼ã€‚開發者å¯èƒ½æœƒé–‹å§‹ç·¨å¯« @@ -70,21 +70,21 @@ 簡單點，先考慮一個調用時始終åªæœ‰ä¸€å€‹åƒæ•¸ä¸”總爲零的函數。我們å¯ä»¥ä¿ç•™é€™å€‹åƒæ•¸ï¼Œ 以在需è¦ä½¿ç”¨å®ƒæ™‚æ供的é¡å¤–éˆæ´»æ€§ã€‚ä¸éŽï¼Œåœ¨é‚£æ™‚實ç¾äº†é€™å€‹é¡å¤–åƒæ•¸çš„代碼很有 å¯èƒ½ä»¥æŸç¨®å¾žæœªè¢«æ³¨æ„到的微妙方å¼è¢«ç ´å£žâ€”â€”å› çˆ²å®ƒå¾žæœªè¢«ä½¿ç”¨éŽã€‚或者當需è¦é¡å¤– -çš„éˆæ´»æ€§æ™‚，它並未以符åˆç¨‹å¼è¨è¨ˆå¸«ç•¶åˆæœŸæœ›çš„æ–¹å¼ä¾†å¯¦ç¾ã€‚å…§æ ¸é–‹ç™¼äººå“¡é€šå¸¸æœƒæ交 +çš„éˆæ´»æ€§æ™‚，它並未以符åˆç¨‹åºå“¡ç•¶åˆæœŸæœ›çš„æ–¹å¼ä¾†å¯¦ç¾ã€‚å…§æ ¸é–‹ç™¼äººå“¡é€šå¸¸æœƒæ交 補ä¸ä¾†åˆªé™¤æœªä½¿ç”¨çš„åƒæ•¸ï¼›ä¸€èˆ¬ä¾†èªªï¼Œä¸€é–‹å§‹å°±ä¸æ‡‰è©²æ·»åŠ 這些åƒæ•¸ã€‚ -éš±è—硬體訪å•çš„抽象層——通常爲了å…許大é‡çš„驅動程åºå…¼å®¹å¤šå€‹ä½œæ¥ç³»çµ±â€”—尤其ä¸å— +éš±è—硬件訪å•çš„抽象層——通常爲了å…許大é‡çš„驅動程åºå…¼å®¹å¤šå€‹æ“作系統——尤其ä¸å— æ¡è¿Žã€‚這樣的層使代碼變得模糊，å¯èƒ½æœƒé€ æˆæ€§èƒ½æ失；它們ä¸å±¬æ–¼Linuxå…§æ ¸ã€‚ å¦ä¸€æ–¹é¢ï¼Œå¦‚果您發ç¾è‡ªå·±å¾žå¦ä¸€å€‹å…§æ ¸å系統複製了大é‡çš„代碼，那麼是時候 -了解一下：是å¦éœ€è¦å°‡é€™äº›ä»£ç¢¼ä¸çš„部分æå–到單ç¨çš„庫ä¸ï¼Œæˆ–者在更高的層次上 +çžè§£ä¸€ä¸‹ï¼šæ˜¯å¦éœ€è¦å°‡é€™äº›ä»£ç¢¼ä¸çš„部分æå–到單ç¨çš„庫ä¸ï¼Œæˆ–者在更高的層次上 實ç¾é€™äº›åŠŸèƒ½ã€‚åœ¨æ•´å€‹å…§æ ¸ä¸è¤‡è£½ç›¸åŒçš„代碼沒有價值。 #ifdef å’Œé è™•ç† *************** -Cé 處ç†å™¨ä¼¼ä¹Žçµ¦ä¸€äº›C程å¼è¨è¨ˆå¸«å¸¶ä¾†äº†å¼·å¤§çš„誘惑，他們èªçˆ²å®ƒæ˜¯ä¸€ç¨®å°‡å¤§é‡éˆæ´»æ€§åŠ å…¥ -原始碼ä¸çš„方法。但是é 處ç†å™¨ä¸æ˜¯C，大é‡ä½¿ç”¨å®ƒæœƒå°Žè‡´ä»£ç¢¼å°å…¶ä»–人來說更難閱讀， +Cé 處ç†å™¨ä¼¼ä¹Žçµ¦ä¸€äº›C程åºå“¡å¸¶ä¾†äº†å¼·å¤§çš„誘惑，他們èªçˆ²å®ƒæ˜¯ä¸€ç¨®å°‡å¤§é‡éˆæ´»æ€§åŠ å…¥ +æºä»£ç¢¼ä¸çš„方法。但是é 處ç†å™¨ä¸æ˜¯C，大é‡ä½¿ç”¨å®ƒæœƒå°Žè‡´ä»£ç¢¼å°å…¶ä»–人來說更難閱讀， å°ç·¨è¯å™¨ä¾†èªªæ›´é›£æª¢æŸ¥æ£ç¢ºæ€§ã€‚使用了大é‡é 處ç†å™¨å¹¾ä¹Žç¸½æ˜¯ä»£ç¢¼éœ€è¦ä¸€äº› 清ç†å·¥ä½œçš„標誌。 @@ -100,23 +100,23 @@ Cé 處ç†å™¨å®å˜åœ¨è¨±å¤šå±éšªæ€§ï¼ŒåŒ…括å¯èƒ½å°å…·æœ‰å‰¯ä½œç”¨ä¸”沒有é å…§è¯å‡½æ•¸ ******** -ä¸éŽï¼Œå…§è¯å‡½æ•¸æœ¬èº«ä¹Ÿå˜åœ¨é¢¨éšªã€‚程å¼è¨è¨ˆå¸«å¯ä»¥å‚¾å¿ƒæ–¼é¿å…函數調用和用內è¯å‡½æ•¸å¡«å……æº +ä¸éŽï¼Œå…§è¯å‡½æ•¸æœ¬èº«ä¹Ÿå˜åœ¨é¢¨éšªã€‚程åºå“¡å¯ä»¥å‚¾å¿ƒæ–¼é¿å…函數調用和用內è¯å‡½æ•¸å¡«å……æº æ–‡ä»¶æ‰€å›ºæœ‰çš„æ•ˆçŽ‡ã€‚ç„¶è€Œï¼Œé€™äº›åŠŸèƒ½å¯¦éš›ä¸Šæœƒé™ä½Žæ€§èƒ½ã€‚å› çˆ²å®ƒå€‘çš„ä»£ç¢¼åœ¨æ¯å€‹èª¿ç”¨ç«™ -點都被複製一éï¼Œæ‰€ä»¥æœ€çµ‚æœƒå¢žåŠ ç·¨è¯å…§æ ¸çš„大å°ã€‚æ¤å¤–，這也å°è™•ç†å™¨çš„å…§å˜ç·©å˜ +點都被複制一éï¼Œæ‰€ä»¥æœ€çµ‚æœƒå¢žåŠ ç·¨è¯å…§æ ¸çš„大å°ã€‚æ¤å¤–，這也å°è™•ç†å™¨çš„å…§å˜ç·©å˜ é€ æˆå£“力，從而大大é™ä½ŽåŸ·è¡Œé€Ÿåº¦ã€‚通常內è¯å‡½æ•¸æ‡‰è©²éžå¸¸å°ï¼Œè€Œä¸”相å°è¼ƒå°‘。畢竟 函數調用的æˆæœ¬ä¸¦ä¸é«˜ï¼›å¤§é‡å‰µå»ºå…§è¯å‡½æ•¸æ˜¯éŽæ—©å„ªåŒ–的典型例å。 -ä¸€èˆ¬ä¾†èªªï¼Œå…§æ ¸ç¨‹å¼è¨è¨ˆå¸«æœƒè‡ªå†’風險忽略緩å˜æ•ˆæžœã€‚在數據çµæ§‹èª²ç¨‹é–‹é ä¸çš„經典 -時間/空間權衡通常ä¸é©ç”¨æ–¼ç•¶ä»£ç¡¬é«”。空間 *就是* æ™‚é–“ï¼Œå› çˆ²ä¸€å€‹å¤§çš„ç¨‹åºæ¯”一個 +ä¸€èˆ¬ä¾†èªªï¼Œå…§æ ¸ç¨‹åºå“¡æœƒè‡ªå†’風險忽略緩å˜æ•ˆæžœã€‚在數據çµæ§‹èª²ç¨‹é–‹é ä¸çš„經典 +時間/空間權衡通常ä¸é©ç”¨æ–¼ç•¶ä»£ç¡¬ä»¶ã€‚空間 *就是* æ™‚é–“ï¼Œå› çˆ²ä¸€å€‹å¤§çš„ç¨‹åºæ¯”一個 更緊湊的程åºé‹è¡Œå¾—慢。 較新的編è¯å™¨è¶Šä¾†è¶Šæ¿€é€²åœ°æ±ºå®šä¸€å€‹çµ¦å®šå‡½æ•¸æ˜¯å¦æ‡‰è©²å…§è¯ã€‚å› æ¤ï¼Œéš¨æ„放置使用 -「inlineã€é—œéµå—å¯èƒ½ä¸åƒ…僅是éŽåº¦çš„，也å¯èƒ½æ˜¯ç„¡ç”¨çš„。 +“inlineâ€é—œéµå—å¯èƒ½ä¸åƒ…僅是éŽåº¦çš„，也å¯èƒ½æ˜¯ç„¡ç”¨çš„。 鎖 ** -2006å¹´5月，「deviceescapeã€ç¶²çµ¡å †æ£§åœ¨å‰å‘¼å¾Œæ“下以GPL發布，並被ç´å…¥ä¸»ç·šå…§æ ¸ã€‚ +2006å¹´5月，“deviceescapeâ€ç¶²çµ¡å †æ£§åœ¨å‰å‘¼å¾Œæ“下以GPL發佈，並被ç´å…¥ä¸»ç·šå…§æ ¸ã€‚ 這是一個å—æ¡è¿Žçš„消æ¯ï¼›Linuxä¸å°ç„¡ç·šç¶²çµ¡çš„支æŒå……å…¶é‡è¢«èªçˆ²æ˜¯ä¸åˆæ ¼çš„，而 Deviceescapeå †æ£§æ‰¿è«¾ä¿®å¾©é€™ç¨®æƒ…æ³ã€‚然而直到2007å¹´6月（2.6.22），這段代碼æ‰çœŸ æ£é€²å…¥ä¸»ç·šã€‚發生了什麼？ @@ -125,25 +125,25 @@ Deviceescapeå †æ£§æ‰¿è«¾ä¿®å¾©é€™ç¨®æƒ…æ³ã€‚然而直到2007å¹´6月（2.6.22） è¨è¨ˆã€‚在åˆä½µé€™å€‹ç¶²çµ¡å †æ£§ï¼ˆç¾åœ¨ç¨±çˆ²mac80211）之å‰ï¼Œéœ€è¦å°å…¶é€²è¡Œä¸€å€‹éŽ–方案的 æ”¹é€ ã€‚ -曾經，Linuxå…§æ ¸ä»£ç¢¼å¯ä»¥åœ¨ä¸è€ƒæ…®å¤šè™•ç†å™¨ç³»çµ±æ‰€å¸¶ä¾†çš„並發性å•é¡Œçš„情æ³ä¸‹é€²è¡Œ +曾經，Linuxå…§æ ¸ä»£ç¢¼å¯ä»¥åœ¨ä¸è€ƒæ…®å¤šè™•ç†å™¨ç³»çµ±æ‰€å¸¶ä¾†çš„併發性å•é¡Œçš„情æ³ä¸‹é€²è¡Œ 開發。然而ç¾åœ¨ï¼Œé€™å€‹æ–‡æª”å°±æ˜¯åœ¨é›™æ ¸ç†è¨˜æœ¬é›»è…¦ä¸Šå¯«çš„。å³ä½¿åœ¨å–®è™•ç†å™¨ç³»çµ±ä¸Šï¼Œ -爲æ高響應能力所åšçš„工作也會æé«˜å…§æ ¸å…§çš„ä¸¦ç™¼æ€§æ°´å¹³ã€‚ç·¨å¯«å…§æ ¸ä»£ç¢¼è€Œä¸è€ƒæ…®éŽ– +爲æ高響應能力所åšçš„工作也會æé«˜å…§æ ¸å…§çš„ä½µç™¼æ€§æ°´å¹³ã€‚ç·¨å¯«å…§æ ¸ä»£ç¢¼è€Œä¸è€ƒæ…®éŽ– çš„æ—¥åæ—©å·²é 去。 -å¯ä»¥ç”±å¤šå€‹ç·šç¨‹ä¸¦ç™¼è¨ªå•çš„任何資æºï¼ˆæ•¸æ“šçµæ§‹ã€ç¡¬é«”寄å˜å™¨ç‰ï¼‰å¿…é ˆç”±éŽ–ä¿è·ã€‚æ–° +å¯ä»¥ç”±å¤šå€‹ç·šç¨‹ä½µç™¼è¨ªå•çš„任何資æºï¼ˆæ•¸æ“šçµæ§‹ã€ç¡¬ä»¶å¯„å˜å™¨ç‰ï¼‰å¿…é ˆç”±éŽ–ä¿è·ã€‚æ–° 的代碼應該謹記這一è¦æ±‚ï¼›äº‹å¾Œä¿®æ”¹éŽ–æ˜¯ä¸€é …ç›¸ç•¶å›°é›£çš„ä»»å‹™ã€‚å…§æ ¸é–‹ç™¼äººå“¡æ‡‰è©²èŠ± -時間充分了解å¯ç”¨çš„鎖原語，以便爲工作é¸æ“‡æ£ç¢ºçš„工具。å°ä¸¦ç™¼æ€§ç¼ºä¹é—œæ³¨çš„代碼 +時間充分了解å¯ç”¨çš„鎖原語，以便爲工作é¸æ“‡æ£ç¢ºçš„工具。å°ä½µç™¼æ€§ç¼ºä¹é—œæ³¨çš„代碼 很難進入主線。 -å›žæ¸ +è¿´æ¸ **** -最後一個值得一æçš„å±éšªæ˜¯å›žæ¸ï¼šå®ƒå¯èƒ½æœƒå¼•èµ·å°Žè‡´ç¾æœ‰ç”¨æˆ¶çš„æŸäº›æ±è¥¿ä¸æ–·çš„改變 -（這也å¯èƒ½æœƒå¸¶ä¾†å¾ˆå¤§çš„改進）。這種變化被稱爲「回æ¸ã€ï¼Œå›žæ¸å·²ç¶“æˆçˆ²ä¸»ç·šå…§æ ¸ -最ä¸å—æ¡è¿Žçš„å•é¡Œã€‚除了少數例外情æ³ï¼Œå¦‚果回æ¸ä¸èƒ½åŠæ™‚ä¿®æ£ï¼Œæœƒå°Žè‡´å›žæ¸çš„修改 -將被å–消。最好首先é¿å…回æ¸ç™¼ç”Ÿã€‚ +最後一個值得一æçš„å±éšªæ˜¯è¿´æ¸ï¼šå®ƒå¯èƒ½æœƒå¼•èµ·å°Žè‡´ç¾æœ‰ç”¨æˆ¶çš„æŸäº›æ±è¥¿ä¸æ–·çš„改變 +（這也å¯èƒ½æœƒå¸¶ä¾†å¾ˆå¤§çš„改進）。這種變化被稱爲“迴æ¸â€ï¼Œè¿´æ¸å·²ç¶“æˆçˆ²ä¸»ç·šå…§æ ¸ +最ä¸å—æ¡è¿Žçš„å•é¡Œã€‚除了少數例外情æ³ï¼Œå¦‚果迴æ¸ä¸èƒ½åŠæ™‚ä¿®æ£ï¼Œæœƒå°Žè‡´è¿´æ¸çš„修改 +將被å–消。最好首先é¿å…è¿´æ¸ç™¼ç”Ÿã€‚ -人們常常çˆè«–，如果回æ¸å¸¶ä¾†çš„功能é 超éŽç”¢ç”Ÿçš„å•é¡Œï¼Œé‚£éº¼å›žæ¸æ˜¯å¦çˆ²å¯æŽ¥å—的。 +人們常常çˆè«–，如果迴æ¸å¸¶ä¾†çš„功能é 超éŽç”¢ç”Ÿçš„å•é¡Œï¼Œé‚£éº¼è¿´æ¸æ˜¯å¦çˆ²å¯æŽ¥å—的。 å¦‚æžœå®ƒç ´å£žäº†ä¸€å€‹ç³»çµ±å»çˆ²å個系統帶來新的功能，爲何ä¸æ”¹æ”¹æ…‹åº¦å‘¢ï¼Ÿ2007å¹´7月， Linuså°é€™å€‹å•é¡Œçµ¦å‡ºäº†æœ€ä½³ç”案: @@ -154,7 +154,7 @@ Linuså°é€™å€‹å•é¡Œçµ¦å‡ºäº†æœ€ä½³ç”案: （http://lwn.net/Articles/243460/） -特別ä¸å—æ¡è¿Žçš„一種回æ¸é¡žåž‹æ˜¯ç”¨æˆ¶ç©ºé–“ABI的任何變化。一旦接å£è¢«å°Žå‡ºåˆ°ç”¨æˆ¶ç©ºé–“， +特別ä¸å—æ¡è¿Žçš„一種迴æ¸é¡žåž‹æ˜¯ç”¨æˆ¶ç©ºé–“ABI的任何變化。一旦接å£è¢«å°Žå‡ºåˆ°ç”¨æˆ¶ç©ºé–“， å°±å¿…é ˆç„¡é™æœŸåœ°æ”¯æŒå®ƒã€‚這一事實使得用戶空間接å£çš„å‰µå»ºç‰¹åˆ¥å…·æœ‰æŒ‘æˆ°æ€§ï¼šå› çˆ²å®ƒå€‘ ä¸èƒ½ä»¥ä¸å…¼å®¹çš„æ–¹å¼é€²è¡Œæ›´æ”¹ï¼Œæ‰€ä»¥å¿…é ˆä¸€æ¬¡å°±å°ã€‚å› æ¤ï¼Œç”¨æˆ¶ç©ºé–“接å£ç¸½æ˜¯éœ€è¦å¤§é‡ çš„æ€è€ƒã€æ¸…晰的文檔和廣泛的審查。 @@ -171,19 +171,19 @@ Linuså°é€™å€‹å•é¡Œçµ¦å‡ºäº†æœ€ä½³ç”案: 第一æ¥æ˜¯æ³¨æ„ç·¨è¯å™¨ç”¢ç”Ÿçš„è¦å‘Šã€‚當å‰ç‰ˆæœ¬çš„GCCå¯ä»¥æª¢æ¸¬ï¼ˆä¸¦è¦å‘Šï¼‰å¤§é‡æ½›åœ¨éŒ¯èª¤ã€‚ 通常，這些è¦å‘Šéƒ½æŒ‡å‘真æ£çš„å•é¡Œã€‚æ交以供審閱的代碼一般ä¸æœƒç”¢ç”Ÿä»»ä½•ç·¨è¯å™¨è¦å‘Šã€‚ -在消除è¦å‘Šæ™‚，注æ„了解真æ£çš„åŽŸå› ï¼Œä¸¦å„˜é‡é¿å…僅「修復ã€ä½¿è¦å‘Šæ¶ˆå¤±è€Œä¸è§£æ±ºå…¶åŽŸå› 。 +在消除è¦å‘Šæ™‚，注æ„çžè§£çœŸæ£çš„åŽŸå› ï¼Œä¸¦å„˜é‡é¿å…僅“修復â€ä½¿è¦å‘Šæ¶ˆå¤±è€Œä¸è§£æ±ºå…¶åŽŸå› 。 -請注æ„，並éžæ‰€æœ‰ç·¨è¯å™¨è¦å‘Šéƒ½é»˜èªå•“用。使用「make KCFLAGS=-Wã€æ§‹å»ºå…§æ ¸ä»¥ +請注æ„，並éžæ‰€æœ‰ç·¨è¯å™¨è¦å‘Šéƒ½é»˜èªå•“用。使用“make KCFLAGS=-Wâ€æ§‹å»ºå…§æ ¸ä»¥ ç²å¾—完整集åˆã€‚ -å…§æ ¸æ供了幾個é…ç½®é¸é …，å¯ä»¥æ‰“開調試功能；大多數é…ç½®é¸é …ä½æ–¼ã€Œkernel hacking〠+å…§æ ¸æ供了幾個é…ç½®é¸é …，å¯ä»¥æ‰“開調試功能；大多數é…ç½®é¸é …ä½æ–¼â€œkernel hacking†åèœå–®ä¸ã€‚å°æ–¼ä»»ä½•ç”¨æ–¼é–‹ç™¼æˆ–æ¸¬è©¦ç›®çš„çš„å…§æ ¸ï¼Œéƒ½æ‡‰è©²å•“ç”¨å…¶ä¸å¹¾å€‹é¸é …。特別是， 您應該打開： - FRAME_WARN ç²å–大於給定數é‡çš„å †æ£§å¹€çš„è¦å‘Šã€‚ 這些è¦å‘Šç”Ÿæˆçš„輸出å¯èƒ½æ¯”較冗長，但您ä¸å¿…æ“”å¿ƒä¾†è‡ªå…§æ ¸å…¶ä»–éƒ¨åˆ†çš„è¦å‘Šã€‚ - - DEBUG_OBJECTS å°‡æ·»åŠ ä»£ç¢¼ä»¥è·Ÿè¹¤å…§æ ¸å‰µå»ºçš„å„種å°è±¡çš„生命周期，並在出ç¾å•é¡Œ + - DEBUG_OBJECTS å°‡æ·»åŠ ä»£ç¢¼ä»¥è·Ÿè¹¤å…§æ ¸å‰µå»ºçš„å„種å°è±¡çš„生命週期，並在出ç¾å•é¡Œ 時發出è¦å‘Šã€‚å¦‚æžœä½ è¦æ·»åŠ 創建（和導出）關於其自己的複雜å°è±¡çš„å系統，請 考慮打開å°è±¡èª¿è©¦åŸºç¤Žçµæ§‹çš„支æŒã€‚ @@ -195,34 +195,34 @@ Linuså°é€™å€‹å•é¡Œçµ¦å‡ºäº†æœ€ä½³ç”案: 還有很多其他調試é¸é …，其ä¸ä¸€äº›å°‡åœ¨ä¸‹é¢è¨Žè«–。其ä¸ä¸€äº›æœ‰é¡¯è‘—的性能影響，ä¸æ‡‰ 一直使用。在å¸ç¿’å¯ç”¨é¸é …上花費一些時間，å¯èƒ½æœƒåœ¨çŸæœŸå…§å¾—åˆ°è¨±å¤šå›žå ±ã€‚ -å…¶ä¸ä¸€å€‹è¼ƒé‡çš„調試工具是鎖檢查器或「lockdepã€ã€‚該工具將跟蹤系統ä¸æ¯å€‹éŽ– +å…¶ä¸ä¸€å€‹è¼ƒé‡çš„調試工具是鎖檢查器或“lockdepâ€ã€‚該工具將跟蹤系統ä¸æ¯å€‹éŽ– （spinlock或mutex）的ç²å–和釋放ã€ç²å–鎖的相å°é †åºã€ç•¶å‰ä¸æ–·ç’°å¢ƒç‰ç‰ã€‚然後， 它å¯ä»¥ç¢ºä¿ç¸½æ˜¯ä»¥ç›¸åŒçš„é †åºç²å–鎖，相åŒçš„ä¸æ–·å‡è¨é©ç”¨æ–¼æ‰€æœ‰æƒ…æ³ç‰ç‰ã€‚æ›å¥è©± 說，lockdepå¯ä»¥æ‰¾åˆ°è¨±å¤šå°Žè‡´ç³»çµ±æ»éŽ–çš„å ´æ™¯ã€‚åœ¨éƒ¨ç½²çš„ç³»çµ±ä¸ï¼Œé€™ç¨®å•é¡Œå¯èƒ½æœƒ 很痛苦（å°æ–¼é–‹ç™¼äººå“¡å’Œç”¨æˆ¶è€Œè¨€ï¼‰ï¼›LockDepå…許æå‰ä»¥è‡ªå‹•æ–¹å¼ç™¼ç¾å•é¡Œã€‚具有 -任何類型的éžæ™®é€šéŽ–的代碼在æ交åˆä½µå‰æ‡‰åœ¨å•“用lockdep的情æ³ä¸‹é‹è¡Œæ¸¬è©¦ã€‚ +任何類型的éžæ™®é€šéŽ–的代碼在æ交åˆä¸¦å‰æ‡‰åœ¨å•“用lockdep的情æ³ä¸‹é‹è¡Œæ¸¬è©¦ã€‚ -ä½œçˆ²ä¸€å€‹å‹¤å¥®çš„å…§æ ¸ç¨‹å¼è¨è¨ˆå¸«ï¼Œæ¯«ç„¡ç–‘å•ï¼Œæ‚¨å°‡æª¢æŸ¥ä»»ä½•å¯èƒ½å¤±æ•—çš„æ“作（如內å˜åˆ†é…） +ä½œçˆ²ä¸€å€‹å‹¤å¥®çš„å…§æ ¸ç¨‹åºå“¡ï¼Œæ¯«ç„¡ç–‘å•ï¼Œæ‚¨å°‡æª¢æŸ¥ä»»ä½•å¯èƒ½å¤±æ•—çš„æ“作（如內å˜åˆ†é…） 的返回狀態。然而，事實上，最終的故障復ç¾è·¯å¾‘å¯èƒ½å®Œå…¨æ²’有經éŽæ¸¬è©¦ã€‚未測試的 代碼往往會出å•é¡Œï¼›å¦‚果所有這些錯誤處ç†è·¯å¾‘都被執行了幾次，那麼您å¯èƒ½å°ä»£ç¢¼ 更有信心。 å…§æ ¸æ供了一個å¯ä»¥åšåˆ°é€™ä¸€é»žçš„錯誤注入框架，特別是在涉åŠå…§å˜åˆ†é…的情æ³ä¸‹ã€‚ 啓用故障注入後，內å˜åˆ†é…çš„å¯é…置失敗的百分比；這些失敗å¯ä»¥é™å®šåœ¨ç‰¹å®šçš„代碼 -範åœå…§ã€‚在啓用了故障注入的情æ³ä¸‹é‹è¡Œï¼Œç¨‹å¼è¨è¨ˆå¸«å¯ä»¥çœ‹åˆ°ç•¶æƒ…æ³æƒ¡åŒ–時代碼如何響 +範åœå…§ã€‚在啓用了故障注入的情æ³ä¸‹é‹è¡Œï¼Œç¨‹åºå“¡å¯ä»¥çœ‹åˆ°ç•¶æƒ…æ³æƒ¡åŒ–時代碼如何響 應。有關如何使用æ¤å·¥å…·çš„詳細信æ¯ï¼Œè«‹åƒé–± Documentation/fault-injection/fault-injection.rst。 -「sparseã€éœæ…‹åˆ†æžå·¥å…·å¯ä»¥ç™¼ç¾å…¶ä»–類型的錯誤。sparseå¯ä»¥è¦å‘Šç¨‹å¼è¨è¨ˆå¸«ç”¨æˆ¶ç©ºé–“ +“sparseâ€éœæ…‹åˆ†æžå·¥å…·å¯ä»¥ç™¼ç¾å…¶ä»–類型的錯誤。sparseå¯ä»¥è¦å‘Šç¨‹åºå“¡ç”¨æˆ¶ç©ºé–“ å’Œå…§æ ¸ç©ºé–“åœ°å€ä¹‹é–“çš„æ··æ·†ã€å¤§ç«¯åºèˆ‡å°ç«¯åºçš„æ··æ·†ã€åœ¨éœ€è¦ä¸€çµ„ä½æ¨™èªŒçš„åœ°æ–¹å‚³éž -整數值ç‰ç‰ã€‚sparseå¿…é ˆå–®ç¨å®‰è£(如果您的分發伺æœå™¨æ²’有將其打包， +整數值ç‰ç‰ã€‚sparseå¿…é ˆå–®ç¨å®‰è£(如果您的分發æœå‹™å™¨æ²’有將其打包， å¯ä»¥åœ¨ https://sparse.wiki.kernel.org/index.php/Main_page 找到）, -然後å¯ä»¥é€šéŽåœ¨make命令ä¸æ·»åŠ 「C=1ã€åœ¨ä»£ç¢¼ä¸Šé‹è¡Œå®ƒã€‚ +然後å¯ä»¥é€šéŽåœ¨make命令ä¸æ·»åŠ “C=1â€åœ¨ä»£ç¢¼ä¸Šé‹è¡Œå®ƒã€‚ -「Coccinelleã€å·¥å…· :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` -èƒ½å¤ ç™¼ç¾å„種潛在的編碼å•é¡Œï¼›å®ƒé‚„å¯ä»¥çˆ²é€™äº›å•é¡Œæ出修複方案。在 -scripts/coccinelleç›®éŒ„ä¸‹å·²ç¶“æ‰“åŒ…äº†ç›¸ç•¶å¤šçš„å…§æ ¸ã€Œèªžç¾©è£œä¸ã€ï¼›é‹è¡Œ -「make coccicheckã€å°‡é‹è¡Œé€™äº›èªžç¾©è£œä¸ä¸¦å ±å‘Šç™¼ç¾çš„任何å•é¡Œã€‚有關詳細信æ¯ï¼Œè«‹åƒé–± +“Coccinelleâ€å·¥å…· :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` +èƒ½å¤ ç™¼ç¾å„種潛在的編碼å•é¡Œï¼›å®ƒé‚„å¯ä»¥çˆ²é€™äº›å•é¡Œæ出修復方案。在 +scripts/coccinelleç›®éŒ„ä¸‹å·²ç¶“æ‰“åŒ…äº†ç›¸ç•¶å¤šçš„å…§æ ¸â€œèªžç¾©è£œä¸â€ï¼›é‹è¡Œ +“make coccicheckâ€å°‡é‹è¡Œé€™äº›èªžç¾©è£œä¸ä¸¦å ±å‘Šç™¼ç¾çš„任何å•é¡Œã€‚有關詳細信æ¯ï¼Œè«‹åƒé–± :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>` @@ -247,7 +247,7 @@ scripts/coccinelleç›®éŒ„ä¸‹å·²ç¶“æ‰“åŒ…äº†ç›¸ç•¶å¤šçš„å…§æ ¸ã€Œèªžç¾©è£œä¸ã€ï¼ ä»»ä½•æ·»åŠ æ–°ç”¨æˆ¶ç©ºé–“æŽ¥å£çš„代碼——包括新的sysfs或/proc文件——都應該包å«è©²æŽ¥å£ çš„æ–‡æª”ï¼Œè©²æ–‡æª”ä½¿ç”¨æˆ¶ç©ºé–“é–‹ç™¼äººå“¡èƒ½å¤ çŸ¥é“他們在使用什麼。請åƒé–± -Documentation/ABI/README，了解如何æ¤æ–‡æª”æ ¼å¼ä»¥åŠéœ€è¦æ供哪些信æ¯ã€‚ +Documentation/ABI/README，çžè§£å¦‚何æ¤æ–‡æª”æ ¼å¼ä»¥åŠéœ€è¦æ供哪些信æ¯ã€‚ 文檔 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` æè¿°äº†å…§æ ¸çš„æ‰€æœ‰å¼•å°Žæ™‚é–“åƒæ•¸ã€‚ä»»ä½•æ·»åŠ æ–°åƒæ•¸çš„補ä¸éƒ½æ‡‰è©²å‘è©²æ–‡æª”æ·»åŠ é©ç•¶çš„ @@ -256,27 +256,27 @@ Documentation/ABI/README，了解如何æ¤æ–‡æª”æ ¼å¼ä»¥åŠéœ€è¦æä¾›å“ªäº›ä¿ ä»»ä½•æ–°çš„é…ç½®é¸é …éƒ½å¿…é ˆé™„æœ‰å¹«åŠ©æ–‡æœ¬ï¼Œå¹«åŠ©æ–‡æœ¬éœ€æ¸…æ¥šåœ°è§£é‡‹é€™äº›é¸é …以åŠç”¨æˆ¶å¯èƒ½ 希望何時使用它們。 -許多å系統的內部APIä¿¡æ¯é€šéŽå°ˆé–€æ ¼å¼åŒ–的注釋進行記錄；這些注釋å¯ä»¥é€šéŽ -「kernel-docã€è…³æœ¬ä»¥å¤šç¨®æ–¹å¼æå–å’Œæ ¼å¼åŒ–。如果您在具有kerneldoc注釋的åç³»çµ±ä¸ +許多å系統的內部APIä¿¡æ¯é€šéŽå°ˆé–€æ ¼å¼åŒ–的註釋進行記錄；這些註釋å¯ä»¥é€šéŽ +“kernel-docâ€è…³æœ¬ä»¥å¤šç¨®æ–¹å¼æå–å’Œæ ¼å¼åŒ–。如果您在具有kerneldoc註釋的åç³»çµ±ä¸ å·¥ä½œï¼Œå‰‡æ‡‰è©²ç¶è·å®ƒå€‘ï¼Œä¸¦æ ¹æ“šéœ€è¦çˆ²å¤–部å¯ç”¨çš„åŠŸèƒ½æ·»åŠ å®ƒå€‘ã€‚å³ä½¿åœ¨æ²’有如æ¤è¨˜éŒ„ -çš„é ˜åŸŸä¸ï¼Œçˆ²å°‡ä¾†æ·»åŠ kerneldoc注釋也沒有壞處；實際上，這å°æ–¼å‰›é–‹å§‹é–‹ç™¼å…§æ ¸çš„人 -ä¾†èªªæ˜¯ä¸€å€‹æœ‰ç”¨çš„æ´»å‹•ã€‚é€™äº›æ³¨é‡‹çš„æ ¼å¼ä»¥åŠå¦‚何創建kerneldoc模æ¿çš„一些信æ¯å¯ä»¥åœ¨ +çš„é ˜åŸŸä¸ï¼Œçˆ²å°‡ä¾†æ·»åŠ kerneldoc註釋也沒有壞處；實際上，這å°æ–¼å‰›é–‹å§‹é–‹ç™¼å…§æ ¸çš„人 +ä¾†èªªæ˜¯ä¸€å€‹æœ‰ç”¨çš„æ´»å‹•ã€‚é€™äº›è¨»é‡‹çš„æ ¼å¼ä»¥åŠå¦‚何創建kerneldoc模æ¿çš„一些信æ¯å¯ä»¥åœ¨ :ref:`Documentation/doc-guide/ <doc_guide>` 上找到。 -任何閱讀大é‡ç¾æœ‰å…§æ ¸ä»£ç¢¼çš„人都會注æ„到，注釋的缺失往往是最值得注æ„的。åŒæ™‚， -å°æ–°ä»£ç¢¼çš„è¦æ±‚比éŽåŽ»æ›´é«˜ï¼›åˆä½µæœªæ³¨é‡‹çš„ä»£ç¢¼å°‡æ›´åŠ å›°é›£ã€‚é€™å°±æ˜¯èªªï¼Œäººå€‘ä¸¦ä¸æœŸæœ› -詳細注釋的代碼。代碼本身應該是自解釋的，注釋闡釋了更微妙的方é¢ã€‚ +任何閱讀大é‡ç¾æœ‰å…§æ ¸ä»£ç¢¼çš„人都會注æ„到，註釋的缺失往往是最值得注æ„的。åŒæ™‚， +å°æ–°ä»£ç¢¼çš„è¦æ±‚比éŽåŽ»æ›´é«˜ï¼›åˆä½µæœªè¨»é‡‹çš„ä»£ç¢¼å°‡æ›´åŠ å›°é›£ã€‚é€™å°±æ˜¯èªªï¼Œäººå€‘ä¸¦ä¸æœŸæœ› +詳細註釋的代碼。代碼本身應該是自解釋的，註釋闡釋了更微妙的方é¢ã€‚ -æŸäº›äº‹æƒ…應該總是被注釋。使用內å˜å±éšœæ™‚，應附上一行文å—，解釋爲什麼需è¦è¨ç½®å…§å˜ +æŸäº›äº‹æƒ…應該總是被註釋。使用內å˜å±éšœæ™‚，應附上一行文å—，解釋爲什麼需è¦è¨ç½®å…§å˜ å±éšœã€‚數據çµæ§‹çš„鎖è¦å‰‡é€šå¸¸éœ€è¦åœ¨æŸå€‹åœ°æ–¹è§£é‡‹ã€‚一般來說，主è¦æ•¸æ“šçµæ§‹éœ€è¦å…¨é¢ 的文檔。應該指出代碼ä¸åˆ†ç«‹çš„ä½ä¹‹é–“ä¸æ˜Žé¡¯çš„ä¾è³´æ€§ã€‚任何å¯èƒ½èª˜ä½¿ä»£ç¢¼ç®¡ç†äººé€²è¡Œ -錯誤的「清ç†ã€çš„事情都需è¦ä¸€å€‹æ³¨é‡‹ä¾†èªªæ˜Žçˆ²ä»€éº¼è¦é€™æ¨£åšã€‚ç‰ç‰ã€‚ +錯誤的“清ç†â€çš„事情都需è¦ä¸€å€‹è¨»é‡‹ä¾†èªªæ˜Žçˆ²ä»€éº¼è¦é€™æ¨£åšã€‚ç‰ç‰ã€‚ 內部API更改 ----------- -å…§æ ¸æ供給用戶空間的二進ä½æŽ¥å£ä¸èƒ½è¢«ç ´å£žï¼Œé™¤éžé€¼ä¸å¾—å·²ã€‚è€Œå…§æ ¸çš„å…§éƒ¨ç·¨ç¨‹æŽ¥å£ +å…§æ ¸æ供給用戶空間的二進制接å£ä¸èƒ½è¢«ç ´å£žï¼Œé™¤éžé€¼ä¸å¾—å·²ã€‚è€Œå…§æ ¸çš„å…§éƒ¨ç·¨ç¨‹æŽ¥å£ æ˜¯é«˜åº¦æµå‹•çš„，當需è¦æ™‚å¯ä»¥æ›´æ”¹ã€‚å¦‚æžœä½ ç™¼ç¾è‡ªå·±ä¸å¾—ä¸è™•ç†ä¸€å€‹å…§æ ¸API，或者僅 åƒ…å› çˆ²å®ƒä¸æ»¿è¶³ä½ 的需求導致無法使用特定的功能，這å¯èƒ½æ˜¯API需è¦æ”¹è®Šçš„一個標誌。 ä½œçˆ²å…§æ ¸é–‹ç™¼äººå“¡ï¼Œæ‚¨æœ‰æ¬Šé€²è¡Œæ¤é¡žæ›´æ”¹ã€‚ @@ -287,7 +287,7 @@ Documentation/ABI/README，了解如何æ¤æ–‡æª”æ ¼å¼ä»¥åŠéœ€è¦æä¾›å“ªäº›ä¿ å¦ä¸€å€‹è¦é»žæ˜¯ï¼Œæ›´æ”¹å…§éƒ¨API的開發人員通常è¦è² è²¬ä¿®å¾©å…§æ ¸æ¨¹ä¸è¢«æ›´æ”¹ç ´å£žçš„任何代碼。 å°æ–¼ä¸€å€‹å»£æ³›ä½¿ç”¨çš„函數，這個責任å¯ä»¥å°Žè‡´æˆç™¾ä¸Šåƒçš„變化，其ä¸è¨±å¤šè®ŠåŒ–å¯èƒ½èˆ‡å…¶ä»– -開發人員æ£åœ¨åšçš„工作相è¡çªã€‚ä¸ç”¨èªªï¼Œé€™å¯èƒ½æ˜¯ä¸€é …大工程，所以最好確ä¿ç†ç”±æ˜¯ +開發人員æ£åœ¨åšçš„工作相沖çªã€‚ä¸ç”¨èªªï¼Œé€™å¯èƒ½æ˜¯ä¸€é …大工程，所以最好確ä¿ç†ç”±æ˜¯ å¯é 的。請注æ„，coccinelle工具å¯ä»¥å¹«åŠ©é€²è¡Œå»£æ³›çš„API更改。 在進行ä¸å…¼å®¹çš„API更改時，應儘å¯èƒ½ç¢ºä¿ç·¨è¯å™¨æ•ç²æœªæ›´æ–°çš„代碼。這將幫助您確ä¿æ‰¾ diff --git a/Documentation/translations/zh_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst index 27015622ad63..d398dda427aa 100644 --- a/Documentation/translations/zh_TW/process/5.Posting.rst +++ b/Documentation/translations/zh_TW/process/5.Posting.rst @@ -15,27 +15,27 @@ .. _tw_development_posting: -ç™¼å¸ƒè£œä¸ +ç™¼ä½ˆè£œä¸ ======== 您的工作é²æ—©æœƒæº–備好æ交給社å€é€²è¡Œå¯©æŸ¥ï¼Œä¸¦æœ€çµ‚包å«åˆ°ä¸»ç·šå…§æ ¸ä¸ã€‚毫ä¸ç¨€å¥‡ï¼Œ -å…§æ ¸é–‹ç™¼ç¤¾å€å·²ç¶“發展出一套用於發布補ä¸çš„約定和éŽç¨‹ï¼›éµå¾ªé€™äº›ç´„定和éŽç¨‹å°‡ä½¿ +å…§æ ¸é–‹ç™¼ç¤¾å€å·²ç¶“發展出一套用於發佈補ä¸çš„約定和éŽç¨‹ï¼›éµå¾ªé€™äº›ç´„定和éŽç¨‹å°‡ä½¿ åƒèˆ‡å…¶ä¸çš„æ¯å€‹äººçš„ç”Ÿæ´»æ›´åŠ è¼•é¬†ã€‚æœ¬æ–‡æª”è©¦åœ–æè¿°é€™äº›ç´„å®šçš„éƒ¨åˆ†ç´°ç¯€ï¼›æ›´å¤šä¿¡æ¯ ä¹Ÿå¯åœ¨ä»¥ä¸‹æ–‡æª”ä¸æ‰¾åˆ° -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` -å’Œ :ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>`。 +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` +å’Œ :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <tw_submitchecklist>`。 -何時郵寄 +ä½•æ™‚å¯„é€ -------- -在補ä¸å®Œå…¨ã€Œæº–備好ã€ä¹‹å‰ï¼Œé¿å…發布補ä¸æ˜¯ä¸€ç¨®æŒçºŒçš„誘惑。å°æ–¼ç°¡å–®çš„補ä¸ï¼Œé€™ +在補ä¸å®Œå…¨â€œæº–備好â€ä¹‹å‰ï¼Œé¿å…發佈補ä¸æ˜¯ä¸€ç¨®æŒçºŒçš„誘惑。å°æ–¼ç°¡å–®çš„補ä¸ï¼Œé€™ ä¸æ˜¯å•é¡Œã€‚但是如果æ£åœ¨å®Œæˆçš„工作很複雜，那麼在工作完æˆä¹‹å‰å¾žç¤¾å€ç²å¾—å饋就 -å¯ä»¥ç²å¾—å¾ˆå¤šå¥½è™•ã€‚å› æ¤ï¼Œæ‚¨æ‡‰è©²è€ƒæ…®ç™¼å¸ƒæ£åœ¨é€²è¡Œçš„工作，甚至ç¶è·ä¸€å€‹å¯ç”¨çš„Git +å¯ä»¥ç²å¾—å¾ˆå¤šå¥½è™•ã€‚å› æ¤ï¼Œæ‚¨æ‡‰è©²è€ƒæ…®ç™¼ä½ˆæ£åœ¨é€²è¡Œçš„工作，甚至ç¶è·ä¸€å€‹å¯ç”¨çš„Git 樹，以便感興趣的開發人員å¯ä»¥éš¨æ™‚趕上您的工作。 -當發布ä¸æœ‰å°šæœªæº–備好被包å«çš„代碼，最好在發布ä¸èªªæ˜Žã€‚還應æåŠä»»ä½•æœ‰å¾…完æˆçš„ +當發佈ä¸æœ‰å°šæœªæº–備好被包å«çš„代碼，最好在發佈ä¸èªªæ˜Žã€‚還應æåŠä»»ä½•æœ‰å¾…完æˆçš„ 主è¦å·¥ä½œå’Œä»»ä½•å·²çŸ¥å•é¡Œã€‚很少有人會願æ„看那些被èªçˆ²æ˜¯åŠç”Ÿä¸ç†Ÿçš„補ä¸ï¼Œä½†æ˜¯ -那些願æ„的人會帶著他們的點åä¾†ä¸€èµ·å¹«åŠ©ä½ æŠŠå·¥ä½œæŽ¨å‘æ£ç¢ºçš„æ–¹å‘。 +那些願æ„的人會帶ç€ä»–們的點åä¾†ä¸€èµ·å¹«åŠ©ä½ æŠŠå·¥ä½œæŽ¨å‘æ£ç¢ºçš„æ–¹å‘。 創建補ä¸ä¹‹å‰ ------------ @@ -50,20 +50,20 @@ - 您的更改是å¦å…·æœ‰æ€§èƒ½å½±éŸ¿ï¼Ÿå¦‚果是這樣，您應該é‹è¡ŒåŸºæº–測試來顯示您的變更的 影響（或好處）；çµæžœçš„摘è¦æ‡‰è©²åŒ…å«åœ¨è£œä¸ä¸ã€‚ - - 確ä¿æ‚¨æœ‰æ¬Šç™¼å¸ƒä»£ç¢¼ã€‚å¦‚æžœé€™é …å·¥ä½œæ˜¯çˆ²åƒ±ä¸»å®Œæˆçš„，僱主å°é€™é …工作具有所有權， - ä¸¦ä¸”å¿…é ˆåŒæ„æ ¹æ“šGPLå°å…¶é€²è¡Œç™¼å¸ƒã€‚ + - 確ä¿æ‚¨æœ‰æ¬Šç™¼ä½ˆä»£ç¢¼ã€‚å¦‚æžœé€™é …å·¥ä½œæ˜¯çˆ²åƒ±ä¸»å®Œæˆçš„，僱主å°é€™é …工作具有所有權， + ä¸¦ä¸”å¿…é ˆåŒæ„æ ¹æ“šGPLå°å…¶é€²è¡Œç™¼ä½ˆã€‚ -一般來說，在發布代碼之å‰é€²è¡Œä¸€äº›é¡å¤–çš„æ€è€ƒï¼Œå¹¾ä¹Žç¸½æ˜¯èƒ½åœ¨çŸæ™‚é–“å…§å¾—åˆ°å›žå ±ã€‚ +一般來說，在發佈代碼之å‰é€²è¡Œä¸€äº›é¡å¤–çš„æ€è€ƒï¼Œå¹¾ä¹Žç¸½æ˜¯èƒ½åœ¨çŸæ™‚é–“å…§å¾—åˆ°å›žå ±ã€‚ 補ä¸æº–å‚™ -------- -準備補ä¸ç™¼å¸ƒçš„工作é‡å¯èƒ½å¾ˆé©šäººï¼Œä½†åœ¨æ¤å˜—試節çœæ™‚間通常是ä¸æ˜Žæ™ºçš„，å³ä½¿åœ¨çŸæœŸ +準備補ä¸ç™¼ä½ˆçš„工作é‡å¯èƒ½å¾ˆé©šäººï¼Œä½†åœ¨æ¤å˜—試節çœæ™‚間通常是ä¸æ˜Žæ™ºçš„，å³ä½¿åœ¨çŸæœŸ 內亦然。 å¿…é ˆé‡å°å…§æ ¸çš„特定版本準備補ä¸ã€‚一般來說，補ä¸æ‡‰è©²åŸºæ–¼Linusçš„Git樹ä¸çš„ç•¶å‰ -主線。當以主線爲基礎時，請從一個衆所周知的發布點開始——如穩定版本或 -rc -版本發布點——而ä¸æ˜¯åœ¨ä¸€å€‹ä»»æ„的主線分支點。 +主線。當以主線爲基礎時，請從一個衆所周知的發佈點開始——如穩定版本或 -rc +版本發佈點——而ä¸æ˜¯åœ¨ä¸€å€‹ä»»æ„的主線分支點。 也å¯èƒ½éœ€è¦é‡å°-mmã€linux-next或å系統樹生æˆç‰ˆæœ¬ï¼Œä»¥ä¾¿æ–¼æ›´å»£æ³›çš„測試和審查。 æ ¹æ“šè£œä¸çš„å€åŸŸä»¥åŠå…¶ä»–地方的情æ³ï¼Œé‡å°å…¶ä»–樹建立的補ä¸å¯èƒ½éœ€è¦å¤§é‡çš„工作來 @@ -73,12 +73,12 @@ 分割補ä¸æ˜¯ä¸€é–€è—術；一些開發人員花了很長時間來弄清楚如何按照社å€æœŸæœ›çš„æ–¹å¼ä¾† 分割。ä¸éŽï¼Œé€™äº›ç¶“驗法則也許有幫助： - - 您發布的補ä¸ç³»åˆ—幾乎肯定ä¸æœƒæ˜¯é–‹ç™¼éŽç¨‹ä¸ç‰ˆæœ¬æŽ§åˆ¶ç³»çµ±ä¸çš„一系列更改。相å， + - 您發佈的補ä¸ç³»åˆ—幾乎肯定ä¸æœƒæ˜¯é–‹ç™¼éŽç¨‹ä¸ç‰ˆæœ¬æŽ§åˆ¶ç³»çµ±ä¸çš„一系列更改。相å， 需è¦å°æ‚¨æ‰€åšæ›´æ”¹çš„最終形å¼åŠ 以考慮，然後以有æ„義的方å¼é€²è¡Œæ‹†åˆ†ã€‚é–‹ç™¼äººå“¡å° é›¢æ•£çš„ã€è‡ªåŒ…å«çš„更改感興趣，而ä¸æ˜¯æ‚¨å‰µé€ 這些更改的原始路徑。 - - æ¯å€‹é‚輯上ç¨ç«‹çš„è®Šæ›´éƒ½æ‡‰è©²æ ¼å¼åŒ–爲單ç¨çš„補ä¸ã€‚這些更改å¯ä»¥æ˜¯å°çš„ï¼ˆå¦‚ã€Œå‘ - æ¤çµæ§‹é«”æ·»åŠ æ¬„ä½ã€ï¼‰æˆ–å¤§çš„ï¼ˆå¦‚æ·»åŠ ä¸€å€‹é‡è¦çš„新驅動程åºï¼‰ï¼Œä½†å®ƒå€‘在概念上 + - æ¯å€‹é‚輯上ç¨ç«‹çš„è®Šæ›´éƒ½æ‡‰è©²æ ¼å¼åŒ–爲單ç¨çš„補ä¸ã€‚這些更改å¯ä»¥æ˜¯å°çš„ï¼ˆå¦‚â€œå‘ + æ¤çµæ§‹é«”æ·»åŠ å—段â€ï¼‰æˆ–å¤§çš„ï¼ˆå¦‚æ·»åŠ ä¸€å€‹é‡è¦çš„新驅動程åºï¼‰ï¼Œä½†å®ƒå€‘在概念上 應該是å°çš„，並且å¯ä»¥åœ¨ä¸€è¡Œå…§ç°¡è¿°ã€‚æ¯å€‹è£œä¸éƒ½æ‡‰è©²åšä¸€å€‹ç‰¹å®šçš„ã€å¯ä»¥å–®ç¨ 檢查並驗è‰å®ƒæ‰€åšçš„事情的更改。 @@ -88,34 +88,34 @@ - æ¯å€‹è£œä¸éƒ½æ‡‰è©²èƒ½å‰µå»ºä¸€å€‹å¯ä»¥æ£ç¢ºåœ°æ§‹å»ºå’Œé‹è¡Œçš„å…§æ ¸ï¼›å¦‚æžœè£œä¸ç³»åˆ—在ä¸é–“被 斷開，那麼çµæžœä»æ‡‰æ˜¯ä¸€å€‹æ£å¸¸å·¥ä½œçš„å…§æ ¸ã€‚éƒ¨åˆ†æ‡‰ç”¨ä¸€ç³»åˆ—è£œä¸æ˜¯ä½¿ç”¨ - 「git bisctã€å·¥å…·æŸ¥æ‰¾å›žæ¸çš„ä¸€å€‹å¸¸è¦‹å ´æ™¯ï¼›å¦‚æžœçµæžœæ˜¯ä¸€å€‹æå£žçš„å…§æ ¸ï¼Œé‚£éº¼å°‡ä½¿ + “git bisctâ€å·¥å…·æŸ¥æ‰¾å›žæ¸çš„ä¸€å€‹å¸¸è¦‹å ´æ™¯ï¼›å¦‚æžœçµæžœæ˜¯ä¸€å€‹æå£žçš„å…§æ ¸ï¼Œé‚£éº¼å°‡ä½¿ 那些從事追蹤å•é¡Œçš„é«˜å°šå·¥ä½œçš„é–‹ç™¼äººå“¡å’Œç”¨æˆ¶çš„ç”Ÿæ´»æ›´åŠ è‰±é›£ã€‚ - ä¸è¦éŽåˆ†åˆ†å‰²ã€‚一ä½é–‹ç™¼äººå“¡æ›¾ç¶“將一組é‡å°å–®å€‹æ–‡ä»¶çš„編輯分æˆ500個單ç¨çš„è£œä¸ - 發布，這並沒有使他æˆçˆ²å…§æ ¸éƒµä»¶åˆ—表ä¸æœ€å—æ¡è¿Žçš„人。一個補ä¸å¯ä»¥ç›¸ç•¶å¤§ï¼Œ + 發佈，這並沒有使他æˆçˆ²å…§æ ¸éƒµä»¶åˆ—表ä¸æœ€å—æ¡è¿Žçš„人。一個補ä¸å¯ä»¥ç›¸ç•¶å¤§ï¼Œ åªè¦å®ƒä»ç„¶åŒ…å«ä¸€å€‹å–®ä¸€çš„ *é‚輯* 變更。 - 用一系列補ä¸æ·»åŠ 一個全新的基礎è¨æ–½ï¼Œä½†æ˜¯è©²è¨æ–½åœ¨ç³»åˆ—ä¸çš„最後一個補ä¸å•“用 整個變更之å‰ä¸èƒ½ä½¿ç”¨ï¼Œé€™çœ‹èµ·ä¾†å¾ˆèª˜äººã€‚如果å¯èƒ½çš„話，應該é¿å…這種誘惑； - å¦‚æžœé€™å€‹ç³»åˆ—å¢žåŠ äº†å›žæ¸ï¼Œé‚£éº¼äºŒåˆ†æ³•å°‡æŒ‡å‡ºæœ€å¾Œä¸€å€‹è£œä¸æ˜¯å°Žè‡´å•é¡Œçš„補ä¸ï¼Œ + å¦‚æžœé€™å€‹ç³»åˆ—å¢žåŠ äº†è¿´æ¸ï¼Œé‚£éº¼äºŒåˆ†æ³•å°‡æŒ‡å‡ºæœ€å¾Œä¸€å€‹è£œä¸æ˜¯å°Žè‡´å•é¡Œçš„補ä¸ï¼Œ å³ä½¿çœŸæ£çš„bug在其他地方。åªè¦æœ‰å¯èƒ½ï¼Œæ·»åŠ 新代碼的補ä¸ç¨‹åºæ‡‰è©²ç«‹å³æ¿€æ´»è©² 代碼。 -創建完美補ä¸ç³»åˆ—的工作å¯èƒ½æ˜¯ä¸€å€‹ä»¤äººæ²®å–ªçš„éŽç¨‹ï¼Œåœ¨å®Œæˆã€ŒçœŸæ£çš„工作ã€ä¹‹å¾Œéœ€è¦ +創建完美補ä¸ç³»åˆ—的工作å¯èƒ½æ˜¯ä¸€å€‹ä»¤äººæ²®å–ªçš„éŽç¨‹ï¼Œåœ¨å®Œæˆâ€œçœŸæ£çš„工作â€ä¹‹å¾Œéœ€è¦ 花費大é‡çš„時間和æ€è€ƒã€‚但是如果åšå¾—好，花費的時間就是值得的。 補ä¸æ ¼å¼å’Œæ›´æ”¹æ—¥èªŒ ------------------ -所以ç¾åœ¨ä½ 有了一系列完美的補ä¸å¯ä»¥ç™¼å¸ƒï¼Œä½†æ˜¯é€™é …工作還沒有完æˆã€‚æ¯å€‹è£œä¸éƒ½ +所以ç¾åœ¨ä½ 有了一系列完美的補ä¸å¯ä»¥ç™¼ä½ˆï¼Œä½†æ˜¯é€™é …工作還沒有完æˆã€‚æ¯å€‹è£œä¸éƒ½ 需è¦è¢«æ ¼å¼åŒ–æˆä¸€æ¢æ¶ˆæ¯ï¼Œä»¥å¿«é€Ÿè€Œæ¸…晰地將其目的傳é”到世界其他地方。爲æ¤ï¼Œ æ¯å€‹è£œä¸å°‡ç”±ä»¥ä¸‹éƒ¨åˆ†çµ„æˆï¼š - - å¯é¸çš„「Fromã€è¡Œï¼Œè¡¨æ˜Žè£œä¸ä½œè€…。åªæœ‰ç•¶ä½ 通éŽé›»å郵件發é€åˆ¥äººçš„補ä¸æ™‚，這一行 - æ‰æ˜¯å¿…é ˆçš„ï¼Œä½†æ˜¯çˆ²é˜²æ¢ç–‘å•åŠ 上它也ä¸æœƒæœ‰ä»€éº¼å£žè™•ã€‚ + - å¯é¸çš„“Fromâ€è¡Œï¼Œè¡¨æ˜Žè£œä¸ä½œè€…。åªæœ‰ç•¶ä½ 通éŽé›»å郵件發é€åˆ¥äººçš„補ä¸æ™‚，這一行 + çº”æ˜¯å¿…é ˆçš„ï¼Œä½†æ˜¯çˆ²é˜²æ¢ç–‘å•åŠ 上它也ä¸æœƒæœ‰ä»€éº¼å£žè™•ã€‚ - 一行æ述，說明補ä¸çš„作用。å°æ–¼åœ¨æ²’有其他上下文的情æ³ä¸‹çœ‹åˆ°è©²æ¶ˆæ¯çš„讀者來說， - 該消æ¯æ‡‰è¶³ä»¥ç¢ºå®šä¿®è£œç¨‹åºçš„範åœï¼›æ¤è¡Œå°‡é¡¯ç¤ºåœ¨ã€Œshort form（簡çŸæ ¼å¼ï¼‰ã€è®Šæ›´ + 該消æ¯æ‡‰è¶³ä»¥ç¢ºå®šä¿®è£œç¨‹åºçš„範åœï¼›æ¤è¡Œå°‡é¡¯ç¤ºåœ¨â€œshort form（簡çŸæ ¼å¼ï¼‰â€è®Šæ›´ 日誌ä¸ã€‚æ¤æ¶ˆæ¯é€šå¸¸éœ€è¦å…ˆåŠ 上å系統å稱å‰ç¶´ï¼Œç„¶å¾Œæ˜¯è£œä¸çš„目的。例如： :: @@ -144,17 +144,17 @@ ä¸€èˆ¬ä¾†èªªï¼Œä½ è¶ŠæŠŠè‡ªå·±æ”¾åœ¨æ¯å€‹é–±è®€ä½ 變更日誌的人的ä½ç½®ä¸Šï¼Œè®Šæ›´æ—¥èªŒï¼ˆå’Œå…§æ ¸ 作爲一個整體）就越好。 -ä¸æ¶ˆèªªï¼Œè®Šæ›´æ—¥èªŒæ˜¯å°‡è®Šæ›´æ交到版本控制系統時使用的文本。接下來將是： +ä¸éœ€è¦èªªï¼Œè®Šæ›´æ—¥èªŒæ˜¯å°‡è®Šæ›´æ交到版本控制系統時使用的文本。接下來將是： - - 補ä¸æœ¬èº«ï¼ŒæŽ¡ç”¨çµ±ä¸€çš„（「-uã€ï¼‰è£œä¸æ ¼å¼ã€‚使用「-pã€é¸é …來diff將使函數å與 + - 補ä¸æœ¬èº«ï¼ŒæŽ¡ç”¨çµ±ä¸€çš„（“-uâ€ï¼‰è£œä¸æ ¼å¼ã€‚使用“-pâ€é¸é …來diff將使函數å與 更改相關è¯ï¼Œå¾žè€Œä½¿çµæžœè£œä¸æ›´å®¹æ˜“被其他人讀å–。 您應該é¿å…在補ä¸ä¸åŒ…括與更改ä¸ç›¸é—œæ–‡ä»¶ï¼ˆä¾‹å¦‚，構建éŽç¨‹ç”Ÿæˆçš„文件或編輯器 -備份文件）。文檔目錄ä¸çš„「dontdiffã€æ–‡ä»¶åœ¨é€™æ–¹é¢æœ‰å¹«åŠ©ï¼›ä½¿ç”¨ã€Œ-Xã€é¸é …å°‡ +備份文件）。文檔目錄ä¸çš„“dontdiffâ€æ–‡ä»¶åœ¨é€™æ–¹é¢æœ‰å¹«åŠ©ï¼›ä½¿ç”¨â€œ-Xâ€é¸é …å°‡ 其傳éžçµ¦diff。 上é¢æ到的標籤（tag）用於æè¿°å„種開發人員如何與這個補ä¸çš„開發相關è¯ã€‚ -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` 文檔ä¸å°å®ƒå€‘進行了詳細æ述；下é¢æ˜¯ä¸€å€‹ç°¡çŸçš„總çµã€‚æ¯ä¸€è¡Œçš„æ ¼å¼å¦‚下： :: @@ -165,14 +165,14 @@ - Signed-off-by: 這是一個開發人員的è‰æ˜Žï¼Œè‰æ˜Žä»–或她有權æ交補ä¸ä»¥åŒ…å«åˆ°å…§æ ¸ ä¸ã€‚這表明åŒæ„開發者來æºèªè‰å”è°ï¼Œå…¶å…¨æ–‡è¦‹ - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` 如果沒有åˆé©çš„ç°½å—，則ä¸èƒ½åˆä½µåˆ°ä¸»ç·šä¸ã€‚ - Co-developed-by: è²æ˜Žè£œä¸æ˜¯ç”±å¤šå€‹é–‹ç™¼äººå“¡å…±åŒå‰µå»ºçš„；當幾個人在一個補ä¸ä¸Š 工作時，它用於給出共åŒä½œè€…（除了 From: 所給出的作者之外）。由於 Co-developed-by: 表示作者身份，所以æ¯å€‹å…±åŒé–‹ç™¼äººï¼Œå¿…é ˆç·Šè·Ÿåœ¨ç›¸é—œåˆä½œä½œè€… çš„Signed-off-by之後。具體內容和示例見以下文件 - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` - Acked-by: 表示å¦ä¸€å€‹é–‹ç™¼äººå“¡ï¼ˆé€šå¸¸æ˜¯ç›¸é—œä»£ç¢¼çš„ç¶è·äººå“¡ï¼‰åŒæ„補ä¸é©åˆåŒ…å« åœ¨å…§æ ¸ä¸ã€‚ @@ -180,7 +180,7 @@ - Tested-by: è²æ˜ŽæŸäººå·²ç¶“測試了補ä¸ä¸¦ç¢ºèªå®ƒå¯ä»¥å·¥ä½œã€‚ - Reviewed-by: 表示æŸé–‹ç™¼äººå“¡å·²ç¶“審查了補ä¸çš„æ£ç¢ºæ€§ï¼›æœ‰é—œè©³ç´°ä¿¡æ¯ï¼Œè«‹åƒé–± - :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` + :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` - Reported-by: æŒ‡å®šå ±å‘Šæ¤è£œä¸ä¿®å¾©çš„å•é¡Œçš„用戶；æ¤æ¨™è¨˜ç”¨æ–¼è¡¨ç¤ºæ„Ÿè¬ã€‚ @@ -188,16 +188,16 @@ 在補ä¸ä¸æ·»åŠ 標籤時è¦å°å¿ƒï¼šåªæœ‰Cc:æ‰é©åˆåœ¨æ²’有指定人員明確許å¯çš„情æ³ä¸‹æ·»åŠ 。 -發é€è£œä¸ +寄é€è£œä¸ -------- -在寄出補ä¸ä¹‹å‰ï¼Œæ‚¨é‚„需è¦æ³¨æ„以下幾點： +在寄é€è£œä¸ä¹‹å‰ï¼Œæ‚¨é‚„需è¦æ³¨æ„以下幾點： - 您確定您的郵件發é€ç¨‹åºä¸æœƒæ壞補ä¸å—Žï¼Ÿè¢«éƒµä»¶å®¢æˆ¶ç«¯æ›´æ”¹ç©ºç™½æˆ–ä¿®é£¾äº†è¡Œçš„è£œä¸ ç„¡æ³•è¢«å¦ä¸€ç«¯æŽ¥å—，並且通常ä¸æœƒé€²è¡Œä»»ä½•è©³ç´°æª¢æŸ¥ã€‚如果有任何疑å•ï¼Œå…ˆæŠŠè£œä¸å¯„ çµ¦ä½ è‡ªå·±ï¼Œè®“ä½ è‡ªå·±ç¢ºå®šå®ƒæ˜¯å®Œå¥½ç„¡æ的。 - :ref:`Documentation/translations/zh_TW/process/email-clients.rst <tw_email_clients>` + :ref:`Documentation/translations/zh_CN/process/email-clients.rst <tw_email_clients>` æ供了一些有用的æ示，å¯ä»¥è®“特定的郵件客戶端æ£å¸¸ç™¼é€è£œä¸ã€‚ - ä½ ç¢ºå®šä½ çš„è£œä¸æ²’有è’å”的錯誤嗎？您應該始終通éŽscripts/checkpatch.pl檢查 @@ -209,12 +209,12 @@ 引用補ä¸çš„部分。相å，åªéœ€å°‡è£œä¸ç›´æŽ¥æ”¾åˆ°æ‚¨çš„消æ¯ä¸ã€‚ 寄出補ä¸æ™‚，é‡è¦çš„是將副本發é€çµ¦ä»»ä½•å¯èƒ½æ„Ÿèˆˆè¶£çš„äººã€‚èˆ‡å…¶ä»–ä¸€äº›é …ç›®ä¸åŒï¼Œå…§æ ¸ -鼓勵人們甚至錯誤地發é€éŽå¤šçš„副本；ä¸è¦å‡å®šç›¸é—œäººå“¡æœƒçœ‹åˆ°æ‚¨åœ¨éƒµä»¶åˆ—表ä¸çš„發布。 +鼓勵人們甚至錯誤地發é€éŽå¤šçš„副本；ä¸è¦å‡å®šç›¸é—œäººå“¡æœƒçœ‹åˆ°æ‚¨åœ¨éƒµä»¶åˆ—表ä¸çš„發佈。 尤其是，副本應發é€è‡³ï¼š - å—影響å系統的ç¶è·äººå“¡ã€‚如å‰æ‰€è¿°ï¼Œç¶è·äººå“¡æ–‡ä»¶æ˜¯æŸ¥æ‰¾é€™äº›äººå“¡çš„首é¸åœ°æ–¹ã€‚ - - 其他在åŒä¸€é ˜åŸŸå·¥ä½œçš„開發人員，尤其是那些ç¾åœ¨å¯èƒ½åœ¨é‚£è£¡å·¥ä½œçš„開發人員。使用 + - 其他在åŒä¸€é ˜åŸŸå·¥ä½œçš„開發人員，尤其是那些ç¾åœ¨å¯èƒ½åœ¨é‚£è£å·¥ä½œçš„開發人員。使用 git查看還有誰修改了您æ£åœ¨è™•ç†çš„文件，這很有幫助。 - 如果您å°æŸéŒ¯èª¤å ±å‘Šæˆ–功能請求åšå‡ºéŸ¿æ‡‰ï¼Œä¹Ÿå¯ä»¥æŠ„é€åŽŸå§‹ç™¼é€äººã€‚ @@ -223,7 +223,7 @@ - 如果您æ£åœ¨ä¿®å¾©ä¸€å€‹ç¼ºé™·ï¼Œè«‹è€ƒæ…®è©²ä¿®å¾©æ˜¯å¦æ‡‰é€²å…¥ä¸‹ä¸€å€‹ç©©å®šæ›´æ–°ã€‚如果是這樣， 補ä¸å‰¯æœ¬ä¹Ÿæ‡‰ç™¼åˆ°stable@vger.kernel.org 。å¦å¤–，在補ä¸æœ¬èº«çš„標籤ä¸æ·»åŠ 一個 - 「Cc: stable@vger.kernel.orgã€ï¼›é€™å°‡ä½¿ç©©å®šç‰ˆåœ˜éšŠåœ¨ä¿®å¾©é€²å…¥ä¸»ç·šæ™‚收到通知。 + “Cc: stable@vger.kernel.orgâ€ï¼›é€™å°‡ä½¿ç©©å®šç‰ˆåœ˜éšŠåœ¨ä¿®å¾©é€²å…¥ä¸»ç·šæ™‚收到通知。 當爲一個補ä¸é¸æ“‡æŽ¥æ”¶è€…æ™‚ï¼Œæœ€å¥½æ¸…æ¥šä½ èªçˆ²èª°æœ€çµ‚會接å—這個補ä¸ä¸¦å°‡å…¶åˆä½µã€‚雖然 å¯ä»¥å°‡è£œä¸ç›´æŽ¥ç™¼çµ¦Linus Torvalds並讓他åˆä½µï¼Œä½†é€šå¸¸æƒ…æ³ä¸‹ä¸æœƒé€™æ¨£åšã€‚Linus很 @@ -236,7 +236,7 @@ [PATCH nn/mm] subsys: one-line description of the patch -å…¶ä¸ã€Œnnã€æ˜¯è£œä¸çš„åºè™Ÿï¼Œã€Œmmã€æ˜¯ç³»åˆ—ä¸è£œä¸çš„總數，「subsysã€æ˜¯å—影響å系統的 +å…¶ä¸â€œnnâ€æ˜¯è£œä¸çš„åºè™Ÿï¼Œâ€œmmâ€æ˜¯ç³»åˆ—ä¸è£œä¸çš„總數，“subsysâ€æ˜¯å—影響å系統的 å稱。當然，一個單ç¨çš„補ä¸å¯ä»¥çœç•¥nn/mm。 如果您有一系列é‡è¦çš„補ä¸ï¼Œé‚£éº¼é€šå¸¸ç™¼é€ä¸€å€‹ç°¡ä»‹ä½œçˆ²ç¬¬ã€‡éƒ¨åˆ†ã€‚ä¸éŽï¼Œé€™å€‹ç´„定 diff --git a/Documentation/translations/zh_TW/process/6.Followthrough.rst b/Documentation/translations/zh_TW/process/6.Followthrough.rst index 5073b6e77c1c..bcc885ae1b8e 100644 --- a/Documentation/translations/zh_TW/process/6.Followthrough.rst +++ b/Documentation/translations/zh_TW/process/6.Followthrough.rst @@ -18,13 +18,13 @@ 跟進 ==== -æ¤æ™‚，您已經éµå¾ªäº†åˆ°ç›®å‰çˆ²æ¢çµ¦å‡ºçš„指導方é‡ï¼Œä¸¦ä¸”ï¼Œéš¨è‘—æ‚¨è‡ªå·±çš„å·¥ç¨‹æŠ€èƒ½çš„å¢žåŠ ï¼Œ +æ¤æ™‚，您已經éµå¾ªäº†åˆ°ç›®å‰çˆ²æ¢çµ¦å‡ºçš„指導方é‡ï¼Œä¸¦ä¸”，隨ç€æ‚¨è‡ªå·±çš„å·¥ç¨‹æŠ€èƒ½çš„å¢žåŠ ï¼Œ 已經發布了一系列完美的補ä¸ã€‚å³ä½¿æ˜¯ç¶“é©—è±å¯Œçš„å…§æ ¸é–‹ç™¼äººå“¡ä¹Ÿèƒ½çŠ¯çš„æœ€å¤§éŒ¯èª¤ä¹‹ä¸€ -是，èªçˆ²ä»–們的工作ç¾åœ¨å·²ç¶“完æˆäº†ã€‚事實上，發布補ä¸æ„味著進入æµç¨‹çš„下一個階段， +是，èªçˆ²ä»–們的工作ç¾åœ¨å·²ç¶“完æˆäº†ã€‚事實上，發佈補ä¸æ„味ç€é€²å…¥æµç¨‹çš„下一個階段， å¯èƒ½é‚„需è¦åšå¾ˆå¤šå·¥ä½œã€‚ -一個補ä¸åœ¨é¦–次發布時就éžå¸¸å‡ºè‰²ã€æ²’æœ‰æ”¹é€²çš„é¤˜åœ°ï¼Œé€™æ˜¯å¾ˆç½•è¦‹çš„ã€‚å…§æ ¸é–‹ç™¼æµç¨‹å·² -èªè˜åˆ°é€™ä¸€äº‹å¯¦ï¼Œå› æ¤å®ƒéžå¸¸æ³¨é‡å°å·²ç™¼å¸ƒä»£ç¢¼çš„改進。作爲代碼的作者，您應該與 +一個補ä¸åœ¨é¦–次發佈時就éžå¸¸å‡ºè‰²ã€æ²’æœ‰æ”¹é€²çš„é¤˜åœ°ï¼Œé€™æ˜¯å¾ˆç½•è¦‹çš„ã€‚å…§æ ¸é–‹ç™¼æµç¨‹å·² +èªè˜åˆ°é€™ä¸€äº‹å¯¦ï¼Œå› æ¤å®ƒéžå¸¸æ³¨é‡å°å·²ç™¼ä½ˆä»£ç¢¼çš„改進。作爲代碼的作者，您應該與 å…§æ ¸ç¤¾å€åˆä½œï¼Œä»¥ç¢ºä¿æ‚¨çš„代碼符åˆå…§æ ¸çš„質é‡æ¨™æº–。如果ä¸åƒèˆ‡é€™å€‹éŽç¨‹ï¼Œå¾ˆå¯èƒ½æœƒ 無法將補ä¸åˆä½µåˆ°ä¸»ç·šä¸ã€‚ @@ -41,7 +41,7 @@ 調整到大é‡çš„é‡å¯«â€”—都來自於å°Linuxçš„ç†è§£ï¼Œå³å¾žç¾åœ¨èµ·å年後，Linuxä»å°‡ 在開發ä¸ã€‚ - - ä»£ç¢¼å¯©æŸ¥æ˜¯ä¸€é …è‰±è‹¦çš„å·¥ä½œï¼Œé€™æ˜¯ä¸€é …ç›¸å°åƒåŠ›ä¸è¨Žå¥½çš„工作；人們記得誰編寫了 + - ä»£ç¢¼å¯©æŸ¥æ˜¯ä¸€é …è‰±è‹¦çš„å·¥ä½œï¼Œé€™æ˜¯ä¸€é …ç›¸å°å–«åŠ›ä¸è¨Žå¥½çš„工作；人們記得誰編寫了 å…§æ ¸ä»£ç¢¼ï¼Œä½†å°æ–¼é‚£äº›å¯©æŸ¥å®ƒçš„人來說，幾乎沒有什麼長久的åè²ã€‚å› æ¤ï¼Œå¯©é–± 人員å¯èƒ½æœƒè®Šå¾—æš´èºï¼Œå°¤å…¶æ˜¯ç•¶ä»–們看到åŒæ¨£çš„錯誤被一éåˆä¸€é地犯下時。如果 ä½ å¾—åˆ°äº†ä¸€å€‹çœ‹èµ·ä¾†æ†¤æ€’ã€ä¾®è¾±æˆ–å®Œå…¨å†’çŠ¯ä½ çš„è©•è«–ï¼Œè«‹æŠ‘åˆ¶ä»¥åŒæ¨£æ–¹å¼å›žæ‡‰çš„è¡å‹•ã€‚ @@ -54,7 +54,7 @@ 所有這些æ¸æ ¹çµåº•å°±æ˜¯ï¼Œç•¶å¯©é–±è€…å‘您發é€è©•è«–時，您需è¦æ³¨æ„他們æ£åœ¨é€²è¡Œçš„技術 評論。ä¸è¦è®“他們的表é”æ–¹å¼æˆ–ä½ è‡ªå·±çš„é©•å‚²é˜»æ¢æ¤äº‹ã€‚ç•¶ä½ åœ¨ä¸€å€‹è£œä¸ä¸Šå¾—到評論 -時，花點時間去ç†è§£è©•è«–人想說什麼。如果å¯èƒ½çš„話，請修覆審閱者è¦æ±‚您修復的內 +時，花點時間去ç†è§£è©•è«–人想說什麼。如果å¯èƒ½çš„話，請修復審閱者è¦æ±‚您修復的內 容。然後回覆審閱者：è¬è¬ä»–們，並æè¿°ä½ å°‡å¦‚ä½•å›žç”他們的å•é¡Œã€‚ 請注æ„，您ä¸å¿…åŒæ„審閱者建è°çš„æ¯å€‹æ›´æ”¹ã€‚如果您èªçˆ²å¯©é–±è€…誤解了您的代碼，請 @@ -65,19 +65,19 @@ æ˜¯éŒ¯èª¤çš„ï¼Œæˆ–è€…ä½ ç”šè‡³æ²’æœ‰è§£æ±ºæ£ç¢ºçš„å•é¡Œã€‚ Andrew Morton建è°ï¼Œæ¯ä¸€å€‹ä¸æœƒå°Žè‡´ä»£ç¢¼æ›´æ”¹çš„審閱評論都應該產生一個é¡å¤–的代碼 -注釋；這å¯ä»¥å¹«åŠ©æœªä¾†çš„審閱人員é¿å…第一次出ç¾çš„å•é¡Œã€‚ +註釋；這å¯ä»¥å¹«åŠ©æœªä¾†çš„審閱人員é¿å…第一次出ç¾çš„å•é¡Œã€‚ 一個致命的錯誤是忽視評論，希望它們會消失。它們ä¸æœƒèµ°çš„。如果您在沒有å°ä¹‹å‰ 收到的評論åšå‡ºéŸ¿æ‡‰çš„情æ³ä¸‹é‡æ–°ç™¼å¸ƒä»£ç¢¼ï¼Œé‚£éº¼å¾ˆå¯èƒ½æœƒç™¼ç¾è£œä¸æ¯«ç„¡ç”¨è™•ã€‚ -說到é‡æ–°ç™¼å¸ƒä»£ç¢¼ï¼šè«‹è¨˜ä½ï¼Œå¯©é–±è€…ä¸æœƒè¨˜ä½æ‚¨ä¸Šæ¬¡ç™¼å¸ƒçš„ä»£ç¢¼çš„æ‰€æœ‰ç´°ç¯€ã€‚å› æ¤ï¼Œ +說到é‡æ–°ç™¼å¸ƒä»£ç¢¼ï¼šè«‹è¨˜ä½ï¼Œå¯©é–±è€…ä¸æœƒè¨˜ä½æ‚¨ä¸Šæ¬¡ç™¼ä½ˆçš„ä»£ç¢¼çš„æ‰€æœ‰ç´°ç¯€ã€‚å› æ¤ï¼Œ æ醒審閱人員以å‰æ出的å•é¡Œä»¥åŠæ‚¨å¦‚何處ç†é€™äº›å•é¡Œç¸½æ˜¯ä¸€å€‹å¥½ä¸»æ„；補ä¸è®Šæ›´ 日誌是æä¾›æ¤é¡žä¿¡æ¯çš„好地方。審閱者ä¸å¿…æœç´¢åˆ—表檔案來熟悉上次所說的內容； 如果您幫助他們直接開始，當他們é‡æ–°æŸ¥çœ‹æ‚¨çš„代碼時，心情會更好。 -å¦‚æžœä½ å·²ç¶“è©¦è‘—åšæ£ç¢ºçš„事情，但事情ä»ç„¶æ²’有進展呢？大多數技術上的分æ§éƒ½å¯ä»¥ +å¦‚æžœä½ å·²ç¶“è©¦ç€åšæ£ç¢ºçš„事情，但事情ä»ç„¶æ²’有進展呢？大多數技術上的分æ§éƒ½å¯ä»¥ 通éŽè¨Žè«–來解決，但有時人們ä»éœ€è¦åšå‡ºæ±ºå®šã€‚å¦‚æžœä½ çœŸçš„èªçˆ²é€™å€‹æ±ºå®šå°ä½ ä¸åˆ©ï¼Œ -ä½ å¯ä»¥è©¦è‘—å‘有更高權力的人上訴。å°æ–¼æœ¬æ–‡ï¼Œæ›´é«˜æ¬ŠåŠ›çš„人是 Andrew Morton 。 +ä½ å¯ä»¥è©¦ç€å‘有更高權力的人上訴。å°æ–¼æœ¬æ–‡ï¼Œæ›´é«˜æ¬ŠåŠ›çš„人是 Andrew Morton 。 Andrew åœ¨å…§æ ¸é–‹ç™¼ç¤¾å€ä¸éžå¸¸å—尊敬；他經常爲似乎被絕望阻塞的事情清障。儘管 如æ¤ï¼Œä¸æ‡‰è¼•æ˜“就直接找 Andrew ，也ä¸æ‡‰åœ¨æ‰€æœ‰å…¶ä»–替代方案都被嘗試之å‰æ‰¾ä»–。 當然，記ä½ï¼Œä»–也å¯èƒ½ä¸åŒæ„ä½ çš„æ„見。 @@ -95,7 +95,7 @@ Andrew åœ¨å…§æ ¸é–‹ç™¼ç¤¾å€ä¸éžå¸¸å—尊敬；他經常爲似乎被絕望阻å 包å«åœ¨å系統樹ä¸å¯ä»¥æ高補ä¸çš„å¯è¦‹æ€§ã€‚ç¾åœ¨ï¼Œä½¿ç”¨è©²æ¨¹çš„其他開發人員將默èªç² 得補ä¸ã€‚å系統樹通常也爲Linuxæ供支æŒï¼Œä½¿å…¶å…§å®¹å°æ•´å€‹é–‹ç™¼ç¤¾å€å¯è¦‹ã€‚在這一點 -上，您很å¯èƒ½æœƒå¾žä¸€çµ„新的審閱者那裡得到更多的評論；這些評論需è¦åƒä¸Šä¸€è¼ªé‚£æ¨£ +上，您很å¯èƒ½æœƒå¾žä¸€çµ„新的審閱者那è£å¾—到更多的評論；這些評論需è¦åƒä¸Šä¸€è¼ªé‚£æ¨£ 得到回應。 在這時也會發生點什麼，這å–æ±ºæ–¼ä½ çš„è£œä¸çš„性質，是å¦èˆ‡å…¶ä»–人æ£åœ¨åšçš„工作發生 @@ -114,23 +114,23 @@ Andrew åœ¨å…§æ ¸é–‹ç™¼ç¤¾å€ä¸éžå¸¸å—尊敬；他經常爲似乎被絕望阻å 這種誘惑，您ä»ç„¶éœ€è¦å°æœ‰å•é¡Œæˆ–建è°çš„開發人員作出響應。 ä¸éŽï¼Œæ›´é‡è¦çš„是：將代碼包å«åœ¨ä¸»ç·šä¸æœƒå°‡ä»£ç¢¼äº¤çµ¦æ›´å¤šçš„一些測試人員。å³ä½¿æ‚¨ -爲尚未å¯ç”¨çš„硬體æ供了驅動程åºï¼Œæ‚¨ä¹Ÿæœƒé©šè¨æ–¼æœ‰å¤šå°‘äººæœƒå°‡æ‚¨çš„ä»£ç¢¼æ§‹å»ºåˆ°å…§æ ¸ +爲尚未å¯ç”¨çš„硬件æ供了驅動程åºï¼Œæ‚¨ä¹Ÿæœƒé©šè¨æ–¼æœ‰å¤šå°‘äººæœƒå°‡æ‚¨çš„ä»£ç¢¼æ§‹å»ºåˆ°å…§æ ¸ ä¸ã€‚當然，如果有測試人員，也å¯èƒ½æœƒæœ‰éŒ¯èª¤å ±å‘Šã€‚ -æœ€ç³Ÿç³•çš„éŒ¯èª¤å ±å‘Šæ˜¯å›žæ¸ã€‚å¦‚æžœä½ çš„è£œä¸å°Žè‡´å›žæ¸ï¼Œä½ 會發ç¾å¤šåˆ°è®“ä½ ä¸èˆ’æœçš„眼ç›ç›¯ -è‘—ä½ ï¼›å›žæ¸éœ€è¦å„˜å¿«ä¿®å¾©ã€‚如果您ä¸é¡˜æ„或無法修復回æ¸ï¼ˆå…¶ä»–人都ä¸æœƒçˆ²æ‚¨ä¿®å¾©ï¼‰ï¼Œ +æœ€ç³Ÿç³•çš„éŒ¯èª¤å ±å‘Šæ˜¯è¿´æ¸ã€‚å¦‚æžœä½ çš„è£œä¸å°Žè‡´è¿´æ¸ï¼Œä½ 會發ç¾å¤šåˆ°è®“ä½ ä¸èˆ’æœçš„眼ç›ç›¯ +ç€ä½ ；迴æ¸éœ€è¦å„˜å¿«ä¿®å¾©ã€‚如果您ä¸é¡˜æ„或無法修復迴æ¸ï¼ˆå…¶ä»–人都ä¸æœƒçˆ²æ‚¨ä¿®å¾©ï¼‰ï¼Œ 那麼在穩定期內，您的補ä¸å¹¾ä¹Žè‚¯å®šæœƒè¢«ç§»é™¤ã€‚除了å¦å®šæ‚¨çˆ²ä½¿è£œä¸é€²å…¥ä¸»ç·šæ‰€åšçš„ -所有工作之外，如果由於未能修復回æ¸è€Œå–消補ä¸ï¼Œå¾ˆå¯èƒ½æœƒä½¿å°‡ä¾†çš„工作更難被åˆä½µã€‚ +所有工作之外，如果由於未能修復迴æ¸è€Œå–消補ä¸ï¼Œå¾ˆå¯èƒ½æœƒä½¿å°‡ä¾†çš„工作更難被åˆä½µã€‚ -在處ç†å®Œä»»ä½•å›žæ¸ä¹‹å¾Œï¼Œå¯èƒ½é‚„有其他普通缺陷需è¦è™•ç†ã€‚穩定期是修復這些錯誤並 -確ä¿ä»£ç¢¼åœ¨ä¸»ç·šå…§æ ¸ç‰ˆæœ¬ä¸çš„首次發布儘å¯èƒ½å¯é 的最好機會。所以，請回應錯誤 +在處ç†å®Œä»»ä½•è¿´æ¸ä¹‹å¾Œï¼Œå¯èƒ½é‚„有其他普通缺陷需è¦è™•ç†ã€‚穩定期是修復這些錯誤並 +確ä¿ä»£ç¢¼åœ¨ä¸»ç·šå…§æ ¸ç‰ˆæœ¬ä¸çš„首次發佈儘å¯èƒ½å¯é 的最好機會。所以，請回應錯誤 å ±å‘Šï¼Œä¸¦å„˜å¯èƒ½è§£æ±ºå•é¡Œã€‚這就是穩定期的目的；一旦解決了舊補ä¸çš„任何å•é¡Œï¼Œå°± å¯ä»¥é–‹å§‹ç›¡æƒ…創建新補ä¸ã€‚ 別忘了，還有其他節點也å¯èƒ½æœƒå‰µå»ºç¼ºé™·å ±å‘Šï¼šä¸‹ä¸€å€‹ä¸»ç·šç©©å®šç‰ˆæœ¬ï¼Œç•¶è‘—å的發行 商é¸æ“‡åŒ…å«æ‚¨è£œä¸çš„å…§æ ¸ç‰ˆæœ¬æ™‚ç‰ç‰ã€‚ç¹¼çºŒéŸ¿æ‡‰é€™äº›å ±å‘Šæ˜¯æ‚¨å·¥ä½œçš„åŸºæœ¬ç´ é¤Šã€‚ä½†æ˜¯ 如果這ä¸èƒ½æä¾›è¶³å¤ çš„å‹•æ©Ÿï¼Œé‚£éº¼ä¹Ÿéœ€è¦è€ƒæ…®ï¼šé–‹ç™¼ç¤¾å€æœƒè¨˜ä½é‚£äº›åœ¨åˆä½µå¾Œå°ä»£ç¢¼ -å¤±åŽ»èˆˆè¶£çš„é–‹ç™¼äººå“¡ã€‚ä¸‹ä¸€æ¬¡ä½ ç™¼å¸ƒè£œä¸æ™‚ï¼Œä»–å€‘æœƒä»¥ä½ ä»¥å¾Œä¸æœƒæŒçºŒç¶è·å®ƒçˆ²å‰æ +å¤±åŽ»èˆˆè¶£çš„é–‹ç™¼äººå“¡ã€‚ä¸‹ä¸€æ¬¡ä½ ç™¼ä½ˆè£œä¸æ™‚ï¼Œä»–å€‘æœƒä»¥ä½ ä»¥å¾Œä¸æœƒæŒçºŒç¶è·å®ƒçˆ²å‰æ 來評估它。 其他å¯èƒ½ç™¼ç”Ÿçš„事情 @@ -141,15 +141,15 @@ Andrew åœ¨å…§æ ¸é–‹ç™¼ç¤¾å€ä¸éžå¸¸å—尊敬；他經常爲似乎被絕望阻å ç¶è·äººå“¡ï¼ˆç¢ºä¿åŒ…å«ä¸€å€‹æ£ç¢ºçš„From:行，這樣屬性是æ£ç¢ºçš„ï¼Œä¸¦æ·»åŠ ä¸€å€‹æ‚¨è‡ªå·±çš„ signoff ），或者回復一個 Acked-by: 讓原始發é€è€…å‘上發é€å®ƒã€‚ -如果您ä¸åŒæ„補ä¸ï¼Œè«‹ç¦®è²Œåœ°å›žå¾©ï¼Œè§£é‡‹åŽŸå› 。如果å¯èƒ½çš„話，告訴作者需è¦åšå“ªäº› -更改æ‰èƒ½è®“您接å—補ä¸ã€‚åˆä½µä»£ç¢¼çš„編寫者和ç¶è·è€…所åå°çš„補ä¸çš„確å˜åœ¨è‘—一定的 +如果您ä¸åŒæ„補ä¸ï¼Œè«‹ç¦®è²Œåœ°å›žè¦†ï¼Œè§£é‡‹åŽŸå› 。如果å¯èƒ½çš„話，告訴作者需è¦åšå“ªäº› +更改æ‰èƒ½è®“您接å—補ä¸ã€‚åˆä½µä»£ç¢¼çš„編寫者和ç¶è·è€…所åå°çš„補ä¸çš„確å˜åœ¨ç€ä¸€å®šçš„ 阻力，但僅æ¤è€Œå·²ã€‚å¦‚æžœä½ è¢«èªçˆ²ä¸å¿…è¦çš„阻礙了好的工作，那麼這些補ä¸æœ€çµ‚會 繞éŽä½ 並進入主線。在Linuxå…§æ ¸ä¸ï¼Œæ²’有人å°ä»»ä½•ä»£ç¢¼æ“有絕å°çš„å¦æ±ºæ¬Šã€‚å¯èƒ½é™¤ 了Linus。 -在éžå¸¸ç½•è¦‹çš„情æ³ä¸‹ï¼Œæ‚¨å¯èƒ½æœƒçœ‹åˆ°å®Œå…¨ä¸åŒçš„æ±è¥¿ï¼šå¦ä¸€å€‹é–‹ç™¼äººå“¡ç™¼å¸ƒäº†é‡å°æ‚¨ -çš„å•é¡Œçš„ä¸åŒè§£æ±ºæ–¹æ¡ˆã€‚在這時，兩個補ä¸ä¹‹ä¸€å¯èƒ½ä¸æœƒè¢«åˆä½µï¼Œã€Œæˆ‘的補ä¸é¦–å…ˆ -發布ã€ä¸è¢«èªçˆ²æ˜¯ä¸€å€‹ä»¤äººä¿¡æœçš„技術論據。如果有別人的補ä¸å–ä»£äº†ä½ çš„è£œä¸è€Œé€² +在éžå¸¸ç½•è¦‹çš„情æ³ä¸‹ï¼Œæ‚¨å¯èƒ½æœƒçœ‹åˆ°å®Œå…¨ä¸åŒçš„æ±è¥¿ï¼šå¦ä¸€å€‹é–‹ç™¼äººå“¡ç™¼ä½ˆäº†é‡å°æ‚¨ +çš„å•é¡Œçš„ä¸åŒè§£æ±ºæ–¹æ¡ˆã€‚在這時，兩個補ä¸ä¹‹ä¸€å¯èƒ½ä¸æœƒè¢«åˆä½µï¼Œâ€œæˆ‘的補ä¸é¦–å…ˆ +發佈â€ä¸è¢«èªçˆ²æ˜¯ä¸€å€‹ä»¤äººä¿¡æœçš„技術論據。如果有別人的補ä¸å–ä»£äº†ä½ çš„è£œä¸è€Œé€² 入了主線，那麼åªæœ‰ä¸€ç¨®æ–¹æ³•å¯ä»¥å›žæ‡‰ä½ ï¼šå¾ˆé«˜èˆˆä½ çš„å•é¡Œè§£æ±ºäº†ï¼Œè«‹ç¹¼çºŒå·¥ä½œå§ã€‚ 以這種方å¼æŠŠæŸäººçš„工作推到一邊å¯èƒ½å°Žè‡´å‚·å¿ƒå’Œæ°£é¤’，但是社å€æœƒè¨˜ä½ä½ çš„å應， å³ä½¿å¾ˆä¹…以後他們已經忘記了誰的補ä¸çœŸæ£è¢«åˆä½µã€‚ diff --git a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst index 2cbd16bfed29..db74d8ca3f3b 100644 --- a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst @@ -24,14 +24,14 @@ 使用Git管ç†è£œä¸ --------------- -å…§æ ¸ä½¿ç”¨åˆ†å¸ƒå¼ç‰ˆæœ¬æŽ§åˆ¶å§‹æ–¼2002å¹´åˆï¼Œç•¶æ™‚Linus首次開始使用專有的Bitkeeper應用 -程åºã€‚雖然BitKeeperå˜åœ¨çˆè°ï¼Œä½†å®ƒæ‰€é«”ç¾çš„軟體版本管ç†æ–¹æ³•å»è‚¯å®šä¸æ˜¯ã€‚åˆ†å¸ƒå¼ +å…§æ ¸ä½¿ç”¨åˆ†ä½ˆå¼ç‰ˆæœ¬æŽ§åˆ¶å§‹æ–¼2002å¹´åˆï¼Œç•¶æ™‚Linus首次開始使用專有的Bitkeeper應用 +程åºã€‚雖然BitKeeperå˜åœ¨çˆè°ï¼Œä½†å®ƒæ‰€é«”ç¾çš„軟件版本管ç†æ–¹æ³•å»è‚¯å®šä¸æ˜¯ã€‚åˆ†ä½ˆå¼ ç‰ˆæœ¬æŽ§åˆ¶å¯ä»¥ç«‹å³åŠ é€Ÿå…§æ ¸é–‹ç™¼é …ç›®ã€‚ç¾åœ¨æœ‰å¥½å¹¾ç¨®å…費的BitKeeper替代å“。 ä½†ç„¡è«–å¥½å£žï¼Œå…§æ ¸é …ç›®éƒ½å·²ç¶“é¸æ“‡äº†Git作爲其工具。 -使用Git管ç†è£œä¸å¯ä»¥ä½¿é–‹ç™¼äººå“¡çš„ç”Ÿæ´»æ›´åŠ è¼•é¬†ï¼Œå°¤å…¶æ˜¯éš¨è‘—è£œä¸æ•¸é‡çš„增長。Git也 +使用Git管ç†è£œä¸å¯ä»¥ä½¿é–‹ç™¼äººå“¡çš„ç”Ÿæ´»æ›´åŠ è¼•é¬†ï¼Œå°¤å…¶æ˜¯éš¨ç€è£œä¸æ•¸é‡çš„增長。Git也 有其粗糙的邊角和一定的å±éšªæ€§ï¼Œå®ƒæ˜¯ä¸€å€‹å¹´è¼•å’Œå¼·å¤§çš„工具，ä»ç„¶åœ¨å…¶é–‹ç™¼äººå“¡å®Œå–„ -ä¸ã€‚本文檔ä¸æœƒè©¦åœ–教會讀者如何使用git；這會是個巨長的文檔。相å，這裡的é‡é»ž +ä¸ã€‚本文檔ä¸æœƒè©¦åœ–教會讀者如何使用git；這會是個巨長的文檔。相å，這è£çš„é‡é»ž 將是Git如何特別é©åˆå…§æ ¸é–‹ç™¼éŽç¨‹ã€‚想è¦åŠ 快用Git速度的開發人員å¯ä»¥åœ¨ä»¥ä¸‹ç¶²ç«™ä¸Š 找到更多信æ¯ï¼š @@ -42,22 +42,22 @@ åŒæ™‚網上也能找到å„種å„樣的教程。 在嘗試使用它生æˆè£œä¸ä¾›ä»–人使用之å‰ï¼Œç¬¬ä¸€è¦å‹™æ˜¯é–±è®€ä¸Šè¿°ç¶²é ，å°Gitçš„å·¥ä½œæ–¹å¼ -有一個紮實的了解。使用Git的開發人員應能進行拉å–主線å˜å„²åº«çš„副本，查詢修訂 -æ·å²ï¼Œæ交å°æ¨¹çš„更改，使用分支ç‰æ“作。了解Git用於é‡å¯«æ·å²çš„工具（如rebase） -也很有用。Git有自己的術語和概念；Git的新用戶應該了解引用ã€é 程分支ã€ç´¢å¼•ã€ -快進åˆä½µã€æŽ¨æ‹‰ã€æ¸¸é›¢é ç‰ã€‚一開始å¯èƒ½æœ‰é»žåš‡äººï¼Œä½†é€™äº›æ¦‚念ä¸é›£é€šéŽä¸€é»žå¸ç¿’來 +有一個紮實的çžè§£ã€‚使用Git的開發人員應能進行拉å–主線å˜å„²åº«çš„副本，查詢修訂 +æ·å²ï¼Œæ交å°æ¨¹çš„更改，使用分支ç‰æ“作。çžè§£Git用於é‡å¯«æ·å²çš„工具（如rebase） +也很有用。Git有自己的術語和概念；Git的新用戶應該çžè§£å¼•ç”¨ã€é 程分支ã€ç´¢å¼•ã€ +快進åˆä½µã€æŽ¨æ‹‰ã€éŠé›¢é ç‰ã€‚一開始å¯èƒ½æœ‰é»žåš‡äººï¼Œä½†é€™äº›æ¦‚念ä¸é›£é€šéŽä¸€é»žå¸ç¿’來 ç†è§£ã€‚ 使用git生æˆé€šéŽé›»å郵件æ交的補ä¸æ˜¯æ高速度的一個很好的練習。 -當您準備好開始建立Git樹供其他人查看時，無疑需è¦ä¸€å€‹å¯ä»¥å¾žä¸æ‹‰å–的伺æœå™¨ã€‚ -如果您有一個å¯ä»¥è¨ªå•ç¶²éš›ç¶²è·¯çš„系統，那麼使用git-daemonè¨ç½®é€™æ¨£çš„伺æœå™¨ç›¸å° +當您準備好開始建立Git樹供其他人查看時，無疑需è¦ä¸€å€‹å¯ä»¥å¾žä¸æ‹‰å–çš„æœå‹™å™¨ã€‚ +如果您有一個å¯ä»¥è¨ªå•å› 特網的系統，那麼使用git-daemonè¨ç½®é€™æ¨£çš„æœå‹™å™¨ç›¸å° 簡單。åŒæ™‚，å…費的公共託管網站（例如github）也開始出ç¾åœ¨ç¶²çµ¡ä¸Šã€‚æˆç†Ÿçš„開發 人員å¯ä»¥åœ¨kernel.org上ç²å¾—一個帳戶，但這些帳戶並ä¸å®¹æ˜“得到；更多有關信æ¯ï¼Œ è«‹åƒé–± https://kernel.org/faq/ 。 -æ£å¸¸çš„Git工作æµç¨‹æ¶‰åŠåˆ°è¨±å¤šåˆ†æ”¯çš„使用。æ¯ä¸€æ¢é–‹ç™¼ç·šéƒ½å¯ä»¥åˆ†çˆ²å–®ç¨çš„「主題 -分支ã€ï¼Œä¸¦ç¨ç«‹ç¶è·ã€‚Git的分支很容易使用，沒有ç†ç”±ä¸ä½¿ç”¨å®ƒå€‘。而且，在任何 +æ£å¸¸çš„Git工作æµç¨‹æ¶‰åŠåˆ°è¨±å¤šåˆ†æ”¯çš„使用。æ¯ä¸€æ¢é–‹ç™¼ç·šéƒ½å¯ä»¥åˆ†çˆ²å–®ç¨çš„“主題 +分支â€ï¼Œä¸¦ç¨ç«‹ç¶è·ã€‚Git的分支很容易使用，沒有ç†ç”±ä¸ä½¿ç”¨å®ƒå€‘。而且，在任何 情æ³ä¸‹ï¼Œæ‚¨éƒ½ä¸æ‡‰è©²åœ¨ä»»ä½•æ‚¨æ‰“算讓其他人從ä¸æ‹‰å–的分支ä¸é€²è¡Œé–‹ç™¼ã€‚應該å°å¿ƒåœ° 創建公開å¯ç”¨çš„分支；當開發分支處於完整狀態並已準備好時(而ä¸æ˜¯ä¹‹å‰ï¼‰æ‰åˆä½µ 開發分支的補ä¸ã€‚ @@ -72,10 +72,10 @@ Gitæ供了一些強大的工具，å¯ä»¥è®“您é‡å¯«é–‹ç™¼æ·å²ã€‚一個ä¸æ– 簡單癡迷。é‡å¯«æ·å²å°‡é‡å¯«è©²æ·å²ä¸åŒ…å«çš„更改，將經éŽæ¸¬è©¦ï¼ˆå¸Œæœ›å¦‚æ¤ï¼‰çš„å…§æ ¸æ¨¹ è®Šçˆ²æœªç¶“æ¸¬è©¦çš„å…§æ ¸æ¨¹ã€‚é™¤æ¤ä¹‹å¤–ï¼Œå¦‚æžœé–‹ç™¼äººå“¡æ²’æœ‰å…±äº«é …ç›®æ·å²ï¼Œä»–們就無法 輕鬆地å”作；如果您é‡å¯«äº†å…¶ä»–開發人員拉入他們å˜å„²åº«çš„æ·å²ï¼Œæ‚¨å°‡ä½¿é€™äº›é–‹ç™¼ -äººå“¡çš„ç”Ÿæ´»æ›´åŠ å›°é›£ã€‚å› æ¤ï¼Œé€™è£¡æœ‰ä¸€å€‹ç°¡å–®çš„經驗法則：被導出到其他地方的æ·å² +äººå“¡çš„ç”Ÿæ´»æ›´åŠ å›°é›£ã€‚å› æ¤ï¼Œé€™è£æœ‰ä¸€å€‹ç°¡å–®çš„經驗法則：被導出到其他地方的æ·å² 在æ¤å¾Œé€šå¸¸è¢«èªçˆ²æ˜¯ä¸å¯è®Šçš„。 -å› æ¤ï¼Œä¸€æ—¦å°‡ä¸€çµ„更改推é€åˆ°å…¬é–‹å¯ç”¨çš„伺æœå™¨ä¸Šï¼Œå°±ä¸æ‡‰è©²é‡å¯«é€™äº›æ›´æ”¹ã€‚如果您 +å› æ¤ï¼Œä¸€æ—¦å°‡ä¸€çµ„更改推é€åˆ°å…¬é–‹å¯ç”¨çš„æœå‹™å™¨ä¸Šï¼Œå°±ä¸æ‡‰è©²é‡å¯«é€™äº›æ›´æ”¹ã€‚如果您 嘗試強制進行無法快進åˆä½µçš„更改（å³ä¸å…±äº«åŒä¸€æ·å²è¨˜éŒ„的更改），Git將嘗試強制 執行æ¤è¦å‰‡ã€‚這å¯èƒ½è¦†è“‹æª¢æŸ¥ï¼Œæœ‰æ™‚甚至需è¦é‡å¯«å°Žå‡ºçš„樹。在樹之間移動變更集以 é¿å…linux-nextä¸çš„è¡çªå°±æ˜¯ä¸€å€‹ä¾‹å。但這種行爲應該是罕見的。這就是爲什麼 @@ -86,9 +86,9 @@ Gitæ供了一些強大的工具，å¯ä»¥è®“您é‡å¯«é–‹ç™¼æ·å²ã€‚一個ä¸æ– å°æ–¼ä¸€å€‹ç§æœ‰çš„分支，rebasing å¯èƒ½æ˜¯ä¸€å€‹å¾ˆå®¹æ˜“跟上å¦ä¸€æ£µæ¨¹çš„方法，但是一旦 一棵樹被導出到外界，rebasingå°±ä¸å¯å–了。一旦發生這種情æ³ï¼Œå°±å¿…é ˆé€²è¡Œå®Œå…¨ åˆä½µï¼ˆmerge）。åˆä½µæœ‰æ™‚是很有æ„義的，但是éŽæ–¼é »ç¹çš„åˆä½µæœƒä¸å¿…è¦åœ°æ“¾äº‚æ·å²ã€‚ -在這種情æ³ä¸‹å»ºè°çš„åšæ³•æ˜¯ä¸è¦é »ç¹åˆä½µï¼Œé€šå¸¸åªåœ¨ç‰¹å®šçš„發布點（如主線-rc發布） +在這種情æ³ä¸‹å»ºè°çš„åšæ³•æ˜¯ä¸è¦é »ç¹åˆä½µï¼Œé€šå¸¸åªåœ¨ç‰¹å®šçš„發佈點（如主線-rc發佈） åˆä½µã€‚如果您å°ç‰¹å®šçš„更改感到緊張，則å¯ä»¥å§‹çµ‚在ç§æœ‰åˆ†æ”¯ä¸åŸ·è¡Œæ¸¬è©¦åˆä½µã€‚在 -這種情æ³ä¸‹ï¼Œgit「rerereã€å·¥å…·å¾ˆæœ‰ç”¨ï¼›å®ƒèƒ½è¨˜ä½åˆä½µè¡çªæ˜¯å¦‚何解決的，這樣您 +這種情æ³ä¸‹ï¼Œgit“rerereâ€å·¥å…·å¾ˆæœ‰ç”¨ï¼›å®ƒèƒ½è¨˜ä½åˆä½µè¡çªæ˜¯å¦‚何解決的，這樣您 å°±ä¸å¿…é‡è¤‡ç›¸åŒçš„工作。 關於Git這樣的工具的一個最大的å覆抱怨是：補ä¸å¾žä¸€å€‹å˜å„²åº«åˆ°å¦ä¸€å€‹å˜å„²åº«çš„ @@ -98,36 +98,36 @@ Gitæ供了一些強大的工具，å¯ä»¥è®“您é‡å¯«é–‹ç™¼æ·å²ã€‚一個ä¸æ– :: - ä½ å¯ä»¥çµ¦æˆ‘發補ä¸ï¼Œä½†ç•¶æˆ‘å¾žä½ é‚£è£¡æ‹‰å–一個Git補ä¸æ™‚，我需è¦çŸ¥é“ä½ æ¸…æ¥š + ä½ å¯ä»¥çµ¦æˆ‘發補ä¸ï¼Œä½†ç•¶æˆ‘å¾žä½ é‚£è£æ‹‰å–一個Git補ä¸æ™‚，我需è¦çŸ¥é“ä½ æ¸…æ¥š 自己在åšä»€éº¼ï¼Œæˆ‘需è¦èƒ½å¤ 相信事情而 *無需* 手動檢查æ¯å€‹å–®ç¨çš„更改。 （http://lwn.net/Articles/224135/）。 -爲了é¿å…這種情æ³ï¼Œè«‹ç¢ºä¿çµ¦å®šåˆ†æ”¯ä¸çš„所有補ä¸éƒ½èˆ‡ç›¸é—œä¸»é¡Œç·Šå¯†ç›¸é—œï¼›ã€Œé©…å‹•ç¨‹åº -修復ã€åˆ†æ”¯ä¸æ‡‰æ›´æ”¹æ ¸å¿ƒå…§å˜ç®¡ç†ä»£ç¢¼ã€‚而且，最é‡è¦çš„是，ä¸è¦ä½¿ç”¨Gitæ¨¹ä¾†ç¹žéŽ -審查éŽç¨‹ã€‚ä¸æ™‚的將樹的摘è¦ç™¼å¸ƒåˆ°ç›¸é—œçš„列表ä¸ï¼Œåœ¨åˆé©æ™‚候請求linux-nextä¸ +爲了é¿å…這種情æ³ï¼Œè«‹ç¢ºä¿çµ¦å®šåˆ†æ”¯ä¸çš„所有補ä¸éƒ½èˆ‡ç›¸é—œä¸»é¡Œç·Šå¯†ç›¸é—œï¼›â€œé©…å‹•ç¨‹åº +修復â€åˆ†æ”¯ä¸æ‡‰æ›´æ”¹æ ¸å¿ƒå…§å˜ç®¡ç†ä»£ç¢¼ã€‚而且，最é‡è¦çš„是，ä¸è¦ä½¿ç”¨Gitæ¨¹ä¾†ç¹žéŽ +審查éŽç¨‹ã€‚ä¸æ™‚的將樹的摘è¦ç™¼ä½ˆåˆ°ç›¸é—œçš„列表ä¸ï¼Œåœ¨åˆé©æ™‚候請求linux-nextä¸ åŒ…å«è©²æ¨¹ã€‚ 如果其他人開始發é€è£œä¸ä»¥åŒ…å«åˆ°æ‚¨çš„樹ä¸ï¼Œä¸è¦å¿˜è¨˜å¯©é–±å®ƒå€‘。還è¦ç¢ºä¿æ‚¨ç¶è·æ£ç¢º -的作者信æ¯ï¼› git 「amã€å·¥å…·åœ¨é€™æ–¹é¢åšå¾—最好，但是如果補ä¸é€šéŽç¬¬ä¸‰æ–¹è½‰ç™¼çµ¦æ‚¨ï¼Œ -您å¯èƒ½éœ€è¦åœ¨è£œä¸ä¸æ·»åŠ 「From:ã€è¡Œã€‚ +的作者信æ¯ï¼› git “amâ€å·¥å…·åœ¨é€™æ–¹é¢åšå¾—最好，但是如果補ä¸é€šéŽç¬¬ä¸‰æ–¹è½‰ç™¼çµ¦æ‚¨ï¼Œ +您å¯èƒ½éœ€è¦åœ¨è£œä¸ä¸æ·»åŠ “From:â€è¡Œã€‚ 請求拉å–時，請務必æ供所有相關信æ¯ï¼šæ¨¹çš„ä½ç½®ã€è¦æ‹‰å–的分支以åŠæ‹‰å–將導致的 æ›´æ”¹ã€‚åœ¨é€™æ–¹é¢ git request-pull 命令éžå¸¸æœ‰ç”¨ï¼›å®ƒå°‡æŒ‰ç…§å…¶ä»–開發人員所期望的 -æ ¼å¼åŒ–請求，並檢查以確ä¿æ‚¨å·²è¨˜å¾—將這些更改推é€åˆ°å…¬å…±ä¼ºæœå™¨ã€‚ +æ ¼å¼åŒ–請求，並檢查以確ä¿æ‚¨å·²è¨˜å¾—將這些更改推é€åˆ°å…¬å…±æœå‹™å™¨ã€‚ å¯©é–±è£œä¸ -------- -一些讀者顯然會åå°å°‡æœ¬ç¯€èˆ‡ã€Œé«˜ç´šä¸»é¡Œã€æ”¾åœ¨ä¸€èµ·ï¼Œå› 爲å³ä½¿æ˜¯å‰›é–‹å§‹çš„å…§æ ¸é–‹ç™¼äººå“¡ -也應該審閱補ä¸ã€‚當然，沒有比查看其他人發布的代碼更好的方法來å¸ç¿’å¦‚ä½•åœ¨å…§æ ¸ç’°å¢ƒ +一些讀者顯然會åå°å°‡æœ¬ç¯€èˆ‡â€œé«˜ç´šä¸»é¡Œâ€æ”¾åœ¨ä¸€èµ·ï¼Œå› 爲å³ä½¿æ˜¯å‰›é–‹å§‹çš„å…§æ ¸é–‹ç™¼äººå“¡ +也應該審閱補ä¸ã€‚當然，沒有比查看其他人發佈的代碼更好的方法來å¸ç¿’å¦‚ä½•åœ¨å…§æ ¸ç’°å¢ƒ ä¸ç·¨ç¨‹äº†ã€‚æ¤å¤–，審閱者永é ä¾›ä¸æ‡‰æ±‚；通éŽå¯©é–±ä»£ç¢¼ï¼Œæ‚¨å¯ä»¥å°æ•´å€‹æµç¨‹åšå‡ºé‡å¤§è²¢ç»ã€‚ 審查代碼å¯èƒ½æ˜¯ä¸€å‰¯ä»¤äººç”Ÿç•çš„圖景，特別是å°ä¸€å€‹æ–°çš„å…§æ ¸é–‹ç™¼äººå“¡ä¾†èªªï¼Œä»–å€‘ -å¯èƒ½æœƒå°å…¬é–‹è©¢å•ä»£ç¢¼æ„Ÿåˆ°ç·Šå¼µï¼Œè€Œé€™äº›ä»£ç¢¼æ˜¯ç”±é‚£äº›æœ‰æ›´å¤šç¶“驗的人發布的。ä¸éŽï¼Œ +å¯èƒ½æœƒå°å…¬é–‹è©¢å•ä»£ç¢¼æ„Ÿåˆ°ç·Šå¼µï¼Œè€Œé€™äº›ä»£ç¢¼æ˜¯ç”±é‚£äº›æœ‰æ›´å¤šç¶“驗的人發佈的。ä¸éŽï¼Œ å³ä½¿æ˜¯æœ€æœ‰ç¶“驗的開發人員編寫的代碼也å¯ä»¥å¾—到改進。也許å°ï¼ˆæ‰€æœ‰ï¼‰å¯©é–±è€…最好 -的建è°æ˜¯ï¼šæŠŠå¯©é–±è©•è«–當æˆå•é¡Œè€Œä¸æ˜¯æ‰¹è©•ã€‚è©¢å•ã€Œåœ¨é€™æ¢è·¯å¾‘ä¸å¦‚何釋放鎖？〠-總是比說「這裡的鎖是錯誤的ã€æ›´å¥½ã€‚ +的建è°æ˜¯ï¼šæŠŠå¯©é–±è©•è«–當æˆå•é¡Œè€Œä¸æ˜¯æ‰¹è©•ã€‚è©¢å•â€œåœ¨é€™æ¢è·¯å¾‘ä¸å¦‚何釋放鎖？†+總是比說“這è£çš„鎖是錯誤的â€æ›´å¥½ã€‚ ä¸åŒçš„開發人員將從ä¸åŒçš„角度審查代碼。部分人會主è¦é—œæ³¨ä»£ç¢¼é¢¨æ ¼ä»¥åŠä»£ç¢¼è¡Œæ˜¯ å¦æœ‰å°¾éš¨ç©ºæ ¼ã€‚其他人會主è¦é—œæ³¨è£œä¸ä½œçˆ²ä¸€å€‹æ•´é«”實ç¾çš„變更是å¦å°å…§æ ¸æœ‰å¥½è™•ã€‚ diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst index 1207991d1570..a0c00741f912 100644 --- a/Documentation/translations/zh_TW/process/8.Conclusion.rst +++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst @@ -17,13 +17,13 @@ æ›´å¤šä¿¡æ¯ ======== -關於Linuxå…§æ ¸é–‹ç™¼å’Œç›¸é—œä¸»é¡Œçš„ä¿¡æ¯ä¾†æºå¾ˆå¤šã€‚é¦–å…ˆæ˜¯åœ¨å…§æ ¸åŽŸå§‹ç¢¼åˆ†ç™¼ä¸æ‰¾åˆ°çš„ +關於Linuxå…§æ ¸é–‹ç™¼å’Œç›¸é—œä¸»é¡Œçš„ä¿¡æ¯ä¾†æºå¾ˆå¤šã€‚é¦–å…ˆæ˜¯åœ¨å…§æ ¸æºä»£ç¢¼åˆ†ç™¼ä¸æ‰¾åˆ°çš„ æ–‡æª”ç›®éŒ„ã€‚é ‚ç´š -:ref:`Documentation/translations/zh_TW/process/howto.rst <tw_process_howto>` +:ref:`Documentation/translations/zh_CN/process/howto.rst <tw_process_howto>` 文件是一個é‡è¦çš„起點； -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <tw_submittingpatches>` ä¹Ÿæ˜¯æ‰€æœ‰å…§æ ¸é–‹ç™¼äººå“¡éƒ½æ‡‰è©²é–±è®€çš„å…§å®¹ã€‚è¨±å¤šå…§éƒ¨å…§æ ¸API都是使用kerneldoc機制 -記錄的；「make htmldocsã€æˆ–「make pdfdocsã€å¯ç”¨æ–¼ä»¥HTML或PDFæ ¼å¼ç”Ÿæˆé€™äº›æ–‡æª” +記錄的；“make htmldocsâ€æˆ–“make pdfdocsâ€å¯ç”¨æ–¼ä»¥HTML或PDFæ ¼å¼ç”Ÿæˆé€™äº›æ–‡æª” （儘管æŸäº›ç™¼è¡Œç‰ˆæ供的tex版本會é‡åˆ°å…§éƒ¨é™åˆ¶ï¼Œç„¡æ³•æ£ç¢ºè™•ç†æ–‡æª”）。 ä¸åŒçš„網站在å„å€‹ç´°ç¯€å±¤æ¬¡ä¸Šè¨Žè«–å…§æ ¸é–‹ç™¼ã€‚æœ¬æ–‡ä½œè€…æƒ³è¬™è™›åœ°å»ºè°ç”¨ https://lwn.net/ @@ -35,7 +35,7 @@ https://kernelnewbies.org/ -當然，也ä¸æ‡‰è©²å¿˜è¨˜ https://kernel.org/ ï¼Œé€™æ˜¯å…§æ ¸ç™¼å¸ƒä¿¡æ¯çš„最終ä½ç½®ã€‚ +當然，也ä¸æ‡‰è©²å¿˜è¨˜ https://kernel.org/ ï¼Œé€™æ˜¯å…§æ ¸ç™¼ä½ˆä¿¡æ¯çš„最終ä½ç½®ã€‚ é—œæ–¼å…§æ ¸é–‹ç™¼æœ‰å¾ˆå¤šæ›¸ï¼š @@ -47,7 +47,7 @@ 《深入ç†è§£Linuxå…§æ ¸ã€‹(Daniel Bovetå’ŒMarco Cesati） 然而，所有這些書都有一個共åŒçš„缺點：它們上架時就往往有些éŽæ™‚，而且已經上架 -一段時間了。ä¸éŽï¼Œåœ¨é‚£è£¡é‚„是å¯ä»¥æ‰¾åˆ°ç›¸ç•¶å¤šçš„好信æ¯ã€‚ +一段時間了。ä¸éŽï¼Œåœ¨é‚£è£é‚„是å¯ä»¥æ‰¾åˆ°ç›¸ç•¶å¤šçš„好信æ¯ã€‚ 有關git的文檔，請訪å•ï¼š @@ -61,7 +61,7 @@ ç¥è³€æ‰€æœ‰é€šéŽé€™ç¯‡å†—é•·çš„æ–‡æª”çš„äººã€‚å¸Œæœ›å®ƒèƒ½å¤ å¹«åŠ©æ‚¨ç†è§£Linuxå…§æ ¸æ˜¯å¦‚ä½•é–‹ç™¼çš„ï¼Œ 以åŠæ‚¨å¦‚何åƒèˆ‡é€™å€‹éŽç¨‹ã€‚ -最後，é‡è¦çš„是åƒèˆ‡ã€‚任何開æºè»Ÿé«”é …ç›®éƒ½ä¸æœƒè¶…éŽå…¶è²¢ç»è€…投入其ä¸çš„總和。Linux +最後，é‡è¦çš„是åƒèˆ‡ã€‚任何開æºè»Ÿä»¶é …目都ä¸æœƒè¶…éŽå…¶è²¢ç»è€…投入其ä¸çš„總和。Linux å…§æ ¸çš„ç™¼å±•é€Ÿåº¦å’Œä»¥å‰ä¸€æ¨£å¿«ï¼Œå› 爲它得到了大é‡é–‹ç™¼äººå“¡çš„幫助，他們都在努力使它 è®Šå¾—æ›´å¥½ã€‚å…§æ ¸æ˜¯ä¸€å€‹æœ€æˆåŠŸçš„例å，說明了當æˆåƒä¸Šè¬çš„人爲了一個共åŒçš„目標一起 工作時，å¯ä»¥åšå‡ºä»€éº¼ã€‚ diff --git a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst index 920bb0f36974..48df918000e9 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst @@ -8,34 +8,34 @@ .. _tw_code_of_conduct_interpretation: -Linuxå…§æ ¸è²¢ç»è€…契約行為準則解釋 +Linuxå…§æ ¸è²¢ç»è€…契約行爲準則解釋 =============================== :ref:`tw_code_of_conduct` 準則是一個通用文檔，旨在爲幾乎所有開æºç¤¾å€æ供一套è¦å‰‡ã€‚ æ¯å€‹é–‹æºç¤¾å€éƒ½æ˜¯ç¨ä¸€ç„¡äºŒçš„，Linuxå…§æ ¸ä¹Ÿä¸ä¾‹å¤–ã€‚å› æ¤ï¼Œæœ¬æ–‡æ述了Linuxå…§æ ¸ç¤¾å€ä¸ -如何解釋它。我們也ä¸å¸Œæœ›é€™ç¨®è§£é‡‹éš¨è‘—時間的推移是éœæ…‹çš„ï¼Œä¸¦å°‡æ ¹æ“šéœ€è¦é€²è¡Œèª¿æ•´ã€‚ +如何解釋它。我們也ä¸å¸Œæœ›é€™ç¨®è§£é‡‹éš¨ç€æ™‚間的推移是éœæ…‹çš„ï¼Œä¸¦å°‡æ ¹æ“šéœ€è¦é€²è¡Œèª¿æ•´ã€‚ -與開發軟體的「傳統ã€æ–¹æ³•ç›¸æ¯”，Linuxå…§æ ¸é–‹ç™¼å·¥ä½œæ˜¯ä¸€å€‹éžå¸¸å€‹äººåŒ–çš„éŽç¨‹ã€‚ä½ çš„è²¢ç» +與開發軟件的“傳統â€æ–¹æ³•ç›¸æ¯”，Linuxå…§æ ¸é–‹ç™¼å·¥ä½œæ˜¯ä¸€å€‹éžå¸¸å€‹äººåŒ–çš„éŽç¨‹ã€‚ä½ çš„è²¢ç» å’ŒèƒŒå¾Œçš„æƒ³æ³•å°‡è¢«ä»”ç´°å¯©æŸ¥ï¼Œå¾€å¾€å°Žè‡´æ‰¹åˆ¤å’Œæ‰¹è©•ã€‚å¯©æŸ¥å°‡å¹¾ä¹Žç¸½æ˜¯éœ€è¦æ”¹é€²ï¼Œææ–™æ‰ èƒ½åŒ…æ‹¬åœ¨å…§æ ¸ä¸ã€‚è¦çŸ¥é“é€™æ˜¯å› çˆ²æ‰€æœ‰ç›¸é—œäººå“¡éƒ½å¸Œæœ›çœ‹åˆ°Linuxæ•´é«”æˆåŠŸçš„最佳解決方 -案。這個開發éŽç¨‹å·²ç¶“被è‰æ˜Žå¯ä»¥å‰µå»ºæœ‰å²ä»¥ä¾†æœ€å¥å£¯çš„作æ¥ç³»çµ±å…§æ ¸ï¼Œæˆ‘們ä¸æƒ³åšä»»ä½• +案。這個開發éŽç¨‹å·²ç¶“被è‰æ˜Žå¯ä»¥å‰µå»ºæœ‰å²ä»¥ä¾†æœ€å¥å£¯çš„æ“ä½œç³»çµ±å…§æ ¸ï¼Œæˆ‘å€‘ä¸æƒ³åšä»»ä½• 事情來導致æ交質é‡å’Œæœ€çµ‚çµæžœçš„下é™ã€‚ ç¶è·è€… ------ -行為準則多次使用「ç¶è·è€…ã€ä¸€è©žã€‚åœ¨å…§æ ¸ç¤¾å€ä¸ï¼Œã€Œç¶è·è€…ã€æ˜¯è² 責å系統ã€é©…動程åºæˆ– -æ–‡ä»¶çš„ä»»ä½•äººï¼Œä¸¦åœ¨å…§æ ¸åŽŸå§‹ç¢¼æ¨¹çš„ç¶è·è€…文件ä¸åˆ—出。 +行爲準則多次使用“ç¶è·è€…â€ä¸€è©žã€‚åœ¨å…§æ ¸ç¤¾å€ä¸ï¼Œâ€œç¶è·è€…â€æ˜¯è² 責å系統ã€é©…動程åºæˆ– +æ–‡ä»¶çš„ä»»ä½•äººï¼Œä¸¦åœ¨å…§æ ¸æºä»£ç¢¼æ¨¹çš„ç¶è·è€…文件ä¸åˆ—出。 責任 ---- -《行為準則》æ到了ç¶è·äººå“¡çš„權利和責任，這需è¦é€²ä¸€æ¥æ¾„清。 +《行爲準則》æ到了ç¶è·äººå“¡çš„權利和責任，這需è¦é€²ä¸€æ¥æ¾„清。 首先，最é‡è¦çš„是，有一個åˆç†çš„期望是由ç¶è·äººå“¡é€šéŽå¯¦ä¾‹ä¾†é ˜å°Žã€‚ 也就是說，我們的社å€æ˜¯å»£é—Šçš„，å°ç¶è·è€…沒有新的è¦æ±‚，他們單方é¢è™•ç†å…¶ä»–人在 -他們活èºçš„社å€çš„行爲。這一責任由我們所有人承擔，最終《行為準則》記錄了最終的 +他們活èºçš„社å€çš„行爲。這一責任由我們所有人承擔，最終《行爲準則》記錄了最終的 上訴路徑，以防有關行爲å•é¡Œçš„å•é¡Œæ‡¸è€Œæœªæ±ºã€‚ ç¶è·äººå“¡æ‡‰è©²é¡˜æ„在出ç¾å•é¡Œæ™‚æ供幫助，並在需è¦æ™‚與社å€ä¸çš„其他人åˆä½œã€‚如果您 @@ -43,10 +43,10 @@ Linuxå…§æ ¸è²¢ç»è€…契約行為準則解釋 除éžæ‚¨é¡˜æ„，å¦å‰‡ä¸æœƒå°‡å…¶è¦–爲é•è¦å ±å‘Šã€‚如果您ä¸ç¢ºå®šæ˜¯å¦è©²è¯ç¹«TAB æˆ–ä»»ä½•å…¶ä»–ç¶ è·äººå“¡ï¼Œè«‹è¯ç¹«æˆ‘們的è¡çªèª¿è§£äºº Mishi Choudhary <mishi@linux.com>。 -最後，「善待å°æ–¹ã€æ‰æ˜¯æ¯å€‹äººçš„最終目標。我們知é“æ¯å€‹äººéƒ½æ˜¯äººï¼Œæœ‰æ™‚我們都會失敗， -但我們所有人的首è¦ç›®æ¨™æ‡‰è©²æ˜¯åŠªåŠ›å‹å¥½åœ°è§£æ±ºå•é¡Œã€‚執行行為準則將是最後的é¸æ“‡ã€‚ +最後，“善待å°æ–¹â€çº”是æ¯å€‹äººçš„最終目標。我們知é“æ¯å€‹äººéƒ½æ˜¯äººï¼Œæœ‰æ™‚我們都會失敗， +但我們所有人的首è¦ç›®æ¨™æ‡‰è©²æ˜¯åŠªåŠ›å‹å¥½åœ°è§£æ±ºå•é¡Œã€‚執行行爲準則將是最後的é¸æ“‡ã€‚ -我們的目標是創建一個強大的ã€æŠ€è¡“先進的作æ¥ç³»çµ±ï¼Œä»¥åŠæ‰€æ¶‰åŠçš„技術複雜性，這自 +我們的目標是創建一個強大的ã€æŠ€è¡“先進的æ“作系統，以åŠæ‰€æ¶‰åŠçš„技術複雜性，這自 然需è¦å°ˆæ¥çŸ¥è˜å’Œæ±ºç–。 所需的專æ¥çŸ¥è˜å› è²¢ç»é ˜åŸŸè€Œç•°ã€‚它主è¦ç”±ä¸Šä¸‹æ–‡å’ŒæŠ€è¡“複雜性決定，其次由貢ç»è€…å’Œ @@ -55,58 +55,58 @@ Linuxå…§æ ¸è²¢ç»è€…契約行為準則解釋 專家的期望和決ç–都è¦ç¶“éŽè¨Žè«–，但在最後，爲了å–å¾—é€²å±•ï¼Œå¿…é ˆèƒ½å¤ åšå‡ºæ±ºç–。這一 特權掌æ¡åœ¨ç¶è·äººå“¡å’Œé …ç›®é ˜å°Žçš„æ‰‹ä¸ï¼Œé 計將善æ„使用。 -å› æ¤ï¼Œè¨å®šå°ˆæ¥çŸ¥è˜æœŸæœ›ã€ä½œå‡ºæ±ºå®šå’Œæ‹’絕ä¸é©ç•¶çš„è²¢ç»ä¸è¢«è¦–爲é•å行為準則。 +å› æ¤ï¼Œè¨å®šå°ˆæ¥çŸ¥è˜æœŸæœ›ã€ä½œå‡ºæ±ºå®šå’Œæ‹’絕ä¸é©ç•¶çš„è²¢ç»ä¸è¢«è¦–爲é•å行爲準則。 雖然ç¶è·äººå“¡ä¸€èˆ¬éƒ½æ¡è¿Žæ–°ä¾†è€…，但他們幫助（新）貢ç»è€…å…‹æœéšœç¤™çš„能力有é™ï¼Œå› æ¤ -ä»–å€‘å¿…é ˆç¢ºå®šå„ªå…ˆäº‹é …ã€‚é€™ä¹Ÿä¸æ‡‰è¢«è¦–爲é•åäº†è¡Œç‚ºæº–å‰‡ã€‚å…§æ ¸ç¤¾å€æ„è˜åˆ°é€™ä¸€é»žï¼Œä¸¦ +ä»–å€‘å¿…é ˆç¢ºå®šå„ªå…ˆäº‹é …ã€‚é€™ä¹Ÿä¸æ‡‰è¢«è¦–爲é•åäº†è¡Œçˆ²æº–å‰‡ã€‚å…§æ ¸ç¤¾å€æ„è˜åˆ°é€™ä¸€é»žï¼Œä¸¦ 以å„種形å¼æ供入門級節目，如 kernelnewbies.org 。 ç¯„åœ ---- -Linuxå…§æ ¸ç¤¾å€ä¸»è¦åœ¨ä¸€çµ„公共電å郵件列表上進行交互，這些列表分布在由多個ä¸åŒ -å…¬å¸æˆ–個人控制的多個ä¸åŒä¼ºæœå™¨ä¸Šã€‚æ‰€æœ‰é€™äº›åˆ—è¡¨éƒ½åœ¨å…§æ ¸åŽŸå§‹ç¢¼æ¨¹ä¸çš„ +Linuxå…§æ ¸ç¤¾å€ä¸»è¦åœ¨ä¸€çµ„公共電å郵件列表上進行交互，這些列表分佈在由多個ä¸åŒ +å…¬å¸æˆ–個人控制的多個ä¸åŒæœå‹™å™¨ä¸Šã€‚æ‰€æœ‰é€™äº›åˆ—è¡¨éƒ½åœ¨å…§æ ¸æºä»£ç¢¼æ¨¹ä¸çš„ MAINTAINERS 文件ä¸å®šç¾©ã€‚發é€åˆ°é€™äº›éƒµä»¶åˆ—表的任何電å郵件都被視爲包å«åœ¨è¡Œçˆ² 準則ä¸ã€‚ 使用 kernel.org bugzilla和其他å系統bugzilla 或bug跟蹤工具的開發人員應該éµå¾ª -行為準則的指導原則。Linuxå…§æ ¸ç¤¾å€æ²’有「官方ã€é …目電å郵件地å€æˆ–「官方ã€ç¤¾äº¤åª’é«” -地å€ã€‚使用kernel.orgé›»åéƒµä»¶å¸³æˆ¶åŸ·è¡Œçš„ä»»ä½•æ´»å‹•å¿…é ˆéµå¾ªçˆ²kernel.org發布的行爲 +行爲準則的指導原則。Linuxå…§æ ¸ç¤¾å€æ²’有“官方â€é …目電å郵件地å€æˆ–“官方â€ç¤¾äº¤åª’é«” +地å€ã€‚使用kernel.orgé›»åéƒµä»¶å¸³æˆ¶åŸ·è¡Œçš„ä»»ä½•æ´»å‹•å¿…é ˆéµå¾ªçˆ²kernel.org發佈的行爲 準則，就åƒä»»ä½•ä½¿ç”¨å…¬å¸é›»åéƒµä»¶å¸³æˆ¶çš„å€‹äººå¿…é ˆéµå¾ªè©²å…¬å¸çš„特定è¦å‰‡ä¸€æ¨£ã€‚ -行為準則並ä¸ç¦æ¢åœ¨éƒµä»¶åˆ—表消æ¯ã€å…§æ ¸æ›´æ”¹æ—¥èªŒæ¶ˆæ¯æˆ–代碼注釋ä¸ç¹¼çºŒåŒ…å«å稱〠+行爲準則並ä¸ç¦æ¢åœ¨éƒµä»¶åˆ—表消æ¯ã€å…§æ ¸æ›´æ”¹æ—¥èªŒæ¶ˆæ¯æˆ–代碼註釋ä¸ç¹¼çºŒåŒ…å«å稱〠電å郵件地å€å’Œç›¸é—œæ³¨é‡‹ã€‚ -其他論壇ä¸çš„互動包括在é©ç”¨æ–¼ä¸Šè¿°è«–壇的任何è¦å‰‡ä¸ï¼Œé€šå¸¸ä¸åŒ…括在行為準則ä¸ã€‚ +其他論壇ä¸çš„互動包括在é©ç”¨æ–¼ä¸Šè¿°è«–壇的任何è¦å‰‡ä¸ï¼Œé€šå¸¸ä¸åŒ…括在行爲準則ä¸ã€‚ 除了在極端情æ³ä¸‹å¯è€ƒæ…®çš„例外情æ³ã€‚ -æäº¤çµ¦å…§æ ¸çš„è²¢ç»æ‡‰è©²ä½¿ç”¨é©ç•¶çš„語言。在行為準則之å‰å·²ç¶“å˜åœ¨çš„內容ç¾åœ¨ä¸æœƒè¢« +æäº¤çµ¦å…§æ ¸çš„è²¢ç»æ‡‰è©²ä½¿ç”¨é©ç•¶çš„語言。在行爲準則之å‰å·²ç¶“å˜åœ¨çš„內容ç¾åœ¨ä¸æœƒè¢« 視爲é•å。然而，ä¸é©ç•¶çš„語言å¯ä»¥è¢«è¦–爲一個bug；如果任何相關方æ交補ä¸ï¼Œ 這樣的bug將被更快地修復。當å‰å±¬æ–¼ç”¨æˆ¶/å…§æ ¸API的一部分的表é”å¼ï¼Œæˆ–者åæ˜ å·² -發布標準或è¦ç¯„ä¸ä½¿ç”¨çš„術語的表é”å¼ï¼Œä¸è¢«è¦–爲bug。 +發佈標準或è¦ç¯„ä¸ä½¿ç”¨çš„術語的表é”å¼ï¼Œä¸è¢«è¦–爲bug。 執行 ---- -行為準則ä¸åˆ—出的地å€å±¬æ–¼è¡Œç‚ºæº–則委員會。https://kernel.org/code-of-conduct.html +行爲準則ä¸åˆ—出的地å€å±¬æ–¼è¡Œçˆ²æº–則委員會。https://kernel.org/code-of-conduct.html 列出了在任何給定時間接收這些電å郵件的確切æˆå“¡ã€‚æˆå“¡ä¸èƒ½è¨ªå•åœ¨åŠ å…¥å§”å“¡æœƒä¹‹å‰ æˆ–é›¢é–‹å§”å“¡æœƒä¹‹å¾Œæ‰€åšçš„å ±å‘Šã€‚ -最åˆçš„行為準則委員會由TAB的志願者以åŠä½œçˆ²ä¸ç«‹ç¬¬ä¸‰æ–¹çš„å°ˆæ¥èª¿è§£äººçµ„æˆã€‚委員會 +最åˆçš„行爲準則委員會由TAB的志願者以åŠä½œçˆ²ä¸ç«‹ç¬¬ä¸‰æ–¹çš„å°ˆæ¥èª¿è§£äººçµ„æˆã€‚委員會 的首è¦ä»»å‹™æ˜¯å»ºç«‹æ–‡ä»¶åŒ–çš„æµç¨‹ï¼Œä¸¦å°‡å…¶å…¬é–‹ã€‚ å¦‚æžœå ±å‘Šäººä¸å¸Œæœ›å°‡æ•´å€‹å§”員會ç´å…¥æŠ•è¨´æˆ–關切，å¯ç›´æŽ¥è¯ç¹«å§”員會的任何æˆå“¡ï¼ŒåŒ…括 調解人。 -è¡Œç‚ºæº–å‰‡å§”å“¡æœƒæ ¹æ“šæµç¨‹å¯©æŸ¥æ¡ˆä¾‹ï¼ˆè¦‹ä¸Šæ–‡ï¼‰ï¼Œä¸¦æ ¹æ“šéœ€è¦å’Œé©ç•¶èˆ‡TABå”商，例如請求 +è¡Œçˆ²æº–å‰‡å§”å“¡æœƒæ ¹æ“šæµç¨‹å¯©æŸ¥æ¡ˆä¾‹ï¼ˆè¦‹ä¸Šæ–‡ï¼‰ï¼Œä¸¦æ ¹æ“šéœ€è¦å’Œé©ç•¶èˆ‡TABå”商，例如請求 å’ŒæŽ¥æ”¶æœ‰é—œå…§æ ¸ç¤¾å€çš„ä¿¡æ¯ã€‚ 委員會åšå‡ºçš„任何決定都將æ交到表ä¸ï¼Œä»¥ä¾¿åœ¨å¿…è¦æ™‚與相關ç¶è·äººå“¡ä¸€èµ·åŸ·è¡Œã€‚行爲 準則委員會的決定å¯ä»¥é€šéŽä¸‰åˆ†ä¹‹äºŒçš„投票推翻。 -æ¯å£åº¦ï¼Œè¡Œç‚ºæº–則委員會和標籤將æä¾›ä¸€ä»½å ±å‘Šï¼Œæ¦‚è¿°è¡Œç‚ºæº–å‰‡å§”å“¡æœƒæ”¶åˆ°çš„åŒ¿åå ±å‘Š +æ¯å£åº¦ï¼Œè¡Œçˆ²æº–則委員會和標籤將æä¾›ä¸€ä»½å ±å‘Šï¼Œæ¦‚è¿°è¡Œçˆ²æº–å‰‡å§”å“¡æœƒæ”¶åˆ°çš„åŒ¿åå ±å‘Š åŠå…¶ç‹€æ…‹ï¼Œä»¥åŠä»»ä½•å¦æ±ºæ±ºå®šçš„細節，包括完整和å¯è˜åˆ¥çš„投票細節。 -我們希望在啓動期之後爲行為準則委員會人員é…備建立一個ä¸åŒçš„æµç¨‹ã€‚發生æ¤æƒ…æ³æ™‚， +我們希望在啓動期之後爲行爲準則委員會人員é…備建立一個ä¸åŒçš„æµç¨‹ã€‚發生æ¤æƒ…æ³æ™‚， 將使用該信æ¯æ›´æ–°æ¤æ–‡æª”。 diff --git a/Documentation/translations/zh_TW/process/code-of-conduct.rst b/Documentation/translations/zh_TW/process/code-of-conduct.rst index e3087112f0bc..a7a31de03526 100644 --- a/Documentation/translations/zh_TW/process/code-of-conduct.rst +++ b/Documentation/translations/zh_TW/process/code-of-conduct.rst @@ -8,7 +8,7 @@ .. _tw_code_of_conduct: -è²¢ç»è€…契約行為準則 +è²¢ç»è€…契約行爲準則 ++++++++++++++++++ 我們的誓言 @@ -35,7 +35,7 @@ * 使用性æ„味的語言或æ„象以åŠä¸å—æ¡è¿Žçš„性注æ„或者更éŽåˆ†çš„行爲 * 煽動ã€ä¾®è¾±/貶æ評論以åŠå€‹äººæˆ–政治攻擊 * 公開或ç§ä¸‹é¨·æ“¾ -* 未經明確許å¯ï¼Œç™¼å¸ƒä»–人的ç§äººä¿¡æ¯ï¼Œå¦‚物ç†æˆ–é›»å地å€ã€‚ +* 未經明確許å¯ï¼Œç™¼ä½ˆä»–人的ç§äººä¿¡æ¯ï¼Œå¦‚物ç†æˆ–é›»å地å€ã€‚ * 在專æ¥å ´åˆè¢«åˆç†èªçˆ²ä¸é©ç•¶çš„其他行爲 我們的責任 @@ -44,29 +44,29 @@ ç¶è·äººå“¡è² 責澄清å¯æŽ¥å—行爲的標準，並應é‡å°ä»»ä½•ä¸å¯æŽ¥å—行爲採å–é©ç•¶å’Œå…¬å¹³çš„ ç³¾æ£æŽªæ–½ã€‚ -ç¶è·äººå“¡æœ‰æ¬Šå’Œè²¬ä»»åˆªé™¤ã€ç·¨è¼¯æˆ–拒絕與本行為準則ä¸ä¸€è‡´çš„è©•è«–ã€æ‰¿è«¾ã€ä»£ç¢¼ã€ +ç¶è·äººå“¡æœ‰æ¬Šå’Œè²¬ä»»åˆªé™¤ã€ç·¨è¼¯æˆ–拒絕與本行爲準則ä¸ä¸€è‡´çš„è©•è«–ã€æ‰¿è«¾ã€ä»£ç¢¼ã€ wiki編輯ã€å•é¡Œå’Œå…¶ä»–è²¢ç»ï¼Œæˆ–暫時或永久ç¦æ¢ä»»ä½•è²¢ç»è€…從事他們èªçˆ²ä¸é©ç•¶ã€ å¨è„…ã€å†’犯或有害的其他行爲。 ç¯„åœ ==== -ç•¶å€‹äººä»£è¡¨é …ç›®æˆ–å…¶ç¤¾å€æ™‚，本行為準則既é©ç”¨æ–¼é …目空間，也é©ç”¨æ–¼å…¬å…±ç©ºé–“。 +ç•¶å€‹äººä»£è¡¨é …ç›®æˆ–å…¶ç¤¾å€æ™‚，本行爲準則既é©ç”¨æ–¼é …目空間，也é©ç”¨æ–¼å…¬å…±ç©ºé–“。 ä»£è¡¨ä¸€å€‹é …ç›®æˆ–ç¤¾å€çš„例å包括使用一個æ£å¼çš„é …ç›®é›»å郵件地å€ï¼Œé€šéŽä¸€å€‹æ£å¼ -的社交媒體帳戶發布，或者在在線或離線事件ä¸æ“”ä»»æŒ‡å®šçš„ä»£è¡¨ã€‚é …ç›®ç¶è·äººå“¡å¯ä»¥ +的社交媒體帳戶發佈，或者在在線或離線事件ä¸æ“”ä»»æŒ‡å®šçš„ä»£è¡¨ã€‚é …ç›®ç¶è·äººå“¡å¯ä»¥ 進一æ¥å®šç¾©å’Œæ¾„æ¸…é …ç›®çš„è¡¨ç¤ºã€‚ 執行 ==== -如有濫用ã€é¨·æ“¾æˆ–其他ä¸å¯æŽ¥å—的行爲，å¯è¯ç¹«è¡Œç‚ºæº–則委員會<conduct@kernel.org>。 -所有投訴都將接å—審查和調查，並將得到必è¦å’Œé©ç•¶çš„ç”覆。行為準則委員會有義務 -å°äº‹ä»¶å ±å‘Šäººä¿å¯†ã€‚具體執行政ç–的進一æ¥ç´°ç¯€å¯å–®ç¨å…¬å¸ƒã€‚ +如有濫用ã€é¨·æ“¾æˆ–其他ä¸å¯æŽ¥å—的行爲，å¯è¯ç¹«è¡Œçˆ²æº–則委員會<conduct@kernel.org>。 +所有投訴都將接å—審查和調查，並將得到必è¦å’Œé©ç•¶çš„ç”覆。行爲準則委員會有義務 +å°äº‹ä»¶å ±å‘Šäººä¿å¯†ã€‚具體執行政ç–的進一æ¥ç´°ç¯€å¯å–®ç¨å…¬ä½ˆã€‚ æ¸å±¬ ==== -本行為準則改編自《貢ç»è€…契約》，版本1.4，å¯å¾ž +本行爲準則改編自《貢ç»è€…契約》，版本1.4，å¯å¾ž https://www.contributor-covenant.org/version/1/4/code-of-conduct.html ç²å–。 解釋 diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index 83862e4d3b64..5749363de421 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -2,42 +2,44 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` +:Original: Documentation/process/coding-style.rst .. _tw_codingstyle: -è¯è€…:: +:è¯è€…: + - 張樂 Zhang Le <r0bertz@gentoo.org> + - Andy Deng <theandy.deng@gmail.com> + - å³æƒ³æˆ <bobwxc@email.cn> - ä¸æ–‡ç‰ˆç¶è·è€…： 張樂 Zhang Le <r0bertz@gentoo.org> - ä¸æ–‡ç‰ˆç¿»è¯è€…： 張樂 Zhang Le <r0bertz@gentoo.org> - ä¸æ–‡ç‰ˆæ ¡è¯è€…： çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com> - wheelz <kernel.zeng@gmail.com> - 管æ—æ± Xudong Guan <xudong.guan@gmail.com> - Li Zefan <lizf@cn.fujitsu.com> - Wang Chen <wangchen@cn.fujitsu.com> - Hu Haowen <src.res.211@gmail.com> +:æ ¡è¯: + - çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com> + - wheelz <kernel.zeng@gmail.com> + - 管æ—æ± Xudong Guan <xudong.guan@gmail.com> + - Li Zefan <lizf@cn.fujitsu.com> + - Wang Chen <wangchen@cn.fujitsu.com> + - Hu Haowen <src.res.211@gmail.com> Linux å…§æ ¸ä»£ç¢¼é¢¨æ ¼ -========================= +================== 這是一個簡çŸçš„文檔，æ述了 linux å…§æ ¸çš„é¦–é¸ä»£ç¢¼é¢¨æ ¼ã€‚ä»£ç¢¼é¢¨æ ¼æ˜¯å› äººè€Œç•°çš„ï¼Œ 而且我ä¸é¡˜æ„æŠŠè‡ªå·±çš„è§€é»žå¼·åŠ çµ¦ä»»ä½•äººï¼Œä½†é€™å°±åƒæˆ‘去åšä»»ä½•äº‹æƒ…éƒ½å¿…é ˆéµå¾ªçš„原則 -那樣，我也希望在絕大多數事上ä¿æŒé€™ç¨®çš„態度。請 (在寫代碼時) 至少考慮一下這裡 +那樣，我也希望在絕大多數事上ä¿æŒé€™ç¨®çš„態度。請 (在寫代碼時) è‡³å°‘è€ƒæ…®ä¸€ä¸‹é€™è£ çš„ä»£ç¢¼é¢¨æ ¼ã€‚ -首先，我建è°ä½ 列å°ä¸€ä»½ GNU 代碼è¦ç¯„，然後ä¸è¦è®€ã€‚燒了它，這是一個具有é‡å¤§è±¡å¾µ +首先，我建è°ä½ 打å°ä¸€ä»½ GNU 代碼è¦ç¯„，然後ä¸è¦è®€ã€‚燒了它，這是一個具有é‡å¤§è±¡å¾µ 性æ„義的動作。 ä¸ç®¡æ€Žæ¨£ï¼Œç¾åœ¨æˆ‘們開始： 1) 縮進 --------------- +------- -制表符是 8 個å—符，所以縮進也是 8 個å—符。有些異端é‹å‹•è©¦åœ–將縮進變爲 4 (甚至 +製表符是 8 個å—符，所以縮進也是 8 個å—符。有些異端é‹å‹•è©¦åœ–將縮進變爲 4 (甚至 2ï¼) å—符深，這幾乎相當於嘗試將圓周率的值定義爲 3。 -ç†ç”±ï¼šç¸®é€²çš„全部æ„義就在於清楚的定義一個控制塊起æ¢æ–¼ä½•è™•ã€‚å°¤å…¶æ˜¯ç•¶ä½ ç›¯è‘—ä½ çš„ +ç†ç”±ï¼šç¸®é€²çš„全部æ„義就在於清楚的定義一個控制塊起æ¢æ–¼ä½•è™•ã€‚å°¤å…¶æ˜¯ç•¶ä½ ç›¯ç€ä½ çš„ å±å¹•é€£çºŒçœ‹äº† 20 å°æ™‚ä¹‹å¾Œï¼Œä½ å°‡æœƒç™¼ç¾å¤§ä¸€é»žçš„ç¸®é€²æœƒä½¿ä½ æ›´å®¹æ˜“åˆ†è¾¨ç¸®é€²ã€‚ ç¾åœ¨ï¼Œæœ‰äº›äººæœƒæŠ±æ€¨ 8 個å—符的縮進會使代碼å‘å³é‚Šç§»å‹•çš„太é ，在 80 個å—符的終端 @@ -69,39 +71,60 @@ Linux å…§æ ¸ä»£ç¢¼é¢¨æ ¼ break; } -ä¸è¦æŠŠå¤šå€‹èªžå¥æ”¾åœ¨ä¸€è¡Œé‡Œï¼Œé™¤éžä½ 有什麼æ±è¥¿è¦éš±è—： +ä¸è¦æŠŠå¤šå€‹èªžå¥æ”¾åœ¨ä¸€è¡Œè£ï¼Œé™¤éžä½ 有什麼æ±è¥¿è¦éš±è—： .. code-block:: c if (condition) do_this; do_something_everytime; -也ä¸è¦åœ¨ä¸€è¡Œé‡Œæ”¾å¤šå€‹è³¦å€¼èªžå¥ã€‚å…§æ ¸ä»£ç¢¼é¢¨æ ¼è¶…ç´šç°¡å–®ã€‚å°±æ˜¯é¿å…å¯èƒ½å°Žè‡´åˆ¥äººèª¤è®€ +ä¸è¦ä½¿ç”¨é€—號來é¿å…使用大括號： + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +使用大括號包裹多語å¥ï¼š + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + +也ä¸è¦åœ¨ä¸€è¡Œè£æ”¾å¤šå€‹è³¦å€¼èªžå¥ã€‚å…§æ ¸ä»£ç¢¼é¢¨æ ¼è¶…ç´šç°¡å–®ã€‚å°±æ˜¯é¿å…å¯èƒ½å°Žè‡´åˆ¥äººèª¤è®€ 的表é”å¼ã€‚ -除了注釋ã€æ–‡æª”å’Œ Kconfig 之外，ä¸è¦ä½¿ç”¨ç©ºæ ¼ä¾†ç¸®é€²ï¼Œå‰é¢çš„例å是例外，是有æ„爲 +除了註釋ã€æ–‡æª”å’Œ Kconfig 之外，ä¸è¦ä½¿ç”¨ç©ºæ ¼ä¾†ç¸®é€²ï¼Œå‰é¢çš„例å是例外，是有æ„爲 之。 é¸ç”¨ä¸€å€‹å¥½çš„編輯器，ä¸è¦åœ¨è¡Œå°¾ç•™ç©ºæ ¼ã€‚ 2) 把長的行和å—符串打散 ------------------------------- +----------------------- ä»£ç¢¼é¢¨æ ¼çš„æ„義就在於使用平常使用的工具來ç¶æŒä»£ç¢¼çš„å¯è®€æ€§å’Œå¯ç¶è·æ€§ã€‚ æ¯ä¸€è¡Œçš„長度的é™åˆ¶æ˜¯ 80 列，我們強烈建è°æ‚¨éµå®ˆé€™å€‹æ…£ä¾‹ã€‚ é•·æ–¼ 80 列的語å¥è¦æ‰“æ•£æˆæœ‰æ„義的片段。除éžè¶…éŽ 80 åˆ—èƒ½é¡¯è‘—å¢žåŠ å¯è®€æ€§ï¼Œä¸¦ä¸”ä¸ -會隱è—ä¿¡æ¯ã€‚å片段è¦æ˜Žé¡¯çŸæ–¼æ¯ç‰‡æ®µï¼Œä¸¦æ˜Žé¡¯é å³ã€‚這åŒæ¨£é©ç”¨æ–¼æœ‰è‘—很長åƒæ•¸åˆ—表 -的函數é 。然而，絕å°ä¸è¦æ‰“æ•£å°ç”¨æˆ¶å¯è¦‹çš„å—符串，例如 printk ä¿¡æ¯ï¼Œå› 爲這樣就 +會隱è—ä¿¡æ¯ã€‚ + +å片段è¦æ˜Žé¡¯çŸæ–¼æ¯ç‰‡æ®µï¼Œä¸¦æ˜Žé¡¯é å³ã€‚一種éžå¸¸å¸¸ç”¨çš„樣å¼æ˜¯å°‡å體與函數左括號å°é½Šã€‚ + +這åŒæ¨£é©ç”¨æ–¼æœ‰ç€å¾ˆé•·åƒæ•¸åˆ—表的函數é 。 + +然而，絕å°ä¸è¦æ‰“æ•£å°ç”¨æˆ¶å¯è¦‹çš„å—符串，例如 printk ä¿¡æ¯ï¼Œå› 爲這樣就 很難å°å®ƒå€‘ grep。 3) å¤§æ‹¬è™Ÿå’Œç©ºæ ¼çš„æ”¾ç½® ------------------------------- +--------------------- -C èªžè¨€é¢¨æ ¼ä¸å¦å¤–一個常見å•é¡Œæ˜¯å¤§æ‹¬è™Ÿçš„放置。和縮進大å°ä¸åŒï¼Œé¸æ“‡æˆ–棄用æŸç§æ”¾ +C èªžè¨€é¢¨æ ¼ä¸å¦å¤–一個常見å•é¡Œæ˜¯å¤§æ‹¬è™Ÿçš„放置。和縮進大å°ä¸åŒï¼Œé¸æ“‡æˆ–棄用æŸç¨®æ”¾ ç½®ç–ç•¥ä¸¦æ²’æœ‰å¤šå°‘æŠ€è¡“ä¸Šçš„åŽŸå› ï¼Œä¸éŽé¦–é¸çš„æ–¹å¼ï¼Œå°±åƒ Kernighan å’Œ Ritchie 展示 給我們的，是把起始大括號放在行尾，而把çµæŸå¤§æ‹¬è™Ÿæ”¾åœ¨è¡Œé¦–，所以： @@ -135,12 +158,12 @@ C èªžè¨€é¢¨æ ¼ä¸å¦å¤–一個常見å•é¡Œæ˜¯å¤§æ‹¬è™Ÿçš„æ”¾ç½®ã€‚å’Œç¸®é€²å¤§å° body of function } -全世界的異端å¯èƒ½æœƒæŠ±æ€¨é€™å€‹ä¸ä¸€è‡´æ€§æ˜¯... 呃... ä¸ä¸€è‡´çš„，ä¸éŽæ‰€æœ‰æ€ç¶å¥å…¨çš„人 +全世界的異端å¯èƒ½æœƒæŠ±æ€¨é€™å€‹ä¸ä¸€è‡´æ€§æ˜¯â€¦â€¦å‘ƒâ€¦â€¦ä¸ä¸€è‡´ï¼Œä¸éŽæ‰€æœ‰æ€ç¶å¥å…¨çš„人 éƒ½çŸ¥é“ (a) K&R 是 **æ£ç¢ºçš„** 並且 (b) K&R 是æ£ç¢ºçš„。æ¤å¤–，ä¸ç®¡æ€Žæ¨£å‡½æ•¸éƒ½æ˜¯ç‰¹ 殊的 (C 函數是ä¸èƒ½åµŒå¥—çš„)。 -注æ„çµæŸå¤§æ‹¬è™Ÿç¨è‡ªå 據一行，除éžå®ƒå¾Œé¢è·Ÿè‘—åŒä¸€å€‹èªžå¥çš„剩餘部分，也就是 do 語 -å¥ä¸çš„ "while" 或者 if 語å¥ä¸çš„ "else"，åƒé€™æ¨£ï¼š +注æ„çµæŸå¤§æ‹¬è™Ÿç¨è‡ªä½”據一行，除éžå®ƒå¾Œé¢è·Ÿç€åŒä¸€å€‹èªžå¥çš„剩餘部分，也就是 do 語 +å¥ä¸çš„ ``while`` 或者 if 語å¥ä¸çš„ ``else`` ，åƒé€™æ¨£ï¼š .. code-block:: c @@ -164,7 +187,7 @@ C èªžè¨€é¢¨æ ¼ä¸å¦å¤–一個常見å•é¡Œæ˜¯å¤§æ‹¬è™Ÿçš„æ”¾ç½®ã€‚å’Œç¸®é€²å¤§å° ä¹Ÿè«‹æ³¨æ„這種大括號的放置方å¼ä¹Ÿèƒ½ä½¿ç©º (或者差ä¸å¤šç©ºçš„) 行的數é‡æœ€å°åŒ–，åŒæ™‚ä¸ å¤±å¯è®€æ€§ã€‚å› æ¤ï¼Œç”±æ–¼ä½ çš„å±å¹•ä¸Šçš„新行是ä¸å¯å†ç”Ÿè³‡æº (想想 25 行的終端å±å¹•)ï¼Œä½ -將會有更多的空行來放置注釋。 +將會有更多的空行來放置註釋。 當åªæœ‰ä¸€å€‹å–®ç¨çš„語å¥çš„時候，ä¸ç”¨åŠ ä¸å¿…è¦çš„大括號。 @@ -194,12 +217,12 @@ C èªžè¨€é¢¨æ ¼ä¸å¦å¤–一個常見å•é¡Œæ˜¯å¤§æ‹¬è™Ÿçš„æ”¾ç½®ã€‚å’Œç¸®é€²å¤§å° } 3.1) ç©ºæ ¼ -******************** +********* Linux å…§æ ¸çš„ç©ºæ ¼ä½¿ç”¨æ–¹å¼ (主è¦) å–決於它是用於函數還是關éµå—。(大多數) é—œéµå— 後è¦åŠ ä¸€å€‹ç©ºæ ¼ã€‚å€¼å¾—æ³¨æ„的例外是 sizeof, typeof, alignof å’Œ __attribute__，這 -些關éµå—æŸäº›ç¨‹åº¦ä¸Šçœ‹èµ·ä¾†æ›´åƒå‡½æ•¸ (它們在 Linux 里也常常伴隨å°æ‹¬è™Ÿè€Œä½¿ç”¨ï¼Œå„˜ç®¡ -在 C 里這樣的å°æ‹¬è™Ÿä¸æ˜¯å¿…éœ€çš„ï¼Œå°±åƒ ``struct fileinfo info;`` è²æ˜ŽéŽå¾Œçš„ +些關éµå—æŸäº›ç¨‹åº¦ä¸Šçœ‹èµ·ä¾†æ›´åƒå‡½æ•¸ (它們在 Linux è£ä¹Ÿå¸¸å¸¸ä¼´éš¨å°æ‹¬è™Ÿè€Œä½¿ç”¨ï¼Œå„˜ç®¡ +在 C è£é€™æ¨£çš„å°æ‹¬è™Ÿä¸æ˜¯å¿…éœ€çš„ï¼Œå°±åƒ ``struct fileinfo info;`` è²æ˜ŽéŽå¾Œçš„ ``sizeof info``)。 所以在這些關éµå—ä¹‹å¾Œæ”¾ä¸€å€‹ç©ºæ ¼:: @@ -213,7 +236,7 @@ Linux å…§æ ¸çš„ç©ºæ ¼ä½¿ç”¨æ–¹å¼ (主è¦) å–決於它是用於函數還是關é s = sizeof(struct file); -ä¸è¦åœ¨å°æ‹¬è™Ÿé‡Œçš„表é”å¼å…©å´åŠ ç©ºæ ¼ã€‚é€™æ˜¯ä¸€å€‹ **å例** ： +ä¸è¦åœ¨å°æ‹¬è™Ÿè£çš„表é”å¼å…©å´åŠ ç©ºæ ¼ã€‚é€™æ˜¯ä¸€å€‹ **å例** ： .. code-block:: c @@ -257,10 +280,10 @@ Linux å…§æ ¸çš„ç©ºæ ¼ä½¿ç”¨æ–¹å¼ (主è¦) å–決於它是用於函數還是關é 4) 命å ------------------------------- +------- -C æ˜¯ä¸€å€‹ç°¡æ¨¸çš„èªžè¨€ï¼Œä½ çš„å‘½å也應該這樣。和 Modula-2 å’Œ Pascal 程å¼è¨è¨ˆå¸«ä¸åŒï¼Œ -C 程å¼è¨è¨ˆå¸«ä¸ä½¿ç”¨é¡žä¼¼ ThisVariableIsATemporaryCounter 這樣è¯éº—çš„åå—。C 程å¼è¨è¨ˆå¸«æœƒ +C æ˜¯ä¸€å€‹ç°¡æ¨¸çš„èªžè¨€ï¼Œä½ çš„å‘½å也應該這樣。和 Modula-2 å’Œ Pascal 程åºå“¡ä¸åŒï¼Œ +C 程åºå“¡ä¸ä½¿ç”¨é¡žä¼¼ ThisVariableIsATemporaryCounter 這樣è¯éº—çš„åå—。C 程åºå“¡æœƒ 稱那個變é‡çˆ² ``tmp`` ，這樣寫起來會更容易，而且至少ä¸æœƒä»¤å…¶é›£æ–¼ç†è§£ã€‚ ä¸éŽï¼Œé›–然混用大å°å¯«çš„åå—是ä¸æ倡使用的，但是全局變é‡é‚„是需è¦ä¸€å€‹å…·æ述性的 @@ -271,23 +294,42 @@ C 程å¼è¨è¨ˆå¸«ä¸ä½¿ç”¨é¡žä¼¼ ThisVariableIsATemporaryCounter 這樣è¯éº—çš„ ``count_active_users()`` 或者類似的åå—ï¼Œä½ ä¸æ‡‰è©²å«å®ƒ ``cntuser()`` 。 在函數åä¸åŒ…å«å‡½æ•¸é¡žåž‹ (所謂的匈牙利命å法) 是腦å出了å•é¡Œâ€”—編è¯å™¨çŸ¥é“那些類 -åž‹è€Œä¸”èƒ½å¤ æª¢æŸ¥é‚£äº›é¡žåž‹ï¼Œé€™æ¨£åšåªèƒ½æŠŠç¨‹å¼è¨è¨ˆå¸«å¼„ç³Šå¡—äº†ã€‚é›£æ€ªå¾®è»Ÿç¸½æ˜¯è£½é€ å‡ºæœ‰å•é¡Œ -的程åºã€‚ +åž‹è€Œä¸”èƒ½å¤ æª¢æŸ¥é‚£äº›é¡žåž‹ï¼Œé€™æ¨£åšåªèƒ½æŠŠç¨‹åºå“¡å¼„糊塗了。 本地變é‡å應該簡çŸï¼Œè€Œä¸”èƒ½å¤ è¡¨é”相關的å«ç¾©ã€‚å¦‚æžœä½ æœ‰ä¸€äº›éš¨æ©Ÿçš„æ•´æ•¸åž‹çš„å¾ªç’°è¨ˆ 數器，它應該被稱爲 ``i`` 。å«å®ƒ ``loop_counter`` 並無益處，如果它沒有被誤解的 å¯èƒ½çš„話。類似的， ``tmp`` å¯ä»¥ç”¨ä¾†ç¨±å‘¼ä»»æ„類型的臨時變é‡ã€‚ å¦‚æžœä½ æ€•æ··æ·†äº†ä½ çš„æœ¬åœ°è®Šé‡åï¼Œä½ å°±é‡åˆ°å¦ä¸€å€‹å•é¡Œäº†ï¼Œå«åšå‡½æ•¸å¢žé•·è·çˆ¾è’™å¤±è¡¡ç¶œ -åˆç—‡ã€‚請看第å…ç« (函數)。 +åˆå¾µã€‚請看第å…ç« (函數)。 +å°æ–¼ç¬¦è™Ÿå稱和文檔，é¿å…引入新的“master/slaveâ€ï¼ˆæˆ–ç¨ç«‹æ–¼â€œmasterâ€çš„“slaveâ€ï¼‰ +和“blacklist/whitelistâ€ã€‚ + +“master/slaveâ€æŽ¨è–¦æ›¿æ›çˆ²ï¼š + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader/follower' + 'director/performer' + +“blacklist/whitelistâ€æŽ¨è–¦æ›¿æ›çˆ²ï¼š + 'denylist/allowlist' + 'blocklist/passlist' + +引入新用法的例外情æ³æ˜¯ï¼šç¶è·ç”¨æˆ¶ç©ºé–“ABI/API，或更新ç¾æœ‰ï¼ˆæˆªè‡³2020年）硬件或 +å”è°è¦ç¯„的代碼時è¦æ±‚這些術語。å°æ–¼æ–°è¦ç¯„，儘å¯èƒ½å°‡è¡“語的è¦ç¯„用法轉æ›çˆ²å…§æ ¸ +編碼標準。 + +.. warning:: + 以上主從ã€é»‘白åå–®è¦å‰‡ä¸é©ç”¨æ–¼ä¸æ–‡æ–‡æª”，請勿更改ä¸æ–‡è¡“èªžï¼ 5) Typedef ------------ +---------- ä¸è¦ä½¿ç”¨é¡žä¼¼ ``vps_t`` 之類的æ±è¥¿ã€‚ -å°çµæ§‹é«”和指é‡ä½¿ç”¨ typedef 是一個 **錯誤** ã€‚ç•¶ä½ åœ¨ä»£ç¢¼é‡Œçœ‹åˆ°ï¼š +å°çµæ§‹é«”和指é‡ä½¿ç”¨ typedef 是一個 **錯誤** ã€‚ç•¶ä½ åœ¨ä»£ç¢¼è£çœ‹åˆ°ï¼š .. code-block:: c @@ -312,13 +354,13 @@ C 程å¼è¨è¨ˆå¸«ä¸ä½¿ç”¨é¡žä¼¼ ThisVariableIsATemporaryCounter 這樣è¯éº—çš„ .. note:: - ä¸é€æ˜Žæ€§å’Œ "訪å•å‡½æ•¸" 本身是ä¸å¥½çš„。我們使用 pte_t ç‰é¡žåž‹çš„åŽŸå› åœ¨æ–¼çœŸ + ä¸é€æ˜Žæ€§å’Œâ€œè¨ªå•å‡½æ•¸â€æœ¬èº«æ˜¯ä¸å¥½çš„。我們使用 pte_t ç‰é¡žåž‹çš„åŽŸå› åœ¨æ–¼çœŸ 的是完全沒有任何共用的å¯è¨ªå•ä¿¡æ¯ã€‚ (b) 清楚的整數類型，如æ¤ï¼Œé€™å±¤æŠ½è±¡å°±å¯ä»¥ **幫助** 消除到底是 ``int`` 還是 ``long`` 的混淆。 - u8/u16/u32 是完全沒有å•é¡Œçš„ typedef，ä¸éŽå®ƒå€‘更符åˆé¡žåˆ¥ (d) 而ä¸æ˜¯é€™è£¡ã€‚ + u8/u16/u32 是完全沒有å•é¡Œçš„ typedef，ä¸éŽå®ƒå€‘更符åˆé¡žåˆ¥ (d) 而ä¸æ˜¯é€™è£ã€‚ .. note:: @@ -345,30 +387,30 @@ C 程å¼è¨è¨ˆå¸«ä¸ä½¿ç”¨é¡žä¼¼ ThisVariableIsATemporaryCounter 這樣è¯éº—çš„ (e) å¯ä»¥åœ¨ç”¨æˆ¶ç©ºé–“安全使用的類型。 - 在æŸäº›ç”¨æˆ¶ç©ºé–“å¯è¦‹çš„çµæ§‹é«”裡，我們ä¸èƒ½è¦æ±‚ C99 類型而且ä¸èƒ½ç”¨ä¸Šé¢æ到的 + 在æŸäº›ç”¨æˆ¶ç©ºé–“å¯è¦‹çš„çµæ§‹é«”è£ï¼Œæˆ‘們ä¸èƒ½è¦æ±‚ C99 類型而且ä¸èƒ½ç”¨ä¸Šé¢æ到的 ``u32`` é¡žåž‹ã€‚å› æ¤ï¼Œæˆ‘們在與用戶空間共享的所有çµæ§‹é«”ä¸ä½¿ç”¨ __u32 和類似 的類型。 å¯èƒ½é‚„有其他的情æ³ï¼Œä¸éŽåŸºæœ¬çš„è¦å‰‡æ˜¯ **æ°¸é ä¸è¦** 使用 typedef，除éžä½ å¯ä»¥æ˜Ž 確的應用上述æŸå€‹è¦å‰‡ä¸çš„一個。 -總的來說，如果一個指é‡æˆ–者一個çµæ§‹é«”è£¡çš„å…ƒç´ å¯ä»¥åˆç†çš„被直接訪å•åˆ°ï¼Œé‚£éº¼å®ƒå€‘ +總的來說，如果一個指é‡æˆ–者一個çµæ§‹é«”è£çš„å…ƒç´ å¯ä»¥åˆç†çš„被直接訪å•åˆ°ï¼Œé‚£éº¼å®ƒå€‘ å°±ä¸æ‡‰è©²æ˜¯ä¸€å€‹ typedef。 6) 函數 ------------------------------- +------- 函數應該簡çŸè€Œæ¼‚亮，並且åªå®Œæˆä¸€ä»¶äº‹æƒ…。函數應該å¯ä»¥ä¸€å±æˆ–者兩å±é¡¯ç¤ºå®Œ (我們 éƒ½çŸ¥é“ ISO/ANSI å±å¹•å¤§å°æ˜¯ 80x24)，åªåšä¸€ä»¶äº‹æƒ…，而且把它åšå¥½ã€‚ 一個函數的最大長度是和該函數的複雜度和縮進級數æˆåæ¯”çš„ã€‚æ‰€ä»¥ï¼Œå¦‚æžœä½ æœ‰ä¸€å€‹ç† è«–ä¸Šå¾ˆç°¡å–®çš„åªæœ‰ä¸€å€‹å¾ˆé•· (但是簡單) çš„ case 語å¥çš„å‡½æ•¸ï¼Œè€Œä¸”ä½ éœ€è¦åœ¨æ¯å€‹ case -里åšå¾ˆå¤šå¾ˆå°çš„事情，這樣的函數儘管很長，但也是å¯ä»¥çš„。 +è£åšå¾ˆå¤šå¾ˆå°çš„事情，這樣的函數儘管很長，但也是å¯ä»¥çš„。 ä¸éŽï¼Œå¦‚æžœä½ æœ‰ä¸€å€‹è¤‡é›œçš„å‡½æ•¸ï¼Œè€Œä¸”ä½ æ‡·ç–‘ä¸€å€‹å¤©åˆ†ä¸æ˜¯å¾ˆé«˜çš„高ä¸ä¸€å¹´ç´šå¸ç”Ÿå¯èƒ½ 甚至æžä¸æ¸…æ¥šé€™å€‹å‡½æ•¸çš„ç›®çš„ï¼Œä½ æ‡‰è©²åš´æ ¼éµå®ˆå‰é¢æ到的長度é™åˆ¶ã€‚使用輔助函數， -並爲之å–個具æ述性的åå— (å¦‚æžœä½ è¦ºå¾—å®ƒå€‘çš„æ€§èƒ½å¾ˆé‡è¦çš„話，å¯ä»¥è®“ç·¨è¯å™¨å…§è¯å®ƒ +併爲之å–個具æ述性的åå— (å¦‚æžœä½ è¦ºå¾—å®ƒå€‘çš„æ€§èƒ½å¾ˆé‡è¦çš„話，å¯ä»¥è®“ç·¨è¯å™¨å…§è¯å®ƒ å€‘ï¼Œé€™æ¨£çš„æ•ˆæžœå¾€å¾€æœƒæ¯”ä½ å¯«ä¸€å€‹è¤‡é›œå‡½æ•¸çš„æ•ˆæžœè¦å¥½ã€‚) 函數的å¦å¤–一個衡é‡æ¨™æº–是本地變é‡çš„數é‡ã€‚æ¤æ•¸é‡ä¸æ‡‰è¶…éŽ 5ï¼10 個，å¦å‰‡ä½ 的函數 @@ -376,7 +418,7 @@ C 程å¼è¨è¨ˆå¸«ä¸ä½¿ç”¨é¡žä¼¼ ThisVariableIsATemporaryCounter 這樣è¯éº—çš„ çš„åŒæ™‚跟蹤 7 個ä¸åŒçš„事物，如果å†å¢žå¤šçš„話，就會糊塗了。å³ä¾¿ä½ è°ç©ŽéŽäººï¼Œä½ ä¹Ÿå¯ èƒ½æœƒè¨˜ä¸æ¸…ä½ 2 個星期å‰åšéŽçš„事情。 -在æºæ–‡ä»¶é‡Œï¼Œä½¿ç”¨ç©ºè¡Œéš”é–‹ä¸åŒçš„函數。如果該函數需è¦è¢«å°Žå‡ºï¼Œå®ƒçš„ **EXPORT** å® +在æºæ–‡ä»¶è£ï¼Œä½¿ç”¨ç©ºè¡Œéš”é–‹ä¸åŒçš„函數。如果該函數需è¦è¢«å°Žå‡ºï¼Œå®ƒçš„ **EXPORT** å® æ‡‰è©²ç·Šè²¼åœ¨å®ƒçš„çµæŸå¤§æ‹¬è™Ÿä¹‹ä¸‹ã€‚比如： .. code-block:: c @@ -387,12 +429,46 @@ C 程å¼è¨è¨ˆå¸«ä¸ä½¿ç”¨é¡žä¼¼ ThisVariableIsATemporaryCounter 這樣è¯éº—çš„ } EXPORT_SYMBOL(system_is_up); -在函數原型ä¸ï¼ŒåŒ…å«å‡½æ•¸å和它們的數據類型。雖然 C 語言裡沒有這樣的è¦æ±‚，在 -Linux 里這是æ倡的åšæ³•ï¼Œå› 爲這樣å¯ä»¥å¾ˆç°¡å–®çš„給讀者æ供更多的有價值的信æ¯ã€‚ +6.1) 函數原型 +************* + +在函數原型ä¸åŒ…å«åƒæ•¸å和它們的數據類型。雖然 C 語言è£æ²’有這樣的è¦æ±‚，但在 +Linux è£é€™æ˜¯æ倡的åšæ³•ï¼Œå› 爲這樣å¯ä»¥å¾ˆç°¡å–®çš„給讀者æ供更多的有價值的信æ¯ã€‚ +ä¸è¦åœ¨å‡½æ•¸è²æ˜Žè£ä½¿ç”¨ ``extern`` é—œéµå—ï¼Œå› çˆ²é€™æœƒå°Žè‡´ä»£ç¢¼è¡Œè®Šé•·ï¼Œä¸¦ä¸”ä¸æ˜¯åš´æ ¼ +必需的。 + +寫函數原型時，請ä¿æŒ `å…ƒç´ é †åºè¦å‰‡ <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_ 。 +例如下列函數è²æ˜Ž:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +æŽ¨è–¦çš„å‡½æ•¸åŽŸåž‹å…ƒç´ é †åºæ˜¯ï¼š + +- 儲å˜é¡žåž‹ï¼ˆä¸‹æ–¹çš„ ``static __always_inline`` ï¼Œæ³¨æ„ ``__always_inline`` + æŠ€è¡“ä¸Šä¾†è¬›æ˜¯å€‹å±¬æ€§ä½†è¢«ç•¶åš ``inline`` ） +- 儲å˜é¡žåž‹å±¬æ€§ï¼ˆä¸Šæ–¹çš„ ``__init`` ——å³ç¯€è²æ˜Žï¼Œä½†ä¹Ÿåƒ ``__cold`` ） +- 返回類型（上方的 ``void *`` ） +- 返回類型屬性（上方的 ``__must_check`` ） +- 函數å（上方的 ``action`` ） +- 函數åƒæ•¸ï¼ˆä¸Šæ–¹çš„ ``(enum magic value, size_t size, u8 count, char *fmt, ...)`` ， + 注æ„å¿…é ˆå¯«ä¸Šåƒæ•¸å） +- 函數åƒæ•¸å±¬æ€§ï¼ˆä¸Šæ–¹çš„ ``__printf(4, 5)`` ） +- 函數行爲屬性（上方的 ``__malloc`` ） + +請注æ„，å°æ–¼å‡½æ•¸ **定義** （å³å¯¦éš›å‡½æ•¸é«”），編è¯å™¨ä¸å…許在函數åƒæ•¸ä¹‹å¾Œæ·»åŠ 函 +數åƒæ•¸å±¬æ€§ã€‚在這種情æ³ä¸‹ï¼Œå®ƒå€‘應該跟隨å˜å„²é¡žåž‹å±¬æ€§ï¼ˆä¾‹å¦‚，與上é¢çš„ **è²æ˜Ž** +示例相比，請注æ„下é¢çš„ ``__printf(4, 5)`` çš„ä½ç½®ç™¼ç”Ÿäº†è®ŠåŒ–）:: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } 7) 集ä¸çš„函數退出途徑 ------------------------------- +--------------------- 雖然被æŸäº›äººè²ç¨±å·²ç¶“éŽæ™‚，但是 goto 語å¥çš„ç‰åƒ¹ç‰©é‚„是經常被編è¯å™¨æ‰€ä½¿ç”¨ï¼Œå…·é«” å½¢å¼æ˜¯ç„¡æ¢ä»¶è·³è½‰æŒ‡ä»¤ã€‚ @@ -436,7 +512,7 @@ Linux 里這是æ倡的åšæ³•ï¼Œå› 爲這樣å¯ä»¥å¾ˆç°¡å–®çš„給讀者æä¾›æ› return result; } -一個需è¦æ³¨æ„的常見錯誤是 ``一個 err 錯誤`` ，就åƒé€™æ¨£ï¼š +一個需è¦æ³¨æ„的常見錯誤是 ``å–® err 錯誤`` ，就åƒé€™æ¨£ï¼š .. code-block:: c @@ -459,22 +535,22 @@ Linux 里這是æ倡的åšæ³•ï¼Œå› 爲這樣å¯ä»¥å¾ˆç°¡å–®çš„給讀者æä¾›æ› ç†æƒ³æƒ…æ³ä¸‹ï¼Œä½ 應該模擬錯誤來測試所有退出路徑。 -8) 注釋 ------------------------------- +8) 註釋 +------- -注釋是好的，ä¸éŽæœ‰éŽåº¦æ³¨é‡‹çš„å±éšªã€‚æ°¸é ä¸è¦åœ¨æ³¨é‡‹é‡Œè§£é‡‹ä½ 的代碼是如何é‹ä½œçš„： +註釋是好的，ä¸éŽæœ‰éŽåº¦è¨»é‡‹çš„å±éšªã€‚æ°¸é ä¸è¦åœ¨è¨»é‡‹è£è§£é‡‹ä½ 的代碼是如何é‹ä½œçš„： 更好的åšæ³•æ˜¯è®“åˆ¥äººä¸€çœ‹ä½ çš„ä»£ç¢¼å°±å¯ä»¥æ˜Žç™½ï¼Œè§£é‡‹å¯«çš„很差的代碼是浪費時間。 -ä¸€èˆ¬çš„ï¼Œä½ æƒ³è¦ä½ çš„æ³¨é‡‹å‘Šè¨´åˆ¥äººä½ çš„ä»£ç¢¼åšäº†ä»€éº¼ï¼Œè€Œä¸æ˜¯æ€Žéº¼åšçš„ã€‚ä¹Ÿè«‹ä½ ä¸è¦æŠŠ -æ³¨é‡‹æ”¾åœ¨ä¸€å€‹å‡½æ•¸é«”å…§éƒ¨ï¼šå¦‚æžœå‡½æ•¸è¤‡é›œåˆ°ä½ éœ€è¦ç¨ç«‹çš„注釋其ä¸çš„ä¸€éƒ¨åˆ†ï¼Œä½ å¾ˆå¯èƒ½ +ä¸€èˆ¬ä¾†èªªä½ ç”¨è¨»é‡‹å‘Šè¨´åˆ¥äººä½ çš„ä»£ç¢¼åšäº†ä»€éº¼ï¼Œè€Œä¸æ˜¯æ€Žéº¼åšçš„ã€‚ä¹Ÿè«‹ä½ ä¸è¦æŠŠ +è¨»é‡‹æ”¾åœ¨ä¸€å€‹å‡½æ•¸é«”å…§éƒ¨ï¼šå¦‚æžœå‡½æ•¸è¤‡é›œåˆ°ä½ éœ€è¦ç¨ç«‹çš„註釋其ä¸çš„ä¸€éƒ¨åˆ†ï¼Œä½ å¾ˆå¯èƒ½ 需è¦å›žåˆ°ç¬¬å…ç« çœ‹ä¸€çœ‹ã€‚ä½ å¯ä»¥åšä¸€äº›å°æ³¨é‡‹ä¾†è¨»æ˜Žæˆ–è¦å‘ŠæŸäº›å¾ˆè°æ˜Ž (或者槽糕) çš„ -åšæ³•ï¼Œä½†ä¸è¦åŠ å¤ªå¤šã€‚ä½ æ‡‰è©²åšçš„，是把注釋放在函數的é 部，告訴人們它åšäº†ä»€éº¼ï¼Œ +åšæ³•ï¼Œä½†ä¸è¦åŠ å¤ªå¤šã€‚ä½ æ‡‰è©²åšçš„，是把註釋放在函數的é 部，告訴人們它åšäº†ä»€éº¼ï¼Œ 也å¯ä»¥åŠ 上它åšé€™äº›äº‹æƒ…çš„åŽŸå› ã€‚ -ç•¶æ³¨é‡‹å…§æ ¸ API 函數時，請使用 kernel-doc æ ¼å¼ã€‚請看 -Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ +ç•¶è¨»é‡‹å…§æ ¸ API 函數時，請使用 kernel-doc æ ¼å¼ã€‚詳見 +Documentation/translations/zh_CN/doc-guide/index.rst å’Œ scripts/kernel-doc 。 -é•· (多行) 注釋的首é¸é¢¨æ ¼æ˜¯ï¼š +é•· (多行) 註釋的首é¸é¢¨æ ¼æ˜¯ï¼š .. code-block:: c @@ -487,7 +563,7 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ * with beginning and ending almost-blank lines. */ -å°æ–¼åœ¨ net/ å’Œ drivers/net/ 的文件，首é¸çš„é•· (多行) æ³¨é‡‹é¢¨æ ¼æœ‰äº›ä¸åŒã€‚ +å°æ–¼åœ¨ net/ å’Œ drivers/net/ 的文件，首é¸çš„é•· (多行) è¨»é‡‹é¢¨æ ¼æœ‰äº›ä¸åŒã€‚ .. code-block:: c @@ -498,23 +574,24 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ * but there is no initial almost-blank line. */ -注釋數據也是很é‡è¦çš„，ä¸ç®¡æ˜¯åŸºæœ¬é¡žåž‹é‚„是è¡ç”Ÿé¡žåž‹ã€‚爲了方便實ç¾é€™ä¸€é»žï¼Œæ¯ä¸€è¡Œ +註釋數據也是很é‡è¦çš„，ä¸ç®¡æ˜¯åŸºæœ¬é¡žåž‹é‚„是è¡ç”Ÿé¡žåž‹ã€‚爲了方便實ç¾é€™ä¸€é»žï¼Œæ¯ä¸€è¡Œ 應åªè²æ˜Žä¸€å€‹æ•¸æ“š (ä¸è¦ä½¿ç”¨é€—號來一次è²æ˜Žå¤šå€‹æ•¸æ“š)ã€‚é€™æ¨£ä½ å°±æœ‰ç©ºé–“ä¾†çˆ²æ¯å€‹æ•¸æ“š 寫一段å°æ³¨é‡‹ä¾†è§£é‡‹å®ƒå€‘的用途了。 9) ä½ å·²ç¶“æŠŠäº‹æƒ…å¼„ç³Ÿäº† ------------------------------- +--------------------- -這沒什麼，我們都是這樣。å¯èƒ½ä½ 的使用了很長時間 Unix 的朋å‹å·²ç¶“å‘Šè¨´ä½ -``GNU emacs`` èƒ½è‡ªå‹•å¹«ä½ æ ¼å¼åŒ– C åŽŸå§‹ç¢¼ï¼Œè€Œä¸”ä½ ä¹Ÿæ³¨æ„到了，確實是這樣，ä¸éŽå®ƒ +這沒什麼，我們都是這樣。å¯èƒ½ä½ 長期使用 Unix 的朋å‹å·²ç¶“å‘Šè¨´ä½ +``GNU emacs`` èƒ½è‡ªå‹•å¹«ä½ æ ¼å¼åŒ– C æºä»£ç¢¼ï¼Œè€Œä¸”ä½ ä¹Ÿæ³¨æ„到了，確實是這樣，ä¸éŽå®ƒ 所使用的默èªå€¼å’Œæˆ‘們想è¦çš„相去甚é (實際上，甚至比隨機打的還è¦å·®â€”—無數個猴å -在 GNU emacs 里打å—æ°¸é ä¸æœƒå‰µé€ 出一個好程åº) (è¯è¨»ï¼šInfinite Monkey Theorem) +在 GNU emacs è£æ‰“å—æ°¸é ä¸æœƒå‰µé€ 出一個好程åº) +*(è¯è¨»ï¼šInfinite Monkey Theorem)* æ‰€ä»¥ä½ è¦éº¼æ”¾æ£„ GNU emacs，è¦éº¼æ”¹è®Šå®ƒè®“它使用更åˆç†çš„è¨å®šã€‚è¦æŽ¡ç”¨å¾Œä¸€å€‹æ–¹æ¡ˆï¼Œ -ä½ å¯ä»¥æŠŠä¸‹é¢é€™æ®µç²˜è²¼åˆ°ä½ çš„ .emacs 文件里。 +ä½ å¯ä»¥æŠŠä¸‹é¢é€™æ®µç²˜è²¼åˆ°ä½ çš„ .emacs 文件è£ã€‚ -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -533,7 +610,7 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) @@ -565,24 +642,29 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ 這會讓 emacs 在 ``~/src/linux-trees`` 下的 C æºæ–‡ä»¶ç²å¾—æ›´å¥½çš„å…§æ ¸ä»£ç¢¼é¢¨æ ¼ã€‚ -ä¸éŽå°±ç®—ä½ å˜—è©¦è®“ emacs æ£ç¢ºçš„æ ¼å¼åŒ–代碼失敗了，也並ä¸æ„å‘³è‘—ä½ å¤±åŽ»äº†ä¸€åˆ‡ï¼šé‚„å¯ +ä¸éŽå°±ç®—ä½ å˜—è©¦è®“ emacs æ£ç¢ºçš„æ ¼å¼åŒ–代碼失敗了，也並ä¸æ„味ç€ä½ å¤±åŽ»äº†ä¸€åˆ‡ï¼šé‚„å¯ ä»¥ç”¨ ``indent`` 。 ä¸éŽï¼ŒGNU indent 也有和 GNU emacs 一樣有å•é¡Œçš„è¨å®šï¼Œæ‰€ä»¥ä½ 需è¦çµ¦å®ƒä¸€äº›å‘½ä»¤é¸ é …ã€‚ä¸éŽï¼Œé€™é‚„ä¸ç®—å¤ªç³Ÿç³•ï¼Œå› çˆ²å°±ç®—æ˜¯ GNU indent 的作者也èªåŒ K&R 的權å¨æ€§ (GNU 的人並ä¸æ˜¯å£žäººï¼Œä»–們åªæ˜¯åœ¨é€™å€‹å•é¡Œä¸Šè¢«åš´é‡çš„誤導了)ï¼Œæ‰€ä»¥ä½ åªè¦çµ¦ indent 指定é¸é … ``-kr -i8`` (代表 ``K&R，8 å—符縮進``)，或使用 ``scripts/Lindent`` -這樣就å¯ä»¥ä»¥æœ€æ™‚髦的方å¼ç¸®é€²åŽŸå§‹ç¢¼ã€‚ +這樣就å¯ä»¥ä»¥æœ€æ™‚髦的方å¼ç¸®é€²æºä»£ç¢¼ã€‚ -``indent`` 有很多é¸é …，特別是é‡æ–°æ ¼å¼åŒ–æ³¨é‡‹çš„æ™‚å€™ï¼Œä½ å¯èƒ½éœ€è¦çœ‹ä¸€ä¸‹å®ƒçš„手冊。 +``indent`` 有很多é¸é …，特別是é‡æ–°æ ¼å¼åŒ–è¨»é‡‹çš„æ™‚å€™ï¼Œä½ å¯èƒ½éœ€è¦çœ‹ä¸€ä¸‹å®ƒçš„手冊。 ä¸éŽè¨˜ä½ï¼š ``indent`` ä¸èƒ½ä¿®æ£å£žçš„編程習慣。 +請注æ„，您還å¯ä»¥ä½¿ç”¨ ``clang-format`` 工具幫助您處ç†é€™äº›è¦å‰‡ï¼Œå¿«é€Ÿè‡ªå‹•é‡æ–°æ ¼ +å¼åŒ–部分代碼，並審閱整個文件以發ç¾ä»£ç¢¼é¢¨æ ¼éŒ¯èª¤ã€æ‰“å—錯誤和å¯èƒ½çš„æ”¹é€²ã€‚å®ƒé‚„å¯ +ä»¥æ–¹ä¾¿åœ°æŽ’åº ``#include`` ，å°é½Šè®Šé‡/å®ï¼Œé‡æŽ’文本和其他類似任務。 +詳見 Documentation/process/clang-format.rst 。 + 10) Kconfig é…置文件 ------------------------------- +-------------------- -å°æ–¼é布æºç¢¼æ¨¹çš„所有 Kconfig* é…置文件來說，它們縮進方å¼æœ‰æ‰€ä¸åŒã€‚緊挨著 -``config`` 定義的行，用一個制表符縮進，然而 help ä¿¡æ¯çš„縮進則é¡å¤–å¢žåŠ 2 個空 +å°æ–¼é佈æºç¢¼æ¨¹çš„所有 Kconfig* é…置文件來說，它們縮進方å¼æœ‰æ‰€ä¸åŒã€‚ç·ŠæŒ¨ç€ +``config`` 定義的行，用一個製表符縮進，然而 help ä¿¡æ¯çš„縮進則é¡å¤–å¢žåŠ 2 個空 æ ¼ã€‚èˆ‰å€‹ä¾‹å:: config AUDIT @@ -594,7 +676,7 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ logging of avc messages output). Does not do system-call auditing without CONFIG_AUDITSYSCALL. -而那些å±éšªçš„功能 (比如æŸäº›æ–‡ä»¶ç³»çµ±çš„寫支æŒ) 應該在它們的æ示å—ç¬¦ä¸²é‡Œé¡¯è‘—çš„è² +而那些å±éšªçš„功能 (比如æŸäº›æ–‡ä»¶ç³»çµ±çš„寫支æŒ) 應該在它們的æ示å—符串è£é¡¯è‘—çš„è² æ˜Žé€™ä¸€é»ž:: config ADFS_FS_RW @@ -602,17 +684,17 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ depends on ADFS_FS ... -è¦æŸ¥çœ‹é…置文件的完整文檔，請看 Documentation/kbuild/kconfig-language.rst。 +è¦æŸ¥çœ‹é…置文件的完整文檔，請看 Documentation/kbuild/kconfig-language.rst 。 11) 數據çµæ§‹ ------------------------------- +------------ -如果一個數據çµæ§‹ï¼Œåœ¨å‰µå»ºå’ŒéŠ·æ¯€å®ƒçš„單線執行環境之外å¯è¦‹ï¼Œé‚£éº¼å®ƒå¿…é ˆè¦æœ‰ä¸€å€‹å¼• -ç”¨è¨ˆæ•¸å™¨ã€‚å…§æ ¸é‡Œæ²’æœ‰åžƒåœ¾æ”¶é›† (ä¸¦ä¸”å…§æ ¸ä¹‹å¤–çš„åžƒåœ¾æ”¶é›†æ…¢ä¸”æ•ˆçŽ‡ä½Žä¸‹)，這æ„å‘³è‘—ä½ +如果一個數據çµæ§‹ï¼Œåœ¨å‰µå»ºå’ŒéŠ·ç‡¬å®ƒçš„單線執行環境之外å¯è¦‹ï¼Œé‚£éº¼å®ƒå¿…é ˆè¦æœ‰ä¸€å€‹å¼• +ç”¨è¨ˆæ•¸å™¨ã€‚å…§æ ¸è£æ²’有垃圾收集 (ä¸¦ä¸”å…§æ ¸ä¹‹å¤–çš„åžƒåœ¾æ”¶é›†æ…¢ä¸”æ•ˆçŽ‡ä½Žä¸‹)，這æ„味ç€ä½ 絕å°éœ€è¦è¨˜éŒ„ä½ å°é€™ç¨®æ•¸æ“šçµæ§‹çš„使用情æ³ã€‚ -引用計數æ„å‘³è‘—ä½ èƒ½å¤ é¿å…上鎖，並且å…許多個用戶並行訪å•é€™å€‹æ•¸æ“šçµæ§‹â€”—而ä¸éœ€è¦ +引用計數æ„味ç€ä½ èƒ½å¤ é¿å…上鎖，並且å…許多個用戶並行訪å•é€™å€‹æ•¸æ“šçµæ§‹â€”—而ä¸éœ€è¦ 擔心這個數據çµæ§‹åƒ…åƒ…å› çˆ²æš«æ™‚ä¸è¢«ä½¿ç”¨å°±æ¶ˆå¤±äº†ï¼Œé‚£äº›ç”¨æˆ¶å¯èƒ½ä¸éŽæ˜¯æ²‰ç¡äº†ä¸€é™£æˆ– 者åšäº†ä¸€äº›å…¶ä»–事情而已。 @@ -626,13 +708,13 @@ Documentation/doc-guide/ å’Œ scripts/kernel-doc 以ç²å¾—詳細信æ¯ã€‚ mm_count)，和文件系統 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰¾åˆ°ã€‚ 記ä½ï¼šå¦‚æžœå¦ä¸€å€‹åŸ·è¡Œç·šç´¢å¯ä»¥æ‰¾åˆ°ä½ 的數據çµæ§‹ï¼Œä½†é€™å€‹æ•¸æ“šçµæ§‹æ²’有引用計數器， -這裡幾乎肯定是一個 bug。 +這è£å¹¾ä¹Žè‚¯å®šæ˜¯ä¸€å€‹ bug。 12) å®ï¼Œæžšèˆ‰å’ŒRTL ------------------------------- +----------------- -用於定義常é‡çš„å®çš„åå—åŠæžšèˆ‰é‡Œçš„標籤需è¦å¤§å¯«ã€‚ +用於定義常é‡çš„å®çš„åå—åŠæžšèˆ‰è£çš„標籤需è¦å¤§å¯«ã€‚ .. code-block:: c @@ -642,9 +724,9 @@ mm_count)，和文件系統 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰ å®çš„åå—請用大寫å—æ¯ï¼Œä¸éŽå½¢å¦‚函數的å®çš„åå—å¯ä»¥ç”¨å°å¯«å—æ¯ã€‚ -一般的，如果能寫æˆå…§è¯å‡½æ•¸å°±ä¸è¦å¯«æˆåƒå‡½æ•¸çš„å®ã€‚ +通常如果能寫æˆå…§è¯å‡½æ•¸å°±ä¸è¦å¯«æˆåƒå‡½æ•¸çš„å®ã€‚ -å«æœ‰å¤šå€‹èªžå¥çš„å®æ‡‰è©²è¢«åŒ…å«åœ¨ä¸€å€‹ do-while 代碼塊里： +å«æœ‰å¤šå€‹èªžå¥çš„å®æ‡‰è©²è¢«åŒ…å«åœ¨ä¸€å€‹ do-while 代碼塊è£ï¼š .. code-block:: c @@ -667,7 +749,7 @@ mm_count)，和文件系統 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰ } while (0) **éžå¸¸** ä¸å¥½ã€‚它看起來åƒä¸€å€‹å‡½æ•¸ï¼Œä¸éŽå»èƒ½å°Žè‡´ ``調用`` 它的函數退出；ä¸è¦æ‰“ -亂讀者大腦里的語法分æžå™¨ã€‚ +亂讀者大腦è£çš„語法分æžå™¨ã€‚ 2) ä¾è³´æ–¼ä¸€å€‹å›ºå®šåå—的本地變é‡çš„å®ï¼š @@ -689,7 +771,7 @@ mm_count)，和文件系統 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰ #define CONSTANT 0x4000 #define CONSTEXP (CONSTANT | 3) -5) 在å®é‡Œå®šç¾©é¡žä¼¼å‡½æ•¸çš„本地變é‡æ™‚命åè¡çªï¼š +5) 在å®è£å®šç¾©é¡žä¼¼å‡½æ•¸çš„本地變é‡æ™‚命åè¡çªï¼š .. code-block:: c @@ -700,45 +782,46 @@ mm_count)，和文件系統 (``struct super_block``: s_count å’Œ s_active) ä¸æ‰ (ret); \ }) -ret 是本地變é‡çš„通用åå— - __foo_ret æ›´ä¸å®¹æ˜“與一個已å˜åœ¨çš„變é‡è¡çªã€‚ +ret 是本地變é‡çš„通用åå——— __foo_ret æ›´ä¸å®¹æ˜“與一個已å˜åœ¨çš„變é‡è¡çªã€‚ -cpp 手冊å°å®çš„講解很詳細。gcc internals 手冊也詳細講解了 RTLï¼Œå…§æ ¸é‡Œçš„å½™ç·¨èªž +cpp 手冊å°å®çš„講解很詳細。gcc internals 手冊也詳細講解了 RTLï¼Œå…§æ ¸è£çš„彙編語 言經常用到它。 -13) 列å°å…§æ ¸æ¶ˆæ¯ ------------------------------- +13) 打å°å…§æ ¸æ¶ˆæ¯ +---------------- -å…§æ ¸é–‹ç™¼è€…æ‡‰è©²æ˜¯å—éŽè‰¯å¥½æ•™è‚²çš„。請一定注æ„å…§æ ¸ä¿¡æ¯çš„拼寫，以給人以好的å°è±¡ã€‚ +å…§æ ¸é–‹ç™¼è€…æ‡‰è©²çœ‹èµ·ä¾†æœ‰æ–‡åŒ–ã€‚è«‹ä¸€å®šæ³¨æ„å…§æ ¸ä¿¡æ¯çš„拼寫，以給人良好的å°è±¡ã€‚ ä¸è¦ç”¨ä¸è¦ç¯„的單詞比如 ``dont``，而è¦ç”¨ ``do not`` 或者 ``don't`` 。ä¿è‰é€™äº›ä¿¡ -æ¯ç°¡å–®æ˜Žäº†,ç„¡æ§ç¾©ã€‚ +æ¯ç°¡å–®æ˜Žçžã€ç„¡æ§ç¾©ã€‚ å…§æ ¸ä¿¡æ¯ä¸å¿…以英文å¥è™ŸçµæŸã€‚ -在å°æ‹¬è™Ÿé‡Œåˆ—å°æ•¸å— (%d) 沒有任何價值，應該é¿å…這樣åšã€‚ +在å°æ‹¬è™Ÿè£æ‰“å°æ•¸å— (%d) 沒有任何價值，應該é¿å…這樣åšã€‚ -<linux/device.h> 里有一些驅動模型診斷å®ï¼Œä½ 應該使用它們，以確ä¿ä¿¡æ¯å°æ‡‰æ–¼æ£ç¢º +<linux/device.h> è£æœ‰ä¸€äº›é©…動模型診斷å®ï¼Œä½ 應該使用它們，以確ä¿ä¿¡æ¯å°æ‡‰æ–¼æ£ç¢º çš„è¨å‚™å’Œé©…動，並且被標記了æ£ç¢ºçš„消æ¯ç´šåˆ¥ã€‚這些å®æœ‰ï¼šdev_err(), dev_warn(), dev_info() ç‰ç‰ã€‚å°æ–¼é‚£äº›ä¸å’ŒæŸå€‹ç‰¹å®šè¨å‚™ç›¸é—œé€£çš„ä¿¡æ¯ï¼Œ<linux/printk.h> 定義 了 pr_notice(), pr_info(), pr_warn(), pr_err() 和其他。 寫出好的調試信æ¯å¯ä»¥æ˜¯ä¸€å€‹å¾ˆå¤§çš„æŒ‘æˆ°ï¼›ä¸€æ—¦ä½ å¯«å‡ºå¾Œï¼Œé€™äº›ä¿¡æ¯åœ¨é 程除錯時能æ -供極大的幫助。然而列å°èª¿è©¦ä¿¡æ¯çš„處ç†æ–¹å¼åŒåˆ—å°éžèª¿è©¦ä¿¡æ¯ä¸åŒã€‚其他 pr_XXX() -函數能無æ¢ä»¶åœ°åˆ—å°ï¼Œpr_debug() å»ä¸ï¼›é»˜èªæƒ…æ³ä¸‹å®ƒä¸æœƒè¢«ç·¨è¯ï¼Œé™¤éžå®šç¾©äº† DEBUG +供極大的幫助。然而打å°èª¿è©¦ä¿¡æ¯çš„處ç†æ–¹å¼åŒæ‰“å°éžèª¿è©¦ä¿¡æ¯ä¸åŒã€‚其他 pr_XXX() +函數能無æ¢ä»¶åœ°æ‰“å°ï¼Œpr_debug() å»ä¸ï¼›é»˜èªæƒ…æ³ä¸‹å®ƒä¸æœƒè¢«ç·¨è¯ï¼Œé™¤éžå®šç¾©äº† DEBUG 或è¨å®šäº† CONFIG_DYNAMIC_DEBUG。實際這åŒæ¨£æ˜¯çˆ²äº† dev_dbg()，一個相關約定是在一 個已經開啓了 DEBUG 時，使用 VERBOSE_DEBUG ä¾†æ·»åŠ dev_vdbg()。 -許多å系統æ“有 Kconfig 調試é¸é …來開啓 -DDEBUG 在å°æ‡‰çš„ Makefile 裡é¢ï¼›åœ¨å…¶ä»– -情æ³ä¸‹ï¼Œç‰¹æ®Šæ–‡ä»¶ä½¿ç”¨ #define DEBUG。當一æ¢èª¿è©¦ä¿¡æ¯éœ€è¦è¢«ç„¡æ¢ä»¶åˆ—å°æ™‚，例如， +許多å系統æ“有 Kconfig 調試é¸é …來開啓å°æ‡‰ Makefile è£é¢çš„ -DDEBUG；在其他 +情æ³ä¸‹ï¼Œç‰¹æ®Šæ–‡ä»¶ä½¿ç”¨ #define DEBUG。當一æ¢èª¿è©¦ä¿¡æ¯éœ€è¦è¢«ç„¡æ¢ä»¶æ‰“å°æ™‚，例如， 如果已經包å«ä¸€å€‹èª¿è©¦ç›¸é—œçš„ #ifdef æ¢ä»¶ï¼Œprintk(KERN_DEBUG ...) å°±å¯è¢«ä½¿ç”¨ã€‚ 14) 分é…å…§å˜ ------------------------------- +------------ å…§æ ¸æ供了下é¢çš„一般用途的內å˜åˆ†é…函數： kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() å’Œ vzalloc()。 -è«‹åƒè€ƒ API 文檔以ç²å–有關它們的詳細信æ¯ã€‚ +è«‹åƒè€ƒ API 文檔以ç²å–有關它們的詳細信æ¯ï¼š +Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 傳éžçµæ§‹é«”大å°çš„首é¸å½¢å¼æ˜¯é€™æ¨£çš„： @@ -765,17 +848,19 @@ kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() å’Œ vzalloc()。 p = kcalloc(n, sizeof(...), ...); -兩種形å¼æª¢æŸ¥åˆ†é…å¤§å° n * sizeof(...) 的溢出，如果溢出返回 NULL。 +兩種形å¼éƒ½æœƒæª¢æŸ¥åˆ†é… n * sizeof(...) 大å°æ™‚å…§å˜çš„溢出，如果溢出返回 NULL。 +在沒有 __GFP_NOWARN 的情æ³ä¸‹ä½¿ç”¨æ™‚，這些通用分é…å‡½æ•¸éƒ½æœƒåœ¨å¤±æ•—æ™‚ç™¼èµ·å †æ£§è½‰å„²ï¼Œ +å› æ¤ç•¶è¿”回NULL時，沒有必è¦ç™¼å‡ºé¡å¤–的失敗消æ¯ã€‚ 15) å…§è¯å¼Šç—… ------------------------------- +------------ 有一個常見的誤解是 ``å…§è¯`` 是 gcc æ供的å¯ä»¥è®“代碼é‹è¡Œæ›´å¿«çš„一個é¸é …。雖然使 用內è¯å‡½æ•¸æœ‰æ™‚候是æ°ç•¶çš„ (比如作爲一種替代å®çš„æ–¹å¼ï¼Œè«‹çœ‹ç¬¬åäºŒç« )，ä¸éŽå¾ˆå¤šæƒ… æ³ä¸‹ä¸æ˜¯é€™æ¨£ã€‚inline çš„éŽåº¦ä½¿ç”¨æœƒä½¿å…§æ ¸è®Šå¤§ï¼Œå¾žè€Œä½¿æ•´å€‹ç³»çµ±é‹è¡Œé€Ÿåº¦è®Šæ…¢ã€‚ -å› çˆ²é«”ç©å¤§å…§æ ¸æœƒå 用更多的指令高速緩å˜ï¼Œè€Œä¸”會導致 pagecache çš„å¯ç”¨å…§å˜æ¸›å°‘。 -想åƒä¸€ä¸‹ï¼Œä¸€æ¬¡ pagecache 未命ä¸å°±æœƒå°Žè‡´ä¸€æ¬¡ç£ç¢Ÿå°‹å€ï¼Œå°‡è€—時 5 毫秒。5 毫秒的 +å› çˆ²é«”ç©å¤§å…§æ ¸æœƒä½”用更多的指令高速緩å˜ï¼Œè€Œä¸”會導致 pagecache çš„å¯ç”¨å…§å˜æ¸›å°‘。 +想象一下，一次 pagecache 未命ä¸å°±æœƒå°Žè‡´ä¸€æ¬¡ç£ç›¤å°‹å€ï¼Œå°‡è€—時 5 毫秒。5 毫秒的 時間內 CPU 能執行很多很多指令。 一個基本的原則是如果一個函數有 3 行以上，就ä¸è¦æŠŠå®ƒè®Šæˆå…§è¯å‡½æ•¸ã€‚這個原則的一 @@ -790,7 +875,7 @@ inline gcc 也å¯ä»¥è‡ªå‹•ä½¿å…¶å…§è¯ã€‚而且其他用戶å¯èƒ½æœƒè¦æ±‚移除 16) 函數返回值åŠå‘½å ------------------------------- +-------------------- 函數å¯ä»¥è¿”回多種ä¸åŒé¡žåž‹çš„值，最常見的一種是表明函數執行æˆåŠŸæˆ–者失敗的值。這樣 的一個值å¯ä»¥è¡¨ç¤ºçˆ²ä¸€å€‹éŒ¯èª¤ä»£ç¢¼æ•´æ•¸ (-Exxxï¼å¤±æ•—，0ï¼æˆåŠŸ) 或者一個 ``æˆåŠŸ`` @@ -801,7 +886,7 @@ inline gcc 也å¯ä»¥è‡ªå‹•ä½¿å…¶å…§è¯ã€‚而且其他用戶å¯èƒ½æœƒè¦æ±‚移除 產生這種 bug，請éµå¾ªä¸‹é¢çš„慣例:: 如果函數的åå—是一個動作或者強制性的命令，那麼這個函數應該返回錯誤代 - 碼整數。如果是一個判斷，那麼函數應該返回一個 "æˆåŠŸ" 布爾值。 + 碼整數。如果是一個判斷，那麼函數應該返回一個“æˆåŠŸâ€å¸ƒçˆ¾å€¼ã€‚ 比如， ``add work`` 是一個命令，所以 add_work() 在æˆåŠŸæ™‚返回 0，在失敗時返回 -EBUSYã€‚é¡žä¼¼çš„ï¼Œå› çˆ² ``PCI device present`` 是一個判斷，所以 pci_dev_present() @@ -810,13 +895,35 @@ inline gcc 也å¯ä»¥è‡ªå‹•ä½¿å…¶å…§è¯ã€‚而且其他用戶å¯èƒ½æœƒè¦æ±‚移除 所有 EXPORTed å‡½æ•¸éƒ½å¿…é ˆéµå®ˆé€™å€‹æ…£ä¾‹ï¼Œæ‰€æœ‰çš„公共函數也都應該如æ¤ã€‚ç§æœ‰ (static) 函數ä¸éœ€è¦å¦‚æ¤ï¼Œä½†æ˜¯æˆ‘們也推薦這樣åšã€‚ -返回值是實際計算çµæžœè€Œä¸æ˜¯è¨ˆç®—是å¦æˆåŠŸçš„標誌的函數ä¸å—æ¤æ…£ä¾‹çš„é™åˆ¶ã€‚一般的， +返回值是實際計算çµæžœè€Œä¸æ˜¯è¨ˆç®—是å¦æˆåŠŸçš„標誌的函數ä¸å—æ¤æ…£ä¾‹çš„é™åˆ¶ã€‚通常 他們通éŽè¿”回一些æ£å¸¸å€¼ç¯„åœä¹‹å¤–çš„çµæžœä¾†è¡¨ç¤ºå‡ºéŒ¯ã€‚典型的例å是返回指é‡çš„函數， 他們使用 NULL 或者 ERR_PTR æ©Ÿåˆ¶ä¾†å ±å‘ŠéŒ¯èª¤ã€‚ +17) 使用布爾類型 +---------------- + +Linuxå…§æ ¸å¸ƒçˆ¾ï¼ˆbool）類型是C99 _Bool類型的別å。布爾值åªèƒ½çˆ²0或1，而å°å¸ƒçˆ¾çš„ +éš±å¼æˆ–顯å¼è½‰æ›å°‡è‡ªå‹•å°‡å€¼è½‰æ›çˆ²true或false。在使用布爾類型時 **ä¸éœ€è¦** æ§‹é€ ï¼Œ +它會消除一類錯誤。 + +使用布爾值時，應使用trueå’Œfalse定義，而ä¸æ˜¯1å’Œ0。 -17) ä¸è¦é‡æ–°ç™¼æ˜Žå…§æ ¸å® ------------------------------- +å¸ƒçˆ¾å‡½æ•¸è¿”å›žé¡žåž‹å’Œå †æ£§è®Šé‡ç¸½æ˜¯å¯ä»¥åœ¨é©ç•¶çš„時候使用。鼓勵使用布爾來æ高å¯è®€æ€§ï¼Œ +並且布爾值在å˜å„²æ™‚通常比“intâ€æ›´å¥½ã€‚ + +如果緩å˜è¡Œä½ˆå±€æˆ–值的大å°å¾ˆé‡è¦ï¼Œè«‹ä¸è¦ä½¿ç”¨å¸ƒçˆ¾ï¼Œå› 爲其大å°å’Œå°é½Šæ–¹å¼æ ¹æ“šç·¨è¯ +的體系çµæ§‹è€Œä¸åŒã€‚é‡å°å°é½Šå’Œå¤§å°é€²è¡Œå„ªåŒ–çš„çµæ§‹é«”ä¸æ‡‰ä½¿ç”¨å¸ƒçˆ¾ã€‚ + +如果一個çµæ§‹é«”有多個true/false值，請考慮將它們åˆä½µçˆ²å…·æœ‰1比特æˆå“¡çš„ä½åŸŸï¼Œæˆ–使 +用é©ç•¶çš„固定寬度類型，如u8。 + +類似地，å°æ–¼å‡½æ•¸åƒæ•¸ï¼Œå¤šå€‹true/false值å¯ä»¥åˆä½µçˆ²å–®å€‹æŒ‰ä½çš„“標誌â€åƒæ•¸ï¼Œå¦‚果調 +用點具有裸true/false常é‡ï¼Œâ€œæ¨™èªŒâ€åƒæ•¸é€šå¸¸æ˜¯æ›´å…·å¯è®€æ€§çš„替代方法。 + +總之，在çµæ§‹é«”å’Œåƒæ•¸ä¸æœ‰é™åœ°ä½¿ç”¨å¸ƒçˆ¾å¯ä»¥æ高å¯è®€æ€§ã€‚ + +18) ä¸è¦é‡æ–°ç™¼æ˜Žå…§æ ¸å® +---------------------- é 文件 include/linux/kernel.h 包å«äº†ä¸€äº›å®ï¼Œä½ 應該使用它們，而ä¸è¦è‡ªå·±å¯«ä¸€äº› å®ƒå€‘çš„è®Šç¨®ã€‚æ¯”å¦‚ï¼Œå¦‚æžœä½ éœ€è¦è¨ˆç®—ä¸€å€‹æ•¸çµ„çš„é•·åº¦ï¼Œä½¿ç”¨é€™å€‹å® @@ -832,15 +939,15 @@ inline gcc 也å¯ä»¥è‡ªå‹•ä½¿å…¶å…§è¯ã€‚而且其他用戶å¯èƒ½æœƒè¦æ±‚移除 #define sizeof_field(t, f) (sizeof(((t*)0)->f)) 還有å¯ä»¥åšåš´æ ¼çš„類型檢查的 min() å’Œ max() å®ï¼Œå¦‚æžœä½ éœ€è¦å¯ä»¥ä½¿ç”¨å®ƒå€‘ã€‚ä½ å¯ä»¥ -自己看看那個é æ–‡ä»¶é‡Œé‚„å®šç¾©äº†ä»€éº¼ä½ å¯ä»¥æ‹¿ä¾†ç”¨çš„æ±è¥¿ï¼Œå¦‚æžœæœ‰å®šç¾©çš„è©±ï¼Œä½ å°±ä¸æ‡‰ -åœ¨ä½ çš„ä»£ç¢¼é‡Œè‡ªå·±é‡æ–°å®šç¾©ã€‚ +自己看看那個é 文件è£é‚„å®šç¾©äº†ä»€éº¼ä½ å¯ä»¥æ‹¿ä¾†ç”¨çš„æ±è¥¿ï¼Œå¦‚æžœæœ‰å®šç¾©çš„è©±ï¼Œä½ å°±ä¸æ‡‰ +åœ¨ä½ çš„ä»£ç¢¼è£è‡ªå·±é‡æ–°å®šç¾©ã€‚ -18) 編輯器模å¼è¡Œå’Œå…¶ä»–需è¦ç¾…嗦的事情 --------------------------------------------------- +19) 編輯器模å¼è¡Œå’Œå…¶ä»–需è¦ç¾…嗦的事情 +------------------------------------ -有一些編輯器å¯ä»¥è§£é‡‹åµŒå…¥åœ¨æºæ–‡ä»¶é‡Œçš„由一些特殊標記標明的é…置信æ¯ã€‚比如，emacs -èƒ½å¤ è§£é‡‹è¢«æ¨™è¨˜æˆé€™æ¨£çš„行： +有一些編輯器å¯ä»¥è§£é‡‹åµŒå…¥åœ¨æºæ–‡ä»¶è£çš„由一些特殊標記標明的é…置信æ¯ã€‚比如，emacs +èƒ½å¤ è§£æžè¢«æ¨™è¨˜æˆé€™æ¨£çš„行： .. code-block:: c @@ -856,23 +963,23 @@ inline gcc 也å¯ä»¥è‡ªå‹•ä½¿å…¶å…§è¯ã€‚而且其他用戶å¯èƒ½æœƒè¦æ±‚移除 End: */ -Vim èƒ½å¤ è§£é‡‹é€™æ¨£çš„æ¨™è¨˜ï¼š +Vim èƒ½å¤ è§£æžé€™æ¨£çš„標記： .. code-block:: c /* vim:set sw=8 noet */ -ä¸è¦åœ¨åŽŸå§‹ç¢¼ä¸åŒ…å«ä»»ä½•é€™æ¨£çš„內容。æ¯å€‹äººéƒ½æœ‰ä»–自己的編輯器é…ç½®ï¼Œä½ çš„æºæ–‡ä»¶ä¸ +ä¸è¦åœ¨æºä»£ç¢¼ä¸åŒ…å«ä»»ä½•é€™æ¨£çš„內容。æ¯å€‹äººéƒ½æœ‰ä»–自己的編輯器é…ç½®ï¼Œä½ çš„æºæ–‡ä»¶ä¸ 應該覆蓋別人的é…置。這包括有關縮進和模å¼é…置的標記。人們å¯ä»¥ä½¿ç”¨ä»–們自己定製 的模å¼ï¼Œæˆ–者使用其他å¯ä»¥ç”¢ç”Ÿæ£ç¢ºçš„縮進的巧妙方法。 -19) å…§è¯å½™ç·¨ ------------------------------- +20) å…§è¯å½™ç·¨ +------------ -在特定架構的代碼ä¸ï¼Œä½ å¯èƒ½éœ€è¦å…§è¯å½™ç·¨èˆ‡ CPU 和平å°ç›¸é—œåŠŸèƒ½é€£æŽ¥ã€‚需è¦é€™éº¼åšæ™‚ +在特定架構的代碼ä¸ï¼Œä½ å¯èƒ½éœ€è¦å…§è¯å½™ç·¨èˆ‡ CPU 和平臺相關功能連接。需è¦é€™éº¼åšæ™‚ å°±ä¸è¦çŒ¶è±«ã€‚然而，當 C å¯ä»¥å®Œæˆå·¥ä½œæ™‚，ä¸è¦å¹³ç™½ç„¡æ•…地使用內è¯å½™ç·¨ã€‚在å¯èƒ½çš„情 -æ³ä¸‹ï¼Œä½ å¯ä»¥ä¸¦ä¸”應該用 C 和硬體æºé€šã€‚ +æ³ä¸‹ï¼Œä½ å¯ä»¥ä¸¦ä¸”應該用 C 和硬件æºé€šã€‚ 請考慮去寫æ†ç¶é€šç”¨ä½å…ƒ (wrap common bits) çš„å…§è¯å½™ç·¨çš„簡單輔助函數，別去é‡è¤‡ 地寫下åªæœ‰ç´°å¾®å·®ç•°å…§è¯å½™ç·¨ã€‚記ä½å…§è¯å½™ç·¨å¯ä»¥ä½¿ç”¨ C åƒæ•¸ã€‚ @@ -883,9 +990,9 @@ Vim èƒ½å¤ è§£é‡‹é€™æ¨£çš„æ¨™è¨˜ï¼š ä½ å¯èƒ½éœ€è¦æŠŠå½™ç·¨èªžå¥æ¨™è¨˜çˆ² volatileï¼Œç”¨ä¾†é˜»æ¢ GCC 在沒發ç¾ä»»ä½•å‰¯ä½œç”¨å¾Œå°±æŠŠå®ƒ ç§»é™¤äº†ã€‚ä½ ä¸å¿…總是這樣åšï¼Œå„˜ç®¡ï¼Œé€™ä¸å¿…è¦çš„舉動會é™åˆ¶å„ªåŒ–。 -在寫一個包å«å¤šæ¢æŒ‡ä»¤çš„單個內è¯å½™ç·¨èªžå¥æ™‚，把æ¯æ¢æŒ‡ä»¤ç”¨å¼•è™Ÿåˆ†å‰²è€Œä¸”å„å 一行， -除了最後一æ¢æŒ‡ä»¤å¤–，在æ¯å€‹æŒ‡ä»¤çµå°¾åŠ 上 \n\t，讓彙編輸出時å¯ä»¥æ£ç¢ºåœ°ç¸®é€²ä¸‹ä¸€æ¢ -指令： +在寫一個包å«å¤šæ¢æŒ‡ä»¤çš„單個內è¯å½™ç·¨èªžå¥æ™‚，把æ¯æ¢æŒ‡ä»¤ç”¨å¼•è™Ÿåˆ†å‰²è€Œä¸”å„佔一行， +除了最後一æ¢æŒ‡ä»¤å¤–，在æ¯å€‹æŒ‡ä»¤çµå°¾åŠ 上 ``\n\t`` ，讓彙編輸出時å¯ä»¥æ£ç¢ºåœ°ç¸®é€² +下一æ¢æŒ‡ä»¤ï¼š .. code-block:: c @@ -894,10 +1001,10 @@ Vim èƒ½å¤ è§£é‡‹é€™æ¨£çš„æ¨™è¨˜ï¼š : /* outputs */ : /* inputs */ : /* clobbers */); -20) æ¢ä»¶ç·¨è¯ ------------------------------- +21) æ¢ä»¶ç·¨è¯ +------------ -åªè¦å¯èƒ½ï¼Œå°±ä¸è¦åœ¨ .c 文件裡é¢ä½¿ç”¨é 處ç†æ¢ä»¶ (#if, #ifdef)；這樣åšè®“代碼更難 +åªè¦å¯èƒ½ï¼Œå°±ä¸è¦åœ¨ .c 文件è£é¢ä½¿ç”¨é 處ç†æ¢ä»¶ (#if, #ifdef)；這樣åšæœƒè®“代碼更難 閱讀並且更難去跟蹤é‚輯。替代方案是，在é 文件ä¸ç”¨é 處ç†æ¢ä»¶æ供給那些 .c 文件 使用，å†çµ¦ #else æä¾›ä¸€å€‹ç©ºæ¨ (no-op stub) 版本，然後在 .c 文件內無æ¢ä»¶åœ°èª¿ç”¨ 那些 (定義在é 文件內的) 函數。這樣åšï¼Œç·¨è¯å™¨æœƒé¿å…爲æ¨å‡½æ•¸ (stub) çš„èª¿ç”¨ç”Ÿæˆ @@ -908,8 +1015,8 @@ Vim èƒ½å¤ è§£é‡‹é€™æ¨£çš„æ¨™è¨˜ï¼š æ¢ä»¶åˆ°é€™å€‹è¼”助函數內。 å¦‚æžœä½ æœ‰ä¸€å€‹åœ¨ç‰¹å®šé…ç½®ä¸ï¼Œå¯èƒ½è®Šæˆæœªä½¿ç”¨çš„函數或變é‡ï¼Œç·¨è¯å™¨æœƒè¦å‘Šå®ƒå®šç¾©äº†ä½† -未使用，把它標記爲 __maybe_unused 而ä¸æ˜¯å°‡å®ƒåŒ…å«åœ¨ä¸€å€‹é 處ç†æ¢ä»¶ä¸ã€‚(然而，如 -果一個函數或變é‡ç¸½æ˜¯æœªä½¿ç”¨ï¼Œå°±ç›´æŽ¥åˆªé™¤å®ƒã€‚) +未使用，請把它標記爲 __maybe_unused 而ä¸æ˜¯å°‡å®ƒåŒ…å«åœ¨ä¸€å€‹é 處ç†æ¢ä»¶ä¸ã€‚(然而， +如果一個函數或變é‡ç¸½æ˜¯æœªä½¿ç”¨ï¼Œå°±ç›´æŽ¥åˆªé™¤å®ƒã€‚) 在代碼ä¸ï¼Œå„˜å¯èƒ½åœ°ä½¿ç”¨ IS_ENABLED å®ä¾†è½‰åŒ–æŸå€‹ Kconfig 標記爲 C 的布爾 表é”å¼ï¼Œä¸¦åœ¨ä¸€èˆ¬çš„ C æ¢ä»¶ä¸ä½¿ç”¨å®ƒï¼š @@ -926,7 +1033,7 @@ Vim èƒ½å¤ è§£é‡‹é€™æ¨£çš„æ¨™è¨˜ï¼š ä¸å˜åœ¨æ™‚ï¼Œä½ é‚„æ˜¯å¿…é ˆåŽ»ç”¨ #ifdef。 在任何有æ„義的 #if 或 #ifdef 塊的末尾 (超éŽå¹¾è¡Œçš„)，在 #endif åŒä¸€è¡Œçš„後é¢å¯«ä¸‹ -註解，注釋這個æ¢ä»¶è¡¨é”å¼ã€‚例如： +註解，註釋這個æ¢ä»¶è¡¨é”å¼ã€‚例如： .. code-block:: c @@ -935,24 +1042,46 @@ Vim èƒ½å¤ è§£é‡‹é€™æ¨£çš„æ¨™è¨˜ï¼š #endif /* CONFIG_SOMETHING */ -附錄 I) åƒè€ƒ -------------------- +附錄 I) åƒè€ƒè³‡æ–™ +---------------- -The C Programming Language, 第二版 +The C Programming Language, 2nd Edition 作者：Brian W. Kernighan å’Œ Denni M. Ritchie. Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (軟皮), 0-13-110370-9 (硬皮). +ISBN 0-13-110362-8 (å¹³è£), 0-13-110370-9 (ç²¾è£). + +.. note:: + + 《C程åºè¨è¨ˆèªžè¨€ï¼ˆç¬¬2版）》 + 作者：[美] Brian W. Kernighan / [美] Dennis M. Ritchie + è¯è€…：å¾å¯¶æ–‡ / æŽå¿— / å°¤æ™‰å…ƒï¼ˆå¯©æ ¡ï¼‰ + 出版社：機械工æ¥å‡ºç‰ˆç¤¾ï¼Œ2019 + ISBN：9787111617945 The Practice of Programming 作者：Brian W. Kernighan å’Œ Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. +.. note:: + + 《程åºè¨è¨ˆå¯¦è¸ã€‹ + 作者：[美] Brian W. Kernighan / [美] Rob Pike + 出版社：機械工æ¥å‡ºç‰ˆç¤¾ï¼Œ2005 + ISBN：9787111091578 + + 《程åºè¨è¨ˆå¯¦è¸ã€‹ + 作者：[美] Brian W. Kernighan / Rob Pike + è¯è€…：裘宗燕 + 出版社：機械工æ¥å‡ºç‰ˆç¤¾ï¼Œ2000 + ISBN：9787111075738 + GNU 手冊 - éµå¾ª K&R 標準和æ¤æ–‡æœ¬ - cpp, gcc, gcc internals and indent, 都å¯ä»¥å¾ž https://www.gnu.org/manual/ 找到 WG14 是 C 語言的國際標準化工作組，URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst，作者 greg@kroah.com 發表於 OLS 2002： +å…§æ ¸æ–‡æª” Documentation/process/coding-style.rst， +作者 greg@kroah.com 發表於 OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_TW/process/development-process.rst b/Documentation/translations/zh_TW/process/development-process.rst index f4cf5c2bbc82..7d803d3db89e 100644 --- a/Documentation/translations/zh_TW/process/development-process.rst +++ b/Documentation/translations/zh_TW/process/development-process.rst @@ -26,5 +26,5 @@ 7.AdvancedTopics 8.Conclusion -本文檔的目的是幫助開發人員（åŠå…¶ç¶“ç†ï¼‰ä»¥æœ€å°çš„挫折感與開發社å€åˆä½œã€‚它試圖記錄這個社å€å¦‚何以一種ä¸ç†Ÿæ‚‰Linuxå…§æ ¸é–‹ç™¼ï¼ˆæˆ–è€…å¯¦éš›ä¸Šæ˜¯è‡ªç”±è»Ÿé«”é–‹ç™¼ï¼‰çš„äººå¯ä»¥è¨ªå•çš„æ–¹å¼å·¥ä½œã€‚雖然這裡有一些技術資料，但這是一個é¢å‘éŽç¨‹çš„討論，ä¸éœ€è¦æ·±å…¥äº†è§£å…§æ ¸ç·¨ç¨‹å°±å¯ä»¥ç†è§£ã€‚ +本文檔的目的是幫助開發人員（åŠå…¶ç¶“ç†ï¼‰ä»¥æœ€å°çš„挫折感與開發社å€åˆä½œã€‚它試圖記錄這個社å€å¦‚何以一種ä¸ç†Ÿæ‚‰Linuxå…§æ ¸é–‹ç™¼ï¼ˆæˆ–è€…å¯¦éš›ä¸Šæ˜¯è‡ªç”±è»Ÿä»¶é–‹ç™¼ï¼‰çš„äººå¯ä»¥è¨ªå•çš„æ–¹å¼å·¥ä½œã€‚雖然這è£æœ‰ä¸€äº›æŠ€è¡“資料，但這是一個é¢å‘éŽç¨‹çš„討論，ä¸éœ€è¦æ·±å…¥çžè§£å…§æ ¸ç·¨ç¨‹å°±å¯ä»¥ç†è§£ã€‚ diff --git a/Documentation/translations/zh_TW/process/email-clients.rst b/Documentation/translations/zh_TW/process/email-clients.rst index ae63e41d9cee..55e10d3fc28a 100644 --- a/Documentation/translations/zh_TW/process/email-clients.rst +++ b/Documentation/translations/zh_TW/process/email-clients.rst @@ -1,20 +1,21 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_email_clients: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +.. _tw_email_clients: -è¯è€…:: +:Original: Documentation/process/email-clients.rst - ä¸æ–‡ç‰ˆç¶è·è€…： 賈å¨å¨ Harry Wei <harryxiyou@gmail.com> - ä¸æ–‡ç‰ˆç¿»è¯è€…： 賈å¨å¨ Harry Wei <harryxiyou@gmail.com> - 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> - ä¸æ–‡ç‰ˆæ ¡è¯è€…： Yinglin Luan <synmyth@gmail.com> - Xiaochen Wang <wangxiaochen0@gmail.com> - yaxinsn <yaxinsn@163.com> - Hu Haowen <src.res.211@gmail.com> +:è¯è€…: + - 賈å¨å¨ Harry Wei <harryxiyou@gmail.com> + - 時奎亮 Alex Shi <alexs@kernel.org> + - å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> + +:æ ¡è¯: + - Yinglin Luan <synmyth@gmail.com> + - Xiaochen Wang <wangxiaochen0@gmail.com> + - yaxinsn <yaxinsn@163.com> + - Hu Haowen <src.res.211@gmail.com> Linux郵件客戶端é…ç½®ä¿¡æ¯ ======================= @@ -30,30 +31,35 @@ Git 改日誌。如果工作æ£å¸¸ï¼Œå†å°‡è£œä¸ç™¼é€åˆ°ç›¸æ‡‰çš„郵件列表。 -普通é…ç½® +通用é…ç½® -------- + Linuxå…§æ ¸è£œä¸æ˜¯é€šéŽéƒµä»¶è¢«æ交的，最好把補ä¸ä½œçˆ²éƒµä»¶é«”的內嵌文本。有些ç¶è·è€… æŽ¥æ”¶é™„ä»¶ï¼Œä½†æ˜¯é™„ä»¶çš„å…§å®¹æ ¼å¼æ‡‰è©²æ˜¯"text/plain"。然而，附件一般是ä¸è´Šæˆçš„， å› çˆ²é€™æœƒä½¿è£œä¸çš„引用部分在評論éŽç¨‹ä¸è®Šçš„很困難。 +åŒæ™‚也強烈建è°åœ¨è£œä¸æˆ–其他郵件的æ£æ–‡ä¸ä½¿ç”¨ç´”æ–‡æœ¬æ ¼å¼ã€‚https://useplaintext.email +有助於çžè§£å¦‚何é…ç½®ä½ å–œæ¡çš„郵件客戶端，並在您還沒有首é¸çš„情æ³ä¸‹åˆ—出一些推薦的 +客戶端。 + 用來發é€Linuxå…§æ ¸è£œä¸çš„郵件客戶端在發é€è£œä¸æ™‚應該處於文本的原始狀態。例如， -他們ä¸èƒ½æ”¹è®Šæˆ–è€…åˆªé™¤åˆ¶è¡¨ç¬¦æˆ–è€…ç©ºæ ¼ï¼Œç”šè‡³æ˜¯åœ¨æ¯ä¸€è¡Œçš„é–‹é 或者çµå°¾ã€‚ +他們ä¸èƒ½æ”¹è®Šæˆ–è€…åˆªé™¤è£½è¡¨ç¬¦æˆ–è€…ç©ºæ ¼ï¼Œç”šè‡³æ˜¯åœ¨æ¯ä¸€è¡Œçš„é–‹é 或者çµå°¾ã€‚ ä¸è¦é€šéŽ"format=flowed"模å¼ç™¼é€è£œä¸ã€‚這樣會引起ä¸å¯é 期以åŠæœ‰å®³çš„斷行。 ä¸è¦è®“ä½ çš„éƒµä»¶å®¢æˆ¶ç«¯é€²è¡Œè‡ªå‹•æ›è¡Œã€‚é€™æ¨£ä¹Ÿæœƒç ´å£žä½ çš„è£œä¸ã€‚ -郵件客戶端ä¸èƒ½æ”¹è®Šæ–‡æœ¬çš„å—符集編碼方å¼ã€‚è¦ç™¼é€çš„補ä¸åªèƒ½æ˜¯ASCII或者UTF-8編碼方å¼ï¼Œ -å¦‚æžœä½ ä½¿ç”¨UTF-8編碼方å¼ç™¼é€éƒµä»¶ï¼Œé‚£éº¼ä½ 將會é¿å…一些å¯èƒ½ç™¼ç”Ÿçš„å—符集å•é¡Œã€‚ +郵件客戶端ä¸èƒ½æ”¹è®Šæ–‡æœ¬çš„å—符集編碼方å¼ã€‚è¦ç™¼é€çš„補ä¸åªèƒ½æ˜¯ASCII或者UTF-8編碼 +æ–¹å¼ï¼Œå¦‚æžœä½ ä½¿ç”¨UTF-8編碼方å¼ç™¼é€éƒµä»¶ï¼Œé‚£éº¼ä½ 將會é¿å…一些å¯èƒ½ç™¼ç”Ÿçš„å—符集å•é¡Œã€‚ -郵件客戶端應該形æˆä¸¦ä¸”ä¿æŒ References: 或者 In-Reply-To: 標題，那麼 -郵件話題就ä¸æœƒä¸æ–·ã€‚ +郵件客戶端應該生æˆä¸¦ä¸”ä¿æŒâ€œReferences:â€æˆ–者“In-Reply-To:â€éƒµä»¶é ，這樣郵件會話 +å°±ä¸æœƒä¸æ–·ã€‚ -複製粘帖(或者剪貼粘帖)通常ä¸èƒ½ç”¨æ–¼è£œä¸ï¼Œå› 爲制表符會轉æ›çˆ²ç©ºæ ¼ã€‚使用xclipboard, xclip -或者xcutsel也許å¯ä»¥ï¼Œä½†æ˜¯æœ€å¥½æ¸¬è©¦ä¸€ä¸‹æˆ–者é¿å…使用複製粘帖。 +複製粘帖(或者剪貼粘帖)通常ä¸èƒ½ç”¨æ–¼è£œä¸ï¼Œå› 爲製表符會轉æ›çˆ²ç©ºæ ¼ã€‚使用xclipboard, +xclip或者xcutsel也許å¯ä»¥ï¼Œä½†æ˜¯æœ€å¥½æ¸¬è©¦ä¸€ä¸‹æˆ–者é¿å…使用複製粘帖。 -ä¸è¦åœ¨ä½¿ç”¨PGP/GPGç½²å的郵件ä¸åŒ…å«è£œä¸ã€‚這樣會使得很多腳本ä¸èƒ½è®€å–å’Œé©ç”¨æ–¼ä½ 的補ä¸ã€‚ -（這個å•é¡Œæ‡‰è©²æ˜¯å¯ä»¥ä¿®å¾©çš„） +ä¸è¦åœ¨ä½¿ç”¨PGP/GPGç°½å的郵件ä¸åŒ…å«è£œä¸ã€‚這樣會使得很多腳本ä¸èƒ½è®€å–å’Œé©ç”¨æ–¼ä½ çš„ +補ä¸ã€‚（這個å•é¡Œæ‡‰è©²æ˜¯å¯ä»¥ä¿®å¾©çš„） åœ¨çµ¦å…§æ ¸éƒµä»¶åˆ—è¡¨ç™¼é€è£œä¸ä¹‹å‰ï¼Œçµ¦è‡ªå·±ç™¼é€ä¸€å€‹è£œä¸æ˜¯å€‹ä¸éŒ¯çš„主æ„，ä¿å˜æŽ¥æ”¶åˆ°çš„ 郵件，將補ä¸ç”¨'patch'命令打上，如果æˆåŠŸäº†ï¼Œå†çµ¦å…§æ ¸éƒµä»¶åˆ—表發é€ã€‚ @@ -61,100 +67,135 @@ Linuxå…§æ ¸è£œä¸æ˜¯é€šéŽéƒµä»¶è¢«æ交的，最好把補ä¸ä½œçˆ²éƒµä»¶é«”çš„ 一些郵件客戶端æ示 ------------------ -這裡給出一些詳細的MUAé…ç½®æ示，å¯ä»¥ç”¨æ–¼çµ¦Linuxå…§æ ¸ç™¼é€è£œä¸ã€‚這些並ä¸æ„味是 -所有的軟體包é…置總çµã€‚ + +這è£çµ¦å‡ºä¸€äº›è©³ç´°çš„MUAé…ç½®æ示，å¯ä»¥ç”¨æ–¼çµ¦Linuxå…§æ ¸ç™¼é€è£œä¸ã€‚這些並ä¸æ„味是 +所有的軟件包é…置總çµã€‚ 說明： -TUI = ä»¥æ–‡æœ¬çˆ²åŸºç¤Žçš„ç”¨æˆ¶æŽ¥å£ -GUI = 圖形界é¢ç”¨æˆ¶æŽ¥å£ + +- TUI = ä»¥æ–‡æœ¬çˆ²åŸºç¤Žçš„ç”¨æˆ¶æŽ¥å£ +- GUI = 圖形界é¢ç”¨æˆ¶æŽ¥å£ Alpine (TUI) -~~~~~~~~~~~~ +************ é…ç½®é¸é …： -在"Sending Preferences"部分： -- "Do Not Send Flowed Text"å¿…é ˆé–‹å•“ -- "Strip Whitespace Before Sending"å¿…é ˆé—œé–‰ +在 :menuselection:`Sending Preferences` èœå–®ï¼š + +- :menuselection:`Do Not Send Flowed Text` å¿…é ˆé–‹å•“ +- :menuselection:`Strip Whitespace Before Sending` å¿…é ˆé—œé–‰ + +當寫郵件時，光標應該放在補ä¸æœƒå‡ºç¾çš„地方，然後按下 :kbd:`CTRL-R` 組åˆéµï¼Œä½¿æŒ‡ +定的補ä¸æ–‡ä»¶åµŒå…¥åˆ°éƒµä»¶ä¸ã€‚ -當寫郵件時，光標應該放在補ä¸æœƒå‡ºç¾çš„地方，然後按下CTRL-R組åˆéµï¼Œä½¿æŒ‡å®šçš„ -補ä¸æ–‡ä»¶åµŒå…¥åˆ°éƒµä»¶ä¸ã€‚ +Claws Mail (GUI) +**************** + +å¯ä»¥ç”¨ï¼Œæœ‰äººç”¨å®ƒæˆåŠŸåœ°ç™¼éŽè£œä¸ã€‚ + +用 :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) 或外置編輯器æ’入補ä¸ã€‚ + +è‹¥è¦åœ¨Claws編輯窗å£é‡ä¿®æ”¹æ’入的補ä¸ï¼Œéœ€é—œé–‰ +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` +çš„ `Auto wrapping` 。 Evolution (GUI) -~~~~~~~~~~~~~~~ +*************** -一些開發者æˆåŠŸçš„使用它發é€è£œä¸ +一些開發者æˆåŠŸçš„使用它發é€è£œä¸ã€‚ -當é¸æ“‡éƒµä»¶é¸é …：Preformat - 從Format->Heading->Preformatted (Ctrl-7)或者工具欄 +撰寫郵件時： +從 :menuselection:`æ ¼å¼-->段è½æ¨£å¼-->é æ ¼å¼åŒ–` (:kbd:`CTRL-7`) +或工具欄é¸æ“‡ :menuselection:`é æ ¼å¼åŒ–` ï¼› 然後使用： - Insert->Text File... (Alt-n x)æ’入補ä¸æ–‡ä»¶ã€‚ +:menuselection:`æ’å…¥-->文本文件...` (:kbd:`ALT-N x`) æ’入補ä¸æ–‡ä»¶ã€‚ -ä½ é‚„å¯ä»¥"diff -Nru old.c new.c | xclip"，é¸æ“‡Preformat，然後使用ä¸é–“éµé€²è¡Œç²˜å¸–。 +ä½ é‚„å¯ä»¥ ``diff -Nru old.c new.c | xclip`` ，é¸æ“‡ :menuselection:`é æ ¼å¼åŒ–` ， +ç„¶å¾Œä½¿ç”¨é¼ æ¨™ä¸éµé€²è¡Œç²˜å¸–。 Kmail (GUI) -~~~~~~~~~~~ +*********** 一些開發者æˆåŠŸçš„使用它發é€è£œä¸ã€‚ -默èªè¨ç½®ä¸çˆ²HTMLæ ¼å¼æ˜¯åˆé©çš„ï¼›ä¸è¦å•“用它。 +默èªæ’°å¯«è¨ç½®ç¦ç”¨HTMLæ ¼å¼æ˜¯åˆé©çš„ï¼›ä¸è¦å•“用它。 + +當書寫一å°éƒµä»¶çš„時候，在é¸é …下é¢ä¸è¦é¸æ“‡è‡ªå‹•æ›è¡Œã€‚å”¯ä¸€çš„ç¼ºé»žå°±æ˜¯ä½ åœ¨éƒµä»¶ä¸è¼¸ +入的任何文本都ä¸æœƒè¢«è‡ªå‹•æ›è¡Œï¼Œå› æ¤ä½ å¿…é ˆåœ¨ç™¼é€è£œä¸ä¹‹å‰æ‰‹å‹•æ›è¡Œã€‚最簡單的方法 +就是啓用自動æ›è¡Œä¾†æ›¸å¯«éƒµä»¶ï¼Œç„¶å¾ŒæŠŠå®ƒä¿å˜çˆ²è‰ç¨¿ã€‚ä¸€æ—¦ä½ åœ¨è‰ç¨¿ä¸å†æ¬¡æ‰“開它，它 +已經全部自動æ›è¡Œäº†ï¼Œé‚£éº¼ä½ 的郵件雖然沒有é¸æ“‡è‡ªå‹•æ›è¡Œï¼Œä½†æ˜¯é‚„ä¸æœƒå¤±åŽ»å·²æœ‰çš„自 +å‹•æ›è¡Œã€‚ -當書寫一å°éƒµä»¶çš„時候，在é¸é …下é¢ä¸è¦é¸æ“‡è‡ªå‹•æ›è¡Œã€‚å”¯ä¸€çš„ç¼ºé»žå°±æ˜¯ä½ åœ¨éƒµä»¶ä¸è¼¸å…¥çš„任何文本 -都ä¸æœƒè¢«è‡ªå‹•æ›è¡Œï¼Œå› æ¤ä½ å¿…é ˆåœ¨ç™¼é€è£œä¸ä¹‹å‰æ‰‹å‹•æ›è¡Œã€‚最簡單的方法就是啓用自動æ›è¡Œä¾†æ›¸å¯«éƒµä»¶ï¼Œ -然後把它ä¿å˜çˆ²è‰ç¨¿ã€‚ä¸€æ—¦ä½ åœ¨è‰ç¨¿ä¸å†æ¬¡æ‰“開它，它已經全部自動æ›è¡Œäº†ï¼Œé‚£éº¼ä½ 的郵件雖然沒有 -é¸æ“‡è‡ªå‹•æ›è¡Œï¼Œä½†æ˜¯é‚„ä¸æœƒå¤±åŽ»å·²æœ‰çš„自動æ›è¡Œã€‚ +在郵件的底部，æ’入補ä¸ä¹‹å‰ï¼Œæ”¾ä¸Šå¸¸ç”¨çš„補ä¸å®šç•Œç¬¦ï¼šä¸‰å€‹é€£å—符(``---``)。 -在郵件的底部，æ’入補ä¸ä¹‹å‰ï¼Œæ”¾ä¸Šå¸¸ç”¨çš„補ä¸å®šç•Œç¬¦ï¼šä¸‰å€‹é€£å—號(---)。 +然後在 :menuselection:`信件` èœå–®ï¼Œé¸æ“‡ :menuselection:`æ’入文本文件` ，接 +ç€é¸å–ä½ çš„è£œä¸æ–‡ä»¶ã€‚還有一個é¡å¤–çš„é¸é …ï¼Œä½ å¯ä»¥é€šéŽå®ƒé…ç½®ä½ çš„å‰µå»ºæ–°éƒµä»¶å·¥å…·æ¬„ï¼Œ +åŠ ä¸Š :menuselection:`æ’入文本文件` 圖標。 -然後在"Message"èœå–®æ¢ç›®ï¼Œé¸æ“‡æ’入文件，接著é¸å–ä½ çš„è£œä¸æ–‡ä»¶ã€‚還有一個é¡å¤–çš„é¸é …ï¼Œä½ å¯ä»¥ -通éŽå®ƒé…ç½®ä½ çš„éƒµä»¶å»ºç«‹å·¥å…·æ¬„èœå–®ï¼Œé‚„å¯ä»¥å¸¶ä¸Š"insert file"圖標。 +將編輯器窗å£æ‹‰åˆ°è¶³å¤ 寬é¿å…折行。å°æ–¼KMail 1.13.5 (KDE 4.5.4)，它會在發é€éƒµä»¶ +時å°ç·¨è¼¯å™¨çª—å£ä¸é¡¯ç¤ºæŠ˜è¡Œçš„地方自動æ›è¡Œã€‚在é¸é …èœå–®ä¸å–消自動æ›è¡Œä»ä¸èƒ½è§£æ±ºã€‚ +å› æ¤ï¼Œå¦‚æžœä½ çš„è£œä¸ä¸æœ‰éžå¸¸é•·çš„è¡Œï¼Œå¿…é ˆåœ¨ç™¼é€ä¹‹å‰æŠŠç·¨è¼¯å™¨çª—å£æ‹‰å¾—éžå¸¸å¯¬ã€‚ +åƒè¦‹ï¼šhttps://bugs.kde.org/show_bug.cgi?id=174034 -ä½ å¯ä»¥å®‰å…¨åœ°é€šéŽGPG標記附件，但是內嵌補ä¸æœ€å¥½ä¸è¦ä½¿ç”¨GPG標記它們。作爲內嵌文本的簽發補ä¸ï¼Œ -當從GPGä¸æå–7ä½ç·¨ç¢¼æ™‚æœƒä½¿ä»–å€‘è®Šçš„æ›´åŠ è¤‡é›œã€‚ +ä½ å¯ä»¥å®‰å…¨åœ°ç”¨GPGç°½å附件，但是內嵌補ä¸æœ€å¥½ä¸è¦ä½¿ç”¨GPGç°½å它們。作爲內嵌文本 +æ’入的簽å補ä¸å°‡ä½¿å…¶é›£ä»¥å¾ž7-bit編碼ä¸æå–。 -å¦‚æžœä½ éžè¦ä»¥é™„件的形å¼ç™¼é€è£œä¸ï¼Œé‚£éº¼å°±å³éµé»žæ“Šé™„件，然後é¸ä¸å±¬æ€§ï¼Œçªå‡º"Suggest automatic -display"，這樣內嵌附件更容易讓讀者看到。 +å¦‚æžœä½ éžè¦ä»¥é™„件的形å¼ç™¼é€è£œä¸ï¼Œé‚£éº¼å°±å³éµé»žæ“Šé™„件，然後é¸æ“‡ +:menuselection:`屬性` ，打開 :menuselection:`建è°è‡ªå‹•é¡¯ç¤º` ，使附件內è¯æ›´å®¹ +易讓讀者看到。 -ç•¶ä½ è¦ä¿å˜å°‡è¦ç™¼é€çš„內嵌文本補ä¸ï¼Œä½ å¯ä»¥å¾žæ¶ˆæ¯åˆ—è¡¨çª—æ ¼é¸æ“‡åŒ…å«è£œä¸çš„郵件，然後å³æ“Šé¸æ“‡ -"save as"ã€‚ä½ å¯ä»¥ä½¿ç”¨ä¸€å€‹æ²’有更改的包å«è£œä¸çš„郵件，如果它是以æ£ç¢ºçš„å½¢å¼çµ„æˆã€‚ç•¶ä½ æ£çœŸåœ¨å®ƒ -自己的窗å£ä¹‹ä¸‹å¯Ÿçœ‹ï¼Œé‚£æ™‚沒有é¸é …å¯ä»¥ä¿å˜éƒµä»¶--已經有一個這樣的bugè¢«åŒ¯å ±åˆ°äº†kmailçš„bugzilla -並且希望這將會被處ç†ã€‚郵件是以åªé‡å°æŸå€‹ç”¨æˆ¶å¯è®€å¯«çš„權é™è¢«ä¿å˜çš„ï¼Œæ‰€ä»¥å¦‚æžœä½ æƒ³æŠŠéƒµä»¶è¤‡è£½åˆ°å…¶ä»–åœ°æ–¹ï¼Œ -ä½ ä¸å¾—ä¸æŠŠä»–們的權é™æ”¹çˆ²çµ„或者整體å¯è®€ã€‚ +ç•¶ä½ è¦ä¿å˜å°‡è¦ç™¼é€çš„內嵌文本補ä¸ï¼Œä½ å¯ä»¥å¾žæ¶ˆæ¯åˆ—è¡¨çª—æ ¼é¸æ“‡åŒ…å«è£œä¸çš„郵件，然 +後å³éµé¸æ“‡ :menuselection:`å¦å˜çˆ²` 。如果整個電å郵件的組æˆæ£ç¢ºï¼Œæ‚¨å¯ç›´æŽ¥å°‡ +其作爲補ä¸ä½¿ç”¨ã€‚é›»å郵件以當å‰ç”¨æˆ¶å¯è®€å¯«æ¬Šé™ä¿å˜ï¼Œå› æ¤æ‚¨å¿…é ˆ ``chmod`` ，以 +使其在複製到別處時用戶組和其他人å¯è®€ã€‚ Lotus Notes (GUI) -~~~~~~~~~~~~~~~~~ +***************** ä¸è¦ä½¿ç”¨å®ƒã€‚ +IBM Verse (Web GUI) +******************* + +åŒä¸Šæ¢ã€‚ + Mutt (TUI) -~~~~~~~~~~ +********** -很多Linux開發人員使用mutt客戶端，所以è‰æ˜Žå®ƒè‚¯å®šå·¥ä½œçš„éžå¸¸æ¼‚亮。 +很多Linux開發人員使用mutt客戶端，這è‰æ˜Žå®ƒè‚¯å®šå·¥ä½œå¾—éžå¸¸æ¼‚亮。 -Muttä¸è‡ªå¸¶ç·¨è¼¯å™¨ï¼Œæ‰€ä»¥ä¸ç®¡ä½ 使用什麼編輯器都ä¸æ‡‰è©²å¸¶æœ‰è‡ªå‹•æ–·è¡Œã€‚大多數編輯器都帶有 -一個"insert file"é¸é …，它å¯ä»¥é€šéŽä¸æ”¹è®Šæ–‡ä»¶å…§å®¹çš„æ–¹å¼æ’入文件。 +Muttä¸è‡ªå¸¶ç·¨è¼¯å™¨ï¼Œæ‰€ä»¥ä¸ç®¡ä½ 使用什麼編輯器，ä¸è‡ªå‹•æ–·è¡Œå°±è¡Œã€‚大多數編輯器都有 +:menuselection:`æ’入文件` é¸é …，它å¯ä»¥åœ¨ä¸æ”¹è®Šæ–‡ä»¶å…§å®¹çš„情æ³ä¸‹æ’入文件。 + +用 ``vim`` 作爲mutt的編輯器:: -'vim'作爲mutt的編輯器： set editor="vi" - 如果使用xclip，敲入以下命令 +如果使用xclip，敲入以下命令:: + :set paste - 按ä¸éµä¹‹å‰æˆ–者shift-insert或者使用 + +然後å†æŒ‰ä¸éµæˆ–者shift-insert或者使用:: + :r filename -如果想è¦æŠŠè£œä¸ä½œçˆ²å…§åµŒæ–‡æœ¬ã€‚ -(a)ttach工作的很好，ä¸å¸¶æœ‰"set paste"。 +把補ä¸æ’入爲內嵌文本。 +在未è¨ç½® ``set paste`` 時(a)ttach工作的很好。 ä½ å¯ä»¥é€šéŽ ``git format-patch`` 生æˆè£œä¸ï¼Œç„¶å¾Œç”¨ Mutt發é€å®ƒå€‘:: - $ mutt -H 0001-some-bug-fix.patch + $ mutt -H 0001-some-bug-fix.patch é…ç½®é¸é …： + 它應該以默èªè¨ç½®çš„å½¢å¼å·¥ä½œã€‚ -然而，把"send_charset"è¨ç½®çˆ²"us-ascii::utf-8"也是一個ä¸éŒ¯çš„主æ„。 +然而，把 ``send_charset`` è¨ç½®ä¸€ä¸‹ä¹Ÿæ˜¯ä¸€å€‹ä¸éŒ¯çš„主æ„:: -Mutt 是高度å¯é…置的。 這裡是個使用mutté€šéŽ Gmail 發é€çš„補ä¸çš„最å°é…ç½®:: + set send_charset="us-ascii:utf-8" + +Mutt 是高度å¯é…置的。 這è£æ˜¯å€‹ä½¿ç”¨mutté€šéŽ Gmail 發é€çš„補ä¸çš„最å°é…ç½®:: # .muttrc # ================ IMAP ==================== @@ -181,72 +222,108 @@ Mutt 是高度å¯é…置的。 這裡是個使用mutté€šéŽ Gmail 發é€çš„è£œä¸ set from = "username@gmail.com" set use_from = yes -Mutt文檔å«æœ‰æ›´å¤šä¿¡æ¯: +Mutt文檔å«æœ‰æ›´å¤šä¿¡æ¯ï¼š - http://dev.mutt.org/trac/wiki/UseCases/Gmail + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail - http://dev.mutt.org/doc/manual.html + http://www.mutt.org/doc/manual/ Pine (TUI) -~~~~~~~~~~ +********** PineéŽåŽ»æœ‰ä¸€äº›ç©ºæ ¼åˆªæ¸›å•é¡Œï¼Œä½†æ˜¯é€™äº›ç¾åœ¨æ‡‰è©²éƒ½è¢«ä¿®å¾©äº†ã€‚ -如果å¯ä»¥ï¼Œè«‹ä½¿ç”¨alpine(pine的繼承者) +如果å¯ä»¥ï¼Œè«‹ä½¿ç”¨alpine（pine的繼承者）。 é…ç½®é¸é …： -- 最近的版本需è¦æ¶ˆé™¤æµç¨‹æ–‡æœ¬ -- "no-strip-whitespace-before-send"é¸é …也是需è¦çš„。 + +- æœ€è¿‘çš„ç‰ˆæœ¬éœ€è¦ ``quell-flowed-text`` +- ``no-strip-whitespace-before-send`` é¸é …也是需è¦çš„。 Sylpheed (GUI) -~~~~~~~~~~~~~~ +************** - 內嵌文本å¯ä»¥å¾ˆå¥½çš„工作（或者使用附件）。 - å…許使用外部的編輯器。 -- å°æ–¼ç›®éŒ„較多時éžå¸¸æ…¢ã€‚ +- 收件箱較多時éžå¸¸æ…¢ã€‚ - 如果通éŽnon-SSL連接，無法使用TLS SMTP授權。 -- 在組æˆçª—å£ä¸æœ‰ä¸€å€‹å¾ˆæœ‰ç”¨çš„ruler bar。 -- 給地å€æœ¬ä¸æ·»åŠ 地å€å°±ä¸æœƒæ£ç¢ºçš„了解顯示å。 +- 撰寫窗å£çš„標尺很有用。 +- 將地å€æ·»åŠ 到通訊簿時無法æ£ç¢ºç†è§£é¡¯ç¤ºçš„å稱。 Thunderbird (GUI) -~~~~~~~~~~~~~~~~~ +***************** + +Thunderbird是Outlook的克隆版本，它很容易æ壞文本，但也有一些方法強制修æ£ã€‚ + +在完æˆä¿®æ”¹å¾Œï¼ˆåŒ…括安è£æ“´å±•ï¼‰ï¼Œæ‚¨éœ€è¦é‡æ–°å•“å‹•Thunderbird。 + +- å…許使用外部編輯器： + + 使用Thunderbird發補ä¸æœ€ç°¡å–®çš„方法是使用擴展來打開您最喜æ¡çš„外部編輯器。 + + 下é¢æ˜¯ä¸€äº›èƒ½å¤ åšåˆ°é€™ä¸€é»žçš„擴展樣例。 + + - “External Editor Revived†+ + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + 它需è¦å®‰è£â€œæœ¬åœ°æ¶ˆæ¯ä¸»æ©Ÿï¼ˆnative messaging host）â€ã€‚ + åƒè¦‹ä»¥ä¸‹æ–‡æª”: + https://github.com/Frederick888/external-editor-revived/wiki + + - “External Editor†+ + https://github.com/exteditor/exteditor + + 下載並安è£æ¤æ“´å±•ï¼Œç„¶å¾Œæ‰“é–‹ :menuselection:`新建消æ¯` 窗å£, 用 + :menuselection:`查看-->工具欄-->自定義...` çµ¦å®ƒå¢žåŠ ä¸€å€‹æŒ‰éˆ•ï¼Œç›´æŽ¥é»žæ“Šæ¤ + 按鈕å³å¯ä½¿ç”¨å¤–置編輯器。 + + 請注æ„，“External Editorâ€è¦æ±‚ä½ çš„ç·¨è¼¯å™¨ä¸èƒ½fork，æ›å¥è©±èªªï¼Œç·¨è¼¯å™¨å¿…é ˆåœ¨ + 關閉å‰ä¸è¿”å›žã€‚ä½ å¯èƒ½éœ€è¦å‚³éžé¡å¤–çš„åƒæ•¸æˆ–修改編輯器è¨ç½®ã€‚最值得注æ„的是， + 如果您使用的是gvimï¼Œé‚£éº¼æ‚¨å¿…é ˆå°‡ :menuselection:`external editor` è¨ç½®çš„ + 編輯器å—段è¨ç½®çˆ² ``/usr/bin/gvim --nofork"`` （å‡è¨å¯åŸ·è¡Œæ–‡ä»¶åœ¨ + ``/usr/bin`` ï¼‰ï¼Œä»¥å‚³éž ``-f`` åƒæ•¸ã€‚如果您æ£åœ¨ä½¿ç”¨å…¶ä»–編輯器，請閱讀其 + 手冊çžè§£å¦‚何處ç†ã€‚ -默èªæƒ…æ³ä¸‹ï¼Œthunderbird很容易æ壞文本，但是還有一些方法å¯ä»¥å¼·åˆ¶å®ƒè®Šå¾—更好。 +è‹¥è¦ä¿®æ£å…§éƒ¨ç·¨è¼¯å™¨ï¼Œè«‹åŸ·è¡Œä»¥ä¸‹æ“作： -- 在用戶帳號è¨ç½®é‡Œï¼Œçµ„æˆå’Œå°‹å€ï¼Œä¸è¦é¸æ“‡"Compose messages in HTML format"。 +- ä¿®æ”¹ä½ çš„Thunderbirdè¨ç½®ï¼Œä¸è¦ä½¿ç”¨ ``format=flowed`` ï¼ + 回到主窗å£ï¼ŒæŒ‰ç…§ + :menuselection:`主èœå–®-->首é¸é …-->常è¦-->é…置編輯器...` + 打開Thunderbirdçš„é…置編輯器。 -- ç·¨è¼¯ä½ çš„Thunderbirdé…ç½®è¨ç½®ä¾†ä½¿å®ƒä¸è¦æ‹†è¡Œä½¿ç”¨ï¼šuser_pref("mailnews.wraplength", 0); + - å°‡ ``mailnews.send_plaintext_flowed`` è¨çˆ² ``false`` -- ç·¨è¼¯ä½ çš„Thunderbirdé…ç½®è¨ç½®ï¼Œä½¿å®ƒä¸è¦ä½¿ç”¨"format=flowed"æ ¼å¼ï¼šuser_pref("mailnews. - send_plaintext_flowed", false); + - å°‡ ``mailnews.wraplength`` 從 ``72`` 改爲 ``0`` -- ä½ éœ€è¦ä½¿Thunderbird變爲é å…ˆæ ¼å¼æ–¹å¼ï¼š - 如果默èªæƒ…æ³ä¸‹ä½ 書寫的是HTMLæ ¼å¼ï¼Œé‚£ä¸æ˜¯å¾ˆé›£ã€‚僅僅從標題欄的下拉框ä¸é¸æ“‡"Preformat"æ ¼å¼ã€‚ - 如果默èªæƒ…æ³ä¸‹ä½ æ›¸å¯«çš„æ˜¯æ–‡æœ¬æ ¼å¼ï¼Œä½ ä¸å¾—把它改爲HTMLæ ¼å¼ï¼ˆåƒ…僅作爲一次性的）來書寫新的消æ¯ï¼Œ - ç„¶å¾Œå¼·åˆ¶ä½¿å®ƒå›žåˆ°æ–‡æœ¬æ ¼å¼ï¼Œå¦å‰‡å®ƒå°±æœƒæ‹†è¡Œã€‚è¦å¯¦ç¾å®ƒï¼Œåœ¨å¯«ä¿¡çš„圖標上使用shiftéµä¾†ä½¿å®ƒè®Šçˆ²HTML - æ ¼å¼ï¼Œç„¶å¾Œæ¨™é¡Œæ¬„的下拉框ä¸é¸æ“‡"Preformat"æ ¼å¼ã€‚ +- ä¸è¦å¯«HTMLéƒµä»¶ï¼ + 回到主窗å£ï¼Œæ‰“é–‹ + :menuselection:`主èœå–®-->賬戶è¨ç½®-->ä½ çš„@郵件.地å€-->通訊錄/編寫&地å€ç°¿` ， + 關掉 ``以HTMLæ ¼å¼ç·¨å¯«æ¶ˆæ¯`` 。 -- å…許使用外部的編輯器： - é‡å°Thunderbird打補ä¸æœ€ç°¡å–®çš„方法就是使用一個"external editor"æ“´å±•ï¼Œç„¶å¾Œä½¿ç”¨ä½ æœ€å–œæ¡çš„ - $EDITOR來讀å–或者åˆä½µè£œä¸åˆ°æ–‡æœ¬ä¸ã€‚è¦å¯¦ç¾å®ƒï¼Œå¯ä»¥ä¸‹è¼‰ä¸¦ä¸”安è£é€™å€‹æ“´å±•ï¼Œç„¶å¾Œæ·»åŠ 一個使用它的 - 按éµView->Toolbars->Customize...æœ€å¾Œç•¶ä½ æ›¸å¯«ä¿¡æ¯çš„時候僅僅點擊它就å¯ä»¥äº†ã€‚ +- åªç”¨ç´”æ–‡æœ¬æ ¼å¼æŸ¥çœ‹éƒµä»¶ï¼ + 回到主窗å£ï¼Œ :menuselection:`主èœå–®-->查看-->消æ¯é«”爲-->純文本` ï¼ TkRat (GUI) -~~~~~~~~~~~ +*********** å¯ä»¥ä½¿ç”¨å®ƒã€‚使用"Insert file..."或者外部的編輯器。 Gmail (Web GUI) -~~~~~~~~~~~~~~~ +*************** ä¸è¦ä½¿ç”¨å®ƒç™¼é€è£œä¸ã€‚ -Gmail網é 客戶端自動地把制表符轉æ›çˆ²ç©ºæ ¼ã€‚ +Gmail網é 客戶端自動地把製表符轉æ›çˆ²ç©ºæ ¼ã€‚ -雖然制表符轉æ›çˆ²ç©ºæ ¼å•é¡Œå¯ä»¥è¢«å¤–部編輯器解決，åŒæ™‚它還會使用回車æ›è¡ŒæŠŠæ¯è¡Œæ‹†åˆ†çˆ²78個å—符。 +雖然製表符轉æ›çˆ²ç©ºæ ¼å•é¡Œå¯ä»¥è¢«å¤–部編輯器解決，但它åŒæ™‚還會使用回車æ›è¡ŒæŠŠæ¯è¡Œ +拆分爲78個å—符。 -å¦ä¸€å€‹å•é¡Œæ˜¯Gmail還會把任何ä¸æ˜¯ASCIIçš„å—符的信æ¯æ”¹çˆ²base64編碼。它把æ±è¥¿è®Šçš„åƒæ洲人的åå—。 +å¦ä¸€å€‹å•é¡Œæ˜¯Gmail還會把任何å«æœ‰éžASCIIçš„å—符的消æ¯æ”¹ç”¨base64編碼，如æ洲人的 +åå—。 - ### diff --git a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst index 8e4db8baa0d1..b9f6ab7b6666 100644 --- a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst @@ -6,17 +6,17 @@ :Translator: Alex Shi <alex.shi@linux.alibaba.com> Hu Haowen <src.res.211@gmail.com> -被é™åˆ¶çš„硬體å•é¡Œ +被é™åˆ¶çš„硬件å•é¡Œ ================ ç¯„åœ ---- -導致安全å•é¡Œçš„硬體å•é¡Œèˆ‡åªå½±éŸ¿Linuxå…§æ ¸çš„ç´”è»Ÿé«”éŒ¯èª¤æ˜¯ä¸åŒçš„安全錯誤類別。 +導致安全å•é¡Œçš„硬件å•é¡Œèˆ‡éš»å½±éŸ¿Linuxå…§æ ¸çš„ç´”è»Ÿä»¶éŒ¯èª¤æ˜¯ä¸åŒçš„安全錯誤類別。 -å¿…é ˆå€åˆ¥å°å¾…諸如熔毀(Meltdown)ã€Spectreã€L1TFç‰ç¡¬é«”å•é¡Œï¼Œå› 爲它們通常會影響 -所有作æ¥ç³»çµ±ï¼ˆã€ŒOSã€ï¼‰ï¼Œå› æ¤éœ€è¦åœ¨ä¸åŒçš„OS供應商ã€ç™¼è¡Œç‰ˆã€ç¡¬é«”供應商和其他å„æ–¹ -之間進行å”調。å°æ–¼æŸäº›å•é¡Œï¼Œè»Ÿé«”緩解å¯èƒ½ä¾è³´æ–¼å¾®ç¢¼æˆ–固件更新，這需è¦é€²ä¸€æ¥çš„ +å¿…é ˆå€åˆ¥å°å¾…諸如熔燬(Meltdown)ã€Spectreã€L1TFç‰ç¡¬ä»¶å•é¡Œï¼Œå› 爲它們通常會影響 +所有æ“作系統（“OSâ€ï¼‰ï¼Œå› æ¤éœ€è¦åœ¨ä¸åŒçš„OS供應商ã€ç™¼è¡Œç‰ˆã€ç¡¬ä»¶ä¾›æ‡‰å•†å’Œå…¶ä»–å„æ–¹ +之間進行å”調。å°æ–¼æŸäº›å•é¡Œï¼Œè»Ÿä»¶ç·©è§£å¯èƒ½ä¾è³´æ–¼å¾®ç¢¼æˆ–固件更新，這需è¦é€²ä¸€æ¥çš„ å”調。 .. _tw_Contact: @@ -24,9 +24,9 @@ 接觸 ---- -Linuxå…§æ ¸ç¡¬é«”å®‰å…¨å°çµ„ç¨ç«‹æ–¼æ™®é€šçš„Linuxå…§æ ¸å®‰å…¨å°çµ„。 +Linuxå…§æ ¸ç¡¬ä»¶å®‰å…¨å°çµ„ç¨ç«‹æ–¼æ™®é€šçš„Linuxå…§æ ¸å®‰å…¨å°çµ„。 -該å°çµ„åªè² 責å”調被é™åˆ¶çš„硬體安全å•é¡Œã€‚Linuxå…§æ ¸ä¸ç´”軟體安全æ¼æ´žçš„å ±å‘Šä¸ç”±è©² +該å°çµ„åªè² 責å”調被é™åˆ¶çš„硬件安全å•é¡Œã€‚Linuxå…§æ ¸ä¸ç´”軟件安全æ¼æ´žçš„å ±å‘Šä¸ç”±è©² å°çµ„處ç†ï¼Œå ±å‘Šè€…將被引導至常è¦Linuxå…§æ ¸å®‰å…¨å°çµ„(:ref:`Documentation/admin-guide/ <securitybugs>`)è¯ç¹«ã€‚ @@ -37,13 +37,13 @@ Linuxå…§æ ¸ç¡¬é«”å®‰å…¨å°çµ„ç¨ç«‹æ–¼æ™®é€šçš„Linuxå…§æ ¸å®‰å…¨å°çµ„。 者的PGP密鑰或S/MIMEè‰æ›¸ç±¤å。該列表的PGP密鑰和S/MIMEè‰æ›¸å¯å¾ž https://www.kernel.org/.... ç²å¾—。 -雖然硬體安全å•é¡Œé€šå¸¸ç”±å—影響的硬體供應商處ç†ï¼Œä½†æˆ‘們æ¡è¿Žç™¼ç¾æ½›åœ¨ç¡¬é«”ç¼ºé™·çš„ç ”ç©¶ +雖然硬件安全å•é¡Œé€šå¸¸ç”±å—影響的硬件供應商處ç†ï¼Œä½†æˆ‘們æ¡è¿Žç™¼ç¾æ½›åœ¨ç¡¬ä»¶ç¼ºé™·çš„ç ”ç©¶ 人員或個人與我們è¯ç¹«ã€‚ -硬體安全官 +硬件安全官 ^^^^^^^^^^ -ç›®å‰çš„硬體安全官å°çµ„: +ç›®å‰çš„硬件安全官å°çµ„: - Linus Torvalds（Linux基金會院士） - Greg Kroah Hartman（Linux基金會院士） @@ -62,50 +62,50 @@ Linux基金會目å‰çš„IT基礎è¨æ–½å®‰å…¨ç¸½ç›£æ˜¯ Konstantin Ryabitsev。 ä¿å¯†å”è° -------- -Linuxå…§æ ¸ç¡¬é«”å®‰å…¨å°çµ„ä¸æ˜¯æ£å¼çš„æ©Ÿæ§‹ï¼Œå› æ¤ç„¡æ³•ç°½è¨‚任何ä¿å¯†å”è°ã€‚æ ¸å¿ƒç¤¾å€æ„è˜åˆ° +Linuxå…§æ ¸ç¡¬ä»¶å®‰å…¨å°çµ„ä¸æ˜¯æ£å¼çš„æ©Ÿæ§‹ï¼Œå› æ¤ç„¡æ³•ç°½è¨‚任何ä¿å¯†å”è°ã€‚æ ¸å¿ƒç¤¾å€æ„è˜åˆ° 這些å•é¡Œçš„æ•æ„Ÿæ€§ï¼Œä¸¦æ供了一份諒解備忘錄。 諒解備忘錄 ---------- -Linuxå…§æ ¸ç¤¾å€æ·±åˆ»ç†è§£åœ¨ä¸åŒä½œæ¥ç³»çµ±ä¾›æ‡‰å•†ã€ç™¼è¡Œå•†ã€ç¡¬é«”供應商和其他å„方之間 -進行å”調時，ä¿æŒç¡¬é«”安全å•é¡Œè™•æ–¼é™åˆ¶ç‹€æ…‹çš„è¦æ±‚。 +Linuxå…§æ ¸ç¤¾å€æ·±åˆ»ç†è§£åœ¨ä¸åŒæ“作系統供應商ã€ç™¼è¡Œå•†ã€ç¡¬ä»¶ä¾›æ‡‰å•†å’Œå…¶ä»–å„方之間 +進行å”調時，ä¿æŒç¡¬ä»¶å®‰å…¨å•é¡Œè™•æ–¼é™åˆ¶ç‹€æ…‹çš„è¦æ±‚。 -Linuxå…§æ ¸ç¤¾å€åœ¨éŽåŽ»å·²ç¶“æˆåŠŸåœ°è™•ç†äº†ç¡¬é«”安全å•é¡Œï¼Œä¸¦ä¸”有必è¦çš„機制å…許在é™åˆ¶ +Linuxå…§æ ¸ç¤¾å€åœ¨éŽåŽ»å·²ç¶“æˆåŠŸåœ°è™•ç†äº†ç¡¬ä»¶å®‰å…¨å•é¡Œï¼Œä¸¦ä¸”有必è¦çš„機制å…許在é™åˆ¶ é™åˆ¶ä¸‹é€²è¡Œç¬¦åˆç¤¾å€çš„開發。 -Linuxå…§æ ¸ç¤¾å€æœ‰ä¸€å€‹å°ˆé–€çš„硬體安全å°çµ„è² è²¬åˆå§‹è¯ç¹«ï¼Œä¸¦ç›£ç£åœ¨é™åˆ¶è¦å‰‡ä¸‹è™•ç† +Linuxå…§æ ¸ç¤¾å€æœ‰ä¸€å€‹å°ˆé–€çš„硬件安全å°çµ„è² è²¬åˆå§‹è¯ç¹«ï¼Œä¸¦ç›£ç£åœ¨é™åˆ¶è¦å‰‡ä¸‹è™•ç† æ¤é¡žå•é¡Œçš„éŽç¨‹ã€‚ -硬體安全å°çµ„ç¢ºå®šé–‹ç™¼äººå“¡ï¼ˆé ˜åŸŸå°ˆå®¶ï¼‰ï¼Œä»–å€‘å°‡çµ„æˆç‰¹å®šå•é¡Œçš„åˆå§‹éŸ¿æ‡‰å°çµ„ã€‚æœ€åˆ +硬件安全å°çµ„ç¢ºå®šé–‹ç™¼äººå“¡ï¼ˆé ˜åŸŸå°ˆå®¶ï¼‰ï¼Œä»–å€‘å°‡çµ„æˆç‰¹å®šå•é¡Œçš„åˆå§‹éŸ¿æ‡‰å°çµ„ã€‚æœ€åˆ çš„éŸ¿æ‡‰å°çµ„å¯ä»¥å¼•å…¥æ›´å¤šçš„é–‹ç™¼äººå“¡ï¼ˆé ˜åŸŸå°ˆå®¶ï¼‰ä»¥æœ€ä½³çš„æŠ€è¡“æ–¹å¼è§£æ±ºé€™å€‹å•é¡Œã€‚ 所有相關開發商承諾éµå®ˆé™åˆ¶è¦å®šï¼Œä¸¦å°æ”¶åˆ°çš„ä¿¡æ¯ä¿å¯†ã€‚é•å承諾將導致立å³å¾žç•¶å‰ -å•é¡Œä¸æŽ’除，並從所有相關郵件列表ä¸åˆªé™¤ã€‚æ¤å¤–，硬體安全å°çµ„還將把é•å者排除在 +å•é¡Œä¸æŽ’除，並從所有相關郵件列表ä¸åˆªé™¤ã€‚æ¤å¤–，硬件安全å°çµ„還將把é•å者排除在 未來的å•é¡Œä¹‹å¤–。這一後果的影響在我們社å€æ˜¯ä¸€ç¨®éžå¸¸æœ‰æ•ˆçš„å¨æ‡¾ã€‚如果發生é•è¦ -情æ³ï¼Œç¡¬é«”安全å°çµ„將立å³é€šçŸ¥ç›¸é—œæ–¹ã€‚如果您或任何人發ç¾æ½›åœ¨çš„é•è¦è¡Œçˆ²ï¼Œè«‹ç«‹å³ -å‘ç¡¬é«”å®‰å…¨äººå“¡å ±å‘Šã€‚ +情æ³ï¼Œç¡¬ä»¶å®‰å…¨å°çµ„將立å³é€šçŸ¥ç›¸é—œæ–¹ã€‚如果您或任何人發ç¾æ½›åœ¨çš„é•è¦è¡Œçˆ²ï¼Œè«‹ç«‹å³ +å‘ç¡¬ä»¶å®‰å…¨äººå“¡å ±å‘Šã€‚ æµç¨‹ ^^^^ -由於Linuxå…§æ ¸é–‹ç™¼çš„å…¨çƒåˆ†å¸ƒå¼ç‰¹æ€§ï¼Œé¢å°é¢çš„會è°å¹¾ä¹Žä¸å¯èƒ½è§£æ±ºç¡¬é«”安全å•é¡Œã€‚ +由於Linuxå…§æ ¸é–‹ç™¼çš„å…¨çƒåˆ†ä½ˆå¼ç‰¹æ€§ï¼Œé¢å°é¢çš„會è°å¹¾ä¹Žä¸å¯èƒ½è§£æ±ºç¡¬ä»¶å®‰å…¨å•é¡Œã€‚ 由於時å€å’Œå…¶ä»–å› ç´ ï¼Œé›»è©±æœƒè°å¾ˆé›£å”調，åªèƒ½åœ¨çµ•å°å¿…è¦æ™‚ä½¿ç”¨ã€‚åŠ å¯†é›»å郵件已被 è‰æ˜Žæ˜¯è§£æ±ºæ¤é¡žå•é¡Œçš„最有效和最安全的通信方法。 開始披露 """""""" -披露內容首先通éŽé›»å郵件è¯ç¹«Linuxå…§æ ¸ç¡¬é«”å®‰å…¨å°çµ„。æ¤åˆå§‹è¯ç¹«äººæ‡‰åŒ…å«å•é¡Œçš„ -æ述和任何已知å—å½±éŸ¿ç¡¬é«”çš„åˆ—è¡¨ã€‚å¦‚æžœæ‚¨çš„çµ„ç¹”è£½é€ æˆ–åˆ†ç™¼å—å½±éŸ¿çš„ç¡¬é«”ï¼Œæˆ‘å€‘å»ºè° -您也考慮哪些其他硬體å¯èƒ½æœƒå—到影響。 +披露內容首先通éŽé›»å郵件è¯ç¹«Linuxå…§æ ¸ç¡¬ä»¶å®‰å…¨å°çµ„。æ¤åˆå§‹è¯ç¹«äººæ‡‰åŒ…å«å•é¡Œçš„ +æ述和任何已知å—å½±éŸ¿ç¡¬ä»¶çš„åˆ—è¡¨ã€‚å¦‚æžœæ‚¨çš„çµ„ç¹”è£½é€ æˆ–åˆ†ç™¼å—å½±éŸ¿çš„ç¡¬ä»¶ï¼Œæˆ‘å€‘å»ºè° +您也考慮哪些其他硬件å¯èƒ½æœƒå—到影響。 -硬體安全å°çµ„å°‡æä¾›ä¸€å€‹ç‰¹å®šæ–¼äº‹ä»¶çš„åŠ å¯†éƒµä»¶åˆ—è¡¨ï¼Œç”¨æ–¼èˆ‡å ±å‘Šè€…é€²è¡Œåˆæ¥è¨Žè«–〠+硬件安全å°çµ„å°‡æä¾›ä¸€å€‹ç‰¹å®šæ–¼äº‹ä»¶çš„åŠ å¯†éƒµä»¶åˆ—è¡¨ï¼Œç”¨æ–¼èˆ‡å ±å‘Šè€…é€²è¡Œåˆæ¥è¨Žè«–〠進一æ¥æŠ«éœ²å’Œå”調。 -硬體安全å°çµ„å°‡å‘披露方æä¾›ä¸€ä»½é–‹ç™¼äººå“¡ï¼ˆé ˜åŸŸå°ˆå®¶ï¼‰å單，在與開發人員確èªä»–們 +硬件安全å°çµ„å°‡å‘披露方æä¾›ä¸€ä»½é–‹ç™¼äººå“¡ï¼ˆé ˜åŸŸå°ˆå®¶ï¼‰å單，在與開發人員確èªä»–們 å°‡éµå®ˆæœ¬è«’解備忘錄和文件化æµç¨‹å¾Œï¼Œæ‡‰é¦–先告知開發人員有關該å•é¡Œçš„ä¿¡æ¯ã€‚這些開發 -人員組æˆåˆå§‹éŸ¿æ‡‰å°çµ„，並在åˆå§‹æŽ¥è§¸å¾Œè² 責處ç†å•é¡Œã€‚硬體安全å°çµ„支æŒéŸ¿æ‡‰å°çµ„， +人員組æˆåˆå§‹éŸ¿æ‡‰å°çµ„，並在åˆå§‹æŽ¥è§¸å¾Œè² 責處ç†å•é¡Œã€‚硬件安全å°çµ„支æŒéŸ¿æ‡‰å°çµ„， 但ä¸ä¸€å®šåƒèˆ‡ç·©è§£é–‹ç™¼éŽç¨‹ã€‚ 雖然個別開發人員å¯èƒ½é€šéŽå…¶åƒ±ä¸»å—到ä¿å¯†å”è°çš„ä¿è·ï¼Œä½†ä»–們ä¸èƒ½ä»¥Linuxå…§æ ¸é–‹ç™¼ @@ -113,7 +113,7 @@ Linuxå…§æ ¸ç¤¾å€æœ‰ä¸€å€‹å°ˆé–€çš„硬體安全å°çµ„è² è²¬åˆå§‹è¯ç¹«ï¼Œä¸¦ç›£ 披露方應æ供已經或應該被告知該å•é¡Œçš„所有其他實體的è¯ç¹«äººå單。這有幾個目的: - - 披露的實體列表å…許跨行æ¥é€šä¿¡ï¼Œä¾‹å¦‚其他作æ¥ç³»çµ±ä¾›æ‡‰å•†ã€ç¡¬é«”供應商ç‰ã€‚ + - 披露的實體列表å…許跨行æ¥é€šä¿¡ï¼Œä¾‹å¦‚其他æ“作系統供應商ã€ç¡¬ä»¶ä¾›æ‡‰å•†ç‰ã€‚ - å¯è¯ç¹«å·²æŠ«éœ²çš„實體，指定應åƒèˆ‡ç·©è§£æŽªæ–½é–‹ç™¼çš„專家。 @@ -133,10 +133,10 @@ Linuxå…§æ ¸ç¤¾å€æœ‰ä¸€å€‹å°ˆé–€çš„硬體安全å°çµ„è² è²¬åˆå§‹è¯ç¹«ï¼Œä¸¦ç›£ åˆå§‹éŸ¿æ‡‰å°çµ„è¨ç½®åŠ 密郵件列表，或在é©ç•¶çš„情æ³ä¸‹é‡æ–°ä¿®æ”¹ç¾æœ‰éƒµä»¶åˆ—表。 -使用郵件列表接近於æ£å¸¸çš„Linux開發éŽç¨‹ï¼Œä¸¦ä¸”在éŽåŽ»å·²ç¶“æˆåŠŸåœ°ç”¨æ–¼çˆ²å„種硬體安全 +使用郵件列表接近於æ£å¸¸çš„Linux開發éŽç¨‹ï¼Œä¸¦ä¸”在éŽåŽ»å·²ç¶“æˆåŠŸåœ°ç”¨æ–¼çˆ²å„種硬件安全 å•é¡Œé–‹ç™¼ç·©è§£æŽªæ–½ã€‚ -郵件列表的æ“作方å¼èˆ‡æ£å¸¸çš„Linux開發相åŒã€‚發布ã€è¨Žè«–和審查修補程åºï¼Œå¦‚æžœåŒæ„， +郵件列表的æ“作方å¼èˆ‡æ£å¸¸çš„Linux開發相åŒã€‚發佈ã€è¨Žè«–和審查修補程åºï¼Œå¦‚æžœåŒæ„， 則應用於éžå…¬å…±gitå˜å„²åº«ï¼Œåƒèˆ‡é–‹ç™¼äººå“¡åªèƒ½é€šéŽå®‰å…¨é€£æŽ¥è¨ªå•è©²å˜å„²åº«ã€‚å˜å„²åº«åŒ…å« é‡å°ä¸»ç·šå…§æ ¸çš„ä¸»é–‹ç™¼åˆ†æ”¯ï¼Œä¸¦æ ¹æ“šéœ€è¦çˆ²ç©©å®šçš„å…§æ ¸ç‰ˆæœ¬æä¾›å‘後移æ¤åˆ†æ”¯ã€‚ @@ -155,9 +155,9 @@ Linuxå…§æ ¸ç¤¾å€æœ‰ä¸€å€‹å°ˆé–€çš„硬體安全å°çµ„è² è²¬åˆå§‹è¯ç¹«ï¼Œä¸¦ç›£ """""""" 有關å„方將å”商é™åˆ¶çµæŸçš„日期和時間。æ¤æ™‚，準備好的緩解措施集æˆåˆ°ç›¸é—œçš„å…§æ ¸æ¨¹ä¸ -並發布。 +併發布。 -雖然我們ç†è§£ç¡¬é«”安全å•é¡Œéœ€è¦å”調é™åˆ¶æ™‚間，但é™åˆ¶æ™‚間應é™åˆ¶åœ¨æ‰€æœ‰æœ‰é—œå„方制定〠+雖然我們ç†è§£ç¡¬ä»¶å®‰å…¨å•é¡Œéœ€è¦å”調é™åˆ¶æ™‚間，但é™åˆ¶æ™‚間應é™åˆ¶åœ¨æ‰€æœ‰æœ‰é—œå„方制定〠測試和準備緩解措施所需的最çŸæ™‚間內。人爲地延長é™åˆ¶æ™‚間以滿足會è°è¨Žè«–日期或其他 éžæŠ€è¡“åŽŸå› ï¼Œæœƒçµ¦ç›¸é—œçš„é–‹ç™¼äººå“¡å’ŒéŸ¿æ‡‰å°çµ„å¸¶ä¾†äº†æ›´å¤šçš„å·¥ä½œå’Œè² æ“”ï¼Œå› çˆ²è£œä¸éœ€è¦ ä¿æŒæœ€æ–°ï¼Œä»¥ä¾¿è·Ÿè¹¤æ£åœ¨é€²è¡Œçš„ä¸Šæ¸¸å…§æ ¸é–‹ç™¼ï¼Œé€™å¯èƒ½æœƒé€ æˆè¡çªçš„更改。 @@ -165,7 +165,7 @@ Linuxå…§æ ¸ç¤¾å€æœ‰ä¸€å€‹å°ˆé–€çš„硬體安全å°çµ„è² è²¬åˆå§‹è¯ç¹«ï¼Œä¸¦ç›£ CVEåˆ†é… """"""" -硬體安全å°çµ„å’Œåˆå§‹éŸ¿æ‡‰å°çµ„都ä¸åˆ†é…CVE，開發éŽç¨‹ä¹Ÿä¸éœ€è¦CVE。如果CVE是由披露方 +硬件安全å°çµ„å’Œåˆå§‹éŸ¿æ‡‰å°çµ„都ä¸åˆ†é…CVE，開發éŽç¨‹ä¹Ÿä¸éœ€è¦CVE。如果CVE是由披露方 æ供的，則å¯ç”¨æ–¼æ–‡æª”ä¸ã€‚ æµç¨‹å°ˆä½¿ @@ -196,22 +196,22 @@ CVEåˆ†é… Google Kees Cook <keescook@chromium.org> ============= ======================================================== -如果è¦å°‡æ‚¨çš„çµ„ç¹”æ·»åŠ åˆ°å°ˆä½¿åå–®ä¸ï¼Œè«‹èˆ‡ç¡¬é«”安全å°çµ„è¯ç¹«ã€‚被æåçš„å°ˆä½¿å¿…é ˆå®Œå…¨ +如果è¦å°‡æ‚¨çš„çµ„ç¹”æ·»åŠ åˆ°å°ˆä½¿åå–®ä¸ï¼Œè«‹èˆ‡ç¡¬ä»¶å®‰å…¨å°çµ„è¯ç¹«ã€‚被æåçš„å°ˆä½¿å¿…é ˆå®Œå…¨ ç†è§£å’Œæ”¯æŒæˆ‘們的éŽç¨‹ï¼Œä¸¦ä¸”在Linuxå…§æ ¸ç¤¾å€ä¸å¾ˆå®¹æ˜“è¯ç¹«ã€‚ åŠ å¯†éƒµä»¶åˆ—è¡¨ ------------ æˆ‘å€‘ä½¿ç”¨åŠ å¯†éƒµä»¶åˆ—è¡¨é€²è¡Œé€šä¿¡ã€‚é€™äº›åˆ—è¡¨çš„å·¥ä½œåŽŸç†æ˜¯ï¼Œç™¼é€åˆ°åˆ—表的電å郵件使用 -列表的PGP密鑰或列表的/MIMEè‰æ›¸é€²è¡ŒåŠ 密。郵件列表軟體å°é›»å郵件進行解密，並 +列表的PGP密鑰或列表的/MIMEè‰æ›¸é€²è¡ŒåŠ 密。郵件列表軟件å°é›»å郵件進行解密，並 使用訂閱者的PGP密鑰或S/MIMEè‰æ›¸çˆ²æ¯å€‹è¨‚閱者分別å°å…¶é€²è¡Œé‡æ–°åŠ 密。有關郵件列表 -軟體和用於確ä¿åˆ—表安全和數據ä¿è·çš„è¨ç½®çš„詳細信æ¯ï¼Œè«‹è¨ªå•: +軟件和用於確ä¿åˆ—表安全和數據ä¿è·çš„è¨ç½®çš„詳細信æ¯ï¼Œè«‹è¨ªå•: https://www.kernel.org/.... é—œéµé»ž ^^^^^^ -åˆæ¬¡æŽ¥è§¸è¦‹ :ref:`tw_Contact`. å°æ–¼ç‰¹å®šæ–¼äº‹ä»¶çš„郵件列表，密鑰和S/MIMEè‰æ›¸é€šéŽ +åˆæ¬¡æŽ¥è§¸è¦‹ :ref:`zh_Contact`. å°æ–¼ç‰¹å®šæ–¼äº‹ä»¶çš„郵件列表，密鑰和S/MIMEè‰æ›¸é€šéŽ 特定列表發é€çš„é›»å郵件傳éžçµ¦è¨‚閱者。 訂閱事件特定列表 @@ -220,8 +220,8 @@ https://www.kernel.org/.... 訂閱由響應å°çµ„處ç†ã€‚希望åƒèˆ‡é€šä¿¡çš„披露方將潛在訂戶的列表發é€çµ¦éŸ¿æ‡‰çµ„，以便 響應組å¯ä»¥é©—è‰è¨‚閱請求。 -æ¯å€‹è¨‚戶都需è¦é€šéŽé›»å郵件å‘響應å°çµ„發é€è¨‚閱請求。電åéƒµä»¶å¿…é ˆä½¿ç”¨è¨‚é–±ä¼ºæœå™¨ -çš„PGP密鑰或S/MIMEè‰æ›¸ç±¤å。如果使用PGPå¯†é‘°ï¼Œå‰‡å¿…é ˆå¾žå…¬é‘°ä¼ºæœå™¨ç²å¾—該密鑰， +æ¯å€‹è¨‚戶都需è¦é€šéŽé›»å郵件å‘響應å°çµ„發é€è¨‚閱請求。電åéƒµä»¶å¿…é ˆä½¿ç”¨è¨‚é–±æœå‹™å™¨ +çš„PGP密鑰或S/MIMEè‰æ›¸ç±¤å。如果使用PGPå¯†é‘°ï¼Œå‰‡å¿…é ˆå¾žå…¬é‘°æœå‹™å™¨ç²å¾—該密鑰， 並且ç†æƒ³æƒ…æ³ä¸‹è©²å¯†é‘°é€£æŽ¥åˆ°Linuxå…§æ ¸çš„PGP信任網。å¦è«‹åƒè¦‹: https://www.kernel.org/signature.html. diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index d742642dab01..6a0d98b2f9ee 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -13,11 +13,12 @@ .. _tw_process_index: +======================== 與Linux å…§æ ¸ç¤¾å€ä¸€èµ·å·¥ä½œ ======================== ä½ æƒ³æˆçˆ²Linuxå…§æ ¸é–‹ç™¼äººå“¡å—Žï¼Ÿæ¡è¿Žä¹‹è‡³ï¼åœ¨å¸ç¿’è¨±å¤šé—œæ–¼å…§æ ¸çš„æŠ€è¡“çŸ¥è˜çš„åŒæ™‚， -了解我們社å€çš„工作方å¼ä¹Ÿå¾ˆé‡è¦ã€‚閱讀這些文檔å¯ä»¥è®“您以更輕鬆的ã€éº»ç…©æ›´å°‘çš„ +çžè§£æˆ‘們社å€çš„工作方å¼ä¹Ÿå¾ˆé‡è¦ã€‚閱讀這些文檔å¯ä»¥è®“您以更輕鬆的ã€éº»ç…©æ›´å°‘çš„ æ–¹å¼å°‡æ›´æ”¹åˆä½µåˆ°å…§æ ¸ã€‚ 以下是æ¯ä½é–‹ç™¼äººå“¡éƒ½æ‡‰é–±è®€çš„基本指å—： @@ -49,7 +50,7 @@ management-style embargoed-hardware-issues -這些是一些總體性技術指å—，由於ä¸å¤§å¥½åˆ†é¡žè€Œæ”¾åœ¨é€™è£¡ï¼š +這些是一些總體性技術指å—，由於ä¸å¤§å¥½åˆ†é¡žè€Œæ”¾åœ¨é€™è£ï¼š .. toctree:: :maxdepth: 1 diff --git a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst index 963ecece3db1..e967089d2e1f 100644 --- a/Documentation/translations/zh_TW/process/kernel-driver-statement.rst +++ b/Documentation/translations/zh_TW/process/kernel-driver-statement.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _zh_process_statement_driver: +.. _tw_process_statement_driver: .. include:: ../disclaimer-zh_TW.rst diff --git a/Documentation/translations/zh_TW/process/license-rules.rst b/Documentation/translations/zh_TW/process/license-rules.rst index 503b6701bde4..2c43bcf2ac79 100644 --- a/Documentation/translations/zh_TW/process/license-rules.rst +++ b/Documentation/translations/zh_TW/process/license-rules.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. SPDX-License-Identifier: GPL-2.0 - .. include:: ../disclaimer-zh_TW.rst :Original: :ref:`Documentation/process/license-rules.rst <kernel_licensing>` @@ -17,10 +15,10 @@ Linuxå…§æ ¸æ ¹æ“šLICENSES/preferred/GPL-2.0ä¸æ供的GNU通用公共許å¯è‰ç （GPL-2.0）的æ¢æ¬¾æ供，並在LICENSES/exceptions/Linux-syscall-noteä¸é¡¯å¼ æ述了例外的系統調用，如COPYING文件ä¸æ‰€è¿°ã€‚ -æ¤æ–‡æª”文件æ供了如何å°æ¯å€‹æºæ–‡ä»¶é€²è¡Œæ³¨é‡‹ä»¥ä½¿å…¶è¨±å¯è‰æ¸…晰明確的說明。 +æ¤æ–‡æª”文件æä¾›çžå¦‚何å°æ¯å€‹æºæ–‡ä»¶é€²è¡Œè¨»é‡‹ä»¥ä½¿å…¶è¨±å¯è‰æ¸…晰明確的說明。 它ä¸æœƒå–ä»£å…§æ ¸çš„è¨±å¯è‰ã€‚ -å…§æ ¸åŽŸå§‹ç¢¼ä½œçˆ²ä¸€å€‹æ•´é«”é©ç”¨æ–¼COPYING文件ä¸æ述的許å¯è‰ï¼Œä½†æ˜¯å–®å€‹æºæ–‡ä»¶å¯ä»¥ +å…§æ ¸æºä»£ç¢¼ä½œçˆ²ä¸€å€‹æ•´é«”é©ç”¨æ–¼COPYING文件ä¸æ述的許å¯è‰ï¼Œä½†æ˜¯å–®å€‹æºæ–‡ä»¶å¯ä»¥ 具有ä¸åŒçš„與GPL-20兼容的許å¯è‰:: GPL-1.0+ : GNU通用公共許å¯è‰v1.0或更高版本 @@ -34,18 +32,18 @@ Linuxå…§æ ¸æ ¹æ“šLICENSES/preferred/GPL-2.0ä¸æ供的GNU通用公共許å¯è‰ç MITç‰è¨±å¯ã€‚ 用戶空間API（UAPI）é 文件æ述了用戶空間程åºèˆ‡å…§æ ¸çš„接å£ï¼Œé€™æ˜¯ä¸€ç¨®ç‰¹æ®Šæƒ…æ³ã€‚ -æ ¹æ“šå…§æ ¸COPYING文件ä¸çš„注釋，syscall接å£æ˜¯ä¸€å€‹æ˜Žç¢ºçš„邊界，它ä¸æœƒå°‡GPLè¦æ±‚ -æ“´å±•åˆ°ä»»ä½•ä½¿ç”¨å®ƒèˆ‡å…§æ ¸é€šä¿¡çš„è»Ÿé«”ã€‚ç”±æ–¼UAPIé æ–‡ä»¶å¿…é ˆåŒ…å«åœ¨å‰µå»ºåœ¨Linuxå…§æ ¸ +æ ¹æ“šå…§æ ¸COPYING文件ä¸çš„註釋，syscall接å£æ˜¯ä¸€å€‹æ˜Žç¢ºçš„邊界，它ä¸æœƒå°‡GPLè¦æ±‚ +æ“´å±•åˆ°ä»»ä½•ä½¿ç”¨å®ƒèˆ‡å…§æ ¸é€šä¿¡çš„è»Ÿä»¶ã€‚ç”±æ–¼UAPIé æ–‡ä»¶å¿…é ˆåŒ…å«åœ¨å‰µå»ºåœ¨Linuxå…§æ ¸ 上é‹è¡Œçš„å¯åŸ·è¡Œæ–‡ä»¶çš„任何æºæ–‡ä»¶ä¸ï¼Œå› æ¤æ¤ä¾‹å¤–å¿…é ˆè¨˜éŒ„åœ¨ç‰¹åˆ¥çš„è¨±å¯è‰è¡¨è¿°ä¸ã€‚ -表é”æºæ–‡ä»¶è¨±å¯è‰çš„常用方法是將匹é…的樣æ¿æ–‡æœ¬æ·»åŠ åˆ°æ–‡ä»¶çš„é ‚éƒ¨æ³¨é‡‹ä¸ã€‚由於 -æ ¼å¼ï¼Œæ‹¼å¯«éŒ¯èª¤ç‰ï¼Œé€™äº›ã€Œæ¨£æ¿ã€å¾ˆé›£é€šéŽé‚£äº›åœ¨ä¸Šä¸‹æ–‡ä¸ä½¿ç”¨çš„é©—è‰è¨±å¯è‰åˆè¦æ€§ +表é”æºæ–‡ä»¶è¨±å¯è‰çš„常用方法是將匹é…的樣æ¿æ–‡æœ¬æ·»åŠ åˆ°æ–‡ä»¶çš„é ‚éƒ¨è¨»é‡‹ä¸ã€‚由於 +æ ¼å¼ï¼Œæ‹¼å¯«éŒ¯èª¤ç‰ï¼Œé€™äº›â€œæ¨£æ¿â€å¾ˆé›£é€šéŽé‚£äº›åœ¨ä¸Šä¸‹æ–‡ä¸ä½¿ç”¨çš„é©—è‰è¨±å¯è‰åˆè¦æ€§ 的工具。 -樣æ¿æ–‡æœ¬çš„替代方法是在æ¯å€‹æºæ–‡ä»¶ä¸ä½¿ç”¨è»Ÿé«”包數據交æ›ï¼ˆSPDX）許å¯è‰æ¨™è˜ç¬¦ã€‚ +樣æ¿æ–‡æœ¬çš„替代方法是在æ¯å€‹æºæ–‡ä»¶ä¸ä½¿ç”¨è»Ÿä»¶åŒ…數據交æ›ï¼ˆSPDX）許å¯è‰æ¨™è˜ç¬¦ã€‚ SPDX許å¯è‰æ¨™è˜ç¬¦æ˜¯æ©Ÿå™¨å¯è§£æžçš„，並且是用於æ供文件內容的許å¯è‰çš„精確縮寫。 SPDX許å¯è‰æ¨™è˜ç¬¦ç”±Linux 基金會的SPDX 工作組管ç†ï¼Œä¸¦å¾—到了整個行æ¥ï¼Œå·¥å…· -供應商和法律團隊的åˆä½œå¤¥ä¼´çš„一致åŒæ„。有關詳細信æ¯ï¼Œè«‹åƒé–± +供應商和法律團隊的åˆä½œä¼™ä¼´çš„一致åŒæ„。有關詳細信æ¯ï¼Œè«‹åƒé–± https://spdx.org/ Linuxå…§æ ¸éœ€è¦æ‰€æœ‰æºæ–‡ä»¶ä¸çš„精確SPDX標è˜ç¬¦ã€‚å…§æ ¸ä¸ä½¿ç”¨çš„有效標è˜ç¬¦åœ¨ @@ -58,7 +56,7 @@ https://spdx.org/licenses/ 上的官方SPDX許å¯è‰åˆ—表ä¸æª¢ç´¢ï¼Œä¸¦é™„帶è 1.安置: -Â Â Â å…§æ ¸æ–‡ä»¶ä¸çš„SPDX許å¯è‰æ¨™è˜ç¬¦æ‡‰æ·»åŠ 到å¯åŒ…å«æ³¨é‡‹çš„文件ä¸çš„第一行。å°æ–¼å¤§å¤š +Â Â Â å…§æ ¸æ–‡ä»¶ä¸çš„SPDX許å¯è‰æ¨™è˜ç¬¦æ‡‰æ·»åŠ 到å¯åŒ…å«è¨»é‡‹çš„文件ä¸çš„第一行。å°æ–¼å¤§å¤š 數文件，這是第一行，除了那些在第一行ä¸éœ€è¦'#!PATH_TO_INTERPRETER'的腳本。 å°æ–¼é€™äº›è…³æœ¬ï¼ŒSPDX標è˜ç¬¦é€²å…¥ç¬¬äºŒè¡Œã€‚ @@ -66,7 +64,7 @@ https://spdx.org/licenses/ 上的官方SPDX許å¯è‰åˆ—表ä¸æª¢ç´¢ï¼Œä¸¦é™„帶è 2. é¢¨æ ¼: - SPDX許å¯è‰æ¨™è˜ç¬¦ä»¥æ³¨é‡‹çš„å½¢å¼æ·»åŠ 。注釋樣å¼å–決於文件類型:: + SPDX許å¯è‰æ¨™è˜ç¬¦ä»¥è¨»é‡‹çš„å½¢å¼æ·»åŠ 。註釋樣å¼å–決於文件類型:: C source: // SPDX-License-Identifier: <SPDX License Expression> C header: /* SPDX-License-Identifier: <SPDX License Expression> */ @@ -75,20 +73,20 @@ https://spdx.org/licenses/ 上的官方SPDX許å¯è‰åˆ—表ä¸æª¢ç´¢ï¼Œä¸¦é™„帶è .rst: .. SPDX-License-Identifier: <SPDX License Expression> .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> - 如果特定工具無法處ç†æ¨™æº–注釋樣å¼ï¼Œå‰‡æ‡‰ä½¿ç”¨å·¥å…·æŽ¥å—的相應注釋機制。這是在 - C é 文件ä¸ä½¿ç”¨ã€Œ/\*\*/ã€æ¨£å¼æ³¨é‡‹çš„åŽŸå› ã€‚éŽåŽ»åœ¨ä½¿ç”¨ç”Ÿæˆçš„.lds文件ä¸è§€å¯Ÿåˆ° - æ§‹å»ºè¢«ç ´å£žï¼Œå…¶ä¸'ld'無法解æžC++注釋。ç¾åœ¨å·²ç¶“解決了這個å•é¡Œï¼Œä½†ä»ç„¶æœ‰è¼ƒ - 舊的彙編程åºå·¥å…·ç„¡æ³•è™•ç†C++樣å¼çš„注釋。 + 如果特定工具無法處ç†æ¨™æº–註釋樣å¼ï¼Œå‰‡æ‡‰ä½¿ç”¨å·¥å…·æŽ¥å—的相應註釋機制。這是在 + C é 文件ä¸ä½¿ç”¨â€œ/\*\*/â€æ¨£å¼è¨»é‡‹çš„åŽŸå› ã€‚éŽåŽ»åœ¨ä½¿ç”¨ç”Ÿæˆçš„.lds文件ä¸è§€å¯Ÿåˆ° + æ§‹å»ºè¢«ç ´å£žï¼Œå…¶ä¸'ld'無法解æžC++註釋。ç¾åœ¨å·²ç¶“解決了這個å•é¡Œï¼Œä½†ä»ç„¶æœ‰è¼ƒ + 舊的彙編程åºå·¥å…·ç„¡æ³•è™•ç†C++樣å¼çš„註釋。 | 3. å¥æ³•: <SPDX許å¯è‰è¡¨é”å¼>是SPDX許å¯è‰åˆ—表ä¸çš„SPDXçŸæ ¼å¼è¨±å¯è‰æ¨™è˜ç¬¦ï¼Œæˆ–è€…åœ¨è¨±å¯ - è‰ä¾‹å¤–é©ç”¨æ™‚由「WITHã€åˆ†éš”的兩個SPDXçŸæ ¼å¼è¨±å¯è‰æ¨™è˜ç¬¦çš„組åˆã€‚當應用多個許 - å¯è‰æ™‚，表é”å¼ç”±åˆ†éš”å表é”å¼çš„é—œéµå—「ANDã€ï¼Œã€ŒORã€çµ„æˆï¼Œä¸¦ç”±ã€Œï¼ˆã€ï¼Œã€Œï¼‰ã€åŒ…åœã€‚ + è‰ä¾‹å¤–é©ç”¨æ™‚由“WITHâ€åˆ†éš”的兩個SPDXçŸæ ¼å¼è¨±å¯è‰æ¨™è˜ç¬¦çš„組åˆã€‚當應用多個許 + å¯è‰æ™‚，表é”å¼ç”±åˆ†éš”å表é”å¼çš„é—œéµå—“ANDâ€ï¼Œâ€œORâ€çµ„æˆï¼Œä¸¦ç”±â€œï¼ˆâ€ï¼Œâ€œï¼‰â€åŒ…åœã€‚ - 帶有「或更高ã€é¸é …çš„[L]GPLç‰è¨±å¯è‰çš„許å¯è‰æ¨™è˜ç¬¦é€šéŽä½¿ç”¨ã€Œ+ã€ä¾†è¡¨ç¤ºã€Œæˆ–更高〠+ 帶有“或更高â€é¸é …çš„[L]GPLç‰è¨±å¯è‰çš„許å¯è‰æ¨™è˜ç¬¦é€šéŽä½¿ç”¨â€œ+â€ä¾†è¡¨ç¤ºâ€œæˆ–更高†é¸é …來構建。:: // SPDX-License-Identifier: GPL-2.0+ @@ -230,7 +228,7 @@ https://spdx.org/licenses/ 上的官方SPDX許å¯è‰åˆ—表ä¸æª¢ç´¢ï¼Œä¸¦é™„帶è 元標籤: - 「其他ã€è¨±å¯è‰çš„元標籤è¦æ±‚與 `優先許å¯`_ çš„è¦æ±‚相åŒã€‚ + “其他â€è¨±å¯è‰çš„元標籤è¦æ±‚與 `優先許å¯`_ çš„è¦æ±‚相åŒã€‚ æ–‡ä»¶æ ¼å¼ç¤ºä¾‹:: @@ -267,8 +265,8 @@ https://spdx.org/licenses/ 上的官方SPDX許å¯è‰åˆ—表ä¸æª¢ç´¢ï¼Œä¸¦é™„帶è LICENSES/exceptions/GCC-exception-2.0 - 包å«GCC'連çµä¾‹å¤–'，它å…許ç¨ç«‹æ–¼å…¶è¨±å¯è‰çš„任何二進ä½æ–‡ä»¶èˆ‡æ¨™è¨˜æœ‰æ¤ä¾‹å¤–çš„ - 文件的編è¯ç‰ˆæœ¬é€£çµã€‚這是從GPLä¸å…¼å®¹åŽŸå§‹ç¢¼å‰µå»ºå¯é‹è¡Œçš„å¯åŸ·è¡Œæ–‡ä»¶æ‰€å¿…需的。 + 包å«GCC'éˆæŽ¥ä¾‹å¤–'，它å…許ç¨ç«‹æ–¼å…¶è¨±å¯è‰çš„任何二進制文件與標記有æ¤ä¾‹å¤–çš„ + 文件的編è¯ç‰ˆæœ¬éˆæŽ¥ã€‚這是從GPLä¸å…¼å®¹æºä»£ç¢¼å‰µå»ºå¯é‹è¡Œçš„å¯åŸ·è¡Œæ–‡ä»¶æ‰€å¿…需的。 _`例外元標記`: @@ -333,11 +331,11 @@ https://spdx.org/licenses/ 上的官方SPDX許å¯è‰åˆ—表ä¸æª¢ç´¢ï¼Œä¸¦é™„帶è _`模塊許å¯` ----------------- - å¯åŠ è¼‰å…§æ ¸æ¨¡å¡Šé‚„éœ€è¦MODULE_LICENSE（）標記。æ¤æ¨™è¨˜æ—¢ä¸æ›¿ä»£æ£ç¢ºçš„原始碼 + å¯åŠ è¼‰å…§æ ¸æ¨¡å¡Šé‚„éœ€è¦MODULE_LICENSE（）標記。æ¤æ¨™è¨˜æ—¢ä¸æ›¿ä»£æ£ç¢ºçš„æºä»£ç¢¼ 許å¯è‰ä¿¡æ¯ï¼ˆSPDX-License-Identifier），也ä¸ä»¥ä»»ä½•æ–¹å¼è¡¨ç¤ºæˆ–確定æ供模塊 - 原始碼的確切許å¯è‰ã€‚ + æºä»£ç¢¼çš„確切許å¯è‰ã€‚ - æ¤æ¨™è¨˜çš„唯一目的是æä¾›è¶³å¤ çš„ä¿¡æ¯ï¼Œè©²æ¨¡å¡Šæ˜¯å¦æ˜¯è‡ªç”±è»Ÿé«”æˆ–è€…æ˜¯å…§æ ¸æ¨¡å¡ŠåŠ + æ¤æ¨™è¨˜çš„唯一目的是æä¾›è¶³å¤ çš„ä¿¡æ¯ï¼Œè©²æ¨¡å¡Šæ˜¯å¦æ˜¯è‡ªç”±è»Ÿä»¶æˆ–è€…æ˜¯å…§æ ¸æ¨¡å¡ŠåŠ è¼‰å™¨å’Œç”¨æˆ¶ç©ºé–“å·¥å…·çš„å°ˆæœ‰æ¨¡å¡Šã€‚ MODULE_LICENSE（）的有效許å¯è‰å—符串是: @@ -365,9 +363,9 @@ _`模塊許å¯` åªèƒ½é€šéŽç›¸æ‡‰çš„æºæ–‡ä»¶ä¸çš„許å¯è‰ä¿¡æ¯ä¾†ç¢ºå®šã€‚ "Proprietary" 該模塊屬於專有許å¯ã€‚æ¤å—符串僅用於專有的第三 - 方模塊，ä¸èƒ½ç”¨æ–¼åœ¨å…§æ ¸æ¨¹ä¸å…·æœ‰åŽŸå§‹ç¢¼çš„模塊。 - 以這種方å¼æ¨™è¨˜çš„æ¨¡å¡Šåœ¨åŠ è¼‰æ™‚æœƒä½¿ç”¨'P'標記汙 - æŸ“å…§æ ¸ï¼Œä¸¦ä¸”å…§æ ¸æ¨¡å¡ŠåŠ è¼‰å™¨æ‹’çµ•å°‡é€™äº›æ¨¡å¡Šé€£çµ + 方模塊，ä¸èƒ½ç”¨æ–¼åœ¨å…§æ ¸æ¨¹ä¸å…·æœ‰æºä»£ç¢¼çš„模塊。 + 以這種方å¼æ¨™è¨˜çš„æ¨¡å¡Šåœ¨åŠ è¼‰æ™‚æœƒä½¿ç”¨'P'標記污 + æŸ“å…§æ ¸ï¼Œä¸¦ä¸”å…§æ ¸æ¨¡å¡ŠåŠ è¼‰å™¨æ‹’çµ•å°‡é€™äº›æ¨¡å¡ŠéˆæŽ¥ 到使用EXPORT_SYMBOL_GPL（）導出的符號。 ============================= ============================================= diff --git a/Documentation/translations/zh_TW/process/management-style.rst b/Documentation/translations/zh_TW/process/management-style.rst index e9d29024f4c9..f3913e3c159d 100644 --- a/Documentation/translations/zh_TW/process/management-style.rst +++ b/Documentation/translations/zh_TW/process/management-style.rst @@ -16,20 +16,20 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ 主è¦æ˜¯çˆ²äº†é¿å…åè¦†å›žç” [#cnf1]_ 相åŒï¼ˆæˆ–類似）的å•é¡Œã€‚ 管ç†é¢¨æ ¼æ˜¯éžå¸¸å€‹äººåŒ–çš„ï¼Œæ¯”ç°¡å–®çš„ç·¨ç¢¼é¢¨æ ¼è¦å‰‡æ›´é›£ä»¥é‡åŒ–ï¼Œå› æ¤æœ¬æ–‡æª”å¯èƒ½èˆ‡å¯¦ -際情æ³æœ‰é—œï¼Œä¹Ÿå¯èƒ½èˆ‡å¯¦éš›æƒ…æ³ç„¡é—œã€‚èµ·åˆå®ƒæ˜¯ä¸€å€‹çŽ©ç¬‘，但這並ä¸æ„味著它å¯èƒ½ä¸ +際情æ³æœ‰é—œï¼Œä¹Ÿå¯èƒ½èˆ‡å¯¦éš›æƒ…æ³ç„¡é—œã€‚èµ·åˆå®ƒæ˜¯ä¸€å€‹çŽ©ç¬‘，但這並ä¸æ„味ç€å®ƒå¯èƒ½ä¸ æ˜¯çœŸçš„ã€‚ä½ å¾—è‡ªå·±æ±ºå®šã€‚ -é †ä¾¿èªªä¸€å¥ï¼Œåœ¨è«‡åˆ°ã€Œæ ¸å¿ƒç®¡ç†è€…ã€æ™‚，主è¦æ˜¯æŠ€è¡“è² è²¬äººï¼Œè€Œä¸æ˜¯åœ¨å…¬å¸å…§éƒ¨é€²è¡Œå‚³ -統管ç†çš„äººã€‚å¦‚æžœä½ ç°½ç½²äº†æŽ¡è³¼è¨‚å–®æˆ–è€…å°ä½ 的團隊的é ç®—æœ‰ä»»ä½•äº†è§£ï¼Œä½ å¹¾ä¹Žè‚¯å®š +é †ä¾¿èªªä¸€å¥ï¼Œåœ¨è«‡åˆ°â€œæ ¸å¿ƒç®¡ç†è€…â€æ™‚，主è¦æ˜¯æŠ€è¡“è² è²¬äººï¼Œè€Œä¸æ˜¯åœ¨å…¬å¸å…§éƒ¨é€²è¡Œå‚³ +統管ç†çš„äººã€‚å¦‚æžœä½ ç°½ç½²äº†æŽ¡è³¼è¨‚å–®æˆ–è€…å°ä½ 的團隊的é 算有任何çžè§£ï¼Œä½ 幾乎肯定 ä¸æ˜¯ä¸€å€‹æ ¸å¿ƒç®¡ç†è€…。這些建è°å¯èƒ½é©ç”¨æ–¼æ‚¨ï¼Œä¹Ÿå¯èƒ½ä¸é©ç”¨æ–¼æ‚¨ã€‚ -首先，我建è°ä½ 購買「高效人的七個習慣ã€ï¼Œè€Œä¸æ˜¯é–±è®€å®ƒã€‚燒了它，這是一個å‰å¤§çš„ +首先，我建è°ä½ 購買“高效人的七個習慣â€ï¼Œè€Œä¸æ˜¯é–±è®€å®ƒã€‚燒了它，這是一個å‰å¤§çš„ 象徵性姿態。 .. [#cnf1] 本文件並ä¸æ˜¯é€šéŽå›žç”å•é¡Œï¼Œè€Œæ˜¯é€šéŽè®“æå•è€…痛苦地明白，我們ä¸çŸ¥é“ ç”案是什麼。 -ä¸ç®¡æ€Žæ¨£ï¼Œé€™è£¡æ˜¯ï¼š +ä¸ç®¡æ€Žæ¨£ï¼Œé€™è£æ˜¯ï¼š .. _tw_decisions: @@ -39,14 +39,14 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ æ¯å€‹äººéƒ½èªçˆ²ç®¡ç†è€…åšæ±ºå®šï¼Œè€Œä¸”決ç–很é‡è¦ã€‚決定越大越痛苦，管ç†è€…å°±å¿…é ˆè¶Šé«˜ç´šã€‚ 這很明顯，但事實並éžå¦‚æ¤ã€‚ -éŠæˆ²çš„åå—是 **é¿å…** åšå‡ºæ±ºå®šã€‚å°¤å…¶æ˜¯ï¼Œå¦‚æžœæœ‰äººå‘Šè¨´ä½ ã€Œé¸æ“‡ï¼ˆa）或（b）， -我們真的需è¦ä½ 來åšæ±ºå®šã€ï¼Œä½ 就是陷入麻煩的管ç†è€…ã€‚ä½ ç®¡ç†çš„äººæ¯”ä½ æ›´äº†è§£ç´°ç¯€ï¼Œ +最é‡è¦çš„是 **é¿å…** åšå‡ºæ±ºå®šã€‚å°¤å…¶æ˜¯ï¼Œå¦‚æžœæœ‰äººå‘Šè¨´ä½ â€œé¸æ“‡ï¼ˆa）或（b）， +我們真的需è¦ä½ 來åšæ±ºå®šâ€ï¼Œä½ 就是陷入麻煩的管ç†è€…ã€‚ä½ ç®¡ç†çš„äººæ¯”ä½ æ›´çžè§£ç´°ç¯€ï¼Œ æ‰€ä»¥å¦‚æžœä»–å€‘ä¾†æ‰¾ä½ åšæŠ€è¡“決ç–ï¼Œä½ å®Œè›‹äº†ã€‚ä½ é¡¯ç„¶æ²’æœ‰èƒ½åŠ›çˆ²ä»–å€‘åšé€™å€‹æ±ºå®šã€‚ -ï¼ˆæŽ¨è«–ï¼šå¦‚æžœä½ ç®¡ç†çš„人ä¸æ¯”ä½ æ›´äº†è§£ç´°ç¯€ï¼Œä½ ä¹Ÿæœƒè¢«æžç ¸ï¼Œå„˜ç®¡åŽŸå› 完全ä¸åŒã€‚ +ï¼ˆæŽ¨è«–ï¼šå¦‚æžœä½ ç®¡ç†çš„人ä¸æ¯”ä½ æ›´çžè§£ç´°ç¯€ï¼Œä½ 也會被æžç ¸ï¼Œå„˜ç®¡åŽŸå› 完全ä¸åŒã€‚ ä¹Ÿå°±æ˜¯èªªï¼Œä½ çš„å·¥ä½œæ˜¯éŒ¯çš„ï¼Œä»–å€‘æ‡‰è©²ç®¡ç†ä½ çš„æ‰æ™ºï¼‰ -所以éŠæˆ²çš„åå—是 **é¿å…** åšå‡ºæ±ºå®šï¼Œè‡³å°‘是那些大而痛苦的決定。åšä¸€äº›å°çš„ +所以最é‡è¦çš„是 **é¿å…** åšå‡ºæ±ºå®šï¼Œè‡³å°‘是那些大而痛苦的決定。åšä¸€äº›å°çš„ å’Œéžçµæžœæ€§çš„決定是很好的，並且使您看起來好åƒçŸ¥é“自己在åšä»€éº¼ï¼Œæ‰€ä»¥å…§æ ¸ç®¡ç†è€… 需è¦åšçš„是將那些大的和痛苦的決定變æˆé‚£äº›æ²’有人真æ£é—œå¿ƒçš„å°äº‹æƒ…。 @@ -61,7 +61,7 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ 逃離的角è½ã€‚走投無路的è€é¼ å¯èƒ½å¾ˆå±éšªâ€”—走投無路的管ç†è€…真å¯æ†ã€‚ 事實è‰æ˜Žï¼Œç”±æ–¼æ²’æœ‰äººæœƒæ„šè ¢åˆ°è®“å…§æ ¸ç®¡ç†è€…承擔巨大的財政責任，所以通常很容易 -å›žæº¯ã€‚æ—¢ç„¶ä½ ä¸å¯èƒ½æµªè²»æŽ‰ä½ 無法償還的巨é¡è³‡é‡‘ï¼Œä½ å”¯ä¸€å¯ä»¥å›žæº¯çš„就是技術決ç–， +å›žæº¯ã€‚æ—¢ç„¶ä½ ä¸å¯èƒ½æµªè²»æŽ‰ä½ 無法償還的鉅é¡è³‡é‡‘ï¼Œä½ å”¯ä¸€å¯ä»¥å›žæº¯çš„就是技術決ç–， 而回溯很容易：åªè¦å‘Šè¨´å¤§å®¶ä½ 是個ä¸ç¨±è·çš„傻瓜，說å°ä¸èµ·ï¼Œç„¶å¾Œæ’¤éŠ·ä½ 去年讓別 人所åšçš„毫無價值的工作。çªç„¶é–“ï¼Œä½ ä¸€å¹´å‰åšçš„決定ä¸åœ¨æ˜¯ä¸€å€‹é‡å¤§çš„æ±ºå®šï¼Œå› çˆ² 它很容易被推翻。 @@ -72,7 +72,7 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ 確實很難。 - å¦‚æžœæœ‰äººå‘Šè¨´ä½ ï¼Œä½ åŽ»å¹´æ‰€åšçš„工作終究是ä¸å€¼å¾—的，那麼å°é‚£äº›å¯æ†çš„低級工 程師來說也是很困難的，雖然實際的 **工作** å¾ˆå®¹æ˜“åˆªé™¤ï¼Œä½†ä½ å¯èƒ½å·²ç¶“ä¸å¯ - 挽回地失去了工程師的信任。記ä½ï¼šã€Œä¸å¯æ’¤éŠ·ã€æ˜¯æˆ‘們一開始就試圖é¿å…的， + 挽回地失去了工程師的信任。記ä½ï¼šâ€œä¸å¯æ’¤éŠ·â€æ˜¯æˆ‘們一開始就試圖é¿å…的， è€Œä½ çš„æ±ºå®šçµ‚ç©¶æ˜¯ä¸€å€‹é‡å¤§çš„決定。 ä»¤äººæ¬£æ…°çš„æ˜¯ï¼Œé€™å…©å€‹åŽŸå› éƒ½å¯ä»¥é€šéŽé 先承èªä½ 沒有任何線索，æå‰å‘Šè¨´äººå€‘ä½ çš„ @@ -80,19 +80,19 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ 的權利，並讓人們 **æ„è˜** åˆ°é€™ä¸€é»žã€‚ç•¶ä½ **還沒有** åšéŽçœŸæ£æ„šè ¢çš„事情的時 候，承èªè‡ªå·±æ˜¯æ„šè ¢çš„è¦å®¹æ˜“得多。 -然後，當它真的被è‰æ˜Žæ˜¯æ„šè ¢çš„時候，人們就轉動他們的眼ç 說「哎呀，下次ä¸è¦äº†ã€ã€‚ +然後，當它真的被è‰æ˜Žæ˜¯æ„šè ¢çš„時候，人們就轉動他們的眼ç 說“哎呀，下次ä¸è¦äº†â€ã€‚ 這種å°ä¸ç¨±è·çš„先發制人的承èªï¼Œä¹Ÿå¯èƒ½ä½¿çœŸæ£åšé€™é …工作的人也會三æ€æ˜¯å¦å€¼å¾—åšã€‚ 畢竟，如果他們ä¸ç¢ºå®šé€™æ˜¯å¦æ˜¯ä¸€å€‹å¥½ä¸»æ„ï¼Œä½ è‚¯å®šä¸æ‡‰è©²é€šéŽå‘他們ä¿è‰ä»–å€‘æ‰€åš çš„å·¥ä½œå°‡æœƒé€²å…¥ï¼ˆå…§æ ¸ï¼‰é¼“å‹µä»–å€‘ã€‚åœ¨ä»–å€‘é–‹å§‹ä¸€é …å·¨å¤§çš„åŠªåŠ›ä¹‹å‰ï¼Œè‡³å°‘讓他們三 æ€è€Œå¾Œè¡Œã€‚ -記ä½ï¼šä»–å€‘æœ€å¥½æ¯”ä½ æ›´äº†è§£ç´°ç¯€ï¼Œè€Œä¸”ä»–å€‘é€šå¸¸èªçˆ²ä»–們å°æ¯ä»¶äº‹éƒ½æœ‰ç”案。作爲一 +記ä½ï¼šä»–å€‘æœ€å¥½æ¯”ä½ æ›´çžè§£ç´°ç¯€ï¼Œè€Œä¸”他們通常èªçˆ²ä»–們å°æ¯ä»¶äº‹éƒ½æœ‰ç”案。作爲一 個管ç†è€…ï¼Œä½ èƒ½åšçš„最好的事情ä¸æ˜¯çŒè¼¸è‡ªä¿¡ï¼Œè€Œæ˜¯å°ä»–們所åšçš„事情進行å¥åº·çš„批 判性æ€è€ƒã€‚ -é †ä¾¿èªªä¸€å¥ï¼Œå¦ä¸€ç¨®é¿å…åšå‡ºæ±ºå®šçš„方法是看起來很å¯æ†çš„抱怨 「我們ä¸èƒ½å…©è€…å…¼ -得嗎？〠相信我，它是有效的。如果ä¸æ¸…楚哪種方法更好，他們最終會弄清楚的。 +é †ä¾¿èªªä¸€å¥ï¼Œå¦ä¸€ç¨®é¿å…åšå‡ºæ±ºå®šçš„方法是看起來很å¯æ†çš„抱怨 “我們ä¸èƒ½å…©è€…å…¼ +得嗎？†相信我，它是有效的。如果ä¸æ¸…楚哪種方法更好，他們最終會弄清楚的。 最終的ç”案å¯èƒ½æ˜¯å…©å€‹åœ˜éšŠéƒ½æœƒå› 爲這種情æ³è€Œæ„Ÿåˆ°æ²®å–ªï¼Œä»¥è‡³æ–¼ä»–們放棄了。 這è½èµ·ä¾†åƒæ˜¯ä¸€å€‹å¤±æ•—ï¼Œä½†é€™é€šå¸¸æ˜¯ä¸€å€‹è·¡è±¡ï¼Œè¡¨æ˜Žå…©å€‹é …ç›®éƒ½æœ‰å•é¡Œï¼Œè€Œåƒèˆ‡å…¶ä¸ @@ -102,7 +102,7 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ 2）人 ----- -大多數人都是白癡，åšä¸€å管ç†è€…æ„å‘³è‘—ä½ å¿…é ˆè™•ç†å¥½é€™ä»¶äº‹ï¼Œä¹Ÿè¨±æ›´é‡è¦çš„是, +大多數人都是白癡，åšä¸€å管ç†è€…æ„味ç€ä½ å¿…é ˆè™•ç†å¥½é€™ä»¶äº‹ï¼Œä¹Ÿè¨±æ›´é‡è¦çš„是, **他們** å¿…é ˆè™•ç†å¥½ä½ 。 事實è‰æ˜Žï¼Œé›–然很容易糾æ£æŠ€è¡“錯誤，但ä¸å®¹æ˜“ç³¾æ£äººæ ¼éšœç¤™ã€‚ä½ åªèƒ½å’Œä»–們的和 @@ -110,16 +110,16 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ 但是，爲了åšå¥½ä½œçˆ²å…§æ ¸ç®¡ç†è€…的準備，最好記ä½ä¸è¦ç‡’掉任何橋樑，ä¸è¦è½Ÿç‚¸ä»»ä½• 無辜的æ‘民，也ä¸è¦ç–é å¤ªå¤šçš„å…§æ ¸é–‹ç™¼äººå“¡ã€‚äº‹å¯¦è‰æ˜Žï¼Œç–é 人是相當容易的，而 -親近一個ç–é çš„äººæ˜¯å¾ˆé›£çš„ã€‚å› æ¤ï¼Œã€Œç–é ã€ç«‹å³å±¬æ–¼ã€Œä¸å¯é€†ã€çš„ç¯„ç–‡ï¼Œä¸¦æ ¹æ“š +親近一個ç–é çš„äººæ˜¯å¾ˆé›£çš„ã€‚å› æ¤ï¼Œâ€œç–é â€ç«‹å³å±¬æ–¼â€œä¸å¯é€†â€çš„ç¯„ç–‡ï¼Œä¸¦æ ¹æ“š :ref:`tw_decisions` æˆçˆ²çµ•ä¸å¯ä»¥åšçš„事情。 -這裡åªæœ‰å¹¾å€‹ç°¡å–®çš„è¦å‰‡ï¼š +這è£åªæœ‰å¹¾å€‹ç°¡å–®çš„è¦å‰‡ï¼š (1) ä¸è¦å«äººç¬¨è›‹ï¼ˆè‡³å°‘ä¸è¦åœ¨å…¬å…±å ´åˆï¼‰ (2) å¸ç¿’如何在忘記è¦å‰‡(1)時é“æ‰ -å•é¡Œåœ¨æ–¼ #1 很容易去åšï¼Œå› çˆ²ä½ å¯ä»¥ç”¨æ•¸ç™¾è¬ç¨®ä¸åŒçš„æ–¹å¼èªªã€Œä½ 是一個笨蛋〠[#cnf2]_ -有時甚至沒有æ„è˜åˆ°ï¼Œè€Œä¸”幾乎總是帶著一種白熱化的信念，èªçˆ²ä½ 是å°çš„。 +å•é¡Œåœ¨æ–¼ #1 很容易去åšï¼Œå› çˆ²ä½ å¯ä»¥ç”¨æ•¸ç™¾è¬ç¨®ä¸åŒçš„æ–¹å¼èªªâ€œä½ 是一個笨蛋†[#cnf2]_ +有時甚至沒有æ„è˜åˆ°ï¼Œè€Œä¸”幾乎總是帶ç€ä¸€ç¨®ç™½ç†±åŒ–的信念，èªçˆ²ä½ 是å°çš„。 ä½ è¶Šç¢ºä¿¡è‡ªå·±æ˜¯å°çš„（讓我們é¢å°ç¾å¯¦å§ï¼Œä½ å¯ä»¥æŠŠå¹¾ä¹Žæ‰€æœ‰äººéƒ½ç¨±çˆ²å£žäººï¼Œè€Œä¸”ä½ ç¶“å¸¸æ˜¯å°çš„），事後é“æ‰å°±è¶Šé›£ã€‚ @@ -127,12 +127,12 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ è¦è§£æ±ºæ¤å•é¡Œï¼Œæ‚¨å¯¦éš›ä¸Šåªæœ‰å…©å€‹é¸é …： - éžå¸¸æ“…é•·é“æ‰ - - 把「愛ã€å‡å‹»åœ°æ•£é–‹ï¼Œæ²’有人會真æ£æ„Ÿè¦ºåˆ°è‡ªå·±è¢«ä¸å…¬å¹³åœ°çž„æº–äº†ã€‚è®“å®ƒæœ‰è¶³å¤ çš„ + - 把“愛â€å‡å‹»åœ°æ•£é–‹ï¼Œæ²’有人會真æ£æ„Ÿè¦ºåˆ°è‡ªå·±è¢«ä¸å…¬å¹³åœ°çž„æº–äº†ã€‚è®“å®ƒæœ‰è¶³å¤ çš„ å‰µé€ æ€§ï¼Œä»–å€‘ç”šè‡³å¯èƒ½æœƒè¦ºå¾—好笑。 é¸æ“‡æ°¸é ä¿æŒç¦®è²Œæ˜¯ä¸å˜åœ¨çš„。沒有人會相信一個如æ¤æ˜Žé¡¯åœ°éš±è—äº†ä»–å€‘çœŸå¯¦æ€§æ ¼çš„äººã€‚ -.. [#cnf2] ä¿ç¾…·西蒙演唱了「離開愛人的50種方法ã€ï¼Œå› 爲å¦çŽ‡åœ°èªªï¼Œã€Œå‘Šè¨´é–‹ç™¼è€… +.. [#cnf2] ä¿ç¾…·西蒙演唱了“離開愛人的50種方法â€ï¼Œå› 爲å¦çŽ‡åœ°èªªï¼Œâ€œå‘Šè¨´é–‹ç™¼è€… 他們是D*CKHEAD" çš„100è¬ç¨®æ–¹æ³•éƒ½ç„¡æ³•ç¢ºèªã€‚但我確信他已經這麼想了。 3）人2 - 好人 @@ -148,8 +148,8 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ ç‰¹åˆ¥æ˜¯ï¼Œä»–å€‘èƒ½å¤ çˆ²ä½ åšæ±ºå®šï¼Œé€™å°±æ˜¯éŠæˆ²çš„全部內容。 æ‰€ä»¥ç•¶ä½ ç™¼ç¾ä¸€å€‹æ¯”ä½ è°æ˜Žçš„äººæ™‚ï¼Œå°±é †å…¶è‡ªç„¶å§ã€‚ä½ çš„ç®¡ç†è·è²¬åœ¨å¾ˆå¤§ç¨‹åº¦ä¸Šè®Šæˆ -了「è½èµ·ä¾†åƒæ˜¯å€‹å¥½ä¸»æ„——去嘗試å§ã€ï¼Œæˆ–者「è½èµ·ä¾†ä¸éŒ¯ï¼Œä½†æ˜¯XXX呢？ã€ã€Œã€‚第二個版 -本尤其是一個很好的方法，è¦éº¼å¸ç¿’一些關於「XXXã€çš„æ–°æ±è¥¿ï¼Œè¦éº¼é€šéŽæŒ‡å‡ºä¸€äº›è°æ˜Ž +了“è½èµ·ä¾†åƒæ˜¯å€‹å¥½ä¸»æ„——去嘗試å§â€ï¼Œæˆ–者“è½èµ·ä¾†ä¸éŒ¯ï¼Œä½†æ˜¯XXX呢？â€â€œã€‚第二個版 +本尤其是一個很好的方法，è¦éº¼å¸ç¿’一些關於“XXXâ€çš„æ–°æ±è¥¿ï¼Œè¦éº¼é€šéŽæŒ‡å‡ºä¸€äº›è°æ˜Ž 人沒有想到的æ±è¥¿ä¾†é¡¯å¾—更具管ç†æ€§ã€‚無論哪種情æ³ï¼Œä½ 都會è´ã€‚ è¦æ³¨æ„的一件事是èªè˜åˆ°ä¸€å€‹é ˜åŸŸçš„å‰å¤§ä¸ä¸€å®šæœƒè½‰åŒ–çˆ²å…¶ä»–é ˜åŸŸã€‚æ‰€ä»¥ä½ å¯èƒ½æœƒå‘ @@ -172,22 +172,22 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ 他們也å¯èƒ½æ˜¯èƒ½å¤ 解決å•é¡Œçš„äººã€‚å› çˆ²ï¼Œè®“æˆ‘å€‘é¢å°ç¾å¯¦å§ï¼Œè‚¯å®šä¸æ˜¯ä½ 。 æ‰¿æ“”è²¬ä»»ä¹Ÿæ˜¯ä½ é¦–å…ˆæˆçˆ²ç®¡ç†è€…çš„åŽŸå› ã€‚é€™æ˜¯è®“äººå€‘ä¿¡ä»»ä½ ï¼Œè®“ä½ ç²å¾—潛在的榮耀的 -ä¸€éƒ¨åˆ†ï¼Œå› çˆ²ä½ å°±æ˜¯é‚£å€‹æœƒèªªã€Œæˆ‘æžç ¸äº†ã€çš„äººã€‚å¦‚æžœä½ å·²ç¶“éµå¾ªäº†ä»¥å‰çš„è¦å‰‡ï¼Œä½ ç¾ +ä¸€éƒ¨åˆ†ï¼Œå› çˆ²ä½ å°±æ˜¯é‚£å€‹æœƒèªªâ€œæˆ‘æžç ¸äº†â€çš„äººã€‚å¦‚æžœä½ å·²ç¶“éµå¾ªäº†ä»¥å‰çš„è¦å‰‡ï¼Œä½ ç¾ åœ¨å·²ç¶“å¾ˆæ“…é•·èªªäº†ã€‚ 5）應é¿å…的事情 --------------- -有一件事人們甚至比被稱爲「笨蛋ã€æ›´è¨ŽåŽï¼Œé‚£å°±æ˜¯åœ¨ä¸€å€‹ç¥žè–çš„è²éŸ³ä¸è¢«ç¨±çˆ²ã€Œç¬¨è›‹ã€ã€‚ +有一件事人們甚至比被稱爲“笨蛋â€æ›´è¨ŽåŽï¼Œé‚£å°±æ˜¯åœ¨ä¸€å€‹ç¥žè–çš„è²éŸ³ä¸è¢«ç¨±çˆ²â€œç¬¨è›‹â€ã€‚ ç¬¬ä¸€å€‹ä½ å¯ä»¥é“æ‰ï¼Œç¬¬äºŒå€‹ä½ ä¸æœƒçœŸæ£å¾—到機會。å³ä½¿ä½ åšå¾—很好，他們也å¯èƒ½ä¸å† 傾è½ã€‚ -我們都èªçˆ²è‡ªå·±æ¯”別人強，這æ„味著當別人è£è…”作勢時，這會讓我們很惱ç«ã€‚ä½ ä¹Ÿè¨± +我們都èªçˆ²è‡ªå·±æ¯”別人強，這æ„味ç€ç•¶åˆ¥äººè£è…”作勢時，這會讓我們很惱ç«ã€‚ä½ ä¹Ÿè¨± 在é“å¾·å’Œæ™ºåŠ›ä¸Šæ¯”ä½ å‘¨åœçš„æ¯å€‹äººéƒ½å„ªè¶Šï¼Œä½†ä¸è¦è©¦åœ–太明顯，除éžä½ 真的打算激怒 æŸäºº [#cnf3]_ åŒæ¨£ï¼Œä¸è¦å°äº‹æƒ…太客氣或太微妙。禮貌很容易è½å¾—è½èŠ±æµæ°´ï¼ŒæŠŠå•é¡Œéš±è—起來， -æ£å¦‚他們所說，「在網際網路上，沒人能è½åˆ°ä½ çš„å«è“„。ã€ç”¨ä¸€å€‹éˆå™¨æŠŠé€™ä¸€é»žéŒ˜é€²åŽ»ï¼Œ +æ£å¦‚他們所說，“在互è¯ç¶²ä¸Šï¼Œæ²’人能è½åˆ°ä½ çš„å«è“„。â€ç”¨ä¸€å€‹éˆå™¨æŠŠé€™ä¸€é»žéŒ˜é€²åŽ»ï¼Œ å› çˆ²ä½ ä¸èƒ½çœŸçš„ä¾é 別人來ç²å¾—ä½ çš„è§€é»žã€‚ 一些幽默å¯ä»¥å¹«åŠ©ç·©å’Œç›´çŽ‡å’Œé“德化。éŽåº¦åˆ°è’謬的地æ¥ï¼Œå¯ä»¥çŒè¼¸ä¸€å€‹è§€é»žï¼Œè€Œä¸ @@ -203,8 +203,8 @@ Linuxå…§æ ¸ç®¡ç†é¢¨æ ¼ æ—¢ç„¶ä½ çš„ä¸»è¦è²¬ä»»ä¼¼ä¹Žæ˜¯çˆ²åˆ¥äººçš„éŒ¯èª¤æ‰¿æ“”è²¬ä»»ï¼Œä¸¦ä¸”è®“åˆ¥äººç—›è‹¦åœ°æ˜Žç™½ä½ æ˜¯ä¸ç¨±è· 的，那麼顯而易見的å•é¡Œä¹‹ä¸€å°±è®Šæˆäº†çˆ²ä»€éº¼é¦–å…ˆè¦é€™æ¨£åšã€‚ -é¦–å…ˆï¼Œé›–ç„¶ä½ å¯èƒ½æœƒæˆ–å¯èƒ½ä¸æœƒè½åˆ°åå¹¾æ²å¥³å©ï¼ˆæˆ–ç”·å©ï¼Œè®“我們ä¸è¦åœ¨é€™è£¡è©•åˆ¤æˆ– -性別æ§è¦–ï¼‰æ•²ä½ çš„æ›´è¡£å®¤é–€ï¼Œä½ æœƒå¾—åˆ°ä¸€å€‹å·¨å¤§çš„å€‹äººæˆå°±æ„Ÿçˆ²ã€Œè² 責ã€ã€‚別介æ„ä½ çœŸ +é¦–å…ˆï¼Œé›–ç„¶ä½ å¯èƒ½æœƒæˆ–å¯èƒ½ä¸æœƒè½åˆ°åå¹¾æ²å¥³å©ï¼ˆæˆ–ç”·å©ï¼Œè®“我們ä¸è¦åœ¨é€™è£è©•åˆ¤æˆ– +性別æ§è¦–ï¼‰æ•²ä½ çš„æ›´è¡£å®¤é–€ï¼Œä½ æœƒå¾—åˆ°ä¸€å€‹å·¨å¤§çš„å€‹äººæˆå°±æ„Ÿçˆ²â€œè² 責â€ã€‚別介æ„ä½ çœŸ çš„åœ¨é ˜å°Žåˆ¥äººï¼Œä½ è¦è·Ÿä¸Šåˆ¥äººï¼Œå„˜å¯èƒ½å¿«åœ°è¿½è¶•ä»–們。æ¯å€‹äººéƒ½æœƒèªçˆ²ä½ æ˜¯è² è²¬äººã€‚ å¦‚æžœä½ å¯ä»¥åšåˆ°é€™å€‹ï¼Œ 這是個å‰å¤§çš„å·¥ä½œï¼ diff --git a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst index 33fc85c2cc51..6839d25bb22a 100644 --- a/Documentation/translations/zh_TW/process/stable-api-nonsense.rst +++ b/Documentation/translations/zh_TW/process/stable-api-nonsense.rst @@ -17,45 +17,45 @@ Linux å…§æ ¸é©…å‹•æŽ¥å£ ================== -寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進ä½å…§æ ¸æŽ¥å£ï¼Œä¹Ÿæ²’有穩定 -çš„å…§æ ¸æŽ¥å£ã€‚é€™è£¡æ‰€èªªçš„å…§æ ¸æŽ¥å£ï¼Œæ˜¯æŒ‡å…§æ ¸é‡Œçš„接å£ï¼Œè€Œä¸æ˜¯å…§æ ¸å’Œç”¨æˆ¶ç©ºé–“ -的接å£ã€‚å…§æ ¸åˆ°ç”¨æˆ¶ç©ºé–“çš„æŽ¥å£ï¼Œæ˜¯æ供給應用程å¼ä½¿ç”¨çš„系統調用，系統調用 -在æ·å²ä¸Šå¹¾ä¹Žæ²’有éŽè®ŠåŒ–，將來也ä¸æœƒæœ‰è®ŠåŒ–。我有一些è€æ‡‰ç”¨ç¨‹å¼æ˜¯åœ¨0.9版本 -æˆ–è€…æ›´æ—©ç‰ˆæœ¬çš„å…§æ ¸ä¸Šç·¨è¯çš„，在使用2.6ç‰ˆæœ¬å…§æ ¸çš„Linux發布上ä¾ç„¶ç”¨å¾—很好 -。用戶和應用程å¼ä½œè€…å¯ä»¥å°‡é€™å€‹æŽ¥å£çœ‹æˆæ˜¯ç©©å®šçš„。 +寫作本文檔的目的，是爲了解釋爲什麼Linuxæ—¢æ²’æœ‰äºŒé€²åˆ¶å…§æ ¸æŽ¥å£ï¼Œä¹Ÿæ²’有穩定 +çš„å…§æ ¸æŽ¥å£ã€‚這è£æ‰€èªªçš„å…§æ ¸æŽ¥å£ï¼Œæ˜¯æŒ‡å…§æ ¸è£çš„接å£ï¼Œè€Œä¸æ˜¯å…§æ ¸å’Œç”¨æˆ¶ç©ºé–“ +的接å£ã€‚å…§æ ¸åˆ°ç”¨æˆ¶ç©ºé–“çš„æŽ¥å£ï¼Œæ˜¯æ供給應用程åºä½¿ç”¨çš„系統調用，系統調用 +在æ·å²ä¸Šå¹¾ä¹Žæ²’有éŽè®ŠåŒ–，將來也ä¸æœƒæœ‰è®ŠåŒ–。我有一些è€æ‡‰ç”¨ç¨‹åºæ˜¯åœ¨0.9版本 +æˆ–è€…æ›´æ—©ç‰ˆæœ¬çš„å…§æ ¸ä¸Šç·¨è¯çš„，在使用2.6ç‰ˆæœ¬å…§æ ¸çš„Linux發佈上ä¾ç„¶ç”¨å¾—很好 +。用戶和應用程åºä½œè€…å¯ä»¥å°‡é€™å€‹æŽ¥å£çœ‹æˆæ˜¯ç©©å®šçš„。 åŸ·è¡Œç¶±è¦ -------- ä½ ä¹Ÿè¨±ä»¥çˆ²è‡ªå·±æƒ³è¦ç©©å®šçš„å…§æ ¸æŽ¥å£ï¼Œä½†æ˜¯ä½ ä¸æ¸…æ¥šä½ è¦çš„實際上ä¸æ˜¯å®ƒã€‚ä½ éœ€ -è¦çš„其實是穩定的驅動程åºï¼Œè€Œä½ åªæœ‰å°‡é©…動程åºæ”¾åˆ°å…¬ç‰ˆå…§æ ¸çš„原始碼樹里， -æ‰æœ‰å¯èƒ½é”到這個目的。而且這樣åšé‚„有很多其它好處，æ£æ˜¯å› 爲這些好處使得 -Linux能æˆçˆ²å¼·å£¯ï¼Œç©©å®šï¼Œæˆç†Ÿçš„作æ¥ç³»çµ±ï¼Œé€™ä¹Ÿæ˜¯ä½ 最開始é¸æ“‡Linuxçš„åŽŸå› ã€‚ +è¦çš„其實是穩定的驅動程åºï¼Œè€Œä½ åªæœ‰å°‡é©…動程åºæ”¾åˆ°å…¬ç‰ˆå…§æ ¸çš„æºä»£ç¢¼æ¨¹è£ï¼Œ +纔有å¯èƒ½é”到這個目的。而且這樣åšé‚„有很多其它好處，æ£æ˜¯å› 爲這些好處使得 +Linux能æˆçˆ²å¼·å£¯ï¼Œç©©å®šï¼Œæˆç†Ÿçš„æ“ä½œç³»çµ±ï¼Œé€™ä¹Ÿæ˜¯ä½ æœ€é–‹å§‹é¸æ“‡Linuxçš„åŽŸå› ã€‚ 入門 ----- -åªæœ‰é‚£äº›å¯«é©…動程åºçš„「怪人ã€æ‰æœƒæ“”å¿ƒå…§æ ¸æŽ¥å£çš„改變，å°å»£å¤§ç”¨æˆ¶ä¾†èªªï¼Œæ—¢ +åªæœ‰é‚£äº›å¯«é©…動程åºçš„“怪人â€çº”æœƒæ“”å¿ƒå…§æ ¸æŽ¥å£çš„改變，å°å»£å¤§ç”¨æˆ¶ä¾†èªªï¼Œæ—¢ 看ä¸åˆ°å…§æ ¸æŽ¥å£ï¼Œä¹Ÿä¸éœ€è¦åŽ»é—œå¿ƒå®ƒã€‚ 首先，我ä¸æ‰“算討論關於任何éžGPL許å¯çš„å…§æ ¸é©…å‹•çš„æ³•å¾‹å•é¡Œï¼Œé€™äº›éžGPLè¨±å¯ -的驅動程åºåŒ…括ä¸å…¬é–‹åŽŸå§‹ç¢¼ï¼Œéš±è—原始碼，二進ä½æˆ–者是用原始碼包è£ï¼Œæˆ–者 -是其它任何形å¼çš„ä¸èƒ½ä»¥GPL許å¯å…¬é–‹åŽŸå§‹ç¢¼çš„驅動程åºã€‚如果有法律å•é¡Œï¼Œè«‹å’¨ -詢律師，我åªæ˜¯ä¸€å€‹ç¨‹å¼è¨è¨ˆå¸«ï¼Œæ‰€ä»¥æˆ‘åªæ‰“算探討技術å•é¡Œï¼ˆä¸æ˜¯å°çœ‹æ³•å¾‹å•é¡Œï¼Œ +的驅動程åºåŒ…括ä¸å…¬é–‹æºä»£ç¢¼ï¼Œéš±è—æºä»£ç¢¼ï¼ŒäºŒé€²åˆ¶æˆ–者是用æºä»£ç¢¼åŒ…è£ï¼Œæˆ–者 +是其它任何形å¼çš„ä¸èƒ½ä»¥GPL許å¯å…¬é–‹æºä»£ç¢¼çš„驅動程åºã€‚如果有法律å•é¡Œï¼Œè«‹è«® +詢律師，我åªæ˜¯ä¸€å€‹ç¨‹åºå“¡ï¼Œæ‰€ä»¥æˆ‘åªæ‰“算探討技術å•é¡Œï¼ˆä¸æ˜¯å°çœ‹æ³•å¾‹å•é¡Œï¼Œ 法律å•é¡Œå¾ˆå¯¦éš›ï¼Œä¸¦ä¸”需è¦ä¸€ç›´é—œæ³¨ï¼‰ã€‚ -既然åªè«‡æŠ€è¡“å•é¡Œï¼Œæˆ‘們就有了下é¢å…©å€‹ä¸»é¡Œï¼šäºŒé€²ä½å…§æ ¸æŽ¥å£å’Œç©©å®šçš„å…§æ ¸æº -代碼接å£ã€‚這兩個å•é¡Œæ˜¯äº’相關è¯çš„，讓我們先解決掉二進ä½æŽ¥å£çš„å•é¡Œã€‚ +既然åªè«‡æŠ€è¡“å•é¡Œï¼Œæˆ‘們就有了下é¢å…©å€‹ä¸»é¡Œï¼šäºŒé€²åˆ¶å…§æ ¸æŽ¥å£å’Œç©©å®šçš„å…§æ ¸æº +代碼接å£ã€‚這兩個å•é¡Œæ˜¯äº’相關è¯çš„，讓我們先解決掉二進制接å£çš„å•é¡Œã€‚ -二進ä½å…§æ ¸æŽ¥å£ +äºŒé€²åˆ¶å…§æ ¸æŽ¥å£ -------------- -å‡å¦‚æˆ‘å€‘æœ‰ä¸€å€‹ç©©å®šçš„å…§æ ¸åŽŸå§‹ç¢¼æŽ¥å£ï¼Œé‚£éº¼è‡ªç„¶è€Œç„¶çš„，我們就æ“有了穩定的 -二進ä½æŽ¥å£ï¼Œæ˜¯é€™æ¨£çš„嗎？錯。讓我們看看關於Linuxå…§æ ¸çš„å¹¾é»žäº‹å¯¦ï¼š +å‡å¦‚æˆ‘å€‘æœ‰ä¸€å€‹ç©©å®šçš„å…§æ ¸æºä»£ç¢¼æŽ¥å£ï¼Œé‚£éº¼è‡ªç„¶è€Œç„¶çš„，我們就æ“有了穩定的 +二進制接å£ï¼Œæ˜¯é€™æ¨£çš„嗎？錯。讓我們看看關於Linuxå…§æ ¸çš„å¹¾é»žäº‹å¯¦ï¼š - - å–決於所用的Cç·¨è¯å™¨çš„版本，ä¸åŒçš„å…§æ ¸æ•¸æ“šçµæ§‹é‡Œçš„çµæ§‹é«”çš„å°é½Šæ–¹ + - å–決於所用的Cç·¨è¯å™¨çš„版本，ä¸åŒçš„å…§æ ¸æ•¸æ“šçµæ§‹è£çš„çµæ§‹é«”çš„å°é½Šæ–¹ å¼æœƒæœ‰å·®åˆ¥ï¼Œä»£ç¢¼ä¸ä¸åŒå‡½æ•¸çš„表ç¾å½¢å¼ä¹Ÿä¸ä¸€æ¨£ï¼ˆå‡½æ•¸æ˜¯ä¸æ˜¯è¢«inline ç·¨è¯å–決於編è¯å™¨è¡Œçˆ²ï¼‰ã€‚ä¸åŒçš„函數的表ç¾å½¢å¼ä¸¦ä¸é‡è¦ï¼Œä½†æ˜¯æ•¸æ“š çµæ§‹å…§éƒ¨çš„å°é½Šæ–¹å¼å¾ˆé—œéµã€‚ @@ -69,33 +69,33 @@ Linux能æˆçˆ²å¼·å£¯ï¼Œç©©å®šï¼Œæˆç†Ÿçš„作æ¥ç³»çµ±ï¼Œé€™ä¹Ÿæ˜¯ä½ æœ€é–‹å§‹é¸ é …ã€‚ - Linuxå¯ä»¥åœ¨å¾ˆå¤šçš„ä¸åŒé«”ç³»çµæ§‹çš„處ç†å™¨ä¸Šé‹è¡Œã€‚在æŸå€‹é«”ç³»çµæ§‹ä¸Šç·¨ - è¯å¥½çš„二進ä½é©…動程åºï¼Œä¸å¯èƒ½åœ¨å¦å¤–一個體系çµæ§‹ä¸Šæ£ç¢ºçš„é‹è¡Œã€‚ + è¯å¥½çš„二進制驅動程åºï¼Œä¸å¯èƒ½åœ¨å¦å¤–一個體繫çµæ§‹ä¸Šæ£ç¢ºçš„é‹è¡Œã€‚ å°æ–¼ä¸€å€‹ç‰¹å®šçš„å…§æ ¸ï¼Œæ»¿è¶³é€™äº›æ¢ä»¶ä¸¦ä¸é›£ï¼Œä½¿ç”¨åŒä¸€å€‹Cç·¨è¯å™¨å’ŒåŒæ¨£çš„å…§æ ¸é… -ç½®é¸é …來編è¯é©…動程åºæ¨¡å¡Šå°±å¯ä»¥äº†ã€‚這å°æ–¼çµ¦ä¸€å€‹ç‰¹å®šLinux發布的特定版本æ -供驅動程åºï¼Œæ˜¯å®Œå…¨å¯ä»¥æ»¿è¶³éœ€æ±‚çš„ã€‚ä½†æ˜¯å¦‚æžœä½ è¦çµ¦ä¸åŒç™¼å¸ƒçš„ä¸åŒç‰ˆæœ¬éƒ½ç™¼ -布一個驅動程åºï¼Œå°±éœ€è¦åœ¨æ¯å€‹ç™¼å¸ƒä¸Šç”¨ä¸åŒçš„å…§æ ¸è¨ç½®åƒæ•¸éƒ½ç·¨è¯ä¸€æ¬¡å…§æ ¸ï¼Œ -這簡直跟噩夢一樣。而且還è¦æ³¨æ„到，æ¯å€‹Linux發布還æä¾›ä¸åŒçš„Linuxå…§æ ¸ï¼Œ -é€™äº›å…§æ ¸éƒ½é‡å°ä¸åŒçš„硬體類型進行了優化（有很多種ä¸åŒçš„處ç†å™¨ï¼Œé‚„有ä¸åŒ -çš„å…§æ ¸è¨ç½®é¸é …）。所以æ¯ç™¼å¸ƒä¸€æ¬¡é©…動程åºï¼Œéƒ½éœ€è¦æ供很多ä¸åŒç‰ˆæœ¬çš„å…§æ ¸ +ç½®é¸é …來編è¯é©…動程åºæ¨¡å¡Šå°±å¯ä»¥äº†ã€‚這å°æ–¼çµ¦ä¸€å€‹ç‰¹å®šLinux發佈的特定版本æ +供驅動程åºï¼Œæ˜¯å®Œå…¨å¯ä»¥æ»¿è¶³éœ€æ±‚çš„ã€‚ä½†æ˜¯å¦‚æžœä½ è¦çµ¦ä¸åŒç™¼ä½ˆçš„ä¸åŒç‰ˆæœ¬éƒ½ç™¼ +佈一個驅動程åºï¼Œå°±éœ€è¦åœ¨æ¯å€‹ç™¼ä½ˆä¸Šç”¨ä¸åŒçš„å…§æ ¸è¨ç½®åƒæ•¸éƒ½ç·¨è¯ä¸€æ¬¡å…§æ ¸ï¼Œ +這簡直跟噩夢一樣。而且還è¦æ³¨æ„到，æ¯å€‹Linux發佈還æä¾›ä¸åŒçš„Linuxå…§æ ¸ï¼Œ +é€™äº›å…§æ ¸éƒ½é‡å°ä¸åŒçš„硬件類型進行了優化（有很多種ä¸åŒçš„處ç†å™¨ï¼Œé‚„有ä¸åŒ +çš„å…§æ ¸è¨ç½®é¸é …）。所以æ¯ç™¼ä½ˆä¸€æ¬¡é©…動程åºï¼Œéƒ½éœ€è¦æ供很多ä¸åŒç‰ˆæœ¬çš„å…§æ ¸ 模塊。 -ç›¸ä¿¡æˆ‘ï¼Œå¦‚æžœä½ çœŸçš„è¦æŽ¡å–這種發布方å¼ï¼Œä¸€å®šæœƒæ…¢æ…¢ç˜‹æŽ‰ï¼Œæˆ‘很久以å‰å°±æœ‰éŽ +ç›¸ä¿¡æˆ‘ï¼Œå¦‚æžœä½ çœŸçš„è¦æŽ¡å–這種發佈方å¼ï¼Œä¸€å®šæœƒæ…¢æ…¢ç˜‹æŽ‰ï¼Œæˆ‘很久以å‰å°±æœ‰éŽ 深刻的教訓... -ç©©å®šçš„å…§æ ¸åŽŸå§‹ç¢¼æŽ¥å£ +ç©©å®šçš„å…§æ ¸æºä»£ç¢¼æŽ¥å£ -------------------- -如果有人ä¸å°‡ä»–çš„å…§æ ¸é©…å‹•ç¨‹åºï¼Œæ”¾å…¥å…¬ç‰ˆå…§æ ¸çš„原始碼樹，而åˆæƒ³è®“é©…å‹•ç¨‹åº +如果有人ä¸å°‡ä»–çš„å…§æ ¸é©…å‹•ç¨‹åºï¼Œæ”¾å…¥å…¬ç‰ˆå…§æ ¸çš„æºä»£ç¢¼æ¨¹ï¼Œè€Œåˆæƒ³è®“é©…å‹•ç¨‹åº ä¸€ç›´ä¿æŒåœ¨æœ€æ–°çš„å…§æ ¸ä¸å¯ç”¨ï¼Œé‚£éº¼é€™å€‹è©±é¡Œå°‡æœƒè®Šå¾—沒完沒了。 å…§æ ¸é–‹ç™¼æ˜¯æŒçºŒè€Œä¸”快節å¥çš„，從來都ä¸æœƒæ…¢ä¸‹ä¾†ã€‚å…§æ ¸é–‹ç™¼äººå“¡åœ¨ç•¶å‰æŽ¥å£ä¸ 找到bug，或者找到更好的實ç¾æ–¹å¼ã€‚一旦發ç¾é€™äº›ï¼Œä»–們就很快會去修改當å‰çš„ -接å£ã€‚修改接å£æ„味著，函數åå¯èƒ½æœƒæ”¹è®Šï¼Œçµæ§‹é«”å¯èƒ½è¢«æ“´å……或者刪減，函數 +接å£ã€‚修改接å£æ„味ç€ï¼Œå‡½æ•¸åå¯èƒ½æœƒæ”¹è®Šï¼Œçµæ§‹é«”å¯èƒ½è¢«æ“´å……或者刪減，函數 çš„åƒæ•¸ä¹Ÿå¯èƒ½ç™¼ç”Ÿæ”¹è®Šã€‚一旦接å£è¢«ä¿®æ”¹ï¼Œå…§æ ¸ä¸ä½¿ç”¨é€™äº›æŽ¥å£çš„地方需è¦åŒæ™‚ ä¿®æ£ï¼Œé€™æ¨£æ‰èƒ½ä¿è‰æ‰€æœ‰çš„æ±è¥¿ç¹¼çºŒå·¥ä½œã€‚ -舉一個例åï¼Œå…§æ ¸çš„USB驅動程åºæŽ¥å£åœ¨USBå系統的整個生命周期ä¸ï¼Œè‡³å°‘ç¶“æ· +舉一個例åï¼Œå…§æ ¸çš„USB驅動程åºæŽ¥å£åœ¨USBå系統的整個生命週期ä¸ï¼Œè‡³å°‘ç¶“æ· äº†ä¸‰æ¬¡é‡å¯«ã€‚這些é‡å¯«è§£æ±ºä»¥ä¸‹å•é¡Œï¼š - 把數據æµå¾žåŒæ¥æ¨¡å¼æ”¹æˆéžåŒæ¥æ¨¡å¼ï¼Œé€™å€‹æ”¹å‹•æ¸›å°‘了一些驅動程åºçš„ @@ -104,11 +104,11 @@ Linux能æˆçˆ²å¼·å£¯ï¼Œç©©å®šï¼Œæˆç†Ÿçš„作æ¥ç³»çµ±ï¼Œé€™ä¹Ÿæ˜¯ä½ æœ€é–‹å§‹é¸ - 修改了USBæ ¸å¿ƒä»£ç¢¼ä¸çˆ²USB驅動分é…數據包內å˜çš„æ–¹å¼ï¼Œæ‰€æœ‰çš„驅動都 需è¦æ供更多的åƒæ•¸çµ¦USBæ ¸å¿ƒï¼Œä»¥ä¿®æ£äº†å¾ˆå¤šå·²ç¶“被記錄在案的æ»éŽ–。 -這和一些å°é–‰åŽŸå§‹ç¢¼çš„作æ¥ç³»çµ±å½¢æˆé®®æ˜Žçš„å°æ¯”，在那些作æ¥ç³»çµ±ä¸Šï¼Œä¸å¾—ä¸é¡ +這和一些å°é–‰æºä»£ç¢¼çš„æ“作系統形æˆé®®æ˜Žçš„å°æ¯”，在那些æ“作系統上，ä¸å¾—ä¸é¡ 外的ç¶è·èˆŠçš„USB接å£ã€‚這導致了一個å¯èƒ½æ€§ï¼Œæ–°çš„開發者ä¾ç„¶æœƒä¸å°å¿ƒä½¿ç”¨èˆŠçš„ -接å£ï¼Œä»¥ä¸æ°ç•¶çš„æ–¹å¼ç·¨å¯«ä»£ç¢¼ï¼Œé€²è€Œå½±éŸ¿åˆ°ä½œæ¥ç³»çµ±çš„穩定性。 +接å£ï¼Œä»¥ä¸æ°ç•¶çš„æ–¹å¼ç·¨å¯«ä»£ç¢¼ï¼Œé€²è€Œå½±éŸ¿åˆ°æ“作系統的穩定性。 在上é¢çš„例åä¸ï¼Œæ‰€æœ‰çš„開發者都åŒæ„這些é‡è¦çš„改動，在這樣的情æ³ä¸‹ä¿®æ”¹ä»£ -價很低。如果Linuxä¿æŒä¸€å€‹ç©©å®šçš„å…§æ ¸åŽŸå§‹ç¢¼æŽ¥å£ï¼Œé‚£éº¼å°±å¾—å‰µå»ºä¸€å€‹æ–°çš„æŽ¥å£ +價很低。如果Linuxä¿æŒä¸€å€‹ç©©å®šçš„å…§æ ¸æºä»£ç¢¼æŽ¥å£ï¼Œé‚£éº¼å°±å¾—å‰µå»ºä¸€å€‹æ–°çš„æŽ¥å£ ï¼›èˆŠçš„ï¼Œæœ‰å•é¡Œçš„接å£å¿…é ˆä¸€ç›´ç¶è·ï¼Œçµ¦Linux USB開發者帶來é¡å¤–的工作。既然 所有的Linux USB驅動的作者都是利用自己的時間工作，那麼è¦æ±‚他們去åšæ¯«ç„¡æ„ 義的å…è²»é¡å¤–工作，是ä¸å¯èƒ½çš„。 @@ -126,28 +126,28 @@ Linux能æˆçˆ²å¼·å£¯ï¼Œç©©å®šï¼Œæˆç†Ÿçš„作æ¥ç³»çµ±ï¼Œé€™ä¹Ÿæ˜¯ä½ æœ€é–‹å§‹é¸ è¦åšä»€éº¼ -------- -å¦‚æžœä½ å¯«äº†ä¸€å€‹Linuxå…§æ ¸é©…å‹•ï¼Œä½†æ˜¯å®ƒé‚„ä¸åœ¨Linux原始碼樹里，作爲一個開發 -è€…ï¼Œä½ æ‡‰è©²æ€Žéº¼åšï¼Ÿçˆ²æ¯å€‹ç™¼å¸ƒçš„æ¯å€‹ç‰ˆæœ¬æ供一個二進ä½é©…動，那簡直是一個 +å¦‚æžœä½ å¯«äº†ä¸€å€‹Linuxå…§æ ¸é©…å‹•ï¼Œä½†æ˜¯å®ƒé‚„ä¸åœ¨Linuxæºä»£ç¢¼æ¨¹è£ï¼Œä½œçˆ²ä¸€å€‹é–‹ç™¼ +è€…ï¼Œä½ æ‡‰è©²æ€Žéº¼åšï¼Ÿçˆ²æ¯å€‹ç™¼ä½ˆçš„æ¯å€‹ç‰ˆæœ¬æ供一個二進制驅動，那簡直是一個 噩夢，è¦è·Ÿä¸Šæ°¸é 處於變化之ä¸çš„å…§æ ¸æŽ¥å£ï¼Œä¹Ÿæ˜¯ä¸€ä»¶è¾›è‹¦æ´»ã€‚ -å¾ˆç°¡å–®ï¼Œè®“ä½ çš„é©…å‹•é€²å…¥å…§æ ¸åŽŸå§‹ç¢¼æ¨¹ï¼ˆè¦è¨˜å¾—我們在談論的是以GPL許å¯ç™¼è¡Œ +å¾ˆç°¡å–®ï¼Œè®“ä½ çš„é©…å‹•é€²å…¥å…§æ ¸æºä»£ç¢¼æ¨¹ï¼ˆè¦è¨˜å¾—我們在談論的是以GPL許å¯ç™¼è¡Œ çš„é©…å‹•ï¼Œå¦‚æžœä½ çš„ä»£ç¢¼ä¸ç¬¦åˆGPL，那麼ç¥ä½ 好é‹ï¼Œä½ åªèƒ½è‡ªå·±è§£æ±ºé€™å€‹å•é¡Œäº†ï¼Œ -ä½ é€™å€‹å¸è¡€é¬¼<把Andrewå’ŒLinuså°å¸è¡€é¬¼çš„定義連çµåˆ°é€™è£¡>ï¼‰ã€‚ç•¶ä½ çš„ä»£ç¢¼åŠ å…¥ -å…¬ç‰ˆå…§æ ¸åŽŸå§‹ç¢¼æ¨¹ä¹‹å¾Œï¼Œå¦‚æžœä¸€å€‹å…§æ ¸æŽ¥å£æ”¹è®Šï¼Œä½ 的驅動會直接被修改接å£çš„ +ä½ é€™å€‹å¸è¡€é¬¼<把Andrewå’ŒLinuså°å¸è¡€é¬¼çš„定義éˆæŽ¥åˆ°é€™è£>ï¼‰ã€‚ç•¶ä½ çš„ä»£ç¢¼åŠ å…¥ +å…¬ç‰ˆå…§æ ¸æºä»£ç¢¼æ¨¹ä¹‹å¾Œï¼Œå¦‚æžœä¸€å€‹å…§æ ¸æŽ¥å£æ”¹è®Šï¼Œä½ 的驅動會直接被修改接å£çš„ 那個人修改。ä¿è‰ä½ çš„é©…å‹•æ°¸é 都å¯ä»¥ç·¨è¯é€šéŽï¼Œä¸¦ä¸”ä¸€ç›´å·¥ä½œï¼Œä½ å¹¾ä¹Žä¸éœ€è¦ åšä»€éº¼äº‹æƒ…。 -æŠŠé©…å‹•æ”¾åˆ°å…§æ ¸åŽŸå§‹ç¢¼æ¨¹é‡Œæœƒæœ‰å¾ˆå¤šçš„å¥½è™•ï¼š +æŠŠé©…å‹•æ”¾åˆ°å…§æ ¸æºä»£ç¢¼æ¨¹è£æœƒæœ‰å¾ˆå¤šçš„好處： - 驅動的質é‡æœƒæå‡ï¼Œè€Œç¶è·æˆæœ¬ï¼ˆå°åŽŸå§‹ä½œè€…來說）會下é™ã€‚ - å…¶ä»–äººæœƒçµ¦é©…å‹•æ·»åŠ æ–°ç‰¹æ€§ã€‚ - 其他人會找到驅動ä¸çš„bug並修復。 - 其他人會在驅動ä¸æ‰¾åˆ°æ€§èƒ½å„ªåŒ–的機會。 - 當外部的接å£çš„改變需è¦ä¿®æ”¹é©…動程åºçš„æ™‚å€™ï¼Œå…¶ä»–äººæœƒä¿®æ”¹é©…å‹•ç¨‹åº - - ä¸éœ€è¦è¯ç¹«ä»»ä½•ç™¼è¡Œå•†ï¼Œé€™å€‹é©…動會自動的隨著所有的Linux發布一起發 + - ä¸éœ€è¦è¯ç¹«ä»»ä½•ç™¼è¡Œå•†ï¼Œé€™å€‹é©…動會自動的隨ç€æ‰€æœ‰çš„Linux發佈一起發 布。 -和別的作æ¥ç³»çµ±ç›¸æ¯”，Linux爲更多ä¸åŒçš„è¨å‚™æä¾›ç¾æˆçš„é©…å‹•ï¼Œè€Œä¸”èƒ½åœ¨æ›´å¤šä¸ -åŒé«”ç³»çµæ§‹çš„處ç†å™¨ä¸Šæ”¯æŒé€™äº›è¨å‚™ã€‚這個經éŽè€ƒé©—的開發模å¼ï¼Œå¿…然是錯ä¸äº† +和別的æ“作系統相比，Linux爲更多ä¸åŒçš„è¨å‚™æä¾›ç¾æˆçš„é©…å‹•ï¼Œè€Œä¸”èƒ½åœ¨æ›´å¤šä¸ +åŒé«”繫çµæ§‹çš„處ç†å™¨ä¸Šæ”¯æŒé€™äº›è¨å‚™ã€‚這個經éŽè€ƒé©—的開發模å¼ï¼Œå¿…然是錯ä¸äº† çš„ :) æ„Ÿè¬ diff --git a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst index 29d9a70a1868..bd82a8ff3969 100644 --- a/Documentation/translations/zh_TW/process/stable-kernel-rules.rst +++ b/Documentation/translations/zh_TW/process/stable-kernel-rules.rst @@ -17,10 +17,10 @@ - Kangkai Yin <e12051@motorola.com> - 胡皓文 Hu Haowen <src.res.211@gmail.com> -æ‰€æœ‰ä½ æƒ³çŸ¥é“的事情 - 關於linux穩定版發布 +æ‰€æœ‰ä½ æƒ³çŸ¥é“的事情 - 關於linux穩定版發佈 ======================================== -關於Linux 2.6ç©©å®šç‰ˆç™¼å¸ƒï¼Œæ‰€æœ‰ä½ æƒ³çŸ¥é“的事情。 +關於Linux 2.6ç©©å®šç‰ˆç™¼ä½ˆï¼Œæ‰€æœ‰ä½ æƒ³çŸ¥é“的事情。 關於哪些類型的補ä¸å¯ä»¥è¢«æŽ¥æ”¶é€²å…¥ç©©å®šç‰ˆä»£ç¢¼æ¨¹ï¼Œå“ªäº›ä¸å¯ä»¥çš„è¦å‰‡ï¼š ---------------------------------------------------------------- @@ -28,39 +28,39 @@ - å¿…é ˆæ˜¯é¡¯è€Œæ˜“è¦‹çš„æ£ç¢ºï¼Œä¸¦ä¸”經éŽæ¸¬è©¦çš„。 - 連åŒä¸Šä¸‹æ–‡ï¼Œä¸èƒ½å¤§æ–¼100行。 - å¿…é ˆåªä¿®æ£ä¸€ä»¶äº‹æƒ…。 - - å¿…é ˆä¿®æ£äº†ä¸€å€‹çµ¦å¤§å®¶å¸¶ä¾†éº»ç…©çš„真æ£çš„bug（ä¸æ˜¯ã€Œé€™ä¹Ÿè¨±æ˜¯ä¸€å€‹å•é¡Œ...〠+ - å¿…é ˆä¿®æ£äº†ä¸€å€‹çµ¦å¤§å®¶å¸¶ä¾†éº»ç…©çš„真æ£çš„bug（ä¸æ˜¯â€œé€™ä¹Ÿè¨±æ˜¯ä¸€å€‹å•é¡Œ...†那樣的æ±è¥¿ï¼‰ã€‚ - å¿…é ˆä¿®æ£å¸¶ä¾†å¦‚下後果的å•é¡Œï¼šç·¨è¯éŒ¯èª¤ï¼ˆå°è¢«æ¨™è¨˜çˆ²CONFIG_BROKEN的例外）， - å…§æ ¸å´©æ½°ï¼ŒæŽ›èµ·ï¼Œæ•¸æ“šæ壞，真æ£çš„安全å•é¡Œï¼Œæˆ–è€…ä¸€äº›é¡žä¼¼ã€Œå“¦ï¼Œé€™ä¸ - 好ã€çš„å•é¡Œã€‚ç°¡çŸçš„說，就是一些致命的å•é¡Œã€‚ - - 沒有「ç†è«–上的競çˆæ¢ä»¶ã€ï¼Œé™¤éžèƒ½çµ¦å‡ºç«¶çˆæ¢ä»¶å¦‚何被利用的解釋。 - - ä¸èƒ½å˜åœ¨ä»»ä½•çš„「瑣碎的ã€ä¿®æ£ï¼ˆæ‹¼å¯«ä¿®æ£ï¼ŒåŽ»æŽ‰å¤šé¤˜ç©ºæ ¼ä¹‹é¡žçš„）。 + å…§æ ¸å´©æ½°ï¼ŒæŽ›èµ·ï¼Œæ•¸æ“šæ壞，真æ£çš„安全å•é¡Œï¼Œæˆ–è€…ä¸€äº›é¡žä¼¼â€œå“¦ï¼Œé€™ä¸ + 好â€çš„å•é¡Œã€‚ç°¡çŸçš„說，就是一些致命的å•é¡Œã€‚ + - 沒有“ç†è«–上的競çˆæ¢ä»¶â€ï¼Œé™¤éžèƒ½çµ¦å‡ºç«¶çˆæ¢ä»¶å¦‚何被利用的解釋。 + - ä¸èƒ½å˜åœ¨ä»»ä½•çš„“瑣碎的â€ä¿®æ£ï¼ˆæ‹¼å¯«ä¿®æ£ï¼ŒåŽ»æŽ‰å¤šé¤˜ç©ºæ ¼ä¹‹é¡žçš„）。 - å¿…é ˆè¢«ç›¸é—œå系統的ç¶è·è€…接å—。 - - å¿…é ˆéµå¾ªDocumentation/translations/zh_TW/process/submitting-patches.rst里的è¦å‰‡ã€‚ + - å¿…é ˆéµå¾ªDocumentation/translations/zh_CN/process/submitting-patches.rstè£çš„è¦å‰‡ã€‚ å‘穩定版代碼樹æ交補ä¸çš„éŽç¨‹ï¼š ------------------------------ - 在確èªäº†è£œä¸ç¬¦åˆä»¥ä¸Šçš„è¦å‰‡å¾Œï¼Œå°‡è£œä¸ç™¼é€åˆ°stable@vger.kernel.org。 - - 如果補ä¸è¢«æŽ¥å—到隊列里，發é€è€…會收到一個ACK回復，如果沒有被接å—，收 - 到的是NAK回復。回復需è¦å¹¾å¤©çš„時間，這å–決於開發者的時間安排。 - - 被接å—的補ä¸æœƒè¢«åŠ 到穩定版本隊列里，ç‰å¾…其他開發者的審查。 + - 如果補ä¸è¢«æŽ¥å—到隊列è£ï¼Œç™¼é€è€…會收到一個ACK回覆，如果沒有被接å—，收 + 到的是NAK回覆。回覆需è¦å¹¾å¤©çš„時間，這å–決於開發者的時間安排。 + - 被接å—的補ä¸æœƒè¢«åŠ 到穩定版本隊列è£ï¼Œç‰å¾…其他開發者的審查。 - 安全方é¢çš„補ä¸ä¸è¦ç™¼åˆ°é€™å€‹åˆ—表，應該發é€åˆ°security@kernel.org。 -審查周期： +審查週期： ---------- - - 當穩定版的ç¶è·è€…決定開始一個審查周期，補ä¸å°‡è¢«ç™¼é€åˆ°å¯©æŸ¥å§”員會，以 + - 當穩定版的ç¶è·è€…決定開始一個審查週期，補ä¸å°‡è¢«é«®é€åˆ°å¯©æŸ¥å§”員會，以 åŠè¢«è£œä¸å½±éŸ¿çš„é ˜åŸŸçš„ç¶è·è€…（除éžæäº¤è€…å°±æ˜¯è©²é ˜åŸŸçš„ç¶è·è€…ï¼‰ä¸¦ä¸”æŠ„é€ åˆ°linux-kernel郵件列表。 - - 審查委員會有48å°æ™‚的時間，用來決定給該補ä¸å›žå¾©ACK還是NAK。 + - 審查委員會有48å°æ™‚的時間，用來決定給該補ä¸å›žè¦†ACK還是NAK。 - 如果委員會ä¸æœ‰æˆå“¡æ‹’絕這個補ä¸ï¼Œæˆ–者linux-kernel列表上有人åå°é€™å€‹ 補ä¸ï¼Œä¸¦æ出ç¶è·è€…和審查委員會之å‰æ²’有æ„è˜åˆ°çš„å•é¡Œï¼Œè£œä¸æœƒå¾žéšŠåˆ—ä¸ ä¸Ÿæ£„ã€‚ - - 在審查周期çµæŸçš„時候，那些得到ACK回應的補ä¸å°‡æœƒè¢«åŠ 入到最新的穩定版 - 發布ä¸ï¼Œä¸€å€‹æ–°çš„穩定版發布就æ¤ç”¢ç”Ÿã€‚ - - 安全性補ä¸å°‡å¾žå…§æ ¸å®‰å…¨å°çµ„那裡直接接收到穩定版代碼樹ä¸ï¼Œè€Œä¸æ˜¯é€šéŽ - 通常的審查周期。請è¯ç¹«å…§æ ¸å®‰å…¨å°çµ„以ç²å¾—關於這個éŽç¨‹çš„更多細節。 + - 在審查週期çµæŸçš„時候，那些得到ACK回應的補ä¸å°‡æœƒè¢«åŠ 入到最新的穩定版 + 發佈ä¸ï¼Œä¸€å€‹æ–°çš„穩定版發佈就æ¤ç”¢ç”Ÿã€‚ + - 安全性補ä¸å°‡å¾žå…§æ ¸å®‰å…¨å°çµ„é‚£è£ç›´æŽ¥æŽ¥æ”¶åˆ°ç©©å®šç‰ˆä»£ç¢¼æ¨¹ä¸ï¼Œè€Œä¸æ˜¯é€šéŽ + 通常的審查週期。請è¯ç¹«å…§æ ¸å®‰å…¨å°çµ„以ç²å¾—關於這個éŽç¨‹çš„更多細節。 審查委員會： ------------ diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst index 12bf6f5ca5c6..942962d1e2f4 100644 --- a/Documentation/translations/zh_TW/process/submit-checklist.rst +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -2,108 +2,114 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> - Hu Haowen <src.res.211@gmail.com> +:Original: Documentation/process/submit-checklist.rst +:Translator: + - Alex Shi <alexs@kernel.org> + - Wu XiangCheng <bobwxc@email.cn> + - Hu Haowen <src.res.211@gmail.com> .. _tw_submitchecklist: -Linuxå…§æ ¸è£œä¸æ交清單 -~~~~~~~~~~~~~~~~~~~~~ +Linuxå…§æ ¸è£œä¸æ交檢查單 +~~~~~~~~~~~~~~~~~~~~~~~ å¦‚æžœé–‹ç™¼äººå“¡å¸Œæœ›çœ‹åˆ°ä»–å€‘çš„å…§æ ¸è£œä¸æ交更快地被接å—，那麼他們應該åšä¸€äº›åŸºæœ¬ 的事情。 -這些都是在 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` +這些都是在 Documentation/translations/zh_CN/process/submitting-patches.rst 和其他有關æ交Linuxå…§æ ¸è£œä¸çš„文檔ä¸æ供的。 -1) 如果使用工具，則包括定義/è²æ˜Žè©²å·¥å…·çš„文件。ä¸è¦ä¾è³´æ–¼å…¶ä»–é 文件拉入您使用 +1) 如果使用工具，則包括定義/è²æ˜Žè©²å·¥å…·çš„文件。ä¸è¦ä¾è³´å…¶ä»–é 文件來引入您使用 çš„é 文件。 2) 乾淨的編è¯ï¼š - a) 使用é©ç”¨æˆ–修改的 ``CONFIG`` é¸é … ``=y``ã€``=m`` å’Œ ``=n`` 。沒有GCC - è¦å‘Š/錯誤，沒有連çµå™¨è¦å‘Š/錯誤。 + a) 使用åˆé©çš„ ``CONFIG`` é¸é … ``=y``ã€``=m`` å’Œ ``=n`` 。沒有 ``gcc`` + è¦å‘Š/錯誤，沒有éˆæŽ¥å™¨è¦å‘Š/錯誤。 - b) 通éŽallnoconfigã€allmodconfig + b) é€šéŽ ``allnoconfig`` 〠``allmodconfig`` c) 使用 ``O=builddir`` 時å¯ä»¥æˆåŠŸç·¨è¯ -3) 通éŽä½¿ç”¨æœ¬åœ°äº¤å‰ç·¨è¯å·¥å…·æˆ–å…¶ä»–ä¸€äº›æ§‹å»ºå ´åœ¨å¤šå€‹CPU體系çµæ§‹ä¸Šæ§‹å»ºã€‚ + d) 任何 Doucmentation/ 下的變更都能æˆåŠŸæ§‹å»ºä¸”ä¸å¼•å…¥æ–°è¦å‘Š/錯誤。 + 用 ``make htmldocs`` 或 ``make pdfdocs`` 檢驗構建情æ³ä¸¦ä¿®å¾©å•é¡Œã€‚ + +3) 通éŽä½¿ç”¨æœ¬åœ°äº¤å‰ç·¨è¯å·¥å…·æˆ–其他一些構建è¨æ–½åœ¨å¤šå€‹CPU體系çµæ§‹ä¸Šæ§‹å»ºã€‚ 4) PPC64是一種很好的交å‰ç·¨è¯æª¢æŸ¥é«”ç³»çµæ§‹ï¼Œå› 爲它傾å‘æ–¼å°64ä½çš„數使用無符號 長整型。 -5) 如下所述 :ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>`. - 檢查您的補ä¸æ˜¯å¦çˆ²å¸¸è¦æ¨£å¼ã€‚在æ交（ ``scripts/check patch.pl`` ）之å‰ï¼Œ - 使用補ä¸æ¨£å¼æª¢æŸ¥å™¨æª¢æŸ¥æ˜¯å¦æœ‰è¼•å¾®çš„è¡çªã€‚æ‚¨æ‡‰è©²èƒ½å¤ è™•ç†æ‚¨çš„補ä¸ä¸å˜åœ¨çš„所有 +5) 按 Documentation/translations/zh_CN/process/coding-style.rst 所述檢查您的 + 補ä¸æ˜¯å¦çˆ²å¸¸è¦æ¨£å¼ã€‚在æ交之å‰ä½¿ç”¨è£œä¸æ¨£å¼æª¢æŸ¥å™¨ ``scripts/checkpatch.pl`` + 檢查是å¦æœ‰è¼•å¾®çš„è¡çªã€‚æ‚¨æ‡‰è©²èƒ½å¤ è™•ç†æ‚¨çš„補ä¸ä¸å˜åœ¨çš„所有 é•è¦è¡Œçˆ²ã€‚ -6) 任何新的或修改éŽçš„ ``CONFIG`` é¸é …都ä¸æœƒå¼„é«’é…ç½®èœå–®ï¼Œä¸¦é»˜èªçˆ²é—œé–‰ï¼Œé™¤éž - å®ƒå€‘ç¬¦åˆ ``Documentation/kbuild/kconfig-language.rst`` ä¸è¨˜éŒ„的異常æ¢ä»¶, - èœå–®å±¬æ€§ï¼šé»˜èªå€¼. +6) 任何新的或修改éŽçš„ ``CONFIG`` é¸é …都ä¸æ‡‰æžäº‚é…ç½®èœå–®ï¼Œä¸¦é»˜èªçˆ²é—œé–‰ï¼Œé™¤éž + å®ƒå€‘ç¬¦åˆ ``Documentation/kbuild/kconfig-language.rst`` èœå–®å±¬æ€§ï¼šé»˜èªå€¼ä¸ + 記錄的例外æ¢ä»¶ã€‚ 7) 所有新的 ``kconfig`` é¸é …都有幫助文本。 -8) 已仔細審查了相關的 ``Kconfig`` 組åˆã€‚這很難用測試來糾æ£â€”—腦力在這裡是有 +8) 已仔細審查了相關的 ``Kconfig`` 組åˆã€‚這很難用測試來糾æ£â€”—腦力在這è£æ˜¯æœ‰ å›žå ±çš„ã€‚ -9) 用 sparse 檢查乾淨。 +9) é€šéŽ sparse 清查。 + （åƒè¦‹ Documentation/translations/zh_CN/dev-tools/sparse.rst ） 10) 使用 ``make checkstack`` å’Œ ``make namespacecheck`` 並修復他們發ç¾çš„任何 å•é¡Œã€‚ .. note:: - ``checkstack`` 並沒有明確指出å•é¡Œï¼Œä½†æ˜¯ä»»ä½•ä¸€å€‹åœ¨å †æ£§ä¸Šä½¿ç”¨è¶…éŽ512 + ``checkstack`` 並ä¸æœƒæ˜Žç¢ºæŒ‡å‡ºå•é¡Œï¼Œä½†æ˜¯ä»»ä½•ä¸€å€‹åœ¨å †æ£§ä¸Šä½¿ç”¨è¶…éŽ512 å—節的函數都å¯ä»¥é€²è¡Œæ›´æ”¹ã€‚ -11) 包括 :ref:`kernel-doc <kernel_doc>` å…§æ ¸æ–‡æª”ä»¥è¨˜éŒ„å…¨å±€å…§æ ¸API。（éœæ…‹å‡½æ•¸ - ä¸éœ€è¦ï¼Œä½†ä¹Ÿå¯ä»¥ã€‚）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查 - :ref:`kernel-doc <kernel_doc>` 並修復任何å•é¡Œã€‚ +11) 包括 :ref:`kernel-doc <kernel_doc_zh>` å…§æ ¸æ–‡æª”ä»¥è¨˜éŒ„å…¨å±€å…§æ ¸API。（éœæ…‹ + 函數ä¸éœ€è¦ï¼Œä½†ä¹Ÿå¯ä»¥ã€‚）使用 ``make htmldocs`` 或 ``make pdfdocs`` 檢查 + :ref:`kernel-doc <kernel_doc_zh>` 並修復任何å•é¡Œã€‚ -12) 通éŽä»¥ä¸‹é¸é …åŒæ™‚啓用的測試 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, +12) 通éŽä»¥ä¸‹é¸é …åŒæ™‚啓用的測試： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` - -13) 已經éŽæ§‹å»ºå’Œé‹è¡Œæ™‚測試，包括有或沒有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + ``CONFIG_PROVE_RCU`` å’Œ ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。 -14) 如果補ä¸ç¨‹åºå½±éŸ¿IO/ç£ç¢Ÿç‰ï¼šä½¿ç”¨æˆ–ä¸ä½¿ç”¨ ``CONFIG_LBDAF`` 進行測試。 +13) 在 ``CONFIG_SMP``, ``CONFIG_PREEMPT`` 開啓和關閉的情æ³ä¸‹éƒ½é€²è¡Œæ§‹å»ºå’Œé‹è¡Œ + 時測試。 -15) 所有代碼路徑都已在啓用所有lockdep功能的情æ³ä¸‹é‹è¡Œã€‚ +14) 所有代碼路徑都已在啓用所有æ»éŽ–檢測（lockdep）功能的情æ³ä¸‹é‹è¡Œã€‚ -16) 所有新的/procæ¢ç›®éƒ½è¨˜éŒ„在 ``Documentation/`` +15) 所有新的 ``/proc`` æ¢ç›®éƒ½è¨˜éŒ„在 ``Documentation/`` -17) æ‰€æœ‰æ–°çš„å…§æ ¸å¼•å°Žåƒæ•¸éƒ½è¨˜éŒ„在 +16) æ‰€æœ‰æ–°çš„å…§æ ¸å¼•å°Žåƒæ•¸éƒ½è¨˜éŒ„在 Documentation/admin-guide/kernel-parameters.rst ä¸ã€‚ -18) 所有新的模塊åƒæ•¸éƒ½è¨˜éŒ„在 ``MODULE_PARM_DESC()`` +17) 所有新的模塊åƒæ•¸éƒ½è¨˜éŒ„在 ``MODULE_PARM_DESC()`` -19) 所有新的用戶空間接å£éƒ½è¨˜éŒ„在 ``Documentation/ABI/`` ä¸ã€‚有關詳細信æ¯ï¼Œ +18) 所有新的用戶空間接å£éƒ½è¨˜éŒ„在 ``Documentation/ABI/`` ä¸ã€‚有關詳細信æ¯ï¼Œ è«‹åƒé–± ``Documentation/ABI/README`` 。更改用戶空間接å£çš„補ä¸æ‡‰è©²æŠ„é€ linux-api@vger.kernel.org。 -20) 已通éŽè‡³å°‘注入slabå’Œpage分é…失敗進行檢查。請åƒé–± ``Documentation/fault-injection/`` +19) 已通éŽè‡³å°‘注入slabå’Œpage分é…失敗進行檢查。請åƒé–± ``Documentation/fault-injection/`` 。 å¦‚æžœæ–°ä»£ç¢¼æ˜¯å¯¦è³ªæ€§çš„ï¼Œé‚£éº¼æ·»åŠ å系統特定的故障注入å¯èƒ½æ˜¯åˆé©çš„。 -21) æ–°æ·»åŠ çš„ä»£ç¢¼å·²ç¶“ç”¨ ``gcc -W`` ç·¨è¯ï¼ˆä½¿ç”¨ ``make EXTRA-CFLAGS=-W`` ）。這 - 將產生大é‡å™ªè²ï¼Œä½†å°æ–¼æŸ¥æ‰¾è«¸å¦‚「è¦å‘Šï¼šæœ‰ç¬¦è™Ÿå’Œç„¡ç¬¦è™Ÿä¹‹é–“的比較ã€ä¹‹é¡žçš„錯誤 +20) æ–°æ·»åŠ çš„ä»£ç¢¼å·²ç¶“ç”¨ ``gcc -W`` ç·¨è¯ï¼ˆä½¿ç”¨ ``make EXTRA-CFLAGS=-W`` ）。這 + 將產生大é‡å™ªè²ï¼Œä½†å°æ–¼æŸ¥æ‰¾è«¸å¦‚“è¦å‘Šï¼šæœ‰ç¬¦è™Ÿå’Œç„¡ç¬¦è™Ÿä¹‹é–“的比較â€ä¹‹é¡žçš„錯誤 很有用。 -22) 在它被åˆä½µåˆ°-mm補ä¸é›†ä¸ä¹‹å¾Œé€²è¡Œæ¸¬è©¦ï¼Œä»¥ç¢ºä¿å®ƒä»ç„¶èˆ‡æ‰€æœ‰å…¶ä»–排隊的補ä¸ä»¥ +21) 在它被åˆä½µåˆ°-mm補ä¸é›†ä¸ä¹‹å¾Œé€²è¡Œæ¸¬è©¦ï¼Œä»¥ç¢ºä¿å®ƒä»ç„¶èˆ‡æ‰€æœ‰å…¶ä»–排隊的補ä¸ä»¥ åŠVMã€VFS和其他å系統ä¸çš„å„種更改一起工作。 -23) 所有內å˜å±éšœä¾‹å¦‚ ``barrier()``, ``rmb()``, ``wmb()`` 都需è¦åŽŸå§‹ç¢¼ä¸çš„注 +22) 所有內å˜å±éšœï¼ˆä¾‹å¦‚ ``barrier()``, ``rmb()``, ``wmb()`` ）都需è¦æºä»£ç¢¼æ³¨ 釋來解釋它們æ£åœ¨åŸ·è¡Œçš„æ“作åŠå…¶åŽŸå› çš„é‚輯。 -24) 如果補ä¸æ·»åŠ 了任何ioctl，那麼也è¦æ›´æ–° ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +23) 如果補ä¸æ·»åŠ 了任何ioctl，那麼也è¦æ›´æ–° + ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 -25) 如果修改後的原始碼ä¾è³´æˆ–使用與以下 ``Kconfig`` ç¬¦è™Ÿç›¸é—œçš„ä»»ä½•å…§æ ¸API或 +24) 如果修改後的æºä»£ç¢¼ä¾è³´æˆ–使用與以下 ``Kconfig`` ç¬¦è™Ÿç›¸é—œçš„ä»»ä½•å…§æ ¸API或 功能，則在ç¦ç”¨ç›¸é—œ ``Kconfig`` 符號和/或 ``=m`` （如果該é¸é …å¯ç”¨ï¼‰çš„æƒ…æ³ ä¸‹æ¸¬è©¦ä»¥ä¸‹å¤šå€‹æ§‹å»º[並éžæ‰€æœ‰é€™äº›éƒ½åŒæ™‚å˜åœ¨ï¼Œåªæ˜¯å®ƒå€‘çš„å„種/隨機組åˆ]： - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (但是後者伴隨 ``CONFIG_NET=y``). + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` ï¼ˆä½†æ˜¯æœ€å¾Œä¸€å€‹éœ€è¦ ``CONFIG_NET=y`` ）。 diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index 0746809c31a2..8272b3218b54 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -1,229 +1,199 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_submittingpatches: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_TW.rst -:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +.. _tw_submittingpatches: -è¯è€…:: +:Original: Documentation/process/submitting-patches.rst - ä¸æ–‡ç‰ˆç¶è·è€…： é¾å®‡ TripleX Chung <xxx.phy@gmail.com> - ä¸æ–‡ç‰ˆç¿»è¯è€…： é¾å®‡ TripleX Chung <xxx.phy@gmail.com> - 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> - ä¸æ–‡ç‰ˆæ ¡è¯è€…： æŽé™½ Li Yang <leoyang.li@nxp.com> - çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com> - 胡皓文 Hu Haowen <src.res.211@gmail.com> +:è¯è€…: + - é¾å®‡ TripleX Chung <xxx.phy@gmail.com> + - 時奎亮 Alex Shi <alexs@kernel.org> + - å³æƒ³æˆ Wu XiangCheng <bobwxc@email.cn> +:æ ¡è¯: + - æŽé™½ Li Yang <leoyang.li@nxp.com> + - çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com> + - 胡皓文 Hu Haowen <src.res.211@gmail.com> -å¦‚ä½•è®“ä½ çš„æ”¹å‹•é€²å…¥å…§æ ¸ -====================== -å°æ–¼æƒ³è¦å°‡æ”¹å‹•æ交到 Linux å…§æ ¸çš„å€‹äººæˆ–è€…å…¬å¸ä¾†èªªï¼Œå¦‚æžœä¸ç†Ÿæ‚‰ã€Œè¦çŸ©ã€ï¼Œ -æ交的æµç¨‹æœƒè®“人ç•æ‡¼ã€‚本文檔收集了一系列建è°ï¼Œé€™äº›å»ºè°å¯ä»¥å¤§å¤§çš„æé«˜ä½ +æ交補ä¸ï¼šå¦‚ä½•è®“ä½ çš„æ”¹å‹•é€²å…¥å…§æ ¸ +================================ + +å°æ–¼æƒ³è¦å°‡æ”¹å‹•æ交到 Linux å…§æ ¸çš„å€‹äººæˆ–è€…å…¬å¸ä¾†èªªï¼Œå¦‚æžœä¸ç†Ÿæ‚‰â€œè¦çŸ©â€ï¼Œ +æ交的æµç¨‹æœƒè®“人ç•æ‡¼ã€‚本文檔包å«äº†ä¸€ç³»åˆ—建è°ï¼Œå¯ä»¥å¤§å¤§æé«˜ä½ çš„æ”¹å‹•è¢«æŽ¥å—的機會. -以下文檔å«æœ‰å¤§é‡ç°¡æ½”的建è°ï¼Œ 具體請見： -:ref:`Documentation/process <development_process_main>` -åŒæ¨£ï¼Œ:ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>` -給出在æ交代碼å‰éœ€è¦æª¢æŸ¥çš„é …ç›®çš„åˆ—è¡¨ã€‚ +本文檔以較爲簡潔的行文給出了大é‡å»ºè°ã€‚é—œæ–¼å…§æ ¸é–‹ç™¼æµç¨‹å¦‚何進行的詳細信æ¯ï¼Œ +åƒè¦‹ï¼š Documentation/translations/zh_CN/process/development-process.rst 。 +Documentation/translations/zh_CN/process/submit-checklist.rst 給出了一系列 +æ交補ä¸ä¹‹å‰è¦æª¢æŸ¥çš„äº‹é …ã€‚è¨å‚™æ¨¹ç›¸é—œçš„補ä¸ï¼Œè«‹åƒé–± +Documentation/devicetree/bindings/submitting-patches.rst 。 -å…¶ä¸è¨±å¤šæ¥é©Ÿæ述了Git版本控制系統的默èªè¡Œçˆ²ï¼›å¦‚果您使用Git來準備補ä¸ï¼Œ -您將發ç¾å®ƒçˆ²æ‚¨å®Œæˆçš„大部分機械工作，儘管您ä»ç„¶éœ€è¦æº–備和記錄一組åˆç†çš„ -補ä¸ã€‚一般來說，使用gitå°‡ä½¿æ‚¨ä½œçˆ²å…§æ ¸é–‹ç™¼äººå“¡çš„ç”Ÿæ´»æ›´è¼•é¬†ã€‚ +本文檔å‡è¨æ‚¨æ£åœ¨ä½¿ç”¨ ``git`` æº–å‚™ä½ çš„è£œä¸ã€‚如果您ä¸ç†Ÿæ‚‰ ``git`` ，最好å¸ç¿’ +å¦‚ä½•ä½¿ç”¨å®ƒï¼Œé€™å°‡ä½¿æ‚¨ä½œçˆ²å…§æ ¸é–‹ç™¼äººå“¡çš„ç”Ÿæ´»è®Šå¾—æ›´åŠ è¼•é¬†ã€‚ +部分å系統和ç¶è·äººå“¡çš„樹有一些關於其工作æµç¨‹å’Œè¦æ±‚çš„é¡å¤–ä¿¡æ¯ï¼Œè«‹åƒé–± +Documentation/process/maintainer-handbooks.rst 。 -0) ç²å–當å‰æºç¢¼æ¨¹ ------------------ +ç²å–當å‰æºç¢¼æ¨¹ +-------------- -如果您沒有一個å¯ä»¥ä½¿ç”¨ç•¶å‰å…§æ ¸åŽŸå§‹ç¢¼çš„å˜å„²åº«ï¼Œè«‹ä½¿ç”¨gitç²å–ä¸€å€‹ã€‚æ‚¨å°‡è¦ -從主線å˜å„²åº«é–‹å§‹ï¼Œå®ƒå¯ä»¥é€šéŽä»¥ä¸‹æ–¹å¼ç²å–:: +如果您手é 沒有當å‰å…§æ ¸æºä»£ç¢¼çš„å˜å„²åº«ï¼Œè«‹ä½¿ç”¨ ``git`` ç²å–一份。您需è¦å…ˆç²å– +主線å˜å„²åº«ï¼Œå®ƒå¯ä»¥é€šéŽä»¥ä¸‹å‘½ä»¤æ‹‰å–:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -但是，請注æ„，您å¯èƒ½ä¸å¸Œæœ›ç›´æŽ¥é‡å°ä¸»ç·šæ¨¹é€²è¡Œé–‹ç™¼ã€‚大多數å系統ç¶è·äººå“¡é‹ +但是，請注æ„，您å¯èƒ½ä¸æƒ³ç›´æŽ¥é‡å°ä¸»ç·šæ¨¹é€²è¡Œé–‹ç™¼ã€‚大多數å系統ç¶è·äººå“¡é‹ 行自己的樹，並希望看到é‡å°é€™äº›æ¨¹æº–備的補ä¸ã€‚è«‹åƒè¦‹MAINTAINERS文件ä¸åç³» -統的 **T:** é …ä»¥æŸ¥æ‰¾è©²æ¨¹ï¼Œæˆ–è€…ç°¡å–®åœ°è©¢å•ç¶è·è€…該樹是å¦æœªåœ¨å…¶ä¸åˆ—出。 - -ä»ç„¶å¯ä»¥é€šéŽtarballsä¸‹è¼‰å…§æ ¸ç‰ˆæœ¬ï¼ˆå¦‚ä¸‹ä¸€ç¯€æ‰€è¿°ï¼‰ï¼Œä½†é€™æ˜¯é€²è¡Œå…§æ ¸é–‹ç™¼çš„ -一種困難的方å¼ã€‚ - -1) "diff -up" -------------- - -使用 "diff -up" 或者 "diff -uprN" 來創建補ä¸ã€‚ - -æ‰€æœ‰å…§æ ¸çš„æ”¹å‹•ï¼Œéƒ½æ˜¯ä»¥è£œä¸çš„å½¢å¼å‘ˆç¾çš„，補ä¸ç”± diff(1) 生æˆã€‚創建補ä¸çš„ -時候，è¦ç¢ºèªå®ƒæ˜¯ä»¥ "unified diff" æ ¼å¼å‰µå»ºçš„ï¼Œé€™ç¨®æ ¼å¼ç”± diff(1) çš„ '-u' -åƒæ•¸ç”Ÿæˆã€‚而且，請使用 '-p' åƒæ•¸ï¼Œé‚£æ¨£æœƒé¡¯ç¤ºæ¯å€‹æ”¹å‹•æ‰€åœ¨çš„C函數，使得 -產生的補ä¸å®¹æ˜“讀得多。補ä¸æ‡‰è©²åŸºæ–¼å…§æ ¸åŽŸå§‹ç¢¼æ¨¹çš„æ ¹ç›®éŒ„ï¼Œè€Œä¸æ˜¯è£¡é‚Šçš„ä»» -何å目錄。 - -爲一個單ç¨çš„文件創建補ä¸ï¼Œä¸€èˆ¬ä¾†èªªé€™æ¨£åšå°±å¤ 了:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -爲多個文件創建補ä¸ï¼Œä½ å¯ä»¥è§£é–‹ä¸€å€‹æ²’有修改éŽçš„å…§æ ¸åŽŸå§‹ç¢¼æ¨¹ï¼Œç„¶å¾Œå’Œä½ è‡ª -å·±çš„ä»£ç¢¼æ¨¹ä¹‹é–“åš diff 。例如:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -"dontdiff" æ˜¯å…§æ ¸åœ¨ç·¨è¯çš„時候產生的文件的列表，列表ä¸çš„文件在 diff(1) -產生的補ä¸é‡Œæœƒè¢«è·³éŽã€‚ - -ç¢ºå®šä½ çš„è£œä¸é‡Œæ²’有包å«ä»»ä½•ä¸å±¬æ–¼é€™æ¬¡è£œä¸æ交的é¡å¤–文件。記得在用diff(1) -生æˆè£œä¸ä¹‹å¾Œï¼Œå¯©é–±ä¸€æ¬¡è£œä¸ï¼Œä»¥ç¢ºä¿æº–確。 - -å¦‚æžœä½ çš„æ”¹å‹•å¾ˆæ•£äº‚ï¼Œä½ æ‡‰è©²ç ”ç©¶ä¸€ä¸‹å¦‚ä½•å°‡è£œä¸åˆ†å‰²æˆç¨ç«‹çš„部分，將改動分 -割æˆä¸€ç³»åˆ—åˆä¹Žé‚輯的æ¥é©Ÿã€‚é€™æ¨£æ›´å®¹æ˜“è®“å…¶ä»–å…§æ ¸é–‹ç™¼è€…å¯©æ ¸ï¼Œå¦‚æžœä½ æƒ³ä½ çš„ -補ä¸è¢«æŽ¥å—，這是很é‡è¦çš„。請åƒé–±ï¼š -:ref:`tw_split_changes` - -å¦‚æžœä½ ç”¨ ``git`` , ``git rebase -i`` å¯ä»¥å¹«åŠ©ä½ é€™ä¸€é»žã€‚å¦‚æžœä½ ä¸ç”¨ ``git``, -``quilt`` <https://savannah.nongnu.org/projects/quilt> å¦å¤–一個æµè¡Œçš„é¸æ“‡ã€‚ +統的 **T:** é …ä»¥æŸ¥æ‰¾è©²æ¨¹ï¼Œæˆ–è€…ç›´æŽ¥è©¢å•ç¶è·è€…該樹是å¦æœªåœ¨å…¶ä¸åˆ—出。 .. _tw_describe_changes: -2) æè¿°ä½ çš„æ”¹å‹• ---------------- +æè¿°ä½ çš„æ”¹å‹• +------------ æè¿°ä½ çš„å•é¡Œã€‚無論您的補ä¸æ˜¯ä¸€è¡ŒéŒ¯èª¤ä¿®å¾©é‚„是5000è¡Œæ–°åŠŸèƒ½ï¼Œéƒ½å¿…é ˆæœ‰ä¸€å€‹æ½›åœ¨ -çš„å•é¡Œæ¿€å‹µæ‚¨å®Œæˆé€™é …工作。讓審稿人相信有一個å•é¡Œå€¼å¾—解決，讓他們讀完第一段 -是有æ„義的。 +çš„å•é¡Œæ¿€å‹µæ‚¨å®Œæˆé€™é …工作。說æœå¯©é–±è€…相信有一個å•é¡Œå€¼å¾—解決，讓他們讀完第一段 +後就能明白這一點。 æ述用戶å¯è¦‹çš„影響。直接崩潰和鎖定是相當有說æœåŠ›çš„，但並ä¸æ˜¯æ‰€æœ‰çš„錯誤都那麼 -明目張胆。å³ä½¿åœ¨ä»£ç¢¼å¯©æŸ¥æœŸé–“發ç¾äº†é€™å€‹å•é¡Œï¼Œä¹Ÿè¦æ述一下您èªçˆ²å®ƒå¯èƒ½å°ç”¨æˆ¶ç”¢ +明目張膽。å³ä½¿åœ¨ä»£ç¢¼å¯©é–±æœŸé–“發ç¾äº†é€™å€‹å•é¡Œï¼Œä¹Ÿè¦æ述一下您èªçˆ²å®ƒå¯èƒ½å°ç”¨æˆ¶ç”¢ 生的影響。請記ä½ï¼Œå¤§å¤šæ•¸Linux安è£é‹è¡Œçš„å…§æ ¸ä¾†è‡ªäºŒç´šç©©å®šæ¨¹æˆ–ç‰¹å®šæ–¼ä¾›æ‡‰å•†/ç”¢å“ çš„æ¨¹ï¼Œåªå¾žä¸Šæ¸¸ç²¾é¸ç‰¹å®šçš„補ä¸ï¼Œå› æ¤è«‹åŒ…å«ä»»ä½•å¯ä»¥å¹«åŠ©æ‚¨å°‡æ›´æ”¹å®šä½åˆ°ä¸‹æ¸¸çš„內容： -è§¸ç™¼çš„å ´æ™¯ã€DMESG的摘錄ã€å´©æ½°æè¿°ã€æ€§èƒ½å›žæ¸ã€å»¶é²å°–峯ã€éŽ–定ç‰ã€‚ +è§¸ç™¼çš„å ´æ™¯ã€DMESG的摘錄ã€å´©æ½°æè¿°ã€æ€§èƒ½è¿´æ¸ã€å»¶é²å°–峯ã€éŽ–定ç‰ã€‚ -é‡åŒ–優化和權衡。如果您è²ç¨±åœ¨æ€§èƒ½ã€å…§å˜æ¶ˆè€—ã€å †æ£§å 用空間或二進ä½å¤§å°æ–¹é¢æœ‰æ‰€ -改進，請包括支æŒå®ƒå€‘的數å—。但也è¦æè¿°ä¸æ˜Žé¡¯çš„æˆæœ¬ã€‚優化通常ä¸æ˜¯å…費的，而是 -在CPUã€å…§å˜å’Œå¯è®€æ€§ä¹‹é–“進行權衡；或者，探索性的工作，在ä¸åŒçš„å·¥ä½œè² è¼‰ä¹‹é–“é€² +質é‡å„ªåŒ–和權衡。如果您è²ç¨±åœ¨æ€§èƒ½ã€å…§å˜æ¶ˆè€—ã€å †æ£§ä½”用空間或二進制大å°æ–¹é¢æœ‰æ‰€ +改進，請包括支æŒå®ƒå€‘的數據。但也è¦æè¿°ä¸æ˜Žé¡¯çš„æˆæœ¬ã€‚優化通常ä¸æ˜¯é›¶æˆæœ¬çš„，而是 +在CPUã€å…§å˜å’Œå¯è®€æ€§ä¹‹é–“進行權衡；或者，åšæŽ¢ç´¢æ€§çš„工作，在ä¸åŒçš„å·¥ä½œè² è¼‰ä¹‹é–“é€² 行權衡。請æ述優化的é 期缺點，以便審閱者å¯ä»¥æ¬Šè¡¡æˆæœ¬å’Œæ”¶ç›Šã€‚ -一旦å•é¡Œå»ºç«‹èµ·ä¾†ï¼Œå°±è¦è©³ç´°åœ°æ述一下您實際在åšä»€éº¼ã€‚å°æ–¼å¯©é–±è€…來說，用簡單的 -英語æ述代碼的變化是很é‡è¦çš„，以驗è‰ä»£ç¢¼çš„行爲是å¦ç¬¦åˆæ‚¨çš„æ„願。 +æ出å•é¡Œä¹‹å¾Œï¼Œå°±è¦è©³ç´°åœ°æ述一下您實際在åšçš„技術細節。å°æ–¼å¯©é–±è€…來說，用簡練的 +英語æ述代碼的變化是很é‡è¦çš„，以驗è‰ä»£ç¢¼çš„行爲是å¦ç¬¦åˆæ‚¨çš„æ„圖。 -如果您將補ä¸æ述寫在一個表單ä¸ï¼Œé€™å€‹è¡¨å–®å¯ä»¥å¾ˆå®¹æ˜“地作爲「æ交日誌ã€æ”¾å…¥Linux -的原始碼管ç†ç³»çµ±gitä¸ï¼Œé‚£éº¼ç¶è·äººå“¡å°‡éžå¸¸æ„Ÿè¬æ‚¨ã€‚見 :ref:`tw_explicit_in_reply_to`. +如果您將補ä¸æ述寫æˆâ€œæ¨™æº–æ ¼å¼â€ï¼Œå¯ä»¥å¾ˆå®¹æ˜“地作爲“æ交日誌â€æ”¾å…¥Linuxçš„æºä»£ +碼管ç†ç³»çµ± ``git`` ä¸ï¼Œé‚£éº¼ç¶è·äººå“¡å°‡éžå¸¸æ„Ÿè¬æ‚¨ã€‚ +åƒè¦‹ :ref:`zh_the_canonical_patch_format` 。 æ¯å€‹è£œä¸åªè§£æ±ºä¸€å€‹å•é¡Œã€‚å¦‚æžœä½ çš„æè¿°é–‹å§‹è®Šé•·ï¼Œé€™å°±è¡¨æ˜Žä½ å¯èƒ½éœ€è¦æ‹†åˆ†ä½ 的補ä¸ã€‚ -請見 :ref:`tw_split_changes` +請見 :ref:`zh_split_changes` 。 -æ交或é‡æ–°æ交修補程åºæˆ–修補程åºç³»åˆ—時，請包括完整的修補程åºèªªæ˜Žå’Œç†ç”±ã€‚ä¸è¦ +æ交或é‡æ–°æ交補ä¸æˆ–補ä¸ç³»åˆ—時，請包括完整的補ä¸èªªæ˜Žå’Œç†ç”±ã€‚ä¸è¦ åªèªªé€™æ˜¯è£œä¸ï¼ˆç³»åˆ—）的第幾版。ä¸è¦æœŸæœ›å系統ç¶è·äººå“¡å¼•ç”¨æ›´æ—©çš„補ä¸ç‰ˆæœ¬æˆ–引用 URL來查找補ä¸æ述並將其放入補ä¸ä¸ã€‚也就是說，補ä¸ï¼ˆç³»åˆ—）åŠå…¶æ述應該是ç¨ç«‹çš„。 -這å°ç¶è·äººå“¡å’Œå¯©æŸ¥äººå“¡éƒ½æœ‰å¥½è™•ã€‚一些評審者å¯èƒ½ç”šè‡³æ²’有收到補ä¸çš„早期版本。 +這å°ç¶è·äººå“¡å’Œå¯©é–±è€…都有好處。一些審閱者å¯èƒ½ç”šè‡³æ²’有收到補ä¸çš„早期版本。 -æè¿°ä½ åœ¨å‘½ä»¤èªžæ°£ä¸çš„變化，例如「make xyzzy do frotzã€è€Œä¸æ˜¯ã€Œ[這個補ä¸]make -xyzzy do frotzã€æˆ–「[我]changed xyzzy to do frotzã€ï¼Œå°±å¥½åƒä½ 在命令代碼庫改變 +用祈使å¥æè¿°ä½ çš„è®Šæ›´ï¼Œä¾‹å¦‚â€œmake xyzzy do frotzâ€è€Œä¸æ˜¯â€œ[This patch]make +xyzzy do frotzâ€æˆ–“[I]changed xyzzy to do frotzâ€ï¼Œå°±å¥½åƒä½ 在命令代碼庫改變 它的行爲一樣。 -如果修補程åºä¿®å¾©äº†ä¸€å€‹è¨˜éŒ„çš„bugæ¢ç›®ï¼Œè«‹æŒ‰ç·¨è™Ÿå’ŒURL引用該bugæ¢ç›®ã€‚如果補ä¸ä¾† -自郵件列表討論，請給出郵件列表å˜æª”çš„URL；使用帶有 ``Message-ID`` çš„ -https://lore.kernel.org/ é‡å®šå‘，以確ä¿é€£çµä¸æœƒéŽæ™‚。 - -但是，在沒有外部資æºçš„情æ³ä¸‹ï¼Œå„˜é‡è®“ä½ çš„è§£é‡‹å¯ç†è§£ã€‚除了æ供郵件列表å˜æª”或 -bugçš„URL之外，還è¦ç¸½çµéœ€è¦æ交補ä¸çš„相關討論è¦é»žã€‚ - -如果您想è¦å¼•ç”¨ä¸€å€‹ç‰¹å®šçš„æ交，ä¸è¦åªå¼•ç”¨æ交的 SHA-1 ID。還請包括æ交的一行 -摘è¦ï¼Œä»¥ä¾¿æ–¼å¯©é–±è€…了解它是關於什麼的。例如:: +如果您想è¦å¼•ç”¨ä¸€å€‹ç‰¹å®šçš„æ交，ä¸è¦åªå¼•ç”¨æ交的SHA-1 ID。還請包括æ交的一行 +摘è¦ï¼Œä»¥ä¾¿æ–¼å¯©é–±è€…çžè§£å®ƒæ˜¯é—œæ–¼ä»€éº¼çš„。例如:: Commit e21d2170f36602ae2708 ("video: remove unnecessary platform_set_drvdata()") removed the unnecessary platform_set_drvdata(), but left the variable "dev" unused, delete it. -您還應該確ä¿è‡³å°‘使用å‰12ä½ SHA-1 ID. å…§æ ¸å˜å„²åº«åŒ…å«*許多*å°è±¡ï¼Œä½¿èˆ‡è¼ƒçŸçš„ID +您還應該確ä¿è‡³å°‘使用å‰12ä½SHA-1 IDã€‚å…§æ ¸å˜å„²åº«åŒ…å« *許多* å°è±¡ï¼Œä½¿è¼ƒçŸçš„ID 發生è¡çªçš„å¯èƒ½æ€§å¾ˆå¤§ã€‚記ä½ï¼Œå³ä½¿ç¾åœ¨ä¸æœƒèˆ‡æ‚¨çš„å…個å—符ID發生è¡çªï¼Œé€™ç¨®æƒ…æ³ -å¯èƒ½äº”年後改變。 +也å¯èƒ½åœ¨äº”年後改變。 + +如果該變更的相關討論或背景信æ¯å¯ä»¥åœ¨ç¶²ä¸ŠæŸ¥é–±ï¼Œè«‹åŠ 上“Link:â€æ¨™ç±¤æŒ‡å‘它。例如 +ä½ çš„è£œä¸ä¿®å¾©äº†ä¸€å€‹ç¼ºé™·ï¼Œéœ€è¦æ·»åŠ 一個帶有URL的標籤指å‘郵件列表å˜æª”或缺陷跟蹤器 +çš„ç›¸é—œå ±å‘Šï¼›å¦‚æžœè©²è£œä¸æ˜¯ç”±ä¸€äº›æ—©å…ˆéƒµä»¶åˆ—表討論或網絡上的記錄引起的，請指å‘它。 + +當éˆæŽ¥åˆ°éƒµä»¶åˆ—表å˜æª”時，請首é¸lore.kernel.org郵件å˜æª”æœå‹™ã€‚用郵件ä¸çš„ +``Message-ID`` é （去掉尖括號）å¯ä»¥å‰µå»ºéˆæŽ¥URL。例如:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +請檢查該éˆæŽ¥ä»¥ç¢ºä¿å¯ç”¨ä¸”指å‘æ£ç¢ºçš„郵件。 + +ä¸éŽï¼Œåœ¨æ²’有外部資æºçš„情æ³ä¸‹ï¼Œä¹Ÿè¦å„˜é‡è®“ä½ çš„è§£é‡‹å¯ç†è§£ã€‚除了æ供郵件列表å˜æª”或 +缺陷的URL之外，還è¦éœ€è¦ç¸½çµè©²è£œä¸çš„相關討論è¦é»žã€‚ -如果修補程åºä¿®å¾©äº†ç‰¹å®šæ交ä¸çš„錯誤，例如，使用 ``git bisct`` ï¼Œè«‹ä½¿ç”¨å¸¶æœ‰å‰ -12個å—符SHA-1 ID çš„"Fixes:"標記和單行摘è¦ã€‚爲了簡化ä¸è¦å°‡æ¨™è¨˜æ‹†åˆ†çˆ²å¤šå€‹ï¼Œ -è¡Œã€æ¨™è¨˜ä¸å—分æžè…³æœ¬ã€Œ75列æ›è¡Œã€è¦å‰‡çš„é™åˆ¶ã€‚例如:: +如果補ä¸ä¿®å¾©äº†ç‰¹å®šæ交ä¸çš„錯誤，例如使用 ``git bisct`` 發ç¾äº†ä¸€å€‹å•é¡Œï¼Œè«‹ä½¿ç”¨ +帶有å‰12個å—符SHA-1 ID的“Fixes:â€æ¨™ç±¤å’Œå–®è¡Œæ‘˜è¦ã€‚爲了簡化解æžè…³æœ¬ï¼Œä¸è¦å°‡è©² +標籤拆分爲多行，標籤ä¸å—“75列æ›è¡Œâ€è¦å‰‡çš„é™åˆ¶ã€‚例如:: - Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -下列 ``git config`` è¨ç½®å¯ä»¥æ·»åŠ 讓 ``git log``, ``git show`` æ¼‚äº®çš„é¡¯ç¤ºæ ¼å¼:: +下列 ``git config`` è¨ç½®å¯ä»¥è®“ ``git log``, ``git show`` å¢žåŠ ä¸Šè¿°é¢¨æ ¼çš„é¡¯ç¤ºæ ¼å¼:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") +使用示例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + .. _tw_split_changes: -3) æ‹†åˆ†ä½ çš„æ”¹å‹• ---------------- +æ‹†åˆ†ä½ çš„æ”¹å‹• +------------ -å°‡æ¯å€‹é‚輯更改分隔æˆä¸€å€‹å–®ç¨çš„補ä¸ã€‚ +å°‡æ¯å€‹ **é‚輯更改** 拆分æˆä¸€å€‹å–®ç¨çš„補ä¸ã€‚ -ä¾‹å¦‚ï¼Œå¦‚æžœä½ çš„æ”¹å‹•é‡ŒåŒæ™‚有bugä¿®æ£å’Œæ€§èƒ½å„ªåŒ–，那麼把這些改動拆分到兩個或 -者更多的補ä¸æ–‡ä»¶ä¸ã€‚å¦‚æžœä½ çš„æ”¹å‹•åŒ…å«å°API的修改，並且修改了驅動程åºä¾†é© -應這些新的API，那麼把這些修改分æˆå…©å€‹è£œä¸ã€‚ +ä¾‹å¦‚ï¼Œå¦‚æžœä½ çš„æ”¹å‹•è£åŒæ™‚有bugä¿®æ£å’Œæ€§èƒ½å„ªåŒ–，那麼把這些改動拆分到兩個或 +者更多的補ä¸æ–‡ä»¶ä¸ã€‚å¦‚æžœä½ çš„æ”¹å‹•åŒ…å«å°APIçš„ä¿®æ”¹ï¼Œä¸¦ä¸”å¢žåŠ äº†ä¸€å€‹ä½¿ç”¨è©²æ–°API +的驅動，那麼把這些修改分æˆå…©å€‹è£œä¸ã€‚ å¦ä¸€æ–¹é¢ï¼Œå¦‚æžœä½ å°‡ä¸€å€‹å–®ç¨çš„改動åšæˆå¤šå€‹è£œä¸æ–‡ä»¶ï¼Œé‚£éº¼å°‡å®ƒå€‘åˆä½µæˆä¸€å€‹ -å–®ç¨çš„補ä¸æ–‡ä»¶ã€‚這樣一個é‚輯上單ç¨çš„改動åªè¢«åŒ…å«åœ¨ä¸€å€‹è£œä¸æ–‡ä»¶é‡Œã€‚ +å–®ç¨çš„補ä¸æ–‡ä»¶ã€‚這樣一個é‚輯上單ç¨çš„改動åªè¢«åŒ…å«åœ¨ä¸€å€‹è£œä¸æ–‡ä»¶è£ã€‚ -如果有一個補ä¸ä¾è³´å¦å¤–一個補ä¸ä¾†å®Œæˆå®ƒçš„改動，那沒å•é¡Œã€‚ç°¡å–®çš„åœ¨ä½ çš„è£œ -ä¸æ述里指出「這個補ä¸ä¾è³´æŸè£œä¸ã€å°±å¥½äº†ã€‚ +需è¦è¨˜ä½çš„一點是，æ¯å€‹è£œä¸çš„更改都應易於ç†è§£ï¼Œä»¥ä¾¿å¯©é–±è€…é©—è‰ã€‚æ¯å€‹è£œä¸éƒ½æ‡‰è©² +å°å…¶åƒ¹å€¼é€²è¡Œé—¡è¿°ã€‚ -在將您的更改劃分爲一系列補ä¸æ™‚，è¦ç‰¹åˆ¥æ³¨æ„確ä¿å…§æ ¸åœ¨ç³»åˆ—ä¸çš„æ¯å€‹è£œä¸ä¹‹å¾Œ -都能æ£å¸¸æ§‹å»ºå’Œé‹è¡Œã€‚使用 ``git bisect`` 來追蹤å•é¡Œçš„開發者å¯èƒ½æœƒåœ¨ä»»ä½•æ™‚ -å€™åˆ†å‰²ä½ çš„è£œä¸ç³»åˆ—ï¼›å¦‚æžœä½ åœ¨ä¸é–“引入錯誤，他們ä¸æœƒæ„Ÿè¬ä½ 。 +如果有一個補ä¸ä¾è³´å¦å¤–一個補ä¸ä¾†å®Œæˆå®ƒçš„改動，那沒å•é¡Œã€‚ç›´æŽ¥åœ¨ä½ çš„è£œ +ä¸æè¿°è£æŒ‡å‡º **“這個補ä¸ä¾è³´æŸè£œä¸â€** 就好了。 -å¦‚æžœä½ ä¸èƒ½å°‡è£œä¸æ¿ƒç¸®æˆæ›´å°‘的文件，那麼æ¯æ¬¡å¤§ç´„發é€å‡º15個，然後ç‰å¾…審查 +在將您的更改劃分爲一系列補ä¸æ™‚，è¦ç‰¹åˆ¥æ³¨æ„確ä¿å…§æ ¸åœ¨æ‡‰ç”¨ç³»åˆ—ä¸çš„æ¯å€‹è£œä¸ä¹‹å¾Œ +都能æ£å¸¸æ§‹å»ºå’Œé‹è¡Œã€‚使用 ``git bisect`` 來追蹤å•é¡Œçš„開發者å¯èƒ½æœƒåœ¨ä»»ä½•åœ°æ–¹åˆ† +å‰²ä½ çš„è£œä¸ç³»åˆ—ï¼›å¦‚æžœä½ åœ¨ä¸é–“引入錯誤，他們ä¸æœƒæ„Ÿè¬ä½ 。 + +å¦‚æžœä½ ä¸èƒ½å°‡è£œä¸ç³»åˆ—濃縮得更å°ï¼Œé‚£éº¼æ¯æ¬¡å¤§ç´„發é€å‡º15個補ä¸ï¼Œç„¶å¾Œç‰å¾…審閱 和集æˆã€‚ -4) æª¢æŸ¥ä½ çš„æ›´æ”¹é¢¨æ ¼ -------------------- +æª¢æŸ¥ä½ çš„æ›´æ”¹é¢¨æ ¼ +---------------- -檢查您的補ä¸æ˜¯å¦å˜åœ¨åŸºæœ¬æ¨£å¼è¡çªï¼Œè©³ç´°ä¿¡æ¯å¯åœ¨ -:ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` -ä¸æ‰¾åˆ°ã€‚如果ä¸é€™æ¨£åšï¼Œåªæœƒæµªè²»å¯©ç¨¿äººçš„æ™‚é–“ï¼Œä¸¦ä¸”æœƒå°Žè‡´ä½ çš„è£œä¸è¢«æ‹’絕，甚至 +檢查您的補ä¸æ˜¯å¦é•å了基本樣å¼è¦å®šï¼Œè©³ç´°ä¿¡æ¯åƒè¦‹ +Documentation/translations/zh_CN/process/coding-style.rst +ä¸æ‰¾åˆ°ã€‚如果ä¸é€™æ¨£åšï¼Œåªæœƒæµªè²»å¯©é–±è€…çš„æ™‚é–“ï¼Œä¸¦ä¸”æœƒå°Žè‡´ä½ çš„è£œä¸è¢«æ‹’絕，甚至 å¯èƒ½æ²’有被閱讀。 一個é‡è¦çš„例外是在將代碼從一個文件移動到å¦ä¸€å€‹æ–‡ä»¶æ™‚——在這種情æ³ä¸‹ï¼Œæ‚¨ä¸æ‡‰ 該在移動代碼的åŒä¸€å€‹è£œä¸ä¸ä¿®æ”¹ç§»å‹•çš„代碼。這清楚地æ述了移動代碼和您的更改 -的行爲。這大大有助於審查實際差異，並å…許工具更好地跟蹤代碼本身的æ·å²ã€‚ +的行爲。這大大有助於審閱實際差異，並å…許工具更好地跟蹤代碼本身的æ·å²ã€‚ 在æ交之å‰ï¼Œä½¿ç”¨è£œä¸æ¨£å¼æª¢æŸ¥ç¨‹åºæª¢æŸ¥è£œä¸ï¼ˆscripts/check patch.pl）。ä¸éŽï¼Œ 請注æ„，樣å¼æª¢æŸ¥ç¨‹åºæ‡‰è©²è¢«è¦–爲一個指å—，而ä¸æ˜¯ä½œçˆ²äººé¡žåˆ¤æ–·çš„替代å“。如果您 -的代碼看起來更好，但有é•è¦è¡Œçˆ²ï¼Œé‚£éº¼æœ€å¥½ä¸è¦ä½¿ç”¨å®ƒã€‚ +的代碼看起來更好，但有é•è¦è¡Œçˆ²ï¼Œé‚£éº¼æœ€å¥½åˆ¥ç®¡å®ƒã€‚ æª¢æŸ¥è€…å ±å‘Šä¸‰å€‹ç´šåˆ¥ï¼š - ERROR：很å¯èƒ½å‡ºéŒ¯çš„事情 - - WARNING：需è¦ä»”ç´°å¯©æŸ¥çš„äº‹é … + - WARNING：需è¦ä»”ç´°å¯©é–±çš„äº‹é … - CHECK：需è¦æ€è€ƒçš„事情 æ‚¨æ‡‰è©²èƒ½å¤ åˆ¤æ–·æ‚¨çš„è£œä¸ä¸å˜åœ¨çš„所有é•è¦è¡Œçˆ²ã€‚ -5) é¸æ“‡è£œä¸æ”¶ä»¶äºº ------------------ +é¸æ“‡è£œä¸æ”¶ä»¶äºº +-------------- -您應該總是在任何補ä¸ä¸Šè¤‡è£½ç›¸æ‡‰çš„å系統ç¶è·äººå“¡ï¼Œä»¥ç²å¾—他們ç¶è·çš„代碼；查看 -ç¶è·äººå“¡æ–‡ä»¶å’ŒåŽŸå§‹ç¢¼ä¿®è¨‚æ·å²è¨˜éŒ„，以了解這些ç¶è·äººå“¡æ˜¯èª°ã€‚腳本 -scripts/get_Maintainer.pl在這個æ¥é©Ÿä¸éžå¸¸æœ‰ç”¨ã€‚如果您找ä¸åˆ°æ£åœ¨å·¥ä½œçš„å系統 +您應該總是知會任何補ä¸ç›¸æ‡‰ä»£ç¢¼çš„å系統ç¶è·äººå“¡ï¼›æŸ¥çœ‹ +ç¶è·äººå“¡æ–‡ä»¶å’Œæºä»£ç¢¼ä¿®è¨‚æ·å²è¨˜éŒ„，以çžè§£é€™äº›ç¶è·äººå“¡æ˜¯èª°ã€‚腳本 +scripts/get_maintainer.pl在這個æ¥é©Ÿä¸éžå¸¸æœ‰ç”¨ã€‚如果您找ä¸åˆ°æ£åœ¨å·¥ä½œçš„å系統 çš„ç¶è·äººå“¡ï¼Œé‚£éº¼Andrew Morton（akpm@linux-foundation.org）將充當最後的ç¶è· 人員。 -您通常還應該é¸æ“‡è‡³å°‘一個郵件列表來接收補ä¸é›†çš„。linux-kernel@vger.kernel.org -作爲最後一個解決辦法的列表，但是這個列表上的體ç©å·²ç¶“引起了許多開發人員的拒絕。 -在MAINTAINERS文件ä¸æŸ¥æ‰¾å系統特定的列表；您的補ä¸å¯èƒ½æœƒåœ¨é‚£è£¡å¾—到更多的關注。 +您通常還應該é¸æ“‡è‡³å°‘一個郵件列表來接收補ä¸é›†çš„副本。linux-kernel@vger.kernel.org +是所有補ä¸çš„默èªåˆ—表，但是這個列表的æµé‡å·²ç¶“導致了許多開發人員ä¸å†çœ‹å®ƒã€‚ +在MAINTAINERS文件ä¸æŸ¥æ‰¾å系統特定的列表；您的補ä¸å¯èƒ½æœƒåœ¨é‚£è£å¾—到更多的關注。 ä¸éŽï¼Œè«‹ä¸è¦ç™¼é€åžƒåœ¾éƒµä»¶åˆ°ç„¡é—œçš„列表。 è¨±å¤šèˆ‡å…§æ ¸ç›¸é—œçš„åˆ—è¡¨è¨—ç®¡åœ¨vger.kernel.org上；您å¯ä»¥åœ¨ @@ -232,188 +202,170 @@ http://vger.kernel.org/vger-lists.html 上找到它們的列表。ä¸éŽï¼Œä¹Ÿæœ ä¸è¦ä¸€æ¬¡ç™¼é€è¶…éŽ15個補ä¸åˆ°vger郵件列表ï¼ï¼ï¼ï¼ -Linus Torvalds 是決定改動能å¦é€²å…¥ Linux å…§æ ¸çš„æœ€çµ‚è£æ±ºè€…。他的 e-mail -地å€æ˜¯ <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 -的說，最好別給他發 e-mail。 +Linus Torvalds是決定改動能å¦é€²å…¥ Linux å…§æ ¸çš„æœ€çµ‚è£æ±ºè€…。他的郵件地å€æ˜¯ +torvalds@linux-foundation.org 。他收到的郵件很多，所以一般來說最好 **別** +給他發郵件。 -如果您有修復å¯åˆ©ç”¨å®‰å…¨æ¼æ´žçš„補ä¸ï¼Œè«‹å°‡è©²è£œä¸ç™¼é€åˆ° security@kernel.org。å°æ–¼ -åš´é‡çš„bug，å¯ä»¥è€ƒæ…®çŸæœŸæš«åœä»¥å…許分銷商å‘用戶發布補ä¸ï¼›åœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œé¡¯ç„¶ä¸æ‡‰ -將補ä¸ç™¼é€åˆ°ä»»ä½•å…¬å…±åˆ—表。 +如果您有修復å¯åˆ©ç”¨å®‰å…¨æ¼æ´žçš„補ä¸ï¼Œè«‹å°‡è©²è£œä¸ç™¼é€åˆ° security@kernel.org 。å°æ–¼ +åš´é‡çš„bug，å¯ä»¥è€ƒæ…®çŸæœŸç¦ä»¤ä»¥å…許分銷商（有時間）å‘用戶發佈補ä¸ï¼›åœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œ +顯然ä¸æ‡‰å°‡è£œä¸ç™¼é€åˆ°ä»»ä½•å…¬å…±åˆ—表。 +åƒè¦‹ Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 -ä¿®å¾©å·²ç™¼å¸ƒå…§æ ¸ä¸åš´é‡éŒ¯èª¤çš„補ä¸ç¨‹åºæ‡‰è©²æŒ‡å‘穩定版ç¶è·äººå“¡ï¼Œæ–¹æ³•æ˜¯æ”¾é€™æ¨£çš„一行:: +ä¿®å¾©å·²ç™¼ä½ˆå…§æ ¸ä¸åš´é‡éŒ¯èª¤çš„補ä¸ç¨‹åºæ‡‰è©²æŠ„é€çµ¦ç©©å®šç‰ˆç¶è·äººå“¡ï¼Œæ–¹æ³•æ˜¯æŠŠä»¥ä¸‹åˆ—è¡Œ +放進補ä¸çš„籤準å€ï¼ˆæ³¨æ„，ä¸æ˜¯é›»å郵件收件人）:: - Cc: stable@vger.kernel.org + Cc: stable@vger.kernel.org -進入補ä¸çš„簽准å€ï¼ˆæ³¨æ„，ä¸æ˜¯é›»å郵件收件人）。除了這個文件之外，您還應該閱讀 -:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +除了本文件之外，您還應該閱讀 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 -但是，請注æ„，一些å系統ç¶è·äººå“¡å¸Œæœ›å¾—出他們自己的çµè«–，å³å“ªäº›è£œä¸æ‡‰è©²è¢«æ”¾åˆ° -穩定的樹上。尤其是網絡ç¶è·äººå“¡ï¼Œä¸å¸Œæœ›çœ‹åˆ°å–®å€‹é–‹ç™¼äººå“¡åœ¨è£œä¸ä¸æ·»åŠ åƒä¸Šé¢é€™æ¨£ -的行。 - -å¦‚æžœæ›´æ”¹å½±éŸ¿åˆ°ç”¨æˆ¶å’Œå…§æ ¸æŽ¥å£ï¼Œè«‹å‘手冊é ç¶è·äººå“¡ï¼ˆå¦‚ç¶è·äººå“¡æ–‡ä»¶ä¸æ‰€åˆ—ï¼‰ç™¼é€ +如果更改影響到用戶å´å…§æ ¸æŽ¥å£ï¼Œè«‹å‘手冊é ç¶è·äººå“¡ï¼ˆå¦‚ç¶è·äººå“¡æ–‡ä»¶ä¸æ‰€åˆ—ï¼‰ç™¼é€ æ‰‹å†Šé 補ä¸ï¼Œæˆ–至少發é€æ›´æ”¹é€šçŸ¥ï¼Œä»¥ä¾¿ä¸€äº›ä¿¡æ¯é€²å…¥æ‰‹å†Šé 。還應將用戶空間API -更改複製到 linux-api@vger.kernel.org。 +更改抄é€åˆ° linux-api@vger.kernel.org 。 + -6) 沒有 MIME 編碼，沒有連çµï¼Œæ²’有壓縮，沒有附件，åªæœ‰ç´”文本 ------------------------------------------------------------ +ä¸è¦MIME編碼，ä¸è¦éˆæŽ¥ï¼Œä¸è¦å£“縮，ä¸è¦é™„件，åªè¦ç´”文本 +------------------------------------------------------ Linus å’Œå…¶ä»–çš„å…§æ ¸é–‹ç™¼è€…éœ€è¦é–±è®€å’Œè©•è«–ä½ æ交的改動。å°æ–¼å…§æ ¸é–‹ç™¼è€…來說 -，å¯ä»¥ã€Œå¼•ç”¨ã€ä½ 的改動很é‡è¦ï¼Œä½¿ç”¨ä¸€èˆ¬çš„ e-mail 工具，他們就å¯ä»¥åœ¨ä½ çš„ +，å¯ä»¥â€œå¼•ç”¨â€ä½ 的改動很é‡è¦ï¼Œä½¿ç”¨ä¸€èˆ¬çš„郵件工具，他們就å¯ä»¥åœ¨ä½ çš„ 代碼的任何ä½ç½®æ·»åŠ 評論。 -å› çˆ²é€™å€‹åŽŸå› ï¼Œæ‰€æœ‰çš„æ交的補ä¸éƒ½æ˜¯ e-mail ä¸ã€Œå…§åµŒã€çš„。 +å› çˆ²é€™å€‹åŽŸå› ï¼Œæ‰€æœ‰çš„æ交的補ä¸éƒ½æ˜¯éƒµä»¶ä¸â€œå…§åµŒâ€çš„。最簡單（和推薦）的方法就 +是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email`` +的交互å¼æ•™ç¨‹ã€‚ + +å¦‚æžœä½ é¸æ“‡ä¸ç”¨ ``git send-email`` ： .. warning:: - å¦‚æžœä½ ä½¿ç”¨å‰ªåˆ‡-ç²˜è²¼ä½ çš„è£œä¸ï¼Œå°å¿ƒä½ 的編輯器的自動æ›è¡ŒåŠŸèƒ½ç ´å£žä½ çš„è£œä¸ -ä¸è¦å°‡è£œä¸ä½œçˆ² MIME 編碼的附件，ä¸ç®¡æ˜¯å¦å£“縮。很多æµè¡Œçš„ e-mail è»Ÿé«”ä¸ -是任何時候都將 MIME 編碼的附件當作純文本發é€çš„ï¼Œé€™æœƒä½¿å¾—åˆ¥äººç„¡æ³•åœ¨ä½ çš„ -代碼ä¸åŠ 評論。å¦å¤–，MIME 編碼的附件會讓 Linus 多花一點時間來處ç†ï¼Œé€™å°± -é™ä½Žäº†ä½ 的改動被接å—çš„å¯èƒ½æ€§ã€‚ + å¦‚æžœä½ ä½¿ç”¨å‰ªåˆ‡-ç²˜è²¼ä½ çš„è£œä¸ï¼Œå°å¿ƒä½ 的編輯器的自動æ›è¡ŒåŠŸèƒ½ç ´å£žä½ çš„è£œä¸ -ä¾‹å¤–ï¼šå¦‚æžœä½ çš„éƒµéžå“¡å¼„壞了補ä¸ï¼Œé‚£éº¼æœ‰äººå¯èƒ½æœƒè¦æ±‚ä½ ä½¿ç”¨mimeé‡æ–°ç™¼é€è£œä¸ +ä¸è¦å°‡è£œä¸ä½œçˆ²MIME編碼的附件，ä¸ç®¡æ˜¯å¦å£“縮。很多æµè¡Œçš„éƒµä»¶è»Ÿä»¶ä¸ +是任何時候都將MIME編碼的附件當作純文本發é€çš„ï¼Œé€™æœƒä½¿å¾—åˆ¥äººç„¡æ³•åœ¨ä½ çš„ +代碼ä¸åŠ 評論。å¦å¤–，MIME編碼的附件會讓Linus多花一點時間來處ç†ï¼Œé€™å°± +é™ä½Žäº†ä½ 的改動被接å—çš„å¯èƒ½æ€§ã€‚ -è«‹åƒé–± :ref:`Documentation/translations/zh_TW/process/email-clients.rst <tw_email_clients>` -以ç²å–有關é…置電å郵件客戶端以使其ä¸å—影響地發é€ä¿®è£œç¨‹åºçš„æ示。 +ä¾‹å¤–ï¼šå¦‚æžœä½ çš„éƒµè·¯æ壞了補ä¸ï¼Œé‚£éº¼æœ‰äººå¯èƒ½æœƒè¦æ±‚ä½ ä½¿ç”¨MIMEé‡æ–°ç™¼é€è£œä¸ã€‚ -7) e-mail çš„å¤§å° ----------------- +è«‹åƒé–± Documentation/translations/zh_CN/process/email-clients.rst +以ç²å–有關é…置電å郵件客戶端以使其ä¸å—影響地發é€è£œä¸çš„æ示。 -大的改動å°éƒµä»¶åˆ—表ä¸åˆé©ï¼Œå°æŸäº›ç¶è·è€…也ä¸åˆé©ã€‚å¦‚æžœä½ çš„è£œä¸ï¼Œåœ¨ä¸å£“縮 -的情æ³ä¸‹ï¼Œè¶…éŽäº†300kBï¼Œé‚£éº¼ä½ æœ€å¥½å°‡è£œä¸æ”¾åœ¨ä¸€å€‹èƒ½é€šéŽ internet 訪å•çš„æœ -務器上，然後用指å‘ä½ çš„è£œä¸çš„ URL 替代。但是請注æ„，如果您的補ä¸è¶…éŽäº† -300kb，那麼它幾乎肯定需è¦è¢«ç ´å£žã€‚ +回覆審閱æ„見 +------------ -8）回複評審æ„見 ---------------- +ä½ çš„è£œä¸å¹¾ä¹Žè‚¯å®šæœƒå¾—到審閱者å°è£œä¸æ”¹é€²æ–¹æ³•çš„評論（以回覆郵件的形å¼ï¼‰ã€‚æ‚¨å¿…é ˆ +å°é€™äº›è©•è«–作出回應；讓補ä¸è¢«å¿½ç•¥çš„一個好辦法就是忽略審閱者的æ„見。直接回復郵 +件來回應æ„見å³å¯ã€‚ä¸æœƒå°Žè‡´ä»£ç¢¼æ›´æ”¹çš„æ„見或å•é¡Œå¹¾ä¹Žè‚¯å®šæœƒå¸¶ä¾†è¨»é‡‹æˆ–變更日誌的 +改變，以便下一個審閱者更好地çžè§£æ£åœ¨ç™¼ç”Ÿçš„事情。 -ä½ çš„è£œä¸å¹¾ä¹Žè‚¯å®šæœƒå¾—到評審者å°è£œä¸æ”¹é€²æ–¹æ³•çš„è©•è«–ã€‚æ‚¨å¿…é ˆå°é€™äº›è©•è«–作出 -回應；讓補ä¸è¢«å¿½ç•¥çš„一個好辦法就是忽略審閱者的æ„見。ä¸æœƒå°Žè‡´ä»£ç¢¼æ›´æ”¹çš„ -æ„見或å•é¡Œå¹¾ä¹Žè‚¯å®šæœƒå¸¶ä¾†æ³¨é‡‹æˆ–變更日誌的改變，以便下一個評審者更好地了解 -æ£åœ¨ç™¼ç”Ÿçš„事情。 +一定è¦å‘Šè¨´å¯©é–±è€…ä½ åœ¨åšä»€éº¼æ”¹è®Šï¼Œä¸¦æ„Ÿè¬ä»–們的時間。代碼審閱是一個累人且耗時的 +éŽç¨‹ï¼Œå¯©é–±è€…有時會變得暴èºã€‚å³ä½¿åœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œä¹Ÿè¦ç¦®è²Œåœ°å›žæ‡‰ä¸¦è§£æ±ºä»–們指出的 +å•é¡Œã€‚當發é€ä¸‹ä¸€ç‰ˆæ™‚，在å°é¢éƒµä»¶æˆ–ç¨ç«‹è£œä¸é‡ŒåŠ 上 ``patch changelog`` 說明與 +å‰ä¸€ç‰ˆæœ¬çš„ä¸åŒä¹‹è™•ï¼ˆåƒè¦‹ :ref:`zh_the_canonical_patch_format` ）。 -一定è¦å‘Šè¨´å¯©ç¨¿äººä½ 在åšä»€éº¼æ”¹è®Šï¼Œä¸¦æ„Ÿè¬ä»–們的時間。代碼審查是一個累人且 -耗時的éŽç¨‹ï¼Œå¯©æŸ¥äººå“¡æœ‰æ™‚會變得暴èºã€‚å³ä½¿åœ¨é€™ç¨®æƒ…æ³ä¸‹ï¼Œä¹Ÿè¦ç¦®è²Œåœ°å›žæ‡‰ä¸¦ -解決他們指出的å•é¡Œã€‚ +.. _tw_resend_reminders: -9）ä¸è¦æ´©æ°£æˆ–ä¸è€ç…© -------------------- +ä¸è¦æ³„氣或ä¸è€ç…© +---------------- -æ交更改後，請è€å¿ƒç‰å¾…。審閱者是忙碌的人，å¯èƒ½ç„¡æ³•ç«‹å³è¨ªå•æ‚¨çš„修補程åºã€‚ +æ交更改後，請è€å¿ƒç‰å¾…。審閱者是大忙人，å¯èƒ½ç„¡æ³•ç«‹å³å¯©é–±æ‚¨çš„補ä¸ã€‚ -曾幾何時，補ä¸æ›¾åœ¨æ²’有評論的情æ³ä¸‹æ¶ˆå¤±åœ¨ç©ºç™½ä¸ï¼Œä½†é–‹ç™¼éŽç¨‹æ¯”ç¾åœ¨æ›´åŠ é †åˆ©ã€‚ -您應該在一周左å³çš„時間內收到評論；如果沒有收到評論，請確ä¿æ‚¨å·²å°‡è£œä¸ç™¼é€ -到æ£ç¢ºçš„ä½ç½®ã€‚在é‡æ–°æ交或è¯ç¹«å¯©é–±è€…之å‰è‡³å°‘ç‰å¾…一周-在諸如åˆä½µçª—å£ä¹‹é¡žçš„ +曾幾何時，補ä¸æ›¾åœ¨æ²’收到評論的情æ³ä¸‹æ¶ˆå¤±åœ¨è™›ç©ºä¸ï¼Œä½†ç¾åœ¨é–‹ç™¼éŽç¨‹æ‡‰è©²æ›´åŠ é †åˆ©äº†ã€‚ +您應該在一週左å³çš„時間內收到評論；如果沒有收到評論，請確ä¿æ‚¨å·²å°‡è£œä¸ç™¼é€ +到æ£ç¢ºçš„ä½ç½®ã€‚在é‡æ–°æ交或è¯ç¹«å¯©é–±è€…之å‰è‡³å°‘ç‰å¾…一週——在諸如åˆä½µçª—å£ä¹‹é¡žçš„ ç¹å¿™æ™‚é–“å¯èƒ½æ›´é•·ã€‚ -10）主題ä¸åŒ…å« PATCH --------------------- - -由於到linuså’Œlinuxå…§æ ¸çš„é›»å郵件æµé‡å¾ˆé«˜ï¼Œé€šå¸¸æœƒåœ¨ä¸»é¡Œè¡Œå‰é¢åŠ 上[PATCH] -å‰ç¶´. 這使Linuså’Œå…¶ä»–å…§æ ¸é–‹ç™¼äººå“¡æ›´å®¹æ˜“å°‡è£œä¸èˆ‡å…¶ä»–é›»å郵件討論å€åˆ†é–‹ã€‚ +在ç‰äº†å¹¾å€‹æ˜ŸæœŸå¾Œï¼Œç”¨å¸¶RESEND的主題é‡ç™¼è£œä¸ä¹Ÿæ˜¯å¯ä»¥çš„:: -11ï¼‰ç°½ç½²ä½ çš„ä½œå“-開發者原始èªè‰ -------------------------------- + [PATCH Vx RESEND] sub/sys: Condensed patch summary -çˆ²äº†åŠ å¼·å°èª°åšäº†ä½•äº‹çš„追蹤，尤其是å°é‚£äº›é€éŽå¥½å¹¾å±¤çš„ç¶è·è€…的補ä¸ï¼Œæˆ‘們 -建è°åœ¨ç™¼é€å‡ºåŽ»çš„補ä¸ä¸ŠåŠ 一個 「sign-off〠的éŽç¨‹ã€‚ +ç•¶ä½ ç™¼ä½ˆè£œä¸ï¼ˆç³»åˆ—）修改版的時候，ä¸è¦åŠ 上“RESENDâ€â€”—“RESENDâ€åªé©ç”¨æ–¼é‡ +æ–°æ交之å‰æœªç¶“修改的補ä¸ï¼ˆç³»åˆ—）。 -"sign-off" 是在補ä¸çš„注釋的最後的簡單的一行文å—，èªè‰ä½ 編寫了它或者其他 -人有權力將它作爲開放原始碼的補ä¸å‚³éžã€‚è¦å‰‡å¾ˆç°¡å–®ï¼šå¦‚æžœä½ èƒ½èªè‰å¦‚下信æ¯: - -開發者來æºè‰æ›¸ 1.1 -^^^^^^^^^^^^^^^^^^ - -å°æ–¼æœ¬é …目的貢ç»ï¼Œæˆ‘èªè‰å¦‚下信æ¯ï¼š +主題ä¸åŒ…å« PATCH +---------------- - （a）這些貢ç»æ˜¯å®Œå…¨æˆ–者部分的由我創建，我有權利以文件ä¸æŒ‡å‡º - 的開放原始碼許å¯è‰æ交它；或者 - （b）這些貢ç»åŸºæ–¼ä»¥å‰çš„工作，據我所知，這些以å‰çš„工作å—æ°ç•¶çš„開放 - 原始碼許å¯è‰ä¿è·ï¼Œè€Œä¸”ï¼Œæ ¹æ“šè¨±å¯è‰ï¼Œæˆ‘有權æ交修改後的貢ç»ï¼Œ - ç„¡è«–æ˜¯å®Œå…¨é‚„æ˜¯éƒ¨åˆ†ç”±æˆ‘å‰µé€ ï¼Œé€™äº›è²¢ç»éƒ½ä½¿ç”¨åŒä¸€å€‹é–‹æ”¾åŽŸå§‹ç¢¼è¨±å¯è‰ - （除éžæˆ‘被å…許用其它的許å¯è‰ï¼‰ï¼Œæ£å¦‚文件ä¸æŒ‡å‡ºçš„；或者 - （c）這些貢ç»ç”±èªè‰ï¼ˆa），（b）或者（c）的人直接æ供給我，而 - 且我沒有修改它。 - （d）我ç†è§£ä¸¦åŒæ„é€™å€‹é …ç›®å’Œè²¢ç»æ˜¯å…¬é–‹çš„，貢ç»çš„記錄（包括我 - 一起æ交的個人記錄，包括 sign-off ）被永久ç¶è·ä¸¦ä¸”å¯ä»¥å’Œé€™å€‹é …ç›® - 或者開放原始碼的許å¯è‰åŒæ¥åœ°å†ç™¼è¡Œã€‚ +由於到Linuså’Œlinux-kernelçš„é›»å郵件æµé‡å¾ˆé«˜ï¼Œé€šå¸¸æœƒåœ¨ä¸»é¡Œè¡Œå‰é¢åŠ 上[PATCH] +å‰ç¶´ã€‚這使Linuså’Œå…¶ä»–å…§æ ¸é–‹ç™¼äººå“¡æ›´å®¹æ˜“å°‡è£œä¸èˆ‡å…¶ä»–é›»å郵件討論å€åˆ†é–‹ã€‚ -é‚£éº¼åŠ å…¥é€™æ¨£ä¸€è¡Œ:: +``git send-email`` æœƒè‡ªå‹•çˆ²ä½ åŠ ä¸Šã€‚ - Signed-off-by: Random J Developer <random@developer.example.org> +ç°½ç½²ä½ çš„ä½œå“——開發者來æºèªè‰ +------------------------------ -ä½¿ç”¨ä½ çš„çœŸå（抱æ‰ï¼Œä¸èƒ½ä½¿ç”¨å‡å或者匿å。） +çˆ²äº†åŠ å¼·å°èª°åšäº†ä½•äº‹çš„追蹤，尤其是å°é‚£äº›é€éŽå¥½å¹¾å±¤ç¶è·è€…æ‰æœ€çµ‚到é”的補ä¸ï¼Œæˆ‘ +們在通éŽéƒµä»¶ç™¼é€çš„補ä¸ä¸Šå¼•å…¥äº†â€œç°½ç½²ï¼ˆsign-off）â€æµç¨‹ã€‚ -æœ‰äººåœ¨æœ€å¾ŒåŠ ä¸Šæ¨™ç±¤ã€‚ç¾åœ¨é€™äº›æ±è¥¿æœƒè¢«å¿½ç•¥ï¼Œä½†æ˜¯ä½ å¯ä»¥é€™æ¨£åšï¼Œä¾†æ¨™è¨˜å…¬å¸ -內部的éŽç¨‹ï¼Œæˆ–者åªæ˜¯æŒ‡å‡ºé—œæ–¼ sign-off 的一些特殊細節。 +“簽署â€æ˜¯åœ¨è£œä¸è¨»é‡‹æœ€å¾Œçš„一行簡單文å—，èªè‰ä½ 編寫了它或者其他 +人有權力將它作爲開放æºä»£ç¢¼çš„補ä¸å‚³éžã€‚è¦å‰‡å¾ˆç°¡å–®ï¼šå¦‚æžœä½ èƒ½èªè‰å¦‚下信æ¯: -如果您是å系統或分支ç¶è·äººå“¡ï¼Œæœ‰æ™‚需è¦ç¨å¾®ä¿®æ”¹æ”¶åˆ°çš„補ä¸ï¼Œä»¥ä¾¿åˆä½µå®ƒå€‘， -å› çˆ²æ¨¹å’Œæ交者ä¸çš„代碼ä¸å®Œå…¨ç›¸åŒã€‚å¦‚æžœä½ åš´æ ¼éµå®ˆè¦å‰‡ï¼ˆcï¼‰ï¼Œä½ æ‡‰è©²è¦æ±‚æ交者 -é‡æ–°ç™¼å¸ƒï¼Œä½†é€™å®Œå…¨æ˜¯åœ¨æµªè²»æ™‚間和精力。è¦å‰‡ï¼ˆb）å…許您調整代碼，但是更改一個 -æ交者的代碼並讓他èªå¯æ‚¨çš„錯誤是éžå¸¸ä¸ç¦®è²Œçš„。è¦è§£æ±ºæ¤å•é¡Œï¼Œå»ºè°åœ¨æœ€å¾Œä¸€å€‹ -由簽åè¡Œå’Œæ‚¨çš„è¡Œä¹‹é–“æ·»åŠ ä¸€è¡Œï¼ŒæŒ‡ç¤ºæ›´æ”¹çš„æ€§è³ªã€‚é›–ç„¶é€™ä¸¦ä¸æ˜¯å¼·åˆ¶æ€§çš„，但似乎 -在æè¿°å‰åŠ 上您的郵件和/或姓å（全部用方括號括起來），這足以讓人注æ„到您å°æœ€ -後一分é˜çš„æ›´æ”¹è² æœ‰è²¬ä»»ã€‚ä¾‹å¦‚:: +開發者來æºèªè‰ 1.1 +^^^^^^^^^^^^^^^^^^ - Signed-off-by: Random J Developer <random@developer.example.org> - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> +å°æ–¼æœ¬é …目的貢ç»ï¼Œæˆ‘èªè‰å¦‚下信æ¯ï¼š -如果您ç¶è·ä¸€å€‹ç©©å®šçš„分支機構，åŒæ™‚希望å°ä½œè€…進行致è¬ã€è·Ÿè¹¤æ›´æ”¹ã€åˆä½µä¿®å¾©ä¸¦ -ä¿è·æ交者ä¸å—投訴，那麼這種åšæ³•å°¤å…¶æœ‰ç”¨ã€‚請注æ„，在任何情æ³ä¸‹éƒ½ä¸èƒ½æ›´æ”¹ä½œè€… -çš„ID（From é ï¼‰ï¼Œå› çˆ²å®ƒæ˜¯å‡ºç¾åœ¨æ›´æ”¹æ—¥èªŒä¸çš„標è˜ã€‚ + (a) 這些貢ç»æ˜¯å®Œå…¨æˆ–者部分的由我創建，我有權利以文件ä¸æŒ‡å‡º + 的開放æºä»£ç¢¼è¨±å¯è‰æ交它；或者 -å°å›žåˆï¼ˆback-porters）的特別說明：在æ交消æ¯çš„é ‚éƒ¨ï¼ˆä¸»é¡Œè¡Œä¹‹å¾Œï¼‰æ’å…¥ä¸€å€‹è£œä¸ -çš„èµ·æºæŒ‡ç¤ºä¼¼ä¹Žæ˜¯ä¸€ç¨®å¸¸è¦‹ä¸”有用的實è¸ï¼Œä»¥ä¾¿æ–¼è·Ÿè¹¤ã€‚例如，下é¢æ˜¯æˆ‘們在3.x穩定 -版本ä¸çœ‹åˆ°çš„內容:: + (b) 這些貢ç»åŸºæ–¼ä»¥å‰çš„工作，據我所知，這些以å‰çš„工作å—æ°ç•¶çš„開放 + æºä»£ç¢¼è¨±å¯è‰ä¿è·ï¼Œè€Œä¸”ï¼Œæ ¹æ“šæ–‡ä»¶ä¸æŒ‡å‡ºçš„許å¯è‰ï¼Œæˆ‘有權æ交修改後的貢ç»ï¼Œ + ç„¡è«–æ˜¯å®Œå…¨é‚„æ˜¯éƒ¨åˆ†ç”±æˆ‘å‰µé€ ï¼Œé€™äº›è²¢ç»éƒ½ä½¿ç”¨åŒä¸€å€‹é–‹æ”¾æºä»£ç¢¼è¨±å¯è‰ + （除éžæˆ‘被å…許用其它的許å¯è‰ï¼‰ï¼›æˆ–者 - Date: Tue Oct 7 07:26:38 2014 -0400 + (c) 這些貢ç»ç”±èªè‰ï¼ˆa），（b）或者（c）的人直接æ供給我，而 + 且我沒有修改它。 - libata: Un-break ATA blacklist + (d) 我ç†è§£ä¸¦åŒæ„é€™å€‹é …ç›®å’Œè²¢ç»æ˜¯å…¬é–‹çš„，貢ç»çš„記錄（包括我 + 一起æ交的個人記錄，包括sign-off）被永久ç¶è·ä¸¦ä¸”å¯ä»¥å’Œé€™å€‹é …ç›® + 或者開放æºä»£ç¢¼çš„許å¯è‰åŒæ¥åœ°å†ç™¼è¡Œã€‚ - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. +é‚£éº¼åŠ å…¥é€™æ¨£ä¸€è¡Œ:: -還有， é€™è£¡æ˜¯ä¸€å€‹èˆŠç‰ˆå…§æ ¸ä¸çš„一個回åˆè£œä¸:: + Signed-off-by: Random J Developer <random@developer.example.org> - Date: Tue May 13 22:12:27 2008 +0200 +ä½¿ç”¨ä½ çš„çœŸå（抱æ‰ï¼Œä¸èƒ½ä½¿ç”¨å‡å或者匿å。）如果使用 ``git commit -s`` 的話 +將會自動完æˆã€‚撤銷也應當包å«â€œSigned-off-byâ€ï¼Œ ``git revert -s`` æœƒå¹«ä½ æžå®šã€‚ - wireless, airo: waitbusy() won't delay +æœ‰äº›äººæœƒåœ¨æœ€å¾ŒåŠ ä¸Šé¡å¤–的標籤。ç¾åœ¨é€™äº›æ±è¥¿æœƒè¢«å¿½ç•¥ï¼Œä½†æ˜¯ä½ å¯ä»¥é€™æ¨£åšï¼Œä¾†æ¨™è¨˜ +å…¬å¸å…§éƒ¨çš„éŽç¨‹ï¼Œæˆ–者åªæ˜¯æŒ‡å‡ºé—œæ–¼ç°½ç½²çš„一些特殊細節。 - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] +作者簽署之後的任何其他簽署（Signed-off-by:'s）å‡ä¾†è‡ªè™•ç†å’Œå‚³éžè£œä¸çš„人員，但 +未åƒèˆ‡å…¶é–‹ç™¼ã€‚簽署éˆæ‡‰ç•¶åæ˜ è£œä¸å‚³æ’到ç¶è·è€…並最終傳æ’到Linus所經éŽçš„ **真實** +路徑，首個簽署指明單個作者的主è¦ä½œè€…身份。 -12）何時使用Acked-by:，CC:，和Co-Developed by: ----------------------------------------------- +何時使用Acked-by:，CC:，和Co-Developed by: +------------------------------------------ -Singed-off-by: 標記表示簽å者åƒèˆ‡äº†è£œä¸çš„開發，或者他/她在補ä¸çš„傳éžè·¯å¾‘ä¸ã€‚ +Singed-off-by: 標籤表示簽å者åƒèˆ‡äº†è£œä¸çš„開發，或者他/她在補ä¸çš„傳éžè·¯å¾‘ä¸ã€‚ -如果一個人沒有直接åƒèˆ‡è£œä¸çš„準備或處ç†ï¼Œä½†å¸Œæœ›è¡¨ç¤ºä¸¦è¨˜éŒ„他們å°è£œä¸çš„批准， -那麼他們å¯ä»¥è¦æ±‚在補ä¸çš„變更日誌ä¸æ·»åŠ 一個 Acked-by: +如果一個人沒有直接åƒèˆ‡è£œä¸çš„準備或處ç†ï¼Œä½†å¸Œæœ›è¡¨ç¤ºä¸¦è¨˜éŒ„他們å°è£œä¸çš„批准/è´Šæˆï¼Œ +那麼他們å¯ä»¥è¦æ±‚在補ä¸çš„變更日誌ä¸æ·»åŠ 一個Acked-by:。 -Acked-by：通常由å—影響代碼的ç¶è·è€…使用，當該ç¶è·è€…既沒有貢ç»ä¹Ÿæ²’有轉發補ä¸æ™‚。 +Acked-by: 通常由å—影響代碼的ç¶è·è€…使用，當該ç¶è·è€…既沒有貢ç»ä¹Ÿæ²’有轉發補ä¸æ™‚。 -Acked-by: ä¸åƒç°½å—人那樣æ£å¼ã€‚這是一個記錄，確èªäººè‡³å°‘審查了補ä¸ï¼Œä¸¦è¡¨ç¤ºæŽ¥å—。 -å› æ¤ï¼Œè£œä¸åˆä½µæœ‰æ™‚會手動將Acker的「Yep，looks good to meã€è½‰æ›çˆ² Acked-By：（但 +Acked-by: ä¸åƒç°½ç½²é‚£æ¨£æ£å¼ã€‚這是一個記錄，確èªäººè‡³å°‘審閱了補ä¸ï¼Œä¸¦è¡¨ç¤ºæŽ¥å—。 +å› æ¤ï¼Œè£œä¸åˆä½µæœ‰æ™‚會手動將Acker的“Yep，looks good to meâ€è½‰æ›çˆ² Acked-By:（但 請注æ„，通常最好è¦æ±‚一個明確的Ack）。 Acked-by：ä¸ä¸€å®šè¡¨ç¤ºå°æ•´å€‹è£œä¸çš„確èªã€‚例如，如果一個補ä¸å½±éŸ¿å¤šå€‹å系統，並且 -有一個：來自一個å系統ç¶è·è€…，那麼這通常表示åªç¢ºèªå½±éŸ¿ç¶è·è€…代碼的部分。這裡 -應該仔細判斷。如有疑å•ï¼Œæ‡‰åƒè€ƒéƒµä»¶åˆ—表檔案ä¸çš„原始討論。 +有一個來自æŸå€‹å系統ç¶è·è€…çš„Acked-By:，那麼這通常表示åªç¢ºèªå½±éŸ¿ç¶è·è€…代碼的部 +分。這è£æ‡‰è©²ä»”細判斷。如有疑å•ï¼Œæ‡‰åƒè€ƒéƒµä»¶åˆ—表å˜æª”ä¸çš„原始討論。 -如果æŸäººæœ‰æ©Ÿæœƒå°è£œä¸é€²è¡Œè©•è«–，但沒有æä¾›æ¤é¡žè©•è«–，您å¯ä»¥é¸æ“‡åœ¨è£œä¸ä¸æ·»åŠ ``Cc:`` -這是唯一一個標籤，它å¯ä»¥åœ¨æ²’有被它命å的人顯å¼æ“作的情æ³ä¸‹æ·»åŠ ，但它應該表明 -這個人是在補ä¸ä¸ŠæŠ„é€çš„。討論ä¸åŒ…å«äº†æ½›åœ¨åˆ©ç›Šç›¸é—œæ–¹ã€‚ +如果æŸäººæœ¬æ‡‰æœ‰æ©Ÿæœƒå°è£œä¸é€²è¡Œè©•è«–，但沒有æä¾›æ¤é¡žè©•è«–，您å¯ä»¥é¸æ“‡åœ¨è£œä¸ä¸æ·»åŠ +``Cc:`` 這是唯一å¯ä»¥åœ¨æ²’有被該人明確åŒæ„的情æ³ä¸‹æ·»åŠ 的標籤——但它應該表明 +這個人是在補ä¸ä¸ŠæŠ„é€çš„。æ¤æ¨™ç±¤è¨˜éŒ„了討論ä¸åŒ…å«çš„潛在利益相關方。 Co-developed-by: è²æ˜Žè£œä¸æ˜¯ç”±å¤šå€‹é–‹ç™¼äººå“¡å…±åŒå‰µå»ºçš„；當幾個人在一個補ä¸ä¸Šå·¥ -作時，它用於將屬性賦予共åŒä½œè€…（除了 From: æ‰€è³¦äºˆçš„ä½œè€…ä¹‹å¤–ï¼‰ã€‚å› çˆ² -Co-developed-by: 表示作者身份，所以æ¯å€‹å…±åŒé–‹ç™¼äººï¼šå¿…é ˆç·Šè·Ÿåœ¨ç›¸é—œåˆä½œä½œè€…çš„ -ç°½åä¹‹å¾Œã€‚æ¨™æº–çš„ç°½æ ¸ç¨‹åºè¦æ±‚ï¼šæ¨™è¨˜çš„ç°½æ ¸é †åºæ‡‰å„˜å¯èƒ½åæ˜ è£œä¸çš„時間æ·å²ï¼Œè€Œä¸ -ç®¡ä½œè€…æ˜¯é€šéŽ From ：還是由 Co-developed-by: å…±åŒé–‹ç™¼çš„。值得注æ„的是，最後一 -個簽å—äººï¼šå¿…é ˆå§‹çµ‚æ˜¯æ交補ä¸çš„開發人員。 +作時，它用於給出共åŒä½œè€…（除了From:æ‰€çµ¦å‡ºçš„ä½œè€…ä¹‹å¤–ï¼‰ã€‚å› çˆ²Co-developed-by: +表示作者身份，所以æ¯å€‹Co-developed-by:å¿…é ˆç·Šè·Ÿåœ¨ç›¸é—œåˆä½œä½œè€…的簽署之後。標準 +簽署程åºè¦æ±‚Singed-off-by:æ¨™ç±¤çš„é †åºæ‡‰å„˜å¯èƒ½åæ˜ è£œä¸çš„時間æ·å²ï¼Œç„¡è«–作者是通 +éŽFrom:還是Co-developed-by:表明。值得注æ„的是，最後一個Singed-off-by:å¿…é ˆæ˜¯ +æ交補ä¸çš„開發人員。 -注æ„，當作者也是電å郵件標題「發件人：ã€è¡Œä¸åˆ—出的人時，「From: 〠標記是å¯é¸çš„。 +注æ„，如果From:作者也是電å郵件標題的From:è¡Œä¸åˆ—出的人，則From:標籤是å¯é¸çš„。 -作者æ交的補ä¸ç¨‹åºç¤ºä¾‹:: +被From:作者æ交的補ä¸ç¤ºä¾‹:: <changelog> @@ -423,7 +375,7 @@ Co-developed-by: 表示作者身份，所以æ¯å€‹å…±åŒé–‹ç™¼äººï¼šå¿…é ˆç·Šè·Ÿ Signed-off-by: Second Co-Author <second@coauthor.example.org> Signed-off-by: From Author <from@author.example.org> -åˆä½œé–‹ç™¼è€…æ交的補ä¸ç¤ºä¾‹:: +被åˆä½œé–‹ç™¼è€…æ交的補ä¸ç¤ºä¾‹:: From: From Author <from@author.example.org> @@ -436,106 +388,115 @@ Co-developed-by: 表示作者身份，所以æ¯å€‹å…±åŒé–‹ç™¼äººï¼šå¿…é ˆç·Šè·Ÿ Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> -13ï¼‰ä½¿ç”¨å ±å‘Šäººï¼šã€æ¸¬è©¦äººï¼šã€å¯©æ ¸äººï¼šã€å»ºè°äººï¼šã€ä¿®å¾©äººï¼š --------------------------------------------------------- +使用Reported-by:ã€Tested-by:ã€Reviewed-by:ã€Suggested-by:å’ŒFixes: +----------------------------------------------------------------- Reported-by: 給那些發ç¾éŒ¯èª¤ä¸¦å ±å‘ŠéŒ¯èª¤çš„人致è¬ï¼Œå®ƒå¸Œæœ›æ¿€å‹µä»–們在將來å†æ¬¡å¹«åŠ© -我們。請注æ„，如果bug是以ç§æœ‰æ–¹å¼å ±å‘Šçš„，那麼在使用Reported-by標記之å‰ï¼Œè«‹ -先請求權é™ã€‚ +我們。請注æ„，如果bug是以ç§æœ‰æ–¹å¼å ±å‘Šçš„，那麼在使用Reported-by標籤之å‰ï¼Œè«‹ +先請求許å¯ã€‚æ¤æ¨™ç±¤æ˜¯çˆ²Bugè¨è¨ˆçš„；請ä¸è¦å°‡å…¶ç”¨æ–¼æ„Ÿè¬åŠŸèƒ½è«‹æ±‚。 -Tested-by: 標記表示補ä¸å·²ç”±æŒ‡å®šçš„人（在æŸäº›ç’°å¢ƒä¸ï¼‰æˆåŠŸæ¸¬è©¦ã€‚這個標籤通知 -ç¶è·äººå“¡å·²ç¶“執行了一些測試，爲將來的補ä¸æ供了一種定ä½æ¸¬è©¦äººå“¡çš„方法，並確 -ä¿æ¸¬è©¦äººå“¡çš„ä¿¡è½ã€‚ +Tested-by: 標籤表示補ä¸å·²ç”±æŒ‡å®šçš„人（在æŸäº›ç’°å¢ƒä¸ï¼‰æˆåŠŸæ¸¬è©¦ã€‚這個標籤通知 +ç¶è·äººå“¡å·²ç¶“執行了一些測試，爲將來的補ä¸æ供了一種定ä½æ¸¬è©¦äººå“¡çš„方法，並彰顯測試人員的功勞。 -Reviewed-by：相åï¼Œæ ¹æ“šå¯©æŸ¥äººçš„è²æ˜Žï¼Œè¡¨æ˜Žè©²è£œä¸å·²è¢«å¯©æŸ¥ä¸¦è¢«èªçˆ²æ˜¯å¯æŽ¥å—的： +Reviewed-byï¼šæ ¹æ“šå¯©é–±è€…çš„ç›£ç£è²æ˜Žï¼Œè¡¨æ˜Žè©²è£œä¸å·²è¢«å¯©é–±ä¸¦è¢«èªçˆ²æ˜¯å¯æŽ¥å—的： -審查人的監ç£è²æ˜Ž +審閱者的監ç£è²æ˜Ž ^^^^^^^^^^^^^^^^ -通éŽæ供我的 Reviewed-by，我è²æ˜Žï¼š +通éŽæ供我的Reviewed-by:標籤，我è²æ˜Žï¼š - (a) 我已經å°é€™å€‹è£œä¸é€²è¡Œäº†ä¸€æ¬¡æŠ€è¡“審查，以評估它是å¦é©åˆè¢«åŒ…å«åˆ° + (a) 我已經å°é€™å€‹è£œä¸é€²è¡Œäº†ä¸€æ¬¡æŠ€è¡“審閱，以評估它是å¦é©åˆè¢«åŒ…å«åˆ° ä¸»ç·šå…§æ ¸ä¸ã€‚ (b) 與補ä¸ç›¸é—œçš„任何å•é¡Œã€é¡§æ…®æˆ–å•é¡Œéƒ½å·²å饋給æ交者。我å°æäº¤è€…å° æˆ‘çš„è©•è«–çš„å›žæ‡‰æ„Ÿåˆ°æ»¿æ„。 - (c) 雖然這一æ交å¯èƒ½æœƒæ”¹é€²ä¸€äº›æ±è¥¿ï¼Œä½†æˆ‘相信，æ¤æ™‚，（1）å°å…§æ ¸ + (c) 雖然這一æ交å¯èƒ½ä»å¯è¢«æ”¹é€²ï¼Œä½†æˆ‘相信，æ¤æ™‚，（1）å°å…§æ ¸ 進行了有價值的修改，（2）沒有包å«çˆè«–ä¸æ¶‰åŠçš„已知å•é¡Œã€‚ - (d) 雖然我已經審查了補ä¸ä¸¦èªçˆ²å®ƒæ˜¯å¥å…¨çš„，但我ä¸æœƒï¼ˆé™¤éžå¦æœ‰æ˜Žç¢º - 說明）作出任何ä¿è‰æˆ–ä¿è‰å®ƒå°‡åœ¨ä»»ä½•çµ¦å®šæƒ…æ³ä¸‹å¯¦ç¾å…¶è¦å®šçš„目的 + (d) 雖然我已經審閱了補ä¸ä¸¦èªçˆ²å®ƒæ˜¯å¥å…¨çš„，但我ä¸æœƒï¼ˆé™¤éžå¦æœ‰æ˜Žç¢º + 說明）作出任何ä¿è‰æˆ–æ“”ä¿å®ƒæœƒåœ¨ä»»ä½•çµ¦å®šæƒ…æ³ä¸‹å¯¦ç¾å…¶è¦å®šçš„目的 或æ£å¸¸é‹è¡Œã€‚ -Reviewed-by 是一種觀點è²æ˜Žï¼Œå³è£œä¸æ˜¯å°å…§æ ¸çš„é©ç•¶ä¿®æ”¹ï¼Œæ²’有任何éºç•™çš„åš´é‡æŠ€è¡“ -å•é¡Œã€‚任何感興趣的審閱者（完æˆå·¥ä½œçš„人）都å¯ä»¥çˆ²ä¸€å€‹è£œä¸æ供一個 Review-by -標籤。æ¤æ¨™ç±¤ç”¨æ–¼å‘審閱者æ供致è¬ï¼Œä¸¦é€šçŸ¥ç¶è·è€…已在修補程åºä¸Šå®Œæˆçš„審閱程度。 -Reviewed-by: 當由已知了解主題å€åŸŸä¸¦åŸ·è¡Œå¾¹åº•æª¢æŸ¥çš„審閱者æä¾›æ™‚ï¼Œé€šå¸¸æœƒå¢žåŠ +Reviewed-by是一種觀點è²æ˜Žï¼Œå³è£œä¸æ˜¯å°å…§æ ¸çš„é©ç•¶ä¿®æ”¹ï¼Œæ²’有任何éºç•™çš„åš´é‡æŠ€è¡“ +å•é¡Œã€‚任何感興趣的審閱者（完æˆå·¥ä½œçš„人）都å¯ä»¥çˆ²ä¸€å€‹è£œä¸æ供一個Reviewed-by +標籤。æ¤æ¨™ç±¤ç”¨æ–¼å‘審閱者æ供致è¬ï¼Œä¸¦é€šçŸ¥ç¶è·è€…補ä¸çš„審閱進度。 +當Reviewed-by:標籤由已知了解主題å€åŸŸä¸¦åŸ·è¡Œå¾¹åº•æª¢æŸ¥çš„審閱者æä¾›æ™‚ï¼Œé€šå¸¸æœƒå¢žåŠ è£œä¸é€²å…¥å…§æ ¸çš„å¯èƒ½æ€§ã€‚ +一旦從測試人員或審閱者的“Tested-byâ€å’Œâ€œReviewed-byâ€æ¨™ç±¤å‡ºç¾åœ¨éƒµä»¶åˆ—表ä¸ï¼Œ +作者應在發é€ä¸‹ä¸€å€‹ç‰ˆæœ¬æ™‚å°‡å…¶æ·»åŠ åˆ°é©ç”¨çš„補ä¸ä¸ã€‚但是，如果補ä¸åœ¨ä»¥ä¸‹ç‰ˆæœ¬ä¸ç™¼ +生了實質性更改，這些標籤å¯èƒ½ä¸å†é©ç”¨ï¼Œå› æ¤æ‡‰è©²åˆªé™¤ã€‚通常，在補ä¸æ›´æ”¹æ—¥èªŒä¸ +（在 ``---`` 分隔符之後）應該æ到刪除æŸäººçš„測試者或審閱者標籤。 + Suggested-by: 表示補ä¸çš„想法是由指定的人æ出的，並確ä¿å°‡æ¤æƒ³æ³•æ¸åŠŸæ–¼æŒ‡å®šçš„ -人。請注æ„，未經許å¯ï¼Œä¸å¾—æ·»åŠ æ¤æ¨™ç±¤ï¼Œç‰¹åˆ¥æ˜¯å¦‚果該想法未在公共論壇上發布。 -這就是說，如果我們勤快地致è¬æˆ‘們的創æ„者，他們很有希望在未來得到鼓舞，å†æ¬¡ +人。請注æ„，未經許å¯ï¼Œä¸å¾—æ·»åŠ æ¤æ¨™ç±¤ï¼Œç‰¹åˆ¥æ˜¯å¦‚果該想法未在公共論壇上發佈。 +也就是說，如果我們勤快地致è¬å‰µæ„æ供者，他們將å—到鼓舞，很有希望在未來å†æ¬¡ 幫助我們。 -Fixes: 指示補ä¸åœ¨ä»¥å‰çš„æ交ä¸ä¿®å¾©äº†ä¸€å€‹å•é¡Œã€‚它å¯ä»¥å¾ˆå®¹æ˜“地確定錯誤的來æºï¼Œ -é€™æœ‰åŠ©æ–¼æª¢æŸ¥éŒ¯èª¤ä¿®å¾©ã€‚é€™å€‹æ¨™è¨˜é‚„å¹«åŠ©ç©©å®šå…§æ ¸åœ˜éšŠç¢ºå®šæ‡‰è©²æŽ¥æ”¶ä¿®å¾©çš„ç©©å®šå…§æ ¸ -版本。這是指示補ä¸ä¿®å¾©çš„錯誤的首é¸æ–¹æ³•ã€‚è«‹åƒé–± :ref:`tw_describe_changes` -æ述您的更改以了解更多詳細信æ¯ã€‚ +Fixes: 指示補ä¸ä¿®å¾©äº†ä¹‹å‰æ交的一個å•é¡Œã€‚它å¯ä»¥ä¾¿æ–¼ç¢ºå®šéŒ¯èª¤çš„來æºï¼Œé€™æœ‰åŠ©æ–¼ +æª¢æŸ¥éŒ¯èª¤ä¿®å¾©ã€‚é€™å€‹æ¨™ç±¤é‚„å¹«åŠ©ç©©å®šå…§æ ¸åœ˜éšŠç¢ºå®šæ‡‰è©²æŽ¥æ”¶ä¿®å¾©çš„ç©©å®šå…§æ ¸ç‰ˆæœ¬ã€‚é€™æ˜¯ +指示補ä¸ä¿®å¾©çš„錯誤的首é¸æ–¹æ³•ã€‚è«‹åƒé–± :ref:`zh_describe_changes` çžè§£æ›´å¤šä¿¡æ¯ã€‚ + +.. note:: + + é™„åŠ Fixes:標籤ä¸æœƒæ”¹è®Šç©©å®šå…§æ ¸è¦å‰‡æµç¨‹ï¼Œä¹Ÿä¸æ”¹è®Šæ‰€æœ‰ç©©å®šç‰ˆè£œä¸æŠ„é€ + stable@vger.kernel.orgçš„è¦æ±‚。有關更多信æ¯ï¼Œè«‹é–±è®€ + Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 .. _tw_the_canonical_patch_format: -12）標準補ä¸æ ¼å¼ ----------------- +標準補ä¸æ ¼å¼ +------------ 本節æè¿°å¦‚ä½•æ ¼å¼åŒ–補ä¸æœ¬èº«ã€‚請注æ„，如果您的補ä¸å˜å„²åœ¨ ``Git`` å˜å„²åº«ä¸ï¼Œå‰‡ -å¯ä»¥ä½¿ç”¨ ``git format-patch`` 進行æ£ç¢ºçš„補ä¸æ ¼å¼è¨ç½®ã€‚但是，這些工具無法創建 +å¯ä»¥ä½¿ç”¨ ``git format-patch`` 進行æ£ç¢ºçš„補ä¸æ ¼å¼åŒ–。但是，這些工具無法創建 å¿…è¦çš„æ–‡æœ¬ï¼Œå› æ¤è«‹å‹™å¿…閱讀下é¢çš„說明。 -標準的補ä¸ï¼Œæ¨™é¡Œè¡Œæ˜¯:: +標準的補ä¸æ¨™é¡Œè¡Œæ˜¯:: Subject: [PATCH 001/123] å系統:一å¥è©±æ¦‚è¿° -標準補ä¸çš„ä¿¡é«”å˜åœ¨å¦‚下部分： +標準補ä¸çš„信體包å«å¦‚下部分： - - 一個 "from" 行指出補ä¸ä½œè€…。後跟空行（僅當發é€ä¿®è£œç¨‹åºçš„人ä¸æ˜¯ä½œè€…時æ‰éœ€è¦ï¼‰ã€‚ + - 一個 ``from`` 行指出補ä¸ä½œè€…。後跟空行（僅當發é€è£œä¸çš„人ä¸æ˜¯ä½œè€…時æ‰éœ€è¦ï¼‰ã€‚ - - 解釋的æ£æ–‡ï¼Œè¡Œä»¥75列包è£ï¼Œé€™å°‡è¢«è¤‡è£½åˆ°æ°¸ä¹…變更日誌來æ述這個補ä¸ã€‚ + - 說明文å—，æ¯è¡Œæœ€é•·75列，這將被複制到永久變更日誌來æ述這個補ä¸ã€‚ - 一個空行 - - 上é¢æ述的「Signed-off-by〠行，也將出ç¾åœ¨æ›´æ”¹æ—¥èªŒä¸ã€‚ + - 上述的 ``Signed-off-by:`` 行，也將出ç¾åœ¨æ›´æ”¹æ—¥èªŒä¸ã€‚ - åªåŒ…å« ``---`` 的標記線。 - - 任何其他ä¸é©åˆæ”¾åœ¨è®Šæ›´æ—¥èªŒçš„注釋。 + - 任何其他ä¸é©åˆæ”¾åœ¨è®Šæ›´æ—¥èªŒçš„註釋。 - 實際補ä¸ï¼ˆ ``diff`` 輸出）。 -æ¨™é¡Œè¡Œçš„æ ¼å¼ï¼Œä½¿å¾—å°æ¨™é¡Œè¡ŒæŒ‰å—æ¯åºæŽ’åºéžå¸¸çš„容易 - 很多 e-mail 客戶端都 -å¯ä»¥æ”¯æŒ - å› çˆ²åºåˆ—號是用零填充的，所以按數å—排åºå’ŒæŒ‰å—æ¯æŽ’åºæ˜¯ä¸€æ¨£çš„。 +æ¨™é¡Œè¡Œçš„æ ¼å¼ï¼Œä½¿å¾—å°æ¨™é¡Œè¡ŒæŒ‰å—æ¯åºæŽ’åºéžå¸¸çš„容易——很多郵件客戶端都 +å¯ä»¥æ”¯æŒâ€”â€”å› çˆ²åºåˆ—號是用零填充的，所以按數å—排åºå’ŒæŒ‰å—æ¯æŽ’åºæ˜¯ä¸€æ¨£çš„。 -e-mail 標題ä¸çš„「å系統ã€æ¨™è˜å“ªå€‹å…§æ ¸å系統將被打補ä¸ã€‚ +郵件標題ä¸çš„“å系統â€æ¨™è˜å“ªå€‹å…§æ ¸å系統將被打補ä¸ã€‚ -e-mail 標題ä¸çš„「一å¥è©±æ¦‚è¿°ã€æ‰¼è¦çš„æè¿° e-mail ä¸çš„補ä¸ã€‚「一å¥è©±æ¦‚述〠-ä¸æ‡‰è©²æ˜¯ä¸€å€‹æ–‡ä»¶å。å°æ–¼ä¸€å€‹è£œä¸ç³»åˆ—（「補ä¸ç³»åˆ—ã€æŒ‡ä¸€ç³»åˆ—的多個相關補 -ä¸ï¼‰ï¼Œä¸è¦å°æ¯å€‹è£œä¸éƒ½ä½¿ç”¨åŒæ¨£çš„「一å¥è©±æ¦‚è¿°ã€ã€‚ +郵件標題ä¸çš„“一å¥è©±æ¦‚è¿°â€æ‰¼è¦çš„æ述郵件ä¸çš„補ä¸ã€‚“一å¥è©±æ¦‚述†+ä¸æ‡‰è©²æ˜¯ä¸€å€‹æ–‡ä»¶å。å°æ–¼ä¸€å€‹è£œä¸ç³»åˆ—（“補ä¸ç³»åˆ—â€æŒ‡ä¸€ç³»åˆ—的多個相關補 +ä¸ï¼‰ï¼Œä¸è¦å°æ¯å€‹è£œä¸éƒ½ä½¿ç”¨åŒæ¨£çš„“一å¥è©±æ¦‚è¿°â€ã€‚ -è¨˜ä½ e-mail 的「一å¥è©±æ¦‚è¿°ã€æœƒæˆçˆ²è©²è£œä¸çš„全局唯一標è˜ã€‚它會蔓延到 git -的改動記錄里。然後「一å¥è©±æ¦‚è¿°ã€æœƒè¢«ç”¨åœ¨é–‹ç™¼è€…的討論里，用來指代這個補 -ä¸ã€‚ç”¨æˆ¶å°‡å¸Œæœ›é€šéŽ google 來æœç´¢"一å¥è©±æ¦‚è¿°"來找到那些討論這個補ä¸çš„æ–‡ +記ä½éƒµä»¶çš„“一å¥è©±æ¦‚è¿°â€æœƒæˆçˆ²è©²è£œä¸çš„全局唯一標è˜ã€‚它會進入 ``git`` +的改動記錄è£ã€‚然後“一å¥è©±æ¦‚è¿°â€æœƒè¢«ç”¨åœ¨é–‹ç™¼è€…的討論è£ï¼Œç”¨ä¾†æŒ‡ä»£é€™å€‹è£œ +ä¸ã€‚用戶將希望通éŽæœç´¢å¼•æ“Žæœç´¢â€œä¸€å¥è©±æ¦‚è¿°â€ä¾†æ‰¾åˆ°é‚£äº›è¨Žè«–這個補ä¸çš„æ–‡ ç« ã€‚ç•¶äººå€‘åœ¨å…©ä¸‰å€‹æœˆå¾Œä½¿ç”¨è«¸å¦‚ ``gitk`` 或 ``git log --oneline`` 之類 的工具查看數åƒå€‹è£œä¸æ™‚，也會很快看到它。 å‡ºæ–¼é€™äº›åŽŸå› ï¼Œæ¦‚è¿°å¿…é ˆä¸è¶…éŽ70-75個å—ç¬¦ï¼Œä¸¦ä¸”å¿…é ˆæ述補ä¸çš„更改以åŠçˆ² -什麼需è¦è£œä¸ã€‚æ—¢è¦ç°¡æ½”åˆè¦æ述性很有挑戰性，但寫得好的概述應該這樣åšã€‚ +什麼需è¦è£œä¸ã€‚æ—¢è¦ç°¡æ½”åˆè¦æ述性很有挑戰性，但寫得好的概述應該這樣。 -概述的å‰ç¶´å¯ä»¥ç”¨æ–¹æ‹¬è™Ÿæ‹¬èµ·ä¾†ï¼šã€ŒSubject: [PATCH <tag>...] <概述>ã€ã€‚標記 +概述的å‰ç¶´å¯ä»¥ç”¨æ–¹æ‹¬è™Ÿæ‹¬èµ·ä¾†ï¼šâ€œSubject: [PATCH <tag>...] <概述>â€ã€‚標記 ä¸è¢«è¦–爲概述的一部分，而是æ述應該如何處ç†è£œä¸ã€‚如果補ä¸çš„多個版本已發 -é€å‡ºä¾†ä»¥éŸ¿æ‡‰è©•å¯©ï¼ˆå³ã€Œv1，v2，v3ã€ï¼‰æˆ–「rfcã€ï¼Œä»¥æŒ‡ç¤ºè©•å¯©è«‹æ±‚，那麼通用標記 -å¯èƒ½åŒ…括版本æ述符。如果一個補ä¸ç³»åˆ—ä¸æœ‰å››å€‹è£œä¸ï¼Œé‚£éº¼å„個補ä¸å¯ä»¥é€™æ¨£ -編號：1/4ã€2/4ã€3/4ã€4/4。這å¯ä»¥ç¢ºä¿é–‹ç™¼äººå“¡äº†è§£è£œä¸æ‡‰ç”¨çš„é †åºï¼Œä¸¦ä¸”他們 +é€å‡ºä¾†ä»¥éŸ¿æ‡‰è©•å¯©ï¼ˆå³â€œv1，v2，v3â€ï¼‰å‰‡å¿…é ˆåŒ…å«ç‰ˆæœ¬è™Ÿï¼Œæˆ–包å«â€œRFCâ€ä»¥æŒ‡ç¤º +評審請求。如果一個補ä¸ç³»åˆ—ä¸æœ‰å››å€‹è£œä¸ï¼Œé‚£éº¼å„個補ä¸å¯ä»¥é€™æ¨£ç·¨è™Ÿï¼š1/4ã€2/4〠+3/4ã€4/4。這å¯ä»¥ç¢ºä¿é–‹ç™¼äººå“¡çžè§£è£œä¸æ‡‰ç”¨çš„é †åºï¼Œä¸” 已經查看或應用了補ä¸ç³»åˆ—ä¸çš„所有補ä¸ã€‚ 一些標題的例å:: @@ -543,95 +504,134 @@ e-mail 標題ä¸çš„「一å¥è©±æ¦‚è¿°ã€æ‰¼è¦çš„æè¿° e-mail ä¸çš„補ä¸ã€‚〠Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking -"From" 行是信體裡的最上é¢ä¸€è¡Œï¼Œå…·æœ‰å¦‚ä¸‹æ ¼å¼ï¼š +``From`` 行是信體è£çš„最上é¢ä¸€è¡Œï¼Œå…·æœ‰å¦‚ä¸‹æ ¼å¼:: + From: Patch Author <author@example.com> -"From" 行指明在永久改動日誌里，誰會被確èªçˆ²ä½œè€…。如果沒有 "From" 行，那 -麼郵件é 裡的 "From: " 行會被用來決定改動日誌ä¸çš„作者。 +``From`` 行指明在永久改動日誌è£ï¼Œèª°æœƒè¢«ç¢ºèªçˆ²ä½œè€…。如果沒有 ``From`` 行，那 +麼郵件é è£çš„ ``From:`` 行會被用來決定改動日誌ä¸çš„作者。 -說明的主題將會被æäº¤åˆ°æ°¸ä¹…çš„åŽŸå§‹ç¢¼æ”¹å‹•æ—¥èªŒé‡Œï¼Œå› æ¤å°é‚£äº›æ—©å·²ç¶“ä¸è¨˜å¾—å’Œ -這個補ä¸ç›¸é—œçš„討論細節的有能力的讀者來說，是有æ„義的。包括補ä¸ç¨‹åºå®šä½ -éŒ¯èª¤çš„ï¼ˆå…§æ ¸æ—¥èªŒæ¶ˆæ¯ã€OOPS消æ¯ç‰ï¼‰ç—‡ç‹€ï¼Œå°æ–¼æœç´¢æ交日誌以尋找é©ç”¨è£œä¸çš„人 -尤其有用。如果一個補ä¸ä¿®å¾©äº†ä¸€å€‹ç·¨è¯å¤±æ•—，那麼å¯èƒ½ä¸éœ€è¦åŒ…å«æ‰€æœ‰ç·¨è¯å¤±æ•—ï¼› +說明文å—將會被æ交到永久的æºä»£ç¢¼æ”¹å‹•æ—¥èªŒè£ï¼Œå› æ¤æ‡‰é‡å°é‚£äº›æ—©å·²ç¶“ä¸è¨˜å¾—和這 +個補ä¸ç›¸é—œçš„討論細節的讀者。包括補ä¸è™•ç†çš„æ•…éšœç—‡ç‹€ï¼ˆå…§æ ¸æ—¥èªŒæ¶ˆæ¯ã€oopsæ¶ˆæ¯ +ç‰ï¼‰ï¼Œé€™å°æ–¼å¯èƒ½æ£åœ¨æœç´¢æ交日誌以查找é©ç”¨è£œä¸çš„人特別有用。文本應該寫得如 +æ¤è©³ç´°ï¼Œä»¥ä¾¿åœ¨æ•¸é€±ã€æ•¸æœˆç”šè‡³æ•¸å¹´å¾Œé–±è®€æ™‚ï¼Œèƒ½å¤ çˆ²è®€è€…æ供所需的細節信æ¯ï¼Œä»¥ +掌æ¡å‰µå»ºè£œä¸çš„ **åŽŸå› ** 。 + +如果一個補ä¸ä¿®å¾©äº†ä¸€å€‹ç·¨è¯å¤±æ•—，那麼å¯èƒ½ä¸éœ€è¦åŒ…å« *所有* ç·¨è¯å¤±æ•—ï¼› åªè¦è¶³å¤ 讓æœç´¢è£œä¸çš„äººèƒ½å¤ æ‰¾åˆ°å®ƒå°±è¡Œäº†ã€‚èˆ‡æ¦‚è¿°ä¸€æ¨£ï¼Œæ—¢è¦ç°¡æ½”åˆè¦æ述性。 -"---" 標記行å°æ–¼è£œä¸è™•ç†å·¥å…·è¦æ‰¾åˆ°å“ªè£¡æ˜¯æ”¹å‹•æ—¥èªŒä¿¡æ¯çš„çµæŸï¼Œæ˜¯ä¸å¯ç¼ºå°‘ +``---`` 標記行å°æ–¼è£œä¸è™•ç†å·¥å…·è¦æ‰¾åˆ°å“ªè£æ˜¯æ”¹å‹•æ—¥èªŒä¿¡æ¯çš„çµæŸï¼Œæ˜¯ä¸å¯ç¼ºå°‘ 的。 -å°æ–¼ "---" 標記之後的é¡å¤–註解，一個好的用途就是用來寫 diffstat，用來顯 -示修改了什麼文件和æ¯å€‹æ–‡ä»¶éƒ½å¢žåŠ 和刪除了多少行。diffstat å°æ–¼æ¯”較大的補 -ä¸ç‰¹åˆ¥æœ‰ç”¨ã€‚其餘那些åªæ˜¯å’Œæ™‚刻或者開發者相關的註解，ä¸åˆé©æ”¾åˆ°æ°¸ä¹…的改 -動日誌里的，也應該放這裡。 -使用 diffstatçš„é¸é … "-p 1 -w 70" 這樣文件åå°±æœƒå¾žå…§æ ¸åŽŸå§‹ç¢¼æ¨¹çš„ç›®éŒ„é–‹å§‹ -，ä¸æœƒå 用太寬的空間（很容易é©åˆ80列的寬度，也許會有一些縮進。） +å°æ–¼ ``---`` 標記之後的é¡å¤–註解，一個好的用途就是用來寫 ``diffstat`` ，用來顯 +示修改了什麼文件和æ¯å€‹æ–‡ä»¶éƒ½å¢žåŠ 和刪除了多少行。 ``diffstat`` å°æ–¼æ¯”較大的補 +ä¸ç‰¹åˆ¥æœ‰ç”¨ã€‚ +使用 ``diffstat`` çš„é¸é … ``-p 1 -w 70`` 這樣文件åå°±æœƒå¾žå…§æ ¸æºä»£ç¢¼æ¨¹çš„目錄開始 +，ä¸æœƒä½”用太寬的空間（很容易é©åˆ80列的寬度，也許會有一些縮進。） +（ ``git`` 默èªæœƒç”Ÿæˆåˆé©çš„diffstat。） -在後é¢çš„åƒè€ƒè³‡æ–™ä¸èƒ½çœ‹åˆ°é©ç•¶çš„補ä¸æ ¼å¼çš„更多細節。 +其餘那些åªé©ç”¨æ–¼ç•¶æ™‚或者與ç¶è·è€…相關的註解，ä¸åˆé©æ”¾åˆ°æ°¸ä¹…的改動日誌è£çš„，也 +應該放這è£ã€‚較好的例å就是 ``補ä¸æ›´æ”¹è¨˜éŒ„`` ，記錄了v1å’Œv2版本補ä¸ä¹‹é–“的差異。 -.. _tw_explicit_in_reply_to: +è«‹å°‡æ¤ä¿¡æ¯æ”¾åœ¨å°‡è®Šæ›´æ—¥èªŒèˆ‡è£œä¸çš„其餘部分分隔開的 ``---`` è¡Œ **之後** 。版本 +ä¿¡æ¯ä¸æ˜¯æ交到git樹的變更日誌的一部分。åªæ˜¯ä¾›å¯©é–±äººå“¡ä½¿ç”¨çš„é™„åŠ ä¿¡æ¯ã€‚如果將 +其放置在æ交標記上方，則需è¦æ‰‹å‹•äº¤äº’æ‰èƒ½å°‡å…¶åˆªé™¤ã€‚如果它ä½æ–¼åˆ†éš”線以下，則在 +應用補ä¸æ™‚會自動å‰é›¢:: -15) 明確回覆郵件é (In-Reply-To) -------------------------------- + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments -æ‰‹å‹•æ·»åŠ å›žå¾©è£œä¸çš„的標題é (In-Reply_To:) 是有幫助的（例如，使用 ``git send-email`` ） -將補ä¸èˆ‡ä»¥å‰çš„相關討論關è¯èµ·ä¾†ï¼Œä¾‹å¦‚，將bug修復程åºé€£çµåˆ°é›»å郵件和bugå ±å‘Šã€‚ -但是，å°æ–¼å¤šè£œä¸ç³»åˆ—，最好é¿å…在回復時使用連çµåˆ°è©²ç³»åˆ—的舊版本。這樣， -補ä¸çš„多個版本就ä¸æœƒæˆçˆ²é›»å郵件客戶端ä¸ç„¡æ³•ç®¡ç†çš„引用åºåˆ—。如果連çµæœ‰ç”¨ï¼Œ -å¯ä»¥ä½¿ç”¨ https://lore.kernel.org/ é‡å®šå‘器（例如，在å°é¢é›»å郵件文本ä¸ï¼‰ -連çµåˆ°è£œä¸ç³»åˆ—的早期版本。 + path/to/file | 5+++-- + ... + +在後é¢çš„åƒè€ƒè³‡æ–™ä¸èƒ½çœ‹åˆ°æ£ç¢ºè£œä¸æ ¼å¼çš„更多細節。 -16) 發é€git pull請求 --------------------- +.. _tw_backtraces: -如果您有一系列補ä¸ï¼Œé‚£éº¼è®“ç¶è·äººå“¡é€šéŽgit pullæ“作將它們直接拉入å系統å˜å„² -庫å¯èƒ½æ˜¯æœ€æ–¹ä¾¿çš„。但是，請注æ„，從開發人員那裡ç²å–補ä¸æ¯”從郵件列表ä¸ç²å–補 -ä¸éœ€è¦æ›´é«˜çš„ä¿¡ä»»åº¦ã€‚å› æ¤ï¼Œè¨±å¤šå系統ç¶è·äººå“¡ä¸é¡˜æ„接å—請求，特別是來自新的 -未知開發人員的請求。如果有疑å•ï¼Œæ‚¨å¯ä»¥åœ¨å°é¢éƒµä»¶ä¸ä½¿ç”¨pull 請求作爲補ä¸ç³»åˆ— -æ£å¸¸ç™¼å¸ƒçš„一個é¸é …，讓ç¶è·äººå“¡å¯ä»¥é¸æ“‡ä½¿ç”¨å…¶ä¸ä¹‹ä¸€ã€‚ +æ交消æ¯ä¸çš„回溯（Backtraces） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +回溯有助於記錄導致å•é¡Œçš„調用éˆã€‚然而，並éžæ‰€æœ‰å›žæº¯éƒ½æœ‰å¹«åŠ©ã€‚例如，早期引導調 +用éˆæ˜¯ç¨ç‰¹è€Œæ˜Žé¡¯çš„。而é€å—複製完整的dmesgè¼¸å‡ºå‰‡æœƒå¢žåŠ æ™‚é–“æˆ³ã€æ¨¡å¡Šåˆ—表ã€å¯„å˜ +å™¨å’Œå †æ£§è½‰å„²ç‰åˆ†æ•£æ³¨æ„力的信æ¯ã€‚ + +å› æ¤ï¼Œæœ€æœ‰ç”¨çš„回溯應該從轉儲ä¸æå–相關信æ¯ï¼Œä»¥æ›´å®¹æ˜“集ä¸åœ¨çœŸå¯¦å•é¡Œä¸Šã€‚下é¢æ˜¯ +一個剪è£è‰¯å¥½çš„回溯示例:: + + 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 + +.. _tw_explicit_in_reply_to: + +明確回覆郵件é （In-Reply-To） +----------------------------- + +æ‰‹å‹•æ·»åŠ å›žå¾©è£œä¸çš„的郵件é （In-Reply_To:）是有用的（例如，使用 ``git send-email`` ）， +å¯ä»¥å°‡è£œä¸èˆ‡ä»¥å‰çš„相關討論關è¯èµ·ä¾†ï¼Œä¾‹å¦‚，將bug補ä¸éˆæŽ¥åˆ°é›»å郵件和bugå ±å‘Šã€‚ +但是，å°æ–¼å¤šè£œä¸ç³»åˆ—，最好é¿å…在回覆時使用éˆæŽ¥åˆ°è©²ç³»åˆ—的舊版本。這樣， +補ä¸çš„多個版本就ä¸æœƒæˆçˆ²é›»å郵件客戶端ä¸ç„¡æ³•ç®¡ç†çš„引用樹。如果éˆæŽ¥æœ‰ç”¨ï¼Œ +å¯ä»¥ä½¿ç”¨ https://lore.kernel.org/ é‡å®šå‘器（例如，在å°é¢é›»å郵件文本ä¸ï¼‰ +éˆæŽ¥åˆ°è£œä¸ç³»åˆ—的早期版本。 -pull 請求的主題行ä¸æ‡‰è©²æœ‰[Git Pull]。請求本身應該在一行ä¸åŒ…å«å˜å„²åº«å稱和 -感興趣的分支；它應該看起來åƒ:: +çµ¦å‡ºåŸºç¤Žæ¨¹ä¿¡æ¯ +-------------- - Please pull from +當其他開發人員收到您的補ä¸ä¸¦é–‹å§‹å¯©é–±æ™‚，知é“應該將您的工作放到代碼樹æ·å²è¨˜éŒ„ +ä¸çš„什麼ä½ç½®é€šå¸¸å¾ˆæœ‰ç”¨ã€‚這å°æ–¼è‡ªå‹•åŒ–æŒçºŒé›†æˆæµæ°´ï¼ˆCI）特別有用，這些æµæ°´ç·šè©¦ +圖é‹è¡Œä¸€ç³»åˆ—測試，以便在ç¶è·äººå“¡é–‹å§‹å¯©é–±ä¹‹å‰ç¢ºå®šæ交的質é‡ã€‚ - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus +如果您使用 ``git format-patch`` 生æˆè£œä¸ï¼Œå‰‡å¯ä»¥é€šéŽ ``--base`` 標誌在æäº¤ä¸ +自動包å«åŸºç¤Žæ¨¹ä¿¡æ¯ã€‚使用æ¤é¸é …最簡單ã€æœ€æ–¹ä¾¿çš„方法是é…åˆä¸»é¡Œåˆ†æ”¯:: - to get these changes: + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + [perform your edits and commits] -pull 請求還應該包å«ä¸€æ¢æ•´é«”消æ¯ï¼Œèªªæ˜Žè«‹æ±‚ä¸å°‡åŒ…å«ä»€éº¼ï¼Œä¸€å€‹è£œä¸æœ¬èº«çš„ ``Git shortlog`` -以åŠä¸€å€‹é¡¯ç¤ºè£œä¸ç³»åˆ—整體效果的 ``diffstat`` 。當然，將所有這些信æ¯æ”¶é›†åœ¨ä¸€èµ· -的最簡單方法是讓 ``git`` 使用 ``git request-pull`` 命令爲您完æˆé€™äº›å·¥ä½œã€‚ + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... -一些ç¶è·äººå“¡ï¼ˆåŒ…括Linus）希望看到來自已簽åæäº¤çš„è«‹æ±‚ï¼›é€™å¢žåŠ äº†ä»–å€‘å°ä½ çš„ -請求信心。特別是，在沒有簽å標籤的情æ³ä¸‹ï¼ŒLinus ä¸æœƒå¾žåƒ Github 這樣的公共 -託管站點拉請求。 +ç•¶ä½ ç·¨è¼¯ ``outgoing/0000-cover-letter.patch`` 時，您會注æ„到在它的最底部有一 +è¡Œ ``base-commit:`` 尾註，它爲審閱者和CI工具æä¾›äº†è¶³å¤ çš„ä¿¡æ¯ä»¥æ£ç¢ºåŸ·è¡Œ +``git am`` 而ä¸å¿…擔心è¡çª:: -創建æ¤é¡žç°½å的第一æ¥æ˜¯ç”Ÿæˆä¸€å€‹ GNRPG å¯†é‘°ï¼Œä¸¦ç”±ä¸€å€‹æˆ–å¤šå€‹æ ¸å¿ƒå…§æ ¸é–‹ç™¼äººå“¡å° -其進行簽å。這一æ¥å°æ–°é–‹ç™¼äººå“¡ä¾†èªªå¯èƒ½å¾ˆå›°é›£ï¼Œä½†æ²’有辦法繞éŽå®ƒã€‚åƒåŠ 會è°æ˜¯ -找到å¯ä»¥ç°½ç½²æ‚¨çš„密鑰的開發人員的好方法。 + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... -一旦您在Git ä¸æº–備了一個您希望有人拉的補ä¸ç³»åˆ—，就用 ``git tag -s`` 創建一 -個簽å標記。這將創建一個新標記，標è˜è©²ç³»åˆ—ä¸çš„最後一次æ交，並包å«ç”¨æ‚¨çš„ç§ -鑰創建的簽å。您還å¯ä»¥å°‡changelog樣å¼çš„消æ¯æ·»åŠ 到標記ä¸ï¼›é€™æ˜¯ä¸€å€‹æ述拉請求 -整體效果的ç†æƒ³ä½ç½®ã€‚ +有關æ¤é¸é …的更多信æ¯ï¼Œè«‹åƒé–± ``man git-format-patch`` 。 -如果ç¶è·äººå“¡å°‡è¦å¾žä¸æå–的樹ä¸æ˜¯æ‚¨æ£åœ¨ä½¿ç”¨çš„å˜å„²åº«ï¼Œè«‹ä¸è¦å¿˜è¨˜å°‡å·²ç°½å的標記 -顯å¼æŽ¨é€åˆ°å…¬å…±æ¨¹ã€‚ +.. note:: -生æˆæ‹‰è«‹æ±‚時，請使用已簽å的標記作爲目標。這樣的命令å¯ä»¥å¯¦ç¾:: + ``--base`` 功能是在2.9.0版gitä¸å¼•å…¥çš„。 - git request-pull master git://my.public.tree/linux.git my-signed-tag +如果您ä¸ä½¿ç”¨gitæ ¼å¼åŒ–補ä¸ï¼Œä»ç„¶å¯ä»¥åŒ…å«ç›¸åŒçš„ ``base-commit`` 尾註，以指示您 +的工作所基於的樹的æäº¤å“ˆå¸Œã€‚ä½ æ‡‰è©²åœ¨å°é¢éƒµä»¶æˆ–系列的第一個補ä¸ä¸æ·»åŠ 它，它應 +該放在 ``---`` 行的下é¢æˆ–所有其他內容之後，å³åªåœ¨ä½ çš„é›»å郵件簽å之å‰ã€‚ åƒè€ƒæ–‡ç» -------- -Andrew Morton, "The perfect patch" (tpp). +Andrew Morton，“完美的補ä¸â€ï¼ˆtpp） <https://www.ozlabs.org/~akpm/stuff/tpp.txt> -Jeff Garzik, "Linux kernel patch submission format". +Jeff Garzik，“Linuxå…§æ ¸è£œä¸æäº¤æ ¼å¼â€ <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". +Greg Kroah-Hartmanï¼Œâ€œå¦‚ä½•æƒ¹æƒ±å…§æ ¸å系統ç¶è·äººå“¡â€ <http://www.kroah.com/log/linux/maintainer.html> <http://www.kroah.com/log/linux/maintainer-02.html> @@ -644,17 +644,16 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer-06.html> -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! +ä¸ï¼ï¼ï¼åˆ¥å†ç™¼å·¨åž‹è£œä¸ç‚¸å½ˆçµ¦linux-kernel@vger.kernel.orgçš„äººå€‘äº†ï¼ <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> -Kernel Documentation/process/coding-style.rst: - :ref:`Documentation/translations/zh_TW/process/coding-style.rst <tw_codingstyle>` +å…§æ ¸ Documentation/translations/zh_CN/process/coding-style.rst -Linus Torvalds's mail on the canonical patch format: +Linus Torvalds關於標準補ä¸æ ¼å¼çš„郵件 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. +Andi Kleen，“æ交補ä¸ä¹‹è·¯â€ + 一些幫助åˆå…¥å›°é›£æˆ–有çˆè°çš„變更的ç–略。 http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst index 469cb5b3a07c..a609620affb0 100644 --- a/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst +++ b/Documentation/translations/zh_TW/process/volatile-considered-harmful.rst @@ -19,20 +19,20 @@ 時奎亮 Alex Shi <alex.shi@linux.alibaba.com> 胡皓文 Hu Haowen <src.res.211@gmail.com> -爲什麼ä¸æ‡‰è©²ä½¿ç”¨ã€Œvolatileã€é¡žåž‹ -================================ +爲什麼ä¸æ‡‰è©²ä½¿ç”¨â€œvolatileâ€é¡žåž‹ +============================== -C程å¼è¨è¨ˆå¸«é€šå¸¸èªçˆ²volatile表示æŸå€‹è®Šé‡å¯ä»¥åœ¨ç•¶å‰åŸ·è¡Œçš„ç·šç¨‹ä¹‹å¤–è¢«æ”¹è®Šï¼›å› æ¤ï¼Œåœ¨å…§æ ¸ -ä¸ç”¨åˆ°å…±äº«æ•¸æ“šçµæ§‹æ™‚，常常會有C程å¼è¨è¨ˆå¸«å–œæ¡ä½¿ç”¨volatile這類變é‡ã€‚æ›å¥è©±èªªï¼Œä»–們經 +C程åºå“¡é€šå¸¸èªçˆ²volatile表示æŸå€‹è®Šé‡å¯ä»¥åœ¨ç•¶å‰åŸ·è¡Œçš„ç·šç¨‹ä¹‹å¤–è¢«æ”¹è®Šï¼›å› æ¤ï¼Œåœ¨å…§æ ¸ +ä¸ç”¨åˆ°å…±äº«æ•¸æ“šçµæ§‹æ™‚，常常會有C程åºå“¡å–œæ¡ä½¿ç”¨volatile這類變é‡ã€‚æ›å¥è©±èªªï¼Œä»–們經 常會把volatile類型看æˆæŸç¨®ç°¡æ˜“的原å變é‡ï¼Œç•¶ç„¶å®ƒå€‘ä¸æ˜¯ã€‚åœ¨å…§æ ¸ä¸ä½¿ç”¨volatileå¹¾ 乎總是錯誤的；本文檔將解釋爲什麼這樣。 ç†è§£volatileçš„é—œéµæ˜¯çŸ¥é“它的目的是用來消除優化，實際上很少有人真æ£éœ€è¦é€™æ¨£çš„應 -ç”¨ã€‚åœ¨å…§æ ¸ä¸ï¼Œç¨‹å¼è¨è¨ˆå¸«å¿…é ˆé˜²æ¢æ„外的並發訪å•ç ´å£žå…±äº«çš„數據çµæ§‹ï¼Œé€™å…¶å¯¦æ˜¯ä¸€å€‹å®Œå…¨ -ä¸åŒçš„任務。用來防æ¢æ„外並發訪å•çš„ä¿è·æŽªæ–½ï¼Œå¯ä»¥æ›´åŠ 高效的é¿å…大多數優化相關的 +ç”¨ã€‚åœ¨å…§æ ¸ä¸ï¼Œç¨‹åºå“¡å¿…é ˆé˜²æ¢æ„外的併發訪å•ç ´å£žå…±äº«çš„數據çµæ§‹ï¼Œé€™å…¶å¯¦æ˜¯ä¸€å€‹å®Œå…¨ +ä¸åŒçš„任務。用來防æ¢æ„外併發訪å•çš„ä¿è·æŽªæ–½ï¼Œå¯ä»¥æ›´åŠ 高效的é¿å…大多數優化相關的 å•é¡Œã€‚ -åƒvolatileä¸€æ¨£ï¼Œå…§æ ¸æ供了很多原語來ä¿è‰ä¸¦ç™¼è¨ªå•æ™‚的數據安全（自旋鎖, 互斥é‡,å…§ +åƒvolatileä¸€æ¨£ï¼Œå…§æ ¸æ供了很多原語來ä¿è‰ä½µç™¼è¨ªå•æ™‚的數據安全（自旋鎖, 互斥é‡,å…§ å˜å±éšœç‰ç‰ï¼‰ï¼ŒåŒæ¨£å¯ä»¥é˜²æ¢æ„外的優化。如果å¯ä»¥æ£ç¢ºä½¿ç”¨é€™äº›å…§æ ¸åŽŸèªžï¼Œé‚£éº¼å°±æ²’有 å¿…è¦å†ä½¿ç”¨volatile。如果ä»ç„¶å¿…é ˆä½¿ç”¨volatile，那麼幾乎å¯ä»¥è‚¯å®šåœ¨ä»£ç¢¼çš„æŸè™•æœ‰ä¸€ 個bug。在æ£ç¢ºè¨è¨ˆçš„å…§æ ¸ä»£ç¢¼ä¸ï¼Œvolatile能帶來的僅僅是使事情變慢。 @@ -46,8 +46,8 @@ C程å¼è¨è¨ˆå¸«é€šå¸¸èªçˆ²volatile表示æŸå€‹è®Šé‡å¯ä»¥åœ¨ç•¶å‰åŸ·è¡Œçš„ç· å¦‚æžœæ‰€æœ‰çš„ä»£ç¢¼éƒ½éµå¾ªåŠ 鎖è¦å‰‡ï¼Œç•¶æŒæœ‰the_lock的時候，ä¸å¯èƒ½æ„外的改變shared_dataçš„ 值。任何å¯èƒ½è¨ªå•è©²æ•¸æ“šçš„其他代碼都會在這個鎖上ç‰å¾…。自旋鎖原語跟內å˜å±éšœä¸€æ¨£â€”— 它 -們顯å¼çš„用來書寫æˆé€™æ¨£ —— æ„味著數據訪å•ä¸æœƒè·¨è¶Šå®ƒå€‘而被優化。所以本來編è¯å™¨èªçˆ² -它知é“在shared_data裡é¢å°‡æœ‰ä»€éº¼ï¼Œä½†æ˜¯å› 爲spin_lock()調用跟內å˜å±éšœä¸€æ¨£ï¼Œæœƒå¼·åˆ¶ç·¨ +們顯å¼çš„用來書寫æˆé€™æ¨£ —— æ„味ç€æ•¸æ“šè¨ªå•ä¸æœƒè·¨è¶Šå®ƒå€‘而被優化。所以本來編è¯å™¨èªçˆ² +它知é“在shared_dataè£é¢å°‡æœ‰ä»€éº¼ï¼Œä½†æ˜¯å› 爲spin_lock()調用跟內å˜å±éšœä¸€æ¨£ï¼Œæœƒå¼·åˆ¶ç·¨ è¯å™¨å¿˜è¨˜å®ƒæ‰€çŸ¥é“的一切。那麼在訪å•é€™äº›æ•¸æ“šæ™‚ä¸æœƒæœ‰å„ªåŒ–çš„å•é¡Œã€‚ 如果shared_data被è²å爲volatile，鎖æ“作將ä»ç„¶æ˜¯å¿…é ˆçš„ã€‚å°±ç®—æˆ‘å€‘çŸ¥é“沒有其他人æ£åœ¨ @@ -55,13 +55,13 @@ C程å¼è¨è¨ˆå¸«é€šå¸¸èªçˆ²volatile表示æŸå€‹è®Šé‡å¯ä»¥åœ¨ç•¶å‰åŸ·è¡Œçš„ç· shared_dataä¸æ˜¯volatile的。在處ç†å…±äº«æ•¸æ“šçš„時候，é©ç•¶çš„鎖æ“作å¯ä»¥ä¸å†éœ€è¦ volatile —— 並且是有潛在å±å®³çš„。 -volatileçš„å˜å„²é¡žåž‹æœ€åˆæ˜¯çˆ²é‚£äº›å…§å˜æ˜ å°„çš„I/O寄å˜å™¨è€Œå®šç¾©ã€‚åœ¨å…§æ ¸é‡Œï¼Œå¯„å˜å™¨è¨ªå•ä¹Ÿæ‡‰ -該被鎖ä¿è·ï¼Œä½†æ˜¯äººå€‘也ä¸å¸Œæœ›ç·¨è¯å™¨ã€Œå„ªåŒ–ã€è‡¨ç•Œå€å…§çš„寄å˜å™¨è¨ªå•ã€‚å…§æ ¸é‡ŒI/Oçš„å…§å˜è¨ªå• +volatileçš„å˜å„²é¡žåž‹æœ€åˆæ˜¯çˆ²é‚£äº›å…§å˜æ˜ å°„çš„I/O寄å˜å™¨è€Œå®šç¾©ã€‚åœ¨å…§æ ¸è£ï¼Œå¯„å˜å™¨è¨ªå•ä¹Ÿæ‡‰ +該被鎖ä¿è·ï¼Œä½†æ˜¯äººå€‘也ä¸å¸Œæœ›ç·¨è¯å™¨â€œå„ªåŒ–â€è‡¨ç•Œå€å…§çš„寄å˜å™¨è¨ªå•ã€‚å…§æ ¸è£I/Oçš„å…§å˜è¨ªå• 是通éŽè¨ªå•å‡½æ•¸å®Œæˆçš„ï¼›ä¸è´Šæˆé€šéŽæŒ‡é‡å°I/Oå…§å˜çš„直接訪å•ï¼Œä¸¦ä¸”ä¸æ˜¯åœ¨æ‰€æœ‰é«”系架構上 都能工作。那些訪å•å‡½æ•¸æ£æ˜¯çˆ²äº†é˜²æ¢æ„å¤–å„ªåŒ–è€Œå¯«çš„ï¼Œå› æ¤ï¼Œå†èªªä¸€æ¬¡ï¼Œvolatileé¡žåž‹ä¸ æ˜¯å¿…éœ€çš„ã€‚ -å¦ä¸€ç¨®å¼•èµ·ç”¨æˆ¶å¯èƒ½ä½¿ç”¨volatile的情æ³æ˜¯ç•¶è™•ç†å™¨æ£å¿™è‘—ç‰å¾…一個變é‡çš„值。æ£ç¢ºåŸ·è¡Œä¸€ +å¦ä¸€ç¨®å¼•èµ·ç”¨æˆ¶å¯èƒ½ä½¿ç”¨volatile的情æ³æ˜¯ç•¶è™•ç†å™¨æ£å¿™ç€ç‰å¾…一個變é‡çš„值。æ£ç¢ºåŸ·è¡Œä¸€ 個忙ç‰å¾…的方法是:: while (my_variable != what_i_want) @@ -74,14 +74,14 @@ cpu_relax()調用會é™ä½ŽCPU的能é‡æ¶ˆè€—或者讓ä½æ–¼è¶…線程雙處ç†å™¨ - 在一些體系架構的系統上，å…許直接的I/0å…§å˜è¨ªå•ï¼Œé‚£éº¼å‰é¢æ到的訪å•å‡½æ•¸å¯ä»¥ä½¿ç”¨ volatile。基本上，æ¯ä¸€å€‹è¨ªå•å‡½æ•¸èª¿ç”¨å®ƒè‡ªå·±éƒ½æ˜¯ä¸€å€‹å°çš„臨界å€åŸŸä¸¦ä¸”ä¿è‰äº†æŒ‰ç…§ - 程å¼è¨è¨ˆå¸«æœŸæœ›çš„那樣發生訪å•æ“作。 + 程åºå“¡æœŸæœ›çš„那樣發生訪å•æ“作。 - æŸäº›æœƒæ”¹è®Šå…§å˜çš„å…§è¯å½™ç·¨ä»£ç¢¼é›–然沒有什麼其他明顯的附作用，但是有被GCCåˆªé™¤çš„å¯ èƒ½æ€§ã€‚åœ¨å½™ç·¨è²æ˜Žä¸åŠ 上volatileé—œéµå—å¯ä»¥é˜²æ¢é€™ç¨®åˆªé™¤æ“作。 - Jiffies變é‡æ˜¯ä¸€ç¨®ç‰¹æ®Šæƒ…æ³ï¼Œé›–然æ¯æ¬¡å¼•ç”¨å®ƒçš„時候都å¯ä»¥æœ‰ä¸åŒçš„值，但讀jiffies 變é‡æ™‚ä¸éœ€è¦ä»»ä½•ç‰¹æ®Šçš„åŠ éŽ–ä¿è·ã€‚所以jiffies變é‡å¯ä»¥ä½¿ç”¨volatile，但是ä¸è´Šæˆ - 其他跟jiffies相åŒé¡žåž‹è®Šé‡ä½¿ç”¨volatile。Jiffies被èªçˆ²æ˜¯ä¸€ç¨®ã€Œæ„šè ¢çš„éºç•™ç‰©" + 其他跟jiffies相åŒé¡žåž‹è®Šé‡ä½¿ç”¨volatile。Jiffies被èªçˆ²æ˜¯ä¸€ç¨®â€œæ„šè ¢çš„éºç•™ç‰©" （Linusçš„è©±ï¼‰å› çˆ²è§£æ±ºé€™å€‹å•é¡Œæ¯”ä¿æŒç¾ç‹€è¦éº»ç…©çš„多。 - 由於æŸäº›I/0è¨å‚™å¯èƒ½æœƒä¿®æ”¹é€£çºŒä¸€è‡´çš„å…§å˜,所以有時,指å‘連續一致內å˜çš„數據çµæ§‹ @@ -92,9 +92,9 @@ cpu_relax()調用會é™ä½ŽCPU的能é‡æ¶ˆè€—或者讓ä½æ–¼è¶…線程雙處ç†å™¨ bug並且需è¦å°é€™æ¨£çš„代碼é¡å¤–仔細檢查。那些試圖使用volatile的開發人員需è¦é€€ä¸€æ¥æƒ³æƒ³ 他們真æ£æƒ³å¯¦ç¾çš„是什麼。 -éžå¸¸æ¡è¿Žåˆªé™¤volatile變é‡çš„è£œä¸ ï¼ åªè¦è‰æ˜Žé€™äº›è£œä¸å®Œæ•´çš„考慮了並發å•é¡Œã€‚ +éžå¸¸æ¡è¿Žåˆªé™¤volatile變é‡çš„è£œä¸ ï¼ åªè¦è‰æ˜Žé€™äº›è£œä¸å®Œæ•´çš„考慮了併發å•é¡Œã€‚ -注釋 +註釋 ---- [1] https://lwn.net/Articles/233481/ diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 394cd226bfae..29072c166d23 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -755,6 +755,8 @@ The uac2 function provides these attributes in its function directory: req_number the number of pre-allocated request for both capture and playback function_name name of the interface + c_terminal_type code of the capture terminal type + p_terminal_type code of the playback terminal type ================ ==================================================== The attributes have sane default values. diff --git a/Documentation/usb/gadget_uvc.rst b/Documentation/usb/gadget_uvc.rst index 80a1f031b593..bf78fba3ce23 100644 --- a/Documentation/usb/gadget_uvc.rst +++ b/Documentation/usb/gadget_uvc.rst @@ -126,7 +126,7 @@ might do: create_frame 1920 1080 uncompressed yuyv The only uncompressed format currently supported is YUYV, which is detailed at -Documentation/userspace-api/media/v4l/pixfmt-packed.yuv.rst. +Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst. Color Matching Descriptors ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index d8cd8cd9ce25..2e3822677061 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -8,13 +8,13 @@ Landlock: unprivileged access control ===================================== :Author: Mickaël Salaün -:Date: October 2022 +:Date: October 2023 The goal of Landlock is to enable to restrict ambient rights (e.g. global -filesystem access) for a set of processes. Because Landlock is a stackable -LSM, it makes possible to create safe security sandboxes as new security layers -in addition to the existing system-wide access-controls. This kind of sandbox -is expected to help mitigate the security impact of bugs or +filesystem or network access) for a set of processes. Because Landlock +is a stackable LSM, it makes possible to create safe security sandboxes as new +security layers in addition to the existing system-wide access-controls. This +kind of sandbox is expected to help mitigate the security impact of bugs or unexpected/malicious behaviors in user space applications. Landlock empowers any process, including unprivileged ones, to securely restrict themselves. @@ -28,20 +28,34 @@ appropriately <kernel_support>`. Landlock rules ============== -A Landlock rule describes an action on an object. An object is currently a -file hierarchy, and the related filesystem actions are defined with `access -rights`_. A set of rules is aggregated in a ruleset, which can then restrict +A Landlock rule describes an action on an object which the process intends to +perform. A set of rules is aggregated in a ruleset, which can then restrict the thread enforcing it, and its future children. +The two existing types of rules are: + +Filesystem rules + For these rules, the object is a file hierarchy, + and the related filesystem actions are defined with + `filesystem access rights`. + +Network rules (since ABI v4) + For these rules, the object is a TCP port, + and the related actions are defined with `network access rights`. + Defining and enforcing a security policy ---------------------------------------- -We first need to define the ruleset that will contain our rules. For this -example, the ruleset will contain rules that only allow read actions, but write -actions will be denied. The ruleset then needs to handle both of these kind of -actions. This is required for backward and forward compatibility (i.e. the -kernel and user space may not know each other's supported restrictions), hence -the need to be explicit about the denied-by-default access rights. +We first need to define the ruleset that will contain our rules. + +For this example, the ruleset will contain rules that only allow filesystem +read actions and establish a specific TCP connection. Filesystem write +actions and other TCP actions will be denied. + +The ruleset then needs to handle both these kinds of actions. This is +required for backward and forward compatibility (i.e. the kernel and user +space may not know each other's supported restrictions), hence the need +to be explicit about the denied-by-default access rights. .. code-block:: c @@ -62,6 +76,9 @@ the need to be explicit about the denied-by-default access rights. LANDLOCK_ACCESS_FS_MAKE_SYM | LANDLOCK_ACCESS_FS_REFER | LANDLOCK_ACCESS_FS_TRUNCATE, + .handled_access_net = + LANDLOCK_ACCESS_NET_BIND_TCP | + LANDLOCK_ACCESS_NET_CONNECT_TCP, }; Because we may not know on which kernel version an application will be @@ -70,9 +87,7 @@ should try to protect users as much as possible whatever the kernel they are using. To avoid binary enforcement (i.e. either all security features or none), we can leverage a dedicated Landlock command to get the current version of the Landlock ABI and adapt the handled accesses. Let's check if we should -remove the ``LANDLOCK_ACCESS_FS_REFER`` or ``LANDLOCK_ACCESS_FS_TRUNCATE`` -access rights, which are only supported starting with the second and third -version of the ABI. +remove access rights which are only supported in higher versions of the ABI. .. code-block:: c @@ -92,6 +107,12 @@ version of the ABI. case 2: /* Removes LANDLOCK_ACCESS_FS_TRUNCATE for ABI < 3 */ ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_TRUNCATE; + __attribute__((fallthrough)); + case 3: + /* Removes network support for ABI < 4 */ + ruleset_attr.handled_access_net &= + ~(LANDLOCK_ACCESS_NET_BIND_TCP | + LANDLOCK_ACCESS_NET_CONNECT_TCP); } This enables to create an inclusive ruleset that will contain our rules. @@ -143,10 +164,23 @@ for the ruleset creation, by filtering access rights according to the Landlock ABI version. In this example, this is not required because all of the requested ``allowed_access`` rights are already available in ABI 1. -We now have a ruleset with one rule allowing read access to ``/usr`` while -denying all other handled accesses for the filesystem. The next step is to -restrict the current thread from gaining more privileges (e.g. thanks to a SUID -binary). +For network access-control, we can add a set of rules that allow to use a port +number for a specific action: HTTPS connections. + +.. code-block:: c + + struct landlock_net_port_attr net_port = { + .allowed_access = LANDLOCK_ACCESS_NET_CONNECT_TCP, + .port = 443, + }; + + err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT, + &net_port, 0); + +The next step is to restrict the current thread from gaining more privileges +(e.g. through a SUID binary). We now have a ruleset with the first rule +allowing read access to ``/usr`` while denying all other handled accesses for +the filesystem, and a second rule allowing HTTPS connections. .. code-block:: c @@ -355,7 +389,7 @@ Access rights ------------- .. kernel-doc:: include/uapi/linux/landlock.h - :identifiers: fs_access + :identifiers: fs_access net_access Creating a new ruleset ---------------------- @@ -374,6 +408,7 @@ Extending a ruleset .. kernel-doc:: include/uapi/linux/landlock.h :identifiers: landlock_rule_type landlock_path_beneath_attr + landlock_net_port_attr Enforcing a ruleset ------------------- @@ -387,9 +422,9 @@ Current limitations Filesystem topology modification -------------------------------- -As for file renaming and linking, a sandboxed thread cannot modify its -filesystem topology, whether via :manpage:`mount(2)` or -:manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied. +Threads sandboxed with filesystem restrictions cannot modify filesystem +topology, whether via :manpage:`mount(2)` or :manpage:`pivot_root(2)`. +However, :manpage:`chroot(2)` calls are not denied. Special filesystems ------------------- @@ -451,6 +486,14 @@ always allowed when using a kernel that only supports the first or second ABI. Starting with the Landlock ABI version 3, it is now possible to securely control truncation thanks to the new ``LANDLOCK_ACCESS_FS_TRUNCATE`` access right. +Network support (ABI < 4) +------------------------- + +Starting with the Landlock ABI version 4, it is now possible to restrict TCP +bind and connect actions to only a set of allowed ports thanks to the new +``LANDLOCK_ACCESS_NET_BIND_TCP`` and ``LANDLOCK_ACCESS_NET_CONNECT_TCP`` +access rights. + .. _kernel_support: Kernel support @@ -469,6 +512,12 @@ still enable it by adding ``lsm=landlock,[...]`` to Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader configuration. +To be able to explicitly allow TCP operations (e.g., adding a network rule with +``LANDLOCK_ACCESS_NET_BIND_TCP``), the kernel must support TCP +(``CONFIG_INET=y``). Otherwise, sys_landlock_add_rule() returns an +``EAFNOSUPPORT`` error, which can safely be ignored because this kind of TCP +operation is already not possible. + Questions and answers ===================== diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst new file mode 100644 index 000000000000..919a50e8b9d9 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _media_using_camera_sensor_drivers: + +Using camera sensor drivers +=========================== + +This section describes common practices for how the V4L2 sub-device interface is +used to control the camera sensor drivers. + +You may also find :ref:`media_writing_camera_sensor_drivers` useful. + +Frame size +---------- + +There are two distinct ways to configure the frame size produced by camera +sensors. + +Freely configurable camera sensor drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Freely configurable camera sensor drivers expose the device's internal +processing pipeline as one or more sub-devices with different cropping and +scaling configurations. The output size of the device is the result of a series +of cropping and scaling operations from the device's pixel array's size. + +An example of such a driver is the CCS driver. + +Register list based drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Register list based drivers generally, instead of able to configure the device +they control based on user requests, are limited to a number of preset +configurations that combine a number of different parameters that on hardware +level are independent. How a driver picks such configuration is based on the +format set on a source pad at the end of the device's internal pipeline. + +Most sensor drivers are implemented this way. + +Frame interval configuration +---------------------------- + +There are two different methods for obtaining possibilities for different frame +intervals as well as configuring the frame interval. Which one to implement +depends on the type of the device. + +Raw camera sensors +~~~~~~~~~~~~~~~~~~ + +Instead of a high level parameter such as frame interval, the frame interval is +a result of the configuration of a number of camera sensor implementation +specific parameters. Luckily, these parameters tend to be the same for more or +less all modern raw camera sensors. + +The frame interval is calculated using the following equation:: + + frame interval = (analogue crop width + horizontal blanking) * + (analogue crop height + vertical blanking) / pixel rate + +The formula is bus independent and is applicable for raw timing parameters on +large variety of devices beyond camera sensors. Devices that have no analogue +crop, use the full source image size, i.e. pixel array size. + +Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and +``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control +is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in +the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same +sub-device. The unit of that control is pixels per second. + +Register list based drivers need to implement read-only sub-device nodes for the +purpose. Devices that are not register list based need these to configure the +device's internal processing pipeline. + +The first entity in the linear pipeline is the pixel array. The pixel array may +be followed by other entities that are there to allow configuring binning, +skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION +<VIDIOC_SUBDEV_G_SELECTION>`. + +USB cameras etc. devices +~~~~~~~~~~~~~~~~~~~~~~~~ + +USB video class hardware, as well as many cameras offering a similar higher +level interface natively, generally use the concept of frame interval (or frame +rate) on device level in firmware or hardware. This means lower level controls +implemented by raw cameras may not be used on uAPI (or even kAPI) to control the +frame interval on these devices. + +Rotation, orientation and flipping +---------------------------------- + +Some systems have the camera sensor mounted upside down compared to its natural +mounting rotation. In such cases, drivers shall expose the information to +userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION +<v4l2-camera-sensor-rotation>` control. + +Sensor drivers shall also report the sensor's mounting orientation with the +:ref:`V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>`. + +Sensor drivers that have any vertical or horizontal flips embedded in the +register programming sequences shall initialize the :ref:`V4L2_CID_HFLIP +<v4l2-cid-hflip>` and :ref:`V4L2_CID_VFLIP <v4l2-cid-vflip>` controls with the +values programmed by the register sequences. The default values of these +controls shall be 0 (disabled). Especially these controls shall not be inverted, +independently of the sensor's mounting rotation. diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst index 6708d649afd7..1726f8ec86fa 100644 --- a/Documentation/userspace-api/media/drivers/index.rst +++ b/Documentation/userspace-api/media/drivers/index.rst @@ -32,11 +32,13 @@ For more details see the file COPYING in the source distribution of Linux. :numbered: aspeed-video + camera-sensor ccs cx2341x-uapi dw100 imx-uapi max2175 + npcm-video omap3isp-uapi st-vgxy61 uvcvideo diff --git a/Documentation/userspace-api/media/drivers/npcm-video.rst b/Documentation/userspace-api/media/drivers/npcm-video.rst new file mode 100644 index 000000000000..b47771dd8b27 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/npcm-video.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: <isonum.txt> + +NPCM video driver +================= + +This driver is used to control the Video Capture/Differentiation (VCD) engine +and Encoding Compression Engine (ECE) present on Nuvoton NPCM SoCs. The VCD can +capture a frame from digital video input and compare two frames in memory, and +the ECE can compress the frame data into HEXTILE format. + +Driver-specific Controls +------------------------ + +V4L2_CID_NPCM_CAPTURE_MODE +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The VCD engine supports two modes: + +- COMPLETE mode: + + Capture the next complete frame into memory. + +- DIFF mode: + + Compare the incoming frame with the frame stored in memory, and updates the + differentiated frame in memory. + +Application can use ``V4L2_CID_NPCM_CAPTURE_MODE`` control to set the VCD mode +with different control values (enum v4l2_npcm_capture_mode): + +- ``V4L2_NPCM_CAPTURE_MODE_COMPLETE``: will set VCD to COMPLETE mode. +- ``V4L2_NPCM_CAPTURE_MODE_DIFF``: will set VCD to DIFF mode. + +V4L2_CID_NPCM_RECT_COUNT +~~~~~~~~~~~~~~~~~~~~~~~~ + +If using V4L2_PIX_FMT_HEXTILE format, VCD will capture frame data and then ECE +will compress the data into HEXTILE rectangles and store them in V4L2 video +buffer with the layout defined in Remote Framebuffer Protocol: +:: + + (RFC 6143, https://www.rfc-editor.org/rfc/rfc6143.html#section-7.6.1) + + +--------------+--------------+-------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------------+ + | 2 | U16 | x-position | + | 2 | U16 | y-position | + | 2 | U16 | width | + | 2 | U16 | height | + | 4 | S32 | encoding-type (5) | + +--------------+--------------+-------------------+ + | HEXTILE rectangle data | + +-------------------------------------------------+ + +Application can get the video buffer through VIDIOC_DQBUF, and followed by +calling ``V4L2_CID_NPCM_RECT_COUNT`` control to get the number of HEXTILE +rectangles in this buffer. + +References +---------- +include/uapi/linux/npcm-video.h + +**Copyright** |copy| 2022 Nuvoton Technologies diff --git a/Documentation/userspace-api/media/gen-errors.rst b/Documentation/userspace-api/media/gen-errors.rst index e595d0bea109..4e8defd3612b 100644 --- a/Documentation/userspace-api/media/gen-errors.rst +++ b/Documentation/userspace-api/media/gen-errors.rst @@ -59,9 +59,7 @@ Generic Error Codes - - ``ENOTTY`` - - The ioctl is not supported by the driver, actually meaning that - the required functionality is not available, or the file - descriptor is not for a media device. + - The ioctl is not supported by the file descriptor. - - ``ENOSPC`` diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 04dec3e570ed..52bbee81c080 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -549,9 +549,9 @@ Buffer Flags - 0x00000400 - The buffer has been prepared for I/O and can be queued by the application. Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, - :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` or :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index 4463fce694b0..57893814a1e5 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -143,9 +143,13 @@ Control IDs recognise the difference between digital and analogue gain use controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. +.. _v4l2-cid-hflip: + ``V4L2_CID_HFLIP`` ``(boolean)`` Mirror the picture horizontally. +.. _v4l2-cid-vflip: + ``V4L2_CID_VFLIP`` ``(boolean)`` Mirror the picture vertically. diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst index a4f1df7093e8..43988516acdd 100644 --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst @@ -579,20 +579,19 @@ is started. There are three steps in configuring the streams: -1) Set up links. Connect the pads between sub-devices using the :ref:`Media -Controller API <media_controller>` +1. Set up links. Connect the pads between sub-devices using the + :ref:`Media Controller API <media_controller>` -2) Streams. Streams are declared and their routing is configured by -setting the routing table for the sub-device using -:ref:`VIDIOC_SUBDEV_S_ROUTING <VIDIOC_SUBDEV_G_ROUTING>` ioctl. Note that -setting the routing table will reset formats and selections in the -sub-device to default values. +2. Streams. Streams are declared and their routing is configured by setting the + routing table for the sub-device using :ref:`VIDIOC_SUBDEV_S_ROUTING + <VIDIOC_SUBDEV_G_ROUTING>` ioctl. Note that setting the routing table will + reset formats and selections in the sub-device to default values. -3) Configure formats and selections. Formats and selections of each stream -are configured separately as documented for plain sub-devices in -:ref:`format-propagation`. The stream ID is set to the same stream ID -associated with either sink or source pads of routes configured using the -:ref:`VIDIOC_SUBDEV_S_ROUTING <VIDIOC_SUBDEV_G_ROUTING>` ioctl. +3. Configure formats and selections. Formats and selections of each stream are + configured separately as documented for plain sub-devices in + :ref:`format-propagation`. The stream ID is set to the same stream ID + associated with either sink or source pads of routes configured using the + :ref:`VIDIOC_SUBDEV_S_ROUTING <VIDIOC_SUBDEV_G_ROUTING>` ioctl. Multiplexed streams setup example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -618,11 +617,11 @@ modeled as V4L2 devices, exposed to userspace via /dev/videoX nodes. To configure this pipeline, the userspace must take the following steps: -1) Set up media links between entities: connect the sensors to the bridge, -bridge to the receiver, and the receiver to the DMA engines. This step does -not differ from normal non-multiplexed media controller setup. +1. Set up media links between entities: connect the sensors to the bridge, + bridge to the receiver, and the receiver to the DMA engines. This step does + not differ from normal non-multiplexed media controller setup. -2) Configure routing +2. Configure routing .. flat-table:: Bridge routing table :header-rows: 1 @@ -656,14 +655,14 @@ not differ from normal non-multiplexed media controller setup. - V4L2_SUBDEV_ROUTE_FL_ACTIVE - Pixel data stream from Sensor B -3) Configure formats and selections +3. Configure formats and selections -After configuring routing, the next step is configuring the formats and -selections for the streams. This is similar to performing this step without -streams, with just one exception: the ``stream`` field needs to be assigned -to the value of the stream ID. + After configuring routing, the next step is configuring the formats and + selections for the streams. This is similar to performing this step without + streams, with just one exception: the ``stream`` field needs to be assigned + to the value of the stream ID. -A common way to accomplish this is to start from the sensors and propagate the -configurations along the stream towards the receiver, -using :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls to configure each -stream endpoint in each sub-device. + A common way to accomplish this is to start from the sensors and propagate + the configurations along the stream towards the receiver, using + :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls to configure each + stream endpoint in each sub-device. diff --git a/Documentation/userspace-api/media/v4l/dv-timings.rst b/Documentation/userspace-api/media/v4l/dv-timings.rst index e17f056b129f..4b19bcb4bd80 100644 --- a/Documentation/userspace-api/media/v4l/dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/dv-timings.rst @@ -33,6 +33,27 @@ current DV timings they use the the DV timings as seen by the video receiver applications use the :ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl. +When the hardware detects a video source change (e.g. the video +signal appears or disappears, or the video resolution changes), then +it will issue a `V4L2_EVENT_SOURCE_CHANGE` event. Use the +:ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` and the +:ref:`VIDIOC_DQEVENT` to check if this event was reported. + +If the video signal changed, then the application has to stop +streaming, free all buffers, and call the :ref:`VIDIOC_QUERY_DV_TIMINGS` +to obtain the new video timings, and if they are valid, it can set +those by calling the :ref:`ioctl VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`. +This will also update the format, so use the :ref:`ioctl VIDIOC_G_FMT <VIDIOC_G_FMT>` +to obtain the new format. Now the application can allocate new buffers +and start streaming again. + +The :ref:`VIDIOC_QUERY_DV_TIMINGS` will just report what the +hardware detects, it will never change the configuration. If the +currently set timings and the actually detected timings differ, then +typically this will mean that you will not be able to capture any +video. The correct approach is to rely on the `V4L2_EVENT_SOURCE_CHANGE` +event so you know when something changed. + Applications can make use of the :ref:`input-capabilities` and :ref:`output-capabilities` flags to determine whether the digital video ioctls can be used with the given input or output. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index 296ad2025e8d..886ba7b08d6b 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -288,6 +288,13 @@ please make a proposal on the linux-media mailing list. - 'MT2110R' - This format is two-planar 10-Bit raster mode and having similitude with ``V4L2_PIX_FMT_MM21`` in term of alignment and tiling. Used for AVC. + * .. _V4L2-PIX-FMT-HEXTILE: + + - ``V4L2_PIX_FMT_HEXTILE`` + - 'HXTL' + - Compressed format used by Nuvoton NPCM video driver. This format is + defined in Remote Framebuffer Protocol (RFC 6143, chapter 7.7.4 Hextile + Encoding). .. raw:: latex \normalsize diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index b6e79e2f8ce4..7c3810ff783c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -60,7 +60,7 @@ Each cell is one byte. G\ :sub:`10low`\ (bits 3--0) - G\ :sub:`12high` - R\ :sub:`13high` - - R\ :sub:`13low`\ (bits 3--2) + - R\ :sub:`13low`\ (bits 7--4) G\ :sub:`12low`\ (bits 3--0) - - start + 12: @@ -82,6 +82,6 @@ Each cell is one byte. G\ :sub:`30low`\ (bits 3--0) - G\ :sub:`32high` - R\ :sub:`33high` - - R\ :sub:`33low`\ (bits 3--2) + - R\ :sub:`33low`\ (bits 7--4) G\ :sub:`32low`\ (bits 3--0) diff --git a/Documentation/userspace-api/netlink/genetlink-legacy.rst b/Documentation/userspace-api/netlink/genetlink-legacy.rst index 40b82ad5d54a..70a77387f6c4 100644 --- a/Documentation/userspace-api/netlink/genetlink-legacy.rst +++ b/Documentation/userspace-api/netlink/genetlink-legacy.rst @@ -11,6 +11,20 @@ the ``genetlink-legacy`` protocol level. Specification ============= +Globals +------- + +Attributes listed directly at the root level of the spec file. + +version +~~~~~~~ + +Generic Netlink family version, default is 1. + +``version`` has historically been used to introduce family changes +which may break backwards compatibility. Since compatibility breaking changes +are generally not allowed ``version`` is very rarely used. + Attribute type nests -------------------- @@ -168,7 +182,7 @@ members - ``name`` - The attribute name of the struct member - ``type`` - One of the scalar types ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, - ``s16``, ``s32``, ``s64``, ``string`` or ``binary``. + ``s16``, ``s32``, ``s64``, ``string``, ``binary`` or ``bitfield32``. - ``byte-order`` - ``big-endian`` or ``little-endian`` - ``doc``, ``enum``, ``enum-as-flags``, ``display-hint`` - Same as for :ref:`attribute definitions <attribute_properties>` diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst index cc4e2430997e..c1b951649113 100644 --- a/Documentation/userspace-api/netlink/specs.rst +++ b/Documentation/userspace-api/netlink/specs.rst @@ -86,11 +86,6 @@ name Name of the family. Name identifies the family in a unique way, since the Family IDs are allocated dynamically. -version -~~~~~~~ - -Generic Netlink family version, default is 1. - protocol ~~~~~~~~ @@ -408,10 +403,21 @@ This section describes the attribute types supported by the ``genetlink`` compatibility level. Refer to documentation of different levels for additional attribute types. -Scalar integer types +Common integer types -------------------- -Fixed-width integer types: +``sint`` and ``uint`` represent signed and unsigned 64 bit integers. +If the value can fit on 32 bits only 32 bits are carried in netlink +messages, otherwise full 64 bits are carried. Note that the payload +is only aligned to 4B, so the full 64 bit value may be unaligned! + +Common integer types should be preferred over fix-width types in majority +of cases. + +Fix-width integer types +----------------------- + +Fixed-width integer types include: ``u8``, ``u16``, ``u32``, ``u64``, ``s8``, ``s16``, ``s32``, ``s64``. Note that types smaller than 32 bit should be avoided as using them @@ -421,6 +427,9 @@ See :ref:`pad_type` for padding of 64 bit attributes. The payload of the attribute is the integer in host order unless ``byte-order`` specifies otherwise. +64 bit values are usually aligned by the kernel but it is recommended +that the user space is able to deal with unaligned values. + .. _pad_type: pad diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 21a7578142a1..7025b3751027 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -416,6 +416,13 @@ Reads the general purpose registers from the vcpu. __u64 pc; }; + /* LoongArch */ + struct kvm_regs { + /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ + unsigned long gpr[32]; + unsigned long pc; + }; + 4.12 KVM_SET_REGS ----------------- @@ -506,7 +513,7 @@ translation mode. ------------------ :Capability: basic -:Architectures: x86, ppc, mips, riscv +:Architectures: x86, ppc, mips, riscv, loongarch :Type: vcpu ioctl :Parameters: struct kvm_interrupt (in) :Returns: 0 on success, negative on failure. @@ -540,7 +547,7 @@ ioctl is useful if the in-kernel PIC is not used. PPC: ^^^^ -Queues an external interrupt to be injected. This ioctl is overleaded +Queues an external interrupt to be injected. This ioctl is overloaded with 3 different irq values: a) KVM_INTERRUPT_SET @@ -592,6 +599,14 @@ b) KVM_INTERRUPT_UNSET This is an asynchronous vcpu ioctl and can be invoked from any thread. +LOONGARCH: +^^^^^^^^^^ + +Queues an external interrupt to be injected into the virtual CPU. A negative +interrupt number dequeues the interrupt. + +This is an asynchronous vcpu ioctl and can be invoked from any thread. + 4.17 KVM_DEBUG_GUEST -------------------- @@ -737,7 +752,7 @@ signal mask. ---------------- :Capability: basic -:Architectures: x86 +:Architectures: x86, loongarch :Type: vcpu ioctl :Parameters: struct kvm_fpu (out) :Returns: 0 on success, -1 on error @@ -746,7 +761,7 @@ Reads the floating point state from the vcpu. :: - /* for KVM_GET_FPU and KVM_SET_FPU */ + /* x86: for KVM_GET_FPU and KVM_SET_FPU */ struct kvm_fpu { __u8 fpr[8][16]; __u16 fcw; @@ -761,12 +776,21 @@ Reads the floating point state from the vcpu. __u32 pad2; }; + /* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */ + struct kvm_fpu { + __u32 fcsr; + __u64 fcc; + struct kvm_fpureg { + __u64 val64[4]; + }fpr[32]; + }; + 4.23 KVM_SET_FPU ---------------- :Capability: basic -:Architectures: x86 +:Architectures: x86, loongarch :Type: vcpu ioctl :Parameters: struct kvm_fpu (in) :Returns: 0 on success, -1 on error @@ -775,7 +799,7 @@ Writes the floating point state to the vcpu. :: - /* for KVM_GET_FPU and KVM_SET_FPU */ + /* x86: for KVM_GET_FPU and KVM_SET_FPU */ struct kvm_fpu { __u8 fpr[8][16]; __u16 fcw; @@ -790,6 +814,15 @@ Writes the floating point state to the vcpu. __u32 pad2; }; + /* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */ + struct kvm_fpu { + __u32 fcsr; + __u64 fcc; + struct kvm_fpureg { + __u64 val64[4]; + }fpr[32]; + }; + 4.24 KVM_CREATE_IRQCHIP ----------------------- @@ -965,7 +998,7 @@ be set in the flags field of this ioctl: The KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag requests KVM to generate the contents of the hypercall page automatically; hypercalls will be intercepted and passed to userspace through KVM_EXIT_XEN. In this -ase, all of the blob size and address fields must be zero. +case, all of the blob size and address fields must be zero. The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates to KVM that userspace will always use the KVM_XEN_HVM_EVTCHN_SEND ioctl to deliver event @@ -1070,7 +1103,7 @@ Other flags returned by ``KVM_GET_CLOCK`` are accepted but ignored. :Extended by: KVM_CAP_INTR_SHADOW :Architectures: x86, arm64 :Type: vcpu ioctl -:Parameters: struct kvm_vcpu_event (out) +:Parameters: struct kvm_vcpu_events (out) :Returns: 0 on success, -1 on error X86: @@ -1193,7 +1226,7 @@ directly to the virtual CPU). :Extended by: KVM_CAP_INTR_SHADOW :Architectures: x86, arm64 :Type: vcpu ioctl -:Parameters: struct kvm_vcpu_event (in) +:Parameters: struct kvm_vcpu_events (in) :Returns: 0 on success, -1 on error X86: @@ -1387,7 +1420,7 @@ documentation when it pops into existence). ------------------- :Capability: KVM_CAP_ENABLE_CAP -:Architectures: mips, ppc, s390, x86 +:Architectures: mips, ppc, s390, x86, loongarch :Type: vcpu ioctl :Parameters: struct kvm_enable_cap (in) :Returns: 0 on success; -1 on error @@ -1442,7 +1475,7 @@ for vm-wide capabilities. --------------------- :Capability: KVM_CAP_MP_STATE -:Architectures: x86, s390, arm64, riscv +:Architectures: x86, s390, arm64, riscv, loongarch :Type: vcpu ioctl :Parameters: struct kvm_mp_state (out) :Returns: 0 on success; -1 on error @@ -1460,7 +1493,7 @@ Possible values are: ========================== =============================================== KVM_MP_STATE_RUNNABLE the vcpu is currently running - [x86,arm64,riscv] + [x86,arm64,riscv,loongarch] KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP) which has not yet received an INIT signal [x86] KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is @@ -1516,11 +1549,14 @@ For riscv: The only states that are valid are KVM_MP_STATE_STOPPED and KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not. +On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect +whether the vcpu is runnable. + 4.39 KVM_SET_MP_STATE --------------------- :Capability: KVM_CAP_MP_STATE -:Architectures: x86, s390, arm64, riscv +:Architectures: x86, s390, arm64, riscv, loongarch :Type: vcpu ioctl :Parameters: struct kvm_mp_state (in) :Returns: 0 on success; -1 on error @@ -1538,6 +1574,9 @@ For arm64/riscv: The only states that are valid are KVM_MP_STATE_STOPPED and KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not. +On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect +whether the vcpu is runnable. + 4.40 KVM_SET_IDENTITY_MAP_ADDR ------------------------------ @@ -2841,6 +2880,19 @@ Following are the RISC-V D-extension registers: 0x8020 0000 0600 0020 fcsr Floating point control and status register ======================= ========= ============================================= +LoongArch registers are mapped using the lower 32 bits. The upper 16 bits of +that is the register group type. + +LoongArch csr registers are used to control guest cpu or get status of guest +cpu, and they have the following id bit patterns:: + + 0x9030 0000 0001 00 <reg:5> <sel:3> (64-bit) + +LoongArch KVM control registers are used to implement some new defined functions +such as set vcpu counter or reset vcpu, and they have the following id bit patterns:: + + 0x9030 0000 0002 <reg:16> + 4.69 KVM_GET_ONE_REG -------------------- @@ -3063,7 +3115,7 @@ as follow:: }; An entry with a "page_shift" of 0 is unused. Because the array is -organized in increasing order, a lookup can stop when encoutering +organized in increasing order, a lookup can stop when encountering such an entry. The "slb_enc" field provides the encoding to use in the SLB for the @@ -3370,6 +3422,8 @@ return indicates the attribute is implemented. It does not necessarily indicate that the attribute can be read or written in the device's current state. "addr" is ignored. +.. _KVM_ARM_VCPU_INIT: + 4.82 KVM_ARM_VCPU_INIT ---------------------- @@ -3455,7 +3509,7 @@ Possible features: - KVM_RUN and KVM_GET_REG_LIST are not available; - KVM_GET_ONE_REG and KVM_SET_ONE_REG cannot be used to access - the scalable archietctural SVE registers + the scalable architectural SVE registers KVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() or KVM_REG_ARM64_SVE_FFR; @@ -4401,7 +4455,7 @@ This will have undefined effects on the guest if it has not already placed itself in a quiescent state where no vcpu will make MMU enabled memory accesses. -On succsful completion, the pending HPT will become the guest's active +On successful completion, the pending HPT will become the guest's active HPT and the previous HPT will be discarded. On failure, the guest will still be operating on its previous HPT. @@ -5016,7 +5070,7 @@ before the vcpu is fully usable. Between KVM_ARM_VCPU_INIT and KVM_ARM_VCPU_FINALIZE, the feature may be configured by use of ioctls such as KVM_SET_ONE_REG. The exact configuration -that should be performaned and how to do it are feature-dependent. +that should be performed and how to do it are feature-dependent. Other calls that depend on a particular feature being finalized, such as KVM_RUN, KVM_GET_REG_LIST, KVM_GET_ONE_REG and KVM_SET_ONE_REG, will fail with @@ -5124,6 +5178,24 @@ Valid values for 'action':: #define KVM_PMU_EVENT_ALLOW 0 #define KVM_PMU_EVENT_DENY 1 +Via this API, KVM userspace can also control the behavior of the VM's fixed +counters (if any) by configuring the "action" and "fixed_counter_bitmap" fields. + +Specifically, KVM follows the following pseudo-code when determining whether to +allow the guest FixCtr[i] to count its pre-defined fixed event:: + + FixCtr[i]_is_allowed = (action == ALLOW) && (bitmap & BIT(i)) || + (action == DENY) && !(bitmap & BIT(i)); + FixCtr[i]_is_denied = !FixCtr[i]_is_allowed; + +KVM always consumes fixed_counter_bitmap, it's userspace's responsibility to +ensure fixed_counter_bitmap is set correctly, e.g. if userspace wants to define +a filter that only affects general purpose counters. + +Note, the "events" field also applies to fixed counters' hardcoded event_select +and unit_mask values. "fixed_counter_bitmap" has higher priority than "events" +if there is a contradiction between the two. + 4.121 KVM_PPC_SVM_OFF --------------------- @@ -5475,7 +5547,7 @@ KVM_XEN_ATTR_TYPE_EVTCHN from the guest. A given sending port number may be directed back to a specified vCPU (by APIC ID) / port / priority on the guest, or to trigger events on an eventfd. The vCPU and priority can be changed - by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but but other + by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but other fields cannot change for a given sending port. A port mapping is removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing KVM_XEN_EVTCHN_RESET in the flags field removes all interception of @@ -6070,6 +6142,56 @@ writes to the CNTVCT_EL0 and CNTPCT_EL0 registers using the SET_ONE_REG interface. No error will be returned, but the resulting offset will not be applied. +.. _KVM_ARM_GET_REG_WRITABLE_MASKS: + +4.139 KVM_ARM_GET_REG_WRITABLE_MASKS +------------------------------------------- + +:Capability: KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES +:Architectures: arm64 +:Type: vm ioctl +:Parameters: struct reg_mask_range (in/out) +:Returns: 0 on success, < 0 on error + + +:: + + #define KVM_ARM_FEATURE_ID_RANGE 0 + #define KVM_ARM_FEATURE_ID_RANGE_SIZE (3 * 8 * 8) + + struct reg_mask_range { + __u64 addr; /* Pointer to mask array */ + __u32 range; /* Requested range */ + __u32 reserved[13]; + }; + +This ioctl copies the writable masks for a selected range of registers to +userspace. + +The ``addr`` field is a pointer to the destination array where KVM copies +the writable masks. + +The ``range`` field indicates the requested range of registers. +``KVM_CHECK_EXTENSION`` for the ``KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES`` +capability returns the supported ranges, expressed as a set of flags. Each +flag's bit index represents a possible value for the ``range`` field. +All other values are reserved for future use and KVM may return an error. + +The ``reserved[13]`` array is reserved for future use and should be 0, or +KVM may return an error. + +KVM_ARM_FEATURE_ID_RANGE (0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Feature ID range is defined as the AArch64 System register space with +op0==3, op1=={0, 1, 3}, CRn==0, CRm=={0-7}, op2=={0-7}. + +The mask returned array pointed to by ``addr`` is indexed by the macro +``ARM64_FEATURE_ID_RANGE_IDX(op0, op1, crn, crm, op2)``, allowing userspace +to know what fields can be changed for the system register described by +``op0, op1, crn, crm, op2``. KVM rejects ID register values that describe a +superset of the features supported by the system. + 5. The kvm_run structure ======================== diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst index e84848432158..7f231c724e16 100644 --- a/Documentation/virt/kvm/arm/index.rst +++ b/Documentation/virt/kvm/arm/index.rst @@ -11,3 +11,4 @@ ARM hypercalls pvtime ptp_kvm + vcpu-features diff --git a/Documentation/virt/kvm/arm/vcpu-features.rst b/Documentation/virt/kvm/arm/vcpu-features.rst new file mode 100644 index 000000000000..f7cc6d8d8b74 --- /dev/null +++ b/Documentation/virt/kvm/arm/vcpu-features.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +vCPU feature selection on arm64 +=============================== + +KVM/arm64 provides two mechanisms that allow userspace to configure +the CPU features presented to the guest. + +KVM_ARM_VCPU_INIT +================= + +The ``KVM_ARM_VCPU_INIT`` ioctl accepts a bitmap of feature flags +(``struct kvm_vcpu_init::features``). Features enabled by this interface are +*opt-in* and may change/extend UAPI. See :ref:`KVM_ARM_VCPU_INIT` for complete +documentation of the features controlled by the ioctl. + +Otherwise, all CPU features supported by KVM are described by the architected +ID registers. + +The ID Registers +================ + +The Arm architecture specifies a range of *ID Registers* that describe the set +of architectural features supported by the CPU implementation. KVM initializes +the guest's ID registers to the maximum set of CPU features supported by the +system. The ID register values may be VM-scoped in KVM, meaning that the +values could be shared for all vCPUs in a VM. + +KVM allows userspace to *opt-out* of certain CPU features described by the ID +registers by writing values to them via the ``KVM_SET_ONE_REG`` ioctl. The ID +registers are mutable until the VM has started, i.e. userspace has called +``KVM_RUN`` on at least one vCPU in the VM. Userspace can discover what fields +are mutable in the ID registers using the ``KVM_ARM_GET_REG_WRITABLE_MASKS``. +See the :ref:`ioctl documentation <KVM_ARM_GET_REG_WRITABLE_MASKS>` for more +details. + +Userspace is allowed to *limit* or *mask* CPU features according to the rules +outlined by the architecture in DDI0487J.a D19.1.3 'Principles of the ID +scheme for fields in ID register'. KVM does not allow ID register values that +exceed the capabilities of the system. + +.. warning:: + It is **strongly recommended** that userspace modify the ID register values + before accessing the rest of the vCPU's CPU register state. KVM may use the + ID register values to control feature emulation. Interleaving ID register + modification with other system register accesses may lead to unpredictable + behavior. diff --git a/Documentation/virt/kvm/devices/arm-vgic-v3.rst b/Documentation/virt/kvm/devices/arm-vgic-v3.rst index 51e5e5762571..5817edb4e046 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-v3.rst +++ b/Documentation/virt/kvm/devices/arm-vgic-v3.rst @@ -59,6 +59,13 @@ Groups: It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes. + Note that to obtain reproducible results (the same VCPU being associated + with the same redistributor across a save/restore operation), VCPU creation + order, redistributor region creation order as well as the respective + interleaves of VCPU and region creation MUST be preserved. Any change in + either ordering may result in a different vcpu_id/redistributor association, + resulting in a VM that will fail to run at restore time. + Errors: ======= ============================================================= diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst index d47595b33fcf..2b3b6d442302 100644 --- a/Documentation/virt/kvm/x86/mmu.rst +++ b/Documentation/virt/kvm/x86/mmu.rst @@ -202,10 +202,22 @@ Shadow pages contain the following information: Is 1 if the MMU instance cannot use A/D bits. EPT did not have A/D bits before Haswell; shadow EPT page tables also cannot use A/D bits if the L1 hypervisor does not enable them. + role.guest_mode: + Indicates the shadow page is created for a nested guest. role.passthrough: The page is not backed by a guest page table, but its first entry points to one. This is set if NPT uses 5-level page tables (host CR4.LA57=1) and is shadowing L1's 4-level NPT (L1 CR4.LA57=0). + mmu_valid_gen: + The MMU generation of this page, used to fast zap of all MMU pages within a + VM without blocking vCPUs too long. Specifically, KVM updates the per-VM + valid MMU generation which causes the mismatch of mmu_valid_gen for each mmu + page. This makes all existing MMU pages obsolete. Obsolete pages can't be + used. Therefore, vCPUs must load a new, valid root before re-entering the + guest. The MMU generation is only ever '0' or '1'. Note, the TDP MMU doesn't + use this field as non-root TDP MMU pages are reachable only from their + owning root. Thus it suffices for TDP MMU to use role.invalid in root pages + to invalidate all MMU pages. gfn: Either the guest page table containing the translations shadowed by this page, or the base page frame for linear translations. See role.direct. @@ -219,21 +231,30 @@ Shadow pages contain the following information: at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. The spt array forms a DAG structure with the shadow page as a node, and guest pages as leaves. - gfns: - An array of 512 guest frame numbers, one for each present pte. Used to - perform a reverse map from a pte to a gfn. When role.direct is set, any - element of this array can be calculated from the gfn field when used, in - this case, the array of gfns is not allocated. See role.direct and gfn. - root_count: - A counter keeping track of how many hardware registers (guest cr3 or - pdptrs) are now pointing at the page. While this counter is nonzero, the - page cannot be destroyed. See role.invalid. + shadowed_translation: + An array of 512 shadow translation entries, one for each present pte. Used + to perform a reverse map from a pte to a gfn as well as its access + permission. When role.direct is set, the shadow_translation array is not + allocated. This is because the gfn contained in any element of this array + can be calculated from the gfn field when used. In addition, when + role.direct is set, KVM does not track access permission for each of the + gfn. See role.direct and gfn. + root_count / tdp_mmu_root_count: + root_count is a reference counter for root shadow pages in Shadow MMU. + vCPUs elevate the refcount when getting a shadow page that will be used as + a root page, i.e. page that will be loaded into hardware directly (CR3, + PDPTRs, nCR3 EPTP). Root pages cannot be destroyed while their refcount is + non-zero. See role.invalid. tdp_mmu_root_count is similar but exclusively + used in TDP MMU as an atomic refcount. parent_ptes: The reverse mapping for the pte/ptes pointing at this page's spt. If parent_ptes bit 0 is zero, only one spte points at this page and parent_ptes points at this single spte, otherwise, there exists multiple sptes pointing at this page and (parent_ptes & ~0x1) points at a data structure with a list of parent sptes. + ptep: + The kernel virtual address of the SPTE that points at this shadow page. + Used exclusively by the TDP MMU, this field is a union with parent_ptes. unsync: If true, then the translations in this page may not match the guest's translation. This is equivalent to the state of the tlb when a pte is @@ -261,6 +282,10 @@ Shadow pages contain the following information: since the last time the page table was actually used; if emulation is triggered too frequently on this page, KVM will unmap the page to avoid emulation in the future. + tdp_mmu_page: + Is 1 if the shadow page is a TDP MMU page. This variable is used to + bifurcate the control flows for KVM when walking any data structure that + may contain pages from both TDP MMU and shadow MMU. Reverse map =========== |
