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 Filename: /audio/gsm_amr/c/src/sub.c
32
33------------------------------------------------------------------------------
34 REVISION HISTORY
35
36 Description: Created separate file for the sub function. Sync'ed up with the
37          current template and fixed tabs.
38
39 Description: Changed all occurrences of L_diff to diff, deleted "short" in
40          the definition of var1 and var2, and fixed the range values.
41
42 Description: Changed function prototype passing in a pointer to overflow flag
43              instead of using global data.
44
45 Description: Changes made per formal review comments.
46              1. Changed the parameter name fron "overflow" to "pOverflow"
47              2. Updated template
48              3. Updated reference section
49
50 Description: Removed conditional code that updates WMOPS counter
51
52 Description:
53              1. Modified if-else structure to save cycles by processing
54                 the most common case faster.
55
56 Who:                       Date:
57 Description:
58
59------------------------------------------------------------------------------
60 MODULE DESCRIPTION
61
62 Subtraction function with overflow control
63
64------------------------------------------------------------------------------
65*/
66
67/*----------------------------------------------------------------------------
68; INCLUDES
69----------------------------------------------------------------------------*/
70#include    "basic_op.h"
71
72/*----------------------------------------------------------------------------
73; MACROS
74; [Define module specific macros here]
75----------------------------------------------------------------------------*/
76
77/*----------------------------------------------------------------------------
78; DEFINES
79; [Include all pre-processor statements here. Include conditional
80; compile variables also.]
81----------------------------------------------------------------------------*/
82
83/*----------------------------------------------------------------------------
84; LOCAL FUNCTION DEFINITIONS
85; [List function prototypes here]
86----------------------------------------------------------------------------*/
87
88/*----------------------------------------------------------------------------
89; LOCAL VARIABLE DEFINITIONS
90; [Variable declaration - defined here and used outside this module]
91----------------------------------------------------------------------------*/
92
93
94/*
95------------------------------------------------------------------------------
96 FUNCTION NAME: sub
97------------------------------------------------------------------------------
98 INPUT AND OUTPUT DEFINITIONS
99
100 Inputs:
101    var1 = 16 bit short signed integer (Word16) whose value falls in
102           the range : 0xffff 8000 <= var1 <= 0x0000 7fff.
103
104    var2 = 16 bit short signed integer (Word16) whose value falls in
105           the range : 0xffff 8000 <= var2 <= 0x0000 7fff.
106
107    pOverflow = pointer to overflow (Flag)
108
109 Outputs:
110    pOverflow -> 1 if the subtract operation resulted in overflow
111
112 Returns:
113    diff = 16-bit limited difference between var1 and var2 (Word16)
114
115 Global Variables Used:
116    None
117
118 Local Variables Needed:
119    None
120
121------------------------------------------------------------------------------
122 FUNCTION DESCRIPTION
123
124 This function performs the subtraction (var1-var2) with overflow control and
125 saturation; the 16 bit result is set at +32767 when overflow occurs or at
126 -32768 when underflow occurs.
127
128------------------------------------------------------------------------------
129 REQUIREMENTS
130
131 None
132
133------------------------------------------------------------------------------
134 REFERENCES
135
136 [1] sub() function in basicop2.c, UMTS GSM AMR speech codec, R99 -
137 Version 3.2.0, March 2, 2001
138
139------------------------------------------------------------------------------
140
141 PSEUDO-CODE
142
143 Word16 sub (Word16 var1, Word16 var2)
144 {
145    Word16 var_out;
146    Word32 diff;
147
148    diff = (Word32) var1 - var2;
149
150* The reference ETSI code uses a global flag for Overflow inside the function
151* saturate(). In the actual implementation a pointer to Overflow flag is passed
152* in as a parameter to the function
153
154    var_out = saturate (diff);
155
156 #if (WMOPS)
157    multiCounter[currCounter].sub++;
158 #endif
159
160    return (var_out);
161 }
162
163------------------------------------------------------------------------------
164 RESOURCES USED [optional]
165
166 When the code is written for a specific target processor the
167 the resources used should be documented below.
168
169 HEAP MEMORY USED: x bytes
170
171 STACK MEMORY USED: x bytes
172
173 CLOCK CYCLES: (cycle count equation for this function) + (variable
174                used to represent cycle count for each subroutine
175                called)
176     where: (cycle count variable) = cycle count for [subroutine
177                                     name]
178
179------------------------------------------------------------------------------
180 CAUTION [optional]
181 [State any special notes, constraints or cautions for users of this function]
182
183------------------------------------------------------------------------------
184*/
185
186/*----------------------------------------------------------------------------
187; FUNCTION CODE
188----------------------------------------------------------------------------*/
189
190Word16 sub(Word16 var1, Word16 var2, Flag *pOverflow)
191{
192
193    Word32 diff;
194
195    diff = (Word32) var1 - var2;
196
197    /* Saturate result (if necessary). */
198    /* Replaced function call with in-line code             */
199    /*  to conserve MIPS, i.e., var_out = saturate (diff)  */
200
201
202    if ((UWord32)(diff - 0xFFFF8000L) > 0x000FFFF)
203    {
204        if (diff > (Word32) 0x0007FFFL)
205        {
206            diff = MAX_16;
207        }
208        else
209        {
210            diff = MIN_16;
211        }
212
213        *pOverflow = 1;
214    }
215
216
217    return ((Word16) diff);
218}
219