Home | History | Annotate | Download | only in hardware 
      1 /*
      2  * Copyright (C) 2014 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 
     17 #include <system/audio.h>
     18 #include <system/sound_trigger.h>
     19 #include <hardware/hardware.h>
     20 
     21 #ifndef ANDROID_SOUND_TRIGGER_HAL_H
     22 #define ANDROID_SOUND_TRIGGER_HAL_H
     23 
     24 
     25 __BEGIN_DECLS
     26 
     27 /**
     28  * The id of this module
     29  */
     30 #define SOUND_TRIGGER_HARDWARE_MODULE_ID "sound_trigger"
     31 
     32 /**
     33  * Name of the audio devices to open
     34  */
     35 #define SOUND_TRIGGER_HARDWARE_INTERFACE "sound_trigger_hw_if"
     36 
     37 #define SOUND_TRIGGER_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
     38 #define SOUND_TRIGGER_MODULE_API_VERSION_CURRENT SOUND_TRIGGER_MODULE_API_VERSION_1_0
     39 
     40 
     41 #define SOUND_TRIGGER_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
     42 #define SOUND_TRIGGER_DEVICE_API_VERSION_CURRENT SOUND_TRIGGER_DEVICE_API_VERSION_1_0
     43 
     44 /**
     45  * List of known sound trigger HAL modules. This is the base name of the sound_trigger HAL
     46  * library composed of the "sound_trigger." prefix, one of the base names below and
     47  * a suffix specific to the device.
     48  * e.g: sondtrigger.primary.goldfish.so or sound_trigger.primary.default.so
     49  */
     50 
     51 #define SOUND_TRIGGER_HARDWARE_MODULE_ID_PRIMARY "primary"
     52 
     53 
     54 /**
     55  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
     56  * and the fields of this data structure must begin with hw_module_t
     57  * followed by module specific information.
     58  */
     59 struct sound_trigger_module {
     60     struct hw_module_t common;
     61 };
     62 
     63 typedef void (*recognition_callback_t)(struct sound_trigger_recognition_event *event, void *cookie);
     64 typedef void (*sound_model_callback_t)(struct sound_trigger_model_event *event, void *cookie);
     65 
     66 struct sound_trigger_hw_device {
     67     struct hw_device_t common;
     68 
     69     /*
     70      * Retrieve implementation properties.
     71      */
     72     int (*get_properties)(const struct sound_trigger_hw_device *dev,
     73                           struct sound_trigger_properties *properties);
     74 
     75     /*
     76      * Load a sound model. Once loaded, recognition of this model can be started and stopped.
     77      * Only one active recognition per model at a time. The SoundTrigger service will handle
     78      * concurrent recognition requests by different users/applications on the same model.
     79      * The implementation returns a unique handle used by other functions (unload_sound_model(),
     80      * start_recognition(), etc...
     81      */
     82     int (*load_sound_model)(const struct sound_trigger_hw_device *dev,
     83                             struct sound_trigger_sound_model *sound_model,
     84                             sound_model_callback_t callback,
     85                             void *cookie,
     86                             sound_model_handle_t *handle);
     87 
     88     /*
     89      * Unload a sound model. A sound model can be unloaded to make room for a new one to overcome
     90      * implementation limitations.
     91      */
     92     int (*unload_sound_model)(const struct sound_trigger_hw_device *dev,
     93                               sound_model_handle_t handle);
     94 
     95     /* Start recognition on a given model. Only one recognition active at a time per model.
     96      * Once recognition succeeds of fails, the callback is called.
     97      * TODO: group recognition configuration parameters into one struct and add key phrase options.
     98      */
     99     int (*start_recognition)(const struct sound_trigger_hw_device *dev,
    100                              sound_model_handle_t sound_model_handle,
    101                              const struct sound_trigger_recognition_config *config,
    102                              recognition_callback_t callback,
    103                              void *cookie);
    104 
    105     /* Stop recognition on a given model.
    106      * The implementation does not have to call the callback when stopped via this method.
    107      */
    108     int (*stop_recognition)(const struct sound_trigger_hw_device *dev,
    109                            sound_model_handle_t sound_model_handle);
    110 };
    111 
    112 typedef struct sound_trigger_hw_device sound_trigger_hw_device_t;
    113 
    114 /** convenience API for opening and closing a supported device */
    115 
    116 static inline int sound_trigger_hw_device_open(const struct hw_module_t* module,
    117                                        struct sound_trigger_hw_device** device)
    118 {
    119     return module->methods->open(module, SOUND_TRIGGER_HARDWARE_INTERFACE,
    120                                  (struct hw_device_t**)device);
    121 }
    122 
    123 static inline int sound_trigger_hw_device_close(struct sound_trigger_hw_device* device)
    124 {
    125     return device->common.close(&device->common);
    126 }
    127 
    128 __END_DECLS
    129 
    130 #endif  // ANDROID_SOUND_TRIGGER_HAL_H
    131