next_inactive up previous
Up: SESAME Users Guide

YML Users Guide

Joseph Coffland

April 5, 2006

Copyright ©2004 University of Amsterdam. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included with this documentation, GNU Free Documentation License.


1 Introduction

This document describes YML or Y-Chart Modeling Language an XML derivative and how to use it. A basic knowledge of XML is assumed. See and for information about XML itself.

YML is a language for describing simulation models as directed graphs. YML was designed to be flexible enough to describe many different types of simulations. We currently use it to describe Kahn process network applications and event driven architectures. The basic components are links, nodes and networks. Properties can be added to these components to give simulation specific information. Scripting and sets were added to simplify the description of complicated simulation structures.

YML is a general purpose simulation description language. It can be easily interfaced to any existing simulation tool by means of a YML translator or direct interface between YML and the simulators internal data structures. This can be done either with existing XML parsers alone or with assistance from the ymllib C++ programming interface. See the LibYMLInterface document for more information.

2 Flat YML

Any piece of YML code can be translated to Flat YML by running it through the YML preprocessor (ymlpp). See ymlpp documentation. Flat YML consists only of network, node, port, link, property, and doc elements. These elements are the building blocks for simulation descriptions.

2.1 node

Node elements can represent processes or hardware components within a simulation. From YML's perspective it does not matter what the node represents. It is up to the specific simulator to interpret the exact meaning. Node elements must have a 'name' attribute and optionally a 'class' attribute. The 'class' attribute is most often used by simulators to designate the specific type of node. For example with PNRunner, the process network application simulator, the 'class' attribute defines nodes to be C, C++, or Java process. Node elements can contain property, doc, and port elements.
  <node name="process0" class="CPPProcess">

2.2 port

Port elements provide connection points for nodes and networks. They require both a 'name' and 'dir' or direction attribute. The 'dir' attribute can contain the values 'in', 'out', or 'both'. If it is left blank 'both' is assumed. Port elements can contain doc and property elements.
  <port name="port0" dir="in">

2.3 link

Link elements connect the port of nodes and networks together. They require 'innode', 'inport', 'outnode', 'outport' attributes. Object attributes specify a node or network with in the current network. The special keyword 'this' can be used to specify the current network as an object. 'innode' and 'outnode' can never both be 'this'. Port attributes name the port with in the specified object. If any of the ports or objects do not exist libyml will report errors. Link elements can contain doc or property elements.
  <link innode="this" inport="port0" 
        outnode="process0" outport="port0"/>

2.4 network

Network elements can encapsulate networks of nodes and links and even subnetworks. They provide hierarchy in simulation descriptions. Network elements require a 'name' and optionally a 'class' attribute. These attributes are used in the same manner as in node elements. Network elements can contain network, node, link, port, property, and doc elements.
  <network name="net0" class="KahnProcessNetwork">
    <network name="net1" class="KahnProcessNetwork">
      <port name="port0" dir="out"/>

      <node name="process1" class="CPPProcess">
        <port name="port0" dir="out">
      <link innode="process1" inport="port0" 
            outnode="this" outport="port0"/>

    <node name="process0" class="CPPProcess">
      <port name="port0" dir="in">

    <link innode="net1" inport="port0" 
          outnode="process0" outport="port0"/>

2.5 property

Property elements add information to YML objects. They are often specific to a simulator. A port for example may have a 'type' property which designates the data type used for communication. Property elements require a 'name' and 'value' attribute. Properties of the same name may be repeated. Care should be taken when choosing property names. It is important that two applications which use the same YML file don't use the same property names for different purposes. To help avoid this problem properties names which cannot be known in advance should be scoped. For example process nodes may wish to have properties naming operations to be performed by the process. The operations could be 'add', 'sub', 'mul'. However these operations may not be know ahead of time so the proper way to add these properties is to prefix the operations with a scope such as 'operation:'. Property elements can only contain doc elements.
  <property name="operation:add" value="0"/>
  <property name="operation:sub" value="1"/>
  <property name="operation:mul" value="2"/>

2.6 doc

Doc elements can contain documentation about a YML object. They can not contain any other elements.
  <doc>Some documentation</doc>

2.7 Object Naming Conventions

Object names can contain any printable character other than '.'. However white space and characters special to languages such as C or Perl should be avoided. For example 'node-2' could be mistakenly interpreted as the expression 'node - 2'. Recommended practice is to use names which would also make valid C variables. The '.' is used in full names to separate parents from children. It is often useful to have unique names for YML objects. libyml provides support for this by concatenating all the parents starting from the top most down to the child separated by '.'s. For example 'net0.net1.node0.outport' is the full name of outport of node0 of net1 of net0 where net0 is the top most network in the model description. Finally names starting with '$' will be evaluated as script variables. See the next section.

3 Scripting

The script element can be used to make dynamic YML. Currently only Larry Wall's Perl is supported as a scripting language, but any scripting language for which a libYML 'Interpreter' interface has been written can be used within YML. See the libYML Users Guide for more information. The script element takes no attributes. The text within a script element will be processed by the Interpreter in the order it appears in the YML file. Attributes which begin with a '$' will be evaluated as variables within the current context of the interpreter. Currently we have not found a good method for providing scope within Perl so users must be aware that all variables are global. This is especially dangerous when including external entities which contain script as it is not immediately obvious which variables they modify.

4 Sets

Set elements further simplify the description of complex network structures by providing a for loop like definition of sets of data. The set element takes three attributes 'init', 'cond', and 'loop' which are interpreted as script code. 'init' is evaluated once at the beginning of set processing. 'cond' is evaluated once at the beginning of each pass of set processing. The value of 'cond' is interpreted as a boolean value. When it is false or 0 set processing stops. Finally 'init' is processed once at the end of each pass of set processing.

  <set init="$i = 0" cond="$i &lt; 5" loop="$i++">
    <node name="$nodename" class="">
      <port name="port0" dir="out"/>

When processed this example will create five nodes named 'node0' through node4 each with a port named 'port0'.

5 Parameterizing YML

It is useful to use YML's scripting features to parameterize YML files. Both PNRunner and YMLPearl support passing of variables from the command line to the interpreter via the YML preprocessor (ymlpp). Here is an example of using this feature to command line parameterize a PNRunner process from the MJPEG case study.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE network SYSTEM "YML.dtd">
<network name="M-JPEG" class="KPN">
    <node name="Control" class="CPP_Process">
        <property name="library" value=""/>
        <property name="class" value="Control"/>

	. . .
          # These lines give default values for min and max threshold
          if (!(defined $min_threshold)) {$min_threshold = 0;}
          if (!(defined $max_threshold)) {$max_threshold = 2;}
          printf "\n";
          printf "Control parameters: min_threshold=$min_threshold,\n";
          printf "                    max_threshold=$max_threshold\n";
        <property name="carg" value="atoi(argv[1])"/>
        <property name="carg" value="atoi(argv[2])"/>
        <property name="arg" value="$min_threshold"/>
        <property name="arg" value="$max_threshold"/>

    . . .


The above example gives the variables 'min_threshold' and 'max_threshold' default values of 0 and 2 respectively. When the script is processed without the '-q' option the current value of the parameters are displayed by the printf statements. The values of these variables are passed on construction to the 'Control' process. Executing the following command will set 'min_threshold' to '1' and run the MJPEG case study application.

  PNRunner mjpeg.yml min_threshold=1

6 Including external YML files

Using XML external entity references you can include external YML. The following example is taken from the QR case study architecture description.

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE network SYSTEM "YML.dtd" [
  <!ENTITY proc SYSTEM "processor.yml">
  <network name="QR_unfold_1" class="net">

  . . .

    $max_port = 50;
    $procname = "ND_1";
    $id = 0;
    $nr_ex = 1;
    $nr_read = 0;
    $nr_write = 2;
    $ibufsize = 1;
    $has_input = 0;
    $has_output = 1;
    $has_ex = 0;
  . . .


In the above example the '!ENTITY' line defines the external entity 'proc' to be the contents of the file 'processor.yml'. The script sets up some variables that configure the processor and the '&proc;' entity reference inserts the processor code. References to the 'proc' entity can be use throughout the file. Multiple external entities can be included by adding additional '!ENTITY' lines. See for the exact details on XML external entities.

7 Making libraries

YML also provides library support via XML parameter entities. For example we first create a file called 'lib.yml' with the following contents.

<!ENTITY processor SYSTEM "processor.yml">
<!ENTITY memory SYSTEM "memory.yml">
<!ENTITY bus SYSTEM "bus.yml">

The external YML files contain YML code for a processor, memory, and bus. Now we include the library with the following XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE network SYSTEM "YML.dtd" [
<!ENTITY % lib SYSTEM "lib.yml">
. . .

Now you can use the included entities throughout the YML file. You can even include multiple libraries or create libraries within libraries as long as you do not create recursive loops. See for the exact details of XML parameter entities.

8 Mapping

The mapping layer in YML (YMLMap) enables users to associate the 'node', 'network' and 'port' elements of one simulation to those of another. We use this to map events, such as read, write and execute, of an application simulation onto an architecture simulation. YMLMaps do not name specific files and can therefore be used in other mappings by inclusion with XInclude statements. XInclude is an XML standard see for more information.

YMLMap is defined by the YML_map.xsd XML schema. Four XML elements are used to describe mappings: 'mapping', 'map', 'port' and 'instruction'. YMLMaps map a source simulation to a destination simulation. These are referred to as 'source' and 'dest'.

8.1 mapping

The 'mapping' element is used to define the mapping context. It requires two attributes 'side' and 'name'. The 'side' attribute can have either the value 'dest' or 'source'. The 'name' attribute refers to a 'network' within the current mapping context on the specified side. 'mapping' elements may contain any of the other YMLMap elements.

The mapping context defines where in the simulation descriptions 'name' attributes refer. There are really two contexts to keep track of. The source context and the destination context. The initial mapping contexts are above the root node in both of the simulations.

In the following example descendants of 'mapping' will refer to descendants of network 'A' on the 'source' side.

<mapping side="source" name="A">
  . . .

8.2 map

The 'map' element maps simulation 'node's. The attributes 'source' and 'dest' refer to YML 'node's in the source and destination simulations respectively. This element like 'mapping's sets the context for its descendants. In this case the context is set by the referenced 'node's. 'map' elements may only contain 'port' or 'instruction' elements.

This example maps the node 'A' in the source simulation to node 'X' in the destination simulation in the current mapping context.

<map source='A' dest='X'>
  . . .

8.3 port

The 'port' element maps 'port's between simulations. The attributes 'source' and 'dest' refer to 'port's of the source and destination simulations with in the current mapping context. This element may not contain any children.

This example maps the port 'A' in the source simulation to port 'X' in the destination simulation with in the current mapping context.

<port source='A' dest='X'/>

8.4 instruction

The 'instruction' element associates events on one side of the simulation to those on the other by name. The attributes 'source' and 'dest' refer to the string names of execution events. 'instruction' elements which are direct children of 'mapping' elements are available to all descendants of that 'mapping' element.

This example maps the instruction 'ADD' in the source simulation to instruction 'PLUS' in the destination simulation for both child 'map's 'A' to 'X' and 'B' to 'Y'.

<mapping side='source' name='A'>
  <map source='A' dest='X'>
  <map source='B' dest='Y'>
  <instruction source='ADD' dest='PLUS'/>

next_inactive up previous
Up: SESAME Users Guide
Joseph Coffland 2006-04-05