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 } LVCS_Params_t; 209 210 211 /* Concert Sound Capability structure */ 212 typedef struct 213 { 214 /* General parameters */ 215 LVM_UINT16 MaxBlockSize; /* Maximum block size in sample pairs */ 216 217 /* Callback parameters */ 218 LVM_Callback CallBack; /* Bundle callback */ 219 void *pBundleInstance; /* Bundle instance handle */ 220 221 } LVCS_Capabilities_t; 222 223 224 /****************************************************************************************/ 225 /* */ 226 /* Function Prototypes */ 227 /* */ 228 /****************************************************************************************/ 229 230 /****************************************************************************************/ 231 /* */ 232 /* FUNCTION: LVCS_Memory */ 233 /* */ 234 /* DESCRIPTION: */ 235 /* This function is used for memory allocation and free. It can be called in */ 236 /* two ways: */ 237 /* */ 238 /* hInstance = NULL Returns the memory requirements */ 239 /* hInstance = Instance handle Returns the memory requirements and */ 240 /* allocated base addresses for the instance */ 241 /* */ 242 /* When this function is called for memory allocation (hInstance=NULL) it is */ 243 /* passed the default capabilities, of these only the buffer processing setting is */ 244 /* used. */ 245 /* */ 246 /* When called for memory allocation the memory base address pointers are NULL on */ 247 /* return. */ 248 /* */ 249 /* When the function is called for free (hInstance = Instance Handle) the */ 250 /* capabilities are ignored and the memory table returns the allocated memory and */ 251 /* base addresses used during initialisation. */ 252 /* */ 253 /* PARAMETERS: */ 254 /* hInstance Instance Handle */ 255 /* pMemoryTable Pointer to an empty memory definition table */ 256 /* pCapabilities Pointer to the default capabilites */ 257 /* */ 258 /* RETURNS: */ 259 /* LVCS_Success Succeeded */ 260 /* */ 261 /* NOTES: */ 262 /* 1. This function may be interrupted by the LVCS_Process function */ 263 /* */ 264 /****************************************************************************************/ 265 266 LVCS_ReturnStatus_en LVCS_Memory(LVCS_Handle_t hInstance, 267 LVCS_MemTab_t *pMemoryTable, 268 LVCS_Capabilities_t *pCapabilities); 269 270 271 /****************************************************************************************/ 272 /* */ 273 /* FUNCTION: LVCS_Init */ 274 /* */ 275 /* DESCRIPTION: */ 276 /* Create and initialisation function for the Concert Sound module */ 277 /* */ 278 /* This function can be used to create an algorithm instance by calling with */ 279 /* hInstance set to NULL. In this case the algorithm returns the new instance */ 280 /* handle. */ 281 /* */ 282 /* This function can be used to force a full re-initialisation of the algorithm */ 283 /* by calling with hInstance = Instance Handle. In this case the memory table */ 284 /* should be correct for the instance, this can be ensured by calling the function */ 285 /* LVCS_Memory before calling this function. */ 286 /* */ 287 /* PARAMETERS: */ 288 /* hInstance Instance handle */ 289 /* pMemoryTable Pointer to the memory definition table */ 290 /* pCapabilities Pointer to the initialisation capabilities */ 291 /* */ 292 /* RETURNS: */ 293 /* LVCS_Success Initialisation succeeded */ 294 /* LVCS_AlignmentError Instance or scratch memory on incorrect alignment */ 295 /* LVCS_NullAddress Instance or scratch memory has a NULL pointer */ 296 /* */ 297 /* NOTES: */ 298 /* 1. The instance handle is the pointer to the base address of the first memory */ 299 /* region. */ 300 /* 2. This function must not be interrupted by the LVCS_Process function */ 301 /* */ 302 /****************************************************************************************/ 303 304 LVCS_ReturnStatus_en LVCS_Init(LVCS_Handle_t *phInstance, 305 LVCS_MemTab_t *pMemoryTable, 306 LVCS_Capabilities_t *pCapabilities); 307 308 309 /****************************************************************************************/ 310 /* */ 311 /* FUNCTION: LVCS_GetParameters */ 312 /* */ 313 /* DESCRIPTION: */ 314 /* Request the Concert Sound parameters. The current parameter set is returned */ 315 /* via the parameter pointer. */ 316 /* */ 317 /* PARAMETERS: */ 318 /* hInstance Instance handle */ 319 /* pParams Pointer to an empty parameter structure */ 320 /* */ 321 /* RETURNS: */ 322 /* LVCS_Success Always succeeds */ 323 /* */ 324 /* NOTES: */ 325 /* 1. This function may be interrupted by the LVCS_Process function */ 326 /* */ 327 /****************************************************************************************/ 328 329 LVCS_ReturnStatus_en LVCS_GetParameters(LVCS_Handle_t hInstance, 330 LVCS_Params_t *pParams); 331 332 333 /****************************************************************************************/ 334 /* */ 335 /* FUNCTION: LVCS_Control */ 336 /* */ 337 /* DESCRIPTION: */ 338 /* Sets or changes the Concert Sound parameters. */ 339 /* */ 340 /* PARAMETERS: */ 341 /* hInstance Instance handle */ 342 /* pParams Pointer to a parameter structure */ 343 /* */ 344 /* RETURNS: */ 345 /* LVCS_Success Succeeded */ 346 /* */ 347 /* NOTES: */ 348 /* 1. This function must not be interrupted by the LVCS_Process function */ 349 /* */ 350 /****************************************************************************************/ 351 352 LVCS_ReturnStatus_en LVCS_Control(LVCS_Handle_t hInstance, 353 LVCS_Params_t *pParams); 354 355 356 /****************************************************************************************/ 357 /* */ 358 /* FUNCTION: LVCS_Process */ 359 /* */ 360 /* DESCRIPTION: */ 361 /* Process function for the Concert Sound module. The implementation supports two */ 362 /* variants of the algorithm, one for headphones and one for mobile speakers. */ 363 /* */ 364 /* PARAMETERS: */ 365 /* hInstance Instance handle */ 366 /* pInData Pointer to the input data */ 367 /* pOutData Pointer to the output data */ 368 /* NumSamples Number of samples in the input buffer */ 369 /* */ 370 /* RETURNS: */ 371 /* LVCS_Success Succeeded */ 372 /* LVCS_TooManySamples NumSamples was larger than the maximum block size */ 373 /* */ 374 /* NOTES: */ 375 /* */ 376 /****************************************************************************************/ 377 378 LVCS_ReturnStatus_en LVCS_Process(LVCS_Handle_t hInstance, 379 const LVM_INT16 *pInData, 380 LVM_INT16 *pOutData, 381 LVM_UINT16 NumSamples); 382 383 384 #ifdef __cplusplus 385 } 386 #endif /* __cplusplus */ 387 388 #endif /* LVCS_H */ 389