1 /* 2 * Copyright (C) 2018 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 #ifndef CHRE_PAL_AUDIO_H_ 18 #define CHRE_PAL_AUDIO_H_ 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 23 #include "chre/pal/system.h" 24 #include "chre/pal/version.h" 25 #include "chre_api/chre/audio.h" 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /** 32 * Initial version of the CHRE audio PAL, tied to CHRE API v1.2. 33 */ 34 #define CHRE_PAL_AUDIO_API_V1_2 CHRE_PAL_CREATE_API_VERSION(1, 2) 35 36 // v1.0 and v1.1 skipped to avoid confusion with older versions of the CHRE API. 37 38 #define CHRE_PAL_AUDIO_API_CURRENT_VERSION CHRE_PAL_AUDIO_API_V1_2 39 40 struct chrePalAudioCallbacks { 41 /** 42 * Callback used to pass audio data events to the core CHRE system, which 43 * distributes it to clients (nanoapps). These events are only delivered 44 * while an audio request is open. 45 * 46 * This function call passes ownership of the event memory to the core CHRE 47 * system, i.e. the PAL module must not modify the referenced data until the 48 * associated API function is called to release the memory. 49 * 50 * @param event Event data to distribute to clients. The audio module 51 * must ensure that this memory remains accessible until it is passed 52 * to the releaseAudioDataEvent function in struct chrePalAudioApi. 53 * 54 */ 55 void (*audioDataEventCallback)(struct chreAudioDataEvent *event); 56 57 /** 58 * Callback used to notify that audio availability for a specific handle has 59 * changed. 60 * 61 * @param handle The audio source handle for which audio availability has 62 * changed. 63 * @param available true when the source is available to provide audio 64 * data events, false otherwise. 65 */ 66 void (*audioAvailabilityCallback)(uint32_t handle, bool available); 67 }; 68 69 struct chrePalAudioApi { 70 /** 71 * Version of the module providing this API. This value should be 72 * constructed from CHRE_PAL_CREATE_MODULE_VERSION using the supported 73 * API version constant (CHRE_PAL_AUDIO_API_*) and the module-specific patch 74 * version. 75 */ 76 uint32_t moduleVersion; 77 78 /** 79 * Initializes the audio module. Initialization must complete synchronously. 80 * 81 * @param systemApi Structure containing CHRE system function pointers which 82 * the PAL implementation should prefer to use over equivalent 83 * functionality exposed by the underlying platform. The module does 84 * not need to deep-copy this structure; its memory remains 85 * accessible at least until after close() is called. 86 * @param callbacks Structure containing entry points to the core CHRE 87 * system. The module does not need to deep-copy this structure; its 88 * memory remains accessible at least until after close() is called. 89 * 90 * @return true if initialization was successful, false otherwise 91 */ 92 bool (*open)(const struct chrePalSystemApi *systemApi, 93 const struct chrePalAudioCallbacks *callbacks); 94 95 /** 96 * Performs clean shutdown of the audio module, usually done in preparation 97 * for stopping the CHRE. The audio module must end any active requests to 98 * ensure that it will not invoke any callbacks past this point, and 99 * complete any relevant teardown activities before returning from this 100 * function. 101 */ 102 void (*close)(void); 103 104 /** 105 * Requests an audio data event from the platform for the provided handle. A 106 * call to this method must cancel any previous request. 107 * 108 * The event requested here may contain data from previously posted events. 109 * The concept is to allow the platform to manage its own buffers for audio 110 * data. If a request comes in for 8000 samples of data and the most recent 111 * request was for 4000 samples of data, the platform implementation may 112 * reuse the existing 4000 samples of data and append 4000 samples of new 113 * data (assuming that the arguments passed here allow that). 114 * 115 * Once a request for a given source has been made, the platform 116 * implementation must maintain a buffer of previously collected audio 117 * samples to provide when a request comes in for data in the past (up to 118 * the maximum buffer size for this source). This happens when numSamples at 119 * the source sample rate is a greater amount of time than eventDelay. This 120 * buffer can be released once cancelAudioDataEventRequest has been invoked 121 * for a given source. 122 * 123 * The event is provided to the client through the audioDataEventCallback. 124 * 125 * @param handle The handle for which an audio event is requested. 126 * @param numSamples The number of samples to send once the request has been 127 * completed. 128 * @param eventDelayNs The amount of time that must pass before providing 129 * the data event via the audioDataEventCallback. 130 */ 131 bool (*requestAudioDataEvent)(uint32_t handle, uint32_t numSamples, 132 uint64_t eventDelayNs); 133 134 /** 135 * Cancels the previous call to requestAudioDataEvent. No audio data is 136 * allowed to be posted to CHRE after this function has been called and 137 * before the next call to requestAudioDataEvent for the supplied handle. 138 * 139 * @param handle The handle for which the most recent call to 140 * requestAudioDataEvent will be cancelled. 141 */ 142 void (*cancelAudioDataEvent)(uint32_t handle); 143 144 /** 145 * Releases a previously posted audio event. This will be invoked by CHRE to 146 * say that all nanoapps have processed the previously posted data event. 147 * 148 * @param event An audio data event that was previously provided to 149 * CHRE as a result of a request for audio data. 150 */ 151 void (*releaseAudioDataEvent)(struct chreAudioDataEvent *event); 152 153 /** 154 * @return the number of sources supported by the implementation. The 155 * returned value must be exactly one greater than the maximum supported 156 * audio handle. 157 */ 158 uint32_t (*getSourceCount)(void); 159 160 /** 161 * Obtains the audio source description for a given handle. 162 * 163 * @param handle the handle for the requested audio source. 164 * @param audioSource the chreAudioSource to populate with details of the 165 * audio source. This pointer must never be null. 166 */ 167 bool (*getAudioSource)(uint32_t handle, struct chreAudioSource *audioSource); 168 }; 169 170 /** 171 * Retrieve a handle for the CHRE audio PAL. 172 * 173 * @param requestedApiVersion The implementation of this function must return a 174 * pointer to a structure with the same major version as requested. 175 * 176 * @return Pointer to API handle, or NULL if a compatible API version is not 177 * supported by the module, or the API as a whole is not implemented. If 178 * non-NULL, the returned API handle must be valid as long as this 179 * module is loaded. 180 */ 181 const struct chrePalAudioApi *chrePalAudioGetApi(uint32_t requestedApiVersion); 182 183 #ifdef __cplusplus 184 } 185 #endif 186 187 #endif // CHRE_PAL_AUDIO_H_ 188