Detailed Description

PRELIMINARY VCE driver interface

WARNING These APIs are PRELIMINARY, and subject to change in the next few months.

Overview

The VCE driver allows you to interact with the Vector Compute Engine (VCE), a linear algebra accellerator peripheral using 64-bit complex numbers. Complex numbers are represented by the float complex type from complex.h, where each number is made up of two 32-bit floats. The VCE works with complex numbers in either Cartesian or Polar formats. In the Cartesian representation, the lower 32 bits are the real part and the upper 32 bits are the imaginary part. In Polar format, the lower 32 bits are the absolute part and the upper 32 bits are the angle, represented as pi radians. As long as arguments to the VCE functions use the same format, the result will also be in that format. Mixing formats produces wrong results. The driver provides basic data types for vectors and matrices constructed from float complex, as well as many common linear algebra operations on these data types.

Data management

All the vector/matrix operations can accept input and output pointers that are inside or outside VCE RAM. If all pointers provided to an operation are inside VCE RAM, the VCE will operate in scratchpad mode . This means the driver will assume that, given the current pointers, the input is already in VCE memory and that input and result will not overlap eachother. Therefore, no data will be copied, and the function output will be placed inside VCE memory. This is the most efficient way to utilize the VCE and is ideal for algorithms with multiple operations that feed into each other, such as MUSIC (https://en.wikipedia.org/wiki/MUSIC_(algorithm)). When chaining together operations, make sure as many as possible use vectors and matrices that are already in VCE memory, to prevent unnecessary copying and overhead.

If any of the pointers are outside VCE memory, the driver will copy input data to the start of its memory, place the result immediately following, and then copy the output back to the provided pointer. This may overwrite data that was already in this location.

The primary purpose of this driver is executing the MUSIC algorithm for distance estimation in Bluetooth Channel Sounding. An implementation of MUSIC using the VCE can be found in the vce_music example.

Usage

This section will cover driver usage.

Synopsis

VCELPF3_init();
float complex *vceMem = (float complex *)VCELPF3_MEM_BASE;
float complex argA[10];
float complex argB[10];
VCELPF3_ComplexVector vecA = {.data = bufA, .size = 10};
VCELPF3_ComplexVector vecB = {.data = bufB, .size = 10};
VCELPF3_ComplexVector resultVec = {.data = vceMem, .size = 10};
// Get control of VCE
VCELPF3_startOperationSequence();
// Perform element-wise product, placing the result in resultVec,
// which is inside VCE memory
VCELPF3_elemProduct(&argA, &argB, resultVec);
// Perform non-conjugated dot product inside of VCE memory, which
// reduces overhead.
VCELPF3_dotProduct(&resultVec, &resultVec, false, vceMem)
// Give up control of VCE
VCELPF3_finishOperationSequence();

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <complex.h>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/devices/DeviceFamily.h>
#include <DeviceFamily_constructPath(inc/hw_memmap.h)>

Include dependency graph for VCELPF3.h:

Go to the source code of this file.

Data Structures
struct	VCELPF3_ComplexVector
	VCELPF3 Vector Struct. More...

struct	VCELPF3_ComplexMatrix
	VCELPF3 Matrix Struct. More...

struct	VCELPF3_ComplexTriangleMatrix
	VCELPF3 Upper Triangle Matrix Struct. More...

struct	VCELPF3_Config
	VCELPF3 Global configuration. More...

struct	VCELPF3_HWAttrs
	VCELPF3 Hardware attributes. More...

Macros
#define	VCELPF3_STATUS_SUCCESS 0
	Successful status code. More...

#define	VCELPF3_STATUS_ERROR 1
	Generic error status code. More...

#define	VCELPF3_STATUS_RESOURCE_UNAVAILABLE 2
	An error status code returned if the hardware or software resource is currently unavailable. More...

#define	VCELPF3_RESULT_INPLACE 0
	VCE operation is in-place, overwriting the input. More...

#define	VCELPF3_MEM_BASE VCERAM_DATA0_BASE
	Start of VCE RAM. More...

#define	VCELPF3_MEM_SIZE_MIRRORED VCERAM_DATA0_SIZE
	Size of VCE RAM in mirrored mode. More...

Enumerations
enum	VCELPF3_OperationMode { VCELPF3_OperationMode_MIRRORED }
	Define the VCE memory operation modes, which are the ways the VCE expects data to be stored in its memory. More...

enum	VCELPF3_SchedulingMode { VCELPF3_SchedulingMode_PIPELINED }
	Define the VCE memory scheduling modes, which are the ways VCE memory operations are scheduled and pipelined. More...

Functions
void	VCELPF3_init (void)
	VCE init function. More...

void	VCELPF3_startOperationSequence ()
	VCE function to prepare the start of an operation chain. More...

void	VCELPF3_stopOperationSequence ()
	VCE function to finish an operation chain. More...

int_fast16_t	VCELPF3_dotProduct (VCELPF3_ComplexVector vecA, VCELPF3_ComplexVector vecB, bool conjugate, float complex *result)
	VCE function for calculating the dot product of two vectors, with the option to perform the complex conjugate on the second vector first. More...

int_fast16_t	VCELPF3_vectorMult (VCELPF3_ComplexVector vecA, VCELPF3_ComplexVector vecB, bool conjugate, VCELPF3_ComplexVector *result)
	VCE function for calculating the element-wise product of two vectors, with the option to perform the complex conjugate on the second vector first. More...

int_fast16_t	VCELPF3_vectorSum (VCELPF3_ComplexVector vecA, VCELPF3_ComplexVector vecB, VCELPF3_ComplexVector *result)
	VCE function for calculating the element-wise sum of two vectors. More...

int_fast16_t	VCELPF3_cartesianToPolarVector (VCELPF3_ComplexVector vec, VCELPF3_ComplexVector result)
	VCE function for converting a complex vector in cartesian format to polar format. More...

int_fast16_t	VCELPF3_polarToCartesianVector (VCELPF3_ComplexVector vec, float complex temp, VCELPF3_ComplexVector *result)
	VCE function for converting a complex vector in polar format to cartesian format. More...

int_fast16_t	VCELPF3_sortVector (VCELPF3_ComplexVector vec, VCELPF3_ComplexVector result)
	VCE function for sorting the real parts of a complex vector in descending order. This function ignores the complex parts of each element and makes no guarantees to their contents after the operation is complete. More...

int_fast16_t	VCELPF3_covMatrixSpatialSmoothing (VCELPF3_ComplexVector vec, uint16_t covMatrixSize, bool fbAveraging, VCELPF3_ComplexTriangleMatrix result)
	VCE function for covariance matrix computation using spatial smoothing and optionally forward-backward averaging. More...

int_fast16_t	VCELPF3_computeFFT (VCELPF3_ComplexVector vec, bool inverse, VCELPF3_ComplexVector result)
	VCE function for computing the Discrete Fourier transform (DFT) of a complex vector using the Fast Fourier Transform (FFT) algorithm. Optionally, the Inverse DFT can be computed. Combines two VCE operations; first configuring the VCE for a fourier transform, then actually computing it. More...

int_fast16_t	VCELPF3_matrixMult (VCELPF3_ComplexMatrix matA, VCELPF3_ComplexMatrix matB, VCELPF3_ComplexMatrix *result)
	VCE function for multiplying two matrices. The number of rows in the first matrix must be equal to the number of columns in the second matrix. More...

int_fast16_t	VCELPF3_matrixSum (VCELPF3_ComplexMatrix matA, VCELPF3_ComplexMatrix matB, VCELPF3_ComplexMatrix *result)
	VCE function for adding two matrices. The matrices must be of exact same sizes. More...

int_fast16_t	VCELPF3_matrixScalarSum (VCELPF3_ComplexMatrix mat, float complex scalar, VCELPF3_ComplexMatrix *result)
	VCE function for adding a scalar to a each of a matrix' elements. More...

int_fast16_t	VCELPF3_matrixScalarMult (VCELPF3_ComplexMatrix mat, float complex scalar, VCELPF3_ComplexMatrix *result)
	VCE function for multiplying each of a matrix' elements by a scalar. More...

int_fast16_t	VCELPF3_matrixNorm (VCELPF3_ComplexMatrix mat, float complex result)
	Compute the Frobenius norm of a matrix. More...

int_fast16_t	VCELPF3_jacobiEVD (VCELPF3_ComplexTriangleMatrix mat, uint16_t maxIter, float stopThreshold, VCELPF3_ComplexVector result)
	VCE function to compute the Jacobi Eigen-Decomposition (EVD) of a triangular Hermitian Matrix. This results in a triangular, diagonal matrix of eigenvalues sorted in descending order replacing the original matrix, and a full matrix, where the eigenvectors are the columns. The eigenvector matrix can be placed anywhere in VCE memory except for where the input matrix is placed. When not using scratchpad mode, the eigenvector matrix will be placed next to the eigenvector matrix. More...

int_fast16_t	VCELPF3_gaussJordanElim (VCELPF3_ComplexMatrix mat, float zeroThreshold, VCELPF3_ComplexMatrix result)
	Reduce the input matrix A[MxN] to reduced echelon form using Gauss-Jordan Elimination. More...

int_fast16_t	VCELPF3_unitCircle (uint16_t numPoints, uint16_t constant, uint16_t phase, bool conjugate, VCELPF3_ComplexVector *result)
	Generate points evenly distributed on a unit circle VCE generates a unit circle as follow: exp(-j2pi(kM+phase)/1024 * (-1)^(conjugate)) More...

void	VCELPF3_prepareResult (uint16_t resultSize, uint16_t inputSize, complex float *resultBuffer)
	Configure the VCE pointers for temporary (in VCE memory) and final results for a VCE operation. This function is intended to be used inside VCE operations, such as dot product. More...

uint16_t	VCELPF3_prepareVectors (VCELPF3_ComplexVector vecA, VCELPF3_ComplexVector vecB)
	Configure the VCE for vector operation inputs. If not in scratchpad mode, the vectors are loaded one after the other into the start of VCE memory. More...

uint16_t	VCELPF3_prepareMatrices (VCELPF3_ComplexMatrix matA, VCELPF3_ComplexMatrix matB)
	Configure the VCE for matrix operation inputs. If not in scratchpad mode, the matrices are loaded one after the other into the start of VCE memory. More...

void *	VCELPF3_loadTriangular (VCELPF3_ComplexMatrix *mat, uint16_t offset)
	Loads the upper triangular part of a full matrix into VCE memory. More...

void *	VCELPF3_loadArgMirrored (uint16_t argSize, uint16_t offset, float complex *src)
	Load operation arguments into VCE memory, assuming the VCE is in mirrored mode. This means memory is viewed as one block that can fit 1024 complex numbers. More...

Macro Definition Documentation

§ VCELPF3_RESULT_INPLACE

#define VCELPF3_RESULT_INPLACE 0

VCE operation is in-place, overwriting the input.

§ VCELPF3_MEM_BASE

#define VCELPF3_MEM_BASE VCERAM_DATA0_BASE

Start of VCE RAM.

§ VCELPF3_MEM_SIZE_MIRRORED

#define VCELPF3_MEM_SIZE_MIRRORED VCERAM_DATA0_SIZE

Size of VCE RAM in mirrored mode.

Enumeration Type Documentation

§ VCELPF3_OperationMode

enum VCELPF3_OperationMode

Define the VCE memory operation modes, which are the ways the VCE expects data to be stored in its memory.

Enumerator
VCELPF3_OperationMode_MIRRORED	In mirrored mode elements are stored sequantially in VCE memory.

§ VCELPF3_SchedulingMode

enum VCELPF3_SchedulingMode

Define the VCE memory scheduling modes, which are the ways VCE memory operations are scheduled and pipelined.

Enumerator
VCELPF3_SchedulingMode_PIPELINED	In pipelined mode, read operations proceed per clock cycle, and only the incoming samples will regulate the data flow.

Function Documentation

§ VCELPF3_init()

void VCELPF3_init ( void )

VCE init function.

This function initializes the VCE internal state. It sets power dependencies, loads the necessary firmware, configures the VCE and sets up interrupts and semaphores

§ VCELPF3_startOperationSequence()

void VCELPF3_startOperationSequence ( )

VCE function to prepare the start of an operation chain.

This function disables standby and acquire exclusive access to the VCE. It should be called before any sequence of VCE operations, wrapping them together with VCELPF3_stopOperationSequence(). VCE operations should not be called outside of a pair of VCELPF3_startOperationSequence() and VCELPF3_stopOperationSequence() functions.

Precondition: VCELPF3_init() has been called.

§ VCELPF3_stopOperationSequence()

void VCELPF3_stopOperationSequence ( )

VCE function to finish an operation chain.

This function enables standby and releases exclusive access to the VCE. It should be called after any sequence of VCE operations, wrapping them together with VCELPF3_startOperationSequence(). VCE operations should not be called outside of a pair of VCELPF3_startOperationSequence() and VCELPF3_stopOperationSequence() functions.

Precondition: VCELPF3_init() and VCELPF3_startOperationSequence() has been called.

§ VCELPF3_prepareResult()

void VCELPF3_prepareResult	(	uint16_t	resultSize,
		uint16_t	inputSize,
		complex float *	resultBuffer
	)

Configure the VCE pointers for temporary (in VCE memory) and final results for a VCE operation. This function is intended to be used inside VCE operations, such as dot product.

Parameters

[in]	resultSize	the size of an operation result
[in]	inputSize	the size of an operation input
[out]	resultBuffer	a pointer where the operation result will be placed in VCE memory. If not using scratchpad mode, usually when an external buffer is supplied, configure to place the result at the start of VCE memory, before copying it to the buffer.

Returns: A status code indicating whether the VCE operation was a success.

Return values

VCELPF3_STATUS_SUCCESS The call was successful.

§ VCELPF3_prepareVectors()

uint16_t VCELPF3_prepareVectors	(	VCELPF3_ComplexVector *	vecA,
		VCELPF3_ComplexVector *	vecB
	)

Configure the VCE for vector operation inputs. If not in scratchpad mode, the vectors are loaded one after the other into the start of VCE memory.

Parameters

[in]	vecA	an input vector
[in]	vecB	an input vector, potentially the same as `vecA`

Returns: The total input size. If the input vectors are the same, this is the vector's size, otherwise it is the sum of the vector sizes.

§ VCELPF3_prepareMatrices()

uint16_t VCELPF3_prepareMatrices	(	VCELPF3_ComplexMatrix *	matA,
		VCELPF3_ComplexMatrix *	matB
	)

Configure the VCE for matrix operation inputs. If not in scratchpad mode, the matrices are loaded one after the other into the start of VCE memory.

Parameters

[in]	matA	a pointer to an input matrix
[in]	matB	a pointer to an input matrix, potentially the same as `matA`

Returns: The total input size. If the input matrices are the same, this is the matrix's size, otherwise it is the sum of the vector sizes.

§ VCELPF3_loadTriangular()

void* VCELPF3_loadTriangular	(	VCELPF3_ComplexMatrix *	mat,
		uint16_t	offset
	)

Loads the upper triangular part of a full matrix into VCE memory.

Parameters

[in]	mat	a pointer to a source matrix
[in]	offset	offset into VCE memory to load to

Returns: Pointer in VCE memory where the argument is stored.

§ VCELPF3_loadArgMirrored()

void* VCELPF3_loadArgMirrored	(	uint16_t	argSize,
		uint16_t	offset,
		float complex *	src
	)

Load operation arguments into VCE memory, assuming the VCE is in mirrored mode. This means memory is viewed as one block that can fit 1024 complex numbers.

Parameters

[in]	argSize	how many complex numbers to load
[in]	offset	offset into VCE memory to load to
[in]	src	data source pointer

Returns: Pointer in VCE memory where the argument is stored.

Detailed Description

Overview

Data management

Usage

Synopsis

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

§ VCELPF3_RESULT_INPLACE

§ VCELPF3_MEM_BASE

§ VCELPF3_MEM_SIZE_MIRRORED

Enumeration Type Documentation

§ VCELPF3_OperationMode

§ VCELPF3_SchedulingMode

Function Documentation

§ VCELPF3_init()

§ VCELPF3_startOperationSequence()

§ VCELPF3_stopOperationSequence()

§ VCELPF3_prepareResult()

§ VCELPF3_prepareVectors()

§ VCELPF3_prepareMatrices()

§ VCELPF3_loadTriangular()

§ VCELPF3_loadArgMirrored()