diff --git a/bindings/input/qcom-hv-haptics.txt b/bindings/input/qcom-hv-haptics.txt new file mode 100644 index 000000000000..72334b9029f6 --- /dev/null +++ b/bindings/input/qcom-hv-haptics.txt @@ -0,0 +1,254 @@ +Qualcomm Technologies, Inc. High-Voltage Haptics + +The High-Voltage Haptics module in QTI PMICs can support either ERM or +LRA actuators with drive voltage up to 10 V. It also has five different +pattern sources (DIRECT_PLAY, PATTERN1, PATTERN2, FIFO, SWR) which can +be used for playing different vibration effects. This binding document +describes the properties for this PMIC module. + +This haptics device supports 2 levels of nodes. The main node defines +the hardware configuration based on the actuator used in the platform. +Child nodes define the configurations for different haptics effects +that can be supported. + +Properties: + +- compatible: + Usage: required + Value type: + Definition: It can be one of following: + "qcom,hv-haptics", + "qcom,pm8350b-haptics". + +- reg: + Usage: required + Value type: + Definition: Register base for HAPTICS_CFG and HAPTICS_PATTERN modules. + +- interrupts: + Usage: required + Value type: + Definition: Peripheral interrupt specifier. + +- interrupt-names: + Usage: required + Value type: + Definition: Interrupt names. This string list must match up 1-to-1 with + the interrupts specified in the 'interrupts' property. + The following interrupt is required: "fifo-empty". + +- qcom,vmax-mv: + Usage: optional + Value type: + Definition: Specifies the maximum allowed output voltage in millivolts + for the actuator. The value specified here will be rounded + off to the closest multiple of 50 mV. Allowed values: 0 to + 11000. If this is not specified, 5000 mV will be used by + default. + +- qcom,brake-mode: + Usage: optional + Value type: + Definition: Specifies vibration brake mode. Please refer to: + include/dt-bindings/input/qcom,hv-haptics.h. + If this is not defined, "auto" brake mode will be used + by default. + +- qcom,brake-disable: + Usage: optional + Value type: + Definition: Specifies if vibation brake is disabled. + +- qcom,brake-pattern: + Usage: optional + Value type: + Definition: Specifies the brake pattern in a byte array which is less + than 8 elements. The array needs to be specified as 8-bit + using '/bits/ 8' parameter. The pattern will be played at the + end of the playing waveform if manual brake mode (either + open-loop or close-loop) is selected. If this is not defined, + or if it's defined as an array with all zeros, then manual + brake is disabled. + +- qcom,use-erm: + Usage: optional + Value type: + Definition: Specifies if the hardware is driving an ERM actuator. If it's + not defined, then LRA actuator is used. + +The following properties are only required when LRA actuator is used: + +- qcom,lra-period-us: + Usage: required + Value type: + Definition: Specifies the initial resonance period in microseconds for + LRA actuator. It has to be specified if an LRA actuator is + used. Allowed values: 5 to 20475. + +- qcom,drv-sig-shape: + Usage: optional + Value type: + Definition: Specifies the drive signal shape for LRA. Please refer to: + include/dt-bindings/input/qcom,hv-haptics.h. + The "sine" drive signal is used by default if this property + is not defined. + +- qcom,brake-sig-shape: + Usage: optional + Value type: + Definition: Specifies the reverse brake signal shape. Please refer to: + include/dt-bindings/input/qcom,hv-haptics.h. + The "sine" brake signal is used by default if this property + is not defined. + +- qcom,brake-sine-gain: + Usage: optional + Value type: + Definition: Specifies the brake signal gain when sine brake signal shape + is selected. Please refer to: + include/dt-bindings/input/qcom,hv-haptics.h. + +The following properties should be specified in child nodes for defining +different vibration effects: + +- qcom,effect-id: + Usage: required + Value type: + Definition: Specifies the effect ID that a client can request to play + the corresponding effect definition in this child node. The ID + is normaly defined and sent from userspace for certain user + notification event. + +- qcom,wf-vmax-mv: + Usage: optional + Value type: + Definition: Specifies maximum allowed output voltage in millivolts for + this effect. Value specified here will be rounded off to + the closest multiple of 50 mV. Allowed values: 0 to 11000. If + this is not specified, the value of "qcom,vmax-mv" which is + defined in the parent node will be used. + +- qcom,wf-pattern-data: + Usage: required + Value type: + Definition: Defines an array of 8 3-tuples in which each tuple specifies + the 3-element pattern data that will be played in PATTERN1 + source mode by default. The 3 elements of each tuple are: + [0] => 9-bit pattern amplitude. + [1] => play period for this pattern amplitude. See + include/dt-bindings/input/qcom,hv-haptics.h + [2] => a 0/1 flag to indicate if the frequency of the LRA + drive signal will be doubled when playing this pattern. + +- qcom,wf-pattern-preload: + Usage: optional + Value type: + Definition: Specifies if the effect pattern should be preloaded into + PATTERN2 source during boot up and it won't be changed when + device is alive. For the effect that has this property + specified, register configurations are done already for + achieving low latency response. This can be specified only for + one effect. + +- qcom,wf-pattern-period-us: + Usage: optional + Value type: + Definition: Specifies the play period in microseconds for each pattern + entry defined in "qcom,wf-pattern-data". Allowed values: + 5 to 20475. + +- qcom,wf-fifo-data: + Usage: optional + Value type: + Definition: Defines a 9-bit data array of patterns which will be filled + into the FIFO memory and played when FIFO mode is selected. + The array needs to be specified as 16-bit using '/bits/ 16' + parameter. Either "qcom,wf-pattern-data" or "qcom,wf-fifo-data" + need to be defined in one effect child node. If both are + defined, then the FIFO data defined in this property will be + ignored. + +- qcom,wf-fifo-period: + Usage: optional + Value type: + Definition: Specifies the play period definition for the FIFO data defined + in "qcom,wf-fifo-data". + See definition at: include/dt-bindings/input/qcom,hv-haptics.h + +- qcom,wf-brake-mode: + Usage: optional + Value type: + Definition: Specifies the brake mode for this effect. Please refer to: + include/dt-bindings/input/qcom,hv-haptics.h. + If this is not defined, the brake mode defined in + "qcom,brake-mode" will be used for this effect. + +- qcom,wf-brake-pattern: + Usage: optional + Value type: + Definition: Specifies manual brake pattern for this effect. The array needs + to be specified as 8-bit using '/bits/ 8' parameter. + If it's not defined, the brake pattern defined in + "qcom,brake-pattern" will be used for this effect. + +- qcom,wf-brake-disable: + Usage: optional + Value type: + Definition: Specifies if the vibration brake is disabled for this effect. + +- qcom,wf-brake-sine-gain: + Usage: optional + Value type: + Definition: Specifies the brake sine signal gain for this effect when sine + brake signal shape is selected. Please refer to: + include/dt-bindings/input/qcom,hv-haptics.h. + +- qcom,wf-auto-res-disable: + Usage: optional + value type: + Definition: Specifies if the effect will be played with LRA auto resonance + feature disabled. + +Example: + qcom,hv-haptics@f000 { + compatible = "qcom,hv-haptics"; + reg = <0xf000>, <0xf100>; + interrupts = <0x3 0xf0 0x1 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "fifo-empty"; + qcom,vmax-mv = <900>; + qcom,brake-mode = ; + qcom,brake-pattern = /bits/ 8 <0xff 0x3f 0x1f>; + qcom,lra-period-us = <5880>; + qcom,drv-sig-shape = ; + qcom,brake-sig-shape = ; + + effect_0 { + /* CLICK effect */ + qcom,effect-id = <0>; + qcom,wf-vmax-mv = <8000>; + qcom,wf-pattern-data = <0x01f S_PERIOD_T_LRA 0>, + <0x03f S_PERIOD_T_LRA 0>, + <0x05f S_PERIOD_T_LRA 0>, + <0x07f S_PERIOD_T_LRA 0>, + <0x17f S_PERIOD_T_LRA 0>, + <0x15f S_PERIOD_T_LRA 0>, + <0x13f S_PERIOD_T_LRA 0>, + <0x11f S_PERIOD_T_LRA 0>; + qcom,wf-pattern-period-us = <5000>; + qcom,wf-brake-pattern = /bits/ 8 <0xff 0x7f 0x3f>; + qcom,wf-pattern-preload; + qcom,wf-auto-res-disable; + }; + + effect_1 { + /* DOUBLE_CLICK effect */ + qcom,effect-id = <1>; + qcom,wf-vmax-mv = <5000>; + qcom,wf-fifo-data = /bits/ 16 <0x1ff 0x1ff 0x1ff 0x1ff 0x1ff + 0x1ff 0x1ff 0x1ff 0x1ff 0x1ff + 0x1ff 0x1ff 0x1ff 0x1ff 0x1ff>; + qcom,wf-fifo-period = ; + qcom,wf-brake-pattern = /bits/ 8 <0x7f 0x5f 0x3f>; + qcom,wf-auto-res-disable; + }; + };