15. Intrinsic functions

This chapter covers predefined intrinsic and built-in functions.

Intrinsics functions appear as ordinary calls but are special compiler constructs, emitting specific instruction sequences. To enable them, include the calypsi/intrinsics68000.h header file.

Built-in functions are similar, but they are not declared in calypsi/intrinsics68000.h.

15.1. Intrinsic functions reference

The calypsi/intrinsics68000.h file appears as follows:

/****************************************************************************
 *
 * Copyright Håkan Thörngren
 *
 * This file is part of the Calypsi C library.
 * Permission to use with the Calypsi tool chain is hereby granted.
 *
 ****************************************************************************/

#ifndef __INTRINSICS_68000_H
#define __INTRINSICS_68000_H

#ifdef __CALYPSI_TARGET_68000__

typedef unsigned short __interrupt_state_t;
typedef void (*__return_address_t)(void);

__attribute__((intrinsic)) void __disable_interrupts(void);
__attribute__((intrinsic)) void __enable_interrupts(void);
__attribute__((intrinsic)) __interrupt_state_t __get_interrupt_state(void);
__attribute__((intrinsic)) void __restore_interrupt_state(__interrupt_state_t);

__attribute__((intrinsic)) __return_address_t __get_return_address(void);
__attribute__((intrinsic)) void __set_return_address(__return_address_t);

__attribute__((intrinsic)) void __stop_processor(__interrupt_state_t);
__attribute__((intrinsic)) void __reset_processor(void);
__attribute__((intrinsic)) void __break_instruction(unsigned char);

#endif // __CALYPSI_TARGET_68000__

#endif // __INTRINSICS_68000_H

Summary of intrinsic functions

Table 15.1 Intrinsic functions summary

Function name	Description
__disable_interrupts	Disable interrupts
__enable_interrupts	Enable interrupts
__get_interrupt_state	Get the current interrupt state
__restore_interrupt_state	Restore to a previous interrupt state
__get_return_address	Get the return address of the current function
__set_return_address	Alter the return address of current function
__break_instruction	Generate a BKPT instruction
__reset_processor	Generate a RESET instruction
__stop_processor	Stop the processor
__builtin_clz	Count leading zeroes in an int
__builtin_clzl	Count leading zeroes in a long
__builtin_clzll	Count leading zeroes in a long long
__builtin_signbit	Get the value of the sign bit

Description of intrinsic functions

This section details each intrinsic function.

__disable_interrupts

Emits a machine instruction that disables interrupts by setting the interrrupt level to 7.

Note

This can only be done in supervisor mode.

__enable_interrupts

Emits a machine instruction that enables interrupts by setting the interrrupt level to 0.

Note

This can only be done in supervisor mode.

__get_interrupt_state

Returns the current interrupt state as a value of type __interrupt_state_t. This can be used in the following way:

int global;

void safe_increment () {
  __interrupt_state_t state = __get_interrupt_state();
  __disable_interrupts;
  global++;
  __restore_interrupt_state(state);
}

In the example the current state of interrupts is obtained and saved in state. The code then ensures interrupts are disabled and then do the real work. Finally, the interrupt state is restored to what it was when the function was entered.

Note

This can only be done in supervisor mode.

__restore_interrupt_state

Restores to a previous interrupt state, see example above.

Note

This can only be done in supervisor mode.

__get_return_address

Reads the return address of the current function from its the stack frame.

__set_return_address

Replaces the return address of the current function with the address found in the argument of __set_return_address().

__break_instruction

Emits a machine instruction that causes a breakpoint exception. This takes a value between 0 and 7 which encodes one of the 8 available software breakpoints.

__reset_processor

Emits the RESET instruction which has the effect of generating a reset to all external devices. Execution continues with the next instruction.

Note

This can only be done in supervisor mode.

__stop_processor

Emits an STOP instruction which takes an argument that is the value to set the processor status register to. This stops execution until an interrupt of high enough priority is received.

Note

This can only be done in supervisor mode.

__builtin_clz

Count the number of leading zeroes in a provided int value. Returns an undefined result if input is zero.

__builtin_clzl

Count the number of leading zeroes in a provided long value. Returns an undefined result if input is zero.

__builtin_clzll

Count the number of leading zeroes in a provided long long value. Returns an undefined result if input is zero.

__builtin_signbit

Returns the value (0 or 1) of the signbit of its input.