DSP Built-in Routines

mikroPascal 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	function DSP_ADDAB(const acc_a : integer; const acc_b : integer) : integer;
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	function DSP_ADD(const acc : integer; value : integer, const shift : integer) : integer;
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	var value : integer; 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	function DSP_CLR() : integer;
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	function DSP_CLR_prefetch(xptr : ^^integer; xval : ^integer; const xincr : integer; yptr : ^^integer; yval : ^integer; const yincr : integer; AWB : ^integer) : integer;
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	var x_memory_buffer : array[256] of integer; xdata; var y_memory_buffer : array[256] of integer; ydata; var xmemory : ^integer; var ymemory : ^integer; var awb : integer; var xVal, yVal : integer; 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	function DSP_ED(sqr : integer; xptr : ^^integer; const xincr : integer; yptr : ^^integer; const yincr : integer; distance : ^integer) : integer;
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	var xmemory, ymemory : ^integer; var distance : integer; 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	function DSP_EDAC(const acc : integer; sqr : integer; xptr : ^^integer; const xincr : integer; yptr : ^^integer; const yincr : integer; distance : ^integer) : integer
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	var xmemory, ymemory : ^integer; var distance : integer; 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	function DSP_LAC(value : integer; shift : integer) : integer;
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	var value : integer; 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	function DSP_MAC(const acc : integer; a : integer; b : integer; xptr : ^^integer; xval : ^integer; const xincr : integer; yptr : ^^integer; yval : ^integer; const yincr : integer; AWB : ^integer) : integer;
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	var xmemory : ^integer; var umemory : ^integer; var xVal, yVal : integer; 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	function DSP_MOVSAC(xptr : ^^integer; xval : ^integer; const xincr : integer; yptr : ^^integer; yval : ^integer; const yincr : integer; AWB : ^integer; const AWB_acc : integer) : integer;
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	var xmemory : ^integer; var ymemory : ^integer; var xVal, yVal : integer; 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	function DSP_MPY(a : integer; b : integer; xptr : ^^integer; xval : ^integer; const xincr : integer; yptr : ^^integer; yval : ^integer; const yincr : integer) : integer;
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	var xmemory : ^integer; var ymemory : ^integer; var xVal, yVal : integer; 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	function DSP_MPYN(a : integer; b : integer; xptr : ^^integer; xval : ^integer; const xincr : integer; yptr : ^^integer; yval : ^integer; const yincr : integer) : integer;
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	var xmemory : ^integer; var ymemory : ^integer; var xVal, yVal : integer; 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	function DSP_MSC(const acc : integer; a : integer; b : integer; xptr : ^^integer; xval : ^integer; const xincr : integer; yptr : ^^integer; yval : ^integer; const yincr : integer; AWB : ^integer) : integer;
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	var xmemory : ^integer; var ymemory : ^integer; var xVal, yVal : integer; 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 acc : integer; const shift : integer) : integer;
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	var res : integer; res := 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 acc : integer; const shift : integer);
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	var res : integer; res := 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	function DSP_SFTAC(const acc : integer; const shift : integer) : integer;
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	var i : integer; 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	function DSP_SUBAB(const acc_a : integer; const acc_b : integer) : integer;
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