diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2025-01-27 16:51:51 -0800 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2025-01-27 16:51:51 -0800 |
| commit | 13845bdc869f136f92ad3d40ea09b867bb4ce467 (patch) | |
| tree | a2f503e60579cee485c2d0de06ad4bcb8abb7612 /Documentation | |
| parent | Merge tag 'staging-6.14-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git... (diff) | |
| parent | ntsync: Fix reference leaks in the remaining create ioctls. (diff) | |
| download | linux-13845bdc869f136f92ad3d40ea09b867bb4ce467.tar.gz linux-13845bdc869f136f92ad3d40ea09b867bb4ce467.zip | |
Merge tag 'char-misc-6.14-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc
Pull Char/Misc/IIO driver updates from Greg KH:
"Here is the "big" set of char/misc/iio and other smaller driver
subsystem updates for 6.14-rc1. Loads of different things in here this
development cycle, highlights are:
- ntsync "driver" to handle Windows locking types enabling Wine to
work much better on many workloads (i.e. games). The driver
framework was in 6.13, but now it's enabled and fully working
properly. Should make many SteamOS users happy. Even comes with
tests!
- Large IIO driver updates and bugfixes
- FPGA driver updates
- Coresight driver updates
- MHI driver updates
- PPS driver updatesa
- const bin_attribute reworking for many drivers
- binder driver updates
- smaller driver updates and fixes
All of these have been in linux-next for a while with no reported
issues"
* tag 'char-misc-6.14-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc: (311 commits)
ntsync: Fix reference leaks in the remaining create ioctls.
spmi: hisi-spmi-controller: Drop duplicated OF node assignment in spmi_controller_probe()
spmi: Set fwnode for spmi devices
ntsync: fix a file reference leak in drivers/misc/ntsync.c
scripts/tags.sh: Don't tag usages of DECLARE_BITMAP
dt-bindings: interconnect: qcom,msm8998-bwmon: Add SM8750 CPU BWMONs
dt-bindings: interconnect: OSM L3: Document sm8650 OSM L3 compatible
dt-bindings: interconnect: qcom-bwmon: Document QCS615 bwmon compatibles
interconnect: sm8750: Add missing const to static qcom_icc_desc
memstick: core: fix kernel-doc notation
intel_th: core: fix kernel-doc warnings
binder: log transaction code on failure
iio: dac: ad3552r-hs: clear reset status flag
iio: dac: ad3552r-common: fix ad3541/2r ranges
iio: chemical: bme680: Fix uninitialized variable in __bme680_read_raw()
misc: fastrpc: Fix copy buffer page size
misc: fastrpc: Fix registered buffer page address
misc: fastrpc: Deregister device nodes properly in error scenarios
nvmem: core: improve range check for nvmem_cell_write()
nvmem: qcom-spmi-sdam: Set size in struct nvmem_config
...
Diffstat (limited to 'Documentation')
45 files changed, 1310 insertions, 220 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-dummy-source b/Documentation/ABI/testing/sysfs-bus-coresight-devices-dummy-source new file mode 100644 index 000000000000..0830661ef656 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-dummy-source @@ -0,0 +1,15 @@ +What: /sys/bus/coresight/devices/dummy_source<N>/enable_source +Date: Dec 2024 +KernelVersion: 6.14 +Contact: Mao Jinlong <quic_jinlmao@quicinc.com> +Description: (RW) Enable/disable tracing of dummy source. A sink should be activated + before enabling the source. The path of coresight components linking + the source to the sink is configured and managed automatically by the + coresight framework. + +What: /sys/bus/coresight/devices/dummy_source<N>/traceid +Date: Dec 2024 +KernelVersion: 6.14 +Contact: Mao Jinlong <quic_jinlmao@quicinc.com> +Description: (R) Show the trace ID that will appear in the trace stream + coming from this trace entity. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index f83bd6829285..25d366d452a5 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -168,18 +168,6 @@ Description: is required is a consistent labeling. Units after application of scale and offset are millivolts. -What: /sys/bus/iio/devices/iio:deviceX/in_currentY_raw -What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_raw -KernelVersion: 3.17 -Contact: linux-iio@vger.kernel.org -Description: - Raw (unscaled no bias removal etc.) current measurement from - channel Y. In special cases where the channel does not - correspond to externally available input one of the named - versions may be used. The number must always be specified and - unique to allow association with event codes. Units after - application of scale and offset are milliamps. - What: /sys/bus/iio/devices/iio:deviceX/in_powerY_raw KernelVersion: 4.5 Contact: linux-iio@vger.kernel.org @@ -227,7 +215,7 @@ Description: same scaling as _raw. What: /sys/bus/iio/devices/iio:deviceX/in_temp_raw -What: /sys/bus/iio/devices/iio:deviceX/in_tempX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_tempY_raw What: /sys/bus/iio/devices/iio:deviceX/in_temp_x_raw What: /sys/bus/iio/devices/iio:deviceX/in_temp_y_raw What: /sys/bus/iio/devices/iio:deviceX/in_temp_ambient_raw @@ -416,11 +404,11 @@ Contact: linux-iio@vger.kernel.org Description: Scaled humidity measurement in milli percent. -What: /sys/bus/iio/devices/iio:deviceX/in_X_mean_raw +What: /sys/bus/iio/devices/iio:deviceX/in_Y_mean_raw KernelVersion: 3.5 Contact: linux-iio@vger.kernel.org Description: - Averaged raw measurement from channel X. The number of values + Averaged raw measurement from channel Y. The number of values used for averaging is device specific. The converting rules for normal raw values also applies to the averaged raw values. @@ -448,7 +436,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_offset What: /sys/bus/iio/devices/iio:deviceX/in_magn_offset What: /sys/bus/iio/devices/iio:deviceX/in_rot_offset What: /sys/bus/iio/devices/iio:deviceX/in_angl_offset -What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceX_offset +What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceY_offset KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -508,6 +496,9 @@ 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 What: /sys/bus/iio/devices/iio:deviceX/in_intensity_z_scale +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_red_scale +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_green_scale +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_blue_scale What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_scale KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org @@ -660,10 +651,10 @@ What: /sys/.../iio:deviceX/in_magn_scale_available What: /sys/.../iio:deviceX/in_illuminance_scale_available What: /sys/.../iio:deviceX/in_intensity_scale_available What: /sys/.../iio:deviceX/in_proximity_scale_available -What: /sys/.../iio:deviceX/in_voltageX_scale_available +What: /sys/.../iio:deviceX/in_voltageY_scale_available What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available -What: /sys/.../iio:deviceX/out_voltageX_scale_available -What: /sys/.../iio:deviceX/out_altvoltageX_scale_available +What: /sys/.../iio:deviceX/out_voltageY_scale_available +What: /sys/.../iio:deviceX/out_altvoltageY_scale_available What: /sys/.../iio:deviceX/in_capacitance_scale_available What: /sys/.../iio:deviceX/in_pressure_scale_available What: /sys/.../iio:deviceX/in_pressureY_scale_available @@ -681,6 +672,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_intensity_red_hardwaregain What: /sys/bus/iio/devices/iio:deviceX/in_intensity_green_hardwaregain What: /sys/bus/iio/devices/iio:deviceX/in_intensity_blue_hardwaregain What: /sys/bus/iio/devices/iio:deviceX/in_intensity_clear_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_hardwaregain KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: @@ -1562,7 +1554,7 @@ Description: This attribute is used to read the amount of quadrature error present in the device at a given time. -What: /sys/.../iio:deviceX/in_accelX_power_mode +What: /sys/.../iio:deviceX/in_accelY_power_mode KernelVersion: 3.11 Contact: linux-iio@vger.kernel.org Description: @@ -1633,6 +1625,10 @@ What: /sys/.../iio:deviceX/in_intensityY_uv_raw What: /sys/.../iio:deviceX/in_intensityY_uva_raw What: /sys/.../iio:deviceX/in_intensityY_uvb_raw What: /sys/.../iio:deviceX/in_intensityY_duv_raw +What: /sys/.../iio:deviceX/in_intensity_red_raw +What: /sys/.../iio:deviceX/in_intensity_green_raw +What: /sys/.../iio:deviceX/in_intensity_blue_raw +What: /sys/.../iio:deviceX/in_intensity_clear_raw KernelVersion: 3.4 Contact: linux-iio@vger.kernel.org Description: @@ -1691,16 +1687,19 @@ Description: Raw value of rotation from true/magnetic north measured with or without compensation from tilt sensors. -What: /sys/bus/iio/devices/iio:deviceX/in_currentX_raw -What: /sys/bus/iio/devices/iio:deviceX/in_currentX_i_raw -What: /sys/bus/iio/devices/iio:deviceX/in_currentX_q_raw -KernelVersion: 3.18 +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_raw +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_raw +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_i_raw +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_q_raw +KernelVersion: 3.17 Contact: linux-iio@vger.kernel.org Description: - Raw current measurement from channel X. Units are in milliamps + Raw current measurement from channel Y. Units are in milliamps after application of scale and offset. If no offset or scale is present, output should be considered as processed with the - unit in milliamps. + unit in milliamps. In special cases where the channel does not + correspond to externally available input one of the named + versions may be used. Channels with 'i' and 'q' modifiers always exist in pairs and both channels refer to the same signal. The 'i' channel contains the in-phase @@ -1864,9 +1863,9 @@ Description: hardware fifo watermark level. What: /sys/bus/iio/devices/iio:deviceX/in_temp_calibemissivity -What: /sys/bus/iio/devices/iio:deviceX/in_tempX_calibemissivity +What: /sys/bus/iio/devices/iio:deviceX/in_tempY_calibemissivity What: /sys/bus/iio/devices/iio:deviceX/in_temp_object_calibemissivity -What: /sys/bus/iio/devices/iio:deviceX/in_tempX_object_calibemissivity +What: /sys/bus/iio/devices/iio:deviceX/in_tempY_object_calibemissivity KernelVersion: 4.1 Contact: linux-iio@vger.kernel.org Description: @@ -1887,17 +1886,17 @@ Description: is considered as one sample for <type>[_name]_sampling_frequency. What: /sys/bus/iio/devices/iio:deviceX/in_concentration_raw -What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_raw -What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_co2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_co2_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentration_ethanol_raw -What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_ethanol_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_ethanol_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentration_h2_raw -What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_h2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_h2_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentration_o2_raw -What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_o2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_o2_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentration_voc_raw -What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_voc_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationY_voc_raw KernelVersion: 4.3 Contact: linux-iio@vger.kernel.org Description: @@ -1905,9 +1904,9 @@ Description: after application of scale and offset are percents. What: /sys/bus/iio/devices/iio:deviceX/in_resistance_raw -What: /sys/bus/iio/devices/iio:deviceX/in_resistanceX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_resistanceY_raw What: /sys/bus/iio/devices/iio:deviceX/out_resistance_raw -What: /sys/bus/iio/devices/iio:deviceX/out_resistanceX_raw +What: /sys/bus/iio/devices/iio:deviceX/out_resistanceY_raw KernelVersion: 4.3 Contact: linux-iio@vger.kernel.org Description: @@ -2096,7 +2095,7 @@ Description: One of the following thermocouple types: B, E, J, K, N, R, S, T. What: /sys/bus/iio/devices/iio:deviceX/in_temp_object_calibambient -What: /sys/bus/iio/devices/iio:deviceX/in_tempX_object_calibambient +What: /sys/bus/iio/devices/iio:deviceX/in_tempY_object_calibambient KernelVersion: 5.10 Contact: linux-iio@vger.kernel.org Description: @@ -2172,9 +2171,9 @@ Description: - a range specified as "[min step max]" -What: /sys/bus/iio/devices/iio:deviceX/in_voltageX_sampling_frequency +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sampling_frequency What: /sys/bus/iio/devices/iio:deviceX/in_powerY_sampling_frequency -What: /sys/bus/iio/devices/iio:deviceX/in_currentZ_sampling_frequency +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_sampling_frequency KernelVersion: 5.20 Contact: linux-iio@vger.kernel.org Description: diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad-sigma-delta b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad-sigma-delta new file mode 100644 index 000000000000..a5a8a579f4f3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad-sigma-delta @@ -0,0 +1,23 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sys_calibration +KernelVersion: 5.5 +Contact: linux-iio@vger.kernel.org +Description: + This attribute, if available, initiates the system calibration procedure. This is done on a + single channel at a time. Write '1' to start the calibration. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sys_calibration_mode_available +KernelVersion: 5.5 +Contact: linux-iio@vger.kernel.org +Description: + This attribute, if available, returns a list with the possible calibration modes. + There are two available options: + "zero_scale" - calibrate to zero scale + "full_scale" - calibrate to full scale + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sys_calibration_mode +KernelVersion: 5.5 +Contact: linux-iio@vger.kernel.org +Description: + This attribute, if available, sets up the calibration mode used in the system calibration + procedure. Reading returns the current calibration mode. + Writing sets the system calibration mode. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192 b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192 index f8315202c8f0..28be1cabf112 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192 +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192 @@ -19,33 +19,9 @@ Description: the bridge can be disconnected (when it is not being used using the bridge_switch_en attribute. -What: /sys/bus/iio/devices/iio:deviceX/in_voltagex_sys_calibration -KernelVersion: -Contact: linux-iio@vger.kernel.org -Description: - Initiates the system calibration procedure. This is done on a - single channel at a time. Write '1' to start the calibration. - What: /sys/bus/iio/devices/iio:deviceX/in_voltage2-voltage2_shorted_raw KernelVersion: Contact: linux-iio@vger.kernel.org Description: Measure voltage from AIN2 pin connected to AIN(+) and AIN(-) shorted. - -What: /sys/bus/iio/devices/iio:deviceX/in_voltagex_sys_calibration_mode_available -KernelVersion: -Contact: linux-iio@vger.kernel.org -Description: - Reading returns a list with the possible calibration modes. - There are two available options: - "zero_scale" - calibrate to zero scale - "full_scale" - calibrate to full scale - -What: /sys/bus/iio/devices/iio:deviceX/in_voltagex_sys_calibration_mode -KernelVersion: -Contact: linux-iio@vger.kernel.org -Description: - Sets up the calibration mode used in the system calibration - procedure. Reading returns the current calibration mode. - Writing sets the system calibration mode. diff --git a/Documentation/ABI/testing/sysfs-pps-gen b/Documentation/ABI/testing/sysfs-pps-gen new file mode 100644 index 000000000000..2519207b88fd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-pps-gen @@ -0,0 +1,43 @@ +What: /sys/class/pps-gen/ +Date: February 2025 +KernelVersion: 6.13 +Contact: Rodolfo Giometti <giometti@enneenne.com> +Description: + The /sys/class/pps-gen/ directory contains files and + directories that provide a unified interface to the PPS + generators. + +What: /sys/class/pps-gen/pps-genX/ +Date: February 2025 +KernelVersion: 6.13 +Contact: Rodolfo Giometti <giometti@enneenne.com> +Description: + The /sys/class/pps-gen/pps-genX/ directory is related to X-th + PPS generator in the system. Each directory contain files to + manage and control its PPS generator. + +What: /sys/class/pps-gen/pps-genX/enable +Date: February 2025 +KernelVersion: 6.13 +Contact: Rodolfo Giometti <giometti@enneenne.com> +Description: + This write-only file enables or disables generation of the + PPS signal. + +What: /sys/class/pps-gen/pps-genX/system +Date: February 2025 +KernelVersion: 6.13 +Contact: Rodolfo Giometti <giometti@enneenne.com> +Description: + This read-only file returns "1" if the generator takes the + timing from the system clock, while it returns "0" if not + (i.e. from a peripheral device clock). + +What: /sys/class/pps-gen/pps-genX/time +Date: February 2025 +KernelVersion: 6.13 +Contact: Rodolfo Giometti <giometti@enneenne.com> +Description: + This read-only file contains the current time stored into the + generator clock as two integers representing the current time + seconds and nanoseconds. diff --git a/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml b/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml index 04a8c37b4aff..742dc4e25d3b 100644 --- a/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml +++ b/Documentation/devicetree/bindings/arm/arm,coresight-dummy-source.yaml @@ -38,6 +38,12 @@ properties: enum: - arm,coresight-dummy-source + arm,static-trace-id: + description: If dummy source needs static id support, use this to set trace id. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 111 + out-ports: $ref: /schemas/graph.yaml#/properties/ports diff --git a/Documentation/devicetree/bindings/arm/arm,coresight-static-replicator.yaml b/Documentation/devicetree/bindings/arm/arm,coresight-static-replicator.yaml index 1892a091ac35..a6f793ea03b6 100644 --- a/Documentation/devicetree/bindings/arm/arm,coresight-static-replicator.yaml +++ b/Documentation/devicetree/bindings/arm/arm,coresight-static-replicator.yaml @@ -45,7 +45,22 @@ properties: patternProperties: '^port@[01]$': description: Output connections to CoreSight Trace bus - $ref: /schemas/graph.yaml#/properties/port + $ref: /schemas/graph.yaml#/$defs/port-base + unevaluatedProperties: false + + properties: + endpoint: + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false + + properties: + filter-source: + $ref: /schemas/types.yaml#/definitions/phandle + description: + phandle to the coresight trace source device matching the + hard coded filtering for this port + + remote-endpoint: true required: - compatible @@ -72,6 +87,7 @@ examples: reg = <0>; replicator_out_port0: endpoint { remote-endpoint = <&etb_in_port>; + filter-source = <&tpdm_video>; }; }; @@ -79,6 +95,7 @@ examples: reg = <1>; replicator_out_port1: endpoint { remote-endpoint = <&tpiu_in_port>; + filter-source = <&tpdm_mdss>; }; }; }; diff --git a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml index 280ed479ef5a..84d949392012 100644 --- a/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml +++ b/Documentation/devicetree/bindings/iio/accel/adi,adxl345.yaml @@ -37,10 +37,17 @@ properties: interrupts: maxItems: 1 + interrupt-names: + items: + - enum: [INT1, INT2] + +dependencies: + interrupts: [ interrupt-names ] + interrupt-names: [ interrupts ] + required: - compatible - reg - - interrupts allOf: - $ref: /schemas/spi/spi-peripheral-props.yaml# @@ -61,6 +68,7 @@ examples: reg = <0x2a>; interrupt-parent = <&gpio0>; interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "INT1"; }; }; - | @@ -79,5 +87,6 @@ examples: spi-cpha; interrupt-parent = <&gpio0>; interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "INT2"; }; }; diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml b/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml index 66ea894dbe55..f07c70e51c45 100644 --- a/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kx022a.yaml @@ -4,23 +4,26 @@ $id: http://devicetree.org/schemas/iio/accel/kionix,kx022a.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: ROHM/Kionix KX022A, KX132-1211 and KX132ACR-LBZ Accelerometers +title: ROHM/Kionix KX022A, KX132/134-1211 and KX132/134ACR-LBZ Accelerometers maintainers: - Matti Vaittinen <mazziesaccount@gmail.com> description: | 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. + +/- 2G, 4G, 8G and 16G ranges. The KX134ACR-LBZ and KX134-1211 support + +/- 8G, 16G, 32G and 64G. All the sensors also have variable output + data-rates and a hardware-fifo buffering. These accelerometers can be + accessed either via I2C or SPI. properties: compatible: enum: - kionix,kx022a - kionix,kx132-1211 + - kionix,kx134-1211 - rohm,kx132acr-lbz + - rohm,kx134acr-lbz reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml b/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml index 783c7ddfcd90..c175f4c4cbdb 100644 --- a/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml +++ b/Documentation/devicetree/bindings/iio/accel/nxp,fxls8962af.yaml @@ -14,12 +14,20 @@ description: | SPI and I2C interface. https://www.nxp.com/docs/en/data-sheet/FXLS8962AF.pdf https://www.nxp.com/docs/en/data-sheet/FXLS8964AF.pdf + https://www.nxp.com/docs/en/data-sheet/FXLS8967AF.pdf + https://www.nxp.com/docs/en/data-sheet/FXLS8974CF.pdf properties: compatible: - enum: - - nxp,fxls8962af - - nxp,fxls8964af + oneOf: + - enum: + - nxp,fxls8962af + - nxp,fxls8964af + - items: + - enum: + - nxp,fxls8967af + - nxp,fxls8974cf + - const: nxp,fxls8962af reg: maxItems: 1 @@ -38,6 +46,11 @@ properties: drive-open-drain: type: boolean + wakeup-source: + $ref: /schemas/types.yaml#/definitions/flag + description: + Enable wake on accelerometer event + required: - compatible - reg @@ -61,6 +74,7 @@ examples: interrupt-parent = <&gpio0>; interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "INT1"; + wakeup-source; }; }; - | diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml index e413a9d8d2a2..96e01a97dd95 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4000.yaml @@ -19,49 +19,82 @@ description: | https://www.analog.com/media/en/technical-documentation/data-sheets/ad4020-4021-4022.pdf https://www.analog.com/media/en/technical-documentation/data-sheets/adaq4001.pdf https://www.analog.com/media/en/technical-documentation/data-sheets/adaq4003.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7685.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7686.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7687.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7688.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7690.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7691.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7693.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7942.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7946.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7980.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7982.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7983.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7984.pdf + https://www.analog.com/media/en/technical-documentation/data-sheets/ad7988-1_7988-5.pdf $ref: /schemas/spi/spi-peripheral-props.yaml# properties: compatible: oneOf: - - const: adi,ad4000 + - enum: + - adi,ad4000 + - adi,ad4001 + - adi,ad4002 + - adi,ad4003 + - adi,ad4020 + - adi,adaq4001 + - adi,adaq4003 + - adi,ad7687 + - adi,ad7691 + - adi,ad7942 + - adi,ad7946 + - adi,ad7983 - items: - enum: - adi,ad4004 - adi,ad4008 - const: adi,ad4000 - - - const: adi,ad4001 - items: - enum: - adi,ad4005 - const: adi,ad4001 - - - const: adi,ad4002 - items: - enum: - adi,ad4006 - adi,ad4010 - const: adi,ad4002 - - - const: adi,ad4003 - items: - enum: - adi,ad4007 - adi,ad4011 - const: adi,ad4003 - - - const: adi,ad4020 - items: - enum: - adi,ad4021 - adi,ad4022 - const: adi,ad4020 - - - const: adi,adaq4001 - - - const: adi,adaq4003 + - items: + - enum: + - adi,ad7685 + - adi,ad7686 + - adi,ad7980 + - adi,ad7988-1 + - adi,ad7988-5 + - const: adi,ad7983 + - items: + - enum: + - adi,ad7688 + - adi,ad7693 + - const: adi,ad7687 + - items: + - enum: + - adi,ad7690 + - adi,ad7982 + - adi,ad7984 + - const: adi,ad7691 reg: maxItems: 1 @@ -133,6 +166,22 @@ required: - ref-supply allOf: + # Single-channel PulSAR devices have SDI either tied to VIO, GND, or host CS. + - if: + properties: + compatible: + contains: + enum: + - adi,ad7687 + - adi,ad7691 + - adi,ad7942 + - adi,ad7946 + - adi,ad7983 + then: + properties: + adi,sdi-pin: + enum: [ high, low, cs ] + default: cs # The configuration register can only be accessed if SDI is connected to MOSI - if: required: diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml index 310f046e139f..7d2229dee444 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad4695.yaml @@ -134,8 +134,9 @@ patternProperties: description: Describes the common mode channel for single channels. 0xFF is REFGND and OxFE is COM. Macros are available for these values in - dt-bindings/iio/adi,ad4695.h. Values 1 to 15 correspond to INx inputs. - Only odd numbered INx inputs can be used as common mode channels. + dt-bindings/iio/adc/adi,ad4695.h. Values 1 to 15 correspond to INx + inputs. Only odd numbered INx inputs can be used as common mode + channels. enum: [1, 3, 5, 7, 9, 11, 13, 15, 0xFE, 0xFF] default: 0xFF @@ -209,7 +210,7 @@ unevaluatedProperties: false examples: - | #include <dt-bindings/gpio/gpio.h> - #include <dt-bindings/iio/adi,ad4695.h> + #include <dt-bindings/iio/adc/adi,ad4695.h> spi { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml index 35ed04350e28..7146a654ae38 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.yaml @@ -37,6 +37,17 @@ properties: description: IRQ line for the ADC maxItems: 1 + rdy-gpios: + description: + GPIO reading the RÌ…DÌ…YÌ… line. Having such a GPIO is technically optional but + highly recommended because DOUT/RÌ…DÌ…YÌ… toggles during SPI transfers (in its + DOUT aka MISO role) and so usually triggers a spurious interrupt. The + distinction between such a spurious event and a real one can only be done + by reading such a GPIO. (There is a register telling the same + information, but accessing that one needs a SPI transfer which then + triggers another interrupt event.) + maxItems: 1 + '#address-cells': const: 1 @@ -111,6 +122,7 @@ unevaluatedProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> spi { #address-cells = <1>; #size-cells = <0>; @@ -121,6 +133,7 @@ examples: spi-max-frequency = <5000000>; interrupts = <25 2>; interrupt-parent = <&gpio>; + rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>; refin1-supply = <&adc_vref>; clocks = <&ad7124_mclk>; clock-names = "mclk"; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml index ad15cf9bc2ff..21ee319d4675 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7173.yaml @@ -135,6 +135,17 @@ properties: '#clock-cells': const: 0 + rdy-gpios: + description: + GPIO reading the RÌ…DÌ…YÌ… line. Having such a GPIO is technically optional but + highly recommended because DOUT/RÌ…DÌ…YÌ… toggles during SPI transfers (in its + DOUT aka MISO role) and so usually triggers a spurious interrupt. The + distinction between such a spurious event and a real one can only be done + by reading such a GPIO. (There is a register telling the same + information, but accessing that one needs a SPI transfer which then + triggers another interrupt event.) + maxItems: 1 + patternProperties: "^channel@[0-9a-f]$": type: object @@ -443,6 +454,7 @@ examples: interrupts = <25 IRQ_TYPE_EDGE_FALLING>; interrupt-names = "rdy"; interrupt-parent = <&gpio>; + rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>; spi-max-frequency = <5000000>; gpio-controller; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml index 66dd1c549bd3..0bd2c6906c83 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7192.yaml @@ -106,6 +106,17 @@ properties: description: see Documentation/devicetree/bindings/iio/adc/adc.yaml type: boolean + rdy-gpios: + description: + GPIO reading the RÌ…DÌ…YÌ… line. Having such a GPIO is technically optional but + highly recommended because DOUT/RÌ…DÌ…YÌ… toggles during SPI transfers (in its + DOUT aka MISO role) and so usually triggers a spurious interrupt. The + distinction between such a spurious event and a real one can only be done + by reading such a GPIO. (There is a register telling the same + information, but accessing that one needs a SPI transfer which then + triggers another interrupt event.) + maxItems: 1 + patternProperties: "^channel@[0-9a-f]+$": type: object @@ -181,6 +192,7 @@ unevaluatedProperties: false examples: - | + #include <dt-bindings/gpio/gpio.h> spi { #address-cells = <1>; #size-cells = <0>; @@ -195,6 +207,7 @@ examples: clock-names = "mclk"; interrupts = <25 0x2>; interrupt-parent = <&gpio>; + rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>; aincom-supply = <&aincom>; dvdd-supply = <&dvdd>; avdd-supply = <&avdd>; @@ -207,6 +220,7 @@ examples: }; }; - | + #include <dt-bindings/gpio/gpio.h> spi { #address-cells = <1>; #size-cells = <0>; @@ -224,6 +238,7 @@ examples: #clock-cells = <0>; interrupts = <25 0x2>; interrupt-parent = <&gpio>; + rdy-gpios = <&gpio 25 GPIO_ACTIVE_LOW>; aincom-supply = <&aincom>; dvdd-supply = <&dvdd>; avdd-supply = <&avdd>; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml index be2616ff9af6..5c8df45bfab0 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7780.yaml @@ -63,6 +63,17 @@ properties: marked GPIO_ACTIVE_LOW. maxItems: 1 + rdy-gpios: + description: + GPIO reading the RÌ…DÌ…YÌ… line. Having such a GPIO is technically optional but + highly recommended because DOUT/RÌ…DÌ…YÌ… toggles during SPI transfers (in its + DOUT aka MISO role) and so usually triggers a spurious interrupt. The + distinction between such a spurious event and a real one can only be done + by reading such a GPIO. (There is a register telling the same + information, but accessing that one needs a SPI transfer which then + triggers another interrupt event.) + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml index ba86c7b7d622..40341d541726 100644 --- a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml @@ -17,12 +17,15 @@ description: | properties: compatible: - items: - - enum: - - renesas,r9a07g043-adc # RZ/G2UL and RZ/Five - - renesas,r9a07g044-adc # RZ/G2L - - renesas,r9a07g054-adc # RZ/V2L - - const: renesas,rzg2l-adc + oneOf: + - items: + - enum: + - renesas,r9a07g043-adc # RZ/G2UL and RZ/Five + - renesas,r9a07g044-adc # RZ/G2L + - renesas,r9a07g054-adc # RZ/V2L + - const: renesas,rzg2l-adc + - items: + - const: renesas,r9a08g045-adc # RZ/G3S reg: maxItems: 1 @@ -57,6 +60,9 @@ properties: '#size-cells': const: 0 + "#io-channel-cells": + const: 1 + required: - compatible - reg @@ -68,7 +74,7 @@ required: - reset-names patternProperties: - "^channel@[0-7]$": + "^channel@[0-8]$": $ref: adc.yaml type: object description: | @@ -78,6 +84,8 @@ patternProperties: reg: description: | The channel number. + minimum: 0 + maximum: 8 required: - reg @@ -92,18 +100,25 @@ allOf: const: renesas,r9a07g043-adc then: patternProperties: - "^channel@[2-7]$": false + "^channel@[2-8]$": false "^channel@[0-1]$": properties: reg: - minimum: 0 maximum: 1 - else: + + - if: + properties: + compatible: + contains: + enum: + - renesas,r9a07g044-adc + - renesas,r9a07g054-adc + then: patternProperties: + "^channel@[8]$": false "^channel@[0-7]$": properties: reg: - minimum: 0 maximum: 7 additionalProperties: false diff --git a/Documentation/devicetree/bindings/iio/chemical/bosch,bme680.yaml b/Documentation/devicetree/bindings/iio/chemical/bosch,bme680.yaml new file mode 100644 index 000000000000..fe98ec44f081 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/bosch,bme680.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/chemical/bosch,bme680.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bosch BME680 Gas sensor + +maintainers: + - Vasileios Amoiridis <vassilisamir@gmail.com> + +description: > + BME680 is a gas sensor which combines relative humidity, barometric pressure, + ambient temperature and gas (VOC - Volatile Organic Compounds) measurements. + + https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme680-ds001.pdf + +properties: + compatible: + const: bosch,bme680 + + reg: + maxItems: 1 + + vdd-supply: true + vddio-supply: true + +required: + - compatible + - reg + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + co2-sensor@77 { + compatible = "bosch,bme680"; + reg = <0x77>; + vddio-supply = <&vddio>; + vdd-supply = <&vdd>; + }; + }; + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + co2-sensor@0 { + compatible = "bosch,bme680"; + reg = <0>; + spi-max-frequency = <500000>; + vddio-supply = <&vddio>; + vdd-supply = <&vdd>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml b/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml index 79cb4b78a88a..2bd89e0aa46b 100644 --- a/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml +++ b/Documentation/devicetree/bindings/iio/dac/adi,ad5791.yaml @@ -91,7 +91,7 @@ examples: vrefn-supply = <&dac_vrefn>; reset-gpios = <&gpio_bd 16 GPIO_ACTIVE_LOW>; clear-gpios = <&gpio_bd 17 GPIO_ACTIVE_LOW>; - ldac-gpios = <&gpio_bd 18 GPIO_ACTIVE_HIGH>; + ldac-gpios = <&gpio_bd 18 GPIO_ACTIVE_LOW>; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/dac/rohm,bd79703.yaml b/Documentation/devicetree/bindings/iio/dac/rohm,bd79703.yaml new file mode 100644 index 000000000000..941a49c93943 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/rohm,bd79703.yaml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2024 ROHM Semiconductor. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/dac/rohm,bd79703.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM BD79703 DAC device driver + +maintainers: + - Matti Vaittinen <mazziesaccount@gmail.com> + +description: | + The ROHM BD79703 is a 6 channel, 8-bit DAC. + Datasheet can be found here: + https://fscdn.rohm.com/en/products/databook/datasheet/ic/data_converter/dac/bd79702fv-lb_bd79703fv-lb-e.pdf + +properties: + compatible: + const: rohm,bd79703 + + reg: + maxItems: 1 + + spi-max-frequency: + maximum: 30000000 + + vfs-supply: + description: + The regulator to use as a full scale voltage. The voltage should be between 2.7V .. VCC + + vcc-supply: + description: + The regulator supplying the operating voltage. Should be between 2.7V ... 5.5V + +required: + - compatible + - reg + - spi-max-frequency + - vfs-supply + - vcc-supply + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +additionalProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + dac@0 { + compatible = "rohm,bd79703"; + reg = <0>; + spi-max-frequency = <30000000>; + vcc-supply = <&vcc>; + vfs-supply = <&vref>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml index e3eec38897bf..7a1a74fec281 100644 --- a/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml +++ b/Documentation/devicetree/bindings/iio/imu/adi,adis16480.yaml @@ -11,24 +11,30 @@ maintainers: properties: compatible: - enum: - - adi,adis16375 - - adi,adis16480 - - adi,adis16485 - - adi,adis16488 - - adi,adis16490 - - adi,adis16495-1 - - adi,adis16495-2 - - adi,adis16495-3 - - adi,adis16497-1 - - adi,adis16497-2 - - adi,adis16497-3 - - adi,adis16545-1 - - adi,adis16545-2 - - adi,adis16545-3 - - adi,adis16547-1 - - adi,adis16547-2 - - adi,adis16547-3 + oneOf: + - enum: + - adi,adis16375 + - adi,adis16480 + - adi,adis16485 + - adi,adis16486 + - adi,adis16488 + - adi,adis16489 + - adi,adis16490 + - adi,adis16495-1 + - adi,adis16495-2 + - adi,adis16495-3 + - adi,adis16497-1 + - adi,adis16497-2 + - adi,adis16497-3 + - adi,adis16545-1 + - adi,adis16545-2 + - adi,adis16545-3 + - adi,adis16547-1 + - adi,adis16547-2 + - adi,adis16547-3 + - items: + - const: adi,adis16487 + - const: adi,adis16485 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml index 3b0a2d8b2e91..2cf8a0c7eb4c 100644 --- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml +++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi160.yaml @@ -37,6 +37,7 @@ properties: to "INT2" if INT2 pin should be used instead drive-open-drain: + type: boolean description: | set if the specified interrupt pin should be configured as open drain. If not set, defaults to push-pull. diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml index 7b0cde1c9b0a..860a6c1fea3c 100644 --- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml +++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi270.yaml @@ -41,6 +41,7 @@ properties: - INT2 drive-open-drain: + type: boolean description: set if the specified interrupt pins should be configured as open drain. If not set, defaults to push-pull. diff --git a/Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml b/Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml index 64ef26e19669..7bf8294a8f2e 100644 --- a/Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml +++ b/Documentation/devicetree/bindings/iio/imu/bosch,bmi323.yaml @@ -38,6 +38,7 @@ properties: - INT2 drive-open-drain: + type: boolean description: set if the specified interrupt pin should be configured as open drain. If not set, defaults to push-pull. diff --git a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml index f91954870a44..0bce71529e34 100644 --- a/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml +++ b/Documentation/devicetree/bindings/iio/imu/invensense,mpu6050.yaml @@ -16,6 +16,7 @@ properties: compatible: oneOf: - enum: + - invensense,iam20380 - invensense,iam20680 - invensense,icm20608 - invensense,icm20609 diff --git a/Documentation/devicetree/bindings/iio/light/rohm,bu27008.yaml b/Documentation/devicetree/bindings/iio/light/rohm,bu27008.yaml deleted file mode 100644 index 4f66fd47b016..000000000000 --- a/Documentation/devicetree/bindings/iio/light/rohm,bu27008.yaml +++ /dev/null @@ -1,49 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/iio/light/rohm,bu27008.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: ROHM BU27008 color sensor - -maintainers: - - Matti Vaittinen <mazziesaccount@gmail.com> - -description: - The ROHM BU27008 is a sensor with 5 photodiodes (red, green, blue, clear - and IR) with four configurable channels. Red and green being always - available and two out of the rest three (blue, clear, IR) can be - selected to be simultaneously measured. Typical application is adjusting - LCD backlight of TVs, mobile phones and tablet PCs. - -properties: - compatible: - const: rohm,bu27008 - - reg: - maxItems: 1 - - interrupts: - maxItems: 1 - - vdd-supply: true - -required: - - compatible - - reg - -additionalProperties: false - -examples: - - | - i2c { - #address-cells = <1>; - #size-cells = <0>; - - light-sensor@38 { - compatible = "rohm,bu27008"; - reg = <0x38>; - }; - }; - -... diff --git a/Documentation/devicetree/bindings/iio/light/rohm,bu27010.yaml b/Documentation/devicetree/bindings/iio/light/rohm,bu27010.yaml deleted file mode 100644 index bed42d5d0d94..000000000000 --- a/Documentation/devicetree/bindings/iio/light/rohm,bu27010.yaml +++ /dev/null @@ -1,50 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/iio/light/rohm,bu27010.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: ROHM BU27010 color sensor - -maintainers: - - Matti Vaittinen <mazziesaccount@gmail.com> - -description: | - The ROHM BU27010 is a sensor with 6 photodiodes (red, green, blue, clear, - IR and flickering detection) with five configurable channels. Red, green - and flickering detection being always available and two out of the rest - three (blue, clear, IR) can be selected to be simultaneously measured. - Typical application is adjusting LCD/OLED backlight of TVs, mobile phones - and tablet PCs. - -properties: - compatible: - const: rohm,bu27010 - - reg: - maxItems: 1 - - interrupts: - maxItems: 1 - - vdd-supply: true - -required: - - compatible - - reg - - vdd-supply - -additionalProperties: false - -examples: - - | - i2c { - #address-cells = <1>; - #size-cells = <0>; - - light-sensor@38 { - compatible = "rohm,bu27010"; - reg = <0x38>; - vdd-supply = <&vdd>; - }; - }; diff --git a/Documentation/devicetree/bindings/iio/light/ti,opt4060.yaml b/Documentation/devicetree/bindings/iio/light/ti,opt4060.yaml new file mode 100644 index 000000000000..568fb2a9b7a3 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/ti,opt4060.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/light/ti,opt4060.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments OPT4060 RGBW Color Sensor + +maintainers: + - Per-Daniel Olsson <perdaniel.olsson@axis.com> + +description: + Texas Instrument RGBW high resolution color sensor over I2C. + https://www.ti.com/lit/gpn/opt4060 + +properties: + compatible: + enum: + - ti,opt4060 + + 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>; + + light-sensor@44 { + compatible = "ti,opt4060"; + reg = <0x44>; + vdd-supply = <&vdd_reg>; + interrupt-parent = <&gpio5>; + interrupts = <13 IRQ_TYPE_EDGE_FALLING>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml index cb201cecfa1a..706b7e24f182 100644 --- a/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/bmp085.yaml @@ -55,12 +55,16 @@ properties: If not set, defaults to push-pull configuration. type: boolean + spi-max-frequency: + maximum: 10000000 + required: - compatible - vddd-supply - vdda-supply allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# - if: properties: compatible: @@ -73,6 +77,16 @@ allOf: then: properties: interrupts: false + - if: + properties: + compatible: + contains: + enum: + - bosch,bmp085 + - bosch,bmp180 + then: + properties: + spi-max-frequency: false additionalProperties: false @@ -93,3 +107,18 @@ examples: vdda-supply = <&bar>; }; }; + - | + # include <dt-bindings/gpio/gpio.h> + # include <dt-bindings/interrupt-controller/irq.h> + spi { + #address-cells = <1>; + #size-cells = <0>; + pressure@0 { + compatible = "bosch,bmp280"; + reg = <0>; + spi-max-frequency = <10000000>; + reset-gpios = <&gpio0 26 GPIO_ACTIVE_LOW>; + vddd-supply = <&foo>; + vdda-supply = <&bar>; + }; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml index ff24b5ee2c66..83bcf0575cd3 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,msm8998-bwmon.yaml @@ -38,6 +38,7 @@ properties: - qcom,sm8250-cpu-bwmon - qcom,sm8550-cpu-bwmon - qcom,sm8650-cpu-bwmon + - qcom,sm8750-cpu-bwmon - qcom,x1e80100-cpu-bwmon - const: qcom,sdm845-bwmon # BWMON v4, unified register space - items: diff --git a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml index 21dae0b92819..4ac0863205b3 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,osm-l3.yaml @@ -33,6 +33,7 @@ properties: - qcom,sm6375-cpucp-l3 - qcom,sm8250-epss-l3 - qcom,sm8350-epss-l3 + - qcom,sm8650-epss-l3 - const: qcom,epss-l3 reg: diff --git a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml index 38e0d50f0e1c..d37f544ab8aa 100644 --- a/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml +++ b/Documentation/devicetree/bindings/nvmem/qcom,qfprom.yaml @@ -20,12 +20,14 @@ properties: - qcom,apq8064-qfprom - qcom,apq8084-qfprom - qcom,ipq5332-qfprom + - qcom,ipq5424-qfprom - qcom,ipq6018-qfprom - qcom,ipq8064-qfprom - qcom,ipq8074-qfprom - qcom,ipq9574-qfprom - qcom,msm8226-qfprom - qcom,msm8916-qfprom + - qcom,msm8917-qfprom - qcom,msm8974-qfprom - qcom,msm8976-qfprom - qcom,msm8996-qfprom @@ -33,6 +35,7 @@ properties: - qcom,qcm2290-qfprom - qcom,qcs404-qfprom - qcom,qcs615-qfprom + - qcom,qcs8300-qfprom - qcom,sc7180-qfprom - qcom,sc7280-qfprom - qcom,sc8280xp-qfprom diff --git a/Documentation/devicetree/bindings/nvmem/rmem.yaml b/Documentation/devicetree/bindings/nvmem/rmem.yaml index 1ec0d09bcafa..85f9f5de3906 100644 --- a/Documentation/devicetree/bindings/nvmem/rmem.yaml +++ b/Documentation/devicetree/bindings/nvmem/rmem.yaml @@ -16,6 +16,7 @@ properties: compatible: items: - enum: + - mobileye,eyeq5-bootloader-config - raspberrypi,bootloader-config - raspberrypi,bootloader-public-key - const: nvmem-rmem diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 7d07b08b1459..fadbd3c041c8 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -55,8 +55,6 @@ properties: - atmel,atsha204a # BPA-RS600: Power Supply - blutek,bpa-rs600 - # Bosch Sensortec pressure, temperature, humididty and VOC sensor - - bosch,bme680 # CM32181: Ambient Light Sensor - capella,cm32181 # CM3232: Ambient Light Sensor diff --git a/Documentation/devicetree/bindings/w1/maxim,ds2482.yaml b/Documentation/devicetree/bindings/w1/maxim,ds2482.yaml index 422becc6e1fa..fe6b3f9a3f8b 100644 --- a/Documentation/devicetree/bindings/w1/maxim,ds2482.yaml +++ b/Documentation/devicetree/bindings/w1/maxim,ds2482.yaml @@ -25,6 +25,8 @@ properties: reg: maxItems: 1 + vcc-supply: true + required: - compatible - reg diff --git a/Documentation/driver-api/extcon.rst b/Documentation/driver-api/extcon.rst new file mode 100644 index 000000000000..d3217b9cdcd5 --- /dev/null +++ b/Documentation/driver-api/extcon.rst @@ -0,0 +1,255 @@ +======================= +Extcon Device Subsystem +======================= + +Overview +======== + +The Extcon (External Connector) subsystem provides a unified framework for +managing external connectors in Linux systems. It allows drivers to report +the state of external connectors and provides a standardized interface for +userspace to query and monitor these states. + +Extcon is particularly useful in modern devices with multiple connectivity +options, such as smartphones, tablets, and laptops. It helps manage various +types of connectors, including: + +1. USB connectors (e.g., USB-C, micro-USB) +2. Charging ports (e.g., fast charging, wireless charging) +3. Audio jacks (e.g., 3.5mm headphone jack) +4. Video outputs (e.g., HDMI, DisplayPort) +5. Docking stations + +Real-world examples: + +1. Smartphone USB-C port: + A single USB-C port on a smartphone can serve multiple functions. Extcon + can manage the different states of this port, such as: + - USB data connection + - Charging (various types like fast charging, USB Power Delivery) + - Audio output (USB-C headphones) + - Video output (USB-C to HDMI adapter) + +2. Laptop docking station: + When a laptop is connected to a docking station, multiple connections are + made simultaneously. Extcon can handle the state changes for: + - Power delivery + - External displays + - USB hub connections + - Ethernet connectivity + +3. Wireless charging pad: + Extcon can manage the state of a wireless charging connection, allowing + the system to respond appropriately when a device is placed on or removed + from the charging pad. + +4. Smart TV HDMI ports: + In a smart TV, Extcon can manage multiple HDMI ports, detecting when + devices are connected or disconnected, and potentially identifying the + type of device (e.g., gaming console, set-top box, Blu-ray player). + +The Extcon framework simplifies the development of drivers for these complex +scenarios by providing a standardized way to report and query connector +states, handle mutually exclusive connections, and manage connector +properties. This allows for more robust and flexible handling of external +connections in modern devices. + +Key Components +============== + +extcon_dev +---------- + +The core structure representing an Extcon device:: + + struct extcon_dev { + const char *name; + const unsigned int *supported_cable; + const u32 *mutually_exclusive; + + /* Internal data */ + struct device dev; + unsigned int id; + struct raw_notifier_head nh_all; + struct raw_notifier_head *nh; + struct list_head entry; + int max_supported; + spinlock_t lock; + u32 state; + + /* Sysfs related */ + struct device_type extcon_dev_type; + struct extcon_cable *cables; + struct attribute_group attr_g_muex; + struct attribute **attrs_muex; + struct device_attribute *d_attrs_muex; + }; + +Key fields: + +- ``name``: Name of the Extcon device +- ``supported_cable``: Array of supported cable types +- ``mutually_exclusive``: Array defining mutually exclusive cable types + This field is crucial for enforcing hardware constraints. It's an array of + 32-bit unsigned integers, where each element represents a set of mutually + exclusive cable types. The array should be terminated with a 0. + + For example: + + :: + + static const u32 mutually_exclusive[] = { + BIT(0) | BIT(1), /* Cable 0 and 1 are mutually exclusive */ + BIT(2) | BIT(3) | BIT(4), /* Cables 2, 3, and 4 are mutually exclusive */ + 0 /* Terminator */ + }; + + In this example, cables 0 and 1 cannot be connected simultaneously, and + cables 2, 3, and 4 are also mutually exclusive. This is useful for + scenarios like a single port that can either be USB or HDMI, but not both + at the same time. + + The Extcon core uses this information to prevent invalid combinations of + cable states, ensuring that the reported states are always consistent + with the hardware capabilities. + +- ``state``: Current state of the device (bitmap of connected cables) + + +extcon_cable +------------ + +Represents an individual cable managed by an Extcon device:: + + struct extcon_cable { + struct extcon_dev *edev; + int cable_index; + struct attribute_group attr_g; + struct device_attribute attr_name; + struct device_attribute attr_state; + struct attribute *attrs[3]; + union extcon_property_value usb_propval[EXTCON_PROP_USB_CNT]; + union extcon_property_value chg_propval[EXTCON_PROP_CHG_CNT]; + union extcon_property_value jack_propval[EXTCON_PROP_JACK_CNT]; + union extcon_property_value disp_propval[EXTCON_PROP_DISP_CNT]; + DECLARE_BITMAP(usb_bits, EXTCON_PROP_USB_CNT); + DECLARE_BITMAP(chg_bits, EXTCON_PROP_CHG_CNT); + DECLARE_BITMAP(jack_bits, EXTCON_PROP_JACK_CNT); + DECLARE_BITMAP(disp_bits, EXTCON_PROP_DISP_CNT); + }; + +Core Functions +============== + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_get_state + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_set_state + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_set_state_sync + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_get_property + + +Sysfs Interface +=============== + +Extcon devices expose the following sysfs attributes: + +- ``name``: Name of the Extcon device +- ``state``: Current state of all supported cables +- ``cable.N/name``: Name of the Nth supported cable +- ``cable.N/state``: State of the Nth supported cable + +Usage Example +------------- + +.. code-block:: c + + #include <linux/module.h> + #include <linux/platform_device.h> + #include <linux/extcon.h> + + struct my_extcon_data { + struct extcon_dev *edev; + struct device *dev; + }; + + static const unsigned int my_extcon_cable[] = { + EXTCON_USB, + EXTCON_USB_HOST, + EXTCON_NONE, + }; + + static int my_extcon_probe(struct platform_device *pdev) + { + struct my_extcon_data *data; + int ret; + + data = devm_kzalloc(&pdev->dev, sizeof(*data), GFP_KERNEL); + if (!data) + return -ENOMEM; + + data->dev = &pdev->dev; + + /* Initialize extcon device */ + data->edev = devm_extcon_dev_allocate(data->dev, my_extcon_cable); + if (IS_ERR(data->edev)) { + dev_err(data->dev, "Failed to allocate extcon device\n"); + return PTR_ERR(data->edev); + } + + /* Register extcon device */ + ret = devm_extcon_dev_register(data->dev, data->edev); + if (ret < 0) { + dev_err(data->dev, "Failed to register extcon device\n"); + return ret; + } + + platform_set_drvdata(pdev, data); + + /* Example: Set initial state */ + extcon_set_state_sync(data->edev, EXTCON_USB, true); + + dev_info(data->dev, "My extcon driver probed successfully\n"); + return 0; + } + + static int my_extcon_remove(struct platform_device *pdev) + { + struct my_extcon_data *data = platform_get_drvdata(pdev); + + /* Example: Clear state before removal */ + extcon_set_state_sync(data->edev, EXTCON_USB, false); + + dev_info(data->dev, "My extcon driver removed\n"); + return 0; + } + + static const struct of_device_id my_extcon_of_match[] = { + { .compatible = "my,extcon-device", }, + { }, + }; + MODULE_DEVICE_TABLE(of, my_extcon_of_match); + + static struct platform_driver my_extcon_driver = { + .driver = { + .name = "my-extcon-driver", + .of_match_table = my_extcon_of_match, + }, + .probe = my_extcon_probe, + .remove = my_extcon_remove, + }; + + module_platform_driver(my_extcon_driver); + +This example demonstrates: +--------------------------- + +- Defining supported cable types (USB and USB Host in this case). +- Allocating and registering an extcon device. +- Setting an initial state for a cable (USB connected in this example). +- Clearing the state when the driver is removed. diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 7f83e05769b4..16e2c4ec3c01 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -86,6 +86,7 @@ Subsystem-specific APIs dmaengine/index dpll edac + extcon firmware/index fpga/index frame-buffer diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst index 78dded03e5d8..71ad04c82d6c 100644 --- a/Documentation/driver-api/pps.rst +++ b/Documentation/driver-api/pps.rst @@ -202,6 +202,46 @@ 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. +To do so the class pps-gen has been added. PPS generators can be +registered in the kernel by defining a struct pps_gen_source_info as +follows:: + + static struct pps_gen_source_info pps_gen_dummy_info = { + .name = "dummy", + .use_system_clock = true, + .get_time = pps_gen_dummy_get_time, + .enable = pps_gen_dummy_enable, + }; + +Where the use_system_clock states if the generator uses the system +clock to generate its pulses, or they are from a peripheral device +clock. Method get_time() is used to query the time stored into the +generator clock, while the method enable() is used to enable or +disable the PPS pulse generation. + +Then calling the function pps_gen_register_source() in your +initialization routine as follows creates a new generator in the +system:: + + pps_gen = pps_gen_register_source(&pps_gen_dummy_info); + +Generators SYSFS support +------------------------ + +If the SYSFS filesystem is enabled in the kernel it provides a new class:: + + $ ls /sys/class/pps-gen/ + pps-gen0/ pps-gen1/ pps-gen2/ + +Every directory is the ID of a PPS generator defined in the system and +inside of it you find several files:: + + $ ls -F /sys/class/pps-gen/pps-gen0/ + dev enable name power/ subsystem@ system time uevent + +To enable the PPS signal generation you can use the command below:: + + $ echo 1 > /sys/class/pps-gen/pps-gen0/enable Parallel port generator ------------------------ diff --git a/Documentation/iio/ad4695.rst b/Documentation/iio/ad4695.rst index 33ed29b7c98a..9ec8bf466c15 100644 --- a/Documentation/iio/ad4695.rst +++ b/Documentation/iio/ad4695.rst @@ -101,7 +101,7 @@ The macro comes from: .. code-block:: - #include <dt-bindings/iio/adi,ad4695.h> + #include <dt-bindings/iio/adc/adi,ad4695.h> Pairing two INx pins ^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/iio/adis16480.rst b/Documentation/iio/adis16480.rst index bc78fa04d958..4a2d40e0daa7 100644 --- a/Documentation/iio/adis16480.rst +++ b/Documentation/iio/adis16480.rst @@ -12,7 +12,10 @@ This driver supports Analog Device's IMUs on SPI bus. * `ADIS16375 <https://www.analog.com/ADIS16375>`_ * `ADIS16480 <https://www.analog.com/ADIS16480>`_ * `ADIS16485 <https://www.analog.com/ADIS16485>`_ +* `ADIS16486 <https://www.analog.com/ADIS16486>`_ +* `ADIS16487 <https://www.analog.com/ADIS16487>`_ * `ADIS16488 <https://www.analog.com/ADIS16488>`_ +* `ADIS16489 <https://www.analog.com/ADIS16489>`_ * `ADIS16490 <https://www.analog.com/ADIS16490>`_ * `ADIS16495 <https://www.analog.com/ADIS16495>`_ * `ADIS16497 <https://www.analog.com/ADIS16497>`_ diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 074dbbf7ba0a..5710f5b9e958 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -29,3 +29,4 @@ Industrial I/O Kernel Drivers adxl380 bno055 ep93xx_adc + opt4060 diff --git a/Documentation/iio/opt4060.rst b/Documentation/iio/opt4060.rst new file mode 100644 index 000000000000..eb155089b6d2 --- /dev/null +++ b/Documentation/iio/opt4060.rst @@ -0,0 +1,61 @@ +============================== +OPT4060 driver +============================== + +1. Overview +============================= + +This driver supports the Texas Instrument RGBW high resolution color sensor over +I2C. +https://www.ti.com/lit/gpn/opt4060 + +The driver supports: +- Raw values for red, green, blue and clear. +- Illuminance values. +- Scaled color values for red, green and blue. +- IIO events for thresholds. +- IIO triggered buffer using both its own data ready trigger and triggers from +other drivers. + +2. Illuminance calculation +============================= + +Illuminance is calculated using the wide spectrum green channel. + +lux = GREEN_RAW x 2.15e-3 + +The value is accessed from: +/sys/bus/iio/devices/iio:deviceX/in_illuminance_input + +See section 8.4.5.2 in the data sheet for additional details. + +3. Color scale values +============================= + +The sensor has different sensitivity for the different color components and +compensating factors are exposed from the driver. + +The values are accessed from: +/sys/bus/iio/devices/iio:deviceX/in_intensity_red_scale +/sys/bus/iio/devices/iio:deviceX/in_intensity_green_scale +/sys/bus/iio/devices/iio:deviceX/in_intensity_blue_scale + +A userspace application can multiply the raw values with the scale values so +that for a particular test light source, typically white, the measurement +intensity is the same across the different color channels. This is calculated +in the following way: + +R = RED_RAW x SCALE_RED(2.4) +G = GREEN_RAW x SCALE_GREEN(1.0) +B = BLUE_RAW x SCALE_BLUE(1.3) + +The data sheet suggests using the scaled values to normalize the scaled R, G +and B values. This is useful to get a value for the ratio between colors +independent of light intensity. A userspace application can do this in the +following way: + +R_NORMALIZED = R / (R + G + B) +G_NORMALIZED = G / (R + G + B) +B_NORMALIZED = B / (R + G + B) + +See section 8.4.5.2 in the data sheet for additional details. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 6272bcf11296..b1395d94b3fd 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -64,6 +64,7 @@ Everything else vduse futex2 perf_ring_buffer + ntsync .. only:: subproject and html diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 243f1f1b554a..bf5aff018c2f 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -283,6 +283,7 @@ Code Seq# Include File Comments 'p' 80-9F linux/ppdev.h user-space parport <mailto:tim@cyberelk.net> 'p' A1-A5 linux/pps.h LinuxPPS +'p' B1-B3 linux/pps_gen.h LinuxPPS <mailto:giometti@linux.it> 'q' 00-1F linux/serio.h 'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK diff --git a/Documentation/userspace-api/ntsync.rst b/Documentation/userspace-api/ntsync.rst new file mode 100644 index 000000000000..25e7c4aef968 --- /dev/null +++ b/Documentation/userspace-api/ntsync.rst @@ -0,0 +1,385 @@ +=================================== +NT synchronization primitive driver +=================================== + +This page documents the user-space API for the ntsync driver. + +ntsync is a support driver for emulation of NT synchronization +primitives by user-space NT emulators. It exists because implementation +in user-space, using existing tools, cannot match Windows performance +while offering accurate semantics. It is implemented entirely in +software, and does not drive any hardware device. + +This interface is meant as a compatibility tool only, and should not +be used for general synchronization. Instead use generic, versatile +interfaces such as futex(2) and poll(2). + +Synchronization primitives +========================== + +The ntsync driver exposes three types of synchronization primitives: +semaphores, mutexes, and events. + +A semaphore holds a single volatile 32-bit counter, and a static 32-bit +integer denoting the maximum value. It is considered signaled (that is, +can be acquired without contention, or will wake up a waiting thread) +when the counter is nonzero. The counter is decremented by one when a +wait is satisfied. Both the initial and maximum count are established +when the semaphore is created. + +A mutex holds a volatile 32-bit recursion count, and a volatile 32-bit +identifier denoting its owner. A mutex is considered signaled when its +owner is zero (indicating that it is not owned). The recursion count is +incremented when a wait is satisfied, and ownership is set to the given +identifier. + +A mutex also holds an internal flag denoting whether its previous owner +has died; such a mutex is said to be abandoned. Owner death is not +tracked automatically based on thread death, but rather must be +communicated using ``NTSYNC_IOC_MUTEX_KILL``. An abandoned mutex is +inherently considered unowned. + +Except for the "unowned" semantics of zero, the actual value of the +owner identifier is not interpreted by the ntsync driver at all. The +intended use is to store a thread identifier; however, the ntsync +driver does not actually validate that a calling thread provides +consistent or unique identifiers. + +An event is similar to a semaphore with a maximum count of one. It holds +a volatile boolean state denoting whether it is signaled or not. There +are two types of events, auto-reset and manual-reset. An auto-reset +event is designaled when a wait is satisfied; a manual-reset event is +not. The event type is specified when the event is created. + +Unless specified otherwise, all operations on an object are atomic and +totally ordered with respect to other operations on the same object. + +Objects are represented by files. When all file descriptors to an +object are closed, that object is deleted. + +Char device +=========== + +The ntsync driver creates a single char device /dev/ntsync. Each file +description opened on the device represents a unique instance intended +to back an individual NT virtual machine. Objects created by one ntsync +instance may only be used with other objects created by the same +instance. + +ioctl reference +=============== + +All operations on the device are done through ioctls. There are four +structures used in ioctl calls:: + + struct ntsync_sem_args { + __u32 count; + __u32 max; + }; + + struct ntsync_mutex_args { + __u32 owner; + __u32 count; + }; + + struct ntsync_event_args { + __u32 signaled; + __u32 manual; + }; + + struct ntsync_wait_args { + __u64 timeout; + __u64 objs; + __u32 count; + __u32 owner; + __u32 index; + __u32 alert; + __u32 flags; + __u32 pad; + }; + +Depending on the ioctl, members of the structure may be used as input, +output, or not at all. + +The ioctls on the device file are as follows: + +.. c:macro:: NTSYNC_IOC_CREATE_SEM + + Create a semaphore object. Takes a pointer to struct + :c:type:`ntsync_sem_args`, which is used as follows: + + .. list-table:: + + * - ``count`` + - Initial count of the semaphore. + * - ``max`` + - Maximum count of the semaphore. + + Fails with ``EINVAL`` if ``count`` is greater than ``max``. + On success, returns a file descriptor the created semaphore. + +.. c:macro:: NTSYNC_IOC_CREATE_MUTEX + + Create a mutex object. Takes a pointer to struct + :c:type:`ntsync_mutex_args`, which is used as follows: + + .. list-table:: + + * - ``count`` + - Initial recursion count of the mutex. + * - ``owner`` + - Initial owner of the mutex. + + If ``owner`` is nonzero and ``count`` is zero, or if ``owner`` is + zero and ``count`` is nonzero, the function fails with ``EINVAL``. + On success, returns a file descriptor the created mutex. + +.. c:macro:: NTSYNC_IOC_CREATE_EVENT + + Create an event object. Takes a pointer to struct + :c:type:`ntsync_event_args`, which is used as follows: + + .. list-table:: + + * - ``signaled`` + - If nonzero, the event is initially signaled, otherwise + nonsignaled. + * - ``manual`` + - If nonzero, the event is a manual-reset event, otherwise + auto-reset. + + On success, returns a file descriptor the created event. + +The ioctls on the individual objects are as follows: + +.. c:macro:: NTSYNC_IOC_SEM_POST + + Post to a semaphore object. Takes a pointer to a 32-bit integer, + which on input holds the count to be added to the semaphore, and on + output contains its previous count. + + If adding to the semaphore's current count would raise the latter + past the semaphore's maximum count, the ioctl fails with + ``EOVERFLOW`` and the semaphore is not affected. If raising the + semaphore's count causes it to become signaled, eligible threads + waiting on this semaphore will be woken and the semaphore's count + decremented appropriately. + +.. c:macro:: NTSYNC_IOC_MUTEX_UNLOCK + + Release a mutex object. Takes a pointer to struct + :c:type:`ntsync_mutex_args`, which is used as follows: + + .. list-table:: + + * - ``owner`` + - Specifies the owner trying to release this mutex. + * - ``count`` + - On output, contains the previous recursion count. + + If ``owner`` is zero, the ioctl fails with ``EINVAL``. If ``owner`` + is not the current owner of the mutex, the ioctl fails with + ``EPERM``. + + The mutex's count will be decremented by one. If decrementing the + mutex's count causes it to become zero, the mutex is marked as + unowned and signaled, and eligible threads waiting on it will be + woken as appropriate. + +.. c:macro:: NTSYNC_IOC_SET_EVENT + + Signal an event object. Takes a pointer to a 32-bit integer, which on + output contains the previous state of the event. + + Eligible threads will be woken, and auto-reset events will be + designaled appropriately. + +.. c:macro:: NTSYNC_IOC_RESET_EVENT + + Designal an event object. Takes a pointer to a 32-bit integer, which + on output contains the previous state of the event. + +.. c:macro:: NTSYNC_IOC_PULSE_EVENT + + Wake threads waiting on an event object while leaving it in an + unsignaled state. Takes a pointer to a 32-bit integer, which on + output contains the previous state of the event. + + A pulse operation can be thought of as a set followed by a reset, + performed as a single atomic operation. If two threads are waiting on + an auto-reset event which is pulsed, only one will be woken. If two + threads are waiting a manual-reset event which is pulsed, both will + be woken. However, in both cases, the event will be unsignaled + afterwards, and a simultaneous read operation will always report the + event as unsignaled. + +.. c:macro:: NTSYNC_IOC_READ_SEM + + Read the current state of a semaphore object. Takes a pointer to + struct :c:type:`ntsync_sem_args`, which is used as follows: + + .. list-table:: + + * - ``count`` + - On output, contains the current count of the semaphore. + * - ``max`` + - On output, contains the maximum count of the semaphore. + +.. c:macro:: NTSYNC_IOC_READ_MUTEX + + Read the current state of a mutex object. Takes a pointer to struct + :c:type:`ntsync_mutex_args`, which is used as follows: + + .. list-table:: + + * - ``owner`` + - On output, contains the current owner of the mutex, or zero + if the mutex is not currently owned. + * - ``count`` + - On output, contains the current recursion count of the mutex. + + If the mutex is marked as abandoned, the function fails with + ``EOWNERDEAD``. In this case, ``count`` and ``owner`` are set to + zero. + +.. c:macro:: NTSYNC_IOC_READ_EVENT + + Read the current state of an event object. Takes a pointer to struct + :c:type:`ntsync_event_args`, which is used as follows: + + .. list-table:: + + * - ``signaled`` + - On output, contains the current state of the event. + * - ``manual`` + - On output, contains 1 if the event is a manual-reset event, + and 0 otherwise. + +.. c:macro:: NTSYNC_IOC_KILL_OWNER + + Mark a mutex as unowned and abandoned if it is owned by the given + owner. Takes an input-only pointer to a 32-bit integer denoting the + owner. If the owner is zero, the ioctl fails with ``EINVAL``. If the + owner does not own the mutex, the function fails with ``EPERM``. + + Eligible threads waiting on the mutex will be woken as appropriate + (and such waits will fail with ``EOWNERDEAD``, as described below). + +.. c:macro:: NTSYNC_IOC_WAIT_ANY + + Poll on any of a list of objects, atomically acquiring at most one. + Takes a pointer to struct :c:type:`ntsync_wait_args`, which is + used as follows: + + .. list-table:: + + * - ``timeout`` + - Absolute timeout in nanoseconds. If ``NTSYNC_WAIT_REALTIME`` + is set, the timeout is measured against the REALTIME clock; + otherwise it is measured against the MONOTONIC clock. If the + timeout is equal to or earlier than the current time, the + function returns immediately without sleeping. If ``timeout`` + is U64_MAX, the function will sleep until an object is + signaled, and will not fail with ``ETIMEDOUT``. + * - ``objs`` + - Pointer to an array of ``count`` file descriptors + (specified as an integer so that the structure has the same + size regardless of architecture). If any object is + invalid, the function fails with ``EINVAL``. + * - ``count`` + - Number of objects specified in the ``objs`` array. + If greater than ``NTSYNC_MAX_WAIT_COUNT``, the function fails + with ``EINVAL``. + * - ``owner`` + - Mutex owner identifier. If any object in ``objs`` is a mutex, + the ioctl will attempt to acquire that mutex on behalf of + ``owner``. If ``owner`` is zero, the ioctl fails with + ``EINVAL``. + * - ``index`` + - On success, contains the index (into ``objs``) of the object + which was signaled. If ``alert`` was signaled instead, + this contains ``count``. + * - ``alert`` + - Optional event object file descriptor. If nonzero, this + specifies an "alert" event object which, if signaled, will + terminate the wait. If nonzero, the identifier must point to a + valid event. + * - ``flags`` + - Zero or more flags. Currently the only flag is + ``NTSYNC_WAIT_REALTIME``, which causes the timeout to be + measured against the REALTIME clock instead of MONOTONIC. + * - ``pad`` + - Unused, must be set to zero. + + This function attempts to acquire one of the given objects. If unable + to do so, it sleeps until an object becomes signaled, subsequently + acquiring it, or the timeout expires. In the latter case the ioctl + fails with ``ETIMEDOUT``. The function only acquires one object, even + if multiple objects are signaled. + + A semaphore is considered to be signaled if its count is nonzero, and + is acquired by decrementing its count by one. A mutex is considered + to be signaled if it is unowned or if its owner matches the ``owner`` + argument, and is acquired by incrementing its recursion count by one + and setting its owner to the ``owner`` argument. An auto-reset event + is acquired by designaling it; a manual-reset event is not affected + by acquisition. + + Acquisition is atomic and totally ordered with respect to other + operations on the same object. If two wait operations (with different + ``owner`` identifiers) are queued on the same mutex, only one is + signaled. If two wait operations are queued on the same semaphore, + and a value of one is posted to it, only one is signaled. + + If an abandoned mutex is acquired, the ioctl fails with + ``EOWNERDEAD``. Although this is a failure return, the function may + otherwise be considered successful. The mutex is marked as owned by + the given owner (with a recursion count of 1) and as no longer + abandoned, and ``index`` is still set to the index of the mutex. + + The ``alert`` argument is an "extra" event which can terminate the + wait, independently of all other objects. + + It is valid to pass the same object more than once, including by + passing the same event in the ``objs`` array and in ``alert``. If a + wakeup occurs due to that object being signaled, ``index`` is set to + the lowest index corresponding to that object. + + The function may fail with ``EINTR`` if a signal is received. + +.. c:macro:: NTSYNC_IOC_WAIT_ALL + + Poll on a list of objects, atomically acquiring all of them. Takes a + pointer to struct :c:type:`ntsync_wait_args`, which is used + identically to ``NTSYNC_IOC_WAIT_ANY``, except that ``index`` is + always filled with zero on success if not woken via alert. + + This function attempts to simultaneously acquire all of the given + objects. If unable to do so, it sleeps until all objects become + simultaneously signaled, subsequently acquiring them, or the timeout + expires. In the latter case the ioctl fails with ``ETIMEDOUT`` and no + objects are modified. + + Objects may become signaled and subsequently designaled (through + acquisition by other threads) while this thread is sleeping. Only + once all objects are simultaneously signaled does the ioctl acquire + them and return. The entire acquisition is atomic and totally ordered + with respect to other operations on any of the given objects. + + If an abandoned mutex is acquired, the ioctl fails with + ``EOWNERDEAD``. Similarly to ``NTSYNC_IOC_WAIT_ANY``, all objects are + nevertheless marked as acquired. Note that if multiple mutex objects + are specified, there is no way to know which were marked as + abandoned. + + As with "any" waits, the ``alert`` argument is an "extra" event which + can terminate the wait. Critically, however, an "all" wait will + succeed if all members in ``objs`` are signaled, *or* if ``alert`` is + signaled. In the latter case ``index`` will be set to ``count``. As + with "any" waits, if both conditions are filled, the former takes + priority, and objects in ``objs`` will be acquired. + + Unlike ``NTSYNC_IOC_WAIT_ANY``, it is not valid to pass the same + object more than once, nor is it valid to pass the same object in + ``objs`` and in ``alert``. If this is attempted, the function fails + with ``EINVAL``. |