Skip to content

Commit ba2e795

Browse files
singalsusingalsu
committed
Math: Update comments for CORDIC trig functions
The SOF code documentation syntax comments are added to header trig.h. Some comments in trig.c are trimmed due to placing more detailed documentation into the header. Signed-off-by: Seppo Ingalsuo <seppo.ingalsuo@linux.intel.com>
1 parent e7ecc4e commit ba2e795

2 files changed

Lines changed: 78 additions & 23 deletions

File tree

‎src/include/sof/math/trig.h‎

Lines changed: 73 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,49 @@ struct cordic_cmpx {
3939
int32_t im;
4040
};
4141

42+
/**
43+
* cordic_approx() - CORDIC-based approximation of sine and cosine
44+
* @param th_rad_fxp Input angle in radian Q4.28 format.
45+
* @param a_idx Used LUT size.
46+
* @param sign Output pointer to sine/cosine sign.
47+
* @param b_yn Output pointer to sine value in Q2.30 format.
48+
* @param xn Output pointer to cosine value in Q2.30 format.
49+
* @param th_cdc_fxp Output pointer to the residual angle in Q2.30 format.
50+
*/
4251
void cordic_approx(int32_t th_rad_fxp, int32_t a_idx, int32_t *sign, int32_t *b_yn, int32_t *xn,
4352
int32_t *th_cdc_fxp);
53+
54+
/**
55+
* is_scalar_cordic_acos() - CORDIC-based approximation for inverse cosine
56+
* @param realvalue Input cosine value in Q2.30 format.
57+
* @param numiters_minus_one Number of iterations minus one.
58+
* @return Inverse cosine angle in Q3.29 format.
59+
*/
4460
int32_t is_scalar_cordic_acos(int32_t realvalue, int numiters_minus_one);
61+
62+
/**
63+
* is_scalar_cordic_asin() - CORDIC-based approximation for inverse sine
64+
* @param realvalue Input sine value in Q2.30 format.
65+
* @param numiters_minus_one Number of iterations minus one.
66+
* @return Inverse sine angle in Q2.30 format.
67+
*/
4568
int32_t is_scalar_cordic_asin(int32_t realvalue, int numiters_minus_one);
4669

70+
/**
71+
* cmpx_cexp() - CORDIC-based approximation of complex exponential e^(j*THETA)
72+
* @param sign Sine sign
73+
* @param b_yn Sine value in Q2.30 format
74+
* @param xn Cosine value in Q2.30 format
75+
* @param type CORDIC type
76+
* @param cexp Output pointer to complex result in struct cordic_cmpx
77+
*/
4778
void cmpx_cexp(int32_t sign, int32_t b_yn, int32_t xn, cordic_cfg type, struct cordic_cmpx *cexp);
48-
/* Input is Q4.28, output is Q1.31 */
79+
4980
/**
81+
* sin_fixed_32b() - Sine function using CORDIC algorithm
82+
* @param th_rad_fxp Input angle in radian Q4.28 format.
83+
* @return Sine value in Q1.31 format.
84+
*
5085
* Compute fixed point cordicsine with table lookup and interpolation
5186
* The cordic sine algorithm converges, when the angle is in the range
5287
* [-pi/2, pi/2).If an angle is outside of this range, then a multiple of
@@ -75,6 +110,10 @@ static inline int32_t sin_fixed_32b(int32_t th_rad_fxp)
75110
}
76111

77112
/**
113+
* cos_fixed_32b() - Cosine function using CORDIC algorithm
114+
* @param th_rad_fxp Input angle in radian Q4.28 format.
115+
* @return Cosine value in Q1.31 format.
116+
*
78117
* Compute fixed point cordicsine with table lookup and interpolation
79118
* The cordic cosine algorithm converges, when the angle is in the range
80119
* [-pi/2, pi/2).If an angle is outside of this range, then a multiple of
@@ -102,8 +141,11 @@ static inline int32_t cos_fixed_32b(int32_t th_rad_fxp)
102141
return sat_int32(Q_SHIFT_LEFT((int64_t)th_cdc_fxp, 30, 31));
103142
}
104143

105-
/* Input is Q4.28, output is Q1.15 */
106144
/**
145+
* sin_fixed_16b() - Sine function using CORDIC algorithm
146+
* @param th_rad_fxp Input angle in radian Q4.28 format.
147+
* @return Sine value in Q1.15 format
148+
*
107149
* Compute fixed point cordic sine with table lookup and interpolation
108150
* The cordic sine algorithm converges, when the angle is in the range
109151
* [-pi/2, pi/2).If an angle is outside of this range, then a multiple of
@@ -133,6 +175,10 @@ static inline int16_t sin_fixed_16b(int32_t th_rad_fxp)
133175
}
134176

135177
/**
178+
* cos_fixed_16b() - Cosine function using CORDIC algorithm
179+
* @param th_rad_fxp Input angle in radian Q4.28 format.
180+
* @return Cosine value in Q1.15 format.
181+
*
136182
* Compute fixed point cordic cosine with table lookup and interpolation
137183
* The cordic cos algorithm converges, when the angle is in the range
138184
* [-pi/2, pi/2).If an angle is outside of this range, then a multiple of
@@ -162,7 +208,10 @@ static inline int16_t cos_fixed_16b(int32_t th_rad_fxp)
162208
}
163209

164210
/**
165-
* CORDIC-based approximation of complex exponential e^(j*THETA).
211+
* cmpx_exp_32b() - CORDIC-based approximation of complex exponential e^(j*THETA).
212+
* @param th_rad_fxp Input angle in radian Q4.28 format.
213+
* @param cexp Output pointer to complex result in struct cordic_cmpx in Q2.30 format.
214+
*
166215
* computes COS(THETA) + j*SIN(THETA) using CORDIC algorithm
167216
* approximation and returns the complex result.
168217
* THETA values must be in the range [-2*pi, 2*pi). The cordic
@@ -194,7 +243,10 @@ static inline void cmpx_exp_32b(int32_t th_rad_fxp, struct cordic_cmpx *cexp)
194243
}
195244

196245
/**
197-
* CORDIC-based approximation of complex exponential e^(j*THETA).
246+
* cmpx_exp_16b() - CORDIC-based approximation of complex exponential e^(j*THETA).
247+
* @param th_rad_fxp Input angle in radian Q4.28 format.
248+
* @param cexp Output pointer to complex result in struct cordic_cmpx in Q1.15 format.
249+
*
198250
* computes COS(THETA) + j*SIN(THETA) using CORDIC algorithm
199251
* approximation and returns the complex result.
200252
* THETA values must be in the range [-2*pi, 2*pi). The cordic
@@ -227,7 +279,10 @@ static inline void cmpx_exp_16b(int32_t th_rad_fxp, struct cordic_cmpx *cexp)
227279
}
228280

229281
/**
230-
* CORDIC-based approximation of inverse sine
282+
* asin_fixed_32b() - CORDIC-based approximation of inverse sine
283+
* @param cdc_asin_th Input value in Q2.30 format.
284+
* @return Inverse sine angle in Q2.30 format.
285+
*
231286
* inverse sine of cdc_asin_theta based on a CORDIC approximation.
232287
* asin(cdc_asin_th) inverse sine angle values in radian produces using the DCORDIC
233288
* (Double CORDIC) algorithm.
@@ -250,7 +305,10 @@ static inline int32_t asin_fixed_32b(int32_t cdc_asin_th)
250305
}
251306

252307
/**
253-
* CORDIC-based approximation of inverse cosine
308+
* acos_fixed_32b() - CORDIC-based approximation of inverse cosine
309+
* @param cdc_acos_th Input value in Q2.30 format.
310+
* @return Inverse cosine angle in Q3.29 format.
311+
*
254312
* inverse cosine of cdc_acos_theta based on a CORDIC approximation
255313
* acos(cdc_acos_th) inverse cosine angle values in radian produces using the DCORDIC
256314
* (Double CORDIC) algorithm.
@@ -266,14 +324,16 @@ static inline int32_t acos_fixed_32b(int32_t cdc_acos_th)
266324
if (cdc_acos_th >= 0)
267325
th_acos_fxp = is_scalar_cordic_acos(cdc_acos_th, CORDIC_31B_ITERATIONS);
268326
else
269-
th_acos_fxp =
270-
PI_Q3_29 - is_scalar_cordic_acos(-cdc_acos_th, CORDIC_31B_ITERATIONS);
327+
th_acos_fxp = PI_Q3_29 - is_scalar_cordic_acos(-cdc_acos_th, CORDIC_31B_ITERATIONS);
271328

272329
return th_acos_fxp; /* Q3.29 */
273330
}
274331

275332
/**
276-
* CORDIC-based approximation of inverse sine
333+
* asin_fixed_16b() - CORDIC-based approximation of inverse sine
334+
* @param cdc_asin_th Input value in Q2.30 format.
335+
* @return Inverse sine angle in Q2.14 format.
336+
*
277337
* inverse sine of cdc_asin_theta based on a CORDIC approximation.
278338
* asin(cdc_asin_th) inverse sine angle values in radian produces using the DCORDIC
279339
* (Double CORDIC) algorithm.
@@ -297,7 +357,10 @@ static inline int16_t asin_fixed_16b(int32_t cdc_asin_th)
297357
}
298358

299359
/**
300-
* CORDIC-based approximation of inverse cosine
360+
* acos_fixed_16b() - CORDIC-based approximation of inverse cosine
361+
* @param cdc_acos_th Input value in Q2.30 format.
362+
* @return Inverse cosine angle in Q3.13 format.
363+
*
301364
* inverse cosine of cdc_acos_theta based on a CORDIC approximation
302365
* acos(cdc_acos_th) inverse cosine angle values in radian produces using the DCORDIC
303366
* (Double CORDIC) algorithm.

‎src/math/trig.c‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -95,9 +95,7 @@ EXPORT_SYMBOL(cordic_approx);
9595

9696
/**
9797
* CORDIC-based approximation for inverse cosine
98-
* Arguments : int32_t cosvalue
99-
* int16_t numiters
100-
* Return Type : int32_t
98+
* cosvalue is Q2.30, return value is angle in Q3.29 format
10199
*/
102100
int32_t is_scalar_cordic_acos(int32_t cosvalue, int numiters)
103101
{
@@ -166,9 +164,7 @@ int32_t is_scalar_cordic_acos(int32_t cosvalue, int numiters)
166164

167165
/**
168166
* CORDIC-based approximation for inverse sine
169-
* Arguments : int32_t sinvalue
170-
* int16_t numiters
171-
* Return Type : int32_t
167+
* sinvalue is Q2.30, return value is angle in Q2.30 format
172168
*/
173169
int32_t is_scalar_cordic_asin(int32_t sinvalue, int numiters)
174170
{
@@ -236,13 +232,9 @@ int32_t is_scalar_cordic_asin(int32_t sinvalue, int numiters)
236232
}
237233

238234
/**
239-
* approximated complex result
240-
* Arguments : int32_t sign
241-
* int32_t b_yn
242-
* int32_t xn
243-
* enum type
244-
* struct cordic_cmpx
245-
* Return Type : none
235+
* cmpx_cexp() - CORDIC-based approximation of complex exponential e^(j*THETA)
236+
*
237+
* The sine and cosine values are in Q2.30 format from cordic_approx()function.
246238
*/
247239
void cmpx_cexp(int32_t sign, int32_t b_yn, int32_t xn, cordic_cfg type, struct cordic_cmpx *cexp)
248240
{

0 commit comments

Comments
 (0)