DSP Built-in Routines

mikroC PRO for dsPIC30/33 and PIC24 includes a collection of DSP Built-in Routines. This section describes the programmer interface to DSP instructions.

Bare in mind that most optimal DSP code can only be achieved by direct asm coding. We strongly discourage usage of these built-in routines for performance critical applications.
For the sake of compatibility each of these functions can be called by its alias formed by replacing 'DSP' name part with '__builtin'.

However, these aliases will not be visible in code assistant.

Note : Valid values for accumulator operands and results are predefined accumulator constants 'A' and 'B'.

Library Routines

DSP_ADDAB
DSP_ADD
DSP_CLR
DSP_CLR_prefetch
DSP_ED
DSP_EDAC
DSP_LAC
DSP_MAC
DSP_MOVSAC
DSP_MPY
DSP_MPYN
DSP_MSC
DSP_SAC
DSP_SACR
DSP_SFTAC
DSP_SUBAB

DSP_ADDAB

Prototype	int DSP_ADDAB(const int acc_a, const int acc_b);
Description	Add accumulators `A` and `B` with the result written back to the specified accumulator. Assembler Operator / Machine Instruction : `add`.
Parameters	`acc_a:` First accumulator to add. `acc_b:` Second accumulator to add. Both arguments can be ommited.
Returns	Returns the addition result to an accumulator.
Requires	Nothing.
Example	A = DSP_ADDAB();
Notes	An error message will be displayed if the result is not an accumulator register.

DSP_ADD

Prototype	int DSP_ADD(const int acc, int value, const int shift);
Description	Add value to the accumulator specified by result with a shift specified by literal shift. Assembler Operator / Machine Instruction : `add`.
Parameters	`acc:` Accumulator to add. `value:` Integer number to add to accumulator value. `shift:` Amount to shift resultant accumulator value.
Returns	Returns the shifted addition result to an accumulator.
Requires	Nothing.
Example	int value; A = DSP_ADD(A, value, 0);
Notes	An error message will be displayed if : The result is not an accumulator register. Argument 0 is not an accumulator. The shift value is not a literal within range.

DSP_CLR

Prototype	int DSP_CLR(void);
Description	Clear the specified accumulator. Assembler Operator / Machine Instruction : `clr`.
Parameters	None.
Returns	Returns the cleared value result to an accumulator.
Requires	Nothing.
Example	A = DSP_CLR();
Notes	An error message will be displayed if the result is not an accumulator register.

DSP_CLR_prefetch

Prototype	int DSP_CLR_prefetch(int xptr, int** xval, const int* xincr, int yptr, int** yval, const int* yincr, int *AWB);
Description	Clear an accumulator and prefetch data ready for a future MAC operation. `xptr` may be null to signify no X prefetch to be performed, in which case the values of `xincr` and `xval` are ignored, but required. `yptr` may be null to signify no Y prefetch to be performed, in which case the values of `yincr` and `yval` are ignored, but required. `xval` and `yval` nominate the address of a C variable where the prefetched value will be stored. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. If AWB is non null, the other accumulator will be written back into the referenced variable. Assembler Operator / Machine Instruction : `clr`.
Parameters	`xptr:` Integer pointer to x prefetch. `xval:` Integer value of x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to y prefetch. `yval:` Integer value of y prefetch. `yincr:` Integer increment value of y prefetch. `AWB:` Accumulator write back location.
Returns	Returns the cleared value result to an accumulator.
Requires	Nothing.
Example	int xdata x_memory_buffer[256]; int ydata y_memory_buffer[256]; int xmemory; int* ymemory; int* awb; int xVal, yVal; xmemory = x_memory_buffer; ymemory = y_memory_buffer; A = DSP_CLR_prefetch(&xmemory, &xVal, 2, &ymemory, &yVal, 2, &awb); /* After this instruction: - result will be cleared, - xVal will contain x_memory_buffer[0], - yVal will contain y_memory_buffer[0], - xmemory and ymemory will be incremented by 2, ready for the next MAC operation*/
Notes	An error message will be displayed if : The result is not an accumulator register. `xval` is a null value but `xptr` is not null. `yval` is a null value but `yptr` is not null. The compiler may need to spill W13 to ensure that it is available for the write-back. It may be recommended to users that the register be claimed for this purpose.

DSP_ED

Prototype	int DSP_ED(int sqr, int xptr, const int xincr, int yptr, const int yincr, int *distance);
Description	Squares `sqr`, returning it as the result. Also prefetches data for future square operation by computing `xptr - yptr` and storing the result in `*distance`. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. Assembler Operator / Machine Instruction : `ed`.
Parameters	`sqr:` Integer squared value. `xptr:` Integer pointer to pointer to x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to pointer to y prefetch. `yincr:` Integer increment value of y prefetch `distance:` nteger pointer to distance.
Returns	Returns the squared result to an accumulator.
Requires	Nothing.
Example	int xmemory, ymemory; int distance; A = DSP_ED(distance, &xmemory, 2, &ymemory, 2, &distance);
Notes	An error message will be displayed if : The result is not an accumulator register. `xptr` is null. `yptr` is null. `distance` is null.

DSP_EDAC

Prototype	int DSP_EDAC(const int acc, int sqr, int xptr, const int xincr, int yptr, const int yincr, int *distance);
Description	Squares `sqr` and sums with the nominated accumulator register, returning it as the result. Also prefetches data for future square operation by computing `xptr - yptr` and storing the result in `*distance`. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. Assembler Operator / Machine Instruction : `edac`.
Parameters	`acc:` Accumulator to sum. `sqr:` Integer squared value. `xptr:` Integer pointer to pointer to x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to pointer to y prefetch. `yincr:` Integer increment value of y prefetch `distance:` nteger pointer to distance.
Returns	Returns the computed result to specified accumulator.
Requires	Nothing.
Example	int xmemory, ymemory; int distance; A = DSP_EDAC(A, distance, &xmemory, 2, &ymemory, 2, &distance);
Notes	An error message will be displayed if : The result is not an accumulator register. `Acc` is not an accumulator register. `xptr` is null. `yptr` is null. `distance` is null.

DSP_LAC

Prototype	int DSP_LAC(int value, int shift);
Description	Shifts `value` by `shift` amount (a literal between -8 and 7) and returns the value to be stored into the accumulator register. Assembler Operator / Machine Instruction : `lac`.
Parameters	`value:` Integer number to be shifted. `shift:` Literal amount to shift.
Returns	Returns the shifted result to an accumulator.
Requires	Nothing.
Example	int value; A = DSP_LAC(value,3);
Notes	An error message will be displayed if : The result is not an accumulator register. The result is not an accumulator register. The shift value is not a literal within range.

DSP_MAC

Prototype	int DSP_MAC(const int acc, int a, int b, int xptr, int** xval, const int* xincr, int yptr, int** yval, const int* yincr, int *AWB);
Description	Computes `a` x `b` and sums with accumulator; also prefetches data ready for a future MAC operation. `xptr` may be null to signify no X prefetch to be performed, in which case the values of `xincr` and `xval` are ignored, but required. `yptr` may be null to signify no Y prefetch to be performed, in which case the values of `yincr` and `yval` are ignored, but required. `xval` and `yval` nominate the address of a C variable where the prefetched value will be stored. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. If `AWB` is non null, the other accumulator will be written back into the referenced variable. Assembler Operator / Machine Instruction : `mac`.
Parameters	`acc:` Accumulator to sum. `a:` Integer multiplicand. `b:` Integer multiplier. `xptr:` Integer pointer to pointer to x prefetch. `xval:` Integer pointer to value of x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to pointer to y prefetch. `yval:` Integer pointer to value of y prefetch. `yincr:` Integer increment value of y prefetch. `AWB:` Accumulator write-back location.
Returns	Returns the computed result to an accumulator.
Requires	Nothing.
Example	int xmemory; int* ymemory; int* xVal, yVal; A = DSP_MAC(A, xVal, yVal, &xmemory, &xVal, 2, &ymemory, &yVal, 2, 0);
Notes	An error message will be displayed if : The result is not an accumulator register. `Acc` is not an accumulator register. `xval` is a null value but `xptr` is not null. `yval` is a null value but `yptr` is not null.

DSP_MOVSAC

Prototype	void DSP_MOVSAC(int xptr, int** xval, const int* xincr, int yptr, int** yval, const int* yincr, int AWB, const int* AWB_acc);
Description	Computes nothing, but prefetches data ready for a future MAC operation. `xptr` may be null to signify no X prefetch to be performed, in which case the values of `xincr` and `xval` are ignored, but required. `yptr` may be null to signify no Y prefetch to be performed, in which case the values of `yincr` and `yval` are ignored, but required. `xval` and `yval` nominate the address of a C variable where the prefetched value will be stored. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. If `AWB` is non null, the other accumulator will be written back into the referenced variable. Assembler Operator / Machine Instruction : `movsac`.
Parameters	`xptr:` Integer pointer to pointer to x prefetch. `xval:` Integer pointer to value of x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to pointer to y prefetch. `yval:` Integer pointer to value of y prefetch. `yincr:` Integer increment value of y prefetch. `AWB:` Accumulator write-back location. `AWB_acc:` Accumulator to write back.
Returns	Nothing, just prefetches data.
Requires	Nothing.
Example	int xmemory; int* ymemory; int* xVal, yVal; DSP_MOVSAC(&xmemory, &xVal, 2, &ymemory, &yVal, 2, 0, A);
Notes	An error message will be displayed if : The result is not an accumulator register. `xval` is a null value but `xptr` is not null. `yval` is a null value but `yptr` is not null. `AWB_acc` is not an accumulator register and `AWB` is not null.

DSP_MPY

Prototype	int DSP_MPY(int a, int b, int xptr, int** xval, const int* xincr, int yptr, int** yval, const int* yincr);
Description	Computes `a` x `b`; also prefetches data ready for a future MAC operation. `xptr` may be null to signify no X prefetch to be performed, in which case the values of `xincr` and `xval` are ignored, but required. `yptr` may be null to signify no Y prefetch to be performed, in which case the values of `yincr` and `yval` are ignored, but required. `xval` and `yval` nominate the address of a C variable where the prefetched value will be stored. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. Assembler Operator / Machine Instruction : `mpy`.
Parameters	`a:` Integer multiplicand. `b:` Integer multiplier. `xptr:` Integer pointer to pointer to x prefetch. `xval:` Integer pointer to value of x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to pointer to y prefetch. `yval:` Integer pointer to value of y prefetch. `yincr:` Integer increment value of y prefetch.
Returns	Returns the computed result to an accumulator.
Requires	Nothing.
Example	int xmemory; int* ymemory; int* xVal, yVal; A = DSP_MPY(xVal, yVal, &xmemory, &xVal, 2, &ymemory, &yVal, 2);
Notes	An error message will be displayed if : The result is not an accumulator register. `xval` is a null value but `xptr` is not null. `yval` is a null value but `yptr` is not null.

DSP_MPYN

Prototype	int DSP_MPYN(int a, int b, int xptr, int** xval, const int* xincr, int yptr, int** yval, const int* yincr);
Description	Computes `-a` x `b`; also prefetches data ready for a future MAC operation. `xptr` may be null to signify no X prefetch to be performed, in which case the values of `xincr` and `xval` are ignored, but required. `yptr` may be null to signify no Y prefetch to be performed, in which case the values of `yincr` and `yval` are ignored, but required. `xval` and `yval` nominate the address of a C variable where the prefetched value will be stored. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. Assembler Operator / Machine Instruction : `mpyn`.
Parameters	`a:` Integer multiplicand. `b:` Integer multiplier. `xptr:` Integer pointer to pointer to x prefetch. `xval:` Integer pointer to value of x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to pointer to y prefetch. `yval:` Integer pointer to value of y prefetch. `yincr:` Integer increment value of y prefetch.
Returns	Returns the addition result to an accumulator.
Requires	Nothing.
Example	int xmemory; int* ymemory; int* xVal, yVal; A = DSP_MPYN(xVal, yVal, &xmemory, &xVal, 2, &ymemory, &yVal, 2);
Notes	An error message will be displayed if : The result is not an accumulator register. `xval` is a null value but `xptr` is not null. `yval` is a null value but `yptr` is not null.

DSP_MSC

Prototype	int DSP_MSC(const int acc, int a, int b, int xptr, int** xval, const int* xincr, int yptr, int** yval, const int* yincr, int *AWB);
Description	Computes `a` x `b` and subtracts from accumulator; also prefetches data ready for a future MAC operation. `xptr` may be null to signify no X prefetch to be performed, in which case the values of `xincr` and `xval` are ignored, but required. `yptr` may be null to signify no Y prefetch to be performed, in which case the values of `yincr` and `yval` are ignored, but required. `xval` and `yval` nominate the address of a C variable where the prefetched value will be stored. `xincr` and `yincr` may be the literal values: -6, -4, -2, 0, 2, 4, 6 or an integer value. If `AWB` is non null, the other accumulator will be written back into the referenced variable. Assembler Operator / Machine Instruction : `msc`.
Parameters	`acc:` Accumulator to sum. `a:` Integer multiplicand. `b:` Integer multiplier. `xptr:` Integer pointer to pointer to x prefetch. `xval:` Integer pointer to value of x prefetch. `xincr:` Integer increment value of x prefetch. `yptr:` Integer pointer to pointer to y prefetch. `yval:` Integer pointer to value of y prefetch. `yincr:` Integer increment value of y prefetch. `AWB:` Accumulator write back location.
Returns	Returns the computed result to an accumulator.
Requires	Nothing.
Example	int xmemory; int* ymemory; int* xVal, yVal; A = DSP_MSC(A, xVal, yVal, &xmemory, &xVal, 2, &ymemory, &yVal, 2, 0);
Notes	An error message will be displayed if : The result is not an accumulator register. `Acc` is not an accumulator register. `xval` is a null value but `xptr` is not null. `yval` is a null value but `yptr` is not null.

DSP_SAC

Prototype	int DSP_SAC(const int acc, const int shift);
Description	Shifts accumulator by `shift` amount (a literal between -8 and 7) and returns the value in the same accumulator. Assembler Operator / Machine Instruction : `sac`.
Parameters	`acc:` Accumulator to be shifted. `shift:` Literal amount to shift.
Returns	Returns the shifted accumulator value.
Requires	Nothing.
Example	int result; result = DSP_SAC(A, 3);
Notes	An error message will be displayed if : The result is not an accumulator register. The `shift` value is not a literal within range.

DSP_SACR

Prototype	int DSP_SACR(const int acc, const int shift);
Description	Shifts value by `shift` amount (a literal between -8 and 7) and returns the value which is rounded using the rounding mode determined by the CORCON's RND control bit. Assembler Operator / Machine Instruction : `sacr`.
Parameters	`acc:` Accumulator to be shifted. `shift:` Literal amount to shift.
Returns	Returns the shifted accumulator value.
Requires	Nothing.
Example	int result; result = DSP_SACR(A, 3);
Notes	An error message will be displayed if : The result is not an accumulator register. The `shift` value is not a literal within range.

DSP_SFTAC

Prototype	int DSP_SFTAC(const int acc, int shift);
Description	Shifts accumulator by `shift` amount. The valid `shift` range is -16 to 16. Assembler Operator / Machine Instruction : `sftac`.
Parameters	`acc:` Accumulator to shift. `shift:` Amount to shift.
Returns	Returns the shifted accumulator value.
Requires	Nothing.
Example	int i; A = DSP_SFTAC(A, i);
Notes	An error message will be displayed if : The result is not an accumulator register. The `Acc` is not an accumulator register. The `shift` value is not a literal within range.

DSP_SUBAB

Prototype	int DSP_SUBAB(const int acc_a, const int acc_b);
Description	Subtracts accumulators `A` and `B` with the result written back to the specified accumulator. Assembler Operator / Machine Instruction : `sub`.
Parameters	`acc_a:` ccumulator from which to subtract. `acc_b:` Accumulator to subtract. Both arguments can be ommited.
Returns	Returns the subtraction result to an accumulator.
Requires	Nothing.
Example	A = DSP_SUBAB();
Notes	An error message will be displayed if the result is not an accumulator register.

Want more examples and libraries?
Find them on