Class for generic DSP functions. More...

#include <MpDspUtils.h>

Static Public Member Functions
Arithmetic Functions
static int16_t	add (int16_t a, int16_t b)
	Return (a+b) saturated (16-bit). More...

static void	add_I (int16_t &a, int16_t b)
	Perform (a+=b) saturated (16-bit). More...

static int32_t	add (int32_t a, int32_t b)
	Return (a+b) saturated (32-bit). More...

static void	add_I (int32_t &a, int32_t b)
	Perform (a+=b) saturated (32-bit). More...

static void	addMul_I (int32_t &a, int16_t b, int16_t c)
	Perform (a+=b*c) saturated (32-bit accumulator, 16-bit operands). More...

static int16_t	abs (int16_t a)
	Perform absolute value calculation with saturation. More...

static int16_t	minimum (int16_t a, int16_t b)
	Perform minimum value calculation. More...

static int16_t	maximum (int16_t a, int16_t b)
	Perform maximum value calculation. More...

static int32_t	abs (int32_t a)
	Perform absolute value calculation with saturation. More...

static int32_t	minimum (int32_t a, int32_t b)
	Perform minimum value calculation. More...

static int32_t	maximum (int32_t a, int32_t b)
	Perform maximum value calculation. More...

static uint32_t	sqrt (uint32_t val)
	Integer square root. More...

Serial Number Arithmetic (Arithmetic with Overflow)
static int	compareSerials (uint32_t val1, uint32_t val2)
	Is `val1` bigger, equal or lesser then `val2`. More...

static int	compareSerials (uint16_t val1, uint16_t val2)
	Is `val1` bigger, equal or lesser then `val2`. More...

Vector Logical and Shift Functions
static void	shl16_I (int32_t &a, unsigned scale)

static int32_t	shl16 (int32_t a, unsigned scale)

static void	shl32_I (int32_t &a, unsigned scale)

static int32_t	shl32 (int32_t a, unsigned scale)

Vector Arithmetic Functions
static MP_DSP_VECTOR_API OsStatus	add_I (const int16_t pSrc1, int32_t pSrc2Dst, int dataLength)
	Add source vector to accumulator. More...

static MP_DSP_VECTOR_API OsStatus	add_IGain (const int16_t pSrc1, int32_t pSrc2Dst, int dataLength, unsigned src1ScaleFactor)
	Gain source vector by 2^src1ScaleFactor factor and add it to accumulator. More...

static MP_DSP_VECTOR_API OsStatus	add_IAtt (const int16_t pSrc1, int32_t pSrc2Dst, int dataLength, unsigned src1ScaleFactor)
	Attenuate source vector by 2^src1ScaleFactor factor and add it to accumulator. More...

static MP_DSP_VECTOR_API OsStatus	add (const int32_t pSrc1, const int32_t pSrc2, int32_t *pDst, int dataLength)
	Add two vectors. More...

static MP_DSP_VECTOR_API OsStatus	addMul_I (const int16_t pSrc1, int16_t val, int32_t pSrc2Dst, int dataLength)
	Multiply source vector by given `val` and add it to accumulator vector. More...

static MP_DSP_VECTOR_API OsStatus	addMulLinear_I (const int16_t pSrc1, int16_t valStart, int16_t valEnd, int32_t pSrc2Dst, int dataLength)
	Multiply source vector by values linearly changing from `valStart` to `valEnd` and add it to accumulator vector. More...

static MP_DSP_VECTOR_API OsStatus	mul (const int16_t pSrc, const int16_t val, int32_t pDst, int dataLength)
	Multiply vector by constant. More...

static MP_DSP_VECTOR_API OsStatus	mul_I (int16_t *pSrcDst, const int16_t val, int dataLength)
	Multiply vector by constant with saturation. More...

static MP_DSP_VECTOR_API OsStatus	mulLinear (const int16_t pSrc, int16_t valStart, int16_t valEnd, int32_t pDst, int dataLength)
	Multiply source vector by values linearly changing from `valStart` to `valEnd` and add it to accumulator vector. More...

static int	maxAbs (const int16_t *pSrc, int dataLength)
	Calculate absolute maximum value of array. More...

static int16_t	maximum (const int16_t *pSrc, int dataLength)
	Calculate maximum value of array. More...

static int32_t	maximum (const int32_t *pSrc, int dataLength)
	Calculate maximum value of array. More...

static int16_t	minimum (const int16_t *pSrc, int dataLength)
	Calculate maximum value of array. More...

static int32_t	minimum (const int32_t *pSrc, int dataLength)
	Calculate maximum value of array. More...

static int32_t	countClippedValues (const int16_t *pSrc, int dataLength)
	Find the number of values in vector that are at maximum or minimum 16 bit value. More...

Vector Conversion Functions
static MP_DSP_VECTOR_API OsStatus	convert (const int32_t pSrc, int16_t pDst, int dataLength)
	Convert vector of 32-bit integers to 16-bit integers. More...

static MP_DSP_VECTOR_API OsStatus	convert_Gain (const int32_t pSrc, int16_t pDst, int dataLength, unsigned srcScaleFactor)
	Gain vector of 32-bit integers and convert them to 16-bit integers. More...

static MP_DSP_VECTOR_API OsStatus	convert_Att (const int32_t pSrc, int16_t pDst, int dataLength, unsigned srcScaleFactor)
	Attenuate vector of 32-bit integers and convert them to 16-bit integers. More...

static MP_DSP_VECTOR_API OsStatus	convert (const int16_t pSrc, int32_t pDst, int dataLength)
	Convert vector of 16-bit integers to 32-bit integers. More...

static MP_DSP_VECTOR_API OsStatus	convert_Gain (const int16_t pSrc, int32_t pDst, int dataLength, unsigned srcScaleFactor)
	Gain vector of 16-bit integers and convert them to 32-bit integers. More...

static MP_DSP_VECTOR_API OsStatus	convert_Att (const int16_t pSrc, int32_t pDst, int dataLength, unsigned srcScaleFactor)
	Attenuate vector of 16-bit integers and convert them to 32-bit integers. More...

Detailed Description

Class for generic DSP functions.

This is utils class, containing only static functions. It provide all DSP processing primitives we need, and meant to be good optimized. In fact, we want this to be only place, which will contain hardware specific speed optimizations. If you could not find what you need here - feel free to add it. But do not forget to add generic C-version of each function, so it will be available if there is no optimized version.

Namig conventions.

If function ends with I it is in-place function. That is its destination is one of source vectors (usually second). If function ends with Gain or Att and its source is integers, it is scaling function. That is it scale source vector up or down (gain or attenuate, respectively) before operation. Functions, where source vector is float never scale values, even with Gain or Att suffix. Their Gain and Att versions are provided to simplify writing of universal floating/fixed-point code.

Saturation.

All arithmetic functions saturate result if destination is integer value (that is for 8-bit unsigned data type 200+200=255). Functions do not saturate result if destination is floating point.

Unittest coverage.

All functions should be covered by unittests. If you implemented optimized version of some function, run unittests to check does your optimized version behave as expected. If unittests does not cover all paths inside your optimized function, add or modify unittests to cover all of them and check does your function behave the same as original one. If optimized version behave differently from original function and this is wanted behaviour, this is different function in fact. And so you should give it different name. When creating new function, do not forget to provide clean C implementation for convenience.

Warning: Please, keep all methods of this class static and stateless!

Member Function Documentation

int16_t add	(	int16_t	a,
		int16_t	b
	)

inlinestatic

Return (a+b) saturated (16-bit).

void add_I	(	int16_t &	a,
		int16_t	b
	)

inlinestatic

Perform (a+=b) saturated (16-bit).

int32_t add	(	int32_t	a,
		int32_t	b
	)

inlinestatic

Return (a+b) saturated (32-bit).

void add_I	(	int32_t &	a,
		int32_t	b
	)

inlinestatic

Perform (a+=b) saturated (32-bit).

void addMul_I	(	int32_t &	a,
		int16_t	b,
		int16_t	c
	)

inlinestatic

Perform (a+=b*c) saturated (32-bit accumulator, 16-bit operands).

int16_t abs ( int16_t a )

inlinestatic

Perform absolute value calculation with saturation.

This function differs from usual ::abs() because it saturates INT16_MIN value. This is essential in DSP calculations, because -INT16_MIN equals to 0 in IEEE format. Thus with this implementation abs(INT16_MIN) = INT16_MAX

int16_t minimum	(	int16_t	a,
		int16_t	b
	)

inlinestatic

Perform minimum value calculation.

int16_t maximum	(	int16_t	a,
		int16_t	b
	)

inlinestatic

Perform maximum value calculation.

int32_t abs ( int32_t a )

inlinestatic

Perform absolute value calculation with saturation.

This function differs from usual ::abs() because it saturates INT32_MIN value. This is essential in DSP calculations, because -INT32_MIN equals to 0 in IEEE format. Thus with this implementation abs(INT32_MIN) = INT32_MAX

int32_t minimum	(	int32_t	a,
		int32_t	b
	)

inlinestatic

Perform minimum value calculation.

int32_t maximum	(	int32_t	a,
		int32_t	b
	)

inlinestatic

Perform maximum value calculation.

uint32_t sqrt ( uint32_t val )

inlinestatic

Integer square root.

int compareSerials	(	uint32_t	val1,
		uint32_t	val2
	)

inlinestatic

Is val1 bigger, equal or lesser then val2.

This function should be used when comparing two values that may overflow. It assume that values could not differ by more then half of their maximum value. See RFC1982 Serial Number Arithmetic for better description and rules of use.

Return values

0	if val1 == val2
1	if val1 > val2
-1	if val1 < val2

Todo:: Write unittest!!!

int compareSerials	(	uint16_t	val1,
		uint16_t	val2
	)

inlinestatic

Is val1 bigger, equal or lesser then val2.

This function should be used when comparing two values that may overflow. It assume that values could not differ by more then half of their maximum value. See RFC1982 Serial Number Arithmetic for better description and rules of use.

Return values

0	if val1 == val2
1	if val1 > val2
-1	if val1 < val2

Todo:: Write unittest!!!

void shl16_I	(	int32_t &	a,
		unsigned	scale
	)

inlinestatic

Todo:: Write unittest!!!

int32_t shl16	(	int32_t	a,
		unsigned	scale
	)

inlinestatic

Todo:: Write unittest!!!

void shl32_I	(	int32_t &	a,
		unsigned	scale
	)

inlinestatic

Todo:: Write unittest!!!

int32_t shl32	(	int32_t	a,
		unsigned	scale
	)

inlinestatic

Todo:: Write unittest!!!

static MP_DSP_VECTOR_API OsStatus add_I	(	const int16_t *	pSrc1,
		int32_t *	pSrc2Dst,
		int	dataLength
	)

static

Add source vector to accumulator.

static MP_DSP_VECTOR_API OsStatus add_IGain	(	const int16_t *	pSrc1,
		int32_t *	pSrc2Dst,
		int	dataLength,
		unsigned	src1ScaleFactor
	)

static

Gain source vector by 2^src1ScaleFactor factor and add it to accumulator.

static MP_DSP_VECTOR_API OsStatus add_IAtt	(	const int16_t *	pSrc1,
		int32_t *	pSrc2Dst,
		int	dataLength,
		unsigned	src1ScaleFactor
	)

static

Attenuate source vector by 2^src1ScaleFactor factor and add it to accumulator.

static MP_DSP_VECTOR_API OsStatus add	(	const int32_t *	pSrc1,
		const int32_t *	pSrc2,
		int32_t *	pDst,
		int	dataLength
	)

static

Add two vectors.

Todo:: Write unittest!!!

static MP_DSP_VECTOR_API OsStatus addMul_I	(	const int16_t *	pSrc1,
		int16_t	val,
		int32_t *	pSrc2Dst,
		int	dataLength
	)

static

Multiply source vector by given val and add it to accumulator vector.

OsStatus addMulLinear_I	(	const int16_t *	pSrc1,
		int16_t	valStart,
		int16_t	valEnd,
		int32_t *	pSrc2Dst,
		int	dataLength
	)

static

Multiply source vector by values linearly changing from valStart to valEnd and add it to accumulator vector.

Todo:: Write unittest!!!

Note: Current implementation works correctly only when (dataLength << (valStart - valEnd)). See implementation for further discussion.

OsStatus mul	(	const int16_t *	pSrc,
		const int16_t	val,
		int32_t *	pDst,
		int	dataLength
	)

static

Multiply vector by constant.

Todo:: Write unittest!!!

static MP_DSP_VECTOR_API OsStatus mul_I	(	int16_t *	pSrcDst,
		const int16_t	val,
		int	dataLength
	)

static

Multiply vector by constant with saturation.

Todo:: Write unittest!!!

OsStatus mulLinear	(	const int16_t *	pSrc,
		int16_t	valStart,
		int16_t	valEnd,
		int32_t *	pDst,
		int	dataLength
	)

static

Multiply source vector by values linearly changing from valStart to valEnd and add it to accumulator vector.

Todo:: Write unittest!!!

Note: Current implementation works correctly only when (dataLength << (valStart - valEnd)). See implementation for further discussion.

int maxAbs	(	const int16_t *	pSrc,
		int	dataLength
	)

inlinestatic

Calculate absolute maximum value of array.

Note: Result value is int because of inverting (-max_val-1) problem

int16_t maximum	(	const int16_t *	pSrc,
		int	dataLength
	)

inlinestatic

Calculate maximum value of array.

int32_t maximum	(	const int32_t *	pSrc,
		int	dataLength
	)

inlinestatic

Calculate maximum value of array.

int16_t minimum	(	const int16_t *	pSrc,
		int	dataLength
	)

inlinestatic

Calculate maximum value of array.

int32_t minimum	(	const int32_t *	pSrc,
		int	dataLength
	)

inlinestatic

Calculate maximum value of array.

int32_t countClippedValues	(	const int16_t *	pSrc,
		int	dataLength
	)

inlinestatic

Find the number of values in vector that are at maximum or minimum 16 bit value.

static MP_DSP_VECTOR_API OsStatus convert	(	const int32_t *	pSrc,
		int16_t *	pDst,
		int	dataLength
	)

static

Convert vector of 32-bit integers to 16-bit integers.

static MP_DSP_VECTOR_API OsStatus convert_Gain	(	const int32_t *	pSrc,
		int16_t *	pDst,
		int	dataLength,
		unsigned	srcScaleFactor
	)

static

Gain vector of 32-bit integers and convert them to 16-bit integers.

static MP_DSP_VECTOR_API OsStatus convert_Att	(	const int32_t *	pSrc,
		int16_t *	pDst,
		int	dataLength,
		unsigned	srcScaleFactor
	)

static

Attenuate vector of 32-bit integers and convert them to 16-bit integers.

static MP_DSP_VECTOR_API OsStatus convert	(	const int16_t *	pSrc,
		int32_t *	pDst,
		int	dataLength
	)

static

Convert vector of 16-bit integers to 32-bit integers.

Todo:: Write unittest!!!

static MP_DSP_VECTOR_API OsStatus convert_Gain	(	const int16_t *	pSrc,
		int32_t *	pDst,
		int	dataLength,
		unsigned	srcScaleFactor
	)

static

Gain vector of 16-bit integers and convert them to 32-bit integers.

Todo:: Write unittest!!!

static MP_DSP_VECTOR_API OsStatus convert_Att	(	const int16_t *	pSrc,
		int32_t *	pDst,
		int	dataLength,
		unsigned	srcScaleFactor
	)

static

Attenuate vector of 16-bit integers and convert them to 32-bit integers.

Todo:: Write unittest!!!

Static Public Member Functions

Detailed Description

Namig conventions.

Saturation.

Unittest coverage.

Member Function Documentation