random documentation and cleanup

src/Convert.hs

@@ -28,7 +28,6 @@ import qualified Convert.Struct
 import qualified Convert.Typedef
 import qualified Convert.UnbasedUnsized
 import qualified Convert.Unique
-import qualified Convert.HoistPortDecls
 
 type Phase = AST -> AST
 
@@ -41,7 +40,6 @@ phases excludes =
     , selectExclude (Job.Logic    , Convert.Logic.convert)
     , Convert.FuncRet.convert
     , Convert.Enum.convert
-    , Convert.HoistPortDecls.convert
     , Convert.KWArgs.convert
     , Convert.PackedArray.convert
     , Convert.StarPort.convert

src/Convert/AlwaysKW.hs

@@ -2,6 +2,9 @@
  - Author: Zachary Snow <zach@zachjs.com>
  -
  - Conversion for `always_comb` and `always_ff`
+ -
+ - `always_comb` -> `always @*`
+ - `always_ff` -> `always`
  -}
 
 module Convert.AlwaysKW (convert) where
@@ -12,10 +15,6 @@ import Language.SystemVerilog.AST
 convert :: AST -> AST
 convert = traverseDescriptions $ traverseModuleItems replaceAlwaysKW
 
--- Conversions:
--- `always_comb` -> `always @*`
--- `always_ff` -> `always`
-
 replaceAlwaysKW :: ModuleItem -> ModuleItem
 replaceAlwaysKW (AlwaysC AlwaysComb stmt) =
     AlwaysC Always $ Timing (Event SenseStar) stmt

src/Convert/AsgnOp.hs

 {- sv2v
  - Author: Zachary Snow <zach@zachjs.com>
  -
- - Conversion for binary assignment operators, which appear in standard and
- - generate for loops and as a special case of blocking assignment statements.
- - We simply elaborate them in the obvious manner.
+ - Conversion for binary assignment operators, which can appear in for loops and
+ - as a special case of blocking assignment statements. We simply elaborate them
+ - in the obvious manner: a += b -> a = a + b.
  -}
 
 module Convert.AsgnOp (convert) where

src/Convert/Assertion.hs

 {- sv2v
  - Author: Zachary Snow <zach@zachjs.com>
  -
- - Conversion which simply removes assertions
+ - Conversion for removing assertions. Assertions items are "commented out."
  -}
 
 module Convert.Assertion (convert) where
@@ -13,8 +13,11 @@ convert :: AST -> AST
 convert = traverseDescriptions $ traverseModuleItems convertModuleItem
 
 convertModuleItem :: ModuleItem -> ModuleItem
-convertModuleItem (AssertionItem _) =
-    MIPackageItem $ Comment "removed an assertion item"
+convertModuleItem (AssertionItem item) =
+    Generate $
+    map (GenModuleItem . MIPackageItem . Comment) $
+        "removed an assertion item" :
+        (lines $ show $ AssertionItem item)
 convertModuleItem other = traverseStmts convertStmt other
 
 convertStmt :: Stmt -> Stmt

src/Convert/Bits.hs

 {- sv2v
  - Author: Zachary Snow <zach@zachjs.com>
  -
- - Elaboration of `$bits`, where possible
+ - Elaboration of `$bits` expressions.
+ -
+ - Some tools support $bits in Verilog, but it is not part of the specification,
+ - so we have to convert it ourselves.
+ -
+ - `$bits(t)`, where `t` is a type, is trivially elaborated to the product of
+ - the sizes of its dimensions once `t` is resolved to a primitive base type.
+ -
+ - `$bits(e)`, where `e` is an expression, requires a scoped traversal to
+ - determine the underlying type of expression. The conversion recursively
+ - breaks the expression into its subtypes, finding their sizes instead.
  -}
 
 module Convert.Bits (convert) where
@@ -21,7 +31,6 @@ convertDescription :: Description -> Description
 convertDescription =
     scopedConversion traverseDeclM traverseModuleItemM traverseStmtM Map.empty
 
--- collects and converts multi-dimensional packed-array declarations
 traverseDeclM :: Decl -> State Info Decl
 traverseDeclM (origDecl @ (Variable _ t ident a _)) = do
     modify $ Map.insert ident (t, a)
@@ -37,6 +46,7 @@ traverseStmtM stmt = traverseStmtExprsM traverseExprM stmt
 traverseExprM :: Expr -> State Info Expr
 traverseExprM = traverseNestedExprsM $ stately convertExpr
 
+-- simplify a bits expression given scoped type information
 convertExpr :: Info -> Expr -> Expr
 convertExpr _ (Bits (Left t)) =
     case t of
@@ -74,6 +84,8 @@ convertExpr info (Bits (Right e)) =
         _ -> Bits $ Right e
 convertExpr _ other = other
 
+-- combines the given type and dimensions and returns a new type with the
+-- innermost range removed
 popRange :: Type -> [Range] -> Type
 popRange t rs =
     tf $ tail rsCombined

src/Convert/FuncRet.hs

@@ -2,6 +2,9 @@
  - Author: Zachary Snow <zach@zachjs.com>
  -
  - Conversion which makes function `logic` and `reg` return types implicit
+ -
+ - Verilog-2005 restricts function return types to `integer`, `real`,
+ - `realtime`, `time`, and implicit signed/dimensioned types.
  -}
 
 module Convert.FuncRet (convert) where

src/Convert/HoistPortDecls.hs

-{- sv2v
- - Author: Zachary Snow <zach@zachjs.com>
- -
- - VCS doesn't like port declarations inside of `generate` blocks, so we hoist
- - them out with this conversion. This obviously isn't ideal, but it's
- - relatively straightforward, and testing in VCS is important.
- -}
-
-module Convert.HoistPortDecls (convert) where
-
-import Data.List (partition)
-
-import Convert.Traverse
-import Language.SystemVerilog.AST
-
-convert :: AST -> AST
-convert = traverseDescriptions hoistPortDecls
-
-hoistPortDecls :: Description -> Description
-hoistPortDecls (Part extern kw lifetime name ports items) =
-    Part extern kw lifetime name ports (concat $ map explode items)
-    where
-        explode :: ModuleItem -> [ModuleItem]
-        explode (Generate genItems) =
-            if null rest
-                then portDecls
-                else portDecls ++ [Generate rest]
-            where
-                (wrappedPortDecls, rest) = partition isPortDecl genItems
-                portDecls = map (\(GenModuleItem item) -> item) wrappedPortDecls
-                isPortDecl :: GenItem -> Bool
-                isPortDecl (GenModuleItem (MIDecl (Variable dir _ _ _ _))) =
-                    dir /= Local
-                isPortDecl _ = False
-        explode other = [other]
-hoistPortDecls other = other

src/Convert/KWArgs.hs

@@ -2,6 +2,9 @@
  - Author: Zachary Snow <zach@zachjs.com>
  -
  - Conversion for named function and task arguments
+ -
+ - This conversion takes the named arguments and moves them into their
+ - corresponding position in the argument list, with names removed.
  -}
 
 module Convert.KWArgs (convert) where

src/Convert/NamedBlock.hs

@@ -2,6 +2,10 @@
  - Author: Zachary Snow <zach@zachjs.com>
  -
  - Conversion for unnamed blocks with contain data declarations
+ -
+ - SystemVerilog allows data declarations to appear in all blocks, but Verilog
+ - only allows them to appear in blocks that are named. This conversion gives
+ - such blocks a unique name to placate strict Verilog frontends.
  -}
 
 module Convert.NamedBlock (convert) where

src/Convert/Typedef.hs

@@ -3,8 +3,8 @@
  -
  - Conversion for `typedef`
  -
- - Aliased types can (probably) appear in all item declarations, including
- - modules, blocks, and function parameters.
+ - Aliased types can appear in all data declarations, including modules, blocks,
+ - and function parameters. They are also found in type cast expressions.
  -}
 
 module Convert.Typedef (convert) where
@@ -61,8 +61,8 @@ resolveType _ (Implicit         sg rs) = Implicit         sg rs
 resolveType _ (IntegerVector kw sg rs) = IntegerVector kw sg rs
 resolveType _ (IntegerAtom   kw sg   ) = IntegerAtom   kw sg
 resolveType _ (NonInteger    kw      ) = NonInteger    kw
-resolveType _ (InterfaceT x my rs) = InterfaceT x my rs
-resolveType _ (Enum Nothing vals rs) = Enum Nothing vals rs
+resolveType _ (InterfaceT     x my rs) = InterfaceT     x my rs
+resolveType _ (Enum Nothing   vals rs) = Enum Nothing   vals rs
 resolveType types (Enum (Just t) vals rs) = Enum (Just $ resolveType types t) vals rs
 resolveType types (Struct p items rs) = Struct p items' rs
     where

src/Convert/UnbasedUnsized.hs

@@ -5,7 +5,7 @@
  -
  - Maintaining the unsized-ness of the literals is critical, but those digits
  - are all equivalent regardless of base. We simply convert them to all use a
- - binary base for compatability with Verilog-2005.
+ - binary base for compatibility with Verilog-2005.
  -}
 
 module Convert.UnbasedUnsized (convert) where

src/Language/SystemVerilog/AST/Stmt.hs

@@ -192,7 +192,7 @@ instance Show Assertion where
     show (Cover  e a) = printf  "cover %s%s" (showAssertionExpr e) (show a)
 
 showAssertionExpr :: AssertionExpr -> String
-showAssertionExpr (Left e) = printf "property (%s)" (show e)
+showAssertionExpr (Left e) = printf "property (%s\n)" (show e)
 showAssertionExpr (Right e) = printf "(%s)" (show e)
 
 data PropertySpec
@@ -200,14 +200,14 @@ data PropertySpec
     deriving Eq
 instance Show PropertySpec where
     show (PropertySpec ms me pe) =
-        printf "%s%s%s" msStr meStr (show pe)
+        printf "%s%s\n\t%s" msStr meStr (show pe)
         where
             msStr = case ms of
                 Nothing -> ""
                 Just s -> printf "@(%s) " (show s)
             meStr = case me of
                 Nothing -> ""
-                Just e -> printf "disable iff (%s) " (show e)
+                Just e -> printf "disable iff (%s)" (show e)
 
 data UniquePriority
     = Unique

sv2v.cabal

@@ -59,7 +59,6 @@ executable sv2v
     Convert.Bits
     Convert.Enum
     Convert.FuncRet
-    Convert.HoistPortDecls
     Convert.Interface
     Convert.KWArgs
     Convert.Logic