MSP DSP Library
|
Many of the DSPLib functions support the Low Energy Accelerator (LEA) peripheral available on MSP430 FRAM devices. LEA is a digital accelerator that enables best in class ultra-low power signal processing and embedded math calculations for common operation such as multiply and accumulate (MAC), filtering (FIR and IIR) and transforms (FFT). See the LEA Supported API's section below for the complete list of API's that support LEA.
The majority of the LEA peripheral usage is abstracted as part of the software library but there are a few key considerations for using LEA with the functions in DSPLib. Data must be placed into shared memory and aligned to certain address boundaries (typically functions require 4-byte alignment but FIR and FFT functions might require more strict alignment). The library includes preprocessor macros to allocate and align data structures in shared LEA memory, an example of how to use them is shown below.
For a more detailed look at using the library with LEA please refer to the code examples.
Data and coefficient arrays must reside in a shared RAM section that both the CPU and LEA can access. These data sections are listed below for CCS and IAR but the DSPLIB_DATA macro can be used to easily place data into the shared LEA memory.
Data placed into the shared LEA RAM section must be aligned to at least a 32-bit boundary (4-byte alignment) however some functions may require stricter alignment such as the transform (FFT) and filter (FIR) functions. Each API lists the required alignment in the "LEA Support" section of the API documentation. By default alignment is checked before invoking LEA commands, if criteria are not met the function will return MSP_LEA_INVALID_ADDRESS.
Functions using LEA will enter LPM0 with interrupts enabled while LEA is running to achieve the lowest possible energy. The LEA interrupt routine is provided by DSPLib and will wake the device upon completion of the command. The application is free to leave other interrupts enabled and service them as needed, exiting from the interrupt back into LPM0.
Some revisions of silicon are effected by the LEA1 errata where asynchronous interrupts from other peripherals can interrupt the timing of LEA. DSPLib works around this errata for effected revisions by staying in active mode and polling LEA registers. While not as low energy as using LPM0 the routine has been optimized to take advantage of the FRAM cache and uses significantly lower energy than typical active mode.
In order to ensure the functionality of LEA and that the latest firmware and workarounds are applied DSPLib checks the revision of LEA code ROM when diagnostic checks are enabled. The revision must be predefined in the compiler options or equal to the default revision defined in DSPLIb_lea.h. Functions that require a patch will load and execute the latest revision of the command. If the revision read from the LEA ROM is not equal to the defined revision the function will return a MSP_LEA_INCORRECT_REVISION status indicating that the revision is incorrect. The msp_lea_getRevision function can be used to check the LEA revision and is demonstrated in the example below.
Function | Description | LEA Support | Data Alignment (bytes) |
---|---|---|---|
msp_add_q15 | Addition of two real source vectors | yes | 4 |
msp_add_iq31 | Addition of two real source vectors | yes | 4 |
msp_sub_q15 | Subtraction of two real source vectors | yes | 4 |
msp_sub_iq31 | Subtraction of two real source vectors | yes | 4 |
msp_mpy_q15 | Multiplication of two real source vectors | yes | 4 |
msp_mpy_iq31 | Multiplication of two real source vectors | yes | 4 |
msp_mac_q15 | Multiply and accumulate of real source vectors | yes | 4 |
msp_mac_iq31 | Multiply and accumulate of real source vectors | yes | 4 |
msp_neg_q15 | Negation of a source vector | yes | 4 |
msp_neg_iq31 | Negation of a source vector | yes | 4 |
msp_abs_q15 | Absolute value of a real source vector | no | 4 |
msp_abs_iq31 | Absolute value of a real source vector | no | 4 |
msp_offset_q15 | Constant offset of a real source vector | yes | 4 |
msp_offset_iq31 | Constant offset of a real source vector | yes | 4 |
msp_scale_q15 | Scale a real source vector | no | 4 |
msp_scale_iq31 | Scale a real source vector | no | 4 |
msp_shift_q15 | Bitwise shift of a real source vector | yes | 4 |
msp_shift_iq31 | Bitwise shift of a real source vector | yes | 4 |
msp_max_q15 | Signed maximum of a source vector | yes | 4 |
msp_max_iq31 | Signed maximum of a source vector | yes | 4 |
msp_max_uq15 | Unsigned maximum of a source vector | yes | 4 |
msp_max_uq31 | Unsigned maximum of a source vector | yes | 4 |
msp_min_q15 | Signed minimum of a source vector | yes | 4 |
msp_min_iq31 | Signed minimum of a source vector | yes | 4 |
msp_min_uq15 | Unsigned minimum of a source vector | yes | 4 |
msp_min_uq31 | Unsigned minimum of a source vector | yes | 4 |
msp_cmplx_add_q15 | Addition of two complex source vectors | yes | 4 |
msp_cmplx_add_iq31 | Addition of two complex source vectors | yes | 4 |
msp_cmplx_sub_q15 | Subtraction of two complex source vectors | yes | 4 |
msp_cmplx_sub_iq31 | Subtraction of two complex source vectors | yes | 4 |
msp_cmplx_mpy_q15 | Multiplication of two complex source vectors | yes | 4 |
msp_cmplx_mpy_iq31 | Multiplication of complex source vectors | no | 4 |
msp_cmplx_mpy_real_q15 | Multiplication of complex source vector by real source vector | no | 4 |
msp_cmplx_mpy_real_iq31 | Multiplication of complex source vector by real source vector | yes | 4 |
msp_cmplx_mac_q15 | Multiply and accumulate of complex source vectors | yes | 4 |
msp_cmplx_mac_iq31 | Multiply and accumulate of complex source vectors | no | 4 |
msp_cmplx_conj_q15 | Conjugation of a source vector | no | 4 |
msp_cmplx_conj_iq31 | Conjugation of a source vector | yes | 4 |
msp_cmplx_scale_q15 | Scale a complex source vector | no | 4 |
msp_cmplx_scale_iq31 | Scale a complex source vector | no | 4 |
msp_cmplx_shift_q15 | Bitwise shift of a complex source vector | yes | 4 |
msp_cmplx_shift_iq31 | Bitwise shift of a complex source vector | yes | 4 |
msp_matrix_add_q15 | Addition of two real source matrices | yes | 4 |
msp_matrix_add_iq31 | Addition of two real source matrices | yes | 4 |
msp_matrix_sub_q15 | Subtraction of two real source matrices | yes | 4 |
msp_matrix_sub_iq31 | Subtraction of two real source matrices | yes | 4 |
msp_matrix_mpy_q15 | Multiplication of two real source matrices | yes | 4 |
msp_matrix_mpy_iq31 | Multiplication of two real source matrices | yes | 4 |
msp_matrix_trans_q15 | Transposition of a source matrix | yes | 4 |
msp_matrix_trans_iq31 | Transposition of a source matrix | yes | 4 |
msp_matrix_neg_q15 | Negation of a source matrix | yes | 4 |
msp_matrix_neg_iq31 | Negation of a source matrix | yes | 4 |
msp_matrix_abs_q15 | Absolute value of a real source matrix | no | 4 |
msp_matrix_abs_iq31 | Absolute value of a real source matrix | no | 4 |
msp_matrix_offset_q15 | Constant offset of a real source matrix | yes | 4 |
msp_matrix_offset_iq31 | Constant offset of a real source matrix | yes | 4 |
msp_matrix_scale_q15 | Scale a real source matrix | no | 4 |
msp_matrix_scale_iq31 | Scale a real source matrix | no | 4 |
msp_matrix_shift_q15 | Bitwise shift of a real source matrix | yes | 4 |
msp_matrix_shift_iq31 | Bitwise shift of a real source matrix | yes | 4 |
msp_fir_q15 | Discrete-time convolution of a source vector with real coefficients to apply an FIR filter | yes | 4 (enableCircularBuffer = false) 4*length (enableCircularBuffer = true) |
msp_fir_iq31 | Discrete-time convolution of a source vector with real coefficients to apply an FIR filter | yes | 4 (enableCircularBuffer = false) 8*length (enableCircularBuffer = true) |
msp_cmplx_fir_q15 | Discrete-time convolution of a complex source vector with complex coefficients to apply an FIR filter | yes | 4 (enableCircularBuffer = false) 8*length (enableCircularBuffer = true) |
msp_cmplx_fir_iq31 | Discrete-time convolution of a complex source vector with complex coefficients to apply an FIR filter | yes | 4 (enableCircularBuffer = false) 16*length (enableCircularBuffer = true) |
msp_biquad_df1_q15 | Second-order direct form 1 biquad filter | yes | 4 |
msp_biquad_df2_q15 | Second-order direct form 2 biquad filter | yes | 4 |
msp_biquad_df2_ext_q15 | Second-order direct form 2 biquad filter extended with DC bias and minimum and maximum tracking | yes | 4 |
msp_biquad_cascade_df1_q15 | Cascaded direct form 1 biquad filter | yes | 4 |
msp_biquad_cascade_df2_q15 | Cascaded direct form 2 biquad filter | yes | 4 |
msp_biquad_cascade_df2_ext_q15 | Cascaded direct form 2 biquad filter extended with DC bias and minimum and maximum tracking | yes | 4 |
msp_fft_auto_q15 | Real forward FFT function with auto-scaling | yes | 2*length |
msp_fft_fixed_q15 | Real forward FFT function with fixed scaling by two at each stage | yes | 2*length |
msp_fft_iq31 | Real forward FFT function without scaling | yes | 4*length |
msp_ifft_auto_q15 | Real result inverse FFT function with auto-scaling | yes | 2*length |
msp_ifft_fixed_q15 | Real result inverse FFT function with fixed scaling by two at each stage | yes | 2*length |
msp_ifft_iq31 | Real result inverse FFT function without scaling | yes | 4*length |
msp_cmplx_fft_auto_q15 | Complex forward FFT function with auto-scaling | yes | 4*length |
msp_cmplx_fft_fixed_q15 | Complex forward FFT function with fixed scaling by two at each stage | yes | 4*length |
msp_cmplx_fft_iq31 | Complex forward FFT function without scaling | yes | 8*length |
msp_cmplx_ifft_auto_q15 | Complex inverse FFT function with auto-scaling | yes | 4*length |
msp_cmplx_ifft_fixed_q15 | Complex inverse FFT function with fixed scaling by two at each stage | yes | 4*length |
msp_cmplx_ifft_iq31 | Complex inverse FFT function without scaling | yes | 8*length |
msp_copy_q15 | Real Q15 vector copy | yes | 4 |
msp_copy_iq31 | Real IQ31 vector copy | yes | 4 |
msp_fill_q15 | Real Q15 vector fill with constant | yes | 4 |
msp_fill_iq31 | Real IQ31 vector fill with constant | yes | 4 |
msp_cmplx_q15 | Create Q15 complex vector from real and imaginary vectors. | yes | 4 |
msp_cmplx_iq31 | Create IQ31 complex vector from real and imaginary vectors. | yes | 4 |
msp_q15_to_iq31 | Convert Q15 vector to IQ31 format. | yes | 4 |
msp_iq31_to_q15 | Convert IQ31 vector to Q15 format. | yes | 4 |
msp_cmplx_fill_q15 | Complex Q15 vector fill with constant | yes | 4 |
msp_cmplx_fill_iq31 | Complex IQ31 vector fill with constant | yes | 4 |
msp_deinterleave_q15 | Extract a single channel from multiple-channel source | yes | 4 |
msp_deinterleave_iq31 | Extract a single channel from multiple-channel source | yes | 4 |
msp_interleave_q15 | Insert a single channel into a multiple-channel destination. | yes | 4 |
msp_interleave_q15 | Insert a single channel into a multiple-channel destination. | yes | 4 |
msp_sinusoid_q15 | Generate a sinusoid with specified amplitude and frequency. | yes | 4 |