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 the N-Band equaliser. */ 21/* */ 22/* This files includes all definitions, types, structures and function */ 23/* prototypes required by the calling layer. All other types, structures and */ 24/* functions are private. */ 25/* */ 26/****************************************************************************************/ 27/* */ 28/* Note: 1 */ 29/* ======= */ 30/* The algorithm can execute either with separate input and output buffers or with */ 31/* a common buffer, i.e. the data is processed in-place. */ 32/* */ 33/****************************************************************************************/ 34/* */ 35/* Note: 2 */ 36/* ======= */ 37/* Two data formats are support Stereo and Mono-In-Stereo. The data is interleaved as */ 38/* follows: */ 39/* Byte Offset Stereo Input Mono-In-Stereo Input */ 40/* =========== ============ ==================== */ 41/* 0 Left Sample #1 Mono Sample #1 */ 42/* 2 Right Sample #1 Mono Sample #1 */ 43/* 4 Left Sample #2 Mono Sample #2 */ 44/* 6 Right Sample #2 Mono Sample #2 */ 45/* . . . */ 46/* . . . */ 47/* */ 48/* Mono format data is not supported, the calling routine must convert a Mono stream */ 49/* in to Mono-In-Stereo format. */ 50/* */ 51/****************************************************************************************/ 52/* */ 53/* Note: 3 */ 54/* ======= */ 55/* The format of the data in the filter band definition structure is as follows: */ 56/* */ 57/* Gain is in integer dB, range -15dB to +15dB inclusive */ 58/* Frequency is the centre frequency in Hz, range DC to Nyquist */ 59/* QFactor is the Q multiplied by 100, range 0.25 (25) to 12 (1200) */ 60/* */ 61/* Example: */ 62/* Gain = 7 7dB gain */ 63/* Frequency = 2467 Centre frequency = 2.467kHz */ 64/* QFactor = 1089 Q = 10.89 */ 65/* */ 66/* The equaliser filters are passed as a pointer to and array of filter band */ 67/* definitions structures. There must be one filter definition for each band. */ 68/* */ 69/****************************************************************************************/ 70 71 72#ifndef __LVEQNB_H__ 73#define __LVEQNB_H__ 74 75#ifdef __cplusplus 76extern "C" { 77#endif /* __cplusplus */ 78 79 80/****************************************************************************************/ 81/* */ 82/* Includes */ 83/* */ 84/****************************************************************************************/ 85 86#include "LVM_Types.h" 87#include "LVM_Common.h" 88 89/****************************************************************************************/ 90/* */ 91/* Definitions */ 92/* */ 93/****************************************************************************************/ 94 95/* Memory table */ 96#define LVEQNB_MEMREGION_INSTANCE 0 /* Offset to the instance memory region */ 97#define LVEQNB_MEMREGION_PERSISTENT_DATA 1 /* Offset to persistent data memory region */ 98#define LVEQNB_MEMREGION_PERSISTENT_COEF 2 /* Offset to persistent coefficient region */ 99#define LVEQNB_MEMREGION_SCRATCH 3 /* Offset to data scratch memory region */ 100#define LVEQNB_NR_MEMORY_REGIONS 4 /* Number of memory regions */ 101 102/* Callback events */ 103#define LVEQNB_EVENT_NONE 0x0000 /* Not a valid event */ 104#define LVEQNB_EVENT_ALGOFF 0x0001 /* EQNB has completed switch off */ 105 106/****************************************************************************************/ 107/* */ 108/* Types */ 109/* */ 110/****************************************************************************************/ 111 112/* Instance handle */ 113typedef void *LVEQNB_Handle_t; 114 115 116/* Operating modes */ 117typedef enum 118{ 119 LVEQNB_BYPASS = 0, 120 LVEQNB_ON = 1, 121 LVEQNB_MODE_MAX = LVM_MAXINT_32 122} LVEQNB_Mode_en; 123 124 125/* Filter mode control */ 126typedef enum 127{ 128 LVEQNB_FILTER_OFF = 0, 129 LVEQNB_FILTER_ON = 1, 130 LVEQNB_FILTER_DUMMY = LVM_MAXINT_32 131} LVEQNB_FilterMode_en; 132 133 134/* Memory Types */ 135typedef enum 136{ 137 LVEQNB_PERSISTENT = 0, 138 LVEQNB_PERSISTENT_DATA = 1, 139 LVEQNB_PERSISTENT_COEF = 2, 140 LVEQNB_SCRATCH = 3, 141 LVEQNB_MEMORY_MAX = LVM_MAXINT_32 142} LVEQNB_MemoryTypes_en; 143 144 145/* Function return status */ 146typedef enum 147{ 148 LVEQNB_SUCCESS = 0, /* Successful return from a routine */ 149 LVEQNB_ALIGNMENTERROR = 1, /* Memory alignment error */ 150 LVEQNB_NULLADDRESS = 2, /* NULL allocation address */ 151 LVEQNB_TOOMANYSAMPLES = 3, /* Maximum block size exceeded */ 152 LVEQNB_STATUS_MAX = LVM_MAXINT_32 153} LVEQNB_ReturnStatus_en; 154 155 156/****************************************************************************************/ 157/* */ 158/* Linked enumerated type and capability definitions */ 159/* */ 160/* The capability definitions are used to define the required capabilities at */ 161/* initialisation, these are added together to give the capability word. The */ 162/* enumerated type is used to select the mode through a control function at run time. */ 163/* */ 164/* The capability definition is related to the enumerated type value by the equation: */ 165/* */ 166/* Capability_value = 2^Enumerated_value */ 167/* */ 168/* For example, a module could be configurd at initialisation to support two sample */ 169/* rates only by calling the init function with the value: */ 170/* Capabilities.SampleRate = LVEQNB_CAP_32000 + LVEQNB_CAP_44100; */ 171/* */ 172/* and at run time it would be passed the value LVEQNB_FS_32000 through the control */ 173/* function to select operation at 32kHz */ 174/* */ 175/****************************************************************************************/ 176 177/* 178 * Supported source data formats 179 */ 180#define LVEQNB_CAP_STEREO 1 181#define LVEQNB_CAP_MONOINSTEREO 2 182 183typedef enum 184{ 185 LVEQNB_STEREO = 0, 186 LVEQNB_MONOINSTEREO = 1, 187 LVEQNB_SOURCE_MAX = LVM_MAXINT_32 188} LVEQNB_SourceFormat_en; 189 190 191/* 192 * Supported sample rates in samples per second 193 */ 194#define LVEQNB_CAP_FS_8000 1 195#define LVEQNB_CAP_FS_11025 2 196#define LVEQNB_CAP_FS_12000 4 197#define LVEQNB_CAP_FS_16000 8 198#define LVEQNB_CAP_FS_22050 16 199#define LVEQNB_CAP_FS_24000 32 200#define LVEQNB_CAP_FS_32000 64 201#define LVEQNB_CAP_FS_44100 128 202#define LVEQNB_CAP_FS_48000 256 203 204typedef enum 205{ 206 LVEQNB_FS_8000 = 0, 207 LVEQNB_FS_11025 = 1, 208 LVEQNB_FS_12000 = 2, 209 LVEQNB_FS_16000 = 3, 210 LVEQNB_FS_22050 = 4, 211 LVEQNB_FS_24000 = 5, 212 LVEQNB_FS_32000 = 6, 213 LVEQNB_FS_44100 = 7, 214 LVEQNB_FS_48000 = 8, 215 LVEQNB_FS_MAX = LVM_MAXINT_32 216} LVEQNB_Fs_en; 217 218 219/****************************************************************************************/ 220/* */ 221/* Structures */ 222/* */ 223/****************************************************************************************/ 224 225/* Memory region definition */ 226typedef struct 227{ 228 LVM_UINT32 Size; /* Region size in bytes */ 229 LVM_UINT16 Alignment; /* Region alignment in bytes */ 230 LVEQNB_MemoryTypes_en Type; /* Region type */ 231 void *pBaseAddress; /* Pointer to the region base address */ 232} LVEQNB_MemoryRegion_t; 233 234 235/* Memory table containing the region definitions */ 236typedef struct 237{ 238 LVEQNB_MemoryRegion_t Region[LVEQNB_NR_MEMORY_REGIONS]; /* One definition for each region */ 239} LVEQNB_MemTab_t; 240 241 242/* Equaliser band definition */ 243typedef struct 244{ 245 LVM_INT16 Gain; /* Band gain in dB */ 246 LVM_UINT16 Frequency; /* Band centre frequency in Hz */ 247 LVM_UINT16 QFactor; /* Band quality factor */ 248} LVEQNB_BandDef_t; 249 250 251/* Parameter structure */ 252typedef struct 253{ 254 /* General parameters */ 255 LVEQNB_Mode_en OperatingMode; 256 LVEQNB_Fs_en SampleRate; 257 LVEQNB_SourceFormat_en SourceFormat; 258 259 /* Equaliser parameters */ 260 LVM_UINT16 NBands; /* Number of bands */ 261 LVEQNB_BandDef_t *pBandDefinition; /* Pointer to equaliser definitions */ 262 263} LVEQNB_Params_t; 264 265 266/* Capability structure */ 267typedef struct 268{ 269 /* General parameters */ 270 LVM_UINT16 SampleRate; 271 LVM_UINT16 SourceFormat; 272 LVM_UINT16 MaxBlockSize; 273 LVM_UINT16 MaxBands; 274 275 /* Callback parameters */ 276 LVM_Callback CallBack; /* Bundle callback */ 277 void *pBundleInstance; /* Bundle instance handle */ 278 279} LVEQNB_Capabilities_t; 280 281 282/****************************************************************************************/ 283/* */ 284/* Function Prototypes */ 285/* */ 286/****************************************************************************************/ 287 288/****************************************************************************************/ 289/* */ 290/* FUNCTION: LVEQNB_Memory */ 291/* */ 292/* DESCRIPTION: */ 293/* This function is used for memory allocation and free. It can be called in */ 294/* two ways: */ 295/* */ 296/* hInstance = NULL Returns the memory requirements */ 297/* hInstance = Instance handle Returns the memory requirements and */ 298/* allocated base addresses for the instance */ 299/* */ 300/* When this function is called for memory allocation (hInstance=NULL) the memory */ 301/* base address pointers are NULL on return. */ 302/* */ 303/* When the function is called for free (hInstance = Instance Handle) the memory */ 304/* table returns the allocated memory and base addresses used during initialisation. */ 305/* */ 306/* PARAMETERS: */ 307/* hInstance Instance Handle */ 308/* pMemoryTable Pointer to an empty memory definition table */ 309/* pCapabilities Pointer to the default capabilities */ 310/* */ 311/* RETURNS: */ 312/* LVEQNB_SUCCESS Succeeded */ 313/* LVEQNB_NULLADDRESS When any of pMemoryTable and pCapabilities is NULL address */ 314/* */ 315/* NOTES: */ 316/* 1. This function may be interrupted by the LVEQNB_Process function */ 317/* */ 318/****************************************************************************************/ 319 320LVEQNB_ReturnStatus_en LVEQNB_Memory(LVEQNB_Handle_t hInstance, 321 LVEQNB_MemTab_t *pMemoryTable, 322 LVEQNB_Capabilities_t *pCapabilities); 323 324 325/****************************************************************************************/ 326/* */ 327/* FUNCTION: LVEQNB_Init */ 328/* */ 329/* DESCRIPTION: */ 330/* Create and initialisation function for the N-Band equalliser module */ 331/* */ 332/* This function can be used to create an algorithm instance by calling with */ 333/* hInstance set to NULL. In this case the algorithm returns the new instance */ 334/* handle. */ 335/* */ 336/* This function can be used to force a full re-initialisation of the algorithm */ 337/* by calling with hInstance = Instance Handle. In this case the memory table */ 338/* should be correct for the instance, this can be ensured by calling the function */ 339/* LVEQNB_Memory before calling this function. */ 340/* */ 341/* PARAMETERS: */ 342/* hInstance Instance handle */ 343/* pMemoryTable Pointer to the memory definition table */ 344/* pCapabilities Pointer to the initialisation capabilities */ 345/* */ 346/* RETURNS: */ 347/* LVEQNB_SUCCESS Initialisation succeeded */ 348/* LVEQNB_NULLADDRESS When pCapabilities or pMemoryTableis or phInstance are NULL */ 349/* LVEQNB_NULLADDRESS One or more of the memory regions has a NULL base address */ 350/* pointer for a memory region with a non-zero size. */ 351/* */ 352/* */ 353/* NOTES: */ 354/* 1. The instance handle is the pointer to the base address of the first memory */ 355/* region. */ 356/* 2. This function must not be interrupted by the LVEQNB_Process function */ 357/* */ 358/****************************************************************************************/ 359 360LVEQNB_ReturnStatus_en LVEQNB_Init(LVEQNB_Handle_t *phInstance, 361 LVEQNB_MemTab_t *pMemoryTable, 362 LVEQNB_Capabilities_t *pCapabilities); 363 364 365/****************************************************************************************/ 366/* */ 367/* FUNCTION: LVEQNB_GetParameters */ 368/* */ 369/* DESCRIPTION: */ 370/* Request the equaliser module parameters. The current parameter set is returned */ 371/* via the parameter pointer. */ 372/* */ 373/* PARAMETERS: */ 374/* hInstance Instance handle */ 375/* pParams Pointer to an empty parameter structure */ 376/* */ 377/* RETURNS: */ 378/* LVEQNB_SUCCESS Succeeds */ 379/* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 380/* */ 381/* NOTES: */ 382/* 1. This function may be interrupted by the LVEQNB_Process function */ 383/* */ 384/****************************************************************************************/ 385 386LVEQNB_ReturnStatus_en LVEQNB_GetParameters(LVEQNB_Handle_t hInstance, 387 LVEQNB_Params_t *pParams); 388 389 390/****************************************************************************************/ 391/* */ 392/* FUNCTION: LVEQNB_GetCapabilities */ 393/* */ 394/* DESCRIPTION: */ 395/* Request the equaliser module capabilities. The capabilities set is returned */ 396/* via the pointer. */ 397/* */ 398/* PARAMETERS: */ 399/* hInstance Instance handle */ 400/* pCapabilities Pointer to an empty capability structure */ 401/* */ 402/* RETURNS: */ 403/* LVEQNB_SUCCESS Succeeds */ 404/* LVEQNB_NULLADDRESS hInstance or pCapabilities is NULL */ 405/* */ 406/* NOTES: */ 407/* 1. This function may be interrupted by the LVEQNB_Process function */ 408/* */ 409/****************************************************************************************/ 410 411LVEQNB_ReturnStatus_en LVEQNB_GetCapabilities(LVEQNB_Handle_t hInstance, 412 LVEQNB_Capabilities_t *pCapabilities); 413 414 415/****************************************************************************************/ 416/* */ 417/* FUNCTION: LVEQNB_Control */ 418/* */ 419/* DESCRIPTION: */ 420/* Sets or changes the equaliser module parameters. */ 421/* */ 422/* PARAMETERS: */ 423/* hInstance Instance handle */ 424/* pParams Pointer to a parameter structure */ 425/* */ 426/* RETURNS: */ 427/* LVEQNB_SUCCESS Succeeded */ 428/* LVEQNB_NULLADDRESS Instance or pParams is NULL pointer */ 429/* LVEQNB_NULLADDRESS NULL address for the equaliser filter definitions and the */ 430/* number of bands is non-zero */ 431/* */ 432/* NOTES: */ 433/* 1. This function may be interrupted by the LVEQNB_Process function */ 434/* */ 435/****************************************************************************************/ 436 437LVEQNB_ReturnStatus_en LVEQNB_Control(LVEQNB_Handle_t hInstance, 438 LVEQNB_Params_t *pParams); 439 440 441/****************************************************************************************/ 442/* */ 443/* FUNCTION: LVEQNB_Process */ 444/* */ 445/* DESCRIPTION: */ 446/* Process function for the LifeVibes module. */ 447/* */ 448/* PARAMETERS: */ 449/* hInstance Instance handle */ 450/* pInData Pointer to the input data */ 451/* pOutData Pointer to the output data */ 452/* NumSamples Number of samples in the input buffer */ 453/* */ 454/* RETURNS: */ 455/* LVEQNB_SUCCESS Succeeded */ 456/* LVEQNB_NULLADDRESS When hInstance, pInData or pOutData are NULL */ 457/* LVEQNB_ALIGNMENTERROR When pInData or pOutData are not 32-bit aligned */ 458/* LVEQNB_TOOMANYSAMPLES NumSamples was larger than the maximum block size */ 459/* */ 460/* NOTES: */ 461/* */ 462/****************************************************************************************/ 463 464LVEQNB_ReturnStatus_en LVEQNB_Process(LVEQNB_Handle_t hInstance, 465 const LVM_INT16 *pInData, 466 LVM_INT16 *pOutData, 467 LVM_UINT16 NumSamples); 468 469 470 471#ifdef __cplusplus 472} 473#endif /* __cplusplus */ 474 475#endif /* __LVEQNB__ */ 476 477