-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A DSL for embedded hard realtime applications.
--   
--   Atom is a Haskell DSL for designing hard realtime embedded programs.
--   Based on conditional term rewriting, atom will compile a collection of
--   atomic state transition rules to a C program with constant memory use
--   and deterministic execution time.
@package atom
@version 0.0.2

module Language.Atom.Expressions

-- | A typed expression.
data E a
VRef :: V a -> E a
Const :: a -> E a
Cast :: E a -> E b
Add :: E a -> E a -> E a
Sub :: E a -> E a -> E a
Mul :: E a -> E a -> E a
Div :: E a -> E a -> E a
Mod :: E a -> E a -> E a
Not :: E Bool -> E Bool
And :: E Bool -> E Bool -> E Bool
BWNot :: E a -> E a
BWAnd :: E a -> E a -> E a
BWOr :: E a -> E a -> E a
Shift :: E a -> Int -> E a
Eq :: E a -> E a -> E Bool
Lt :: E a -> E a -> E Bool
Mux :: E Bool -> E a -> E a -> E a
F2B :: E Float -> E Word32
D2B :: E Double -> E Word64
B2F :: E Word32 -> E Float
B2D :: E Word64 -> E Double

-- | Variables updated by state transition rules.
data V a
V :: UV -> V a

-- | An untyped term.
data UE
UVRef :: UV -> UE
UConst :: Const -> UE
UCast :: Type -> UE -> UE
UAdd :: UE -> UE -> UE
USub :: UE -> UE -> UE
UMul :: UE -> UE -> UE
UDiv :: UE -> UE -> UE
UMod :: UE -> UE -> UE
UNot :: UE -> UE
UAnd :: [UE] -> UE
UBWNot :: UE -> UE
UBWAnd :: UE -> UE -> UE
UBWOr :: UE -> UE -> UE
UShift :: UE -> Int -> UE
UEq :: UE -> UE -> UE
ULt :: UE -> UE -> UE
UMux :: UE -> UE -> UE -> UE
UF2B :: UE -> UE
UD2B :: UE -> UE
UB2F :: UE -> UE
UB2D :: UE -> UE

-- | Unsigned variables.
data UV
UV :: Int -> String -> UVLocality -> UV

-- | UV locality.
data UVLocality
Local :: Const -> UVLocality
External :: Type -> UVLocality
class (Eq a) => Expr a
eType :: (Expr a) => E a -> Type
constant :: (Expr a) => a -> Const
expression :: (Expr a) => E a -> Expression
variable :: (Expr a) => V a -> Variable
rawBits :: (Expr a) => E a -> E Word64
data Expression
EBool :: (E Bool) -> Expression
EInt8 :: (E Int8) -> Expression
EInt16 :: (E Int16) -> Expression
EInt32 :: (E Int32) -> Expression
EInt64 :: (E Int64) -> Expression
EWord8 :: (E Word8) -> Expression
EWord16 :: (E Word16) -> Expression
EWord32 :: (E Word32) -> Expression
EWord64 :: (E Word64) -> Expression
EFloat :: (E Float) -> Expression
EDouble :: (E Double) -> Expression
data Variable
VBool :: (V Bool) -> Variable
VInt8 :: (V Int8) -> Variable
VInt16 :: (V Int16) -> Variable
VInt32 :: (V Int32) -> Variable
VInt64 :: (V Int64) -> Variable
VWord8 :: (V Word8) -> Variable
VWord16 :: (V Word16) -> Variable
VWord32 :: (V Word32) -> Variable
VWord64 :: (V Word64) -> Variable
VFloat :: (V Float) -> Variable
VDouble :: (V Double) -> Variable

-- | The type of a <a>E</a>.
data Type
Bool :: Type
Int8 :: Type
Int16 :: Type
Int32 :: Type
Int64 :: Type
Word8 :: Type
Word16 :: Type
Word32 :: Type
Word64 :: Type
Float :: Type
Double :: Type
data Const
CBool :: Bool -> Const
CInt8 :: Int8 -> Const
CInt16 :: Int16 -> Const
CInt32 :: Int32 -> Const
CInt64 :: Int64 -> Const
CWord8 :: Word8 -> Const
CWord16 :: Word16 -> Const
CWord32 :: Word32 -> Const
CWord64 :: Word64 -> Const
CFloat :: Float -> Const
CDouble :: Double -> Const
class Width a
width :: (Width a) => a -> Int
constType :: Const -> Type
ue :: (Expr a) => E a -> UE
uv :: V a -> UV

-- | The type of an UE.
ueType :: UE -> Type
uvType :: UV -> Type

-- | The list of UEs adjacent upstream of a UE.
ueUpstream :: UE -> [UE]

-- | A set of all variables referenced in a term.
uvSet :: UE -> [UV]
class (Num a, Expr a, EqE a, OrdE a) => NumE a
class (RealFloat a, NumE a, OrdE a) => FloatingE a
class (Eq a, Expr a) => EqE a
class (Eq a, Ord a, EqE a) => OrdE a

-- | True term.
true :: E Bool

-- | False term.
false :: E Bool

-- | Returns the value of a <a>V</a>.
value :: V a -> E a

-- | Logical negation.
not_ :: E Bool -> E Bool

-- | Logical AND.
(&&.) :: E Bool -> E Bool -> E Bool

-- | Logical OR.
(||.) :: E Bool -> E Bool -> E Bool

-- | The conjunction of a E Bool list.
and_ :: [E Bool] -> E Bool

-- | The disjunction of a E Bool list.
or_ :: [E Bool] -> E Bool

-- | True iff the predicate is true for any element.
any_ :: (a -> E Bool) -> [a] -> E Bool

-- | True iff the predicate is true for all elements.
all_ :: (a -> E Bool) -> [a] -> E Bool

-- | Equal.
(==.) :: (EqE a, OrdE a) => E a -> E a -> E Bool

-- | Not equal.
(/=.) :: (EqE a, OrdE a) => E a -> E a -> E Bool

-- | Less than.
(<.) :: (OrdE a) => E a -> E a -> E Bool

-- | Less than or equal.
(<=.) :: (OrdE a) => E a -> E a -> E Bool

-- | Greater than.
(>.) :: (OrdE a) => E a -> E a -> E Bool

-- | Greater than or equal.
(>=.) :: (OrdE a) => E a -> E a -> E Bool

-- | Returns the minimum of two numbers.
min_ :: (OrdE a) => E a -> E a -> E a

-- | Returns the minimum of a list of numbers.
minimum_ :: (OrdE a) => [E a] -> E a

-- | Returns the maximum of two numbers.
max_ :: (OrdE a) => E a -> E a -> E a

-- | Returns the maximum of a list of numbers.
maximum_ :: (OrdE a) => [E a] -> E a

-- | Limits between min and max.
limit :: (OrdE a) => E a -> E a -> E a -> E a

-- | Division.
div_ :: (IntegralE a) => E a -> E a -> E a

-- | Modulo.
mod_ :: (IntegralE a) => E a -> E a -> E a

-- | Conditional expression.
--   
--   <pre>
--   mux test onTrue ofFalse
--   </pre>
mux :: (Expr a) => E Bool -> E a -> E a -> E a
ubool :: Bool -> UE
unot :: UE -> UE
uand :: UE -> UE -> UE
uor :: UE -> UE -> UE
ueq :: UE -> UE -> UE
umux :: UE -> UE -> UE -> UE
instance Show UE
instance Eq UE
instance Ord UE
instance Show UVLocality
instance Show UV
instance Eq (V a)
instance Eq Variable
instance Eq Const
instance Ord Const
instance Show Type
instance Read Type
instance Eq Type
instance Ord Type
instance (Expr a, OrdE a, EqE a, IntegralE a, Bits a) => Bits (E a)
instance (OrdE a, NumE a, Num a, Fractional a) => Fractional (E a)
instance (Num a, NumE a, OrdE a) => Num (E a)
instance FloatingE Double
instance FloatingE Float
instance OrdE Double
instance OrdE Float
instance OrdE Word64
instance OrdE Word32
instance OrdE Word16
instance OrdE Word8
instance OrdE Int64
instance OrdE Int32
instance OrdE Int16
instance OrdE Int8
instance EqE Double
instance EqE Float
instance EqE Word64
instance EqE Word32
instance EqE Word16
instance EqE Word8
instance EqE Int64
instance EqE Int32
instance EqE Int16
instance EqE Int8
instance EqE Bool
instance IntegralE Word64
instance IntegralE Word32
instance IntegralE Word16
instance IntegralE Word8
instance IntegralE Int64
instance IntegralE Int32
instance IntegralE Int16
instance IntegralE Int8
instance NumE Double
instance NumE Float
instance NumE Word64
instance NumE Word32
instance NumE Word16
instance NumE Word8
instance NumE Int64
instance NumE Int32
instance NumE Int16
instance NumE Int8
instance Expr Double
instance Expr Float
instance Expr Word64
instance Expr Word32
instance Expr Word16
instance Expr Word8
instance Expr Int64
instance Expr Int32
instance Expr Int16
instance Expr Int8
instance Expr Bool
instance Width UE
instance (Expr a) => Width (V a)
instance (Expr a) => Width (E a)
instance Width Const
instance Width Type
instance (Expr a) => Eq (E a)
instance Show (E a)
instance Ord UV
instance Eq UV
instance Show Const

module Language.Atom.Elaboration

-- | The <a>Atom</a> container holds top level IO, <tt>Var</tt>, and
--   <a>Rule</a> definitions.
type Atom = StateT (Global, AtomDB) IO
data AtomDB
AtomDB :: Int -> Name -> [Name] -> UE -> [AtomDB] -> Int -> [(UV, UE)] -> [([String] -> String, [UE])] -> AtomDB
atomId :: AtomDB -> Int
atomName :: AtomDB -> Name
atomNames :: AtomDB -> [Name]
atomEnable :: AtomDB -> UE
atomSubs :: AtomDB -> [AtomDB]
atomPeriod :: AtomDB -> Int
atomAssigns :: AtomDB -> [(UV, UE)]
atomActions :: AtomDB -> [([String] -> String, [UE])]
data Global
Global :: Int -> [(String, Type, E Word64)] -> [UV] -> Int -> [(String, UE)] -> Global
gId :: Global -> Int
gProbes :: Global -> [(String, Type, E Word64)]
gUVs :: Global -> [UV]
gPeriod :: Global -> Int
gAsserts :: Global -> [(String, UE)]
data Rule
Rule :: Int -> Name -> UE -> [(UV, UE)] -> [([String] -> String, [UE])] -> Int -> Rule
ruleId :: Rule -> Int
ruleName :: Rule -> Name
ruleEnable :: Rule -> UE
ruleAssigns :: Rule -> [(UV, UE)]
ruleActions :: Rule -> [([String] -> String, [UE])]
rulePeriod :: Rule -> Int
buildAtom :: Global -> Name -> Atom a -> IO (a, (Global, AtomDB))
type UID = Int

-- | A name.
type Name = String

-- | A heirarchical name.
type Path = [Name]

-- | A Relation is used for relative performance constraints between
--   <tt>Action</tt>s. data Relation = Higher UID | Lower UID deriving
--   (Show, Eq)
--   
--   Given a top level name and design, elabortes design and returns a
--   design database.
elaborate :: Name -> Atom () -> IO (Maybe ([Rule], [UV], [(String, UE)]))

-- | Generic local variable declaration.
var :: Name -> Const -> Atom (V a)

-- | Generic external variable declaration.
var' :: Name -> Type -> Atom (V a)
addName :: Name -> Atom Name
instance Ord Rule
instance Eq Rule
instance Show Rule
instance Ord AtomDB
instance Eq AtomDB
instance Show AtomDB

module Language.Atom.Verify
verify :: Int -> [[[Rule]]] -> [UV] -> (String, UE) -> IO Bool
instance Show Group


-- | Atom code generation.
module Language.Atom.Code
writeC :: Name -> [[[Rule]]] -> [UV] -> IO ()

-- | Number of UE's computed in rule.
ruleComplexity :: Rule -> Int


-- | Atom rule scheduling.
module Language.Atom.Scheduling
schedule :: Name -> [Rule] -> IO (Maybe [[[Rule]]])


-- | The Atom language.
module Language.Atom.Language

-- | A Atom captures declarations including inputs, outputs, variables, and
--   assertions and actions including guard conditions and variable
--   assignments.
type Atom = Atom

-- | Creates a hierarical node, where each node could be a atomic rule.
atom :: Name -> Atom a -> Atom a

-- | Defines the period of execution of sub rules as a factor of the base
--   rate of the system. Rule period is bound by the closest period
--   assertion. For example:
--   
--   <pre>
--   period 10 $ period 2 a   -- Rules in 'a' have a period of 2, not 10.
--   </pre>
period :: Int -> Atom a -> Atom a

-- | Returns the execution period of the current scope.
getPeriod :: Atom Int

-- | Adds an enabling condition to an atom subtree of rules. This condition
--   must be true before any rules in heirarchy are allowed to execute.
cond :: E Bool -> Atom ()
class (Expr a) => Assign a
(<==) :: (Assign a) => V a -> E a -> Atom ()

-- | Increments a NumE <a>V</a>.
incr :: (Assign a, NumE a) => V a -> Atom ()

-- | Decrements a NumE <a>V</a>.
decr :: (Assign a, NumE a) => V a -> Atom ()

-- | Generic local variable declaration.
var :: Name -> Const -> Atom (V a)

-- | Generic external variable declaration.
var' :: Name -> Type -> Atom (V a)

-- | Local boolean variable declaration.
bool :: Name -> Bool -> Atom (V Bool)

-- | External boolean variable declaration.
bool' :: Name -> Atom (V Bool)

-- | Local int8 variable declaration.
int8 :: Name -> Int8 -> Atom (V Int8)

-- | External int8 variable declaration.
int8' :: Name -> Atom (V Int8)

-- | Local int16 variable declaration.
int16 :: Name -> Int16 -> Atom (V Int16)

-- | External int16 variable declaration.
int16' :: Name -> Atom (V Int16)

-- | Local int32 variable declaration.
int32 :: Name -> Int32 -> Atom (V Int32)

-- | External int32 variable declaration.
int32' :: Name -> Atom (V Int32)

-- | Local int64 variable declaration.
int64 :: Name -> Int64 -> Atom (V Int64)

-- | External int64 variable declaration.
int64' :: Name -> Atom (V Int64)

-- | Local word8 variable declaration.
word8 :: Name -> Word8 -> Atom (V Word8)

-- | External word8 variable declaration.
word8' :: Name -> Atom (V Word8)

-- | Local word16 variable declaration.
word16 :: Name -> Word16 -> Atom (V Word16)

-- | External word16 variable declaration.
word16' :: Name -> Atom (V Word16)

-- | Local word32 variable declaration.
word32 :: Name -> Word32 -> Atom (V Word32)

-- | External word32 variable declaration.
word32' :: Name -> Atom (V Word32)

-- | Local word64 variable declaration.
word64 :: Name -> Word64 -> Atom (V Word64)

-- | External word64 variable declaration.
word64' :: Name -> Atom (V Word64)

-- | Local float variable declaration.
float :: Name -> Float -> Atom (V Float)

-- | External float variable declaration.
float' :: Name -> Atom (V Float)

-- | Local double variable declaration.
double :: Name -> Double -> Atom (V Double)

-- | External double variable declaration.
double' :: Name -> Atom (V Double)

-- | Declares an action.
action :: ([String] -> String) -> [UE] -> Atom ()

-- | Asserts expression must always be true.
assert :: Name -> E Bool -> Atom ()

-- | Declares a probe.
probe :: (Expr a) => Name -> E a -> Atom ()

-- | Fetches all declared probes to current design point.
probes :: Atom [(String, Type, E Word64)]

-- | A name.
type Name = String
liftIO :: (MonadIO m) => forall a. IO a -> m a

-- | Returns the current atom heirarchical path.
path :: Atom String

-- | Reference to the 64-bit free running clock.
clock :: E Word64

-- | Rule coverage information. (current coverage index, coverage data)
nextCoverage :: Atom (E Word32, E Word32)
instance Assign Double
instance Assign Float
instance Assign Word64
instance Assign Word32
instance Assign Word16
instance Assign Word8
instance Assign Int64
instance Assign Int32
instance Assign Int16
instance Assign Int8
instance Assign Bool


-- | Common Atom functions.
module Language.Atom.Common

-- | A Timer.
data Timer

-- | Creates a new timer.
timer :: Name -> Atom Timer

-- | Starts a Timer. A Timer can be restarted at any time.
startTimer :: Timer -> E Word64 -> Atom ()

-- | True when a timer has completed.
timerDone :: Timer -> E Bool

-- | One-shot on a rising transition.
oneShotRise :: E Bool -> Atom (E Bool)

-- | One-shot on a falling transition.
oneShotFall :: E Bool -> Atom (E Bool)

-- | Debounces a boolean given an on and off time (ticks) and an initial
--   state.
debounce :: Name -> E Word64 -> E Word64 -> Bool -> E Bool -> Atom (E Bool)

-- | 1-D lookup table. X values out of table range are clipped at end Y
--   values. Input table must be monitonically increasing in X.
lookupTable :: (FloatingE a) => [(E a, E a)] -> E a -> E a

-- | Hysteresis returns true when then input exceeds max and false when the
--   input is less than min. The state is held when the input is between
--   min and max.
--   
--   <pre>
--   hysteresis name min max input
--   </pre>
hysteresis :: (OrdE a) => E a -> E a -> E a -> Atom (E Bool)


-- | Atom compilation.
module Language.Atom.Compile

-- | Compiles an atom description to C.
compile :: Name -> Atom () -> IO ()


-- | Atom is a Haskell DSL for designing hard realtime embedded programs.
--   Based on conditional term rewriting, atom will compile a collection of
--   atomic state transition rules to a C program with constant memory use
--   and deterministic execution time.
module Language.Atom


-- | An example atom design.
module Language.Atom.Example

-- | Invoke the atom compiler.
compileExample :: IO ()

-- | Example design introduces a unsigned 16-bit variable, and declares two
--   rules: one to increment the variable, one to reset the variable back
--   to zero when it hits 100.
example :: Atom ()