1 /* 2 * Copyright (C) 2004-2010 NXP Software 3 * Copyright (C) 2010 The Android Open Source Project 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /****************************************************************************************/ 19 /* */ 20 /* Header file for the application layer interface of Concert Sound and Concert */ 21 /* Sound EX. */ 22 /* */ 23 /* This files includes all definitions, types, structures and function */ 24 /* prototypes required by the calling layer. All other types, structures and */ 25 /* functions are private. */ 26 /* */ 27 /****************************************************************************************/ 28 /* */ 29 /* Note: 1 */ 30 /* ======= */ 31 /* The algorithm can execute either with separate input and output buffers or with */ 32 /* a common buffer, i.e. the data is processed in-place. If the buffers are the */ 33 /* same then the MIPs will be slightly higher and an extra stereo scratch buffer is */ 34 /* required. */ 35 /* */ 36 /****************************************************************************************/ 37 /* */ 38 /* Note: 2 */ 39 /* ======= */ 40 /* Two data formats are support Stereo and Mono-In-Stereo. The data is interleaved as */ 41 /* follows: */ 42 /* Byte Offset Stereo Input Mono-In-Stereo Input */ 43 /* =========== ============ ==================== */ 44 /* 0 Left Sample #1 Mono Sample #1 */ 45 /* 2 Right Sample #1 Mono Sample #1 */ 46 /* 4 Left Sample #2 Mono Sample #2 */ 47 /* 6 Right Sample #2 Mono Sample #2 */ 48 /* . . . */ 49 /* . . . */ 50 /* */ 51 /* Mono format data is not supported, the calling routine must convert a Mono stream */ 52 /* in to Mono-In-Stereo format. */ 53 /* */ 54 /****************************************************************************************/ 55 56 #ifndef LVCS_H 57 #define LVCS_H 58 59 /****************************************************************************************/ 60 /* */ 61 /* Includes */ 62 /* */ 63 /****************************************************************************************/ 64 65 #include "LVM_Types.h" 66 #include "LVM_Common.h" 67 68 /****************************************************************************************/ 69 /* */ 70 /* Definitions */ 71 /* */ 72 /****************************************************************************************/ 73 74 /* Memory table */ 75 #define LVCS_MEMREGION_PERSISTENT_SLOW_DATA 0 /* Offset to the instance memory region */ 76 #define LVCS_MEMREGION_PERSISTENT_FAST_DATA 1 /* Offset to the persistent data memory region */ 77 #define LVCS_MEMREGION_PERSISTENT_FAST_COEF 2 /* Offset to the persistent coefficient memory region */ 78 #define LVCS_MEMREGION_TEMPORARY_FAST 3 /* Offset to temporary memory region */ 79 #define LVCS_NR_MEMORY_REGIONS 4 /* Number of memory regions */ 80 81 /* Effect Level */ 82 #define LVCS_EFFECT_LOW 16384 /* Effect scaling 50% */ 83 #define LVCS_EFFECT_MEDIUM 24576 /* Effect scaling 75% */ 84 #define LVCS_EFFECT_HIGH 32767 /* Effect Scaling 100% */ 85 86 /* Callback events */ 87 #define LVCS_EVENT_NONE 0x0000 /* Not a valid event */ 88 #define LVCS_EVENT_ALGOFF 0x0001 /* CS has completed switch off */ 89 90 /****************************************************************************************/ 91 /* */ 92 /* Types */ 93 /* */ 94 /****************************************************************************************/ 95 96 /* Instance handle */ 97 typedef void *LVCS_Handle_t; 98 99 /* Operating modes */ 100 typedef enum 101 { 102 LVCS_OFF = 0, 103 LVCS_ON = 15, 104 LVCS_MAX = LVM_MAXENUM 105 } LVCS_Modes_en; 106 107 /* Memory Types */ 108 typedef enum 109 { 110 LVCS_SCRATCH = 0, 111 LVCS_DATA = 1, 112 LVCS_COEFFICIENT = 2, 113 LVCS_PERSISTENT = 3, 114 LVCS_MEMORYTYPE_MAX = LVM_MAXENUM 115 } LVCS_MemoryTypes_en; 116 117 /* Function return status */ 118 typedef enum 119 { 120 LVCS_SUCCESS = 0, /* Successful return from a routine */ 121 LVCS_ALIGNMENTERROR = 1, /* Memory alignment error */ 122 LVCS_NULLADDRESS = 2, /* NULL allocation address */ 123 LVCS_TOOMANYSAMPLES = 3, /* Maximum block size exceeded */ 124 LVCS_INVALIDBUFFER = 4, /* Invalid buffer processing request */ 125 LVCS_STATUSMAX = LVM_MAXENUM 126 } LVCS_ReturnStatus_en; 127 128 /* 129 * Source data formats 130 */ 131 typedef enum 132 { 133 LVCS_STEREO = 0, 134 LVCS_MONOINSTEREO = 1, 135 LVCS_SOURCEMAX = LVM_MAXENUM 136 } LVCS_SourceFormat_en; 137 138 /* 139 * Supported output devices 140 */ 141 typedef enum 142 { 143 LVCS_HEADPHONES = 0, 144 LVCS_EX_HEADPHONES = 1, 145 LVCS_SPEAKERTYPE_MAX = LVM_MAXENUM 146 } LVCS_SpeakerType_en; 147 148 /* 149 * Speaker Coefficients Table 150 */ 151 typedef struct 152 { 153 void *pTable1; 154 void *pTable2; 155 void *pTable3; 156 void *pTable4; 157 void *pTable5; 158 void *pTable6; 159 void *pTable7; 160 void *pTable8; 161 } LVCS_CSMS_Coef_Tables_t; 162 163 /****************************************************************************************/ 164 /* */ 165 /* Structures */ 166 /* */ 167 /****************************************************************************************/ 168 169 /* Memory region definition */ 170 typedef struct 171 { 172 LVM_UINT32 Size; /* Region size in bytes */ 173 LVCS_MemoryTypes_en Type; /* Region type */ 174 void *pBaseAddress; /* Pointer to the region base address */ 175 } LVCS_MemoryRegion_t; 176 177 /* Memory table containing the region definitions */ 178 typedef struct 179 { 180 LVCS_MemoryRegion_t Region[LVCS_NR_MEMORY_REGIONS]; /* One definition for each region */ 181 } LVCS_MemTab_t; 182 183 /* Concert Sound parameter structure */ 184 typedef struct 185 { 186 LVCS_Modes_en OperatingMode; /* Algorithm mode */ 187 LVCS_SpeakerType_en SpeakerType; /* Output device type */ 188 LVCS_SourceFormat_en SourceFormat; /* Source data format */ 189 LVM_Mode_en CompressorMode; /* Non-Linear Compressor Mode */ 190 LVM_Fs_en SampleRate; /* Sampling rate */ 191 LVM_INT16 EffectLevel; /* Effect level */ 192 LVM_UINT16 ReverbLevel; /* Reverb level in % */ 193 #ifdef SUPPORT_MC 194 LVM_INT32 NrChannels; 195 #endif 196 } LVCS_Params_t; 197 198 /* Concert Sound Capability structure */ 199 typedef struct 200 { 201 /* General parameters */ 202 LVM_UINT16 MaxBlockSize; /* Maximum block size in sample pairs */ 203 204 /* Callback parameters */ 205 LVM_Callback CallBack; /* Bundle callback */ 206 void *pBundleInstance; /* Bundle instance handle */ 207 208 } LVCS_Capabilities_t; 209 210 /****************************************************************************************/ 211 /* */ 212 /* Function Prototypes */ 213 /* */ 214 /****************************************************************************************/ 215 216 /****************************************************************************************/ 217 /* */ 218 /* FUNCTION: LVCS_Memory */ 219 /* */ 220 /* DESCRIPTION: */ 221 /* This function is used for memory allocation and free. It can be called in */ 222 /* two ways: */ 223 /* */ 224 /* hInstance = NULL Returns the memory requirements */ 225 /* hInstance = Instance handle Returns the memory requirements and */ 226 /* allocated base addresses for the instance */ 227 /* */ 228 /* When this function is called for memory allocation (hInstance=NULL) it is */ 229 /* passed the default capabilities, of these only the buffer processing setting is */ 230 /* used. */ 231 /* */ 232 /* When called for memory allocation the memory base address pointers are NULL on */ 233 /* return. */ 234 /* */ 235 /* When the function is called for free (hInstance = Instance Handle) the */ 236 /* capabilities are ignored and the memory table returns the allocated memory and */ 237 /* base addresses used during initialisation. */ 238 /* */ 239 /* PARAMETERS: */ 240 /* hInstance Instance Handle */ 241 /* pMemoryTable Pointer to an empty memory definition table */ 242 /* pCapabilities Pointer to the default capabilites */ 243 /* */ 244 /* RETURNS: */ 245 /* LVCS_Success Succeeded */ 246 /* */ 247 /* NOTES: */ 248 /* 1. This function may be interrupted by the LVCS_Process function */ 249 /* */ 250 /****************************************************************************************/ 251 252 LVCS_ReturnStatus_en LVCS_Memory(LVCS_Handle_t hInstance, 253 LVCS_MemTab_t *pMemoryTable, 254 LVCS_Capabilities_t *pCapabilities); 255 256 /****************************************************************************************/ 257 /* */ 258 /* FUNCTION: LVCS_Init */ 259 /* */ 260 /* DESCRIPTION: */ 261 /* Create and initialisation function for the Concert Sound module */ 262 /* */ 263 /* This function can be used to create an algorithm instance by calling with */ 264 /* hInstance set to NULL. In this case the algorithm returns the new instance */ 265 /* handle. */ 266 /* */ 267 /* This function can be used to force a full re-initialisation of the algorithm */ 268 /* by calling with hInstance = Instance Handle. In this case the memory table */ 269 /* should be correct for the instance, this can be ensured by calling the function */ 270 /* LVCS_Memory before calling this function. */ 271 /* */ 272 /* PARAMETERS: */ 273 /* hInstance Instance handle */ 274 /* pMemoryTable Pointer to the memory definition table */ 275 /* pCapabilities Pointer to the initialisation capabilities */ 276 /* */ 277 /* RETURNS: */ 278 /* LVCS_Success Initialisation succeeded */ 279 /* LVCS_AlignmentError Instance or scratch memory on incorrect alignment */ 280 /* LVCS_NullAddress Instance or scratch memory has a NULL pointer */ 281 /* */ 282 /* NOTES: */ 283 /* 1. The instance handle is the pointer to the base address of the first memory */ 284 /* region. */ 285 /* 2. This function must not be interrupted by the LVCS_Process function */ 286 /* */ 287 /****************************************************************************************/ 288 289 LVCS_ReturnStatus_en LVCS_Init(LVCS_Handle_t *phInstance, 290 LVCS_MemTab_t *pMemoryTable, 291 LVCS_Capabilities_t *pCapabilities); 292 293 /****************************************************************************************/ 294 /* */ 295 /* FUNCTION: LVCS_GetParameters */ 296 /* */ 297 /* DESCRIPTION: */ 298 /* Request the Concert Sound parameters. The current parameter set is returned */ 299 /* via the parameter pointer. */ 300 /* */ 301 /* PARAMETERS: */ 302 /* hInstance Instance handle */ 303 /* pParams Pointer to an empty parameter structure */ 304 /* */ 305 /* RETURNS: */ 306 /* LVCS_Success Always succeeds */ 307 /* */ 308 /* NOTES: */ 309 /* 1. This function may be interrupted by the LVCS_Process function */ 310 /* */ 311 /****************************************************************************************/ 312 313 LVCS_ReturnStatus_en LVCS_GetParameters(LVCS_Handle_t hInstance, 314 LVCS_Params_t *pParams); 315 316 /****************************************************************************************/ 317 /* */ 318 /* FUNCTION: LVCS_Control */ 319 /* */ 320 /* DESCRIPTION: */ 321 /* Sets or changes the Concert Sound parameters. */ 322 /* */ 323 /* PARAMETERS: */ 324 /* hInstance Instance handle */ 325 /* pParams Pointer to a parameter structure */ 326 /* */ 327 /* RETURNS: */ 328 /* LVCS_Success Succeeded */ 329 /* */ 330 /* NOTES: */ 331 /* 1. This function must not be interrupted by the LVCS_Process function */ 332 /* */ 333 /****************************************************************************************/ 334 335 LVCS_ReturnStatus_en LVCS_Control(LVCS_Handle_t hInstance, 336 LVCS_Params_t *pParams); 337 338 /****************************************************************************************/ 339 /* */ 340 /* FUNCTION: LVCS_Process */ 341 /* */ 342 /* DESCRIPTION: */ 343 /* Process function for the Concert Sound module. The implementation supports two */ 344 /* variants of the algorithm, one for headphones and one for mobile speakers. */ 345 /* */ 346 /* PARAMETERS: */ 347 /* hInstance Instance handle */ 348 /* pInData Pointer to the input data */ 349 /* pOutData Pointer to the output data */ 350 /* NumSamples Number of samples in the input buffer */ 351 /* */ 352 /* RETURNS: */ 353 /* LVCS_Success Succeeded */ 354 /* LVCS_TooManySamples NumSamples was larger than the maximum block size */ 355 /* */ 356 /* NOTES: */ 357 /* */ 358 /****************************************************************************************/ 359 LVCS_ReturnStatus_en LVCS_Process(LVCS_Handle_t hInstance, 360 const LVM_FLOAT *pInData, 361 LVM_FLOAT *pOutData, 362 LVM_UINT16 NumSamples); 363 364 #endif /* LVCS_H */ 365