1/* ------------------------------------------------------------------
2 * Copyright (C) 1998-2009 PacketVideo
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
13 * express or implied.
14 * See the License for the specific language governing permissions
15 * and limitations under the License.
16 * -------------------------------------------------------------------
17 */
18/****************************************************************************************
19Portions of this file are derived from the following 3GPP standard:
20
21    3GPP TS 26.073
22    ANSI-C code for the Adaptive Multi-Rate (AMR) speech codec
23    Available from http://www.3gpp.org
24
25(C) 2004, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TTA, TTC)
26Permission to distribute, modify and use this file under the standard license
27terms listed above has been obtained from the copyright holder.
28****************************************************************************************/
29/*
30------------------------------------------------------------------------------
31
32
33 Pathname: ./audio/gsm-amr/c/src/amrdecode.c
34
35     Date: 05/23/2001
36------------------------------------------------------------------------------
37 REVISION HISTORY
38
39 Description:       AMRDecode now doesn't call getbits() or put_header_in().
40                    It also now obtains a new bit_offset value from a constant
41                    rather than from the returned value of getbits().
42
43 Description:       AMRDecode now returns byte_offset rather than bit_offset,
44                    so the program can access the next frame that is byte
45                    aligned rather than packed without padding.
46
47 Description:       The structure types Speech_Decode_FrameState are now
48                    passed into amrdecode( ) using void pointers, so that
49                    higher level functions don't need to know anything about
50                    this structure type.
51
52 Description: Changed input argument list. Added code to handle incoming DTX
53              frames, and added call to wmf_to_ets function prior to calling
54              GSMFrameDecode.
55
56 Description: Made the following changes per comments from Phase 2/3 review:
57              1. Changed all references to bit_offset to byte_offset.
58
59 Description: Added input_type to the function interface and modified code
60              to check type of conversion that needs to be made.
61
62 Description: Modified pseudo-code to include IF2 and ETS input formats.
63              Removed byte_offset from input list. Renamed speech_bits
64              to speech_bits_ptr.
65
66 Description: Added dec_input_format_tab.h in Include section. Modified
67              pseudo-code to use correct table names. Renamed input_type to
68              input_format and speech_bits to speech_bits_ptr.
69
70 Description: Removed *prev_mode_ptr in the input argument list.
71
72 Description: Made the following changes per comments from Phase 2/3 review:
73              1. Removed dec_input_format_tab.h from Include section.
74              2. Changed type definition of raw_pcm_buffer in the I/O
75                 definition section.
76
77 Description: Renamed WmfBytesPerFrame to WmfDecBytesPerFrame, and
78              If2BytesPerFrame to If2DecBytesPerFrame.
79
80 Description: Modified code so that the ETS testvectors could be fed directly
81              to this function.
82
83 Description: Changed '&' to '&&' in the setting of rx_type and mode for
84              AMR_SID < frame_type < NO_DATA case.
85
86 Description: Added code comments and made some code optimizations per Phase
87              2/3 review comments.
88
89 Description: Added conditional compile around the call to GSMFrameDecode to
90              allow amrdecode.c to be used in the ETS reference console.
91
92 Description:
93
94------------------------------------------------------------------------------
95*/
96
97/*----------------------------------------------------------------------------
98; INCLUDES
99----------------------------------------------------------------------------*/
100#include "amrdecode.h"
101#include "cnst.h"
102#include "typedef.h"
103#include "frame.h"
104#include "sp_dec.h"
105#include "wmf_to_ets.h"
106#include "if2_to_ets.h"
107#include "frame_type_3gpp.h"
108
109/*----------------------------------------------------------------------------
110; MACROS
111; Define module specific macros here
112----------------------------------------------------------------------------*/
113
114
115/*----------------------------------------------------------------------------
116; DEFINES
117; Include all pre-processor statements here. Include conditional
118; compile variables also.
119----------------------------------------------------------------------------*/
120
121
122/*----------------------------------------------------------------------------
123; LOCAL FUNCTION DEFINITIONS
124; Function Prototype declaration
125----------------------------------------------------------------------------*/
126
127/*----------------------------------------------------------------------------
128; LOCAL STORE/BUFFER/POINTER DEFINITIONS
129; Variable declaration - defined here and used outside this module
130----------------------------------------------------------------------------*/
131
132/*
133------------------------------------------------------------------------------
134 FUNCTION NAME: AMRDecode
135------------------------------------------------------------------------------
136 INPUT AND OUTPUT DEFINITIONS
137
138 Inputs:
139    state_data      = pointer to a structure (type void)
140
141    frame_type      = 3GPP frame type (enum Frame_Type_3GPP)
142
143    speech_bits_ptr = pointer to the beginning of the raw encoded speech bits
144                      for the current frame to be decoded (unsigned char)
145
146    raw_pcm_buffer  = pointer to the output pcm outputs array (Word16)
147
148    input_format    = input format used; valid values are AMR_WMF, AMR_IF2,
149                      and AMR_ETS (Word16)
150
151 Outputs:
152    raw_pcm_buffer contains the newly decoded linear PCM speech samples
153    state_data->prev_mode contains the new mode
154
155 Returns:
156    byte_offset     = address offset of the next frame to be processed or
157                      error condition flag (-1) (int)
158
159 Global Variables Used:
160    WmfDecBytesPerFrame = table containing the number of core AMR data bytes
161                          used by each codec mode for WMF input format (const
162                          int)
163
164    If2DecBytesPerFrame = table containing the number of core AMR data bytes
165                          used by each codec mode for IF2 input format (const
166                          int)
167
168 Local Variables Needed:
169    None
170
171------------------------------------------------------------------------------
172 FUNCTION DESCRIPTION
173
174 This function is the top level entry function to the GSM AMR Decoder library.
175
176 First, it checks the input format type (input_format) to determine the type
177 of de-formattting that needs to be done. If input_format is AMR_WMF, the input
178 data is in WMF (aka, non-IF2) format and the function wmf_to_ets will be
179 called to convert to the ETS format (1 bit/word, where 1 word = 16 bits),
180 and byte_offset will be updated according to the contents of WmfDecBytesPerFrame
181 table.
182
183 If input_format is AMR_IF2, the input data is in IF2 format [1] and the
184 function if2_to_ets will be called to convert to the ETS format, and
185 byte_offset will be updated according to the contents of If2DecBytesPerFrame
186 table.
187
188 The codec mode and receive frame type is initialized based on the incoming
189 frame_type.
190
191 If input_format is AMR_ETS, the input data is in the ETS format. The receive
192 frame type is set to the value in the first location of the buffer pointed to
193 by speech_bits_ptr. Then, the encoded speech parameters in the buffer pointed
194 to by speech_bits is copied to dec_ets_input_bfr and the type will be changed
195 from unsigned char to Word16. Lastly, if the receive frame type is not
196 RX_NO_DATA, the mode is obtained from the buffer pointed to by
197 speech_bits_ptr, offset by MAX_SERIAL_SIZE+1, otherwise, the mode is set to
198 the previous mode (found the in state_data->prev_mode).
199
200 If input_format is an unsupported format, byte_offset will be set to -1, to
201 indicate an error condition has occurred, and the function will exit.
202
203 If there are no errors, GSMFrameDecode is called to decode a 20 ms frame. It
204 puts the decoded linear PCM samples in the buffer pointed to by
205 raw_pcm_buffer. Then, the prev_mode field of the structure pointed to by
206 state_data is updated to the current mode.
207
208 This function returns the new byte_offset value to indicate the address
209 offset of the next speech frame to be decoded.
210
211------------------------------------------------------------------------------
212 REQUIREMENTS
213
214 None
215
216------------------------------------------------------------------------------
217 REFERENCES
218
219 [1] "AMR Speech Codec Frame Structure", 3GPP TS 26.101 version 4.1.0
220     Release 4, June 2001
221
222------------------------------------------------------------------------------
223 PSEUDO-CODE
224
225 Note: AMRSID_RXTYPE_BIT_OFFSET = 35
226       AMRSID_RXMODE_BIT_OFFSET = 36
227       NUM_AMRSID_RXMODE_BITS = 3
228
229
230 // Set up Decoder state structure pointer
231 Speech_Decode_FrameState *decoder_state
232            = (Speech_Decode_FrameState *) state_data
233
234 // Determine type of de-formatting
235
236 // Decode WMF or IF2 frames
237 IF ((input_format == AMR_RX_WMF) | (input_format == AMR_RX_IF2))
238 THEN
239     IF (input_format == AMR_RX_WMF)
240     THEN
241         // Convert incoming packetized raw WMF data to ETS format
242         CALL wmf_to_ets(frame_type = frame_type
243                         input_ptr = speech_bits_ptr
244                         output_ptr = &dec_ets_input_bfr)
245           MODIFYING(nothing)
246           RETURNING(nothing)
247
248         // Address offset of the start of next frame
249         byte_offset = WmfDecBytesPerFrame[frame_type]
250
251     ELSEIF (input_format == AMR_RX_IF2)
252     THEN
253         // Convert incoming packetized raw IF2 data to ETS format
254         CALL if2_to_ets(frame_type = frame_type
255                         input_ptr = speech_bits_ptr
256                         output_ptr = &dec_ets_input_bfr)
257           MODIFYING(nothing)
258           RETURNING(nothing)
259
260         // Address offset of the start of next frame
261         byte_offset = If2DecBytesPerFrame[frame_type]
262
263     ENDIF
264
265       // Determine AMR codec mode and AMR RX frame type
266     IF (frame_type <= AMR_122)
267     THEN
268         mode = (enum Mode) frame_type;
269         rx_type = RX_SPEECH_GOOD;
270
271     ELSEIF (frame_type == AMR_SID)
272     THEN
273         // Clear mode store prior to reading mode info from input buffer
274         mode = 0
275
276         FOR i = 0 TO NUM_AMRSID_RXMODE_BITS-1
277
278             mode |= (dec_ets_input_bfr[AMRSID_RXMODE_BIT_OFFSET+i] << i)
279
280         ENDFOR
281
282         IF (dec_ets_input_bfr[AMRSID_RXTYPE_BIT_OFFSET] == 0)
283         THEN
284             rx_type = RX_SID_FIRST
285
286         ELSE
287             rx_type = RX_SID_UPDATE
288
289         ENDIF
290
291     ELSEIF ((frame_type > AMR_SID) && (frame_type < NO_DATA))
292     THEN
293         // Use previous mode
294         mode = decoder_state->prev_mode
295
296         // Unsupported SID frames
297         rx_type = RX_SPEECH_BAD;
298
299     ELSE
300         // Use previous mode
301         mode = decoder_state->prev_mode
302
303         // No data received
304         rx_type = RX_NO_DATA;
305
306     ENDIF
307
308 // Decode ETS frames
309 ELSEIF (input_format == AMR_RX_ETS)
310 THEN
311     // Change type of pointer to incoming raw ETS data
312     ets_word_ptr = (Word16 *) speech_bits_ptr
313
314     // Get RX frame type
315     rx_type = (enum RXFrameType) *ets_word_ptr
316     ets_word_ptr = ets_word_ptr + 1
317
318     // Copy incoming raw ETS data to dec_ets_input_bfr
319     FOR i = 0 TO MAX_SERIAL_SIZE-1
320
321         dec_ets_input_bfr[i] = *ets_word_ptr
322         ets_word_ptr = ets_word_ptr + 1
323
324     ENDFOR
325
326     // Get codec mode
327     IF (rx_type != RX_NO_DATA)
328     THEN
329         mode = (enum Mode) *ets_word_ptr
330
331     ELSE
332         //Use previous mode if no received data
333         mode = decoder_state->prev_mode
334
335     ENDIF
336
337     // Set up byte_offset
338     byte_offset = 2*(MAX_SERIAL_SIZE+2)
339
340 ELSE
341     // Invalid format, return error code
342     byte_offset = -1
343
344 ENDIF
345
346 // Proceed with decoding frame, if there are no errors
347 IF (byte_offset != -1)
348 THEN
349     // Decode a 20 ms frame
350     CALL GSMFrameDecode( st = decoder_state
351                          mode = mode
352                          serial = dec_ets_input_bfr,
353                          frame_type = rx_type,
354                          synth = (Word16 *)raw_pcm_buffer);
355       MODIFYING (nothing)
356       RETURNING (Nothing)
357
358     // Save mode for next frame
359     decoder_state->prev_mode = mode
360
361 ENDIF
362
363 RETURN (byte_offset)
364
365------------------------------------------------------------------------------
366 RESOURCES USED [optional]
367
368 When the code is written for a specific target processor the
369 the resources used should be documented below.
370
371 HEAP MEMORY USED: x bytes
372
373 STACK MEMORY USED: x bytes
374
375 CLOCK CYCLES: (cycle count equation for this function) + (variable
376                used to represent cycle count for each subroutine
377                called)
378     where: (cycle count variable) = cycle count for [subroutine
379                                     name]
380
381------------------------------------------------------------------------------
382 CAUTION [optional]
383 [State any special notes, constraints or cautions for users of this function]
384
385------------------------------------------------------------------------------
386*/
387
388Word16 AMRDecode(
389    void                      *state_data,
390    enum Frame_Type_3GPP      frame_type,
391    UWord8                    *speech_bits_ptr,
392    Word16                    *raw_pcm_buffer,
393    bitstream_format          input_format
394)
395{
396    Word16 *ets_word_ptr;
397    enum Mode mode = (enum Mode)MR475;
398    int modeStore;
399    int tempInt;
400    enum RXFrameType rx_type = RX_NO_DATA;
401    Word16 dec_ets_input_bfr[MAX_SERIAL_SIZE];
402    Word16 i;
403    Word16 byte_offset = -1;
404
405    /* Type cast state_data to Speech_Decode_FrameState rather than passing
406     * that structure type to this function so the structure make up can't
407     * be viewed from higher level functions than this.
408     */
409    Speech_Decode_FrameState *decoder_state
410    = (Speech_Decode_FrameState *) state_data;
411
412    /* Determine type of de-formatting */
413    /* WMF or IF2 frames */
414    if ((input_format == MIME_IETF) | (input_format == IF2))
415    {
416        if (input_format == MIME_IETF)
417        {
418            /* Convert incoming packetized raw WMF data to ETS format */
419            wmf_to_ets(frame_type, speech_bits_ptr, dec_ets_input_bfr);
420
421            /* Address offset of the start of next frame */
422            byte_offset = WmfDecBytesPerFrame[frame_type];
423        }
424        else   /* else has to be input_format  IF2 */
425        {
426            /* Convert incoming packetized raw IF2 data to ETS format */
427            if2_to_ets(frame_type, speech_bits_ptr, dec_ets_input_bfr);
428
429            /* Address offset of the start of next frame */
430            byte_offset = If2DecBytesPerFrame[frame_type];
431        }
432
433        /* At this point, input data is in ETS format     */
434        /* Determine AMR codec mode and AMR RX frame type */
435        if (frame_type <= AMR_122)
436        {
437            mode = (enum Mode) frame_type;
438            rx_type = RX_SPEECH_GOOD;
439        }
440        else if (frame_type == AMR_SID)
441        {
442            /* Clear mode store prior to reading mode info from input buffer */
443            modeStore = 0;
444
445            for (i = 0; i < NUM_AMRSID_RXMODE_BITS; i++)
446            {
447                tempInt = dec_ets_input_bfr[AMRSID_RXMODE_BIT_OFFSET+i] << i;
448                modeStore |= tempInt;
449            }
450            mode = (enum Mode) modeStore;
451
452            /* Get RX frame type */
453            if (dec_ets_input_bfr[AMRSID_RXTYPE_BIT_OFFSET] == 0)
454            {
455                rx_type = RX_SID_FIRST;
456            }
457            else
458            {
459                rx_type = RX_SID_UPDATE;
460            }
461        }
462        else if (frame_type < AMR_NO_DATA)
463        {
464            /* Invalid frame_type, return error code */
465            byte_offset = -1;   /*  !!! */
466        }
467        else
468        {
469            mode = decoder_state->prev_mode;
470
471            /*
472             * RX_NO_DATA, generate exponential decay from latest valid frame for the first 6 frames
473             * after that, create silent frames
474             */
475            rx_type = RX_NO_DATA;
476
477        }
478
479    }
480
481    /* ETS frames */
482    else if (input_format == ETS)
483    {
484        /* Change type of pointer to incoming raw ETS data */
485        ets_word_ptr = (Word16 *) speech_bits_ptr;
486
487        /* Get RX frame type */
488        rx_type = (enum RXFrameType) * ets_word_ptr;
489        ets_word_ptr++;
490
491        /* Copy incoming raw ETS data to dec_ets_input_bfr */
492        for (i = 0; i < MAX_SERIAL_SIZE; i++)
493        {
494            dec_ets_input_bfr[i] = *ets_word_ptr;
495            ets_word_ptr++;
496        }
497
498        /* Get codec mode */
499        if (rx_type != RX_NO_DATA)
500        {
501            /* Get mode from input bitstream */
502            mode = (enum Mode) * ets_word_ptr;
503        }
504        else
505        {
506            /* Use previous mode if no received data */
507            mode = decoder_state->prev_mode;
508        }
509
510        /* Set up byte_offset */
511        byte_offset = 2 * (MAX_SERIAL_SIZE + 2);
512    }
513    else
514    {
515        /* Invalid input format, return error code */
516        byte_offset = -1;
517    }
518
519    /* Proceed with decoding frame, if there are no errors */
520    if (byte_offset != -1)
521    {
522        /* Decode a 20 ms frame */
523
524#ifndef CONSOLE_DECODER_REF
525        /* Use PV version of sp_dec.c */
526        GSMFrameDecode(decoder_state, mode, dec_ets_input_bfr, rx_type,
527                       raw_pcm_buffer);
528
529#else
530        /* Use ETS version of sp_dec.c */
531        Speech_Decode_Frame(decoder_state, mode, dec_ets_input_bfr, rx_type,
532                            raw_pcm_buffer);
533
534#endif
535
536        /* Save mode for next frame */
537        decoder_state->prev_mode = mode;
538    }
539
540    return (byte_offset);
541}
542
543
544
545