From 11444a63a7492a85906adbcc281b5e9c989a5e6f Mon Sep 17 00:00:00 2001 From: Fenglin Wu Date: Thu, 28 Nov 2019 10:34:53 +0800 Subject: [PATCH] dt-bindings: input: qcom-hv-haptics: Add initial binding document Qualcomm Technologies, Inc. (QTI) High Voltage (HV) PMIC haptics modules can support up to 10 V voltage to drive either ERM or LRA. It has an integrated module to support auto resonance detection and correction for LRA actuator. It can play different vibration effects with different pattern sources. It also has an integrated brake module which can work in different modes to use BEMF for quick vibration stop. Change-Id: Id8b9fa1e4eefc7dda325e25728e59af9c1de9049 --- bindings/input/qcom-hv-haptics.txt | 254 +++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 bindings/input/qcom-hv-haptics.txt 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; + }; + };