.. _concept-application: ============= Application ============= .. index:: pair: Modeling; Application DSX models the application in a split way: * The Tasks_ are the basic computation element, * The `Task and communication graph`_ connects the tasks around communication resources. The application is composed of tasks. They are self-contained and perform a single computation in the whole application. An application needs many tasks to be complete. Depending on the parallelism paradigm chosen by the application, different tasks will share the workload in different ways. Some applications have many similar tasks working in different elements of the datastream; other applications have a set of successive tasks working on the same datastream in a pipelined fashion. DSX permits both. Communication is modeled around the `communication resources`_. .. _concept-comm: Communication resources ======================= .. index:: single: Communication resource pair: model; Communication DSX has some built-in communication resources included. .. todo:: User can provide its own. Document adding communication resources Built-in communication resources are presented here. .. _concept-mwmr: MWMR channel ------------ .. index:: pair: Communication resource; MWMR channel single: KPN MWMR channels are the preferred way of modeling the communication in DSX. They offer several features: * They can be accessed from hardware or software tasks transparently. * They can fit most parallelism paradigms: KPN, task-farm, work-queue. * They are efficient * They require a minimal memory footprint. .. todo:: cite etienne MWMR channels are multi-writer, multi-reader fifo channels conveying `items` of fixed `width`. An item is always copied atomically from/to a channel. Items are guaranteed to transit in order in a channel, but contiguity is not asserted. This is a side-effect of the multi- feature. Read and/or writes can be interleaved on an item boundary. As a subset of the multi-writer/reader setup, an MWMR channel with only one writer and one reader behaves exactly like a bounded KPN channel. Mwmr channels can be declared through the :ref:`description API `, and can be used through the :ref:`C API `. .. _concept-memspace: Shared-memory buffer -------------------- .. index:: pair: Communication resource; Shared-memory buffer Shared-memory buffers are quite usual in a shared-memory system. They offer programmatic ease of use, but can add some unwanted trouble when used on a non-coherent hardware interconnect. For work with such cases, DSX offers primitives in its software API that permit explicit update of the memory system when working with shared memory. Memspaces can be declared through the :ref:`description API `, and can be used through the :ref:`C API `. .. _concept-lock: Lock ---- .. index:: pair: Communication resource; Lock Locks are — with shared-memory buffers — another well-known shared-memory-based communication primitive. They offer exclusive temporal access to an associated resource. DSX offers such a primitive implemented as a `mutex`. Semantically binding the lock to another shared resource is up to the application designer. Locks can be declared through the :ref:`description API `, and can be used through the :ref:`C API `. .. _concept-barrier: Synchronization barrier ----------------------- .. index:: triple: Communication resource; Synchronization; Barrier Synchronization Barriers are an usual feature of parallel workflows. They ensure all tasks involved in a computation meet at a defined point in the program before going on. DSX offers such a primitive. Barriers can be declared through the :ref:`description API `, and can be used through the :ref:`C API `. .. _concept-constant: Constant -------- .. index:: pair: Communication resource; Constant This is not a communication resource per se, but simply a per-instance constant value. This can help sharing the code of a task, yet differentiating the different instances. Constants needs no declaration, and can be directly used as integers. .. _concept-task: Tasks ===== .. index:: pair: Task; Modeling `Task` can be associated to three concepts: * A `Task model`_ is an abstract definition of the task from the `Task and communication graph`_ point of view. * `Task instance`_ is the actual presence of the task once or many times in the graph. * `Task implementations`_ are containing the code associated to the `task model`_. One model may have many *interchangeable* implementations. .. _concept-task-model: Task Model ---------- .. index:: pair: Task; Model A Task model defines a Task as seen from the *outside*. It corresponds to: * a name, * some ports_ that will be assigned to resources on instantiation_, * some parameters that must be specified in instantiation_. Task models can be declared through the :ref:`description API `. .. _concepts-task-port: Task ports ~~~~~~~~~~ .. todo:: tout .. figure:: /_static/producer.* Example representation of a producer task with one output MWMR port. .. _concept-task-instance: Task Instance ------------- .. index:: pair: Task; Instance Task instantiation is done when building a :ref:`concept-tcg`. On instantiation, each task's port_ must be associated to a compatible resource_, and valid instance parameters. Task instances can be created through the :ref:`description API `. .. _concept-task-implementation: Task implementations -------------------- When declaring a `Task model`_, implementations have to be specified. There can be any number of implementations, but at least one is necessary if TCG_ is to be implemented. Software implementation ~~~~~~~~~~~~~~~~~~~~~~~ .. index:: triple: Software; Task; Implementation This is an implementation of a task corresponding to compilable C (or any *gcc*\ -supported language) code. The corresponding code must use the :ref:`capi-srl` middleware. This ensures the code can be compiled on all supported backends. A software task can be used: * on a workstation, * on a SoC with a MutekH-based operating-system, * as a `synthetic task`_. Designers must take extra care for portability of their code. Endianness and data word widths can vary from one target to another. Software Task implementations can be declared through the :ref:`description API `. .. _concept-task-hardware: Hardware implementation ~~~~~~~~~~~~~~~~~~~~~~~ .. index:: triple: Hardware; Task; Implementation Hardware implementation of a task can correspond to either: * An hardware module that can be interconnected through an :ref:`mwmr-controller`, * An hardware module that got synthetized from a high-level source code (like C code for instance). Hardware Task implementations can be declared through the dedicated APIs in hardware component library support package, like :py:class:`soclib.hwtask.MwmrCoproc`. .. _concept-task-synthetic: Synthetic task ~~~~~~~~~~~~~~ .. index:: triple: Synthetic; Task; Implementation Synthetic implementation of a task is the software implementation of the task running as a coprocessor, wrapped in a transactor component making it act as a :py:class:`soclib.hwtask.MwmrCoproc`. This is done by the :py:class:`soclib.hwtask.SyntheticTask` class. Having a software task acting as an hardware one can help evaluating the relevance of creating a coprocessor without actually implementing it. .. _concept-tcg: Task and Communication Graph ============================ .. index:: single: TCG single: Task and Communication Graph A Task and Communication Graph is a bipartite graph where: * nodes are `task instance`_\s and `communication resources`_, * edges are connections from the ports of tasks to the associated communication resources. All the communication in the application is explicit. .. figure:: /_static/tcg-split.* Example representation of a TCG composed of a producer task and a consumer task connected through an MWMR channel. .. _instantiation: `Task instance`_ .. _ports: `Task ports`_ .. _port: `Task ports`_ .. _resource: `Communication resources`_ .. _tcg: `Task and Communication Graph`_