Miscellaneous built-ins

Prototype Description
void __alignx(int alignment, const void *address); Informs the compiler that the specified address is aligned at a known compile-time offset. Alignment must be a positive constant integer with a value greater than zero and of a power of two.
void __builtin_return_address (unsigned int level); Returns the return address of the current function, or of one of its callers. Where level argument is a constant literal indicating the number of frames to scan up the call stack. The level must range from 0 to 63. 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 on.
Notes:
  1. When the top of the stack is reached, the function will return 0.
  2. The level must range from 0 to 63, otherwise a warning message will be issued and the compilation will halt.
  3. When functions are inlined, the return address corresponds to that of the function that is returned to.
  4. Compiler optimization may affect expected return value due to introducing extra stack frames or fewer stack frames than expected due to optimizations such as inlining.
void __builtin_frame_address (unsigned int level); Returns the address of the function frame of the current function, or of one of its callers. Where level argument is a constant literal indicating the number of frames to scan up the call stack. The level must range from 0 to 63. A value of 0 yields the return the frame address of the current function, a value of 1 yields the return the frame address of the caller of the current function and so on.
Notes:
  1. When the top of the stack is reached, the function will return 0.
  2. The level must range from 0 to 63, otherwise a warning message will be issued and the compilation will halt.
  3. When functions are inlined, the frame address corresponds to that of the function that is returned to.
  4. Compiler optimization may affect expected return value due to introducing extra stack frames or fewer stack frames than expected due to optimizations such as inlining.
unsigned long __mftb(); Generates a Move From Time Base (__mftb) hardware instruction.

In 32-bit compilation mode, the hardware instruction returns the lower word of the time base register, and can be used in conjunction with the__mftbu built-in function to read the entire time base register. In 64-bit mode, the mftb instruction returns the entire double word time base register.

Note:
It is recommended that you insert __fence built-in function before and after the __mftb built-in function.
unsigned int __mftbu(); Generates a Move From Time Base Upper (mftbu) hardware instruction.

In 32-bit compilation mode, the hardware instruction returns the upper word of the time base register, and can be used in conjunction with the mftb instruction to read the entire time base register. In 64-bit mode, the mftb instruction returns the entire double word time base register, therefore separate use of mftbu is unnecessary.

Notes:
  1. It is not recommended to use __mftbu as __mftb returns the entire 64-bits of the time base.
  2. It is recommended that you insert __fence built-in function before and after the __mftbu built-in function.
unsigned long __mfdcr (signed int); Moves the contents of the designated Device Control Register into the designated GPR.
unsigned long __mfmsr (void); Moves the contents of the MSR into bits 32:63 of the designated GPR. Execution of this instruction is privileged and restricted to supervisor mode only.
unsigned __mfspr(const int registerNumber); Returns the value of given special purpose register registerNumber. The registerNumber must be known at compile time.
void __mtdcr (signed int, unsigned long); Moves the contents of the designated GPR into the designated Device Control Register. Execution of this instruction is privileged and restricted to supervisor mode only.
void __mtmsr (unsigned long); Moves the contents of bits 32:63 of the designated GPR into the MSR. Execution of this instruction is privileged and restricted to supervisor mode only.
void __mtspr(const int registerNumber, unsigned long value); Sets the value of special purpose register registerNumber with unsigned long value. Both values must be known at compile time.
float __nanf (const char*); Converts a constant character to a float value to signal a quiet Not-a-number (Nan)
double __nans (const char*); Converts a constant character into a double value to signal Not-a-number (Nan)
float __nansf (const char*); Converts a constant character into a float value to signal Not-a-number (Nan)
int __stdcx(volatile long* addr, long val); Generates a Store Double Word Conditional Indexed (stdcx.) instruction.

This instruction can be used in conjunction with a preceding ldarx instruction to implement a read-modify-write on a specified memory location. The memory location that is taken as the input parameter addr must be 8-byte aligned. The ldarxand stwcx.' instructions work together to ensure that if the store is successfully performed, no other processor or mechanism has modified the target double word between the time the ldarx instruction is executed and the time the stdcx. instruction completes. The __stdcx built-in function returns 1 if the stwcx. instruction is successful in updating the specified memory location, and 0 if it is unsuccessful. This built-in function ensures that no other instructions are reordered with the generated stwcx. instruction by the compiler. This has the same effect as inserting __fence built-in functions before and after the __stdcx built-in function and can inhibit compiler optimization of surrounding code.

int __stwcx(volatile int* addr, int val); Generates a Store Word Conditional Indexed (stwcx.) instruction.

This instruction can be used in conjunction with a preceding lwarx instruction to implement a read-modify-write on a specified memory location. The memory location that is taken as the input parameter addr must be 4-byte aligned. The lwarx and stwcx. instructions work together to ensure that if the store is successfully performed, no other processor or mechanism has modified the target single word between the time the lwarx instruction is executed and the time the stwcx. instruction completes. The __stwcx built-in function returns 1 if the stwcx. instruction is successful in updating the specified memory location, and 0 if it is unsuccessful. This built-in function ensures that no other instructions are reordered with the generated stwcx. instruction by the compiler and has the same effect as inserting __fence built-in functions before and after the __stwcx built-in function and can inhibit compiler optimization of surrounding code.