soundtrigger: Define v2.1 HAL

SoundTrigger 2.1 HAL is an extension to 2.0 fixing
the issue with of data blobs of arbitrary size that
can't outgrow HwBinder's IPC transaction size limit.
Instead of vectors, shared memory handles are used.

Added methods for getting and setting parameters.
The parameters are opaque to the framework, it does
not interpret them.

Bug: 68823037
Change-Id: I01c0c867e1d13023a22ccf408e84da78947d3bc2
Test: run hardware/interfaces/update-makefiles.sh

3 files changed, 345 insertions, 0 deletions

diff --git a/soundtrigger/2.1/Android.bp b/soundtrigger/2.1/Android.bp
new file mode 100644
index 000000000..ed1ec3d20
--- /dev/null
+++ b/soundtrigger/2.1/Android.bp
@@ -0,0 +1,20 @@
+// This file is autogenerated by hidl-gen -Landroidbp.
+
+hidl_interface {
+    name: "android.hardware.soundtrigger@2.1",
+    root: "android.hardware",
+    vndk: {
+        enabled: true,
+    },
+    srcs: [
+        "ISoundTriggerHw.hal",
+        "ISoundTriggerHwCallback.hal",
+    ],
+    interfaces: [
+        "android.hardware.audio.common@2.0",
+        "android.hardware.soundtrigger@2.0",
+        "android.hidl.base@1.0",
+    ],
+    gen_java: false,
+}
+
diff --git a/soundtrigger/2.1/ISoundTriggerHw.hal b/soundtrigger/2.1/ISoundTriggerHw.hal
new file mode 100644
index 000000000..2f2e73ae7
--- /dev/null
+++ b/soundtrigger/2.1/ISoundTriggerHw.hal
@@ -0,0 +1,234 @@
+/*
+ * Copyright 2017 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.soundtrigger@2.1;
+
+import @2.0::ISoundTriggerHw;
+import @2.0::ISoundTriggerHwCallback.CallbackCookie;
+import @2.0::SoundModelHandle;
+
+import ISoundTriggerHwCallback;
+
+/**
+ * SoundTrigger HAL interface. Used for hardware recognition of hotwords.
+ */
+interface ISoundTriggerHw extends @2.0::ISoundTriggerHw {
+
+    /**
+     * Base sound model descriptor. This struct is the header of a larger block
+     * passed to loadSoundModel_2_1() and contains the binary data of the
+     * sound model.
+     */
+    struct SoundModel {
+        /** Sound model header. Any data contained in the 'header.data' field
+         * is ignored */
+        @2.0::ISoundTriggerHw.SoundModel header;
+        /** Opaque data transparent to Android framework */
+        memory data;
+    };
+
+    /**
+     * Specialized sound model for key phrase detection.
+     * Proprietary representation of key phrases in binary data must match
+     * information indicated by phrases field.
+     */
+    struct PhraseSoundModel {
+        /** Common part of sound model descriptor */
+        SoundModel  common;
+        /** List of descriptors for key phrases supported by this sound model */
+        vec<Phrase> phrases;
+    };
+
+    /**
+     * Configuration for sound trigger capture session passed to
+     * startRecognition_2_1() method.
+     */
+    struct RecognitionConfig {
+        /** Configuration header. Any data contained in the 'header.data' field
+         * is ignored */
+        @2.0::ISoundTriggerHw.RecognitionConfig header;
+        /** Opaque capture configuration data transparent to the framework */
+        memory data;
+    };
+
+    /**
+     * Load a sound model. Once loaded, recognition of this model can be
+     * started and stopped. Only one active recognition per model at a time.
+     * The SoundTrigger service must handle concurrent recognition requests by
+     * different users/applications on the same model.
+     * The implementation returns a unique handle used by other functions
+     * (unloadSoundModel(), startRecognition*(), etc...
+     *
+     * Must have the exact same semantics as loadSoundModel from
+     * ISoundTriggerHw@2.0 except that the SoundModel uses shared memory
+     * instead of data.
+     *
+     * @param soundModel A SoundModel structure describing the sound model
+     *     to load.
+     * @param callback The callback interface on which the soundmodelCallback*()
+     *     method must be called upon completion.
+     * @param cookie The value of the cookie argument passed to the completion
+     *     callback. This unique context information is assigned and
+     *     used only by the framework.
+     * @return retval Operation completion status: 0 in case of success,
+     *     -EINVAL in case of invalid sound model (e.g 0 data size),
+     *     -ENOSYS in case of invalid operation (e.g max number of models
+     *             exceeded),
+     *     -ENOMEM in case of memory allocation failure,
+     *     -ENODEV in case of initialization error.
+     * @return modelHandle A unique handle assigned by the HAL for use by the
+     *     framework when controlling activity for this sound model.
+     */
+    @callflow(next={"startRecognition_2_1", "setSoundModelParameters", "unloadSoundModel"})
+    loadSoundModel_2_1(SoundModel soundModel,
+                   ISoundTriggerHwCallback callback,
+                   CallbackCookie cookie)
+            generates (int32_t retval, SoundModelHandle modelHandle);
+
+    /**
+     * Load a key phrase sound model. Once loaded, recognition of this model can
+     * be started and stopped. Only one active recognition per model at a time.
+     * The SoundTrigger service must handle concurrent recognition requests by
+     * different users/applications on the same model.
+     * The implementation returns a unique handle used by other functions
+     * (unloadSoundModel(), startRecognition*(), etc...
+     *
+     * Must have the exact same semantics as loadPhraseSoundModel from
+     * ISoundTriggerHw@2.0 except that the PhraseSoundModel uses shared memory
+     * instead of data.
+     *
+     * @param soundModel A PhraseSoundModel structure describing the sound model
+     *     to load.
+     * @param callback The callback interface on which the soundmodelCallback*()
+     *     method must be called upon completion.
+     * @param cookie The value of the cookie argument passed to the completion
+     *     callback. This unique context information is assigned and
+     *     used only by the framework.
+     * @return retval Operation completion status: 0 in case of success,
+     *     -EINVAL in case of invalid sound model (e.g 0 data size),
+     *     -ENOSYS in case of invalid operation (e.g max number of models
+     *             exceeded),
+     *     -ENOMEM in case of memory allocation failure,
+     *     -ENODEV in case of initialization error.
+     * @return modelHandle A unique handle assigned by the HAL for use by the
+     *     framework when controlling activity for this sound model.
+     */
+    @callflow(next={"startRecognition_2_1", "setSoundModelParameters", "unloadSoundModel"})
+    loadPhraseSoundModel_2_1(PhraseSoundModel soundModel,
+                   ISoundTriggerHwCallback callback,
+                   CallbackCookie cookie)
+            generates (int32_t retval, SoundModelHandle modelHandle);
+
+    /**
+     * Start recognition on a given model. Only one recognition active
+     * at a time per model. Once recognition succeeds of fails, the callback
+     * is called.
+     *
+     * Must have the exact same semantics as startRecognition from
+     * ISoundTriggerHw@2.0 except that the RecognitionConfig uses shared memory
+     * instead of data.
+     *
+     * @param modelHandle the handle of the sound model to use for recognition
+     * @param config A RecognitionConfig structure containing attributes of the
+     *     recognition to perform
+     * @param callback The callback interface on which the recognitionCallback()
+     *     method must be called upon recognition.
+     * @param cookie The value of the cookie argument passed to the recognition
+     *     callback. This unique context information is assigned and
+     *     used only by the framework.
+     * @return retval Operation completion status: 0 in case of success,
+     *     -EINVAL in case of invalid recognition attributes,
+     *     -ENOSYS in case of invalid model handle,
+     *     -ENOMEM in case of memory allocation failure,
+     *     -ENODEV in case of initialization error.
+     */
+    @callflow(next={"stopRecognition", "stopAllRecognitions"})
+    startRecognition_2_1(SoundModelHandle modelHandle,
+                     RecognitionConfig config,
+                     ISoundTriggerHwCallback callback,
+                     CallbackCookie cookie)
+            generates (int32_t retval);
+
+
+    struct ParameterValue {
+        string key;
+        string value;
+    };
+
+    /**
+     * Generic method for retrieving vendor-specific parameter values.
+     * The framework does not interpret the parameters, they are passed
+     * in an opaque manner between a vendor application and HAL.
+     *
+     * @param keys parameter keys.
+     * @return retval Operation completion status: 0 in case of success,
+     *     -EINVAL in case of invalid keys,
+     *     -ENOSYS in case if this operation is not supported,
+     *     -ENOMEM in case of memory allocation failure,
+     *     -ENODEV in case of initialization error.
+     * @return parameters parameter key value pairs.
+     */
+    getParameters(vec<string> keys)
+            generates (int32_t retval, vec<ParameterValue> parameters);
+
+    /**
+     * Generic method for setting vendor-specific parameter values.
+     * The framework does not interpret the parameters, they are passed
+     * in an opaque manner between a vendor application and HAL.
+     *
+     * @param parameters parameter key value pairs.
+     * @return retval Operation completion status: 0 in case of success,
+     *     -EINVAL in case of invalid keys,
+     *     -ENOSYS in case if this operation is not supported,
+     *     -ENOMEM in case of memory allocation failure,
+     *     -ENODEV in case of initialization error.
+     */
+    setParameters(vec<ParameterValue> parameters) generates (int32_t retval);
+
+    /**
+     * Generic method for retrieving vendor-specific parameter values.
+     * The framework does not interpret the parameters, they are passed
+     * in an opaque manner between a vendor application and HAL.
+     *
+     * @param modelHandle the handle of the sound model to get parameters about.
+     * @param keys parameter keys.
+     * @return retval Operation completion status: 0 in case of success,
+     *     -EINVAL in case of invalid keys,
+     *     -ENOSYS in case if this operation is not supported,
+     *     -ENOMEM in case of memory allocation failure,
+     *     -ENODEV in case of initialization error.
+     * @return parameters parameter key value pairs.
+     */
+    getSoundModelParameters(SoundModelHandle modelHandle, vec<string> keys)
+            generates (int32_t retval, vec<ParameterValue> parameters);
+
+    /**
+     * Generic method for setting vendor-specific parameter values.
+     * The framework does not interpret the parameters, they are passed
+     * in an opaque manner between a vendor application and HAL.
+     *
+     * @param modelHandle the handle of the sound model to set parameters for.
+     * @param parameters parameter key value pairs.
+     * @return retval Operation completion status: 0 in case of success,
+     *     -EINVAL in case of invalid keys,
+     *     -ENOSYS in case if this operation is not supported,
+     *     -ENOMEM in case of memory allocation failure,
+     *     -ENODEV in case of initialization error.
+     */
+    setSoundModelParameters(
+            SoundModelHandle modelHandle, vec<ParameterValue> parameters)
+            generates (int32_t retval);
+};
diff --git a/soundtrigger/2.1/ISoundTriggerHwCallback.hal b/soundtrigger/2.1/ISoundTriggerHwCallback.hal
new file mode 100644
index 000000000..42e851b8d
--- /dev/null
+++ b/soundtrigger/2.1/ISoundTriggerHwCallback.hal
@@ -0,0 +1,91 @@
+/*
+ * Copyright 2017 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.soundtrigger@2.1;
+
+import @2.0::ISoundTriggerHwCallback;
+import @2.0::PhraseRecognitionExtra;
+
+/**
+ * SoundTrigger HAL Callback interface. Obtained during SoundTrigger setup.
+ */
+@hidl_callback
+interface ISoundTriggerHwCallback extends @2.0::ISoundTriggerHwCallback {
+
+    /**
+     * Generic recognition event sent via recognition callback.
+     */
+    struct RecognitionEvent {
+        /** Event header. Any data contained in the 'header.data' field
+         * is ignored */
+        @2.0::ISoundTriggerHwCallback.RecognitionEvent header;
+        /** Opaque event data */
+        memory data;
+    };
+
+    /**
+     * Specialized recognition event for key phrase recognitions.
+     */
+    struct PhraseRecognitionEvent {
+        /** Common part of the recognition event */
+        RecognitionEvent common;
+        /** List of descriptors for each recognized key phrase */
+        vec<PhraseRecognitionExtra> phraseExtras;
+    };
+
+    /**
+     * Event sent via load sound model callback.
+     */
+    struct ModelEvent {
+        /** Event header. Any data contained in the 'header.data' field
+         * is ignored */
+        @2.0::ISoundTriggerHwCallback.ModelEvent header;
+        /** Opaque event data, passed transparently by the framework */
+        memory data;
+    };
+
+    /**
+     * Callback method called by the HAL when the sound recognition triggers.
+     *
+     * @param event A RecognitionEvent structure containing detailed results
+     *     of the recognition triggered
+     * @param cookie The cookie passed by the framework when recognition was
+     *     started (see ISoundtriggerHw.startRecognition*())
+     */
+    recognitionCallback_2_1(RecognitionEvent event, CallbackCookie cookie);
+
+    /**
+     * Callback method called by the HAL when the sound recognition triggers
+     * for a key phrase sound model.
+     *
+     * @param event A RecognitionEvent structure containing detailed results
+     *     of the recognition triggered
+     * @param cookie The cookie passed by the framework when recognition was
+     *     started (see ISoundtriggerHw.startRecognition*())
+     */
+    phraseRecognitionCallback_2_1(PhraseRecognitionEvent event,
+                                  CallbackCookie cookie);
+
+    /**
+     * Callback method called by the HAL when the sound model loading completes.
+     *
+     * @param event A ModelEvent structure containing detailed results of the
+     *     model loading operation
+     * @param cookie The cookie passed by the framework when loading was
+     *     initiated (see ISoundtriggerHw.loadSoundModel*())
+     */
+    soundModelCallback_2_1(ModelEvent event, CallbackCookie cookie);
+};