SystemCoDesigner: System Programming Tutorial

SystemCoDesigner: System Programming Tutorial Martin Streubühr Falk Christian Zebelein Hardware/Software Co-Design Department of Computer Science University of Erlangen-Nuremberg Germany Version 1.2 Christian Haubelt Joachim

Outline Introduction Programming Examples Advanced Data Flow Modeling Remarks Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 2

Introduction

Introduction SysteMoC Concepts SystemCoDesigner uses SysteMoC as input language SysteMoC...... is implemented on top of SystemC... uses actor-oriented design for modeling... supports data flow models of computation (MoC) Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 4

Introduction SysteMoC Concepts the SysteMoC library defines...... channels for data flow... syntax for modeling actor communication behavior as FSMs SysteMoC SysteMoC Elementary channels separating functionality and communication C++ syntax for specifying actor communication behaviour as FSMs Scheduler for (dynamic) dataflow MoC domain Elementary Channels Signal, timer, mutex, semaphore, FIFO, etc... SystemC Core Languages Modules Ports Processes Events Interfaces Channels Data Types 4 valued logic types 4 valued logic vectors Bits and bit vectors Arbitrary precision integers Fixed point numbers C++ user defined types Event driven Simulation Kernel Events, Processes, etc... C++ C++ Language Standard Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 5

Introduction SysteMoC Concepts produce() approximate() o 1 # 1/produce() i 3 # 1&i 4 # 1&o 4 # 1 /approximate() start o 1 src i 1 copystore() copyapprox() copyinput() check() o 2 i 3 start i 4 o 4 approx consume() i 6 # 1/consume() i 1 # 1&o 2 # 1 /copystore() i 2 # 1&!check() &o 2 # 1 start /copyinput() loop i 2 # 1&check()&o 3 # 1 /copyapprox() i 6 o 3 i 2 o 6 sqrloop o 5 i 5 duplicate() i 5 # 1&o 5 # 1&o 6 # 1 /duplicate() start sink start dup graphical representation of a complete SysteMoC design Newton s iterative algorithm square root calculation Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 6

Introduction SysteMoC Concepts produce() approximate() o 1 # 1/produce() i 3 # 1&i 4 # 1&o 4 # 1 /approximate() start o 1 src i 1 copystore() copyapprox() copyinput() check() o 2 i 3 start i 4 o 4 approx consume() i 6 # 1/consume() i 1 # 1&o 2 # 1 /copystore() i 2 # 1&!check() &o 2 # 1 start /copyinput() loop i 2 # 1&check()&o 3 # 1 /copyapprox() i 6 o 3 i 2 o 6 sqrloop o 5 i 5 duplicate() i 5 # 1&o 5 # 1&o 6 # 1 /duplicate() start sink start dup actors have ports Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 6

Introduction SysteMoC Concepts produce() approximate() o 1 # 1/produce() i 3 # 1&i 4 # 1&o 4 # 1 /approximate() start o 1 src i 1 copystore() copyapprox() copyinput() check() o 2 i 3 start i 4 o 4 approx consume() i 6 # 1/consume() i 1 # 1&o 2 # 1 /copystore() i 2 # 1&!check() &o 2 # 1 start /copyinput() loop i 2 # 1&check()&o 3 # 1 /copyapprox() i 6 o 3 i 2 o 6 sqrloop o 5 i 5 duplicate() i 5 # 1&o 5 # 1&o 6 # 1 /duplicate() start sink start dup ports are connected to channels actors communication via channels only Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 6

Introduction SysteMoC Concepts produce() approximate() o 1 # 1/produce() i 3 # 1&i 4 # 1&o 4 # 1 /approximate() start o 1 src i 1 copystore() copyapprox() copyinput() check() o 2 i 3 start i 4 o 4 approx consume() i 6 # 1/consume() i 1 # 1&o 2 # 1 /copystore() i 2 # 1&!check() &o 2 # 1 start /copyinput() loop i 2 # 1&check()&o 3 # 1 /copyapprox() i 6 o 3 i 2 o 6 sqrloop o 5 i 5 duplicate() i 5 # 1&o 5 # 1&o 6 # 1 /duplicate() start sink start dup actions implement functionality of actors actions are written in C++ Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 6

Introduction SysteMoC Concepts produce() approximate() o 1 # 1/produce() i 3 # 1&i 4 # 1&o 4 # 1 /approximate() start o 1 src i 1 copystore() copyapprox() copyinput() check() o 2 i 3 start i 4 o 4 approx consume() i 6 # 1/consume() i 1 # 1&o 2 # 1 /copystore() i 2 # 1&!check() &o 2 # 1 start /copyinput() loop i 2 # 1&check()&o 3 # 1 /copyapprox() i 6 o 3 i 2 o 6 sqrloop o 5 i 5 duplicate() i 5 # 1&o 5 # 1&o 6 # 1 /duplicate() start sink start dup a finite state machine controls an actor the FSM defines communication behavior and triggers execution of actions Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 6

Introduction Actor Interaction Actor state active Actor FSM call passive Variables read modify Functions actions guards actors are composed of a Finite State Machine (FSM), functions, and variables the FSM controls the function invocation functions are executed atomically data consumption and production is performed at the end of an action execution Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 7

Introduction Simulation Semantics a transition is active if all referred input queues have enough tokens, all referred output queues have enough free space (places), and all guards are evaluated to true an active transition may be fired the associated action is executed consumption and production of data tokens take place data flow between actors may activate or deactivate actions if several transitions of one actor are active one transition is selected non-deterministically Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 8

Programming Examples

Hello World Objectives You will see a state-of-the-art Hello World application...... modeled in SysteMoC. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 10

Hello World // file hello.cpp #include < iostream > #include < systemoc / smoc_moc.hpp > class HelloActor : public smoc_actor { public: // actor constructor HelloActor ( sc_module_name name) : smoc_actor ( name, start) { // FSM definition : // transition from start to end calling action src start = CALL( HelloActor :: src) >> end; } private: smoc_firing_state start, end; // FSM states void src () { // action std :: cout << " Actor " << this-> name () << " says :\ n" << " Hello World" << std :: endl; } }; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 11

Hello World // file hello. cpp cont d class HelloNetworkGraph : public smoc_graph { public: // network graph constructor HelloNetworkGraph ( sc_module_name name) : smoc_graph (name), helloactor (" HelloActor ") // create actor HelloActor { } private: // actors HelloActor helloactor ; }; int sc_main (int argc, char ** argv) { // create network graph HelloNetworkGraph top(" top"); smoc_scheduler_top sched( top); } sc_start (); // start simulation ( SystemC) return 0; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 12

Hello World compile the source code run simulation (OSCI SystemC: execute binary for simulation )./ hello simulation output SystemC 2.2.0 --- Dec 15 2008 11:10:07 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED Actor top. HelloActor says: Hello World SystemC: simulation stopped by user. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 13

Actors and Graphs Objectives You will learn to...... write actors.... instantiate actors in a network graph.... run functional simulation. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 14

Actors and Graphs Actors include SysteMoC library header #include < systemoc / smoc_moc.hpp > an actor is a C++ class derived from base class smoc_actor class HelloActor : public smoc_actor { an action is a member function of the actors class actions shall be private prohibit execution by others private: void src () { // action std :: cout << " Actor " << this-> name () << " says :\ n" << " Hello World" << std :: endl; } Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 15

Actors and Graphs Actors an actor has a finite set of states smoc_firing_state state_a, state_b; // FSM states like objects of a class in C++, we create instances of an actor constructors are responsible for creating a certain actor instance provide actor name and start state to base class smoc_actor HelloActor ( sc_module_name name) // actor constructor : smoc_actor ( name, state_a) { Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 16

Actors and Graphs Actors a finite state machine (FSM) defines transitions between states e.g. a transition from state_a to state_b if this transition is taken, the action HelloActor::src is executed } HelloActor ( sc_module_name name) // actor constructor : smoc_actor ( name, state_a) { // FSM definition : // transition from state_a to state_b calling action src state_a = CALL( HelloActor :: src) >> state_b; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 17

Actors and Graphs Graphs a network graph is derived from base class smoc_graph class HelloNetworkGraph : public smoc_graph { our network graph has an instance of the HelloActor private: // actors HelloActor helloactor ; a name for the graph has to be passed to base class smoc_graph we need to call HelloActor s constructor // network graph constructor HelloNetworkGraph ( sc_module_name name) : smoc_graph (name), helloactor (" HelloActor ") // create actor HelloWorld { } }; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 18

Simulation function sc_main is the entry point for simulation (cf. SystemC) the network graph is instantiated parameters are passed to the graph constructor (e.g. top ) call sc_start to start simulation (cf. SystemC) int sc_main (int argc, char ** argv) { // create network graph HelloNetworkGraph top(" top"); smoc_scheduler_top sched( top); } sc_start (); // start simulation ( SystemC) return 0; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 19

Ports and Channels Objectives You will learn to...... use ports.... connect actors via channels. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 20

Ports and Channels Sink Actor class Sink: public smoc_actor { public: // ports: smoc_port_in <char> in; Sink( sc_module_name name) // actor constructor : smoc_actor ( name, start) { // FSM definition : start = in (1) >> CALL(Sink :: sink) >> start; } private: smoc_firing_state start; // FSM states void sink () { std :: cout << this-> name () << " recv: \"" << in [0] << "\"" << std :: endl; } }; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 21

Ports and Channels Input Port create an input port ports have a data type (e.g. char) smoc_port_in <char> in; a single object of the particular data type is termed a token declare to read one token in FSM transition start = in (1) >> CALL(Sink :: sink) >> start; write data in action void sink () { std :: cout << this-> name () << " recv: \ " << in [0] << "\ " << std :: endl; } Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 22

Ports and Channels Source Actor using output ports is similar class Source: public smoc_actor { public: // ports: smoc_port_out <char> out; Source( sc_module_name name) : smoc_actor ( name, start) { start = out (1) >> CALL(Source :: src) >> start; } private: smoc_firing_state start; // FSM states void src () { std :: cout << this-> name () << " send: \ X\ " << std :: endl; out [0] = X ; } }; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 23

Ports and Channels Output Port create an output with data type char smoc_port_out <char> out; declare to write one token in FSM transition start = out (1) >> CALL(Source :: src) >> start; access data in action void src () { std :: cout << this-> name () << " send: \ X\ " << std :: endl; out [0] = X ; } Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 24

Ports and Channels Connect Actors class NetworkGraph : public smoc_graph { public: NetworkGraph ( sc_module_name name) // network graph constructor : smoc_graph (name), source(" Source"), // create actors sink("sink") { connectnodeports ( source.out, sink. in); // connect } private: Source source; // actors Sink sink; }; actors int sc_main (int argc, char ** argv) { smoc_top_moc < NetworkGraph > top(" top"); // create network graph } sc_start (); // start simulation ( SystemC) return 0; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 25

Ports and Channels FIFO Queues connect a pair of ports (input, output) using a FIFO queue connected ports have to use the same data type queues have default size 1 (one data token) connectnodeports ( source.out, sink. in); set queue size explicitly connectnodeports <23 >( source.out, sink. in); more advanced channel features (later) channel types initial data tokens Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 26

Ports and Channels simulation output SystemC 2.2.0 --- Dec 15 2008 11:10:07 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED top.source send: X top.sink recv: X top.source send: X top.sink recv: X top.source send: X top.sink recv: X... simulation runs infinitely Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 27

Guards and Actions Objectives You will learn to...... write and use guards.... write and use actions. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 28

Guards and Actions SourceActor static const std :: string MESSAGE = " 0123456789 "; class Source: public smoc_actor { public: smoc_port_out <char> out; Source( sc_module_name name) : smoc_actor ( name, start), count (0), size(message.size ()), message(message) { start = GUARD(Source :: hastoken ) >> out (1) >> CALL(Source :: src) >> start; } private: smoc_firing_state start; unsigned int count, size; // variables ( functional state) const std :: string message; // bool hastoken () const{ return count < size; } // guard void src () { out [0] = message[ count ++]; } // action }; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 29

Guards and Actions Guards a guard is a const member function returning a boolean value bool hastoken () const{ return count < size; } // guard guards enable/disable transitions (true/false) guards must (can) not change variable values or token in channels refer to guards via GUARD(..) macro start = GUARD(Source :: hastoken ) >> out (1) >> CALL(Source :: src) >> start; use guards for control flow (see below) Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 30

Guards and Actions Variables variables...... are private class member of an actor... can be used to store data... represent a functional state of an actor (in contrast to FSM state) unsigned int count, size; const std :: string message; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 31

Guards and Actions Actions actions...... are used to read/write data on input/output ports... modify variables void src () { out [0] = message[ count ++]; } guards access variables read-only (mandatory const modifier) actions are allowed to modify variables Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 32

Guards and Actions Multiple Access you can write/read data more than once (overwrite/re-read) e.g. read input twice void sink () { char squareinput = in [0] * in [0]; } char x = in [0]; char y = in [0]; // re -read assert(x == y); e.g. write a default value first void src () { out [0] = X ; // default if(count <size){ out [0] = message[ count ++]; // overwrite } } Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 33

Guards and Actions simulation output (using Sink actor from previous example) top. Sink recv: "0" top. Sink recv: "1" top. Sink recv: "2" top. Sink recv: "3" top. Sink recv: "4" top. Sink recv: "5" top. Sink recv: "6" top. Sink recv: "7" top. Sink recv: "8" top. Sink recv: "9" SystemC: simulation stopped by user. Source actor sends a finite number of characters only simulation terminates when no actor can be activated Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 34

Communication Rates Objectives former examples consume/produce only a single token per invocation consumption and production rates may be different from one You will learn to...... use consumption and production rates. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 35

Communication Rates Source Actor static const std :: string MESSAGE = " 0123456789 "; class Source: public smoc_actor { public: smoc_port_out <char> out; Source( sc_module_name name) : smoc_actor ( name, start), count (0), size(strlen(message)), message(message) { start = GUARD(Source :: hastoken ) >> } private: out (2) >> CALL(Source :: src) >> start; smoc_firing_state start; unsigned int count, size; // variables ( functional state) const char* message; // bool hastoken () const{ return count < size; } // guard void src () { // action out [0] = message[ count ++]; out [1] = message[ count ++]; }}; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 36

Communication Rates Production Rate the Source actor produces two data tokens per invocation we declare to produce n data tokens in a transition using out(n) start = GUARD(Source :: hastoken ) >> out (2) >> CALL(Source :: src) >> start; use the index operator [] to write data values void src () { out [0] = message[ count ++]; out [1] = message[ count ++]; } similar to arrays addressing range is 0,...,n 1 Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 37

Communication Rates Avoid Deadlocks simulation output (using Sink actor from previous example) SystemC 2.2.0 --- Dec 15 2008 11:10:07 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED SystemC: simulation stopped by user. Oh oh, nothing happens! writing two tokens requires free space for (at least) two tokens we need to increase the queue size (implicit size was 1 ) connectnodeports <4>( source.out, sink.in); minimum size of 2 is mandatory (but actors would run in lockstep) using larger sized queues may decouple execution of actors Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 38

Communication Rates Simulation simulation output (using Sink actor from previous example) and increased queue size SystemC 2.2.0 --- Dec 15 2008 11:10:07 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED top. Sink recv: "0" top. Sink recv: "1" top. Sink recv: "2" top. Sink recv: "3" top. Sink recv: "4" top. Sink recv: "5" top. Sink recv: "6" top. Sink recv: "7" top. Sink recv: "8" top. Sink recv: "9" SystemC: simulation stopped by user. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 39

Communication Rates Queue Access Source Sink void produce(){ out[0] = x; out[2] = y; } void consume(){ int a = in[0]; } out(3) /produce() out out[2] out[1] out[0] in[1] in[0] in in(2) /consume() read tokens... a transition claims to consume n tokens from input port in using in(n) read data from FIFO queue using in[j]; j 0,...,n 1 in[0] refers first available token in queue Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 40

Communication Rates Queue Access Source Sink void produce(){ out[0] = x; out[2] = y; } void consume(){ int a = in[0]; } out(3) /produce() out out[2] out[1] out[0] in[1] in[0] in in(2) /consume() write tokens... a transition claims to produce n tokens on output port out using out(n) write data to FIFO queue using out[j]; j 0,...,n 1 out[0] refers first free position (place) in a queue Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 40

Communication Rates Queue Access Source Sink void produce(){ out[0] = x; out[2] = y; } void consume(){ int a = in[0]; } out(3) /produce() out out[2] out[1] out[0] in[1] in[0] in in(2) /consume() activation and execution... transition becomes active (enough token, free space; guards) an activated transition may be fired firing a transition implies execution of its action Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 40

Initial Tokens Objectives data flow graphs may contain cyclic dependencies initial tokens are a common way to break cyclic dependencies You will learn to...... initialize queues. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 41

Initial Tokens Cyclic Dependencies forward() in out forward() in(1)&&out(1)/forward() in(1)&&out(1)/forward() out in start Ping Pong start each actor forwards input tokens to output port network graph contains a cyclic dependency without initialization none of the actors would become active we may use an initial token to break the cyclic dependency Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 42

Initial Tokens Example class Forward: public smoc_actor { public: smoc_port_in <int> in; smoc_port_out <int> out; Forward( sc_module_name start = in (1) >> out (1) >> CALL(Forward :: forward) >> start; } private: smoc_firing_state start; name) : smoc_actor ( name, start){ void forward () { std :: cout << this-> name () << " forward: \"" << in [0] << "\"" << std :: endl; out [0] = in [0]; } }; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 43

Initial Tokens Example class NetworkGraph : public smoc_graph { protected: // actors Forward ping; Forward pong; public: // network graph constructor NetworkGraph ( sc_module_name name) : smoc_graph (name), // create actors ping("ping"), pong("pong") { } }; smoc_fifo <int> initfifo (1); initfifo << 42; connectnodeports (ping.out, pong.in); connectnodeports ( pong.out, ping.in, initfifo ); Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 44

Initial Tokens Simulation SystemC 2.2.0 --- Dec 15 2008 11:10:07 Copyright (c) 1996-2006 by all Contributors ALL RIGHTS RESERVED top.ping forward: "42" top.pong forward: "42" top.ping forward: "42" top.pong forward: "42"... Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 45

Initial Tokens Syntax explicit creation of a FIFO initializer give queue size as constructor parameter smoc_fifo <int> initfifo (1); push initial value to initializer initfifo << 42; pass initializer when constructing the queue connectnodeports ( pong.out, ping.in, initfifo ); initializer may be reused for creating identical initialized queues Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 46

Advanced Data Flow Modeling

Hierarchical States Objectives You will learn how to refine states of an FSM into hierarchical states by means of...... XOR decomposition,... AND decomposition, and... Junction states Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 48

Non-Hierarchical Example #include < iostream > #include < systemoc / smoc_moc.hpp > class Actor : public smoc_actor { public: enum CmdType { CMD_GO, CMD_STOP }; smoc_port_in < CmdType > inctl; Actor( sc_module_name name) : smoc_actor ( name, stopped) { smoc_firing_state run; // states can be declared locally stopped = inctl (1) && GUARD(Actor :: iscmd)(cmd_go) >> CALL(Actor ::go) >> run; run = inctl (1) && GUARD( Actor :: iscmd)( CMD_STOP ) >> CALL(Actor :: stop) >> stopped; }... Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 49

Non-Hierarchical Example... private: smoc_firing_state stopped; bool iscmd( CmdType cmd) const { return inctl [0] == cmd; } void go() { std :: cout << this-> name () << ": Go" << std :: endl; } void stop () { std :: cout << this-> name () << ": Stop" << std :: endl; } }; This initial example contains two non-hierarchical states stopped and run as known from previous examples Note that states (except the initial state) can be declared locally inside the constructor In the following, we will refine the run state into a nested FSM by means of hierarchical states Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 50

Hierarchical States XOR decomposition First step: Replace the type of a state by the desired hierarchical state type, namely smoc_xor_state or smoc_and_state. In this example, we will refine the run state into an XOR state: Actor (...) : smoc_actor (..., stopped) { smoc_xor_state run;... } Second step: Instantiate the child states of the XOR state. Note that these can consist of hierarchical and non-hierarchical states:... smoc_xor_state run; smoc_firing_state waitmsg; smoc_and_state storedata ; // will be refined later smoc_firing_state sendack;... Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 51

Hierarchical States XOR decomposition Third step: Add the child states to the XOR state. Note that the initial child state, i.e., the state which should be active when the XOR state is entered, must be added via parent.init(child). All other states are added via parent.add(child): smoc_xor_state run; smoc_firing_state waitmsg; // initial child state smoc_and_state storedata ; smoc_firing_state sendack; run.init(waitmsg); run.add( storedata ); run.add(sendack); Last step: Add transitions to the child states: waitmsg = inlink (1) >> CALL( Actor :: processmsg ) >> storedata ; sendack = outlink (1) >> CALL( Actor :: sendackmsg ) >> waitmsg; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 52

Hierarchical States XOR decomposition XOR states must have exactly one initial state States which are not added to any hierarchical state are automatically added to the FSM (like stopped and run in this example), which can also be seen as an XOR state (with stopped being the initial state in this example) Transitions added to the XOR state itself are added (recursively) to all child states. In this case, the only outgoing transition of the run state allows for leaving the receive/send loop at any time: run = inctl (1) && GUARD( Actor :: iscmd)( CMD_STOP ) >> CALL(Actor :: stop) >> stopped; History connectors are not supported at this time Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 53

Hierarchical States AND decomposition An XOR state has exactly one active child state at any one time In an AND state, all child states are active at any one time. In the following, the child states of an AND state will be called partitions A partition can be a hierarchical or non-hierarchical state The state of an AND state with N partitions P 1,...,P N is given by the tuple (s 1,s 2,...,s N ), such that i,1 i N : s i is a valid state from partition P i. This is also called a product state The initial state of an AND state is the product state whose components are in turn the initial states of the corresponding partitions In SysteMoC, an AND state can be declared as follows: smoc_and_state storedata ; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 54

Hierarchical States AND decomposition Partitions are added to AND states in the same manner as child states are added to XOR states: smoc_and_state storedata ; smoc_xor_state senddmawritereqs ; smoc_xor_state recvdmawriteacks ; // add two partitions to storedata : storedata. add( senddmawritereqs ). add( recvdmawriteacks ); // add child states to the first partition : smoc_firing_state senddmawritereq ; smoc_firing_state sentalldmawritereqs ; senddmawritereqs. init( senddmawritereq ). add( sentalldmawritereqs ); // add child states to the second partition : smoc_firing_state recvdmawriteack ; smoc_firing_state recvdalldmawriteacks ; recvdmawriteacks. init( recvdmawriteack ). add( recvdalldmawriteacks ); Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 55

Hierarchical States AND decomposition Transitions can be added to partitions as usual. Note that transitions between partitions are not allowed: senddmawritereq = outmem (1) && GUARD( Actor :: sendmoredmawritereqs ) >> CALL( Actor :: senddmawritereq ) >> senddmawritereq! GUARD( Actor :: sendmoredmawritereqs ) >> sentalldmawritereqs ; recvdmawriteack = inmem (1) && GUARD( Actor :: isdmawriteack ) >> CALL( Actor :: processdmawriteack ) >> recvdmawriteack! GUARD( Actor :: pendingdmawriteacks ) >> recvdalldmawriteacks ; // not allowed ( will throw a ModelingException ): // senddmawritereq =... >> recvdmawriteack ; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 56

Hierarchical States AND decomposition A transition whose target state is an AND state may specify for each partition which state should be active when entering the AND state: waitmsg = inlink (1) >> CALL( Actor :: processmsg ) >> ( senddmawritereq, recvdmawriteack ); If no specific state is given for a partition, the default initial state will be the active state: waitmsg = inlink (1) >> CALL( Actor :: processmsg ) >> storedata ; Both transitions are equivalent, as both senddmawritereq and recvdmawriteack are the initial states of their corresponding partitions In fact, the target state can be any valid (partial) product state Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 57

Hierarchical States AND decomposition It is also possible for the source state to be a (partial) product state. However, some restrictions apply A transition must be appended to exactly one state. All other states in the (partial) product state must be marked with the IN keyword: (s1, IN(s2), IN(s3),...) =...; In this case, the transition from s1 will be enabled if the FSM is also in states s2 and s3. The IN keyword can also be negated: (s1, IN(s2),!IN(s3),...) =...; In this case, the transition from s1 will be enabled if the FSM is in state s2 but not in s3. Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 58

Hierarchical States AND decomposition Like an XOR state, an AND state will be left if the target state of a transition is no child state of the AND state... ( sentalldmawritereqs, IN( recvdalldmawriteacks )) =... >> sendack...or if the source state of a transition is the AND state itself: ( storedata, IN( sentalldmawritereqs ), IN( recvdalldmawriteacks )) =... >> sendack Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 59

Hierarchical States Junction states Junction states as known from UML can be used to chain together multiple transitions They are not part of the state hierarchy and need not be added to any states smoc_firing_state a, b, c; smoc_junction_state j; a = CALL( Actor :: actiona) >> j; b = CALL( Actor :: actionb) >> j; j = CALL( Actor :: actionc) >> c; This example is equivalent to the following FSM fragment without junction states: smoc_firing_state a, b, c; a = CALL(Actor :: actiona) >> CALL(Actor :: actionc) >> c; b = CALL(Actor :: actionb) >> CALL(Actor :: actionc) >> c; Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 60

Hierarchical States Junction states Note that a transition can have multiple actions. In this case, the order of execution is equal to the order of appearance All pairs (t in,t out ) of transitions where t in is a transition entering the junction state and t out is a transition leaving the junction state will be transformed into a single compound transition Actions of transition t in will be executed prior to the actions of transition t out All guards of a compound transition are executed prior to any action of a compound transition For example, if variables are modified by transition t in, guards of transition t out will see the old values of these variables, and not the modified values The port requirements of t in and t out should be disjoint at this time. However, the actions of t out can access tokens required by t in and vice versa Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 61

Dynamic FSM Construction Objectives You will learn how to dynamically construct the FSM of an actor...... by dynamically adding transitions to states and... by passing and returning states to and from functions Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 62

Dynamic FSM Construction Transitions can be added to states after some transitions have already been added: smoc_firing_state a, b, c, d; // overwrite any transitions already added to a a = GUARD(Actor :: guarda) >> CALL(Actor :: actiona) >> a GUARD(Actor :: guardb) >> CALL(Actor :: actionb) >> b; // append some more transitions to a a = GUARD(Actor :: guardc) >> CALL(Actor :: actionc) >> c GUARD(Actor :: guardd) >> CALL(Actor :: actiond) >> d; Note that whereas a = <transition list> first removes all transitions from a and then adds <transition list> to a, a = <transition list> simply appends <transition list> to a Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 63

Dynamic FSM Construction States can be passed to functions via pointers or references: void a( smoc_firing_state & s); void b( smoc_firing_state :: Ref s); // equivalent to a void c(const smoc_firing_state & s); void d( smoc_firing_state :: ConstRef s); // equivalent to c void e( smoc_firing_state * a); void f( smoc_firing_state :: Ptr a); // equivalent to e void g(const smoc_firing_state * a); void h( smoc_firing_state :: ConstPtr a); // equivalent to g Due to states being reference counted, using ::Ref, ::ConstRef, ::Ptr and ::ConstPtr is the preferred way of passing around references or pointers to states Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 64

Dynamic FSM Construction States can be returned from functions via pointers or references: smoc_firing_state :: Ptr a() { smoc_firing_state s;... return &s; } smoc_firing_state :: Ref b() { smoc_firing_state s;... return s; } Note that when using ::Ref, ::ConstRef, ::Ptr or ::ConstPtr as the return type of a function, returning a pointer or reference to a state declared locally inside the function is perfectly legal Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 65

Remarks

Outline Introduction Programming Examples Advanced Data Flow Modeling Remarks Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 67

Contact Contact Persons: Joachim Falk, Jürgen Teich Email: joachim.falk@fau.de Address: Hardware/Software Co-Design Department of Computer Science University of Erlangen-Nuremberg Cauerstr. 11 91058 Erlangen, Germany Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 68

Credits SysteMoC Development Team: Joachim Falk, Jens Gladigau, Martin Streubühr, Christian Zebelein SystemCoDesigner Contributors: Joachim Falk, Michael Glass, Jens Gladigau, Joachim Keinert, Martin Lukasiewycz, Felix Reimann, Thomas Schlichter, Thilo Streichert, Martin Streubühr, Christian Zebelein, Christian Haubelt, Jürgen Teich Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 69

Document Info Authors: Martin Streubühr, Christian Zebelein, Christian Haubelt, Joachim Falk Document Release: Jul. 3, 2012 Version History: Jul. 3, 2012: Version 1.2 Jul. 28, 2010: Version 1.1 Oct.1, 2009: Version 1.0 Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 70

Index actions, 36 actor, 19 21 CALL, 21 connectnodeports, 29 30, 42 FIFO queue, 44 46 FSM, 21 GUARD, 34 guard, 34 input port, 26 network graph, 22 output port, 28 port, 25 28, 37 simulation, 12, 23 smoc_actor, 19, 20 smoc_firing_state, 20 smoc_graph, 22 state, 20 variables, 35 Version 1.2 Martin Streubühr et al. FAU SystemCoDesigner: System Programming Tutorial 71