fixed-point: more TI macros. Comments on the existing ones.

1 files changed, 45 insertions, 5 deletions

diff --git a/libcelt/fixed_generic.h b/libcelt/fixed_generic.h
index 355dc2d..364b3c2 100644
--- a/libcelt/fixed_generic.h
+++ b/libcelt/fixed_generic.h
@@ -1,4 +1,4 @@
-/* Copyright (C) 2003 Jean-Marc Valin */
+/* Copyright (C) 2003-2008 Jean-Marc Valin, CSIRO */
 /**
    @file fixed_generic.h
    @brief Generic fixed-point operations
@@ -35,61 +35,99 @@
 #ifndef FIXED_GENERIC_H
 #define FIXED_GENERIC_H
 
+/** Multiply a 16-bit signed value by a 16-bit unsigned value. The result is a 32-bit signed value */
 #define MULT16_16SU(a,b) ((celt_word32_t)(celt_word16_t)(a)*(celt_word32_t)(celt_uint16_t)(b))
 
+/** 16x32 multiplication, followed by a 15-bit shift right. Results fits in 32 bits */
 #define MULT16_32_Q15(a,b) ADD32(SHL(MULT16_16((a),SHR((b),16)),1), SHR(MULT16_16SU((a),((b)&0x0000ffff)),15))
 
+/** 32x32 multiplication, followed by a 31-bit shift right. Results fits in 32 bits */
 #define MULT32_32_Q31(a,b) ADD32(ADD32(SHL(MULT16_16(SHR((a),16),SHR((b),16)),1), SHR(MULT16_16SU(SHR((a),16),((b)&0x0000ffff)),15)), SHR(MULT16_16SU(SHR((b),16),((a)&0x0000ffff)),15))
 
+/** 32x32 multiplication, followed by a 32-bit shift right. Results fits in 32 bits */
 #define MULT32_32_Q32(a,b) ADD32(ADD32(MULT16_16(SHR((a),16),SHR((b),16)), SHR(MULT16_16SU(SHR((a),16),((b)&0x0000ffff)),16)), SHR(MULT16_16SU(SHR((b),16),((a)&0x0000ffff)),16))
 
-
+/** Compile-time conversion of float constant to 16-bit value */
 #define QCONST16(x,bits) ((celt_word16_t)(.5+(x)*(((celt_word32_t)1)<<(bits))))
+/** Compile-time conversion of float constant to 32-bit value */
 #define QCONST32(x,bits) ((celt_word32_t)(.5+(x)*(((celt_word32_t)1)<<(bits))))
 
+/** Negate a 16-bit value */
 #define NEG16(x) (-(x))
+/** Negate a 32-bit value */
 #define NEG32(x) (-(x))
+
+/** Change a 32-bit value into a 16-bit value. The value is assumed to fit in 16-bit, otherwise the result is undefined */
 #define EXTRACT16(x) ((celt_word16_t)(x))
+/** Change a 16-bit value into a 32-bit value */
 #define EXTEND32(x) ((celt_word32_t)(x))
+
+/** Arithmetic shift-right of a 16-bit value */
 #define SHR16(a,shift) ((a) >> (shift))
+/** Arithmetic shift-left of a 16-bit value */
 #define SHL16(a,shift) ((a) << (shift))
+/** Arithmetic shift-right of a 32-bit value */
 #define SHR32(a,shift) ((a) >> (shift))
+/** Arithmetic shift-left of a 32-bit value */
 #define SHL32(a,shift) ((celt_word32_t)(a) << (shift))
+
+/** 16-bit arithmetic shift right with rounding-to-nearest instead of rounding down */
 #define PSHR16(a,shift) (SHR16((a)+((1<<((shift))>>1)),shift))
+/** 32-bit arithmetic shift right with rounding-to-nearest instead of rounding down */
 #define PSHR32(a,shift) (SHR32((a)+((EXTEND32(1)<<((shift))>>1)),shift))
+/** 32-bit arithmetic shift right where the argument can be negative */
 #define VSHR32(a, shift) (((shift)>0) ? SHR32(a, shift) : SHL32(a, -(shift)))
+
+/** Saturates 16-bit value to +/- a */
 #define SATURATE16(x,a) (((x)>(a) ? (a) : (x)<-(a) ? -(a) : (x)))
+/** Saturates 32-bit value to +/- a */
 #define SATURATE32(x,a) (((x)>(a) ? (a) : (x)<-(a) ? -(a) : (x)))
 
+/** "RAW" macros, should not be used outside of this header file */
 #define SHR(a,shift) ((a) >> (shift))
 #define SHL(a,shift) ((celt_word32_t)(a) << (shift))
 #define PSHR(a,shift) (SHR((a)+((EXTEND32(1)<<((shift))>>1)),shift))
 #define SATURATE(x,a) (((x)>(a) ? (a) : (x)<-(a) ? -(a) : (x)))
 
+/** Shift by a and round-to-neareast 32-bit value. Result is a 16-bit value */
 #define ROUND(x,a) (EXTRACT16(PSHR32((x),(a))))
+/** Divide by two */
 #define HALF32(x)  (SHR32(x,1))
 
+/** Add two 16-bit values */
 #define ADD16(a,b) ((celt_word16_t)((celt_word16_t)(a)+(celt_word16_t)(b)))
+/** Subtract two 16-bit values */
 #define SUB16(a,b) ((celt_word16_t)(a)-(celt_word16_t)(b))
+/** Add two 32-bit values */
 #define ADD32(a,b) ((celt_word32_t)(a)+(celt_word32_t)(b))
+/** Subtract two 32-bit values */
 #define SUB32(a,b) ((celt_word32_t)(a)-(celt_word32_t)(b))
 
 
-/* result fits in 16 bits */
+/** 16x16 multiplication where the result fits in 16 bits */
 #define MULT16_16_16(a,b)     ((((celt_word16_t)(a))*((celt_word16_t)(b))))
 
 /* (celt_word32_t)(celt_word16_t) gives TI compiler a hint that it's 16x16->32 multiply */
+/** 16x16 multiplication where the result fits in 32 bits */
 #define MULT16_16(a,b)     (((celt_word32_t)(celt_word16_t)(a))*((celt_word32_t)(celt_word16_t)(b)))
 
+/** 16x16 multiply-add where the result fits in 32 bits */
 #define MAC16_16(c,a,b) (ADD32((c),MULT16_16((a),(b))))
+/** 16x32 multiplication, followed by a 12-bit shift right. Results fits in 32 bits */
 #define MULT16_32_Q12(a,b) ADD32(MULT16_16((a),SHR((b),12)), SHR(MULT16_16((a),((b)&0x00000fff)),12))
+/** 16x32 multiplication, followed by a 13-bit shift right. Results fits in 32 bits */
 #define MULT16_32_Q13(a,b) ADD32(MULT16_16((a),SHR((b),13)), SHR(MULT16_16((a),((b)&0x00001fff)),13))
+/** 16x32 multiplication, followed by a 14-bit shift right. Results fits in 32 bits */
 #define MULT16_32_Q14(a,b) ADD32(MULT16_16((a),SHR((b),14)), SHR(MULT16_16((a),((b)&0x00003fff)),14))
 
+/** 16x32 multiplication, followed by an 11-bit shift right. Results fits in 32 bits */
 #define MULT16_32_Q11(a,b) ADD32(MULT16_16((a),SHR((b),11)), SHR(MULT16_16((a),((b)&0x000007ff)),11))
+/** 16x32 multiply-add, followed by an 11-bit shift right. Results fits in 32 bits */
 #define MAC16_32_Q11(c,a,b) ADD32(c,ADD32(MULT16_16((a),SHR((b),11)), SHR(MULT16_16((a),((b)&0x000007ff)),11)))
 
+/** 16x32 multiplication, followed by a 15-bit shift right (round-to-nearest). Results fits in 32 bits */
 #define MULT16_32_P15(a,b) ADD32(MULT16_16((a),SHR((b),15)), PSHR(MULT16_16((a),((b)&0x00007fff)),15))
+/** 16x32 multiply-add, followed by a 15-bit shift right. Results fits in 32 bits */
 #define MAC16_32_Q15(c,a,b) ADD32(c,ADD32(MULT16_16((a),SHR((b),15)), SHR(MULT16_16((a),((b)&0x00007fff)),15)))
 
 
@@ -106,11 +144,13 @@
 #define MULT16_16_P14(a,b) (SHR(ADD32(8192,MULT16_16((a),(b))),14))
 #define MULT16_16_P15(a,b) (SHR(ADD32(16384,MULT16_16((a),(b))),15))
 
-#define MUL_16_32_R15(a,bh,bl) ADD32(MULT16_16((a),(bh)), SHR(MULT16_16((a),(bl)),15))
-
+/** Divide a 32-bit value by a 16-bit value. Result fits in 16 bits */
 #define DIV32_16(a,b) ((celt_word16_t)(((celt_word32_t)(a))/((celt_word16_t)(b))))
+/** Divide a 32-bit value by a 16-bit value and round to nearest. Result fits in 16 bits */
 #define PDIV32_16(a,b) ((celt_word16_t)(((celt_word32_t)(a)+((celt_word16_t)(b)>>1))/((celt_word16_t)(b))))
+/** Divide a 32-bit value by a 32-bit value. Result fits in 32 bits */
 #define DIV32(a,b) (((celt_word32_t)(a))/((celt_word32_t)(b)))
+/** Divide a 32-bit value by a 32-bit value and round to nearest. Result fits in 32 bits */
 #define PDIV32(a,b) (((celt_word32_t)(a)+((celt_word16_t)(b)>>1))/((celt_word32_t)(b)))
 
 #endif