/* * 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", "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", "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); };