

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

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

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

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

.. literalinclude:: ../../../../lib/target/68k/include/calypsi/intrinsics68000.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 ``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:

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

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