/*********************************************************************
*                                                                    *
*                       Software License Agreement                   *
*                                                                    *
*   The software supplied herewith by Microchip Technology           *
*   Incorporated (the "Company") for its dsPIC controller            *
*   is intended and supplied to you, the Company's customer,         *
*   for use solely and exclusively on Microchip dsPIC                *
*   products. The software is owned by the Company and/or its        *
*   supplier, and is protected under applicable copyright laws. All  *
*   rights are reserved. Any use in violation of the foregoing       *
*   restrictions may subject the user to criminal sanctions under    *
*   applicable laws, as well as to civil liability for the breach of *
*   the terms and conditions of this license.                        *
*                                                                    *
*   THIS SOFTWARE IS PROVIDED IN AN "AS IS" CONDITION.  NO           *
*   WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING,    *
*   BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND    *
*   FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE     *
*   COMPANY SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL,  *
*   INCIDENTAL OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.  *
*                                                                    *
*   (c) Copyright 2003 Microchip Technology, All rights reserved.    *
*********************************************************************/

/****************************************************************************
*
* DSP.H
* Interface to the DSP Library for the dsPIC30F.
*
****************************************************************************/

#ifndef	__DSP_LIB__	/* [ */
#define	__DSP_LIB__

/***************************************************************************/

/* External headers. */

#include	<stdlib.h>		/* malloc, NULL */
#include	<math.h>		/* fabs, sin, cos, atan, sqrt */

/*...........................................................................*/

/* Local defines. */

#define	FLOATING	-1			/* using floating type */
#define	FRACTIONAL	 1			/* using fractional type */
#ifndef	DATA_TYPE			/* [ */
#define	DATA_TYPE	FRACTIONAL		/* default */
#endif	/* ] */

/* Some constants. */
#ifndef	PI				/* [ */
#define	PI 3.1415926535897931159979634685441851615905761718750 /* double */
#endif	/* ] */
#ifndef	SIN_PI_Q				/* [ */
#define	SIN_PI_Q 0.7071067811865474617150084668537601828575134277343750
						/* sin(PI/4), (double) */
#endif	/* ] */
#ifndef	INV_SQRT2				/* [ */
#define	INV_SQRT2 SIN_PI_Q			/* 1/sqrt(2), (double) */
						/* 1/sqrt(2) = sin(PI/4) */
#endif	/* ] */

#define	BART_0		 2.0			/* Bartlett 0th factor */

#define	HANN_0		 0.50			/* Hanning 0th factor */
#define	HANN_1		-0.50			/* Hanning 1st factor */

#define	HAMM_0		 0.53836		/* Hamming 0th factor */
#define	HAMM_1		-0.46164		/* Hamming 1st factor */

#define	BLCK_0		 0.42			/* Blackman 0th factor */
#define	BLCK_1		-0.50			/* Blackman 1st factor */
#define	BLCK_2		 0.08			/* Blackman 2nd factor */

#define	COEFFS_IN_DATA	0xFF00			/* page number used for */
						/* filter coefficients */
						/* when allocated in X */
						/* data memory */
/*...........................................................................*/

/* Local types. */

/* Type definitions. */
#ifndef	fractional			/* [ */

#if	DATA_TYPE==FLOATING		/* [ */
typedef	double		fractional;
#else	/* ] */
typedef	int		fractional;
#endif	/* ] */

#ifndef	fractcomplex			/* [ */
typedef struct {
  fractional real;
  fractional imag;
} fractcomplex;
#endif	/* ] fractcomplex */

#endif	/* ] fractional */

/*...........................................................................*/

/****************************************************************************
*
* Preliminary remarks.
*
* None of the functions provided within this API allocate memory space.
*
****************************************************************************/

/*...........................................................................*/

/****************************************************************************
*
* Interface to generic function prototypes. 
*
****************************************************************************/

/* Generic function prototypes. */


#if	DATA_TYPE==FLOATING		/* [ */
#define	Float2Fract(aVal)	(aVal)	/* Identity function */
#else	/* ] */
extern fractional Float2Fract (		/* Converts float into fractional */
   float aVal				/* float value in range [-1, 1) */
);
#endif	/* ] */

/*...........................................................................*/

/****************************************************************************
*
* Interface to vector operations.
*
* A vector is a collection of numerical values, the vector elements,
* allocated contiguosly in memory, with the first element at the
* lowest memory address. One word of memory (two bytes) is used to
* store the value of each element, and this quantity must be interpreted
* as a fractional value in Q.15 format.
*
* A pointer addressing the first element of the vector is used as
* a handle which provides access to each of the vector values. The
* one dimensional arrangement of a vector fits with the memory
* storage model, so that the n-th element of an N-element vector
* can be accessed from the vector's base address BA as:
*
*	BA +  (n-1)*2,
*
* Note that because of the byte addressing capabilities of the dsPIC30F,
* the addressing of vector elements uses an increment (or decrement) size
* of 2: INC2 (or DEC2) instruction.
*
* Unary and binary operations are prototyped in this interface. The
* operand vector in a unary operation is called the source vector.
* In a binary operation the first operand is referred to as source
* one vector, and the second as source two vector. Each operation
* applies some computation to one or several elements of the source
* vector(s). Some operations result in a scalar value (also to be
* interpreted as a Q.15 fractional number), others in a vector. When
* the result is also a vector this is referred to as the destination
* vector.
*
* Some operations resulting in a vector allow computation in place;
* i.e., the results of the operations are placed back on the source
* (or source one, if binary) vector. In this case, the destination
* vector is said to (physically) replace the source (one) vector.
* When an operation can be computed in place it is indicated as such
* in the comments provided with its prototype.
*
* For some binary operations, the two operands can be the same (physical)
* source vector: the operation is applied between the source vector
* and itself. If this type of computation is possible for a given
* operation, it is indicated as such in the comments provided with
* its prototype.
* 
* Some operations can be self applicable and computed in place.
* 
* The operations prototyped in this interface take as an argument the
* cardinality (number of elements) of the operand vector(s). It is
* assumed that this number is in the range {1, 2, ..., (2^14)-1}, and
* that in the case of binary operations both operand vectors have the
* same cardinality. Note that no boundary checking is performed by
* the operations, and that out of range cardinalities as well as the
* use of source vectors of different sizes in binary operations may
* produce unexpected results.
*
* Additional remarks.
*
* A) Operations which return a destination vector can be nested, so that
*    for instance if:
*
*	a = Op1 (b, c), with b = Op2 (d), and c = Op3 (e, f), then
*
*	a = Op1 (Op2 (d), Op3 (e, f))
*
* B) The vector dot product and power operations could lead to saturation
*    if the sum of products is greater than 1-2^(-15) or smaller than -1.
*
* C) All the functions have been designed to operate on vectors allocated
*    in default RAM memory space (X-Data or Y-Data).
*
* D) The sum of sizes of the vector(s) involved in an operation must not
*    exceed the available memory in the target device.
*
****************************************************************************/

/* Vector operation prototypes. */


extern fractional VectorMax (		/* Vector (last) maximum */
					/* maxVal = max{srcV[elem]} */
					/* if srcV[i] = srcV[j] = maxVal */
					/* and i < j, then *(maxIndex) = j */
   int numElems,			/* number elements in srcV */
   fractional* srcV,			/* ptr to source vector */
   int* maxIndex			/* ptr to index for maximum value */

					/* maxVal returned */
);

/*...........................................................................*/

extern fractional VectorMin (		/* Vector (last) minimum */
					/* minVal = min{srcV[elem]} */
					/* if srcV[i] = srcV[j] = minVal */
					/* and i < j, then *(minIndex) = j */
   int numElems,			/* number elements in srcV */
   fractional* srcV,			/* ptr to source vector */
   int* minIndex			/* ptr to index for minimum value */

					/* minVal returned */
);

/*...........................................................................*/

extern fractional* VectorCopy (		/* Copy elements from source vector */
					/* to an (existing) dest vector */
					/* (both srcV and dstV MUST have, */
					/* at least, numElems elements). */
					/* dstV[n] = srcV[n], 0 <= n < N */
					/* (in place capable) */
   int numElems,			/* number elements to copy (N) */
   fractional* dstV,			/* ptr to destination vector */
   fractional* srcV			/* ptr to source vector */

					/* dstV returned */
);

/*...........................................................................*/

extern fractional* VectorZeroPad (	/* Zero pad tail of a vector */
					/* dstV[n] = srcV[n], 0 <= n < N */
					/* dstV[n] = 0, N <= n < N+M */
					/* (srcV MUST have length >= N) */
					/* (dstV MUST have length N+M) */
					/* (in place capable) */
   int numElems,			/* number elements in srcV (N) */
   int numZeros,			/* number zeros to append (M) */
   fractional* dstV,			/* ptr to destination vector */
   fractional* srcV			/* ptr to source vector */

					/* dstV returned */
);

/*...........................................................................*/

extern fractional* VectorNegate (	/* Vector negate */
					/* dstV[n] = (-1)*srcV[n]+0, 0<=n<N */
					/* (in place capable) */
   int numElems,			/* number elements in srcV (N) */
   fractional* dstV,			/* ptr to destination vector */
   fractional* srcV			/* ptr to source vector */

					/* dstV returned */
);

/*...........................................................................*/

extern fractional* VectorScale (	/* Vector scale */
					/* dstV[elem] = sclVal*srcV[elem] */
					/* (in place capable) */
   int numElems,			/* number elements in srcV (N) */
   fractional* dstV,			/* ptr to destination vector */
   fractional* srcV,			/* ptr to source vector */
   fractional sclVal			/* scale value (Q.15 fractional) */

					/* dstV returned */
);

/*...........................................................................*/

extern fractional* VectorAdd (		/* Vector addition */
					/* dstV[elem] =			*/
					/*    = srcV1[elem] + srcV2[elem] */
					/* (in place capable) */
					/* (with itself capable) */
   int numElems,			/* number elements in srcV[1,2] (N) */
   fractional* dstV,			/* ptr to destination vector */
   fractional* srcV1,			/* ptr to source vector one */
   fractional* srcV2			/* ptr to source vector two */

					/* dstV returned */
);

/*...........................................................................*/

extern fractional* VectorSubtract (	/* Vector subtraction */
					/* dstV[elem] =			*/
					/*    = srcV1[elem] - srcV2[elem] */
					/* (in place capable) */
					/* (with itself capable) */
   int numElems,			/* number elements in srcV[1,2] (N) */
   fractional* dstV,			/* ptr to destination vector */
   fractional* srcV1,			/* ptr to source vector one */
   fractional* srcV2			/* ptr to source vector two */

					/* dstV returned */
);

/*...........................................................................*/

extern fractional* VectorMultiply (	/* Vector elem-to-elem multiply */
					/* dstV[elem] =			*/
					/*    = srcV1[elem] * srcV2[elem] */
					/* (in place capable) */
					/* (with itself capable) */
   int numElems,			/* number elements in srcV[1,2] (N) */
   fractional* dstV,			/* ptr to destination vector */
   fractional* srcV1,			/* ptr to source vector one */
   fractional* srcV2			/* ptr to source vector two */

					/* dstV returned */
);

/*...........................................................................*/

extern fractional VectorDotProduct (	/* Vector dot product */
					/* dotVal =			*/
					/*    = sum(srcV1[elem]*srcV2[elem]) */
					/* (with itself capable) */
   int numElems,			/* number elements in srcV[1,2] (N) */
   fractional* srcV1,			/* ptr to source vector one */
   fractional* srcV2			/* ptr to source vector two */

					/* dot product value returned */
);

/*...........................................................................*/

extern fractional VectorPower (		/* Vector power */
					/* powVal =			*/
					/*    = sum(srcV[elem]^2)	*/
   int numElems,			/* number elements in srcV (N) */
   fractional* srcV			/* ptr to source vector one */

					/* power value returned */
);

/*...........................................................................*/

extern fractional* VectorConvolve (	/* Vector Convolution */
					/* (with itself capable) */
   int numElems1,			/* number elements in srcV1 */
   int numElems2,			/* number elements in srcV2 */
   					/* numElems2 <= numElems1 */
   fractional* dstV,			/* ptr to destination vector */
   					/* with numElems1+numElems2-1 elems */