1/* 2 * Copyright 2019 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.3; 18 19import @2.0::SoundModelHandle; 20import @2.0::ISoundTriggerHwCallback.CallbackCookie; 21import @2.2::ISoundTriggerHw; 22import @2.1::ISoundTriggerHwCallback; 23 24/** 25 * SoundTrigger HAL interface. Used for hardware recognition of hotwords 26 * and other sounds. 27 */ 28interface ISoundTriggerHw extends @2.2::ISoundTriggerHw { 29 30 /** 31 * Retrieve extended implementation properties. 32 * The returned properties includes what is returned from the 33 * getProperties along with expanded implementation details. 34 * 35 * @return retval Operation completion status: 0 in case of success, 36 * -ENODEV in case of initialization error. 37 * @return properties A Properties structure containing implementation 38 * description and capabilities. 39 */ 40 getProperties_2_3() generates (int32_t retval, Properties properties); 41 42 /** 43 * Start recognition on a given model. Only one recognition active 44 * at a time per model. Once recognition succeeds or fails, the callback 45 * associated with the model handle is called. 46 * 47 * Must have the exact same semantics as startRecognition from 48 * ISoundTriggerHw@2.1 except that the RecognitionConfig includes audio 49 * capabilities applied when the recognition is active. 50 * 51 * @param modelHandle the handle of the sound model to use for recognition 52 * @param config A RecognitionConfig structure containing attributes of the 53 * recognition to perform 54 * @return retval Operation completion status: 0 in case of success, 55 * -EINVAL in case of invalid recognition attributes, 56 * -ENOSYS in case of invalid model handle, 57 * -ENOMEM in case of memory allocation failure, 58 * -ENODEV in case of initialization error. 59 */ 60 startRecognition_2_3(SoundModelHandle modelHandle, RecognitionConfig config) 61 generates (int32_t retval); 62 63 /** 64 * Set a model specific parameter with the given value. This parameter 65 * will keep its value for the duration the model is loaded regardless of starting and stopping 66 * recognition. Once the model is unloaded, the value will be lost. 67 * It is expected to check if the handle supports the parameter via the queryParameter 68 * API prior to calling this method. 69 * 70 * @param modelHandle The sound model handle indicating which model to modify parameters 71 * @param modelParam Parameter to set which will be validated against the 72 * ModelParameter type. Not putting ModelParameter type 73 * directly in the definition and validating internally 74 * allows for forward compatibility. 75 * @param value The value to set for the given model parameter 76 * @return status Operation completion status: 0 in case of success, 77 * -ENODEV if the native service cannot be reached 78 * -EINVAL invalid input parameter 79 */ 80 setParameter(SoundModelHandle modelHandle, ModelParameter modelParam, int32_t value) 81 generates (int32_t status); 82 83 /** 84 * Get a model specific parameter. This parameter will keep its value 85 * for the duration the model is loaded regardless of starting and stopping recognition. 86 * Once the model is unloaded, the value will be lost. If the value is not set, a default 87 * value is returned. See ModelParameter for parameter default values. 88 * It is expected to check if the handle supports the parameter via the queryParameter 89 * API prior to calling this method. 90 * 91 * @param modelHandle The sound model associated with given modelParam 92 * @param modelParam Parameter to set which will be validated against the 93 * ModelParameter type. Not putting ModelParameter type 94 * directly in the definition and validating internally 95 * allows for forward compatibility. 96 * @return status Operation completion status: 0 in case of success, 97 * -ENODEV if the native service cannot be reached 98 * -EINVAL invalid input parameter 99 * @return value Value set to the requested parameter. Value is only set when status 100 * indicates success. 101 */ 102 getParameter(SoundModelHandle modelHandle, ModelParameter modelParam) 103 generates (int32_t status, int32_t value); 104 105 /** 106 * Get supported parameter attributes with respect to the provided model 107 * handle. Along with determining the valid range, this API is also used 108 * to determine if a given parameter ID is supported at all by the 109 * modelHandle for use with getParameter and setParameter APIs. 110 * 111 * @param modelHandle The sound model handle indicating which model to query 112 * @param modelParam Parameter to set which will be validated against the 113 * ModelParameter type 114 * @return status Operation completion status: 0 in case of success 115 * -ENODEV if the native service cannot be reached 116 * -EINVAL invalid input parameter 117 * @return retval OptionalModelParameterRange safe union structure wrapping 118 * ModelParameterRange. This structure indicates supported attributes 119 * of the parameter for the given model handle. If the parameter is not 120 * supported the Monostate of the union is used. 121 */ 122 queryParameter(SoundModelHandle modelHandle, ModelParameter modelParam) 123 generates (int32_t status, OptionalModelParameterRange retval); 124}; 125