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