.. -*- rst -*-

=========
DSX Views
=========

.. digraph:: views

   fontsize = 10;

   node [shape=box,height=.6];

   SoftFromTcg; SoftDriver; PlatformToDts; DtsToPlatform;
   Hexo [label = "Hexo\nMutekH\nMutekS", color = red]
   MacrocellDriver [label = "MacrocellDriver\nPfDriver"];
   DtsDriver; DtsParser; ScModuleDriver; HardDriver;

   node [shape=ellipse,height=.6];

   tcg[color = red]; software; hard;
   architecture [label = "architecture", color = red];
   mapper [color = red]; device_tree; systemc;

   node [shape=tab];

   hfiles [label = "Hardware\nsimulator\nfiles", color = red];
   sfiles [label = "Software\nfiles", color = red];
   dfiles [label = "device tree\nfiles"];

   #subgraph cluster_p {
   #    SoftFromTcg -> software;
   #    label = "Posix";
   #    shape = box;
   #}

   subgraph {
      rank = min;
      tcg; architecture;
   }
      
   #subgraph {
   #   rank = same;
      
   #}

   subgraph {
      rank = same;
      sfiles; dfiles; hfiles;
   }

   subgraph {
      rank = same;
      software; mapper; systemc; hard; device_tree;
   }

   subgraph {
      rank = same;
      device_tree; systemc;
   }

   subgraph {
      rank = same;
      DtsToPlatform; PlatformToDts; SoftFromTcg;
   }

   subgraph {
      rank = same;
      MacrocellDriver; Hexo;
   }

   subgraph {
      rank = same;
      SoftDriver; DtsDriver; DtsParser;
      ScModuleDriver; HardDriver;
   }

   tcg -> SoftFromTcg;
   architecture -> hard;
   
   tcg -> mapper [color = red];
   architecture -> mapper [color = red];
   architecture -> systemc;
   systemc -> ScModuleDriver -> hfiles [color = red];
   architecture -> MacrocellDriver;
   MacrocellDriver -> systemc [color = red];

   ##
   SoftFromTcg -> software;   

   software -> SoftDriver;
   SoftDriver -> sfiles [color = red];
   mapper -> software;

   mapper -> Hexo [color = red];
   Hexo -> SoftDriver [color = red];
   Hexo -> MacrocellDriver [color = red];

   architecture -> PlatformToDts -> device_tree;
   device_tree -> DtsToPlatform -> architecture;

   device_tree -> DtsDriver -> dfiles;
   dfiles -> DtsParser -> device_tree;

   hard -> HardDriver -> hfiles;
   
The figure contains most of the |ware|\s (ellipses) and |driver|\s
(boxes) available in DSX.

.. note::

  In red, this is the path most users take when mapping an application
  on an hardware platform using MutekH. Red boxes and ellipses are the
  *explicitely* used |ware|\s and |driver|\s. You can see some drivers
  are transparently used behind the scenes.

The application view
====================

Application is a :py:class:`~dsx.application.tcg.Tcg`.

It can be transformed in a :py:class:`~dsx.soft.soft.Software` directly,
when all tasks have an associated
:py:class:`~dsx.application.swtask.SwTask` implementation.

It can also be put inside a :py:class:`~dsx.mapper.mapper.Mapper` with
an architecture.  Mapping results are both a
:py:class:`~dsx.soft.soft.Software` and a
:py:class:`~dsx.systemc.systemc.SystemC` netlist.  In this case, the
produced :py:class:`~dsx.soft.soft.Software` is not equivalent to the
one created directly from the :py:class:`~dsx.application.tcg.Tcg`
because some tasks are implemented as hardware, therefore not present
in the software tasks to create.

The Software view
=================

:py:class:`~dsx.soft.soft.Software` is a software-centric view of an
application. Nodes are tasks and other software memory resources.
They can be selectively assigned to processors or addresses.  It's up
to the driver creating the associated files to handle this correctly
for the backend.

The Hardware views
==================

Hardware exists in different representations.

* Platform netlist views are high-level netlist of components with
  full connection to the underlying component implementation and
  semantics. :py:class:`~soclib.platform.Architecture` is such a
  view. It has full connection to the external :py:mod:`soclib
  metadata library <soclib_desc>`.

* Hardware listing views are just an abstract list of components and
  their features. This is the :py:class:`~dsx.hard.hard.Hardware` and
  :py:class:`~dsx.device_tree.device_tree.DeviceTree` views.

* Hardware netlist views are an in-memory representation of an actual
  netlist, :py:class:`~dsx.systemc.systemc.SystemC` is such a view
  where semantics of components is lost, only remains the component
  names, C++ types, instantiation and connections.

.. |ware| replace:: :py:class:`~dsx.ware.Ware`
.. |driver| replace:: :py:class:`~dsx.driver.Driver`