.. -*- rst -*-

.. py:module:: soclib

======================
``soclib`` package API
======================

Architecture
============

.. py:class:: Architecture()

   A soclib-based platform description.

   .. method:: __init__(abstraction_level, **default_args)

      Creates a new platform.

      :type abstraction_level: str

      :param abstraction_level: The main abstraction level of the
                                platform, adds some default signals
                                for "caba".

      :param default_args: A key/value mapping of parameter values to
                           implicitly add for any :py:meth:`~.create`
                           call.

   .. method:: create(module, name, **args)

      Creates a new component in this platform.

      :param str module: Module name in :ref:`md-index`.

      :param str name: Instance name

      :param args: A key/value mapping of components
                   parameters. ``default_args`` passed at
                   `Architecture` creation are used as defaults values
                   here.

      :returns: a :py:class:`soclib.Component` object.

      :raises: Any error if instantiation is invalid.

   Underlying class is :py:class:`soclib.platform.Architecture`.

Component
=========

.. py:class:: Component()

   A component spawned by :py:meth:`soclib.Architecture.create`.

   A component object is fully defined, it has an actual corresponding
   component implementation, it is fully parameterized. Ports are
   accessed as attributes (see Ports_).

   .. method:: addSegment(name, address, size, cacheable = None, mt = None)

      Adds a memory segment to the segment list targeting this
      component.

      :param str name: Name of segment

      :param int address: Base address of segment

      :param int size: Size in bytes of segment

      :param bool cacheable: Whether this segment should be cacheable

      :type mt: :py:class:`~.Component`

      :param mt: a component corresponding to a
                 ``common:mapping_table`` soclib module

      :raises: ValueError if address or size is invalid.

   Underlying class is :py:class:`soclib.component.Component`.

Ports
=====

In a :py:class:`Component`, ports are available through their names,
and the "p\_" prefix is skipped, if present in metadata.

For instance, a module defined with the following :ref:`sd-file`::

  Module("caba:my_super_module",
         classname = "MySuperModule",
         ports = [
            Port('caba:bit_out','p_irq'),
            Port('caba:bit_in','p_irq_in', 10),
            ],
         )

Instantiated through the following code::

  import soclib

  arch = soclib.Architecture("caba")

  inst0 = arch.create("caba:my_super_module", "inst0")

exports the ports as::

  # simple ports as a Port object
  inst0.irq

  # port arrays an array of Port objects
  inst0.irq_in[0]
  inst0.irq_in[1]
  inst0.irq_in[2]
  ...
  inst0.irq_in[9]

.. py:class:: Port()

   A port attached to a :py:class:`~.Component`. Ports are implicitly
   created by component creation.

   .. py:method:: // other
                  __floordiv__(other)

      This corresponds to the following syntax::

        inst0 = arch.create(...)
        inst1 = arch.create(...)

        new_signal = inst0.portA // inst1.portB

      Spawns a signal compatible with both ports and connect them to
      it.

      :type other: :py:class:`~.Port`

      :param other: another port

      :returns: spawned :py:class:`~.Signal` object

   .. py:method:: setExternal(port_desc, name)

      Exports the port to the boundary of the architecture. This
      permits to build hierarchical netlists.

      :param str port_desc: A port type in :ref:`md-index`.

      :param str name: External port name.

   Underlying class is :py:class:`soclib.component.Port`.

.. py:class:: Signal()

   A signal. Signals are created by the connection of two ports
   together (See :py:meth:`Port // operator
   <Port.__floordiv__>`). Reference is here for the two following
   methods:

   .. py:method:: // port
                  __floordiv__(port)

      The ``//`` operator.

      This corresponds to the following syntax::

        inst0 = arch.create(...)
        inst1 = arch.create(...)
        inst2 = arch.create(...)

        new_signal = inst0.portA // inst1.portB
        new_signal // inst2.portB

        # Equivalent to:

        inst0.portA // inst1.portB // inst2.portB

      Connects the signal to the given port.

      :type port: :py:class:`~.Port`

      :param port: a compatible port

      :returns: the signal itself (so that you can use the return
                value for another connection).

   .. py:method:: setExternal(port_desc, name)

      Exports the signal to the boundary of the architecture. This
      permits to build hierarchical netlists.

      :param str port_desc: A port type in :ref:`md-index`.

      :param str name: External port name.

   Underlying class is :py:class:`soclib.component.Signal`.

Coprocessors
============

Coprocessors can be instantiated from their matching
:py:class:`dsx.application.TaskModel` object. This is done the
following way:

#. Retrieve a model by its type, and get an implementation by its
   class::

     import dsx.application
     import soclib

     arch = soclib.Architecture(...)

     model = dsx.application.TaskModel.getByName("task_model_name")
     impl = model.getImpl(soclib.HwTask)

   See :py:meth:`dsx.application.taskmodel.TaskModel.getByName` and
   :py:meth:`dsx.application.taskmodel.TaskModel.getImpl`.

#. Instantiate the coprocessor component and its interface
   controller::

     ctrl, coproc = model.instanciate(arch,
                                      "coproc_instance_name",
                                      "controller_instance_name")

   See :py:meth:`soclib.hwtask.HwTask.instanciate`.

#. Assign a segment to the controller::

     ctrl.addSegment("ctrl_seg", 0x42000000, 0x200, False)

   See :py:meth:`soclib.Component.addSegment`.

#. Connect the controller to the NoC::

     ctrl.vci_initiator // noc.to_initiator.new()
     ctrl.vci_target // noc.to_target.new()

   See Ports_.

   .. note::

      Connections between the coprocessor and its controller are
      automatically done on instantiation.