Mapping description API

Mapping is done through a Mapper object. This object only has one user method: dsx.Mapper.map. User must call it once for each resource with the relevant parameters.

class dsx.Mapper

A mapper object.

__init__(hard, app)

Create a new Mapper object.

Parameters:

• hard (soclib.Architecture) – An hardware platform
• app (dsx.application.Tcg) – An application

map(resource, **kwargs)

Parameters:

• resource (Mwmr, Lock, Memspace, Barrier, Task, Tcg, or str.) – An application resource object to map. If a string is passed, resource will be referred by name.
• kwargs – a key/value mapping of hardware components names to map resources to.

Underlying class is 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

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 mwmr-controller‘s selected protocol.

Example:

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

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

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

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

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

Software task

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

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

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 Tasks:

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

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 Tasks:

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)