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 #ifdef __cplusplus 60 extern "C" { 61 #endif /* __cplusplus */ 62 63 64 /****************************************************************************************/ 65 /* */ 66 /* Includes */ 67 /* */ 68 /****************************************************************************************/ 69 70 #include "LVM_Types.h" 71 #include "LVM_Common.h" 72 73 74 /****************************************************************************************/ 75 /* */ 76 /* Definitions */ 77 /* */ 78 /****************************************************************************************/ 79 80 /* Memory table */ 81 #define LVCS_MEMREGION_PERSISTENT_SLOW_DATA 0 /* Offset to the instance memory region */ 82 #define LVCS_MEMREGION_PERSISTENT_FAST_DATA 1 /* Offset to the persistent data memory region */ 83 #define LVCS_MEMREGION_PERSISTENT_FAST_COEF 2 /* Offset to the persistent coefficient memory region */ 84 #define LVCS_MEMREGION_TEMPORARY_FAST 3 /* Offset to temporary memory region */ 85 #define LVCS_NR_MEMORY_REGIONS 4 /* Number of memory regions */ 86 87 /* Effect Level */ 88 #define LVCS_EFFECT_LOW 16384 /* Effect scaling 50% */ 89 #define LVCS_EFFECT_MEDIUM 24576 /* Effect scaling 75% */ 90 #define LVCS_EFFECT_HIGH 32767 /* Effect Scaling 100% */ 91 92 /* Callback events */ 93 #define LVCS_EVENT_NONE 0x0000 /* Not a valid event */ 94 #define LVCS_EVENT_ALGOFF 0x0001 /* CS has completed switch off */ 95 96 97 /****************************************************************************************/ 98 /* */ 99 /* Types */ 100 /* */ 101 /****************************************************************************************/ 102 103 /* Instance handle */ 104 typedef void *LVCS_Handle_t; 105 106 107 /* Operating modes */ 108 typedef enum 109 { 110 LVCS_OFF = 0, 111 LVCS_ON = 15, 112 LVCS_MAX = LVM_MAXENUM 113 } LVCS_Modes_en; 114 115 116 /* Memory Types */ 117 typedef enum 118 { 119 LVCS_SCRATCH = 0, 120 LVCS_DATA = 1, 121 LVCS_COEFFICIENT = 2, 122 LVCS_PERSISTENT = 3, 123 LVCS_MEMORYTYPE_MAX = LVM_MAXENUM 124 } LVCS_MemoryTypes_en; 125 126 127 /* Function return status */ 128 typedef enum 129 { 130 LVCS_SUCCESS = 0, /* Successful return from a routine */ 131 LVCS_ALIGNMENTERROR = 1, /* Memory alignment error */ 132 LVCS_NULLADDRESS = 2, /* NULL allocation address */ 133 LVCS_TOOMANYSAMPLES = 3, /* Maximum block size exceeded */ 134 LVCS_INVALIDBUFFER = 4, /* Invalid buffer processing request */ 135 LVCS_STATUSMAX = LVM_MAXENUM 136 } LVCS_ReturnStatus_en; 137 138 139 /* 140 * Source data formats 141 */ 142 typedef enum 143 { 144 LVCS_STEREO = 0, 145 LVCS_MONOINSTEREO = 1, 146 LVCS_SOURCEMAX = LVM_MAXENUM 147 } LVCS_SourceFormat_en; 148 149 150 /* 151 * Supported output devices 152 */ 153 typedef enum 154 { 155 LVCS_HEADPHONES = 0, 156 LVCS_EX_HEADPHONES = 1, 157 LVCS_SPEAKERTYPE_MAX = LVM_MAXENUM 158 } LVCS_SpeakerType_en; 159 160 /* 161 * Speaker Coefficients Table 162 */ 163 typedef struct 164 { 165 void *pTable1; 166 void *pTable2; 167 void *pTable3; 168 void *pTable4; 169 void *pTable5; 170 void *pTable6; 171 void *pTable7; 172 void *pTable8; 173 } LVCS_CSMS_Coef_Tables_t; 174 175 176 /****************************************************************************************/ 177 /* */ 178 /* Structures */ 179 /* */ 180 /****************************************************************************************/ 181 182 /* Memory region definition */ 183 typedef struct 184 { 185 LVM_UINT32 Size; /* Region size in bytes */ 186 LVCS_MemoryTypes_en Type; /* Region type */ 187 void *pBaseAddress; /* Pointer to the region base address */ 188 } LVCS_MemoryRegion_t; 189 190 191 /* Memory table containing the region definitions */ 192 typedef struct 193 { 194 LVCS_MemoryRegion_t Region[LVCS_NR_MEMORY_REGIONS]; /* One definition for each region */ 195 } LVCS_MemTab_t; 196 197 198 /* Concert Sound parameter structure */ 199 typedef struct 200 { 201 LVCS_Modes_en OperatingMode; /* Algorithm mode */ 202 LVCS_SpeakerType_en SpeakerType; /* Output device type */ 203 LVCS_SourceFormat_en SourceFormat; /* Source data format */ 204 LVM_Mode_en CompressorMode; /* Non-Linear Compressor Mode */ 205 LVM_Fs_en SampleRate; /* Sampling rate */ 206 LVM_INT16 EffectLevel; /* Effect level */ 207 LVM_UINT16 ReverbLevel; /* Reverb level in % */ 208 #ifdef SUPPORT_MC 209 LVM_INT32 NrChannels; 210 #endif 211 } LVCS_Params_t; 212 213 214 /* Concert Sound Capability structure */ 215 typedef struct 216 { 217 /* General parameters */ 218 LVM_UINT16 MaxBlockSize; /* Maximum block size in sample pairs */ 219 220 /* Callback parameters */ 221 LVM_Callback CallBack; /* Bundle callback */ 222 void *pBundleInstance; /* Bundle instance handle */ 223 224 } LVCS_Capabilities_t; 225 226 227 /****************************************************************************************/ 228 /* */ 229 /* Function Prototypes */ 230 /* */ 231 /****************************************************************************************/ 232 233 /****************************************************************************************/ 234 /* */ 235 /* FUNCTION: LVCS_Memory */ 236 /* */ 237 /* DESCRIPTION: */ 238 /* This function is used for memory allocation and free. It can be called in */ 239 /* two ways: */ 240 /* */ 241 /* hInstance = NULL Returns the memory requirements */ 242 /* hInstance = Instance handle Returns the memory requirements and */ 243 /* allocated base addresses for the instance */ 244 /* */ 245 /* When this function is called for memory allocation (hInstance=NULL) it is */ 246 /* passed the default capabilities, of these only the buffer processing setting is */ 247 /* used. */ 248 /* */ 249 /* When called for memory allocation the memory base address pointers are NULL on */ 250 /* return. */ 251 /* */ 252 /* When the function is called for free (hInstance = Instance Handle) the */ 253 /* capabilities are ignored and the memory table returns the allocated memory and */ 254 /* base addresses used during initialisation. */ 255 /* */ 256 /* PARAMETERS: */ 257 /* hInstance Instance Handle */ 258 /* pMemoryTable Pointer to an empty memory definition table */ 259 /* pCapabilities Pointer to the default capabilites */ 260 /* */ 261 /* RETURNS: */ 262 /* LVCS_Success Succeeded */ 263 /* */ 264 /* NOTES: */ 265 /* 1. This function may be interrupted by the LVCS_Process function */ 266 /* */ 267 /****************************************************************************************/ 268 269 LVCS_ReturnStatus_en LVCS_Memory(LVCS_Handle_t hInstance, 270 LVCS_MemTab_t *pMemoryTable, 271 LVCS_Capabilities_t *pCapabilities); 272 273 274 /****************************************************************************************/ 275 /* */ 276 /* FUNCTION: LVCS_Init */ 277 /* */ 278 /* DESCRIPTION: */ 279 /* Create and initialisation function for the Concert Sound module */ 280 /* */ 281 /* This function can be used to create an algorithm instance by calling with */ 282 /* hInstance set to NULL. In this case the algorithm returns the new instance */ 283 /* handle. */ 284 /* */ 285 /* This function can be used to force a full re-initialisation of the algorithm */ 286 /* by calling with hInstance = Instance Handle. In this case the memory table */ 287 /* should be correct for the instance, this can be ensured by calling the function */ 288 /* LVCS_Memory before calling this function. */ 289 /* */ 290 /* PARAMETERS: */ 291 /* hInstance Instance handle */ 292 /* pMemoryTable Pointer to the memory definition table */ 293 /* pCapabilities Pointer to the initialisation capabilities */ 294 /* */ 295 /* RETURNS: */ 296 /* LVCS_Success Initialisation succeeded */ 297 /* LVCS_AlignmentError Instance or scratch memory on incorrect alignment */ 298 /* LVCS_NullAddress Instance or scratch memory has a NULL pointer */ 299 /* */ 300 /* NOTES: */ 301 /* 1. The instance handle is the pointer to the base address of the first memory */ 302 /* region. */ 303 /* 2. This function must not be interrupted by the LVCS_Process function */ 304 /* */ 305 /****************************************************************************************/ 306 307 LVCS_ReturnStatus_en LVCS_Init(LVCS_Handle_t *phInstance, 308 LVCS_MemTab_t *pMemoryTable, 309 LVCS_Capabilities_t *pCapabilities); 310 311 312 /****************************************************************************************/ 313 /* */ 314 /* FUNCTION: LVCS_GetParameters */ 315 /* */ 316 /* DESCRIPTION: */ 317 /* Request the Concert Sound parameters. The current parameter set is returned */ 318 /* via the parameter pointer. */ 319 /* */ 320 /* PARAMETERS: */ 321 /* hInstance Instance handle */ 322 /* pParams Pointer to an empty parameter structure */ 323 /* */ 324 /* RETURNS: */ 325 /* LVCS_Success Always succeeds */ 326 /* */ 327 /* NOTES: */ 328 /* 1. This function may be interrupted by the LVCS_Process function */ 329 /* */ 330 /****************************************************************************************/ 331 332 LVCS_ReturnStatus_en LVCS_GetParameters(LVCS_Handle_t hInstance, 333 LVCS_Params_t *pParams); 334 335 336 /****************************************************************************************/ 337 /* */ 338 /* FUNCTION: LVCS_Control */ 339 /* */ 340 /* DESCRIPTION: */ 341 /* Sets or changes the Concert Sound parameters. */ 342 /* */ 343 /* PARAMETERS: */ 344 /* hInstance Instance handle */ 345 /* pParams Pointer to a parameter structure */ 346 /* */ 347 /* RETURNS: */ 348 /* LVCS_Success Succeeded */ 349 /* */ 350 /* NOTES: */ 351 /* 1. This function must not be interrupted by the LVCS_Process function */ 352 /* */ 353 /****************************************************************************************/ 354 355 LVCS_ReturnStatus_en LVCS_Control(LVCS_Handle_t hInstance, 356 LVCS_Params_t *pParams); 357 358 359 /****************************************************************************************/ 360 /* */ 361 /* FUNCTION: LVCS_Process */ 362 /* */ 363 /* DESCRIPTION: */ 364 /* Process function for the Concert Sound module. The implementation supports two */ 365 /* variants of the algorithm, one for headphones and one for mobile speakers. */ 366 /* */ 367 /* PARAMETERS: */ 368 /* hInstance Instance handle */ 369 /* pInData Pointer to the input data */ 370 /* pOutData Pointer to the output data */ 371 /* NumSamples Number of samples in the input buffer */ 372 /* */ 373 /* RETURNS: */ 374 /* LVCS_Success Succeeded */ 375 /* LVCS_TooManySamples NumSamples was larger than the maximum block size */ 376 /* */ 377 /* NOTES: */ 378 /* */ 379 /****************************************************************************************/ 380 #ifdef BUILD_FLOAT 381 LVCS_ReturnStatus_en LVCS_Process(LVCS_Handle_t hInstance, 382 const LVM_FLOAT *pInData, 383 LVM_FLOAT *pOutData, 384 LVM_UINT16 NumSamples); 385 #else 386 LVCS_ReturnStatus_en LVCS_Process(LVCS_Handle_t hInstance, 387 const LVM_INT16 *pInData, 388 LVM_INT16 *pOutData, 389 LVM_UINT16 NumSamples); 390 #endif 391 392 #ifdef __cplusplus 393 } 394 #endif /* __cplusplus */ 395 396 #endif /* LVCS_H */ 397