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
diff --git a/soundtrigger/2.1/ISoundTriggerHw.hal b/soundtrigger/2.1/ISoundTriggerHw.hal
new file mode 100644
index 0000000..2f2e73a
--- /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);
+};