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 60extern "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 */ 104typedef void *LVCS_Handle_t; 105 106 107/* Operating modes */ 108typedef enum 109{ 110 LVCS_OFF = 0, 111 LVCS_ON = 15, 112 LVCS_MAX = LVM_MAXENUM 113} LVCS_Modes_en; 114 115 116/* Memory Types */ 117typedef 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 */ 128typedef 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 */ 142typedef 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 */ 153typedef 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 */ 163typedef 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 */ 183typedef 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 */ 192typedef 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 */ 199typedef 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 */ 212typedef 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 266LVCS_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 304LVCS_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 329LVCS_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 352LVCS_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 378LVCS_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