Application description API

The application description API lies in the dsx.application module. All the objects from the Task and Communication Graph are defined through Python objects. Objects reference each other to create the Graph.

Let’s start with an example. Let’s create a Task and Communication Graph with two tasks communicating through an MWMR channel, corresponding to the following picture:

Example producer/consumer TCG.

Application description code is:

from dsx.application import *

# Define the task models, both taking one MWMR channel with items of
# 32 bytes

producer = TaskModel('producer',
                     ports = {
                         'output': MwmrOutput(32),
                     },
                     )

consumer = TaskModel('consumer',
                     ports = {
                         'input': MwmrInput(32),
                     },
                     )


# Create an MWMR channel, containing 5 items of 32 bytes

chan0 = Mwmr('chan0', 32, 5)

# Create task instances

prod0 = Task('prod0', producer, portmap = {'output': chan0})
cons0 = Task('cons0', consumer, portmap = {'input': chan0})

# Finally, the TCG

tcg = Tcg(prod0, cons0)

Now, let’s see the details.

Task models

DSX automatically indexes all the files with a name ending with .task, in the DSX lib/task_library/ and in current directory.

Todo

en dire plus, pas forcement ici

class dsx.application.TaskModel(name, ports = {}, impls =[])

Creates a new task model.

Parameters:

• name (str) – Name of the task model. This must be unique for a given application declaration.
• ports (mapping of names to ports) – Ports of the task, declaring expected communication resources associated to symbolic names.
• impls (list of implementations) – Implementations of the task model.

Underlying class is dsx.application.taskmodel.TaskModel.

Ports

Depending on the resource type, different ports exist with different attributes. Attributes are used to specify constraints on the communication resource.

class dsx.application.MwmrInput(width)

A task port using an MWMR channel for reading data.

Parameters:width (int) – Expected width of items.

Underlying class is dsx.application.taskmodel.MwmrInput.

class dsx.application.MwmrOutput(width)

A task port using an MWMR channel for writing data.

Parameters:width (int) – Expected width of items.

Underlying class is dsx.application.taskmodel.MwmrOutput.

class dsx.application.MemspacePort(min_size)

A task port using a Shared-memory buffer for read/write access

Parameters:min_size (int, bytes) – Minimal expected size of memspace. 0 fits all sizes.

Underlying class is dsx.application.taskmodel.MemspacePort.

class dsx.application.BarrierPort

A task port using a Synchronization barrier. Barrier expected task list grows on assignment.

Underlying class is dsx.application.taskmodel.BarrierPort.

class dsx.application.LockPort

A task port using a Lock.

Underlying class is dsx.application.taskmodel.LockPort.

class dsx.application.ConstPort

A Constant. Upon resource mapping, a different constant value may be assigned to each instance of the task.

Underlying class is dsx.application.taskmodel.ConstPort.

Implementations

The core DSX module only provides support for a software implementation of tasks. Some other modules like soclib provide support for other implementation types.

class dsx.application.SwTask(name, stack_size, sources =[], bootstrap = None, defines =[])

Declaration of a software implementation of a task.

Parameters:

• name (str) – Name of implementation main routine
• stack_size (int, bytes) – Stack memory the task expects in order to run correctly.
• sources (list of filenames) – Source files where the implementation code lies
• bootstrap (str) – Name of the bootstrap routine. If left to None, no bootstrap code is run.
• defines (list of strings) – Preprocessor definitions the designer has to provide to the source code.

Underlying class is dsx.application.swtask.SwTask.

Communication resources

class dsx.application.Mwmr(name, width, depth)

An MWMR channel declaration.

Parameters:

• name (str) – Name of channel.
• width (int) – Width of one item, in bytes.
• depth (int) – Depth of channel, in items.

Underlying class is dsx.application.widgets.Mwmr.

class dsx.application.Memspace(name, size)

An Shared-memory buffer declaration.

Parameters:

• name (str) – Name of buffer.
• size (int) – Size of the whole buffer, in bytes.

Underlying class is dsx.application.widgets.Memspace.

class dsx.application.Lock(name)

A Lock declaration.

Parameters:name (str) – Name of the mutex.

Underlying class is dsx.application.widgets.Lock.

class dsx.application.Barrier(name)

A Synchronization barrier declaration.

Parameters:name (str) – Name of the barrier.

Underlying class is dsx.application.widgets.Barrier.

Task instances

class dsx.application.Task(name, model, portmap = {}, defines = {})

Instantiate a TaskModel.

Parameters:

• name (str) – Name of instance
• model (TaskModel) – Model of the task
• portmap (dict) – Mapping of port name to communication resources objects
• defines (dict) – Mapping of preprocessor variables to values. All names listed in defines parameter of TaskModel must be listed here.

Underlying class is dsx.application.widgets.Task.

Task and Communication Graph

class dsx.application.Tcg(task...)

Parameters:task (Task) – A variadic argument list of tasks

Underlying class is dsx.application.tcg.Tcg.

Examples

Task-farm

Let’s create a task-farm TCG corresponding to the following graph:

Example task-farm TCG.

Code uses some a for statement to create tasks in a loop:

from dsx.application import *

scatter = TaskModel('scatter',
                    ports = {
                        'output': MwmrOutput(4),
                    },
                    )

work = TaskModel('work',
                 ports = {
                     'input': MwmrInput(4),
                     'output': MwmrOutput(4),
                 },
                 )

gather = TaskModel('gather',
                   ports = {
                       'input': MwmrInput(4),
                   },
                   )


# Create two MWMR channels, containing 32 items of 4 bytes

todo = Mwmr('todo', 4, 32)
done = Mwmr('done', 4, 32)

# Create task instances, and let's have 3 workers

scat = Task('scat0', scatter, portmap = {'output': todo})
gath = Task('gath0', gather, portmap = {'input': done})

workers = []
for i in range(3):
  w = Task('work%d' % i, work, portmap = {'input': todo, 'output': done})
  workers.append(w)

# Finally, the TCG, using some Pythonic syntax

tasks = [scat, gath] + workers

tcg = Tcg(*tasks)