signal-lib

Описание

Библиотека elcore50-signal-lib предназначена для выполнения операций цифровой обработки сигналов. На данный момент возможны вычисление одномерных и двумерных прямых и обратных быстрых преобразований Фурье (БПФ), одномерной и двумерной БПФ-свертки, проектирование КИХ-фильтров методом оконного взвешивания и фильтрация сигнала на DSP ELcore-50.

Библиотека позволяет вычислять БПФ для сигналов размером от 256 до 256к комплексных отсчётов, являющимся степенью 2, в формате данных float32, float16 и fractional16 (тип с фиксированной точкой). Число S типа fractional16 — 16-разрядное дробное число со знаком в дополнительном коде вида \(S = -S_{15} * 2^0 + S_{14} * 2^{-1} + S_{13} * 2^{-2} + ... + S_0 * 2^{-15}\).

В библиотеке используется алгоритм вычисления линейной свертки через БПФ. Известно, что дискретное преобразование Фурье (ДПФ) циклической свертки равно произведению спектров сворачиваемых сигналов. Для приведения циклической свертки к линейной необходимо дополнить сигналы нулями до длины N + M - 1, где N — количество отсчетов первого сигнала, M — количество отсчетов второго сигнала.

Вычисление БПФ-свертки в библиотеке elcore50-signal-lib возможно только для массивов, длина которых является степенью двойки. В противном случае каждый из массивов необходимо дополнить нулями до размера ближайшей степени двойки. Максимальный размер БПФ-свертки — 256к комплексных отсчетов.

Для фильтрации сигналов используется БПФ-свертка, описанная выше.

Комплексные числа в массивах записываются последовательно, сначала идет мнимая часть, затем — действительная.

Использование API

Вычисление БПФ происходит в три этапа. Сначала необходимо создать объект типа fft_t, в нем задать параметры преобразования: размер сигнала, тип преобразования, указатели на входной и выходной массивы и т.д. Далее вызвать функцию fft_plan_1d() или fft_plan_2d(), где на основе этих данных вычисляются поворачивающие коэффициенты *w_cols, *w_rows, *t. Третий этап — непосредственно вычисление БПФ, которое осуществляет функция fft_execute().

Вычисление БПФ-свертки производится функциями fft_conv_1d() и fft_conv_2d().

Проектирование КИХ-фильтров осуществляется функцией fir_window(). Отфильтровать сигнал можно с использованием функции lfilter().

Более детальная информация представлена в главе API. Также в составе библиотеки распространяются тесты и примеры использования, см. главу Примеры использования.

API

Состоит из следующих заголовочных файлов:

  • elcore50-signal-lib/fft.h — структуры данных и функции библиотеки.

  • elcore50-signal-lib/types_converter.h — функции для преобразования массивов в различные типы данных.

  • elcore50-signal-lib/reference.h — референсные функции.

Структуры данных

sl_dimensions

enum sl_dimensions
enumerator SL_1D = 1
enumerator SL_2D = 2

Перечисление доступных размерностей.

sl_data_types

enum sl_data_types
enumerator SL_FLOAT = 1
enumerator SL_FRACTIONAL = 2
enumerator SL_HFLOAT = 3

Перечисление доступных типов данных: SL_FLOAT соответствует float32, SL_FRACTIONAL — fractional16, SL_HFLOAT — float16.

sl_data_memory

enum sl_data_memory
enumerator SL_DDR = 0
enumerator SL_XYRAM = 1

Перечисление типов вычислений: SL_DDR — над данными во внешней памяти, SL_XYRAM — во внутренней памяти DSP (XYRAM).

sl_transform_type

enum sl_transform_type
enumerator SL_IFFT = 0
enumerator SL_FFT = 1

Перечисление типов преобразований: SL_IFFT — обратное БПФ, SL_FFT — прямое БПФ.

fft_t

struct fft_t
sl_dimensions dim
int size
int height
int length
void *w_cols
void *w_rows
void *t
void *src
void *dst
sl_transform_type dir
int big_size
sl_data_types fft_type
int element_size
sl_data_memory int_mem
int ticks
int instrs

Описание полей структуры fft_t:

  • dim — размерность пространства. Определяется через sl_dimensions.

  • size — количество комплексных отсчетов для одномерного преобразования.

  • height — количество строк матрицы для двумерного преобразования.

  • length — количество столбцов матрицы для двумерного преобразования.

    Предупреждение

    Значение height должно быть в диапазоне от 16 до 512, length — в диапазоне от 16 до 512 комплексных отсчетов.

    Примечание

    Поле size доступно только для чтения при двумерном преобразовании, а поля height и length — при одномерном.

  • *w_cols, *w_rows, *t — вектор поворотов столбцов, вектор поворотов строк, вектор поворотов промежуточного этапа соответственно. Данные поля всегда доступны только для чтения.

  • *src, *dst — вектор входного сигнала и результата преобразования соответственно.

    Предупреждение

    При вычислениях во внешней памяти адреса должны быть выровнены на размер массива в байтах.

  • dir — флаг типа преобразования. Определяется через sl_transform_type.

    Предупреждение

    При вычислении обратного преобразования для типа float32 нормировка результата не происходит.

  • big_size — флаг преобразования большого размера: устанавливается равным 1 при размерах входного сигнала > 16к комплексных отсчетов для типа float32, > 32K — для типов fractional16 и float16. Доступно для чтения.

  • fft_type — тип данных преобразования. Определяется через sl_data_types.

  • element_size — размер типа используемых данных в байтах. Доступно только для чтения.

  • int_mem — тип вычислений. Определяется через sl_data_memory.

  • ticks — количество тактов DSP, затраченное на выполнение преобразования. Доступно для чтения.

  • instrs — количество инструкций, выполненное при вычислении преобразования. Доступно для чтения.

Предупреждение

При вычислении одномерного преобразования, когда big_size = 0 или int_mem = 0, результат преобразования будет находиться в массиве dst. В противном случае результат сохранится в массиве src, а массив dst будет использоваться как вспомогательный.

При вычислении двумерного преобразования результат будет помещен в массив src, dst — вспомогательный.

Предупреждение

При вычислении двумерного преобразования, когда big_size = 1 и int_mem = 1, результат преобразования будет транспонирован.

sl_fir_window_type

enum sl_fir_window_type
enumerator HAMMING
enumerator NUTTALL
enumerator BLACKMAN
enumerator BLACKMAN_HARRIS
enumerator BLACKMAN_NUTTALL
enumerator HANN
enumerator LANCZOS
enumerator BARTLETT
enumerator CHEBWIN

Перечисление типов поддерживаемых окон.

sl_filter_type

enum sl_filter_type
enumerator LOWPASS
enumerator HIGHPASS
enumerator BANDPASS
enumerator BANDSTOP

Перечисление типов фильтров.

Функции

Вычисление БПФ

Описанные ниже функции определены в заголовочном файле elcore50-signal-lib/fft.h.

fft_plan_1d()
int fft_plan_1d(fft_t *fft_obj, int size, sl_data_types fft_type)

Описание аргументов функции fft_plan_1d():

  • fft_obj — структура с параметрами преобразования.

  • size — размер преобразования.

  • fft_type — тип данных преобразования, соответствующий sl_data_types.

Функция fft_plan_1d() заполняет структуру fft_obj и вычисляет соответствующие матрицы поворотов для одномерного БПФ (ОБПФ).

Функция вернет код статуса, содержание которого можно посмотреть, использовав функцию print_error_message().

fft_plan_2d()
int fft_plan_2d(fft_t *fft_obj, const int height, const int length, sl_data_types fft_type)

Описание аргументов функции fft_plan_2d():

  • fft_obj — структура с параметрами преобразования.

  • height — количество строк матрицы.

  • length — количество столбцов матрицы.

  • fft_type — тип данных преобразования, соответствующий sl_data_types.

Функция fft_plan_2d() заполняет структуру fft_obj и вычисляет соответствующие матрицы поворотов для двумерного БПФ (ОБПФ).

Функция вернет код статуса.

fft_execute()
int fft_execute(fft_t *fft_obj)

Описание аргументов функции fft_execute():

  • fft_obj — структура с параметрами преобразования.

Функция fft_execute() выполняет вычисление БПФ (ОБПФ). Если параметр int_mem в структуре fft_obj соответствует SL_XYRAM, то данные будут загружены во внутреннюю память DSP.

Функция вернет код статуса.

fft_free_sources()
void fft_free_sources(fft_t *fft_obj)

Описание аргументов функции fft_free_sources():

  • fft_obj — структура с параметрами преобразования.

Функция fft_free_sources() освобождает память, выделенную для выполнения преобразований.

Вычисление свертки

fft_conv_1d()
int fft_conv_1d(float *src0, float *src1, float *dst, const int32_t size, const sl_data_memory is_data_in_xyram)

Описание аргументов функции fft_conv_1d():

  • src0 — первый входной массив.

  • src1 — второй входной массив.

  • dst — выходной массив.

  • size — количество комплексных элементов.

  • is_data_in_xyram — расположение входных данных.

Функция fft_conv_1d() вычисляет одномерную БПФ-свертку двух массивов типа float. Размер свертки size необходимо рассчитать по формуле

size = 1 << ceil(log2(size0 + size1 - 1)),

где size0 — размер первого массива, size1 — размер второго массива.

Функция вернет код статуса.

fft_conv_2d()
int fft_conv_2d(float *src0, float *src1, float *dst, const int32_t rows, const int32_t cols, const sl_data_memory is_data_in_xyram)

Описание аргументов функции fft_conv_2d():

  • src0 — первый входной массив.

  • src1 — второй входной массив.

  • dst — выходной массив.

  • rows — количество элементов в столбце результирующей матрицы.

  • cols — количество комплексных элементов в строке результирующей матрицы.

  • is_data_in_xyram — расположение входных данных.

Функция fft_conv_2d() вычисляет одномерную БПФ-свертку двух массивов типа float. Количество строк rows необходимо рассчитать по формуле

rows = 1 << ceil(log2(rows0 + rows1 - 1)),

где rows0 — количество строк первого массива, rows1 — количество строк второго массива. Количество столбцов рассчитывается аналогично.

Функция вернет код статуса.

Проектирование фильтров и фильтрация

get_window()
int get_window(float *w, const int32_t n, const sl_fir_window_type win_type, const int8_t is_symmetric, float param)

Описание аргументов функции get_window():

  • w — массив с вычисленной оконной функцией.

  • n — размер оконной функции в комплексных элементах.

  • win_type — тип оконной функции.

  • is_symmetric — симметричное или периодическое окно.

  • param — параметр для параметрического окна.

Функция get_window() рассчитывает симметричную или периодическую оконную функцию. Параметр is_symmetric равен 1, если требуемая оконная функция — симметричная, в противном случае — 0. Параметр для параметрического окна игнорируется для непараметрических окон.

Функция вернет код статуса.

fir_lpf()
int fir_lpf(float *h, const int32_t ord, const float wp, const sl_fir_window_type win_type, const int8_t is_symmetric, float param)

Описание аргументов функции fir_lpf():

  • h — массив с вычисленными коэффициентами.

  • ord — порядок фильтра в комплексных элементах.

  • wp — частота среза.

  • win_type — тип оконной функции.

  • is_symmetric — симметричное или периодическое окно.

  • param — параметр для параметрического окна.

Функция fir_lpf() рассчитывает фильтр нижних частот с частотой среза wp. Параметр is_symmetric равен 1, если требуемая оконная функция — симметричная, в противном случае — 0. Параметр для параметрического окна игнорируется для непараметрических окон.

Функция вернет код статуса.

fir_window()
int fir_window(float *h, const int32_t ord, const float w0, const float w1, const sl_filter_type filter_type, const sl_fir_window_type win_type, const sl_data_memory is_symmetric, float param)

Описание аргументов функции fir_window():

  • h — массив с вычисленными коэффициентами.

  • ord — порядок фильтра в комплексных элементах.

  • w0 — частота среза ФНЧ или левая частота среза для полосового и режекторного фильтров.

  • w1 — частота среза ФВЧ или правая частота среза для полосового и режекторного фильтров.

  • filter_type — тип фильтра.

  • win_type — тип оконной функции.

  • is_symmetric — симметричное или периодическое окно.

  • param — параметр для параметрического окна.

Функция fir_window() вычисляет коэффициенты КИХ-фильтра методом оконного взвешивания. Параметр is_symmetric равен 1, если требуемая оконная функция — симметричная, в противном случае — 0. Параметр для параметрического окна игнорируется для непараметрических окон.

Функция вернет код статуса.

lfilter()
int lfilter(float *b, float *a, const int16_t ord, float *x, const int16_t n, float *y, const sl_data_memory is_data_in_xyram)

Описание аргументов функции lfilter():

  • b — коэффициенты числителя передаточной характеристики фильтра.

  • a — коэффициенты знаменателя передаточной характеристики фильтра.

  • ord — порядок фильтра.

  • x — входной сигнал для фильтрации.

  • n — размер входного сигнала в комплексных элементах.

  • y — отфильтрованный сигнал.

  • is_data_in_xyram — расположение входных данных.

Функция lfilter() фильтрует полученный сигнал с использованием КИХ-фильтра при a равном NULL.

Функция вернет код статуса.

Преобразование типов данных

Описанные ниже функции определены в заголовочном файле elcore50-signal-lib/types_converter.h.

float16_to_float32()
extern void float16_to_float32(int16 *src, float *dst, int size)

Описание аргументов функции float16_to_float32():

  • src — входной массив.

  • dst — выходной массив.

  • size — размер массива в элементах.

Функция float16_to_float32() преобразовывает входной массив типа float16 в массив типа float32.

float32_to_float16()
extern void float32_to_float16(float *src, int16 *dst, int size)

Описание аргументов функции float32_to_float16():

  • src — входной массив.

  • dst — выходной массив.

  • size — размер массива в элементах.

Функция float32_to_float16() преобразовывает входной массив типа float32 в массив типа float16.

float32_to_fract16()
void float32_to_fract16(float *src, int16 *dst, const int size)

Описание аргументов функции float32_to_fract16():

  • src — входной массив.

  • dst — выходной массив.

  • size — количество комплексных чисел во входном массиве.

Функция float32_to_fract16() преобразовывает входной массив типа float32 в массив типа fractional16.

fract16_to_float32()
void fract16_to_float32(int16 *src, float *dst, const int size)

Описание аргументов функции fract16_to_float32():

  • src — входной массив.

  • dst — выходной массив.

  • size — количество комплексных чисел во входном массиве.

Функция fract16_to_float32() преобразовывает входной массив типа fractional16 в массив типа float32.