copilot-1.0: A stream DSL for writing embedded C monitors.

Language.Copilot.Core

Description

Provides basic types and functions for other parts of Copilot.

If you wish to add a new type, you need to make it an instance of Streamable, to add it to foldStreamableMaps, mapStreamableMaps, and optionnaly to add an ext[Type], a [type] and a var[Type] functions in Language.hs to make it easier to use.

Synopsis

Documentation

type Period = Int

Atom period -- used as an option to control the duration of a Copilot tick.

type Var = String

Names of the streams or external variables

type Name = String

C file name

data Port

Port over which to broadcast information

Constructors

Port Int 

data Ext

Holds external variables or external functions to call.

Constructors

ExtV Var 
Fun String Args 

Instances

Eq Ext 
Show Ext 
ExtCl Ext

For functions.

type Exs = (Type, Ext, ExtRet)

data ExtRet

Constructors

ExtRetV 
ExtRetA String 

Instances

type Args = [ArgConstVar]

data ArgConstVar

Arguments to be passed to a C function. Either a Copilot variable or a constant. A little hacky that I store constants as strings so we don't have to pass around types. However, these data are just used to make external C calls, for which we have no type info anyway, so it's a bit of a moot point.

Constructors

V Var 
C String 

Instances

data Spec a where

Specification of a stream, parameterized by the type of the values of the stream. The only requirement on a is that it should be Streamable.

Constructors

Var :: Streamable a => Var -> Spec a 
Const :: Streamable a => a -> Spec a 
PVar :: Streamable a => Type -> Ext -> Spec a 
PArr :: (Streamable a, Streamable b, IntegralE b) => Type -> (Ext, Spec b) -> Spec a 
F :: (Streamable a, Streamable b) => (b -> a) -> (E b -> E a) -> Spec b -> Spec a 
F2 :: (Streamable a, Streamable b, Streamable c) => (b -> c -> a) -> (E b -> E c -> E a) -> Spec b -> Spec c -> Spec a 
F3 :: (Streamable a, Streamable b, Streamable c, Streamable d) => (b -> c -> d -> a) -> (E b -> E c -> E d -> E a) -> Spec b -> Spec c -> Spec d -> Spec a 
Append :: Streamable a => [a] -> Spec a -> Spec a 
Drop :: Streamable a => Int -> Spec a -> Spec a 

Instances

Eq a => Eq (Spec a) 
(Streamable a, NumE a, Fractional a) => Fractional (Spec a) 
(Streamable a, NumE a) => Num (Spec a) 
Show a => Show (Spec a) 
Monoid (StreamableMaps Spec) 
Streamable b => ArgCl (Spec b) 

type Streams = Writer LangElems ()

Container for mutually recursive streams, whose specifications may be parameterized by different types

type Stream a = Streamable a => (Var, Spec a)

A named stream

data Send a

An instruction to send data on a port at a given phase. data Send a = Sendable a => Send (Var, Phase, Port)

Constructors

Send 

Fields

sendVar :: Spec a
 
sendPort :: Port
 
sendName :: String
 

Instances

Streamable a => Show (Send a) 

data Trigger

Constructors

Trigger 

Fields

trigVar :: Spec Bool
 
trigName :: String
 
trigArgs :: Args
 

Instances

type Triggers = Map String Trigger

data LangElems

Holds all the different kinds of language elements that are pushed into the Writer monad. This currently includes the actual specs, send directives, and trigger directives. (Use the functions in Language.hs to make sends and triggers.)

Constructors

LangElems 

Fields

strms :: StreamableMaps Spec
 
snds :: StreamableMaps Send
 
trigs :: Triggers
 

Instances

class (Expr a, Assign a, Show a) => Streamable a where

Holds the complete specification of a distributed monitor type DistributedStreams = (Streams, Sends)

A type is streamable iff a stream may emit values of that type

There are very strong links between Streamable and StreamableMaps : the types aggregated in StreamableMaps are exactly the Streamable types and that invariant should be kept (see methods)

Methods

getSubMap :: StreamableMaps b -> Map Var (b a)

Provides access to the Map in a StreamableMaps which store values of the good type

updateSubMap :: (Map Var (b a) -> Map Var (b a)) -> StreamableMaps b -> StreamableMaps b

Provides a way to modify (mostly used for insertions) the Map in a StreamableMaps which store values of the good type

unit :: a

A default value for the type a. Its value is not important.

atomConstructor :: Var -> a -> Atom (V a)

A constructor to produce an Atom value

externalAtomConstructor :: Var -> V a

A constructor to get an Atom value from an external variable

typeId :: a -> String

The argument only coerces the type, it is discarded. Returns the format for outputting a value of this type with printf in C

For example %f for a float

typeIdPrec :: a -> String

The same, only adds the wanted precision for floating points.

atomType :: a -> Type

The argument only coerces the type, it is discarded. Returns the corresponding Atom type.

showAsC :: a -> String

Like Show, except that the formatting is exactly the same as the one of C for example the booleans are first converted to 0 or 1, and floats and doubles have the good precision.

Instances

data StreamableMaps a

This is a generalization of Streams which is used for storing Maps over values parameterized by different types.

It is extensively used in the internals of Copilot, in conjunction with foldStreamableMaps and mapStreamableMaps

Constructors

SM 

Fields

bMap :: Map Var (a Bool)
 
i8Map :: Map Var (a Int8)
 
i16Map :: Map Var (a Int16)
 
i32Map :: Map Var (a Int32)
 
i64Map :: Map Var (a Int64)
 
w8Map :: Map Var (a Word8)
 
w16Map :: Map Var (a Word16)
 
w32Map :: Map Var (a Word32)
 
w64Map :: Map Var (a Word64)
 
fMap :: Map Var (a Float)
 
dMap :: Map Var (a Double)
 

Instances

emptySM :: StreamableMaps a

An empty streamableMaps.

isEmptySM :: StreamableMaps a -> Bool

Verifies if its argument is equal to emptySM

getMaybeElem :: Streamable a => Var -> StreamableMaps b -> Maybe (b a)

Lookup into the map of the right type in StreamableMaps

getElem :: Streamable a => Var -> StreamableMaps b -> b a

Lookup into the map of the right type in StreamableMaps Launch an exception if the index is not in it

foldStreamableMaps :: forall b c. (Streamable a => Var -> c a -> b -> b) -> StreamableMaps c -> b -> b

This function is used to iterate on all the values in all the maps stored by a StreamableMaps, accumulating a value over time

mapStreamableMaps :: forall s s'. (forall a. Streamable a => Var -> s a -> s' a) -> StreamableMaps s -> StreamableMaps s'

mapStreamableMapsM :: forall s s' m. Monad m => (Streamable a => Var -> s a -> m (s' a)) -> StreamableMaps s -> m (StreamableMaps s')

filterStreamableMaps :: forall c b. StreamableMaps c -> [(Type, Var, b)] -> (StreamableMaps c, Bool)

Only keeps in sm the values whose key+type are in l. Also returns a bool saying whether all the elements in sm were in l. Works even if some elements in l are not in sm. Not optimised at all.

normalizeVar :: Var -> Var

Replace all accepted special characters by sequences of underscores.

getVars :: StreamableMaps s -> [Var]

Get the Copilot variables.

type Vars = StreamableMaps []

For each typed variable, this type holds all its successive values in an infinite list Beware : each element of one of those lists corresponds to a full Atom period, not to a single clock tick.

getAtomType :: Streamable a => Spec a -> Type

getSpecs :: Streams -> StreamableMaps Spec

getSends :: Streams -> StreamableMaps Send

getTriggers :: Streams -> Triggers

vPre :: Name -> String

Copilot variable reference, taking the name of the generated C file.

funcShow :: Name -> String -> Args -> String

For calling a function with Atom variables.

getMaybeVar :: Streamable a => Spec a -> Var

Get a variable name from a spec; throw an error otherwise.

notConstVarErr :: Streamable a => Spec a -> (ArgConstVar -> b) -> b

If the Spec isn't a Var or Const, then throw an error; otherwise, apply the function.