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", "qcom,pm5100-haptics". - reg: Usage: required Value type: Definition: Register base for following haptics modules: HAPTICS_CFG, HAPTICS_PATTERN, HAPTICS_BOOST. HAPTICS_BOOST register base is not applicable for PM5100. - 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,fifo-empty-threshold: Usage: optional Value type: Definition: Specifies the FIFO empty threshold. The "fifo-empty" IRQ will be triggered when the number of the samples in the FIFO is less than the threshold. For PM8350B v1, allowed value is 0 - 104 in multiple of 4 and the default value is 48. For PM8350B v2, allowed value is 0 - 640 in multiple of 40 and the default value is 280. For PM5100, allowed value is 0 - 1024 in multiple of 32 and the default value is 288. - 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. - nvmem-cell-names: Usage: optional Value type: Definition: The nvmem cell name of the SDAM module where the closed-loop brake calibration settings can be stored. It must be "hap_cl_brake". Not applicable for PM5100. - nvmem-cells: Usage: optional Value type: Definition: Phandle of the nvmem cell to store the closed-loop brake calibration settings. Please refer to nvmem bindings as described in bindings/nvmem/nvmem.txt. Not applicable for PM5100. - nvmem-names: Usage: optional Value type: Definition: The nvmem device name of the SDAM module used for haptics configuration. It must be "hap_cfg_sdam". Not applicable for PM5100. - nvmem: Usage: optional Value type: Definition: Phandle of the nvmem device used for haptics configuration. Please refer to nvmem bindings as described in bindings/nvmem/nvmem.txt. Not applicable for PM5100. - qcom,pbs-client: Usage: optional Value type: Definition: Phandle of the PBS client used for triggering PBS to configure haptics ISC (short circuit current) config during LRA impedance detection. Not applicable for PM5100. 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. - qcom,rt-imp-detect: Usage: optional Value type: Definition: Specifies if HW based realtime impedance measurement is used when detecting LRA impedance. This is only applicable for HAP525_HV haptics module. A child node named "qcom,hap-swr-slave-reg" can be defined to export a regulator device which is used for swr-haptics module to control the online status of SWR slave. The child node should have following property for this regulator device: - regulator-name: Please refer to: bindings/regulator/regulator.txt. The following properties should be specified in child nodes for defining different vibration effects: - qcom,effect-id: Usage: optional 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,primitive-id: Usage: optional Value type: Definition: Specifies the effect primitive ID that a client can request to play the corresponding primitive 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 byte 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 8-bit using '/bits/ 8' parameter, or using '[]' instead of '<>'. 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-fifo-preload: Usage: optional Value type: Definition: Specifies if the FIFO effect data should be preloaded into pattern memory during boot up. In HAP525_HV module, there are 4 pattern memory partitions with configurable size and each partition can be used for preloading one FIFO effect. The total FIFO memory space is 2K bytes and 640 bytes space is reserved for FIFO streaming mode which needs to load the FIFO data at runtime, the rest can be all used for pattern memory partitions. This feature is only available for HAP525_HV haptics module that is present on PMICs like PM8550B. - 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>, <0xf200>; interrupts = <0x3 0xf0 0x1 IRQ_TYPE_EDGE_BOTH>; interrupt-names = "fifo-empty"; nvmem-cell-names = "hap_cl_brake"; nvmem-cells = <&hap_cl_brake>; nvmem-names = "hap_cfg_sdam"; nvmem = <&pmk8350_sdam_46>; qcom,pbs-client = <&pm8350b_pbs2>; 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 = ; qcom,hap-swr-slave-reg { regulator-name = "hap-swr-slave-reg"; }; 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/ 8 <0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff>; qcom,wf-fifo-period = ; qcom,wf-brake-pattern = /bits/ 8 <0x7f 0x5f 0x3f>; qcom,wf-auto-res-disable; }; primitive_0 { qcom,primitive-id = <0>; qcom,wf-vmax-mv = <8000>; qcom,wf-pattern-data = <0x0ff S_PERIOD_T_LRA 0>, <0x07f S_PERIOD_T_LRA 0>, qcom,wf-pattern-period-us = <5000>; qcom,wf-brake-pattern = /bits/ 8 <0xff 0x7f 0x3f>; qcom,wf-auto-res-disable; } };