

.. index:: intrinsic functions, built-in functions
.. index:: functions, intrinsic, functions, built-in

.. _intrinsic-functions:

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

Intrinsic functions reference
=============================

The ``calypsi/intrinsics65816.h`` file appears as follows:

.. literalinclude:: ../../../../lib/target/WDC65816/include/calypsi/intrinsics65816.h
   :language: C


Summary of intrinsic functions
------------------------------

.. table:: Intrinsic functions summary
 :widths: 2 3
 :column-dividers: none single none
 :column-alignment: left left

 +-------------------------------+------------------------------------------------+
 |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:

.. code-block:: C

   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.
