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/intrinsics65816.h header file.

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

15.1. Intrinsic functions reference

The calypsi/intrinsics65816.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_65816_H
#define __INTRINSICS_65816_H

#ifdef __CALYPSI_TARGET_65816__

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

__attribute__((intrinsic)) void __disable_interrupts(void);
__attribute__((intrinsic)) void __enable_interrupts(void);
__attribute__((intrinsic)) void __break_instruction(void);
__attribute__((intrinsic)) void __break_with(unsigned char);
__attribute__((intrinsic)) void __coprocessor_with(unsigned char);
__attribute__((intrinsic)) void __no_operation(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 __set_return_address_low16(__return_address16_t);

__attribute__((intrinsic)) void __wait_for_interrupt(void);
__attribute__((intrinsic)) void __stop_processor(void);


#endif // __CALYPSI_TARGET_65816__

#endif // __INTRINSICS_65816_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 BRK instruction
__break_with	Generate a BRK instruction with an argument
__coprocessor_with	Generate a COP instruction with an argument
__no_operation	Generate a NOP instruction
__wait_for_interrupt	Wait for an interrupt
__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.

__enable_interrupts

Emits a machine instruction that enables interrupts.

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

__restore_interrupt_state

Restores to a previous interrupt state, see example above.

__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().

__no_operation

Emits a NOP machine instruction.

__break_instruction

Emits a machine instruction that causes a break exception.

__break_with

Emits a machine instruction that causes a break exception. This variant take an opcode argument for the second byte of the BRK instruction.

__coprocessor_with

Emits a COP machine instruction with its argument is the second byte of the COP instruction.

__wait_for_interrupt

Emits an instruction that causes the 65816 to wait until an interrupt is triggered. Execution resumes with the interrupt and then normal execution.

__stop_processor

Emits an instruction that causes the 65816 to halt execution.

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