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