========================
The resources access API
========================

The whole resource access API is defined in :file:`srl.h`. Task code
should include it:

.. code-block:: c

   #include <srl.h>

.. _capi-GET_ARG:

Retrieving resources associated to ports
========================================


.. todo::

   GET_ARG

.. _capi-mwmr:

MWMR channels
=============

.. c:type:: srl_mwmr_t

   Abstract type for a :ref:`concept-mwmr`

.. c:function:: void srl_mwmr_read(srl_mwmr_t channel, void *buffer, size_t size)

   Reads from an MWMR channel to the given buffer. Block the task
   until the whole transfer is completed.

   :param channel: the MWMR channel where to make transfer
   :param buffer: Buffer's base address to copy data into
   :param size: Size of transfer in bytes. This must be a multiple of
                the channel's width.

.. c:function:: void srl_mwmr_write(srl_mwmr_t channel, const void *buffer, size_t size)

   Writes to an MWMR channel to the given buffer. Block the task until
   the whole transfer is completed.

   :param channel: the MWMR channel where to make transfer
   :param buffer: Buffer's base address to copy data from
   :param size: Size of transfer in bytes. This must be a multiple of
                the channel's width.

.. c:function:: size_t srl_mwmr_try_read(srl_mwmr_t channel, void *buffer, size_t size)

   Reads from an MWMR channel to the given buffer. Returns as soon as
   a blocking could occur.

   :param channel: the MWMR channel where to make transfer
   :param buffer: Buffer's base address to copy data into
   :param size: Size of transfer in bytes. This must be a multiple of
                the channel's width.
   :returns: The actual size transfered, in bytes.

.. c:function:: size_t srl_mwmr_try_write(srl_mwmr_t channel, const void *buffer, size_t size)

   Writes to an MWMR channel to the given buffer. Returns as soon as a
   blocking could occur.

   :param channel: the MWMR channel where to make transfer
   :param buffer: Buffer's base address to copy data from
   :param size: Size of transfer in bytes. This must be a multiple of
                the channel's width.
   :returns: The actual size transfered, in bytes.

.. c:function:: void srl_mwmr_config(void *coproc, size_t no, uint32_t value)

   Writes a *config* register of an MWMR controller.

   :param coproc: Controller base address
   :param no: Configuration register number
   :param value: Value to put in configuration register

.. c:function:: uint32_t srl_mwmr_status(void *coproc, size_t no)

   Reads a *status* register of an MWMR controller.

   :param coproc: Controller base address
   :param no: Configuration register number
   :returns: the value present is status register

.. _capi-barrier:

Barriers
========

.. c:type:: srl_barrier_t

   Abstract type for a :ref:`concept-barrier`

.. c:function:: void srl_barrier_wait(srl_barrier_t barrier)

   Waits until all tasks registered on the barrier have called this
   function.

   :param barrier: barrier to wait on

.. c:function:: void srl_barrier_reset(srl_barrier_t barrier)

   Resets the internal state of the barrier. If tasks are waiting on
   the same barrier at time of call, application behavior is
   undefined.

   :param barrier: barrier to reset

.. _capi-memspace:

Memspaces
=========

.. c:type:: srl_memspace_t

   Abstract type for a :ref:`concept-memspace`

.. c:function:: void *SRL_MEMSPACE_ADDR(srl_memspace_t memspace)

   Retrieves the base address of a memspace

   :param memspace: a memspace
   :returns: The memspace base address

.. c:function:: size_t SRL_MEMSPACE_SIZE(srl_memspace_t memspace)

   Retrieves the size of a memspace

   :param memspace: a memspace
   :returns: The memspace size, in bytes

.. _capi-lock:

Locks
=====

.. c:type:: srl_lock_t

   Abstract type for a :ref:`concept-lock`

.. c:function:: void srl_lock_lock(srl_lock_t lock)

   Waits until the lock is taken exclusively.

   :param lock: lock to wait on

.. c:function:: void srl_lock_unlock(srl_lock_t lock)

   Releases the taken lock. If a task releases a lock it does not own,
   application behavior is undefined.

   :param lock: lock to release

.. c:function:: void srl_lock_try_lock(srl_lock_t lock)

   Try to take a lock, if it would block, don't take it and return
   immediately.

   :param lock: lock to take
   :returns: 0 if taken successfully, non-0 otherwise