原创 Microchip C30 的内部函数

 2010-9-26 09:19  12743 9 7 分类: MCU/ 嵌入式

Microchip C30有一些内部函数，使用这些函数，可以实现一些比较底层的功能。这样的好处是可以不需要使用嵌入式汇编，可以简化程序，也方便代码维护。

所有的内部函数都是以__builtin_开始的。下面是内部函数列表，摘自C30的帮助文件hlpMPLABC30.chm。

Built-In Function List

__builtin_addab

Description:

Add 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

Prototype:

int __builtin_addab(int Accum_a, int Accum_b);

Argument:

Accum_a First accumulator to add.

Accum_b Second accumulator to add.

Return Value:

Returns the addition result to an accumulator.

Assembler Operator / Machine Instruction:

add

Error Messages

An error message will be displayed if the result is not an accumulator register.

__builtin_add

Description:

Add 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

Prototype:

int __builtin_add(int Accum,int value,

const int shift);

Argument:

Accum Accumulator to add.

value Integer number to add to accumulator value.

shift Amount to shift resultant accumulator value.

Return Value:

Returns the shifted addition result to an accumulator.

Assembler Operator / Machine Instruction:

add

Error Messages

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

__builtin_btg

Description:

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

Prototype:

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

Argument:

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

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

Return Value:

Returns a btg machine instruction.

Assembler Operator / Machine Instruction:

btg

Error Messages

An error message will be displayed if the parameter values are not within range

__builtin_clr

Description:

Clear the specified accumulator. For example:

register int result asm("A");

result = __builtin_clr();

will generate:

clr A

Prototype:

int __builtin_clr(void);

Argument:

None

Return Value:

Returns the cleared value result to an accumulator.

Assembler Operator / Machine Instruction:

clr

Error Messages

An error message will be displayed if the result is not an accumulator register.

__builtin_clr_prefetch

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.

For example:

register int result asm("A");

register int B asm("B");

int x_memory_buffer[256]

__attribute__((space(xmemory)));

int y_memory_buffer[256]

__attribute__((space(ymemory)));

int *xmemory;

int *ymemory;

int awb;

int xVal, yVal;

xmemory = x_memory_buffer;

ymemory = y_memory_buffer;

result = __builtin_clr(&xmemory, &xVal, 2,

&ymemory, &yVal, 2, &awb, B);

might generate:

clr A, [w8]+=2, w4, [w10]+=2, w5, w13

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.

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

Prototype:

int __builtin_clr_prefetch(

int **xptr, int *xval, int xincr,

int **yptr, int *yval, int yincr, int *AWB,

int AWB_accum);

Argument:

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.

AWB_accum Accumulator to write back.

Return Value:

Returns the cleared value result to an accumulator.

Assembler Operator / Machine Instruction:

clr

Error Messages

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_accum is not an accumulator and AWB is not null

__builtin_divf

Description:

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

Prototype:

unsigned int __builtin_divf(unsigned int num,

unsigned int den);

Argument:

num numerator

den denominator

Return Value:

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

Assembler Operator / Machine Instruction:

div.f

__builtin_divmodsd

Description:

Issues the 16-bit architecture's native signed divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.

Prototype:

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

Argument:

dividend number to be divided

divisor number to divide by

remainder pointer to remainder

Return Value:

Quotient and remainder.

Assembler Operator / Machine Instruction:

divmodsd

Error Messages

None.

__builtin_divmodud

Description:

Issues the 16-bit architecture's native unsigned divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.

Prototype:

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

Argument:

dividend number to be divided

divisor number to divide by

remainder pointer to remainder

Return Value:

Quotient and remainder.

Assembler Operator / Machine Instruction:

divmodud

Error Messages

None.

__builtin_divsd

Description:

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.

Prototype:

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

Argument:

num numerator

den denominator

Return Value:

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

Assembler Operator / Machine Instruction:

div.sd

__builtin_divud

Description:

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.

Prototype:

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

Argument:

num numerator

den denominator

Return Value:

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

Assembler Operator / Machine Instruction:

div.ud

__builtin_dmaoffset

Description:

Obtains the offset of a symbol within DMA memory.

For example:

unsigned int result;

char buffer[256] __attribute__((space(dma)));

result = __builtin_dmaoffset(&buffer);

Might generate:

mov #dmaoffset(buffer), w0

Prototype:

unsigned int __builtin_dmaoffset(const void *p);

Argument:

*p pointer to DMA address value

Return Value:

Returns the offset to a variable located in DMA memory.

Assembler Operator / Machine Instruction:

dmaoffset

Error Messages

An error message will be displayed if the parameter is not the address of a global symbol.

__builtin_ed

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.

For example:

register int result asm("A");

int *xmemory, *ymemory;

int distance;

result = __builtin_ed(distance,

&xmemory, 2,

&ymemory, 2,

&distance);

might generate:

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

Prototype:

int __builtin_ed(int sqr, int **xptr, int xincr,

int **yptr, int yincr, int *distance);

Argument:

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.

Return Value:

Returns the squared result to an accumulator.

Assembler Operator / Machine Instruction:

ed

Error Messages

An error message will be displayed if:

the result is not an accumulator register

xptr is null

yptr is null

distance is null

__builtin_edac

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 - **yptrand 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);

might generate:

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

Prototype:

int __builtin_edac(int Accum, int sqr,

int **xptr, int xincr, int **yptr, int yincr,

int *distance);

Argument:

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.

Return Value:

Returns the squared result to specified accumulator.

Assembler Operator / Machine Instruction:

edac

Error Messages

An error message will be displayed if:

the result is not an accumulator register

Accum is not an accumulator register

xptr is null

yptr is null

distance is null

__builtin_fbcl

Description:

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);

might generate:

fbcl w4, w5

Prototype:

int __builtin_fbcl(int value);

Argument:

value Integer number of first bit change.

Return Value:

Returns the shifted addition result to an accumulator.

Assembler Operator / Machine Instruction:

fbcl

Error Messages

An error message will be displayed if the result is not an accumulator register.

__builtin_lac

Description:

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);

Might generate:

lac w4, #3, A

Prototype:

int __builtin_lac(int value, int shift);

Argument:

value Integer number to be shifted.

shift Literal amount to shift.

Return Value:

Returns the shifted addition result to an accumulator.

Assembler Operator / Machine Instruction:

lac

Error Messages

An error message will be displayed if:

the result is not an accumulator register

the shift value is not a literal within range

__builtin_mac

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.

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);

might generate:

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

Prototype:

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);

Argument:

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.

Return Value:

Returns the cleared value result to an accumulator.

Assembler Operator / Machine Instruction:

mac

Error Messages

An error message will be displayed 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

__builtin_modsd

Description:

Issues the 16-bit architecture's native signed divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.

Prototype:

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

Argument:

dividend number to be divided

divisor number to divide by

Return Value:

Remainder.

Assembler Operator / Machine Instruction:

modsd

Error Messages

None.

__builtin_modud

Description:

Issues the 16-bit architecture's native unsigned divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.

Prototype:

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

Argument:

dividend number to be divided

divisor number to divide by

Return Value:

Remainder.

Assembler Operator / Machine Instruction:

modud

Error Messages

None.

__builtin_movsac

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.

For example:

register int result asm("A");

int *xmemory;

int *ymemory;

int xVal, yVal;

result = __builtin_movsac(&xmemory, &xVal, 2,

&ymemory, &yVal, 2, 0, 0);

might generate:

movsac A, [w8]+=2, w4, [w10]+=2, w5

Prototype:

int __builtin_movsac(

int **xptr, int *xval, int xincr,

int **yptr, int *yval, int yincr, int *AWB

int AWB_accum);

Argument:

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.

Return Value:

Returns prefetch data.

Assembler Operator / Machine Instruction:

movsac

Error Messages

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_accum is not an accumulator register and AWB is not null

__builtin_mpy

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.

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);

might generate:

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

Prototype:

int __builtin_mpy(int a, int b,

int **xptr, int *xval, int xincr,

int **yptr, int *yval, int yincr);

Argument:

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.

Return Value:

Returns the cleared value result to an accumulator.

Assembler Operator / Machine Instruction:

mpy

Error Messages

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

__builtin_mpyn

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.

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);

might generate:

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

Prototype:

int __builtin_mpyn(int a, int b,

int **xptr, int *xval, int xincr,

int **yptr, int *yval, int yincr);

Argument:

aInteger multiplicand.

bInteger multiplier.

xptrInteger pointer to pointer to x prefetch.

xvalInteger pointer to value of x prefetch.

xincrInteger increment value of x prefetch.

yptrInteger pointer to pointer to y prefetch.

yvalInteger pointer to value of y prefetch.

yincrInteger increment value of y prefetch.

AWBInteger pointer to accumulator selection.

Return Value:

Returns the cleared value result to an accumulator.

Assembler Operator / Machine Instruction:

mpyn

Error Messages

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

__builtin_msc

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.

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);

might generate:

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

Prototype:

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);

Argument:

AccumIAccumulator to sum.

aInteger multiplicand.

bInteger multiplier.

xptrInteger pointer to pointer to x prefetch.

xvalInteger pointer to value of x prefetch.

xincrInteger increment value of x prefetch.

yptrInteger pointer to pointer to y prefetch.

yvalInteger pointer to value of y prefetch.

yincrInteger increment value of y prefetch.

AWBAccumulator write back location.

AWB_accumAccumulator to write back.

Return Value:

Returns the cleared value result to an accumulator.

Assembler Operator / Machine Instruction:

msc

Error Messages

An error message will be displayed 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

__builtin_mulss

Description:

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.

Prototype:

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

Argument:

p0multiplicand

p1 multiplier

Return Value:

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

Assembler Operator / Machine Instruction:

mul.ss

__builtin_mulsu

Description:

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.

Prototype:

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

Argument:

p0multiplicand

p1 multiplier

Return Value:

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

Assembler Operator / Machine Instruction:

mul.su

__builtin_mulus

Description:

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.

Prototype:

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

Argument:

p0multiplicand

p1 multiplier

Return Value:

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

Assembler Operator / Machine Instruction:

mul.us

__builtin_muluu

Description:

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.

Prototype:

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

Argument:

p0multiplicand

p1 multiplier

Return Value:

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

Assembler Operator / Machine Instruction:

mul.uu

__builtin_nop

Description:

Generates a nop instruction.

Prototype:

void __builtin_nop(void);

Argument:

None.

Return Value:

Returns a no operation (nop).

Assembler Operator / Machine Instruction:

nop

__builtin_psvpage

Description:

Returns the psv page number of the object whose address is given as a parameter. The argument p must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the spaceattribute in Section 2.3.1 "Specifying Attributes of Variables".

Prototype:

unsigned int __builtin_psvpage(const void *p);

Argument:

pobject address

Return Value:

Returns the psv page number of the object whose address is given as a parameter.

Assembler Operator / Machine Instruction:

psvpage

Error Messages

The following error message is produced when this function is used incorrectly:

"Argument to __builtin_psvpage() is not the address of an object in code, psv, or eedata section".

The argument must be an explicit object address.

For example, if obj is object in an executable or read-only section, the following syntax is valid:

unsigned page = __builtin_psvpage(&obj);

__builtin_psvoffset

Description:

Returns the psv page offset of the object whose address is given as a parameter. The argument p must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the spaceattribute in Section 2.3.1 "Specifying Attributes of Variables".

Prototype:

unsigned int __builtin_psvoffset(const void *p);

Argument:

pobject address

Return Value:

Returns the psv page number offset of the object whose address is given as a parameter.

Assembler Operator / Machine Instruction:

psvoffset

Error Messages

The following error message is produced when this function is used incorrectly:

"Argument to __builtin_psvoffset() is not the address of an object in code, psv, or eedata section".

The argument must be an explicit object address.

For example, if obj is object in an executable or read-only section, the following syntax is valid:

unsigned page = __builtin_psvoffset(&obj);

__builtin_readsfr

Description:

Reads the SFR.

Prototype:

unsigned int __builtin_readsfr(const void *p);

Argument:

pobject address

Return Value:

Returns the SFR.

Assembler Operator / Machine Instruction:

readsfr

Error Messages

The following error message is produced when this function is used incorrectly:

__builtin_return_address

Description:

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

Prototype:

int __builtin_return_address (const int level);

Argument:

levelNumber of frames to scan up the call stack.

Return Value:

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

Assembler Operator / Machine Instruction:

return_address

__builtin_sac

Description:

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);

Might generate:

sac A, #3, w0

Prototype:

int __builtin_sac(int value, int shift);

Argument:

valueInteger number to be shifted.

shiftLiteral amount to shift.

Return Value:

Returns the shifted result to an accumulator.

Assembler Operator / Machine Instruction:

sac

Error Messages

An error message will be displayed if:

the result is not an accumulator register

the shift value is not a literal within range

__builtin_sacr

Description:

Shifts value by shift (a literal between -8 and 7) and returns the value which is rounded using the rounding mode determined by the CORCONbits.RND control bit.

For example:

register int value asm("A");

int result;

result = __builtin_sac(value,3);

Might generate:

sac.r A, #3, w0

Prototype:

int __builtin_sacr(int value, int shift);

Argument:

valueInteger number to be shifted.

shiftLiteral amount to shift.

Return Value:

Returns the shifted result to CORCON register.

Assembler Operator / Machine Instruction:

sacr

Error Messages

An error message will be displayed if:

the result is not an accumulator register

the shift value is not a literal within range

__builtin_sftac

Description:

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);

Might generate:

sftac A, w0

Prototype:

int __builtin_sftac(int Accum, int shift);

Argument:

Accum Accumulator to shift.

shiftAmount to shift.

Return Value:

Returns the shifted result to an accumulator.

Assembler Operator / Machine Instruction:

sftac

Error Messages

An error message will be displayed if:

the result is not an accumulator register

Accum is not an accumulator register

the shift value is not a literal within range

__builtin_subab

Description:

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

Prototype:

int __builtin_subab(int Accum_a, int Accum_b);

Argument:

Accum_a Accumulator from which to subtract.

Accum_bAccumulator to subtract.

Return Value:

Returns the subtraction result to an accumulator.

Assembler Operator / Machine Instruction:

sub

Error Messages

An error message will be displayed if the result is not an accumulator register.

__builtin_tbladdress

Description:

Returns a value that represents the address of an object in program memory. The argumentp must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the space attribute in Section 2.3.1 "Specifying Attributes of Variables".

Prototype:

unsigned long __builtin_tblpage(const void *p);

Argument:

pobject address

Return Value:

Returns an unsigned long value that represents the address of an object in program memory.

Assembler Operator / Machine Instruction:

tbladdress

Error Messages

The following error message is produced when this function is used incorrectly:

"Argument to __builtin_tbladdress() is not the address of an object in code, psv, or eedata section".

The argument must be an explicit object address.

For example, if obj is object in an executable or read-only section, the following syntax is valid:

unsigned long page = __builtin_tbladdress(&obj);

__builtin_tblpage

Description:

Returns the table page number of the object whose address is given as a parameter. The argument p must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the spaceattribute in Section 2.3.1 "Specifying Attributes of Variables".

Prototype:

unsigned int __builtin_tblpage(const void *p);

Argument:

pobject address

Return Value:

Returns the table page number of the object whose address is given as a parameter.

Assembler Operator / Machine Instruction:

tblpage

Error Messages

The following error message is produced when this function is used incorrectly:

"Argument to __builtin_tblpage() is not the address of an object in code, psv, or eedata section".

The argument must be an explicit object address.

For example, if obj is object in an executable or read-only section, the following syntax is valid:

unsigned page = __builtin_tblpage(&obj);

__builtin_tbloffset

Description:

Returns the table page offset of the object whose address is given as a parameter. The argument p must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the spaceattribute in Section 2.3.1 "Specifying Attributes of Variables".

Prototype:

unsigned int __builtin_tbloffset(const void *p);

Argument:

pobject address

Return Value:

Returns the table page number offset of the object whose address is given as a parameter.

Assembler Operator / Machine Instruction:

tbloffset

Error Messages

The following error message is produced when this function is used incorrectly:

"Argument to __builtin_tbloffset() is not the address of an object in code, psv, or eedata section".

The argument must be an explicit object address.

For example, if obj is object in an executable or read-only section, the following syntax is valid:

unsigned page = __builtin_tbloffset(&obj);

__builtin_tblrdh

Description:

Issues the tblrdh.w instruction to read a word from Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __builtin_tbloffset() and __builtin_tblpage().

Please refer to the data sheet or dsPIC Family Reference Manual for complete details regarding reading and writing program Flash.

Prototype:

unsigned int __builtin_tblrdh(unsigned int offset);

Argument:

offsetdesired memory offset

Return Value:

None.

Assembler Operator / Machine Instruction:

tblrdh

Error Messages

None.

__builtin_tblrdl

Description:

Issues the tblrdl.w instruction to read a word from Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __builtin_tbloffset() and__builtin_tblpage().

Please refer to the data sheet or "dsPIC30F Family Reference Manual" (DS70046) for complete details regarding reading and writing program Flash.

Prototype:

unsigned int __builtin_tblrdl(unsigned int offset);

Argument:

offsetdesired memory offset

Return Value:

None.

Assembler Operator / Machine Instruction:

tblrdl

Error Messages

None.

__builtin_tblwth

Description:

Issues the tblwth.w instruction to write a word to Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __builtin_tbloffset() and __builtin_tblpage().

Please refer to the data sheet or "dsPIC30F Family Reference Manual" (DS70046) for complete details regarding reading and writing program Flash.

Prototype:

void __builtin_tblwth(unsigned int offsetunsigned int data);

Argument:

offsetdesired memory offset

data data to be written

Return Value:

None.

Assembler Operator / Machine Instruction:

tblwth

Error Messages

None.

__builtin_tblwtl

Description:

Issues the tblrdl.w instruction to write a word to Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __builtin_tbloffset() and __builtin_tblpage().

Please refer to the data sheet or "dsPIC30F Family Reference Manual" (DS70046) for complete details regarding reading and writing program Flash.

Prototype:

void __builtin_tblwtl(unsigned int offsetunsigned int data);

Argument:

offsetdesired memory offset

data data to be written

Return Value:

None.

Assembler Operator / Machine Instruction:

tblwtl

Error Messages

None.

__builtin_write_NVM

Description:

Enables the Flash for writing by issuing the correct unlock sequence and enabling the WRite bit of the NVMCON register.

Prototype:

void __builtin_write_NVM(void);

Argument:

None.

Return Value:

None.

Assembler Operator / Machine Instruction:

mov #0x55, Wn

mov Wn, _NVMKEY

mov #0xAA, Wn

mov Wn, _NVMKEY

bset _NVMCON, #15

nop

nop

Error Messages

None.

__builtin_write_RTCWEN

Description:

Used to write to the RTCC Timer by implementing the unlock sequence by writing the correct unlock values to NVMKEY and then setting the RTCWREN bit of RCFGCAL SFR.

Prototype:

void __builtin_write_RTCWEN(void);

Argument:

None.

Return Value:

None.

Assembler Operator / Machine Instruction:

mov #0x55, Wn

mov Wn, _NVMKEY

mov #0xAA, Wn

mov Wn, _NVMKEY

bset _NVMCON, #15

nop

nop

Error Messages

None.

__builtin_write_OSCCONL

Description:

Unlocks and writes its argument to OSCCONL.

Prototype:

void __builtin_write_OSCCONL(unsigned char value);

Argument:

valuecharacter to be written

Return Value:

None.

Assembler Operator / Machine Instruction*:

mov #0x46, w0

mov #0x57, w1

mov __OSCCON, w2

mov.b w0, [w2]

mov.b w1, [w2]

mov.b value, [w2]

Error Messages

None.

* The exact sequence may be different.

__builtin_write_OSCCONH

Description:

Unlocks and writes its argument to OSCCONH.

Prototype:

void __builtin_write_OSCCONH(unsigned char value);

Argument:

valuecharacter to be written

Return Value:

None.

Assembler Operator / Machine Instruction*:

mov #0x78, w0

mov #0x9A, w1

mov __OSCCON+1, w2

mov.b w0, [w2]

mov.b w1, [w2]

mov.b value, [w2]

Error Messages

None.

* The exact sequence may be different.

__builtin_addab
Description:	Add 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`
Prototype:	`int` __`builtin_addab(int Accum_a, int Accum_b);`
Argument:	`Accum_a` First accumulator to add. `Accum_b` Second accumulator to add.
Return Value:	Returns the addition result to an accumulator.
Assembler Operator / Machine Instruction:	`add`
Error Messages	An error message will be displayed if the result is not an accumulator register.

__builtin_add
Description:	`A`dd `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`
Prototype:	`int` __`builtin_add(int Accum,int` `value,` `const int` `shift);`
Argument:	`Accum` Accumulator to add. `value` Integer number to add to accumulator value. `shift` Amount to shift resultant accumulator value.
Return Value:	Returns the shifted addition result to an accumulator.
Assembler Operator / Machine Instruction:	`add`
Error Messages	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

__builtin_btg
Description:	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 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.
Prototype:	`void` __`builtin_btg(unsigned int *, unsigned int 0xn);`
Argument:	`*` A pointer to the data item for which a bit should be toggled. 0x`n` A literal value in the range of 0 to 15.
Return Value:	Returns a btg machine instruction.
Assembler Operator / Machine Instruction:	`btg`
Error Messages	An error message will be displayed if the parameter values are not within range

__builtin_clr
Description:	Clear the specified accumulator. For example: `register int result asm("A");` `result =` __`builtin_clr();` will generate: `clr A`
Prototype:	`int` __`builtin_clr(void);`
Argument:	None
Return Value:	Returns the cleared value result to an accumulator.
Assembler Operator / Machine Instruction:	`clr`
Error Messages	An error message will be displayed if the result is not an accumulator register.

__builtin_clr_prefetch
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. For example: `register int result asm("A");` `register int B asm("B");` `int x_memory_buffer[256]` __`attribute`__`((space(xmemory)));` `int y_memory_buffer[256]` __`attribute`__`((space(ymemory)));` `int xmemory;` `int ymemory;` `int awb;` `int xVal, yVal;` `xmemory = x_memory_buffer;` `ymemory = y_memory_buffer;` `result =` __`builtin_clr(&xmemory, &xVal, 2,` `&ymemory, &yVal, 2, &awb, B);` might generate: `clr A, [w8]+=2, w4, [w10]+=2, w5, w13` 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. 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
Prototype:	`int` __`builtin_clr_prefetch(` `int *xptr, int xval, int` `xincr,` `int *yptr, int yval, int` `yincr, int *AWB,` `int` `AWB_accum);`
Argument:	`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. `AWB_accum` Accumulator to write back.
Return Value:	Returns the cleared value result to an accumulator.
Assembler Operator / Machine Instruction:	`clr`
Error Messages	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_accum is not an accumulator and AWB is not null

__builtin_divf
Description:	Computes the quotient `num` / `den`. A math error exception occurs if `den` is zero. Function arguments are unsigned, as is the function result.
Prototype:	`unsigned int` __`builtin_divf(unsigned int` `num,` `unsigned int` `den);`
Argument:	`num` numerator `den` denominator
Return Value:	Returns the unsigned integer value of the quotient `num` / `den`.
Assembler Operator / Machine Instruction:	`div.f`

__builtin_divmodsd
Description:	Issues the 16-bit architecture's native signed divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.
Prototype:	`signed int` __`builtin_divmodsd( signed long` `dividend, signed int` `divisor, signed int *remainder);`
Argument:	`dividend` number to be divided `divisor` number to divide by `remainder` pointer to remainder
Return Value:	Quotient and remainder.
Assembler Operator / Machine Instruction:	`divmodsd`
Error Messages	None.

__builtin_divmodud
Description:	Issues the 16-bit architecture's native unsigned divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.
Prototype:	`unsigned int` __`builtin_divmodud( unsigned long` `dividend, unsigned int` `divisor, unsigned int *remainder);`
Argument:	`dividend` number to be divided `divisor` number to divide by `remainder` pointer to remainder
Return Value:	Quotient and remainder.
Assembler Operator / Machine Instruction:	`divmodud`
Error Messages	None.

__builtin_divsd
Description:	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.
Prototype:	`int` __`builtin_divsd(const long` `num, const int` `den);`
Argument:	`num` numerator `den` denominator
Return Value:	Returns the signed integer value of the quotient `num` / `den`.
Assembler Operator / Machine Instruction:	`div.sd`

__builtin_divud
Description:	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.
Prototype:	`unsigned int` __`builtin_divud(const unsigned long` `num, const unsigned int` `den);`
Argument:	`num` numerator `den` denominator
Return Value:	Returns the unsigned integer value of the quotient `num` / `den`.
Assembler Operator / Machine Instruction:	`div.ud`

__builtin_dmaoffset
Description:	Obtains the offset of a symbol within DMA memory. For example: `unsigned int result;` `char buffer[256]` __`attribute`__`((space(dma)));` `result =` __`builtin_dmaoffset(&buffer);` Might generate: `mov #dmaoffset(buffer), w0`
Prototype:	`unsigned int` __`builtin_dmaoffset(const void` `*p);`
Argument:	`*p` pointer to DMA address value
Return Value:	Returns the offset to a variable located in DMA memory.
Assembler Operator / Machine Instruction:	`dmaoffset`
Error Messages	An error message will be displayed if the parameter is not the address of a global symbol.

__builtin_ed
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. For example: `register int result asm("A");` `int xmemory, ymemory;` `int distance;` `result =` __`builtin_ed(distance,` `&xmemory, 2,` `&ymemory, 2,` `&distance);` might generate: `ed w4w4, A, [w8]+=2, [W10]+=2, w4`
Prototype:	`int` __`builtin_ed(int` `sqr, int xptr, int` `xincr,` `int yptr, int` `yincr, int *distance);`
Argument:	`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.
Return Value:	Returns the squared result to an accumulator.
Assembler Operator / Machine Instruction:	`ed`
Error Messages	An error message will be displayed if: the result is not an accumulator register `xptr` is null `yptr` is null `distance` is null

__builtin_edac
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. For example: `register int result asm("A");` `int xmemory, ymemory;` `int distance;` `result =` __`builtin_ed(result,` `distance,` `&xmemory, 2,` `&ymemory, 2,` `&distance);` might generate: `edac` `w4w4, A, [w8]+=2, [W10]+=2, w4`
Prototype:	`int` __`builtin_edac(int` `Accum, int` `sqr,` `int xptr, int` `xincr, int yptr, int` `yincr,` `int *distance);`
Argument:	`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.
Return Value:	Returns the squared result to specified accumulator.
Assembler Operator / Machine Instruction:	`edac`
Error Messages	An error message will be displayed if: the result is not an accumulator register Accum is not an accumulator register `xptr` is null `yptr` is null `distance` is null

__builtin_fbcl
Description:	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);` might generate: `fbcl w4, w5`
Prototype:	`int` __`builtin_fbcl(int` `value);`
Argument:	`value` Integer number of first bit change.
Return Value:	Returns the shifted addition result to an accumulator.
Assembler Operator / Machine Instruction:	`fbcl`
Error Messages	An error message will be displayed if the result is not an accumulator register.

__builtin_lac
Description:	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);` Might generate: `lac w4, #3, A`
Prototype:	`int` __`builtin_lac(int` `value, int` `shift);`
Argument:	`value` Integer number to be shifted. `shift` Literal amount to shift.
Return Value:	Returns the shifted addition result to an accumulator.
Assembler Operator / Machine Instruction:	`lac`
Error Messages	An error message will be displayed if: the result is not an accumulator register the shift value is not a literal within range

__builtin_mac
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. 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);` might generate: `mac w4*w5, A, [w8]+=2, w4, [w10]+=2, w5`
Prototype:	`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);`
Argument:	`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.
Return Value:	Returns the cleared value result to an accumulator.
Assembler Operator / Machine Instruction:	`mac`
Error Messages	An error message will be displayed 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

__builtin_modsd
Description:	Issues the 16-bit architecture's native signed divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.
Prototype:	`signed int` __`builtin_modsd(signed long` `dividend, signed int` `divisor);`
Argument:	`dividend` number to be divided `divisor` number to divide by
Return Value:	Remainder.
Assembler Operator / Machine Instruction:	`modsd`
Error Messages	None.

__builtin_modud
Description:	Issues the 16-bit architecture's native unsigned divide support with the same restrictions given in the "dsPIC30F/33FProgrammer's Reference Manual" (DS70157). 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.
Prototype:	`unsigned int` __`builtin_modud(unsigned long` `dividend, unsigned int` `divisor);`
Argument:	`dividend` number to be divided `divisor` number to divide by
Return Value:	Remainder.
Assembler Operator / Machine Instruction:	`modud`
Error Messages	None.

__builtin_movsac
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. For example: `register int result asm("A");` `int xmemory;` `int ymemory;` `int xVal, yVal;` `result =` __`builtin_movsac(&xmemory, &xVal, 2,` `&ymemory, &yVal, 2, 0, 0);` might generate: `movsac A, [w8]+=2, w4, [w10]+=2, w5`
Prototype:	`int` __`builtin_movsac(` `int *xptr, int xval, int` `xincr,` `int *yptr, int yval, int` `yincr, int *AWB` `int` `AWB_accum);`
Argument:	`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.
Return Value:	Returns prefetch data.
Assembler Operator / Machine Instruction:	`movsac`
Error Messages	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_accum is not an accumulator register and AWB is not null

__builtin_mpy
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. 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);` might generate: `mac w4*w5, A, [w8]+=2, w4, [w10]+=2, w5`
Prototype:	`int` __`builtin_mpy(int` `a, int` `b,` `int *xptr, int xval, int` `xincr,` `int *yptr, int yval, int` `yincr);`
Argument:	`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.
Return Value:	Returns the cleared value result to an accumulator.
Assembler Operator / Machine Instruction:	`mpy`
Error Messages	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

__builtin_mpyn
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. 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);` might generate: `mac w4*w5, A, [w8]+=2, w4, [w10]+=2, w5`
Prototype:	`int` __`builtin_mpyn(int` `a, int` `b,` `int *xptr, int xval, int` `xincr,` `int *yptr, int yval, int` `yincr);`
Argument:	`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.
Return Value:	Returns the cleared value result to an accumulator.
Assembler Operator / Machine Instruction:	`mpyn`
Error Messages	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

__builtin_msc
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. 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);` might generate: `msc w4*w5, A, [w8]+=2, w4, [w10]+=2, w5`
Prototype:	`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);`
Argument:	`Accum`IAccumulator 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.
Return Value:	Returns the cleared value result to an accumulator.
Assembler Operator / Machine Instruction:	`msc`
Error Messages	An error message will be displayed 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

__builtin_mulss
Description:	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.
Prototype:	`signed long` __`builtin_mulss(const signed int` `p0, const signed int` `p1);`
Argument:	`p0`multiplicand `p1` multiplier
Return Value:	Returns the signed long integer value of the product `p0` x `p1`.
Assembler Operator / Machine Instruction:	`mul.ss`

__builtin_mulsu
Description:	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`.
Prototype:	`signed long` __`builtin_mulsu(const signed int` `p0, const unsigned int` `p1);`
Argument:	`p0`multiplicand `p1` multiplier
Return Value:	Returns the signed long integer value of the product `p0` x `p1`.
Assembler Operator / Machine Instruction:	`mul.su`

__builtin_mulus
Description:	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.
Prototype:	`signed long` __`builtin_mulus(const unsigned int` `p0, const signed int` `p1);`
Argument:	`p0`multiplicand `p1` multiplier
Return Value:	Returns the signed long integer value of the product `p0` x `p1`.
Assembler Operator / Machine Instruction:	`mul.us`

__builtin_muluu
Description:	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`.
Prototype:	`unsigned long` __`builtin_muluu(const unsigned int` `p0, const unsigned int` `p1);`
Argument:	`p0`multiplicand `p1` multiplier
Return Value:	Returns the signed long integer value of the product `p0` x `p1`.
Assembler Operator / Machine Instruction:	`mul.uu`

__builtin_nop
Description:	Generates a `nop` instruction.
Prototype:	`void` __`builtin_nop(void);`
Argument:	None.
Return Value:	Returns a no operation (`nop`).
Assembler Operator / Machine Instruction:	`nop`

__builtin_psvpage
Description:	Returns the psv page number of the object whose address is given as a parameter. The argument `p` must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the `space`attribute in Section 2.3.1 "Specifying Attributes of Variables".
Prototype:	`unsigned int` __`builtin_psvpage(const void *p);`
Argument:	`p`object address
Return Value:	Returns the psv page number of the object whose address is given as a parameter.
Assembler Operator / Machine Instruction:	`psvpage`
Error Messages	The following error message is produced when this function is used incorrectly: "Argument to __`builtin_psvpage()` is not the address of an object in code, psv, or eedata section". The argument must be an explicit object address. For example, if `obj` is object in an executable or read-only section, the following syntax is valid: `unsigned page =` __`builtin_psvpage(&obj);`

__builtin_psvoffset
Description:	Returns the psv page offset of the object whose address is given as a parameter. The argument `p` must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the `space`attribute in Section 2.3.1 "Specifying Attributes of Variables".
Prototype:	`unsigned int` __`builtin_psvoffset(const void *p);`
Argument:	`p`object address
Return Value:	Returns the psv page number offset of the object whose address is given as a parameter.
Assembler Operator / Machine Instruction:	`psvoffset`
Error Messages	The following error message is produced when this function is used incorrectly: "Argument to __`builtin_psvoffset()` is not the address of an object in code, psv, or eedata section". The argument must be an explicit object address. For example, if `obj` is object in an executable or read-only section, the following syntax is valid: `unsigned page =` __`builtin_psvoffset(&obj);`

__builtin_readsfr
Description:	Reads the SFR.
Prototype:	`unsigned int` __`builtin_readsfr(const void *p);`
Argument:	`p`object address
Return Value:	Returns the SFR.
Assembler Operator / Machine Instruction:	`readsfr`
Error Messages	The following error message is produced when this function is used incorrectly:

__builtin_return_address
Description:	Returns the return address of the current function, or of one of its callers. For the `level`argument, a value of 0 yields the return address of the current function, a value of 1 yields the return address of the caller of the current function, and so forth. When level exceeds the current stack depth, 0 will be returned. This function should only be used with a non-zero argument for debugging purposes.
Prototype:	`int` __`builtin_return_address (const int` `level);`
Argument:	`level`Number of frames to scan up the call stack.
Return Value:	Returns the return address of the current function, or of one of its callers.
Assembler Operator / Machine Instruction:	`return_address`

__builtin_sac
Description:	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);` Might generate: `sac A, #3, w0`
Prototype:	`int` __`builtin_sac(int` `value, int` `shift);`
Argument:	`value`Integer number to be shifted. `shift`Literal amount to shift.
Return Value:	Returns the shifted result to an accumulator.
Assembler Operator / Machine Instruction:	`sac`
Error Messages	An error message will be displayed if: the result is not an accumulator register the shift value is not a literal within range

__builtin_sacr
Description:	Shifts value by `shift` (a literal between -8 and 7) and returns the value which is rounded using the rounding mode determined by the CORCONbits.RND control bit. For example: `register int value asm("A");` `int result;` `result =` __`builtin_sac(value,3);` Might generate: `sac.r A, #3, w0`
Prototype:	`int` __`builtin_sacr(int` `value, int` `shift);`
Argument:	`value`Integer number to be shifted. `shift`Literal amount to shift.
Return Value:	Returns the shifted result to CORCON register.
Assembler Operator / Machine Instruction:	`sacr`
Error Messages	An error message will be displayed if: the result is not an accumulator register the shift value is not a literal within range

__builtin_sftac
Description:	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);` Might generate: `sftac A, w0`
Prototype:	`int` __`builtin_sftac(int` `Accum, int` `shift);`
Argument:	`Accum` Accumulator to shift. `shift`Amount to shift.
Return Value:	Returns the shifted result to an accumulator.
Assembler Operator / Machine Instruction:	`sftac`
Error Messages	An error message will be displayed if: the result is not an accumulator register Accum is not an accumulator register the shift value is not a literal within range

__builtin_subab
Description:	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`
Prototype:	`int` __`builtin_subab(int` `Accum_a, int` `Accum_b);`
Argument:	`Accum`_a Accumulator from which to subtract. `Accum_b`Accumulator to subtract.
Return Value:	Returns the subtraction result to an accumulator.
Assembler Operator / Machine Instruction:	`sub`
Error Messages	An error message will be displayed if the result is not an accumulator register.

__builtin_tbladdress
Description:	Returns a value that represents the address of an object in program memory. The argument`p` must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the `space` attribute in Section 2.3.1 "Specifying Attributes of Variables".
Prototype:	`unsigned` `long` __`builtin_tblpage(const void *p);`
Argument:	`p`object address
Return Value:	Returns an `unsigned long` value that represents the address of an object in program memory.
Assembler Operator / Machine Instruction:	`tbladdress`
Error Messages	The following error message is produced when this function is used incorrectly: "Argument to __`builtin_tbladdress()` is not the address of an object in code, psv, or eedata section". The argument must be an explicit object address. For example, if `obj` is object in an executable or read-only section, the following syntax is valid: `unsigned` `long` `page =` __`builtin_tbladdress(&obj);`

__builtin_tblpage
Description:	Returns the table page number of the object whose address is given as a parameter. The argument `p` must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the `space`attribute in Section 2.3.1 "Specifying Attributes of Variables".
Prototype:	`unsigned int` __`builtin_tblpage(const void *p);`
Argument:	`p`object address
Return Value:	Returns the table page number of the object whose address is given as a parameter.
Assembler Operator / Machine Instruction:	`tblpage`
Error Messages	The following error message is produced when this function is used incorrectly: "Argument to __`builtin_tblpage()` is not the address of an object in code, psv, or eedata section". The argument must be an explicit object address. For example, if `obj` is object in an executable or read-only section, the following syntax is valid: `unsigned page =` __`builtin_tblpage(&obj);`

__builtin_tbloffset
Description:	Returns the table page offset of the object whose address is given as a parameter. The argument `p` must be the address of an object in an EE data, PSV or executable memory space; otherwise an error message is produced and the compilation fails. See the `space`attribute in Section 2.3.1 "Specifying Attributes of Variables".
Prototype:	`unsigned int` __`builtin_tbloffset(const void *p);`
Argument:	`p`object address
Return Value:	Returns the table page number offset of the object whose address is given as a parameter.
Assembler Operator / Machine Instruction:	`tbloffset`
Error Messages	The following error message is produced when this function is used incorrectly: "Argument to __`builtin_tbloffset()` is not the address of an object in code, psv, or eedata section". The argument must be an explicit object address. For example, if `obj` is object in an executable or read-only section, the following syntax is valid: `unsigned page =` __`builtin_tbloffset(&obj);`

__builtin_tblrdh
Description:	Issues the `tblrdh.w` instruction to read a word from Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __`builtin_tbloffset()` and __`builtin_tblpage()`. Please refer to the data sheet or dsPIC Family Reference Manual for complete details regarding reading and writing program Flash.
Prototype:	`unsigned int` __`builtin_tblrdh(unsigned int` `offset);`
Argument:	`offset`desired memory offset
Return Value:	None.
Assembler Operator / Machine Instruction:	`tblrdh`
Error Messages	None.

__builtin_tblrdl
Description:	Issues the `tblrdl.w` instruction to read a word from Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __`builtin_tbloffset()` and__`builtin_tblpage()`. Please refer to the data sheet or "dsPIC30F Family Reference Manual" (DS70046) for complete details regarding reading and writing program Flash.
Prototype:	`unsigned int` __`builtin_tblrdl(unsigned int` `offset);`
Argument:	`offset`desired memory offset
Return Value:	None.
Assembler Operator / Machine Instruction:	`tblrdl`
Error Messages	None.

__builtin_tblwth
Description:	Issues the `tblwth.w` instruction to write a word to Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __`builtin_tbloffset()` and __`builtin_tblpage()`. Please refer to the data sheet or "dsPIC30F Family Reference Manual" (DS70046) for complete details regarding reading and writing program Flash.
Prototype:	`void` __`builtin_tblwth(unsigned int` `offsetunsigned int` `data);`
Argument:	`offset`desired memory offset `data` data to be written
Return Value:	None.
Assembler Operator / Machine Instruction:	`tblwth`
Error Messages	None.

__builtin_tblwtl
Description:	Issues the `tblrdl.w` instruction to write a word to Flash or EEDATA memory. You must set up the TBLPAG to point to the appropriate page. To do this, you may make use of __`builtin_tbloffset()` and __`builtin_tblpage()`. Please refer to the data sheet or "dsPIC30F Family Reference Manual" (DS70046) for complete details regarding reading and writing program Flash.
Prototype:	`void` __`builtin_tblwtl(unsigned int` `offsetunsigned int` `data);`
Argument:	`offset`desired memory offset `data` data to be written
Return Value:	None.
Assembler Operator / Machine Instruction:	`tblwtl`
Error Messages	None.

__builtin_write_NVM
Description:	Enables the Flash for writing by issuing the correct unlock sequence and enabling the WRite bit of the NVMCON register.
Prototype:	`void` __`builtin_write_NVM(void);`
Argument:	None.
Return Value:	None.
Assembler Operator / Machine Instruction:	`mov #0x55,` Wn `mov` Wn`, _NVMKEY` `mov #0xAA,` Wn `mov` Wn`, _NVMKEY` `bset _NVMCON, #15` `nop` `nop`
Error Messages	None.

__builtin_write_RTCWEN
Description:	Used to write to the RTCC Timer by implementing the unlock sequence by writing the correct unlock values to `NVMKEY` and then setting the `RTCWREN` bit of RCFGCAL SFR.
Prototype:	`void` __`builtin_write_RTCWEN(void);`
Argument:	None.
Return Value:	None.
Assembler Operator / Machine Instruction:	`mov #0x55,` Wn `mov` Wn`, _NVMKEY` `mov #0xAA,` Wn `mov` Wn`, _NVMKEY` `bset _NVMCON,` `#15` `nop` `nop`
Error Messages	None.

__builtin_write_OSCCONL
Description:	Unlocks and writes its argument to OSCCONL.
Prototype:	`void` __`builtin_write_OSCCONL(unsigned char` `value);`
Argument:	`value`character to be written
Return Value:	None.
Assembler Operator / Machine Instruction*:	`mov #0x46, w0` `mov #0x57, w1` `mov` `__OSCCON, w2` `mov.b w0, [w2]` `mov.b w1, [w2]` `mov.b` value`, [w2]`
Error Messages	None.
* The exact sequence may be different.

__builtin_write_OSCCONH
Description:	Unlocks and writes its argument to OSCCONH.
Prototype:	`void` __`builtin_write_OSCCONH(unsigned char` `value);`
Argument:	`value`character to be written
Return Value:	None.
Assembler Operator / Machine Instruction*:	`mov #0x78, w0` `mov #0x9A, w1` `mov` `__OSCCON+1, w2` `mov.b w0, [w2]` `mov.b w1, [w2]` `mov.b` value`, [w2]`
Error Messages	None.
* The exact sequence may be different.