1# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause 2%YAML 1.2 3--- 4$id: http://devicetree.org/schemas/input/qcom,spmi-haptics.yaml# 5$schema: http://devicetree.org/meta-schemas/core.yaml# 6 7title: Haptics device inside Qualcomm Technologies, Inc. PMIC 8 9maintainers: 10 - Fenglin Wu <fenglin.wu@oss.qualcomm.com> 11 12description: | 13 Certain Qualcomm PMICs integrate a haptics module, such as the HAP530_HV haptics 14 module in the PMIH0108 PMIC, which drives an LRA (Linear Resonant Actuator) with 15 an output voltage up to 10 V. Several play modes are supported in HAP530_HV: 16 17 DIRECT_PLAY: The hardware outputs sinusoidal waveforms whose period is 18 defined by qcom,lra-period-us and whose peak voltage is defined by 19 qcom,vmax-microvolt. The driving amplitude can be scaled in the range 20 [0, 255] via a single register byte. Hardware-based LRA auto-resonance 21 tracking is enabled by default in this mode, allowing the haptics engine 22 to follow the actual resonant frequency of the LRA and update the driving 23 period accordingly to achieve stronger vibration magnitude. 24 25 FIFO: The hardware can play an arbitrary waveform composed of a sequence 26 of 8-bit samples at a configurable play rate. Samples are pre-filled 27 into the internal FIFO memory of the haptics module and continuously 28 replenished via the FIFO-empty IRQ until all samples have been played. 29 An 8K-byte FIFO memory bank is available in the HAP530_HV haptics module, 30 shared between the FIFO and PAT_MEM play modes. The memory partition 31 between the two modes is configurable via registers, and FIFO mode always 32 uses the 1st partition starting from offset 0. 33 34 PAT_MEM: This mode is very similar to FIFO streaming mode but without the 35 data refilling capability. It is designed mainly for short, latency-critical 36 vibrations. The memory space for PAT_MEM mode must be reserved for dedicated 37 usage, and the waveform data should be preloaded and remain unchanged 38 thereafter. The haptics module can play the waveform data from the memory 39 region specified by the PAT_MEM play start address and length registers. 40 41 In either FIFO mode or PAT_MEM mode, the following play rates are supported: 42 -- 0(T_LRA): each FIFO byte drives one full sinusoidal cycle with the 43 period defined in qcom,lra-period-us. 44 -- 1/2/3(T_LRA_DIV_2/4/8): each FIFO byte drives a half/quarter/eighth 45 sinusoidal cycle with the period defined in qcom,lra-period-us. 46 -- 4/5/6(T_LRA_X_2/4/8): each FIFO byte drives 2/4/8 sinusoidal cycles 47 with the period defined in qcom,lra-period-us. 48 -- 8/9/10/11/12/13(8KHz/16KHz/24KHz/32KHz/44.1KHz/48KHz): the FIFO 49 data is treated as PCM samples and drives the output with an 50 arbitrarily shaped waveform. This mode is typically used to define 51 custom driving waveforms for specific vibration effects such as fast 52 attack, crisp brake, etc. 53 54 The drive voltage in FIFO or PAT_MEM mode can exceed the value defined in 55 qcom,vmax-microvolt to achieve a special vibration effect, but the waveform 56 must be short enough to prevent the LRA from being damaged by operating at 57 an overvoltage. 58 59 Also, hardware-based LRA auto-resonance tracking is normally disabled in 60 FIFO or PAT_MEM mode, as these modes are intended to drive arbitrary 61 waveforms that may not follow the resonant frequency; autonomous hardware 62 resonance correction would interfere with the intended output. 63 64properties: 65 compatible: 66 items: 67 - const: qcom,pmih0108-haptics 68 - const: qcom,spmi-haptics 69 70 reg: 71 items: 72 - description: HAP_CFG module base address 73 - description: HAP_PTN module base address 74 75 reg-names: 76 items: 77 - const: cfg 78 - const: ptn 79 80 interrupts: 81 maxItems: 1 82 83 interrupt-names: 84 items: 85 - const: fifo-empty 86 87 qcom,vmax-microvolt: 88 description: 89 Maximum allowed output driving voltage in microvolts, must be a multiple 90 of 50,000 uV. This is the peak driving voltage in DIRECT_PLAY mode, 91 which outputs sinusoidal waveforms. The value should be equal to the 92 square root of 2 times the Vrms voltage of the LRA. 93 minimum: 50000 94 maximum: 10000000 95 multipleOf: 50000 96 97 qcom,lra-period-us: 98 description: 99 LRA actuator initial resonance period in microseconds 100 (1,000,000 / resonant_freq_hz). Used to configure T_LRA-based play 101 rates and the auto-resonance zero-crossing window. It could be also used 102 as the initial period if the LRA wants to be driven off resonance. 103 minimum: 5 104 maximum: 20475 105 multipleOf: 5 106 107required: 108 - compatible 109 - reg 110 - reg-names 111 - interrupts 112 - interrupt-names 113 - qcom,vmax-microvolt 114 - qcom,lra-period-us 115 116additionalProperties: false 117