Documentation/devicetree/bindings/input/qcom,spmi-haptics.yaml

# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/input/qcom,spmi-haptics.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Haptics device inside Qualcomm Technologies, Inc. PMIC

maintainers:
  - Fenglin Wu <fenglin.wu@oss.qualcomm.com>

description: |
  Certain Qualcomm PMICs integrate a haptics module, such as the HAP530_HV haptics
  module in the PMIH0108 PMIC, which drives an LRA (Linear Resonant Actuator) with
  an output voltage up to 10 V. Several play modes are supported in HAP530_HV:

    DIRECT_PLAY: The hardware outputs sinusoidal waveforms whose period is
      defined by qcom,lra-period-us and whose peak voltage is defined by
      qcom,vmax-microvolt. The driving amplitude can be scaled in the range
      [0, 255] via a single register byte.  Hardware-based LRA auto-resonance
      tracking is enabled by default in this mode, allowing the haptics engine
      to follow the actual resonant frequency of the LRA and update the driving
      period accordingly to achieve stronger vibration magnitude.

    FIFO: The hardware can play an arbitrary waveform composed of a sequence
      of 8-bit samples at a configurable play rate.  Samples are pre-filled
      into the internal FIFO memory of the haptics module and continuously
      replenished via the FIFO-empty IRQ until all samples have been played.
      An 8K-byte FIFO memory bank is available in the HAP530_HV haptics module,
      shared between the FIFO and PAT_MEM play modes. The memory partition
      between the two modes is configurable via registers, and FIFO mode always
      uses the 1st partition starting from offset 0.

    PAT_MEM: This mode is very similar to FIFO streaming mode but without the
      data refilling capability. It is designed mainly for short, latency-critical
      vibrations. The memory space for PAT_MEM mode must be reserved for dedicated
      usage, and the waveform data should be preloaded and remain unchanged
      thereafter. The haptics module can play the waveform data from the memory
      region specified by the PAT_MEM play start address and length registers.

    In either FIFO mode or PAT_MEM mode, the following play rates are supported:
      -- 0(T_LRA): each FIFO byte drives one full sinusoidal cycle with the
        period defined in qcom,lra-period-us.
      -- 1/2/3(T_LRA_DIV_2/4/8): each FIFO byte drives a half/quarter/eighth
        sinusoidal cycle with the period defined in qcom,lra-period-us.
      -- 4/5/6(T_LRA_X_2/4/8): each FIFO byte drives 2/4/8 sinusoidal cycles
        with the period defined in qcom,lra-period-us.
      -- 8/9/10/11/12/13(8KHz/16KHz/24KHz/32KHz/44.1KHz/48KHz): the FIFO
        data is treated as PCM samples and drives the output with an
        arbitrarily shaped waveform.  This mode is typically used to define
        custom driving waveforms for specific vibration effects such as fast
        attack, crisp brake, etc.

    The drive voltage in FIFO or PAT_MEM mode can exceed the value defined in
    qcom,vmax-microvolt to achieve a special vibration effect, but the waveform
    must be short enough to prevent the LRA from being damaged by operating at
    an overvoltage.

    Also, hardware-based LRA auto-resonance tracking is normally disabled in
    FIFO or PAT_MEM mode, as these modes are intended to drive arbitrary
    waveforms that may not follow the resonant frequency; autonomous hardware
    resonance correction would interfere with the intended output.

properties:
  compatible:
    items:
      - const: qcom,pmih0108-haptics
      - const: qcom,spmi-haptics

  reg:
    items:
      - description: HAP_CFG module base address
      - description: HAP_PTN module base address

  reg-names:
    items:
      - const: cfg
      - const: ptn

  interrupts:
    maxItems: 1

  interrupt-names:
    items:
      - const: fifo-empty

  qcom,vmax-microvolt:
    description:
      Maximum allowed output driving voltage in microvolts, must be a multiple
      of 50,000 uV. This is the peak driving voltage in DIRECT_PLAY mode,
      which outputs sinusoidal waveforms. The value should be equal to the
      square root of 2 times the Vrms voltage of the LRA.
    minimum: 50000
    maximum: 10000000
    multipleOf: 50000

  qcom,lra-period-us:
    description:
      LRA actuator initial resonance period in microseconds
      (1,000,000 / resonant_freq_hz).  Used to configure T_LRA-based play
      rates and the auto-resonance zero-crossing window. It could be also used
      as the initial period if the LRA wants to be driven off resonance.
    minimum: 5
    maximum: 20475
    multipleOf: 5

required:
  - compatible
  - reg
  - reg-names
  - interrupts
  - interrupt-names
  - qcom,vmax-microvolt
  - qcom,lra-period-us

additionalProperties: false