.. -*- rst -*-

.. _desc-mapping:

=======================
Mapping description API
=======================

:ref:`concept-mapping` is done through a :py:class:`~dsx.Mapper`
object.  This object only has one user method:
:py:class:`dsx.Mapper.map`.  User must call it once for each resource
with the relevant parameters.

.. class:: dsx.Mapper()

   A mapper object.

   .. method:: __init__(hard, app)

      Create a new Mapper object.

      :type hard: :py:class:`soclib.Architecture`
      :param hard: An hardware platform

      :type app: :py:class:`dsx.application.Tcg`
      :param app: An application

   .. method:: map(resource, **kwargs)

      :type resource: :py:class:`~dsx.application.Mwmr`,
                      :py:class:`~dsx.application.Lock`,
                      :py:class:`~dsx.application.Memspace`,
                      :py:class:`~dsx.application.Barrier`,
                      :py:class:`~dsx.application.Task`,
                      :py:class:`~dsx.application.Tcg`, or str.

      :param resource: An application resource object to map. If a
                      string is passed, resource will be referred by
                      name.

      :param kwargs: a key/value mapping of hardware components names
                     to map resources to.


  Underlying class is :py:class:`dsx.mapper.mapper.Mapper`.

Example::

  import dsx
  import dsx.application
  import soclib

  # Declare the tasks, the communication and finally the Tcg:

  # ...
  tcg = dsx.application.Tcg(...)


  # Declare the hardware platform

  pf = soclib.Architecture(...)
  # ...


  # Create the mapper
  mapper = dsx.Mapper(pf, tcg)


  # Map the resources
  mapper.map(...)

Depending on the resource type, key/values to pass differ.
Here we cover what to pass in order to correctly map the resources.

Mwmr
====

.. _desc-mapping-mwmr:

For an MWMR channel, some arguments are mandatory:

``buffer``:
  A memory Segment to put the data buffer in. This may be cacheable.
``status``:
  A memory Segment to put dynamic status and buffer in. This must be
  cacheable.

One is optional:

``lock``:

  A Locks dedicated hardware component, like SocLib's Locks
  component. Uses one lock.  Mandatory if used protocol is not using
  atomic operations but hardware lock engine.  This depends on the
  :ref:`mwmr-controller`\ 's selected protocol.

Example::

  mapper.map("fifo",
             lock   = "locks",
             status = "cram2",
             buffer = "cram1")

Memspace
========

.. _desc-mapping-memspace:

For an Memspace, one argument is mandatory:

``buffer``:
  A memory Segment to put the data buffer in. This may be cacheable.

Example::

  mapper.map("memspace0",
             buffer = "cram32")

Lock
====

.. _desc-mapping-lock:

For a Lock, one argument is mandatory:

``segment``:
  A memory Segment where to put the lock structure in.

Example::

  mapper.map("lock0",
             segment = "uram3")

Barrier
=======

.. _desc-mapping-barrier:

For a Barrier, one argument is mandatory:

``segment``:
  A memory Segment where to put the barrier structure in.

Example::

  mapper.map("barrier0",
             segment = "cram8")

Task
====

.. _desc-mapping-task:

On task mapping, depending on the passed arguments, different task
implementation may be used.  The mapping destination automatically
selects the correct implementation.

Software task
-------------

.. _desc-mapping-swtask:

For a Task implemented as software, 3 arguments are mandatory:

``run``:
  A processor component where the thread will run.
``stack``:
  A memory Segment where to put the call task.
``desc``:
  A memory Segment where to put the description structure in.

Two other parameters are optional and select the printed messages
output:

``tty``:
  A serial-line-like component.
``tty_no``:
  An integer, if the component has more than one output channel.

Example::

  mapper.map("producer",
             run = "proc0",
             stack = "ram1",
             desc = "cram2")

  mapper.map("consumer",
             run = "proc1",
             stack = "ram1",
             desc = "cram2",
             tty = "tty0",
             tty_no = 2)

Hardware task
-------------

.. _desc-mapping-hwtask:

For a Task implemented as an hardware coprocessor, two arguments are
mandatory:

``coprocessor``:
  The coprocessor component name.  The `HwTask` associated to the task
  model must be compatible with it.
``controller``:
  The attached MWMR controller.

Example::

  mapper.map("consumer",
             coprocessor = "cons0_coproc",
             controller = "cons0_ctrl")

Processors
==========

.. _desc-mapping-cpu:

Processors have some attached data, like scheduler context and task
lists. A processor must be mapped. Mandatory arguments are:

``private``:
  A memory Segment where to put private data. It may be cached.
``shared``:
  A memory Segment where to put shared data. It must be uncached or
  coherent.

Optional arguments define the printed messages output, exactly like
for `software Task`_\s:

``tty``:
  A serial-line-like component.
``tty_no``:
  An integer, if the component has more than one output channel.

Example::

  mapper.map("proc1",
             private = "cram1",
             shared = "uram2")

Tcg
===

.. _desc-mapping-tcg:

Finally, the Tcg as a whole must be mapped. It corresponds to the
global application objects, like the description of the application
and other internal data. Mandatory arguments are:

``private``:
  A memory Segment where to put private data. It may be cached.
``shared``:
  A memory Segment where to put shared data. It must be uncached or
  coherent.
``code``:
  A memory Segment where to put executable code in. It may be
  read-only (and cached).

Optional arguments define the printed messages default output, exactly
like for `software Task`_\s:

``tty``:
  A serial-line-like component.
``tty_no``:
  An integer, if the component has more than one output channel.

Example::

  mapper.map(tcg,
             private = "cram1",
             shared = "uram2",
             code = "rom0",
             tty = "tty0",
             tto_no = 0)