Home | History | Annotate | Download | only in lib
      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