.. _capi-control:

==================
 The control APIs
==================

Time control
============

.. c:function:: void srl_sleep_cycles(int n)

   Waits at least ``n`` cycles pass. Calling task may be unscheduled
   meanwhile.

   :param n: Number of cycles


.. c:function:: void srl_busy_cycles(int n)

   Waits ``n`` cycles pass in the hardware.

   :param n: Number of cycles

   When using a software implementation of a task for hardware
   coprocessor evaluation, some timing accuracy tweaks may be useful.

   Purpose of this call is to simulate the latency of an hardware
   coprocessor latency from the software task's code. When running as
   a SyntheticTask, all computation is done with no latency.

Condition waiting API
=====================

Sometimes, tasks have to poll from an hardware register until it has
some defined condition satisfied. Here are some calls to implement
such polling.  When using these calls, tasks may be unscheduled until
the condition is satisfied.

.. c:function:: void srl_sched_wait_COMP_ENDIANNESS(uint32_t *addr, int32_t val)

   This function exists with different values of ``COMP`` and
   ``ENDIANNESS``.

   ``COMP`` is in ``eq`` (``==``), ``ne`` (``!=``), ``le`` (``<=``),
   ``gt`` (``>``), ``lt`` (``<``), or ``ge`` (``>=``).

   ``ENDIANNESS`` is in ``be`` (big endian), ``le`` (little endian),
   or ``cpu`` (natural CPU endianness).

   This waits until ``*addr COMP val`` is true, fetching ``addr`` with
   the given endianness.

   :param addr: An address to fetch data from
   :param val: Value to compare to

   Example: ``srl_sched_wait_lt_be(addr, val)`` waits unitl the
   big-endian value pointed by ``addr`` is less than the constant
   passed in ``val``.

.. c:type:: srl_callback_t

   .. c:function:: int8_t srl_callback_t(uint32_t val)

      :param val: a passed value
      :returns: a boolean (0 is false)

.. c:function:: void srl_sched_wait_priv(srl_callback_t *cb, uint32_t val)

   This waits until callback returns true.

   :param cb: A callback function
   :param val: A value to pass to the callback function

Cache flush API
===============

When dealing with SoC memory system, which is sometimes non-coherent,
a cache control API may be useful. Here are the calls:

.. c:function:: void srl_dcache_flush_addr(void *addr)

   Removes the pointed data from the processor's cache, if present.

   :param addr: An address.

.. c:function:: void srl_dcache_flush_zone(void *addr, size_t size)

   Removes all the lines matching the memory zone from processor's
   cache.

   :param addr: An address.
   :param size: A size (in bytes)

Simulation control
==================

.. c:function:: void srl_abort()

   Stops the execution as soon as possible. This is not guaranteed to
   succeed, as it sometimes makes no sense.

   On simulated platforms, this may exit the simulator.