We are going to implement plus1, ForSyDe's Hello World, a system with takes integer values, adds 1 to them and forwards the result through its output signal.

As we mentioned previously, the plus1 process can be created in terms of the mapSY process constructor. Here is the signature of mapSY in the deep-embedded API.

mapSY :: (ProcType a, ProcType b) =>
         ProcId -> ProcFun (a -> b) -> Signal a -> Signal b	
	

mapSY works similarly to Haskell's map function. It creates a process which applies a function to every value in a signal. Let's have a closer look at its arguments.

{-# LANGUAGE TemplateHaskell #-}
module Plus1 where

import ForSyDe
import Data.Int (Int32)
	

We need to import ForSyDe's library and Int32. Since deep-embedded systems might be later translated to hardware, it is required to be specific about the size of integers used (the size of Int is platform-specific). Additionally, in all ForSyDe deep-embedded designs we need to tell GHC to enable the Template Haskell (TH) extension, here is why:

-- A process function which adds one to its input
addOnef :: ProcFun (Int32 -> Int32)
addOnef = $(newProcFun [d|addOnef :: Int32 -> Int32 
                          addOnef n = n + 1     |])
	

In the code above, we declared the ProcFun needed by mapSY. It simply takes an Int32 value and adds 1 to it.

Instead of creating a specific DSL to express computations in the deep-embedded model, ForSyDe uses TH to allow using plain Haskell. In principle, ProcFuns can make use of any Haskell feature supported by TH. However, such features might not be supported or make sense for certain backends (e.g. lists and thus, list comprehensions, are difficult to support in VHDL). Thus, in this tutorial we will create systems which are compatible with every backend. For example, writing addOnef = (+1) instead of addOnef n = n +1 is more compact, however the VHDL backend does not currently support sections nor points-free notation.

In order to use ForSyDe it is not vital to understand what is really happening, but, for those curious about it, here is how the TH trick works. First, the [d| .. |] brackets enclosing the function declaration lift its AST (Abstract Syntax Tree). Then, the AST is used by newProcFun to splice (expand in TH's terminology) a ProcFun. It is important to note that everything happens at compile-time.

Here is the rest of the system definition.

-- System function (simply a process in this case) which uses addOnef
plus1Proc :: Signal Int32 -> Signal Int32
plus1Proc = mapSY "plus1Proc" addOnef


-- System definition associated to the system function
plus1SysDef :: SysDef (Signal Int32 -> Signal Int32)
plus1SysDef = newSysDef plus1Proc "plus1" ["inSignal"] ["outSignal"]
	

First, we use mapSY to create process. Then we create the final definition of the plus1 system with newSysDef. Here is its type signature.

newSysDef :: (SysFun f) => f -> SysId -> [PortId] -> [PortId] -> SysDef f
	

Now we can simulate our system, or, as we will see later on, translate it to VHDL or GraphML.

simulate :: SysFunToSimFun sysFun simFun => SysDef sysFun -> simFun
	

simulate transforms our system definition into a list-based function with the help of a multiparameter typeclass, SysFunToSimFun, in charge of implementing the type-level translation of the system signals to lists.

$ ghci Plus1.hs
*Plus1> let simPlus1 = simulate plus1SysDef 
*Plus1> :t simPlus1
simPlus1 :: [Int32] -> [Int32]
*Plus1> simPlus1 [1..10]
[2,3,4,5,6,7,8,9,10,11]
	

Simulation is lazy, allowing to work with infinite signals.

*Plus1> take 10 $ simPlus1 [1,1..] 
[2,2,2,2,2,2,2,2,2,2]
	

It is important to remark that ForSyDe does not support systems containing combinational loops. If such a loop is found, an error will be reported.

For example, here is a system containing a combinational loop, built with a mutually recursive call between two processes adding one to their inputs.

combLoopSysDef :: SysDef (Signal Int32)
combLoopSysDef = newSysDef s "combLoop" [] ["out"] 
 where s  = mapSY "addOne1" addOnef s'
       s' = mapSY "addOne2" addOnef s
	

As we mentioned, combLoopSysDef cannot be simulated.

*Plus1> simulate combLoopSysDef 
*** Exception: detected combinational loop
	

Here is a slightly more complex example. We have a keypad with 4 arrow buttons connected to our synchronous system. The key-presses are sent in the form of a 4-bit vector. Each bit indicates whether the corresponding button is pressed (high value) or not (low value) according to the diagram below.

In order to work more comfortably and forget about multiple key-strokes at once, we want to encode each key-press event with a specific Haskell type: data Direction = Left | Down | Right | Up.

Of course, keys are not necessarily pressed all the time. Thus, instead of encoding the input vector into a signal of Direction we will output signals of AbstExt Direction.

data AbstExt a = Abst | Prst a
	  

AbstExt (read absent-extended) is ForSyDe's equivalent to the popular Haskell type Maybe. It is used to introduce absent values in signals, in our particular case it will denote an absence of key presses.

{-# LANGUAGE TemplateHaskell, DeriveDataTypeable #-}
module Encoder where

import ForSyDe
import Language.Haskell.TH.Lift (deriveLift1)

import Prelude hiding (Left, Right)
import Data.Generics (Data,Typeable)
import Data.Param.FSVec
import Data.TypeLevel.Num hiding ((==))


data Direction = Left | Down | Right | Up
 deriving (Typeable, Data, Show)

$(deriveLift1 ''Direction)
	

There are a few things worth remarking

Here is the code of the process function, needed to encode the button presses:

encoderFun :: ProcFun (FSVec D4 Bit -> AbstExt Direction)
encoderFun = $(newProcFun 
  [d| encode :: FSVec D4 Bit -> AbstExt Direction
      encode v = if v ! d0 == H then Prst Left  else
                 if v ! d1 == H then Prst Down  else
                 if v ! d2 == H then Prst Right else
                 if v ! d3 == H then Prst Up else Abst  |])
	

The code should be self-explanatory, it makes use of the type ForSyDe.Bit.Bit, with data constructors L (low) and H (high), and of vectors of size 4 (hence the D4 type parameter). In order to get a deeper insight on how FSVecs work, check Appendix A, FSVecs: Vectors parameterized in size. It is important to note that the system does not take simultaneous key-strokes in account, choosing the direction with higher precedence (i.e. situated in the outermost if expression). Also, using pattern matching with multiple function clauses instead of nested if expressions would had been more clear. However, the VHDL backend currently only supports one clause.

Here is the remaining code needed to build the rest of the system.

encoderProc :: Signal (FSVec D4 Bit) -> Signal (AbstExt Direction)
encoderProc = mapSY "encoder" encoderFun

encoderSysDef :: SysDef (Signal (FSVec D4 Bit) -> Signal (AbstExt Direction))
encoderSysDef = newSysDef encoderProc "KeypadEncoder" ["arrowBits"] ["direction"]	  
	

Finally, we can evaluate some simulations.

$ ghci -XTemplateHaskell Encoder.hs
*Encoder> let simEncoder = simulate encoderSysDef 
*Encoder> :t simEncoder
simEncoder :: [FSVec D4 Bit] -> [AbstExt Direction]
*Encoder> simEncoder [$(vectorTH [L,H,L,L]), $(vectorTH [L,L,L,L])]
[Down,_]
	

Our goal is to generate a signal whose values match its tags or, more intuitively, a counter from 1 to infinity.

This is clearly a sequential system since its output signal is not stateless, each output value depends on the previous one.

{-# LANGUAGE TemplateHaskell #-}
module Counter where

import ForSyDe
import Data.Int (Int32)
import Plus1 (addOnef)

counterProc :: Signal Int32
counterProc = out'
  where out  = mapSY "addOneProc" addOnef out'
        out' = delaySY "delayOne" 1 out

counterSysDef :: SysDef (Signal Int32)
counterSysDef = newSysDef counterProc "counter" [] ["count"]
	  

We reuse addOnef from previous examples. The counter is built by the mutually recursive calls of mapSY and delaySY which should be interpreted as parallel equations.

Again, we can lazily simulate the system.

$ ghci Counter.hs
*Counter> :t simulate counterSysDef 
simulate counterSysDef :: [Int32]
*Plus1> simulate counterSysDef
[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17
^C Interrupted
	  

Actually, the definition of counterProc can be simplified by using sourceSY, getting the following equivalent declaration.

counterProc :: Signal Int32
counterProc = sourceSY "counterProc" addOnef 1
	  

A serial full adder which adds two streams of bits is a, still simple, but more elaborated example of a sequential system. Our system will receive pairs of bits which will be added together, taking the resulting carry of last cycle in account.

We are going to implement it as a Mealy FSM (Finite State Machine) following the diagram below.

ForSyDe provides derived process constructors to implement FSMs, in this case we will be using mealySY.

mealySY :: (ProcType c, ProcType b, ProcType a) =>
           ProcId
        -> ProcFun (a -> b -> a)
        -> ProcFun (a -> b -> c)
        -> a
        -> Signal b
        -> Signal c
	

Here is the Haskell code, which should be straightforward to understand.

{-# LANGUAGE TemplateHaskell #-}
module FullAdder where

import ForSyDe

faNextState :: ProcFun (Bit -> (Bit,Bit) -> Bit)
faNextState = $(newProcFun
  [d| faNextState :: Bit -> (Bit,Bit) -> Bit
      faNextState st input =
         if st == L then
            case input of
              (H, H) -> H
              _ -> L
         else
            case input of
              (L,L) -> L
              _ -> H
     |])

faOut :: ProcFun (Bit -> (Bit,Bit) -> Bit)
faOut= $(newProcFun
  [d| faOut :: Bit -> (Bit,Bit) -> Bit
      faOut st input =
         if st == L then
            case input of
              (L, L) -> L
              (L, H) -> H
              (H, L) -> H
              (H, H) -> L
         else
            case input of
              (L, L) -> H
              (L, H) -> L
              (H, L) -> L
              (H, H) -> H
     |])


faProc :: Signal (Bit,Bit) -> Signal Bit
faProc = mealySY "addProc" faNextState faOut L

faSysDef :: SysDef (Signal (Bit,Bit) -> Signal Bit)
faSysDef = newSysDef faProc "fullAdder" ["op1", "op2"] ["res"]	  
	

*FullAdder> let simfa = simulate faSysDef 
*FullAdder> simfa [(L,L),(L,H),(H,H),(L,L)]
[L,H,L,H]
*FullAdder> 	
	

The GraphML definition does not provide a way to specify the graphical representation of graphs (e.g. edge and node shapes, colours, textual tags ...)

For that reason, yWorks, a company offering graph visualization products, created yFiles-GraphML, an extension to the GraphML schema which adds graphical information.

yWorks also distributes yEd, a free (as in beer) multiplatform graph editor with impressive automatic layout features.

Here is an example on how to generate and edit yFiles-GraphML diagrams from ForSyDe systems. For this purpose, we will use our counter system.

$ ghci Counter.hs
*Counter> writeGraphMLOps defaultGraphMLOps{yFilesMarkup=True} counterSysDef 
*Counter> :q
$ ls -R counter
graphml

counter/graphml:
counter.graphml              sourceSY_counterProc.graphml
	

sourceSY_counterProc.graphml contains the sourceSY process used in the counter. Let's view its representation with yEd.

This is the unorganized representation we get right after opening sourceSY_counterProc.graphml with yEd.

All nodes are overlapped because the GraphML-yFiles backend does not perform any kind of node placement nor edge routing. yEd, however, does a very good job in this regard.

Before running a layout algorithm it is convenient to set port constraints on the graph nodes. This is a workaround to make yEd faithfully represent shared signals (signals coming from the same process output), otherwise yEd will treat them as different outputs. The GraphML format (and GraphML-yFiles) allows edge sharing through the use of ports, however, yEd does not currently respect them. Our current solution is to set a location for the edge ends in the GraphML backend and lock that location through yEd port constraints.

In order to set the port constraints we will go to Tools -> Constraints -> Port Constraints.

The port constraints menu will initially look like this.

Figure 14. Port constraints default options

These are the options we need to set in order to fix all ports. Remember to click on OK after setting them.

Figure 15. Desired port constraint options

It is important to note that due to a bug in yFiles format it is not possible to save port constraints in .graphml files. Thus, we will need to reset the port constraints every time a file is reopened.

Now we are ready to run an automatic layout algorithm. The generated GraphML-yFiles graph is prepared to be displayed from left to right. The hierarchical layout (Layout -> Hierarchical -> Classic) seems to give the best results for system diagrams. It is important to set the Orientation to Left to Right and allow Backloop Routing.

Figure 16. hierarchical layout

Unfortunately, GraphML nor yFiles-GraphML + yEd suit all ForSyDe needs: