Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a788bedc authored by Ahmad Khalil's avatar Ahmad Khalil
Browse files

Update HAL with new PWLE V2 APIs 

Updating IVibrator.aidl to introduce APIs for PWLE V2 support. The updated interface now enables retrieval of minimum and maximum PWLE durations, maximum composition size, and facilitates the composition of PWLE effects using points.

Bug: 347034419
Flag: EXEMPT HAL interface change
Test: vts-tradefed run vts -m VtsHalVibratorTargetTest
Change-Id: Id0a93e4f8678622bdb698cddc2b39f46e0283fdd
parent 9415a2f3

vibrator/aidl/aidl_api/android.hardware.vibrator/current/android/hardware/vibrator/IVibrator.aidl

+6 −0
Original line number Diff line number Diff line
@@ -59,6 +59,11 @@ interface IVibrator { 
  android.hardware.vibrator.Braking[] getSupportedBraking();

  void composePwle(in android.hardware.vibrator.PrimitivePwle[] composite, in android.hardware.vibrator.IVibratorCallback callback);

  void performVendorEffect(in android.hardware.vibrator.VendorEffect vendorEffect, in android.hardware.vibrator.IVibratorCallback callback);

  List<android.hardware.vibrator.PwleV2OutputMapEntry> getPwleV2FrequencyToOutputAccelerationMap();

  int getPwleV2PrimitiveDurationMaxMillis();

  int getPwleV2CompositionSizeMax();

  int getPwleV2PrimitiveDurationMinMillis();

  void composePwleV2(in android.hardware.vibrator.PwleV2Primitive[] composite, in android.hardware.vibrator.IVibratorCallback callback);

  const int CAP_ON_CALLBACK = (1 << 0) /* 1 */;

  const int CAP_PERFORM_CALLBACK = (1 << 1) /* 2 */;

  const int CAP_AMPLITUDE_CONTROL = (1 << 2) /* 4 */;
@@ -71,4 +76,5 @@ interface IVibrator { 
  const int CAP_FREQUENCY_CONTROL = (1 << 9) /* 512 */;

  const int CAP_COMPOSE_PWLE_EFFECTS = (1 << 10) /* 1024 */;

  const int CAP_PERFORM_VENDOR_EFFECTS = (1 << 11) /* 2048 */;

  const int CAP_COMPOSE_PWLE_EFFECTS_V2 = (1 << 12) /* 4096 */;

}

vibrator/aidl/aidl_api/android.hardware.vibrator/current/android/hardware/vibrator/PwleV2OutputMapEntry.aidl

0 → 100644
+39 −0
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2024 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

///////////////////////////////////////////////////////////////////////////////

// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //

///////////////////////////////////////////////////////////////////////////////



// This file is a snapshot of an AIDL file. Do not edit it manually. There are

// two cases:

// 1). this is a frozen version file - do not edit this in any case.

// 2). this is a 'current' file. If you make a backwards compatible change to

//     the interface (from the latest frozen version), the build system will

//     prompt you to update this file with `m <name>-update-api`.

//

// You must not make a backward incompatible change to any AIDL file built

// with the aidl_interface module type with versions property set. The module

// type is used to build AIDL files in a way that they can be used across

// independently updatable components of the system. If a device is shipped

// with such a backward incompatible change, it has a high risk of breaking

// later when a module using the interface is updated, e.g., Mainline modules.



package android.hardware.vibrator;

@VintfStability

parcelable PwleV2OutputMapEntry {

  float frequencyHz;

  float maxOutputAccelerationGs;

}

vibrator/aidl/aidl_api/android.hardware.vibrator/current/android/hardware/vibrator/PwleV2Primitive.aidl

0 → 100644
+40 −0
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2024 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

///////////////////////////////////////////////////////////////////////////////

// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //

///////////////////////////////////////////////////////////////////////////////



// This file is a snapshot of an AIDL file. Do not edit it manually. There are

// two cases:

// 1). this is a frozen version file - do not edit this in any case.

// 2). this is a 'current' file. If you make a backwards compatible change to

//     the interface (from the latest frozen version), the build system will

//     prompt you to update this file with `m <name>-update-api`.

//

// You must not make a backward incompatible change to any AIDL file built

// with the aidl_interface module type with versions property set. The module

// type is used to build AIDL files in a way that they can be used across

// independently updatable components of the system. If a device is shipped

// with such a backward incompatible change, it has a high risk of breaking

// later when a module using the interface is updated, e.g., Mainline modules.



package android.hardware.vibrator;

@VintfStability

parcelable PwleV2Primitive {

  float amplitude;

  float frequencyHz;

  int timeMillis;

}

vibrator/aidl/android/hardware/vibrator/IVibrator.aidl

+84 −0
Original line number Diff line number Diff line
@@ -23,6 +23,8 @@ import android.hardware.vibrator.Effect; 
import android.hardware.vibrator.EffectStrength;

import android.hardware.vibrator.IVibratorCallback;

import android.hardware.vibrator.PrimitivePwle;

import android.hardware.vibrator.PwleV2OutputMapEntry;

import android.hardware.vibrator.PwleV2Primitive;

import android.hardware.vibrator.VendorEffect;



@VintfStability
@@ -75,6 +77,10 @@ interface IVibrator { 
     * Whether perform w/ vendor effect is supported.

     */

    const int CAP_PERFORM_VENDOR_EFFECTS = 1 << 11;

    /**

     * Whether composePwleV2 for PwlePrimitives is supported.

     */

    const int CAP_COMPOSE_PWLE_EFFECTS_V2 = 1 << 12;



    /**

     * Determine capabilities of the vibrator HAL (CAP_* mask)
@@ -385,4 +391,82 @@ interface IVibrator { 
     *         - EX_SERVICE_SPECIFIC for bad vendor data, vibration is not triggered.

     */

    void performVendorEffect(in VendorEffect vendorEffect, in IVibratorCallback callback);



    /**

     * Retrieves a mapping of vibration frequency (Hz) to the maximum achievable output

     * acceleration (Gs) the device can reach at that frequency.

     *

     * The map, represented as a list of `PwleV2OutputMapEntry` (frequency, output acceleration)

     * pairs, defines the device's frequency response. The platform uses the minimum and maximum

     * frequency values to determine the supported input range for `IVibrator.composePwleV2`.

     * Output acceleration values are used to identify a frequency range suitable to safely play

     * perceivable vibrations with a simple API. The map is also exposed for developers using an

     * advanced API.

     *

     * The platform does not impose specific requirements on map resolution which can vary

     * depending on the shape of device output curve. The values will be linearly interpolated

     * during lookups. The platform will provide a simple API, defined by the first frequency range

     * where output acceleration consistently exceeds a minimum threshold of 10 db SL.

     *

     *

     * This may not be supported and this support is reflected in getCapabilities

     * (CAP_COMPOSE_PWLE_EFFECTS_V2). If this is supported, it's expected to be non-empty and

     * describe a valid non-empty frequency range where the simple API can be defined

     * (i.e. a range where the output acceleration is always above 10 db SL).

     *

     * @return A list of map entries representing the frequency to max acceleration

     *         mapping.

     * @throws EX_UNSUPPORTED_OPERATION if unsupported, as reflected by getCapabilities.

     */

    List<PwleV2OutputMapEntry> getPwleV2FrequencyToOutputAccelerationMap();



    /**

     * Retrieve the maximum duration allowed for any primitive PWLE in units of

     * milliseconds.

     *

     * This may not be supported and this support is reflected in

     * getCapabilities (CAP_COMPOSE_PWLE_EFFECTS_V2).

     *

     * @return The maximum duration allowed for a single PrimitivePwle. Non-zero value if supported.

     * @throws EX_UNSUPPORTED_OPERATION if unsupported, as reflected by getCapabilities.

     */

    int getPwleV2PrimitiveDurationMaxMillis();



    /**

     * Retrieve the maximum number of PWLE primitives input supported by IVibrator.composePwleV2.

     *

     * This may not be supported and this support is reflected in

     * getCapabilities (CAP_COMPOSE_PWLE_EFFECTS_V2). Devices supporting PWLE effects must

     * support effects with at least 16 PwleV2Primitive.

     *

     * @return The maximum count allowed. Non-zero value if supported.

     * @throws EX_UNSUPPORTED_OPERATION if unsupported, as reflected by getCapabilities.

     */

    int getPwleV2CompositionSizeMax();



    /**

     * Retrieves the minimum duration (in milliseconds) of any segment within a

     * PWLE effect. Devices supporting PWLE effects must support a minimum ramp

     * time of 20 milliseconds.

     *

     * This may not be supported and this support is reflected in

     * getCapabilities (CAP_COMPOSE_PWLE_EFFECTS_V2).

     *

     * @return The minimum duration allowed for a single PrimitivePwle. Non-zero value if supported.

     * @throws EX_UNSUPPORTED_OPERATION if unsupported, as reflected by getCapabilities.

     */

    int getPwleV2PrimitiveDurationMinMillis();



    /**

     * Play composed sequence of chirps with optional callback upon completion.

     *

     * This may not be supported and this support is reflected in

     * getCapabilities (CAP_COMPOSE_PWLE_EFFECTS_V2).

     *

     * Doing this operation while the vibrator is already on is undefined behavior. Clients should

     * explicitly call off. IVibratorCallback.onComplete() support is required for this API.

     *

     * @param composite An array of primitives that represents a PWLE (Piecewise-Linear Envelope).

     */

    void composePwleV2(in PwleV2Primitive[] composite, in IVibratorCallback callback);

}

vibrator/aidl/android/hardware/vibrator/PwleV2OutputMapEntry.aidl

0 → 100644
+35 −0
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2024 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */



package android.hardware.vibrator;



@VintfStability

parcelable PwleV2OutputMapEntry {

    /**

     * Absolute frequency point in the units of hertz

     *

     */

    float frequencyHz;



    /**

     * Max output acceleration for the specified frequency in units of Gs.

     *

     * This value represents the maximum safe output acceleration (in Gs) achievable at the

     * specified frequency, typically determined during calibration. The actual output acceleration

     * is assumed to scale linearly with the input amplitude within the range of [0, 1].

     */

    float maxOutputAccelerationGs;

}