1/* 2 * Copyright 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.soundtrigger@2.1; 18 19import @2.0::ISoundTriggerHw; 20import @2.0::ISoundTriggerHwCallback.CallbackCookie; 21import @2.0::SoundModelHandle; 22 23import ISoundTriggerHwCallback; 24 25/** 26 * SoundTrigger HAL interface. Used for hardware recognition of hotwords. 27 */ 28interface ISoundTriggerHw extends @2.0::ISoundTriggerHw { 29 30 /** 31 * Base sound model descriptor. This struct is the header of a larger block 32 * passed to loadSoundModel_2_1() and contains the binary data of the 33 * sound model. 34 */ 35 struct SoundModel { 36 /** Sound model header. Any data contained in the 'header.data' field 37 * is ignored */ 38 @2.0::ISoundTriggerHw.SoundModel header; 39 /** Opaque data transparent to Android framework */ 40 memory data; 41 }; 42 43 /** 44 * Specialized sound model for key phrase detection. 45 * Proprietary representation of key phrases in binary data must match 46 * information indicated by phrases field. 47 */ 48 struct PhraseSoundModel { 49 /** Common part of sound model descriptor */ 50 SoundModel common; 51 /** List of descriptors for key phrases supported by this sound model */ 52 vec<Phrase> phrases; 53 }; 54 55 /** 56 * Configuration for sound trigger capture session passed to 57 * startRecognition_2_1() method. 58 */ 59 struct RecognitionConfig { 60 /** Configuration header. Any data contained in the 'header.data' field 61 * is ignored */ 62 @2.0::ISoundTriggerHw.RecognitionConfig header; 63 /** Opaque capture configuration data transparent to the framework */ 64 memory data; 65 }; 66 67 /** 68 * Load a sound model. Once loaded, recognition of this model can be 69 * started and stopped. Only one active recognition per model at a time. 70 * The SoundTrigger service must handle concurrent recognition requests by 71 * different users/applications on the same model. 72 * The implementation returns a unique handle used by other functions 73 * (unloadSoundModel(), startRecognition*(), etc... 74 * 75 * Must have the exact same semantics as loadSoundModel from 76 * ISoundTriggerHw@2.0 except that the SoundModel uses shared memory 77 * instead of data. 78 * 79 * @param soundModel A SoundModel structure describing the sound model 80 * to load. 81 * @param callback The callback interface on which the soundmodelCallback*() 82 * method must be called upon completion. 83 * @param cookie The value of the cookie argument passed to the completion 84 * callback. This unique context information is assigned and 85 * used only by the framework. 86 * @return retval Operation completion status: 0 in case of success, 87 * -EINVAL in case of invalid sound model (e.g 0 data size), 88 * -ENOSYS in case of invalid operation (e.g max number of models 89 * exceeded), 90 * -ENOMEM in case of memory allocation failure, 91 * -ENODEV in case of initialization error. 92 * @return modelHandle A unique handle assigned by the HAL for use by the 93 * framework when controlling activity for this sound model. 94 */ 95 @callflow(next={"startRecognition_2_1", "unloadSoundModel"}) 96 loadSoundModel_2_1(SoundModel soundModel, 97 ISoundTriggerHwCallback callback, 98 CallbackCookie cookie) 99 generates (int32_t retval, SoundModelHandle modelHandle); 100 101 /** 102 * Load a key phrase sound model. Once loaded, recognition of this model can 103 * be started and stopped. Only one active recognition per model at a time. 104 * The SoundTrigger service must handle concurrent recognition requests by 105 * different users/applications on the same model. 106 * The implementation returns a unique handle used by other functions 107 * (unloadSoundModel(), startRecognition*(), etc... 108 * 109 * Must have the exact same semantics as loadPhraseSoundModel from 110 * ISoundTriggerHw@2.0 except that the PhraseSoundModel uses shared memory 111 * instead of data. 112 * 113 * @param soundModel A PhraseSoundModel structure describing the sound model 114 * to load. 115 * @param callback The callback interface on which the soundmodelCallback*() 116 * method must be called upon completion. 117 * @param cookie The value of the cookie argument passed to the completion 118 * callback. This unique context information is assigned and 119 * used only by the framework. 120 * @return retval Operation completion status: 0 in case of success, 121 * -EINVAL in case of invalid sound model (e.g 0 data size), 122 * -ENOSYS in case of invalid operation (e.g max number of models 123 * exceeded), 124 * -ENOMEM in case of memory allocation failure, 125 * -ENODEV in case of initialization error. 126 * @return modelHandle A unique handle assigned by the HAL for use by the 127 * framework when controlling activity for this sound model. 128 */ 129 @callflow(next={"startRecognition_2_1", "unloadSoundModel"}) 130 loadPhraseSoundModel_2_1(PhraseSoundModel soundModel, 131 ISoundTriggerHwCallback callback, 132 CallbackCookie cookie) 133 generates (int32_t retval, SoundModelHandle modelHandle); 134 135 /** 136 * Start recognition on a given model. Only one recognition active 137 * at a time per model. Once recognition succeeds of fails, the callback 138 * is called. 139 * 140 * Must have the exact same semantics as startRecognition from 141 * ISoundTriggerHw@2.0 except that the RecognitionConfig uses shared memory 142 * instead of data. 143 * 144 * @param modelHandle the handle of the sound model to use for recognition 145 * @param config A RecognitionConfig structure containing attributes of the 146 * recognition to perform 147 * @param callback The callback interface on which the recognitionCallback() 148 * method must be called upon recognition. 149 * @param cookie The value of the cookie argument passed to the recognition 150 * callback. This unique context information is assigned and 151 * used only by the framework. 152 * @return retval Operation completion status: 0 in case of success, 153 * -EINVAL in case of invalid recognition attributes, 154 * -ENOSYS in case of invalid model handle, 155 * -ENOMEM in case of memory allocation failure, 156 * -ENODEV in case of initialization error. 157 */ 158 @callflow(next={"stopRecognition", "stopAllRecognitions"}) 159 startRecognition_2_1(SoundModelHandle modelHandle, 160 RecognitionConfig config, 161 ISoundTriggerHwCallback callback, 162 CallbackCookie cookie) 163 generates (int32_t retval); 164}; 165