dsps_cplx_gen.h File Reference

#include "dsp_err.h"
#include "dsps_cplx_gen_platform.h"

Include dependency graph for dsps_cplx_gen.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	cplx_sig_s
	Data struct of the complex signal generator. More...

Macros
#define	dsps_cplx_gen   dsps_cplx_gen_ansi

Typedefs
typedef enum output_data_type	out_d_type
	Ennum defining output data type of the complex generator.
typedef struct cplx_sig_s	cplx_sig_t
	Data struct of the complex signal generator.

Enumerations
enum	output_data_type { S16_FIXED = 0 , F32_FLOAT = 1 }
	Ennum defining output data type of the complex generator. More...

Functions
esp_err_t	dsps_cplx_gen_init (cplx_sig_t *cplx_gen, out_d_type d_type, void *lut, int32_t lut_len, float freq, float initial_phase)
	Initialize strucure for complex generator.
esp_err_t	dsps_cplx_gen_freq_set (cplx_sig_t *cplx_gen, float freq)
	function sets the output frequency of the complex generator
float	dsps_cplx_gen_freq_get (cplx_sig_t *cplx_gen)
	function gets the output frequency of the complex generator
esp_err_t	dsps_cplx_gen_phase_set (cplx_sig_t *cplx_gen, float phase)
	function sets the phase of the complex generator
float	dsps_cplx_gen_phase_get (cplx_sig_t *cplx_gen)
	function gets the phase of the complex generator
esp_err_t	dsps_cplx_gen_set (cplx_sig_t *cplx_gen, float freq, float phase)
	function sets the output frequency and the phase of the complex generator
void	cplx_gen_free (cplx_sig_t *cplx_gen)
	function frees dynamically allocated memory, which was allocated in the init function
esp_err_t	dsps_cplx_gen_ansi (cplx_sig_t *cplx_gen, void *output, int32_t len)
	The function generates a complex signal.
esp_err_t	dsps_cplx_gen_ae32 (cplx_sig_t *cplx_gen, void *output, int32_t len)

Macro Definition Documentation

dsps_cplx_gen

#define dsps_cplx_gen   dsps_cplx_gen_ansi

Definition at line 184 of file dsps_cplx_gen.h.

Typedef Documentation

cplx_sig_t

typedef struct cplx_sig_s cplx_sig_t

Data struct of the complex signal generator.

This structure is used by a complex generator internally. A user should access this structure only in case of extensions for the DSP Library. All the fields of this structure are initialized by the dsps_cplx_gen_init(...) function.

out_d_type

typedef enum output_data_type out_d_type

Ennum defining output data type of the complex generator.

Enumeration Type Documentation

output_data_type

enum output_data_type

Ennum defining output data type of the complex generator.

Enumerator
S16_FIXED	Q15 fixed point - int16_t
F32_FLOAT	Single precision floating point - float

Definition at line 23 of file dsps_cplx_gen.h.

                              {
    S16_FIXED = 0,              
    F32_FLOAT = 1,              
} out_d_type;

Function Documentation

cplx_gen_free()

void cplx_gen_free

(

cplx_sig_t *

cplx_gen

)

function frees dynamically allocated memory, which was allocated in the init function

free function must be called after the dsps_cplx_gen_init(...) is called, once the complex generator is not needed anymore

Parameters

cplx_gen

pointer to the complex signal generator structure

Definition at line 142 of file dsps_cplx_gen_init.c.

{
    if (cplx_gen->free_status & 0x0001) {
        free(cplx_gen->lut);
        cplx_gen->free_status = 0;
    }
}

References cplx_sig_s::free_status, and cplx_sig_s::lut.

dsps_cplx_gen_ae32()

esp_err_t dsps_cplx_gen_ae32	(	cplx_sig_t *	cplx_gen,
		void *	output,
		int32_t	len )

dsps_cplx_gen_ansi()

esp_err_t dsps_cplx_gen_ansi	(	cplx_sig_t *	cplx_gen,
		void *	output,
		int32_t	len )

The function generates a complex signal.

the generated complex signal is in the form of two harmonics signals in either 16-bit signed fixed point or 32-bit floating point

x[i]= A*sin(step*i + ph/180*Pi) x[i+1]= B*cos(step*i + ph/180*Pi) where step = 2*Pi*frequency

dsps_cplx_gen_ansi() - The implementation uses ANSI C and could be compiled and run on any platform dsps_cplx_gen_ae32() - Is targetted for Xtensa cores

Parameters

cplx_gen	pointer to the generator structure
output	output array (length of len*2), data type is void so both (S16_FIXED, F32_FLOAT) types could be used
len	length of the output signal

Returns

• ESP_OK on success
• One of the error codes from DSP library

Definition at line 9 of file dsps_cplx_gen.c.

{
    // angle frequency is already cplx_gen->freq
    const int sin_to_cos = cplx_gen->lut_len / 4;
    float ph = cplx_gen->phase;
    const float fr = cplx_gen->freq;
    int sin_pos, cos_pos;
 
    for (int i = 0 ; i < len; i++) {
 
        if (ph < 0) {
            ph += 1.0;
        }
        if (ph >= 1.0) {
            ph -= 1.0;
        }
 
        sin_pos = (int)(ph * (cplx_gen->lut_len));
        cos_pos = (sin_pos + sin_to_cos) & (cplx_gen->lut_len - 1);
 
        if (cplx_gen->d_type == S16_FIXED) {
            ((int16_t *)output)[i * 2 + 0] = ((int16_t *)cplx_gen->lut)[cos_pos];
            ((int16_t *)output)[i * 2 + 1] = ((int16_t *)cplx_gen->lut)[sin_pos];
        } else {
            ((float *)output)[i * 2 + 0] = ((float *)cplx_gen->lut)[cos_pos];
            ((float *)output)[i * 2 + 1] = ((float *)cplx_gen->lut)[sin_pos];
        }
        ph += fr;
    }
 
    return ESP_OK;
}

References cplx_sig_s::d_type, ESP_OK, cplx_sig_s::freq, cplx_sig_s::lut, cplx_sig_s::lut_len, cplx_sig_s::phase, and S16_FIXED.

dsps_cplx_gen_freq_get()

float dsps_cplx_gen_freq_get

(

cplx_sig_t *

cplx_gen

)

function gets the output frequency of the complex generator

get function can be used after the cplx_gen structure was initialized by the dsps_cplx_gen_init(...) function

Parameters

cplx_gen

pointer to the complex signal generator structure

Returns

function returns frequency of the signal generator

Definition at line 92 of file dsps_cplx_gen_init.c.

{
    // Check if the structure was initialized
    if (!dsp_is_power_of_two(cplx_gen->lut_len)) {
        ESP_LOGE(TAG, "cplx_gen strucure was not initialized");
        return -2;
    }
 
    return (cplx_gen->freq);
}

References dsp_is_power_of_two(), cplx_sig_s::freq, cplx_sig_s::lut_len, and TAG.

Here is the call graph for this function:

dsps_cplx_gen_freq_set()

esp_err_t dsps_cplx_gen_freq_set	(	cplx_sig_t *	cplx_gen,
		float	freq )

function sets the output frequency of the complex generator

set function can be used after the cplx_gen structure was initialized by the dsps_cplx_gen_init(...) function

Parameters

cplx_gen	pointer to the complex signal generator structure
freq	new frequency to be set in a range of [-1..1] where 1 is a Nyquist frequency

Returns

• ESP_OK on success
• ESP_ERR_DSP_INVALID_PARAM if the frequency is out of the Nyquist frequency range

Definition at line 81 of file dsps_cplx_gen_init.c.

{
    if ((freq >= 1) || (freq <= -1)) {          // frequency is a Nyquist frequency, must be in a range from (-1 to 1)
        ESP_LOGE(TAG, "The frequency is out of range. Valid range is +/- 1. ");
        return ESP_ERR_DSP_INVALID_PARAM;
    }
 
    cplx_gen->freq = freq;
    return ESP_OK;
}

References ESP_ERR_DSP_INVALID_PARAM, ESP_OK, cplx_sig_s::freq, and TAG.

dsps_cplx_gen_init()

esp_err_t dsps_cplx_gen_init	(	cplx_sig_t *	cplx_gen,
		out_d_type	d_type,
		void *	lut,
		int32_t	lut_len,
		float	freq,
		float	initial_phase )

Initialize strucure for complex generator.

Function initializes a structure for either 16-bit fixed point, or 32-bit floating point complex generator using LUT table. cplx_gen_free(...) must be called, once the generator is not needed anymore to free dynamically allocated memory

A user can specify his own LUT table and pass a pointer to the table (void *lut) during the initialization. If the LUT table pointer passed to the init function is a NULL, the LUT table is initialized internally.

Parameters

cplx_gen	pointer to the floating point generator structure
d_type	output data type - out_d_type enum
lut	pointer to a user-defined LUT, the data type is void so both (S16_FIXED, F32_FLOAT) types could be used
lut_len	length of the LUT
freq	Frequency of the output signal in a range of [-1...1], where 1 is a Nyquist frequency
initial_phase	initial phase of the complex signal in range of [-1..1] where 1 is related to 2Pi and -1 is related to -2Pi

Returns

• ESP_OK on success
• One of the error codes from DSP library

Definition at line 18 of file dsps_cplx_gen_init.c.

{
    cplx_gen->lut_len = lut_len;
    cplx_gen->freq = freq;
    cplx_gen->lut = lut;
    cplx_gen->free_status = 0;
    cplx_gen->d_type = d_type;
    cplx_gen->phase = initial_phase;
 
    // length of the LUT must be power of 2
    if (!dsp_is_power_of_two(lut_len)) {
        ESP_LOGE(TAG, "The length of the LUT must be power of 2");
        return ESP_ERR_DSP_INVALID_LENGTH;
    }
 
    // LUT length must be in a range from 256 to 8192
    if ((lut == NULL) && ((cplx_gen->lut_len > 8192) || (cplx_gen->lut_len < 256))) {
        ESP_LOGE(TAG, "The length of the LUT table out of range. Valid range is 256 to 8192");
        return ESP_ERR_DSP_PARAM_OUTOFRANGE;
    }
 
    // frequency is a Nyquist frequency, must be in a range from (-1 to 1)
    if ((cplx_gen->freq >= 1) || (cplx_gen->freq <= -1)) {
        ESP_LOGE(TAG, "The frequency is out of range. Valid range is +/- 1. ");
        return ESP_ERR_DSP_INVALID_PARAM;
    }
 
    // initial phase in a range from (-1 to 1)
    if ((cplx_gen->phase >= 1) || (cplx_gen->phase <= -1)) {
        ESP_LOGE(TAG, "The phase is out of range. Valid range is +/- 1. ");
        return ESP_ERR_DSP_INVALID_PARAM;
    }
 
    // LUT table coefficients generation
    if (lut == NULL) {                      // lut has not been provided by an user. Allocate and initialize it
        cplx_gen->free_status |= 0x0001;    // lut has been allocated, free_status indicates that the space must be freed afterwards
 
        if (cplx_gen->d_type == S16_FIXED) {                    // Q15 fixed point
            int16_t *local_lut = (int16_t *)malloc(cplx_gen->lut_len * sizeof(int16_t));
 
            float term;
            for (int i = 0 ; i < cplx_gen->lut_len; i++) {
                term = (2.0 * M_PI) * ((float)(i) / (float)(cplx_gen->lut_len));
                local_lut[i] = (int16_t)(sin(term) * Q15_MAX);  // conversion to Q15 fixed point
            }
            cplx_gen->lut = (void *)local_lut;
        } else if (cplx_gen->d_type == F32_FLOAT) {             // Single precision floating point
            float *local_lut = (float *)malloc(cplx_gen->lut_len * sizeof(float));
 
            float term;
            for (int i = 0 ; i < cplx_gen->lut_len; i++) {
                term = (2.0 * M_PI) * ((float)(i) / (float)(cplx_gen->lut_len));
                local_lut[i] = (float)sin(term);
            }
            cplx_gen->lut = (void *)local_lut;
        } else {
            cplx_gen->lut = NULL;
            return ESP_ERR_DSP_INVALID_PARAM;
        }
    }
    return ESP_OK;
}

References cplx_sig_s::d_type, dsp_is_power_of_two(), ESP_ERR_DSP_INVALID_LENGTH, ESP_ERR_DSP_INVALID_PARAM, ESP_ERR_DSP_PARAM_OUTOFRANGE, ESP_OK, F32_FLOAT, cplx_sig_s::free_status, cplx_sig_s::freq, cplx_sig_s::lut, cplx_sig_s::lut_len, M_PI, cplx_sig_s::phase, Q15_MAX, S16_FIXED, and TAG.

Here is the call graph for this function:

dsps_cplx_gen_phase_get()

float dsps_cplx_gen_phase_get

(

cplx_sig_t *

cplx_gen

)

function gets the phase of the complex generator

get function can be used after the cplx_gen structure was initialized by the dsps_cplx_gen_init(...) function

Parameters

cplx_gen

pointer to the complex signal generator structure

Returns

function returns phase of the signal generator

Definition at line 114 of file dsps_cplx_gen_init.c.

{
    // Check if the structure was initialized
    if (!dsp_is_power_of_two(cplx_gen->lut_len)) {
        ESP_LOGE(TAG, "cplx_gen strucure was not initialized");
        return -2;
    }
 
    return (cplx_gen->phase);
}

References dsp_is_power_of_two(), cplx_sig_s::lut_len, cplx_sig_s::phase, and TAG.

Here is the call graph for this function:

dsps_cplx_gen_phase_set()

esp_err_t dsps_cplx_gen_phase_set	(	cplx_sig_t *	cplx_gen,
		float	phase )

function sets the phase of the complex generator

set function can be used after the cplx_gen structure was initialized by the dsps_cplx_gen_init(...) function

Parameters

cplx_gen	pointer to the complex signal generator structure
phase	new phase to be set in the range of [-1..1] where 1 is related to 2Pi and -1 is related to -2Pi

Returns

• ESP_OK on success
• ESP_ERR_DSP_INVALID_PARAM if the phase is out of -1 ... 1 range

Definition at line 103 of file dsps_cplx_gen_init.c.

{
    if ((phase >= 1) || (phase <= -1)) {        // initial phase in a range from (-1 to 1)
        ESP_LOGE(TAG, "The phase is out of range. Valid range is +/- 1. ");
        return ESP_ERR_DSP_INVALID_PARAM;
    }
 
    cplx_gen->phase = phase;
    return ESP_OK;
}

References ESP_ERR_DSP_INVALID_PARAM, ESP_OK, cplx_sig_s::phase, and TAG.

dsps_cplx_gen_set()

esp_err_t dsps_cplx_gen_set	(	cplx_sig_t *	cplx_gen,
		float	freq,
		float	phase )

function sets the output frequency and the phase of the complex generator

set function can be used after the cplx_gen structure was initialized by the dsps_cplx_gen_init(...) function

Parameters

cplx_gen	pointer to the complex signal generator structure
freq	new frequency to be set in the range of [-1..1] where 1 is a Nyquist frequency
phase	new phase to be set in the range of [-1..1] where 1 is related to 2Pi and -1 is related to -2Pi

Returns

• ESP_OK on success
• ESP_ERR_DSP_INVALID_PARAM if the frequency is out of the Nyquist frequency range if the phase is out of -1 ... 1 range

Definition at line 125 of file dsps_cplx_gen_init.c.

{
    if ((freq >= 1) || (freq <= -1)) {          // frequency is a Nyquist frequency, must be in a range from (-1 to 1)
        ESP_LOGE(TAG, "The frequency is out of range. Valid range is +/- 1. ");
        return ESP_ERR_DSP_INVALID_PARAM;
    }
 
    if ((phase >= 1) || (phase <= -1)) {        // phase in a range from (-1 to 1)
        ESP_LOGE(TAG, "The phase is out of range. Valid range is +/- 1. ");
        return ESP_ERR_DSP_INVALID_PARAM;
    }
 
    cplx_gen->phase = phase;
    cplx_gen->freq = freq;
    return ESP_OK;
}

References ESP_ERR_DSP_INVALID_PARAM, ESP_OK, cplx_sig_s::freq, cplx_sig_s::phase, and TAG.