5.2 Built-In Functions List

Adds Accumulators A and B with the result written back to the specified accumulator. For example:

register int result asm("A");
register int B asm("A");
result = _builtin_addab(result,B);

will generate:

add A

int _builtin_addab(int Accum_a, int Accum_b);

Accum_a First accumulator to add.

Accum_b Second accumulator to add.

Returns the addition result to an accumulator.

add

An error message appears if the result is not an Accumulator register.

Adds value to the accumulator specified by result with a shift specified by literal shift. For example:

register int result asm("A");
int      value;
result = _builtin_add(result,value,0);

If value is held in w0, the following will be generated:

add w0, #0, A

int   _builtin_add(int Accum,int value,
const int shift);

Accum Accumulator to add.

value Integer number to add to accumulator value.

shift Amount to shift resultant accumulator value.

Returns the shifted addition result to an accumulator.

add

An error message appears if:

• The result is not an Accumulator register
• Argument 0 is not an accumulator
• The shift value is not a literal within range

This function will generate a btg machine instruction. Some examples include:

int i;   /* near by default */
int l    _attribute_((far));
struct foo {
  int bit1:1;
} barbits;
int  bar;
void some_bittoggles() {
  register int j asm("w9");
  int k;
  k = i;
  _builtin_btg(&i,1);
  _builtin_btg(&j,3);
_builtin_btg(&k,4);
  _builtin_btg(&l,11);
  return j+k;
}

Note that taking the address of a variable in a register will produce a warning by the compiler and cause the register to be saved onto the stack (so that its address may be taken); this form is not recommended. This caution only applies to variables explicitly placed in registers by the programmer.

void _builtin_btg(unsigned int *, unsigned int 0xn);

* A pointer to the data item for which a bit should be toggled.

0xn A literal value in the range of 0 to 15.

Returns a btg machine instruction.

btg

An error message appears if the parameter values are not within range.

Clears the specified accumulator. For example:

register int result asm("A");
result = _builtin_clr();

will generate:

clr A

int _builtin_clr(void);

None.

Returns the cleared value result to an accumulator.

clr

An error message appears if the result is not an Accumulator register.

Computes the quotient: num / den. A math error exception occurs if den is zero. Function arguments are unsigned, as is the function result.

unsigned int _builtin_divf(unsigned int num,
unsigned int den);

num Numerator.

den Denominator.

Returns the unsigned integer value of the quotient: num / den.

div.f

Issues the 16-bit architecture’s native signed divide support. Notably, if the quotient does not fit into a 16-bit result, the results (including remainder) are unexpected. This form of the built-in function will capture both the quotient and remainder.

signed int  _builtin_divmodsd(
signed long dividend, signed int divisor,
signed int  *remainder);

dividend Number to be divided.

divisor Number to divide by.

remainder Pointer to remainder.

Quotient and remainder.

divmodsd

None.

Issues the 16-bit architecture’s native unsigned divide support. Notably, if the quotient does not fit into a 16-bit result, the results (including remainder) are unexpected. This form of the built-in function will capture both the quotient and remainder.

unsigned int  _builtin_divmodud(
unsigned long dividend, unsigned int divisor,
unsigned int  *remainder);

dividend Number to be divided.

divisor Number to divide by.

remainder Pointer to remainder.

Quotient and remainder.

divmodud

None.

Computes the quotient: num / den. A math error exception occurs if den is zero. Function arguments are signed, as is the function result. The command-line option, -Wconversions, can be used to detect unexpected sign conversions.

int _builtin_divsd(const long num, const int den);

num Numerator.

den Denominator.

Returns the signed integer value of the quotient: num / den.

div.sd

Computes the quotient: num / den. A math error exception occurs if den is zero. Function arguments are unsigned, as is the function result. The command-line option, -Wconversions, can be used to detect unexpected sign conversions.

unsigned int  _builtin_divud(const unsigned 
long     num, const unsigned int den);

num Numerator.

den Denominator.

Returns the unsigned integer value of the quotient: num / den.

div.ud

Obtains the offset of a symbol within DMA memory.

For example:

unsigned int         result;
char     buffer[256] _attribute_((space(dma)));
result = _builtin_dmaoffset(&buffer);

May generate:

mov #dmaoffset(buffer), w0

unsigned int _builtin_dmaoffset(const void *p);

*p Pointer to DMA address value.

Returns the offset to a variable located in DMA memory.

dmaoffset

An error message appears if the parameter is not the address of a global symbol.

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.

For example:

register int result asm("A");
int      *xmemory, *ymemory;
int      distance;
result = _builtin_ed(distance,
                      &xmemory, 2,
                      &ymemory, 2,
                      &distance);

May generate:

ed w4*w4, A, [w8]+=2, [W10]+=2, w4

int _builtin_ed(int sqr, int **xptr, int xincr,
int **yptr, int yincr, int *distance);

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 Integer Pointer to distance.

Returns the squared result to an accumulator.

ed

An error message appears if:

• The result is not an Accumulator register
• xptr is null
• yptr is null
• distance is null

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.

For example:

register int result asm("A");
int      *xmemory, *ymemory;
int      distance;
result = _builtin_ed(result, distance,
                      &xmemory, 2,
                      &ymemory, 2,
                      &distance);

May generate:

edac w4*w4, A, [w8]+=2, [W10]+=2, w4

int _builtin_edac(int Accum, int sqr,
int **xptr, int xincr, int **yptr, int yincr,
int *distance);

Accum 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 Integer Pointer to distance.

Returns the squared result to specified accumulator.

edac

An error message appears if:

• The result is not an Accumulator register
• Accum is not an Accumulator register
• xptr is null
• yptr is null
• distance is null

Finds the first bit change from left in value. This is useful for dynamic scaling of fixed-point data. For example:

int result, value;
result = _builtin_fbcl(value);

May generate:

fbcl w4, w5

int _builtin_fbcl(int value);

value Integer number of first bit change.

Returns the shifted addition result to an accumulator.

fbcl

An error message appears if the result is not an Accumulator register.

Shifts value by shift (a literal between -8 and 7) and returns the value to be stored into the Accumulator register. For example:

register int result asm("A");
int      value;
result = _builtin_lac(value,3);

May generate:

lac w4, #3, A

int _builtin_lac(int value, int shift);

value Integer number to be shifted.

shift Literal amount to shift.

Returns the shifted addition result to an accumulator.

lac

An error message appears if:

• The result is not an Accumulator register
• The shift value is not a literal within range

Computes a x b and sums with the accumulator; it 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.

For example:

register int result asm("A");
register int B asm("B");
int      *xmemory;
int      *ymemory;
int      xVal, yVal;
result = _builtin_mac(result, xVal, yVal,
                       &xmemory, &xVal, 2,
                       &ymemory, &yVal, 2, 0, B);

May generate:

mac w4*w5, A, [w8]+=2, w4, [w10]+=2, w5

int _builtin_mac(int Accum, int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr, int *AWB,
int AWB_accum);

Accum 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.

AWB_accum Accumulator to Write-Back.

Returns the cleared value result to an accumulator.

mac

An error message appears if:

• The result is not an Accumulator register
• Accum 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_accum is not an Accumulator register and AWB is not null

Issues the 16-bit architecture’s native signed divide support. Notably, if the quotient does not fit into a 16-bit result, the results (including remainder) are unexpected. This form of the built-in function will capture only the remainder.

signed int _builtin_modsd(signed long dividend,
signed int divisor);

dividend Number to be divided.

divisor Number to divide by.

Remainder.

modsd

None.

Issues the 16-bit architecture’s native unsigned divide support. Notably, if the quotient does not fit into a 16-bit result, the results (including remainder) are unexpected. This form of the built-in function will capture only the remainder.

unsigned int _builtin_modud(unsigned long dividend,
unsigned int divisor);

dividend Number to be divided.

divisor Number to divide by.

Remainder.

modud

None.

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.

For example:

register int result asm("A");
int      *xmemory;
int      *ymemory;
int      xVal, yVal;
result = _builtin_mpy(xVal, yVal,
                       &xmemory, &xVal, 2,
                       &ymemory, &yVal, 2);

May generate:

mac w4*w5, A, [w8]+=2, w4, [w10]+=2, w5

int _builtin_mpy(int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr);

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 Integer Pointer to accumulator selection.

Returns the cleared value result to an accumulator.

mpy

An error message appears 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

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.

For example:

register int result asm("A");
int      *xmemory;
int      *ymemory;
int      xVal, yVal;
result = _builtin_mpy(xVal, yVal,
                       &xmemory, &xVal, 2,
                       &ymemory, &yVal, 2);

May generate:

mac w4*w5, A, [w8]+=2, w4, [w10]+=2, w5

int _builtin_mpyn(int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr);

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 Integer Pointer to accumulator selection.

Returns the cleared value result to an accumulator.

mpyn

An error message appears 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

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.

For example:

register int result asm("A");
int      *xmemory;
int      *ymemory;
int      xVal, yVal;
result = _builtin_msc(result, xVal, yVal,
                       &xmemory, &xVal, 2,
                       &ymemory, &yVal, 2, 0, 0);

May generate:

msc w4*w5, A, [w8]+=2, w4, [w10]+=2, w5

int _builtin_msc(int Accum, int a, int b,
int **xptr, int *xval, int xincr,
int **yptr, int *yval, int yincr, int *AWB,
int AWB_accum);

Accum 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.

AWB_accum Accumulator to Write-Back.

Returns the cleared value result to an accumulator.

msc

An error message appears if:

• The result is not an Accumulator register
• Accum 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_accum is not an Accumulator register and AWB is not null

Computes the product p0 x p1. Function arguments are signed integers and the function result is a signed long integer. The command-line option, -Wconversions, can be used to detect unexpected sign conversions.

signed long _builtin_mulss(const signed int p0, const signed int p1);

p0 Multiplicand.

p1 Multiplier.

Returns the signed long integer value of the product p0 x p1.

mul.ss

Computes the product p0 x p1. Function arguments are integers with mixed signs and the function result is a signed long integer. The command-line option, -Wconversions, can be used to detect unexpected sign conversions. This function supports the full range of addressing modes of the instruction, including Immediate mode for operand p1.

signed long _builtin_mulsu(const signed int p0, const unsigned int p1);

p0 Multiplicand.

p1 Multiplier.

Returns the signed long integer value of the product p0 x p1.

mul.su

Computes the product p0 x p1. Function arguments are integers with mixed signs and the function result is a signed long integer. The command-line option, -Wconversions, can be used to detect unexpected sign conversions. This function supports the full range of addressing modes of the instruction.

signed long _builtin_mulus(const unsigned int p0, const signed int p1);

p0 Multiplicand.

p1 Multiplier.

Returns the signed long integer value of the product p0 x p1.

mul.us

Computes the product p0 x p1. Function arguments are unsigned integers and the function result is an unsigned long integer. The command-line option, -Wconversions, can be used to detect unexpected sign conversions. This function supports the full range of addressing modes of the instruction, including Immediate mode for operand p1.

unsigned long _builtin_muluu(const unsigned int p0, const unsigned int p1);

p0 Multiplicand.

p1 Multiplier.

Returns the signed long integer value of the product p0 x p1.

mul.uu

Generates a NOP instruction.

void _builtin_nop(void);

None.

Returns a no operation (NOP).

NOP

Reads the SFR.

unsigned int _builtin_readsfr(const void *p);

p Object address.

Returns the SFR.

readsfr

Returns the return address of the current function or of one of its callers. For the level argument, a value of zero yields the return address of the current function, a value of one yields the return address of the caller of the current function, and so forth. When level exceeds the current stack depth, zero will be returned. This function should only be used with a non-zero argument for debugging purposes.

int _builtin_return_address (const int level);

level Number of frames to scan up the call stack.

Returns the return address of the current function or of one of its callers.

return_address

Shifts value by shift (a literal between -8 and 7) and returns the value.

For example:

register int value asm("A");
int      result;
result = _builtin_sac(value,3);

May generate:

sac A, #3, w0

int _builtin_sac(int value, int shift);

value Integer number to be shifted.

shift Literal amount to shift.

Returns the shifted result to an accumulator.

sac

An error message appears if:

• The result is not an Accumulator register
• The shift value is not a literal within range

Shifts value by shift (a literal between -8 and 7) and returns the value, which is rounded using the Rounding mode determined by the RND (CORCON<1>) control bit.

For example:

register int value asm("A");
int      result;
result = _builtin_sac(value,3);

May generate:

sacr A, #3, w0

int _builtin_sacr(int value, int shift);

value Integer number to be shifted.

shift Literal amount to shift.

Returns the shifted result to the CORCON register.

sacr

An error message appears if:

• The result is not an Accumulator register
• The shift value is not a literal within range

Shifts accumulator by shift. The valid shift range is -16 to 16.

For example:

register int result asm("A");
int      i;
result = _builtin_sftac(result,i);

May generate:

sftac A, w0

int _builtin_sftac(int Accum, int shift);

Accum Accumulator to shift.

shift Amount to shift.

Returns the shifted result to an accumulator.

sftac

An error message appears if:

• The result is not an Accumulator register
• Accum is not an Accumulator register
• The shift value is not a literal within range

Subtracts accumulators A and B with the result written back to the specified accumulator. For example:

register int result asm("A");
register int B asm("B");
result = _builtin_subab(result,B);

Will generate:

sub A

int _builtin_subab(int Accum_a, int Accum_b);

Accum_a Accumulator from which to subtract.

Accum_b Accumulator to subtract.

Returns the subtraction result to an accumulator.

sub

An error message appears if the result is not an Accumulator register.