copilot-bluespec: Flip direction of interface inputs and outputs in Bluespec. Refs #677.

The current Bluespec backend leads to Verilog code that requires manual
manipulations in order to work correctly. Specifically, Copilot externs, which
are inputs to the Copilot monitoring system, are treated as _outputs_ in
Verilog, and Copilot triggers, which can be considered outputs of the
monitoring system, are treated as _inputs_. This is the opposite of the
interface that we would like users to work with, and of what other backends
generate (e.g., C99).

This commit updates the internals of `copilot-bluespec` to flip the order in
which generated Bluespec module interfaces declare their inputs and outputs. A
module interface now represents each Copilot extern as a method of type `<ty>
-> Action` (where `<ty>` is the type of the extern), as this directly
translates to a Verilog input. Moreover, a module interface now represents
trigger arguments as interface methods of type `<ty>_i`, where each `<ty>_i` is
the type of each trigger argument. Each `<ty>_i` directly translates to a
Verilog output.

In addition to changing the module interface definitions, this also changes the
generated modules that instantiate the new interfaces. One of the more notable
changes is that all extern values are stored as a Bluespec `Wire` in the module
internals, as this leads to compact Verilog code without adding any
user-visible inputs or outputs. Every time a value is read from an extern, the
corresponding `Wire` must be read from, which means that several parts of the
module internals have been updated to reference these `Wire`s.

Author: RyanGlScott

copilot-bluespec/src/Copilot/Compile/Bluespec/CodeGen.hs

@@ -14,12 +14,17 @@ module Copilot.Compile.Bluespec.CodeGen
     -- * Stream generators
   , mkGenFun
 
+    -- * External streams
+  , mkExtWireDecln
+
     -- * Monitor processing
-  , mkStepRule
+  , mkExtRule
   , mkTriggerRule
+  , mkStepRule
 
     -- * Module interface specifications
   , mkSpecIfcFields
+  , mkSpecIfcRulesFields
   ) where
 
 -- External imports
@@ -50,6 +55,16 @@ mkGenFun name expr ty =
     nameId = BS.mkId BS.NoPos $ fromString $ lowercaseName name
     def = BS.CClause [] [] (transExpr expr)
 
+-- | Bind a @Wire@ variable using @mkBypassWire@.
+mkExtWireDecln :: String -> Type a -> BS.CStmt
+mkExtWireDecln name ty =
+  BS.CSBindT
+    (BS.CPVar (BS.mkId BS.NoPos (fromString (wireName name))))
+    Nothing
+    []
+    (BS.CQType [] (tWire `BS.TAp` transType ty))
+    (BS.CVar (BS.mkId BS.NoPos "mkBypassWire"))
+
 -- | Bind a buffer variable and initialise it with the stream buffer.
 mkBuffDecln :: forall a. Id -> Type a -> [a] -> [BS.CStmt]
 mkBuffDecln sId ty xs =
@@ -133,44 +148,112 @@ mkAccessDecln sId ty xs =
 
 -- | Define fields for a module interface containing a specification's trigger
 -- functions and external variables.
-mkSpecIfcFields :: [Trigger] -> [External] -> [BS.CField]
-mkSpecIfcFields triggers exts =
+mkSpecIfcFields :: [UniqueTrigger] -> [External] -> [BS.CField]
+mkSpecIfcFields uniqueTriggers exts =
+    concatMap mkTriggerFields uniqueTriggers ++ map mkExtField exts
+  where
+    -- trigger_guard :: Bool
+    -- trigger_arg0 :: arg_ty_0
+    -- ...
+    -- trigger_arg(n-1) :: arg_ty_(n-1)
+    mkTriggerFields :: UniqueTrigger -> [BS.CField]
+    mkTriggerFields (UniqueTrigger uniqueName (Trigger _name _ args)) =
+      mkField (guardName uniqueName) [] BS.tBool
+        : zipWith
+            (\(UExpr arg _) argName -> mkField argName [] (transType arg))
+            args
+            (argNames uniqueName)
+
+    -- ext :: ty -> Action
+    mkExtField :: External -> BS.CField
+    mkExtField (External name ty) =
+      mkField
+        name
+        [ BS.PIPrefixStr ""
+        , BS.PIArgNames [BS.mkId BS.NoPos $ fromString $ lowercaseName name]
+        ]
+        (BS.tArrow `BS.TAp` transType ty `BS.TAp` BS.tAction)
+
+-- | Define fields for a module interface containing the actions to perform for
+-- a specification's trigger functions and external variables.
+mkSpecIfcRulesFields :: [Trigger] -> [External] -> [BS.CField]
+mkSpecIfcRulesFields triggers exts =
     map mkTriggerField triggers ++ map mkExtField exts
   where
-    -- trigger :: args_1 -> ... -> args_n -> Action
+    -- trigger_action :: arg_ty_0 -> ... -> arg_ty_(n-1) -> Action
     mkTriggerField :: Trigger -> BS.CField
     mkTriggerField (Trigger name _ args) =
-      mkField name $
-      foldr
-        (\(UExpr arg _) res -> BS.tArrow `BS.TAp` transType arg `BS.TAp` res)
-        BS.tAction
-        args
+      mkField
+        (actionName name)
+        []
+        (foldr
+          (\(UExpr arg _) res -> BS.tArrow `BS.TAp` transType arg `BS.TAp` res)
+          BS.tAction
+          args)
 
-    -- ext :: Reg ty
+    -- ext_action :: ActionValue ty
     mkExtField :: External -> BS.CField
     mkExtField (External name ty) =
-      mkField name $ tReg `BS.TAp` transType ty
+      mkField (actionName name) [] (BS.tActionValue `BS.TAp` transType ty)
+
+-- | Define a rule for an external stream that performs an action on the most
+-- recently computed value from the stream.
+mkExtRule :: External -> BS.CRule
+mkExtRule (External name _) =
+    -- rules
+    --   "ext": when True ==>
+    --     action
+    --       extVal <- ifcRules.ext_action
+    --       ifc.ext extVal
+    BS.CRule
+      []
+      (Just $ cLit $ BS.LString name)
+      [ BS.CQFilter $ BS.CCon BS.idTrue []
+      ]
+      (BS.Caction
+        BS.NoPos
+        [ BS.CSBind
+            (BS.CPVar extValId)
+            Nothing
+            []
+            (BS.CSelect (BS.CVar ifcRulesArgId) extActionId)
+        , BS.CSExpr Nothing $
+            BS.CApply (BS.CSelect (BS.CVar ifcArgId) extId) [BS.CVar extValId]
+        ])
+  where
+    ifcArgId = BS.mkId BS.NoPos $ fromString ifcArgName
+    ifcRulesArgId = BS.mkId BS.NoPos $ fromString ifcRulesArgName
+
+    extActionId = BS.mkId BS.NoPos $ fromString $ actionName name
+    extId = BS.mkId BS.NoPos $ fromString name
+    extValId = BS.mkId BS.NoPos $ fromString $ name ++ "Val"
 
--- | Define a rule for a trigger function.
+-- | Define a rule for a trigger function that performs an action when the rule
+-- fires.
 mkTriggerRule :: UniqueTrigger -> BS.CRule
 mkTriggerRule (UniqueTrigger uniqueName (Trigger name _ args)) =
+    -- rules
+    --   "trigger": when ifc.trigger_guard ==>
+    --     ifcRules.trigger_action ifc.trigger_arg0
     BS.CRule
       []
       (Just $ cLit $ BS.LString uniqueName)
       [ BS.CQFilter $
-        BS.CVar $ BS.mkId BS.NoPos $
-        fromString $ guardName uniqueName
+          BS.CSelect
+            (BS.CVar ifcArgId)
+            (BS.mkId BS.NoPos $ fromString $ guardName uniqueName)
       ]
-      (BS.CApply nameExpr args')
+      (BS.CApply actionNameExpr args')
   where
     ifcArgId = BS.mkId BS.NoPos $ fromString ifcArgName
+    ifcRulesArgId = BS.mkId BS.NoPos $ fromString ifcRulesArgName
     -- Note that we use 'name' here instead of 'uniqueName', as 'name' is the
     -- name of the actual external function.
-    nameId   = BS.mkId BS.NoPos $ fromString $ lowercaseName name
-    nameExpr = BS.CSelect (BS.CVar ifcArgId) nameId
+    actionNameId   = BS.mkId BS.NoPos $ fromString $ actionName name
+    actionNameExpr = BS.CSelect (BS.CVar ifcRulesArgId) actionNameId
 
-    args'   = take (length args) (map argCall (argNames uniqueName))
-    argCall = BS.CVar . BS.mkId BS.NoPos . fromString
+    args' = take (length args) (map argCall (argNames uniqueName))
+    argCall = BS.CSelect (BS.CVar ifcArgId) . BS.mkId BS.NoPos . fromString
 
 -- | Writes the @step@ rule that updates all streams.
 mkStepRule :: [Stream] -> Maybe BS.CRule
@@ -238,14 +321,15 @@ mkStructDecln x =
 
     mkStructField :: Value a -> BS.CField
     mkStructField (Value ty field) =
-      mkField (fieldName field) (transType ty)
+      mkField (fieldName field) [] (transType ty)
 
--- | Write a field of a struct or interface, along with its type.
-mkField :: String -> BS.CType -> BS.CField
-mkField name ty =
+-- | Write a field of a struct or interface, along with its pragmas and type
+-- signature.
+mkField :: String -> [BS.IfcPragma] -> BS.CType -> BS.CField
+mkField name pragmas ty =
   BS.CField
     { BS.cf_name = BS.mkId BS.NoPos $ fromString $ lowercaseName name
-    , BS.cf_pragmas = Nothing
+    , BS.cf_pragmas = Just pragmas
     , BS.cf_type = BS.CQType [] ty
     , BS.cf_default = []
     , BS.cf_orig_type = Nothing
@@ -260,3 +344,12 @@ tReg = BS.TCon $
     , BS.tcon_sort = BS.TIstruct (BS.SInterface [])
                                  [BS.id_write BS.NoPos, BS.id_read BS.NoPos]
     }
+
+-- | The @Wire@ Bluespec type.
+tWire :: BS.CType
+tWire = BS.TCon $
+  BS.TyCon
+    { BS.tcon_name = BS.mkId BS.NoPos "Wire"
+    , BS.tcon_kind = Just (BS.Kfun BS.KStar BS.KStar)
+    , BS.tcon_sort = BS.TItype 0 tReg
+    }

copilot-bluespec/src/Copilot/Compile/Bluespec/Expr.hs

@@ -51,11 +51,8 @@ transExpr (Drop _ amount sid) =
             [BS.CLit $ BS.CLiteral BS.NoPos index]
 
 transExpr (ExternVar _ name _) =
-  let ifcArgId = BS.mkId BS.NoPos $ fromString ifcArgName in
   BS.CSelect
-    (BS.CSelect
-      (BS.CVar ifcArgId)
-      (BS.mkId BS.NoPos $ fromString $ lowercaseName name))
+    (BS.CVar $ BS.mkId BS.NoPos $ fromString $ wireName name)
     (BS.id_read BS.NoPos)
 
 transExpr (Label _ _ e) = transExpr e -- ignore label

copilot-bluespec/src/Copilot/Compile/Bluespec/Name.hs

@@ -1,9 +1,11 @@
 -- | Naming of variables and functions in Bluespec.
 module Copilot.Compile.Bluespec.Name
-  ( argNames
+  ( actionName
+  , argNames
   , generatorName
   , guardName
   , ifcArgName
+  , ifcRulesArgName
   , indexName
   , lowercaseName
   , specIfcName
@@ -13,6 +15,7 @@ module Copilot.Compile.Bluespec.Name
   , streamElemName
   , streamName
   , uppercaseName
+  , wireName
   ) where
 
 -- External imports
@@ -41,11 +44,14 @@ specTypesPkgName prefix = prefix ++ "Types"
 streamElemName :: Id -> Int -> String
 streamElemName sId n = streamName sId ++ "_" ++ show n
 
--- | The name of the variable of type @<prefix>Ifc@. This is used to select
--- trigger functions and external variables.
+-- | The name of a variable of type @<prefix>Ifc@.
 ifcArgName :: String
 ifcArgName = "ifc"
 
+-- | The name of a variable of type @<prefix>RulesIfc@.
+ifcRulesArgName :: String
+ifcRulesArgName = "ifcRules"
+
 -- | Create a Bluespec name that must start with an uppercase letter (e.g., a
 -- struct or interface name). If the supplied name already begins with an
 -- uppercase letter, this function returns the name unchanged. Otherwise, this
@@ -86,6 +92,15 @@ generatorName sId = streamName sId ++ "_gen"
 guardName :: String -> String
 guardName name = lowercaseName name ++ "_guard"
 
+-- | Turn the name of a trigger of external stream into the name of a method
+-- that performs a Bluespec @Action@.
+actionName :: String -> String
+actionName name = lowercaseName name ++ "_action"
+
+-- | Turn the name of an external stream into a Bluespec @Wire@.
+wireName :: String -> String
+wireName name = lowercaseName name ++ "_wire"
+
 -- | Turn a trigger name into a an trigger argument name.
 argName :: String -> Int -> String
 argName name n = lowercaseName name ++ "_arg" ++ show n