DSP Built-in Routines

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