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