root/SigProc/branches/SigProc-c/src/sigprocc.h @ 5709

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

Copyright 2007 Virginia Polytechnic Institute and State University

This file is part of the OSSIE Signal Processing C Library.

OSSIE Signal Processing C Library is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the License,
or (at your option) any later version.

OSSIE Signal Processing C Library is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with OSSIE Signal Processing C Library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


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

#ifndef __SIG_PROC_C_H__
#define __SIG_PROC_C_H__

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>

#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */

#ifdef FPM
#include "fixed.h"
#endif

#define PI      3.14159265358979f
#define TWO_PI  6.28318530717959f

//-----------------------------------------------------------------------------
//
// Design root raised-cosine filter
//
//-----------------------------------------------------------------------------
void design_rrc_filter(
  unsigned int k,      // samples per symbol
  unsigned int m,      // delay
  float beta,          // rolloff factor ( 0 < beta <= 1 )
  float * h            // pointer to filter coefficients
);

//-----------------------------------------------------------------------------
//
// Design Gaussian filter
//
//-----------------------------------------------------------------------------
void design_gaussian_filter(
  unsigned int k,      // samples per symbol
  unsigned int m,      // delay
  float beta,          // rolloff factor ( 0 < beta <= 1 )
  float * h            // pointer to filter coefficients
);

//-----------------------------------------------------------------------------
//
// Design low-pass butterworth filter
//
//-----------------------------------------------------------------------------
void design_butter_lowpass_filter(
  unsigned int order,   // filter order
  float wc,             // cutoff frequency
  float *b,             // feedback
  float *a              // feedforward
);

//-----------------------------------------------------------------------------
//
// Circular buffer
//
//-----------------------------------------------------------------------------
/** \brief Circlar buffer structure
 *
 * \section CB_basic_description Basic Description
 * The circular buffer template class implementation minimizes memory copies
 * by wrapping the array around to its beginning.  Elements can be added
 * and removed by invoking the Push() and Pop() methods, respectively.
 *
 * \section CB_creating Creating Buffers
 * There are three ways to create a buffer...
 * \code
 * // 1. generate an empty buffer
 * CircularBuffer <short> v1(100);
 *
 * // 2. wrap an existing array
 * short * x = new short[100];
 * for (unsigned int i=0; i<100; i++)
 *     x[i] = i;
 * CircularBuffer <short> v2(x, 100);
 *
 * // 3. copy from another CircularBuffer
 * CircularBuffer <short> v3(v2);
 * \endcode
 *
 * \section CB_resizing_buffers Resizing Buffers
 * CircularBuffer supports dynamic memory allocation as well; if an instance
 * of CircularBuffer is created of a particular size and then later it is
 * determined that the size is too small, invoking SetBufferSize() can be used
 * to increase the length without loss of data.  However, decreasing the buffer
 * size beyond the number of elements in the buffer truncates the data.
 *
 * \section CB_wrapping Wrapping
 * When the buffer is full and another element is pushed, the new element
 * overwrites the last element in the buffer without warning.  Status of the
 * buffer can be checked with the GetBufferSize() and GetNumElements()
 * methods.
 *
 */

struct circular_buffer {
    float * v;
    unsigned int len;
    unsigned int head_index;
};

typedef struct circular_buffer circular_buffer_t;

/// Create circular buffer object, including memory allocation
circular_buffer_t * circular_buffer_create(unsigned int buffer_lenth);

/// Initialize circular buffer object
void circular_buffer_initialize(circular_buffer_t * c, float * _v, unsigned int buffer_length);

/// Push value into buffer
void circular_buffer_push(circular_buffer_t * c, float x);

/// Index value within buffer
float circular_buffer_value(circular_buffer_t * c, unsigned int i);

/// Linearize a circular buffer object
void circular_buffer_linearize(circular_buffer_t * c);

/// Get pointer to linearized buffer object
float * circular_buffer_getpointer(circular_buffer_t * c);

/// Print buffer values to screen
void circular_buffer_print(circular_buffer_t * c);

/// Destroy circular buffer object, free memory
void circular_buffer_destroy(circular_buffer_t * c);

//-----------------------------------------------------------------------------
//
// P/N Sequence
//
//-----------------------------------------------------------------------------


//-----------------------------------------------------------------------------
//
// Automatic Gain Control class
//
//-----------------------------------------------------------------------------
/** \brief Automatic gain control signal processor
 *
 * \cite  R. G. Lyons, Understanding Digital Signal Processing, 2nd ed. New Jersey:
 * Prentice Hall, 2004.
 */

//-----------------------------------------------------------------------------
//
// FIR polyphase filter bank
//
//-----------------------------------------------------------------------------
/** \brief Finite impulse response (FIR) polyphase filter bank
 *
 * This class implementes a finite impulse response (FIR) polyphase filter
 * bank useful for decimators that need to interpolate samples in digital
 * receivers.
 *
 * The filter bank can automatically calculate filter coefficients for
 * prototypes commonly used in communications systems. Currently, such
 * supported filter prototypes are
 *   - root raised-cosine
 *
 * Filter prototypes that will eventually be supported are
 *   - raised-cosine
 *   - gaussian
 *   - triangular
 *   - hamming
 *
 * The user can also load filter coefficients that have been calculated
 * externally.
 *
 * \image latex polyphase_rcos_filter_k2_N4.eps "Example filter bank (1)"
 * \image html polyphase_rcos_filter_k2_N4.png  "Example filter bank (1)"
 *
 * \image latex polyphase_rcos_filter_k4_N2.eps "Example filter bank (2)"
 * \image html polyphase_rcos_filter_k4_N2.png  "Example filter bank (2)"
 *
 * \cite M. Rice and fred harris, "Polyphase Filterbanks for Symbol Timing
 * Synchronization in Sampled Data Receivers," in MILCOMM Proceedings, vol.
 * 2, October 2002, pp. 982--986.
 *
 */

struct polyphase_filterbank {
    float * H;
    unsigned int Npfb;
    unsigned int h_len;
    circular_buffer_t * v;
};

typedef struct polyphase_filterbank polyphase_filterbank_t;

//
void polyphase_filterbank_initialize();

//-----------------------------------------------------------------------------
//
// Dot product definitions
//
//-----------------------------------------------------------------------------
float dot_product(float *x, float *y, unsigned int N);
//short dot_product(short *x, short *y, unsigned int N);
//short dot_product(float *x, short *y, unsigned int N);
//float dot_product(float *x, short *y, unsigned int N);

//-----------------------------------------------------------------------------
//
// Misellany
//
//-----------------------------------------------------------------------------

/// Uniform random number generator, (0,1]
float randf();

/// Gaussian random number generator, N(0,1)
void randnf(float * i, float * q);

//-----------------------------------------------------------------------------
//
// Trigonometric functions
//
//-----------------------------------------------------------------------------
float arctan(float x, float y);


//-----------------------------------------------------------------------------
//
// Byte packing functions
//
//-----------------------------------------------------------------------------
void pack_bytes(
    char * input,
    unsigned int input_length,
    char * output,
    unsigned int output_length,
    unsigned int *num_written);

void unpack_bytes(
    char * input,
    unsigned int input_length,
    char * output,
    unsigned int output_length,
    unsigned int *num_written);

void repack_bytes(
    char * input,
    unsigned int input_sym_size,
    unsigned int input_length,
    char * output,
    unsigned int output_sym_size,
    unsigned int output_length,
    unsigned int *num_written);


//-----------------------------------------------------------------------------
//
// Modulation functions
//
//-----------------------------------------------------------------------------

///
enum modulation_scheme {
        UNKNOWN,                                // Unknown modulation scheme
        BPSK,   QPSK,   PSK8,   PSK16,          // Phase shift keying
        DBPSK,  DQPSK,  DPSK8,  DPSK16,         // Differential PSK
        PAM4,   PAM8,   PAM16,  PAM32,          // Pulse amplitude modulation
        BFSK,   FSK4,   FSK8,   FSK16,          // Frequency shift keying
        QAM16,  QAM32,  QAM64,  QAM128, QAM256  // Quadrature amplitude modulation
        };

#define BPSK_ALPHA      1
#define QPSK_ALPHA      1/sqrt(2)

#define QAM16_ALPHA     1/sqrt(10)
#define QAM32_ALPHA     1/sqrt(20)
#define QAM64_ALPHA     1/sqrt(42)
#define QAM128_ALPHA    1/sqrt(82)
#define QAM256_ALPHA    1/sqrt(170)

#define PAM4_ALPHA      1/sqrt(5)
#define PAM8_ALPHA      1/sqrt(21)
#define PAM16_ALPHA     1/sqrt(85)

#define BPSK_LEVEL      10000   ///< BPSK amplitude (RMS=10000)
#define QPSK_LEVEL      7071    ///< QPSK amplitude (RMS=10000)
#define PSK8_LEVEL_1    7071    ///< Low 8-PSK amplitude (RMS=10000)
#define PSK8_LEVEL_2    10000   ///< High 8-PSK amplitude (RMS=10000)
#define QAM16_LEVEL_1   3162    ///< Low 16-QAM amplitude (RMS=10000)
#define QAM16_LEVEL_2   9487    ///< High 16-QAM amplitude (RMS=10000)
#define PAM4_LEVEL_1    4472    ///< Low 4-PAM amplitude (RMS=10000)
#define PAM4_LEVEL_2    13416   ///< High 4-PAM amplitude (RMS=10000)

/// modulate_s a symbol into an I/Q pair for binary phase shift keying
///
/// \image latex ConstellationBPSK.eps "BPSK constellation"
/// \image html ConstellationBPSK.png "BPSK constellation"
void modulate_bpsk(short symbol_in, short *I_out, short *Q_out);

/// modulate_s a symbol into an I/Q pair for quadrature phase shift keying
///
/// \image latex ConstellationQPSK.eps "QPSK constellation"
/// \image html ConstellationQPSK.png "QPSK constellation"
void modulate_qpsk(short symbol_in, short *I_out, short *Q_out);

/// modulate_s a symbol into an I/Q pair for 8-ary phase shift keying
///
/// \image latex Constellation8PSK.eps "8-PSK constellation"
/// \image html Constellation8PSK.png "8-PSK constellation"
void modulate_8psk(short symbol_in, short *I_out, short *Q_out);

/// modulate_s a symbol into an I/Q pair for 16-point quadrature
/// amplitude modulation
///
/// \image latex Constellation16QAM.eps "16-QAM constellation"
/// \image html Constellation16QAM.png "16-QAM constellation"
void modulate_16qam(short symbol_in, short *I_out, short *Q_out);

/// modulate_s a symbol into an I/Q pair for 4-ary pulse amplitude
/// modulation
///
/// \image latex Constellation4PAM.eps "4-PAM constellation"
/// \image html Constellation4PAM.png "4-PAM constellation"
void modulate_4pam(short symbol_in, short *I_out, short *Q_out);


#define DEMOD_COS_22_5 0.923879532511287
#define DEMOD_SIN_22_5 0.382683432365090

#define QAM16_THRESHOLD 6324    ///< 16-QAM threshold for RMS=10000 signal
#define PAM4_THRESHOLD  8944    ///< 4-PAM threshold for RMS=10000 signal

///
void demodulate_bpsk(short I_in, short Q_in, short *symbol_out);

///
void demodulate_qpsk(short I_in, short Q_in, short *symbol_out);

///
void demodulate_8psk(short I_in, short Q_in, short *symbol_out);

///
void demodulate_16qam(short I_in, short Q_in, short *symbol_out);

///
void demodulate_4pam(short I_in, short Q_in, short *symbol_out);

#ifdef __cplusplus
}  /* extern "C" */
#endif /* __cplusplus */

#endif /* __SIG_PROC_H__ */